inamprotocol 0.15.0 → 0.16.0

package/README.md

@@ -70,6 +70,22 @@ await verifierClient.getVerification(verification.verificationId);
 await verifierClient.listReceiptVerifications(receipt.receiptId);
 ```
 
+### Deciding whether to deal with an agent
+
+`checkTrust` turns an agent's reputation into `allow`, `escrow` (deal, but hold payment until delivery is confirmed), or `deny`, with the reasons. It runs on your side: the registry's numbers are a hint (SPEC.md §5.4), and the thresholds are yours.
+
+```ts
+import { checkTrust } from "inamprotocol";
+
+const d = await checkTrust(did, client, {
+  allow: { minEvidence: "independently_verified", minTrustScore: 5 }, // default: independently_verified, any score
+  escrow: { minEvidence: "none" },                                     // below this: deny
+});
+// { decision: "escrow", reasons: ["evidence countersigned is below independently_verified"], ... }
+```
+
+A revoked ID or one the registry doesn't know is `deny`. Warning flags (`in_dispute`, `attestation_rejected`, `nonperformance_reported`, `concentrated_counterparty`) cap the decision at `escrow`; pass `escrowFlags` to change that list. Use it to fill a wallet's merchant allow list, or to choose between paying upfront and paying on delivery.
+
 ## What's exported
 
 `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`, ...).

package/dist/index.d.ts

@@ -15,3 +15,5 @@ export { INAM_X402_EXTENSION, inamX402Extension, decideX402, withInamX402Gate, X
 export type { X402Policy, X402Decision } from "./x402.js";
 export { INAM_A2A_EXTENSION_URI, inamA2AExtension, decideA2A, verifyA2ACard, cardEndpoints } from "./a2a.js";
 export type { A2APolicy, A2ADecision, A2AAgentCardLike } from "./a2a.js";
+export { decideTrust, checkTrust, DEFAULT_ESCROW_FLAGS } from "./trust.js";
+export type { TrustPolicy, TrustDecision, TrustDecisionKind } from "./trust.js";

package/dist/index.js

@@ -22,4 +22,5 @@ export { payloadHash } from "./core/transparencyLog.js";
 export { registerAgentSchema, linkChallengeSchema, linkSchema, postJobSchema, offerSchema, acceptOfferSchema, draftReceiptSchema, countersignSchema, disputeSchema, submitVerificationSchema, setVerifierStatusSchema, } from "./core/schemas.js";
 export { INAM_X402_EXTENSION, inamX402Extension, decideX402, withInamX402Gate, X402PaymentBlocked } from "./x402.js";
 export { INAM_A2A_EXTENSION_URI, inamA2AExtension, decideA2A, verifyA2ACard, cardEndpoints } from "./a2a.js";
+export { decideTrust, checkTrust, DEFAULT_ESCROW_FLAGS } from "./trust.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,IAAI,EACJ,MAAM,EACN,gBAAgB,EAChB,SAAS,EACT,QAAQ,EACR,UAAU,EACV,KAAK,EACL,OAAO,GAER,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,UAAU,EAAoB,MAAM,kBAAkB,CAAC;AAE/F,OAAO,EACL,wBAAwB,EACxB,aAAa,EACb,eAAe,EACf,mCAAmC,EACnC,qBAAqB,GAEtB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAErD,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAA4B,MAAM,0BAA0B,CAAC;AAE5G,qEAAqE;AACrE,yEAAyE;AACzE,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAExF,OAAO,EAAE,qBAAqB,EAAE,gCAAgC,EAAiC,MAAM,+BAA+B,CAAC;AAEvI,2EAA2E;AAC3E,0EAA0E;AAC1E,sEAAsE;AACtE,0CAA0C;AAC1C,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAA8B,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGpF,4EAA4E;AAC5E,2EAA2E;AAC3E,sEAAsE;AACtE,wEAAwE;AACxE,oEAAoE;AACpE,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,UAAU,EACV,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAuB3B,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,UAAU,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAErH,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,SAAS,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,IAAI,EACJ,MAAM,EACN,gBAAgB,EAChB,SAAS,EACT,QAAQ,EACR,UAAU,EACV,KAAK,EACL,OAAO,GAER,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,UAAU,EAAoB,MAAM,kBAAkB,CAAC;AAE/F,OAAO,EACL,wBAAwB,EACxB,aAAa,EACb,eAAe,EACf,mCAAmC,EACnC,qBAAqB,GAEtB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAErD,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAA4B,MAAM,0BAA0B,CAAC;AAE5G,qEAAqE;AACrE,yEAAyE;AACzE,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAExF,OAAO,EAAE,qBAAqB,EAAE,gCAAgC,EAAiC,MAAM,+BAA+B,CAAC;AAEvI,2EAA2E;AAC3E,0EAA0E;AAC1E,sEAAsE;AACtE,0CAA0C;AAC1C,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAA8B,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGpF,4EAA4E;AAC5E,2EAA2E;AAC3E,sEAAsE;AACtE,wEAAwE;AACxE,oEAAoE;AACpE,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,UAAU,EACV,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAuB3B,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,UAAU,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAErH,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,SAAS,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE7G,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC"}

package/dist/trust.d.ts

@@ -0,0 +1,29 @@
+import type { InamClient } from "./client.js";
+import type { AgentRecord, ReputationResult } from "./types.js";
+import { type X402Policy } from "./x402.js";
+/** A decision-ready trust check: allow, escrow, or deny, with the reasons.
+ *
+ * Runs on the caller's side from the registry's appraisal, which is a hint
+ * (SPEC.md §5.4); the registry never decides for you. "escrow" means: deal,
+ * but don't release payment until delivery is confirmed. INAM holds no money,
+ * so the escrow itself is the caller's rail (x402, a wallet allow list, etc.). */
+export type TrustDecisionKind = "allow" | "escrow" | "deny";
+export interface TrustPolicy {
+    /** Bar for "allow". Default: independently verified evidence, any score. Countersigned-only history is the two parties' own word (THREAT-MODEL.md), so by default it gets escrow. */
+    allow?: X402Policy;
+    /** Bar for "escrow"; below it is "deny". Default: no evidence needed, so unknown agents get escrow. */
+    escrow?: X402Policy;
+    /** Reputation flags that cap the decision at "escrow" (prefix match, so `concentrated_counterparty` matches its `:did` suffix). */
+    escrowFlags?: string[];
+}
+export interface TrustDecision {
+    decision: TrustDecisionKind;
+    reasons: string[];
+    did: string;
+    reputation?: ReputationResult;
+}
+export declare const DEFAULT_ESCROW_FLAGS: string[];
+/** Pure policy check, for callers that already fetched the agent and its reputation. */
+export declare function decideTrust(agent: AgentRecord, reputation: ReputationResult, policy?: TrustPolicy): TrustDecision;
+/** Fetches `did` from the registry `inam` points at and decides. An ID the registry doesn't know is "deny". */
+export declare function checkTrust(did: string, inam: InamClient, policy?: TrustPolicy): Promise<TrustDecision>;

package/dist/trust.js

@@ -0,0 +1,34 @@
+import { policyFailure } from "./x402.js";
+export const DEFAULT_ESCROW_FLAGS = ["in_dispute", "attestation_rejected", "nonperformance_reported", "concentrated_counterparty"];
+/** Pure policy check, for callers that already fetched the agent and its reputation. */
+export function decideTrust(agent, reputation, policy = {}) {
+    const base = { did: agent.id, reputation };
+    if (agent.revokedAt)
+        return { ...base, decision: "deny", reasons: ["INAM ID is revoked"] };
+    const escrowMiss = policyFailure(reputation, { minEvidence: "none", ...policy.escrow });
+    if (escrowMiss)
+        return { ...base, decision: "deny", reasons: [escrowMiss] };
+    const reasons = [];
+    const allowMiss = policyFailure(reputation, { minEvidence: "independently_verified", ...policy.allow });
+    if (allowMiss)
+        reasons.push(allowMiss);
+    const watch = policy.escrowFlags ?? DEFAULT_ESCROW_FLAGS;
+    for (const f of reputation.flags ?? [])
+        if (watch.some((w) => f === w || f.startsWith(`${w}:`)))
+            reasons.push(`flag ${f}`);
+    if (reasons.length)
+        return { ...base, decision: "escrow", reasons };
+    return { ...base, decision: "allow", reasons: [`evidence ${reputation.evidenceLevel}, trustScore ${reputation.trustScore}`] };
+}
+/** Fetches `did` from the registry `inam` points at and decides. An ID the registry doesn't know is "deny". */
+export async function checkTrust(did, inam, policy = {}) {
+    let agent, reputation;
+    try {
+        [agent, reputation] = await Promise.all([inam.getAgent(did), inam.getReputation(did)]);
+    }
+    catch {
+        return { did, decision: "deny", reasons: ["INAM ID not found in the registry"] };
+    }
+    return decideTrust(agent, reputation, policy);
+}
+//# sourceMappingURL=trust.js.map

package/dist/trust.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust.js","sourceRoot":"","sources":["../src/trust.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAmB,MAAM,WAAW,CAAC;AA2B3D,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,YAAY,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,2BAA2B,CAAC,CAAC;AAEnI,wFAAwF;AACxF,MAAM,UAAU,WAAW,CAAC,KAAkB,EAAE,UAA4B,EAAE,SAAsB,EAAE;IACpG,MAAM,IAAI,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,UAAU,EAAE,CAAC;IAC3C,IAAI,KAAK,CAAC,SAAS;QAAE,OAAO,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,oBAAoB,CAAC,EAAE,CAAC;IAE3F,MAAM,UAAU,GAAG,aAAa,CAAC,UAAU,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACxF,IAAI,UAAU;QAAE,OAAO,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC;IAE5E,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,SAAS,GAAG,aAAa,CAAC,UAAU,EAAE,EAAE,WAAW,EAAE,wBAAwB,EAAE,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IACxG,IAAI,SAAS;QAAE,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,IAAI,oBAAoB,CAAC;IACzD,KAAK,MAAM,CAAC,IAAI,UAAU,CAAC,KAAK,IAAI,EAAE;QAAE,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAE3H,IAAI,OAAO,CAAC,MAAM;QAAE,OAAO,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpE,OAAO,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,YAAY,UAAU,CAAC,aAAa,gBAAgB,UAAU,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC;AAChI,CAAC;AAED,+GAA+G;AAC/G,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAAW,EAAE,IAAgB,EAAE,SAAsB,EAAE;IACtF,IAAI,KAAkB,EAAE,UAA4B,CAAC;IACrD,IAAI,CAAC;QACH,CAAC,KAAK,EAAE,UAAU,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACzF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,mCAAmC,CAAC,EAAE,CAAC;IACnF,CAAC;IACD,OAAO,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;AAChD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inamprotocol",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Reference TypeScript/JavaScript SDK for the INAM Protocol — agent identity, execution receipts, jobs, and reputation",
   "type": "module",
   "main": "./dist/index.js",