@aicent/rttp 0.1.0

package/src/conformance.mjs

@@ -0,0 +1,243 @@
+/**
+ * @aicent/rttp/conformance - the RTTP conformance vectors, and their replay.
+ *
+ * Why this package exists
+ * -----------------------
+ * A specification is worth exactly what an independent implementation can
+ * reproduce from it. Two implementations that share no code, given the same
+ * vectors, must produce bit-identical output; one implementation agreeing with
+ * itself proves nothing.
+ *
+ * This module is therefore an **independent second implementation** of the same
+ * vectors as `SPEC/tools/conformance.py` on the Python side. It deliberately
+ * 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
+ * extended by `SPEC/RTTP-FRAME-EXT-v1.2.6.md`.
+ *
+ * Zero dependencies: `node:crypto` and `node:fs`, nothing else.
+ */
+
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * The vector set shipped inside this package. Loading it with `readFileSync`
+ * keeps this package importable from plain ESM without JSON import attributes,
+ * and lets a caller replay a *newer* vector set without reinstalling.
+ */
+export const DEFAULT_VECTORS_PATH = fileURLToPath(new URL('./vectors.json', import.meta.url));
+
+// ---------------------------------------------------------------------------
+// Frame constants (§4.1)
+// ---------------------------------------------------------------------------
+
+const MAGIC = 0x52545450;
+const VERSION_ID = 130n;
+const SIZE = 128;
+
+/** Offset of ACTION_LEN and of the ACTION field itself. */
+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. */
+export const ACTION_MAX_LEN = 16;
+
+const TOKEN = /^[a-z0-9-]+$/;
+const HASH_INTENT = /^[0-9a-f]{8}$/;
+
+// ---------------------------------------------------------------------------
+// Independent implementation: URI parsing + canonicalisation
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse one `rttp` URI - an implementation written from RFC-002 §10.2 alone,
+ * sharing no code with `src/rttp-uri.mjs`.
+ *
+ * @param {string} uri
+ * @returns {{ authority: string, action: string, shardHex: string }}
+ */
+export function parseUri(uri) {
+  if (typeof uri !== 'string' || uri === '') throw new Error('empty uri');
+  if (uri !== uri.trim()) throw new Error('leading/trailing whitespace');
+
+  let rest;
+  if (uri.startsWith('web+rttp://')) rest = uri.slice(11);
+  else if (uri.startsWith('rttp://')) rest = uri.slice(7);
+  else throw new Error('scheme must be rttp:// or web+rttp://');
+
+  for (const ch of ['@', '?', '#', '[', ']']) {
+    if (uri.includes(ch)) throw new Error(`illegal char ${ch}`);
+  }
+
+  const slash = rest.indexOf('/');
+  let authority;
+  let action = '';
+  if (slash === -1) {
+    authority = rest;
+  } else {
+    authority = rest.slice(0, slash);
+    action = rest.slice(slash + 1);
+    if (action.includes('/')) throw new Error('path must be one segment');
+    if (action === '') throw new Error('trailing slash with empty action');
+  }
+
+  const parts = authority.split('.');
+  if (parts.length !== 3) throw new Error('authority must be intent.pillar.root');
+  const [intent, pillar, root] = parts;
+
+  const isHash = HASH_INTENT.test(intent);
+  if (!isHash && !TOKEN.test(intent)) throw new Error('bad intent');
+  if (!TOKEN.test(pillar)) throw new Error('bad pillar');
+  if (!TOKEN.test(root)) throw new Error('bad root');
+  if (action !== '' && !TOKEN.test(action)) throw new Error('bad action');
+
+  for (const [value, name] of [[intent, 'intent'], [pillar, 'pillar'], [root, 'root']]) {
+    if (value.startsWith('-') || value.endsWith('-')) {
+      throw new Error(`${name} must not begin/end with '-'`);
+    }
+  }
+  if (action !== '' && (action.startsWith('-') || action.endsWith('-'))) {
+    throw new Error("action must not begin/end with '-'");
+  }
+
+  const canonicalAuthority = `${intent}.${pillar}.${root}`;
+  const shard = createHash('sha256')
+    .update(canonicalAuthority, 'ascii').digest().subarray(0, 16);
+
+  return { authority: canonicalAuthority, action, shardHex: shard.toString('hex') };
+}
+
+// ---------------------------------------------------------------------------
+// Independent implementation: the 128-byte frame
+// ---------------------------------------------------------------------------
+
+/**
+ * Build one `PulseHeader128` from a URI and the vector's frame fields.
+ *
+ * Refuses an `action` that cannot fit the field 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.
+ *
+ * @param {{
+ *   sequenceId: number|string|bigint, ttl: number, priority: number,
+ *   shardHex: string, aidHex: string, timestampNs: number|string|bigint,
+ *   action: string, uriAnchored: boolean
+ * }} fields
+ * @returns {Buffer} 128 bytes
+ */
+export function buildFrame({ sequenceId, ttl, priority, shardHex, aidHex, timestampNs, action, uriAnchored }) {
+  const actionBytes = Buffer.from(action, 'ascii');
+  if (actionBytes.length > ACTION_MAX_LEN) {
+    throw new Error(`action is ${actionBytes.length} bytes; the field holds ${ACTION_MAX_LEN}`);
+  }
+  if (shardHex.length !== 32) throw new Error('ROUTE_SHARD must be 32 hex characters');
+  if (aidHex.length !== 64) throw new Error('AID_ORIGIN must be 64 hex characters');
+
+  const buf = Buffer.alloc(SIZE);
+  buf.writeUInt32BE(MAGIC, 0x00);
+  buf.writeBigUInt64BE(0n, 0x04);                  // VERSION_ID u128 high half
+  buf.writeBigUInt64BE(VERSION_ID, 0x0C);          // VERSION_ID = 130
+  const seq = BigInt(sequenceId);
+  buf.writeBigUInt64BE(seq >> 64n, 0x14);          // SEQUENCE_ID u128
+  buf.writeBigUInt64BE(seq & 0xFFFFFFFFFFFFFFFFn, 0x1C);
+  const ts = BigInt(timestampNs);
+  buf.writeBigUInt64BE(ts >> 64n, 0x24);           // TIMESTAMP u128
+  buf.writeBigUInt64BE(ts & 0xFFFFFFFFFFFFFFFFn, 0x2C);
+  buf.writeUInt8(ttl & 0xFF, 0x34);                // TTL_PULSE
+  buf.writeUInt8(priority & 0xFF, 0x35);           // PRIORITY
+  Buffer.from(shardHex, 'hex').copy(buf, 0x36);    // ROUTE_SHARD u128
+  Buffer.from(aidHex, 'hex').copy(buf, 0x46);      // AID_ORIGIN 256-bit
+  buf[0x66] = 1;                                   // SPEC_REV
+  buf[0x67] = uriAnchored ? 1 : 0;                 // FLAGS
+  buf[OFF_ACTION_LEN] = actionBytes.length;        // ACTION_LEN
+  actionBytes.copy(buf, OFF_ACTION);               // ACTION (zero-padded)
+  return buf;                                      // 0x79..0x80 RESERVED = 0
+}
+
+// ---------------------------------------------------------------------------
+// Vector loading and replay
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {string} [path] defaults to the vector set shipped with this package
+ * @returns {object} the parsed vector set
+ */
+export function loadVectors(path = DEFAULT_VECTORS_PATH) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+/**
+ * Replay a vector set against the independent implementations above.
+ *
+ * @param {object} vectors
+ * @returns {{ checked: number, failures: string[], passed: boolean }}
+ */
+export function runConformance(vectors) {
+  const failures = [];
+  let checked = 0;
+
+  for (const c of vectors.positive_uris) {
+    checked += 1;
+    try {
+      const got = parseUri(c.uri);
+      if (got.authority !== c.authority) failures.push(`${c.uri} :: authority ${got.authority} != ${c.authority}`);
+      if (got.action !== c.action) failures.push(`${c.uri} :: action ${got.action} != ${c.action}`);
+      if (got.shardHex !== c.route_shard_hex) failures.push(`${c.uri} :: shard ${got.shardHex} != ${c.route_shard_hex}`);
+    } catch (err) {
+      failures.push(`${c.uri} :: expected ACCEPT but threw: ${err.message}`);
+    }
+  }
+
+  for (const c of vectors.negative_uris) {
+    checked += 1;
+    try {
+      parseUri(c.uri);
+      failures.push(`${c.uri} :: expected REJECT but parsed`);
+    } catch { /* expected */ }
+  }
+
+  const aidHex = vectors.frame_vectors[0].aid_origin_hex;
+
+  for (const c of vectors.frame_vectors) {
+    checked += 1;
+    const { shardHex, action } = parseUri(c.uri);
+    const frame = buildFrame({
+      sequenceId: c.sequence_id,
+      ttl: c.ttl,
+      priority: c.priority,
+      shardHex,
+      aidHex,
+      timestampNs: c.timestamp_ns,
+      action,
+      uriAnchored: true,
+    });
+    if (frame.toString('hex') !== c.header_hex) {
+      failures.push(`${c.uri} :: frame bytes mismatch`);
+    }
+  }
+
+  {
+    checked += 1;
+    const cv = vectors.compat_vector_spec_rev_0;
+    const { shardHex, action } = parseUri(cv.uri);
+    const frame = buildFrame({
+      sequenceId: vectors.frame_vectors[0].sequence_id,
+      ttl: vectors.frame_vectors[0].ttl,
+      priority: vectors.frame_vectors[0].priority,
+      shardHex,
+      aidHex,
+      timestampNs: vectors.frame_vectors[0].timestamp_ns,
+      action,
+      uriAnchored: true,
+    });
+    frame.fill(0, 0x66, SIZE);  // SPEC_REV=0: the extension block is all zero
+    if (frame.toString('hex') !== cv.header_hex) {
+      failures.push('compat vector :: frame bytes mismatch');
+    }
+  }
+
+  return { checked, failures, passed: failures.length === 0 };
+}

package/src/rttp-uri.d.mts

@@ -0,0 +1,70 @@
+/**
+ * Type declarations for @aicent/rttp (main entry).
+ *
+ * Hand-written so the package stays build-free: the published `src/` is exactly
+ * what runs, and exactly what a reviewer reads.
+ */
+
+/** The canonical field set of a parsed `rttp` URI. */
+export interface RttpUri {
+  /** `rttp` for the canonical form, `web+rttp` when the input used the browser-handler prefix. */
+  scheme: 'rttp' | 'web+rttp';
+  /** 8 lowercase hex digits (32-bit routing hash) or a readable organ token. */
+  intent: string;
+  /** True when `intent` is a hash-intent. */
+  intent_is_hash: boolean;
+  /** `intent` read as a 32-bit routing hash; `null` when it is a name. */
+  intent_hash32: number | null;
+  pillar: string;
+  root: string;
+  /** Empty string when omitted (§10.4 default operation). */
+  action: string;
+  action_omitted: boolean;
+  /** `<intent>.<pillar>.<root>`, canonical. */
+  authority: string;
+  /** Always starts `rttp://`, whatever prefix the input used. */
+  canonical_uri: string;
+  /** 16 bytes, SHA-256(authority)[0:16]. */
+  route_shard: Uint8Array;
+  /** The same 16 bytes as 32 lowercase hex characters. */
+  route_shard_hex: string;
+}
+
+/** The URI does not conform. Always fail closed (§10.5). */
+export declare class RttpUriError extends Error {
+  constructor(message: string);
+  name: 'RttpUriError';
+}
+
+/** The canonical scheme name. */
+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. */
+export declare const ROUTE_SHARD_BYTES: 16;
+
+/** Length of a hash-intent, in lowercase hex characters. */
+export declare const HASH_INTENT_LEN: 8;
+
+/** Capacity of the frame's ACTION field. Not a syntax rule - see the README. */
+export declare const ACTION_MAX_LEN: 16;
+
+/** The RTTP specification release this module was written against. */
+export declare const SPEC_RELEASE: string;
+
+/** Parse one `rttp` URI and return its canonical fields. Throws `RttpUriError`. */
+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. */
+export declare function isValidAction(value: unknown): boolean;
+
+/** `authority` -> ROUTE_SHARD (16 bytes). Throws `RttpUriError`. */
+export declare function deriveRouteShard(canonicalAuthority: string): Uint8Array;
+
+/** `authority` -> ROUTE_SHARD as 32 lowercase hex characters. */
+export declare function deriveRouteShardHex(canonicalAuthority: string): string;

package/src/rttp-uri.mjs

@@ -0,0 +1,322 @@
+/**
+ * @aicent/rttp - RFC-002 §10 `rttp` URI validation, canonicalisation and
+ * ROUTE_SHARD derivation.
+ *
+ * This module is the reference implementation of the mapping RFC-002 §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
+ * 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
+ *     adds no syntax.
+ *   * This module does exactly two things: (1) validate and **canonicalise**
+ *     per §10.2/§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)
+ *            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,
+ *            port, query or fragment.
+ *   * §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
+ * because a check could not be performed: this module fails closed.
+ *
+ * ROUTE_SHARD derivation (see spec §5): the first 16 bytes of
+ * SHA-256(ASCII(canonical_authority)).
+ *
+ * Zero dependencies - `node:crypto` and nothing else.
+ *
+ * @see https://rttp.com/RFC-002/
+ */
+
+import { createHash } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** The canonical scheme name. */
+export const SCHEME = 'rttp';
+
+/**
+ * The browser protocol-handler form. A user agent accepts
+ * `navigator.registerProtocolHandler()` only for schemes on its safelisted set,
+ * or for a scheme beginning `web+`, so a web page must use this prefix to
+ * register an `rttp` handler (RFC-002 §10.6). It is a property of the **client**,
+ * never of the target: both forms are the same address, and the canonical output
+ * of this module is always `rttp://`.
+ */
+export const BROWSER_HANDLER_SCHEME = 'web+rttp';
+
+/** §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. */
+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`, so `parse()` accepts longer values. A frame builder must reject
+ * them, because the field cannot hold more.
+ */
+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 / "-" )
+const TOKEN = /^[a-z0-9-]+$/;
+const LOWHEX = /^[0-9a-f]+$/;
+
+// §10.3: this scheme defines no userinfo / port / query / fragment
+const FORBIDDEN_CHARS = ['@', '?', '#', '[', ']'];
+
+// ---------------------------------------------------------------------------
+// Error
+// ---------------------------------------------------------------------------
+
+/**
+ * The URI does not conform. **Always fail closed** (§10.5: no fallback, and no
+ * `rttps`).
+ */
+export class RttpUriError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'RttpUriError';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * §10.2 token check, with the case rule of §10.3 kept separate so that an
+ * uppercase letter produces a message that says what is actually wrong.
+ *
+ * @param {string} value
+ * @param {string} what  field name, for the error message
+ */
+function checkToken(value, what) {
+  if (typeof value !== 'string' || value === '') {
+    throw new RttpUriError(`${what} is empty`);
+  }
+  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
+      // spelling difference - it is illegal input.
+      throw new RttpUriError(
+        `${what} contains uppercase '${ch}' - lowercase US-ASCII only (RFC-002 §10.3)`);
+    }
+    throw new RttpUriError(
+      `${what} contains illegal character ${JSON.stringify(ch)} (allowed: a-z, 0-9, '-')`);
+  }
+  if (value.startsWith('-') || value.endsWith('-')) {
+    throw new RttpUriError(`${what} must not begin or end with '-'`);
+  }
+}
+
+/**
+ * @param {string} value
+ * @returns {boolean} true for a hash-intent (8 lowhex), false for a name-intent
+ */
+function checkIntent(value) {
+  if (value.length === HASH_INTENT_LEN && LOWHEX.test(value)) return true;
+  checkToken(value, 'intent');
+  return false;
+}
+
+/**
+ * §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
+ * not written twice.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isValidAction(value) {
+  if (typeof value !== 'string' || value === '') return false;
+  if (value.startsWith('-') || value.endsWith('-')) return false;
+  return TOKEN.test(value);
+}
+
+// ---------------------------------------------------------------------------
+// ROUTE_SHARD derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * authority -> ROUTE_SHARD (16 bytes).
+ *
+ *     ROUTE_SHARD = SHA-256( ASCII(canonical_authority) )[0:16]
+ *
+ * Properties:
+ *   * **Deterministic** - one authority always yields one shard.
+ *   * **Pure computation** - no DNS, no registry, no network (§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).
+ *
+ * @param {string} canonicalAuthority
+ * @returns {Uint8Array} 16 bytes
+ */
+export function deriveRouteShard(canonicalAuthority) {
+  if (typeof canonicalAuthority !== 'string' || canonicalAuthority === '') {
+    throw new RttpUriError('canonical_authority is empty');
+  }
+  if (canonicalAuthority !== canonicalAuthority.toLowerCase()) {
+    throw new RttpUriError('canonical_authority must be lowercase (RFC-002 §10.3)');
+  }
+  const digest = createHash('sha256')
+    .update(Buffer.from(canonicalAuthority, 'ascii'))
+    .digest();
+  return new Uint8Array(digest.subarray(0, ROUTE_SHARD_BYTES));
+}
+
+/**
+ * @param {string} canonicalAuthority
+ * @returns {string} 32 lowercase hex characters
+ */
+export function deriveRouteShardHex(canonicalAuthority) {
+  return Buffer.from(deriveRouteShard(canonicalAuthority)).toString('hex');
+}
+
+// ---------------------------------------------------------------------------
+// Parse / canonicalise
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse one `rttp` URI and return its canonical fields.
+ *
+ * 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.)
+ *
+ * Field names are `snake_case` on purpose: the published conformance vectors use
+ * those names, so the output of the Python and JavaScript implementations
+ * compares directly.
+ *
+ * @param {string} uri
+ * @returns {{
+ *   scheme: string,
+ *   intent: string,
+ *   intent_is_hash: boolean,
+ *   intent_hash32: number | null,
+ *   pillar: string,
+ *   root: string,
+ *   action: string,
+ *   action_omitted: boolean,
+ *   authority: string,
+ *   canonical_uri: string,
+ *   route_shard: Uint8Array,
+ *   route_shard_hex: string
+ * }}
+ */
+export function parse(uri) {
+  if (typeof uri !== 'string') {
+    throw new RttpUriError('uri must be a string');
+  }
+  if (uri === '') {
+    throw new RttpUriError('uri is empty');
+  }
+  if (uri !== uri.trim()) {
+    // Leading/trailing whitespace may be paste contamination, or an attempt to
+    // slip past a prefix check. Either way: reject.
+    throw new RttpUriError('uri must not contain leading/trailing whitespace');
+  }
+
+  // --- scheme (§10.6 prefix whitelist) ---
+  let scheme;
+  let rest;
+  if (uri.startsWith(`${BROWSER_HANDLER_SCHEME}://`)) {
+    scheme = BROWSER_HANDLER_SCHEME;
+    rest = uri.slice(BROWSER_HANDLER_SCHEME.length + 3);
+  } else if (uri.startsWith(`${SCHEME}://`)) {
+    scheme = SCHEME;
+    rest = uri.slice(SCHEME.length + 3);
+  } else {
+    throw new RttpUriError(
+      `not an rttp URI: must begin with '${SCHEME}://' or '${BROWSER_HANDLER_SCHEME}://'`);
+  }
+
+  // --- §10.3 excluded characters ---
+  for (const ch of FORBIDDEN_CHARS) {
+    if (uri.includes(ch)) {
+      throw new RttpUriError(
+        `illegal character ${JSON.stringify(ch)}: this scheme defines no `
+        + 'userinfo / query / fragment');
+    }
+  }
+
+  // --- authority and path ---
+  const slash = rest.indexOf('/');
+  const authority = slash === -1 ? rest : rest.slice(0, slash);
+  const action = slash === -1 ? '' : rest.slice(slash + 1);
+
+  if (slash !== -1 && action.includes('/')) {
+    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
+    // 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>'");
+  }
+
+  const parts = authority.split('.');
+  if (parts.length !== 3) {
+    throw new RttpUriError(
+      "authority must be exactly '<intent>.<pillar>.<root>' "
+      + `(got ${parts.length} segment(s))`);
+  }
+  const [intent, pillar, root] = parts;
+
+  const intentIsHash = checkIntent(intent);
+  checkToken(pillar, 'pillar');
+  checkToken(root, 'root');
+  if (action) checkToken(action, 'action');
+
+  const canonicalAuthority = `${intent}.${pillar}.${root}`;
+  const canonicalUri = `${SCHEME}://${canonicalAuthority}${action ? `/${action}` : ''}`;
+  const shard = deriveRouteShard(canonicalAuthority);
+
+  return {
+    scheme,
+    intent,
+    intent_is_hash: intentIsHash,
+    intent_hash32: intentIsHash ? parseInt(intent, 16) : null,
+    pillar,
+    root,
+    action,
+    action_omitted: action === '',
+    authority: canonicalAuthority,
+    canonical_uri: canonicalUri,
+    route_shard: shard,
+    route_shard_hex: Buffer.from(shard).toString('hex'),
+  };
+}
+
+/**
+ * Convenience entry point: parse and derive in one step. Identical to `parse`;
+ * it exists so that callers reading the specification's wording have a
+ * function to name.
+ *
+ * @param {string} uri
+ * @returns {ReturnType<typeof parse>}
+ */
+export function parseAndDerive(uri) {
+  return parse(uri);
+}