@paybond/kit 0.9.3 → 0.9.5

package/README.md

@@ -22,12 +22,27 @@ npm install @paybond/kit
 - A `paybond_sk_sandbox_...` or `paybond_sk_live_...` service-account API key
 - For intent creation or evidence submission: 32-byte Ed25519 signing seeds owned by your application
 
-Minimal environment for the quick start:
+Create a sandbox key for local development:
 
 ```bash
-export PAYBOND_API_KEY="paybond_sk_sandbox_..."
+npx -p @paybond/kit paybond login
 ```
 
+`paybond login` writes a sandbox `PAYBOND_API_KEY` to `.env.local` with file mode `0600`, adds the default `.env.local` target to `.gitignore` when needed, and refuses to overwrite an existing key unless `--force` is passed. Custom env-file paths inside a git repo must already be ignored. Live production keys are created by tenant admins in Console and stored in deployment secret managers.
+
+## First guardrail scaffold
+
+Use this first when you have a paid tool and want Paybond guardrails in the sandbox:
+
+```bash
+npx -p @paybond/kit paybond-init \
+  --preset paid-tool-guard \
+  --framework provider-agnostic \
+  --out paybond-paid-tool-guard.ts
+```
+
+The generated integration opens Paybond from the environment, loads `.env.local` when `PAYBOND_API_KEY` is not already present, bootstraps a sandbox guardrail intent, wraps your paid-tool handler, and submits sandbox evidence. It does not generate a paid-tool implementation. Free Developer is sandbox-only; live settlement rails start on paid production plans.
+
 ## Tenant isolation
 
 Every session is bound to the tenant realm echoed by gateway-authenticated service-account introspection.
@@ -73,31 +88,37 @@ const paybond = await Paybond.open({
   expectedEnvironment: "sandbox",
 });
 
-const created = await paybond.intents.create({
-  // principal, payee, budget, predicate, evidence schema, deadline...
-  allowedTools: ["travel.book_hotel"],
-  settlementRail: "stripe_connect",
+const guardrail = await paybond.guardrails.bootstrapSandbox({
+  operation: "travel.book_hotel",
+  requestedSpendCents: 20_000,
+  currency: "usd",
 });
 
-const intentId = String(created.intent_id);
-const capabilityToken = String(created.capability_token ?? "");
-if (!capabilityToken) {
-  throw new Error("fund the intent before guarding tools");
-}
-
-const guard = paybond.spendGuard(intentId, capabilityToken);
+const guard = paybond.spendGuard(guardrail.intent_id, guardrail.capability_token);
 const guardedTool = guard.guardTool(
-  { operation: "travel.book_hotel", requestedSpendCents: 20_000 },
+  {
+    operation: guardrail.operation,
+    requestedSpendCents: guardrail.requested_spend_cents,
+  },
   async (input) => bookHotel(input),
 );
+
+const result = await guardedTool({ hotelId: "hotel_123", maxPriceCents: 20_000 });
+await paybond.guardrails.submitSandboxEvidence({
+  intentId: guardrail.intent_id,
+  payload: { result, sandbox: true },
+});
 ```
 
-The `paybond.harbor` client is created by `Paybond.open(...)` and bound to the tenant resolved from the service-account API key. Normal integrations read `capability_token` from `paybond.intents.create(...)`, or from `paybond.intents.fund(...)` after an `x402_usdc_base` payment challenge is satisfied.
+The `paybond.harbor` and `paybond.guardrails` clients are created by `Paybond.open(...)` and bound to the tenant resolved from the service-account API key. Production integrations read `capability_token` from `paybond.intents.create(...)`, or from `paybond.intents.fund(...)` after an `x402_usdc_base` payment challenge is satisfied.
 
-Scaffold a wrapper:
+Scaffold a guardrail integration:
 
 ```bash
-npx -p @paybond/kit paybond-init --framework provider-agnostic --out paybond-spend-guard.ts
+npx -p @paybond/kit paybond-init \
+  --preset paid-tool-guard \
+  --framework provider-agnostic \
+  --out paybond-paid-tool-guard.ts
 ```
 
 ## What the package includes
@@ -117,8 +138,9 @@ Gateway and trust helpers:
 - `GatewaySignalClient` and `ServiceAccountSignalSession` for tenant-scoped Signal reads and signed portfolio artifacts
 - `GatewayFraudClient` and `ServiceAccountFraudSession` for tenant-scoped fraud assessments, review queues, review events, metrics, and release-gate config
 - Protocol-v2 helpers for mandate verification, replay-safe recognition proof verification, receipt reads, and A2A discovery
+- `paybond login` for sandbox device approval and local `.env.local` API-key setup
 - `paybond-mcp-server` for tenant-bound MCP tool exposure to any MCP-compatible host
-- `paybond-init` for generating a small spend guard wrapper
+- `paybond-init` for generating a Paybond guardrail integration helper
 
 Agent-facing surfaces are model-provider agnostic. Paybond verifies tool operations and tenant scope, not whether a tool call came from OpenAI, Anthropic, Gemini, a local model, or another runtime.
 
@@ -143,6 +165,7 @@ Gateway-backed protocol helpers throw `ProtocolHttpError` with parsed `errorCode
 ## Docs
 
 - Long-form docs: https://paybond.ai/docs/kit
+- One-command guardrails: https://paybond.ai/docs/kit/one-command-guardrails
 - TypeScript quickstart: https://paybond.ai/docs/kit/quickstart-typescript
 - TypeScript SDK reference: https://paybond.ai/docs/kit/sdk-reference-typescript
 - MCP server guide: https://paybond.ai/docs/kit/mcp-server

package/dist/index.d.ts

@@ -72,6 +72,49 @@ export type FundIntentResult = {
     capabilityToken?: string;
     funding?: IntentFundingResult;
 };
+export type SandboxGuardrailBootstrapInput = {
+    operation: string;
+    requestedSpendCents: number;
+    currency?: string;
+    evidenceSchema?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
+};
+export type SandboxGuardrailEvidenceInput = {
+    intentId: string;
+    payload?: Record<string, unknown>;
+    artifacts?: string[];
+    operation?: string;
+    requestedSpendCents?: number;
+    metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
+};
+export type SandboxGuardrailBootstrapResult = {
+    tenant_id: string;
+    intent_id: string;
+    capability_token: string;
+    operation: string;
+    requested_spend_cents: number;
+    sandbox_lifecycle_status: string;
+    currency?: string;
+    settlement_rail?: string;
+    settlement_mode?: string;
+    simulator_event?: unknown;
+};
+export type SandboxGuardrailEvidenceResult = {
+    tenant_id: string;
+    intent_id: string;
+    capability_token?: string;
+    operation: string;
+    requested_spend_cents: number;
+    sandbox_lifecycle_status: string;
+    settlement_rail?: string;
+    settlement_mode?: string;
+    predicate_passed?: boolean | null;
+    payload_digest?: string;
+    artifacts_digest?: string;
+    simulator_event?: unknown;
+};
 export declare const DEFAULT_PAYBOND_GATEWAY_BASE_URL = "https://api.paybond.ai";
 /** Async supplier for upstream Harbor bearer tokens on low-level direct clients. */
 export type HarborBearerSupplier = () => Promise<string | null | undefined>;
@@ -878,6 +921,28 @@ export declare class GatewayHarborClient {
     }): Promise<FundIntentResult>;
     submitEvidence(intentId: string, evidenceBody: Record<string, unknown>, options: GatewayHarborMutationOptions): Promise<SubmitEvidenceResult>;
 }
+type GatewaySandboxGuardrailsClientOptions = {
+    staticGatewayBearerToken: string;
+    maxRetries?: number;
+};
+/**
+ * Gateway sandbox guardrail helpers.
+ *
+ * These routes derive tenant scope only from the service-account bearer token and intentionally
+ * reject caller-supplied tenant IDs, including the normal `x-tenant-id` Gateway Harbor header.
+ */
+export declare class PaybondGuardrails {
+    private readonly base;
+    readonly tenantId: string;
+    private readonly bearerToken;
+    private readonly maxRetries;
+    constructor(gatewayBaseUrl: string, tenantId: string, options: GatewaySandboxGuardrailsClientOptions);
+    private headers;
+    private fetchWithRetries;
+    private postJSON;
+    bootstrapSandbox(input: SandboxGuardrailBootstrapInput): Promise<SandboxGuardrailBootstrapResult>;
+    submitSandboxEvidence(input: SandboxGuardrailEvidenceInput): Promise<SandboxGuardrailEvidenceResult>;
+}
 type GatewaySignalClientOptions = {
     staticGatewayBearerToken: string;
     maxRetries?: number;
@@ -1071,6 +1136,7 @@ export declare class PaybondIntents {
  */
 export declare class Paybond {
     readonly harbor: GatewayHarborClient;
+    readonly guardrails: PaybondGuardrails;
     readonly signal: GatewaySignalClient;
     readonly fraud: GatewayFraudClient;
     readonly a2a: GatewayA2AClient;

package/dist/index.js

@@ -801,6 +801,132 @@ export class GatewayHarborClient {
         return parseSubmitEvidenceResponse(JSON.parse(text));
     }
 }
+/**
+ * Gateway sandbox guardrail helpers.
+ *
+ * These routes derive tenant scope only from the service-account bearer token and intentionally
+ * reject caller-supplied tenant IDs, including the normal `x-tenant-id` Gateway Harbor header.
+ */
+export class PaybondGuardrails {
+    base;
+    tenantId;
+    bearerToken;
+    maxRetries;
+    constructor(gatewayBaseUrl, tenantId, options) {
+        this.base = normalizeBase(gatewayBaseUrl) + "/";
+        this.tenantId = tenantId.trim();
+        this.bearerToken = options.staticGatewayBearerToken.trim();
+        this.maxRetries = Math.max(1, options.maxRetries ?? 3);
+    }
+    headers(extra) {
+        const headers = new Headers(extra);
+        headers.set("accept", "application/json");
+        headers.set("authorization", `Bearer ${this.bearerToken}`);
+        return headers;
+    }
+    async fetchWithRetries(url, init) {
+        let lastErr;
+        for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+            let res;
+            try {
+                res = await fetch(url, init);
+            }
+            catch (e) {
+                lastErr = e;
+                if (attempt + 1 >= this.maxRetries)
+                    throw e;
+                await new Promise((r) => setTimeout(r, backoffMs(attempt)));
+                continue;
+            }
+            if ([429, 500, 502, 503, 504].includes(res.status) && attempt + 1 < this.maxRetries) {
+                const raSec = parseRetryAfterSeconds(res.headers.get("retry-after"));
+                const delayMs = raSec != null ? raSec * 1000 : backoffMs(attempt);
+                await new Promise((r) => setTimeout(r, delayMs));
+                continue;
+            }
+            return res;
+        }
+        throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+    }
+    async postJSON(path, payload, options) {
+        const url = `${this.base}${path.replace(/^\/+/, "")}`;
+        const extraHeaders = {
+            "content-type": "application/json",
+        };
+        if (options?.idempotencyKey?.trim()) {
+            extraHeaders["idempotency-key"] = options.idempotencyKey.trim();
+        }
+        const res = await this.fetchWithRetries(url, {
+            method: "POST",
+            headers: this.headers(extraHeaders),
+            body: JSON.stringify(payload),
+        });
+        const text = await res.text();
+        return { res, text, url };
+    }
+    async bootstrapSandbox(input) {
+        const payload = {
+            operation: input.operation,
+            requested_spend_cents: input.requestedSpendCents,
+        };
+        if (input.currency !== undefined) {
+            payload.currency = input.currency;
+        }
+        if (input.evidenceSchema !== undefined) {
+            payload.evidence_schema = input.evidenceSchema;
+        }
+        if (input.metadata !== undefined) {
+            payload.metadata = input.metadata;
+        }
+        const { res, text, url } = await this.postJSON("/v1/sandbox/guardrails/bootstrap", payload, { idempotencyKey: input.idempotencyKey });
+        if (!res.ok) {
+            throw new HarborHttpError(`Gateway sandbox guardrail bootstrap HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        return parseSandboxGuardrailBootstrapResponse(JSON.parse(text), {
+            tenantId: this.tenantId,
+            url,
+            bodyText: text,
+            statusCode: res.status,
+        });
+    }
+    async submitSandboxEvidence(input) {
+        const payload = {};
+        if (input.payload !== undefined) {
+            payload.payload = input.payload;
+        }
+        if (input.artifacts !== undefined) {
+            payload.artifacts = input.artifacts;
+        }
+        if (input.operation !== undefined) {
+            payload.operation = input.operation;
+        }
+        if (input.requestedSpendCents !== undefined) {
+            payload.requested_spend_cents = input.requestedSpendCents;
+        }
+        if (input.metadata !== undefined) {
+            payload.metadata = input.metadata;
+        }
+        const { res, text, url } = await this.postJSON(`/v1/sandbox/guardrails/${encodeURIComponent(input.intentId)}/evidence`, payload, { idempotencyKey: input.idempotencyKey });
+        if (!res.ok) {
+            throw new HarborHttpError(`Gateway sandbox guardrail evidence HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        return parseSandboxGuardrailEvidenceResponse(JSON.parse(text), {
+            tenantId: this.tenantId,
+            intentId: input.intentId,
+            url,
+            bodyText: text,
+            statusCode: res.status,
+        });
+    }
+}
 const DEFAULT_PRINCIPAL_PATH = "/v1/auth/principal";
 const SETTLEMENT_RAIL_VALUES = new Set(["stripe_connect", "stripe_ach_debit", "x402_usdc_base"]);
 const FRAUD_REVIEW_EVENT_TYPES = new Set([
@@ -878,6 +1004,78 @@ function parseSubmitEvidenceResponse(value) {
         predicatePassed: typeof body.predicate_passed === "boolean" ? body.predicate_passed : undefined,
     };
 }
+function parseSandboxGuardrailBootstrapResponse(value, init) {
+    const body = assertJSONObject(value);
+    const tenant = sandboxGuardrailString(body, "tenant_id", init);
+    if (tenant !== init.tenantId) {
+        throw new Error(`sandbox guardrail tenant mismatch: client=${init.tenantId} gateway=${tenant}`);
+    }
+    return {
+        tenant_id: tenant,
+        intent_id: sandboxGuardrailString(body, "intent_id", init),
+        capability_token: sandboxGuardrailString(body, "capability_token", init),
+        operation: sandboxGuardrailString(body, "operation", init),
+        requested_spend_cents: sandboxGuardrailNumber(body, "requested_spend_cents", init),
+        sandbox_lifecycle_status: sandboxGuardrailString(body, "sandbox_lifecycle_status", init),
+        currency: sandboxGuardrailOptionalString(body.currency),
+        settlement_rail: sandboxGuardrailOptionalString(body.settlement_rail),
+        settlement_mode: sandboxGuardrailOptionalString(body.settlement_mode),
+        simulator_event: body.simulator_event,
+    };
+}
+function parseSandboxGuardrailEvidenceResponse(value, init) {
+    const body = assertJSONObject(value);
+    const tenant = sandboxGuardrailString(body, "tenant_id", init);
+    if (tenant !== init.tenantId) {
+        throw new Error(`sandbox guardrail tenant mismatch: client=${init.tenantId} gateway=${tenant}`);
+    }
+    const intentId = sandboxGuardrailString(body, "intent_id", init);
+    if (intentId !== init.intentId) {
+        throw new Error(`sandbox guardrail intent mismatch: requested=${init.intentId} gateway=${intentId}`);
+    }
+    const predicatePassedRaw = body.predicate_passed;
+    return {
+        tenant_id: tenant,
+        intent_id: intentId,
+        capability_token: sandboxGuardrailOptionalString(body.capability_token),
+        operation: sandboxGuardrailString(body, "operation", init),
+        requested_spend_cents: sandboxGuardrailNumber(body, "requested_spend_cents", init),
+        sandbox_lifecycle_status: sandboxGuardrailString(body, "sandbox_lifecycle_status", init),
+        settlement_rail: sandboxGuardrailOptionalString(body.settlement_rail),
+        settlement_mode: sandboxGuardrailOptionalString(body.settlement_mode),
+        predicate_passed: typeof predicatePassedRaw === "boolean" || predicatePassedRaw === null
+            ? predicatePassedRaw
+            : undefined,
+        payload_digest: sandboxGuardrailOptionalString(body.payload_digest),
+        artifacts_digest: sandboxGuardrailOptionalString(body.artifacts_digest),
+        simulator_event: body.simulator_event,
+    };
+}
+function sandboxGuardrailString(body, field, init) {
+    const value = body[field];
+    if (typeof value === "string" && value.trim()) {
+        return value;
+    }
+    throw new HarborHttpError(`Gateway sandbox guardrail response missing ${field}`, {
+        statusCode: init.statusCode,
+        url: init.url,
+        bodyText: init.bodyText,
+    });
+}
+function sandboxGuardrailOptionalString(value) {
+    return typeof value === "string" && value.trim() ? value : undefined;
+}
+function sandboxGuardrailNumber(body, field, init) {
+    const value = body[field];
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    throw new HarborHttpError(`Gateway sandbox guardrail response missing ${field}`, {
+        statusCode: init.statusCode,
+        url: init.url,
+        bodyText: init.bodyText,
+    });
+}
 function parseIntentFundingResult(value) {
     const body = assertJSONObject(value);
     const onchainRaw = body.onchain_transaction_hashes;
@@ -1795,13 +1993,15 @@ export class PaybondIntents {
  */
 export class Paybond {
     harbor;
+    guardrails;
     signal;
     fraud;
     a2a;
     protocol;
     intents;
-    constructor(harbor, signal, fraud, a2a, protocol) {
+    constructor(harbor, guardrails, signal, fraud, a2a, protocol) {
         this.harbor = harbor;
+        this.guardrails = guardrails;
         this.signal = signal;
         this.fraud = fraud;
         this.a2a = a2a;
@@ -1817,6 +2017,10 @@ export class Paybond {
             staticGatewayBearerToken: init.apiKey,
             maxRetries,
         });
+        const guardrails = new PaybondGuardrails(gatewayBaseUrl, tenantId, {
+            staticGatewayBearerToken: init.apiKey,
+            maxRetries,
+        });
         const signal = new GatewaySignalClient(gatewayBaseUrl, tenantId, {
             staticGatewayBearerToken: init.apiKey,
             maxRetries,
@@ -1833,7 +2037,7 @@ export class Paybond {
             staticGatewayBearerToken: init.apiKey,
             maxRetries,
         });
-        return new Paybond(harbor, signal, fraud, a2a, protocol);
+        return new Paybond(harbor, guardrails, signal, fraud, a2a, protocol);
     }
     /** Reserved for future HTTP client cleanup; safe to call after work completes. */
     async aclose() {