fix(plugin-auth)!: POST /admin/create-user reads the deployment membership policy instead of hard-coding auto (#16683) (#17443)

* fix(plugin-auth)!: admin/create-user reads the deployment membership policy

`POST /api/v1/auth/admin/create-user` handed the membership reconciler a
literal `policy: 'auto'`, making it the one membership-writing path that did
not consult `AuthManager.getMembershipPolicy()`. On an `invite-only`
deployment the `user.create.after` reconciler correctly bound nobody and this
endpoint-side belt-and-suspenders bind then bound them anyway, answering
`membershipCreated: true`. The failure direction was OPEN: it granted the
membership the policy exists to withhold.

ADR-0093 D1 enumerates the `invite-only` flows as a closed set and refuses
"which endpoint created the user" as a determinant, so the endpoint now reads
the live accessor through a new optional `AdminUserEndpointDeps.getMembershipPolicy`
dep, wired at the mount in auth-plugin.ts. Absent dep falls back to `'auto'`,
the accessor's own default, so unwired hosts are byte-identical.

The accessor's docblock enumerated "both membership paths" while a third
writer sat outside the accounting; it now names all three.

Tests: invite-only binds nothing (single-org and multi-org), the org lookup is
never reached so `policy-skip` stays distinguishable from `no-target-org`, and
a negative control pins the `auto` path byte-identical across an explicit
`'auto'`, an unwired dep and a dep returning `undefined`.

Co-authored-by: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ToDPcx9AESFubJkDiFMtKW

* fix(plugin-auth): the new admin-endpoint assertions add no test-type debt

`check:test-typecheck` ledgers this file's TS2493 / TS18048 counts and only
ratchets DOWN. The invite-only and negative-control assertions read
`engineInsert.mock.calls` directly, and `vi.fn(async () => ({}))` infers a
ZERO-length parameter tuple, so every `c[0]` was a fresh TS2493 and the
`![1]` audit-row read a fresh TS18048 — six new errors across three ledgered
signatures.

Read those calls through a typed `callsOf()` helper instead. No type is
loosened, no ledger number is raised, no test is skipped: the recorded
counts return to exactly what the ledger already holds.

Co-authored-by: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ToDPcx9AESFubJkDiFMtKW

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-sales

.changeset/admin-create-user-reads-membership-policy.md

@@ -0,0 +1,21 @@
+---
+"@objectstack/plugin-auth": minor
+---
+
+fix(plugin-auth)!: `POST /admin/create-user` reads the deployment's membership policy instead of hard-coding `auto` (#16683)
+
+**BREAKING** — the membership this published endpoint writes moves for existing inputs on `invite-only` deployments. The route, its request body, its response fields and every exported signature are byte-identical; what changes is what an existing call does on a deployment that declared a non-default policy, stated as a FROM/TO pair below.
+
+ADR-0093 D1 makes the deployment's `membershipPolicy` the one answer to "does this new account get an organization membership", and enumerates the `invite-only` flows as a closed set — "which endpoint created the user" is explicitly not a determinant. The `user.create.after` reconciler and the D6 backfill both read it through `AuthManager.getMembershipPolicy()`. This endpoint did not: its belt-and-suspenders bind handed the reconciler a literal `'auto'`, so it was the one membership-writing path in the product that ignored the setting.
+
+FROM: on a deployment declaring `membershipPolicy: 'invite-only'`, an account created through `POST /api/v1/auth/admin/create-user` was bound to the default organization anyway, and the 200 response answered `membershipCreated: true`. The `user.create.after` reconciler had already declined to bind it; this endpoint bound it afterwards.
+
+TO: the same call creates the account and binds no membership. The response answers `membershipCreated: false` and omits `organizationId`, and the audit row records the same. The account is created and can sign in — `invite-only` withholds the membership, not the login.
+
+Who is affected: only deployments that set `auth.membership_policy` (or `OS_AUTH_MEMBERSHIP_POLICY`) to `invite-only`. Under the default `auto` posture behaviour is unchanged in every observable respect — response body, `sys_member` write and audit metadata — and that equivalence is pinned by a test rather than asserted here.
+
+If you relied on admin-created accounts acquiring a membership on an `invite-only` deployment, the supported way to keep it is to bind the membership explicitly (the `add_member` action / `POST /organization/add-member`), which is what `invite-only` means: memberships are granted deliberately, never as a side effect of account creation. Setting the deployment back to `auto` restores the old behaviour for every path at once, including sign-up.
+
+The direction of the old defect was open, not closed: it GRANTED a membership the operator had configured the platform to withhold, and reported success while doing it. An operator who set `invite-only` specifically to keep a shared organization identity off their users got one anyway.
+
+<!-- adr-0087: not-required (no-migration-prescription) nothing authorable changes shape: no spec key, no Zod schema, no stored metadata and no exported symbol is added, removed or renamed, so `os migrate meta` has no edit to make and no ledger id to carry. What moves is one runtime decision inside an HTTP handler, already governed by the `auth.membership_policy` setting an operator sets and can change back. -->

packages/plugins/plugin-auth/src/admin-user-endpoints.test.ts

@@ -52,6 +52,18 @@ function makeDeps(overrides: Partial<Record<string, any>> = {}) {
   return { deps, createUser, engineUpdate, engineCreate, authCtx, warn, noteMustChangePasswordIssued };
 }
 
+/**
+ * Read a mock's recorded calls at their real arity.
+ *
+ * `vi.fn(async () => ({}))` infers a ZERO-length parameter tuple, so `c[0]` on
+ * `mock.calls` is a type error (`TS2493`) even though every recorded call has
+ * two arguments — the shape `scripts/check-test-typecheck.mts` ledgers for this
+ * file. New assertions go through here so the ledger keeps ratcheting DOWN.
+ */
+function callsOf(fn: { mock: { calls: unknown[][] } }): Array<[string, any]> {
+  return fn.mock.calls as unknown as Array<[string, any]>;
+}
+
 /**
  * Security red line (#2766): no mock the endpoint touched may ever have seen
  * the plaintext password outside the better-auth hashing surface.
@@ -460,6 +472,130 @@ describe('runAdminCreateUser', () => {
     expect(data.membershipCreated).toBe(true);
   });
 
+  // ── ADR-0093 D1: the deployment membership policy governs THIS path too ──
+  //
+  // The endpoint used to hand the reconciler a literal `policy: 'auto'`, so an
+  // `invite-only` deployment — where the `user.create.after` reconciler and the
+  // D6 backfill both correctly bound nobody — got the membership bound anyway
+  // by this belt-and-suspenders call, and a `membershipCreated: true` that read
+  // as success. The failure direction was OPEN: it GRANTED what the policy is
+  // set to withhold. Nothing pinned either direction before these tests, which
+  // is why the literal survived.
+
+  it("invite-only: creates the account and binds NO membership (ADR-0093 D1)", async () => {
+    const m = makeDepsWithOrgs({ orgs: [{ id: 'org_only' }] });
+    m.deps.getMembershipPolicy = () => 'invite-only';
+    const res = await runAdminCreateUser(
+      m.deps,
+      makeRequest({ email: 'a@b.co', generatePassword: true }),
+      ACTOR,
+    );
+
+    // The ACCOUNT is still created — `invite-only` withholds the membership,
+    // not the login. That distinction is the whole ruling.
+    expect(res.status).toBe(200);
+    expect(m.createUser).toHaveBeenCalledTimes(1);
+
+    const data = res.body.data as any;
+    expect(data.user.id).toBe('user-9');
+    expect(data.membershipCreated).toBe(false);
+    expect(data.organizationId).toBeUndefined();
+    expect(callsOf(m.engineInsert).some((c) => c[0] === 'sys_member')).toBe(false);
+
+    // `policy-skip` is decided BEFORE any target-org resolution, so the org
+    // lookup never runs. This separates "policy said no" from "no target org
+    // was found" — two outcomes that would both show membershipCreated:false.
+    expect(m.find.mock.calls.some((c) => c[0] === 'sys_organization')).toBe(false);
+
+    // The audit row records the refusal, so the trail shows the account was
+    // created member-less on purpose rather than by a failed bind.
+    const auditRow = callsOf(m.engineInsert).find((c) => c[0] === 'sys_audit_log')?.[1];
+    expect(auditRow).toBeTruthy();
+    const meta = JSON.parse(auditRow.metadata);
+    expect(meta.membershipCreated).toBe(false);
+    expect(meta.organizationId).toBeUndefined();
+  });
+
+  it('invite-only in multi-org mode: also binds nothing (both reasons hold)', async () => {
+    const m = makeDepsWithOrgs({
+      orgs: [{ id: 'org_default', slug: 'default' }, { id: 'org_tenant_b' }],
+    });
+    m.deps.getTenancy = () => ({ defaultOrgId: async () => null });
+    m.deps.getMembershipPolicy = () => 'invite-only';
+    const res = await runAdminCreateUser(
+      m.deps,
+      makeRequest({ email: 'a@b.co', generatePassword: true }),
+      ACTOR,
+    );
+    expect(res.status).toBe(200);
+    const data = res.body.data as any;
+    expect(data.membershipCreated).toBe(false);
+    expect(data.organizationId).toBeUndefined();
+    expect(callsOf(m.engineInsert).some((c) => c[0] === 'sys_member')).toBe(false);
+  });
+
+  it('auto (explicit): still binds — the default posture is untouched', async () => {
+    const m = makeDepsWithOrgs({ orgs: [{ id: 'org_only' }] });
+    m.deps.getMembershipPolicy = () => 'auto';
+    const res = await runAdminCreateUser(
+      m.deps,
+      makeRequest({ email: 'a@b.co', generatePassword: true }),
+      ACTOR,
+    );
+    expect(res.status).toBe(200);
+    const data = res.body.data as any;
+    expect(data.organizationId).toBe('org_only');
+    expect(data.membershipCreated).toBe(true);
+    expect(callsOf(m.engineInsert).some((c) => c[0] === 'sys_member')).toBe(true);
+  });
+
+  /**
+   * NEGATIVE CONTROL (the ruling requires it, and it is not decorative).
+   *
+   * Under `auto` the behaviour must be BYTE-IDENTICAL to the pre-change
+   * literal. A green `invite-only` assertion alone would also be green if the
+   * endpoint had been changed to "never bind": that mistake passes the pin
+   * above and silently breaks every default deployment. So compare the whole
+   * observable surface — response body and every engine write — across the
+   * three ways `auto` can be reached: an explicit `'auto'`, no policy dep at
+   * all (unwired host: the accessor's own `?? 'auto'` default), and a dep that
+   * is present but returns `undefined`.
+   *
+   * `sys_member.id` is a fresh random id per run, so it is normalized out;
+   * everything else, including the audit metadata JSON, is compared verbatim.
+   * The password is passed explicitly so no random temporary one is minted.
+   */
+  async function autoPathSurface(
+    policyDep: undefined | (() => any),
+  ): Promise<{ body: string; writes: string }> {
+    const m = makeDepsWithOrgs({ orgs: [{ id: 'org_only' }] });
+    if (policyDep) m.deps.getMembershipPolicy = policyDep as any;
+    const res = await runAdminCreateUser(
+      m.deps,
+      makeRequest({ email: 'a@b.co', password: 'Sup3rSecret!x' }),
+      ACTOR,
+    );
+    const writes = callsOf(m.engineInsert).map(([object, doc]) => [
+      object,
+      object === 'sys_member' ? { ...doc, id: '(generated)' } : doc,
+    ]);
+    return { body: JSON.stringify(res.body), writes: JSON.stringify(writes) };
+  }
+
+  it('auto: byte-identical across explicit / unwired / undefined policy deps', async () => {
+    const explicitAuto = await autoPathSurface(() => 'auto');
+    const unwired = await autoPathSurface(undefined);
+    const returnsUndefined = await autoPathSurface(() => undefined);
+
+    expect(unwired).toEqual(explicitAuto);
+    expect(returnsUndefined).toEqual(explicitAuto);
+
+    // And the shared surface is the BINDING one — a suite that agreed on
+    // "nothing happened" three times would satisfy the equalities above.
+    expect(explicitAuto.body).toContain('"membershipCreated":true');
+    expect(explicitAuto.writes).toContain('sys_member');
+  });
+
   it('no-ops the bind (no throw) when the engine has no find surface', async () => {
     // Default makeDeps engine exposes only update/insert — the bind must be a
     // clean no-op, leaving exactly the audit insert.

packages/plugins/plugin-auth/src/admin-user-endpoints.ts

@@ -104,6 +104,27 @@ export interface AdminUserEndpointDeps {
    * is registered.
    */
   getTenancy?(): { defaultOrgId(): Promise<string | null> } | undefined;
+  /**
+   * ADR-0093 D1 — the deployment's membership policy, read LIVE through
+   * `AuthManager.getMembershipPolicy()` (never a captured option).
+   *
+   * This endpoint used to hand the reconciler a literal `'auto'`, which made
+   * it the one membership-writing path that did not consult the policy: an
+   * `invite-only` deployment's `user.create.after` reconciler correctly bound
+   * nobody, and then this endpoint-side belt-and-suspenders call bound them
+   * anyway. The failure direction was OPEN — it GRANTED the membership the
+   * policy exists to withhold, and answered `membershipCreated: true` while
+   * doing it. ADR-0093 D1 enumerates the `invite-only` flows as a closed set
+   * and refuses "which endpoint created the user" as a determinant, so the
+   * endpoint reads the policy like every other consumer.
+   *
+   * Optional, and absent ⇒ `'auto'`: that is the accessor's OWN default
+   * (`this.config.membershipPolicy ?? 'auto'`), so a host that wires no
+   * policy dep — lean embeddings, the package's own mock-deps tests — keeps
+   * byte-identical behaviour. The real mount in `auth-plugin.ts` always
+   * wires it.
+   */
+  getMembershipPolicy?(): MembershipPolicy;
   logger?: { warn(msg: string): void };
 }
 
@@ -153,7 +174,7 @@ export interface EndpointResult {
 
 import { CREDENTIAL_ISSUER } from './backfill-account-issuer.js';
 import { generatePlaceholderEmail } from './placeholder-email.js';
-import { reconcileMembership } from './reconcile-membership.js';
+import { reconcileMembership, type MembershipPolicy } from './reconcile-membership.js';
 import { resolveDefaultOrgId } from './tenancy-service.js';
 
 const SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] };
@@ -299,7 +320,8 @@ async function stampMustChangePassword(
 }
 
 /**
- * Bind an admin-created user to the organization (single-org membership).
+ * Bind an admin-created user to the organization (single-org membership),
+ * SUBJECT TO the deployment's membership policy.
  *
  * ADR-0093 D2 — this now delegates to the shared membership reconciler, the
  * single owner of the "every new user gets a membership" invariant. The
@@ -311,10 +333,22 @@ async function stampMustChangePassword(
  * org is the single-org default (resolveDefaultOrgId); multi-org resolves to
  * none, so this no-ops there just as before.
  *
+ * ADR-0093 D1 — the policy comes from {@link AdminUserEndpointDeps.getMembershipPolicy},
+ * the same live accessor the sign-up and backfill seams read. It used to be a
+ * literal `'auto'`, which made double-coverage anything but harmless under
+ * `invite-only`: the hook skipped by policy and this call bound regardless, so
+ * the endpoint GRANTED the membership the policy was set to withhold. D1
+ * enumerates the `invite-only` flows as a closed set and refuses "which
+ * endpoint created the user" as a determinant — an admin-created account is
+ * not an implicit invitation.
+ *
  * Returns the shape the response/audit consumed pre-ADR-0093:
  * `membershipCreated` is true only when THIS call inserted the row (a `bound`
  * outcome); a `yielded` outcome (the hook or a race already bound it) reports
- * the org with `membershipCreated: false`.
+ * the org with `membershipCreated: false`. Under `invite-only` the reconciler
+ * answers `policy-skip` before it looks at any org, so the caller reports no
+ * organization and `membershipCreated: false` — the account is created, the
+ * membership is not.
  */
 async function bindUserToSoleOrganization(
   deps: AdminUserEndpointDeps,
@@ -327,8 +361,11 @@ async function bindUserToSoleOrganization(
   // in a multi-org deployment. Fallback (no tenancy wired: lean embeddings,
   // legacy mocks) keeps the single-org resolution.
   const tenancy = deps.getTenancy?.();
+  // ADR-0093 D1 — read the live policy, never a literal. Absent dep ⇒ `auto`,
+  // which is the accessor's own default, so unwired hosts are unchanged.
+  const policy: MembershipPolicy = deps.getMembershipPolicy?.() ?? 'auto';
   const result = await reconcileMembership(engine, userId, {
-    policy: 'auto',
+    policy,
     resolveTargetOrg: () => (tenancy ? tenancy.defaultOrgId() : resolveDefaultOrgId(engine)),
     logger: deps.logger
       ? { warn: (msg, meta) => deps.logger?.warn(`${msg} ${meta ? JSON.stringify(meta) : ''}`.trim()) }
@@ -535,7 +572,8 @@ export async function runAdminCreateUser(
 
   // Match the invite / add-member flows: give the new user a membership so a
   // single-org deployment shows them under the Default Organization instead of
-  // as a member-less account. No-op in multi-org (≥2 orgs) — see the helper.
+  // as a member-less account. No-op in multi-org (≥2 orgs), and no-op under
+  // `membershipPolicy: 'invite-only'` (ADR-0093 D1) — see the helper.
   const membership = await bindUserToSoleOrganization(deps, userId);
 
   await writeAdminAudit(deps, {

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -3996,10 +3996,19 @@ export class AuthManager {
   /**
    * ADR-0093 D1 — the deployment's membership policy **as it stands right now**.
    *
-   * The ONE source both membership paths read (#5152):
+   * The ONE source EVERY membership-writing path reads (#5152):
    *   - sign-up: the reconciler composed into `user.create.after` (below);
    *   - backfill: `AuthPlugin`'s ADR-0093 D6 pass over pre-existing member-less
-   *     users, which used to read the plugin's CONSTRUCTOR options instead.
+   *     users, which used to read the plugin's CONSTRUCTOR options instead;
+   *   - `POST /admin/create-user`: the endpoint-side belt-and-suspenders bind
+   *     in `admin-user-endpoints.ts`, reached through
+   *     `AdminUserEndpointDeps.getMembershipPolicy`.
+   *
+   * That list was written as "both membership paths" while the admin endpoint
+   * handed the reconciler a literal `'auto'` — a third writer, outside the
+   * accounting, binding under `invite-only` where the other two correctly did
+   * not. Enumerate every writer here: a path that is not in this list is a
+   * path that can disagree with the deployment's policy.
    *
    * That split mattered because `this.config` is what {@link applyConfigPatch}
    * targets: once `auth.membership_policy` became a platform setting, the

packages/plugins/plugin-auth/src/auth-plugin.ts

@@ -2410,6 +2410,12 @@ export class AuthPlugin implements Plugin {
         // target org (never grab the bootstrap default org in a multi-tenant
         // deployment); single-org resolves the default org.
         getTenancy: () => this.tenancy ?? undefined,
+        // ADR-0093 D1 — the LIVE membership policy, read through the accessor
+        // per call (the deps factory itself runs per request). A captured
+        // value would keep the endpoint auto-binding after an admin switched
+        // the deployment to `invite-only`, which is the exact defect the
+        // accessor exists to prevent.
+        getMembershipPolicy: () => this.authManager!.getMembershipPolicy(),
         logger: ctx.logger,
       });
       // Gate: the shared `gateAdmin` hoisted above the SSO mounts (#9653).