permdock 0.1.0 → 0.3.0

package/dist/{permissions-B8vCg_bI.d.ts → permissions-CDgvKG5L.d.ts}

@@ -1,5 +1,5 @@
-import { h as ResourceInit, l as InferPermissionTree } from "./permissions-B4apnahQ.js";
-import { r as Role, t as Plan } from "./vocabulary-Dk0fs-Jk.js";
+import { g as ResourceInit, u as InferPermissionTree } from "./permissions-DttnqqxC.js";
+import { r as Role, t as Plan } from "./vocabulary-DA8a8zif.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/testing/saas/permissions.d.ts
 declare const SaasProjectSchema: StandardSchemaV1<SaasProject>;

package/dist/{permissions-DC7GROPA.js → permissions-DVoF6dMt.js}

@@ -1,5 +1,5 @@
 import { n as isReadonlyArray, t as compact } from "./compact-y6vfu2_f.js";
-import { n as freezeDeep } from "./freeze-y1_jQL4v.js";
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
 //#region src/core/paths.ts
 const FORBIDDEN_KEYS = /* @__PURE__ */ new Set([
 	"__proto__",
@@ -40,6 +40,28 @@ const TREE_REGISTRY = Symbol.for("permdock.registry");
 const NODE_RESOURCE = Symbol.for("permdock.resource");
 const TREE_LEAVES = Symbol.for("permdock.leaves");
 const LEAF_FORMER = Symbol.for("permdock.former");
+/** The edge's group resources with their relation and id column. */
+function groupEntries(spec) {
+	const groups = spec.groups;
+	if (groups === void 0) return [];
+	return Object.entries(groups.resources).map(([resource, group]) => typeof group === "string" ? {
+		resource,
+		relation: group,
+		subject: spec.subject ?? "user_id",
+		typed: false
+	} : {
+		resource,
+		relation: group.relation,
+		subject: group.subject ?? spec.subject ?? "user_id",
+		typed: group.subject !== void 0
+	});
+}
+function restrictedStops(node, path) {
+	return node?.restricted !== void 0 && (node.restrictedStops === void 0 || node.restrictedStops.includes(path));
+}
+function restrictedFor(node, path) {
+	return restrictedStops(node, path) ? node?.restricted : void 0;
+}
 function isFieldRelation(relation) {
 	return relation !== void 0 && "field" in relation;
 }
@@ -187,7 +209,20 @@ function resource(schemaOrOptions, options) {
 	throw new Error("PermDock: resource() first argument must be a schema or options");
 }
 const RESOURCE_NAME = /^[A-Za-z][A-Za-z0-9_-]*$/u;
+/** Level names ride claims and grant keys (`key@level`), so they stay SQL- and claim-safe. */
+const LEVEL_NAME = /^[a-z][a-z0-9_]*$/u;
 const EDGE_TABLE = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/u;
+function restrictedStopsOf(name, option, parent, links) {
+	if (option.stops === void 0) return;
+	if (!Array.isArray(option.stops) || option.stops.length === 0) throw new Error(`PermDock: resource "${name}" restricted.stops must list 'parent' or link names`);
+	const stops = /* @__PURE__ */ new Set();
+	for (const path of option.stops) {
+		if (typeof path !== "string") throw new TypeError(`PermDock: resource "${name}" restricted.stops must list 'parent' or link names`);
+		if (path === "parent" ? parent === void 0 : !Object.hasOwn(links, path)) throw new Error(`PermDock: resource "${name}" restricted.stops names '${path}', which it does not declare`);
+		stops.add(path);
+	}
+	return Object.freeze([...stops].toSorted());
+}
 function normaliseRelation(resourceName, relationName, spec) {
 	if (typeof spec === "string") {
 		assertSafeKey(spec, "relation field");
@@ -265,25 +300,38 @@ function normaliseMatch(label, match) {
 	return out;
 }
 function normaliseGroups(label, groups) {
-	assertSafeKey(groups.column, "edge groups column");
+	if (groups.column !== void 0) assertSafeKey(groups.column, "edge groups column");
 	const resources = {};
 	const names = Object.keys(groups.resources);
 	if (names.length === 0) throw new Error(`PermDock: ${label} groups needs at least one resource`);
 	for (const name of names) {
 		assertSafeKey(name, "group resource");
-		const relationName = groups.resources[name];
+		const group = groups.resources[name];
+		if (typeof group === "string") {
+			assertSafeKey(group, "group relation");
+			if (groups.column === void 0) throw new Error(`PermDock: ${label} groups '${name}' needs its own subject column, or groups needs a column naming the resource`);
+			resources[name] = group;
+			continue;
+		}
+		if (group === null || typeof group !== "object") throw new TypeError(`PermDock: ${label} groups '${name}' must name a relation`);
+		const relationName = "relation" in group ? group.relation : void 0;
 		if (typeof relationName !== "string") throw new TypeError(`PermDock: ${label} groups '${name}' must name a relation`);
 		assertSafeKey(relationName, "group relation");
-		resources[name] = relationName;
+		const subject = "subject" in group ? group.subject : void 0;
+		if (subject !== void 0 && typeof subject !== "string") throw new TypeError(`PermDock: ${label} groups '${name}' subject must be a column name`);
+		if (subject !== void 0) assertSafeKey(subject, "group subject column");
+		else if (groups.column === void 0) throw new Error(`PermDock: ${label} groups '${name}' needs its own subject column, or groups needs a column naming the resource`);
+		resources[name] = subject === void 0 ? { relation: relationName } : {
+			relation: relationName,
+			subject
+		};
 	}
+	if (groups.direct !== void 0 && groups.column === void 0) throw new Error(`PermDock: ${label} groups direct needs a column to compare it with`);
 	if (groups.direct !== void 0 && groups.direct in resources) throw new Error(`PermDock: ${label} groups direct '${groups.direct}' is also a group resource`);
-	return groups.direct === void 0 ? {
-		column: groups.column,
-		resources
-	} : {
-		column: groups.column,
+	return {
+		...groups.column === void 0 ? {} : { column: groups.column },
 		resources,
-		direct: groups.direct
+		...groups.direct === void 0 ? {} : { direct: groups.direct }
 	};
 }
 /** An included relation must exist on the same resource, be tenancy-free and never include itself back. */
@@ -322,7 +370,7 @@ function assertGraphTargets(registry) {
 		for (const [linkName, link] of Object.entries(node.links)) if (!registry.has(link.resource)) throw new Error(`PermDock: link '${linkName}' on '${node.name}' names the undeclared resource '${link.resource}'`);
 		for (const [relationName, spec] of Object.entries(node.relations)) {
 			if (!isEdgeRelation(spec) || spec.groups === void 0) continue;
-			for (const [target, targetRelation] of Object.entries(spec.groups.resources)) {
+			for (const { resource: target, relation: targetRelation } of groupEntries(spec)) {
 				assertGroupTarget(registry, node, relationName, spec, target, targetRelation);
 				if (target !== node.name) {
 					const out = edges.get(node.name) ?? /* @__PURE__ */ new Set();
@@ -381,8 +429,12 @@ function materialiseResource(init, path, registry, leaves, former) {
 	}
 	const version = init.options.version;
 	if (version !== void 0) assertSafeKey(version, "version field");
-	const restricted = init.options.restricted;
-	if (restricted !== void 0) assertSafeKey(restricted, "restricted field");
+	const restrictedOption = init.options.restricted;
+	const restricted = typeof restrictedOption === "string" ? restrictedOption : restrictedOption?.field;
+	if (restrictedOption !== void 0) {
+		if (typeof restricted !== "string") throw new TypeError(`PermDock: resource "${name}" restricted must name a field`);
+		assertSafeKey(restricted, "restricted field");
+	}
 	const disclosure = init.options.disclosure ?? "reveal";
 	if (disclosure !== "hide" && disclosure !== "reveal") throw new Error(`PermDock: resource "${name}" disclosure must be 'hide' or 'reveal'`);
 	const relations = {};
@@ -401,6 +453,14 @@ function materialiseResource(init, path, registry, leaves, former) {
 			resource: link.resource
 		});
 	}
+	const restrictedStopList = typeof restrictedOption === "object" ? restrictedStopsOf(name, restrictedOption, parent, links) : void 0;
+	const levels = {};
+	for (const [levelName, condition] of Object.entries(init.options.levels ?? {})) {
+		if (!LEVEL_NAME.test(levelName)) throw new Error(`PermDock: level '${levelName}' on '${name}' must match ^[a-z][a-z0-9_]*$`);
+		if (condition === null || typeof condition !== "object" || Array.isArray(condition)) throw new Error(`PermDock: level '${levelName}' on '${name}' must be a condition object`);
+		levels[levelName] = freezeDeep({ ...condition });
+	}
+	if (Object.keys(levels).length > 0 && instanceSet.size === 0) throw new Error(`PermDock: resource '${name}' declares levels but no instance actions`);
 	const resourceNode = Object.freeze({
 		name,
 		path: prefix,
@@ -411,9 +471,11 @@ function materialiseResource(init, path, registry, leaves, former) {
 		relations: freezeDeep(relations),
 		version,
 		restricted,
+		...restrictedStopList === void 0 ? {} : { restrictedStops: restrictedStopList },
 		disclosure,
 		instanceActions: instanceSet,
-		collectionActions: collectionSet
+		collectionActions: collectionSet,
+		levels: Object.freeze(levels)
 	});
 	assertIncludes(resourceNode);
 	registry.set(name, resourceNode);
@@ -597,4 +659,4 @@ function mergePermissions(...trees) {
 	return freezeDeep(attachRegistry(merged, registry, leaves));
 }
 //#endregion
-export { ownGet as C, splitPath as E, isForbiddenKey as S, readPath as T, mergePermissions as _, formerKeys as a, resourceOfNode as b, getResource as c, isFieldRelation as d, isPermission as f, listPermissions as g, isSelfParented as h, findPermission as i, isComputedRelation as l, isRegistryTree as m, definePermissions as n, formerScopes as o, isPrincipalRelation as p, expandRelation as r, getRegistry as s, annotationsFor as t, isEdgeRelation as u, renamedKeys as v, ownKeys as w, assertSafeKey as x, resource as y };
+export { restrictedStops as C, ownKeys as D, ownGet as E, readPath as O, restrictedFor as S, isForbiddenKey as T, listPermissions as _, formerKeys as a, resource as b, getResource as c, isEdgeRelation as d, isFieldRelation as f, isSelfParented as g, isRegistryTree as h, findPermission as i, splitPath as k, groupEntries as l, isPrincipalRelation as m, definePermissions as n, formerScopes as o, isPermission as p, expandRelation as r, getRegistry as s, annotationsFor as t, isComputedRelation as u, mergePermissions as v, assertSafeKey as w, resourceOfNode as x, renamedKeys as y };

package/dist/{permissions-B4apnahQ.d.ts → permissions-DttnqqxC.d.ts}

@@ -63,15 +63,28 @@ type FieldRelation = RelationIncludes & {
 };
 /** Literal values an edge row's columns must hold, so one table backs several relations. */
 type EdgeMatch = Readonly<Record<string, string | number | boolean>>;
+/**
+ * One group resource of an edge: the relation whoever the row names must
+ * hold on the group, and, when the group's id has its own typed column, that
+ * column in place of the edge's `subject`.
+ */
+type EdgeGroup = string | {
+  readonly relation: string;
+  readonly subject?: string;
+};
 /**
  * Edge rows that name a group instead of a principal: `column` holds the
  * resource name, `subject` the group's id, and the row holds for whoever
  * holds `resources[<name>]` on that group. A null `column` (or `direct`)
- * names a principal; any other value matches nothing.
+ * names a principal; any other value matches nothing. A group with its own
+ * `subject` column reads the group's id from it; without `column`, a row
+ * names that group when the column is not null, and a principal when the
+ * edge's `subject` is not null.
  */
 type EdgeGroups = {
-  readonly column: string;
-  readonly resources: Readonly<Record<string, string>>;
+  /** Required unless every group names its own `subject` column. */
+  readonly column?: string;
+  readonly resources: Readonly<Record<string, EdgeGroup>>;
   /** The `column` value of a row naming a principal, besides `null`. */
   readonly direct?: string;
 };
@@ -107,6 +120,10 @@ type ResourceLink = {
   readonly field: string;
   readonly resource: string;
 };
+type ResourceRestricted = {
+  readonly field: string;
+  readonly stops?: readonly string[];
+};
 type ActionList = readonly string[] | Record<string, ActionMeta>;
 type ResourceOptions<A extends ActionList | undefined = ActionList | undefined, C extends ActionList | undefined = ActionList | undefined> = {
   /**
@@ -129,13 +146,22 @@ type ResourceOptions<A extends ActionList | undefined = ActionList | undefined,
    * A boolean column: a row where it is `true` is reached only by grants on
    * itself, never by relations held on its ancestors.
    */
-  readonly restricted?: string;
+  readonly restricted?: string | ResourceRestricted;
   /**
    * `'hide'`: a denied check on a loaded row answers as if the row did not
    * exist (HTTP `404`), so an id never confirms a row the caller cannot read.
    */
   readonly disclosure?: "hide" | "reveal";
+  /**
+   * Named grant levels a custom role may pick per permission, each a row
+   * condition (`where` shorthand or a `Condition`), such as `own`, `team` and
+   * `all`. A level narrows the ceiling grant it applies to and never widens
+   * it; it reaches only instance actions. Names match `^[a-z][a-z0-9_]*$`.
+   */
+  readonly levels?: Readonly<Record<string, ResourceLevel>>;
 };
+/** A level's row condition: `where` shorthand or a normalised `Condition`, checked by `definePolicy`. */
+type ResourceLevel = Readonly<Record<string, unknown>>;
 type ResourceInit<T = unknown, A extends ActionList | undefined = ActionList | undefined, C extends ActionList | undefined = ActionList | undefined> = {
   readonly [RESOURCE_BRAND]: true;
   readonly schema: StandardSchemaV1<unknown, T> | undefined;
@@ -151,9 +177,12 @@ type ResourceNode<T = unknown> = {
   readonly relations: Readonly<Record<string, ResourceRelation>>;
   readonly version: string | undefined;
   readonly restricted: string | undefined;
+  readonly restrictedStops?: readonly string[];
   readonly disclosure: "hide" | "reveal";
   readonly instanceActions: ReadonlySet<string>;
   readonly collectionActions: ReadonlySet<string>;
+  /** Declared level names to their raw condition; `definePolicy` normalises them. */
+  readonly levels?: Readonly<Record<string, ResourceLevel>>;
 };
 type PermissionTree = {
   readonly [key: string]: PermissionTree | Permission;
@@ -182,4 +211,4 @@ declare function findPermission(tree: PermissionTree, keyOrScope: string): Permi
 declare function isPermission(value: unknown): value is Permission;
 declare function mergePermissions<const Trees extends readonly PermissionTree[]>(...trees: Trees): PermissionTree;
 //#endregion
-export { findPermission as C, listPermissions as D, isPermission as E, mergePermissions as O, definePermissions as S, getResource as T, ResourceNode as _, EdgeGroups as a, ResourceRelation as b, FieldRelation as c, Permission as d, PermissionKind as f, ResourceLink as g, ResourceInit as h, DefinePermissionsOptions as i, resource as k, InferPermissionTree as l, PrincipalRelation as m, ActionMeta as n, EdgeMatch as o, PermissionTree as p, ComputedRelation as r, EdgeRelation as s, ActionList as t, MetaValue as u, ResourceOptions as v, formerKeys as w, ResourceRelationInput as x, ResourceParent as y };
+export { listPermissions as A, ResourceRelationInput as C, formerKeys as D, findPermission as E, resource as M, getResource as O, ResourceRelation as S, definePermissions as T, ResourceLevel as _, EdgeGroup as a, ResourceOptions as b, EdgeRelation as c, MetaValue as d, Permission as f, ResourceInit as g, PrincipalRelation as h, DefinePermissionsOptions as i, mergePermissions as j, isPermission as k, FieldRelation as l, PermissionTree as m, ActionMeta as n, EdgeGroups as o, PermissionKind as p, ComputedRelation as r, EdgeMatch as s, ActionList as t, InferPermissionTree as u, ResourceLink as v, ResourceRestricted as w, ResourceParent as x, ResourceNode as y };

package/dist/{permissions-CofRqesP.js → permissions-RJrovw98.js}

@@ -1,6 +1,6 @@
-import { n as definePermissions, y as resource } from "./permissions-DC7GROPA.js";
-import { s as crud } from "./src-CTNT-PBW.js";
-import { v as definePlans, y as defineRoles } from "./grantee-Bv04_Vzf.js";
+import { b as resource, n as definePermissions } from "./permissions-DVoF6dMt.js";
+import { s as crud } from "./src-BDwEZWrZ.js";
+import { b as definePlans, x as defineRoles } from "./grantee-Cv5Sogfv.js";
 //#region src/testing/saas/schema.ts
 function accepts(kind, value) {
 	switch (kind) {

package/dist/{pins-CqE1jZuF.js → pins-8ILTftC9.js}

@@ -6,7 +6,7 @@ const DRAFT_PINS = {
 };
 const PROFILE_NAMES = { fapi2: "fapi-20-security-profile" };
 /** PermDock's published `supportedParametersSchema` per profile, stable across pins. */
-const PROFILE_PARAMETERS = { fapi2: "https://permdock.dev/schemas/security-profiles/fapi2.json" };
-const GNAP_RESERVED = "scheme.type 'gnap' is reserved and emits nothing. See https://permdock.dev/docs/standards/watch-list#gnap";
+const PROFILE_PARAMETERS = { fapi2: "https://permdock.com/schemas/security-profiles/fapi2.json" };
+const GNAP_RESERVED = "scheme.type 'gnap' is reserved and emits nothing. See https://permdock.com/docs/standards/watch-list#gnap";
 //#endregion
 export { PROFILE_PARAMETERS as i, GNAP_RESERVED as n, PROFILE_NAMES as r, DRAFT_PINS as t };

package/dist/{policy-Cq2fB8Q5.d.ts → policy-D2W7uv19.d.ts}

@@ -1,5 +1,5 @@
-import { C as Policy, hr as Subject, mr as Principal } from "./policy-CInmNGkM.js";
-import { c as saasPlans, l as saasRoles, s as saasPermissions } from "./permissions-B8vCg_bI.js";
+import { C as Policy, Nr as Principal, Pr as Subject } from "./policy-IB6yxpC3.js";
+import { c as saasPlans, l as saasRoles, s as saasPermissions } from "./permissions-CDgvKG5L.js";
 //#region src/testing/saas/policy.d.ts
 /** Daily API-key quota per subject; the bucket should be per tenant too. */
 declare const SAAS_API_KEY_LIMIT = 5;