permdock 0.1.0 → 0.3.0

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

@@ -0,0 +1,223 @@
+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 { AuthorizationProvider } from "better-supabase/config";
+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";
+//#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
+   * 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.
+   */
+  readonly approver?: Permission;
+};
+/**
+ * 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.
+ */
+export declare function authorizationProvider(options: AuthorizationProviderOptions): AuthorizationProvider;
+//#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. */
+  readonly scope: string;
+  /** 1-based path or topic segment holding the scope id; better-supabase's default is the `{organizationId}` segment. */
+  readonly segment?: number;
+};
+/**
+ * Either the policy the app already defines, or the two files the CLI writes.
+ * With `policy` nothing is read at runtime: the scopes, the row conditions and
+ * the scopes a permission is granted at come from the definitions.
+ */
+type AccessPolicyOptions = AccessScope & ({
+  /** `permdock.manifest.json`, parsed or as JSON text: it names the helpers' schema and the scopes. */
+  readonly manifest: unknown;
+  /** `permissions.catalog.json`: only keys it marks `rowConditions: false` are accepted. */
+  readonly catalog: unknown;
+  readonly policy?: undefined;
+  readonly schema?: undefined;
+} | {
+  /** The `definePolicy` result: only keys with no row condition in it are accepted. */
+  readonly policy: Policy;
+  /** The schema `rls generate` put the helpers in (`rls.schema`). Default `permdock`. */
+  readonly schema?: string;
+  readonly manifest?: undefined;
+  readonly catalog?: undefined;
+});
+type BucketAccess = {
+  /** Downloads, signed URLs, renders and metadata reads. */
+  readonly read: Permission;
+  /** Listing; without it `read` covers listing too. */
+  readonly list?: Permission;
+  /** Uploads, updates and moves; also deletes unless `delete` is set. */
+  readonly write: Permission;
+  readonly delete?: Permission;
+};
+type TopicAccess = {
+  readonly receive: Permission;
+  /** Lets clients send on the topic. */
+  readonly send?: Permission;
+};
+/**
+ * A better-supabase bucket `policy` that checks PermDock permissions with
+ * the `rls generate` helpers at `scope`. The helpers check role and scope
+ * only, so a permission with row conditions (`rowConditions: true` in the
+ * catalog, or a conditioned grant in `policy`), or one not granted at
+ * `scope`, throws.
+ */
+export declare function bucketPolicy(access: BucketAccess, options: AccessPolicyOptions): AccessBucketPolicy;
+/** 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. */
+  readonly permdock: () => PermDock | Promise<PermDock>;
+  /** The permission that resolves a token or connects an account; decided on the ref. */
+  readonly use: Permission;
+  /** The permission that revokes a stored credential; defaults to `use`. */
+  readonly revoke?: Permission;
+};
+/**
+ * `provider` with every `getToken`, `startAuthorization`,
+ * `completeAuthorization` and `revoke` decided by PermDock first, on the
+ * `CredentialRef` as the row. Anything but `granted` is a `forbidden`
+ * error with hint `PERMDOCK_DENIED`, and a failed check is one too.
+ * `capabilities` and `verifyInbound` (a third party's request, with no
+ * user) pass through. Build it per request, with that request's PermDock.
+ */
+export declare function credentialGuard(provider: CredentialProvider, options: CredentialGuardOptions): CredentialProvider;
+//#endregion
+//#region src/better-supabase/mcp.d.ts
+/** What better-supabase's `createMcp` hooks see of a tool. */
+type McpToolRef = Pick<ToolRef, "meta">;
+/** The outcome of better-supabase's `createMcp` `authorize` hook. */
+type McpToolDecision = ToolDecision;
+type ToolPolicyOptions<C> = {
+  /** The request's PermDock instance, from the hook's context. */
+  readonly permdock: (ctx: C) => PermDock | Promise<PermDock>;
+  /**
+   * The row an instance permission is decided on, from the validated
+   * arguments. Without it the call is decided without a row, which an
+   * instance permission with a row condition denies.
+   */
+  readonly data?: (ctx: C, tool: McpToolRef, args: unknown) => unknown;
+};
+type ToolPolicy<C> = {
+  readonly authorize: (ctx: C, tool: McpToolRef, args: unknown) => Promise<McpToolDecision>;
+  readonly visible: (ctx: C, tool: McpToolRef) => Promise<boolean>;
+};
+/**
+ * The `authorize` and `visible` hooks of better-supabase's `createMcp`, for
+ * 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.
+ */
+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>;
+};
+/** 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;
+  /**
+   * 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<CredentialPrincipal> | Subject;
+//#endregion
+export type { AccessPolicyOptions, ApiKeySession, ApiKeySessionOptions, ApiKeyVerifierOptions, AuthorizationProviderOptions, BetterSupabaseSubjectOptions, BucketAccess, CredentialGuardOptions, McpToolDecision, McpToolRef, ServiceRoles, SupabasePrincipal, ToolPolicy, ToolPolicyOptions, TopicAccess };