better-supabase 0.13.0 → 0.15.0

package/dist/blocks/security-events/index.d.ts

@@ -0,0 +1,440 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult } from "../../result-DZeA5KS6.js";
+import { Ct as Events } from "../../events-vcqenSYU.js";
+import { n as Logger } from "../../logger-DWVYUmwi.js";
+import { n as BlockOptions } from "../../block-helpers-CRpAHrp_.js";
+import { s as sqlTransport, t as BlockTransport } from "../../block-transport-DWZSJrwN.js";
+import { n as BlockHooks } from "../../block-hooks-DZN2w69m.js";
+import { n as VaultCredentials } from "../../vault-O-YlAyHb.js";
+import { c as BlockOf } from "../../define-block-BVcLQ3DF.js";
+import { n as Jwks } from "../../jws-D0toeQlA.js";
+import { o as Signer } from "../../signing-keys-BNDUxpQL.js";
+//#region src/blocks/security-events/set.d.ts
+/** The `typ` header of a Security Event Token (RFC 8417 §2.3). */
+export declare const SET_TYP = "secevent+jwt";
+/** The media type a pushed SET is sent with (RFC 8935 §2). */
+export declare const SET_CONTENT_TYPE = "application/secevent+jwt";
+/** The SSF 1.0 stream events (§8.1.4, §8.1.5). */
+export declare const SSF_EVENTS: {
+  readonly verification: "https://schemas.openid.net/secevent/ssf/event-type/verification";
+  readonly streamUpdated: "https://schemas.openid.net/secevent/ssf/event-type/stream-updated";
+};
+/** The CAEP 1.0 event types (§3). */
+export declare const CAEP_EVENTS: {
+  readonly sessionRevoked: "https://schemas.openid.net/secevent/caep/event-type/session-revoked";
+  readonly tokenClaimsChange: "https://schemas.openid.net/secevent/caep/event-type/token-claims-change";
+  readonly credentialChange: "https://schemas.openid.net/secevent/caep/event-type/credential-change";
+  readonly assuranceLevelChange: "https://schemas.openid.net/secevent/caep/event-type/assurance-level-change";
+  readonly deviceComplianceChange: "https://schemas.openid.net/secevent/caep/event-type/device-compliance-change";
+  readonly sessionEstablished: "https://schemas.openid.net/secevent/caep/event-type/session-established";
+  readonly sessionPresented: "https://schemas.openid.net/secevent/caep/event-type/session-presented";
+  readonly riskLevelChange: "https://schemas.openid.net/secevent/caep/event-type/risk-level-change";
+};
+/** The RISC 1.0 event types (§2), without the deprecated `sessions-revoked`. */
+export declare const RISC_EVENTS: {
+  readonly accountCredentialChangeRequired: "https://schemas.openid.net/secevent/risc/event-type/account-credential-change-required";
+  readonly accountPurged: "https://schemas.openid.net/secevent/risc/event-type/account-purged";
+  readonly accountDisabled: "https://schemas.openid.net/secevent/risc/event-type/account-disabled";
+  readonly accountEnabled: "https://schemas.openid.net/secevent/risc/event-type/account-enabled";
+  readonly identifierChanged: "https://schemas.openid.net/secevent/risc/event-type/identifier-changed";
+  readonly identifierRecycled: "https://schemas.openid.net/secevent/risc/event-type/identifier-recycled";
+  readonly credentialCompromise: "https://schemas.openid.net/secevent/risc/event-type/credential-compromise";
+  readonly optIn: "https://schemas.openid.net/secevent/risc/event-type/opt-in";
+  readonly optOutInitiated: "https://schemas.openid.net/secevent/risc/event-type/opt-out-initiated";
+  readonly optOutCancelled: "https://schemas.openid.net/secevent/risc/event-type/opt-out-cancelled";
+  readonly optOutEffective: "https://schemas.openid.net/secevent/risc/event-type/opt-out-effective";
+  readonly recoveryActivated: "https://schemas.openid.net/secevent/risc/event-type/recovery-activated";
+  readonly recoveryInformationChanged: "https://schemas.openid.net/secevent/risc/event-type/recovery-information-changed";
+};
+/**
+ * An SSF subject identifier (RFC 9493 and SSF §3): `{ format: "email", email
+ * }`, `{ format: "iss_sub", iss, sub }`, `{ format: "opaque", id }`, or a
+ * complex subject with `user`, `session`, `tenant` and other members.
+ */
+type SubjectIdentifier = {
+  readonly format: string;
+} & Readonly<Record<string, unknown>>;
+/** One event: its type URI and its claims. */
+interface SecurityEvent {
+  readonly type: string;
+  readonly claims: Readonly<Record<string, unknown>>;
+}
+/** What signs a SET: a signing-keys `signer(owner)`, or anything with `signJwt`. */
+type SetSigner = Pick<Signer, "signJwt">;
+interface MintSetInput {
+  readonly issuer: string;
+  readonly audience: string | readonly string[];
+  readonly subject: SubjectIdentifier;
+  readonly event: SecurityEvent;
+  /** Links SETs that describe the same change (SSF §4.1.7). */
+  readonly txn?: string;
+}
+interface MintedSet {
+  readonly jti: string;
+  readonly token: string;
+}
+/**
+ * A signed SET (RFC 8417) with the SSF profile: `typ: secevent+jwt`, a
+ * top-level `sub_id`, exactly one event, and no `sub` or `exp` claim.
+ */
+export declare function mintSet(signer: SetSigner, input: MintSetInput): AsyncResult<MintedSet>;
+/** The RFC 8935 §2.3 error codes a receiver answers with. */
+type SetErrorCode = "invalid_request" | "invalid_key" | "invalid_issuer" | "invalid_audience" | "authentication_failed" | "access_denied";
+interface VerifiedSet {
+  readonly jti: string;
+  readonly issuer: string;
+  /** Seconds since the epoch. */
+  readonly issuedAt: number;
+  readonly audience: readonly string[];
+  readonly subject: SubjectIdentifier;
+  readonly type: string;
+  readonly claims: Readonly<Record<string, unknown>>;
+  readonly txn: string | undefined;
+  readonly token: string;
+}
+type SetVerification = {
+  readonly ok: true;
+  readonly set: VerifiedSet;
+} | {
+  readonly ok: false;
+  readonly err: SetErrorCode;
+  readonly description: string;
+};
+interface VerifySetOptions {
+  readonly jwks: Jwks;
+  readonly issuer: string;
+  readonly audience: string;
+  /** How far `iat` may be in the future, in seconds. Default: 300. */
+  readonly skewSeconds?: number;
+  /** The transmitter's `critical_subject_members` (SSF §7.1). */
+  readonly criticalSubjectMembers?: readonly string[];
+  /** The complex subject members this receiver processes. Default: the SSF ones. */
+  readonly understoodSubjectMembers?: readonly string[];
+}
+/**
+ * Verifies a SET as an RFC 8935 receiver: the signature against `jwks`, `typ`,
+ * `iss`, `aud`, `jti`, `iat`, one event and an SSF `sub_id`. A failure carries
+ * the error code to answer the transmitter with.
+ */
+export declare function verifySet(token: string, options: VerifySetOptions): Promise<SetVerification>;
+//#endregion
+//#region src/blocks/security-events/receiver.d.ts
+/**
+ * Handles one event type; a throw leaves the SET unprocessed, so the
+ * transmitter sends it again.
+ */
+type SsfEventHandler = (set: VerifiedSet) => void | Promise<void>;
+interface SsfReceiverOptions extends BlockOptions {
+  /**
+   * The transmitter's issuer, compared exactly with its metadata and each
+   * `iss`.
+   */
+  readonly issuer: string;
+  /** This receiver's `aud`. */
+  readonly audience: string;
+  /** The transmitter's keys. Default: its metadata's `jwks_uri`, cached. */
+  readonly jwks?: Jwks | (() => Promise<Jwks>);
+  /**
+   * Handlers by event type URI; `"*"` takes the rest. Unhandled events are
+   * acknowledged.
+   */
+  readonly handlers?: Readonly<Record<string, SsfEventHandler>>;
+  /**
+   * The `Authorization` header value the transmitter pushes with; checked when
+   * set.
+   */
+  readonly authorization?: string;
+  /** The transmitter's `critical_subject_members`. */
+  readonly criticalSubjectMembers?: readonly string[];
+  /** How long fetched metadata and keys stay cached, in seconds. Default: 300. */
+  readonly cacheSeconds?: number;
+  /** The largest pushed SET, in bytes. Default: 64 KiB. */
+  readonly maxBodyBytes?: number;
+  readonly fetch?: typeof fetch;
+  /**
+   * Receives handler errors and the errors `after` hooks throw. Default:
+   * `consoleLogger`.
+   */
+  readonly logger?: Logger;
+  /** `withBlockHooks` hooks around the receiver's methods. */
+  readonly hooks?: NoInfer<BlockHooks<SsfReceiver>>;
+}
+type SsfReceiveResult = {
+  readonly ok: true;
+  readonly set: VerifiedSet;
+  readonly duplicate: boolean;
+} | {
+  readonly ok: false;
+  readonly err: SetErrorCode;
+  readonly description: string;
+};
+interface SsfPollOptions {
+  /** The stream's `delivery.endpoint_url`. */
+  readonly endpoint: string;
+  /** The `Authorization` header value the transmitter's API takes. */
+  readonly authorization: string;
+  /** SETs per request. Default: 100. */
+  readonly maxEvents?: number;
+  /** Requests before returning. Default: 10. */
+  readonly maxRequests?: number;
+}
+interface SsfPollResult {
+  readonly received: number;
+  readonly rejected: number;
+  /** SETs whose handler threw: not acknowledged, so the next poll returns them. */
+  readonly failed: number;
+  readonly moreAvailable: boolean;
+}
+interface SsfStreamRequest {
+  readonly method: "push" | "poll";
+  /** Required for push: this receiver's RFC 8935 endpoint. */
+  readonly endpointUrl?: string;
+  /** The `Authorization` header the transmitter pushes with. */
+  readonly authorizationHeader?: string;
+  readonly eventsRequested: readonly string[];
+  readonly description?: string;
+}
+/** The transmitter's stream management API, as a receiver calls it. */
+interface SsfStreamClient {
+  create(request: SsfStreamRequest): AsyncResult<Readonly<Record<string, unknown>>>;
+  read(streamId: string): AsyncResult<Readonly<Record<string, unknown>>>;
+  remove(streamId: string): AsyncResult<void>;
+  status(streamId: string): AsyncResult<Readonly<Record<string, unknown>>>;
+  setStatus(streamId: string, status: "enabled" | "paused" | "disabled", reason?: string): AsyncResult<Readonly<Record<string, unknown>>>;
+  /** Asks for a verification event; `false` when the transmitter answered 429. */
+  verify(streamId: string, state?: string): AsyncResult<boolean>;
+}
+/** An SSF 1.0 receiver on the `security-events` module's replay table. */
+interface SsfReceiver {
+  /** The transmitter's metadata, with its `issuer` checked. */
+  discover(): AsyncResult<Readonly<Record<string, unknown>>>;
+  /** Verifies a SET, drops a replay, and runs its handler. */
+  receive(token: string): Promise<SsfReceiveResult>;
+  /** The RFC 8935 push endpoint: 202, or 400 with `{ err, description }`. */
+  pushHandler(): (request: Request) => Promise<Response>;
+  /**
+   * RFC 8936: polls until no more SETs are available, acknowledging what it
+   * processed.
+   */
+  poll(options: SsfPollOptions): AsyncResult<SsfPollResult>;
+  /** The management API with this `Authorization` header value. */
+  streams(authorization: string): SsfStreamClient;
+  /** Deletes replay entries past the retention. */
+  purge(olderThan?: Temporal.Duration): AsyncResult<number>;
+}
+/**
+ * An SSF receiver: verifies pushed or polled SETs with the transmitter's keys,
+ * drops replays through the `security-events` module's `(iss, jti)` table, and
+ * calls the handler for the event type. Service role only.
+ */
+export declare function createSsfReceiver(options: SsfReceiverOptions): SsfReceiver;
+//#endregion
+//#region src/blocks/security-events/transmitter.d.ts
+type SsfDeliveryMethod = "push" | "poll";
+type SsfStreamStatus = "enabled" | "paused" | "disabled";
+/** A stream as the `security-events` module stores it. */
+interface SsfStream {
+  readonly id: string;
+  readonly tenant: string | null;
+  /** Who manages the stream: the receiver `authorize` returned. */
+  readonly receiver: string;
+  readonly audience: readonly string[];
+  readonly description: string | null;
+  readonly eventsRequested: readonly string[];
+  readonly eventsDelivered: readonly string[];
+  readonly method: SsfDeliveryMethod;
+  /** The receiver's push endpoint; `null` for a poll stream. */
+  readonly endpointUrl: string | null;
+  readonly status: SsfStreamStatus;
+  readonly reason: string | null;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+/** The receiver a management request comes from, as `authorize` found it. */
+interface SsfReceiverIdentity {
+  /** A stable id, such as the OAuth client id. */
+  readonly receiver: string;
+  /**
+   * Scopes the receiver's streams to one tenant's events; `null` for every
+   * tenant.
+   */
+  readonly tenant?: string | null;
+  /** The `aud` of its SETs. Default: `receiver`. */
+  readonly audience?: string | readonly string[];
+}
+interface CreateSsfStreamInput {
+  readonly receiver: SsfReceiverIdentity;
+  readonly method: SsfDeliveryMethod;
+  readonly eventsRequested: readonly string[];
+  /** The receiver's RFC 8935 endpoint, for push. */
+  readonly endpointUrl?: string;
+  /** The `Authorization` header value the endpoint expects, kept in Vault. */
+  readonly authorizationHeader?: string;
+  readonly description?: string;
+}
+interface UpdateSsfStreamInput {
+  readonly description?: string | null;
+  readonly eventsRequested?: readonly string[];
+  readonly endpointUrl?: string;
+}
+interface EmitSecurityEventInput {
+  readonly event: SecurityEvent;
+  readonly subject: SubjectIdentifier;
+  /** The tenant the event belongs to: its streams and the app-wide ones get it. */
+  readonly tenant?: string | null;
+  readonly txn?: string;
+}
+/** What `emit` did, per stream. */
+interface EmitResult {
+  readonly streams: number;
+  readonly dispatched: number;
+  readonly queued: number;
+  readonly held: number;
+}
+interface SsfTransmitterOptions extends BlockOptions {
+  /** The transmitter's issuer: an https URL, the `iss` of every SET. */
+  readonly issuer: string;
+  /**
+   * Where the signer's public keys are published, e.g.
+   * `signingKeys.jwksResponse`.
+   */
+  readonly jwksUri: string;
+  /** Signs the SETs: `signingKeys.signer({ type: "ssf", id: "transmitter" })`. */
+  readonly signer: SetSigner;
+  /**
+   * Authenticates a management or poll request and names its receiver; `null`
+   * answers 401. SSF requires the API to be authorized.
+   */
+  readonly authorize: (request: Request) => SsfReceiverIdentity | null | Promise<SsfReceiverIdentity | null>;
+  /** The route prefix under the issuer's origin. Default: `/ssf`. */
+  readonly basePath?: string;
+  /** The event types receivers can request. Default: every CAEP and RISC type. */
+  readonly eventsSupported?: readonly string[];
+  /** Default: both. */
+  readonly deliveryMethods?: readonly SsfDeliveryMethod[];
+  /** Seconds between verification requests per stream. Default: 30. */
+  readonly minVerificationInterval?: number;
+  /**
+   * Keeps a push stream's `authorization_header` in Vault. Without it, such
+   * requests fail.
+   */
+  readonly credentials?: Pick<VaultCredentials, "set" | "revoke">;
+  /**
+   * `authorization_schemes` in the metadata. Default: OAuth 2.0
+   * (`urn:ietf:rfc:6749`).
+   */
+  readonly authorizationSchemes?: readonly {
+    readonly spec_urn: string;
+  }[];
+  /** The largest management request body, in bytes. Default: 64 KiB. */
+  readonly maxBodyBytes?: number;
+  /**
+   * `withBlockHooks` hooks around the transmitter's methods; the routes call
+   * through them.
+   */
+  readonly hooks?: NoInfer<BlockHooks<SsfTransmitter>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+/** An SSF 1.0 transmitter on the `security-events` module. */
+interface SsfTransmitter {
+  /** The transmitter configuration metadata (SSF §7.1). */
+  metadata(): Readonly<Record<string, unknown>>;
+  createStream(input: CreateSsfStreamInput): AsyncResult<SsfStream>;
+  stream(id: string): AsyncResult<SsfStream | null>;
+  streams(receiver: string): AsyncResult<readonly SsfStream[]>;
+  updateStream(id: string, input: UpdateSsfStreamInput): AsyncResult<SsfStream | null>;
+  deleteStream(id: string): AsyncResult<boolean>;
+  /**
+   * Sets the status. Pausing or disabling sends `stream-updated` first;
+   * enabling sends it after the held SETs.
+   */
+  setStatus(id: string, status: SsfStreamStatus, reason?: string): AsyncResult<SsfStreamStatus>;
+  /** Sends a verification event (SSF §8.1.4). */
+  verify(id: string, state?: string): AsyncResult<string>;
+  /** Mints the event once per stream that delivers it and queues it. */
+  emit(input: EmitSecurityEventInput): AsyncResult<EmitResult>;
+  /** RFC 8936: acknowledges and returns SETs of a poll stream. */
+  poll(id: string, request: SsfPollRequest): AsyncResult<SsfPollResponse>;
+  /** Deletes replay entries and unpolled SETs past the retention. */
+  purge(olderThan?: Temporal.Duration): AsyncResult<number>;
+  /**
+   * The well-known metadata, stream management, status, verification and poll
+   * routes.
+   */
+  handler(): (request: Request) => Promise<Response>;
+}
+interface SsfPollRequest {
+  readonly maxEvents?: number;
+  readonly ack?: readonly string[];
+  readonly setErrs?: Readonly<Record<string, {
+    readonly err: string;
+    readonly description?: string;
+  }>>;
+}
+interface SsfPollResponse {
+  readonly sets: Readonly<Record<string, string>>;
+  readonly moreAvailable: boolean;
+}
+/**
+ * An SSF transmitter: streams and their status live in the `security-events`
+ * module, push SETs go out through webhooks-out endpoints with format `set`,
+ * and poll SETs wait in the module's queue. Service role only.
+ */
+export declare function createSsfTransmitter(options: SsfTransmitterOptions): SsfTransmitter;
+//#endregion
+//#region src/blocks/security-events/security-events.d.ts
+type SecurityEventsOptions = BlockOptions;
+/**
+ * The `security-events` block: transmitters and receivers on the shared
+ * transport.
+ */
+interface SecurityEvents {
+  transmitter(options: Omit<SsfTransmitterOptions, keyof BlockOptions>): SsfTransmitter;
+  receiver(options: Omit<SsfReceiverOptions, keyof BlockOptions>): SsfReceiver;
+}
+/**
+ * What `createBlocks` builds: each transmitter and receiver takes the block's
+ * transport.
+ */
+export declare function createSecurityEvents(options: SecurityEventsOptions): SecurityEvents;
+//#endregion
+//#region src/blocks/security-events/methods.d.ts
+/** RFC 8935 push delivery, as SSF names it in `delivery.method`. */
+export declare const SSF_PUSH = "urn:ietf:rfc:8935";
+/** RFC 8936 poll delivery. */
+export declare const SSF_POLL = "urn:ietf:rfc:8936";
+//#endregion
+//#region src/blocks/security-events/events.d.ts
+/** `ssf_stream.*`: the stream and the receiver that manages it. */
+interface SsfStreamEventData {
+  readonly streamId: string;
+  readonly receiver: string;
+  readonly tenant: string | null;
+}
+/** `ssf_stream.created` also carries the delivery method URN. */
+interface SsfStreamCreatedEventData extends SsfStreamEventData {
+  readonly method: string;
+}
+/** `ssf_stream.status_changed` carries the new status and its reason. */
+interface SsfStreamStatusEventData extends SsfStreamEventData {
+  readonly status: "enabled" | "paused" | "disabled";
+  readonly reason: string | null;
+}
+/** The events of the `security-events` block: type to data. */
+type SecurityEventsEvents = {
+  readonly "ssf_stream.created": SsfStreamCreatedEventData;
+  readonly "ssf_stream.status_changed": SsfStreamStatusEventData;
+  readonly "ssf_stream.deleted": SsfStreamEventData;
+};
+/**
+ * The `security-events` block's event types, for its manifest and
+ * `onBlockEvent`.
+ */
+export declare const securityEventsEvents: Events<SecurityEventsEvents>;
+//#endregion
+//#region src/blocks/security-events/manifest.d.ts
+/** The `security-events` block's manifest (ADR 0029). */
+export declare const securityEventsBlock: BlockOf<"security-events", typeof createSecurityEvents, SecurityEventsEvents>;
+//#endregion
+export { type BlockTransport, type CreateSsfStreamInput, type EmitResult, type EmitSecurityEventInput, type MintSetInput, type MintedSet, type SecurityEvent, type SecurityEvents, type SecurityEventsEvents, type SecurityEventsOptions, type SetErrorCode, type SetSigner, type SetVerification, type SsfDeliveryMethod, type SsfEventHandler, type SsfPollOptions, type SsfPollRequest, type SsfPollResponse, type SsfPollResult, type SsfReceiveResult, type SsfReceiver, type SsfReceiverIdentity, type SsfReceiverOptions, type SsfStream, type SsfStreamClient, type SsfStreamCreatedEventData, type SsfStreamEventData, type SsfStreamRequest, type SsfStreamStatus, type SsfStreamStatusEventData, type SsfTransmitter, type SsfTransmitterOptions, type SubjectIdentifier, type UpdateSsfStreamInput, type VerifiedSet, type VerifySetOptions, sqlTransport };