@real-life/trust-protocol 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 0.4.0
+
+- `createHolder`: one person's device state behind typed human acts
+  (`{when, actId}`, journaled), `receive`, `report`, `resume` and `tick`,
+  with the views `contacts`, `contact`, `groups`, `profile`, `prompts`,
+  `deliveryStatus` and `subscribe`. Results are a closed union with rule
+  references; events are a closed union, issued after the commit.
+- Ports: `Store` (compare-and-swap), `KeyProvider` (`seedKeys` by default),
+  `Entropy` by closed purpose, `Log`, `Access`, `RetryPolicy`,
+  `DeliveryReport`, pure-JSON `Outbound`. `storeContract` is the suite a
+  Store adapter passes.
+- Modules on the holder: identity (the register, device names, the
+  community anchor's rotation over the Log port), trust (the trust act and
+  the classes, the anchor mapping, the star and the group star, merge,
+  split and departure, continuity, `profile@1`, the duties), encounter
+  (`encounter-scan@0.25` with both paths), membership (founding, prelude,
+  invite, admission, welcome, `vouch@2`) and introduction (Trust §8, three
+  roles).
+- Delivery: stages 1–9 once per envelope through a task register, the
+  completed-effect cache with stored acks, the outbox with the status
+  trias, retry by backoff, give-up at the horizon.
+- State codec 1 with golden fixtures (`test/fixtures/`) and a
+  non-normative JSON Schema (`schemas/holder-state-v1.schema.json`) with
+  the generated type `HolderStateV1`; a newer codec is `codec-newer`, a
+  codec without a validator `codec-unknown`.
+- Entry points: the root, `./testing`, `./internal`,
+  `./adapters/vti-mediator`. `visibility` and `ceremony` carry pure wire
+  builders and verifiers only. There is no `./probe` entry point.
+- Invariant predicates over every commit (`invariants: true`) and a
+  generator over random sequences of acts on two and three holders.

package/README.md

@@ -5,14 +5,18 @@ encounters between people: two humans meet, recognize each other, and record
 that recognition as verifiable credentials. Cryptography proves freshness and
 authorship; only a human can witness a human.
 
-This package is the **executable form of the specification** — it lives beside
-the schemas and the test vectors it must reproduce byte-for-byte. Published by
-the [Real Life Organisation](https://real-life.org) under CC BY 4.0.
-
-- Specification, schemas and vectors: <https://rltp.real-life.org>
-- Zero dependencies. WebCrypto only (Ed25519, X25519, HKDF, AES-256-GCM).
-- Works in browsers, Node ≥ 20, Deno, Bun. No DOM, no storage, no network:
-  the library computes and verifies, the host decides where bytes live.
+This package is the reference library of the specification. It lives beside
+the schemas and the test vectors it reproduces byte for byte. Published by the
+[Real Life Organisation](https://real-life.org) under CC BY 4.0.
+
+- Specification, schemas and vectors: <https://trust-protocol.real-life.org>
+- Zero runtime dependencies. WebCrypto only (Ed25519, X25519, HKDF,
+  AES-256-GCM, SHA-256), with one scoped exception: a synchronous SHA-256
+  (`sha256.ts`) digests local reconciliation views inside synchronous state
+  transitions (the star and the group star). It never touches wire bytes,
+  keys or MACs.
+- No DOM, no storage, no network: the holder computes and verifies, the app
+  stores its state and carries its envelopes.
 
 ## Install
 
@@ -20,92 +24,197 @@ the [Real Life Organisation](https://real-life.org) under CC BY 4.0.
 npm i @real-life/trust-protocol
 ```
 
-## The modules mirror the specification
-
-Each module answers to one document, so a reader of the spec knows where to
-look in the code:
+## The holder
 
-| Module | Specification | What it carries |
-|---|---|---|
-| `core` | across all layers | The canonical form: JCS serialization, multibase encodings, digest equality over *decoded* bytes, whole-second timestamps, calendar validity — and the JSON-Schema subset validator the conformance runner uses. |
-| `crypto` | — (primitives) | Hashes, HKDF, key pairs, did:key and multikey renderings, ECDH, and the eddsa-jcs-2022 Data Integrity proof every layer signs with. Answers *how*, never *what*. |
-| `identity` | Identity Layer | One root seed, every context derived — community anchor, pair anchor per relationship, member anchor per group. Contexts never link without their holder's deliberate act. |
-| `encounter` | Encounter Layer | The ceremony under fresh-always pair anchors: challenges, contact cards, the enactment binding both sides compute independently, encounter credentials. |
-| `delivery` | Delivery Contract | The sealed envelope, and the receive chain in its declared order — size bound *before* decryption, envelope form, decryption, parse and digest over the canonical form, completed-effect cache. |
-| `carrier-identity` | Identity §7a | The carrier-relationship principal: one Ed25519 control key per (relationship × carrier), derived so that no computable relation to the relationship's other principals or its `rkid` exists — which is why registration must *prove* the binding instead of computing it. |
-| `carrier` | Delivery §4.4 + §5a | The carrier side of the port as one transport-agnostic state machine: the five guarantees, the proof rule, the total binding lifecycle (unbound → live → closing → released), the verdict sets in their normative evaluation orders, wind-up and binding tombstones. The clock is injected. |
-| `holder` | Delivery §5a + Identity §9.3 | The holder's half: proof construction for all four purposes, the closed verdict set, and the two-exchange recovery flow for a lost carrier entry. |
-| `visibility` | Network Visibility 0.29 on Delivery 0.79 | The trust act (`anchor-mapping@2` + `grade-declaration@1`), the blinded star (`star@1`, 5.2a chunks), the admission layer and the 5.4 reconciliation automaton, §6a continuity (probe + mapping — chains instead of duplicates), and the deniable `delivery-ack/0.1`. Namespaced: `visibility.trust`, `.continuity`, `.acks`. Graduated from `/probe` on 04.09.2026 after a 39-round conformance loop. |
-| `ceremony` | Encounter 0.29 (`encounter-scan@0.25`) on Delivery 0.79 | The ceremony's transmission: `encounter-bundle/0.1`, `encounter-credential-delivery/0.1` (counter-step in the bundle's thread), the signed `delivery-ack/0.1`; the own-challenge state model with its aging latch, the enactment record as the serialization point, the eight-step acceptance, connected and offline path with free switching; one commit discipline (prepare → verify → commit) under the §6.2 lock set; resumable issuance. Graduated from `/probe` on 05.09.2026 after a 25-round conformance loop. |
-
-Everything is re-exported from the package root; the table is a map, not an
-import instruction.
+`createHolder` is one person's device: its state behind the human acts, the
+delivery channel's three calls and the views an app reads.
 
 ```ts
-import { labeledContext, signCard, seal, sameDigest } from '@real-life/trust-protocol'
+import { createHolder, seedKeys } from '@real-life/trust-protocol'
+import { InMemoryStore } from '@real-life/trust-protocol/testing'
+
+const holder = await createHolder({ store: new InMemoryStore(), keys: seedKeys(rootSeed) })
+
+// a human act: its time and an actId the app mints when the human acts
+const shown = await holder.show({ when: Date.now(), actId: crypto.randomUUID() })
+// shown.events carries the card to display; shown.outbound the envelopes to send
+
+// the channel: one receive per arriving envelope, the adapter's reports,
+// and resume on a timer (retries and due duties)
+const got = await holder.receive(envelope, Date.now())
+await holder.report({ digest, status: 'accepted' }, Date.now())
+const { outbound, nextDueAt } = await holder.resume(Date.now())
+
+// the views, read after each commit (subscribe announces them)
+holder.subscribe(async () => render(await holder.contacts(), await holder.prompts()))
 ```
 
-## Two entry points
+**The timer.** Every act, receive and resume may name `nextDueAt`: the
+earliest time something is due, delivery work (retries, duties, acks)
+and expiry work (a prompt's expiry, an act's timeout or lifetime, an aging
+challenge, the retention of the effect cache, the journal, the outbox and
+the address keys) alike. The app keeps one timer at the earliest
+`nextDueAt` it was given; when it fires, it calls `tick(now)` and then
+`resume(now)`, sends the outbound and sets the timer anew.
+
+Every act returns `{ok: true, outbound, events} | {ok: false, code, ref?}`;
+`code` is a closed union, `ref` names the rule where one applies. Every
+`outbound` item is pure JSON (`digest`, `envelope`, `type`, `threadId`,
+`recipient`, `attempt`); the app delivers it to the device holding
+`envelope.rkid` and reports what its transport saw by `digest`.
+
+The human acts: `show`, `scan`, `captureSentCard`, `counter` (the encounter),
+`decide` (a prompt: confirm an encounter, accept an invitation, take up or
+consent to an introduction), `trust`, `untrust`, `pauseTrust`, `setClass`,
+`setGroupClass`, `merge`, `depart`, `setProfile`, `foundGroup`, `invite`,
+`vouchFor`, `introduce`, `rotateAnchor`, `addDevice`, `revokeDevice`. Not
+human: `receive`, `report`, `resume`, `tick`, `recover`. Reads: `contacts`,
+`contact`, `groups`, `profile`, `prompts`, `deliveryStatus`, `deviceKey`,
+`snapshot`, `subscribe`.
+
+## What the root exports
+
+- `createHolder` and its types (`Holder`, `HolderOptions`, `HumanActOptions`,
+  `HolderSnapshot`).
+- The ports: `Store`, `KeyProvider`, `Entropy`, `Log`, `Access`,
+  `RetryPolicy`, `DeliveryReport`, `Outbound`; `seedKeys(seed)` is the
+  default KeyProvider, `randomEntropy` the default Entropy.
+- The views: `ContactView`, `GroupView`, `PromptView`, `ProfileView`,
+  `DeliveryStatusView` and their parts.
+- The results and events: `ActResult`, `ReceiveResult`, `ResumeResult`,
+  `InfraError`, `CryptoUnavailableError`, `HolderEvent`.
+- The state as an opaque type (`HolderState`), `decodeState`, `CODEC`,
+  `StateCodecError`, and `storeContract`, the suite a Store adapter passes.
+- The pure wire builders and verifiers of every layer (`core`, `crypto`,
+  `identity`, `profile`, `encounter`, `membership`, `introduction`,
+  `delivery`, `carrier-identity`, `carrier`, `carrier-holder`), and two
+  namespaces of pure forms: `visibility` (anchor, star, group star,
+  continuity, acks) and `ceremony` (the encounter's, the group's and the
+  introduction's forms).
+
+Other entry points:
+
+| Entry point | What it holds |
+|---|---|
+| `./testing` | `InMemoryStore`, `memoryLog`, `scriptedEntropy`, `storeContract`, `emptyState`, `stateBuilder`, `freezeDeep`, `sampleState`, `openPromptModule`, the invariant checks, `forgeMapping` (deniability, Trust 6.1), `SCHEMAS` and the generated `wire` types. For tests, vectors and adapter authors; not for production holders. |
+| `./internal` | The structural `HolderState`, `encodeState` and the codec chain, the engine's module types, the pure view functions, the modules' factories and pure reads. For the library's own modules and tests; not an app contract. |
+| `./adapters/vti-mediator` | The VTI mediator as a carrier adapter: its submission states as `DeliveryReport`, collection and ack handling. |
+
+## The modules and the rules they implement
+
+Bare four-digit numbers are RLTP-TRU rules; the other layers name theirs.
+
+| Module | Specification | Rules |
+|---|---|---|
+| `core` | all layers | the canonical form: JCS (RFC 8785), multibase, digest equality over decoded bytes, whole-second timestamps, calendar validity, the JSON-Schema subset validator |
+| `crypto` | primitives | HKDF, key pairs, did:key and multikey, X25519, the `eddsa-jcs-2022` Data Integrity proof |
+| `identity` | Identity 0.54 §6.1, §6.2, §5.4, §5.5 | context derivation under the closed label registry: `group/<digest>` and its generations, `pair/…`, `persona/…`, `device/<n>/<c>`; the name pipeline pinned to Unicode 15.0 |
+| `identity-state` | Identity §2, §5.4, §5.5 | the label register with monotone sets, device names and revocation marks, the community anchor's rotation as a procedure over the Log port (register before log before duties) |
+| `encounter`, `encounter/ceremony` | Encounter 0.31 §4–§7 | `encounter-scan@0.25`: challenges and their aging latch (5.3), the enactment record (5.5), the 5.6 acceptance in its order, both paths of 5.8, `encounter-bundle/0.1` and `encounter-credential-delivery/0.1` with signed acks, the confirm prompt |
+| `trust/mapping` | Trust Section 2, 2a, §6.1–§6.5 | the trust act and the class settings (2720–2850), `anchor-mapping@4` issuance (6300/6310, 6420) and verification (6.3, conditions 4a, 4b, 8), the entry commit and the admission bound |
+| `trust/star`, `trust/group-star` | Trust §5.1–§5.4, §5.2b | `star@2` and `group-star@1` reconciled per recipient (5.4: salt scope, baseline automaton, completion by the ack), reception with assemblies and lower bounds |
+| `trust/entries` | Trust Section 2, §6a.1 | merge (net and manual, 6640), split (2080–2115), departure (2260), the head rule and the binding rule (6605) |
+| `trust/continuity` | Trust §6a | `continuity-probe@1` and `continuity-mapping@1`, chaining a re-encounter into the existing relationship (6a.4) |
+| `trust/profile`, `profile` | Trust §6b | `profile@1`: the one revision counter (6450), delivery on the class gates (6455), reception and the image bounds (6475) |
+| `trust/duties` | Trust 2850, 6370, 6455, 6595, 6596 | the duties a commit leaves: class on, re-issue after a rotation, the lag rule |
+| `membership`, `membership/holder` | Membership Tasks 0.19 on Access 0.57 | founding (Access 3.4.1), the prelude, invite, accept, admission and welcome, evidence relay and `vouch@2` (Access 5.3), an in-library Access over the holder's groups |
+| `introduction`, `introduction/holder` | Trust §8 on Delivery §4.4 | the Introduction Act in its three roles: request, forward, reply, the mediator's one ack at its declared delay, the vouchers; the requester's timeout at the act's expiry (8340; A20, spec follow-up 18: no ack timeout of 8690) |
+| `receive`, `engine` | Delivery 0.81 §5, §6.1, §6.2 | the sealed envelope, stages 1–9 once per envelope, the task register by full task URI, the completed-effect cache with stored acks, the outbox with the status trias, retry by backoff, give-up at the horizon, the act journal |
+| `carrier-identity`, `carrier`, `carrier-holder` | Identity §7a, Delivery §4.4, §5a, Identity §9.3 | the carrier-relationship principal, the carrier port's state machine, proofs, verdicts and recovery |
+| `views`, `prompts` | — | the read model: contacts by entry (2120, 2140), groups, prompts, the delivery status |
+
+## Runtime
+
+| Runtime | Status |
+|---|---|
+| Node 22 | tested in CI (the library job) |
+| Node 24 | tested locally |
+| Node 20 | the declared minimum (`engines`); Ed25519 and X25519 are in its WebCrypto |
+| Chromium 145 | tested by the workbench's end-to-end run (`apps/gesamtsimulator/tests/local-perspective.mjs`) |
+| Chromium ≥ 137, Firefox ≥ 129, Safari ≥ 17 | expected: they carry Ed25519 and X25519 in WebCrypto; not tested here |
+
+The WebCrypto handle is resolved when a holder is built, not at import: an
+app may pass its own (`createHolder({crypto})`, `seedKeys(seed, crypto)`),
+and a runtime without Ed25519 or X25519 is reported then as
+`CryptoUnavailableError`.
+
+## State, codec and storage
+
+A holder's state is pure JSON under a codec version. The Store port takes
+the state as opaque JSON and gives it back; the library decodes it
+(`decodeState`), the adapter never migrates.
+
+- **Codec 1** is the format of 0.4.0, the first stable one. Its golden
+  fixtures (`test/fixtures/state-v1*.json`, deterministic runs of
+  `test/fixtures/gen-state-v1.mjs`, reproduced in `npm test`) cover a
+  settled holder, one with work open (prompts, a joining invite, duties, a
+  rotation at step 2) and one with a tombstone, a revoked device and
+  carrier entries; each decodes and re-encodes byte for byte. A later codec brings its validator, a pure migration from the
+  one before, and its own fixture with a migration test.
+- A newer codec is refused as `codec-newer`, a codec without a validator
+  as `codec-unknown`; nothing is read best-effort.
+- `schemas/holder-state-v1.schema.json` describes codec 1 as a
+  non-normative JSON Schema (published with the package). The type
+  `HolderStateV1` (`./internal`) is generated from it
+  (`scripts/build-holder-state-types.mjs`); the build holds it against the
+  library's `HolderState`, and the tests hold the schema against the
+  codec's validator on the fixtures and on mutations of them. Two rules
+  only the codec states: a record's id equals its key, and an envelope's
+  `rkid` equals its recipient's `keyAgreement`.
+
+**Writing a Store adapter.** Implement `read(): Promise<{state, version}>`
+(a deep, independent copy; `null` state and version for an empty store) and
+`commit(version, next): Promise<{ok: true, version} | {ok: false, reason:
+'conflict'}>` as compare-and-swap: atomic, storing a copy, a version token
+never reused in the store's lifetime. One writer per holder; the adapter
+guarantees it. Then run the contract against it:
 
 ```ts
-import { …, visibility } from '@real-life/trust-protocol'   // wire-normative core
-const { trust, continuity, acks } = visibility                // Network Visibility, graduated
-import { introduce, membership }
-  from '@real-life/trust-protocol/probe'                     // draft — will change
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { storeContract } from '@real-life/trust-protocol'
+
+storeContract(() => new MyStore(), { test, assert })   // a fresh, empty store per call
 ```
 
-The **`/probe` subpath is deliberate.** Its modules exercise the converged
-*semantics* of their layers, but their transport shapes carry `@probe` and
-are **not wire-normative**: mediated introductions over a rendezvous drop
-and group membership (founding, VIC invite, admission, vouching). The
-trust act, the blinded star, §6a continuity and the deniable ack **left
-this subpath on 04.09.2026** — they are wire-normative now and live under
-`visibility` at the package root; the Encounter ceremony's transmission
-**left on 05.09.2026** and lives under `ceremony`. Experiment with the rest; do not treat its wire forms
-as an interoperability target. A subpath import is a decision someone has
-to make — nothing behind it can be reached by accident.
-
-**The redelivery contract of probe receivers:** a receiver's inbound
-effect is complete the moment it returns `handled: true` without `error` —
-that delivery is cached and answers `duplicate-known` forever after.
-Outbound work a receiver triggers (star refreshes, continuity mappings)
-is built per recipient and never discards partial results; what failed is
-named in `outboundError` / `outbound.failures`, and **redelivering the
-inbound document is not the retry path** — re-invoking the producing call
-(e.g. `trust.starRefreshAll`) is, and it is the host application's job.
+It checks snapshot isolation, CAS, atomicity, a lost result, the codec
+boundary and reopening. Durability across process loss is the persistent
+adapter's own test.
+
+## Invariants and the generator
+
+`invariants.ts` states predicates over a commit (`state → state'`): the
+register and revocation marks only grow, tombstones never shrink, a salt is
+issued at most once per tuple, the effect cache holds only completed
+digests, `accepted` arises only from a report, a duty leaves only by its
+specified fulfilment. `createHolder(ports, {invariants: true})` checks them
+on every commit. `test/invariants-generator.test.mjs` runs random sequences
+of acts, receives, reports and ticks over two and three holders and checks
+every predicate after every step.
 
 ## Versions
 
-This package uses its own semver; the specification uses castings. Each
-release states, per module, whose **wire forms** it implements — and what
-it deliberately does not:
-
-| Module (0.3.x) | Casting | Implemented | Not in this package |
-|---|---|---|---|
-| `identity` | Identity 0.50 | context derivation under the closed label registry (§6.1, unchanged since 0.13) with the ordered persona pipeline (§6.2, Unicode 15.0 pinned) | recovery derivation (§5.3), service identities (§7), the label register and its state |
-| `carrier-identity` | Identity 0.51 (§7a) | the carrier-relationship principal derivation, identifier validation | the register's generation state (held by the holder's store) |
-| `carrier` + `holder` | Delivery 0.79 (§4.4, §5a) + Identity 0.51 (§9.3) | the port state machine, proofs for all four purposes, verdicts, recovery | transport adapters and their policies (a carrier's budgets enter through hooks) |
-| `encounter` | Encounter 0.29 — wire `0.25` (`rltp-card/0.25`, `encounter-scan@0.25`) | challenges, both card profiles, the enactment binding, encounter credentials (the primitives) | — (the ceremony machine lives in `ceremony`) |
-| `ceremony` | Encounter 0.29 §5.3–5.8 + Delivery 0.79 (§3, §4.1–4.3, §6) | `encounter-bundle/0.1`, `encounter-credential-delivery/0.1`, signed `delivery-ack/0.1`; own-challenge state model (aging latch, whole seconds), enactment record + record-key lock set, 5.6 acceptance in order, both 5.8 paths, thread freshness incl. re-issue, resumable issuance, chain-head carry | storage, transport adapters, the host's UI correlation (duties listed in the handoff) |
-| `delivery` | Delivery 0.64 | the sealed envelope (§5) and the generic receive stages 1–4 | the type-specific stages, residual bookkeeping, transport adapters |
-| `core`, `crypto` | cross-layer | canonical form, digest equality, timestamps, validator; primitives + `eddsa-jcs-2022` proof | — |
-| `visibility` | Network Visibility 0.29 + Delivery 0.79 (§3, §4.2, §4.4) | the trust act (`anchor-mapping@2`, `grade-declaration@1`), `star@1` with 5.2a chunk assembly, the admission layer (Section 2), the 5.4 reconciliation automaton with completion via deniable acks, §6a continuity (`continuity-probe@1`, `continuity-mapping@1`, chaining), the registered task documents and `delivery-ack/0.1` with the 4.2 class rule; full §6.2 stage order on every receive path, peek→build→commit issuance on every producer | storage, transport adapters and their policies (the Encounter ceremony's flows live in `ceremony`) |
-| `/probe` | Network Visibility (introductions) · Membership Tasks + Access | mediated introductions, group membership — semantics of the running castings, transport shapes `@probe` | any wire-form stability whatsoever |
-
-Persona-name validation is **pinned to Unicode 15.0** as Identity §6.2
-requires: the repertoire ships with the package (`unicode15.ts`, ~5 kB of
-ranges) and no platform Unicode data is consulted — the same name derives
-the same anchor on every runtime, whatever ICU it carries.
+This package uses its own semver; the specification uses castings.
+
+| Area | Casting | Not in this package |
+|---|---|---|
+| identity | Identity 0.54 | recovery derivation (§5.3), service identities (§7) |
+| encounter | Encounter 0.31, cards 0.25, credentials 0.26 | — |
+| trust | Trust Layer 0.31 | — |
+| membership | Membership Tasks 0.19, Access 0.57 | the Access envelope (Membership 3.3: `access-operation/0.1` with `member.add` and the sealed welcome; this library sends its own `x-membership-welcome/0.1`, and the prelude as `x-membership-prelude-*`); roster replication: a holder knows the members it admitted and the roster its welcome carried |
+| introduction | Trust 0.31 §8 | how a requester learns the mediator's designator (8.3): this library's mediator sends `x-introduction-offer/0.1` |
+| delivery | Delivery 0.81 | transport adapters beyond `./adapters/vti-mediator` |
+| devices | Identity §5.5 | multi-device production: one writer per holder |
 
 ## The contract: the vectors
 
-A version that does not reproduce `vectors/` byte-for-byte is not a valid
-version — the conformance runner checks every cryptographic claim, and every
-negative case must fail at its declared stage. If you implement RLTP in
-another language, those same vectors are how you check yourself; you do not
-need this package to do it.
+A version that does not reproduce `vectors/` byte for byte is not a valid
+version. The conformance runner checks every cryptographic claim, and every
+negative case fails at its declared stage. An implementation in another
+language checks itself against the same vectors; it does not need this
+package.
 
 ## License
 
-[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — specification and
+[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), specification and
 reference implementation alike.

package/dist/ack.d.ts

@@ -0,0 +1,84 @@
+/** The registered type of the acknowledgement (Delivery §4.2). */
+export declare const ACK_TYPE = "https://real-life.org/trust-tasks/delivery-ack/0.1";
+/** The ack document without its proof: the MAC preimage (4.2). */
+export interface AckDocument {
+    id: string;
+    type: typeof ACK_TYPE;
+    issuer: string;
+    recipient: string;
+    threadId: string;
+    issuedAt: string;
+    payload: {
+        ref: string;
+        meaning: 'received';
+    };
+}
+/** The HKDF info of the channel ack key, issuer first (4.2). */
+export declare const ackInfo: (issuerPairAnchor: string, recipientPairAnchor: string) => string;
+/** The channel ack key from the tuple's X25519 shared secret (4.2). */
+export declare function ackKeyOf(shared: Uint8Array, issuerPairAnchor: string, recipientPairAnchor: string, subtle?: SubtleCrypto): Promise<Uint8Array>;
+/** "u" + base64url HMAC-SHA-256 over the JCS of `doc` under `key`. */
+export declare function ackMac(key: Uint8Array, doc: unknown, subtle?: SubtleCrypto): Promise<string>;
+/** The proof-less ack of `ref` on the acked document's thread (4.2):
+ *  issuer = the acked document's recipient, recipient = its issuer. */
+export declare const ackDocument: (f: {
+    id: string;
+    issuer: string;
+    recipient: string;
+    threadId: string;
+    issuedAt: string;
+    ref: string;
+}) => AckDocument;
+/** The deniable ack: `doc` with its MAC-form proof under the channel ack key. */
+export declare function macAck(doc: AckDocument, key: Uint8Array, subtle?: SubtleCrypto): Promise<AckDocument & {
+    proof: {
+        mac: string;
+    };
+}>;
+/** Where a received ack's form fails, by the stage of Delivery §6.2 that names it. */
+export type AckFormFailure = {
+    stage: 5 | 7;
+    reason: 'malformed';
+} | {
+    stage: 8;
+    reason: 'validation-failed';
+};
+/**
+ * The context-free checks of a received MAC-form ack, in stage order
+ * (Delivery §6.2): 5 document profile (schema, closed form, calendar), 7
+ * payload schema, 8 the class rule's proof form (exactly `{mac}`), no
+ * enactment, `meaning`. What needs the arrival context stays the
+ * caller's: recipient = own anchor (5), issuer = the tuple's counterpart,
+ * `ref` = a document sent on that thread, and the MAC itself (8).
+ */
+export declare function macAckForm(doc: unknown): {
+    ok: true;
+    ref: string;
+    threadId: string;
+} | ({
+    ok: false;
+} & AckFormFailure);
+/**
+ * The context-free checks of a received SIGNED ack (the class rule's
+ * form for a signature-class payload, 4.2/4.4), in stage order: 5 the
+ * document profile, 7 the payload schema, 8 the proof form (an
+ * eddsa-jcs-2022 DataIntegrityProof, no `mac`, calendar-valid), no
+ * enactment, `meaning`. The signature itself (under `issuer`) and the
+ * consistency against what the holder sent stay the caller's.
+ */
+export declare function signedAckForm(doc: unknown): {
+    ok: true;
+    ref: string;
+    threadId: string;
+} | ({
+    ok: false;
+} & AckFormFailure);
+/** The proof form a received ack carries: the MAC object, a signature, or neither. */
+export declare const ackProofForm: (doc: unknown) => "mac" | "signed" | null;
+/** Does the ack's MAC verify under `key`? (4.2; over JCS of the document without proof) */
+export declare function macAckValid(doc: {
+    proof?: {
+        mac?: unknown;
+    };
+} & Record<string, unknown>, key: Uint8Array, subtle?: SubtleCrypto): Promise<boolean>;
+//# sourceMappingURL=ack.d.ts.map

package/dist/ack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ack.d.ts","sourceRoot":"","sources":["../src/ack.ts"],"names":[],"mappings":"AAwBA,kEAAkE;AAClE,eAAO,MAAM,QAAQ,uDAAuD,CAAA;AAE5E,kEAAkE;AAClE,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,OAAO,QAAQ,CAAA;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,UAAU,CAAA;KAAE,CAAA;CAC9C;AAED,gEAAgE;AAChE,eAAO,MAAM,OAAO,GAAI,kBAAkB,MAAM,EAAE,qBAAqB,MAAM,KAAG,MACJ,CAAA;AAE5E,uEAAuE;AACvE,wBAAsB,QAAQ,CAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CAGrJ;AAED,sEAAsE;AACtE,wBAAsB,MAAM,CAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAInG;AAED;uEACuE;AACvE,eAAO,MAAM,WAAW,GAAI,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,KAAG,WAGlI,CAAA;AAEF,iFAAiF;AACjF,wBAAsB,MAAM,CAAE,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,GAAG;IAAE,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC,CAEzI;AAMD,sFAAsF;AACtF,MAAM,MAAM,cAAc,GAAG;IAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,CAAC,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,CAAA;AAE9G;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAE,GAAG,EAAE,OAAO,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,CAAC;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,GAAG,cAAc,CAAC,CAUxH;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAE,GAAG,EAAE,OAAO,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,CAAC;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,GAAG,cAAc,CAAC,CAY3H;AAED,sFAAsF;AACtF,eAAO,MAAM,YAAY,GAAI,KAAK,OAAO,KAAG,KAAK,GAAG,QAAQ,GAAG,IAI9D,CAAA;AAED,2FAA2F;AAC3F,wBAAsB,WAAW,CAAE,GAAG,EAAE;IAAE,KAAK,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAGzJ"}

package/dist/ack.js

@@ -0,0 +1,114 @@
+// ack — the delivery acknowledgement's pure parts (Delivery §4.2, the
+// acknowledgement class rule of §4.4): the type, the deniable MAC form's
+// channel-keyed derivation, the MAC, and the context-free form checks of
+// a received ack. Used by the holder's receive core (engine.ts);
+// byte-compatible with vectors/delivery-ack.json
+// (lib/test/vectors4.test.mjs).
+//
+//   k     = HKDF-SHA-256(ikm = X25519(pairX_issuer, pairX_recipient),
+//                        salt = empty, info = "rltp/v1/delivery/mac/ack/"
+//                        || issuerPairAnchor || "/" || recipientPairAnchor,
+//                        32 bytes; an all-zero shared secret is rejected)
+//   proof = { mac: "u" + base64url(HMAC-SHA-256(k, JCS(document without proof))) }
+//
+// Deniable by construction: either party of the tuple derives k, so for a
+// designated-verifier payload the ack is evidence to its sender alone,
+// never an attestation (4.2). The key agreement itself is the caller's:
+// the holder asks its KeyProvider.
+import { jcs, b64uOf, calOK, makeValidator } from './core.js';
+import { hkdf, platformSubtle } from './crypto.js';
+import { SCHEMAS } from './schemas.js';
+const te = new TextEncoder();
+/** The registered type of the acknowledgement (Delivery §4.2). */
+export const ACK_TYPE = 'https://real-life.org/trust-tasks/delivery-ack/0.1';
+/** The HKDF info of the channel ack key, issuer first (4.2). */
+export const ackInfo = (issuerPairAnchor, recipientPairAnchor) => 'rltp/v1/delivery/mac/ack/' + issuerPairAnchor + '/' + recipientPairAnchor;
+/** The channel ack key from the tuple's X25519 shared secret (4.2). */
+export async function ackKeyOf(shared, issuerPairAnchor, recipientPairAnchor, subtle) {
+    if (shared.every((b) => b === 0))
+        throw new Error('all-zero X25519 output');
+    return hkdf(shared, ackInfo(issuerPairAnchor, recipientPairAnchor), 32, subtle);
+}
+/** "u" + base64url HMAC-SHA-256 over the JCS of `doc` under `key`. */
+export async function ackMac(key, doc, subtle) {
+    const S = subtle ?? platformSubtle();
+    const k = await S.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    return 'u' + b64uOf(new Uint8Array(await S.sign('HMAC', k, te.encode(jcs(doc)))));
+}
+/** The proof-less ack of `ref` on the acked document's thread (4.2):
+ *  issuer = the acked document's recipient, recipient = its issuer. */
+export const ackDocument = (f) => ({
+    id: f.id, type: ACK_TYPE, issuer: f.issuer, recipient: f.recipient, threadId: f.threadId, issuedAt: f.issuedAt,
+    payload: { ref: f.ref, meaning: 'received' },
+});
+/** The deniable ack: `doc` with its MAC-form proof under the channel ack key. */
+export async function macAck(doc, key, subtle) {
+    return { ...doc, proof: { mac: await ackMac(key, doc, subtle) } };
+}
+const V = makeValidator(SCHEMAS);
+const schemaOk = (file, data) => V.validate(data, SCHEMAS[file], SCHEMAS[file]).length === 0;
+const ACK_FIELDS = new Set(['id', 'type', 'issuer', 'recipient', 'threadId', 'issuedAt', 'payload', 'proof', 'ceremony']);
+/**
+ * The context-free checks of a received MAC-form ack, in stage order
+ * (Delivery §6.2): 5 document profile (schema, closed form, calendar), 7
+ * payload schema, 8 the class rule's proof form (exactly `{mac}`), no
+ * enactment, `meaning`. What needs the arrival context stays the
+ * caller's: recipient = own anchor (5), issuer = the tuple's counterpart,
+ * `ref` = a document sent on that thread, and the MAC itself (8).
+ */
+export function macAckForm(doc) {
+    const d = doc;
+    if (!schemaOk('rltp-delivery-document.schema.json', d) || d?.type !== ACK_TYPE)
+        return { ok: false, stage: 5, reason: 'malformed' };
+    if (Object.keys(d).some((k) => !ACK_FIELDS.has(k)) || !calOK(d.issuedAt))
+        return { ok: false, stage: 5, reason: 'malformed' };
+    if (!schemaOk('payload-delivery-ack.schema.json', d.payload))
+        return { ok: false, stage: 7, reason: 'malformed' };
+    const p = d.proof;
+    if (p === null || typeof p !== 'object' || Object.keys(p).length !== 1 || typeof p.mac !== 'string')
+        return { ok: false, stage: 8, reason: 'validation-failed' };
+    if (d.ceremony?.enactment !== undefined)
+        return { ok: false, stage: 8, reason: 'validation-failed' };
+    if (d.payload.meaning !== 'received')
+        return { ok: false, stage: 8, reason: 'validation-failed' };
+    return { ok: true, ref: d.payload.ref, threadId: d.threadId };
+}
+/**
+ * The context-free checks of a received SIGNED ack (the class rule's
+ * form for a signature-class payload, 4.2/4.4), in stage order: 5 the
+ * document profile, 7 the payload schema, 8 the proof form (an
+ * eddsa-jcs-2022 DataIntegrityProof, no `mac`, calendar-valid), no
+ * enactment, `meaning`. The signature itself (under `issuer`) and the
+ * consistency against what the holder sent stay the caller's.
+ */
+export function signedAckForm(doc) {
+    const d = doc;
+    if (!schemaOk('rltp-delivery-document.schema.json', d) || d?.type !== ACK_TYPE)
+        return { ok: false, stage: 5, reason: 'malformed' };
+    if (Object.keys(d).some((k) => !ACK_FIELDS.has(k)) || !calOK(d.issuedAt))
+        return { ok: false, stage: 5, reason: 'malformed' };
+    if (!schemaOk('payload-delivery-ack.schema.json', d.payload))
+        return { ok: false, stage: 7, reason: 'malformed' };
+    const p = d.proof;
+    if (p === null || typeof p !== 'object' || p.mac !== undefined || p.type !== 'DataIntegrityProof' || p.cryptosuite !== 'eddsa-jcs-2022' || !calOK(p.created)) {
+        return { ok: false, stage: 8, reason: 'validation-failed' };
+    }
+    if (d.ceremony?.enactment !== undefined)
+        return { ok: false, stage: 8, reason: 'validation-failed' };
+    if (d.payload.meaning !== 'received')
+        return { ok: false, stage: 8, reason: 'validation-failed' };
+    return { ok: true, ref: d.payload.ref, threadId: d.threadId };
+}
+/** The proof form a received ack carries: the MAC object, a signature, or neither. */
+export const ackProofForm = (doc) => {
+    const p = doc?.proof;
+    if (p === null || typeof p !== 'object')
+        return null;
+    return typeof p.mac === 'string' ? 'mac' : typeof p.proofValue === 'string' ? 'signed' : null;
+};
+/** Does the ack's MAC verify under `key`? (4.2; over JCS of the document without proof) */
+export async function macAckValid(doc, key, subtle) {
+    const { proof, ...rest } = doc;
+    return typeof proof?.mac === 'string' && (await ackMac(key, rest, subtle)) === proof.mac;
+}
+//# sourceMappingURL=ack.js.map

package/dist/ack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ack.js","sourceRoot":"","sources":["../src/ack.ts"],"names":[],"mappings":"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","sourcesContent":["// ack — the delivery acknowledgement's pure parts (Delivery §4.2, the\n// acknowledgement class rule of §4.4): the type, the deniable MAC form's\n// channel-keyed derivation, the MAC, and the context-free form checks of\n// a received ack. Used by the holder's receive core (engine.ts);\n// byte-compatible with vectors/delivery-ack.json\n// (lib/test/vectors4.test.mjs).\n//\n//   k     = HKDF-SHA-256(ikm = X25519(pairX_issuer, pairX_recipient),\n//                        salt = empty, info = \"rltp/v1/delivery/mac/ack/\"\n//                        || issuerPairAnchor || \"/\" || recipientPairAnchor,\n//                        32 bytes; an all-zero shared secret is rejected)\n//   proof = { mac: \"u\" + base64url(HMAC-SHA-256(k, JCS(document without proof))) }\n//\n// Deniable by construction: either party of the tuple derives k, so for a\n// designated-verifier payload the ack is evidence to its sender alone,\n// never an attestation (4.2). The key agreement itself is the caller's:\n// the holder asks its KeyProvider.\nimport { jcs, b64uOf, calOK, makeValidator } from './core.js'\nimport type { Json } from './core.js'\nimport { hkdf, platformSubtle } from './crypto.js'\nimport { SCHEMAS } from './schemas.js'\n\nconst te = new TextEncoder()\n\n/** The registered type of the acknowledgement (Delivery §4.2). */\nexport const ACK_TYPE = 'https://real-life.org/trust-tasks/delivery-ack/0.1'\n\n/** The ack document without its proof: the MAC preimage (4.2). */\nexport interface AckDocument {\n  id: string\n  type: typeof ACK_TYPE\n  issuer: string\n  recipient: string\n  threadId: string\n  issuedAt: string\n  payload: { ref: string, meaning: 'received' }\n}\n\n/** The HKDF info of the channel ack key, issuer first (4.2). */\nexport const ackInfo = (issuerPairAnchor: string, recipientPairAnchor: string): string =>\n  'rltp/v1/delivery/mac/ack/' + issuerPairAnchor + '/' + recipientPairAnchor\n\n/** The channel ack key from the tuple's X25519 shared secret (4.2). */\nexport async function ackKeyOf (shared: Uint8Array, issuerPairAnchor: string, recipientPairAnchor: string, subtle?: SubtleCrypto): Promise<Uint8Array> {\n  if (shared.every((b) => b === 0)) throw new Error('all-zero X25519 output')\n  return hkdf(shared, ackInfo(issuerPairAnchor, recipientPairAnchor), 32, subtle)\n}\n\n/** \"u\" + base64url HMAC-SHA-256 over the JCS of `doc` under `key`. */\nexport async function ackMac (key: Uint8Array, doc: unknown, subtle?: SubtleCrypto): Promise<string> {\n  const S = subtle ?? platformSubtle()\n  const k = await S.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'])\n  return 'u' + b64uOf(new Uint8Array(await S.sign('HMAC', k, te.encode(jcs(doc)))))\n}\n\n/** The proof-less ack of `ref` on the acked document's thread (4.2):\n *  issuer = the acked document's recipient, recipient = its issuer. */\nexport const ackDocument = (f: { id: string, issuer: string, recipient: string, threadId: string, issuedAt: string, ref: string }): AckDocument => ({\n  id: f.id, type: ACK_TYPE, issuer: f.issuer, recipient: f.recipient, threadId: f.threadId, issuedAt: f.issuedAt,\n  payload: { ref: f.ref, meaning: 'received' },\n})\n\n/** The deniable ack: `doc` with its MAC-form proof under the channel ack key. */\nexport async function macAck (doc: AckDocument, key: Uint8Array, subtle?: SubtleCrypto): Promise<AckDocument & { proof: { mac: string } }> {\n  return { ...doc, proof: { mac: await ackMac(key, doc, subtle) } }\n}\n\nconst V = makeValidator(SCHEMAS)\nconst schemaOk = (file: string, data: unknown): boolean => V.validate(data, SCHEMAS[file], SCHEMAS[file]).length === 0\nconst ACK_FIELDS = new Set(['id', 'type', 'issuer', 'recipient', 'threadId', 'issuedAt', 'payload', 'proof', 'ceremony'])\n\n/** Where a received ack's form fails, by the stage of Delivery §6.2 that names it. */\nexport type AckFormFailure = { stage: 5 | 7, reason: 'malformed' } | { stage: 8, reason: 'validation-failed' }\n\n/**\n * The context-free checks of a received MAC-form ack, in stage order\n * (Delivery §6.2): 5 document profile (schema, closed form, calendar), 7\n * payload schema, 8 the class rule's proof form (exactly `{mac}`), no\n * enactment, `meaning`. What needs the arrival context stays the\n * caller's: recipient = own anchor (5), issuer = the tuple's counterpart,\n * `ref` = a document sent on that thread, and the MAC itself (8).\n */\nexport function macAckForm (doc: unknown): { ok: true, ref: string, threadId: string } | ({ ok: false } & AckFormFailure) {\n  const d = doc as Record<string, any>\n  if (!schemaOk('rltp-delivery-document.schema.json', d) || d?.type !== ACK_TYPE) return { ok: false, stage: 5, reason: 'malformed' }\n  if (Object.keys(d).some((k) => !ACK_FIELDS.has(k)) || !calOK(d.issuedAt)) return { ok: false, stage: 5, reason: 'malformed' }\n  if (!schemaOk('payload-delivery-ack.schema.json', d.payload)) return { ok: false, stage: 7, reason: 'malformed' }\n  const p = d.proof as Record<string, Json> | undefined\n  if (p === null || typeof p !== 'object' || Object.keys(p).length !== 1 || typeof p.mac !== 'string') return { ok: false, stage: 8, reason: 'validation-failed' }\n  if (d.ceremony?.enactment !== undefined) return { ok: false, stage: 8, reason: 'validation-failed' }\n  if (d.payload.meaning !== 'received') return { ok: false, stage: 8, reason: 'validation-failed' }\n  return { ok: true, ref: d.payload.ref, threadId: d.threadId }\n}\n\n/**\n * The context-free checks of a received SIGNED ack (the class rule's\n * form for a signature-class payload, 4.2/4.4), in stage order: 5 the\n * document profile, 7 the payload schema, 8 the proof form (an\n * eddsa-jcs-2022 DataIntegrityProof, no `mac`, calendar-valid), no\n * enactment, `meaning`. The signature itself (under `issuer`) and the\n * consistency against what the holder sent stay the caller's.\n */\nexport function signedAckForm (doc: unknown): { ok: true, ref: string, threadId: string } | ({ ok: false } & AckFormFailure) {\n  const d = doc as Record<string, any>\n  if (!schemaOk('rltp-delivery-document.schema.json', d) || d?.type !== ACK_TYPE) return { ok: false, stage: 5, reason: 'malformed' }\n  if (Object.keys(d).some((k) => !ACK_FIELDS.has(k)) || !calOK(d.issuedAt)) return { ok: false, stage: 5, reason: 'malformed' }\n  if (!schemaOk('payload-delivery-ack.schema.json', d.payload)) return { ok: false, stage: 7, reason: 'malformed' }\n  const p = d.proof as Record<string, Json> | undefined\n  if (p === null || typeof p !== 'object' || p.mac !== undefined || p.type !== 'DataIntegrityProof' || p.cryptosuite !== 'eddsa-jcs-2022' || !calOK(p.created)) {\n    return { ok: false, stage: 8, reason: 'validation-failed' }\n  }\n  if (d.ceremony?.enactment !== undefined) return { ok: false, stage: 8, reason: 'validation-failed' }\n  if (d.payload.meaning !== 'received') return { ok: false, stage: 8, reason: 'validation-failed' }\n  return { ok: true, ref: d.payload.ref, threadId: d.threadId }\n}\n\n/** The proof form a received ack carries: the MAC object, a signature, or neither. */\nexport const ackProofForm = (doc: unknown): 'mac' | 'signed' | null => {\n  const p = (doc as { proof?: Record<string, unknown> } | null)?.proof\n  if (p === null || typeof p !== 'object') return null\n  return typeof p.mac === 'string' ? 'mac' : typeof p.proofValue === 'string' ? 'signed' : null\n}\n\n/** Does the ack's MAC verify under `key`? (4.2; over JCS of the document without proof) */\nexport async function macAckValid (doc: { proof?: { mac?: unknown } } & Record<string, unknown>, key: Uint8Array, subtle?: SubtleCrypto): Promise<boolean> {\n  const { proof, ...rest } = doc\n  return typeof proof?.mac === 'string' && (await ackMac(key, rest, subtle)) === proof.mac\n}\n"]}