@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,230 @@
1
+ "use strict";
2
+ /**
3
+ * @file ServeProof.ts
4
+ * @description ServeProof construction and signing utilities for the 0G AgenticID protocol.
5
+ *
6
+ * A ServeProof attests that an agent (identified by agentSeal) served a task at a
7
+ * specific time. The agentSeal private key signs the proof. Two hashes:
8
+ *
9
+ * proofHash = keccak256(abi.encode(<proof fields>)) (buildServeProofMessageHash)
10
+ * digest = keccak256(0x19 ‖ 0x00 ‖ validator ‖ proofHash) (buildServeProofSigningHash)
11
+ *
12
+ * The signed digest is EIP-191 version 0x00 ("data with intended validator",
13
+ * OZ `MessageHashUtils.toDataWithIntendedValidatorHash`), where `validator` is
14
+ * the VerifiedFeedbackRegistry proxy that redeems the proof. It is NOT
15
+ * personal_sign: the sealed sign socket offers personal_sign (0x19 0x45),
16
+ * EIP-712 typed data (0x19 0x01) and transactions — never raw hashes or
17
+ * 0x19 0x00 — so an in-container agent cannot forge ServeProof contents
18
+ * through it. A personal_sign over proofHash is rejected on purpose.
19
+ *
20
+ * Attribution is msg.sender at giveFeedback submission (feedback is stored
21
+ * under the submitting address); the proof additionally names a `submitter`,
22
+ * the only address the registry lets redeem it (single-use via the signature).
23
+ */
24
+ Object.defineProperty(exports, "__esModule", { value: true });
25
+ exports.buildServeProofMessageHash = buildServeProofMessageHash;
26
+ exports.buildServeProofSigningHash = buildServeProofSigningHash;
27
+ exports.buildServeProof = buildServeProof;
28
+ exports.signServeProof = signServeProof;
29
+ exports.verifyServeProofSignature = verifyServeProofSignature;
30
+ const viem_1 = require("viem");
31
+ const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
32
+ /**
33
+ * Compute the ServeProof message hash exactly as the Solidity contract does.
34
+ *
35
+ * Solidity:
36
+ * ```solidity
37
+ * bytes32 messageHash = keccak256(abi.encode(
38
+ * block.chainid,
39
+ * identityRegistry, // verifyingContract
40
+ * submitter,
41
+ * agentId,
42
+ * timestamp,
43
+ * deadline,
44
+ * taskHash,
45
+ * keccak256(abi.encodePacked(dataHashes)),
46
+ * frameworkHash
47
+ * ));
48
+ * ```
49
+ *
50
+ * chainId + verifyingContract give cross-chain / cross-deployment separation;
51
+ * submitter binds the proof to the single address allowed to redeem it.
52
+ * This is the inner hash only — what gets signed is
53
+ * {@link buildServeProofSigningHash}.
54
+ *
55
+ * @param params - The ServeProof hash parameters
56
+ * @returns The keccak256 hash of the abi.encode payload
57
+ */
58
+ function buildServeProofMessageHash(params) {
59
+ const { chainId, verifyingContract, submitter, agentId, timestamp, deadline, taskHash, dataHashes, frameworkHash } = params;
60
+ // Step 1: keccak256(abi.encodePacked(dataHashes)) — concatenate bytes32 values
61
+ const packedDataHashes = dataHashes.length > 0
62
+ ? (0, viem_1.concat)(dataHashes)
63
+ : '0x';
64
+ const dataHashesHash = (0, viem_1.keccak256)(packedDataHashes);
65
+ // Step 2: abi.encode(chainId, verifyingContract, submitter, agentId, timestamp,
66
+ // deadline, taskHash, dataHashesHash, frameworkHash). Each field is a static
67
+ // 32-byte word: uint256 = 32, address = 32 (left-padded), bytes32 = 32.
68
+ const encoded = (0, viem_1.concat)([
69
+ (0, viem_1.pad)((0, viem_1.toHex)(chainId), { size: 32 }),
70
+ (0, viem_1.pad)(verifyingContract, { size: 32 }),
71
+ (0, viem_1.pad)(submitter, { size: 32 }),
72
+ (0, viem_1.pad)((0, viem_1.toHex)(agentId), { size: 32 }),
73
+ (0, viem_1.pad)((0, viem_1.toHex)(timestamp), { size: 32 }),
74
+ (0, viem_1.pad)((0, viem_1.toHex)(deadline), { size: 32 }),
75
+ (0, viem_1.pad)(taskHash, { size: 32 }),
76
+ (0, viem_1.pad)(dataHashesHash, { size: 32 }),
77
+ (0, viem_1.pad)(frameworkHash, { size: 32 }),
78
+ ]);
79
+ // Step 3: keccak256(encoded)
80
+ return (0, viem_1.keccak256)(encoded);
81
+ }
82
+ /** True for a well-formed (any case), non-zero 20-byte address. viem's
83
+ * `concat` does not validate lengths, so a short or padded validator would
84
+ * silently yield a digest nobody can redeem. */
85
+ function isUsableValidator(validator) {
86
+ return (typeof validator === 'string' &&
87
+ (0, viem_1.isAddress)(validator, { strict: false }) &&
88
+ validator.toLowerCase() !== ZERO_ADDRESS);
89
+ }
90
+ /**
91
+ * Compute the digest a ServeProof signature covers.
92
+ *
93
+ * EIP-191 version 0x00 (data with intended validator):
94
+ * `keccak256(0x19 ‖ 0x00 ‖ validator (20 bytes) ‖ proofHash (32 bytes))` —
95
+ * Solidity: `MessageHashUtils.toDataWithIntendedValidatorHash(address(this),
96
+ * abi.encodePacked(proofHash))` in the VerifiedFeedbackRegistry.
97
+ *
98
+ * @param params - The ServeProof hash parameters plus the validator
99
+ * @returns The final digest — sign it raw, never re-wrap it
100
+ * @throws if `validator` is missing, malformed, or the zero address
101
+ */
102
+ function buildServeProofSigningHash(params) {
103
+ if (!isUsableValidator(params.validator)) {
104
+ throw new Error(`buildServeProofSigningHash: validator must be the non-zero VerifiedFeedbackRegistry address (got ${String(params.validator)})`);
105
+ }
106
+ const messageHash = buildServeProofMessageHash(params);
107
+ return (0, viem_1.keccak256)((0, viem_1.concat)(['0x1900', params.validator, messageHash]));
108
+ }
109
+ /**
110
+ * Build a complete ServeProof object from components (without signature).
111
+ *
112
+ * Use this to construct the proof, then sign it with the agentSeal private key
113
+ * using `signServeProof`.
114
+ *
115
+ * @param params - The ServeProof parameters (without signature)
116
+ * @returns ServeProof object with empty signature
117
+ */
118
+ function buildServeProof(params) {
119
+ return {
120
+ ...params,
121
+ signature: '0x',
122
+ };
123
+ }
124
+ /**
125
+ * Sign a ServeProof using a viem account or wallet client.
126
+ *
127
+ * The hash handed to `sign` is already the final EIP-191 version 0x00 digest
128
+ * (`buildServeProofSigningHash`), so the callback must sign it raw —
129
+ * `account.sign({ hash })`. Do NOT use `signMessage({ message: { raw } })`:
130
+ * that produces the personal_sign (0x19 0x45) form, which the registry
131
+ * rejects on purpose, and the proof fails `verifyServeProofSignature`.
132
+ *
133
+ * @param params - The ServeProof parameters plus the validator (VerifiedFeedbackRegistry)
134
+ * @param sign - A function that raw-signs the final digest (e.g. `account.sign`)
135
+ * @returns The complete ServeProof with signature (and `validator`, informational)
136
+ *
137
+ * @example
138
+ * ```typescript
139
+ * import { signServeProof } from '@0gfoundation/0g-agentdna';
140
+ *
141
+ * const proof = await signServeProof(
142
+ * { chainId: 16602n, verifyingContract: '0x...', submitter: '0x...',
143
+ * agentId: 1n, timestamp: 1700000000n, deadline: 1700003600n,
144
+ * taskHash: '0x...', dataHashes: ['0x...'], frameworkHash: '0x...',
145
+ * validator: '0x...' }, // the VerifiedFeedbackRegistry proxy
146
+ * async (hash) => account.sign({ hash }),
147
+ * );
148
+ * ```
149
+ */
150
+ async function signServeProof(params, sign) {
151
+ const signingHash = buildServeProofSigningHash(params);
152
+ const signature = await sign(signingHash);
153
+ return {
154
+ agentId: params.agentId,
155
+ submitter: params.submitter,
156
+ timestamp: params.timestamp,
157
+ deadline: params.deadline,
158
+ taskHash: params.taskHash,
159
+ dataHashes: params.dataHashes,
160
+ frameworkHash: params.frameworkHash,
161
+ signature,
162
+ validator: params.validator,
163
+ };
164
+ }
165
+ /**
166
+ * Verify that a ServeProof signature matches the expected agentSeal address.
167
+ *
168
+ * The digest is domain-bound, so the caller supplies the chain id, the
169
+ * identity-registry (verifyingContract) the proof was issued against, and the
170
+ * VerifiedFeedbackRegistry (validator) it is meant for; the submitter comes
171
+ * from the proof itself. The proof's own `validator` field is NOT consulted —
172
+ * it is unsigned diagnostics; pass the registry you trust.
173
+ *
174
+ * Exactly as strict as the registry (OZ 5.0.2 `ECDSA.recover`): the signature
175
+ * must be 65 bytes with `v` ∈ {27, 28} and a low `s` (≤ secp256k1n / 2).
176
+ * A high-`s` or `v` ∈ {0, 1} encoding of an otherwise genuine signature
177
+ * recovers the same signer off chain but reverts on chain, so it is `false`
178
+ * here too — never an `ok` that the registry then refuses.
179
+ *
180
+ * @param proof - The complete ServeProof with signature
181
+ * @param expectedSigner - The agentSeal address that should have signed
182
+ * @param domain - The chainId + verifyingContract + validator the proof is bound to
183
+ * @returns True if the signature is valid for the expected signer; false for a
184
+ * missing / malformed / zero validator or a non-canonical signature encoding
185
+ */
186
+ async function verifyServeProofSignature(proof, expectedSigner, domain) {
187
+ // No usable validator → nothing to verify against. Never fall back to the
188
+ // legacy personal_sign digest.
189
+ if (!isUsableValidator(domain?.validator))
190
+ return false;
191
+ if (!isRegistryCanonicalSignature(proof.signature))
192
+ return false;
193
+ const signingHash = buildServeProofSigningHash({
194
+ chainId: domain.chainId,
195
+ verifyingContract: domain.verifyingContract,
196
+ validator: domain.validator,
197
+ submitter: proof.submitter,
198
+ agentId: proof.agentId,
199
+ timestamp: proof.timestamp,
200
+ deadline: proof.deadline,
201
+ taskHash: proof.taskHash,
202
+ dataHashes: proof.dataHashes,
203
+ frameworkHash: proof.frameworkHash,
204
+ });
205
+ // A malformed signature (bad length / invalid v) is just a failed verification,
206
+ // not an exception — a buyer verifying a hostile proof should get `false`.
207
+ let recovered;
208
+ try {
209
+ recovered = await (0, viem_1.recoverAddress)({ hash: signingHash, signature: proof.signature });
210
+ }
211
+ catch {
212
+ return false;
213
+ }
214
+ return recovered.toLowerCase() === expectedSigner.toLowerCase();
215
+ }
216
+ /** secp256k1n / 2 — OZ ECDSA rejects any `s` above it (signature malleability). */
217
+ const SECP256K1N_HALF = BigInt('0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0');
218
+ /**
219
+ * Whether `sig` is an encoding the VerifiedFeedbackRegistry accepts: 65 bytes
220
+ * (`r ‖ s ‖ v`), `v` ∈ {27, 28} (ecrecover yields no signer for anything else)
221
+ * and `s` ≤ secp256k1n / 2 (OZ `ECDSA.tryRecover` → `ECDSAInvalidSignatureS`).
222
+ */
223
+ function isRegistryCanonicalSignature(sig) {
224
+ if (typeof sig !== 'string' || !/^0x[0-9a-fA-F]{130}$/.test(sig))
225
+ return false;
226
+ const s = BigInt(`0x${sig.slice(66, 130)}`);
227
+ const v = parseInt(sig.slice(130, 132), 16);
228
+ return (v === 27 || v === 28) && s <= SECP256K1N_HALF;
229
+ }
230
+ //# sourceMappingURL=ServeProof.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ServeProof.js","sourceRoot":"","sources":["../src/ServeProof.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,180 @@
1
+ /**
2
+ * @file ServeSession.ts
3
+ * @description Consumer-side transport for reputation: call an agent's serve
4
+ * endpoint (any framework, any path) and capture the TEE-signed ServeProof the
5
+ * sealed proxy stamps on every response as the `X-Agent-Proof` header.
6
+ *
7
+ * Each agent runs its own serve endpoint — whatever HTTP API it needs; the
8
+ * protocol doesn't prescribe one, so it differs per agent. The one invariant is
9
+ * the sealed proxy in front of it, which stamps `X-Agent-Proof` on every
10
+ * response. So this layer doesn't model the call — you invoke the agent however
11
+ * it expects; ServeSession only extracts the proof from the response. The proof
12
+ * is then submittable on-chain via ReputationClient.giveFeedback (attribution is
13
+ * msg.sender; only the proof's `submitter` may redeem it).
14
+ *
15
+ * Header format (from sealed/internal/proxy):
16
+ * X-Agent-Proof: 0x<65-byte sig hex>.<base64url(envelope JSON)>
17
+ * envelope JSON = { agent_id, submitter, timestamp, deadline, task_hash,
18
+ * data_hashes[], framework_hash, validator }
19
+ * `validator` (the VerifiedFeedbackRegistry the signature is bound to) is
20
+ * diagnostics only — not part of the on-chain ServeProof tuple — and absent on
21
+ * images that predate it.
22
+ */
23
+ import { type Address, type PublicClient } from 'viem';
24
+ import { type Ctx } from './context';
25
+ import type { ServeProof, TaskReveal } from './types';
26
+ export declare const SERVE_PROOF_HEADER = "X-Agent-Proof";
27
+ /**
28
+ * Parse an `X-Agent-Proof` header value into a ServeProof ready for
29
+ * ReputationClient.giveFeedback.
30
+ */
31
+ export declare function parseServeProofHeader(value: string): ServeProof;
32
+ /**
33
+ * Extract the ServeProof from a fetch Response, or null if the agent did not
34
+ * stamp one (e.g. an unminted agent / dev mode).
35
+ */
36
+ export declare function proofFromResponse(res: {
37
+ headers: {
38
+ get(name: string): string | null;
39
+ };
40
+ }): ServeProof | null;
41
+ /** The HTTP method as it travels on the wire (see the set above). */
42
+ export declare function normalizedMethod(m?: string): string;
43
+ /** The request body bytes as they traveled, for the taskHash preimage —
44
+ * or null when the shape cannot be captured faithfully (Blob/FormData
45
+ * are async, ReadableStream would block): the caller must treat the
46
+ * whole task as unrecorded, never hash a wrong '' stand-in. */
47
+ export declare function requestBytesOf(body: unknown): Uint8Array | string | null;
48
+ /**
49
+ * A fetch-compatible wrapper for generic MCP clients: every SIGNED exchange
50
+ * it performs is recorded (proof + task) into `log`, and the Response is
51
+ * returned untouched, so an MCP SDK's streamable-HTTP transport accepts it
52
+ * as its custom fetch (the transport is passed to `client.connect()`).
53
+ * Unsigned responses are logged with `task: null` and their body is never
54
+ * read — a long-lived SSE listener would otherwise never resolve. After the
55
+ * session, verify each entry with `session.verifyProof(entry.proof, { task:
56
+ * entry.task })` — note `task: null` yields `ok: false` (fail closed), so
57
+ * skip entries whose task is null only when you know why it is.
58
+ *
59
+ * @example
60
+ * const log: Array<{ proof: ServeProof | null; task: TaskExchange | null }> = [];
61
+ * const client = new Client({ name: 'consumer', version: '1' });
62
+ * await client.connect(new StreamableHTTPClientTransport(url, {
63
+ * fetch: proofRecordingFetch(log),
64
+ * }));
65
+ * // … run the MCP session …
66
+ * for (const e of log) if (e.proof) {
67
+ * const v = await session.verifyProof(e.proof, { task: e.task });
68
+ * if (!v.ok || !v.taskMatches) throw new Error('unverified MCP exchange');
69
+ * }
70
+ */
71
+ export declare function proofRecordingFetch(log: Array<{
72
+ proof: ServeProof | null;
73
+ task: TaskExchange | null;
74
+ }>): typeof fetch;
75
+ /**
76
+ * Build the TaskReveal(s) for an exchange you actually sent and received —
77
+ * the input to `verifyProof(proof, { task })`'s per-exchange binding. The
78
+ * proxy hashed one specific URI form; undici (Node fetch) and browsers
79
+ * differ on a bare trailing '?', so one reveal per requestUriCandidates
80
+ * form is returned and the comparison tries each.
81
+ *
82
+ * The bytes are hashed exactly as they traveled: pass the raw request body
83
+ * string/bytes and the raw response body (NOT a re-serialized JSON —
84
+ * key order and whitespace change the hash).
85
+ */
86
+ export declare function taskRevealOf(exchange: TaskExchange): TaskReveal[];
87
+ /**
88
+ * Run an agent call (yielding a Response) and capture its ServeProof.
89
+ * You still consume the body yourself (`response.json()` etc.).
90
+ *
91
+ * @example
92
+ * const { response, proof } = await captureProof(() =>
93
+ * fetch(`${agentUrl}/chat`, { method: 'POST', body }));
94
+ * const data = await response.json();
95
+ * if (proof) await rep.giveFeedback({ ...feedback, serveProof: proof });
96
+ */
97
+ export declare function captureProof(call: () => Promise<Response>): Promise<{
98
+ response: Response;
99
+ proof: ServeProof | null;
100
+ }>;
101
+ /** Result of a local ServeProof pre-check (before spending gas on-chain). */
102
+ export interface ProofVerification {
103
+ ok: boolean;
104
+ signerMatches: boolean;
105
+ notExpired: boolean;
106
+ dataOnChain: boolean;
107
+ /** False when no VerifiedFeedbackRegistry is configured, or the proof's
108
+ * envelope names a different one. The signature is then not checked
109
+ * (`signerMatches` is false too) — a configuration mismatch, not
110
+ * necessarily a bad proof. */
111
+ registryMatches: boolean;
112
+ /** null when no task was passed to verifyProof (the call means signer
113
+ * attribution only). With a task: whether the proof's taskHash equals
114
+ * the hash recomputed from that task — binding the proof to THIS
115
+ * exchange's method, URI, request body, response body and status, not
116
+ * just to the signer. Required for `ok` when a task is passed. */
117
+ taskMatches: boolean | null;
118
+ reasons: string[];
119
+ }
120
+ /** The exchange a proof's taskHash commits to, in caller-friendly form: what
121
+ * you actually sent and received. Turned into TaskReveal(s) by
122
+ * taskRevealOf (the URI the proxy hashed is not always knowable in
123
+ * advance, so each requestUriCandidates form gets one). */
124
+ export interface TaskExchange {
125
+ method: string;
126
+ /** The full request URL — only its path+query feed the hash, but the
127
+ * candidates are derived from the whole URL. */
128
+ url: string | URL;
129
+ /** Raw request body bytes/string as sent ('' for none). */
130
+ requestBytes?: Uint8Array | string;
131
+ /** Raw response body bytes/string as received. */
132
+ responseBytes: Uint8Array | string;
133
+ status: number;
134
+ }
135
+ export interface ServeSessionOptions {
136
+ /** Seconds of clock skew tolerated when checking the deadline. Default 0. */
137
+ clockSkew?: number;
138
+ /** Current unix time (seconds); injectable for testing. */
139
+ now?: () => number;
140
+ }
141
+ /**
142
+ * Chain-aware helper to validate a captured ServeProof before submitting — so a
143
+ * stale or mismatched proof is caught locally rather than by an on-chain revert.
144
+ */
145
+ export declare class ServeSession {
146
+ readonly publicClient: PublicClient;
147
+ readonly agenticID: Address;
148
+ /** The VerifiedFeedbackRegistry proxy — the intended validator every
149
+ * serve-proof signature is bound to. Zero = not configured. */
150
+ readonly verifiedFeedback: Address;
151
+ private readonly clockSkew;
152
+ private readonly now;
153
+ constructor(ctx: Ctx, options?: ServeSessionOptions);
154
+ /**
155
+ * Verify a proof against chain state: signer == on-chain agentSeal (over the
156
+ * digest bound to the configured VerifiedFeedbackRegistry), deadline not
157
+ * passed, and every declared dataHash is present in the agent's on-chain
158
+ * iData (so the buyer knows what the agent was running).
159
+ *
160
+ * Needs `addresses.verifiedFeedback` (fromAttestor fills it): without it
161
+ * nothing can be verified and `signerMatches` / `registryMatches` are false.
162
+ */
163
+ /**
164
+ * Verify a proof against chain state. Without `opts.task` the verdict is
165
+ * signer attribution: the proof was signed by this agent's on-chain
166
+ * agentSeal, in time, over data the chain knows. With `opts.task` (a
167
+ * TaskReveal, or the TaskExchange you actually sent/received) the verdict
168
+ * additionally binds the proof to THAT exchange: `taskMatches` recomputes
169
+ * taskHash = keccak(method ‖ uri ‖ keccak(reqBody) ‖ keccak(respBody) ‖
170
+ * status) from your bytes and compares it to the proof's commitment — a
171
+ * genuine proof attached to a different response body yields
172
+ * `taskMatches: false` and `ok: false`. An explicit `task: null` (what
173
+ * the recorders return when the exchange wasn't captured) fails closed:
174
+ * `ok: false`, never a silent fall-back to signer-only.
175
+ */
176
+ verifyProof(proof: ServeProof, opts?: {
177
+ task?: TaskReveal | TaskExchange | null;
178
+ }): Promise<ProofVerification>;
179
+ }
180
+ //# sourceMappingURL=ServeSession.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ServeSession.d.ts","sourceRoot":"","sources":["../src/ServeSession.ts"],"names":[],"mappings":"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"}