permdock 0.0.0 → 0.1.0

package/dist/permissions-B4apnahQ.d.ts

@@ -0,0 +1,185 @@
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/core/permissions.d.ts
+declare const RESOURCE_BRAND: unique symbol;
+/** `definePermissions` options. */
+type DefinePermissionsOptions = {
+  /**
+   * Keys a permission used to have, mapped to its current key. Old keys are
+   * accepted wherever a key arrives as a string (stored custom roles, OAuth
+   * scopes, AuthZEN actions, hosted grants, `findPermission`) and resolve to
+   * the current leaf; code, decisions and audit only ever see the current key.
+   */
+  readonly renamed?: Readonly<Record<string, string>>;
+};
+type ActionMeta = {
+  readonly title?: string;
+  readonly description?: string;
+  readonly tags?: readonly string[];
+  readonly readOnly?: boolean;
+  /** The action may destroy or overwrite data; only meaningful when not `readOnly`. */
+  readonly destructive?: boolean;
+  /** Repeating the action with the same input has no further effect. */
+  readonly idempotent?: boolean;
+  /**
+   * On a role, or on a permission the subject is granted: whoever holds it may
+   * assign the whole custom-role ceiling, not only what they hold themselves.
+   */
+  readonly manageRoles?: boolean;
+  /** Set by a generator (`permdock openapi import`) to the operation an action was inferred from. */
+  readonly inferredFrom?: string;
+  /**
+   * Data the application owns, such as a risk level or an undo window. Plain
+   * JSON; PermDock carries it on the leaf, the catalog and snapshots and
+   * never reads it.
+   */
+  readonly x?: Readonly<Record<string, MetaValue>>;
+};
+/** A JSON value in `ActionMeta.x`. */
+type MetaValue = string | number | boolean | null | readonly MetaValue[] | {
+  readonly [key: string]: MetaValue;
+};
+type PermissionKind = "instance" | "collection";
+type Permission<K extends string = string, T = unknown, Kind extends PermissionKind = PermissionKind> = {
+  readonly key: K;
+  readonly scope: string;
+  readonly resource: string;
+  readonly action: string;
+  readonly meta: ActionMeta;
+  readonly kind: Kind;
+} & ([T] extends [never] ? unknown : unknown);
+type ResourceParent = {
+  readonly field: string;
+  readonly resource: string;
+};
+/** Relations on the same resource whose holders also hold this one. */
+type RelationIncludes = {
+  readonly includes?: readonly string[];
+};
+/** The row's `field` holds the principal id (or, with `memberOf`, a scope id). */
+type FieldRelation = RelationIncludes & {
+  readonly field: string;
+  /** A declared scope name (or the `tenant` / `team` alias): the field holds that scope's id. */
+  readonly memberOf?: string;
+};
+/** Literal values an edge row's columns must hold, so one table backs several relations. */
+type EdgeMatch = Readonly<Record<string, string | number | boolean>>;
+/**
+ * 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.
+ */
+type EdgeGroups = {
+  readonly column: string;
+  readonly resources: Readonly<Record<string, string>>;
+  /** The `column` value of a row naming a principal, besides `null`. */
+  readonly direct?: string;
+};
+/** One row per holder in an edge table: `object` holds the resource id, `subject` the principal id. */
+type EdgeRelation = RelationIncludes & {
+  readonly edge: string;
+  /** Default `<resource>_id`. */
+  readonly object?: string;
+  /** Default `user_id`. */
+  readonly subject?: string;
+  /** A timestamp column; an edge whose value has passed does not match. */
+  readonly expiresAt?: string;
+  readonly match?: EdgeMatch;
+  readonly groups?: EdgeGroups;
+};
+/** On a principal resource: the row's `principal` column holds the principal who holds the relation over it. */
+type PrincipalRelation = RelationIncludes & {
+  readonly principal: string;
+  /** Timestamp columns bounding when the relation holds; `null` leaves that side open. */
+  readonly period?: {
+    readonly startsAt?: string;
+    readonly expiresAt?: string;
+  };
+};
+/** Held only through the relations it includes. */
+type ComputedRelation = {
+  readonly includes: readonly string[];
+};
+type ResourceRelation = FieldRelation | EdgeRelation | PrincipalRelation | ComputedRelation;
+type ResourceRelationInput = string | ResourceRelation;
+/** A to-one link from a row to another resource's instance, walked by `through: [<link>]`. */
+type ResourceLink = {
+  readonly field: string;
+  readonly resource: string;
+};
+type ActionList = readonly string[] | Record<string, ActionMeta>;
+type ResourceOptions<A extends ActionList | undefined = ActionList | undefined, C extends ActionList | undefined = ActionList | undefined> = {
+  /**
+   * The resource name leaves, tables, relations and AuthZEN types use; the
+   * last path segment when absent. Names are unique across a tree.
+   */
+  readonly name?: string;
+  readonly id?: string;
+  readonly actions?: A;
+  readonly collection?: C;
+  readonly parent?: ResourceParent;
+  readonly links?: Readonly<Record<string, ResourceLink>>;
+  readonly relations?: Readonly<Record<string, ResourceRelationInput>>;
+  /**
+   * The row field that changes whenever the row does (`updatedAt`, a revision
+   * counter). An `approval: { staleOn: 'resource-change' }` binds to its value.
+   */
+  readonly version?: string;
+  /**
+   * 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;
+  /**
+   * `'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";
+};
+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;
+  readonly options: ResourceOptions<A, C>;
+};
+type ResourceNode<T = unknown> = {
+  readonly name: string;
+  readonly path: string;
+  readonly schema: StandardSchemaV1<unknown, T> | undefined;
+  readonly id: string;
+  readonly parent: ResourceParent | undefined;
+  readonly links: Readonly<Record<string, ResourceLink>>;
+  readonly relations: Readonly<Record<string, ResourceRelation>>;
+  readonly version: string | undefined;
+  readonly restricted: string | undefined;
+  readonly disclosure: "hide" | "reveal";
+  readonly instanceActions: ReadonlySet<string>;
+  readonly collectionActions: ReadonlySet<string>;
+};
+type PermissionTree = {
+  readonly [key: string]: PermissionTree | Permission;
+};
+type ActionNames<A extends ActionList | undefined> = A extends readonly string[] ? A[number] : A extends Record<string, ActionMeta> ? keyof A & string : never;
+type LeavesFrom<Prefix extends string, Names extends string, T, Kind extends PermissionKind> = [Names] extends [never] ? object : { readonly [K in Names]: Permission<Prefix extends "" ? K : `${Prefix}.${K}`, T, Kind>; };
+type InferResourceLeaves<R extends ResourceInit, Prefix extends string> = R extends ResourceInit<infer T, infer A, infer C> ? LeavesFrom<Prefix, ActionNames<A>, T, "instance"> & LeavesFrom<Prefix, ActionNames<C>, T, "collection"> : object;
+type InferPermissionTree<Input, Prefix extends string = ""> = Input extends ResourceInit ? InferResourceLeaves<Input, Prefix> : Input extends Record<string, unknown> ? { readonly [K in keyof Input & string]: InferPermissionTree<Input[K], Prefix extends "" ? K : `${Prefix}.${K}`>; } : never;
+/**
+ * The keys `permission` was renamed from, sorted. Empty for a leaf without
+ * renames and for one that crossed a serialisation boundary.
+ */
+declare function formerKeys(permission: object): readonly string[];
+declare function resource<T, const A extends ActionList = readonly [], const C extends ActionList = readonly []>(schema: StandardSchemaV1<unknown, T>, options?: ResourceOptions<A, C>): ResourceInit<T, A, C>;
+declare function resource<const A extends ActionList = readonly [], const C extends ActionList = readonly []>(options: ResourceOptions<A, C>): ResourceInit<unknown, A, C>;
+declare function getResource(tree: PermissionTree, name: string): ResourceNode | undefined;
+declare function definePermissions<const Input>(input: Input, options?: DefinePermissionsOptions): InferPermissionTree<Input>;
+declare function listPermissions(tree: PermissionTree | Permission): readonly Permission[];
+declare function findPermission(tree: PermissionTree, keyOrScope: string): Permission | undefined;
+/**
+ * A permission leaf: string `key`, `scope`, `resource` and `action` plus an
+ * object `meta`. `kind` is non-enumerable and does not survive
+ * `JSON.stringify`, so a leaf that crossed a serialisation boundary passes
+ * without it; when present it must be `instance` or `collection`.
+ */
+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 };

package/dist/permissions-B8vCg_bI.d.ts

@@ -0,0 +1,52 @@
+import { h as ResourceInit, l as InferPermissionTree } from "./permissions-B4apnahQ.js";
+import { r as Role, t as Plan } from "./vocabulary-Dk0fs-Jk.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/testing/saas/permissions.d.ts
+declare const SaasProjectSchema: StandardSchemaV1<SaasProject>;
+declare const SaasDocSchema: StandardSchemaV1<SaasDoc>;
+declare const SaasFolderSchema: StandardSchemaV1<SaasFolder>;
+/** A folder in an org's tree; `restricted` keeps grants held on its ancestors out. */
+type SaasFolder = {
+  readonly id: string;
+  readonly orgId: string;
+  readonly parentId: string | null;
+  readonly name: string;
+  readonly restricted: boolean;
+};
+type SaasProject = {
+  readonly id: string;
+  readonly orgId: string;
+  readonly ownerId: string;
+  readonly name: string;
+  readonly archived: boolean;
+};
+type SaasDoc = {
+  readonly id: string;
+  readonly orgId: string;
+  readonly teamId: string | null;
+  readonly title: string;
+  readonly locked: boolean;
+};
+type CrudActions = readonly ["read", "update", "delete"];
+type CrudCollection = readonly ["create", "list"];
+type Collection<C extends readonly string[]> = ResourceInit<unknown, readonly [], C>;
+type SaasDefinition = {
+  readonly project: ResourceInit<SaasProject, CrudActions, CrudCollection>;
+  readonly doc: ResourceInit<SaasDoc, CrudActions, CrudCollection>;
+  readonly folder: ResourceInit<SaasFolder, CrudActions, CrudCollection>;
+  readonly member: Collection<readonly ["list", "invite", "assignRole"]>;
+  readonly settings: Collection<readonly ["manage"]>;
+  readonly billing: Collection<readonly ["read", "manage"]>;
+  readonly analytics: Collection<readonly ["read"]>;
+  readonly audit: Collection<readonly ["read"]>;
+  readonly sso: Collection<readonly ["manage"]>;
+  readonly apiKey: Collection<readonly ["manage", "create", "revokeAll"]>;
+  readonly integration: Collection<readonly ["read"]>;
+};
+declare const saasPermissions: InferPermissionTree<SaasDefinition>;
+type SaasRoleName = "owner" | "admin" | "member" | "viewer" | "lead" | "collaborator";
+declare const saasRoles: { readonly [K in SaasRoleName]: Role<K>; };
+declare const saasPlans: { readonly [K in "free" | "pro"]: Plan<K>; };
+declare const saasTenantRoleNames: readonly ["owner", "admin", "member", "viewer"];
+//#endregion
+export { SaasProject as a, saasPlans as c, SaasFolderSchema as i, saasRoles as l, SaasDocSchema as n, SaasProjectSchema as o, SaasFolder as r, saasPermissions as s, SaasDoc as t, saasTenantRoleNames as u };

package/dist/permissions-CofRqesP.js

@@ -0,0 +1,142 @@
+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";
+//#region src/testing/saas/schema.ts
+function accepts(kind, value) {
+	switch (kind) {
+		case "string": return typeof value === "string";
+		case "boolean": return typeof value === "boolean";
+		case "nullable-string": return value === null || typeof value === "string";
+		default: return kind;
+	}
+}
+/** A dependency-free Standard Schema for flat fixture rows. */
+function rowSchema(shape) {
+	return { "~standard": {
+		version: 1,
+		vendor: "permdock-testing",
+		validate(value) {
+			if (typeof value !== "object" || value === null) return { issues: [{ message: "expected an object" }] };
+			const record = value;
+			const issues = [];
+			for (const [field, kind] of Object.entries(shape)) if (!accepts(kind, record[field])) issues.push({
+				message: `expected ${kind}`,
+				path: [field]
+			});
+			return issues.length > 0 ? { issues } : { value: record };
+		}
+	} };
+}
+//#endregion
+//#region src/testing/saas/permissions.ts
+const SaasProjectSchema = rowSchema({
+	id: "string",
+	orgId: "string",
+	ownerId: "string",
+	name: "string",
+	archived: "boolean"
+});
+const SaasDocSchema = rowSchema({
+	id: "string",
+	orgId: "string",
+	teamId: "nullable-string",
+	title: "string",
+	locked: "boolean"
+});
+const SaasFolderSchema = rowSchema({
+	id: "string",
+	orgId: "string",
+	parentId: "nullable-string",
+	name: "string",
+	restricted: "boolean"
+});
+const saasPermissions = definePermissions({
+	project: resource(SaasProjectSchema, crud({ relations: { org: {
+		field: "orgId",
+		memberOf: "tenant"
+	} } })),
+	doc: resource(SaasDocSchema, crud({ relations: {
+		org: {
+			field: "orgId",
+			memberOf: "tenant"
+		},
+		team: {
+			field: "teamId",
+			memberOf: "team"
+		}
+	} })),
+	folder: resource(SaasFolderSchema, crud({
+		parent: {
+			field: "parentId",
+			resource: "folder"
+		},
+		restricted: "restricted",
+		relations: {
+			org: {
+				field: "orgId",
+				memberOf: "tenant"
+			},
+			viewer: {
+				edge: "folder_share",
+				object: "folder_id",
+				expiresAt: "expires_at"
+			},
+			editor: {
+				edge: "folder_editor",
+				object: "folder_id"
+			}
+		}
+	})),
+	member: resource({ collection: [
+		"list",
+		"invite",
+		"assignRole"
+	] }),
+	settings: resource({ collection: ["manage"] }),
+	billing: resource({ collection: ["read", "manage"] }),
+	analytics: resource({ collection: ["read"] }),
+	audit: resource({ collection: ["read"] }),
+	sso: resource({ collection: ["manage"] }),
+	apiKey: resource({ collection: [
+		"manage",
+		"create",
+		"revokeAll"
+	] }),
+	integration: resource({ collection: ["read"] })
+});
+const saasRoles = defineRoles({
+	owner: {
+		on: "tenant",
+		assignable: true
+	},
+	admin: {
+		on: "tenant",
+		assignable: true
+	},
+	member: {
+		on: "tenant",
+		assignable: true
+	},
+	viewer: {
+		on: "tenant",
+		assignable: true
+	},
+	lead: {
+		on: "team",
+		assignable: true
+	},
+	/** Resource-scoped; `role(..., { on: saasPermissions.project })` in the policy. */
+	collaborator: { assignable: true }
+});
+const saasPlans = definePlans({
+	free: {},
+	pro: {}
+});
+const saasTenantRoleNames = [
+	"owner",
+	"admin",
+	"member",
+	"viewer"
+];
+//#endregion
+export { saasPlans as a, rowSchema as c, saasPermissions as i, SaasFolderSchema as n, saasRoles as o, SaasProjectSchema as r, saasTenantRoleNames as s, SaasDocSchema as t };