@0x0501/mystack 0.0.0-stage → 0.1.0-bootstrap.0

package/template/src/services/nowpayments.ts

@@ -0,0 +1,154 @@
+/**
+ * NowPayments crypto IPN: signature verification and the framework-agnostic
+ * callback handler. Crypto settles asynchronously, so the signed IPN is the
+ * sole source of truth for fulfillment — the return page never confirms.
+ *
+ * Kept free of `env` and framework glue so it is unit-testable; the route
+ * (src/routes/api/webhooks/nowpayments.ts) supplies the secret and the
+ * service-context db.
+ */
+import type { Database } from "@/db";
+import { markPurchasePaid } from "@/services/purchase";
+
+/** Only these statuses release funds; everything else leaves the row pending. */
+const PAID_STATUSES = new Set(["finished", "confirmed"]);
+
+/**
+ * Deeper than any real IPN payload, shallow enough that the recursion below
+ * cannot exhaust the stack on a hostile body.
+ */
+const MAX_CANONICAL_DEPTH = 64;
+
+class TooDeepError extends Error {}
+
+/** Recursively sort object keys so serialization is canonical (arrays keep order). */
+function sortKeys(value: unknown, depth = 0): unknown {
+	if (depth > MAX_CANONICAL_DEPTH) throw new TooDeepError();
+	if (Array.isArray(value)) return value.map((v) => sortKeys(v, depth + 1));
+	if (value && typeof value === "object") {
+		return Object.fromEntries(
+			Object.keys(value as Record<string, unknown>)
+				.sort()
+				.map((k) => [
+					k,
+					sortKeys((value as Record<string, unknown>)[k], depth + 1),
+				]),
+		);
+	}
+	return value;
+}
+
+async function hmacSha512Hex(key: string, message: string): Promise<string> {
+	const enc = new TextEncoder();
+	const cryptoKey = await crypto.subtle.importKey(
+		"raw",
+		enc.encode(key),
+		{ name: "HMAC", hash: "SHA-512" },
+		false,
+		["sign"],
+	);
+	const sig = await crypto.subtle.sign("HMAC", cryptoKey, enc.encode(message));
+	return Array.from(new Uint8Array(sig))
+		.map((b) => b.toString(16).padStart(2, "0"))
+		.join("");
+}
+
+/** Length-independent, constant-time comparison of two equal-length hex strings. */
+function timingSafeEqualHex(a: string, b: string): boolean {
+	if (a.length !== b.length) return false;
+	let diff = 0;
+	for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+	return diff === 0;
+}
+
+/**
+ * Verify an IPN callback: HMAC-SHA512 (hex) over the recursively key-sorted,
+ * re-serialized JSON body, compared constant-time against the
+ * `x-nowpayments-sig` header. Returns false for a missing/invalid signature or
+ * an unparseable body — never throws on bad input.
+ */
+export async function verifyNowPaymentsSignature(
+	ipnKey: string,
+	rawBody: string,
+	signature: string | null | undefined,
+): Promise<boolean> {
+	if (!signature) return false;
+	let canonical: string;
+	try {
+		// Parsing and canonicalising are both refusals, not crashes: a body that
+		// is unparseable or nested past the depth limit is a bad signature. If it
+		// escaped as a 500 the route would answer "retry me" and NowPayments
+		// would replay the hostile body forever.
+		canonical = JSON.stringify(sortKeys(JSON.parse(rawBody)));
+	} catch {
+		return false;
+	}
+	const expected = await hmacSha512Hex(ipnKey, canonical);
+	return timingSafeEqualHex(expected, signature.trim());
+}
+
+export type NowPaymentsWebhookResult =
+	| "invalid_signature"
+	| "credited"
+	| "underpaid"
+	| "unknown_order"
+	| "noop";
+
+/**
+ * Handle a NowPayments IPN: verify the signature, then map the payment status
+ * to the matching action, joining on our own `order_id` (= Purchase
+ * `externalId`). Only a terminal paid status fulfills; an underpaid invoice and
+ * every intermediate status leave the Purchase `pending`. Fulfillment is
+ * idempotent and status-guarded (see services/purchase), so retries and
+ * out-of-order callbacks never deliver twice.
+ *
+ * `db` must already carry service RLS context (the route wraps this in
+ * withRlsService). Throws only on a genuine processing/DB error — including a
+ * throw from the purchase-paid hook — so the route can answer 5xx and
+ * NowPayments retries; every mapped outcome resolves so the route answers 200
+ * and NowPayments stops retrying.
+ */
+export async function handleNowPaymentsWebhook(
+	db: Database,
+	args: { rawBody: string; signature: string | null; ipnKey: string },
+): Promise<NowPaymentsWebhookResult> {
+	if (
+		!(await verifyNowPaymentsSignature(
+			args.ipnKey,
+			args.rawBody,
+			args.signature,
+		))
+	) {
+		return "invalid_signature";
+	}
+
+	// Parsing cannot fail here: verification already parsed this exact body.
+	const body = JSON.parse(args.rawBody) as {
+		order_id?: string;
+		payment_status?: string;
+		actually_paid?: number;
+		price_amount?: number;
+	};
+
+	const externalId = body.order_id;
+	if (!externalId || !body.payment_status) return "noop";
+	if (!PAID_STATUSES.has(body.payment_status)) return "noop";
+
+	// Underpayment: actually_paid < price_amount → do not fulfill.
+	if (
+		typeof body.actually_paid === "number" &&
+		typeof body.price_amount === "number" &&
+		body.actually_paid + 1e-9 < body.price_amount
+	) {
+		return "underpaid";
+	}
+
+	const result = await markPurchasePaid(db, {
+		provider: "nowpayments",
+		externalId,
+	});
+	if (result.status === "not_found") return "unknown_order";
+	return result.status === "fulfilled" || result.status === "already_paid"
+		? "credited"
+		: "noop";
+}

package/template/src/services/oauth-client.ts

@@ -0,0 +1,85 @@
+import { z } from "zod";
+
+export const DEFAULT_OAUTH_SCOPE = "openid profile email offline_access";
+
+const redirectUriSchema = z
+	.url()
+	.trim()
+	.refine(
+		(value) => {
+			const url = new URL(value);
+			if (url.hash || url.username || url.password) return false;
+			if (url.protocol === "https:") return true;
+			if (url.protocol !== "http:") return false;
+			return url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+		},
+		{
+			message:
+				"Redirect URI must be HTTPS, or HTTP on 127.0.0.1/[::1], without userinfo or fragments.",
+		},
+	);
+
+const scopeToken = /^[\x21\x23-\x5B\x5D-\x7E]+$/;
+const scopeSchema = z
+	.string()
+	.trim()
+	.min(1)
+	.max(500)
+	.refine(
+		(value) => value.split(/\s+/).every((token) => scopeToken.test(token)),
+		{ message: "Scope contains invalid characters." },
+	)
+	.transform((value) => value.split(/\s+/).join(" "));
+
+export const createOAuthClientInputSchema = z.object({
+	clientName: z.string().trim().min(1).max(100),
+	redirectUris: z
+		.array(redirectUriSchema)
+		.min(1)
+		.max(10)
+		.transform((uris) => [...new Set(uris)]),
+	scope: scopeSchema.default(DEFAULT_OAUTH_SCOPE),
+	publicClient: z.boolean().default(false),
+});
+
+export type CreateOAuthClientInput = z.infer<
+	typeof createOAuthClientInputSchema
+>;
+
+/**
+ * Written as mutable arrays, not `as const` tuples: the provider's registration
+ * body declares these as writable arrays of enum members, and a `readonly`
+ * tuple is not assignable to one. Fresh arrays per call so a caller cannot
+ * reach back through the returned body and edit a shared literal.
+ */
+type GrantType = "authorization_code" | "refresh_token";
+const grantTypes = (): GrantType[] => ["authorization_code", "refresh_token"];
+const responseTypes = (): Array<"code"> => ["code"];
+
+export function oauthClientRegistrationBody(input: CreateOAuthClientInput) {
+	if (input.publicClient) {
+		return {
+			client_name: input.clientName,
+			redirect_uris: input.redirectUris,
+			type: "native" as const,
+			token_endpoint_auth_method: "none" as const,
+			require_pkce: true,
+			grant_types: grantTypes(),
+			response_types: responseTypes(),
+			skip_consent: false,
+			scope: input.scope,
+			enable_end_session: true,
+		};
+	}
+	return {
+		client_name: input.clientName,
+		redirect_uris: input.redirectUris,
+		token_endpoint_auth_method: "client_secret_post" as const,
+		require_pkce: true,
+		grant_types: grantTypes(),
+		response_types: responseTypes(),
+		skip_consent: false,
+		scope: input.scope,
+		enable_end_session: true,
+	};
+}

package/template/src/services/oauth-clients.ts

@@ -0,0 +1,15 @@
+import { eq } from "drizzle-orm";
+import type { Database } from "@/db";
+import { oauthClient } from "@/db/schema";
+
+/** Returns false when there was no such client. */
+export async function deleteOAuthClientById(
+	db: Database,
+	clientId: string,
+): Promise<boolean> {
+	const deleted = await db
+		.delete(oauthClient)
+		.where(eq(oauthClient.clientId, clientId))
+		.returning({ clientId: oauthClient.clientId });
+	return deleted.length > 0;
+}

package/template/src/services/payment-providers.ts

@@ -0,0 +1,157 @@
+/**
+ * Thin hosted-checkout adapters for demo purchase start.
+ * Webhooks remain the paid confirmation path.
+ */
+import { env } from "@/env";
+import type { PurchaseProvider } from "@/services/purchase";
+
+export function isPaymentProviderConfigured(
+	provider: PurchaseProvider,
+): boolean {
+	switch (provider) {
+		case "stripe":
+			return Boolean(env.STRIPE_SECRET_KEY);
+		case "creem":
+			return Boolean(env.CREEM_API_KEY && env.CREEM_PRODUCT_ID);
+		case "nowpayments":
+			return Boolean(env.NOW_PAYMENTS_API_KEY);
+		default:
+			return false;
+	}
+}
+
+export async function createHostedCheckoutSession(input: {
+	provider: PurchaseProvider;
+	userId: string;
+	userEmail: string;
+	amount: number;
+	currency: string;
+}): Promise<{ externalId: string; url: string }> {
+	switch (input.provider) {
+		case "stripe":
+			return createStripeSession(input);
+		case "creem":
+			return createCreemCheckout(input);
+		case "nowpayments":
+			return createNowPaymentsInvoice(input);
+		default:
+			throw new Error(`Unknown payment provider: ${input.provider}`);
+	}
+}
+
+async function createStripeSession(input: {
+	userId: string;
+	userEmail: string;
+	amount: number;
+	currency: string;
+}): Promise<{ externalId: string; url: string }> {
+	const key = env.STRIPE_SECRET_KEY;
+	if (!key) throw new Error("Stripe is not configured.");
+	const origin = env.APP_ORIGIN;
+	const body = new URLSearchParams();
+	body.set("mode", "payment");
+	body.set("success_url", `${origin}/dashboard?checkout=success`);
+	body.set("cancel_url", `${origin}/dashboard?checkout=cancel`);
+	body.set("customer_email", input.userEmail);
+	body.set("client_reference_id", input.userId);
+	body.set("line_items[0][quantity]", "1");
+	body.set("line_items[0][price_data][currency]", input.currency);
+	body.set("line_items[0][price_data][unit_amount]", String(input.amount));
+	body.set("line_items[0][price_data][product_data][name]", "Demo purchase");
+
+	const res = await fetch("https://api.stripe.com/v1/checkout/sessions", {
+		method: "POST",
+		headers: {
+			authorization: `Bearer ${key}`,
+			"content-type": "application/x-www-form-urlencoded",
+		},
+		body,
+	});
+	if (!res.ok) {
+		const text = await res.text();
+		throw new Error(`Stripe checkout failed: ${res.status} ${text}`);
+	}
+	const data = (await res.json()) as { id: string; url: string };
+	if (!data.id || !data.url) throw new Error("Stripe returned no session URL.");
+	return { externalId: data.id, url: data.url };
+}
+
+async function createCreemCheckout(input: {
+	userId: string;
+	userEmail: string;
+	amount: number;
+}): Promise<{ externalId: string; url: string }> {
+	const apiKey = env.CREEM_API_KEY;
+	const productId = env.CREEM_PRODUCT_ID;
+	if (!apiKey || !productId) throw new Error("Creem is not configured.");
+	const base = env.CREEM_TEST_MODE
+		? "https://test-api.creem.io"
+		: "https://api.creem.io";
+	const res = await fetch(`${base}/v1/checkouts`, {
+		method: "POST",
+		headers: {
+			"content-type": "application/json",
+			"x-api-key": apiKey,
+		},
+		body: JSON.stringify({
+			product_id: productId,
+			request_id: input.userId,
+			customer: { email: input.userEmail },
+			// custom_price in minor units when product allows
+			custom_price: input.amount,
+			success_url: `${env.APP_ORIGIN}/dashboard?checkout=success`,
+		}),
+	});
+	if (!res.ok) {
+		const text = await res.text();
+		throw new Error(`Creem checkout failed: ${res.status} ${text}`);
+	}
+	const data = (await res.json()) as {
+		id?: string;
+		checkout_url?: string;
+		url?: string;
+	};
+	const externalId = data.id;
+	const url = data.checkout_url ?? data.url;
+	if (!externalId || !url) throw new Error("Creem returned no checkout URL.");
+	return { externalId, url };
+}
+
+async function createNowPaymentsInvoice(input: {
+	userId: string;
+	userEmail: string;
+	amount: number;
+	currency: string;
+}): Promise<{ externalId: string; url: string }> {
+	const apiKey = env.NOW_PAYMENTS_API_KEY;
+	if (!apiKey) throw new Error("NOWPayments is not configured.");
+	const priceAmount = (input.amount / 100).toFixed(2);
+	const res = await fetch("https://api.nowpayments.io/v1/invoice", {
+		method: "POST",
+		headers: {
+			"content-type": "application/json",
+			"x-api-key": apiKey,
+		},
+		body: JSON.stringify({
+			price_amount: Number(priceAmount),
+			price_currency: input.currency,
+			order_id: `demo-${input.userId}-${Date.now()}`,
+			order_description: "Demo purchase",
+			ipn_callback_url: `${env.APP_ORIGIN}/api/webhooks/nowpayments`,
+			success_url: `${env.APP_ORIGIN}/dashboard?checkout=success`,
+			cancel_url: `${env.APP_ORIGIN}/dashboard?checkout=cancel`,
+		}),
+	});
+	if (!res.ok) {
+		const text = await res.text();
+		throw new Error(`NOWPayments invoice failed: ${res.status} ${text}`);
+	}
+	const data = (await res.json()) as {
+		id?: string | number;
+		invoice_url?: string;
+	};
+	if (data.id == null || !data.invoice_url) {
+		throw new Error("NOWPayments returned no invoice URL.");
+	}
+	return { externalId: String(data.id), url: data.invoice_url };
+}

package/template/src/services/payment-toggles.ts

@@ -0,0 +1,48 @@
+/**
+ * Runtime payment method toggles stored in system_config.
+ * Disabled rails are refused server-side, not merely hidden.
+ */
+import { eq } from "drizzle-orm";
+import type { Database } from "@/db";
+import { systemConfig } from "@/db/schema";
+import type { PurchaseProvider } from "@/services/purchase";
+
+const KEY = "payment_toggles";
+
+export type PaymentToggles = Record<PurchaseProvider, boolean>;
+
+const DEFAULT_TOGGLES: PaymentToggles = {
+	stripe: true,
+	creem: true,
+	nowpayments: true,
+};
+
+export async function getPaymentToggles(db: Database): Promise<PaymentToggles> {
+	const [row] = await db
+		.select()
+		.from(systemConfig)
+		.where(eq(systemConfig.key, KEY))
+		.limit(1);
+	if (!row || typeof row.value !== "object" || row.value === null) {
+		return { ...DEFAULT_TOGGLES };
+	}
+	const v = row.value as Partial<PaymentToggles>;
+	return {
+		stripe: v.stripe !== false,
+		creem: v.creem !== false,
+		nowpayments: v.nowpayments !== false,
+	};
+}
+
+export async function setPaymentToggles(
+	db: Database,
+	toggles: PaymentToggles,
+): Promise<void> {
+	await db
+		.insert(systemConfig)
+		.values({ key: KEY, value: toggles })
+		.onConflictDoUpdate({
+			target: systemConfig.key,
+			set: { value: toggles, updatedAt: new Date() },
+		});
+}

package/template/src/services/purchase.ts

@@ -0,0 +1,233 @@
+/**
+ * Purchase fulfillment: idempotent mark-paid with the purchase-paid hook
+ * running inside the same transaction as the pending→paid flip.
+ *
+ * Product domain implements fulfillment by replacing `onPurchasePaid`.
+ * Adapters (Stripe/Creem/NowPayments) call `markPurchasePaid` after verifying
+ * the webhook; they never invent balances or entitlements, and they trust the
+ * Purchase row's amount and user rather than the numbers in the callback.
+ */
+import { and, eq } from "drizzle-orm";
+import type { Database } from "@/db";
+import type { JsonValue } from "@/db/platform.schema";
+import { adminAction, purchase as purchaseTable } from "@/db/schema";
+
+export type PurchaseProvider = "stripe" | "creem" | "nowpayments";
+
+export type PurchaseStatus = "pending" | "paid" | "failed";
+
+export type Purchase = {
+	id: string;
+	userId: string;
+	provider: PurchaseProvider;
+	externalId: string;
+	/** Trusted amount in minor units (e.g. cents). */
+	amount: number;
+	currency: string;
+	status: PurchaseStatus;
+	paidAt: Date | null;
+};
+
+export type MarkPurchasePaidResult =
+	| { status: "fulfilled"; purchase: Purchase }
+	| { status: "already_paid"; purchase: Purchase }
+	| { status: "not_found" }
+	| { status: "not_pending"; purchase: Purchase }
+	| { status: "amount_mismatch"; purchase: Purchase };
+
+type PurchaseAuditEntry = {
+	action: "purchase.paid" | "purchase.failed" | "purchase.duplicate_ignored";
+	targetId?: string;
+	detail?: Record<string, JsonValue>;
+};
+
+/** Parse a minor-unit amount stored as decimal text (no float parse). */
+function parseMinorUnits(amount: string): number {
+	if (!/^-?\d+$/.test(amount)) {
+		throw new Error(`Invalid purchase amount: ${amount}`);
+	}
+	const n = Number.parseInt(amount, 10);
+	if (!Number.isSafeInteger(n)) {
+		throw new Error(`Purchase amount outside safe integer range: ${amount}`);
+	}
+	return n;
+}
+
+function rowToPurchase(row: typeof purchaseTable.$inferSelect): Purchase {
+	return {
+		id: row.id,
+		userId: row.userId,
+		provider: row.provider as PurchaseProvider,
+		externalId: row.externalId,
+		amount: parseMinorUnits(row.amount),
+		currency: row.currency,
+		status: row.status as PurchaseStatus,
+		paidAt: row.paidAt,
+	};
+}
+
+async function findPurchase(
+	db: Database,
+	provider: PurchaseProvider,
+	externalId: string,
+): Promise<Purchase | null> {
+	const [row] = await db
+		.select()
+		.from(purchaseTable)
+		.where(
+			and(
+				eq(purchaseTable.provider, provider),
+				eq(purchaseTable.externalId, externalId),
+			),
+		)
+		.limit(1);
+	return row ? rowToPurchase(row) : null;
+}
+
+/**
+ * The single extension point a product domain implements. Default: no-op.
+ *
+ * It runs **inside the transaction that flips the row to `paid`**, so a throw
+ * rolls the flip back, `markPurchasePaid` rethrows, the route answers 5xx, and
+ * the provider's retry re-enters and delivers exactly once. That is the whole
+ * reason the hook receives `tx`.
+ *
+ * Because it shares that transaction it must do database work only. An HTTP
+ * call or an email send here holds a Postgres connection open across the
+ * network (the deadlock rule in ADR 0006, and Hyperdrive cannot multiplex a
+ * held connection) and couples the provider's retry window to its latency. If
+ * fulfillment needs IO, write a row here and do the IO afterwards.
+ */
+export async function onPurchasePaid(
+	_tx: Database,
+	_purchase: Purchase,
+): Promise<void> {
+	// Product domain implements entitlements here.
+}
+
+/**
+ * Idempotent payment fulfillment. Amounts and user identity come only from the
+ * Purchase row — never from callback-reported amounts alone (optional
+ * `reportedAmount` is an integrity check that fails closed on mismatch).
+ *
+ * Throws only on a genuine processing/DB error — including a throw from
+ * `hook` — so the caller can answer 5xx and the provider retries. Every mapped
+ * outcome resolves, so the caller answers 200 and the provider stops retrying.
+ */
+export async function markPurchasePaid(
+	db: Database,
+	input: {
+		provider: PurchaseProvider;
+		externalId: string;
+		/** Optional integrity check against the local Purchase amount. */
+		reportedAmount?: number;
+	},
+	hook: (tx: Database, purchase: Purchase) => Promise<void> = onPurchasePaid,
+): Promise<MarkPurchasePaidResult> {
+	const existing = await findPurchase(db, input.provider, input.externalId);
+	if (!existing) return { status: "not_found" };
+	if (existing.status === "paid") {
+		await safeAudit(db, {
+			action: "purchase.duplicate_ignored",
+			targetId: existing.id,
+			detail: { provider: input.provider, externalId: input.externalId },
+		});
+		return { status: "already_paid", purchase: existing };
+	}
+	if (existing.status !== "pending") {
+		return { status: "not_pending", purchase: existing };
+	}
+	if (
+		input.reportedAmount !== undefined &&
+		input.reportedAmount !== existing.amount
+	) {
+		return { status: "amount_mismatch", purchase: existing };
+	}
+
+	const now = new Date();
+	const paid = await db.transaction(async (tx) => {
+		const flipped = await tx
+			.update(purchaseTable)
+			.set({ status: "paid", paidAt: now })
+			.where(
+				and(
+					eq(purchaseTable.id, existing.id),
+					eq(purchaseTable.status, "pending"),
+				),
+			)
+			.returning();
+		// Lost the race: a concurrent confirmation already fulfilled this row.
+		if (!flipped[0]) return null;
+		const row = rowToPurchase(flipped[0]);
+		await hook(tx as unknown as Database, row);
+		return row;
+	});
+
+	if (!paid) {
+		const again = await findPurchase(db, input.provider, input.externalId);
+		if (again?.status === "paid") {
+			await safeAudit(db, {
+				action: "purchase.duplicate_ignored",
+				targetId: again.id,
+			});
+			return { status: "already_paid", purchase: again };
+		}
+		return { status: "not_pending", purchase: existing };
+	}
+
+	// After the commit, never inside it. Audit writes are best-effort: a logging
+	// failure must not roll back a payment that has already been delivered.
+	await safeAudit(db, {
+		action: "purchase.paid",
+		targetId: paid.id,
+		detail: {
+			provider: paid.provider,
+			externalId: paid.externalId,
+			amount: paid.amount,
+			currency: paid.currency,
+			userId: paid.userId,
+		},
+	});
+	return { status: "fulfilled", purchase: paid };
+}
+
+export async function createPendingPurchase(
+	db: Database,
+	input: {
+		userId: string;
+		provider: PurchaseProvider;
+		externalId: string;
+		amount: number;
+		currency?: string;
+	},
+): Promise<{ purchaseId: string }> {
+	const id = crypto.randomUUID();
+	await db.insert(purchaseTable).values({
+		id,
+		userId: input.userId,
+		provider: input.provider,
+		externalId: input.externalId,
+		amount: String(input.amount),
+		currency: input.currency ?? "usd",
+		status: "pending",
+	});
+	return { purchaseId: id };
+}
+
+async function safeAudit(
+	db: Database,
+	entry: PurchaseAuditEntry,
+): Promise<void> {
+	try {
+		await db.insert(adminAction).values({
+			id: crypto.randomUUID(),
+			actorId: null,
+			action: entry.action,
+			targetType: "purchase",
+			targetId: entry.targetId ?? null,
+			detail: entry.detail ?? null,
+		});
+	} catch (e) {
+		console.error("purchase audit log write failed", e);
+	}
+}