@absol-labs/agent 0.4.0 → 0.6.0

package/README.md

@@ -120,6 +120,63 @@ const decision = await checkMandate(
 if (!decision.allowed) throw new Error(`mandate denied: ${decision.reason}`);
 ```
 
+### Agent wallet lifecycle: create/restore → fund → sign
+
+An agent gets a usable wallet entirely through this package — no out-of-band key. `resolveAgentWallet()`
+accepts an injected viem private key OR a Coinbase CDP config; the CDP path is **create-or-restore**:
+the same `ownerName` always resolves to the same CDP-managed address, so re-running with the same env
+restores the identical wallet instead of minting a new one.
+
+```ts
+import {
+  resolveAgentWallet,
+  parseAgentWalletEnv,
+  getWalletBalances,
+  faucetHint,
+  requestCdpFaucet,
+} from "@absol-labs/agent";
+import { MetrikClient } from "@absol-labs/sdk";
+import { CdpClient } from "@coinbase/cdp-sdk";
+
+// 1) Create or restore, from env (CDP_API_KEY_ID/CDP_API_KEY_SECRET/CDP_WALLET_SECRET +
+//    METRIK_AGENT_CDP_OWNER_NAME, or METRIK_AGENT_PRIVATE_KEY for an injected key).
+const wallet = await resolveAgentWallet(parseAgentWalletEnv());
+console.log("address:", wallet.account.address);
+
+// 2) Read balance.
+const metrik = MetrikClient.baseSepolia({ account: wallet.account });
+const balances = await getWalletBalances({
+  publicClient: metrik.publicClient,
+  address: wallet.account.address,
+  usdc: metrik.config.usdc,
+});
+
+// 3) Fund (testnet only) — a faucet hint, or request funds programmatically for a CDP wallet.
+console.log(faucetHint(84532)); // { cdpFaucetUrl, usdcFaucetUrl, ... }
+if (wallet.source === "cdp" && balances.nativeWei === 0n) {
+  const cdp = new CdpClient({
+    /* same CDP_* creds */
+  });
+  await requestCdpFaucet({
+    cdp,
+    address: wallet.account.address,
+    token: "eth",
+  });
+}
+
+// 4) Sign — `wallet.account` is a plain viem `Account`; no extra wrapper needed.
+const signature = await wallet.account.signTypedData?.(/* ... */);
+```
+
+`getWalletBalances` and `faucetHint`/`requestCdpFaucet` are deliberately thin: they don't introduce a
+second wallet system, they just fill in the "read balance" and "get testnet funds" gaps around the
+existing `resolveAgentWallet()` / `createWalletBackedAgentClient()` surface. `faucetHint` and
+`requestCdpFaucet` only support Base Sepolia (`84532`) — Metrik is testnet-only, single-chain.
+
+See [`scripts/e2e-hire.ts`](./scripts/e2e-hire.ts) for the full journey (create/restore wallet → fund →
+hire → invoke → settle) run against real Base Sepolia infrastructure: `pnpm e2e:hire` (needs real CDP
+creds — see `.env.example`).
+
 ### Hire via x402: `402` challenge → signed payload → open stream
 
 ```ts
@@ -183,6 +240,136 @@ Core env surface: `METRIK_AGENT_RPC_URL`, `METRIK_AGENT_ESCROW`, `METRIK_AGENT_U
 `RECLAIM_APP_ID` / `RECLAIM_APP_SECRET` to enable the `prove_https_response` zkTLS tool.
 See [`docs/quickstart.md`](./docs/quickstart.md) for the full list.
 
+## Closed loop: `hire → invoke → (prove) → settle`
+
+Opening and funding a stream only pays for a service - it does not, on its own,
+authorize the buyer to _call_ it. The caller-auth gateway (metrik-protocol#62/#63/#64)
+closes that gap: a seller runs a small reverse-proxy gateway in front of its real
+service, and a buyer's SDK calls it directly with a short-lived, single-use,
+stream-bound `InvocationCapability` - no separate credential, no manual API key.
+
+**Seller side** - front any HTTP service with the reference gateway:
+
+```ts
+import {
+  CallerAuthGateway,
+  createCallerAuthGatewayServer,
+} from "@absol-labs/agent";
+
+const gateway = new CallerAuthGateway({
+  escrowAddress: "0x...", // the StreamEscrowV2 this service's streams settle on
+  rpcUrl: process.env.METRIK_GATEWAY_RPC_URL!,
+  serviceRef: "0x...", // this gateway's serviceRef - must match the listing
+});
+
+const server = createCallerAuthGatewayServer({
+  gateway,
+  upstreamUrl: "https://my-real-service.example.com",
+});
+await server.listen(8787);
+```
+
+Or run the ready-made standalone server from env (`METRIK_GATEWAY_ESCROW_ADDRESS`,
+`METRIK_GATEWAY_RPC_URL`, `METRIK_GATEWAY_SERVICE_REF`, `METRIK_GATEWAY_UPSTREAM_URL`,
+optional comma-separated `METRIK_GATEWAY_SERVICE_REFS` migration aliases,
+optional `METRIK_GATEWAY_CHAIN_ID` / `METRIK_GATEWAY_PORT` / `METRIK_GATEWAY_HOST`):
+
+```bash
+pnpm gateway
+```
+
+Every request must carry a valid capability; every failure mode (missing header, bad
+signature, wrong buyer, closed/expired/underfunded stream, replayed nonce, wrong
+method/path, wrong `serviceRef`) is rejected with a distinct machine-readable `reason`
+and a `402`/`403` - the real upstream is never touched on a rejection. Access is revoked
+automatically: once a stream is closed, expired, or reclaimed, the next on-chain read
+fails closed with no extra bookkeeping.
+
+**Buyer side** - after `hireVerifiedService`/`open()`, call the purchased service
+directly:
+
+```ts
+import { privateKeyToAccount } from "viem/accounts";
+import {
+  createSdkInvokeStreamReader,
+  discoverServices,
+  invoke,
+} from "@absol-labs/agent";
+
+const buyer = privateKeyToAccount(
+  process.env.METRIK_AGENT_PRIVATE_KEY as `0x${string}`,
+);
+const streamReader = createSdkInvokeStreamReader({
+  escrowAddress: "0x...",
+  rpcUrl: process.env.METRIK_AGENT_RPC_URL!,
+});
+const { serviceRef } = await streamReader.getStreamV2(streamId);
+const listing = (await discoverServices()).find(
+  (service) => service.serviceRef.toLowerCase() === serviceRef.toLowerCase(),
+);
+if (!listing) throw new Error("verified signed listing unavailable");
+
+const { response } = await invoke(
+  streamId, // from hireVerifiedService()
+  {
+    method: "POST",
+    path: "/v1/infer",
+    body: JSON.stringify({ prompt: "..." }),
+  },
+  {
+    streamReader,
+    buyer,
+    domain: { chainId: 84532, verifyingContract: "0x..." }, // same escrow as above
+    listing, // verified signature + signed callerAuth.accessUrl; no manual credential/URL
+  },
+);
+
+console.log(await response.json());
+```
+
+`invoke()` loads the stream, fails closed BEFORE any network call if it is not active,
+is expired, or does not belong to the signing account, then builds and signs a
+capability scoped to exactly that one `method`+`path` (short expiry, single-use nonce)
+and attaches it as the `x-metrik-capability` header. Use `capabilityFor()` directly if
+you only need the signed capability without the SDK also performing the `fetch`.
+
+For a public T2 (consumer-zkTLS) service, `invokeWithT2DeliveryProof()` attaches the SAME
+capability to the exact request the buyer's Reclaim attestor proves, so the
+capability-authorized call IS the delivery evidence - usage and proof become one action:
+
+```ts
+import { discoverServices, invokeWithT2DeliveryProof } from "@absol-labs/agent";
+
+const { serviceRef: t2ServiceRef } = await streamReader.getStreamV2(streamId);
+const publicT2Listing = (await discoverServices()).find(
+  (service) => service.serviceRef.toLowerCase() === t2ServiceRef.toLowerCase(),
+);
+if (!publicT2Listing || publicT2Listing.access !== "public") {
+  throw new Error("verified public T2 listing unavailable");
+}
+
+const { t2 } = await invokeWithT2DeliveryProof(streamId, {
+  streamReader,
+  buyer,
+  domain: { chainId: 84532, verifyingContract: "0x..." },
+  request: {
+    url: "https://public-t2-service.example.com/v1/infer",
+    method: "POST",
+    responseMatches: [{ type: "regex", value: '"result":"(?<result>.*)"' }],
+    nonceInjection: { in: "query", name: "nonce" },
+  },
+  intervalIndex: 0n,
+  nonce: deliveryNonce, // from GET /delivery/nonce
+  listing: publicT2Listing,
+});
+
+// t2.body is the exact POST /delivery/proof request payload.
+```
+
+Gated consumer-attested invocation fails closed for now: proof-target pinning does
+not yet distinguish the public oracle origin from a signed access gateway. Gated
+services use output-probe verification until that protocol support exists.
+
 ## Consumer zkTLS (delivery proofs)
 
 `ReclaimConsumerProofService` (and `createReclaimConsumerProofServiceFromEnv`) generate a

package/dist/capability/invocation-capability.d.ts

@@ -0,0 +1,184 @@
+import { type Address, type Hex, type LocalAccount } from "viem";
+import { z } from "zod";
+/** HTTP methods a capability may authorize. */
+export declare const httpMethodSchema: z.ZodEnum<["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]>;
+export type HttpMethod = z.infer<typeof httpMethodSchema>;
+export declare const invocationCapabilitySchema: z.ZodObject<{
+    /** The on-chain `StreamEscrowV2` stream this capability draws authority from. */
+    streamId: z.ZodEffects<z.ZodString, string, string>;
+    /** Must equal `stream.buyer` and the EIP-712 signer. */
+    buyer: z.ZodEffects<z.ZodString, `0x${string}`, string>;
+    /** Must equal the target service's `serviceRef` (and the stream's). */
+    serviceRef: z.ZodEffects<z.ZodString, string, string>;
+    /** The single HTTP method this capability authorizes. */
+    method: z.ZodEnum<["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]>;
+    /** `keccak256` of the exact request path this capability authorizes. */
+    pathHash: z.ZodEffects<z.ZodString, string, string>;
+    /** Single-use anti-replay nonce. */
+    nonce: z.ZodEffects<z.ZodString, string, string>;
+    /** Unix seconds after which the capability is no longer valid. */
+    expiry: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    streamId: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD";
+    serviceRef: string;
+    nonce: string;
+    buyer: `0x${string}`;
+    pathHash: string;
+    expiry: number;
+}, {
+    streamId: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD";
+    serviceRef: string;
+    nonce: string;
+    buyer: string;
+    pathHash: string;
+    expiry: number;
+}>;
+export type InvocationCapability = z.infer<typeof invocationCapabilitySchema>;
+export declare const signedInvocationCapabilitySchema: z.ZodObject<{
+    /** The on-chain `StreamEscrowV2` stream this capability draws authority from. */
+    streamId: z.ZodEffects<z.ZodString, string, string>;
+    /** Must equal `stream.buyer` and the EIP-712 signer. */
+    buyer: z.ZodEffects<z.ZodString, `0x${string}`, string>;
+    /** Must equal the target service's `serviceRef` (and the stream's). */
+    serviceRef: z.ZodEffects<z.ZodString, string, string>;
+    /** The single HTTP method this capability authorizes. */
+    method: z.ZodEnum<["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]>;
+    /** `keccak256` of the exact request path this capability authorizes. */
+    pathHash: z.ZodEffects<z.ZodString, string, string>;
+    /** Single-use anti-replay nonce. */
+    nonce: z.ZodEffects<z.ZodString, string, string>;
+    /** Unix seconds after which the capability is no longer valid. */
+    expiry: z.ZodNumber;
+} & {
+    signature: z.ZodEffects<z.ZodString, string, string>;
+}, "strip", z.ZodTypeAny, {
+    signature: string;
+    streamId: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD";
+    serviceRef: string;
+    nonce: string;
+    buyer: `0x${string}`;
+    pathHash: string;
+    expiry: number;
+}, {
+    signature: string;
+    streamId: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD";
+    serviceRef: string;
+    nonce: string;
+    buyer: string;
+    pathHash: string;
+    expiry: number;
+}>;
+export type SignedInvocationCapability = z.infer<typeof signedInvocationCapabilitySchema>;
+/** Chain-bound domain: a capability for one chain/escrow can never be replayed against another. */
+export interface InvocationCapabilityDomainInput {
+    readonly chainId: number;
+    /** The `StreamEscrowV2` the stream settles on. */
+    readonly verifyingContract: Address;
+}
+export declare const invocationCapabilityDomainName: "Metrik Invocation Capability";
+export declare const invocationCapabilityDomainVersion: "1";
+export declare const invocationCapabilityTypedData: {
+    readonly InvocationCapability: readonly [{
+        readonly name: "streamId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "buyer";
+        readonly type: "address";
+    }, {
+        readonly name: "serviceRef";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "method";
+        readonly type: "string";
+    }, {
+        readonly name: "pathHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "expiry";
+        readonly type: "uint64";
+    }];
+};
+/** Default single-use lifetime for a freshly-issued capability. Deliberately short. */
+export declare const DEFAULT_CAPABILITY_TTL_SECONDS = 60;
+/** Header a buyer's request carries the signed capability in. */
+export declare const CAPABILITY_HEADER_NAME = "x-metrik-capability";
+export declare function createInvocationCapabilityEip712Domain(domain: InvocationCapabilityDomainInput): {
+    readonly name: "Metrik Invocation Capability";
+    readonly version: "1";
+    readonly chainId: number;
+    readonly verifyingContract: `0x${string}`;
+};
+/**
+ * `keccak256` of the exact request path this capability authorizes (e.g.
+ * `/v1/infer`). Path only - no scheme/host/query/fragment - so the signer and
+ * the gateway hash the identical canonical string regardless of how each side
+ * received the full URL.
+ */
+export declare function hashInvocationPath(path: string): Hex;
+/** Strips query/fragment and any trailing slash (except the root) for a stable canonical form. */
+export declare function normalizeInvocationPath(path: string): string;
+export declare function buildInvocationCapabilityTypedData(capability: InvocationCapability, domain: InvocationCapabilityDomainInput): {
+    domain: {
+        readonly name: "Metrik Invocation Capability";
+        readonly version: "1";
+        readonly chainId: number;
+        readonly verifyingContract: `0x${string}`;
+    };
+    types: {
+        readonly InvocationCapability: readonly [{
+            readonly name: "streamId";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "buyer";
+            readonly type: "address";
+        }, {
+            readonly name: "serviceRef";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "method";
+            readonly type: "string";
+        }, {
+            readonly name: "pathHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "nonce";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "expiry";
+            readonly type: "uint64";
+        }];
+    };
+    primaryType: "InvocationCapability";
+    message: {
+        streamId: Hex;
+        buyer: `0x${string}`;
+        serviceRef: Hex;
+        method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD";
+        pathHash: Hex;
+        nonce: Hex;
+        expiry: bigint;
+    };
+};
+/** Signs an `InvocationCapability` with the buyer's own wallet. */
+export declare function signInvocationCapability(capability: InvocationCapability, domain: InvocationCapabilityDomainInput, account: LocalAccount): Promise<Hex>;
+/** Recovers the EIP-712 signer of a capability. Throws on a malformed signature. */
+export declare function recoverInvocationCapabilitySigner(capability: InvocationCapability, domain: InvocationCapabilityDomainInput, signature: Hex): Promise<Address>;
+/** Cryptographically random 32-byte single-use nonce. */
+export declare function generateCapabilityNonce(): Hex;
+export declare class InvalidCapabilityHeaderError extends Error {
+    constructor(message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+/** Encodes a signed capability as an opaque, header-safe (base64url) string. */
+export declare function encodeCapabilityHeader(signed: SignedInvocationCapability): string;
+/** Decodes and schema-validates a capability header value. Fails closed on any malformation. */
+export declare function decodeCapabilityHeader(headerValue: string): SignedInvocationCapability;
+//# sourceMappingURL=invocation-capability.d.ts.map

package/dist/capability/invocation-capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation-capability.d.ts","sourceRoot":"","sources":["../../src/capability/invocation-capability.ts"],"names":[],"mappings":"AAEA,OAAO,EAOL,KAAK,OAAO,EACZ,KAAK,GAAG,EACR,KAAK,YAAY,EAClB,MAAM,MAAM,CAAC;AACd,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAmCxB,+CAA+C;AAC/C,eAAO,MAAM,gBAAgB,yEAQ3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,0BAA0B;IACrC,iFAAiF;;IAEjF,wDAAwD;;IAExD,uEAAuE;;IAEvE,yDAAyD;;IAEzD,wEAAwE;;IAExE,oCAAoC;;IAEpC,kEAAkE;;;;;;;;;;;;;;;;;;EAElE,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,gCAAgC;IAjB3C,iFAAiF;;IAEjF,wDAAwD;;IAExD,uEAAuE;;IAEvE,yDAAyD;;IAEzD,wEAAwE;;IAExE,oCAAoC;;IAEpC,kEAAkE;;;;;;;;;;;;;;;;;;;;;;EAQhE,CAAC;AACL,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC9C,OAAO,gCAAgC,CACxC,CAAC;AAEF,mGAAmG;AACnG,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kDAAkD;IAClD,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;CACrC;AAED,eAAO,MAAM,8BAA8B,EACzC,8BAAuC,CAAC;AAC1C,eAAO,MAAM,iCAAiC,EAAG,GAAY,CAAC;AAE9D,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;CAUhC,CAAC;AAEX,uFAAuF;AACvF,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAEjD,iEAAiE;AACjE,eAAO,MAAM,sBAAsB,wBAAwB,CAAC;AAE5D,wBAAgB,sCAAsC,CACpD,MAAM,EAAE,+BAA+B;;;;;EAQxC;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAEpD;AAED,kGAAkG;AAClG,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAU5D;AAeD,wBAAgB,kCAAkC,CAChD,UAAU,EAAE,oBAAoB,EAChC,MAAM,EAAE,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAZR,GAAG;;oBAEC,GAAG;;kBAEP,GAAG;eACT,GAAG;;;EAe7B;AAED,mEAAmE;AACnE,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,oBAAoB,EAChC,MAAM,EAAE,+BAA+B,EACvC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,GAAG,CAAC,CAGd;AAED,oFAAoF;AACpF,wBAAsB,iCAAiC,CACrD,UAAU,EAAE,oBAAoB,EAChC,MAAM,EAAE,+BAA+B,EACvC,SAAS,EAAE,GAAG,GACb,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED,yDAAyD;AACzD,wBAAgB,uBAAuB,IAAI,GAAG,CAE7C;AAED,qBAAa,4BAA6B,SAAQ,KAAK;gBACzC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIpE;AAED,gFAAgF;AAChF,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,0BAA0B,GACjC,MAAM,CAaR;AAED,gGAAgG;AAChG,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,GAClB,0BAA0B,CA2B5B"}

package/dist/capability/invocation-capability.js

@@ -0,0 +1,183 @@
+import { randomBytes } from "node:crypto";
+import { getAddress, isAddress, isHex, keccak256, recoverTypedDataAddress, stringToBytes, } from "viem";
+import { z } from "zod";
+/**
+ * `InvocationCapability` — the stream-bound EIP-712 credential that closes the
+ * "pay -> use" loop (metrik-protocol#62/#63/#64).
+ *
+ * A buyer who has opened an active, funded stream signs one of these per
+ * service call: "I, `buyer`, authorize exactly `method` `pathHash` against
+ * `serviceRef` under stream `streamId`, once, before `expiry`." The seller's
+ * gateway (`../gateway/caller-auth-gateway.ts`) recovers the signer, cross
+ * checks it against the on-chain stream, and enforces the nonce/expiry/route
+ * binding before proxying the call upstream.
+ *
+ * Deliberately kept LOCAL to `@absol-labs/agent` for this MVP slice (per
+ * metrik-agent#64) rather than added to `@absol-labs/shared` - it is never
+ * read on-chain (no contract parses it), so there is no cross-repo byte
+ * compatibility requirement the way there is for `DeliveryReceipt`.
+ */
+const addressSchema = z
+    .string()
+    .refine((value) => isAddress(value), "must be an EVM address");
+const bytes32Schema = z
+    .string()
+    .refine((value) => isHex(value, { strict: true }) && value.length === 66, "must be bytes32 hex");
+const signatureSchema = z
+    .string()
+    .refine((value) => isHex(value, { strict: true }) && value.length === 132, "must be a 65-byte signature");
+/** HTTP methods a capability may authorize. */
+export const httpMethodSchema = z.enum([
+    "GET",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "HEAD",
+    "OPTIONS",
+]);
+export const invocationCapabilitySchema = z.object({
+    /** The on-chain `StreamEscrowV2` stream this capability draws authority from. */
+    streamId: bytes32Schema,
+    /** Must equal `stream.buyer` and the EIP-712 signer. */
+    buyer: addressSchema,
+    /** Must equal the target service's `serviceRef` (and the stream's). */
+    serviceRef: bytes32Schema,
+    /** The single HTTP method this capability authorizes. */
+    method: httpMethodSchema,
+    /** `keccak256` of the exact request path this capability authorizes. */
+    pathHash: bytes32Schema,
+    /** Single-use anti-replay nonce. */
+    nonce: bytes32Schema,
+    /** Unix seconds after which the capability is no longer valid. */
+    expiry: z.number().int().positive(),
+});
+export const signedInvocationCapabilitySchema = invocationCapabilitySchema.extend({
+    signature: signatureSchema,
+});
+export const invocationCapabilityDomainName = "Metrik Invocation Capability";
+export const invocationCapabilityDomainVersion = "1";
+export const invocationCapabilityTypedData = {
+    InvocationCapability: [
+        { name: "streamId", type: "bytes32" },
+        { name: "buyer", type: "address" },
+        { name: "serviceRef", type: "bytes32" },
+        { name: "method", type: "string" },
+        { name: "pathHash", type: "bytes32" },
+        { name: "nonce", type: "bytes32" },
+        { name: "expiry", type: "uint64" },
+    ],
+};
+/** Default single-use lifetime for a freshly-issued capability. Deliberately short. */
+export const DEFAULT_CAPABILITY_TTL_SECONDS = 60;
+/** Header a buyer's request carries the signed capability in. */
+export const CAPABILITY_HEADER_NAME = "x-metrik-capability";
+export function createInvocationCapabilityEip712Domain(domain) {
+    return {
+        name: invocationCapabilityDomainName,
+        version: invocationCapabilityDomainVersion,
+        chainId: domain.chainId,
+        verifyingContract: getAddress(domain.verifyingContract),
+    };
+}
+/**
+ * `keccak256` of the exact request path this capability authorizes (e.g.
+ * `/v1/infer`). Path only - no scheme/host/query/fragment - so the signer and
+ * the gateway hash the identical canonical string regardless of how each side
+ * received the full URL.
+ */
+export function hashInvocationPath(path) {
+    return keccak256(stringToBytes(normalizeInvocationPath(path)));
+}
+/** Strips query/fragment and any trailing slash (except the root) for a stable canonical form. */
+export function normalizeInvocationPath(path) {
+    const withoutFragment = path.split("#")[0] ?? "";
+    const withoutQuery = withoutFragment.split("?")[0] ?? "";
+    if (withoutQuery.length === 0) {
+        return "/";
+    }
+    if (withoutQuery.length > 1 && withoutQuery.endsWith("/")) {
+        return withoutQuery.slice(0, -1);
+    }
+    return withoutQuery;
+}
+function invocationCapabilityMessage(capability) {
+    const parsed = invocationCapabilitySchema.parse(capability);
+    return {
+        streamId: parsed.streamId,
+        buyer: getAddress(parsed.buyer),
+        serviceRef: parsed.serviceRef,
+        method: parsed.method,
+        pathHash: parsed.pathHash,
+        nonce: parsed.nonce,
+        expiry: BigInt(parsed.expiry),
+    };
+}
+export function buildInvocationCapabilityTypedData(capability, domain) {
+    return {
+        domain: createInvocationCapabilityEip712Domain(domain),
+        types: invocationCapabilityTypedData,
+        primaryType: "InvocationCapability",
+        message: invocationCapabilityMessage(capability),
+    };
+}
+/** Signs an `InvocationCapability` with the buyer's own wallet. */
+export async function signInvocationCapability(capability, domain, account) {
+    const typedData = buildInvocationCapabilityTypedData(capability, domain);
+    return account.signTypedData(typedData);
+}
+/** Recovers the EIP-712 signer of a capability. Throws on a malformed signature. */
+export async function recoverInvocationCapabilitySigner(capability, domain, signature) {
+    const typedData = buildInvocationCapabilityTypedData(capability, domain);
+    return recoverTypedDataAddress({ ...typedData, signature });
+}
+/** Cryptographically random 32-byte single-use nonce. */
+export function generateCapabilityNonce() {
+    return `0x${randomBytes(32).toString("hex")}`;
+}
+export class InvalidCapabilityHeaderError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "InvalidCapabilityHeaderError";
+    }
+}
+/** Encodes a signed capability as an opaque, header-safe (base64url) string. */
+export function encodeCapabilityHeader(signed) {
+    const parsed = signedInvocationCapabilitySchema.parse(signed);
+    const json = JSON.stringify({
+        streamId: parsed.streamId,
+        buyer: parsed.buyer,
+        serviceRef: parsed.serviceRef,
+        method: parsed.method,
+        pathHash: parsed.pathHash,
+        nonce: parsed.nonce,
+        expiry: parsed.expiry,
+        signature: parsed.signature,
+    });
+    return Buffer.from(json, "utf8").toString("base64url");
+}
+/** Decodes and schema-validates a capability header value. Fails closed on any malformation. */
+export function decodeCapabilityHeader(headerValue) {
+    let json;
+    try {
+        json = Buffer.from(headerValue, "base64url").toString("utf8");
+    }
+    catch (cause) {
+        throw new InvalidCapabilityHeaderError("malformed base64 capability header", { cause });
+    }
+    let raw;
+    try {
+        raw = JSON.parse(json);
+    }
+    catch (cause) {
+        throw new InvalidCapabilityHeaderError("malformed JSON capability header", {
+            cause,
+        });
+    }
+    const result = signedInvocationCapabilitySchema.safeParse(raw);
+    if (!result.success) {
+        throw new InvalidCapabilityHeaderError(`invalid capability shape: ${result.error.message}`);
+    }
+    return result.data;
+}
+//# sourceMappingURL=invocation-capability.js.map

package/dist/capability/invocation-capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation-capability.js","sourceRoot":"","sources":["../../src/capability/invocation-capability.ts"],"names":[],"mappings":"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"}