permdock 0.3.1 → 0.5.0

package/dist/cloud/index.d.ts

@@ -1,90 +1,129 @@
-import { $ as AccessEvent, At as SnapshotSource, Ft as TokenVerifier, Nt as TokenFailureCause, at as DecisionSink, bn as PolicySource, ht as MembershipEvent, ot as DirectoryEvent, rt as DecisionEvent, tt as CredentialEvent } from "../policy-IB6yxpC3.js";
-import { f as ApprovalStore } from "../types-aqOHTHcp.js";
-import { n as CatalogEventData, o as CloudEventType } from "../sink-B1fZzIMf.js";
-import { a as JsonWebKeySet, g as ReplayStore } from "../types-Cq_H8N_X.js";
-//#region src/cloud/types.d.ts
-type CloudEndpointOptions = {
-  readonly url?: string;
-  readonly environment?: string;
-};
-type CloudEndpoints = {
-  /** The environment URL, `<url>/v1/environments/<env>`: `iss` and `aud` of the policy document. */
-  readonly issuer: string;
-  /** The environment's JWK Set URL, for `joseTokenVerifier({ jwks })`. */
-  readonly jwks: string;
-};
-type CloudOptions = CloudEndpointOptions & {
-  readonly key?: string;
-  readonly fetch?: typeof fetch;
-  readonly flushAt?: number;
-  /** Most events the sink holds while the Cloud is unreachable (default 10 000); the oldest are dropped first. */
-  readonly capacity?: number;
-  readonly waitUntil?: (task: Promise<void>) => void;
-  /**
-   * Verifies the environment's signed policy document, typically
-   * `joseTokenVerifier({ jwks: cloudEndpoints().jwks })`. Without one,
-   * `policies.current()` stays `null`: an unverifiable document is never applied.
-   */
-  readonly verifier?: TokenVerifier;
-};
-type CloudClient = CloudEndpoints & {
-  readonly approvals: ApprovalStore;
-  readonly sink: DecisionSink;
-  readonly snapshots: SnapshotSource;
-  readonly policies: PolicySource;
-};
-//#endregion
-//#region src/cloud/create.d.ts
+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-DzwivBgR.js";
+import { m as ApprovalStore } from "../types-CCpc2Dcv.js";
+import { i as CatalogEventData, l as CloudEventType, r as CLOUD_EVENT_TYPES, s as CloudEvent } from "../sink-Bj_lDUDq.js";
+import { c as DeliveryTransport } from "../types-DX0LaKTb.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-C8-KNsFf.js";
+import { n as ApprovalWaiter } from "../waiter-CKy4MQSY.js";
+import { l as ReplayStore } from "../types-DiQjupG2.js";
+import { f as WebhookVerifier, r as WebhookFailureCause$1, s as WebhookJwks } from "../standard-webhooks-6lg8v_is.js";
+//#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`).
  */
 export declare function cloudEndpoints(options?: CloudEndpointOptions): CloudEndpoints;
+//#endregion
+//#region src/cloud/create.d.ts
 export declare function cloud(options?: CloudOptions): CloudClient;
 //#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.
+ */
+export declare function cloudDeliveryTransport<C extends DeliveryChannel>(channel: C, options?: CloudConnectionOptions): DeliveryTransport<C>;
+//#endregion
+//#region src/cloud/signer.d.ts
+/**
+ * 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 })`.
+ */
+export declare function cloudSigner(options?: CloudSignerOptions): TokenSigner;
+//#endregion
 //#region src/cloud/webhook.d.ts
-type Envelope<TType extends CloudEventType, TData> = {
-  readonly specversion: "1.0";
+type Envelope<TType extends CloudEventType, TData> = Omit<CloudEvent, "type" | "data"> & {
   readonly type: TType;
-  readonly source: string;
-  readonly subject?: string;
-  readonly id: string;
-  readonly time: string;
-  readonly datacontenttype: "application/json";
   readonly data: TData;
 };
+type Types = typeof CLOUD_EVENT_TYPES;
 /** A CloudEvent PermDock Cloud delivers, discriminated by `type`. */
-type PermDockCloudEvent = Envelope<"dev.permdock.decision", DecisionEvent> | Envelope<"dev.permdock.approval", DecisionEvent> | Envelope<"dev.permdock.directory", DirectoryEvent> | Envelope<"dev.permdock.membership", MembershipEvent> | Envelope<"dev.permdock.credential", CredentialEvent> | Envelope<"dev.permdock.catalog", CatalogEventData> | Envelope<"dev.permdock.access.started", AccessEvent> | Envelope<"dev.permdock.access.ended", AccessEvent> | Envelope<"dev.permdock.access.revoked", AccessEvent>;
-type VerifyWebhookOptions = {
-  /** Your receiver's URL; the batch `aud` must name it. */
-  readonly audience: string | readonly string[];
-  /** A verifier over the Cloud JWKS; built from `jwks` when absent. */
-  readonly verifier?: TokenVerifier;
-  /** `cloud().jwks`, a JWKS URL, or an inline key set. */
-  readonly jwks?: string | URL | JsonWebKeySet;
-  /** Drops a batch whose `jti` was already delivered. */
+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.
+   */
+  readonly verifier?: WebhookVerifier;
+  /** `cloud().jwks`, a JWKS URL or an inline key set, for `v1a` signatures. */
+  readonly jwks?: WebhookJwks;
+  /** The endpoint's `whsec_` secret, for `v1` signatures. */
+  readonly secret?: string | readonly string[];
+  /** Records each `webhook-id`; required unless `verifier` is set. */
   readonly replay?: ReplayStore;
+  /** Seconds a timestamp may differ from the clock. Defaults to 300. */
+  readonly tolerance?: number;
+  readonly now?: () => Instant;
+  readonly fetch?: typeof fetch;
 };
-type WebhookFailureReason = "unsigned" | "invalid-token" | "invalid-events" | "replayed";
+/** 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;
+  /** The `webhook-id`, unique per message across retries. */
   readonly id: string;
+  /** The `webhook-timestamp` as an RFC 3339 instant. */
+  readonly timestamp: string;
   readonly events: readonly PermDockCloudEvent[];
 } | {
   readonly ok: false;
-  readonly reason: WebhookFailureReason;
-  readonly cause?: TokenFailureCause;
+  readonly cause: WebhookFailureCause;
 };
 /**
- * Validates one CloudEvent against the closed type list and its data shape;
- * returns `null` for anything else, never throws.
+ * Validates one CloudEvent against the closed type list, its `dataschema` and
+ * its data shape; returns `null` for anything else, never throws.
  */
 export declare function parseCloudEvent(value: unknown): PermDockCloudEvent | null;
 /**
- * Verifies a PermDock Cloud webhook delivery: a compact JWS with
- * `typ: permdock-decisions+jwt` whose `events` claim holds CloudEvents.
- * There is no unsigned mode, and it never throws.
+ * 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.
+ */
+export declare function verifyWebhook(request: Request, options: WebhookOptions): Promise<VerifiedWebhook>;
+//#endregion
+//#region src/cloud/waiter.d.ts
+type CloudApprovalWaiterOptions = WebhookOptions & ({
+  /** 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. */
+  readonly waiter: ApprovalWaiter;
+  readonly store?: undefined;
+  readonly interval?: undefined;
+});
+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.
+   */
+  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.
  */
-export declare function verifyWebhook(request: Request, options: VerifyWebhookOptions): Promise<VerifiedWebhook>;
+export declare function cloudApprovalWaiter(options: CloudApprovalWaiterOptions): CloudApprovalWaiter;
 //#endregion
-export type { CloudClient, CloudEndpointOptions, CloudEndpoints, CloudOptions, PermDockCloudEvent, VerifiedWebhook, VerifyWebhookOptions, WebhookFailureReason };
+export type { CloudApprovalWaiter, CloudApprovalWaiterOptions, CloudApproverOptions, CloudCatalog, CloudCatalogPush, CloudClient, CloudConnectionOptions, CloudEndpointOptions, CloudEndpoints, CloudOptions, CloudSignerOptions, PermDockCloudEvent, VerifiedWebhook, WebhookFailureCause, WebhookOptions };