permdock 0.3.1 → 0.5.0

package/dist/index-DOVf7RJv.d.ts

@@ -0,0 +1,900 @@
+import { $n as Delegation, Bt as LocalSnapshotManifest, C as MembershipFixture, D as PolicyDelegation, I as SeparationConflict, In as DenialReason, J as EntitlementSource, Kt as AccessEvent, Lt as InstanceHandle, N as RoleBinding, Nn as Decision, P as RoleOptions, Pn as Denial, Qt as DeliveryEvent, R as SupportAccessOptions, Rt as Instant, T as Policy, V as VocabularyFromInput, Vt as Snapshot, W as CustomRoleSource, Xt as DecisionEvent, Y as JwtClaims, Zn as CustomRole, at as SettingsSource, c as BreakGlassOptions, ct as TenantSettings, et as MembershipSource, g as GrantCondition, h as Grant, i as ApprovalOption, ir as Subject, it as RelationSource, j as PolicyVocabulary, k as PolicyOptions, mr as OpaqueCondition, nr as Membership, nt as RelationGroup, ot as SnapshotSource, rn as SinkEvent, rr as Principal, s as AssuranceRequirement, sn as PolicyScopesInput, ur as ConditionRef, ut as TokenSigner, vr as SqlFunctionArg, yr as SqlFunctionCondition } from "./policy-types-DzwivBgR.js";
+import { C as InferPermissionTree, D as PermissionsOptions, E as PermissionTree, F as ResourceParent, L as ResourceRelationInput, M as ResourceMeta, N as ResourceNode, P as ResourceOptions, R as ResourceRestricted, T as PermissionKind, g as ActionMeta, h as ActionList, k as ResourceInit, r as Role, w as Permission, z as ResourceXTree } from "./vocabulary-D6lPdb4Z.js";
+import { i as PermDockOptions, r as PermDock } from "./permdock-D7eeLJER.js";
+import { a as PolicyDocument } from "./hosted-DBDX0M-P.js";
+import { m as ApprovalStore } from "./types-CCpc2Dcv.js";
+import { t as InstanceOptions } from "./instance-options-Omfd793B.js";
+import { n as PermDockWrap } from "./wrap-Bd1Tejur.js";
+import { t as JsonSchemaNode } from "./json-schema-CN_iLFH2.js";
+import { i as CatalogEventData, s as CloudEvent } from "./sink-Bj_lDUDq.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/conditions/refs.d.ts
+type KnownRefField = "id" | "issuer" | "kind" | "tenant" | "team" | "roles" | "plans" | "memberships" | "assurance" | "binding" | "session";
+type SubjectRef = ConditionRef & { readonly [K in KnownRefField]: SubjectRef; } & {
+  readonly [key: string]: SubjectRef;
+};
+declare const principal: SubjectRef;
+declare const context: SubjectRef;
+//#endregion
+//#region src/core/custom-roles.d.ts
+type CustomRoleDropReason = "unknown-permission" | "outside-ceiling" | "condition-not-allowed" | "unknown-level";
+/** Why part of a custom role was left out: a permission, or an undeclared include. */
+type CustomRoleDrop = {
+  readonly permission: string;
+  readonly reason: CustomRoleDropReason;
+  /** The stored level, for `unknown-level`. */
+  readonly level?: string;
+} | {
+  readonly role: string;
+  readonly reason: "unknown-role";
+};
+/** A stored grant that named a permission by a key it was renamed from. */
+type CustomRoleRename = {
+  readonly from: string;
+  readonly to: string;
+};
+type ResolvedCustomRole = {
+  /** Declared grants re-targeted to the custom role; conditions and approvals kept. */
+  readonly grants: readonly Grant[];
+  readonly dropped: readonly CustomRoleDrop[];
+  /** Grants stored under a former key (`definePermissions` `renamed`), resolved to the current one. */
+  readonly renamed: readonly CustomRoleRename[];
+};
+type CustomRoleValidation = {
+  readonly ok: boolean;
+  /** Permission keys the role allows after the ceiling, sorted. */
+  readonly permissions: readonly string[];
+  readonly dropped: readonly CustomRoleDrop[];
+  /** Grants to rewrite in storage: each still resolves, under its current key. */
+  readonly renamed: readonly CustomRoleRename[];
+};
+/**
+ * The one resolver behind evaluation, snapshots and `validateCustomRole`.
+ * Included roles' grants plus the role's own allows, minus its denies, all
+ * intersected with the ceiling. An allow inherits the condition, approval and
+ * limit of the declared grant it comes from: an included assignable role's
+ * grant when there is one, otherwise every ceiling grant of that permission,
+ * together with the denies of the roles those grants belong to.
+ */
+declare function resolveCustomRole(policy: Policy, role: CustomRole): ResolvedCustomRole;
+declare function validateCustomRole(policy: Policy, role: CustomRole): CustomRoleValidation;
+/**
+ * The compact JWT form of custom roles for the `memberships[].grants` claim
+ * RLS reads in `jwt` mode: role name to entries, where `key` allows, `-key`
+ * denies and `@role` includes. Put a team custom role on its team membership.
+ * Pass `policy` to write keys stored under a former name as the current key.
+ */
+declare function customRoleClaim(roles: readonly CustomRole[], policy?: Policy): Readonly<Record<string, readonly string[]>>;
+//#endregion
+//#region src/core/snapshot.d.ts
+declare function parseSnapshot(json: unknown): Snapshot;
+//#endregion
+//#region src/core/from-snapshot.d.ts
+declare function fromSnapshot(snapshot: Snapshot, options?: {
+  readonly tenant?: string;
+  readonly team?: string;
+}): PermDock;
+declare function emptySnapshot(): Snapshot;
+//#endregion
+//#region src/core/approval-required.d.ts
+declare function requiresApproval(approval: Grant["approval"] | undefined): boolean;
+//#endregion
+//#region src/core/policy.d.ts
+declare function definePolicy<TUser, TPrincipal extends Principal, const Input extends PermissionTree | PolicyVocabulary, const S extends PolicyScopesInput = PolicyScopesInput>(permissions: Input, options: PolicyOptions<TUser, TPrincipal, S>): Policy<TUser, TPrincipal, VocabularyFromInput<Input>>;
+declare function separationConflicts(policy: Policy, memberships: readonly MembershipFixture[]): readonly SeparationConflict[];
+//#endregion
+//#region src/core/permission-registry.d.ts
+declare function getResource<RX = never>(tree: PermissionTree & ResourceXTree<RX>, name: string): ([RX] extends [never] ? ResourceNode : ResourceNode & {
+  readonly meta?: ResourceMeta<Readonly<RX>>;
+}) | undefined;
+declare function listPermissions(tree: PermissionTree | Permission): readonly Permission[];
+declare function findPermission(tree: PermissionTree, keyOrScope: string): Permission | undefined;
+/**
+ * A permission leaf: string `key`, `scope`, `resource` and `action` plus an
+ * object `meta`. `kind` is non-enumerable and does not survive
+ * `JSON.stringify`, so a leaf that crossed a serialisation boundary passes
+ * without it; when present it must be `instance` or `collection`.
+ */
+declare function isPermission(value: unknown): value is Permission;
+declare function mergePermissions<const Trees extends readonly PermissionTree[]>(...trees: Trees): PermissionTree;
+//#endregion
+//#region src/conditions/opaque.d.ts
+declare function opaque(input: {
+  readonly sql: string;
+  readonly fingerprint: string;
+}): OpaqueCondition;
+//#endregion
+//#region src/conditions/sql-function.d.ts
+declare function sqlFunction(name: string, options: {
+  readonly args?: readonly SqlFunctionArg[];
+  readonly twin: unknown;
+}): SqlFunctionCondition;
+//#endregion
+//#region src/core/memory-sources.d.ts
+declare function memoryEntitlementSource(entries: Readonly<Record<string, readonly string[]>>): EntitlementSource;
+declare function memorySettingsSource(settings: Readonly<Record<string, TenantSettings>>): SettingsSource;
+/** Memberships keyed by principal id; `tenant` is not a filter, as for a database source. */
+declare function memoryMembershipSource(entries: Readonly<Record<string, readonly Membership[]>>): MembershipSource;
+/** A snapshot held in memory; `set` replaces it and notifies every subscriber. */
+declare function memorySnapshotSource(initial: Snapshot | string): SnapshotSource & {
+  set(snapshot: Snapshot | string): void;
+};
+declare function memoryCustomRoleSource(customRoles: readonly CustomRole[]): CustomRoleSource;
+//#endregion
+//#region src/core/approval-state.d.ts
+/** The denial detail when an `ApprovalPolicySource` threw or returned an invalid entry. */
+declare const APPROVAL_POLICY_UNAVAILABLE = "approval-policy-unavailable";
+//#endregion
+//#region src/core/memberships.d.ts
+/**
+ * One `MembershipSource` over several: memberships are merged and
+ * de-duplicated, `list` concatenates the sources that can list, and `version`
+ * is the highest version any source reports. A source that throws makes the
+ * whole lookup throw, which the subject resolver turns into no memberships.
+ */
+declare function composeMemberships(sources: readonly MembershipSource[]): MembershipSource;
+/**
+ * Trust the memberships the verified token carries, and read `source` only
+ * when the token marks them truncated. With `version`, a token minted before
+ * the latest membership change is stale for the policy's `fresh` permissions,
+ * or with `onStale: 'reread'` has its memberships read from `source` instead.
+ */
+declare function claimsFirst(source: MembershipSource | readonly MembershipSource[], options?: {
+  readonly version?: MembershipSource["version"];
+  readonly onStale?: "deny" | "reread";
+}): MembershipSource;
+/** Whether the identity provider owns `membership`: the application must not add, change or remove it. */
+declare function isExternallyManaged(membership: Membership): boolean;
+/**
+ * How many principals hold `role` in one scope instance now, from the
+ * source's member list (`MembershipSource.list`): live memberships of exactly
+ * that scope and instance, each principal counted once. The `holders` a
+ * `decideRoleChange` with `min`, `max` or `transferOnly` needs. `undefined`
+ * when the source cannot list or the read fails, which that check denies.
+ */
+declare function countHolders(source: MembershipSource | readonly MembershipSource[], query: {
+  readonly scope: string;
+  readonly id: string;
+  readonly role: string | {
+    readonly key: string;
+  };
+}): Promise<number | undefined>;
+//#endregion
+//#region src/core/stripe-entitlements.d.ts
+/** The part of the Stripe Node SDK this source calls: `stripe.entitlements.activeEntitlements.list`. */
+type StripeEntitlementsClient = {
+  readonly entitlements: {
+    readonly activeEntitlements: {
+      list(params: {
+        readonly customer: string;
+        readonly limit?: number;
+        readonly starting_after?: string;
+      }): PromiseLike<{
+        readonly data: readonly {
+          readonly id: string;
+          readonly lookup_key: string;
+        }[];
+        readonly has_more: boolean;
+      }>;
+    };
+  };
+};
+/**
+ * Plan names from Stripe Entitlements: the `lookup_key` of every active
+ * entitlement of the tenant's Stripe customer. `customer` maps the active
+ * tenant to its customer id; no tenant or no customer means no entitlements.
+ * Pass it as `entitlements`, and grant with `plan('<lookup_key>')`.
+ */
+declare function stripeEntitlementSource(options: {
+  readonly stripe: StripeEntitlementsClient;
+  readonly customer: (tenant: string, principal: {
+    readonly id: string;
+  }) => string | undefined | PromiseLike<string | undefined>;
+}): EntitlementSource;
+//#endregion
+//#region src/core/memory-relations.d.ts
+type MemoryEdge = {
+  /** The object's id. */
+  readonly id: string;
+  readonly principal: string;
+  readonly startsAt?: number;
+  readonly expiresAt?: number;
+};
+type MemoryRelationSourceData = {
+  /** Rows per resource: parent pointers, links, restricted flags and relation columns are read from them. */
+  readonly rows?: Readonly<Record<string, readonly Readonly<Record<string, unknown>>[]>>;
+  /** Edge-table rows per resource and relation. */
+  readonly edges?: Readonly<Record<string, Readonly<Record<string, readonly MemoryEdge[]>>>>;
+  /**
+   * Edge tables as the database holds them, keyed by `edge` name: each row
+   * is read through the relation's `object`, `subject`, `expiresAt`, `match`
+   * and `groups` columns. A relation whose table is here ignores `edges`.
+   */
+  readonly tables?: Readonly<Record<string, readonly Readonly<Record<string, unknown>>[]>>;
+};
+/**
+ * An in-process `RelationSource` over plain rows and edges, read against the
+ * resource definitions in `permissions`. For tests, fixtures and small apps.
+ */
+declare function memoryRelationSource(permissions: PermissionTree, data?: MemoryRelationSourceData): RelationSource;
+//#endregion
+//#region src/core/who-can.d.ts
+/** One way a principal holds a permission on an object. */
+type HoldingVia = {
+  readonly kind: "role";
+  readonly role: string;
+  readonly membership: Membership;
+} | {
+  readonly kind: "relation";
+  readonly resource: string;
+  readonly relation: string;
+  /** The instance the relation is held on: the object or one of its ancestors. */
+  readonly id: string;
+} | {
+  readonly kind: "share";
+  readonly resource: string;
+  readonly relation: string;
+  readonly id: string;
+  readonly expiresAt?: number;
+  /** The group the share names, when the principal holds it as one of its members. */
+  readonly group?: RelationGroup;
+};
+type Holder = {
+  readonly principal: {
+    readonly id: string;
+  };
+  readonly via: readonly HoldingVia[];
+};
+/**
+ * Who holds a permission on one object, for share dialogs and access
+ * reviews. It lists and never grants. `complete: false` means some grantee
+ * could not be enumerated (a global role, a plan, a source without `list`,
+ * an unavailable relation): holders may be missing, so check with `decide`.
+ */
+type WhoCan = {
+  readonly permission: string;
+  readonly holders: readonly Holder[];
+  readonly complete: boolean;
+};
+/**
+ * Who holds `permission` on `resource` for the instance's policy and how
+ * (role, relation or share), from `MembershipSource.list` and
+ * `RelationSource.related`. It lists and never grants; `complete: false`
+ * means some holders could not be listed. An instance built from a
+ * snapshot answers an empty, incomplete list.
+ */
+declare function whoCan(permdock: InstanceHandle, permission: Permission<string, unknown, "instance">, resource: unknown): Promise<WhoCan>;
+//#endregion
+//#region src/core/policy-sign.d.ts
+type SignPolicyDocumentOptions = {
+  /** `aud`: the environment URL `cloud().policies` checks it against. */
+  readonly audience: string | readonly string[];
+  /** `exp`, a NumericDate; the signer's default (one hour after `iat`) when absent. */
+  readonly expiresAt?: number;
+};
+/**
+ * Signs `document` as a `vnd.permdock.policy+jwt`: the `policy` claim holds
+ * every field but `id` and `issuedAt`, which become `jti` and `iat`, so
+ * `policyDocumentFromClaims` reads it back. `iss` is the signer's own.
+ */
+declare function signPolicyDocument(document: PolicyDocument, signer: TokenSigner, options: SignPolicyDocumentOptions): Promise<string>;
+//#endregion
+//#region src/core/snapshot-sign.d.ts
+type SignSnapshotOptions = {
+  /** `aud`; a signer with no default audience refuses to sign without one. */
+  readonly audience?: string | readonly string[];
+};
+/**
+ * Signs `snapshot` as a `vnd.permdock.snapshot+jwt`. `issuedAt` and
+ * `expiresAt` become `iat` and `exp` and leave the `snapshot` claim, so the
+ * registered claims are the only times a verifier reads.
+ */
+declare function signSnapshot(snapshot: Snapshot, signer: TokenSigner, options?: SignSnapshotOptions): Promise<string>;
+/**
+ * The snapshot a verified `vnd.permdock.snapshot+jwt` carries, parsed as
+ * `parseSnapshot` parses it, with `issuedAt` and `expiresAt` from `iat` and
+ * `exp`. `null` when the claim is missing or not a valid snapshot.
+ */
+declare function snapshotFromClaims(claims: JwtClaims): Snapshot | null;
+//#endregion
+//#region src/core/delivery-event.d.ts
+declare function deliveryEvent(input: Omit<DeliveryEvent, "type" | "at"> & {
+  /** An RFC 3339 instant; defaults to now. */
+  readonly at?: string;
+}): DeliveryEvent;
+//#endregion
+//#region src/core/arazzo.d.ts
+type ArazzoSimulateInput = {
+  readonly arazzo: unknown;
+  readonly openapi: unknown;
+  readonly workflowId?: string;
+  readonly permissions?: PermissionTree;
+  readonly inputs?: Readonly<Record<string, unknown>>;
+};
+type ArazzoStepResult = {
+  readonly stepId: string;
+  /** The nested workflow that owns the step, when it is not the plan's workflow. */
+  readonly workflowId?: string;
+  readonly operationId?: string;
+  readonly permissions: readonly Permission[];
+  readonly decision: Decision;
+  readonly provisional?: true;
+};
+type ArazzoPlan = {
+  readonly workflowId: string;
+  readonly outcome: Decision["outcome"];
+  readonly steps: readonly ArazzoStepResult[];
+};
+type ArazzoFinding = {
+  readonly stepId: string;
+  readonly workflowId: string;
+  readonly reason: "undocumented" | "unsupported" | "validation" | "unknown-key";
+  readonly detail: string;
+};
+declare function arazzoFindings(input: ArazzoSimulateInput, tree: PermissionTree | undefined): readonly ArazzoFinding[];
+/**
+ * Walks an Arazzo workflow against `permdock`: each step's operation is
+ * decided as `permdock.simulate` would, and a server instance emits one
+ * simulate event for the whole plan. Works on an instance built from a
+ * snapshot too.
+ */
+declare function simulateArazzo(permdock: PermDock, input: ArazzoSimulateInput): ArazzoPlan;
+//#endregion
+//#region src/core/local-manifest.d.ts
+/**
+ * What the policy grants, as JSON a device turns into snapshots from its own
+ * membership rows (`localSnapshot` in `permdock/react-native`). Write it at
+ * build time; the policy itself never ships to the client.
+ */
+declare function localSnapshotManifest(policy: Policy): LocalSnapshotManifest;
+//#endregion
+//#region src/core/app.d.ts
+/**
+ * How strict `defineApp` is about the services the policy needs. `dev`
+ * fills in in-process defaults (a memory approval store and a memory limit
+ * store) so a new app runs before any infrastructure exists. `prod` throws at startup when a grant needs a
+ * service the app does not configure, instead of denying at run time.
+ */
+type AppProfile = "dev" | "prod";
+/**
+ * Everything an app wires once and every adapter reads: the data sources,
+ * the opt-in features and the services. An adapter's own options win over
+ * these, key by key.
+ */
+type AppOptions = InstanceOptions & Pick<PermDockOptions, "settings"> & {
+  /** Where approval requests open and resume, for every adapter. */
+  readonly store?: ApprovalStore;
+  readonly profile?: AppProfile;
+};
+//#endregion
+//#region src/app/define-app.d.ts
+/**
+ * Binds the app's sources, features and services to `policy`. The result
+ * is a policy: pass it wherever a policy goes (`createPermDock`, every
+ * adapter, the CLI) and each picks up the app definition, with its own
+ * options taking precedence. The profile defaults to `prod`.
+ */
+declare function defineApp<TUser, TPrincipal extends Principal, V extends PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, options?: AppOptions): Policy<TUser, TPrincipal, V>;
+//#endregion
+//#region src/core/shadow.d.ts
+/** The application's existing check, asked the same question PermDock is. */
+type LegacyCheck = (input: {
+  readonly permission: Permission;
+  readonly data: unknown;
+  readonly subject: Subject;
+}) => boolean;
+/** One check where the legacy system and PermDock disagree. */
+type ShadowMismatch = {
+  readonly permission: string;
+  readonly principal: string | null;
+  /** What the legacy check answered; `false` when it threw. */
+  readonly legacy: boolean;
+  readonly permdock: Decision["outcome"];
+  /** `true` when PermDock's answer was the one returned. */
+  readonly enforced: boolean;
+};
+type ShadowOptions = {
+  readonly legacy: LegacyCheck;
+  /**
+   * Permissions PermDock decides; every other check returns the legacy
+   * answer. `"all"` once every mismatch is resolved; default none.
+   */
+  readonly enforce?: readonly Permission[] | "all";
+  /** Called for each disagreement; a throw here is ignored. */
+  readonly onMismatch?: (mismatch: ShadowMismatch) => void;
+};
+/**
+ * Runs PermDock beside the application's existing checks while adopting
+ * it. Each `can`, `decide`, `decideEach`, `filter` and `assert` asks both;
+ * the legacy answer is returned unless the permission is in `enforce`, and
+ * every disagreement reaches `onMismatch`. Promote permissions one by one
+ * as their mismatches are resolved, then remove the wrap. Pass it as an
+ * adapter's `wrap` option, or call it on a core instance.
+ */
+declare function shadowMode(options: ShadowOptions): PermDockWrap;
+//#endregion
+//#region src/core/may-access.d.ts
+/**
+ * An optimistic routing hint for a proxy or middleware, never a decision.
+ * `false` only when the subject's declared roles provably lack `permission`;
+ * `true` whenever custom roles, plans, memberships the claims do not carry or
+ * row conditions could still grant it. Synchronous, no network, never throws.
+ * Pages, Server Actions and RLS remain the enforcement points.
+ */
+declare function mayAccess(policy: Policy, user: unknown, permission: Permission, options?: {
+  readonly tenant?: string;
+}): boolean;
+//#endregion
+//#region src/core/custom-role-source.d.ts
+/** Reads custom roles from the application's store, as `customRoleSource` takes them. */
+type CustomRoleReader = {
+  /** Every custom role of `tenant`, whether or not anyone in the request holds it. */
+  rolesFor(tenant: string): CustomRole[] | Promise<CustomRole[]>;
+  assignable?(tenant: string): string[] | Promise<string[]>;
+  /** Platform custom roles (`scope: 'global'`). */
+  globalRoles?(): CustomRole[] | Promise<CustomRole[]>;
+};
+type CustomRoleSourceOptions = {
+  /** `'all'` (default): read every custom role of each tenant, so `assignableRoles` and `decideRoleChange` see them all. */
+  readonly read?: "all";
+} | {
+  /** `'held'`: skip a tenant's read, and the platform read, when every role the subject holds there is declared in `policy`. For requests that never manage roles. */
+  readonly read: "held";
+  readonly policy: Policy;
+};
+/**
+ * A `CustomRoleSource` over a reader that returns every custom role of a tenant.
+ * It keeps only the roles of the requested tenant. With `read: 'held'` it
+ * skips a tenant's read, and `globalRoles`, when the subject holds only
+ * declared roles there.
+ */
+declare function customRoleSource(reader: CustomRoleReader, options?: CustomRoleSourceOptions): CustomRoleSource;
+//#endregion
+//#region src/core/instance-snapshot.d.ts
+type SnapshotInclude = readonly (Permission | {
+  readonly [key: string]: unknown;
+})[];
+//#endregion
+//#region src/core/snapshot-for.d.ts
+type SnapshotForOptions = {
+  /** Active tenant; ignored unless the subject holds a membership in it. */
+  readonly tenant?: string;
+  /** Database mode: replaces the memberships carried by the subject. */
+  readonly memberships?: readonly Membership[];
+  /** The tenant's custom roles, typically from a shared, tagged cache. */
+  readonly customRoles?: readonly CustomRole[];
+  /** Per tenant, the role names `CustomRoleSource.assignable` returns; narrows `assignable`. */
+  readonly assignable?: Readonly<Record<string, readonly string[]>>;
+  /** Plans of the active tenant; replaces `principal.plans`. */
+  readonly plans?: readonly string[];
+  readonly include?: SnapshotInclude;
+  readonly tenants?: "all";
+  /** The instant for `issuedAt` and membership expiry. Defaults to the clock. */
+  readonly now?: Instant;
+};
+/**
+ * Builds the serializable access snapshot for a subject without a request,
+ * a network call or a cache directive: call it inside the app's own
+ * `'use cache: private'` function. Synchronous; the policy's `subject` and
+ * `context` mappers must be synchronous too.
+ */
+declare function snapshotFor<TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, user: TUser | Subject | null, options?: SnapshotForOptions): Snapshot;
+//#endregion
+//#region src/core/permissions.d.ts
+declare function definePermissions<const Input, PX = never, RX = never>(input: Input, options?: PermissionsOptions<PX, RX>): InferPermissionTree<Input, "", PX> & ResourceXTree<RX>;
+//#endregion
+//#region src/core/permission-leaf.d.ts
+/**
+ * The keys `permission` was renamed from, sorted. Empty for a leaf without
+ * renames and for one that crossed a serialisation boundary.
+ */
+declare function formerKeys(permission: object): readonly string[];
+declare function resource<T, const A extends ActionList = readonly [], const C extends ActionList = readonly []>(schema: StandardSchemaV1<unknown, T>, options?: ResourceOptions<A, C>): ResourceInit<T, A, C>;
+declare function resource<const A extends ActionList = readonly [], const C extends ActionList = readonly []>(options: ResourceOptions<A, C>): ResourceInit<unknown, A, C>;
+//#endregion
+//#region src/core/presets.d.ts
+type ReadOnlyMeta = {
+  readonly readOnly: true;
+};
+type DestructiveMeta = {
+  readonly destructive: true;
+};
+type CrudActions = {
+  readonly read: ReadOnlyMeta;
+  readonly update: ActionMeta;
+  readonly delete: DestructiveMeta;
+};
+type CrudCollection = {
+  readonly create: ActionMeta;
+  readonly list: ReadOnlyMeta;
+};
+type ReadableActions = {
+  readonly read: ReadOnlyMeta;
+};
+type ReadableCollection = {
+  readonly list: ReadOnlyMeta;
+};
+type WritableActions = {
+  readonly read: ReadOnlyMeta;
+  readonly update: ActionMeta;
+};
+declare const CRUD_ACTIONS: CrudActions;
+declare const CRUD_COLLECTION: CrudCollection;
+declare const READABLE_ACTIONS: ReadableActions;
+declare const READABLE_COLLECTION: ReadableCollection;
+declare const WRITABLE_ACTIONS: WritableActions;
+type EmptyRecord = Record<never, never>;
+declare const WRITABLE_COLLECTION: EmptyRecord;
+type ActionNames<A extends ActionList | undefined> = A extends readonly string[] ? A[number] & string : A extends Record<string, ActionMeta> ? keyof A & string : never;
+type ToActionRecord<A extends ActionList | undefined> = [ActionNames<A>] extends [never] ? EmptyRecord : { readonly [K in ActionNames<A>]: ActionMeta; };
+type OverlayMeta<Base extends ActionMeta, Extra extends ActionMeta> = Omit<Base, keyof Extra> & Extra;
+type MergeActionRecords<Base extends Record<string, ActionMeta>, Extra extends Record<string, ActionMeta>> = { readonly [K in keyof Base | keyof Extra]: K extends keyof Extra ? K extends keyof Base ? OverlayMeta<Base[K] & ActionMeta, Extra[K] & ActionMeta> : Extra[K] & ActionMeta : K extends keyof Base ? Base[K] & ActionMeta : never; };
+type PresetOptions<A extends ActionList | undefined = undefined, C extends ActionList | undefined = undefined> = {
+  readonly id?: string;
+  readonly parent?: ResourceParent;
+  readonly relations?: Readonly<Record<string, ResourceRelationInput>>;
+  readonly restricted?: string | ResourceRestricted;
+  readonly disclosure?: "hide" | "reveal";
+  readonly actions?: A;
+  readonly collection?: C;
+};
+type PresetResult<BaseA extends Record<string, ActionMeta>, BaseC extends Record<string, ActionMeta>, A extends ActionList | undefined, C extends ActionList | undefined> = {
+  readonly id?: string;
+  readonly parent?: ResourceParent;
+  readonly relations?: Readonly<Record<string, ResourceRelationInput>>;
+  readonly restricted?: string | ResourceRestricted;
+  readonly disclosure?: "hide" | "reveal";
+  readonly actions: MergeActionRecords<BaseA, ToActionRecord<A>>;
+  readonly collection?: MergeActionRecords<BaseC, ToActionRecord<C>>;
+};
+declare function crud<const A extends ActionList | undefined = undefined, const C extends ActionList | undefined = undefined>(options?: PresetOptions<A, C>): PresetResult<typeof CRUD_ACTIONS, typeof CRUD_COLLECTION, A, C>;
+declare function readable<const A extends ActionList | undefined = undefined, const C extends ActionList | undefined = undefined>(options?: PresetOptions<A, C>): PresetResult<typeof READABLE_ACTIONS, typeof READABLE_COLLECTION, A, C>;
+declare function writable<const A extends ActionList | undefined = undefined, const C extends ActionList | undefined = undefined>(options?: PresetOptions<A, C>): PresetResult<typeof WRITABLE_ACTIONS, typeof WRITABLE_COLLECTION, A, C>;
+//#endregion
+//#region src/core/role-builder.d.ts
+type RoleGrants = readonly (Omit<Grant, "role" | "scope"> | readonly Omit<Grant, "role" | "scope">[])[];
+/** A role held at a named scope: `on` is checked against `definePolicy({ scopes })`. */
+declare function role<const S extends string>(name: string | Role, grants: RoleGrants, options: RoleOptions<S> & {
+  readonly on: S;
+}): RoleBinding<S>;
+/** A global role, or one held on a resource. */
+declare function role(name: string | Role, grants: RoleGrants, options?: RoleOptions<never>): RoleBinding<never>;
+/** Options built at runtime: the scope name is only checked by `definePolicy`. */
+declare function role(name: string | Role, grants: RoleGrants, options?: RoleOptions): RoleBinding;
+declare function normalizeAssurance(input: AssuranceRequirement | undefined): AssuranceRequirement | undefined;
+//#endregion
+//#region src/core/grant-builders.d.ts
+declare function allow<T, K extends PermissionKind = PermissionKind>(permission: Permission<string, T, K> | readonly Permission<string, T, K>[], condition?: GrantCondition<T, K>): Omit<Grant, "role" | "scope"> | Omit<Grant, "role" | "scope">[];
+declare function deny<T, K extends PermissionKind = PermissionKind>(permission: Permission<string, T, K> | readonly Permission<string, T, K>[], condition?: GrantCondition<T, K>): Omit<Grant, "role" | "scope"> | Omit<Grant, "role" | "scope">[];
+//#endregion
+//#region src/core/approval-normalize.d.ts
+declare function normalizeApproval(approval: ApprovalOption | undefined, permission?: string): Grant["approval"];
+//#endregion
+//#region src/core/elevated.d.ts
+/**
+ * The only deny override: a break-glass grant overrides deny grants whose
+ * `name` it lists, and nothing else. It is an allow that stays non-portable
+ * (RLS never compiles it) and grants only once its `requires` are met.
+ */
+declare function breakGlass<T>(permission: Permission<string, T> | readonly Permission<string, T>[], options?: BreakGlassOptions): Omit<Grant, "role" | "scope"> | Omit<Grant, "role" | "scope">[];
+/**
+ * Support access with tenant consent: a role a vendor holds only through a
+ * consented, time-bound `via: 'support'` membership. `actorRequired` denies
+ * every decision under it without an `act`; `forbid` compiles to deny grants
+ * scoped to `via: 'support'`.
+ */
+declare function supportAccess<const S extends string>(options: SupportAccessOptions<S> & {
+  readonly on: S;
+}): RoleBinding<S>;
+/** Support access held in the `tenant` scope. */
+declare function supportAccess(options: SupportAccessOptions<never>): RoleBinding<"tenant">;
+type ActivateInput = {
+  readonly role: string | Role;
+  /** The scope the activation applies in (a declared name or the `tenant` / `team` alias). */
+  readonly scope: string;
+  readonly id: string;
+  /** Ancestor scope ids, keyed by scope name, for a nested-scope activation. */
+  readonly within?: Readonly<Record<string, string>>;
+  /** Seconds the elevation lasts; capped at the role's `maxDuration`. */
+  readonly duration?: number;
+  readonly reason?: string;
+};
+/**
+ * Requests a just-in-time role activation. It never writes: a granted
+ * decision carries the elevated membership under `elevation` for the app to
+ * write. `approval-required` comes back first when the role's `activation`
+ * sets `approval`. Fail-closed: an unknown role, an ineligible subject, a
+ * missing justification or stale authentication all deny.
+ */
+/**
+ * Requests a just-in-time activation of an eligible role for the subject of
+ * `permdock`. It never writes: a granted decision carries the elevated
+ * membership under `elevation` for the app to write, and
+ * `approval-required` comes back first when the role's `activation` sets
+ * `approval`. An instance built from a snapshot denies with `unsupported`.
+ */
+declare function activate(permdock: InstanceHandle, input: ActivateInput): Decision;
+//#endregion
+//#region src/core/ownership.d.ts
+/** Who a role change is about: their principal id and their membership in the scope instance. */
+type RoleChangeTarget = {
+  readonly id: string;
+  /** The kind of the target's membership in the instance (`staff`, `contact`, ...). */
+  readonly via?: string;
+  /** The roles the target holds in the instance now. */
+  readonly roles?: readonly string[];
+  /** `idp` when the identity provider owns the target's membership: the application cannot change it. */
+  readonly managedBy?: "idp";
+};
+type RoleChangeBase = {
+  readonly kind: "assign" | "revoke" | "transfer";
+  readonly role: string | Role;
+  /** Ids of the instance's ancestor scopes; a holder there may assign here. */
+  readonly within?: Readonly<Record<string, string>>;
+  readonly target: RoleChangeTarget;
+  /**
+   * How many principals hold `role` in the instance now, from the
+   * application's store. Without it a role with `min`, `max` or
+   * `transferOnly` is denied.
+   */
+  readonly holders?: number;
+};
+/**
+ * A role held at a named scope instance (`scope` is a declared name or alias
+ * and `id` the instance), or a global role: `scope: 'global'` with no `id`.
+ * A global change has no tenant, so `within` and `holders` do not apply to it.
+ */
+type RoleChange = RoleChangeBase & ({
+  /** The scope the role is held at (a declared name or alias). */
+  readonly scope: string;
+  /** The scope instance. */
+  readonly id: string;
+} | {
+  readonly scope: "global";
+  readonly id?: undefined;
+});
+/**
+ * `granted` names the role that authorised the change (`null` when a
+ * `meta.manageRoles` holder or the declared-role ceiling did); `denied` lists
+ * every rule the change breaks.
+ */
+type RoleChangeDecision = {
+  readonly outcome: "granted";
+  readonly change: RoleChange;
+  readonly role: string | null;
+} | {
+  readonly outcome: "denied";
+  readonly change: RoleChange;
+  readonly denials: readonly Denial[];
+};
+type RoleChangeOptions = {
+  /**
+   * `true` when the application loaded `change.within` from its own store
+   * (the instance's stored parent), not from the request. Without it, a
+   * nested instance's tenant comes only from a live membership the actor
+   * holds on that instance or under it.
+   */
+  readonly trusted?: boolean;
+};
+/**
+ * The one rule check behind `permdock.decideRoleChange`. The actor is always
+ * the instance's own principal; nothing in `change` can stand in for it.
+ */
+/**
+ * Whether the subject of `permdock` may assign, revoke or transfer a role
+ * in one scope instance: `assigns`, the ceiling, `for`, `exclusiveWith`,
+ * `min`, `max` and `transferOnly`. It never writes; the application does,
+ * and generated RLS triggers re-check the holder counts at commit. A nested
+ * instance's tenant comes from a live membership the subject holds on it,
+ * or from `change.within` only with `{ trusted: true }`; otherwise
+ * `no-membership`. An instance built from a snapshot denies with
+ * `unsupported`.
+ */
+declare function decideRoleChange(permdock: InstanceHandle, change: RoleChange, options?: RoleChangeOptions): RoleChangeDecision;
+//#endregion
+//#region src/core/parse-sink-events.d.ts
+/**
+ * Validates one untrusted sink event against its family's schema and returns
+ * a frozen copy, or `null` for anything else. Never throws.
+ */
+declare function parseSinkEvent(value: unknown): SinkEvent | null;
+/**
+ * Validates an untrusted list of sink events, such as a request body a sink
+ * receiver read. Each event that fails its schema is dropped, and a value
+ * that is not an array yields no events. Never throws.
+ */
+declare function parseSinkEvents(value: unknown): readonly SinkEvent[];
+/** Validates the data of a `com.permdock.catalog.*` CloudEvent; `null` when it does not match. */
+declare function parseCatalogEventData(value: unknown): CatalogEventData | null;
+/**
+ * Validates one CloudEvent against the closed type list, its `dataschema` and
+ * its data shape; `null` for anything else, a reserved type included. Never
+ * throws.
+ */
+declare function parseCloudEvent(value: unknown): CloudEvent | null;
+/**
+ * Validates a CloudEvents JSON batch (`application/cloudevents-batch+json`):
+ * `null` unless the value is an array and every event in it is valid.
+ */
+declare function parseCloudEventBatch(value: unknown): readonly CloudEvent[] | null;
+//#endregion
+//#region src/core/event-schemas.d.ts
+/** The URL each event family's schema is published at, and its CloudEvents `dataschema`. */
+declare const EVENT_SCHEMA_IDS: {
+  readonly decision: "https://permdock.com/schemas/decision-event-v1.json";
+  readonly directory: "https://permdock.com/schemas/directory-event-v1.json";
+  readonly membership: "https://permdock.com/schemas/membership-event-v1.json";
+  readonly credential: "https://permdock.com/schemas/credential-event-v1.json";
+  readonly access: "https://permdock.com/schemas/access-event-v1.json";
+  readonly automation: "https://permdock.com/schemas/automation-event-v1.json";
+  readonly catalog: "https://permdock.com/schemas/catalog-event-v1.json";
+  readonly delivery: "https://permdock.com/schemas/delivery-event-v1.json";
+};
+declare const DECISION_EVENT_SCHEMA: JsonSchemaNode;
+declare const DIRECTORY_EVENT_SCHEMA: JsonSchemaNode;
+declare const MEMBERSHIP_EVENT_SCHEMA: JsonSchemaNode;
+declare const CREDENTIAL_EVENT_SCHEMA: JsonSchemaNode;
+declare const ACCESS_EVENT_SCHEMA: JsonSchemaNode;
+declare const AUTOMATION_EVENT_SCHEMA: JsonSchemaNode;
+declare const CATALOG_EVENT_SCHEMA: JsonSchemaNode;
+declare const DELIVERY_EVENT_SCHEMA: JsonSchemaNode;
+/** Every sink event family's schema, keyed by the event's `type`. */
+declare const SINK_EVENT_SCHEMAS: {
+  readonly decision: JsonSchemaNode;
+  readonly directory: JsonSchemaNode;
+  readonly membership: JsonSchemaNode;
+  readonly credential: JsonSchemaNode;
+  readonly access: JsonSchemaNode;
+  readonly automation: JsonSchemaNode;
+  readonly delivery: JsonSchemaNode;
+};
+//#endregion
+//#region src/core/ocsf.d.ts
+/** The OCSF schema version `toOcsf` emits. */
+declare const OCSF_VERSION = "1.9.0";
+/**
+ * An OCSF Authorize Session (class 3003, category Identity and Access Management) event.
+ * API Activity (6003) would fit a per-request decision, but it requires `api` and
+ * `src_endpoint`, which a decision event does not carry.
+ */
+type OcsfAuthorizeSession = {
+  readonly class_uid: 3003;
+  readonly category_uid: 3;
+  readonly activity_id: 1;
+  readonly type_uid: 300301;
+  readonly severity_id: 1 | 4;
+  readonly time: number;
+  readonly status_id: 0 | 1 | 2 | 99;
+  /** OCSF requires a source label for status 99: `Approval Required`. */
+  readonly status: "Unknown" | "Success" | "Failure" | "Approval Required";
+  readonly status_detail?: string;
+  readonly message: string;
+  readonly privileges: readonly string[];
+  /** OCSF requires `user`; an anonymous subject is `{ name: 'anonymous' }`. */
+  readonly user: {
+    readonly uid: string;
+  } | {
+    readonly name: "anonymous";
+  };
+  readonly actor?: {
+    readonly user?: {
+      readonly uid: string;
+    };
+    readonly app_name?: string;
+  };
+  readonly metadata: {
+    readonly version: typeof OCSF_VERSION;
+    readonly product: {
+      readonly name: "PermDock";
+      readonly vendor_name: "PermDock";
+      readonly feature?: {
+        readonly name: string;
+      };
+    };
+    readonly tenant_uid?: string;
+    readonly correlation_uid?: string;
+  };
+  readonly unmapped: {
+    readonly outcome: DecisionEvent["outcome"];
+    readonly scope: string;
+    readonly resource: DecisionEvent["resource"];
+    readonly call: DecisionEvent["call"];
+    readonly phase?: DecisionEvent["phase"];
+    readonly role?: string | null;
+    /** The matched grant's declared `name`. */
+    readonly grant?: string;
+    /** The names of the app obligations the decision carries. */
+    readonly obligations?: readonly string[];
+    readonly via?: string | null;
+    /** Set high-severity break-glass events apart in a SIEM. */
+    readonly breakGlass?: true;
+    readonly purpose?: readonly string[];
+    readonly reason?: string;
+  };
+};
+/**
+ * Projects a decision or approval event onto OCSF Authorize Session; the event itself is unchanged.
+ * An event whose `at` does not parse has no OCSF `time` and projects to `undefined`.
+ */
+declare function toOcsf(event: DecisionEvent): OcsfAuthorizeSession | undefined;
+/**
+ * An OCSF User Management (class 3007) event for a support-access lifecycle
+ * event: `started` enables the session, `ended` and `revoked` disable it.
+ * Support access is high severity, so a SIEM can alert on vendor access.
+ * OCSF 1.9.0 deprecates Account Change (3001) in favour of this class.
+ */
+type OcsfUserManagement = {
+  readonly class_uid: 3007;
+  readonly category_uid: 3;
+  /** 4 Enable for `started`, 5 Disable for `ended` and `revoked`. */
+  readonly activity_id: 4 | 5;
+  readonly type_uid: 300704 | 300705;
+  readonly severity_id: 4;
+  readonly time: number;
+  readonly message: string;
+  readonly user: {
+    readonly uid: string;
+  };
+  readonly actor?: {
+    readonly user?: {
+      readonly uid: string;
+    };
+  };
+  readonly metadata: {
+    readonly version: typeof OCSF_VERSION;
+    readonly product: {
+      readonly name: "PermDock";
+      readonly vendor_name: "PermDock";
+    };
+    readonly tenant_uid: string;
+  };
+  readonly unmapped: {
+    readonly operation: AccessEvent["operation"];
+    readonly via: string;
+    readonly roles: readonly string[];
+    readonly member?: {
+      readonly group: string;
+    };
+    readonly grantedBy?: string;
+    readonly reason?: string;
+  };
+};
+/** An access event whose `at` does not parse projects to `undefined`. */
+declare function accessToOcsf(event: AccessEvent): OcsfUserManagement | undefined;
+//#endregion
+//#region src/core/csv.d.ts
+/** The CSV export columns, in order; the header row of every CSV file. */
+declare const CSV_COLUMNS: readonly ["time", "principal", "actor", "tenant", "permission", "outcome", "matched.role", "via", "denials.reason", "token"];
+/**
+ * One RFC 4180 row for a decision or approval event, without a line
+ * terminator; join rows with CRLF under a `CSV_COLUMNS` header.
+ */
+declare function toCsvRow(event: DecisionEvent): string;
+//#endregion
+//#region src/core/catalog-fingerprint.d.ts
+/**
+ * The catalog v1 fingerprint: the `sha-256:` digest of its RFC 8785 JSON without `generatedAt`, `generator`, `fingerprint`
+ * and every `permissions[].usages`, so neither the CLI version, the clock nor
+ * call sites change it.
+ */
+declare function catalogFingerprint(catalog: unknown): string;
+//#endregion
+//#region src/core/delegation.d.ts
+type DelegatedPermission = Pick<Permission, "scope" | "resource" | "action">;
+/**
+ * Whether a delegated caller may use a permission its principal holds, through
+ * OAuth `scopes`, RFC 9396 `authorizationDetails` or GNAP `access`.
+ * `undefined` means covered; otherwise the denial reason `decide` would add.
+ */
+declare function coveredByDelegation(permission: DelegatedPermission, delegation: Delegation | undefined, resourceId?: string, hasActor?: boolean): DenialReason | undefined;
+/**
+ * The permission keys the policy's delegations let `subject.actor` use for
+ * `subject.principal` right now: the union over every active delegation whose
+ * `to` matches the actor and whose `from` the principal holds. `undefined`
+ * when none applies, so the call falls back to the token delegation alone.
+ * An actor with `readOnly: true` gets only each delegation's read-only keys.
+ * Attenuation only: a key here still needs a matching allow and no deny.
+ */
+declare function delegatedPermissions(delegations: readonly PolicyDelegation[] | undefined, subject: Subject, heldRoles: ReadonlySet<string>, now: number): ReadonlySet<string> | undefined;
+//#endregion
+export { ShadowMismatch as $, CustomRoleValidation as $t, decideRoleChange as A, isExternallyManaged as At, crud as B, getResource as Bt, parseCloudEventBatch as C, MemoryRelationSourceData as Ct, RoleChangeDecision as D, claimsFirst as Dt, RoleChange as E, stripeEntitlementSource as Et, normalizeApproval as F, memorySettingsSource as Ft, definePermissions as G, separationConflicts as Gt, writable as H, listPermissions as Ht, allow as I, memorySnapshotSource as It, CustomRoleReader as J, fromSnapshot as Jt, SnapshotForOptions as K, requiresApproval as Kt, deny as L, sqlFunction as Lt, activate as M, memoryCustomRoleSource as Mt, breakGlass as N, memoryEntitlementSource as Nt, RoleChangeOptions as O, composeMemberships as Ot, supportAccess as P, memoryMembershipSource as Pt, LegacyCheck as Q, CustomRoleRename as Qt, normalizeAssurance as R, opaque as Rt, parseCloudEvent as S, MemoryEdge as St, parseSinkEvents as T, StripeEntitlementsClient as Tt, formerKeys as U, mergePermissions as Ut, readable as V, isPermission as Vt, resource as W, definePolicy as Wt, customRoleSource as X, CustomRoleDrop as Xt, CustomRoleSourceOptions as Y, parseSnapshot as Yt, mayAccess as Z, CustomRoleDropReason as Zt, DIRECTORY_EVENT_SCHEMA as _, signPolicyDocument as _t, toCsvRow as a, principal as an, localSnapshotManifest as at, SINK_EVENT_SCHEMAS as b, WhoCan as bt, OcsfUserManagement as c, ArazzoSimulateInput as ct, ACCESS_EVENT_SCHEMA as d, simulateArazzo as dt, ResolvedCustomRole as en, ShadowOptions as et, AUTOMATION_EVENT_SCHEMA as f, deliveryEvent as ft, DELIVERY_EVENT_SCHEMA as g, SignPolicyDocumentOptions as gt, DECISION_EVENT_SCHEMA as h, snapshotFromClaims as ht, CSV_COLUMNS as i, context as in, AppProfile as it, ActivateInput as j, APPROVAL_POLICY_UNAVAILABLE as jt, RoleChangeTarget as k, countHolders as kt, accessToOcsf as l, ArazzoStepResult as lt, CREDENTIAL_EVENT_SCHEMA as m, signSnapshot as mt, delegatedPermissions as n, resolveCustomRole as nn, defineApp as nt, OCSF_VERSION as o, ArazzoFinding as ot, CATALOG_EVENT_SCHEMA as p, SignSnapshotOptions as pt, snapshotFor as q, emptySnapshot as qt, catalogFingerprint as r, validateCustomRole as rn, AppOptions as rt, OcsfAuthorizeSession as s, ArazzoPlan as st, coveredByDelegation as t, customRoleClaim as tn, shadowMode as tt, toOcsf as u, arazzoFindings as ut, EVENT_SCHEMA_IDS as v, Holder as vt, parseSinkEvent as w, memoryRelationSource as wt, parseCatalogEventData as x, whoCan as xt, MEMBERSHIP_EVENT_SCHEMA as y, HoldingVia as yt, role as z, findPermission as zt };