nixamp 0.28.43 → 0.28.44

package/README.md

@@ -619,9 +619,14 @@ multiplied by five. Credentials and balances never travel in checkout URLs.
 New checkout creation is capped at five per account and fifty per account server
 per UTC day, plus IP and request throttles; retries reuse the original invoice.
 
-After the ten free sessions, new sessions require purchased credit. Configure `COINPAY_X402_KEY`
-with `payments:create` permission and at least one business wallet; the scoped
-key supplies the merchant identity. Free sessions and existing credit still work during a
+After the ten free sessions, new sessions require purchased credit. Configure `COINPAY_API_KEY`
+(the older name `COINPAY_X402_KEY` still works; `COINPAY_API_KEY` wins when both are set)
+with `payments:create` and `payments:read` permission and at least one business wallet. The scoped
+key supplies the merchant identity, so it must belong to nixamp's own CoinPay business. Set
+`COINPAY_WEBHOOK_SECRET` to that business's webhook secret and its webhook URL to
+`https://<site>/api/v1/webhooks/coinpay`, and a paid order is credited even if the buyer never
+comes back to the page. The webhook body is only a nudge: the order is re-checked with CoinPay
+before anything is credited, and it is credited once however many times it is delivered. Free sessions and existing credit still work during a
 checkout outage. A self-hosted operator explicitly sponsoring API usage may set
 `NIXAMP_TRANSLATION_BILLING=off`.
 

package/dist/accounts.js

@@ -96,11 +96,19 @@ export class Accounts {
             (options.system
                 ? null
                 : new PostgresAdapter({ connectionString: options.connectionString }));
+        // Without a secret the module signs with a public default, and anyone can
+        // mint a session for any account. Refuse rather than run that way.
+        if (!options.system && !options.secret) {
+            throw new Error("NIXAMP_JWT_SECRET is required for accounts");
+        }
         this.system =
             options.system ??
                 createAuthSystem({
                     adapter,
-                    jwtSecret: options.secret,
+                    // tokenOptions.secret, not jwtSecret: the module has no top-level
+                    // jwtSecret, and until 2026-10-09 this passed one, so every JWT was
+                    // signed with the module's public default secret.
+                    tokenOptions: { secret: options.secret },
                     // The module defaults to requiring an uppercase and a lowercase
                     // letter. Its rules have to match the ones checked above, or a password
                     // this accepts is refused a layer down in a different sentence.

package/dist/paywall.js

@@ -134,7 +134,7 @@ export function paywallFromEnv(env = process.env) {
     return {
         enabled: env["NIXAMP_X402"] === "1",
         payTo: env["NIXAMP_PAY_TO"] ?? "",
-        coinpayKey: env["COINPAY_X402_KEY"] ?? "",
+        coinpayKey: env["COINPAY_API_KEY"] || env["COINPAY_X402_KEY"] || "",
         priceCents: Number.isFinite(price) && price > 0 ? Math.floor(price) : DEFAULT_PAYWALL.priceCents,
         passMinutes: Number.isFinite(minutes) && minutes > 0 ? Math.floor(minutes) : DEFAULT_PAYWALL.passMinutes,
     };

package/dist/server.d.ts

@@ -143,6 +143,20 @@ export interface ServeOptions {
      */
     rtmp: string[];
 }
+/**
+ * Read DATABASE_URL the way libpq does.
+ *
+ * node-postgres reads `sslmode=require` as verify-full, so a cluster that
+ * signs its own certificate (dev2's shared Postgres) refuses every query with
+ * "self signed certificate" while the process itself stays up and healthy:
+ * pages serve, accounts and follows and events all fail. libpq, and every
+ * other client, read `require` as "encrypt, do not verify", and pg honours
+ * that reading when the URL carries `uselibpqcompat=true`. Railway's internal
+ * URL had no sslmode at all, which is why this never came up there. Only
+ * `require` and `prefer` are rewritten: `no-verify` is pg's own spelling and
+ * has no libpq meaning, and `verify-*` asks for exactly what pg does anyway.
+ */
+export declare function libpqDatabaseUrl(raw: string | undefined): string | undefined;
 /**
  * Flags are parsed by hand: three of them do not justify a dependency, and the
  * failure mode of a wrong `--port` should be a message rather than NaN.
@@ -723,6 +737,8 @@ export interface HandlerOptions {
     speech?: Speech;
     liveVoice?: LiveVoice;
     translationPasses?: TranslationPasses;
+    /** Signing secret of nixamp's CoinPay business, for /api/v1/webhooks/coinpay. */
+    coinpayWebhookSecret?: string;
     sharedTranslations?: SharedTranslations;
     /** Translation: texts in another language, by a model here. The same optional library. */
     translator?: Translator;

package/dist/server.js

@@ -20,7 +20,7 @@ import { Readable } from "node:stream";
 import { pipeline as pipeStream } from "node:stream/promises";
 import { relative } from "node:path";
 import { SharedTranslations } from "./shared-translation.js";
-import { TranslationPasses } from "./translation-passes.js";
+import { TranslationPasses, coinpayKeyFrom, readCoinpayWebhook, verifyCoinpaySignature } from "./translation-passes.js";
 import { LiveVoice, LIVE_VOICE_LANGUAGES, LIVE_VOICE_MODEL } from "./live-voice.js";
 import { Connections } from "./connections.js";
 import { Broadcaster, DEFAULT_ENCODER, PRESETS, redact, } from "./broadcast.js";
@@ -106,6 +106,24 @@ import { emptySnapshot, parseCommand, } from "./protocol.js";
 const FFT_SIZE = 2048;
 export const SERVE_BAND_COUNT = 24;
 export const DEFAULT_PORT = 4321;
+/**
+ * Read DATABASE_URL the way libpq does.
+ *
+ * node-postgres reads `sslmode=require` as verify-full, so a cluster that
+ * signs its own certificate (dev2's shared Postgres) refuses every query with
+ * "self signed certificate" while the process itself stays up and healthy:
+ * pages serve, accounts and follows and events all fail. libpq, and every
+ * other client, read `require` as "encrypt, do not verify", and pg honours
+ * that reading when the URL carries `uselibpqcompat=true`. Railway's internal
+ * URL had no sslmode at all, which is why this never came up there. Only
+ * `require` and `prefer` are rewritten: `no-verify` is pg's own spelling and
+ * has no libpq meaning, and `verify-*` asks for exactly what pg does anyway.
+ */
+export function libpqDatabaseUrl(raw) {
+    if (!raw || !/[?&]sslmode=(require|prefer)\b/.test(raw) || /[?&]uselibpqcompat=/.test(raw))
+        return raw;
+    return `${raw}${raw.includes("?") ? "&" : "?"}uselibpqcompat=true`;
+}
 /**
  * Flags are parsed by hand: three of them do not justify a dependency, and the
  * failure mode of a wrong `--port` should be a message rather than NaN.
@@ -1906,6 +1924,57 @@ export function createHandler(engine, options) {
             json(response, 404, { error: "no such endpoint" });
             return;
         }
+        // --- CoinPay ----------------------------------------------------------
+        //
+        // Ahead of the share-key check because the caller is CoinPay, which signs
+        // the body instead. The body is only a nudge: settle() asks CoinPay for the
+        // payment itself before anything is credited.
+        if (path === "/api/v1/webhooks/coinpay") {
+            if (request.method !== "POST") {
+                json(response, 405, { error: "POST only" });
+                return;
+            }
+            const secret = options.coinpayWebhookSecret ?? "";
+            if (!secret) {
+                json(response, 503, { error: "CoinPay webhooks are not configured here." });
+                return;
+            }
+            let raw;
+            try {
+                raw = await readBody(request);
+            }
+            catch {
+                json(response, 413, { error: "body too large" });
+                return;
+            }
+            const signature = request.headers["x-coinpay-signature"];
+            if (!verifyCoinpaySignature(raw, Array.isArray(signature) ? signature[0] : signature, secret)) {
+                json(response, 401, { error: "invalid signature" });
+                return;
+            }
+            let event;
+            try {
+                event = readCoinpayWebhook(JSON.parse(raw));
+            }
+            catch {
+                json(response, 400, { error: "invalid JSON" });
+                return;
+            }
+            if (!options.translationPasses) {
+                json(response, 200, { settled: false, reason: "billing is off here" });
+                return;
+            }
+            try {
+                json(response, 200, await options.translationPasses.settle(event.paymentId));
+            }
+            catch (error) {
+                // A 5xx makes CoinPay deliver it again, which is what an unreachable
+                // CoinPay or database needs.
+                console.error(`nixamp: CoinPay webhook for ${event.paymentId} could not settle: ${error instanceof Error ? error.message : String(error)}`);
+                json(response, 500, { error: "could not settle; retry" });
+            }
+            return;
+        }
         // --- the party line ---------------------------------------------------
         //
         // Ahead of the share-key check because the caller is a telephone. Telnyx
@@ -5917,8 +5986,9 @@ export async function serve(argv, version = "0.1.0") {
     // pocket can administer it from anywhere by signing in as the same person.
     // Following outlives every stream, so unlike the rest of this it wants a
     // database. Only where there is one: a nixamp on a laptop has no followers.
-    const pool = options.directory && process.env["DATABASE_URL"]
-        ? new pg.Pool({ connectionString: process.env["DATABASE_URL"] })
+    const databaseUrl = libpqDatabaseUrl(process.env["DATABASE_URL"]);
+    const pool = options.directory && databaseUrl
+        ? new pg.Pool({ connectionString: databaseUrl })
         : undefined;
     const follows = pool ? new Follows(pool) : undefined;
     const favorites = pool ? new Favorites(pool) : undefined;
@@ -5943,9 +6013,9 @@ export async function serve(argv, version = "0.1.0") {
     // the handler options because the authorization server issues its access
     // tokens out of the same table -- an OAuth token IS a nixamp token with a
     // client's name on it, which is why every existing route understands one.
-    const accounts = options.directory && process.env["DATABASE_URL"]
+    const accounts = options.directory && databaseUrl
         ? new Accounts({
-            connectionString: process.env["DATABASE_URL"],
+            connectionString: databaseUrl,
             secret: process.env["NIXAMP_JWT_SECRET"] ?? "",
         })
         : undefined;
@@ -5956,7 +6026,7 @@ export async function serve(argv, version = "0.1.0") {
     // Account servers meter paid providers by default, including when checkout
     // is temporarily unconfigured. Self-hosters can explicitly sponsor usage.
     const translationPasses = accounts && pool && process.env["NIXAMP_TRANSLATION_BILLING"] !== "off"
-        ? new TranslationPasses({ db: pool, key: process.env["COINPAY_X402_KEY"] ?? "", site: nixampSite }) : undefined;
+        ? new TranslationPasses({ db: pool, key: coinpayKeyFrom(), site: nixampSite }) : undefined;
     if (translationPasses)
         void translationPasses.access().catch(() => console.error("nixamp: translation checkout could not warm; it will retry on demand"));
     const liveVoice = accounts && process.env["NIXAMP_DUBBING"] !== "off" ? new LiveVoice({
@@ -6502,6 +6572,7 @@ export async function serve(argv, version = "0.1.0") {
         ...(speech ? { speech } : {}),
         ...(liveVoice ? { liveVoice } : {}),
         ...(translationPasses ? { translationPasses } : {}),
+        ...(process.env["COINPAY_WEBHOOK_SECRET"] ? { coinpayWebhookSecret: process.env["COINPAY_WEBHOOK_SECRET"] } : {}),
         ...(sharedTranslations ? { sharedTranslations } : {}),
         ...(translator ? { translator } : {}),
         ...(transcripts ? { transcripts } : {}),

package/dist/tickets.js

@@ -145,7 +145,7 @@ export class Tickets {
 }
 /** Read a Tickets configuration out of the environment. */
 export function ticketsFromEnv(site, env = process.env) {
-    const coinpayKey = env["COINPAY_X402_KEY"] ?? "";
+    const coinpayKey = env["COINPAY_API_KEY"] || env["COINPAY_X402_KEY"] || "";
     if (!coinpayKey)
         return null;
     return {

package/dist/translation-passes.d.ts

@@ -54,6 +54,23 @@ export declare function translationCost(kind: TranslationUsage, units: number):
     charge: number;
 };
 export declare function verifyTranslationPayment(payment: Record<string, unknown>, id: string, priceCents: number): boolean;
+/** Which CoinPay key this deployment sells with. `COINPAY_API_KEY` is nixamp's
+ * own business; `COINPAY_X402_KEY` is the older name, still honoured so a box
+ * that has only it keeps selling. The own key wins, because the fleet-wide
+ * x402 key belongs to another site's business and would book nixamp's sales
+ * (and send its webhooks) there. */
+export declare function coinpayKeyFrom(env?: NodeJS.ProcessEnv): string;
+/** CoinPay signs `t=<unix>,v1=<hex HMAC-SHA256 of "t.rawBody">` and allows
+ * 300 s of skew. Computed over the raw bytes: reserialising changes them. */
+export declare function verifyCoinpaySignature(raw: string, header: string | undefined, secret: string, nowMs?: number): boolean;
+/** CoinPay's webhook nests the payment under `data`, and its top-level `id` is
+ * the EVENT (`evt_…`), not the payment. Read `data` first; the flat shape is
+ * only the older test sender's. */
+export declare function readCoinpayWebhook(payload: unknown): {
+    type: string;
+    paymentId: string;
+    status: string;
+};
 export declare class TranslationPasses implements TranslationMeter {
     private readonly options;
     private schema;
@@ -90,6 +107,18 @@ export declare class TranslationPasses implements TranslationMeter {
         id: string;
         url: string;
     }>;
+    /**
+     * A CoinPay webhook only says "look again". The order is settled by asking
+     * CoinPay, exactly as a returning buyer's check does, so a replayed or
+     * stale body cannot credit anything and a second delivery (confirmed, then
+     * forwarded) credits nothing twice. A payment that is not ours is answered,
+     * not failed: CoinPay would otherwise retry it forever.
+     */
+    settle(paymentId: string): Promise<{
+        settled: boolean;
+        status?: string;
+        reason?: string;
+    }>;
     check(by: string, id: string): Promise<{
         status: string;
         access: TranslationAccess;

package/dist/translation-passes.js

@@ -1,6 +1,6 @@
 /** Account-bound, prepaid translation credit. Money is integer micro-USD;
  * each listening account reserves 5x base provider cost for paid access. */
-import { randomUUID } from "node:crypto";
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
 import { SpeechError } from "./speech.js";
 import { UpgradeAllowances } from "./upgrade-allowance.js";
 export const TRANSLATION_MULTIPLIER = 5;
@@ -33,6 +33,47 @@ export function verifyTranslationPayment(payment, id, priceCents) {
     return payment["id"] === id && PAID.has(String(payment["status"])) &&
         String(payment["currency"]).toUpperCase() === "USD" && cents(payment["amount"]) === priceCents;
 }
+/** Which CoinPay key this deployment sells with. `COINPAY_API_KEY` is nixamp's
+ * own business; `COINPAY_X402_KEY` is the older name, still honoured so a box
+ * that has only it keeps selling. The own key wins, because the fleet-wide
+ * x402 key belongs to another site's business and would book nixamp's sales
+ * (and send its webhooks) there. */
+export function coinpayKeyFrom(env = process.env) {
+    return env["COINPAY_API_KEY"] || env["COINPAY_X402_KEY"] || "";
+}
+/** CoinPay signs `t=<unix>,v1=<hex HMAC-SHA256 of "t.rawBody">` and allows
+ * 300 s of skew. Computed over the raw bytes: reserialising changes them. */
+export function verifyCoinpaySignature(raw, header, secret, nowMs = Date.now()) {
+    if (!secret || !header)
+        return false;
+    let t = "", v1 = "";
+    for (const part of header.split(",")) {
+        const at = part.indexOf("=");
+        const name = part.slice(0, at).trim(), value = part.slice(at + 1).trim();
+        if (name === "t")
+            t = value;
+        else if (name === "v1")
+            v1 = value;
+    }
+    if (!/^\d{1,12}$/.test(t) || !/^[a-f0-9]{64}$/i.test(v1))
+        return false;
+    if (Math.abs(nowMs / 1000 - Number(t)) > 300)
+        return false;
+    const expected = createHmac("sha256", secret).update(`${t}.${raw}`).digest();
+    return timingSafeEqual(expected, Buffer.from(v1, "hex"));
+}
+/** CoinPay's webhook nests the payment under `data`, and its top-level `id` is
+ * the EVENT (`evt_…`), not the payment. Read `data` first; the flat shape is
+ * only the older test sender's. */
+export function readCoinpayWebhook(payload) {
+    const body = payload && typeof payload === "object" ? payload : {};
+    const data = body["data"] && typeof body["data"] === "object" ? body["data"] : body;
+    return {
+        type: String(body["type"] ?? ""),
+        paymentId: String(data["payment_id"] ?? data["id"] ?? ""),
+        status: String(data["status"] ?? "").toLowerCase(),
+    };
+}
 export class TranslationPasses {
     options;
     schema = null;
@@ -202,6 +243,23 @@ export class TranslationPasses {
         }
         return { id: String(order["id"]), url: `https://coinpayportal.com/pay/${paymentId}` };
     }
+    /**
+     * A CoinPay webhook only says "look again". The order is settled by asking
+     * CoinPay, exactly as a returning buyer's check does, so a replayed or
+     * stale body cannot credit anything and a second delivery (confirmed, then
+     * forwarded) credits nothing twice. A payment that is not ours is answered,
+     * not failed: CoinPay would otherwise retry it forever.
+     */
+    async settle(paymentId) {
+        if (!ID.test(paymentId))
+            return { settled: false, reason: "unknown payment" };
+        await this.ensure();
+        const order = (await this.options.db.query("SELECT id, by_account FROM translation_orders WHERE payment_id = $1", [paymentId])).rows[0];
+        if (!order)
+            return { settled: false, reason: "unknown payment" };
+        const { status } = await this.check(String(order["by_account"]), String(order["id"]));
+        return { settled: status === "paid", status };
+    }
     async check(by, id) {
         if (!ID.test(id))
             throw new SpeechError("Purchase not found.", 404);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.28.43",
+  "version": "0.28.44",
   "description": "It really whips the terminal's ass. A Winamp-shaped audio player for your terminal.",
   "license": "MIT",
   "type": "module",
@@ -45,7 +45,7 @@
     "pack:cli": "bun scripts/pack-cli.ts"
   },
   "dependencies": {
-    "@profullstack/auth-system": "^0.6.0",
+    "@profullstack/auth-system": "^0.8.3",
     "@profullstack/hqtui": "^0.5.0",
     "@profullstack/notifications": "^0.1.0",
     "@profullstack/synconfig": "^0.1.2",
@@ -60,6 +60,7 @@
   "devDependencies": {
     "@types/node": "^26",
     "@types/pg": "^8.23.1",
+    "jsonwebtoken": "^9.0.2",
     "typescript": "^7.0.2"
   },
   "trustedDependencies": [

package/src/accounts.ts

@@ -142,11 +142,19 @@ export class Accounts {
       (options.system
         ? null
         : (new PostgresAdapter({ connectionString: options.connectionString }) as unknown as AdapterLike));
+    // Without a secret the module signs with a public default, and anyone can
+    // mint a session for any account. Refuse rather than run that way.
+    if (!options.system && !options.secret) {
+      throw new Error("NIXAMP_JWT_SECRET is required for accounts");
+    }
     this.system =
       options.system ??
       (createAuthSystem({
         adapter,
-        jwtSecret: options.secret,
+        // tokenOptions.secret, not jwtSecret: the module has no top-level
+        // jwtSecret, and until 2026-10-09 this passed one, so every JWT was
+        // signed with the module's public default secret.
+        tokenOptions: { secret: options.secret },
         // The module defaults to requiring an uppercase and a lowercase
         // letter. Its rules have to match the ones checked above, or a password
         // this accepts is refused a layer down in a different sentence.

package/src/paywall.ts

@@ -168,7 +168,7 @@ export function paywallFromEnv(env: NodeJS.ProcessEnv = process.env): PaywallCon
   return {
     enabled: env["NIXAMP_X402"] === "1",
     payTo: env["NIXAMP_PAY_TO"] ?? "",
-    coinpayKey: env["COINPAY_X402_KEY"] ?? "",
+    coinpayKey: env["COINPAY_API_KEY"] || env["COINPAY_X402_KEY"] || "",
     priceCents: Number.isFinite(price) && price > 0 ? Math.floor(price) : DEFAULT_PAYWALL.priceCents,
     passMinutes:
       Number.isFinite(minutes) && minutes > 0 ? Math.floor(minutes) : DEFAULT_PAYWALL.passMinutes,

package/src/server.ts

@@ -20,7 +20,7 @@ import { Readable } from "node:stream";
 import { pipeline as pipeStream } from "node:stream/promises";
 import { relative } from "node:path";
 import { SharedTranslations, type SharedEvent } from "./shared-translation.ts";
-import { TranslationPasses } from "./translation-passes.ts";
+import { TranslationPasses, coinpayKeyFrom, readCoinpayWebhook, verifyCoinpaySignature } from "./translation-passes.ts";
 import { LiveVoice, LIVE_VOICE_LANGUAGES, LIVE_VOICE_MODEL, type VoiceRequest } from "./live-voice.ts";
 import { Connections, type Kind } from "./connections.ts";
 import {
@@ -255,6 +255,24 @@ export interface ServeOptions {
   rtmp: string[];
 }
 
+/**
+ * Read DATABASE_URL the way libpq does.
+ *
+ * node-postgres reads `sslmode=require` as verify-full, so a cluster that
+ * signs its own certificate (dev2's shared Postgres) refuses every query with
+ * "self signed certificate" while the process itself stays up and healthy:
+ * pages serve, accounts and follows and events all fail. libpq, and every
+ * other client, read `require` as "encrypt, do not verify", and pg honours
+ * that reading when the URL carries `uselibpqcompat=true`. Railway's internal
+ * URL had no sslmode at all, which is why this never came up there. Only
+ * `require` and `prefer` are rewritten: `no-verify` is pg's own spelling and
+ * has no libpq meaning, and `verify-*` asks for exactly what pg does anyway.
+ */
+export function libpqDatabaseUrl(raw: string | undefined): string | undefined {
+  if (!raw || !/[?&]sslmode=(require|prefer)\b/.test(raw) || /[?&]uselibpqcompat=/.test(raw)) return raw;
+  return `${raw}${raw.includes("?") ? "&" : "?"}uselibpqcompat=true`;
+}
+
 /**
  * Flags are parsed by hand: three of them do not justify a dependency, and the
  * failure mode of a wrong `--port` should be a message rather than NaN.
@@ -1796,6 +1814,8 @@ export interface HandlerOptions {
   speech?: Speech;
   liveVoice?: LiveVoice;
   translationPasses?: TranslationPasses;
+  /** Signing secret of nixamp's CoinPay business, for /api/v1/webhooks/coinpay. */
+  coinpayWebhookSecret?: string;
   sharedTranslations?: SharedTranslations;
   /** Translation: texts in another language, by a model here. The same optional library. */
   translator?: Translator;
@@ -2417,6 +2437,35 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
       return;
     }
 
+    // --- CoinPay ----------------------------------------------------------
+    //
+    // Ahead of the share-key check because the caller is CoinPay, which signs
+    // the body instead. The body is only a nudge: settle() asks CoinPay for the
+    // payment itself before anything is credited.
+    if (path === "/api/v1/webhooks/coinpay") {
+      if (request.method !== "POST") { json(response, 405, { error: "POST only" }); return; }
+      const secret = options.coinpayWebhookSecret ?? "";
+      if (!secret) { json(response, 503, { error: "CoinPay webhooks are not configured here." }); return; }
+      let raw: string;
+      try { raw = await readBody(request); } catch { json(response, 413, { error: "body too large" }); return; }
+      const signature = request.headers["x-coinpay-signature"];
+      if (!verifyCoinpaySignature(raw, Array.isArray(signature) ? signature[0] : signature, secret)) {
+        json(response, 401, { error: "invalid signature" }); return;
+      }
+      let event: ReturnType<typeof readCoinpayWebhook>;
+      try { event = readCoinpayWebhook(JSON.parse(raw)); } catch { json(response, 400, { error: "invalid JSON" }); return; }
+      if (!options.translationPasses) { json(response, 200, { settled: false, reason: "billing is off here" }); return; }
+      try {
+        json(response, 200, await options.translationPasses.settle(event.paymentId));
+      } catch (error) {
+        // A 5xx makes CoinPay deliver it again, which is what an unreachable
+        // CoinPay or database needs.
+        console.error(`nixamp: CoinPay webhook for ${event.paymentId} could not settle: ${error instanceof Error ? error.message : String(error)}`);
+        json(response, 500, { error: "could not settle; retry" });
+      }
+      return;
+    }
+
     // --- the party line ---------------------------------------------------
     //
     // Ahead of the share-key check because the caller is a telephone. Telnyx
@@ -6423,9 +6472,10 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
   // pocket can administer it from anywhere by signing in as the same person.
   // Following outlives every stream, so unlike the rest of this it wants a
   // database. Only where there is one: a nixamp on a laptop has no followers.
+  const databaseUrl = libpqDatabaseUrl(process.env["DATABASE_URL"]);
   const pool =
-    options.directory && process.env["DATABASE_URL"]
-      ? new pg.Pool({ connectionString: process.env["DATABASE_URL"] })
+    options.directory && databaseUrl
+      ? new pg.Pool({ connectionString: databaseUrl })
       : undefined;
   const follows = pool ? new Follows(pool) : undefined;
   const favorites = pool ? new Favorites(pool) : undefined;
@@ -6452,9 +6502,9 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
   // tokens out of the same table -- an OAuth token IS a nixamp token with a
   // client's name on it, which is why every existing route understands one.
   const accounts =
-    options.directory && process.env["DATABASE_URL"]
+    options.directory && databaseUrl
       ? new Accounts({
-          connectionString: process.env["DATABASE_URL"],
+          connectionString: databaseUrl,
           secret: process.env["NIXAMP_JWT_SECRET"] ?? "",
         })
       : undefined;
@@ -6465,7 +6515,7 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
   // Account servers meter paid providers by default, including when checkout
   // is temporarily unconfigured. Self-hosters can explicitly sponsor usage.
   const translationPasses = accounts && pool && process.env["NIXAMP_TRANSLATION_BILLING"] !== "off"
-    ? new TranslationPasses({ db: pool, key: process.env["COINPAY_X402_KEY"] ?? "", site: nixampSite }) : undefined;
+    ? new TranslationPasses({ db: pool, key: coinpayKeyFrom(), site: nixampSite }) : undefined;
   if (translationPasses) void translationPasses.access().catch(() => console.error("nixamp: translation checkout could not warm; it will retry on demand"));
   const liveVoice = accounts && process.env["NIXAMP_DUBBING"] !== "off" ? new LiveVoice({
     ...(pool ? { db: pool } : {}),
@@ -7015,6 +7065,7 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
     ...(speech ? { speech } : {}),
     ...(liveVoice ? { liveVoice } : {}),
     ...(translationPasses ? { translationPasses } : {}),
+    ...(process.env["COINPAY_WEBHOOK_SECRET"] ? { coinpayWebhookSecret: process.env["COINPAY_WEBHOOK_SECRET"] } : {}),
     ...(sharedTranslations ? { sharedTranslations } : {}),
     ...(translator ? { translator } : {}),
     ...(transcripts ? { transcripts } : {}),

package/src/tickets.ts

@@ -185,7 +185,7 @@ export function ticketsFromEnv(
   site: string,
   env: NodeJS.ProcessEnv = process.env,
 ): TicketOptions | null {
-  const coinpayKey = env["COINPAY_X402_KEY"] ?? "";
+  const coinpayKey = env["COINPAY_API_KEY"] || env["COINPAY_X402_KEY"] || "";
   if (!coinpayKey) return null;
   return {
     coinpayKey,

package/src/translation-passes.ts

@@ -1,6 +1,6 @@
 /** Account-bound, prepaid translation credit. Money is integer micro-USD;
  * each listening account reserves 5x base provider cost for paid access. */
-import { randomUUID } from "node:crypto";
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
 import type { Queryable } from "./follows.ts";
 import { SpeechError } from "./speech.ts";
 import { UpgradeAllowances, type UpgradeAllowance } from "./upgrade-allowance.ts";
@@ -53,6 +53,44 @@ export function verifyTranslationPayment(payment: Record<string, unknown>, id: s
     String(payment["currency"]).toUpperCase() === "USD" && cents(payment["amount"]) === priceCents;
 }
 
+/** Which CoinPay key this deployment sells with. `COINPAY_API_KEY` is nixamp's
+ * own business; `COINPAY_X402_KEY` is the older name, still honoured so a box
+ * that has only it keeps selling. The own key wins, because the fleet-wide
+ * x402 key belongs to another site's business and would book nixamp's sales
+ * (and send its webhooks) there. */
+export function coinpayKeyFrom(env: NodeJS.ProcessEnv = process.env): string {
+  return env["COINPAY_API_KEY"] || env["COINPAY_X402_KEY"] || "";
+}
+
+/** CoinPay signs `t=<unix>,v1=<hex HMAC-SHA256 of "t.rawBody">` and allows
+ * 300 s of skew. Computed over the raw bytes: reserialising changes them. */
+export function verifyCoinpaySignature(raw: string, header: string | undefined, secret: string, nowMs = Date.now()): boolean {
+  if (!secret || !header) return false;
+  let t = "", v1 = "";
+  for (const part of header.split(",")) {
+    const at = part.indexOf("=");
+    const name = part.slice(0, at).trim(), value = part.slice(at + 1).trim();
+    if (name === "t") t = value; else if (name === "v1") v1 = value;
+  }
+  if (!/^\d{1,12}$/.test(t) || !/^[a-f0-9]{64}$/i.test(v1)) return false;
+  if (Math.abs(nowMs / 1000 - Number(t)) > 300) return false;
+  const expected = createHmac("sha256", secret).update(`${t}.${raw}`).digest();
+  return timingSafeEqual(expected, Buffer.from(v1, "hex"));
+}
+
+/** CoinPay's webhook nests the payment under `data`, and its top-level `id` is
+ * the EVENT (`evt_…`), not the payment. Read `data` first; the flat shape is
+ * only the older test sender's. */
+export function readCoinpayWebhook(payload: unknown): { type: string; paymentId: string; status: string } {
+  const body = payload && typeof payload === "object" ? payload as Record<string, unknown> : {};
+  const data = body["data"] && typeof body["data"] === "object" ? body["data"] as Record<string, unknown> : body;
+  return {
+    type: String(body["type"] ?? ""),
+    paymentId: String(data["payment_id"] ?? data["id"] ?? ""),
+    status: String(data["status"] ?? "").toLowerCase(),
+  };
+}
+
 export class TranslationPasses implements TranslationMeter {
   private schema: Promise<void> | null = null;
   private merchant: Promise<{ business: string; coins: string[] }> | null = null;
@@ -209,6 +247,21 @@ export class TranslationPasses implements TranslationMeter {
     }
     return { id: String(order["id"]), url: `https://coinpayportal.com/pay/${paymentId}` };
   }
+  /**
+   * A CoinPay webhook only says "look again". The order is settled by asking
+   * CoinPay, exactly as a returning buyer's check does, so a replayed or
+   * stale body cannot credit anything and a second delivery (confirmed, then
+   * forwarded) credits nothing twice. A payment that is not ours is answered,
+   * not failed: CoinPay would otherwise retry it forever.
+   */
+  async settle(paymentId: string): Promise<{ settled: boolean; status?: string; reason?: string }> {
+    if (!ID.test(paymentId)) return { settled: false, reason: "unknown payment" };
+    await this.ensure();
+    const order = (await this.options.db.query("SELECT id, by_account FROM translation_orders WHERE payment_id = $1", [paymentId])).rows[0];
+    if (!order) return { settled: false, reason: "unknown payment" };
+    const { status } = await this.check(String(order["by_account"]), String(order["id"]));
+    return { settled: status === "paid", status };
+  }
   async check(by: string, id: string): Promise<{ status: string; access: TranslationAccess }> {
     if (!ID.test(id)) throw new SpeechError("Purchase not found.", 404);
     await this.ensure();

package/src/types/auth-system.d.ts

@@ -80,9 +80,18 @@ declare module "@profullstack/auth-system" {
 
   export function createAuthSystem(options?: {
     adapter?: unknown;
-    jwtSecret?: string;
-    accessTokenExpiry?: string | number;
-    refreshTokenExpiry?: string | number;
+    /**
+     * Signing for the module's JWTs. The secret goes HERE: the module has no
+     * top-level jwtSecret, and one there is silently ignored, leaving tokens
+     * signed with its public default ('default-secret-change-me').
+     */
+    tokenOptions?: {
+      secret?: string;
+      /** Seconds. */
+      accessTokenExpiry?: number;
+      /** Seconds. */
+      refreshTokenExpiry?: number;
+    };
     /**
      * Composition rules. Every "require" defaults to true except
      * requireSpecialChars, so leaving this out is stricter than passing it.

package/web/dist/.well-known/openwebring.json

@@ -0,0 +1,6 @@
+{
+  "openwebring": "0.1",
+  "site": { "url": "https://nixamp.com/", "name": "nixamp" },
+  "made_by": "both",
+  "rings": [{ "ring": "https://rssamplifier.com/ring/profullstack", "slug": "nixamp-com" }]
+}