sealedrecord 0.2.0 → 0.4.0

package/README.md

@@ -1,45 +1,132 @@
 # sealedrecord
 
-Verify a sealed session record without trusting whoever produced it.
+Recomputes the hash chain, signatures, and time receipts of a sealed session record and reports whether it holds, and if not, at which entry it breaks.
 
-A record is one JSON file: a chain of entries where every entry's SHA-256 digest commits to its full content and to the digest before it, an Ed25519 signature per enrolled entry, and optional time receipts. This library recomputes all of it and reports where, if anywhere, the chain breaks. It also matches an audio file to the entry that anchored it, by file bytes or, for uncompressed WAV, by sample bytes alone (a retagged copy still finds its record).
+## Verify in a browser
 
-WebCrypto only. No runtime dependencies. Same bytes in a browser and in Node 20 or later.
+https://juanlentino.github.io/sealedrecord/ is this library served as static files: drop a record, get a reading. The page imports the published npm tarball of the version it names, is rebuilt only by the release workflow, and makes no network request after it loads. The example buttons use the conformance vectors below.
 
-## Use
+## Install and verify
+
+```sh
+npm install sealedrecord
+```
 
 ```js
-import { verifyPackage, verifyReceipts, hashFile, pcmHashFile, findAnchors, findPcmAnchors } from "sealedrecord";
+import { readFileSync } from "node:fs";
+import { verifyPackage, verifyReceipts } from "sealedrecord";
 
-const pkg = JSON.parse(text);
+const pkg = JSON.parse(readFileSync("vectors/record.json", "utf8"));
 const reading = await verifyPackage(pkg);
-// reading.kind: "holds" | "unsealed" | "altered" | "malformed"
+console.log(reading.kind, reading.signed, reading.entries.length);
+// holds true 9
 
 const receipts = await verifyReceipts({ ...pkg, entries: reading.entries });
+console.log(receipts);
+// { total: 9, receipted: 9, verified: 9, problems: [] }
+```
+
+A record that has been changed after sealing breaks at the changed entry. The reading names the entry, what was recomputed, and what the file claimed:
 
-const { sha256 } = await hashFile(file);
-const exact = findAnchors(sha256, reading.entries);
-const byAudio = exact.length ? exact : findPcmAnchors(await pcmHashFile(file), reading.entries);
+```js
+pkg.entries[3].note = "chorus wants a triple";
+const broken = await verifyPackage(pkg);
+console.log(broken.kind, broken.breakSeq);
+// altered 4
+console.log(broken.detail);
+// entry 4 (note) does not match its recorded digest: recomputed c056c813…, recorded a3442bc7…; its content was altered after signing
+console.log(broken.entries.length);
+// 3   (the accepted prefix; nothing after the break is read)
 ```
 
-`docs/FORMAT.md` specifies the record format completely enough to write a second reader from the document alone. `vectors/` holds signed conformance records the test suite runs against; `npm run vectors` regenerates them with fresh keys.
+`reading.kind` is one of four values. `holds`: every digest and signature recomputes and the last entry seals the record. `unsealed`: the chain recomputes but was never sealed. `altered`: the chain fails at `breakSeq`. `malformed`: not a record this reader reads (wrong format tag, no entries, over the size limits).
+
+Matching an audio file to the entry that anchored it:
+
+```js
+import { hashFile, pcmHashFile, findAnchors, findPcmAnchors } from "sealedrecord";
+
+const { sha256 } = await hashFile(file);            // File or Blob
+const exact = findAnchors(sha256, reading.entries);  // same bytes
+const sameAudio = exact.length ? exact : findPcmAnchors(await pcmHashFile(file), reading.entries);
+// findPcmAnchors matches on the WAV sample data alone, so a retagged copy
+// (new metadata chunks, same samples) still finds its entry.
+```
+
+## What this does not do
+
+- No audio analysis, fingerprinting, similarity, or detection of any kind. The sample anchor is a SHA-256 over raw PCM bytes; one sample different, no match.
+- No authorship inference. A verified signature proves that the holder of a key signed an entry. Who holds the key is outside the format.
+- No key management, custody, backup, or revocation. The record carries public keys only.
+- No signing user interface, storage, transport, or network access. The library takes bytes and returns a reading.
+- No verification of timestamp proofs (OpenTimestamps or similar). They may travel in the record; this library does not check them.
+- No reading or writing of C2PA manifests.
+- No sample anchor for compressed audio. Only uncompressed WAV (PCM and IEEE float) has one; other files match by file hash only.
+
+## Specification and background
+
+The normative specification is [docs/FORMAT.md](docs/FORMAT.md). It is written so that a second implementation can be built from the document alone: the digest preimage and its stringification rules, the check order, both anchors byte for byte, the receipt canonical form, limits, and the exact outcomes.
+
+The design the format implements was published before this library existed:
+
+- Provenance Over Detection. SSRN 6402298. https://papers.ssrn.com/abstract=6402298
+- Provenance as Substrate. SSRN 6730343. https://papers.ssrn.com/abstract=6730343
+- Author ORCID: https://orcid.org/0009-0006-8151-5920
 
-## Producing records
+The papers argue for what the format commits to and why; the specification says how. Where they differ, the specification governs this implementation.
 
-The producer half (`buildEvents`, `sealEntry`, `buildPackage`) is included so a second implementation can check its output against a reference. Key custody, storage, and everything around the record are out of scope here.
+## Conformance vectors
 
-## What this does not cover
+`vectors/record.json` is a signed record with three signers, nine entries, receipts on every entry, a derivation link, and anchored audio. `vectors/take.wav` matches entry 2 by file hash; `vectors/take-retagged.wav` has the same samples and an extra metadata chunk, so it matches entry 2 by sample anchor only. `test/vectors.test.js` runs against all three, including a tamper case that must fail at entry 4.
 
-The library reads and produces the record. It deliberately stops there.
+A third-party implementation can run against the same files. That is what makes the format independently implementable rather than defined by whatever this code happens to do. `npm run vectors` regenerates the set with fresh keys; the generator verifies its own output and refuses to write a record that does not hold.
 
-- **Key custody.** Who holds a private key, how it is generated, backed up, or revoked, is the producer's problem. The record carries public keys only.
-- **Identity.** An actor id is an opaque string. The record proves that whoever holds a key signed an entry; binding that key to a person is outside the format.
-- **Timestamp proofs.** OpenTimestamps or similar proofs may ride in `attestations`; this library carries them and does not verify them. Use standard tooling.
-- **Content Credentials.** C2PA manifests embedded in audio files are neither read nor written here. The sample anchor survives them because they live in their own chunks.
-- **Transport and storage.** Nothing here fetches, uploads, or persists. Hand it bytes; it hands back a reading.
-- **Working documents.** Only sealed records are specified. An unsealed session in transit between collaborators is a different document with a different format tag, and this reader rejects it as `malformed` on purpose.
-- **Compressed audio.** The sample anchor is defined for uncompressed WAV only. Anything else has no sample anchor, honestly, and matches by file hash alone.
-- **Any user interface.** Readings are plain objects with human-readable `detail` strings; rendering them is the caller's job.
+## Runtime
+
+- Zero runtime dependencies. One dev dependency (vitest).
+- Requires WebCrypto with SHA-256 and Ed25519: Node 20 or later, or any browser whose `crypto.subtle` implements Ed25519. Where Ed25519 is missing, `hasEd25519()` returns false, `verifyPackage` checks the hash chain only, and the reading carries `signed: false`.
+- Every computation is SHA-256 or Ed25519 over UTF-8 strings or raw bytes, with lowercase hex output, so results do not depend on the runtime. The test suite itself runs under Node.
+- `hashFile` reads the whole file into memory and refuses files over 200 MiB (`MAX_ARTIFACT_BYTES`). That is a limit of this reader, not of the format.
+
+## API
+
+Reading:
+
+- `verifyPackage(pkg)`: recompute the chain and signatures; returns the reading described above.
+- `verifyReceipts(pkg)`: verify time receipts against the key carried in `pkg.attestations`; returns counts and problems.
+- `hashFile(file)`: `{ name, size, sha256 }` of a File or Blob.
+- `pcmHash(arrayBuffer)`: sample anchor of a WAV, or `null` when the buffer is not one this reader understands.
+- `pcmHashFile(file)`: the same from a File or Blob.
+- `findAnchors(sha256, entries)`: entries whose artifact has this file hash.
+- `findPcmAnchors(pcmSha256, entries)`: entries whose artifact has this sample anchor; empty for `null`.
+- `verdictOf(entries, laneId)`: per-track verdict (`pending`, `unverified`, `broken`, `intact`).
+
+Format constants and primitives, for anyone writing their own reader or producer:
+
+- `PKG_FORMAT`: the format tag a record must carry.
+- `GENESIS`: the 64-zero digest the chain starts from.
+- `entryHash(prev, index, entry)`: the entry digest, exactly as the specification defines it.
+- `hhmm(m)`: the display time derived from a session minute; the reader checks it.
+- `receiptCanonical({ sessionId, seq, hash, receivedAt })`: the string a receipt signs.
+- `MAX_ARTIFACT_BYTES`: the file-size limit `hashFile` enforces.
+
+Producing, included as a reference so a second producer can be checked against it:
+
+- `buildEvents(rawEvents, signerFor)`: order, sequence, digest, and sign a list of raw events.
+- `sealEntry({ prev, seq, raw, privateKey })`: one entry onto an existing chain, identical to what `buildEvents` would produce.
+- `buildPackage(lanes, entries, meta, sealedAt, signers, attestations, note)`: the record object.
+- `packageText(...)`: the same, serialized with two-space indentation.
+
+WebCrypto wrappers used throughout, exported so callers hash and sign the same way the reader verifies:
+
+- `sha256Hex(string)`, `signText(privateKey, string)`, `verifyText(publicKey, hexSignature, string)`
+- `generateSigningKey()`, `exportJwk(key)`, `importPublicJwk(jwk)`, `importPrivateJwk(jwk)`, `hasEd25519()`
+
+## Status and license
+
+Version 0.x. The format tag is `sealedrecord/package.v3`; the digest rules have been stable across the tag's history, and the current constants are the ones intended to freeze. 1.0 will mean the format is frozen: any later change to a committed field, the preimage, or the check order gets a new tag, and this reader keeps reading v3.
+
+Apache-2.0. See [CHANGELOG.md](CHANGELOG.md) for what changed and when.
 
 ## Development
 
@@ -48,10 +135,4 @@ npm ci
 npm test
 ```
 
-Releases: bump the version and CHANGELOG, commit, push a `vX.Y.Z` tag. CI publishes to npm through trusted publishing; nothing is published by hand.
-
-To develop against a consuming app without editing its manifest: `npm link` here, then `npm link sealedrecord` in the app. A plain `npm install` there restores the published version.
-
-## License
-
-Apache-2.0.
+Releases are a version bump, a CHANGELOG entry, and a `vX.Y.Z` tag; CI publishes to npm through trusted publishing. To develop against a consuming project without editing its manifest, `npm link` here and `npm link sealedrecord` there.

package/index.js

@@ -3,7 +3,7 @@
 
 export { verifyPackage } from "./src/verify.js";
 export { verifyReceipts, receiptCanonical } from "./src/attest.js";
-export { MAX_ARTIFACT_BYTES, hashFile, fileMatchesArtifact, findAnchors, findPcmAnchors, formatBytes } from "./src/artifact.js";
+export { MAX_ARTIFACT_BYTES, hashFile, findAnchors, findPcmAnchors } from "./src/artifact.js";
 export { pcmHash, pcmHashFile } from "./src/pcm.js";
 export { GENESIS, entryHash, hhmm, verdictOf, buildEvents } from "./src/chain.js";
 export { PKG_FORMAT, buildPackage, packageText } from "./src/pkg.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sealedrecord",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Verify a sealed session record: recompute the SHA-256 chain, check Ed25519 entry signatures and time receipts, and match audio files to their anchors. WebCrypto only, browser and Node.",
   "license": "Apache-2.0",
   "type": "module",

package/src/artifact.js

@@ -1,5 +1,6 @@
 /* Artifact anchoring: the file's SHA-256, computed wherever the reader
-   runs, becomes part of the entry the author signs. The file itself does
+   runs, becomes part of the entry the author signs. formatBytes is exported
+   here for its own test and the cap message; it is not on the public surface. The file itself does
    not travel with the record; the chain holds its identity, the producer
    holds the bytes. */
 /* WebCrypto digests a whole ArrayBuffer in memory — no streaming — so cap
@@ -22,10 +23,6 @@ export const formatBytes = (n) => {
   return `${(n / (1024 * 1024)).toFixed(1)} MB`;
 };
 
-/* Re-check a file someone hands you against an anchored entry. */
-export const fileMatchesArtifact = async (file, artifact) =>
-  (await hashFile(file)).sha256 === artifact.sha256;
-
 /* Every entry that anchors this exact file — the reader's answer to
    "where does this file appear in the session?" */
 export const findAnchors = (sha256, entries) =>

package/src/attest.js

@@ -35,7 +35,7 @@ export const verifyReceipts = async (pkg) => {
       sessionId: pkg.session?.id, seq: e.seq, hash: e.hash, receivedAt: r.received_at,
     })));
     if (ok) out.verified += 1;
-    else out.problems.push(`entry ${e.seq}: receipt does not verify — its time or content claim was altered`);
+    else out.problems.push(`entry ${e.seq}: receipt does not verify; its time or content claim was altered`);
   }
   return out;
 };

package/src/verify.js

@@ -2,14 +2,14 @@
    nothing else: no session state, no crew list, no trust in any field the
    package asserts about itself. It recomputes the whole SHA-256 chain from
    genesis, and where the package carries signers it verifies each enrolled
-   entry's Ed25519 signature — so a forger who rebuilds the hashes still
+   entry's Ed25519 signature, so a forger who rebuilds the hashes still
    fails at the first entry they could not re-sign.
 
    Result kinds:
-     malformed  — not a package this reader can read; `detail` says why
-     altered    — the chain fails at `breakSeq`; `detail` names what failed
-     unsealed   — chain recomputes but the package was never sealed
-     holds      — chain recomputes end to end and the package is sealed */
+     malformed: not a package this reader can read; `detail` says why
+     altered: the chain fails at `breakSeq`; `detail` names what failed
+     unsealed: chain recomputes but the package was never sealed
+     holds: chain recomputes end to end and the package is sealed */
 
 import { GENESIS, entryHash, hhmm, verdictOf } from "./chain.js";
 import { verifyText, importPublicJwk, hasEd25519 } from "./crypto.js";
@@ -85,7 +85,7 @@ export const verifyPackage = async (pkg) => {
     }
     const computed = await entryHash(prev, i, e);
     if (computed !== e.hash) {
-      breakAt = { seq: i + 1, detail: `entry ${i + 1} (${e.action}) does not match its recorded digest — recomputed ${computed.slice(0, 8)}…, recorded ${e.hash.slice(0, 8)}…; its content was altered after signing` };
+      breakAt = { seq: i + 1, detail: `entry ${i + 1} (${e.action}) does not match its recorded digest: recomputed ${computed.slice(0, 8)}…, recorded ${e.hash.slice(0, 8)}…; its content was altered after signing` };
       break;
     }
     if (e.t !== hhmm(e.m)) {