permdock 0.0.0 → 0.2.0

package/dist/manifest-uDS9y5de.d.ts

@@ -0,0 +1,206 @@
+//#region src/supabase/manifest.d.ts
+/**
+ * What `permdock supabase inspect --json` prints and `--out` writes to
+ * `permdock.manifest.json`: the contract between the generated hook and SQL
+ * helpers and a package that writes policies or claims next to them.
+ * `version` is the major of this shape; a field is only
+ * ever added within it. `schemas/supabase-manifest-v1.json` is its JSON Schema.
+ */
+type SupabaseHookManifest = {
+  readonly $schema: "https://permdock.com/schemas/supabase-manifest-v1.json";
+  readonly version: 1;
+  readonly hook: {
+    readonly schema: string;
+    readonly function: "custom_access_token_hook";
+    readonly out: string;
+    readonly before?: readonly string[];
+  };
+  readonly helpers: {
+    readonly schema: string;
+    /**
+     * `permdock_has` and, per declared scope, `permitted_<scope>_ids`, each
+     * `(p_grant text)`, the membership-only `member_<scope>_ids()` and, for a
+     * scope with a membership source, `member_<scope>_ids_for(p_user uuid)`.
+     */
+    readonly functions: readonly string[];
+  };
+  readonly tenantClaim: string;
+  readonly budget: {
+    readonly bytes: number;
+    readonly measure: string;
+  };
+  readonly claims: readonly SupabaseHookClaim[];
+  readonly authzVersion: boolean;
+  /**
+   * With `authzVersion`, the function that bumps the listed users' `authz_ver`,
+   * for a membership source outside the hook. It is `security definer` and no
+   * client role may execute it: call it from a trigger owned by the table's owner.
+   */
+  readonly authzVersionBump?: {
+    readonly schema: string;
+    readonly function: "permdock_bump_authz_version_for";
+    readonly args: "p_users uuid[]";
+  };
+  /** The `supabase.hook.memberships` sources, in the order the hook reads them. */
+  readonly memberships: readonly SupabaseManifestMembership[];
+  readonly rls: SupabaseManifestRls;
+  /**
+   * Every `schema.table.column` a membership or an `attrs` claim is computed
+   * from. A client role that can insert or update one can grant itself access.
+   */
+  readonly decidingColumns: readonly string[];
+  /** The majors of the `-- permdock:hook` and `-- permdock:grants` marker lines. */
+  readonly markers: {
+    readonly hook: "v1";
+    readonly grants: "v1";
+  };
+  /**
+   * The `supabase/sdk` capability-matrix feature ids the hook, the helpers and
+   * `subjectFromSupabase` depend on, as of the `matrix` release tag. A client
+   * SDK that lacks one cannot serve this policy.
+   */
+  readonly requires?: SupabaseManifestRequires;
+};
+type SupabaseManifestRequires = {
+  /** The capability-matrix release tag, `capability-matrix-v1.<minor>.<patch>`. */
+  readonly matrix: string;
+  /** Sorted three-segment feature ids, such as `auth.session.get_claims`. */
+  readonly capabilities: readonly string[];
+};
+type SupabaseHookClaim = {
+  readonly name: string;
+  /** `permdock`, or the `<schema>.<function>` of a `supabase.hook.claims` entry. */
+  readonly source: string;
+  /** Whether the claim counts toward `budget.bytes`. */
+  readonly budget: boolean;
+};
+type SupabaseManifestColumn = {
+  readonly column: string;
+};
+/** A column of the source table, or a value every row has. */
+type SupabaseManifestValue = SupabaseManifestColumn | {
+  readonly value: string | readonly string[];
+};
+/** A column that references another table: the value (role key or user id) is `column` of `table`, matched on `id`. */
+type SupabaseManifestThrough = {
+  readonly table: string;
+  readonly id: string;
+  readonly column: string;
+};
+/** A role column (with `through` when it references a roles table), or the fixed roles every row holds. */
+type SupabaseManifestRole = SupabaseManifestValue | (SupabaseManifestColumn & {
+  readonly through: SupabaseManifestThrough;
+});
+/** One `fromTable` or `fromJunction` source. */
+type SupabaseManifestMembership = {
+  /** `schema.table`, `public` when the source names no schema. */
+  readonly table: string;
+  /** The user id column, with `through` when it references the table that holds the user id. */
+  readonly user: SupabaseManifestColumn | (SupabaseManifestColumn & {
+    readonly through: SupabaseManifestThrough;
+  });
+  /** A column for `fromTable`, the fixed scope for `fromJunction`. */
+  readonly scope: SupabaseManifestValue;
+  readonly id: SupabaseManifestColumn;
+  /** A role column, the fixed roles every row holds, or several role columns whose keys the row holds together. */
+  readonly role: SupabaseManifestRole | readonly SupabaseManifestRole[];
+  /** A `jsonb` column of ancestor ids keyed by scope, or one column per ancestor scope. */
+  readonly within?: SupabaseManifestColumn | {
+    readonly columns: Readonly<Record<string, string>>;
+  };
+  readonly via?: SupabaseManifestValue;
+  readonly expiresAt?: SupabaseManifestColumn;
+  readonly disabledAt?: SupabaseManifestColumn;
+  /** The columns of `table` that decide the membership. */
+  readonly columns: readonly string[];
+};
+type SupabaseManifestHelper = {
+  readonly name: string;
+  /** The argument list, `p_grant text`, or `''` for none. */
+  readonly args: string;
+  readonly returns: string;
+  /** The roles granted `execute`; a field view `anon` reads adds `anon` to the `authenticated` ones. */
+  readonly execute: readonly string[];
+};
+/** A table whose row says whether a user or a scope instance is active (`rls.suspension`); a missing row counts as suspended. */
+type SupabaseManifestActiveRow = {
+  /** `schema.table`. */
+  readonly table: string;
+  /** The column holding the user id or the scope instance id. */
+  readonly id: string;
+  /** A nullable timestamp column; a row with a value is suspended. */
+  readonly disabledAt?: string;
+  /** A status column; only a row whose value is in `active` is active. */
+  readonly status?: string;
+  readonly active?: readonly string[];
+  /** A scope only: the permission keys members of a suspended instance still hold. */
+  readonly keep?: readonly string[];
+};
+type SupabaseManifestRls = {
+  readonly schema: string;
+  /** Where the helpers read roles and memberships: the claims (`jwt`) or the tables (`database`). */
+  readonly mode: "jwt" | "database";
+  readonly tenantClaim: string;
+  /** The declared scopes, root first, with the Postgres type of their ids. */
+  readonly scopes: readonly {
+    readonly name: string;
+    readonly type: string;
+    readonly within?: string;
+  }[];
+  /**
+   * Every function `rls generate` writes for policies and trusted SQL to
+   * call: `permdock_has`, `permitted_<scope>_ids`, `member_<scope>_ids` and
+   * `permdock_user_id`, the caller's user id; in `database` mode `permdock_has_for`, `permitted_<scope>_ids_for` and
+   * `member_<scope>_ids_for`; and when a role declares `assigns`,
+   * `permdock_can_assign`, `permdock_can_assign_any` and, with custom roles,
+   * `permdock_can_assign_custom_role`, each with its `_for` form where one
+   * is written. A helper whose `execute` is empty is for trusted SQL only.
+   */
+  readonly helpers: readonly SupabaseManifestHelper[];
+  /**
+   * The tables `member_<scope>_ids_for` reads: an `rls.memberships` table
+   * mapped for the scope, else `rls.membershipSources`, else the hook's
+   * `memberships`.
+   */
+  readonly memberships: readonly SupabaseManifestMembership[];
+  /** Whether custom roles live in the helpers' tables (`rls.customRoles` in `database` mode). */
+  readonly customRoles?: boolean;
+  /** The global-roles table the hook and the `database` mode helpers read. */
+  readonly roles?: {
+    readonly table: string;
+    readonly user: SupabaseManifestColumn;
+    readonly role: SupabaseManifestRole | readonly SupabaseManifestRole[];
+  };
+  /** `rls.suspension`: a suspended user, or a suspended scope instance, holds nothing but its scope's `keep`. */
+  readonly suspension?: {
+    readonly users?: SupabaseManifestActiveRow;
+    readonly scopes?: Readonly<Record<string, SupabaseManifestActiveRow>>;
+    readonly memberships?: {
+      readonly keep: readonly string[];
+    };
+  };
+  /**
+   * `rls.assignments`: the tables whose client writes the assignment
+   * triggers check against `permdock_can_assign_any`, so SQL writing rows
+   * there needs no role-ceiling check of its own.
+   */
+  readonly assignments?: {
+    readonly tables: readonly string[];
+  };
+  readonly apiKeys?: {
+    readonly claim: string;
+    readonly scopes: string;
+    readonly tenant: string;
+    readonly roles: string;
+    readonly serviceRoles: readonly string[];
+  };
+};
+/**
+ * Reads a `permdock.manifest.json` document (parsed, or the JSON text) and
+ * validates it against `schemas/supabase-manifest-v1.json`. Returns a
+ * deep-frozen copy built from own keys; throws `PermDockValidationError`
+ * with every issue, so a manifest of another major is refused.
+ */
+declare function parseSupabaseManifest(json: unknown): SupabaseHookManifest;
+//#endregion
+export { SupabaseManifestHelper as a, SupabaseManifestRls as c, SupabaseManifestValue as d, parseSupabaseManifest as f, SupabaseManifestColumn as i, SupabaseManifestRole as l, SupabaseHookManifest as n, SupabaseManifestMembership as o, SupabaseManifestActiveRow as r, SupabaseManifestRequires as s, SupabaseHookClaim as t, SupabaseManifestThrough as u };

package/dist/map-AcxK9o_D.js

@@ -0,0 +1,147 @@
+import { t as compact } from "./compact-y6vfu2_f.js";
+import { t as itemResourceData } from "./evaluation-items-CfCCejQd.js";
+//#region src/authzen/map.ts
+const UNKNOWN = {
+	outcome: "denied",
+	denials: [{
+		role: null,
+		reason: "no-grant",
+		detail: "unknown-permission"
+	}],
+	alternatives: []
+};
+const UNAVAILABLE = {
+	outcome: "denied",
+	denials: [{
+		role: null,
+		reason: "no-grant",
+		detail: "resource-unavailable"
+	}],
+	alternatives: []
+};
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function actionNameOf(item) {
+	if (typeof item.action?.name === "string") return item.action.name;
+	if (!isRecord(item.action?.properties)) return;
+	const scope = item.action.properties["scope"];
+	return typeof scope === "string" ? scope : void 0;
+}
+function permissionOf(lookup, item) {
+	return lookup(actionNameOf(item), item.resource);
+}
+function resourceData(item) {
+	return itemResourceData(item.resource);
+}
+function resourceIdOf(item) {
+	const id = item.resource?.id;
+	if (typeof id === "string" || typeof id === "number") return String(id);
+}
+function userFromEntity(entity) {
+	if (entity === void 0) return null;
+	const result = {};
+	if (typeof entity.id === "string" || typeof entity.id === "number") result["id"] = String(entity.id);
+	if (isRecord(entity.properties)) for (const [key, value] of Object.entries(entity.properties)) {
+		if (key === "actor" || key === "delegation") continue;
+		result[key] = value;
+	}
+	return Object.keys(result).length === 0 ? null : result;
+}
+function actorOf(item) {
+	const context = isRecord(item.context) ? item.context : {};
+	const fromSubject = isRecord(item.subject?.properties) ? item.subject.properties["actor"] : void 0;
+	const raw = context["actor"] ?? fromSubject;
+	if (!isRecord(raw) || typeof raw["id"] !== "string") return;
+	const kind = typeof raw["kind"] === "string" ? raw["kind"] : "oauth-client";
+	return {
+		id: raw["id"],
+		kind
+	};
+}
+function delegationOf(item) {
+	const context = isRecord(item.context) ? item.context : {};
+	const fromSubject = isRecord(item.subject?.properties) ? item.subject.properties["delegation"] : void 0;
+	const raw = context["delegation"] ?? fromSubject;
+	if (!isRecord(raw)) return;
+	const scopes = raw["scopes"];
+	const authorizationDetails = raw["authorizationDetails"];
+	return compact({
+		scopes: Array.isArray(scopes) ? scopes.filter((scope) => typeof scope === "string") : void 0,
+		authorizationDetails: Array.isArray(authorizationDetails) ? authorizationDetails : void 0
+	});
+}
+function tenantOf(item) {
+	if (!isRecord(item.context) || typeof item.context["tenant"] !== "string") return;
+	return item.context["tenant"];
+}
+function permdockContext(decision) {
+	switch (decision.outcome) {
+		case "granted": return { outcome: "granted" };
+		case "denied": {
+			const unknown = decision.denials.some((denial) => denial.detail === "unknown-permission");
+			return compact({
+				outcome: "denied",
+				denials: decision.denials.map((denial) => ({
+					role: denial.role,
+					reason: denial.reason
+				})),
+				reason: unknown ? "unknown-permission" : void 0
+			});
+		}
+		case "approval-required": return {
+			outcome: "approval-required",
+			token: decision.token
+		};
+		default: return decision;
+	}
+}
+function evaluationContext(decision) {
+	return { permdock: permdockContext(decision) };
+}
+function evaluationRow(decision) {
+	return {
+		decision: decision.outcome === "granted",
+		context: evaluationContext(decision)
+	};
+}
+function pathnameOf(request) {
+	return new URL(request.url).pathname;
+}
+function endsWithPath(pathname, suffix) {
+	return pathname === suffix || pathname.endsWith(suffix);
+}
+function mergeItem(shared, item) {
+	if (!isRecord(item)) return shared;
+	return compact({
+		subject: isRecord(item["subject"]) ? item["subject"] : shared.subject,
+		action: isRecord(item["action"]) ? item["action"] : shared.action,
+		resource: isRecord(item["resource"]) ? item["resource"] : shared.resource,
+		context: item["context"] ?? shared.context
+	});
+}
+function pageOf(body) {
+	const page = isRecord(body["page"]) ? body["page"] : {};
+	const raw = typeof page["token"] === "string" ? page["token"] : typeof page["next_token"] === "string" ? page["next_token"] : "0";
+	const parsed = Math.trunc(Number(raw));
+	const sizeRaw = page["limit"] ?? page["size"];
+	const size = typeof sizeRaw === "number" && sizeRaw > 0 ? Math.min(sizeRaw, 200) : 50;
+	return {
+		offset: Number.isFinite(parsed) && parsed > 0 ? parsed : 0,
+		size
+	};
+}
+function paged(items, offset, size) {
+	const slice = items.slice(offset, offset + size);
+	const next = offset + slice.length;
+	return {
+		results: slice,
+		page: {
+			next_token: next < items.length ? String(next) : "",
+			count: slice.length,
+			total: items.length
+		}
+	};
+}
+//#endregion
+export { endsWithPath as a, mergeItem as c, pathnameOf as d, permissionOf as f, userFromEntity as g, tenantOf as h, delegationOf as i, pageOf as l, resourceIdOf as m, UNKNOWN as n, evaluationRow as o, resourceData as p, actorOf as r, isRecord as s, UNAVAILABLE as t, paged as u };