@jwilleke/ngdpbase-types 5.41.0 → 5.42.0

package/lib/src/providers/FileSystemMediaProvider.d.ts

@@ -37,6 +37,12 @@ export interface FileSystemMediaProviderConfig {
     readonly: boolean;
     /** Set of file extensions (lowercase, no dot) to index */
     extensions: Set<string>;
+    /**
+     * Private storage the scanner never walks under or keeps in the index (#2195):
+     * the roots `privateStorageRoots` lists. MediaManager already refuses a folder
+     * that overlaps them; this holds even if one gets past it.
+     */
+    excludedRoots?: string[];
 }
 /** Default supported media file extensions — used when no config override is provided */
 export declare const DEFAULT_MEDIA_EXTENSIONS: string[];
@@ -54,6 +60,8 @@ declare class FileSystemMediaProvider extends BaseMediaProvider {
     private readonly config;
     /** In-memory index: id → MediaIndexEntry */
     private index;
+    /** `config.excludedRoots` as real paths, resolved once (#2195). */
+    private readonly excludedReal;
     /** Single ExifTool worker process reused across all reads */
     private readonly exiftoolInstance;
     constructor(config: FileSystemMediaProviderConfig);
@@ -62,6 +70,17 @@ declare class FileSystemMediaProvider extends BaseMediaProvider {
      * (before the first background scan).
      */
     initialize(): Promise<void>;
+    /** The private storage root `p` is under, or undefined (#2195). */
+    private excludedRootOf;
+    /** Whether `p` is under private storage the scanner must not touch (#2195). */
+    private isExcluded;
+    /**
+     * Drop index entries under private storage (#2195): a site that had a media
+     * folder overlapping it before the check existed has those files indexed.
+     */
+    private dropExcludedEntries;
+    /** Delete every cached thumbnail (`{id}-*.webp`) of `ids`: they are copies of the files. */
+    private removeThumbnails;
     /**
      * Release the ExifTool worker process.
      */

package/lib/src/providers/NullAuditProvider.d.ts

@@ -0,0 +1,82 @@
+import BaseAuditProvider, { WikiEngine, AuditFilters, AuditSearchResults, AuditStats } from './BaseAuditProvider.js';
+import type { AuditReport } from './BaseAuditProvider.js';
+/**
+ * NullAuditProvider - No-op audit provider
+ *
+ * Used when auditing is disabled or for testing.
+ * All audit operations are no-ops that return immediately.
+ */
+declare class NullAuditProvider extends BaseAuditProvider {
+    /**
+     * Not chained (#1119): this provider stores nothing, so there is nothing to
+     * chain. A legitimate configuration rather than a hole — provided the
+     * instance cannot then claim tamper evidence, which is what
+     * getProviderInfo().guarantees reports.
+     */
+    protected chainEnabled(): boolean;
+    /** Nothing is stored, so nothing is guaranteed (#1119). */
+    getGuarantees(): AuditReport;
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the null audit provider (no-op)
+     * @returns {Promise<void>}
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get provider information
+     * @returns {Object} Provider metadata
+     */
+    getProviderInfo(): {
+        name: string;
+        version: string;
+        description: string;
+        features: string[];
+    };
+    /**
+     * Log an audit event (no-op)
+     * @param {AuditEvent} _auditEvent - Audit event data
+     * @returns {Promise<string>} Dummy event ID
+     */
+    writeEvent(_record: Record<string, unknown>): Promise<string>;
+    /**
+     * Search audit logs (returns empty results)
+     * @param {AuditFilters} _filters - Search filters
+     * @param {Record<string, number>} options - Search options
+     * @returns {Promise<AuditSearchResults>} Empty search results
+     */
+    searchAuditLogs(_filters?: AuditFilters, options?: Record<string, number>): Promise<AuditSearchResults>;
+    /**
+     * Get audit statistics (returns zeros)
+     * @param {AuditFilters} _filters - Optional filters
+     * @returns {Promise<AuditStats>} Empty statistics
+     */
+    getAuditStats(_filters?: AuditFilters): Promise<AuditStats>;
+    /**
+     * Export audit logs (returns empty data)
+     * @param {AuditFilters} _filters - Export filters
+     * @param {string} format - Export format ('json', 'csv')
+     * @returns {Promise<string>} Empty export data
+     */
+    exportAuditLogs(_filters?: AuditFilters, format?: 'json' | 'csv'): Promise<string>;
+    /**
+     * Flush pending audit events (no-op)
+     * @returns {Promise<void>}
+     */
+    flush(): Promise<void>;
+    /**
+     * Clean up old audit logs (no-op)
+     * @returns {Promise<void>}
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Check if the audit provider is healthy (always true)
+     * @returns {Promise<boolean>} Always true
+     */
+    isHealthy(): Promise<boolean>;
+    /**
+     * Close/cleanup the audit provider (no-op)
+     * @returns {Promise<void>}
+     */
+    close(): Promise<void>;
+}
+export default NullAuditProvider;

package/lib/src/providers/TotpAuthProvider.d.ts

@@ -0,0 +1,55 @@
+import type { AuthProvider, AuthResult, AuthVerifyCredentials, FactorDescription } from './BaseAuthProvider.js';
+import type { CredentialRecord } from './BaseCredentialsProvider.js';
+/** Steps either side of now that are accepted. */
+export declare const TOTP_DRIFT_STEPS = 1;
+/** The store access AuthManager grants: an account's TOTP rows, and recording a use. */
+export interface TotpStoreAccess {
+    rows(username: string): CredentialRecord[];
+    used(id: string, at: string, secret: string): Promise<void>;
+}
+/** A new seed, offered while enrolling and kept by the caller until it is confirmed. */
+export interface TotpEnrolment {
+    /** Base32, for typing into the app by hand. */
+    seed: string;
+    /** The `otpauth://` URI the QR code carries. */
+    uri: string;
+}
+/**
+ * The time step `code` belongs to within the drift window, or null. Pure; the
+ * caller decides about replay.
+ */
+export declare function matchingStep(seed: string, code: string, now: number): number | null;
+export declare class TotpAuthProvider implements AuthProvider {
+    private readonly credentialsKey;
+    private readonly issuer;
+    private readonly store;
+    private readonly now;
+    readonly id = "totp";
+    readonly displayName = "Authenticator app";
+    readonly factor: FactorDescription;
+    private readonly serial;
+    /**
+     * @param credentialsKey `NGDPBASE_CREDENTIALS_KEY`, from which the seed key is derived
+     * @param issuer         shown in the authenticator app beside the account
+     */
+    constructor(credentialsKey: string, issuer: string, store: TotpStoreAccess, now?: () => number);
+    /** A fresh 160-bit seed and its URI for `username`. Nothing is stored. */
+    newEnrolment(username: string): TotpEnrolment;
+    /**
+     * Seal a seed that is offered but not yet confirmed, so it can wait in the
+     * session without being readable there or in a session log (#421). Its own
+     * shape, so it never opens as a stored secret.
+     */
+    sealPending(username: string, seed: string): string;
+    /** Open what `sealPending` made for `username`; null when it is not that. */
+    openPending(username: string, sealed: unknown): string | null;
+    /**
+     * Check the code that confirms an enrolment and seal the seed for the store.
+     * The confirming code's step is recorded, so it cannot then sign anyone in.
+     * Null when the seed is malformed or the code does not match.
+     */
+    confirmEnrolment(username: string, seed: string, code: string): string | null;
+    /** Verify `credentials.code` for `credentials.username`. A failure gives no reason. */
+    verify(credentials: AuthVerifyCredentials): Promise<AuthResult | null>;
+    private open;
+}

package/lib/src/providers/TotpAuthProvider.js

@@ -0,0 +1,145 @@
+/**
+ * TOTP — an authenticator app's six-digit code (#421), on `otpauth` (decided
+ * on #1523, 2026-10-31).
+ *
+ * - A second factor only (`primary: false`): something you have, `amr`
+ *   `otp`, AAL1 on its own. After a password the sign-in covers two factor
+ *   types and AuthManager's `assess()` lifts it to AAL2. Not phishing-resistant.
+ * - The seed lives in the credentials store (#1524), kind `totp`, AES-GCM
+ *   encrypted under a subkey of `NGDPBASE_CREDENTIALS_KEY`
+ *   (`utils/totpSeedCipher`). The row's sealed secret also holds the last time
+ *   step used, so a code cannot be used twice in its window.
+ * - A code is accepted for the current 30-second step and one step either
+ *   side (RFC 6238 §5.2 drift), never for a step at or before the last one used.
+ * - Verification for one account runs one at a time, so two requests carrying
+ *   the same code cannot both pass before the step is recorded.
+ */
+import { Secret, TOTP, URI } from 'otpauth';
+import { openTotpSecret, sealTotpSecret } from '../utils/totpSeedCipher.js';
+import { KeyedSerial } from '../utils/keyedSerial.js';
+/** RFC 6238 defaults, which every authenticator app supports. */
+const PERIOD = 30;
+const DIGITS = 6;
+/** Steps either side of now that are accepted. */
+export const TOTP_DRIFT_STEPS = 1;
+function totpFor(seed, issuer = '', label = '') {
+    return new TOTP({ issuer, label, algorithm: 'SHA1', digits: DIGITS, period: PERIOD, secret: Secret.fromBase32(seed) });
+}
+function isCode(code) {
+    return typeof code === 'string' && /^\d{6}$/.test(code);
+}
+function currentStep(now) {
+    return Math.floor(now / 1000 / PERIOD);
+}
+/**
+ * The time step `code` belongs to within the drift window, or null. Pure; the
+ * caller decides about replay.
+ */
+export function matchingStep(seed, code, now) {
+    if (!isCode(code))
+        return null;
+    const delta = totpFor(seed).validate({ token: code, timestamp: now, window: TOTP_DRIFT_STEPS });
+    return delta === null ? null : currentStep(now) + delta;
+}
+export class TotpAuthProvider {
+    credentialsKey;
+    issuer;
+    store;
+    now;
+    id = 'totp';
+    displayName = 'Authenticator app';
+    factor = { amr: ['otp'], aal: 1, primary: false };
+    serial = new KeyedSerial();
+    /**
+     * @param credentialsKey `NGDPBASE_CREDENTIALS_KEY`, from which the seed key is derived
+     * @param issuer         shown in the authenticator app beside the account
+     */
+    constructor(credentialsKey, issuer, store, now = Date.now) {
+        this.credentialsKey = credentialsKey;
+        this.issuer = issuer;
+        this.store = store;
+        this.now = now;
+        if (!credentialsKey)
+            throw new Error('TOTP needs NGDPBASE_CREDENTIALS_KEY (#421)');
+    }
+    /** A fresh 160-bit seed and its URI for `username`. Nothing is stored. */
+    newEnrolment(username) {
+        const seed = new Secret({ size: 20 }).base32;
+        return { seed, uri: URI.stringify(totpFor(seed, this.issuer, username)) };
+    }
+    /**
+     * Seal a seed that is offered but not yet confirmed, so it can wait in the
+     * session without being readable there or in a session log (#421). Its own
+     * shape, so it never opens as a stored secret.
+     */
+    sealPending(username, seed) {
+        return sealTotpSecret(this.credentialsKey, username, JSON.stringify({ pendingSeed: seed }));
+    }
+    /** Open what `sealPending` made for `username`; null when it is not that. */
+    openPending(username, sealed) {
+        if (typeof sealed !== 'string')
+            return null;
+        const plain = openTotpSecret(this.credentialsKey, username, sealed);
+        if (!plain)
+            return null;
+        try {
+            const p = JSON.parse(plain);
+            return typeof p.pendingSeed === 'string' ? p.pendingSeed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Check the code that confirms an enrolment and seal the seed for the store.
+     * The confirming code's step is recorded, so it cannot then sign anyone in.
+     * Null when the seed is malformed or the code does not match.
+     */
+    confirmEnrolment(username, seed, code) {
+        let step;
+        try {
+            step = matchingStep(seed, code, this.now());
+        }
+        catch {
+            return null; // not base32
+        }
+        if (step === null)
+            return null;
+        return sealTotpSecret(this.credentialsKey, username, JSON.stringify({ seed, lastStep: step }));
+    }
+    /** Verify `credentials.code` for `credentials.username`. A failure gives no reason. */
+    async verify(credentials) {
+        const { username, code } = credentials;
+        if (typeof username !== 'string' || !username || !isCode(code))
+            return null;
+        return this.serial.run(username, async () => {
+            const now = this.now();
+            for (const row of this.store.rows(username)) {
+                const secret = this.open(row);
+                if (!secret)
+                    continue;
+                const step = matchingStep(secret.seed, code, now);
+                if (step === null || step <= secret.lastStep)
+                    continue;
+                const next = sealTotpSecret(this.credentialsKey, username, JSON.stringify({ seed: secret.seed, lastStep: step }));
+                await this.store.used(row.id, new Date(now).toISOString(), next);
+                return { username };
+            }
+            return null;
+        });
+    }
+    open(row) {
+        if (row.kind !== 'totp')
+            return null;
+        const plain = openTotpSecret(this.credentialsKey, row.username, row.secret);
+        if (!plain)
+            return null;
+        try {
+            const s = JSON.parse(plain);
+            return typeof s.seed === 'string' && typeof s.lastStep === 'number' ? s : null;
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/lib/src/types/Consent.d.ts

@@ -33,6 +33,15 @@ export declare const RECOVERY_WORDS_DOCUMENT = "recovery-words";
 export declare const SHARED_FOLDERS_WORDS_CONSENT_SCOPE = "shared-folders-recovery-words";
 /** The page whose `version:` is the version of the shared-folders recovery-words wording (#2124). */
 export declare const SHARED_FOLDERS_WORDS_DOCUMENT = "shared-folders-recovery-words";
+/**
+ * The scope of "Remember this browser" (#1523 slice 1c, Q5): a person's
+ * opt-in, at the second-factor step, to a device key on this browser that
+ * skips the second-factor prompt next time. Bound to a subject: the remembered
+ * device's id, so each browser is its own consent, withdrawn by removing it.
+ */
+export declare const REMEMBER_BROWSER_CONSENT_SCOPE = "remember-browser";
+/** The page whose `version:` is the version of the "Remember this browser" wording (#1523 slice 1c). */
+export declare const REMEMBER_BROWSER_DOCUMENT = "remember-browser";
 /** Core's scopes bound to a subject, each with its one document (#1928, #2124). */
 export declare const SUBJECT_CONSENT_DOCUMENTS: Readonly<Record<ConsentScope, string>>;
 /** Scopes whose acceptance is about one thing (a subject), not the account as a whole (#1928). */
@@ -61,17 +70,21 @@ export interface ConsentSeen {
     version: string;
 }
 /**
- * One acceptance, one line of the person's file. Append-only: a later
- * version is a later line, nothing is rewritten.
+ * One acceptance, or its withdrawal, one line of the person's file.
+ * Append-only: a later version is a later line, and a withdrawal is a later
+ * `withdraw` line naming the same document, version and subject; nothing is
+ * rewritten.
  */
 export interface ConsentRecord {
-    kind: 'accept';
+    kind: 'accept' | 'withdraw';
     document: string;
     scope: ConsentScope;
     version: string;
     effective: string | null;
-    /** ISO 8601 time the person accepted. */
+    /** ISO 8601 time the person accepted (on a `withdraw` line, of the acceptance withdrawn). */
     acceptedAt: string;
+    /** ISO 8601 time it was withdrawn; on a `withdraw` line only. */
+    withdrawnAt?: string;
     /**
      * The account this was accepted on, by its creation time (#1937): a later
      * account that takes the same username never inherits it.

package/lib/src/types/Consent.js

@@ -31,10 +31,20 @@ export const RECOVERY_WORDS_DOCUMENT = 'recovery-words';
 export const SHARED_FOLDERS_WORDS_CONSENT_SCOPE = 'shared-folders-recovery-words';
 /** The page whose `version:` is the version of the shared-folders recovery-words wording (#2124). */
 export const SHARED_FOLDERS_WORDS_DOCUMENT = 'shared-folders-recovery-words';
+/**
+ * The scope of "Remember this browser" (#1523 slice 1c, Q5): a person's
+ * opt-in, at the second-factor step, to a device key on this browser that
+ * skips the second-factor prompt next time. Bound to a subject: the remembered
+ * device's id, so each browser is its own consent, withdrawn by removing it.
+ */
+export const REMEMBER_BROWSER_CONSENT_SCOPE = 'remember-browser';
+/** The page whose `version:` is the version of the "Remember this browser" wording (#1523 slice 1c). */
+export const REMEMBER_BROWSER_DOCUMENT = 'remember-browser';
 /** Core's scopes bound to a subject, each with its one document (#1928, #2124). */
 export const SUBJECT_CONSENT_DOCUMENTS = {
     [RECOVERY_WORDS_CONSENT_SCOPE]: RECOVERY_WORDS_DOCUMENT,
-    [SHARED_FOLDERS_WORDS_CONSENT_SCOPE]: SHARED_FOLDERS_WORDS_DOCUMENT
+    [SHARED_FOLDERS_WORDS_CONSENT_SCOPE]: SHARED_FOLDERS_WORDS_DOCUMENT,
+    [REMEMBER_BROWSER_CONSENT_SCOPE]: REMEMBER_BROWSER_DOCUMENT
 };
 /** Scopes whose acceptance is about one thing (a subject), not the account as a whole (#1928). */
 export const SUBJECT_CONSENT_SCOPES = Object.keys(SUBJECT_CONSENT_DOCUMENTS);

package/lib/src/types/Provider.d.ts

@@ -630,6 +630,12 @@ export interface StoreFileInput {
     keptOriginal?: {
         types: readonly string[];
     };
+    /**
+     * The id to store the file under, set only by AttachmentManager for a file
+     * a takeout re-import brings back (#2188), after it checked that no other
+     * file anywhere holds it. A store that already lists the id refuses it.
+     */
+    id?: string;
 }
 /**
  * A page in a private store (#1456): its entry in the store's OWN page index,

package/lib/src/types/express.d.ts

@@ -40,6 +40,14 @@ declare module 'express-session' {
             purpose: 'register' | 'authenticate' | 'reauth';
             expires: number;
         };
+        /**
+         * #421: an authenticator-app seed offered on /profile/totp, until a code confirms it (10 minutes).
+         * Sealed for the account by `totpEnrolmentStart`; the plain seed never enters the session.
+         */
+        totpEnrolment?: {
+            pending: string;
+            expires: number;
+        };
         /** The step-up asked for and not yet given (#2145): its permission, where it returns, whether returning redoes it. */
         pendingStepUp?: PendingStepUp;
         /** The path whose next page view says "Confirmed — you can do it now" after a step-up (#2145). */
@@ -49,6 +57,20 @@ declare module 'express-session' {
         /** A sign-in waiting for its second factor: the handle, and where to go after (#1523). No identity yet. */
         pendingSignIn?: string;
         pendingRedirect?: string;
+        /**
+         * #1523 slice 1c: "Remember this browser" was ticked and a second factor
+         * completed the sign-in; the next page has the browser make its key. The
+         * version of the page the person was shown, the sign-in's amr, where to go
+         * after, until when (epoch ms), and the id of the sign-in's audit record,
+         * which the remembered row names. Single use.
+         */
+        rememberBrowser?: {
+            version: string;
+            amr: string[];
+            next: string;
+            until: number;
+            auditId?: string;
+        };
         /** A verified outside identity no account has connected, waiting for the person to sign in another way (#1743). */
         pendingConnection?: PendingConnection;
         /** #2073: an outside sign-in whose email several accounts share, waiting for the person to choose one. */

package/lib/src/utils/auditChain.d.ts

@@ -0,0 +1,83 @@
+/** `prevHash` of the first record in a chain. */
+export declare const GENESIS_HASH = "genesis";
+/**
+ * Hash a record in its position in the chain.
+ *
+ * `seq` and `prevHash` are part of the input, not just the payload — otherwise
+ * records could be reordered, or a record moved to a different predecessor,
+ * without breaking anything.
+ */
+export declare function hashRecord(record: Record<string, unknown>, seq: number, prevHash: string): string;
+/** Add `seq`, `prevHash` and `hash` to a record. Returns a new object. */
+export declare function stampRecord(record: Record<string, unknown>, seq: number, prevHash: string): Record<string, unknown>;
+/** Outcome of verifying a chain. `brokenAt` is the 1-based position, not the seq. */
+export interface ChainVerdict {
+    ok: boolean;
+    checked: number;
+    brokenAt?: number;
+    reason?: string;
+}
+/**
+ * Where a chain that does not begin at genesis begins (#1537): the sequence
+ * and hash of the last record before the first one present. A retention
+ * checkpoint holds exactly this for the records it removed, so what remains
+ * verifies from it rather than from genesis.
+ */
+export interface ChainStart {
+    seq: number;
+    hash: string;
+}
+/**
+ * Walk a chain in order and report the first break.
+ *
+ * @param records - Audit records, oldest first
+ * @param options.expectedHead - Hash the last record must have. Supplying it is
+ *   the only way to detect truncation: removing records from the end breaks no
+ *   link, so the chain alone cannot see it.
+ * @param options.start - The checkpoint the chain continues from (#1537). The
+ *   first record must then carry `start.seq + 1` and link to `start.hash`;
+ *   without it the first record must link to genesis.
+ */
+export declare function verifyChain(records: readonly Record<string, unknown>[], options?: {
+    expectedHead?: string;
+    start?: ChainStart;
+}): ChainVerdict;
+/** Event type of a record that declares a deliberate chain discontinuity (#1124). */
+export declare const CHAIN_RESTART_EVENT: "audit-chain-restart";
+/** One contiguous chain within a log. */
+export interface ChainSegment {
+    /** Index of the segment's first record in the input. */
+    startIndex: number;
+    verdict: ChainVerdict;
+    /** The restart marker that begins this segment, if it was started by one. */
+    restart?: Record<string, unknown>;
+    /** True when a break at the END of this segment is followed by a restart marker. */
+    explained: boolean;
+    /** True when this segment's marker names a previous head that does not match. */
+    mismatchedPrevious: boolean;
+}
+export interface LogVerdict {
+    ok: boolean;
+    segments: ChainSegment[];
+}
+/**
+ * Verify a log that may contain deliberate discontinuities (#1124).
+ *
+ * `verifyChain` answers "is this one chain intact", which is the right question
+ * for a chain and the wrong one for a log that has legitimately restarted — a
+ * migration, a restore, or a bug that wrote unverifiable records. Without this,
+ * one bad record leaves a log unverifiable forever and the only ways forward
+ * are dishonest: edit the log, delete it, or ignore the verifier.
+ *
+ * A break is __explained__ only when the very next record is a restart marker.
+ * That is what keeps the marker from being an escape hatch: an attacker who
+ * wants a clean chain must write a record saying they broke it, which is a
+ * confession rather than a cover-up.
+ *
+ * The marker's claimed `previousHash` is checked against the head it actually
+ * follows. A marker asserting a history that did not happen is itself a
+ * finding — otherwise a restart could claim anything.
+ */
+export declare function verifyLog(records: readonly Record<string, unknown>[], options?: {
+    start?: ChainStart;
+}): LogVerdict;

package/lib/src/utils/auditHeadWitness.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Off-box witness for the audit chain head (#1138).
+ *
+ * The chain detects alteration and deletion, and __cannot detect truncation of
+ * the tail__: removing records from the end breaks no link. That is also the
+ * attack an intruder actually wants — remove the record of what they just did.
+ * Everything before their session verifies perfectly, and the log ends looking
+ * like a clean shutdown.
+ *
+ * It cannot be fixed locally, for the reason #1119 made the chain functions
+ * pure: an attacker who owns the machine owns anything the machine wrote
+ * locally, including a head stored beside the log. __The head has to leave the
+ * box, or it is not evidence.__
+ *
+ * Three decisions from docs/security-posture.md shape what this does and does
+ * not do:
+ *
+ * - __D13__ — deployment methodology does not influence the design. This
+ *   publishes a head to a configured destination and takes no view on what that
+ *   destination is. Whether it is genuinely off-box is the operator's decision
+ *   and the operator's to state.
+ * - __D21__ — report facts, not a claim. There is deliberately no `offBox:
+ *   true` produced here. Nothing on this machine can verify that a path leaves
+ *   it, and asserting so would be the `durable` defect (#1148) repeated: a
+ *   boolean derived from something that does not establish it.
+ * - __D20__ — no scoring. A verdict says what is observably true of the records
+ *   and the witness, and stops there.
+ */
+/** What is published: one sequence number and one hash. Nothing else. */
+export interface ChainWitness {
+    seq: number;
+    hash: string;
+    /** Which instance the head belongs to, so one store can hold several. */
+    instance: string;
+    publishedAt: string;
+}
+/** The minimum of a stored record this assessment needs. */
+export interface ChainRecord {
+    seq?: number;
+    hash?: string;
+}
+export type WitnessVerdict = 
+/** The log is consistent with the witness. */
+'intact'
+/** The witness is ahead of the log: records were removed from the end. */
+ | 'truncated'
+/** The witnessed sequence is present with a different hash, or absent. */
+ | 'altered'
+/** No witness. NOT the same statement as "intact". */
+ | 'unknown';
+export interface WitnessAssessment {
+    verdict: WitnessVerdict;
+    /** How many records are missing from the end. Only meaningful when truncated. */
+    missing?: number;
+    reason?: string;
+}
+export interface BuildWitnessInput {
+    seq: number;
+    hash: string;
+    instance: string;
+    at: Date;
+}
+/**
+ * Build the record to publish.
+ *
+ * The head is one hash and one sequence number. Publishing more would put
+ * audit CONTENT wherever the witness lives, which is a different and much
+ * larger trust decision than publishing a fingerprint of it.
+ */
+export declare function buildWitness(input: BuildWitnessInput): ChainWitness;
+/**
+ * Is it time to publish again?
+ *
+ * The gap between publications is the window an attacker can truncate within,
+ * which makes the interval the actual security parameter — worth setting
+ * explicitly rather than inheriting.
+ *
+ * A zero or negative interval publishes every time rather than never: a
+ * misconfigured interval must fail toward more evidence, not toward silently
+ * disabling the witness.
+ */
+export declare function shouldPublish(lastPublishedAtMs: number | null, nowMs: number, intervalMs: number): boolean;
+/**
+ * Compare a published head against the records now on disk.
+ *
+ * The verdicts are kept distinct because an assessor needs the difference:
+ * truncation says records were removed, alteration says one was rewritten, and
+ * reporting both as "broken" loses what they would act on.
+ *
+ * `unknown` is never reported as `intact`. "Nothing is witnessing this log" and
+ * "this log is intact" are different statements, and deriving the second from
+ * the first is exactly the claim #1148 removed elsewhere.
+ */
+export declare function assessWitness(witness: ChainWitness | {
+    seq: number;
+    hash: string;
+} | null, records: readonly ChainRecord[]): WitnessAssessment;