permdock 0.1.0 → 0.2.0

package/dist/sources-BcJgw0lt.d.ts

@@ -0,0 +1,192 @@
+import { gt as MembershipSource } from "./policy-CFZAr_Al.js";
+import { n as RoleThrough, y as SupabaseSuspension } from "./types-yF5LmQVD.js";
+import { o as SupabaseManifestMembership } from "./manifest-uDS9y5de.js";
+//#region src/supabase/roles.d.ts
+/** A roles table a role column references, by `schema.table`. */
+type RoleKeys = {
+  readonly table: string;
+  /** The roles table column the reference points at. */
+  readonly id: string;
+  /** The roles table column holding the role key. */
+  readonly key: string;
+  /** The referencing table's column. */
+  readonly ref: string;
+};
+//#endregion
+//#region src/supabase/sources.d.ts
+/**
+ * Runs one parameterised statement: `pg`'s `client.query` (which resolves
+ * `{ rows }`) and `postgres`'s `sql.unsafe` (which resolves the rows) both fit.
+ */
+type SqlQuery = (text: string, values: readonly unknown[]) => Promise<readonly Record<string, unknown>[] | {
+  readonly rows: readonly Record<string, unknown>[];
+}>;
+type Common = {
+  readonly table: string;
+  /** Runs the lookups; without it the source only describes SQL (for `permdock supabase hook generate`). */
+  readonly query?: SqlQuery;
+  /** Drop suspended users and memberships under suspended instances, like `rls.suspension`. */
+  readonly suspension?: SupabaseSuspension;
+};
+type MembershipTableOptions = Common & {
+  /** Column names; `user`, `scope`, `id` and `role` default to `user_id`, `scope`, `scope_id`, `role`. */
+  readonly columns?: {
+    /** The user id column, or a reference to a table that holds the user id. */
+    readonly user?: string | RoleThrough;
+    readonly scope?: string;
+    readonly id?: string;
+    /** A `jsonb` column of ancestor ids keyed by scope name. */
+    readonly within?: string;
+    /**
+     * The role key column, a reference to a roles table that holds the key,
+     * or several of them: the row holds every non-null key.
+     */
+    readonly role?: string | RoleThrough | readonly (string | RoleThrough)[];
+    readonly via?: string;
+    readonly expiresAt?: string;
+    readonly disabledAt?: string;
+    /** The principal id that wrote the membership (`grantedBy`). */
+    readonly grantedBy?: string;
+    /** Free-text justification recorded on the membership (`reason`). */
+    readonly reason?: string;
+    /** A subgroup column filling `member.group`. */
+    readonly group?: string;
+    /** A text column; the value `idp` marks the row as owned by the identity provider. */
+    readonly managedBy?: string;
+    /** A `text[]` column of seats. */
+    readonly seats?: string;
+  };
+};
+type MembershipJunctionOptions = Common & {
+  /** The declared scope every row is a membership of. */
+  readonly scope: string;
+  /** The user id column (default `user_id`), or a reference to a table that holds the user id. */
+  readonly user?: string | RoleThrough;
+  /** The column holding the scope instance id. Default `<scope>_id`. */
+  readonly id?: string;
+  /** Ancestor id columns keyed by scope name. */
+  readonly within?: Readonly<Record<string, string>>;
+  /**
+   * A role column, a reference to a roles table that holds the key, fixed
+   * roles every row holds (a contact table with no role column), or
+   * `{ sources }`: several role columns whose non-null keys the row holds.
+   */
+  readonly roles: string | RoleThrough | readonly string[] | {
+    readonly sources: readonly (string | RoleThrough)[];
+  };
+  /** The membership kind every row has (`contact`, `staff`, `partner`). */
+  readonly via?: string;
+  readonly expiresAt?: string;
+  readonly disabledAt?: string;
+  /** The principal id that wrote the membership (`grantedBy`). */
+  readonly grantedBy?: string;
+  /** Free-text justification recorded on the membership (`reason`). */
+  readonly reason?: string;
+  /** A subgroup filling `member.group`: a fixed name every row has, or a column. */
+  readonly group?: string | {
+    readonly column: string;
+  };
+  /** `idp` when the identity provider owns every row, or a text column holding `idp` per row. */
+  readonly managedBy?: "idp" | {
+    readonly column: string;
+  };
+  /** A `text[]` column of seats. */
+  readonly seats?: string;
+};
+/** What `permdock supabase hook generate` compiles; the same SQL the source runs. */
+type MembershipSql = {
+  readonly table: string;
+  /** The table's user column: the user id, or with `userThrough` the reference to the row holding it. */
+  readonly user: string;
+  /** The table that holds the user id when `user` references it; a change of that id bumps the old and the new user. */
+  readonly userThrough?: RoleKeys;
+  /** `<table>.<user>%type`: the PL/pgSQL type of the user id column, for a variable `select` compares with. */
+  readonly userType: string;
+  /**
+   * The `select` of claim rows for one user, with every filter applied.
+   * `user` must have the column's type (a `userType` variable, or an untyped
+   * `$1` Postgres infers): the column is compared uncast so its index applies.
+   * `keep` adds the `keep` column; it defaults to `keeps`, and a `union`
+   * with a source that keeps passes `true`.
+   */
+  select(user: string, keep?: boolean): string;
+  /** The `select` of member rows for one scope instance (`$1` scope, `$2` id). */
+  list(keep?: boolean): string;
+  /** A suspended scope on the source keeps permissions: rows of its suspended instances stay, with a `keep` column. */
+  readonly keeps: boolean;
+  /** A text column holding `idp` for rows the identity provider owns; `''` when every row is owned. */
+  readonly managed?: string;
+  /** Other tables the `select` reads (suspension tables). */
+  readonly reads: readonly string[];
+  /** The roles table the role column references; a key change bumps every holder's authorization version. */
+  readonly through?: RoleKeys;
+  /** Every roles table the role columns reference, `through` first. */
+  readonly throughs: readonly RoleKeys[];
+  /** Every column that decides who holds which membership: user, scope, id, `within`, role, `via` and expiry. */
+  readonly columns: readonly string[];
+  /** For a single-scope source: its scope and the scopes whose ids each row carries. */
+  readonly scope?: string;
+  readonly holds?: readonly string[];
+  /** The source's entry in the hook manifest's `memberships`. */
+  readonly manifest: SupabaseManifestMembership;
+  /** What the ownership triggers count; absent on a source that is not a table. */
+  readonly holders?: MembershipHolders;
+};
+/**
+ * The rows of a membership table, for the holder-count and transfer-only
+ * triggers `permdock rls generate` puts on it. No suspension filter: a
+ * suspended holder still holds the role.
+ */
+type MembershipHolders = {
+  /** `<table>.<id column>%type`: the type of a variable `rows` compares the id column with. */
+  readonly idType: string;
+  /** The instance id of scope `scope` the PL/pgSQL record `row` holds, as text; null on a row of another scope. */
+  id(scope: string, row: string): string;
+  /**
+   * `select id, user_id, role, via, live` over the rows of scope `scope`
+   * in `from` (default the table): one row per held role key, `live` false
+   * once expired. `id` is an expression of `idType` the id column must equal.
+   */
+  rows(scope: string, options?: {
+    readonly id?: string;
+    readonly from?: string;
+  }): string;
+};
+type SqlMembershipSource = MembershipSource & {
+  readonly sql: MembershipSql;
+};
+/** The part of `@supabase/server`'s `PostgresApi` a `SqlQuery` needs. */
+type SupabasePostgres = {
+  readonly queryRaw: (text: string, params?: unknown[]) => Promise<readonly Record<string, unknown>[]>;
+};
+/**
+ * `ctx.postgres` (from `withPostgresClient`) or `ctx.postgresAdmin` as a
+ * `SqlQuery` for `fromTable`, `fromJunction` and `supabaseApprovalStore`.
+ * `ctx.postgres` runs as the caller under RLS, so the membership tables must
+ * be readable by `authenticated`; `ctx.postgresAdmin` bypasses RLS.
+ */
+declare function fromSupabasePostgres(postgres: SupabasePostgres): SqlQuery;
+/**
+ * Memberships from one table holding every scope: a row per user, scope,
+ * instance and role (`user_id, scope, scope_id, role`), with optional
+ * `within`, `via`, expiry, owner and seat columns. Rows of the same instance
+ * merge into one membership.
+ */
+declare function fromTable(options: MembershipTableOptions): SqlMembershipSource;
+/**
+ * Memberships from a table of one scope (`customer_contacts`): every row is a
+ * membership of `scope`, with roles from a column or fixed (`['contact']`), a
+ * fixed `via`, and ancestor ids from `within` columns.
+ */
+declare function fromJunction(options: MembershipJunctionOptions): SqlMembershipSource;
+declare const AUTHZ_VERSION_TABLE = "permdock_authz_version";
+/**
+ * Reads the authorization version `permdock supabase hook generate` keeps in
+ * `<schema>.permdock_authz_version`: pass it to `claimsFirst(sources, { version })`.
+ */
+declare function authzVersion(options: {
+  readonly query: SqlQuery;
+  readonly schema?: string;
+}): NonNullable<MembershipSource["version"]>;
+//#endregion
+export { MembershipTableOptions as a, SupabasePostgres as c, fromSupabasePostgres as d, fromTable as f, MembershipSql as i, authzVersion as l, MembershipHolders as n, SqlMembershipSource as o, MembershipJunctionOptions as r, SqlQuery as s, AUTHZ_VERSION_TABLE as t, fromJunction as u };

package/dist/{sql-Bll1d7y0.js → sql-xdg5f4Fi.js}

@@ -18,5 +18,10 @@ function quoteSqlLiteral(value) {
 function escapeSqlIdent(name) {
 	return `"${name.replaceAll("\"", "\"\"")}"`;
 }
+const PLAIN_IDENT = /^[a-z_][a-z0-9_]*$/u;
+/** An identifier left bare when it is already lower snake case, otherwise quoted by `escapeSqlIdent`. */
+function sqlIdent(name) {
+	return PLAIN_IDENT.test(name) ? name : escapeSqlIdent(name);
+}
 //#endregion
-export { quoteSqlTable as a, quoteSqlLiteral as i, escapeSqlIdent as n, quoteSqlIdent as r, SQL_IDENT as t };
+export { quoteSqlTable as a, quoteSqlLiteral as i, escapeSqlIdent as n, sqlIdent as o, quoteSqlIdent as r, SQL_IDENT as t };

package/dist/{src-CTNT-PBW.js → src-CSbUiozF.js}

@@ -1,13 +1,16 @@
 import { t as compact } from "./compact-y6vfu2_f.js";
-import { n as freezeDeep } from "./freeze-y1_jQL4v.js";
-import { _ as assertSqlFunctionArg, g as assertPortableTwin, h as normalizeWhere, s as grantList, v as assertSqlFunctionName } from "./policy-ANp36PnI.js";
-import { f as tenantOf, u as scopeList } from "./scopes-cKVp_WTw.js";
-import { C as listPlans, s as flattenGrantee } from "./grantee-Bv04_Vzf.js";
-import { l as canonicalJson } from "./snapshot-DE8dE_hz.js";
-import { f as tenantsOf } from "./validity-D0uRmJKJ.js";
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+import { i as findPermission } from "./permissions-DVoF6dMt.js";
+import { b as assertSqlFunctionArg, i as declaredRoleNames, s as grantList, u as levelNames, v as normalizeWhere, x as assertSqlFunctionName, y as assertPortableTwin } from "./policy-xyWg7QdR.js";
+import { d as scopeList, m as tenantOf } from "./scopes-CVdPrWN-.js";
+import { r as snapshotGrant, t as buildSnapshot } from "./snapshot-Enxd0n-s.js";
+import { T as listPlans, s as flattenGrantee } from "./grantee-Cv5Sogfv.js";
+import { t as canonicalJson } from "./canonical-json-DemiK4Vp.js";
 import { n as sha256, t as bytesToBase64Url } from "./sha256-BO0swRXL.js";
+import { g as tenantsOf } from "./validity-uOp8UpYn.js";
 import { n as isThenable } from "./thenable-okc2xDsj.js";
-import { i as snapshotOf, n as resolveSubject, o as declaredRoleNames, r as collectSnapshotGrants } from "./permdock-yoZ7EjxX.js";
+import { a as collectSnapshotGrants, c as rankRoles, l as usesAssigns, m as ceilingGrants, n as resolveSubject, o as snapshotOf, s as snapshotScopes, u as declaredRoleNames$1, y as resolveCustomRole } from "./permdock-CzqXjCpU.js";
+import { n as LOCAL_CUSTOM_ROLE } from "./parse-local-manifest-BrMozJCo.js";
 //#region src/conditions/sql-function.ts
 function sqlFunction(name, options) {
 	assertSqlFunctionName(name);
@@ -35,6 +38,41 @@ function memorySettings(settings) {
 		return byTenant.get(tenant);
 	} });
 }
+/** Memberships keyed by principal id; `tenant` is not a filter, as for a database source. */
+function memoryMembershipSource(entries) {
+	const byPrincipal = new Map(Object.entries(entries));
+	return Object.freeze({
+		membershipsFor(principal) {
+			return [...byPrincipal.get(principal.id) ?? []];
+		},
+		list(query) {
+			const members = [];
+			for (const [id, memberships] of byPrincipal) for (const membership of memberships) if (membership.scope === query.scope && membership.id === query.id) members.push({
+				principal: { id },
+				membership
+			});
+			return members;
+		}
+	});
+}
+/** A snapshot held in memory; `set` replaces it and notifies every subscriber. */
+function memorySnapshotSource(initial) {
+	let current = initial;
+	const listeners = /* @__PURE__ */ new Set();
+	return Object.freeze({
+		get: () => current,
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		set(snapshot) {
+			current = snapshot;
+			for (const listener of listeners) listener();
+		}
+	});
+}
 function memoryRoleSource(customRoles) {
 	const byTenant = /* @__PURE__ */ new Map();
 	const global = [];
@@ -49,10 +87,10 @@ function memoryRoleSource(customRoles) {
 	}
 	return {
 		rolesFor(tenant) {
-			return byTenant.get(tenant) ?? [];
+			return [...byTenant.get(tenant) ?? []];
 		},
 		globalRoles() {
-			return global;
+			return [...global];
 		}
 	};
 }
@@ -91,6 +129,83 @@ function fromStripeEntitlements(options) {
 	} };
 }
 //#endregion
+//#region src/core/local-manifest.ts
+/** A relation grantee needs the relation graph, which a device does not hold: the grant decides on the server only. */
+function localGrant(grant) {
+	const relational = flattenGrantee(grant.to).some((item) => item.kind === "relation");
+	return snapshotGrant(relational ? {
+		...grant,
+		portable: false
+	} : grant, void 0);
+}
+function customTable(policy, scope, roles) {
+	const keys = [...new Set(ceilingGrants(policy, scope).map((grant) => grant.permission.key))];
+	if (keys.length === 0) return;
+	const resolve = (body) => resolveCustomRole(policy, scope === "global" ? {
+		name: LOCAL_CUSTOM_ROLE,
+		scope: "global",
+		...body
+	} : {
+		name: LOCAL_CUSTOM_ROLE,
+		tenant: LOCAL_CUSTOM_ROLE,
+		scope,
+		...body
+	}).grants.map(localGrant);
+	const permissions = {};
+	for (const key of keys) {
+		const leaf = findPermission(policy.permissions, key);
+		const names = leaf?.kind === "instance" ? levelNames(policy, leaf.resource) : [];
+		permissions[key] = compact({
+			all: resolve({ grants: [{ permission: key }] }),
+			levels: names.length === 0 ? void 0 : Object.fromEntries(names.map((level) => [level, resolve({ grants: [{
+				permission: key,
+				level
+			}] })]))
+		});
+	}
+	const includes = {};
+	for (const role of roles) {
+		const grants = resolve({ includes: [role] });
+		if (grants.length > 0) includes[role] = grants;
+	}
+	return {
+		permissions,
+		includes
+	};
+}
+/**
+* What the policy grants, as JSON a device turns into snapshots from its own
+* membership rows (`localSnapshot` in `permdock/react-native`). Write it at
+* build time; the policy itself never ships to the client.
+*/
+function localSnapshotManifest(policy) {
+	const roles = [...declaredRoleNames(policy)].toSorted();
+	const custom = {};
+	for (const scope of [...scopeList(policy.scopes).map((item) => item.name), "global"]) {
+		const table = customTable(policy, scope, roles);
+		if (table !== void 0) custom[scope] = table;
+	}
+	const scopes = snapshotScopes(policy);
+	const { vocabulary } = buildSnapshot({
+		subject: {
+			principal: null,
+			context: {}
+		},
+		roles: [],
+		grants: [],
+		vocabulary: policy.vocabulary
+	});
+	return freezeDeep(compact({
+		v: 1,
+		scopes,
+		vocabulary,
+		roles,
+		rank: usesAssigns(policy) ? rankRoles(policy, roles) : void 0,
+		grants: grantList(policy).map(localGrant),
+		custom
+	}));
+}
+//#endregion
 //#region src/core/may-access.ts
 function policyPlans(policy) {
 	const names = new Set(listPlans(policy.vocabulary?.plans).map((p) => p.key));
@@ -114,7 +229,7 @@ function mayAccess(policy, user, permission, options = {}) {
 		const principal = resolved.principal;
 		const relevant = policy.index.grantsByKey.get(permission.key) ?? [];
 		if (principal !== null) {
-			const declared = declaredRoleNames(policy);
+			const declared = declaredRoleNames$1(policy);
 			if (heldRoleNames(principal).some((name) => !declared.has(name))) return true;
 			if ((principal.memberships ?? []).length === 0 && relevant.some((grant) => grant.scope !== "global")) return true;
 		}
@@ -138,6 +253,29 @@ function mayAccess(policy, user, permission, options = {}) {
 	}
 }
 //#endregion
+//#region src/core/custom-role-source.ts
+function ofTenant(tenant, roles) {
+	return Array.isArray(roles) ? roles.filter((role) => role !== null && typeof role === "object" && Reflect.get(role, "tenant") === tenant) : [];
+}
+/**
+* A `RoleSource` over a reader that returns every custom role of a tenant.
+* It keeps only the roles of the requested tenant. With `read: 'held'` it
+* skips a tenant's read, and `globalRoles`, when the subject holds only
+* declared roles there.
+*/
+function customRoleSource(reader, options = {}) {
+	const declared = options.read === "held" ? declaredRoleNames(options.policy) : void 0;
+	return Object.freeze({
+		rolesFor(tenant, context) {
+			if (declared !== void 0 && context?.held.every((name) => declared.has(name)) === true) return [];
+			const roles = reader.rolesOf(tenant);
+			return isThenable(roles) ? roles.then((list) => ofTenant(tenant, list)) : ofTenant(tenant, roles);
+		},
+		...reader.assignable === void 0 ? {} : { assignable: (tenant) => reader.assignable?.(tenant) ?? [] },
+		...reader.globalRoles === void 0 ? {} : { globalRoles: (context) => declared !== void 0 && context?.held.every((name) => declared.has(name)) === true ? [] : reader.globalRoles?.() ?? [] }
+	});
+}
+//#endregion
 //#region src/core/snapshot-for.ts
 function withPlans(subject, plans) {
 	if (plans === void 0 || subject.principal === null) return subject;
@@ -427,4 +565,4 @@ function catalogFingerprint(catalog) {
 	return bytesToBase64Url(sha256(canonicalJson(fingerprintInput(catalog))));
 }
 //#endregion
-export { accessToOcsf as a, readable as c, mayAccess as d, fromStripeEntitlements as f, sqlFunction as g, memorySettings as h, OCSF_VERSION as i, writable as l, memoryRoleSource as m, CSV_COLUMNS as n, toOcsf as o, memoryEntitlementSource as p, toCsvRow as r, crud as s, catalogFingerprint as t, snapshotFor as u };
+export { memoryRoleSource as _, accessToOcsf as a, sqlFunction as b, readable as c, customRoleSource as d, mayAccess as f, memoryMembershipSource as g, memoryEntitlementSource as h, OCSF_VERSION as i, writable as l, fromStripeEntitlements as m, CSV_COLUMNS as n, toOcsf as o, localSnapshotManifest as p, toCsvRow as r, crud as s, catalogFingerprint as t, snapshotFor as u, memorySettings as v, memorySnapshotSource as y };

package/dist/ssf/index.d.ts

@@ -1,3 +1,4 @@
-import { a as ReplayStore, c as SsfEventHandler, d as SsfOnEvent, f as SsfPermDock, g as SsfSubjectMapper, h as SsfSubject, i as PollResult, l as SsfEventInput, m as SsfReceiver, n as PollHandle, o as SetSubject, p as SsfPermDockOptions, r as PollOptions, s as SsfAuditEvent, t as CaepEventName, u as SsfEventListener } from "../types-i4BAOvdb.js";
-import { n as createPermDock, t as memoryReplayStore } from "../index-fG6NSXlc.js";
+import { C as SsfPermDock, D as SsfSubjectMapper, E as SsfSubject, S as SsfOnEvent, T as SsfReceiver, _ as SetSubject, b as SsfEventInput, f as CaepEventName, g as ReplayStore, h as PollResult, m as PollOptions, p as PollHandle, v as SsfAuditEvent, w as SsfPermDockOptions, x as SsfEventListener, y as SsfEventHandler } from "../types-9AWO9EGt.js";
+import { t as memoryReplayStore } from "../replay-sqBGMnNs.js";
+import { t as createPermDock } from "../index-CtE07CBF.js";
 export { type CaepEventName, type PollHandle, type PollOptions, type PollResult, type ReplayStore, type SetSubject, type SsfAuditEvent, type SsfEventHandler, type SsfEventInput, type SsfEventListener, type SsfOnEvent, type SsfPermDock, type SsfPermDockOptions, type SsfReceiver, type SsfSubject, type SsfSubjectMapper, createPermDock, memoryReplayStore };

package/dist/ssf/index.js

@@ -1,6 +1,7 @@
 import { t as compact } from "../compact-y6vfu2_f.js";
-import { t as cancelApprovals } from "../helpers-DnSOrhB9.js";
-import { i as issuerFromDiscovery, t as joseTokenVerifier } from "../verifier-B90agnhl.js";
+import { t as cancelApprovals } from "../helpers-H_KARDVC.js";
+import { i as issuerFromDiscovery, t as joseTokenVerifier } from "../verifier-BxBo6I44.js";
+import { t as memoryReplayStore } from "../replay-BsOyTrdV.js";
 import { t as timeoutSignal } from "../timeout-D51niuQP.js";
 //#region src/ssf/wire.ts
 const SET_TYP = "secevent+jwt";
@@ -564,33 +565,6 @@ function createReceiver(config) {
 	};
 }
 //#endregion
-//#region src/ssf/replay.ts
-function memoryReplayStore() {
-	const seen = /* @__PURE__ */ new Map();
-	function evict(now = Date.now() / 1e3) {
-		for (const [jti, expiresAt] of seen) if (expiresAt !== void 0 && expiresAt <= now) seen.delete(jti);
-	}
-	return {
-		seen(jti) {
-			evict();
-			return seen.has(jti);
-		},
-		remember(jti, expiresAt) {
-			evict();
-			seen.set(jti, expiresAt);
-		},
-		claim(key, expiresAt) {
-			evict();
-			if (seen.has(key)) return false;
-			seen.set(key, expiresAt);
-			return true;
-		},
-		release(key) {
-			seen.delete(key);
-		}
-	};
-}
-//#endregion
 //#region src/ssf/create.ts
 function createPermDock(policy, options) {
 	if (typeof options.subject !== "function") throw new TypeError("PermDock: permdock/ssf requires subject.");