brains-mcp 1.91.1 → 1.93.0

package/dist/billing/stripe.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Stripe Checkout, the path from a chosen tier to a hosted payment page
+ * (GH #1057).
+ *
+ * This is the first money-handling code in the repo. Three rules shape it.
+ *
+ * **Price ids come from the environment, never from the request.** A caller
+ * sends a tier name. This module turns that into a Price id. If the browser
+ * could name a price, anyone could buy the $39 tier at a price of their own
+ * making. Test mode and live mode also carry different ids, so hard-coding one
+ * would make the deploy that flips modes a code change.
+ *
+ * **Return URLs are built here, never taken from the request.** A
+ * caller-supplied `success_url` is an open redirect wearing a payment page as
+ * a disguise.
+ *
+ * **The session carries the subject, not the tier.** `client_reference_id`
+ * holds the Brains subject so the webhook in GH #1059 knows whose tier to
+ * write. The tier itself is read back from the Price id on the completed
+ * subscription, so a tampered session cannot grant a tier nobody paid for.
+ */
+import Stripe from "stripe";
+import type { BillingTier } from "./tierStore.js";
+/** The three tiers a customer can buy. The others are assigned by seedUsers. */
+export declare const PAID_TIERS: readonly ["solo", "pro", "unlimited"];
+export type PaidTier = (typeof PAID_TIERS)[number];
+export declare function isPaidTier(value: unknown): value is PaidTier;
+/** Every paid tier widens to a BillingTier, so tierStore can store it unchanged. */
+export declare function paidTierToBillingTier(tier: PaidTier): BillingTier;
+export interface StripeConfig {
+    secretKey: string;
+    prices: Record<PaidTier, string>;
+}
+export type StripeConfigResult = {
+    ok: true;
+    config: StripeConfig;
+} | {
+    ok: false;
+    missing: string[];
+};
+/**
+ * Read the Stripe configuration out of an environment.
+ *
+ * Returns the names of the variables that are missing rather than throwing.
+ * The server must keep serving wiki traffic when billing is not configured,
+ * which is the normal state of a local run and of any self-hosted instance.
+ */
+export declare function resolveStripeConfig(env?: NodeJS.ProcessEnv): StripeConfigResult;
+/**
+ * Build the URLs Stripe sends the customer back to.
+ *
+ * `webUrl` is the server's own `WEB_URL`, so neither value can be influenced
+ * by the caller. Stripe replaces `{CHECKOUT_SESSION_ID}` itself.
+ */
+export declare function checkoutReturnUrls(webUrl: string, tier: PaidTier): {
+    successUrl: string;
+    cancelUrl: string;
+};
+export interface CheckoutSessionRequest {
+    tier: PaidTier;
+    /** The Brains subject. Travels on the session so the webhook can resolve it. */
+    subject: string;
+    /** Prefills the Stripe payment page. Optional, because not every auth mode has one. */
+    email?: string;
+    config: StripeConfig;
+    webUrl: string;
+    /** Injected in tests. Defaults to a real Stripe client. */
+    stripe?: Pick<Stripe, "checkout">;
+}
+export interface CheckoutSessionResult {
+    id: string;
+    url: string;
+}
+/**
+ * Create a Stripe Checkout Session and return the URL to send the browser to.
+ *
+ * Throws when Stripe rejects the call or returns a session with no URL. The
+ * caller turns that into a 502, because a failure here is Stripe's side and
+ * not the customer's mistake.
+ */
+export declare function createCheckoutSession(req: CheckoutSessionRequest): Promise<CheckoutSessionResult>;
+/**
+ * Resolve the tier a Stripe subscription entitles its owner to.
+ *
+ * Status drives this before price does. A subscription whose price says "pro"
+ * but whose status says `canceled` entitles nobody to anything.
+ *
+ * `past_due` deliberately keeps the paid tier. Stripe retries a failed payment
+ * for days before giving up, and cutting a paying customer off at the first
+ * failed charge is a worse outcome than a few days of unpaid access. Stripe
+ * moves the subscription to `canceled` or `unpaid` when it stops retrying, and
+ * that is where access ends.
+ */
+export declare function tierForSubscription(subscription: {
+    status: string;
+    items: {
+        data: Array<{
+            price: {
+                id: string;
+            };
+        }>;
+    };
+}, prices: Record<PaidTier, string>): BillingTier;
+/** The Brains subject a subscription belongs to, or null when it carries none. */
+export declare function subjectForSubscription(subscription: {
+    metadata?: Record<string, string> | null;
+}): string | null;
+/** Event types that change a tier. Everything else is acknowledged and ignored. */
+export declare const HANDLED_WEBHOOK_EVENTS: readonly ["checkout.session.completed", "customer.subscription.updated", "customer.subscription.deleted"];
+export declare function isHandledWebhookEvent(type: string): boolean;
+/**
+ * The subscription id an event points at, or null when there is none to read.
+ *
+ * A `checkout.session.completed` for a subscription carries the subscription as
+ * an id or as an expanded object. The two subscription events carry the object
+ * itself.
+ */
+export declare function subscriptionIdForEvent(event: {
+    type: string;
+    data: {
+        object: unknown;
+    };
+}): string | null;
+//# sourceMappingURL=stripe.d.ts.map

package/dist/billing/stripe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stripe.d.ts","sourceRoot":"","sources":["../../src/billing/stripe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,gFAAgF;AAChF,eAAO,MAAM,UAAU,uCAAwC,CAAC;AAEhE,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED,oFAAoF;AACpF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,GAAG,WAAW,CAEjE;AASD,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GAClC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAErC;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,kBAAkB,CAmB5F;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAM5G;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,QAAQ,CAAC;IACf,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;IAChB,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAsBvG;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,KAAK,CAAC;YAAE,KAAK,EAAE;gBAAE,EAAE,EAAE,MAAM,CAAA;aAAE,CAAA;SAAE,CAAC,CAAA;KAAE,CAAA;CAAE,EACnF,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,GAC/B,WAAW,CAcb;AAED,kFAAkF;AAClF,wBAAgB,sBAAsB,CAAC,YAAY,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;CAAE,GAAG,MAAM,GAAG,IAAI,CAGhH;AAED,mFAAmF;AACnF,eAAO,MAAM,sBAAsB,2GAIzB,CAAC;AAEX,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,GAAG,MAAM,GAAG,IAAI,CAgBxG"}

package/dist/billing/stripe.js

@@ -0,0 +1,172 @@
+/**
+ * Stripe Checkout, the path from a chosen tier to a hosted payment page
+ * (GH #1057).
+ *
+ * This is the first money-handling code in the repo. Three rules shape it.
+ *
+ * **Price ids come from the environment, never from the request.** A caller
+ * sends a tier name. This module turns that into a Price id. If the browser
+ * could name a price, anyone could buy the $39 tier at a price of their own
+ * making. Test mode and live mode also carry different ids, so hard-coding one
+ * would make the deploy that flips modes a code change.
+ *
+ * **Return URLs are built here, never taken from the request.** A
+ * caller-supplied `success_url` is an open redirect wearing a payment page as
+ * a disguise.
+ *
+ * **The session carries the subject, not the tier.** `client_reference_id`
+ * holds the Brains subject so the webhook in GH #1059 knows whose tier to
+ * write. The tier itself is read back from the Price id on the completed
+ * subscription, so a tampered session cannot grant a tier nobody paid for.
+ */
+import Stripe from "stripe";
+/** The three tiers a customer can buy. The others are assigned by seedUsers. */
+export const PAID_TIERS = ["solo", "pro", "unlimited"];
+export function isPaidTier(value) {
+    return typeof value === "string" && PAID_TIERS.includes(value);
+}
+/** Every paid tier widens to a BillingTier, so tierStore can store it unchanged. */
+export function paidTierToBillingTier(tier) {
+    return tier;
+}
+/** Environment variable that holds the Price id for each paid tier. */
+const PRICE_ENV_VARS = {
+    solo: "STRIPE_PRICE_SOLO",
+    pro: "STRIPE_PRICE_PRO",
+    unlimited: "STRIPE_PRICE_UNLIMITED",
+};
+/**
+ * Read the Stripe configuration out of an environment.
+ *
+ * Returns the names of the variables that are missing rather than throwing.
+ * The server must keep serving wiki traffic when billing is not configured,
+ * which is the normal state of a local run and of any self-hosted instance.
+ */
+export function resolveStripeConfig(env = process.env) {
+    const missing = [];
+    const secretKey = (env.STRIPE_SECRET_KEY ?? "").trim();
+    if (!secretKey)
+        missing.push("STRIPE_SECRET_KEY");
+    const prices = {};
+    for (const tier of PAID_TIERS) {
+        const name = PRICE_ENV_VARS[tier];
+        const value = (env[name] ?? "").trim();
+        if (!value) {
+            missing.push(name);
+            continue;
+        }
+        prices[tier] = value;
+    }
+    if (missing.length > 0)
+        return { ok: false, missing };
+    return { ok: true, config: { secretKey, prices } };
+}
+/**
+ * Build the URLs Stripe sends the customer back to.
+ *
+ * `webUrl` is the server's own `WEB_URL`, so neither value can be influenced
+ * by the caller. Stripe replaces `{CHECKOUT_SESSION_ID}` itself.
+ */
+export function checkoutReturnUrls(webUrl, tier) {
+    const base = webUrl.replace(/\/$/, "");
+    return {
+        successUrl: `${base}/dashboard?checkout=success&session_id={CHECKOUT_SESSION_ID}`,
+        cancelUrl: `${base}/checkout?plan=${tier}&checkout=cancelled`,
+    };
+}
+/**
+ * Create a Stripe Checkout Session and return the URL to send the browser to.
+ *
+ * Throws when Stripe rejects the call or returns a session with no URL. The
+ * caller turns that into a 502, because a failure here is Stripe's side and
+ * not the customer's mistake.
+ */
+export async function createCheckoutSession(req) {
+    const client = req.stripe ?? new Stripe(req.config.secretKey);
+    const { successUrl, cancelUrl } = checkoutReturnUrls(req.webUrl, req.tier);
+    const session = await client.checkout.sessions.create({
+        mode: "subscription",
+        line_items: [{ price: req.config.prices[req.tier], quantity: 1 }],
+        success_url: successUrl,
+        cancel_url: cancelUrl,
+        client_reference_id: req.subject,
+        ...(req.email ? { customer_email: req.email } : {}),
+        // Read back by the webhook. client_reference_id is not copied onto the
+        // subscription, and subscription.updated events arrive with no session
+        // attached, so the subject has to live on the subscription too (GH #1059).
+        subscription_data: { metadata: { brains_subject: req.subject, brains_tier: req.tier } },
+        metadata: { brains_subject: req.subject, brains_tier: req.tier },
+    });
+    if (!session.url) {
+        throw new Error(`Stripe returned session ${session.id} with no URL`);
+    }
+    return { id: session.id, url: session.url };
+}
+// ── Webhook (GH #1059) ──────────────────────────────────────────────────────
+/**
+ * Resolve the tier a Stripe subscription entitles its owner to.
+ *
+ * Status drives this before price does. A subscription whose price says "pro"
+ * but whose status says `canceled` entitles nobody to anything.
+ *
+ * `past_due` deliberately keeps the paid tier. Stripe retries a failed payment
+ * for days before giving up, and cutting a paying customer off at the first
+ * failed charge is a worse outcome than a few days of unpaid access. Stripe
+ * moves the subscription to `canceled` or `unpaid` when it stops retrying, and
+ * that is where access ends.
+ */
+export function tierForSubscription(subscription, prices) {
+    const PAYING_STATUSES = ["active", "trialing", "past_due"];
+    if (!PAYING_STATUSES.includes(subscription.status))
+        return "free";
+    const priceId = subscription.items.data[0]?.price?.id;
+    if (!priceId)
+        return "free";
+    for (const tier of PAID_TIERS) {
+        if (prices[tier] === priceId)
+            return tier;
+    }
+    // A price we do not recognise is not a licence to guess. This happens when a
+    // Price is created in the dashboard and the environment variable is not
+    // updated, so it is logged by the caller rather than silently granting a tier.
+    return "free";
+}
+/** The Brains subject a subscription belongs to, or null when it carries none. */
+export function subjectForSubscription(subscription) {
+    const subject = subscription.metadata?.brains_subject;
+    return typeof subject === "string" && subject.trim() !== "" ? subject.trim() : null;
+}
+/** Event types that change a tier. Everything else is acknowledged and ignored. */
+export const HANDLED_WEBHOOK_EVENTS = [
+    "checkout.session.completed",
+    "customer.subscription.updated",
+    "customer.subscription.deleted",
+];
+export function isHandledWebhookEvent(type) {
+    return HANDLED_WEBHOOK_EVENTS.includes(type);
+}
+/**
+ * The subscription id an event points at, or null when there is none to read.
+ *
+ * A `checkout.session.completed` for a subscription carries the subscription as
+ * an id or as an expanded object. The two subscription events carry the object
+ * itself.
+ */
+export function subscriptionIdForEvent(event) {
+    const object = event.data.object;
+    if (!object)
+        return null;
+    if (event.type === "checkout.session.completed") {
+        const subscription = object.subscription;
+        if (typeof subscription === "string")
+            return subscription;
+        if (subscription && typeof subscription === "object") {
+            const id = subscription.id;
+            return typeof id === "string" ? id : null;
+        }
+        return null;
+    }
+    const id = object.id;
+    return typeof id === "string" ? id : null;
+}
+//# sourceMappingURL=stripe.js.map

package/dist/billing/stripe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stripe.js","sourceRoot":"","sources":["../../src/billing/stripe.ts"],"names":[],"mappings":"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"}

package/dist/billing/webhook.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Stripe webhook handling (GH #1059).
+ *
+ * This is where money becomes a tier. Stripe delivers an event, and
+ * `tierStore.set()` is called for the subject that paid.
+ *
+ * ## Why this reads the subscription back instead of trusting the event
+ *
+ * Stripe retries a webhook until it gets a 2xx, and it does not promise
+ * delivery order. The usual fix is a table of processed event ids plus a
+ * version comparison, so a replayed or late event cannot undo a newer one.
+ *
+ * This takes a different route. On any handled event it reads the
+ * **current** subscription from Stripe and writes the tier that matches it.
+ * The consequences:
+ *
+ * - A duplicate delivery writes the same value twice. Idempotent by
+ *   construction, with no event-id bookkeeping.
+ * - A late `subscription.deleted` that arrives after a newer
+ *   `subscription.updated` reads a live subscription and writes the paid tier.
+ *   It cannot strand a paying customer on `free`, which is the failure the
+ *   ordering guard exists to prevent.
+ * - No table, so no migration. That matters here specifically: production runs
+ *   migrations only inside the manual `Deploy Production` dispatch while
+ *   Railway deploys code on every push to `main`, so a table and its writer in
+ *   one change would work on staging and fail on production.
+ *
+ * The cost is one extra Stripe API call per event. At the volume a $9 to $39
+ * product generates that is not a consideration.
+ */
+import type Stripe from "stripe";
+import type { TierStore } from "./tierStore.js";
+import { type StripeConfig } from "./stripe.js";
+export type WebhookOutcome = 
+/** Event type we do not act on. Acknowledged so Stripe stops retrying. */
+{
+    status: "ignored";
+    reason: string;
+}
+/** A tier was written. */
+ | {
+    status: "applied";
+    subject: string;
+    tier: string;
+    subscriptionId: string;
+}
+/** Something is wrong with the event itself. Retrying will not fix it. */
+ | {
+    status: "rejected";
+    reason: string;
+}
+/** A transient failure. The caller returns 5xx so Stripe retries. */
+ | {
+    status: "failed";
+    reason: string;
+};
+export interface HandleWebhookDeps {
+    event: Stripe.Event;
+    config: StripeConfig;
+    tierStore: TierStore;
+    /** Reads the current subscription. Injected so tests need no network. */
+    retrieveSubscription: (id: string) => Promise<Stripe.Subscription>;
+}
+export declare function handleStripeWebhookEvent(deps: HandleWebhookDeps): Promise<WebhookOutcome>;
+//# sourceMappingURL=webhook.d.ts.map

package/dist/billing/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../src/billing/webhook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,cAAc;AACxB,0EAA0E;AACxE;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACvC,0BAA0B;GACxB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE;AAC9E,0EAA0E;GACxE;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACxC,qEAAqE;GACnE;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC;IACpB,MAAM,EAAE,YAAY,CAAC;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,yEAAyE;IACzE,oBAAoB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;CACpE;AAED,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAyC/F"}

package/dist/billing/webhook.js

@@ -0,0 +1,69 @@
+/**
+ * Stripe webhook handling (GH #1059).
+ *
+ * This is where money becomes a tier. Stripe delivers an event, and
+ * `tierStore.set()` is called for the subject that paid.
+ *
+ * ## Why this reads the subscription back instead of trusting the event
+ *
+ * Stripe retries a webhook until it gets a 2xx, and it does not promise
+ * delivery order. The usual fix is a table of processed event ids plus a
+ * version comparison, so a replayed or late event cannot undo a newer one.
+ *
+ * This takes a different route. On any handled event it reads the
+ * **current** subscription from Stripe and writes the tier that matches it.
+ * The consequences:
+ *
+ * - A duplicate delivery writes the same value twice. Idempotent by
+ *   construction, with no event-id bookkeeping.
+ * - A late `subscription.deleted` that arrives after a newer
+ *   `subscription.updated` reads a live subscription and writes the paid tier.
+ *   It cannot strand a paying customer on `free`, which is the failure the
+ *   ordering guard exists to prevent.
+ * - No table, so no migration. That matters here specifically: production runs
+ *   migrations only inside the manual `Deploy Production` dispatch while
+ *   Railway deploys code on every push to `main`, so a table and its writer in
+ *   one change would work on staging and fail on production.
+ *
+ * The cost is one extra Stripe API call per event. At the volume a $9 to $39
+ * product generates that is not a consideration.
+ */
+import { isHandledWebhookEvent, subjectForSubscription, subscriptionIdForEvent, tierForSubscription, } from "./stripe.js";
+export async function handleStripeWebhookEvent(deps) {
+    const { event, config, tierStore, retrieveSubscription } = deps;
+    if (!isHandledWebhookEvent(event.type)) {
+        return { status: "ignored", reason: `unhandled event type ${event.type}` };
+    }
+    const subscriptionId = subscriptionIdForEvent(event);
+    if (!subscriptionId) {
+        // A one-off Checkout Session has no subscription. Brains sells nothing
+        // one-off today, so this is noise rather than an error.
+        return { status: "ignored", reason: `event ${event.id} names no subscription` };
+    }
+    let subscription;
+    try {
+        subscription = await retrieveSubscription(subscriptionId);
+    }
+    catch (err) {
+        // Could be Stripe being briefly unavailable. Ask for a retry.
+        return {
+            status: "failed",
+            reason: `could not read subscription ${subscriptionId}: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    const subject = subjectForSubscription(subscription);
+    if (!subject) {
+        // Every subscription Brains creates carries brains_subject. One without it
+        // was made by hand in the dashboard, and guessing an owner would be worse
+        // than refusing. Retrying cannot add the metadata, so this is rejected and
+        // not failed.
+        return { status: "rejected", reason: `subscription ${subscriptionId} carries no brains_subject` };
+    }
+    const tier = tierForSubscription(subscription, config.prices);
+    const written = await tierStore.set(subject, tier, "stripe-webhook");
+    if (!written) {
+        return { status: "failed", reason: `tierStore.set failed for ${subject}` };
+    }
+    return { status: "applied", subject, tier, subscriptionId };
+}
+//# sourceMappingURL=webhook.js.map

package/dist/billing/webhook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.js","sourceRoot":"","sources":["../../src/billing/webhook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,GAEpB,MAAM,aAAa,CAAC;AAoBrB,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,IAAuB;IACpE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,IAAI,CAAC;IAEhE,IAAI,CAAC,qBAAqB,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,wBAAwB,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;IAC7E,CAAC;IAED,MAAM,cAAc,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC;IACrD,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,uEAAuE;QACvE,wDAAwD;QACxD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,KAAK,CAAC,EAAE,wBAAwB,EAAE,CAAC;IAClF,CAAC;IAED,IAAI,YAAiC,CAAC;IACtC,IAAI,CAAC;QACH,YAAY,GAAG,MAAM,oBAAoB,CAAC,cAAc,CAAC,CAAC;IAC5D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,8DAA8D;QAC9D,OAAO;YACL,MAAM,EAAE,QAAQ;YAChB,MAAM,EAAE,+BAA+B,cAAc,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;SAC7G,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,sBAAsB,CAAC,YAAY,CAAC,CAAC;IACrD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,2EAA2E;QAC3E,0EAA0E;QAC1E,2EAA2E;QAC3E,cAAc;QACd,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,cAAc,4BAA4B,EAAE,CAAC;IACpG,CAAC;IAED,MAAM,IAAI,GAAG,mBAAmB,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,gBAAgB,CAAC,CAAC;IACrE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,4BAA4B,OAAO,EAAE,EAAE,CAAC;IAC7E,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;AAC9D,CAAC"}

package/dist/httpServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"httpServer.d.ts","sourceRoot":"","sources":["../src/httpServer.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAQxB,OAAO,EAAsD,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAuH7G,wBAAgB,8BAA8B,IAAI,IAAI,CAErD;AA+8BD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAI9D;AAgsBD,wBAAsB,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAusF9F"}
+{"version":3,"file":"httpServer.d.ts","sourceRoot":"","sources":["../src/httpServer.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAQxB,OAAO,EAAsD,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AA2H7G,wBAAgB,8BAA8B,IAAI,IAAI,CAErD;AAi9BD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAI9D;AAgsBD,wBAAsB,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CA20F9F"}

package/dist/httpServer.js

@@ -44,6 +44,10 @@ import { getDigestPreference, upsertDigestPreference, updateDigestEnabled, } fro
 import { DEFAULT_ACCESS_CONTEXT, getUserAccessLevel, isHiveModeEnabled, } from "./governance/accessControl.js";
 import { seedUsers, purgeSeedUsers, isSeedEnabled, isGodModeSubject } from "./admin/seedUsers.js";
 import { deleteAccount } from "./auth/deleteAccount.js";
+import { createCheckoutSession, isPaidTier, resolveStripeConfig } from "./billing/stripe.js";
+import Stripe from "stripe";
+import { handleStripeWebhookEvent } from "./billing/webhook.js";
+import { getTierStore } from "./billing/tierStore.js";
 const MAX_BODY_BYTES = 1024 * 1024;
 // GH #898: single declared cap shared by both import-zip routes — the raw
 // multipart upload and the JSON route's zipData/zipPath body — so the two
@@ -198,6 +202,8 @@ function classifyRouteForRateLimit(method, pathname) {
     }
     if (method === "POST" && (pathname === "/api/v1/pages/batch" || pathname === "/api/v1/import" || pathname === "/api/v1/links/extract" || pathname === "/api/v1/links/suggest" || pathname === "/api/v1/pages/delete-batch"))
         return "batch";
+    if (method === "POST" && pathname === "/api/v1/billing/webhook")
+        return null;
     if (method === "POST" && pathname === "/chat")
         return "chat";
     if (method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE")
@@ -349,6 +355,7 @@ function isPublicRoute(method, pathname) {
         (method === "GET" && pathname === "/chat-ui") ||
         (method === "GET" && pathname === "/connect") ||
         (method === "POST" && pathname === "/api/inbound-email") ||
+        (method === "POST" && pathname === "/api/v1/billing/webhook") ||
         (method === "GET" && pathname.startsWith("/assets/css/")) ||
         (method === "GET" && pathname.startsWith("/assets/img/")) ||
         (method === "GET" && pathname === "/openapi.json") ||
@@ -2744,6 +2751,128 @@ export async function startHttpServer(drive, port) {
                 json(req, res, 200, { ok: true, tier, pageCount: currentCount, pageLimit: limit });
                 return;
             }
+            if (method === "POST" && pathname === "/api/v1/billing/webhook") {
+                const stripeConfig = resolveStripeConfig();
+                const webhookSecret = (process.env.STRIPE_WEBHOOK_SECRET ?? "").trim();
+                if (!stripeConfig.ok || !webhookSecret) {
+                    const missing = [...(stripeConfig.ok ? [] : stripeConfig.missing), ...(webhookSecret ? [] : ["STRIPE_WEBHOOK_SECRET"])];
+                    console.error("[billing] webhook unavailable, missing:", missing.join(", "));
+                    // 503 and not 500. Stripe retries a 5xx, which is right: the operator
+                    // may be mid-deploy, and the event should not be lost.
+                    json(req, res, 503, { ok: false, error: "Billing is not configured on this server" });
+                    return;
+                }
+                // Signature verification runs over the exact bytes Stripe sent. Parsing
+                // and re-serialising changes them and the signature stops matching.
+                const rawBody = await readBodyBuffer(req, 1_000_000, "billing/webhook").catch(() => null);
+                const signature = req.headers["stripe-signature"];
+                if (!rawBody || typeof signature !== "string") {
+                    json(req, res, 400, { ok: false, error: "Missing body or stripe-signature header" });
+                    return;
+                }
+                const stripeClient = new Stripe(stripeConfig.config.secretKey);
+                let event;
+                try {
+                    event = stripeClient.webhooks.constructEvent(rawBody, signature, webhookSecret);
+                }
+                catch (err) {
+                    // An unverified payload is not from Stripe, or the secret is wrong.
+                    // Either way a retry changes nothing, so this is 400 and not 5xx.
+                    console.error("[billing] webhook signature rejected:", err instanceof Error ? err.message : err);
+                    json(req, res, 400, { ok: false, error: "Signature verification failed" });
+                    return;
+                }
+                const outcome = await handleStripeWebhookEvent({
+                    event,
+                    config: stripeConfig.config,
+                    tierStore: getTierStore(),
+                    retrieveSubscription: (id) => stripeClient.subscriptions.retrieve(id),
+                }).catch((err) => ({
+                    status: "failed",
+                    reason: err instanceof Error ? err.message : String(err),
+                }));
+                switch (outcome.status) {
+                    case "applied":
+                        console.log(`[billing] ${event.type} set tier ${outcome.tier} for ${outcome.subject}`);
+                        json(req, res, 200, { ok: true, applied: true });
+                        return;
+                    case "ignored":
+                        json(req, res, 200, { ok: true, applied: false });
+                        return;
+                    case "rejected":
+                        // 200 on purpose. The event is wrong in a way no retry can fix, and
+                        // a 4xx here only makes Stripe redeliver it for days.
+                        console.error(`[billing] webhook rejected: ${outcome.reason}`);
+                        json(req, res, 200, { ok: true, applied: false });
+                        return;
+                    case "failed":
+                        console.error(`[billing] webhook failed, asking Stripe to retry: ${outcome.reason}`);
+                        json(req, res, 500, { ok: false, error: "Could not apply the event" });
+                        return;
+                }
+            }
+            if (method === "POST" && pathname === "/api/v1/billing/checkout") {
+                // Checkout must be tied to a person, because the webhook writes a tier
+                // against this subject. An api-key or connector-key caller is a shared
+                // machine credential with no user behind it, and a PAT belongs to an
+                // agent rather than to a browser that can follow a redirect.
+                if (authorization.mode !== "supabase" && authorization.mode !== "oauth") {
+                    json(req, res, 403, {
+                        ok: false,
+                        error: "Checkout requires a user session (Supabase or OAuth auth)",
+                    });
+                    return;
+                }
+                const stripeConfig = resolveStripeConfig();
+                if (!stripeConfig.ok) {
+                    // Name the variables. A self-hosted or local instance reaching this
+                    // line has simply not set up billing, and a bare 500 sends the
+                    // operator reading source code.
+                    console.error("[billing] checkout unavailable, missing:", stripeConfig.missing.join(", "));
+                    json(req, res, 503, {
+                        ok: false,
+                        error: "Billing is not configured on this server",
+                        missing: stripeConfig.missing,
+                    });
+                    return;
+                }
+                const web = webUrl();
+                if (!web) {
+                    console.error("[billing] checkout unavailable, missing: WEB_URL");
+                    json(req, res, 503, {
+                        ok: false,
+                        error: "Billing is not configured on this server",
+                        missing: ["WEB_URL"],
+                    });
+                    return;
+                }
+                const payload = (await readJsonBody(req, 4096, "billing/checkout").catch(() => null));
+                const tier = payload?.tier;
+                if (!isPaidTier(tier)) {
+                    json(req, res, 400, {
+                        ok: false,
+                        error: "Unknown tier",
+                        detail: "tier must be one of: solo, pro, unlimited",
+                    });
+                    return;
+                }
+                try {
+                    const session = await createCheckoutSession({
+                        tier,
+                        subject: authorization.subject,
+                        config: stripeConfig.config,
+                        webUrl: web,
+                    });
+                    json(req, res, 200, { ok: true, url: session.url, sessionId: session.id });
+                }
+                catch (err) {
+                    // Never echo the Stripe error to the browser. It can carry account
+                    // detail, and the customer cannot act on it either way.
+                    console.error("[billing] checkout session failed:", err instanceof Error ? err.message : err);
+                    json(req, res, 502, { ok: false, error: "Could not start checkout. Try again shortly." });
+                }
+                return;
+            }
             if (method === "DELETE" && pathname === "/api/v1/account") {
                 if (authorization.mode !== "supabase" && authorization.mode !== "oauth") {
                     json(req, res, 403, { ok: false, error: "Account deletion requires a user session (Supabase or OAuth auth)" });