sealedrecord 0.1.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,55 @@
+# sealedrecord
+
+Verify a sealed session record without trusting whoever produced it.
+
+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).
+
+WebCrypto only. No runtime dependencies. Same bytes in a browser and in Node 20 or later.
+
+## Use
+
+```js
+import { verifyPackage, verifyReceipts, hashFile, pcmHashFile, findAnchors, findPcmAnchors } from "sealedrecord";
+
+const pkg = JSON.parse(text);
+const reading = await verifyPackage(pkg);
+// reading.kind: "holds" | "unsealed" | "altered" | "malformed"
+
+const receipts = await verifyReceipts({ ...pkg, entries: reading.entries });
+
+const { sha256 } = await hashFile(file);
+const exact = findAnchors(sha256, reading.entries);
+const byAudio = exact.length ? exact : findPcmAnchors(await pcmHashFile(file), reading.entries);
+```
+
+`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.
+
+## Producing records
+
+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.
+
+## What this does not cover
+
+The library reads and produces the record. It deliberately stops there.
+
+- **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.
+
+## Development
+
+```sh
+npm ci
+npm test
+```
+
+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.

package/docs/FORMAT.md

@@ -0,0 +1,210 @@
+# Sealed record format, version `selo/package.v3`
+
+This document specifies the record completely enough to implement an independent reader. Where it and the reference implementation disagree, the reference implementation is the bug report; the record bytes are the authority.
+
+The format identifier `selo/package.v3` and the receipt tag `selo-receipt.v1` are opaque protocol constants. Readers compare them byte for byte and attach no meaning to them.
+
+## 1. Encoding
+
+A record is one UTF-8 JSON document. All digests and signatures are lowercase hexadecimal strings. All hashing and signing operates on the UTF-8 bytes of the strings described below, never on raw binary except where §6 says so.
+
+## 2. Top level
+
+| Field | Type | Committed | Notes |
+|---|---|---|---|
+| `format` | string | no | Must equal `selo/package.v3`. Anything else is `malformed`. |
+| `note` | string | no | Free text for humans. Readers ignore it. |
+| `session` | object | partly | `id` (optional string), `code`, `title`. Only `id` participates in receipts (§7). |
+| `sealedAt` | string | no | The `t` of the sealing entry. Display only. |
+| `tracks` | array | no | `{ id, name, origin }`. Used only to compute per-track verdicts (§5.4). |
+| `signers` | object | no | Map from actor id to an Ed25519 public JWK (`kty: "OKP"`, `crv: "Ed25519"`, `x`). Optional. |
+| `attestations` | object | no | `{ key, receipts, ... }`, see §7. Optional. |
+| `entries` | array | yes | The chain. 1 to 10000 entries. |
+
+"Committed" means the value participates in an entry digest. Nothing at the top level is committed directly; the chain is committed entry by entry, and the reader believes nothing else in the file.
+
+## 3. Entry
+
+| Field | Type | Required | Committed |
+|---|---|---|---|
+| `seq` | integer | yes | as the zero-based index `seq - 1` |
+| `m` | number | yes | yes |
+| `t` | string | yes | no, but must equal `hhmm(m)` (§4.3) |
+| `room` | string | yes | yes |
+| `lane` | string or null | emitted always | yes |
+| `action` | string | yes | yes |
+| `note` | string | no | yes (absent commits as empty) |
+| `artifact` | object | no | yes (§4.2) |
+| `derivedFrom` | integer | no | yes (absent commits as empty) |
+| `alg` | string | no | yes (absent commits as empty) |
+| `actor` | object | yes | `id` (string or null) and `name` both committed |
+| `prev` | string | yes | yes, as the first preimage component |
+| `hash` | string | yes | the digest; recomputed, never believed |
+| `sig` | string | no | Ed25519 over `hash` (§4.4) |
+
+The reference producer never emits `lane` as undefined; a reader recomputing the digest stringifies whatever it finds (§4.1), so a missing `lane` commits as the text `undefined` and will not match a digest produced with `null`.
+
+## 4. The chain
+
+### 4.1 Digest
+
+```
+GENESIS = 64 ASCII zeros
+prev_0  = GENESIS
+hash_i  = SHA-256( preimage_i )   as lowercase hex
+prev_i  = hash_{i-1}
+```
+
+`preimage_i` is the following components joined with `|` (U+007C), no trailing separator, `i` being the zero-based index:
+
+```
+prev | i | action | lane | actor.id | actor.name | m | room | note' | artifact' | derivedFrom' | alg'
+```
+
+Stringification follows JavaScript template conversion: numbers in shortest decimal form, `null` as the text `null`, `undefined` as the text `undefined`, booleans as `true`/`false`. The primed components use these substitutions:
+
+- `note'`: `note` if present, else empty string.
+- `derivedFrom'`: `derivedFrom` if present, else empty string.
+- `alg'`: `alg` if present, else empty string.
+- `artifact'`: empty string when the entry has no artifact; otherwise `sha256:name:size:pcm'` where `pcm'` is `pcm_sha256` if present else empty. Note the `:` separator inside this component.
+- `actor`: when absent, treated as `{ id: null, name: "unresolved" }`.
+
+Because a pipe or colon inside a field value is not escaped, the format relies on the digest committing to the whole string, not on field boundaries being recoverable from it.
+
+### 4.2 Artifact
+
+```json
+{ "name": "take.wav", "size": 35244, "sha256": "<hex>", "pcm_sha256": "<hex>" }
+```
+
+`sha256` is the SHA-256 of the file's bytes as delivered. `pcm_sha256` is the sample anchor of §6, present only for WAV files the anchor understands. `name` and `size` commit, so a renamed or padded file breaks the entry.
+
+### 4.3 Session clock
+
+`m` is a session-relative minute count. `t` is derived from it and must match or the record is `altered`:
+
+```
+hhmm(m) = pad2(14 + floor(m / 60)) + ":" + pad2(m mod 60)
+```
+
+The 14 is a fixed downbeat, not a time zone. `t` is display; `m` is what is committed. `sealedAt` at the top level is the `t` of the last entry and is not checked.
+
+### 4.4 Signature
+
+An entry whose `actor.id` is a non-empty string is enrolled. When the record carries `signers`, every enrolled entry must carry `sig`, and `signers[actor.id]` must be an importable Ed25519 public JWK, and
+
+```
+Ed25519.verify( signers[actor.id], sig_bytes, UTF8(hash) ) == true
+```
+
+`sig` is the 64-byte signature as 128 hex characters. The signed message is the UTF-8 bytes of the lowercase hex digest string, not the 32 raw digest bytes.
+
+When the record carries no `signers`, or the runtime cannot do Ed25519, signatures are not checked and the reading reports `signed: false`. An unimportable key in `signers` fails every entry by that actor. Reader implementations may need to drop a JWK `alg` member before import; the curve field is authoritative.
+
+### 4.5 Derivation and scheme fields
+
+- `derivedFrom`, when present, must be an integer `1 <= derivedFrom < seq`. It names an earlier entry by `seq`.
+- `alg`, when present, must be `"Ed25519"`. Any other value is `altered` at that entry, since this reader cannot verify it.
+
+## 5. Reading a record
+
+### 5.1 Malformed
+
+Return `{ kind: "malformed", detail }` when: the value is not an object; `format` differs from `selo/package.v3`; `entries` is not a non-empty array; `entries.length > 10000`; `signers` has more than 200 keys.
+
+### 5.2 Walk
+
+Walk `entries` in order with `prev = GENESIS`. Stop at the first entry that fails any check, in this order, and report `{ kind: "altered", breakSeq, detail }` where `breakSeq` is the one-based position:
+
+1. Each of `seq`, `m`, `room`, `action`, `actor`, `prev`, `hash` is present (not undefined).
+2. `actor` is a non-null object.
+3. `seq == index + 1`.
+4. `prev == running prev`.
+5. `derivedFrom`, if present, is an integer in `[1, index]`.
+6. `alg`, if present, is `"Ed25519"`.
+7. Recomputed digest (§4.1) equals `hash`.
+8. `t == hhmm(m)`.
+9. If signatures are being checked and `actor.id` is truthy: `sig` present, key present and importable, signature verifies.
+
+After each accepted entry, set `running prev = hash` and mark the entry `sealed = Boolean(actor.id)`.
+
+Entries after the break are not read. `entries` in the result holds the accepted prefix.
+
+### 5.3 Outcome
+
+If no entry failed: the record is `unsealed` unless the last entry's `action` is exactly `package sealed`, in which case it `holds`.
+
+The result carries `session`, `sealedAt`, `entries` (accepted, with `sealed` added), `tracks`, `verdicts`, `total` (count in the file), and `signed` (whether signatures were checked).
+
+### 5.4 Track verdicts
+
+For each `tracks[i]`, take the accepted entries whose `lane` equals `tracks[i].id` (strict equality; the producer uses the lane string itself as the id). Then:
+
+- no entries: `pending`
+- first entry not sealed: `unverified` (origin unverified)
+- any later entry not sealed: `broken`, with `gap` naming the first such entry
+- otherwise: `intact`
+
+## 6. Anchors
+
+### 6.1 File anchor
+
+`sha256` = SHA-256 over the entire file, lowercase hex. The reference reader refuses files over 200 MiB because it digests in memory; that is a reader limit, not a format rule.
+
+### 6.2 Sample anchor (`pcm_sha256`)
+
+Defined only for RIFF/WAVE files with an uncompressed `fmt ` chunk. Parse the container yourself; do not decode through an audio API.
+
+1. Bytes 0..3 are `RIFF`, bytes 8..11 are `WAVE`, file is at least 12 bytes. Otherwise: no anchor.
+2. From offset 12, read chunks: 4-byte id, 4-byte little-endian size, body. If `body + size` exceeds the file: no anchor. Advance by `8 + size + (size mod 2)`; odd bodies are padded.
+3. `fmt ` chunk: size at least 16; format tag (u16 LE at body+0) is 1 (PCM) or 3 (IEEE float), otherwise no anchor. Read `channels` (u16 LE at body+2), `rate` (u32 LE at body+4), `bits` (u16 LE at body+14).
+4. `data` chunk: the body bytes, exactly `size` long.
+5. If more than one `fmt ` or `data` chunk appears, the last one read wins.
+6. Both chunks required, else no anchor.
+7. Anchor = SHA-256 over `UTF8("pcm|" + channels + "|" + rate + "|" + bits + "|")` followed by the `data` body bytes, lowercase hex.
+
+Any parse failure yields no anchor (`null`), never an error. Metadata chunks (`LIST`, `bext`, `id3 `) do not participate, so retagging leaves the anchor unchanged; a transcode or resample changes it.
+
+### 6.3 Matching
+
+`findAnchors(sha256, entries)` returns every entry whose `artifact.sha256` equals the file hash. `findPcmAnchors(pcm, entries)` returns every entry whose `artifact.pcm_sha256` equals the sample anchor, and returns nothing for a null anchor. A reader shows an exact-bytes match and a samples-only match differently; the second means the delivered file is not the anchored file, only the same audio.
+
+## 7. Time receipts
+
+`attestations` is metadata about the chain, never part of it. A record with none still verifies.
+
+```json
+"attestations": {
+  "key": { "kty": "OKP", "crv": "Ed25519", "x": "..." },
+  "receipts": [ { "seq": 1, "received_at": "2026-08-14T18:05:00.000Z", "sig": "<hex>" } ]
+}
+```
+
+A receipt for entry `seq` is valid when
+
+```
+Ed25519.verify( attestations.key, sig_bytes, UTF8(canonical) ) == true
+canonical = "selo-receipt.v1|" + session.id + "|" + seq + "|" + hash + "|" + received_at
+```
+
+with `hash` taken from the entry (verify the chain first; receipts vouch for time, not content) and `session.id` stringified as in §4.1 (a missing id commits as `undefined`). Drop any JWK `alg` member before importing `attestations.key`.
+
+The reader reports `total` entries, `receipted` (entries with a receipt), `verified`, and a `problems` list. Entries without a receipt are not a problem. An unimportable key is one problem and no receipts verify.
+
+What a receipt proves: the holder of `attestations.key` saw this hash at this time. It is as strong as trust in that key and its clock, no stronger. Other attestation members (for example OpenTimestamps proofs) may ride alongside; this specification does not verify them.
+
+## 8. Producing a record
+
+A conforming producer sorts raw events by `m` ascending, assigns `seq` from 1, derives `t`, computes each digest per §4.1, signs each enrolled entry's digest with that actor's private key, and serialises exactly the fields listed in §2 and §3, omitting optional fields that are absent rather than emitting `null`. The last entry of a finished record has `action` equal to `package sealed`.
+
+## 9. Limits and refusals
+
+| Limit | Value | Result |
+|---|---|---|
+| entries | 1..10000 | `malformed` outside |
+| signers | at most 200 | `malformed` above |
+| file anchor input | reader policy, 200 MiB in the reference | error, not a reading |
+
+## 10. Test vectors
+
+`vectors/` in this repository holds a signed record that `holds`, a WAV that matches an entry by file hash, and a retagged copy of the same WAV that matches only by sample anchor. `npm run vectors` regenerates them with fresh keys; the digests change, the structure does not.

package/index.js

@@ -0,0 +1,14 @@
+/* The public surface. Reading first; the producer half follows so a second
+   implementation can check its output against a reference. */
+
+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 { 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";
+export { sealEntry } from "./src/append.js";
+export {
+  sha256Hex, generateSigningKey, exportJwk, importPublicJwk, importPrivateJwk,
+  signText, verifyText, hasEd25519,
+} from "./src/crypto.js";

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "sealedrecord",
+  "version": "0.1.1",
+  "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",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "docs/FORMAT.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "vectors": "node scripts/build-vectors.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juanlentino/sealedrecord.git"
+  },
+  "keywords": [
+    "provenance",
+    "hash-chain",
+    "ed25519",
+    "sha-256",
+    "webcrypto",
+    "verification",
+    "audio"
+  ],
+  "devDependencies": {
+    "vitest": "^4.1.11"
+  }
+}

package/src/append.js

@@ -0,0 +1,17 @@
+/* Chain continuation: seal one new entry onto a live chain without
+   rebuilding from genesis. Produces exactly what buildEvents would have —
+   the reader cannot tell a continued chain from a rebuilt one, which the
+   round-trip test proves. */
+
+import { entryHash, hhmm } from "./chain.js";
+import { signText } from "./crypto.js";
+
+export const sealEntry = async ({ prev, seq, raw, privateKey = null }) => {
+  const actor = raw.actor || { id: null, name: "unresolved" };
+  const sealed = Boolean(actor.id);
+  const base = { ...raw, actor, seq, t: hhmm(raw.m ?? 0), sealed, prev };
+  const hash = await entryHash(prev, seq - 1, base);
+  let sig;
+  if (sealed && privateKey) sig = await signText(privateKey, hash);
+  return { ...base, hash, ...(sig ? { sig } : {}) };
+};

package/src/artifact.js

@@ -0,0 +1,38 @@
+/* Artifact anchoring: the file's SHA-256, computed wherever the reader
+   runs, becomes part of the entry the author signs. 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
+   loudly rather than letting a 2GB session bounce freeze the tab. */
+export const MAX_ARTIFACT_BYTES = 200 * 1024 * 1024;
+
+const HEX = (buf) => [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+
+export const hashFile = async (file) => {
+  if (file.size > MAX_ARTIFACT_BYTES) {
+    throw new Error(`file too large to anchor (${formatBytes(file.size)}; the cap is ${formatBytes(MAX_ARTIFACT_BYTES)})`);
+  }
+  const digest = await crypto.subtle.digest("SHA-256", await file.arrayBuffer());
+  return { name: file.name, size: file.size, sha256: HEX(digest) };
+};
+
+export const formatBytes = (n) => {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  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) =>
+  entries.filter((e) => e.artifact?.sha256 === sha256);
+
+/* The survivability half of the same question: entries whose anchored
+   AUDIO matches, even though the file's bytes no longer do — a retagged
+   copy finds its record here. Null/absent hashes match nothing. */
+export const findPcmAnchors = (pcmSha256, entries) =>
+  pcmSha256 ? entries.filter((e) => e.artifact?.pcm_sha256 === pcmSha256) : [];

package/src/attest.js

@@ -0,0 +1,41 @@
+/* The reader's side of time attestation. Receipts are a server's signed
+   statement "I received the entry with this hash at this time", verifiable
+   against the attestation key the record carries, but only as strong as
+   trust in that server's clock and key custody. Timestamp proofs
+   (OpenTimestamps) are the trustless layer; they travel in the record for
+   standard tooling and are not verified here. Attestations are metadata
+   ABOUT the chain, never part of it: a record with none still verifies. */
+
+import { importPublicJwk, verifyText } from "./crypto.js";
+
+/* The signing side must byte-match this canonical form. */
+export const receiptCanonical = ({ sessionId, seq, hash, receivedAt }) =>
+  `selo-receipt.v1|${sessionId}|${seq}|${hash}|${receivedAt}`;
+
+export const verifyReceipts = async (pkg) => {
+  const entries = pkg.entries ?? [];
+  const out = { total: entries.length, receipted: 0, verified: 0, problems: [] };
+  const att = pkg.attestations;
+  if (!att?.key || !Array.isArray(att.receipts)) return out;
+
+  let key;
+  try {
+    key = await importPublicJwk({ ...att.key, alg: undefined });
+  } catch {
+    out.problems.push("the attestation key in this package is not importable");
+    return out;
+  }
+
+  const bySeq = new Map(att.receipts.map((r) => [r.seq, r]));
+  for (const e of entries) {
+    const r = bySeq.get(e.seq);
+    if (!r) continue;
+    out.receipted += 1;
+    const ok = r.sig && (await verifyText(key, r.sig, receiptCanonical({
+      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`);
+  }
+  return out;
+};

package/src/chain.js

@@ -0,0 +1,68 @@
+/* Chain projections. The event log is the single source of truth; everything
+   here derives from it and holds no state of its own.
+
+   Every entry's digest is SHA-256 over its full content plus its
+   predecessor's digest, and an enrolled actor's entry is signed Ed25519
+   over that digest. Identity custody lives outside the record. */
+
+import { sha256Hex, signText } from "./crypto.js";
+
+export const GENESIS = "0".repeat(64);
+/* Canonical entry digest (format v3). Every content field is committed, so
+   altering any of them after the fact breaks the chain at exactly that
+   entry, including the anchored artifact: its file hash, name, size, and
+   (when the audio is uncompressed) its PCM hash all commit, so neither
+   the file, its name, nor the samples themselves can be swapped. v3 also
+   commits the derivation link (`derivedFrom`, an earlier entry's seq) and
+   the reserved signature-scheme field (`alg`; absent means Ed25519).
+   The reader recomputes this same function over a package it is handed.
+   v2 never shipped; clean break,
+   same as v1→v2. */
+export const entryHash = (prev, i, e) => {
+  const actor = e.actor || { id: null, name: "unresolved" };
+  const artifact = e.artifact
+    ? `${e.artifact.sha256}:${e.artifact.name}:${e.artifact.size}:${e.artifact.pcm_sha256 ?? ""}`
+    : "";
+  return sha256Hex(
+    `${prev}|${i}|${e.action}|${e.lane}|${actor.id}|${actor.name}|${e.m}|${e.room}|${e.note ?? ""}|${artifact}|${e.derivedFrom ?? ""}|${e.alg ?? ""}`,
+  );
+};
+
+/* Session-relative clock from a 14:00 downbeat. Skeleton-stage: positions
+   inside one session. Real wall-clock timestamps arrive with persistence. */
+export const hhmm = (m) =>
+  `${String(14 + Math.floor(m / 60)).padStart(2, "0")}:${String(m % 60).padStart(2, "0")}`;
+
+/* Adds seq, t, sealed, prev, hash, and — when the actor has a signing key —
+   an Ed25519 signature over the entry's digest. Derives defensively: events
+   are sorted by session time first, and an actor without an identifier is a
+   recorded gap, never an error. Sequential by construction: each digest
+   commits to the one before it. */
+export const buildEvents = async (rawEvents, signerFor = null) => {
+  const ordered = [...rawEvents].sort((a, b) => (a.m ?? 0) - (b.m ?? 0));
+  let prev = GENESIS;
+  const out = [];
+  for (let i = 0; i < ordered.length; i++) {
+    const e = ordered[i];
+    const actor = e.actor || { id: null, name: "unresolved" };
+    const sealed = Boolean(actor.id);
+    const hash = await entryHash(prev, i, { ...e, actor });
+    let sig;
+    if (sealed && signerFor) {
+      const key = signerFor(actor.id);
+      if (key) sig = await signText(key, hash);
+    }
+    out.push({ ...e, actor, seq: i + 1, t: hhmm(e.m ?? 0), sealed, prev, hash, ...(sig ? { sig } : {}) });
+    prev = hash;
+  }
+  return out;
+};
+
+export const verdictOf = (events, laneId) => {
+  const own = events.filter((e) => e.lane === laneId);
+  if (!own.length) return { key: "pending", label: "no events" };
+  if (!own[0].sealed) return { key: "unverified", label: "origin unverified" };
+  const gap = own.find((e) => !e.sealed);
+  if (gap) return { key: "broken", label: "chain broken", gap };
+  return { key: "intact", label: "chain intact" };
+};

package/src/crypto.js

@@ -0,0 +1,45 @@
+/* SHA-256 for entry digests, Ed25519 for per-actor signatures, via
+   WebCrypto. Signing happens on the producer's side, always; a store that
+   holds chains can never forge them. Keys are generated extractable so a
+   caller can persist them. On a runtime without Ed25519 the chain runs
+   hash-only and records carry no signers. */
+const HEX = (buf) => [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+const ENC = new TextEncoder();
+const ED = { name: "Ed25519" };
+
+export const sha256Hex = async (s) =>
+  HEX(await crypto.subtle.digest("SHA-256", ENC.encode(s)));
+
+export const generateSigningKey = () =>
+  crypto.subtle.generateKey(ED, true, ["sign", "verify"]);
+
+export const exportJwk = (key) => crypto.subtle.exportKey("jwk", key);
+
+export const importPrivateJwk = (jwk) =>
+  crypto.subtle.importKey("jwk", jwk, ED, true, ["sign"]);
+
+export const importPublicJwk = (jwk) =>
+  crypto.subtle.importKey("jwk", jwk, ED, true, ["verify"]);
+
+export const signText = async (privateKey, s) =>
+  HEX(await crypto.subtle.sign(ED, privateKey, ENC.encode(s)));
+
+export const verifyText = async (publicKey, signatureHex, s) => {
+  const bytes = signatureHex.match(/.{2}/g);
+  if (!bytes) return false;
+  const sig = new Uint8Array(bytes.map((h) => parseInt(h, 16)));
+  return crypto.subtle.verify(ED, publicKey, sig, ENC.encode(s));
+};
+
+let edSupport = null;
+export const hasEd25519 = async () => {
+  if (edSupport === null) {
+    try {
+      await generateSigningKey();
+      edSupport = true;
+    } catch {
+      edSupport = false;
+    }
+  }
+  return edSupport;
+};

package/src/pcm.js

@@ -0,0 +1,54 @@
+/* The PCM secondary anchor: a hash of the audio's sample data plus the
+   parameters needed to play it — not the file's bytes. Retagging a WAV
+   (cover art, INFO chunks, bext) changes the file hash; it cannot change
+   this one. Deterministic by construction: we parse the container
+   ourselves, byte for byte — no Web Audio, no decoder variance — so the
+   same recording hashes the same in every browser. Uncompressed WAV
+   (PCM and IEEE float) only in phase 1; anything else is null, honestly. */
+
+const HEX = (buf) => [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+
+const fourcc = (view, at) =>
+  String.fromCharCode(view.getUint8(at), view.getUint8(at + 1), view.getUint8(at + 2), view.getUint8(at + 3));
+
+/* Returns the hex SHA-256 of "pcm|channels|rate|bits|" + data bytes, or
+   null when the buffer is not a WAV this phase understands. */
+export const pcmHash = async (buffer) => {
+  try {
+    const view = new DataView(buffer);
+    if (view.byteLength < 12 || fourcc(view, 0) !== "RIFF" || fourcc(view, 8) !== "WAVE") return null;
+
+    let fmt = null;
+    let data = null;
+    let at = 12;
+    while (at + 8 <= view.byteLength) {
+      const id = fourcc(view, at);
+      const size = view.getUint32(at + 4, true);
+      const body = at + 8;
+      if (body + size > view.byteLength) return null; /* truncated chunk */
+      if (id === "fmt ") {
+        if (size < 16) return null;
+        const format = view.getUint16(body, true);
+        if (format !== 1 && format !== 3) return null; /* PCM & IEEE float only, for now */
+        fmt = {
+          channels: view.getUint16(body + 2, true),
+          rate: view.getUint32(body + 4, true),
+          bits: view.getUint16(body + 14, true),
+        };
+      }
+      if (id === "data") data = new Uint8Array(buffer, body, size);
+      at = body + size + (size % 2); /* RIFF pads odd chunks */
+    }
+    if (!fmt || !data) return null;
+
+    const prefix = new TextEncoder().encode(`pcm|${fmt.channels}|${fmt.rate}|${fmt.bits}|`);
+    const material = new Uint8Array(prefix.length + data.length);
+    material.set(prefix, 0);
+    material.set(data, prefix.length);
+    return HEX(await crypto.subtle.digest("SHA-256", material));
+  } catch {
+    return null;
+  }
+};
+
+export const pcmHashFile = async (file) => pcmHash(await file.arrayBuffer());

package/src/pkg.js

@@ -0,0 +1,41 @@
+/* Sealed-record serialization. The record is what leaves the room: the
+   sealed prefix of the log, the track labels, the signers' public keys,
+   and nothing else. Derived fields (sealed, verdicts) are deliberately
+   absent; the reader re-derives them and takes nothing in the file at its
+   word. */
+
+/* v3: artifact commits gain the PCM secondary anchor, and entries commit
+   derivation links (derivedFrom) and the reserved signature-scheme field
+   (alg). v1 and v2 never shipped; no legacy records to honor. */
+export const PKG_FORMAT = "selo/package.v3";
+
+/* Free text for humans, never committed, never read by a verifier. */
+export const DEFAULT_NOTE = "Sealed record: SHA-256 chain digests, Ed25519 entry signatures. Attestations (time receipts, timestamp proofs) are metadata about the chain, never part of it.";
+
+export const buildPackage = (lanes, sealedEvents, meta, sealedAt, signers = null, attestations = null, note = DEFAULT_NOTE) => ({
+  format: PKG_FORMAT,
+  note,
+  session: { ...(meta.id ? { id: meta.id } : {}), code: meta.code, title: meta.title },
+  sealedAt,
+  tracks: lanes.map((l) => ({ id: l.id, name: l.name, origin: l.origin })),
+  ...(signers && Object.keys(signers).length ? { signers } : {}),
+  ...(attestations ? { attestations } : {}),
+  entries: sealedEvents.map((e) => ({
+    seq: e.seq, m: e.m, t: e.t, room: e.room, lane: e.lane, action: e.action,
+    ...(e.note ? { note: e.note } : {}),
+    ...(e.artifact ? {
+      artifact: {
+        name: e.artifact.name, size: e.artifact.size, sha256: e.artifact.sha256,
+        ...(e.artifact.pcm_sha256 ? { pcm_sha256: e.artifact.pcm_sha256 } : {}),
+      },
+    } : {}),
+    ...(e.derivedFrom ? { derivedFrom: e.derivedFrom } : {}),
+    ...(e.alg ? { alg: e.alg } : {}),
+    actor: { id: e.actor.id, name: e.actor.name },
+    prev: e.prev, hash: e.hash,
+    ...(e.sig ? { sig: e.sig } : {}),
+  })),
+});
+
+export const packageText = (lanes, sealedEvents, meta, sealedAt, signers = null, attestations = null, note = DEFAULT_NOTE) =>
+  JSON.stringify(buildPackage(lanes, sealedEvents, meta, sealedAt, signers, attestations, note), null, 2);

package/src/verify.js

@@ -0,0 +1,125 @@
+/* The independent reader's logic. It is handed a parsed package object and
+   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
+   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 */
+
+import { GENESIS, entryHash, hhmm, verdictOf } from "./chain.js";
+import { verifyText, importPublicJwk, hasEd25519 } from "./crypto.js";
+import { PKG_FORMAT } from "./pkg.js";
+
+const FIELDS = ["seq", "m", "room", "action", "actor", "prev", "hash"];
+const MAX_ENTRIES = 10000;
+const MAX_SIGNERS = 200; /* a session has a handful of members; this is hostile input */
+
+const malformed = (detail) => ({ kind: "malformed", detail });
+
+export const verifyPackage = async (pkg) => {
+  if (!pkg || typeof pkg !== "object") return malformed("not a JSON object");
+  if (pkg.format !== PKG_FORMAT) {
+    return malformed(`unknown format ${JSON.stringify(pkg.format ?? null)}; this reader reads ${PKG_FORMAT}`);
+  }
+  if (!Array.isArray(pkg.entries) || pkg.entries.length === 0) {
+    return malformed("the package carries no entries");
+  }
+  if (pkg.entries.length > MAX_ENTRIES) {
+    return malformed(`the package carries more than ${MAX_ENTRIES} entries; refusing to process it`);
+  }
+
+  /* Import signer keys, if the package carries any and the runtime can.
+     Null prototype: signer ids are attacker-controlled strings. */
+  const keys = Object.create(null);
+  const signers = pkg.signers && typeof pkg.signers === "object" ? pkg.signers : null;
+  if (signers && Object.keys(signers).length > MAX_SIGNERS) {
+    return malformed(`the package carries more than ${MAX_SIGNERS} signer keys; refusing to process it`);
+  }
+  const checkSigs = Boolean(signers) && (await hasEd25519());
+  if (checkSigs) {
+    for (const [id, jwk] of Object.entries(signers)) {
+      try {
+        keys[id] = await importPublicJwk(jwk);
+      } catch { /* an unimportable key simply fails that signer's entries below */ }
+    }
+  }
+
+  /* Re-derive what the session derived; trust nothing carried. */
+  const entries = [];
+  let prev = GENESIS;
+  let breakAt = null;
+  for (let i = 0; i < pkg.entries.length; i++) {
+    const e = pkg.entries[i];
+    const missing = FIELDS.find((f) => e?.[f] === undefined);
+    if (missing !== undefined) {
+      breakAt = { seq: i + 1, detail: `entry ${i + 1} is missing its ${missing} field` };
+      break;
+    }
+    if (e.actor === null || typeof e.actor !== "object") {
+      breakAt = { seq: i + 1, detail: `entry ${i + 1} carries no actor; every entry names who acted` };
+      break;
+    }
+    if (e.seq !== i + 1) {
+      breakAt = { seq: i + 1, detail: `entry ${i + 1} carries sequence number ${e.seq}; entries have been reordered or removed` };
+      break;
+    }
+    if (e.prev !== prev) {
+      breakAt = { seq: i + 1, detail: `entry ${i + 1} chains from ${e.prev.slice(0, 8)}…, but the preceding entry resolves to ${prev.slice(0, 8)}…; the chain does not connect here` };
+      break;
+    }
+    /* v3: a derivation link may only point at an earlier entry. */
+    if (e.derivedFrom !== undefined
+      && (!Number.isInteger(e.derivedFrom) || e.derivedFrom < 1 || e.derivedFrom > i)) {
+      breakAt = { seq: i + 1, detail: `entry ${i + 1} claims derivation from entry ${e.derivedFrom}, which is not an earlier entry in this chain` };
+      break;
+    }
+    /* v3: the signature-scheme field is reserved; this reader speaks Ed25519. */
+    if (e.alg !== undefined && e.alg !== "Ed25519") {
+      breakAt = { seq: i + 1, detail: `entry ${i + 1} is signed with ${e.alg}, a scheme this reader does not support yet` };
+      break;
+    }
+    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` };
+      break;
+    }
+    if (e.t !== hhmm(e.m)) {
+      breakAt = { seq: i + 1, detail: `entry ${i + 1} displays time ${e.t} but its committed position resolves to ${hhmm(e.m)}; the displayed time was altered` };
+      break;
+    }
+    if (checkSigs && e.actor?.id) {
+      const key = keys[e.actor.id];
+      if (!e.sig || !key) {
+        breakAt = { seq: i + 1, detail: `entry ${i + 1} carries the identifier ${e.actor.id} but no verifiable signature; an enrolled entry must be signed` };
+        break;
+      }
+      if (!(await verifyText(key, e.sig, e.hash))) {
+        breakAt = { seq: i + 1, detail: `entry ${i + 1} (${e.action}) fails signature verification: the chain was rebuilt without ${e.actor.name}'s key` };
+        break;
+      }
+    }
+    entries.push({ ...e, sealed: Boolean(e.actor.id) });
+    prev = e.hash;
+  }
+
+  const tracks = Array.isArray(pkg.tracks) ? pkg.tracks : [];
+  const verdicts = tracks.map((tr) => ({
+    track: tr, verdict: verdictOf(entries, tr.id),
+  }));
+  const base = {
+    session: pkg.session ?? {}, sealedAt: pkg.sealedAt ?? null,
+    entries, tracks, verdicts, total: pkg.entries.length,
+    signed: checkSigs,
+  };
+
+  if (breakAt) return { kind: "altered", breakSeq: breakAt.seq, detail: breakAt.detail, ...base };
+  if (entries[entries.length - 1].action !== "package sealed") {
+    return { kind: "unsealed", detail: "the chain recomputes, but the package was never sealed; nothing attests that this is a delivered record", ...base };
+  }
+  return { kind: "holds", ...base };
+};