@coffre/db 0.14.5 → 0.15.0

package/dist/log.d.ts

@@ -1,622 +1,2 @@
-import { a as Transaction, i as Queryable } from "./database-wq1AVRAP.js";
-import { Placeholder, SQL } from "drizzle-orm";
-import { LogKey, StoredEntry } from "@coffre/core/audit";
-//#region src/log.d.ts
-/**
- * Appending to the audit log, the one table both the app and the vault
- * write, each under its own key (@coffre/core/audit says what an entry's MAC
- * and hash cover).
- *
- * Every append locks the log's head first, `audit_chain_head`, so entries
- * from any process take their numbers in one order. It then reads the
- * database clock, after the lock, and the log's last entry, which the head
- * must name: a head that does not was moved, or entries were deleted behind
- * it, and the append refuses. The same statement says whether the log has
- * moved on from the key it appends under (`KeyRetired`).
- *
- * This is deliberately not a queue and not best-effort: the entries go in
- * the caller's transaction, so if the append fails, what it records does
- * not happen either.
- */
-/** An entry to append: what it says. The append numbers, dates, signs and chains it. */
-export type NewEntry = {
-  actor: string;
-  action: string;
-  decision: 'allow' | 'deny';
-  code?: string | null;
-  subjectPrincipal?: string | null;
-  projectId?: string | null;
-  environmentId?: string | null;
-  secretId?: string | null;
-  secretVersionId?: string | null;
-  operationId?: string | null;
-  requestId?: string | null;
-  sourceIp?: string | null;
-  relatedSeq?: bigint | null;
-  /** JSON text. */
-  metadata?: string;
-};
-export type Appended = {
-  /** The first entry's number, and the next number after the last. */
-  seqStart: bigint;
-  nextSeq: bigint;
-  headHash: Buffer;
-  /** Milliseconds since the epoch, the database's, shared by the batch. */
-  occurredAt: number;
-};
-/** The log's head does not name its last entry: something moved it, or cut the log behind it. */
-export declare class LogHeadMismatch extends Error {
-  constructor(message: string);
-}
-/**
- * As many transactions as may already wait for the log's head do
- * (`lockLogHeadQueued`): this one waits for nothing, and holds nothing.
- * Its code is Postgres's for a lock not available, so every caller already
- * answers it as one that gave up waiting: unavailable, ask again shortly.
- */
-export declare class HeadBusy extends Error {
-  readonly code = "55P03";
-  constructor();
-}
-/**
- * The log's head is behind one this process wrote: the database was rolled
- * back, or entries were cut off its end. That cannot be told from a restore,
- * so the append refuses and someone has to look.
- */
-export declare class LogRewound extends Error {
-  constructor(message: string);
-}
-/**
- * An append under a key the log has moved on from: an entry of its
- * author's, `key.reseal` or `key.rotate`, names it as the key it moves
- * from (`MOVES_FROM`), and a key moved from writes no more.
- */
-export declare class KeyRetired extends Error {
-  constructor(message: string);
-}
-/**
- * The actions by which an author moves to a new key, each under the new one
- * and naming the key it moves from as its subject: from the first, that key
- * writes no more (`KeyRetired`). The app's key rotation writes them
- * (packages/server/src/key-rotation.ts).
- */
-export declare const MOVES_FROM: readonly ["key.reseal", "key.rotate"];
-/**
- * Forget every head written so far. For tests that empty the database
- * between cases, which is exactly what the check above refuses.
- */
-export declare function forgetLogHeads(): void;
-/**
- * Lock the log's head, and read it. A transaction that appends takes this
- * before any other row, so the lock order is the same everywhere; taking it
- * again in the same transaction is free.
- */
-export declare function lockLogHead(tx: Transaction): Promise<{
-  nextSeq: bigint;
-  headHash: Buffer;
-}>;
-/**
- * Lock the log's head if no one holds it, without waiting: whether it is
- * held now. For work any caller may do, of which one at a time is enough,
- * which a request that finds the head taken leaves to the one that has it.
- * SQLite's transactions hold the whole file, so the head is always free.
- */
-export declare function lockLogHeadIfFree(tx: Transaction): Promise<boolean>;
-/**
- * Lock the log's head, waiting for it as `lockLogHead` does, if fewer than
- * `waiters` other transactions hold one of its places in line; otherwise
- * refuse at once (`HeadBusy`), having waited for nothing. A place is an
- * advisory lock, tried, never waited for, and held to the end of the
- * transaction, which holds the head by then: so at most `waiters`
- * connections wait for the head, or hold it, through here, and a burst
- * beyond them answers in one round trip rather than seconds later, holding
- * a connection all the while. One statement: the place, then, only if one
- * was free, the head; refused, one more says whether the head is there at
- * all. SQLite's transactions hold the whole file.
- */
-export declare function lockLogHeadQueued(tx: Transaction, waiters: number): Promise<{
-  nextSeq: bigint;
-  headHash: Buffer;
-}>;
-/**
- * Append `entries` under `key`. `check`, when given, runs once the head is
- * locked and before anything is written: a writer's own condition on the
- * log as it stands, which no other append can change until this one
- * commits. It throws to refuse.
- */
-export declare function appendEntries(tx: Transaction, key: LogKey, entries: readonly NewEntry[], check?: (tx: Transaction) => Promise<void>,
-/**
- * The head as a statement of the caller's locked it, with the log's last
- * entry and the clock as that statement read them once it held the lock:
- * nothing to read again.
- */
-locked?: HeldHead): Promise<Appended>;
-/** A head locked by a statement of the caller's, and what it read under the lock (`appendEntries`). */
-export type HeldHead = {
-  head: {
-    nextSeq: bigint;
-    headHash: Buffer;
-  };
-  last: {
-    seq: bigint;
-    hash: Buffer;
-  } | null;
-  at: number;
-};
-/** An entry's columns, as the chain's codec reads them (`StoredEntry`). */
-export declare function entryColumns(db: Queryable): {
-  seq: import("drizzle-orm/pg-core").PgColumn<{
-    name: "seq";
-    tableName: "audit_log";
-    dataType: "bigint";
-    columnType: "PgBigInt64";
-    data: bigint;
-    driverParam: string;
-    notNull: true;
-    hasDefault: false;
-    isPrimaryKey: true;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: undefined;
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {}>;
-  author: import("drizzle-orm/pg-core").PgColumn<{
-    name: "author";
-    tableName: "audit_log";
-    dataType: "string";
-    columnType: "PgText";
-    data: string;
-    driverParam: string;
-    notNull: true;
-    hasDefault: false;
-    isPrimaryKey: false;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: [string, ...string[]];
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {}>;
-  keyId: import("drizzle-orm/pg-core").PgColumn<{
-    name: "key_id";
-    tableName: "audit_log";
-    dataType: "string";
-    columnType: "PgText";
-    data: string;
-    driverParam: string;
-    notNull: true;
-    hasDefault: false;
-    isPrimaryKey: false;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: [string, ...string[]];
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {}>;
-  occurredAt: import("drizzle-orm/pg-core").PgColumn<{
-    name: "occurred_at";
-    tableName: "audit_log";
-    dataType: "number";
-    columnType: "PgBigInt53";
-    data: number;
-    driverParam: string | number;
-    notNull: true;
-    hasDefault: false;
-    isPrimaryKey: false;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: undefined;
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {}>;
-  actor: import("drizzle-orm/pg-core").PgColumn<{
-    name: "actor";
-    tableName: "audit_log";
-    dataType: "string";
-    columnType: "PgText";
-    data: string;
-    driverParam: string;
-    notNull: true;
-    hasDefault: false;
-    isPrimaryKey: false;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: [string, ...string[]];
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {}>;
-  action: import("drizzle-orm/pg-core").PgColumn<{
-    name: "action";
-    tableName: "audit_log";
-    dataType: "string";
-    columnType: "PgText";
-    data: string;
-    driverParam: string;
-    notNull: true;
-    hasDefault: false;
-    isPrimaryKey: false;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: [string, ...string[]];
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {}>;
-  decision: import("drizzle-orm/pg-core").PgColumn<{
-    name: "decision";
-    tableName: "audit_log";
-    dataType: "string";
-    columnType: "PgText";
-    data: string;
-    driverParam: string;
-    notNull: true;
-    hasDefault: false;
-    isPrimaryKey: false;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: [string, ...string[]];
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {}>;
-  code: import("drizzle-orm/pg-core").PgColumn<{
-    name: "code";
-    tableName: "audit_log";
-    dataType: "string";
-    columnType: "PgText";
-    data: string;
-    driverParam: string;
-    notNull: false;
-    hasDefault: false;
-    isPrimaryKey: false;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: [string, ...string[]];
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {}>;
-  subjectPrincipal: import("drizzle-orm/pg-core").PgColumn<{
-    name: "subject_principal";
-    tableName: "audit_log";
-    dataType: "string";
-    columnType: "PgText";
-    data: string;
-    driverParam: string;
-    notNull: false;
-    hasDefault: false;
-    isPrimaryKey: false;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: [string, ...string[]];
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {}>;
-  projectId: import("drizzle-orm/pg-core").PgColumn<{
-    name: "project_id";
-    tableName: "audit_log";
-    dataType: "string";
-    columnType: "PgUUID";
-    data: string;
-    driverParam: string;
-    notNull: false;
-    hasDefault: false;
-    isPrimaryKey: false;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: undefined;
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {}>;
-  environmentId: import("drizzle-orm/pg-core").PgColumn<{
-    name: "environment_id";
-    tableName: "audit_log";
-    dataType: "string";
-    columnType: "PgUUID";
-    data: string;
-    driverParam: string;
-    notNull: false;
-    hasDefault: false;
-    isPrimaryKey: false;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: undefined;
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {}>;
-  secretId: import("drizzle-orm/pg-core").PgColumn<{
-    name: "secret_id";
-    tableName: "audit_log";
-    dataType: "string";
-    columnType: "PgUUID";
-    data: string;
-    driverParam: string;
-    notNull: false;
-    hasDefault: false;
-    isPrimaryKey: false;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: undefined;
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {}>;
-  secretVersionId: import("drizzle-orm/pg-core").PgColumn<{
-    name: "secret_version_id";
-    tableName: "audit_log";
-    dataType: "string";
-    columnType: "PgUUID";
-    data: string;
-    driverParam: string;
-    notNull: false;
-    hasDefault: false;
-    isPrimaryKey: false;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: undefined;
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {}>;
-  operationId: import("drizzle-orm/pg-core").PgColumn<{
-    name: "operation_id";
-    tableName: "audit_log";
-    dataType: "string";
-    columnType: "PgUUID";
-    data: string;
-    driverParam: string;
-    notNull: false;
-    hasDefault: false;
-    isPrimaryKey: false;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: undefined;
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {}>;
-  requestId: import("drizzle-orm/pg-core").PgColumn<{
-    name: "request_id";
-    tableName: "audit_log";
-    dataType: "string";
-    columnType: "PgText";
-    data: string;
-    driverParam: string;
-    notNull: false;
-    hasDefault: false;
-    isPrimaryKey: false;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: [string, ...string[]];
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {}>;
-  sourceIp: import("drizzle-orm/pg-core").PgColumn<{
-    name: "source_ip";
-    tableName: "audit_log";
-    dataType: "string";
-    columnType: "PgText";
-    data: string;
-    driverParam: string;
-    notNull: false;
-    hasDefault: false;
-    isPrimaryKey: false;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: [string, ...string[]];
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {}>;
-  relatedSeq: import("drizzle-orm/pg-core").PgColumn<{
-    name: "related_seq";
-    tableName: "audit_log";
-    dataType: "bigint";
-    columnType: "PgBigInt64";
-    data: bigint;
-    driverParam: string;
-    notNull: false;
-    hasDefault: false;
-    isPrimaryKey: false;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: undefined;
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {}>;
-  metadata: import("drizzle-orm/pg-core").PgColumn<{
-    name: "metadata";
-    tableName: "audit_log";
-    dataType: "string";
-    columnType: "PgText";
-    data: string;
-    driverParam: string;
-    notNull: true;
-    hasDefault: true;
-    isPrimaryKey: false;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: [string, ...string[]];
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {}>;
-  prevHash: import("drizzle-orm/pg-core").PgColumn<{
-    name: "prev_hash";
-    tableName: "audit_log";
-    dataType: "custom";
-    columnType: "PgCustomColumn";
-    data: Buffer<ArrayBufferLike>;
-    driverParam: unknown;
-    notNull: true;
-    hasDefault: false;
-    isPrimaryKey: false;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: undefined;
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {
-    pgColumnBuilderBrand: "PgCustomColumnBuilderBrand";
-  }>;
-  mac: import("drizzle-orm/pg-core").PgColumn<{
-    name: "mac";
-    tableName: "audit_log";
-    dataType: "custom";
-    columnType: "PgCustomColumn";
-    data: Buffer<ArrayBufferLike>;
-    driverParam: unknown;
-    notNull: true;
-    hasDefault: false;
-    isPrimaryKey: false;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: undefined;
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {
-    pgColumnBuilderBrand: "PgCustomColumnBuilderBrand";
-  }>;
-  hash: import("drizzle-orm/pg-core").PgColumn<{
-    name: "hash";
-    tableName: "audit_log";
-    dataType: "custom";
-    columnType: "PgCustomColumn";
-    data: Buffer<ArrayBufferLike>;
-    driverParam: unknown;
-    notNull: true;
-    hasDefault: false;
-    isPrimaryKey: false;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: undefined;
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {
-    pgColumnBuilderBrand: "PgCustomColumnBuilderBrand";
-  }>;
-};
-/**
- * Metadata a reader of many entries holds at once, at most: an entry about
- * a read of several secrets lists them, a thousand some 150 kilobytes, so a
- * count of entries alone does not bound a batch's or a page's memory within
- * a Worker's 128 megabytes.
- */
-export declare const BATCH_BYTES: number;
-/**
- * Of the entries `where` matches, in `order` of seq, the first `limit` or
- * fewer that hold no more than `BATCH_BYTES` of metadata between them, but
- * always the first: the seqs they run from and to, and whether the bytes
- * cut the run short of `limit`. Null when none matches. A reader asks this
- * first, then reads `where` between the two.
- */
-export declare function withinBytes(db: Queryable, where: SQL | undefined, limit: number, order?: 'asc' | 'desc'): Promise<{
-  from: bigint;
-  to: bigint;
-  cut: boolean;
-  count: number;
-} | null>;
-/**
- * The first entry missing from the log up to `seq`, and the one found in
- * its place, or null when every one is there. Seqs are the primary key, so
- * a stretch is whole exactly when its count is its length: one pass over
- * the key's index, never the entries. Only a log with a gap pays for more,
- * a count per halving to find where.
- *
- *   entries 0..9, 4 cut:  { expected: 4n, found: 5n }
- */
-export declare function missingEntry(db: Queryable, seq: bigint): Promise<{
-  expected: bigint;
-  found: bigint | null;
-} | null>;
-/**
- * How a reader tells the vault's own entries from those forged in its name:
- * by their MAC, which only the vault holds the key to check. Each it finds
- * forged goes to `forged`.
- */
-export type Authenticity = {
-  authentic: (entry: StoredEntry) => boolean;
-  forged: (entry: StoredEntry) => void;
-};
-/** Up to `limit` of the entries in the vault's name, allowed, of one `action`, before `before` (the newest when undefined), newest first. */
-export declare function newestVaultEntries(db: Queryable, action: string, limit: number, before?: bigint): Promise<StoredEntry[]>;
-/**
- * The number of the newest entry in the vault's name, allowed, of one
- * `action`, or null for none: whether one was appended since, and nothing
- * of what it says, so its MAC is not checked. One indexed read.
- */
-export declare function newestVaultSeq(db: Queryable, action: string): Promise<bigint | null>;
-/**
- * `newestVaultSeq`'s query, to run or to read inside another, as a
- * credential's read takes the newest `policy.change` with it: one rule for
- * what the newest is, wherever it is read.
- */
-export declare function newestSeqQuery(db: Queryable, action: string | Placeholder): Omit<import("drizzle-orm/pg-core").PgSelectBase<"audit_log", {
-  seq: import("drizzle-orm/pg-core").PgColumn<{
-    name: "seq";
-    tableName: "audit_log";
-    dataType: "bigint";
-    columnType: "PgBigInt64";
-    data: bigint;
-    driverParam: string;
-    notNull: true;
-    hasDefault: false;
-    isPrimaryKey: true;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: undefined;
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {}>;
-}, "partial", Record<"audit_log", "not-null">, false, "where" | "orderBy" | "limit", {
-  seq: bigint;
-}[], {
-  seq: import("drizzle-orm/pg-core").PgColumn<{
-    name: "seq";
-    tableName: "audit_log";
-    dataType: "bigint";
-    columnType: "PgBigInt64";
-    data: bigint;
-    driverParam: string;
-    notNull: true;
-    hasDefault: false;
-    isPrimaryKey: true;
-    isAutoincrement: false;
-    hasRuntimeDefault: false;
-    enumValues: undefined;
-    baseColumn: never;
-    identity: undefined;
-    generated: undefined;
-  }, {}, {}>;
-}>, "where" | "orderBy" | "limit">;
-/** How many entries in its name the vault reads back, a page at a time, for its own newest of a kind (`newestAuthentic`). */
-export declare const LOOK_BACK: {
-  page: number;
-  pages: number;
-};
-/** What `newestAuthentic` finds: the entry, or why there is none. */
-export type Newest = StoredEntry | 'none' | 'forged' | 'unreached';
-/**
- * The newest of the entries `page` reads, newest first and before a seq,
- * that `check` finds authentic: the newest alone first, which it is unless
- * entries were forged in the vault's name since, then back a page at a
- * time. 'none' when there are none at all, 'forged' when every one is in
- * the vault's name but not its own, and 'unreached' once it has read
- * LOOK_BACK such entries (1024), whether or not more are left.
- */
-export declare function newestAuthentic(page: (limit: number, before: bigint | undefined) => Promise<StoredEntry[]>, check: Authenticity): Promise<Newest>;
-//#endregion
+import { A as ChangeRecord, C as logObject, D as newestVaultEntries, E as newestSeqQuery, M as recorded, O as newestVaultSeq, S as lockLogHeadQueued, T as newestAuthentic, _ as holdFence, a as HeldHead, b as lockLogHead, c as LogHeadMismatch, d as NewEntry, f as Newest, g as forgetLogHeads, h as entryColumns, i as HeadBusy, j as RECORDS, k as withinBytes, l as LogRewound, m as appendEntries, n as Authenticity, o as KeyRetired, p as appChanges, r as BATCH_BYTES, s as LOOK_BACK, t as Appended, u as MOVES_FROM, v as holdIssues, w as missingEntry, x as lockLogHeadIfFree, y as isStaleChange } from "./log-DaD7fyUq.js";
+export { Appended, Authenticity, BATCH_BYTES, type ChangeRecord, HeadBusy, HeldHead, KeyRetired, LOOK_BACK, LogHeadMismatch, LogRewound, MOVES_FROM, NewEntry, Newest, RECORDS, appChanges, appendEntries, entryColumns, forgetLogHeads, holdFence, holdIssues, isStaleChange, lockLogHead, lockLogHeadIfFree, lockLogHeadQueued, logObject, missingEntry, newestAuthentic, newestSeqQuery, newestVaultEntries, newestVaultSeq, recorded, withinBytes };