permdock 0.3.1 → 0.5.0

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

@@ -1,14 +1,298 @@
-import { $t as CredentialPrincipal, C as Policy, Pr as Subject, ln as PermDock, nt as CredentialVerifier } from "../policy-IB6yxpC3.js";
-import { f as Permission, m as PermissionTree } from "../permissions-DttnqqxC.js";
-import { g as SupabaseSubjectOptions, m as SupabaseSessionLike, u as SupabasePrincipal } from "../types-C97IskBw.js";
+import { Rt as Instant, St as ApiKeyPrincipal, T as Policy, U as CredentialVerifier, gt as SupportSession, ir as Subject, pn as ApproverInput, qt as AuthEvent, rr as Principal } from "../policy-types-DzwivBgR.js";
+import { E as PermissionTree, w as Permission } from "../vocabulary-D6lPdb4Z.js";
+import { d as PrincipalIdentity, i as PermDockOptions, p as PrincipalSource, r as PermDock } from "../permdock-D7eeLJER.js";
+import { c as AccessReviewStore } from "../types-_sHy8BQf.js";
+import { i as SupabaseRpcCaller } from "../postgrest-NUqZT-RB.js";
+import { g as SupabaseSubjectOptions, m as SupabaseSessionLike, u as SupabasePrincipal } from "../types-CdlxsYQh.js";
+import { c as LinkPolicy, o as CapabilityPrincipal, t as Capability } from "../capability-BSslw1QV.js";
 import { AuthorizationProvider } from "better-supabase/config";
+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 { ApiKey, ApiKeyClaimsOptions, ApiKeys } from "better-supabase/blocks/api-keys";
 import { CredentialProvider } from "better-supabase/credentials";
 import { ToolDecision, ToolRef } from "better-supabase/mcp";
-import { EntitlementClaimOptions } from "better-supabase/blocks/entitlements";
-import { AuthSession } from "better-supabase/server";
+import { AuthorizeHookOptions, ProtectWebHandlerOptions } from "better-supabase/workflow-sdk";
+//#region src/better-supabase/access-reviews.d.ts
+type AccessReviewApplierOptions = {
+  /**
+   * 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 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 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 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">;
+};
+/**
+ * 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 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. */
+type ServiceRoles<K> = readonly string[] | ((key: K) => readonly string[]);
+type ApiKeyVerifierOptions = {
+  /** `createApiKeys()` over a service transport. */
+  readonly keys: Pick<ApiKeys, "verify">;
+  /**
+   * `permdock.manifest.json`, whose `rls.apiKeys.serviceRoles` is the
+   * default for `serviceRoles`.
+   */
+  readonly manifest?: unknown;
+  /**
+   * The roles a tenant key holds in its tenant, as a `service` principal.
+   * Without it or a manifest with `rls.apiKeys`, a tenant key verifies to
+   * `null`.
+   */
+  readonly serviceRoles?: ServiceRoles<ApiKey>;
+  /** The permissions `*` stands for. Without it, a key with `*` verifies to `null`. */
+  readonly allPermissions?: readonly Permission[];
+};
+/**
+ * better-supabase's API keys as a `CredentialVerifier`, for
+ * `subjectFromApiKey` from `permdock/server`, which reads PermDock's
+ * `pdk_<id>_<secret>` format: create the keys with `prefix: "pdk"`. The
+ * credential id is the key's `publicId`, the id in the token. A personal key
+ * is a `user` credential acting as its user (inside its tenant when the key
+ * is limited to one), a tenant key a `service` credential holding
+ * `serviceRoles` in its tenant, and the key's scopes are the credential's
+ * permissions. better-supabase records the use when it verifies, so there is
+ * no `touch`. A rotated key in its grace period verifies, and its credential
+ * expires when the grace period ends. An invalid, revoked, expired or
+ * rate-limited key, and a failed lookup, are `null`. `permdock/server` exports a different
+ * `apiKeyVerifier`, over the application's own key records.
+ */
+export declare function apiKeyVerifier(options: ApiKeyVerifierOptions): CredentialVerifier;
+/**
+ * The `claim` and `tenantClaim` options of better-supabase's
+ * `apiKeyClaims()`, from the manifest's `rls.apiKeys`, so a key's token
+ * carries the scopes ceiling, tenant and roles the `rls generate` helpers
+ * read. Throws when the manifest has no `rls.apiKeys`.
+ */
+export declare function apiKeyClaimOptions(manifest: unknown): Pick<ApiKeyClaimsOptions, "claim" | "tenantClaim">;
+//#endregion
+//#region src/better-supabase/subject.d.ts
+/** An `AuthSession` of kind `apiKey`, from better-supabase's api-keys middleware. */
+type ApiKeySession = Extract<AuthSession, {
+  readonly kind: "apiKey";
+}>;
+type ApiKeySessionOptions = {
+  /** The definitions: the key's scopes become the subject's delegation, and `*` stands for all of them. */
+  readonly permissions: PermissionTree;
+  /** `permdock.manifest.json`, whose `rls.apiKeys.serviceRoles` is the default for `serviceRoles`. */
+  readonly manifest?: unknown;
+  /** The roles a tenant key holds in its tenant. Without it or a manifest with `rls.apiKeys`, a tenant key is anonymous. */
+  readonly serviceRoles?: ServiceRoles<ApiKeySession>;
+};
+/** The claim, and the short code better-supabase writes for each feature key. */
+type FeatureClaim = EntitlementClaimOptions;
+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;
+  /**
+   * The claim `principal.plans` reads: its name (default `features`), or
+   * `{ claim, keys }` with the same `entitlements.claim.keys` better-supabase
+   * writes short codes with, so `plans` holds the feature keys. A code
+   * without a key is dropped.
+   */
+  readonly plans?: string | FeatureClaim;
+};
+/**
+ * `subjectFromSupabaseSession` for better-supabase's `AuthSession`, reading
+ * `memberships` for the memberships and the entitlements module's `features`
+ * claim for `principal.plans` (`plans` names another claim). With `apiKeys`,
+ * a verified `apiKey` session is the key's credential subject: a personal key
+ * acts as its user within the key's scopes, a tenant key as a `service`
+ * 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<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`. */
@@ -22,12 +306,20 @@ type AuthorizationProviderOptions = {
   /** 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
-   * 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 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
@@ -35,12 +327,40 @@ type AuthorizationProviderOptions = {
  * 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
+ * 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`. */
+type AuthorizerOperation = "list" | "get" | "create" | "update" | "delete";
+type AuthorizerOptions = {
+  readonly policy: Policy;
+  /** How the verified claims map to a subject; the defaults of `subjectFromBetterSupabase`. */
+  readonly subject?: Omit<BetterSupabaseSubjectOptions, "apiKeys">;
+  /**
+   * The permission of each table operation, so a resource with
+   * `permissions: true` is checked. Without it such a resource is refused.
+   */
+  readonly operations?: Readonly<Record<string, Partial<Record<AuthorizerOperation, Permission>>>>;
+  /** Sources and sinks for each instance. The subject, actor and tenant always come from the verified request. */
+  readonly options?: Omit<PermDockOptions, "tenant" | "actor" | "delegation" | "session" | "expiresAt">;
+};
+/**
+ * better-supabase's `authorizer` for PermDock: every resource, action, route
+ * guard and MCP tool that declares a `permission` is decided with `decide`.
+ * The subject is mapped from the verified claims with
+ * `subjectFromBetterSupabase`; the request's `context.tenant` selects the
+ * active tenant only among the memberships the claims hold. A caller without
+ * claims is anonymous, and a throw denies.
+ */
+export declare function authorizer(options: AuthorizerOptions): Authorizer<Permission>;
+//#endregion
 //#region src/better-supabase/policies.d.ts
 type AccessScope = {
   /** A scope in the policy's scopes (or the manifest's `rls.scopes`), or `platform` for permissions granted globally. */
@@ -93,49 +413,6 @@ export declare function bucketPolicy(access: BucketAccess, options: AccessPolicy
 /** As {@link bucketPolicy}, for a better-supabase Realtime topic. */
 export declare function topicPolicy(access: TopicAccess, options: AccessPolicyOptions): AccessTopicPolicy;
 //#endregion
-//#region src/better-supabase/api-keys.d.ts
-/** The roles a tenant key holds in its tenant: a list, or one per key. */
-type ServiceRoles<K> = readonly string[] | ((key: K) => readonly string[]);
-type ApiKeyVerifierOptions = {
-  /** `createApiKeys()` over a service transport. */
-  readonly keys: Pick<ApiKeys, "verify">;
-  /**
-   * `permdock.manifest.json`, whose `rls.apiKeys.serviceRoles` is the
-   * default for `serviceRoles`.
-   */
-  readonly manifest?: unknown;
-  /**
-   * The roles a tenant key holds in its tenant, as a `service` principal.
-   * Without it or a manifest with `rls.apiKeys`, a tenant key verifies to
-   * `null`.
-   */
-  readonly serviceRoles?: ServiceRoles<ApiKey>;
-  /** The permissions `*` stands for. Without it, a key with `*` verifies to `null`. */
-  readonly allPermissions?: readonly Permission[];
-};
-/**
- * better-supabase's API keys as a `CredentialVerifier`, for
- * `subjectFromApiKey` from `permdock/server`, which reads PermDock's
- * `pdk_<id>_<secret>` format: create the keys with `prefix: "pdk"`. The
- * credential id is the key's `publicId`, the id in the token. A personal key
- * is a `user` credential acting as its user (inside its tenant when the key
- * is limited to one), a tenant key a `service` credential holding
- * `serviceRoles` in its tenant, and the key's scopes are the credential's
- * permissions. better-supabase records the use when it verifies, so there is
- * no `touch`. A rotated key in its grace period verifies, and its credential
- * expires when the grace period ends. An invalid, revoked, expired or
- * rate-limited key, and a failed lookup, are `null`. `permdock/server` exports a different
- * `apiKeyVerifier`, over the application's own key records.
- */
-export declare function apiKeyVerifier(options: ApiKeyVerifierOptions): CredentialVerifier;
-/**
- * The `claim` and `tenantClaim` options of better-supabase's
- * `apiKeyClaims()`, from the manifest's `rls.apiKeys`, so a key's token
- * carries the scopes ceiling, tenant and roles the `rls generate` helpers
- * read. Throws when the manifest has no `rls.apiKeys`.
- */
-export declare function apiKeyClaimOptions(manifest: unknown): Pick<ApiKeyClaimsOptions, "claim" | "tenantClaim">;
-//#endregion
 //#region src/better-supabase/credentials.d.ts
 type CredentialGuardOptions = {
   /** The request's PermDock instance. */
@@ -183,41 +460,116 @@ type ToolPolicy<C> = {
  */
 export declare function toolPolicy<C>(options: ToolPolicyOptions<C>): ToolPolicy<C>;
 //#endregion
-//#region src/better-supabase/subject.d.ts
-/** An `AuthSession` of kind `apiKey`, from better-supabase's api-keys middleware. */
-type ApiKeySession = Extract<AuthSession, {
-  readonly kind: "apiKey";
-}>;
-type ApiKeySessionOptions = {
-  /** The definitions: the key's scopes become the subject's delegation, and `*` stands for all of them. */
-  readonly permissions: PermissionTree;
-  /** `permdock.manifest.json`, whose `rls.apiKeys.serviceRoles` is the default for `serviceRoles`. */
-  readonly manifest?: unknown;
-  /** The roles a tenant key holds in its tenant. Without it or a manifest with `rls.apiKeys`, a tenant key is anonymous. */
-  readonly serviceRoles?: ServiceRoles<ApiKeySession>;
+//#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;
 };
-/** The claim, and the short code better-supabase writes for each feature key. */
-type FeatureClaim = EntitlementClaimOptions;
-type BetterSupabaseSubjectOptions = Omit<SupabaseSubjectOptions, "plans"> & {
-  /** How `kind: 'apiKey'` sessions map. Without it they are anonymous. */
-  readonly apiKeys?: ApiKeySessionOptions;
+type Maybe<T> = T | null | undefined | Promise<T | null | undefined>;
+type PrincipalSourceOptions = {
   /**
-   * The claim `principal.plans` reads: its name (default `features`), or
-   * `{ claim, keys }` with the same `entitlements.claim.keys` better-supabase
-   * writes short codes with, so `plans` holds the feature keys. A code
-   * without a key is dropped.
+   * 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 plans?: string | FeatureClaim;
+  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">;
 };
 /**
- * `subjectFromSupabaseSession` for better-supabase's `AuthSession`, reading
- * `memberships` for the memberships and the entitlements module's `features`
- * claim for `principal.plans` (`plans` names another claim). With `apiKeys`,
- * a verified `apiKey` session is the key's credential subject: a personal key
- * acts as its user within the key's scopes, a tenant key as a `service`
- * principal holding `serviceRoles`. Without `apiKeys`, and for `anon`,
- * `service` and `invalid` sessions, the subject is anonymous.
+ * 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 subjectFromBetterSupabase(session: SupabaseSessionLike | ApiKeySession | null | undefined, options?: BetterSupabaseSubjectOptions): Subject<SupabasePrincipal> | Subject<CredentialPrincipal> | Subject;
+export declare function handlerCan(source: HandlerPermDockSource): ProtectWebHandlerOptions["can"];
 //#endregion
-export type { AccessPolicyOptions, ApiKeySession, ApiKeySessionOptions, ApiKeyVerifierOptions, AuthorizationProviderOptions, BetterSupabaseSubjectOptions, BucketAccess, CredentialGuardOptions, McpToolDecision, McpToolRef, ServiceRoles, SupabasePrincipal, ToolPolicy, ToolPolicyOptions, TopicAccess };
+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 };