@remit/backend 0.0.1

package/.env.test

@@ -0,0 +1,7 @@
+SERVER_PORT=5433
+DYNAMODB_PORT=5434
+DYNAMODB_TABLE_NAME=remit-local
+DYNAMODB_PAGINATION_SALT=test-salt
+SQS_QUEUE_URL=http://localhost:9324/queue/remit-local
+NODE_ENV=development
+LOG_LEVEL=debug

package/dev-server/content-auth.test.ts

@@ -0,0 +1,113 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createContentSigner } from "../src/derive/contentSignature.js";
+import { authorizeContentRequest } from "./content-auth.js";
+
+const SECRET = "test-master-secret-at-least-32-chars-long";
+const PATH = "accounts/cfg-alice/acc-alice/messages/msg-1/parts/1.2";
+const now = () => Math.floor(Date.now() / 1000);
+
+describe("authorizeContentRequest", () => {
+	it("is a no-op outside Postgres mode (AWS serves unsigned URLs)", () => {
+		const result = authorizeContentRequest({
+			dataBackend: undefined,
+			secret: undefined,
+			relativePath: PATH,
+			exp: undefined,
+			sig: undefined,
+			nowSeconds: now(),
+		});
+		assert.deepEqual(result, { authorized: true });
+	});
+
+	it("authorizes a validly signed request in Postgres mode", () => {
+		const { exp, sig } = createContentSigner(SECRET)(PATH);
+		const result = authorizeContentRequest({
+			dataBackend: "postgres",
+			secret: SECRET,
+			relativePath: PATH,
+			exp: String(exp),
+			sig,
+			nowSeconds: now(),
+		});
+		assert.deepEqual(result, { authorized: true });
+	});
+
+	it("returns 401 when the signature is absent", () => {
+		const result = authorizeContentRequest({
+			dataBackend: "postgres",
+			secret: SECRET,
+			relativePath: PATH,
+			exp: undefined,
+			sig: undefined,
+			nowSeconds: now(),
+		});
+		assert.equal(result.authorized, false);
+		assert.equal(result.authorized === false && result.status, 401);
+	});
+
+	it("returns 403 for a signature minted for another account's path", () => {
+		const { exp, sig } = createContentSigner(SECRET)(PATH);
+		const result = authorizeContentRequest({
+			dataBackend: "postgres",
+			secret: SECRET,
+			relativePath: "accounts/cfg-bob/acc-bob/messages/msg-9/parts/1.2",
+			exp: String(exp),
+			sig,
+			nowSeconds: now(),
+		});
+		assert.equal(result.authorized, false);
+		assert.equal(result.authorized === false && result.status, 403);
+	});
+
+	it("returns 403 for an expired signature", () => {
+		const { exp, sig } = createContentSigner(SECRET, -20)(PATH);
+		const result = authorizeContentRequest({
+			dataBackend: "postgres",
+			secret: SECRET,
+			relativePath: PATH,
+			exp: String(exp),
+			sig,
+			nowSeconds: now(),
+		});
+		assert.equal(result.authorized, false);
+		assert.equal(result.authorized === false && result.status, 403);
+	});
+
+	it("fails closed with 500 in Postgres mode when no signing secret is configured", () => {
+		const result = authorizeContentRequest({
+			dataBackend: "postgres",
+			secret: undefined,
+			relativePath: PATH,
+			exp: "123",
+			sig: "whatever",
+			nowSeconds: now(),
+		});
+		assert.equal(result.authorized, false);
+		assert.equal(result.authorized === false && result.status, 500);
+	});
+
+	it("enforces signatures in SQLite mode the same as Postgres", () => {
+		const { exp, sig } = createContentSigner(SECRET)(PATH);
+		const valid = authorizeContentRequest({
+			dataBackend: "sqlite",
+			secret: SECRET,
+			relativePath: PATH,
+			exp: String(exp),
+			sig,
+			nowSeconds: now(),
+		});
+		assert.deepEqual(valid, { authorized: true });
+
+		const unsigned = authorizeContentRequest({
+			dataBackend: "sqlite",
+			secret: SECRET,
+			relativePath: PATH,
+			exp: undefined,
+			sig: undefined,
+			nowSeconds: now(),
+		});
+		assert.equal(unsigned.authorized, false);
+		assert.equal(unsigned.authorized === false && unsigned.status, 401);
+	});
+});

package/dev-server/content-auth.ts

@@ -0,0 +1,54 @@
+import { verifyContentSignature } from "../src/derive/contentSignature.js";
+
+/**
+ * Decide whether a `/content` request is authorized. Enforcement applies on the
+ * self-host SQL backends (postgres and sqlite), where this server is the
+ * deployed backend container and content URLs are signed. On AWS-local dev
+ * (`DATA_BACKEND` unset) `/content` is served straight from the filesystem
+ * stand-in for CloudFront and URLs are unsigned, so the check is a no-op.
+ *
+ * Pure so the decision can be unit-tested without a live server. `relativePath`
+ * is the decoded storage path (`accounts/{cfg}/{acc}/messages/{msg}/parts/{part}`)
+ * the signature was minted over — the caller strips the `/content/` prefix.
+ */
+export interface AuthorizeContentInput {
+	dataBackend: string | undefined;
+	secret: string | undefined;
+	relativePath: string;
+	exp: string | undefined;
+	sig: string | undefined;
+	nowSeconds: number;
+}
+
+export const authorizeContentRequest = (
+	input: AuthorizeContentInput,
+):
+	| { authorized: true }
+	| { authorized: false; status: number; reason: string } => {
+	if (input.dataBackend !== "postgres" && input.dataBackend !== "sqlite") {
+		return { authorized: true };
+	}
+
+	if (!input.secret || input.secret.length === 0) {
+		// A self-host SQL backend with no signing secret means every content URL
+		// is unsigned and unverifiable. Fail closed rather than serve mail bytes
+		// without auth.
+		return {
+			authorized: false,
+			status: 500,
+			reason: "content-signing-not-configured",
+		};
+	}
+
+	const result = verifyContentSignature(
+		input.relativePath,
+		input.exp,
+		input.sig,
+		input.secret,
+		input.nowSeconds,
+	);
+	if (result.valid) return { authorized: true };
+
+	const status = result.reason === "missing" ? 401 : 403;
+	return { authorized: false, status, reason: result.reason };
+};

package/dev-server/content-handler.test.ts

@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { gzipSync } from "node:zlib";
+import {
+	parseContentStorageKey,
+	type ServeContentDeps,
+	serveContent,
+} from "./content-handler.js";
+
+const PART_KEY = "accounts/cfg-1/acc-1/messages/msg-1/parts/1.2";
+
+const baseDeps = (
+	over: Partial<ServeContentDeps> = {},
+): { deps: ServeContentDeps; cues: Array<Record<string, unknown>> } => {
+	const cues: Array<Record<string, unknown>> = [];
+	const deps: ServeContentDeps = {
+		readObject: async () => null,
+		lookupMessage: async () => ({ mailboxId: "mbx-1", uid: 42 }),
+		requestBodySync: async (input) => {
+			cues.push(input);
+		},
+		...over,
+	};
+	return { deps, cues };
+};
+
+describe("parseContentStorageKey", () => {
+	it("extracts account + message ids from a part key", () => {
+		assert.deepEqual(parseContentStorageKey(PART_KEY), {
+			accountConfigId: "cfg-1",
+			accountId: "acc-1",
+			messageId: "msg-1",
+		});
+	});
+
+	it("returns null for a non-matching key", () => {
+		assert.equal(parseContentStorageKey("nope/whatever"), null);
+	});
+});
+
+describe("serveContent", () => {
+	it("returns 200 with decompressed bytes when the object is present", async () => {
+		const { deps, cues } = baseDeps({
+			readObject: async () => gzipSync(Buffer.from("hello body")),
+		});
+
+		const result = await serveContent(deps, {
+			fullPath: "/x/parts/1.2",
+			storageKey: PART_KEY,
+		});
+
+		assert.equal(result.status, 200);
+		assert.equal(result.headers["content-type"], "application/octet-stream");
+		assert.equal(result.body.toString(), "hello body");
+		assert.equal(cues.length, 0);
+	});
+
+	it("returns 202 + Retry-After and re-arms the cue when the object is missing", async () => {
+		const { deps, cues } = baseDeps({ readObject: async () => null });
+
+		const result = await serveContent(deps, {
+			fullPath: "/x/parts/1.2",
+			storageKey: PART_KEY,
+		});
+
+		assert.equal(result.status, 202);
+		assert.equal(result.headers["Retry-After"], "1");
+		assert.equal(cues.length, 1, "cue re-armed exactly once");
+		assert.deepEqual(cues[0], {
+			accountId: "acc-1",
+			mailboxId: "mbx-1",
+			messageId: "msg-1",
+			uid: 42,
+		});
+	});
+
+	it("still answers 202 (no cue) when the message row is gone", async () => {
+		const { deps, cues } = baseDeps({
+			readObject: async () => null,
+			lookupMessage: async () => null,
+		});
+
+		const result = await serveContent(deps, {
+			fullPath: "/x/parts/1.2",
+			storageKey: PART_KEY,
+		});
+
+		assert.equal(result.status, 202);
+		assert.equal(cues.length, 0);
+	});
+
+	it("propagates a non-missing read error so the route 500s", async () => {
+		const { deps } = baseDeps({
+			readObject: async () => {
+				throw new Error("EACCES");
+			},
+		});
+
+		await assert.rejects(
+			() =>
+				serveContent(deps, { fullPath: "/x/parts/1.2", storageKey: PART_KEY }),
+			/EACCES/,
+		);
+	});
+});

package/dev-server/content-handler.ts

@@ -0,0 +1,79 @@
+import { gunzipSync } from "node:zlib";
+import { parseContentStorageKey } from "@remit/storage-service";
+
+// Re-exported for existing same-package consumers (server.ts,
+// content-handler.test.ts). The key-shape parser itself lives in
+// `@remit/storage-service` next to the `build*Key` functions it
+// inverts, so non-backend consumers (e.g. the content-selfheal worker) can
+// depend on it without pulling in the rest of `@remit/backend`.
+export { parseContentStorageKey };
+
+export interface ContentResult {
+	status: number;
+	headers: Record<string, string>;
+	body: string | Buffer;
+}
+
+export interface ServeContentDeps {
+	/**
+	 * Reads the stored bytes, or returns null when the object is genuinely
+	 * missing (ENOENT / NoSuchKey). Any other read error must throw so the route
+	 * 500s — a permission/infra failure is never masked as a missing body.
+	 */
+	readObject(fullPath: string): Promise<Buffer | null>;
+	/** Resolves the message's mailbox + uid so the cue can issue one FETCH. */
+	lookupMessage(
+		messageId: string,
+	): Promise<{ mailboxId: string; uid: number } | null>;
+	requestBodySync(input: {
+		accountId: string;
+		mailboxId: string;
+		messageId: string;
+		uid?: number;
+	}): Promise<void>;
+}
+
+/**
+ * Local stand-in for the CloudFront `/content/*` behavior. Body-fetch outcomes:
+ *
+ * - Object present → 200 with the (decompressed) bytes.
+ * - Object missing → 202 + `Retry-After: 1`, and re-arm the SYNC_MESSAGE_BODY
+ *   cue for that message so a retry succeeds once the worker stores the body.
+ * - Any other read failure throws, so the route 500s loudly.
+ */
+export const serveContent = async (
+	deps: ServeContentDeps,
+	args: { fullPath: string; storageKey: string },
+): Promise<ContentResult> => {
+	const raw = await deps.readObject(args.fullPath);
+
+	if (raw) {
+		// The filesystem/S3 backends gzip every part; decompress here since there
+		// is no CloudFront to auto-decode locally.
+		const buffer = raw[0] === 0x1f && raw[1] === 0x8b ? gunzipSync(raw) : raw;
+		return {
+			status: 200,
+			headers: { "content-type": "application/octet-stream" },
+			body: buffer,
+		};
+	}
+
+	const ids = parseContentStorageKey(args.storageKey);
+	if (ids) {
+		const message = await deps.lookupMessage(ids.messageId);
+		if (message) {
+			await deps.requestBodySync({
+				accountId: ids.accountId,
+				mailboxId: message.mailboxId,
+				messageId: ids.messageId,
+				uid: message.uid,
+			});
+		}
+	}
+
+	return {
+		status: 202,
+		headers: { "Retry-After": "1" },
+		body: "body not yet synced",
+	};
+};

package/dev-server/content-path.test.ts

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import { sep } from "node:path";
+import { describe, it } from "node:test";
+import { resolveContentPath } from "./content-path.js";
+
+describe("resolveContentPath — dev-server /content/* path safety (#310 review P1)", () => {
+	const ROOT = "/x/storage";
+
+	it("returns the absolute path for a normal nested storage key", () => {
+		assert.equal(
+			resolveContentPath(ROOT, "accounts/cfg/acc/messages/m/parts/1"),
+			"/x/storage/accounts/cfg/acc/messages/m/parts/1",
+		);
+	});
+
+	it("rejects a sibling-prefix escape (`startsWith` was the original bug)", () => {
+		// `/x/storage-evil/y` shares the prefix `/x/storage` with the root,
+		// so the naive `fullPath.startsWith(ROOT)` check would pass it.
+		assert.equal(resolveContentPath(ROOT, `..${sep}storage-evil${sep}y`), null);
+	});
+
+	it("rejects parent-directory traversal via `..`", () => {
+		assert.equal(resolveContentPath(ROOT, `..${sep}etc${sep}passwd`), null);
+		assert.equal(
+			resolveContentPath(ROOT, `accounts${sep}..${sep}..${sep}etc`),
+			null,
+		);
+	});
+
+	it("rejects an absolute key that resolves outside the root", () => {
+		assert.equal(resolveContentPath(ROOT, "/etc/passwd"), null);
+	});
+
+	it("rejects an empty key (would expose the root listing)", () => {
+		assert.equal(resolveContentPath(ROOT, ""), null);
+	});
+});

package/dev-server/content-path.ts

@@ -0,0 +1,27 @@
+import { relative, resolve, sep } from "node:path";
+
+/**
+ * Resolve a `/content/*` URL path to an absolute filesystem path under the
+ * storage root, or return null if the resolved path would escape the root.
+ *
+ * The naive `fullPath.startsWith(STORAGE_BASE)` check fails on a sibling
+ * directory whose name is a prefix of the base — e.g. `/x/storage` and
+ * `/x/storage-evil` — so we use `path.relative` and reject any result that
+ * starts with `..` or is itself absolute (#310 review P1). Empty keys are
+ * also rejected so the root directory is never served.
+ */
+export const resolveContentPath = (
+	storageBase: string,
+	storageKey: string,
+): string | null => {
+	const fullPath = resolve(storageBase, storageKey);
+	const rel = relative(storageBase, fullPath);
+	if (rel === "" || rel.startsWith("..") || rel.includes(`..${sep}`)) {
+		return null;
+	}
+	if (resolve(rel) === rel) {
+		// `rel` is absolute → escaped the root via an absolute storageKey.
+		return null;
+	}
+	return fullPath;
+};

package/dev-server/cors.test.ts

@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { parseAllowedOrigins, resolveAllowOrigin } from "./cors.js";
+
+describe("parseAllowedOrigins", () => {
+	it("splits, trims, and drops empties", () => {
+		assert.deepEqual(
+			parseAllowedOrigins("https://a.example, https://b.example ,"),
+			["https://a.example", "https://b.example"],
+		);
+	});
+
+	it("returns an empty list for undefined or blank", () => {
+		assert.deepEqual(parseAllowedOrigins(undefined), []);
+		assert.deepEqual(parseAllowedOrigins("  "), []);
+	});
+});
+
+describe("resolveAllowOrigin", () => {
+	it("returns '*' when the allowlist contains a wildcard", () => {
+		assert.equal(resolveAllowOrigin("https://any.example", ["*"]), "*");
+		assert.equal(resolveAllowOrigin(undefined, ["*"]), "*");
+	});
+
+	it("reflects an allowlisted origin", () => {
+		assert.equal(
+			resolveAllowOrigin("https://app.example", [
+				"https://app.example",
+				"https://other.example",
+			]),
+			"https://app.example",
+		);
+	});
+
+	it("returns undefined for an origin outside the allowlist", () => {
+		assert.equal(
+			resolveAllowOrigin("https://evil.example", ["https://app.example"]),
+			undefined,
+		);
+	});
+
+	it("returns undefined when no origin is presented and no wildcard", () => {
+		assert.equal(
+			resolveAllowOrigin(undefined, ["https://app.example"]),
+			undefined,
+		);
+	});
+});

package/dev-server/cors.ts

@@ -0,0 +1,25 @@
+export const parseAllowedOrigins = (raw: string | undefined): string[] =>
+	(raw ?? "")
+		.split(",")
+		.map((origin) => origin.trim())
+		.filter((origin) => origin.length > 0);
+
+/**
+ * Resolve the `Access-Control-Allow-Origin` value for a request against the
+ * configured allowlist.
+ *
+ * - a `*` entry allows any origin (browsers reject `*` with credentials, so this
+ *   stays safe for a bearer-token API);
+ * - otherwise the request `Origin` is reflected only when it is in the allowlist;
+ * - an origin outside the allowlist yields `undefined` — no CORS header is sent.
+ */
+export const resolveAllowOrigin = (
+	requestOrigin: string | undefined,
+	allowedOrigins: string[],
+): string | undefined => {
+	if (allowedOrigins.includes("*")) return "*";
+	if (requestOrigin && allowedOrigins.includes(requestOrigin)) {
+		return requestOrigin;
+	}
+	return undefined;
+};

package/dev-server/lambda-helpers.ts

@@ -0,0 +1,69 @@
+import type {
+	APIGatewayProxyEvent,
+	APIGatewayProxyEventPathParameters,
+	Context,
+} from "aws-lambda";
+import type { Request } from "express";
+
+export const createLambdaEvent = (req: Request): APIGatewayProxyEvent => ({
+	httpMethod: req.method,
+	path: req.path,
+	pathParameters: (req.params as APIGatewayProxyEventPathParameters) || null,
+	queryStringParameters: (req.query as { [name: string]: string }) || null,
+	headers: (req.headers as { [name: string]: string }) || {},
+	body: req.body ? JSON.stringify(req.body) : null,
+	isBase64Encoded: false,
+	requestContext: {
+		requestId: `local-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+		stage: "local",
+		httpMethod: req.method,
+		path: req.path,
+		protocol: "HTTP/1.1",
+		requestTime: new Date().toISOString(),
+		requestTimeEpoch: Date.now(),
+		identity: {
+			sourceIp: req.ip || "127.0.0.1",
+			userAgent: req.get("User-Agent") || "local-test",
+			accessKey: null,
+			accountId: null,
+			apiKey: null,
+			apiKeyId: null,
+			caller: null,
+			cognitoAuthenticationProvider: null,
+			cognitoAuthenticationType: null,
+			cognitoIdentityId: null,
+			cognitoIdentityPoolId: null,
+			principalOrgId: null,
+			user: null,
+			userArn: null,
+			clientCert: null,
+		},
+		accountId: "123456789012",
+		apiId: "local",
+		domainName: "localhost",
+		domainPrefix: "local",
+		resourceId: "local",
+		resourcePath: req.path,
+		authorizer: undefined,
+	},
+	resource: req.path,
+	multiValueHeaders: {},
+	multiValueQueryStringParameters: null,
+	stageVariables: null,
+});
+
+export const createLambdaContext = (): Context => ({
+	callbackWaitsForEmptyEventLoop: false,
+	functionName: "remit-backend-local",
+	functionVersion: "$LATEST",
+	invokedFunctionArn:
+		"arn:aws:lambda:local:123456789012:function:remit-backend-local",
+	memoryLimitInMB: "128",
+	awsRequestId: `local-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+	logGroupName: "/aws/lambda/remit-backend-local",
+	logStreamName: `${new Date().toISOString().split("T")[0]}/[$LATEST]${Math.random().toString(36).substr(2, 9)}`,
+	getRemainingTimeInMillis: () => 30000,
+	done: () => {},
+	fail: () => {},
+	succeed: () => {},
+});