permdock 0.4.0 → 0.6.0

package/dist/{types-Br9IXUBG.d.ts → types-BdtSDbBO.d.ts}

@@ -1,4 +1,5 @@
-import { Dr as Membership, Jn as RelationGrantee, Ln as Approver, kr as Subject, o as ApprovalStage, r as ApprovalMode } from "./policy-types-sp9P1iIV.js";
+import { Cn as RelationGrantee, Rt as Instant, ar as Subject, cr as AdapterId, fn as Approver, nr as Membership, o as ApprovalStage, on as WireDelegation, r as ApprovalMode } from "./policy-types-n0uRTsW8.js";
+import { V as AppData } from "./vocabulary-CN8H_9UF.js";
 //#region src/approvals/types.d.ts
 type ApprovalStatus = "pending" | "approved" | "rejected" | "expired";
 type ApprovalApprovers = {
@@ -13,9 +14,9 @@ type ApprovalApprovers = {
   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`. */
+  /** Who else may approve once the request has waited `after` seconds since `createdAt`. */
   readonly escalation?: {
-    readonly after: string;
+    readonly after: number;
     readonly to: Approver | readonly Approver[];
   };
 };
@@ -25,6 +26,43 @@ type ApprovalSignature = {
   readonly at: string;
   readonly stage?: number;
   readonly vouched?: string;
+  /** The principal `by` approved for, when `by` acted under an `ApprovalDelegation`. */
+  readonly onBehalfOf?: string;
+  /** The `ApprovalDelegation` id `onBehalfOf` was read from. */
+  readonly delegation?: string;
+};
+/**
+ * One out-of-office delegation: `delegate` may approve what `delegator`
+ * could approve, from `from` until `until`. Both instants are required, so
+ * a delegation cannot be open-ended. `permissions` and `resources` narrow
+ * it; absent, it covers every request. `tenant` holds it to one tenant.
+ */
+type ApprovalDelegation = {
+  readonly id: string;
+  readonly delegator: string;
+  readonly delegate: string;
+  readonly tenant?: string;
+  readonly permissions?: readonly string[];
+  readonly resources?: readonly string[];
+  /** RFC 3339. Inclusive. */
+  readonly from: string;
+  /** RFC 3339. Exclusive. */
+  readonly until: string;
+};
+/**
+ * Active approval delegations for one delegate, a subject input the handler
+ * reads when the caller is not an approver on their own. A throw matches
+ * nobody. One hop: the handler never reads the delegator's own delegations.
+ */
+type ApprovalDelegationSource = {
+  /** Names the implementation in errors and events. */
+  readonly name?: string;
+  delegationsFor(query: {
+    readonly delegate: string;
+    readonly tenant?: string;
+    /** RFC 3339. The source returns delegations active at this instant. */
+    readonly at: string;
+  }): readonly ApprovalDelegation[] | Promise<readonly ApprovalDelegation[]>;
 };
 type ApprovalSubjectSummary = {
   readonly principal: {
@@ -37,13 +75,13 @@ type ApprovalSubjectSummary = {
     readonly kind: string;
   };
   readonly session?: string;
-  readonly delegation?: {
-    readonly scopes?: readonly string[];
-    readonly authorizationDetails?: readonly unknown[];
-  };
+  /** OAuth `scope` (space-separated) and RFC 9396 `authorization_details`. */
+  readonly delegation?: WireDelegation;
 };
 type ApprovalRequest = {
   readonly v: 1;
+  /** The request id: the signature's `jti`. */
+  readonly id: string;
   readonly token: string;
   readonly permission: string;
   readonly scope: string;
@@ -55,7 +93,7 @@ type ApprovalRequest = {
   readonly membership?: Membership;
   readonly approvers?: ApprovalApprovers;
   readonly detail: string;
-  readonly adapter?: string;
+  readonly adapter?: AdapterId;
   readonly createdAt: string;
   readonly expiresAt: string;
   readonly status: ApprovalStatus;
@@ -67,6 +105,8 @@ type ApprovalRequest = {
   readonly vouched?: string;
   readonly note?: string;
   readonly consumedAt?: string;
+  /** The application's own data, set when the request opens; plain JSON, never read by a decision. */
+  readonly x?: AppData;
 };
 type ApprovalVerdict = {
   readonly status: "approved" | "rejected";
@@ -87,6 +127,18 @@ type ApprovalVerdict = {
    */
   readonly permissions?: readonly string[];
   readonly vouched?: string;
+  /**
+   * Set when `by` is not an approver and acts for this principal under an
+   * `ApprovalDelegation`. Server-side input: the handler resolves the
+   * delegator, and `applyApprovalVerdict` checks them again. `relations`
+   * and `permissions` are that principal's facts, never the delegate's.
+   */
+  readonly onBehalfOf?: {
+    readonly subject: Subject;
+    readonly delegation: string;
+    readonly relations?: readonly string[];
+    readonly permissions?: readonly string[];
+  };
 };
 type ApprovalListFilter = {
   readonly status?: ApprovalStatus;
@@ -114,35 +166,43 @@ type ApprovalCancelMeta = {
   readonly note?: string;
 };
 type ApprovalStore = {
+  /** Names the implementation in errors and events. */
+  readonly name?: string;
   /**
-   * 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.
+   * Seconds a request opened against this store stays open when the
+   * caller sets no `ttl`; absent means `DEFAULT_APPROVAL_TTL`. 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;
+  /**
+   * The request with this `id`, for `approvalsHandler`, which routes by id.
+   * Without it the handler pages through `list` to find the id.
+   */
+  getById?(id: 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;
+  expire(now?: Instant): 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;
+  consume(token: string, now?: Instant): 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 ApprovalResumeFailureCause = "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;
+  readonly cause: ApprovalResumeFailureCause;
 };
 declare const APPROVAL_HEADER: "PermDock-Approval";
-declare const DEFAULT_APPROVAL_TTL_MS: number;
+/** Seconds a request stays open when neither the store nor the call sets a `ttl`. */
+declare const DEFAULT_APPROVAL_TTL: 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;
 /**
@@ -154,4 +214,4 @@ 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 };
+export { DEFAULT_APPROVAL_TTL as _, ApprovalDelegationSource as a, escalationOpenAt as b, ApprovalListQuery as c, ApprovalResumeFailureCause as d, ApprovalSignature as f, ApprovalVerdict as g, ApprovalSubjectSummary as h, ApprovalDelegation as i, ApprovalPage as l, ApprovalStore as m, ApprovalApprovers as n, ApprovalInspectResult as o, ApprovalStatus as p, ApprovalCancelMeta as r, ApprovalListFilter as s, APPROVAL_HEADER as t, ApprovalRequest as u, approvalQuorum as v, approverRelationKey as y };

package/dist/types-BtHtcKMr.d.ts

@@ -0,0 +1,157 @@
+import { $t as DeliveryFailureCause, Qt as DeliveryEvent, Zt as DeliveryChannel, tn as EmailCategory, zn as GrantedDecision } from "./policy-types-n0uRTsW8.js";
+import { s as CloudEvent } from "./sink-4-eQIRWf.js";
+import { t as ApprovalPrompt } from "./approval-prompt-DvSSPQJX.js";
+//#region src/delivery/types.d.ts
+/**
+ * Who a delivery goes to. `{ principal }` names an app principal and the
+ * address the server loaded for it on `channel`. `{ address }` alone is an
+ * email or chat identity that resolves through
+ * `PrincipalSource.principalByIdentity`; with no principal linked it is
+ * refused unless `trusted` is set for an address the server loaded itself,
+ * such as a customer's billing email, and then the sender must hold the
+ * permission.
+ */
+type Recipient = {
+  readonly principal: string;
+  readonly channel: DeliveryChannel;
+  /** An RFC 5322 `addr-spec`, a chat platform user id, or an https webhook endpoint. */
+  readonly address: string;
+  /** The chat platform (`slack`, `teams`, …). */
+  readonly provider?: string;
+  readonly workspace?: string;
+} | {
+  readonly principal?: undefined;
+  readonly channel: "email" | "chat";
+  readonly address: string;
+  /** The chat platform; required for a chat address. */
+  readonly provider?: string;
+  readonly workspace?: string;
+  /** `true` only for an address the server loaded itself, never one from a request. */
+  readonly trusted?: boolean;
+};
+/** One-click unsubscribe (RFC 8058): an https URL, plus an optional `mailto:` address. */
+type EmailUnsubscribe = {
+  readonly url: string;
+  readonly mailto?: string;
+};
+type EmailMessage = {
+  /** Defaults to the router's `from`. A name-addr (`Acme <billing@acme.test>`) is allowed here. */
+  readonly from?: string;
+  readonly replyTo?: string;
+  readonly subject: string;
+  readonly text: string;
+  readonly html?: string;
+  /** Extra headers. `Auto-Submitted` and the `List-Unsubscribe` pair are the router's. */
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly category: EmailCategory;
+  /** Required on `notification`, ignored on every other category. */
+  readonly unsubscribe?: EmailUnsubscribe | ((target: DeliveryTarget<"email">) => EmailUnsubscribe);
+};
+/** An email as a transport receives it: `from` set and the standards headers added. */
+type OutgoingEmail = Omit<EmailMessage, "from" | "unsubscribe" | "headers"> & {
+  readonly from: string;
+  readonly headers: Readonly<Record<string, string>>;
+};
+type ChatMessage = {
+  readonly text: string;
+  /** Rendered by the transport as its approval card, linking to `url`. */
+  readonly approval?: {
+    readonly prompt: ApprovalPrompt;
+    readonly url: string;
+  };
+};
+/** A CloudEvents 1.0 event, posted as `application/cloudevents+json`. */
+type WebhookMessage = {
+  readonly event: CloudEvent;
+};
+type DeliveryMessages = {
+  readonly email: EmailMessage;
+  readonly chat: ChatMessage;
+  readonly webhook: WebhookMessage;
+};
+/** What a transport of channel `C` receives. */
+type TransportMessages = {
+  readonly email: OutgoingEmail;
+  readonly chat: ChatMessage;
+  readonly webhook: WebhookMessage;
+};
+/**
+ * A recipient the router checked: the granted decision that let it through
+ * and the address in the form the channel compares. A transport refuses a
+ * target without a granted `decision` (`isDeliveryTarget`).
+ */
+type DeliveryTarget<C extends DeliveryChannel = DeliveryChannel> = {
+  readonly channel: C;
+  readonly address: string;
+  /** Absent for a trusted address no principal is linked to. */
+  readonly principal?: string;
+  readonly provider?: string;
+  readonly workspace?: string;
+  readonly trusted?: true;
+  readonly decision: GrantedDecision;
+};
+type TransportOptions = {
+  /** Stable for one delivery id and recipient: the provider's `Idempotency-Key` and the `webhook-id`. */
+  readonly idempotencyKey: string;
+  /** The delivery id every recipient of one `deliver` call shares. */
+  readonly delivery: string;
+};
+type DeliveryResult = {
+  readonly status: "sent";
+  readonly providerId?: string;
+} | {
+  readonly status: "failed";
+  readonly cause: DeliveryFailureCause;
+  /** Whether a retry with the same idempotency key may succeed. */
+  readonly retryable: boolean;
+  readonly reason?: string;
+};
+/** One delivery as a transport receives it. */
+type TransportItem<C extends DeliveryChannel = DeliveryChannel> = {
+  readonly target: DeliveryTarget<C>;
+  readonly message: TransportMessages[C];
+  readonly options: TransportOptions;
+};
+/**
+ * One channel's sender. `deliver` resolves to a result; a throw or a
+ * rejection counts as a retryable `unavailable` failure.
+ */
+type DeliveryTransport<C extends DeliveryChannel = DeliveryChannel> = {
+  readonly channel: C;
+  /** The provider name delivery events carry (`resend`, `chat-sdk`, `webhook`). */
+  readonly name: string;
+  deliver(target: DeliveryTarget<C>, message: TransportMessages[C], options: TransportOptions): DeliveryResult | Promise<DeliveryResult>;
+  /**
+   * Sends several deliveries in one provider call, one result per item in
+   * item order. The router uses it for two or more ready recipients.
+   */
+  deliverBatch?(items: readonly TransportItem<C>[]): readonly DeliveryResult[] | Promise<readonly DeliveryResult[]>;
+  /** The most items one `deliverBatch` call takes. Defaults to 100. */
+  readonly batchSize?: number;
+};
+type EmailTransport = DeliveryTransport<"email"> & {
+  /** The `from` of an email whose message and router set none. */
+  readonly from?: string;
+};
+type ChatTransport = DeliveryTransport<"chat">;
+type WebhookTransport = DeliveryTransport<"webhook">;
+type DeliveryTransports = {
+  readonly email?: EmailTransport;
+  readonly chat?: ChatTransport;
+  readonly webhook?: WebhookTransport;
+};
+type DeliverOptions = {
+  /** Keep it across retries so each recipient's idempotency key repeats. Defaults to `dlv_` and a random UUID. */
+  readonly id?: string;
+  /** The approval request id a prompt is delivered for, on every event. */
+  readonly approval?: string;
+};
+type DeliveryReport = {
+  readonly id: string;
+  /** One event per recipient, in recipient order. */
+  readonly events: readonly DeliveryEvent[];
+  readonly sent: number;
+  readonly failed: number;
+};
+//#endregion
+export { TransportOptions as _, DeliveryReport as a, DeliveryTransport as c, EmailTransport as d, EmailUnsubscribe as f, TransportMessages as g, TransportItem as h, DeliveryMessages as i, DeliveryTransports as l, Recipient as m, ChatTransport as n, DeliveryResult as o, OutgoingEmail as p, DeliverOptions as r, DeliveryTarget as s, ChatMessage as t, EmailMessage as u, WebhookMessage as v, WebhookTransport as y };

package/dist/{types-CqrjB9o6.d.ts → types-BzzaHxt3.d.ts}

@@ -1,4 +1,5 @@
-import { Or as Principal, yn as AuthEvent } from "./policy-types-sp9P1iIV.js";
+import { qt as AuthEvent, rr as Principal } from "./policy-types-n0uRTsW8.js";
+import { t as ClaimsMap } from "./claims-map-Ca-QX8C6.js";
 import { t as ClientNames } from "./clients-C7zLFuWT.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/supabase/claims.d.ts
@@ -18,14 +19,14 @@ type SupabaseMembershipClaim = {
   readonly roles: readonly string[];
   readonly via?: string;
   /** Seconds since the epoch. */
-  readonly expiresAt?: number;
-  readonly grantedBy?: string;
+  readonly expires_at?: number;
+  readonly granted_by?: string;
   readonly reason?: string;
   /** The subgroup a membership source's `group` fills: a fixed name or a column. */
   readonly member?: {
     readonly group: string;
   };
-  readonly managedBy?: "idp";
+  readonly managed_by?: "idp";
   readonly entitlements?: readonly string[];
   /** The instance or an ancestor is suspended: the permission keys the membership still grants. */
   readonly keep?: readonly string[];
@@ -247,14 +248,17 @@ type SupabaseSessionLike = {
   readonly claims?: unknown;
 };
 type SupabaseSubjectOptions = {
-  readonly roles?: string;
-  readonly tenant?: string;
-  readonly memberships?: string;
+  /**
+   * Where the token carries roles (default `user_role`), the active tenant
+   * (default `tenant_id`), memberships (default `memberships`) and plan names
+   * per tenant id (no default; the active tenant's entry becomes
+   * `principal.plans`). A name is read at the top level, then in
+   * `app_metadata`.
+   */
+  readonly claims?: Pick<ClaimsMap, "roles" | "tenant" | "memberships" | "plans">;
   readonly schema?: StandardSchemaV1;
   readonly include?: readonly SupabaseInclude[];
   readonly declared?: readonly string[];
-  /** Claim holding plan names per tenant id; the active tenant's entry becomes `principal.plans`. */
-  readonly plans?: string;
   /** Names for OAuth client ids: an `oauth-client` actor gets `client` set to the name of its id, which a policy delegation matches with `to: { kind: 'oauth-client', client }`. */
   readonly clients?: ClientNames;
   /** `'deny'` maps a token with `is_anonymous: true` (`signInAnonymously()`) to the anonymous subject, as `rls.anonymousSignIns: 'deny'` does in RLS. */
@@ -271,8 +275,9 @@ type SupabaseSubjectOptions = {
 /**
  * Who acts for the user. `oauth-client`: a third-party app or an agent chain (`client_id`, or an
  * `act` without `kind`). `support`: a support session (`act.kind: "support"` with `session_id`).
- * `impersonation`: an admin acting as the user (`act.kind: "impersonation"`). `chain` is a copy of
- * the token's `act` claim when it has one.
+ * `impersonation`: an admin acting as the user (`act.kind: "impersonation"`). `agent`: an agent
+ * run better-supabase's `agentClaims` minted (`act.kind: "agent"`), with the `tools` it may call.
+ * `chain` is a copy of the token's `act` claim when it has one.
  */
 type SupabaseActor = {
   readonly id: string;
@@ -290,6 +295,13 @@ type SupabaseActor = {
   readonly kind: "impersonation";
   readonly reason?: string;
   readonly chain: SupabaseActClaim;
+} | {
+  readonly id: string;
+  readonly kind: "agent";
+  readonly tools?: readonly string[];
+  /** `act.read_only`, default `false`: a read-only agent never writes. */
+  readonly readOnly: boolean;
+  readonly chain: SupabaseActClaim;
 };
 /** `actorOf` output: `{ ok: false }` must deny. */
 type SupabaseActorResult = {