@0gfoundation/0g-agentdna 0.0.0-stage → 0.2.1

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 (206) hide show
  1. package/GUIDE.md +975 -0
  2. package/LICENSE +21 -0
  3. package/MIGRATION.md +84 -0
  4. package/MIGRATION.zh.md +70 -0
  5. package/PROVIDERS.md +273 -0
  6. package/PROVIDERS.zh.md +234 -0
  7. package/README.md +334 -2
  8. package/dist/AgentClient.d.ts +312 -0
  9. package/dist/AgentClient.d.ts.map +1 -0
  10. package/dist/AgentClient.js +715 -0
  11. package/dist/AgentClient.js.map +1 -0
  12. package/dist/AgenticID.d.ts +823 -0
  13. package/dist/AgenticID.d.ts.map +1 -0
  14. package/dist/AgenticID.js +1188 -0
  15. package/dist/AgenticID.js.map +1 -0
  16. package/dist/AgenticIDClient.d.ts +68 -0
  17. package/dist/AgenticIDClient.d.ts.map +1 -0
  18. package/dist/AgenticIDClient.js +198 -0
  19. package/dist/AgenticIDClient.js.map +1 -0
  20. package/dist/AttestorClient.d.ts +465 -0
  21. package/dist/AttestorClient.d.ts.map +1 -0
  22. package/dist/AttestorClient.js +1030 -0
  23. package/dist/AttestorClient.js.map +1 -0
  24. package/dist/Providers.d.ts +72 -0
  25. package/dist/Providers.d.ts.map +1 -0
  26. package/dist/Providers.js +182 -0
  27. package/dist/Providers.js.map +1 -0
  28. package/dist/ReputationClient.d.ts +213 -0
  29. package/dist/ReputationClient.d.ts.map +1 -0
  30. package/dist/ReputationClient.js +708 -0
  31. package/dist/ReputationClient.js.map +1 -0
  32. package/dist/SandboxClient.d.ts +107 -0
  33. package/dist/SandboxClient.d.ts.map +1 -0
  34. package/dist/SandboxClient.js +200 -0
  35. package/dist/SandboxClient.js.map +1 -0
  36. package/dist/ServeProof.d.ts +161 -0
  37. package/dist/ServeProof.d.ts.map +1 -0
  38. package/dist/ServeProof.js +230 -0
  39. package/dist/ServeProof.js.map +1 -0
  40. package/dist/ServeSession.d.ts +180 -0
  41. package/dist/ServeSession.d.ts.map +1 -0
  42. package/dist/ServeSession.js +336 -0
  43. package/dist/ServeSession.js.map +1 -0
  44. package/dist/Settings.d.ts +179 -0
  45. package/dist/Settings.d.ts.map +1 -0
  46. package/dist/Settings.js +247 -0
  47. package/dist/Settings.js.map +1 -0
  48. package/dist/abi.d.ts +2216 -0
  49. package/dist/abi.d.ts.map +1 -0
  50. package/dist/abi.js +1248 -0
  51. package/dist/abi.js.map +1 -0
  52. package/dist/cli/commands/cells.d.ts +62 -0
  53. package/dist/cli/commands/cells.d.ts.map +1 -0
  54. package/dist/cli/commands/cells.js +113 -0
  55. package/dist/cli/commands/cells.js.map +1 -0
  56. package/dist/cli/commands/doctor.d.ts +15 -0
  57. package/dist/cli/commands/doctor.d.ts.map +1 -0
  58. package/dist/cli/commands/doctor.js +236 -0
  59. package/dist/cli/commands/doctor.js.map +1 -0
  60. package/dist/cli/commands/interactive.d.ts +115 -0
  61. package/dist/cli/commands/interactive.d.ts.map +1 -0
  62. package/dist/cli/commands/interactive.js +3052 -0
  63. package/dist/cli/commands/interactive.js.map +1 -0
  64. package/dist/cli/commands/list.d.ts +31 -0
  65. package/dist/cli/commands/list.d.ts.map +1 -0
  66. package/dist/cli/commands/list.js +91 -0
  67. package/dist/cli/commands/list.js.map +1 -0
  68. package/dist/cli/commands/providers.d.ts +3 -0
  69. package/dist/cli/commands/providers.d.ts.map +1 -0
  70. package/dist/cli/commands/providers.js +21 -0
  71. package/dist/cli/commands/providers.js.map +1 -0
  72. package/dist/cli/commands/settings.d.ts +22 -0
  73. package/dist/cli/commands/settings.d.ts.map +1 -0
  74. package/dist/cli/commands/settings.js +188 -0
  75. package/dist/cli/commands/settings.js.map +1 -0
  76. package/dist/cli/commands/status.d.ts +16 -0
  77. package/dist/cli/commands/status.d.ts.map +1 -0
  78. package/dist/cli/commands/status.js +148 -0
  79. package/dist/cli/commands/status.js.map +1 -0
  80. package/dist/cli/commands/update.d.ts +21 -0
  81. package/dist/cli/commands/update.d.ts.map +1 -0
  82. package/dist/cli/commands/update.js +95 -0
  83. package/dist/cli/commands/update.js.map +1 -0
  84. package/dist/cli/config.d.ts +73 -0
  85. package/dist/cli/config.d.ts.map +1 -0
  86. package/dist/cli/config.js +239 -0
  87. package/dist/cli/config.js.map +1 -0
  88. package/dist/cli/env.d.ts +36 -0
  89. package/dist/cli/env.d.ts.map +1 -0
  90. package/dist/cli/env.js +74 -0
  91. package/dist/cli/env.js.map +1 -0
  92. package/dist/cli/envelope.d.ts +33 -0
  93. package/dist/cli/envelope.d.ts.map +1 -0
  94. package/dist/cli/envelope.js +62 -0
  95. package/dist/cli/envelope.js.map +1 -0
  96. package/dist/cli/errors.d.ts +48 -0
  97. package/dist/cli/errors.d.ts.map +1 -0
  98. package/dist/cli/errors.js +81 -0
  99. package/dist/cli/errors.js.map +1 -0
  100. package/dist/cli/inference.d.ts +21 -0
  101. package/dist/cli/inference.d.ts.map +1 -0
  102. package/dist/cli/inference.js +60 -0
  103. package/dist/cli/inference.js.map +1 -0
  104. package/dist/cli/logo.d.ts +21 -0
  105. package/dist/cli/logo.d.ts.map +1 -0
  106. package/dist/cli/logo.js +131 -0
  107. package/dist/cli/logo.js.map +1 -0
  108. package/dist/cli/main.d.ts +14 -0
  109. package/dist/cli/main.d.ts.map +1 -0
  110. package/dist/cli/main.js +223 -0
  111. package/dist/cli/main.js.map +1 -0
  112. package/dist/cli/proofs.d.ts +67 -0
  113. package/dist/cli/proofs.d.ts.map +1 -0
  114. package/dist/cli/proofs.js +133 -0
  115. package/dist/cli/proofs.js.map +1 -0
  116. package/dist/cli/ref.d.ts +39 -0
  117. package/dist/cli/ref.d.ts.map +1 -0
  118. package/dist/cli/ref.js +48 -0
  119. package/dist/cli/ref.js.map +1 -0
  120. package/dist/cli/sdk.d.ts +24 -0
  121. package/dist/cli/sdk.d.ts.map +1 -0
  122. package/dist/cli/sdk.js +65 -0
  123. package/dist/cli/sdk.js.map +1 -0
  124. package/dist/cli/settings.d.ts +66 -0
  125. package/dist/cli/settings.d.ts.map +1 -0
  126. package/dist/cli/settings.js +137 -0
  127. package/dist/cli/settings.js.map +1 -0
  128. package/dist/cli/tokenize.d.ts +61 -0
  129. package/dist/cli/tokenize.d.ts.map +1 -0
  130. package/dist/cli/tokenize.js +157 -0
  131. package/dist/cli/tokenize.js.map +1 -0
  132. package/dist/cli/types.d.ts +25 -0
  133. package/dist/cli/types.d.ts.map +1 -0
  134. package/dist/cli/types.js +8 -0
  135. package/dist/cli/types.js.map +1 -0
  136. package/dist/constants.d.ts +107 -0
  137. package/dist/constants.d.ts.map +1 -0
  138. package/dist/constants.js +74 -0
  139. package/dist/constants.js.map +1 -0
  140. package/dist/context.d.ts +108 -0
  141. package/dist/context.d.ts.map +1 -0
  142. package/dist/context.js +64 -0
  143. package/dist/context.js.map +1 -0
  144. package/dist/index.d.ts +45 -0
  145. package/dist/index.d.ts.map +1 -0
  146. package/dist/index.js +118 -0
  147. package/dist/index.js.map +1 -0
  148. package/dist/provider-catalog.json +23 -0
  149. package/dist/seal.d.ts +47 -0
  150. package/dist/seal.d.ts.map +1 -0
  151. package/dist/seal.js +145 -0
  152. package/dist/seal.js.map +1 -0
  153. package/dist/secretEnv.d.ts +119 -0
  154. package/dist/secretEnv.d.ts.map +1 -0
  155. package/dist/secretEnv.js +199 -0
  156. package/dist/secretEnv.js.map +1 -0
  157. package/dist/taskHash.d.ts +39 -0
  158. package/dist/taskHash.d.ts.map +1 -0
  159. package/dist/taskHash.js +119 -0
  160. package/dist/taskHash.js.map +1 -0
  161. package/dist/types.d.ts +336 -0
  162. package/dist/types.d.ts.map +1 -0
  163. package/dist/types.js +19 -0
  164. package/dist/types.js.map +1 -0
  165. package/package.json +75 -4
  166. package/scripts/sync-providers.cjs +8 -0
  167. package/src/AgentClient.ts +897 -0
  168. package/src/AgenticID.ts +1382 -0
  169. package/src/AgenticIDClient.ts +238 -0
  170. package/src/AttestorClient.ts +1306 -0
  171. package/src/Providers.ts +176 -0
  172. package/src/ReputationClient.ts +821 -0
  173. package/src/SandboxClient.ts +227 -0
  174. package/src/ServeProof.ts +290 -0
  175. package/src/ServeSession.ts +421 -0
  176. package/src/Settings.ts +296 -0
  177. package/src/abi.ts +1282 -0
  178. package/src/cli/commands/cells.ts +107 -0
  179. package/src/cli/commands/doctor.ts +235 -0
  180. package/src/cli/commands/interactive.ts +2738 -0
  181. package/src/cli/commands/list.ts +95 -0
  182. package/src/cli/commands/providers.ts +16 -0
  183. package/src/cli/commands/settings.ts +197 -0
  184. package/src/cli/commands/status.ts +170 -0
  185. package/src/cli/commands/update.ts +86 -0
  186. package/src/cli/config.ts +225 -0
  187. package/src/cli/env.ts +90 -0
  188. package/src/cli/envelope.ts +57 -0
  189. package/src/cli/errors.ts +114 -0
  190. package/src/cli/inference.ts +57 -0
  191. package/src/cli/logo.ts +125 -0
  192. package/src/cli/main.ts +235 -0
  193. package/src/cli/proofs.ts +160 -0
  194. package/src/cli/ref.ts +58 -0
  195. package/src/cli/sdk.ts +65 -0
  196. package/src/cli/settings.ts +153 -0
  197. package/src/cli/tokenize.ts +131 -0
  198. package/src/cli/types.ts +27 -0
  199. package/src/constants.ts +106 -0
  200. package/src/context.ts +161 -0
  201. package/src/index.ts +129 -0
  202. package/src/provider-catalog.json +23 -0
  203. package/src/seal.ts +163 -0
  204. package/src/secretEnv.ts +250 -0
  205. package/src/taskHash.ts +100 -0
  206. package/src/types.ts +357 -0
@@ -0,0 +1,336 @@
1
+ "use strict";
2
+ /**
3
+ * @file ServeSession.ts
4
+ * @description Consumer-side transport for reputation: call an agent's serve
5
+ * endpoint (any framework, any path) and capture the TEE-signed ServeProof the
6
+ * sealed proxy stamps on every response as the `X-Agent-Proof` header.
7
+ *
8
+ * Each agent runs its own serve endpoint — whatever HTTP API it needs; the
9
+ * protocol doesn't prescribe one, so it differs per agent. The one invariant is
10
+ * the sealed proxy in front of it, which stamps `X-Agent-Proof` on every
11
+ * response. So this layer doesn't model the call — you invoke the agent however
12
+ * it expects; ServeSession only extracts the proof from the response. The proof
13
+ * is then submittable on-chain via ReputationClient.giveFeedback (attribution is
14
+ * msg.sender; only the proof's `submitter` may redeem it).
15
+ *
16
+ * Header format (from sealed/internal/proxy):
17
+ * X-Agent-Proof: 0x<65-byte sig hex>.<base64url(envelope JSON)>
18
+ * envelope JSON = { agent_id, submitter, timestamp, deadline, task_hash,
19
+ * data_hashes[], framework_hash, validator }
20
+ * `validator` (the VerifiedFeedbackRegistry the signature is bound to) is
21
+ * diagnostics only — not part of the on-chain ServeProof tuple — and absent on
22
+ * images that predate it.
23
+ */
24
+ Object.defineProperty(exports, "__esModule", { value: true });
25
+ exports.ServeSession = exports.SERVE_PROOF_HEADER = void 0;
26
+ exports.parseServeProofHeader = parseServeProofHeader;
27
+ exports.proofFromResponse = proofFromResponse;
28
+ exports.normalizedMethod = normalizedMethod;
29
+ exports.requestBytesOf = requestBytesOf;
30
+ exports.proofRecordingFetch = proofRecordingFetch;
31
+ exports.taskRevealOf = taskRevealOf;
32
+ exports.captureProof = captureProof;
33
+ const viem_1 = require("viem");
34
+ const abi_1 = require("./abi");
35
+ const ServeProof_1 = require("./ServeProof");
36
+ const taskHash_1 = require("./taskHash");
37
+ exports.SERVE_PROOF_HEADER = 'X-Agent-Proof';
38
+ const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
39
+ function b64urlDecode(s) {
40
+ const b64 = s.replace(/-/g, '+').replace(/_/g, '/');
41
+ const g = globalThis;
42
+ if (typeof g.atob === 'function')
43
+ return g.atob(b64);
44
+ // Node fallback (envelope is ASCII, so binary === utf8 here).
45
+ return Buffer.from(b64, 'base64').toString('binary');
46
+ }
47
+ /**
48
+ * Parse an `X-Agent-Proof` header value into a ServeProof ready for
49
+ * ReputationClient.giveFeedback.
50
+ */
51
+ function parseServeProofHeader(value) {
52
+ const dot = value.indexOf('.');
53
+ if (dot < 0)
54
+ throw new Error('malformed X-Agent-Proof header (missing ".")');
55
+ const signature = value.slice(0, dot);
56
+ const env = JSON.parse(b64urlDecode(value.slice(dot + 1)));
57
+ return {
58
+ agentId: BigInt(env.agent_id),
59
+ submitter: env.submitter ?? ZERO_ADDRESS,
60
+ timestamp: BigInt(env.timestamp),
61
+ deadline: BigInt(env.deadline),
62
+ taskHash: env.task_hash,
63
+ dataHashes: env.data_hashes ?? [],
64
+ frameworkHash: env.framework_hash,
65
+ signature,
66
+ // Unsigned diagnostics from an untrusted header: keep only a string.
67
+ ...(typeof env.validator === 'string' && env.validator ? { validator: env.validator } : {}),
68
+ };
69
+ }
70
+ /**
71
+ * Extract the ServeProof from a fetch Response, or null if the agent did not
72
+ * stamp one (e.g. an unminted agent / dev mode).
73
+ */
74
+ function proofFromResponse(res) {
75
+ const header = res.headers.get(exports.SERVE_PROOF_HEADER);
76
+ return header ? parseServeProofHeader(header) : null;
77
+ }
78
+ /** The methods undici/fetch normalize to uppercase themselves (measured:
79
+ * get→GET … options→OPTIONS; anything else, e.g. `patch`, travels as
80
+ * written and the proxy hashes r.Method as received). Recording must
81
+ * uppercase exactly these six — more would hash a method the proxy never
82
+ * saw, fewer would record 'get' where the wire said 'GET'. */
83
+ const FETCH_NORMALIZED_METHODS = new Set(['get', 'head', 'post', 'put', 'delete', 'options']);
84
+ /** The HTTP method as it travels on the wire (see the set above). */
85
+ function normalizedMethod(m) {
86
+ const s = m ?? 'GET';
87
+ return FETCH_NORMALIZED_METHODS.has(s.toLowerCase()) ? s.toUpperCase() : s;
88
+ }
89
+ /** The request body bytes as they traveled, for the taskHash preimage —
90
+ * or null when the shape cannot be captured faithfully (Blob/FormData
91
+ * are async, ReadableStream would block): the caller must treat the
92
+ * whole task as unrecorded, never hash a wrong '' stand-in. */
93
+ function requestBytesOf(body) {
94
+ if (body == null)
95
+ return '';
96
+ if (typeof body === 'string')
97
+ return body;
98
+ if (body instanceof Uint8Array)
99
+ return body;
100
+ if (body instanceof ArrayBuffer)
101
+ return new Uint8Array(body);
102
+ if (body instanceof URLSearchParams)
103
+ return body.toString(); // undici sends exactly this
104
+ if (body instanceof DataView) {
105
+ return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
106
+ }
107
+ return null; // Blob, FormData, ReadableStream, … — unrecordable, not wrong
108
+ }
109
+ /**
110
+ * A fetch-compatible wrapper for generic MCP clients: every SIGNED exchange
111
+ * it performs is recorded (proof + task) into `log`, and the Response is
112
+ * returned untouched, so an MCP SDK's streamable-HTTP transport accepts it
113
+ * as its custom fetch (the transport is passed to `client.connect()`).
114
+ * Unsigned responses are logged with `task: null` and their body is never
115
+ * read — a long-lived SSE listener would otherwise never resolve. After the
116
+ * session, verify each entry with `session.verifyProof(entry.proof, { task:
117
+ * entry.task })` — note `task: null` yields `ok: false` (fail closed), so
118
+ * skip entries whose task is null only when you know why it is.
119
+ *
120
+ * @example
121
+ * const log: Array<{ proof: ServeProof | null; task: TaskExchange | null }> = [];
122
+ * const client = new Client({ name: 'consumer', version: '1' });
123
+ * await client.connect(new StreamableHTTPClientTransport(url, {
124
+ * fetch: proofRecordingFetch(log),
125
+ * }));
126
+ * // … run the MCP session …
127
+ * for (const e of log) if (e.proof) {
128
+ * const v = await session.verifyProof(e.proof, { task: e.task });
129
+ * if (!v.ok || !v.taskMatches) throw new Error('unverified MCP exchange');
130
+ * }
131
+ */
132
+ function proofRecordingFetch(log) {
133
+ return (async (input, init) => {
134
+ // A Request as input: clone it BEFORE fetch consumes its body, so the
135
+ // request bytes stay recoverable if the response turns out signed.
136
+ // init.body (when set) overrides the Request's own body on the wire —
137
+ // clone only when the Request's body is what will actually be sent.
138
+ // Per the Fetch spec, `init.body: null` falls back to the Request's
139
+ // body too, so only a non-null override defeats the clone.
140
+ const reqClone = input instanceof Request && input.body && init?.body == null ? input.clone() : null;
141
+ const response = await fetch(input, init);
142
+ // Record the task only when the response carries X-Agent-Proof: a
143
+ // signed response is always finite (the proxy buffers it whole), so
144
+ // awaiting the clone cannot hang; an unsigned/SSE response is returned
145
+ // immediately — awaiting its body would block the caller's stream.
146
+ const proof = proofFromResponse(response);
147
+ let task = null;
148
+ if (proof) {
149
+ try {
150
+ const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
151
+ const method = input instanceof Request && !init?.method ? input.method : normalizedMethod(init?.method);
152
+ let reqBytes;
153
+ if (reqClone) {
154
+ reqBytes = await reqClone.arrayBuffer().then((b) => new Uint8Array(b));
155
+ }
156
+ else {
157
+ reqBytes = requestBytesOf(init?.body);
158
+ }
159
+ if (reqBytes !== null) {
160
+ const cloned = response.clone();
161
+ const respBytes = await cloned.arrayBuffer().then((b) => new Uint8Array(b));
162
+ task = { method, url, requestBytes: reqBytes, responseBytes: respBytes, status: response.status };
163
+ }
164
+ }
165
+ catch {
166
+ task = null;
167
+ }
168
+ }
169
+ log.push({ proof, task });
170
+ return response;
171
+ });
172
+ }
173
+ /**
174
+ * Build the TaskReveal(s) for an exchange you actually sent and received —
175
+ * the input to `verifyProof(proof, { task })`'s per-exchange binding. The
176
+ * proxy hashed one specific URI form; undici (Node fetch) and browsers
177
+ * differ on a bare trailing '?', so one reveal per requestUriCandidates
178
+ * form is returned and the comparison tries each.
179
+ *
180
+ * The bytes are hashed exactly as they traveled: pass the raw request body
181
+ * string/bytes and the raw response body (NOT a re-serialized JSON —
182
+ * key order and whitespace change the hash).
183
+ */
184
+ function taskRevealOf(exchange) {
185
+ const reqBytes = exchange.requestBytes ?? '';
186
+ const reqBodyHash = (0, viem_1.keccak256)(typeof reqBytes === 'string' ? (0, viem_1.stringToBytes)(reqBytes) : reqBytes);
187
+ const respBodyHash = (0, viem_1.keccak256)(typeof exchange.responseBytes === 'string'
188
+ ? (0, viem_1.stringToBytes)(exchange.responseBytes)
189
+ : exchange.responseBytes);
190
+ return (0, taskHash_1.requestUriCandidates)(exchange.url).map((uri) => ({
191
+ method: exchange.method,
192
+ uri,
193
+ reqBodyHash,
194
+ respBodyHash,
195
+ statusCode: exchange.status,
196
+ }));
197
+ }
198
+ /**
199
+ * Run an agent call (yielding a Response) and capture its ServeProof.
200
+ * You still consume the body yourself (`response.json()` etc.).
201
+ *
202
+ * @example
203
+ * const { response, proof } = await captureProof(() =>
204
+ * fetch(`${agentUrl}/chat`, { method: 'POST', body }));
205
+ * const data = await response.json();
206
+ * if (proof) await rep.giveFeedback({ ...feedback, serveProof: proof });
207
+ */
208
+ async function captureProof(call) {
209
+ const response = await call();
210
+ return { response, proof: proofFromResponse(response) };
211
+ }
212
+ /**
213
+ * Chain-aware helper to validate a captured ServeProof before submitting — so a
214
+ * stale or mismatched proof is caught locally rather than by an on-chain revert.
215
+ */
216
+ class ServeSession {
217
+ constructor(ctx, options = {}) {
218
+ this.agenticID = ctx.addresses.agenticID;
219
+ this.verifiedFeedback = ctx.addresses.verifiedFeedback ?? ZERO_ADDRESS;
220
+ this.publicClient = ctx.publicClient;
221
+ this.clockSkew = options.clockSkew ?? 0;
222
+ this.now = options.now ?? (() => Math.floor(Date.now() / 1000));
223
+ }
224
+ /**
225
+ * Verify a proof against chain state: signer == on-chain agentSeal (over the
226
+ * digest bound to the configured VerifiedFeedbackRegistry), deadline not
227
+ * passed, and every declared dataHash is present in the agent's on-chain
228
+ * iData (so the buyer knows what the agent was running).
229
+ *
230
+ * Needs `addresses.verifiedFeedback` (fromAttestor fills it): without it
231
+ * nothing can be verified and `signerMatches` / `registryMatches` are false.
232
+ */
233
+ /**
234
+ * Verify a proof against chain state. Without `opts.task` the verdict is
235
+ * signer attribution: the proof was signed by this agent's on-chain
236
+ * agentSeal, in time, over data the chain knows. With `opts.task` (a
237
+ * TaskReveal, or the TaskExchange you actually sent/received) the verdict
238
+ * additionally binds the proof to THAT exchange: `taskMatches` recomputes
239
+ * taskHash = keccak(method ‖ uri ‖ keccak(reqBody) ‖ keccak(respBody) ‖
240
+ * status) from your bytes and compares it to the proof's commitment — a
241
+ * genuine proof attached to a different response body yields
242
+ * `taskMatches: false` and `ok: false`. An explicit `task: null` (what
243
+ * the recorders return when the exchange wasn't captured) fails closed:
244
+ * `ok: false`, never a silent fall-back to signer-only.
245
+ */
246
+ async verifyProof(proof, opts) {
247
+ const reasons = [];
248
+ const notExpired = proof.deadline > BigInt(this.now() - this.clockSkew);
249
+ if (!notExpired)
250
+ reasons.push('proof deadline has passed');
251
+ // The signature is bound to the registry that redeems it (EIP-191 v0x00
252
+ // intended validator). Without one there is nothing to verify against;
253
+ // when the envelope names another one, the signature cannot match ours.
254
+ const registry = this.verifiedFeedback;
255
+ const registryConfigured = (0, viem_1.isAddress)(registry, { strict: false }) && registry.toLowerCase() !== ZERO_ADDRESS;
256
+ let registryMatches = registryConfigured;
257
+ let signerMatches = false;
258
+ if (!registryConfigured) {
259
+ reasons.push('no VerifiedFeedbackRegistry configured — cannot verify serve-proof');
260
+ }
261
+ else if (proof.validator && proof.validator.toLowerCase() !== registry.toLowerCase()) {
262
+ registryMatches = false;
263
+ reasons.push(`proof signed for a different VerifiedFeedbackRegistry (proof: ${proof.validator}, configured: ${registry})`);
264
+ }
265
+ else {
266
+ const agentSeal = (await this.publicClient.readContract({
267
+ address: this.agenticID,
268
+ abi: abi_1.agenticIDAbi,
269
+ functionName: 'getAgentSeal',
270
+ args: [proof.agentId],
271
+ }));
272
+ // The digest is domain-bound: the proof was signed against this chain,
273
+ // the identity registry the reputation contract is anchored to, and the
274
+ // reputation contract itself.
275
+ const chainId = BigInt(await this.publicClient.getChainId());
276
+ signerMatches =
277
+ agentSeal !== ZERO_ADDRESS &&
278
+ (await (0, ServeProof_1.verifyServeProofSignature)(proof, agentSeal, {
279
+ chainId,
280
+ verifyingContract: this.agenticID,
281
+ validator: registry,
282
+ }));
283
+ if (!signerMatches) {
284
+ reasons.push(proof.validator
285
+ ? 'signature does not match the on-chain agentSeal'
286
+ : 'signature does not match the on-chain agentSeal (the proof names no validator — likely a pre-upgrade sealed image)');
287
+ }
288
+ }
289
+ // dataHashes ⊆ intelligentDatasOf(agentId)
290
+ let dataOnChain = true;
291
+ if (proof.dataHashes.length > 0) {
292
+ const idatas = (await this.publicClient.readContract({
293
+ address: this.agenticID,
294
+ abi: abi_1.agenticIDAbi,
295
+ functionName: 'intelligentDatasOf',
296
+ args: [proof.agentId],
297
+ }));
298
+ const onChain = new Set(idatas.map((d) => d.dataHash.toLowerCase()));
299
+ dataOnChain = proof.dataHashes.every((h) => onChain.has(h.toLowerCase()));
300
+ if (!dataOnChain)
301
+ reasons.push('a declared dataHash is not on chain for this agent');
302
+ }
303
+ // Optional per-exchange binding: recompute the taskHash from the
304
+ // caller's own bytes and compare against the proof's commitment. With a
305
+ // TaskExchange every URI candidate gets a reveal (undici drops a bare
306
+ // trailing '?', browsers keep it — the proxy hashed one of the two).
307
+ // An EXPLICIT null is not "no task": the caller passed
308
+ // fetchWithProof's task and it wasn't recorded — fail closed rather
309
+ // than silently degrade to the signer-only verdict.
310
+ let taskMatches = null;
311
+ if (opts && 'task' in opts) {
312
+ if (opts.task == null) {
313
+ taskMatches = false;
314
+ reasons.push('task was passed but not recorded — cannot bind this exchange');
315
+ }
316
+ else {
317
+ const reveals = 'responseBytes' in opts.task ? taskRevealOf(opts.task) : [opts.task];
318
+ taskMatches = reveals.some((r) => (0, taskHash_1.taskHashOf)(r) === proof.taskHash);
319
+ if (!taskMatches) {
320
+ reasons.push('taskHash does not match this exchange (method/uri/bodies/status)');
321
+ }
322
+ }
323
+ }
324
+ return {
325
+ ok: signerMatches && notExpired && dataOnChain && taskMatches !== false,
326
+ signerMatches,
327
+ notExpired,
328
+ dataOnChain,
329
+ registryMatches,
330
+ taskMatches,
331
+ reasons,
332
+ };
333
+ }
334
+ }
335
+ exports.ServeSession = ServeSession;
336
+ //# sourceMappingURL=ServeSession.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ServeSession.js","sourceRoot":"","sources":["../src/ServeSession.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,179 @@
1
+ import { type InferenceProvider } from './Providers';
2
+ /**
3
+ * @file Settings.ts
4
+ * @description The owner's configuration document — the one blob that says
5
+ * which model an agent thinks with, and how hard.
6
+ *
7
+ * Where it lives and who understands it:
8
+ * - the OWNER authors it (this file's {@link SettingsDoc});
9
+ * - the ATTESTOR stores it opaquely: it never parses the contents, never
10
+ * validates them, and gains no knowledge of what a setting means. Its
11
+ * only jobs are store / serve to the container / refuse a write that is
12
+ * not signed by the agent's current on-chain owner;
13
+ * - the CONTAINER (`sealed/internal/settings`) is where all meaning lives
14
+ * and is the real gate.
15
+ *
16
+ * That layering is the point: widening the vocabulary — a new field, a new
17
+ * framework knob — is a container change only. Nothing here or in the
18
+ * attestor has to learn about it. {@link SettingsDoc} therefore mirrors the
19
+ * Go `settings.Doc` exactly, and `others` stays deliberately opaque.
20
+ *
21
+ * It is NOT on chain. Configuration is re-suppliable (an owner re-picks a
22
+ * model in ten seconds); memory is not, and only memory earns chain storage.
23
+ *
24
+ * THE SIGNATURE COVERS A DIGEST, NOT THE DOCUMENT. `POST /settings` carries
25
+ * the signed statement in an HTTP header, which must stay short and ASCII,
26
+ * while the document is large and may be non-ASCII. So the owner signs
27
+ * `AgenticID.Settings.v1:<sealId>:<ts>:<base_version>:<sha256 of the bytes sent>`
28
+ * and the bytes themselves ride the body. For that to mean anything, the
29
+ * digest and the body must come from ONE serialization — see
30
+ * {@link canonicalSettings}, whose output is BOTH hashed and spliced
31
+ * verbatim into the request body.
32
+ *
33
+ * EVERY WRITE IS A COMPARE-AND-SWAP. `base_version` is the version the writer
34
+ * read before editing (0 = "I believe there is no document yet"); the attestor
35
+ * refuses with HTTP 409 when it no longer matches the stored one. Three holes
36
+ * close at once: a captured request cannot be replayed to roll the document
37
+ * back to a superseded one, two clients editing the same agent cannot silently
38
+ * overwrite each other, and a client that never read cannot blind-write over a
39
+ * document it has not seen. {@link SettingsConflictError} is what the SDK
40
+ * raises for that 409 — re-read, re-apply the edit, write again. Never retry
41
+ * the same bytes in a loop: the point of the refusal is that a human decides
42
+ * what survives.
43
+ *
44
+ * READS ARE OWNER-GATED TOO. The document is the owner's, so `GET /settings`
45
+ * carries the same owner signature, minus the digest (there is no body): the
46
+ * message ends at `base_version`, which a reader sends as 0. It is NOT on the
47
+ * public deployment row or in any listing.
48
+ */
49
+ /** The reasoning-depth vocabulary (Go: `settings.Levels`). */
50
+ export declare const THINKING_LEVELS: readonly ["low", "high", "max"];
51
+ export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
52
+ /** Signed-message domain for `POST /settings`. */
53
+ export declare const SETTINGS_DOMAIN = "AgenticID.Settings.v1";
54
+ /** The 0G router's public model catalog — no auth. */
55
+ export declare const ROUTER_MODELS_URL: string;
56
+ /**
57
+ * The owner's settings document — the exact shape of Go's `settings.Doc`
58
+ * (`sealed/internal/settings/settings.go`). Field names, field order and
59
+ * omit-when-empty semantics all match, so what this SDK stores is what Go
60
+ * parses back, field for field. (The encoded BYTES can differ — see
61
+ * {@link canonicalSettings} — and nothing depends on them not doing so.)
62
+ */
63
+ export interface SettingsDoc {
64
+ /**
65
+ * Who serves the model. `'0g-compute'` means the PLATFORM supplies the
66
+ * endpoint. Other registered managed providers supply their own endpoint;
67
+ * registered native providers use the framework's built-in wiring.
68
+ */
69
+ provider?: string;
70
+ /** The model id, spelled the way the provider spells it. */
71
+ model?: string;
72
+ /** Reasoning-depth preference — one of {@link THINKING_LEVELS}. */
73
+ thinking?: ThinkingLevel;
74
+ /**
75
+ * Everything beyond the three named settings: the running framework's OWN
76
+ * knobs, passed through opaquely. Named `others` and not `framework`
77
+ * because a live drill showed the obvious reading of that word — choosing
78
+ * WHICH framework runs — is exactly what this field cannot do (the
79
+ * framework binding is minted identity). The platform neither parses nor
80
+ * validates the contents, nor promises they survive a framework upgrade. Any
81
+ * JSON value. `undefined`/`null` omits the section entirely.
82
+ */
83
+ others?: unknown;
84
+ /**
85
+ * The document is EXTENSIBLE by design: the container defines the
86
+ * vocabulary, so a field newer than this SDK is legitimate. It is carried
87
+ * through {@link canonicalSettings} untouched, which is what keeps an
88
+ * older client from erasing a newer setting on a read-modify-write.
89
+ */
90
+ [key: string]: unknown;
91
+ }
92
+ /** `'0g-compute'` — the provider for which the platform routes the model. */
93
+ export declare const ZG_COMPUTE_PROVIDER = "0g-compute";
94
+ /** The fields the PLATFORM names and guarantees, in Go declaration order.
95
+ * Everything else in a document belongs to the container. */
96
+ export declare const SETTINGS_FIELDS: readonly ["provider", "model", "thinking", "others"];
97
+ /**
98
+ * THE serialization. Its output is what gets hashed into the signed header
99
+ * AND what is spliced verbatim into the request body, so the two can never
100
+ * disagree — two independent `JSON.stringify` calls would be one refactor
101
+ * away from a bogus "signer mismatch".
102
+ *
103
+ * Field order follows the Go struct's declaration order and empty fields are
104
+ * dropped, matching `encoding/json` + `omitempty`. `others` is passed
105
+ * through as raw JSON — the platform does not interpret it.
106
+ *
107
+ * It is NOT byte-identical to Go's `settings.Doc.Marshal`, and does not have
108
+ * to be: Go's encoder escapes `<`, `>`, `&` (and U+2028/U+2029) by default,
109
+ * where `JSON.stringify` emits them literally — so any document containing
110
+ * one of those serializes differently on the two sides. Nothing rests on the
111
+ * two agreeing byte-for-byte. The digest covers the bytes ACTUALLY SENT, the
112
+ * attestor stores those bytes, and the container parses the document rather
113
+ * than re-hashing it. What must match across the two is the VALUE: same
114
+ * fields, same types, same omissions.
115
+ */
116
+ export declare function canonicalSettings(doc: SettingsDoc): string;
117
+ /** sha256 of a string's UTF-8 bytes, lowercase hex, no `0x`. */
118
+ export declare function sha256Hex(s: string): Promise<string>;
119
+ /**
120
+ * The exact statement the owner signs. ASCII and short by construction — it
121
+ * travels in `X-Auth-Message`. Two forms, one grammar:
122
+ *
123
+ * write `AgenticID.Settings.v1:0x<sealId>:<unix seconds>:<base_version>:<sha256-hex>`
124
+ * read `AgenticID.Settings.v1:0x<sealId>:<unix seconds>:<base_version>`
125
+ *
126
+ * `baseVersion` is the version the writer read before editing — the
127
+ * compare-and-swap term. A read has no body and therefore no digest, and
128
+ * nothing to swap against, so it ends at `baseVersion` and sends 0.
129
+ */
130
+ export declare function settingsAuthMessage(sealId: string, unixSeconds: number, baseVersion: number, digestHex?: string): string;
131
+ /**
132
+ * A write whose `base_version` no longer matches what the attestor holds
133
+ * (HTTP 409): somebody else changed the document between the read and the
134
+ * write, or the request is a replay of a superseded one.
135
+ *
136
+ * The SDK re-reads before throwing, so {@link current} / {@link currentVersion}
137
+ * are the live document — enough for a caller to show what it would have
138
+ * overwritten. It deliberately does NOT retry: re-applying the same edit
139
+ * blindly is how the other writer's change disappears, which is the whole
140
+ * thing the version guard exists to prevent. Re-apply the edit onto
141
+ * {@link current} and write again against {@link currentVersion} — as a human
142
+ * decision, not a loop.
143
+ */
144
+ export declare class SettingsConflictError extends Error {
145
+ readonly name = "SettingsConflictError";
146
+ /** The agent whose document was contested. */
147
+ readonly sealId: string;
148
+ /** The version this write was made against. */
149
+ readonly baseVersion: number;
150
+ /** The version the attestor holds now (0 when it could not be re-read). */
151
+ readonly currentVersion: number;
152
+ /** The document the attestor holds now; null when unset or unreadable. */
153
+ readonly current: SettingsDoc | null;
154
+ constructor(args: {
155
+ sealId: string;
156
+ baseVersion: number;
157
+ currentVersion: number;
158
+ current: SettingsDoc | null;
159
+ detail?: string;
160
+ });
161
+ }
162
+ /**
163
+ * The advisory model check: is `model` in the 0G router's public catalog?
164
+ *
165
+ * ADVISORY ONLY, in both directions. A framework built-in
166
+ * (`anthropic/claude-…`) is legitimately absent from a catalog that covers
167
+ * the 0G router alone, and the container is the real gate — so an absence is
168
+ * a warning, never a refusal. An unreachable catalog produces no warning at
169
+ * all rather than a false one.
170
+ *
171
+ * Never throws.
172
+ *
173
+ * @returns human-readable warnings; empty when everything looked fine, the
174
+ * catalog was unreachable, or there was nothing to check.
175
+ */
176
+ export declare function modelAdvisory(doc: SettingsDoc, resolvedProvider?: InferenceProvider): Promise<string[]>;
177
+ /** The router catalog's model ids, or null when it could not be read. */
178
+ export declare function fetchRouterModelIds(provider?: string): Promise<string[] | null>;
179
+ //# sourceMappingURL=Settings.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"Settings.d.ts","sourceRoot":"","sources":["../src/Settings.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyD,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC5G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,8DAA8D;AAC9D,eAAO,MAAM,eAAe,iCAAkC,CAAC;AAC/D,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,kDAAkD;AAClD,eAAO,MAAM,eAAe,0BAA0B,CAAC;AAEvD,sDAAsD;AACtD,eAAO,MAAM,iBAAiB,QAAgD,CAAC;AAE/E;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD;8DAC8D;AAC9D,eAAO,MAAM,eAAe,sDAAuD,CAAC;AAEpF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAyB1D;AAqBD,gEAAgE;AAChE,wBAAsB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAGR;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,2BAA2B;IACxC,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;gBAEzB,IAAI,EAAE;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;QACvB,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;QAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;CAYF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,WAAW,EAAE,gBAAgB,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAoC7G;AAED,yEAAyE;AACzE,wBAAsB,mBAAmB,CAAC,QAAQ,SAAsB,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAGlG"}