better-supabase 0.8.0 → 0.10.0

package/dist/blocks/audit/index.d.ts

@@ -1,377 +1,84 @@
 /// <reference lib="esnext.temporal" />
-import { t as AsyncResult, w as ErrorMapper } from "../../result-BchM1XZn.js";
-import { L as TableKey, a as AnyModels, i as AnyFunctions } from "../../types-CoE5Zwy4.js";
-import { t as SqlClient } from "../../executor-ngjKL_Pe.js";
-import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-inD4fFq-.js";
-import { r as BlockTemporalOptions } from "../../block-helpers-C0Xj8War.js";
-import { i as EventSink, t as CloudEvent } from "../../cloud-event-Dune0KI7.js";
-import { Bt as WhereInput, t as BetterSupabase } from "../../define-DmcfoNXB.js";
-import { i as ListDefinition } from "../../list-query-D3JQeEL7.js";
-import { n as AuditCategory } from "../../context-DsV2SueA.js";
-//#region src/blocks/audit/audit.d.ts
-interface PurgeAuditLogOptions extends BlockTemporalOptions {
-  /** How long entries are kept when `retention` has no answer. Defaults to `1 year`. */
-  readonly olderThan?: number | string;
-  /** The most entries deleted per tenant in one call. Defaults to 10000. */
-  readonly batch?: number;
-  /**
-   * Days a tenant keeps its entries (a plan's retention, say); `undefined`
-   * uses `olderThan`. Called with `null` for entries without a tenant.
-   * Retention shorter than a day is not supported. `setAuditRetention`
-   * reads the days from a column.
-   */
-  readonly retention?: (tenant: string | null) => number | undefined | Promise<number | undefined>;
-}
-type Retention = NonNullable<PurgeAuditLogOptions["retention"]>;
-/**
- * Deletes audit entries past their retention and returns how many. Without
- * `retention` it is one `purge_audit_log` call (which honours an
- * `audit_retention` SQL hook); with it, each tenant is purged with its own
- * interval. Run it from a schedule until it returns 0.
- */
-export declare function purgeAuditLog(sql: SqlClient, options?: PurgeAuditLogOptions): AsyncResult<number>;
-interface AuditRetentionSource {
-  /** `schema.table` holding one row per tenant, e.g. `public.organizations`. */
-  readonly table: string;
-  /** The integer column with the days to keep; `null` uses `olderThan`. */
-  readonly column: string;
-  /** The tenant id column. Defaults to `id`. */
-  readonly key?: string;
-}
-/**
- * A `retention` callback for `purgeAuditLog` that reads each tenant's days
- * from a column (a plan's `audit_retention_days`, say). `purgeAuditLog` reads
- * every tenant's days in one query; a direct call reads one tenant.
- */
-export declare function setAuditRetention(sql: SqlClient, source: AuditRetentionSource): Retention;
-/** One audit entry as `exportAuditLog` reads it. */
-interface AuditEntry {
-  readonly id: string;
-  readonly occurredAt: Temporal.Instant;
-  /** `insert`, `update` and `delete` for row changes; `event` for `audit_event()`. */
-  readonly op: string;
-  readonly table?: string;
-  readonly record?: string;
-  readonly changed?: readonly string[];
-  readonly actor?: string;
-  readonly actorRole?: string;
-  readonly organizationId?: string;
-  readonly eventType?: string;
-  readonly category?: string;
-  readonly outcome?: string;
-  readonly source?: string;
-  readonly targetType?: string;
-  readonly metadata?: Readonly<Record<string, unknown>>;
-}
-interface OcsfProduct {
-  readonly name: string;
-  readonly vendor_name?: string;
-  readonly version?: string;
-}
-/**
- * One entry as an OCSF event (`SPEC_PINS.ocsf`). Row changes are Entity
- * Management (3004); semantic events are API Activity (6003), with the
- * activity read from the event type's last segment (`deal.created` is Create).
- */
-export declare function toOcsf(entry: AuditEntry, product: OcsfProduct): Record<string, unknown>;
-interface ExportAuditLogOptions extends BlockTemporalOptions {
-  /** Only this tenant's entries. */
-  readonly organizationId: string;
-  readonly from?: Temporal.Instant;
-  /** Exclusive. */
-  readonly to?: Temporal.Instant;
-  /** `ndjson` writes entries as they are; `ocsf` maps each with `toOcsf`. */
-  readonly format?: "ndjson" | "ocsf";
-  /** Required for `ocsf`: `metadata.product`. */
-  readonly product?: OcsfProduct;
-  /** Rows per query. Defaults to 1000. */
-  readonly batch?: number;
-  /** Defaults to `better_supabase.audit_events`. */
-  readonly table?: string;
-}
-/**
- * Streams one tenant's audit entries as newline-delimited JSON, in id
- * order, one keyset query per batch. Run it with a member's claims (the
- * `readPolicy` filters) or as the service role. It reads the managed
- * module's column names; for an adopted log, the version 3 columns or CSV,
- * use `createAuditLog().export()`, which reads `list_audit_events`.
- */
-export declare function exportAuditLog(sql: SqlClient, options: ExportAuditLogOptions): ReadableStream<Uint8Array>;
-type AuditSort = "newest" | "oldest";
-type AuditFacet = "table" | "record" | "op" | "actor" | "event" | "category" | "outcome" | "target";
-type AuditListDefinition<M extends AnyModels, T extends TableKey<M>, E> = ListDefinition<M, T, E, AuditSort, AuditFacet, false, "cursor"> & {
-  /** A `where` for `run(db, query, { where })`: entries in `[from, to)`. */
-  between(from?: Temporal.Instant, to?: Temporal.Instant): WhereInput<M, T>;
+import { t as AsyncResult, w as ErrorMapper } from "../../result-Cj3yWhjH.js";
+import { b as AuditRevealEventData, wt as Events } from "../../events-CtAHxPal.js";
+import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-NbUJygA7.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-7pMBVsE6.js";
+import { s as BlockOf } from "../../define-block-BlHQxDIQ.js";
+import { A as AuditSort, C as auditSink, D as AuditFacet, E as AuditEntry, F as exportAuditLog, I as purgeAuditLog, L as setAuditRetention, M as OcsfProduct, N as PurgeAuditLogOptions, O as AuditListDefinition, P as auditListQuery, R as toOcsf, S as auditEventOf, T as AuditCsvOptions, _ as AuditPage, a as AuditLogSnapshot, b as createAudit, c as AuditCursor, d as AuditExportBucket, f as AuditExportOptions, g as AuditLogOptions, h as AuditLog, i as AuditLogControllerOptions, j as ExportAuditLogOptions, k as AuditRetentionSource, l as AuditDetails, m as AuditListOptions, n as AuditLogActions, o as createAuditLogController, p as AuditExportToStorageOptions, r as AuditLogController, s as AuditColumns, t as AuditFilters, u as AuditEventInput, v as AuditRecord, w as AuditCsvColumn, x as AuditSinkOptions, y as AuditReverted } from "../../client-B9H4BZJh.js";
+//#region src/blocks/audit/events.d.ts
+/** The events of the `audit` block: type to data. */
+type AuditEvents = {
+  readonly "audit.revealed": AuditRevealEventData;
 };
-/**
- * A cursor-paged list over the audit table through the Data API or
- * `ctx.sql` (generate types for the module's schema to get it in your
- * models; facets follow the managed column names). `createAuditLog().list()`
- * reads `list_audit_events` instead, with an adopted log's columns mapped.
- * Filtered by actor,
- * table, record, event type, category, outcome and target, newest first.
- * The `readPolicy` and the `restricted` table decide what a member sees.
- */
-export declare function auditListQuery<M extends AnyModels, D, Fn extends AnyFunctions, E, T extends TableKey<M>>(betterSupabase: BetterSupabase<M, D, Fn, E>, table: T, options?: {
-  readonly pageSize?: number;
-  readonly maxPageSize?: number;
-}): AuditListDefinition<M, T, E>;
+/** The `audit` block's event types, for its manifest and `onBlockEvent`. */
+export declare const auditEvents: Events<AuditEvents>;
 //#endregion
-//#region src/blocks/audit/csv.d.ts
-/** A CSV export column: a key, or a key and the header to write for it. */
-type AuditCsvColumn = string | {
-  readonly key: string;
-  readonly label: string;
-};
-/** How `export({ format: "csv" })` writes its rows. */
-interface AuditCsvOptions<Columns extends AuditColumns = AuditColumns> {
-  /**
-   * The columns, in order: a key of the record (`eventType`),
-   * `columns.<name>` for a column `metadataColumns` fills, or
-   * `restricted.<field>` (`ip`, `userAgent`, `sessionId`, `metadata`, `old`,
-   * `new` or `changes`) for a caller who may reveal the entries. A restricted
-   * column reads each page through `reveal_audit_entries`, which records
-   * `audit.revealed`, and is empty for entries the caller may not reveal.
-   * Defaults to the built-in columns.
-   */
-  readonly columns?: readonly AuditCsvColumn[];
-  /** Lines written before the header row, one cell each, such as a title. */
-  readonly preamble?: readonly string[];
-  /**
-   * The row to write, by column key. It gets the default row, the record and
-   * its restricted details (only with a restricted column).
-   */
-  readonly formatRow?: (row: Readonly<Record<string, unknown>>, record: AuditRecord<Columns>, details: AuditDetails | undefined) => Readonly<Record<string, unknown>>;
-}
-//#endregion
-//#region src/blocks/audit/sink.d.ts
-interface AuditSinkOptions {
-  /** The type prefix stripped from each event's `type`. Defaults to `dev.better-supabase`. */
-  readonly typePrefix?: string;
-  /**
-   * The category for an event type (without the prefix), from the categories
-   * the SQL modules use. Defaults to `security` for `account.*` and
-   * `support.*`, and no category for the rest.
-   */
-  readonly category?: (eventType: string) => AuditCategory | undefined;
-}
-/**
- * The audit entry for one CloudEvent: its type without the prefix, its
- * subject as the record, the tenant from the `tenant` or `partitionkey`
- * extension (or `data.organizationId`), and the data as metadata. The
- * idempotency key is the event's source and id, so a redelivery records once.
- * A `support.*` event also fills the impersonation columns from its
- * `sessionId`, `adminId` and `reason`.
- */
-export declare function auditEventOf(event: CloudEvent, options?: AuditSinkOptions): AuditEventInput;
-/**
- * An `EventSink` that records each CloudEvent in the audit log. `send`
- * throws when an entry fails, so an outbox relay retries the batch; the
- * idempotency key keeps the entries already written from repeating.
- */
-export declare function auditSink(record: (event: AuditEventInput) => AsyncResult<string>, options?: AuditSinkOptions): EventSink;
+//#region src/blocks/audit/manifest.d.ts
+/** The `audit` block's manifest (ADR 0029). */
+export declare const auditBlock: BlockOf<"audit", typeof createAudit, AuditEvents>;
 //#endregion
-//#region src/blocks/audit/client.d.ts
-/** The adopted log's own columns, by column name, as `metadataColumns` maps them. */
-type AuditColumns = Readonly<Record<string, unknown>>;
-/**
- * One entry as `list_audit_events` returns it: the module's columns under
- * stable keys, whatever the adopted log calls them. Fields the log doesn't
- * have, or the caller may not read, are missing.
- */
-interface AuditRecord<Columns extends AuditColumns = AuditColumns> {
-  readonly id: string;
-  readonly occurredAt: Temporal.Instant;
-  readonly op?: string;
-  readonly table?: string;
-  readonly record?: string;
-  readonly changed?: readonly string[];
-  readonly old?: Readonly<Record<string, unknown>>;
-  readonly new?: Readonly<Record<string, unknown>>;
-  readonly actorId?: string;
-  readonly actorRole?: string;
-  readonly actorKind?: string;
-  readonly actorLabel?: string;
-  readonly tenant?: string;
-  readonly tenantLabel?: string;
-  readonly impersonatedBy?: string;
-  readonly impersonationReason?: string;
-  readonly supportSession?: string;
-  readonly eventType?: string;
-  readonly category?: string;
-  readonly outcome?: string;
-  readonly source?: string;
-  readonly targetType?: string;
-  readonly targetLabel?: string;
-  readonly summary?: string;
-  readonly requestId?: string;
-  readonly correlationId?: string;
-  readonly scope?: string;
-  readonly metadata?: Readonly<Record<string, unknown>>;
-  /**
-   * The adopted log's columns that `sql.modules.audit.options.metadataColumns`
-   * fills, by column name. Missing without that option.
-   */
-  readonly columns?: Readonly<Partial<Columns>>;
-}
-/** Where a page ends: pass it as `before` for the next, older page. */
-interface AuditCursor {
-  readonly occurredAt: Temporal.Instant;
+//#region src/blocks/audit/chain.d.ts
+/** Why `verify` stopped: the row changed, a link or an entry is missing, or a signed head disagrees. */
+type AuditChainBreak = "hash" | "link" | "gap" | "checkpoint";
+type AuditChainVerdict = {
+  readonly valid: true;
+  readonly checked: number;
+  /** The last entry's position, absent for an empty range. */
+  readonly seq: number | undefined;
+  /** The last entry's hash (hex), to compare with a checkpoint kept elsewhere. */
+  readonly hash: string | undefined;
+} | {
+  readonly valid: false;
+  readonly checked: number;
+  readonly seq: number;
+  /** The first broken entry, absent when the range ends early (`gap`). */
+  readonly brokenAt: string | undefined;
+  readonly reason: AuditChainBreak;
+};
+/** A tenant's latest entry that no checkpoint covers. */
+interface AuditChainHead {
+  readonly organizationId: string | undefined;
+  readonly seq: number;
+  readonly hash: string;
+  readonly entryId: string;
+}
+interface AuditCheckpoint extends AuditChainHead {
   readonly id: string;
+  readonly keyId: string;
+  /** The compact JWS over `sub`, `seq`, `hash`, `entry` and `iat`. */
+  readonly signature: string;
+  readonly createdAt: Temporal.Instant;
 }
-type OneOrMany = string | readonly string[];
-interface AuditListOptions {
-  readonly organizationId?: OneOrMany;
-  readonly eventType?: OneOrMany;
-  readonly actorId?: OneOrMany;
-  readonly targetType?: OneOrMany;
-  readonly record?: OneOrMany;
-  readonly category?: OneOrMany;
-  readonly outcome?: OneOrMany;
-  readonly source?: OneOrMany;
-  readonly actorKind?: OneOrMany;
-  readonly correlationId?: OneOrMany;
-  readonly search?: string;
-  readonly order?: "desc" | "asc";
-  readonly count?: boolean;
-  /** Entries at or after this instant. */
-  readonly since?: Temporal.Instant;
-  /** Entries before this instant. */
-  readonly until?: Temporal.Instant;
-  /** `page.next` of the previous page; `undefined` starts at the newest. */
-  readonly cursor?: AuditCursor | undefined;
-  /** Default 50, at most 1000. */
-  readonly limit?: number;
-  readonly offset?: number;
-}
-interface AuditPage<Columns extends AuditColumns = AuditColumns> {
-  readonly entries: readonly AuditRecord<Columns>[];
-  /** The cursor of the next page, or `undefined` on the last one. */
-  readonly next: AuditCursor | undefined;
-  readonly total?: number;
-}
-/** The restricted details `reveal` returns, when the entry has them. */
-interface AuditDetails {
-  readonly entry: string;
-  readonly old?: Readonly<Record<string, unknown>>;
-  readonly new?: Readonly<Record<string, unknown>>;
-  readonly ip?: string;
-  readonly userAgent?: string;
-  readonly metadata?: Readonly<Record<string, unknown>>;
-  readonly sessionId?: string;
-  readonly changes?: unknown;
+/** What signs a checkpoint: the signing-keys block's `Signer` fits. */
+interface AuditCheckpointSigner {
+  signJwt(claims: Readonly<Record<string, unknown>>): AsyncResult<string>;
 }
-interface AuditExportOptions<Columns extends AuditColumns = AuditColumns> extends Omit<AuditListOptions, "before" | "limit" | "count">, AuditCsvOptions<Columns> {
-  /**
-   * `ndjson` (default) writes the records as they are, `csv` a spreadsheet
-   * with a header row, `ocsf` each record mapped with `toOcsf`.
-   */
-  readonly format?: "ndjson" | "csv" | "ocsf";
-  /** Required for `ocsf`: `metadata.product`. */
-  readonly product?: OcsfProduct;
-  /** Entries per call. Default 500. */
-  readonly batch?: number;
-}
-/** The part of `supabase.storage.from(bucket)` an export upload uses. */
-interface AuditExportBucket {
-  upload(path: string, body: Blob, options?: {
-    contentType?: string;
-    upsert?: boolean;
-  }): PromiseLike<{
-    readonly data: unknown;
-    readonly error: unknown;
-  }>;
-  createSignedUrl?(path: string, expiresIn: number, options?: {
-    download?: string | boolean;
-  }): PromiseLike<{
-    readonly data: {
-      readonly signedUrl: string;
-    } | null;
-    readonly error: unknown;
-  }>;
-}
-interface AuditExportToStorageOptions<Columns extends AuditColumns = AuditColumns> extends AuditExportOptions<Columns> {
-  readonly storage: {
-    from(bucket: string): AuditExportBucket;
-  };
-  readonly bucket: string;
-  /** The object path, such as `{organizationId}/audit/{jobId}.csv`. */
-  readonly path: string;
-  /** Also sign a download URL that lives this many seconds. */
-  readonly signedUrlTtl?: number;
-}
-interface AuditEventInput {
-  readonly eventType: string;
-  readonly category?: string;
-  readonly outcome?: string;
-  readonly source?: string;
-  readonly targetType?: string;
-  readonly record?: string;
-  readonly organizationId?: string;
-  readonly metadata?: Readonly<Record<string, unknown>>;
-  readonly idempotencyKey?: string;
-  readonly restricted?: Readonly<Record<string, unknown>>;
-  readonly summary?: string;
-  readonly targetLabel?: string;
-  readonly correlationId?: string;
-  readonly actorId?: string;
-  readonly actorKind?: string;
-  readonly actorLabel?: string;
-  readonly ip?: string;
-  readonly userAgent?: string;
-  readonly sessionId?: string;
-  readonly requestId?: string;
-  readonly scope?: string;
-  /**
-   * The support session the event belongs to, its admin and their reason,
-   * for the impersonation columns. Honoured for the service role; any other
-   * caller may only name itself as `impersonatedBy`, from a token without an
-   * `act` claim, and otherwise gets the claim's values.
-   */
-  readonly supportSessionId?: string;
-  readonly impersonatedBy?: string;
-  readonly impersonationReason?: string;
-}
-interface AuditLogOptions extends BlockTemporalOptions {
-  /** `sqlTransport(ctx.postgres)` for members, or `rpcTransport` over an API schema. */
+interface AuditChainOptions extends BlockTemporalOptions {
+  /** A service-role transport: the functions are granted to `service_role` only. */
   readonly transport: BlockTransport;
-  /** The audit module's schema, or its API schema. Default `better_supabase`. */
+  /** Required for `checkpoint()`. */
+  readonly signer?: AuditCheckpointSigner;
+  /** The `iss` claim of each checkpoint. */
+  readonly issuer?: string;
   readonly schema?: string;
   readonly mappers?: readonly ErrorMapper[];
 }
-interface AuditLog<Columns extends AuditColumns = AuditColumns> {
-  record(event: AuditEventInput): AsyncResult<string>;
-  /** A page of the entries the caller can read, newest first. */
-  list(options?: AuditListOptions): AsyncResult<AuditPage<Columns>>;
-  /**
-   * The restricted details of one entry for a caller with the reveal
-   * permission in its tenant (or platform staff); the reveal is itself
-   * recorded as `audit.revealed`. `not_found` otherwise.
-   */
-  reveal(entryId: string): AsyncResult<AuditDetails>;
-  /** Every matching entry as NDJSON, CSV or OCSF, read page by page as the caller. */
-  export(options?: AuditExportOptions<Columns>): ReadableStream<Uint8Array>;
-  /**
-   * Writes an export to a Storage object, for a job that runs it in the
-   * background (the data lifecycle export bucket, say), and returns the path
-   * and a signed URL when `signedUrlTtl` is set.
-   */
-  exportToStorage(options: AuditExportToStorageOptions<Columns>): AsyncResult<{
-    readonly path: string;
-    readonly url: string | undefined;
-  }>;
-  /**
-   * An `EventSink` that records CloudEvents, for `forwardBlockEvents`,
-   * `forwardMutations`, an outbox relay or the server's `audit` option.
-   * Build the log on a service-role transport so the event's actor counts.
-   */
-  sink(options?: AuditSinkOptions): EventSink;
-}
-/**
- * The audit log over the `audit` module's functions, as the caller: the
- * read policy decides what `list` and `export` return, and column mappings
- * of an adopted log are already applied.
- */
-export declare function createAuditLog<Columns extends AuditColumns = AuditColumns>(options: AuditLogOptions): AuditLog<Columns>;
+interface AuditChain {
+  /** Checks a tenant's entries (none: those without a tenant) in chain order. */
+  verify(range?: {
+    readonly organizationId?: string;
+    readonly from?: Temporal.Instant;
+    readonly to?: Temporal.Instant;
+  }): AsyncResult<AuditChainVerdict>;
+  heads(): AsyncResult<readonly AuditChainHead[]>;
+  /** Signs and records every head; run it on a schedule. */
+  checkpoint(): AsyncResult<readonly AuditCheckpoint[]>;
+  checkpoints(options?: {
+    readonly organizationId?: string;
+    readonly limit?: number;
+  }): AsyncResult<readonly AuditCheckpoint[]>;
+}
+/** The audit hash chain (`blocks.audit.options.chain`), as the service role. */
+export declare function createAuditChain(options: AuditChainOptions): AuditChain;
 //#endregion
-export { type AuditColumns, type AuditCsvColumn, type AuditCsvOptions, type AuditCursor, type AuditDetails, type AuditEntry, type AuditEventInput, type AuditExportBucket, type AuditExportOptions, type AuditExportToStorageOptions, type AuditFacet, type AuditListDefinition, type AuditListOptions, type AuditLog, type AuditLogOptions, type AuditPage, type AuditRecord, type AuditRetentionSource, type AuditSinkOptions, type AuditSort, type BlockTransport, type ExportAuditLogOptions, type OcsfProduct, type PurgeAuditLogOptions, dbTransport, rpcTransport, sqlTransport };
+export { type AuditChain, type AuditChainBreak, type AuditChainHead, type AuditChainOptions, type AuditChainVerdict, type AuditCheckpoint, type AuditCheckpointSigner, type AuditColumns, type AuditCsvColumn, type AuditCsvOptions, type AuditCursor, type AuditDetails, type AuditEntry, type AuditEventInput, type AuditEvents, type AuditExportBucket, type AuditExportOptions, type AuditExportToStorageOptions, type AuditFacet, type AuditFilters, type AuditListDefinition, type AuditListOptions, type AuditLog, type AuditLogActions, type AuditLogController, type AuditLogControllerOptions, type AuditLogOptions, type AuditLogSnapshot, type AuditPage, type AuditRecord, type AuditRetentionSource, type AuditReverted, type AuditSinkOptions, type AuditSort, type BlockTransport, type ExportAuditLogOptions, type OcsfProduct, type PurgeAuditLogOptions, auditEventOf, auditListQuery, auditSink, createAudit, createAuditLogController, dbTransport, exportAuditLog, purgeAuditLog, rpcTransport, setAuditRetention, sqlTransport, toOcsf };