permdock 0.4.0 → 0.6.0

package/dist/index-B8YjkEZ4.d.ts

@@ -0,0 +1,210 @@
+import { Ct as Credential, Nn as Decision, St as ApiKeyPrincipal, T as Policy, Tt as CredentialKind, U as CredentialVerifier, ar as Subject, at as SettingsSource, dt as TokenVerifier, gt as SupportSession, j as PolicyVocabulary, lt as TokenFailureCause, q as DecisionSink, qt as AuthEvent, rr as Principal, ut as TokenSigner } from "./policy-types-n0uRTsW8.js";
+import { E as PermissionTree, w as Permission } from "./vocabulary-CN8H_9UF.js";
+import { p as PrincipalSource } from "./permdock-SV8ZINYT.js";
+import { t as Disclosure } from "./problem-details-B45V5d2b.js";
+import { a as ProblemDetails, t as ApprovalHint } from "./errors-DH5QEGXh.js";
+import { c as ServerPermDock, l as ServerPermDockOptions } from "./server-types-CKQiCnON.js";
+//#region src/server/create.d.ts
+/**
+ * The Fetch factory behind every HTTP adapter. The subject and actor are
+ * resolved once per `Request`; one instance is cached per `(Request, tenant)`,
+ * so a global middleware and a later tenant-scoped `protect` never share a
+ * tenant.
+ */
+declare function createPermDock<TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, given: ServerPermDockOptions<TUser>): ServerPermDock<V>;
+//#endregion
+//#region src/server/map-error.d.ts
+type ProblemFromErrorOptions = {
+  readonly instance?: string;
+  /** Whether the request carried credentials, which picks the `401` challenge. */
+  readonly credentials?: boolean;
+};
+/**
+ * Turns a thrown PermDock error into its Problem Details response, with the
+ * status, `WWW-Authenticate` and rate-limit fields `protect` sends for the
+ * same decision. Returns `undefined` for anything else so the framework's own
+ * error path takes over.
+ */
+declare function problemFromError(error: unknown, options?: ProblemFromErrorOptions): Response | undefined;
+//#endregion
+//#region src/server/credentials.d.ts
+/** `on('auth')` causes for an API key that resolves to the anonymous subject. */
+type ApiKeyFailureCause = "malformed" | "unknown-credential" | "invalid-claims" | "expired" | "credential-policy" | "credential-revoked" | "owner-unavailable";
+/** An opaque key split at its last `_`: `pdk_<id>_<secret><checksum>`. */
+type ApiKeyParts = {
+  readonly id: string;
+  readonly secret: string;
+};
+/** What an application stores per key: the credential and the key's hash, never the key. */
+type StoredCredential = {
+  readonly credential: Credential;
+  readonly hash: string;
+};
+/**
+ * Splits `pdk_<id>_<secret><checksum>`: `id` is 1 to 128 of `A-Z a-z 0-9 _ -`,
+ * the secret 43 base62 characters and the checksum the 6 base62 characters of
+ * the CRC-32 of everything before it. Anything else, including a checksum
+ * that does not match, is `undefined`.
+ */
+declare function parseApiKey(key: unknown): ApiKeyParts | undefined;
+/**
+ * Splits `pdfeed_<id>_<secret><checksum>`. `id` is `isFeedId`, the secret is
+ * 26 lowercase base32 characters and the checksum is 6 more. A checksum that
+ * does not match is `undefined`.
+ */
+declare function parseFeedKey(key: unknown): ApiKeyParts | undefined;
+/**
+ * A fresh `pdfeed_<id>_<secret><checksum>`: 26 lowercase base32 characters
+ * (130 bits) and a 6-character CRC-32 checksum. The whole key is lowercase.
+ */
+declare function generateFeedKey(id: string): string;
+/**
+ * A fresh `pdk_<id>_<secret><checksum>`: a 43-character base62 secret (about
+ * 256 bits) and a 6-character CRC-32 checksum, so a secret scanner can tell a
+ * real key from a lookalike without calling the issuer.
+ */
+declare function generateApiKey(id: string): string;
+/** base64url SHA-256 of the whole key, the value to store and compare. */
+declare function hashApiKey(key: string): Promise<string>;
+/**
+ * A `CredentialVerifier` over the application's own table: `find` looks a
+ * key up by the id in it, and the key's hash is compared in constant time.
+ * A record that is not a valid v1 credential, or whose id is not the key's,
+ * verifies to `null`. A throwing `find` propagates, so the resolver denies
+ * with `source-threw`.
+ */
+declare function apiKeyVerifier(options: {
+  readonly find: (id: string) => StoredCredential | null | undefined | Promise<StoredCredential | null | undefined>;
+  /** Passed through as the verifier's `touch`, for a `lastUsedAt` column. */
+  readonly touch?: CredentialVerifier["touch"];
+}): CredentialVerifier;
+type MemoryCredentialStore = CredentialVerifier & {
+  /** Stores `credential` and returns its key; the key is never stored. */
+  issue(credential: Credential): Promise<string>;
+  /** A new secret for the same id; the old key stops verifying at once. */
+  rotate(id: string): Promise<string | undefined>;
+  /** `true` when a credential was removed. */
+  revoke(id: string): boolean;
+  list(): readonly Credential[];
+  /** When `touch` last recorded a use of `id`, as RFC 3339. */
+  lastUsedAt(id: string): string | undefined;
+};
+/**
+ * In-process credentials for tests and single-replica apps. `issue`, `rotate`
+ * and `revoke` write `credential` events to `sink` when one is given.
+ */
+declare function memoryCredentialStore(options?: {
+  readonly sink?: DecisionSink;
+  readonly source?: string;
+}): MemoryCredentialStore;
+type ApiKeySubjectOptions = {
+  readonly verifier: CredentialVerifier;
+  /** The definitions, to turn the credential's permission keys into its delegation. */
+  readonly permissions: PermissionTree;
+  /**
+   * Loads the live owner of a user-bound key: roles and memberships as of
+   * this request, asked with the key's tenant. `null` (a deleted or
+   * suspended user) is anonymous with `owner-unavailable`, and a throw is
+   * `source-threw`. Without it the owner is `{ id, kind: 'user' }` and its
+   * rights come from the `memberships` source passed to `createPermDock`.
+   */
+  readonly principals?: PrincipalSource;
+  /** The tenant the request acts in: a user key is held to its owner's memberships there. */
+  readonly tenant?: string;
+  /** `true` when the application revoked the credential id; a throw denies. */
+  readonly revoked?: (id: string) => boolean | Promise<boolean>;
+  /**
+   * The tenant `credentials` policy, checked on every use so a tightened
+   * policy reaches existing keys: a service key's own tenant, a user key's
+   * the `tenant` the resolver is called with. A throw denies.
+   */
+  readonly settings?: SettingsSource;
+  /** Receives a `credential` event with operation `used` for sampled uses. */
+  readonly sink?: DecisionSink;
+  /** Fraction of uses reported to `sink`, in `(0, 1]`; defaults to 1. */
+  readonly sample?: number;
+  /** The `source` of `used` events; defaults to `permdock`. */
+  readonly source?: string;
+  readonly onAuth?: (event: AuthEvent) => void;
+  readonly requestId?: string;
+  /** Accept only these credential kinds. A key of another kind is anonymous. */
+  readonly kinds?: readonly CredentialKind[];
+};
+/**
+ * Resolves an opaque API key (`pdk_<id>_<secret>`) into the subject its
+ * credential acts as. Every failure (a malformed or unknown key, a record
+ * that is not a valid credential, expiry, a tenant policy the key breaks, a
+ * revoked id, a missing owner, a throwing verifier, source or callback) is
+ * the anonymous subject, never a throw.
+ */
+declare function subjectFromApiKey(key: string | undefined | null, options: ApiKeySubjectOptions): Promise<Subject<ApiKeyPrincipal>>;
+//#endregion
+//#region src/server/support-session.d.ts
+/** `on('auth')` causes: a verification failure, or one of the session checks. */
+type SupportSessionFailureCause = TokenFailureCause | "invalid-claims" | "session-ended" | "principal-unavailable" | "actor-unavailable";
+/** The live state of each support session, so one can end before it expires. */
+type SupportSessionSource = {
+  /** The session as of now, or `null` for an unknown one. A throw ends it. */
+  session(id: string): {
+    readonly id: string;
+    readonly ended?: boolean;
+  } | null | Promise<{
+    readonly id: string;
+    readonly ended?: boolean;
+  } | null>;
+};
+type SupportSessionSubjectOptions = {
+  readonly verifier: TokenVerifier;
+  /** Loads the viewed principal and the support actor, live, on every request. */
+  readonly principals: PrincipalSource;
+  /** The permission tree the session's keys name. */
+  readonly permissions: PermissionTree;
+  /** Checked on every request when set; an unknown or ended session denies. */
+  readonly sessions?: SupportSessionSource;
+  readonly audience?: string | readonly string[];
+  readonly issuer?: string;
+  readonly clockTolerance?: number;
+  readonly onAuth?: (event: AuthEvent) => void;
+  readonly requestId?: string;
+};
+/** `subject.context.supportSession` of a subject resolved from a session token. */
+type SupportSessionContext = {
+  readonly id: string;
+  readonly reason: string;
+  readonly approvedBy?: string;
+  readonly reference?: string;
+};
+/**
+ * Signs a granted `SupportSession` as a `vnd.permdock.support-session+jwt`
+ * (`sub` the viewed principal, `act` the support actor, `jti` the session
+ * id) that expires with the session. Throws a `TypeError` for a record
+ * `parseSupportSession` refuses.
+ */
+declare function signSupportSession(session: SupportSession, signer: TokenSigner, options?: {
+  readonly audience?: string | readonly string[];
+}): Promise<string>;
+/**
+ * Resolves a `vnd.permdock.support-session+jwt` into the subject each
+ * request of the session acts as: the viewed principal loaded live, a
+ * `support` actor, the session's permissions as the delegation and
+ * `context.supportSession`. The actor must still exist. Every failure is the
+ * anonymous subject, never a throw.
+ */
+declare function subjectFromSupportSession(token: string | undefined | null, options: SupportSessionSubjectOptions): Promise<Subject>;
+//#endregion
+//#region src/server/problem.d.ts
+declare function wwwAuthenticate(decision: Decision, permission: Permission | undefined, credentials?: boolean): string | undefined;
+declare function problemResponse(details: ProblemDetails, permission?: Permission, decision?: Decision, extra?: Readonly<Record<string, string>>, credentials?: boolean): Response;
+declare function validationProblem(detail: string): Response;
+declare function problemFromDecision(decision: Decision, permission: Permission, subject: Subject | undefined, options?: {
+  readonly instance?: string;
+  readonly approval?: ApprovalHint;
+  /** `'hide'` on a loaded row: a denial answers as `404` `/not-found`. */
+  readonly disclosure?: Disclosure;
+  /** Whether the request carried credentials, which picks the `401` challenge. */
+  readonly credentials?: boolean;
+  /** The scope an `insufficient_scope` challenge names; the permission's own scope when absent. */
+  readonly scope?: string;
+}): Response;
+//#endregion
+export { subjectFromApiKey as C, createPermDock as E, parseFeedKey as S, problemFromError as T, generateApiKey as _, SupportSessionContext as a, memoryCredentialStore as b, SupportSessionSubjectOptions as c, ApiKeyFailureCause as d, ApiKeyParts as f, apiKeyVerifier as g, StoredCredential as h, wwwAuthenticate as i, signSupportSession as l, MemoryCredentialStore as m, problemResponse as n, SupportSessionFailureCause as o, ApiKeySubjectOptions as p, validationProblem as r, SupportSessionSource as s, problemFromDecision as t, subjectFromSupportSession as u, generateFeedKey as v, ProblemFromErrorOptions as w, parseApiKey as x, hashApiKey as y };

package/dist/index-C-6Letxg.d.ts

@@ -0,0 +1,431 @@
+import { Nn as Decision, Rt as Instant, T as Policy, Yn as AuthorizationDetail, ar as Subject, et as MembershipSource, fn as Approver, it as RelationSource, nr as Membership, ut as TokenSigner } from "./policy-types-n0uRTsW8.js";
+import { E as PermissionTree, V as AppData, w as Permission } from "./vocabulary-CN8H_9UF.js";
+import { r as PermDock } from "./permdock-SV8ZINYT.js";
+import { a as ApprovalDelegationSource, c as ApprovalListQuery, g as ApprovalVerdict, i as ApprovalDelegation, l as ApprovalPage, m as ApprovalStore, o as ApprovalInspectResult, r as ApprovalCancelMeta, s as ApprovalListFilter, u as ApprovalRequest } from "./types-BdtSDbBO.js";
+import { a as AccessReviewItemQuery, c as AccessReviewStore, i as AccessReviewItemPage, n as AccessReviewDecision, r as AccessReviewItem, t as AccessReview } from "./types-C_IiEs64.js";
+import { t as JsonSchemaNode } from "./json-schema-CN_iLFH2.js";
+//#region src/approvals/access-reviews/handler.d.ts
+type AccessReviewsHandlerOptions = {
+  readonly subject: (request: Request) => Subject | null | undefined | Promise<Subject | null | undefined>;
+  /**
+   * The reviewer's own instance, for `holder()` reviewers. Without it they
+   * match nobody.
+   */
+  readonly permdockFor?: (reviewer: Subject, tenant: string) => PermDock | Promise<PermDock>;
+};
+/**
+ * HTTP for one access-review store: `GET` a review and its items, `POST`
+ * `.../keep`, `.../revoke`, `.../applied` and `.../close`. A caller who is
+ * not a reviewer and did not open the review gets 404.
+ */
+declare function accessReviewsHandler(store: AccessReviewStore, options: AccessReviewsHandlerOptions): (request: Request) => Promise<Response>;
+//#endregion
+//#region src/approvals/access-reviews/decide.d.ts
+type AccessReviewVerdict = {
+  readonly status: "kept" | "revoked";
+  readonly by: Subject;
+  readonly note?: string;
+  /**
+   * The `holder(permission)` reviewers `by` holds, read from `by`'s own
+   * instance. Server-side input. Absent means none.
+   */
+  readonly permissions?: readonly string[];
+};
+/** Whether `by` is named as a reviewer. A link, a feed or a contact is never a reviewer. */
+declare function accessReviewerEligible(review: AccessReview, by: Subject, permissions?: readonly string[], now?: Instant): boolean;
+/**
+ * The decision to persist, or throws. A reviewer cannot decide a holding
+ * of their own principal. `holder()` matches only through `permissions`.
+ */
+declare function decideAccessReviewItem(review: AccessReview, item: AccessReviewItem, verdict: AccessReviewVerdict, at?: Instant): AccessReviewDecision;
+//#endregion
+//#region src/approvals/access-reviews/errors.d.ts
+type AccessReviewErrorCode = "review-not-found" | "review-closed" | "item-not-found" | "item-not-pending" | "reviewer-unauthenticated" | "reviewer-not-eligible" | "reviewer-is-holder" | "not-revoked" | "already-applied";
+declare class AccessReviewError extends Error {
+  override readonly name: "AccessReviewError";
+  readonly code: AccessReviewErrorCode;
+  constructor(code: AccessReviewErrorCode, message: string);
+}
+declare function isAccessReviewError(value: unknown): value is AccessReviewError;
+//#endregion
+//#region src/approvals/access-reviews/start.d.ts
+type AccessReviewHolder = {
+  readonly principal: string;
+  readonly permission: string;
+  readonly via: readonly string[];
+};
+type StartAccessReviewInput = {
+  readonly id: string;
+  readonly permissions: readonly Permission[];
+  readonly reviewers: Approver | readonly Approver[];
+  readonly dueAt: string;
+};
+type AccessReviewOptions = {
+  readonly reviews: AccessReviewStore;
+  /**
+   * Replaces the membership listing. The Supabase recipe passes the rows of
+   * `permitted_<scope>_users`. `complete` defaults to `true` for this path.
+   */
+  readonly holders?: readonly AccessReviewHolder[];
+  readonly complete?: boolean;
+  readonly memberships?: MembershipSource;
+  /** Scope name passed to `memberships.list`. Defaults to `tenant`. */
+  readonly scope?: string;
+  /**
+   * An instance for one member, used to confirm each holding with a rowless
+   * `decide`. Required when `holders` is omitted.
+   */
+  readonly permdockFor?: (principalId: string) => PermDock | Promise<PermDock>;
+  /**
+   * When set, a global role, a plan, a relation or an inherit grant on a
+   * reviewed permission makes `complete` false. Without it the membership
+   * path is incomplete, because those holders cannot be listed from a tenant.
+   */
+  readonly policy?: Policy;
+  readonly now?: Instant;
+};
+/**
+ * Opens a review of who holds `permissions` in the caller's active tenant.
+ * The caller must be signed in. PermDock stores the population and does not
+ * revoke anything: the application changes the source, then `markApplied`.
+ */
+declare function startAccessReview(permdock: PermDock, input: StartAccessReviewInput, options: AccessReviewOptions): Promise<AccessReview>;
+//#endregion
+//#region src/approvals/access-reviews/store.d.ts
+/** Pages items in `(principal, id)` order with the approval cursor codec. */
+declare function pageAccessReviewItems(matching: readonly AccessReviewItem[], query: AccessReviewItemQuery): AccessReviewItemPage;
+type MemoryAccessReviewStore = AccessReviewStore & {
+  readonly reviews: () => readonly AccessReview[];
+};
+/** In-process access reviews for tests and single-replica apps. */
+declare function memoryAccessReviewStore(): MemoryAccessReviewStore;
+//#endregion
+//#region src/approvals/delegation.d.ts
+/**
+ * A frozen copy of a delegation with only the known fields, or `undefined`
+ * when a known field has the wrong type, `until` is not after `from`, or
+ * the delegate and the delegator are the same principal.
+ */
+declare function parseApprovalDelegation(input: unknown): ApprovalDelegation | undefined;
+/** In-process delegations. An entry that does not parse is dropped. */
+declare function memoryApprovalDelegationSource(entries: readonly unknown[]): ApprovalDelegationSource;
+type ApprovalDelegationMatch = {
+  readonly delegation: ApprovalDelegation;
+  readonly delegator: Subject;
+  readonly relations: readonly string[];
+  readonly permissions: readonly string[];
+};
+type MatchDelegationOptions = {
+  readonly approvalDelegations?: ApprovalDelegationSource;
+  readonly subjectFor?: (principalId: string, request: ApprovalRequest) => Subject | null | undefined | Promise<Subject | null | undefined>;
+  readonly now?: Instant;
+  readonly requireDistinct: boolean;
+  readonly factsFor: (subject: Subject) => Promise<{
+    readonly relations: readonly string[];
+    readonly permissions: readonly string[];
+  }>;
+};
+/**
+ * The first active delegation under which `delegate` may approve `request`,
+ * or `undefined`. The delegator is resolved by `subjectFor` and checked with
+ * `assertApprover`, so relation and permission approvers use the delegator's
+ * facts. A throw, a missing option or a delegator the source does not name
+ * matches nobody. The delegator's own delegations are never read.
+ */
+declare function matchDelegation(request: ApprovalRequest, delegate: Subject, options: MatchDelegationOptions): Promise<ApprovalDelegationMatch | undefined>;
+//#endregion
+//#region src/approvals/idempotency.d.ts
+/** A response the approvals handler replays for a repeated `Idempotency-Key`. */
+type IdempotentResponse = {
+  /** Which request produced it: a reused key with another fingerprint is refused with `422`. */
+  readonly fingerprint: string;
+  readonly status: number;
+  readonly headers: readonly (readonly [name: string, value: string])[];
+  readonly body: string;
+};
+/**
+ * Where `approvalsHandler` keeps `Idempotency-Key` responses
+ * (draft-ietf-httpapi-idempotency-key-header). Keys arrive scoped to the
+ * approver. Share one store across instances so a retry that lands on another
+ * instance replays the first response.
+ */
+type IdempotencyStore = {
+  /** Names the implementation in errors and events. */
+  readonly name?: string;
+  get(key: string): IdempotentResponse | undefined | Promise<IdempotentResponse | undefined>;
+  /** `expiresAt` is epoch milliseconds; the store may drop the entry after it. */
+  set(key: string, response: IdempotentResponse, expiresAt: number): void | Promise<void>;
+};
+/** An in-process `IdempotencyStore`, for one instance and for tests. */
+declare function memoryIdempotencyStore(): IdempotencyStore;
+//#endregion
+//#region src/approvals/handler.d.ts
+type ApprovalsHandlerOptions = {
+  readonly subject: (request: Request) => Subject | null | undefined | Promise<Subject | null | undefined>;
+  /** Refuse the principal even on grants that set `approval: { distinct: false }`. */
+  readonly requireDistinctApprover?: boolean;
+  readonly signer?: TokenSigner;
+  readonly audience?: string | readonly string[];
+  /** Where `relation()` approvers are read, by the request's resource id; without it they match nobody. */
+  readonly relations?: RelationSource;
+  /** The policy's permission tree, for `through` links and `includes` on relation approvers. */
+  readonly permissions?: PermissionTree;
+  /**
+   * The approver's own instance in the request's tenant, for
+   * `holder(permission)` approvers (custom roles included when the instance
+   * reads a `CustomRoleSource`). Without it, or when it throws, they match nobody.
+   */
+  readonly permdockFor?: (approver: Subject, request: ApprovalRequest) => PermDock | Promise<PermDock>;
+  /**
+   * Out-of-office delegations. With `subjectFor`, a caller who is not an
+   * approver may approve as someone who delegated to them. Without either,
+   * delegation matches nobody.
+   */
+  readonly approvalDelegations?: ApprovalDelegationSource;
+  /**
+   * Resolves a delegator's subject from their principal id. Server-side:
+   * never from the request body. A throw matches nobody.
+   */
+  readonly subjectFor?: (principalId: string, request: ApprovalRequest) => Subject | null | undefined | Promise<Subject | null | undefined>;
+  /**
+   * Where `Idempotency-Key` responses on approve and reject are kept for 24
+   * hours; a `memoryIdempotencyStore()` per handler when absent.
+   */
+  readonly idempotency?: IdempotencyStore;
+};
+/** An approval as the approvals API shows it: never the resume `token`. */
+type ApprovalView = Omit<ApprovalRequest, "token">;
+declare function approvalsHandler(store: ApprovalStore, options: ApprovalsHandlerOptions): (request: Request) => Promise<Response>;
+//#endregion
+//#region src/approvals/parse-request.d.ts
+/**
+ * Reads an `ApprovalRequest` (parsed, or the JSON text) as an approval store
+ * or the Cloud returns it, validated against
+ * `schemas/approval-request-v1.json`. Returns a deep-frozen copy, or `null`
+ * for anything that does not match, including a `__proto__`, `constructor`
+ * or `prototype` key.
+ */
+declare function parseApprovalRequest(value: unknown): ApprovalRequest | null;
+//#endregion
+//#region src/approvals/request-schema.d.ts
+/**
+ * `schemas/approval-request-v1.json`: the `ApprovalRequest` an approval store
+ * holds. Self-contained (`$defs`, no remote `$ref`) so `rls.jsonSchema` can
+ * inline it into a pg_jsonschema check constraint.
+ */
+declare const APPROVAL_REQUEST_SCHEMA: JsonSchemaNode;
+//#endregion
+//#region src/approvals/signature.d.ts
+/** One recorded approval as the `approvals` claim of a `vnd.permdock.approval+jwt` carries it. */
+type ApprovalSignatureEntry = {
+  readonly by: string;
+  /** RFC 3339. */
+  readonly at: string;
+  readonly stage?: number;
+  readonly vouched?: string;
+  readonly on_behalf_of?: string;
+  readonly delegation?: string;
+};
+/**
+ * The claims of a `vnd.permdock.approval+jwt` other than `iss`, `aud`,
+ * `iat`, `exp` and `jti`, which the signer sets: `jti` is the request `id`,
+ * `iat` its `resolvedAt` and `exp` its `expiresAt`.
+ */
+type ApprovalSignatureClaims = {
+  readonly sub?: string;
+  /** RFC 8693: the actor that asked for the approval. */
+  readonly act?: {
+    readonly sub: string;
+  };
+  /** The `PermDock-Approval` token the signature approves. */
+  readonly token: string;
+  readonly resolved_by?: string;
+  readonly approvals: readonly ApprovalSignatureEntry[];
+  /** RFC 9396: one entry, the approved action on the approved resource. */
+  readonly authorization_details: readonly [AuthorizationDetail];
+};
+declare function approvalSignatureClaims(request: ApprovalRequest): ApprovalSignatureClaims;
+type SignApprovalOptions = {
+  /** `aud`: the resource server that verifies the signature. */
+  readonly audience?: string | readonly string[];
+};
+/**
+ * Signs an approved request as a `vnd.permdock.approval+jwt`: `jti` is the
+ * request id, `iat` its `resolvedAt` and `exp` its `expiresAt`. `undefined`
+ * without a signer or for any status but `approved`.
+ */
+declare function signApproval(request: ApprovalRequest, signer: TokenSigner | undefined, options?: SignApprovalOptions): Promise<string | undefined>;
+//#endregion
+//#region src/approvals/relations.d.ts
+type ApproverRelationsOptions = {
+  /** The object graph relation approvers are read from; without it they match nobody. */
+  readonly relations?: RelationSource;
+  /** The permission tree the policy declares; needed to follow `through` links and `includes`. */
+  readonly permissions?: PermissionTree;
+  /** The clock relation expiry is read at; defaults to the current time. */
+  readonly now?: Instant;
+};
+/**
+ * The relation approvers of `request` that `subject` holds on its resource,
+ * keyed by `approverRelationKey`, for `ApprovalVerdict.relations`. Reads go
+ * through `relations` by the request's resource id; a request without an id,
+ * a missing source or a read that fails holds nothing.
+ */
+declare function approverRelations(request: ApprovalRequest, subject: Subject, options: ApproverRelationsOptions): Promise<readonly string[]>;
+//#endregion
+//#region src/approvals/helpers.d.ts
+declare function summarizeSubject(subject: Subject): ApprovalRequest["subject"];
+declare function requestApproval(store: ApprovalStore, decision: Extract<Decision, {
+  readonly outcome: "approval-required";
+}>, meta: {
+  readonly permission: Permission | {
+    readonly key: string;
+    readonly scope: string;
+    readonly resource: string;
+  };
+  readonly resource?: {
+    readonly type: string;
+    readonly id?: string;
+  };
+  readonly subject: Subject;
+  readonly membership?: Membership;
+  readonly adapter?: string;
+  readonly ttl?: number;
+  readonly now?: Instant;
+  readonly detail?: string;
+  /** The application's own data for the request; plain JSON, checked here. */
+  readonly x?: AppData;
+}): Promise<ApprovalRequest>;
+/**
+ * Checks `verdict.by` and resolves the request. Relation approvers are read
+ * through `options.relations` unless `verdict.relations` is already set.
+ */
+declare function resolveApproval(store: ApprovalStore, token: string, verdict: ApprovalVerdict, options?: ApproverRelationsOptions & {
+  readonly requireDistinctApprover?: boolean;
+  readonly permdockFor?: ApprovalsHandlerOptions["permdockFor"];
+}): Promise<ApprovalRequest>;
+declare function vouchApproval(store: ApprovalStore, token: string, verdict: {
+  readonly status: "approved" | "rejected";
+  readonly by: Subject;
+  readonly rule: string;
+  readonly note?: string;
+}): Promise<ApprovalRequest>;
+declare function inspectApproval(store: ApprovalStore, token: string, at?: Instant): Promise<ApprovalInspectResult>;
+/** Inspects `token` and, when it is approved, consumes it so it resumes once. */
+declare function consumeApproval(store: ApprovalStore, token: string, at?: Instant): Promise<ApprovalInspectResult>;
+/**
+ * Applies a resume token to a decision. The token only matters when the
+ * decision is `approval-required` and the token is the one this call was
+ * issued; otherwise a new approval is requested. A matching token is consumed
+ * unless `consume` is `false`, so an approval resumes exactly one call. Under
+ * `staleOn: 'resource-change'`, a token issued for an earlier version of the
+ * same row denies with `stale-approval`; the next call without it asks again.
+ */
+declare function resumeDecision(input: {
+  readonly decision: Decision;
+  readonly permission: Permission | {
+    readonly key: string;
+    readonly scope: string;
+    readonly resource: string;
+  };
+  readonly subject: Subject;
+  readonly store: ApprovalStore | undefined;
+  readonly resource: {
+    readonly type: string;
+    readonly id?: string;
+  };
+  readonly adapter: string;
+  readonly token: string | undefined;
+  /** `false` for checks that do not run the action, such as the decision endpoint. */
+  readonly consume?: boolean;
+  readonly now?: Instant;
+  /**
+   * Seconds a request this call opens stays open; absent means the
+   * store's `ttl`, else `DEFAULT_APPROVAL_TTL`. The grant's `approval.ttl`
+   * still caps it.
+   */
+  readonly ttl?: number;
+}): Promise<Decision>;
+declare function cancelApprovals(store: ApprovalStore, filter: ApprovalListFilter, meta: ApprovalCancelMeta): Promise<number>;
+/** The token of a `PermDock-Approval` field: one RFC 9651 sf-token Item with no parameters, else `undefined`. */
+declare function readApprovalHeader(headers: Headers | {
+  readonly get: (name: string) => string | null;
+}): string | undefined;
+declare function resumeFromHeader(store: ApprovalStore, headers: Headers | {
+  readonly get: (name: string) => string | null;
+}, now?: Instant): Promise<ApprovalInspectResult>;
+/**
+ * The token to resume `decision` with when the caller carries none: the
+ * decision's own token when the store holds an approved or rejected request
+ * for it, so `resumeDecision` resumes (or denies) the call without the
+ * caller passing the token back. The token already binds permission,
+ * resource (or the call's data when there is no row id), subject and actor.
+ * A pending request counts only with `denyPending: true`, which makes the
+ * call deny with `approval-pending` instead of asking again. `undefined` when
+ * the decision needs no approval, there is no store, or the store has no
+ * unexpired request for the token; a store that throws counts as none.
+ */
+declare function storedApprovalToken(store: ApprovalStore | undefined, decision: Decision, options?: {
+  readonly denyPending?: boolean;
+  readonly now?: Instant;
+}): Promise<string | undefined>;
+//#endregion
+//#region src/approvals/page.d.ts
+/** The page size of a query: `limit` within 1 to 200, 50 when absent. */
+declare function approvalPageSize(limit: number | undefined): number;
+/** Where a page starts: the `(createdAt, token)` of the last request before it. */
+type ApprovalCursorPosition = readonly [createdAt: string, token: string];
+/** The `next` cursor after `request`, for a store that pages in its own query. */
+declare function encodeApprovalCursor(request: ApprovalRequest): string;
+/** The `(createdAt, token)` position a `next` cursor names, or `null` for one that does not parse. */
+declare function decodeApprovalCursor(cursor: string): ApprovalCursorPosition | null;
+/**
+ * Pages already-filtered requests in `(createdAt, token)` order, as the
+ * built-in stores do: `limit` within 1 to 200 (50 when absent), `cursor` from
+ * the previous page's `next`, and no items for a cursor that does not parse.
+ * A custom `ApprovalStore` that filters in memory returns it from `list`.
+ */
+declare function pageApprovals(matching: readonly ApprovalRequest[], query: ApprovalListQuery): ApprovalPage;
+/** Every matching request of `store`, following `next` until the last page (at most 1000 pages of 200). */
+declare function listAllApprovals(store: ApprovalStore, filter: ApprovalListFilter): Promise<ApprovalRequest[]>;
+//#endregion
+//#region src/approvals/permissions.d.ts
+/**
+ * The `holder(permission)` approvers of `request` that `approver` holds, for
+ * `ApprovalVerdict.permissions`: each permission key the approver's own
+ * instance grants without a row. `approver` must be an instance for the
+ * approving principal in the request's tenant; for any other tenant, or an
+ * anonymous instance, it holds nothing. A check that throws holds nothing.
+ */
+declare function approverPermissions(request: ApprovalRequest, approver: PermDock): readonly string[];
+//#endregion
+//#region src/approvals/store.d.ts
+/**
+ * Refuses `by` as an approver of `request`, or returns the index of the
+ * stage the approval counts for (`undefined` without `stages`). Eligibility
+ * is `approvers.by` or, under `stages`, the first incomplete stage
+ * (`sequential`) or any incomplete stage (`all`); `approvers.escalation.to`
+ * is eligible too once the request has waited `escalation.after`. A
+ * principal who already approved is refused, so one person never completes
+ * two stages. `relations` are the relation approvers `by` holds on the
+ * request's resource (see `ApprovalVerdict.relations`).
+ */
+declare function assertApprover(request: ApprovalRequest, by: Subject, requireDistinctApprover: boolean, at?: Instant, relations?: readonly string[], permissions?: readonly string[]): number | undefined;
+/**
+ * The request after `verdict`, for a store to persist: a rejection resolves
+ * it; an approval is appended to `approvals` and resolves it once there are
+ * `approvers.quorum` (default 1). Throws an `ApprovalError` when the request
+ * is not pending, has expired or `verdict.by` may not approve it. Stores
+ * should write the result only when the stored row is still pending with the
+ * same number of approvals, so two approvers racing both count.
+ */
+declare function applyApprovalVerdict(request: ApprovalRequest, verdict: ApprovalVerdict, at?: Instant): ApprovalRequest;
+type MemoryApprovalStore = ApprovalStore & {
+  readonly ttl: number;
+};
+declare function memoryApprovalStore(options?: {
+  readonly ttl?: number;
+  readonly now?: () => Instant;
+}): MemoryApprovalStore;
+//#endregion
+export { AccessReviewVerdict as $, APPROVAL_REQUEST_SCHEMA as A, matchDelegation as B, ApproverRelationsOptions as C, SignApprovalOptions as D, ApprovalSignatureEntry as E, IdempotencyStore as F, pageAccessReviewItems as G, parseApprovalDelegation as H, IdempotentResponse as I, StartAccessReviewInput as J, AccessReviewHolder as K, memoryIdempotencyStore as L, ApprovalView as M, ApprovalsHandlerOptions as N, approvalSignatureClaims as O, approvalsHandler as P, isAccessReviewError as Q, ApprovalDelegationMatch as R, vouchApproval as S, ApprovalSignatureClaims as T, MemoryAccessReviewStore as U, memoryApprovalDelegationSource as V, memoryAccessReviewStore as W, AccessReviewError as X, startAccessReview as Y, AccessReviewErrorCode as Z, resolveApproval as _, approverPermissions as a, storedApprovalToken as b, decodeApprovalCursor as c, pageApprovals as d, accessReviewerEligible as et, cancelApprovals as f, requestApproval as g, readApprovalHeader as h, memoryApprovalStore as i, parseApprovalRequest as j, signApproval as k, encodeApprovalCursor as l, inspectApproval as m, applyApprovalVerdict as n, AccessReviewsHandlerOptions as nt, ApprovalCursorPosition as o, consumeApproval as p, AccessReviewOptions as q, assertApprover as r, accessReviewsHandler as rt, approvalPageSize as s, MemoryApprovalStore as t, decideAccessReviewItem as tt, listAllApprovals as u, resumeDecision as v, approverRelations as w, summarizeSubject as x, resumeFromHeader as y, MatchDelegationOptions as z };

package/dist/index-CaxrMD1A.d.ts

@@ -0,0 +1 @@
+export {}