@wildo-ai/saas-models 1.1.3 → 1.1.5

package/dist/esm/security/authorizations/application-access-grants.shared.schemas.js

@@ -0,0 +1,271 @@
+/**
+ * Application Access Grants — time-bound, justified, TWO-PERSON-APPROVED elevation for an operator
+ * act that names no single tenant.
+ *
+ * ## Which reads use this grant
+ *
+ * Actual application-wide grants always require a different administrator's approval. The general
+ * directory and other application-wide read gates retain that requirement. The application audit
+ * viewer instead defaults to its administrator-role gate, in production and development alike;
+ * `auditTrail.applicationReadAccess = AuditApplicationReadAccess.INDEPENDENT_APPROVAL` explicitly
+ * enrolls that viewer in this grant requirement. Role-based audit reads remain observed and do not
+ * invent a grant id. The historical diagnosis below explains the general elevation mechanism, not
+ * an assertion that every cross-tenant audit read must use it.
+ *
+ * ## The asymmetry this closes
+ *
+ * `platformAccessGrants` governs the NARROW act: one operator, one named tenant, one window. It is
+ * the door `.claude/rules/administrative-continuity-floors.md` calls rungs 4–5 of the ladder, and it
+ * works.
+ *
+ * The WIDE act was ungoverned. Measured 2026-09-09 and recorded on
+ * `ScopeRootConfinementDisposition.UNCONFINED_APPLICATION_TIER_DIRECTORY`:
+ *
+ * | | per-row crossing | application-wide read |
+ * |---|---|---|
+ * | elevation required | a usable `platformAccessGrants` row | **none** |
+ * | role tier | `APP_ADMIN_SUPER_ADMIN` | `APP_ADMIN_VIEWER` / `ORG_MEMBER` |
+ * | evidence | `CROSS_TENANT_ADMINISTRATIVE_ACCESS`, naming the grant | an observation naming no elevation |
+ *
+ * So the narrow act carried elevation and expiry and the widest read did not — and the wide one sat
+ * at a strictly LOWER role tier. That is worse than "not symmetric"; it is the control inverted.
+ *
+ * ## Why a SEPARATE resource and not a `scope` field on the tenant grant
+ *
+ * Structural, not stylistic. A `platformAccessGrants` row is ORGANIZATIONS-scoped: its primary-scope
+ * relationship carries `isPrimaryScope: true` on `organizationId`, every route is
+ * `/organizations/{organizationId}/platform-access-grants/…`, and the tenant's ability to SEE and
+ * REVOKE the row is exactly what that scope buys. An application-wide elevation names no tenant, so
+ * the route has nothing to carry and the scope has nobody to serve. Adding a nullable
+ * `organizationId` to make one row shape serve both would weaken the field whose presence IS the
+ * tenant grant's control — which the finding explicitly refuses ("do not weaken the per-row model to
+ * make the two symmetric").
+ *
+ * The engine's own precedent for a second scope over one lifecycle is `applicationAuditLogs` beside
+ * `auditLogs`: a sibling resource type carrying ONE application parent, taking the route it needs and
+ * leaving the existing door byte-identical.
+ *
+ * ## Why TWO-PERSON, and what was rejected
+ *
+ * Tenant approval is the industry ceiling (Microsoft Customer Lockbox, Google Access Approval) and it
+ * is structurally unavailable here: there is no single customer to ask. `administrative-continuity-floors.md`
+ * names the next-strongest control in as many words — *"a second factor authenticates a session; only
+ * a second signature constrains an authenticated operator"* — and asks for a two-person rule on the
+ * widest acts.
+ *
+ * Auto-approval was rejected: it is the tenant grant's default posture precisely BECAUSE a tenant can
+ * opt in above it, and there is no such party here, so an auto-approved application-wide grant would
+ * be a standing privilege with a request form in front of it.
+ *
+ * Confining the read to tenants the caller holds a grant for was rejected on MEASUREMENT rather than
+ * cost: `users` rows carry no tenant column at all, so there is nothing for a tenant predicate to
+ * bind to, and any junction-based confinement would also remove the tenant-less user — the person who
+ * has just signed up and belongs to nobody — from the only surface that can find them.
+ */
+import { z } from 'zod';
+import { ExecutionContext_MachineCredentialSchema } from '../../runtime/execution-context.shared.schemas.js';
+import { PersonalDataCategory } from '../../compliance/privacy/personal-data-category.shared.schemas.js';
+import { RedactionType } from '../../compliance/privacy/redaction.shared.schemas.js';
+import { addImpersonalizeWith } from '@wildo-ai/zod-decorators';
+import { PlatformAccessGrantStatus } from './platform-access-grants.shared.schemas.js';
+/** Fixed replacement for grant free-text that cannot be cleared (a `.min(1)` field). */
+const ERASED_GRANT_TEXT = '[erased]';
+/**
+ * The default life of an application-wide grant whose request names no duration.
+ *
+ * THIRTY minutes — half the tenant grant's default, and the halving is the point rather than a round
+ * number. A tenant grant reaches ONE customer and the customer can see and revoke it; this one
+ * reaches every customer at once and no customer can see it. The window is the only thing that ends
+ * it early, so the unconsidered case gets the narrowest window a support interaction can still use.
+ */
+export const APPLICATION_ACCESS_GRANT_DEFAULT_DURATION_MINUTES = 30;
+/**
+ * The maximum life of an application-wide grant, whatever a request asks for.
+ *
+ * ONE HOUR against the tenant grant's four. A four-hour window is defended there as "a working
+ * session, not a working week" for an elevation into one tenant; the same reasoning gives a shorter
+ * answer for an elevation into all of them. An operator who genuinely needs longer re-requests, and
+ * a second administrator signs again — which is the record we want, and the reason a shorter ceiling
+ * here costs no security and buys a second signature per hour of the widest access the system grants.
+ */
+export const APPLICATION_ACCESS_GRANT_MAXIMUM_DURATION_MINUTES = 60;
+/**
+ * Custom verbs. Mirrors `PlatformAccessGrants_Operations` deliberately — the same lifecycle,
+ * so the same verbs, so a reader who knows one knows the other.
+ *
+ * There is no ordinary CREATE/UPDATE for the same reason: they would be a second, ungated path to the
+ * server-authored fields whose server authorship IS the control.
+ */
+export var ApplicationAccessGrants_Operations;
+(function (ApplicationAccessGrants_Operations) {
+    /**
+     * The bootstrap verb. Writes one row in `PENDING_APPROVAL` and NEVER in `ACTIVE` — see
+     * the `status` field below for why auto-approval has no member here.
+     */
+    ApplicationAccessGrants_Operations["REQUEST_ACCESS"] = "requestAccess";
+    /** The SECOND administrator's signature. Refuses the requester — {@link applicationAccessGrantApproverIsDistinct}. */
+    ApplicationAccessGrants_Operations["APPROVE"] = "approve";
+    ApplicationAccessGrants_Operations["DENY"] = "deny";
+    ApplicationAccessGrants_Operations["REVOKE"] = "revoke";
+    /** ACTIVE → EXPIRED, dispatched by the credential-expiry sweep and by nothing else. */
+    ApplicationAccessGrants_Operations["EXPIRE"] = "expire";
+})(ApplicationAccessGrants_Operations || (ApplicationAccessGrants_Operations = {}));
+export const ApplicationAccessGrantSchema = z.object({
+    _id: z.string().min(1).isPrimaryKey().isSummaryField(),
+    /**
+     * The primary-scope parent — the deployment this elevation is inside.
+     *
+     * OPTIONAL, and that is a load-bearing copy of `applicationAuditLogs`' own shape rather than a
+     * looseness: declared MANDATORY the resource does not load at all on a Mongo-persisted deployment
+     * (the ZodToMongoose convertor refuses it and INIT dies on `zod_converter_schema_conversion_failed`).
+     * Addressing is carried by `isPrimaryScope` + `REQUIRES_CONTEXT` on the relationship, which is what
+     * the URL builder reads, so the route is identical either way.
+     */
+    applicationId: z.string().min(1).optional().isDBIndexed().isForeignKey().excludeFromUpdate().isAuditEvidence(),
+    /** The operator who requested the elevation. Server-authored from the session, never client-supplied. */
+    operatorUserId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    /**
+     * Why the operator needs application-wide reach. REQUIRED, like its tenant sibling, and here it
+     * carries more weight: it is the ONLY thing the approving administrator has to decide on. A tenant
+     * grant's approver knows their own tenant and their own support case; this approver knows nothing
+     * but this sentence.
+     */
+    // USER_CONTENT — free prose an OPERATOR typed. MASK rather than REMOVE on erasure: `.min(1)` makes
+    // it non-clearable, so a null would be rejected by the strict update-DTO parse the impersonalize
+    // writer runs, and a fixed non-empty string is accepted.
+    justification: addImpersonalizeWith(z.string().min(1).max(1000).isSummaryField()
+        .dataCategories(PersonalDataCategory.USER_CONTENT), RedactionType.MASK, { maskValue: ERASED_GRANT_TEXT }),
+    /**
+     * Lifecycle position, sharing {@link PlatformAccessGrantStatus} rather than declaring a parallel
+     * vocabulary — the states really are the same states, and two enums holding the same five members
+     * is how a sweep, a predicate and a UI come to disagree about what `active` means.
+     *
+     * ## The member that is UNREACHABLE here, and why that is the control
+     *
+     * Every application-wide grant starts `PENDING_APPROVAL`. There is no auto-approval path and
+     * therefore no `autoApprovalReason` field: the tenant grant auto-approves when the tenant has not
+     * opted into approval, or cannot approve — both are statements about a NAMED tenant, and this row
+     * names none. A grant that could approve itself would make the two-person rule ceremonial, which is
+     * exactly the criticism `approve` on the tenant resource carries against platform self-approval.
+     */
+    status: z.enum(PlatformAccessGrantStatus)
+        .systemEnum('PlatformAccessGrantStatus')
+        .default(PlatformAccessGrantStatus.PENDING_APPROVAL)
+        .isDBIndexed()
+        .isSummaryField()
+        .excludeFromCreate()
+        .excludeFromUpdate()
+        .isAuditEvidence(),
+    /**
+     * When the elevation stops working.
+     *
+     * Server-authored from the requested duration, clamped to
+     * {@link APPLICATION_ACCESS_GRANT_MAXIMUM_DURATION_MINUTES}. The admission predicate reads THIS
+     * field and not `status`, so expiry needs no sweeper to take effect — the same separation the
+     * tenant grant keeps, and for the same reason: if admission ever starts reading the label, a
+     * lagging sweep becomes an authorization hole rather than a stale display.
+     */
+    expiresAt: z.date().isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    /**
+     * The SECOND administrator. Present on every `ACTIVE` row, by construction.
+     *
+     * Optional in the SCHEMA because it is unset while the request is pending and stays unset on a
+     * denied or revoked one. It is not optional in the LIFECYCLE: the only writer of
+     * `status = ACTIVE` is `approve`, and `approve` refuses when this would equal `operatorUserId`.
+     * That refusal is the two-person rule, and it lives in one predicate
+     * ({@link applicationAccessGrantApproverIsDistinct}) so no second call site can re-derive it
+     * more leniently.
+     */
+    approvedByUserId: z.string().min(1).optional().isForeignKey().isSummaryField().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    approvedAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),
+    /**
+     * The ONE machine credential this elevation is for, when it is for a machine rather than the requester (#297).
+     *
+     * An application's audit read policy can require independent approval (`INDEPENDENT_APPROVAL`), and until
+     * 2026-09-13 that refused every machine outright: a grant was keyed on `operatorUserId` and a machine has no
+     * user. So the assurance collector — the reader such a policy most wants governed — could never read.
+     *
+     * When set, a HUMAN administrator requests the elevation ON BEHALF OF this credential, a second administrator
+     * signs exactly as for any other grant, and the admission admits that credential and NOBODY ELSE — in
+     * particular never the requester, who would otherwise have minted themselves a window by naming a machine.
+     * {@link applicationAccessGrantAdmits} is the one place that decision lives.
+     *
+     * Set at request time only, validated against a live application API key or OAuth client, and never updated:
+     * re-pointing a signed elevation at a different credential would be a grant nobody signed.
+     */
+    grantedMachineCredential: ExecutionContext_MachineCredentialSchema.optional().excludeFromUpdate().isAuditEvidence(),
+    /** The approver's reason for refusing, or the revoker's reason for withdrawing. */
+    // REMOVE — free text again, and clearable (`.optional()`).
+    decisionReason: addImpersonalizeWith(z.string().max(1000).optional().excludeFromCreate().excludeFromUpdate()
+        .dataCategories(PersonalDataCategory.USER_CONTENT), RedactionType.REMOVE),
+    createdAt: z.date().optional(),
+    updatedAt: z.date().optional(),
+});
+/**
+ * Clamp a requested duration to the application-wide ceiling.
+ *
+ * A deliberate near-copy of `resolvePlatformAccessGrantExpiry` rather than a shared function taking
+ * two constants: the two ceilings are two DECISIONS about two different acts, and a shared helper
+ * invites the next author to pass whichever constant is in scope. The behaviour that matters is
+ * identical and stated in both places — a longer ask is CLAMPED, never refused, because being told
+ * "ask again with a smaller number" during an incident is friction with no security benefit.
+ */
+export function resolveApplicationAccessGrantExpiry(requestedDurationMinutes, now) {
+    const requested = requestedDurationMinutes && requestedDurationMinutes > 0
+        ? requestedDurationMinutes
+        : APPLICATION_ACCESS_GRANT_DEFAULT_DURATION_MINUTES;
+    const minutes = Math.min(requested, APPLICATION_ACCESS_GRANT_MAXIMUM_DURATION_MINUTES);
+    return new Date(now.getTime() + minutes * 60_000);
+}
+/**
+ * Does this grant admit this principal?
+ *
+ * **The one decision about WHO a grant is for**, because two principals now hold grants and each reading of the
+ * row must agree:
+ *
+ *  - a grant bound to a machine credential admits exactly that credential (same method, same id) and nobody else —
+ *    not its requester, not another credential, not a human carrying no credential;
+ *  - an unbound grant admits exactly its requester, as a HUMAN: a machine principal carrying the requester's user
+ *    id is not a thing the request pipeline builds, and admitting one would be a second way for a person to lend
+ *    their elevation to a credential without a second signature naming it.
+ *
+ * Fails closed on every missing input. Usability of the WINDOW is a separate question (`isPlatformAccessGrantUsable`).
+ */
+export function applicationAccessGrantAdmits(params) {
+    const bound = params.grant.grantedMachineCredential;
+    const presented = params.principal.machineCredential;
+    if (bound) {
+        return Boolean(presented && presented.credentialId && presented.credentialId === bound.credentialId && presented.authMethod === bound.authMethod);
+    }
+    if (presented)
+        return false;
+    const userId = String(params.principal.userId ?? '');
+    return Boolean(userId) && String(params.grant.operatorUserId ?? '') === userId;
+}
+/**
+ * Is this approver a DIFFERENT person from the operator who asked?
+ *
+ * **This predicate is the two-person rule.** Everything else about an application-wide grant — the
+ * request, the window, the justification, the audit row — exists in the tenant grant too. What is new
+ * here is exactly this comparison, so it is named, exported, and asked in ONE place.
+ *
+ * ## Why it is a predicate and not an inline `!==`
+ *
+ * Three call sites would otherwise each write their own comparison, and two of the three ways to
+ * write it are wrong in the same direction:
+ *
+ *  - an approver id that is ABSENT must NOT pass. An unauthenticated or system-context approval has
+ *    no second person behind it, and `undefined !== 'operator'` is `true` — the inline form fails
+ *    OPEN on precisely the input a broken context supplies;
+ *  - an operator id that is absent must not pass either, for the mirror reason.
+ *
+ * So the predicate requires BOTH ids to be present and different. Fails closed on everything else.
+ */
+export function applicationAccessGrantApproverIsDistinct(params) {
+    const operator = String(params.operatorUserId ?? '');
+    const approver = String(params.approverUserId ?? '');
+    if (!operator || !approver)
+        return false;
+    return operator !== approver;
+}
+//# sourceMappingURL=application-access-grants.shared.schemas.js.map

package/dist/esm/security/authorizations/application-access-grants.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-access-grants.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/security/authorizations/application-access-grants.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Application Access Grants — time-bound, justified, TWO-PERSON-APPROVED elevation for an operator\n * act that names no single tenant.\n *\n * ## Which reads use this grant\n *\n * Actual application-wide grants always require a different administrator's approval. The general\n * directory and other application-wide read gates retain that requirement. The application audit\n * viewer instead defaults to its administrator-role gate, in production and development alike;\n * `auditTrail.applicationReadAccess = AuditApplicationReadAccess.INDEPENDENT_APPROVAL` explicitly\n * enrolls that viewer in this grant requirement. Role-based audit reads remain observed and do not\n * invent a grant id. The historical diagnosis below explains the general elevation mechanism, not\n * an assertion that every cross-tenant audit read must use it.\n *\n * ## The asymmetry this closes\n *\n * `platformAccessGrants` governs the NARROW act: one operator, one named tenant, one window. It is\n * the door `.claude/rules/administrative-continuity-floors.md` calls rungs 4–5 of the ladder, and it\n * works.\n *\n * The WIDE act was ungoverned. Measured 2026-09-09 and recorded on\n * `ScopeRootConfinementDisposition.UNCONFINED_APPLICATION_TIER_DIRECTORY`:\n *\n * | | per-row crossing | application-wide read |\n * |---|---|---|\n * | elevation required | a usable `platformAccessGrants` row | **none** |\n * | role tier | `APP_ADMIN_SUPER_ADMIN` | `APP_ADMIN_VIEWER` / `ORG_MEMBER` |\n * | evidence | `CROSS_TENANT_ADMINISTRATIVE_ACCESS`, naming the grant | an observation naming no elevation |\n *\n * So the narrow act carried elevation and expiry and the widest read did not — and the wide one sat\n * at a strictly LOWER role tier. That is worse than \"not symmetric\"; it is the control inverted.\n *\n * ## Why a SEPARATE resource and not a `scope` field on the tenant grant\n *\n * Structural, not stylistic. A `platformAccessGrants` row is ORGANIZATIONS-scoped: its primary-scope\n * relationship carries `isPrimaryScope: true` on `organizationId`, every route is\n * `/organizations/{organizationId}/platform-access-grants/…`, and the tenant's ability to SEE and\n * REVOKE the row is exactly what that scope buys. An application-wide elevation names no tenant, so\n * the route has nothing to carry and the scope has nobody to serve. Adding a nullable\n * `organizationId` to make one row shape serve both would weaken the field whose presence IS the\n * tenant grant's control — which the finding explicitly refuses (\"do not weaken the per-row model to\n * make the two symmetric\").\n *\n * The engine's own precedent for a second scope over one lifecycle is `applicationAuditLogs` beside\n * `auditLogs`: a sibling resource type carrying ONE application parent, taking the route it needs and\n * leaving the existing door byte-identical.\n *\n * ## Why TWO-PERSON, and what was rejected\n *\n * Tenant approval is the industry ceiling (Microsoft Customer Lockbox, Google Access Approval) and it\n * is structurally unavailable here: there is no single customer to ask. `administrative-continuity-floors.md`\n * names the next-strongest control in as many words — *\"a second factor authenticates a session; only\n * a second signature constrains an authenticated operator\"* — and asks for a two-person rule on the\n * widest acts.\n *\n * Auto-approval was rejected: it is the tenant grant's default posture precisely BECAUSE a tenant can\n * opt in above it, and there is no such party here, so an auto-approved application-wide grant would\n * be a standing privilege with a request form in front of it.\n *\n * Confining the read to tenants the caller holds a grant for was rejected on MEASUREMENT rather than\n * cost: `users` rows carry no tenant column at all, so there is nothing for a tenant predicate to\n * bind to, and any junction-based confinement would also remove the tenant-less user — the person who\n * has just signed up and belongs to nobody — from the only surface that can find them.\n */\n\nimport { z } from 'zod';\nimport { ExecutionContext_MachineCredentialSchema } from '../../runtime/execution-context.shared.schemas';\nimport { PersonalDataCategory } from '../../compliance/privacy/personal-data-category.shared.schemas';\nimport { RedactionType } from '../../compliance/privacy/redaction.shared.schemas';\nimport { addImpersonalizeWith } from '@wildo-ai/zod-decorators';\nimport { PlatformAccessGrantStatus } from './platform-access-grants.shared.schemas';\n\n/** Fixed replacement for grant free-text that cannot be cleared (a `.min(1)` field). */\nconst ERASED_GRANT_TEXT = '[erased]';\n\n/**\n * The default life of an application-wide grant whose request names no duration.\n *\n * THIRTY minutes — half the tenant grant's default, and the halving is the point rather than a round\n * number. A tenant grant reaches ONE customer and the customer can see and revoke it; this one\n * reaches every customer at once and no customer can see it. The window is the only thing that ends\n * it early, so the unconsidered case gets the narrowest window a support interaction can still use.\n */\nexport const APPLICATION_ACCESS_GRANT_DEFAULT_DURATION_MINUTES = 30;\n\n/**\n * The maximum life of an application-wide grant, whatever a request asks for.\n *\n * ONE HOUR against the tenant grant's four. A four-hour window is defended there as \"a working\n * session, not a working week\" for an elevation into one tenant; the same reasoning gives a shorter\n * answer for an elevation into all of them. An operator who genuinely needs longer re-requests, and\n * a second administrator signs again — which is the record we want, and the reason a shorter ceiling\n * here costs no security and buys a second signature per hour of the widest access the system grants.\n */\nexport const APPLICATION_ACCESS_GRANT_MAXIMUM_DURATION_MINUTES = 60;\n\n/**\n * Custom verbs. Mirrors `PlatformAccessGrants_Operations` deliberately — the same lifecycle,\n * so the same verbs, so a reader who knows one knows the other.\n *\n * There is no ordinary CREATE/UPDATE for the same reason: they would be a second, ungated path to the\n * server-authored fields whose server authorship IS the control.\n */\nexport enum ApplicationAccessGrants_Operations {\n  /**\n   * The bootstrap verb. Writes one row in `PENDING_APPROVAL` and NEVER in `ACTIVE` — see\n   * the `status` field below for why auto-approval has no member here.\n   */\n  REQUEST_ACCESS = 'requestAccess',\n  /** The SECOND administrator's signature. Refuses the requester — {@link applicationAccessGrantApproverIsDistinct}. */\n  APPROVE = 'approve',\n  DENY = 'deny',\n  REVOKE = 'revoke',\n  /** ACTIVE → EXPIRED, dispatched by the credential-expiry sweep and by nothing else. */\n  EXPIRE = 'expire',\n}\n\nexport const ApplicationAccessGrantSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  /**\n   * The primary-scope parent — the deployment this elevation is inside.\n   *\n   * OPTIONAL, and that is a load-bearing copy of `applicationAuditLogs`' own shape rather than a\n   * looseness: declared MANDATORY the resource does not load at all on a Mongo-persisted deployment\n   * (the ZodToMongoose convertor refuses it and INIT dies on `zod_converter_schema_conversion_failed`).\n   * Addressing is carried by `isPrimaryScope` + `REQUIRES_CONTEXT` on the relationship, which is what\n   * the URL builder reads, so the route is identical either way.\n   */\n  applicationId: z.string().min(1).optional().isDBIndexed().isForeignKey().excludeFromUpdate().isAuditEvidence(),\n\n  /** The operator who requested the elevation. Server-authored from the session, never client-supplied. */\n  operatorUserId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),\n\n  /**\n   * Why the operator needs application-wide reach. REQUIRED, like its tenant sibling, and here it\n   * carries more weight: it is the ONLY thing the approving administrator has to decide on. A tenant\n   * grant's approver knows their own tenant and their own support case; this approver knows nothing\n   * but this sentence.\n   */\n  // USER_CONTENT — free prose an OPERATOR typed. MASK rather than REMOVE on erasure: `.min(1)` makes\n  // it non-clearable, so a null would be rejected by the strict update-DTO parse the impersonalize\n  // writer runs, and a fixed non-empty string is accepted.\n  justification: addImpersonalizeWith(\n    z.string().min(1).max(1000).isSummaryField()\n    .dataCategories(PersonalDataCategory.USER_CONTENT),\n    RedactionType.MASK,\n    { maskValue: ERASED_GRANT_TEXT },\n  ),\n\n  /**\n   * Lifecycle position, sharing {@link PlatformAccessGrantStatus} rather than declaring a parallel\n   * vocabulary — the states really are the same states, and two enums holding the same five members\n   * is how a sweep, a predicate and a UI come to disagree about what `active` means.\n   *\n   * ## The member that is UNREACHABLE here, and why that is the control\n   *\n   * Every application-wide grant starts `PENDING_APPROVAL`. There is no auto-approval path and\n   * therefore no `autoApprovalReason` field: the tenant grant auto-approves when the tenant has not\n   * opted into approval, or cannot approve — both are statements about a NAMED tenant, and this row\n   * names none. A grant that could approve itself would make the two-person rule ceremonial, which is\n   * exactly the criticism `approve` on the tenant resource carries against platform self-approval.\n   */\n  status: z.enum(PlatformAccessGrantStatus)\n    .systemEnum('PlatformAccessGrantStatus')\n    .default(PlatformAccessGrantStatus.PENDING_APPROVAL)\n    .isDBIndexed()\n    .isSummaryField()\n    .excludeFromCreate()\n    .excludeFromUpdate()\n    .isAuditEvidence(),\n\n  /**\n   * When the elevation stops working.\n   *\n   * Server-authored from the requested duration, clamped to\n   * {@link APPLICATION_ACCESS_GRANT_MAXIMUM_DURATION_MINUTES}. The admission predicate reads THIS\n   * field and not `status`, so expiry needs no sweeper to take effect — the same separation the\n   * tenant grant keeps, and for the same reason: if admission ever starts reading the label, a\n   * lagging sweep becomes an authorization hole rather than a stale display.\n   */\n  expiresAt: z.date().isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),\n\n  /**\n   * The SECOND administrator. Present on every `ACTIVE` row, by construction.\n   *\n   * Optional in the SCHEMA because it is unset while the request is pending and stays unset on a\n   * denied or revoked one. It is not optional in the LIFECYCLE: the only writer of\n   * `status = ACTIVE` is `approve`, and `approve` refuses when this would equal `operatorUserId`.\n   * That refusal is the two-person rule, and it lives in one predicate\n   * ({@link applicationAccessGrantApproverIsDistinct}) so no second call site can re-derive it\n   * more leniently.\n   */\n  approvedByUserId: z.string().min(1).optional().isForeignKey().isSummaryField().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),\n  approvedAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),\n\n  /**\n   * The ONE machine credential this elevation is for, when it is for a machine rather than the requester (#297).\n   *\n   * An application's audit read policy can require independent approval (`INDEPENDENT_APPROVAL`), and until\n   * 2026-09-13 that refused every machine outright: a grant was keyed on `operatorUserId` and a machine has no\n   * user. So the assurance collector — the reader such a policy most wants governed — could never read.\n   *\n   * When set, a HUMAN administrator requests the elevation ON BEHALF OF this credential, a second administrator\n   * signs exactly as for any other grant, and the admission admits that credential and NOBODY ELSE — in\n   * particular never the requester, who would otherwise have minted themselves a window by naming a machine.\n   * {@link applicationAccessGrantAdmits} is the one place that decision lives.\n   *\n   * Set at request time only, validated against a live application API key or OAuth client, and never updated:\n   * re-pointing a signed elevation at a different credential would be a grant nobody signed.\n   */\n  grantedMachineCredential: ExecutionContext_MachineCredentialSchema.optional().excludeFromUpdate().isAuditEvidence(),\n\n  /** The approver's reason for refusing, or the revoker's reason for withdrawing. */\n  // REMOVE — free text again, and clearable (`.optional()`).\n  decisionReason: addImpersonalizeWith(\n    z.string().max(1000).optional().excludeFromCreate().excludeFromUpdate()\n    .dataCategories(PersonalDataCategory.USER_CONTENT),\n    RedactionType.REMOVE,\n  ),\n\n  createdAt: z.date().optional(),\n  updatedAt: z.date().optional(),\n});\n\nexport type ApplicationAccessGrant = z.infer<typeof ApplicationAccessGrantSchema>;\n\n/**\n * Clamp a requested duration to the application-wide ceiling.\n *\n * A deliberate near-copy of `resolvePlatformAccessGrantExpiry` rather than a shared function taking\n * two constants: the two ceilings are two DECISIONS about two different acts, and a shared helper\n * invites the next author to pass whichever constant is in scope. The behaviour that matters is\n * identical and stated in both places — a longer ask is CLAMPED, never refused, because being told\n * \"ask again with a smaller number\" during an incident is friction with no security benefit.\n */\nexport function resolveApplicationAccessGrantExpiry(requestedDurationMinutes: number | undefined, now: Date): Date {\n  const requested = requestedDurationMinutes && requestedDurationMinutes > 0\n    ? requestedDurationMinutes\n    : APPLICATION_ACCESS_GRANT_DEFAULT_DURATION_MINUTES;\n  const minutes = Math.min(requested, APPLICATION_ACCESS_GRANT_MAXIMUM_DURATION_MINUTES);\n  return new Date(now.getTime() + minutes * 60_000);\n}\n\n/**\n * Does this grant admit this principal?\n *\n * **The one decision about WHO a grant is for**, because two principals now hold grants and each reading of the\n * row must agree:\n *\n *  - a grant bound to a machine credential admits exactly that credential (same method, same id) and nobody else —\n *    not its requester, not another credential, not a human carrying no credential;\n *  - an unbound grant admits exactly its requester, as a HUMAN: a machine principal carrying the requester's user\n *    id is not a thing the request pipeline builds, and admitting one would be a second way for a person to lend\n *    their elevation to a credential without a second signature naming it.\n *\n * Fails closed on every missing input. Usability of the WINDOW is a separate question (`isPlatformAccessGrantUsable`).\n */\nexport function applicationAccessGrantAdmits(params: {\n  readonly grant: {\n    readonly operatorUserId?: string | null;\n    readonly grantedMachineCredential?: { readonly authMethod: string; readonly credentialId: string } | null;\n  };\n  readonly principal: {\n    readonly userId?: string | null;\n    readonly machineCredential?: { readonly authMethod: string; readonly credentialId: string } | null;\n  };\n}): boolean {\n  const bound = params.grant.grantedMachineCredential;\n  const presented = params.principal.machineCredential;\n  if (bound) {\n    return Boolean(presented && presented.credentialId && presented.credentialId === bound.credentialId && presented.authMethod === bound.authMethod);\n  }\n  if (presented) return false;\n  const userId = String(params.principal.userId ?? '');\n  return Boolean(userId) && String(params.grant.operatorUserId ?? '') === userId;\n}\n\n/**\n * Is this approver a DIFFERENT person from the operator who asked?\n *\n * **This predicate is the two-person rule.** Everything else about an application-wide grant — the\n * request, the window, the justification, the audit row — exists in the tenant grant too. What is new\n * here is exactly this comparison, so it is named, exported, and asked in ONE place.\n *\n * ## Why it is a predicate and not an inline `!==`\n *\n * Three call sites would otherwise each write their own comparison, and two of the three ways to\n * write it are wrong in the same direction:\n *\n *  - an approver id that is ABSENT must NOT pass. An unauthenticated or system-context approval has\n *    no second person behind it, and `undefined !== 'operator'` is `true` — the inline form fails\n *    OPEN on precisely the input a broken context supplies;\n *  - an operator id that is absent must not pass either, for the mirror reason.\n *\n * So the predicate requires BOTH ids to be present and different. Fails closed on everything else.\n */\nexport function applicationAccessGrantApproverIsDistinct(params: {\n  readonly operatorUserId: string | undefined | null;\n  readonly approverUserId: string | undefined | null;\n}): boolean {\n  const operator = String(params.operatorUserId ?? '');\n  const approver = String(params.approverUserId ?? '');\n  if (!operator || !approver) return false;\n  return operator !== approver;\n}\n"]}

package/dist/esm/security/authorizations/platform-access-grants.shared.schemas.d.ts

@@ -45,6 +45,29 @@
  * the condition either: stranding a tenant is exactly what the floors refuse.
  */
 import { z } from 'zod';
+/**
+ * WHAT an elevation reaches, and therefore WHO can approve it.
+ *
+ * A closed two-member vocabulary with one named runtime source, because the two members answer a
+ * question no boolean can carry: approval AUTHORITY follows scope. A `TENANT` grant names one
+ * organization and is approved by that organization (the Lockbox posture); an `APPLICATION_WIDE`
+ * grant names none, so there is no customer to ask and approval falls to a SECOND platform
+ * administrator under the two-person rule.
+ *
+ * It exists as a vocabulary rather than being inferred from which resource a row came from because
+ * the AUDIT TRAIL needs it: `authorizingGrantId` on a crossing names a row id, and a reviewer given
+ * only an id cannot tell which of the two collections to look in. Carrying the scope beside the id
+ * is what makes the join mechanical instead of a guess.
+ */
+export declare enum PlatformAccessGrantScope {
+    /** Scoped to ONE named organization. Approved by that organization, or auto-approved per its posture. */
+    TENANT = "tenant",
+    /**
+     * Application-wide: an unconfined directory read or a declared cross-tenant read that names no
+     * single tenant. Approved by a SECOND platform administrator — never the requester.
+     */
+    APPLICATION_WIDE = "application_wide"
+}
 /**
  * Lifecycle of one elevation request.
  *

package/dist/esm/security/authorizations/platform-access-grants.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"platform-access-grants.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/security/authorizations/platform-access-grants.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;GAKG;AACH,oBAAY,yBAAyB;IACnC,wFAAwF;IACxF,gBAAgB,qBAAqB;IACrC,yFAAyF;IACzF,MAAM,WAAW;IACjB,gGAAgG;IAChG,MAAM,WAAW;IACjB;;;;;;;;;OASG;IACH,OAAO,YAAY;IACnB,2EAA2E;IAC3E,OAAO,YAAY;CACpB;AAED;;;;;;;GAOG;AACH,oBAAY,sCAAsC;IAChD,SAAS,cAAc;IACvB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB;;;;;;;;;OASG;IACH,OAAO,YAAY;CACpB;AAED,yGAAyG;AACzG,oBAAY,qCAAqC;IAC/C,kGAAkG;IAClG,4BAA4B,iCAAiC;IAC7D;;;;;OAKG;IACH,qBAAqB,0BAA0B;CAChD;AAKD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,8CAA8C,KAAK,CAAC;AAEjE;;;;;;;GAOG;AACH,eAAO,MAAM,8CAA8C,MAAM,CAAC;AAElE,0DAA0D;AAC1D,eAAO,MAAM,wCAAwC,EAAE,SAAS,yBAAyB,EAGxF,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;iBAiFpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,IAAI,CAAC,mBAAmB,EAAE,QAAQ,GAAG,WAAW,CAAC,GAAG,SAAS,EACpE,GAAG,EAAE,IAAI,GACR,OAAO,CAMT;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,wBAAwB,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,IAAI,GAAG,IAAI,CAM9G;AAED;;;;;;;;;;GAUG;AACH;;;;;;;;GAQG;AACH,oBAAY,+BAA+B;IACzC,cAAc,kBAAkB;IAChC,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB;;;;OAIG;IACH,MAAM,WAAW;CAClB"}
+{"version":3,"file":"platform-access-grants.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/security/authorizations/platform-access-grants.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;;;;;;;;GAaG;AACH,oBAAY,wBAAwB;IAClC,yGAAyG;IACzG,MAAM,WAAW;IACjB;;;OAGG;IACH,gBAAgB,qBAAqB;CACtC;AAED;;;;;GAKG;AACH,oBAAY,yBAAyB;IACnC,wFAAwF;IACxF,gBAAgB,qBAAqB;IACrC,yFAAyF;IACzF,MAAM,WAAW;IACjB,gGAAgG;IAChG,MAAM,WAAW;IACjB;;;;;;;;;OASG;IACH,OAAO,YAAY;IACnB,2EAA2E;IAC3E,OAAO,YAAY;CACpB;AAED;;;;;;;GAOG;AACH,oBAAY,sCAAsC;IAChD,SAAS,cAAc;IACvB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB;;;;;;;;;OASG;IACH,OAAO,YAAY;CACpB;AAED,yGAAyG;AACzG,oBAAY,qCAAqC;IAC/C,kGAAkG;IAClG,4BAA4B,iCAAiC;IAC7D;;;;;OAKG;IACH,qBAAqB,0BAA0B;CAChD;AAKD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,8CAA8C,KAAK,CAAC;AAEjE;;;;;;;GAOG;AACH,eAAO,MAAM,8CAA8C,MAAM,CAAC;AAElE,0DAA0D;AAC1D,eAAO,MAAM,wCAAwC,EAAE,SAAS,yBAAyB,EAGxF,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;iBAiFpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,IAAI,CAAC,mBAAmB,EAAE,QAAQ,GAAG,WAAW,CAAC,GAAG,SAAS,EACpE,GAAG,EAAE,IAAI,GACR,OAAO,CAMT;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,wBAAwB,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,IAAI,GAAG,IAAI,CAM9G;AAED;;;;;;;;;;GAUG;AACH;;;;;;;;GAQG;AACH,oBAAY,+BAA+B;IACzC,cAAc,kBAAkB;IAChC,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB;;;;OAIG;IACH,MAAM,WAAW;CAClB"}

package/dist/esm/security/authorizations/platform-access-grants.shared.schemas.js

@@ -48,6 +48,30 @@ import { z } from 'zod';
 import { PersonalDataCategory } from '../../compliance/privacy/personal-data-category.shared.schemas.js';
 import { RedactionType } from '../../compliance/privacy/redaction.shared.schemas.js';
 import { addImpersonalizeWith } from '@wildo-ai/zod-decorators';
+/**
+ * WHAT an elevation reaches, and therefore WHO can approve it.
+ *
+ * A closed two-member vocabulary with one named runtime source, because the two members answer a
+ * question no boolean can carry: approval AUTHORITY follows scope. A `TENANT` grant names one
+ * organization and is approved by that organization (the Lockbox posture); an `APPLICATION_WIDE`
+ * grant names none, so there is no customer to ask and approval falls to a SECOND platform
+ * administrator under the two-person rule.
+ *
+ * It exists as a vocabulary rather than being inferred from which resource a row came from because
+ * the AUDIT TRAIL needs it: `authorizingGrantId` on a crossing names a row id, and a reviewer given
+ * only an id cannot tell which of the two collections to look in. Carrying the scope beside the id
+ * is what makes the join mechanical instead of a guess.
+ */
+export var PlatformAccessGrantScope;
+(function (PlatformAccessGrantScope) {
+    /** Scoped to ONE named organization. Approved by that organization, or auto-approved per its posture. */
+    PlatformAccessGrantScope["TENANT"] = "tenant";
+    /**
+     * Application-wide: an unconfined directory read or a declared cross-tenant read that names no
+     * single tenant. Approved by a SECOND platform administrator — never the requester.
+     */
+    PlatformAccessGrantScope["APPLICATION_WIDE"] = "application_wide";
+})(PlatformAccessGrantScope || (PlatformAccessGrantScope = {}));
 /**
  * Lifecycle of one elevation request.
  *

package/dist/esm/security/authorizations/platform-access-grants.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"platform-access-grants.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/security/authorizations/platform-access-grants.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Platform Access Grants — time-bound, justified, optionally tenant-approved elevation that lets a\n * platform operator cross the tenant boundary.\n *\n * ## Where this sits\n *\n * Wildo's answer to \"may a platform super-administrator administer any tenant?\" is YES, as at most\n * B2B platforms. The question this resource answers is the narrower one that follows: *on what\n * terms?* The progression, recorded in `.claude/rules/administrative-continuity-floors.md`:\n *\n *   ambient+unaudited → ambient+audited → declared, deny-by-default → **JIT/time-bound (here)**\n *   → customer-approved (here, when the tenant opts in)\n *\n * Declaring a crossing per operation variant (`admitsCrossTenantPlatformAdministration`) removed\n * AMBIENT authority: a crossing must now be asked for in code, reviewed, and specified. It did not\n * remove STANDING authority — every platform administrator still held every declared crossing,\n * permanently, over every tenant. That is the shape zero-standing-privilege programmes exist to\n * eliminate, and what NIST SP 800-53 AC-2 / AC-6(1) mean by least privilege: privileged access is\n * requested, scoped, time-boxed, and expires on its own.\n *\n * A grant is therefore required IN ADDITION to the variant's declaration. The declaration says\n * \"this verb MAY cross\"; the grant says \"this operator MAY cross into THIS tenant, until THIS time,\n * for THIS reason\". Neither is sufficient alone.\n *\n * ## The tenant-approval half (Lockbox)\n *\n * Microsoft Customer Lockbox and Google Access Approval let the CUSTOMER approve provider access\n * before it happens. Wildo models that as {@link PlatformAccessGrantStatus.PENDING_APPROVAL}, gated\n * per tenant so it is an opt-in posture rather than a deployment-wide one — the same shape those\n * products ship, and for the same reason: a tenant that has not staffed an approver must not be\n * unable to receive support.\n *\n * ## ⚠️ The interaction that is easy to get wrong\n *\n * Tenant approval and the administrative-continuity floors are in direct tension. Approval requires\n * an administrator; the floors exist precisely because a tenant can end up WITHOUT one. Requiring a\n * stranded tenant to approve its own repair is circular — the tenant cannot approve, so the repair\n * cannot happen, so the tenant stays stranded.\n *\n * This is resolved by measurement, not by exception: when the target tenant has no administratively\n * usable owner, the grant is auto-approved with\n * {@link PlatformAccessGrantAutoApprovalReason.TENANT_CANNOT_APPROVE} and recorded loudly. The\n * condition is evaluated with the SAME predicate the owner floor uses to refuse writes, so the two\n * can never disagree about whether a tenant can administer itself. An operator cannot manufacture\n * the condition either: stranding a tenant is exactly what the floors refuse.\n */\n\nimport { z } from 'zod';\nimport { PersonalDataCategory } from '../../compliance/privacy/personal-data-category.shared.schemas';\nimport { RedactionType } from '../../compliance/privacy/redaction.shared.schemas';\nimport { addImpersonalizeWith } from '@wildo-ai/zod-decorators';\n\n/**\n * Lifecycle of one elevation request.\n *\n * A closed vocabulary with one named runtime source: schemas, guards, fixtures and comparisons all\n * derive from this enum rather than repeating literals.\n */\nexport enum PlatformAccessGrantStatus {\n  /** Awaiting a decision from an administrator of the TARGET tenant (Lockbox posture). */\n  PENDING_APPROVAL = 'pending_approval',\n  /** Usable now. The admission predicate accepts this status, and only while unexpired. */\n  ACTIVE = 'active',\n  /** The tenant refused. Terminal — a new request must be raised rather than this one retried. */\n  DENIED = 'denied',\n  /**\n   * The window elapsed. Terminal, and written by the credential-expiry sweep since 2026-09-08\n   * (#413) — before that it was reached by NO writer at all, so an elapsed grant read as ACTIVE\n   * forever in the customer-facing listing of its own resource.\n   *\n   * The label is still bookkeeping for humans and reporting, NEVER the control: the admission\n   * predicate compares `expiresAt` against now, so an expired grant stops working whether or not\n   * the sweep has run. That separation is deliberate and must survive — if admission ever starts\n   * reading this label, a lagging sweep becomes an authorization hole rather than a stale display.\n   */\n  EXPIRED = 'expired',\n  /** Withdrawn before expiry, by the tenant or by the platform. Terminal. */\n  REVOKED = 'revoked',\n}\n\n/**\n * Which step of a grant's life an audit row records.\n *\n * Distinct from {@link PlatformAccessGrantStatus}: a status is where the grant IS, a transition is\n * what just happened to it. They differ where it matters — an auto-approved grant lands in `ACTIVE`\n * through `REQUESTED`, never through `APPROVED`, and collapsing the two would erase exactly the\n * distinction a customer audit asks about.\n */\nexport enum PlatformAccessGrantLifecycleTransition {\n  REQUESTED = 'requested',\n  APPROVED = 'approved',\n  DENIED = 'denied',\n  REVOKED = 'revoked',\n  /**\n   * The window elapsed and the sweep relabelled the grant (#413). The ONE transition with no human\n   * actor — every other member records a decision somebody made, so an audit row for this one\n   * carries no `decidedByUserId`, and that absence is the fact rather than a gap.\n   *\n   * It is recorded even though the label is bookkeeping and never the control: a customer reading\n   * the history of an operator's access to their tenant should see the access END, and a grant that\n   * simply stops appearing as ACTIVE with no corresponding row is the version of that history that\n   * raises questions.\n   */\n  EXPIRED = 'expired',\n}\n\n/** Why a grant became {@link PlatformAccessGrantStatus.ACTIVE} without a tenant administrator acting. */\nexport enum PlatformAccessGrantAutoApprovalReason {\n  /** The tenant has not opted into approval. The default posture, matching Lockbox being opt-in. */\n  TENANT_APPROVAL_NOT_REQUIRED = 'tenant_approval_not_required',\n  /**\n   * The tenant has NO administratively usable owner, so no principal exists who could approve.\n   * Evaluated with the owner floor's own predicate — see this file's header for why the alternative\n   * (refusing) is circular. Recorded at high severity: this is the one path where operator access\n   * proceeds against a tenant that never consented and never could.\n   */\n  TENANT_CANNOT_APPROVE = 'tenant_cannot_approve',\n}\n\n/** Fixed replacement for grant free-text that cannot be cleared (a `.min(1)` field). */\nconst ERASED_GRANT_TEXT = '[erased]';\n\n/**\n * The default life of a grant whose request names no duration.\n *\n * ONE HOUR, and deliberately far below the ceiling. A request that states no duration is the\n * unconsidered case, and the unconsidered case should get the narrowest window that still works —\n * not the widest the system allows. Until 2026-09-08 this was 240, equal to the maximum, so every\n * grant that did not ask was issued a four-hour elevation; that is the opposite of what a\n * just-in-time mechanism is for.\n *\n * Sixty rather than thirty, and the reasoning is the part worth keeping: the failure mode of a\n * too-short default is not a security one, it is that an operator re-requesting mid-incident learns\n * to ask for the maximum every time — which would restore the old behaviour through the front door\n * and make the ceiling the effective default. An hour covers an ordinary support interaction\n * without teaching that habit. An operator who genuinely needs longer asks, and that ask is the\n * record we want.\n */\nexport const PLATFORM_ACCESS_GRANT_DEFAULT_DURATION_MINUTES = 60;\n\n/**\n * The maximum life of a grant, whatever a request asks for.\n *\n * Four hours is a working session, not a working week: long enough that an operator is not\n * re-requesting mid-incident, short enough that a forgotten grant is not a standing privilege by\n * another name. Callers may request LESS; the ceiling is enforced server-side so a client cannot\n * mint a long-lived elevation by asking for one.\n */\nexport const PLATFORM_ACCESS_GRANT_MAXIMUM_DURATION_MINUTES = 240;\n\n/** Statuses from which a grant can still be withdrawn. */\nexport const PLATFORM_ACCESS_GRANT_REVOCABLE_STATUSES: readonly PlatformAccessGrantStatus[] = [\n  PlatformAccessGrantStatus.PENDING_APPROVAL,\n  PlatformAccessGrantStatus.ACTIVE,\n];\n\nexport const PlatformAccessGrantSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  /**\n   * The TARGET tenant — the one being reached into, never the operator's own.\n   *\n   * This is the scope anchor: the grant is an organization-scoped row so the tenant can see, approve\n   * and revoke elevations raised against it. A grant the tenant cannot see would defeat the point of\n   * modelling consent at all.\n   */\n  organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate().isAuditEvidence(),\n\n  /** The operator who requested the elevation. Server-authored from the session, never client-supplied. */\n  operatorUserId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),\n\n  /**\n   * Why the operator needs access. REQUIRED, and deliberately not optional anywhere in the flow.\n   *\n   * An elevation record without a reason answers \"who and when\" but not \"why\", which is the only\n   * question a reviewer or a customer actually asks. `AC-2(7)` wants privileged assignment monitored;\n   * an unexplained monitored assignment is a log line, not a control.\n   */\n  // USER_CONTENT — free prose an OPERATOR typed, about why they need to reach a customer tenant.\n  // The data subject here is the operator, not the tenant's users; a notice covering staff must\n  // enumerate it, and it is exactly the free-text surface that can name a third party in passing.\n  // MASK on erasure, not REMOVE: `.min(1)` makes this non-clearable, so a null would be rejected by the\n  // strict update-DTO parse the impersonalize writer runs. A fixed non-empty string is accepted.\n  // It must be scrubbed at all because it is free text an operator wrote about why they needed\n  // access — exactly the surface that names a third party in passing.\n  justification: addImpersonalizeWith(\n    z.string().min(1).max(1000).isSummaryField()\n    .dataCategories(PersonalDataCategory.USER_CONTENT),\n    RedactionType.MASK,\n    { maskValue: ERASED_GRANT_TEXT },\n  ),\n\n  status: z.enum(PlatformAccessGrantStatus)\n    .systemEnum('PlatformAccessGrantStatus')\n    .default(PlatformAccessGrantStatus.PENDING_APPROVAL)\n    .isDBIndexed()\n    .isSummaryField()\n    .excludeFromCreate()\n    .excludeFromUpdate()\n    .isAuditEvidence(),\n\n  /**\n   * When the elevation stops working.\n   *\n   * Server-authored from the requested duration, clamped to\n   * {@link PLATFORM_ACCESS_GRANT_MAXIMUM_DURATION_MINUTES}. The admission predicate reads THIS field\n   * rather than trusting `status`, so expiry needs no sweeper to take effect.\n   */\n  expiresAt: z.date().isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),\n\n  /** Set when a tenant administrator approved. Absent on an auto-approved grant — see {@link autoApprovalReason}. */\n  approvedByUserId: z.string().min(1).optional().isForeignKey().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),\n  approvedAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),\n\n  /**\n   * Present exactly when the grant became ACTIVE with no tenant administrator acting.\n   *\n   * Its absence on an ACTIVE grant is therefore meaningful: a human in the tenant approved it. That\n   * distinction is what a customer audit needs and what a single `approved: true` boolean would erase.\n   */\n  autoApprovalReason: z.enum(PlatformAccessGrantAutoApprovalReason)\n    .systemEnum('PlatformAccessGrantAutoApprovalReason')\n    .optional()\n    .excludeFromCreate()\n    .excludeFromUpdate()\n    .isAuditEvidence(),\n\n  /** The tenant's reason for refusing, or the revoker's reason for withdrawing. */\n  // REMOVE — free text again, and clearable (`.optional()`).\n  decisionReason: addImpersonalizeWith(\n    z.string().max(1000).optional().excludeFromCreate().excludeFromUpdate()\n    .dataCategories(PersonalDataCategory.USER_CONTENT),\n    RedactionType.REMOVE,\n  ),\n\n  createdAt: z.date().optional(),\n  updatedAt: z.date().optional(),\n});\n\nexport type PlatformAccessGrant = z.infer<typeof PlatformAccessGrantSchema>;\n\n/**\n * Is this grant usable RIGHT NOW?\n *\n * The single predicate every consumer must use — the admission check, the tenant's UI, and any\n * report. Two independent conditions, and the expiry half is why this is a function rather than a\n * status comparison: a grant whose window elapsed is unusable the moment it elapses, with no writer\n * involved. Reading `status === ACTIVE` alone would honour a stale row for as long as no sweeper had\n * run, turning a time-bound elevation back into a standing one.\n *\n * `now` is injected so callers can evaluate a grant at a decision time they already fixed, and so\n * this stays testable without clock control.\n */\nexport function isPlatformAccessGrantUsable(\n  grant: Pick<PlatformAccessGrant, 'status' | 'expiresAt'> | undefined,\n  now: Date,\n): boolean {\n  if (!grant) return false;\n  if (grant.status !== PlatformAccessGrantStatus.ACTIVE) return false;\n  return grant.expiresAt instanceof Date\n    ? grant.expiresAt.getTime() > now.getTime()\n    : new Date(grant.expiresAt).getTime() > now.getTime();\n}\n\n/**\n * Clamp a requested duration to the server-side ceiling.\n *\n * Applied to every request path, including trusted ones. A caller asking for a longer window is not\n * refused — being told \"no, ask again with a smaller number\" during an incident is friction with no\n * security benefit, since the ceiling is what actually binds. They simply get the ceiling.\n */\nexport function resolvePlatformAccessGrantExpiry(requestedDurationMinutes: number | undefined, now: Date): Date {\n  const requested = requestedDurationMinutes && requestedDurationMinutes > 0\n    ? requestedDurationMinutes\n    : PLATFORM_ACCESS_GRANT_DEFAULT_DURATION_MINUTES;\n  const minutes = Math.min(requested, PLATFORM_ACCESS_GRANT_MAXIMUM_DURATION_MINUTES);\n  return new Date(now.getTime() + minutes * 60_000);\n}\n\n/**\n * NOTE ON PLACEMENT — this enum lives with the VOCABULARY, not with the resource configuration,\n * and moving it back would reintroduce a real defect.\n *\n * The authorization layer needs `REQUEST_ACCESS` by name (it is the bootstrap verb, exempt from the\n * grant requirement it bootstraps). Importing that value from the resources-config module dragged\n * resource-configuration evaluation into the authorizer's module graph, and schema construction that\n * runs before the Zod decorators are initialised loses decorator metadata — which surfaced, far from\n * here, as the ephemeral-disclosure catalogue losing an operation-level declaration. A vocabulary has\n * no such side effects.\n */\n/**\n * Custom verbs. Ordinary CREATE/UPDATE/DELETE are deliberately NOT exposed:\n *\n * - CREATE would let a caller author `status`, `expiresAt` and `operatorUserId` directly, which are\n *   precisely the fields whose server authorship IS the control.\n * - UPDATE would be a second, ungated path to the status transitions `approve`/`deny`/`revoke` own.\n * - DELETE exists but has NO client door — see its configuration below. An elevation either side could\n *   erase is not evidence; the terminal statuses (DENIED / EXPIRED / REVOKED) are how a grant ends.\n */\nexport enum PlatformAccessGrants_Operations {\n  REQUEST_ACCESS = 'requestAccess',\n  APPROVE = 'approve',\n  DENY = 'deny',\n  REVOKE = 'revoke',\n  /**\n   * ACTIVE → EXPIRED once the window has elapsed, dispatched by the credential-expiry sweep and by\n   * nothing else (#413). Not an operator verb: an operator who wants access to end early uses\n   * REVOKE, and nobody needs a button that declares a date has passed.\n   */\n  EXPIRE = 'expire',\n}\n"]}
+{"version":3,"file":"platform-access-grants.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/security/authorizations/platform-access-grants.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Platform Access Grants — time-bound, justified, optionally tenant-approved elevation that lets a\n * platform operator cross the tenant boundary.\n *\n * ## Where this sits\n *\n * Wildo's answer to \"may a platform super-administrator administer any tenant?\" is YES, as at most\n * B2B platforms. The question this resource answers is the narrower one that follows: *on what\n * terms?* The progression, recorded in `.claude/rules/administrative-continuity-floors.md`:\n *\n *   ambient+unaudited → ambient+audited → declared, deny-by-default → **JIT/time-bound (here)**\n *   → customer-approved (here, when the tenant opts in)\n *\n * Declaring a crossing per operation variant (`admitsCrossTenantPlatformAdministration`) removed\n * AMBIENT authority: a crossing must now be asked for in code, reviewed, and specified. It did not\n * remove STANDING authority — every platform administrator still held every declared crossing,\n * permanently, over every tenant. That is the shape zero-standing-privilege programmes exist to\n * eliminate, and what NIST SP 800-53 AC-2 / AC-6(1) mean by least privilege: privileged access is\n * requested, scoped, time-boxed, and expires on its own.\n *\n * A grant is therefore required IN ADDITION to the variant's declaration. The declaration says\n * \"this verb MAY cross\"; the grant says \"this operator MAY cross into THIS tenant, until THIS time,\n * for THIS reason\". Neither is sufficient alone.\n *\n * ## The tenant-approval half (Lockbox)\n *\n * Microsoft Customer Lockbox and Google Access Approval let the CUSTOMER approve provider access\n * before it happens. Wildo models that as {@link PlatformAccessGrantStatus.PENDING_APPROVAL}, gated\n * per tenant so it is an opt-in posture rather than a deployment-wide one — the same shape those\n * products ship, and for the same reason: a tenant that has not staffed an approver must not be\n * unable to receive support.\n *\n * ## ⚠️ The interaction that is easy to get wrong\n *\n * Tenant approval and the administrative-continuity floors are in direct tension. Approval requires\n * an administrator; the floors exist precisely because a tenant can end up WITHOUT one. Requiring a\n * stranded tenant to approve its own repair is circular — the tenant cannot approve, so the repair\n * cannot happen, so the tenant stays stranded.\n *\n * This is resolved by measurement, not by exception: when the target tenant has no administratively\n * usable owner, the grant is auto-approved with\n * {@link PlatformAccessGrantAutoApprovalReason.TENANT_CANNOT_APPROVE} and recorded loudly. The\n * condition is evaluated with the SAME predicate the owner floor uses to refuse writes, so the two\n * can never disagree about whether a tenant can administer itself. An operator cannot manufacture\n * the condition either: stranding a tenant is exactly what the floors refuse.\n */\n\nimport { z } from 'zod';\nimport { PersonalDataCategory } from '../../compliance/privacy/personal-data-category.shared.schemas';\nimport { RedactionType } from '../../compliance/privacy/redaction.shared.schemas';\nimport { addImpersonalizeWith } from '@wildo-ai/zod-decorators';\n\n/**\n * WHAT an elevation reaches, and therefore WHO can approve it.\n *\n * A closed two-member vocabulary with one named runtime source, because the two members answer a\n * question no boolean can carry: approval AUTHORITY follows scope. A `TENANT` grant names one\n * organization and is approved by that organization (the Lockbox posture); an `APPLICATION_WIDE`\n * grant names none, so there is no customer to ask and approval falls to a SECOND platform\n * administrator under the two-person rule.\n *\n * It exists as a vocabulary rather than being inferred from which resource a row came from because\n * the AUDIT TRAIL needs it: `authorizingGrantId` on a crossing names a row id, and a reviewer given\n * only an id cannot tell which of the two collections to look in. Carrying the scope beside the id\n * is what makes the join mechanical instead of a guess.\n */\nexport enum PlatformAccessGrantScope {\n  /** Scoped to ONE named organization. Approved by that organization, or auto-approved per its posture. */\n  TENANT = 'tenant',\n  /**\n   * Application-wide: an unconfined directory read or a declared cross-tenant read that names no\n   * single tenant. Approved by a SECOND platform administrator — never the requester.\n   */\n  APPLICATION_WIDE = 'application_wide',\n}\n\n/**\n * Lifecycle of one elevation request.\n *\n * A closed vocabulary with one named runtime source: schemas, guards, fixtures and comparisons all\n * derive from this enum rather than repeating literals.\n */\nexport enum PlatformAccessGrantStatus {\n  /** Awaiting a decision from an administrator of the TARGET tenant (Lockbox posture). */\n  PENDING_APPROVAL = 'pending_approval',\n  /** Usable now. The admission predicate accepts this status, and only while unexpired. */\n  ACTIVE = 'active',\n  /** The tenant refused. Terminal — a new request must be raised rather than this one retried. */\n  DENIED = 'denied',\n  /**\n   * The window elapsed. Terminal, and written by the credential-expiry sweep since 2026-09-08\n   * (#413) — before that it was reached by NO writer at all, so an elapsed grant read as ACTIVE\n   * forever in the customer-facing listing of its own resource.\n   *\n   * The label is still bookkeeping for humans and reporting, NEVER the control: the admission\n   * predicate compares `expiresAt` against now, so an expired grant stops working whether or not\n   * the sweep has run. That separation is deliberate and must survive — if admission ever starts\n   * reading this label, a lagging sweep becomes an authorization hole rather than a stale display.\n   */\n  EXPIRED = 'expired',\n  /** Withdrawn before expiry, by the tenant or by the platform. Terminal. */\n  REVOKED = 'revoked',\n}\n\n/**\n * Which step of a grant's life an audit row records.\n *\n * Distinct from {@link PlatformAccessGrantStatus}: a status is where the grant IS, a transition is\n * what just happened to it. They differ where it matters — an auto-approved grant lands in `ACTIVE`\n * through `REQUESTED`, never through `APPROVED`, and collapsing the two would erase exactly the\n * distinction a customer audit asks about.\n */\nexport enum PlatformAccessGrantLifecycleTransition {\n  REQUESTED = 'requested',\n  APPROVED = 'approved',\n  DENIED = 'denied',\n  REVOKED = 'revoked',\n  /**\n   * The window elapsed and the sweep relabelled the grant (#413). The ONE transition with no human\n   * actor — every other member records a decision somebody made, so an audit row for this one\n   * carries no `decidedByUserId`, and that absence is the fact rather than a gap.\n   *\n   * It is recorded even though the label is bookkeeping and never the control: a customer reading\n   * the history of an operator's access to their tenant should see the access END, and a grant that\n   * simply stops appearing as ACTIVE with no corresponding row is the version of that history that\n   * raises questions.\n   */\n  EXPIRED = 'expired',\n}\n\n/** Why a grant became {@link PlatformAccessGrantStatus.ACTIVE} without a tenant administrator acting. */\nexport enum PlatformAccessGrantAutoApprovalReason {\n  /** The tenant has not opted into approval. The default posture, matching Lockbox being opt-in. */\n  TENANT_APPROVAL_NOT_REQUIRED = 'tenant_approval_not_required',\n  /**\n   * The tenant has NO administratively usable owner, so no principal exists who could approve.\n   * Evaluated with the owner floor's own predicate — see this file's header for why the alternative\n   * (refusing) is circular. Recorded at high severity: this is the one path where operator access\n   * proceeds against a tenant that never consented and never could.\n   */\n  TENANT_CANNOT_APPROVE = 'tenant_cannot_approve',\n}\n\n/** Fixed replacement for grant free-text that cannot be cleared (a `.min(1)` field). */\nconst ERASED_GRANT_TEXT = '[erased]';\n\n/**\n * The default life of a grant whose request names no duration.\n *\n * ONE HOUR, and deliberately far below the ceiling. A request that states no duration is the\n * unconsidered case, and the unconsidered case should get the narrowest window that still works —\n * not the widest the system allows. Until 2026-09-08 this was 240, equal to the maximum, so every\n * grant that did not ask was issued a four-hour elevation; that is the opposite of what a\n * just-in-time mechanism is for.\n *\n * Sixty rather than thirty, and the reasoning is the part worth keeping: the failure mode of a\n * too-short default is not a security one, it is that an operator re-requesting mid-incident learns\n * to ask for the maximum every time — which would restore the old behaviour through the front door\n * and make the ceiling the effective default. An hour covers an ordinary support interaction\n * without teaching that habit. An operator who genuinely needs longer asks, and that ask is the\n * record we want.\n */\nexport const PLATFORM_ACCESS_GRANT_DEFAULT_DURATION_MINUTES = 60;\n\n/**\n * The maximum life of a grant, whatever a request asks for.\n *\n * Four hours is a working session, not a working week: long enough that an operator is not\n * re-requesting mid-incident, short enough that a forgotten grant is not a standing privilege by\n * another name. Callers may request LESS; the ceiling is enforced server-side so a client cannot\n * mint a long-lived elevation by asking for one.\n */\nexport const PLATFORM_ACCESS_GRANT_MAXIMUM_DURATION_MINUTES = 240;\n\n/** Statuses from which a grant can still be withdrawn. */\nexport const PLATFORM_ACCESS_GRANT_REVOCABLE_STATUSES: readonly PlatformAccessGrantStatus[] = [\n  PlatformAccessGrantStatus.PENDING_APPROVAL,\n  PlatformAccessGrantStatus.ACTIVE,\n];\n\nexport const PlatformAccessGrantSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  /**\n   * The TARGET tenant — the one being reached into, never the operator's own.\n   *\n   * This is the scope anchor: the grant is an organization-scoped row so the tenant can see, approve\n   * and revoke elevations raised against it. A grant the tenant cannot see would defeat the point of\n   * modelling consent at all.\n   */\n  organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate().isAuditEvidence(),\n\n  /** The operator who requested the elevation. Server-authored from the session, never client-supplied. */\n  operatorUserId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),\n\n  /**\n   * Why the operator needs access. REQUIRED, and deliberately not optional anywhere in the flow.\n   *\n   * An elevation record without a reason answers \"who and when\" but not \"why\", which is the only\n   * question a reviewer or a customer actually asks. `AC-2(7)` wants privileged assignment monitored;\n   * an unexplained monitored assignment is a log line, not a control.\n   */\n  // USER_CONTENT — free prose an OPERATOR typed, about why they need to reach a customer tenant.\n  // The data subject here is the operator, not the tenant's users; a notice covering staff must\n  // enumerate it, and it is exactly the free-text surface that can name a third party in passing.\n  // MASK on erasure, not REMOVE: `.min(1)` makes this non-clearable, so a null would be rejected by the\n  // strict update-DTO parse the impersonalize writer runs. A fixed non-empty string is accepted.\n  // It must be scrubbed at all because it is free text an operator wrote about why they needed\n  // access — exactly the surface that names a third party in passing.\n  justification: addImpersonalizeWith(\n    z.string().min(1).max(1000).isSummaryField()\n    .dataCategories(PersonalDataCategory.USER_CONTENT),\n    RedactionType.MASK,\n    { maskValue: ERASED_GRANT_TEXT },\n  ),\n\n  status: z.enum(PlatformAccessGrantStatus)\n    .systemEnum('PlatformAccessGrantStatus')\n    .default(PlatformAccessGrantStatus.PENDING_APPROVAL)\n    .isDBIndexed()\n    .isSummaryField()\n    .excludeFromCreate()\n    .excludeFromUpdate()\n    .isAuditEvidence(),\n\n  /**\n   * When the elevation stops working.\n   *\n   * Server-authored from the requested duration, clamped to\n   * {@link PLATFORM_ACCESS_GRANT_MAXIMUM_DURATION_MINUTES}. The admission predicate reads THIS field\n   * rather than trusting `status`, so expiry needs no sweeper to take effect.\n   */\n  expiresAt: z.date().isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),\n\n  /** Set when a tenant administrator approved. Absent on an auto-approved grant — see {@link autoApprovalReason}. */\n  approvedByUserId: z.string().min(1).optional().isForeignKey().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),\n  approvedAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),\n\n  /**\n   * Present exactly when the grant became ACTIVE with no tenant administrator acting.\n   *\n   * Its absence on an ACTIVE grant is therefore meaningful: a human in the tenant approved it. That\n   * distinction is what a customer audit needs and what a single `approved: true` boolean would erase.\n   */\n  autoApprovalReason: z.enum(PlatformAccessGrantAutoApprovalReason)\n    .systemEnum('PlatformAccessGrantAutoApprovalReason')\n    .optional()\n    .excludeFromCreate()\n    .excludeFromUpdate()\n    .isAuditEvidence(),\n\n  /** The tenant's reason for refusing, or the revoker's reason for withdrawing. */\n  // REMOVE — free text again, and clearable (`.optional()`).\n  decisionReason: addImpersonalizeWith(\n    z.string().max(1000).optional().excludeFromCreate().excludeFromUpdate()\n    .dataCategories(PersonalDataCategory.USER_CONTENT),\n    RedactionType.REMOVE,\n  ),\n\n  createdAt: z.date().optional(),\n  updatedAt: z.date().optional(),\n});\n\nexport type PlatformAccessGrant = z.infer<typeof PlatformAccessGrantSchema>;\n\n/**\n * Is this grant usable RIGHT NOW?\n *\n * The single predicate every consumer must use — the admission check, the tenant's UI, and any\n * report. Two independent conditions, and the expiry half is why this is a function rather than a\n * status comparison: a grant whose window elapsed is unusable the moment it elapses, with no writer\n * involved. Reading `status === ACTIVE` alone would honour a stale row for as long as no sweeper had\n * run, turning a time-bound elevation back into a standing one.\n *\n * `now` is injected so callers can evaluate a grant at a decision time they already fixed, and so\n * this stays testable without clock control.\n */\nexport function isPlatformAccessGrantUsable(\n  grant: Pick<PlatformAccessGrant, 'status' | 'expiresAt'> | undefined,\n  now: Date,\n): boolean {\n  if (!grant) return false;\n  if (grant.status !== PlatformAccessGrantStatus.ACTIVE) return false;\n  return grant.expiresAt instanceof Date\n    ? grant.expiresAt.getTime() > now.getTime()\n    : new Date(grant.expiresAt).getTime() > now.getTime();\n}\n\n/**\n * Clamp a requested duration to the server-side ceiling.\n *\n * Applied to every request path, including trusted ones. A caller asking for a longer window is not\n * refused — being told \"no, ask again with a smaller number\" during an incident is friction with no\n * security benefit, since the ceiling is what actually binds. They simply get the ceiling.\n */\nexport function resolvePlatformAccessGrantExpiry(requestedDurationMinutes: number | undefined, now: Date): Date {\n  const requested = requestedDurationMinutes && requestedDurationMinutes > 0\n    ? requestedDurationMinutes\n    : PLATFORM_ACCESS_GRANT_DEFAULT_DURATION_MINUTES;\n  const minutes = Math.min(requested, PLATFORM_ACCESS_GRANT_MAXIMUM_DURATION_MINUTES);\n  return new Date(now.getTime() + minutes * 60_000);\n}\n\n/**\n * NOTE ON PLACEMENT — this enum lives with the VOCABULARY, not with the resource configuration,\n * and moving it back would reintroduce a real defect.\n *\n * The authorization layer needs `REQUEST_ACCESS` by name (it is the bootstrap verb, exempt from the\n * grant requirement it bootstraps). Importing that value from the resources-config module dragged\n * resource-configuration evaluation into the authorizer's module graph, and schema construction that\n * runs before the Zod decorators are initialised loses decorator metadata — which surfaced, far from\n * here, as the ephemeral-disclosure catalogue losing an operation-level declaration. A vocabulary has\n * no such side effects.\n */\n/**\n * Custom verbs. Ordinary CREATE/UPDATE/DELETE are deliberately NOT exposed:\n *\n * - CREATE would let a caller author `status`, `expiresAt` and `operatorUserId` directly, which are\n *   precisely the fields whose server authorship IS the control.\n * - UPDATE would be a second, ungated path to the status transitions `approve`/`deny`/`revoke` own.\n * - DELETE exists but has NO client door — see its configuration below. An elevation either side could\n *   erase is not evidence; the terminal statuses (DENIED / EXPIRED / REVOKED) are how a grant ends.\n */\nexport enum PlatformAccessGrants_Operations {\n  REQUEST_ACCESS = 'requestAccess',\n  APPROVE = 'approve',\n  DENY = 'deny',\n  REVOKE = 'revoke',\n  /**\n   * ACTIVE → EXPIRED once the window has elapsed, dispatched by the credential-expiry sweep and by\n   * nothing else (#413). Not an operator verb: an operator who wants access to end early uses\n   * REVOKE, and nobody needs a button that declares a date has passed.\n   */\n  EXPIRE = 'expire',\n}\n"]}

package/dist/esm/security/authorizations/roles.shared.defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"roles.shared.defaults.d.ts","sourceRoot":"","sources":["../../../../../src/security/authorizations/roles.shared.defaults.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAkC,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAE5F,eAAO,MAAM,8BAA8B,EAAE,kBAwC5C,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,kBA8BxC,CAAC"}
+{"version":3,"file":"roles.shared.defaults.d.ts","sourceRoot":"","sources":["../../../../../src/security/authorizations/roles.shared.defaults.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAkC,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAE5F,eAAO,MAAM,8BAA8B,EAAE,kBA8C5C,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,kBA8BxC,CAAC"}

package/dist/esm/security/authorizations/roles.shared.defaults.js

@@ -41,6 +41,12 @@ export const DEFAULT_APP_ROLE_CONFIGURATION = {
         isSystemRole: true,
         relatedPrimaryScope: ResourcePrimaryScope.APPLICATION
     },
+    // No `inheritFrom`: the reader confers exactly the operations that name it. See the enum member.
+    [CORE_APP_ROLES.APP_AUDIT_EVIDENCE_READER]: {
+        role: CORE_APP_ROLES.APP_AUDIT_EVIDENCE_READER,
+        isSystemRole: true,
+        relatedPrimaryScope: ResourcePrimaryScope.APPLICATION
+    },
     [CORE_APP_ROLES.APP_ANONYMOUS]: {
         role: CORE_APP_ROLES.APP_ANONYMOUS,
         isSystemRole: true,

package/dist/esm/security/authorizations/roles.shared.defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"roles.shared.defaults.js","sourceRoot":"","sources":["../../../../../src/security/authorizations/roles.shared.defaults.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * App Roles Shared Schemas\n *\n * Application-level roles directly linked to users (not organization-specific)\n * Similar behavior to OrganizationRole but for app-wide permissions\n */\n\nimport { ResourcePrimaryScope } from '../../resources/resources.shared.schemas';\nimport { CORE_APP_ROLES, CORE_ORG_ROLES, RolesConfiguration } from './roles.shared.schemas';\n\nexport const DEFAULT_APP_ROLE_CONFIGURATION: RolesConfiguration = {\n  [CORE_APP_ROLES.APP_PUBLIC]: {\n    role: CORE_APP_ROLES.APP_PUBLIC,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION\n  },\n  [CORE_APP_ROLES.APP_USER]: {\n    role: CORE_APP_ROLES.APP_USER,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION\n  },\n  [CORE_APP_ROLES.APP_ADMIN_VIEWER]: {\n    role: CORE_APP_ROLES.APP_ADMIN_VIEWER,\n    inheritFrom: CORE_APP_ROLES.APP_USER,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION\n  },\n  [CORE_APP_ROLES.APP_ADMIN_MARKETING_EDITOR]: {\n    role: CORE_APP_ROLES.APP_ADMIN_MARKETING_EDITOR,\n    inheritFrom: CORE_APP_ROLES.APP_ADMIN_VIEWER,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION\n  },\n  [CORE_APP_ROLES.APP_ADMIN_BILLING_MANAGER]: {\n    role: CORE_APP_ROLES.APP_ADMIN_BILLING_MANAGER,\n    inheritFrom: CORE_APP_ROLES.APP_ADMIN_VIEWER,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION\n  },\n  [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN]: {\n    role: CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN,\n    inheritFrom: CORE_APP_ROLES.APP_ADMIN_BILLING_MANAGER,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION\n  },\n  [CORE_APP_ROLES.APP_ANONYMOUS]: {\n    role: CORE_APP_ROLES.APP_ANONYMOUS,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION\n  },\n};\n\nexport const DEFAULT_ORGANIZATION_ROLES: RolesConfiguration = {\n  [CORE_ORG_ROLES.ORG_GUEST]: {\n    role: CORE_ORG_ROLES.ORG_GUEST,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  },\n  [CORE_ORG_ROLES.ORG_MEMBER]: {\n    role: CORE_ORG_ROLES.ORG_MEMBER,\n    inheritFrom: CORE_ORG_ROLES.ORG_GUEST,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  },\n  [CORE_ORG_ROLES.ORG_MANAGER]: {\n    role: CORE_ORG_ROLES.ORG_MANAGER,\n    inheritFrom: CORE_ORG_ROLES.ORG_MEMBER,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  },\n  [CORE_ORG_ROLES.ORG_ADMIN]: {\n    role: CORE_ORG_ROLES.ORG_ADMIN,\n    inheritFrom: CORE_ORG_ROLES.ORG_MANAGER,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  },\n  [CORE_ORG_ROLES.ORG_OWNER]: {\n    role: CORE_ORG_ROLES.ORG_OWNER,\n    inheritFrom: CORE_ORG_ROLES.ORG_ADMIN,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  }\n};\n\n"]}
+{"version":3,"file":"roles.shared.defaults.js","sourceRoot":"","sources":["../../../../../src/security/authorizations/roles.shared.defaults.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * App Roles Shared Schemas\n *\n * Application-level roles directly linked to users (not organization-specific)\n * Similar behavior to OrganizationRole but for app-wide permissions\n */\n\nimport { ResourcePrimaryScope } from '../../resources/resources.shared.schemas';\nimport { CORE_APP_ROLES, CORE_ORG_ROLES, RolesConfiguration } from './roles.shared.schemas';\n\nexport const DEFAULT_APP_ROLE_CONFIGURATION: RolesConfiguration = {\n  [CORE_APP_ROLES.APP_PUBLIC]: {\n    role: CORE_APP_ROLES.APP_PUBLIC,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION\n  },\n  [CORE_APP_ROLES.APP_USER]: {\n    role: CORE_APP_ROLES.APP_USER,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION\n  },\n  [CORE_APP_ROLES.APP_ADMIN_VIEWER]: {\n    role: CORE_APP_ROLES.APP_ADMIN_VIEWER,\n    inheritFrom: CORE_APP_ROLES.APP_USER,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION\n  },\n  [CORE_APP_ROLES.APP_ADMIN_MARKETING_EDITOR]: {\n    role: CORE_APP_ROLES.APP_ADMIN_MARKETING_EDITOR,\n    inheritFrom: CORE_APP_ROLES.APP_ADMIN_VIEWER,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION\n  },\n  [CORE_APP_ROLES.APP_ADMIN_BILLING_MANAGER]: {\n    role: CORE_APP_ROLES.APP_ADMIN_BILLING_MANAGER,\n    inheritFrom: CORE_APP_ROLES.APP_ADMIN_VIEWER,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION\n  },\n  [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN]: {\n    role: CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN,\n    inheritFrom: CORE_APP_ROLES.APP_ADMIN_BILLING_MANAGER,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION\n  },\n  // No `inheritFrom`: the reader confers exactly the operations that name it. See the enum member.\n  [CORE_APP_ROLES.APP_AUDIT_EVIDENCE_READER]: {\n    role: CORE_APP_ROLES.APP_AUDIT_EVIDENCE_READER,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION\n  },\n  [CORE_APP_ROLES.APP_ANONYMOUS]: {\n    role: CORE_APP_ROLES.APP_ANONYMOUS,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION\n  },\n};\n\nexport const DEFAULT_ORGANIZATION_ROLES: RolesConfiguration = {\n  [CORE_ORG_ROLES.ORG_GUEST]: {\n    role: CORE_ORG_ROLES.ORG_GUEST,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  },\n  [CORE_ORG_ROLES.ORG_MEMBER]: {\n    role: CORE_ORG_ROLES.ORG_MEMBER,\n    inheritFrom: CORE_ORG_ROLES.ORG_GUEST,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  },\n  [CORE_ORG_ROLES.ORG_MANAGER]: {\n    role: CORE_ORG_ROLES.ORG_MANAGER,\n    inheritFrom: CORE_ORG_ROLES.ORG_MEMBER,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  },\n  [CORE_ORG_ROLES.ORG_ADMIN]: {\n    role: CORE_ORG_ROLES.ORG_ADMIN,\n    inheritFrom: CORE_ORG_ROLES.ORG_MANAGER,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  },\n  [CORE_ORG_ROLES.ORG_OWNER]: {\n    role: CORE_ORG_ROLES.ORG_OWNER,\n    inheritFrom: CORE_ORG_ROLES.ORG_ADMIN,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  }\n};\n\n"]}

package/dist/esm/security/authorizations/roles.shared.schemas.d.ts

@@ -22,6 +22,20 @@ export declare enum CORE_APP_ROLES {
     APP_ADMIN_BILLING_MANAGER = "APP_ADMIN_BILLING_MANAGER",
     APP_ADMIN_MARKETING_EDITOR = "APP_ADMIN_MARKETING_EDITOR",
     APP_ADMIN_VIEWER = "APP_ADMIN_VIEWER",
+    /**
+     * Reads the application-wide audit trail and NOTHING else.
+     *
+     * Exists so the party that attests the application — an assurance evidence collector's machine
+     * credential, or an external auditor — does not have to hold `APP_ADMIN_SUPER_ADMIN`, which until
+     * 2026-09-13 was the only role the application audit door accepted. An auditor holding the largest
+     * standing privilege in the deployment is the concentration `WILDO.ACCESS.PRIVILEGED_REVIEW` exists
+     * to review, so the reader must not be it.
+     *
+     * Inherits from nothing, deliberately: a collector needs no `APP_USER` capability, and inheriting one
+     * would make the role's reach a function of whatever the user tier grows later. Named only by the
+     * application audit-log door's read verbs (`APPLICATION_AUDIT_LOG_READ_ROLES`).
+     */
+    APP_AUDIT_EVIDENCE_READER = "APP_AUDIT_EVIDENCE_READER",
     APP_USER = "APP_USER",
     /** Anonymous session access. Operations with APP_ANONYMOUS are accessible to anonymous users. */
     APP_ANONYMOUS = "APP_ANONYMOUS"

package/dist/esm/security/authorizations/roles.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"roles.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/security/authorizations/roles.shared.schemas.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,0CAA0C,CAAC;AAEhF,oBAAY,cAAc;IACxB;;;;;;;;;;;;;;;OAeG;IACH,UAAU,eAAe;IACzB,qBAAqB,0BAA0B;IAC/C,yBAAyB,8BAA8B;IACvD,0BAA0B,+BAA+B;IACzD,gBAAgB,qBAAqB;IACrC,QAAQ,aAAa;IACrB,iGAAiG;IACjG,aAAa,kBAAkB;CAChC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,qCAAqC,EAAE,SAAS,cAAc,EAKzE,CAAC;AAEH,oBAAY,cAAc;IACxB,SAAS,cAAc;IACvB,SAAS,cAAc;IACvB,SAAS,cAAc;IACvB,WAAW,gBAAgB;IAC3B,UAAU,eAAe;CAC1B;AAGD,eAAO,MAAM,eAAe,2FAG1B,CAAC;AAEH,eAAO,MAAM,WAAW,wGAItB,CAAC;AAEH,eAAO,MAAM,cAAc,sEAGzB,CAAC;AAEH,eAAO,MAAM,cAAc,sEAGzB,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;iBAK/B,CAAC;AAGH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,wBAAwB;;;;;kBAYpC,CAAC;AAEF,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAChD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AACxD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}
+{"version":3,"file":"roles.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/security/authorizations/roles.shared.schemas.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,0CAA0C,CAAC;AAEhF,oBAAY,cAAc;IACxB;;;;;;;;;;;;;;;OAeG;IACH,UAAU,eAAe;IACzB,qBAAqB,0BAA0B;IAC/C,yBAAyB,8BAA8B;IACvD,0BAA0B,+BAA+B;IACzD,gBAAgB,qBAAqB;IACrC;;;;;;;;;;;;OAYG;IACH,yBAAyB,8BAA8B;IACvD,QAAQ,aAAa;IACrB,iGAAiG;IACjG,aAAa,kBAAkB;CAChC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,qCAAqC,EAAE,SAAS,cAAc,EAUzE,CAAC;AAEH,oBAAY,cAAc;IACxB,SAAS,cAAc;IACvB,SAAS,cAAc;IACvB,SAAS,cAAc;IACvB,WAAW,gBAAgB;IAC3B,UAAU,eAAe;CAC1B;AAGD,eAAO,MAAM,eAAe,2FAG1B,CAAC;AAEH,eAAO,MAAM,WAAW,wGAItB,CAAC;AAEH,eAAO,MAAM,cAAc,sEAGzB,CAAC;AAEH,eAAO,MAAM,cAAc,sEAGzB,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;iBAK/B,CAAC;AAGH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,wBAAwB;;;;;kBAYpC,CAAC;AAEF,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAChD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AACxD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/esm/security/authorizations/roles.shared.schemas.js

@@ -23,6 +23,20 @@ export var CORE_APP_ROLES;
     CORE_APP_ROLES["APP_ADMIN_BILLING_MANAGER"] = "APP_ADMIN_BILLING_MANAGER";
     CORE_APP_ROLES["APP_ADMIN_MARKETING_EDITOR"] = "APP_ADMIN_MARKETING_EDITOR";
     CORE_APP_ROLES["APP_ADMIN_VIEWER"] = "APP_ADMIN_VIEWER";
+    /**
+     * Reads the application-wide audit trail and NOTHING else.
+     *
+     * Exists so the party that attests the application — an assurance evidence collector's machine
+     * credential, or an external auditor — does not have to hold `APP_ADMIN_SUPER_ADMIN`, which until
+     * 2026-09-13 was the only role the application audit door accepted. An auditor holding the largest
+     * standing privilege in the deployment is the concentration `WILDO.ACCESS.PRIVILEGED_REVIEW` exists
+     * to review, so the reader must not be it.
+     *
+     * Inherits from nothing, deliberately: a collector needs no `APP_USER` capability, and inheriting one
+     * would make the role's reach a function of whatever the user tier grows later. Named only by the
+     * application audit-log door's read verbs (`APPLICATION_AUDIT_LOG_READ_ROLES`).
+     */
+    CORE_APP_ROLES["APP_AUDIT_EVIDENCE_READER"] = "APP_AUDIT_EVIDENCE_READER";
     CORE_APP_ROLES["APP_USER"] = "APP_USER";
     /** Anonymous session access. Operations with APP_ANONYMOUS are accessible to anonymous users. */
     CORE_APP_ROLES["APP_ANONYMOUS"] = "APP_ANONYMOUS";
@@ -40,6 +54,11 @@ export const CORE_APPLICATION_ADMINISTRATION_ROLES = Object.freeze([
     CORE_APP_ROLES.APP_ADMIN_BILLING_MANAGER,
     CORE_APP_ROLES.APP_ADMIN_MARKETING_EDITOR,
     CORE_APP_ROLES.APP_ADMIN_VIEWER,
+    // Reading the application's own audit trail is oversight of the APPLICATION, not access to its
+    // customer-facing domain — and the API reference files an operation under application
+    // administration only when EVERY role it accepts is in this set, so leaving the reader out would
+    // move the audit door into the customer API reference.
+    CORE_APP_ROLES.APP_AUDIT_EVIDENCE_READER,
 ]);
 export var CORE_ORG_ROLES;
 (function (CORE_ORG_ROLES) {