permdock 0.0.0 → 0.2.0

package/dist/clerk/index.js

@@ -0,0 +1,301 @@
+import { t as compact } from "../compact-y6vfu2_f.js";
+import { n as freezeDeep } from "../freeze-CrU8nQeX.js";
+import { t as ignoreRejection } from "../thenable-okc2xDsj.js";
+import { t as anonymousSubject } from "../subject-C6dLxqHU.js";
+import { c as ttlMs, s as ttlCache } from "../shared-DRu8VFVM.js";
+//#region src/clerk/subject.ts
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function asRoles(value) {
+	if (typeof value === "string") return value === "" ? [] : [value];
+	if (!Array.isArray(value)) return [];
+	return value.filter((item) => typeof item === "string");
+}
+function readPath(record, path) {
+	let current = record;
+	for (const part of path.split(".")) {
+		if (!isRecord(current) || !Object.hasOwn(current, part)) return;
+		current = current[part];
+	}
+	return current;
+}
+function validateClaims(extra, schema) {
+	const result = schema["~standard"].validate(extra);
+	if (result instanceof Promise) {
+		ignoreRejection(result);
+		return;
+	}
+	if ("issues" in result && result.issues !== void 0) return;
+	const value = result.value;
+	return isRecord(value) ? value : void 0;
+}
+const REGISTERED_CLAIMS = /* @__PURE__ */ new Set([
+	"iss",
+	"sub",
+	"aud",
+	"exp",
+	"nbf",
+	"iat",
+	"jti",
+	"sid",
+	"org_id",
+	"org_role",
+	"org_permissions",
+	"org_slug",
+	"pla",
+	"fea",
+	"o",
+	"v"
+]);
+function extraClaims(claims) {
+	const extra = {};
+	for (const [key, value] of Object.entries(claims)) {
+		if (REGISTERED_CLAIMS.has(key) || key === "unsafeMetadata") continue;
+		extra[key] = value;
+	}
+	return extra;
+}
+/**
+* Plan slugs from `pla`, split by owner: `o:` plans belong to the session's
+* organization, everything else (`u:` and unprefixed) to the user.
+*/
+function planSlugs(pla) {
+	const org = [];
+	const user = [];
+	if (typeof pla !== "string" || pla === "") return {
+		org,
+		user
+	};
+	for (const raw of pla.split(",")) {
+		const token = raw.trim();
+		if (token === "") continue;
+		const prefixed = /^([ou]):(.+)$/u.exec(token);
+		const slug = prefixed?.[2] ?? token;
+		if (slug !== "") (prefixed?.[1] === "o" ? org : user).push(slug);
+	}
+	return {
+		org,
+		user
+	};
+}
+function featureRoles(fea, map) {
+	if (map === void 0 || typeof fea !== "string" || fea === "") return {
+		org: [],
+		user: [],
+		sources: {}
+	};
+	const org = [];
+	const user = [];
+	const sources = {};
+	for (const raw of fea.split(",")) {
+		const token = raw.trim();
+		if (token === "") continue;
+		const prefixed = /^([ou]):(.+)$/u.exec(token);
+		const slug = prefixed?.[2] ?? token;
+		const source = prefixed?.[1] === "o" || prefixed?.[1] === "u" ? prefixed[1] : void 0;
+		const role = map[slug];
+		if (role === void 0) continue;
+		(source === "o" ? org : user).push(role);
+		if (source !== void 0) sources[role] = source;
+	}
+	return {
+		org,
+		user,
+		sources
+	};
+}
+function globalRolesFrom(claims, option) {
+	if (option === void 0) return [];
+	if (typeof option === "function") try {
+		return asRoles(option(claims));
+	} catch {
+		return [];
+	}
+	return asRoles(readPath(claims, option));
+}
+function splitList(value) {
+	return typeof value === "string" ? value.split(",").map((item) => item.trim()).filter((item) => item !== "") : [];
+}
+function orgFeatures(fea) {
+	return splitList(fea).map((token) => /^o:(.+)$/u.exec(token)?.[1]).filter((feature) => feature !== void 0);
+}
+/**
+* Session token v2 carries the organization as `o: { id, rol, per, fpm }`:
+* `fpm` holds one bitmask per `o:` feature in `fea`, bit `i` selecting
+* `per[i]`, so a permission key is `org:<feature>:<per[i]>`.
+*/
+function orgClaimsV2(claims) {
+	const org = claims["o"];
+	if (!isRecord(org) || typeof org["id"] !== "string" || org["id"] === "") return;
+	const role = typeof org["rol"] === "string" && org["rol"] !== "" ? org["rol"].startsWith("org:") ? org["rol"] : `org:${org["rol"]}` : void 0;
+	const actions = splitList(org["per"]);
+	const features = orgFeatures(claims["fea"]);
+	const masks = splitList(org["fpm"]).map(Number);
+	const orgPermissions = [];
+	for (const [index, feature] of features.entries()) {
+		const mask = masks[index];
+		if (mask === void 0 || !Number.isSafeInteger(mask) || mask < 0) continue;
+		for (const [bit, action] of actions.entries()) if (bit < 31 && (mask & 1 << bit) !== 0) orgPermissions.push(`org:${feature}:${action}`);
+	}
+	return {
+		tenant: org["id"],
+		orgRole: role,
+		orgPermissions
+	};
+}
+function orgClaimsV1(claims) {
+	return {
+		tenant: typeof claims["org_id"] === "string" ? claims["org_id"] : void 0,
+		orgRole: typeof claims["org_role"] === "string" ? claims["org_role"] : void 0,
+		orgPermissions: asRoles(claims["org_permissions"])
+	};
+}
+function orgClaims(claims) {
+	return orgClaimsV2(claims) ?? orgClaimsV1(claims);
+}
+function isAuthObject(value) {
+	if (!isRecord(value)) return false;
+	return typeof value["has"] === "function" || isRecord(value["sessionClaims"]);
+}
+function isVerifiedPayload(value) {
+	if (!isRecord(value)) return false;
+	if (typeof value["sub"] !== "string" || value["sub"] === "") return false;
+	return typeof value["sid"] === "string" || typeof value["azp"] === "string" || typeof value["org_id"] === "string" || orgClaimsV2(value) !== void 0;
+}
+function fromAuthObject(auth) {
+	const claims = isRecord(auth.sessionClaims) ? { ...auth.sessionClaims } : {};
+	const fromClaims = orgClaims(claims);
+	return {
+		id: typeof auth.userId === "string" ? auth.userId : typeof claims["sub"] === "string" ? claims["sub"] : void 0,
+		tenant: typeof auth.orgId === "string" ? auth.orgId : fromClaims.tenant,
+		orgRole: typeof auth.orgRole === "string" ? auth.orgRole : fromClaims.orgRole,
+		orgPermissions: auth.orgPermissions !== void 0 && auth.orgPermissions !== null ? asRoles(auth.orgPermissions) : fromClaims.orgPermissions,
+		claims,
+		session: typeof auth.sessionId === "string" ? auth.sessionId : typeof claims["sid"] === "string" ? claims["sid"] : void 0
+	};
+}
+function fromPayload(claims) {
+	return {
+		id: typeof claims["sub"] === "string" ? claims["sub"] : void 0,
+		...orgClaims(claims),
+		claims,
+		session: typeof claims["sid"] === "string" ? claims["sid"] : void 0
+	};
+}
+const MEMBERSHIP_PAGE = 100;
+const MEMBERSHIP_PAGES = 50;
+function membershipRow(item, userId) {
+	if (!isRecord(item)) return;
+	const owner = isRecord(item["publicUserData"]) ? item["publicUserData"]["userId"] : void 0;
+	if (typeof owner === "string" && owner !== userId) return;
+	const organization = isRecord(item["organization"]) ? item["organization"] : void 0;
+	const tenant = typeof item["organizationId"] === "string" ? item["organizationId"] : typeof organization?.["id"] === "string" ? organization["id"] : void 0;
+	const roles = asRoles(item["role"]);
+	if (tenant === void 0 || roles.length === 0) return;
+	return compact({
+		tenant,
+		roles
+	});
+}
+/** The memberships Clerk lists for `userId`, or `undefined` when a page fails. */
+async function extraMemberships(backend, userId) {
+	const list = backend?.users?.getOrganizationMembershipList;
+	if (list === void 0) return [];
+	try {
+		const out = [];
+		for (let page = 0; page < MEMBERSHIP_PAGES; page += 1) {
+			const offset = page * MEMBERSHIP_PAGE;
+			const raw = await list({
+				userId,
+				limit: MEMBERSHIP_PAGE,
+				offset
+			});
+			const rows = Array.isArray(raw) ? raw : isRecord(raw) && Array.isArray(raw.data) ? raw.data : [];
+			for (const item of rows) {
+				const row = membershipRow(item, userId);
+				if (row !== void 0) out.push(row);
+			}
+			const total = isRecord(raw) && typeof raw.totalCount === "number" ? raw.totalCount : void 0;
+			if (rows.length < MEMBERSHIP_PAGE || total !== void 0 && offset + rows.length >= total) break;
+		}
+		return out;
+	} catch {
+		return;
+	}
+}
+function subjectFromClerk(authObject, options = {}) {
+	return fromClerk(authObject, options, extraMemberships);
+}
+/**
+* A resolver that keeps each user's `memberships: 'all'` list for
+* `cache.ttl` (at most 30 seconds), so a removed membership grants until then.
+*/
+function createClerkSubjectResolver(options = {}) {
+	const { cache, ...rest } = options;
+	const lists = ttlCache(ttlMs(cache));
+	const load = async (backend, userId) => {
+		const hit = lists.get(userId);
+		if (hit !== void 0) return hit;
+		const loaded = await extraMemberships(backend, userId);
+		if (loaded !== void 0) lists.set(userId, loaded);
+		return loaded;
+	};
+	return (authObject) => fromClerk(authObject, rest, load);
+}
+async function fromClerk(authObject, options, loadMemberships) {
+	try {
+		const trustedObject = isAuthObject(authObject);
+		const trustedPayload = isVerifiedPayload(authObject);
+		if (!trustedObject && !trustedPayload) return anonymousSubject();
+		const mapped = trustedObject ? fromAuthObject(authObject) : fromPayload(authObject);
+		if (mapped.id === void 0 || mapped.id === "") return anonymousSubject();
+		const declared = options.declared;
+		const orgRole = mapped.orgRole !== void 0 && (declared === void 0 || declared.includes(mapped.orgRole)) ? mapped.orgRole : void 0;
+		const permissionRoles = Object.keys(options.permissions ?? {}).filter((key) => mapped.orgPermissions.includes(key));
+		const features = featureRoles(mapped.claims["fea"], options.features);
+		const plans = planSlugs(mapped.claims["pla"]);
+		const membershipRoles = [
+			...orgRole === void 0 ? [] : [orgRole],
+			...permissionRoles,
+			...features.org
+		];
+		const sessionMembership = mapped.tenant !== void 0 && (membershipRoles.length > 0 || plans.org.length > 0) ? [compact({
+			tenant: mapped.tenant,
+			roles: membershipRoles,
+			entitlements: plans.org.length === 0 ? void 0 : plans.org
+		})] : [];
+		const loaded = options.memberships === "all" ? await loadMemberships(options.backend, mapped.id) ?? [] : [];
+		const seen = new Set(sessionMembership.map((item) => item.tenant));
+		const memberships = [...sessionMembership, ...loaded.filter((item) => {
+			if (seen.has(item.tenant)) return false;
+			seen.add(item.tenant);
+			return true;
+		})];
+		let claims = extraClaims(mapped.claims);
+		if (options.schema !== void 0) claims = validateClaims(claims, options.schema) ?? {};
+		const global = [...globalRolesFrom(mapped.claims, options.globalRoles), ...features.user];
+		const exp = mapped.claims["exp"];
+		const principal = compact({
+			id: mapped.id,
+			kind: "user",
+			tenant: mapped.tenant,
+			roles: global,
+			plans: plans.user.length === 0 ? void 0 : plans.user,
+			memberships,
+			clerkPermissions: mapped.orgPermissions,
+			claims: Object.keys(claims).length === 0 ? void 0 : claims,
+			featureSources: Object.keys(features.sources).length === 0 ? void 0 : features.sources
+		});
+		return freezeDeep(compact({
+			principal,
+			context: {},
+			session: mapped.session,
+			expiresAt: typeof exp === "number" ? exp : void 0
+		}));
+	} catch {
+		return anonymousSubject();
+	}
+}
+//#endregion
+export { createClerkSubjectResolver, subjectFromClerk };

package/dist/cli/bin.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cli/bin.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { t as run } from "../run-YXCJDNYk.js";
+import { n as streamHasColors } from "../style-CTm1AXDT.js";
+//#region src/cli/bin.ts
+const result = await run(process.argv.slice(2), {
+	cwd: process.cwd(),
+	io: {
+		env: process.env,
+		stdout: (text) => {
+			process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+		},
+		stderr: (text) => {
+			process.stderr.write(text.endsWith("\n") ? text : `${text}\n`);
+		},
+		color: streamHasColors(process.stdout),
+		interactive: process.stdin.isTTY === true && process.stdout.isTTY === true && process.env["CI"] === void 0
+	}
+});
+process.exitCode ??= result.code;
+//#endregion

package/dist/cli/index.d.ts

@@ -0,0 +1,46 @@
+import { a as CatalogDocument, c as CatalogResource, d as CatalogSupportAccess, f as CatalogUsage, l as CatalogRole, n as CatalogApproval, r as CatalogBreakGlass, s as CatalogPermission, t as CatalogActivation, u as CatalogScope } from "../types-Dnemwd77.js";
+import { _ as RunResult, c as RlsConfig, d as RlsMembershipTable, f as RlsMemberships, g as RlsTarget, h as RlsSuspension, i as PermDockConfig, l as RlsDialect, m as RlsSuspendedScope, n as CliIo, o as RlsActiveRow, p as RlsSuspendedMembership, r as CollectConfig, s as RlsApiKeys, t as CatalogConfig, u as RlsFunctionMapping } from "../types-BPxgszlT.js";
+//#region src/cli/catalog-path.d.ts
+/**
+ * The absolute path `permdock collect` writes the catalog to: `collect.out`,
+ * then `catalog.out`, then `permissions.catalog.json`, resolved against `cwd`.
+ * `out` overrides the config, as `collect --out` does.
+ */
+export declare function catalogPath(config: PermDockConfig, cwd: string, out?: string): string;
+//#endregion
+//#region src/cli/config.d.ts
+export declare function defineConfig<T extends PermDockConfig>(config: T): T;
+//#endregion
+//#region src/cli/markers.d.ts
+/** The first line of a hook migration `permdock supabase hook generate` wrote. */
+type SupabaseHookMarker = {
+  /** The marker's major: `1` for `-- permdock:hook v1`. */
+  readonly version: number;
+  readonly schema?: string;
+  readonly tenantClaim?: string;
+  readonly budget?: number;
+  readonly claims: readonly string[];
+};
+/** The first line of a `--grants-out` migration. */
+type SupabaseGrantsMarker = {
+  readonly version: number;
+  readonly schema?: string;
+};
+/**
+ * Reads the `-- permdock:hook v<N>` line that starts a generated hook
+ * migration. Undefined when the first line is not a hook marker.
+ */
+export declare function parseHookMarker(sql: string): SupabaseHookMarker | undefined;
+/**
+ * Reads the `-- permdock:grants v<N>` line that starts a `--grants-out`
+ * migration. Undefined when the first line is not a grants marker.
+ */
+export declare function parseGrantsMarker(sql: string): SupabaseGrantsMarker | undefined;
+//#endregion
+//#region src/cli/run.d.ts
+export declare function run(argv: readonly string[], options?: {
+  readonly cwd?: string;
+  readonly io?: CliIo;
+}): Promise<RunResult>;
+//#endregion
+export type { CatalogActivation, CatalogApproval, CatalogBreakGlass, CatalogConfig, CatalogDocument, CatalogPermission, CatalogResource, CatalogRole, CatalogScope, CatalogSupportAccess, CatalogUsage, CollectConfig, PermDockConfig, RlsActiveRow, RlsApiKeys, RlsConfig, RlsDialect, RlsFunctionMapping, RlsMembershipTable, RlsMemberships, RlsSuspendedMembership, RlsSuspendedScope, RlsSuspension, RlsTarget, RunResult, SupabaseGrantsMarker, SupabaseHookMarker };

package/dist/cli/index.js

@@ -0,0 +1,5 @@
+import { t as catalogPath } from "../catalog-path-CnI0XTFK.js";
+import { t as defineConfig } from "../config-BJiM-xAm.js";
+import { o as parseGrantsMarker, s as parseHookMarker } from "../markers-B0hYLvMD.js";
+import { t as run } from "../run-YXCJDNYk.js";
+export { catalogPath, defineConfig, parseGrantsMarker, parseHookMarker, run };

package/dist/clients-C7zLFuWT.d.ts

@@ -0,0 +1,12 @@
+//#region src/core/clients.d.ts
+/**
+ * Stable names for OAuth clients whose ids differ per environment or are
+ * assigned at dynamic registration. A record maps each name to the client
+ * id (or ids) it stands for; an unset id (an environment variable that is
+ * not defined) names nothing. A function maps a verified client id to a
+ * name, or `undefined`. Policy delegations name the client (`to: { kind,
+ * client }`), never its id.
+ */
+type ClientNames = Readonly<Record<string, string | readonly string[] | undefined>> | ((clientId: string) => string | undefined);
+//#endregion
+export { ClientNames as t };

package/dist/clients-DjU5ABMy.js

@@ -0,0 +1,23 @@
+//#region src/core/clients.ts
+/**
+* The name `clients` gives `clientId`, or `undefined`: unknown ids, an id
+* two names claim, a function that throws or returns anything but a
+* non-empty string. Never throws.
+*/
+function clientNameOf(clients, clientId) {
+	if (clients === void 0 || clientId === "") return;
+	try {
+		if (typeof clients === "function") {
+			const name = clients(clientId);
+			return typeof name === "string" && name !== "" ? name : void 0;
+		}
+		const names = Object.entries(clients).flatMap(([name, ids]) => {
+			return name !== "" && (typeof ids === "string" ? [ids] : Array.isArray(ids) ? ids : []).includes(clientId) ? [name] : [];
+		});
+		return names.length === 1 ? names[0] : void 0;
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { clientNameOf as t };

package/dist/cloud/index.d.ts

@@ -0,0 +1,90 @@
+import { $ as AccessEvent, At as SnapshotSource, Ft as TokenVerifier, Nt as TokenFailureCause, at as DecisionSink, bn as PolicySource, ht as MembershipEvent, ot as DirectoryEvent, rt as DecisionEvent, tt as CredentialEvent } from "../policy-CFZAr_Al.js";
+import { f as ApprovalStore } from "../types-vKyAMtcX.js";
+import { n as CatalogEventData, o as CloudEventType } from "../sink-Gs6TTVa-.js";
+import { a as JsonWebKeySet, g as ReplayStore } from "../types-9AWO9EGt.js";
+//#region src/cloud/types.d.ts
+type CloudEndpointOptions = {
+  readonly url?: string;
+  readonly environment?: string;
+};
+type CloudEndpoints = {
+  /** The environment URL, `<url>/v1/environments/<env>`: `iss` and `aud` of the policy document. */
+  readonly issuer: string;
+  /** The environment's JWK Set URL, for `joseTokenVerifier({ jwks })`. */
+  readonly jwks: string;
+};
+type CloudOptions = CloudEndpointOptions & {
+  readonly key?: string;
+  readonly fetch?: typeof fetch;
+  readonly flushAt?: number;
+  /** Most events the sink holds while the Cloud is unreachable (default 10 000); the oldest are dropped first. */
+  readonly capacity?: number;
+  readonly waitUntil?: (task: Promise<void>) => void;
+  /**
+   * Verifies the environment's signed policy document, typically
+   * `joseTokenVerifier({ jwks: cloudEndpoints().jwks })`. Without one,
+   * `policies.current()` stays `null`: an unverifiable document is never applied.
+   */
+  readonly verifier?: TokenVerifier;
+};
+type CloudClient = CloudEndpoints & {
+  readonly approvals: ApprovalStore;
+  readonly sink: DecisionSink;
+  readonly snapshots: SnapshotSource;
+  readonly policies: PolicySource;
+};
+//#endregion
+//#region src/cloud/create.d.ts
+/**
+ * The environment URL and JWK Set URL `cloud()` uses, resolved with the same
+ * fallbacks (`PERMDOCK_CLOUD_URL`; `PERMDOCK_CLOUD_ENV`, `VERCEL_ENV`, `production`).
+ */
+export declare function cloudEndpoints(options?: CloudEndpointOptions): CloudEndpoints;
+export declare function cloud(options?: CloudOptions): CloudClient;
+//#endregion
+//#region src/cloud/webhook.d.ts
+type Envelope<TType extends CloudEventType, TData> = {
+  readonly specversion: "1.0";
+  readonly type: TType;
+  readonly source: string;
+  readonly subject?: string;
+  readonly id: string;
+  readonly time: string;
+  readonly datacontenttype: "application/json";
+  readonly data: TData;
+};
+/** A CloudEvent PermDock Cloud delivers, discriminated by `type`. */
+type PermDockCloudEvent = Envelope<"dev.permdock.decision", DecisionEvent> | Envelope<"dev.permdock.approval", DecisionEvent> | Envelope<"dev.permdock.directory", DirectoryEvent> | Envelope<"dev.permdock.membership", MembershipEvent> | Envelope<"dev.permdock.credential", CredentialEvent> | Envelope<"dev.permdock.catalog", CatalogEventData> | Envelope<"dev.permdock.access.started", AccessEvent> | Envelope<"dev.permdock.access.ended", AccessEvent> | Envelope<"dev.permdock.access.revoked", AccessEvent>;
+type VerifyWebhookOptions = {
+  /** Your receiver's URL; the batch `aud` must name it. */
+  readonly audience: string | readonly string[];
+  /** A verifier over the Cloud JWKS; built from `jwks` when absent. */
+  readonly verifier?: TokenVerifier;
+  /** `cloud().jwks`, a JWKS URL, or an inline key set. */
+  readonly jwks?: string | URL | JsonWebKeySet;
+  /** Drops a batch whose `jti` was already delivered. */
+  readonly replay?: ReplayStore;
+};
+type WebhookFailureReason = "unsigned" | "invalid-token" | "invalid-events" | "replayed";
+type VerifiedWebhook = {
+  readonly ok: true;
+  readonly id: string;
+  readonly events: readonly PermDockCloudEvent[];
+} | {
+  readonly ok: false;
+  readonly reason: WebhookFailureReason;
+  readonly cause?: TokenFailureCause;
+};
+/**
+ * Validates one CloudEvent against the closed type list and its data shape;
+ * returns `null` for anything else, never throws.
+ */
+export declare function parseCloudEvent(value: unknown): PermDockCloudEvent | null;
+/**
+ * Verifies a PermDock Cloud webhook delivery: a compact JWS with
+ * `typ: permdock-decisions+jwt` whose `events` claim holds CloudEvents.
+ * There is no unsigned mode, and it never throws.
+ */
+export declare function verifyWebhook(request: Request, options: VerifyWebhookOptions): Promise<VerifiedWebhook>;
+//#endregion
+export type { CloudClient, CloudEndpointOptions, CloudEndpoints, CloudOptions, PermDockCloudEvent, VerifiedWebhook, VerifyWebhookOptions, WebhookFailureReason };