@hathbanger/tap-core 1.0.0

package/README.md

@@ -0,0 +1,280 @@
+# @hathbanger/tap-core
+
+RFC 9421 HTTP Message Signatures for AI agents — the crypto primitives behind [Visa's Trusted Agent Protocol (TAP)](https://developer.visa.com/pages/tap).
+
+Generate Ed25519 keypairs, sign HTTP requests with cryptographically verifiable identity, and verify those signatures on the server side. Works in Node.js and any runtime with the Web Crypto API.
+
+```ts
+import { generateKeyPair, signRequest, verifyAgentSignature } from "@hathbanger/tap-core"
+
+const keyPair = await generateKeyPair()
+
+const headers = await signRequest(keyPair, [
+  ["@method", "POST"],
+  ["@authority", "api.example.com"],
+  ["@path", "/v1/checkout"],
+], "agent-payer-auth")
+
+// headers["signature-input"] → sig1=("@method" "@authority" "@path");created=...;keyid="...";...
+// headers["signature"]       → sig1=:base64url:
+```
+
+---
+
+## Install
+
+```bash
+npm install @hathbanger/tap-core
+# or
+pnpm add @hathbanger/tap-core
+```
+
+Requires Node.js 18+. No native dependencies.
+
+---
+
+## Core concepts
+
+**Keypair** — an Ed25519 keypair with a derived key ID (JWK SHA-256 thumbprint). The public half is published to a JWKS endpoint; the private half signs requests.
+
+**Signature-Input** — an RFC 9421 header that describes _what_ was signed: the ordered list of covered components, a timestamp window, nonce, key ID, algorithm, and an optional application tag.
+
+**Signature** — the Ed25519 signature over the canonical signature base, base64url-encoded.
+
+**Verification** — the recipient re-derives the signature base from the live request values and verifies the signature against the key fetched from JWKS.
+
+---
+
+## Usage
+
+### 1. Generate a keypair
+
+```ts
+import { generateKeyPair, exportKeyPairToJwk } from "@hathbanger/tap-core"
+
+const keyPair = await generateKeyPair()
+// keyPair.keyId     → "abc123..." (JWK thumbprint, stable key identifier)
+// keyPair.privateKey → CryptoKey (sign)
+// keyPair.publicKey  → CryptoKey (verify)
+// keyPair.jwk        → TapJwk    (publish to /.well-known/jwks)
+
+// Export to JWK for storage / transport
+const { privateJwk, publicJwk } = await exportKeyPairToJwk(keyPair)
+```
+
+### 2. Sign a request
+
+Pass an ordered list of `[componentName, componentValue]` tuples. You control exactly which parts of the request are covered.
+
+```ts
+import { signRequest } from "@hathbanger/tap-core"
+
+// Minimal — authority + path only
+const headers = await signRequest(keyPair, [
+  ["@authority", "api.example.com"],
+  ["@path", "/v1/browse"],
+], "agent-browser-auth")
+
+// Full — method + authority + path + body integrity
+const headers = await signRequest(keyPair, [
+  ["@method", "POST"],
+  ["@authority", "api.example.com"],
+  ["@path", "/v1/checkout"],
+  ["content-type", "application/json"],
+  ["content-digest", `sha-256=:${bodyDigestBase64}:`],
+], "agent-payer-auth")
+
+// Attach to your fetch call
+await fetch("https://api.example.com/v1/checkout", {
+  method: "POST",
+  headers: { ...headers, "content-type": "application/json" },
+  body: JSON.stringify(payload),
+})
+```
+
+**Covered component names** follow RFC 9421 conventions:
+- Derived: `@method`, `@authority`, `@path`, `@target-uri`, `@scheme`, `@query`
+- HTTP fields: any lowercase header name — `content-type`, `content-digest`, `authorization`, etc.
+
+**Tags** are application-defined labels. TAP uses:
+| Tag | When to use |
+|-----|-------------|
+| `agent-browser-auth` | Agent browsing / reading data |
+| `agent-payer-auth` | Agent initiating a payment as payer |
+| `agent-payee-auth` | Agent accepting a payment as payee |
+
+### 3. Verify a signature
+
+The verifier reads the covered component list out of `Signature-Input` and reconstructs the base from the values you supply. Pass a map of all components that could appear.
+
+```ts
+import { verifyAgentSignature, fetchPublicKeyFromJwks } from "@hathbanger/tap-core"
+
+const result = await verifyAgentSignature(
+  {
+    "@method":    req.method,
+    "@authority": req.headers.host,
+    "@path":      new URL(req.url, "http://x").pathname,
+    "content-type": req.headers["content-type"] ?? "",
+  },
+  req.headers["signature-input"],
+  req.headers["signature"],
+  (kid) => fetchPublicKeyFromJwks("https://mcp.visa.com/.well-known/jwks", kid)
+)
+
+if (!result.valid) {
+  return res.status(401).json({ error: result.failureReason })
+}
+
+// result.agentKeyId → verified key ID
+// result.tag        → "agent-payer-auth" etc.
+```
+
+### 4. Load a keypair from stored JWK
+
+```ts
+import { loadKeyPairFromJwk } from "@hathbanger/tap-core"
+
+const privateJwk = JSON.parse(fs.readFileSync("agent.private.jwk.json", "utf-8"))
+const keyPair = await loadKeyPairFromJwk(privateJwk)
+```
+
+### 5. Serve a JWKS endpoint
+
+```ts
+import { buildJwksResponse } from "@hathbanger/tap-core"
+
+// In your route handler:
+const body = buildJwksResponse([keyPair.jwk])
+res.json(body)
+// → { keys: [{ kty: "OKP", crv: "Ed25519", x: "...", kid: "...", use: "sig" }] }
+```
+
+---
+
+## API Reference
+
+### Keys
+
+| Function | Description |
+|----------|-------------|
+| `generateKeyPair()` | Generate an Ed25519 `TapKeyPair` with derived key ID |
+| `exportKeyPairToJwk(pair)` | Export keypair to `{ privateJwk, publicJwk }` |
+| `loadKeyPairFromJwk(privateJwk)` | Reconstruct a `TapKeyPair` from a stored private JWK |
+| `importPrivateKey(jwk)` | Import a raw JWK → `CryptoKey` for signing |
+| `importPublicKey(jwk)` | Import a raw JWK → `CryptoKey` for verification |
+
+### Signing
+
+| Function | Description |
+|----------|-------------|
+| `signRequest(keyPair, components, tag)` | Sign an HTTP request — returns `{ "signature-input", "signature" }` |
+| `signPayload(keyPair, payload)` | Sign an arbitrary JSON payload — returns base64url signature |
+| `buildSignatureBase(components, params)` | Low-level: construct the RFC 9421 signature base string |
+| `buildSignatureInputParams(componentNames, params)` | Low-level: serialize the Inner List + params string |
+
+### Verification
+
+| Function | Description |
+|----------|-------------|
+| `verifyAgentSignature(componentValues, sigInput, sig, fetchKey)` | Verify an RFC 9421 agent signature |
+| `parseSignatureInput(header)` | Parse `Signature-Input` → `{ params, components, raw }` |
+| `parseSignatureHeader(header)` | Extract raw base64url signature from `Signature` header |
+| `verifyConsumerRecognition(obj, nonce, fetchKey)` | Verify a TAP Consumer Recognition Object |
+| `verifyPaymentContainer(obj, nonce, fetchKey)` | Verify a TAP Payment Container |
+| `verifyAgentPayeeObject(payment, fetchKey)` | Verify a TAP A2A payment credential |
+
+### JWKS
+
+| Function | Description |
+|----------|-------------|
+| `fetchPublicKeyFromJwks(url, keyId)` | Fetch a key by ID from a JWKS endpoint (5-min cache) |
+| `buildJwksResponse(publicJwks)` | Build a `{ keys: [...] }` JWKS response body |
+
+### Nonce / Timestamps
+
+| Function | Description |
+|----------|-------------|
+| `generateNonce()` | Generate a cryptographically random base64url nonce |
+| `makeTimestamps()` | Return `{ created, expires }` with an 8-minute window |
+| `validateTimestamps(created, expires)` | Validate timestamp window against current time |
+| `nowSeconds()` | Current Unix timestamp in seconds |
+
+### TAP Tokens (Consumer Identity)
+
+| Function | Description |
+|----------|-------------|
+| `createIdToken(keyPair, claims)` | Create an EdDSA JWT for a Consumer Recognition Object |
+| `verifyIdToken(token, publicJwk, audience)` | Verify and decode a TAP ID token |
+| `hashPii(value)` | SHA-256 hash a PII value (email / phone) |
+| `maskEmail(email)` | Mask email to `a***@domain.com` |
+| `maskPhone(phone)` | Mask phone to `***-***-1234` |
+
+---
+
+## Types
+
+```ts
+import type {
+  TapKeyPair,          // { keyId, privateKey, publicKey, jwk }
+  TapJwk,              // JWK with optional kid, use, alg
+  TapSignedHeaders,    // { "signature-input": string; signature: string }
+  SignatureInputParams,// { tag, keyId, alg, created, expires, nonce }
+  SignatureTag,        // "agent-browser-auth" | "agent-payer-auth" | "agent-payee-auth"
+  VerificationResult,  // { valid, agentKeyId?, tag?, failureReason? }
+} from "@hathbanger/tap-core"
+```
+
+---
+
+## Express middleware example
+
+```ts
+import express from "express"
+import { verifyAgentSignature, fetchPublicKeyFromJwks } from "@hathbanger/tap-core"
+
+const JWKS_URL = process.env.TAP_JWKS_URL ?? "http://localhost:4456/.well-known/jwks"
+
+async function tapAuth(req, res, next) {
+  const sigInput = req.headers["signature-input"]
+  const sig      = req.headers["signature"]
+
+  if (!sigInput || !sig) return next() // not a TAP request
+
+  const result = await verifyAgentSignature(
+    {
+      "@method":    req.method,
+      "@authority": req.hostname,
+      "@path":      req.path,
+    },
+    sigInput,
+    sig,
+    (kid) => fetchPublicKeyFromJwks(JWKS_URL, kid)
+  )
+
+  if (!result.valid) {
+    return res.status(401).json({ error: result.failureReason })
+  }
+
+  req.tapAgent = { keyId: result.agentKeyId, tag: result.tag }
+  next()
+}
+```
+
+---
+
+## Spec compliance
+
+This library implements the signature and verification mechanics from [RFC 9421 — HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421). Key points:
+
+- **Signature base** is constructed as specified in §2.5, with each covered component on its own line followed by `"@signature-params"`.
+- **Inner List** serialization (§4.1) covers any ordered set of derived components (`@method`, `@authority`, `@path`, etc.) and HTTP field names.
+- **Algorithm**: Ed25519 (`alg="ed25519"`) using Web Crypto `subtle.sign/verify`.
+- **Key IDs**: derived as a JWK SHA-256 thumbprint (RFC 7638).
+- **Timestamp window**: 8 minutes (`created` → `expires`), enforced on both sign and verify.
+
+---
+
+## License
+
+MIT

package/dist/agent.d.ts

@@ -0,0 +1,13 @@
+import type { ConsumerRecognitionObject, ContextualData, TapKeyPair } from "./types.js";
+export interface ConsumerProfile {
+    sub: string;
+    email: string;
+    phone?: string;
+    audience: string;
+}
+/**
+ * Builds a ConsumerRecognitionObject for inclusion in browsing or checkout requests.
+ * The nonce must match the agent recognition signature nonce.
+ */
+export declare function buildConsumerRecognition(keyPair: TapKeyPair, nonce: string, consumer: ConsumerProfile, contextualData?: ContextualData): Promise<ConsumerRecognitionObject>;
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,yBAAyB,EACzB,cAAc,EACd,UAAU,EACX,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,UAAU,EACnB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,eAAe,EACzB,cAAc,CAAC,EAAE,cAAc,GAC9B,OAAO,CAAC,yBAAyB,CAAC,CA4BpC"}

package/dist/agent.js

@@ -0,0 +1,32 @@
+import { signPayload } from "./sign.js";
+import { createIdToken, hashPii, maskEmail, maskPhone } from "./tokens.js";
+/**
+ * Builds a ConsumerRecognitionObject for inclusion in browsing or checkout requests.
+ * The nonce must match the agent recognition signature nonce.
+ */
+export async function buildConsumerRecognition(keyPair, nonce, consumer, contextualData) {
+    const [hashedEmail, hashedPhone] = await Promise.all([
+        hashPii(consumer.email),
+        consumer.phone ? hashPii(consumer.phone) : Promise.resolve(undefined),
+    ]);
+    const idToken = await createIdToken(keyPair, {
+        sub: consumer.sub,
+        aud: consumer.audience,
+        email: hashedEmail,
+        phone_number: hashedPhone,
+        email_verified: true,
+        phone_number_verified: !!consumer.phone,
+        email_mask: maskEmail(consumer.email),
+        phone_number_mask: consumer.phone ? maskPhone(consumer.phone) : undefined,
+    });
+    const unsigned = {
+        nonce,
+        idToken,
+        contextualData: contextualData ?? {},
+        kid: keyPair.keyId,
+        alg: "ed25519",
+    };
+    const signature = await signPayload(keyPair, unsigned);
+    return { ...unsigned, signature };
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAc1E;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,OAAmB,EACnB,KAAa,EACb,QAAyB,EACzB,cAA+B;IAE/B,MAAM,CAAC,WAAW,EAAE,WAAW,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACnD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;QACvB,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;KACtE,CAAC,CAAA;IAEF,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,OAAO,EAAE;QAC3C,GAAG,EAAE,QAAQ,CAAC,GAAG;QACjB,GAAG,EAAE,QAAQ,CAAC,QAAQ;QACtB,KAAK,EAAE,WAAW;QAClB,YAAY,EAAE,WAAW;QACzB,cAAc,EAAE,IAAI;QACpB,qBAAqB,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK;QACvC,UAAU,EAAE,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC;QACrC,iBAAiB,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS;KAC1E,CAAC,CAAA;IAEF,MAAM,QAAQ,GAAiD;QAC7D,KAAK;QACL,OAAO;QACP,cAAc,EAAE,cAAc,IAAI,EAAE;QACpC,GAAG,EAAE,OAAO,CAAC,KAAK;QAClB,GAAG,EAAE,SAAS;KACf,CAAA;IAED,MAAM,SAAS,GAAG,MAAM,WAAW,CAAC,OAAO,EAAE,QAAmC,CAAC,CAAA;IAEjF,OAAO,EAAE,GAAG,QAAQ,EAAE,SAAS,EAAE,CAAA;AACnC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./types.js";
+export * from "./keys.js";
+export * from "./nonce.js";
+export * from "./sign.js";
+export * from "./verify.js";
+export * from "./tokens.js";
+export * from "./payment.js";
+export * from "./agent.js";
+export * from "./jwks.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA"}

package/dist/index.js

@@ -0,0 +1,10 @@
+export * from "./types.js";
+export * from "./keys.js";
+export * from "./nonce.js";
+export * from "./sign.js";
+export * from "./verify.js";
+export * from "./tokens.js";
+export * from "./payment.js";
+export * from "./agent.js";
+export * from "./jwks.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA"}

package/dist/jwks.d.ts

@@ -0,0 +1,14 @@
+import type { JwksResponse, TapJwk } from "./types.js";
+/**
+ * Fetches a JWK by keyId from a JWKS endpoint.
+ * Used by merchants to retrieve the agent's public key for verification.
+ *
+ * In production: https://mcp.visa.com/.well-known/jwks
+ * In development: http://localhost:4456/.well-known/jwks (tap-cli dev server)
+ */
+export declare function fetchPublicKeyFromJwks(jwksUrl: string, keyId: string, cacheTtlMs?: number): Promise<TapJwk | null>;
+/**
+ * Creates a JWKS response body from an array of public JWKs.
+ */
+export declare function buildJwksResponse(publicJwks: TapJwk[]): JwksResponse;
+//# sourceMappingURL=jwks.d.ts.map

package/dist/jwks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks.d.ts","sourceRoot":"","sources":["../src/jwks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAEtD;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,UAAU,SAAU,GACnB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAmBxB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,YAAY,CAEpE"}

package/dist/jwks.js

@@ -0,0 +1,31 @@
+/**
+ * Fetches a JWK by keyId from a JWKS endpoint.
+ * Used by merchants to retrieve the agent's public key for verification.
+ *
+ * In production: https://mcp.visa.com/.well-known/jwks
+ * In development: http://localhost:4456/.well-known/jwks (tap-cli dev server)
+ */
+export async function fetchPublicKeyFromJwks(jwksUrl, keyId, cacheTtlMs = 300_000) {
+    const cacheKey = `${jwksUrl}:${keyId}`;
+    const cached = jwksCache.get(cacheKey);
+    if (cached && Date.now() - cached.fetchedAt < cacheTtlMs) {
+        return cached.jwk;
+    }
+    const res = await fetch(jwksUrl);
+    if (!res.ok)
+        throw new Error(`JWKS fetch failed: ${res.status}`);
+    const body = await res.json();
+    const match = body.keys.find((k) => k.kid === keyId) ?? null;
+    if (match) {
+        jwksCache.set(cacheKey, { jwk: match, fetchedAt: Date.now() });
+    }
+    return match;
+}
+/**
+ * Creates a JWKS response body from an array of public JWKs.
+ */
+export function buildJwksResponse(publicJwks) {
+    return { keys: publicJwks };
+}
+const jwksCache = new Map();
+//# sourceMappingURL=jwks.js.map

package/dist/jwks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks.js","sourceRoot":"","sources":["../src/jwks.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,OAAe,EACf,KAAa,EACb,UAAU,GAAG,OAAO;IAEpB,MAAM,QAAQ,GAAG,GAAG,OAAO,IAAI,KAAK,EAAE,CAAA;IACtC,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IAEtC,IAAI,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,SAAS,GAAG,UAAU,EAAE,CAAC;QACzD,OAAO,MAAM,CAAC,GAAG,CAAA;IACnB,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,CAAA;IAChC,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAA;IAEhE,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAkB,CAAA;IAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,CAAC,IAAI,IAAI,CAAA;IAE5D,IAAI,KAAK,EAAE,CAAC;QACV,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;IAChE,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAoB;IACpD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAA;AAC7B,CAAC;AAED,MAAM,SAAS,GAAG,IAAI,GAAG,EAA8C,CAAA"}

package/dist/keys.d.ts

@@ -0,0 +1,12 @@
+import type { TapJwk, TapKeyPair } from "./types.js";
+export declare function generateKeyPair(): Promise<TapKeyPair>;
+export declare function importPrivateKey(jwk: TapJwk): Promise<CryptoKey>;
+export declare function importPublicKey(jwk: TapJwk): Promise<CryptoKey>;
+export declare function exportKeyPairToJwk(pair: TapKeyPair): Promise<{
+    privateJwk: TapJwk;
+    publicJwk: TapJwk;
+}>;
+export declare function loadKeyPairFromJwk(privateJwk: TapJwk): Promise<TapKeyPair>;
+export declare function base64url(buffer: ArrayBuffer | Uint8Array<ArrayBufferLike>): string;
+export declare function base64urlDecode(str: string): Buffer;
+//# sourceMappingURL=keys.d.ts.map

package/dist/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAIpD,wBAAsB,eAAe,IAAI,OAAO,CAAC,UAAU,CAAC,CAiB3D;AAED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAEtE;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAErE;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAO7G;AAED,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAchF;AAaD,wBAAgB,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,CAAC,eAAe,CAAC,GAAG,MAAM,CAOnF;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAInD"}

package/dist/keys.js

@@ -0,0 +1,65 @@
+import { webcrypto } from "node:crypto";
+const subtle = webcrypto.subtle;
+export async function generateKeyPair() {
+    const result = await subtle.generateKey({ name: "Ed25519" }, true, ["sign", "verify"]);
+    const { privateKey, publicKey } = result;
+    const publicJwk = await subtle.exportKey("jwk", publicKey);
+    const keyId = await deriveKeyId(publicJwk);
+    return {
+        keyId,
+        privateKey,
+        publicKey,
+        jwk: { ...publicJwk, kid: keyId, use: "sig", alg: "EdDSA" },
+    };
+}
+export async function importPrivateKey(jwk) {
+    return subtle.importKey("jwk", jwk, { name: "Ed25519" }, false, ["sign"]);
+}
+export async function importPublicKey(jwk) {
+    return subtle.importKey("jwk", jwk, { name: "Ed25519" }, false, ["verify"]);
+}
+export async function exportKeyPairToJwk(pair) {
+    const privateJwk = await subtle.exportKey("jwk", pair.privateKey);
+    const publicJwk = await subtle.exportKey("jwk", pair.publicKey);
+    return {
+        privateJwk: { ...privateJwk, kid: pair.keyId },
+        publicJwk: { ...publicJwk, kid: pair.keyId, use: "sig" },
+    };
+}
+export async function loadKeyPairFromJwk(privateJwk) {
+    const privateKey = await importPrivateKey(privateJwk);
+    const publicJwk = {
+        kty: privateJwk.kty,
+        crv: privateJwk.crv,
+        x: privateJwk.x,
+        kid: privateJwk.kid,
+        use: "sig",
+    };
+    const publicKey = await importPublicKey(publicJwk);
+    const keyId = privateJwk.kid ?? await deriveKeyId(publicJwk);
+    return { keyId, privateKey, publicKey, jwk: { ...publicJwk, kid: keyId } };
+}
+async function deriveKeyId(publicJwk) {
+    const thumbprintInput = JSON.stringify({
+        crv: publicJwk.crv,
+        kty: publicJwk.kty,
+        x: publicJwk.x,
+    });
+    const encoded = new TextEncoder().encode(thumbprintInput);
+    const hash = await subtle.digest("SHA-256", encoded);
+    return base64url(hash);
+}
+export function base64url(buffer) {
+    const bytes = buffer instanceof ArrayBuffer ? new Uint8Array(buffer) : buffer;
+    return Buffer.from(bytes)
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=/g, "");
+}
+export function base64urlDecode(str) {
+    const padded = str.replace(/-/g, "+").replace(/_/g, "/");
+    const pad = padded.length % 4;
+    return Buffer.from(pad ? padded + "=".repeat(4 - pad) : padded, "base64");
+}
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

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

package/dist/nonce.d.ts

@@ -0,0 +1,10 @@
+export declare const NONCE_WINDOW_SECONDS = 480;
+export declare const SIGNATURE_WINDOW_SECONDS = 480;
+export declare function generateNonce(): string;
+export declare function nowSeconds(): number;
+export declare function makeTimestamps(): {
+    created: number;
+    expires: number;
+};
+export declare function validateTimestamps(created: number, expires: number): boolean;
+//# sourceMappingURL=nonce.d.ts.map

package/dist/nonce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonce.d.ts","sourceRoot":"","sources":["../src/nonce.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,oBAAoB,MAAM,CAAA;AACvC,eAAO,MAAM,wBAAwB,MAAM,CAAA;AAE3C,wBAAgB,aAAa,IAAI,MAAM,CAGtC;AAED,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,cAAc,IAAI;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAGrE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAM5E"}

package/dist/nonce.js

@@ -0,0 +1,26 @@
+import { webcrypto } from "node:crypto";
+import { base64url } from "./keys.js";
+export const NONCE_WINDOW_SECONDS = 480; // 8 minutes per spec
+export const SIGNATURE_WINDOW_SECONDS = 480;
+export function generateNonce() {
+    const bytes = webcrypto.getRandomValues(new Uint8Array(24));
+    return base64url(bytes.buffer);
+}
+export function nowSeconds() {
+    return Math.floor(Date.now() / 1000);
+}
+export function makeTimestamps() {
+    const created = nowSeconds();
+    return { created, expires: created + SIGNATURE_WINDOW_SECONDS };
+}
+export function validateTimestamps(created, expires) {
+    const now = nowSeconds();
+    if (created > now)
+        return false;
+    if (expires < now)
+        return false;
+    if (expires - created > SIGNATURE_WINDOW_SECONDS)
+        return false;
+    return true;
+}
+//# sourceMappingURL=nonce.js.map

package/dist/nonce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonce.js","sourceRoot":"","sources":["../src/nonce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAErC,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,CAAA,CAAC,qBAAqB;AAC7D,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,CAAA;AAE3C,MAAM,UAAU,aAAa;IAC3B,MAAM,KAAK,GAAG,SAAS,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,CAAA;IAC3D,OAAO,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;AAChC,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAA;AACtC,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAA;IAC5B,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,wBAAwB,EAAE,CAAA;AACjE,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,OAAe;IACjE,MAAM,GAAG,GAAG,UAAU,EAAE,CAAA;IACxB,IAAI,OAAO,GAAG,GAAG;QAAE,OAAO,KAAK,CAAA;IAC/B,IAAI,OAAO,GAAG,GAAG;QAAE,OAAO,KAAK,CAAA;IAC/B,IAAI,OAAO,GAAG,OAAO,GAAG,wBAAwB;QAAE,OAAO,KAAK,CAAA;IAC9D,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/payment.d.ts

@@ -0,0 +1,19 @@
+import type { Address, AgentPayeeObject, CardMetadata, EncryptedPaymentPayload, PaymentContainerObject, TapKeyPair, TapPaymentRequest } from "./types.js";
+/**
+ * Builds a PaymentContainerObject for checkout requests.
+ *
+ * In production this would contain an encrypted Visa payment token.
+ * In demo mode it contains a mock token with realistic structure.
+ */
+export declare function buildPaymentContainer(keyPair: TapKeyPair, nonce: string, payload: EncryptedPaymentPayload, cardMetadata: CardMetadata): Promise<PaymentContainerObject>;
+/**
+ * Creates a mock payment token for demo purposes.
+ * Simulates the encrypted token Visa would issue in production.
+ */
+export declare function createMockPaymentToken(lastFour: string, cardholderName: string, billingAddress: Address, shippingAddress: Address, email: string): Promise<{
+    payload: EncryptedPaymentPayload;
+    cardMetadata: CardMetadata;
+}>;
+export declare function buildTapPaymentRequest(keyPair: TapKeyPair, amount: number, currency: string, description: string): TapPaymentRequest;
+export declare function buildAgentPayeeObject(keyPair: TapKeyPair, paymentRequest: TapPaymentRequest): Promise<AgentPayeeObject>;
+//# sourceMappingURL=payment.d.ts.map

package/dist/payment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment.d.ts","sourceRoot":"","sources":["../src/payment.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,OAAO,EACP,gBAAgB,EAChB,YAAY,EACZ,uBAAuB,EACvB,sBAAsB,EACtB,UAAU,EACV,iBAAiB,EAClB,MAAM,YAAY,CAAA;AAEnB;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,UAAU,EACnB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,uBAAuB,EAChC,YAAY,EAAE,YAAY,GACzB,OAAO,CAAC,sBAAsB,CAAC,CAYjC;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,OAAO,EACvB,eAAe,EAAE,OAAO,EACxB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;IAAE,OAAO,EAAE,uBAAuB,CAAC;IAAC,YAAY,EAAE,YAAY,CAAA;CAAE,CAAC,CA2B3E;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,iBAAiB,CASnB;AAED,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,UAAU,EACnB,cAAc,EAAE,iBAAiB,GAChC,OAAO,CAAC,gBAAgB,CAAC,CAgB3B"}