@aicent/iqa 1.2.8 → 1.3.2

package/src/iqa-uri.mjs

@@ -1,169 +1,169 @@
-// iqa:// URI codec -- validate, canonicalise, derive (RFC-009 sec. 10/sec. 11).
-//
-// Authority boundaries:
-//   Grammar ......... RFC-009 sec. 10.2 ABNF (sole authority)
-//   Closed sets ..... sec. 10.1 (organ and action are CLOSED sets)
-//   Case discipline . sec. 10.3 (lowercase US-ASCII only) + sec. 12 #8 (fail closed)
-//   Deref safety .... sec. 11.3 (action safety classes)
-//   Route derivation  SPEC/IQA-URI-ATTEST-v1.2.6.md sec. 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 sec. 10.1 -- organ is a CLOSED set (RFC-009-A/-B/-C). */
-export const ORGANS = Object.freeze(['forge', 'tss', 'gateway']);
-
-/**
- * RFC-009 sec. 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 sec. 3 -- standings an Organ may render (closed set, lowercase). */
-export const STANDINGS = Object.freeze(['ghost', 'probation', 'radiant', 'genesis']);
-
-/** RFC-009 sec. 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']); // sec. 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}`);
-
-/** sec. 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 sec. 3, decision D1).
- *
- * Pure computation, DNS-free (RFC-009 sec. 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 sec. 10.3, sec. 12 #8)');
-  }
-  const rest = uri.slice(prefix.length);
-
-  // Charset gate: lowercase US-ASCII only (sec. 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 sec. 10.3)`);
-      }
-      if (/\s/.test(ch)) {
-        throw fail(uri, 'whitespace is not allowed (RFC-009 sec. 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 (sec. 10.2)');
-    }
-    if (action.includes('/')) {
-      throw fail(uri, "second path segment - path is a single '/<action>' (sec. 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 sec. 10.2)');
-  }
-  const [subject, organ, root] = segments;
-  if (subject === '' || root === '') {
-    throw fail(uri, 'authority segments must be non-empty (RFC-009 sec. 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 (sec. 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 sec. 10.1/sec. 10.3)`);
-  }
-
-  // Action -- CLOSED set (sec. 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 sec. 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),           // sec. 11.3
-    canonical_uri: canonicalUri,
-    route_hex: deriveRouteHex(authority),    // SPEC sec. 3
-  };
-}
+// iqa:// URI codec -- validate, canonicalise, derive (AICENT-009 sec. 10/sec. 11).
+//
+// Authority boundaries:
+//   Grammar ......... AICENT-009 sec. 10.2 ABNF (sole authority)
+//   Closed sets ..... sec. 10.1 (organ and action are CLOSED sets)
+//   Case discipline . sec. 10.3 (lowercase US-ASCII only) + sec. 12 #8 (fail closed)
+//   Deref safety .... sec. 11.3 (action safety classes)
+//   Route derivation  SPEC/IQA-URI-ATTEST-v1.2.6.md sec. 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';
+
+/** AICENT-009 sec. 10.1 -- organ is a CLOSED set (AICENT-009-A/-B/-C). */
+export const ORGANS = Object.freeze(['forge', 'tss', 'gateway']);
+
+/**
+ * AICENT-009 sec. 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']);
+
+/** AICENT-009-C sec. 3 -- standings an Organ may render (closed set, lowercase). */
+export const STANDINGS = Object.freeze(['ghost', 'probation', 'radiant', 'genesis']);
+
+/** AICENT-009 sec. 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']); // sec. 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}`);
+
+/** sec. 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 sec. 3, decision D1).
+ *
+ * Pure computation, DNS-free (AICENT-009 sec. 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 (AICENT-009 sec. 10.3, sec. 12 #8)');
+  }
+  const rest = uri.slice(prefix.length);
+
+  // Charset gate: lowercase US-ASCII only (sec. 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 (AICENT-009 sec. 10.3)`);
+      }
+      if (/\s/.test(ch)) {
+        throw fail(uri, 'whitespace is not allowed (AICENT-009 sec. 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 (sec. 10.2)');
+    }
+    if (action.includes('/')) {
+      throw fail(uri, "second path segment - path is a single '/<action>' (sec. 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> (AICENT-009 sec. 10.2)');
+  }
+  const [subject, organ, root] = segments;
+  if (subject === '' || root === '') {
+    throw fail(uri, 'authority segments must be non-empty (AICENT-009 sec. 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 (sec. 10.1). 'Forge', 'forgery', '' all fail.
+  if (!ORGANS.includes(organ)) {
+    throw fail(uri, `organ ${JSON.stringify(organ)} is outside the closed set `
+      + `[${ORGANS.join(', ')}] (AICENT-009 sec. 10.1/sec. 10.3)`);
+  }
+
+  // Action -- CLOSED set (sec. 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(', ')}] (AICENT-009 sec. 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),           // sec. 11.3
+    canonical_uri: canonicalUri,
+    route_hex: deriveRouteHex(authority),    // SPEC sec. 3
+  };
+}

package/src/vectors.json

@@ -1,8 +1,8 @@
 {
   "spec": "IQA-URI-ATTEST-v1.2.6",
   "applies_to": [
-    "RFC-009 sec. 10",
-    "RFC-009 sec. 11"
+    "draft-li-rttp-iqa-addressing-02 §§4.2, 5",
+    "AICENT-009 sec. 10-11 (attestation semantics; beyond -02)"
   ],
   "generated_by": "SPEC/tools/iqa_conformance.py",
   "note": "Generated file - do not edit by hand. Change the cases in iqa_conformance.py instead.",
@@ -135,108 +135,108 @@
       "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 sec. 10.2)"
+      "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 (draft-02 §5.1)"
     }
   ],
   "negative_uris": [
     {
       "uri": "iqa://3f9a1b2c.gateway.iqa/AUDIT",
-      "reason": "uppercase action - lowercase only (RFC-009 sec. 10.3)"
+      "reason": "uppercase action - lowercase only (draft-02 §4.2 + §5.1)"
     },
     {
       "uri": "iqa://3F9A1B2C.gateway.iqa/audit",
-      "reason": "uppercase hex subject - lowercase only (RFC-009 sec. 10.3)"
+      "reason": "uppercase hex subject - lowercase only (draft-02 §4.2 + §5.2)"
     },
     {
       "uri": "IQA://3f9a1b2c.gateway.iqa/audit",
-      "reason": "uppercase scheme prefix - canonical form is lowercase (RFC-009 sec. 10.3)"
+      "reason": "uppercase scheme prefix - canonical form is lowercase (draft-02 §4.2)"
     },
     {
       "uri": "iqas://3f9a1b2c.gateway.iqa/audit",
-      "reason": "no iqas variant exists and no fallback is defined - fail closed (RFC-009 sec. 12 #8)"
+      "reason": "no iqas variant exists and no fallback is defined - fail closed (draft-02 §5.2)"
     },
     {
       "uri": "iqa://subject@iqa.org",
-      "reason": "userinfo is not defined (RFC-009 sec. 10.3)"
+      "reason": "userinfo is not defined (draft-02 §4.2)"
     },
     {
       "uri": "iqa://iqa.org/RFC-009/",
-      "reason": "no organ, second path segment - this is an https matter (RFC-009 sec. 10.3)"
+      "reason": "no organ, second path segment - this is an https matter (draft-02 §5.1)"
     },
     {
       "uri": "iqa://3f9a1b2c.forgery.iqa",
-      "reason": "organ is a closed set (RFC-009 sec. 10.1/sec. 10.3)"
+      "reason": "organ is a closed set (draft-02 §5.1)"
     },
     {
       "uri": "iqa://3f9a1b2c.gateway.iqa/pulse",
-      "reason": "action is a closed set - 'pulse' is not one of the four verbs (RFC-009 sec. 10.1)"
+      "reason": "action is a closed set - 'pulse' is not one of the four verbs (draft-02 §5.1)"
     },
     {
       "uri": "iqa://3f9a1b2c.Gateway.iqa/verify",
-      "reason": "organ is case-sensitive within the closed set (RFC-009 sec. 10.3)"
+      "reason": "organ is case-sensitive within the closed set (draft-02 §5.1 + §4.2)"
     },
     {
       "uri": "iqa://3f9a1b2c.gateway.iqa/audit?x=1",
-      "reason": "query is not defined (RFC-009 sec. 10.3)"
+      "reason": "query is not defined (draft-02 §4.2)"
     },
     {
       "uri": "iqa://3f9a1b2c.gateway.iqa/audit#f",
-      "reason": "fragment is not defined (RFC-009 sec. 10.3)"
+      "reason": "fragment is not defined (draft-02 §4.2)"
     },
     {
       "uri": "iqa://3f9a1b2c.gateway.iqa:443/audit",
-      "reason": "port is not defined (RFC-009 sec. 10.3)"
+      "reason": "port is not defined (draft-02 §4.2)"
     },
     {
       "uri": "iqa://3f9a1b2c.gateway.iqa/a/b",
-      "reason": "second path segment - path is a single '/<action>' (RFC-009 sec. 10.2)"
+      "reason": "second path segment - path is a single '/<action>' (draft-02 §5.1)"
     },
     {
       "uri": "iqa://3f9a1b2c.gateway.iqa/",
-      "reason": "trailing '/' with empty action - the closed set has no empty verb (RFC-009 sec. 10.2)"
+      "reason": "trailing '/' with empty action - the closed set has no empty verb (draft-02 §5.1)"
     },
     {
       "uri": "iqa://a.b",
-      "reason": "authority has two segments, must be <subject>.<organ>.<root> (RFC-009 sec. 10.2)"
+      "reason": "authority has two segments, must be <subject>.<organ>.<root> (draft-02 §5.1)"
     },
     {
       "uri": "iqa://a.b.c.d/audit",
-      "reason": "authority has four segments, must be <subject>.<organ>.<root> (RFC-009 sec. 10.2)"
+      "reason": "authority has four segments, must be <subject>.<organ>.<root> (draft-02 §5.1)"
     },
     {
       "uri": "https://3f9a1b2c.gateway.iqa/audit",
-      "reason": "not an iqa scheme - there is no fallback (RFC-009 sec. 10.3, sec. 12 #8)"
+      "reason": "not an iqa scheme - there is no fallback (draft-02 §5.2 + §4.5.2)"
     },
     {
       "uri": "iqa://3f9a1b2c.gateway.iqa/audit ",
-      "reason": "trailing whitespace"
+      "reason": "trailing whitespace (draft-02 §5.1)"
     }
   ],
   "action_safety": [
     {
       "action": null,
       "safe": true,
-      "why": "omitted - standing read (RFC-009 sec. 11.1/sec. 11.3)"
+      "why": "omitted - standing read (draft-02 §5.3/§5.4)"
     },
     {
       "action": "verify",
       "safe": true,
-      "why": "read-only comparison, no state written (RFC-009 sec. 11.3)"
+      "why": "read-only comparison, no state written (draft-02 §5.4)"
     },
     {
       "action": "audit",
       "safe": false,
-      "why": "a failing measurement triggers Authority Ischemia (RFC-009 sec. 11.3/sec. 11.4)"
+      "why": "a failing measurement may change standing (draft-02 §5.4)"
     },
     {
       "action": "attest",
       "safe": false,
-      "why": "state transition - Seal issuance (RFC-009 sec. 11.3)"
+      "why": "state transition - Seal issuance (draft-02 §5.4)"
     },
     {
       "action": "revoke",
       "safe": false,
-      "why": "state transition - standing withdrawal (RFC-009 sec. 11.3)"
+      "why": "state transition - standing withdrawal (draft-02 §5.4)"
     }
   ],
   "attest_envelope_vector": {