Unsafe OAuth Redirect URI Flag Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Replace OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS with FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI, preserving safe defaults and allowing any parseable redirect URI only when the flag is enabled.

Architecture: Keep OAuth redirect URI policy centralized in packages/utils/src/url-security.node.ts. Pass the new env flag from both Better Auth hook validation and the server auth preflight so both paths make identical decisions. Update env/docs references and tests in the same slice.

Tech Stack: TypeScript, Zod env schema, Better Auth hook middleware, Vitest, Turborepo env filtering, MDX docs.

File Structure

Modify packages/utils/src/url-security.node.ts: Change the OAuth redirect validator from allowlist-based to mode-based.
Modify packages/utils/src/url-security.node.test.ts: Update safe-mode tests and add unsafe-mode coverage.
Modify packages/env/src/server.ts: Remove the old allowlist env var and add FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI.
Modify packages/auth/src/config.ts: Remove host-list parsing and pass { allowUnsafe: env.FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI }.
Modify apps/server/src/http/auth.ts: Remove host-list parsing and pass the same flag to the validator.
Modify apps/server/src/http/auth.test.ts: Update env mock shape and preserve existing local edits.
Modify turbo.json, .env.example, and MDX docs: Replace old env references with the new flag and warnings.

Task 1: URL Policy Tests And Validator

Files:

Modify: packages/utils/src/url-security.node.test.ts
Modify: packages/utils/src/url-security.node.ts
Step 1: Write the failing safe/unsafe OAuth redirect tests

Use this shape in packages/utils/src/url-security.node.test.ts:

describe("isAllowedOAuthRedirectUri", () => {
	const trustedOrigins = ["https://app.example.com"];

	it("returns false for malformed URI", () => {
		expect(isAllowedOAuthRedirectUri("nope", trustedOrigins)).toBe(false);
	});

	it("returns true for any parseable URI when unsafe mode is enabled", () => {
		const options = { allowUnsafe: true };

		expect(isAllowedOAuthRedirectUri("myapp://callback", trustedOrigins, options)).toBe(true);
		expect(isAllowedOAuthRedirectUri("http://example.com/cb", trustedOrigins, options)).toBe(true);
		expect(isAllowedOAuthRedirectUri("https://192.168.1.1/cb", trustedOrigins, options)).toBe(true);
		expect(isAllowedOAuthRedirectUri("https://u:[email protected]/cb#x", trustedOrigins, options)).toBe(true);
		expect(isAllowedOAuthRedirectUri("not a url", trustedOrigins, options)).toBe(false);
	});
});

Step 2: Run the focused utils test and verify it fails

Run: pnpm --filter @reactive-resume/utils test -- src/url-security.node.test.ts

Expected before implementation: TypeScript/test failure because isAllowedOAuthRedirectUri still requires the removed allowlist argument.

Step 3: Implement mode-based OAuth redirect validation

Use this signature in packages/utils/src/url-security.node.ts:

type OAuthRedirectUriOptions = {
	allowUnsafe?: boolean;
};

export function isAllowedOAuthRedirectUri(
	input: string,
	trustedOrigins: string[],
	options?: OAuthRedirectUriOptions,
) {
	const parsed = parseUrl(input);
	if (!parsed) return false;
	if (options?.allowUnsafe) return true;
	if (parsed.username || parsed.password) return false;
	if (parsed.hash) return false;

	const origin = parsed.origin.toLowerCase();
	const hostname = normalizeHostname(parsed.hostname);

	if (parsed.protocol === "http:") return isOAuthLoopbackRedirectHost(hostname);
	if (parsed.protocol !== "https:") return false;
	if (isPrivateOrLoopbackHost(hostname)) return false;

	return trustedOrigins.includes(origin);
}

Step 4: Run the focused utils test and verify it passes

Run: pnpm --filter @reactive-resume/utils test -- src/url-security.node.test.ts

Expected after implementation: all tests in url-security.node.test.ts pass.

Task 2: Env And Runtime Wiring

Files:

Modify: packages/env/src/server.ts
Modify: packages/auth/src/config.ts
Modify: apps/server/src/http/auth.ts
Modify: apps/server/src/http/auth.test.ts
Modify: turbo.json
Step 1: Update env schema and Turbo env list

In packages/env/src/server.ts, remove:

OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS: z.string().optional(),

Add with feature flags:

FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI: z.stringbool().default(false),

In turbo.json, remove "OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS" and add "FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI" beside the other flags.

Step 2: Wire the flag into Better Auth config

In packages/auth/src/config.ts, remove parseAllowedHostList usage and call:

if (
	!isAllowedOAuthRedirectUri(uri, TRUSTED_ORIGINS, {
		allowUnsafe: env.FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI,
	})
) {
	throw new APIError("BAD_REQUEST", {
		message: "redirect_uri is not allowed for dynamic client registration",
	});
}

Step 3: Wire the flag into server preflight

In apps/server/src/http/auth.ts, remove parseAllowedHostList usage and call:

!isAllowedOAuthRedirectUri(redirectUri, oauthTrustedOrigins, {
	allowUnsafe: env.FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI,
})

Update the test env mock in apps/server/src/http/auth.test.ts:

env: {
	SERVER_PORT: 3001,
	APP_URL: "http://localhost:3000",
	FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI: false,
},

Step 4: Run focused typechecks

Run:

pnpm --filter @reactive-resume/auth typecheck
pnpm --filter server typecheck

Expected: both commands exit 0.

Task 3: Docs And Env Examples

Files:

Modify: .env.example
Modify: docs/self-hosting/docker.mdx
Modify: docs/self-hosting/sso.mdx
Modify: docs/getting-started/quickstart.mdx
Step 1: Replace old env docs with the new flag

Remove all OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS references.

Add this warning wherever feature flags are documented:

`FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI`: Allows dynamic OAuth client registration to use any parseable redirect URI, including custom schemes, private hosts, and non-loopback `http://` URLs. Keep disabled unless this is a trusted self-hosted deployment. Enabling it on public or multi-tenant instances can enable phishing or token exfiltration.

Step 2: Verify the removed env is gone from product code and docs

Run: rg -n "OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS" . --glob "!docs/superpowers/**"

Expected: no matches outside the approved design and implementation plan documents.

Run: rg -n "FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI" .

Expected: matches in env schema, Turbo config, docs, tests, and runtime validation paths.

Task 4: Final Verification

Files:

Verify all modified files.
Step 1: Run focused tests

Run:

pnpm --filter @reactive-resume/utils test -- src/url-security.node.test.ts
pnpm --filter server test -- src/http/auth.test.ts

Expected: both commands exit 0.

Step 2: Run focused typechecks and boundaries

Run:

pnpm --filter @reactive-resume/auth typecheck
pnpm --filter server typecheck
pnpm exec turbo boundaries

Expected: all commands exit 0.