@remit/backend 0.0.1

package/dev-server/server.ts

@@ -0,0 +1,289 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { isStorageNotFoundError } from "@remit/storage-service";
+import type { APIGatewayProxyResult } from "aws-lambda";
+import { env } from "expect-env";
+import express, {
+	type NextFunction,
+	type Request,
+	type Response,
+} from "express";
+import { handler, OpenAPISpec } from "../src/index.js";
+import { safeJsonParse } from "../src/json.js";
+import { getClient } from "../src/service/dynamodb.js";
+import { authorizeContentRequest } from "./content-auth.js";
+import { serveContent } from "./content-handler.js";
+import { resolveContentPath } from "./content-path.js";
+import { parseAllowedOrigins, resolveAllowOrigin } from "./cors.js";
+import { createLambdaContext, createLambdaEvent } from "./lambda-helpers.js";
+
+const app = express();
+
+// The self-host relational backends — Postgres and, from RFC 036, SQLite — both
+// run better-auth and the APISIX edge; the AWS-local (DynamoDB) dev path runs
+// neither. Everything gated on "not the AWS-local path" keys off this.
+const isSelfHostBackend =
+	process.env.DATA_BACKEND === "postgres" ||
+	process.env.DATA_BACKEND === "sqlite";
+
+// CORS is driven by CORS_ALLOWED_ORIGINS (comma-separated, or `*`). On the
+// self-host backends it is required config — refuse to start if unset, so the
+// deployed edge is never accidentally wide open by omission. On the AWS-local
+// dev path it defaults to `*` to keep the existing local flow working.
+const configuredCorsOrigins = parseAllowedOrigins(
+	process.env.CORS_ALLOWED_ORIGINS,
+);
+if (isSelfHostBackend && configuredCorsOrigins.length === 0) {
+	throw new Error(
+		"Missing required env var CORS_ALLOWED_ORIGINS (comma-separated origins, or '*')",
+	);
+}
+const corsAllowedOrigins =
+	configuredCorsOrigins.length > 0 ? configuredCorsOrigins : ["*"];
+
+// better-auth owns identity on the self-host backends. Its handler must be
+// mounted BEFORE express.json() (better-auth reads the raw body itself; a prior
+// json parser leaves its fetch calls hanging). This mirrors the production edge
+// where the same better-auth service sits in front of the API.
+if (isSelfHostBackend) {
+	// Synthetic OIDC discovery document for the APISIX edge tier. better-auth
+	// serves a JWKS but not a discovery doc; APISIX's openid-connect plugin needs
+	// one to locate the JWKS. Registered before the better-auth catch-all so it
+	// is not shadowed. `issuer` matches the token `iss`, so it stays the public
+	// BETTER_AUTH_URL. `jwks_uri` is different: APISIX fetches it directly, and
+	// on a deployment where the public origin isn't reachable from inside the
+	// container network (a tailnet/VPN address a bridge network can't route to
+	// — the shape deploy/vps's compose stack runs in), deriving it from
+	// BETTER_AUTH_URL would point APISIX at an address it cannot reach, even
+	// though it just reached this very endpoint fine.
+	//
+	// BETTER_AUTH_JWKS_URL — the same in-network override
+	// remit-auth-service's own verifier config already reads
+	// (packages/auth-service/src/config.ts) and every env file sets to
+	// the backend's in-network address — is authoritative here, not the
+	// incoming request's Host header: an operator-controlled value instead
+	// of one derived from client-supplied input. It only falls back to
+	// echoing the request's own host when unset, matching prior behavior
+	// for any environment that doesn't set it.
+	app.get(
+		"/api/auth/.well-known/openid-configuration",
+		(req: Request, res: Response) => {
+			const base =
+				process.env.BETTER_AUTH_URL ??
+				`http://localhost:${process.env.SERVER_PORT ?? "5436"}`;
+			const jwksUri =
+				process.env.BETTER_AUTH_JWKS_URL ??
+				`${req.protocol}://${req.get("host")}/api/auth/jwks`;
+			res.json({
+				issuer: base,
+				jwks_uri: jwksUri,
+				authorization_endpoint: `${base}/api/auth/authorize`,
+				token_endpoint: `${base}/api/auth/token`,
+				response_types_supported: ["token"],
+				subject_types_supported: ["public"],
+				id_token_signing_alg_values_supported: ["RS256"],
+			});
+		},
+	);
+
+	const { createAuth, resolveAuthConfig, toNodeHandler } = await import(
+		"@remit/auth-service"
+	);
+	const auth = await createAuth(resolveAuthConfig());
+	app.all(/^\/api\/auth\//, toNodeHandler(auth));
+}
+
+app.use(express.json({ limit: "10mb" }));
+app.use(express.urlencoded({ extended: true }));
+
+app.use((req: Request, res: Response, next: NextFunction) => {
+	const allowOrigin = resolveAllowOrigin(
+		req.headers.origin,
+		corsAllowedOrigins,
+	);
+	if (allowOrigin) {
+		res.header("Access-Control-Allow-Origin", allowOrigin);
+		if (allowOrigin !== "*") res.header("Vary", "Origin");
+	}
+	res.header(
+		"Access-Control-Allow-Methods",
+		"GET, POST, PUT, DELETE, OPTIONS, PATCH",
+	);
+	res.header(
+		"Access-Control-Allow-Headers",
+		"Origin, X-Requested-With, Content-Type, Accept, Authorization",
+	);
+
+	if (req.method === "OPTIONS") {
+		res.sendStatus(200);
+	} else {
+		next();
+	}
+});
+
+app.get("/.well-known/appspecific/com.chrome.devtools.json", () => ({}));
+
+app.get("/health", (_req: Request, res: Response) => {
+	res.json({
+		status: "ok",
+		timestamp: new Date().toISOString(),
+		service: "remit-backend-local",
+	});
+});
+
+// Swagger UI exposes the full API schema, so it must never be on the public
+// surface. On the self-host backends this server is the deployed backend
+// container; gate the docs to the AWS-local dev path only. The generated
+// OpenAPI document is still consumed programmatically by the APISIX edge via its
+// own mounted paths — this only removes the browsable UI from the deployed
+// surface.
+//
+// Dynamic import, not a static one: swagger-ui-express uses `__dirname` to
+// locate its bundled assets on disk, which esbuild only shims (not
+// eliminates) for an unconditional top-level import — that shim plus this
+// file's own top-level `await import("@remit/auth-service")` above
+// makes the bundle's module format ambiguous to Node
+// (`ERR_AMBIGUOUS_MODULE_SYNTAX`), crashing every backend container start,
+// including the ones that never take this branch. A dynamic import here
+// keeps swagger-ui-express (and its `__dirname` shim) out of module scope
+// entirely unless this is the AWS-local dev path.
+if (!isSelfHostBackend) {
+	const swaggerUi = await import("swagger-ui-express");
+	const localSpec = { ...OpenAPISpec };
+	if (localSpec.servers) {
+		localSpec.servers[0].url = "/";
+	}
+	app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(localSpec));
+}
+
+// Local stand-in for the CloudFront `/content/*` behavior. In production the
+// Lambda@Edge JWT verifier guards these requests and CloudFront serves them
+// from the storage S3 bucket via OAC. Locally we stream the bytes from the
+// filesystem-backed storage location keyed by URL path. No JWT check — this
+// server only runs against an isolated dev/e2e DynamoDB + storage tree.
+//
+// `LOCAL_CONTENT_STORAGE_BASE` lets the e2e/smoke fixture point this server at
+// the same absolute filesystem root it seeded under (repo-relative), since
+// the fixture writes from the repo root while the dev-server's cwd is the
+// playwright workspace.
+const STORAGE_LOCAL_PATH = process.env.STORAGE_LOCAL_PATH ?? ".remit/storage";
+const STORAGE_BASE = resolve(
+	process.env.LOCAL_CONTENT_STORAGE_BASE ?? process.cwd(),
+	STORAGE_LOCAL_PATH,
+);
+
+app.get(/^\/content\/.+$/, async (req: Request, res: Response) => {
+	const storageKey = req.path.replace(/^\/content\//, "");
+
+	// On the Postgres stack this route is the deployed content-delivery surface;
+	// require a valid signed URL (HMAC + expiry, scoped to the owning account)
+	// before touching storage. Bearer auth can't ride on an `<img src>` content
+	// load, so the signature carried in the query string is the authorization.
+	const auth = authorizeContentRequest({
+		dataBackend: process.env.DATA_BACKEND,
+		secret: process.env.BETTER_AUTH_SECRET,
+		relativePath: storageKey,
+		exp: typeof req.query.exp === "string" ? req.query.exp : undefined,
+		sig: typeof req.query.sig === "string" ? req.query.sig : undefined,
+		nowSeconds: Math.floor(Date.now() / 1000),
+	});
+	if (!auth.authorized) {
+		res.status(auth.status).setHeader("x-remit-403-reason", auth.reason);
+		res.send(auth.reason);
+		return;
+	}
+
+	const fullPath = resolveContentPath(STORAGE_BASE, storageKey);
+	if (fullPath === null) {
+		res.status(400).send("invalid path");
+		return;
+	}
+
+	const client = await getClient();
+	const result = await serveContent(
+		{
+			// ENOENT means the body isn't synced yet (→ 202); any other read error
+			// throws so express 500s it — never masked as a missing body.
+			readObject: async (path) =>
+				readFile(path).catch((error: unknown) => {
+					if (isStorageNotFoundError(error)) return null;
+					throw error;
+				}),
+			lookupMessage: async (messageId) => {
+				// A gone message row means nothing to re-arm — still answer 202.
+				const message = await client.message.get(messageId).catch(() => null);
+				return message
+					? { mailboxId: message.mailboxId, uid: message.uid }
+					: null;
+			},
+			requestBodySync: async (input) => {
+				await client.bodySyncQueue?.requestBodySync(input);
+			},
+		},
+		{ fullPath, storageKey },
+	);
+
+	res.status(result.status);
+	for (const [name, value] of Object.entries(result.headers)) {
+		res.setHeader(name, value);
+	}
+	res.send(result.body);
+});
+
+app.all(/(.*)/, async (req: Request, res: Response) => {
+	const event = createLambdaEvent(req);
+	const context = createLambdaContext();
+
+	const result: APIGatewayProxyResult = await handler(event, context);
+	const headers = (result.headers ?? {}) as Record<string, string>;
+
+	let body: unknown = result.body;
+
+	if (
+		typeof body === "string" &&
+		headers["Content-Type"]?.includes("application/json")
+	) {
+		const parsed = await safeJsonParse<unknown>(body).catch(() => undefined);
+		if (parsed === undefined) {
+			console.error("[dev-server] Failed to parse JSON body");
+		} else if (
+			parsed &&
+			typeof parsed === "object" &&
+			"statusCode" in parsed &&
+			"body" in parsed
+		) {
+			const inner = (parsed as { body: unknown }).body;
+			body =
+				typeof inner === "string"
+					? await safeJsonParse(inner).catch(() => inner)
+					: inner;
+		} else {
+			body = parsed;
+		}
+	}
+
+	res
+		.setHeaders(new Map(Object.entries(headers)))
+		.status(result.statusCode)
+		.send(body);
+});
+
+const port = env.SERVER_PORT;
+
+app.listen(Number(port), "0.0.0.0", () => {
+	console.log(`Remit Backend running on http://localhost:${port}`);
+	console.log(
+		`OpenAPI documentation available at http://localhost:${port}/api-docs`,
+	);
+
+	console.table({
+		SERVER_PORT: port,
+		DYNAMODB_PORT: env.DYNAMODB_PORT,
+		DYNAMODB_TABLE: env.DYNAMODB_TABLE_NAME,
+		NODE_ENV: env.NODE_ENV,
+	});
+
+	process.send?.("ready");
+});
+
+export default app;

package/package.json

@@ -0,0 +1,82 @@
+{
+	"name": "@remit/backend",
+	"version": "0.0.1",
+	"description": "Remit Mail Inspector API backend",
+	"license": "MIT",
+	"author": "",
+	"type": "module",
+	"main": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./client": {
+			"types": "./src/service/dynamodb.ts",
+			"default": "./src/service/dynamodb.ts"
+		},
+		"./organize": {
+			"types": "./src/service/organize.ts",
+			"default": "./src/service/organize.ts"
+		},
+		"./trigger-sync": {
+			"types": "./src/service/trigger-sync.ts",
+			"default": "./src/service/trigger-sync.ts"
+		},
+		"./content-handler": {
+			"types": "./dev-server/content-handler.ts",
+			"default": "./dev-server/content-handler.ts"
+		}
+	},
+	"scripts": {
+		"test:typecheck": "tsgo --noEmit",
+		"test:run": "node --env-file .env.test --import tsx --test 'src/**/*.test.ts' 'dev-server/**/*.test.ts'",
+		"test": "npm run test:typecheck && npm run test:run",
+		"bundle": "esbuild 'src/index.ts' --sourcemap --bundle --platform=node --outfile=dist/index.js",
+		"dev": "node --env-file .env.test --watch --import tsx dev-server/server.ts",
+		"dev:remote": "node --env-file ../../.env.dev --watch --import tsx dev-server/server.ts"
+	},
+	"devDependencies": {
+		"@aws-sdk/client-secrets-manager": "*",
+		"@aws-sdk/client-sqs": "*",
+		"@aws-sdk/core": "*",
+		"@remit/data-ports": "*",
+		"@remit/electrodb-entities": "*",
+		"@remit/auth-service": "*",
+		"@remit/drizzle-service": "*",
+		"drizzle-orm": "^0.45.2",
+		"@remit/domain-enums": "*",
+		"@remit/mail-oauth-service": "*",
+		"@remit/mailbox-service": "*",
+		"@remit/secrets-service": "*",
+		"@remit/api-openapi-types": "*",
+		"@remit/search-index-worker": "*",
+		"@remit/search-service": "*",
+		"@remit/sqs-client": "*",
+		"@remit/storage-service": "*",
+		"@types/aws-lambda": "*",
+		"@types/express": "^5.0.3",
+		"@types/swagger-ui-express": "^4.1.8",
+		"electrodb": "*",
+		"esbuild": "^0.27.7",
+		"expect-env": "*",
+		"express": "^5.1.0",
+		"openapi-backend": "*",
+		"p-map": "*",
+		"@remit/logger-lambda": "*",
+		"swagger-ui-express": "^5.0.1",
+		"tsx": "*"
+	},
+	"dependencies": {
+		"jose": "^6.2.3",
+		"mailparser": "^3.9.14"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/remit-mail/remit.git",
+		"directory": "packages/backend"
+	}
+}

package/src/auth.ts

@@ -0,0 +1,92 @@
+import { base36uuidv5, REMIT_NAMESPACE } from "@remit/data-ports/id";
+import type { APIGatewayProxyEvent } from "aws-lambda";
+
+const LOCAL_BYPASS_VARS = [
+	"LOCAL_ACCOUNT_CONFIG_ID",
+	"LOCAL_COGNITO_SUB",
+] as const;
+
+const isLocalEnv = (env: NodeJS.ProcessEnv): boolean =>
+	env.NODE_ENV === "development" || env.NODE_ENV === "test";
+
+/**
+ * The LOCAL_ACCOUNT_CONFIG_ID / LOCAL_COGNITO_SUB overrides bypass authentication
+ * for local dev and fixtures: with them set, an unauthenticated request is served
+ * as the pinned account. They must never reach a deployed environment. Refuse to
+ * start (throw at module load) if either is present outside a local NODE_ENV — the
+ * same `development`/`test` signal the data layer already uses to decide local vs
+ * deployed. Fail loud rather than silently ignore, so a leaked env var is caught at
+ * boot, not exploited at runtime.
+ */
+export const assertLocalBypassNotInDeployedEnv = (
+	env: NodeJS.ProcessEnv = process.env,
+): void => {
+	if (isLocalEnv(env)) return;
+	const leaked = LOCAL_BYPASS_VARS.filter((name) => {
+		const value = env[name];
+		return typeof value === "string" && value.length > 0;
+	});
+	if (leaked.length === 0) return;
+	throw new Error(
+		`Refusing to start: local auth bypass ${leaked.join(", ")} is set while NODE_ENV=${env.NODE_ENV ?? "(unset)"}. These overrides bypass authentication and must never be present in a deployed environment.`,
+	);
+};
+
+/**
+ * Derive a deterministic accountConfigId from a Cognito subject (`sub`) claim.
+ * One Cognito user maps to exactly one account config.
+ */
+export const deriveAccountConfigId = (sub: string): string =>
+	base36uuidv5(`account:${sub}`, REMIT_NAMESPACE);
+
+const getSubFromClaims = (event: APIGatewayProxyEvent): string | undefined => {
+	const claims = event.requestContext?.authorizer?.claims;
+	if (!claims) return undefined;
+	const sub = claims.sub;
+	if (typeof sub === "string" && sub.length > 0) return sub;
+	return undefined;
+};
+
+/**
+ * Return the Cognito `sub` for the current request, preferring the JWT claim
+ * and falling back to `LOCAL_COGNITO_SUB` for local development. Returns
+ * `undefined` when neither is available (e.g. seeded fixtures that only set
+ * `LOCAL_ACCOUNT_CONFIG_ID`).
+ */
+export const getSubFromEvent = (
+	event: APIGatewayProxyEvent,
+): string | undefined => {
+	const sub = getSubFromClaims(event);
+	if (sub) return sub;
+	const localSub = process.env.LOCAL_COGNITO_SUB;
+	if (localSub && localSub.length > 0) return localSub;
+	return undefined;
+};
+
+/**
+ * Extract the caller's accountConfigId from an API Gateway event.
+ *
+ * Production: reads the Cognito `sub` claim (verified by the API Gateway
+ * Cognito authorizer) and derives the accountConfigId via UUIDv5.
+ *
+ * Local development: honours two environment overrides so the dev server and
+ * playwright fixtures can run without a real Cognito token:
+ *   - `LOCAL_ACCOUNT_CONFIG_ID` — pin a specific seeded accountConfigId
+ *   - `LOCAL_COGNITO_SUB` — pin a Cognito `sub` value; derived like production
+ */
+export const getAccountConfigIdFromEvent = (
+	event: APIGatewayProxyEvent,
+): string => {
+	const sub = getSubFromClaims(event);
+	if (sub) return deriveAccountConfigId(sub);
+
+	const localAccountConfigId = process.env.LOCAL_ACCOUNT_CONFIG_ID;
+	if (localAccountConfigId) return localAccountConfigId;
+
+	const localSub = process.env.LOCAL_COGNITO_SUB;
+	if (localSub) return deriveAccountConfigId(localSub);
+
+	throw new Error(
+		"Missing accountConfigId: no Cognito `sub` claim on the request, and neither LOCAL_ACCOUNT_CONFIG_ID nor LOCAL_COGNITO_SUB env var is set",
+	);
+};

package/src/config/msoauth.ts

@@ -0,0 +1,60 @@
+/**
+ * Typed reads for Microsoft OAuth (Entra) environment variables.
+ *
+ * In production these are wired by CDK (see infra/stacks/dev/stacks/):
+ *   - `MSOAUTH_SECRET_ARN`  — Secrets Manager ARN; Lambda calls GetSecretValue
+ *     at runtime to retrieve `{"clientId":"…","clientSecret":"…"}`.
+ *   - `MSOAUTH_AUTHORITY`   — OIDC authority base URL (baked in at deploy time).
+ *   - `MSOAUTH_REDIRECT_URI`— OAuth callback URI (baked in at deploy time).
+ *
+ * For local development, set `MSOAUTH_CLIENT_ID` and `MSOAUTH_CLIENT_SECRET`
+ * directly in `localhost-dev-aws.env` to bypass Secrets Manager.
+ *
+ * See doc/oauth-microsoft.md for the Azure portal setup runbook.
+ */
+
+export interface MsOAuthConfig {
+	/** Secrets Manager ARN — present in deployed Lambda environments. */
+	readonly secretArn: string | undefined;
+	/** OIDC authority, e.g. `https://login.microsoftonline.com/common`. */
+	readonly authority: string;
+	/** OAuth redirect URI registered in the Entra app. */
+	readonly redirectUri: string;
+	/** Client ID — used for local dev (bypasses Secrets Manager). */
+	readonly clientId: string | undefined;
+	/** Client secret — used for local dev (bypasses Secrets Manager). */
+	readonly clientSecret: string | undefined;
+	/** Token endpoint override — used for local stubbing (bypasses default OIDC discovery). */
+	readonly tokenEndpoint: string | undefined;
+}
+
+/**
+ * Read Microsoft OAuth configuration from the environment.
+ * Throws when mandatory values (`MSOAUTH_AUTHORITY`, `MSOAUTH_REDIRECT_URI`)
+ * are absent — both are always present in deployed Lambdas and should be set
+ * in `localhost-dev-aws.env` for local development.
+ */
+export const getMsOAuthConfig = (): MsOAuthConfig => {
+	const authority = process.env.MSOAUTH_AUTHORITY;
+	const redirectUri = process.env.MSOAUTH_REDIRECT_URI;
+
+	if (!authority) {
+		throw new Error(
+			"MSOAUTH_AUTHORITY is not set. Wire via CDK (infra/stacks/dev/stacks/remit-api-stack.ts) or set in localhost-dev-aws.env.",
+		);
+	}
+	if (!redirectUri) {
+		throw new Error(
+			"MSOAUTH_REDIRECT_URI is not set. Wire via CDK (infra/stacks/dev/stacks/remit-api-stack.ts) or set in localhost-dev-aws.env.",
+		);
+	}
+
+	return {
+		secretArn: process.env.MSOAUTH_SECRET_ARN,
+		authority,
+		redirectUri,
+		clientId: process.env.MSOAUTH_CLIENT_ID,
+		clientSecret: process.env.MSOAUTH_CLIENT_SECRET,
+		tokenEndpoint: process.env.MSOAUTH_TOKEN_ENDPOINT,
+	};
+};

package/src/data-backend.test.ts

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { usesBetterAuthJwt } from "./data-backend.js";
+
+describe("usesBetterAuthJwt", () => {
+	const ORIGINAL = process.env.DATA_BACKEND;
+	afterEach(() => {
+		if (ORIGINAL === undefined) delete process.env.DATA_BACKEND;
+		else process.env.DATA_BACKEND = ORIGINAL;
+	});
+
+	it("is true for the self-host SQL backends", () => {
+		process.env.DATA_BACKEND = "postgres";
+		assert.equal(usesBetterAuthJwt(), true);
+		process.env.DATA_BACKEND = "sqlite";
+		assert.equal(usesBetterAuthJwt(), true);
+	});
+
+	it("is false for the AWS DynamoDB path and when unset", () => {
+		process.env.DATA_BACKEND = "dynamodb";
+		assert.equal(usesBetterAuthJwt(), false);
+		delete process.env.DATA_BACKEND;
+		assert.equal(usesBetterAuthJwt(), false);
+	});
+});

package/src/data-backend.ts

@@ -0,0 +1,20 @@
+/**
+ * The two self-host SQL backends (RFC 034/035/036), as opposed to the AWS
+ * DynamoDB path.
+ */
+export const isSelfHostSqlBackend = (): boolean => {
+	const backend = process.env.DATA_BACKEND;
+	return backend === "postgres" || backend === "sqlite";
+};
+
+/**
+ * The self-host SQL backends authenticate requests and sign content URLs the
+ * same way: a better-auth RS256 JWT verified at the edge and re-verified
+ * in-process, no Cognito authorizer. DynamoDB is the AWS path (Cognito claims,
+ * Lambda@Edge content guard) and is deliberately excluded.
+ *
+ * Guarding these paths on `=== "postgres"` alone left the sqlite deployment
+ * with no claim injection (every identity-bound request 500s) and unsigned
+ * `/content/*` URLs; both branch on this predicate instead.
+ */
+export const usesBetterAuthJwt = (): boolean => isSelfHostSqlBackend();

package/src/derive/autoMoved.ts

@@ -0,0 +1,28 @@
+import type { AutoMovedInfo } from "@remit/api-openapi-types";
+import type { MessageItem } from "@remit/data-ports";
+import { PlacementConfidence } from "@remit/domain-enums";
+
+/**
+ * Project a Message's internal placement verdict to the public `AutoMovedInfo`
+ * shape. Present only for a real, in-effect auto-move — `movedByRemit` is
+ * true, the verdict is `Confident`, and it was not a dry run. Confidence,
+ * dryRun, decidedAt and reasons are internal diagnostics and never cross to
+ * the wire; the client derives everything else (whether the move is still in
+ * effect, the undo target) from `action`/`fromPlacement` plus current
+ * placement.
+ */
+export const deriveAutoMoved = (
+	message: Pick<MessageItem, "movedByRemit" | "placementVerdict">,
+): AutoMovedInfo | undefined => {
+	if (message.movedByRemit !== true) return undefined;
+
+	const verdict = message.placementVerdict;
+	if (!verdict) return undefined;
+	if (verdict.confidence !== PlacementConfidence.Confident) return undefined;
+	if (verdict.dryRun === true) return undefined;
+
+	return {
+		action: verdict.action,
+		fromPlacement: verdict.fromPlacement,
+	};
+};