kxco-pq-agent 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,155 @@
+# kxco-pq-agent
+
+Post-quantum AI agent and robot identity for the KXCO platform.
+
+Institutions that hold a `KxcoIdentity` (from `kxco-pq-sdk`) can sponsor machine identities — LLMs, robots, IoT devices, and automated processes — that cannot pass KYC themselves. The sponsoring institution signs the agent's ML-DSA-65 public key and a structured capability scope, anchoring the agent's authority to their own verified identity.
+
+**Not open source.** This package is part of the KXCO Chain platform. Contact hello@kxco.ai for licensing.
+
+---
+
+## How it works
+
+1. A KYC'd institution generates an ML-DSA-65 keypair for the agent
+2. The institution signs a credential binding the agent's public key to a capability scope
+3. The agent presents this credential with every relay request, signed with its own private key
+4. The KXCO relay validates both the credential (institution's signature) and the intent (agent's signature) before submitting to chain
+
+The credential scope is locked at issuance. To change an agent's permissions, revoke and re-issue.
+
+---
+
+## Install
+
+```bash
+npm install kxco-pq-agent
+```
+
+---
+
+## Usage
+
+### Issue an agent credential
+
+```js
+import { KxcoAgentIdentity } from 'kxco-pq-agent'
+
+// `sponsor` is a KxcoIdentity from kxco-pq-sdk
+const agent = await KxcoAgentIdentity.create({
+  sponsor,
+  label:     'Trading Bot v2',
+  agentType: 'llm',
+  model:     'claude-opus-4-7',   // optional — model/firmware/version string
+  scope: {
+    payments: {
+      maxPerTransaction: 5000,   // ARMR, in smallest denomination
+      maxPerDay:         50000,
+      allowedRecipients: [
+        '0xAbC123...',                // EVM address
+        'aa29f37ab7f4b2cf',           // KXCO kid
+      ],
+    },
+    attestations: {
+      purposes: ['trade-confirmation', 'settlement-receipt'],
+    },
+    auditLog:    true,
+    credentials: false,
+  },
+  expiresIn: '90d',   // '30d', '1y', or seconds as a number
+  chain,              // optional KxcoChain — records the credential on-chain
+})
+```
+
+### Sign a message
+
+```js
+const signature = await agent.sign(new TextEncoder().encode('hello'))
+```
+
+### Export and restore
+
+```js
+// Save to secure storage
+const exported = agent.export()
+
+// Restore in another process
+const restored = await KxcoAgentIdentity.import(exported)
+```
+
+### Send relay operations
+
+```js
+import { KxcoChain } from 'kxco-pq-chain'
+
+const chain = new KxcoChain({ relay: 'https://relay.kxco.ai', identity: sponsor })
+const client = agent.toChainClient('https://relay.kxco.ai')
+
+const result = await client.anchorAttestation({
+  payloadHash: '9f86d081884c7d65...',
+  purpose:     'trade-confirmation',
+})
+// → { txHash: '0x...', blockNumber: 228345 }
+
+await client.anchorAuditRoot({ rootHash: '...', entryCount: 100 })
+await client.transfer({ recipientKid: 'aa29f37ab7f4b2cf', amount: 1000 })
+```
+
+### Verify a credential
+
+```js
+const result = await KxcoAgentIdentity.verify(credential, {
+  sponsorPublicKey: sponsor.publicKey,  // optional — skip to check format only
+})
+// → { valid: true, agentKid: '...', sponsorKid: '...', scope: {...} }
+```
+
+### Revoke an agent
+
+```js
+await KxcoAgentIdentity.revoke(agent.credential.agentKid, {
+  chain,
+  reason: 'Decommissioned',
+})
+```
+
+---
+
+## Scope manifest
+
+The scope is signed by the institution and cannot be modified after issuance.
+
+```ts
+interface AgentScope {
+  payments?: {
+    maxPerTransaction: number   // in smallest denomination
+    maxPerDay:         number
+    allowedRecipients: string[] // EVM addresses (0x + 40 hex) or KXCO kids (16 hex)
+  }
+  attestations?: {
+    purposes: string[]          // allowed purpose strings
+  }
+  auditLog?:    boolean         // can anchor audit checkpoints
+  credentials?: boolean         // can manage credentials (use sparingly)
+}
+```
+
+The scope hash (SHA-256 of JCS-canonical scope JSON) is stored on-chain at issuance.
+
+---
+
+## Agent types
+
+| Type | Use |
+|------|-----|
+| `llm` | Large language models and AI assistants |
+| `robot` | Physical robots and automated machinery |
+| `iot` | IoT devices and sensors |
+| `process` | Automated software processes and daemons |
+
+---
+
+## Authors
+
+Shayne Heffernan and John Heffernan — KXCO by Knightsbridge
+
+hello@kxco.ai | https://kxco.ai

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "kxco-pq-agent",
+  "version": "1.0.0",
+  "description": "AI agent and robot identity for the KXCO post-quantum stack. Any KxcoIdentity holder may sponsor an agent with a locked ML-DSA-65 keypair and capability scope — payments, attestations, audit anchoring.",
+  "keywords": [
+    "post-quantum",
+    "pqc",
+    "ml-dsa",
+    "nist",
+    "fips-204",
+    "kxco",
+    "agent-identity",
+    "robot-identity",
+    "machine-identity",
+    "ai-agent",
+    "capability-scope",
+    "armature",
+    "relay",
+    "blockchain"
+  ],
+  "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": "git+https://github.com/JackKXCO/kxco-pq-agent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JackKXCO/kxco-pq-agent/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/agent.test.js"
+  },
+  "funding": "https://kxco.ai",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/agent-client.js

@@ -0,0 +1,147 @@
+import { KxcoPqAgentError } from './errors.js'
+import { canonicalize }     from './jcs.js'
+
+const enc = new TextEncoder()
+
+function randomNonce() {
+  const bytes = new Uint8Array(32)
+  globalThis.crypto.getRandomValues(bytes)
+  return Buffer.from(bytes).toString('hex')
+}
+
+async function sha256Hex(str) {
+  const buf = await globalThis.crypto.subtle.digest('SHA-256', enc.encode(str))
+  return Buffer.from(buf).toString('hex')
+}
+
+function buildSigningMessage(operation, agentKid, sponsorKid, nonce, timestamp, credentialHash, payload) {
+  return enc.encode([
+    'kxco-relay-agent-v1',
+    `operation: ${operation}`,
+    `agentKid: ${agentKid}`,
+    `sponsorKid: ${sponsorKid}`,
+    `nonce: ${nonce}`,
+    `timestamp: ${timestamp}`,
+    `credentialHash: ${credentialHash}`,
+    `payload: ${canonicalize(payload)}`,
+  ].join('\n'))
+}
+
+/**
+ * AgentChainClient — relay client for KxcoAgentIdentity.
+ *
+ * Sends ML-DSA-65 signed intents to the KXCO relay's /agent-intents endpoint.
+ * Each request includes the agent's signed credential so the relay can verify
+ * the sponsor's authorisation and enforce scope.
+ *
+ * Returned by KxcoAgentIdentity.toChainClient().
+ */
+export class AgentChainClient {
+  #relay
+  #agent
+  #timeout
+  #credentialB64
+  #credentialHash  // lazy, cached after first use
+
+  constructor({ relay, agent, timeout = 10_000 }) {
+    if (!relay) throw new KxcoPqAgentError('relay URL is required', { code: 'BAD_CONFIG' })
+    if (!agent) throw new KxcoPqAgentError('agent is required',     { code: 'BAD_CONFIG' })
+    this.#relay          = relay.replace(/\/$/, '')
+    this.#agent          = agent
+    this.#timeout        = timeout
+    this.#credentialB64  = Buffer.from(JSON.stringify(agent.credential)).toString('base64')
+    this.#credentialHash = null
+  }
+
+  async #getCredentialHash() {
+    if (!this.#credentialHash) {
+      this.#credentialHash = await sha256Hex(this.#credentialB64)
+    }
+    return this.#credentialHash
+  }
+
+  // ── Operations ───────────────────────────────────────────────────────────
+
+  /** Anchor an attestation envelope hash on-chain (requires scope.attestations.enabled). */
+  async anchorAttestation({ payloadHash, purpose }) {
+    return this.#send('anchorAttestation', { payloadHash, purpose })
+  }
+
+  /** Anchor an audit log checkpoint on-chain (requires scope.auditLog.enabled). */
+  async anchorAuditRoot({ rootHash, entryCount }) {
+    return this.#send('anchorAuditRoot', { rootHash, entryCount })
+  }
+
+  /**
+   * Submit a payment intent (requires scope.payments.enabled).
+   * The relay enforces allowedRecipients, maxPerTransaction, and maxPerDay.
+   * @param {object} opts
+   * @param {string} opts.to     — EVM address or KXCO kid of the recipient
+   * @param {number} opts.amount — amount in ARMR
+   */
+  async transfer({ to, amount }) {
+    return this.#send('transfer', { to, amount })
+  }
+
+  // ── Internal ─────────────────────────────────────────────────────────────
+
+  async #send(operation, payload) {
+    const nonce          = randomNonce()
+    const timestamp      = Math.floor(Date.now() / 1000)
+    const credentialHash = await this.#getCredentialHash()
+    const agentKid       = this.#agent.kid
+    const sponsorKid     = this.#agent.sponsorKid
+
+    const msg      = buildSigningMessage(operation, agentKid, sponsorKid, nonce, timestamp, credentialHash, payload)
+    const sigBytes = await this.#agent.sign(msg)
+    const signature = Buffer.from(sigBytes).toString('hex')
+
+    const intent = {
+      operation,
+      agentKid,
+      sponsorKid,
+      agentCredential: this.#credentialB64,
+      credentialHash,
+      nonce,
+      timestamp,
+      payload,
+      signature,
+    }
+
+    const ac  = new AbortController()
+    const tid = setTimeout(() => ac.abort(), this.#timeout)
+
+    let response
+    try {
+      response = await fetch(`${this.#relay}/agent-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 KxcoPqAgentError(`relay request timed out after ${this.#timeout}ms`, { code: 'TIMEOUT' })
+      }
+      throw new KxcoPqAgentError(`relay request failed: ${err.message}`, { code: 'NETWORK_ERROR' })
+    }
+    clearTimeout(tid)
+
+    let body
+    try {
+      body = await response.json()
+    } catch {
+      throw new KxcoPqAgentError('relay returned non-JSON response', { code: 'PARSE_ERROR', status: response.status })
+    }
+
+    if (!response.ok || body.ok === false) {
+      throw new KxcoPqAgentError(
+        body.error ?? `relay error ${response.status}`,
+        { code: body.code ?? 'RELAY_ERROR' }
+      )
+    }
+
+    return { txHash: body.txHash, blockNumber: body.blockNumber }
+  }
+}

package/src/agent-identity.js

@@ -0,0 +1,299 @@
+import { mlDsa, fingerprint } from 'kxco-post-quantum'
+import { validateScope, hashScope } from './scope.js'
+import { canonicalize }             from './jcs.js'
+import { KxcoPqAgentError }         from './errors.js'
+import { AgentChainClient }         from './agent-client.js'
+
+const CREDENTIAL_VERSION = '1'
+const IDENTITY_VERSION   = '1'
+
+const enc = new TextEncoder()
+
+function b64url(bytes) {
+  return Buffer.from(bytes).toString('base64url')
+}
+
+function fromB64url(s) {
+  return new Uint8Array(Buffer.from(s, 'base64url'))
+}
+
+function parseDuration(val) {
+  if (typeof val === 'number') return val * 1000
+  const m = String(val).match(/^(\d+)(d|h|m|s|y)$/)
+  if (!m) throw new KxcoPqAgentError(`invalid expiresIn '${val}' — use '30d', '1y', or seconds as a number`)
+  const n  = parseInt(m[1], 10)
+  const ms = { d: 86400000, h: 3600000, m: 60000, s: 1000, y: 31536000000 }
+  return n * ms[m[2]]
+}
+
+function credentialSigningMsg({ agentKid, agentPublicKey, sponsorKid, agentType, label, model, scope, issuedAt, expiresAt }) {
+  return enc.encode([
+    'kxco-agent-credential-v1',
+    agentKid,
+    agentPublicKey,
+    sponsorKid,
+    agentType,
+    label,
+    model ?? '',
+    canonicalize(scope),
+    issuedAt,
+    expiresAt,
+  ].join('\n'))
+}
+
+const VALID_AGENT_TYPES = new Set(['llm', 'robot', 'iot', 'process'])
+
+export class KxcoAgentIdentity {
+  #kid
+  #keypair
+  #sponsorKid
+  #agentType
+  #label
+  #model
+  #scope
+  #issuedAt
+  #expiresAt
+  #credential
+
+  constructor(opts) {
+    this.#kid        = opts.kid
+    this.#keypair    = opts.keypair
+    this.#sponsorKid = opts.sponsorKid
+    this.#agentType  = opts.agentType
+    this.#label      = opts.label
+    this.#model      = opts.model ?? null
+    this.#scope      = opts.scope
+    this.#issuedAt   = opts.issuedAt
+    this.#expiresAt  = opts.expiresAt
+    this.#credential = opts.credential
+  }
+
+  get kid()        { return this.#kid }
+  get sponsorKid() { return this.#sponsorKid }
+  get agentType()  { return this.#agentType }
+  get label()      { return this.#label }
+  get model()      { return this.#model }
+  get scope()      { return JSON.parse(JSON.stringify(this.#scope)) }
+  get issuedAt()   { return this.#issuedAt }
+  get expiresAt()  { return this.#expiresAt }
+  get credential() { return JSON.parse(JSON.stringify(this.#credential)) }
+
+  // ── Factory ───────────────────────────────────────────────────────────────
+
+  /**
+   * Create a new agent identity. Any KxcoIdentity holder may sponsor an agent.
+   *
+   * @param {object} opts
+   * @param {{ kid: string, sign(msg: Uint8Array): Promise<Uint8Array> }} opts.sponsor
+   * @param {string} opts.label       — human-readable name for this agent
+   * @param {'llm'|'robot'|'iot'|'process'} opts.agentType
+   * @param {string} [opts.model]     — model/hardware identifier (optional)
+   * @param {object} opts.scope       — locked capability manifest (see scope.js)
+   * @param {string|number} opts.expiresIn — '30d', '1y', or seconds as number (mandatory)
+   * @param {object} [opts.chain]     — KxcoChain instance for on-chain registration
+   */
+  static async create({ sponsor, label, agentType, model, scope, expiresIn, chain } = {}) {
+    if (!sponsor?.kid || typeof sponsor.sign !== 'function') {
+      throw new KxcoPqAgentError('create: sponsor must have .kid and .sign(message)')
+    }
+    if (!label)                       throw new KxcoPqAgentError('create: label is required')
+    if (!agentType)                   throw new KxcoPqAgentError('create: agentType is required')
+    if (!VALID_AGENT_TYPES.has(agentType)) {
+      throw new KxcoPqAgentError(`create: agentType must be one of: ${[...VALID_AGENT_TYPES].join(', ')}`)
+    }
+    if (!scope)                       throw new KxcoPqAgentError('create: scope is required')
+    if (expiresIn == null)            throw new KxcoPqAgentError('create: expiresIn is required — agents must have an expiry')
+
+    validateScope(scope)
+
+    const keypair      = mlDsa.ml_dsa65.keygen()
+    const agentKid     = fingerprint(keypair.publicKey)
+    const agentPubB64  = b64url(keypair.publicKey)
+    const issuedAt     = new Date().toISOString()
+    const expiresAt    = new Date(Date.now() + parseDuration(expiresIn)).toISOString()
+
+    const sigMsg = credentialSigningMsg({
+      agentKid,
+      agentPublicKey: agentPubB64,
+      sponsorKid:     sponsor.kid,
+      agentType,
+      label,
+      model,
+      scope,
+      issuedAt,
+      expiresAt,
+    })
+
+    const sigBytes   = await sponsor.sign(sigMsg)
+    const credential = {
+      'kxco-agent':     CREDENTIAL_VERSION,
+      agentKid,
+      agentPublicKey:   agentPubB64,
+      sponsorKid:       sponsor.kid,
+      agentType,
+      label,
+      ...(model && { model }),
+      scope,
+      issuedAt,
+      expiresAt,
+      sponsorSignature: b64url(sigBytes),
+    }
+
+    if (chain) {
+      const scopeHash    = await hashScope(scope)
+      const expiresAtSec = Math.floor(new Date(expiresAt).getTime() / 1000)
+      await chain.issueAgentCredential({
+        agentKid,
+        agentPublicKeyHex: Buffer.from(keypair.publicKey).toString('hex'),
+        agentType,
+        scopeHash,
+        expiresAt: expiresAtSec,
+      })
+    }
+
+    return new KxcoAgentIdentity({
+      kid:        agentKid,
+      keypair,
+      sponsorKid: sponsor.kid,
+      agentType,
+      label,
+      model:      model ?? null,
+      scope,
+      issuedAt,
+      expiresAt,
+      credential,
+    })
+  }
+
+  // ── Signing ───────────────────────────────────────────────────────────────
+
+  async sign(message) {
+    if (!this.#keypair?.secretKey) {
+      throw new KxcoPqAgentError('no signing key — reconstruct with KxcoAgentIdentity.import()')
+    }
+    return mlDsa.ml_dsa65.sign(
+      new Uint8Array(this.#keypair.secretKey),
+      new Uint8Array(message),
+    )
+  }
+
+  async getPublicKey() {
+    return this.#keypair.publicKey
+  }
+
+  // ── Export / import ───────────────────────────────────────────────────────
+
+  export() {
+    return {
+      'kxco-agent-identity': IDENTITY_VERSION,
+      kid:        this.#kid,
+      sponsorKid: this.#sponsorKid,
+      agentType:  this.#agentType,
+      label:      this.#label,
+      ...(this.#model && { model: this.#model }),
+      scope:      this.#scope,
+      issuedAt:   this.#issuedAt,
+      expiresAt:  this.#expiresAt,
+      secretKey:  b64url(this.#keypair.secretKey),
+      publicKey:  b64url(this.#keypair.publicKey),
+      credential: this.#credential,
+    }
+  }
+
+  static async import(exported) {
+    if (!exported || exported['kxco-agent-identity'] !== IDENTITY_VERSION) {
+      throw new KxcoPqAgentError('import: invalid or unsupported agent identity format')
+    }
+    return new KxcoAgentIdentity({
+      kid:        exported.kid,
+      keypair:    { secretKey: fromB64url(exported.secretKey), publicKey: fromB64url(exported.publicKey) },
+      sponsorKid: exported.sponsorKid,
+      agentType:  exported.agentType,
+      label:      exported.label,
+      model:      exported.model ?? null,
+      scope:      exported.scope,
+      issuedAt:   exported.issuedAt,
+      expiresAt:  exported.expiresAt,
+      credential: exported.credential,
+    })
+  }
+
+  // ── Chain client ──────────────────────────────────────────────────────────
+
+  /**
+   * Returns an AgentChainClient that sends agent-signed intents to the relay.
+   * Each request automatically includes this agent's credential and kid.
+   * @param {string} relay — relay base URL, e.g. 'https://relay.kxco.ai'
+   * @param {{ timeout?: number }} [opts]
+   */
+  toChainClient(relay, { timeout } = {}) {
+    return new AgentChainClient({ relay, agent: this, ...(timeout && { timeout }) })
+  }
+
+  // ── Static: verify a credential ──────────────────────────────────────────
+
+  /**
+   * Verify an agent credential envelope.
+   * Pass sponsorPublicKey (Uint8Array) to perform full ML-DSA-65 signature verification.
+   * Without it, only expiry and format are checked.
+   *
+   * @param {object} credential
+   * @param {{ sponsorPublicKey?: Uint8Array }} [opts]
+   */
+  static async verify(credential, { sponsorPublicKey } = {}) {
+    if (!credential || credential['kxco-agent'] !== CREDENTIAL_VERSION) {
+      return { valid: false, error: 'invalid or unsupported credential format' }
+    }
+
+    const {
+      agentKid, agentPublicKey, sponsorKid, agentType,
+      label, model, scope, issuedAt, expiresAt, sponsorSignature,
+    } = credential
+
+    if (!agentKid || !agentPublicKey || !sponsorKid || !agentType || !issuedAt || !expiresAt || !sponsorSignature) {
+      return { valid: false, error: 'malformed credential — missing required fields' }
+    }
+
+    if (new Date(expiresAt) < new Date()) {
+      return { valid: false, error: 'agent credential has expired' }
+    }
+
+    if (sponsorPublicKey) {
+      const msg = credentialSigningMsg({ agentKid, agentPublicKey, sponsorKid, agentType, label, model, scope, issuedAt, expiresAt })
+      let ok
+      try {
+        ok = mlDsa.ml_dsa65.verify(new Uint8Array(sponsorPublicKey), msg, fromB64url(sponsorSignature))
+      } catch {
+        ok = false
+      }
+      if (!ok) return { valid: false, error: 'sponsor signature invalid' }
+    }
+
+    return {
+      valid: true,
+      agentKid,
+      sponsorKid,
+      agentType,
+      label,
+      ...(model && { model }),
+      scope,
+      issuedAt,
+      expiresAt,
+    }
+  }
+
+  // ── Static: revoke on-chain ───────────────────────────────────────────────
+
+  /**
+   * Revoke an agent credential on-chain.
+   * The chain parameter must be a KxcoChain instance belonging to the sponsor.
+   *
+   * @param {string} agentKid
+   * @param {{ chain: object, reason?: string }} opts
+   */
+  static async revoke(agentKid, { chain, reason = '' } = {}) {
+    if (!agentKid) throw new KxcoPqAgentError('revoke: agentKid is required')
+    if (!chain)    throw new KxcoPqAgentError('revoke: chain is required for on-chain revocation')
+    await chain.revokeAgentCredential({ agentKid, reason })
+  }
+}

package/src/errors.js

@@ -0,0 +1,7 @@
+export class KxcoPqAgentError extends Error {
+  constructor(message, { code } = {}) {
+    super(message)
+    this.name = 'KxcoPqAgentError'
+    this.code = code ?? 'AGENT_ERROR'
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,146 @@
+// kxco-pq-agent — AI agent and robot identity for the KXCO PQ stack
+
+// ── Error ────────────────────────────────────────────────────────────────────
+
+export class KxcoPqAgentError extends Error {
+  name: 'KxcoPqAgentError'
+  code: string
+}
+
+// ── Scope ────────────────────────────────────────────────────────────────────
+
+export interface PaymentScope {
+  enabled:             boolean
+  maxPerTransaction?:  number   // ARMR; must be ≤ maxPerDay
+  maxPerDay?:          number   // ARMR
+  /**
+   * Allowed recipients — EVM addresses (0x + 40 hex) or KXCO kids (16 lowercase hex).
+   * Empty array = locked to that empty whitelist (no payments allowed).
+   * Absent / undefined = any recipient.
+   */
+  allowedRecipients?:  string[]
+  currency?:           string   // e.g. 'ARMR'
+}
+
+export interface AttestationScope {
+  enabled:   boolean
+  /** Allowed purposes. Empty array = any purpose. */
+  purposes?: string[]
+}
+
+export interface AgentScope {
+  payments?:     PaymentScope
+  attestations?: AttestationScope
+  auditLog?:     { enabled: boolean }
+  credentials?:  { enabled: boolean }
+}
+
+export function validateScope(scope: AgentScope): AgentScope
+export function hashScope(scope: AgentScope): Promise<string>
+
+// ── Credential envelope ───────────────────────────────────────────────────────
+
+export interface AgentCredential {
+  'kxco-agent':     string
+  agentKid:         string
+  agentPublicKey:   string   // base64url ML-DSA-65 public key
+  sponsorKid:       string
+  agentType:        'llm' | 'robot' | 'iot' | 'process'
+  label:            string
+  model?:           string
+  scope:            AgentScope
+  issuedAt:         string   // ISO 8601
+  expiresAt:        string   // ISO 8601
+  sponsorSignature: string   // base64url ML-DSA-65 sig by sponsor
+}
+
+export interface VerifyResult {
+  valid:      boolean
+  error?:     string
+  agentKid?:  string
+  sponsorKid?: string
+  agentType?:  string
+  label?:      string
+  model?:      string
+  scope?:      AgentScope
+  issuedAt?:   string
+  expiresAt?:  string
+}
+
+// ── AgentChainClient ──────────────────────────────────────────────────────────
+
+export interface AgentRelayResult {
+  txHash:      string
+  blockNumber: number
+}
+
+export class AgentChainClient {
+  constructor(opts: { relay: string; agent: KxcoAgentIdentity; timeout?: number })
+  anchorAttestation(opts: { payloadHash: string; purpose: string }): Promise<AgentRelayResult>
+  anchorAuditRoot(opts: { rootHash: string; entryCount: number }):   Promise<AgentRelayResult>
+  transfer(opts: { to: string; amount: number }):                    Promise<AgentRelayResult>
+}
+
+// ── KxcoAgentIdentity ─────────────────────────────────────────────────────────
+
+export interface Sponsor {
+  kid:  string
+  sign(message: Uint8Array): Promise<Uint8Array>
+}
+
+export interface CreateAgentOptions {
+  sponsor:    Sponsor
+  label:      string
+  agentType:  'llm' | 'robot' | 'iot' | 'process'
+  model?:     string
+  scope:      AgentScope
+  /** Mandatory. '7d', '30d', '1y', or seconds as number. */
+  expiresIn:  string | number
+  /** KxcoChain instance (from kxco-pq-chain) for on-chain registration. */
+  chain?:     { issueAgentCredential(opts: object): Promise<AgentRelayResult> }
+}
+
+export interface ExportedAgentIdentity {
+  'kxco-agent-identity': string
+  kid:        string
+  sponsorKid: string
+  agentType:  string
+  label:      string
+  model?:     string
+  scope:      AgentScope
+  issuedAt:   string
+  expiresAt:  string
+  secretKey:  string
+  publicKey:  string
+  credential: AgentCredential
+}
+
+export class KxcoAgentIdentity {
+  readonly kid:        string
+  readonly sponsorKid: string
+  readonly agentType:  string
+  readonly label:      string
+  readonly model:      string | null
+  readonly scope:      AgentScope
+  readonly issuedAt:   string
+  readonly expiresAt:  string
+  readonly credential: AgentCredential
+
+  static create(opts: CreateAgentOptions): Promise<KxcoAgentIdentity>
+  static import(exported: ExportedAgentIdentity): Promise<KxcoAgentIdentity>
+
+  static verify(
+    credential: AgentCredential,
+    opts?: { sponsorPublicKey?: Uint8Array }
+  ): Promise<VerifyResult>
+
+  static revoke(
+    agentKid: string,
+    opts: { chain: { revokeAgentCredential(opts: object): Promise<AgentRelayResult> }; reason?: string }
+  ): Promise<void>
+
+  sign(message: Uint8Array): Promise<Uint8Array>
+  getPublicKey(): Promise<Uint8Array>
+  export(): ExportedAgentIdentity
+  toChainClient(relay: string, opts?: { timeout?: number }): AgentChainClient
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export { KxcoAgentIdentity } from './agent-identity.js'
+export { AgentChainClient } from './agent-client.js'
+export { KxcoPqAgentError } from './errors.js'
+export { validateScope, hashScope } from './scope.js'

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}`)
+}

package/src/scope.js

@@ -0,0 +1,94 @@
+import { KxcoPqAgentError } from './errors.js'
+import { canonicalize }     from './jcs.js'
+
+const EVM_RE = /^0x[0-9a-fA-F]{40}$/
+const KID_RE = /^[0-9a-f]{16}$/
+
+function validRecipient(s) {
+  return EVM_RE.test(s) || KID_RE.test(s)
+}
+
+/**
+ * Validate a scope object. Throws KxcoPqAgentError on any violation.
+ * Returns the scope unchanged.
+ */
+export function validateScope(scope) {
+  if (!scope || typeof scope !== 'object' || Array.isArray(scope)) {
+    throw new KxcoPqAgentError('scope must be a plain object')
+  }
+
+  const { payments, attestations, auditLog, credentials } = scope
+
+  if (payments != null) {
+    if (typeof payments !== 'object' || Array.isArray(payments)) {
+      throw new KxcoPqAgentError('scope.payments must be an object')
+    }
+    if (payments.enabled !== false) {
+      const { maxPerTransaction: mpt, maxPerDay: mpd, allowedRecipients: ar } = payments
+
+      if (mpt !== undefined) {
+        if (typeof mpt !== 'number' || mpt <= 0) {
+          throw new KxcoPqAgentError('scope.payments.maxPerTransaction must be a positive number')
+        }
+      }
+      if (mpd !== undefined) {
+        if (typeof mpd !== 'number' || mpd <= 0) {
+          throw new KxcoPqAgentError('scope.payments.maxPerDay must be a positive number')
+        }
+      }
+      if (mpt !== undefined && mpd !== undefined && mpt > mpd) {
+        throw new KxcoPqAgentError('scope.payments.maxPerTransaction must not exceed maxPerDay')
+      }
+      if (ar !== undefined) {
+        if (!Array.isArray(ar)) {
+          throw new KxcoPqAgentError('scope.payments.allowedRecipients must be an array')
+        }
+        for (const r of ar) {
+          if (!validRecipient(r)) {
+            throw new KxcoPqAgentError(
+              `invalid recipient '${r}' — must be an EVM address (0x + 40 hex) or KXCO kid (16 lowercase hex chars)`
+            )
+          }
+        }
+      }
+    }
+  }
+
+  if (attestations != null) {
+    if (typeof attestations !== 'object' || Array.isArray(attestations)) {
+      throw new KxcoPqAgentError('scope.attestations must be an object')
+    }
+    if (attestations.enabled !== false && attestations.purposes !== undefined) {
+      if (!Array.isArray(attestations.purposes)) {
+        throw new KxcoPqAgentError('scope.attestations.purposes must be an array of strings')
+      }
+      for (const p of attestations.purposes) {
+        if (typeof p !== 'string' || !p.trim()) {
+          throw new KxcoPqAgentError('each entry in scope.attestations.purposes must be a non-empty string')
+        }
+      }
+    }
+  }
+
+  if (auditLog != null && (typeof auditLog !== 'object' || Array.isArray(auditLog))) {
+    throw new KxcoPqAgentError('scope.auditLog must be an object')
+  }
+
+  if (credentials != null && (typeof credentials !== 'object' || Array.isArray(credentials))) {
+    throw new KxcoPqAgentError('scope.credentials must be an object')
+  }
+
+  return scope
+}
+
+/**
+ * Compute a hex SHA-256 of the JCS-canonical scope.
+ * This hash is stored on-chain so the relay can verify scope integrity.
+ * @param {object} scope
+ * @returns {Promise<string>} 64-char hex string
+ */
+export async function hashScope(scope) {
+  const bytes = new TextEncoder().encode(canonicalize(scope))
+  const buf   = await globalThis.crypto.subtle.digest('SHA-256', bytes)
+  return Buffer.from(buf).toString('hex')
+}