@openlup/platform 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -8,6 +8,46 @@ SemVer promise.
 
 ## [Unreleased]
 
+## [0.16.0]
+
+- Publishable on the npm `latest` dist-tag as `0.16.0`, from tag
+  `openlup-platform-v0.16.0`.
+
+- Add the experimental identity capability at `./identity` and browser-safe
+  `./identity/contracts`: role-based authorization, actor-scoped profiles,
+  bounded normalized contact matching, unconfirmed soft accounts with explicit
+  email-trust policies, and configured-origin magic-link redirect resolution.
+- Add operator invitations with transactional pending acceptance, expiry,
+  cancellation and revoked re-invitation for direct stores, and immediate active
+  membership with repeat/concurrent recovery for managed stores. Direct operator
+  login uses single-use email challenges, operator-audience sessions, live
+  membership authorization, explicit first-administrator bootstrap and bounded
+  challenge pruning. An opt-in OIDC access-token verifier provides pinned issuer
+  discovery, bounded rotating JWKS, strict claim validation and deterministic
+  issuer/subject principals for direct composition.
+- Add versioned personal-data contributors, identity export and transactional
+  direct erasure with contributor vetoes, challenge/invitation cleanup,
+  pseudonymization, guarded operator revocation and idempotent receipts. Managed
+  export reports incomplete coverage; managed erasure refuses with
+  `MANAGED_PRIVACY_ERASURE_UNAVAILABLE` without mutation. Issued tokens may remain
+  valid until expiry.
+- Add seven byte-identical identity SQL projections and host-selected module
+  schema readiness. The projections retain canonical migration identities and
+  positions; they are not a standalone installation chain.
+
+Migration: identity adoption is opt-in; upgrade the complete package set together
+for the exact `@openlup/core` `0.16.0` peer pin. Supply the selected bundle's schema
+inventory, clients and delivery bindings, an explicit email-trust policy, exact
+redirect origins, a distinct operator audience and a deployment policy for
+admin, operator and privacy routes. Managed soft-account provisioning requires
+an email-trust envelope with automatic confirmation disabled and all enabled
+non-email providers declared email-verifying. Install the complete direct
+catalogue through `20261018190000_identity_privacy_erasures` before enabling
+identity; never reapply projections to an existing canonical history. Managed
+adopters need their committed chain's
+`20261018160000_identity_service_role_capabilities.sql` forward for contact linking
+and operator membership capabilities, and must supply their own erasure path.
+
 ## [0.15.0]
 
 - Publishable on the npm `latest` dist-tag as `0.15.0`, from tag

package/README.md

@@ -6,7 +6,7 @@ It holds the runnable server substrate an OpenLup application composes: the Node
 
 ## Package surface
 
-`release-gates.json` declares kind `rail`: this foundation provides runtime infrastructure over core ports, matching the architecture's rail responsibility. Its nine experimental entries each bind a declaration snapshot and package-owned smoke tests. The API checker reads this same inventory.
+`release-gates.json` declares kind `rail`: this foundation provides runtime infrastructure over core ports, matching the architecture's rail responsibility. Its eleven experimental entries each bind a declaration snapshot and package-owned smoke tests. The API checker reads this same inventory.
 
 | Export | Contents |
 | --- | --- |
@@ -19,6 +19,8 @@ It holds the runnable server substrate an OpenLup application composes: the Node
 | `./job-ledger` | The job-run ledger port, its PostgreSQL and managed (Supabase) adapters, the managed v2/v3 compatibility calls and the location of its SQL |
 | `./kernel` | The bundle identifiers, descriptors and readiness |
 | `./composition` | `createBundleComposer`, the Node HTTP binding helpers and `createNodeHost` |
+| `./identity` | Experimental capability: identity engine, authorization, profile readers, session adapters and BFF factories |
+| `./identity/contracts` | Experimental capability: browser-safe customer auth port, value types and provider parser |
 
 ## Scheduled jobs
 
@@ -83,7 +85,32 @@ failed HEAD; use an upload or list operation to observe an S3 loading refusal.
 
 This package's tests are part of the repository's required test selection; from this directory, `npm test` runs them alone. The tests rewrite the originating application's characterization with neutral names and synthetic data, and a boundary test refuses any environment read or provider import in the package source.
 
-`npm run api:check` compares each of the nine declaration entry graphs with the
+The module-boundary proof permits one optional `./<module>/contracts` export
+only when that module declares `contracts: true` in `PLATFORM_MODULE_GRAPH` in
+[`eslint.config.js`](../../eslint.config.js). Its `types`, `import` and `default`
+targets follow the module entry shape at `dist/<module>/contracts/index`.
+Contracts files may import only their own contracts subtree through canonical
+relative `.js` paths and exact public `@openlup/core` entries. Both ESLint and
+[`packageBoundary.test.ts`](test/packageBoundary.test.ts) enforce this allowlist
+for static imports and re-exports (including types) and literal `import()`;
+they refuse non-literal `import()` targets. Both checks reserve the identifier
+names `require`, `module`, `exports`, `process`, `globalThis`, `global`,
+`__dirname`, `__filename` and `Buffer` in every value and type position,
+including local and property identifiers, and refuse every use of `import.meta`.
+This rejects loader aliases and wrapped calls regardless of the load target.
+The existing non-literal `require` member-call guard also remains, including
+computed property calls.
+The package test additionally requires every file in the contracts subtree to
+be a scanned `.ts` file, refuses triple-slash type and path references and all
+meta-properties (also `new.target`), and retains member-call `require` detection
+outside contracts. Identity declares this entry; synthetic graphs also exercise these checks.
+
+
+The job-run ledger SQL asset test verifies a readable, nonempty file within the
+package SQL directory. Its SQL parity tests bind the actual adapter calls to the
+shipped routine signatures; the asset's explanatory header may be edited freely.
+
+`npm run api:check` compares each of the eleven declaration entry graphs with the
 committed `api/*.api.md` reports. After building, deliberately regenerate them
 with `node --experimental-strip-types ./scripts/api-contract.ts --update` from
 this package, and review the declaration changes.
@@ -120,7 +147,327 @@ phase redirects npm to an empty temporary cache.
 
 The composition declarations describe the injected Supabase factory structurally;
 they do not import the data entry or its PostgreSQL types. The cold proof still
-requires all five nonadapter entries to import in fresh processes and compile
+requires all six nonadapter entries (including `./identity/contracts`) to import in fresh processes and compile
 in both resolution modes with all three optional peers absent.
 
 <!-- openlup-doc-impact {"unit":"platform-substrate","digest":"sha256-00994d288cfec0c8dc0ae9aeae2ff542e2e9af2fedcb4dd2dfeb6c99523be92d","reason":"The manifest moves to the 0.15.0 set version with the exact @openlup/core 0.15.0 peer pin. The package surface, settings and verification described here are unchanged by this preparation delta."} -->
+
+## Identity import candidate
+
+The OIDC API adds `createOidcIdentityVerifier`,
+`deriveOidcPrincipalId`, `createPostgresAccountLinkStore` and
+`identityOidcReadiness` from `@openlup/platform/identity`, which also exports
+`OIDC_FAILURE_CODES` and `OidcFailureCode` for hosts. The browser-shared
+`@openlup/platform/identity/contracts` entry excludes OIDC refusals.
+Inject the host's selected JWT library through `IdentityJwtLibraryLoader`.
+Discovery and rotating keys load only on verification or readiness. The opt-in
+direct composition uses normal reconcile with an explicit email-trust policy,
+authenticated actor reads and live operator membership. Managed storage requires
+native federation sessions and refuses raw upstream-token composition. Run
+`node tests/postgres/runOidcIdentityConformance.mjs` from the repository root with
+its cached pinned issuer and local prerequisites; the [OIDC recipe](../../docs/platform/IDENTITY.md#real-issuer-oidc-recipe)
+owns timing, refusal, session and certification boundaries. There is no schema or
+default login flow change; existing static session verification and default
+reference/browser flows retain their runtime behaviour.
+
+The existing `IdentityJwtLibrary.jwtVerify` contract widens with optional
+`currentDate?: Date` and `clockTolerance?: number` verify options and now returns
+`{ payload: IdentityJwtClaims }`, whose claims interface includes a string index
+signature. **Migration:** hosts implementing or typing their own
+`IdentityJwtLibrary` or `IdentityJwtLibraryLoader` must accept the optional verify
+options and return claims as `IdentityJwtClaims`.
+
+The direct operator API adds `createPostgresOperatorIdentityStore`,
+`createOperatorSessionService`, `createOperatorIdentityVerifier`,
+`createOperatorAdminAuth` and `createOperatorAuthHandlers` to `./identity`.
+`./identity/contracts` exposes strict operator challenge/session schemas and
+`OperatorBrowserAuthPort` without a server or provider import. Challenge delivery
+and session signing use the existing structural ports. Operator handlers send
+the padded generic acceptance before awaiting mailbox delivery, keeping delivery
+latency out of the response. Custom HTTP composition uses the session service's
+optional acceptance callback for the same ordering. Restoration reads preserve
+in-flight browser redemption; explicit sign-out still cancels it. Active operator
+login needs no pending invitation and preserves membership and invitation history. The new store's public
+signature exposes no driver types and loads its optional driver only on use.
+
+Apply the complete direct catalogue through position 68 before enabling human
+login; `sql/20261018180000_identity_operator_challenges.sql` is its exact projection.
+Configure a distinct operator audience and an adopter deployment route policy:
+the public policy refuses all mounted operator routes, including `me`, with
+`adopter_policy_required` before input or authentication-binding construction. The reference dispatcher accepts a
+session-binding factory through `createReferenceBffDispatch`; use it to compose
+separate operator delivery. Caller-supplied operator handlers retain the same
+policy boundary. The browser hook consumes guarded auth-port notifications rather
+than signing out from a stale post-redemption check. Use the
+explicit bootstrap/prune commands in the [identity guide](../../docs/platform/IDENTITY.md#direct-human-login).
+The bounded reference browser builds do not mount the admin shell; application
+composition must mount the provided pages and hook. First redemption activates the existing invitation and consumes the challenge in
+one transaction. Live membership, not a JWT role, authorizes each request. The
+cold consumer includes both identity entries and the new adapter's missing-peer
+refusal; real concurrency and upgrade proof needs the complete PostgreSQL chain.
+
+Creating a client/contact records commerce contact data, not an authentication
+identity. Creating an auth user provisions a principal. Neither a typed address
+nor a soft-account link proves mailbox ownership; reconcile may create a contact
+for an existing authenticated principal without creating that principal.
+
+Customer soft-account provisioning now creates unconfirmed auth users
+(`email_confirm:false`). The soft-account linker retains create-first lookup,
+normalized duplicate recovery and conditional linking. Checkout and paid-order
+retry are adopter composition that must call the linker. Failed links retain
+the provisioned identity for retry. Customer magic links keep
+`shouldCreateUser:false`: captured mailbox proof confirms that existing user;
+unknown addresses cannot sign themselves up through this path.
+
+The managed link store requires an injected `emailTrustPolicy`, assessed before
+creation or linking an existing identity by email. Unsafe or unavailable settings
+return a non-fatal soft-account refusal (`EMAIL_TRUST_ENVELOPE_REFUSED` or
+`EMAIL_TRUST_SETTINGS_UNAVAILABLE`) without creating an identity or link. Matching
+existing links retain their replay behaviour. The reference adapter binds managed
+settings assessment regardless of the selected bundle.
+
+**Migration:** soft-account provisioning requires a trusted envelope: automatic
+email confirmation disabled and every enabled non-email provider explicitly
+declared email-verifying. Automatic signup can otherwise confirm an unconfirmed
+user and issue a session to someone who merely knows the contact's address.
+Pass the policy to `createSupabaseClientAuthLinkStore(client, emailTrustPolicy)`;
+custom `ClientAuthLinkStore` implementations must expose `emailTrustPolicy`.
+An adopter may explicitly bind `createVerifierResultOnlyEmailTrustPolicy()` when
+its own trust boundary supplies the guarantee. Ensure the selected Auth installation can deliver and verify the
+first-login link for an existing unconfirmed user. Run the documented joint local conformance
+command after building core/platform. Existing identities, contact links,
+subscription references and migration history are not rewritten.
+
+Managed verification now requires the confirmation timestamp. Email-derived
+reconcile requires an injected `emailTrustPolicy`. Managed hosts share
+`createManagedEmailTrustPolicy` with `identityEmailTrustReadiness`; it reports
+module `identity` using core's existing codes. Hosts retaining verifier-only
+admission explicitly bind `createVerifierResultOnlyEmailTrustPolicy()`.
+See the [identity policy and migration](../../docs/platform/IDENTITY.md#responsibility-and-composition)
+for the empty provider allowlist, cache/deadline, 403/503 failures and the opt-in
+`node tests/postgres/runIdentityEnvelopeConformance.mjs --phase email-trust` and
+`node tests/postgres/runIdentityEnvelopeConformance.mjs --phase joint` prerequisites
+and conformance scope. Both phases replay the committed managed chain, including
+the identity capabilities forward, and prove association under the shipped managed
+reference grants.
+Construction and imports perform no settings read or SDK initialization.
+
+
+The `./identity` server entry imports the existing identity engine, authorization,
+profile readers, session adapters and BFF factories into one capability. Its
+`./identity/contracts` entry is declared browser-safe and currently exposes the
+customer auth port, value types and provider parser. Runtime-schema extraction
+is pending the contracts-boundary choice described in the
+[identity owner page](../../docs/platform/IDENTITY.md). Both entries remain an
+unpublished development-preview import candidate.
+
+Application composition supplies SDK clients/loaders, feature admission, redirect
+policy, rate limiting, messages, sender and deployment URLs. Factories use the
+foundation BFF envelope and accept the application's observed request-ID reader.
+The module depends only on the declared foundation entries, without changing the
+artifact's rail kind. Its schema contribution requires a host-selected inventory;
+its seven SQL files are verbatim projections at canonical positions 11, 12, 29,
+60, 67, 68 and 69, not an independent migration chain. The owner page maps the characterization
+witnesses and records the remaining evidence.
+
+Identity authorizes stored operator roles only when they are `admin` or
+`distributor`; null and unknown values return `FORBIDDEN` (HTTP 403). The reference
+admin-profile reader reports those rows as non-admin, and admin magic links do
+not send for them while retaining the generic accepted response, padding and
+quota. Adopters needing legacy role mapping must do it in their own adapter
+before passing the role to the package; there is no package fallback option.
+
+Both managed contact stores match normalized addresses case-insensitively,
+including mixed-case stored contacts. Literal matching uses an anchored, escaped
+`imatch` database prefilter plus an exact `email.trim().toLowerCase()` comparison
+with the normalized input. Unicode regex folding alone cannot establish identity.
+Both lookups select email and fetch at most ten candidates. Soft linking selects
+the oldest accepted contact; reconciliation requires a single accepted contact
+and throws the existing multiple-row error if several remain. A match beyond the
+candidate bound is not selected. Injected structural query clients must implement
+`filter(column, "imatch", value)` and the bounded array query. The direct customer
+challenge already compares `lower(email)` to normalized input; no migration is
+needed.
+
+Magic-link factories default to the shared strict origin resolver. Pass
+`redirectOrigins: ["https://example.com", "https://secondary.example.com:8443"]`;
+the first configured origin builds the callback and every entry must be an exact
+HTTP(S) origin, without credentials, a path, query or fragment (a root trailing
+slash is accepted). Request headers never authorize an origin. Missing or invalid
+configuration returns BFF `UPSTREAM_UNAVAILABLE` (503), with details reason
+`magic_link_origin_not_configured`, before provider access. Customer `returnTo`
+is normalized to a same-origin relative path; unsafe targets are omitted for the
+callback's default landing page. An adopter needing its existing policy can keep
+passing `resolveOrigin`; that explicit injection overrides the default. See the
+[identity redirect contract](../../docs/platform/IDENTITY.md#magic-link-redirect-policy)
+for reference configuration and migration.
+
+
+### Operator invitations
+
+`identity/contracts` exposes distinct direct pending-invitation and managed
+active-membership results. Matching runtime schemas remain in the server entry.
+The admin-action port returns `OperatorInviteResult`, a union of those results.
+
+`createDirectOperatorInvitationStore` provides the new pending, active, expired and
+revoked lifecycle in its trusted PostgreSQL transaction lane, including ordered
+membership locks and atomic membership/audit writes. Direct callers inject the
+store and a parsed TTL. `createDirectOperatorIdentityDirectory` commits principal
+creation/reuse separately. Apply the complete direct catalogue through position
+67; the byte-identical package projection is for inspection and composition, not
+a standalone fresh chain. Direct human acceptance is a trusted command,
+unmounted from machine authentication.
+
+Managed hosts use `createInviteAdminUserGateway().activateMembership` in
+`runInviteAdminUserUseCase`. Insertion immediately creates active `admin_users`
+membership with invitation provenance; it omits `is_machine_actor` and relies on
+the database default false. The result carries principal ID, role, active state
+and `MEMBERSHIP_CREATED` or `ALREADY_ACTIVE`, without pending timestamps or an
+invitation ID. Identical repeats and concurrent insert losers return the existing
+membership without a second notification. Role differences conflict; revoked
+members refuse with `MANAGED_REINVITE_UNSUPPORTED`. Failures retain identities
+for retry, including after notification failure. No Auth metadata store,
+first-entry acceptance, expiry or compensation is used. Magic-link eligibility
+requires active membership and a known role. Authorization, removal and admin
+`me` retain their actor bindings without a service key for lifecycle state.
+
+**Migration:** direct hosts can adopt the new pending lifecycle by applying
+`20261018120000_identity_operator_invitations` after the existing direct catalogue
+and composing the store, trusted human acceptance and parsed TTL. Existing
+memberships are preserved. Managed immediate activation is retained; managed
+consumers must now parse the structured active result and its
+`MEMBERSHIP_CREATED`/`ALREADY_ACTIVE` codes instead of message-only success.
+Duplicates return existing membership rather than `ALREADY_ADDED`, and
+notification failure returns 503 `INVITATION_NOTIFICATION_FAILED` while keeping
+membership active. Managed pending/expiry remains a compatibility gap requiring
+a separate transactional store and reviewed forward. No managed SQL, RPC or SDK
+dependency is added. See the
+[identity lifecycle owner](../../docs/platform/IDENTITY.md#operator-invitation-lifecycle).
+
+The managed chain's identity capabilities forward
+`20261018160000_identity_service_role_capabilities.sql` grants `service_role`
+SELECT(email) and INSERT(id, email, role, membership_state, membership_provenance,
+membership_accepted_at) on `admin_users`.
+The opt-in managed conformance replays the complete committed chain with ambient
+default ACLs removed and adds no grant. It proves immediate activation,
+repeat/concurrent recovery and revoked-member refusal under the shipped grants.
+It does not establish managed/direct lifecycle parity.
+
+With a fresh local managed stack running, export its API URL, service key and
+PostgreSQL owner (`supabase_admin`) connection URL as `OPENLUP_MANAGED_CONFORMANCE_URL`,
+`OPENLUP_MANAGED_CONFORMANCE_SERVICE_KEY` and
+`OPENLUP_MANAGED_CONFORMANCE_DATABASE_URL`, then run from the repository root:
+
+```sh
+npm --workspace @openlup/platform run build
+node --import tsx tests/postgres/operatorInvitationManaged.conformance.ts
+```
+
+The module refuses non-loopback endpoints, an already-installed public schema,
+and existing synthetic fixture identities. It retains synthetic identities;
+discard the disposable stack after the run. Its database owner connection must
+be able to replay the committed prerequisites, baseline and ordered forwards.
+
+## Personal data
+
+The experimental identity entry exposes `createPersonalDataContributorRegistry`,
+`createIdentityPersonalDataContributor`, `createPrivacyOperations`,
+`exportPersonalData`, `erasePersonalData`, `createPrivacyExportHandler` and
+`createPrivacyEraseHandler`. Browser requests, versioned contributor documents and
+receipts come from `@openlup/platform/identity/contracts`. Register every required
+contributor explicitly, with its owned fields, assessment, erase/retain operation
+and remote/retention obligations. Missing required owners refuse erasure; export
+reports missing coverage. This capability erases identity-owned data only.
+
+Direct hosts compose `createPostgresPrivacyUnitOfWork` and
+`createPostgresPrivacyStore` with the identity contributor and their domain vetoes
+using the same executor. The reference subscriptions contributor holds a relation
+lock through commit, refusing active and paused subscriptions without changing
+them. `IdentityPrivacyPolicy.retainedContactFields` names explicit retention
+owners for populated opaque columns; unknown ownership refuses. The reference
+retains lifecycle/acquisition fields, and refuses nonempty metadata or external
+references until an owner declares their disposition.
+
+Migration: apply the complete direct catalogue including
+`20261018190000_identity_privacy_erasures` before using privacy or the updated
+customer challenge store. The forward appends one receipt table at position 69
+without grants or stored functions. Direct erasure pseudonymizes identity-owned
+fields, deletes challenges and outstanding invitations, uses guarded membership
+revocation, clears only the selected contact's direct principal link, and commits
+an idempotent audit receipt atomically. Contact IDs and managed auth links never
+change. Failed writes roll back. Retained audit references are pseudonymous, not
+an assertion of anonymization. Already-issued tokens may remain valid until expiry.
+Customer challenge issuance and redemption reject a receipt for either the
+contact or principal under the same transaction-held challenge relation lock as
+erasure, including late challenges inserted after cleanup. Hosts must use the
+package adapters; calling the retained raw challenge SQL functions directly
+bypasses this erasure receipt fence.
+
+Managed hosts compose `createManagedPrivacyStore` with their structural service
+client for export. Coverage explicitly excludes inaccessible country and
+identity history/receipt fields. Managed erasure refuses with
+`MANAGED_PRIVACY_ERASURE_UNAVAILABLE`: a managed adopter must provide its own
+erasure path. The committed grants and structural client cannot provide the
+required mutations and atomic receipt. This change adds no managed forward or
+erasure grants. Provider identity is never deleted; any future composed provider
+erasure must disable it after committed local success. The managed refusal here
+occurs before reaching any provider mutation.
+
+The reference mounts authenticated human-admin export/erase POSTs and an Admin
+Settings readback panel. Direct and managed mounts require the adopter deployment
+policy under admin mutation risk; the public default returns
+`adopter_policy_required` before body/query reads, and direct mounts also refuse
+before authentication or privacy binding construction. The shipped dispatcher mounts
+both routes for managed bundles even when its caller supplies no routes. After admission,
+exports and receipts stay in memory with no-store
+responses. The maintenance `prune-challenges` command prunes separate bounded
+operator/customer batches. See [identity privacy](../../docs/platform/IDENTITY.md#identity-personal-data)
+for refusals, token limits and retained obligations.
+
+The complete direct conformance is included in
+`ai-resource-gate run --wait openlup:coverage -- npx vitest run tests/postgres/operatorIdentityUpgrade.test.ts`.
+For managed conformance, supply the same three `OPENLUP_MANAGED_CONFORMANCE_*`
+local disposable-stack settings described for operator invitations, with
+`OPENLUP_MANAGED_CONFORMANCE_DATABASE_URL` set to the database owner
+(`supabase_admin`) connection, then run
+`node --experimental-strip-types tests/postgres/identityPrivacyManaged.conformance.ts`.
+Use a fresh public schema and reset the disposable stack between proofs; the
+managed privacy proof replays the committed chain without fixture erasure grants.
+Replay through node-postgres omits only the psql-only pg_dump `\restrict` and
+`\unrestrict` guard lines; all migration SQL remains unchanged.
+
+
+Reference startup can compose identity through `createReferenceIdentity` and
+`startPublicReferenceServer({ identity })`, with explicit route functions,
+selected adapters, trusted schema/migration observation and the bundle-specific
+inventory. It consumes email-trust readiness before listening, and rejects
+unknown or unsatisfied candidates. Direct reconcile reads the existing actor
+link; direct invite/remove select the pending-invitation stores. The default
+static reference and browser page sets remain unchanged. See the
+[composition contract](../../docs/platform/IDENTITY.md#responsibility-and-composition).
+
+Both identity entries already belong to the public export map and build output;
+artifact availability does not imply registry publication or release activation.
+The cold installed-artifact consumer imports both entries without optional peers,
+compiles contracts without driver types, and invokes every driver-owning direct
+identity adapter for its missing-peer refusal. Managed factories consume
+structural clients. Server declarations compile after peer selection. Full
+installed-artifact and database proof require the existing supervisor-run package
+consumer command and an owned disposable database.
+
+The managed identity service-role capabilities forward in the committed chain
+supplies client link writes and operator membership insert/email-read
+permissions; the local conformance runners add no fixture grant. No migration is
+added by reference composition.
+
+
+## Disposable identity composition
+
+The reference application's opt-in identity shell consumes the existing
+`./identity` and `./identity/contracts` exports without changing their maturity
+or publishing a registry version. It reuses the customer/operator pages and
+captured-delivery port, with a private local mailbox and administrator privacy
+panel. Its explicit runtime must supply actual routes and readiness admission;
+the shell refuses a missing composition. See the
+[identity reference guide](../../docs/platform/IDENTITY.md#disposable-identity-reference)
+for both-bundle commands, the committed managed grants and installation limits.

package/dist/identity/adminAuthBinding.d.ts

@@ -0,0 +1,28 @@
+import type { AdminAuthPort } from "./ports.js";
+import type { AdminAuthBinding } from "./adminPreflight.js";
+type Env = Record<string, string | undefined>;
+export interface PlatformOperatorChecker {
+    isOperatorAllowed(principalId: string): Promise<boolean>;
+    close(): Promise<void>;
+}
+export type PlatformOperatorCheckerFactory = (env: Env) => PlatformOperatorChecker | Promise<PlatformOperatorChecker>;
+export type AdminAuthBindingResolution = {
+    readonly binding: AdminAuthBinding;
+    readonly error?: undefined;
+} | {
+    readonly binding?: undefined;
+    readonly error: "managed_admin_auth_env_required" | "direct_admin_auth_config_invalid";
+};
+export interface AdminAuthBindingOptions {
+    humanAuthFactory?: (env: Env) => AdminAuthPort & {
+        close(): Promise<void>;
+    };
+    checkerFactory?: PlatformOperatorCheckerFactory;
+    managedAuthFactory?: (env: {
+        url: string;
+        anonKey: string;
+    }, accessToken: string | null) => AdminAuthPort;
+}
+/** Bind the admin authorizer selected by PLATFORM_BUNDLE. */
+export declare function createAdminAuthBindingResolver(defaults: Required<Pick<AdminAuthBindingOptions, "checkerFactory" | "managedAuthFactory">> & Pick<AdminAuthBindingOptions, "humanAuthFactory">): (env: Env, options?: AdminAuthBindingOptions) => AdminAuthBindingResolution;
+export {};

package/dist/identity/adminAuthBinding.js

@@ -0,0 +1,66 @@
+import { createOperatorTokenAdminAuth, resolvePlatformOperatorAuthConfig } from "./operatorTokenAdminAuth.js";
+import { resolveBundleId } from "../kernel/index.js";
+function managedAuthEnv(env) {
+    const url = env.SUPABASE_URL ?? env.VITE_SUPABASE_URL;
+    const anonKey = env.VITE_SUPABASE_PUBLISHABLE_KEY ?? env.VITE_SUPABASE_ANON_KEY ?? env.SUPABASE_ANON_KEY;
+    return url && anonKey ? { url, anonKey } : null;
+}
+/** Bind the admin authorizer selected by PLATFORM_BUNDLE. */
+export function createAdminAuthBindingResolver(defaults) {
+    return function resolveAdminAuthBinding(env, options = {}) {
+        const bundleId = resolveBundleId(env);
+        if (bundleId === "node-postgres") {
+            const config = resolvePlatformOperatorAuthConfig(env);
+            const humanFactory = options.humanAuthFactory ?? defaults.humanAuthFactory;
+            const humanEnabled = !!env.OPERATOR_IDENTITY_AUDIENCE && !!humanFactory;
+            if (!config.config && !humanEnabled)
+                return { error: "direct_admin_auth_config_invalid" };
+            const checkerFactory = options.checkerFactory ?? defaults.checkerFactory;
+            return {
+                binding: {
+                    identity: bundleId,
+                    async run(accessToken, work) {
+                        const scope = {};
+                        const machine = config.config ? createOperatorTokenAdminAuth(config.config, async (principalId) => {
+                            scope.checker ??= await checkerFactory(env);
+                            return scope.checker.isOperatorAllowed(principalId);
+                        }) : null;
+                        let human;
+                        const auth = { async authorize(token, restrictions) {
+                                // Only a credential mismatch may select human verification; machine
+                                // revocation and database errors retain their existing result.
+                                const result = machine ? await machine.authorize(token, restrictions) : null;
+                                if (result && (result.ok || result.code !== "UNAUTHORIZED"))
+                                    return result;
+                                if (!humanEnabled || !token)
+                                    return result ?? { ok: false, code: "UNAUTHORIZED", message: "Operator authentication required" };
+                                human ??= humanFactory(env);
+                                return human.authorize(token, restrictions);
+                            } };
+                        try {
+                            return await work(auth);
+                        }
+                        finally {
+                            try {
+                                await scope.checker?.close();
+                            }
+                            finally {
+                                await human?.close();
+                            }
+                        }
+                    },
+                },
+            };
+        }
+        const authEnv = managedAuthEnv(env);
+        if (!authEnv)
+            return { error: "managed_admin_auth_env_required" };
+        const managedAuthFactory = options.managedAuthFactory ?? defaults.managedAuthFactory;
+        return {
+            binding: {
+                identity: bundleId,
+                run: (accessToken, work) => work(managedAuthFactory(authEnv, accessToken)),
+            },
+        };
+    };
+}

package/dist/identity/adminAuthorization.d.ts

@@ -0,0 +1,34 @@
+import type { HttpResponse, HttpRequest } from "../http/index.js";
+import { type IdentityResponseOptions } from "./response.js";
+export type AdminRole = "admin" | "distributor";
+/** Authorization outcome: a resolved admin `userId`, or a typed denial. */
+export type AdminAuthorization = {
+    ok: true;
+    userId: string;
+    role: AdminRole;
+    isMachineActor: boolean;
+} | {
+    ok: false;
+    code: "UNAUTHORIZED" | "FORBIDDEN";
+    message: string;
+    identityCode?: string;
+};
+/** A request-bound thunk that resolves the calling admin (or a denial). */
+export type AuthorizeAdmin = () => Promise<AdminAuthorization>;
+export declare function authorizeAdminWithUser(rawClient: unknown, accessToken: string | null, options?: {
+    allowedRoles?: readonly AdminRole[];
+}): Promise<AdminAuthorization>;
+export declare function authorizeCommerceAdminWithUser(client: unknown, accessToken: string | null): Promise<AdminAuthorization>;
+export declare function authorizeAdminBooleanWithUser(client: unknown, accessToken: string | null, options?: {
+    allowedRoles?: readonly AdminRole[];
+}): Promise<boolean>;
+/**
+ * Shared authz gate: returns the resolved admin (`userId` + DB-derived
+ * `isMachineActor`) or sends the error envelope and returns null.
+ */
+export declare function resolveAdmin(authorizeAdmin: AuthorizeAdmin, res: HttpResponse, options?: IdentityResponseOptions): Promise<{
+    userId: string;
+    role: AdminRole;
+    isMachineActor: boolean;
+} | null>;
+export declare function readBearerToken(req: HttpRequest): string | null;

package/dist/identity/adminAuthorization.js

@@ -0,0 +1,72 @@
+import { createIdentityResponder } from "./response.js";
+export async function authorizeAdminWithUser(rawClient, accessToken, options = {}) {
+    const client = rawClient;
+    if (!accessToken) {
+        return { ok: false, code: "UNAUTHORIZED", message: "Admin session required" };
+    }
+    const { data: userData, error: userError } = await client.auth.getUser(accessToken);
+    if (userError || !userData.user) {
+        return { ok: false, code: "UNAUTHORIZED", message: "Admin session required" };
+    }
+    const { data, error } = await client
+        .from("admin_users")
+        .select("id, role, is_machine_actor")
+        .eq("id", userData.user.id)
+        .eq("membership_state", "active")
+        .maybeSingle();
+    if (error)
+        throw error;
+    if (!data) {
+        return { ok: false, code: "FORBIDDEN", message: "Admin role required" };
+    }
+    const role = normalizeAdminRole(data.role);
+    if (role === null || (options.allowedRoles && !options.allowedRoles.includes(role))) {
+        return { ok: false, code: "FORBIDDEN", message: "Admin role required" };
+    }
+    // Fail closed: mirror the activate RPC's `COALESCE(is_machine_actor, true)` — only an
+    // explicit `false` is a human actor; anything else is treated as a machine. The DB row
+    // (`admin_users.is_machine_actor`, re-derived here and in every write RPC) is the single
+    // source of truth for actor kind — never trusted from the caller.
+    return {
+        ok: true,
+        userId: userData.user.id,
+        role,
+        isMachineActor: data.is_machine_actor !== false,
+    };
+}
+export function authorizeCommerceAdminWithUser(client, accessToken) {
+    return authorizeAdminWithUser(client, accessToken, { allowedRoles: ["admin"] });
+}
+export async function authorizeAdminBooleanWithUser(client, accessToken, options = {}) {
+    const authorization = await authorizeAdminWithUser(client, accessToken, options);
+    return authorization.ok;
+}
+/**
+ * Shared authz gate: returns the resolved admin (`userId` + DB-derived
+ * `isMachineActor`) or sends the error envelope and returns null.
+ */
+export async function resolveAdmin(authorizeAdmin, res, options = {}) {
+    const { sendBffError } = createIdentityResponder(options);
+    let authz;
+    try {
+        authz = await authorizeAdmin();
+    }
+    catch {
+        sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+        return null;
+    }
+    if (authz.ok === false) {
+        sendBffError(res, authz.code, authz.message);
+        return null;
+    }
+    return { userId: authz.userId, role: authz.role, isMachineActor: authz.isMachineActor };
+}
+function normalizeAdminRole(role) {
+    return role === "admin" || role === "distributor" ? role : null;
+}
+export function readBearerToken(req) {
+    const raw = req.headers.authorization;
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    const match = value?.match(/^Bearer\s+(.+)$/i);
+    return match?.[1]?.trim() || null;
+}