inamprotocol 0.3.0 → 0.3.1

package/README.md

@@ -40,9 +40,39 @@ const receipt = await worker.submitWork(poster.did, {
 await poster.acceptWork(receipt); // finalizes the receipt and auto-completes the job
 ```
 
+`poster.cancelJob(job.jobId)` cancels a not-yet-completed job (poster only); `client.getJob(id)` / `client.searchJobs({ capability, status })` / `client.listOffers(jobId)` round out discovery.
+
+### External identity linking (challenge-response)
+
+Linking a key-derived external identity (`agentpass_id` / `aitp_id` / `passport_id`; SPEC.md §2.1) requires proving control of that external key via a single-use, ~60s challenge — a bare claim is no longer enough. `a2a_endpoint` isn't key-derived, so it skips straight to `linkIdentity(protocol, value)`.
+
+```ts
+// externalKeypair stands in for whatever key AgentPass/AITP/Passport Alliance
+// already issued this agent -- not an INAM keypair.
+const challenge = await client.requestLinkChallenge("agentpass_id", toBase64(externalKeypair.publicKey), "ed25519");
+const proof = toBase64(sign(fromHex(challenge.challenge), externalKeypair.privateKey));
+await client.completeLink("agentpass_id", "ap_my_external_id", challenge.challengeId, proof);
+```
+
+### Verification (independent attestation)
+
+A third party — anyone but the receipt's own worker (`agentB`) — can attest that a finalized receipt's output actually holds up (SPEC.md §12), feeding a reputation boost:
+
+```ts
+const verification = await verifierClient.submitVerification({
+  receiptId: receipt.receiptId,
+  method: "deterministic", // or "agent_attestation"
+  outputHash: receipt.result.outputHash,
+  result: "verified", // or "rejected"
+});
+
+await verifierClient.getVerification(verification.verificationId);
+await verifierClient.listReceiptVerifications(receipt.receiptId);
+```
+
 ## What's exported
 
-`InamClient`, `generateKeypair`/`keypairFromPrivateKey`/`publicKeyToDid`/`didToPublicKey`/`sign`/`verify`/`sha256Hex`, `canonicalize` (the canonical-JSON serializer every INAM signature is computed over), `computeReceiptId`/`buildSignableContent`, and the full set of wire-format types (`AgentRecord`, `ExecutionReceipt`, `JobRecord`, `JobOffer`, `ReputationResult`, ...).
+`InamClient`, `generateKeypair`/`keypairFromPrivateKey`/`publicKeyToDid`/`didToPublicKey`/`sign`/`verify`/`verifyRawEd25519`/`sha256Hex`, `generateP256Keypair`/`p256Sign`/`p256Verify` (used for external-identity link-challenge proofs, SPEC.md §2.1), `canonicalize` (the canonical-JSON serializer every INAM signature is computed over), `computeReceiptId`/`buildSignableContent`, `computeVerificationId`/`buildSignableVerificationContent`, and the full set of wire-format types (`AgentRecord`, `ExecutionReceipt`, `JobRecord`, `JobOffer`, `ReputationResult`, `LinkChallenge`, `VerificationRecord`, ...).
 
 ## Building from source
 

package/dist/crypto/canonical.d.ts

@@ -4,5 +4,16 @@
  * not handle every JCS number-formatting edge case, but it is deterministic
  * for the plain string/number/boolean/array/object shapes used by Inam Protocol's own
  * schemas, which is all that's required for our signer and verifier to agree.
+ *
+ * Number formatting here (via native `JSON.stringify`) already follows the
+ * ECMA-262 `Number::toString` algorithm, which is what
+ * sdk-python/inamprotocol/canonical.py's `_format_number` was written to
+ * replicate byte-for-byte after a real cross-language signature failure
+ * (`score: 1.0` verified in Python, rejected here, because Python's own
+ * `json.dumps` renders it "1.0" where this renders it "1"). One gap native
+ * `JSON.stringify` has that Python's fix doesn't: `JSON.stringify(NaN)` and
+ * `JSON.stringify(Infinity)` both silently produce the string `"null"`
+ * rather than erroring, which would corrupt a signature without any error on
+ * either side — guarded against explicitly below.
  */
 export declare function canonicalize(value: unknown): string;

package/dist/crypto/canonical.js

@@ -4,11 +4,25 @@
  * not handle every JCS number-formatting edge case, but it is deterministic
  * for the plain string/number/boolean/array/object shapes used by Inam Protocol's own
  * schemas, which is all that's required for our signer and verifier to agree.
+ *
+ * Number formatting here (via native `JSON.stringify`) already follows the
+ * ECMA-262 `Number::toString` algorithm, which is what
+ * sdk-python/inamprotocol/canonical.py's `_format_number` was written to
+ * replicate byte-for-byte after a real cross-language signature failure
+ * (`score: 1.0` verified in Python, rejected here, because Python's own
+ * `json.dumps` renders it "1.0" where this renders it "1"). One gap native
+ * `JSON.stringify` has that Python's fix doesn't: `JSON.stringify(NaN)` and
+ * `JSON.stringify(Infinity)` both silently produce the string `"null"`
+ * rather than erroring, which would corrupt a signature without any error on
+ * either side — guarded against explicitly below.
  */
 export function canonicalize(value) {
     return stringify(value);
 }
 function stringify(value) {
+    if (typeof value === "number" && !Number.isFinite(value)) {
+        throw new Error(`Cannot canonicalize non-finite number: ${value}`);
+    }
     if (value === null || typeof value !== "object") {
         return JSON.stringify(value);
     }

package/dist/crypto/canonical.js.map

@@ -1 +1 @@
-{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../../src/crypto/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACpD,CAAC;IACD,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACrC,MAAM,OAAO,GAAG,IAAI;SACjB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC;SACnC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,OAAO,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;AACvC,CAAC"}
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../../src/crypto/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACzD,MAAM,IAAI,KAAK,CAAC,0CAA0C,KAAK,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACpD,CAAC;IACD,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACrC,MAAM,OAAO,GAAG,IAAI;SACjB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC;SACnC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,OAAO,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;AACvC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inamprotocol",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Reference TypeScript/JavaScript SDK for the INAM Protocol — agent identity, execution receipts, jobs, and reputation",
   "type": "module",
   "main": "./dist/index.js",
@@ -46,6 +46,7 @@
     "bs58": "^6.0.0"
   },
   "devDependencies": {
+    "@types/node": "^22.5.0",
     "typescript": "^5.5.4"
   }
 }