@wtfalch/foundry 0.76.0 → 0.77.0

package/dist/app-canary-worker.d.ts

@@ -0,0 +1,35 @@
+/**
+ * foundry#1133: the app-layer canary, the whole Worker. Archon's uptime
+ * Worker probes `GET /` on it (archon#812, service `app-layer`), so a red
+ * check means the layer every company's managed app runs on
+ * (`<label>.companyincluded.app`, edge's Worker routes) is down, not the
+ * canary. It has no bindings, no secrets and no data: `/` answers 200 with an
+ * empty body, anything else 404, and nothing is cached.
+ *
+ * This string is the only source and the only build: the package ships it,
+ * so a host serves the pinned artifact from it ({@link fetchAppCanaryArtifact})
+ * the way Archon serves `archon-uptime-worker.js` from its own image. Nothing
+ * is published at {@link import('./platform.js').appCanaryArtifactUrl}; the
+ * URL only names the pin at the `fetchArtifact(url, sha256)` boundary.
+ */
+export declare const APP_CANARY_WORKER_SOURCE = "export default {\n  fetch(request) {\n    const { pathname } = new URL(request.url);\n    return new Response(null, {\n      status: pathname === '/' ? 200 : 404,\n      headers: { 'cache-control': 'no-store' },\n    });\n  },\n};\n";
+/** Lower-case hex SHA-256 of {@link APP_CANARY_WORKER_SOURCE}'s UTF-8 bytes. */
+export declare const APP_CANARY_WORKER_SHA256: string;
+/**
+ * The pin of the shipped canary: its digest, and a tag made from it, so the
+ * tag changes exactly when the script does. A host declares
+ * `platform.appCanary = { enabled: true, ...appCanaryShippedPin() }`.
+ */
+export declare function appCanaryShippedPin(): {
+    tag: string;
+    sha256: string;
+};
+/** The file name the artifact URL ends in. */
+export declare const APP_CANARY_ARTIFACT_FILE = "app-canary-worker.js";
+/**
+ * A `fetchArtifact` for the canary step: the shipped bytes, no network and no
+ * credential. Refuses any URL that is not a canary artifact URL, and a digest
+ * that is not the shipped one (the pin names another build than this package
+ * holds), in fixed words.
+ */
+export declare function fetchAppCanaryArtifact(url: string, sha256: string): Promise<Uint8Array>;

package/dist/app-canary-worker.js

@@ -0,0 +1,56 @@
+import { createHash } from 'node:crypto';
+/**
+ * foundry#1133: the app-layer canary, the whole Worker. Archon's uptime
+ * Worker probes `GET /` on it (archon#812, service `app-layer`), so a red
+ * check means the layer every company's managed app runs on
+ * (`<label>.companyincluded.app`, edge's Worker routes) is down, not the
+ * canary. It has no bindings, no secrets and no data: `/` answers 200 with an
+ * empty body, anything else 404, and nothing is cached.
+ *
+ * This string is the only source and the only build: the package ships it,
+ * so a host serves the pinned artifact from it ({@link fetchAppCanaryArtifact})
+ * the way Archon serves `archon-uptime-worker.js` from its own image. Nothing
+ * is published at {@link import('./platform.js').appCanaryArtifactUrl}; the
+ * URL only names the pin at the `fetchArtifact(url, sha256)` boundary.
+ */
+export const APP_CANARY_WORKER_SOURCE = `export default {
+  fetch(request) {
+    const { pathname } = new URL(request.url);
+    return new Response(null, {
+      status: pathname === '/' ? 200 : 404,
+      headers: { 'cache-control': 'no-store' },
+    });
+  },
+};
+`;
+/** Lower-case hex SHA-256 of {@link APP_CANARY_WORKER_SOURCE}'s UTF-8 bytes. */
+export const APP_CANARY_WORKER_SHA256 = createHash('sha256')
+    .update(APP_CANARY_WORKER_SOURCE)
+    .digest('hex');
+/**
+ * The pin of the shipped canary: its digest, and a tag made from it, so the
+ * tag changes exactly when the script does. A host declares
+ * `platform.appCanary = { enabled: true, ...appCanaryShippedPin() }`.
+ */
+export function appCanaryShippedPin() {
+    return { tag: `v0-${APP_CANARY_WORKER_SHA256.slice(0, 12)}`, sha256: APP_CANARY_WORKER_SHA256 };
+}
+/** The file name the artifact URL ends in. */
+export const APP_CANARY_ARTIFACT_FILE = 'app-canary-worker.js';
+/** `appCanaryArtifactUrl(tag)` for any release-shaped tag: the only URL {@link fetchAppCanaryArtifact} serves. */
+const APP_CANARY_ARTIFACT_URL = /^https:\/\/github\.com\/wtfalch\/foundry\/releases\/download\/v[0-9A-Za-z][0-9A-Za-z.+_-]*\/app-canary-worker\.js$/;
+/**
+ * A `fetchArtifact` for the canary step: the shipped bytes, no network and no
+ * credential. Refuses any URL that is not a canary artifact URL, and a digest
+ * that is not the shipped one (the pin names another build than this package
+ * holds), in fixed words.
+ */
+export async function fetchAppCanaryArtifact(url, sha256) {
+    if (!APP_CANARY_ARTIFACT_URL.test(url)) {
+        throw new Error('the app canary is served only from its own artifact URL');
+    }
+    if (sha256.toLowerCase() !== APP_CANARY_WORKER_SHA256) {
+        throw new Error("the pinned app canary digest is not the one this foundry ships; pin appCanaryShippedPin()'s values");
+    }
+    return new TextEncoder().encode(APP_CANARY_WORKER_SOURCE);
+}

package/dist/audit/connector.d.ts

@@ -31,12 +31,16 @@ export interface LedgerConnectorDeps {
     };
     /** 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. */
+    /**
+     * The host's driver: reaches the app database (over its Access-protected route) as the given role. For a ledger
+     * a company's Boule registered, `login.ledger.database` says where the database is; the driver connects there.
+     */
     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
+ * Worker app database apply, or from the registration) and its password from the held keys (`ledger.passwordRef`
+ * for a registered ledger), 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.
  */

package/dist/audit/connector.js

@@ -2,7 +2,8 @@ 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
+ * Worker app database apply, or from the registration) and its password from the held keys (`ledger.passwordRef`
+ * for a registered ledger), 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.
  */
@@ -12,7 +13,7 @@ export function createLedgerConnector(deps) {
             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));
+            const password = await deps.heldKeys.resolve(ledger.passwordRef ?? auditSealerRef(ledger.orgId, ledger.entryKey));
             if (!password)
                 return { unavailable: 'the sealing credential is not held' };
             deps.secret?.(password);

package/dist/audit/evidence.d.ts

@@ -26,13 +26,17 @@ export interface EvidenceBundle {
     /** File name -> text. Written to a folder as is, it is what `audit-verify-bundle` reads. */
     files: Record<string, string>;
 }
+/** `refused`: the request itself cannot be answered (a bundle range not on checkpoints), not the ledger being down. */
 export type EvidenceResult<T> = {
     ok: true;
     value: T;
 } | {
     ok: false;
     why: string;
+    refused?: true;
 };
+/** Why a bundle range was refused, in words for Boule to show. */
+export declare const BUNDLE_RANGE_REFUSED = "Pick a range that starts at 1 or just after a checkpoint, and ends on a checkpoint.";
 export interface AuditEvidence {
     status(ledger: AppLedger): Promise<EvidenceResult<LedgerStatus>>;
     checkpoints(ledger: AppLedger): Promise<EvidenceResult<Checkpoint[]>>;

package/dist/audit/evidence.js

@@ -1,6 +1,8 @@
-import { BUNDLE_FORMAT, auditAnchors, buildBundle, listCheckpoints, } from '@wtfalch/audit-sealing';
+import { BUNDLE_FORMAT, BundleRefusal, auditAnchors, buildBundle, listCheckpoints, } from '@wtfalch/audit-sealing';
 import { isUnavailable } from './connector.js';
 import { describeRetention } from './registry.js';
+/** Why a bundle range was refused, in words for Boule to show. */
+export const BUNDLE_RANGE_REFUSED = 'Pick a range that starts at 1 or just after a checkpoint, and ends on a checkpoint.';
 async function readAnchors(handle) {
     const rows = await handle.select().from(auditAnchors);
     return rows
@@ -25,7 +27,17 @@ export function createAuditEvidence(deps) {
         try {
             return { ok: true, value: await read(connection.handle) };
         }
-        catch {
+        catch (error) {
+            if (error instanceof BundleRefusal) {
+                const nothing = /no checkpoint/.test(error.message);
+                return {
+                    ok: false,
+                    why: nothing
+                        ? 'Nothing in this log is sealed yet, so there is nothing to export.'
+                        : BUNDLE_RANGE_REFUSED,
+                    refused: true,
+                };
+            }
             return { ok: false, why: 'The log could not be read. Try again in a minute.' };
         }
         finally {

package/dist/audit/host-store.d.ts

@@ -0,0 +1,58 @@
+import type { DeclaredOrg, OrgId } from '../org.js';
+import type { FoundryStoreDb } from '../store/postgres.js';
+import { type AppLedger, type AuditPolicy, type LedgerAddress } from './registry.js';
+import type { SealOutcome, SealResult } from './seal.js';
+/**
+ * What the audit host keeps (foundry#1110, migration 0072): each company's key (its sha256 only), the ledgers a
+ * company's Boule registered, and every seal tick's result for the last {@link SEAL_RESULTS_KEPT_HOURS} hours.
+ * No password is kept here: a registration names the held-key ref its password was put at.
+ */
+/** How long a seal result is kept, and so how far back `status` shows the seals. */
+export declare const SEAL_RESULTS_KEPT_HOURS = 12;
+/** A company's audit host key: `fah_` and 64 lowercase hex characters. */
+export declare const AUDIT_HOST_KEY_PATTERN: RegExp;
+export interface LedgerRegistration {
+    orgId: OrgId;
+    entryKey: string;
+    copy: 'live';
+    database: LedgerAddress;
+    /** The sealing role the ledger is opened as. */
+    user: string;
+    /** The held-key ref the sealing role's password was put at ({@link auditLedgerPasswordRef}). */
+    passwordRef: string;
+}
+/** One kept seal result, as `status` shows it. */
+export interface SealRecord {
+    at: string;
+    outcome: SealOutcome;
+    /** The new checkpoint's tree size, when one was sealed. */
+    treeSize?: number;
+    anchored: number;
+    erasures: number;
+    /** Plain words on why a step did not happen (`SealResult.reason`). */
+    reason?: string;
+}
+export interface AuditHostStore {
+    /** The company a key belongs to, or `null`. A key of the wrong shape is `null` without a read. */
+    companyOfKey(key: string): Promise<OrgId | null>;
+    /** Makes the company a new key and returns it, once; the company's previous key stops working. */
+    mintKey(orgId: OrgId): Promise<string>;
+    /** Keeps a registration, replacing the company's previous one for the app. */
+    putRegistration(registration: LedgerRegistration): Promise<'created' | 'replaced'>;
+    registrations(orgId: OrgId): Promise<LedgerRegistration[]>;
+    /** Keeps a tick's results and drops the ones older than {@link SEAL_RESULTS_KEPT_HOURS}. */
+    recordSeals(results: readonly SealResult[], now?: Date): Promise<void>;
+    /** The kept results of one ledger, newest first. */
+    seals(orgId: OrgId, entryKey: string, now?: Date): Promise<SealRecord[]>;
+}
+/** The held-key ref of a registered ledger's sealing password (apart from foundry's own `auditSealerRef`). */
+export declare const auditLedgerPasswordRef: (orgId: OrgId, entryKey: string) => string;
+export declare function createPostgresAuditHostStore(db: FoundryStoreDb): AuditHostStore;
+/** A registration as the ledger it seals: `<org slug>-<app>`, opened as its own role at its own address. */
+export declare function registeredLedgerOf(org: Pick<DeclaredOrg, 'id' | 'slug'>, registration: LedgerRegistration, policy: AuditPolicy): AppLedger;
+/**
+ * Every ledger a company has: the ones its own plan registered (`registeredAppLedgers`), then the ones its
+ * Boule registered at the audit host. An app key both name is the plan's: a registration never takes a ledger
+ * the plan seals.
+ */
+export declare function companyAuditLedgers(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, policy: AuditPolicy, store?: Pick<AuditHostStore, 'registrations'>): Promise<AppLedger[]>;

package/dist/audit/host-store.js

@@ -0,0 +1,147 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { and, desc, eq, gte, lt, sql } from 'drizzle-orm';
+import { foundryAuditHostKeys, foundryAuditLedgerRegistrations, foundryAuditSealResults, } from '../store/schema.js';
+import { appLedgerName, registeredAppLedgers, retentionOf, } from './registry.js';
+/**
+ * What the audit host keeps (foundry#1110, migration 0072): each company's key (its sha256 only), the ledgers a
+ * company's Boule registered, and every seal tick's result for the last {@link SEAL_RESULTS_KEPT_HOURS} hours.
+ * No password is kept here: a registration names the held-key ref its password was put at.
+ */
+/** How long a seal result is kept, and so how far back `status` shows the seals. */
+export const SEAL_RESULTS_KEPT_HOURS = 12;
+/** A company's audit host key: `fah_` and 64 lowercase hex characters. */
+export const AUDIT_HOST_KEY_PATTERN = /^fah_[0-9a-f]{64}$/;
+/** The held-key ref of a registered ledger's sealing password (apart from foundry's own `auditSealerRef`). */
+export const auditLedgerPasswordRef = (orgId, entryKey) => `foundry:audit-ledger:${orgId}:${entryKey}`;
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+const keptSince = (now) => new Date(now.getTime() - SEAL_RESULTS_KEPT_HOURS * 3600_000);
+const MAX_REASON = 1000;
+const OUTCOMES = ['sealed', 'unchanged', 'skipped', 'failed'];
+export function createPostgresAuditHostStore(db) {
+    return {
+        async companyOfKey(key) {
+            if (!AUDIT_HOST_KEY_PATTERN.test(key))
+                return null;
+            const [row] = await db
+                .select({ orgId: foundryAuditHostKeys.orgId })
+                .from(foundryAuditHostKeys)
+                .where(eq(foundryAuditHostKeys.keySha256, sha256(key)))
+                .limit(1);
+            return row?.orgId ?? null;
+        },
+        async mintKey(orgId) {
+            const key = `fah_${randomBytes(32).toString('hex')}`;
+            await db
+                .insert(foundryAuditHostKeys)
+                .values({ orgId, keySha256: sha256(key) })
+                .onConflictDoUpdate({
+                target: foundryAuditHostKeys.orgId,
+                set: { keySha256: sha256(key), createdAt: sql `now()` },
+            });
+            return key;
+        },
+        async putRegistration(r) {
+            const values = {
+                copy: r.copy,
+                dbHost: r.database.host,
+                dbPort: r.database.port,
+                dbName: r.database.database,
+                dbUser: r.user,
+                sslmode: r.database.sslmode ?? null,
+                passwordRef: r.passwordRef,
+            };
+            const [row] = await db
+                .insert(foundryAuditLedgerRegistrations)
+                .values({ orgId: r.orgId, entryKey: r.entryKey, ...values })
+                .onConflictDoUpdate({
+                target: [foundryAuditLedgerRegistrations.orgId, foundryAuditLedgerRegistrations.entryKey],
+                set: { ...values, updatedAt: sql `now()` },
+            })
+                .returning({ created: sql `(xmax = 0)` });
+            return row?.created ? 'created' : 'replaced';
+        },
+        async registrations(orgId) {
+            const rows = await db
+                .select()
+                .from(foundryAuditLedgerRegistrations)
+                .where(eq(foundryAuditLedgerRegistrations.orgId, orgId))
+                .orderBy(foundryAuditLedgerRegistrations.entryKey);
+            return rows.map((row) => ({
+                orgId: row.orgId,
+                entryKey: row.entryKey,
+                copy: 'live',
+                database: {
+                    host: row.dbHost,
+                    port: row.dbPort,
+                    database: row.dbName,
+                    ...(row.sslmode ? { sslmode: row.sslmode } : {}),
+                },
+                user: row.dbUser,
+                passwordRef: row.passwordRef,
+            }));
+        },
+        async recordSeals(results, now = new Date()) {
+            if (results.length > 0) {
+                await db.insert(foundryAuditSealResults).values(results.map((r) => ({
+                    orgId: r.orgId,
+                    entryKey: r.entryKey,
+                    ledger: r.ledger,
+                    outcome: r.outcome,
+                    treeSize: r.treeSize ?? null,
+                    anchored: r.anchored,
+                    erasures: r.erasures,
+                    reason: r.reason ? r.reason.slice(0, MAX_REASON) : null,
+                    at: new Date(r.at),
+                })));
+            }
+            await db
+                .delete(foundryAuditSealResults)
+                .where(lt(foundryAuditSealResults.at, keptSince(now)));
+        },
+        async seals(orgId, entryKey, now = new Date()) {
+            const rows = await db
+                .select()
+                .from(foundryAuditSealResults)
+                .where(and(eq(foundryAuditSealResults.orgId, orgId), eq(foundryAuditSealResults.entryKey, entryKey), gte(foundryAuditSealResults.at, keptSince(now))))
+                .orderBy(desc(foundryAuditSealResults.at), desc(foundryAuditSealResults.id));
+            return rows.map((row) => ({
+                at: row.at.toISOString(),
+                outcome: OUTCOMES.includes(row.outcome)
+                    ? row.outcome
+                    : 'failed',
+                ...(row.treeSize === null ? {} : { treeSize: row.treeSize }),
+                anchored: row.anchored,
+                erasures: row.erasures,
+                ...(row.reason ? { reason: row.reason } : {}),
+            }));
+        },
+    };
+}
+/** A registration as the ledger it seals: `<org slug>-<app>`, opened as its own role at its own address. */
+export function registeredLedgerOf(org, registration, policy) {
+    return {
+        orgId: org.id,
+        orgSlug: org.slug,
+        entryKey: registration.entryKey,
+        ledger: appLedgerName(org, registration.entryKey),
+        retention: retentionOf(org, policy),
+        sealerRole: registration.user,
+        database: registration.database,
+        passwordRef: registration.passwordRef,
+    };
+}
+/**
+ * Every ledger a company has: the ones its own plan registered (`registeredAppLedgers`), then the ones its
+ * Boule registered at the audit host. An app key both name is the plan's: a registration never takes a ledger
+ * the plan seals.
+ */
+export async function companyAuditLedgers(org, recordedIds, policy, store) {
+    const own = registeredAppLedgers(org, recordedIds, policy);
+    if (!store)
+        return own;
+    const taken = new Set(own.map((ledger) => ledger.entryKey));
+    const registered = (await store.registrations(org.id))
+        .filter((r) => !taken.has(r.entryKey))
+        .map((r) => registeredLedgerOf(org, r, policy));
+    return [...own, ...registered];
+}

package/dist/audit/host.d.ts

@@ -0,0 +1,53 @@
+import type { DeclaredOrgStore } from '../store.js';
+import type { LedgerConnector } from './connector.js';
+import { type AuditHostStore } from './host-store.js';
+import { type AuditPolicy } from './registry.js';
+/**
+ * The audit host (foundry#1110): `@wtfalch/foundry/audit` served over HTTP, for a host (Archon) to mount at the
+ * address Boule calls `AUDIT_HOST_URL`. It answers exactly the routes Boule reads (`src/lib/apps/audit/host.ts`,
+ * the shapes its `fakeAuditHost` serves) and the registration Boule's managed install makes (boule#656):
+ *
+ *   GET /v1/audit/ledgers                       200 { ledgers: [{ app, ledger, retention, retentionMonths, legalHold }] }
+ *   GET /v1/audit/ledgers/:app/status           200 LedgerStatus + { seals: SealRecord[] } (the last 12 hours, newest first)
+ *   GET /v1/audit/ledgers/:app/checkpoints      200 { checkpoints: Checkpoint[] }   oldest first
+ *   GET /v1/audit/ledgers/:app/anchors          200 { anchors: AnchorView[] }       oldest first
+ *   GET /v1/audit/ledgers/:app/bundle?from&to   200 { format, files }   both optional whole numbers >= 1
+ *   PUT /v1/audit/ledgers/:app                  { copy: 'live', database: { host, port, database, user, password, sslmode? } }
+ *                                               201 (new) or 200 (replaced) { ledger }
+ *
+ * Every answer is JSON with `Cache-Control: no-store`. `Authorization: Bearer <key>` is a company's key
+ * ({@link AuditHostStore.mintKey}); the company comes from the key, never from a parameter, and every read and the
+ * registration see only that company's ledgers. An `:app` with no ledger for the company is 404, never another
+ * company's. Errors are `{ error: { code, message } }` with edge's codes: 400 `invalid_request`, 401
+ * `unauthorized`, 403 `forbidden`, 404 `not_found`, 405 `method_not_allowed`, 409 `conflict`, 413
+ * `invalid_request` (a body over 16 KB), 503 `unavailable` (foundry's `{ ok: false, why }`, `why` as the message).
+ *
+ * The registration's password is put in the host's held keys at {@link auditLedgerPasswordRef} and registered
+ * with `secret`; it is never logged, stored in a table, put in an error or answered. Nothing a request carries
+ * reaches a log line: a line names the route, the company's slug and the app at most.
+ */
+export interface AuditHostOptions {
+    store: AuditHostStore;
+    /** The declared orgs and their applied ids (foundry's `DeclaredOrgStore`). */
+    orgs: Pick<DeclaredOrgStore, 'get' | 'getAppliedState'>;
+    /** The host's retention policy, the same one the seal tick gets. */
+    policy: AuditPolicy;
+    /** Opens a ledger as its sealing role: `createLedgerConnector`, the same one the seal tick gets. */
+    connector: LedgerConnector;
+    /** The platform signer's seed is read from it (`AUDIT_SIGNER_REF`); a registration's password is put in it. */
+    heldKeys: {
+        resolve(ref: string): Promise<string | null | undefined>;
+        put(ref: string, value: string): Promise<void>;
+    };
+    /** Registers a value so no log, error or result carries it. */
+    secret?: (value: string) => void;
+    /** The path the host mounts the handler at, e.g. `/api/audit`. Requests outside it are 404. */
+    basePath?: string;
+    now?: () => Date;
+    /** One plain line per refused or failed request. Defaults to `console.info`. */
+    log?: (line: string) => void;
+}
+export declare const AUDIT_HOST_MAX_LEDGERS = 500;
+export declare const AUDIT_HOST_MAX_BUNDLE_BYTES = 10000000;
+/** The handler a host mounts: a web `Request` in, a `Response` out (a Next.js route handler, a Worker, `node:http` through an adapter). */
+export declare function createAuditHostHandler(options: AuditHostOptions): (request: Request) => Promise<Response>;