permdock 0.6.0 → 0.8.0

package/dist/cloud/index.d.ts

@@ -1,29 +1,169 @@
-import { Jt as AutomationEvent, Kt as AccessEvent, Qt as DeliveryEvent, Rt as Instant, Xt as DecisionEvent, Yt as CredentialEvent, Zt as DeliveryChannel, en as DirectoryEvent, nn as MembershipEvent, ut as TokenSigner } from "../policy-types-n0uRTsW8.js";
-import { m as ApprovalStore } from "../types-BdtSDbBO.js";
-import { i as CatalogEventData, l as CloudEventType, r as CLOUD_EVENT_TYPES, s as CloudEvent } from "../sink-4-eQIRWf.js";
-import { c as DeliveryTransport } from "../types-BtHtcKMr.js";
-import { a as CloudConnectionOptions, c as CloudOptions, i as CloudClient, l as CloudSignerOptions, n as CloudCatalog, o as CloudEndpointOptions, r as CloudCatalogPush, s as CloudEndpoints, t as CloudApproverOptions } from "../types-8RnwUAvE.js";
-import { n as ApprovalWaiter } from "../waiter-B986w1oK.js";
-import { l as ReplayStore } from "../types-C791HFu9.js";
-import { f as WebhookVerifier, r as WebhookFailureCause$1, s as WebhookJwks } from "../standard-webhooks-rbD7LS6h.js";
+import { $t as CredentialEvent, Qt as AutomationEvent, Rt as Instant, Xt as AccessEvent, en as DecisionEvent, in as DirectoryEvent, nn as DeliveryEvent, on as MembershipEvent, tn as DeliveryChannel, ut as TokenSigner } from "../policy-types-CCiDRZBH.js";
+import { m as ApprovalStore } from "../types-B_tiYvk8.js";
+import { i as CatalogEventData, l as CloudEventType, r as CLOUD_EVENT_TYPES, s as CloudEvent } from "../sink-Dvi7YZG_.js";
+import { c as DeliveryTransport } from "../types-yUuPR5Hy.js";
+import { a as CloudConnectionOptions, c as CloudOptions, i as CloudClient, l as CloudSignerOptions, n as CloudCatalog, o as CloudEndpointOptions, r as CloudCatalogPush, s as CloudEndpoints, t as CloudApproverOptions } from "../types-AMJ5qoU_.js";
+import { n as ApprovalWaiter } from "../waiter-Bu9zAlE0.js";
+import { l as ReplayStore } from "../types-DjuMBNF9.js";
+import { f as WebhookVerifier, r as WebhookFailureCause$1, s as WebhookJwks } from "../standard-webhooks-C-qX4mJW.js";
+//#region src/cloud/base-url.d.ts
+/**
+ * The one base URL of PermDock Cloud. The platform issuer is this URL; its
+ * OAuth routes, `/.well-known/oauth-authorization-server` and `/openapi.json`
+ * sit at the root, unversioned, and the data routes under `/v1`.
+ */
+export declare const CLOUD_BASE_URL = "https://permdock.com/api";
+/** The scopes the platform issuer grants a person's login. */
+type CloudScope = "projects:read" | "policy:read" | "catalog:write" | "evidence:read" | "approvals:read";
+//#endregion
 //#region src/cloud/request.d.ts
 /**
- * The environment URL and JWK Set URL `cloud()` uses, resolved with the same
- * fallbacks (`PERMDOCK_CLOUD_URL`; `PERMDOCK_CLOUD_ENV`, `VERCEL_ENV`, `production`).
+ * The environment URL and JWK Set URL `cloud()` uses when the environment is
+ * configured: `environment`, else `PERMDOCK_CLOUD_ENV`. Throws when neither is
+ * set; `resolveCloudEndpoints` then asks the Cloud which environment the key
+ * belongs to.
  */
 export declare function cloudEndpoints(options?: CloudEndpointOptions): CloudEndpoints;
+/**
+ * The environment URL and JWK Set URL for a key: `cloudEndpoints(options)` when
+ * the environment is configured, else the environment `GET /v1/environment`
+ * names for `key` (`PERMDOCK_CLOUD_KEY`). Rejects when the Cloud does not
+ * answer or answers another issuer.
+ */
+export declare function resolveCloudEndpoints(options?: CloudConnectionOptions): Promise<CloudEndpoints>;
 //#endregion
 //#region src/cloud/create.d.ts
 export declare function cloud(options?: CloudOptions): CloudClient;
 //#endregion
+//#region src/cloud/oauth.d.ts
+type CloudOAuthOptions = {
+  /** The client id the dashboard issued, or one from `/oauth/register`. */
+  readonly clientId: string;
+  /**
+   * Registered with the client; the Cloud redirects here with `code` and
+   * `state`.
+   */
+  readonly redirectUri: string;
+  /**
+   * A confidential client's secret, sent as `client_secret_basic` (RFC 6749
+   * section 2.3.1). Server-only.
+   */
+  readonly clientSecret?: string;
+  /** The Cloud base URL and platform issuer; defaults to `CLOUD_BASE_URL`. */
+  readonly url?: string;
+  /** Requested on `authorizeUrl`; defaults to `projects:read` and `policy:read`. */
+  readonly scopes?: readonly CloudScope[];
+  readonly fetch?: typeof fetch;
+  /** The clock `expires_at` is computed from; defaults to the system clock. */
+  readonly now?: () => Instant;
+};
+/**
+ * A token response, with RFC 6749 field names; `expires_at` is seconds since
+ * the epoch.
+ */
+type CloudCredential = {
+  readonly access_token: string;
+  readonly token_type?: string;
+  readonly expires_at?: number;
+  readonly refresh_token?: string;
+  readonly scope?: string;
+};
+/**
+ * A started authorization. Keep `state` and `codeVerifier` server-side until
+ * the callback.
+ */
+type CloudAuthorization = {
+  /** Where to send the browser. */
+  readonly url: string;
+  readonly state: string;
+  readonly codeVerifier: string;
+};
+/**
+ * `GET /v1/projects` item. A project is one environment: `id` is the `{env}` of
+ * `/v1/environments/{env}`.
+ */
+type CloudProject = {
+  readonly id: string;
+  readonly name: string;
+  readonly environment: string;
+  readonly slug?: string;
+  readonly issuer?: string;
+  readonly catalog?: {
+    readonly version: number;
+    readonly fingerprint: string;
+  };
+  readonly updatedAt?: string;
+};
+type CloudProjectPage = {
+  readonly items: readonly CloudProject[];
+  /** Pass back as `cursor` for the next page. */
+  readonly next?: string;
+};
+type CloudOAuthClient = {
+  /** The platform issuer the client discovers its endpoints from. */
+  readonly issuer: string;
+  /** An authorization code request with PKCE `S256` and a fresh `state`. */
+  readonly authorizeUrl: (options?: {
+    readonly scopes?: readonly CloudScope[];
+  }) => Promise<CloudAuthorization>;
+  /**
+   * Redeems the callback URL. Throws `state-mismatch` unless it echoes
+   * `pending.state`, `issuer-mismatch` for an RFC 9207 `iss` of another server,
+   * and `authorization-denied` for an `error` or a missing `code`.
+   */
+  readonly exchangeCode: (callback: string | URL, pending: Pick<CloudAuthorization, "state" | "codeVerifier">) => Promise<CloudCredential>;
+  readonly refresh: (refreshToken: string) => Promise<CloudCredential>;
+  /** `GET /v1/projects` with a login holding `projects:read`. */
+  readonly listProjects: (accessToken: string, options?: {
+    readonly cursor?: string;
+  }) => Promise<CloudProjectPage>;
+};
+/**
+ * An OAuth 2.0 client of the PermDock Cloud platform issuer, for an app that
+ * signs its users in to PermDock Cloud and reads their projects. Endpoints come
+ * from the issuer's RFC 8414 metadata; every call throws a `CloudAuthError`.
+ */
+export declare function cloudOAuth(options: CloudOAuthOptions): CloudOAuthClient;
+//#endregion
+//#region src/cloud/oauth-error.d.ts
+type CloudAuthErrorCode = "discovery-failed" | "state-mismatch" | "issuer-mismatch" | "authorization-denied" | "token-refused" | "invalid-token" | "insufficient-scope" | "forbidden" | "rate-limited" | "unreachable" | "unexpected-response";
+type CloudAuthErrorDetails = {
+  /** The HTTP status, when the Cloud answered. */
+  readonly status?: number;
+  /**
+   * The RFC 6749 or RFC 6750 `error` the Cloud sent (`invalid_grant`,
+   * `insufficient_scope`).
+   */
+  readonly error?: string;
+  /** The scope an `insufficient_scope` challenge names. */
+  readonly scope?: string;
+};
+/**
+ * A failed `cloudOAuth` call. `code` tells a dead token (`invalid-token`) from
+ * a missing scope (`insufficient-scope`).
+ */
+export declare class CloudAuthError extends Error {
+  override readonly name: "CloudAuthError";
+  readonly code: CloudAuthErrorCode;
+  readonly status: number | undefined;
+  readonly error: string | undefined;
+  readonly scope: string | undefined;
+  constructor(code: CloudAuthErrorCode, message: string, details?: CloudAuthErrorDetails);
+}
+/**
+ * Matches by `name` and `code`, so an error from another copy of the module
+ * still maps.
+ */
+export declare function isCloudAuthError(value: unknown): value is CloudAuthError;
+//#endregion
 //#region src/cloud/delivery.d.ts
 /**
  * A `DeliveryTransport` for `channel` that hands each checked recipient to
- * PermDock Cloud, which sends it from its hosted email, chat or webhook
- * sender and reports back through `com.permdock.delivery.*` events. The
- * router has already decided the recipient: the Cloud receives the target
- * and the permission that let it through, never a decision to make.
- * `Idempotency-Key` is the delivery's idempotency key, so a retry repeats it.
+ * PermDock Cloud, which sends it from its hosted email, chat or webhook sender
+ * and reports back through `com.permdock.delivery.*` events. The router has
+ * already decided the recipient: the Cloud receives the target and the
+ * permission that let it through, never a decision to make. `Idempotency-Key`
+ * is the delivery's idempotency key, so a retry repeats it.
  */
 export declare function cloudDeliveryTransport<C extends DeliveryChannel>(channel: C, options?: CloudConnectionOptions): DeliveryTransport<C>;
 //#endregion
@@ -31,11 +171,11 @@ export declare function cloudDeliveryTransport<C extends DeliveryChannel>(channe
 /**
  * A `TokenSigner` backed by the environment's PermDock Cloud keys, typically
  * KMS-held, for run tickets (`vnd.permdock.run+jwt`) and every other signed
- * output an app issues. The Cloud signs only what the app sends: it sets
- * `iss` to the environment URL and adds no claim. Policy documents,
- * snapshots, evidence exports, Security Event Tokens and `at+jwt` access tokens are the Cloud's own
- * outputs, so their `typ` values are refused here. Verify what it signs with
- * `joseTokenVerifier({ jwks: cloudEndpoints().jwks })`.
+ * output an app issues. The Cloud signs only what the app sends: it sets `iss`
+ * to the environment URL and adds no claim. Policy documents, snapshots,
+ * evidence exports, Security Event Tokens and `at+jwt` access tokens are the
+ * Cloud's own outputs, so their `typ` values are refused here. Verify what it
+ * signs with `joseTokenVerifier({ jwks: cloudEndpoints().jwks })`.
  */
 export declare function cloudSigner(options?: CloudSignerOptions): TokenSigner;
 //#endregion
@@ -49,8 +189,8 @@ type Types = typeof CLOUD_EVENT_TYPES;
 type PermDockCloudEvent = Envelope<Types["decision"], DecisionEvent> | Envelope<Types["approvalRequested"] | Types["approvalResolved"] | Types["approvalExpired"] | Types["approvalCancelled"], DecisionEvent> | Envelope<Types["directoryCreated"] | Types["directoryReplaced"] | Types["directoryPatched"] | Types["directoryDeleted"], DirectoryEvent> | Envelope<Types["membershipAdded"] | Types["membershipRemoved"] | Types["membershipChanged"], MembershipEvent> | Envelope<Types["credentialCreated"] | Types["credentialUsed"] | Types["credentialRotated"] | Types["credentialRevoked"], CredentialEvent> | Envelope<Types["catalogPublished"] | Types["catalogDrifted"], CatalogEventData> | Envelope<Types["supportSessionStarted"] | Types["supportSessionEnded"], AccessEvent> | Envelope<Types["automationPublished"] | Types["automationChanged"] | Types["automationRevoked"] | Types["automationRun"], AutomationEvent> | Envelope<Types["deliverySent"] | Types["deliveryDelivered"] | Types["deliveryBounced"] | Types["deliveryComplained"] | Types["deliveryFailed"], DeliveryEvent>;
 type WebhookOptions = {
   /**
-   * A verifier to reuse across deliveries, so the JWKS is fetched once;
-   * built from `jwks`, `secret`, `replay`, `tolerance` and `now` when absent.
+   * A verifier to reuse across deliveries, so the JWKS is fetched once; built
+   * from `jwks`, `secret`, `replay`, `tolerance` and `now` when absent.
    */
   readonly verifier?: WebhookVerifier;
   /** `cloud().jwks`, a JWKS URL or an inline key set, for `v1a` signatures. */
@@ -64,7 +204,10 @@ type WebhookOptions = {
   readonly now?: () => Instant;
   readonly fetch?: typeof fetch;
 };
-/** The Standard Webhooks verifier's cause, or `invalid-events` for a signed body that is not a CloudEvents batch. */
+/**
+ * The Standard Webhooks verifier's cause, or `invalid-events` for a signed body
+ * that is not a CloudEvents batch.
+ */
 type WebhookFailureCause = WebhookFailureCause$1 | "invalid-events";
 type VerifiedWebhook = {
   readonly ok: true;
@@ -83,8 +226,8 @@ type VerifiedWebhook = {
  */
 export declare function parseCloudEvent(value: unknown): PermDockCloudEvent | null;
 /**
- * Verifies a PermDock Cloud webhook delivery: Standard Webhooks headers over
- * an `application/cloudevents-batch+json` body (or one
+ * Verifies a PermDock Cloud webhook delivery: Standard Webhooks headers over an
+ * `application/cloudevents-batch+json` body (or one
  * `application/cloudevents+json` event). There is no unsigned mode, and it
  * never throws.
  */
@@ -92,13 +235,19 @@ export declare function verifyWebhook(request: Request, options: WebhookOptions)
 //#endregion
 //#region src/cloud/waiter.d.ts
 type CloudApprovalWaiterOptions = WebhookOptions & ({
-  /** Read when a wait starts and every `interval` after; typically `cloud().approvals`. */
+  /**
+   * Read when a wait starts and every `interval` after; typically
+   * `cloud().approvals`.
+   */
   readonly store: ApprovalStore;
   /** Milliseconds between fallback reads of `store`. Defaults to 60000. */
   readonly interval?: number;
   readonly waiter?: undefined;
 } | {
-  /** A durable runner's waiter (`workflowSdkWaiter()`); `wait` and `wake` go to it. */
+  /**
+   * A durable runner's waiter (`workflowSdkWaiter()`); `wait` and `wake`
+   * go to it.
+   */
   readonly waiter: ApprovalWaiter;
   readonly store?: undefined;
   readonly interval?: undefined;
@@ -107,23 +256,22 @@ type CloudApprovalWaiter = ApprovalWaiter & {
   /**
    * The endpoint for the environment's webhook connector. It verifies the
    * Standard Webhooks signature and wakes the wait of every
-   * `com.permdock.approval.resolved`, `.expired` and `.cancelled` event in
-   * the batch. It answers `204` once handled or replayed, and Problem
-   * Details otherwise.
+   * `com.permdock.approval.resolved`, `.expired` and `.cancelled` event in the
+   * batch. It answers `204` once handled or replayed, and Problem Details
+   * otherwise.
    */
   readonly webhook: (request: Request) => Promise<Response>;
 };
 /** The approval token of each event that ends a wait, in delivery order. */
 export declare function approvalTokensOf(events: readonly PermDockCloudEvent[]): readonly string[];
 /**
- * An `ApprovalWaiter` that PermDock Cloud wakes. Mount `webhook` on the
- * route the environment's webhook connector posts to: when an approval is
- * resolved, expires or is cancelled, the parked run for its token wakes.
- * Waking never approves anything. The run decides again with the token, and
- * only the app's `decide` and its approval store can grant. Without
- * `waiter`, waits poll `store` as a fallback for a webhook another process
- * received.
+ * An `ApprovalWaiter` that PermDock Cloud wakes. Mount `webhook` on the route
+ * the environment's webhook connector posts to: when an approval is resolved,
+ * expires or is cancelled, the parked run for its token wakes. Waking never
+ * approves anything. The run decides again with the token, and only the app's
+ * `decide` and its approval store can grant. Without `waiter`, waits poll
+ * `store` as a fallback for a webhook another process received.
  */
 export declare function cloudApprovalWaiter(options: CloudApprovalWaiterOptions): CloudApprovalWaiter;
 //#endregion
-export type { CloudApprovalWaiter, CloudApprovalWaiterOptions, CloudApproverOptions, CloudCatalog, CloudCatalogPush, CloudClient, CloudConnectionOptions, CloudEndpointOptions, CloudEndpoints, CloudOptions, CloudSignerOptions, PermDockCloudEvent, VerifiedWebhook, WebhookFailureCause, WebhookOptions };
+export type { CloudApprovalWaiter, CloudApprovalWaiterOptions, CloudApproverOptions, CloudAuthErrorCode, CloudAuthErrorDetails, CloudAuthorization, CloudCatalog, CloudCatalogPush, CloudClient, CloudConnectionOptions, CloudCredential, CloudEndpointOptions, CloudEndpoints, CloudOAuthClient, CloudOAuthOptions, CloudOptions, CloudProject, CloudProjectPage, CloudScope, CloudSignerOptions, PermDockCloudEvent, VerifiedWebhook, WebhookFailureCause, WebhookOptions };

package/dist/cloud/index.js

@@ -1,13 +1,276 @@
 import { r as isRecord, t as compact } from "../compact-CAf557ZB.js";
-import { n as freezeDeep } from "../freeze-CrU8nQeX.js";
-import { o as statusProblem } from "../problem-details-cn5X30gZ.js";
-import { r as CLOUD_EVENT_TYPES } from "../sink-BEZSlMS_.js";
-import { i as parseCloudEventBatch, r as parseCloudEvent$1 } from "../catalog-fingerprint-CCP0-yQS.js";
-import { c as problemResponse } from "../problem-CTviyH5L.js";
-import { n as webhookVerifier } from "../standard-webhooks-DgFFD-Ga.js";
-import { t as pollingApprovalWaiter } from "../waiter-BGUtGYoU.js";
-import { i as isDeliveryTarget } from "../target-Bw37TFNA.js";
-import { i as isCompactJws, n as cloudConnection, r as cloudEndpoints, t as cloud } from "../create-CQWIpUG-.js";
+import { n as freezeDeep } from "../freeze-jjan0lCv.js";
+import { o as statusProblem } from "../problem-details-CLDgX1KV.js";
+import { h as secondsAt } from "../time-nR1JesoH.js";
+import { r as CLOUD_EVENT_TYPES } from "../sink-D9_vh372.js";
+import { i as parseCloudEventBatch, r as parseCloudEvent$1 } from "../catalog-fingerprint-e6aCWosn.js";
+import { n as readBodyText } from "../body-text-DQhcmqdY.js";
+import { l as problemResponse } from "../problem-BVLHFK33.js";
+import { t as timeoutSignal } from "../timeout-D51niuQP.js";
+import { n as webhookVerifier } from "../standard-webhooks-D67a3nzk.js";
+import { c as stringField, n as discoverAuthorizationServer, r as parseToken } from "../device-BwbJNmb2.js";
+import { t as pollingApprovalWaiter } from "../waiter-aBLM63_f.js";
+import { i as isDeliveryTarget } from "../target-qdEAnnhU.js";
+import { t as CLOUD_BASE_URL } from "../base-url-BQbddZO5.js";
+import { a as isCompactJws, i as cloudEndpoints, n as cloud, o as resolveCloudEndpoints, r as cloudConnection, t as bearerChallenge } from "../challenge-DImNcR7B.js";
+import { n as randomToken, t as pkce } from "../pkce-CnmmYqUZ.js";
+//#region src/cloud/oauth-error.ts
+/**
+* A failed `cloudOAuth` call. `code` tells a dead token (`invalid-token`) from
+* a missing scope (`insufficient-scope`).
+*/
+var CloudAuthError = class extends Error {
+	name = "CloudAuthError";
+	code;
+	status;
+	error;
+	scope;
+	constructor(code, message, details = {}) {
+		super(message);
+		this.code = code;
+		this.status = details.status;
+		this.error = details.error;
+		this.scope = details.scope;
+	}
+};
+const CODES = /* @__PURE__ */ new Set([
+	"discovery-failed",
+	"state-mismatch",
+	"issuer-mismatch",
+	"authorization-denied",
+	"token-refused",
+	"invalid-token",
+	"insufficient-scope",
+	"forbidden",
+	"rate-limited",
+	"unreachable",
+	"unexpected-response"
+]);
+/**
+* Matches by `name` and `code`, so an error from another copy of the module
+* still maps.
+*/
+function isCloudAuthError(value) {
+	if (!(value instanceof Error) || value.name !== "CloudAuthError") return false;
+	const code = Reflect.get(value, "code");
+	return typeof code === "string" && CODES.has(code);
+}
+//#endregion
+//#region src/cloud/oauth.ts
+/**
+* Milliseconds a Cloud OAuth or read request may take; a slower one fails with
+* `unreachable`.
+*/
+const OAUTH_TIMEOUT_MS = 1e4;
+const DEFAULT_SCOPES = ["projects:read", "policy:read"];
+function trimSlash(value) {
+	return value.replace(/\/+$/u, "");
+}
+/**
+* The form-urlencoding RFC 6749 section 2.3.1 applies to client_secret_basic
+* credentials.
+*/
+function formEncode(value) {
+	return encodeURIComponent(value).replaceAll("%20", "+");
+}
+function isLoopback(hostname) {
+	return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+/**
+* An endpoint must be `https:`, except on a loopback issuer, which a local
+* Cloud serves over plain HTTP.
+*/
+function secureEndpoint(value, issuer) {
+	try {
+		const url = new URL(value);
+		return url.protocol === "https:" || url.protocol === "http:" && isLoopback(new URL(issuer).hostname);
+	} catch {
+		return false;
+	}
+}
+async function readRecord(response) {
+	const text = await readBodyText(response);
+	if (!text.ok) return null;
+	try {
+		const body = JSON.parse(text.text);
+		return isRecord(body) ? body : null;
+	} catch {
+		return null;
+	}
+}
+function optionalString(value) {
+	return value === void 0 || typeof value === "string";
+}
+function parseProject(value) {
+	if (!isRecord(value) || typeof value["id"] !== "string" || value["id"] === "" || typeof value["name"] !== "string" || typeof value["environment"] !== "string" || value["environment"] === "" || !optionalString(value["slug"]) || !optionalString(value["issuer"]) || !optionalString(value["updatedAt"])) return null;
+	const catalog = value["catalog"];
+	if (catalog !== void 0 && (!isRecord(catalog) || !Number.isInteger(catalog["version"]) || typeof catalog["fingerprint"] !== "string")) return null;
+	return compact({
+		id: value["id"],
+		name: value["name"],
+		environment: value["environment"],
+		slug: value["slug"],
+		issuer: value["issuer"],
+		catalog: isRecord(catalog) && typeof catalog["version"] === "number" && typeof catalog["fingerprint"] === "string" ? {
+			version: catalog["version"],
+			fingerprint: catalog["fingerprint"]
+		} : void 0,
+		updatedAt: value["updatedAt"]
+	});
+}
+function refusal$1(response) {
+	const challenge = bearerChallenge(response.headers.get("www-authenticate"));
+	const error = challenge?.params["error"];
+	const status = response.status;
+	if (status === 401) return new CloudAuthError("invalid-token", "PermDock Cloud refused the access token; refresh it or sign in again", compact({
+		status,
+		error: error ?? "invalid_token"
+	}));
+	if (status === 403 && error === "insufficient_scope") {
+		const scope = challenge?.params["scope"];
+		return new CloudAuthError("insufficient-scope", `The access token lacks ${scope ?? "a required scope"}; sign in again with it`, compact({
+			status,
+			error,
+			scope
+		}));
+	}
+	if (status === 403) return new CloudAuthError("forbidden", "The access token may not read this resource", compact({
+		status,
+		error
+	}));
+	if (status === 429) return new CloudAuthError("rate-limited", `PermDock Cloud rate-limited the request; retry after ${response.headers.get("retry-after") ?? "a while"} seconds`, { status });
+	return new CloudAuthError("unexpected-response", `PermDock Cloud answered HTTP ${String(status)}`, { status });
+}
+/**
+* An OAuth 2.0 client of the PermDock Cloud platform issuer, for an app that
+* signs its users in to PermDock Cloud and reads their projects. Endpoints come
+* from the issuer's RFC 8414 metadata; every call throws a `CloudAuthError`.
+*/
+function cloudOAuth(options) {
+	const issuer = trimSlash(options.url ?? "https://permdock.com/api");
+	const fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis);
+	const scopes = options.scopes ?? DEFAULT_SCOPES;
+	let discovered;
+	const discover = async () => {
+		const body = await discoverAuthorizationServer(issuer, { fetch: fetchFn });
+		const authorization = body === null ? void 0 : stringField(body, "authorization_endpoint");
+		const token = body === null ? void 0 : stringField(body, "token_endpoint");
+		const methods = body?.["code_challenge_methods_supported"];
+		if (authorization === void 0 || token === void 0 || !secureEndpoint(authorization, issuer) || !secureEndpoint(token, issuer) || !Array.isArray(methods) || !methods.includes("S256")) throw new CloudAuthError("discovery-failed", `No usable RFC 8414 metadata for ${issuer}`);
+		return {
+			authorization,
+			token
+		};
+	};
+	const endpoints = () => {
+		discovered ??= discover().catch((error) => {
+			discovered = void 0;
+			throw error;
+		});
+		return discovered;
+	};
+	const send = async (url, init) => {
+		try {
+			return await fetchFn(url, {
+				...init,
+				signal: timeoutSignal(OAUTH_TIMEOUT_MS)
+			});
+		} catch {
+			throw new CloudAuthError("unreachable", `PermDock Cloud at ${issuer} did not answer`);
+		}
+	};
+	const token = async (fields) => {
+		const headers = new Headers({
+			"content-type": "application/x-www-form-urlencoded",
+			accept: "application/json"
+		});
+		const form = new URLSearchParams(fields);
+		if (options.clientSecret === void 0) form.set("client_id", options.clientId);
+		else headers.set("authorization", `Basic ${btoa(`${formEncode(options.clientId)}:${formEncode(options.clientSecret)}`)}`);
+		const response = await send((await endpoints()).token, {
+			method: "POST",
+			headers,
+			body: form
+		});
+		const body = await readRecord(response);
+		if (body === null) throw new CloudAuthError("unexpected-response", "PermDock Cloud answered the token request with a body that is not a JSON object", { status: response.status });
+		const parsed = parseToken(body, secondsAt(options.now?.()));
+		if (!parsed.ok || !response.ok) {
+			const error = parsed.ok ? void 0 : parsed.error;
+			throw new CloudAuthError("token-refused", `PermDock Cloud refused the token request${error === void 0 ? "" : `: ${error}`}`, compact({
+				status: response.status,
+				error
+			}));
+		}
+		return parsed.credential;
+	};
+	return Object.freeze({
+		issuer,
+		async authorizeUrl(request = {}) {
+			const { authorization } = await endpoints();
+			const { verifier, challenge } = await pkce();
+			const state = randomToken(16);
+			const url = new URL(authorization);
+			url.searchParams.set("response_type", "code");
+			url.searchParams.set("client_id", options.clientId);
+			url.searchParams.set("redirect_uri", options.redirectUri);
+			url.searchParams.set("scope", (request.scopes ?? scopes).join(" "));
+			url.searchParams.set("state", state);
+			url.searchParams.set("code_challenge", challenge);
+			url.searchParams.set("code_challenge_method", "S256");
+			return Object.freeze({
+				url: url.href,
+				state,
+				codeVerifier: verifier
+			});
+		},
+		async exchangeCode(callback, pending) {
+			let params;
+			try {
+				params = new URL(callback).searchParams;
+			} catch {
+				throw new CloudAuthError("authorization-denied", "The callback is not a URL");
+			}
+			if (pending.state === "" || params.get("state") !== pending.state) throw new CloudAuthError("state-mismatch", "The callback does not echo the state of the authorization");
+			const iss = params.get("iss");
+			if (iss !== null && trimSlash(iss) !== issuer) throw new CloudAuthError("issuer-mismatch", `The callback names the issuer ${iss}, not ${issuer}`);
+			const error = params.get("error");
+			const code = params.get("code");
+			if (error !== null || code === null || code === "") throw new CloudAuthError("authorization-denied", `The authorization was not granted${error === null ? "" : `: ${error}`}`, error === null ? {} : { error });
+			return await token({
+				grant_type: "authorization_code",
+				code,
+				redirect_uri: options.redirectUri,
+				code_verifier: pending.codeVerifier
+			});
+		},
+		refresh(refreshToken) {
+			return token({
+				grant_type: "refresh_token",
+				refresh_token: refreshToken
+			});
+		},
+		async listProjects(accessToken, request = {}) {
+			const url = new URL(`${issuer}/v1/projects`);
+			if (request.cursor !== void 0) url.searchParams.set("cursor", request.cursor);
+			const response = await send(url, { headers: {
+				authorization: `Bearer ${accessToken}`,
+				accept: "application/json"
+			} });
+			if (!response.ok) throw refusal$1(response);
+			const body = await readRecord(response);
+			const raw = body?.["items"];
+			const items = Array.isArray(raw) ? raw.map(parseProject) : null;
+			const next = body?.["next"];
+			if (items === null || items.includes(null) || !optionalString(next)) throw new CloudAuthError("unexpected-response", "PermDock Cloud sent a project list that does not match cloud-api-v1.json", { status: response.status });
+			return Object.freeze(compact({
+				items: Object.freeze(items.filter((item) => item !== null)),
+				next
+			}));
+		}
+	});
+}
+//#endregion
 //#region src/cloud/delivery.ts
 function failed(cause, retryable, reason) {
 	return {
@@ -41,11 +304,11 @@ async function fromResponse(response) {
 }
 /**
 * A `DeliveryTransport` for `channel` that hands each checked recipient to
-* PermDock Cloud, which sends it from its hosted email, chat or webhook
-* sender and reports back through `com.permdock.delivery.*` events. The
-* router has already decided the recipient: the Cloud receives the target
-* and the permission that let it through, never a decision to make.
-* `Idempotency-Key` is the delivery's idempotency key, so a retry repeats it.
+* PermDock Cloud, which sends it from its hosted email, chat or webhook sender
+* and reports back through `com.permdock.delivery.*` events. The router has
+* already decided the recipient: the Cloud receives the target and the
+* permission that let it through, never a decision to make. `Idempotency-Key`
+* is the delivery's idempotency key, so a retry repeats it.
 */
 function cloudDeliveryTransport(channel, options = {}) {
 	const connection = cloudConnection(options);
@@ -103,8 +366,8 @@ const REGISTERED = /* @__PURE__ */ new Set([
 	"jti"
 ]);
 /**
-* The Cloud's own outputs and access tokens; a client key that could mint
-* them could forge them, or forge the approver behind `PermDock-Approver`.
+* The Cloud's own outputs and access tokens; a client key that could mint them
+* could forge them, or forge the approver behind `PermDock-Approver`.
 */
 const CLOUD_ISSUED = /* @__PURE__ */ new Set([
 	"vnd.permdock.policy+jwt",
@@ -126,11 +389,11 @@ function headerTyp(token) {
 /**
 * A `TokenSigner` backed by the environment's PermDock Cloud keys, typically
 * KMS-held, for run tickets (`vnd.permdock.run+jwt`) and every other signed
-* output an app issues. The Cloud signs only what the app sends: it sets
-* `iss` to the environment URL and adds no claim. Policy documents,
-* snapshots, evidence exports, Security Event Tokens and `at+jwt` access tokens are the Cloud's own
-* outputs, so their `typ` values are refused here. Verify what it signs with
-* `joseTokenVerifier({ jwks: cloudEndpoints().jwks })`.
+* output an app issues. The Cloud signs only what the app sends: it sets `iss`
+* to the environment URL and adds no claim. Policy documents, snapshots,
+* evidence exports, Security Event Tokens and `at+jwt` access tokens are the
+* Cloud's own outputs, so their `typ` values are refused here. Verify what it
+* signs with `joseTokenVerifier({ jwks: cloudEndpoints().jwks })`.
 */
 function cloudSigner(options = {}) {
 	const connection = cloudConnection(options);
@@ -206,8 +469,8 @@ function eventsOf(body) {
 	return parseCloudEventBatch(parsed);
 }
 /**
-* Verifies a PermDock Cloud webhook delivery: Standard Webhooks headers over
-* an `application/cloudevents-batch+json` body (or one
+* Verifies a PermDock Cloud webhook delivery: Standard Webhooks headers over an
+* `application/cloudevents-batch+json` body (or one
 * `application/cloudevents+json` event). There is no unsigned mode, and it
 * never throws.
 */
@@ -264,13 +527,12 @@ function refusal(cause) {
 	}
 }
 /**
-* An `ApprovalWaiter` that PermDock Cloud wakes. Mount `webhook` on the
-* route the environment's webhook connector posts to: when an approval is
-* resolved, expires or is cancelled, the parked run for its token wakes.
-* Waking never approves anything. The run decides again with the token, and
-* only the app's `decide` and its approval store can grant. Without
-* `waiter`, waits poll `store` as a fallback for a webhook another process
-* received.
+* An `ApprovalWaiter` that PermDock Cloud wakes. Mount `webhook` on the route
+* the environment's webhook connector posts to: when an approval is resolved,
+* expires or is cancelled, the parked run for its token wakes. Waking never
+* approves anything. The run decides again with the token, and only the app's
+* `decide` and its approval store can grant. Without `waiter`, waits poll
+* `store` as a fallback for a webhook another process received.
 */
 function cloudApprovalWaiter(options) {
 	const inner = options.waiter ?? pollingApprovalWaiter({
@@ -294,4 +556,4 @@ function cloudApprovalWaiter(options) {
 	});
 }
 //#endregion
-export { approvalTokensOf, cloud, cloudApprovalWaiter, cloudDeliveryTransport, cloudEndpoints, cloudSigner, parseCloudEvent, verifyWebhook };
+export { CLOUD_BASE_URL, CloudAuthError, approvalTokensOf, cloud, cloudApprovalWaiter, cloudDeliveryTransport, cloudEndpoints, cloudOAuth, cloudSigner, isCloudAuthError, parseCloudEvent, resolveCloudEndpoints, verifyWebhook };