@remit/backend 0.0.142 → 0.0.144

package/dist/dev-server/content-handler.d.ts

@@ -0,0 +1,38 @@
+import { parseContentStorageKey } from "@remit/storage-service";
+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 declare const serveContent: (deps: ServeContentDeps, args: {
+    fullPath: string;
+    storageKey: string;
+}) => Promise<ContentResult>;

package/dist/dev-server/content-handler.js

@@ -0,0 +1,46 @@
+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 };
+/**
+ * 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, args) => {
+    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/dist/src/api.d.ts

@@ -0,0 +1,7 @@
+import type { APIGatewayProxyEvent, APIGatewayProxyResult, Context } from "aws-lambda";
+import { type Document, OpenAPIBackend } from "openapi-backend";
+export declare const OpenAPISpec: Document;
+declare const api: OpenAPIBackend;
+export { setLogger } from "@remit/logger";
+export { api };
+export declare const handleApiEvent: (event: APIGatewayProxyEvent, context: Context) => Promise<APIGatewayProxyResult>;

package/dist/src/api.js

@@ -0,0 +1,144 @@
+import spec from "@remit/api-openapi-spec/openapi.json" with { type: "json" };
+import { redactCalendarFeedPath } from "@remit/calendar-service";
+import { logger, withLogContext } from "@remit/logger";
+import { OpenAPIBackend, } from "openapi-backend";
+import { assertLocalBypassNotInDeployedEnv } from "./auth.js";
+import { usesBetterAuthJwt } from "./data-backend.js";
+import { defaultErrorCode, handleError } from "./error.js";
+import { handlers } from "./handlers/index.js";
+import { authenticateSelfHostRequest } from "./jwt-auth.js";
+import { normalizeRequest } from "./request.js";
+import { runWithRequestContext } from "./request-context.js";
+import { formatResponse, postResponseHandler } from "./response.js";
+// 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();
+const isDocument = (value) => typeof value === "object" &&
+    value !== null &&
+    "openapi" in value &&
+    typeof value.openapi === "string" &&
+    "paths" in value;
+// Imported, not read from disk, so no host has to place openapi.json next to the
+// entry point — a Worker has no filesystem to read it from.
+if (!isDocument(spec)) {
+    throw new Error("@remit/api-openapi-spec is not an OpenAPI document");
+}
+// Typed as a Document so importers do not see the JSON literal type.
+export const OpenAPISpec = spec;
+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.
+    coerceTypes: true,
+});
+api.register("postResponseHandler", postResponseHandler);
+/**
+ * The validator's findings, narrowed to the three fields `RequestValidationDetail`
+ * declares. Copied field by field rather than passed through: an AJV error also
+ * carries `params`, and under `verbose` the rejected `data` itself — which for a
+ * refused request body is whatever the caller sent, a password among the
+ * possibilities. Naming the fields is what keeps that off the wire.
+ */
+const validationDetails = (errors) => (errors ?? []).map((error) => ({
+    path: error.instancePath,
+    rule: error.keyword,
+    message: error.message ?? "refused",
+}));
+// The errors and the operation, and nothing that came off the wire. A request
+// that fails validation is logged at error level, and the request it carries
+// holds the caller's headers and cookies — an Authorization bearer among them,
+// and for a calendar feed the token in the path is itself the credential
+// (issue #1065). The path is redacted the same way the request scope redacts it.
+api.register("validationFail", (c, req) => {
+    logger.error({
+        errors: c.validation.errors,
+        path: redactCalendarFeedPath(req.path),
+        operation: c.operation?.operationId,
+    }, "Validation failed");
+    return {
+        statusCode: 400,
+        body: {
+            code: defaultErrorCode(400),
+            message: "Invalid request",
+            errors: validationDetails(c.validation.errors),
+        },
+    };
+});
+api.register("notFound", () => ({
+    statusCode: 404,
+    body: { code: defaultErrorCode(404), message: "Not found" },
+}));
+api.register("notImplemented", async (c) => {
+    const { status, mock } = api.mockResponseForOperation(c.operation.operationId);
+    return formatResponse(mock, status);
+});
+api.register(handlers);
+api.init();
+export { setLogger } from "@remit/logger";
+export { api };
+const readOriginHeader = (headers) => {
+    if (!headers)
+        return undefined;
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === "origin" && typeof value === "string") {
+            return value;
+        }
+    }
+    return undefined;
+};
+// A scope, not `logger.setBindings`: this process serves requests concurrently,
+// and bindings on the shared logger belong to whichever request wrote them last,
+// so a line gets attributed to the wrong request. The scope follows the request
+// through its own async continuations and nothing else. It nests inside the one
+// `withTelemetry` opens, which is where `requestId` comes from.
+export const handleApiEvent = async (event, context) => {
+    // A calendar feed carries its credential in the path, so the raw path is a
+    // secret and cannot be a log field (issue #1065). Redacted once, here, where
+    // every line inside the request picks it up from the scope.
+    const path = redactCalendarFeedPath(event.path);
+    return withLogContext({
+        path,
+        method: event.httpMethod,
+    }, async () => {
+        logger.debug({ method: event.httpMethod, path }, "Request received");
+        const origin = readOriginHeader(event.headers);
+        const startedAt = Date.now();
+        // Capture the correlation id here: it is seeded by
+        // runWithRequestContext below (from context.awsRequestId), but that
+        // AsyncLocalStorage scope does not reliably survive the
+        // openapi-backend handleRequest call chain, so we read it from
+        // `context.awsRequestId` directly rather than via
+        // getRequestCorrelationId at log time.
+        const correlationId = context.awsRequestId;
+        const result = await runWithRequestContext({ origin, correlationId }, async () => {
+            if (usesBetterAuthJwt()) {
+                const denied = await authenticateSelfHostRequest(event);
+                if (denied)
+                    return denied;
+            }
+            return api
+                .handleRequest(normalizeRequest(event), event, context)
+                .catch(handleError);
+        });
+        // One structured access line per request: method, path, status, and
+        // duration. The correlation id is inlined as a top-level field so a bug
+        // report quoting the id can grep logs by it directly, and emitted at
+        // info so it is on by default in production (the debug "Request
+        // received" above already filters out under normal log levels).
+        // biome-ignore lint/plugin/no-logger-info: one access line per request is an audit-grade signal (issue #1054)
+        logger.info({
+            method: event.httpMethod,
+            path,
+            statusCode: result.statusCode,
+            durationMs: Date.now() - startedAt,
+            correlationId,
+        }, "Request completed");
+        return result;
+    });
+};

package/dist/src/auth.d.ts

@@ -0,0 +1,30 @@
+import type { APIGatewayProxyEvent } from "aws-lambda";
+/**
+ * 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 declare const assertLocalBypassNotInDeployedEnv: (env?: NodeJS.ProcessEnv) => void;
+/**
+ * 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 declare const getSubFromEvent: (event: APIGatewayProxyEvent) => string | 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 declare const getAccountConfigIdFromEvent: (event: APIGatewayProxyEvent) => string;

package/dist/src/auth.js

@@ -0,0 +1,73 @@
+import { deriveAccountConfigId } from "@remit/data-ports/id";
+const LOCAL_BYPASS_VARS = [
+    "LOCAL_ACCOUNT_CONFIG_ID",
+    "LOCAL_COGNITO_SUB",
+];
+const isLocalEnv = (env) => 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 = process.env) => {
+    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.`);
+};
+const getSubFromClaims = (event) => {
+    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) => {
+    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) => {
+    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/dist/src/config/msoauth.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Typed reads for Microsoft OAuth (Entra) environment variables.
+ *
+ * `MSOAUTH_REDIRECT_URI` is derived from `PUBLIC_ORIGIN` by the compose file
+ * (deploy/vps/docker-compose.sqlite.yml) and must match the redirect URI
+ * registered on the Entra app registration.
+ *
+ * Credentials come either from `MSOAUTH_CLIENT_ID` / `MSOAUTH_CLIENT_SECRET`
+ * in the deploy env file, or from Secrets Manager via `MSOAUTH_SECRET_ARN`.
+ *
+ * The Microsoft authorization and token endpoints are fixed in
+ * `@remit/mail-oauth-service`; no authority URL is read from the environment.
+ */
+export interface MsOAuthConfig {
+    /** Secrets Manager ARN — an alternative to the client id/secret pair. */
+    readonly secretArn: string | undefined;
+    /** OAuth redirect URI registered in the Entra app. */
+    readonly redirectUri: string;
+    /** Client ID — set directly to bypass Secrets Manager. */
+    readonly clientId: string | undefined;
+    /** Client secret — set directly to bypass 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 `MSOAUTH_REDIRECT_URI` is absent.
+ */
+export declare const getMsOAuthConfig: () => MsOAuthConfig;

package/dist/src/config/msoauth.js

@@ -0,0 +1,30 @@
+/**
+ * Typed reads for Microsoft OAuth (Entra) environment variables.
+ *
+ * `MSOAUTH_REDIRECT_URI` is derived from `PUBLIC_ORIGIN` by the compose file
+ * (deploy/vps/docker-compose.sqlite.yml) and must match the redirect URI
+ * registered on the Entra app registration.
+ *
+ * Credentials come either from `MSOAUTH_CLIENT_ID` / `MSOAUTH_CLIENT_SECRET`
+ * in the deploy env file, or from Secrets Manager via `MSOAUTH_SECRET_ARN`.
+ *
+ * The Microsoft authorization and token endpoints are fixed in
+ * `@remit/mail-oauth-service`; no authority URL is read from the environment.
+ */
+/**
+ * Read Microsoft OAuth configuration from the environment.
+ * Throws when `MSOAUTH_REDIRECT_URI` is absent.
+ */
+export const getMsOAuthConfig = () => {
+    const redirectUri = process.env.MSOAUTH_REDIRECT_URI;
+    if (!redirectUri) {
+        throw new Error("MSOAUTH_REDIRECT_URI is not set. It is derived from PUBLIC_ORIGIN — set PUBLIC_ORIGIN in the deploy env file (deploy/vps/.env) and restart, or set MSOAUTH_REDIRECT_URI directly.");
+    }
+    return {
+        secretArn: process.env.MSOAUTH_SECRET_ARN,
+        redirectUri,
+        clientId: process.env.MSOAUTH_CLIENT_ID,
+        clientSecret: process.env.MSOAUTH_CLIENT_SECRET,
+        tokenEndpoint: process.env.MSOAUTH_TOKEN_ENDPOINT,
+    };
+};

package/{src/data-backend.ts → dist/src/data-backend.d.ts}

@@ -2,13 +2,11 @@
  * The self-host SQL backend (RFC 034/035/036), as opposed to the AWS DynamoDB
  * path.
  */
-export const isSelfHostSqlBackend = (): boolean =>
-	process.env.DATA_BACKEND === "sqlite";
-
+export declare const isSelfHostSqlBackend: () => boolean;
 /**
  * The self-host SQL backend authenticates requests and signs content URLs with
  * 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.
  */
-export const usesBetterAuthJwt = (): boolean => isSelfHostSqlBackend();
+export declare const usesBetterAuthJwt: () => boolean;

package/dist/src/data-backend.js

@@ -0,0 +1,12 @@
+/**
+ * The self-host SQL backend (RFC 034/035/036), as opposed to the AWS DynamoDB
+ * path.
+ */
+export const isSelfHostSqlBackend = () => process.env.DATA_BACKEND === "sqlite";
+/**
+ * The self-host SQL backend authenticates requests and signs content URLs with
+ * 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.
+ */
+export const usesBetterAuthJwt = () => isSelfHostSqlBackend();

package/{src/derive/autoMoved.ts → dist/src/derive/autoMoved.d.ts}

@@ -1,7 +1,5 @@
 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 auto-move state to the public `AutoMovedInfo`
  * shape. Present only for a real, in-effect auto-move; absent otherwise, so a
@@ -27,30 +25,4 @@ import { PlacementConfidence } from "@remit/domain-enums";
  * The client derives everything else (whether the move is still in effect, the
  * undo target) from these fields plus current placement.
  */
-export const deriveAutoMoved = (
-	message: Pick<
-		MessageItem,
-		"movedByRemit" | "placementVerdict" | "filterMove"
-	>,
-): AutoMovedInfo | undefined => {
-	if (message.movedByRemit !== true) return undefined;
-
-	const filterMove = message.filterMove;
-	if (filterMove) {
-		return {
-			fromMailboxId: filterMove.sourceMailboxId,
-			destinationMailboxId: filterMove.destinationMailboxId,
-			filterId: filterMove.filterId,
-		};
-	}
-
-	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,
-	};
-};
+export declare const deriveAutoMoved: (message: Pick<MessageItem, "movedByRemit" | "placementVerdict" | "filterMove">) => AutoMovedInfo | undefined;

package/dist/src/derive/autoMoved.js

@@ -0,0 +1,49 @@
+import { PlacementConfidence } from "@remit/domain-enums";
+/**
+ * Project a Message's internal auto-move state to the public `AutoMovedInfo`
+ * shape. Present only for a real, in-effect auto-move; absent otherwise, so a
+ * message synced before either mechanism existed (no `filterMove`, no
+ * `placementVerdict`) projects nothing and renders no badge.
+ *
+ * Two mechanisms move mail and both raise `movedByRemit`:
+ *
+ * 1. A standing filter (RFC 034) records a `filterMove` marker naming the
+ *    source folder, the destination folder, and the filter. It has no
+ *    classifier direction/role, so the projection carries mailbox ids
+ *    (`fromMailboxId`/`destinationMailboxId`) and the `filterId` for the
+ *    Settings link — an arbitrary destination the Inbox/Junk-shaped `action`
+ *    cannot name.
+ * 2. The Tier 0 classifier records a `placementVerdict`. Its `action`
+ *    (MoveToInbox/MoveToJunk) and `fromPlacement` (inbox/junk/other) are the
+ *    only fields that cross to the wire; confidence, dryRun, decidedAt and
+ *    reasons stay internal.
+ *
+ * The filter marker outranks the verdict check: a matched filter's move is
+ * exclusive and outranks the classifier's placement move at index time (RFC 034
+ * Decision 3.1), so a message carrying both was ultimately moved by the filter.
+ * The client derives everything else (whether the move is still in effect, the
+ * undo target) from these fields plus current placement.
+ */
+export const deriveAutoMoved = (message) => {
+    if (message.movedByRemit !== true)
+        return undefined;
+    const filterMove = message.filterMove;
+    if (filterMove) {
+        return {
+            fromMailboxId: filterMove.sourceMailboxId,
+            destinationMailboxId: filterMove.destinationMailboxId,
+            filterId: filterMove.filterId,
+        };
+    }
+    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,
+    };
+};

package/dist/src/derive/contentSignature.d.ts

@@ -0,0 +1,41 @@
+import { type SignedPathFailure } from "@remit/storage-service/signed-path";
+/**
+ * Default validity window for a signed content URL. Long enough to cover a
+ * viewing session (react-query caches describeMessage for 30 min and inline
+ * images may load late), short enough to bound the replay window if a URL
+ * leaks.
+ */
+export declare const CONTENT_URL_TTL_SECONDS = 3600;
+export interface ContentSignature {
+    exp: number;
+    sig: string;
+}
+/**
+ * A function that signs a decoded, account-scoped storage path and returns the
+ * `exp`/`sig` query params to append to its content URL.
+ */
+export type ContentSigner = (relativePath: string) => ContentSignature;
+export declare const createContentSigner: (masterSecret: string, ttlSeconds?: number) => ContentSigner;
+/**
+ * Build the content-URL signer for the current environment, or `undefined` when
+ * signing does not apply. Signing is enforced on the self-host SQL backend,
+ * which serves `/content/*` straight from the backend container; on AWS the
+ * Lambda@Edge JWT verifier guards `/content/*` and the URL stays unsigned so
+ * CloudFront/S3 behaviour is unchanged. Throws on the self-host backend when the
+ * master secret is missing, so a misconfigured deploy fails loud rather than
+ * shipping unsigned (unauthenticated) content URLs.
+ */
+export declare const getContentSigner: () => ContentSigner | undefined;
+export type ContentSignatureFailure = SignedPathFailure;
+export type ContentSignatureResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: ContentSignatureFailure;
+};
+/**
+ * Verify a signed content request. Recomputes the HMAC over the requested path
+ * and the supplied expiry and constant-time compares it against the presented
+ * signature. Pure so the decision can be unit-tested without a live server.
+ */
+export declare const verifyContentSignature: (relativePath: string, expRaw: string | undefined, sig: string | undefined, masterSecret: string, nowSeconds: number) => ContentSignatureResult;