@paybond/kit 0.9.3 → 0.9.5

package/dist/login.js

@@ -0,0 +1,454 @@
+#!/usr/bin/env node
+const DEFAULT_GATEWAY = "https://api.paybond.ai";
+const DEFAULT_ENV_FILE = ".env.local";
+const CLIENT_ID = "paybond-kit-cli";
+const CLIENT_NAME = "Paybond CLI";
+const DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+const MIN_POLL_INTERVAL_SECONDS = 1;
+class PaybondLoginError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PaybondLoginError";
+    }
+}
+class OAuthPollError extends PaybondLoginError {
+    code;
+    interval;
+    constructor(body) {
+        super(body.error_description?.trim() || body.error);
+        this.name = "OAuthPollError";
+        this.code = body.error;
+        this.interval = body.interval;
+    }
+}
+function usage() {
+    return [
+        "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 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") {
+        return value;
+    }
+    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) {
+        throw new PaybondLoginError(`missing command: login\n\n${usage()}`);
+    }
+    const [command, ...rest] = argv;
+    if (command === "--help" || command === "-h") {
+        return "help";
+    }
+    if (command !== "login") {
+        throw new PaybondLoginError(`unknown command: ${command}\n\n${usage()}`);
+    }
+    let envFile = DEFAULT_ENV_FILE;
+    let gateway = DEFAULT_GATEWAY;
+    let environment = "sandbox";
+    let noOpen = false;
+    let force = false;
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        if (arg === "--help" || arg === "-h") {
+            return "help";
+        }
+        if (arg === "--no-open") {
+            noOpen = true;
+            continue;
+        }
+        if (arg === "--force") {
+            force = true;
+            continue;
+        }
+        if (arg === "--live") {
+            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)");
+            }
+            environment = parseEnvironment(raw);
+            continue;
+        }
+        if (arg === "--env-file" || arg.startsWith("--env-file=")) {
+            const raw = arg === "--env-file" ? rest[++i] : arg.slice("--env-file=".length);
+            if (!raw || raw.startsWith("-")) {
+                throw new PaybondLoginError("invalid --env-file");
+            }
+            envFile = raw;
+            continue;
+        }
+        if (arg === "--gateway" || arg.startsWith("--gateway=")) {
+            const raw = arg === "--gateway" ? rest[++i] : arg.slice("--gateway=".length);
+            if (!raw || raw.startsWith("-")) {
+                throw new PaybondLoginError("invalid --gateway");
+            }
+            gateway = raw;
+            continue;
+        }
+        throw new PaybondLoginError(`unknown argument: ${arg}`);
+    }
+    if (!envFile.trim()) {
+        throw new PaybondLoginError("invalid --env-file");
+    }
+    if (!gateway.trim()) {
+        throw new PaybondLoginError("invalid --gateway");
+    }
+    return { envFile, gateway, environment, noOpen, force };
+}
+function envKeyPattern() {
+    return /^\s*(?:export\s+)?PAYBOND_API_KEY\s*=/m;
+}
+function quoteEnvValue(value) {
+    if (/^[A-Za-z0-9_./:@+-]+$/.test(value)) {
+        return value;
+    }
+    return JSON.stringify(value);
+}
+function replaceOrAppendEnvValue(existing, rawKey, force) {
+    const line = `PAYBOND_API_KEY=${quoteEnvValue(rawKey)}`;
+    const pattern = /^(\s*(?:export\s+)?PAYBOND_API_KEY\s*=).*$/m;
+    if (pattern.test(existing)) {
+        if (!force) {
+            throw new PaybondLoginError("PAYBOND_API_KEY already exists in the target env file; pass --force to replace it.");
+        }
+        return existing.replace(pattern, line);
+    }
+    const suffix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    return `${existing}${suffix}${line}\n`;
+}
+async function pathModule() {
+    // @ts-expect-error Node builtins are available in the published CLI runtime.
+    return await import("node:path");
+}
+async function fsModule() {
+    // @ts-expect-error Node builtins are available in the published CLI runtime.
+    return await import("node:fs/promises");
+}
+async function spawnCommand(command, args, cwd) {
+    // @ts-expect-error Node builtins are available in the published CLI runtime.
+    const childProcess = await import("node:child_process");
+    return await new Promise((resolve) => {
+        const child = childProcess.spawn(command, args, {
+            cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += String(chunk);
+        });
+        child.on("error", (err) => {
+            resolve({ code: 127, stdout: "", stderr: err.message });
+        });
+        child.on("close", (code) => {
+            resolve({ code, stdout, stderr });
+        });
+    });
+}
+async function resolveEnvFile(envFile, cwd) {
+    const path = await pathModule();
+    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);
+    if (rootResult.code !== 0) {
+        return;
+    }
+    const repoRoot = await fs.realpath(path.resolve(rootResult.stdout.trim()));
+    const targetDir = await fs.realpath(path.dirname(path.resolve(envPath)));
+    const target = path.resolve(targetDir, path.basename(envPath));
+    const relativeTarget = path.relative(repoRoot, target);
+    if (relativeTarget !== "" && (relativeTarget.startsWith("..") || path.isAbsolute(relativeTarget))) {
+        return;
+    }
+    const ignoreResult = await spawnCommand("git", ["-C", repoRoot, "check-ignore", "--quiet", "--", relativeTarget], cwd);
+    if (ignoreResult.code === 0) {
+        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"}`);
+}
+export async function assertCanWriteEnvFile(envPath, force) {
+    const fs = await fsModule();
+    try {
+        const existing = await fs.readFile(envPath, "utf8");
+        if (envKeyPattern().test(existing) && !force) {
+            throw new PaybondLoginError("PAYBOND_API_KEY already exists in the target env file; pass --force to replace it.");
+        }
+    }
+    catch (err) {
+        if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+            return;
+        }
+        throw err;
+    }
+}
+export async function writeEnvFile(envPath, rawKey, force) {
+    const fs = await fsModule();
+    let existing = "";
+    try {
+        existing = await fs.readFile(envPath, "utf8");
+    }
+    catch (err) {
+        if (!(err && typeof err === "object" && "code" in err && err.code === "ENOENT")) {
+            throw err;
+        }
+    }
+    const next = replaceOrAppendEnvValue(existing, rawKey, force);
+    await fs.writeFile(envPath, next, { encoding: "utf8", mode: 0o600 });
+    await fs.chmod(envPath, 0o600);
+}
+function gatewayUrl(base, path) {
+    return `${base.trim().replace(/\/+$/, "")}${path}`;
+}
+async function parseJsonResponse(response) {
+    const text = await response.text();
+    if (!text.trim()) {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Fall through to the shaped error below.
+    }
+    throw new PaybondLoginError(`Gateway returned non-JSON response (${response.status}).`);
+}
+function stringField(body, field) {
+    const value = body[field];
+    return typeof value === "string" ? value.trim() : "";
+}
+function numberField(body, field, fallback) {
+    const value = body[field];
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+async function postGatewayJson(fetchFn, gateway, path, body) {
+    const response = await fetchFn(gatewayUrl(gateway, path), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    const parsed = await parseJsonResponse(response);
+    if (response.ok) {
+        return parsed;
+    }
+    const error = stringField(parsed, "error");
+    if (error) {
+        throw new OAuthPollError({
+            error,
+            error_description: stringField(parsed, "error_description") || stringField(parsed, "message"),
+            interval: numberField(parsed, "interval", 0) || undefined,
+        });
+    }
+    throw new PaybondLoginError(`Gateway ${path} HTTP ${response.status}.`);
+}
+function toDeviceStartResponse(body) {
+    const response = {
+        device_code: stringField(body, "device_code"),
+        user_code: stringField(body, "user_code"),
+        verification_uri: stringField(body, "verification_uri"),
+        verification_uri_complete: stringField(body, "verification_uri_complete") || undefined,
+        expires_in: numberField(body, "expires_in", 600),
+        interval: numberField(body, "interval", 5),
+    };
+    if (!response.device_code || !response.user_code || !response.verification_uri) {
+        throw new PaybondLoginError("Gateway device start response was missing required fields.");
+    }
+    return response;
+}
+function toDeviceTokenResponse(body, environment) {
+    const response = {
+        access_token: stringField(body, "access_token"),
+        token_type: stringField(body, "token_type"),
+        tenant_id: stringField(body, "tenant_id"),
+        tenant_uuid: stringField(body, "tenant_uuid"),
+        environment: stringField(body, "environment"),
+        service_account_role: stringField(body, "service_account_role"),
+        expires_at: stringField(body, "expires_at"),
+    };
+    if (!response.access_token || !response.tenant_id || !response.tenant_uuid) {
+        throw new PaybondLoginError("Gateway device token response was missing required fields.");
+    }
+    if (response.environment !== environment) {
+        throw new PaybondLoginError(`Gateway returned a ${response.environment || "unknown"} key but ${environment} was requested.`);
+    }
+    if (response.service_account_role !== "operator") {
+        throw new PaybondLoginError(`Gateway returned a non-operator key (${response.service_account_role || "unknown"}).`);
+    }
+    if (!response.access_token.startsWith(`paybond_sk_${environment}_`)) {
+        throw new PaybondLoginError(`Gateway returned an unexpected ${environment} API key shape.`);
+    }
+    return response;
+}
+async function startDeviceFlow(fetchFn, gateway, environment) {
+    const body = await postGatewayJson(fetchFn, gateway, "/v1/public/auth/device/start", {
+        client_id: CLIENT_ID,
+        client_name: CLIENT_NAME,
+        requested_environment: environment,
+        service_account_role: "operator",
+    });
+    return toDeviceStartResponse(body);
+}
+async function pollDeviceToken(fetchFn, gateway, environment, start, deps) {
+    let intervalSeconds = Math.max(MIN_POLL_INTERVAL_SECONDS, Math.trunc(start.interval || 5));
+    const expiresAtMs = deps.now() + Math.max(1, start.expires_in) * 1000;
+    for (;;) {
+        await deps.sleep(intervalSeconds * 1000);
+        if (deps.now() > expiresAtMs + 1000) {
+            throw new PaybondLoginError("Device authorization expired before approval.");
+        }
+        try {
+            const body = await postGatewayJson(fetchFn, gateway, "/v1/public/auth/device/token", {
+                grant_type: DEVICE_GRANT_TYPE,
+                device_code: start.device_code,
+                client_id: CLIENT_ID,
+            });
+            return toDeviceTokenResponse(body, environment);
+        }
+        catch (err) {
+            if (!(err instanceof OAuthPollError)) {
+                throw err;
+            }
+            if (err.code === "authorization_pending") {
+                intervalSeconds = Math.max(intervalSeconds, Math.trunc(err.interval || intervalSeconds));
+                continue;
+            }
+            if (err.code === "slow_down") {
+                intervalSeconds = Math.max(intervalSeconds + MIN_POLL_INTERVAL_SECONDS, Math.trunc(err.interval || 0));
+                continue;
+            }
+            if (err.code === "access_denied") {
+                throw new PaybondLoginError("Device authorization was denied.");
+            }
+            if (err.code === "expired_token") {
+                throw new PaybondLoginError("Device authorization expired before approval.");
+            }
+            throw new PaybondLoginError(err.message);
+        }
+    }
+}
+function maskAPIKey(rawKey) {
+    const trimmed = rawKey.trim();
+    const parts = trimmed.split("_");
+    if (parts.length >= 5 && parts[0] === "paybond" && parts[1] === "sk") {
+        const environment = parts[2];
+        const keyID = parts[3];
+        const redactedKeyID = keyID.length > 12 ? `${keyID.slice(0, 8)}...${keyID.slice(-4)}` : "redacted";
+        return `paybond_sk_${environment}_${redactedKeyID}`;
+    }
+    return "paybond_sk_...";
+}
+async function defaultSleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function defaultOpenBrowser(url) {
+    const platform = process.platform;
+    const command = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+    const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+    const result = await spawnCommand(command, args, process.cwd());
+    return result.code === 0;
+}
+export async function runLogin(options, deps = {}) {
+    const cwd = deps.cwd ?? process.cwd();
+    const stdout = deps.stdout ?? process.stdout;
+    const fetchFn = deps.fetch ?? fetch;
+    const sleep = deps.sleep ?? defaultSleep;
+    const now = deps.now ?? Date.now;
+    const openBrowser = deps.openBrowser ?? defaultOpenBrowser;
+    const envPath = await resolveEnvFile(options.envFile, cwd);
+    await assertCanWriteEnvFile(envPath, options.force);
+    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`);
+    stdout.write(`Verification URL: ${verificationUrl}\n`);
+    stdout.write(`Code: ${start.user_code}\n`);
+    if (!options.noOpen) {
+        const opened = await openBrowser(verificationUrl);
+        if (!opened) {
+            stdout.write(`Open the verification URL in a browser to approve this login.\n`);
+        }
+    }
+    stdout.write(`Waiting for approval...\n`);
+    const token = await pollDeviceToken(fetchFn, options.gateway, options.environment, start, { sleep, now });
+    await writeEnvFile(envPath, token.access_token, options.force);
+    stdout.write(`Wrote PAYBOND_API_KEY to ${envPath}\n`);
+    stdout.write(`Key: ${maskAPIKey(token.access_token)}\n`);
+    stdout.write(`Target ${token.environment} tenant: ${token.tenant_id} (${token.tenant_uuid})\n`);
+    if (token.expires_at) {
+        stdout.write(`This key auto-expires at ${token.expires_at}; re-run paybond login to mint a new one.\n`);
+    }
+    return 0;
+}
+export async function main(argv = process.argv.slice(2), deps = {}) {
+    let parsed;
+    try {
+        parsed = parseArgs(argv);
+        if (parsed === "help") {
+            (deps.stdout ?? process.stdout).write(`${usage()}\n`);
+            return 0;
+        }
+        return await runLogin(parsed, deps);
+    }
+    catch (err) {
+        (deps.stderr ?? process.stderr).write(`${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+}
+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);
+}
+if (invokedFromCLI()) {
+    main().then((code) => {
+        process.exitCode = code;
+    }, (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;
@@ -204,6 +235,59 @@ class PaybondMCPRuntime {
         }
         return body;
     }
+    async bootstrapSandboxGuardrail(init) {
+        const expectedTenant = await this.tenantId();
+        const payload = {
+            operation: init.operation,
+            requested_spend_cents: init.requestedSpendCents,
+        };
+        if (init.currency?.trim()) {
+            payload.currency = init.currency.trim();
+        }
+        if (init.evidenceSchema !== undefined) {
+            payload.evidence_schema = init.evidenceSchema;
+        }
+        if (init.metadata !== undefined) {
+            payload.metadata = init.metadata;
+        }
+        const body = await this.gateway.postJSON("/v1/sandbox/guardrails/bootstrap", payload, optionalMutationHeaders(init.idempotencyKey));
+        assertSandboxGuardrailTenant(body, expectedTenant);
+        stringArg(body.intent_id, "intent_id");
+        stringArg(body.capability_token, "capability_token");
+        stringArg(body.operation, "operation");
+        intArg(body.requested_spend_cents, "requested_spend_cents");
+        stringArg(body.sandbox_lifecycle_status, "sandbox_lifecycle_status");
+        return body;
+    }
+    async submitSandboxGuardrailEvidence(init) {
+        const expectedTenant = await this.tenantId();
+        const payload = {};
+        if (init.payload !== undefined) {
+            payload.payload = init.payload;
+        }
+        if (init.artifacts !== undefined) {
+            payload.artifacts = init.artifacts;
+        }
+        if (init.operation?.trim()) {
+            payload.operation = init.operation.trim();
+        }
+        if (init.requestedSpendCents !== undefined) {
+            payload.requested_spend_cents = init.requestedSpendCents;
+        }
+        if (init.metadata !== undefined) {
+            payload.metadata = init.metadata;
+        }
+        const body = await this.gateway.postJSON(`/v1/sandbox/guardrails/${encodeURIComponent(init.intentId)}/evidence`, payload, optionalMutationHeaders(init.idempotencyKey));
+        assertSandboxGuardrailTenant(body, expectedTenant);
+        const echoedIntent = stringArg(body.intent_id, "intent_id");
+        if (echoedIntent !== init.intentId) {
+            throw new Error(`sandbox guardrail intent mismatch: requested=${init.intentId} gateway=${echoedIntent}`);
+        }
+        stringArg(body.operation, "operation");
+        intArg(body.requested_spend_cents, "requested_spend_cents");
+        stringArg(body.sandbox_lifecycle_status, "sandbox_lifecycle_status");
+        return body;
+    }
     async verifyAgentMandateV1(signedMandate) {
         return this.gateway.postJSON("/protocol/v2/mandates/verify", signedMandate, {
             "x-tenant-id": await this.tenantId(),
@@ -495,6 +579,56 @@ export class PaybondMCPServer {
                         : intArg(args.requested_spend_cents, "requested_spend_cents"),
                 }),
             },
+            {
+                name: "paybond_bootstrap_sandbox_guardrail",
+                description: "Bootstrap a sandbox-only Paybond guardrail intent for a first paid-tool integration. Tenant scope is derived from the configured service-account API key and the route never touches live settlement rails.",
+                inputSchema: objectSchema({
+                    operation: { type: "string", description: "Delegated operation or paid tool name." },
+                    requested_spend_cents: {
+                        type: "integer",
+                        description: "Sandbox spend amount in cents to authorize for the sample tool call.",
+                    },
+                    currency: { type: "string", description: "Optional ISO currency code; defaults at the gateway." },
+                    evidence_schema: { type: "object", additionalProperties: true },
+                    metadata: { type: "object", additionalProperties: true },
+                    idempotency_key: { type: "string" },
+                }, ["operation", "requested_spend_cents"]),
+                call: async (args) => this.runtime.bootstrapSandboxGuardrail({
+                    operation: stringArg(args.operation, "operation"),
+                    requestedSpendCents: intArg(args.requested_spend_cents, "requested_spend_cents"),
+                    currency: optionalString(args.currency),
+                    evidenceSchema: args.evidence_schema === undefined ? undefined : ensureObject(args.evidence_schema, "evidence_schema"),
+                    metadata: args.metadata === undefined ? undefined : ensureObject(args.metadata, "metadata"),
+                    idempotencyKey: optionalString(args.idempotency_key),
+                }),
+            },
+            {
+                name: "paybond_submit_sandbox_guardrail_evidence",
+                description: "Submit evidence for a sandbox-only Paybond guardrail intent. Tenant scope is derived from the configured service-account API key and simulator settlement remains sandbox-only.",
+                inputSchema: objectSchema({
+                    intent_id: { type: "string", description: "Sandbox guardrail intent UUID." },
+                    payload: { type: "object", additionalProperties: true },
+                    artifacts: { type: "array", items: { type: "string" } },
+                    operation: { type: "string", description: "Optional operation override for the evidence record." },
+                    requested_spend_cents: {
+                        type: "integer",
+                        description: "Optional sandbox spend amount override for the evidence record.",
+                    },
+                    metadata: { type: "object", additionalProperties: true },
+                    idempotency_key: { type: "string" },
+                }, ["intent_id"]),
+                call: async (args) => this.runtime.submitSandboxGuardrailEvidence({
+                    intentId: uuidArg(args.intent_id, "intent_id"),
+                    payload: args.payload === undefined ? undefined : ensureObject(args.payload, "payload"),
+                    artifacts: args.artifacts === undefined ? undefined : stringArrayArg(args.artifacts, "artifacts"),
+                    operation: optionalString(args.operation),
+                    requestedSpendCents: args.requested_spend_cents === undefined
+                        ? undefined
+                        : intArg(args.requested_spend_cents, "requested_spend_cents"),
+                    metadata: args.metadata === undefined ? undefined : ensureObject(args.metadata, "metadata"),
+                    idempotencyKey: optionalString(args.idempotency_key),
+                }),
+            },
             {
                 name: "paybond_list_intents",
                 description: "List tenant-scoped Harbor intents through the gateway operator view with optional filters.",
@@ -742,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)
@@ -820,6 +955,18 @@ function uuidArg(value, field) {
     }
     return raw;
 }
+function stringArrayArg(value, field) {
+    if (!Array.isArray(value)) {
+        throw new Error(`${field} must be an array`);
+    }
+    return value.map((item, index) => stringArg(item, `${field}[${index}]`));
+}
+function assertSandboxGuardrailTenant(body, expectedTenant) {
+    const echoedTenant = stringArg(body.tenant_id, "tenant_id");
+    if (echoedTenant !== expectedTenant) {
+        throw new Error(`sandbox guardrail tenant mismatch: expected=${expectedTenant} gateway=${echoedTenant}`);
+    }
+}
 function encodeRecognitionProofHeader(proof) {
     return Buffer.from(JSON.stringify(proof), "utf8").toString("base64url");
 }
@@ -899,13 +1046,16 @@ function formatError(err) {
     }
     return String(err);
 }
+function normalizeFileURL(url) {
+    return url.startsWith("file:///var/") ? url.replace("file:///var/", "file:///private/var/") : url;
+}
 const isMainModule = (() => {
     const scriptPath = process.argv[1];
     if (!scriptPath) {
         return false;
     }
     try {
-        return import.meta.url === new URL(scriptPath, "file://").href;
+        return normalizeFileURL(import.meta.url) === normalizeFileURL(new URL("file://" + scriptPath).href);
     }
     catch {
         return import.meta.url.endsWith(scriptPath);

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@paybond/kit",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "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",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
+    "paybond": "dist/login.js",
     "paybond-init": "dist/init.js",
     "paybond-mcp-server": "dist/mcp-server.js"
   },