kxco-pq-chain 1.0.0

package/LICENSE

@@ -0,0 +1,34 @@
+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.
+"Licensor" shall mean KXCO by Knightsbridge.
+"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.
+"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.
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form.
+"Work" shall mean the work of authorship made available under the License.
+"Derivative Works" shall mean any work that is based on the Work.
+"Contribution" shall mean any work of authorship submitted to the Licensor for inclusion in the Work.
+"Contributor" shall mean Licensor and any Legal Entity on behalf of whom a Contribution has been received by the Licensor and 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 patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work.
+
+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; and (d) If the Work includes a "NOTICE" text file, You must include a readable copy of the attribution notices contained within such NOTICE file.
+
+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.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor.
+
+7. Disclaimer of Warranty. THE WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
+
+8. Limitation of Liability. IN NO EVENT SHALL ANY CONTRIBUTOR BE LIABLE FOR ANY DAMAGES ARISING FROM THIS LICENSE OR THE USE OF THE WORK.
+
+Copyright 2026 KXCO by Knightsbridge

package/README.md

@@ -0,0 +1,147 @@
+# kxco-pq-chain
+
+HTTP client for the KXCO meta-transaction relay.
+
+Institutions sign ML-DSA-65 intents with their existing post-quantum identity. KXCO validates the signature, pays gas in ARMR, and submits the EVM transaction on Armature L1. Institutions never hold a wallet or pay gas directly — KXCO bills monthly via invoice.
+
+---
+
+## Install
+
+```bash
+npm install kxco-pq-chain
+```
+
+## Usage
+
+```js
+import { KxcoChain } from 'kxco-pq-chain'
+
+// identity is a KxcoIdentity from kxco-pq-sdk
+const chain = new KxcoChain({
+  relay:    'https://relay.kxco.ai',
+  identity: institutionIdentity,
+  timeout:  10_000,   // optional, ms (default 10 000)
+})
+
+// Register an institution on-chain (called once during onboarding)
+const { txHash, blockNumber } = await chain.registerInstitution({
+  publicKeyHex: Buffer.from(identity.publicKey).toString('hex'),
+  metadataUrl:  'https://example.com/institution.json',   // optional
+})
+
+// Record a credential issuance
+await chain.issueCredential({
+  userKid:         'aa29f37ab7f4b2cf',
+  userPublicKeyHex: Buffer.from(userPublicKey).toString('hex'),
+  role:            'verified-user',
+  expiresAt:       1800000000,   // unix seconds, optional (0 = no expiry)
+})
+
+// Revoke a credential
+await chain.revokeCredential({
+  userKid: 'aa29f37ab7f4b2cf',
+  reason:  'kyc-expired',   // optional
+})
+
+// Anchor an audit log checkpoint
+await chain.anchorAuditRoot({
+  rootHash:   'a3f1...64-hex-chars',
+  entryCount: 100,
+})
+
+// Anchor an attestation envelope hash
+await chain.anchorAttestation({
+  payloadHash: 'b7c2...64-hex-chars',
+  purpose:     'regulatory-report',
+})
+
+// Record a key rotation
+await chain.rotateKey({
+  newKid:          'bb39a48bc5e4d1f0',
+  newPublicKeyHex: Buffer.from(newPublicKey).toString('hex'),
+})
+```
+
+All methods return `Promise<{ txHash: string, blockNumber: number }>` on success and throw `KxcoChainError` on failure.
+
+---
+
+## Error handling
+
+```js
+import { KxcoChain, KxcoChainError } from 'kxco-pq-chain'
+
+try {
+  await chain.issueCredential({ ... })
+} catch (err) {
+  if (err instanceof KxcoChainError) {
+    console.error(err.code)    // 'CREDIT_EXHAUSTED', 'TIMEOUT', 'NETWORK_ERROR', ...
+    console.error(err.status)  // HTTP status or null
+    console.error(err.body)    // raw relay response body or null
+  }
+}
+```
+
+Common error codes: `BAD_CONFIG`, `TIMEOUT`, `NETWORK_ERROR`, `PARSE_ERROR`, `RELAY_ERROR`, plus relay-specific codes like `CREDIT_EXHAUSTED`.
+
+---
+
+## Relay request format
+
+Every request is a signed JSON intent. The relay validates the ML-DSA-65 signature against the registered institution public key before submitting the EVM transaction.
+
+```json
+{
+  "operation":      "issueCredential",
+  "institutionKid": "aa29f37ab7f4b2cf",
+  "nonce":          "<64 random hex chars>",
+  "timestamp":      1748342400,
+  "payload":        { "...JCS-canonical operation fields..." },
+  "signature":      "<ML-DSA-65 hex signature>"
+}
+```
+
+Signing message (newline-delimited UTF-8):
+
+```
+kxco-relay-v1
+operation: issueCredential
+institutionKid: aa29f37ab7f4b2cf
+nonce: <hex>
+timestamp: <unix seconds>
+payload: <JCS-canonical JSON of payload>
+```
+
+Replay protection: the relay rejects requests where `timestamp` is outside ±5 minutes of server time, or where the `nonce` has been seen before.
+
+---
+
+## Low-level helpers
+
+```js
+import { buildSigningMessage, buildIntent, randomNonce, canonicalize } from 'kxco-pq-chain'
+
+// Build the canonical signing message for a relay intent
+const msg = buildSigningMessage(operation, institutionKid, nonce, timestamp, payload)
+
+// Build and sign a complete relay intent object
+const intent = await buildIntent({ operation, institutionKid, payload, identity })
+
+// Generate a cryptographically random 64-hex-char nonce
+const nonce = randomNonce()
+
+// RFC 8785 JSON Canonicalization Scheme
+const canonical = canonicalize({ b: 2, a: 1 })  // '{"a":1,"b":2}'
+```
+
+---
+
+## Requirements
+
+- Node.js 20.19+
+- `kxco-post-quantum` (installed automatically as a dependency)
+
+## License
+
+Apache-2.0 — Copyright 2026 KXCO by Knightsbridge

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "kxco-pq-chain",
+  "version": "1.0.0",
+  "description": "HTTP client for the KXCO meta-transaction relay. Institutions sign ML-DSA-65 intents; KXCO pays gas and submits EVM transactions on Armature L1.",
+  "keywords": [
+    "post-quantum",
+    "pqc",
+    "ml-dsa",
+    "nist",
+    "fips-204",
+    "blockchain",
+    "meta-transaction",
+    "relay",
+    "kxco",
+    "armature",
+    "identity-registry",
+    "credential",
+    "audit-anchor",
+    "attestation"
+  ],
+  "license": "Apache-2.0",
+  "author": "KXCO by Knightsbridge <hello@kxco.ai>",
+  "contributors": [
+    {
+      "name": "Shayne Heffernan"
+    },
+    {
+      "name": "John Heffernan"
+    }
+  ],
+  "homepage": "https://kxco.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JackKXCO/kxco-pq-chain.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JackKXCO/kxco-pq-chain/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "dependencies": {
+    "kxco-post-quantum": "^1.1.6"
+  },
+  "scripts": {
+    "test": "node --test --test-timeout=30000 test/chain.test.js"
+  },
+  "funding": "https://kxco.ai",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/client.js

@@ -0,0 +1,170 @@
+/**
+ * KxcoChain — HTTP client for the KXCO meta-transaction relay.
+ *
+ * Institutions never interact with Armature L1 directly. This client
+ * sends ML-DSA-65 signed intents to the KXCO relay, which validates
+ * the signature and submits the EVM transaction on the institution's behalf.
+ *
+ * All six operations return { txHash, blockNumber } on success and throw
+ * KxcoChainError on failure.
+ */
+
+import { buildIntent } from './intents.js'
+import { KxcoChainError } from './errors.js'
+
+export class KxcoChain {
+  #relay
+  #identity
+  #timeout
+
+  /**
+   * @param {object} opts
+   * @param {string} opts.relay     — relay base URL, e.g. 'https://relay.kxco.ai'
+   * @param {object} opts.identity  — KxcoIdentity from kxco-pq-sdk (must have .kid and .sign())
+   * @param {number} [opts.timeout] — request timeout in ms (default 10000)
+   */
+  constructor({ relay, identity, timeout = 10_000 }) {
+    if (!relay)    throw new KxcoChainError('relay URL is required',    { code: 'BAD_CONFIG' })
+    if (!identity) throw new KxcoChainError('identity is required',     { code: 'BAD_CONFIG' })
+    this.#relay    = relay.replace(/\/$/, '')
+    this.#identity = identity
+    this.#timeout  = timeout
+  }
+
+  // ─── operations ──────────────────────────────────────────────────────────
+
+  /**
+   * Register an institution on-chain. Called once during institution onboarding.
+   * @param {object} opts
+   * @param {string} opts.publicKeyHex  — hex-encoded 1952-byte ML-DSA-65 public key
+   * @param {string} [opts.metadataUrl] — URL of institution metadata JSON
+   * @returns {Promise<{txHash: string, blockNumber: number}>}
+   */
+  async registerInstitution({ publicKeyHex, metadataUrl = '' }) {
+    return this.#send('registerInstitution', {
+      publicKeyHex,
+      metadataUrl,
+    })
+  }
+
+  /**
+   * Record a user credential issuance on-chain.
+   * @param {object} opts
+   * @param {string} opts.userKid         — 16-hex-char kid of the issued user
+   * @param {string} opts.userPublicKeyHex — hex-encoded user ML-DSA-65 public key
+   * @param {string} opts.role            — role string (e.g. 'verified-user')
+   * @param {number} [opts.expiresAt]     — unix seconds; omit or 0 = no expiry
+   * @returns {Promise<{txHash: string, blockNumber: number}>}
+   */
+  async issueCredential({ userKid, userPublicKeyHex, role, expiresAt = 0 }) {
+    return this.#send('issueCredential', {
+      userKid,
+      userPublicKeyHex,
+      role,
+      expiresAt,
+    })
+  }
+
+  /**
+   * Revoke a user credential on-chain.
+   * @param {object} opts
+   * @param {string} opts.userKid       — kid of the user whose credential is revoked
+   * @param {string} [opts.reason]      — human-readable revocation reason
+   * @returns {Promise<{txHash: string, blockNumber: number}>}
+   */
+  async revokeCredential({ userKid, reason = '' }) {
+    return this.#send('revokeCredential', {
+      userKid,
+      reason,
+    })
+  }
+
+  /**
+   * Anchor an audit log checkpoint on-chain.
+   * @param {object} opts
+   * @param {string} opts.rootHash    — hex SHA-256 of the latest AuditLog entry hash
+   * @param {number} opts.entryCount  — total entries in the log at checkpoint time
+   * @returns {Promise<{txHash: string, blockNumber: number}>}
+   */
+  async anchorAuditRoot({ rootHash, entryCount }) {
+    return this.#send('anchorAuditRoot', {
+      rootHash,
+      entryCount,
+    })
+  }
+
+  /**
+   * Anchor a high-value attestation envelope hash on-chain.
+   * @param {object} opts
+   * @param {string} opts.payloadHash — hex SHA-256 of the signed attestation envelope
+   * @param {string} opts.purpose     — purpose string (e.g. 'regulatory-report')
+   * @returns {Promise<{txHash: string, blockNumber: number}>}
+   */
+  async anchorAttestation({ payloadHash, purpose }) {
+    return this.#send('anchorAttestation', {
+      payloadHash,
+      purpose,
+    })
+  }
+
+  /**
+   * Record an institution key rotation on-chain.
+   * @param {object} opts
+   * @param {string} opts.newKid           — new 16-hex-char kid after rotation
+   * @param {string} opts.newPublicKeyHex  — hex-encoded new ML-DSA-65 public key
+   * @returns {Promise<{txHash: string, blockNumber: number}>}
+   */
+  async rotateKey({ newKid, newPublicKeyHex }) {
+    return this.#send('rotateKey', {
+      newKid,
+      newPublicKeyHex,
+    })
+  }
+
+  // ─── internal ────────────────────────────────────────────────────────────
+
+  async #send(operation, payload) {
+    const intent = await buildIntent({
+      operation,
+      institutionKid: this.#identity.kid,
+      payload,
+      identity: this.#identity,
+    })
+
+    const ac  = new AbortController()
+    const tid = setTimeout(() => ac.abort(), this.#timeout)
+
+    let response
+    try {
+      response = await fetch(`${this.#relay}/intents`, {
+        method:  'POST',
+        headers: { 'content-type': 'application/json' },
+        body:    JSON.stringify(intent),
+        signal:  ac.signal,
+      })
+    } catch (err) {
+      clearTimeout(tid)
+      if (err.name === 'AbortError') {
+        throw new KxcoChainError(`relay request timed out after ${this.#timeout}ms`, { code: 'TIMEOUT' })
+      }
+      throw new KxcoChainError(`relay request failed: ${err.message}`, { code: 'NETWORK_ERROR' })
+    }
+    clearTimeout(tid)
+
+    let body
+    try {
+      body = await response.json()
+    } catch {
+      throw new KxcoChainError('relay returned non-JSON response', { code: 'PARSE_ERROR', status: response.status })
+    }
+
+    if (!response.ok || body.ok === false) {
+      throw new KxcoChainError(
+        body.error ?? `relay error ${response.status}`,
+        { code: body.code ?? 'RELAY_ERROR', status: response.status, body }
+      )
+    }
+
+    return { txHash: body.txHash, blockNumber: body.blockNumber }
+  }
+}

package/src/errors.js

@@ -0,0 +1,9 @@
+export class KxcoChainError extends Error {
+  constructor(message, { code, status, body } = {}) {
+    super(message)
+    this.name   = 'KxcoChainError'
+    this.code   = code   ?? 'CHAIN_ERROR'
+    this.status = status ?? null
+    this.body   = body   ?? null
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,96 @@
+// ── KxcoChainError ────────────────────────────────────────────────────────────
+
+export class KxcoChainError extends Error {
+  name: 'KxcoChainError'
+  code: string
+  status: number | null
+  body: unknown | null
+}
+
+// ── Intent types ──────────────────────────────────────────────────────────────
+
+export interface RelayIntent {
+  operation:      string
+  institutionKid: string
+  nonce:          string
+  timestamp:      number
+  payload:        Record<string, unknown>
+  signature:      string
+}
+
+export interface RelayResult {
+  txHash:      string
+  blockNumber: number
+}
+
+// ── KxcoChain ─────────────────────────────────────────────────────────────────
+
+export interface KxcoChainOptions {
+  relay:      string
+  /** KxcoIdentity from kxco-pq-sdk — must have .kid (string) and .sign(Uint8Array) */
+  identity:   { kid: string; sign(message: Uint8Array): Promise<Uint8Array> }
+  timeout?:   number
+}
+
+export interface RegisterInstitutionOpts {
+  publicKeyHex:  string
+  metadataUrl?:  string
+}
+
+export interface IssueCredentialOpts {
+  userKid:         string
+  userPublicKeyHex: string
+  role:            string
+  expiresAt?:      number
+}
+
+export interface RevokeCredentialOpts {
+  userKid: string
+  reason?: string
+}
+
+export interface AnchorAuditRootOpts {
+  rootHash:   string
+  entryCount: number
+}
+
+export interface AnchorAttestationOpts {
+  payloadHash: string
+  purpose:     string
+}
+
+export interface RotateKeyOpts {
+  newKid:          string
+  newPublicKeyHex: string
+}
+
+export class KxcoChain {
+  constructor(opts: KxcoChainOptions)
+  registerInstitution(opts: RegisterInstitutionOpts): Promise<RelayResult>
+  issueCredential(opts: IssueCredentialOpts):         Promise<RelayResult>
+  revokeCredential(opts: RevokeCredentialOpts):       Promise<RelayResult>
+  anchorAuditRoot(opts: AnchorAuditRootOpts):         Promise<RelayResult>
+  anchorAttestation(opts: AnchorAttestationOpts):     Promise<RelayResult>
+  rotateKey(opts: RotateKeyOpts):                     Promise<RelayResult>
+}
+
+// ── Low-level helpers ─────────────────────────────────────────────────────────
+
+export function buildSigningMessage(
+  operation:      string,
+  institutionKid: string,
+  nonce:          string,
+  timestamp:      number,
+  payload:        Record<string, unknown>,
+): Uint8Array
+
+export function randomNonce(): string
+
+export function buildIntent(opts: {
+  operation:      string
+  institutionKid: string
+  payload:        Record<string, unknown>
+  identity:       { kid: string; sign(message: Uint8Array): Promise<Uint8Array> }
+}): Promise<RelayIntent>
+
+export function canonicalize(value: unknown): string

package/src/index.js

@@ -0,0 +1,4 @@
+export { KxcoChain }      from './client.js'
+export { KxcoChainError } from './errors.js'
+export { buildIntent, buildSigningMessage, randomNonce } from './intents.js'
+export { canonicalize }   from './jcs.js'

package/src/intents.js

@@ -0,0 +1,82 @@
+/**
+ * Relay intent builder + signer.
+ *
+ * Every relay request is a signed JSON intent that proves the institution
+ * authorised the operation. The relay validates the ML-DSA-65 signature
+ * off-chain before submitting the EVM transaction.
+ *
+ * Signing message format (newline-delimited, UTF-8):
+ *
+ *   kxco-relay-v1
+ *   operation: <name>
+ *   institutionKid: <16-hex-char kid>
+ *   nonce: <64 random hex chars>
+ *   timestamp: <unix seconds>
+ *   payload: <JCS-canonical JSON of the payload object>
+ *
+ * Replay protection: the relay rejects requests where timestamp is outside
+ * ±5 minutes of server time, or where the nonce has been seen before.
+ */
+
+import { canonicalize } from './jcs.js'
+
+const enc = new TextEncoder()
+
+/**
+ * Build the signing message for a relay intent.
+ * @param {string} operation
+ * @param {string} institutionKid
+ * @param {string} nonce          — 64 random hex chars
+ * @param {number} timestamp      — unix seconds
+ * @param {object} payload
+ * @returns {Uint8Array}
+ */
+export function buildSigningMessage(operation, institutionKid, nonce, timestamp, payload) {
+  return enc.encode([
+    'kxco-relay-v1',
+    `operation: ${operation}`,
+    `institutionKid: ${institutionKid}`,
+    `nonce: ${nonce}`,
+    `timestamp: ${timestamp}`,
+    `payload: ${canonicalize(payload)}`,
+  ].join('\n'))
+}
+
+/**
+ * Generate a cryptographically random 64-hex-char nonce.
+ * Node 20+ exposes globalThis.crypto; earlier versions use node:crypto.
+ * @returns {string}
+ */
+export function randomNonce() {
+  const bytes = new Uint8Array(32)
+  // globalThis.crypto is available in Node 20+ and all modern browsers
+  globalThis.crypto.getRandomValues(bytes)
+  return Buffer.from(bytes).toString('hex')
+}
+
+/**
+ * Build and sign a relay intent payload.
+ *
+ * @param {object} opts
+ * @param {string} opts.operation
+ * @param {string} opts.institutionKid
+ * @param {object} opts.payload
+ * @param {object} opts.identity   — KxcoIdentity (must have .kid and .sign())
+ * @returns {Promise<object>}      — the complete signed intent object
+ */
+export async function buildIntent({ operation, institutionKid, payload, identity }) {
+  const nonce     = randomNonce()
+  const timestamp = Math.floor(Date.now() / 1000)
+  const message   = buildSigningMessage(operation, institutionKid, nonce, timestamp, payload)
+  const sigBytes  = await identity.sign(message)
+  const signature = Buffer.from(sigBytes).toString('hex')
+
+  return {
+    operation,
+    institutionKid,
+    nonce,
+    timestamp,
+    payload,
+    signature,
+  }
+}

package/src/jcs.js

@@ -0,0 +1,34 @@
+// RFC 8785 JSON Canonicalization Scheme (JCS), subset.
+// Copied from kxco-pq-cli/src/jcs.js — do not diverge.
+
+/**
+ * Canonicalize a JSON-serializable value per (a subset of) RFC 8785.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function canonicalize(value) {
+  return JSON.stringify(walk(value))
+}
+
+function walk(v) {
+  if (v === null) return null
+  if (typeof v === 'boolean') return v
+  if (typeof v === 'string')  return v
+  if (typeof v === 'number') {
+    if (!Number.isFinite(v)) throw new TypeError('JCS: non-finite numbers are not representable in JSON')
+    if (!Number.isInteger(v)) throw new TypeError('JCS subset: floats are not supported')
+    return v
+  }
+  if (Array.isArray(v)) return v.map(walk)
+  if (v && typeof v === 'object') {
+    const out = {}
+    for (const k of Object.keys(v).sort()) {
+      const child = walk(v[k])
+      if (child === undefined) continue
+      out[k] = child
+    }
+    return out
+  }
+  if (v === undefined) return undefined
+  throw new TypeError(`JCS: unsupported value of type ${typeof v}`)
+}