glyphpay 0.5.0 → 1.0.1

package/README.md

@@ -19,6 +19,12 @@ The CLI covers setup, diagnostics, and credential lifecycle:
 | `glyphpay deliveries` | Page/filter webhook deliveries and retry one with `--retry <id>`. |
 | `glyphpay init` | Scaffold routes for Next.js, Remix, Astro, SvelteKit, Hono, or Express. |
 
+## 1.0 compatibility
+
+`glyphpay` 1.x follows Semantic Versioning. The documented package exports and the `/api/client/v1` and `/api/cli/v1` HTTP contracts accept additive changes only; ignore unknown response fields and event types. Breaking changes ship under a new API version with an overlap period. The full rules are in `docs/versioning-policy.md`.
+
+The CLI supports **Node 18+**. The server connector (`glyphpay/server`) uses `fetch` and Web Crypto and targets **Node 20+**, Next.js, edge runtimes, and Cloudflare Workers. A 1.0 release is a code and contract milestone: live payments remain gated by sandbox acceptance, deployment verification, and written approval.
+
 ## Connect a site from the CLI
 
 ```sh
@@ -37,6 +43,8 @@ GLYPHPAY_CALLBACK_SECRET=dgcb_...
 - `--no-open`, `--base-url` and `--timeout` help scripts and local testing.
 - Codes expire after ten minutes. Approving again rotates the token: the previous token stops working immediately.
 - Pairing is disabled while the platform is in live mode.
+- **Only approve a code you generated in your own terminal.** Glyph Pay never calls, emails, or messages you to approve a pairing code. Check the webhook domain before approving; approval rotates the credential and can replace the old webhook.
+- `--base-url` and `GLYPHPAY_API_URL` must use HTTPS; loopback HTTP is accepted only for local development. A non-default origin is printed.
 
 The browser never receives the credential. Keep the token in server environment variables and never prefix it with `NEXT_PUBLIC_`, `VITE_` or `PUBLIC_`.
 
@@ -49,7 +57,7 @@ npx glyphpay rotate
 npx glyphpay disconnect
 ```
 
-`doctor` verifies the local env file, checks for credentials leaked into public-prefixed variables, validates the token with Glyph Pay, checks Stripe charge readiness and the registered webhook, and optionally sends a signed test event:
+`doctor` verifies the local env file, warns when it is not ignored by git, checks for credentials leaked into public-prefixed variables, validates the token with Glyph Pay, checks Stripe charge readiness and the registered webhook, and optionally sends a signed test event:
 
 ```sh
 npx glyphpay doctor --send-test-event
@@ -66,7 +74,7 @@ npx glyphpay deliveries
 npx glyphpay deliveries --retry evt_...
 ```
 
-`deliveries` pages through callback outbox records for the credential's client and environment: event type, delivery state, attempt count, timestamp, and the last error. Filter with `--state pending|delivered|failed`, control the page with `--limit 1..100`, and pass the returned `--cursor` for the next page. A retry sends the exact stored signed event again and persists the result. Retry is one attempt; fix the endpoint first. The admin **Connections** tab exposes the same filtering, pagination, and retry operations.
+`deliveries` pages through callback outbox records for the credential's client and environment: event type, delivery state, attempt count, timestamp, and the last error. Filter with `--state pending|delivered|failed`, control the page with `--limit 1..100`, and pass the returned `--cursor` for the next page. A retry re-sends the stored event body with a fresh signature and timestamp, then persists the result. Retry is one attempt; fix the endpoint first. The admin **Connections** tab exposes the same filtering, pagination, and retry operations.
 
 ## Scaffold a site
 
@@ -89,7 +97,7 @@ It refuses to overwrite existing files unless you pass `--force`; use `--dry-run
 
 1. **Admin → Clients → (client)**: make sure Stripe onboarding is complete (charges enabled).
 2. **Issue a service credential** (test first). Copy the `dgsvc_test_…` token. It is shown only once.
-3. **Set the callback URL** to `https://<client-site>/api/glyphpay/webhook`. Copy the signing secret. It is also shown only once.
+3. **Set the callback URL** to `https://<client-site>/api/glyphpay/webhook`. Check the domain before saving; saving replaces the previous callback. Copy the signing secret. It is also shown only once.
 
 ## Add to the client site
 
@@ -114,16 +122,23 @@ export const glyphpay = glyphPay({
   callbackSecret: process.env.GLYPHPAY_CALLBACK_SECRET,
 
   // Price the order from YOUR data. Never trust an amount sent by the browser.
-  async priceOrder(body) {
-    const cart = await db.carts.get((body as { cartId: string }).cartId);
+  async priceOrder(body, req) {
+    const cartId = (body as { cartId?: string }).cartId;
+    // Load from the shopper's session, or verify ownership; never fetch by a guessable id alone.
+    const cart = cartId ? await db.carts.getForShopper(cartId, req) : null;
     if (!cart?.items.length) throw new CheckoutError("Your cart is empty.");
     // orderId must change whenever the total changes, or GlyphPay returns 409.
     return { orderId: `${cart.id}-v${cart.version}`, amountCents: cart.totalCents, description: `Order ${cart.id}` };
   },
 
+  // Optional fast path; a unique insert in onEvent also works.
+  seen: (eventId) => db.processedEvents.has(eventId),
+
   // Signed and verified. At-least-once delivery: dedupe on event.id. Throw to have it retried.
   async onEvent(event) {
+    if (await db.processedEvents.has(event.id)) return;
     if (event.type === "payment.succeeded") await db.orders.markPaid(event.data.orderId, event.id);
+    await db.processedEvents.add(event.id);
   },
 });
 ```
@@ -142,6 +157,8 @@ import { glyphpay } from "@/lib/glyphpay";
 export const POST = glyphpay.webhook;
 ```
 
+The checkout route requires `application/json`, checks the request `Origin`, caps the body at 1 MB, and exposes `beforeCheckout(req)` for rate limiting or a bot challenge. Put rate limiting in your host/proxy or that hook, and enable Stripe Radar for the connected account. The webhook route also caps bodies at 1 MB, accepts multiple `v1` signatures during secret rotation, rejects a `livemode` mismatch, and calls `seen` before `onEvent`.
+
 Checkout page:
 
 ```tsx
@@ -150,6 +167,8 @@ import { GlyphPayCheckout } from "glyphpay/react";
 <GlyphPayCheckout order={{ cartId }} returnUrl={`/thank-you?cart=${cartId}`} appearance={{ theme: "stripe" }} />
 ```
 
+`returnUrl` must stay on the site's origin unless you set `allowCrossOriginReturn`. A redirect is never payment proof; verify the payment on the server.
+
 Style the button with `.glyphpay button { … }`. Errors appear in `.glyphpay [role=alert]`.
 
 Without React:
@@ -158,7 +177,8 @@ Without React:
 <div id="pay"></div>
 <script type="module">
   import { mountCheckout } from "glyphpay/browser";
-  mountCheckout(document.getElementById("pay"), { order: { cartId: "42" }, returnUrl: "/thank-you" });
+  // cartId comes from the shopper's server-rendered session, not a URL parameter.
+  mountCheckout(document.getElementById("pay"), { order: { cartId: "session-cart-id" }, returnUrl: "/thank-you" });
 </script>
 ```
 
@@ -169,7 +189,7 @@ The route handlers take a standard `Request` and return a `Response`, so the sam
 1. The component POSTs `order` to `/api/glyphpay/checkout`. `priceOrder` sets the amount, and the site's server calls GlyphPay with the token.
 2. The browser gets back only `clientSecret`, `publishableKey`, and `stripeAccount`, then mounts Stripe's Payment Element.
 3. The shopper pays, and Stripe redirects to `returnUrl`. **The redirect doesn't prove payment.**
-4. GlyphPay POSTs `payment.succeeded` to `/api/glyphpay/webhook`, and `onEvent` marks the order paid. The thank-you page reads the order status from your database, or calls `glyphpay.getPayment(paymentId)`.
+4. GlyphPay POSTs `payment.succeeded` to `/api/glyphpay/webhook`, and `onEvent` marks the order paid. The thank-you page reads the order status from your database, or calls `glyphpay.getPayment(paymentId)` after checking that the payment belongs to that shopper.
 
 Refunds run server-side:
 

package/dist/browser.d.ts

@@ -6,8 +6,10 @@ import { type Appearance } from "@stripe/stripe-js";
 export interface CheckoutOptions {
     /** JSON posted to your checkout route, e.g. `{ cartId }`. Your server prices it; never send a trusted amount. */
     order: unknown;
-    /** Where Stripe sends the shopper after paying. Confirm the order server-side there (callback/getPayment), not from the URL. */
+    /** Where Stripe sends the shopper after paying. Must stay on this site unless `allowCrossOriginReturn` is set. */
     returnUrl: string;
+    /** Allow an absolute return URL on another origin. Off by default. */
+    allowCrossOriginReturn?: boolean;
     /** Your site's checkout route. Default `/api/glyphpay/checkout`. */
     endpoint?: string;
     /** Stripe Elements appearance (theme, colors, fonts). */

package/dist/browser.js

@@ -3,6 +3,7 @@
  * Talks only to the site's own checkout route; the service credential never reaches the browser.
  */
 import { loadStripe } from "@stripe/stripe-js";
+import { resolveReturnUrl } from "./security.js";
 /**
  * Renders `<form class="glyphpay">` (Stripe Payment Element + submit button + `role=alert` message)
  * into `container`. Style it with `.glyphpay button { … }`. Returns an unmount function.
@@ -42,10 +43,18 @@ export function mountCheckout(container, options) {
             event.preventDefault();
             button.disabled = true;
             message.textContent = "";
-            // On success Stripe always redirects to returnUrl (adds payment_intent & redirect_status params).
-            const { error } = await stripe.confirmPayment({ elements, confirmParams: { return_url: new URL(options.returnUrl, location.href).href } });
-            message.textContent = error.message ?? "Payment failed. Please try again.";
-            button.disabled = false;
+            try {
+                // On success Stripe always redirects to returnUrl (adds payment_intent & redirect_status params).
+                const returnUrl = resolveReturnUrl(options.returnUrl, location.href, !!options.allowCrossOriginReturn);
+                const { error } = await stripe.confirmPayment({ elements, confirmParams: { return_url: returnUrl } });
+                message.textContent = error.message ?? "Payment failed. Please try again.";
+            }
+            catch (error) {
+                message.textContent = error instanceof Error ? error.message : "Payment failed. Please try again.";
+            }
+            finally {
+                button.disabled = false;
+            }
         });
     })().catch((error) => { message.textContent = error.message; });
     return () => { unmounted = true; form.remove(); };

package/dist/cli.d.ts

@@ -99,6 +99,16 @@ interface ParsedCommand {
 }
 export declare function parseArgs(argv: string[]): ParsedCommand;
 export declare function helpText(): string;
+/** Strip ANSI escapes and control characters from server-controlled text before printing it. */
+export declare function sanitizeTerminal(value: string): string;
+/** Validate and normalize the API origin. HTTPS is required outside loopback development. */
+export declare function normalizeApiBaseUrl(raw: string): string;
+/** True when a browser URL is https, or http on loopback. */
+export declare function isSafeBrowserUrl(raw: string): boolean;
+/** True when a callback URL is public HTTPS (no credentials, IP literals, or internal names). */
+export declare function isPublicHttpsUrl(raw: string): boolean;
+/** Doctor may probe a public HTTPS callback, or loopback HTTP for local testing. */
+export declare function isProbeableCallbackUrl(raw: string): boolean;
 /** `shop.example.com` -> `https://shop.example.com/api/glyphpay/webhook`. */
 export declare function toCallbackUrl(raw: string): string;
 /**
@@ -115,7 +125,7 @@ export declare function removeEnvKeys(contents: string, keys: string[]): string;
 export declare function readEnvValue(contents: string, key: string): string | null;
 /** Public-prefixed variables must never contain a Glyph Pay credential. */
 export declare function findPublicCredentialKeys(contents: string): string[];
-export declare function openBrowser(url: string): boolean;
+export declare function openBrowser(rawUrl: string): boolean;
 export declare function runConnect(options?: CliOptions, mode?: "connect" | "rotate"): Promise<ConnectResult>;
 /**
  * Re-pair the site. If the current env token is still valid, reuse the

package/dist/cli.js

@@ -14,19 +14,21 @@
  *
  * Zero runtime dependencies: Node 18+ built-ins and global fetch only.
  */
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { createHmac, randomBytes } from "node:crypto";
 import { access, chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { pathToFileURL } from "node:url";
-const VERSION = "0.5.0";
+const VERSION = "1.0.1";
 const DEFAULT_BASE_URL = "https://designglyph.web.app";
 const DEFAULT_ENV_FILE = ".env.local";
 const DEFAULT_TIMEOUT_SECONDS = 600;
 const TOKEN_KEY = "GLYPHPAY_TOKEN";
 const CALLBACK_SECRET_KEY = "GLYPHPAY_CALLBACK_SECRET";
 const WEBHOOK_PATH = "/api/glyphpay/webhook";
+const TOKEN_PATTERN = /^dgsvc_(test|live)_[A-Za-z0-9_-]{1,128}_[A-Za-z0-9_-]{43}$/;
+const CALLBACK_SECRET_PATTERN = /^dgcb_[A-Za-z0-9_-]{20,}$/;
 export class CliUsageError extends Error {
     constructor(message) {
         super(message);
@@ -291,6 +293,80 @@ approves this machine. The service credential goes only to this terminal.`;
 /* ------------------------------------------------------------------ */
 /* URL and env-file helpers                                            */
 /* ------------------------------------------------------------------ */
+function isLoopbackHost(hostname) {
+    const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    return host === "localhost" || host === "127.0.0.1" || host === "::1";
+}
+/** Strip ANSI escapes and control characters from server-controlled text before printing it. */
+export function sanitizeTerminal(value) {
+    return value
+        .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, "")
+        .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, "")
+        .replace(/[\u0000-\u001f\u007f-\u009f]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** Validate and normalize the API origin. HTTPS is required outside loopback development. */
+export function normalizeApiBaseUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new CliUsageError("--base-url is not a valid URL.");
+    }
+    if (url.username || url.password)
+        throw new CliUsageError("--base-url must not contain credentials.");
+    if (url.protocol !== "https:" && !(isLoopbackHost(url.hostname) && url.protocol === "http:")) {
+        throw new CliUsageError("--base-url must use https:// (http:// is allowed only for localhost).");
+    }
+    return `${url.origin}${url.pathname.replace(/\/+$/, "")}`;
+}
+/** True when a browser URL is https, or http on loopback. */
+export function isSafeBrowserUrl(raw) {
+    try {
+        const url = new URL(raw);
+        if (url.protocol !== "https:" && !(isLoopbackHost(url.hostname) && url.protocol === "http:"))
+            return false;
+        return !url.username && !url.password;
+    }
+    catch {
+        return false;
+    }
+}
+/** True when a callback URL is public HTTPS (no credentials, IP literals, or internal names). */
+export function isPublicHttpsUrl(raw) {
+    try {
+        const url = new URL(raw);
+        if (url.protocol !== "https:" || url.username || url.password)
+            return false;
+        const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+        if (!host || isLoopbackHost(host) || !host.includes("."))
+            return false;
+        if (/\.(localhost|local|internal|lan|home|corp)$/.test(host))
+            return false;
+        if (/^\d{1,3}(?:\.\d{1,3}){3}$/.test(host) || host.includes(":"))
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Doctor may probe a public HTTPS callback, or loopback HTTP for local testing. */
+export function isProbeableCallbackUrl(raw) {
+    try {
+        const url = new URL(raw);
+        if (url.username || url.password)
+            return false;
+        if (url.protocol === "https:")
+            return isPublicHttpsUrl(raw);
+        return url.protocol === "http:" && isLoopbackHost(url.hostname);
+    }
+    catch {
+        return false;
+    }
+}
 /** `shop.example.com` -> `https://shop.example.com/api/glyphpay/webhook`. */
 export function toCallbackUrl(raw) {
     let value = raw.trim();
@@ -305,11 +381,26 @@ export function toCallbackUrl(raw) {
     catch {
         throw new CliUsageError(`"${raw}" is not a valid URL.`);
     }
-    if (url.protocol !== "https:" && url.protocol !== "http:") {
-        throw new CliUsageError("The site URL must start with https:// (or http:// for local development).");
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    const loopback = isLoopbackHost(host);
+    if (url.protocol !== "https:" && !(loopback && url.protocol === "http:")) {
+        throw new CliUsageError("The site URL must use https:// (http:// is allowed only for localhost).");
     }
     if (url.username || url.password)
         throw new CliUsageError("The site URL must not contain a username or password.");
+    if (url.protocol === "https:" && url.port && url.port !== "443") {
+        throw new CliUsageError("The site URL must use the default https port.");
+    }
+    if (!loopback && !host.includes("."))
+        throw new CliUsageError("The site URL must use a public hostname.");
+    if (!loopback && /^\d{1,3}(?:\.\d{1,3}){3}$/.test(host)) {
+        throw new CliUsageError("The site URL must use a public hostname, not an IP address.");
+    }
+    if (!loopback && host.includes(":"))
+        throw new CliUsageError("The site URL must use a public hostname, not an IP address.");
+    if (!loopback && /\.(localhost|local|internal|lan|home|corp)$/.test(host)) {
+        throw new CliUsageError("The site URL must use a public hostname.");
+    }
     if (url.pathname === "/" || url.pathname === "")
         url.pathname = WEBHOOK_PATH;
     url.hash = "";
@@ -321,6 +412,13 @@ export function toCallbackUrl(raw) {
  * so the file keeps a single source of truth.
  */
 export function upsertEnv(contents, values) {
+    for (const [key, value] of Object.entries(values)) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            throw new CliUsageError(`Invalid environment key: ${key}`);
+        if (/[\r\n\0]/.test(value)) {
+            throw new CliUsageError(`Refusing to write ${key}: the value contains a line break or NUL byte.`);
+        }
+    }
     const eol = contents.includes("\r\n") ? "\r\n" : "\n";
     const lines = contents.length
         ? contents.replace(/\r\n/g, "\n").replace(/\n+$/, "").split("\n")
@@ -432,11 +530,14 @@ async function directoryExists(path) {
 /* ------------------------------------------------------------------ */
 /* Browser and API                                                     */
 /* ------------------------------------------------------------------ */
-export function openBrowser(url) {
-    const command = process.platform === "win32" ? "cmd" : process.platform === "darwin" ? "open" : "xdg-open";
-    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+export function openBrowser(rawUrl) {
+    if (!isSafeBrowserUrl(rawUrl))
+        return false;
+    const url = new URL(rawUrl).toString();
+    const command = process.platform === "win32" ? "rundll32" : process.platform === "darwin" ? "open" : "xdg-open";
+    const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
     try {
-        const child = spawn(command, args, { detached: true, stdio: "ignore" });
+        const child = spawn(command, args, { detached: true, stdio: "ignore", windowsHide: true });
         child.on("error", () => undefined);
         child.unref();
         return true;
@@ -471,7 +572,12 @@ async function api(baseUrl, path, body, token) {
     return payload.data;
 }
 function baseUrlFor(options) {
-    return options.baseUrl?.trim() || process.env.GLYPHPAY_API_URL?.trim() || DEFAULT_BASE_URL;
+    const raw = options.baseUrl?.trim() || process.env.GLYPHPAY_API_URL?.trim() || DEFAULT_BASE_URL;
+    const normalized = normalizeApiBaseUrl(raw);
+    if (normalized !== DEFAULT_BASE_URL) {
+        process.stderr.write(`Glyph Pay: using API origin ${normalized}\n`);
+    }
+    return normalized;
 }
 function fetchCredential(baseUrl, token) {
     return api(baseUrl, "/credential", undefined, token);
@@ -510,16 +616,20 @@ export async function runConnect(options = {}, mode = "connect") {
     const timeoutSeconds = options.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
     const callbackUrl = options.url ? toCallbackUrl(options.url) : null;
     const created = await api(baseUrl, "/device", { callbackUrl });
+    if (!isSafeBrowserUrl(created.verificationUrl)) {
+        throw new CliApiError(0, "invalid_verification_url", "Glyph Pay returned an unsafe browser verification URL.");
+    }
+    const verificationUrl = new URL(created.verificationUrl).toString();
     say();
     say(style(1, mode === "rotate" ? "Glyph Pay - rotate credential" : "Glyph Pay - connect a site"));
     say();
-    say(`1. Open ${style(4, created.verificationUrl)}`);
-    say(`2. Sign in and approve pairing code ${style(1, created.userCode)}.`);
+    say(`1. Open ${style(4, sanitizeTerminal(verificationUrl))}`);
+    say(`2. Sign in and approve pairing code ${style(1, sanitizeTerminal(created.userCode))}.`);
     say(`   The code expires at ${new Date(created.expiresAt).toLocaleTimeString()}.`);
     if (options.noOpen) {
         say("   (Browser opening skipped: --no-open.)");
     }
-    else if (openBrowser(created.verificationUrl)) {
+    else if (openBrowser(verificationUrl)) {
         say("   A browser window should open.");
     }
     else {
@@ -528,13 +638,20 @@ export async function runConnect(options = {}, mode = "connect") {
     say();
     say(mode === "rotate" ? "Waiting for approval (the previous token stays valid until then)..." : "Waiting for approval...");
     const approved = await waitForApproval(baseUrl, created.deviceCode, created.interval, timeoutSeconds * 1000);
+    const tokenMode = TOKEN_PATTERN.exec(approved.token)?.[1];
+    if (!tokenMode || tokenMode !== approved.environment) {
+        throw new CliApiError(0, "invalid_credential", "Glyph Pay returned a credential that does not match its environment.");
+    }
+    if (approved.callbackSecret && !CALLBACK_SECRET_PATTERN.test(approved.callbackSecret)) {
+        throw new CliApiError(0, "invalid_callback_secret", "Glyph Pay returned a callback secret in an unexpected format.");
+    }
     const values = { [TOKEN_KEY]: approved.token };
     if (approved.callbackSecret)
         values[CALLBACK_SECRET_KEY] = approved.callbackSecret;
     say();
-    say(style(1, `${mode === "rotate" ? "Rotated" : "Connected"} ${approved.businessName} (${approved.environment} mode).`));
+    say(style(1, `${mode === "rotate" ? "Rotated" : "Connected"} ${sanitizeTerminal(approved.businessName)} (${approved.environment} mode).`));
     if (approved.callbackUrl)
-        say(`Webhook registered: ${approved.callbackUrl}`);
+        say(`Webhook registered: ${sanitizeTerminal(approved.callbackUrl)}`);
     else
         say("No webhook was registered. Add one later in Glyph Pay admin if your site needs payment events.");
     let writtenTo = null;
@@ -555,7 +672,7 @@ export async function runConnect(options = {}, mode = "connect") {
         }
         catch (error) {
             say();
-            say(style(33, `Could not write ${file}: ${error instanceof Error ? error.message : String(error)}`));
+            say(style(33, `Could not write ${file}: ${sanitizeTerminal(error instanceof Error ? error.message : String(error))}`));
             say("Copy these values into your server environment now; they are shown only this once:");
             for (const [key, value] of Object.entries(values))
                 say(`${key}=${value}`);
@@ -587,7 +704,7 @@ export async function runRotate(options = {}) {
         try {
             const info = await fetchCredential(baseUrl, token);
             say();
-            say(`Rotating ${info.businessName} (${info.environment} mode).`);
+            say(`Rotating ${sanitizeTerminal(info.businessName)} (${sanitizeTerminal(info.environment)} mode).`);
             if (!url && info.callbackUrl)
                 url = info.callbackUrl;
         }
@@ -655,22 +772,21 @@ export async function runDisconnect(options = {}) {
     say();
     say(style(1, alreadyRevoked
         ? "That credential was already disconnected."
-        : `Disconnected ${businessName ?? "the site"}.`));
+        : `Disconnected ${businessName ? sanitizeTerminal(businessName) : "the site"}.`));
     if (removedKeys)
         say(`Removed ${TOKEN_KEY} and ${CALLBACK_SECRET_KEY} from ${displayEnv}.`);
     else
         say(`The credential is revoked. Local values in ${displayEnv} were kept.`);
     return { businessName, removedKeys, alreadyRevoked, canceled: false };
 }
-const TOKEN_PATTERN = /^dgsvc_(test|live)_[A-Za-z0-9_-]{1,128}_[A-Za-z0-9_-]{43}$/;
 function addDoctorCheck(report, check, json) {
     report.checks.push(check);
     if (json)
         return;
     const symbol = check.status === "ok" ? style(32, "✓") : check.status === "warn" ? style(33, "!") : style(31, "✗");
-    say(`${symbol} ${check.label}`);
+    say(`${symbol} ${sanitizeTerminal(check.label)}`);
     if (check.detail)
-        say(`   ${check.detail}`);
+        say(`   ${sanitizeTerminal(check.detail)}`);
 }
 function signedTestEvent(secret, environment) {
     const createdAt = new Date().toISOString();
@@ -739,6 +855,20 @@ export async function runDoctor(options = {}) {
     addDoctorCheck(report, exists
         ? { id: "env", status: "ok", label: `Found ${displayEnv}` }
         : { id: "env", status: "error", label: `${displayEnv} was not found`, detail: "Run `glyphpay connect` first or pass --env <path>." }, json);
+    if (exists) {
+        const ignored = spawnSync("git", ["check-ignore", "-q", "--", envFile], {
+            cwd: dirname(envFile),
+            stdio: "ignore",
+        });
+        if (ignored.status === 1) {
+            addDoctorCheck(report, {
+                id: "env-gitignored",
+                status: "warn",
+                label: `${displayEnv} is not ignored by git`,
+                detail: "Add it to .gitignore before committing; it contains a service credential.",
+            }, json);
+        }
+    }
     const contents = await readEnvFile(envFile);
     const token = readEnvValue(contents, TOKEN_KEY);
     const callbackSecret = readEnvValue(contents, CALLBACK_SECRET_KEY);
@@ -798,7 +928,15 @@ export async function runDoctor(options = {}) {
                     ? "Complete Stripe onboarding in Design Glyph admin, then re-check."
                     : "No connected account is linked to this client yet.",
             }, json);
-        if (info.callbackUrl) {
+        if (info.callbackUrl && !isProbeableCallbackUrl(info.callbackUrl)) {
+            addDoctorCheck(report, {
+                id: "callback-url",
+                status: "error",
+                label: "Webhook URL is not a public HTTPS URL",
+                detail: "Refusing to contact it from this machine. Register a public HTTPS callback URL.",
+            }, json);
+        }
+        else if (info.callbackUrl) {
             addDoctorCheck(report, { id: "callback-url", status: "ok", label: "Webhook URL is registered", detail: info.callbackUrl }, json);
             addDoctorCheck(report, callbackSecret
                 ? { id: "callback-secret", status: "ok", label: "Callback signing secret is present locally" }
@@ -900,10 +1038,10 @@ export async function runDoctor(options = {}) {
 /* Webhook deliveries                                                  */
 /* ------------------------------------------------------------------ */
 function printDelivery(delivery) {
-    say(`  ${delivery.id}  ${delivery.type}  ${delivery.state.toUpperCase()}  ` +
-        `attempt ${delivery.attempts}  ${delivery.updatedAt}`);
+    say(sanitizeTerminal(`  ${delivery.id}  ${delivery.type}  ${delivery.state.toUpperCase()}  ` +
+        `attempt ${delivery.attempts}  ${delivery.updatedAt}`));
     if (delivery.lastError)
-        say(`    ${delivery.lastError}`);
+        say(`    ${sanitizeTerminal(delivery.lastError)}`);
 }
 export async function runDeliveries(options = {}) {
     const baseUrl = baseUrlFor(options);
@@ -923,7 +1061,7 @@ export async function runDeliveries(options = {}) {
             say(style(1, `Webhook ${result.outcome === "delivered" ? "delivered" : "not delivered"}.`));
             printDelivery(result.delivery);
             if (result.detail)
-                say(`  ${result.detail}`);
+                say(`  ${sanitizeTerminal(result.detail)}`);
         }
         return result;
     }
@@ -941,7 +1079,7 @@ export async function runDeliveries(options = {}) {
         return result;
     }
     say();
-    say(style(1, `Webhook deliveries - ${result.businessName} (${result.environment} mode)`));
+    say(style(1, `Webhook deliveries - ${sanitizeTerminal(result.businessName)} (${sanitizeTerminal(result.environment)} mode)`));
     say();
     if (result.deliveries.length === 0) {
         say(options.state ? `No ${options.state} deliveries recorded.` : "No deliveries recorded yet.");
@@ -1255,7 +1393,7 @@ export async function main(argv = process.argv.slice(2)) {
             return 2;
         }
         say();
-        say(style(31, error instanceof Error ? error.message : String(error)));
+        say(style(31, sanitizeTerminal(error instanceof Error ? error.message : String(error))));
         return 1;
     }
 }

package/dist/security.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Browser-side URL safety helpers. Kept separate from the Stripe loader so the
+ * rules can be tested without a DOM.
+ */
+/** Resolve a post-payment return URL, rejecting cross-origin targets unless explicitly allowed. */
+export declare function resolveReturnUrl(returnUrl: string, baseHref: string, allowCrossOrigin?: boolean): string;

package/dist/security.js

@@ -0,0 +1,16 @@
+/**
+ * Browser-side URL safety helpers. Kept separate from the Stripe loader so the
+ * rules can be tested without a DOM.
+ */
+/** Resolve a post-payment return URL, rejecting cross-origin targets unless explicitly allowed. */
+export function resolveReturnUrl(returnUrl, baseHref, allowCrossOrigin = false) {
+    const base = new URL(baseHref);
+    const target = new URL(returnUrl, base);
+    if (target.protocol !== "http:" && target.protocol !== "https:") {
+        throw new Error("returnUrl must be an http(s) URL.");
+    }
+    if (!allowCrossOrigin && target.origin !== base.origin) {
+        throw new Error("returnUrl must use this site's origin.");
+    }
+    return target.href;
+}

package/dist/server.d.ts

@@ -8,8 +8,15 @@ export interface GlyphPayOptions {
     token: string | undefined;
     /** Signing secret shown when the callback URL was saved in Design Glyph admin. Needed for `webhook`. */
     callbackSecret?: string;
-    /** Defaults to the Design Glyph production origin. */
+    /** Defaults to the Design Glyph production origin. Non-HTTPS is allowed only for loopback development. */
     baseUrl?: string;
+    /** Additional browser origins allowed to call the checkout route. Defaults to same-origin only. */
+    allowedCheckoutOrigins?: string[];
+    /**
+     * Optional hook for rate limiting, a bot challenge, or a cart/session check
+     * before a PaymentIntent is created. Throw `CheckoutError` to show its message.
+     */
+    beforeCheckout?: (req: Request) => Promise<void> | void;
     /**
      * Price the order from YOUR data (DB, cart, CMS). Never trust an amount sent by the browser.
      * `orderId` must change whenever the amount or description changes (e.g. `${cartId}-v${version}`):
@@ -17,6 +24,12 @@ export interface GlyphPayOptions {
      * Throw `CheckoutError` to show the shopper a message.
      */
     priceOrder?: (body: unknown, req: Request) => Promise<Order> | Order;
+    /**
+     * Optional replay guard. Return true when this event id was already
+     * processed. GlyphPay delivers at-least-once, so handlers must still be
+     * idempotent if this hook is not used.
+     */
+    seen?: (eventId: string) => Promise<boolean> | boolean;
     /** Runs once per verified callback. Delivery is at-least-once, so dedupe on `event.id`. Throw to have it retried. */
     onEvent?: (event: GlyphPayEvent) => Promise<void> | void;
 }
@@ -72,9 +85,11 @@ export declare class GlyphPayError extends Error {
     status: number;
     constructor(status: number, message: string);
 }
-/** Throw from `priceOrder` to send `message` to the shopper with a 400. */
+/** Throw from `priceOrder` or `beforeCheckout` to send `message` to the shopper with a 400. */
 export declare class CheckoutError extends Error {
 }
+/** Validate and normalize the API origin. HTTPS is required outside loopback development. */
+export declare function normalizeBaseUrl(raw: string): string;
 export declare function glyphPay(options: GlyphPayOptions): {
     /** Route handler: `export const POST = glyphpay.checkout`. Prices the order, returns what the browser needs. */
     checkout: (req: Request) => Promise<Response>;
@@ -91,5 +106,9 @@ export declare function glyphPay(options: GlyphPayOptions): {
     /** Re-read the payment from Stripe if a callback looks missed. */
     reconcile: (paymentId: string) => Promise<Payment>;
 };
-/** Verifies `Designglyph-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "t.body")>` and returns the event. Rejects >5 min skew. */
+/**
+ * Verifies `Designglyph-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "t.body")>`.
+ * Multiple `v1` values are accepted so a secret can be rotated with an overlap.
+ * Rejects >5 min skew and returns the parsed event.
+ */
 export declare function verifyCallback(rawBody: string, header: string | null, secret: string): Promise<GlyphPayEvent>;

package/dist/server.js

@@ -3,6 +3,8 @@
  * must only ever run on the client site's server (route handlers, API routes).
  * Runtime-agnostic: uses fetch + Web Crypto (Node 20+, Next.js, edge, Workers).
  */
+const DEFAULT_BASE_URL = "https://designglyph.web.app";
+const MAX_BODY_BYTES = 1_000_000;
 /** Error from the GlyphPay API (status/message are the API's). */
 export class GlyphPayError extends Error {
     status;
@@ -11,13 +13,115 @@ export class GlyphPayError extends Error {
         this.status = status;
     }
 }
-/** Throw from `priceOrder` to send `message` to the shopper with a 400. */
+/** Throw from `priceOrder` or `beforeCheckout` to send `message` to the shopper with a 400. */
 export class CheckoutError extends Error {
 }
+/** Validate and normalize the API origin. HTTPS is required outside loopback development. */
+export function normalizeBaseUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new GlyphPayError(500, "GlyphPay baseUrl is not a valid URL.");
+    }
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    const loopback = host === "localhost" || host === "127.0.0.1" || host === "::1";
+    if (url.protocol !== "https:" && !(loopback && url.protocol === "http:")) {
+        throw new GlyphPayError(500, "GlyphPay baseUrl must use https (http is allowed only for localhost).");
+    }
+    if (url.username || url.password) {
+        throw new GlyphPayError(500, "GlyphPay baseUrl must not contain credentials.");
+    }
+    const path = url.pathname.replace(/\/+$/, "");
+    const normalized = `${url.origin}${path}`;
+    if (normalized !== DEFAULT_BASE_URL)
+        console.warn(`GlyphPay: using non-default API origin ${normalized}.`);
+    return normalized;
+}
+async function readBody(req, maxBytes = MAX_BODY_BYTES) {
+    const lengthHeader = req.headers.get("content-length");
+    if (lengthHeader !== null) {
+        const length = Number(lengthHeader);
+        if (!Number.isSafeInteger(length) || length < 0)
+            throw new GlyphPayError(400, "Invalid Content-Length.");
+        if (length > maxBytes)
+            throw new GlyphPayError(413, "Request body is too large.");
+    }
+    if (!req.body)
+        return "";
+    const reader = req.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel().catch(() => undefined);
+                throw new GlyphPayError(413, "Request body is too large.");
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch { /* already released */ }
+    }
+    const merged = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(merged);
+}
+async function readJson(req) {
+    const text = await readBody(req);
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function checkoutOriginAllowed(req, allowed) {
+    const origin = req.headers.get("origin");
+    if (!origin)
+        return true; // server-to-server callers do not send Origin
+    try {
+        return origin === new URL(req.url).origin || allowed.includes(origin);
+    }
+    catch {
+        return false;
+    }
+}
+/** Parse `t=…,v1=…,v1=…` without object keys, so header values cannot pollute prototypes. */
+function parseSignatureHeader(header) {
+    const result = { timestamp: null, signatures: [] };
+    for (const raw of (header ?? "").split(",")) {
+        const index = raw.indexOf("=");
+        if (index < 1)
+            continue;
+        const key = raw.slice(0, index).trim();
+        const value = raw.slice(index + 1).trim();
+        if (key === "t" && result.timestamp === null)
+            result.timestamp = value;
+        if (key === "v1")
+            result.signatures.push(value);
+    }
+    return result;
+}
 export function glyphPay(options) {
-    const baseUrl = (options.baseUrl ?? "https://designglyph.web.app").replace(/\/$/, "");
+    const baseUrl = normalizeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
     async function call(method, path, body) {
-        // ponytail: checked per call, not at construction, so `next build` works without env vars.
+        // Checked per call, not at construction, so `next build` works without env vars.
         if (!/^dgsvc_(test|live)_/.test(options.token ?? ""))
             throw new GlyphPayError(500, "GlyphPay token is missing or not a dgsvc_ service credential.");
         const res = await fetch(`${baseUrl}/api/client/v1${path}`, {
@@ -47,13 +151,25 @@ export function glyphPay(options) {
             try {
                 if (!options.priceOrder)
                     throw new Error("GlyphPay: priceOrder is required for checkout.");
-                const session = await api.createPayment(await options.priceOrder(await req.json().catch(() => null), req));
+                if (!checkoutOriginAllowed(req, options.allowedCheckoutOrigins ?? [])) {
+                    return Response.json({ error: "Checkout requests must come from this site." }, { status: 403 });
+                }
+                const contentType = req.headers.get("content-type")?.split(";")[0].trim().toLowerCase();
+                if (contentType && contentType !== "application/json") {
+                    return Response.json({ error: "Checkout requires application/json." }, { status: 415 });
+                }
+                const body = await readJson(req);
+                await options.beforeCheckout?.(req);
+                const session = await api.createPayment(await options.priceOrder(body, req));
                 const { clientSecret, publishableKey, stripeAccount } = session;
                 return Response.json({ clientSecret, publishableKey, stripeAccount, paymentId: session.id }, { headers: { "cache-control": "no-store" } });
             }
             catch (error) {
                 if (error instanceof CheckoutError)
                     return Response.json({ error: error.message }, { status: 400 });
+                if (error instanceof GlyphPayError && error.status === 413) {
+                    return Response.json({ error: "Checkout request is too large." }, { status: 413 });
+                }
                 console.error("GlyphPay checkout failed:", error instanceof Error ? error.message : error);
                 return Response.json({ error: "Checkout is unavailable right now. Please try again." }, { status: 502 });
             }
@@ -63,14 +179,30 @@ export function glyphPay(options) {
             // 5xx makes GlyphPay retry (up to 72h), so config and handler errors don't lose events. A bad signature is a permanent 400.
             if (!options.callbackSecret)
                 return new Response("GlyphPay callback secret not configured", { status: 500 });
+            let rawBody;
+            try {
+                rawBody = await readBody(req);
+            }
+            catch (error) {
+                const tooLarge = error instanceof GlyphPayError && error.status === 413;
+                return new Response(tooLarge ? "Payload too large" : "Bad request", { status: tooLarge ? 413 : 400 });
+            }
             let event;
             try {
-                event = await verifyCallback(await req.text(), req.headers.get("designglyph-signature"), options.callbackSecret);
+                event = await verifyCallback(rawBody, req.headers.get("designglyph-signature"), options.callbackSecret);
             }
             catch {
                 return new Response("Invalid signature", { status: 400 });
             }
+            const tokenMode = /^dgsvc_(test|live)_/.exec(options.token ?? "")?.[1];
+            if (!tokenMode)
+                return new Response("GlyphPay token not configured", { status: 500 });
+            if (event.livemode !== (tokenMode === "live")) {
+                return new Response("Event mode does not match this credential", { status: 400 });
+            }
             try {
+                if (options.seen && (await options.seen(event.id)))
+                    return new Response(null, { status: 204 });
                 await options.onEvent?.(event);
             }
             catch (error) {
@@ -81,16 +213,34 @@ export function glyphPay(options) {
         },
     };
 }
-/** Verifies `Designglyph-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "t.body")>` and returns the event. Rejects >5 min skew. */
+/**
+ * Verifies `Designglyph-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "t.body")>`.
+ * Multiple `v1` values are accepted so a secret can be rotated with an overlap.
+ * Rejects >5 min skew and returns the parsed event.
+ */
 export async function verifyCallback(rawBody, header, secret) {
-    const { t, v1 } = Object.fromEntries((header ?? "").split(",").map((part) => part.trim().split("=")));
+    if (!secret)
+        throw new GlyphPayError(400, "Invalid GlyphPay signature.");
+    const { timestamp, signatures } = parseSignatureHeader(header);
+    const timestampNumber = Number(timestamp);
+    const fresh = typeof timestamp === "string" && /^\d{1,12}$/.test(timestamp) &&
+        Math.abs(Date.now() / 1000 - timestampNumber) <= 300;
+    const validHex = signatures.filter((signature) => /^[0-9a-f]{64}$/.test(signature));
+    if (!fresh || validHex.length === 0)
+        throw new GlyphPayError(400, "Invalid GlyphPay signature.");
     const enc = new TextEncoder();
     const key = await crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
-    const signature = /^[0-9a-f]{64}$/.test(v1 ?? "") ? Uint8Array.from(v1.match(/../g), (h) => parseInt(h, 16)) : null;
-    const fresh = Math.abs(Date.now() / 1000 - Number(t)) <= 300;
-    // subtle.verify compares in constant time.
-    if (!signature || !fresh || !(await crypto.subtle.verify("HMAC", key, signature, enc.encode(`${t}.${rawBody}`)))) {
-        throw new GlyphPayError(400, "Invalid GlyphPay signature.");
+    const signed = enc.encode(`${timestamp}.${rawBody}`);
+    let matched = false;
+    for (const signature of validHex) {
+        const bytes = Uint8Array.from(signature.match(/../g), (hex) => parseInt(hex, 16));
+        // subtle.verify compares in constant time.
+        if (await crypto.subtle.verify("HMAC", key, bytes, signed)) {
+            matched = true;
+            break;
+        }
     }
+    if (!matched)
+        throw new GlyphPayError(400, "Invalid GlyphPay signature.");
     return JSON.parse(rawBody);
 }

package/package.json

@@ -1,60 +1,60 @@
-{
-  "name": "glyphpay",
-  "version": "0.5.0",
-  "description": "Drop-in GlyphPay checkout for websites, with a CLI for setup, diagnostics, and credential lifecycle.",
-  "homepage": "https://glyphpay.net",
-  "keywords": [
-    "glyphpay",
-    "payments",
-    "checkout",
-    "stripe",
-    "react",
-    "nextjs"
-  ],
-  "license": "UNLICENSED",
-  "type": "module",
-  "bin": {
-    "glyphpay": "dist/cli.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "exports": {
-    "./server": {
-      "types": "./dist/server.d.ts",
-      "default": "./dist/server.js"
-    },
-    "./browser": {
-      "types": "./dist/browser.d.ts",
-      "default": "./dist/browser.js"
-    },
-    "./react": {
-      "types": "./dist/react.d.ts",
-      "default": "./dist/react.js"
-    }
-  },
-  "scripts": {
-    "build": "tsc",
-    "prepare": "tsc",
-    "test": "tsc && node --test test/*.test.mjs"
-  },
-  "dependencies": {
-    "@stripe/stripe-js": "^10.2.1"
-  },
-  "peerDependencies": {
-    "react": ">=18"
-  },
-  "peerDependenciesMeta": {
-    "react": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@types/node": "^22.20.5",
-    "@types/react": "^19",
-    "typescript": "^5"
-  }
-}
+{
+  "name": "glyphpay",
+  "version": "1.0.1",
+  "description": "Drop-in GlyphPay checkout for websites, with a CLI for setup, diagnostics, and credential lifecycle.",
+  "homepage": "https://glyphpay.net",
+  "keywords": [
+    "glyphpay",
+    "payments",
+    "checkout",
+    "stripe",
+    "react",
+    "nextjs"
+  ],
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "glyphpay": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "test": "tsc && node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@stripe/stripe-js": "^10.2.1"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "@types/react": "^19",
+    "typescript": "^5"
+  }
+}