@oxy.so/protocol 1.0.0

package/src/__tests__/transparency.test.ts

@@ -0,0 +1,353 @@
+/**
+ * Transparency-log tests — leaf hashing, the Merkle tree, inclusion proofs, and
+ * the co-signable checkpoint.
+ *
+ * These lock the properties a third party depends on when auditing Oxy without
+ * trusting it: a root recomputable from a snapshot in any order, an inclusion
+ * proof verifiable from ONLY the verifier's own leaf (never the full leaf set),
+ * and a checkpoint whose signing bytes are identical for every independent
+ * co-signer (Oxy plus witness nodes).
+ */
+
+import { generateSecp256k1KeyPair } from '../secp256k1';
+import {
+  sha256,
+  transparencyLeafHash,
+  buildTransparencyTree,
+  buildTransparencyTreeFromHeads,
+  inclusionProof,
+  verifyInclusionProof,
+  EMPTY_TRANSPARENCY_ROOT,
+  checkpointSigningInput,
+  checkpointHash,
+  signCheckpoint,
+  verifyCheckpointSignature,
+  type TransparencyHeadEntry,
+  type TransparencyCheckpointFields,
+} from '../index';
+
+const HEAD_A: TransparencyHeadEntry = {
+  subjectDid: 'did:web:oxy.so:u:aaa',
+  seq: 4,
+  headRecordId: 'a'.repeat(64),
+};
+const HEAD_B: TransparencyHeadEntry = {
+  subjectDid: 'did:web:oxy.so:u:bbb',
+  seq: 0,
+  headRecordId: 'b'.repeat(64),
+};
+const HEAD_C: TransparencyHeadEntry = {
+  subjectDid: 'did:web:oxy.so:u:ccc',
+  seq: 17,
+  headRecordId: 'c'.repeat(64),
+};
+
+/** `n` distinct head entries, deterministic. */
+function heads(n: number): TransparencyHeadEntry[] {
+  return Array.from({ length: n }, (_, i) => ({
+    subjectDid: `did:web:oxy.so:u:${String(i).padStart(3, '0')}`,
+    seq: i,
+    headRecordId: String(i).padStart(64, '0'),
+  }));
+}
+
+/**
+ * RFC 6962 §2.1 MTH, transcribed directly from the spec — the independent
+ * oracle the production bottom-up build is checked against.
+ *
+ * `buildTransparencyTree` builds levels iteratively (pair adjacent, carry a
+ * trailing odd node up) because that lets it keep the interior nodes for cheap
+ * proofs. This recursive split-at-the-largest-power-of-two definition is the
+ * normative one, and the equivalence between the two is an assumption the
+ * commitment rests on — so it is TESTED, never assumed.
+ */
+async function rfc6962MerkleTreeHash(leaves: string[]): Promise<string> {
+  if (leaves.length === 0) {
+    return EMPTY_TRANSPARENCY_ROOT;
+  }
+  if (leaves.length === 1) {
+    return leaves[0];
+  }
+  let k = 1;
+  while (k * 2 < leaves.length) {
+    k *= 2;
+  }
+  const [left, right] = await Promise.all([
+    rfc6962MerkleTreeHash(leaves.slice(0, k)),
+    rfc6962MerkleTreeHash(leaves.slice(k)),
+  ]);
+  return sha256(`oxy.transparency.node.v1:${left}${right}`);
+}
+
+describe('transparencyLeafHash', () => {
+  it('is deterministic for the same head', async () => {
+    expect(await transparencyLeafHash(HEAD_A)).toBe(await transparencyLeafHash(HEAD_A));
+  });
+
+  it('changes when seq advances', async () => {
+    const before = await transparencyLeafHash(HEAD_A);
+    const after = await transparencyLeafHash({ ...HEAD_A, seq: HEAD_A.seq + 1 });
+    expect(after).not.toBe(before);
+  });
+
+  it('changes when the head record id changes', async () => {
+    const tampered = await transparencyLeafHash({ ...HEAD_A, headRecordId: 'd'.repeat(64) });
+    expect(tampered).not.toBe(await transparencyLeafHash(HEAD_A));
+  });
+
+  it('changes when the subject changes', async () => {
+    const other = await transparencyLeafHash({ ...HEAD_A, subjectDid: HEAD_B.subjectDid });
+    expect(other).not.toBe(await transparencyLeafHash(HEAD_A));
+  });
+
+  it('is domain-separated, so it is never a bare hash of the concatenated fields', async () => {
+    const bare = await sha256(`${HEAD_A.subjectDid}${HEAD_A.seq}${HEAD_A.headRecordId}`);
+    expect(await transparencyLeafHash(HEAD_A)).not.toBe(bare);
+  });
+});
+
+describe('buildTransparencyTree', () => {
+  it('gives the empty tree a fixed, domain-separated root', async () => {
+    const tree = await buildTransparencyTree([]);
+    expect(tree.treeSize).toBe(0);
+    expect(tree.root).toBe(EMPTY_TRANSPARENCY_ROOT);
+  });
+
+  it('pins the empty root to the hash of its domain string', async () => {
+    // The constant is hard-coded (the hash is async), so this pins it against
+    // an accidental edit: a changed empty root changes every empty checkpoint.
+    expect(EMPTY_TRANSPARENCY_ROOT).toBe(await sha256('oxy.transparency.empty.v1'));
+  });
+
+  it('uses the leaf itself as the root of a single-leaf tree', async () => {
+    const leaf = await transparencyLeafHash(HEAD_A);
+    const tree = await buildTransparencyTree([leaf]);
+    expect(tree.root).toBe(leaf);
+    expect(tree.treeSize).toBe(1);
+  });
+
+  it('hashes a two-leaf tree as one interior node over the ordered pair', async () => {
+    const l0 = await transparencyLeafHash(HEAD_A);
+    const l1 = await transparencyLeafHash(HEAD_B);
+    const tree = await buildTransparencyTree([l0, l1]);
+    expect(tree.root).toBe(await sha256(`oxy.transparency.node.v1:${l0}${l1}`));
+  });
+
+  it('is order-sensitive at the leaf level (swapping two leaves changes the root)', async () => {
+    const l0 = await transparencyLeafHash(HEAD_A);
+    const l1 = await transparencyLeafHash(HEAD_B);
+    const forward = await buildTransparencyTree([l0, l1]);
+    const reversed = await buildTransparencyTree([l1, l0]);
+    expect(reversed.root).not.toBe(forward.root);
+  });
+
+  it('splits an odd tree so the left subtree is the largest power of two below the size', async () => {
+    const l = await Promise.all([HEAD_A, HEAD_B, HEAD_C].map(transparencyLeafHash));
+    const left = await sha256(`oxy.transparency.node.v1:${l[0]}${l[1]}`);
+    const tree = await buildTransparencyTree(l);
+    expect(tree.root).toBe(await sha256(`oxy.transparency.node.v1:${left}${l[2]}`));
+  });
+
+  it('matches the RFC 6962 recursive definition at every size from 0 to 40', async () => {
+    for (let size = 0; size <= 40; size++) {
+      const leaves = await Promise.all(heads(size).map(transparencyLeafHash));
+      const tree = await buildTransparencyTree(leaves);
+      expect(tree.root).toBe(await rfc6962MerkleTreeHash(leaves));
+      expect(tree.levels[0]).toEqual(leaves);
+    }
+  });
+
+  it('keeps the leaf level independent of the caller array', async () => {
+    const leaves = await Promise.all(heads(3).map(transparencyLeafHash));
+    const tree = await buildTransparencyTree(leaves);
+    leaves[0] = 'f'.repeat(64);
+    expect(tree.levels[0][0]).not.toBe('f'.repeat(64));
+  });
+});
+
+describe('buildTransparencyTreeFromHeads', () => {
+  it('sorts by subject did, so the root does not depend on the input order', async () => {
+    const sorted = await buildTransparencyTreeFromHeads([HEAD_A, HEAD_B, HEAD_C]);
+    const shuffled = await buildTransparencyTreeFromHeads([HEAD_C, HEAD_A, HEAD_B]);
+    expect(shuffled.root).toBe(sorted.root);
+    expect(shuffled.treeSize).toBe(3);
+  });
+
+  it('reports the leaf index of each subject so a proof can be served', async () => {
+    const tree = await buildTransparencyTreeFromHeads([HEAD_C, HEAD_A, HEAD_B]);
+    expect(tree.indexBySubject[HEAD_A.subjectDid]).toBe(0);
+    expect(tree.indexBySubject[HEAD_B.subjectDid]).toBe(1);
+    expect(tree.indexBySubject[HEAD_C.subjectDid]).toBe(2);
+  });
+
+  it('rejects a duplicate subject rather than silently committing to one of them', async () => {
+    await expect(buildTransparencyTreeFromHeads([HEAD_A, HEAD_A])).rejects.toThrow(/duplicate/i);
+  });
+});
+
+describe('verifyInclusionProof', () => {
+  it('verifies every leaf of every tree size from 1 to 40', async () => {
+    for (let size = 1; size <= 40; size++) {
+      const entries = heads(size);
+      const tree = await buildTransparencyTreeFromHeads(entries);
+      for (let index = 0; index < size; index++) {
+        const leaf = await transparencyLeafHash(entries[index]);
+        const proof = inclusionProof(tree, index);
+        await expect(
+          verifyInclusionProof({ leaf, index, treeSize: size, proof, root: tree.root }),
+        ).resolves.toBe(true);
+      }
+    }
+  });
+
+  it('verifies from the leaf alone, without the rest of the leaf set', async () => {
+    const entries = heads(7);
+    const tree = await buildTransparencyTreeFromHeads(entries);
+    const proof = inclusionProof(tree, 5);
+    const leaf = await transparencyLeafHash(entries[5]);
+    // Only the verifier's own leaf, its index, the tree size, the path and the
+    // signed root — the full leaf set is never needed.
+    await expect(
+      verifyInclusionProof({ leaf, index: 5, treeSize: 7, proof, root: tree.root }),
+    ).resolves.toBe(true);
+  });
+
+  it('fails when the head record id was tampered with after the checkpoint', async () => {
+    const entries = heads(5);
+    const tree = await buildTransparencyTreeFromHeads(entries);
+    const proof = inclusionProof(tree, 2);
+    const tamperedLeaf = await transparencyLeafHash({ ...entries[2], headRecordId: 'f'.repeat(64) });
+    await expect(
+      verifyInclusionProof({ leaf: tamperedLeaf, index: 2, treeSize: 5, proof, root: tree.root }),
+    ).resolves.toBe(false);
+  });
+
+  it('fails when a chain was rolled back to an earlier seq', async () => {
+    const entries = heads(5);
+    const tree = await buildTransparencyTreeFromHeads(entries);
+    const proof = inclusionProof(tree, 3);
+    const rolledBack = await transparencyLeafHash({ ...entries[3], seq: entries[3].seq - 1 });
+    await expect(
+      verifyInclusionProof({ leaf: rolledBack, index: 3, treeSize: 5, proof, root: tree.root }),
+    ).resolves.toBe(false);
+  });
+
+  it('fails when the proof is replayed at a different index', async () => {
+    const entries = heads(6);
+    const tree = await buildTransparencyTreeFromHeads(entries);
+    const proof = inclusionProof(tree, 1);
+    const leaf = await transparencyLeafHash(entries[1]);
+    await expect(
+      verifyInclusionProof({ leaf, index: 2, treeSize: 6, proof, root: tree.root }),
+    ).resolves.toBe(false);
+  });
+
+  it('fails against the root of a different checkpoint', async () => {
+    const entries = heads(4);
+    const tree = await buildTransparencyTreeFromHeads(entries);
+    const otherTree = await buildTransparencyTreeFromHeads(heads(5));
+    const proof = inclusionProof(tree, 0);
+    const leaf = await transparencyLeafHash(entries[0]);
+    await expect(
+      verifyInclusionProof({ leaf, index: 0, treeSize: 4, proof, root: otherTree.root }),
+    ).resolves.toBe(false);
+  });
+
+  it('fails when the proof path is truncated', async () => {
+    const entries = heads(8);
+    const tree = await buildTransparencyTreeFromHeads(entries);
+    const proof = inclusionProof(tree, 0);
+    await expect(
+      verifyInclusionProof({
+        leaf: await transparencyLeafHash(entries[0]),
+        index: 0,
+        treeSize: 8,
+        proof: proof.slice(0, -1),
+        root: tree.root,
+      }),
+    ).resolves.toBe(false);
+  });
+
+  it('rejects an index outside the tree instead of verifying', async () => {
+    const entries = heads(3);
+    const tree = await buildTransparencyTreeFromHeads(entries);
+    expect(() => inclusionProof(tree, 3)).toThrow(/index/i);
+  });
+});
+
+describe('checkpoint signing', () => {
+  const fields: TransparencyCheckpointFields = {
+    index: 42,
+    periodEnd: 1_800_000_000_000,
+    treeSize: 3,
+    root: 'e'.repeat(64),
+    prevCheckpointHash: '9'.repeat(64),
+  };
+
+  it('produces stable, domain-separated signing bytes', async () => {
+    expect(checkpointSigningInput(fields)).toBe(checkpointSigningInput({ ...fields }));
+    expect(checkpointSigningInput(fields)).toContain('oxy.transparency.checkpoint.v1:');
+  });
+
+  it('does not depend on the key order of the fields object', () => {
+    const reordered: TransparencyCheckpointFields = {
+      prevCheckpointHash: fields.prevCheckpointHash,
+      root: fields.root,
+      treeSize: fields.treeSize,
+      periodEnd: fields.periodEnd,
+      index: fields.index,
+    };
+    expect(checkpointSigningInput(reordered)).toBe(checkpointSigningInput(fields));
+  });
+
+  it('changes the hash when the root changes', async () => {
+    const other = await checkpointHash({ ...fields, root: 'f'.repeat(64) });
+    expect(other).not.toBe(await checkpointHash(fields));
+  });
+
+  it('changes the hash when the previous checkpoint link changes', async () => {
+    const other = await checkpointHash({ ...fields, prevCheckpointHash: '8'.repeat(64) });
+    expect(other).not.toBe(await checkpointHash(fields));
+  });
+
+  it('verifies a signature made by the signer', async () => {
+    const key = generateSecp256k1KeyPair();
+    const signature = await signCheckpoint(fields, key.privateKey);
+    expect(signature.alg).toBe('ES256K-DER-SHA256');
+    expect(signature.publicKey).toBe(key.publicKey);
+    await expect(verifyCheckpointSignature(fields, signature)).resolves.toBe(true);
+  });
+
+  it('rejects a signature once any signed field is altered', async () => {
+    const key = generateSecp256k1KeyPair();
+    const signature = await signCheckpoint(fields, key.privateKey);
+    await expect(
+      verifyCheckpointSignature({ ...fields, treeSize: fields.treeSize + 1 }, signature),
+    ).resolves.toBe(false);
+  });
+
+  it('lets independent co-signers sign the identical bytes, so witnesses need no coordination', async () => {
+    const oxy = generateSecp256k1KeyPair();
+    const witnessOne = generateSecp256k1KeyPair();
+    const witnessTwo = generateSecp256k1KeyPair();
+    const signatures = await Promise.all(
+      [oxy, witnessOne, witnessTwo].map((k) => signCheckpoint(fields, k.privateKey)),
+    );
+    for (const signature of signatures) {
+      await expect(verifyCheckpointSignature(fields, signature)).resolves.toBe(true);
+    }
+    // Distinct signers, distinct signatures, one set of signed bytes.
+    expect(new Set(signatures.map((s) => s.signature)).size).toBe(3);
+  });
+
+  it('does not accept a signature from one checkpoint on the next one', async () => {
+    const key = generateSecp256k1KeyPair();
+    const signature = await signCheckpoint(fields, key.privateKey);
+    const next: TransparencyCheckpointFields = {
+      ...fields,
+      index: fields.index + 1,
+      prevCheckpointHash: await checkpointHash(fields),
+    };
+    await expect(verifyCheckpointSignature(next, signature)).resolves.toBe(false);
+  });
+});

package/src/chain/continuity.ts

@@ -0,0 +1,59 @@
+/**
+ * Chain continuity — the pure "does this record extend the head by exactly one?"
+ * check, with NO storage or crypto dependency.
+ *
+ * This is the single definition of continuity that used to be duplicated in
+ * oxy-api (`verifyChainContinuity`) and the node store (`appendTxn`). The engine
+ * calls it with the head it read from the injected store; a store MAY call it
+ * again inside its atomic append, but the unique-index backstop (surfaced as
+ * `chain_conflict`) is the real race guard.
+ *
+ * v1 envelopes have no chain coordinates, so they always pass (the caller does
+ * not advance a chain for them).
+ */
+
+import type { SignedRecordEnvelope } from '@oxy.so/contracts';
+import type { ChainHead, VerifyOutcome } from './types';
+
+/**
+ * True when `head` represents an actual existing chain (as opposed to `null` or
+ * the "no chain yet" sentinel head a store may return).
+ */
+function hasChain(head: ChainHead | null): head is ChainHead & { headRecordId: string } {
+  return head !== null && head.headRecordId !== null && head.seq >= 0;
+}
+
+/**
+ * Check that `env` validly extends `head`:
+ *
+ *  - **v1** (no chain coordinates): always `{ ok: true }` — v1 records are not
+ *    chained.
+ *  - **no head** (genesis position): only a genesis (`seq === 0`, `prev` null)
+ *    is accepted; anything else is `chain_gap` (it claims to extend a chain that
+ *    does not exist).
+ *  - **head exists**: `env.prev` MUST equal `head.headRecordId` (else
+ *    `chain_fork`, which also covers a re-genesis whose `prev` is `null`), and
+ *    `env.seq` MUST equal `head.seq + 1` (else `bad_seq`).
+ */
+export function checkContinuity(head: ChainHead | null, env: SignedRecordEnvelope): VerifyOutcome {
+  if (env.version !== 2) {
+    return { ok: true };
+  }
+
+  const isGenesis = env.seq === 0 && (env.prev === null || env.prev === undefined);
+
+  if (!hasChain(head)) {
+    if (!isGenesis) {
+      return { ok: false, reason: 'chain_gap' };
+    }
+    return { ok: true };
+  }
+
+  if (env.prev !== head.headRecordId) {
+    return { ok: false, reason: 'chain_fork' };
+  }
+  if (env.seq !== head.seq + 1) {
+    return { ok: false, reason: 'bad_seq' };
+  }
+  return { ok: true };
+}

package/src/chain/engine.ts

@@ -0,0 +1,43 @@
+/**
+ * Chain engine — verify-then-append orchestration.
+ *
+ * The one entry point an app's adapter calls to publish a record: it runs the
+ * full {@link verifyEnvelope} state machine, computes the content address
+ * (`recordId`), and hands the verified envelope to the injected
+ * {@link RecordStore} to persist atomically. The store owns the durable
+ * concurrency backstop (`chain_conflict` on a unique-index collision); the
+ * engine owns the verification + ordering policy.
+ *
+ * Storage and identity are both injected, so the engine has zero knowledge of
+ * Mongo/SQLite, Oxy DIDs, or any app's lexicon — exactly what makes it reusable.
+ */
+
+import type { SignedRecordEnvelope } from '@oxy.so/contracts';
+import { computeRecordId } from '../envelope/recordId';
+import type { VerificationMethodResolver } from '../identity/resolver';
+import { verifyEnvelope, type VerifyOptions } from './verify';
+import type { RecordStore } from './recordStore';
+import type { AppendOutcome } from './types';
+
+/**
+ * Verify `env` and, if it passes, append it to the subject's chain.
+ *
+ * On a verification failure the rejection is returned WITHOUT touching the store.
+ * On success the (engine-computed) `recordId` is passed to `store.append`, whose
+ * own outcome — including the `chain_conflict` backstop on a concurrent-writer
+ * collision — is returned verbatim.
+ */
+export async function verifyAndAppend(
+  store: RecordStore,
+  resolver: VerificationMethodResolver,
+  env: SignedRecordEnvelope,
+  opts: VerifyOptions = {},
+): Promise<AppendOutcome> {
+  const verification = await verifyEnvelope(store, resolver, env, opts);
+  if (!verification.ok) {
+    return verification;
+  }
+
+  const recordId = await computeRecordId(env);
+  return store.append(env.subject, env, recordId);
+}

package/src/chain/recordStore.ts

@@ -0,0 +1,98 @@
+/**
+ * Storage interfaces — the injected persistence the chain engine drives.
+ *
+ * The engine ({@link ./verify}, {@link ./engine}) is storage-agnostic: it owns
+ * the verification state machine and continuity logic, and delegates EVERY read
+ * and write to an injected {@link RecordStore}. An app supplies a store over its
+ * own backend (oxy-api over Mongo `SignedRecord`/`RepoHead`, a node over SQLite,
+ * Mention over its own Mongo) without the engine knowing anything Oxy- or
+ * app-specific.
+ *
+ * All methods are **subject-keyed**: `subject` is the chain's subject DID
+ * (`env.subject`). A store maps that DID to its own primary key (e.g. an Oxy
+ * userId) internally; the engine never sees that mapping.
+ *
+ * ## Concurrency contract
+ *
+ * `append` MUST be atomic (record insert + head advance in one unit) and MUST
+ * translate a duplicate-key collision on the unique `(subject, seq)` /
+ * `recordId` index — i.e. a concurrent writer that already took this `seq` — into
+ * `{ ok: false, reason: 'chain_conflict' }` (Mongo E11000 / SQLite
+ * `SQLITE_CONSTRAINT`). That is the real multi-writer race guard; the engine's
+ * pre-append continuity check is only the fast-path rejection.
+ */
+
+import type { SignedRecordEnvelope } from '@oxy.so/contracts';
+import type { AppendOutcome, ChainHead } from './types';
+
+export interface RecordStore {
+  /** The subject's chain head, or `null` when the subject has no chain yet. */
+  getHead(subject: string): Promise<ChainHead | null>;
+
+  /**
+   * Atomically persist a verified envelope and advance the subject's chain.
+   *
+   * `recordId` is the engine-computed content address (`computeRecordId(env)`).
+   * Implementations MUST surface a duplicate-key collision as `chain_conflict`
+   * (see the concurrency contract above). v1 envelopes (no chain coordinates)
+   * are stored without advancing a chain and SHOULD report `seq: -1`.
+   */
+  append(subject: string, env: SignedRecordEnvelope, recordId: string): Promise<AppendOutcome>;
+
+  /**
+   * The ordered slice of the subject's chain with `seq > sinceSeq`, ascending by
+   * `seq`, capped at `limit`. Only chained (v2) records have a `seq`, so v1 rows
+   * are naturally excluded. Pass `sinceSeq = -1` to start from genesis.
+   */
+  getLogSince(subject: string, sinceSeq: number, limit: number): Promise<SignedRecordEnvelope[]>;
+
+  /**
+   * Resolve a `recordId` cursor to its chain `seq` (so a puller resumes from the
+   * last record it ingested), or `null` when no such record exists.
+   */
+  resolveCursorSeq(subject: string, recordId: string): Promise<number | null>;
+
+  /**
+   * The latest verified envelope for an AtProto-style `(collection, rkey)` key —
+   * the materialized "current" value (last-writer-wins by chain order), or
+   * `null` when no record exists for that key.
+   */
+  materializeCurrent(
+    subject: string,
+    collection: string,
+    rkey: string,
+  ): Promise<SignedRecordEnvelope | null>;
+
+  /**
+   * The `issuedAt` of the latest stored record for the envelope's LOGICAL key —
+   * the monotonicity frontier the engine compares against (replay/rollback
+   * defence). Scoping is the store's policy:
+   *  - v2: per record key (`collection`, `rkey`) — last-writer-wins for THAT key.
+   *  - v1: per `type` (the legacy identity/profile singletons).
+   *
+   * Returns `null` when there is no prior record (the record is the first of its
+   * key, so any `issuedAt` is acceptable).
+   */
+  latestIssuedAtForKey(subject: string, env: SignedRecordEnvelope): Promise<number | null>;
+}
+
+/**
+ * Content-addressed blob storage — the bytes a record's blob refs point at,
+ * keyed by their SHA-256 (`sha256`) content address.
+ *
+ * Separate from {@link RecordStore} because not every app stores blobs in the
+ * same place a record lives (oxy-api identity records carry no blobs; a node
+ * pins them; Mention rehosts to the Oxy CDN). `Uint8Array` rather than Node's
+ * `Buffer` so the interface stays platform-agnostic.
+ */
+export interface BlobStore {
+  /**
+   * Pin `bytes` under their content address `hash`. Implementations MUST validate
+   * that `bytes` actually hash to `hash`, and SHOULD be idempotent (re-pinning
+   * the same hash is a no-op).
+   */
+  putBlob(hash: string, bytes: Uint8Array): Promise<void>;
+
+  /** The bytes of a pinned blob, or `null` when absent. */
+  getBlob(hash: string): Promise<Uint8Array | null>;
+}

package/src/chain/types.ts

@@ -0,0 +1,85 @@
+/**
+ * Chain engine types — the per-subject hash-chain vocabulary.
+ *
+ * A "chain" is a single signer's append-only log of signed-record envelopes
+ * ("personal blockchain": one signer, no consensus/mining), ordered by a
+ * strictly-increasing `seq` with each record's `prev` pointing at the content
+ * address (`recordId`) of the one before it. These types are storage-agnostic:
+ * the engine ({@link ./verify}, {@link ./engine}) drives them over an injected
+ * {@link ./recordStore.RecordStore}, and any app (Oxy identity/civic/node,
+ * Mention posts, …) supplies its own store + resolver.
+ *
+ * The {@link RejectionReason} union is the SINGLE source of truth for every way
+ * an append can fail — it consolidates what used to be three divergent copies
+ * (oxy-api's `EnvelopeRejectionReason`, the node store's `AppendOutcome.reason`,
+ * and the node verifier's `VerifyRejectionReason`). The exact strings match the
+ * ones oxy-api returns today, so API responses are byte-for-byte unchanged.
+ */
+
+/**
+ * The O(1) head pointer of a subject's chain.
+ *
+ * `headRecordId` is the content address of the latest record (`null` only on the
+ * "no chain yet" wire shape); `seq` is its sequence number; `recordCount` is the
+ * total appended so far. A store returns `null` (not a `ChainHead`) when the
+ * subject has no chain — the engine treats both `null` and a `headRecordId:null`
+ * head as "no chain".
+ */
+export interface ChainHead {
+  headRecordId: string | null;
+  seq: number;
+  recordCount: number;
+}
+
+/**
+ * Every way verifying or appending a signed record can be rejected — stable,
+ * machine-readable, and the ONE consolidated union across the protocol.
+ *
+ *  - `invalid_envelope` — the envelope failed the base schema shape.
+ *  - `subject_mismatch` — the envelope's `subject` is not who the caller is
+ *    authorized to write for (an adapter-policy binding, surfaced here so a
+ *    store/adapter can report it on the same channel).
+ *  - `public_key_not_a_current_verification_method` — the issuer is recognized
+ *    (self or custodial) but the signing key is not its current key.
+ *  - `bad_signature` — the signature does not verify against the embedded key.
+ *  - `issued_in_future` — `issuedAt` is beyond the tolerated clock skew.
+ *  - `stale_issued_at` — `issuedAt` is not strictly newer than the latest record
+ *    for the same logical key (replay/rollback defence).
+ *  - `chain_gap` — a non-genesis record claims to extend a chain that has no head.
+ *  - `chain_fork` — `prev` does not match the current head (or a re-genesis).
+ *  - `bad_seq` — `seq` is not exactly `head.seq + 1`.
+ *  - `chain_conflict` — a concurrent writer already took this `seq` (the store's
+ *    unique-index backstop, surfaced from a duplicate-key error).
+ *  - `untrusted_issuer` — the `issuer` is neither the subject nor a recognized
+ *    custodial issuer.
+ */
+export type RejectionReason =
+  | 'invalid_envelope'
+  | 'subject_mismatch'
+  | 'public_key_not_a_current_verification_method'
+  | 'bad_signature'
+  | 'issued_in_future'
+  | 'stale_issued_at'
+  | 'chain_gap'
+  | 'chain_fork'
+  | 'bad_seq'
+  | 'chain_conflict'
+  | 'untrusted_issuer';
+
+/** Verdict of verifying an envelope WITHOUT persisting it. */
+export type VerifyOutcome = { ok: true } | { ok: false; reason: RejectionReason };
+
+/**
+ * Outcome of appending a verified envelope to a chain.
+ *
+ * On success it carries the record's content address (`recordId`) and its chain
+ * `seq` (`-1` for an unchained v1 record, which has no sequence). On failure it
+ * carries the {@link RejectionReason} (a continuity violation or the store's
+ * `chain_conflict` backstop).
+ */
+export type AppendOutcome =
+  | { ok: true; recordId: string; seq: number }
+  | { ok: false; reason: RejectionReason };
+
+/** The `seq` reported for a v1 (unchained) append — it has no sequence. */
+export const UNCHAINED_SEQ = -1;