@wtfalch/foundry 0.59.0 → 0.61.0

package/dist/audit/registry.d.ts

@@ -0,0 +1,49 @@
+import type { DeclaredOrg } from '../org.js';
+/**
+ * The registry of app ledgers (foundry#929). An app is registered by declaring `uses.audit`; there is no other
+ * list. Two views of the same fact:
+ *
+ * - {@link declaredAppLedgers}: every ledger the declared org asks for.
+ * - {@link registeredAppLedgers}: the ones the `audit:ledger` step has applied (`plan/entry-audit.ts` records
+ *   `audit_ledger.<entry>`), which is when the app's database has the tables the sealer reads. Only these are
+ *   sealed.
+ *
+ * Retention is a record of the policy, not an action: nothing here or in the sealing service prunes, deletes or
+ * rewrites a ledger (append-only; the audit package has no prune path either).
+ */
+/** The retention a ledger is kept under. */
+export interface LedgerRetention {
+    /** The plan's period in months, or `null` when the plan keeps it for as long as the company exists. */
+    months: number | null;
+    /** Under a legal hold the ledger is kept forever whatever `months` says. */
+    legalHold: boolean;
+}
+export interface AppLedger {
+    orgId: string;
+    orgSlug: string;
+    entryKey: string;
+    /** The ledger's name in every checkpoint it signs. Stable: it is part of what a checkpoint's hash covers. */
+    ledger: string;
+    retention: LedgerRetention;
+    /** The database role the sealing service connects as (`audit/sealer-role.ts`), once the apply recorded it. */
+    sealerRole?: string;
+}
+/** What the host knows about retention. The plan's period is the host's (billing) to say; foundry holds no default. */
+export interface AuditPolicy {
+    /** The plan's period in months for this org, or `null` for no end. */
+    retentionMonths(org: Pick<DeclaredOrg, 'id' | 'slug'>): number | null;
+    /** Org ids under a legal hold. */
+    legalHold?: ReadonlySet<string>;
+}
+/** The held name of a ledger: `<org slug>-<entry key>`. */
+export declare const appLedgerName: (org: Pick<DeclaredOrg, "slug">, entryKey: string) => string;
+/** `audit_ledger.<entry>`: what the registration step recorded (the ledger name), cleared never. */
+export declare const auditLedgerScopeKey: (entryKey: string) => string;
+export declare const AUDIT_LEDGER_PREFIX = "audit_ledger.";
+export declare function retentionOf(org: Pick<DeclaredOrg, 'id' | 'slug'>, policy: AuditPolicy): LedgerRetention;
+/** Plain words on how long a ledger is kept, for Boule to show. */
+export declare function describeRetention(retention: LedgerRetention): string;
+/** Every ledger the declared org asks for with `uses.audit`. */
+export declare function declaredAppLedgers(org: DeclaredOrg, policy: AuditPolicy): AppLedger[];
+/** The declared ledgers whose registration step has applied. An entry that dropped `uses.audit` is no longer sealed. */
+export declare function registeredAppLedgers(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, policy: AuditPolicy): AppLedger[];

package/dist/audit/registry.js

@@ -0,0 +1,44 @@
+import { auditSealerScopeKey } from './sealer-role.js';
+/** The held name of a ledger: `<org slug>-<entry key>`. */
+export const appLedgerName = (org, entryKey) => `${org.slug}-${entryKey}`;
+/** `audit_ledger.<entry>`: what the registration step recorded (the ledger name), cleared never. */
+export const auditLedgerScopeKey = (entryKey) => `audit_ledger.${entryKey}`;
+export const AUDIT_LEDGER_PREFIX = 'audit_ledger.';
+export function retentionOf(org, policy) {
+    const legalHold = policy.legalHold?.has(org.id) === true;
+    return { months: legalHold ? null : policy.retentionMonths(org), legalHold };
+}
+/** Plain words on how long a ledger is kept, for Boule to show. */
+export function describeRetention(retention) {
+    if (retention.legalHold)
+        return 'Kept without an end date while a legal hold is in place.';
+    if (retention.months === null)
+        return 'Kept for as long as your company has the app.';
+    return `Kept for ${retention.months} months, as your plan says.`;
+}
+function ledgerOf(org, entryKey, policy) {
+    return {
+        orgId: org.id,
+        orgSlug: org.slug,
+        entryKey,
+        ledger: appLedgerName(org, entryKey),
+        retention: retentionOf(org, policy),
+    };
+}
+/** Every ledger the declared org asks for with `uses.audit`. */
+export function declaredAppLedgers(org, policy) {
+    if (!org.hosting.enabled)
+        return [];
+    return org.hosting.entries
+        .filter((entry) => entry.uses?.audit === true)
+        .map((entry) => ledgerOf(org, entry.key, policy));
+}
+/** The declared ledgers whose registration step has applied. An entry that dropped `uses.audit` is no longer sealed. */
+export function registeredAppLedgers(org, recordedIds, policy) {
+    return declaredAppLedgers(org, policy)
+        .filter((ledger) => recordedIds[auditLedgerScopeKey(ledger.entryKey)] === ledger.ledger)
+        .map((ledger) => {
+        const sealerRole = recordedIds[auditSealerScopeKey(ledger.entryKey)];
+        return sealerRole ? { ...ledger, sealerRole } : ledger;
+    });
+}

package/dist/audit/seal.d.ts

@@ -0,0 +1,49 @@
+import type { CheckpointSigner } from '@wtfalch/audit-sealing';
+import { type LedgerConnector } from './connector.js';
+import type { AppLedger } from './registry.js';
+/**
+ * The sealing and anchoring tick (foundry#929, audit#56). The host calls {@link sealLedgers} on
+ * {@link AUDIT_SEAL_EVERY_MINUTES}; one call seals every registered app ledger with the platform signer and has
+ * the timestamp authority stamp each new checkpoint. It is idempotent: a ledger with no new rows seals nothing,
+ * and `anchorCheckpoints` anchors only checkpoints the authority has not stamped yet.
+ *
+ * One ledger failing never stops the others. Every ledger gets a result that says what happened and, when
+ * nothing did, why. Nothing here deletes, updates or prunes a row.
+ */
+/** How often the host runs the tick. */
+export declare const AUDIT_SEAL_EVERY_MINUTES = 15;
+/** A timestamp authority (RFC 3161). Host-chosen: foundry names none. */
+export interface TimestampAuthority {
+    tsaUrl: string;
+    /** A name for the authority; one anchor per checkpoint and name. */
+    provider: string;
+}
+export type SealOutcome = 'sealed' | 'unchanged' | 'skipped' | 'failed';
+export interface SealResult {
+    ledger: string;
+    orgId: string;
+    entryKey: string;
+    outcome: SealOutcome;
+    /** The new checkpoint's tree size, when one was sealed. */
+    treeSize?: number;
+    /** How many checkpoints the authority stamped in this tick. */
+    anchored: number;
+    /** Plain words on why a step did not happen. Present whenever `outcome` is not `sealed`, or anchoring did not run. */
+    reason?: string;
+    at: string;
+}
+export interface SealDeps {
+    ledgers: readonly AppLedger[];
+    connector: LedgerConnector;
+    signer: CheckpointSigner;
+    /** Null when the host picked none: the ledger is sealed and not anchored, and each result says so. */
+    authority: TimestampAuthority | null;
+    fetch?: typeof fetch;
+    now?: () => Date;
+    /** Called with each result as it is known (a log line, a status row). A throwing callback is ignored. */
+    onResult?: (result: SealResult) => void;
+}
+/** A failure in words that carry no address, key or credential. */
+export declare function plainFailure(error: unknown): string;
+/** Seals and anchors each ledger in turn. Never throws for one ledger's failure. */
+export declare function sealLedgers(deps: SealDeps): Promise<SealResult[]>;

package/dist/audit/seal.js

@@ -0,0 +1,131 @@
+import { anchorCheckpoints, sealCheckpoint } from '@wtfalch/audit-sealing';
+import { isUnavailable } from './connector.js';
+/**
+ * The sealing and anchoring tick (foundry#929, audit#56). The host calls {@link sealLedgers} on
+ * {@link AUDIT_SEAL_EVERY_MINUTES}; one call seals every registered app ledger with the platform signer and has
+ * the timestamp authority stamp each new checkpoint. It is idempotent: a ledger with no new rows seals nothing,
+ * and `anchorCheckpoints` anchors only checkpoints the authority has not stamped yet.
+ *
+ * One ledger failing never stops the others. Every ledger gets a result that says what happened and, when
+ * nothing did, why. Nothing here deletes, updates or prunes a row.
+ */
+/** How often the host runs the tick. */
+export const AUDIT_SEAL_EVERY_MINUTES = 15;
+const MAX_REASON = 300;
+/** A failure in words that carry no address, key or credential. */
+export function plainFailure(error) {
+    const name = error instanceof Error ? error.name : 'Error';
+    const message = error instanceof Error ? error.message : '';
+    const clean = message
+        .replace(/[a-z][a-z0-9+.-]*:\/\/\S+/gi, '<address>')
+        .replace(/\b[0-9a-f]{32,}\b/gi, '<value>')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, MAX_REASON);
+    return clean === '' ? name : `${name}: ${clean}`;
+}
+/** Seals and anchors each ledger in turn. Never throws for one ledger's failure. */
+export async function sealLedgers(deps) {
+    const now = deps.now ?? (() => new Date());
+    const results = [];
+    for (const ledger of deps.ledgers) {
+        const result = await sealOne(deps, ledger, now);
+        results.push(result);
+        try {
+            deps.onResult?.(result);
+        }
+        catch {
+            // a reporting callback must not stop the tick
+        }
+    }
+    return results;
+}
+async function sealOne(deps, ledger, now) {
+    const base = { ledger: ledger.ledger, orgId: ledger.orgId, entryKey: ledger.entryKey };
+    let connection;
+    try {
+        connection = await deps.connector.open(ledger);
+    }
+    catch (error) {
+        return {
+            ...base,
+            outcome: 'failed',
+            anchored: 0,
+            reason: `could not open the ledger: ${plainFailure(error)}`,
+            at: now().toISOString(),
+        };
+    }
+    if (isUnavailable(connection)) {
+        return {
+            ...base,
+            outcome: 'skipped',
+            anchored: 0,
+            reason: `not sealed, the ledger is not reachable: ${connection.unavailable}`,
+            at: now().toISOString(),
+        };
+    }
+    const notes = [];
+    let outcome = 'unchanged';
+    let treeSize;
+    let anchored = 0;
+    try {
+        try {
+            const checkpoint = await sealCheckpoint(connection.handle, {
+                ledger: ledger.ledger,
+                signer: deps.signer,
+            });
+            if (checkpoint) {
+                outcome = 'sealed';
+                treeSize = checkpoint.tree_size;
+            }
+            else {
+                notes.push('nothing sealed, no entry since the last checkpoint');
+            }
+        }
+        catch (error) {
+            return {
+                ...base,
+                outcome: 'failed',
+                anchored: 0,
+                reason: `sealing failed: ${plainFailure(error)}`,
+                at: now().toISOString(),
+            };
+        }
+        if (deps.authority === null) {
+            notes.push('not anchored, no timestamp authority is configured');
+        }
+        else {
+            try {
+                anchored = await anchorCheckpoints(connection.handle, {
+                    tsaUrl: deps.authority.tsaUrl,
+                    provider: deps.authority.provider,
+                    ...(deps.fetch ? { fetch: deps.fetch } : {}),
+                });
+                if (anchored === 0)
+                    notes.push('nothing anchored, every checkpoint already has a time stamp');
+            }
+            catch (error) {
+                // The checkpoint is sealed and kept; the next tick asks the authority again.
+                notes.push(`anchoring failed, the next tick tries again: ${plainFailure(error)}`);
+                if (outcome === 'unchanged')
+                    outcome = 'failed';
+            }
+        }
+    }
+    finally {
+        try {
+            await connection.close();
+        }
+        catch {
+            // the connection is gone either way
+        }
+    }
+    return {
+        ...base,
+        outcome,
+        ...(treeSize === undefined ? {} : { treeSize }),
+        anchored,
+        ...(notes.length > 0 ? { reason: notes.join('; ') } : {}),
+        at: now().toISOString(),
+    };
+}

package/dist/audit/sealer-role.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The sealing role (foundry#929, audit#56): one database role per app ledger, apart from the app's runtime role.
+ * The runtime role appends events and never writes a checkpoint, a signing key or an anchor; this role writes
+ * those three and never touches the app's own tables. It exists so that the platform can seal a ledger without
+ * holding the app's runtime credential, and so that the app, which holds only the runtime credential, cannot.
+ *
+ * The password is made by the Worker app database apply, held at {@link auditSealerRef} and never recorded,
+ * logged or returned. Only the role name is recorded ({@link auditSealerScopeKey}); it is not a secret.
+ */
+/** The tables the sealing role may read and insert into. It has no UPDATE, DELETE or TRUNCATE on any of them. */
+export declare const AUDIT_SEALER_INSERT_TABLES: readonly string[];
+/** `audit_sealer.<entry>`: the sealing role's name, recorded after the role was made and its password held. */
+export declare const auditSealerScopeKey: (entryKey: string) => string;
+/** `audit_sealer_undelivered.<entry>`: the role name recorded before its password is held (no `:` in the key). */
+export declare const auditSealerUndeliveredScopeKey: (entryKey: string) => string;
+/** The held-key ref of one ledger's sealing password. */
+export declare const auditSealerRef: (orgId: string, entryKey: string) => string;
+/**
+ * The sealing role's name for an app database: `<database>_seal`, beside the runtime role's `<database>_rt`. Cut
+ * to Postgres's 63 bytes with a hash of the full name when the database name is long.
+ */
+export declare function sealerRoleName(database: string): string;
+/** The SQL the host runs as the database owner, after the audit migrations. Idempotent. */
+export interface SealerRoleSql {
+    statements: string[];
+}
+/**
+ * Makes `user` true: it can log in with `password`, is no superuser and bypasses no row security, may read and
+ * insert into the checkpoint, signing-key and anchor tables and run the two sealing functions, and holds nothing
+ * else. The grants are listed here and in `AUDIT_SEALER_GRANTS`; `audit/sealer-role.test.ts` runs a real
+ * checkpoint as this role to prove the list is enough.
+ */
+export declare function sealerRoleSql(user: string, password: string): SealerRoleSql;

package/dist/audit/sealer-role.js

@@ -0,0 +1,56 @@
+import { createHash } from 'node:crypto';
+import { AUDIT_SEALER_GRANTS } from '../modules/audit-ledger.js';
+/**
+ * The sealing role (foundry#929, audit#56): one database role per app ledger, apart from the app's runtime role.
+ * The runtime role appends events and never writes a checkpoint, a signing key or an anchor; this role writes
+ * those three and never touches the app's own tables. It exists so that the platform can seal a ledger without
+ * holding the app's runtime credential, and so that the app, which holds only the runtime credential, cannot.
+ *
+ * The password is made by the Worker app database apply, held at {@link auditSealerRef} and never recorded,
+ * logged or returned. Only the role name is recorded ({@link auditSealerScopeKey}); it is not a secret.
+ */
+/** The tables the sealing role may read and insert into. It has no UPDATE, DELETE or TRUNCATE on any of them. */
+export const AUDIT_SEALER_INSERT_TABLES = [
+    'audit_checkpoints',
+    'audit_signing_keys',
+    'audit_anchors',
+];
+/** `audit_sealer.<entry>`: the sealing role's name, recorded after the role was made and its password held. */
+export const auditSealerScopeKey = (entryKey) => `audit_sealer.${entryKey}`;
+/** `audit_sealer_undelivered.<entry>`: the role name recorded before its password is held (no `:` in the key). */
+export const auditSealerUndeliveredScopeKey = (entryKey) => `audit_sealer_undelivered.${entryKey}`;
+/** The held-key ref of one ledger's sealing password. */
+export const auditSealerRef = (orgId, entryKey) => `foundry:audit-sealer:${orgId}:${entryKey}`;
+/**
+ * The sealing role's name for an app database: `<database>_seal`, beside the runtime role's `<database>_rt`. Cut
+ * to Postgres's 63 bytes with a hash of the full name when the database name is long.
+ */
+export function sealerRoleName(database) {
+    const name = `${database}_seal`;
+    if (name.length <= 63)
+        return name;
+    const hash = createHash('sha256').update(name).digest('hex').slice(0, 10);
+    return `${name.slice(0, 63 - 11)}_${hash}`;
+}
+const ident = (name) => `"${name.replace(/"/g, '""')}"`;
+const literal = (value) => `'${value.replace(/'/g, "''")}'`;
+/**
+ * Makes `user` true: it can log in with `password`, is no superuser and bypasses no row security, may read and
+ * insert into the checkpoint, signing-key and anchor tables and run the two sealing functions, and holds nothing
+ * else. The grants are listed here and in `AUDIT_SEALER_GRANTS`; `audit/sealer-role.test.ts` runs a real
+ * checkpoint as this role to prove the list is enough.
+ */
+export function sealerRoleSql(user, password) {
+    const role = ident(user);
+    const tables = AUDIT_SEALER_INSERT_TABLES.map(ident).join(', ');
+    return {
+        statements: [
+            `do $$ begin if not exists (select from pg_roles where rolname = ${literal(user)}) then create role ${role} login; end if; end $$`,
+            `alter role ${role} with login password ${literal(password)} nosuperuser nocreatedb nocreaterole noinherit nobypassrls`,
+            `grant usage on schema public to ${role}`,
+            `grant select, insert on ${tables} to ${role}`,
+            `revoke update, delete, truncate on ${tables} from ${role}`,
+            ...AUDIT_SEALER_GRANTS.map((fn) => `grant execute on function ${fn} to ${role}`),
+        ],
+    };
+}

package/dist/audit/signer.d.ts

@@ -0,0 +1,40 @@
+import type { CheckpointSigner } from '@wtfalch/audit-sealing';
+/**
+ * The platform's checkpoint signer (foundry#929, audit#56). One Ed25519 key for every app ledger the platform
+ * seals, held by foundry and never by the company's app or its developers: the app's database stores the
+ * checkpoints and the public key, nothing that signs.
+ *
+ * Custody: foundry has no signing use of the `keys` service (it only delivers a custody credential to a Worker
+ * app), so the key follows the way foundry already holds a platform secret it made (`calls-sfu-keys.ts`): made
+ * once, delivered to the host's held keys, read back on every later run. The 32-byte seed is the only secret.
+ * It lives in {@link AuditSignerKeysPort}, in the signer's closure and nowhere else: not a plan, a log, an
+ * error, a recorded id or a result.
+ */
+/** The held-key ref of the platform signer's seed. */
+export declare const AUDIT_SIGNER_REF = "foundry:audit-signer:seed";
+/**
+ * Where the seed is held. `deliverSeed` must be create-if-absent at the store: when two applies both see `null`
+ * and both mint, the first delivery wins and the second `resolveSeed` returns the winner's seed.
+ */
+export interface AuditSignerKeysPort {
+    resolveSeed(): Promise<string | null>;
+    deliverSeed(seedHex: string): Promise<void>;
+}
+/** A fresh seed from the CSPRNG, 64 lower-case hex characters. */
+export declare function mintSignerSeed(): string;
+/** The signer for a seed. The seed is not readable back from it. */
+export declare function signerFromSeed(seedHex: string): CheckpointSigner;
+/**
+ * The platform signer: the held seed, or a new one made and held first. Whether it was made is returned so the
+ * caller can record why a new public key appeared. Refuses a held value that is not a seed, without echoing it.
+ */
+export declare function ensurePlatformSigner(keys: AuditSignerKeysPort, mint?: () => string, 
+/**
+ * The public key already recorded as the platform signer, if any. When one is recorded and the held seed
+ * reads missing or empty, no new seed is ever made: a new key would silently replace the one earlier
+ * checkpoints were sealed under. The run stops and nothing is written.
+ */
+recordedPublicKey?: string): Promise<{
+    signer: CheckpointSigner;
+    created: boolean;
+}>;

package/dist/audit/signer.js

@@ -0,0 +1,78 @@
+import { createPrivateKey, createPublicKey, sign as edSign, generateKeyPairSync, } from 'node:crypto';
+/**
+ * The platform's checkpoint signer (foundry#929, audit#56). One Ed25519 key for every app ledger the platform
+ * seals, held by foundry and never by the company's app or its developers: the app's database stores the
+ * checkpoints and the public key, nothing that signs.
+ *
+ * Custody: foundry has no signing use of the `keys` service (it only delivers a custody credential to a Worker
+ * app), so the key follows the way foundry already holds a platform secret it made (`calls-sfu-keys.ts`): made
+ * once, delivered to the host's held keys, read back on every later run. The 32-byte seed is the only secret.
+ * It lives in {@link AuditSignerKeysPort}, in the signer's closure and nowhere else: not a plan, a log, an
+ * error, a recorded id or a result.
+ */
+/** The held-key ref of the platform signer's seed. */
+export const AUDIT_SIGNER_REF = 'foundry:audit-signer:seed';
+const SEED_HEX = /^[0-9a-f]{64}$/;
+// PKCS#8 wrapper for a raw Ed25519 seed (RFC 8410).
+const PKCS8_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+function privateKeyOf(seedHex) {
+    return createPrivateKey({
+        key: Buffer.concat([PKCS8_PREFIX, Buffer.from(seedHex, 'hex')]),
+        format: 'der',
+        type: 'pkcs8',
+    });
+}
+function publicKeyHexOf(key) {
+    const x = createPublicKey(key).export({ format: 'jwk' }).x;
+    if (typeof x !== 'string')
+        throw new Error('the audit signer key has no public half');
+    return Buffer.from(x, 'base64url').toString('hex');
+}
+/** A fresh seed from the CSPRNG, 64 lower-case hex characters. */
+export function mintSignerSeed() {
+    const { privateKey } = generateKeyPairSync('ed25519');
+    const der = privateKey.export({ format: 'der', type: 'pkcs8' });
+    return der.subarray(PKCS8_PREFIX.length).toString('hex');
+}
+/** The signer for a seed. The seed is not readable back from it. */
+export function signerFromSeed(seedHex) {
+    if (!SEED_HEX.test(seedHex))
+        throw new Error('the audit signer seed is not 32 bytes of hex');
+    const key = privateKeyOf(seedHex);
+    const publicKey = publicKeyHexOf(key);
+    return {
+        publicKey,
+        async sign(message) {
+            return new Uint8Array(edSign(null, message, key));
+        },
+    };
+}
+/**
+ * The platform signer: the held seed, or a new one made and held first. Whether it was made is returned so the
+ * caller can record why a new public key appeared. Refuses a held value that is not a seed, without echoing it.
+ */
+export async function ensurePlatformSigner(keys, mint = mintSignerSeed, 
+/**
+ * The public key already recorded as the platform signer, if any. When one is recorded and the held seed
+ * reads missing or empty, no new seed is ever made: a new key would silently replace the one earlier
+ * checkpoints were sealed under. The run stops and nothing is written.
+ */
+recordedPublicKey) {
+    let seed = await keys.resolveSeed();
+    let created = false;
+    if (seed === null || seed === '') {
+        if (recordedPublicKey) {
+            throw new Error(`the platform audit signing key is missing at ${AUDIT_SIGNER_REF}; restore it, nothing was changed`);
+        }
+        await keys.deliverSeed(mint());
+        seed = await keys.resolveSeed();
+        created = true;
+        if (seed === null || seed === '') {
+            throw new Error(`the audit signer seed was delivered but ${AUDIT_SIGNER_REF} reads back empty`);
+        }
+    }
+    if (!SEED_HEX.test(seed)) {
+        throw new Error(`the held value at ${AUDIT_SIGNER_REF} is not an audit signer seed`);
+    }
+    return { signer: signerFromSeed(seed), created };
+}

package/dist/audit/tick.d.ts

@@ -0,0 +1,36 @@
+import type { DeclaredOrg } from '../org.js';
+import type { LedgerConnector } from './connector.js';
+import { type AuditPolicy } from './registry.js';
+import { type SealResult, type TimestampAuthority } from './seal.js';
+/**
+ * The scheduled sealing run (foundry#929). Foundry has no scheduler: the host calls
+ * `FoundryPlanApply.runAuditSealTick()` every {@link AUDIT_SEAL_EVERY_MINUTES} minutes, the way it calls
+ * `runReleaseTick()` every 10, and that runs this for every declared org. It seals the ledgers the `audit:ledger`
+ * step registered, nothing else, and writes one log line per ledger that says what happened and, when nothing did,
+ * why (a ledger with no new entries, an unreachable database, no timestamp authority).
+ */
+/** What the host gives `FoundryPlanApply` to run the tick. */
+export interface AuditSealingOptions {
+    /** Where the platform signer's seed is held (`foundry:audit-signer:seed`). */
+    heldKeys: {
+        resolve(ref: string): Promise<string | null | undefined>;
+    };
+    /** How a ledger is reached as its sealing role: `createLedgerConnector`. */
+    connector: LedgerConnector;
+    /** The plan's retention period per org and the legal holds (the host's, from billing). */
+    policy: AuditPolicy;
+    /** The RFC 3161 authority, or `null` to seal without anchoring (each result and the log say so). */
+    authority: TimestampAuthority | null;
+    fetch?: typeof fetch;
+    /** One plain line per ledger and per skipped step. Defaults to `console.info`. */
+    log?: (line: string) => void;
+}
+export interface AuditSealTickDeps extends AuditSealingOptions {
+    orgs: readonly DeclaredOrg[];
+    recorded(org: DeclaredOrg): Promise<Readonly<Record<string, string>>>;
+    /** Whether the actor may seal this org's ledgers (the apply permission). */
+    allowed(org: DeclaredOrg): Promise<boolean>;
+    now?: () => Date;
+}
+export declare const NO_AUTHORITY_LINE = "audit sealing: no timestamp authority is configured, so checkpoints are sealed and not anchored";
+export declare function runAuditSealTick(deps: AuditSealTickDeps): Promise<SealResult[]>;

package/dist/audit/tick.js

@@ -0,0 +1,87 @@
+import { AUDIT_SIGNER_PUBLIC_KEY_SCOPE_KEY } from '../plan/entry-audit.js';
+import { registeredAppLedgers } from './registry.js';
+import { sealLedgers, } from './seal.js';
+import { AUDIT_SIGNER_REF, signerFromSeed } from './signer.js';
+export const NO_AUTHORITY_LINE = 'audit sealing: no timestamp authority is configured, so checkpoints are sealed and not anchored';
+const describe = (r) => `audit seal ${r.ledger}: ${r.outcome}${r.reason ? `, ${r.reason}` : ''}`;
+export async function runAuditSealTick(deps) {
+    const log = deps.log ?? ((line) => console.info(line));
+    const now = deps.now ?? (() => new Date());
+    const results = [];
+    const skip = (ledger, reason) => {
+        const result = {
+            ledger: ledger.ledger,
+            orgId: ledger.orgId,
+            entryKey: ledger.entryKey,
+            outcome: 'skipped',
+            anchored: 0,
+            reason,
+            at: now().toISOString(),
+        };
+        results.push(result);
+        log(describe(result));
+    };
+    const due = [];
+    for (const org of deps.orgs) {
+        try {
+            const ledgers = registeredAppLedgers(org, await deps.recorded(org), deps.policy);
+            if (ledgers.length > 0)
+                due.push({ org, ledgers });
+        }
+        catch {
+            log(`audit sealing: ${org.slug} skipped, its records could not be read; the other orgs go on`);
+        }
+    }
+    if (due.length === 0)
+        return results;
+    if (deps.authority === null)
+        log(NO_AUTHORITY_LINE);
+    let signer = null;
+    let noSigner = 'not sealed, the platform signer key is not held';
+    try {
+        const seed = await deps.heldKeys.resolve(AUDIT_SIGNER_REF);
+        if (seed)
+            signer = signerFromSeed(seed);
+    }
+    catch {
+        noSigner = 'not sealed, the platform signer key could not be read';
+    }
+    for (const { org, ledgers } of due) {
+        if (!signer) {
+            for (const ledger of ledgers)
+                skip(ledger, noSigner);
+            continue;
+        }
+        // One org that throws (permission check, record read, a ledger) never stops the orgs after it.
+        try {
+            if (!(await deps.allowed(org))) {
+                for (const ledger of ledgers)
+                    skip(ledger, 'not sealed, the actor may not apply this org');
+                continue;
+            }
+            const recordedKey = (await deps.recorded(org))[AUDIT_SIGNER_PUBLIC_KEY_SCOPE_KEY];
+            if (recordedKey && recordedKey !== signer.publicKey) {
+                for (const ledger of ledgers) {
+                    skip(ledger, 'not sealed, the held signer key is not the one recorded as the platform signer');
+                }
+                continue;
+            }
+            const sealed = await sealLedgers({
+                ledgers,
+                connector: deps.connector,
+                signer,
+                authority: deps.authority,
+                ...(deps.fetch ? { fetch: deps.fetch } : {}),
+                now,
+                onResult: (r) => log(describe(r)),
+            });
+            results.push(...sealed);
+        }
+        catch {
+            for (const ledger of ledgers) {
+                skip(ledger, 'not sealed, a check or read for this org failed; the other orgs go on');
+            }
+        }
+    }
+    return results;
+}

package/dist/catalogue/copy-en.d.ts

@@ -0,0 +1 @@
+export declare const CATALOGUE_EN: Readonly<Record<string, string>>;