@wildo-ai/saas-models 1.1.8 → 1.1.10

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 * 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"]}
+{"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.application-roles.example.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Illustrative declaration of an application's own organization role, for the app-facing
+ * `application-roles-authoring` skill.
+ *
+ * TIER B (framework-owned illustrative sample): the reference applications do not show the complete
+ * wiring. Wonder Todos declares `CUSTOM_ORG_SUPERVISOR` but lists it in no `availableOrgRoles` and names
+ * it on no operation, so anchoring it would teach a role nobody can hold and that unlocks nothing.
+ * This sample shows the three places a role must appear, typed against the real contracts.
+ */
+import { type Roles, type RolesConfiguration } from './roles.shared.schemas';
+/**
+ * @wildo_source:part:start example.authorization.application-roles.office-and-field facet:kind:usage-example facet:audience:app-developer
+ *
+ * A trade business with office staff and field technicians. Everything below imports from
+ * `@wildo-ai/saas-models`.
+ *
+ * 1. `shared-lib/src/engine/roles.ts` declares the field role. Office staff need no new role: they hold
+ *    the core `ORG_MEMBER`, so administrators and owners keep everything office staff can do. The field
+ *    role inherits `ORG_GUEST`, the bottom of the chain, so it starts from almost nothing.
+ */
+export declare const CUSTOM_ROLES_CONFIGURATION: RolesConfiguration;
+/**
+ * 2. `wildo.saas.config.ts` → `organizationTypes.<type>.availableOrgRoles` offers it. Omitted, the list
+ *    defaults to owner, admin and member only, so the field role could never be given to anyone.
+ */
+export declare const workspaceAvailableOrgRoles: Roles[];
+/**
+ * 3. Each operation variant's `roles` names who may call it. A holder satisfies a role it holds OR one
+ *    up its `inheritFrom` chain, so `ORG_MEMBER` here admits office staff, managers, admins and owners,
+ *    and the field role must be named explicitly wherever technicians are admitted.
+ */
+/** Jobs: technicians read the jobs and record progress on them. */
+export declare const jobReadAndProgressRoles: Roles[];
+/** Quotes and invoices: office only. A technician holding only the field role is refused. */
+export declare const quoteAndInvoiceRoles: Roles[];
+/** @wildo_source:part:end example.authorization.application-roles.office-and-field */
+//# sourceMappingURL=roles.application-roles.example.d.ts.map

package/dist/esm/security/authorizations/roles.application-roles.example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.application-roles.example.d.ts","sourceRoot":"","sources":["../../../../src/security/authorizations/roles.application-roles.example.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAkB,KAAK,KAAK,EAAE,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAE7F;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,EAAE,kBAOxC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,KAAK,EAK7C,CAAC;AAEF;;;;GAIG;AACH,mEAAmE;AACnE,eAAO,MAAM,uBAAuB,EAAE,KAAK,EAAoD,CAAC;AAChG,6FAA6F;AAC7F,eAAO,MAAM,oBAAoB,EAAE,KAAK,EAAgC,CAAC;AACzE,sFAAsF"}

package/dist/esm/security/authorizations/roles.application-roles.example.js

@@ -0,0 +1,50 @@
+/**
+ * Illustrative declaration of an application's own organization role, for the app-facing
+ * `application-roles-authoring` skill.
+ *
+ * TIER B (framework-owned illustrative sample): the reference applications do not show the complete
+ * wiring. Wonder Todos declares `CUSTOM_ORG_SUPERVISOR` but lists it in no `availableOrgRoles` and names
+ * it on no operation, so anchoring it would teach a role nobody can hold and that unlocks nothing.
+ * This sample shows the three places a role must appear, typed against the real contracts.
+ */
+import { ResourcePrimaryScope } from '../../resources/resources.shared.schemas.js';
+import { CORE_ORG_ROLES } from './roles.shared.schemas.js';
+/**
+ * @wildo_source:part:start example.authorization.application-roles.office-and-field facet:kind:usage-example facet:audience:app-developer
+ *
+ * A trade business with office staff and field technicians. Everything below imports from
+ * `@wildo-ai/saas-models`.
+ *
+ * 1. `shared-lib/src/engine/roles.ts` declares the field role. Office staff need no new role: they hold
+ *    the core `ORG_MEMBER`, so administrators and owners keep everything office staff can do. The field
+ *    role inherits `ORG_GUEST`, the bottom of the chain, so it starts from almost nothing.
+ */
+export const CUSTOM_ROLES_CONFIGURATION = {
+    FIELD_TECHNICIAN: {
+        role: 'FIELD_TECHNICIAN',
+        inheritFrom: CORE_ORG_ROLES.ORG_GUEST,
+        isSystemRole: false,
+        relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS,
+    },
+};
+/**
+ * 2. `wildo.saas.config.ts` → `organizationTypes.<type>.availableOrgRoles` offers it. Omitted, the list
+ *    defaults to owner, admin and member only, so the field role could never be given to anyone.
+ */
+export const workspaceAvailableOrgRoles = [
+    CORE_ORG_ROLES.ORG_OWNER,
+    CORE_ORG_ROLES.ORG_ADMIN,
+    CORE_ORG_ROLES.ORG_MEMBER,
+    'FIELD_TECHNICIAN',
+];
+/**
+ * 3. Each operation variant's `roles` names who may call it. A holder satisfies a role it holds OR one
+ *    up its `inheritFrom` chain, so `ORG_MEMBER` here admits office staff, managers, admins and owners,
+ *    and the field role must be named explicitly wherever technicians are admitted.
+ */
+/** Jobs: technicians read the jobs and record progress on them. */
+export const jobReadAndProgressRoles = ['FIELD_TECHNICIAN', CORE_ORG_ROLES.ORG_MEMBER];
+/** Quotes and invoices: office only. A technician holding only the field role is refused. */
+export const quoteAndInvoiceRoles = [CORE_ORG_ROLES.ORG_MEMBER];
+/** @wildo_source:part:end example.authorization.application-roles.office-and-field */
+//# sourceMappingURL=roles.application-roles.example.js.map

package/dist/esm/security/authorizations/roles.application-roles.example.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.application-roles.example.js","sourceRoot":"","sources":["../../../../src/security/authorizations/roles.application-roles.example.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,0CAA0C,CAAC;AAChF,OAAO,EAAE,cAAc,EAAuC,MAAM,wBAAwB,CAAC;AAE7F;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAuB;IAC5D,gBAAgB,EAAE;QAChB,IAAI,EAAE,kBAAkB;QACxB,WAAW,EAAE,cAAc,CAAC,SAAS;QACrC,YAAY,EAAE,KAAK;QACnB,mBAAmB,EAAE,oBAAoB,CAAC,aAAa;KACxD;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAY;IACjD,cAAc,CAAC,SAAS;IACxB,cAAc,CAAC,SAAS;IACxB,cAAc,CAAC,UAAU;IACzB,kBAAkB;CACnB,CAAC;AAEF;;;;GAIG;AACH,mEAAmE;AACnE,MAAM,CAAC,MAAM,uBAAuB,GAAY,CAAC,kBAAkB,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;AAChG,6FAA6F;AAC7F,MAAM,CAAC,MAAM,oBAAoB,GAAY,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;AACzE,sFAAsF","sourcesContent":["/**\n * Illustrative declaration of an application's own organization role, for the app-facing\n * `application-roles-authoring` skill.\n *\n * TIER B (framework-owned illustrative sample): the reference applications do not show the complete\n * wiring. Wonder Todos declares `CUSTOM_ORG_SUPERVISOR` but lists it in no `availableOrgRoles` and names\n * it on no operation, so anchoring it would teach a role nobody can hold and that unlocks nothing.\n * This sample shows the three places a role must appear, typed against the real contracts.\n */\n\nimport { ResourcePrimaryScope } from '../../resources/resources.shared.schemas';\nimport { CORE_ORG_ROLES, type Roles, type RolesConfiguration } from './roles.shared.schemas';\n\n/**\n * @wildo_source:part:start example.authorization.application-roles.office-and-field facet:kind:usage-example facet:audience:app-developer\n *\n * A trade business with office staff and field technicians. Everything below imports from\n * `@wildo-ai/saas-models`.\n *\n * 1. `shared-lib/src/engine/roles.ts` declares the field role. Office staff need no new role: they hold\n *    the core `ORG_MEMBER`, so administrators and owners keep everything office staff can do. The field\n *    role inherits `ORG_GUEST`, the bottom of the chain, so it starts from almost nothing.\n */\nexport const CUSTOM_ROLES_CONFIGURATION: RolesConfiguration = {\n  FIELD_TECHNICIAN: {\n    role: 'FIELD_TECHNICIAN',\n    inheritFrom: CORE_ORG_ROLES.ORG_GUEST,\n    isSystemRole: false,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS,\n  },\n};\n\n/**\n * 2. `wildo.saas.config.ts` → `organizationTypes.<type>.availableOrgRoles` offers it. Omitted, the list\n *    defaults to owner, admin and member only, so the field role could never be given to anyone.\n */\nexport const workspaceAvailableOrgRoles: Roles[] = [\n  CORE_ORG_ROLES.ORG_OWNER,\n  CORE_ORG_ROLES.ORG_ADMIN,\n  CORE_ORG_ROLES.ORG_MEMBER,\n  'FIELD_TECHNICIAN',\n];\n\n/**\n * 3. Each operation variant's `roles` names who may call it. A holder satisfies a role it holds OR one\n *    up its `inheritFrom` chain, so `ORG_MEMBER` here admits office staff, managers, admins and owners,\n *    and the field role must be named explicitly wherever technicians are admitted.\n */\n/** Jobs: technicians read the jobs and record progress on them. */\nexport const jobReadAndProgressRoles: Roles[] = ['FIELD_TECHNICIAN', CORE_ORG_ROLES.ORG_MEMBER];\n/** Quotes and invoices: office only. A technician holding only the field role is refused. */\nexport const quoteAndInvoiceRoles: Roles[] = [CORE_ORG_ROLES.ORG_MEMBER];\n/** @wildo_source:part:end example.authorization.application-roles.office-and-field */\n"]}

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

@@ -6,5 +6,18 @@
  */
 import { RolesConfiguration } from './roles.shared.schemas';
 export declare const DEFAULT_APP_ROLE_CONFIGURATION: RolesConfiguration;
+/**
+ * @wildo_source:part:start saas.models.roles.organization-defaults facet:layer:shared facet:audience:app-developer
+ *
+ * The organization roles the engine ships, and how they inherit. Read it to choose what a custom role
+ * should `inheritFrom` and which roles an operation must name.
+ *
+ * The person-holdable chain is linear: `ORG_OWNER → ORG_ADMIN → ORG_MANAGER → ORG_MEMBER → ORG_GUEST`
+ * (each holds everything to its right). `ORG_SERVICE_PROVIDER` hangs off `ORG_MEMBER` for experts of a
+ * service firm. The entries after `ORG_OWNER` are handler-only or delegated-capability roles: the
+ * engine confers them (an inbound handler, a live capability grant), they are never stored on a
+ * membership, and a membership naming one is refused. Never inherit from them or assign them.
+ */
 export declare const DEFAULT_ORGANIZATION_ROLES: RolesConfiguration;
+/** @wildo_source:part:end saas.models.roles.organization-defaults */
 //# sourceMappingURL=roles.shared.defaults.d.ts.map

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,kBA0D5C,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,kBA0ExC,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,kBA0D5C,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,EAAE,kBA0ExC,CAAC;AACF,qEAAqE"}

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

@@ -65,6 +65,18 @@ export const DEFAULT_APP_ROLE_CONFIGURATION = {
         relatedPrimaryScope: ResourcePrimaryScope.APPLICATION
     },
 };
+/**
+ * @wildo_source:part:start saas.models.roles.organization-defaults facet:layer:shared facet:audience:app-developer
+ *
+ * The organization roles the engine ships, and how they inherit. Read it to choose what a custom role
+ * should `inheritFrom` and which roles an operation must name.
+ *
+ * The person-holdable chain is linear: `ORG_OWNER → ORG_ADMIN → ORG_MANAGER → ORG_MEMBER → ORG_GUEST`
+ * (each holds everything to its right). `ORG_SERVICE_PROVIDER` hangs off `ORG_MEMBER` for experts of a
+ * service firm. The entries after `ORG_OWNER` are handler-only or delegated-capability roles: the
+ * engine confers them (an inbound handler, a live capability grant), they are never stored on a
+ * membership, and a membership naming one is refused. Never inherit from them or assign them.
+ */
 export const DEFAULT_ORGANIZATION_ROLES = {
     [CORE_ORG_ROLES.ORG_GUEST]: {
         role: CORE_ORG_ROLES.ORG_GUEST,
@@ -140,4 +152,5 @@ export const DEFAULT_ORGANIZATION_ROLES = {
         relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS
     }
 };
+/** @wildo_source:part:end saas.models.roles.organization-defaults */
 //# sourceMappingURL=roles.shared.defaults.js.map

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  // 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  // No `inheritFrom`: handler-only, confers exactly the billing operations that name it (#1629).\n  [CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS]: {\n    role: CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION\n  },\n  // No `inheritFrom`: handler-only, and no operation names it — the email intake writes as the engine (#1600).\n  [CORE_APP_ROLES.APP_EMAIL_INBOUND_INTAKE]: {\n    role: CORE_APP_ROLES.APP_EMAIL_INBOUND_INTAKE,\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_SERVICE_PROVIDER]: {\n    role: CORE_ORG_ROLES.ORG_SERVICE_PROVIDER,\n    inheritFrom: CORE_ORG_ROLES.ORG_MEMBER,\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  // No `inheritFrom`: handler-only, confers exactly the billing operations that name it (#1629).\n  [CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS]: {\n    role: CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  },\n  // No `inheritFrom` on any delegated capability (#1631): each confers exactly the operations that name it, and\n  // inheriting anything would make a lent capability's reach a function of what that role grows into later.\n  [CORE_ORG_ROLES.ORG_DELEGATED_INVITE_MEMBERS]: {\n    role: CORE_ORG_ROLES.ORG_DELEGATED_INVITE_MEMBERS,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  },\n  [CORE_ORG_ROLES.ORG_DELEGATED_MANAGE_RELATIONSHIP_EXPERTS]: {\n    role: CORE_ORG_ROLES.ORG_DELEGATED_MANAGE_RELATIONSHIP_EXPERTS,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  },\n  [CORE_ORG_ROLES.ORG_DELEGATED_READ_AUDIT_TRAIL]: {\n    role: CORE_ORG_ROLES.ORG_DELEGATED_READ_AUDIT_TRAIL,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  },\n  [CORE_ORG_ROLES.ORG_DELEGATED_MANAGE_SSO_SCIM]: {\n    role: CORE_ORG_ROLES.ORG_DELEGATED_MANAGE_SSO_SCIM,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  },\n  [CORE_ORG_ROLES.ORG_DELEGATED_MANAGE_API_KEYS]: {\n    role: CORE_ORG_ROLES.ORG_DELEGATED_MANAGE_API_KEYS,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  },\n  [CORE_ORG_ROLES.ORG_DELEGATED_APPROVE_ACCESS_GRANTS]: {\n    role: CORE_ORG_ROLES.ORG_DELEGATED_APPROVE_ACCESS_GRANTS,\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  // No `inheritFrom`: handler-only, confers exactly the billing operations that name it (#1629).\n  [CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS]: {\n    role: CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION\n  },\n  // No `inheritFrom`: handler-only, and no operation names it — the email intake writes as the engine (#1600).\n  [CORE_APP_ROLES.APP_EMAIL_INBOUND_INTAKE]: {\n    role: CORE_APP_ROLES.APP_EMAIL_INBOUND_INTAKE,\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\n/**\n * @wildo_source:part:start saas.models.roles.organization-defaults facet:layer:shared facet:audience:app-developer\n *\n * The organization roles the engine ships, and how they inherit. Read it to choose what a custom role\n * should `inheritFrom` and which roles an operation must name.\n *\n * The person-holdable chain is linear: `ORG_OWNER → ORG_ADMIN → ORG_MANAGER → ORG_MEMBER → ORG_GUEST`\n * (each holds everything to its right). `ORG_SERVICE_PROVIDER` hangs off `ORG_MEMBER` for experts of a\n * service firm. The entries after `ORG_OWNER` are handler-only or delegated-capability roles: the\n * engine confers them (an inbound handler, a live capability grant), they are never stored on a\n * membership, and a membership naming one is refused. Never inherit from them or assign them.\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_SERVICE_PROVIDER]: {\n    role: CORE_ORG_ROLES.ORG_SERVICE_PROVIDER,\n    inheritFrom: CORE_ORG_ROLES.ORG_MEMBER,\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  // No `inheritFrom`: handler-only, confers exactly the billing operations that name it (#1629).\n  [CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS]: {\n    role: CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  },\n  // No `inheritFrom` on any delegated capability (#1631): each confers exactly the operations that name it, and\n  // inheriting anything would make a lent capability's reach a function of what that role grows into later.\n  [CORE_ORG_ROLES.ORG_DELEGATED_INVITE_MEMBERS]: {\n    role: CORE_ORG_ROLES.ORG_DELEGATED_INVITE_MEMBERS,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  },\n  [CORE_ORG_ROLES.ORG_DELEGATED_MANAGE_RELATIONSHIP_EXPERTS]: {\n    role: CORE_ORG_ROLES.ORG_DELEGATED_MANAGE_RELATIONSHIP_EXPERTS,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  },\n  [CORE_ORG_ROLES.ORG_DELEGATED_READ_AUDIT_TRAIL]: {\n    role: CORE_ORG_ROLES.ORG_DELEGATED_READ_AUDIT_TRAIL,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  },\n  [CORE_ORG_ROLES.ORG_DELEGATED_MANAGE_SSO_SCIM]: {\n    role: CORE_ORG_ROLES.ORG_DELEGATED_MANAGE_SSO_SCIM,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  },\n  [CORE_ORG_ROLES.ORG_DELEGATED_MANAGE_API_KEYS]: {\n    role: CORE_ORG_ROLES.ORG_DELEGATED_MANAGE_API_KEYS,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  },\n  [CORE_ORG_ROLES.ORG_DELEGATED_APPROVE_ACCESS_GRANTS]: {\n    role: CORE_ORG_ROLES.ORG_DELEGATED_APPROVE_ACCESS_GRANTS,\n    isSystemRole: true,\n    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS\n  }\n};\n/** @wildo_source:part:end saas.models.roles.organization-defaults */\n\n"]}

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

@@ -136,6 +136,34 @@ export declare const CoreRolesSchema: z.ZodUnion<readonly [z.ZodEnum<typeof CORE
 export declare const RolesSchema: z.ZodUnion<readonly [z.ZodEnum<typeof CORE_APP_ROLES>, z.ZodEnum<typeof CORE_ORG_ROLES>, z.ZodString]>;
 export declare const AppRolesSchema: z.ZodUnion<readonly [z.ZodEnum<typeof CORE_APP_ROLES>, z.ZodString]>;
 export declare const OrgRolesSchema: z.ZodUnion<readonly [z.ZodEnum<typeof CORE_ORG_ROLES>, z.ZodString]>;
+/**
+ * @wildo_source:part:start saas.models.roles.definition facet:layer:shared facet:audience:app-developer
+ *
+ * One role an application declares, and the table of them. Import from `@wildo-ai/saas-models`
+ * (`RolesConfiguration`, `CORE_ORG_ROLES`, `CORE_APP_ROLES`, `ResourcePrimaryScope`).
+ *
+ * An application's own roles live in ONE place: `CUSTOM_ROLES_CONFIGURATION` in
+ * `shared-lib/src/engine/roles.ts`, a `RolesConfiguration` keyed by the role's name. Nothing else
+ * declares a role — never a resource holding role names or permission lists, which the engine does not
+ * read.
+ *
+ * - `role` — the role's name, equal to its key. Any string; prefer a stable upper-snake name
+ *   (`FIELD_TECHNICIAN`).
+ * - `inheritFrom` — the role whose access this one also receives. A holder of a role satisfies every
+ *   operation naming that role OR any role up its `inheritFrom` chain. The core organization chain is
+ *   linear: `ORG_OWNER → ORG_ADMIN → ORG_MANAGER → ORG_MEMBER → ORG_GUEST`. So a custom role inheriting
+ *   `ORG_MEMBER` is NOT held by an `ORG_ADMIN`: to let administrators do what the custom role does,
+ *   name both roles on the operation.
+ * - `isSystemRole` — `false` for every role an application declares.
+ * - `relatedPrimaryScope` — `ResourcePrimaryScope.ORGANIZATIONS` for a role a member holds inside one
+ *   organization, `ResourcePrimaryScope.APPLICATION` for an application-wide role. Any other scope is
+ *   ignored at startup with a warning, and the role grants nothing.
+ *
+ * Declaring a role is one of three steps. An organization role must also be listed in
+ * `organizationTypes.<type>.availableOrgRoles` of `wildo.saas.config.ts` (or no member can be given
+ * it), and it must be named in the `roles` of the operation variants it unlocks (or holding it changes
+ * nothing). People receive it through the engine's members screen and invitations.
+ */
 export declare const RoleDefinitionSchema: z.ZodObject<{
     role: z.ZodUnion<readonly [z.ZodEnum<typeof CORE_APP_ROLES>, z.ZodEnum<typeof CORE_ORG_ROLES>, z.ZodString]>;
     inheritFrom: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof CORE_APP_ROLES>, z.ZodEnum<typeof CORE_ORG_ROLES>, z.ZodString]>>;
@@ -149,6 +177,7 @@ export declare const RolesConfigurationSchema: z.ZodRecord<z.ZodString, z.ZodObj
     isSystemRole: z.ZodDefault<z.ZodBoolean>;
     relatedPrimaryScope: z.ZodEnum<typeof ResourcePrimaryScope>;
 }, z.core.$strip>>;
+/** @wildo_source:part:end saas.models.roles.definition */
 export type Roles = z.infer<typeof RolesSchema>;
 export type CoreRoles = z.infer<typeof CoreRolesSchema>;
 export type AppRoles = z.infer<typeof AppRolesSchema>;

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;;;;;;;;;;;;OAYG;IACH,yBAAyB,8BAA8B;IACvD;;;;;;;;OAQG;IACH,2BAA2B,gCAAgC;IAC3D;;;;;;;;OAQG;IACH,wBAAwB,6BAA6B;IACrD,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;IACzB;;;;;;OAMG;IACH,oBAAoB,yBAAyB;IAC7C;;;;;;;;;;;OAWG;IACH,2BAA2B,gCAAgC;IAQ3D,6EAA6E;IAC7E,4BAA4B,iCAAiC;IAC7D,mGAAmG;IACnG,yCAAyC,8CAA8C;IACvF,2CAA2C;IAC3C,8BAA8B,mCAAmC;IACjE,4GAA4G;IAC5G,6BAA6B,kCAAkC;IAC/D,wFAAwF;IACxF,6BAA6B,kCAAkC;IAC/D,0HAA0H;IAC1H,mCAAmC,wCAAwC;CAC5E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,MAAM,CAIzD,CAAC;AAEH,yEAAyE;AACzE,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9D;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;;;;;;;;OAQG;IACH,2BAA2B,gCAAgC;IAC3D;;;;;;;;OAQG;IACH,wBAAwB,6BAA6B;IACrD,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;IACzB;;;;;;OAMG;IACH,oBAAoB,yBAAyB;IAC7C;;;;;;;;;;;OAWG;IACH,2BAA2B,gCAAgC;IAQ3D,6EAA6E;IAC7E,4BAA4B,iCAAiC;IAC7D,mGAAmG;IACnG,yCAAyC,8CAA8C;IACvF,2CAA2C;IAC3C,8BAA8B,mCAAmC;IACjE,4GAA4G;IAC5G,6BAA6B,kCAAkC;IAC/D,wFAAwF;IACxF,6BAA6B,kCAAkC;IAC/D,0HAA0H;IAC1H,mCAAmC,wCAAwC;CAC5E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,MAAM,CAIzD,CAAC;AAEH,yEAAyE;AACzE,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9D;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;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,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;AACF,0DAA0D;AAE1D,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

@@ -175,6 +175,34 @@ export const OrgRolesSchema = z.union([
     z.enum(CORE_ORG_ROLES),
     z.string().min(1),
 ]);
+/**
+ * @wildo_source:part:start saas.models.roles.definition facet:layer:shared facet:audience:app-developer
+ *
+ * One role an application declares, and the table of them. Import from `@wildo-ai/saas-models`
+ * (`RolesConfiguration`, `CORE_ORG_ROLES`, `CORE_APP_ROLES`, `ResourcePrimaryScope`).
+ *
+ * An application's own roles live in ONE place: `CUSTOM_ROLES_CONFIGURATION` in
+ * `shared-lib/src/engine/roles.ts`, a `RolesConfiguration` keyed by the role's name. Nothing else
+ * declares a role — never a resource holding role names or permission lists, which the engine does not
+ * read.
+ *
+ * - `role` — the role's name, equal to its key. Any string; prefer a stable upper-snake name
+ *   (`FIELD_TECHNICIAN`).
+ * - `inheritFrom` — the role whose access this one also receives. A holder of a role satisfies every
+ *   operation naming that role OR any role up its `inheritFrom` chain. The core organization chain is
+ *   linear: `ORG_OWNER → ORG_ADMIN → ORG_MANAGER → ORG_MEMBER → ORG_GUEST`. So a custom role inheriting
+ *   `ORG_MEMBER` is NOT held by an `ORG_ADMIN`: to let administrators do what the custom role does,
+ *   name both roles on the operation.
+ * - `isSystemRole` — `false` for every role an application declares.
+ * - `relatedPrimaryScope` — `ResourcePrimaryScope.ORGANIZATIONS` for a role a member holds inside one
+ *   organization, `ResourcePrimaryScope.APPLICATION` for an application-wide role. Any other scope is
+ *   ignored at startup with a warning, and the role grants nothing.
+ *
+ * Declaring a role is one of three steps. An organization role must also be listed in
+ * `organizationTypes.<type>.availableOrgRoles` of `wildo.saas.config.ts` (or no member can be given
+ * it), and it must be named in the `roles` of the operation variants it unlocks (or holding it changes
+ * nothing). People receive it through the engine's members screen and invitations.
+ */
 export const RoleDefinitionSchema = z.object({
     role: RolesSchema,
     inheritFrom: RolesSchema.optional(),

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

@@ -1 +1 @@
-{"version":3,"file":"roles.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/security/authorizations/roles.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["\nimport { z } from 'zod';\nimport { ResourcePrimaryScope } from '../../resources/resources.shared.schemas';\n\nexport enum CORE_APP_ROLES {\n  /**\n   * Open access: an operation declaring `APP_PUBLIC` requires NO credential, and imposes no role\n   * requirement on one that is presented.\n   *\n   * Not a role anybody is granted — a SENTINEL on the operation's `roles`, which is why the two\n   * halves above have to be stated together. \"Accessible without auth\" was the whole comment until\n   * 2026-08-31, and it was read as *reachable only when unauthenticated*: every role gate then\n   * refused a credentialed caller, so a public price list, catalogue or i18n bundle answered 200 to\n   * an anonymous probe and 403 to a logged-in customer (#153). Authenticating must never take access\n   * away.\n   *\n   * `requiredRolesDeclarePublicAccess` in `roles.shared.utils.ts` is the runtime source of this\n   * meaning; every gate consults it rather than re-deriving the test. Scope, tenancy and the\n   * repository's contextual filter are untouched by the declaration — it says no role is required to\n   * ASK, never that no scope confines the answer.\n   */\n  APP_PUBLIC = 'APP_PUBLIC',\n  APP_ADMIN_SUPER_ADMIN = 'APP_ADMIN_SUPER_ADMIN',\n  APP_ADMIN_BILLING_MANAGER = 'APP_ADMIN_BILLING_MANAGER',\n  APP_ADMIN_MARKETING_EDITOR = 'APP_ADMIN_MARKETING_EDITOR',\n  APP_ADMIN_VIEWER = 'APP_ADMIN_VIEWER',\n  /**\n   * Reads the application-wide audit trail and NOTHING else.\n   *\n   * Exists so the party that attests the application — an assurance evidence collector's machine\n   * credential, or an external auditor — does not have to hold `APP_ADMIN_SUPER_ADMIN`, which until\n   * 2026-09-13 was the only role the application audit door accepted. An auditor holding the largest\n   * standing privilege in the deployment is the concentration `WILDO.ACCESS.PRIVILEGED_REVIEW` exists\n   * to review, so the reader must not be it.\n   *\n   * Inherits from nothing, deliberately: a collector needs no `APP_USER` capability, and inheriting one\n   * would make the role's reach a function of whatever the user tier grows later. Named only by the\n   * application audit-log door's read verbs (`APPLICATION_AUDIT_LOG_READ_ROLES`).\n   */\n  APP_AUDIT_EVIDENCE_READER = 'APP_AUDIT_EVIDENCE_READER',\n  /**\n   * The engine's billing inbound handler, acting on a signature-verified provider event that belongs to ONE\n   * person's billing account (#1629). The user-scope twin of `ORG_BILLING_PROVIDER_EVENTS`: personal\n   * (`USER_SELF`) billing variants gate on application roles, so the handler's authority there is an\n   * application role, confined to the delivery's scope user by the ownership check.\n   *\n   * HANDLER-ONLY — a member of {@link INBOUND_HANDLER_ONLY_ROLES}. It confers nothing to a person, an API\n   * key or an OAuth client, and inherits from nothing: it grants exactly the billing operations that name it.\n   */\n  APP_BILLING_PROVIDER_EVENTS = 'APP_BILLING_PROVIDER_EVENTS',\n  /**\n   * The engine's email intake (#1600): the stage-1 handler that fetches a received message from the provider,\n   * routes each recipient address to an organization, stores the message and hands it to the email channel.\n   * It writes as the engine's infrastructure and calls NO resource operation, so no operation names this role\n   * and it grants nothing — it exists because an application-scope delivery must run as SOME role, and every\n   * other role would grant something.\n   *\n   * HANDLER-ONLY — a member of {@link INBOUND_HANDLER_ONLY_ROLES}. Inherits from nothing.\n   */\n  APP_EMAIL_INBOUND_INTAKE = 'APP_EMAIL_INBOUND_INTAKE',\n  APP_USER = 'APP_USER',\n  /** Anonymous session access. Operations with APP_ANONYMOUS are accessible to anonymous users. */\n  APP_ANONYMOUS = 'APP_ANONYMOUS',\n}\n\n/**\n * Authorities that administer the generated application itself.\n *\n * This named subset is the canonical boundary used by consumer-facing\n * products such as the API reference. It prevents each downstream consumer\n * from guessing administrative meaning from `APP_ADMIN_` spelling or copying\n * an independent list that drifts when the role vocabulary evolves.\n */\nexport const CORE_APPLICATION_ADMINISTRATION_ROLES: readonly CORE_APP_ROLES[] = Object.freeze([\n  CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN,\n  CORE_APP_ROLES.APP_ADMIN_BILLING_MANAGER,\n  CORE_APP_ROLES.APP_ADMIN_MARKETING_EDITOR,\n  CORE_APP_ROLES.APP_ADMIN_VIEWER,\n  // Reading the application's own audit trail is oversight of the APPLICATION, not access to its\n  // customer-facing domain — and the API reference files an operation under application\n  // administration only when EVERY role it accepts is in this set, so leaving the reader out would\n  // move the audit door into the customer API reference.\n  CORE_APP_ROLES.APP_AUDIT_EVIDENCE_READER,\n]);\n\nexport enum CORE_ORG_ROLES {\n  ORG_GUEST = 'ORG_GUEST',\n  ORG_OWNER = 'ORG_OWNER',\n  ORG_ADMIN = 'ORG_ADMIN',\n  ORG_MANAGER = 'ORG_MANAGER',\n  ORG_MEMBER = 'ORG_MEMBER',\n  /**\n   * An expert of a SERVICE FIRM working inside this organization under a service-provider relationship\n   * the organization controls (`SERVICE_PROVIDER_RELATIONSHIPS`). Inherits `ORG_MEMBER`, never more:\n   * the relationship's role may be any role the client type makes available EXCEPT one that leads up to\n   * `ORG_ADMIN`, which startup refuses. Administrative authority is never conferred by a relationship by\n   * default (delegated administration is a separate, narrow, time-bound grant).\n   */\n  ORG_SERVICE_PROVIDER = 'ORG_SERVICE_PROVIDER',\n  /**\n   * The engine's billing inbound handler, acting on a signature-verified provider event that belongs to ONE\n   * organization's billing account (#1629). It replaced the role-free `WEBHOOK_CALLBACK` bypass, under which\n   * every billing webhook write ran with no role check and no tenant filter.\n   *\n   * Grants exactly what the event handlers do and nothing more: read the organization's billing account,\n   * subscriptions, invoice references and credit pools; create and update subscriptions and invoice\n   * references; create a credit pool and top it up; deactivate the billing account. Inherits from nothing.\n   *\n   * HANDLER-ONLY — a member of {@link INBOUND_HANDLER_ONLY_ROLES}. It confers nothing to a person, an API\n   * key or an OAuth client.\n   */\n  ORG_BILLING_PROVIDER_EVENTS = 'ORG_BILLING_PROVIDER_EVENTS',\n  /*\n   * DELEGATED ADMINISTRATIVE CAPABILITIES (#1631) — one role per `DelegatedAdministrativeCapability`, conferred ONLY by\n   * a live `SERVICE_PROVIDER_CAPABILITY_GRANTS` row to a service firm's experts, through the execution-context live\n   * filter; the member role doors refuse them on any membership row. Each inherits from NOTHING and is listed\n   * explicitly, beside `ORG_ADMIN`, in the `roles` of exactly the core operations it opens — so it confers those\n   * operations and no others, and never leads to `ORG_ADMIN` / `ORG_OWNER` (startup refuses a capability role that does).\n   */\n  /** Invite people into the organization, resend an invitation, revoke one. */\n  ORG_DELEGATED_INVITE_MEMBERS = 'ORG_DELEGATED_INVITE_MEMBERS',\n  /** Suspend, reactivate or remove the delegating firm's OWN experts under the same relationship. */\n  ORG_DELEGATED_MANAGE_RELATIONSHIP_EXPERTS = 'ORG_DELEGATED_MANAGE_RELATIONSHIP_EXPERTS',\n  /** Read the organization's audit trail. */\n  ORG_DELEGATED_READ_AUDIT_TRAIL = 'ORG_DELEGATED_READ_AUDIT_TRAIL',\n  /** Configure the organization's SSO and SCIM provisioning. Security-critical: owner-granted, time-bound. */\n  ORG_DELEGATED_MANAGE_SSO_SCIM = 'ORG_DELEGATED_MANAGE_SSO_SCIM',\n  /** Manage the organization's API keys. Security-critical: owner-granted, time-bound. */\n  ORG_DELEGATED_MANAGE_API_KEYS = 'ORG_DELEGATED_MANAGE_API_KEYS',\n  /** Approve or deny, as the tenant, a platform operator's access request. Security-critical: owner-granted, time-bound. */\n  ORG_DELEGATED_APPROVE_ACCESS_GRANTS = 'ORG_DELEGATED_APPROVE_ACCESS_GRANTS',\n}\n\n/**\n * Roles only an ENGINE inbound handler may act with (#1629) — never a person, an API key, an OAuth client or\n * an application's own handler.\n *\n * ## Why a named set, and where it is enforced\n *\n * A role is granted through many doors — organization and unit memberships, a user's application roles,\n * invitations, SSO and SCIM mappings, machine credentials — and several of them accept any string (the\n * member-role check is skipped entirely when an application declares no organization types). Guarding each\n * door would be the one-of-N shape `invariant-call-site-enumeration.md` records. So the set is enforced where\n * every principal converges instead:\n *\n * - the `ExecutionContext` constructor refuses a context carrying one of these roles unless it is an\n *   `INBOUND_DELIVERY` context, so a grant that slipped through any door cannot confer anything;\n * - the inbound handler registry refuses them in an application handler's `actingRoles`, so only the engine's\n *   own handler, which declares the engine capability, may act with them.\n *\n * The write doors that are cheap to guard (the organization member roles) refuse them too, so a mistaken grant\n * is answered where it is made rather than when the member next signs in.\n */\n// assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — the roles cut for one engine handler's writes confer nothing to any other principal (#1629).\nexport const INBOUND_HANDLER_ONLY_ROLES: ReadonlySet<string> = new Set<string>([\n  CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS,\n  CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS,\n  CORE_APP_ROLES.APP_EMAIL_INBOUND_INTAKE,\n]);\n\n/** Whether `role` is one only an engine inbound handler may act with. */\nexport function isInboundHandlerOnlyRole(role: string): boolean {\n  return INBOUND_HANDLER_ONLY_ROLES.has(role);\n}\n\n\nexport const CoreRolesSchema = z.union([\n  z.enum(CORE_APP_ROLES),\n  z.enum(CORE_ORG_ROLES),\n]);\n\nexport const RolesSchema = z.union([\n  z.enum(CORE_APP_ROLES),\n  z.enum(CORE_ORG_ROLES),\n  z.string().min(1),\n]);\n\nexport const AppRolesSchema = z.union([\n  z.enum(CORE_APP_ROLES),\n  z.string().min(1),\n]);\n\nexport const OrgRolesSchema = z.union([\n  z.enum(CORE_ORG_ROLES),\n  z.string().min(1),\n]);\n\nexport const RoleDefinitionSchema = z.object({\n  role: RolesSchema,\n  inheritFrom: RolesSchema.optional(),\n  isSystemRole: z.boolean().default(false),\n  relatedPrimaryScope : z.enum(ResourcePrimaryScope),\n});\n\n\nexport type RoleDefinition = z.infer<typeof RoleDefinitionSchema>;\n\nexport const RolesConfigurationSchema = z.record(z.string(), RoleDefinitionSchema).refine(\n  (record) => {\n    // Validate that all keys are valid roles\n    return Object.keys(record).every(key => {\n      try {\n        RolesSchema.parse(key);\n        return true;\n      } catch {\n        return false;\n      }\n    });\n  }\n);\n\nexport type Roles = z.infer<typeof RolesSchema>;\nexport type CoreRoles = z.infer<typeof CoreRolesSchema>;\nexport type AppRoles = z.infer<typeof AppRolesSchema>;\nexport type OrgRoles = z.infer<typeof OrgRolesSchema>;\nexport type RolesConfiguration = z.infer<typeof RolesConfigurationSchema>;\n"]}
+{"version":3,"file":"roles.shared.schemas.js","sourceRoot":"","sources":["../../../../src/security/authorizations/roles.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["\nimport { z } from 'zod';\nimport { ResourcePrimaryScope } from '../../resources/resources.shared.schemas';\n\nexport enum CORE_APP_ROLES {\n  /**\n   * Open access: an operation declaring `APP_PUBLIC` requires NO credential, and imposes no role\n   * requirement on one that is presented.\n   *\n   * Not a role anybody is granted — a SENTINEL on the operation's `roles`, which is why the two\n   * halves above have to be stated together. \"Accessible without auth\" was the whole comment until\n   * 2026-08-31, and it was read as *reachable only when unauthenticated*: every role gate then\n   * refused a credentialed caller, so a public price list, catalogue or i18n bundle answered 200 to\n   * an anonymous probe and 403 to a logged-in customer (#153). Authenticating must never take access\n   * away.\n   *\n   * `requiredRolesDeclarePublicAccess` in `roles.shared.utils.ts` is the runtime source of this\n   * meaning; every gate consults it rather than re-deriving the test. Scope, tenancy and the\n   * repository's contextual filter are untouched by the declaration — it says no role is required to\n   * ASK, never that no scope confines the answer.\n   */\n  APP_PUBLIC = 'APP_PUBLIC',\n  APP_ADMIN_SUPER_ADMIN = 'APP_ADMIN_SUPER_ADMIN',\n  APP_ADMIN_BILLING_MANAGER = 'APP_ADMIN_BILLING_MANAGER',\n  APP_ADMIN_MARKETING_EDITOR = 'APP_ADMIN_MARKETING_EDITOR',\n  APP_ADMIN_VIEWER = 'APP_ADMIN_VIEWER',\n  /**\n   * Reads the application-wide audit trail and NOTHING else.\n   *\n   * Exists so the party that attests the application — an assurance evidence collector's machine\n   * credential, or an external auditor — does not have to hold `APP_ADMIN_SUPER_ADMIN`, which until\n   * 2026-09-13 was the only role the application audit door accepted. An auditor holding the largest\n   * standing privilege in the deployment is the concentration `WILDO.ACCESS.PRIVILEGED_REVIEW` exists\n   * to review, so the reader must not be it.\n   *\n   * Inherits from nothing, deliberately: a collector needs no `APP_USER` capability, and inheriting one\n   * would make the role's reach a function of whatever the user tier grows later. Named only by the\n   * application audit-log door's read verbs (`APPLICATION_AUDIT_LOG_READ_ROLES`).\n   */\n  APP_AUDIT_EVIDENCE_READER = 'APP_AUDIT_EVIDENCE_READER',\n  /**\n   * The engine's billing inbound handler, acting on a signature-verified provider event that belongs to ONE\n   * person's billing account (#1629). The user-scope twin of `ORG_BILLING_PROVIDER_EVENTS`: personal\n   * (`USER_SELF`) billing variants gate on application roles, so the handler's authority there is an\n   * application role, confined to the delivery's scope user by the ownership check.\n   *\n   * HANDLER-ONLY — a member of {@link INBOUND_HANDLER_ONLY_ROLES}. It confers nothing to a person, an API\n   * key or an OAuth client, and inherits from nothing: it grants exactly the billing operations that name it.\n   */\n  APP_BILLING_PROVIDER_EVENTS = 'APP_BILLING_PROVIDER_EVENTS',\n  /**\n   * The engine's email intake (#1600): the stage-1 handler that fetches a received message from the provider,\n   * routes each recipient address to an organization, stores the message and hands it to the email channel.\n   * It writes as the engine's infrastructure and calls NO resource operation, so no operation names this role\n   * and it grants nothing — it exists because an application-scope delivery must run as SOME role, and every\n   * other role would grant something.\n   *\n   * HANDLER-ONLY — a member of {@link INBOUND_HANDLER_ONLY_ROLES}. Inherits from nothing.\n   */\n  APP_EMAIL_INBOUND_INTAKE = 'APP_EMAIL_INBOUND_INTAKE',\n  APP_USER = 'APP_USER',\n  /** Anonymous session access. Operations with APP_ANONYMOUS are accessible to anonymous users. */\n  APP_ANONYMOUS = 'APP_ANONYMOUS',\n}\n\n/**\n * Authorities that administer the generated application itself.\n *\n * This named subset is the canonical boundary used by consumer-facing\n * products such as the API reference. It prevents each downstream consumer\n * from guessing administrative meaning from `APP_ADMIN_` spelling or copying\n * an independent list that drifts when the role vocabulary evolves.\n */\nexport const CORE_APPLICATION_ADMINISTRATION_ROLES: readonly CORE_APP_ROLES[] = Object.freeze([\n  CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN,\n  CORE_APP_ROLES.APP_ADMIN_BILLING_MANAGER,\n  CORE_APP_ROLES.APP_ADMIN_MARKETING_EDITOR,\n  CORE_APP_ROLES.APP_ADMIN_VIEWER,\n  // Reading the application's own audit trail is oversight of the APPLICATION, not access to its\n  // customer-facing domain — and the API reference files an operation under application\n  // administration only when EVERY role it accepts is in this set, so leaving the reader out would\n  // move the audit door into the customer API reference.\n  CORE_APP_ROLES.APP_AUDIT_EVIDENCE_READER,\n]);\n\nexport enum CORE_ORG_ROLES {\n  ORG_GUEST = 'ORG_GUEST',\n  ORG_OWNER = 'ORG_OWNER',\n  ORG_ADMIN = 'ORG_ADMIN',\n  ORG_MANAGER = 'ORG_MANAGER',\n  ORG_MEMBER = 'ORG_MEMBER',\n  /**\n   * An expert of a SERVICE FIRM working inside this organization under a service-provider relationship\n   * the organization controls (`SERVICE_PROVIDER_RELATIONSHIPS`). Inherits `ORG_MEMBER`, never more:\n   * the relationship's role may be any role the client type makes available EXCEPT one that leads up to\n   * `ORG_ADMIN`, which startup refuses. Administrative authority is never conferred by a relationship by\n   * default (delegated administration is a separate, narrow, time-bound grant).\n   */\n  ORG_SERVICE_PROVIDER = 'ORG_SERVICE_PROVIDER',\n  /**\n   * The engine's billing inbound handler, acting on a signature-verified provider event that belongs to ONE\n   * organization's billing account (#1629). It replaced the role-free `WEBHOOK_CALLBACK` bypass, under which\n   * every billing webhook write ran with no role check and no tenant filter.\n   *\n   * Grants exactly what the event handlers do and nothing more: read the organization's billing account,\n   * subscriptions, invoice references and credit pools; create and update subscriptions and invoice\n   * references; create a credit pool and top it up; deactivate the billing account. Inherits from nothing.\n   *\n   * HANDLER-ONLY — a member of {@link INBOUND_HANDLER_ONLY_ROLES}. It confers nothing to a person, an API\n   * key or an OAuth client.\n   */\n  ORG_BILLING_PROVIDER_EVENTS = 'ORG_BILLING_PROVIDER_EVENTS',\n  /*\n   * DELEGATED ADMINISTRATIVE CAPABILITIES (#1631) — one role per `DelegatedAdministrativeCapability`, conferred ONLY by\n   * a live `SERVICE_PROVIDER_CAPABILITY_GRANTS` row to a service firm's experts, through the execution-context live\n   * filter; the member role doors refuse them on any membership row. Each inherits from NOTHING and is listed\n   * explicitly, beside `ORG_ADMIN`, in the `roles` of exactly the core operations it opens — so it confers those\n   * operations and no others, and never leads to `ORG_ADMIN` / `ORG_OWNER` (startup refuses a capability role that does).\n   */\n  /** Invite people into the organization, resend an invitation, revoke one. */\n  ORG_DELEGATED_INVITE_MEMBERS = 'ORG_DELEGATED_INVITE_MEMBERS',\n  /** Suspend, reactivate or remove the delegating firm's OWN experts under the same relationship. */\n  ORG_DELEGATED_MANAGE_RELATIONSHIP_EXPERTS = 'ORG_DELEGATED_MANAGE_RELATIONSHIP_EXPERTS',\n  /** Read the organization's audit trail. */\n  ORG_DELEGATED_READ_AUDIT_TRAIL = 'ORG_DELEGATED_READ_AUDIT_TRAIL',\n  /** Configure the organization's SSO and SCIM provisioning. Security-critical: owner-granted, time-bound. */\n  ORG_DELEGATED_MANAGE_SSO_SCIM = 'ORG_DELEGATED_MANAGE_SSO_SCIM',\n  /** Manage the organization's API keys. Security-critical: owner-granted, time-bound. */\n  ORG_DELEGATED_MANAGE_API_KEYS = 'ORG_DELEGATED_MANAGE_API_KEYS',\n  /** Approve or deny, as the tenant, a platform operator's access request. Security-critical: owner-granted, time-bound. */\n  ORG_DELEGATED_APPROVE_ACCESS_GRANTS = 'ORG_DELEGATED_APPROVE_ACCESS_GRANTS',\n}\n\n/**\n * Roles only an ENGINE inbound handler may act with (#1629) — never a person, an API key, an OAuth client or\n * an application's own handler.\n *\n * ## Why a named set, and where it is enforced\n *\n * A role is granted through many doors — organization and unit memberships, a user's application roles,\n * invitations, SSO and SCIM mappings, machine credentials — and several of them accept any string (the\n * member-role check is skipped entirely when an application declares no organization types). Guarding each\n * door would be the one-of-N shape `invariant-call-site-enumeration.md` records. So the set is enforced where\n * every principal converges instead:\n *\n * - the `ExecutionContext` constructor refuses a context carrying one of these roles unless it is an\n *   `INBOUND_DELIVERY` context, so a grant that slipped through any door cannot confer anything;\n * - the inbound handler registry refuses them in an application handler's `actingRoles`, so only the engine's\n *   own handler, which declares the engine capability, may act with them.\n *\n * The write doors that are cheap to guard (the organization member roles) refuse them too, so a mistaken grant\n * is answered where it is made rather than when the member next signs in.\n */\n// assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — the roles cut for one engine handler's writes confer nothing to any other principal (#1629).\nexport const INBOUND_HANDLER_ONLY_ROLES: ReadonlySet<string> = new Set<string>([\n  CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS,\n  CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS,\n  CORE_APP_ROLES.APP_EMAIL_INBOUND_INTAKE,\n]);\n\n/** Whether `role` is one only an engine inbound handler may act with. */\nexport function isInboundHandlerOnlyRole(role: string): boolean {\n  return INBOUND_HANDLER_ONLY_ROLES.has(role);\n}\n\n\nexport const CoreRolesSchema = z.union([\n  z.enum(CORE_APP_ROLES),\n  z.enum(CORE_ORG_ROLES),\n]);\n\nexport const RolesSchema = z.union([\n  z.enum(CORE_APP_ROLES),\n  z.enum(CORE_ORG_ROLES),\n  z.string().min(1),\n]);\n\nexport const AppRolesSchema = z.union([\n  z.enum(CORE_APP_ROLES),\n  z.string().min(1),\n]);\n\nexport const OrgRolesSchema = z.union([\n  z.enum(CORE_ORG_ROLES),\n  z.string().min(1),\n]);\n\n/**\n * @wildo_source:part:start saas.models.roles.definition facet:layer:shared facet:audience:app-developer\n *\n * One role an application declares, and the table of them. Import from `@wildo-ai/saas-models`\n * (`RolesConfiguration`, `CORE_ORG_ROLES`, `CORE_APP_ROLES`, `ResourcePrimaryScope`).\n *\n * An application's own roles live in ONE place: `CUSTOM_ROLES_CONFIGURATION` in\n * `shared-lib/src/engine/roles.ts`, a `RolesConfiguration` keyed by the role's name. Nothing else\n * declares a role — never a resource holding role names or permission lists, which the engine does not\n * read.\n *\n * - `role` — the role's name, equal to its key. Any string; prefer a stable upper-snake name\n *   (`FIELD_TECHNICIAN`).\n * - `inheritFrom` — the role whose access this one also receives. A holder of a role satisfies every\n *   operation naming that role OR any role up its `inheritFrom` chain. The core organization chain is\n *   linear: `ORG_OWNER → ORG_ADMIN → ORG_MANAGER → ORG_MEMBER → ORG_GUEST`. So a custom role inheriting\n *   `ORG_MEMBER` is NOT held by an `ORG_ADMIN`: to let administrators do what the custom role does,\n *   name both roles on the operation.\n * - `isSystemRole` — `false` for every role an application declares.\n * - `relatedPrimaryScope` — `ResourcePrimaryScope.ORGANIZATIONS` for a role a member holds inside one\n *   organization, `ResourcePrimaryScope.APPLICATION` for an application-wide role. Any other scope is\n *   ignored at startup with a warning, and the role grants nothing.\n *\n * Declaring a role is one of three steps. An organization role must also be listed in\n * `organizationTypes.<type>.availableOrgRoles` of `wildo.saas.config.ts` (or no member can be given\n * it), and it must be named in the `roles` of the operation variants it unlocks (or holding it changes\n * nothing). People receive it through the engine's members screen and invitations.\n */\nexport const RoleDefinitionSchema = z.object({\n  role: RolesSchema,\n  inheritFrom: RolesSchema.optional(),\n  isSystemRole: z.boolean().default(false),\n  relatedPrimaryScope : z.enum(ResourcePrimaryScope),\n});\n\n\nexport type RoleDefinition = z.infer<typeof RoleDefinitionSchema>;\n\nexport const RolesConfigurationSchema = z.record(z.string(), RoleDefinitionSchema).refine(\n  (record) => {\n    // Validate that all keys are valid roles\n    return Object.keys(record).every(key => {\n      try {\n        RolesSchema.parse(key);\n        return true;\n      } catch {\n        return false;\n      }\n    });\n  }\n);\n/** @wildo_source:part:end saas.models.roles.definition */\n\nexport type Roles = z.infer<typeof RolesSchema>;\nexport type CoreRoles = z.infer<typeof CoreRolesSchema>;\nexport type AppRoles = z.infer<typeof AppRolesSchema>;\nexport type OrgRoles = z.infer<typeof OrgRolesSchema>;\nexport type RolesConfiguration = z.infer<typeof RolesConfigurationSchema>;\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"roles.shared.utils.d.ts","sourceRoot":"","sources":["../../../../../src/security/authorizations/roles.shared.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAkC,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAMjG;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,kBAAkB,GAAG,MAAM,EAAE,CAQ/F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,gCAAgC,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,OAAO,CAEtG;AAeD,4DAA4D;AAC5D,MAAM,WAAW,mCAAmC;IAClD,qFAAqF;IACrF,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAC7C,wEAAwE;IACxE,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,0GAA0G;IAC1G,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,mFAAmF;IACnF,cAAc,CAAC,EAAE,kBAAkB,CAAC;IACpC,+EAA+E;IAC/E,cAAc,CAAC,EAAE,kBAAkB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,mCAAmC,GAAG,OAAO,CAoClG;AAwCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,cAAc,GAAE,kBAAmD,EACnE,cAAc,GAAE,kBAA+C,GAC9D,MAAM,CAMR;AAED,sFAAsF;AACtF,MAAM,WAAW,qBAAqB;IACpC,8FAA8F;IAC9F,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,qBAAqB,EAC9B,cAAc,CAAC,EAAE,kBAAkB,EACnC,cAAc,CAAC,EAAE,kBAAkB,GAClC,MAAM,CAIR;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,SAAS,qBAAqB,EACzE,QAAQ,EAAE,SAAS,CAAC,EAAE,EACtB,cAAc,CAAC,EAAE,kBAAkB,EACnC,cAAc,CAAC,EAAE,kBAAkB,GAClC,CAAC,EAAE,CAQL"}
+{"version":3,"file":"roles.shared.utils.d.ts","sourceRoot":"","sources":["../../../../src/security/authorizations/roles.shared.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAkC,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAMjG;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,kBAAkB,GAAG,MAAM,EAAE,CAQ/F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,gCAAgC,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,OAAO,CAEtG;AAeD,4DAA4D;AAC5D,MAAM,WAAW,mCAAmC;IAClD,qFAAqF;IACrF,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAC7C,wEAAwE;IACxE,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,0GAA0G;IAC1G,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,mFAAmF;IACnF,cAAc,CAAC,EAAE,kBAAkB,CAAC;IACpC,+EAA+E;IAC/E,cAAc,CAAC,EAAE,kBAAkB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,mCAAmC,GAAG,OAAO,CAoClG;AAwCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,cAAc,GAAE,kBAAmD,EACnE,cAAc,GAAE,kBAA+C,GAC9D,MAAM,CAMR;AAED,sFAAsF;AACtF,MAAM,WAAW,qBAAqB;IACpC,8FAA8F;IAC9F,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,qBAAqB,EAC9B,cAAc,CAAC,EAAE,kBAAkB,EACnC,cAAc,CAAC,EAAE,kBAAkB,GAClC,MAAM,CAIR;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,SAAS,qBAAqB,EACzE,QAAQ,EAAE,SAAS,CAAC,EAAE,EACtB,cAAc,CAAC,EAAE,kBAAkB,EACnC,cAAc,CAAC,EAAE,kBAAkB,GAClC,CAAC,EAAE,CAQL"}

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

@@ -1 +1 @@
-{"version":3,"file":"roles.shared.utils.js","sourceRoot":"","sources":["../../../../../src/security/authorizations/roles.shared.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Role-resolution utilities — pure, shared between backend authorization and\n * frontend display gating.\n *\n * The framework authorizes operations against a role **hierarchy**: a user\n * holding a high role (e.g. `ORG_OWNER`) implicitly satisfies every role it\n * inherits from (`ORG_OWNER → ORG_ADMIN → ORG_MANAGER → ORG_MEMBER → ORG_GUEST`).\n * `AuthorizationsBackendService` enforces this on every request; these helpers\n * expose the SAME hierarchy walk so the frontend can decide which operation\n * actions to even surface — without duplicating (and drifting from) the\n * algorithm.\n *\n * **Why this exists on the frontend.** The resource registry the browser holds\n * carries every operation a resource declares, each with its `roles` requirement,\n * but the frontend historically never consulted `operation.roles` when building\n * the action bar — so admin-only / super-admin-only actions rendered for every\n * viewer and only 403'd on click. The backend stays the security authority; this\n * gate is a display optimisation that hides buttons the user provably cannot use.\n *\n * @see roles.shared.defaults.ts — the default app/org role configurations\n * @see roles.shared.schemas.ts — `Roles`, `RolesConfiguration`, `RoleDefinition`\n * @see AuthorizationsBackendService.getRoleHierarchy / validateOperationRoles —\n *   the backend twin this mirrors. If the hierarchy walk changes there, change it\n *   here too (the role *configuration* is already shared via the constants below,\n *   so only the algorithm can drift).\n */\n\nimport { CORE_APP_ROLES, CORE_ORG_ROLES, type RolesConfiguration } from './roles.shared.schemas';\nimport {\n  DEFAULT_APP_ROLE_CONFIGURATION,\n  DEFAULT_ORGANIZATION_ROLES,\n} from './roles.shared.defaults';\n\n/**\n * Walk a role's inheritance chain within a single role configuration, returning\n * the role itself plus every role it (transitively) inherits from, nearest-first.\n *\n * Mirrors `AuthorizationsBackendService.getRoleHierarchy`: starts at `roleKey`\n * and follows `inheritFrom` until a role is absent from the config. A role that\n * is **not present** in `rolesConfig` yields an EMPTY chain (it contributes\n * nothing), exactly like the backend — callers that must not over-restrict on\n * unknown (app-custom) roles handle that case explicitly (see\n * {@link userRolesSatisfyRequiredRoles}).\n *\n * @param roleKey - the assigned role to expand\n * @param rolesConfig - the role configuration owning the hierarchy (app or org)\n * @returns the role + its inherited ancestors, nearest-first; empty if unknown\n */\nexport function computeRoleHierarchy(roleKey: string, rolesConfig: RolesConfiguration): string[] {\n  const hierarchy: string[] = [];\n  let current: string | undefined = roleKey;\n  while (current && rolesConfig[current]) {\n    hierarchy.push(current);\n    current = rolesConfig[current].inheritFrom;\n  }\n  return hierarchy;\n}\n\n/**\n * Does this required-role set declare PUBLIC access — imposing no positive role requirement on ANY\n * caller, credentialed or not?\n *\n * ## The semantic this settles, and why the alternative reading was wrong\n *\n * `APP_PUBLIC` can be read two ways, and for a long time different layers of the framework read it\n * differently:\n *\n *  - *no credential REQUIRED* — reachable when nobody authenticated, and gated on roles otherwise;\n *  - *no credential EXAMINED* — reachable by everyone, whether or not they authenticated.\n *\n * The second is the contract, and the first was a defect. Under the first reading, an operation\n * declaring `APP_PUBLIC` answered 200 to an anonymous probe and **403 to the same request carrying a\n * valid token**, because `APP_PUBLIC` is not a role anybody is GRANTED — so a credentialed caller\n * fell past the public carve-out to an ordinary role gate that nothing in their grant set could\n * satisfy. Authenticating REDUCED access below what anonymity gave, on every public surface an\n * application can build: a price list, a public catalogue, an i18n bundle served as a resource.\n *\n * Three of the four surfaces that consume `roles` already implemented the second reading, which is\n * what makes this the framework's settled contract rather than a preference:\n *\n * | surface | reading |\n * |---|---|\n * | frontend action visibility ({@link userRolesSatisfyRequiredRoles}) | no positive requirement |\n * | OpenAPI generation — `APP_PUBLIC` emits `security: []` | no authentication required |\n * | variant rights ranking ({@link computeRolePrivilegeRank}) | ranks `0`, the floor |\n * | backend role gate (before this predicate existed) | **credentialed callers refused** |\n *\n * An OpenAPI `security: []` says the endpoint imposes no security requirement. A client that sends a\n * bearer token to such an endpoint is conformant, and refusing it contradicts the published\n * contract. And independently of any document: **authenticating must never take access away.**\n *\n * ## What it does NOT relax\n *\n * Only the ROLE question. Tenancy, parent-scope and FK-path gates run unchanged, and the\n * repository's contextual filter still confines every row the caller then reaches. A public\n * declaration says \"no role is required to ask\"; it never says \"no scope confines the answer\".\n *\n * ## Why `APP_ANONYMOUS` is deliberately NOT here\n *\n * {@link OPEN_REQUIRED_ROLES} — the DISPLAY-side set — holds both sentinels, because that gate only\n * decides whether to render a button and is documented to fail OPEN on uncertainty. This predicate\n * is an ADMISSION rule, and the two sentinels are not interchangeable for admission:\n * `APP_ANONYMOUS` is a role an anonymous session genuinely HOLDS (the execution-context creator\n * grants it), so an anonymous caller already satisfies the ordinary gate and needs no carve-out —\n * whereas nobody is ever granted `APP_PUBLIC`. Widening admission to `APP_ANONYMOUS` would therefore\n * change who reaches anonymous-scoped operations without fixing anything, which is the wrong trade\n * for a gate. Keep the two questions separate.\n *\n * @param requiredRoles - an operation's declared `roles` (OR semantics)\n * @returns `true` when the declaration admits every caller, role-wise\n */\nexport function requiredRolesDeclarePublicAccess(requiredRoles: readonly string[] | undefined): boolean {\n  return Array.isArray(requiredRoles) && requiredRoles.includes(CORE_APP_ROLES.APP_PUBLIC);\n}\n\n/**\n * Required-role sentinels that impose NO positive role requirement — an operation\n * gated on public / anonymous access must never be hidden from a viewer. Treated\n * as always-satisfied.\n *\n * DISPLAY-side and deliberately WIDER than {@link requiredRolesDeclarePublicAccess}; see that\n * predicate's JSDoc for why the admission rule must not adopt `APP_ANONYMOUS`.\n */\nconst OPEN_REQUIRED_ROLES: ReadonlySet<string> = new Set<string>([\n  CORE_APP_ROLES.APP_PUBLIC,\n  CORE_APP_ROLES.APP_ANONYMOUS,\n]);\n\n/** Parameters for {@link userRolesSatisfyRequiredRoles}. */\nexport interface UserRolesSatisfyRequiredRolesParams {\n  /** The operation's required roles (OR semantics). Empty/undefined ⇒ unrestricted. */\n  requiredRoles: readonly string[] | undefined;\n  /** The user's APPLICATION-scope roles (e.g. `permissions.appLevel`). */\n  userAppRoles: readonly string[];\n  /** The user's ORGANIZATIONS-scope roles for the CURRENT org (e.g. `permissions.organizations[orgId]`). */\n  userOrgRoles: readonly string[];\n  /** App role configuration (defaults to {@link DEFAULT_APP_ROLE_CONFIGURATION}). */\n  appRolesConfig?: RolesConfiguration;\n  /** Org role configuration (defaults to {@link DEFAULT_ORGANIZATION_ROLES}). */\n  orgRolesConfig?: RolesConfiguration;\n}\n\n/**\n * Decide whether a user's effective roles satisfy an operation's required roles,\n * honouring the role hierarchy — the shared answer to \"can this user perform this\n * operation, role-wise?\".\n *\n * This is the SAME OR-with-hierarchy decision the backend enforces\n * (`validateOperationRoles`): the user passes if ANY required role lies in the\n * inheritance closure of ANY role they hold (app roles expanded against the app\n * config, org roles against the org config).\n *\n * **Conservative on the frontend / display side.** It gates which action buttons\n * are even shown; the backend remains the security authority. It therefore FAILS\n * OPEN on uncertainty so it can never hide a button the user is actually allowed\n * to use:\n *   - no/empty `requiredRoles` ⇒ `true` (unrestricted operation).\n *   - a required role that is a public/anonymous sentinel ⇒ `true`.\n *   - if the user holds a role UNKNOWN to the supplied config (an app-custom role\n *     whose inheritance the default config cannot resolve) and the known-role\n *     expansion did not already satisfy the requirement ⇒ `true` (do not hide —\n *     the custom role might inherit a required role). For core-role-only users\n *     (the common case, and the whole settings hub) the decision is exact.\n *\n * @returns `true` if the operation should be considered role-permitted (shown).\n */\nexport function userRolesSatisfyRequiredRoles(params: UserRolesSatisfyRequiredRolesParams): boolean {\n  const {\n    requiredRoles,\n    userAppRoles,\n    userOrgRoles,\n    appRolesConfig = DEFAULT_APP_ROLE_CONFIGURATION,\n    orgRolesConfig = DEFAULT_ORGANIZATION_ROLES,\n  } = params;\n\n  // Unrestricted operation — always permitted.\n  if (!requiredRoles || requiredRoles.length === 0) return true;\n\n  // A public/anonymous gate imposes no positive requirement.\n  if (requiredRoles.some(role => OPEN_REQUIRED_ROLES.has(role))) return true;\n\n  // Expand the user's roles through their respective hierarchies.\n  const satisfiedRoles = new Set<string>();\n  let hasUnresolvableUserRole = false;\n\n  for (const role of userAppRoles) {\n    const hierarchy = computeRoleHierarchy(role, appRolesConfig);\n    if (hierarchy.length === 0) hasUnresolvableUserRole = true;\n    for (const inherited of hierarchy) satisfiedRoles.add(inherited);\n  }\n  for (const role of userOrgRoles) {\n    const hierarchy = computeRoleHierarchy(role, orgRolesConfig);\n    if (hierarchy.length === 0) hasUnresolvableUserRole = true;\n    for (const inherited of hierarchy) satisfiedRoles.add(inherited);\n  }\n\n  // Direct OR-with-hierarchy satisfaction.\n  if (requiredRoles.some(role => satisfiedRoles.has(role))) return true;\n\n  // Fail open if the user holds a role the supplied config can't expand — its\n  // (unknown) inheritance might cover a required role. Never hide on uncertainty.\n  return hasUnresolvableUserRole;\n}\n\n// ════════════════════════════════════════════════════════════════════════════\n// Variant selection by rights (\"show only the highest-right-level variant\")\n// ════════════════════════════════════════════════════════════════════════════\n\n/**\n * Privilege **tier** of a core role — the product ordering between role families.\n * A variant gated on a higher-tier role represents a \"higher right level\".\n *\n *   3 — platform/app admin (`APP_ADMIN_*`)\n *   2 — organisation roles (`ORG_*`)\n *   1 — authenticated user (`APP_USER`)\n *   0 — public / anonymous\n *\n * This is the one **cross-scope** decision the ranking needs: app-admin outranks\n * org, which outranks the plain authenticated user. Within a tier, the role\n * hierarchy depth breaks ties (a deeper role inherits more, so it is higher).\n */\nconst ROLE_PRIVILEGE_TIER: Readonly<Record<string, number>> = {\n  [CORE_APP_ROLES.APP_PUBLIC]: 0,\n  [CORE_APP_ROLES.APP_ANONYMOUS]: 0,\n  [CORE_APP_ROLES.APP_USER]: 1,\n  [CORE_ORG_ROLES.ORG_GUEST]: 2,\n  [CORE_ORG_ROLES.ORG_MEMBER]: 2,\n  [CORE_ORG_ROLES.ORG_MANAGER]: 2,\n  [CORE_ORG_ROLES.ORG_ADMIN]: 2,\n  [CORE_ORG_ROLES.ORG_OWNER]: 2,\n  [CORE_APP_ROLES.APP_ADMIN_VIEWER]: 3,\n  [CORE_APP_ROLES.APP_ADMIN_MARKETING_EDITOR]: 3,\n  [CORE_APP_ROLES.APP_ADMIN_BILLING_MANAGER]: 3,\n  [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN]: 3,\n  // Application tier: it reads across every tenant, which no organisation role can.\n  [CORE_APP_ROLES.APP_AUDIT_EVIDENCE_READER]: 3,\n};\n\n/** Tier used for a role unknown to the default config (an app-custom role). */\nconst UNKNOWN_ROLE_TIER = 2;\nconst TIER_MULTIPLIER = 100;\n\n/**\n * Numeric privilege rank of a single role: `tier * 100 + hierarchyDepth`.\n *\n * Higher = more privileged. Derived from {@link ROLE_PRIVILEGE_TIER} (cross-tier\n * ordering) plus the role's hierarchy depth within its config (intra-tier\n * ordering), so e.g. `ORG_OWNER` (205) > `ORG_MEMBER` (202), and\n * `APP_ADMIN_SUPER_ADMIN` (304) outranks every `ORG_*`. Unknown custom roles fall\n * back to the org tier with depth 1 — exact for core-role apps (the common case),\n * conservative otherwise.\n *\n * Public / anonymous gates impose no positive requirement, so they rank `0` — the\n * floor, equal to a truly unrestricted variant (see {@link computeVariantRightsRank}).\n *\n * NOTE: the intra-tier tiebreak uses hierarchy DEPTH, which is a faithful proxy\n * for privilege only when inheritance is (near-)linear, as it is in the default\n * configs. A branching custom `RolesConfiguration` could give a shallow-but-powerful\n * role a lower depth than a deep-but-weak one and mis-order them; thread an explicit\n * rank (or extend this) if such a config is introduced.\n */\nexport function computeRolePrivilegeRank(\n  role: string,\n  appRolesConfig: RolesConfiguration = DEFAULT_APP_ROLE_CONFIGURATION,\n  orgRolesConfig: RolesConfiguration = DEFAULT_ORGANIZATION_ROLES,\n): number {\n  if (OPEN_REQUIRED_ROLES.has(role)) return 0;\n  const tier = ROLE_PRIVILEGE_TIER[role] ?? UNKNOWN_ROLE_TIER;\n  const config = appRolesConfig[role] ? appRolesConfig : orgRolesConfig[role] ? orgRolesConfig : undefined;\n  const depth = config ? computeRoleHierarchy(role, config).length : 1;\n  return tier * TIER_MULTIPLIER + depth;\n}\n\n/** Minimal shape this module needs from an operation variant to rank it by rights. */\nexport interface RightsRankableVariant {\n  /** The roles that may perform this variant (OR semantics). Empty/undefined = unrestricted. */\n  roles?: readonly string[];\n}\n\n/**\n * The rights rank a variant represents = the privilege of its most-privileged\n * required role. An unrestricted variant (no `roles`) ranks `0` — the lowest gate.\n */\nexport function computeVariantRightsRank(\n  variant: RightsRankableVariant,\n  appRolesConfig?: RolesConfiguration,\n  orgRolesConfig?: RolesConfiguration,\n): number {\n  const roles = variant.roles ?? [];\n  if (roles.length === 0) return 0;\n  return Math.max(...roles.map(role => computeRolePrivilegeRank(role, appRolesConfig, orgRolesConfig)));\n}\n\n/**\n * Collapse a set of operation variants to **only the highest-right-level ones**.\n *\n * The framework principle: variants of an operation exist to give different\n * behaviour according to rights, so a surface should show only the variant with\n * the highest right level the user qualifies for — not the lower-rights ones too.\n * (A super-admin who is also an org member otherwise sees both the member READ and\n * the super-admin READ; this keeps only the super-admin one.)\n *\n * **Precondition:** pass variants the user already QUALIFIES for (i.e. post\n * role-gating via {@link userRolesSatisfyRequiredRoles}). This selector then keeps\n * the subset with the maximum {@link computeVariantRightsRank}. Variants that\n * **tie** at the top rank (equal rights — e.g. context/variantKey variants that\n * are not a rights distinction) are all returned, so the caller's existing\n * default/sub-group logic still handles non-rights multiplicity unchanged.\n *\n * Used globally wherever variants surface as user actions; composite / execution\n * views deliberately bypass this (they may show all variants, for now) by not\n * routing through the collapsing path.\n */\nexport function selectHighestRightsVariants<T extends RightsRankableVariant>(\n  variants: readonly T[],\n  appRolesConfig?: RolesConfiguration,\n  orgRolesConfig?: RolesConfiguration,\n): T[] {\n  if (variants.length <= 1) return [...variants];\n  const ranked = variants.map(variant => ({\n    variant,\n    rank: computeVariantRightsRank(variant, appRolesConfig, orgRolesConfig),\n  }));\n  const maxRank = Math.max(...ranked.map(entry => entry.rank));\n  return ranked.filter(entry => entry.rank === maxRank).map(entry => entry.variant);\n}\n"]}
+{"version":3,"file":"roles.shared.utils.js","sourceRoot":"","sources":["../../../../src/security/authorizations/roles.shared.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Role-resolution utilities — pure, shared between backend authorization and\n * frontend display gating.\n *\n * The framework authorizes operations against a role **hierarchy**: a user\n * holding a high role (e.g. `ORG_OWNER`) implicitly satisfies every role it\n * inherits from (`ORG_OWNER → ORG_ADMIN → ORG_MANAGER → ORG_MEMBER → ORG_GUEST`).\n * `AuthorizationsBackendService` enforces this on every request; these helpers\n * expose the SAME hierarchy walk so the frontend can decide which operation\n * actions to even surface — without duplicating (and drifting from) the\n * algorithm.\n *\n * **Why this exists on the frontend.** The resource registry the browser holds\n * carries every operation a resource declares, each with its `roles` requirement,\n * but the frontend historically never consulted `operation.roles` when building\n * the action bar — so admin-only / super-admin-only actions rendered for every\n * viewer and only 403'd on click. The backend stays the security authority; this\n * gate is a display optimisation that hides buttons the user provably cannot use.\n *\n * @see roles.shared.defaults.ts — the default app/org role configurations\n * @see roles.shared.schemas.ts — `Roles`, `RolesConfiguration`, `RoleDefinition`\n * @see AuthorizationsBackendService.getRoleHierarchy / validateOperationRoles —\n *   the backend twin this mirrors. If the hierarchy walk changes there, change it\n *   here too (the role *configuration* is already shared via the constants below,\n *   so only the algorithm can drift).\n */\n\nimport { CORE_APP_ROLES, CORE_ORG_ROLES, type RolesConfiguration } from './roles.shared.schemas';\nimport {\n  DEFAULT_APP_ROLE_CONFIGURATION,\n  DEFAULT_ORGANIZATION_ROLES,\n} from './roles.shared.defaults';\n\n/**\n * Walk a role's inheritance chain within a single role configuration, returning\n * the role itself plus every role it (transitively) inherits from, nearest-first.\n *\n * Mirrors `AuthorizationsBackendService.getRoleHierarchy`: starts at `roleKey`\n * and follows `inheritFrom` until a role is absent from the config. A role that\n * is **not present** in `rolesConfig` yields an EMPTY chain (it contributes\n * nothing), exactly like the backend — callers that must not over-restrict on\n * unknown (app-custom) roles handle that case explicitly (see\n * {@link userRolesSatisfyRequiredRoles}).\n *\n * @param roleKey - the assigned role to expand\n * @param rolesConfig - the role configuration owning the hierarchy (app or org)\n * @returns the role + its inherited ancestors, nearest-first; empty if unknown\n */\nexport function computeRoleHierarchy(roleKey: string, rolesConfig: RolesConfiguration): string[] {\n  const hierarchy: string[] = [];\n  let current: string | undefined = roleKey;\n  while (current && rolesConfig[current]) {\n    hierarchy.push(current);\n    current = rolesConfig[current].inheritFrom;\n  }\n  return hierarchy;\n}\n\n/**\n * Does this required-role set declare PUBLIC access — imposing no positive role requirement on ANY\n * caller, credentialed or not?\n *\n * ## The semantic this settles, and why the alternative reading was wrong\n *\n * `APP_PUBLIC` can be read two ways, and for a long time different layers of the framework read it\n * differently:\n *\n *  - *no credential REQUIRED* — reachable when nobody authenticated, and gated on roles otherwise;\n *  - *no credential EXAMINED* — reachable by everyone, whether or not they authenticated.\n *\n * The second is the contract, and the first was a defect. Under the first reading, an operation\n * declaring `APP_PUBLIC` answered 200 to an anonymous probe and **403 to the same request carrying a\n * valid token**, because `APP_PUBLIC` is not a role anybody is GRANTED — so a credentialed caller\n * fell past the public carve-out to an ordinary role gate that nothing in their grant set could\n * satisfy. Authenticating REDUCED access below what anonymity gave, on every public surface an\n * application can build: a price list, a public catalogue, an i18n bundle served as a resource.\n *\n * Three of the four surfaces that consume `roles` already implemented the second reading, which is\n * what makes this the framework's settled contract rather than a preference:\n *\n * | surface | reading |\n * |---|---|\n * | frontend action visibility ({@link userRolesSatisfyRequiredRoles}) | no positive requirement |\n * | OpenAPI generation — `APP_PUBLIC` emits `security: []` | no authentication required |\n * | variant rights ranking ({@link computeRolePrivilegeRank}) | ranks `0`, the floor |\n * | backend role gate (before this predicate existed) | **credentialed callers refused** |\n *\n * An OpenAPI `security: []` says the endpoint imposes no security requirement. A client that sends a\n * bearer token to such an endpoint is conformant, and refusing it contradicts the published\n * contract. And independently of any document: **authenticating must never take access away.**\n *\n * ## What it does NOT relax\n *\n * Only the ROLE question. Tenancy, parent-scope and FK-path gates run unchanged, and the\n * repository's contextual filter still confines every row the caller then reaches. A public\n * declaration says \"no role is required to ask\"; it never says \"no scope confines the answer\".\n *\n * ## Why `APP_ANONYMOUS` is deliberately NOT here\n *\n * {@link OPEN_REQUIRED_ROLES} — the DISPLAY-side set — holds both sentinels, because that gate only\n * decides whether to render a button and is documented to fail OPEN on uncertainty. This predicate\n * is an ADMISSION rule, and the two sentinels are not interchangeable for admission:\n * `APP_ANONYMOUS` is a role an anonymous session genuinely HOLDS (the execution-context creator\n * grants it), so an anonymous caller already satisfies the ordinary gate and needs no carve-out —\n * whereas nobody is ever granted `APP_PUBLIC`. Widening admission to `APP_ANONYMOUS` would therefore\n * change who reaches anonymous-scoped operations without fixing anything, which is the wrong trade\n * for a gate. Keep the two questions separate.\n *\n * @param requiredRoles - an operation's declared `roles` (OR semantics)\n * @returns `true` when the declaration admits every caller, role-wise\n */\nexport function requiredRolesDeclarePublicAccess(requiredRoles: readonly string[] | undefined): boolean {\n  return Array.isArray(requiredRoles) && requiredRoles.includes(CORE_APP_ROLES.APP_PUBLIC);\n}\n\n/**\n * Required-role sentinels that impose NO positive role requirement — an operation\n * gated on public / anonymous access must never be hidden from a viewer. Treated\n * as always-satisfied.\n *\n * DISPLAY-side and deliberately WIDER than {@link requiredRolesDeclarePublicAccess}; see that\n * predicate's JSDoc for why the admission rule must not adopt `APP_ANONYMOUS`.\n */\nconst OPEN_REQUIRED_ROLES: ReadonlySet<string> = new Set<string>([\n  CORE_APP_ROLES.APP_PUBLIC,\n  CORE_APP_ROLES.APP_ANONYMOUS,\n]);\n\n/** Parameters for {@link userRolesSatisfyRequiredRoles}. */\nexport interface UserRolesSatisfyRequiredRolesParams {\n  /** The operation's required roles (OR semantics). Empty/undefined ⇒ unrestricted. */\n  requiredRoles: readonly string[] | undefined;\n  /** The user's APPLICATION-scope roles (e.g. `permissions.appLevel`). */\n  userAppRoles: readonly string[];\n  /** The user's ORGANIZATIONS-scope roles for the CURRENT org (e.g. `permissions.organizations[orgId]`). */\n  userOrgRoles: readonly string[];\n  /** App role configuration (defaults to {@link DEFAULT_APP_ROLE_CONFIGURATION}). */\n  appRolesConfig?: RolesConfiguration;\n  /** Org role configuration (defaults to {@link DEFAULT_ORGANIZATION_ROLES}). */\n  orgRolesConfig?: RolesConfiguration;\n}\n\n/**\n * Decide whether a user's effective roles satisfy an operation's required roles,\n * honouring the role hierarchy — the shared answer to \"can this user perform this\n * operation, role-wise?\".\n *\n * This is the SAME OR-with-hierarchy decision the backend enforces\n * (`validateOperationRoles`): the user passes if ANY required role lies in the\n * inheritance closure of ANY role they hold (app roles expanded against the app\n * config, org roles against the org config).\n *\n * **Conservative on the frontend / display side.** It gates which action buttons\n * are even shown; the backend remains the security authority. It therefore FAILS\n * OPEN on uncertainty so it can never hide a button the user is actually allowed\n * to use:\n *   - no/empty `requiredRoles` ⇒ `true` (unrestricted operation).\n *   - a required role that is a public/anonymous sentinel ⇒ `true`.\n *   - if the user holds a role UNKNOWN to the supplied config (an app-custom role\n *     whose inheritance the default config cannot resolve) and the known-role\n *     expansion did not already satisfy the requirement ⇒ `true` (do not hide —\n *     the custom role might inherit a required role). For core-role-only users\n *     (the common case, and the whole settings hub) the decision is exact.\n *\n * @returns `true` if the operation should be considered role-permitted (shown).\n */\nexport function userRolesSatisfyRequiredRoles(params: UserRolesSatisfyRequiredRolesParams): boolean {\n  const {\n    requiredRoles,\n    userAppRoles,\n    userOrgRoles,\n    appRolesConfig = DEFAULT_APP_ROLE_CONFIGURATION,\n    orgRolesConfig = DEFAULT_ORGANIZATION_ROLES,\n  } = params;\n\n  // Unrestricted operation — always permitted.\n  if (!requiredRoles || requiredRoles.length === 0) return true;\n\n  // A public/anonymous gate imposes no positive requirement.\n  if (requiredRoles.some(role => OPEN_REQUIRED_ROLES.has(role))) return true;\n\n  // Expand the user's roles through their respective hierarchies.\n  const satisfiedRoles = new Set<string>();\n  let hasUnresolvableUserRole = false;\n\n  for (const role of userAppRoles) {\n    const hierarchy = computeRoleHierarchy(role, appRolesConfig);\n    if (hierarchy.length === 0) hasUnresolvableUserRole = true;\n    for (const inherited of hierarchy) satisfiedRoles.add(inherited);\n  }\n  for (const role of userOrgRoles) {\n    const hierarchy = computeRoleHierarchy(role, orgRolesConfig);\n    if (hierarchy.length === 0) hasUnresolvableUserRole = true;\n    for (const inherited of hierarchy) satisfiedRoles.add(inherited);\n  }\n\n  // Direct OR-with-hierarchy satisfaction.\n  if (requiredRoles.some(role => satisfiedRoles.has(role))) return true;\n\n  // Fail open if the user holds a role the supplied config can't expand — its\n  // (unknown) inheritance might cover a required role. Never hide on uncertainty.\n  return hasUnresolvableUserRole;\n}\n\n// ════════════════════════════════════════════════════════════════════════════\n// Variant selection by rights (\"show only the highest-right-level variant\")\n// ════════════════════════════════════════════════════════════════════════════\n\n/**\n * Privilege **tier** of a core role — the product ordering between role families.\n * A variant gated on a higher-tier role represents a \"higher right level\".\n *\n *   3 — platform/app admin (`APP_ADMIN_*`)\n *   2 — organisation roles (`ORG_*`)\n *   1 — authenticated user (`APP_USER`)\n *   0 — public / anonymous\n *\n * This is the one **cross-scope** decision the ranking needs: app-admin outranks\n * org, which outranks the plain authenticated user. Within a tier, the role\n * hierarchy depth breaks ties (a deeper role inherits more, so it is higher).\n */\nconst ROLE_PRIVILEGE_TIER: Readonly<Record<string, number>> = {\n  [CORE_APP_ROLES.APP_PUBLIC]: 0,\n  [CORE_APP_ROLES.APP_ANONYMOUS]: 0,\n  [CORE_APP_ROLES.APP_USER]: 1,\n  [CORE_ORG_ROLES.ORG_GUEST]: 2,\n  [CORE_ORG_ROLES.ORG_MEMBER]: 2,\n  [CORE_ORG_ROLES.ORG_MANAGER]: 2,\n  [CORE_ORG_ROLES.ORG_ADMIN]: 2,\n  [CORE_ORG_ROLES.ORG_OWNER]: 2,\n  [CORE_APP_ROLES.APP_ADMIN_VIEWER]: 3,\n  [CORE_APP_ROLES.APP_ADMIN_MARKETING_EDITOR]: 3,\n  [CORE_APP_ROLES.APP_ADMIN_BILLING_MANAGER]: 3,\n  [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN]: 3,\n  // Application tier: it reads across every tenant, which no organisation role can.\n  [CORE_APP_ROLES.APP_AUDIT_EVIDENCE_READER]: 3,\n};\n\n/** Tier used for a role unknown to the default config (an app-custom role). */\nconst UNKNOWN_ROLE_TIER = 2;\nconst TIER_MULTIPLIER = 100;\n\n/**\n * Numeric privilege rank of a single role: `tier * 100 + hierarchyDepth`.\n *\n * Higher = more privileged. Derived from {@link ROLE_PRIVILEGE_TIER} (cross-tier\n * ordering) plus the role's hierarchy depth within its config (intra-tier\n * ordering), so e.g. `ORG_OWNER` (205) > `ORG_MEMBER` (202), and\n * `APP_ADMIN_SUPER_ADMIN` (304) outranks every `ORG_*`. Unknown custom roles fall\n * back to the org tier with depth 1 — exact for core-role apps (the common case),\n * conservative otherwise.\n *\n * Public / anonymous gates impose no positive requirement, so they rank `0` — the\n * floor, equal to a truly unrestricted variant (see {@link computeVariantRightsRank}).\n *\n * NOTE: the intra-tier tiebreak uses hierarchy DEPTH, which is a faithful proxy\n * for privilege only when inheritance is (near-)linear, as it is in the default\n * configs. A branching custom `RolesConfiguration` could give a shallow-but-powerful\n * role a lower depth than a deep-but-weak one and mis-order them; thread an explicit\n * rank (or extend this) if such a config is introduced.\n */\nexport function computeRolePrivilegeRank(\n  role: string,\n  appRolesConfig: RolesConfiguration = DEFAULT_APP_ROLE_CONFIGURATION,\n  orgRolesConfig: RolesConfiguration = DEFAULT_ORGANIZATION_ROLES,\n): number {\n  if (OPEN_REQUIRED_ROLES.has(role)) return 0;\n  const tier = ROLE_PRIVILEGE_TIER[role] ?? UNKNOWN_ROLE_TIER;\n  const config = appRolesConfig[role] ? appRolesConfig : orgRolesConfig[role] ? orgRolesConfig : undefined;\n  const depth = config ? computeRoleHierarchy(role, config).length : 1;\n  return tier * TIER_MULTIPLIER + depth;\n}\n\n/** Minimal shape this module needs from an operation variant to rank it by rights. */\nexport interface RightsRankableVariant {\n  /** The roles that may perform this variant (OR semantics). Empty/undefined = unrestricted. */\n  roles?: readonly string[];\n}\n\n/**\n * The rights rank a variant represents = the privilege of its most-privileged\n * required role. An unrestricted variant (no `roles`) ranks `0` — the lowest gate.\n */\nexport function computeVariantRightsRank(\n  variant: RightsRankableVariant,\n  appRolesConfig?: RolesConfiguration,\n  orgRolesConfig?: RolesConfiguration,\n): number {\n  const roles = variant.roles ?? [];\n  if (roles.length === 0) return 0;\n  return Math.max(...roles.map(role => computeRolePrivilegeRank(role, appRolesConfig, orgRolesConfig)));\n}\n\n/**\n * Collapse a set of operation variants to **only the highest-right-level ones**.\n *\n * The framework principle: variants of an operation exist to give different\n * behaviour according to rights, so a surface should show only the variant with\n * the highest right level the user qualifies for — not the lower-rights ones too.\n * (A super-admin who is also an org member otherwise sees both the member READ and\n * the super-admin READ; this keeps only the super-admin one.)\n *\n * **Precondition:** pass variants the user already QUALIFIES for (i.e. post\n * role-gating via {@link userRolesSatisfyRequiredRoles}). This selector then keeps\n * the subset with the maximum {@link computeVariantRightsRank}. Variants that\n * **tie** at the top rank (equal rights — e.g. context/variantKey variants that\n * are not a rights distinction) are all returned, so the caller's existing\n * default/sub-group logic still handles non-rights multiplicity unchanged.\n *\n * Used globally wherever variants surface as user actions; composite / execution\n * views deliberately bypass this (they may show all variants, for now) by not\n * routing through the collapsing path.\n */\nexport function selectHighestRightsVariants<T extends RightsRankableVariant>(\n  variants: readonly T[],\n  appRolesConfig?: RolesConfiguration,\n  orgRolesConfig?: RolesConfiguration,\n): T[] {\n  if (variants.length <= 1) return [...variants];\n  const ranked = variants.map(variant => ({\n    variant,\n    rank: computeVariantRightsRank(variant, appRolesConfig, orgRolesConfig),\n  }));\n  const maxRank = Math.max(...ranked.map(entry => entry.rank));\n  return ranked.filter(entry => entry.rank === maxRank).map(entry => entry.variant);\n}\n"]}