kxco-pq-agent 1.0.7 → 1.1.0

package/ASSESSMENT.md

@@ -0,0 +1,117 @@
+# Assessment notes
+
+The answers a buyer's readiness assessment asks for: what this package does,
+how it moves when algorithms move, and what it takes to run it.
+
+Algorithm conformance belongs to
+[`kxco-post-quantum`](https://www.npmjs.com/package/kxco-post-quantum), which
+runs 2,103 NIST ACVP vectors and a cross-implementation interoperability matrix
+and publishes the lot. Cited here, proven there.
+
+## What this package is
+
+Identity for a non-human actor. A KYC-verified institution sponsors an ML-DSA-65
+keypair for an agent and binds a capability scope to it at issuance.
+
+The question a supervisor asks about an autonomous system is not "was it
+encrypted" but "who authorised this, and what were they allowed to do". This
+package is built to answer exactly that, and three properties hold:
+
+**An agent cannot widen its own authority.** The scope is signed by the sponsor
+at issuance and hashed on chain, so it cannot be edited afterwards. Widening
+requires revoke and re-issue by the sponsor. Compromising the agent does not
+enlarge what the agent may do, which is the property that makes an autonomous
+key safe to deploy at all.
+
+**An agent cannot mint another agent.** Only a KYC-verified sponsor issues an
+identity. There is no path from one compromised agent to a population of them.
+
+**Every agent traces to a named legal entity.** No anonymous mode, no
+self-signed mode. When a regulator asks who authorised an action, the answer is
+an institution that completed KYC, not a key of unknown provenance.
+
+**Enforcement runs at both ends.** The relay checks scope behind the agent,
+where a compromised agent cannot reach it, and `checkScope()` checks the same
+signed scope in front:
+
+```js
+const decision = checkScope(agent.scope, {
+  type: 'payment', amount: 4500, spentToday: 12000, recipient: '0xAbC…',
+})
+// { allowed: false, reason: 'amount 4500 would take today's total to 16500,
+//    past maxPerDay 15000', checked: ['payments.enabled', …] }
+```
+
+It refuses offline, so an agent that cannot reach the relay still knows what it
+may not do. It refuses without spending a round trip. And it names the limit that
+stopped it, which a remote refusal cannot do as precisely. It fails closed
+throughout: a capability the scope does not grant is denied, an action type it
+does not recognise is denied, and a configured limit that cannot be judged from
+the inputs given is denied rather than skipped. `checked` reports every limit
+the decision actually evaluated, so a caller can see the control was applied
+rather than assume it.
+
+**Expiry is mandatory.** `expiresIn` is required at creation. An agent identity
+cannot be issued without an end date, which is the default that stops a
+short-lived task leaving a long-lived key behind.
+
+## Scope
+
+The relay's enforcement is the one that binds, because it sits where the agent
+cannot influence it, and `checkScope()` is defence in depth in front of it.
+Assess both: the local check for fast, offline, precise refusal, and the relay
+for the guarantee.
+
+The sponsor's KYC is an operational control at KXCO rather than a protocol one,
+and it is the thing that makes attribution to a legal entity meaningful.
+
+Actions land where they land: on Armature L1 through
+[`kxco-pq-chain`](https://www.npmjs.com/package/kxco-pq-chain), or in whatever
+record the sponsor keeps, for which
+[`kxco-pq-audit`](https://www.npmjs.com/package/kxco-pq-audit) is the
+append-only option.
+
+## Agility
+
+**Inherited.** Signing primitives belong to `kxco-post-quantum`.
+
+**Coordinated by design.** An agent identity is registered on chain and its
+scope is checked by the relay, so a parameter-set change moves through the chain
+and the relay before it reaches the client. That ordering is correct: an
+identity nobody can verify is worse than one that waits, and it is why the
+migration story for this package is the chain's rather than its own.
+
+**The scope manifest is a signed data structure** with named capability
+sections, so adding a capability class is a change the sponsor signs and the
+enforcer recognises, agreed between the two rather than assumed by either.
+
+## Running it
+
+**Release integrity.** Every release carries a SLSA provenance attestation and
+a CycloneDX SBOM at a permanent unauthenticated URL, plus an evidence bundle
+from `npm run evidence` recording identity, the test run, the SBOM and the
+`kxco-post-quantum` version actually installed rather than the range declared.
+
+**Supported versions.** One line moving forward. Fixes land in the next release.
+
+**Cost.** No hardware or runtime ceiling. Signing is one ML-DSA-65 operation per
+action; the practical limits are the scope caps themselves, which are policy
+rather than performance.
+
+**Connection.** `relay.kxco.ai`, which negotiates the hybrid key exchange group
+`X25519MLKEM768` under TLS 1.3. Measured 7 September 2026 with OpenSSL 3.5.6,
+and reproducible:
+
+```
+echo | openssl s_client -connect relay.kxco.ai:443 -servername relay.kxco.ai \
+  -groups X25519MLKEM768 -tls1_3 2>&1 | grep "Negotiated TLS1.3 group"
+```
+
+The intent is signed with ML-DSA-65 before it is sent and verified on chain
+after it arrives, so the transport carries the intent rather than securing it.
+
+## Correcting this document
+
+Every claim here is checkable against `src/` and the README. The TLS measurement
+is reproducible with the command given. If one does not match, that is a defect
+worth reporting through the repository's issues.

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## 1.1.0
+
+**`checkScope()` enforces the scope locally, before the relay sees the action.**
+
+```js
+import { checkScope } from 'kxco-pq-agent'
+
+const decision = checkScope(agent.scope, {
+  type: 'payment', amount: 4500, spentToday: 12000, recipient: '0xAbC…',
+})
+// { allowed: false,
+//   reason: "amount 4500 would take today's total to 16500, past maxPerDay 15000",
+//   checked: ['payments.enabled', 'payments.maxPerTransaction', 'payments.maxPerDay'] }
+```
+
+The relay's enforcement is unchanged and is still the one that binds, because it
+sits behind the agent where a compromised agent cannot reach it. This runs in
+front, on the same signed scope, and earns its place three ways: it refuses
+offline, so an agent that cannot reach the relay still knows what it may not do;
+it refuses without spending a round trip; and it names the limit that stopped
+it, which a remote refusal cannot do as precisely.
+
+**Fails closed throughout.** A capability the scope does not grant is denied. An
+action type it does not recognise is denied. A configured limit that cannot be
+judged from the inputs given is denied rather than skipped — pass a scope with
+`maxPerDay` set and no `spentToday`, and the answer is a refusal that says which
+input is missing, not a pass that quietly skipped a control.
+
+`checked` reports every limit the decision actually evaluated, in the order
+applied, so a caller can show the control ran rather than assert it did.
+
+Covers payments (`maxPerTransaction`, `maxPerDay`, `allowedRecipients`, with EVM
+recipients matched case-insensitively), attestation purposes, `auditLog` and
+`credentials`. Eleven tests.
+
+**ASSESSMENT.md rewritten** to lead with the containment properties — an agent
+cannot widen its own authority, cannot mint another agent, and always traces to
+a KYC-verified institution — and to record that enforcement now runs at both
+ends.

package/README.md

@@ -4,6 +4,33 @@ Post-quantum identity for AI agents and autonomous systems.
 
 ---
 
+## Release integrity
+
+Every release of this package is checkable without asking us for anything.
+
+- **Provenance.** Each release carries a SLSA provenance attestation tying the
+  published tarball to the commit and workflow that built it. Verify with
+  `npm audit signatures`, or read it directly from
+  `registry.npmjs.org/-/npm/v1/attestations/kxco-pq-agent@<version>`.
+- **Bill of materials.** A CycloneDX SBOM is published as a GitHub Release asset
+  at `releases/download/v<version>/sbom.cyclonedx.json`, a permanent
+  unauthenticated URL. Not an expiring build artifact.
+- **Pinned where it matters.** Third-party dependencies are pinned to exact
+  versions, never ranges, so the code that performs the cryptography cannot
+  change without a release. Sibling `kxco-*` packages sit on caret ranges
+  deliberately: it means a correctness fix in the base package reaches you
+  without a release of every package above it. That is not theoretical. When
+  `@noble/post-quantum` 0.7.1 was found to fail NIST SLH-DSA verification
+  vectors, the revert in the base package propagated here on the next install.
+  Every GitHub Action is pinned by 40-character commit SHA.
+- **Conformance underneath.** The cryptography comes from
+  [`kxco-post-quantum`](https://www.npmjs.com/package/kxco-post-quantum), which
+  is run against **2,103 NIST ACVP vectors: 1,793 passed, 0 failed, 310 skipped** and a **225-check
+  cross-implementation interoperability matrix** against liboqs, Bouncy Castle
+  and two pure-Python implementations, in both directions and with negative
+  controls. Its published tarball also rebuilds bit-for-bit from its own tag,
+  verified in CI on every run.
+
 ## The problem it solves
 
 AI systems cannot pass KYC. An LLM, robot, IoT device, or daemon has no legal standing to authenticate itself to a regulated network. This package solves that with a delegation model: a KYC-verified institution sponsors the agent by signing its ML-DSA-65 public key alongside a locked capability scope. The agent then signs its own relay operations independently, presenting the sponsor's credential as proof of authority. The KXCO relay validates both signatures before accepting any intent — the institution's approval is cryptographically bound to every action the agent takes.
@@ -149,6 +176,41 @@ Anchors an audit log checkpoint on-chain. Requires `scope.auditLog: true`.
 
 Submits a payment intent. `to` is an EVM address or KXCO kid. `amount` is in ARMR. The relay enforces `allowedRecipients`, `maxPerTransaction`, and `maxPerDay` from the scope.
 
+### `checkScope(scope, action)`
+
+Decide whether a scope permits an action, before attempting it.
+
+```js
+import { checkScope } from 'kxco-pq-agent'
+
+checkScope(agent.scope, {
+  type: 'payment', amount: 4500, spentToday: 12000, recipient: '0xAbC…',
+})
+// { allowed: false,
+//   reason: "amount 4500 would take today's total to 16500, past maxPerDay 15000",
+//   checked: ['payments.enabled', 'payments.maxPerTransaction', 'payments.maxPerDay'] }
+```
+
+The relay enforces the same signed scope behind the agent, and that enforcement
+is the one that binds. This runs in front of it: it refuses offline, refuses
+without spending a round trip, and names the limit that stopped it.
+
+| Action | Fields | Checked against |
+|---|---|---|
+| `payment` | `amount`, `recipient`, `spentToday` | `maxPerTransaction`, `maxPerDay`, `allowedRecipients` |
+| `attestation` | `purpose` | `attestations.purposes` |
+| `auditLog` | — | `auditLog` |
+| `credentials` | — | `credentials` |
+
+Returns `{ allowed, reason?, checked }`. `checked` lists every limit the
+decision actually evaluated, so a caller can show the control ran.
+
+It fails closed: a capability the scope does not grant is denied, an action type
+it does not recognise is denied, and a configured limit that cannot be judged
+from the inputs given is denied rather than skipped. Set `maxPerDay` and omit
+`spentToday` and the answer is a refusal naming the missing input, never a pass
+that skipped the cap.
+
 ---
 
 ## Agent types
@@ -162,11 +224,23 @@ Submits a payment intent. `to` is an EVM address or KXCO kid. `amount` is in ARM
 
 ---
 
-## What this does NOT do
+## The containment model
+
+Three properties hold for every agent identity, and they are the reason to use
+this rather than handing an agent a key.
+
+**An agent can never widen its own authority.** The capability scope is fixed
+at issuance and enforced relay-side, so an out-of-scope operation is refused
+before it reaches the chain. Compromising the agent does not enlarge what the
+agent may do.
+
+**An agent can never mint another agent.** Only a KYC-verified sponsor issues
+an identity, so there is no path from one compromised agent to a population of
+them.
 
-- Agents cannot issue credentials to other agents. Only a KYC-verified sponsor can create an agent identity.
-- Agents cannot exceed the scope declared at issuance. The relay enforces scope server-side; attempting an out-of-scope operation returns an error.
-- Agents cannot operate without a sponsor. There is no anonymous or self-signed credential mode.
+**Every agent traces to a named, KYC-verified institution.** There is no
+anonymous or self-signed mode, which is what makes an agent's action
+attributable to a legal entity when a supervisor asks who authorised it.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxco-pq-agent",
-  "version": "1.0.7",
+  "version": "1.1.0",
   "description": "Post-quantum identity for AI agents and autonomous systems: a KYC-verified institution sponsors an ML-DSA-65 keypair and locked capability scope for any agent that cannot pass KYC itself.",
   "keywords": [
     "post-quantum",
@@ -47,8 +47,10 @@
     }
   },
   "files": [
+    "CHANGELOG.md",
     "src",
-    "LICENSE"
+    "LICENSE",
+    "ASSESSMENT.md"
   ],
   "engines": {
     "node": ">=20.19"
@@ -57,7 +59,8 @@
     "kxco-post-quantum": "^1.3.0"
   },
   "scripts": {
-    "test": "node --test --test-timeout=30000 test/agent.test.js"
+    "test": "node --test --test-timeout=30000 test/agent.test.js",
+    "evidence": "node scripts/build-evidence.mjs"
   },
   "funding": "https://kxco.ai",
   "publishConfig": {

package/src/index.d.ts

@@ -38,6 +38,30 @@ export interface AgentScope {
 export function validateScope(scope: AgentScope): AgentScope
 export function hashScope(scope: AgentScope): Promise<string>
 
+export type ScopeAction =
+  | { type: 'payment'; amount: number; recipient?: string; spentToday?: number }
+  | { type: 'attestation'; purpose?: string }
+  | { type: 'auditLog' }
+  | { type: 'credentials' }
+
+export interface ScopeDecision {
+  allowed: boolean
+  /** Why the action was refused. Absent when allowed. */
+  reason?: string
+  /** Every limit the decision actually evaluated, in the order applied. */
+  checked: string[]
+}
+
+/**
+ * Decide whether a scope permits an action, before it is attempted.
+ *
+ * Runs in front of the relay's own enforcement, on the same signed scope: it
+ * refuses offline, refuses without spending a round trip, and names the limit
+ * that stopped it. Fails closed on an ungranted capability, an unknown action
+ * type, and a configured limit that cannot be evaluated from the inputs given.
+ */
+export function checkScope(scope: AgentScope, action: ScopeAction): ScopeDecision
+
 // ── Credential envelope ───────────────────────────────────────────────────────
 
 export interface AgentCredential {

package/src/index.js

@@ -1,4 +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'
+export { validateScope, checkScope, hashScope } from './scope.js'

package/src/scope.js

@@ -81,6 +81,127 @@ export function validateScope(scope) {
   return scope
 }
 
+/**
+ * Decide whether a scope permits an action, before it is attempted.
+ *
+ * The relay enforces scope too, and that enforcement is the one that binds: it
+ * sits behind the agent, so a compromised agent cannot talk its way past it.
+ * This check runs in front, on the same signed scope, and it earns its place
+ * three ways. It refuses offline, so an agent that cannot reach the relay still
+ * knows what it may not do. It refuses immediately, without spending a network
+ * round trip to be told no. And it names the limit that stopped it, which a
+ * remote refusal cannot do as precisely.
+ *
+ * Fails closed throughout. A capability the scope does not grant is denied, an
+ * action type it does not recognise is denied, and a configured limit that
+ * cannot be evaluated from the inputs given is denied rather than skipped.
+ *
+ * @param {object} scope — the signed capability manifest
+ * @param {object} action
+ * @param {'payment'|'attestation'|'auditLog'|'credentials'} action.type
+ * @param {number}  [action.amount]      — payment only, ARMR
+ * @param {string}  [action.recipient]   — payment only, EVM address or kid
+ * @param {number}  [action.spentToday]  — payment only, required when
+ *   `payments.maxPerDay` is set, because a day cap cannot be judged from one
+ *   transaction
+ * @param {string}  [action.purpose]     — attestation only
+ * @returns {{ allowed: boolean, reason?: string, checked: string[] }}
+ */
+export function checkScope(scope, action) {
+  if (!scope || typeof scope !== 'object' || Array.isArray(scope)) {
+    throw new KxcoPqAgentError('checkScope: scope must be a plain object')
+  }
+  if (!action || typeof action !== 'object' || Array.isArray(action)) {
+    throw new KxcoPqAgentError('checkScope: action must be a plain object')
+  }
+
+  const checked = []
+  const deny  = (reason) => ({ allowed: false, reason, checked })
+  const allow = ()       => ({ allowed: true, checked })
+
+  const granted = (section) =>
+    section != null && section !== false && section.enabled !== false
+
+  switch (action.type) {
+    case 'payment': {
+      const p = scope.payments
+      checked.push('payments.enabled')
+      if (!granted(p)) return deny('scope does not grant payments')
+
+      if (typeof action.amount !== 'number' || !(action.amount > 0)) {
+        return deny('payment amount must be a positive number')
+      }
+
+      if (p.maxPerTransaction !== undefined) {
+        checked.push('payments.maxPerTransaction')
+        if (action.amount > p.maxPerTransaction) {
+          return deny(
+            `amount ${action.amount} exceeds maxPerTransaction ${p.maxPerTransaction}`,
+          )
+        }
+      }
+
+      if (p.maxPerDay !== undefined) {
+        checked.push('payments.maxPerDay')
+        if (typeof action.spentToday !== 'number' || action.spentToday < 0) {
+          return deny(
+            'payments.maxPerDay is set, so spentToday is required to evaluate it',
+          )
+        }
+        if (action.spentToday + action.amount > p.maxPerDay) {
+          return deny(
+            `amount ${action.amount} would take today's total to ` +
+            `${action.spentToday + action.amount}, past maxPerDay ${p.maxPerDay}`,
+          )
+        }
+      }
+
+      if (p.allowedRecipients !== undefined) {
+        checked.push('payments.allowedRecipients')
+        if (typeof action.recipient !== 'string') {
+          return deny('payments.allowedRecipients is set, so a recipient is required')
+        }
+        // EVM addresses are case-insensitive; kids are lowercase hex.
+        const want = action.recipient.toLowerCase()
+        const ok = p.allowedRecipients.some((r) => r.toLowerCase() === want)
+        if (!ok) return deny(`recipient ${action.recipient} is not in allowedRecipients`)
+      }
+
+      return allow()
+    }
+
+    case 'attestation': {
+      const a = scope.attestations
+      checked.push('attestations.enabled')
+      if (!granted(a)) return deny('scope does not grant attestations')
+
+      if (a.purposes !== undefined) {
+        checked.push('attestations.purposes')
+        if (typeof action.purpose !== 'string') {
+          return deny('attestations.purposes is set, so a purpose is required')
+        }
+        if (!a.purposes.includes(action.purpose)) {
+          return deny(`purpose '${action.purpose}' is not in attestations.purposes`)
+        }
+      }
+      return allow()
+    }
+
+    case 'auditLog':
+      checked.push('auditLog')
+      return granted(scope.auditLog) ? allow() : deny('scope does not grant auditLog')
+
+    case 'credentials':
+      checked.push('credentials')
+      return granted(scope.credentials)
+        ? allow()
+        : deny('scope does not grant credentials')
+
+    default:
+      return deny(`unknown action type '${action.type}'`)
+  }
+}
+
 /**
  * Compute a hex SHA-256 of the JCS-canonical scope.
  * This hash is stored on-chain so the relay can verify scope integrity.