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

package/template/src/services/admin-security.ts

@@ -0,0 +1,164 @@
+/**
+ * Peer-protection guards for administrator mutations.
+ *
+ * `admin` and `superadmin` hold the same capabilities — superadmin is a
+ * protected label, not a higher tier. Neither may ban, demote, or revoke
+ * credentials of an administrator; nobody may change their own role.
+ */
+
+import { and, count, eq, inArray, isNull, ne, or } from "drizzle-orm";
+import type { Database } from "@/db";
+import {
+	adminAction,
+	type JsonValue,
+	oauthAccessToken,
+	oauthRefreshToken,
+	session,
+	user,
+} from "@/db/schema";
+import { HttpError } from "@/utils/api-error";
+
+const ADMIN_ROLES = ["admin", "superadmin"] as const;
+
+export function isAdminRole(role: string | null | undefined): boolean {
+	return role === "admin" || role === "superadmin";
+}
+
+/**
+ * Neutralize web + OAuth access for a banned user (sessions + tokens).
+ * Starter has no api-key plugin; only sessions and OAuth tokens are revoked.
+ */
+export async function revokeUserCredentials(
+	db: Database,
+	userId: string,
+): Promise<void> {
+	await db.transaction(async (tx) => {
+		await tx
+			.delete(oauthAccessToken)
+			.where(eq(oauthAccessToken.userId, userId));
+		await tx
+			.delete(oauthRefreshToken)
+			.where(eq(oauthRefreshToken.userId, userId));
+		await tx.delete(session).where(eq(session.userId, userId));
+		await tx
+			.update(user)
+			.set({ tokensRevokedAt: new Date() })
+			.where(eq(user.id, userId));
+	});
+}
+
+/**
+ * Throw if `userId` is the last remaining usable admin/superadmin.
+ */
+export async function assertNotLastAdmin(
+	db: Database,
+	userId: string,
+): Promise<void> {
+	const rows = await db
+		.select({ n: count() })
+		.from(user)
+		.where(
+			and(
+				inArray(user.role, [...ADMIN_ROLES]),
+				ne(user.id, userId),
+				or(eq(user.banned, false), isNull(user.banned)),
+			),
+		);
+	if (Number(rows[0]?.n ?? 0) === 0) {
+		throw new HttpError({
+			status: 409,
+			error: "conflict",
+			message: "Cannot remove the last administrator.",
+		});
+	}
+}
+
+export type AdminAuditEntry = {
+	actorId: string;
+	action: string;
+	targetType?: string;
+	targetId?: string;
+	detail?: JsonValue;
+};
+
+/** Best-effort audit row; never blocks the main operation. */
+export async function logAdminAction(
+	db: Database,
+	entry: AdminAuditEntry,
+	onFailure?: (error: unknown, entry: AdminAuditEntry) => void,
+): Promise<void> {
+	try {
+		await db.insert(adminAction).values({
+			id: crypto.randomUUID(),
+			actorId: entry.actorId,
+			action: entry.action,
+			targetType: entry.targetType ?? null,
+			targetId: entry.targetId ?? null,
+			detail: entry.detail ?? null,
+		});
+	} catch (e) {
+		onFailure?.(e, entry);
+		console.error("admin audit log write failed", e);
+	}
+}
+
+/**
+ * Who may create, read, update and delete OAuth clients.
+ * Both administrator roles are capability-identical.
+ */
+export function canManageOAuthClients(user: unknown): boolean {
+	if (!user || typeof user !== "object") return false;
+	const { role } = user as { role?: unknown };
+	return typeof role === "string" && isAdminRole(role);
+}
+
+/**
+ * Pure peer-protection check. Callers have already read the target row.
+ */
+export function assertAdminMayActOn(args: {
+	actorId: string;
+	targetId: string;
+	targetRole: string | null | undefined;
+	/** The role this submit writes, when it writes one. */
+	nextRole?: string;
+	/** The ban state this submit writes, when it changes it. */
+	banning?: boolean;
+	/** True on the credential-revocation path. */
+	revokingCredentials?: boolean;
+}): void {
+	const { actorId, targetId, targetRole, nextRole, banning } = args;
+
+	const changesRole = nextRole !== undefined && nextRole !== targetRole;
+	if (changesRole && actorId === targetId) {
+		throw new HttpError({
+			status: 403,
+			error: "forbidden",
+			message: "You cannot change your own role.",
+		});
+	}
+
+	if (!isAdminRole(targetRole)) return;
+	if (changesRole) {
+		throw new HttpError({
+			status: 403,
+			error: "forbidden",
+			message: "You cannot change another administrator's role.",
+		});
+	}
+	if (banning === true) {
+		throw new HttpError({
+			status: 403,
+			error: "forbidden",
+			message: "You cannot ban another administrator.",
+		});
+	}
+	if (args.revokingCredentials) {
+		throw new HttpError({
+			status: 403,
+			error: "forbidden",
+			message: "You cannot revoke another administrator's credentials.",
+		});
+	}
+}
+
+export { ADMIN_ROLES };

package/template/src/services/admin-users.ts

@@ -0,0 +1,181 @@
+/**
+ * Admin user list + update. Starter roles only: user | admin | superadmin.
+ */
+import { and, asc, count, desc, eq, ilike, or, type SQL } from "drizzle-orm";
+import type { Database } from "@/db";
+import { user } from "@/db/schema";
+import type { AdminAuditEntry } from "@/services/admin-security";
+
+export type AdminUserRole = "user" | "admin" | "superadmin";
+
+export type ListAdminUsersParams = {
+	page: number;
+	pageSize: number;
+	search: string;
+	sort?: { id: string; desc?: boolean };
+	filters: { role?: string; banned?: string };
+};
+
+export async function listAdminUsers(
+	db: Database,
+	params: ListAdminUsersParams,
+) {
+	const { page, pageSize, search, sort, filters } = params;
+
+	const conds: SQL[] = [];
+	if (search.trim()) {
+		const q = `%${search.trim()}%`;
+		const m = or(ilike(user.email, q), ilike(user.name, q));
+		if (m) conds.push(m);
+	}
+	if (
+		filters.role === "user" ||
+		filters.role === "admin" ||
+		filters.role === "superadmin"
+	) {
+		conds.push(eq(user.role, filters.role));
+	}
+	if (filters.banned === "true" || filters.banned === "false") {
+		conds.push(eq(user.banned, filters.banned === "true"));
+	}
+	const where = conds.length ? and(...conds) : undefined;
+
+	const sortCol =
+		sort?.id === "email"
+			? user.email
+			: sort?.id === "name"
+				? user.name
+				: user.createdAt;
+	const orderBy = sort && sort.desc === false ? asc(sortCol) : desc(sortCol);
+
+	const rows = await db
+		.select({
+			id: user.id,
+			email: user.email,
+			name: user.name,
+			emailVerified: user.emailVerified,
+			role: user.role,
+			banned: user.banned,
+			twoFactorEnabled: user.twoFactorEnabled,
+			createdAt: user.createdAt,
+		})
+		.from(user)
+		.where(where)
+		.orderBy(orderBy)
+		.limit(pageSize)
+		.offset(page * pageSize);
+
+	const [{ n }] = await db.select({ n: count() }).from(user).where(where);
+	return {
+		rows: rows.map((row) => ({
+			...row,
+			createdAt: row.createdAt.getTime(),
+		})),
+		total: Number(n),
+	};
+}
+
+export type AdminUserCurrent = {
+	role: string | null;
+	banned: boolean | null;
+	emailVerified: boolean;
+};
+
+export type AdminUserUpdateData = {
+	userId: string;
+	emailVerified: boolean;
+	banned: boolean;
+	role?: AdminUserRole;
+};
+
+export type AdminUserAuthApi = {
+	setRole(args: {
+		body: { userId: string; role: AdminUserRole };
+		headers: HeadersInit;
+	}): Promise<unknown>;
+	banUser(args: {
+		body: { userId: string };
+		headers: HeadersInit;
+	}): Promise<unknown>;
+	unbanUser(args: {
+		body: { userId: string };
+		headers: HeadersInit;
+	}): Promise<unknown>;
+};
+
+export type AdminUserUpdateDeps = {
+	db: Database;
+	auth: AdminUserAuthApi;
+	headers: HeadersInit;
+	actorId: string;
+	log: (entry: AdminAuditEntry) => Promise<void>;
+	revokeCredentials: (userId: string) => Promise<void>;
+};
+
+/**
+ * Apply admin user mutations. Auth API calls first (other connection), then
+ * direct db writes — never hold a row lock across auth.api (deadlock rule).
+ */
+export async function applyAdminUserUpdate(
+	deps: AdminUserUpdateDeps,
+	current: AdminUserCurrent,
+	data: AdminUserUpdateData,
+): Promise<void> {
+	const { db, auth, headers, actorId, log, revokeCredentials } = deps;
+
+	const roleChanged =
+		data.role !== undefined && (current.role ?? "user") !== data.role;
+	const banChanged = Boolean(current.banned) !== data.banned;
+	const verifiedChanged = current.emailVerified !== data.emailVerified;
+
+	if (roleChanged && data.role !== undefined) {
+		await auth.setRole({
+			body: { userId: data.userId, role: data.role },
+			headers,
+		});
+	}
+	if (banChanged) {
+		if (data.banned) {
+			await auth.banUser({ body: { userId: data.userId }, headers });
+		} else {
+			await auth.unbanUser({ body: { userId: data.userId }, headers });
+		}
+	}
+
+	if (banChanged && data.banned) {
+		await revokeCredentials(data.userId);
+	}
+	if (verifiedChanged) {
+		await db
+			.update(user)
+			.set({ emailVerified: data.emailVerified, updatedAt: new Date() })
+			.where(eq(user.id, data.userId));
+	}
+
+	if (verifiedChanged) {
+		await log({
+			actorId,
+			action: "user.email_verified",
+			targetType: "user",
+			targetId: data.userId,
+			detail: { emailVerified: data.emailVerified },
+		});
+	}
+	if (roleChanged && data.role !== undefined) {
+		await log({
+			actorId,
+			action: "user.role_change",
+			targetType: "user",
+			targetId: data.userId,
+			detail: { from: current.role ?? "user", to: data.role },
+		});
+	}
+	if (banChanged) {
+		await log({
+			actorId,
+			action: data.banned ? "user.ban" : "user.unban",
+			targetType: "user",
+			targetId: data.userId,
+		});
+	}
+}

package/template/src/services/auth-rate-limit.ts

@@ -0,0 +1,32 @@
+// Which Better Auth endpoints to throttle, and how to key the limiter. Pure and
+// framework-free so it's unit-testable without the Cloudflare `env` binding.
+//
+// Only the brute-force / abuse-prone POST actions are throttled — credential
+// stuffing (sign-in), mass signup (sign-up), and email-bombing / enumeration
+// (password reset + verification email). Session/callback/get-session POSTs are
+// left alone so normal app traffic isn't limited.
+export const SENSITIVE_AUTH_PATHS = [
+	"/api/auth/sign-in",
+	"/api/auth/sign-up",
+	"/api/auth/forget-password",
+	"/api/auth/reset-password",
+	"/api/auth/request-password-reset",
+	"/api/auth/send-verification-email",
+] as const;
+
+/**
+ * The rate-limit key for a request that should be throttled, or null to let it
+ * through. Keyed per client IP + path so each action gets its own budget.
+ * `cf-connecting-ip` is set by the Cloudflare edge and can't be spoofed/removed
+ * by the client; the `x-forwarded-for` fallback only matters off-Cloudflare.
+ */
+export function authRateLimitKey(request: Request): string | null {
+	if (request.method !== "POST") return null;
+	const { pathname } = new URL(request.url);
+	if (!SENSITIVE_AUTH_PATHS.some((p) => pathname.startsWith(p))) return null;
+	const ip =
+		request.headers.get("cf-connecting-ip") ??
+		request.headers.get("x-forwarded-for") ??
+		"unknown";
+	return `${ip}:${pathname}`;
+}

package/template/src/services/creem.ts

@@ -0,0 +1,83 @@
+/**
+ * Creem checkout webhook: signature verification and the framework-agnostic
+ * callback handler.
+ *
+ * Kept free of `env` and framework glue so it is unit-testable; the route
+ * (src/routes/api/webhooks/creem.ts) supplies the secret and the
+ * service-context db.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type { Database } from "@/db";
+import { markPurchasePaid } from "@/services/purchase";
+
+/**
+ * Verify a Creem signature header: HMAC-SHA256 (hex) over the raw body,
+ * compared constant-time. Returns false for anything malformed — never throws
+ * on bad input, because a throw would answer "retry me" and Creem would replay
+ * a hostile body.
+ */
+export function verifyCreemSignature(
+	secret: string,
+	rawBody: string,
+	signatureHeader: string | null | undefined,
+): boolean {
+	if (!signatureHeader) return false;
+	const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
+	try {
+		return timingSafeEqual(
+			Buffer.from(expected),
+			Buffer.from(signatureHeader.trim()),
+		);
+	} catch {
+		return false;
+	}
+}
+
+export type CreemWebhookResult =
+	| "invalid_signature"
+	| "invalid_payload"
+	| "credited"
+	| "unknown_order"
+	| "noop";
+
+/**
+ * Handle a Creem webhook: verify the signature, then fulfill on the checkout
+ * id, joining on it as the Purchase `externalId`. Creem reports no amount we
+ * would trust, so fulfillment uses the Purchase row's own amount with no
+ * integrity check to run against.
+ *
+ * `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 Creem
+ * retries; every mapped outcome resolves so the route answers 200 and Creem
+ * stops retrying.
+ */
+export async function handleCreemWebhook(
+	db: Database,
+	args: { rawBody: string; signature: string | null; secret: string },
+): Promise<CreemWebhookResult> {
+	if (!verifyCreemSignature(args.secret, args.rawBody, args.signature)) {
+		return "invalid_signature";
+	}
+
+	// Creem signs the raw string, so a valid signature over an unparseable body
+	// means the sender signed garbage. That is a client error, not a retry.
+	let payload: { id?: string; object?: { id?: string }; eventType?: string };
+	try {
+		payload = JSON.parse(args.rawBody) as typeof payload;
+	} catch {
+		return "invalid_payload";
+	}
+
+	const externalId = payload.object?.id ?? payload.id;
+	if (!externalId) return "noop";
+
+	const result = await markPurchasePaid(db, {
+		provider: "creem",
+		externalId,
+	});
+	if (result.status === "not_found") return "unknown_order";
+	return result.status === "fulfilled" || result.status === "already_paid"
+		? "credited"
+		: "noop";
+}

package/template/src/services/demo-checkout.ts

@@ -0,0 +1,100 @@
+/**
+ * Minimal demo checkout start: toggle + env gated, pending Purchase under
+ * service scope. Product domain fulfills via onPurchasePaid.
+ */
+import type { PaymentToggles } from "@/services/payment-toggles";
+import type { PurchaseProvider } from "@/services/purchase";
+
+/** Fixed demo price in minor units ($5.00). Clones replace or parameterize. */
+export const DEMO_CHECKOUT_AMOUNT_MINOR = 500;
+
+type CheckoutGateResult =
+	| { ok: true }
+	| { ok: false; code: "disabled" | "not_configured" };
+
+export function resolveCheckoutGate(args: {
+	provider: PurchaseProvider;
+	toggles: PaymentToggles;
+	configured: Record<PurchaseProvider, boolean>;
+}): CheckoutGateResult {
+	if (!args.toggles[args.provider]) return { ok: false, code: "disabled" };
+	if (!args.configured[args.provider]) {
+		return { ok: false, code: "not_configured" };
+	}
+	return { ok: true };
+}
+
+export type DemoCheckoutPort = {
+	getToggles(): Promise<PaymentToggles>;
+	isConfigured(provider: PurchaseProvider): boolean;
+	createHostedSession(input: {
+		provider: PurchaseProvider;
+		userId: string;
+		userEmail: string;
+		amount: number;
+		currency: string;
+	}): Promise<{ externalId: string; url: string }>;
+	createPendingPurchase(input: {
+		userId: string;
+		provider: PurchaseProvider;
+		externalId: string;
+		amount: number;
+		currency: string;
+	}): Promise<{ purchaseId: string }>;
+};
+
+type StartDemoCheckoutResult =
+	| {
+			ok: true;
+			url: string;
+			purchaseId: string;
+			externalId: string;
+			amount: number;
+	  }
+	| { ok: false; code: "disabled" | "not_configured" };
+
+/**
+ * Start a demo checkout: host session first (external id), then pending row
+ * keyed by that id so webhooks can fulfill. Host session before DB so a
+ * failed provider call never leaves an orphan pending purchase.
+ */
+export async function startDemoCheckout(
+	port: DemoCheckoutPort,
+	input: { userId: string; userEmail: string; provider: PurchaseProvider },
+): Promise<StartDemoCheckoutResult> {
+	const toggles = await port.getToggles();
+	const gate = resolveCheckoutGate({
+		provider: input.provider,
+		toggles,
+		configured: {
+			stripe: port.isConfigured("stripe"),
+			creem: port.isConfigured("creem"),
+			nowpayments: port.isConfigured("nowpayments"),
+		},
+	});
+	if (!gate.ok) return gate;
+
+	const currency = "usd";
+	const amount = DEMO_CHECKOUT_AMOUNT_MINOR;
+	const session = await port.createHostedSession({
+		provider: input.provider,
+		userId: input.userId,
+		userEmail: input.userEmail,
+		amount,
+		currency,
+	});
+	const { purchaseId } = await port.createPendingPurchase({
+		userId: input.userId,
+		provider: input.provider,
+		externalId: session.externalId,
+		amount,
+		currency,
+	});
+	return {
+		ok: true,
+		url: session.url,
+		purchaseId,
+		externalId: session.externalId,
+		amount,
+	};
+}