mcpmake 0.1.0

package/dist/cloud/shared-state.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared singletons used by both the API server and the web router.
+ * Extracted to break circular dependencies between server.ts and router.ts.
+ *
+ * Environment variables:
+ *   DATABASE_URL            — PostgreSQL connection string (optional; in-memory when unset)
+ *   ENCRYPTION_KEY          — Master key for secret encryption (>=32 chars in production)
+ *   ADMIN_EMAIL             — Email address auto-promoted to admin on registration
+ *   ADMIN_TOKEN             — Bearer token for API-level admin endpoints
+ *   IDLE_THRESHOLD_MS       — Idle timeout before containers are stopped (default: 3600000)
+ *   TRUST_PROXY             — Set to "true" to trust X-Forwarded-* headers
+ *   STRIPE_SECRET_KEY       — Stripe secret API key (optional; billing disabled when unset)
+ *   STRIPE_WEBHOOK_SECRET   — Stripe webhook signing secret for signature verification
+ *   STRIPE_PRICE_HOBBYIST   — Stripe Price ID for the Hobbyist plan ($9/mo)
+ *   STRIPE_PRICE_PRO        — Stripe Price ID for the Pro plan ($29/mo)
+ *   STRIPE_PRICE_TEAM       — Stripe Price ID for the Team plan ($99/mo)
+ */
+import { ServerStore, PortAllocator } from './store.js';
+import { MetricsStore } from './metrics.js';
+import { RateLimiter } from './rate-limiter.js';
+import { UsageTracker } from './billing/usage-tracker.js';
+import { type UsageStore } from './billing/usage-store.js';
+import { type CreditStore } from './billing/credit-store.js';
+import { FailureTracker } from './failure-tracker.js';
+import { type MetricSampleStore } from './metric-samples.js';
+import { type TelemetryStore } from './telemetry-store.js';
+import { SecretStore } from './secret-store.js';
+import type { Database } from './db/index.js';
+import type { PgServerStore } from './db/pg-store.js';
+import type { PgUserStore, PgSessionStore } from './db/pg-store.js';
+export declare const MAX_SPEC_SIZE: number;
+export declare const MAX_NAME_LENGTH = 100;
+export declare const UPLOAD_DIR = "/tmp/mcpmake-uploads";
+export declare const store: ServerStore;
+export declare const ports: PortAllocator;
+export declare const uploadLimiter: RateLimiter;
+export declare const loginLimiter: RateLimiter;
+export declare const resetLimiter: RateLimiter;
+export declare const telemetryLimiter: RateLimiter;
+export declare const metrics: MetricsStore;
+export declare const usageTracker: UsageTracker;
+/** Rolling per-minute API failure-rate counter (in-memory, bounded). */
+export declare const failureTracker: FailureTracker;
+/** Returns the active Database instance, or null when running in-memory. */
+export declare function getDb(): Database | null;
+/** Returns the Pg-backed server store, or null when running in-memory. */
+export declare function getPgServerStore(): PgServerStore | null;
+/** Returns the Pg-backed user store, or null when running in-memory. */
+export declare function getPgUserStore(): PgUserStore | null;
+/** Returns the Pg-backed session store, or null when running in-memory. */
+export declare function getPgSessionStore(): PgSessionStore | null;
+/** Returns the active usage store (Pg-backed when a database is configured). */
+export declare function getUsageStore(): UsageStore;
+/** Returns the active credit store (Pg-backed when a database is configured). */
+export declare function getCreditStore(): CreditStore;
+/** Returns the active metric-sample store (Pg-backed when a database is configured). */
+export declare function getMetricSampleStore(): MetricSampleStore;
+/** Returns the active telemetry store (Pg-backed when a database is configured). */
+export declare function getTelemetryStore(): TelemetryStore;
+/** Returns the secret store. Lazily initialised on first access. */
+export declare function getSecretStore(): SecretStore;
+/**
+ * Initialise stores from environment.
+ *
+ * When `DATABASE_URL` is set, creates PostgreSQL-backed stores and runs
+ * pending migrations. The Pg stores are exposed via getter functions above
+ * so that callers can be migrated incrementally.
+ *
+ * The original in-memory `store`, `userStore`, and `sessionStore` remain
+ * available for code that hasn't been ported to async yet.
+ */
+export declare function initStores(): Promise<void>;

package/dist/cloud/shared-state.js

@@ -0,0 +1,159 @@
+/**
+ * Shared singletons used by both the API server and the web router.
+ * Extracted to break circular dependencies between server.ts and router.ts.
+ *
+ * Environment variables:
+ *   DATABASE_URL            — PostgreSQL connection string (optional; in-memory when unset)
+ *   ENCRYPTION_KEY          — Master key for secret encryption (>=32 chars in production)
+ *   ADMIN_EMAIL             — Email address auto-promoted to admin on registration
+ *   ADMIN_TOKEN             — Bearer token for API-level admin endpoints
+ *   IDLE_THRESHOLD_MS       — Idle timeout before containers are stopped (default: 3600000)
+ *   TRUST_PROXY             — Set to "true" to trust X-Forwarded-* headers
+ *   STRIPE_SECRET_KEY       — Stripe secret API key (optional; billing disabled when unset)
+ *   STRIPE_WEBHOOK_SECRET   — Stripe webhook signing secret for signature verification
+ *   STRIPE_PRICE_HOBBYIST   — Stripe Price ID for the Hobbyist plan ($9/mo)
+ *   STRIPE_PRICE_PRO        — Stripe Price ID for the Pro plan ($29/mo)
+ *   STRIPE_PRICE_TEAM       — Stripe Price ID for the Team plan ($99/mo)
+ */
+import os from 'node:os';
+import { ServerStore, PortAllocator } from './store.js';
+import { MetricsStore } from './metrics.js';
+import { RateLimiter } from './rate-limiter.js';
+import { UsageTracker } from './billing/usage-tracker.js';
+import { InMemoryUsageStore } from './billing/usage-store.js';
+import { InMemoryCreditStore } from './billing/credit-store.js';
+import { FailureTracker } from './failure-tracker.js';
+import { InMemoryMetricSampleStore } from './metric-samples.js';
+import { InMemoryTelemetryStore } from './telemetry-store.js';
+import { SecretStore } from './secret-store.js';
+import { logger } from '../utils/logger.js';
+export const MAX_SPEC_SIZE = 5 * 1024 * 1024; // 5 MB
+export const MAX_NAME_LENGTH = 100;
+export const UPLOAD_DIR = '/tmp/mcpmake-uploads';
+export const store = new ServerStore();
+export const ports = new PortAllocator();
+export const uploadLimiter = new RateLimiter({ maxRequests: 10, windowMs: 86_400_000 }); // 10/day
+export const loginLimiter = new RateLimiter({ maxRequests: 10, windowMs: 3_600_000 }); // 10/hour per key
+export const resetLimiter = new RateLimiter({ maxRequests: 3, windowMs: 3_600_000 }); // 3/hour per key
+// Per-IP flood cap for the unauthenticated telemetry endpoint. NOTE: behind a
+// reverse proxy without TRUST_PROXY=true every request appears to come from
+// 127.0.0.1, so this degrades to a single global bucket (a coarse but still
+// useful flood cap). Same limitation as uploadLimiter/loginLimiter.
+export const telemetryLimiter = new RateLimiter({ maxRequests: 20, windowMs: 3_600_000 }); // 20/hour per key
+export const metrics = new MetricsStore();
+export const usageTracker = new UsageTracker();
+/** Rolling per-minute API failure-rate counter (in-memory, bounded). */
+export const failureTracker = new FailureTracker();
+// ---------------------------------------------------------------------------
+// PostgreSQL-backed stores (populated by initStores when DATABASE_URL is set)
+// ---------------------------------------------------------------------------
+let _db = null;
+let _pgServerStore = null;
+let _pgUserStore = null;
+let _pgSessionStore = null;
+let _secretStore = null;
+let _usageStore = new InMemoryUsageStore();
+let _creditStore = new InMemoryCreditStore();
+let _metricSampleStore = new InMemoryMetricSampleStore();
+let _telemetryStore = new InMemoryTelemetryStore();
+/** Returns the active Database instance, or null when running in-memory. */
+export function getDb() {
+    return _db;
+}
+/** Returns the Pg-backed server store, or null when running in-memory. */
+export function getPgServerStore() {
+    return _pgServerStore;
+}
+/** Returns the Pg-backed user store, or null when running in-memory. */
+export function getPgUserStore() {
+    return _pgUserStore;
+}
+/** Returns the Pg-backed session store, or null when running in-memory. */
+export function getPgSessionStore() {
+    return _pgSessionStore;
+}
+/** Returns the active usage store (Pg-backed when a database is configured). */
+export function getUsageStore() {
+    return _usageStore;
+}
+/** Returns the active credit store (Pg-backed when a database is configured). */
+export function getCreditStore() {
+    return _creditStore;
+}
+/** Returns the active metric-sample store (Pg-backed when a database is configured). */
+export function getMetricSampleStore() {
+    return _metricSampleStore;
+}
+/** Returns the active telemetry store (Pg-backed when a database is configured). */
+export function getTelemetryStore() {
+    return _telemetryStore;
+}
+/** Returns the secret store. Lazily initialised on first access. */
+export function getSecretStore() {
+    if (!_secretStore) {
+        _secretStore = createSecretStore();
+    }
+    return _secretStore;
+}
+/**
+ * Create a SecretStore from the ENCRYPTION_KEY env var.
+ * Falls back to a machine-specific derived key in development.
+ */
+function createSecretStore(db) {
+    let masterKey = process.env.ENCRYPTION_KEY;
+    if (!masterKey || masterKey.length < 32) {
+        if (process.env.NODE_ENV === 'production' || process.env.DOMAIN) {
+            throw new Error('ENCRYPTION_KEY must be set to at least 32 characters in production');
+        }
+        const devKey = `dev-insecure-${os.hostname()}`;
+        logger.warn('ENCRYPTION_KEY is not set or is shorter than 32 characters. ' +
+            'Using a derived dev key — NOT suitable for production.');
+        masterKey = devKey;
+    }
+    return new SecretStore(masterKey, db);
+}
+/**
+ * Initialise stores from environment.
+ *
+ * When `DATABASE_URL` is set, creates PostgreSQL-backed stores and runs
+ * pending migrations. The Pg stores are exposed via getter functions above
+ * so that callers can be migrated incrementally.
+ *
+ * The original in-memory `store`, `userStore`, and `sessionStore` remain
+ * available for code that hasn't been ported to async yet.
+ */
+export async function initStores() {
+    const databaseUrl = process.env.DATABASE_URL;
+    if (!databaseUrl)
+        return;
+    try {
+        const { createDatabase } = await import('./db/index.js');
+        const { runMigrations } = await import('./db/migrations.js');
+        const { PgServerStore: PgSS, PgUserStore: PgUS, PgSessionStore: PgSesS, } = await import('./db/pg-store.js');
+        const db = await createDatabase(databaseUrl);
+        await runMigrations(db);
+        _db = db;
+        _pgServerStore = new PgSS(db);
+        _pgUserStore = new PgUS(db);
+        _pgSessionStore = new PgSesS(db);
+        const { PgUsageStore } = await import('./billing/usage-store.js');
+        _usageStore = new PgUsageStore(db);
+        const { PgCreditStore } = await import('./billing/credit-store.js');
+        _creditStore = new PgCreditStore(db);
+        const { PgMetricSampleStore } = await import('./metric-samples.js');
+        _metricSampleStore = new PgMetricSampleStore(db);
+        const { PgTelemetryStore } = await import('./telemetry-store.js');
+        _telemetryStore = new PgTelemetryStore(db);
+        // Wire the secret store to the database
+        if (_secretStore) {
+            _secretStore.setDatabase(db);
+        }
+        else {
+            _secretStore = createSecretStore(db);
+        }
+        logger.info('PostgreSQL stores initialized');
+    }
+    catch (err) {
+        logger.warn(`PostgreSQL initialization failed, using in-memory stores: ${err instanceof Error ? err.message : err}`);
+    }
+}

package/dist/cloud/ssrf.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SSRF protection for user-supplied URLs.
+ *
+ * Before the backend fetches a spec URL or crawls a website on behalf of a
+ * user, we must ensure the target is a genuinely public host. Otherwise an
+ * attacker could point us at internal services, the cloud metadata endpoint
+ * (169.254.169.254), or other private infrastructure.
+ *
+ * Guards:
+ *   - protocol must be http/https
+ *   - the hostname's resolved IP(s) must all be public (no loopback,
+ *     private, link-local, CGNAT, unique-local, etc.)
+ *   - redirects are followed manually and each hop is re-validated
+ */
+export declare class SsrfError extends Error {
+    constructor(message: string);
+}
+/**
+ * Return true if an IP address string falls in a blocked (non-public) range.
+ */
+export declare function isBlockedIp(ip: string): boolean;
+/**
+ * Validate that a URL targets a public host. Resolves DNS and checks every
+ * returned address. Throws {@link SsrfError} on any violation.
+ *
+ * @returns the resolved public IP and address family for connection pinning.
+ */
+export declare function assertPublicUrl(rawUrl: string): Promise<{
+    url: URL;
+    address: string;
+    family: number;
+}>;
+/**
+ * Fetch a URL with SSRF protection, following up to `maxRedirects` redirects
+ * and re-validating each hop. Returns the final Response.
+ *
+ * Note: Node's global fetch resolves DNS itself, so there is a small TOCTOU
+ * gap between our lookup and the connect. The network-level egress allowlist
+ * (see deploy/harden-egress.sh) is the backstop for that residual risk.
+ */
+export declare function safeFetch(rawUrl: string, init?: RequestInit & {
+    timeoutMs?: number;
+}, maxRedirects?: number): Promise<Response>;

package/dist/cloud/ssrf.js

@@ -0,0 +1,150 @@
+/**
+ * SSRF protection for user-supplied URLs.
+ *
+ * Before the backend fetches a spec URL or crawls a website on behalf of a
+ * user, we must ensure the target is a genuinely public host. Otherwise an
+ * attacker could point us at internal services, the cloud metadata endpoint
+ * (169.254.169.254), or other private infrastructure.
+ *
+ * Guards:
+ *   - protocol must be http/https
+ *   - the hostname's resolved IP(s) must all be public (no loopback,
+ *     private, link-local, CGNAT, unique-local, etc.)
+ *   - redirects are followed manually and each hop is re-validated
+ */
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+export class SsrfError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SsrfError';
+    }
+}
+/**
+ * Return true if an IP address string falls in a blocked (non-public) range.
+ */
+export function isBlockedIp(ip) {
+    const family = isIP(ip);
+    if (family === 4)
+        return isBlockedIpv4(ip);
+    if (family === 6)
+        return isBlockedIpv6(ip);
+    return true; // not a valid IP — refuse
+}
+function isBlockedIpv4(ip) {
+    const parts = ip.split('.').map((p) => parseInt(p, 10));
+    if (parts.length !== 4 || parts.some((p) => Number.isNaN(p) || p < 0 || p > 255))
+        return true;
+    const [a, b] = parts;
+    if (a === 0)
+        return true; // 0.0.0.0/8 "this host"
+    if (a === 10)
+        return true; // 10.0.0.0/8 private
+    if (a === 127)
+        return true; // 127.0.0.0/8 loopback
+    if (a === 169 && b === 254)
+        return true; // 169.254.0.0/16 link-local incl. cloud metadata
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // 172.16.0.0/12 private
+    if (a === 192 && b === 168)
+        return true; // 192.168.0.0/16 private
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // 100.64.0.0/10 CGNAT
+    if (a === 192 && b === 0)
+        return true; // 192.0.0.0/24 + 192.0.2.0/24 special-use
+    if (a === 198 && (b === 18 || b === 19))
+        return true; // 198.18.0.0/15 benchmarking
+    if (a >= 224)
+        return true; // 224.0.0.0/4 multicast + 240.0.0.0/4 reserved
+    return false;
+}
+function isBlockedIpv6(ip) {
+    const lower = ip.toLowerCase();
+    // IPv4-mapped (::ffff:a.b.c.d) — validate the embedded IPv4
+    const mapped = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    if (mapped)
+        return isBlockedIpv4(mapped[1]);
+    if (lower === '::1' || lower === '::')
+        return true; // loopback / unspecified
+    if (lower.startsWith('fe80'))
+        return true; // link-local
+    if (lower.startsWith('fc') || lower.startsWith('fd'))
+        return true; // fc00::/7 unique-local
+    if (lower.startsWith('ff'))
+        return true; // multicast
+    if (lower.startsWith('::ffff:'))
+        return true; // other v4-mapped forms — refuse
+    if (lower.startsWith('2001:db8'))
+        return true; // documentation
+    return false;
+}
+/**
+ * Validate that a URL targets a public host. Resolves DNS and checks every
+ * returned address. Throws {@link SsrfError} on any violation.
+ *
+ * @returns the resolved public IP and address family for connection pinning.
+ */
+export async function assertPublicUrl(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new SsrfError('Invalid URL');
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new SsrfError(`Unsupported protocol: ${url.protocol}`);
+    }
+    const hostname = url.hostname.replace(/^\[|\]$/g, ''); // strip IPv6 brackets
+    // Literal IP — check directly.
+    if (isIP(hostname)) {
+        if (isBlockedIp(hostname)) {
+            throw new SsrfError(`Blocked non-public address: ${hostname}`);
+        }
+        return { url, address: hostname, family: isIP(hostname) };
+    }
+    // Hostname — resolve ALL addresses and ensure every one is public.
+    let addresses;
+    try {
+        addresses = await lookup(hostname, { all: true });
+    }
+    catch {
+        throw new SsrfError(`Could not resolve host: ${hostname}`);
+    }
+    if (addresses.length === 0) {
+        throw new SsrfError(`Host did not resolve: ${hostname}`);
+    }
+    for (const addr of addresses) {
+        if (isBlockedIp(addr.address)) {
+            throw new SsrfError(`Host ${hostname} resolves to a blocked address: ${addr.address}`);
+        }
+    }
+    return { url, address: addresses[0].address, family: addresses[0].family };
+}
+/**
+ * Fetch a URL with SSRF protection, following up to `maxRedirects` redirects
+ * and re-validating each hop. Returns the final Response.
+ *
+ * Note: Node's global fetch resolves DNS itself, so there is a small TOCTOU
+ * gap between our lookup and the connect. The network-level egress allowlist
+ * (see deploy/harden-egress.sh) is the backstop for that residual risk.
+ */
+export async function safeFetch(rawUrl, init = {}, maxRedirects = 5) {
+    const { timeoutMs = 15_000, ...rest } = init;
+    let current = rawUrl;
+    for (let hop = 0; hop <= maxRedirects; hop++) {
+        await assertPublicUrl(current);
+        const res = await fetch(current, {
+            ...rest,
+            redirect: 'manual',
+            signal: rest.signal ?? AbortSignal.timeout(timeoutMs),
+        });
+        if (res.status >= 300 && res.status < 400 && res.headers.has('location')) {
+            const location = res.headers.get('location');
+            current = new URL(location, current).toString();
+            continue;
+        }
+        return res;
+    }
+    throw new SsrfError(`Too many redirects (>${maxRedirects})`);
+}

package/dist/cloud/store.d.ts

@@ -0,0 +1,41 @@
+/**
+ * In-memory server metadata store (MVP).
+ * Will be replaced with Postgres in a later phase.
+ */
+export interface ServerRecord {
+    slug: string;
+    userId?: string;
+    specHash: string;
+    containerId: string;
+    port: number;
+    bearerToken: string;
+    status: 'building' | 'running' | 'stopped' | 'error';
+    toolCount: number;
+    /** Type of MCP server: 'http' for API proxies, 'playwright' for website scrapers. Defaults to 'http'. */
+    serverType?: 'http' | 'playwright';
+    createdAt: string;
+    lastActiveAt: string;
+}
+export declare class ServerStore {
+    private servers;
+    create(record: ServerRecord): void;
+    get(slug: string): ServerRecord | undefined;
+    list(): ServerRecord[];
+    update(slug: string, updates: Partial<ServerRecord>): void;
+    delete(slug: string): void;
+    findByPort(port: number): ServerRecord | undefined;
+}
+/**
+ * Port allocator for assigning host ports to containers.
+ * Allocates from a configurable range (default 4000-4999).
+ */
+export declare class PortAllocator {
+    private readonly minPort;
+    private readonly maxPort;
+    private allocated;
+    private nextCandidate;
+    constructor(minPort?: number, maxPort?: number);
+    allocate(): number;
+    release(port: number): void;
+    get allocatedCount(): number;
+}

package/dist/cloud/store.js

@@ -0,0 +1,75 @@
+/**
+ * In-memory server metadata store (MVP).
+ * Will be replaced with Postgres in a later phase.
+ */
+export class ServerStore {
+    servers = new Map();
+    create(record) {
+        if (this.servers.has(record.slug)) {
+            throw new Error(`Server with slug "${record.slug}" already exists`);
+        }
+        // Default serverType to 'http' for backwards compatibility
+        this.servers.set(record.slug, { serverType: 'http', ...record });
+    }
+    get(slug) {
+        const record = this.servers.get(slug);
+        return record ? { ...record } : undefined;
+    }
+    list() {
+        return [...this.servers.values()].map((r) => ({ ...r }));
+    }
+    update(slug, updates) {
+        const existing = this.servers.get(slug);
+        if (!existing) {
+            throw new Error(`Server with slug "${slug}" not found`);
+        }
+        // Prevent changing the slug via update
+        const { slug: _ignored, ...safeUpdates } = updates;
+        this.servers.set(slug, { ...existing, ...safeUpdates });
+    }
+    delete(slug) {
+        this.servers.delete(slug);
+    }
+    findByPort(port) {
+        for (const record of this.servers.values()) {
+            if (record.port === port) {
+                return { ...record };
+            }
+        }
+        return undefined;
+    }
+}
+/**
+ * Port allocator for assigning host ports to containers.
+ * Allocates from a configurable range (default 4000-4999).
+ */
+export class PortAllocator {
+    minPort;
+    maxPort;
+    allocated = new Set();
+    nextCandidate;
+    constructor(minPort = 4000, maxPort = 4999) {
+        this.minPort = minPort;
+        this.maxPort = maxPort;
+        this.nextCandidate = minPort;
+    }
+    allocate() {
+        const range = this.maxPort - this.minPort + 1;
+        // Try sequential allocation first for simplicity
+        for (let attempts = 0; attempts < range; attempts++) {
+            const port = this.nextCandidate;
+            this.nextCandidate = this.minPort + ((this.nextCandidate - this.minPort + 1) % range);
+            if (!this.allocated.has(port)) {
+                this.allocated.add(port);
+                return port;
+            }
+        }
+        throw new Error(`No available ports in range ${this.minPort}-${this.maxPort} (${this.allocated.size} allocated)`);
+    }
+    release(port) {
+        this.allocated.delete(port);
+    }
+    get allocatedCount() {
+        return this.allocated.size;
+    }
+}

package/dist/cloud/stripe.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Stripe payment integration.
+ *
+ * Optional module — if STRIPE_SECRET_KEY is not set, all functions return
+ * null or throw descriptive errors. Uses dynamic import for the `stripe`
+ * package to avoid a hard dependency (same pattern as `pg`).
+ *
+ * Environment variables:
+ *   STRIPE_SECRET_KEY      — Stripe secret API key
+ *   STRIPE_WEBHOOK_SECRET  — Webhook endpoint signing secret
+ *   STRIPE_PRICE_HOBBYIST  — Price ID for the Hobbyist plan
+ *   STRIPE_PRICE_PRO       — Price ID for the Pro plan
+ *   STRIPE_PRICE_TEAM      — Price ID for the Team plan
+ */
+/** Minimal subset of the Stripe SDK we actually use. */
+interface StripeClient {
+    checkout: {
+        sessions: {
+            create(params: Record<string, unknown>): Promise<{
+                url: string | null;
+            }>;
+        };
+    };
+    billingPortal: {
+        sessions: {
+            create(params: Record<string, unknown>): Promise<{
+                url: string;
+            }>;
+        };
+    };
+    webhooks: {
+        constructEvent(payload: Buffer | string, sig: string, secret: string): unknown;
+    };
+}
+export declare const PLAN_PRICE_IDS: Record<string, string>;
+/**
+ * Get a configured Stripe client. Returns `null` when STRIPE_SECRET_KEY
+ * is not set. Caches the instance after first successful creation.
+ */
+export declare function getStripeClient(): Promise<StripeClient | null>;
+/**
+ * Returns true when Stripe is configured (secret key is present).
+ * Does NOT load the Stripe SDK — just checks the env var.
+ */
+export declare function isStripeConfigured(): boolean;
+/**
+ * Create a Stripe Checkout session for a plan upgrade.
+ *
+ * @returns The checkout session URL to redirect the user to.
+ * @throws If Stripe is not configured or the plan has no price ID.
+ */
+export declare function createCheckoutSession(opts: {
+    userId: string;
+    email: string;
+    plan: string;
+    successUrl: string;
+    cancelUrl: string;
+}): Promise<string>;
+/**
+ * Create a Stripe billing portal session so the customer can manage
+ * their subscription (cancel, change payment method, view invoices).
+ *
+ * @returns The portal session URL to redirect the user to.
+ */
+export declare function createPortalSession(customerId: string, returnUrl: string): Promise<string>;
+/**
+ * Verify and handle an incoming Stripe webhook event.
+ *
+ * Handles:
+ *   - checkout.session.completed  — activate subscription, store customer ID
+ *   - customer.subscription.updated — plan change / renewal
+ *   - customer.subscription.deleted — cancellation, downgrade to free
+ *
+ * @param payload   - The raw request body as a Buffer (required for signature verification)
+ * @param signature - The `stripe-signature` header value
+ */
+export declare function handleWebhookEvent(payload: Buffer, signature: string): Promise<void>;
+export {};