permdock 0.0.0 → 0.2.0

package/dist/bind-VnYn2HKq.js

@@ -0,0 +1,97 @@
+import { t as compact } from "./compact-y6vfu2_f.js";
+import { o as invalidSignatureResponse } from "./evaluations-tz6D9A2G.js";
+import { t as instanceOptions } from "./instance-options-Dhhcnm3y.js";
+import { n as tenantScope } from "./adapter-context-mlWsVGGg.js";
+import { n as createServerKernel } from "./create-CPhDL6qx.js";
+//#region src/server/bind.ts
+/** The server kernel with the subject and actor callbacks reading the context `contextOf` maps a `Request` to. */
+function adapterKernel(policy, options, adapter, contextOf) {
+	return createServerKernel(policy, compact({
+		subject: (request) => {
+			const context = contextOf(request);
+			return context === void 0 ? null : options.subject(context);
+		},
+		actor: options.actor === void 0 ? void 0 : (request) => {
+			const context = contextOf(request);
+			return context === void 0 ? void 0 : options.actor?.(context);
+		},
+		...instanceOptions(options),
+		store: options.store,
+		pdp: options.pdp,
+		webBotAuth: options.webBotAuth,
+		revocations: options.revocations,
+		adapter,
+		wrap: options.otel
+	}));
+}
+/**
+* The kernel of a framework adapter, with the subject, actor and tenant
+* callbacks reading the framework context each `Request` was built from.
+*/
+function bindKernel(policy, options, adapter, toRequest) {
+	const contexts = /* @__PURE__ */ new WeakMap();
+	const bound = /* @__PURE__ */ new WeakMap();
+	const kernel = adapterKernel(policy, options, adapter, (request) => contexts.get(request));
+	const bind = (context) => {
+		const hit = bound.get(context);
+		if (hit !== void 0) return hit;
+		const request = toRequest(context);
+		bound.set(context, request);
+		contexts.set(request, context);
+		return request;
+	};
+	const rebind = (context) => {
+		const request = toRequest(context);
+		contexts.set(request, context);
+		const previous = bound.get(context);
+		if (previous !== void 0) kernel.shareSubject(previous, request);
+		return request;
+	};
+	const scopeOf = (context) => tenantScope(options.tenant, context);
+	const handlerScope = (request) => {
+		const context = contexts.get(request);
+		return context === void 0 ? Promise.resolve({ tenant: void 0 }) : scopeOf(context);
+	};
+	const attach = (context) => attached(async () => kernel.permdock(bind(context), await scopeOf(context)));
+	return {
+		kernel,
+		bind,
+		rebind,
+		scopeOf,
+		handlerScope,
+		attach
+	};
+}
+/** The instance `build` resolves; an invalid Web Bot Auth signature is its `401` response. */
+async function attached(build) {
+	try {
+		return {
+			ok: true,
+			permdock: await build()
+		};
+	} catch (error) {
+		const response = invalidSignatureResponse(error);
+		if (response === void 0) throw error;
+		return {
+			ok: false,
+			response
+		};
+	}
+}
+/** Sets `permdock`, and `permdockData` when a loader returned a row, on a framework request or context. */
+function decorate(target, instance, data) {
+	Object.assign(target, data === void 0 ? { permdock: instance } : {
+		permdock: instance,
+		permdockData: data
+	});
+}
+/** One connection per socket: every handler of `socket` gets the promise the first one opened. */
+function socketConnection(sockets, socket, open) {
+	const hit = sockets.get(socket);
+	if (hit !== void 0) return hit;
+	const opened = open();
+	sockets.set(socket, opened);
+	return opened;
+}
+//#endregion
+export { socketConnection as a, decorate as i, attached as n, bindKernel as r, adapterKernel as t };

package/dist/boundary-BM8a_P6E.js

@@ -0,0 +1,13 @@
+import { r as parsePermDockDigest } from "./digest-BI-6aa6d.js";
+//#region src/client/boundary.ts
+/** The digest of a PermDock error (`PermDockDeniedError`, `PermDockApprovalRequiredError`); `null` for any other error. */
+function boundaryDigest(error) {
+	if (error === null || typeof error !== "object" || !("digest" in error)) return null;
+	return parsePermDockDigest(error.digest);
+}
+/** What a boundary renders for `digest`: `approval` for an approval request when given, otherwise `denied`. */
+function boundaryFallback(digest, fallbacks) {
+	return digest.outcome === "approval-required" ? fallbacks.approval ?? fallbacks.denied : fallbacks.denied;
+}
+//#endregion
+export { boundaryFallback as n, boundaryDigest as t };

package/dist/boundary-BmHxVH1J.d.ts

@@ -0,0 +1,15 @@
+import { t as PermDockDigest } from "./digest-B3kc_PgQ.js";
+//#region src/client/boundary.d.ts
+type PermissionBoundaryState = PermDockDigest & {
+  /** Renders the boundary's children again, e.g. after an approval or a role change. */
+  readonly retry: () => void;
+};
+/** The digest of a PermDock error (`PermDockDeniedError`, `PermDockApprovalRequiredError`); `null` for any other error. */
+declare function boundaryDigest(error: unknown): PermDockDigest | null;
+/** What a boundary renders for `digest`: `approval` for an approval request when given, otherwise `denied`. */
+declare function boundaryFallback<T>(digest: PermDockDigest, fallbacks: {
+  readonly denied?: T | undefined;
+  readonly approval?: T | undefined;
+}): T | undefined;
+//#endregion
+export { boundaryDigest as n, boundaryFallback as r, PermissionBoundaryState as t };

package/dist/budget-JqcRqyhK.d.ts

@@ -0,0 +1,11 @@
+//#region src/supabase/budget.d.ts
+/** The default size budget, in bytes of JSON, for the hook's `memberships` claim: about 15 UUID-keyed single-role memberships. */
+declare const supabaseMembershipsBudget = 1024;
+/**
+ * The default claim that carries the active first-scope id: the hook writes
+ * it, `subjectFromSupabase` reads it, and the RLS helpers compare with it.
+ * `rls.tenantClaim` and the `tenant` option change it.
+ */
+declare const supabaseTenantClaim = "tenant_id";
+//#endregion
+export { supabaseTenantClaim as n, supabaseMembershipsBudget as t };

package/dist/budget-NbEtbJC_.js

@@ -0,0 +1,11 @@
+//#region src/supabase/budget.ts
+/** The default size budget, in bytes of JSON, for the hook's `memberships` claim: about 15 UUID-keyed single-role memberships. */
+const supabaseMembershipsBudget = 1024;
+/**
+* The default claim that carries the active first-scope id: the hook writes
+* it, `subjectFromSupabase` reads it, and the RLS helpers compare with it.
+* `rls.tenantClaim` and the `tenant` option change it.
+*/
+const supabaseTenantClaim = "tenant_id";
+//#endregion
+export { supabaseTenantClaim as n, supabaseMembershipsBudget as t };

package/dist/canonical-json-DemiK4Vp.js

@@ -0,0 +1,26 @@
+//#region src/core/canonical-json.ts
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+* JSON with sorted keys and `undefined` members dropped, so equal values hash
+* equally. Dates become ISO strings, bigints `"<n>n"`, and a repeated object
+* on the current path `"[Circular]"`, so any validated row serialises.
+*/
+function canonicalJson(value, path = /* @__PURE__ */ new Set()) {
+	if (typeof value === "bigint") return JSON.stringify(`${value}n`);
+	if (value instanceof Date) return JSON.stringify(Number.isNaN(value.getTime()) ? null : value.toISOString());
+	if (value !== null && typeof value === "object") {
+		if (path.has(value)) return "\"[Circular]\"";
+		path.add(value);
+		try {
+			if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item === void 0 ? null : item, path)).join(",")}]`;
+			if (isRecord(value)) return `{${Object.keys(value).toSorted().filter((key) => value[key] !== void 0).map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key], path)}`).join(",")}}`;
+		} finally {
+			path.delete(value);
+		}
+	}
+	return JSON.stringify(value) ?? "null";
+}
+//#endregion
+export { canonicalJson as t };

package/dist/capability-4qPdO9gk.js

@@ -0,0 +1,173 @@
+import { t as compact } from "./compact-y6vfu2_f.js";
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+import { T as isForbiddenKey, _ as listPermissions } from "./permissions-DVoF6dMt.js";
+import { t as expiredAt } from "./expiry-BoBJ8Tvc.js";
+import { n as sameId } from "./ids-DC4V4CFu.js";
+import { t as anonymousSubject } from "./subject-C6dLxqHU.js";
+//#region src/core/capability.ts
+function redeemerKind(redeemer) {
+	if (redeemer === void 0 || typeof redeemer === "string") return redeemer ?? "anyone";
+	return "user" in redeemer ? "user" : "scope";
+}
+/**
+* The first rule of `policy` the capability breaks, or `undefined`. A
+* lifetime rule without a known `issuedAt`, or one that is not a finite
+* non-negative number, is broken: the check fails closed.
+*/
+function linkPolicyViolation(capability, policy, issuedAt) {
+	const policies = Array.isArray(policy) ? policy : [policy];
+	for (const item of policies) {
+		const max = item.maxLifetime;
+		if (max !== void 0 && (typeof max !== "number" || !Number.isFinite(max) || max < 0 || issuedAt === void 0 || capability.expiresAt - issuedAt > max)) return "lifetime";
+		if (item.redeemers !== void 0 && !item.redeemers.includes(redeemerKind(capability.redeemer))) return "redeemer";
+		if (item.once === true && capability.once !== true) return "once";
+	}
+}
+const MAX_ID = 256;
+const MAX_ENTRIES = 64;
+/** A copy holding only own enumerable properties, so a prototype never supplies a field. */
+function ownRecord(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return;
+	const record = {};
+	for (const [key, item] of Object.entries(value)) if (!isForbiddenKey(key)) record[key] = item;
+	return record;
+}
+function isId(value) {
+	return typeof value === "string" && value.length > 0 && value.length <= MAX_ID;
+}
+function idList(value) {
+	if (!Array.isArray(value) || value.length === 0 || value.length > MAX_ENTRIES || !value.every(isId)) return;
+	return [...new Set(value)];
+}
+function parseRedeemer(input) {
+	if (input === "anyone" || input === "signed-in") return input;
+	const value = ownRecord(input);
+	if (value === void 0) return;
+	const keys = Object.keys(value);
+	if (keys.length === 1 && isId(value["user"])) return { user: value["user"] };
+	if (keys.length === 2 && isId(value["scope"]) && isId(value["id"])) return {
+		scope: value["scope"],
+		id: value["id"]
+	};
+}
+/**
+* Validates an untrusted `capability` claim and returns a frozen copy with
+* only the v1 fields, or `undefined`. Unknown fields are dropped; a wrong
+* type in a known field rejects the whole claim.
+*/
+function parseCapability(input) {
+	const value = ownRecord(input);
+	if (value === void 0 || value["v"] !== 1 || !isId(value["id"])) return;
+	if (value["holder"] !== "link" && value["holder"] !== "key") return;
+	const on = ownRecord(value["on"]);
+	if (on === void 0 || !isId(on["resource"]) || !isId(on["id"])) return;
+	const roles = idList(value["roles"]);
+	if (roles === void 0) return;
+	const permissions = value["permissions"] === void 0 ? void 0 : idList(value["permissions"]);
+	if (value["permissions"] !== void 0 && permissions === void 0) return;
+	const redeemer = value["redeemer"] === void 0 ? void 0 : parseRedeemer(value["redeemer"]);
+	if (value["redeemer"] !== void 0 && redeemer === void 0) return;
+	if (value["once"] !== void 0 && value["once"] !== true) return;
+	const expiresAt = value["expiresAt"];
+	if (typeof expiresAt !== "number" || !Number.isFinite(expiresAt)) return;
+	return freezeDeep(compact({
+		v: 1,
+		id: value["id"],
+		holder: value["holder"],
+		on: {
+			resource: on["resource"],
+			id: on["id"]
+		},
+		roles,
+		permissions,
+		redeemer,
+		once: value["once"],
+		expiresAt
+	}));
+}
+function resourceName(resource) {
+	const names = new Set(listPermissions(resource).map((leaf) => leaf.resource));
+	const [name] = names;
+	if (names.size !== 1 || name === void 0) throw new Error("PermDock: capability on.resource must name exactly one resource");
+	return name;
+}
+/** Builds the v1 `Capability` for `input`; throws on an input no resolver would accept. */
+function capabilityOf(input) {
+	const capability = parseCapability(compact({
+		v: 1,
+		id: input.id,
+		holder: "link",
+		on: {
+			resource: resourceName(input.on.resource),
+			id: input.on.id
+		},
+		roles: input.roles,
+		permissions: input.permissions?.map((permission) => permission.key),
+		redeemer: input.redeemer,
+		once: input.once === true ? true : void 0,
+		expiresAt: Math.floor(input.expiresAt)
+	}));
+	if (capability === void 0) throw new Error("PermDock: invalid capability (id, on.id and roles are required; roles and permissions hold at most 64 entries)");
+	return capability;
+}
+/**
+* Signs a capability as a `permdock-capability+jwt`: `sub` is the link id,
+* `exp` is `expiresAt`, and the signer sets `iss`, `iat` and a fresh `jti`.
+*/
+function signCapability(input, signer, options = {}) {
+	const capability = capabilityOf(input);
+	const violation = options.linkPolicy === void 0 ? void 0 : linkPolicyViolation(capability, options.linkPolicy, Math.floor(Date.now() / 1e3));
+	if (violation !== void 0) return Promise.reject(/* @__PURE__ */ new Error(`PermDock: capability breaks the link policy (${violation})`));
+	return signer.sign({
+		capability,
+		sub: capability.id
+	}, compact({
+		typ: "permdock-capability+jwt",
+		audience: options.audience,
+		expiresAt: capability.expiresAt
+	}));
+}
+function holdsScope(membership, scope, id, now) {
+	if (expiredAt(membership, now)) return false;
+	if (membership.scope === scope && sameId(membership.id, id)) return true;
+	return scope === "tenant" && sameId(membership.tenant, id) || scope === "team" && sameId(membership.team, id);
+}
+/** Whether `viewer`, the request's own verified subject, may redeem a capability. */
+function redeemerAllows(redeemer, viewer, now = Date.now() / 1e3) {
+	if (redeemer === void 0 || redeemer === "anyone") return true;
+	const principal = viewer?.principal ?? null;
+	if (principal === null || principal.kind === "link") return false;
+	if (redeemer === "signed-in") return true;
+	if ("user" in redeemer) return principal.id === redeemer.user;
+	return (principal.memberships ?? []).some((membership) => holdsScope(membership, redeemer.scope, redeemer.id, now));
+}
+/**
+* The subject a verified capability acts as: a `link` principal holding
+* `roles` on `on` and nothing else, with `delegation.scopes` narrowing it to
+* `permissions` when the capability lists them. A `key` holder resolves to
+* the anonymous subject until user-bound credentials ship.
+*/
+function capabilitySubject(capability, options = {}) {
+	if (capability.holder !== "link") return anonymousSubject();
+	const membership = {
+		on: capability.on,
+		roles: capability.roles,
+		via: "link",
+		expiresAt: capability.expiresAt
+	};
+	const principal = compact({
+		id: capability.id,
+		kind: "link",
+		issuer: options.issuer,
+		memberships: [membership],
+		capability
+	});
+	return freezeDeep(compact({
+		principal,
+		delegation: capability.permissions === void 0 ? void 0 : { scopes: capability.permissions.map((key) => key.replaceAll(".", ":")) },
+		context: {},
+		expiresAt: capability.expiresAt
+	}));
+}
+//#endregion
+export { ownRecord as a, signCapability as c, linkPolicyViolation as i, idList as n, parseCapability as o, isId as r, redeemerAllows as s, capabilitySubject as t };

package/dist/capability-Dq43tT1u.d.ts

@@ -0,0 +1,99 @@
+import { Nr as Principal, Pr as Subject, Pt as TokenSigner } from "./policy-CFZAr_Al.js";
+import { f as Permission, m as PermissionTree } from "./permissions-DttnqqxC.js";
+//#region src/core/capability.d.ts
+/**
+ * Who may redeem a capability: anyone holding it, any signed-in principal,
+ * one user, or a member of one scope instance. The viewer is the request's
+ * own verified subject, never a claim of the capability.
+ */
+type CapabilityRedeemer = "anyone" | "signed-in" | {
+  readonly user: string;
+} | {
+  readonly scope: string;
+  readonly id: string;
+};
+/**
+ * Capability v1: the `capability` claim of a `permdock-capability+jwt`. It
+ * holds `roles` on one resource instance (`on`, the `Membership.on` shape),
+ * optionally narrowed to `permissions` (keys). `id` is the link id: the
+ * token's `sub` and the handle an application revokes.
+ */
+type Capability = {
+  readonly v: 1;
+  readonly id: string;
+  /** `key` is reserved for user-bound credentials and resolves to no subject. */
+  readonly holder: "link" | "key";
+  readonly on: {
+    readonly resource: string;
+    readonly id: string;
+  };
+  readonly roles: readonly string[];
+  readonly permissions?: readonly string[];
+  readonly redeemer?: CapabilityRedeemer;
+  /** One request per token: the resolver claims the token's `jti` in a `ReplayStore`. */
+  readonly once?: true;
+  /** Seconds since the epoch; also the token's `exp` and the membership's `expiresAt`. */
+  readonly expiresAt: number;
+};
+type LinkPrincipal = Principal & {
+  readonly kind: "link";
+  readonly capability: Capability;
+};
+type CapabilityInput = {
+  readonly id: string;
+  readonly on: {
+    readonly resource: Permission | PermissionTree;
+    readonly id: string;
+  };
+  readonly roles: readonly string[];
+  readonly permissions?: readonly Permission[];
+  readonly redeemer?: CapabilityRedeemer;
+  readonly once?: boolean;
+  readonly expiresAt: number;
+};
+/**
+ * What one scope instance (a tenant, a customer) allows for links on its
+ * resources. Every field only tightens; several policies must all hold.
+ */
+type LinkPolicy = {
+  /** Longest a link may live, in seconds from when it was issued. */
+  readonly maxLifetime?: number;
+  /** Redeemer kinds allowed; `anyone` also covers a capability without `redeemer`. */
+  readonly redeemers?: readonly ("anyone" | "signed-in" | "user" | "scope")[];
+  /** Every link must be one-time. */
+  readonly once?: boolean;
+};
+type LinkPolicyViolation = "lifetime" | "redeemer" | "once";
+type SignCapabilityOptions = {
+  readonly audience?: string | readonly string[];
+  /** Refuse to sign a link these policies would refuse at resolution. */
+  readonly linkPolicy?: LinkPolicy | readonly LinkPolicy[];
+};
+/**
+ * The first rule of `policy` the capability breaks, or `undefined`. A
+ * lifetime rule without a known `issuedAt`, or one that is not a finite
+ * non-negative number, is broken: the check fails closed.
+ */
+declare function linkPolicyViolation(capability: Capability, policy: LinkPolicy | readonly LinkPolicy[], issuedAt: number | undefined): LinkPolicyViolation | undefined;
+/**
+ * Validates an untrusted `capability` claim and returns a frozen copy with
+ * only the v1 fields, or `undefined`. Unknown fields are dropped; a wrong
+ * type in a known field rejects the whole claim.
+ */
+declare function parseCapability(input: unknown): Capability | undefined;
+/**
+ * Signs a capability as a `permdock-capability+jwt`: `sub` is the link id,
+ * `exp` is `expiresAt`, and the signer sets `iss`, `iat` and a fresh `jti`.
+ */
+declare function signCapability(input: CapabilityInput, signer: TokenSigner, options?: SignCapabilityOptions): Promise<string>;
+/**
+ * The subject a verified capability acts as: a `link` principal holding
+ * `roles` on `on` and nothing else, with `delegation.scopes` narrowing it to
+ * `permissions` when the capability lists them. A `key` holder resolves to
+ * the anonymous subject until user-bound credentials ship.
+ */
+declare function capabilitySubject(capability: Capability, options?: {
+  readonly issuer?: string;
+}): Subject<LinkPrincipal> | Subject;
+//#endregion
+export { LinkPolicyViolation as a, capabilitySubject as c, signCapability as d, LinkPolicy as i, linkPolicyViolation as l, CapabilityInput as n, LinkPrincipal as o, CapabilityRedeemer as r, SignCapabilityOptions as s, Capability as t, parseCapability as u };

package/dist/catalog/index.d.ts

@@ -0,0 +1,12 @@
+import { a as CatalogDocument, c as CatalogResource, d as CatalogSupportAccess, f as CatalogUsage, i as CatalogDelegation, l as CatalogRole, n as CatalogApproval, o as CatalogGrant, p as CatalogValidity, r as CatalogBreakGlass, s as CatalogPermission, t as CatalogActivation, u as CatalogScope } from "../types-Dnemwd77.js";
+//#region src/catalog/parse.d.ts
+/**
+ * Reads a `permissions.catalog.json` document (parsed, or the JSON text) and
+ * validates it against `schemas/catalog-v1.json`. Returns a deep-frozen copy
+ * built from own keys; throws `PermDockValidationError` with every issue.
+ */
+export declare function parseCatalog(json: unknown): CatalogDocument;
+/** Keys of the permissions the catalog marks `rowConditions: true`: the SQL helpers alone cannot enforce them. */
+export declare function rowConditionKeys(catalog: CatalogDocument): ReadonlySet<string>;
+//#endregion
+export type { CatalogActivation, CatalogApproval, CatalogBreakGlass, CatalogDelegation, CatalogDocument, CatalogGrant, CatalogPermission, CatalogResource, CatalogRole, CatalogScope, CatalogSupportAccess, CatalogUsage, CatalogValidity };

package/dist/catalog/index.js

@@ -0,0 +1,2 @@
+import { n as rowConditionKeys, t as parseCatalog } from "../parse-BuyjxhZV.js";
+export { parseCatalog, rowConditionKeys };

package/dist/catalog-BjZSovXQ.js

@@ -0,0 +1,2 @@
+import { t as runCatalog } from "./catalog-z8q6bi_r.js";
+export { runCatalog };