@aicent/iqa 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2013-2019 Nikolay Kim and Andrew Svetlov
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,246 @@
+# @aicent/iqa
+
+**IQA for JavaScript: `iqa://` subject-attestation addressing, `IQA_ROUTE`
+derivation, action safety classes — and the published conformance vectors that
+prove an implementation is right.**
+
+[RFC-009 §10](https://iqa.org/RFC-009/) · §11 · v1.2.6 · zero dependencies · no build step
+
+---
+
+## Verify it in one command — no trust required
+
+```console
+$ npx @aicent/iqa
+[PASS] all 32 checks passed
+```
+
+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.
+
+The vectors cover the `iqa://` grammar (RFC-009 §10.2), the **closed sets**
+(`organ` and `action` — the deliberate difference from `rttp`, whose verb set
+is open), the §11.3 action safety classes, the `IQA_ROUTE` derivation, **and**
+the deterministic Ed25519 attestation envelope — replayed by both
+implementations.
+
+### The other half — Python, on PyPI
+
+```console
+$ pip install iqa
+$ python -m iqa.selftest
+```
+
+Published as **`@aicent/iqa`** — the bare `iqa` name is unregistered on npm but
+blocked by its typosquatting protection, so the JavaScript side lives under
+this project's organization, as `@aicent/rttp` already does. The Python
+package keeps the bare name: **`iqa`** on PyPI. It ships a **byte-identical
+copy** of this same vector set (three mirrors, one sha256) and replays it
+offline, exactly as this one does: two registries, two languages, one
+specification.
+
+---
+
+## Install
+
+```console
+npm install @aicent/iqa
+```
+
+Node 18+. No dependencies, no build step, no transitive tree to audit: the
+published `src/` is exactly what runs.
+
+---
+
+## Quickstart
+
+```js
+import { parse } from '@aicent/iqa';
+
+const r = parse('iqa://3f9a1b2c.gateway.iqa');
+
+r.subject        // '3f9a1b2c'   — 8-hex routing short form of the AID
+r.organ          // 'gateway'    — closed set: forge | tss | gateway
+r.action         // null         — omitted = standing read (§11.1)
+r.action_safe    // true         — §11.3: omitted and verify are SAFE
+r.canonical_uri  // 'iqa://3f9a1b2c.gateway.iqa'
+r.route_hex      // '5c378581'   <- pure computation, pinned by the vectors
+```
+
+The same lines ship as a runnable file:
+
+```console
+$ node examples/quickstart.mjs
+5c378581
+```
+
+Its expected output is the route fingerprint the published conformance vectors
+pin for that address, so the example can be **checked** rather than believed.
+
+Addressing is **DNS-free** (RFC-009 §12 #9): the route fingerprint is derived
+from the authority by SHA-256, so no registry, resolver or network is
+involved. A URI either yields its fields or throws — there is no fallback, no
+`iqas`, and no rewriting to `https`.
+
+---
+
+## The two closed sets — the deliberate difference from `rttp`
+
+`rttp` accepts any well-formed action verb. **`iqa` does not.** RFC-009 §10.1
+marks *both* segments "Closed set", and this package enforces exactly that:
+
+```js
+parse('iqa://3f9a1b2c.gateway.iqa/pulse')  // throws — 'pulse' is an rttp verb
+parse('iqa://3f9a1b2c.forgery.iqa')        // throws — organ is forge|tss|gateway
+```
+
+### The one rule that surprises people
+
+**Malformed input is rejected, not normalised.** `iqa://…/AUDIT`,
+`iqa://3F9A1B2C.…` and `IQA://…` all throw: the canonical form is lowercase
+US-ASCII (RFC-009 §10.3), a case variant is not a spelling difference, and
+nothing is ever accepted because a check could not be performed.
+
+### One honest quirk of the grammar
+
+The ABNF is an ordered choice (`hash-subject / name-subject`), so a lowercase
+hex string of a **non-hash length** (9 digits, say) is a *name subject*, not
+an error. The grammar is the grammar; vector #8 pins the behaviour so every
+implementation agrees on it.
+
+---
+
+## Action safety classes (RFC-009 §11.3)
+
+| `action` | Class | `action_safe` |
+|:---|:---|:---|
+| *(omitted)* | SAFE — standing read | `true` |
+| `verify` | SAFE — read-only comparison | `true` |
+| `audit` | NOT SAFE — can trigger Authority Ischemia | `false` |
+| `attest` | NOT SAFE — state transition | `false` |
+| `revoke` | NOT SAFE — state transition | `false` |
+
+Per §11.2, dereferencing an `iqa` URI MUST NOT transition any subject's
+standing. Tooling built on this package MUST gate the three NOT-SAFE verbs
+behind an explicit user action — parsing one is not requesting one.
+
+---
+
+## API — main entry
+
+| Export | What it does |
+|:---|:---|
+| `parse(uri)` | Validate, canonicalise, classify, derive. Throws `IqaUriError`. |
+| `deriveRoute(authority)` | `Uint8Array(4)` = `SHA-256(ASCII(authority))[0:4]`. |
+| `deriveRouteHex(authority)` | The same, as 8 lowercase hex characters. |
+| `isValidAction(value)` | §10.1 closed-set test. |
+| `IqaUriError` | The only error type thrown. |
+| `SCHEME`, `ORGANS`, `ACTIONS`, `STANDINGS`, `HASH_LENGTHS` | Constants. |
+
+### The attestation envelope — `@aicent/iqa/conformance`
+
+The deterministic Ed25519 envelope (SPEC/IQA-URI-ATTEST-v1.2.6 §5: domain
+prefix `iqa-attest-v1`, `AID = SHA-256(pub)`, `ts`/`nonce` inside the
+signature, 120-second freshness) is part of the shared vector set and is
+replayed by this package's conformance run. `buildSigningInput` is exported
+from `./conformance` for implementers of other languages.
+
+---
+
+## The conformance vectors
+
+```js
+import { loadVectors, runConformance } from '@aicent/iqa/conformance';
+
+const { checked, failures, passed } = runConformance(loadVectors());
+```
+
+Or from the command line:
+
+```console
+npx @aicent/iqa                       # replay the shipped vectors
+npx @aicent/iqa --vectors ./new.json  # replay a different vector set
+npx @aicent/iqa --json                # machine-readable output
+```
+
+In CI:
+
+```yaml
+- run: npx @aicent/iqa
+```
+
+| Group | Count | What it proves |
+|:---|---:|:---|
+| `positive_uris` | 8 | Accept, classify and derive — §10.3's own examples, the 256-bit form, the all-zero boundary, the name-subject fall-through |
+| `negative_uris` | 18 | Reject — uppercase anywhere, `iqas://`, userinfo, port, query, fragment, wrong authority shape, closed-set violations on both segments |
+| `action_safety` | 5 | §11.3 classes as data |
+| `attest_envelope_vector` | 1 | Deterministic Ed25519 envelope, verified through `node:crypto` |
+
+`vectors.json` is plain JSON and ships inside the package, also reachable as
+the subpath export `@aicent/iqa/vectors.json`. Any language can read it; that
+is what it is for.
+
+### Why the checker lives in this package, and why that is still honest
+
+`src/conformance.mjs` is written from RFC-009 §10 alone and **must never
+import `src/iqa-uri.mjs`**. A conformance suite that reuses the code under
+test only proves the code equals itself. The two files share no code — one is
+a streaming charset scanner, the other a single full-match grammar check — so
+the rule is checkable by reading them.
+
+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 JSON. Hand-editing a conformance vector is how a specification quietly
+starts agreeing with its own bugs.
+
+---
+
+## Scope — what this package is not
+
+| | |
+|:---|:---|
+| ✅ **Validation / canonicalisation** | Real, and specified (RFC-009 §10.2 / §10.3). |
+| ✅ **Closed-set enforcement** | Real, and specified (§10.1). |
+| ✅ **IQA_ROUTE derivation** | Real (SPEC §3, decision D1). |
+| ✅ **Action safety classes** | Real, and specified (§11.3). |
+| ✅ **Conformance vectors + independent replay** | Published and generated. |
+| ❌ **Dereferencing / resolver service** | Not here. The codec computes; *answering* a standing read is an Organ's job (RFC-009-C §3). |
+| ❌ **Staking, tiers, vitality** | Operator economics and telemetry — RFC-009 narrative, no cryptographic object in this package. |
+| ❌ **Post-quantum Lattice Guard** | RFC-009 §12 #11 schedules it for v1.4.0; no implementation exists. |
+| ❌ **Revocation transport** | §11.3 defines the verb; executing it is not the codec's job. |
+| ❌ **Confidentiality** | Signing is not encryption. |
+
+---
+
+## Naming
+
+| Ecosystem | Name | Status |
+|:---|:---|:---|
+| crates.io | `iqa-org` | held by this project (Shipyard Rust crate) |
+| PyPI | `iqa` | **published** — the Python reference implementation; `pip install iqa` |
+| npm | **`@aicent/iqa`** | the bare `iqa` name is unregistered but **blocked by npm's typosquatting protection** (too similar to existing short names) — so this package is published under the organization this project controls, as `@aicent/rttp` already is. The package name itself is still just `iqa`. |
+
+---
+
+## Specification status
+
+* **`iqa` URI scheme** — submitted to IANA under RFC 7595, ticket **#1459963**,
+  Provisional, **under review**. It is **not yet registered** — as of
+  2026-09-18 the IANA "URI Schemes" registry contains no `iqa` entry. Please
+  describe it that way.
+* **URI grammar** — RFC-009 §10.2 (frozen; this package adds no syntax).
+* **Dereference safety** — RFC-009 §11 (closed sets and safety classes).
+* **Attestation envelope** — `SPEC/IQA-URI-ATTEST-v1.2.6.md` §5, a **draft**:
+  the format is implemented and vector-tested, but it is not yet a numbered
+  RFC-009 section.
+
+Where this package and the specification disagree, **the specification wins
+and this package is wrong.** Please report it.
+
+---
+
+## License
+
+Apache-2.0. See `LICENSE`.

package/bin/iqa.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// iqa — replay the published conformance vectors. [PASS] or it is not.
+//
+//   npx @aicent/iqa                       # replay the shipped vectors
+//   npx @aicent/iqa --vectors ./new.json  # replay a different vector set
+//   npx @aicent/iqa --json                # machine-readable output
+
+import { runConformance, loadVectors, DEFAULT_VECTORS_PATH } from '../src/conformance.mjs';
+
+const args = process.argv.slice(2);
+
+let vectorsPath = DEFAULT_VECTORS_PATH;
+let json = false;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--vectors') {
+    vectorsPath = args[++i];
+    if (!vectorsPath) {
+      console.error('error: --vectors requires a path');
+      process.exit(2);
+    }
+  } else if (args[i] === '--json') {
+    json = true;
+  } else if (args[i] === '--help' || args[i] === '-h') {
+    console.log('@aicent/iqa — replay the published conformance vectors (RFC-009 §10/§11)');
+    console.log('  npx @aicent/iqa                       replay the shipped vectors');
+    console.log('  npx @aicent/iqa --vectors ./new.json  replay a different vector set');
+    console.log('  npx @aicent/iqa --json                machine-readable output');
+    process.exit(0);
+  } else {
+    console.error(`error: unknown argument ${args[i]}`);
+    process.exit(2);
+  }
+}
+
+let vectors;
+try {
+  vectors = loadVectors(vectorsPath);
+} catch (err) {
+  console.error(`error: cannot load vectors (${err.message})`);
+  process.exit(2);
+}
+
+const result = runConformance(vectors);
+
+if (json) {
+  console.log(JSON.stringify({
+    checked: result.checked,
+    passed: result.passed,
+    failures: result.failures,
+    vectors: vectorsPath,
+  }, null, 2));
+} else {
+  console.log(`iqa conformance replay — spec ${vectors.spec ?? '(unlabeled)'}`);
+  for (const f of result.failures) console.log(`[FAIL] ${f}`);
+  console.log(`[PASS] all ${result.checked} checks passed`);
+}
+
+process.exit(result.failures.length === 0 ? 0 : 1);

package/examples/quickstart.mjs

@@ -0,0 +1,15 @@
+// The same three lines as the README quickstart — runnable, so the example can
+// be CHECKED rather than believed. Its expected output is the route fingerprint
+// the published conformance vectors pin for that address.
+//
+//   node examples/quickstart.mjs
+//   5c378581
+
+import { parse } from '../src/iqa-uri.mjs';
+
+const r = parse('iqa://3f9a1b2c.gateway.iqa');
+
+console.log(r.subject);        // '3f9a1b2c'      (8-hex routing short form)
+console.log(r.organ);          // 'gateway'       (closed set: forge|tss|gateway)
+console.log(r.action);         // null            (omitted = standing read, SAFE)
+console.log(r.route_hex);      // '5c378581'      <- pinned by the published vectors

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@aicent/iqa",
+  "version": "0.1.0",
+  "description": "IQA for JavaScript: iqa:// subject-attestation addressing, IQA_ROUTE derivation, action safety classes — and the published conformance vectors that prove an implementation is right.",
+  "author": "IQA.ORG Organization",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./src/iqa-uri.mjs",
+  "types": "./src/iqa-uri.d.mts",
+  "exports": {
+    ".": {
+      "types": "./src/iqa-uri.d.mts",
+      "default": "./src/iqa-uri.mjs"
+    },
+    "./conformance": {
+      "types": "./src/conformance.d.mts",
+      "default": "./src/conformance.mjs"
+    },
+    "./vectors.json": "./src/vectors.json"
+  },
+  "bin": {
+    "iqa": "bin/iqa.mjs"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "examples/",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "iqa",
+    "attestation",
+    "identity",
+    "uri",
+    "conformance",
+    "ed25519",
+    "aicent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Aicent-Stack/aicent-stack.git"
+  },
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "node --test"
+  }
+}

package/src/conformance.d.mts

@@ -0,0 +1,29 @@
+/** Independent conformance replay for the published IQA vector set. */
+
+export interface ConformanceResult {
+  checked: number;
+  failures: string[];
+  passed: number;
+}
+
+export interface ParsedForConformance {
+  authority: string;
+  action: string | null;
+  shardHex: string;
+}
+
+/**
+ * The independent RFC-009 §10 implementation used by the checker.
+ * `buildFrame`-style helpers do not exist here: IQA v1.2.6 has no frame —
+ * the derivation chain is URI → IQA_ROUTE (4 bytes).
+ */
+export declare function parseUri(uri: string): ParsedForConformance;
+
+/** Replay a vector set. Accepts any object with the documented groups. */
+export declare function runConformance(vectors: object): ConformanceResult;
+
+/** Parse a vector set; defaults to the shipped one. */
+export declare function loadVectors(path?: string): Record<string, unknown>;
+
+/** Absolute path of the shipped vectors.json. */
+export declare const DEFAULT_VECTORS_PATH: string;

package/src/conformance.mjs

@@ -0,0 +1,181 @@
+// IQA conformance replay — an INDEPENDENT implementation of RFC-009 §10.
+//
+// This file is written from RFC-009 §10/§11 alone and MUST NEVER import
+// ./iqa-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.
+//
+// They ship together for the same reason the Python wheel ships its self-test:
+// so a stranger can verify an installed package offline, with no repository
+// checkout. Zero dependencies — node:crypto and node:fs only.
+
+import { createHash, createPublicKey, verify as cryptoVerify } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const DOMAIN = Buffer.from('iqa-attest-v1\n', 'utf8');
+
+// ---------------------------------------------------------------------------
+// Independent parse — single full-match grammar check, deliberately different
+// in structure from the streaming charset scanner in iqa-uri.mjs.
+// ---------------------------------------------------------------------------
+
+// authority = subject "." organ "." root ; subject/organ/root over [a-z0-9-]
+// (the "." split is done by the regex groups, so empty segments fail);
+// path = "/" action at most once; every matched char is lowercase US-ASCII,
+// so uppercase, '@', ':', '?', '#', whitespace and all foreign bytes fail.
+const GRAMMAR = /^iqa:\/\/([a-z0-9-]+)\.([a-z0-9-]+)\.([a-z0-9-]+)(?:\/([a-z0-9-]+))?$/;
+
+const ORGANS = ['forge', 'tss', 'gateway'];         // §10.1 closed set
+const ACTIONS = ['verify', 'audit', 'attest', 'revoke']; // §10.1 closed set
+const HASH_LENGTHS = [8, 32, 64];                   // §10.2 hash-subject
+
+export function parseUri(uri) {
+  const m = GRAMMAR.exec(uri);
+  if (!m) {
+    throw new Error(`REJECT (grammar/full-match): ${JSON.stringify(uri)}`);
+  }
+  const [, subject, organ, root, action = null] = m;
+
+  if (!ORGANS.includes(organ)) {
+    throw new Error(`REJECT (organ closed set): ${JSON.stringify(uri)}`);
+  }
+  if (action !== null && !ACTIONS.includes(action)) {
+    throw new Error(`REJECT (action closed set): ${JSON.stringify(uri)}`);
+  }
+
+  const isAllLowerHex = /^[0-9a-f]+$/.test(subject);
+  const subjectIsHash = isAllLowerHex && HASH_LENGTHS.includes(subject.length);
+
+  return {
+    scheme: 'iqa',
+    subject,
+    subject_is_hash: subjectIsHash,
+    subject_hex: subjectIsHash ? subject : null,
+    organ,
+    root,
+    authority: `${subject}.${organ}.${root}`,
+    action,
+    action_omitted: action === null,
+    action_safe: action === null || action === 'verify', // §11.3
+    canonical_uri: 'iqa://' + `${subject}.${organ}.${root}` + (action ? '/' + action : ''),
+    route_hex: createHash('sha256').update(`${subject}.${organ}.${root}`, 'ascii')
+      .digest().subarray(0, 4).toString('hex'),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Envelope — canonical JSON + Ed25519 over the domain-separated input.
+// ---------------------------------------------------------------------------
+
+function canonicalize(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return '[' + value.map(canonicalize).join(',') + ']';
+  const keys = Object.keys(value).sort();
+  return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonicalize(value[k])).join(',') + '}';
+}
+
+export function buildSigningInput(env) {
+  const body = canonicalize({
+    alg: 'ed25519',
+    aid: env.aid,
+    nonce: env.nonce,
+    payload: env.payload,
+    pub: env.pub,
+    ts: env.ts,
+  });
+  return Buffer.concat([DOMAIN, Buffer.from(body, 'utf8')]);
+}
+
+function verifyEnvelope(env) {
+  const input = buildSigningInput(env);
+  if (input.toString('hex') !== env.signing_input_hex) {
+    throw new Error('envelope :: signing input mismatch');
+  }
+  const aid = createHash('sha256').update(Buffer.from(env.pub, 'hex')).digest('hex');
+  if (aid !== env.aid) {
+    throw new Error('envelope :: aid != SHA-256(pub)');
+  }
+  // Wrap the raw 32-byte key in the fixed Ed25519 SPKI DER prefix.
+  const spki = Buffer.concat([
+    Buffer.from('302a300506032b6570032100', 'hex'),
+    Buffer.from(env.pub, 'hex'),
+  ]);
+  const key = createPublicKey({ key: spki, format: 'der', type: 'spki' });
+  const ok = cryptoVerify(null, input, key, Buffer.from(env.sig, 'hex'));
+  if (!ok) throw new Error('envelope :: Ed25519 verification failed');
+}
+
+// ---------------------------------------------------------------------------
+// Runner
+// ---------------------------------------------------------------------------
+
+const DEFAULT_VECTORS_PATH = join(dirname(fileURLToPath(import.meta.url)), 'vectors.json');
+
+export { DEFAULT_VECTORS_PATH };
+
+export function loadVectors(path = DEFAULT_VECTORS_PATH) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+/**
+ * Replay a vector set → { checked, failures, passed }.
+ * The checker accepts any object with the documented groups, so a different
+ * vector set (e.g. a candidate next revision) can be replayed the same way.
+ */
+export function runConformance(vectors) {
+  const failures = [];
+  let checked = 0;
+
+  for (const c of vectors.positive_uris ?? []) {
+    checked += 1;
+    try {
+      const got = parseUri(c.uri);
+      for (const key of ['canonical_uri', 'subject_is_hash', 'organ', 'root',
+        'authority', 'action', 'action_omitted', 'action_safe', 'route_hex']) {
+        if (got[key] !== c[key]) {
+          failures.push(`${c.uri} :: ${key} ${JSON.stringify(c[key])} != ${JSON.stringify(got[key])}`);
+        }
+      }
+    } catch (err) {
+      failures.push(`${c.uri} :: expected ACCEPT but rejected (${err.message})`);
+    }
+  }
+
+  for (const c of vectors.negative_uris ?? []) {
+    checked += 1;
+    try {
+      parseUri(c.uri);
+      failures.push(`${c.uri} :: expected REJECT but parsed`);
+    } catch {
+      // required behaviour
+    }
+  }
+
+  for (const row of vectors.action_safety ?? []) {
+    checked += 1;
+    const uri = row.action === null
+      ? 'iqa://3f9a1b2c.gateway.iqa'
+      : `iqa://3f9a1b2c.gateway.iqa/${row.action}`;
+    try {
+      const got = parseUri(uri).action_safe;
+      if (got !== row.safe) {
+        failures.push(`action_safety ${row.action} :: expected ${row.safe} got ${got}`);
+      }
+    } catch (err) {
+      failures.push(`action_safety ${row.action} :: expected ACCEPT but rejected (${err.message})`);
+    }
+  }
+
+  if (vectors.attest_envelope_vector) {
+    checked += 1;
+    try {
+      verifyEnvelope(vectors.attest_envelope_vector);
+    } catch (err) {
+      failures.push(err.message);
+    }
+  }
+
+  return { checked, failures, passed: checked - failures.length };
+}

package/src/iqa-uri.d.mts

@@ -0,0 +1,42 @@
+/**
+ * iqa — RFC-009 §10/§11 codec for JavaScript.
+ * Zero dependencies. Field names are snake_case on purpose: they match the
+ * published conformance vectors (and the Python implementation) field for field.
+ */
+
+export declare const SCHEME: 'iqa';
+export declare const ORGANS: readonly ['forge', 'tss', 'gateway'];
+export declare const ACTIONS: readonly ['verify', 'audit', 'attest', 'revoke'];
+export declare const STANDINGS: readonly ['ghost', 'probation', 'radiant', 'genesis'];
+export declare const HASH_LENGTHS: readonly [8, 32, 64];
+
+export declare class IqaUriError extends Error {}
+
+/** True only for the closed four-verb set (RFC-009 §10.1). */
+export declare function isValidAction(value: string): boolean;
+
+/**
+ * IQA_ROUTE = SHA-256(ASCII(canonical_authority))[0:4]  (SPEC §3).
+ * The address fingerprint — not the subject hash (which hints the AID).
+ */
+export declare function deriveRoute(authority: string): Uint8Array;
+export declare function deriveRouteHex(authority: string): string;
+
+export interface ParsedUri {
+  scheme: 'iqa';
+  subject: string;
+  subject_is_hash: boolean;
+  subject_hex: string | null;
+  organ: string;
+  root: string;
+  authority: string;
+  action: string | null;
+  action_omitted: boolean;
+  /** RFC-009 §11.3 — true for omitted and `verify`, false for audit/attest/revoke. */
+  action_safe: boolean;
+  canonical_uri: string;
+  route_hex: string;
+}
+
+/** Validate, canonicalise and derive. Throws IqaUriError on any violation. */
+export declare function parse(uri: string): ParsedUri;

package/src/iqa-uri.mjs

@@ -0,0 +1,169 @@
+// iqa:// URI codec — validate, canonicalise, derive (RFC-009 §10/§11).
+//
+// Authority boundaries:
+//   Grammar ......... RFC-009 §10.2 ABNF (sole authority)
+//   Closed sets ..... §10.1 (organ and action are CLOSED sets)
+//   Case discipline . §10.3 (lowercase US-ASCII only) + §12 #8 (fail closed)
+//   Deref safety .... §11.3 (action safety classes)
+//   Route derivation  SPEC/IQA-URI-ATTEST-v1.2.6.md §3 (IQA_ROUTE)
+//
+// Zero dependencies. Node 18+. No build step — the published src/ is what runs.
+
+import { createHash } from 'node:crypto';
+
+export const SCHEME = 'iqa';
+
+/** RFC-009 §10.1 — organ is a CLOSED set (RFC-009-A/-B/-C). */
+export const ORGANS = Object.freeze(['forge', 'tss', 'gateway']);
+
+/**
+ * RFC-009 §10.1 — action is a CLOSED set. This is the deliberate difference
+ * from `rttp`, whose verb set is open: here anything outside the four verbs
+ * is rejected.
+ */
+export const ACTIONS = Object.freeze(['verify', 'audit', 'attest', 'revoke']);
+
+/** RFC-009-C §3 — standings an Organ may render (closed set, lowercase). */
+export const STANDINGS = Object.freeze(['ghost', 'probation', 'radiant', 'genesis']);
+
+/** RFC-009 §10.2 — hash-subject lengths: routing short form / 128-bit / 256-bit. */
+export const HASH_LENGTHS = Object.freeze([8, 32, 64]);
+
+const SAFE = new Set([null, 'verify']); // §11.3: omitted = standing read; verify = read-only
+const LOWHEX = new Set('0123456789abcdef');
+const NAME_CHARS = new Set('abcdefghijklmnopqrstuvwxyz0123456789-');
+const ALLOWED = new Set([...LOWHEX, ...NAME_CHARS, '.', '/']);
+const FORBIDDEN = new Set(['@', ':', '?', '#', '[', ']']);
+
+export class IqaUriError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'IqaUriError';
+  }
+}
+
+const fail = (uri, reason) => new IqaUriError(`${JSON.stringify(uri)}: ${reason}`);
+
+/** §10.2 action test — true only for the closed four-verb set. */
+export function isValidAction(value) {
+  return ACTIONS.includes(value);
+}
+
+/**
+ * IQA_ROUTE = SHA-256(ASCII(canonical_authority))[0:4]  (SPEC §3, decision D1).
+ *
+ * Pure computation, DNS-free (RFC-009 §12 #9). Mirrors the RTTP ROUTE_SHARD
+ * rule so both schemes of the same addressing family derive the same way.
+ * NOTE: this is the *address* fingerprint — NOT the subject hash, which is a
+ * routing hint for the *AID*. Different numbers about different things.
+ */
+export function deriveRoute(authority) {
+  if (!authority) throw new IqaUriError('deriveRoute: authority is empty');
+  return createHash('sha256').update(authority, 'ascii').digest().subarray(0, 4);
+}
+
+/** The same four bytes, as 8 lowercase hex characters. */
+export function deriveRouteHex(authority) {
+  return deriveRoute(authority).toString('hex');
+}
+
+/**
+ * Validate, canonicalise and derive. Throws IqaUriError on any violation.
+ *
+ * Returned fields are snake_case ON PURPOSE so this output and the Python
+ * package's output compare directly against the published vectors — field
+ * for field, byte for byte.
+ */
+export function parse(uri) {
+  if (typeof uri !== 'string') throw fail(uri, 'input must be a string');
+
+  const prefix = SCHEME + '://';
+  if (!uri.startsWith(prefix)) {
+    throw fail(uri, `scheme must be exactly ${JSON.stringify(prefix)} - no other `
+      + 'scheme, no case variant, no fallback (RFC-009 §10.3, §12 #8)');
+  }
+  const rest = uri.slice(prefix.length);
+
+  // Charset gate: lowercase US-ASCII only (§10.3). One scan rejects uppercase
+  // anywhere, userinfo '@', port ':', query '?', fragment '#', whitespace and
+  // every other foreign byte.
+  for (const ch of rest) {
+    if (!ALLOWED.has(ch)) {
+      if (FORBIDDEN.has(ch)) {
+        throw fail(uri, `${JSON.stringify(ch)} is not defined by the scheme (RFC-009 §10.3)`);
+      }
+      if (/\s/.test(ch)) {
+        throw fail(uri, 'whitespace is not allowed (RFC-009 §10.3 lowercase US-ASCII only)');
+      }
+      throw fail(uri, `character ${JSON.stringify(ch)} is outside the allowed set `
+        + "(lowercase US-ASCII, digits, '-', '.', '/')");
+    }
+  }
+
+  // Path: at most one '/', and the action behind it must be non-empty.
+  let authority = rest;
+  let action = null;
+  const slash = rest.indexOf('/');
+  if (slash !== -1) {
+    authority = rest.slice(0, slash);
+    action = rest.slice(slash + 1);
+    if (action === '') {
+      throw fail(uri, "trailing '/' with empty action - action is a closed-set "
+        + 'verb, not omissible by empty string (§10.2)');
+    }
+    if (action.includes('/')) {
+      throw fail(uri, "second path segment - path is a single '/<action>' (§10.2)");
+    }
+  }
+
+  // Authority: exactly three segments.
+  const segments = authority.split('.');
+  if (segments.length !== 3) {
+    throw fail(uri, `authority has ${segments.length} segment(s), must be `
+      + '<subject>.<organ>.<root> (RFC-009 §10.2)');
+  }
+  const [subject, organ, root] = segments;
+  if (subject === '' || root === '') {
+    throw fail(uri, 'authority segments must be non-empty (RFC-009 §10.2)');
+  }
+
+  // Subject: hash form (8/32/64 lowercase hex) or name form. Ordered choice
+  // per the ABNF: all-lowerhex input is tried as hash-subject first; a
+  // lowercase-hex string of another length is therefore a NAME subject,
+  // exactly as the grammar says. Documented, not "fixed".
+  let subjectIsHash = false;
+  let subjectHex = null;
+  if ([...subject].every((c) => LOWHEX.has(c)) && HASH_LENGTHS.includes(subject.length)) {
+    subjectIsHash = true;
+    subjectHex = subject;
+  }
+
+  // Organ — CLOSED set, case-sensitive (§10.1). 'Forge', 'forgery', '' all fail.
+  if (!ORGANS.includes(organ)) {
+    throw fail(uri, `organ ${JSON.stringify(organ)} is outside the closed set `
+      + `[${ORGANS.join(', ')}] (RFC-009 §10.1/§10.3)`);
+  }
+
+  // Action — CLOSED set (§10.1). The deliberate difference from rttp.
+  if (action !== null && !ACTIONS.includes(action)) {
+    throw fail(uri, `action ${JSON.stringify(action)} is outside the closed set `
+      + `[${ACTIONS.join(', ')}] (RFC-009 §10.1)`);
+  }
+
+  const canonicalUri = SCHEME + '://' + authority + (action ? '/' + action : '');
+
+  return {
+    scheme: SCHEME,
+    subject,
+    subject_is_hash: subjectIsHash,
+    subject_hex: subjectHex,
+    organ,
+    root,
+    authority,
+    action,
+    action_omitted: action === null,
+    action_safe: SAFE.has(action),           // §11.3
+    canonical_uri: canonicalUri,
+    route_hex: deriveRouteHex(authority),    // SPEC §3
+  };
+}

package/src/vectors.json

@@ -0,0 +1,260 @@
+{
+  "spec": "IQA-URI-ATTEST-v1.2.6",
+  "applies_to": [
+    "RFC-009 §10",
+    "RFC-009 §11"
+  ],
+  "generated_by": "SPEC/tools/iqa_conformance.py",
+  "note": "Generated file - do not edit by hand. Change the cases in iqa_conformance.py instead.",
+  "route_rule": "IQA_ROUTE = SHA-256(ASCII(canonical_authority))[0:4]",
+  "organ_closed_set": [
+    "forge",
+    "tss",
+    "gateway"
+  ],
+  "action_closed_set": [
+    "verify",
+    "audit",
+    "attest",
+    "revoke"
+  ],
+  "standings_closed_set": [
+    "ghost",
+    "probation",
+    "radiant",
+    "genesis"
+  ],
+  "positive_uris": [
+    {
+      "uri": "iqa://3f9a1b2c.gateway.iqa",
+      "canonical_uri": "iqa://3f9a1b2c.gateway.iqa",
+      "subject": "3f9a1b2c",
+      "subject_is_hash": true,
+      "organ": "gateway",
+      "root": "iqa",
+      "authority": "3f9a1b2c.gateway.iqa",
+      "action": null,
+      "action_omitted": true,
+      "action_safe": true,
+      "route_hex": "5c378581",
+      "note": null
+    },
+    {
+      "uri": "iqa://0000004149434e531c5b21d80403358b.forge.iqa",
+      "canonical_uri": "iqa://0000004149434e531c5b21d80403358b.forge.iqa",
+      "subject": "0000004149434e531c5b21d80403358b",
+      "subject_is_hash": true,
+      "organ": "forge",
+      "root": "iqa",
+      "authority": "0000004149434e531c5b21d80403358b.forge.iqa",
+      "action": null,
+      "action_omitted": true,
+      "action_safe": true,
+      "route_hex": "133a7fcd",
+      "note": null
+    },
+    {
+      "uri": "iqa://3f9a1b2c.tss.iqa/audit",
+      "canonical_uri": "iqa://3f9a1b2c.tss.iqa/audit",
+      "subject": "3f9a1b2c",
+      "subject_is_hash": true,
+      "organ": "tss",
+      "root": "iqa",
+      "authority": "3f9a1b2c.tss.iqa",
+      "action": "audit",
+      "action_omitted": false,
+      "action_safe": false,
+      "route_hex": "1d60651a",
+      "note": null
+    },
+    {
+      "uri": "iqa://master-authority.gateway.iqa/verify",
+      "canonical_uri": "iqa://master-authority.gateway.iqa/verify",
+      "subject": "master-authority",
+      "subject_is_hash": false,
+      "organ": "gateway",
+      "root": "iqa",
+      "authority": "master-authority.gateway.iqa",
+      "action": "verify",
+      "action_omitted": false,
+      "action_safe": true,
+      "route_hex": "510ef099",
+      "note": null
+    },
+    {
+      "uri": "iqa://0000004149434e531c5b21d80403358ba794ef228ca5253994959ef6f3ff5678.tss.iqa/attest",
+      "canonical_uri": "iqa://0000004149434e531c5b21d80403358ba794ef228ca5253994959ef6f3ff5678.tss.iqa/attest",
+      "subject": "0000004149434e531c5b21d80403358ba794ef228ca5253994959ef6f3ff5678",
+      "subject_is_hash": true,
+      "organ": "tss",
+      "root": "iqa",
+      "authority": "0000004149434e531c5b21d80403358ba794ef228ca5253994959ef6f3ff5678.tss.iqa",
+      "action": "attest",
+      "action_omitted": false,
+      "action_safe": false,
+      "route_hex": "afd25fe8",
+      "note": null
+    },
+    {
+      "uri": "iqa://0000000000000000.gateway.iqa",
+      "canonical_uri": "iqa://0000000000000000.gateway.iqa",
+      "subject": "0000000000000000",
+      "subject_is_hash": false,
+      "organ": "gateway",
+      "root": "iqa",
+      "authority": "0000000000000000.gateway.iqa",
+      "action": null,
+      "action_omitted": true,
+      "action_safe": true,
+      "route_hex": "6ddc5b56",
+      "note": null
+    },
+    {
+      "uri": "iqa://a-b-c.forge.iqa/revoke",
+      "canonical_uri": "iqa://a-b-c.forge.iqa/revoke",
+      "subject": "a-b-c",
+      "subject_is_hash": false,
+      "organ": "forge",
+      "root": "iqa",
+      "authority": "a-b-c.forge.iqa",
+      "action": "revoke",
+      "action_omitted": false,
+      "action_safe": false,
+      "route_hex": "e14bcb62",
+      "note": null
+    },
+    {
+      "uri": "iqa://3f9a1b2cd.gateway.iqa/verify",
+      "canonical_uri": "iqa://3f9a1b2cd.gateway.iqa/verify",
+      "subject": "3f9a1b2cd",
+      "subject_is_hash": false,
+      "organ": "gateway",
+      "root": "iqa",
+      "authority": "3f9a1b2cd.gateway.iqa",
+      "action": "verify",
+      "action_omitted": false,
+      "action_safe": true,
+      "route_hex": "acee0323",
+      "note": "note - 9 hex digits is not a hash length (8/32/64), so the subject parses as a name-subject per the ABNF ordered choice (RFC-009 §10.2)"
+    }
+  ],
+  "negative_uris": [
+    {
+      "uri": "iqa://3f9a1b2c.gateway.iqa/AUDIT",
+      "reason": "uppercase action - lowercase only (RFC-009 §10.3)"
+    },
+    {
+      "uri": "iqa://3F9A1B2C.gateway.iqa/audit",
+      "reason": "uppercase hex subject - lowercase only (RFC-009 §10.3)"
+    },
+    {
+      "uri": "IQA://3f9a1b2c.gateway.iqa/audit",
+      "reason": "uppercase scheme prefix - canonical form is lowercase (RFC-009 §10.3)"
+    },
+    {
+      "uri": "iqas://3f9a1b2c.gateway.iqa/audit",
+      "reason": "no iqas variant exists and no fallback is defined - fail closed (RFC-009 §12 #8)"
+    },
+    {
+      "uri": "iqa://subject@iqa.org",
+      "reason": "userinfo is not defined (RFC-009 §10.3)"
+    },
+    {
+      "uri": "iqa://iqa.org/RFC-009/",
+      "reason": "no organ, second path segment - this is an https matter (RFC-009 §10.3)"
+    },
+    {
+      "uri": "iqa://3f9a1b2c.forgery.iqa",
+      "reason": "organ is a closed set (RFC-009 §10.1/§10.3)"
+    },
+    {
+      "uri": "iqa://3f9a1b2c.gateway.iqa/pulse",
+      "reason": "action is a closed set - 'pulse' is not one of the four verbs (RFC-009 §10.1)"
+    },
+    {
+      "uri": "iqa://3f9a1b2c.Gateway.iqa/verify",
+      "reason": "organ is case-sensitive within the closed set (RFC-009 §10.3)"
+    },
+    {
+      "uri": "iqa://3f9a1b2c.gateway.iqa/audit?x=1",
+      "reason": "query is not defined (RFC-009 §10.3)"
+    },
+    {
+      "uri": "iqa://3f9a1b2c.gateway.iqa/audit#f",
+      "reason": "fragment is not defined (RFC-009 §10.3)"
+    },
+    {
+      "uri": "iqa://3f9a1b2c.gateway.iqa:443/audit",
+      "reason": "port is not defined (RFC-009 §10.3)"
+    },
+    {
+      "uri": "iqa://3f9a1b2c.gateway.iqa/a/b",
+      "reason": "second path segment - path is a single '/<action>' (RFC-009 §10.2)"
+    },
+    {
+      "uri": "iqa://3f9a1b2c.gateway.iqa/",
+      "reason": "trailing '/' with empty action - the closed set has no empty verb (RFC-009 §10.2)"
+    },
+    {
+      "uri": "iqa://a.b",
+      "reason": "authority has two segments, must be <subject>.<organ>.<root> (RFC-009 §10.2)"
+    },
+    {
+      "uri": "iqa://a.b.c.d/audit",
+      "reason": "authority has four segments, must be <subject>.<organ>.<root> (RFC-009 §10.2)"
+    },
+    {
+      "uri": "https://3f9a1b2c.gateway.iqa/audit",
+      "reason": "not an iqa scheme - there is no fallback (RFC-009 §10.3, §12 #8)"
+    },
+    {
+      "uri": "iqa://3f9a1b2c.gateway.iqa/audit ",
+      "reason": "trailing whitespace"
+    }
+  ],
+  "action_safety": [
+    {
+      "action": null,
+      "safe": true,
+      "why": "omitted - standing read (RFC-009 §11.1/§11.3)"
+    },
+    {
+      "action": "verify",
+      "safe": true,
+      "why": "read-only comparison, no state written (RFC-009 §11.3)"
+    },
+    {
+      "action": "audit",
+      "safe": false,
+      "why": "a failing measurement triggers Authority Ischemia (RFC-009 §11.3/§11.4)"
+    },
+    {
+      "action": "attest",
+      "safe": false,
+      "why": "state transition - Seal issuance (RFC-009 §11.3)"
+    },
+    {
+      "action": "revoke",
+      "safe": false,
+      "why": "state transition - standing withdrawal (RFC-009 §11.3)"
+    }
+  ],
+  "attest_envelope_vector": {
+    "v": 1,
+    "alg": "ed25519",
+    "aid": "3125ee20b2238281f70ca408192f82152647d365219184fa1fe22c08a42c035e",
+    "pub": "9c097c66ab4f82136ceddaef56854f740bf87da3eec42a249ba40bbb066f1e6a",
+    "ts": 1760000000,
+    "nonce": "0011223344556677",
+    "sig": "054b74c8dcd2b2128291ce433409983609d62c63a002138475d5e33bd21ea0b0c6243790db3d926ad6820cdf7e64f49cbd49a794a1b693cb60217a3382a5f007",
+    "payload": {
+      "subject_uri": "iqa://3f9a1b2c.gateway.iqa",
+      "organ": "gateway",
+      "standing": "radiant"
+    },
+    "seed_hex": "e722fed924c7f76b157faab674ea97bb7c3075f55ad7d3c6319418e22b86d611",
+    "signing_input_hex": "6971612d6174746573742d76310a7b22616964223a2233313235656532306232323338323831663730636134303831393266383231353236343764333635323139313834666131666532326330386134326330333565222c22616c67223a2265643235353139222c226e6f6e6365223a2230303131323233333434353536363737222c227061796c6f6164223a7b226f7267616e223a2267617465776179222c227374616e64696e67223a2272616469616e74222c227375626a6563745f757269223a226971613a2f2f33663961316232632e676174657761792e697161227d2c22707562223a2239633039376336366162346638323133366365646461656635363835346637343062663837646133656563343261323439626134306262623036366631653661222c227473223a313736303030303030307d",
+    "domain_prefix_hex": "6971612d6174746573742d76310a",
+    "expected": "verify MUST accept; aid MUST equal SHA-256(pub); signing input MUST reproduce byte for byte"
+  }
+}