[finding] `sys_member` "Add Member" action targets `POST /organization/add-member`, which better-auth 1.7.0-rc.2 never mounts (server-only) — on multi-org there is NO remaining UI path to attach an existing user to an org

[baozhoutao]

Symptom

The sys_member list-toolbar action Add Member (add_member) always fails with HTTP 404. Its target route POST /api/v1/auth/organization/add-member is never mounted.

Route-mount probe against a deployed 17.0.0 stack (no credentials — contrast with a sibling route that IS mounted):

POST /api/v1/auth/organization/add-member -> 404 (route not mounted)
POST /api/v1/auth/organization/remove-member -> 400 (mounted; body validation fired)

Root cause

better-auth 1.7.0-rc.2 declares addMember without an HTTP path — it is a server-only endpoint (auth.api.addMember), while every sibling member route keeps its path (better-auth/dist/plugins/organization/routes/crud-members.mjs):

const addMember = (option) => { ... return createAuthEndpoint({ method: "POST", ... }) // no path → server-only
const removeMember = (options) => createAuthEndpoint("/organization/remove-member", { ... }) // mounted
const updateMemberRole = (option) => createAuthEndpoint("/organization/update-member-role", { ... })

So POST /organization/add-member does not exist over HTTP, yet three places in the platform still claim it does (all current on main @ d7c42405):

1. packages/platform-objects/src/identity/sys-member.object.ts:54 — the add_member action: target: '/api/v1/auth/organization/add-member';
2. packages/plugins/plugin-auth/src/adopt-membership.ts:72 — doc contract: "POST /organization/add-member pre-checks and refuses first (… a 400)";
3. by omission: packages/plugins/plugin-auth/src/auth-route-ledger.ts correctly does NOT list organization/add-member (only add-team-member) — the ledger and the action metadata contradict each other. The ledger even has a 'server-only' disposition arm that nothing uses for this endpoint.

Why this is a hard blocker (not a cosmetic 404)

On a multi-org posture there is no path left, in any UI, to attach an existing user to an organization:

• POST /api/v1/auth/admin/create-user → bindUserToSoleOrganization → reconcileMembership resolves the target org via tenancy.defaultOrgId(), which returns null when the posture enforces the org wall (by design — the framework must not guess an org). Outcome no-target-org, no sys_member row.
• The freshly created user signs in with zero memberships and is greeted by the "create a workspace" bootstrap prompt (they then either mint a stray org or cancel into a dead-end shell).
• The one advertised remediation — sys_member.object.ts's own comment: "The add_member toolbar action covers the admin 'attach an existing user directly without sending an invitation' flow" — 404s as above.
• Generic CRUD on sys_member is suppressed (managedBy: "better-auth", ADR-0010 full lock), so an admin cannot hand-create the row either.
• The invite flow requires an email round-trip, which phone-number-only users (created via the phoneNumber plugin path of create-user) cannot complete.

Expected

Either plugin-auth exposes an admin-guarded HTTP route that wraps auth.api.addMember (and the route ledger lists it), or the add_member action metadata is retargeted to whatever route is the sanctioned "attach existing user" entry — plus the stale adopt-membership.ts claim updated. As shipped, action metadata, route ledger, and better-auth reality are three different stories.

Versions

• @objectstack/* 17.0.0 (GA); reproduced on main @ d7c424055 (2026-08-19) by inspection — same better-auth pin (1.7.0-rc.2), same action target, same ledger omission.
• better-auth 1.7.0-rc.2.

What we did NOT do

No app-side workaround: no patched action metadata, no direct sys_member writes shipped. The app-side issue is parked as blocked on this one.

Part of steedos-labs/os-project-titanwind-ehr#1615

[os-warren]

Triage: lands in packages/plugins/plugin-auth (route + auth-route-ledger.ts) with an action-metadata touch in packages/platform-objects/src/identity/sys-member.object.ts → domain:services; type Bug (declared action targets a route the vendor never mounts; on multi-org there is no remaining UI path to attach an existing user — production field report). Queued.

Preferred shape, from the card's own Expected: an admin-guarded HTTP route wrapping auth.api.addMember, listed in the route ledger (which already carries an unused 'server-only' disposition arm), gated the same ADR-0068 capability way #9652's PR gates ban/unban — this restores the declared surface rather than widening it. Retargeting the action is the fallback if a sanctioned attach route already exists. Serial constraint for the claimer: #9652 is in flight in the same lane and the same plugin-auth route files — name it in the claim's serial-constraints line and sequence behind its PR (or prove disjoint file surface). Size/model suggestion: M, opus.

---

Generated by Claude Code

[os-warren]

Claim: PM seat domain:services (#6021), round 6.

• Session: session_01PnJHU45vPJj5UQrxe946Bx (os-warren)
• Branch: claude/issue-9941-add-member-http-route
• Worktree: objectstack-issue-9941 (from origin/main)
• File surface: packages/plugins/plugin-auth/src/ (new route + auth-route-ledger.ts + adopt-membership.ts doc claim) and packages/platform-objects/src/identity/sys-member.object.ts if the action metadata needs a touch
• Container & model: subagent os-dev, claude-fable-5
• Clause-②: yes — contract-review tier, read live from scripts/pm/dispatch-gates.mjs (CONTRACT_REVIEW_TIER = 'claude-fable-5'). This card mounts an HTTP route that does not exist today, i.e. it changes what the API accepts. That is Clause-② on content regardless of what --tier derives from paths.
• Serial: plugin-auth/** is treated as ONE hot surface by this lane, and it is free as of now — Every better-auth-native /admin/ route refuses ObjectStack platform admins — the vendor gates on the legacy user.role === 'admin' scalar ADR-0068 D2 stopped synthesizing #9652/PR fix(plugin-auth): serve /admin/ban-user and /admin/unban-user with the ADR-0068 platform-admin gate #9970, finding: the four /admin/sso/* bridges carry no ObjectStack-side admin gate, and their delegated authorization is unprovable on a stock boot #9653/PR fix(plugin-auth): gate the four /admin/sso/* bridges with the shared ADR-0068 platform-admin judge (#9653) #10013 and [finding] managed-extension-fields.test.ts seeds its source scan from import.meta, costing plugin-auth's TEST_DEBT its only TS1470 — the package already has an idiom that avoids it #9694/PR fix(plugin-auth): seed managed-extension-fields' source scan from __dirname, retiring the package's only TS1470 (TEST_DEBT 110 -> 109) #10028 have all merged (09b880b0c). Triage's serial warning ("Every better-auth-native /admin/ route refuses ObjectStack platform admins — the vendor gates on the legacy user.role === 'admin' scalar ADR-0068 D2 stopped synthesizing #9652 in flight in the same route files") is discharged. ⚠️ [finding] rate-limit-storage-isolation.test.ts reads two other packages through a findUp seed, so check:cross-package-test-inputs cannot see the radius and turbo does not hash it #10029 and [finding] sys_session has no retention policy — nothing sweeps it, here or in better-auth, and #7732 makes revoked rows permanent #7826 are the next cards on this same surface and stay queued behind this one.

Premise re-verified on origin/main@09b880b0c — all three sites the card names are intact:

1. sys-member.object.ts:54 — target: '/api/v1/auth/organization/add-member' (with the "attach an existing user directly without sending an invitation" comment at :39).
2. adopt-membership.ts:72 — the stale contract sentence "POST /organization/add-member pre-checks and refuses first".
3. auth-route-ledger.ts — lists POST /api/v1/auth/organization/add-team-member (:182, :333) and not organization/add-member; the unused 'server-only' disposition arm is at :60. Zero-hit counter-check applied: the ledger holds 55 organization/ rows, so the absence is a real absence, not a broken search.
4. The shared judge exists: packages/plugins/plugin-auth/src/platform-admin-gate.ts (landed by Every better-auth-native /admin/ route refuses ObjectStack platform admins — the vendor gates on the legacy user.role === 'admin' scalar ADR-0068 D2 stopped synthesizing #9652/PR fix(plugin-auth): serve /admin/ban-user and /admin/unban-user with the ADR-0068 platform-admin gate #9970).

Route choice — taking triage's preferred shape, and why it is not a widening. The platform already declares this surface: the sys_member toolbar action ships pointing at it, and the object's own comment advertises it as the admin remediation. Today that declaration is a lie the vendor never mounted. Mounting an admin-guarded wrapper restores the declared surface; retargeting the action would be the fallback only if a sanctioned attach route already existed, and the card's evidence is that none does.

⛔ Hard boundaries carried into the dispatch (this is a privileged route, so the tolerances are tight):

• The gate MUST be the shared platform-admin-gate.ts judge — ⛔ no fifth predicate copy, same shape finding: the four /admin/sso/* bridges carry no ObjectStack-side admin gate, and their delegated authorization is unprovable on a stock boot #9653/PR fix(plugin-auth): gate the four /admin/sso/* bridges with the shared ADR-0068 platform-admin judge (#9653) #10013 hoisted for the /admin/sso/* bridges.
• The admit set is platform admin only. If the dev finds itself wanting to admit org owners/admins, that is a security-boundary loosening ⇒ maintainer floor: stop and report, do not ship it. (Live context: finding: the direct /sso/register endpoint's ADR-0024 before-hook admits org owners/admins — wider than the platform-admin posture #9653 landed on the /admin/sso/* bridges #10009 is open precisely because a sibling admit set is wider than the ADR-0068 posture.)
• Refusals per ADR-0112: assert code AND status, never one alone. Anonymous-first ordering — identity error before capability error before body validation.
• The route MUST be registered in auth-route-ledger.ts, and the 'server-only' disposition arm at :60 is the right vocabulary for what the vendor endpoint is — use it rather than inventing a new one, or say why it does not fit.
• ⛔ No direct sys_member writes as a shortcut — the object is managedBy: "better-auth" under an ADR-0010 full lock. Go through auth.api.addMember.

Pins required on a real multi-org fixture: anon 401, member 403, org owner/admin 403, platform admin admitted; plus the card's actual blocker — an existing user with zero memberships gets a sys_member row and no longer lands on the "create a workspace" bootstrap. Every negative pin needs the standing ablation treatment (predicted signature first, output captured, byte-identical restore proven with git hash-object, explicit rebuild statement).

⚠️ Metadata-string consumer sweep (this seat's new clause, learned from #9807 the hard way this round): if the action metadata in sys-member.object.ts changes, its string ships into dist/ and the generated en bundle, and consumer pins in examples/app-showcase can hold it. Sweep the consumers; the package suite and the named gate families do not see them.

Downstream: the field report steedos-labs/os-project-titanwind-ehr#1615 is parked on this card.

---

Generated by Claude Code

[os-warren]

{
 "issue": 9941,
 "status": "done",
 "branch": "claude/issue-9941-add-member-http-route",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/10049",
 "premise_still_valid": true,
 "summary": "Mounted POST /api/v1/auth/organization/add-member in auth-plugin.ts ahead of the catch-all, wrapping better-auth's server-only auth.api.addMember behind the shared ADR-0068 platform-admin gate (gateAdmin/judgePlatformAdmin — no new predicate copy; admit set platform-admin only, org owners/admins refused 403), with the vendor's own verdicts forwarded verbatim and the write attributed to the admin. Ledgered as source 'objectstack', disposition 'server-only' (the previously-unused arm — it fits: no SDK method builds this URL, the sys_member action posts it directly); BETTER_AUTH_MOUNTED_SURFACE deliberately untouched since the pathless vendor endpoint never enters the live enumeration. Fixed the stale adopt-membership.ts:72 claim; sys-member.object.ts untouched (its target was correct all along, so no metadata string moved and the #9807 consumer surface is unmoved by construction). NOTE: installed better-auth is 1.7.1, not the card's 1.7.0-rc.2 — re-measured on the installed dist (crud-members.mjs:20-25 addMember pathless; :139/:236 siblings keep paths; organization.mjs:326 'Server-only' doc): the premise holds unchanged. Blocker for steedos-labs/os-project-titanwind-ehr#1615 is cleared at the platform layer: pinned end to end that an existing zero-membership user on a two-org fixture gets a real sys_member row via the mounted route (written by the vendor through the objectql adapter, no direct sys_member writes) and their own session then sees the org, i.e. no more 'create a workspace' bootstrap.",
 "tests": "organization-add-member.test.ts: 11/11 green — real AuthManager + dispatch-asserted memory engine, TWO orgs (real multi-org), real better-auth sessions, real ADR-0068 admin signal (admin_full_access + org-less sys_user_permission_set; no role scalar patched). Pins: anon 401 UNAUTHENTICATED with invalid body (identity before body validation, nothing written); member 403 PERMISSION_DENIED; org OWNER 403 PERMISSION_DENIED; platform admin 200 with sys_member row landed and organization/list non-empty; repeat 400 USER_IS_ALREADY_A_MEMBER_OF_THIS_ORGANIZATION; 400 USER_NOT_FOUND; 400 NO_ACTIVE_ORGANIZATION; 400 INVALID_REQUEST x2; 501 NOT_IMPLEMENTED before body validation; body/headers forwarding. All rejections assert code AND status. Ablation (gate neutered in the mount, predictions stated first): predicted anon 401→400, member 403→200 + unauthorized write, owner 403→400 already-a-member, downstream row-count poisoning — observed exactly that (5 failed/6 passed, 'expected 401, received 400', 'expected 403, received 200', 'expected 403, received 400', 'length 1 but got 2' x2); NO rebuild required for observability (same-package relative source import under vitest; marker verified absent from dist on both legs); restored byte-identically, git hash-object 56c783b059d81e058c540079db786c204bc8351f before and after, restored leg 11/11. Union at final commit 918435096: pnpm --filter @objectstack/plugin-auth test = 58 files/1312 tests passed (includes ledger conformance); typecheck tsc --noEmit exit 0; dispatch-gates re-derived (no hand-fed paths, re-run after last commit — it added check:cross-package-test-inputs via the double-contract ledger artifact, run green: 'OK: 12 package(s) read outside themselves, all declared'); check:route-envelope '1 conformant, 0 ratcheted'; check:engine-double-contract 'OK — 323 pinned' (new double registered via the gate's own --write); check:type-check-debt 'none above its recorded number' (a first-cut untyped vi.fn() had moved plugin-auth TEST_DEBT 109→110; typed the mock, back to exactly 109); check:type-check-coverage, slot-lookup, test-source-alias, type-source-resolution, query-options-erasure, where-matcher, nul-bytes, changeset-gate-self-tests, objectui-changeset, adr-0087, changeset-no-major, empty-changeset, affected-docs all exit 0 with their own verdict lines captured (exit codes taken before any pipe). CI on PR #10049 not awaited per the standing report-at-draft rule.",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code