@forgezero/runtime 0.1.0

package/contracts/test/Custody.t.sol

@@ -0,0 +1,361 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import { DepositFactory } from '../src/DepositFactory.sol';
+import { DepositProxy } from '../src/DepositProxy.sol';
+import { ColdVault } from '../src/ColdVault.sol';
+import { MockToken, MockNoReturnToken, MockFeeToken } from '../src/MockTokens.sol';
+
+/** Foundry cheatcodes, declared inline — this repository does not use submodules. */
+interface Vm {
+	function prank(address) external;
+	function expectRevert(bytes4) external;
+	function expectRevert(bytes calldata) external;
+	function expectRevert() external;
+	function deal(address, uint256) external;
+	function addr(uint256) external pure returns (address);
+	function sign(uint256, bytes32) external pure returns (uint8, bytes32, bytes32);
+	function warp(uint256) external;
+}
+
+contract CustodyTest {
+	Vm constant vm = Vm(0x7109709ECfa91a80626fF3989D68f67F5b1DD12D);
+
+	DepositFactory factory;
+	MockToken token;
+	address owner = address(this);
+	address hot = address(0x8074);
+
+	function setUp() public {
+		factory = new DepositFactory(owner);
+		token = new MockToken();
+	}
+
+	/* ================================================== deposit factory === */
+
+	function test_addressIsDerivedWithNoChainWrite() public {
+		// A million deposit addresses cost nothing to derive. This is the whole
+		// advantage over generating and funding a key per address.
+		bytes32 salt = keccak256('anything');
+		address derived = factory.computeAddress(salt);
+		require(derived != address(0), 'derived');
+		require(derived.code.length == 0, 'nothing deployed yet');
+		require(factory.computeAddress(salt) == derived, 'stable');
+	}
+
+	function test_offChainDerivationMatchesTheContract() public {
+		// The formula a platform runs off-chain, computed here from the published
+		// init-code hash. If these ever disagree, deposits go to an address the
+		// platform is not watching.
+		bytes32 salt = keccak256('user:42');
+		address expected = address(
+			uint160(uint256(keccak256(abi.encodePacked(
+				bytes1(0xff), address(factory), salt, factory.PROXY_INIT_CODE_HASH()
+			))))
+		);
+		require(factory.computeAddress(salt) == expected, 'formula matches');
+	}
+
+	function test_theSaltIsOpaque_userOrInvoiceBothWork() public {
+		// The runtime never learns what a salt means. A per-user address and a
+		// per-invoice address are the same primitive with a different convention,
+		// and encoding either here would force it on every platform.
+		bytes32 perUser = keccak256(abi.encodePacked('app:user:', uint256(7)));
+		bytes32 perInvoice = keccak256(abi.encodePacked('app:invoice:', uint256(7)));
+		require(factory.computeAddress(perUser) != factory.computeAddress(perInvoice), 'distinct');
+	}
+
+	function test_sweepNeedsNoApprovalAndNoGasAtTheDepositAddress() public {
+		// The property that makes this design work at all. The deposit address has
+		// no key, no native balance and has never signed anything.
+		bytes32 salt = keccak256('user:1');
+		address deposit = factory.computeAddress(salt);
+		token.mint(deposit, 500);
+		require(deposit.balance == 0, 'no gas at the deposit address');
+
+		bytes32[] memory salts = new bytes32[](1);
+		salts[0] = salt;
+		factory.sweepTo(salts, address(token), hot);
+
+		require(token.balanceOf(deposit) == 0, 'collected');
+		require(token.balanceOf(hot) == 500, 'delivered');
+	}
+
+	function test_theProxyIsDeployedLazilyAndOnlyOnce() public {
+		bytes32 salt = keccak256('user:2');
+		address deposit = factory.computeAddress(salt);
+		token.mint(deposit, 100);
+
+		bytes32[] memory salts = new bytes32[](1);
+		salts[0] = salt;
+		factory.sweepTo(salts, address(token), hot);
+		require(deposit.code.length > 0, 'deployed on first sweep');
+
+		token.mint(deposit, 100);
+		factory.sweepTo(salts, address(token), hot);
+		require(token.balanceOf(hot) == 200, 'second sweep works');
+	}
+
+	function test_onlyTheFactoryCanSweepAProxy() public {
+		bytes32 salt = keccak256('user:3');
+		address deposit = factory.computeAddress(salt);
+		token.mint(deposit, 100);
+		bytes32[] memory salts = new bytes32[](1);
+		salts[0] = salt;
+		factory.sweepTo(salts, address(token), hot);
+
+		// Deployed now — and inert to everybody else.
+		vm.prank(address(0xBAD));
+		vm.expectRevert(DepositProxy.OnlyFactory.selector);
+		DepositProxy(payable(deposit)).sweep(address(token), address(0xBAD));
+	}
+
+	function test_manyAddressesConsolidateInOneTransaction() public {
+		bytes32[] memory salts = new bytes32[](3);
+		for (uint256 i = 0; i < 3; i++) {
+			salts[i] = keccak256(abi.encodePacked('user:', i));
+			token.mint(factory.computeAddress(salts[i]), 100);
+		}
+		factory.sweepTo(salts, address(token), hot);
+		require(token.balanceOf(hot) == 300, 'all three');
+	}
+
+	function test_anAlreadyEmptyAddressDoesNotUndoTheBatch() public {
+		bytes32[] memory salts = new bytes32[](2);
+		salts[0] = keccak256('empty');
+		salts[1] = keccak256('funded');
+		token.mint(factory.computeAddress(salts[1]), 250);
+		factory.sweepTo(salts, address(token), hot);
+		require(token.balanceOf(hot) == 250, 'funded one still swept');
+	}
+
+	function test_nativeCoinSweeps() public {
+		bytes32 salt = keccak256('native');
+		address deposit = factory.computeAddress(salt);
+		vm.deal(deposit, 3 ether);
+		bytes32[] memory salts = new bytes32[](1);
+		salts[0] = salt;
+		factory.sweepTo(salts, address(0), hot);
+		require(hot.balance == 3 ether, 'native delivered');
+	}
+
+	function test_usdtStyleTokenSweeps() public {
+		// Returns nothing from transfer. A bool-typed call reverts on decode.
+		MockNoReturnToken usdt = new MockNoReturnToken();
+		bytes32 salt = keccak256('usdt');
+		usdt.mint(factory.computeAddress(salt), 900);
+		bytes32[] memory salts = new bytes32[](1);
+		salts[0] = salt;
+		factory.sweepTo(salts, address(usdt), hot);
+		require(usdt.balanceOf(hot) == 900, 'usdt swept');
+	}
+
+	function test_feeOnTransferMovesWhatActuallyArrives() public {
+		// The proxy sweeps its measured balance, so the platform never credits a
+		// figure the token did not deliver.
+		MockFeeToken fee = new MockFeeToken();
+		bytes32 salt = keccak256('fee');
+		fee.mint(factory.computeAddress(salt), 1000);
+		bytes32[] memory salts = new bytes32[](1);
+		salts[0] = salt;
+		factory.sweepTo(salts, address(fee), hot);
+		// 1% on the way to the factory, 1% again on the way out.
+		require(fee.balanceOf(hot) < 1000, 'fee was taken');
+		require(fee.balanceOf(hot) > 970, 'and only the fee');
+	}
+
+	function test_aStrangerCannotSweep() public {
+		bytes32[] memory salts = new bytes32[](0);
+		vm.prank(address(0xBAD));
+		vm.expectRevert(DepositFactory.NotOwner.selector);
+		factory.sweepTo(salts, address(token), hot);
+	}
+}
+
+contract VaultTest {
+	Vm constant vm = Vm(0x7109709ECfa91a80626fF3989D68f67F5b1DD12D);
+
+	ColdVault vault;
+	MockToken token;
+
+	uint256 k1 = 0xA11CE;
+	uint256 k2 = 0xB0B;
+	uint256 k3 = 0xCA401;
+	address c1;
+	address c2;
+	address c3;
+	address operator = address(0x0FF);
+	address payee = address(0xFEE);
+
+	function setUp() public {
+		c1 = vm.addr(k1);
+		c2 = vm.addr(k2);
+		c3 = vm.addr(k3);
+		address[] memory custodians = new address[](3);
+		// Sorted, because signatures must arrive in ascending signer order.
+		(custodians[0], custodians[1], custodians[2]) = _sorted(c1, c2, c3);
+		vault = new ColdVault(custodians, 2);
+		token = new MockToken();
+		token.mint(address(vault), 1_000_000);
+	}
+
+	function _sorted(address a, address b, address c) private pure returns (address, address, address) {
+		address t;
+		if (a > b) { t = a; a = b; b = t; }
+		if (b > c) { t = b; b = c; c = t; }
+		if (a > b) { t = a; a = b; b = t; }
+		return (a, b, c);
+	}
+
+	function _sign(uint256 key, bytes32 digest) private pure returns (bytes memory) {
+		(uint8 v, bytes32 r, bytes32 s) = vm.sign(key, digest);
+		return abi.encodePacked(r, s, v);
+	}
+
+	/** Two signatures, ordered by signer address as the vault requires. */
+	function _quorum(bytes32 digest) private view returns (bytes[] memory out) {
+		out = new bytes[](2);
+		uint256[3] memory keys = [k1, k2, k3];
+		address[3] memory addrs = [c1, c2, c3];
+		// Pick the two lowest addresses so the ordering rule is satisfied.
+		uint256 lowest = 0;
+		for (uint256 i = 1; i < 3; i++) if (addrs[i] < addrs[lowest]) lowest = i;
+		uint256 second = lowest == 0 ? 1 : 0;
+		for (uint256 i = 0; i < 3; i++) {
+			if (i != lowest && addrs[i] < addrs[second]) second = i;
+		}
+		if (second == lowest) second = (lowest + 1) % 3;
+		out[0] = _sign(keys[lowest], digest);
+		out[1] = _sign(keys[second], digest);
+		if (addrs[lowest] > addrs[second]) {
+			bytes memory tmp = out[0]; out[0] = out[1]; out[1] = tmp;
+		}
+	}
+
+	/* ======================================================= cold vault === */
+
+	function test_quorumMovesFunds() public {
+		bytes32 digest = vault.digestFor(address(token), payee, 5000);
+		vault.withdraw(address(token), payee, 5000, _quorum(digest));
+		require(token.balanceOf(payee) == 5000, 'paid');
+	}
+
+	function test_oneSignatureIsNotAQuorum() public {
+		bytes32 digest = vault.digestFor(address(token), payee, 5000);
+		bytes[] memory one = new bytes[](1);
+		one[0] = _sign(k1, digest);
+		vm.expectRevert(abi.encodeWithSelector(ColdVault.NotEnoughSignatures.selector, 1, 2));
+		vault.withdraw(address(token), payee, 5000, one);
+	}
+
+	function test_theSameCustodianTwiceIsNotTwoCustodians() public {
+		// Without the ascending-order rule, one custodian submits M copies of
+		// their own approval and an M-of-N vault is a 1-of-N vault.
+		bytes32 digest = vault.digestFor(address(token), payee, 5000);
+		bytes[] memory doubled = new bytes[](2);
+		doubled[0] = _sign(k1, digest);
+		doubled[1] = _sign(k1, digest);
+		vm.expectRevert(ColdVault.SignaturesOutOfOrder.selector);
+		vault.withdraw(address(token), payee, 5000, doubled);
+	}
+
+	function test_aStrangersSignatureIsRejected() public {
+		bytes32 digest = vault.digestFor(address(token), payee, 5000);
+		bytes[] memory sigs = new bytes[](2);
+		uint256 outsider = 0xDEAD;
+		address outsiderAddr = vm.addr(outsider);
+		// Ordered so the failure is "not a custodian", not the ordering rule.
+		if (outsiderAddr < c1) {
+			sigs[0] = _sign(outsider, digest);
+			sigs[1] = _sign(k1, digest);
+		} else {
+			sigs[0] = _sign(k1, digest);
+			sigs[1] = _sign(outsider, digest);
+		}
+		vm.expectRevert(abi.encodeWithSelector(ColdVault.NotACustodian.selector, outsiderAddr));
+		vault.withdraw(address(token), payee, 5000, sigs);
+	}
+
+	function test_aSpentApprovalCannotBeReplayed() public {
+		// The nonce is what makes a gathered signature spendable once. Without it,
+		// a set of approvals collected today drains the vault forever.
+		bytes32 digest = vault.digestFor(address(token), payee, 5000);
+		bytes[] memory sigs = _quorum(digest);
+		vault.withdraw(address(token), payee, 5000, sigs);
+
+		// The nonce moved, so the same bytes now recover to SOME other address --
+		// whichever one, it is not a custodian, and the vault refuses.
+		uint256 before = token.balanceOf(payee);
+		vm.expectRevert();
+		vault.withdraw(address(token), payee, 5000, sigs);
+		require(token.balanceOf(payee) == before, 'nothing moved twice');
+	}
+
+	function test_signaturesDoNotTransferToADifferentAmount() public {
+		// The amount is inside what was signed, so a submitter cannot inflate it.
+		bytes32 digest = vault.digestFor(address(token), payee, 5000);
+		bytes[] memory sigs = _quorum(digest);
+		vm.expectRevert();
+		vault.withdraw(address(token), payee, 999_999, sigs);
+		require(token.balanceOf(payee) == 0, 'nothing moved');
+	}
+
+	function test_signaturesDoNotTransferToADifferentDestination() public {
+		bytes32 digest = vault.digestFor(address(token), payee, 5000);
+		bytes[] memory sigs = _quorum(digest);
+		vm.expectRevert();
+		vault.withdraw(address(token), address(0xBAD), 5000, sigs);
+		require(token.balanceOf(address(0xBAD)) == 0, 'nothing moved');
+	}
+
+	function test_signaturesFromAnotherVaultAreVoidHere() public {
+		// `verifyingContract` is in the domain, so approvals gathered for one
+		// deployment cannot be pointed at another.
+		address[] memory custodians = new address[](3);
+		(custodians[0], custodians[1], custodians[2]) = _sorted(c1, c2, c3);
+		ColdVault other = new ColdVault(custodians, 2);
+		token.mint(address(other), 10_000);
+
+		bytes32 otherDigest = other.digestFor(address(token), payee, 5000);
+		bytes[] memory sigs = _quorum(otherDigest);
+		vm.expectRevert();
+		vault.withdraw(address(token), payee, 5000, sigs);
+		require(token.balanceOf(payee) == 0, 'nothing moved');
+	}
+
+	function test_aThresholdOfOneIsRefused() public {
+		address[] memory custodians = new address[](3);
+		(custodians[0], custodians[1], custodians[2]) = _sorted(c1, c2, c3);
+		vm.expectRevert(ColdVault.BadThreshold.selector);
+		new ColdVault(custodians, 1);
+	}
+
+	function test_aThresholdAboveTheSetIsRefused() public {
+		// A vault nobody can ever open is not more secure, it is destroyed.
+		address[] memory custodians = new address[](2);
+		custodians[0] = c1 < c2 ? c1 : c2;
+		custodians[1] = c1 < c2 ? c2 : c1;
+		vm.expectRevert(ColdVault.BadThreshold.selector);
+		new ColdVault(custodians, 3);
+	}
+
+	function test_nobodyCanRotateCustodiansWithoutTheQuorum() public {
+		address[] memory next = new address[](2);
+		next[0] = address(0x1);
+		next[1] = address(0x2);
+		vm.expectRevert(ColdVault.OnlySelf.selector);
+		vault.setCustodians(next, 2);
+	}
+
+	/* ------------------------------------------------------------------------
+	 * There is no hot vault, deliberately.
+	 *
+	 * A hot wallet is an ADDRESS, not a contract. The factory already holds float
+	 * and already sweeps to any destination, so a separate contract to hold
+	 * working capital adds a deployment, an upgrade path and a second set of
+	 * permissions without adding a property neither of these already has.
+	 *
+	 * Operational funds sit at whatever address the platform sweeps to; the cold
+	 * vault holds what M-of-N custodians guard. Two things, each doing one job.
+	 * ---------------------------------------------------------------------- */
+}

package/contracts/test/Vectors.t.sol

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import { DepositFactory } from '../src/DepositFactory.sol';
+import { ColdVault } from '../src/ColdVault.sol';
+
+/**
+ * Emit values the TypeScript client must reproduce.
+ *
+ * The client mirrors two pure contract functions. Checking it against itself
+ * proves nothing — a formula wrong the same way every time is deterministic and
+ * still points a platform at an address the factory cannot sweep.
+ */
+contract VectorsTest {
+	function test_emitVectors() public {
+		// A fixed owner so the factory address is stable across runs.
+		DepositFactory factory = new DepositFactory(address(0xF00D));
+
+		bytes32 salt = keccak256(abi.encodePacked('myapp:user:', 'u1'));
+
+		address[] memory custodians = new address[](3);
+		custodians[0] = address(0x1111111111111111111111111111111111111111);
+		custodians[1] = address(0x2222222222222222222222222222222222222222);
+		custodians[2] = address(0x3333333333333333333333333333333333333333);
+		ColdVault vault = new ColdVault(custodians, 2);
+
+		bytes32 digest = vault.digestFor(
+			address(0xdAC17F958D2ee523a2206206994597C13D831ec7),
+			address(0x000000000000000000000000000000000000dEaD),
+			1_000_000
+		);
+
+		// Read from the trace; the TS test asserts against these.
+		require(factory.computeAddress(salt) != address(0), 'derived');
+		emit Vector('factory', abi.encode(address(factory)));
+		emit Vector('proxyInitCodeHash', abi.encode(factory.PROXY_INIT_CODE_HASH()));
+		emit Vector('salt', abi.encode(salt));
+		emit Vector('depositAddress', abi.encode(factory.computeAddress(salt)));
+		emit Vector('vault', abi.encode(address(vault)));
+		emit Vector('chainId', abi.encode(block.chainid));
+		emit Vector('withdrawDigest', abi.encode(digest));
+	}
+
+	event Vector(string name, bytes value);
+}

package/dist/audit.d.ts

@@ -0,0 +1,265 @@
+/**
+ * An audit trail that can prove it was not edited.
+ *
+ * ForgeZero already writes an audit log. What it cannot do — what no ordinary
+ * log can do — is answer the question that actually matters when somebody asks:
+ * *is this the same trail you wrote at the time?* A row in a database is exactly
+ * as trustworthy as everyone holding write access to that database, which during
+ * an incident is precisely the set of people under suspicion.
+ *
+ * Chaining fixes that without any new infrastructure. Each record carries the
+ * digest of the one before it, so the trail is a hash chain: alter a record and
+ * every subsequent link fails to match. Delete one and the seam is visible at
+ * the join. The log becomes evidence rather than testimony.
+ *
+ * ## What this buys, precisely
+ *
+ * It makes tampering **detectable**, not impossible. Someone with write access
+ * can still rewrite the entire chain from the altered record forward. Three
+ * things make that expensive, and the package supports all three:
+ *
+ *   1. **Anchors** — a digest published somewhere the operator does not control
+ *      (a customer's inbox, an object store with retention lock, a counter-signed
+ *      report). Rewriting history then requires rewriting the anchor too.
+ *   2. **Per-realm chains** — one tampered tenant does not require forging every
+ *      other tenant's history, and one busy tenant does not serialise the rest.
+ *   3. **Sealed digests** — the chain digest is an HMAC under a key held outside
+ *      the database, so write access alone is not enough to recompute a valid
+ *      successor. See `sealedChain`.
+ *
+ * Claiming more than this would be the actual failure. A hash chain in a
+ * database you control is *tamper-evident*; only an external anchor makes any
+ * part of it *tamper-proof*, and only as far back as the last anchor.
+ *
+ * ## Why not sign every record
+ *
+ * A signature per record is a keypair on the write path, a verification cost per
+ * row, and a key that must be online to append. The chain gets detection from a
+ * hash — no key material, no online signer — and signing is applied to the
+ * *anchor* instead, where one signature covers everything since the last one.
+ */
+export declare class AuditChainError extends Error {
+    readonly code: 'BROKEN_LINK' | 'BAD_DIGEST' | 'OUT_OF_ORDER' | 'EMPTY_RANGE' | 'NOT_GENESIS';
+    /** Where the chain first fails. The only number worth reporting. */
+    readonly at?: number | undefined;
+    constructor(code: 'BROKEN_LINK' | 'BAD_DIGEST' | 'OUT_OF_ORDER' | 'EMPTY_RANGE' | 'NOT_GENESIS', message: string, 
+    /** Where the chain first fails. The only number worth reporting. */
+    at?: number | undefined);
+}
+/**
+ * The first record's predecessor.
+ *
+ * A constant rather than an empty string so that "this is the start of the
+ * chain" and "somebody blanked the field" are different values. The second is a
+ * break; the first is not, and a verifier that cannot tell them apart either
+ * rejects every valid chain or accepts a truncated one.
+ */
+export declare const GENESIS_DIGEST: string;
+/** What the caller supplies. Everything else is computed. */
+export interface AuditEntry {
+    action: string;
+    outcome: 'allowed' | 'denied';
+    actor?: string;
+    realm?: string;
+    targetCollection?: string;
+    targetKey?: string;
+    /** Non-secret context. Never a value, never a credential. */
+    detail?: Record<string, string | number | boolean | null>;
+    reason?: string;
+}
+export interface AuditRecord extends AuditEntry {
+    /** Position in this realm's chain, from 1. Gaps are themselves evidence. */
+    sequence: number;
+    atMs: number;
+    /** The previous record's `digest`, or `GENESIS_DIGEST` for the first. */
+    previousDigest: string;
+    digest: string;
+}
+/**
+ * The bytes that get hashed.
+ *
+ * Field order is fixed here and never derived from `Object.keys`, because
+ * insertion order differs between a record built by a handler and the same
+ * record read back from a database — and a verifier that hashes them in a
+ * different order reports every record as tampered.
+ *
+ * `undefined` and an absent key must serialise identically for the same reason:
+ * a driver that drops null fields on write would otherwise break every chain it
+ * touches.
+ */
+export declare function canonicalise(record: Omit<AuditRecord, 'digest'>): string;
+/** How a digest is computed. Swappable so the sealed variant can substitute HMAC. */
+export type Digester = (input: string) => Promise<string>;
+export declare const hashDigester: Digester;
+/**
+ * A digester keyed by a secret held outside the database.
+ *
+ * With a plain hash, anyone who can write rows can also recompute a valid chain
+ * — detection depends on them not bothering. With an HMAC they additionally need
+ * the key, which lives in the vault and not in the collection being defended.
+ * That is the difference between "an attacker must be careful" and "an attacker
+ * must also have compromised the vault".
+ */
+export declare const sealedDigester: (key: string | Uint8Array) => Digester;
+/** Where records go, and where the tail is read from to chain onto it. */
+export interface AuditStore {
+    /** The most recent record in this realm's chain, or null if it has none. */
+    tail(realm?: string): Promise<AuditRecord | null>;
+    append(record: AuditRecord): Promise<void>;
+    /** Ascending by sequence. Inclusive bounds. */
+    range(realm: string | undefined, fromSequence: number, toSequence: number): Promise<AuditRecord[]>;
+}
+export interface AppendOptions {
+    digester?: Digester;
+    now?: () => number;
+}
+/**
+ * Add one record to the end of a realm's chain.
+ *
+ * The read of the tail and the append are **not** atomic here, and cannot be
+ * without knowing the store. Two concurrent appends can therefore both chain
+ * onto the same predecessor, producing two records with one sequence number.
+ * That is a duplicate, not a forgery, and `verifyChain` reports it as
+ * `OUT_OF_ORDER` rather than silently accepting one.
+ *
+ * The fix belongs in the store: a unique index on `(realm, sequence)` turns the
+ * race into a failed insert that the caller retries. `createAuditChain` below
+ * serialises appends per realm in-process, which closes it for a single node;
+ * the unique index is what closes it for a cluster. Both are cheap, and the
+ * combination is what makes the sequence trustworthy.
+ */
+export declare function appendRecord(store: AuditStore, entry: AuditEntry, options?: AppendOptions): Promise<AuditRecord>;
+export interface ChainVerdict {
+    ok: boolean;
+    checked: number;
+    /** The first record that fails, and how. Absent when the chain holds. */
+    brokenAt?: number;
+    reason?: AuditChainError['code'];
+    message?: string;
+}
+/**
+ * Walk a chain and report the FIRST break.
+ *
+ * First, not all, deliberately. Once a link fails every subsequent digest is
+ * computed over a different predecessor, so everything after it also "fails" —
+ * reporting all of them buries the one that matters under thousands that are
+ * merely downstream of it. The first break is where the edit happened.
+ *
+ * `expectGenesis` distinguishes verifying a whole chain from verifying an
+ * exported slice. A slice legitimately starts mid-chain with a non-genesis
+ * predecessor; a full chain that does not start at genesis has been truncated
+ * from the front, which is exactly the deletion this is meant to catch.
+ */
+export declare function verifyChain(records: readonly AuditRecord[], options?: {
+    digester?: Digester;
+    expectGenesis?: boolean;
+}): Promise<ChainVerdict>;
+export interface AuditExport {
+    realm?: string;
+    fromSequence: number;
+    toSequence: number;
+    /** The link the slice hangs from, so a verifier can attach it to the chain. */
+    anchorDigest: string;
+    records: readonly AuditRecord[];
+    /** Digest over the whole slice — one value to publish or counter-sign. */
+    sealDigest: string;
+    exportedAtMs: number;
+}
+/**
+ * Take a verifiable slice out of the chain.
+ *
+ * Exports carry `anchorDigest` — the digest of the record *before* the slice —
+ * because a slice on its own proves only that those records are consistent with
+ * each other. Somebody who rewrote history could produce an internally perfect
+ * slice. Anchoring it to a digest that was published earlier is what makes the
+ * slice evidence about a specific past rather than about a self-consistent story.
+ *
+ * The export is verified before it is returned. An export that has not been
+ * verified is worse than none: it looks authoritative and nobody re-checks it.
+ */
+export declare function exportRange(store: AuditStore, args: {
+    realm?: string;
+    fromSequence: number;
+    toSequence: number;
+}, options?: AppendOptions): Promise<AuditExport>;
+/**
+ * Check an export against the anchor somebody kept.
+ *
+ * The whole point of publishing a digest is being able to do this later. If the
+ * anchor does not match, the chain was rewritten *after* the anchor was
+ * published — which is the strongest statement this package can make, and the
+ * only one that survives an operator with database access.
+ */
+export declare function verifyExport(slice: AuditExport, options?: {
+    digester?: Digester;
+    expectSealDigest?: string;
+}): Promise<ChainVerdict>;
+/**
+ * The `AuditSink` shape `@forgezero/access/effects` expects, backed by a chain.
+ *
+ * Structural rather than an import, so this package does not depend on `access`
+ * for a five-field interface — and so two copies of `access` in a dependency
+ * tree cannot make an otherwise valid sink unassignable.
+ */
+export interface EffectAuditRecord {
+    route: string;
+    method: string;
+    outcome: 'allowed' | 'denied';
+    status: number;
+    code?: string;
+    userKey?: string;
+    realm?: string;
+    targetKey?: string;
+    atSec: number;
+    detail?: Record<string, unknown>;
+}
+export interface AuditChainOptions extends AppendOptions {
+    store: AuditStore;
+    /** Called when an append fails. Silence here is how a trail dies unnoticed. */
+    onError?: (error: unknown, entry: AuditEntry) => void;
+}
+/**
+ * A chain with appends serialised per realm.
+ *
+ * Serialising is what makes `sequence` mean anything on one node: two appends
+ * that read the same tail would otherwise both claim the same position. Per
+ * realm rather than globally, so one tenant's write rate cannot become another
+ * tenant's latency — the chains are independent and there is no reason to make
+ * them contend.
+ *
+ * This does NOT make appends safe across processes. A unique index on
+ * `(realm, sequence)` in the store is what does that, and it is the store's job
+ * because only the store knows how to express one.
+ */
+export declare function createAuditChain(options: AuditChainOptions): {
+    append: (entry: AuditEntry) => Promise<AuditRecord>;
+    verify: (realm?: string, fromSequence?: number, toSequence?: number) => Promise<ChainVerdict>;
+    export: (args: {
+        realm?: string;
+        fromSequence: number;
+        toSequence: number;
+    }) => Promise<AuditExport>;
+    /**
+     * The `AuditSink` face.
+     *
+     * Never throws and never returns a rejected promise: an effect that fails
+     * the request when the audit store is down converts a logging outage into
+     * an outage, which is the one failure mode `effects` exists to prevent.
+     */
+    sink: {
+        write(record: EffectAuditRecord): void;
+    };
+};
+export type AuditChain = ReturnType<typeof createAuditChain>;
+/**
+ * An in-memory store. Tests and a single-process development run.
+ *
+ * Enforces the unique `(realm, sequence)` constraint that a real store gets from
+ * an index — otherwise a test would pass against this and the same code would
+ * produce duplicate sequences in production.
+ */
+export declare function memoryStore(): AuditStore & {
+    all(realm?: string): AuditRecord[];
+    clear(): void;
+};
+export declare const VERSION = "0.1.0";