@aicent/rttp 0.1.2 → 1.2.7

package/README.md

@@ -1,36 +1,40 @@
 # @aicent/rttp
 
-**RTTP for JavaScript: `rttp://` intent addressing, `ROUTE_SHARD` derivation —
+**RTTP for JavaScript: `rttp://` intent addressing, `ROUTE_SHARD` derivation --
 and the published conformance vectors that prove an implementation is right.**
 
-[RFC-002 §10](https://rttp.com/RFC-002/) · v1.2.6 · zero dependencies · no build step
+[RFC-002 sec. 10](https://rttp.com/RFC-002/) - spec v1.2.6 - zero dependencies - no build step
 
 ---
 
-## Verify it in one command — no trust required
+## Verify it in one command -- no trust required
 
 ```console
 $ npx @aicent/rttp
-[PASS] all 25 checks passed (node, independent implementation)
+[PASS] all 35 checks passed (node, independent implementation)
 ```
 
 That is the point of this package. A specification is worth exactly what an
 independent implementation can reproduce from it, so instead of asking you to
 believe a table of numbers, the vectors ship inside the package and replay
-locally — offline, no account, no network. `[PASS]` or it is not.
+locally -- offline, no account, no network. `[PASS]` or it is not. Every vector file shipped here is listed in `vectors.manifest.json` with its byte count and SHA-256, produced by a generator rather than typed by hand - recompute the hash yourself if you prefer.
 
 The JavaScript and Python sides **share no code**. They are separate
 implementations of the same published vectors, and they agree byte for byte.
 
-### The other half — Python, on PyPI
+### The other half -- Python, on PyPI
 
 ```console
 $ pip install rttp
 $ python -m rttp.selftest
-[PASS] all 53 checks passed
+[PASS] all 80 checks passed (3 skipped)   # default install
+
+$ pip install rttp[ed25519]
+$ python -m rttp.selftest
+[PASS] all 83 checks passed               # with the optional Ed25519 backend
 ```
 
-Published as **`rttp`** — the bare name, because PyPI has no scopes and the name
+Published as **`rttp`** -- the bare name, because PyPI has no scopes and the name
 was free. That package ships a **byte-identical copy** of this same vector set and
 replays it offline, exactly as this one does: two registries, two languages, one
 specification.
@@ -71,38 +75,38 @@ $ node examples/quickstart.mjs
 459e543b73d86005b72ba77d5756e83c
 ```
 
-Its expected output is the shard printed above — the value the published
+Its expected output is the shard printed above -- the value the published
 conformance vectors pin for that address, so the example can be **checked**
 rather than believed. It is also the value the Python implementation derives,
 from code that shares nothing with this one.
 
-Addressing is **DNS-free** (RFC-002 §10.5): the routing hash is derived from the
+Addressing is **DNS-free** (RFC-002 sec. 10.5): the routing hash is derived from the
 authority by SHA-256, so no registry, resolver or network is involved. A URI
-either yields a shard or throws — there is no fallback, and no `rttps`.
+either yields a shard or throws -- there is no fallback, and no `rttps`.
 
 ---
 
 ## The one rule that surprises people
 
-**Malformed input is rejected, not normalised.** `rttp://…/VESSEL` and
-`rttp://F3B2A1C4.…/vessel` both throw, because the canonical form is lowercase
-US-ASCII (RFC-002 §10.3) and a case variant is not a spelling difference — it is
+**Malformed input is rejected, not normalised.** `rttp://.../VESSEL` and
+`rttp://F3B2A1C4..../vessel` both throw, because the canonical form is lowercase
+US-ASCII (RFC-002 sec. 10.3) and a case variant is not a spelling difference -- it is
 a *different string*. Admitting both would give one address two spellings, which
-is the ambiguity §10.3 exists to remove.
+is the ambiguity sec. 10.3 exists to remove.
 
 Nothing here is ever accepted because a check could not be performed: this
 package fails closed everywhere.
 
 ---
 
-## The browser's registration prefix — accepted, never advertised
+## The browser's registration prefix -- accepted, never advertised
 
 A browser lets a page register a protocol handler only for a scheme it already
 knows, or for one carrying the browser's own **reserved registration prefix**. So
 the string a web page hands to a handler is not the bare address.
 
 This package **accepts** that form, because refusing a string a browser is about
-to deliver would break the handler path — but it is a **tolerance, and the
+to deliver would break the handler path -- but it is a **tolerance, and the
 specification defines no such form**. The canonical `rttp://` address is what
 this package reports, and the only form it ever emits: same authority, same path,
 same **route shard** either way.
@@ -116,7 +120,7 @@ The `scheme` field tells you which form arrived; everything else is identical.
 
 ---
 
-## API — main entry
+## API -- main entry
 
 | Export | What it does |
 |:---|:---|
@@ -124,14 +128,14 @@ The `scheme` field tells you which form arrived; everything else is identical.
 | `parseAndDerive(uri)` | Identical to `parse`; the specification's own wording. |
 | `deriveRouteShard(authority)` | `Uint8Array(16)` = `SHA-256(ASCII(authority))[0:16]`. |
 | `deriveRouteShardHex(authority)` | The same, as 32 lowercase hex characters. |
-| `isValidAction(value)` | §10.2 `action` form test. The verb set is **open**. |
+| `isValidAction(value)` | sec. 10.2 `action` form test. The verb set is **open**. |
 | `RttpUriError` | The only error type thrown. |
 | `SCHEME`, `BROWSER_HANDLER_SCHEME`, `ROUTE_SHARD_BYTES`, `HASH_INTENT_LEN`, `ACTION_MAX_LEN`, `SPEC_RELEASE` | Constants. |
 
 ### Returned fields
 
 Field names are `snake_case` **on purpose**: the published conformance vectors use
-those names, so this output and the Python package's output compare directly —
+those names, so this output and the Python package's output compare directly --
 field for field, byte for byte.
 
 | Field | Meaning |
@@ -140,7 +144,7 @@ field for field, byte for byte.
 | `intent` | 8 lowercase hex digits (32-bit routing hash) or a readable organ token |
 | `intent_is_hash` / `intent_hash32` | Whether it is a hash-intent, and its value |
 | `pillar`, `root` | The other two authority labels |
-| `action` | Empty string when omitted (RFC-002 §10.4 default operation) |
+| `action` | Empty string when omitted (RFC-002 sec. 10.4 default operation) |
 | `action_omitted` | The same fact as a boolean |
 | `authority` | `<intent>.<pillar>.<root>`, canonical |
 | `canonical_uri` | Always begins `rttp://` |
@@ -148,7 +152,7 @@ field for field, byte for byte.
 
 ---
 
-## The conformance vectors — `@aicent/rttp/conformance`
+## The conformance vectors -- `@aicent/rttp/conformance`
 
 ```js
 import { loadVectors, runConformance } from '@aicent/rttp/conformance';
@@ -172,32 +176,34 @@ In CI:
 
 | Export | What it does |
 |:---|:---|
-| `runConformance(vectors)` | Replay a vector set → `{ checked, failures, passed }` |
+| `runConformance(vectors)` | Replay a vector set -> `{ checked, failures, passed }` |
 | `loadVectors(path?)` | Parse a vector set; defaults to the shipped one |
 | `DEFAULT_VECTORS_PATH` | Absolute path of the shipped `vectors.json` |
-| `parseUri(uri)` | The independent RFC-002 §10.2 implementation → `{ authority, action, shardHex }` |
-| `buildFrame(fields)` | The independent 128-byte frame builder → `Buffer` |
-| `ACTION_MAX_LEN` | `16` — the ACTION field's capacity |
+| `parseUri(uri)` | The independent RFC-002 sec. 10.2 implementation -> `{ authority, action, shardHex }` |
+| `buildFrame(fields)` | The independent 128-byte frame builder -> `Buffer` |
+| `ACTION_MAX_LEN` | `16` -- the ACTION field's capacity |
 
 `vectors.json` is plain JSON and ships inside the package, also reachable as the
 subpath export `@aicent/rttp/vectors.json`. Any language can read it; that is
 what it is for.
 
-### What the 25 checks are
+### What the 35 checks are
 
 | Group | Count | What it proves |
 |:---|:---|---:|
-| `positive_uris` | 6 | Accept, canonicalise and derive — including a hash-intent and an omitted action. **Five are conformance claims; one is a `tolerance`** — the browser-registration prefix — and the vector set labels it as such |
-| `negative_uris` | 15 | **Reject** — uppercase, userinfo, query, fragment, port, multi-segment path, wrong authority shape, trailing slash, foreign scheme, surrounding whitespace |
-| `frame_vectors` | 3 | URI → `ROUTE_SHARD` → the 128-byte `PulseHeader128`, bit for bit |
+| `positive_uris` | 6 | Accept, canonicalise and derive -- including a hash-intent and an omitted action. **Five are conformance claims; one is a `tolerance`** -- the browser-registration prefix -- and the vector set labels it as such |
+| `negative_uris` | 15 | **Reject** -- uppercase, userinfo, query, fragment, port, multi-segment path, wrong authority shape, trailing slash, foreign scheme, surrounding whitespace |
+| `frame_vectors` | 3 | URI -> `ROUTE_SHARD` -> the 128-byte `PulseHeader128`, bit for bit |
 | `compat_vector_spec_rev_0` | 1 | A frame written before the v1.2.6 extension block still verifies |
+| `negative_frames` | 9 | **Reject** -- fail-closed frames: ACTION length/padding/embedded NUL/grammar, unknown SPEC_REV, SPEC_REV=0 with a non-zero extension, non-zero RESERVED, unknown FLAGS bit |
+| `positive_frames` | 1 | Accept -- SPEC_REV=1 with ACTION_LEN=0 is valid and equivalent to an omitted action |
 
 Each vector is deterministic: fixed sequence numbers, fixed timestamp, fixed AID.
 Two implementations either agree byte for byte or they do not.
 
 ### Why the checker lives in this package, and why that is still honest
 
-`src/conformance.mjs` is written from RFC-002 §10 alone and **must never import
+`src/conformance.mjs` is written from RFC-002 sec. 10 alone and **must never import
 `src/rttp-uri.mjs`**. A conformance suite that reuses the code under test only
 proves the code equals itself. The two files share no code, so the rule is
 checkable by reading them.
@@ -209,8 +215,8 @@ not a verification step.
 
 `buildFrame` **refuses** an action longer than the field can hold rather than
 truncating it: a silently shortened verb would be a routing decision made by the
-codec, and the codec does not get to make that decision. (§10.2 sets no length
-limit on `action` — a *parser* must accept a long one; a frame builder cannot.)
+codec, and the codec does not get to make that decision. (sec. 10.2 sets no length
+limit on `action` -- a *parser* must accept a long one; a frame builder cannot.)
 
 The vectors are **generated, not written**. `generated_by` in the JSON names the
 generator, and the file says so itself: change the cases in the generator, not the
@@ -219,19 +225,19 @@ agreeing with its own bugs.
 
 ---
 
-## Scope — what this package is not
+## Scope -- what this package is not
 
 | | |
 |:---|:---|
-| ✅ **Validation** | Real, and specified (RFC-002 §10.2 / §10.3). |
-| ✅ **Canonicalisation** | Real, and specified. |
-| ✅ **ROUTE_SHARD derivation** | Real, and specified. |
-| ✅ **Conformance vectors + independent replay** | Published and generated. |
-| ❌ **Framing, as a library API** | `buildFrame` is exported from `./conformance`, where it exists to replay frame vectors — it is not offered as a general codec. |
-| ❌ **Transport** | Not here. There is no `send()`. |
-| ❌ **Routing service** | Not here. The shard is computed locally; delivering a frame to that hash is an operator's job. |
-| ❌ **Sealing (§11)** | Separate artifacts. |
-| ❌ **Browsers** | Node only — it uses `node:crypto`. The derivation is trivial to reproduce elsewhere, and the vectors let you prove you did. |
+| OK **Validation** | Real, and specified (RFC-002 sec. 10.2 / sec. 10.3). |
+| OK **Canonicalisation** | Real, and specified. |
+| OK **ROUTE_SHARD derivation** | Real, and specified. |
+| OK **Conformance vectors + independent replay** | Published and generated. |
+| NO **Framing, as a library API** | `buildFrame` is exported from `./conformance`, where it exists to replay frame vectors -- it is not offered as a general codec. |
+| NO **Transport** | Not here. There is no `send()`. |
+| NO **Routing service** | Not here. The shard is computed locally; delivering a frame to that hash is an operator's job. |
+| NO **Sealing (sec. 11)** | Separate artifacts. |
+| NO **Browsers** | Node only -- it uses `node:crypto`. The derivation is trivial to reproduce elsewhere, and the vectors let you prove you did. |
 
 ---
 
@@ -240,18 +246,24 @@ agreeing with its own bugs.
 | Ecosystem | Name | Status |
 |:---|:---|:---|
 | crates.io | `rttp` | held by this project |
-| PyPI | `rttp` | **published** — the Python reference implementation; `pip install rttp` |
-| npm | **`@aicent/rttp`** | the bare `rttp` name on npm is held by an unrelated, unmaintained 2017 REST helper, and the `rttp` scope cannot be created at all — a personal account already holds that name. This package is therefore published under the organization this project controls; the package name itself is still just `rttp`. |
+| PyPI | `rttp` | **published** -- the Python reference implementation; `pip install rttp` |
+| npm | **`@aicent/rttp`** | the bare `rttp` name on npm is held by an unrelated, unmaintained 2017 REST helper, and the `rttp` scope cannot be created at all -- a personal account already holds that name. This package is therefore published under the organization this project controls; the package name itself is still just `rttp`. |
 
 ---
 
 ## Specification status
 
-* **`rttp` URI scheme** — submitted to IANA under RFC 7595, ticket **#1459939**,
-  Provisional, **under review**. It is **not yet registered** — as of 2026-09-17
+* **`rttp` URI scheme** -- submitted to IANA under RFC 7595, ticket **#1459939**,
+  Provisional, **under review**. It is **not yet registered** -- as of 2026-09-20
   the IANA "URI Schemes" registry contains no `rttp` entry. Please describe it
   that way.
-* **Frame layout** — RFC-002 §4.1, extended by `SPEC/RTTP-FRAME-EXT-v1.2.6.md`.
+* **Internet-Draft (IETF)** -- the protocol is under IETF review as the
+  Individual Submission Internet-Draft `draft-li-rttp-intent-addressing`
+  (revision -01, posted 2026-09-20, informational):
+  https://datatracker.ietf.org/doc/draft-li-rttp-intent-addressing/ .
+  An Internet-Draft is a working document -- it is not an IETF standard and
+  carries no IETF endorsement.
+* **Frame layout** -- RFC-002 sec. 4.1, extended by `SPEC/RTTP-FRAME-EXT-v1.2.6.md`.
 
 Where this package and the specification disagree, **the specification wins and
 this package is wrong.** Please report it.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aicent/rttp",
-  "version": "0.1.2",
-  "description": "RTTP for JavaScript: rttp:// intent validation, canonicalisation and ROUTE_SHARD derivation (RFC-002 §10), plus the published conformance vectors and an independent replay of them, including the 128-byte frame. Zero dependencies, no build step.",
+  "version": "1.2.7",
+  "description": "RTTP for JavaScript: rttp:// intent validation, canonicalisation and ROUTE_SHARD derivation (RFC-002 sec. 10), plus the published conformance vectors and an independent replay of them, including the 128-byte frame. Zero dependencies, no build step.",
   "keywords": [
     "rttp",
     "uri",

package/src/conformance.d.mts

@@ -95,7 +95,7 @@ export declare const DEFAULT_VECTORS_PATH: string;
 /** The ACTION field is 16 bytes. */
 export declare const ACTION_MAX_LEN: 16;
 
-/** Independent implementation of RFC-002 §10.2. Throws `Error`. */
+/** Independent implementation of RFC-002 sec. 10.2. Throws `Error`. */
 export declare function parseUri(uri: string): ParsedUri;
 
 /** Independent implementation of the 128-byte frame. Throws `Error`. */

package/src/conformance.mjs

@@ -13,7 +13,7 @@
  * imports nothing from `src/rttp-uri.mjs` and must not: a conformance suite that
  * reuses the code it is checking only proves that the code equals itself.
  *
- * Authority boundary: URI syntax = RFC-002 §10.2; frame layout = §4.1 as
+ * Authority boundary: URI syntax = RFC-002 sec. 10.2; frame layout = sec. 4.1 as
  * extended by `SPEC/RTTP-FRAME-EXT-v1.2.6.md`.
  *
  * Zero dependencies: `node:crypto` and `node:fs`, nothing else.
@@ -31,7 +31,7 @@ import { fileURLToPath } from 'node:url';
 export const DEFAULT_VECTORS_PATH = fileURLToPath(new URL('./vectors.json', import.meta.url));
 
 // ---------------------------------------------------------------------------
-// Frame constants (§4.1)
+// Frame constants (sec. 4.1)
 // ---------------------------------------------------------------------------
 
 const MAGIC = 0x52545450;
@@ -42,7 +42,14 @@ const SIZE = 128;
 const OFF_ACTION_LEN = 0x68;
 const OFF_ACTION = 0x69;
 
-/** The ACTION field is 16 bytes; ACTION_LEN is one byte. See RFC-002 §10.2. */
+/** Offsets fixed by RTTP-FRAME-EXT-v1.2.6 sec. 2 (extension block at 0x66..0x7F). */
+const OFF_SPEC_REV = 0x66;
+const OFF_FLAGS = 0x67;
+const OFF_RESERVED = 0x79;
+const KNOWN_SPEC_REVS = new Set([0, 1]);
+const FLAG_URI_ANCHORED = 0x01;
+
+/** The ACTION field is 16 bytes; ACTION_LEN is one byte. See RFC-002 sec. 10.2. */
 export const ACTION_MAX_LEN = 16;
 
 const TOKEN = /^[a-z0-9-]+$/;
@@ -53,7 +60,7 @@ const HASH_INTENT = /^[0-9a-f]{8}$/;
 // ---------------------------------------------------------------------------
 
 /**
- * Parse one `rttp` URI - an implementation written from RFC-002 §10.2 alone,
+ * Parse one `rttp` URI - an implementation written from RFC-002 sec. 10.2 alone,
  * sharing no code with `src/rttp-uri.mjs`.
  *
  * @param {string} uri
@@ -159,6 +166,79 @@ export function buildFrame({ sequenceId, ttl, priority, shardHex, aidHex, timest
   return buf;                                      // 0x79..0x80 RESERVED = 0
 }
 
+/**
+ * Verify a `PulseHeader128`, mirroring the Python `pulse_header.verify`.
+ *
+ * Implements the extension-block rules of RTTP-FRAME-EXT-v1.2.6 sec. 2 / sec. 4
+ * (R2-R7) and the ACTION grammar of RFC-002 sec. 10.2. Every failure throws: a
+ * check that cannot be performed is a failure, never a pass.
+ *
+ * @param {Buffer} raw 128 bytes
+ * @param {{ expectedAidOrigin?: string }} [options]
+ * @returns {{ specRev: number, flags: number, uriAnchored: boolean,
+ *             action: string, actionOmitted: boolean }}
+ */
+export function verifyFrame(raw, options = {}) {
+  if (!Buffer.isBuffer(raw) || raw.length !== SIZE) {
+    throw new Error(`frame must be ${SIZE} bytes`);
+  }
+  if (raw.readUInt32BE(0x00) !== MAGIC) throw new Error('bad RTTP_MAGIC');
+  if (raw.readBigUInt64BE(0x0C) !== VERSION_ID) throw new Error('unsupported VERSION_ID');
+
+  const specRev = raw[OFF_SPEC_REV];
+  if (!KNOWN_SPEC_REVS.has(specRev)) {
+    throw new Error(`unknown SPEC_REV: ${specRev} (fail closed)`);
+  }
+
+  const flags = raw[OFF_FLAGS];
+  const actionLen = raw[OFF_ACTION_LEN];
+
+  if (specRev === 0) {
+    // R6: a pre-v1.2.6 frame must have an all-zero extension block.
+    for (let i = OFF_SPEC_REV; i < SIZE; i += 1) {
+      if (raw[i] !== 0) throw new Error('SPEC_REV=0 but extension block is not all-zero');
+    }
+  } else {
+    // R7: unknown FLAGS bits and any RESERVED byte are rejections.
+    if ((flags & ~FLAG_URI_ANCHORED) !== 0) {
+      throw new Error(`unknown FLAGS bits set: 0x${(flags & ~FLAG_URI_ANCHORED).toString(16).padStart(2, '0')}`);
+    }
+    for (let i = OFF_RESERVED; i < SIZE; i += 1) {
+      if (raw[i] !== 0) throw new Error('RESERVED bytes must be zero in SPEC_REV=1');
+    }
+    // R4: ACTION_LEN is one byte, the field holds 16.
+    if (actionLen > ACTION_MAX_LEN) {
+      throw new Error(`ACTION_LEN ${actionLen} > ${ACTION_MAX_LEN}`);
+    }
+    for (let i = OFF_ACTION + actionLen; i < OFF_ACTION + ACTION_MAX_LEN; i += 1) {
+      if (raw[i] !== 0) throw new Error('ACTION padding must be zero');
+    }
+  }
+
+  let action = '';
+  if (specRev === 1 && actionLen > 0) {
+    action = raw.subarray(OFF_ACTION, OFF_ACTION + actionLen).toString('ascii');
+    if (!TOKEN.test(action)) {
+      throw new Error(`ACTION violates RFC-002 sec. 10.2: ${JSON.stringify(action)}`);
+    }
+  }
+
+  if (options.expectedAidOrigin !== undefined) {
+    const got = raw.subarray(0x46, 0x66).toString('hex');
+    if (got !== options.expectedAidOrigin) {
+      throw new Error('AID_ORIGIN does not match the expected origin');
+    }
+  }
+
+  return {
+    specRev,
+    flags,
+    uriAnchored: (flags & FLAG_URI_ANCHORED) !== 0,
+    action,
+    actionOmitted: action === '',
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Vector loading and replay
 // ---------------------------------------------------------------------------
@@ -219,6 +299,31 @@ export function runConformance(vectors) {
     if (frame.toString('hex') !== c.header_hex) {
       failures.push(`${c.uri} :: frame bytes mismatch`);
     }
+    try {
+      verifyFrame(frame, { expectedAidOrigin: aidHex });
+    } catch (err) {
+      failures.push(`${c.uri} :: published frame rejected by verifyFrame: ${err.message}`);
+    }
+  }
+
+  for (const c of (vectors.negative_frames || [])) {
+    checked += 1;
+    try {
+      verifyFrame(Buffer.from(c.header_hex, 'hex'), { expectedAidOrigin: aidHex });
+      failures.push(`frame ${c.rule} :: ${c.label} :: expected REJECT but accepted`);
+    } catch { /* expected */ }
+  }
+
+  for (const c of (vectors.positive_frames || [])) {
+    checked += 1;
+    try {
+      const got = verifyFrame(Buffer.from(c.header_hex, 'hex'), { expectedAidOrigin: aidHex });
+      if (got.action !== c.action) {
+        failures.push(`frame ${c.rule} :: action ${got.action} != ${c.action}`);
+      }
+    } catch (err) {
+      failures.push(`frame ${c.rule} :: ${c.label} :: expected ACCEPT but rejected: ${err.message}`);
+    }
   }
 
   {
@@ -239,6 +344,14 @@ export function runConformance(vectors) {
     if (frame.toString('hex') !== cv.header_hex) {
       failures.push('compat vector :: frame bytes mismatch');
     }
+    try {
+      const got = verifyFrame(Buffer.from(cv.header_hex, 'hex'), { expectedAidOrigin: aidHex });
+      if (got.specRev !== 0 || !got.actionOmitted) {
+        failures.push('compat vector :: SPEC_REV=0 semantics mismatch');
+      }
+    } catch (err) {
+      failures.push(`compat vector :: verifyFrame rejected an old frame: ${err.message}`);
+    }
   }
 
   return { checked, failures, passed: failures.length === 0 };

package/src/rttp-uri.d.mts

@@ -17,7 +17,7 @@ export interface RttpUri {
   intent_hash32: number | null;
   pillar: string;
   root: string;
-  /** Empty string when omitted (§10.4 default operation). */
+  /** Empty string when omitted (sec. 10.4 default operation). */
   action: string;
   action_omitted: boolean;
   /** `<intent>.<pillar>.<root>`, canonical. */
@@ -30,7 +30,7 @@ export interface RttpUri {
   route_shard_hex: string;
 }
 
-/** The URI does not conform. Always fail closed (§10.5). */
+/** The URI does not conform. Always fail closed (sec. 10.5). */
 export declare class RttpUriError extends Error {
   constructor(message: string);
   name: 'RttpUriError';
@@ -42,7 +42,7 @@ export declare const SCHEME: 'rttp';
 /** The browser protocol-handler form - a property of the client, never of the target. */
 export declare const BROWSER_HANDLER_SCHEME: 'web+rttp';
 
-/** §4.1: ROUTE_SHARD is a u128. */
+/** sec. 4.1: ROUTE_SHARD is a u128. */
 export declare const ROUTE_SHARD_BYTES: 16;
 
 /** Length of a hash-intent, in lowercase hex characters. */
@@ -60,7 +60,7 @@ export declare function parse(uri: string): RttpUri;
 /** Identical to `parse`. */
 export declare function parseAndDerive(uri: string): RttpUri;
 
-/** §10.2 `action` syntax test. Judges form only - the verb set is open. */
+/** sec. 10.2 `action` syntax test. Judges form only - the verb set is open. */
 export declare function isValidAction(value: unknown): boolean;
 
 /** `authority` -> ROUTE_SHARD (16 bytes). Throws `RttpUriError`. */

package/src/rttp-uri.mjs

@@ -1,37 +1,37 @@
 /**
- * @aicent/rttp - RFC-002 §10 `rttp` URI validation, canonicalisation and
+ * @aicent/rttp - RFC-002 sec. 10 `rttp` URI validation, canonicalisation and
  * ROUTE_SHARD derivation.
  *
- * This module is the reference implementation of the mapping RFC-002 §10.4
+ * This module is the reference implementation of the mapping RFC-002 sec. 10.4
  * promises:
  *     "Dereferencing an `rttp` URI emits one pulse ... carrying `action` as the
  *      intent verb."
- * The specification previously had syntax (§10.2 ABNF) but no "URI -> frame
+ * The specification previously had syntax (sec. 10.2 ABNF) but no "URI -> frame
  * field" mapping; this module and `SPEC/RTTP-FRAME-EXT-v1.2.6.md` supply that
  * segment. It is an independent implementation of the same conformance vectors
  * as the Python package `rttp` on PyPI - two implementations that share no code
  * and agree byte for byte is what makes the vectors worth anything.
  *
  * Authority (important):
- *   * URI **syntax** - the sole authority is the RFC-002 §10.2 ABNF. This module
+ *   * URI **syntax** - the sole authority is the RFC-002 sec. 10.2 ABNF. This module
  *     adds no syntax.
  *   * This module does exactly two things: (1) validate and **canonicalise**
- *     per §10.2/§10.3; (2) derive ROUTE_SHARD.
+ *     per sec. 10.2/sec. 10.3; (2) derive ROUTE_SHARD.
  *
  * Design constraints (each is a requirement in the specification):
- *   * §10.1  `intent` is either 8 lowercase hex digits (a 32-bit routing hash)
+ *   * sec. 10.1  `intent` is either 8 lowercase hex digits (a 32-bit routing hash)
  *            or a readable organ token.
- *   * §10.2  `action` is an **open set**: 1*( %x61-7A / DIGIT / "-" ).
- *   * §10.3  The canonical form is **lowercase US-ASCII**; there is no userinfo,
+ *   * sec. 10.2  `action` is an **open set**: 1*( %x61-7A / DIGIT / "-" ).
+ *   * sec. 10.3  The canonical form is **lowercase US-ASCII**; there is no userinfo,
  *            port, query or fragment.
- *   * §10.5  **No DNS**: ROUTE_SHARD is pure computation - no registry, no
+ *   * sec. 10.5  **No DNS**: ROUTE_SHARD is pure computation - no registry, no
  *            resolver, no network.
  *
  * Case is **not** normalised. A case variant is not a spelling difference, it is
- * a different string, and it is rejected (§10.3). Nothing here is ever accepted
+ * a different string, and it is rejected (sec. 10.3). Nothing here is ever accepted
  * because a check could not be performed: this module fails closed.
  *
- * ROUTE_SHARD derivation (see spec §5): the first 16 bytes of
+ * ROUTE_SHARD derivation (see spec sec. 5): the first 16 bytes of
  * SHA-256(ASCII(canonical_authority)).
  *
  * Zero dependencies - `node:crypto` and nothing else.
@@ -54,22 +54,22 @@ export const SCHEME = 'rttp';
  * **client**, never of the target: both spellings name the same address, and the
  * canonical output of this module is always `rttp://`.
  *
- * Accepted for **tolerance only** — the specification defines no such form. A
+ * Accepted for **tolerance only** -- the specification defines no such form. A
  * conforming third-party implementation is not required to reproduce this
  * tolerance; refusing the string a browser is about to deliver would, however,
  * break the handler path.
  */
 export const BROWSER_HANDLER_SCHEME = 'web+rttp';
 
-/** §4.1: ROUTE_SHARD is a u128. */
+/** sec. 4.1: ROUTE_SHARD is a u128. */
 export const ROUTE_SHARD_BYTES = 16;
 
-/** §10.2: `lowhex = %x30-39 / %x61-66`; 8 of them is a 32-bit routing hash. */
+/** sec. 10.2: `lowhex = %x30-39 / %x61-66`; 8 of them is a 32-bit routing hash. */
 export const HASH_INTENT_LEN = 8;
 
 /**
  * The capacity of the frame's ACTION field (`0x69`..`0x78`, one byte of
- * ACTION_LEN at `0x68`). **Not** a syntax rule: §10.2 places no length limit on
+ * ACTION_LEN at `0x68`). **Not** a syntax rule: sec. 10.2 places no length limit on
  * `action`, so `parse()` accepts longer values. A frame builder must reject
  * them, because the field cannot hold more.
  */
@@ -78,11 +78,11 @@ export const ACTION_MAX_LEN = 16;
 /** The RTTP specification release this module was written against. */
 export const SPEC_RELEASE = 'v1.2.6';
 
-// §10.2: name-intent / pillar / root / action = 1*( %x61-7A / DIGIT / "-" )
+// sec. 10.2: name-intent / pillar / root / action = 1*( %x61-7A / DIGIT / "-" )
 const TOKEN = /^[a-z0-9-]+$/;
 const LOWHEX = /^[0-9a-f]+$/;
 
-// §10.3: this scheme defines no userinfo / port / query / fragment
+// sec. 10.3: this scheme defines no userinfo / port / query / fragment
 const FORBIDDEN_CHARS = ['@', '?', '#', '[', ']'];
 
 // ---------------------------------------------------------------------------
@@ -90,7 +90,7 @@ const FORBIDDEN_CHARS = ['@', '?', '#', '[', ']'];
 // ---------------------------------------------------------------------------
 
 /**
- * The URI does not conform. **Always fail closed** (§10.5: no fallback, and no
+ * The URI does not conform. **Always fail closed** (sec. 10.5: no fallback, and no
  * `rttps`).
  */
 export class RttpUriError extends Error {
@@ -105,7 +105,7 @@ export class RttpUriError extends Error {
 // ---------------------------------------------------------------------------
 
 /**
- * §10.2 token check, with the case rule of §10.3 kept separate so that an
+ * sec. 10.2 token check, with the case rule of sec. 10.3 kept separate so that an
  * uppercase letter produces a message that says what is actually wrong.
  *
  * @param {string} value
@@ -118,10 +118,10 @@ function checkToken(value, what) {
   for (const ch of value) {
     if (TOKEN.test(ch)) continue;
     if (ch !== ch.toLowerCase()) {
-      // §10.3: the canonical form is lowercase. Uppercase is not a normalisable
+      // sec. 10.3: the canonical form is lowercase. Uppercase is not a normalisable
       // spelling difference - it is illegal input.
       throw new RttpUriError(
-        `${what} contains uppercase '${ch}' - lowercase US-ASCII only (RFC-002 §10.3)`);
+        `${what} contains uppercase '${ch}' - lowercase US-ASCII only (RFC-002 sec. 10.3)`);
     }
     throw new RttpUriError(
       `${what} contains illegal character ${JSON.stringify(ch)} (allowed: a-z, 0-9, '-')`);
@@ -142,7 +142,7 @@ function checkIntent(value) {
 }
 
 /**
- * §10.2 `action` syntax test: 1*( %x61-7A / DIGIT / "-" ).
+ * sec. 10.2 `action` syntax test: 1*( %x61-7A / DIGIT / "-" ).
  *
  * `action` is an **open set** - this only judges the *form*, never whether the
  * verb is one this specification knows. Frame builders reuse it so the rule is
@@ -168,10 +168,10 @@ export function isValidAction(value) {
  *
  * Properties:
  *   * **Deterministic** - one authority always yields one shard.
- *   * **Pure computation** - no DNS, no registry, no network (§10.5).
+ *   * **Pure computation** - no DNS, no registry, no network (sec. 10.5).
  *   * **One-way** - the authority cannot be recovered from the shard.
  *   * **Independent of `action`** - it routes *where*, never *what*, which is
- *     exactly why `action` must be a separate frame field (see spec §5.3).
+ *     exactly why `action` must be a separate frame field (see spec sec. 5.3).
  *
  * @param {string} canonicalAuthority
  * @returns {Uint8Array} 16 bytes
@@ -181,7 +181,7 @@ export function deriveRouteShard(canonicalAuthority) {
     throw new RttpUriError('canonical_authority is empty');
   }
   if (canonicalAuthority !== canonicalAuthority.toLowerCase()) {
-    throw new RttpUriError('canonical_authority must be lowercase (RFC-002 §10.3)');
+    throw new RttpUriError('canonical_authority must be lowercase (RFC-002 sec. 10.3)');
   }
   const digest = createHash('sha256')
     .update(Buffer.from(canonicalAuthority, 'ascii'))
@@ -206,7 +206,7 @@ export function deriveRouteShardHex(canonicalAuthority) {
  *
  * The validation order deliberately stays "reject before interpreting": any
  * suspicious form throws immediately, and nothing is ever guessed at.
- * (§10.5: user agents that do not implement this scheme fail closed.)
+ * (sec. 10.5: user agents that do not implement this scheme fail closed.)
  *
  * Field names are `snake_case` on purpose: the published conformance vectors use
  * those names, so the output of the Python and JavaScript implementations
@@ -241,7 +241,7 @@ export function parse(uri) {
     throw new RttpUriError('uri must not contain leading/trailing whitespace');
   }
 
-  // --- scheme (§10.6 prefix whitelist) ---
+  // --- scheme (sec. 10.6 prefix whitelist) ---
   let scheme;
   let rest;
   if (uri.startsWith(`${BROWSER_HANDLER_SCHEME}://`)) {
@@ -255,7 +255,7 @@ export function parse(uri) {
       `not an rttp URI: must begin with '${SCHEME}://' or '${BROWSER_HANDLER_SCHEME}://'`);
   }
 
-  // --- §10.3 excluded characters ---
+  // --- sec. 10.3 excluded characters ---
   for (const ch of FORBIDDEN_CHARS) {
     if (uri.includes(ch)) {
       throw new RttpUriError(
@@ -273,7 +273,7 @@ export function parse(uri) {
     throw new RttpUriError("path must be a single segment '/<action>'");
   }
   if (slash !== -1 && action === '') {
-    // §10.2: path = "/" action, action = 1*(...). A trailing slash with an empty
+    // sec. 10.2: path = "/" action, action = 1*(...). A trailing slash with an empty
     // action is a different form from "no path", and the two must not be
     // conflated.
     throw new RttpUriError("trailing '/' with empty action: path must be '/<action>'");

package/src/vectors.json

@@ -1,8 +1,8 @@
 {
   "spec": "RTTP-FRAME-EXT-v1.2.6",
   "applies_to": [
-    "RFC-002 §4.1",
-    "RFC-002 §10"
+    "RFC-002 sec. 4.1",
+    "RFC-002 sec. 10"
   ],
   "generated_by": "SPEC/tools/conformance.py",
   "note": "Generated file - do not edit by hand. Change the cases in conformance.py instead.",
@@ -78,7 +78,7 @@
       "action_omitted": false,
       "route_shard_hex": "cdc32d19641c84aca3292de6276de056",
       "tolerance": true,
-      "note": "tolerance - the specification defines no such form; accepted because it is the scheme name under which a handler is registered (RFC-002 §10.6)"
+      "note": "tolerance - the specification defines no such form; accepted because it is the scheme name under which a handler is registered (RFC-002 sec. 10.6)"
     },
     {
       "uri": "rttp://a-b-c.d-e.f-g/audit-v2",
@@ -98,35 +98,35 @@
   "negative_uris": [
     {
       "uri": "rttp://f3b2a1c4.rttp.aicent/VESSEL",
-      "reason": "uppercase action - lowercase only (RFC-002 §10.3)"
+      "reason": "uppercase action - lowercase only (RFC-002 sec. 10.3)"
     },
     {
       "uri": "rttp://F3B2A1C4.rttp.aicent/vessel",
-      "reason": "uppercase intent - lowercase only (RFC-002 §10.3)"
+      "reason": "uppercase intent - lowercase only (RFC-002 sec. 10.3)"
     },
     {
       "uri": "RTTP://f3b2a1c4.rttp.aicent/vessel",
-      "reason": "uppercase scheme prefix - canonical form is lowercase (RFC-002 §10.3)"
+      "reason": "uppercase scheme prefix - canonical form is lowercase (RFC-002 sec. 10.3)"
     },
     {
       "uri": "WEB+RTTP://f3b2a1c4.rttp.aicent/vessel",
-      "reason": "uppercase scheme prefix on the handler form (RFC-002 §10.3)"
+      "reason": "uppercase scheme prefix on the handler form (RFC-002 sec. 10.3)"
     },
     {
       "uri": "rttp://subject@rttp.aicent/vessel",
-      "reason": "userinfo is not defined (RFC-002 §10.3)"
+      "reason": "userinfo is not defined (RFC-002 sec. 10.3)"
     },
     {
       "uri": "rttp://f3b2a1c4.rttp.aicent/vessel?x=1",
-      "reason": "query is not defined (RFC-002 §10.3)"
+      "reason": "query is not defined (RFC-002 sec. 10.3)"
     },
     {
       "uri": "rttp://f3b2a1c4.rttp.aicent/vessel#f",
-      "reason": "fragment is not defined (RFC-002 §10.3)"
+      "reason": "fragment is not defined (RFC-002 sec. 10.3)"
     },
     {
       "uri": "rttp://f3b2a1c4.rttp.aicent:443/vessel",
-      "reason": "port is not defined (RFC-002 §10.3)"
+      "reason": "port is not defined (RFC-002 sec. 10.3)"
     },
     {
       "uri": "rttp://f3b2a1c4.rttp.aicent/a/b",
@@ -146,7 +146,7 @@
     },
     {
       "uri": "https://f3b2a1c4.rttp.aicent/vessel",
-      "reason": "not an rttp scheme - there is no fallback (RFC-002 §10.5)"
+      "reason": "not an rttp scheme - there is no fallback (RFC-002 sec. 10.5)"
     },
     {
       "uri": "rttp://f3b2a1c4.rttp.aicent/vessel ",
@@ -198,13 +198,103 @@
       "header_hex": "5254545000000000000000000000000000000082000000000000000000000000000000030000000000000000186cc6acd4b0000080ffbf77b78ff6ceafc363226aa5865622185d42ba8b38fe10bfa702bdfe6af536ea16e20e35fbb48d84c3658d80cad2789d0101000000000000000000000000000000000000000000000000"
     }
   ],
+  "negative_frames": [
+    {
+      "label": "ACTION_LEN exceeds the 16-byte maximum (17)",
+      "rule": "R4",
+      "spec_ref": "RTTP-FRAME-EXT-v1.2.6 sec. 3.2",
+      "expected": "reject",
+      "header_hex": "5254545000000000000000000000000000000082000000000000000000000000000000010000000000000000186cc6acd4b00000ff01bf77b78ff6ceafc363226aa5865622185d42ba8b38fe10bfa702bdfe6af536ea16e20e35fbb48d84c3658d80cad2789d01011176657373656c0000000000000000000000000000000000"
+    },
+    {
+      "label": "ACTION padding is non-zero",
+      "rule": "R4",
+      "spec_ref": "RTTP-FRAME-EXT-v1.2.6 sec. 3.2",
+      "expected": "reject",
+      "header_hex": "5254545000000000000000000000000000000082000000000000000000000000000000010000000000000000186cc6acd4b00000ff01bf77b78ff6ceafc363226aa5865622185d42ba8b38fe10bfa702bdfe6af536ea16e20e35fbb48d84c3658d80cad2789d01010676657373656c0078000000000000000000000000000000"
+    },
+    {
+      "label": "ACTION contains an embedded NUL",
+      "rule": "R4",
+      "spec_ref": "RTTP-FRAME-EXT-v1.2.6 sec. 3.2",
+      "expected": "reject",
+      "header_hex": "5254545000000000000000000000000000000082000000000000000000000000000000010000000000000000186cc6acd4b00000ff01bf77b78ff6ceafc363226aa5865622185d42ba8b38fe10bfa702bdfe6af536ea16e20e35fbb48d84c3658d80cad2789d01010676657300656c0000000000000000000000000000000000"
+    },
+    {
+      "label": "ACTION violates the sec. 10.2 grammar (uppercase)",
+      "rule": "R4",
+      "spec_ref": "RTTP-FRAME-EXT-v1.2.6 sec. 3.2",
+      "expected": "reject",
+      "header_hex": "5254545000000000000000000000000000000082000000000000000000000000000000010000000000000000186cc6acd4b00000ff01bf77b78ff6ceafc363226aa5865622185d42ba8b38fe10bfa702bdfe6af536ea16e20e35fbb48d84c3658d80cad2789d01010656455353454c0000000000000000000000000000000000"
+    },
+    {
+      "label": "SPEC_REV is outside the known set (2)",
+      "rule": "R5",
+      "spec_ref": "RTTP-FRAME-EXT-v1.2.6 sec. 4",
+      "expected": "reject",
+      "header_hex": "5254545000000000000000000000000000000082000000000000000000000000000000010000000000000000186cc6acd4b00000ff01bf77b78ff6ceafc363226aa5865622185d42ba8b38fe10bfa702bdfe6af536ea16e20e35fbb48d84c3658d80cad2789d02010676657373656c0000000000000000000000000000000000"
+    },
+    {
+      "label": "SPEC_REV is outside the known set (255)",
+      "rule": "R5",
+      "spec_ref": "RTTP-FRAME-EXT-v1.2.6 sec. 4",
+      "expected": "reject",
+      "header_hex": "5254545000000000000000000000000000000082000000000000000000000000000000010000000000000000186cc6acd4b00000ff01bf77b78ff6ceafc363226aa5865622185d42ba8b38fe10bfa702bdfe6af536ea16e20e35fbb48d84c3658d80cad2789dff010676657373656c0000000000000000000000000000000000"
+    },
+    {
+      "label": "SPEC_REV=0 with a non-zero extension block",
+      "rule": "R6",
+      "spec_ref": "RTTP-FRAME-EXT-v1.2.6 sec. 4",
+      "expected": "reject",
+      "header_hex": "5254545000000000000000000000000000000082000000000000000000000000000000010000000000000000186cc6acd4b00000ff01bf77b78ff6ceafc363226aa5865622185d42ba8b38fe10bfa702bdfe6af536ea16e20e35fbb48d84c3658d80cad2789d00010676657373656c0000000000000000000000000000000000"
+    },
+    {
+      "label": "RESERVED is non-zero under SPEC_REV=1",
+      "rule": "R7",
+      "spec_ref": "RTTP-FRAME-EXT-v1.2.6 sec. 4",
+      "expected": "reject",
+      "header_hex": "5254545000000000000000000000000000000082000000000000000000000000000000010000000000000000186cc6acd4b00000ff01bf77b78ff6ceafc363226aa5865622185d42ba8b38fe10bfa702bdfe6af536ea16e20e35fbb48d84c3658d80cad2789d01010676657373656c0000000000000000000001000000000000"
+    },
+    {
+      "label": "unknown FLAGS bit set under SPEC_REV=1",
+      "rule": "R7",
+      "spec_ref": "RTTP-FRAME-EXT-v1.2.6 sec. 4",
+      "expected": "reject",
+      "header_hex": "5254545000000000000000000000000000000082000000000000000000000000000000010000000000000000186cc6acd4b00000ff01bf77b78ff6ceafc363226aa5865622185d42ba8b38fe10bfa702bdfe6af536ea16e20e35fbb48d84c3658d80cad2789d01030676657373656c0000000000000000000000000000000000"
+    }
+  ],
+  "positive_frames": [
+    {
+      "label": "SPEC_REV=1 with ACTION_LEN=0 is valid and equivalent to omission",
+      "rule": "R3",
+      "spec_ref": "RTTP-FRAME-EXT-v1.2.6 sec. 4",
+      "expected": "accept",
+      "action": "",
+      "header_hex": "5254545000000000000000000000000000000082000000000000000000000000000000010000000000000000186cc6acd4b00000ff01bf77b78ff6ceafc363226aa5865622185d42ba8b38fe10bfa702bdfe6af536ea16e20e35fbb48d84c3658d80cad2789d0101000000000000000000000000000000000000000000000000"
+    }
+  ],
+  "envelope_vector": {
+    "spec": "RTTP-SEAL-ENVELOPE-v1.2.6 sec. 7",
+    "alg": "ed25519",
+    "seed_hex": "e722fed924c7f76b157faab674ea97bb7c3075f55ad7d3c6319418e22b86d611",
+    "aid": "3125ee20b2238281f70ca408192f82152647d365219184fa1fe22c08a42c035e",
+    "pub": "9c097c66ab4f82136ceddaef56854f740bf87da3eec42a249ba40bbb066f1e6a",
+    "ts": 1760000000,
+    "nonce": "0011223344556677",
+    "payload": {
+      "intent": "verify",
+      "task_id": "selftest-0001"
+    },
+    "signing_input_hex": "727474702d7365616c2d76310a7b22616964223a2233313235656532306232323338323831663730636134303831393266383231353236343764333635323139313834666131666532326330386134326330333565222c22616c67223a2265643235353139222c226e6f6e6365223a2230303131323233333434353536363737222c227061796c6f6164223a7b22696e74656e74223a22766572696679222c227461736b5f6964223a2273656c66746573742d30303031227d2c22707562223a2239633039376336366162346638323133366365646461656635363835346637343062663837646133656563343261323439626134306262623036366631653661222c227473223a313736303030303030307d",
+    "sig": "8d8e0d458b1defb6fd078343e7e46fc96cbaa05b6ead9e587d324e4c2358145790042f4a5001f3d902e7da670e2ea5700903363dd2825159a25dc262b25cb305"
+  },
   "compat_vector_spec_rev_0": {
     "uri": "rttp://f3b2a1c4.rttp.aicent/vessel",
     "spec_rev": 0,
     "action": "",
     "action_omitted": true,
     "uri_anchored": false,
-    "expected": "verify() MUST accept; action is treated as omitted (RFC-002 §10.4 default operation)",
+    "expected": "verify() MUST accept; action is treated as omitted (RFC-002 sec. 10.4 default operation)",
     "header_hex": "5254545000000000000000000000000000000082000000000000000000000000000000010000000000000000186cc6acd4b00000ff01bf77b78ff6ceafc363226aa5865622185d42ba8b38fe10bfa702bdfe6af536ea16e20e35fbb48d84c3658d80cad2789d0000000000000000000000000000000000000000000000000000"
   }
 }