inamprotocol 0.19.0 → 0.21.0

package/README.md

@@ -10,6 +10,48 @@ This package is a standalone build of the same crypto/client code the [Node refe
 npm install inamprotocol
 ```
 
+## inam check before you pay
+
+One command, no key, no INAM account, and useful even when nobody involved uses INAM:
+
+```
+npx inamprotocol check https://x402.coinstats.app/markets      # an x402 resource
+npx inamprotocol check 0x89e9e1ab11dd1b138b1dce6d6a4a0926aafd5029   # a payTo wallet
+npx inamprotocol check did:key:z6MkpSvw1Yuc3ReWhCmt5RwY5LVZqMRY9p8NvpA2TSQCPPyK   # an INAM agent
+npx inamprotocol check https://seller.example/api --method POST --json
+```
+
+```
+inam check https://x402.coinstats.app/markets
+
+  verdict  CAUTION  nothing failed, but some signals are missing; read the [warn] lines before paying
+
+  payment requirements
+    resource  https://x402.coinstats.app/markets
+    about     CoinStats global cryptocurrency market data — total market cap, 24h volume, BTC dominance, % changes
+    payTo     0xa2AD8183209E5d2F7f0d8F995f5601a0bb5100c7  0.001 USD Coin on Base (eip155:8453)
+
+  checks
+    [ ok ] HTTPS, certificate accepted
+    [ ok ] 402 with 1 payment option (x402 v2)
+    [warn] No ERC-8004 identity owned by 0xa2AD81…00c7 (on-chain on Base: 0)
+    [warn] 0xa2AD81…00c7 is not linked to any INAM ID
+    [info] No Web Bot Auth key directory (HTTP 404)
+    [ ok ] coinstats.app registered 2018-05-08 (3076 days ago)
+```
+
+What it checks:
+
+| Target | Signals |
+| --- | --- |
+| x402 URL | Fetches it without paying and parses the 402 (v2 `PAYMENT-REQUIRED` header or v1 body): payTo, network, asset, amount, resource, description. Then, per EVM payTo, everything a wallet gets. Plus: the `inam` extension's ID must have proven that payTo (else FAIL), HTTPS, a Web Bot Auth key directory at `/.well-known/http-message-signatures-directory` (signature verified), and the domain's RDAP registration date (shared hosts like `*.workers.dev` are labelled as such). |
+| `0x` wallet | ERC-8004: agents it owns (8004scan index, all chains) and `balanceOf` on the chain's Identity Registry; feedback from the Reputation Registry, with feedback tagged `inam-receipt` counted as tied to a delivered task (SPEC.md §11.1). INAM: whether an INAM ID proved control of the wallet, and that ID's receipts and evidence level. |
+| `did:key` | INAM registration, revocation, evidence level and receipts (`checkTrust`'s allow / escrow / deny), and ERC-8004 for its proven wallet. |
+
+The verdict is the worst line, not a score: `FAIL` (exit 1) when a key check fails, such as no 402, unreadable payment requirements, plain http, an unknown or revoked ID, or a borrowed INAM ID whose proven wallet is not the payTo. `CAUTION` (exit 0, exit 1 with `--strict`) when signals are missing. `PASS` otherwise. Exit 2 on bad usage.
+
+Use it as a gate before paying or in CI: `npx inamprotocol check "$URL" --strict || exit 1`. Programmatic use: `checkTarget(target, opts)` returns the same report (`formatReport(report)` prints it). On-chain reads use keyless public RPCs (Ethereum, Base, Base Sepolia); set `INAM_RPC_<chainId>` to use your own. `npx inam check` also works once `inamprotocol` is installed in the project or globally; without it, `npx inam` would fetch an unrelated package of that name.
+
 ## Usage
 
 ```ts
@@ -118,6 +160,24 @@ await inam.settle(); // countersigns run in the background; wait before a server
 
 The requester only countersigns when the receipt's hashes match the exact request it sent and response it received. That confirms delivery, not quality; pass `accept: (res, receipt) => ...` to `inamFetch` to run your own check first.
 
+### Web Bot Auth (signed agent requests)
+
+Origins behind Cloudflare can recognize your agent by signature instead of User-Agent or IP. Opt in on `inamFetch`, and every request is signed with the agent's own Ed25519 key (HTTP Message Signatures, RFC 9421, Web Bot Auth profile):
+
+```ts
+const inam = inamFetch(client, { webBotAuth: { signatureAgent: "https://agent.example" } });
+```
+
+`signatureAgent` is the https origin that serves your key directory. Serve it from there:
+
+```ts
+// GET https://agent.example/.well-known/http-message-signatures-directory
+const { body, headers } = client.webBotAuthDirectory(new URL(req.url).host);
+return new Response(body, { headers });
+```
+
+Signatures expire after 60 seconds (`expiresIn` to change). `Signature-Agent` uses the structured-string form Cloudflare accepts. Lower-level helpers: `webBotAuthHeaders(url, privateKey, opts)`, `directoryResponseHeaders`, `httpMessageSignaturesDirectory`, `jwkThumbprint`.
+
 ## Vercel AI SDK tools
 
 ```ts

package/dist/aiSdk.d.ts

@@ -509,19 +509,19 @@ export declare function inamTools(options?: {
             };
             output: NoInfer<{
                 receipt: import("./types.js").ExecutionReceipt;
-                verifications: import("./types.js").VerificationRecord[] | never[];
+                verifications: never[] | import("./types.js").VerificationRecord[];
             }>;
         }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
     } & {
         outputSchema?: import("ai").FlexibleSchema<{
             receipt: import("./types.js").ExecutionReceipt;
-            verifications: import("./types.js").VerificationRecord[] | never[];
+            verifications: never[] | import("./types.js").VerificationRecord[];
         }> | undefined;
         execute: import("ai").ToolExecuteFunction<{
             receiptId: string;
         }, {
             receipt: import("./types.js").ExecutionReceipt;
-            verifications: import("./types.js").VerificationRecord[] | never[];
+            verifications: never[] | import("./types.js").VerificationRecord[];
         }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
     } & {
         description?: string | ((options: {
@@ -545,7 +545,7 @@ export declare function inamTools(options?: {
             receiptId: string;
         }, {
             receipt: import("./types.js").ExecutionReceipt;
-            verifications: import("./types.js").VerificationRecord[] | never[];
+            verifications: never[] | import("./types.js").VerificationRecord[];
         }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
     }) | ({
         deferLoading?: boolean;
@@ -575,19 +575,19 @@ export declare function inamTools(options?: {
             };
             output: NoInfer<{
                 receipt: import("./types.js").ExecutionReceipt;
-                verifications: import("./types.js").VerificationRecord[] | never[];
+                verifications: never[] | import("./types.js").VerificationRecord[];
             }>;
         }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
     } & {
         outputSchema?: import("ai").FlexibleSchema<{
             receipt: import("./types.js").ExecutionReceipt;
-            verifications: import("./types.js").VerificationRecord[] | never[];
+            verifications: never[] | import("./types.js").VerificationRecord[];
         }> | undefined;
         execute: import("ai").ToolExecuteFunction<{
             receiptId: string;
         }, {
             receipt: import("./types.js").ExecutionReceipt;
-            verifications: import("./types.js").VerificationRecord[] | never[];
+            verifications: never[] | import("./types.js").VerificationRecord[];
         }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
     } & {
         description?: string | ((options: {
@@ -611,7 +611,7 @@ export declare function inamTools(options?: {
             receiptId: string;
         }, {
             receipt: import("./types.js").ExecutionReceipt;
-            verifications: import("./types.js").VerificationRecord[] | never[];
+            verifications: never[] | import("./types.js").VerificationRecord[];
         }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
     }) | ({
         deferLoading?: boolean;
@@ -641,19 +641,19 @@ export declare function inamTools(options?: {
             };
             output: NoInfer<{
                 receipt: import("./types.js").ExecutionReceipt;
-                verifications: import("./types.js").VerificationRecord[] | never[];
+                verifications: never[] | import("./types.js").VerificationRecord[];
             }>;
         }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
     } & {
         outputSchema?: import("ai").FlexibleSchema<{
             receipt: import("./types.js").ExecutionReceipt;
-            verifications: import("./types.js").VerificationRecord[] | never[];
+            verifications: never[] | import("./types.js").VerificationRecord[];
         }> | undefined;
         execute: import("ai").ToolExecuteFunction<{
             receiptId: string;
         }, {
             receipt: import("./types.js").ExecutionReceipt;
-            verifications: import("./types.js").VerificationRecord[] | never[];
+            verifications: never[] | import("./types.js").VerificationRecord[];
         }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
     } & {
         type: "provider";
@@ -670,7 +670,7 @@ export declare function inamTools(options?: {
             receiptId: string;
         }, {
             receipt: import("./types.js").ExecutionReceipt;
-            verifications: import("./types.js").VerificationRecord[] | never[];
+            verifications: never[] | import("./types.js").VerificationRecord[];
         }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
     }) | ({
         deferLoading?: boolean;
@@ -700,19 +700,19 @@ export declare function inamTools(options?: {
             };
             output: NoInfer<{
                 receipt: import("./types.js").ExecutionReceipt;
-                verifications: import("./types.js").VerificationRecord[] | never[];
+                verifications: never[] | import("./types.js").VerificationRecord[];
             }>;
         }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
     } & {
         outputSchema?: import("ai").FlexibleSchema<{
             receipt: import("./types.js").ExecutionReceipt;
-            verifications: import("./types.js").VerificationRecord[] | never[];
+            verifications: never[] | import("./types.js").VerificationRecord[];
         }> | undefined;
         execute: import("ai").ToolExecuteFunction<{
             receiptId: string;
         }, {
             receipt: import("./types.js").ExecutionReceipt;
-            verifications: import("./types.js").VerificationRecord[] | never[];
+            verifications: never[] | import("./types.js").VerificationRecord[];
         }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
     } & {
         type: "provider";
@@ -729,7 +729,7 @@ export declare function inamTools(options?: {
             receiptId: string;
         }, {
             receipt: import("./types.js").ExecutionReceipt;
-            verifications: import("./types.js").VerificationRecord[] | never[];
+            verifications: never[] | import("./types.js").VerificationRecord[];
         }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
     });
 };

package/dist/check.d.ts

@@ -0,0 +1,115 @@
+/** `inam check <url | 0x wallet | did:key>`: a pre-payment check built from public signals.
+ *
+ * Useful with no INAM data at all: it reads the x402 402 response, asks ERC-8004 (on-chain
+ * through a public RPC, plus the 8004scan indexer for the reverse lookup by owner), looks for a
+ * Web Bot Auth key directory and the domain's RDAP registration date, and adds INAM's wallet
+ * link and receipts when they exist. It reports what it found, not a score. */
+export type CheckStatus = "pass" | "warn" | "fail" | "info";
+export interface CheckItem {
+    id: string;
+    status: CheckStatus;
+    label: string;
+    detail?: string;
+}
+export interface PaymentOption {
+    scheme?: string;
+    network: string;
+    chainId: number | null;
+    asset?: string;
+    amount?: string;
+    /** Human price when the asset is a known 6-decimal USD stablecoin. */
+    price?: string;
+    payTo: string;
+    testnet: boolean;
+}
+export interface CheckReport {
+    target: string;
+    kind: "url" | "wallet" | "did";
+    /** Worst status among the checks: any fail is "fail", any warn is "caution". */
+    verdict: "pass" | "caution" | "fail";
+    checkedAt: string;
+    payment?: {
+        x402Version?: number;
+        status: number;
+        resource?: string;
+        description?: string;
+        accepts: PaymentOption[];
+        inamDid?: string;
+    };
+    checks: CheckItem[];
+}
+export interface CheckOptions {
+    registryUrl?: string;
+    /** ERC-8004 indexer used for the reverse lookup by owner (no on-chain index exists). */
+    indexerUrl?: string;
+    /** chainId -> JSON-RPC URL; merged over the public defaults. */
+    rpc?: Record<number, string>;
+    method?: string;
+    timeoutMs?: number;
+    /** wallet (lowercase) -> INAM ID, if the caller already listed linked agents (the bulk scan does). */
+    linkedWallets?: Map<string, string>;
+    /** Skip the RDAP domain-age lookup. */
+    noRdap?: boolean;
+    /** Retries after HTTP 429 from the indexer and RDAP (default 1). The bulk scan raises it. */
+    retries?: number;
+}
+export declare const ERC8004: {
+    identity: {
+        mainnet: string;
+        testnet: string;
+    };
+    reputation: {
+        mainnet: string;
+        testnet: string;
+    };
+};
+/** Keyless public RPCs. Other chains are covered by the indexer only, or by `rpc` / INAM_RPC_<chainId>. */
+export declare const DEFAULT_RPC: Record<number, string>;
+export declare const SHARED_HOSTING: RegExp;
+export declare const isEvmAddress: (a: string) => boolean;
+export declare const chainIdOf: (network: string) => number | null;
+/** Payment requirements from a 402: the v2 PAYMENT-REQUIRED header, or the v1 JSON body. */
+export declare function parsePaymentRequired(headers: Headers, body: string): any | null;
+export declare function paymentOptions(required: any): PaymentOption[];
+export declare function erc8004Balance(rpc: string, chainId: number, wallet: string, timeoutMs?: number): Promise<number>;
+/** Feedback on one agent from the Reputation Registry: all of it, and the part tagged as INAM-receipt-backed (SPEC.md §11.1). */
+export declare function erc8004Feedback(rpc: string, chainId: number, agentId: number, timeoutMs?: number): Promise<{
+    total: number;
+    receiptBacked: number;
+}>;
+export interface Erc8004Agent {
+    chainId: number;
+    agentId: number;
+    name?: string;
+    feedbacks: number;
+    testnet: boolean;
+}
+/** Agents a wallet owns, from the indexer (on-chain ERC-721 has no enumeration by owner). */
+export declare function erc8004AgentsByOwner(indexerUrl: string, wallet: string, timeoutMs?: number, retries?: number): Promise<Erc8004Agent[]>;
+export interface WalletErc8004 {
+    agents: Erc8004Agent[] | null;
+    onchain: {
+        chainId: number;
+        balance: number;
+    } | null;
+    feedback: {
+        total: number;
+        receiptBacked: number;
+        source: "onchain" | "indexer";
+    } | null;
+    errors: string[];
+}
+export declare function walletErc8004(wallet: string, chainId: number | null, opts?: CheckOptions): Promise<WalletErc8004>;
+/** Every INAM agent with a proven EVM wallet (`linked.erc8004_id`), keyed by lowercase wallet. The registry has no lookup by wallet. */
+export declare function inamLinkedWallets(registryUrl?: string, timeoutMs?: number): Promise<Map<string, string>>;
+export declare function directoryItem(origin: string, timeoutMs?: number): Promise<CheckItem>;
+/** Last two labels, or three under a two-letter ccTLD's co/com/org/net/ac/gov/edu. */
+export declare function registrableDomain(host: string): string;
+export declare function domainItem(host: string, timeoutMs?: number, retries?: number): Promise<CheckItem>;
+export declare function checkWallet(wallet: string, opts?: CheckOptions & {
+    chainId?: number | null;
+}): Promise<CheckReport>;
+export declare function checkDid(did: string, opts?: CheckOptions): Promise<CheckReport>;
+export declare function checkUrl(url: string, opts?: CheckOptions): Promise<CheckReport>;
+export declare function checkTarget(target: string, opts?: CheckOptions): Promise<CheckReport>;
+export declare function formatReport(r: CheckReport): string;