permdock 0.9.0 → 0.11.0

package/dist/active-tenant-DVee32-T.js

@@ -0,0 +1,39 @@
+import { i as qualifySqlTable } from "./sql-0WjxIp9g.js";
+//#region src/better-supabase/active-tenant.ts
+function describe(from) {
+	return "appMetadata" in from ? `app_metadata.${from.appMetadata}` : `${from.table}.${from.column} (joined on ${from.id})`;
+}
+/**
+* Why PermDock's token hook and better-supabase disagree on the active tenant,
+* or `undefined` when they agree. `"resolver"` takes the tenant from the
+* request, so any hook source agrees with it.
+*/
+function activeTenantMismatch(from, tenantClaim, activeTenant) {
+	if (activeTenant === "resolver") return;
+	if (activeTenant === "claim") {
+		if ("appMetadata" in from && from.appMetadata === tenantClaim) return;
+		return `blocks.permissions.activeTenant is "claim", so better-supabase's switch_organization writes app_metadata.${tenantClaim}, but PermDock's token hook reads the active tenant from ${describe(from)}. Set supabase.hook.activeFrom: "app_metadata.${tenantClaim}" and run permdock supabase hook generate.`;
+	}
+	const dot = activeTenant.profileColumn.lastIndexOf(".");
+	if (dot <= 0) return;
+	const table = qualifySqlTable(activeTenant.profileColumn.slice(0, dot));
+	const column = activeTenant.profileColumn.slice(dot + 1);
+	const id = activeTenant.key ?? "id";
+	if ("table" in from && qualifySqlTable(from.table) === table && from.column === column && from.id === id) return;
+	return `blocks.permissions.activeTenant writes the active tenant to ${table}.${column} (joined on ${id}), but PermDock's token hook reads it from ${describe(from)}. Set supabase.hook.activeFrom: { table: "${table}", column: "${column}", id: "${id}" } and run permdock supabase hook generate.`;
+}
+/**
+* Where the token hook reads the active tenant, as better-supabase names it in
+* `tokenHook.activeOrganizationFrom`, or `undefined` when the hook reads an
+* `app_metadata` key other than the tenant claim, which has no better-supabase
+* name.
+*/
+function activeOrganizationFrom(from, tenantClaim) {
+	if ("appMetadata" in from) return from.appMetadata === tenantClaim ? "claim" : void 0;
+	return {
+		profileColumn: `${qualifySqlTable(from.table)}.${from.column}`,
+		...from.id === "id" ? {} : { key: from.id }
+	};
+}
+//#endregion
+export { activeTenantMismatch as n, activeOrganizationFrom as t };

package/dist/{adoption-scan-Ch07MdxN.js → adoption-scan-DKCOsfcF.js}

@@ -1,5 +1,5 @@
 import { r as listSourceFiles } from "./files-BSjrtIHw.js";
-import { t as DOCS_BASE } from "./manifest-B2QPh19C.js";
+import { t as DOCS_BASE } from "./manifest-Cav1rjNQ.js";
 import { readFileSync } from "node:fs";
 import { relative } from "node:path";
 //#region src/cli/adoption-scan.ts

package/dist/{arazzo-BpS7LnV0.js → arazzo-BXaEhGHM.js}

@@ -21,7 +21,7 @@ const check = defineLeaf({
 		...permissionsFlag
 	},
 	async run(ctx, { flags }) {
-		return (await import("./arazzo-CmQaGPkM.js")).runArazzo({
+		return (await import("./arazzo-CTH5iN--.js")).runArazzo({
 			cwd: ctx.cwd,
 			config: ctx.config,
 			doc: given(flags.doc),

package/dist/{arazzo-CmQaGPkM.js → arazzo-CTH5iN--.js}

@@ -3,7 +3,7 @@ import { c as missingInput } from "./errors-Vpu6rKHl.js";
 import { i as readJsonFile } from "./files-BSjrtIHw.js";
 import { t as ARAZZO_REPORT_SCHEMA } from "./version-DMQ0dnN5.js";
 import { a as loadModule, s as pickNamed, t as asPermissionTree } from "./load-DjSU5KXO.js";
-import { t as DOCS_BASE } from "./manifest-B2QPh19C.js";
+import { t as DOCS_BASE } from "./manifest-Cav1rjNQ.js";
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 //#region src/cli/arazzo.ts

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

@@ -1,13 +1,15 @@
-import { Cn as ApproverInput, Ot as ApiKeyPrincipal, St as SupportSession, T as Policy, U as CredentialVerifier, Wt as Instant, hr as Subject, pr as Principal, rn as AuthEvent } from "../policy-types-DGIO_gxq.js";
+import { Cn as ApproverInput, Ot as ApiKeyPrincipal, St as SupportSession, T as Policy, U as CredentialVerifier, Wt as Instant, X as Intent, hr as Subject, nt as MembershipSource, pr as Principal, rn as AuthEvent } from "../policy-types-DGIO_gxq.js";
 import { f as PermissionTree, u as Permission } from "../permission-types-CAY-GU7e.js";
 import { _ as PrincipalSource, a as PermDock, h as PrincipalIdentity, o as PermDockOptions } from "../permdock-CprAPN3w.js";
 import { c as AccessReviewStore } from "../types-B2efzoSX.js";
 import { i as SupabaseRpcCaller } from "../postgrest-D5nUGm-c.js";
 import { a as CatalogDocument } from "../types-ZzRGoViD.js";
-import { d as SupabasePrincipal, g as SupabaseSessionLike, v as SupabaseSubjectOptions } from "../types-BMVDHvI0.js";
+import { A as SupabaseSubjectOptions, C as SupabasePrincipal, N as SupabaseSuspension, O as SupabaseSessionLike, s as SqlMembershipSource } from "../sources-oB1Hg1Fm.js";
+import { n as VersionCache } from "../version-cache-Df11C2Qp.js";
+import { t as SqlQuery } from "../sql-B80DFdpG.js";
 import { c as LinkPolicy, o as CapabilityPrincipal, t as Capability } from "../capability-Di9tiUvi.js";
 import { AuthorizationProvider } from "better-supabase/config";
-import { AuthSession, AuthorizationHooks, Authorizer, SupportAuthorize, SupportAuthorizeInput } from "better-supabase/server";
+import { AuthSession, AuthorizationHooks, AuthorizationRequest, 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";
@@ -159,6 +161,18 @@ type ApiKeySessionOptions = {
    */
   readonly serviceRoles?: ServiceRoles<ApiKeySession>;
 };
+/**
+ * better-supabase's `SessionSnapshot` (0.15 and later): one verified token,
+ * from `bsb.getRequestSession()`, that `'use cache: private'` scopes share. Its
+ * `issuedAt` and `authzVersion` come from the `iat` and `authz_ver` claims.
+ */
+type SessionSnapshotLike = {
+  readonly accessToken: string;
+  readonly userId: string;
+  readonly claims: unknown;
+  readonly issuedAt?: number | null;
+  readonly authzVersion?: number | null;
+};
 /** The claim, and the short code better-supabase writes for each feature key. */
 type FeatureClaim = EntitlementClaimOptions;
 type BetterSupabaseSubjectOptions = Omit<SupabaseSubjectOptions, "claims"> & {
@@ -184,9 +198,10 @@ type BetterSupabaseSubjectOptions = Omit<SupabaseSubjectOptions, "claims"> & {
  * 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.
+ * `service` and `invalid` sessions, the subject is anonymous. A
+ * `SessionSnapshot` maps as the user session of its claims.
  */
-export declare function subjectFromBetterSupabase(session: SupabaseSessionLike | ApiKeySession | null | undefined, options?: BetterSupabaseSubjectOptions): Subject<SupabasePrincipal> | Subject<ApiKeyPrincipal> | Subject;
+export declare function subjectFromBetterSupabase(session: SupabaseSessionLike | ApiKeySession | SessionSnapshotLike | null | undefined, options?: BetterSupabaseSubjectOptions): Subject<SupabasePrincipal> | Subject<ApiKeyPrincipal> | Subject;
 //#endregion
 //#region src/better-supabase/subscribers.d.ts
 /** The fields of better-supabase's `OutboxEvent` the policy reads. */
@@ -350,6 +365,17 @@ type AuthorizationHooksOptions = {
  */
 export declare function authorizationHooks(options: AuthorizationHooksOptions): AuthorizationHooks;
 //#endregion
+//#region src/better-supabase/active-tenant.d.ts
+/**
+ * better-supabase's `blocks.permissions.activeTenant`: where its
+ * `switch_organization` writes the active tenant and `current_tenant_id()`
+ * reads it.
+ */
+type BetterSupabaseActiveTenant = "claim" | "resolver" | {
+  readonly profileColumn: string;
+  readonly key?: string;
+};
+//#endregion
 //#region src/better-supabase/provider.d.ts
 type AuthorizationProviderOptions = {
   /**
@@ -380,6 +406,14 @@ type AuthorizationProviderOptions = {
    * `permdock_is_approver` from `rls.approvals`.
    */
   readonly approvers?: ProviderApprovers;
+  /**
+   * better-supabase's `blocks.permissions.activeTenant`. When the token hook
+   * reads the active tenant from another place than better-supabase writes it,
+   * `problems` names the `supabase.hook.activeFrom` to set. With `"resolver"`
+   * the tenant comes from the request, so `tokenHook.activeOrganizationFrom`
+   * stays unset and doctor BS409 has nothing to compare.
+   */
+  readonly activeTenant?: BetterSupabaseActiveTenant;
 };
 /**
  * better-supabase's `authorization` config value, built from PermDock's
@@ -387,16 +421,31 @@ 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; `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, and so is `teamIdsOf` (`member_<scope>_ids_of({user})`)
- * for a scope named `team` or `teams`. Throws when the manifest or catalog is
- * invalid, or when the tenant scope is ambiguous.
+ * helper, which `rls.mode: 'database'` writes. `isApprover` is set with
+ * `approvers` or `approver` and `permdock_is_approver`: `approver` fills its
+ * `'ai-tool'` entry. `canApprove` is never set. `holdersOf` (`permitted_<tenant
+ * scope>_users`) and `actorMayWrite` (`permdock_actor_may_write()`) are set
+ * when the manifest lists their helper, and so is `teamIdsOf`
+ * (`member_<scope>_ids_of({user})`) for a scope named `team` or `teams`. 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/report.d.ts
+/** What an `onError` sink receives next to the thrown error. */
+type BetterSupabaseErrorContext = {
+  /** The key of the permission being checked, when the request named one. */
+  readonly permission: string | null;
+  /** The active tenant the check ran in, or `null`. */
+  readonly tenant: string | null;
+};
+/**
+ * Receives an error a permission check threw. The check still denies; a sink
+ * that throws is ignored.
+ */
+type BetterSupabaseOnError = (error: unknown, context: BetterSupabaseErrorContext) => void;
+//#endregion
 //#region src/better-supabase/authorizer.d.ts
 /**
  * The table operations better-supabase's `permissions: true` resolves through
@@ -416,10 +465,36 @@ type AuthorizerOptions = {
    */
   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.
+   * The membership source a stale or truncated token is re-read from, wrapped
+   * in `claimsFirst(source, { onStale: 'reread', versions })`. `versions` is
+   * the cache better-supabase passes at runtime (`createNext({ versions })`),
+   * else the `versions` option.
    */
-  readonly options?: Omit<PermDockOptions, "tenant" | "actor" | "delegation" | "session" | "expiresAt">;
+  readonly memberships?: MembershipSource | readonly MembershipSource[];
+  /**
+   * The current authorization version for `memberships`, such as
+   * `authzVersion({ query })`; default the source's own `version`.
+   */
+  readonly version?: MembershipSource["version"];
+  /**
+   * The version cache for `memberships` when better-supabase passes none (0.13
+   * and 0.14, or a server created without `versions`).
+   */
+  readonly versions?: VersionCache;
+  /**
+   * The intent of one check. By default a batch (`evaluations`, list and row
+   * filtering) and an action named `read`, `list` or `view` are `read`, so
+   * `claimsFirst` may answer from the version cache; every other check is
+   * `write` and reads the version live.
+   */
+  readonly intent?: (request: AuthorizationRequest<Permission>) => Intent;
+  /** Receives every error a check threw; the check still denies. */
+  readonly onError?: BetterSupabaseOnError;
+  /**
+   * Sources and sinks for each instance. The subject, actor, tenant and intent
+   * always come from the verified request.
+   */
+  readonly options?: Omit<PermDockOptions, "tenant" | "actor" | "delegation" | "session" | "expiresAt" | "intent">;
 };
 /**
  * better-supabase's `authorizer` for PermDock: every resource, action, route
@@ -427,10 +502,76 @@ type AuthorizerOptions = {
  * 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.
+ * throw denies. With better-supabase 0.15's runtime `memo`, the checks of one
+ * request scope share an instance per claims, tenant and intent.
  */
 export declare function authorizer(options: AuthorizerOptions): Authorizer<Permission>;
 //#endregion
+//#region src/better-supabase/block-memberships.d.ts
+/**
+ * A roles table the membership's role column references, in better-supabase's
+ * `blocks.memberships.options.roleThrough` shape: the role column holds
+ * `table.id`, and `table.column` holds the role key.
+ */
+type BlockRoleThrough = {
+  readonly table: string;
+  readonly id: string;
+  readonly column: string;
+};
+/**
+ * A role junction holding several roles per membership: one row per role,
+ * `membership` referencing the membership's `id` column and `role` holding the
+ * role key.
+ */
+type BlockRoleJunction = {
+  readonly table: string;
+  /** The junction column referencing the membership. */
+  readonly membership: string;
+  /** The junction column holding the role key. */
+  readonly role: string;
+  /** The membership's primary key column. Default `id`. */
+  readonly id?: string;
+};
+type BlockMembershipSourceOptions = {
+  /** The memberships block's table. Default `better_supabase.memberships`. */
+  readonly table?: string;
+  /** The declared scope a row is a membership of. Default `organization`. */
+  readonly scope?: string;
+  /**
+   * Physical column names, keyed like better-supabase's
+   * `blocks.memberships.columns.memberships`. Defaults `organization_id`,
+   * `user_id`, `role` and `disabled_at`.
+   */
+  readonly columns?: {
+    readonly tenant?: string;
+    readonly user?: string;
+    readonly role?: string;
+    readonly disabledAt?: string | null;
+  };
+  /**
+   * The roles table the role column references, so a custom role's key reads
+   * through it. The same value as `blocks.memberships.options.roleThrough`.
+   */
+  readonly roleThrough?: BlockRoleThrough;
+  /**
+   * A role junction read instead of the role column. `"many"` reads
+   * `membership_roles` in the table's schema, the role set
+   * `blocks.memberships.options.roles.many` keeps, keyed by the tenant and user
+   * columns.
+   */
+  readonly roles?: BlockRoleJunction | "many";
+  readonly query?: SqlQuery;
+  readonly suspension?: SupabaseSuspension;
+};
+/**
+ * Memberships from better-supabase's `memberships` block table: one row per
+ * user and organization, its role key in `role`, a custom role's key through
+ * `roleThrough`, or several roles from a `roles` junction or, with `roles:
+ * "many"`, from better-supabase's `membership_roles`. A row with `disabled_at`
+ * set is no membership.
+ */
+export declare function blockMembershipSource(options?: BlockMembershipSourceOptions): SqlMembershipSource;
+//#endregion
 //#region src/better-supabase/policies.d.ts
 type AccessScope = {
   /**
@@ -536,6 +677,11 @@ type ToolPolicyOptions<C> = {
    * with a row condition denies.
    */
   readonly data?: (ctx: C, tool: McpToolRef, args: unknown) => unknown;
+  /**
+   * Receives every error `authorize` or `visible` threw; the tool stays
+   * refused.
+   */
+  readonly onError?: BetterSupabaseOnError;
 };
 type ToolPolicy<C> = {
   readonly authorize: (ctx: C, tool: McpToolRef, args: unknown) => Promise<McpToolDecision>;
@@ -546,7 +692,8 @@ type ToolPolicy<C> = {
  * tools whose `meta` is a PermDock permission. A tool without a permission is
  * hidden and refused. `authorize` grants only a `granted` decision: an
  * approval-required call is refused, because `createMcp` has no approval flow.
- * A throw anywhere refuses.
+ * A denial's text names the first denial reason. A throw anywhere refuses and
+ * reaches `onError`.
  */
 export declare function toolPolicy<C>(options: ToolPolicyOptions<C>): ToolPolicy<C>;
 //#endregion
@@ -729,19 +876,37 @@ export declare function subjectFromShareLink(token: string | undefined | null, o
 type HandlerPermDockSource = {
   readonly getPermDock: (request: Request) => PermDock | Promise<PermDock>;
 };
+type HookCanOptions = {
+  /**
+   * Loads the row the permission `key` is decided on in `tenant`, so a
+   * condition on the row applies. Without it there is no row; a throw is
+   * `false`.
+   */
+  readonly data?: (tenant: string, key: string) => unknown;
+};
+type HandlerCanOptions = {
+  /**
+   * Loads the row the permission `key` is decided on for `request`, so a
+   * condition on the row applies. Without it there is no row; a throw is
+   * `false` (403).
+   */
+  readonly data?: (request: Request, key: string) => unknown;
+};
 /**
  * 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`.
+ * `decide` grants the permission its `hookMetadata` names there, on the row
+ * `options.data` loads. An unknown key, `approval-required` and a throw are
+ * `false`.
  */
-export declare function hookCan(permdock: PermDock): NonNullable<AuthorizeHookOptions["can"]>;
+export declare function hookCan(permdock: PermDock, options?: HookCanOptions): 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).
+ * tenant, on the row `options.data` loads. An unknown key, `approval-required`
+ * and a throwing `data` are `false` (403).
  */
-export declare function handlerCan(source: HandlerPermDockSource): ProtectWebHandlerOptions["can"];
+export declare function handlerCan(source: HandlerPermDockSource, options?: HandlerCanOptions): ProtectWebHandlerOptions["can"];
 //#endregion
-export type { AccessPolicyOptions, AccessReviewApplierOptions, AccessReviewApplyFailure, AccessReviewApplyResult, ApiKeySession, ApiKeySessionOptions, ApiKeyVerifierOptions, AuthorizationHooksOptions, AuthorizationProviderOptions, AuthorizerOperation, AuthorizerOptions, BetterSupabaseIdentityLink, BetterSupabaseMembershipRow, BetterSupabaseSubjectOptions, BucketAccess, CredentialGuardOptions, HandlerPermDockSource, McpToolDecision, McpToolRef, PendingSupportSession, PrincipalFromMembershipsOptions, PrincipalSourceOptions, ProviderApprovers, RoleOrderOptions, ServiceRoles, ShareLinkResolver, ShareLinkRow, ShareLinkSubjectOptions, ShareLinkTarget, SubscriberPolicyEvent, SubscriberPolicyOptions, SupabasePrincipal, SupportPolicyOptions, ToolPolicy, ToolPolicyOptions, TopicAccess };
+export type { AccessPolicyOptions, AccessReviewApplierOptions, AccessReviewApplyFailure, AccessReviewApplyResult, ApiKeySession, ApiKeySessionOptions, ApiKeyVerifierOptions, AuthorizationHooksOptions, AuthorizationProviderOptions, AuthorizerOperation, AuthorizerOptions, BetterSupabaseActiveTenant, BetterSupabaseErrorContext, BetterSupabaseIdentityLink, BetterSupabaseMembershipRow, BetterSupabaseOnError, BetterSupabaseSubjectOptions, BlockMembershipSourceOptions, BlockRoleJunction, BlockRoleThrough, BucketAccess, CredentialGuardOptions, HandlerCanOptions, HandlerPermDockSource, HookCanOptions, McpToolDecision, McpToolRef, PendingSupportSession, PrincipalFromMembershipsOptions, PrincipalSourceOptions, ProviderApprovers, RoleOrderOptions, ServiceRoles, SessionSnapshotLike, ShareLinkResolver, ShareLinkRow, ShareLinkSubjectOptions, ShareLinkTarget, SubscriberPolicyEvent, SubscriberPolicyOptions, SupabasePrincipal, SupportPolicyOptions, ToolPolicy, ToolPolicyOptions, TopicAccess };