permdock 0.4.0 → 0.6.0

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

@@ -1,45 +1,119 @@
-import { E as Policy, H as CredentialVerifier, Mt as PermDockOptions, jt as PermDock, kr as Subject, xt as CredentialPrincipal } from "../policy-types-sp9P1iIV.js";
-import { d as Permission, p as PermissionTree } from "../permission-types-Dg39z9Kv.js";
-import { g as SupabaseSubjectOptions, m as SupabaseSessionLike, u as SupabasePrincipal } from "../types-CqrjB9o6.js";
+import { Rt as Instant, St as ApiKeyPrincipal, T as Policy, U as CredentialVerifier, ar as Subject, gt as SupportSession, pn as ApproverInput, qt as AuthEvent, rr as Principal } from "../policy-types-n0uRTsW8.js";
+import { E as PermissionTree, w as Permission } from "../vocabulary-CN8H_9UF.js";
+import { d as PrincipalIdentity, i as PermDockOptions, p as PrincipalSource, r as PermDock } from "../permdock-SV8ZINYT.js";
+import { c as AccessReviewStore } from "../types-C_IiEs64.js";
+import { i as SupabaseRpcCaller } from "../postgrest-CEgRbefE.js";
+import { g as SupabaseSubjectOptions, m as SupabaseSessionLike, u as SupabasePrincipal } from "../types-BzzaHxt3.js";
+import { c as LinkPolicy, o as CapabilityPrincipal, t as Capability } from "../capability-Drg-1YhL.js";
 import { AuthorizationProvider } from "better-supabase/config";
-import { AuthSession, Authorizer } from "better-supabase/server";
+import { AuthSession, AuthorizationHooks, Authorizer, SupportAuthorize, SupportAuthorizeInput } from "better-supabase/server";
 import { EntitlementClaimOptions } from "better-supabase/blocks/entitlements";
 import { ApiKey, ApiKeyClaimsOptions, ApiKeys } from "better-supabase/blocks/api-keys";
 import { AccessTopicPolicy } from "better-supabase/realtime";
 import { AccessBucketPolicy } from "better-supabase/storage";
 import { CredentialProvider } from "better-supabase/credentials";
 import { ToolDecision, ToolRef } from "better-supabase/mcp";
-//#region src/better-supabase/provider.d.ts
-type AuthorizationProviderOptions = {
-  /** `permdock.manifest.json`, parsed or as JSON text, from `permdock supabase inspect --out`. */
-  readonly manifest: unknown;
+import { AuthorizeHookOptions, ProtectWebHandlerOptions } from "better-supabase/workflow-sdk";
+//#region src/better-supabase/access-reviews.d.ts
+type AccessReviewApplierOptions = {
   /**
-   * `permissions.catalog.json` from `permdock catalog`. Without it the
-   * provider lists no permissions, so better-supabase refuses every key in
-   * a bucket, topic or module check.
+   * A supabase-js client that may call the organizations and invitations
+   * block functions. Pass the reviewer's client so the block's own
+   * permission and role-ceiling checks run as the reviewer.
    */
-  readonly catalog?: unknown;
-  /** The scope tenants are; defaults to the manifest's one root scope. */
+  readonly client: SupabaseRpcCaller;
+  readonly reviews: AccessReviewStore;
+  /** Decides whether a fallback role or an invitation's role grants the reviewed permission. */
+  readonly policy: Policy;
+  /**
+   * The role a revoked member moves to with `update_member_role`: one role,
+   * or a map from the roles in the item's `via` to their fallback. A
+   * fallback that still grants the permission, or none, removes the member
+   * with `remove_member` instead.
+   */
+  readonly demoteTo?: string | Readonly<Record<string, string>>;
+  /**
+   * The member's email, for revoking the tenant's open invitations to it
+   * whose role grants the permission. Without it invitations are left alone.
+   */
+  readonly email?: (userId: string) => string | null | undefined | Promise<string | null | undefined>;
+  /**
+   * An instance for the member in the review's tenant, read after the
+   * change. An item it still grants is not marked applied.
+   */
+  readonly permdockFor?: (principalId: string, tenant: string) => PermDock | Promise<PermDock>;
+  /** The schema of the block functions; better-supabase's default is `better_supabase`. */
+  readonly schema?: string;
+  /** The scope review tenants are; defaults to the policy's first scope. */
   readonly scope?: string;
+  readonly now?: Instant;
+};
+type AccessReviewApplyFailure = {
+  readonly item: string;
+  readonly cause: string;
+};
+type AccessReviewApplyResult = {
+  /** Items marked applied, including those whose member was already gone. */
+  readonly applied: readonly string[];
+  /** Items left unapplied, with the error the block function or the re-check gave. */
+  readonly failed: readonly AccessReviewApplyFailure[];
+};
+/**
+ * Applies the revoked items of an access review to better-supabase's
+ * organizations and invitations blocks, then marks each one applied. A
+ * revoked member moves to the `demoteTo` role when the policy says that
+ * role lacks the permission, and is removed otherwise. With `email`, the
+ * tenant's open invitations to the member whose role grants the permission
+ * are revoked too. A member who is no longer in the organization counts as
+ * applied. Any other error leaves the item unapplied in `failed`, and one
+ * item's failure never stops the others. Throws `review-not-found` for an
+ * unknown review.
+ */
+export declare function accessReviewApplier(options: AccessReviewApplierOptions): (reviewId: string) => Promise<AccessReviewApplyResult>;
+//#endregion
+//#region src/better-supabase/approvers.d.ts
+/**
+ * Who may approve each better-supabase request kind: `'ai-tool'` (a tool
+ * call), `'support-session'`, or `'<subject type>.<action>'` from the
+ * approvals block.
+ */
+type ProviderApprovers = Readonly<Record<string, ApproverInput>>;
+//#endregion
+//#region src/better-supabase/subscribers.d.ts
+/** The fields of better-supabase's `OutboxEvent` the policy reads. */
+type SubscriberPolicyEvent = {
+  readonly type: string;
+  readonly tenant: string | null;
+  readonly actorId: string | null;
+  readonly payload: unknown;
+};
+type SubscriberPolicyOptions<E extends SubscriberPolicyEvent = SubscriberPolicyEvent> = {
+  readonly policy: Policy;
+  /** Loads the sender and every subscriber's principal. */
+  readonly principals: PrincipalSource;
   /**
-   * The permission that lets a user decide a tool call waiting for approval
-   * in a tenant, for better-supabase's `canApprove`. The approver is never
-   * the user who asked (`approvals.distinctApprover`). Without it the chat's
-   * owner decides.
+   * The permission a subscriber needs for each event type: an exact type,
+   * `prefix.*` or `*`, with the exact type first and then the longest
+   * pattern. A type with no entry reaches no one.
    */
-  readonly approver?: Permission;
+  readonly events: Readonly<Record<string, Permission>>;
+  /** The row the permission is decided on. Defaults to `event.payload`, validated against the resource schema. */
+  readonly row?: (event: E) => unknown;
+  /** The principal the fan-out runs as in the event's tenant. Defaults to `event.actorId`. */
+  readonly sender?: (event: E) => string | null | undefined;
+  /** Sources for the sender's and subscribers' instances. */
+  readonly options?: Omit<PermDockOptions, "tenant" | "actor" | "delegation" | "session" | "expiresAt" | "principals">;
 };
 /**
- * better-supabase's `authorization` config value, built from PermDock's
- * manifest and catalog: the scopes, the `rls generate` helpers as SQL
- * templates, the membership tables, suspension rows, the token hook and
- * every catalog key with `sqlComplete` set from its `rowConditions`. A
- * `_for` template and `permissionsFor` are set only when the manifest lists
- * their helper, which `rls.mode: 'database'` writes; `canApprove` only with
- * `approver`. Throws when the manifest or catalog is invalid, or when the
- * tenant scope is ambiguous.
+ * The per-subscriber check for better-supabase's webhooks-out, outbox and
+ * realtime fan-out: the subscribers whose `principal` `decideFor` grants
+ * the event type's permission on its row, in the event's tenant, as the
+ * sender. An unmapped type, an event without a tenant or sender, a sender
+ * outside the tenant and a throw reach no one.
  */
-export declare function authorizationProvider(options: AuthorizationProviderOptions): AuthorizationProvider;
+export declare function subscriberPolicy<E extends SubscriberPolicyEvent = SubscriberPolicyEvent>(options: SubscriberPolicyOptions<E>): <S extends {
+  readonly principal: string;
+}>(event: E, subscribers: readonly S[]) => Promise<S[]>;
 //#endregion
 //#region src/better-supabase/api-keys.d.ts
 /** The roles a tenant key holds in its tenant: a list, or one per key. */
@@ -99,7 +173,9 @@ type ApiKeySessionOptions = {
 };
 /** The claim, and the short code better-supabase writes for each feature key. */
 type FeatureClaim = EntitlementClaimOptions;
-type BetterSupabaseSubjectOptions = Omit<SupabaseSubjectOptions, "plans"> & {
+type BetterSupabaseSubjectOptions = Omit<SupabaseSubjectOptions, "claims"> & {
+  /** Where the token carries roles, the active tenant and memberships; plans come from `plans`. */
+  readonly claims?: Omit<NonNullable<SupabaseSubjectOptions["claims"]>, "plans">;
   /** How `kind: 'apiKey'` sessions map. Without it they are anonymous. */
   readonly apiKeys?: ApiKeySessionOptions;
   /**
@@ -119,7 +195,146 @@ type BetterSupabaseSubjectOptions = Omit<SupabaseSubjectOptions, "plans"> & {
  * principal holding `serviceRoles`. Without `apiKeys`, and for `anon`,
  * `service` and `invalid` sessions, the subject is anonymous.
  */
-export declare function subjectFromBetterSupabase(session: SupabaseSessionLike | ApiKeySession | null | undefined, options?: BetterSupabaseSubjectOptions): Subject<SupabasePrincipal> | Subject<CredentialPrincipal> | Subject;
+export declare function subjectFromBetterSupabase(session: SupabaseSessionLike | ApiKeySession | null | undefined, options?: BetterSupabaseSubjectOptions): Subject<SupabasePrincipal> | Subject<ApiKeyPrincipal> | Subject;
+//#endregion
+//#region src/better-supabase/support.d.ts
+/** A start `decideSupportSession` holds for approval: the session it would start and the token an approval binds to. */
+type PendingSupportSession = {
+  readonly token: string;
+  readonly session: SupportSession;
+};
+type SupportPolicyOptions = {
+  readonly policy: Policy;
+  /** How the admin's verified claims map to a subject; the defaults of `subjectFromBetterSupabase`. */
+  readonly subject?: Omit<BetterSupabaseSubjectOptions, "apiKeys">;
+  /** Sources and sinks for the admin's instance; `settings` also supplies the tenant's `supportSessions` rules. */
+  readonly options?: Omit<PermDockOptions, "tenant" | "actor" | "delegation" | "session" | "expiresAt">;
+  /**
+   * The session's permissions when a start asks for `readOnly: false`.
+   * Without it such a start is refused; a read-only start gets every
+   * `readOnlyHint` permission the admin can use.
+   */
+  readonly writable?: readonly Permission[];
+  /** Approval by someone other than the admin is required unless this is `false`. */
+  readonly approval?: boolean;
+  /**
+   * The approval the application recorded for `pending.token`, or
+   * `undefined` while none exists. `approvedBy` is the approver's principal
+   * id and never the admin's.
+   */
+  readonly approved?: (input: SupportAuthorizeInput, pending: PendingSupportSession) => {
+    readonly approvedBy: string;
+  } | undefined | Promise<{
+    readonly approvedBy: string;
+  } | undefined>;
+};
+/**
+ * The `authorize` option of better-supabase's `supportSessions`: the admin's
+ * verified claims become a PermDock subject, and the start is decided with
+ * `permdock.decideSupportSession` in the requested tenant. `true` only for
+ * `granted`: an `approval-required` start passes once `approved` returns a
+ * distinct approver for its token. `readOnly: false` needs `writable`. A
+ * throw is `false`.
+ */
+export declare function supportPolicy(options: SupportPolicyOptions): SupportAuthorize;
+//#endregion
+//#region src/better-supabase/hooks.d.ts
+type Maybe$1<T> = T | null | undefined | Promise<T | null | undefined>;
+type Claims = Readonly<Record<string, unknown>>;
+type AuthorizationHooksOptions = {
+  readonly policy: Policy;
+  /**
+   * The claims better-supabase mints for `userId` now, or `null` for a user
+   * deleted, suspended or unknown: the same loader `principalSource` takes.
+   */
+  readonly claims: (userId: string, options: {
+    readonly tenant?: string;
+  }) => Maybe$1<Claims>;
+  /** How the claims map to a subject; the defaults of `subjectFromBetterSupabase`. */
+  readonly subject?: Omit<BetterSupabaseSubjectOptions, "apiKeys">;
+  /** Sources for every instance the hooks build. */
+  readonly options?: Omit<PermDockOptions, "tenant" | "actor" | "delegation" | "session" | "expiresAt">;
+  /**
+   * The claims an organization-owned automation runs as in `tenant`, such
+   * as its default service principal's. Without it such an automation runs
+   * as no one.
+   */
+  readonly service?: (tenant: string | null) => Maybe$1<Claims>;
+  /** The `principalSource` for `identities` and `delivery`; without it neither hook is set. */
+  readonly principals?: PrincipalSource;
+  /** The permission each event type needs, for `delivery` (`subscriberPolicy`'s `events`). */
+  readonly events?: Readonly<Record<string, Permission>>;
+  /** The row a delivery check decides on; defaults to `event.payload`. */
+  readonly row?: (event: SubscriberPolicyEvent) => unknown;
+  /** Who may approve each request kind, as for `authorizationProvider`; sets `approverOf`. */
+  readonly approvers?: ProviderApprovers;
+  /** `supportPolicy`'s options without `policy`; sets `support.authorize`. */
+  readonly support?: Omit<SupportPolicyOptions, "policy">;
+  /**
+   * The user and tenant a run ticket stands for, looked up in the app's
+   * store; `null` refuses the ticket. Sets `tickets.subject`, which loads
+   * the user's current claims, so a suspended user's ticket runs as no one.
+   */
+  readonly tickets?: (ticket: string) => Maybe$1<{
+    readonly userId: string;
+    readonly tenant?: string;
+  }>;
+};
+/**
+ * better-supabase's `AuthorizationHooks` (`createServer(betterSupabase,
+ * { authorization })`), decided by `policy`. Every hook builds the
+ * principal's instance from the claims `claims` loads now, never from the
+ * request, and fails closed: a throw, an unknown key and `approval-required`
+ * refuse. `automation` and `delegation` are always set; `identities`,
+ * `delivery`, `approverOf`, `support` and `tickets` only with the options
+ * they read. `delegation.permissions` maps each scope to the keys whose
+ * `.scope` it is, was renamed from, or that a policy `oauthScopes` entry
+ * covers, and reads no `authorization_details`.
+ */
+export declare function authorizationHooks(options: AuthorizationHooksOptions): AuthorizationHooks;
+//#endregion
+//#region src/better-supabase/provider.d.ts
+type AuthorizationProviderOptions = {
+  /** `permdock.manifest.json`, parsed or as JSON text, from `permdock supabase inspect --out`. */
+  readonly manifest: unknown;
+  /**
+   * `permissions.catalog.json` from `permdock catalog`. Without it the
+   * provider lists no permissions, so better-supabase refuses every key in
+   * a bucket, topic or module check.
+   */
+  readonly catalog?: unknown;
+  /** The scope tenants are; defaults to the manifest's one root scope. */
+  readonly scope?: string;
+  /**
+   * The permission that lets a user decide a tool call waiting for
+   * approval: the `'ai-tool'` entry of `approvers` (`holder(approver)`)
+   * unless `approvers` names one. The requester is never their own approver.
+   */
+  readonly approver?: Permission;
+  /**
+   * Who may approve each request kind, for better-supabase's `isApprover`:
+   * `'ai-tool'`, `'support-session'` or the approvals block's
+   * `'<subject type>.<action>'`, each mapped to `user()`, `holder()` or
+   * `anyOf()` approvers. A kind it does not name has no provider approver,
+   * which for tool calls and support sessions means nobody but the service
+   * role. Needs `permdock_is_approver` from `rls.approvals`.
+   */
+  readonly approvers?: ProviderApprovers;
+};
+/**
+ * better-supabase's `authorization` config value, built from PermDock's
+ * manifest and catalog: the scopes, the `rls generate` helpers as SQL
+ * templates, the membership tables, suspension rows, the token hook and
+ * every catalog key with `sqlComplete` set from its `rowConditions`. A
+ * `_for` template and `permissionsFor` are set only when the manifest lists
+ * their helper, which `rls.mode: 'database'` writes; `isApprover` only with
+ * `approvers` and `permdock_is_approver`, and otherwise `canApprove` only
+ * with `approver`. `holdersOf` (`permitted_<tenant scope>_users`) and
+ * `actorMayWrite` (`permdock_actor_may_write()`) are set when the manifest
+ * lists their helper. Throws when the manifest or catalog is invalid, or when the
+ * tenant scope is ambiguous.
+ */
+export declare function authorizationProvider(options: AuthorizationProviderOptions): AuthorizationProvider;
 //#endregion
 //#region src/better-supabase/authorizer.d.ts
 /** The table operations better-supabase's `permissions: true` resolves through `forOperation`. */
@@ -245,4 +460,116 @@ type ToolPolicy<C> = {
  */
 export declare function toolPolicy<C>(options: ToolPolicyOptions<C>): ToolPolicy<C>;
 //#endregion
-export type { AccessPolicyOptions, ApiKeySession, ApiKeySessionOptions, ApiKeyVerifierOptions, AuthorizationProviderOptions, AuthorizerOperation, AuthorizerOptions, BetterSupabaseSubjectOptions, BucketAccess, CredentialGuardOptions, McpToolDecision, McpToolRef, ServiceRoles, SupabasePrincipal, ToolPolicy, ToolPolicyOptions, TopicAccess };
+//#region src/better-supabase/principals.d.ts
+/**
+ * Where an identity link points: an app user, whose claims `principal`
+ * loads, or a contact the app stores itself, which must be `kind: 'contact'`.
+ */
+type BetterSupabaseIdentityLink = {
+  readonly user: string;
+} | {
+  readonly contact: Principal;
+};
+type Maybe<T> = T | null | undefined | Promise<T | null | undefined>;
+type PrincipalSourceOptions = {
+  /**
+   * The claims better-supabase mints for `userId` now, or `null` for a user
+   * deleted, suspended or unknown. `sqlSupportStore(…).claims`, which runs
+   * the custom access token hook, fills it.
+   */
+  readonly claims: (userId: string, options: {
+    readonly tenant?: string;
+  }) => Maybe<Readonly<Record<string, unknown>>>;
+  /**
+   * The identity link for an email address or chat user. Only links the
+   * app created through a signed-in link flow or a verified address count.
+   * Without it the source has no `principalByIdentity`.
+   */
+  readonly identities?: (identity: PrincipalIdentity) => Maybe<BetterSupabaseIdentityLink>;
+  /** How the claims map to a principal; the defaults of `subjectFromBetterSupabase`. */
+  readonly subject?: Omit<BetterSupabaseSubjectOptions, "apiKeys">;
+};
+/**
+ * A `PrincipalSource` over better-supabase: `principal(id)` maps the claims
+ * `claims` loads with `subjectFromBetterSupabase`, and `principalByIdentity`
+ * follows `identities` to a user or a contact. Claims for another user, a
+ * link to a non-contact principal and a missing link are `null`.
+ */
+export declare function principalSource(options: PrincipalSourceOptions): PrincipalSource;
+//#endregion
+//#region src/better-supabase/share-links.d.ts
+/** The fields of better-supabase's `ResolvedShareLink` a link subject is built from. */
+type ShareLinkRow = {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  readonly role: string;
+  /** Set on a link pinned to one version, which `subjectFromShareLink` refuses. */
+  readonly versionId?: string;
+  readonly expiresAt?: Instant;
+};
+/** better-supabase's `ShareLinks`, or anything with its `resolve`. */
+type ShareLinkResolver = {
+  resolve(token: string): PromiseLike<{
+    readonly ok: true;
+    readonly data: ShareLinkRow | null;
+  } | {
+    readonly ok: false;
+  }>;
+};
+/** How links on one better-supabase subject type map to PermDock. */
+type ShareLinkTarget = {
+  /** The resource the subject type's rows are; RLS matches it against `capability.on.resource`. */
+  readonly resource: Permission | PermissionTree;
+  /** PermDock roles for each share-link role (`{ view: ['guest'] }`). A role with no entry is refused. */
+  readonly roles: Readonly<Record<string, readonly string[]>>;
+};
+type ShareLinkSubjectOptions = {
+  readonly shareLinks: ShareLinkResolver;
+  /** One entry per subject type a guest page serves, keyed by better-supabase's `subjectType`. */
+  readonly links: Readonly<Record<string, ShareLinkTarget>>;
+  /** Lifetime of the subject in seconds, capped by the link's own expiry. Default 300, at most 3600. */
+  readonly ttl?: number;
+  /**
+   * The link policies of the link's organization (`row.organizationId`);
+   * every one must hold, and a throw denies. A row carries no creation
+   * time, so a `maxLifetime` rule refuses every share link.
+   */
+  readonly linkPolicy?: (capability: Capability, row: ShareLinkRow) => LinkPolicy | readonly LinkPolicy[] | undefined | Promise<LinkPolicy | readonly LinkPolicy[] | undefined>;
+  readonly onAuth?: (event: AuthEvent) => void;
+  readonly requestId?: string;
+  readonly now?: Instant;
+};
+/**
+ * Resolves a better-supabase share-link token into the `link` subject it
+ * acts as, for `exchangeCapability` and `--capabilities` RLS. The row is
+ * read on every call, so a revoked or expired link stops resolving at
+ * once. An unknown token, subject type or role, a malformed row, a broken
+ * link policy, a `resolve` error and a throw are the anonymous subject. So
+ * is a link pinned to a version: a capability grants the subject's current
+ * rows, so a pinned link reads through `versions.getShared(token)` instead.
+ */
+export declare function subjectFromShareLink(token: string | undefined | null, options: ShareLinkSubjectOptions): Promise<Subject<CapabilityPrincipal>>;
+//#endregion
+//#region src/better-supabase/workflow.d.ts
+/** Where `handlerCan` gets the request's instance, such as `permdock/server`'s `createPermDock` result. */
+type HandlerPermDockSource = {
+  readonly getPermDock: (request: Request) => PermDock | Promise<PermDock>;
+};
+/**
+ * The `can` option of better-supabase's `authorizeHook`, for the caller's
+ * `permdock`: `true` only when the caller is a member of the hook's tenant
+ * and `decide` grants the permission its `hookMetadata` names there. An
+ * unknown key, `approval-required` and a throw are `false`.
+ */
+export declare function hookCan(permdock: PermDock): NonNullable<AuthorizeHookOptions["can"]>;
+/**
+ * The `can` option of better-supabase's `protectWebHandler`: `undefined`
+ * (401) when the request has no signed-in principal or `getPermDock`
+ * throws, otherwise whether `decide` grants the permission in the request's
+ * active tenant. An unknown key and `approval-required` are `false` (403).
+ */
+export declare function handlerCan(source: HandlerPermDockSource): ProtectWebHandlerOptions["can"];
+//#endregion
+export type { AccessPolicyOptions, AccessReviewApplierOptions, AccessReviewApplyFailure, AccessReviewApplyResult, ApiKeySession, ApiKeySessionOptions, ApiKeyVerifierOptions, AuthorizationHooksOptions, AuthorizationProviderOptions, AuthorizerOperation, AuthorizerOptions, BetterSupabaseIdentityLink, BetterSupabaseSubjectOptions, BucketAccess, CredentialGuardOptions, HandlerPermDockSource, McpToolDecision, McpToolRef, PendingSupportSession, PrincipalSourceOptions, ProviderApprovers, ServiceRoles, ShareLinkResolver, ShareLinkRow, ShareLinkSubjectOptions, ShareLinkTarget, SubscriberPolicyEvent, SubscriberPolicyOptions, SupabasePrincipal, SupportPolicyOptions, ToolPolicy, ToolPolicyOptions, TopicAccess };