@paybond/kit 0.9.4 → 0.9.6

package/README.md

@@ -28,17 +28,20 @@ Create a sandbox key for local development:
 npx -p @paybond/kit paybond login
 ```
 
-`paybond login` writes `PAYBOND_API_KEY` to `.env.local` with file mode `0600`, refuses to overwrite an existing key unless `--force` is passed, and refuses env files that are not ignored by git. Live production keys are created by tenant admins in Console and stored in deployment secret managers.
+`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-guardrail-demo.ts
+npx -p @paybond/kit paybond-init \
+  --preset paid-tool-guard \
+  --framework provider-agnostic \
+  --out paybond-paid-tool-guard.ts
 ```
 
-The generated demo opens Paybond, bootstraps a sandbox guardrail intent, wraps one replaceable paid-tool handler, submits sandbox evidence, and prints the lifecycle result. Free Developer is sandbox-only; live settlement rails start on paid production plans.
+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
 
@@ -100,7 +103,7 @@ const guardedTool = guard.guardTool(
   async (input) => bookHotel(input),
 );
 
-const result = await guardedTool({ hotelId: "hotel_demo", maxPriceCents: 20_000 });
+const result = await guardedTool({ hotelId: "hotel_123", maxPriceCents: 20_000 });
 await paybond.guardrails.submitSandboxEvidence({
   intentId: guardrail.intent_id,
   payload: { result, sandbox: true },
@@ -112,7 +115,10 @@ The `paybond.harbor` and `paybond.guardrails` clients are created by `Paybond.op
 Scaffold a guardrail integration:
 
 ```bash
-npx -p @paybond/kit paybond-init --preset paid-tool-guard --framework provider-agnostic --out paybond-guardrail-demo.ts
+npx -p @paybond/kit paybond-init \
+  --preset paid-tool-guard \
+  --framework provider-agnostic \
+  --out paybond-paid-tool-guard.ts
 ```
 
 ## What the package includes
@@ -134,7 +140,7 @@ Gateway and trust helpers:
 - 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 Paybond guardrail integration with a sandbox smoke path
+- `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.
 

package/dist/init.js

@@ -26,15 +26,15 @@ const FRAMEWORK_NOTES = {
 };
 function usage() {
     return [
-        "Usage: paybond-init [--preset paid-tool-guard] [--framework generic|provider-agnostic|openai|claude|anthropic|gemini|google-ai|vercel-ai|langgraph|mcp] [--out paybond-guardrail-demo.ts] [--force]",
+        "Usage: paybond-init [--preset paid-tool-guard] [--framework generic|provider-agnostic|openai|claude|anthropic|gemini|google-ai|vercel-ai|langgraph|mcp] [--out paybond-paid-tool-guard.ts] [--force]",
         "",
-        "Scaffolds a production-shaped Paybond guardrail integration with a sandbox smoke path.",
+        "Scaffolds a production-shaped Paybond guardrail integration helper.",
     ].join("\n");
 }
 function parseArgs(argv) {
     let preset = "paid-tool-guard";
     let framework = "provider-agnostic";
-    let out = "paybond-guardrail-demo.ts";
+    let out = "paybond-paid-tool-guard.ts";
     let force = false;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
@@ -85,7 +85,13 @@ function template(framework) {
   type SandboxGuardrailEvidenceResult,
 } from "@paybond/kit";
 
-const DEFAULT_OPERATION = "paid_tool.smoke_test";
+declare const process: {
+  env: Record<string, string | undefined>;
+};
+
+// Production integration helpers only. Add your paid-tool handler in
+// application code and pass it to wrapPaidTool(...).
+const DEFAULT_OPERATION = "paid_tool.operation";
 const DEFAULT_REQUESTED_SPEND_CENTS = 500;
 
 export type PaidToolHandler<TInput, TResult> = (input: TInput) => TResult | Promise<TResult>;
@@ -107,22 +113,59 @@ export type SubmitSandboxEvidenceOptions = {
   idempotencyKey?: string;
 };
 
-export type SmokePaidToolInput = {
-  itemId: string;
-  maxPriceCents: number;
+export type OpenPaybondFromEnvOptions = {
+  /**
+   * Load PAYBOND_API_KEY from this local env file when the process environment
+   * does not already provide it. Pass false when your agent host injects secrets.
+   */
+  envFile?: string | false;
 };
 
-export type SmokePaidToolResult = {
-  confirmationId: string;
-  itemId: string;
-  chargedCents: number;
-  sandbox: true;
-};
+function readEnvValue(body: string, key: string): string | undefined {
+  const pattern = new RegExp("^\\\\s*(?:export\\\\s+)?" + key + "\\\\s*=\\\\s*(.*)$", "m");
+  const match = body.match(pattern);
+  if (!match) return undefined;
+  let value = (match[1] ?? "").trim();
+  if (value.startsWith('"') && value.endsWith('"')) {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      value = value.slice(1, -1);
+    }
+  } else if (value.startsWith("'") && value.endsWith("'")) {
+    value = value.slice(1, -1);
+  }
+  return value.trim() || undefined;
+}
+
+async function readTextFile(envFile: string): Promise<string | undefined> {
+  // @ts-ignore Node builtins are available in agent and CLI Node runtimes.
+  const fs: { readFile(path: string, encoding: "utf8"): Promise<string> } = await import("node:fs/promises");
+  try {
+    return await fs.readFile(envFile, "utf8");
+  } catch (err) {
+    if ((err as { code?: unknown })?.code === "ENOENT") return undefined;
+    throw err;
+  }
+}
 
-export async function openPaybondFromEnv(): Promise<Paybond> {
+export async function loadPaybondEnvFile(envFile = ".env.local"): Promise<void> {
+  if (process.env.PAYBOND_API_KEY?.trim()) return;
+  const body = await readTextFile(envFile);
+  if (body === undefined) return;
+  const apiKey = readEnvValue(body, "PAYBOND_API_KEY");
+  if (apiKey) {
+    process.env.PAYBOND_API_KEY = apiKey;
+  }
+}
+
+export async function openPaybondFromEnv(options: OpenPaybondFromEnvOptions = {}): Promise<Paybond> {
+  if (options.envFile !== false) {
+    await loadPaybondEnvFile(options.envFile ?? ".env.local");
+  }
   const apiKey = process.env.PAYBOND_API_KEY?.trim();
   if (!apiKey) {
-    throw new Error("PAYBOND_API_KEY is required");
+    throw new Error("PAYBOND_API_KEY is required; run paybond login or configure your agent host to pass it");
   }
 
   return Paybond.open({
@@ -193,56 +236,6 @@ export async function submitSandboxEvidence(
     idempotencyKey: options.idempotencyKey,
   });
 }
-
-export async function replaceableSmokeTestPaidTool(
-  input: SmokePaidToolInput,
-): Promise<SmokePaidToolResult> {
-  // Replace this sandbox smoke-test function with the real paid side-effecting tool.
-  return {
-    confirmationId: "sandbox-confirmation-" + input.itemId,
-    itemId: input.itemId,
-    chargedCents: Math.min(input.maxPriceCents, DEFAULT_REQUESTED_SPEND_CENTS),
-    sandbox: true,
-  };
-}
-
-export async function runSandboxSmokePath(): Promise<{
-  guardrail: SandboxGuardrailBootstrapResult;
-  toolResult: SmokePaidToolResult;
-  evidence: SandboxGuardrailEvidenceResult;
-}> {
-  const paybond = await openPaybondFromEnv();
-  const guardrail = await bootstrapSandboxGuardrailIntent(paybond);
-  const guardedTool = wrapPaidTool(paybond, guardrail, replaceableSmokeTestPaidTool);
-  const toolResult = await guardedTool({
-    itemId: "replace-with-your-tool-input",
-    maxPriceCents: DEFAULT_REQUESTED_SPEND_CENTS,
-  });
-  const evidence = await submitSandboxEvidence(paybond, guardrail, {
-    confirmation_id: toolResult.confirmationId,
-    charged_cents: toolResult.chargedCents,
-    item_id: toolResult.itemId,
-    sandbox: toolResult.sandbox,
-  });
-  return { guardrail, toolResult, evidence };
-}
-
-async function main(): Promise<void> {
-  const result = await runSandboxSmokePath();
-  console.log(JSON.stringify(result, null, 2));
-}
-
-function normalizeFileURL(url: string): string {
-  return url.startsWith("file:///var/") ? url.replace("file:///var/", "file:///private/var/") : url;
-}
-
-const invokedPath = process.argv[1] ? normalizeFileURL(new URL("file://" + process.argv[1]).href) : "";
-if (invokedPath && normalizeFileURL(import.meta.url) === invokedPath) {
-  main().catch((err) => {
-    console.error(err instanceof Error ? err.message : String(err));
-    process.exitCode = 1;
-  });
-}
 `;
 }
 async function writeScaffold(out, body, force) {
@@ -288,15 +281,41 @@ export async function main(argv = process.argv.slice(2)) {
 function normalizeFileURL(url) {
     return url.startsWith("file:///var/") ? url.replace("file:///var/", "file:///private/var/") : url;
 }
-function invokedFromCLI() {
-    const invokedPath = process.argv[1] ? normalizeFileURL(new URL("file://" + process.argv[1]).href) : "";
-    return Boolean(invokedPath && normalizeFileURL(import.meta.url) === invokedPath);
+async function invokedFromCLI() {
+    const scriptPath = process.argv[1];
+    if (!scriptPath) {
+        return false;
+    }
+    // @ts-ignore Node builtins are available in the published CLI runtime.
+    const fs = (await import("node:fs/promises"));
+    // @ts-ignore Node builtins are available in the published CLI runtime.
+    const path = (await import("node:path"));
+    // @ts-ignore Node builtins are available in the published CLI runtime.
+    const url = (await import("node:url"));
+    async function realFileURL(filePath) {
+        let resolved = path.resolve(filePath);
+        try {
+            resolved = await fs.realpath(resolved);
+        }
+        catch {
+            // If realpath fails, compare the absolute path. This keeps direct execution
+            // working even when the script path disappears during process startup.
+        }
+        return normalizeFileURL(url.pathToFileURL(resolved).href);
+    }
+    return (await realFileURL(scriptPath)) === (await realFileURL(url.fileURLToPath(import.meta.url)));
 }
-if (invokedFromCLI()) {
+invokedFromCLI().then((invoked) => {
+    if (!invoked) {
+        return;
+    }
     main().then((code) => {
         process.exitCode = code;
     }, (err) => {
         process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
         process.exitCode = 1;
     });
-}
+}, (err) => {
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+});

package/dist/login.d.ts

@@ -2,7 +2,7 @@
 type Writable = {
     write(chunk: string): boolean;
 };
-export type DeviceEnvironment = "sandbox" | "live";
+export type DeviceEnvironment = "sandbox";
 export type LoginOptions = {
     envFile: string;
     gateway: string;

package/dist/login.js

@@ -23,19 +23,22 @@ class OAuthPollError extends PaybondLoginError {
 }
 function usage() {
     return [
-        "Usage: paybond login [--env sandbox|live] [--env-file .env.local] [--gateway https://api.paybond.ai] [--no-open] [--force]",
+        "Usage: paybond login [--env sandbox] [--env-file .env.local] [--gateway https://api.paybond.ai] [--no-open] [--force]",
         "",
-        "Starts a device login and writes PAYBOND_API_KEY to an ignored env file.",
-        "Defaults to the sandbox environment. Pass --env live to mint a production operator key;",
-        "a tenant admin must approve it from an active live console session.",
+        "Starts a device login and writes PAYBOND_API_KEY to a local env file.",
+        "The default .env.local target is added to .gitignore when needed.",
+        "Defaults to the sandbox environment. Production keys are created in Console and stored in secret managers.",
     ].join("\n");
 }
 function parseEnvironment(raw) {
     const value = raw.trim().toLowerCase();
-    if (value === "sandbox" || value === "live") {
+    if (value === "sandbox") {
         return value;
     }
-    throw new PaybondLoginError("invalid --env (expected sandbox or live)");
+    if (value === "live") {
+        throw new PaybondLoginError("live device login is not supported; create production keys in Console and store them in a secret manager");
+    }
+    throw new PaybondLoginError("invalid --env (expected sandbox)");
 }
 export function parseArgs(argv) {
     if (argv.length === 0) {
@@ -67,13 +70,12 @@ export function parseArgs(argv) {
             continue;
         }
         if (arg === "--live") {
-            environment = "live";
-            continue;
+            throw new PaybondLoginError("live device login is not supported; create production keys in Console and store them in a secret manager");
         }
         if (arg === "--env" || arg.startsWith("--env=")) {
             const raw = arg === "--env" ? rest[++i] : arg.slice("--env=".length);
             if (!raw || raw.startsWith("-")) {
-                throw new PaybondLoginError("invalid --env (expected sandbox or live)");
+                throw new PaybondLoginError("invalid --env (expected sandbox)");
             }
             environment = parseEnvironment(raw);
             continue;
@@ -162,6 +164,9 @@ async function resolveEnvFile(envFile, cwd) {
     return path.isAbsolute(envFile) ? path.resolve(envFile) : path.resolve(cwd, envFile);
 }
 export async function assertGitIgnored(envPath, cwd) {
+    await ensureGitIgnored(envPath, cwd, false);
+}
+async function ensureGitIgnored(envPath, cwd, autoAddDefaultEnvFile) {
     const path = await pathModule();
     const fs = await fsModule();
     const rootResult = await spawnCommand("git", ["rev-parse", "--show-toplevel"], cwd);
@@ -180,6 +185,24 @@ export async function assertGitIgnored(envPath, cwd) {
         return;
     }
     if (ignoreResult.code === 1) {
+        if (autoAddDefaultEnvFile && relativeTarget === DEFAULT_ENV_FILE) {
+            const gitignorePath = path.resolve(repoRoot, ".gitignore");
+            let existing = "";
+            try {
+                existing = await fs.readFile(gitignorePath, "utf8");
+            }
+            catch (err) {
+                if (!(err && typeof err === "object" && "code" in err && err.code === "ENOENT")) {
+                    throw err;
+                }
+            }
+            const suffix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+            await fs.writeFile(gitignorePath, `${existing}${suffix}${DEFAULT_ENV_FILE}\n`, { encoding: "utf8", mode: 0o644 });
+            const recheck = await spawnCommand("git", ["-C", repoRoot, "check-ignore", "--quiet", "--", relativeTarget], cwd);
+            if (recheck.code === 0) {
+                return;
+            }
+        }
         throw new PaybondLoginError(`Refusing to write ${target} because it is not ignored by git. Add ${relativeTarget} to .gitignore or pass --env-file pointing outside the repo.`);
     }
     throw new PaybondLoginError(`Unable to verify git ignore status for ${target}: ${ignoreResult.stderr.trim() || "git check-ignore failed"}`);
@@ -376,14 +399,10 @@ export async function runLogin(options, deps = {}) {
     const openBrowser = deps.openBrowser ?? defaultOpenBrowser;
     const envPath = await resolveEnvFile(options.envFile, cwd);
     await assertCanWriteEnvFile(envPath, options.force);
-    await assertGitIgnored(envPath, cwd);
+    await ensureGitIgnored(envPath, cwd, options.envFile === DEFAULT_ENV_FILE);
     const start = await startDeviceFlow(fetchFn, options.gateway, options.environment);
     const verificationUrl = start.verification_uri_complete || start.verification_uri;
     stdout.write(`Paybond ${options.environment} login\n`);
-    if (options.environment === "live") {
-        stdout.write(`WARNING: this mints a PRODUCTION operator API key with access to live tenant data and money movement.\n`);
-        stdout.write(`A tenant admin must approve it from an active live console session and confirm the live environment.\n`);
-    }
     stdout.write(`Verification URL: ${verificationUrl}\n`);
     stdout.write(`Code: ${start.user_code}\n`);
     if (!options.noOpen) {
@@ -421,15 +440,41 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
 function normalizeFileURL(url) {
     return url.startsWith("file:///var/") ? url.replace("file:///var/", "file:///private/var/") : url;
 }
-function invokedFromCLI() {
-    const invokedPath = process.argv[1] ? normalizeFileURL(new URL("file://" + process.argv[1]).href) : "";
-    return Boolean(invokedPath && normalizeFileURL(import.meta.url) === invokedPath);
+async function invokedFromCLI() {
+    const scriptPath = process.argv[1];
+    if (!scriptPath) {
+        return false;
+    }
+    // @ts-ignore Node builtins are available in the published CLI runtime.
+    const fs = (await import("node:fs/promises"));
+    // @ts-ignore Node builtins are available in the published CLI runtime.
+    const path = (await import("node:path"));
+    // @ts-ignore Node builtins are available in the published CLI runtime.
+    const url = (await import("node:url"));
+    async function realFileURL(filePath) {
+        let resolved = path.resolve(filePath);
+        try {
+            resolved = await fs.realpath(resolved);
+        }
+        catch {
+            // If realpath fails, compare the absolute path. This keeps direct execution
+            // working even when the script path disappears during process startup.
+        }
+        return normalizeFileURL(url.pathToFileURL(resolved).href);
+    }
+    return (await realFileURL(scriptPath)) === (await realFileURL(url.fileURLToPath(import.meta.url)));
 }
-if (invokedFromCLI()) {
+invokedFromCLI().then((invoked) => {
+    if (!invoked) {
+        return;
+    }
     main().then((code) => {
         process.exitCode = code;
     }, (err) => {
         process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
         process.exitCode = 1;
     });
-}
+}, (err) => {
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+});

package/dist/mcp-server.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+// @ts-ignore Node builtins are available in the published CLI runtime.
+import { readFileSync } from "node:fs";
 import { GatewayAuthError, GatewayFraudClient, GatewaySignalClient, SignalHttpError, DEFAULT_PAYBOND_GATEWAY_BASE_URL, } from "./index.js";
 const SERVER_NAME = "Paybond MCP";
 const SERVER_VERSION = "0.6.0";
@@ -6,6 +8,35 @@ const MCP_PROTOCOL_VERSION = "2025-11-25";
 const DEFAULT_PRINCIPAL_PATH = "/v1/auth/principal";
 const DEFAULT_RECOGNITION_VERIFIER_ID = "paybond-gateway";
 const agentRecognitionProofHeader = "x-paybond-agent-recognition-proof";
+const DEFAULT_ENV_FILE = ".env.local";
+function readEnvFileValue(envFile, key) {
+    let body;
+    try {
+        body = readFileSync(envFile, "utf8");
+    }
+    catch (err) {
+        if (err?.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+    const pattern = new RegExp("^\\s*(?:export\\s+)?" + key + "\\s*=\\s*(.*)$", "m");
+    const match = body.match(pattern);
+    if (!match)
+        return undefined;
+    let value = String(match[1] ?? "").trim();
+    if (value.startsWith('"') && value.endsWith('"')) {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            value = value.slice(1, -1);
+        }
+    }
+    else if (value.startsWith("'") && value.endsWith("'")) {
+        value = value.slice(1, -1);
+    }
+    return value.trim() || undefined;
+}
 class GatewayHTTPError extends Error {
     statusCode;
     url;
@@ -845,12 +876,13 @@ export class PaybondMCPServer {
     }
 }
 export function settingsFromEnv(env = process.env) {
-    const apiKey = String(env.PAYBOND_API_KEY ?? "").trim();
+    const envFile = optionalEnv(env.PAYBOND_ENV_FILE) ?? DEFAULT_ENV_FILE;
+    const apiKey = String(env.PAYBOND_API_KEY ?? readEnvFileValue(envFile, "PAYBOND_API_KEY") ?? "").trim();
     if (!apiKey) {
-        throw new Error("PAYBOND_API_KEY is required");
+        throw new Error("PAYBOND_API_KEY is required; run paybond login or configure your MCP host environment");
     }
     return {
-        gatewayBaseUrl: DEFAULT_PAYBOND_GATEWAY_BASE_URL,
+        gatewayBaseUrl: optionalEnv(env.PAYBOND_GATEWAY_BASE_URL) ?? DEFAULT_PAYBOND_GATEWAY_BASE_URL,
         apiKey,
         principalPath: optionalEnv(env.PAYBOND_PRINCIPAL_PATH) ?? DEFAULT_PRINCIPAL_PATH,
         maxRetries: optionalEnv(env.PAYBOND_MCP_MAX_RETRIES)
@@ -1017,18 +1049,35 @@ function formatError(err) {
 function normalizeFileURL(url) {
     return url.startsWith("file:///var/") ? url.replace("file:///var/", "file:///private/var/") : url;
 }
-const isMainModule = (() => {
+async function invokedFromCLI() {
     const scriptPath = process.argv[1];
     if (!scriptPath) {
         return false;
     }
-    try {
-        return normalizeFileURL(import.meta.url) === normalizeFileURL(new URL("file://" + scriptPath).href);
+    // @ts-ignore Node builtins are available in the published CLI runtime.
+    const fs = (await import("node:fs/promises"));
+    // @ts-ignore Node builtins are available in the published CLI runtime.
+    const path = (await import("node:path"));
+    // @ts-ignore Node builtins are available in the published CLI runtime.
+    const url = (await import("node:url"));
+    async function realFileURL(filePath) {
+        let resolved = path.resolve(filePath);
+        try {
+            resolved = await fs.realpath(resolved);
+        }
+        catch {
+            // If realpath fails, compare the absolute path. This keeps direct execution
+            // working even when the script path disappears during process startup.
+        }
+        return normalizeFileURL(url.pathToFileURL(resolved).href);
     }
-    catch {
-        return import.meta.url.endsWith(scriptPath);
+    return (await realFileURL(scriptPath)) === (await realFileURL(url.fileURLToPath(import.meta.url)));
+}
+invokedFromCLI().then((invoked) => {
+    if (invoked && main() !== 0) {
+        process.exitCode = 1;
     }
-})();
-if (isMainModule && main() !== 0) {
+}, (err) => {
+    process.stderr.write(`${formatError(err)}\n`);
     process.exitCode = 1;
-}
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paybond/kit",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "description": "Paybond Kit for TypeScript: agent spend governance for paid tool calls with spend authorization, evidence receipts, refunds, disputes, hosted Gateway sessions, and settlement.",
   "license": "Apache-2.0",
   "type": "module",