@aicent/iqa 1.2.7 → 1.3.1

package/src/conformance.mjs

@@ -1,181 +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 };
-}
+// IQA conformance replay -- an INDEPENDENT implementation of AICENT-009 sec. 10.
+//
+// This file is written from AICENT-009 sec. 10/sec. 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'];         // sec. 10.1 closed set
+const ACTIONS = ['verify', 'audit', 'attest', 'revoke']; // sec. 10.1 closed set
+const HASH_LENGTHS = [8, 32, 64];                   // sec. 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', // sec. 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/envelope.d.mts

@@ -0,0 +1,103 @@
+/**
+ * AE-128 -- the fixed 128-byte attestation envelope (companion draft v0.3).
+ * Zero dependencies. Field names are snake_case on purpose: they match the
+ * Python implementation (iqa.envelope) and the published vector byte for byte.
+ */
+
+export declare const SIZE: 128;
+export declare const MAGIC: 'IQAE';
+export declare const VERSION: 1;
+export declare const ALGORITHM_HMAC_SHA256: 0x01;
+
+export declare const OFF_MAGIC: 0;
+export declare const OFF_VERSION: 4;
+export declare const OFF_ALGORITHM: 5;
+export declare const OFF_FLAGS: 6;
+export declare const OFF_LEASE: 8;
+export declare const OFF_SHARD: 16;
+export declare const OFF_ATTESTATION: 32;
+export declare const OFF_ORGAN: 64;
+export declare const OFF_NONCE: 72;
+export declare const OFF_STANDING: 80;
+export declare const OFF_RESERVED: 81;
+export declare const OFF_EXTENSION: 96;
+
+/** Standing closed set per AICENT-009 sec. 11.1.1. */
+export declare const STANDING_CODES: Readonly<Record<'ghost' | 'probation' | 'radiant' | 'genesis', number>>;
+export declare const STANDING_NAMES: Readonly<Record<number, string>>;
+
+export declare class EnvelopeError extends Error {}
+
+/**
+ * ROUTE_SHARD = SHA-256(ASCII(canonical_authority))[0:16]  (I-D sec. 4.4).
+ * The same derivation the rttp pulse frame carries at offset 0x36 -- NOT
+ * deriveRoute() (the 4-octet IQA_ROUTE address fingerprint).
+ */
+export declare function deriveIntentShard(canonicalAuthority: string): Uint8Array;
+export declare function intentShardHex(canonicalAuthority: string): string;
+
+export interface EncodeParams {
+  /** Organ key material (non-empty). HMAC-SHA256 secret. */
+  key: Uint8Array;
+  /** The subject's ROUTE_SHARD: 16 bytes or 32 hex characters. */
+  intent_shard: Uint8Array | string;
+  /** US-ASCII organ tag, 1..8 characters, right-padded with 0x00. */
+  organ: string | Uint8Array;
+  /** Standing: a closed-set wire code or its lowercase name. */
+  standing: number | string;
+  /** u64 BE Unix seconds -- verdict valid until (inclusive). */
+  lease_expiry: number;
+  /** u64 BE -- unique per verdict issued. */
+  nonce: number;
+  /** Must be 0x0000 in version 1 (unassigned). */
+  flags?: number;
+}
+
+/** Build one AE-128 frame -- exactly 128 bytes (draft sec. 2 + sec. 3). */
+export declare function encode(params: EncodeParams): Uint8Array;
+
+export interface ParsedEnvelope {
+  version: number;
+  algorithm: number;
+  flags: number;
+  lease_expiry: number;
+  intent_shard: Uint8Array;
+  attestation: Uint8Array;
+  organ: string;
+  nonce: number;
+  standing: number;
+  standing_name: string;
+}
+
+/** Structural decode -- fail closed on every rule. Throws EnvelopeError. */
+export declare function parse(data: Uint8Array): ParsedEnvelope;
+
+export interface VerifyResult {
+  ok: boolean;
+  reason: string;
+  /** The parsed frame on success, null on failure. */
+  frame: ParsedEnvelope | null;
+}
+
+/**
+ * Verify one AE-128 frame (draft sec. 4). Constant-time HMAC compare.
+ * A failure is a RESULT, never an exception. now defaults to the wall clock;
+ * check_lease=false is the archival mode.
+ */
+export declare function verify(
+  data: Uint8Array,
+  key: Uint8Array,
+  opts?: { now?: number | null; check_lease?: boolean },
+): VerifyResult;
+
+export declare const VECTOR_1_AUTHORITY: string;
+export declare const VECTOR_1_KEY: Uint8Array;
+export declare const VECTOR_1_LEASE: 1798761600;
+export declare const VECTOR_1_STANDING: 'radiant';
+export declare const VECTOR_1_ORGAN: 'ORG-TEST';
+export declare const VECTOR_1_NONCE: 1;
+/** The full 128-octet published vector, as lowercase hex. */
+export declare const VECTOR_1_FRAME_HEX: string;
+
+/** The published vector as bytes -- encode() of the documented parameters. */
+export declare function vector1Frame(): Uint8Array;