permdock 0.0.0 → 0.2.0

package/dist/permissions-DttnqqxC.d.ts

@@ -0,0 +1,214 @@
+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>>;
+/**
+ * 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. 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 = {
+  /** 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;
+};
+/** 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 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> = {
+  /**
+   * 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 | 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;
+  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 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;
+};
+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 { 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/pins-8ILTftC9.js

@@ -0,0 +1,12 @@
+//#region src/openapi/pins.ts
+const DRAFT_PINS = {
+	oas: "3.3-dev@2026-09-01",
+	securityProfiles: "oai-discussion-5304@2026-09-01",
+	overlay: "1.2-dev@edd4adea"
+};
+const PROFILE_NAMES = { fapi2: "fapi-20-security-profile" };
+/** PermDock's published `supportedParametersSchema` per profile, stable across pins. */
+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 };