@obsunified/collector 2.2.1 → 2.3.0

package/src/__tests__/internal-contracts-routes.test.ts

@@ -0,0 +1,451 @@
+import {
+	ContractMismatchError,
+	createInternalClient,
+	InternalClientHttpError,
+	type InternalEndpoints,
+} from "@obsunified/types";
+import { Hono } from "hono";
+import { describe, expect, it } from "vitest";
+import { CollectorRuntime } from "../framework/collector";
+import type { CollectorEnv } from "../framework/env";
+import { upsertOntologyFromSpans } from "../lib/autosre-ontology";
+import {
+	createMigratedSqliteDb,
+	type NodeSqliteDb,
+} from "../lib/test-utils/node-sqlite-db";
+import { aiReceiverPlugin } from "../plugins/ai-receiver";
+import {
+	autosreRoutesPlugin,
+	respondWithContract,
+} from "../plugins/autosre-routes";
+import { connectedRoutesPlugin } from "../plugins/connected-routes";
+import { evalCasesRoutesPlugin } from "../plugins/eval-cases-routes";
+import { evidenceRetrievalRoutesPlugin } from "../plugins/evidence-retrieval-routes";
+
+const createTestApp = (db: NodeSqliteDb) => {
+	const app = new Hono<{ Bindings: CollectorEnv }>();
+	const runtime = new CollectorRuntime();
+	autosreRoutesPlugin.register(app, runtime);
+	evalCasesRoutesPlugin.register(app, runtime);
+	connectedRoutesPlugin.register(app, runtime);
+	evidenceRetrievalRoutesPlugin.register(app, runtime);
+	aiReceiverPlugin.register(app, runtime);
+	const env: CollectorEnv = {
+		DB: db as unknown as D1Database,
+	};
+	return { app, env };
+};
+
+describe("Collector internal HTTP contract integration (RFC 0014 WS5)", () => {
+	it("respondWithContract throws ContractMismatchError if a handler attempts to return a mistyped payload", () => {
+		const fakeContext = {
+			json: (data: unknown, status = 200) =>
+				new Response(JSON.stringify(data), { status }),
+		};
+		expect(() =>
+			respondWithContract(
+				fakeContext,
+				"GET /internal/incidents",
+				// Intentionally mistyped payload
+				{
+					incidents: "not-an-array",
+				} as unknown as InternalEndpoints["GET /internal/incidents"]["response"],
+			),
+		).toThrow(ContractMismatchError);
+	});
+
+	it("createInternalClient round-trips changes, incidents, findings, counterfactuals, remediations, evals, connected, AI calls, and evidence against collector routes", async () => {
+		const db = createMigratedSqliteDb();
+		const { app, env } = createTestApp(db);
+
+		const makeClient = (defaultHeaders?: Record<string, string>) =>
+			createInternalClient({
+				baseUrl: "http://localhost",
+				defaultHeaders,
+				fetchImpl: (input, init) => app.request(input, init, env),
+			});
+
+		const client = makeClient();
+
+		// Seed a trace + span so eval cases and ontology have a source entity
+		db.raw
+			.prepare(
+				`INSERT INTO telemetry_spans (
+					project_id, trace_id, span_id, parent_span_id, service_name,
+					span_name, span_kind, start_time, end_time, duration_ms,
+					status_code, status_message, attributes_json, resource_attributes_json,
+					events_json, links_json, received_at, expires_at,
+					environment, service_version, commit_sha, target_node_id, error_signature
+				) VALUES (
+					'default', 'trace-ws5', 'span-ws5', NULL, 'checkout',
+					'POST /charge', 2, '2026-04-16T00:00:00.000Z', '2026-04-16T00:00:00.500Z', 500,
+					2, 'Timeout', '{}', '{}',
+					'[]', '[]', '2026-04-16T00:00:00.500Z', '2099-01-01T00:00:00.000Z',
+					'production', '2.1.0', 'abc1234', 'service:default:checkout', 'Timeout'
+				)`,
+			)
+			.run();
+		await upsertOntologyFromSpans(db, [
+			{
+				projectId: "default",
+				traceId: "trace-ws5",
+				spanId: "span-ws5",
+				parentSpanId: null,
+				traceState: null,
+				serviceName: "checkout",
+				spanName: "POST /charge",
+				spanKind: 2,
+				statusCode: 2,
+				statusMessage: "Timeout",
+				startTime: "2026-04-16T00:00:00.000Z",
+				endTime: "2026-04-16T00:00:00.500Z",
+				durationMs: 500,
+				environment: "prod",
+				scopeName: null,
+				scopeVersion: null,
+				attributesJson: "{}",
+				resourceAttributesJson: "{}",
+				eventsJson: "[]",
+				linksJson: "[]",
+				droppedAttributesCount: 0,
+				droppedEventsCount: 0,
+				droppedLinksCount: 0,
+				receivedAt: "2026-04-16T00:00:00.500Z",
+				expiresAt: "2099-01-01T00:00:00.000Z",
+			},
+		]);
+
+		// 1. Changes
+		const createdChange = await client.request("POST /v1/changes", {
+			body: {
+				environment: "prod",
+				kind: "deploy",
+				serviceName: "checkout",
+				version: "2.1.0",
+				previousVersion: "2.0.0",
+				commitSha: "abc1234",
+				summary: "Deploy checkout 2.1.0",
+			},
+		});
+		expect(createdChange.id).toBeTruthy();
+		expect(createdChange.change.id).toBe(createdChange.id);
+		expect(createdChange.changeEvent?.id).toBe(createdChange.id);
+
+		const listedChanges = await client.request("GET /internal/changes", {
+			query: { environment: "prod", serviceName: "checkout" },
+		});
+		expect(listedChanges.changes.some((c) => c.id === createdChange.id)).toBe(
+			true,
+		);
+
+		const fetchedChange = await client.request("GET /internal/changes/:id", {
+			params: { id: createdChange.id },
+		});
+		expect(fetchedChange.change.id).toBe(createdChange.id);
+
+		const blastRadius = await client.request(
+			"GET /internal/changes/:id/blast-radius",
+			{
+				params: { id: createdChange.id },
+			},
+		);
+		expect(blastRadius.change.id).toBe(createdChange.id);
+		expect(blastRadius.blastRadius.change.id).toBe(createdChange.id);
+
+		// 2. Ontology
+		const ontology = await client.request("GET /internal/ontology", {
+			query: { environment: "prod", traceId: "trace-ws5" },
+		});
+		expect(Array.isArray(ontology.nodes)).toBe(true);
+
+		// 3. Incidents (both /internal/incidents and /internal/incidents/open)
+		const openedIncident = await client.request("POST /internal/incidents", {
+			body: {
+				environment: "prod",
+				targetNodeId: "service:default:checkout",
+				symptomAnchorKind: "trace",
+				symptomAnchorId: "trace-ws5",
+				symptomFingerprint: "fp-checkout-timeout",
+			},
+		});
+		expect(openedIncident.deduplicated).toBe(false);
+
+		const dedupedIncident = await client.request(
+			"POST /internal/incidents/open",
+			{
+				body: {
+					environment: "prod",
+					targetNodeId: "service:default:checkout",
+					symptomAnchorKind: "trace",
+					symptomAnchorId: "trace-ws5",
+					symptomFingerprint: "fp-checkout-timeout",
+				},
+			},
+		);
+		expect(dedupedIncident.deduplicated).toBe(true);
+		expect(dedupedIncident.incident.id).toBe(openedIncident.incident.id);
+
+		const leaseResult = await client.request(
+			"POST /internal/incidents/:id/lease",
+			{
+				params: { id: openedIncident.incident.id },
+				body: {
+					runnerId: "runner-ws5",
+					leaseDurationSeconds: 120,
+				},
+			},
+		);
+		expect(leaseResult.acquired).toBe(true);
+
+		const incidentsList = await client.request("GET /internal/incidents", {
+			query: { environment: "prod" },
+		});
+		expect(
+			incidentsList.incidents.some((i) => i.id === openedIncident.incident.id),
+		).toBe(true);
+
+		// 4. Findings & Counterfactuals
+		const createdFinding = await client.request("POST /internal/findings", {
+			body: {
+				environment: "prod",
+				incidentId: openedIncident.incident.id,
+				title: "Checkout timeout after 2.1.0 deploy",
+				summary: "Cohort isolated to version 2.1.0",
+				symptomEntityKind: "trace",
+				symptomEntityId: "trace-ws5",
+				faultLocusEntityKind: "span",
+				faultLocusEntityId: "trace-ws5:span-ws5",
+				rootCauseEntityKind: "change",
+				rootCauseEntityId: createdChange.id,
+				contributingChangeId: createdChange.id,
+				causalChain: [
+					{
+						subjectKind: "change",
+						subjectId: createdChange.id,
+						predicate: "degraded_after_change",
+						objectKind: "span",
+						objectId: "trace-ws5:span-ws5",
+						relationshipCertainty: "exact",
+						causalProofTier: "corroborated_candidate",
+						confidence: 0.9,
+						reason: "Version 2.1.0 deployed immediately before errors",
+					},
+				],
+				citedEvidenceIds: [`change:${createdChange.id}`, "trace:trace-ws5"],
+			},
+		});
+		expect(createdFinding.finding.id).toBe(createdFinding.id);
+
+		const fetchedFinding = await client.request("GET /internal/findings/:id", {
+			params: { id: createdFinding.id },
+		});
+		expect(fetchedFinding.finding.id).toBe(createdFinding.id);
+
+		const findingsList = await client.request("GET /internal/findings", {
+			query: { incidentId: openedIncident.incident.id },
+		});
+		expect(findingsList.findings.some((f) => f.id === createdFinding.id)).toBe(
+			true,
+		);
+
+		// Eval case + runs for counterfactual verification
+		const createdCase = await client.request("POST /internal/eval-cases", {
+			body: {
+				sourceEntityType: "trace",
+				sourceEntityId: "trace-ws5",
+				name: "Checkout timeout regression case",
+			},
+		});
+		expect(createdCase.evalCase.id).toBeTruthy();
+
+		const listedCases = await client.request("GET /internal/eval-cases", {
+			query: { sourceEntityType: "trace" },
+		});
+		expect(
+			listedCases.evalCases.some((ec) => ec.id === createdCase.evalCase.id),
+		).toBe(true);
+
+		const failingRun = await client.request("POST /internal/eval-runs", {
+			body: {
+				evalCaseId: createdCase.evalCase.id,
+				status: "failed",
+				environment: "prod",
+				serviceVersion: "2.1.0",
+				commitSha: "abc1234",
+				inputPayloadHash: "hash-ws5",
+				failureFingerprint: createdFinding.finding.fingerprint,
+				totalCount: 1,
+				passCount: 0,
+				failCount: 1,
+			},
+		});
+		await client.request("POST /internal/eval-cases/:id/results", {
+			params: { id: createdCase.evalCase.id },
+			body: {
+				runId: failingRun.evalRun.id,
+				passed: false,
+				inputPayloadHash: "hash-ws5",
+				failureFingerprint: createdFinding.finding.fingerprint,
+			},
+		});
+
+		const passingRunIds: string[] = [];
+		for (let i = 0; i < 3; i += 1) {
+			const passRun = await client.request("POST /internal/eval-runs", {
+				body: {
+					evalCaseId: createdCase.evalCase.id,
+					status: "completed",
+					environment: "prod",
+					serviceVersion: "2.0.0",
+					commitSha: "prev000",
+					inputPayloadHash: "hash-ws5",
+					totalCount: 1,
+					passCount: 1,
+					failCount: 0,
+				},
+			});
+			await client.request("POST /internal/eval-cases/:id/results", {
+				params: { id: createdCase.evalCase.id },
+				body: {
+					runId: passRun.evalRun.id,
+					passed: true,
+					inputPayloadHash: "hash-ws5",
+				},
+			});
+			passingRunIds.push(passRun.evalRun.id);
+		}
+
+		const evalRunSummary = await client.request(
+			"GET /internal/evals/runs/:id",
+			{
+				params: { id: failingRun.evalRun.id },
+			},
+		);
+		expect(evalRunSummary.run.id).toBe(failingRun.evalRun.id);
+
+		const counterfactual = await client.request(
+			"POST /internal/findings/:id/counterfactual",
+			{
+				params: { id: createdFinding.id },
+				body: {
+					environment: "prod",
+					evalCaseId: createdCase.evalCase.id,
+					failingRunId: failingRun.evalRun.id,
+					passingRunIds,
+				},
+			},
+		);
+		expect(counterfactual.verified).toBe(true);
+		expect(counterfactual.finding.causalProofTier).toBe(
+			"counterfactual_verified",
+		);
+
+		// 5. Remediations
+		const proposedHuman = await client.request(
+			"POST /internal/remediations/propose",
+			{
+				body: {
+					environment: "prod",
+					incidentId: openedIncident.incident.id,
+					findingId: createdFinding.id,
+					idempotencyKey: "idem-ws5-human",
+					actionKind: "rollback_deploy",
+					targetNodeId: "service:default:checkout",
+					expectedCurrentState: { version: "2.1.0" },
+					desiredTargetState: { version: "2.0.0" },
+					requestedAutonomy: "human_approved_write",
+				},
+			},
+		);
+		expect(proposedHuman.proposal.status).toBe("pending_human_approval");
+
+		// Bearer token approval must fail with 403 InternalClientHttpError
+		const bearerClient = makeClient({
+			Authorization: "Bearer obs_secret_agent_token",
+		});
+		await expect(
+			bearerClient.request("POST /internal/remediations/:id/approve", {
+				params: { id: proposedHuman.proposal.id },
+				body: {},
+			}),
+		).rejects.toThrow(InternalClientHttpError);
+
+		// Cookie session approval succeeds and mints grantToken
+		const humanSessionClient = makeClient({
+			Cookie: "obs_session=valid_human_session_cookie",
+		});
+		const approved = await humanSessionClient.request(
+			"POST /internal/remediations/:id/approve",
+			{
+				params: { id: proposedHuman.proposal.id },
+				body: {},
+			},
+		);
+		expect(approved.proposal.status).toBe("grant_issued");
+		expect(typeof approved.grantToken).toBe("string");
+
+		const claimed = await client.request(
+			"POST /internal/remediations/:id/claim",
+			{
+				params: { id: proposedHuman.proposal.id },
+				body: {
+					grantToken: approved.grantToken as string,
+					runnerId: "runner-ws5",
+				},
+			},
+		);
+		expect(claimed.claimed).toBe(true);
+		expect(claimed.proposal.status).toBe("claimed_executing");
+
+		const completed = await client.request(
+			"POST /internal/remediations/:id/complete",
+			{
+				params: { id: proposedHuman.proposal.id },
+				body: {
+					runnerId: "runner-ws5",
+					resultingChangeId: createdChange.id,
+				},
+			},
+		);
+		expect(completed.proposal.status).toBe("completed");
+
+		const watchdog = await client.request(
+			"POST /internal/remediations/watchdog",
+			{
+				body: {},
+			},
+		);
+		expect(typeof watchdog.summary.evaluated).toBe("number");
+
+		const incidentDetail = await client.request("GET /internal/incidents/:id", {
+			params: { id: openedIncident.incident.id },
+		});
+		expect(incidentDetail.incident.id).toBe(openedIncident.incident.id);
+		expect(incidentDetail.findings.length).toBeGreaterThanOrEqual(1);
+		expect(incidentDetail.proposals.length).toBeGreaterThanOrEqual(1);
+
+		// 6. Connected, Evidence Bundle, Evidence Stats
+		const connected = await client.request(
+			"GET /internal/connected/:kind/:id",
+			{
+				params: { kind: "incident", id: openedIncident.incident.id },
+			},
+		);
+		expect(connected.entity.id).toBe(openedIncident.incident.id);
+
+		const bundle = await client.request("POST /internal/evidence/bundle", {
+			body: {
+				anchor: {
+					entityKind: "incident",
+					entityId: openedIncident.incident.id,
+				},
+			},
+		});
+		expect(bundle.schemaVersion).toBe("obs-unified.evidence-bundle.v1");
+
+		const stats = await client.request("GET /internal/evidence/stats", {
+			query: { limit: 10 },
+		});
+		expect(stats.projectId).toBe("default");
+	});
+});

package/src/auth/dashboard-auth.test.ts

@@ -789,3 +789,64 @@ describe("dashboard-auth middleware & programmatic token contract", () => {
 		});
 	});
 });
+
+describe("session cookie Secure attribute", () => {
+	const loginCookie = async (
+		url: string,
+		headers: Record<string, string>,
+		trustProxyHeaders: boolean | undefined,
+	): Promise<string> => {
+		const auth = createDashboardAuth({
+			password: TEST_PASSWORD,
+			token: TEST_TOKEN,
+			loginRateLimit: { trustProxyHeaders, warn: () => {} },
+		});
+		const app = new Hono<{ Bindings: CollectorEnv }>();
+		auth.registerRoutes(app);
+		const res = await app.fetch(
+			new Request(url, {
+				method: "POST",
+				headers: { "Content-Type": "application/json", ...headers },
+				body: JSON.stringify({ password: TEST_PASSWORD }),
+			}),
+			makeEnv(createTestDb()),
+		);
+		expect(res.status).toBe(200);
+		return res.headers.get("Set-Cookie") ?? "";
+	};
+
+	it("sets Secure for an https request URL", async () => {
+		expect(await loginCookie("https://x.test/auth/login", {}, false)).toContain(
+			"; Secure",
+		);
+	});
+
+	it("sets Secure for X-Forwarded-Proto: https when the proxy is trusted", async () => {
+		const cookie = await loginCookie(
+			"http://x.test/auth/login",
+			{ "x-forwarded-proto": "https" },
+			true,
+		);
+		expect(cookie).toContain("; Secure");
+	});
+
+	it("ignores X-Forwarded-Proto when the proxy is not trusted, and on plain http", async () => {
+		expect(
+			await loginCookie(
+				"http://x.test/auth/login",
+				{ "x-forwarded-proto": "https" },
+				undefined,
+			),
+		).not.toContain("Secure");
+		expect(
+			await loginCookie(
+				"http://x.test/auth/login",
+				{ "x-forwarded-proto": "http" },
+				true,
+			),
+		).not.toContain("Secure");
+		expect(
+			await loginCookie("http://x.test/auth/login", {}, true),
+		).not.toContain("Secure");
+	});
+});

package/src/auth/dashboard-auth.ts

@@ -293,6 +293,21 @@ export function createDashboardAuth(config?: DashboardAuthConfig): {
 				: new LoginRateLimiter(config?.loginRateLimit ?? {});
 		let warnedUnkeyedClient = false;
 
+		// `Secure` when the request itself is https, or when the operator
+		// declared a trusted TLS-terminating proxy (`trustProxyHeaders`, i.e.
+		// TRUST_PROXY) that reports `X-Forwarded-Proto: https`.
+		const isSecureRequest = (
+			c: Context<{ Bindings: CollectorEnv }>,
+			limitConfig: { trustProxyHeaders?: boolean } | undefined,
+		): boolean =>
+			c.req.url.startsWith("https:") ||
+			(limitConfig?.trustProxyHeaders === true &&
+				c.req
+					.header("x-forwarded-proto")
+					?.split(",")[0]
+					?.trim()
+					.toLowerCase() === "https");
+
 		app.post("/auth/login", async (c) => {
 			const configuredPassword = config?.password ?? c.env.DASHBOARD_PASSWORD;
 			if (!configuredPassword) {
@@ -342,7 +357,7 @@ export function createDashboardAuth(config?: DashboardAuthConfig): {
 			const sig = await sign(payload, configuredPassword);
 			const cookieValue = `${payload}.${sig}`;
 
-			const isSecure = c.req.url.startsWith("https:");
+			const isSecure = isSecureRequest(c, config?.loginRateLimit || undefined);
 			c.header(
 				"Set-Cookie",
 				`${SESSION_COOKIE}=${encodeURIComponent(cookieValue)}; Path=/; HttpOnly; SameSite=Strict; Max-Age=${SESSION_MAX_AGE}${isSecure ? "; Secure" : ""}`,
@@ -405,7 +420,7 @@ export function createDashboardAuth(config?: DashboardAuthConfig): {
 		});
 
 		app.post("/auth/logout", (c) => {
-			const isSecure = c.req.url.startsWith("https:");
+			const isSecure = isSecureRequest(c, config?.loginRateLimit || undefined);
 			c.header(
 				"Set-Cookie",
 				`${SESSION_COOKIE}=; Path=/; HttpOnly; SameSite=Strict; Max-Age=0${isSecure ? "; Secure" : ""}`,

package/src/framework/env.ts

@@ -89,6 +89,111 @@ export interface CollectorEnv {
 	TELEMETRY_QUERY_TOKEN?: string;
 }
 
+/**
+ * Optional string settings on `CollectorEnv` that host adapters (such as
+ * `apps/collector-node`) forward directly from the process environment after
+ * trimming whitespace and coercing blank strings to `undefined`.
+ */
+export const COLLECTOR_OPTIONAL_STRING_ENV_KEYS = [
+	"RETENTION_HOURS",
+	"ANTHROPIC_API_KEY",
+	"OPENAI_API_KEY",
+	"OPENAI_BASE_URL",
+	"NARRATIVE_MODEL",
+	"NARRATIVE_BUDGET_PER_HOUR",
+	"ALERT_WEBHOOK_ALLOW_PRIVATE",
+	"MAX_BODY_BYTES",
+	"TELEMETRY_REDACT_FIELDS",
+	"OBS_PAYLOAD_CAPTURE_DEFAULT",
+] as const;
+
+/**
+ * String settings on `CollectorEnv` that require explicit host handling (e.g.
+ * required auth secrets, CORS origin parsing, Worker-only self-instrumentation
+ * vars, or deprecated Worker tokens) and must not be blindly forwarded by the
+ * generic optional-env loop.
+ */
+export const COLLECTOR_HOST_MANAGED_ENV_KEYS = [
+	"INGEST_KEY",
+	"DASHBOARD_PASSWORD",
+	"DASHBOARD_TOKEN",
+	"ALLOWED_ORIGINS",
+	"ALLOW_UNAUTHENTICATED",
+	"OBS_DASHBOARD_INGEST_KEY",
+	"OBS_COLLECTOR_SELF_URL",
+	"OBS_SELF_AWAIT_EXPORTS",
+	"TELEMETRY_INGEST_TOKEN",
+	"USAGE_INGEST_TOKEN",
+	"TELEMETRY_QUERY_TOKEN",
+] as const;
+
+export const COLLECTOR_STRING_ENV_MANIFEST = {
+	forwarded: COLLECTOR_OPTIONAL_STRING_ENV_KEYS,
+	hostManaged: COLLECTOR_HOST_MANAGED_ENV_KEYS,
+} as const;
+
+export type CollectorOptionalStringEnvKey =
+	(typeof COLLECTOR_OPTIONAL_STRING_ENV_KEYS)[number];
+
+export type CollectorHostManagedEnvKey =
+	(typeof COLLECTOR_HOST_MANAGED_ENV_KEYS)[number];
+
+export type CollectorManifestStringEnvKey =
+	| CollectorOptionalStringEnvKey
+	| CollectorHostManagedEnvKey;
+
+export type CollectorObjectBindingKey =
+	| "DB"
+	| "REPLAYS_BUCKET"
+	| "PROFILES_BUCKET"
+	| "TAIL_HUB";
+
+export type CollectorStringEnvKey = Exclude<
+	keyof CollectorEnv,
+	CollectorObjectBindingKey
+>;
+
+type AssertNever<T extends never> = T;
+type _UnaccountedCollectorStringEnvKeys = AssertNever<
+	Exclude<CollectorStringEnvKey, CollectorManifestStringEnvKey>
+>;
+type _UnknownManifestStringEnvKeys = AssertNever<
+	Exclude<CollectorManifestStringEnvKey, CollectorStringEnvKey>
+>;
+type _OverlappingManifestStringEnvKeys = AssertNever<
+	Extract<CollectorOptionalStringEnvKey, CollectorHostManagedEnvKey>
+>;
+
+/**
+ * Verifies that every string key in `declaredKeys` is categorized in either
+ * `COLLECTOR_OPTIONAL_STRING_ENV_KEYS` or `COLLECTOR_HOST_MANAGED_ENV_KEYS`
+ * without overlap. Throws if any key is uncategorized or duplicated.
+ */
+export function assertCollectorEnvManifestCompleteness(
+	declaredKeys: readonly string[],
+	manifest: {
+		readonly forwarded: readonly string[];
+		readonly hostManaged: readonly string[];
+	} = COLLECTOR_STRING_ENV_MANIFEST,
+): void {
+	const forwardedSet = new Set(manifest.forwarded);
+	const hostManagedSet = new Set(manifest.hostManaged);
+	const overlap = manifest.forwarded.filter((k) => hostManagedSet.has(k));
+	if (overlap.length > 0) {
+		throw new Error(
+			`CollectorEnv manifest keys cannot be both forwarded and host-managed: ${overlap.join(", ")}`,
+		);
+	}
+	const unaccounted = declaredKeys.filter(
+		(k) => !forwardedSet.has(k) && !hostManagedSet.has(k),
+	);
+	if (unaccounted.length > 0) {
+		throw new Error(
+			`Uncategorized CollectorEnv string setting(s): ${unaccounted.join(", ")}. Add each key to COLLECTOR_OPTIONAL_STRING_ENV_KEYS or COLLECTOR_HOST_MANAGED_ENV_KEYS.`,
+		);
+	}
+}
+
 export interface CollectorRouteContext {
 	hono: Context<{ Bindings: CollectorEnv }>;
 	env: CollectorEnv;

package/src/index.ts

@@ -68,10 +68,19 @@ export {
 	type UsageEventProcessorPlugin,
 } from "./framework/collector";
 
-export type {
-	CollectorApp,
-	CollectorEnv,
-	CollectorRouteContext,
+export {
+	assertCollectorEnvManifestCompleteness,
+	COLLECTOR_HOST_MANAGED_ENV_KEYS,
+	COLLECTOR_OPTIONAL_STRING_ENV_KEYS,
+	COLLECTOR_STRING_ENV_MANIFEST,
+	type CollectorApp,
+	type CollectorEnv,
+	type CollectorHostManagedEnvKey,
+	type CollectorManifestStringEnvKey,
+	type CollectorObjectBindingKey,
+	type CollectorOptionalStringEnvKey,
+	type CollectorRouteContext,
+	type CollectorStringEnvKey,
 } from "./framework/env";
 
 export type { Logger } from "./framework/logger";