@proxy-checkout/cli 0.1.0-prx-128.104.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Linus Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# Proxy CLI
+
+`@proxy-checkout/cli` publishes the `proxy` binary: a revocable, capability-scoped command foundation for developers and agents. The first workflow relays real, Proxy-signed test webhooks to localhost and can optionally orchestrate Stripe CLI through a temporary Proxy ingress.
+
+Requires Node.js 22 or newer and has no production npm dependencies.
+
+## Install and authenticate
+
+```bash
+npm install --global @proxy-checkout/cli
+
+proxy auth login \
+  --profile my-app-test \
+  --merchant merch_... \
+  --mode test
+
+proxy auth status \
+  --profile my-app-test \
+  --merchant merch_... \
+  --mode test
+```
+
+Authentication uses an RFC 8628 browser/device handoff. Proxy exchanges the short-lived approved browser session for a distinct `pcli_test_...` credential, revokes the temporary session, and stores only the CLI credential. The CLI never persists a Portal session or exposes a merchant `sk_test_*` key.
+
+Profiles bind the saved API origin, organization, merchant, and mode. `--merchant` and `--mode` assert the target returned by login or remote credential introspection; they do not select or elevate a merchant client-side. Stored credentials cannot be sent to a different API origin.
+
+macOS uses the built-in Security framework and Keychain; supported Linux desktops use Secret Service. Native-store writes pass over stdin, never process arguments or environment. When neither native store is available, the CLI warns and uses an owner-only `0600` file under the user's data directory. Agents and CI can inject `PROXY_CLI_TOKEN` without writing a credential locally.
+
+All grants issued in this release and all operational/resource commands are test-only. `auth status` and `auth logout` are mode-neutral safety controls so a future separately issued live grant can still be inspected and revoked. This release does not issue live grants, and `--mode live` on login or a resource command exits `5` with `cli_live_mode_not_enabled` before authentication or resource creation. The credential/verifier, profiles, command registry, and policies model mode explicitly so future live commands can require a separate live-bound grant, capability, and command intent without redesigning auth.
+
+## Listen for Proxy webhooks
+
+An active HTTPS source endpoint must already exist. Its selected event types, schema version, and signing-secret identity are cloned server-side; the CLI never receives the signing secret.
+
+```bash
+proxy webhooks endpoints list --profile my-app-test --format json
+
+proxy listen \
+  --profile my-app-test \
+  --merchant merch_... \
+  --mode test \
+  --endpoint whend_... \
+  --forward-to http://127.0.0.1:3000/webhooks
+```
+
+The listener has a two-minute lease renewed every 30 seconds. Proxy prepares the canonical body and signature headers, the CLI forwards those exact bytes to the loopback URL, and the server records the real local outcome in its normal attempt/retry state machine. The source HTTPS endpoint continues to receive its independent normal delivery. Only `localhost`, `127.0.0.1`, and `::1` HTTP(S) destinations are allowed.
+
+Control-C closes the listener. Logout closes resources owned by the credential. The server expires abandoned listeners after a crash.
+
+## Optional Stripe CLI orchestration
+
+Install and authenticate [Stripe CLI](https://docs.stripe.com/stripe-cli), then run:
+
+```bash
+stripe login
+
+proxy listen \
+  --stripe \
+  --stripe-psp-config pspcfg_... \
+  --profile my-app-test \
+  --merchant merch_... \
+  --mode test \
+  --endpoint whend_... \
+  --forward-to http://127.0.0.1:3000/webhooks
+```
+
+The Stripe signing secret is captured only in child-process memory, never echoed or placed in argv, and stored only inside Proxy's existing encrypted temporary PSP ingress boundary. The CLI never receives the merchant's Stripe API credential. Both the Stripe ingress and local listener close on exit or expire server-side after a crash.
+
+## Advanced delivery controls
+
+Use the one-command listener for normal work. Explicit controls make retry, duplicate, replay, and ordering tests deterministic:
+
+```bash
+proxy webhooks listeners create --endpoint whend_... --profile my-app-test
+proxy webhooks listeners heartbeat --listener whend_... --profile my-app-test
+proxy webhooks deliveries list --listener whend_... --profile my-app-test --format json
+
+proxy webhooks deliveries forward \
+  --listener whend_... \
+  --delivery whdel_... \
+  --forward-to http://127.0.0.1:3000/webhooks \
+  --profile my-app-test
+
+proxy webhooks deliveries replay \
+  --listener whend_... \
+  --delivery whdel_... \
+  --reason "verify duplicate handling" \
+  --profile my-app-test
+
+# Read replay.outbox_event_id from the previous JSON result.
+proxy webhooks deliveries forward \
+  --listener whend_... \
+  --replay-outbox out_... \
+  --forward-to http://127.0.0.1:3000/webhooks \
+  --profile my-app-test
+
+proxy webhooks listeners close --listener whend_... --profile my-app-test
+```
+
+Manual listeners require an explicit heartbeat while active. Selecting delivery IDs permits intentional out-of-order claims. Replay creates fresh canonical work/signing while preserving original delivery history and recording the actor/reason; pass its returned outbox ID to `deliveries forward --replay-outbox` when no managed `proxy listen` process is active. Application handlers must remain idempotent.
+
+## Agent and library use
+
+Every command uses the same versioned registry exported by this package:
+
+```bash
+proxy commands schema --format json
+proxy auth status --schema --format json
+proxy --llms-full
+```
+
+Non-TTY output defaults to JSON Lines. Pass `--format json` for one-shot JSON, `--format jsonl` for event streams, and `--no-input` with explicit endpoint/merchant/mode flags to prohibit prompts. Errors use stable machine codes; process exit codes are exported as `cliExitCodes`.
+
+The package boundary also exports `runCli`, `commandSchemas`, `commandSchemaDocument`, `findCommandSchema`, `llmsFullDocument`, `CliConfigStore`, `CliError`, and their public types. A future MCP or skill adapter can invoke the same command layer and inspect the same schemas instead of scraping terminal prose.
+
+| Exit | Meaning |
+| ---: | --- |
+| `0` | Success |
+| `2` | Usage/validation |
+| `3` | Authentication |
+| `4` | Network/API |
+| `5` | Capability/merchant/mode denied |
+| `6` | Conflict/non-claimable state |
+| `7` | Missing or unauthenticated dependency |
+| `8` | Interrupted |
+| `10` | Internal error |
+
+For local or preview APIs, pass `--api-base https://...`. Plain HTTP is accepted only for loopback development. See the public [Local webhooks guide](https://docs.proxycheckout.com/guides/local-webhooks/) for handler verification, troubleshooting, and full safety behavior.

package/dist/cjs/auth.d.cts

@@ -0,0 +1,38 @@
+import type { CliConfigStore, CliProfile } from "./config.js";
+import type { CliOutput } from "./output.js";
+interface CredentialExchangeResponse {
+    credential: string;
+    profile: {
+        api_version: string;
+        capability_version: number;
+        credential_id: string;
+        expires_at: string | null;
+        merchant_id: string;
+        mode: "test" | "live";
+        name: string;
+        organization_id: string;
+    };
+}
+export declare function login(input: {
+    apiBaseUrl: string;
+    configStore: CliConfigStore;
+    expectedMerchantId?: string;
+    expectedMode?: "live" | "test";
+    name?: string;
+    noBrowser: boolean;
+    output: CliOutput;
+    profileName: string;
+    signal?: AbortSignal;
+}): Promise<CliProfile>;
+export declare function status(input: {
+    apiBaseUrl: string;
+    token: string;
+}): Promise<CredentialExchangeResponse["profile"]>;
+export declare function logout(input: {
+    apiBaseUrl: string;
+    configStore: CliConfigStore;
+    profileName: string;
+    removeLocalProfile: boolean;
+    token: string;
+}): Promise<void>;
+export {};

package/dist/cjs/auth.d.ts

@@ -0,0 +1,38 @@
+import type { CliConfigStore, CliProfile } from "./config.js";
+import type { CliOutput } from "./output.js";
+interface CredentialExchangeResponse {
+    credential: string;
+    profile: {
+        api_version: string;
+        capability_version: number;
+        credential_id: string;
+        expires_at: string | null;
+        merchant_id: string;
+        mode: "test" | "live";
+        name: string;
+        organization_id: string;
+    };
+}
+export declare function login(input: {
+    apiBaseUrl: string;
+    configStore: CliConfigStore;
+    expectedMerchantId?: string;
+    expectedMode?: "live" | "test";
+    name?: string;
+    noBrowser: boolean;
+    output: CliOutput;
+    profileName: string;
+    signal?: AbortSignal;
+}): Promise<CliProfile>;
+export declare function status(input: {
+    apiBaseUrl: string;
+    token: string;
+}): Promise<CredentialExchangeResponse["profile"]>;
+export declare function logout(input: {
+    apiBaseUrl: string;
+    configStore: CliConfigStore;
+    profileName: string;
+    removeLocalProfile: boolean;
+    token: string;
+}): Promise<void>;
+export {};

package/dist/cjs/auth.js

@@ -0,0 +1,258 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.login = login;
+exports.status = status;
+exports.logout = logout;
+const node_child_process_1 = require("node:child_process");
+const node_os_1 = require("node:os");
+const errors_js_1 = require("./errors.js");
+const http_client_js_1 = require("./http-client.js");
+const clientId = "proxy-cli";
+const deviceScope = "proxy.cli.local-webhook-development";
+const deviceGrantType = "urn:ietf:params:oauth:grant-type:device_code";
+async function login(input) {
+    const signal = input.signal ?? new AbortController().signal;
+    const client = new http_client_js_1.ProxyApiClient(input.apiBaseUrl);
+    const codeResult = await client.oauthRequest("/api/auth/device/code", {
+        client_id: clientId,
+        scope: deviceScope,
+    }, { signal });
+    const device = requireDeviceCode(codeResult);
+    const verificationUrl = validateVerificationUrl(device.verification_uri_complete);
+    input.output.event("auth.device_code", {
+        expires_in: device.expires_in,
+        user_code: device.user_code,
+        verification_uri: device.verification_uri,
+        verification_uri_complete: verificationUrl,
+    }, `Your pairing code is ${device.user_code}. Approve it at ${verificationUrl}`);
+    if (!input.noBrowser) {
+        const opened = await openBrowser(verificationUrl);
+        if (!opened) {
+            input.output.notice("Could not open a browser automatically; use the approval URL above.");
+        }
+    }
+    const temporarySession = await pollForDeviceToken(client, device, input.output, signal);
+    const approved = parseApprovedScope(temporarySession.scope);
+    const exchangeClient = new http_client_js_1.ProxyApiClient(input.apiBaseUrl, temporarySession.access_token);
+    const exchanged = await exchangeClient.request("/cli/auth/exchange", {
+        method: "POST",
+        signal,
+        body: {
+            approval_id: approved.approvalId,
+            merchant_id: approved.merchantId,
+            name: normalizeCredentialName(input.name),
+            user_code: device.user_code,
+        },
+    });
+    const profile = requireExchangeProfile(exchanged.profile, input.apiBaseUrl);
+    if (input.expectedMerchantId && profile.merchantId !== input.expectedMerchantId) {
+        const mismatch = new errors_js_1.CliError("The approved CLI credential does not match the requested merchant", "cli_merchant_not_allowed", errors_js_1.cliExitCodes.permission);
+        await revokeExchangedCredential(input.apiBaseUrl, exchanged.credential, profile, mismatch);
+        throw mismatch;
+    }
+    if (input.expectedMode && profile.mode !== input.expectedMode) {
+        const mismatch = new errors_js_1.CliError("The approved CLI credential does not match the requested mode", input.expectedMode === "live" ? "cli_live_mode_not_enabled" : "cli_mode_not_allowed", errors_js_1.cliExitCodes.permission);
+        await revokeExchangedCredential(input.apiBaseUrl, exchanged.credential, profile, mismatch);
+        throw mismatch;
+    }
+    try {
+        const saved = await input.configStore.saveProfile(input.profileName, profile, exchanged.credential);
+        if (saved.credentialStore === "file") {
+            input.output.notice("Warning: native credential storage is unavailable; the CLI credential is in an owner-only (0600) file fallback.");
+        }
+        return saved;
+    }
+    catch (error) {
+        await revokeExchangedCredential(input.apiBaseUrl, exchanged.credential, profile, error);
+        throw error;
+    }
+}
+async function revokeExchangedCredential(apiBaseUrl, credential, profile, originalError) {
+    try {
+        await new http_client_js_1.ProxyApiClient(apiBaseUrl, credential).request("/cli/auth/logout", {
+            method: "POST",
+        });
+    }
+    catch (cleanupError) {
+        throw new errors_js_1.CliError(`Login did not complete and cleanup of credential ${profile.credentialId} could not be confirmed; revoke it in the Proxy Portal`, "cli_credential_cleanup_failed", errors_js_1.cliExitCodes.network, {
+            cleanup_error_class: cleanupError instanceof Error ? cleanupError.name : typeof cleanupError,
+            credential_id: profile.credentialId,
+            original_error_class: originalError instanceof Error ? originalError.name : typeof originalError,
+            original_error_code: originalError instanceof errors_js_1.CliError ? originalError.code : undefined,
+        });
+    }
+}
+async function status(input) {
+    const response = await new http_client_js_1.ProxyApiClient(input.apiBaseUrl, input.token).request("/cli/auth/status");
+    return response.profile;
+}
+async function logout(input) {
+    await new http_client_js_1.ProxyApiClient(input.apiBaseUrl, input.token).request("/cli/auth/logout", {
+        method: "POST",
+    });
+    if (input.removeLocalProfile) {
+        await input.configStore.removeProfile(input.profileName);
+    }
+}
+async function pollForDeviceToken(client, device, output, signal) {
+    const expiresAt = Date.now() + device.expires_in * 1_000;
+    let intervalMs = Math.max(1, device.interval) * 1_000;
+    while (Date.now() < expiresAt) {
+        await delay(intervalMs, signal);
+        const response = await client.oauthRequest("/api/auth/device/token", {
+            client_id: clientId,
+            device_code: device.device_code,
+            grant_type: deviceGrantType,
+        }, { signal });
+        if (response.ok) {
+            return requireDeviceToken(response.body);
+        }
+        const errorCode = readString(response.body, "error");
+        if (errorCode === "authorization_pending") {
+            continue;
+        }
+        if (errorCode === "slow_down") {
+            intervalMs += 5_000;
+            continue;
+        }
+        if (errorCode === "access_denied") {
+            throw new errors_js_1.CliError("Device authorization was denied", "cli_device_access_denied", errors_js_1.cliExitCodes.authentication);
+        }
+        if (errorCode === "expired_token") {
+            throw deviceExpired();
+        }
+        output.notice("The authentication service rejected the device exchange.");
+        throw new errors_js_1.CliError("Device authorization failed", "cli_device_authorization_failed", errors_js_1.cliExitCodes.authentication, { oauth_error: errorCode });
+    }
+    throw deviceExpired();
+}
+function requireDeviceCode(result) {
+    if (!result.ok ||
+        !isRecord(result.body) ||
+        !readString(result.body, "device_code") ||
+        !readString(result.body, "user_code") ||
+        !readString(result.body, "verification_uri") ||
+        !readString(result.body, "verification_uri_complete") ||
+        !readNumber(result.body, "expires_in") ||
+        !readNumber(result.body, "interval")) {
+        throw new errors_js_1.CliError("Proxy authentication returned an invalid device code", "cli_invalid_auth_response", errors_js_1.cliExitCodes.network, { status: result.status });
+    }
+    return result.body;
+}
+function requireDeviceToken(value) {
+    if (!isRecord(value) ||
+        readString(value, "token_type")?.toLowerCase() !== "bearer" ||
+        !readString(value, "access_token") ||
+        !readString(value, "scope")) {
+        throw new errors_js_1.CliError("Proxy authentication returned an invalid temporary session", "cli_invalid_auth_response", errors_js_1.cliExitCodes.network);
+    }
+    return value;
+}
+function parseApprovedScope(scope) {
+    const parts = new Set(scope.split(/\s+/));
+    const approval = [...parts].find((part) => part.startsWith("approval:"));
+    const merchant = [...parts].find((part) => part.startsWith("merchant:"));
+    if (!parts.has(deviceScope) ||
+        !parts.has("mode:test") ||
+        !approval?.startsWith("approval:cliappr_") ||
+        !merchant?.startsWith("merchant:merch_")) {
+        throw new errors_js_1.CliError("Device approval did not contain the required test-merchant capability grant", "cli_invalid_approval_scope", errors_js_1.cliExitCodes.permission);
+    }
+    return {
+        approvalId: approval.slice("approval:".length),
+        merchantId: merchant.slice("merchant:".length),
+    };
+}
+function requireExchangeProfile(profile, apiBaseUrl) {
+    if (profile.mode !== "test" ||
+        typeof profile.api_version !== "string" ||
+        profile.api_version.length === 0 ||
+        !Number.isSafeInteger(profile.capability_version) ||
+        profile.capability_version < 1 ||
+        !profile.credential_id.startsWith("apk_") ||
+        !profile.merchant_id.startsWith("merch_") ||
+        !profile.organization_id.startsWith("org_") ||
+        typeof profile.name !== "string" ||
+        profile.name.length < 1 ||
+        profile.name.length > 80 ||
+        (profile.expires_at !== null && Number.isNaN(Date.parse(profile.expires_at)))) {
+        throw new errors_js_1.CliError("Proxy returned an invalid or non-test CLI grant", "cli_invalid_credential_grant", errors_js_1.cliExitCodes.permission);
+    }
+    return {
+        apiBaseUrl,
+        apiVersion: profile.api_version,
+        capabilityVersion: profile.capability_version,
+        credentialId: profile.credential_id,
+        expiresAt: profile.expires_at,
+        merchantId: profile.merchant_id,
+        mode: profile.mode,
+        name: profile.name,
+        organizationId: profile.organization_id,
+    };
+}
+function normalizeCredentialName(name) {
+    const value = name?.trim() || `Proxy CLI on ${(0, node_os_1.hostname)()}`;
+    if (value.length > 80) {
+        throw new errors_js_1.CliError("Credential name must be at most 80 characters", "cli_credential_name_invalid", errors_js_1.cliExitCodes.usage);
+    }
+    return value;
+}
+function validateVerificationUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new errors_js_1.CliError("Proxy returned an invalid browser approval URL", "cli_invalid_auth_response", errors_js_1.cliExitCodes.network);
+    }
+    const loopback = ["127.0.0.1", "::1", "localhost"].includes(url.hostname);
+    if ((url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) ||
+        url.username ||
+        url.password) {
+        throw new errors_js_1.CliError("Proxy returned an unsafe browser approval URL", "cli_invalid_auth_response", errors_js_1.cliExitCodes.network);
+    }
+    return url.toString();
+}
+async function openBrowser(url) {
+    const command = (0, node_os_1.platform)() === "darwin" ? "open" : (0, node_os_1.platform)() === "win32" ? "cmd" : "xdg-open";
+    const args = (0, node_os_1.platform)() === "win32" ? ["/c", "start", "", url] : [url];
+    return new Promise((resolve) => {
+        const child = (0, node_child_process_1.spawn)(command, args, { detached: true, shell: false, stdio: "ignore" });
+        child.once("error", () => resolve(false));
+        child.once("spawn", () => {
+            child.unref();
+            resolve(true);
+        });
+    });
+}
+function deviceExpired() {
+    return new errors_js_1.CliError("Device authorization expired", "cli_device_authorization_expired", errors_js_1.cliExitCodes.authentication);
+}
+function readString(value, key) {
+    return isRecord(value) && typeof value[key] === "string" ? value[key] : undefined;
+}
+function readNumber(value, key) {
+    return isRecord(value) && typeof value[key] === "number" ? value[key] : undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function delay(milliseconds, signal) {
+    if (signal.aborted)
+        return Promise.reject(authInterrupted());
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", onAbort);
+            reject(authInterrupted());
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, milliseconds);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function authInterrupted() {
+    return new errors_js_1.CliError("Device authorization interrupted", "cli_auth_interrupted", errors_js_1.cliExitCodes.interrupted);
+}

package/dist/cjs/bin.d.cts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cjs/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cjs/bin.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const cli_js_1 = require("./cli.js");
+void (0, cli_js_1.runCli)(process.argv.slice(2)).then((exitCode) => {
+    process.exitCode = exitCode;
+}, () => {
+    process.stderr.write("Proxy CLI failed unexpectedly.\n");
+    process.exitCode = 10;
+});

package/dist/cjs/cli.d.cts

@@ -0,0 +1,10 @@
+import { CliConfigStore } from "./config.js";
+import { type CliIo } from "./output.js";
+export declare const cliVersion = "0.1.0-prx-128.104.1";
+export interface RunCliOptions {
+    configStore?: CliConfigStore;
+    environment?: NodeJS.ProcessEnv;
+    io?: CliIo;
+    signal?: AbortSignal;
+}
+export declare function runCli(argv: readonly string[], options?: RunCliOptions): Promise<number>;

package/dist/cjs/cli.d.ts

@@ -0,0 +1,10 @@
+import { CliConfigStore } from "./config.js";
+import { type CliIo } from "./output.js";
+export declare const cliVersion = "0.1.0-prx-128.104.1";
+export interface RunCliOptions {
+    configStore?: CliConfigStore;
+    environment?: NodeJS.ProcessEnv;
+    io?: CliIo;
+    signal?: AbortSignal;
+}
+export declare function runCli(argv: readonly string[], options?: RunCliOptions): Promise<number>;