@happyvertical/smrt-users 0.37.1 → 0.37.2

package/dist/services/AccessRequestService.d.ts

@@ -0,0 +1,326 @@
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { AccessRequestCollection } from '../collections/AccessRequestCollection.js';
+import { AccessRequest } from '../models/AccessRequest.js';
+import { Membership } from '../models/Membership.js';
+import { Tenant } from '../models/Tenant.js';
+import { User } from '../models/User.js';
+import { AccessRequestStatus, TenantStatus, UserStatus } from '../types/index.js';
+/**
+ * Capabilities that gate the operator-facing methods of
+ * {@link AccessRequestService}.
+ */
+export declare const ACCESS_REQUEST_CAPABILITIES: {
+    /** Read the access-request queue (`list` / `get`). */
+    readonly READ: "access-requests:read";
+    /** Decide requests (`approve` / `decline` / `cancel` / `graduate`). */
+    readonly MANAGE: "access-requests:manage";
+};
+/**
+ * One of the capability slugs in {@link ACCESS_REQUEST_CAPABILITIES}.
+ */
+export type AccessRequestCapability = (typeof ACCESS_REQUEST_CAPABILITIES)[keyof typeof ACCESS_REQUEST_CAPABILITIES];
+/**
+ * Context passed to an {@link AccessRequestAuthorizer} before an operator method
+ * runs.
+ */
+export interface AccessRequestAuthorizationContext {
+    /** The capability the operation requires. */
+    capability: AccessRequestCapability;
+    /** The operator user id supplied to the method (`by`), if any. */
+    by?: string | null;
+    /** The target access-request id, when the operation targets a specific row. */
+    accessRequestId?: string;
+}
+/**
+ * Hook that authorizes an operator action. Throw (or reject) to deny — the
+ * thrown error propagates to the caller unchanged. Resolve/return to allow.
+ *
+ * Wire this to your permission system, e.g. resolve the operator's permissions
+ * and assert the required capability:
+ *
+ * ```typescript
+ * const service = await AccessRequestService.create({
+ *   db,
+ *   authorize: async ({ capability, by }) => {
+ *     if (!by || !(await isPlatformOperator(by, capability))) {
+ *       throw new Error(`Missing capability: ${capability}`);
+ *     }
+ *   },
+ * });
+ * ```
+ */
+export type AccessRequestAuthorizer = (context: AccessRequestAuthorizationContext) => void | Promise<void>;
+/**
+ * Lifecycle event types emitted by {@link AccessRequestService}.
+ */
+export type AccessRequestEventType = 'access-request.created' | 'access-request.approved' | 'access-request.declined' | 'access-request.canceled' | 'access-request.graduated';
+/**
+ * Payload delivered to an {@link AccessRequestEventHandler}.
+ */
+export interface AccessRequestEvent {
+    /** Which lifecycle transition fired. */
+    type: AccessRequestEventType;
+    /** The access request after the transition. */
+    accessRequest: AccessRequest;
+    /** When the event was emitted. */
+    at: Date;
+    /** Operator user id responsible, for operator-driven transitions. */
+    by?: string | null;
+    /** Graduated user (only on `access-request.graduated`). */
+    user?: User;
+    /** Membership created/linked on graduation, when a tenant was attached. */
+    membership?: Membership;
+    /** Tenant created/linked on graduation, when a tenant was attached. */
+    tenant?: Tenant;
+}
+/**
+ * Event hook apps provide to react to access-request lifecycle changes.
+ * Delivery is best-effort: a throwing handler is logged and swallowed so it
+ * never rolls back an already-persisted transition. Do not rely on it for
+ * critical-path work that must share the request's transaction.
+ */
+export type AccessRequestEventHandler = (event: AccessRequestEvent) => void | Promise<void>;
+/**
+ * Options for {@link AccessRequestService}.
+ */
+export interface AccessRequestServiceOptions extends SmrtClassOptions {
+    /** Optional capability gate for operator methods (see {@link AccessRequestAuthorizer}). */
+    authorize?: AccessRequestAuthorizer;
+    /** Optional lifecycle event hook (see {@link AccessRequestEventHandler}). */
+    onEvent?: AccessRequestEventHandler;
+}
+/**
+ * Input for {@link AccessRequestService.createAccessRequest}. Only `email` is
+ * required.
+ */
+export interface CreateAccessRequestInput {
+    /** Requester email (validated + normalized to lowercase). */
+    email: string;
+    /** Requester display name. */
+    name?: string | null;
+    /** Where the request came from, e.g. `www`, `sdk`. */
+    source?: string;
+    /** Free-form metadata (intended use, company, message, referrer, …). */
+    context?: Record<string, unknown>;
+    /** Optional requested org/tenant hint (advisory). */
+    tenantHint?: Record<string, unknown> | null;
+    /** Optional initial note. */
+    note?: string | null;
+}
+/**
+ * Filter for {@link AccessRequestService.listAccessRequests}.
+ */
+export interface ListAccessRequestsFilter {
+    /** Restrict to one status or any of several. */
+    status?: AccessRequestStatus | AccessRequestStatus[];
+    /** Restrict to a single (normalized) email. */
+    email?: string;
+    /** Restrict to a single source. */
+    source?: string;
+    /** Operator user id, forwarded to the authorizer as `by`. */
+    by?: string | null;
+    /** Max rows to return. */
+    limit?: number;
+    /** Rows to skip. */
+    offset?: number;
+    /** Order-by clause (defaults to `created_at DESC`). */
+    orderBy?: string;
+}
+/**
+ * Options shared by the operator decision methods.
+ */
+export interface DecideAccessRequestOptions {
+    /** Operator user id recorded as `decidedBy` and forwarded to the authorizer. */
+    by?: string | null;
+}
+/**
+ * Options for {@link AccessRequestService.approveAccessRequest}.
+ */
+export interface ApproveAccessRequestOptions extends DecideAccessRequestOptions {
+    /** Operator note stored on the request. */
+    note?: string | null;
+}
+/**
+ * Options for {@link AccessRequestService.declineAccessRequest}.
+ */
+export interface DeclineAccessRequestOptions extends DecideAccessRequestOptions {
+    /** Decision reason stored as the request's note. */
+    reason?: string | null;
+}
+/**
+ * Options for {@link AccessRequestService.cancelAccessRequest}.
+ */
+export interface CancelAccessRequestOptions extends DecideAccessRequestOptions {
+    /** Cancellation reason stored as the request's note. */
+    reason?: string | null;
+}
+/**
+ * Graduate into a **new** tenant, enrolling the requester (owner by default).
+ */
+export interface GraduateNewTenantOption {
+    /** New tenant attributes — `name` is required. */
+    create: {
+        name: string;
+        slug?: string;
+        description?: string;
+        status?: TenantStatus;
+    };
+    /** Role slug for the requester's membership (default `owner`). */
+    role?: string;
+}
+/**
+ * Graduate into an **existing** tenant, enrolling the requester.
+ */
+export interface GraduateExistingTenantOption {
+    /** Target tenant id. */
+    tenantId: string;
+    /** Role slug for the requester's membership (default `member`). */
+    role?: string;
+}
+/**
+ * Tenant handling at graduation: create a new tenant, attach to an existing
+ * one, or `'none'` (user only, no membership).
+ */
+export type GraduateTenantOption = GraduateNewTenantOption | GraduateExistingTenantOption | 'none';
+/**
+ * Options for {@link AccessRequestService.graduateAccessRequest}.
+ */
+export interface GraduateAccessRequestOptions extends DecideAccessRequestOptions {
+    /** Tenant handling (default `'none'`). */
+    tenant?: GraduateTenantOption;
+    /** Status applied to the user produced/linked by graduation (default `ACTIVE`). */
+    activate?: UserStatus;
+    /**
+     * Convenience: allow graduating directly from `REQUESTED` (skipping the
+     * `APPROVED` step). Defaults to `false`.
+     */
+    allowFromRequested?: boolean;
+    /** Operator note stored on the request. */
+    note?: string | null;
+}
+/**
+ * Result of {@link AccessRequestService.graduateAccessRequest}.
+ */
+export interface GraduateAccessRequestResult {
+    /** The graduated (created or linked) user. */
+    user: User;
+    /** The membership, when a tenant was attached. */
+    membership?: Membership;
+    /** The tenant, when one was created or attached. */
+    tenant?: Tenant;
+    /** The access request, now `GRADUATED`. */
+    accessRequest: AccessRequest;
+    /** Whether a brand-new user was created (`false` when an existing one was linked). */
+    created: boolean;
+}
+/**
+ * Error codes raised by {@link AccessRequestError}.
+ */
+export type AccessRequestErrorCode = 'INVALID_EMAIL' | 'NOT_FOUND' | 'INVALID_TRANSITION' | 'TENANT_NOT_FOUND' | 'ROLE_NOT_FOUND';
+/**
+ * Error thrown for access-request domain failures the caller is expected to
+ * surface (invalid email, unknown id, illegal state transition, …). Authorizer
+ * denials are not wrapped — those propagate from the supplied authorizer
+ * unchanged.
+ */
+export declare class AccessRequestError extends Error {
+    readonly code: AccessRequestErrorCode;
+    constructor(message: string, code: AccessRequestErrorCode);
+}
+/**
+ * High-level orchestration for the access-request lifecycle and graduation.
+ */
+export declare class AccessRequestService {
+    #private;
+    constructor(options: AccessRequestServiceOptions);
+    /**
+     * Initialize the backing collections (creates/verifies their tables).
+     */
+    initialize(): Promise<void>;
+    /**
+     * Static factory — construct and initialize in one call.
+     */
+    static create(options: AccessRequestServiceOptions): Promise<AccessRequestService>;
+    /**
+     * The underlying collection, for advanced read scenarios. Prefer the service
+     * methods, which apply normalization, the state machine, capability gating,
+     * and events.
+     */
+    get collection(): AccessRequestCollection;
+    /**
+     * 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.
+     */
+    createAccessRequest(input: CreateAccessRequestInput): Promise<AccessRequest>;
+    /**
+     * List access requests (operator-facing). Requires the `access-requests:read`
+     * capability when an authorizer is configured.
+     */
+    listAccessRequests(filter?: ListAccessRequestsFilter): Promise<AccessRequest[]>;
+    /**
+     * Get a single access request by id (operator-facing). Requires the
+     * `access-requests:read` capability when an authorizer is configured.
+     */
+    getAccessRequest(id: string, options?: {
+        by?: string | null;
+    }): Promise<AccessRequest | null>;
+    /**
+     * 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.
+     */
+    approveAccessRequest(id: string, options?: ApproveAccessRequestOptions): Promise<AccessRequest>;
+    /**
+     * Decline a request: `REQUESTED | APPROVED → DECLINED`. Idempotent. Requires
+     * `access-requests:manage`.
+     *
+     * @throws {@link AccessRequestError} (`INVALID_TRANSITION`) from a terminal state.
+     */
+    declineAccessRequest(id: string, options?: DeclineAccessRequestOptions): Promise<AccessRequest>;
+    /**
+     * Cancel a request: `REQUESTED | APPROVED → CANCELED`. Idempotent. Requires
+     * `access-requests:manage`.
+     *
+     * @throws {@link AccessRequestError} (`INVALID_TRANSITION`) from a terminal state.
+     */
+    cancelAccessRequest(id: string, options?: CancelAccessRequestOptions): Promise<AccessRequest>;
+    /**
+     * 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`.
+     */
+    graduateAccessRequest(id: string, options?: GraduateAccessRequestOptions): Promise<GraduateAccessRequestResult>;
+}
+//# sourceMappingURL=AccessRequestService.d.ts.map

package/dist/services/AccessRequestService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AccessRequestService.d.ts","sourceRoot":"","sources":["../../src/services/AccessRequestService.ts"],"names":[],"mappings":"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"}

package/dist/services/index.d.ts

@@ -2,6 +2,7 @@
  * Service exports for smrt-users
  * @packageDocumentation
  */
+export { ACCESS_REQUEST_CAPABILITIES, type AccessRequestAuthorizationContext, type AccessRequestAuthorizer, type AccessRequestCapability, AccessRequestError, type AccessRequestErrorCode, type AccessRequestEvent, type AccessRequestEventHandler, type AccessRequestEventType, AccessRequestService, type AccessRequestServiceOptions, type ApproveAccessRequestOptions, type CancelAccessRequestOptions, type CreateAccessRequestInput, type DeclineAccessRequestOptions, type GraduateAccessRequestOptions, type GraduateAccessRequestResult, type GraduateExistingTenantOption, type GraduateNewTenantOption, type GraduateTenantOption, type ListAccessRequestsFilter, } from './AccessRequestService.js';
 export { MagicLinkError, type MagicLinkResult, MagicLinkService, type MagicLinkServiceOptions, type MagicLinkVerifyResult, } from './MagicLinkService.js';
 export { type CreateAuthorizationUrlOptions, decodeOidcTransaction, encodeOidcTransaction, getUsersOidcConfig, type OidcCallbackResult, OidcLoginError, type OidcLoginResult, OidcLoginService, type OidcLoginServiceOptions, type OidcProviderConfig, type OidcProviderKind, type OidcProviderMetadata, type OidcProviderResolution, type OidcProviderResolutionOptions, type OidcTokenEndpointAuthMethod, type OidcTokenSet, type OidcTransaction, type ResolvedOidcProviderConfig, resolveOidcProviderConfig, type UsersOidcConfig, } from './OidcLoginService.js';
 export { type PermissionCatalog, PermissionCatalogService, type PermissionCatalogSource, type PermissionCatalogSyncResult, type PermissionDefinition, type PostgresPermissionAction, type PostgresPermissionBinding, registerPermissionDefinitions, syncPermissionCatalog, type UsersConfig, } from './PermissionCatalogService.js';

package/dist/services/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,cAAc,EACd,KAAK,eAAe,EACpB,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,GAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,6BAA6B,EAClC,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,cAAc,EACd,KAAK,eAAe,EACpB,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,EAClC,KAAK,2BAA2B,EAChC,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAC/B,yBAAyB,EACzB,KAAK,eAAe,GACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,iBAAiB,EACtB,wBAAwB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,2BAA2B,EAChC,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,6BAA6B,EAC7B,qBAAqB,EACrB,KAAK,WAAW,GACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,kBAAkB,EAClB,KAAK,iCAAiC,GACvC,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,+BAA+B,EAC/B,KAAK,mCAAmC,EACxC,6BAA6B,EAC7B,KAAK,kCAAkC,EACvC,KAAK,8BAA8B,GACpC,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,kCAAkC,EAClC,wBAAwB,EACxB,KAAK,+BAA+B,EACpC,KAAK,+BAA+B,EACpC,4BAA4B,GAC7B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,KAAK,cAAc,EACnB,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,kBAAkB,EACvB,aAAa,EACb,KAAK,yBAAyB,GAC/B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,+CAA+C,EAC/C,qCAAqC,EACrC,sCAAsC,EACtC,oCAAoC,EACpC,+BAA+B,EAC/B,iBAAiB,EACjB,0BAA0B,EAC1B,mBAAmB,EACnB,KAAK,0BAA0B,GAChC,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,2BAA2B,EAC3B,KAAK,iCAAiC,EACtC,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,kBAAkB,EAClB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAC3B,oBAAoB,EACpB,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,KAAK,4BAA4B,EACjC,KAAK,2BAA2B,EAChC,KAAK,4BAA4B,EACjC,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,GAC9B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,cAAc,EACd,KAAK,eAAe,EACpB,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,GAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,6BAA6B,EAClC,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,cAAc,EACd,KAAK,eAAe,EACpB,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,EAClC,KAAK,2BAA2B,EAChC,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAC/B,yBAAyB,EACzB,KAAK,eAAe,GACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,iBAAiB,EACtB,wBAAwB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,2BAA2B,EAChC,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,6BAA6B,EAC7B,qBAAqB,EACrB,KAAK,WAAW,GACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,kBAAkB,EAClB,KAAK,iCAAiC,GACvC,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,+BAA+B,EAC/B,KAAK,mCAAmC,EACxC,6BAA6B,EAC7B,KAAK,kCAAkC,EACvC,KAAK,8BAA8B,GACpC,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,kCAAkC,EAClC,wBAAwB,EACxB,KAAK,+BAA+B,EACpC,KAAK,+BAA+B,EACpC,4BAA4B,GAC7B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,KAAK,cAAc,EACnB,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,kBAAkB,EACvB,aAAa,EACb,KAAK,yBAAyB,GAC/B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,+CAA+C,EAC/C,qCAAqC,EACrC,sCAAsC,EACtC,oCAAoC,EACpC,+BAA+B,EAC/B,iBAAiB,EACjB,0BAA0B,EAC1B,mBAAmB,EACnB,KAAK,0BAA0B,GAChC,MAAM,0BAA0B,CAAC"}

package/dist/smrt-knowledge.json

@@ -1,14 +1,14 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-06-30T04:09:12.864Z",
+  "generatedAt": "2026-07-01T02:36:07.189Z",
   "packageName": "@happyvertical/smrt-users",
-  "packageVersion": "0.37.1",
+  "packageVersion": "0.37.2",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "b0ced21be693bf01f11fb206f171ebb40444d75aa98c4cd39eacefcd6c79e0c4",
-    "packageJson": "cc8759f2964ac8f51688704e6adf66c51e876581b27b0ea4516c2115d816d1c2",
-    "agents": "2684404a1735fd4993d4383f2dfed5f9c0f4de68f0cbfcd996f7e94eb50ac9c8"
+    "manifest": "fae4644a4f6304f9e45cd231941f0e5f197a44ec9bdf6905a3c528a589fae546",
+    "packageJson": "bd0c5070da8950403f025840c2d39f35a05789bfea1c109a04ed1cdeb50d9760",
+    "agents": "7244609f8590febc0f58df6f139e22317a1489541071ac249a5c07557b95dee3"
   },
   "exports": [
     ".",
@@ -55,6 +55,28 @@
   "tags": [],
   "risks": [],
   "objects": [
+    {
+      "name": "AccessRequestCollection",
+      "qualifiedName": "@happyvertical/smrt-users:AccessRequestCollection",
+      "collection": "accessrequests",
+      "tableName": "access_requests",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "findByEmail",
+        "findByStatus",
+        "findOpen",
+        "findOpenByEmail"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "UsersCliAuthRequestCollection",
       "qualifiedName": "@happyvertical/smrt-users:UsersCliAuthRequestCollection",
@@ -414,6 +436,98 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "AccessRequest",
+      "qualifiedName": "@happyvertical/smrt-users:AccessRequest",
+      "collection": "accessrequests",
+      "tableName": "access_requests",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "email",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "name",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "source",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "requestContext",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "note",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "requestedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "decidedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "decidedBy",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "resultingUserId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "tenantHint",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [],
+      "methods": [
+        "getRequestContext",
+        "getTenantHint",
+        "isApproved",
+        "isOpen",
+        "isTerminal",
+        "setRequestContext",
+        "setTenantHint"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "UsersCliAuthRequest",
       "qualifiedName": "@happyvertical/smrt-users:UsersCliAuthRequest",
@@ -2739,7 +2853,7 @@
     "junctionCollections": 0,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 47
+    "uuidColumns": 49
   },
-  "agentDoc": "# @happyvertical/smrt-users\n\nMulti-tenant user management with RBAC, hierarchical tenants, session handling, and SvelteKit integration.\n\n## Models (13)\n\n| Model | Key Pattern |\n|-------|-------------|\n| User | Auth identity. `profileId` is plain string (not FK) to smrt-profiles. Email auto-lowercased. |\n| Tenant | **STI** + hierarchical parent-child. `hierarchyPath` (materialized path), `hierarchyLevel`. Max depth 10. |\n| Session | Server-side. Secure UUID. TTL in **seconds** (not ms). Status auto-updates to EXPIRED on access. |\n| MagicLinkToken | Single-use email login token. Backed by `MagicLinkService`. |\n| Role | `tenantId = null` → system role (available to all tenants). `isSystem: true` blocks deletion. |\n| Permission | Slug format: `resource.action`. Parsed by PermissionResolver. |\n| Membership | User + Tenant + Role junction. UNIQUE(userId, tenantId). |\n| Group | Team within a tenant. Multiple roles via GroupRole. |\n| GroupMember, GroupRole, RolePermission | Join tables. |\n| MembershipOverride | Per-user permission grant/deny. **DENY always wins.** |\n| TenantPermissionOverride | Tenant-level cascade overrides. Effect: INHERIT/GRANT/DENY. |\n\n## Permission Resolution — Precedence (broad → specific, most-specific wins)\n\n`PermissionResolver.resolvePermissions` builds the effective set in this order;\neach later layer overrides earlier ones:\n\n1. **Tenant-inherited** — walk ancestors, apply each `TenantPermissionOverride`\n   down the cascade (GRANT adds, DENY removes within the hierarchy)\n2. **Membership role** — base permissions from the user's role in the tenant\n3. **Group roles** — permissions from all groups the user belongs to **in that tenant**\n4. **Tenant-level DENY** *(removes; overrides role/group grants, tenant-wide)* — a\n   `TenantPermissionOverride` with effect `DENY` is a HARD, tenant-wide block: it\n   subtracts the DENY'd slug even if a role or group granted it (steps 2–3). It\n   sits just **above** the per-user membership overrides and **below** role/group.\n5. **Membership GRANT override** *(re-adds; most specific)* — a per-user GRANT can\n   re-add a slug a tenant DENY'd in step 4, because it is more specific.\n6. **Membership DENY override** *(absolute; always wins)* — a per-user DENY removes\n   the slug last and is never overridden.\n\nSo a permission a role grants but the tenant DENYs is **removed**, unless that\nexact user also has a membership-GRANT override for it. A membership-DENY always\nwins. Tenant-DENY of an inherited/cascade grant still blocks it (unchanged).\nThe hard block reflects the tenant cascade's **net** resolution, not an\nunconditional union of every DENY in the chain — so a more-specific tenant GRANT\n(e.g. a child sub-tenant re-granting a permission its parent DENYs) still wins.\n\n**Critical**: `getGroupIdsForTenant(userId, tenantId)` (joins with groups table to scope by tenant). Never use `getGroupIds()` — it's cross-tenant.\n\n## Hierarchical Tenants\n\n- `TenantCollection.createChild()` auto-calculates hierarchy fields, enforces depth limit\n- `moveToParent()` updates tenant + ALL descendants' paths/levels\n- `cascadePermissions` (parent pushes down) + `inheritPermissions` (child accepts) — both must be true\n- `getTree(rootId?)` returns nested structure for UI\n\n## SvelteKit Integration\n\n```typescript\n// hooks.server.ts\nexport const handle = createSessionHandler({ db, ttl: 604800, skipPaths: ['/api/public'] });\n// Populates event.locals: { user, membership, permissions: string[], tenantId, sessionId }\n\n// +page.server.ts\nawait createSessionCookie(event, userId, tenantId, { db });\nawait destroySessionCookie(event, { db });\nawait switchSessionTenant(event, tenantId, { db });\n```\n\n## Security (S5 #1400)\n\n- **Generated REST/MCP surface is READ-ONLY for every RBAC/identity model.**\n  User, Tenant, Group, Membership, MembershipOverride, Role, Permission,\n  RolePermission, GroupRole, GroupMember, and TenantPermissionOverride generate\n  `list`/`get` only — `create`/`update`/`delete` are intentionally NOT\n  generated. The merged `requireRouteAuth` gate (#1540) enforces *authentication*,\n  not *authorization*, and these models are not `@TenantScoped`, so an\n  auto-generated mutating route would let any authenticated user self-grant a\n  role/permission, flip a tenant's cascade flags, or change another user's auth\n  identity. Mutate them through the permission-gated services (`TenantService`,\n  collection helpers) or consumer-owned, permission-checked handlers. A\n  structural regression test (`security-audit-1400.test.ts`) enumerates the\n  registry to assert no authority model exposes a mutating op. (`cli` stays\n  enabled — local-operator surface, outside the network/agent threat model.)\n- **`switchTenant` is fail-closed AND rotates the session id.**\n  `SessionService.switchTenant` / `switchSessionTenant` verify the session's user\n  has an ACTIVE membership in the target tenant before any write (the tenant id\n  is the isolation key for every `@TenantScoped` query). A non-member/unknown-\n  session switch returns `{ switched: false, sessionId: null, ... }` and mutates\n  nothing. On a successful switch into a NON-null tenant the session id is\n  ROTATED: a fresh `Session` (new secure id, fresh TTL, same user, new tenant,\n  device context carried over) is minted and the old session is REVOKED — so a\n  captured pre-switch id immediately stops validating, shrinking the blast radius\n  of a leaked id across a tenant boundary. `switchTenant` returns a\n  `SwitchTenantResult` (`{ switched, sessionId, session, rotated }`); callers MUST\n  persist the returned `sessionId`. `switchSessionTenant` does this for you by\n  re-setting the session cookie (preserving httpOnly/secure/sameSite) to the new\n  id. A `null` clear stays in place (no rotation, no cookie change). The\n  low-level `SessionCollection.setSessionTenant` is the UNGUARDED primitive (used\n  for the null-clear path) — never call it with an untrusted tenant id.\n- **OIDC `email_verified` is enforced.** `UserCollection.getOrCreateFromOidc`\n  refuses to provision a user when the IdP explicitly returns\n  `email_verified: false` (opt out with `{ allowUnverifiedEmail: true }`). An\n  absent claim makes no assertion and is not enforced.\n\n## Gotchas\n\n- **seedSystemRoles() required**: call `RoleCollection.seedSystemRoles()` at app init (creates owner/admin/member/viewer)\n- **PermissionResolver casts `as any`**: collections have protected constructors — known framework limitation\n- **Session TTL in seconds**: `DEFAULT_SESSION_TTL = 7 * 24 * 60 * 60` (not milliseconds)\n- **Users are cross-tenant**: one user, many tenants via Membership. Email globally unique.\n- **Batch permission queries**: resolver fetches all permission IDs in one query, then maps to slugs (avoids N+1)\n"
+  "agentDoc": "# @happyvertical/smrt-users\n\nMulti-tenant user management with RBAC, hierarchical tenants, session handling, and SvelteKit integration.\n\n## Models (14)\n\n| Model | Key Pattern |\n|-------|-------------|\n| User | Auth identity. `profileId` is plain string (not FK) to smrt-profiles. Email auto-lowercased. |\n| AccessRequest | \"Request access / waitlist\" record captured before a `User` exists. CLOSED generated surface (`api`/`mcp`/`cli` = `[]`) — all access via `AccessRequestService`. Email normalized + indexed; JSON `requestContext` (NOT `context` — reserved for slug scoping). |\n| Tenant | **STI** + hierarchical parent-child. `hierarchyPath` (materialized path), `hierarchyLevel`. Max depth 10. |\n| Session | Server-side. Secure UUID. TTL in **seconds** (not ms). Status auto-updates to EXPIRED on access. |\n| MagicLinkToken | Single-use email login token. Backed by `MagicLinkService`. |\n| Role | `tenantId = null` → system role (available to all tenants). `isSystem: true` blocks deletion. |\n| Permission | Slug format: `resource.action`. Parsed by PermissionResolver. |\n| Membership | User + Tenant + Role junction. UNIQUE(userId, tenantId). |\n| Group | Team within a tenant. Multiple roles via GroupRole. |\n| GroupMember, GroupRole, RolePermission | Join tables. |\n| MembershipOverride | Per-user permission grant/deny. **DENY always wins.** |\n| TenantPermissionOverride | Tenant-level cascade overrides. Effect: INHERIT/GRANT/DENY. |\n\n## Permission Resolution — Precedence (broad → specific, most-specific wins)\n\n`PermissionResolver.resolvePermissions` builds the effective set in this order;\neach later layer overrides earlier ones:\n\n1. **Tenant-inherited** — walk ancestors, apply each `TenantPermissionOverride`\n   down the cascade (GRANT adds, DENY removes within the hierarchy)\n2. **Membership role** — base permissions from the user's role in the tenant\n3. **Group roles** — permissions from all groups the user belongs to **in that tenant**\n4. **Tenant-level DENY** *(removes; overrides role/group grants, tenant-wide)* — a\n   `TenantPermissionOverride` with effect `DENY` is a HARD, tenant-wide block: it\n   subtracts the DENY'd slug even if a role or group granted it (steps 2–3). It\n   sits just **above** the per-user membership overrides and **below** role/group.\n5. **Membership GRANT override** *(re-adds; most specific)* — a per-user GRANT can\n   re-add a slug a tenant DENY'd in step 4, because it is more specific.\n6. **Membership DENY override** *(absolute; always wins)* — a per-user DENY removes\n   the slug last and is never overridden.\n\nSo a permission a role grants but the tenant DENYs is **removed**, unless that\nexact user also has a membership-GRANT override for it. A membership-DENY always\nwins. Tenant-DENY of an inherited/cascade grant still blocks it (unchanged).\nThe hard block reflects the tenant cascade's **net** resolution, not an\nunconditional union of every DENY in the chain — so a more-specific tenant GRANT\n(e.g. a child sub-tenant re-granting a permission its parent DENYs) still wins.\n\n**Critical**: `getGroupIdsForTenant(userId, tenantId)` (joins with groups table to scope by tenant). Never use `getGroupIds()` — it's cross-tenant.\n\n## Hierarchical Tenants\n\n- `TenantCollection.createChild()` auto-calculates hierarchy fields, enforces depth limit\n- `moveToParent()` updates tenant + ALL descendants' paths/levels\n- `cascadePermissions` (parent pushes down) + `inheritPermissions` (child accepts) — both must be true\n- `getTree(rootId?)` returns nested structure for UI\n\n## SvelteKit Integration\n\n```typescript\n// hooks.server.ts\nexport const handle = createSessionHandler({ db, ttl: 604800, skipPaths: ['/api/public'] });\n// Populates event.locals: { user, membership, permissions: string[], tenantId, sessionId }\n\n// +page.server.ts\nawait createSessionCookie(event, userId, tenantId, { db });\nawait destroySessionCookie(event, { db });\nawait switchSessionTenant(event, tenantId, { db });\n```\n\n## Security (S5 #1400)\n\n- **Generated REST/MCP surface is READ-ONLY for every RBAC/identity model.**\n  User, Tenant, Group, Membership, MembershipOverride, Role, Permission,\n  RolePermission, GroupRole, GroupMember, and TenantPermissionOverride generate\n  `list`/`get` only — `create`/`update`/`delete` are intentionally NOT\n  generated. The merged `requireRouteAuth` gate (#1540) enforces *authentication*,\n  not *authorization*, and these models are not `@TenantScoped`, so an\n  auto-generated mutating route would let any authenticated user self-grant a\n  role/permission, flip a tenant's cascade flags, or change another user's auth\n  identity. Mutate them through the permission-gated services (`TenantService`,\n  collection helpers) or consumer-owned, permission-checked handlers. A\n  structural regression test (`security-audit-1400.test.ts`) enumerates the\n  registry to assert no authority model exposes a mutating op. (`cli` stays\n  enabled — local-operator surface, outside the network/agent threat model.)\n- **`switchTenant` is fail-closed AND rotates the session id.**\n  `SessionService.switchTenant` / `switchSessionTenant` verify the session's user\n  has an ACTIVE membership in the target tenant before any write (the tenant id\n  is the isolation key for every `@TenantScoped` query). A non-member/unknown-\n  session switch returns `{ switched: false, sessionId: null, ... }` and mutates\n  nothing. On a successful switch into a NON-null tenant the session id is\n  ROTATED: a fresh `Session` (new secure id, fresh TTL, same user, new tenant,\n  device context carried over) is minted and the old session is REVOKED — so a\n  captured pre-switch id immediately stops validating, shrinking the blast radius\n  of a leaked id across a tenant boundary. `switchTenant` returns a\n  `SwitchTenantResult` (`{ switched, sessionId, session, rotated }`); callers MUST\n  persist the returned `sessionId`. `switchSessionTenant` does this for you by\n  re-setting the session cookie (preserving httpOnly/secure/sameSite) to the new\n  id. A `null` clear stays in place (no rotation, no cookie change). The\n  low-level `SessionCollection.setSessionTenant` is the UNGUARDED primitive (used\n  for the null-clear path) — never call it with an untrusted tenant id.\n- **OIDC `email_verified` is enforced.** `UserCollection.getOrCreateFromOidc`\n  refuses to provision a user when the IdP explicitly returns\n  `email_verified: false` (opt out with `{ allowUnverifiedEmail: true }`). An\n  absent claim makes no assertion and is not enforced.\n\n## Gotchas\n\n- **seedSystemRoles() required**: call `RoleCollection.seedSystemRoles()` at app init (creates owner/admin/member/viewer)\n- **PermissionResolver casts `as any`**: collections have protected constructors — known framework limitation\n- **Session TTL in seconds**: `DEFAULT_SESSION_TTL = 7 * 24 * 60 * 60` (not milliseconds)\n- **Users are cross-tenant**: one user, many tenants via Membership. Email globally unique.\n- **Batch permission queries**: resolver fetches all permission IDs in one query, then maps to slugs (avoids N+1)\n"
 }

package/dist/sveltekit.js

@@ -1,4 +1,4 @@
-import { O as OidcLoginError, h as DEFAULT_SESSION_TTL, Z as withSessionPermissionContext, H as TerminalAuthRateLimitError, F as TerminalAuthError, Y as resolveOidcProviderConfig, u as OidcLoginService, N as encodeOidcTransaction, X as getUsersOidcConfig, L as decodeOidcTransaction, I as TerminalAuthService, z as SessionService } from "./chunks/TerminalAuthService-bY1oWeAh.js";
+import { O as OidcLoginError, j as DEFAULT_SESSION_TTL, Z as withSessionPermissionContext, I as TerminalAuthRateLimitError, H as TerminalAuthError, Y as resolveOidcProviderConfig, v as OidcLoginService, N as encodeOidcTransaction, X as getUsersOidcConfig, L as decodeOidcTransaction, J as TerminalAuthService, A as SessionService } from "./chunks/TerminalAuthService-DcgimQYo.js";
 import { createLogger } from "@happyvertical/logger";
 import { ObjectRegistry } from "@happyvertical/smrt-core";
 import { classnameToTablename } from "@happyvertical/smrt-core/utils";

package/dist/types/index.d.ts

@@ -2,7 +2,7 @@
  * Type definitions for smrt-users
  * @packageDocumentation
  */
-export { MembershipStatus, OverrideEffect, SessionStatus, TenantPermissionEffect, TenantStatus, UserStatus, } from '@happyvertical/smrt-types';
+export { AccessRequestStatus, MembershipStatus, OverrideEffect, SessionStatus, TenantPermissionEffect, TenantStatus, UserStatus, } from '@happyvertical/smrt-types';
 /**
  * Default system role slugs
  */

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,sBAAsB,EACtB,YAAY,EACZ,UAAU,GACX,MAAM,2BAA2B,CAAC;AAInC;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;EAqBhB,CAAC;AAEX,MAAM,MAAM,eAAe,GACzB,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC;AAI/D;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,CAAC;AAEpE;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,kBAAkB;IAClB,IAAI,EAAE,gBAAgB,CAAC;IAEvB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IAEnB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,YAInC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,sBAAsB,EACtB,YAAY,EACZ,UAAU,GACX,MAAM,2BAA2B,CAAC;AAInC;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;EAqBhB,CAAC;AAEX,MAAM,MAAM,eAAe,GACzB,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC;AAI/D;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,CAAC;AAEpE;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,kBAAkB;IAClB,IAAI,EAAE,gBAAgB,CAAC;IAEvB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IAEnB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,YAInC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-users",
-  "version": "0.37.1",
+  "version": "0.37.2",
   "description": "Multi-tenant user management for the SMRT framework - users, tenants, roles, permissions, groups",
   "type": "module",
   "smrtRawPrimitives": "strict",
@@ -43,12 +43,12 @@
   "dependencies": {
     "@happyvertical/logger": "^0.74.10",
     "jose": "^6.1.3",
-    "@happyvertical/smrt-config": "0.37.1",
-    "@happyvertical/smrt-profiles": "0.37.1",
-    "@happyvertical/smrt-tenancy": "0.37.1",
-    "@happyvertical/smrt-core": "0.37.1",
-    "@happyvertical/smrt-ui": "0.37.1",
-    "@happyvertical/smrt-types": "0.37.1"
+    "@happyvertical/smrt-profiles": "0.37.2",
+    "@happyvertical/smrt-config": "0.37.2",
+    "@happyvertical/smrt-core": "0.37.2",
+    "@happyvertical/smrt-tenancy": "0.37.2",
+    "@happyvertical/smrt-types": "0.37.2",
+    "@happyvertical/smrt-ui": "0.37.2"
   },
   "devDependencies": {
     "@happyvertical/sql": "^0.74.10",
@@ -61,7 +61,7 @@
     "typescript": "^5.9.3",
     "vite": "^7.3.6",
     "vitest": "^4.0.17",
-    "@happyvertical/smrt-vitest": "0.37.1"
+    "@happyvertical/smrt-vitest": "0.37.2"
   },
   "keywords": [
     "smrt",