permdock 0.0.0 → 0.2.0

package/dist/types-C3s9xVJG.d.ts

@@ -0,0 +1,48 @@
+import { Ft as TokenVerifier, Tt as Snapshot, Yn as Decision } from "./policy-CFZAr_Al.js";
+import { f as Permission } from "./permissions-DttnqqxC.js";
+import { ReactNode } from "react";
+//#region src/react/types.d.ts
+type PermDockProviderProps = ({
+  readonly snapshot: Snapshot | string;
+  readonly snapshotPromise?: never;
+} | {
+  /**
+   * An unawaited snapshot from a Server Component. Hooks never suspend on it: until it
+   * resolves they deny with `status: 'pending'`, then re-render. A rejection fails closed
+   * (`server-only`). Set `suspend` to suspend readers through `use()` instead.
+   */
+  readonly snapshotPromise: PromiseLike<Snapshot | string>;
+  readonly snapshot?: never;
+}) & {
+  /**
+   * With `snapshotPromise`: `true` suspends every hook to the nearest Suspense boundary until it
+   * resolves, and a rejection reaches the nearest error boundary. Defaults to `false`.
+   */
+  readonly suspend?: boolean;
+  /**
+   * The AuthZEN evaluations endpoint for checks the snapshot cannot answer. `false` never
+   * fetches: those checks answer `denied` with reason `server-only`.
+   */
+  readonly endpoint?: string | false;
+  /** Where `refresh()` fetches a fresh snapshot. Defaults to `endpoint`. */
+  readonly snapshotUrl?: string;
+  readonly approvals?: string;
+  readonly tenant?: string;
+  readonly fetch?: typeof fetch;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly maxAge?: number;
+  readonly verifier?: TokenVerifier;
+  readonly children: ReactNode;
+};
+type ProtectedProps = {
+  readonly permission: Permission;
+  readonly data?: unknown;
+  readonly tenant?: string;
+  readonly pending?: ReactNode;
+  readonly fallback?: ReactNode | ((decision: Decision) => ReactNode);
+  readonly children: ReactNode | ((decision: Extract<Decision, {
+    readonly outcome: "granted";
+  }>) => ReactNode);
+};
+//#endregion
+export { ProtectedProps as n, PermDockProviderProps as t };

package/dist/types-Dnemwd77.d.ts

@@ -0,0 +1,183 @@
+import { S as ResourceRelation } from "./permissions-DttnqqxC.js";
+//#region src/catalog/types.d.ts
+type CatalogUsage = {
+  readonly file: string;
+  readonly line: number;
+  readonly call: string;
+};
+type CatalogPermission = {
+  readonly key: string;
+  readonly scope: string;
+  readonly resource: string;
+  readonly action: string;
+  readonly arity: "instance" | "collection";
+  readonly meta: Readonly<Record<string, unknown>>;
+  readonly usages: readonly CatalogUsage[];
+  /** Keys the permission was renamed from (`definePermissions` `renamed`), sorted; absent when none. */
+  readonly renamedFrom?: readonly string[];
+  /** Level names a custom role may pick for the permission (`resource(…, { levels })`); absent when none. */
+  readonly levels?: readonly string[];
+  /** Present only when the policy lists the permission in `hostable`. */
+  readonly hostable?: true;
+  /**
+   * `true` when a code grant for the key has a condition beyond role and
+   * scope, so the SQL helpers alone cannot enforce it, and when the catalog
+   * was built without the policy, which leaves it unknown.
+   */
+  readonly rowConditions: boolean;
+  /** The approvals code allows on this permission require; a hosted grant must meet each. */
+  readonly approvals?: readonly CatalogApproval[];
+  /** Present when a `breakGlass` override targets this permission. */
+  readonly breakGlass?: CatalogBreakGlass;
+};
+/** A break-glass override as the catalog carries it. */
+type CatalogBreakGlass = {
+  readonly overrides: readonly string[];
+  readonly purpose?: readonly string[];
+  readonly reason: boolean;
+  readonly maxDuration?: string;
+  readonly obligations: readonly string[];
+};
+type CatalogApproval = "human" | {
+  readonly by?: unknown;
+  readonly mode?: "any" | "all" | "sequential";
+  readonly stages?: readonly {
+    readonly by: unknown;
+    readonly quorum?: number;
+  }[];
+  readonly distinct?: boolean;
+  readonly staleOn?: "resource-change";
+  readonly quorum?: number;
+  readonly ttl?: string;
+  readonly escalation?: {
+    readonly after: string;
+    readonly to: unknown;
+  };
+};
+type CatalogResource = {
+  readonly id: string;
+  readonly schema: unknown;
+  readonly definedIn?: string;
+  readonly relations?: Readonly<Record<string, ResourceRelation>>;
+  /** The row field an `approval: { staleOn: 'resource-change' }` binds to. */
+  readonly version?: string;
+  /** The boolean column that keeps ancestor grants out of a row. */
+  readonly restricted?: string;
+  readonly restrictedStops?: readonly string[];
+};
+type CatalogRole = {
+  readonly key: string;
+  /** A declared scope name, or `resource`; absent for a global role. */
+  readonly on?: string;
+  readonly assignable?: boolean;
+  /** Fewest holders per scope instance; absent when 0. */
+  readonly min?: number;
+  readonly max?: number;
+  readonly transferOnly?: true;
+  readonly assigns?: readonly string[];
+  /** Membership kinds (`via`) that may hold the role. */
+  readonly for?: readonly string[];
+  readonly exclusiveWith?: readonly string[];
+  readonly audience?: string;
+  /** Present when the role is eligible-only and activated with `permdock.activate`. */
+  readonly activation?: CatalogActivation;
+  /** Present when the role is a `supportAccess` role. */
+  readonly supportAccess?: CatalogSupportAccess;
+};
+/** A role activation as the catalog carries it. */
+type CatalogActivation = {
+  readonly maxDuration?: string;
+  readonly justification: "required" | "optional";
+  readonly approval?: boolean;
+  readonly assurance?: {
+    readonly maxAge?: number;
+    readonly acr?: readonly string[];
+    readonly amr?: readonly string[];
+  };
+};
+/** A support-access role as the catalog carries it. */
+type CatalogSupportAccess = {
+  readonly actorRequired: boolean;
+  readonly group: string;
+  readonly durations: readonly string[];
+};
+/** One declared scope, in declaration order. */
+type CatalogScope = {
+  readonly name: string;
+  readonly key: string;
+  readonly within?: string;
+};
+/** A grant's `validFrom` / `validUntil` window in Unix seconds. */
+type CatalogValidity = {
+  readonly from?: number;
+  readonly until?: number;
+};
+/**
+ * One code grant as the catalog carries it: the normalised shape
+ * `definePolicy` produced, minus closures. `permdock diff` compares these;
+ * a hosted document is authored against them.
+ */
+type CatalogGrant = {
+  readonly permission: string;
+  readonly effect: "allow" | "deny";
+  /** The role binding the grant came from; `null` for a top-level grant. */
+  readonly role: string | null;
+  /** The grantee selector, or an array for an intersection, in its JSON form. */
+  readonly to: unknown;
+  /** `global`, a declared scope name, or `{ resource }`. */
+  readonly scope: string | {
+    readonly resource: string;
+  };
+  /** Portable condition on the current row; absent on a non-portable grant. */
+  readonly where?: unknown;
+  /** Portable condition on the next row; absent on a non-portable grant. */
+  readonly check?: unknown;
+  readonly approval?: CatalogApproval;
+  readonly fields?: readonly string[];
+  readonly validity?: CatalogValidity;
+  readonly name?: string;
+  readonly purpose?: readonly string[];
+  /** The permission key the subject must also hold through a role on the row's scope instance (`requires`). */
+  readonly requires?: string | readonly string[];
+  readonly limit?: {
+    readonly count: number;
+    readonly per: string;
+    readonly mode?: "hard" | "soft";
+  };
+  /** Present when the grant is a closure, reads the relation graph or is opaque; `where` and `check` are then omitted. */
+  readonly portable?: false;
+};
+/** `permissions.catalog.json`, validated by `schemas/catalog-v1.json`. */
+type CatalogDocument = {
+  readonly $schema: string;
+  readonly version: 1;
+  readonly generatedAt: string;
+  readonly generator: string;
+  /** `catalogFingerprint` of this document; what hosted documents pin as `catalog`. */
+  readonly fingerprint?: string;
+  readonly resources: Readonly<Record<string, CatalogResource>>;
+  readonly permissions: readonly CatalogPermission[];
+  /** The policy's scopes in order; absent when it declares none. */
+  readonly scopes?: readonly CatalogScope[];
+  readonly roles?: readonly CatalogRole[];
+  readonly plans?: readonly {
+    readonly key: string;
+  }[];
+  /** Every code grant, canonically ordered; present when the catalog was built with the policy. */
+  readonly grants?: readonly CatalogGrant[];
+  /** The policy's standing delegations, canonically ordered; present when the policy declares any. */
+  readonly delegations?: readonly CatalogDelegation[];
+};
+/** One `definePolicy({ delegations })` entry: who hands over, to which actor, which permission keys, and when. */
+type CatalogDelegation = {
+  readonly from: unknown;
+  readonly to: {
+    readonly kind: string;
+    readonly id?: string;
+    readonly client?: string;
+  };
+  readonly permissions: readonly string[];
+  readonly validity?: CatalogValidity;
+};
+//#endregion
+export { CatalogDocument as a, CatalogResource as c, CatalogSupportAccess as d, CatalogUsage as f, CatalogDelegation as i, CatalogRole as l, CatalogApproval as n, CatalogGrant as o, CatalogValidity as p, CatalogBreakGlass as r, CatalogPermission as s, CatalogActivation as t, CatalogScope as u };

package/dist/types-kxznc7cn.d.ts

@@ -0,0 +1,52 @@
+import { Cr as Actor, D as PolicyVocabulary, Nr as Principal, Yn as Decision, kr as Delegation, ln as PermDock } from "./policy-CFZAr_Al.js";
+import { f as Permission } from "./permissions-DttnqqxC.js";
+//#region src/client/types.d.ts
+type ClientStatus = "ready" | "pending" | "stale" | "server-only";
+type PermissionState = {
+  readonly allowed: boolean;
+  readonly status: ClientStatus;
+  readonly decision: Decision;
+};
+type PermissionSet = {
+  readonly granted: readonly Permission[];
+  get(permission: Permission): PermissionState | undefined;
+};
+type ClientPermDock<V extends PolicyVocabulary = PolicyVocabulary> = PermDock<V> & {
+  status(permission?: Permission, data?: unknown): ClientStatus;
+  invalidate(ref: Permission | {
+    readonly [key: string]: unknown;
+  }): void;
+  refresh(options?: {
+    readonly tenant?: string;
+  }): Promise<void>;
+  clear(): void;
+  subscribe(listener: () => void): () => void;
+};
+type ApprovalState = "not-needed" | "required" | "pending" | "approved" | "rejected" | "expired";
+type ApprovalHandle = {
+  readonly state: ApprovalState;
+  readonly token: string | undefined;
+  readonly request: (note?: string) => Promise<void>;
+};
+type SubjectView = {
+  readonly principal: Principal | null;
+  readonly actor: Actor | undefined;
+  readonly delegation: Delegation | undefined;
+  readonly expiresAt: number | undefined;
+  readonly simulated: boolean;
+};
+type TenantView = {
+  readonly tenant: string | null;
+  readonly tenants: readonly string[];
+  readonly switchTo: (id: string) => Promise<void>;
+  readonly status: ClientStatus;
+};
+type FilterResult<T> = readonly T[] & {
+  readonly partial: boolean;
+};
+type UseRolesOptions = {
+  readonly tenant?: string;
+  readonly team?: string;
+};
+//#endregion
+export { FilterResult as a, SubjectView as c, ClientStatus as i, TenantView as l, ApprovalState as n, PermissionSet as o, ClientPermDock as r, PermissionState as s, ApprovalHandle as t, UseRolesOptions as u };

package/dist/types-vKyAMtcX.d.ts

@@ -0,0 +1,157 @@
+import { G as Approver, Mr as Membership, Pr as Subject, dr as RelationGrantee, o as ApprovalStage, r as ApprovalMode } from "./policy-CFZAr_Al.js";
+//#region src/approvals/types.d.ts
+type ApprovalStatus = "pending" | "approved" | "rejected" | "expired";
+type ApprovalApprovers = {
+  /** Under `mode: 'any'` (the default). */
+  readonly by?: Approver | readonly Approver[];
+  readonly mode?: ApprovalMode;
+  /** Under `mode: 'all'` or `'sequential'`. */
+  readonly stages?: readonly ApprovalStage[];
+  /** `false` lets the request's principal approve it; absent means `true`. */
+  readonly distinct?: boolean;
+  /** Set when the approval no longer applies once the row's `version` changes. */
+  readonly staleOn?: "resource-change";
+  /** Distinct approvers of `by` needed before `status` becomes `approved`; absent means 1. */
+  readonly quorum?: number;
+  /** Who else may approve once the request has waited `after` (a duration such as `'4h'`) since `createdAt`. */
+  readonly escalation?: {
+    readonly after: string;
+    readonly to: Approver | readonly Approver[];
+  };
+};
+/** One recorded approval: who gave it, when, and under `stages` the index of the stage it counts for. */
+type ApprovalSignature = {
+  readonly by: string;
+  readonly at: string;
+  readonly stage?: number;
+  readonly vouched?: string;
+};
+type ApprovalSubjectSummary = {
+  readonly principal: {
+    readonly id: string;
+    readonly roles: readonly string[];
+    readonly tenant?: string;
+  } | null;
+  readonly actor?: {
+    readonly id: string;
+    readonly kind: string;
+  };
+  readonly session?: string;
+  readonly delegation?: {
+    readonly scopes?: readonly string[];
+    readonly authorizationDetails?: readonly unknown[];
+  };
+};
+type ApprovalRequest = {
+  readonly v: 1;
+  readonly token: string;
+  readonly permission: string;
+  readonly scope: string;
+  readonly resource: {
+    readonly type: string;
+    readonly id?: string;
+  };
+  readonly subject: ApprovalSubjectSummary;
+  readonly membership?: Membership;
+  readonly approvers?: ApprovalApprovers;
+  readonly detail: string;
+  readonly adapter?: string;
+  readonly createdAt: string;
+  readonly expiresAt: string;
+  readonly status: ApprovalStatus;
+  /** Approvals given so far, oldest first; the request is `approved` once there are `approvers.quorum` of them. */
+  readonly approvals?: readonly ApprovalSignature[];
+  readonly resolvedAt?: string;
+  /** The approver whose verdict resolved the request (the last of `approvals` on a quorum), or `system:<by>` for a cancellation. */
+  readonly resolvedBy?: string;
+  readonly vouched?: string;
+  readonly note?: string;
+  readonly consumedAt?: string;
+};
+type ApprovalVerdict = {
+  readonly status: "approved" | "rejected";
+  readonly by: Subject;
+  readonly note?: string;
+  /**
+   * The relation approvers (by `approverRelationKey`) that `by` holds on the
+   * request's resource, as `approverRelations` read them. Server-side input:
+   * set it from a `RelationSource`, never from the request body. Absent means
+   * none, so relation approvers match nobody.
+   */
+  readonly relations?: readonly string[];
+  /**
+   * The `holder(permission)` approvers (by permission key) that `by` holds
+   * in the request's tenant, as `approverPermissions` read them from the
+   * approver's own instance. Server-side input, never from the request body.
+   * Absent means none, so permission approvers match nobody.
+   */
+  readonly permissions?: readonly string[];
+  readonly vouched?: string;
+};
+type ApprovalListFilter = {
+  readonly status?: ApprovalStatus;
+  readonly principalId?: string;
+  readonly actorId?: string;
+  readonly tenant?: string;
+  readonly session?: string;
+};
+type ApprovalListQuery = ApprovalListFilter & {
+  /** Page size, 1 to 200; 50 when omitted. */
+  readonly limit?: number;
+  /** The `next` of the previous page; opaque to the caller. */
+  readonly cursor?: string;
+};
+/**
+ * One page, oldest `createdAt` first. `next` is absent on the last page; an
+ * unreadable cursor yields an empty last page.
+ */
+type ApprovalPage = {
+  readonly items: readonly ApprovalRequest[];
+  readonly next?: string;
+};
+type ApprovalCancelMeta = {
+  readonly by: string;
+  readonly note?: string;
+};
+type ApprovalStore = {
+  /**
+   * How long a request opened against this store stays open, in
+   * milliseconds, when the caller sets no `ttl`; absent means
+   * `DEFAULT_APPROVAL_TTL_MS`. A grant's `approval.ttl` still caps it.
+   */
+  readonly ttl?: number;
+  create(request: ApprovalRequest): Promise<void> | void;
+  get(token: string): Promise<ApprovalRequest | null> | ApprovalRequest | null;
+  resolve(token: string, verdict: ApprovalVerdict): Promise<ApprovalRequest> | ApprovalRequest;
+  list(query: ApprovalListQuery): Promise<ApprovalPage> | ApprovalPage;
+  expire(now?: Date): Promise<number> | number;
+  /**
+   * Marks an approved, unexpired, unconsumed request consumed and returns it;
+   * returns `null` otherwise. Must be atomic: two concurrent calls for one
+   * token never both return the request.
+   */
+  consume(token: string, now?: Date): Promise<ApprovalRequest | null> | ApprovalRequest | null;
+  cancel?(filter: ApprovalListFilter, meta: ApprovalCancelMeta): Promise<number> | number;
+};
+type ApprovalResumeFailure = "approval-not-found" | "approval-pending" | "approval-rejected" | "approval-expired" | "approval-consumed";
+type ApprovalInspectResult = {
+  readonly ok: true;
+  readonly request: ApprovalRequest;
+} | {
+  readonly ok: false;
+  readonly detail: ApprovalResumeFailure;
+};
+declare const APPROVAL_HEADER: "PermDock-Approval";
+declare const DEFAULT_APPROVAL_TTL_MS: number;
+/** The approvals a request needs in total: `approvers.quorum` (or 1), or the sum of its stages' quorums. */
+declare function approvalQuorum(request: ApprovalRequest): number;
+/**
+ * The instant from which `approvers.escalation.to` may approve, in epoch
+ * milliseconds, or `undefined` when the request has no escalation or its
+ * `after` does not parse (then nobody escalates: fail-closed).
+ */
+declare function escalationOpenAt(request: ApprovalRequest): number | undefined;
+/** The key a verdict's `relations` lists a relation approver under. */
+declare function approverRelationKey(item: RelationGrantee): string;
+//#endregion
+export { approverRelationKey as _, ApprovalListFilter as a, ApprovalRequest as c, ApprovalStatus as d, ApprovalStore as f, approvalQuorum as g, DEFAULT_APPROVAL_TTL_MS as h, ApprovalInspectResult as i, ApprovalResumeFailure as l, ApprovalVerdict as m, ApprovalApprovers as n, ApprovalListQuery as o, ApprovalSubjectSummary as p, ApprovalCancelMeta as r, ApprovalPage as s, APPROVAL_HEADER as t, ApprovalSignature as u, escalationOpenAt as v };

package/dist/types-vNSDF7Dq.d.ts

@@ -0,0 +1,66 @@
+import { D as PolicyVocabulary, ln as PermDock, rt as DecisionEvent } from "./policy-CFZAr_Al.js";
+//#region src/otel/types.d.ts
+declare const GENAI_SEMCONV_PIN = "1.37.0";
+declare const GEN_AI_TOOL_NAME = "gen_ai.tool.name";
+declare const GEN_AI_TOOL_CALL_ID = "gen_ai.tool.call.id";
+type StructuralLogger = {
+  readonly debug?: (message: string, attributes?: Record<string, unknown>) => void;
+  readonly info: (message: string, attributes?: Record<string, unknown>) => void;
+  readonly warn: (message: string, attributes?: Record<string, unknown>) => void;
+  readonly error?: (message: string, attributes?: Record<string, unknown>) => void;
+};
+type OtelSpan = {
+  readonly setAttribute?: (key: string, value: unknown) => void;
+  readonly setAttributes?: (attributes: Record<string, unknown>) => void;
+  readonly addEvent?: (name: string, attributes?: Record<string, unknown>) => void;
+  readonly recordException?: (error: unknown) => void;
+  readonly setStatus?: (status: {
+    readonly code: number;
+  }) => void;
+  readonly end?: (endTime?: number) => void;
+  readonly isRecording?: () => boolean;
+  readonly attributes?: Record<string, unknown>;
+};
+type OtelTracer = {
+  readonly startSpan: (name: string, options?: {
+    readonly startTime?: number;
+  }) => OtelSpan;
+};
+type OtelCounter = {
+  readonly add: (value: number, attributes?: Record<string, unknown>) => void;
+};
+type OtelHistogram = {
+  readonly record: (value: number, attributes?: Record<string, unknown>) => void;
+};
+type OtelMeter = {
+  readonly createCounter: (name: string) => OtelCounter;
+  readonly createHistogram: (name: string, options?: {
+    readonly unit?: string;
+    readonly description?: string;
+  }) => OtelHistogram;
+};
+type OtelApi = {
+  readonly trace: {
+    readonly getTracer: (name: string) => OtelTracer;
+    readonly getActiveSpan?: () => OtelSpan | undefined;
+  };
+  readonly metrics?: {
+    readonly getMeter: (name: string) => OtelMeter;
+  };
+};
+type OtelOptions = {
+  readonly tracer?: string;
+  readonly logger?: StructuralLogger;
+  readonly attributes?: (event: DecisionEvent) => Record<string, unknown>;
+  readonly redact?: readonly string[];
+  readonly errorOnDeny?: boolean;
+  readonly api?: OtelApi;
+};
+/**
+ * An adapter's `otel` option: wraps each request-scoped instance, usually
+ * `(permdock) => withOtel(permdock, options)` from `permdock/otel`, so an app
+ * without it does not bundle the instrumentation.
+ */
+type OtelWrap = <V extends PolicyVocabulary>(permdock: PermDock<V>) => PermDock<V>;
+//#endregion
+export { OtelOptions as a, OtelApi as i, GEN_AI_TOOL_CALL_ID as n, OtelWrap as o, GEN_AI_TOOL_NAME as r, StructuralLogger as s, GENAI_SEMCONV_PIN as t };