@wtfalch/foundry 0.60.0 → 0.62.0

package/dist/apps/migrations.js

@@ -0,0 +1,458 @@
+import { createHash } from 'node:crypto';
+import { WORKER_APP_FUNCTION_SIGNATURE, WORKER_APP_TABLE_NAME } from '../entry-rules.js';
+import { WORKER_APP_MIGRATION_TIMEOUT_MS, parseMigrations, runWorkerAppMigrations, verifyMigrationsDigest, } from '../worker-app-migrations.js';
+/** The ledger source the release's migrations are recorded under. */
+export const RELEASE_MIGRATION_SOURCE = 'release';
+const CALL_TIMEOUT_MS = 120_000;
+const RUNTIME_USER = /^[a-z_][a-z0-9_]{0,62}$/;
+const RUNTIME_PASSWORD_MIN = 16;
+const SHA256 = /^[0-9a-f]{64}$/;
+const MIGRATION_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const LIST_MAX = 100;
+const ABORT_WAIT_MS = 5_000;
+const NO_TRANSACTION_MARKER = '-- db:no-transaction';
+/** The comment a runtime role this function made carries: it names the database it was made for. */
+export const runtimeRoleMarker = (database) => `@wtfalch/foundry worker app runtime role for database ${database}`;
+/** The ledger's checksum of a migration's text, as `@wtfalch/db` writes it (CRLF read as LF). */
+export const migrationChecksum = (sql) => createHash('sha256').update(sql.replaceAll('\r\n', '\n')).digest('hex');
+const runsOutsideTransaction = (sql) => sql.split('\n', 1)[0]?.replace(/\r$/, '') === NO_TRANSACTION_MARKER;
+/** A refusal or a failure, already in plain words. */
+class Stop extends Error {
+    step;
+    constructor(step, message) {
+        super(message);
+        this.step = step;
+    }
+}
+/** Thrown by the default runner when the ledger holds another text for an applied id. */
+const CHANGED = 'migration_changed';
+const sqlState = (error) => {
+    const code = error?.code;
+    return typeof code === 'string' && /^[0-9A-Z]{5}$/.test(code) ? code : null;
+};
+function parseAddress(url, which) {
+    const refuse = () => new Stop('check', `The ${which} is not a Postgres address. It looks like postgres://user:password@host:5432/name.`);
+    if (typeof url !== 'string')
+        throw refuse();
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw refuse();
+    }
+    if (parsed.protocol !== 'postgres:' && parsed.protocol !== 'postgresql:')
+        throw refuse();
+    try {
+        const address = {
+            host: parsed.hostname,
+            port: parsed.port || '5432',
+            database: decodeURIComponent(parsed.pathname.replace(/^\//, '')),
+            user: decodeURIComponent(parsed.username),
+            password: decodeURIComponent(parsed.password),
+        };
+        if (!address.host || !address.database || !address.user || !address.password)
+            throw refuse();
+        return address;
+    }
+    catch {
+        throw refuse();
+    }
+}
+function check(input) {
+    const owner = parseAddress(input.ownerUrl, 'owner address of the database');
+    const runtime = parseAddress(input.runtimeUrl, 'app’s database address');
+    if (owner.host !== runtime.host ||
+        owner.port !== runtime.port ||
+        owner.database !== runtime.database) {
+        throw new Stop('check', 'The owner address and the app’s address must name the same database on the same server.');
+    }
+    if (owner.user === runtime.user) {
+        throw new Stop('check', 'The app must not run as the database’s owner. Give the app its own user in its address.');
+    }
+    if (!RUNTIME_USER.test(runtime.user)) {
+        throw new Stop('check', 'The app’s database user must be lower-case letters, digits and _ (at most 63), starting with a letter or _.');
+    }
+    if (runtime.user === 'postgres' || runtime.user.startsWith('pg_')) {
+        throw new Stop('check', 'The app’s database user may not be postgres or start with pg_: those names belong to the server. Give the app its own user in its address.');
+    }
+    if (runtime.password.length < RUNTIME_PASSWORD_MIN) {
+        throw new Stop('check', `The app’s database password must be at least ${RUNTIME_PASSWORD_MIN} characters.`);
+    }
+    const appendOnly = input.appendOnly ?? [];
+    const grants = input.grants ?? [];
+    if (!Array.isArray(appendOnly) || appendOnly.length > LIST_MAX) {
+        throw new Stop('check', `At most ${LIST_MAX} append-only tables.`);
+    }
+    for (const table of appendOnly) {
+        if (typeof table !== 'string' || !WORKER_APP_TABLE_NAME.test(table)) {
+            throw new Stop('check', `${String(table).slice(0, 80)} is not a table name (letters, digits and _, optionally schema.table).`);
+        }
+    }
+    if (!Array.isArray(grants) || grants.length > LIST_MAX) {
+        throw new Stop('check', `At most ${LIST_MAX} granted functions.`);
+    }
+    for (const signature of grants) {
+        if (typeof signature !== 'string' || !WORKER_APP_FUNCTION_SIGNATURE.test(signature)) {
+            throw new Stop('check', `${String(signature).slice(0, 80)} is not a function signature (name(type, ...) or schema.name(type, ...)).`);
+        }
+    }
+    if (input.migrationsSha256 !== undefined && !SHA256.test(input.migrationsSha256)) {
+        throw new Stop('check', 'The migrations checksum in build.json is not a sha256 (64 lower-case hex characters).');
+    }
+    // A checksum names a file: without the file the release's database changes would be skipped.
+    if (input.migrationsJson === null && input.migrationsSha256 !== undefined) {
+        throw new Stop('check', 'The build says it has database changes, but its migrations.json could not be read.');
+    }
+    // The file before any connection: the same pure checks the shared run makes, in words.
+    try {
+        verifyMigrationsDigest(input.migrationsJson, input.migrationsSha256);
+    }
+    catch {
+        throw new Stop('check', input.migrationsSha256
+            ? 'The build’s migrations.json is not the one build.json names (its checksum differs). Publish the release again.'
+            : 'The build has a migrations.json, but its build.json names no checksum for it (database.migrationsSha256). Publish the release again with it.');
+    }
+    let migrations;
+    try {
+        migrations = parseMigrations(input.migrationsJson);
+    }
+    catch (error) {
+        // parseMigrations names the file and an entry index, never SQL.
+        throw new Stop('check', `The build’s ${error.message}.`);
+    }
+    return { owner, runtime, migrations };
+}
+function scrub(text, hidden) {
+    let out = text;
+    for (const value of hidden)
+        if (value.length >= 4)
+            out = out.split(value).join('[hidden]');
+    return out;
+}
+/**
+ * Runs the release's database changes into the company's Postgres and makes the app's role
+ * true. Rerunning is safe: applied migrations are skipped by the ledger.
+ */
+export async function applyWorkerAppMigrations(input, deps = {}) {
+    const hidden = [];
+    const steps = [];
+    const ran = [];
+    try {
+        for (const value of [input.ownerUrl, input.runtimeUrl]) {
+            if (typeof value === 'string')
+                hidden.push(value);
+        }
+    }
+    catch {
+        // An input we cannot read is refused below.
+    }
+    try {
+        const { owner, runtime, migrations } = check(input);
+        hidden.push(owner.password, runtime.password);
+        const outsideTransaction = new Set(migrations.filter((m) => runsOutsideTransaction(m.sql)).map((m) => m.id));
+        const sql = deps.sql ?? postgresMigrationRunner();
+        const ms = deps.timeoutMs ?? CALL_TIMEOUT_MS;
+        const ownerAddress = { url: input.ownerUrl };
+        const appendOnly = input.appendOnly ?? [];
+        const grants = input.grants ?? [];
+        const call = async (label, task, over) => {
+            const step = label.startsWith('apply migration')
+                ? 'migrations'
+                : label.startsWith('ensure')
+                    ? 'role'
+                    : 'database';
+            const id = /'([^']+)'/.exec(label)?.[1] ?? null;
+            let timer;
+            try {
+                const running = task();
+                running.catch(() => { });
+                return await Promise.race([
+                    running,
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new Error('timeout')), over ?? ms);
+                    }),
+                ]);
+            }
+            catch (error) {
+                if (error instanceof Error && error.message === 'timeout') {
+                    // The work may still be running: stop it on the server, so it ends (or commits) now.
+                    let wait;
+                    await Promise.race([
+                        sql.abort().catch(() => { }),
+                        new Promise((resolve) => {
+                            wait = setTimeout(resolve, ABORT_WAIT_MS);
+                        }),
+                    ]);
+                    clearTimeout(wait);
+                }
+                throw failed(step, id, error, id !== null && outsideTransaction.has(id));
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        };
+        // A role someone else made would be handed this app's password and grants.
+        const origin = await call('ensure: read the app’s database user', () => sql.runtimeRoleOrigin(ownerAddress, runtime.user));
+        if (origin === 'other') {
+            throw new Stop('role', `The database already has a user ${runtime.user} that was not made for this app. Give the app another user in its address, or remove that user from the database, then try again.`);
+        }
+        // A change that ran is never edited: the ledger's checksum is the text it ran with.
+        const checksums = await call('read the applied migrations', () => sql.appliedChecksums(ownerAddress));
+        for (const migration of migrations) {
+            const stored = checksums[migration.id];
+            if (stored && stored !== migrationChecksum(migration.sql)) {
+                throw new Stop('migrations', editedMessage(migration.id));
+            }
+        }
+        const result = await runWorkerAppMigrations(sql, ownerAddress, input.migrationsJson, {
+            appendOnly,
+            grants,
+            ...(input.migrationsSha256 ? { migrationsSha256: input.migrationsSha256 } : {}),
+        }, { user: runtime.user, password: runtime.password }, {
+            at: 'database changes',
+            call,
+            migrationTimeoutMs: deps.migrationTimeoutMs ?? WORKER_APP_MIGRATION_TIMEOUT_MS,
+            onApplied: async (done) => {
+                const id = done.at(-1);
+                if (id) {
+                    ran.push(id);
+                    steps.push(`Ran the database change ${id}`);
+                }
+            },
+        }).catch((error) => {
+            if (error instanceof Stop)
+                throw error;
+            // The only check left after `check`: an applied migration moved or left the file.
+            throw new Stop('migrations', 'A database change that already ran is no longer in the same place in migrations.json. Changes are only ever added at the end; restore the file’s earlier order in a new release.');
+        });
+        const held = await call('ensure: check the app’s database user', () => sql.runtimeRolePrivileges(ownerAddress, { user: runtime.user, appendOnly, grants }));
+        proveRole(held, appendOnly, grants);
+        if (result.ran.length === 0)
+            steps.push('The database already had every change of this build');
+        steps.push(`Set up the app’s database user ${runtime.user}`);
+        return {
+            ok: true,
+            applied: result.applied,
+            ran: result.ran,
+            steps: steps.map((s) => scrub(s, hidden)),
+        };
+    }
+    catch (error) {
+        const stop = error instanceof Stop
+            ? error
+            : new Stop('check', 'Something went wrong while changing the database. Try again.');
+        return {
+            ok: false,
+            step: stop.step,
+            message: scrub(stop.message, hidden),
+            ran,
+            steps: steps.map((s) => scrub(s, hidden)),
+        };
+    }
+}
+const named = (id) => (id && MIGRATION_ID.test(id) ? ` ${id}` : '');
+const editedMessage = (id) => `The database change${named(id)} was edited after it ran. A change that ran is never edited: add a new one in a new release.`;
+/** The role as read back must be what build.json asks for; else the `role` step fails, naming what. */
+function proveRole(held, appendOnly, grants) {
+    for (const name of appendOnly) {
+        const table = held.tables.find((t) => t.name === name);
+        if (!table?.exists) {
+            throw new Stop('role', `The append-only table ${name} is not in the database after its changes ran. Write it in build.json (database.appendOnly) as the table is named, then publish the release again.`);
+        }
+        if (table.update || table.delete || table.truncate) {
+            throw new Stop('role', `The app’s database user can still change or delete rows of ${name}, which build.json says only grows. Write the name in build.json as the table is named, and remove any grant on it to PUBLIC or to a role that user belongs to; then try again.`);
+        }
+    }
+    for (const signature of grants) {
+        const fn = held.functions.find((f) => f.signature === signature);
+        if (!fn?.exists) {
+            throw new Stop('role', `The function ${signature} that build.json grants (database.grants) is not in the database after its changes ran.`);
+        }
+        if (!fn.execute) {
+            throw new Stop('role', `The app’s database user could not be allowed to run ${signature}. The owner address must be able to grant it; check it under Database, then try again.`);
+        }
+    }
+}
+function failed(step, id, error, outsideTransaction = false) {
+    const timedOut = error instanceof Error && error.message === 'timeout';
+    const state = sqlState(error);
+    const tail = state ? ` (the database answered ${state})` : '';
+    if (step === 'migrations') {
+        if (error?.code === CHANGED) {
+            return new Stop(step, editedMessage(id));
+        }
+        if (outsideTransaction) {
+            return new Stop(step, `${timedOut
+                ? `The database change${named(id)} did not finish in time, so we asked the database to stop it.`
+                : `The database change${named(id)} failed${tail}.`} It runs outside a transaction (-- db:no-transaction), so part of it may have been kept; the changes before it stay. Check the database before you try again.`);
+        }
+        return new Stop(step, timedOut
+            ? `The database change${named(id)} did not finish in time, so we asked the database to stop it. It may or may not have finished; running this again is safe, a change that finished is not run twice.`
+            : `The database change${named(id)} failed${tail}. Nothing of it was kept and the changes before it stay. Fix it in a new release, then try again.`);
+    }
+    if (step === 'role') {
+        return new Stop(step, timedOut
+            ? 'The database did not answer in time while we set up the app’s database user. It may or may not have finished; running this again is safe.'
+            : `We could not set up the app’s database user${tail}. The owner address must be able to create roles and grant on the tables; check it under Database, then try again.`);
+    }
+    return new Stop(step, timedOut
+        ? 'The database did not answer in time. Check that it takes connections from Boule, then try again.'
+        : `We could not read the database as its owner${tail}. Check the owner address under Database, then try again.`);
+}
+/** The default runner, on `@wtfalch/db` (loaded on first use, so only a caller of it needs the package). */
+export function postgresMigrationRunner() {
+    /** Each connection open now, with the address it was opened on and its server process. */
+    const open = new Map();
+    const runtimeUrlFor = (ownerUrl, user, password) => {
+        const url = new URL(ownerUrl);
+        url.username = encodeURIComponent(user);
+        url.password = encodeURIComponent(password);
+        return url.toString();
+    };
+    /** One connection as the owner for `work`, closed after; `abort` closes it sooner. */
+    const withOwner = async (url, work) => {
+        const { createDatabase } = await import('@wtfalch/db/postgres');
+        const owner = createDatabase({
+            url,
+            max: 1,
+            connectTimeoutMs: 15_000,
+            applicationName: 'foundry-app-migrations',
+        });
+        const entry = { url, pid: null };
+        open.set(owner, entry);
+        try {
+            const [backend] = await owner.database.query('select pg_backend_pid() as pid');
+            entry.pid = backend?.pid ?? null;
+            return await work(owner);
+        }
+        finally {
+            open.delete(owner);
+            await owner.close().catch(() => { });
+        }
+    };
+    const ledger = async (owner) => {
+        const [table] = await owner.database.query(`select to_regclass('_migrations_sources') is not null as present`);
+        if (!table?.present)
+            return [];
+        return owner.database.query('select filename, checksum from _migrations_sources where source = $1 order by applied_at, filename', [RELEASE_MIGRATION_SOURCE]);
+    };
+    return {
+        async appliedMigrationIds({ url }) {
+            return withOwner(url, async (owner) => (await ledger(owner)).map((row) => row.filename));
+        },
+        async appliedChecksums({ url }) {
+            return withOwner(url, async (owner) => Object.fromEntries((await ledger(owner)).map((row) => [row.filename, row.checksum])));
+        },
+        async applyMigration({ url }, migration) {
+            const { runMigrationSources } = await import('@wtfalch/db/migrate');
+            try {
+                // On our own connection, so a timeout can close it (`abort`).
+                await withOwner(url, (owner) => runMigrationSources({
+                    owner,
+                    sources: [
+                        {
+                            name: RELEASE_MIGRATION_SOURCE,
+                            steps: [{ filename: migration.id, sql: migration.sql }],
+                        },
+                    ],
+                    log: () => { },
+                }));
+            }
+            catch (error) {
+                if (/^migrate: checksum mismatch/.test(error instanceof Error ? error.message : '')) {
+                    throw Object.assign(new Error('changed'), { code: CHANGED });
+                }
+                throw error;
+            }
+        },
+        async runtimeRoleOrigin({ url }, user) {
+            return withOwner(url, async (owner) => {
+                const [row] = await owner.database.query(`select shobj_description(oid, 'pg_authid') as comment from pg_roles where rolname = $1`, [user]);
+                if (!row)
+                    return 'absent';
+                const database = decodeURIComponent(new URL(url).pathname.replace(/^\//, ''));
+                return row.comment === runtimeRoleMarker(database) ? 'ours' : 'other';
+            });
+        },
+        async ensureRuntimeRole({ owner, runtime, appendOnly, grants }) {
+            const { ensureRuntimeRole } = await import('@wtfalch/db/runtime-role');
+            // Not abortable: `@wtfalch/db` opens its own connection. Every statement of it is idempotent.
+            await ensureRuntimeRole({
+                ownerUrl: owner.url,
+                runtimeUrl: runtimeUrlFor(owner.url, runtime.user, runtime.password),
+                appendOnly,
+                grants,
+                log: () => { },
+            });
+            await withOwner(owner.url, async (db) => {
+                const database = decodeURIComponent(new URL(owner.url).pathname.replace(/^\//, ''));
+                const [quoted] = await db.database.query('select quote_ident($1::text) as role, quote_literal($2::text) as note', [runtime.user, runtimeRoleMarker(database)]);
+                if (!quoted)
+                    throw new Error('quote failed');
+                await db.database.query(`comment on role ${quoted.role} is ${quoted.note}`);
+            });
+        },
+        async runtimeRolePrivileges({ url }, { user, appendOnly, grants }) {
+            return withOwner(url, async (owner) => {
+                // A right the role holds itself, through PUBLIC, or through a role it belongs to (a
+                // NOINHERIT member can still SET ROLE to it).
+                const holds = (privilege) => `(
+          has_table_privilege($1::name, c.oid, '${privilege}') or exists (
+            select 1 from pg_roles r
+            where r.rolname <> $1::name and pg_has_role($1::name, r.oid, 'MEMBER')
+              and has_table_privilege(r.oid, c.oid, '${privilege}')))`;
+                const tables = [];
+                for (const name of appendOnly) {
+                    const [row] = await owner.database.query(`select c.oid is not null as exists,
+                    coalesce(${holds('UPDATE')}, false) as update,
+                    coalesce(${holds('DELETE')}, false) as delete,
+                    coalesce(${holds('TRUNCATE')}, false) as truncate
+               from (select to_regclass($2::text) as oid) c`, [user, name]);
+                    tables.push({
+                        name,
+                        exists: row?.exists ?? false,
+                        update: row?.update ?? true,
+                        delete: row?.delete ?? true,
+                        truncate: row?.truncate ?? true,
+                    });
+                }
+                const functions = [];
+                for (const signature of grants) {
+                    const [row] = await owner.database.query(`select p.oid is not null as exists,
+                    coalesce(has_function_privilege($1::name, p.oid, 'EXECUTE'), false) as execute
+               from (select to_regprocedure($2::text) as oid) p`, [user, signature]);
+                    functions.push({
+                        signature,
+                        exists: row?.exists ?? false,
+                        execute: row?.execute ?? false,
+                    });
+                }
+                return { tables, functions };
+            });
+        },
+        async abort() {
+            // A closed socket alone does not stop a running statement (the server notices only when it
+            // next writes), and ending the connection under a transaction makes the driver (postgres
+            // 3.4.9) write its ROLLBACK to a null socket, a throw outside any promise. So the running
+            // statement is cancelled, from a connection of its own: the work rejects (57014), the
+            // transaction rolls back on its live connection, and `withOwner` closes it as usual.
+            // A connection whose process is not known yet, or that cannot be reached, is left to finish.
+            const { createDatabase } = await import('@wtfalch/db/postgres');
+            await Promise.all([...open.values()].map(async ({ url, pid }) => {
+                if (pid === null)
+                    return;
+                const killer = createDatabase({ url, max: 1, connectTimeoutMs: 5_000 });
+                try {
+                    await killer.database.query('select pg_cancel_backend($1::int)', [pid]);
+                }
+                catch {
+                    // Left to finish: the message already says it may or may not have.
+                }
+                finally {
+                    await killer.close().catch(() => { });
+                }
+            }));
+        },
+    };
+}

package/dist/audit/connector.d.ts

@@ -0,0 +1,43 @@
+import type { Handle } from '@wtfalch/audit-sealing';
+import type { AppLedger } from './registry.js';
+/** An open connection to one app ledger's database, as the sealing role. */
+export interface LedgerConnection {
+    handle: Handle;
+    close(): Promise<void>;
+}
+/** The ledger cannot be reached now; `why` is plain words and holds no address or credential. */
+export interface LedgerUnavailable {
+    unavailable: string;
+}
+/**
+ * How the sealing service reaches an app ledger. Host-implemented, like the other ports: the host holds the
+ * app database's owner address (the one `applyWorkerAppMigrations` uses) and opens it as a role that may run
+ * `audit_chain_leaves`, `audit_retire_signing_key` and insert into `audit_checkpoints`, `audit_signing_keys` and
+ * `audit_anchors` (`AUDIT_SEALER_GRANTS`). It is never the app's runtime role and never the company's developers'.
+ */
+export interface LedgerConnector {
+    open(ledger: AppLedger): Promise<LedgerConnection | LedgerUnavailable>;
+}
+export declare const isUnavailable: (value: LedgerConnection | LedgerUnavailable) => value is LedgerUnavailable;
+/** What the host's SQL driver needs to connect as one ledger's sealing role. The password is never logged or returned. */
+export interface SealerLogin {
+    ledger: AppLedger;
+    user: string;
+    password: string;
+}
+export interface LedgerConnectorDeps {
+    heldKeys: {
+        resolve(ref: string): Promise<string | null | undefined>;
+    };
+    /** Registers a value so no log, error or result carries it. */
+    secret?: (value: string) => void;
+    /** The host's driver: reaches the app database (over its Access-protected route) as the given role. */
+    connect(login: SealerLogin): Promise<LedgerConnection | LedgerUnavailable>;
+}
+/**
+ * A {@link LedgerConnector} built from the sealing role: it reads the role's name from the ledger (recorded by the
+ * Worker app database apply) and its password from the held keys, and hands both to the host's driver. A ledger
+ * whose role or password is not there yet is unavailable with the reason, and nothing is opened. It never falls
+ * back to another credential: the app's runtime role cannot seal, and the owner is not used to seal.
+ */
+export declare function createLedgerConnector(deps: LedgerConnectorDeps): LedgerConnector;

package/dist/audit/connector.js

@@ -0,0 +1,22 @@
+import { auditSealerRef } from './sealer-role.js';
+export const isUnavailable = (value) => 'unavailable' in value;
+/**
+ * A {@link LedgerConnector} built from the sealing role: it reads the role's name from the ledger (recorded by the
+ * Worker app database apply) and its password from the held keys, and hands both to the host's driver. A ledger
+ * whose role or password is not there yet is unavailable with the reason, and nothing is opened. It never falls
+ * back to another credential: the app's runtime role cannot seal, and the owner is not used to seal.
+ */
+export function createLedgerConnector(deps) {
+    return {
+        async open(ledger) {
+            if (!ledger.sealerRole) {
+                return { unavailable: 'the sealing role has not been made for it yet' };
+            }
+            const password = await deps.heldKeys.resolve(auditSealerRef(ledger.orgId, ledger.entryKey));
+            if (!password)
+                return { unavailable: 'the sealing credential is not held' };
+            deps.secret?.(password);
+            return deps.connect({ ledger, user: ledger.sealerRole, password });
+        },
+    };
+}

package/dist/audit/evidence.d.ts

@@ -0,0 +1,49 @@
+import { BUNDLE_FORMAT, type Checkpoint } from '@wtfalch/audit-sealing';
+import { type LedgerConnector } from './connector.js';
+import { type AppLedger } from './registry.js';
+/**
+ * What Boule's audit screen reads for one app ledger (foundry#929, boule#363). Read only: no method here writes
+ * to a ledger. Entries are not served here: they stay behind the app's own `ledgerReadHandler` route, which
+ * checks the person's grant, and Boule reads them with `@wtfalch/audit/read`'s `fetchMergedLedgerPage`.
+ */
+export interface AnchorView {
+    checkpointHash: string;
+    provider: string;
+    /** The authority's time, `Date#toISOString()`. */
+    anchoredAt: string;
+}
+export interface LedgerStatus {
+    ledger: string;
+    /** The platform signer's public key, for the trusted-keys file a verifier is handed. */
+    signerPublicKey: string;
+    retention: string;
+    checkpointCount: number;
+    latest: Checkpoint | null;
+    anchoredCheckpoints: number;
+}
+export interface EvidenceBundle {
+    format: typeof BUNDLE_FORMAT;
+    /** File name -> text. Written to a folder as is, it is what `audit-verify-bundle` reads. */
+    files: Record<string, string>;
+}
+export type EvidenceResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    why: string;
+};
+export interface AuditEvidence {
+    status(ledger: AppLedger): Promise<EvidenceResult<LedgerStatus>>;
+    checkpoints(ledger: AppLedger): Promise<EvidenceResult<Checkpoint[]>>;
+    anchors(ledger: AppLedger): Promise<EvidenceResult<AnchorView[]>>;
+    /** The offline-verifiable export, whole or `from`..`to` (sequence numbers). */
+    bundle(ledger: AppLedger, range?: {
+        from?: number;
+        to?: number;
+    }): Promise<EvidenceResult<EvidenceBundle>>;
+}
+export declare function createAuditEvidence(deps: {
+    connector: LedgerConnector;
+    signerPublicKey: string;
+}): AuditEvidence;

package/dist/audit/evidence.js

@@ -0,0 +1,56 @@
+import { BUNDLE_FORMAT, auditAnchors, buildBundle, listCheckpoints, } from '@wtfalch/audit-sealing';
+import { isUnavailable } from './connector.js';
+import { describeRetention } from './registry.js';
+async function readAnchors(handle) {
+    const rows = await handle.select().from(auditAnchors);
+    return rows
+        .map((row) => ({
+        checkpointHash: row.checkpointHash,
+        provider: row.provider,
+        anchoredAt: row.anchoredAt.toISOString(),
+    }))
+        .sort((a, b) => a.anchoredAt.localeCompare(b.anchoredAt));
+}
+export function createAuditEvidence(deps) {
+    async function withLedger(ledger, read) {
+        let connection;
+        try {
+            connection = await deps.connector.open(ledger);
+        }
+        catch {
+            return { ok: false, why: 'The log could not be reached. Try again in a minute.' };
+        }
+        if (isUnavailable(connection))
+            return { ok: false, why: connection.unavailable };
+        try {
+            return { ok: true, value: await read(connection.handle) };
+        }
+        catch {
+            return { ok: false, why: 'The log could not be read. Try again in a minute.' };
+        }
+        finally {
+            await connection.close().catch(() => undefined);
+        }
+    }
+    return {
+        status: (ledger) => withLedger(ledger, async (handle) => {
+            const checkpoints = await listCheckpoints(handle);
+            const anchors = await readAnchors(handle);
+            const anchored = new Set(anchors.map((a) => a.checkpointHash));
+            return {
+                ledger: ledger.ledger,
+                signerPublicKey: deps.signerPublicKey,
+                retention: describeRetention(ledger.retention),
+                checkpointCount: checkpoints.length,
+                latest: checkpoints.at(-1) ?? null,
+                anchoredCheckpoints: checkpoints.filter((c) => anchored.has(c.checkpoint_hash)).length,
+            };
+        }),
+        checkpoints: (ledger) => withLedger(ledger, (handle) => listCheckpoints(handle)),
+        anchors: (ledger) => withLedger(ledger, readAnchors),
+        bundle: (ledger, range) => withLedger(ledger, async (handle) => ({
+            format: BUNDLE_FORMAT,
+            files: await buildBundle(handle, { ledger: ledger.ledger, ...range }),
+        })),
+    };
+}

package/dist/audit/index.d.ts

@@ -0,0 +1,9 @@
+export * from './connector.js';
+export * from './evidence.js';
+export * from './registry.js';
+export * from './seal.js';
+export * from './sealer-role.js';
+export * from './signer.js';
+export * from './tick.js';
+export { AUDIT_PACKAGE_VERSION, AUDIT_APPEND_ONLY_TABLES, AUDIT_APP_GRANTS, AUDIT_SEALER_GRANTS, withAuditDatabase, } from '../modules/audit-ledger.js';
+export { auditMigrations } from './migrations.js';

package/dist/audit/index.js

@@ -0,0 +1,9 @@
+export * from './connector.js';
+export * from './evidence.js';
+export * from './registry.js';
+export * from './seal.js';
+export * from './sealer-role.js';
+export * from './signer.js';
+export * from './tick.js';
+export { AUDIT_PACKAGE_VERSION, AUDIT_APPEND_ONLY_TABLES, AUDIT_APP_GRANTS, AUDIT_SEALER_GRANTS, withAuditDatabase, } from '../modules/audit-ledger.js';
+export { auditMigrations } from './migrations.js';

package/dist/audit/migrations.d.ts

@@ -0,0 +1,5 @@
+/** The pinned `@wtfalch/audit` migrations (id and SQL) an app database needs, in order. */
+export declare function auditMigrations(): readonly {
+    id: string;
+    sql: string;
+}[];

package/dist/audit/migrations.js

@@ -0,0 +1,5 @@
+import { migrations } from '@wtfalch/audit-sealing/migration-list';
+/** The pinned `@wtfalch/audit` migrations (id and SQL) an app database needs, in order. */
+export function auditMigrations() {
+    return migrations;
+}