@hansjm10/volt-coding-agent 0.0.0-bootstrap.0 → 0.1.0

package/examples/remote/firebase-push-relay/README.md

@@ -0,0 +1,79 @@
+# Firebase Push Relay
+
+This deploys Volt's managed push relay contract to Firebase Cloud Functions. The relay stores the raw FCM registration token in private Firestore state and gives the mobile app an opaque target id plus a target-scoped credential. A paired desktop host can send to that target without receiving the FCM token.
+
+## Security contract
+
+- Registration requires an `X-Firebase-AppCheck` **limited-use** token. The function verifies it with replay consumption, rejects an already-consumed token, requires its one-time `jti`, and allowlists the Firebase app id. There is no embedded or shared app secret.
+- One FCM token maps to one deterministic Firestore document. Re-registering rotates the target credential instead of growing an attacker-controlled collection.
+- Target credentials are stored only as SHA-256 hashes. FCM tokens remain raw because Firebase Messaging needs them, so Firestore access is denied to clients and project IAM must stay least-privilege.
+- Targets expire after 30 days by default. Every delivery rejects an expired target immediately; the deployed Firestore TTL policy deletes expired documents asynchronously.
+- The app validates a cached target through the credential-authenticated status route before reuse. A host-side revoke therefore causes fresh App Check registration instead of leaving the phone stuck on a dead credential.
+- Registration, notification, Live Activity, and revocation bodies have a 16 KiB total cap plus explicit field, string, object-depth, key-count, array-count, and timestamp bounds.
+- Each target reserves a delivery quota slot in a Firestore transaction before FCM is called. Failures consume the slot, so a failing send cannot create a hot retry loop.
+- Registration also has a per-instance burst cap. The function has bounded concurrency, instance count, memory, and request time. These are defense-in-depth controls, not substitutes for a project-level budget and edge rate limit.
+- `relayUrl` is returned only from the validated `PUSH_RELAY_URL` setting (or the compiled production URL); request `Host` and forwarding headers are never reflected.
+- Explicit revocation requires the target id and target credential. Desktop unpair is locally authoritative even if this remote cleanup fails; the failure is audited and the finite target TTL bounds its lifetime.
+- Turning off both notification and Live Activity delivery emits one disabled host registration, revokes the current and bounded pending relay credentials best-effort, deletes the FCM token, and clears the Keychain cache.
+
+The function remains publicly invokable because an unattached iOS app must reach the registration endpoint. App Check attestation is the registration authorization boundary. Notification, Live Activity, and revoke routes use the random per-target credential.
+
+## Routes
+
+- `POST /v1/push-targets`: mobile app registration with `X-Firebase-AppCheck`; body `{ provider:"fcm", platform:"ios", token, enabled }`; returns `{ pushTargetId, pushTargetAuthToken, relayUrl, tokenHash, expiresAtEpochSeconds }`.
+- `POST /v1/push-targets/revoke`: app or host cleanup with `{ pushTargetId, pushTargetAuthToken }`; returns `revoked` or idempotent `already_revoked`.
+- `POST /v1/push-targets/status`: credential-authenticated cache validation; returns `{ status:"active", expiresAtEpochSeconds }`, or `401`/`404`/`410` when the cached credential must be replaced.
+- `POST /v1/notifications`: desktop delivery with `{ pushTargetId, pushTargetAuthToken, eventId, kind, title, body, workspace?, data }`.
+- `POST /v1/live-activities`: desktop delivery with `{ pushTargetId, pushTargetAuthToken, activityId, activityPushToken, tokenEnvironment?, eventId, kind, contentState, ... }`.
+
+Volt host state stores only the opaque relay target id, the target-scoped credential, and optional token hashes.
+
+## Required Firebase setup
+
+1. Register the production iOS app and include its generated `GoogleService-Info.plist` in the app target.
+2. Enable Firebase App Check for that iOS app. Production builds should use App Attest with DeviceCheck fallback. Simulator/debug tokens are development-only and must never be enabled for the production Beta build.
+3. Confirm that the Firebase app id in App Check matches `ALLOWED_FIREBASE_APP_IDS`. The built-in default is Volt's production iOS app id; self-hosted deployments must override it.
+4. Enable replay protection support for limited-use App Check tokens. Registration intentionally performs the extra consumption network call and rejects ordinary reusable App Check tokens.
+5. Configure APNs credentials in Firebase Console for FCM and Live Activities.
+6. Deploy Firestore rules **and indexes** so the `expiresAt` TTL field override is active. Verify the TTL policy in the Firestore console after deployment.
+7. Keep the function service account and Firestore project IAM least-privilege, enable Cloud Audit Logs, set project budget alerts, and monitor App Check invalid/replay metrics plus `429`/`5xx` responses.
+
+For an Internet-facing production deployment, put the Gen 2 function behind an external Application Load Balancer with Cloud Armor (or an equivalent API gateway) and apply IP/bot/rate policies there. If the direct `cloudfunctions.net` URL remains reachable, edge policies can be bypassed; restrict ingress to the load balancer after verifying iOS and host traffic through the canonical `PUSH_RELAY_URL`.
+
+## Configuration
+
+All limits have safe defaults and bounded override ranges:
+
+- `ALLOWED_FIREBASE_APP_IDS`: comma-separated allowlist, 1-8 app ids.
+- `PUSH_RELAY_URL`: canonical absolute HTTPS relay URL; credentials, query, and fragment are rejected.
+- `PUSH_TARGET_TTL_DAYS`: 1-90, default 30. Changing the value does not renew existing targets.
+- `DELIVERIES_PER_TARGET_PER_MINUTE`: 1-600, default 30.
+- `REGISTRATIONS_PER_INSTANCE_PER_MINUTE`: 1-120, default 30. This local burst control is supplemented by App Check replay protection and should be backed by an edge/global quota.
+- `FUNCTION_REGION`: deployment region, default `us-central1`.
+- `LIVE_ACTIVITY_APNS_TOPIC`: default `com.hansjm10.volt.push-type.liveactivity`.
+- `LIVE_ACTIVITY_ALLOW_DEVELOPMENT=1`: development-only escape hatch described below.
+
+## Deploy
+
+From this directory:
+
+```bash
+firebase use volt-3fae7
+firebase firestore:databases:create '(default)' --project volt-3fae7 --location nam5
+firebase deploy --project volt-3fae7 --only firestore:rules,firestore:indexes,functions:volt-push-relay:pushRelay
+```
+
+Use a different Firestore location if `nam5` is not intended. Cloud Functions deployment requires the Blaze plan so Firebase can enable Cloud Build and Artifact Registry APIs. Do not deploy until App Check, the app-id allowlist, APNs, TTL, monitoring, budget, and edge controls above are verified.
+
+The official Volt host defaults to the managed relay URL. For a self-hosted relay, point the host at the same canonical URL configured in `PUSH_RELAY_URL`:
+
+```bash
+export VOLT_PUSH_RELAY_URL="https://push.example.com/"
+volt remote host --mobile --workspace volt=/path/to/Volt
+```
+
+## Error behavior
+
+FCM send failures return `502 { error: "fcm_send_failed", code }` with the FCM error code. Cloud Logging receives the server error plus event id and kind, never the FCM token or target credential.
+
+Live Activity updates with `tokenEnvironment: "development"` return `422 { error: "live_activity_environment_unsupported" }` before FCM. FCM delivers `live_activity_token` pushes through production APNs, so a sandbox ActivityKit token from an Xcode-installed build is not reachable. Hosts treat this as a permanently invalid channel. `LIVE_ACTIVITY_ALLOW_DEVELOPMENT=1` attempts delivery only for controlled development testing.

package/examples/remote/firebase-push-relay/firebase.json

@@ -0,0 +1,12 @@
+{
+	"functions": [
+		{
+			"source": "functions",
+			"codebase": "volt-push-relay"
+		}
+	],
+	"firestore": {
+		"rules": "firestore.rules",
+		"indexes": "firestore.indexes.json"
+	}
+}

package/examples/remote/firebase-push-relay/firestore.indexes.json

@@ -0,0 +1,11 @@
+{
+	"indexes": [],
+	"fieldOverrides": [
+		{
+			"collectionGroup": "voltPushTargets",
+			"fieldPath": "expiresAt",
+			"ttl": true,
+			"indexes": []
+		}
+	]
+}

package/examples/remote/firebase-push-relay/firestore.rules

@@ -0,0 +1,9 @@
+rules_version = '2';
+
+service cloud.firestore {
+	match /databases/{database}/documents {
+		match /{document=**} {
+			allow read, write: if false;
+		}
+	}
+}

package/examples/remote/firebase-push-relay/functions/core.js

@@ -0,0 +1,511 @@
+const { createHash, timingSafeEqual } = require("node:crypto");
+
+const DEFAULT_ALLOWED_FIREBASE_APP_ID = "1:546623825529:ios:9f5a707e3f4ef89154d6a8";
+const DEFAULT_PUBLIC_RELAY_URL = "https://us-central1-volt-3fae7.cloudfunctions.net/pushRelay";
+const DEFAULT_PUSH_TARGET_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+const MAX_REQUEST_BYTES = 16 * 1024;
+const MAX_OBJECT_DEPTH = 8;
+const MAX_TOTAL_ARRAY_ENTRIES = 32;
+const MAX_TOTAL_KEYS = 80;
+const MAX_TOTAL_VALUES = 160;
+const MAX_GENERIC_STRING_LENGTH = 4096;
+const MAX_LIVE_ACTIVITY_FUTURE_SECONDS = 30 * 24 * 60 * 60;
+const MAX_LIVE_ACTIVITY_PAST_SECONDS = 24 * 60 * 60;
+const MAX_CLOCK_SKEW_SECONDS = 5 * 60;
+const FORBIDDEN_OBJECT_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+class RequestError extends Error {
+	constructor(status, publicMessage) {
+		super(publicMessage);
+		this.name = "RequestError";
+		this.publicMessage = publicMessage;
+		this.status = status;
+	}
+}
+
+function assertRequestEnvelope(request) {
+	const contentType = getHeader(request, "content-type");
+	if (contentType === undefined || contentType.toLowerCase().split(";", 1)[0].trim() !== "application/json") {
+		throw new RequestError(415, "content_type_must_be_json");
+	}
+	const contentLength = getHeader(request, "content-length");
+	if (contentLength !== undefined) {
+		const parsedLength = Number(contentLength);
+		if (!Number.isSafeInteger(parsedLength) || parsedLength < 0) {
+			throw new RequestError(400, "invalid_content_length");
+		}
+		if (parsedLength > MAX_REQUEST_BYTES) {
+			throw new RequestError(413, "request_body_too_large");
+		}
+	}
+	const rawBody = request.rawBody;
+	if (Buffer.isBuffer(rawBody) && rawBody.byteLength > MAX_REQUEST_BYTES) {
+		throw new RequestError(413, "request_body_too_large");
+	}
+}
+
+function readJsonBody(request) {
+	assertRequestEnvelope(request);
+	const body = request.body;
+	let parsed;
+	if (Buffer.isBuffer(body)) {
+		if (body.byteLength > MAX_REQUEST_BYTES) {
+			throw new RequestError(413, "request_body_too_large");
+		}
+		parsed = parseJson(body.toString("utf8"));
+	} else if (typeof body === "string") {
+		if (Buffer.byteLength(body, "utf8") > MAX_REQUEST_BYTES) {
+			throw new RequestError(413, "request_body_too_large");
+		}
+		parsed = parseJson(body);
+	} else if (isRecord(body)) {
+		const encoded = JSON.stringify(body);
+		if (Buffer.byteLength(encoded, "utf8") > MAX_REQUEST_BYTES) {
+			throw new RequestError(413, "request_body_too_large");
+		}
+		parsed = body;
+	} else {
+		throw new RequestError(400, "request_body_must_be_json");
+	}
+	assertBoundedJsonValue(parsed);
+	return parsed;
+}
+
+function parseJson(value) {
+	try {
+		const parsed = JSON.parse(value);
+		if (!isRecord(parsed)) {
+			throw new RequestError(400, "request_body_must_be_json_object");
+		}
+		return parsed;
+	} catch (error) {
+		if (error instanceof RequestError) {
+			throw error;
+		}
+		throw new RequestError(400, "request_body_must_be_json");
+	}
+}
+
+function assertBoundedJsonValue(root) {
+	let totalArrayEntries = 0;
+	let totalKeys = 0;
+	let totalValues = 0;
+	const pending = [{ depth: 0, value: root }];
+	while (pending.length > 0) {
+		const current = pending.pop();
+		if (current === undefined) break;
+		totalValues += 1;
+		if (totalValues > MAX_TOTAL_VALUES) {
+			throw new RequestError(400, "request_body_too_complex");
+		}
+		if (current.depth > MAX_OBJECT_DEPTH) {
+			throw new RequestError(400, "request_body_too_deep");
+		}
+		if (typeof current.value === "string" && current.value.length > MAX_GENERIC_STRING_LENGTH) {
+			throw new RequestError(400, "request_string_too_large");
+		}
+		if (Array.isArray(current.value)) {
+			totalArrayEntries += current.value.length;
+			if (totalArrayEntries > MAX_TOTAL_ARRAY_ENTRIES) {
+				throw new RequestError(400, "request_arrays_too_large");
+			}
+			for (const entry of current.value) {
+				pending.push({ depth: current.depth + 1, value: entry });
+			}
+			continue;
+		}
+		if (!isRecord(current.value)) continue;
+		const entries = Object.entries(current.value);
+		totalKeys += entries.length;
+		if (totalKeys > MAX_TOTAL_KEYS) {
+			throw new RequestError(400, "request_has_too_many_keys");
+		}
+		for (const [key, value] of entries) {
+			assertSafeObjectKey(key, "request");
+			pending.push({ depth: current.depth + 1, value });
+		}
+	}
+}
+
+function parsePushTargetRegistration(body) {
+	expectAllowedKeys(body, ["provider", "platform", "token", "enabled"], "registration");
+	return {
+		provider: expectLiteral(body.provider, "fcm", "provider"),
+		platform: expectLiteral(body.platform, "ios", "platform"),
+		token: expectString(body.token, "token", 16, 4096),
+		enabled: expectBoolean(body.enabled, "enabled"),
+	};
+}
+
+function parsePushTargetRevocation(body) {
+	expectAllowedKeys(body, ["pushTargetId", "pushTargetAuthToken"], "revocation");
+	return {
+		pushTargetId: expectString(body.pushTargetId, "pushTargetId", 16, 96),
+		pushTargetAuthToken: expectString(body.pushTargetAuthToken, "pushTargetAuthToken", 32, 128),
+	};
+}
+
+function parseNotification(body) {
+	expectAllowedKeys(
+		body,
+		["pushTargetId", "pushTargetAuthToken", "eventId", "kind", "title", "body", "workspace", "data"],
+		"notification",
+	);
+	const eventId = expectString(body.eventId, "eventId", 1, 128);
+	const kind = expectString(body.kind, "kind", 1, 64);
+	const data = expectStringRecord(body.data, "data", { maxEntries: 16, maxKeyLength: 64, maxValueLength: 1024 });
+	const workspace = expectOptionalString(body.workspace, "workspace", 1, 128);
+	return {
+		body: expectString(body.body, "body", 1, 1024),
+		data: {
+			...data,
+			eventId,
+			kind,
+		},
+		eventId,
+		kind,
+		pushTargetAuthToken: expectString(body.pushTargetAuthToken, "pushTargetAuthToken", 32, 128),
+		pushTargetId: expectString(body.pushTargetId, "pushTargetId", 16, 96),
+		title: expectString(body.title, "title", 1, 128),
+		...(workspace === undefined ? {} : { workspace }),
+	};
+}
+
+function parseLiveActivityUpdate(body, nowEpochSeconds = Math.floor(Date.now() / 1000)) {
+	expectAllowedKeys(
+		body,
+		[
+			"pushTargetId",
+			"pushTargetAuthToken",
+			"activityId",
+			"activityPushToken",
+			"tokenEnvironment",
+			"eventId",
+			"kind",
+			"contentState",
+			"activityEvent",
+			"staleDateEpochSeconds",
+			"dismissalDateEpochSeconds",
+		],
+		"live_activity",
+	);
+	return {
+		activityEvent: expectOptionalLiteral(body.activityEvent, ["update", "end"], "activityEvent") || "update",
+		activityPushToken: expectString(body.activityPushToken, "activityPushToken", 16, 4096),
+		activityId: expectString(body.activityId, "activityId", 1, 128),
+		tokenEnvironment: expectOptionalLiteral(
+			body.tokenEnvironment,
+			["development", "production"],
+			"tokenEnvironment",
+		),
+		contentState: expectLiveActivityContentState(body.contentState, nowEpochSeconds),
+		dismissalDateEpochSeconds: expectOptionalEpochSeconds(
+			body.dismissalDateEpochSeconds,
+			"dismissalDateEpochSeconds",
+			nowEpochSeconds,
+		),
+		eventId: expectString(body.eventId, "eventId", 1, 128),
+		kind: expectString(body.kind, "kind", 1, 64),
+		pushTargetAuthToken: expectString(body.pushTargetAuthToken, "pushTargetAuthToken", 32, 128),
+		pushTargetId: expectString(body.pushTargetId, "pushTargetId", 16, 96),
+		staleDateEpochSeconds: expectOptionalEpochSeconds(
+			body.staleDateEpochSeconds,
+			"staleDateEpochSeconds",
+			nowEpochSeconds,
+		),
+	};
+}
+
+function expectLiveActivityContentState(value, nowEpochSeconds) {
+	if (!isRecord(value)) {
+		throw new RequestError(400, "contentState_must_be_object");
+	}
+	expectAllowedKeys(
+		value,
+		["status", "statusText", "currentTool", "recentTools", "sessionID", "workspaceName", "updatedAtEpochSeconds"],
+		"contentState",
+	);
+	if (!Array.isArray(value.recentTools) || value.recentTools.length > 12) {
+		throw new RequestError(400, "recentTools_must_be_bounded_array");
+	}
+	const updatedAtEpochSeconds = expectEpochSeconds(value.updatedAtEpochSeconds, "updatedAtEpochSeconds");
+	if (
+		updatedAtEpochSeconds < nowEpochSeconds - MAX_LIVE_ACTIVITY_PAST_SECONDS ||
+		updatedAtEpochSeconds > nowEpochSeconds + MAX_CLOCK_SKEW_SECONDS
+	) {
+		throw new RequestError(400, "updatedAtEpochSeconds_out_of_range");
+	}
+	const currentTool = value.currentTool === undefined ? undefined : expectToolGlyph(value.currentTool, "currentTool");
+	const recentTools = value.recentTools.map((entry, index) => expectToolGlyph(entry, `recentTools_${index}`));
+	return {
+		status: expectOneOf(value.status, ["running", "completed", "failed", "waiting"], "status"),
+		statusText: expectString(value.statusText, "statusText", 1, 128),
+		...(currentTool === undefined ? {} : { currentTool }),
+		recentTools,
+		...(value.sessionID === undefined
+			? {}
+			: { sessionID: expectString(value.sessionID, "sessionID", 1, 128) }),
+		...(value.workspaceName === undefined
+			? {}
+			: { workspaceName: expectString(value.workspaceName, "workspaceName", 1, 128) }),
+		updatedAtEpochSeconds,
+	};
+}
+
+function expectToolGlyph(value, label) {
+	if (!isRecord(value)) {
+		throw new RequestError(400, `${label}_must_be_object`);
+	}
+	expectAllowedKeys(value, ["name", "symbolName", "status"], label);
+	return {
+		name: expectString(value.name, `${label}_name`, 1, 64),
+		symbolName: expectString(value.symbolName, `${label}_symbolName`, 1, 64),
+		status: expectOneOf(value.status, ["started", "completed", "failed"], `${label}_status`),
+	};
+}
+
+function assertVerifiedAppCheck(verification, allowedAppIds) {
+	if (!isRecord(verification) || typeof verification.appId !== "string") {
+		throw new RequestError(401, "app_check_invalid");
+	}
+	if (verification.alreadyConsumed !== false) {
+		throw new RequestError(401, "app_check_token_replayed");
+	}
+	if (!allowedAppIds.has(verification.appId)) {
+		throw new RequestError(403, "app_check_app_not_allowed");
+	}
+	const token = verification.token;
+	if (!isRecord(token) || typeof token.jti !== "string" || token.jti.length < 8 || token.jti.length > 256) {
+		throw new RequestError(401, "app_check_limited_use_token_required");
+	}
+	return verification.appId;
+}
+
+function getAllowedFirebaseAppIds(env = process.env) {
+	const configured = env.ALLOWED_FIREBASE_APP_IDS;
+	const values = (configured === undefined ? DEFAULT_ALLOWED_FIREBASE_APP_ID : configured)
+		.split(",")
+		.map((value) => value.trim())
+		.filter((value) => value.length > 0);
+	if (values.length === 0 || values.length > 8 || values.some((value) => value.length > 128)) {
+		throw new Error("ALLOWED_FIREBASE_APP_IDS must contain 1-8 comma-separated Firebase app IDs");
+	}
+	return new Set(values);
+}
+
+function getConfiguredRelayUrl(env = process.env) {
+	const configured = env.PUSH_RELAY_URL?.trim() || DEFAULT_PUBLIC_RELAY_URL;
+	let url;
+	try {
+		url = new URL(configured);
+	} catch {
+		throw new Error("PUSH_RELAY_URL must be a valid absolute HTTPS URL");
+	}
+	if (
+		url.protocol !== "https:" ||
+		url.username !== "" ||
+		url.password !== "" ||
+		url.search !== "" ||
+		url.hash !== ""
+	) {
+		throw new Error("PUSH_RELAY_URL must be an HTTPS URL without credentials, query, or fragment");
+	}
+	url.pathname = url.pathname.replace(/\/+$/, "");
+	return url.toString().replace(/\/$/, "");
+}
+
+function getPushTargetTtlMs(env = process.env) {
+	return getBoundedPositiveInteger(env.PUSH_TARGET_TTL_DAYS, 1, 90, DEFAULT_PUSH_TARGET_TTL_MS / 86_400_000) * 86_400_000;
+}
+
+function getPushTargetId(token) {
+	return `fcm_${createHash("sha256").update(token, "utf8").digest("base64url")}`;
+}
+
+function hashToken(token) {
+	return `sha256:${createHash("sha256").update(token, "utf8").digest("base64url")}`;
+}
+
+function timingSafeTokenHashMatches(token, expectedHash) {
+	if (typeof expectedHash !== "string") return false;
+	const actual = Buffer.from(hashToken(token), "utf8");
+	const expected = Buffer.from(expectedHash, "utf8");
+	return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+
+async function revokePushTargetTransaction(firestore, pushTargetRef, authToken) {
+	return firestore.runTransaction(async (transaction) => {
+		const snapshot = await transaction.get(pushTargetRef);
+		if (!snapshot.exists) return "already_revoked";
+		const pushTarget = snapshot.data();
+		if (!isRecord(pushTarget) || !timingSafeTokenHashMatches(authToken, pushTarget.pushTargetAuthTokenHash)) {
+			throw new RequestError(401, "unauthorized");
+		}
+		transaction.delete(pushTargetRef);
+		return "revoked";
+	});
+}
+
+function getTimestampMillis(value) {
+	if (isRecord(value) && typeof value.toMillis === "function") {
+		const millis = value.toMillis();
+		return Number.isFinite(millis) ? millis : undefined;
+	}
+	if (isRecord(value) && Number.isFinite(value.seconds)) {
+		return Number(value.seconds) * 1000;
+	}
+	if (value instanceof Date) return value.getTime();
+	return undefined;
+}
+
+function isPushTargetExpired(pushTarget, nowMs = Date.now()) {
+	const expiresAtMs = isRecord(pushTarget) ? getTimestampMillis(pushTarget.expiresAt) : undefined;
+	return expiresAtMs === undefined || expiresAtMs <= nowMs;
+}
+
+function getBoundedPositiveInteger(value, minimum, maximum, fallback) {
+	if (value === undefined || value === "") return fallback;
+	const parsed = Number(value);
+	if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) {
+		throw new Error(`configuration value must be an integer from ${minimum} through ${maximum}`);
+	}
+	return parsed;
+}
+
+function expectAllowedKeys(value, allowedKeys, label) {
+	const allowed = new Set(allowedKeys);
+	for (const key of Object.keys(value)) {
+		assertSafeObjectKey(key, label);
+		if (!allowed.has(key)) {
+			throw new RequestError(400, `${label}_has_unknown_field`);
+		}
+	}
+}
+
+function assertSafeObjectKey(key, label) {
+	if (key.length === 0 || key.length > 64 || FORBIDDEN_OBJECT_KEYS.has(key)) {
+		throw new RequestError(400, `${label}_has_invalid_key`);
+	}
+}
+
+function expectLiteral(value, expected, label) {
+	if (value !== expected) {
+		throw new RequestError(400, `${label}_must_be_${expected}`);
+	}
+	return expected;
+}
+
+function expectOneOf(value, expected, label) {
+	if (!expected.includes(value)) {
+		throw new RequestError(400, `${label}_must_be_${expected.join("_or_")}`);
+	}
+	return value;
+}
+
+function expectString(value, label, minimumLength, maximumLength) {
+	if (typeof value !== "string" || value.length < minimumLength || value.length > maximumLength) {
+		throw new RequestError(400, `${label}_has_invalid_length`);
+	}
+	if (/^[\s]*$/.test(value)) {
+		throw new RequestError(400, `${label}_must_not_be_blank`);
+	}
+	return value;
+}
+
+function expectOptionalString(value, label, minimumLength, maximumLength) {
+	if (value === undefined) return undefined;
+	return expectString(value, label, minimumLength, maximumLength);
+}
+
+function expectBoolean(value, label) {
+	if (typeof value !== "boolean") {
+		throw new RequestError(400, `${label}_must_be_boolean`);
+	}
+	return value;
+}
+
+function expectEpochSeconds(value, label) {
+	if (!Number.isSafeInteger(value) || value < 0) {
+		throw new RequestError(400, `${label}_must_be_non_negative_integer`);
+	}
+	return value;
+}
+
+function expectOptionalEpochSeconds(value, label, nowEpochSeconds) {
+	if (value === undefined) return undefined;
+	const parsed = expectEpochSeconds(value, label);
+	if (
+		parsed < nowEpochSeconds - MAX_CLOCK_SKEW_SECONDS ||
+		parsed > nowEpochSeconds + MAX_LIVE_ACTIVITY_FUTURE_SECONDS
+	) {
+		throw new RequestError(400, `${label}_out_of_range`);
+	}
+	return parsed;
+}
+
+function expectOptionalLiteral(value, expected, label) {
+	if (value === undefined) return undefined;
+	return expectOneOf(value, expected, label);
+}
+
+function expectStringRecord(value, label, options) {
+	if (!isRecord(value)) {
+		throw new RequestError(400, `${label}_must_be_object`);
+	}
+	const entries = Object.entries(value);
+	if (entries.length > options.maxEntries) {
+		throw new RequestError(400, `${label}_has_too_many_entries`);
+	}
+	const parsed = Object.create(null);
+	let encodedLength = 0;
+	for (const [key, entry] of entries) {
+		assertSafeObjectKey(key, label);
+		if (key.length > options.maxKeyLength || typeof entry !== "string" || entry.length > options.maxValueLength) {
+			throw new RequestError(400, `${label}_has_invalid_entry`);
+		}
+		encodedLength += key.length + entry.length;
+		if (encodedLength > 4096) {
+			throw new RequestError(400, `${label}_too_large`);
+		}
+		parsed[key] = entry;
+	}
+	return parsed;
+}
+
+function getHeader(request, name) {
+	const direct = request.get?.(name);
+	if (typeof direct === "string" && direct.length > 0) return direct;
+	const value = request.headers?.[name.toLowerCase()];
+	if (typeof value === "string") return value;
+	if (Array.isArray(value) && value.length === 1 && typeof value[0] === "string") return value[0];
+	return undefined;
+}
+
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+module.exports = {
+	DEFAULT_ALLOWED_FIREBASE_APP_ID,
+	DEFAULT_PUBLIC_RELAY_URL,
+	DEFAULT_PUSH_TARGET_TTL_MS,
+	MAX_REQUEST_BYTES,
+	RequestError,
+	assertRequestEnvelope,
+	assertVerifiedAppCheck,
+	getAllowedFirebaseAppIds,
+	getBoundedPositiveInteger,
+	getConfiguredRelayUrl,
+	getHeader,
+	getPushTargetId,
+	getPushTargetTtlMs,
+	hashToken,
+	isPushTargetExpired,
+	parseLiveActivityUpdate,
+	parseNotification,
+	parsePushTargetRegistration,
+	parsePushTargetRevocation,
+	readJsonBody,
+	revokePushTargetTransaction,
+	timingSafeTokenHashMatches,
+};