permdock 0.1.0 → 0.3.0

package/dist/testing/index.d.ts

@@ -1,14 +1,15 @@
-import { $ as DecisionSink, C as Policy, Et as TokenVerifier, Qt as PermDockOptions, St as SubjectResolver, Tt as TokenSigner, X as CredentialVerifier, Zt as PermDock, at as LimitStore, cr as CustomRole, ct as MembershipSource, ft as RelationSource, gt as Snapshot, hr as Subject, kn as ApprovalPolicySource, kt as WhereCompiler, mr as Principal, mt as SettingsSource, pr as Membership, pt as RoleSource, sn as PolicySource, tn as WhereResult, tt as EntitlementSource, xt as SnapshotSource } from "../policy-CInmNGkM.js";
-import { d as Permission, h as ResourceInit, l as InferPermissionTree } from "../permissions-B4apnahQ.js";
-import { r as Role } from "../vocabulary-Dk0fs-Jk.js";
-import { f as ApprovalStore } from "../types-B8w5PFtS.js";
-import { n as SupabaseHookManifest } from "../manifest-DDQbC6K0.js";
+import { At as SnapshotSource, C as Policy, Ct as SettingsSource, Dr as CustomRole, Ft as TokenVerifier, Mr as Membership, Nr as Principal, Pr as Subject, Pt as TokenSigner, Rt as WhereCompiler, Tt as Snapshot, Wn as ApprovalPolicySource, at as DecisionSink, bn as PolicySource, bt as RelationSource, dt as LimitStore, gt as MembershipSource, jt as SubjectResolver, ln as PermDock, mn as WhereResult, nt as CredentialVerifier, st as EntitlementSource, un as PermDockOptions, xt as RoleSource } from "../policy-IB6yxpC3.js";
+import { f as Permission, g as ResourceInit, u as InferPermissionTree } from "../permissions-DttnqqxC.js";
+import { r as Role } from "../vocabulary-DA8a8zif.js";
+import { f as ApprovalStore } from "../types-aqOHTHcp.js";
+import { t as ToolMap } from "../types-Bvc4oWT6.js";
+import { n as SupabaseHookManifest } from "../manifest-uDS9y5de.js";
 import { t as supabaseMembershipsBudget } from "../budget-JqcRqyhK.js";
 import { n as RevocationFeed } from "../revocations-Cy06JNx2.js";
-import { a as ReplayStore } from "../types-i4BAOvdb.js";
-import { v as DirectoryStore } from "../index-LF_hS-yn.js";
-import { a as SaasProject } from "../permissions-B8vCg_bI.js";
-import { n as saasPolicy } from "../policy-Cq2fB8Q5.js";
+import { g as ReplayStore } from "../types-Cq_H8N_X.js";
+import { v as DirectoryStore } from "../index-C8z4RjQV.js";
+import { a as SaasProject } from "../permissions-CDgvKG5L.js";
+import { n as saasPolicy } from "../policy-D2W7uv19.js";
 import { expectTypeOf } from "vitest";
 //#region src/testing/describe-policy.d.ts
 type MatrixOutcome = "granted" | "denied" | "approval-required";
@@ -358,6 +359,61 @@ type HttpAdapterOptions = {
  */
 export declare function testHttpAdapter(options: HttpAdapterOptions): void;
 //#endregion
+//#region src/testing/agent-adapter.d.ts
+/** The user whose subject resolver throws. */
+export declare const AGENT_THROWING_USER = "throws";
+/** The project id whose loader throws. */
+export declare const AGENT_THROWING_ROW = "throws";
+type AgentToolName = "project_read" | "api_keys_revoke_all";
+/**
+ * What a mount wires into its adapter. The subject and the tenant come from
+ * the server-side context the mount builds for each call, never from the
+ * tool arguments.
+ */
+type AgentScenarioDomain = {
+  readonly policy: typeof saasPolicy;
+  /**
+   * The principal for `user` with the plans of `org`, or `null` for an
+   * anonymous call. Throws for `AGENT_THROWING_USER`.
+   */
+  readonly subject: (user: string | null, org: string) => Principal | null;
+  /**
+   * `project_read` loads the row named by `args.id`: `null` for an unknown
+   * id, a throw for `AGENT_THROWING_ROW`. `api_keys_revoke_all` needs
+   * approval.
+   */
+  readonly tools: ToolMap & { readonly [K in AgentToolName]: ToolMap[K]; };
+  readonly customRoles: RoleSource;
+  readonly store: ApprovalStore;
+};
+type AgentCall = {
+  /** `null` for a call with no authenticated user. */
+  readonly user: string | null;
+  readonly org: string;
+  readonly tool: AgentToolName;
+  readonly args: {
+    readonly id?: string;
+  };
+};
+type AgentOutcome = "granted" | "denied" | "approval-required";
+type AgentMounted = {
+  /** Runs one tool call through the adapter's own entry and reports its outcome. */
+  readonly call: (call: AgentCall) => Promise<AgentOutcome>;
+  readonly close?: () => Promise<void> | void;
+};
+type AgentScenarioName = "granted" | "denied" | "cross-tenant" | "anonymous" | "subject-throws" | "loader-throws" | "missing-row" | "approval-required";
+type AgentAdapterOptions = {
+  readonly name: string;
+  readonly mount: (domain: AgentScenarioDomain) => AgentMounted | Promise<AgentMounted>;
+  /** Scenarios the adapter cannot express, each with a reason. */
+  readonly skip?: Readonly<Partial<Record<AgentScenarioName, string>>>;
+};
+/**
+ * Runs the same tool calls through an agent adapter: a grant, the denials an
+ * attacker or an outage produces, and an approval. Every failure denies.
+ */
+export declare function testAgentAdapter(options: AgentAdapterOptions): void;
+//#endregion
 //#region src/testing/authzen.d.ts
 type Entity = {
   readonly type: string;
@@ -467,6 +523,8 @@ export declare function testMembershipSource(source: MembershipSource, options:
   readonly expect?: Record<string, readonly Membership[]>;
   /** With the policy, every membership must name one of its scopes and carry its parent ids. */
   readonly policy?: Policy;
+  /** Passed to every `membershipsFor`; a source keyed by tenant answers nothing without one. */
+  readonly tenant?: string;
 }): void;
 /**
  * A `RelationSource` answers facts only: well-formed chains nearest first and
@@ -502,6 +560,11 @@ export declare function testRoleSource(source: RoleSource, options: {
   readonly declared: readonly (string | Role)[];
   /** When set, every custom role's `grants` must resolve inside the ceiling. */
   readonly policy?: Policy;
+  /**
+   * Names of every custom role the tenant has. When set, `rolesFor` must
+   * return each of them with nothing held, as role management needs.
+   */
+  readonly every?: readonly string[];
 }): void;
 export declare function testLimitStore(store: LimitStore): void;
 export declare function testDecisionSink(sink: DecisionSink): void;
@@ -554,9 +617,17 @@ export declare function testCredentialVerifier(verifier: CredentialVerifier, opt
 export declare function testTokenSigner(signer: TokenSigner, options: {
   readonly verifier: TokenVerifier;
 }): void;
+type WhereRow = Readonly<Record<string, unknown>>;
+/**
+ * `matches` answers whether the compiled output selects `row`, for example
+ * by running it against a table holding only that row. With it, every case
+ * must select the rows the in-memory evaluator keeps, including rows whose
+ * fields are NULL.
+ */
 export declare function testWhereCompiler<TTarget>(compiler: WhereCompiler<TTarget>, options: {
   readonly target: TTarget;
   readonly isFailClosed?: (compiled: unknown) => boolean;
+  readonly matches?: (compiled: unknown, row: WhereRow) => boolean | Promise<boolean>;
 }): void;
 //#endregion
 //#region src/testing/jwt-fixtures.d.ts
@@ -588,14 +659,14 @@ export declare const jwtFixtureTokens: {
 /**
  * Claim sets in the shape the Supabase custom access token hook produces (the RBAC guide's
  * `user_role` claim, optionally mirrored into `app_metadata`, plus a `memberships` array for
- * multi-org apps). `betterSupabase` is the canonical shape better-supabase 0.5 emits: scoped
- * memberships, `tenant_id` and per-tenant plans in `features`. `full` sets every field of the
+ * multi-org apps). `tenantPlans` has scoped memberships, `tenant_id` and per-tenant plans in
+ * `features`, read with `plans: 'features'`. `full` sets every field of the
  * claim contract plus a `hook.claims` extra claim; `portalContact`, `oauthClient` and
  * `actChain` cover a customer contact, a Supabase OAuth server token and an RFC 8693 chain.
  * `supportSession`, `supportSessionReadOnly` and `impersonation` are the `act.kind` tokens
- * better-supabase mints; `anonymousSignIn` is a `signInAnonymously()` token read with
+ * of a support tool; `anonymousSignIn` is a `signInAnonymously()` token read with
  * `anonymousSignIns: 'deny'`. Every fixture passes `supabaseClaims()` and
- * `schemas/supabase-claims-v1.json`. Plain data: no Supabase or better-supabase types.
+ * `schemas/supabase-claims-v1.json`. Plain data: no Supabase types.
  */
 type SupabaseClaimFixture = {
   readonly claims: Readonly<Record<string, unknown>>;
@@ -643,14 +714,32 @@ type SupabaseClaimFixture = {
     };
   };
 };
-type SupabaseClaimFixtureName = "topLevelRole" | "appMetadataRole" | "nullTopLevelFallsBack" | "arrayRoles" | "missingRole" | "nullRole" | "userMetadataIgnored" | "multiOrg" | "betterSupabase" | "full" | "portalContact" | "oauthClient" | "actChain" | "supportSession" | "supportSessionReadOnly" | "impersonation" | "anonymousSignIn" | "anon" | "serviceRole";
+type SupabaseClaimFixtureName = "topLevelRole" | "appMetadataRole" | "nullTopLevelFallsBack" | "arrayRoles" | "missingRole" | "nullRole" | "userMetadataIgnored" | "multiOrg" | "tenantPlans" | "full" | "portalContact" | "oauthClient" | "actChain" | "supportSession" | "supportSessionReadOnly" | "impersonation" | "anonymousSignIn" | "anon" | "serviceRole";
 export declare const supabaseClaimFixtures: Readonly<Record<SupabaseClaimFixtureName, SupabaseClaimFixture>>;
+/**
+ * `supabaseClaimFixtures` as a `supabase/sdk` conformance vector file
+ * (`schema/conformance.schema.json`): each case's `input` is a verified
+ * `getClaims()` payload and the `subjectFromSupabase` options, `expected` the
+ * subject fields it maps to. `JSON.stringify` it for a port in another language.
+ */
+type SupabaseClaimVectors = {
+  readonly feature: "auth.session.get_claims";
+  readonly cases: readonly {
+    readonly name: string;
+    readonly input: {
+      readonly claims: SupabaseClaimFixture["claims"];
+      readonly options?: SupabaseClaimFixture["options"];
+    };
+    readonly expected: SupabaseClaimFixture["expect"];
+  }[];
+};
+export declare const supabaseClaimVectors: SupabaseClaimVectors;
 /**
  * The `permdock supabase inspect --json` manifest for a policy with one
  * `tenant` scope, the default `supabase.hook` and a `features` claim from
- * `better_supabase.feature_claims`. A package that reads the manifest tests its
+ * `public.feature_claims`. A package that reads the manifest tests its
  * parser against this value.
  */
 export declare const supabaseHookManifestFixture: SupabaseHookManifest;
 //#endregion
-export { type ApprovalStoreOptions, type AuthZenEvaluationVector, type AuthZenEvaluationsVector, type AuthZenSearchVector, type AuthZenVectors, type ClientParityCase, type ClientParityOptions, type ClientStoreFactory, type ClientStoreFactoryOptions, type ClientStoreHandle, type ClientStorePermDock, type ClientStoreStatus, type DescribePolicyConfig, type HttpAdapterOptions, type HttpCall, type HttpMounted, type HttpOp, type HttpResult, type HttpScenarioDomain, type HttpScenarioName, type MatrixCell, type MatrixOutcome, type OrmParityCase, type OrmParityOptions, type OrmParityReport, type OrmParityRunInput, type OrmParityScenario, type RlsDbOutcome, type RlsFieldsOutcome, type RlsParityCase, type RlsParityFixture, type RlsParityOptions, type RlsParityReport, type RlsParitySubject, type RlsQueryFn, type RlsQueryResult, type SupabaseClaimFixture, type SupabaseClaimFixtureName, type TestAuthZenOptions, expectTypeOf, supabaseMembershipsBudget };
+export { type AgentAdapterOptions, type AgentCall, type AgentMounted, type AgentOutcome, type AgentScenarioDomain, type AgentScenarioName, type AgentToolName, type ApprovalStoreOptions, type AuthZenEvaluationVector, type AuthZenEvaluationsVector, type AuthZenSearchVector, type AuthZenVectors, type ClientParityCase, type ClientParityOptions, type ClientStoreFactory, type ClientStoreFactoryOptions, type ClientStoreHandle, type ClientStorePermDock, type ClientStoreStatus, type DescribePolicyConfig, type HttpAdapterOptions, type HttpCall, type HttpMounted, type HttpOp, type HttpResult, type HttpScenarioDomain, type HttpScenarioName, type MatrixCell, type MatrixOutcome, type OrmParityCase, type OrmParityOptions, type OrmParityReport, type OrmParityRunInput, type OrmParityScenario, type RlsDbOutcome, type RlsFieldsOutcome, type RlsParityCase, type RlsParityFixture, type RlsParityOptions, type RlsParityReport, type RlsParitySubject, type RlsQueryFn, type RlsQueryResult, type SupabaseClaimFixture, type SupabaseClaimFixtureName, type SupabaseClaimVectors, type TestAuthZenOptions, expectTypeOf, supabaseMembershipsBudget };