@stripe/link-cli 0.9.0 → 0.10.0

package/README.md

@@ -63,11 +63,12 @@ Link CLI can run as a local MCP server. Add the following to your MCP client con
 Use `serve` to expose link-cli as an MCP endpoint over HTTP. This is useful for remote or containerised agents that can't launch a local subprocess.
 
 ```bash
-link-cli serve            # listens on port 54321 by default
+link-cli serve            # binds 127.0.0.1:54321 (loopback only)
 link-cli serve --port 8080
+link-cli serve --host 0.0.0.0   # expose beyond localhost (see warning below)
 ```
 
-The MCP endpoint is available at `/mcp` on the chosen port.
+The server only handles the `/mcp` endpoint (and `/.well-known/skills/` discovery); any other path returns `404`. It binds to `127.0.0.1` by default so only the local host can reach it. Anyone who can reach the port can use this CLI's authenticated Link session, so only override `--host` on a trusted, isolated network — doing so prints a warning.
 
 ## Quickstart
 

package/dist/cli.js

@@ -11282,6 +11282,11 @@ var BalancesResource = class extends BaseResource {
   }
   buildUrl(params) {
     const url = new URL(this.endpoint);
+    if (params.sources !== void 0) {
+      for (const source of params.sources) {
+        url.searchParams.append("sources[]", source);
+      }
+    }
     if (params.limit !== void 0) {
       url.searchParams.set("limit", String(params.limit));
     }
@@ -13097,6 +13102,7 @@ var BalancesList = ({
 // src/commands/balances/schema.ts
 import { z as z2 } from "incur";
 var listOptions = z2.object({
+  source: z2.array(z2.string()).default([]).describe("Filter by source ID. Repeat to include multiple sources."),
   limit: z2.coerce.number().int().positive().max(100).optional().describe("Maximum number of balances to return (1-100)."),
   startingAfter: z2.string().optional().describe("Cursor: return balances after this balance ID."),
   endingBefore: z2.string().optional().describe("Cursor: return balances before this balance ID.")
@@ -13117,6 +13123,7 @@ function createBalancesCli(createResource, authStorage2, envAccessToken2) {
       const opts = c.options;
       const resource = createResource();
       const params = {};
+      if (opts.source.length > 0) params.sources = opts.source;
       if (opts.limit !== void 0) params.limit = opts.limit;
       if (opts.startingAfter !== void 0)
         params.starting_after = opts.startingAfter;
@@ -13814,11 +13821,11 @@ function getMethodDetails(request) {
 }
 function resolveStripeChallenge(challenges) {
   const stripeChallenge = challenges.find(
-    (challenge) => challenge.method === "stripe" && challenge.intent === "charge"
+    (challenge) => challenge.method === "stripe" && (challenge.intent === "charge" || challenge.intent === "session")
   );
   if (!stripeChallenge) {
     throw new Error(
-      "WWW-Authenticate header does not include a stripe charge challenge"
+      "WWW-Authenticate header does not include a stripe charge or session challenge"
     );
   }
   if (typeof stripeChallenge.request !== "object" || stripeChallenge.request == null || Array.isArray(stripeChallenge.request)) {
@@ -13853,7 +13860,7 @@ function decodeStripeChallenge(challengeHeader) {
     id: challenge.id,
     realm: challenge.realm,
     method: "stripe",
-    intent: "charge",
+    intent: challenge.intent,
     description: challenge.description,
     digest: challenge.digest,
     expires: challenge.expires,
@@ -13898,8 +13905,19 @@ function createStripePaymentClient(spt) {
       });
     }
   });
+  const stripeSession = Method.toClient(
+    { ...StripeMethods.charge, intent: "session" },
+    {
+      async createCredential({ challenge }) {
+        return Credential.serialize({
+          challenge,
+          payload: { action: "open", grantedToken: spt }
+        });
+      }
+    }
+  );
   return Mppx.create({
-    methods: [stripeCharge],
+    methods: [stripeCharge, stripeSession],
     polyfill: false,
     transport: Transport.from({
       name: "stripe-http",
@@ -13917,7 +13935,7 @@ function createStripePaymentClient(spt) {
     })
   });
 }
-async function runMppPay(url, spendRequestId, method, data, headers, repository) {
+async function runMppPayWithSpendRequest(url, spendRequestId, method, data, headers, repository) {
   const spendRequest = await repository.getSpendRequest(spendRequestId, {
     include: ["shared_payment_token"]
   });
@@ -13938,7 +13956,15 @@ async function runMppPay(url, spendRequestId, method, data, headers, repository)
   if (!spendRequest.shared_payment_token) {
     throw new Error("Spend request does not have a shared payment token");
   }
-  const spt = spendRequest.shared_payment_token.id;
+  return payWithSpt(
+    url,
+    spendRequest.shared_payment_token.id,
+    method,
+    data,
+    headers
+  );
+}
+async function payWithSpt(url, spt, method, data, headers) {
   const httpMethod = method ?? (data !== void 0 ? "POST" : "GET");
   const requestHeaders = buildHeaders(data, headers);
   const initialResponse = await fetch(url, {
@@ -13960,72 +13986,156 @@ async function runMppPay(url, spendRequestId, method, data, headers, repository)
   });
   return readPayResult(retryResponse);
 }
+async function runMppPayFullFlow(opts) {
+  const {
+    url,
+    method,
+    data,
+    headers,
+    context,
+    amountOverride,
+    paymentMethodId,
+    test,
+    repository,
+    paymentMethodsFactory,
+    onStep,
+    onApprovalUrl
+  } = opts;
+  const httpMethod = method ?? (data !== void 0 ? "POST" : "GET");
+  const requestHeaders = buildHeaders(data, headers);
+  onStep?.("probing");
+  const probeResponse = await fetch(url, {
+    method: httpMethod,
+    body: data,
+    headers: requestHeaders
+  });
+  if (probeResponse.status !== 402) {
+    return readPayResult(probeResponse);
+  }
+  const wwwAuth = probeResponse.headers.get("www-authenticate");
+  if (!wwwAuth) {
+    throw new Error("URL returned 402 but no WWW-Authenticate header");
+  }
+  const decoded = decodeStripeChallenge(wwwAuth);
+  const networkId = decoded.network_id;
+  const challengeAmount = decoded.request_json.amount ? Number(decoded.request_json.amount) : void 0;
+  const challengeCurrency = decoded.request_json.currency ?? "usd";
+  const amount = amountOverride ?? challengeAmount;
+  if (!amount) {
+    throw new Error(
+      "Could not determine amount from 402 challenge. Pass --amount explicitly."
+    );
+  }
+  let pmId = paymentMethodId;
+  if (!pmId) {
+    onStep?.("creating");
+    const pmResource = paymentMethodsFactory();
+    const methods = await pmResource.list();
+    if (!methods.length) {
+      throw new Error(
+        "No payment methods found. Add one with `link-cli payment-methods add`."
+      );
+    }
+    pmId = methods[0].id;
+  }
+  onStep?.("creating");
+  const spendRequest = await repository.createSpendRequest({
+    payment_details: pmId,
+    credential_type: "shared_payment_token",
+    network_id: networkId,
+    amount,
+    currency: challengeCurrency,
+    context,
+    request_approval: true,
+    test: test || void 0
+  });
+  onStep?.("approving");
+  if (spendRequest.approval_url) {
+    onApprovalUrl?.(spendRequest.approval_url);
+  }
+  const approved = await pollUntilApproved(repository, spendRequest.id);
+  if (approved.status !== "approved") {
+    throw new Error(
+      `Spend request was not approved (status: ${approved.status})`
+    );
+  }
+  onStep?.("signing");
+  let withSpt = await repository.getSpendRequest(spendRequest.id, {
+    include: ["shared_payment_token"]
+  });
+  for (let i = 0; i < 3 && withSpt && !withSpt.shared_payment_token; i++) {
+    await new Promise((r) => setTimeout(r, 1e3));
+    withSpt = await repository.getSpendRequest(spendRequest.id, {
+      include: ["shared_payment_token"]
+    });
+  }
+  if (!withSpt?.shared_payment_token) {
+    throw new Error("Failed to retrieve shared payment token");
+  }
+  onStep?.("submitting");
+  return payWithSpt(
+    url,
+    withSpt.shared_payment_token.id,
+    method,
+    data,
+    headers
+  );
+}
 function MppPay({
   url,
   spendRequestId,
   method,
   data,
   headers,
+  context,
+  amountOverride,
+  paymentMethodId,
+  test,
   repository,
+  paymentMethodsFactory,
   onComplete
 }) {
-  const [step, setStep] = useState5("retrieving");
+  const [step, setStep] = useState5(
+    spendRequestId ? "signing" : "probing"
+  );
   const [result, setResult] = useState5(null);
   const [error, setError] = useState5(null);
+  const [approvalUrl, setApprovalUrl] = useState5(null);
   useEffect5(() => {
     (async () => {
       try {
-        setStep("retrieving");
-        const spendRequest = await repository.getSpendRequest(spendRequestId, {
-          include: ["shared_payment_token"]
-        });
-        if (!spendRequest) {
-          throw new Error(`Spend request ${spendRequestId} not found`);
-        }
-        if (spendRequest.credential_type !== "shared_payment_token") {
-          const type = spendRequest.credential_type ?? "card";
-          throw new Error(
-            `Spend request ${spendRequestId} must have credential_type 'shared_payment_token' (current: '${type}')`
-          );
-        }
-        if (spendRequest.status !== "approved") {
-          throw new Error(
-            `Spend request must be approved (current status: ${spendRequest.status})`
+        let payResult;
+        if (spendRequestId) {
+          setStep("signing");
+          payResult = await runMppPayWithSpendRequest(
+            url,
+            spendRequestId,
+            method,
+            data,
+            headers,
+            repository
           );
-        }
-        if (!spendRequest.shared_payment_token) {
-          throw new Error("Spend request does not have a shared payment token");
-        }
-        const spt = spendRequest.shared_payment_token.id;
-        const httpMethod = method ?? (data !== void 0 ? "POST" : "GET");
-        const requestHeaders = buildHeaders(data, headers);
-        setStep("probing");
-        const initialResponse = await fetch(url, {
-          method: httpMethod,
-          body: data,
-          headers: requestHeaders
-        });
-        if (initialResponse.status !== 402) {
-          const payResult2 = await readPayResult(initialResponse);
-          setResult(payResult2);
-          setStep("done");
-          onComplete(payResult2);
-          return;
-        }
-        setStep("signing");
-        const authHeader = await createStripePaymentClient(spt).createCredential(
-          initialResponse
-        );
-        setStep("submitting");
-        const retryResponse = await fetch(url, {
-          method: httpMethod,
-          body: data,
-          headers: {
-            ...requestHeaders,
-            Authorization: authHeader
+        } else {
+          if (!context) {
+            throw new Error(
+              "--context is required for the full MPP flow (min 100 chars)"
+            );
           }
-        });
-        const payResult = await readPayResult(retryResponse);
+          payResult = await runMppPayFullFlow({
+            url,
+            method,
+            data,
+            headers,
+            context,
+            amountOverride,
+            paymentMethodId,
+            test: test ?? false,
+            repository,
+            paymentMethodsFactory,
+            onStep: setStep,
+            onApprovalUrl: (u) => setApprovalUrl(u)
+          });
+        }
         setResult(payResult);
         setStep("done");
         onComplete(payResult);
@@ -14034,10 +14144,24 @@ function MppPay({
         onComplete(null);
       }
     })();
-  }, [url, spendRequestId, method, data, headers, repository, onComplete]);
+  }, [
+    url,
+    spendRequestId,
+    method,
+    data,
+    headers,
+    context,
+    amountOverride,
+    paymentMethodId,
+    test,
+    repository,
+    paymentMethodsFactory,
+    onComplete
+  ]);
   const stepLabels = {
-    retrieving: "Retrieving spend request",
-    probing: "Probing URL",
+    probing: "Probing URL for 402 challenge",
+    creating: "Creating spend request",
+    approving: "Waiting for approval",
     signing: "Signing credential",
     submitting: "Submitting payment",
     done: "Done"
@@ -14049,12 +14173,19 @@ function MppPay({
     ] });
   }
   return /* @__PURE__ */ jsxs7(Box7, { flexDirection: "column", children: [
-    step !== "done" && /* @__PURE__ */ jsx10(Box7, { children: /* @__PURE__ */ jsxs7(Text9, { color: "cyan", children: [
-      /* @__PURE__ */ jsx10(Spinner4, { type: "dots" }),
-      " ",
-      stepLabels[step],
-      "..."
-    ] }) }),
+    step !== "done" && /* @__PURE__ */ jsxs7(Box7, { flexDirection: "column", children: [
+      /* @__PURE__ */ jsx10(Box7, { children: /* @__PURE__ */ jsxs7(Text9, { color: "cyan", children: [
+        /* @__PURE__ */ jsx10(Spinner4, { type: "dots" }),
+        " ",
+        stepLabels[step],
+        "..."
+      ] }) }),
+      step === "approving" && approvalUrl && /* @__PURE__ */ jsx10(Box7, { marginTop: 1, paddingX: 2, children: /* @__PURE__ */ jsxs7(Text9, { children: [
+        "Approve in Link app:",
+        " ",
+        /* @__PURE__ */ jsx10(Text9, { bold: true, color: "blue", children: approvalUrl })
+      ] }) })
+    ] }),
     result && /* @__PURE__ */ jsxs7(Box7, { flexDirection: "column", children: [
       /* @__PURE__ */ jsxs7(
         Text9,
@@ -14221,7 +14352,7 @@ var SptFlow = ({
         setStep("mpp-pay-gate");
         await waitForEnter();
         setStep("mpp-pay");
-        const payResponse = await runMppPay(
+        const payResponse = await runMppPayWithSpendRequest(
           DEMO_CLIMATE_API_URL,
           result.id,
           "POST",
@@ -14641,12 +14772,22 @@ function DecodeChallengeView({
 // src/commands/mpp/schema.ts
 import { z as z4 } from "incur";
 var payOptions = z4.object({
-  spendRequestId: z4.string().describe(
-    'Approved spend request ID with credential_type "shared_payment_token"'
+  spendRequestId: z4.string().optional().describe(
+    'Approved spend request ID with credential_type "shared_payment_token". If omitted, the command handles the full flow: probe URL, parse challenge, create spend request, get approval, and pay.'
   ),
   method: z4.string().optional().describe("HTTP method (default: GET, or POST if --data is provided)"),
   data: z4.string().optional().describe("Request body (implies POST if --method is not set)"),
-  header: z4.array(z4.string()).default([]).describe('Request header in "Name: Value" format (repeatable)')
+  header: z4.array(z4.string()).default([]).describe('Request header in "Name: Value" format (repeatable)'),
+  context: z4.string().min(100).optional().describe(
+    "Min 100 chars \u2014 describe the purchase and rationale; the user reads this when approving. Required when --spend-request-id is not provided."
+  ),
+  amount: z4.coerce.number().int().positive().optional().describe(
+    "Amount in cents (derived from 402 challenge if omitted; required if challenge has no amount)"
+  ),
+  paymentMethodId: z4.string().optional().describe("Payment method ID (uses default if omitted)"),
+  test: z4.boolean().default(false).describe(
+    "Use test mode (creates testmode credentials from test card data)"
+  )
 });
 var decodeOptions = z4.object({
   challenge: z4.string().describe(
@@ -14656,12 +14797,12 @@ var decodeOptions = z4.object({
 
 // src/commands/mpp/index.tsx
 import { jsx as jsx15 } from "react/jsx-runtime";
-function createMppCli(repository, authStorage2, envAccessToken2) {
+function createMppCli(repository, paymentMethodsFactory, authStorage2, envAccessToken2) {
   const cli2 = Cli4.create("mpp", {
     description: "Machine payment protocol (MPP) commands"
   });
   cli2.command("pay", {
-    description: "Complete a machine payment protocol (MPP) payment using an approved spend request",
+    description: "Pay a URL via the Machine Payment Protocol. Handles the full 402 flow: probes the URL, parses the challenge, creates a spend request, gets approval, and pays with the SPT. Pass --spend-request-id to skip creation and use a pre-approved spend request.",
     args: z5.object({
       url: z5.string().describe("URL to pay")
     }),
@@ -14669,7 +14810,7 @@ function createMppCli(repository, authStorage2, envAccessToken2) {
     alias: { method: "X", data: "d", header: "H" },
     outputPolicy: "agent-only",
     middleware: [requireAuth(authStorage2, envAccessToken2)],
-    async run(c) {
+    async *run(c) {
       const url = c.args.url;
       const opts = c.options;
       const method = opts.method;
@@ -14686,7 +14827,12 @@ function createMppCli(repository, authStorage2, envAccessToken2) {
               method,
               data,
               headers,
+              context: opts.context,
+              amountOverride: opts.amount,
+              paymentMethodId: opts.paymentMethodId,
+              test: opts.test,
               repository,
+              paymentMethodsFactory,
               onComplete: (result) => {
                 capturedResult = result;
               }
@@ -14699,14 +14845,90 @@ function createMppCli(repository, authStorage2, envAccessToken2) {
           }
         );
       }
-      return runMppPay(
-        url,
-        opts.spendRequestId,
-        method,
-        data,
-        headers,
-        repository
-      );
+      if (opts.spendRequestId) {
+        yield await runMppPayWithSpendRequest(
+          url,
+          opts.spendRequestId,
+          method,
+          data,
+          headers,
+          repository
+        );
+        return;
+      }
+      const httpMethod = method ?? (data !== void 0 ? "POST" : "GET");
+      const requestHeaders = buildHeaders(data, headers);
+      const probeResponse = await fetch(url, {
+        method: httpMethod,
+        body: data,
+        headers: requestHeaders
+      });
+      if (probeResponse.status !== 402) {
+        yield await readPayResult(probeResponse);
+        return;
+      }
+      const wwwAuth = probeResponse.headers.get("www-authenticate");
+      if (!wwwAuth) {
+        return c.error({
+          code: "INVALID_RESPONSE",
+          message: "URL returned 402 but no WWW-Authenticate header"
+        });
+      }
+      const decoded = decodeStripeChallenge(wwwAuth);
+      const networkId = decoded.network_id;
+      const challengeAmount = decoded.request_json.amount ? Number(decoded.request_json.amount) : void 0;
+      const challengeCurrency = decoded.request_json.currency ?? "usd";
+      const amount = opts.amount ?? challengeAmount;
+      if (!amount) {
+        return c.error({
+          code: "INVALID_INPUT",
+          message: "Could not determine amount from 402 challenge. Pass --amount explicitly."
+        });
+      }
+      if (!opts.context) {
+        return c.error({
+          code: "INVALID_INPUT",
+          message: "--context is required for the full MPP flow (min 100 chars). Describe the purchase and rationale."
+        });
+      }
+      let pmId = opts.paymentMethodId;
+      if (!pmId) {
+        const pmResource = paymentMethodsFactory();
+        const methods = await pmResource.list();
+        if (!methods.length) {
+          return c.error({
+            code: "NO_PAYMENT_METHOD",
+            message: "No payment methods found. Add one with `link-cli payment-methods add`."
+          });
+        }
+        pmId = methods[0].id;
+      }
+      const spendRequest = await repository.createSpendRequest({
+        payment_details: pmId,
+        credential_type: "shared_payment_token",
+        network_id: networkId,
+        amount,
+        currency: challengeCurrency,
+        context: opts.context,
+        request_approval: true,
+        test: opts.test || void 0
+      });
+      const nextFlags = [`--spend-request-id ${spendRequest.id}`];
+      if (method) nextFlags.push(`-X ${method}`);
+      if (data) nextFlags.push(`-d '${data}'`);
+      if (headers) {
+        for (const h of headers) nextFlags.push(`-H '${h}'`);
+      }
+      const nextCommand = `mpp pay ${url} ${nextFlags.join(" ")}`;
+      yield {
+        ...spendRequest,
+        instruction: `Present the approval_url to the user and ask them to approve in the Link app. Then call \`spend-request retrieve ${spendRequest.id} --interval 2 --max-attempts 300\` to poll until approved. Once approved, run the _next.command to complete payment. Do not wait for the user to reply \u2014 start polling immediately.`,
+        _next: {
+          poll_command: `spend-request retrieve ${spendRequest.id} --interval 2 --max-attempts 300`,
+          pay_command: nextCommand,
+          until: "status changes from pending_approval, then run pay_command"
+        }
+      };
     }
   });
   cli2.command("decode", {
@@ -15083,17 +15305,47 @@ async function sendWebResponse(webRes, res) {
   res.writeHead(webRes.status);
   res.end(Buffer.from(buffer));
 }
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["127.0.0.1", "::1", "localhost"]);
+function isLoopbackHost(host) {
+  return LOOPBACK_HOSTS.has(host.toLowerCase());
+}
+function isAllowedOrigin(origin) {
+  if (!origin) return true;
+  try {
+    return isLoopbackHost(new URL(origin).hostname);
+  } catch {
+    return false;
+  }
+}
+function isAllowedRoute(method, pathname) {
+  if (pathname === "/mcp") return true;
+  if (pathname.startsWith("/.well-known/skills/") && method === "GET")
+    return true;
+  return false;
+}
 function createServeCli(rootCli) {
   return Cli8.create("serve", {
     description: "Start an HTTP server exposing link-cli as an MCP endpoint at /mcp",
     options: z7.object({
-      port: z7.coerce.number().default(54321).describe("Port to listen on")
+      port: z7.coerce.number().default(54321).describe("Port to listen on"),
+      host: z7.string().default("127.0.0.1").describe(
+        "Host/interface to bind. Defaults to loopback; set explicitly (e.g. 0.0.0.0) to expose beyond localhost."
+      )
     }),
     async run(c) {
-      const { port } = c.options;
+      const { port, host } = c.options;
       const server = createServer(
         async (req, res) => {
-          res.setHeader("Access-Control-Allow-Origin", "*");
+          const origin = req.headers.origin;
+          if (!isAllowedOrigin(origin)) {
+            res.writeHead(403, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "forbidden origin" }));
+            return;
+          }
+          if (origin) {
+            res.setHeader("Access-Control-Allow-Origin", origin);
+            res.setHeader("Vary", "Origin");
+          }
           res.setHeader(
             "Access-Control-Allow-Methods",
             "GET, POST, DELETE, OPTIONS"
@@ -15107,6 +15359,12 @@ function createServeCli(rootCli) {
             res.end();
             return;
           }
+          const pathname = new URL(req.url ?? "/", `http://localhost:${port}`).pathname;
+          if (!isAllowedRoute(req.method ?? "GET", pathname)) {
+            res.writeHead(404, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "not found" }));
+            return;
+          }
           try {
             const webReq = await nodeRequestToWebRequest(req, port);
             const webRes = await rootCli.fetch(webReq);
@@ -15120,9 +15378,16 @@ function createServeCli(rootCli) {
       );
       await new Promise((resolve, reject) => {
         server.on("error", reject);
-        server.listen(port, () => {
+        server.listen(port, host, () => {
+          if (!isLoopbackHost(host)) {
+            process.stderr.write(
+              `WARNING: link-cli serve is bound to ${host}, which may be reachable beyond localhost.
+Any caller that can reach this port can use the authenticated Link session of this CLI. Only do this on a trusted, isolated network.
+`
+            );
+          }
           process.stderr.write(
-            `link-cli MCP server listening on http://localhost:${port}/mcp
+            `link-cli MCP server listening on http://${host}:${port}/mcp
 `
           );
         });
@@ -17850,7 +18115,7 @@ function cacheUpdateInfo(value, ttlMs = UPDATE_CACHE_TTL_MS) {
 }
 
 // src/cli.tsx
-var cliVersion = "0.9.0";
+var cliVersion = "0.10.0";
 var cliName = "@stripe/link-cli";
 var defaultHeaders = {
   "User-Agent": `link-cli/${cliVersion}`
@@ -17941,7 +18206,14 @@ if (!hiddenCli) {
       envAccessToken
     )
   );
-  cli.command(createMppCli(spendRequestRepo, authStorage, envAccessToken));
+  cli.command(
+    createMppCli(
+      spendRequestRepo,
+      () => factory.createPaymentMethodsResource(),
+      authStorage,
+      envAccessToken
+    )
+  );
   cli.command(
     createReportCli(
       () => factory.createReportResource(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stripe/link-cli",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "bin": {
     "link-cli": "./dist/cli.js"