@coffre/vault 0.14.5 → 0.15.0

package/README.md

@@ -10,16 +10,18 @@ import { postgres, vault } from '@coffre/vault/cloudflare';
 
 export default vault((env) => ({
   database: postgres(env.VAULT_HYPERDRIVE), // coffre_vault_runtime, caching disabled
+  hotDatabase: postgres(env.HOT_HYPERDRIVE), // coffre_vault_hot, for 0.15's uses
   kek: { id: env.VAULT_KEY_ID, key: env.VAULT_KEY }, // or awsKms({ keyArn, credentials }), with a signingKey
   owners: env.OWNERS.split(','), // Owners of the whole instance, whom nobody demotes while named
 }));
 ```
 
-On Node, `serveVault({ socket, database, … })` from `@coffre/vault/node`,
-with the vault's Postgres URL. Only `coffre_vault_runtime` may write members
-and grants; the app uses `coffre_runtime`. See the
+On Node, `serveVault({ socket, database, hotDatabase, … })` from
+`@coffre/vault/node`, with the vault's Postgres URLs. Only the vault's
+logins, `coffre_vault_runtime` and its hot path's, `coffre_vault_hot`, may
+write members and grants; the app uses `coffre_runtime`. See the
 [deploy guide](https://github.com/erwinkn/coffre/blob/main/docs/deploy.md)
-for the logins and both Hyperdrive configs.
+for the logins and the Hyperdrive configs.
 
 Part of [coffre](https://github.com/erwinkn/coffre), a secrets manager you
 deploy as a small project of your own. Its eight `@coffre/*` packages are

package/dist/cloudflare.d.ts

@@ -1,12 +1,273 @@
+import { a as SealThrough, n as Alarm, o as Tick, r as Checkpointer, s as Witness, t as LogMacKey } from "./log-entry-BYWqj3O5.js";
 import { a as KekUnavailableError, c as awsKms, d as Kek, f as VaultConfig, i as KekProvider, l as checkpointMessage, n as AwsKmsOptions, o as SecretContext, p as derivedSigningKey, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-DQ-FKVF3.js";
-import { AdmitInput, ChangePolicyInput, EndReferencesInput, ReferenceInput, RemoveInput, RewrapInput, SetAccessInput, SetSettingsInput, UnwrapInput, Vault, VerifyLogInput, WrapInput } from "@coffre/core/vault";
-import { PostgresDatabase, PostgresDatabase as PostgresDatabase$1, postgres } from "@coffre/db/hyperdrive";
+import { AdmitInput, ChangeBindingsInput, ChangePolicyInput, CutoverInput, EndReferencesInput, IssueTokenInput, NamedUseInput, PrepareInput, ReferenceInput, RemoveInput, RevokeCredentialInput, RewrapInput, Sealing, SetAccessInput, SetSettingsInput, SignInInput, UnwrapInput, UseInput, UseManyInput, Vault, VerifyLogInput, VouchInput, WrapInput } from "@coffre/core/vault";
+import { HyperdrivePool, PostgresDatabase, PostgresDatabase as PostgresDatabase$1, postgres } from "@coffre/db/hyperdrive";
 import { WorkerEntrypoint } from "cloudflare:workers";
+import { LogEntry, LogReader, PairNotes, PairVerifiers, TreeName } from "@coffre/core/merkle";
 export * from "@coffre/core/vault";
+//#region src/reads.d.ts
+/** A use as the pages list it (`log_reads`), every id lower-case. */
+type ReadRow = {
+  number: bigint;
+  at: number;
+  credential: string;
+  /** The use's code: its purpose, keepsSensitive and way in (`USE_PURPOSES`). */
+  purpose: number;
+  principal: string;
+  /** The key the use named, where it is held: a reference's holder. */
+  secret: string;
+  environment: string;
+  project: string;
+  /** The fork it was read in. */
+  place: string | null;
+  /** Through a reference: its source then, and where that is. */
+  source: string | null;
+  sourceEnvironment: string | null;
+  sourceProject: string | null;
+  /** The version read: its key's, or its source's; null where its object names none. */
+  version: string | null;
+  mac: Buffer;
+};
+/**
+ * How far the projector has gone: every use at or below `through` is
+ * projected; `pair`, the signed pair at or below it; `at`, the signed time
+ * of the newest pair whose uses are all projected, which the pages say they
+ * list reads through when it is behind.
+ */
+type ReadsCursor = {
+  through: bigint;
+  pair: bigint;
+  at: number;
+  mac: Buffer | null;
+};
+/** A way in's or key's object as the log holds it, for a projection: a change of it, whole, for its MAC; null for none. */
+type Sealed = LogEntry | null;
+/** What the projector needs of the database (log-store.ts, on both engines). */
+type ReadsStore = Pick<LogReader, 'tiles'> & {
+  readsCursor(): Promise<ReadsCursor>;
+  /** The newest retention change and its leaf index in the changes tree (plan PR 7), for `sealedCut`. */
+  retention(): Promise<{
+    entry: LogEntry;
+    index: number;
+  } | null>;
+  pair(upto: bigint): Promise<{
+    upto: bigint;
+    notes: {
+      changes: string;
+      uses: string;
+    };
+  } | null>;
+  pairs(after: bigint, limit: number): Promise<{
+    upto: bigint;
+    notes: {
+      changes: string;
+      uses: string;
+    };
+  }[]>;
+  newest(): Promise<{
+    upto: bigint;
+    notes: {
+      changes: string;
+      uses: string;
+    };
+  } | null>;
+  entries(after: bigint, upto: bigint, options?: {
+    floor?: number;
+    limit?: number;
+  }): Promise<LogEntry[]>;
+  /**
+   * Each object asked, in order: its first change (`first`), or its newest
+   * numbered below `below`; null for none.
+   */
+  objects(asked: readonly {
+    object: string;
+    below: bigint;
+    first: boolean;
+  }[]): Promise<Sealed[]>;
+  /**
+   * The reads, each once by its number, their days made (`make_reads_day` on Postgres: a log older than the days made
+   * ahead holds uses of others), and the cursor on to `cursor`, never back: one write, and only while the cursor still
+   * stands at `from`, where the chunk started (FromChecked): whether it wrote. A projector another overtook writes
+   * nothing, so never the reads of a day retention has since dropped (review r11).
+   */
+  writeReads(reads: readonly ReadRow[], from: bigint, cursor: ReadsCursor): Promise<boolean>;
+  /**
+   * What the listing holds of a stretch (`checkReads`): its reads numbered in `(after, upto]` at times in `[from, to]`,
+   * each with whether its member's day of it is in `log_read_days` (`dayed`), which their pages read.
+   */
+  listing(stretch: {
+    after: bigint;
+    upto: bigint;
+    from: number;
+    to: number;
+  }): Promise<(ReadRow & {
+    dayed: boolean;
+  })[]>;
+};
+/**
+ * The projector as a host runs it, apart from its checkpointer: on Node,
+ * `kick` after each tick starts a run unless one is going, and returns at
+ * once (checkpointer-node.ts); on Workers, an object of its own runs it on
+ * its own alarm (checkpointer-workers.ts). Either way no tick, seal, change
+ * or use ever waits on it (formal/Reads.tla, SealNeverWaitsOnProjection).
+ * Each run goes some steps over the host's store. A failure is an alarm, said once while it stands; the pages show the
+ * lag meanwhile.
+ */
+declare class Projector {
+  #private;
+  constructor(store: ReadsStore, keys: {
+    verifiers: PairVerifiers;
+    mac: LogMacKey;
+  }, alert: (message: string) => void);
+  /** Start a run unless one is going or the projector is stopped; never waits on it. */
+  kick(): void;
+  /** A run, or the one going: whether it left sealed uses to project. Never throws. */
+  run(): Promise<boolean>;
+  /** The run going, if any, ended: for a host that stops, and for tests. */
+  settled(): Promise<void>;
+  /** No run after this one: a host's stop. */
+  stop(): Promise<void>;
+}
+//#endregion
+//#region src/checkpointer-workers.d.ts
+/** The part of a Durable Object's state the checkpointer uses. */
+type ObjectState = {
+  storage: {
+    get<T>(key: string): Promise<T | undefined>;
+    put<T>(key: string, value: T): Promise<void>;
+    sync(): Promise<void>;
+    delete(keys: string[]): Promise<number>;
+    list<T>(options: {
+      prefix: string;
+      start?: string;
+      end?: string;
+      limit?: number;
+    }): Promise<Map<string, T>>;
+    getAlarm(): Promise<number | null>;
+    setAlarm(scheduledTime: number): Promise<void>;
+  };
+  blockConcurrencyWhile<T>(work: () => Promise<T>): Promise<T>;
+};
+/** A Durable Object binding: `env.CHECKPOINTER`, `env.WITNESS`. */
+type ObjectNamespace = {
+  idFromName(name: string): unknown;
+  get(id: unknown): {
+    fetch(request: Request): Promise<Response>;
+  };
+};
+/**
+ * The change path's seam on Workers (plan PR 4): seal through the checkpointer's object. Its 503, or no answer in
+ * time, is `Unsealed` (T169): the change is committed and in force, and the app says 503, try again.
+ */
+export declare function durableSealThrough(namespace: ObjectNamespace, name?: string): SealThrough;
+/** Starts the object's ticks, once; again is harmless. Throws when it cannot open, its alarm set all the same. */
+export declare function startCheckpointer(namespace: ObjectNamespace, name?: string): Promise<void>;
+/**
+ * Starts the reads' projector (reads.ts, T166): the object of the same class named `name`, which projects from then
+ * on, on its own alarm. Again is harmless.
+ */
+export declare function startProjector(namespace: ObjectNamespace, name?: string): Promise<void>;
+/** The object's head and its last ticks, each with its barrier, write and wall time. */
+export declare function checkpointerStatus(namespace: ObjectNamespace, name?: string): Promise<{
+  open: boolean;
+  failed: string | null;
+  sealing: Sealing;
+  upto: string | null;
+  sizes: Record<'changes' | 'uses', number> | null;
+  ticks: (Omit<Tick, 'upto'> & {
+    upto: string;
+    wallMs: number;
+    at: number;
+  })[];
+}>;
+/** Whether the object seals (`Vault.sealing`, T169): its own view, or, if it does not answer within 2 s, that it does not. */
+export declare function durableSealing(namespace: ObjectNamespace, name?: string): () => Promise<Sealing>;
+/**
+ * The pair the signer remembers, where no database writer reaches: what the
+ * vault's verifier holds its walks to (`VaultOptions.heldOutside`).
+ */
+export declare function durableHeldOutside(namespace: ObjectNamespace, name?: string): () => Promise<PairNotes[]>;
+/** The alarms the object kept since `since` (ms). */
+export declare function checkpointerAlarms(namespace: ObjectNamespace, since?: number, name?: string): Promise<Alarm[]>;
+//#endregion
+//#region src/witness-workers.d.ts
+type WitnessSettings = {
+  /** The witness's own name, its cosignatures' key name: `witness.acme.example`, say. */
+  name: string;
+  /** Its own Ed25519 seed, 32 bytes, base64. */
+  key: string;
+  /** The log's two verifier keys, as the vault's checkpointer signs them. */
+  log: Record<TreeName, string>;
+};
+type Publication = {
+  notes: PairNotes;
+  from: Record<TreeName, number>;
+  proofs: Record<TreeName, string[]>;
+};
+/** The witness's Durable Object class. A new name for it is a new witness, which takes the next pair it is sent as given. */
+declare function witnessObject<Env>(settings: (env: Env) => WitnessSettings | Promise<WitnessSettings>): {
+  new (state: ObjectState, env: Env): {
+    readonly "__#private@#state": ObjectState;
+    readonly "__#private@#env": Env;
+    fetch(request: Request): Promise<Response>;
+    /** Every failure answered from inside the gate, never thrown out of it, which would reset the object. */
+    "__#private@#answer"(p: Publication | null): Promise<Response>;
+    "__#private@#answerOr"(p: Publication | null): Promise<Response>;
+  };
+};
+/** The witness's object as the checkpointer's `Witness`: the pair and each tree's proof from the sizes the object holds. */
+export declare function durableWitness(namespace: ObjectNamespace, options?: {
+  name?: string;
+}): Witness;
+/** The part of an R2 bucket binding the archive uses. */
+type ArchiveBucket = {
+  put(key: string, value: string, options?: {
+    onlyIf?: {
+      etagDoesNotMatch?: string;
+    };
+  }): Promise<unknown | null>;
+  get(key: string): Promise<{
+    text(): Promise<string>;
+  } | null>;
+};
+/**
+ * Each pair it is sent, kept in an R2 bucket under `<prefix><upto, 20 digits>.json`.
+ * A place already archived with the same pair is fine (a pair sent again);
+ * one archived with another is refused, and said.
+ */
+export declare function r2Archive(bucket: ArchiveBucket, options?: {
+  prefix?: string;
+}): Witness;
+//#endregion
 //#region src/cloudflare.d.ts
-/** What the vault Worker's `vault(env => …)` returns. */
+/**
+ * What the vault Worker's `vault(env => …)` returns, for 0.15's log
+ * (docs/design/0.15-plan.md):
+ * - `hotDatabase`: the uses' own Hyperdrive config, whose login is
+ *   `coffre_vault_hot`, and `uses`, how many uses an isolate has in flight
+ *   at most (by default `connections`, the share of that config's pool an
+ *   isolate may hold: T112 measures it), and `uses.batch`, the most keys
+ *   a statement of a request's several makes uses of (100:
+ *   `UseLimits.batch`);
+ * - `checkpointer`: the namespace of the checkpointer's Durable Object,
+ *   `CoffreCheckpointer` (`checkpointer()`, below), bound beside the vault.
+ *   A change answers once that object has sealed it (R51), and the
+ *   verifier holds every check to the pair it remembers;
+ * - `witnesses` (docs/design/audit-tree.md, R40: a deployment opts in).
+ * A configuration without the first two is refused, at the first call.
+ */
 export type WorkersVaultConfig = VaultConfig & {
   database: PostgresDatabase$1;
+  hotDatabase: PostgresDatabase$1;
+  checkpointer: ObjectNamespace;
+  witnesses?: readonly Witness[];
+  uses?: {
+    inFlight?: number;
+    connections?: number;
+    coverMs?: number;
+    names?: number;
+    batch?: number;
+  };
 };
 /**
  * What the app's `VAULT` service binding calls. Each call gets a database of
@@ -16,6 +277,16 @@ export type WorkersVaultConfig = VaultConfig & {
  */
 export declare class VaultEntrypoint extends WorkerEntrypoint implements Vault {
   #private;
+  /**
+   * 0.15's use: one connection of the hot path's config, for its one statement. Closed once the call is done, and by
+   * its deadline at the latest, so that a call answered `late` lets go of Hyperdrive by then, as its place in admission
+   * lapses soon after (use.ts, `HELD_PAST_DEADLINE_MS`; T170).
+   */
+  use(input: UseInput): Promise<import("@coffre/core/vault").UseOutcome>;
+  /** A request's several keys (T167): the same one connection, for its one statement, or two. */
+  useMany(input: UseManyInput): Promise<import("@coffre/core/vault").UseManyOutcome>;
+  /** 0.15's use as the request names it: the same one connection, for its read of ids on a miss and its one use. */
+  useNamed(input: NamedUseInput): Promise<import("@coffre/core/vault").NamedUseOutcome>;
   unwrap(input: UnwrapInput): Promise<import("@coffre/core/vault").Outcome<import("@coffre/core/vault").Unwrapped>>;
   wrap(input: WrapInput): Promise<import("@coffre/core/vault").Outcome<import("@coffre/core/vault").Wrapped>>;
   rewrap(input: RewrapInput): Promise<import("@coffre/core/vault").Outcome<import("@coffre/core/vault").Wrapped>>;
@@ -48,17 +319,83 @@ export declare class VaultEntrypoint extends WorkerEntrypoint implements Vault {
     checkpoint: import("@coffre/core/vault").Checkpoint;
     warning?: string;
   }>>;
+  /** What the vault says of itself; its uses over the hot path's own config (`use`), which `#call`'s vault has not. */
   about(): Promise<{
     checkpointKeys: Record<string, import("@coffre/core/vault").CheckpointKey>;
     owners?: string[];
     rootAdmins: [];
+    log?: "0.15";
+    uses?: true;
+    batchUses?: true;
+    sealing?: true;
+    credentials?: true;
+    issues?: true;
+    binds?: true;
   }>;
   keyChecks(): Promise<import("@coffre/core/vault").KeyChecks>;
   verifyLog(input: VerifyLogInput): Promise<import("@coffre/core/vault").LogVerification>;
+  prepare(input: PrepareInput): Promise<import("@coffre/core/vault").Outcome<import("@coffre/core/vault").Prepared>>;
+  waitSealed(input: {
+    number: string;
+  }): Promise<import("@coffre/core/vault").Outcome<{
+    witnessed: boolean | null;
+  }>>;
+  signIn(input: SignInInput): Promise<import("@coffre/core/vault").SignInOutcome>;
+  revokeCredential(input: RevokeCredentialInput): Promise<import("@coffre/core/vault").RevokeCredentialOutcome>;
+  issueToken(input: IssueTokenInput): Promise<import("@coffre/core/vault").IssueTokenOutcome>;
+  changeBindings(input: ChangeBindingsInput): Promise<import("@coffre/core/vault").ChangeBindingsOutcome>;
+  cutover(input?: CutoverInput): Promise<import("@coffre/core/vault").CutoverOutcome>;
+  verifyTrees(): Promise<import("@coffre/core/vault").TreeVerification>;
+  verifyReads(input: {
+    from: string;
+  }): Promise<import("@coffre/core/vault").ReadsVerification>;
+  vouch(input: VouchInput): Promise<{
+    forged: string[];
+  }>;
+  /** Whether the checkpointer seals (T169), asked of its object for at most 2 s; no database, and no start awaited. */
+  sealing(): Promise<import("@coffre/core/vault").Sealing>;
   /** No HTTP surface: only the app's service binding reaches the vault. */
   fetch(): Response;
 }
 /** The vault Worker's default export, `VaultEntrypoint`, configured from its `env`. */
 export declare function vault<Env>(configure_: (env: Env) => WorkersVaultConfig): typeof VaultEntrypoint;
+/**
+ * 0.15's checkpointer, the Durable Object class a deployment binds beside
+ * the vault, configured by the same `vault(env => …)`: its Hyperdrive, its
+ * signing key, its witnesses. `export const CoffreCheckpointer = checkpointer()`.
+ */
+export declare function checkpointer(): {
+  new (state: ObjectState, env: object): {
+    readonly "__#private@#state": ObjectState;
+    readonly "__#private@#env": object;
+    "__#private@#checkpointer": Checkpointer | null;
+    "__#private@#pool": HyperdrivePool | null;
+    "__#private@#upkeep": (() => Promise<void>) | null;
+    "__#private@#projects": boolean | null;
+    "__#private@#projector": Projector | null;
+    "__#private@#daysFor": string | null;
+    "__#private@#daysTried": number;
+    "__#private@#daysFailed": string | null;
+    "__#private@#upkeeping": boolean;
+    "__#private@#lastSeen"(): {
+      at: number;
+      failures: readonly string[];
+    } | null;
+    readonly "__#private@#ticks": (Tick & {
+      wallMs: number;
+      at: number;
+    })[];
+    "__#private@#open"(): Promise<Checkpointer | null>;
+    "__#private@#failed": string | null;
+    "__#private@#failure"(message: string): Promise<void>;
+    "__#private@#reset"(): Promise<void>;
+    "__#private@#record"(alarm: Alarm): Promise<void>;
+    "__#private@#makeDays"(): Promise<void>;
+    "__#private@#project"(): Promise<void>;
+    "__#private@#isProjector"(): Promise<boolean>;
+    alarm(): Promise<void>;
+    fetch(request: Request): Promise<Response>;
+  };
+};
 //#endregion
-export { type AwsCredentials, type AwsKmsOptions, type Kek, KekBadClaimError, type KekProvider, KekUnavailableError, type PostgresDatabase, type SecretContext, type Vault, type VaultConfig, type WrappedDek, awsKms, checkpointMessage, derivedSigningKey, postgres, verifyCheckpoint };
+export { type AwsCredentials, type AwsKmsOptions, type Kek, KekBadClaimError, type KekProvider, KekUnavailableError, type ObjectNamespace, type PostgresDatabase, type SecretContext, type Vault, type VaultConfig, type WitnessSettings, type WrappedDek, awsKms, checkpointMessage, derivedSigningKey, postgres, verifyCheckpoint, witnessObject as witness };