@aicent/rttp 0.1.0 → 0.1.1

package/README.md

@@ -22,6 +22,19 @@ locally — offline, no account, no network. `[PASS]` or it is not.
 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
+
+```console
+$ pip install rttp
+$ python -m rttp.selftest
+[PASS] all 53 checks passed
+```
+
+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.
+
 ---
 
 ## Install
@@ -51,6 +64,18 @@ r.canonical_uri   // 'rttp://brain.epoekie.aicent/verify'
 r.route_shard_hex // '459e543b73d86005b72ba77d5756e83c'  <- pure computation
 ```
 
+The same three lines ship as a runnable file:
+
+```console
+$ node examples/quickstart.mjs
+459e543b73d86005b72ba77d5756e83c
+```
+
+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
 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`.
@@ -70,24 +95,24 @@ package fails closed everywhere.
 
 ---
 
-## The address and the prefix are different things
+## The browser's registration prefix — accepted, never advertised
 
-A user agent accepts `navigator.registerProtocolHandler()` only for schemes on its
-own safelisted set, or for a scheme beginning `web+`. So a **web page** must use
-the `web+rttp:` prefix to register a handler (RFC-002 §10.6) — but that prefix
-describes the **client**, never the target.
+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.
 
-```js
-parse('web+rttp://logic.zcmk.aicent/pulse').canonical_uri
-// 'rttp://logic.zcmk.aicent/pulse'   <- always the canonical form, either way
+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
+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.
 
-parse('web+rttp://logic.zcmk.aicent/pulse').route_shard_hex
-=== parse('rttp://logic.zcmk.aicent/pulse').route_shard_hex
-// true - same authority, same path, same shard
+```js
+parse('rttp://logic.zcmk.aicent/pulse').canonical_uri
+// 'rttp://logic.zcmk.aicent/pulse'   <- always the canonical form
 ```
 
-The output `scheme` field tells you which form arrived; everything else is
-identical.
+The `scheme` field tells you which form arrived; everything else is identical.
 
 ---
 
@@ -111,7 +136,7 @@ field for field, byte for byte.
 
 | Field | Meaning |
 |:---|:---|
-| `scheme` | `rttp` or `web+rttp` — which form arrived |
+| `scheme` | Which form arrived: `rttp` for the canonical address |
 | `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 |
@@ -162,7 +187,7 @@ what it is for.
 
 | Group | Count | What it proves |
 |:---|:---|---:|
-| `positive_uris` | 6 | Accept, canonicalise and derive — including a hash-intent, an omitted action, and the browser-handler prefix |
+| `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 |
@@ -172,7 +197,7 @@ 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.2 alone and **must never import
+`src/conformance.mjs` is written from RFC-002 §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.
@@ -215,7 +240,7 @@ agreeing with its own bugs.
 | Ecosystem | Name | Status |
 |:---|:---|:---|
 | crates.io | `rttp` | held by this project |
-| PyPI | `rttp` | the Python reference implementation |
+| 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`. |
 
 ---

package/examples/quickstart.mjs

@@ -0,0 +1,20 @@
+/**
+ * The whole quickstart, in three lines.
+ *
+ *     node examples/quickstart.mjs
+ *
+ * Expected output:
+ *
+ *     459e543b73d86005b72ba77d5756e83c
+ *
+ * That is not an arbitrary number. It is the ROUTE_SHARD the published
+ * conformance vectors pin for this exact address (`positive_uris[1]` and
+ * `frame_vectors[1]` in `src/vectors.json`), which is what makes this example
+ * checkable rather than merely illustrative - and it is the same value the
+ * Python implementation derives, from code that shares nothing with this one.
+ */
+
+import { parse } from '@aicent/rttp';
+
+const r = parse('rttp://brain.epoekie.aicent/verify');
+console.log(r.route_shard_hex);   // 459e543b73d86005b72ba77d5756e83c

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aicent/rttp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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.",
   "keywords": [
     "rttp",
@@ -37,6 +37,7 @@
   "files": [
     "src",
     "bin",
+    "examples",
     "README.md",
     "LICENSE"
   ],

package/src/conformance.mjs

@@ -64,9 +64,11 @@ export function parseUri(uri) {
   if (uri !== uri.trim()) throw new Error('leading/trailing whitespace');
 
   let rest;
+  // The browser-registration form is accepted as a **tolerance only**: the
+  // specification defines no such form, but a browser hands it to the handler.
   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://');
+  else throw new Error('scheme must be rttp:// or the browser-registration form');
 
   for (const ch of ['@', '?', '#', '[', ']']) {
     if (uri.includes(ch)) throw new Error(`illegal char ${ch}`);

package/src/rttp-uri.d.mts

@@ -7,7 +7,7 @@
 
 /** 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. */
+  /** The canonical form, or the browser-registration form when that is how the input arrived. */
   scheme: 'rttp' | 'web+rttp';
   /** 8 lowercase hex digits (32-bit routing hash) or a readable organ token. */
   intent: string;

package/src/rttp-uri.mjs

@@ -49,12 +49,15 @@ import { createHash } from 'node:crypto';
 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://`.
+ * The prefix a user agent requires on a scheme it does not already know, before
+ * it will let a page register a protocol handler. It is a property of the
+ * **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
+ * 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';
 

package/src/vectors.json

@@ -20,7 +20,9 @@
       "root": "aicent",
       "action": "vessel",
       "action_omitted": false,
-      "route_shard_hex": "bf77b78ff6ceafc363226aa586562218"
+      "route_shard_hex": "bf77b78ff6ceafc363226aa586562218",
+      "tolerance": false,
+      "note": null
     },
     {
       "uri": "rttp://brain.epoekie.aicent/verify",
@@ -32,7 +34,9 @@
       "root": "aicent",
       "action": "verify",
       "action_omitted": false,
-      "route_shard_hex": "459e543b73d86005b72ba77d5756e83c"
+      "route_shard_hex": "459e543b73d86005b72ba77d5756e83c",
+      "tolerance": false,
+      "note": null
     },
     {
       "uri": "rttp://f3b2a1c4.rttp.aicent",
@@ -44,7 +48,9 @@
       "root": "aicent",
       "action": "",
       "action_omitted": true,
-      "route_shard_hex": "bf77b78ff6ceafc363226aa586562218"
+      "route_shard_hex": "bf77b78ff6ceafc363226aa586562218",
+      "tolerance": false,
+      "note": null
     },
     {
       "uri": "rttp://00000000.rpki.aicent/attest",
@@ -56,7 +62,9 @@
       "root": "aicent",
       "action": "attest",
       "action_omitted": false,
-      "route_shard_hex": "753c105fd0f8bf341811acfaaac85b37"
+      "route_shard_hex": "753c105fd0f8bf341811acfaaac85b37",
+      "tolerance": false,
+      "note": null
     },
     {
       "uri": "web+rttp://logic.zcmk.aicent/pulse",
@@ -68,7 +76,9 @@
       "root": "aicent",
       "action": "pulse",
       "action_omitted": false,
-      "route_shard_hex": "cdc32d19641c84aca3292de6276de056"
+      "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)"
     },
     {
       "uri": "rttp://a-b-c.d-e.f-g/audit-v2",
@@ -80,7 +90,9 @@
       "root": "f-g",
       "action": "audit-v2",
       "action_omitted": false,
-      "route_shard_hex": "905bf68b86aadf883cda2db9640912de"
+      "route_shard_hex": "905bf68b86aadf883cda2db9640912de",
+      "tolerance": false,
+      "note": null
     }
   ],
   "negative_uris": [
@@ -94,11 +106,11 @@
     },
     {
       "uri": "RTTP://f3b2a1c4.rttp.aicent/vessel",
-      "reason": "uppercase scheme prefix - canonical form is lowercase (RFC-002 §10.2)"
+      "reason": "uppercase scheme prefix - canonical form is lowercase (RFC-002 §10.3)"
     },
     {
       "uri": "WEB+RTTP://f3b2a1c4.rttp.aicent/vessel",
-      "reason": "uppercase scheme prefix on the handler form (RFC-002 §10.2)"
+      "reason": "uppercase scheme prefix on the handler form (RFC-002 §10.3)"
     },
     {
       "uri": "rttp://subject@rttp.aicent/vessel",