@happyvertical/smrt-users 0.37.0 → 0.37.2

package/dist/index.js

@@ -1,10 +1,198 @@
-import { D as DEFAULT_ROLES, n as normalizeEmail, i as isValidEmail, P as PermissionCollection, p as parsePermissionSlug, a as isValidPermissionSlug, b as DEFAULT_TENANT_POLICY, T as TenantCollection, M as MembershipCollection, c as DEFAULT_ROLE_SLUGS } from "./chunks/TerminalAuthService-bY1oWeAh.js";
-import { U, d, e, f, g, h, G, j, k, l, m, o, q, r, s, t, O, u, v, w, R, x, S, y, z, A, B, C, E, F, H, I, J, K, U as U2, d as d2, L, N, Q, V, W, X, Y, Z } from "./chunks/TerminalAuthService-bY1oWeAh.js";
+import { n as normalizeEmail, D as DEFAULT_ROLES, U as UserCollection, T as TenantCollection, M as MembershipCollection, i as isValidEmail, a as DEFAULT_ROLE_SLUGS, P as PermissionCollection, p as parsePermissionSlug, b as isValidPermissionSlug, c as DEFAULT_TENANT_POLICY } from "./chunks/TerminalAuthService-DcgimQYo.js";
+import { d, e, f, g, h, j, G, k, l, m, o, q, r, s, t, u, O, v, w, x, R, y, S, z, A, B, C, E, F, H, I, J, K, d as d2, e as e2, L, N, Q, V, W, X, Y, Z } from "./chunks/TerminalAuthService-DcgimQYo.js";
 import { field, smrt, SmrtObject, SmrtCollection, foreignKey, ObjectRegistry, findManifestEntryByQualifiedName } from "@happyvertical/smrt-core";
+import { AccessRequestStatus, UserStatus, MembershipStatus } from "@happyvertical/smrt-types";
+import { AccessRequestStatus as AccessRequestStatus2, MembershipStatus as MembershipStatus2, OverrideEffect, SessionStatus, TenantPermissionEffect, TenantStatus, UserStatus as UserStatus2 } from "@happyvertical/smrt-types";
+import { createLogger } from "@happyvertical/logger";
 import { getPackageConfig } from "@happyvertical/smrt-config";
 import { createHash } from "node:crypto";
-import { MembershipStatus } from "@happyvertical/smrt-types";
-import { MembershipStatus as MembershipStatus2, OverrideEffect, SessionStatus, TenantPermissionEffect, TenantStatus, UserStatus } from "@happyvertical/smrt-types";
+var __defProp$2 = Object.defineProperty;
+var __getOwnPropDesc$2 = Object.getOwnPropertyDescriptor;
+var __decorateClass$2 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$2(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp$2(target, key, result);
+  return result;
+};
+let AccessRequest = class extends SmrtObject {
+  email = "";
+  name = null;
+  status = AccessRequestStatus.REQUESTED;
+  source = "";
+  requestContext = "{}";
+  note = null;
+  requestedAt = /* @__PURE__ */ new Date();
+  decidedAt = null;
+  decidedBy = null;
+  resultingUserId = null;
+  tenantHint = null;
+  constructor(options = {}) {
+    super(options);
+    if (options.email !== void 0) this.email = normalizeEmail(options.email);
+    if (options.name !== void 0) this.name = options.name;
+    if (options.status !== void 0) this.status = options.status;
+    if (options.source !== void 0) this.source = options.source;
+    if (options.requestContext !== void 0)
+      this.requestContext = options.requestContext;
+    if (options.note !== void 0) this.note = options.note;
+    if (options.requestedAt !== void 0)
+      this.requestedAt = options.requestedAt;
+    if (options.decidedAt !== void 0) this.decidedAt = options.decidedAt;
+    if (options.decidedBy !== void 0) this.decidedBy = options.decidedBy;
+    if (options.resultingUserId !== void 0)
+      this.resultingUserId = options.resultingUserId;
+    if (options.tenantHint !== void 0) this.tenantHint = options.tenantHint;
+  }
+  /**
+   * Parse {@link requestContext} into an object. Returns `{}` on missing or
+   * malformed JSON (graceful — never throws).
+   */
+  getRequestContext() {
+    try {
+      const parsed = JSON.parse(this.requestContext);
+      return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+  /**
+   * Serialize and store {@link requestContext} from an object.
+   */
+  setRequestContext(value) {
+    this.requestContext = JSON.stringify(value ?? {});
+  }
+  /**
+   * Parse {@link tenantHint} into an object, or `null` when unset / malformed.
+   */
+  getTenantHint() {
+    if (!this.tenantHint) return null;
+    try {
+      const parsed = JSON.parse(this.tenantHint);
+      return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Serialize and store {@link tenantHint} from an object (or clear with null).
+   */
+  setTenantHint(value) {
+    this.tenantHint = value ? JSON.stringify(value) : null;
+  }
+  /**
+   * Whether the request is still open (awaiting a decision).
+   */
+  isOpen() {
+    return this.status === AccessRequestStatus.REQUESTED;
+  }
+  /**
+   * Whether the request has been approved (and not yet graduated).
+   */
+  isApproved() {
+    return this.status === AccessRequestStatus.APPROVED;
+  }
+  /**
+   * Whether the request reached a terminal state (declined, graduated, or
+   * canceled) and can no longer transition.
+   */
+  isTerminal() {
+    return this.status === AccessRequestStatus.DECLINED || this.status === AccessRequestStatus.GRADUATED || this.status === AccessRequestStatus.CANCELED;
+  }
+};
+__decorateClass$2([
+  field({ required: true, indexed: true })
+], AccessRequest.prototype, "email", 2);
+__decorateClass$2([
+  field({ nullable: true })
+], AccessRequest.prototype, "name", 2);
+__decorateClass$2([
+  field({ type: "text", indexed: true })
+], AccessRequest.prototype, "status", 2);
+__decorateClass$2([
+  field({ indexed: true })
+], AccessRequest.prototype, "source", 2);
+__decorateClass$2([
+  field()
+], AccessRequest.prototype, "requestContext", 2);
+__decorateClass$2([
+  field({ nullable: true })
+], AccessRequest.prototype, "note", 2);
+__decorateClass$2([
+  field()
+], AccessRequest.prototype, "requestedAt", 2);
+__decorateClass$2([
+  field({ nullable: true })
+], AccessRequest.prototype, "decidedAt", 2);
+__decorateClass$2([
+  field({ nullable: true })
+], AccessRequest.prototype, "decidedBy", 2);
+__decorateClass$2([
+  field({ nullable: true })
+], AccessRequest.prototype, "resultingUserId", 2);
+__decorateClass$2([
+  field({ nullable: true })
+], AccessRequest.prototype, "tenantHint", 2);
+AccessRequest = __decorateClass$2([
+  smrt({
+    tableName: "access_requests",
+    // Append-style: the natural key is the surrogate id, so a new request never
+    // upserts over an existing row. Without this, SMRT defaults to upserting on
+    // `slug`/`context`, and `slug` is derived from `name` — two public submissions
+    // sharing a display name (e.g. two "Jane Doe"s with different emails) would
+    // collide and overwrite each other. Open-request dedup is handled explicitly
+    // by AccessRequestService.createAccessRequest, not by the storage conflict key.
+    conflictColumns: ["id"],
+    // CLOSED generated surface — all access flows through AccessRequestService.
+    api: { include: [] },
+    mcp: { include: [] },
+    cli: { include: [] }
+  })
+], AccessRequest);
+class AccessRequestCollection extends SmrtCollection {
+  static _itemClass = AccessRequest;
+  /**
+   * Find all access requests for an email (any status), newest first. The email
+   * is normalized before querying so callers can pass any case.
+   */
+  async findByEmail(email) {
+    return await this.list({
+      where: { email: normalizeEmail(email) },
+      orderBy: "created_at DESC"
+    });
+  }
+  /**
+   * Find the single open (`REQUESTED`) request for an email, if any. This is
+   * the dedup key used by {@link AccessRequestService.createAccessRequest}.
+   */
+  async findOpenByEmail(email) {
+    const results = await this.list({
+      where: {
+        email: normalizeEmail(email),
+        status: AccessRequestStatus.REQUESTED
+      },
+      limit: 1,
+      orderBy: "created_at DESC"
+    });
+    return results.length > 0 ? results[0] : null;
+  }
+  /**
+   * Find access requests by status, newest first.
+   */
+  async findByStatus(status) {
+    return await this.list({
+      where: { status },
+      orderBy: "created_at DESC"
+    });
+  }
+  /**
+   * Find all open (`REQUESTED`) access requests — the operator triage queue.
+   */
+  async findOpen() {
+    return await this.findByStatus(AccessRequestStatus.REQUESTED);
+  }
+}
 var __defProp$1 = Object.defineProperty;
 var __getOwnPropDesc$1 = Object.getOwnPropertyDescriptor;
 var __decorateClass$1 = (decorators, target, key, kind) => {
@@ -253,6 +441,521 @@ class RoleCollection extends SmrtCollection {
     return roles;
   }
 }
+const logger = createLogger({ level: "info" });
+const ACCESS_REQUEST_CAPABILITIES = {
+  /** Read the access-request queue (`list` / `get`). */
+  READ: "access-requests:read",
+  /** Decide requests (`approve` / `decline` / `cancel` / `graduate`). */
+  MANAGE: "access-requests:manage"
+};
+class AccessRequestError extends Error {
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "AccessRequestError";
+    this.code = code;
+  }
+}
+const APPROVE_FROM = [AccessRequestStatus.REQUESTED];
+const DECLINE_FROM = [
+  AccessRequestStatus.REQUESTED,
+  AccessRequestStatus.APPROVED
+];
+const CANCEL_FROM = [
+  AccessRequestStatus.REQUESTED,
+  AccessRequestStatus.APPROVED
+];
+class AccessRequestService {
+  #options;
+  #authorize;
+  #onEvent;
+  #requests;
+  #users;
+  #tenants;
+  #memberships;
+  #roles;
+  #rolesSeeded = false;
+  constructor(options) {
+    this.#options = options;
+    this.#authorize = options.authorize;
+    this.#onEvent = options.onEvent;
+  }
+  /**
+   * Initialize the backing collections (creates/verifies their tables).
+   */
+  async initialize() {
+    this.#requests = await AccessRequestCollection.create(this.#options);
+    this.#users = await UserCollection.create(this.#options);
+    this.#tenants = await TenantCollection.create(this.#options);
+    this.#memberships = await MembershipCollection.create(this.#options);
+    this.#roles = await RoleCollection.create(this.#options);
+  }
+  /**
+   * Static factory — construct and initialize in one call.
+   */
+  static async create(options) {
+    const service = new AccessRequestService(options);
+    await service.initialize();
+    return service;
+  }
+  /**
+   * The underlying collection, for advanced read scenarios. Prefer the service
+   * methods, which apply normalization, the state machine, capability gating,
+   * and events.
+   */
+  get collection() {
+    return this.#requests;
+  }
+  // ============= Public-safe creation =============
+  /**
+   * Create an access request. **Public-safe**: no capability check — meant to be
+   * callable unauthenticated by apps (which add their own rate-limiting).
+   *
+   * Validates and normalizes the email, then de-duplicates: if an open
+   * (`REQUESTED`) request already exists for the email, this merges any newly
+   * supplied context/name/source/hint into it and returns it instead of
+   * creating a duplicate (no second `created` event).
+   *
+   * @remarks
+   * De-duplication is **best-effort, not atomic**: it is a read-then-write
+   * (`findOpenByEmail` → `create`) with no DB-level partial-unique constraint
+   * (the table is append-style, keyed on `id`, because the same email may
+   * accumulate many requests over its lifetime). Two requests for the same
+   * email racing concurrently can therefore both create an open row. This is by
+   * design — the spec makes dedup configurable and pushes abuse control to the
+   * app (rate-limiting on the public endpoint). Operators triaging two open rows
+   * for one email is benign; apps needing a hard single-open-request guarantee
+   * should add a partial unique index (`UNIQUE(email) WHERE status='requested'`)
+   * in their migration.
+   *
+   * @throws {@link AccessRequestError} (`INVALID_EMAIL`) when the email is invalid.
+   */
+  async createAccessRequest(input) {
+    const email = normalizeEmail(input.email);
+    if (!isValidEmail(email)) {
+      throw new AccessRequestError(
+        "A valid email address is required to request access.",
+        "INVALID_EMAIL"
+      );
+    }
+    const existing = await this.#requests.findOpenByEmail(email);
+    if (existing) {
+      let changed = false;
+      if (input.context && Object.keys(input.context).length > 0) {
+        existing.setRequestContext({
+          ...existing.getRequestContext(),
+          ...input.context
+        });
+        changed = true;
+      }
+      if (input.tenantHint) {
+        existing.setTenantHint({
+          ...existing.getTenantHint() ?? {},
+          ...input.tenantHint
+        });
+        changed = true;
+      }
+      if (input.name && !existing.name) {
+        existing.name = input.name;
+        changed = true;
+      }
+      if (input.source && !existing.source) {
+        existing.source = input.source;
+        changed = true;
+      }
+      if (changed) await existing.save();
+      return existing;
+    }
+    const request = await this.#requests.create({
+      email,
+      name: input.name ?? null,
+      source: input.source ?? "",
+      status: AccessRequestStatus.REQUESTED,
+      requestedAt: /* @__PURE__ */ new Date(),
+      requestContext: JSON.stringify(input.context ?? {}),
+      tenantHint: input.tenantHint ? JSON.stringify(input.tenantHint) : null,
+      note: input.note ?? null
+    });
+    await this.#emit({
+      type: "access-request.created",
+      accessRequest: request,
+      at: /* @__PURE__ */ new Date()
+    });
+    return request;
+  }
+  // ============= Operator reads =============
+  /**
+   * List access requests (operator-facing). Requires the `access-requests:read`
+   * capability when an authorizer is configured.
+   */
+  async listAccessRequests(filter = {}) {
+    await this.#requireCapability(ACCESS_REQUEST_CAPABILITIES.READ, {
+      by: filter.by
+    });
+    const where = {};
+    if (filter.status !== void 0) where.status = filter.status;
+    if (filter.email !== void 0) where.email = normalizeEmail(filter.email);
+    if (filter.source !== void 0) where.source = filter.source;
+    return await this.#requests.list({
+      where,
+      limit: filter.limit,
+      offset: filter.offset,
+      orderBy: filter.orderBy ?? "created_at DESC"
+    });
+  }
+  /**
+   * Get a single access request by id (operator-facing). Requires the
+   * `access-requests:read` capability when an authorizer is configured.
+   */
+  async getAccessRequest(id, options = {}) {
+    await this.#requireCapability(ACCESS_REQUEST_CAPABILITIES.READ, {
+      by: options.by,
+      accessRequestId: id
+    });
+    return await this.#requests.get(id);
+  }
+  // ============= Operator decisions =============
+  /**
+   * Approve a request: `REQUESTED → APPROVED`. Idempotent (re-approving an
+   * already-`APPROVED` request is a no-op returning it). Requires
+   * `access-requests:manage`.
+   *
+   * @throws {@link AccessRequestError} (`INVALID_TRANSITION`) from a terminal state.
+   */
+  async approveAccessRequest(id, options = {}) {
+    await this.#requireCapability(ACCESS_REQUEST_CAPABILITIES.MANAGE, {
+      by: options.by,
+      accessRequestId: id
+    });
+    const request = await this.#load(id);
+    if (request.status === AccessRequestStatus.APPROVED) return request;
+    this.#assertTransition(request, APPROVE_FROM, "approve");
+    request.status = AccessRequestStatus.APPROVED;
+    request.decidedAt = /* @__PURE__ */ new Date();
+    if (options.by) request.decidedBy = options.by;
+    if (options.note != null) request.note = options.note;
+    await request.save();
+    await this.#emit({
+      type: "access-request.approved",
+      accessRequest: request,
+      at: /* @__PURE__ */ new Date(),
+      by: options.by
+    });
+    return request;
+  }
+  /**
+   * Decline a request: `REQUESTED | APPROVED → DECLINED`. Idempotent. Requires
+   * `access-requests:manage`.
+   *
+   * @throws {@link AccessRequestError} (`INVALID_TRANSITION`) from a terminal state.
+   */
+  async declineAccessRequest(id, options = {}) {
+    await this.#requireCapability(ACCESS_REQUEST_CAPABILITIES.MANAGE, {
+      by: options.by,
+      accessRequestId: id
+    });
+    const request = await this.#load(id);
+    if (request.status === AccessRequestStatus.DECLINED) return request;
+    this.#assertTransition(request, DECLINE_FROM, "decline");
+    request.status = AccessRequestStatus.DECLINED;
+    request.decidedAt = /* @__PURE__ */ new Date();
+    if (options.by) request.decidedBy = options.by;
+    if (options.reason != null) request.note = options.reason;
+    await request.save();
+    await this.#emit({
+      type: "access-request.declined",
+      accessRequest: request,
+      at: /* @__PURE__ */ new Date(),
+      by: options.by
+    });
+    return request;
+  }
+  /**
+   * Cancel a request: `REQUESTED | APPROVED → CANCELED`. Idempotent. Requires
+   * `access-requests:manage`.
+   *
+   * @throws {@link AccessRequestError} (`INVALID_TRANSITION`) from a terminal state.
+   */
+  async cancelAccessRequest(id, options = {}) {
+    await this.#requireCapability(ACCESS_REQUEST_CAPABILITIES.MANAGE, {
+      by: options.by,
+      accessRequestId: id
+    });
+    const request = await this.#load(id);
+    if (request.status === AccessRequestStatus.CANCELED) return request;
+    this.#assertTransition(request, CANCEL_FROM, "cancel");
+    request.status = AccessRequestStatus.CANCELED;
+    request.decidedAt = /* @__PURE__ */ new Date();
+    if (options.by) request.decidedBy = options.by;
+    if (options.reason != null) request.note = options.reason;
+    await request.save();
+    await this.#emit({
+      type: "access-request.canceled",
+      accessRequest: request,
+      at: /* @__PURE__ */ new Date(),
+      by: options.by
+    });
+    return request;
+  }
+  // ============= Graduation =============
+  /**
+   * Graduate an approved request into a `User`, optionally attaching a tenant.
+   *
+   * Valid from `APPROVED` (or from `REQUESTED` when
+   * {@link GraduateAccessRequestOptions.allowFromRequested} is set). Creates a
+   * user when none exists for the email, or **links** the existing one
+   * otherwise (reusing {@link UserCollection}). Idempotent: a second call on an
+   * already-`GRADUATED` request returns the same user (and an existing
+   * membership for the requested tenant, if any) without re-creating anything.
+   *
+   * Requires `access-requests:manage`.
+   *
+   * @throws {@link AccessRequestError} — `NOT_FOUND` (unknown id),
+   *   `INVALID_TRANSITION` (terminal/declined/canceled or `REQUESTED` without
+   *   `allowFromRequested`), `TENANT_NOT_FOUND`, or `ROLE_NOT_FOUND`.
+   */
+  async graduateAccessRequest(id, options = {}) {
+    await this.#requireCapability(ACCESS_REQUEST_CAPABILITIES.MANAGE, {
+      by: options.by,
+      accessRequestId: id
+    });
+    const request = await this.#load(id);
+    const tenantOption = options.tenant ?? "none";
+    if (request.status === AccessRequestStatus.GRADUATED && request.resultingUserId) {
+      const existingUser = await this.#users.get(request.resultingUserId);
+      if (existingUser) {
+        const membership2 = await this.#resolveExistingMembership(
+          existingUser.id,
+          tenantOption
+        );
+        return {
+          user: existingUser,
+          membership: membership2 ?? void 0,
+          accessRequest: request,
+          created: false
+        };
+      }
+    }
+    if (request.status !== AccessRequestStatus.GRADUATED) {
+      const allowFromRequested = options.allowFromRequested ?? false;
+      const canGraduate = request.status === AccessRequestStatus.APPROVED || request.status === AccessRequestStatus.REQUESTED && allowFromRequested;
+      if (!canGraduate) {
+        const hint = request.status === AccessRequestStatus.REQUESTED ? " (approve it first, or pass allowFromRequested)" : "";
+        throw new AccessRequestError(
+          `Cannot graduate an access request in status "${request.status}"${hint}.`,
+          "INVALID_TRANSITION"
+        );
+      }
+    }
+    if (tenantOption !== "none") {
+      await this.#ensureRolesSeeded();
+      await this.#validateTenantOption(tenantOption);
+    }
+    const email = normalizeEmail(request.email);
+    let user = await this.#users.findByEmail(email);
+    let created = false;
+    if (!user) {
+      user = await this.#users.create({
+        email,
+        status: options.activate ?? UserStatus.ACTIVE
+      });
+      created = true;
+    } else if (options.activate !== void 0 && user.status !== options.activate) {
+      user.status = options.activate;
+      await user.save();
+    }
+    let membership;
+    let tenant;
+    if (tenantOption !== "none") {
+      const attached = await this.#attachTenant(
+        user.id,
+        tenantOption
+      );
+      membership = attached.membership;
+      tenant = attached.tenant;
+    }
+    request.status = AccessRequestStatus.GRADUATED;
+    request.resultingUserId = user.id;
+    request.decidedAt = /* @__PURE__ */ new Date();
+    if (options.by) request.decidedBy = options.by;
+    if (options.note != null) request.note = options.note;
+    await request.save();
+    await this.#emit({
+      type: "access-request.graduated",
+      accessRequest: request,
+      at: /* @__PURE__ */ new Date(),
+      by: options.by,
+      user,
+      membership,
+      tenant
+    });
+    return { user, membership, tenant, accessRequest: request, created };
+  }
+  // ============= Internals =============
+  /**
+   * Load a request or throw `NOT_FOUND`.
+   */
+  async #load(id) {
+    const request = await this.#requests.get(id);
+    if (!request) {
+      throw new AccessRequestError("Access request not found.", "NOT_FOUND");
+    }
+    return request;
+  }
+  /**
+   * Guard a state transition; throw `INVALID_TRANSITION` if the current status
+   * is not an allowed source.
+   */
+  #assertTransition(request, allowedFrom, action) {
+    if (!allowedFrom.includes(request.status)) {
+      throw new AccessRequestError(
+        `Cannot ${action} an access request in status "${request.status}".`,
+        "INVALID_TRANSITION"
+      );
+    }
+  }
+  /**
+   * Run the configured authorizer (if any). Absent an authorizer, operator
+   * methods are ungated — see the class-level security note.
+   */
+  async #requireCapability(capability, context) {
+    if (!this.#authorize) return;
+    await this.#authorize({
+      capability,
+      by: context.by ?? null,
+      accessRequestId: context.accessRequestId
+    });
+  }
+  /**
+   * Best-effort event delivery — a throwing handler is logged and swallowed so
+   * it cannot roll back an already-persisted transition.
+   */
+  async #emit(event) {
+    if (!this.#onEvent) return;
+    try {
+      await this.#onEvent(event);
+    } catch (error) {
+      logger.error(
+        `AccessRequest event handler threw for "${event.type}" (request ${event.accessRequest.id})`,
+        { error }
+      );
+    }
+  }
+  /**
+   * Throw `ROLE_NOT_FOUND` if no role with `roleSlug` is resolvable (tenant-
+   * specific first, then system). Roles must already be seeded.
+   */
+  async #assertRoleExists(roleSlug, tenantId) {
+    if (!await this.#roles.findBySlug(roleSlug, tenantId)) {
+      throw new AccessRequestError(
+        `Role "${roleSlug}" not found — seed system roles or pass a valid role slug.`,
+        "ROLE_NOT_FOUND"
+      );
+    }
+  }
+  /**
+   * Validate a graduation tenant option with NO side effects: the target tenant
+   * must exist (existing-tenant variant) and the role slug must resolve. Run
+   * before any persistence so a bad option can't leave orphan rows.
+   */
+  async #validateTenantOption(option) {
+    if ("tenantId" in option) {
+      const tenant = await this.#tenants.get(option.tenantId);
+      if (!tenant) {
+        throw new AccessRequestError(
+          `Target tenant "${option.tenantId}" not found.`,
+          "TENANT_NOT_FOUND"
+        );
+      }
+      await this.#assertRoleExists(
+        option.role ?? DEFAULT_ROLE_SLUGS.MEMBER,
+        option.tenantId
+      );
+    } else {
+      await this.#assertRoleExists(option.role ?? DEFAULT_ROLE_SLUGS.OWNER);
+    }
+  }
+  /**
+   * Create-or-attach the requester to a tenant, reusing the tenant / role /
+   * membership collections (no duplication of user/membership logic).
+   */
+  async #attachTenant(userId, option) {
+    await this.#ensureRolesSeeded();
+    if ("tenantId" in option) {
+      const tenant2 = await this.#tenants.get(option.tenantId);
+      if (!tenant2) {
+        throw new AccessRequestError(
+          `Target tenant "${option.tenantId}" not found.`,
+          "TENANT_NOT_FOUND"
+        );
+      }
+      const membership2 = await this.#getOrCreateMembership(
+        userId,
+        tenant2.id,
+        option.role ?? DEFAULT_ROLE_SLUGS.MEMBER
+      );
+      return { tenant: tenant2, membership: membership2 };
+    }
+    const tenant = await this.#tenants.create({
+      name: option.create.name,
+      slug: option.create.slug,
+      description: option.create.description,
+      status: option.create.status
+    });
+    const membership = await this.#getOrCreateMembership(
+      userId,
+      tenant.id,
+      option.role ?? DEFAULT_ROLE_SLUGS.OWNER
+    );
+    return { tenant, membership };
+  }
+  /**
+   * Resolve (creating if needed) the user's membership in a tenant with the
+   * given role slug. Idempotent — returns any existing membership for the pair.
+   */
+  async #getOrCreateMembership(userId, tenantId, roleSlug) {
+    const existing = await this.#memberships.findByUserAndTenant(
+      userId,
+      tenantId
+    );
+    if (existing) return existing;
+    const role = await this.#roles.findBySlug(roleSlug, tenantId);
+    if (!role) {
+      throw new AccessRequestError(
+        `Role "${roleSlug}" not found — seed system roles or pass a valid role slug.`,
+        "ROLE_NOT_FOUND"
+      );
+    }
+    return await this.#memberships.create({
+      userId,
+      tenantId,
+      roleId: role.id,
+      status: MembershipStatus.ACTIVE
+    });
+  }
+  /**
+   * For idempotent re-graduation: find an existing membership for the requested
+   * tenant. Only the existing-tenant variant is resolvable (a `{ create }`
+   * variant has no known tenant id on a re-call).
+   */
+  async #resolveExistingMembership(userId, tenantOption) {
+    if (tenantOption === "none" || !("tenantId" in tenantOption)) return null;
+    return await this.#memberships.findByUserAndTenant(
+      userId,
+      tenantOption.tenantId
+    );
+  }
+  /**
+   * Lazily seed the default system roles (owner/admin/member/viewer) the first
+   * time graduation attaches a tenant — so the public create path never incurs
+   * the write.
+   */
+  async #ensureRolesSeeded() {
+    if (this.#rolesSeeded) return;
+    await this.#roles.seedSystemRoles();
+    this.#rolesSeeded = true;
+  }
+}
 class MagicLinkError extends Error {
   constructor(message) {
     super(message);
@@ -299,7 +1002,7 @@ class MagicLinkService {
    * The caller is responsible for emailing the token to the user.
    */
   async generate(email) {
-    const { SignJWT } = await import("./chunks/index-DBpq-WMK.js");
+    const { SignJWT } = await import("./chunks/index-C3E55ikp.js");
     const key = await this.getSigningKey();
     const nonce = crypto.randomUUID();
     const normalizedEmail = normalizeEmail(email);
@@ -328,7 +1031,7 @@ class MagicLinkService {
    * @throws {MagicLinkError} If the token is invalid, expired, or already used
    */
   async verify(token) {
-    const { jwtVerify, errors } = await import("./chunks/index-DBpq-WMK.js");
+    const { jwtVerify, errors } = await import("./chunks/index-C3E55ikp.js");
     const key = await this.getSigningKey();
     let payload;
     try {
@@ -1339,63 +2042,69 @@ class TenantService {
   }
 }
 export {
-  U as CliAuthRequest,
-  d as CliAuthRequestCollection,
-  e as DEFAULT_CLI_AUTH_POLL_INTERVAL_SECONDS,
-  f as DEFAULT_CLI_AUTH_REQUEST_TTL_SECONDS,
-  g as DEFAULT_CLI_SESSION_TTL_SECONDS,
+  ACCESS_REQUEST_CAPABILITIES,
+  AccessRequest,
+  AccessRequestCollection,
+  AccessRequestError,
+  AccessRequestService,
+  AccessRequestStatus2 as AccessRequestStatus,
+  d as CliAuthRequest,
+  e as CliAuthRequestCollection,
+  f as DEFAULT_CLI_AUTH_POLL_INTERVAL_SECONDS,
+  g as DEFAULT_CLI_AUTH_REQUEST_TTL_SECONDS,
+  h as DEFAULT_CLI_SESSION_TTL_SECONDS,
   DEFAULT_ROLES,
   DEFAULT_ROLE_SLUGS,
-  h as DEFAULT_SESSION_TTL,
+  j as DEFAULT_SESSION_TTL,
   DEFAULT_TENANT_POLICY,
   DEFAULT_TOKEN_EXPIRY_SECONDS,
   G as Group,
-  j as GroupCollection,
-  k as GroupMember,
-  l as GroupMemberCollection,
-  m as GroupRole,
-  o as GroupRoleCollection,
-  q as MAX_TENANT_HIERARCHY_DEPTH,
+  k as GroupCollection,
+  l as GroupMember,
+  m as GroupMemberCollection,
+  o as GroupRole,
+  q as GroupRoleCollection,
+  r as MAX_TENANT_HIERARCHY_DEPTH,
   MagicLinkError,
   MagicLinkService,
   UsersMagicLinkToken as MagicLinkToken,
   UsersMagicLinkTokenCollection as MagicLinkTokenCollection,
-  r as Membership,
+  s as Membership,
   MembershipCollection,
-  s as MembershipOverride,
-  t as MembershipOverrideCollection,
+  t as MembershipOverride,
+  u as MembershipOverrideCollection,
   MembershipStatus2 as MembershipStatus,
   O as OidcLoginError,
-  u as OidcLoginService,
+  v as OidcLoginService,
   OverrideEffect,
-  v as Permission,
+  w as Permission,
   PermissionCatalogService,
   PermissionCollection,
-  w as PermissionResolver,
+  x as PermissionResolver,
   Role,
   RoleCollection,
   R as RolePermission,
-  x as RolePermissionCollection,
+  y as RolePermissionCollection,
   S as Session,
-  y as SessionCollection,
-  z as SessionService,
+  z as SessionCollection,
+  A as SessionService,
   SessionStatus,
-  A as Tenant,
+  B as Tenant,
   TenantCollection,
-  B as TenantHierarchyError,
+  C as TenantHierarchyError,
   TenantPermissionEffect,
-  C as TenantPermissionOverride,
-  E as TenantPermissionOverrideCollection,
+  E as TenantPermissionOverride,
+  F as TenantPermissionOverrideCollection,
   TenantService,
   TenantStatus,
-  F as TerminalAuthError,
-  H as TerminalAuthRateLimitError,
-  I as TerminalAuthService,
-  J as User,
-  K as UserCollection,
-  UserStatus,
-  U2 as UsersCliAuthRequest,
-  d2 as UsersCliAuthRequestCollection,
+  H as TerminalAuthError,
+  I as TerminalAuthRateLimitError,
+  J as TerminalAuthService,
+  K as User,
+  UserCollection,
+  UserStatus2 as UserStatus,
+  d2 as UsersCliAuthRequest,
+  e2 as UsersCliAuthRequestCollection,
   UsersMagicLinkToken,
   UsersMagicLinkTokenCollection,
   applyPostgresPermissionPolicies,