permdock 0.17.0 → 0.18.0

package/dist/better-supabase/index.d.ts

@@ -1,15 +1,17 @@
-import { At as ApiKeyPrincipal, E as Policy, Kt as Instant, Tn as ApproverInput, W as CredentialVerifier, Z as Intent, Zn as DeniedDecision, _r as Principal, an as AuthEvent, rt as MembershipSource, wt as SupportSession, yr as Subject } from "../policy-types-IRJVABmm.js";
+import { At as ApiKeyPrincipal, E as Policy, Kt as Instant, Tn as ApproverInput, W as CredentialVerifier, Z as Intent, Zn as DeniedDecision, _r as Principal, an as AuthEvent, rt as MembershipSource, wt as SupportSession, yr as Subject } from "../policy-types-D-GwfQTc.js";
 import { f as PermissionTree, u as Permission } from "../permission-types-CAY-GU7e.js";
-import { i as ApprovalPolicySource } from "../approval-policies-9VagPixq.js";
-import { C as InstanceCache, O as PermissionCheck, _ as PrincipalSource, a as PermDock, h as PrincipalIdentity, k as PermissionState, o as PermDockOptions } from "../permdock-DUWZEOLR.js";
-import { m as ApprovalStore } from "../types-BvBbkAu1.js";
-import { c as AccessReviewStore } from "../types-AOP5HQku.js";
-import { i as SupabaseRpcCaller } from "../postgrest-B_cEDd4e.js";
+import { i as OperationEffect } from "../operations-Ci_rT6Uo.js";
+import { i as ApprovalPolicySource } from "../approval-policies-oNnckT12.js";
+import { A as PermissionState, _ as PrincipalSource, a as PermDock, h as PrincipalIdentity, k as PermissionCheck, o as PermDockOptions, w as InstanceCache } from "../permdock-ffY4CMd9.js";
+import { m as ApprovalStore } from "../types-CqcsNCaN.js";
+import { t as InstanceOptions } from "../instance-options-2sFGSdsf.js";
+import { c as AccessReviewStore } from "../types-CDVXR6YD.js";
+import { i as SupabaseRpcCaller } from "../postgrest-D84p5dbA.js";
 import { a as CatalogDocument } from "../types-NYoj8JBm.js";
-import { A as SupabaseSubjectOptions, C as SupabasePrincipal, N as SupabaseSuspension, O as SupabaseSessionLike, s as SqlMembershipSource } from "../sources-CXY05xtB.js";
-import { n as VersionCache } from "../version-cache-9Vq5QVFC.js";
+import { n as VersionCache } from "../version-cache-DzNKWiI6.js";
+import { A as SupabaseSubjectOptions, C as SupabasePrincipal, N as SupabaseSuspension, O as SupabaseSessionLike, s as SqlMembershipSource } from "../sources-xdQShLDU.js";
 import { t as SqlQuery } from "../sql-B80DFdpG.js";
-import { c as LinkPolicy, o as CapabilityPrincipal, t as Capability } from "../capability-BzjWdKmP.js";
+import { c as LinkPolicy, o as CapabilityPrincipal, t as Capability } from "../capability-BZ_veK9o.js";
 import { AccessBucketPolicy, AccessTopicPolicy, AuthorizationHooks, AuthorizationProvider, AuthorizationRequest, Authorizer, BlockTables, CredentialProvider, SupportAuthorize, SupportAuthorizeInput, ToolDecision, ToolRef } from "better-supabase/contract";
 import { EntitlementClaimOptions } from "better-supabase/blocks/entitlements";
 import { AuthSession } from "better-supabase/server";
@@ -112,16 +114,21 @@ type BlockApprovalApprovers = {
   readonly users?: readonly string[];
   readonly manager?: boolean;
 };
-/** The approvals block's tenant policy (`options.tenantPolicies`). */
+/**
+ * The approvals block's tenant or platform policy (`options.tenantPolicies`,
+ * `options.platformPolicies`). `organizationId` is `null` on a platform policy;
+ * `subjectType` and `action` may be `*`.
+ */
 type BlockApprovalTenantPolicy = {
-  readonly organizationId: string;
+  readonly organizationId: string | null;
   readonly subjectType: string;
   readonly action: string;
+  readonly effect?: string;
   readonly conditions?: unknown;
   readonly mode: "confirm" | "authorize";
   readonly steps: readonly {
     readonly approvers: BlockApprovalApprovers;
-    readonly required: number;
+    readonly required: number | "all";
   }[];
   readonly selfApproval: boolean;
   readonly expiresIn?: string;
@@ -140,48 +147,72 @@ type BlockApprovalsClient<I extends BlockInstant> = {
     readonly reason?: string;
     readonly payload?: Readonly<Record<string, unknown>>;
     readonly fingerprint?: string;
+    readonly tenantless?: boolean;
   }) => BlockResult<BlockApprovalRecord<I>>;
   readonly list: (options?: {
     readonly status?: BlockStatus | null;
     readonly pageSize?: number;
     readonly before?: I;
+    readonly tenantless?: boolean;
   }) => BlockResult<readonly BlockApprovalRecord<I>[]>;
   readonly consume: (id: string, fingerprint?: string) => BlockResult<BlockApprovalRecord<I>>;
+  readonly approve?: BlockDecide<I>;
+  readonly reject?: BlockDecide<I>;
 };
+type BlockDecide<I extends BlockInstant> = (id: string, comment?: string, options?: {
+  readonly decidedBy?: string;
+}) => BlockResult<BlockApprovalRecord<I>>;
 /** The call `blockApprovalPolicySource` makes on the approvals block. */
 type BlockApprovalPoliciesClient = {
   readonly listPolicies: (options?: {
     readonly subjectType?: string;
     readonly pageSize?: number;
+    readonly platform?: boolean;
   }) => BlockResult<readonly BlockApprovalTenantPolicy[]>;
 };
+type BlockApprovalStoreOptions = {
+  readonly tenantless?: boolean;
+};
 /**
  * An `ApprovalStore` over better-supabase's approvals block, so a PermDock
  * `approval-required` decision files a block request and is decided in the
  * block's own approve and reject flow. `create` files the request on the
  * resource under the permission's action, with the PermDock request in
  * `payload.permdock` and its `fingerprint`. `get`, `getById` and `list` read
- * the block's latest 2,000 requests in the block's tenant. `consume` calls the
- * block's `consume`, which refuses a second use and another fingerprint.
- * `resolve` throws: approvers decide through the block, never through
- * `approvalsHandler`. `expire` answers 0, since the block expires requests
+ * the block's latest 2,000 requests in the block's tenant, and with
+ * `tenantless` the latest 2,000 without one. `consume` calls the block's
+ * `consume`, which refuses a second use and another fingerprint. `resolve`
+ * checks the verdict against the PermDock request, then calls the block's
+ * `approve` or `reject` with `decidedBy` set to the approver, so a service-role
+ * client records the user who decided; without `approve` and `reject` on the
+ * client it throws. `expire` answers 0, since the block expires requests
  * itself.
  */
-export declare function blockApprovalStore<I extends BlockInstant>(approvals: BlockApprovalsClient<I>): ApprovalStore;
+export declare function blockApprovalStore<I extends BlockInstant>(approvals: BlockApprovalsClient<I>, options?: BlockApprovalStoreOptions): ApprovalStore;
 type BlockApprovalPolicySourceOptions = {
   /** The scope a step's `role` is held in. Default `tenant`. */
   readonly roleScope?: string;
+  readonly platform?: boolean;
+  readonly permissions?: PermissionTree;
+  readonly effects?: Readonly<Record<string, readonly OperationEffect[]>>;
 };
 /**
- * An `ApprovalPolicySource` over the approvals block's tenant policies, so a
- * PermDock decision asks for approval wherever the block would. A policy keys
- * the permission `<subjectType>.<action>`; its steps become sequential stages
- * whose approvers are any of the step's permission, role, users and manager;
- * `confirm` with `selfApproval` lets the principal approve; `expiresIn` caps
- * the request's `ttl`. `conditions` are not read, so a conditional policy
- * applies to every call: stricter, never looser. A step with only a `team`
- * approver, an interval it cannot read or a failed read makes the source fail,
- * and every call an allow would grant denies.
+ * An `ApprovalPolicySource` over the approvals block's tenant policies, and
+ * with `platform` its platform policies, so a PermDock decision asks for
+ * approval wherever the block would. A policy keys the permission
+ * `<subjectType>.<action>`; a platform policy has no tenant. Its steps become
+ * sequential stages whose approvers are any of the step's permission, role,
+ * users and manager; `required: "all"` over users needs each of them. `confirm`
+ * with `selfApproval` lets the principal approve; `expiresIn` caps the
+ * request's `ttl`. `conditions` become a `check` over the call's input, or the
+ * row without one; a tree PermDock cannot express is dropped, so the policy
+ * applies to every call: stricter, never looser. A `*` subject type or action
+ * with an effect PermDock knows matches every operation with that effect, and
+ * without one expands over `permissions`. A concrete policy's `effect` is
+ * ignored, so it applies to every call of its permission. A step with only a
+ * `team` approver, `required: "all"` over anything but users, an interval it
+ * cannot read or a failed read makes the source fail, and every call an allow
+ * would grant denies.
  */
 export declare function blockApprovalPolicySource(approvals: BlockApprovalPoliciesClient, options?: BlockApprovalPolicySourceOptions): ApprovalPolicySource;
 //#endregion
@@ -266,9 +297,9 @@ type ApiKeySessionOptions = {
 };
 /**
  * The fields of better-supabase's `SessionSnapshot` a subject reads: one
- * verified token, from `bsb.getClaims()`, that `'use cache: private'` scopes
- * share. Its `issuedAt` and `authzVersion` come from the `iat` and `authz_ver`
- * claims.
+ * verified token, from `bsb.getClaims()` in Next.js, where `'use cache:
+ * private'` scopes share it, or from `server.snapshot(request)` elsewhere. Its
+ * `issuedAt` and `authzVersion` come from the `iat` and `authz_ver` claims.
  */
 type SessionSnapshotLike = {
   readonly accessToken: string;
@@ -307,6 +338,81 @@ type BetterSupabaseSubjectOptions = Omit<SupabaseSubjectOptions, "claims"> & {
  */
 export declare function subjectFromBetterSupabase(session: SupabaseSessionLike | ApiKeySession | SessionSnapshotLike | null | undefined, options?: BetterSupabaseSubjectOptions): Subject<SupabasePrincipal> | Subject<ApiKeyPrincipal> | Subject;
 //#endregion
+//#region src/better-supabase/permdock-for.d.ts
+/**
+ * What `bsb.bootstrap()` and `bsb.getAccess()` return: a session with the
+ * tenant and the authorization version read in the same request.
+ */
+type PermDockForResult = {
+  readonly session: SupabaseSessionLike | ApiKeySession | null;
+  readonly tenant: string | null;
+  readonly authzVersion: number | null;
+  /** `bsb.bootstrap()`'s `session_active()`; `false` is signed out. */
+  readonly sessionActive?: boolean;
+};
+/** Who an instance is for. */
+type PermDockForInput = SupabaseSessionLike | ApiKeySession | SessionSnapshotLike | PermDockForResult | Subject | null | undefined;
+type PermDockForQuery = {
+  /** Default the source's tenant (`bootstrap`, `getAccess`). */
+  readonly tenant?: string | null;
+  /** Default `read`. */
+  readonly intent?: Intent;
+};
+/**
+ * The instance for a session, a `bsb.bootstrap()` result, a `bsb.getAccess()`
+ * result or a subject. The second argument is a query or a tenant, so it also
+ * serves as an approvals handler's or access-review handler's `permdockFor`.
+ * The third is the version cache better-supabase passes at runtime, which
+ * replaces the `versions` option.
+ */
+type PermDockFor = {
+  (source: PermDockForInput, query?: PermDockForQuery | string | null, versions?: VersionCache): Promise<PermDock>;
+  /**
+   * The instance options every instance of `versions` (default the `versions`
+   * option) is built with: the same object on every call, so an adapter that
+   * spreads it into its own options, such as oRPC's or MCP's `createPermDock`,
+   * shares the `claimsFirst` memberships and the `instances` entries.
+   */
+  readonly sources: (versions?: VersionCache) => InstanceOptions;
+};
+type PermDockForOptions = {
+  readonly policy: Policy;
+  /** How the verified claims map to a subject. */
+  readonly subject?: BetterSupabaseSubjectOptions;
+  /**
+   * The membership source a stale token is re-read from, wrapped in
+   * `claimsFirst(source, { onStale: 'reread', versions })`.
+   */
+  readonly memberships?: MembershipSource | readonly MembershipSource[];
+  /** The version `claimsFirst` compares with `authz_ver`; default the source's. */
+  readonly version?: MembershipSource["version"];
+  /** The process-wide version cache (`createNext({ versions })`). */
+  readonly versions?: VersionCache;
+  /** The process-wide instance cache, shared with the app's other adapters. */
+  readonly instances?: InstanceCache;
+  /** Sources and sinks for each instance. */
+  readonly options?: Omit<PermDockOptions, "tenant" | "intent" | "version">;
+};
+/**
+ * One resolver for every instance of the app: `permdockFor(await
+ * bsb.claims())`, `permdockFor(await bsb.bootstrap(...))` or `permdockFor(await
+ * bsb.getAccess(...))`. A bootstrap or access result passes its `authzVersion`
+ * as `version.known`, so the instance reads no version, and a `sessionActive:
+ * false` bootstrap is anonymous. With `instances`, a subject at an unchanged
+ * version reuses its instance across requests. Pass the same resolver to
+ * `authorizer({ permdockFor })`, `authorizationHooks({ permdockFor })` and,
+ * through `permdockFor.sources()`, to every other adapter's options, so they
+ * share one instance per subject and version.
+ */
+export declare function permdockFor(options: PermDockForOptions): PermDockFor;
+/**
+ * One `{ allowed, outcome, reason? }` per named check for `input`, from one
+ * `permdockFor` instance: frozen plain JSON an island returns from `'use cache:
+ * private'`. A check that throws denies its entry; an instance that cannot be
+ * built denies them all.
+ */
+export declare function getPermissions<K extends string>(resolve: (source: PermDockForInput, query?: PermDockForQuery | string | null) => Promise<PermDock>, input: PermDockForInput, checks: Readonly<Record<K, PermissionCheck>>, query?: PermDockForQuery | string | null): Promise<Readonly<Record<K, PermissionState>>>;
+//#endregion
 //#region src/better-supabase/subscribers.d.ts
 /** The fields of better-supabase's `OutboxEvent` the policy reads. */
 type SubscriberPolicyEvent = {
@@ -417,6 +523,13 @@ type Maybe$1<T> = T | null | undefined | Promise<T | null | undefined>;
 type Claims = Readonly<Record<string, unknown>>;
 type AuthorizationHooksOptions = {
   readonly policy: Policy;
+  /**
+   * The app's `permdockFor` resolver, shared with `authorizer({ permdockFor })`
+   * so a hook reuses the instances the checks built. It holds `subject`,
+   * `memberships`, `version`, `versions`, `instances` and `options`; passing
+   * one of those as well throws a `TypeError`.
+   */
+  readonly permdockFor?: PermDockFor;
   /**
    * The claims better-supabase mints for `userId` now, or `null` for a user
    * deleted, suspended or unknown: the same loader `principalSource` takes.
@@ -526,6 +639,7 @@ type AuthorizationProviderOptions = {
    * `permdock_is_approver` from `rls.approvals`.
    */
   readonly approvers?: ProviderApprovers;
+  readonly requestApprovers?: boolean;
   /**
    * better-supabase's `blocks.permissions.activeTenant`. When the token hook
    * reads the active tenant from another place than better-supabase writes it,
@@ -581,6 +695,15 @@ type BetterSupabaseOnError = (error: unknown, context: BetterSupabaseErrorContex
 type AuthorizerOperation = "list" | "get" | "create" | "update" | "delete";
 type AuthorizerOptions = {
   readonly policy: Policy;
+  /**
+   * The app's `permdockFor` resolver: `bsb.action`, `protectAction` and every
+   * adapter that spreads `permdockFor.sources()` then share one instance per
+   * subject and version. Each check calls it with better-supabase's runtime
+   * `versions`. It holds `subject`, `memberships`, `version`, `versions`,
+   * `instances` and `options`; passing one of those as well throws a
+   * `TypeError`.
+   */
+  readonly permdockFor?: PermDockFor;
   /**
    * How the verified claims map to a subject; the defaults of
    * `subjectFromBetterSupabase`.
@@ -883,67 +1006,6 @@ type PrincipalFromMembershipsOptions = {
  */
 export declare function principalFromMemberships(userId: string, rows: readonly BetterSupabaseMembershipRow[], options?: PrincipalFromMembershipsOptions): Principal;
 //#endregion
-//#region src/better-supabase/permdock-for.d.ts
-/**
- * What `bsb.bootstrap()` and `bsb.getAccess()` return: a session with the
- * tenant and the authorization version read in the same request.
- */
-type PermDockForResult = {
-  readonly session: SupabaseSessionLike | ApiKeySession | null;
-  readonly tenant: string | null;
-  readonly authzVersion: number | null;
-  /** `bsb.bootstrap()`'s `session_active()`; `false` is signed out. */
-  readonly sessionActive?: boolean;
-};
-/** Who an instance is for. */
-type PermDockForInput = SupabaseSessionLike | ApiKeySession | SessionSnapshotLike | PermDockForResult | Subject | null | undefined;
-type PermDockForQuery = {
-  /** Default the source's tenant (`bootstrap`, `getAccess`). */
-  readonly tenant?: string | null;
-  /** Default `read`. */
-  readonly intent?: Intent;
-};
-/**
- * The instance for a session, a `bsb.bootstrap()` result, a `bsb.getAccess()`
- * result or a subject. The second argument is a query or a tenant, so it also
- * serves as an approvals handler's or access-review handler's `permdockFor`.
- */
-type PermDockFor = (source: PermDockForInput, query?: PermDockForQuery | string | null) => Promise<PermDock>;
-type PermDockForOptions = {
-  readonly policy: Policy;
-  /** How the verified claims map to a subject. */
-  readonly subject?: BetterSupabaseSubjectOptions;
-  /**
-   * The membership source a stale token is re-read from, wrapped in
-   * `claimsFirst(source, { onStale: 'reread', versions })`.
-   */
-  readonly memberships?: MembershipSource | readonly MembershipSource[];
-  /** The version `claimsFirst` compares with `authz_ver`; default the source's. */
-  readonly version?: MembershipSource["version"];
-  /** The process-wide version cache (`createNext({ versions })`). */
-  readonly versions?: VersionCache;
-  /** The process-wide instance cache, shared with the app's other adapters. */
-  readonly instances?: InstanceCache;
-  /** Sources and sinks for each instance. */
-  readonly options?: Omit<PermDockOptions, "tenant" | "intent" | "version">;
-};
-/**
- * One resolver for every instance of the app: `permdockFor(await
- * bsb.claims())`, `permdockFor(await bsb.bootstrap(...))` or `permdockFor(await
- * bsb.getAccess(...))`. A bootstrap or access result passes its `authzVersion`
- * as `version.known`, so the instance reads no version, and a `sessionActive:
- * false` bootstrap is anonymous. With `instances`, a subject at an unchanged
- * version reuses its instance across requests.
- */
-export declare function permdockFor(options: PermDockForOptions): PermDockFor;
-/**
- * One `{ allowed, outcome, reason? }` per named check for `input`, from one
- * `permdockFor` instance: frozen plain JSON an island returns from `'use cache:
- * private'`. A check that throws denies its entry; an instance that cannot be
- * built denies them all.
- */
-export declare function getPermissions<K extends string>(resolve: PermDockFor, input: PermDockForInput, checks: Readonly<Record<K, PermissionCheck>>, query?: PermDockForQuery | string | null): Promise<Readonly<Record<K, PermissionState>>>;
-//#endregion
 //#region src/better-supabase/principals.d.ts
 /**
  * Where an identity link points: an app user, whose claims `principal` loads,
@@ -1150,4 +1212,4 @@ type WorkflowResourceResult = {
  */
 export declare function workflowResource(subject: unknown, types: WorkflowSubjectTypes): WorkflowResourceResult;
 //#endregion
-export type { AccessPolicyOptions, AccessReviewApplierOptions, AccessReviewApplyFailure, AccessReviewApplyResult, ApiKeySession, ApiKeySessionOptions, ApiKeyVerifierOptions, AuthorizationHooksOptions, AuthorizationProviderOptions, AuthorizerOperation, AuthorizerOptions, BetterSupabaseActiveTenant, BetterSupabaseErrorContext, BetterSupabaseIdentityLink, BetterSupabaseMembershipRow, BetterSupabaseOnError, BetterSupabaseSubjectOptions, BlockApprovalApprovers, BlockApprovalPoliciesClient, BlockApprovalPolicySourceOptions, BlockApprovalRecord, BlockApprovalTenantPolicy, BlockApprovalsClient, BlockInstant, BlockMembershipSourceOptions, BlockRoleJunction, BlockRoleThrough, BucketAccess, CredentialGuardOptions, HandlerCanOptions, HandlerPermDockSource, HookCanOptions, McpToolDecision, McpToolRef, PendingSupportSession, PermDockFor, PermDockForInput, PermDockForOptions, PermDockForQuery, PermDockForResult, PrincipalFromMembershipsOptions, PrincipalSourceOptions, ProviderApprovers, RoleOrderOptions, ServiceRoles, SessionSnapshotLike, ShareLinkResolver, ShareLinkRow, ShareLinkSubjectOptions, ShareLinkTarget, SubscriberPolicyEvent, SubscriberPolicyOptions, SupabasePrincipal, SupportPolicyOptions, ToolPolicy, ToolPolicyOptions, TopicAccess, WorkflowRecordRef, WorkflowResourceResult, WorkflowSubjectTypes };
+export type { AccessPolicyOptions, AccessReviewApplierOptions, AccessReviewApplyFailure, AccessReviewApplyResult, ApiKeySession, ApiKeySessionOptions, ApiKeyVerifierOptions, AuthorizationHooksOptions, AuthorizationProviderOptions, AuthorizerOperation, AuthorizerOptions, BetterSupabaseActiveTenant, BetterSupabaseErrorContext, BetterSupabaseIdentityLink, BetterSupabaseMembershipRow, BetterSupabaseOnError, BetterSupabaseSubjectOptions, BlockApprovalApprovers, BlockApprovalPoliciesClient, BlockApprovalPolicySourceOptions, BlockApprovalRecord, BlockApprovalStoreOptions, BlockApprovalTenantPolicy, BlockApprovalsClient, BlockDecide, BlockInstant, BlockMembershipSourceOptions, BlockRoleJunction, BlockRoleThrough, BucketAccess, CredentialGuardOptions, HandlerCanOptions, HandlerPermDockSource, HookCanOptions, McpToolDecision, McpToolRef, PendingSupportSession, PermDockFor, PermDockForInput, PermDockForOptions, PermDockForQuery, PermDockForResult, PrincipalFromMembershipsOptions, PrincipalSourceOptions, ProviderApprovers, RoleOrderOptions, ServiceRoles, SessionSnapshotLike, ShareLinkResolver, ShareLinkRow, ShareLinkSubjectOptions, ShareLinkTarget, SubscriberPolicyEvent, SubscriberPolicyOptions, SupabasePrincipal, SupportPolicyOptions, ToolPolicy, ToolPolicyOptions, TopicAccess, WorkflowRecordRef, WorkflowResourceResult, WorkflowSubjectTypes };