@remit/backend 0.0.1

package/src/index.ts

@@ -0,0 +1,170 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { inspect } from "node:util";
+import { logger, withTelemetry } from "@remit/logger-lambda";
+import type { APIGatewayProxyEvent, Context } from "aws-lambda";
+import {
+	type Document,
+	OpenAPIBackend,
+	type Context as OpenAPIContext,
+	type Request,
+} from "openapi-backend";
+import { assertLocalBypassNotInDeployedEnv } from "./auth.js";
+import { usesBetterAuthJwt } from "./data-backend.js";
+import { handleError } from "./error.js";
+import { handlers } from "./handlers/index.js";
+import { authenticatePostgresRequest } from "./jwt-auth.js";
+import { normalizeRequest } from "./request.js";
+import { runWithRequestContext } from "./request-context.js";
+import { formatResponse, postResponseHandler } from "./response.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Boot-time refusal: the local auth-bypass overrides must never be set in a
+// deployed environment. Runs on module load so a leaked env var fails the
+// process at startup rather than silently opening authentication at runtime.
+assertLocalBypassNotInDeployedEnv();
+
+/**
+ * Last-resort net for a leaked background rejection.
+ *
+ * Every fire-and-forget side effect is meant to be contained at its source (see
+ * service/fire-and-forget.ts), so reaching here is a bug — an uncontained
+ * `void promise` somewhere. The API process (dev-server / warm Lambda container)
+ * shares one event loop across requests, so without this handler such a leak
+ * would surface as a spurious 500 on whatever request was in flight. We log it
+ * LOUDLY with a distinct alert so it is observable, and deliberately do NOT exit
+ * — a stray background rejection must never take the API down or fail a request.
+ * (The worker process intentionally has no such net: there each message is its
+ * own invocation and a rejection should crash it.)
+ */
+const unhandledRejectionRegistered = Symbol.for(
+	"remit.backend.unhandledRejectionNet",
+);
+const globalProcess = process as unknown as Record<symbol, boolean>;
+if (!globalProcess[unhandledRejectionRegistered]) {
+	globalProcess[unhandledRejectionRegistered] = true;
+	process.on("unhandledRejection", (reason: unknown) => {
+		logger.error(
+			{
+				alert: "unhandled_rejection",
+				errorName: (reason as { name?: string })?.name,
+				errorCode:
+					(reason as { Code?: string })?.Code ??
+					(reason as { code?: string })?.code,
+				error: inspect(reason),
+			},
+			"Unhandled promise rejection leaked into the API event loop (contained, request not failed)",
+		);
+	});
+}
+
+const loadOpenAPISpec = (): Document => {
+	// Bundled Lambda: infra's NodeJSArmFunction copies openapi.json into the
+	// bundle root next to the entrypoint via its `extraFiles` prop.
+	const bundledPath = join(__dirname, "openapi.json");
+	if (existsSync(bundledPath)) {
+		return JSON.parse(readFileSync(bundledPath, "utf-8"));
+	}
+
+	// Dev (tsx / dev-server): read straight from the repo build tree.
+	const devPath = join(__dirname, "../../../build/remit-openapi3/openapi.json");
+	return JSON.parse(readFileSync(devPath, "utf-8"));
+};
+
+const OpenAPISpec = loadOpenAPISpec();
+
+const api = new OpenAPIBackend({
+	definition: OpenAPISpec,
+	quick: true,
+	// Coerce query/path params to their schema types. API Gateway delivers every
+	// query param as a string; handlers cast them to number/boolean (e.g. `limit`,
+	// `hasAttachment`) and forward them downstream. Without coercion a string
+	// `limit` reaches ElectroDB's `.go({ limit })` and DynamoDB rejects the
+	// numeric Limit field ("STRING_VALUE cannot be converted to Integer"), 500ing
+	// /addresses/search and /search/semantic.
+	coerceTypes: true,
+});
+
+api.register("postResponseHandler", postResponseHandler);
+
+api.register("validationFail", (c: OpenAPIContext, req: Request) => {
+	const operation = api.router.getOperation(c.operation?.operationId ?? "");
+	logger.error(
+		{
+			errors: c.validation.errors,
+			method: req.method,
+			path: req.path,
+			operation: c.operation?.operationId,
+			operationParameters: operation?.parameters,
+			validationContext: {
+				parsedRequest: c.request,
+				validationTarget: c.validation,
+			},
+		},
+		"Validation failed",
+	);
+	return {
+		statusCode: 400,
+		body: {
+			message: "Invalid request",
+			errors: c.validation.errors,
+		},
+	};
+});
+
+api.register("notFound", () => ({ statusCode: 404 }));
+
+api.register("notImplemented", async (c: OpenAPIContext) => {
+	const { status, mock } = api.mockResponseForOperation(
+		c.operation.operationId as string,
+	);
+	return formatResponse(mock as Record<string, unknown>, status);
+});
+
+api.register(handlers);
+
+api.init();
+
+export { api, OpenAPISpec };
+
+const readOriginHeader = (
+	headers: APIGatewayProxyEvent["headers"],
+): string | undefined => {
+	if (!headers) return undefined;
+	for (const [key, value] of Object.entries(headers)) {
+		if (key.toLowerCase() === "origin" && typeof value === "string") {
+			return value;
+		}
+	}
+	return undefined;
+};
+
+const rawHandler = async (event: APIGatewayProxyEvent, context: Context) => {
+	logger.setBindings({
+		requestId: context.awsRequestId,
+		path: event.path,
+		method: event.httpMethod,
+	});
+
+	logger.debug(
+		{ method: event.httpMethod, path: event.path },
+		"Request received",
+	);
+
+	const origin = readOriginHeader(event.headers);
+
+	if (usesBetterAuthJwt()) {
+		const denied = await authenticatePostgresRequest(event);
+		if (denied) return denied;
+	}
+
+	return runWithRequestContext({ origin }, () =>
+		api
+			.handleRequest(normalizeRequest(event), event, context)
+			.catch(handleError),
+	);
+};
+
+export const handler = withTelemetry(rawHandler);

package/src/json.ts

@@ -0,0 +1,11 @@
+/**
+ * Parse JSON in a Promise so a malformed string surfaces as a rejection the
+ * caller can `.catch()`, instead of a synchronous throw that would need a block
+ * try/catch. Use only where an unparseable value is an expected, recoverable
+ * absence (e.g. a third-party token, a dev-server response body) — never to
+ * soften an internal contract, which must stay a fatal uncaught `JSON.parse`.
+ */
+export const safeJsonParse = <T>(raw: string): Promise<T> =>
+	new Promise((resolve) => {
+		resolve(JSON.parse(raw));
+	});

package/src/jwt-auth.test.ts

@@ -0,0 +1,89 @@
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, test } from "node:test";
+import type { APIGatewayProxyEvent } from "aws-lambda";
+import {
+	_setVerifierForTest,
+	authenticatePostgresRequest,
+} from "./jwt-auth.js";
+
+const buildEvent = (
+	overrides: Partial<APIGatewayProxyEvent> = {},
+): APIGatewayProxyEvent =>
+	({
+		headers: {},
+		requestContext: {},
+		...overrides,
+	}) as APIGatewayProxyEvent;
+
+let savedBypass: string | undefined;
+
+beforeEach(() => {
+	savedBypass = process.env.LOCAL_ACCOUNT_CONFIG_ID;
+	delete process.env.LOCAL_ACCOUNT_CONFIG_ID;
+});
+
+afterEach(() => {
+	_setVerifierForTest(null);
+	if (savedBypass === undefined) delete process.env.LOCAL_ACCOUNT_CONFIG_ID;
+	else process.env.LOCAL_ACCOUNT_CONFIG_ID = savedBypass;
+});
+
+test("valid token injects verified sub into authorizer claims", async () => {
+	_setVerifierForTest(async () => ({ sub: "user-abc", email: "a@b.com" }));
+	const event = buildEvent({
+		headers: { Authorization: "Bearer good.token.here" },
+	});
+
+	const result = await authenticatePostgresRequest(event);
+
+	assert.equal(result, null);
+	assert.equal(event.requestContext.authorizer?.claims?.sub, "user-abc");
+	assert.equal(event.requestContext.authorizer?.claims?.email, "a@b.com");
+});
+
+test("invalid token returns 401 and does not inject claims", async () => {
+	_setVerifierForTest(async () => {
+		throw new Error("bad signature");
+	});
+	const event = buildEvent({
+		headers: { authorization: "Bearer bad.token" },
+	});
+
+	const result = await authenticatePostgresRequest(event);
+
+	assert.equal(result?.statusCode, 401);
+	assert.equal(event.requestContext.authorizer, undefined);
+});
+
+test("no token with a local bypass configured is allowed", async () => {
+	process.env.LOCAL_ACCOUNT_CONFIG_ID = "some-config-id";
+	const event = buildEvent();
+
+	const result = await authenticatePostgresRequest(event);
+
+	assert.equal(result, null);
+});
+
+test("no token and no bypass returns 401", async () => {
+	const event = buildEvent();
+
+	const result = await authenticatePostgresRequest(event);
+
+	assert.equal(result?.statusCode, 401);
+});
+
+test("pre-injected claims (edge tier) short-circuit verification", async () => {
+	_setVerifierForTest(async () => {
+		throw new Error("verifier must not be called");
+	});
+	const event = buildEvent({
+		requestContext: {
+			authorizer: { claims: { sub: "edge-user" } },
+		} as unknown as APIGatewayProxyEvent["requestContext"],
+	});
+
+	const result = await authenticatePostgresRequest(event);
+
+	assert.equal(result, null);
+	assert.equal(event.requestContext.authorizer?.claims?.sub, "edge-user");
+});

package/src/jwt-auth.ts

@@ -0,0 +1,95 @@
+import {
+	createJwtVerifier,
+	extractBearerToken,
+	type JwtVerifier,
+	resolveVerifierConfig,
+} from "@remit/auth-service/verifier";
+import { logger } from "@remit/logger-lambda";
+import type { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
+
+let verifier: JwtVerifier | null = null;
+
+const getVerifier = (): JwtVerifier => {
+	if (!verifier) verifier = createJwtVerifier(resolveVerifierConfig());
+	return verifier;
+};
+
+/** Test-only override for the memoized verifier. Pass null to reset. */
+export const _setVerifierForTest = (v: JwtVerifier | null): void => {
+	verifier = v;
+};
+
+const readHeader = (
+	headers: APIGatewayProxyEvent["headers"],
+	name: string,
+): string | undefined => {
+	for (const [key, value] of Object.entries(headers ?? {})) {
+		if (key.toLowerCase() === name && typeof value === "string") return value;
+	}
+	return undefined;
+};
+
+const unauthorized = (message: string): APIGatewayProxyResult => ({
+	statusCode: 401,
+	headers: { "Content-Type": "application/json" },
+	body: JSON.stringify({ message }),
+});
+
+const injectClaims = (
+	event: APIGatewayProxyEvent,
+	sub: string,
+	email: string | undefined,
+): void => {
+	event.requestContext = {
+		...event.requestContext,
+		authorizer: {
+			...event.requestContext?.authorizer,
+			claims: {
+				sub,
+				email: email ?? "",
+			},
+		},
+	};
+};
+
+const hasLocalBypass = (): boolean =>
+	Boolean(process.env.LOCAL_ACCOUNT_CONFIG_ID);
+
+/**
+ * Authenticate a Postgres-mode request from a better-auth RS256 JWT.
+ *
+ * On a valid token the verified `sub` is injected into the event's authorizer
+ * claims, exactly where the Cognito authorizer puts it, so every downstream
+ * handler reads identity through the unchanged `auth.ts` path. Returns a 401
+ * response (not null) when a token is present but fails verification, or when no
+ * token is supplied and no local test bypass is configured. Returns null to let
+ * the request proceed.
+ *
+ * When the edge tier (APISIX) has already verified and injected claims, this is
+ * a no-op — the backend trusts pre-populated claims and re-verifies otherwise.
+ */
+export const authenticatePostgresRequest = async (
+	event: APIGatewayProxyEvent,
+): Promise<APIGatewayProxyResult | null> => {
+	const existingSub = event.requestContext?.authorizer?.claims?.sub;
+	if (typeof existingSub === "string" && existingSub.length > 0) return null;
+
+	const token = extractBearerToken(readHeader(event.headers, "authorization"));
+
+	if (token) {
+		const claims = await getVerifier()(token).catch((err: unknown) => {
+			logger.warn(
+				{ err: err instanceof Error ? err.message : String(err) },
+				"better-auth JWT verification failed",
+			);
+			return null;
+		});
+		if (!claims) return unauthorized("Invalid or expired token");
+		injectClaims(event, claims.sub, claims.email);
+		return null;
+	}
+
+	if (hasLocalBypass()) return null;
+
+	return unauthorized("Authentication required");
+};

package/src/request-context.test.ts

@@ -0,0 +1,61 @@
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import {
+	getRequestOrigin,
+	resolveAllowedOrigin,
+	runWithRequestContext,
+} from "./request-context.js";
+
+describe("request-context", () => {
+	const originalEnv = process.env.CORS_ALLOWED_ORIGINS;
+
+	afterEach(() => {
+		if (originalEnv === undefined) {
+			process.env.CORS_ALLOWED_ORIGINS = undefined;
+			process.env.CORS_ALLOWED_ORIGINS = "";
+			delete process.env.CORS_ALLOWED_ORIGINS;
+		} else {
+			process.env.CORS_ALLOWED_ORIGINS = originalEnv;
+		}
+	});
+
+	it("stores and retrieves the request origin", () => {
+		runWithRequestContext({ origin: "https://example.com" }, () => {
+			assert.equal(getRequestOrigin(), "https://example.com");
+		});
+	});
+
+	it("returns undefined when no origin is set", () => {
+		runWithRequestContext({}, () => {
+			assert.equal(getRequestOrigin(), undefined);
+		});
+	});
+
+	it("returns star when no allow-list is configured", () => {
+		delete process.env.CORS_ALLOWED_ORIGINS;
+		assert.equal(resolveAllowedOrigin("https://any.com"), "*");
+	});
+
+	it("reflects the request origin when it is allow-listed", () => {
+		process.env.CORS_ALLOWED_ORIGINS =
+			"https://app.example.com,http://localhost:5173";
+		assert.equal(
+			resolveAllowedOrigin("http://localhost:5173"),
+			"http://localhost:5173",
+		);
+	});
+
+	it("falls back to the first allowed origin when the request origin is not allow-listed", () => {
+		process.env.CORS_ALLOWED_ORIGINS =
+			"https://app.example.com,http://localhost:5173";
+		assert.equal(
+			resolveAllowedOrigin("https://evil.example.com"),
+			"https://app.example.com",
+		);
+	});
+
+	it("falls back to the first allowed origin when no request origin is provided", () => {
+		process.env.CORS_ALLOWED_ORIGINS = "https://app.example.com";
+		assert.equal(resolveAllowedOrigin(undefined), "https://app.example.com");
+	});
+});

package/src/request-context.ts

@@ -0,0 +1,29 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+interface RequestContext {
+	origin?: string;
+}
+
+const storage = new AsyncLocalStorage<RequestContext>();
+
+export const runWithRequestContext = <T>(ctx: RequestContext, fn: () => T): T =>
+	storage.run(ctx, fn);
+
+export const getRequestOrigin = (): string | undefined =>
+	storage.getStore()?.origin;
+
+const parseAllowedOrigins = (): readonly string[] => {
+	const raw = process.env.CORS_ALLOWED_ORIGINS;
+	if (!raw) return [];
+	return raw
+		.split(",")
+		.map((s) => s.trim())
+		.filter((s) => s.length > 0);
+};
+
+export const resolveAllowedOrigin = (origin: string | undefined): string => {
+	const allowed = parseAllowedOrigins();
+	if (allowed.length === 0) return "*";
+	if (origin && allowed.includes(origin)) return origin;
+	return allowed[0];
+};

package/src/request.ts

@@ -0,0 +1,10 @@
+import type { APIGatewayProxyEvent } from "aws-lambda";
+import type { Request } from "openapi-backend";
+
+export const normalizeRequest = (event: APIGatewayProxyEvent): Request => ({
+	method: event.httpMethod,
+	path: event.path,
+	query: (event.queryStringParameters ?? {}) as Record<string, string>,
+	body: event.body,
+	headers: (event.headers ?? {}) as Record<string, string>,
+});

package/src/response.test.ts

@@ -0,0 +1,107 @@
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import type { Context as OpenAPIContext } from "openapi-backend";
+import { postResponseHandler } from "./response.js";
+
+type ValidateResponseFn = (
+	response: unknown,
+	operation: unknown,
+) => { valid: boolean; errors?: { instancePath?: string; message?: string }[] };
+
+const makeContext = (
+	response: Record<string, unknown>,
+	validateResponse: ValidateResponseFn,
+): OpenAPIContext => {
+	return {
+		api: { validateResponse },
+		response,
+		operation: { operationId: "testOp" },
+	} as unknown as OpenAPIContext;
+};
+
+describe("postResponseHandler validation gating", () => {
+	const originalStage = process.env.STAGE_NAME;
+
+	beforeEach(() => {
+		delete process.env.STAGE_NAME;
+	});
+
+	afterEach(() => {
+		if (originalStage === undefined) {
+			delete process.env.STAGE_NAME;
+		} else {
+			process.env.STAGE_NAME = originalStage;
+		}
+	});
+
+	it("runs validateResponse when STAGE_NAME is 'dev'", () => {
+		process.env.STAGE_NAME = "dev";
+		let called = false;
+		const validate: ValidateResponseFn = () => {
+			called = true;
+			return { valid: true };
+		};
+		const result = postResponseHandler(makeContext({ items: [] }, validate));
+		assert.equal(called, true);
+		assert.equal(result.statusCode, 200);
+	});
+
+	it("skips validateResponse when STAGE_NAME is 'prod'", () => {
+		process.env.STAGE_NAME = "prod";
+		let called = false;
+		const validate: ValidateResponseFn = () => {
+			called = true;
+			return { valid: true };
+		};
+		const result = postResponseHandler(makeContext({ items: [] }, validate));
+		assert.equal(called, false);
+		assert.equal(result.statusCode, 200);
+	});
+
+	it("skips validateResponse when STAGE_NAME is 'beta'", () => {
+		process.env.STAGE_NAME = "beta";
+		let called = false;
+		const validate: ValidateResponseFn = () => {
+			called = true;
+			return { valid: true };
+		};
+		postResponseHandler(makeContext({ items: [] }, validate));
+		assert.equal(called, false);
+	});
+
+	it("skips validateResponse when STAGE_NAME is unset", () => {
+		let called = false;
+		const validate: ValidateResponseFn = () => {
+			called = true;
+			return { valid: true };
+		};
+		postResponseHandler(makeContext({ items: [] }, validate));
+		assert.equal(called, false);
+	});
+
+	it("returns the formatted error response when statusCode is set, regardless of stage", () => {
+		process.env.STAGE_NAME = "dev";
+		let called = false;
+		const validate: ValidateResponseFn = () => {
+			called = true;
+			return { valid: true };
+		};
+		const result = postResponseHandler(
+			makeContext({ statusCode: 404, message: "Not Found" }, validate),
+		);
+		assert.equal(called, false);
+		assert.equal(result.statusCode, 404);
+	});
+
+	it("returns 200 with the response body when validation fails in dev", () => {
+		process.env.STAGE_NAME = "dev";
+		const validate: ValidateResponseFn = () => ({
+			valid: false,
+			errors: [{ instancePath: "/items/0/id", message: "must be string" }],
+		});
+		const result = postResponseHandler(
+			makeContext({ items: [{ id: 42 }] }, validate),
+		);
+		assert.equal(result.statusCode, 200);
+	});
+});

package/src/response.ts

@@ -0,0 +1,80 @@
+import { logger } from "@remit/logger-lambda";
+import type { APIGatewayProxyResult } from "aws-lambda";
+import type { Context as OpenAPIContext } from "openapi-backend";
+import { getRequestOrigin, resolveAllowedOrigin } from "./request-context.js";
+
+export const formatResponse = (
+	body: Record<string, unknown>,
+	statusCode = 200,
+): APIGatewayProxyResult => {
+	if (body.statusCode && typeof body.statusCode === "number") {
+		statusCode = body.statusCode;
+	}
+
+	if ("body" in body && body.body && typeof body.body === "object") {
+		body = body.body as Record<string, unknown>;
+	}
+
+	logger.debug({ statusCode }, "response");
+
+	const allowOrigin = resolveAllowedOrigin(getRequestOrigin());
+
+	const corsHeaders: Record<string, string> = {
+		"Access-Control-Allow-Origin": allowOrigin,
+		"Access-Control-Allow-Headers": "Authorization,Content-Type",
+		"Access-Control-Allow-Methods": "GET,POST,PUT,PATCH,DELETE,OPTIONS",
+		Vary: "Origin",
+	};
+
+	if (allowOrigin !== "*") {
+		corsHeaders["Access-Control-Allow-Credentials"] = "true";
+	}
+
+	return {
+		statusCode: statusCode,
+		headers: {
+			"Content-Type": "application/json",
+			...corsHeaders,
+		},
+		body: JSON.stringify(body),
+	};
+};
+
+export const postResponseHandler = (context: OpenAPIContext) => {
+	const { api, response, operation } = context;
+
+	if (response.statusCode) return formatResponse(response, response.statusCode);
+
+	if (process.env.STAGE_NAME !== "dev") return formatResponse(response, 200);
+
+	const { valid, errors } = api.validateResponse(response, operation);
+
+	if (valid) return formatResponse(response, 200);
+
+	const { operationId } = operation;
+
+	const errorDetails: Record<string, unknown> = {
+		errors,
+		operationId,
+		responseKeys: Object.keys(response),
+	};
+
+	errors?.forEach((error) => {
+		if (error.instancePath) {
+			const pathParts = error.instancePath.split("/").filter(Boolean);
+			let value = response;
+			for (const part of pathParts) {
+				value = value?.[part];
+			}
+			errorDetails[`problematicValue_${error.instancePath}`] = {
+				path: error.instancePath,
+				value: JSON.stringify(value).substring(0, 500),
+				error: error.message,
+			};
+		}
+	});
+
+	logger.error(errorDetails, "Response validation failed");
+
+	return formatResponse(response, 200);
+};