permdock 0.6.0 → 0.8.0

package/dist/{audience-DabClFLQ.js → audience-BAkBDMqn.js}

@@ -1,10 +1,11 @@
-import { t as whoCan } from "./who-can-DWBAcaCQ.js";
+import { t as whoCan } from "./who-can-rI7dCR9Q.js";
 //#region src/delivery/audience.ts
 async function granted(permdock, ids, permission, row) {
 	const unique = [...new Set(ids.filter((id) => typeof id === "string" && id !== ""))];
 	const decisions = await Promise.all(unique.map(async (id) => {
 		try {
-			return (await permdock.decideFor(id, permission, row)).outcome;
+			const { outcome } = await permdock.decideFor(id, permission, row);
+			return outcome;
 		} catch {
 			return "denied";
 		}
@@ -14,8 +15,8 @@ async function granted(permdock, ids, permission, row) {
 /**
 * Who may receive a delivery about `row`: the holders `whoCan` lists (or
 * `candidates`), kept only where `decideFor` grants `permission` in the
-* sender's active tenant. A collection permission has no holders to list,
-* so it needs `candidates`; without them it is empty and incomplete.
+* sender's active tenant. A collection permission has no holders to list, so it
+* needs `candidates`; without them it is empty and incomplete.
 */
 async function audience(permdock, permission, row, options = {}) {
 	if (options.candidates !== void 0) return Object.freeze({
@@ -41,10 +42,9 @@ async function audience(permdock, permission, row, options = {}) {
 	});
 }
 /**
-* The subscribers whose principal `decideFor` grants the event's
-* permission on its row, in their order: the per-event filter for webhook
-* endpoints and realtime channels. A subscriber without a string
-* `principal` is dropped.
+* The subscribers whose principal `decideFor` grants the event's permission on
+* its row, in their order: the per-event filter for webhook endpoints and
+* realtime channels. A subscriber without a string `principal` is dropped.
 */
 async function subscribersFor(permdock, event, subscribers) {
 	const ids = subscribers.map((subscriber) => subscriber.principal).filter((id) => typeof id === "string");

package/dist/{auth-DRLEizbL.js → auth--yPyZNgr.js}

@@ -1,13 +1,12 @@
 import { r as isRecord } from "./compact-CAf557ZB.js";
-import { h as secondsAt } from "./time-DkWjdL98.js";
-import { n as CliError } from "./errors-CWTY6uih.js";
-import { a as refreshCredential, c as stringField, n as discoverAuthorizationServer } from "./device-BARQ8eYG.js";
+import { h as secondsAt } from "./time-nR1JesoH.js";
+import { n as CliError } from "./errors-Vpu6rKHl.js";
+import { a as refreshCredential, c as stringField, n as discoverAuthorizationServer } from "./device-BwbJNmb2.js";
 import { i as writeCredentials, r as readCredentials, t as credentialsPath } from "./storage-C2bWdvJH.js";
+import { t as CLOUD_BASE_URL } from "./base-url-BQbddZO5.js";
 import { existsSync } from "node:fs";
 import path from "node:path";
 //#region src/cli/cloud/issuer.ts
-/** The PermDock Cloud platform issuer and API base. */
-const PLATFORM_ISSUER = "https://permdock.com/api";
 /** The public OAuth client the `permdock` binary registers as. */
 const CLI_CLIENT_ID = "permdock-cli";
 const READ_SCOPES = ["projects:read", "policy:read"];
@@ -16,9 +15,12 @@ function firstNonEmpty(...values) {
 	for (const value of values) if (value !== void 0 && value !== "") return value;
 	return "";
 }
-/** `--url`, then `PERMDOCK_CLOUD_URL`, then the platform issuer; never a trailing slash. */
+/**
+* `--url`, then `PERMDOCK_CLOUD_URL`, then the platform issuer; never a
+* trailing slash.
+*/
 function cloudUrl(flag, env) {
-	return firstNonEmpty(flag, env["PERMDOCK_CLOUD_URL"], PLATFORM_ISSUER).replace(/\/+$/u, "");
+	return firstNonEmpty(flag, env["PERMDOCK_CLOUD_URL"], CLOUD_BASE_URL).replace(/\/+$/u, "");
 }
 async function issuerMetadata(issuer, runtime) {
 	const body = await discoverAuthorizationServer(issuer, runtime);
@@ -55,7 +57,10 @@ function isHttps(value, issuer) {
 }
 //#endregion
 //#region src/cli/cloud/auth.ts
-/** The service name credentials are stored under, in the keychain or the config directory. */
+/**
+* The service name credentials are stored under, in the keychain or the config
+* directory.
+*/
 const CREDENTIAL_SERVICE = "permdock";
 /** Seconds before `expires_at` at which a stored access token counts as expired. */
 const EXPIRY_SKEW_SECONDS = 30;
@@ -99,7 +104,10 @@ function repositoryRoot(cwd) {
 		dir = parent;
 	}
 }
-/** The credentials file when it would land inside the repository at `cwd`; `null` when it is outside. */
+/**
+* The credentials file when it would land inside the repository at `cwd`;
+* `null` when it is outside.
+*/
 function credentialsInsideRepository(cwd, runtime) {
 	const root = repositoryRoot(cwd);
 	if (root === null) return null;
@@ -160,7 +168,10 @@ async function readAuth(command, issuer, env, runtime) {
 		source: "login"
 	};
 }
-/** The bearer for `cloud push`: `PERMDOCK_CLOUD_KEY`, then a login holding `catalog:write`. */
+/**
+* The bearer for `cloud push`: `PERMDOCK_CLOUD_KEY`, then a login holding
+* `catalog:write`.
+*/
 async function pushAuth(issuer, env, runtime) {
 	const key = env["PERMDOCK_CLOUD_KEY"];
 	if (key !== void 0 && key !== "") return {

package/dist/authzen/index.d.ts

@@ -1,7 +1,92 @@
-import { T as Policy, rr as Principal } from "../policy-types-n0uRTsW8.js";
-import { m as ApprovalStore } from "../types-BdtSDbBO.js";
-import { t as InstanceOptions } from "../instance-options-BsVpyGIk.js";
-import { a as evaluationsSemantic, n as EvaluationsSemantic, r as evaluateBatch, t as EVALUATIONS_SEMANTICS } from "../evaluations-C_1vdSZc.js";
+import { T as Policy, Zn as Actor, rr as Delegation, sr as Principal } from "../policy-types-CCiDRZBH.js";
+import { m as ApprovalStore } from "../types-B_tiYvk8.js";
+import { a as ProblemDetails } from "../errors-zi_4T-rx.js";
+import { t as InstanceOptions } from "../instance-options-B0KXqTrJ.js";
+import { a as evaluationsSemantic, n as EvaluationsSemantic, r as evaluateBatch, t as EVALUATIONS_SEMANTICS } from "../evaluations-z8dQFDaN.js";
+//#region src/authzen/map.d.ts
+type AuthzenEntity = {
+  readonly type?: unknown;
+  readonly id?: unknown;
+  readonly properties?: unknown;
+  readonly name?: unknown;
+};
+type AuthzenItem = {
+  readonly subject?: AuthzenEntity;
+  readonly action?: AuthzenEntity;
+  readonly resource?: AuthzenEntity;
+  readonly context?: unknown;
+};
+/**
+ * One item of an `evaluations` batch with the request's top-level `subject`,
+ * `action`, `resource` and `context` filled in where the item omits them.
+ */
+export declare function mergeEvaluationItem(shared: AuthzenItem, item: unknown): AuthzenItem;
+//#endregion
+//#region src/authzen/search.d.ts
+/** One `search/action` result. */
+type AuthzenAction = {
+  readonly name: string;
+};
+/** One `search/subject` result. */
+type AuthzenSubject = {
+  readonly type: "user";
+  readonly id: string;
+};
+/**
+ * What `search/subject` asks a lister for: candidates of `type` for one action
+ * on one resource.
+ */
+type AuthzenSubjectQuery = {
+  readonly type: string;
+  readonly action: AuthzenEntity;
+  readonly resource: AuthzenEntity;
+  readonly context?: unknown;
+};
+/**
+ * The principals a policy decision point may answer `search/subject` with, the
+ * way `AuthzenResourceAdapter.list` supplies rows. Each record is decided as `{
+ * type: "user", id, properties }`; only candidates that are granted are
+ * returned, so a lister may answer a superset.
+ */
+type AuthzenSubjectLister = {
+  readonly name?: string;
+  readonly list: (query: AuthzenSubjectQuery) => readonly AuthzenSubjectRecord[] | Promise<readonly AuthzenSubjectRecord[]>;
+};
+type AuthzenSearchOptions = InstanceOptions & {
+  readonly tenant?: string;
+  readonly actor?: Actor;
+  readonly delegation?: Delegation;
+};
+type SearchActionsOptions = AuthzenSearchOptions & {
+  /**
+   * The row the server loaded for `resource`, trusted. Without it the
+   * resource's `properties` (or `{ id }`) are boundary-validated.
+   */
+  readonly data?: unknown;
+};
+/**
+ * The AuthZEN `search/action` answer for `user` on `resource`: every permission
+ * of `resource.type` in the policy is decided, and the distinct actions of the
+ * granted ones are returned in catalog order. Paging is the caller's
+ * (`authzenPage`).
+ */
+export declare function searchActions<TUser, TPrincipal extends Principal = Principal>(policy: Policy<TUser, TPrincipal>, user: TUser, resource: AuthzenEntity & {
+  readonly type: string;
+}, options?: SearchActionsOptions): Promise<readonly AuthzenAction[]>;
+/**
+ * The AuthZEN `search/subject` answer: the candidates `lister` returns for
+ * `request`, each decided as itself, filtered to those granted `action` on
+ * `resource`. An unknown action, a subject type other than `user`, or a lister
+ * that throws answers none.
+ */
+export declare function searchSubjects<TUser, TPrincipal extends Principal = Principal>(policy: Policy<TUser, TPrincipal>, lister: AuthzenSubjectLister, request: AuthzenItem & {
+  readonly subject: {
+    readonly type: string;
+  };
+  readonly action: AuthzenEntity;
+  readonly resource: AuthzenEntity;
+}, options?: AuthzenSearchOptions): Promise<readonly AuthzenSubject[]>;
+//#endregion
 //#region src/authzen/types.d.ts
 type AuthzenResourceAdapter = {
   readonly data?: (id: string) => unknown;
@@ -17,15 +102,14 @@ type AuthzenPermDockOptions<TUser = unknown> = InstanceOptions & {
   readonly subject: (request: Request) => TUser | Promise<TUser>;
   readonly anonymous?: boolean;
   /**
-   * Allow-list over the authenticated PEP. Only a PEP it returns `true` for
-   * may evaluate the body's `subject`, `actor` and `delegation`; every other
-   * caller is evaluated as itself. Off by default.
+   * Allow-list over the authenticated PEP. Only a PEP it returns `true` for may
+   * evaluate the body's `subject`, `actor` and `delegation`; every other caller
+   * is evaluated as itself. Off by default.
    */
   readonly trustedPep?: (pep: unknown) => boolean;
   readonly resources?: Readonly<Record<string, AuthzenResourceAdapter>>;
-  readonly subjects?: {
-    readonly list?: () => readonly AuthzenSubjectRecord[] | Promise<readonly AuthzenSubjectRecord[]>;
-  };
+  /** Enables `search/subject`; discovery advertises it only when set. */
+  readonly subjects?: AuthzenSubjectLister;
   readonly store?: ApprovalStore;
   readonly maxEvaluations?: number;
 };
@@ -37,23 +121,85 @@ type AuthzenFactory = <TUser, TPrincipal extends Principal = Principal>(policy:
 //#region src/authzen/create.d.ts
 export declare const createPermDock: AuthzenFactory;
 //#endregion
-//#region src/authzen/map.d.ts
-type AuthzenEntity = {
-  readonly type?: unknown;
-  readonly id?: unknown;
-  readonly properties?: unknown;
-  readonly name?: unknown;
+//#region src/authzen/page.d.ts
+/** The largest page a search answers; a larger `page.limit` is capped to it. */
+export declare const AUTHZEN_MAX_PAGE = 200;
+/** Where a search page starts and how many results it holds. */
+type AuthzenPageRequest = {
+  readonly offset: number;
+  readonly size: number;
 };
-type AuthzenItem = {
-  readonly subject?: AuthzenEntity;
-  readonly action?: AuthzenEntity;
-  readonly resource?: AuthzenEntity;
-  readonly context?: unknown;
+type AuthzenPage<T> = {
+  readonly results: readonly T[];
+  readonly page: {
+    /**
+     * The offset of the next page as a decimal string, or `""` on the last
+     * page.
+     */
+    readonly next_token: string;
+    readonly count: number;
+    readonly total: number;
+  };
 };
 /**
- * One item of an `evaluations` batch with the request's top-level `subject`,
- * `action`, `resource` and `context` filled in where the item omits them.
+ * The page a search body asks for. The token is `page.token`, else
+ * `page.next_token`, read as a decimal offset; anything else starts at 0. The
+ * size is `page.limit`, else `page.size`, capped at 200 and 50 by default.
  */
-export declare function mergeEvaluationItem(shared: AuthzenItem, item: unknown): AuthzenItem;
+export declare function readAuthzenPage(body: unknown): AuthzenPageRequest;
+/** One page of `items` with the AuthZEN `page` object. */
+export declare function authzenPage<T>(items: readonly T[], request: AuthzenPageRequest): AuthzenPage<T>;
+/** The answer to a search the PDP cannot run: no results and no next page. */
+export declare function emptyAuthzenPage<T>(): AuthzenPage<T>;
+//#endregion
+//#region src/authzen/parse.d.ts
+type AuthzenRequestKind = "evaluation" | "evaluations" | "search/subject" | "search/resource" | "search/action";
+type AuthzenSearchKind = Extract<AuthzenRequestKind, `search/${string}`>;
+/**
+ * A checked AuthZEN request. An `evaluations` body with no items is the single
+ * evaluation AuthZEN 1.0 section 7.1 makes it, so it parses as `kind:
+ * "evaluation"`; the `evaluations` items already carry the shared top-level
+ * fields.
+ */
+type AuthzenRequest = AuthzenEvaluationRequest | AuthzenEvaluationsRequest | AuthzenSearchRequest;
+type AuthzenEvaluationRequest = {
+  readonly kind: "evaluation";
+  readonly item: AuthzenItem;
+};
+type AuthzenEvaluationsRequest = {
+  readonly kind: "evaluations";
+  readonly semantic: EvaluationsSemantic;
+  readonly items: readonly AuthzenItem[];
+};
+type AuthzenSearchRequest<K extends AuthzenSearchKind = AuthzenSearchKind> = {
+  readonly kind: K;
+  readonly item: AuthzenItem;
+  readonly page: AuthzenPageRequest;
+};
+/** The requests a body for `kind` can parse into. */
+type AuthzenRequestOf<K extends AuthzenRequestKind> = K extends "evaluation" ? AuthzenEvaluationRequest : K extends "evaluations" ? AuthzenEvaluationRequest | AuthzenEvaluationsRequest : K extends AuthzenSearchKind ? AuthzenSearchRequest<K> : never;
+type ParseAuthzenRequestResult<R extends AuthzenRequest = AuthzenRequest> = {
+  readonly ok: true;
+  readonly request: R;
+} | {
+  readonly ok: false;
+  readonly problem: ProblemDetails;
+};
+type ParseAuthzenRequestOptions = {
+  /** The largest `evaluations` batch; default 256. A larger one is a 413. */
+  readonly maxEvaluations?: number;
+};
+/**
+ * Checks a parsed AuthZEN body the way `permdock/authzen` answers it: the body
+ * is an object, then each required entity and field in a fixed order, then the
+ * `evaluations` array, batch size and semantic. A failure is the 400 (or 413)
+ * Problem Details the handler sends, with the same `detail`.
+ */
+export declare function parseAuthzenRequest<K extends AuthzenRequestKind>(kind: K, body: unknown, options?: ParseAuthzenRequestOptions): ParseAuthzenRequestResult<AuthzenRequestOf<K>>;
+/**
+ * Reads `request` as an AuthZEN body: `Content-Type: application/json`, at most
+ * 1 MiB (a 413 above it), valid JSON, then `parseAuthzenRequest`.
+ */
+export declare function readAuthzenRequest<K extends AuthzenRequestKind>(kind: K, request: Request, options?: ParseAuthzenRequestOptions): Promise<ParseAuthzenRequestResult<AuthzenRequestOf<K>>>;
 //#endregion
-export { type AuthzenEntity, type AuthzenFactory, type AuthzenItem, type AuthzenPermDock, type AuthzenPermDockOptions, type AuthzenResourceAdapter, type AuthzenSubjectRecord, EVALUATIONS_SEMANTICS, type EvaluationsSemantic, evaluateBatch, evaluationsSemantic };
+export { type AuthzenAction, type AuthzenEntity, type AuthzenEvaluationRequest, type AuthzenEvaluationsRequest, type AuthzenFactory, type AuthzenItem, type AuthzenPage, type AuthzenPageRequest, type AuthzenPermDock, type AuthzenPermDockOptions, type AuthzenRequest, type AuthzenRequestKind, type AuthzenRequestOf, type AuthzenResourceAdapter, type AuthzenSearchKind, type AuthzenSearchOptions, type AuthzenSearchRequest, type AuthzenSubject, type AuthzenSubjectLister, type AuthzenSubjectQuery, type AuthzenSubjectRecord, EVALUATIONS_SEMANTICS, type EvaluationsSemantic, type ParseAuthzenRequestOptions, type ParseAuthzenRequestResult, type SearchActionsOptions, evaluateBatch, evaluationsSemantic };