Strengthen source-control provider foundation (#72)

* feat: add single-provider scm guardrails

* refactor: apply scm provider review feedback

Author: ColeMurray

CONTRIBUTING.md

@@ -67,6 +67,13 @@ Use clear, descriptive commit messages:
 4. Update documentation if needed
 5. Provide a clear description of your changes
 
+### Source Control Provider Contributions
+
+For SCM/provider changes, follow:
+
+- `docs/adr/0001-single-provider-scm-boundaries.md`
+- `docs/provider-contribution-checklist.md`
+
 ## Reporting Issues
 
 When reporting issues, please include:

docs/adr/0001-single-provider-scm-boundaries.md

@@ -0,0 +1,50 @@
+# ADR 0001: Single-Provider SCM Deployment and Boundary Rules
+
+## Status
+
+Accepted
+
+## Context
+
+Open-Inspect currently runs with GitHub as the only production SCM integration, while external
+contributors have requested Bitbucket support. The codebase already has a `SourceControlProvider`
+abstraction, but GitHub-specific details can still leak into non-provider layers if not guarded.
+
+The team decision is to keep deployments single-provider. We need a safe foundation that preserves
+existing GitHub behavior and prevents unsafe coupling during future provider contributions.
+
+## Decision
+
+1. **Single provider per deployment**
+   - Deployment config (`SCM_PROVIDER`) selects the provider.
+   - No per-session provider state is persisted.
+
+2. **Fail fast for unimplemented providers**
+   - If `SCM_PROVIDER` resolves to a provider without implementation (currently `bitbucket`),
+     control-plane returns explicit `501 Not Implemented` responses for non-public routes.
+
+3. **Provider/auth boundary rules**
+   - Provider-specific PR URL and push-transport construction must live in provider implementations.
+   - Direct GitHub API base URL usage is limited to approved auth/provider modules.
+
+4. **Guardrails enforced by code review + focused tests**
+   - Provider boundary expectations are documented and validated through provider/factory tests.
+
+## Consequences
+
+### Positive
+
+- Minimizes migration risk by avoiding schema/API expansion.
+- Keeps GitHub paths stable and auditable.
+- Gives contributors a clear and safe insertion point for future providers.
+
+### Negative
+
+- Multi-provider-per-deployment use cases are intentionally unsupported.
+- A future shift to multi-provider would require a new ADR and migration plan.
+
+## Follow-Up Rules for Provider Contributions
+
+- Add new provider logic under `packages/control-plane/src/source-control/providers`.
+- Register provider in factory and env resolver.
+- Do not add provider-specific URL/token logic to router/session/slack layers.

docs/provider-contribution-checklist.md

@@ -0,0 +1,35 @@
+# Provider Contribution Checklist
+
+Use this checklist before opening a pull request for a new source-control provider.
+
+## Architecture Checklist
+
+- [ ] Provider implementation lives under `packages/control-plane/src/source-control/providers`.
+- [ ] Provider factory (`createSourceControlProvider`) has an explicit case for the new provider.
+- [ ] Deployment resolver (`SCM_PROVIDER`) recognizes the new provider name.
+- [ ] No provider-specific URL/token construction was added to router/session/slack layers.
+
+## Auth and API Checklist
+
+- [ ] User-authenticated repository lookup and PR creation are implemented via
+      `SourceControlProvider`.
+- [ ] Push auth/token generation is implemented via provider auth path (not session/router
+      hardcoding).
+- [ ] Manual PR fallback URL is built via provider method (`buildManualPullRequestUrl`).
+- [ ] Push transport spec is built via provider method (`buildGitPushSpec`).
+
+## Tests Checklist
+
+- [ ] Provider factory tests cover selection and unsupported behavior.
+- [ ] Provider implementation tests cover:
+  - [ ] manual PR URL building
+  - [ ] push spec building
+  - [ ] basic API mapping behavior
+- [ ] Existing create-PR branch consistency tests still pass.
+- [ ] Slack manual-PR button tests still pass.
+- [ ] No provider-specific URL/token logic is introduced outside provider/auth modules.
+
+## Documentation Checklist
+
+- [ ] Control-plane README documents any new provider-related env vars or constraints.
+- [ ] ADR updated or added when architecture assumptions change.

packages/control-plane/README.md

@@ -220,6 +220,12 @@ All secrets are configured via Terraform. Required secrets include:
 - `GITHUB_APP_INSTALLATION_ID` - Single installation for all users
 - `REPO_SECRETS_ENCRYPTION_KEY` - AES-GCM key for encrypting repo secrets in D1
 
+Optional variables:
+
+- `SCM_PROVIDER` - Source control provider for this deployment (`github` or `bitbucket`, default:
+  `github`). Current implementation supports `github` only; `bitbucket` returns explicit
+  `501 Not Implemented` responses until implemented.
+
 See
 [terraform/environments/production/terraform.tfvars.example](../../terraform/environments/production/terraform.tfvars.example)
 for the complete list.

packages/control-plane/src/router.ts

@@ -10,6 +10,11 @@ import {
   getInstallationRepository,
   listInstallationRepositories,
 } from "./auth/github-app";
+import {
+  resolveScmProviderFromEnv,
+  SourceControlProviderError,
+  type SourceControlProviderName,
+} from "./source-control";
 import { RepoSecretsStore, RepoSecretsValidationError } from "./db/repo-secrets";
 import { SessionIndexStore } from "./db/session-index";
 
@@ -89,6 +94,18 @@ function error(message: string, status = 400): Response {
   return json({ error: message }, status);
 }
 
+function withCorsAndTraceHeaders(response: Response, ctx: RequestContext): Response {
+  const headers = new Headers(response.headers);
+  headers.set("Access-Control-Allow-Origin", "*");
+  headers.set("x-request-id", ctx.request_id);
+  headers.set("x-trace-id", ctx.trace_id);
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
 /**
  * Get Durable Object stub for a session.
  * Returns the stub or null if session ID is missing.
@@ -115,6 +132,46 @@ const SANDBOX_AUTH_ROUTES: RegExp[] = [
   /^\/sessions\/[^/]+\/pr$/, // PR creation from sandbox
 ];
 
+type CachedScmProvider =
+  | {
+      envValue: string | undefined;
+      provider: SourceControlProviderName;
+      error?: never;
+    }
+  | {
+      envValue: string | undefined;
+      provider?: never;
+      error: SourceControlProviderError;
+    };
+
+let cachedScmProvider: CachedScmProvider | null = null;
+
+function resolveDeploymentScmProvider(env: Env): SourceControlProviderName {
+  const envValue = env.SCM_PROVIDER;
+  if (!cachedScmProvider || cachedScmProvider.envValue !== envValue) {
+    try {
+      cachedScmProvider = {
+        envValue,
+        provider: resolveScmProviderFromEnv(envValue),
+      };
+    } catch (errorValue) {
+      cachedScmProvider = {
+        envValue,
+        error:
+          errorValue instanceof SourceControlProviderError
+            ? errorValue
+            : new SourceControlProviderError("Invalid SCM provider configuration", "permanent"),
+      };
+    }
+  }
+
+  if (cachedScmProvider.error) {
+    throw cachedScmProvider.error;
+  }
+
+  return cachedScmProvider.provider;
+}
+
 /**
  * Check if a path matches any public route pattern.
  */
@@ -129,6 +186,47 @@ function isSandboxAuthRoute(path: string): boolean {
   return SANDBOX_AUTH_ROUTES.some((pattern) => pattern.test(path));
 }
 
+function enforceImplementedScmProvider(
+  path: string,
+  env: Env,
+  ctx: RequestContext
+): Response | null {
+  try {
+    const provider = resolveDeploymentScmProvider(env);
+    if (provider !== "github" && !isPublicRoute(path)) {
+      logger.warn("SCM provider not implemented", {
+        event: "scm.provider_not_implemented",
+        scm_provider: provider,
+        http_path: path,
+        request_id: ctx.request_id,
+        trace_id: ctx.trace_id,
+      });
+      const response = error(
+        `SCM provider '${provider}' is not implemented in this deployment.`,
+        501
+      );
+      return withCorsAndTraceHeaders(response, ctx);
+    }
+
+    return null;
+  } catch (errorValue) {
+    const errorMessage =
+      errorValue instanceof SourceControlProviderError
+        ? errorValue.message
+        : "Invalid SCM provider configuration";
+
+    logger.error("Invalid SCM provider configuration", {
+      event: "scm.provider_invalid",
+      error: errorValue instanceof Error ? errorValue : String(errorValue),
+      request_id: ctx.request_id,
+      trace_id: ctx.trace_id,
+    });
+
+    const response = error(errorMessage, 500);
+    return withCorsAndTraceHeaders(response, ctx);
+  }
+}
+
 /**
  * Validate sandbox authentication by checking with the Durable Object.
  * The DO stores the expected sandbox auth token.
@@ -406,32 +504,21 @@ export async function handleRequest(
             // Sandbox auth passed, continue to route handler
           } else {
             // Both HMAC and sandbox auth failed
-            const corsHeaders = new Headers(sandboxAuthError.headers);
-            corsHeaders.set("Access-Control-Allow-Origin", "*");
-            corsHeaders.set("x-request-id", ctx.request_id);
-            corsHeaders.set("x-trace-id", ctx.trace_id);
-            return new Response(sandboxAuthError.body, {
-              status: sandboxAuthError.status,
-              statusText: sandboxAuthError.statusText,
-              headers: corsHeaders,
-            });
+            return withCorsAndTraceHeaders(sandboxAuthError, ctx);
           }
         }
       } else {
         // Not a sandbox auth route, return HMAC auth error
-        const corsHeaders = new Headers(hmacAuthError.headers);
-        corsHeaders.set("Access-Control-Allow-Origin", "*");
-        corsHeaders.set("x-request-id", ctx.request_id);
-        corsHeaders.set("x-trace-id", ctx.trace_id);
-        return new Response(hmacAuthError.body, {
-          status: hmacAuthError.status,
-          statusText: hmacAuthError.statusText,
-          headers: corsHeaders,
-        });
+        return withCorsAndTraceHeaders(hmacAuthError, ctx);
       }
     }
   }
 
+  const providerCheck = enforceImplementedScmProvider(path, env, ctx);
+  if (providerCheck) {
+    return providerCheck;
+  }
+
   // Find matching route
   for (const route of routes) {
     if (route.method !== method) continue;
@@ -460,12 +547,6 @@ export async function handleRequest(
         return error("Internal server error", 500);
       }
 
-      // Create new response with CORS + correlation headers
-      const corsHeaders = new Headers(response.headers);
-      corsHeaders.set("Access-Control-Allow-Origin", "*");
-      corsHeaders.set("x-request-id", ctx.request_id);
-      corsHeaders.set("x-trace-id", ctx.trace_id);
-
       const durationMs = Date.now() - startTime;
       logger.info("http.request", {
         event: "http.request",
@@ -479,11 +560,7 @@ export async function handleRequest(
         ...ctx.metrics.summarize(),
       });
 
-      return new Response(response.body, {
-        status: response.status,
-        statusText: response.statusText,
-        headers: corsHeaders,
-      });
+      return withCorsAndTraceHeaders(response, ctx);
     }
   }
 

packages/control-plane/src/session/durable-object.ts

@@ -27,6 +27,7 @@ import {
 } from "../sandbox/lifecycle/manager";
 import {
   createSourceControlProvider as createSourceControlProviderImpl,
+  resolveScmProviderFromEnv,
   SourceControlProviderError,
   type SourceControlProvider,
   type SourceControlAuthContext,
@@ -188,9 +189,10 @@ export class SessionDO extends DurableObject<Env> {
    */
   private createSourceControlProvider(): SourceControlProvider {
     const appConfig = getGitHubAppConfig(this.env);
+    const provider = resolveScmProviderFromEnv(this.env.SCM_PROVIDER);
 
     return createSourceControlProviderImpl({
-      provider: "github",
+      provider,
       github: {
         appConfig: appConfig ?? undefined,
       },

packages/control-plane/src/source-control/config.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import { SourceControlProviderError } from "./errors";
+import { DEFAULT_SCM_PROVIDER, resolveScmProviderFromEnv } from "./config";
+
+describe("resolveScmProviderFromEnv", () => {
+  it("defaults to github when SCM_PROVIDER is unset", () => {
+    expect(resolveScmProviderFromEnv(undefined)).toBe(DEFAULT_SCM_PROVIDER);
+  });
+
+  it("normalizes case and whitespace", () => {
+    expect(resolveScmProviderFromEnv("  GITHUB ")).toBe("github");
+    expect(resolveScmProviderFromEnv(" bitbucket ")).toBe("bitbucket");
+  });
+
+  it("throws for unknown provider values", () => {
+    expect(() => resolveScmProviderFromEnv("gitlab")).toThrow(SourceControlProviderError);
+    expect(() => resolveScmProviderFromEnv("gitlab")).toThrow(
+      "Invalid SCM_PROVIDER value 'gitlab'"
+    );
+  });
+});

packages/control-plane/src/source-control/config.ts

@@ -0,0 +1,20 @@
+import { SourceControlProviderError } from "./errors";
+import type { SourceControlProviderName } from "./types";
+
+export const DEFAULT_SCM_PROVIDER: SourceControlProviderName = "github";
+
+export function resolveScmProviderFromEnv(value: string | undefined): SourceControlProviderName {
+  const normalized = value?.trim().toLowerCase() ?? "";
+  if (!normalized) {
+    return DEFAULT_SCM_PROVIDER;
+  }
+
+  if (normalized === "github" || normalized === "bitbucket") {
+    return normalized;
+  }
+
+  throw new SourceControlProviderError(
+    `Invalid SCM_PROVIDER value '${normalized}'. Supported values: github, bitbucket.`,
+    "permanent"
+  );
+}

packages/control-plane/src/source-control/index.ts

@@ -23,6 +23,7 @@ export type {
 // Errors
 export type { SourceControlErrorType } from "./errors";
 export { SourceControlProviderError } from "./errors";
+export { DEFAULT_SCM_PROVIDER, resolveScmProviderFromEnv } from "./config";
 
 // Providers
 export {