@apicity/cost 0.2.0-alpha.1 → 0.2.0

package/dist/src/paid-endpoints.js

@@ -1,4 +1,12 @@
-import { computeEstimate } from "./compute.js";
+/**
+ * Exact paid-endpoint registry.
+ *
+ * Only endpoints listed here are considered paid. All unlisted endpoints
+ * are assumed free and must preserve current behavior with no caller changes.
+ *
+ * Matching is exact: provider + method + dotPath. No regex, prefix,
+ * wildcard, path-family, generated broad match, or fallback-by-method logic.
+ */
 /**
  * The canonical list of paid endpoints. Add new entries here only after
  * review. Keep the list small and explicit.
@@ -42,116 +50,4 @@ export function lookupPaidEndpoint(provider, method, dotPath) {
 export function isPaidEndpoint(provider, method, dotPath) {
     return lookupPaidEndpoint(provider, method, dotPath) !== undefined;
 }
-/**
- * Error thrown when a paid endpoint is called without an explicit maxSpend.
- */
-export class MaxSpendError extends Error {
-    provider;
-    method;
-    dotPath;
-    maxSpend;
-    constructor(provider, method, dotPath, maxSpend) {
-        super(`Endpoint ${provider} ${method} ${dotPath} may spend money. ` +
-            `maxSpend is ${maxSpend} USD. ` +
-            `Pass an explicit maxSpend to proceed.`);
-        this.name = "MaxSpendError";
-        this.provider = provider;
-        this.method = method;
-        this.dotPath = dotPath;
-        this.maxSpend = maxSpend;
-    }
-}
-/**
- * Error thrown when the estimated cost of a paid endpoint exceeds the
- * caller's maxSpend or when the cost cannot be safely estimated.
- */
-export class SpendBoundError extends Error {
-    provider;
-    method;
-    dotPath;
-    maxSpend;
-    estimatedUsd;
-    constructor(provider, method, dotPath, maxSpend, estimatedUsd, message) {
-        super(message ??
-            `Endpoint ${provider} ${method} ${dotPath} estimated cost ` +
-                `(${estimatedUsd} USD) exceeds maxSpend (${maxSpend} USD).`);
-        this.name = "SpendBoundError";
-        this.provider = provider;
-        this.method = method;
-        this.dotPath = dotPath;
-        this.maxSpend = maxSpend;
-        this.estimatedUsd = estimatedUsd;
-    }
-}
-/**
- * Preflight check for paid endpoints.
- *
- * For paid endpoints, maxSpend defaults to 0 when omitted. maxSpend=0 blocks
- * before the network request with a MaxSpendError. maxSpend>0 authorizes the
- * call to proceed.
- *
- * Free/unlisted endpoints are always allowed regardless of maxSpend.
- */
-export function maxSpendPreflight(provider, method, dotPath, maxSpend = 0) {
-    if (!isPaidEndpoint(provider, method, dotPath)) {
-        return;
-    }
-    if (maxSpend <= 0) {
-        throw new MaxSpendError(provider, method, dotPath, maxSpend);
-    }
-}
-/**
- * Verify that a cost estimate is within the caller's maxSpend.
- *
- * If the estimate has warnings (could not be computed safely), the spend
- * cannot be bounded and the call is blocked. If the estimated USD exceeds
- * maxSpend, the call is blocked. Otherwise the call proceeds.
- *
- * This must run AFTER maxSpendPreflight, so maxSpend is known to be > 0.
- */
-export function spendBoundCheck(provider, method, dotPath, maxSpend, estimate) {
-    if (maxSpend === undefined || maxSpend <= 0) {
-        return;
-    }
-    if (estimate.warnings.length > 0) {
-        throw new SpendBoundError(provider, method, dotPath, maxSpend, estimate.usd, `Endpoint ${provider} ${method} ${dotPath} spend cannot be bounded ` +
-            `from the payload: ${estimate.warnings.join("; ")}. ` +
-            `Pass an explicit maxSpend that covers the worst-case cost, ` +
-            `or adjust the payload so the cost can be estimated.`);
-    }
-    if (estimate.usd > maxSpend) {
-        throw new SpendBoundError(provider, method, dotPath, maxSpend, estimate.usd);
-    }
-}
-/**
- * Wrap a provider network dispatch with the paid-endpoint guard.
- *
- * This is the canonical boundary enforcement: it runs the preflight check
- * and spend-bound check before the actual HTTP request, and only calls the
- * supplied `dispatch` function when the checks pass.
- *
- * Free/unlisted endpoints return `dispatch()` immediately without guard
- * overhead, so callers that omit `maxSpend` on free endpoints see no change.
- *
- * @param provider - Provider identifier (e.g. "kie", "openai")
- * @param method - HTTP method (e.g. "POST", "GET")
- * @param dotPath - Exact endpoint dot-path (e.g. "api.v1.jobs.createTask")
- * @param payload - Request payload for cost estimation
- * @param maxSpend - Maximum spend authorization in USD (undefined for free endpoints)
- * @param dispatch - The actual network dispatch to wrap
- * @returns The result of `dispatch()`
- */
-export async function dispatchWithPaidGuard(provider, method, dotPath, payload, maxSpend, dispatch) {
-    maxSpendPreflight(provider, method, dotPath, maxSpend);
-    if (isPaidEndpoint(provider, method, dotPath) &&
-        maxSpend !== undefined &&
-        maxSpend > 0) {
-        const estimate = computeEstimate({
-            provider: provider,
-            payload,
-        });
-        spendBoundCheck(provider, method, dotPath, maxSpend, estimate);
-    }
-    return dispatch();
-}
 //# sourceMappingURL=paid-endpoints.js.map

package/dist/src/paid-endpoints.js.map

@@ -1 +1 @@
-{"version":3,"file":"paid-endpoints.js","sourceRoot":"","sources":["../../src/paid-endpoints.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"paid-endpoints.js","sourceRoot":"","sources":["../../src/paid-endpoints.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAsBH;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAiC;IAC1D;QACE,GAAG,EAAE;YACH,QAAQ,EAAE,KAAK;YACf,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,wBAAwB;SAClC;QACD,IAAI,EAAE;YACJ,MAAM,EACJ,wEAAwE;YAC1E,WAAW,EAAE,cAAc;YAC3B,SAAS,EACP,sEAAsE;SACzE;KACF;CACF,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAgB,EAChB,MAAc,EACd,OAAe;IAEf,KAAK,MAAM,KAAK,IAAI,cAAc,EAAE,CAAC;QACnC,IACE,KAAK,CAAC,GAAG,CAAC,QAAQ,KAAK,QAAQ;YAC/B,KAAK,CAAC,GAAG,CAAC,MAAM,KAAK,MAAM;YAC3B,KAAK,CAAC,GAAG,CAAC,OAAO,KAAK,OAAO,EAC7B,CAAC;YACD,OAAO,KAAK,CAAC,IAAI,CAAC;QACpB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAgB,EAChB,MAAc,EACd,OAAe;IAEf,OAAO,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,KAAK,SAAS,CAAC;AACrE,CAAC"}

package/dist/src/paygate-cli.d.ts

@@ -1,19 +1,3 @@
 #!/usr/bin/env node
-/**
- * Parse a TTL string like "10m", "1h", "30s" into seconds.
- */
-export declare function parseTtl(ttl: string): number;
-/**
- * Mint an OTP for a specific request.
- *
- * Requires `APICITY_PAYGATE_PRIVATE_KEY_PATH` to point to an Ed25519 private key PEM.
- */
-export declare function mintOtp(provider: string, method: string, dotPath: string, payload: Record<string, unknown>, maxSpendUsd: number, ttlSeconds: number): string;
-/**
- * Generate a fresh Ed25519 key pair for the pay gate.
- */
-export declare function generateKeyPair(): {
-    publicKeyPem: string;
-    privateKeyPem: string;
-};
+export {};
 //# sourceMappingURL=paygate-cli.d.ts.map

package/dist/src/paygate-cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paygate-cli.d.ts","sourceRoot":"","sources":["../../src/paygate-cli.ts"],"names":[],"mappings":";AAkBA;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAqB5C;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GACjB,MAAM,CAuCR;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB,CAMA"}
+{"version":3,"file":"paygate-cli.d.ts","sourceRoot":"","sources":["../../src/paygate-cli.ts"],"names":[],"mappings":""}

package/dist/src/paygate-cli.js

@@ -1,83 +1,7 @@
 #!/usr/bin/env node
-import { sign, generateKeyPairSync, randomBytes } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { canonicalHash } from "./paygate.js";
-/**
- * Encode a buffer to unpadded base64url.
- */
-function base64urlEncode(data) {
-    return data
-        .toString("base64")
-        .replace(/\+/g, "-")
-        .replace(/\//g, "_")
-        .replace(/=+$/g, "");
-}
-/**
- * Parse a TTL string like "10m", "1h", "30s" into seconds.
- */
-export function parseTtl(ttl) {
-    const match = ttl.match(/^(\d+)([smhd])$/i);
-    if (!match) {
-        throw new Error(`Invalid TTL format: ${ttl}. Expected format like 10m, 1h, 30s.`);
-    }
-    const value = parseInt(match[1], 10);
-    const unit = match[2].toLowerCase();
-    switch (unit) {
-        case "s":
-            return value;
-        case "m":
-            return value * 60;
-        case "h":
-            return value * 60 * 60;
-        case "d":
-            return value * 60 * 60 * 24;
-        default:
-            throw new Error(`Unknown TTL unit: ${unit}`);
-    }
-}
-/**
- * Mint an OTP for a specific request.
- *
- * Requires `APICITY_PAYGATE_PRIVATE_KEY_PATH` to point to an Ed25519 private key PEM.
- */
-export function mintOtp(provider, method, dotPath, payload, maxSpendUsd, ttlSeconds) {
-    const privateKeyPath = process.env.APICITY_PAYGATE_PRIVATE_KEY_PATH;
-    if (!privateKeyPath) {
-        throw new Error("APICITY_PAYGATE_PRIVATE_KEY_PATH is not set. " +
-            "Export the path to your Ed25519 private key PEM.");
-    }
-    const privateKeyPem = readFileSync(privateKeyPath, "utf8");
-    const jti = randomBytes(16).toString("hex");
-    const iat = Math.floor(Date.now() / 1000);
-    const exp = iat + ttlSeconds;
-    const payloadObj = {
-        v: 1,
-        jti,
-        provider,
-        method,
-        dotPath,
-        requestHash: canonicalHash(payload),
-        maxSpendUsd,
-        iat,
-        exp,
-    };
-    const payloadJson = JSON.stringify(payloadObj);
-    const payloadSegment = base64urlEncode(Buffer.from(payloadJson, "utf8"));
-    const signature = sign(null, Buffer.from(payloadSegment, "utf8"), privateKeyPem);
-    const signatureSegment = base64urlEncode(signature);
-    return `${payloadSegment}.${signatureSegment}`;
-}
-/**
- * Generate a fresh Ed25519 key pair for the pay gate.
- */
-export function generateKeyPair() {
-    const { publicKey, privateKey } = generateKeyPairSync("ed25519", {
-        publicKeyEncoding: { type: "spki", format: "pem" },
-        privateKeyEncoding: { type: "pkcs8", format: "pem" },
-    });
-    return { publicKeyPem: publicKey, privateKeyPem: privateKey };
-}
+import { mintOtp } from "./paygate.js";
 function parseMintArgs(argv) {
     const out = {};
     for (let i = 0; i < argv.length; i++) {
@@ -98,10 +22,10 @@ function parseMintArgs(argv) {
             out.payloadFile = argv[++i];
         else if (a.startsWith("--payload-file="))
             out.payloadFile = a.slice(15);
-        else if (a === "--max-spend")
-            out.maxSpend = parseFloat(argv[++i]);
-        else if (a.startsWith("--max-spend="))
-            out.maxSpend = parseFloat(a.slice(12));
+        else if (a === "--secret-file")
+            out.secretFile = argv[++i];
+        else if (a.startsWith("--secret-file="))
+            out.secretFile = a.slice(14);
         else if (a === "--ttl")
             out.ttl = argv[++i];
         else if (a.startsWith("--ttl="))
@@ -110,14 +34,7 @@ function parseMintArgs(argv) {
             console.error(`[apicity-paygate] unknown arg: ${a}`);
         }
     }
-    const required = [
-        "provider",
-        "method",
-        "dotPath",
-        "payloadFile",
-        "maxSpend",
-        "ttl",
-    ];
+    const required = ["dotPath", "payloadFile", "secretFile"];
     for (const key of required) {
         if (out[key] === undefined || out[key] === null) {
             throw new Error(`Missing required argument: --${key.replace(/([A-Z])/g, "-$1").toLowerCase()}`);
@@ -131,23 +48,20 @@ function printHelp() {
         "",
         "Usage:",
         "  apicity-paygate otp mint \\",
-        "    --provider <provider> \\",
-        "    --method <HTTP method> \\",
+        "    --secret-file <path> \\",
         "    --dot-path <api.path> \\",
         "    --payload-file <path> \\",
-        "    --max-spend <usd> \\",
-        "    --ttl <duration>",
+        "    [--provider <provider>] \\",
+        "    [--method <HTTP method>] \\",
+        "    [--ttl <duration>]",
         "",
         "Options:",
-        "  --provider     Provider name (e.g. kie, openai, xai)",
-        "  --method       HTTP method (e.g. POST, GET)",
+        "  --secret-file  Path to a file containing the shared HMAC secret",
         "  --dot-path     API dot-path (e.g. api.v1.jobs.createTask)",
         "  --payload-file Path to JSON request payload file",
-        "  --max-spend    Maximum spend in USD",
-        "  --ttl          Time-to-live: 10m, 1h, 30s, 1d",
-        "",
-        "Environment:",
-        "  APICITY_PAYGATE_PRIVATE_KEY_PATH  Path to Ed25519 private key PEM",
+        "  --provider     Provider name (optional; resolved from the dot-path)",
+        "  --method       HTTP method (optional; resolved from the dot-path)",
+        "  --ttl          Time-to-live: 10m, 1h, 30s, 1d (default 10m)",
     ].join("\n"));
 }
 async function main() {
@@ -162,9 +76,15 @@ async function main() {
         process.exit(1);
     }
     const args = parseMintArgs(argv.slice(2));
-    const payload = JSON.parse(readFileSync(args.payloadFile, "utf8"));
-    const ttlSeconds = parseTtl(args.ttl);
-    const otp = mintOtp(args.provider, args.method, args.dotPath, payload, args.maxSpend, ttlSeconds);
+    const secret = readFileSync(args.secretFile, "utf8").trim();
+    const request = JSON.parse(readFileSync(args.payloadFile, "utf8"));
+    const otp = mintOtp(secret, {
+        provider: args.provider,
+        method: args.method,
+        dotPath: args.dotPath,
+        request,
+        ttl: args.ttl,
+    });
     console.log(otp);
 }
 const __filename = fileURLToPath(import.meta.url);

package/dist/src/paygate-cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"paygate-cli.js","sourceRoot":"","sources":["../../src/paygate-cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C;;GAEG;AACH,SAAS,eAAe,CAAC,IAAY;IACnC,OAAO,IAAI;SACR,QAAQ,CAAC,QAAQ,CAAC;SAClB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,uBAAuB,GAAG,sCAAsC,CACjE,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,EAAE,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,CAAC;IACrC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,GAAG;YACN,OAAO,KAAK,CAAC;QACf,KAAK,GAAG;YACN,OAAO,KAAK,GAAG,EAAE,CAAC;QACpB,KAAK,GAAG;YACN,OAAO,KAAK,GAAG,EAAE,GAAG,EAAE,CAAC;QACzB,KAAK,GAAG;YACN,OAAO,KAAK,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;QAC9B;YACE,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,EAAE,CAAC,CAAC;IACjD,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CACrB,QAAgB,EAChB,MAAc,EACd,OAAe,EACf,OAAgC,EAChC,WAAmB,EACnB,UAAkB;IAElB,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,gCAAgC,CAAC;IACpE,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,+CAA+C;YAC7C,kDAAkD,CACrD,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,YAAY,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;IAE3D,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC5C,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IAC1C,MAAM,GAAG,GAAG,GAAG,GAAG,UAAU,CAAC;IAE7B,MAAM,UAAU,GAAG;QACjB,CAAC,EAAE,CAAU;QACb,GAAG;QACH,QAAQ;QACR,MAAM;QACN,OAAO;QACP,WAAW,EAAE,aAAa,CAAC,OAAO,CAAC;QACnC,WAAW;QACX,GAAG;QACH,GAAG;KACJ,CAAC;IAEF,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IAC/C,MAAM,cAAc,GAAG,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;IAEzE,MAAM,SAAS,GAAG,IAAI,CACpB,IAAI,EACJ,MAAM,CAAC,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,EACnC,aAAa,CACd,CAAC;IAEF,MAAM,gBAAgB,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;IAEpD,OAAO,GAAG,cAAc,IAAI,gBAAgB,EAAE,CAAC;AACjD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe;IAI7B,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,mBAAmB,CAAC,SAAS,EAAE;QAC/D,iBAAiB,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE;QAClD,kBAAkB,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE;KACrD,CAAC,CAAC;IACH,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,CAAC;AAChE,CAAC;AAWD,SAAS,aAAa,CAAC,IAAc;IACnC,MAAM,GAAG,GAAsB,EAAE,CAAC;IAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,KAAK,YAAY;YAAE,GAAG,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;aAC5C,IAAI,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC;YAAE,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;aAC5D,IAAI,CAAC,KAAK,UAAU;YAAE,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;aAC7C,IAAI,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC;YAAE,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;aACvD,IAAI,CAAC,KAAK,YAAY;YAAE,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;aAChD,IAAI,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC;YAAE,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;aAC3D,IAAI,CAAC,KAAK,gBAAgB;YAAE,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;aACxD,IAAI,CAAC,CAAC,UAAU,CAAC,iBAAiB,CAAC;YAAE,GAAG,CAAC,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;aACnE,IAAI,CAAC,KAAK,aAAa;YAAE,GAAG,CAAC,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAE,CAAC,CAAC;aAC/D,IAAI,CAAC,CAAC,UAAU,CAAC,cAAc,CAAC;YACnC,GAAG,CAAC,QAAQ,GAAG,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;aACpC,IAAI,CAAC,KAAK,OAAO;YAAE,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;aACvC,IAAI,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;aACjD,CAAC;YACJ,OAAO,CAAC,KAAK,CAAC,kCAAkC,CAAC,EAAE,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAuB;QACnC,UAAU;QACV,QAAQ;QACR,SAAS;QACT,aAAa;QACb,UAAU;QACV,KAAK;KACN,CAAC;IACF,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;YAChD,MAAM,IAAI,KAAK,CACb,gCAAgC,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,WAAW,EAAE,EAAE,CAC/E,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,GAAe,CAAC;AACzB,CAAC;AAED,SAAS,SAAS;IAChB,OAAO,CAAC,KAAK,CACX;QACE,0DAA0D;QAC1D,EAAE;QACF,QAAQ;QACR,+BAA+B;QAC/B,8BAA8B;QAC9B,+BAA+B;QAC/B,8BAA8B;QAC9B,8BAA8B;QAC9B,0BAA0B;QAC1B,sBAAsB;QACtB,EAAE;QACF,UAAU;QACV,wDAAwD;QACxD,+CAA+C;QAC/C,6DAA6D;QAC7D,oDAAoD;QACpD,uCAAuC;QACvC,iDAAiD;QACjD,EAAE;QACF,cAAc;QACd,qEAAqE;KACtE,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEnC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAClE,SAAS,EAAE,CAAC;QACZ,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC;QAC5C,OAAO,CAAC,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACjE,SAAS,EAAE,CAAC;QACZ,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1C,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAGhE,CAAC;IACF,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtC,MAAM,GAAG,GAAG,OAAO,CACjB,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,MAAM,EACX,IAAI,CAAC,OAAO,EACZ,OAAO,EACP,IAAI,CAAC,QAAQ,EACb,UAAU,CACX,CAAC;IACF,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACnB,CAAC;AACD,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,UAAU,EAAE,CAAC;IACnC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACnB,OAAO,CAAC,KAAK,CACX,0BAA0B,EAC1B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CACzC,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"paygate-cli.js","sourceRoot":"","sources":["../../src/paygate-cli.ts"],"names":[],"mappings":"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"}

package/dist/src/paygate.d.ts

@@ -1,5 +1,7 @@
 /**
- * OTP payload schema.
+ * OTP payload schema. An OTP commits to an exact
+ * `(provider, method, dotPath, requestHash)` tuple with an expiry, and is
+ * single-use via its `jti`.
  */
 export interface PayGateOtpPayload {
     v: 1;
@@ -8,7 +10,6 @@ export interface PayGateOtpPayload {
     method: string;
     dotPath: string;
     requestHash: `sha256:${string}`;
-    maxSpendUsd: number;
     iat: number;
     exp: number;
 }
@@ -19,8 +20,29 @@ export interface PayGateApproval {
     otp: string;
 }
 /**
- * Error thrown when the pay gate blocks a request for any reason
- * other than spend bounds (which use SpendBoundError).
+ * Single-use replay ledger. The default is an in-process Set scoped to one
+ * provider instance (see `createReplayStore`). Pass a custom store for
+ * cross-process or persistent replay protection.
+ */
+export interface ReplayStore {
+    has(jti: string): boolean;
+    add(jti: string): void;
+}
+/**
+ * Pay-gate configuration supplied by the code client at construction time
+ * (never by the autonomous caller). Holds the shared HMAC secret used to mint
+ * and verify OTPs. No environment variables, no key files.
+ */
+export interface PayGateConfig {
+    /** Shared HMAC secret. The code client holds it; the AI never sees it. */
+    secret: string;
+    /** Replay ledger. Defaults to an in-process Set, per provider instance. */
+    replayStore?: ReplayStore;
+    /** Clock injection for testing. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Error thrown when the pay gate blocks a request.
  */
 export declare class PayGateError extends Error {
     readonly provider: string;
@@ -29,6 +51,39 @@ export declare class PayGateError extends Error {
     readonly code: "paygate-not-configured" | "otp-missing" | "otp-malformed" | "otp-invalid-signature" | "otp-expired" | "otp-mismatched-request" | "otp-replayed";
     constructor(provider: string, method: string, dotPath: string, code: PayGateError["code"], message: string);
 }
+/**
+ * Verification-only error codes — the subset of PayGateError codes that the
+ * pure `verifyOtp` can emit. The shell layer ("paygate-not-configured",
+ * "otp-missing") is handled separately in `dispatchWithPaidGate`.
+ */
+export type VerifyFailureCode = "otp-malformed" | "otp-invalid-signature" | "otp-expired" | "otp-mismatched-request" | "otp-replayed";
+/**
+ * Tagged-union result from the pure `verifyOtp` function.
+ */
+export type VerifyResult = {
+    ok: true;
+    jti: string;
+} | {
+    ok: false;
+    code: VerifyFailureCode;
+    message: string;
+};
+/**
+ * Pure inputs to `verifyOtp`. Every dependency is explicit — no env vars,
+ * no `Date.now()`, no filesystem reads.
+ */
+export interface VerifyOtpInput {
+    nowSeconds: number;
+    secret: string;
+    expected: {
+        provider: string;
+        method: string;
+        dotPath: string;
+    };
+    payloadHash: `sha256:${string}`;
+    otp: string;
+    isJtiConsumed: (jti: string) => boolean;
+}
 /**
  * Canonicalize a JSON value by sorting object keys recursively.
  * Arrays preserve order. Non-JSON values (undefined, functions, symbols,
@@ -39,6 +94,10 @@ export declare function canonicalizeJson(value: unknown): string;
  * Compute SHA-256 of canonical JSON, prefixed with `sha256:`.
  */
 export declare function canonicalHash(value: unknown): `sha256:${string}`;
+/**
+ * Parse a TTL string like "10m", "1h", "30s", "1d" into seconds.
+ */
+export declare function parseTtl(ttl: string): number;
 /**
  * Parse an OTP envelope: `<base64url(payloadJson)>.<base64url(signature)>`.
  * Returns the payload object and raw signature bytes.
@@ -48,33 +107,54 @@ export declare function parseOtp(otp: string): {
     signature: Buffer;
 };
 /**
- * Verify the Ed25519 signature of an OTP payload segment.
- * `publicKey` is the PEM string read from the public key file.
+ * Create an in-process, single-use replay store backed by a `Set`.
+ * Scoped to whatever holds the reference (typically one provider instance).
  */
-export declare function verifyOtpSignature(payloadSegmentBase64url: string, signature: Buffer, publicKeyPem: string): boolean;
+export declare function createReplayStore(): ReplayStore;
 /**
- * Check whether a jti has already been consumed.
+ * The exact endpoint an OTP authorizes, plus the request it is bound to.
+ * `provider`/`method` may be omitted when `dotPath` uniquely identifies a
+ * single paid endpoint (it is resolved from `PAID_ENDPOINTS`).
+ */
+export interface OtpCall {
+    provider?: string;
+    method?: string;
+    dotPath: string;
+    request: Record<string, unknown>;
+    /** Time-to-live as seconds or a string like "10m". Defaults to 10m. */
+    ttl?: string | number;
+}
+/**
+ * Mint an OTP for a specific request, signed with the shared HMAC secret.
  *
- * @param jti - The OTP jti to check
- * @param ledgerPath - Optional override path; defaults to XDG_STATE_HOME or ~/.local/state
+ * Pure and env-free: the secret is passed explicitly. The OTP binds to the
+ * exact request via its canonical hash, so changing any byte of the request
+ * invalidates the token.
  */
-export declare function isJtiConsumed(jti: string, ledgerPath?: string): boolean;
+export declare function mintOtp(secret: string, call: OtpCall): string;
 /**
- * Append a jti to the replay ledger.
+ * Pure verification of an OTP against expected request context.
  *
- * @param jti - The OTP jti to consume
- * @param ledgerPath - Optional override path; defaults to XDG_STATE_HOME or ~/.local/state
+ * Returns a tagged-union `VerifyResult` — never throws. The caller is
+ * responsible for converting `{ ok: false }` into a `PayGateError` at the
+ * boundary.
  */
-export declare function consumeJti(jti: string, ledgerPath?: string): void;
+export declare function verifyOtp(input: VerifyOtpInput): VerifyResult;
 /**
  * Wrap a provider network dispatch with the OTP-based paid-endpoint gate.
  *
  * Free/unlisted endpoints return `dispatch()` immediately without OTP or
- * pay gate configuration.
+ * pay-gate configuration.
  *
  * Paid endpoints fail closed: if the pay gate is not configured, or the OTP
- * is missing, invalid, expired, replayed, mismatched, or the cost exceeds the
- * OTP's maxSpendUsd, the call throws before dispatch runs.
+ * is missing, invalid, expired, replayed, or mismatched, the call throws
+ * before dispatch runs. This is the "no bypass" guarantee — a paid call cannot
+ * fire without a configured secret and a valid, human/code-client-minted OTP.
+ *
+ * The OTP jti is consumed BEFORE dispatch. If dispatch later fails for any
+ * reason, the jti remains consumed and the caller must mint a fresh OTP to
+ * retry. This is intentional — without it, a hostile caller could replay an
+ * OTP on every transient failure.
  */
-export declare function dispatchWithPaidGate<T>(provider: string, method: string, dotPath: string, payload: Record<string, unknown>, approval: PayGateApproval | undefined, dispatch: () => Promise<T>): Promise<T>;
+export declare function dispatchWithPaidGate<T>(provider: string, method: string, dotPath: string, payload: Record<string, unknown>, approval: PayGateApproval | undefined, dispatch: () => Promise<T>, config?: PayGateConfig): Promise<T>;
 //# sourceMappingURL=paygate.d.ts.map

package/dist/src/paygate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paygate.d.ts","sourceRoot":"","sources":["../../src/paygate.ts"],"names":[],"mappings":"AAWA;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,CAAC,EAAE,CAAC,CAAC;IACL,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,UAAU,MAAM,EAAE,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EACT,wBAAwB,GACxB,aAAa,GACb,eAAe,GACf,uBAAuB,GACvB,aAAa,GACb,wBAAwB,GACxB,cAAc,CAAC;gBAGjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,EAC1B,OAAO,EAAE,MAAM;CASlB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAsCvD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,MAAM,EAAE,CAIhE;AAaD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG;IACrC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB,CAyCA;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,uBAAuB,EAAE,MAAM,EAC/B,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GACnB,OAAO,CAIT;AAaD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,EACX,UAAU,GAAE,MAA4B,GACvC,OAAO,CAkBT;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,MAAM,EACX,UAAU,GAAE,MAA4B,GACvC,IAAI,CAUN;AAuGD;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,EAAE,eAAe,GAAG,SAAS,EACrC,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CAsEZ"}
+{"version":3,"file":"paygate.d.ts","sourceRoot":"","sources":["../../src/paygate.ts"],"names":[],"mappings":"AASA;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,CAAC,EAAE,CAAC,CAAC;IACL,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,UAAU,MAAM,EAAE,CAAC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EACT,wBAAwB,GACxB,aAAa,GACb,eAAe,GACf,uBAAuB,GACvB,aAAa,GACb,wBAAwB,GACxB,cAAc,CAAC;gBAGjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,EAC1B,OAAO,EAAE,MAAM;CASlB;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GACzB,eAAe,GACf,uBAAuB,GACvB,aAAa,GACb,wBAAwB,GACxB,cAAc,CAAC;AAEnB;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE,WAAW,EAAE,UAAU,MAAM,EAAE,CAAC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CACzC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAsCvD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,MAAM,EAAE,CAIhE;AAuBD;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAqB5C;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG;IACrC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB,CA+BA;AAwBD;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,WAAW,CAQ/C;AAED;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAyCD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CA6B7D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY,CA8D7D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,EAAE,eAAe,GAAG,SAAS,EACrC,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC1B,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,CAAC,CAAC,CAkDZ"}