@real-life/trust-protocol 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## 0.8.0
+
+Takes up the VTI Mediator Adapter Profile 0.25 (§1b, the delivery hint)
+and Encounter 0.31.1: a card carries the hints by which its side is
+reachable in the relationship the card opens. A minor version: the
+public API grows (`CarrierOffer`, a new `ActError` member, new
+`RelationshipView` fields, three adapter exports); the storage format
+does not change.
+
+- **The carrier offer** of `show` and `scan`: `carrier: {nonce,
+  deliveryHints}` (new type `CarrierOffer`). `nonce` is the
+  relationship's carrier nonce N, 32 bytes the app draws fresh (Identity
+  §7a.3); `deliveryHints` are the hints the app built from the wire
+  identities its adapter derives from N. The displayed card (`show`) or
+  the scanner's sent card (`scan`) carries the hints under its proof.
+  The library interprets no hint. The offer is act input: bound and
+  journaled with the act, so a repeat under the same actId answers the
+  same card and another offer under it is `actid-conflict`.
+- **N in the register** (`register.carriers`, generation 1) under the
+  relationship the card opens: at `show` already, as the card's pair
+  label enters the register before display (Encounter 4110); a card that
+  ages unscanned leaves its entry, as it leaves its label. At `scan`
+  under the scanner's fresh relationship. The storage format is
+  unchanged (codec 3).
+- **Refusals**: more than eight hints or a hint over 512 characters
+  (Encounter RLTP-ENC-6090) is `card-invalid` with `ref`
+  `RLTP-ENC-6090`; an offer without a hint, or with a hint that is no
+  string, is `card-invalid` without a `ref` (an empty offer announces
+  nothing; a card without hints needs no offer, 6080); a nonce that is not 32 bytes in canonical base64url,
+  or that the register already holds as a carrier or pair nonce, is the
+  new code `carrier-nonce-invalid`. Nothing commits on a refusal.
+- **The view**: each `RelationshipView` names the relationship's
+  canonical carrier-nonce entry (`carrierNonce: {nonce, generation}`) and
+  the counterpart's hints from the card of the enactment that opened it
+  (`counterpartDeliveryHints`), as signed. A re-encounter chained into
+  the relationship changes neither (profile RLTP-VTI-1230). Without an
+  offer both are absent.
+- `cardBody` takes `deliveryHints`.
+- **The adapter builds and reads the hint** (`./adapters/vti-mediator`,
+  below the port line): `deliveryHint(rootIkm, C, N)` derives this
+  side's connection DID and egress identity from (root, `C`, `N`), as
+  the factory derives the instance's trio (derived, not supplied), and
+  gives its hint (RLTP-VTI-1210: the JCS form of the `TSPTransport`
+  entry);
+  `readDeliveryHint(hint, C)` reads one hint strictly (1210, 1220: JSON,
+  byte-equal to its JCS form, exactly the four members, both identities
+  canonical Ed25519 `did:key` that decode to `0xed01` and 32 bytes,
+  `serviceEndpoint` = `C`) into `{connectionDid, egressDid, carrier}` or null;
+  `readDeliveryHints(hints, C, self)` reads a card's list as the side
+  `self` (its own connection DID and egress identity): a hint naming one
+  of them is ignored (RLTP-VTI-1227), then exactly one hint for `C`
+  (1225), else null. Both readers are total (RLTP-VTI-1220): any input
+  answers null or the complete identities, nothing throws — a hint that
+  parses but has no JCS form (a lone surrogate) included; tested over the
+  vector's corpus and 20 000 seeded mutations. The app passes the
+  identities to the wire (`peerDid`, `peerEgressDid` of the binding),
+  which refuses a counterpart identity that is one of its own.
+- **No change of N.** The library offers no rotation of a carrier nonce
+  (Identity §7a.3, `generation + 1`) and no replacement after loss:
+  `register.carriers` is written once per relationship, at `show` or
+  `scan`. The profile carries none either (RLTP-VTI-1245). With one
+  writer of the register per holder, as in this library, `carrierNonce`
+  is the `N` whose identities the counterpart saw; two devices writing a
+  first `N` apart would make that untrue (profile Open Issue 13). A
+  relationship chained into another is no `RelationshipView` of its own
+  (only an id in `chainedFrom`) and shows no `carrierNonce`: the app
+  closes the adapter instance of a relationship once its id appears in
+  another relationship's `chainedFrom` (RLTP-VTI-1230).
+
 ## 0.7.0
 
 Takes up the VTI Mediator Adapter Profile 0.24: the sending form of §3a.

package/README.md

@@ -146,6 +146,44 @@ human: `receive`, `report`, `resume`, `tick`, `recover`, `takeMessages`.
 Reads: `contacts`, `contact`, `groups`, `profile`, `prompts`, `inbox`,
 `deliveryStatus`, `deviceKey`, `replay`, `snapshot`, `subscribe`.
 
+**Delivery hints** (Encounter RLTP-ENC-6080, 6090; Identity §7a.3; VTI
+Mediator Adapter Profile 0.25 §1b). `show` and `scan` take a carrier
+offer, `carrier: {nonce, deliveryHints}`: the relationship's carrier
+nonce N (32 bytes the app draws fresh) and the hints the app built from
+the wire identities its adapter derives from N. The card (the displayed
+card, or the scanner's sent card) carries the hints under its proof, and
+N enters the register under the relationship the card opens — at `show`
+already, as the card's pair label does. More than eight hints or a hint
+over 512 characters is `card-invalid` with `ref` `RLTP-ENC-6090`; an
+offer without a hint, or with a hint that is no string, is
+`card-invalid` without a `ref`; a nonce
+that is not 32 bytes or that the register already holds is
+`carrier-nonce-invalid`. The offer is act input, journaled with the act.
+The library interprets no hint. Each relationship of a contact view names
+the own canonical carrier-nonce entry (`carrierNonce: {nonce,
+generation}`) and the counterpart's hints from the card of the enactment
+that opened it (`counterpartDeliveryHints`); a re-encounter chained into
+the relationship changes neither, and the chained relationship shows no
+`carrierNonce`: the app closes the adapter instance of a relationship
+once its id appears in another relationship's `chainedFrom`. The
+library offers no rotation or replacement of N (profile RLTP-VTI-1245);
+with its one writer per holder, `carrierNonce` is the N the counterpart
+saw. The VTI adapter module builds and reads the hint:
+`deliveryHint(rootIkm, C, N)` (derived like the adapter's trio),
+`readDeliveryHint(hint, C)`, `readDeliveryHints(hints, C, self)` (profile
+§1b; total readers, a hint naming `self`'s identities ignored).
+
+```ts
+import { deliveryHint } from '@real-life/trust-protocol/adapters/vti-mediator'
+
+// rootIkm and C: the same inputs the app gives MediatorCarrierAdapter.create
+const nonce = crypto.getRandomValues(new Uint8Array(32))
+const hint = await deliveryHint(rootIkm, C, nonce)
+const shown = await holder.show({ when: Date.now(), actId: crypto.randomUUID(), carrier: { nonce, deliveryHints: [hint] } })
+const [rel] = (await holder.contacts())[0]?.relationships ?? []
+// rel?.carrierNonce: this side's N; rel?.counterpartDeliveryHints: the counterpart's hints, as signed
+```
+
 One actId, one result: every human act is journaled under its actId with
 its result. A repeat under the same actId answers the journaled events
 (for `sendMessage` the same `mid`) at any clock and across a lock and a
@@ -167,7 +205,7 @@ journal, and acting anew is the human's decision. Custody:
 
 ## What the root exports
 
-- `createHolder` and its types (`Holder`, `HolderOptions`, `HumanActOptions`,
+- `createHolder` and its types (`Holder`, `HolderOptions`, `HumanActOptions`, `CarrierOffer`,
   `HolderSnapshot`).
 - The ports: `Store`, `KeyProvider`, `Entropy`, `Log`, `Access`,
   `RetryPolicy`, `DeliveryReport`, `Outbound`; `seedKeys(seed)` is the
@@ -194,7 +232,7 @@ Other entry points:
 |---|---|
 | `./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 transport adapter (profile 0.24): its submission states as `DeliveryReport`, collection and ack handling, the selective conclusion of a collection (`conclude(c, now, {keep})`, `concludable(result)`: a `failed(rate-limited)` item stays with the carrier), the sending form of §3a: every deposit names its `SendMode` (`routed`, or `egress-session` after the one-way switch of RLTP-VTI-3130), the send state (mode, open routed deposits) travels in `AckState.send` (a `submit()` without a digest opens nothing), a `WireError('routed-refused')` switches at once, a wire without `queueEmpty()` never completes a collection and so never switches, `answered(digest, now)` carries the holder's answers to a later instance, and `depositAddressing(mode, self, peerConnection, carrier)` gives both layers' addressing. |
+| `./adapters/vti-mediator` | The VTI mediator as a transport adapter (profile 0.25): its submission states as `DeliveryReport`, collection and ack handling, the selective conclusion of a collection (`conclude(c, now, {keep})`, `concludable(result)`: a `failed(rate-limited)` item stays with the carrier), the sending form of §3a: every deposit names its `SendMode` (`routed`, or `egress-session` after the one-way switch of RLTP-VTI-3130), the send state (mode, open routed deposits) travels in `AckState.send` (a `submit()` without a digest opens nothing), a `WireError('routed-refused')` switches at once, a wire without `queueEmpty()` never completes a collection and so never switches, `answered(digest, now)` carries the holder's answers to a later instance, `depositAddressing(mode, self, peerConnection, carrier)` gives both layers' addressing, and `deliveryHint(rootIkm, C, N)`, `readDeliveryHint(hint, C)`, `readDeliveryHints(hints, C, self)` build and read the delivery hint of §1b (total readers). |
 
 ## The modules and the rules they implement
 
@@ -314,7 +352,7 @@ This package uses its own semver; the specification uses castings.
 | membership | Membership Tasks 0.20, 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`); an admission prompt after the bound of RLTP-MT-3282; 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.83 | transport adapters beyond `./adapters/vti-mediator`; the block of the Trust Layer's types (Message Tasks 6240: their treatments wait for the next casting of the Trust Layer) |
-| transport adapter | VTI Mediator Adapter Profile 0.24 | the TSP framing, which is the wire binding's (profile §7; `binding/` in the repository); a return from `egress-session` to `routed` (profile Open Issue 7) |
+| transport adapter | VTI Mediator Adapter Profile 0.25 | a change of the carrier nonce N (RLTP-VTI-1245; profile Open Issue 13); the TSP framing, which is the wire binding's (profile §7; `binding/` in the repository); a return from `egress-session` to `routed` (profile Open Issue 7) |
 | message | Message Tasks 0.1 | holding a message unsent until its tuple is ready (5020): `sendMessage` answers `not-ready` and the app keeps the message; checking `replyTo` against the relationship's history (5120), which is the app's; multi-device (§9); `failed(task-expired)` for a message: reachable only with a retry horizon beyond P179D, which the engine does not admit (at most P90D), so an undelivered message ends as `failed(expired-by-adapter-policy)` |
 | devices | Identity §5.5 | multi-device production: one writer per holder |
 

package/dist/adapters/vti-mediator.d.ts

@@ -12,6 +12,38 @@ export declare const DECLARED: Readonly<{
     readonly duplicateWindowMs: number;
     readonly routedAckDeadlineMs: number;
 }>;
+/** The counterpart's wire identities at one carrier, as its hint names them. */
+export interface DeliveryHintIdentities {
+    connectionDid: string;
+    egressDid: string;
+    carrier: string;
+}
+/** This side's hint for carrier `C` in the relationship of carrier nonce
+ *  `N` (RLTP-VTI-1210, 1215): the connection DID and the egress identity
+ *  derived here from (root, `C`, `N`), exactly as the factory derives the
+ *  instance's trio — derived, not supplied, so the two cannot come from
+ *  different relationships — as the JCS form of the TSPTransport service
+ *  entry naming the connection DID (`id`, with `#tsp`), `C`
+ *  (`serviceEndpoint`) and the egress identity (`rltpEgress`). */
+export declare function deliveryHint(rootIkm: Uint8Array, carrier: string, nonce: Uint8Array): Promise<string>;
+/** One hint read strictly (RLTP-VTI-1210, 1220) for carrier `C`: JSON,
+ *  byte-equal to its JCS form, exactly the four members, type
+ *  TSPTransport, an `id` ending in `#tsp`, both identities distinct
+ *  canonical Ed25519 did:key, `serviceEndpoint` byte-equal to `C`.
+ *  Total (RLTP-VTI-1220): any other input — not a string, not JSON, no JCS
+ *  form (a lone surrogate), any other shape — is null, ignored; it never
+ *  throws. */
+export declare function readDeliveryHint(hint: unknown, carrier: unknown): DeliveryHintIdentities | null;
+/** The counterpart's wire identities at `C` from the hints of the card
+ *  that opened the relationship, read by the side `self` (its own
+ *  connection DID and egress identity of this relationship and carrier):
+ *  every hint read as readDeliveryHint does; a hint naming one of `self`'s
+ *  identities is ignored (RLTP-VTI-1227); of what remains, the one hint
+ *  for `C` (RLTP-VTI-1225, 1240) — none, or more than one, is null: the
+ *  relationship is not carried at `C` (RLTP-VTI-1235). Total: any input
+ *  answers null or the identities, never a throw; without a well-formed
+ *  `self` nothing is read. */
+export declare function readDeliveryHints(hints: unknown, carrier: unknown, self: unknown): DeliveryHintIdentities | null;
 /** How a deposit reaches the mediator (RLTP-VTI-3110, 3120). */
 export type SendMode = 'routed' | 'egress-session';
 /** One TSP layer's addressing (no keys, no bytes: those are the wire's). */

package/dist/adapters/vti-mediator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vti-mediator.d.ts","sourceRoot":"","sources":["../../src/adapters/vti-mediator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"vti-mediator.d.ts","sourceRoot":"","sources":["../../src/adapters/vti-mediator.ts"],"names":[],"mappings":"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"}

package/dist/adapters/vti-mediator.js

@@ -20,9 +20,14 @@
 // about transport; the holder's receive core verifies the delivery-ack
 // itself.
 //
-// Profile: spec/adapter-vti-mediator.md v0.24 (twenty-fourth casting;
+// Profile: spec/adapter-vti-mediator.md v0.25 (twenty-fifth casting;
 // round journals under design/adapter-review*). A
-// transport adapter contract — NOT a carrier at the port.
+// transport adapter contract — NOT a carrier at the port. The
+// counterpart's connection DID and egress identity the wire needs come
+// from the counterpart's delivery hint in the card that opened the
+// relationship (profile §1b); the holder hands the hints on uninterpreted
+// (RelationshipView.counterpartDeliveryHints) and this adapter derives its
+// own trio from the relationship's carrier nonce (RelationshipView.carrierNonce).
 //
 // Sending form (profile §3a, lib 0.7.0): every deposit names its mode to
 // the wire. Mode `routed` (the mode of every instance from construction):
@@ -82,7 +87,7 @@
 //   · A retired instance mutates nothing and refuses everything
 //     except reading its ack state.
 import { jcs } from '../core.js';
-import { sha } from '../crypto.js';
+import { anchorOfEd, edRawOfAnchor, sha } from '../crypto.js';
 import { carrierPrincipal, carrierScopedIdentity } from '../carrier-identity.js';
 // ── Declared constants (profile §2) — promises of THIS casting ──────
 // frozen: the declared promises cannot be changed at run time either
@@ -95,6 +100,89 @@ export const DECLARED = Object.freeze({
     duplicateWindowMs: 30 * 86_400_000,
     routedAckDeadlineMs: 72 * 3_600_000,
 });
+const HINT_MEMBERS = jcs(['id', 'rltpEgress', 'serviceEndpoint', 'type']);
+/** An Ed25519 did:key in the form RLTP-VTI-1210 fixes: `did:key:z` and the
+ *  base58btc of multicodec 0xed01 followed by the 32-byte key, rendered
+ *  canonically (decoding and re-encoding gives the same string). */
+const edDidKey = (x) => {
+    // the canonical form has exactly 56 characters; checked first, so no long input reaches the base58 decoder
+    if (typeof x !== 'string' || x.length !== 56)
+        return false;
+    const raw = edRawOfAnchor(x);
+    return raw !== null && anchorOfEd(raw) === x;
+};
+/** This side's hint for carrier `C` in the relationship of carrier nonce
+ *  `N` (RLTP-VTI-1210, 1215): the connection DID and the egress identity
+ *  derived here from (root, `C`, `N`), exactly as the factory derives the
+ *  instance's trio — derived, not supplied, so the two cannot come from
+ *  different relationships — as the JCS form of the TSPTransport service
+ *  entry naming the connection DID (`id`, with `#tsp`), `C`
+ *  (`serviceEndpoint`) and the egress identity (`rltpEgress`). */
+export async function deliveryHint(rootIkm, carrier, nonce) {
+    // snapshot at entry, as create does (R8-B2): a caller's buffer changed
+    // between the two derivations must not couple two relationships
+    const ikm = new Uint8Array(rootIkm);
+    const n = new Uint8Array(nonce);
+    const connection = await carrierScopedIdentity(ikm, carrier, n, 'connection');
+    const egress = await carrierScopedIdentity(ikm, carrier, n, 'egress');
+    return jcs({ id: connection.did + '#tsp', type: 'TSPTransport', serviceEndpoint: carrier, rltpEgress: egress.did });
+}
+/** One hint read strictly (RLTP-VTI-1210, 1220) for carrier `C`: JSON,
+ *  byte-equal to its JCS form, exactly the four members, type
+ *  TSPTransport, an `id` ending in `#tsp`, both identities distinct
+ *  canonical Ed25519 did:key, `serviceEndpoint` byte-equal to `C`.
+ *  Total (RLTP-VTI-1220): any other input — not a string, not JSON, no JCS
+ *  form (a lone surrogate), any other shape — is null, ignored; it never
+ *  throws. */
+export function readDeliveryHint(hint, carrier) {
+    try {
+        return readStrict(hint, carrier);
+    }
+    catch {
+        return null;
+    }
+}
+function readStrict(hint, carrier) {
+    if (typeof hint !== 'string' || typeof carrier !== 'string' || carrier.length === 0)
+        return null;
+    const o = JSON.parse(hint);
+    if (o === null || typeof o !== 'object' || Array.isArray(o) || jcs(o) !== hint)
+        return null;
+    const e = o;
+    if (jcs(Object.keys(e).sort()) !== HINT_MEMBERS || e.type !== 'TSPTransport' || e.serviceEndpoint !== carrier)
+        return null;
+    if (typeof e.id !== 'string' || !e.id.endsWith('#tsp'))
+        return null;
+    const connectionDid = e.id.slice(0, -'#tsp'.length);
+    if (!edDidKey(connectionDid) || !edDidKey(e.rltpEgress) || connectionDid === e.rltpEgress)
+        return null;
+    return { connectionDid, egressDid: e.rltpEgress, carrier };
+}
+/** The counterpart's wire identities at `C` from the hints of the card
+ *  that opened the relationship, read by the side `self` (its own
+ *  connection DID and egress identity of this relationship and carrier):
+ *  every hint read as readDeliveryHint does; a hint naming one of `self`'s
+ *  identities is ignored (RLTP-VTI-1227); of what remains, the one hint
+ *  for `C` (RLTP-VTI-1225, 1240) — none, or more than one, is null: the
+ *  relationship is not carried at `C` (RLTP-VTI-1235). Total: any input
+ *  answers null or the identities, never a throw; without a well-formed
+ *  `self` nothing is read. */
+export function readDeliveryHints(hints, carrier, self) {
+    try {
+        if (!Array.isArray(hints))
+            return null;
+        const me = self;
+        if (me === null || typeof me !== 'object' || !edDidKey(me.connection) || !edDidKey(me.egress))
+            return null;
+        const own = new Set([me.connection, me.egress]);
+        const read = hints.map((h) => readDeliveryHint(h, carrier))
+            .filter((x) => x !== null && !own.has(x.connectionDid) && !own.has(x.egressDid));
+        return read.length === 1 ? read[0] : null;
+    }
+    catch {
+        return null;
+    }
+}
 const SEND_MODES = new Set(['routed', 'egress-session']);
 /** The addressing of a deposit in `mode` (RLTP-VTI-1110, 1120, 3110,
  *  3115, 3120): the inner `direct` message from this side's egress