kxco-pq-agent 1.0.2 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +119 -87
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,21 +1,18 @@
1
1
  # kxco-pq-agent
2
2
 
3
- Post-quantum AI agent and robot identity for the KXCO platform.
3
+ Post-quantum identity for AI agents and autonomous systems.
4
4
 
5
- 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.
5
+ ---
6
6
 
7
- **Not open source.** This package is part of the KXCO Chain platform. Contact hello@kxco.ai for licensing.
7
+ ## The problem it solves
8
8
 
9
- ---
9
+ 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.
10
10
 
11
- ## How it works
11
+ ---
12
12
 
13
- 1. A KYC'd institution generates an ML-DSA-65 keypair for the agent
14
- 2. The institution signs a credential binding the agent's public key to a capability scope
15
- 3. The agent presents this credential with every relay request, signed with its own private key
16
- 4. The KXCO relay validates both the credential (institution's signature) and the intent (agent's signature) before submitting to chain
13
+ ## When to use this
17
14
 
18
- The credential scope is locked at issuance. To change an agent's permissions, revoke and re-issue.
15
+ Use this package when deploying LLMs, robots, IoT devices, or daemons that need to perform on-chain operations — payments, attestation anchoring, audit checkpointing — with verifiable, auditable scope controlled by a licensed institution.
19
16
 
20
17
  ---
21
18
 
@@ -27,113 +24,130 @@ npm install kxco-pq-agent
27
24
 
28
25
  ---
29
26
 
30
- ## Usage
31
-
32
- ### Issue an agent credential
27
+ ## Quick start
33
28
 
34
29
  ```js
35
30
  import { KxcoAgentIdentity } from 'kxco-pq-agent'
36
31
 
37
- // `sponsor` is a KxcoIdentity from kxco-pq-sdk
32
+ // sponsor is a KxcoIdentity from kxco-pq-sdk
33
+ // it must have .kid (string) and .sign(Uint8Array) -> Promise<Uint8Array>
34
+
38
35
  const agent = await KxcoAgentIdentity.create({
39
36
  sponsor,
40
- label: 'Trading Bot v2',
37
+ label: 'Settlement Bot',
41
38
  agentType: 'llm',
42
- model: 'claude-opus-4-7', // optional — model/firmware/version string
43
39
  scope: {
44
- payments: {
45
- maxPerTransaction: 5000, // ARMR, in smallest denomination
46
- maxPerDay: 50000,
47
- allowedRecipients: [
48
- '0xAbC123...', // EVM address
49
- 'aa29f37ab7f4b2cf', // KXCO kid
50
- ],
51
- },
52
- attestations: {
53
- purposes: ['trade-confirmation', 'settlement-receipt'],
54
- },
55
- auditLog: true,
56
- credentials: false,
40
+ attestations: { purposes: ['trade-confirmation'] },
41
+ auditLog: true,
57
42
  },
58
- expiresIn: '90d', // '30d', '1y', or seconds as a number
59
- chain, // optional KxcoChain — records the credential on-chain
43
+ expiresIn: '90d',
44
+ })
45
+
46
+ // Connect to the relay and anchor an attestation
47
+ const client = agent.toChainClient('https://relay.kxco.ai')
48
+
49
+ const result = await client.anchorAttestation({
50
+ payloadHash: '9f86d081884c7d65...',
51
+ purpose: 'trade-confirmation',
60
52
  })
53
+ // { txHash: '0x...', blockNumber: 228345 }
61
54
  ```
62
55
 
63
- ### Sign a message
56
+ ---
57
+
58
+ ## Scope manifest
59
+
60
+ The scope is signed by the sponsor at issuance and cannot be changed. To update an agent's permissions, revoke and re-issue.
64
61
 
65
62
  ```js
66
- const signature = await agent.sign(new TextEncoder().encode('hello'))
63
+ scope: {
64
+ payments: {
65
+ maxPerTransaction: 5000, // maximum ARMR per transfer (positive number)
66
+ maxPerDay: 50000, // rolling daily cap across all transfers
67
+ allowedRecipients: [ // EVM address (0x + 40 hex) or KXCO kid (16 hex chars)
68
+ '0xAbCdEf...',
69
+ 'aa29f37ab7f4b2cf',
70
+ ],
71
+ },
72
+ attestations: {
73
+ purposes: ['trade-confirmation', 'settlement-receipt'], // allowed purpose strings
74
+ },
75
+ auditLog: true, // permits anchorAuditRoot calls
76
+ credentials: false, // permits credential management (use sparingly)
77
+ }
67
78
  ```
68
79
 
69
- ### Export and restore
80
+ All fields are optional. Omit a section entirely to deny that capability. The scope hash (SHA-256 of the JCS-canonical scope JSON) is stored on-chain at issuance so the relay can verify integrity.
70
81
 
71
- ```js
72
- // Save to secure storage
73
- const exported = agent.export()
82
+ ---
74
83
 
75
- // Restore in another process
76
- const restored = await KxcoAgentIdentity.import(exported)
77
- ```
84
+ ## API
78
85
 
79
- ### Send relay operations
86
+ ### KxcoAgentIdentity
80
87
 
81
- ```js
82
- import { KxcoChain } from 'kxco-pq-chain'
88
+ **`KxcoAgentIdentity.create(opts)` → `Promise<KxcoAgentIdentity>`**
83
89
 
84
- const chain = new KxcoChain({ relay: 'https://relay.kxco.ai', identity: sponsor })
85
- const client = agent.toChainClient('https://relay.kxco.ai')
90
+ Generates an ML-DSA-65 keypair for the agent and has the sponsor sign the credential.
86
91
 
87
- const result = await client.anchorAttestation({
88
- payloadHash: '9f86d081884c7d65...',
89
- purpose: 'trade-confirmation',
90
- })
91
- // → { txHash: '0x...', blockNumber: 228345 }
92
+ | Option | Type | Required | Description |
93
+ |--------|------|----------|-------------|
94
+ | `sponsor` | `{ kid: string, sign(msg: Uint8Array): Promise<Uint8Array> }` | Yes | The sponsoring KxcoIdentity |
95
+ | `label` | `string` | Yes | Human-readable name for this agent |
96
+ | `agentType` | `'llm' \| 'robot' \| 'iot' \| 'process'` | Yes | Category of the agent |
97
+ | `model` | `string` | No | Model, firmware, or version identifier |
98
+ | `scope` | `object` | Yes | Capability manifest (see above) |
99
+ | `expiresIn` | `string \| number` | Yes | Duration: `'30d'`, `'1y'`, or seconds as a number |
100
+ | `chain` | `KxcoChain` | No | If provided, registers the credential on-chain at issuance |
92
101
 
93
- await client.anchorAuditRoot({ rootHash: '...', entryCount: 100 })
94
- await client.transfer({ recipientKid: 'aa29f37ab7f4b2cf', amount: 1000 })
95
- ```
102
+ **`agent.toChainClient(relay, opts?)` → `AgentChainClient`**
96
103
 
97
- ### Verify a credential
104
+ Returns a relay client that automatically attaches the agent's credential and signature to every request.
98
105
 
99
- ```js
100
- const result = await KxcoAgentIdentity.verify(credential, {
101
- sponsorPublicKey: sponsor.publicKey, // optional — skip to check format only
102
- })
103
- // → { valid: true, agentKid: '...', sponsorKid: '...', scope: {...} }
104
- ```
106
+ | Option | Type | Default | Description |
107
+ |--------|------|---------|-------------|
108
+ | `relay` | `string` | — | Relay base URL, e.g. `'https://relay.kxco.ai'` |
109
+ | `opts.timeout` | `number` | `10000` | Request timeout in milliseconds |
105
110
 
106
- ### Revoke an agent
111
+ **`agent.sign(message)` → `Promise<Uint8Array>`**
107
112
 
108
- ```js
109
- await KxcoAgentIdentity.revoke(agent.credential.agentKid, {
110
- chain,
111
- reason: 'Decommissioned',
112
- })
113
- ```
113
+ Signs an arbitrary message with the agent's ML-DSA-65 private key.
114
+
115
+ **`agent.export()` → `object`**
116
+
117
+ Serialises the full identity including the secret key. Store securely.
118
+
119
+ **`KxcoAgentIdentity.import(exported)` → `Promise<KxcoAgentIdentity>`**
120
+
121
+ Restores an agent identity from a previously exported object.
122
+
123
+ **`KxcoAgentIdentity.verify(credential, opts?)` → `Promise<{ valid, agentKid, sponsorKid, scope, ... }>`**
124
+
125
+ Verifies an agent credential envelope.
126
+
127
+ - Without `opts.sponsorPublicKey`: checks format and expiry only.
128
+ - With `opts.sponsorPublicKey` (Uint8Array): performs full ML-DSA-65 signature verification.
129
+
130
+ **`KxcoAgentIdentity.revoke(agentKid, { chain, reason? })` → `Promise`**
131
+
132
+ Revokes an agent credential on-chain. `chain` must be a KxcoChain instance belonging to the original sponsor.
114
133
 
115
134
  ---
116
135
 
117
- ## Scope manifest
136
+ ### AgentChainClient
118
137
 
119
- The scope is signed by the institution and cannot be modified after issuance.
120
-
121
- ```ts
122
- interface AgentScope {
123
- payments?: {
124
- maxPerTransaction: number // in smallest denomination
125
- maxPerDay: number
126
- allowedRecipients: string[] // EVM addresses (0x + 40 hex) or KXCO kids (16 hex)
127
- }
128
- attestations?: {
129
- purposes: string[] // allowed purpose strings
130
- }
131
- auditLog?: boolean // can anchor audit checkpoints
132
- credentials?: boolean // can manage credentials (use sparingly)
133
- }
134
- ```
138
+ Returned by `agent.toChainClient()`. All methods return `Promise<{ txHash: string, blockNumber: number }>`.
135
139
 
136
- The scope hash (SHA-256 of JCS-canonical scope JSON) is stored on-chain at issuance.
140
+ **`client.anchorAttestation({ payloadHash, purpose })`**
141
+
142
+ Anchors an attestation envelope hash on-chain. Requires `scope.attestations` with the matching purpose listed.
143
+
144
+ **`client.anchorAuditRoot({ rootHash, entryCount })`**
145
+
146
+ Anchors an audit log checkpoint on-chain. Requires `scope.auditLog: true`.
147
+
148
+ **`client.transfer({ to, amount })`**
149
+
150
+ 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.
137
151
 
138
152
  ---
139
153
 
@@ -148,8 +162,26 @@ The scope hash (SHA-256 of JCS-canonical scope JSON) is stored on-chain at issua
148
162
 
149
163
  ---
150
164
 
165
+ ## What this does NOT do
166
+
167
+ - Agents cannot issue credentials to other agents. Only a KYC-verified sponsor can create an agent identity.
168
+ - Agents cannot exceed the scope declared at issuance. The relay enforces scope server-side; attempting an out-of-scope operation returns an error.
169
+ - Agents cannot operate without a sponsor. There is no anonymous or self-signed credential mode.
170
+
171
+ ---
172
+
173
+ ## Part of the KXCO stack
174
+
175
+ | Package | Purpose |
176
+ |---------|---------|
177
+ | `kxco-post-quantum` | ML-DSA-65 and ML-KEM primitives |
178
+ | `kxco-pq-sdk` | KxcoIdentity — human and institution identities |
179
+ | `kxco-pq-agent` | This package — machine and agent identities |
180
+
181
+ Contact: hello@kxco.ai | https://kxco.ai
182
+
183
+ ---
184
+
151
185
  ## Authors
152
186
 
153
187
  Shayne Heffernan and John Heffernan — KXCO by Knightsbridge
154
-
155
- hello@kxco.ai | https://kxco.ai
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "kxco-pq-agent",
3
- "version": "1.0.2",
4
- "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.",
3
+ "version": "1.0.3",
4
+ "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.",
5
5
  "keywords": [
6
6
  "post-quantum",
7
7
  "pqc",