@rehearsal-db/core 0.1.0-beta.11 → 0.1.0-beta.12

package/CHANGELOG.md

@@ -5,6 +5,41 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ## Unreleased
 
+## [0.1.0-beta.12] - 2026-10-04
+
+### Added
+
+- Supabase projects can declaratively configure local Google or GitHub OAuth in
+  `rehearsal.config.mjs`. Rehearsal derives the credential allowlist, injects only the
+  ignored owner-only environment values, and generates the exact loopback callback in
+  the disposable runtime without tracking secrets. Local signup requires an explicit
+  acknowledgment and is enabled only in that generated runtime copy.
+- Branded, responsive documentation is now hosted on GitHub Pages with searchable
+  navigation, light and dark themes, and automatic deployment from `main`.
+- The documentation home page and packaged README show the live monthly npm download
+  count and link directly to the npm package.
+- Packed-package onboarding acceptance now proves both fresh root-config creation and a
+  real beta.11 upgrade that preserves the user's existing configuration byte for byte.
+
+### Changed
+
+- The packaged README now links prominently to the hosted documentation, npm package,
+  and issue tracker. Package homepage metadata also points to the hosted documentation.
+- GitHub Pages publishing uses the current Node.js 24 action generations without legacy
+  runtime warnings.
+- `rehearsal init` now calls out important optional settings that are available but not
+  enabled before showing the current installed-release template.
+
+### Fixed
+
+- Existing Google or GitHub provider sections can transition to declarative ownership
+  without editing the tracked Supabase template. Rehearsal replaces only a compatible
+  section in the disposable runtime copy, while `doctor` refuses ambiguous or
+  safety-weakening provider settings before reset.
+- Multi-target plain-text plans now print each declarative OAuth callback, and `init`
+  advertises the declarative replacement even when a project still uses legacy provider
+  fields.
+
 ## [0.1.0-beta.11] - 2026-10-03
 
 ### Added
@@ -314,7 +349,8 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
   publication uses short-lived trusted OIDC, and every release tag must already exist on
   protected `main`.
 
-[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.11...HEAD
+[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.12...HEAD
+[0.1.0-beta.12]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.11...v0.1.0-beta.12
 [0.1.0-beta.11]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.10...v0.1.0-beta.11
 [0.1.0-beta.10]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.9...v0.1.0-beta.10
 [0.1.0-beta.9]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.8...v0.1.0-beta.9

package/README.md

@@ -1,5 +1,9 @@
 # Rehearsal
 
+[![Monthly npm downloads](https://img.shields.io/npm/dm/%40rehearsal-db%2Fcore?style=flat-square&logo=npm&logoColor=white&label=npm%20downloads&labelColor=1c2a34&color=287b5c)](https://www.npmjs.com/package/@rehearsal-db/core)
+
+[Read the documentation](https://ddupasquier.github.io/rehearsal-db/) · [View on npm](https://www.npmjs.com/package/@rehearsal-db/core) · [Report a problem](https://github.com/Ddupasquier/rehearsal-db/issues)
+
 Rehearsal tests PostgreSQL and Supabase migrations on your computer before you run them
 anywhere important. It restores safe test data into a disposable local database, applies
 only the migrations you approve, and runs your project's own test command.
@@ -55,6 +59,11 @@ docker pull postgres:17-alpine
 
 Rehearsal itself never downloads a database image during a rehearsal.
 
+For local Google or GitHub sign-in, the generated config includes a commented
+`supabase.authentication` example. It names an ignored owner-only credential file;
+Rehearsal generates the provider block and local callback inside the disposable runtime.
+See [Supabase authentication](docs/configuration.md#supabase-authentication).
+
 ## Three terms you will see
 
 - **Baseline:** a locked, safe starting copy of your schema and test data.

package/docs/commands.md

@@ -34,8 +34,9 @@ Storage files. `baseline create` and `baseline prepare` are local-only.
 
 `setup --write` is idempotent: supported existing config files and completed runtime
 files remain unchanged, while missing safe ignore entries may be appended. On upgrades,
-`init` prints the installed release's template for comparison; `init --write` never
-replaces an existing config.
+`init` first lists important optional settings that are available but not enabled, then
+prints the installed release's template for comparison. `init --write` never replaces an
+existing config.
 
 ## Optional source preparation
 

package/docs/configuration.md

@@ -42,9 +42,21 @@ export default defineRehearsalConfig({
     rehearsalConfig: "infrastructure/rehearsal/supabase/config.toml",
     runtimeWorkdir: ".rehearsal/runtime",
 
-    // Optional; configure both keys together.
-    // serviceEnvironmentFile: ".env.rehearsal-service.local",
-    // serviceEnvironmentVariables: ["LOCAL_IDP_CLIENT_ID", "LOCAL_IDP_SECRET"],
+    // Optional local OAuth connection. Secrets stay in the ignored owner-only file.
+    // Register http://127.0.0.1:58321/auth/v1/callback with the provider.
+    // authentication: {
+    //   enableLocalSignup: true,
+    //   environmentFile: ".env.rehearsal-service.local",
+    //   providers: [
+    //     {
+    //       name: "google",
+    //       clientIdEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_ID",
+    //       clientSecretEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_SECRET",
+    //       skipNonceCheck: false,
+    //       emailOptional: false,
+    //     },
+    //   ],
+    // },
   },
   baseline: {
     artifactDirectory: ".rehearsal",
@@ -124,7 +136,8 @@ safe, run setup again, and compare the two files before deleting either one.
 After upgrading, run `npx rehearsal init` to print the current release's generated
 template beside the path of your existing config. This comparison is read-only; adding a
 new optional key remains your decision. `npx rehearsal init --write` still refuses to
-replace an existing config.
+replace an existing config. Rehearsal lists important optional settings that are
+available but not enabled before printing the template, so they are easier to find.
 
 ### Workspaces and custom paths
 
@@ -247,19 +260,72 @@ negative controls, such as unauthorized, malformed, withheld, or missing records
 response that merely avoids a server error does not prove that eligible data was
 published or can be found.
 
-## Supabase service environment
+## Supabase authentication
 
-Some local identity providers need a client ID and secret. Configure both fields or
-neither:
+Rehearsal can configure a Google or GitHub OAuth connection in its disposable local
+Supabase runtime. Declare the provider and the names of its credential variables:
 
 ```ts
-serviceEnvironmentFile: ".env.rehearsal-service.local",
-serviceEnvironmentVariables: ["LOCAL_IDP_CLIENT_ID", "LOCAL_IDP_SECRET"],
+authentication: {
+  enableLocalSignup: true,
+  environmentFile: ".env.rehearsal-service.local",
+  providers: [
+    {
+      name: "google",
+      clientIdEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_ID",
+      clientSecretEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_SECRET",
+      skipNonceCheck: false,
+      emailOptional: false,
+    },
+  ],
+},
+```
+
+Create the ignored file, add the values, then restrict it to your account:
+
+```dotenv
+REHEARSAL_GOOGLE_CLIENT_ID=your-local-oauth-client-id
+REHEARSAL_GOOGLE_CLIENT_SECRET=your-local-oauth-client-secret
+```
+
+```bash
+chmod 600 .env.rehearsal-service.local
 ```
 
-The file must be ignored, owner-readable only, and contain only the exact allowlisted
-names. These credentials may authorize an identity handshake, but the callback must
-terminate at local Auth. They do not grant hosted database access.
+Register `http://127.0.0.1:<apiPort>/auth/v1/callback` with the provider, using the
+`runtime.apiPort` value from this config. `rehearsal explain` also prints the exact URL.
+Rehearsal writes that callback and `env(...)` references into the disposable runtime; it
+never copies credential values into tracked configuration. Use `name: "github"` and
+distinct GitHub variable names for GitHub. Duplicate providers, reused variable names,
+unsupported providers, extra keys, and a template that already owns the same provider
+are refused. This follows Supabase's documented
+[`env()` configuration pattern](https://supabase.com/docs/guides/local-development/managing-config).
+
+`enableLocalSignup: true` explicitly acknowledges that disposable local Auth may create
+the temporary user returned by OAuth. Rehearsal changes the generated runtime copy only;
+the tracked Supabase template and every hosted project remain unchanged.
+
+The older `serviceEnvironmentFile`, `serviceEnvironmentVariables`, and
+`safety.authenticationProviders` fields remain compatible for projects that manually
+own their Supabase provider TOML. Do not combine those fields with the declarative
+`authentication` block.
+
+To migrate a manual Google or GitHub setup, replace those three legacy config fields
+with the `authentication` block together. The tracked Supabase template may keep its
+existing provider section: Rehearsal replaces a compatible legacy section only in the
+generated disposable runtime copy. The section may contain `enabled`, `client_id`,
+`secret`, `redirect_uri`, `skip_nonce_check`, and `email_optional`. The latter two must
+match the explicit `skipNonceCheck` and `emailOptional` declarations, which default to
+`false`. Keep them false unless the provider integration has a reviewed need; Supabase
+warns in its [CLI configuration reference](https://supabase.com/docs/guides/local-development/cli/config#auth.external.provider.skip_nonce_check)
+that skipping nonce validation reduces replay protection. Unknown settings,
+duplicate sections, nested provider tables, or mismatched options fail
+`rehearsal doctor` before reset. Rehearsal never edits the tracked template during this
+transition.
+
+Provider connection and copied-account association are separate. This block lets the
+ordinary application sign-in reach local Auth. An optional `identityPolicy` decides
+whether that verified local identity may claim a reviewed copied account.
 
 ## Safety fields
 

package/docs/getting-started.md

@@ -55,6 +55,13 @@ Supabase or PostgreSQL, and approve the same safe setup preview.
 The proof command should check behavior changed by the migration. A test that only checks
 whether the home page loads is usually too weak.
 
+If the sandbox needs Google or GitHub sign-in, uncomment
+`supabase.authentication` in `rehearsal.config.mjs`. Add the named credentials to
+`.env.rehearsal-service.local`, run `chmod 600 .env.rehearsal-service.local`, and
+register the local callback printed in the config. See
+[Supabase authentication](configuration.md#supabase-authentication). Rehearsal keeps the
+values out of tracked files and generates the disposable provider configuration for you.
+
 ## 3. Prepare safe baseline inputs
 
 A **baseline** is the locked starting point restored before each rehearsal. Start with a
@@ -168,7 +175,9 @@ complete reference and [Troubleshooting](troubleshooting.md) when a check fails.
 
 Running setup again is safe: existing configuration and runtime files are reported as
 unchanged. Rehearsal only adds missing ignore entries. It never refreshes an existing
-config during an upgrade.
+config during an upgrade. After upgrading, run `npx rehearsal init` to see important
+optional settings you have not enabled and compare your file with the installed
+release's current template.
 
 ## Files Rehearsal creates
 

package/docs/runtime-policies.md

@@ -157,8 +157,10 @@ graph without an application callback patch:
 
 Authentication has three separate parts:
 
-1. The local Supabase configuration enables Google, GitHub, or email sign-in and reads
-   any provider credentials from the environment.
+1. `config.supabase.authentication` can enable a Google or GitHub connection in local
+   Supabase and reads its credentials from the ignored owner-only environment file.
+   Existing projects may still own that local provider TOML manually. Email sign-in does
+   not use an OAuth credential declaration.
 2. The application completes the ordinary sign-in and receives a normal Supabase
    session. Rehearsal does not intercept the callback.
 3. The identity policy matches that verified local identity and transfers only the

package/docs/troubleshooting.md

@@ -146,9 +146,20 @@ changes.
 
 ## Local authentication fails
 
-Confirm the provider is enabled in the dedicated local Supabase config, the allowlisted
-service environment file exists with owner-only permissions, and the provider callback
-is the local Auth callback. Do not paste provider secrets into config or terminal output.
+For Google or GitHub, confirm `supabase.authentication` is declared in
+`rehearsal.config.mjs`, its ignored environment file exists with `chmod 600`, and the
+provider has the printed local Auth callback registered. Rehearsal generates the
+disposable Supabase provider block.
+
+When migrating from the legacy service environment fields, replace those fields together
+with `supabase.authentication` and rerun `rehearsal doctor`. A compatible Google or
+GitHub provider section may remain in the tracked template: Rehearsal supersedes it only
+inside the generated runtime copy. Doctor refuses unknown provider settings, duplicate
+or nested provider sections, and nonce or optional-email settings that do not match the
+new declaration. Keep both options false unless there is a reviewed provider-specific
+need; skipping nonce validation reduces replay protection. Otherwise keep using the
+documented legacy configuration.
+Never paste provider secrets into tracked config or terminal output.
 
 If `identity plan` refuses the matcher, read the message literally:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rehearsal-db/core",
-  "version": "0.1.0-beta.11",
+  "version": "0.1.0-beta.12",
   "private": false,
   "description": "Safely rehearse PostgreSQL and Supabase migrations against sanitized, production-shaped data.",
   "repository": {
@@ -10,7 +10,7 @@
   "bugs": {
     "url": "https://github.com/Ddupasquier/rehearsal-db/issues"
   },
-  "homepage": "https://github.com/Ddupasquier/rehearsal-db#readme",
+  "homepage": "https://ddupasquier.github.io/rehearsal-db/",
   "publishConfig": {
     "access": "public",
     "tag": "beta",
@@ -62,6 +62,7 @@
     "test:fixture": "node scripts/verification/fixtures/supabase.mjs",
     "test:fixture:postgresql": "node scripts/verification/fixtures/postgresql.mjs",
     "test:fixture:dependent": "node scripts/verification/fixtures/dependent.mjs",
+    "test:fixture:onboarding": "node scripts/verification/fixtures/onboarding.mjs",
     "test:fixture:standalone": "node scripts/verification/fixtures/standalone.mjs",
     "test:fixture:privacy": "node scripts/verification/fixtures/privacy.mjs",
     "check": "npm run check:syntax && npm run test && npm run docs:build && npm run format:check && npm run package:audit",

package/src/cli/init_command.mjs

@@ -49,11 +49,27 @@ export const runRehearsalInit = async ({ projectRoot, flags }) => {
           applicationUrl: loaded.config.runtime.applicationUrl,
           databasePort: loaded.config.runtime.ports.database,
         });
+    const usesLegacyAuthentication = Boolean(
+      loaded.config.supabase?.serviceEnvironmentFile ||
+      loaded.config.safety.authenticationProviders.length,
+    );
+    const availableOptions =
+      loaded.config.supabase && !loaded.config.supabase.authentication
+        ? [
+            {
+              path: "supabase.authentication",
+              summary: usesLegacyAuthentication
+                ? "A declarative Google/GitHub replacement is available; replace the legacy provider fields together after review."
+                : "Configure local Google or GitHub sign-in with credentials kept outside tracked files.",
+            },
+          ]
+        : [];
     return {
       mode: "current-template",
       destination: relative(projectRoot, existingPath),
       detected,
       source,
+      availableOptions,
       nextAction:
         "Your existing configuration was not changed. Compare it with this installed-release template to discover new optional keys.",
     };
@@ -70,6 +86,7 @@ export const runRehearsalInit = async ({ projectRoot, flags }) => {
     destination: relative(projectRoot, destination),
     detected,
     source,
+    availableOptions: [],
     nextAction: flags.write
       ? "Review the generated safety settings and run rehearsal doctor."
       : "Review this preview, then rerun rehearsal init --write to create it.",

package/src/cli/renderers.mjs

@@ -14,6 +14,16 @@ export const renderPlan = (plan, verbosity) => {
       ...plan.targets.flatMap((target) => [
         `${target.name} — ${target.plan.config.project}`,
         `  ✓ ${target.plan.environment.kind}`,
+        ...(target.plan.environment.authenticationProviders.length
+          ? [
+              `  ✓ External identity providers ${target.plan.environment.authenticationProviders.join(", ")}`,
+              ...(target.plan.environment.authenticationCallback
+                ? [
+                    `  → Register callback ${target.plan.environment.authenticationCallback}`,
+                  ]
+                : []),
+            ]
+          : []),
         `  ✓ baseline ${target.plan.baseline.generationId}`,
         `  ✓ ${formatCount(target.plan.baseline.tableCount, "table")}; ${formatCount(target.plan.baseline.rowCount, "row")}`,
         ...(target.plan.migrations.candidates.length
@@ -69,6 +79,11 @@ export const renderPlan = (plan, verbosity) => {
     ...(plan.environment.authenticationProviders.length
       ? [
           `  ✓ External identity providers ${plan.environment.authenticationProviders.join(", ")}`,
+          ...(plan.environment.authenticationCallback
+            ? [
+                `  → Register callback ${plan.environment.authenticationCallback}`,
+              ]
+            : []),
         ]
       : []),
     "",
@@ -194,6 +209,15 @@ export const renderInit = (result) =>
     `Detected package manager: ${result.detected.packageManager}`,
     `Detected Supabase config: ${result.detected.hasSupabaseConfig ? "yes" : "no"}`,
     `Detected migrations: ${result.detected.hasMigrations ? "yes" : "no"}`,
+    ...(result.availableOptions?.length
+      ? [
+          "",
+          "AVAILABLE BUT NOT ENABLED",
+          ...result.availableOptions.map(
+            (option) => `  → ${option.path}: ${option.summary}`,
+          ),
+        ]
+      : []),
     ...(result.source ? ["", result.source] : []),
     result.nextAction,
   ].join("\n");

package/src/identity/provider_configuration.mjs

@@ -0,0 +1,177 @@
+/** Render reviewed local OAuth declarations into the disposable Supabase runtime. */
+
+const escapePattern = (value) =>
+  value.replaceAll(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+
+const LEGACY_PROVIDER_KEYS = new Set([
+  "client_id",
+  "email_optional",
+  "enabled",
+  "redirect_uri",
+  "secret",
+  "skip_nonce_check",
+]);
+const SAFE_BOOLEAN_PROVIDER_KEYS = new Set([
+  "email_optional",
+  "skip_nonce_check",
+]);
+
+const readTomlSections = (source) => {
+  const lines = source.split("\n");
+  const sections = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = /^\s*\[([^\]]+)\]\s*(?:#.*)?$/u.exec(lines[index]);
+    if (!match) continue;
+    if (sections.length) sections.at(-1).end = index;
+    sections.push({ name: match[1], start: index, end: lines.length });
+  }
+  return { lines, sections };
+};
+
+const validateLegacyProviderSection = ({ lines, section, provider }) => {
+  const seen = new Set();
+  for (const line of lines.slice(section.start + 1, section.end)) {
+    if (!line.trim() || /^\s*#/u.test(line)) continue;
+    const assignment = /^\s*([A-Za-z0-9_]+)\s*=/u.exec(line);
+    if (!assignment || !LEGACY_PROVIDER_KEYS.has(assignment[1])) {
+      throw new Error(
+        `The local Supabase template auth.external.${provider.name} section contains an unsupported setting. Rehearsal left the tracked template unchanged.`,
+      );
+    }
+    const key = assignment[1];
+    if (seen.has(key)) {
+      throw new Error(
+        `The local Supabase template auth.external.${provider.name} section contains duplicate ${key} settings.`,
+      );
+    }
+    seen.add(key);
+    if (
+      SAFE_BOOLEAN_PROVIDER_KEYS.has(key) &&
+      !new RegExp(
+        `^\\s*${escapePattern(key)}\\s*=\\s*${
+          key === "skip_nonce_check"
+            ? (provider.skipNonceCheck ?? false)
+            : (provider.emailOptional ?? false)
+        }\\s*(?:#.*)?$`,
+        "u",
+      ).test(line)
+    ) {
+      throw new Error(
+        `The local Supabase template auth.external.${provider.name}.${key} setting must match its explicit declarative authentication option before Rehearsal can replace the legacy provider in its disposable runtime copy.`,
+      );
+    }
+  }
+};
+
+export const inspectSupabaseAuthenticationProviderTransition = ({
+  source,
+  authentication,
+}) => {
+  if (!authentication) return Object.freeze({ replacedProviders: [] });
+  const { lines, sections } = readTomlSections(source);
+  const replacementSections = [];
+  for (const provider of authentication.providers) {
+    const sectionName = `auth.external.${provider.name}`;
+    const nested = sections.filter((section) =>
+      section.name.startsWith(`${sectionName}.`),
+    );
+    if (nested.length) {
+      throw new Error(
+        `The local Supabase template contains unsupported nested ${sectionName} configuration. Rehearsal left the tracked template unchanged.`,
+      );
+    }
+    const matching = sections.filter((section) => section.name === sectionName);
+    if (matching.length > 1) {
+      throw new Error(
+        `The local Supabase template declares ${sectionName} more than once.`,
+      );
+    }
+    if (matching.length === 1) {
+      validateLegacyProviderSection({
+        lines,
+        section: matching[0],
+        provider,
+      });
+      replacementSections.push({ ...matching[0], provider: provider.name });
+    }
+  }
+  return Object.freeze({
+    replacedProviders: Object.freeze(
+      replacementSections.map(({ provider }) => provider),
+    ),
+    replacementSections: Object.freeze(replacementSections),
+  });
+};
+
+export const renderSupabaseAuthenticationProviders = ({
+  authentication,
+  apiPort,
+}) => {
+  if (!authentication) return "";
+  return authentication.providers
+    .map(
+      (
+        provider,
+      ) => `# Generated by Rehearsal from config.supabase.authentication.
+[auth.external.${provider.name}]
+enabled = true
+client_id = "env(${provider.clientIdEnvironmentVariable})"
+secret = "env(${provider.clientSecretEnvironmentVariable})"
+redirect_uri = "http://127.0.0.1:${apiPort}/auth/v1/callback"
+${provider.skipNonceCheck ? "skip_nonce_check = true\n" : ""}${provider.emailOptional ? "email_optional = true\n" : ""}
+`,
+    )
+    .join("\n");
+};
+
+const enableLocalSignup = (source) => {
+  const lines = source.split("\n");
+  let inAuth = false;
+  let authSections = 0;
+  let signupSettings = 0;
+  const updated = lines.map((line) => {
+    const section = /^\s*\[([^\]]+)\]\s*(?:#.*)?$/u.exec(line);
+    if (section) {
+      inAuth = section[1] === "auth";
+      if (inAuth) authSections += 1;
+      return line;
+    }
+    if (!inAuth || !/^\s*enable_signup\s*=/u.test(line)) return line;
+    signupSettings += 1;
+    const comment = line.match(/\s+#.*$/u)?.[0] ?? "";
+    return `enable_signup = true${comment}`;
+  });
+  if (authSections !== 1 || signupSettings !== 1) {
+    throw new Error(
+      "The local Supabase template must declare exactly one [auth] section with one enable_signup setting before Rehearsal can configure OAuth.",
+    );
+  }
+  return updated.join("\n");
+};
+
+export const applySupabaseAuthenticationProviders = ({
+  source,
+  authentication,
+  apiPort,
+}) => {
+  if (!authentication) return source;
+  const transition = inspectSupabaseAuthenticationProviderTransition({
+    source,
+    authentication,
+  });
+  const { lines } = readTomlSections(source);
+  const replacedIndexes = new Set(
+    transition.replacementSections.flatMap((section) =>
+      Array.from(
+        { length: section.end - section.start },
+        (_, offset) => section.start + offset,
+      ),
+    ),
+  );
+  const transitionedSource = lines
+    .filter((_, index) => !replacedIndexes.has(index))
+    .join("\n");
+  const runtimeSource = enableLocalSignup(transitionedSource);
+  const separator = runtimeSource.endsWith("\n") ? "\n" : "\n\n";
+  return `${runtimeSource}${separator}${renderSupabaseAuthenticationProviders({ authentication, apiPort })}`;
+};

package/src/project/configuration.d.mts

@@ -8,6 +8,17 @@ export interface RehearsalConfig {
     migrationDirectory: string;
     rehearsalConfig: string;
     runtimeWorkdir: string;
+    authentication?: {
+      enableLocalSignup: true;
+      environmentFile: string;
+      providers: Array<{
+        name: "google" | "github";
+        clientIdEnvironmentVariable: string;
+        clientSecretEnvironmentVariable: string;
+        skipNonceCheck?: boolean;
+        emailOptional?: boolean;
+      }>;
+    };
     serviceEnvironmentFile?: string;
     serviceEnvironmentVariables?: string[];
   };

package/src/project/configuration.mjs

@@ -61,6 +61,7 @@ const POSTGRES_IMAGE_PATTERN = /^postgres:\d+(?:\.\d+)?-alpine$/u;
 const SAFE_COMMAND_PATTERN = /^[^\n\r\0]+$/u;
 const ENVIRONMENT_KEY_PATTERN = /^[A-Z][A-Z0-9_]*$/u;
 const ENVIRONMENT_REFERENCE_PATTERN = /^[a-z0-9][a-z0-9-]*:[A-Z][A-Z0-9_]*$/u;
+const SUPPORTED_SUPABASE_OAUTH_PROVIDERS = new Set(["github", "google"]);
 
 const isPlainObject = (value) =>
   value !== null &&
@@ -251,6 +252,7 @@ const normalizeConfig = (input) => {
         "migrationDirectory",
         "rehearsalConfig",
         "runtimeWorkdir",
+        "authentication",
         "serviceEnvironmentFile",
         "serviceEnvironmentVariables",
       ],
@@ -437,8 +439,123 @@ const normalizeConfig = (input) => {
   if (!Array.isArray(commands)) {
     throw new Error("config.verification.commands must be an array.");
   }
-  const serviceEnvironmentVariables =
-    supabase?.serviceEnvironmentVariables ?? [];
+  const authentication =
+    supabase?.authentication === undefined
+      ? null
+      : assertPlainObject(
+          supabase.authentication,
+          "config.supabase.authentication",
+        );
+  let normalizedAuthentication = null;
+  if (authentication) {
+    assertKnownKeys(
+      authentication,
+      ["enableLocalSignup", "environmentFile", "providers"],
+      "config.supabase.authentication",
+    );
+    if (authentication.enableLocalSignup !== true) {
+      throw new Error(
+        "config.supabase.authentication.enableLocalSignup must be true to create the disposable local identity used by an OAuth sign-in.",
+      );
+    }
+    if (
+      supabase.serviceEnvironmentFile !== undefined ||
+      supabase.serviceEnvironmentVariables !== undefined
+    ) {
+      throw new Error(
+        "config.supabase.authentication cannot be combined with the legacy serviceEnvironmentFile or serviceEnvironmentVariables fields.",
+      );
+    }
+    if (safety.authenticationProviders !== undefined) {
+      throw new Error(
+        "config.safety.authenticationProviders is derived from config.supabase.authentication and must be omitted.",
+      );
+    }
+    if (
+      !Array.isArray(authentication.providers) ||
+      authentication.providers.length === 0
+    ) {
+      throw new Error(
+        "config.supabase.authentication.providers must be a non-empty array.",
+      );
+    }
+    const providers = authentication.providers.map((entry, index) => {
+      const path = `config.supabase.authentication.providers[${index}]`;
+      const value = assertPlainObject(entry, path);
+      assertKnownKeys(
+        value,
+        [
+          "name",
+          "clientIdEnvironmentVariable",
+          "clientSecretEnvironmentVariable",
+          "skipNonceCheck",
+          "emailOptional",
+        ],
+        path,
+      );
+      const name = assertNonEmptyString(value.name, `${path}.name`);
+      if (!SUPPORTED_SUPABASE_OAUTH_PROVIDERS.has(name)) {
+        throw new Error(
+          `${path}.name must be one of: ${[...SUPPORTED_SUPABASE_OAUTH_PROVIDERS].join(", ")}.`,
+        );
+      }
+      const environmentVariable = (key) => {
+        const variable = assertNonEmptyString(value[key], `${path}.${key}`);
+        if (!ENVIRONMENT_KEY_PATTERN.test(variable)) {
+          throw new Error(
+            `${path}.${key} must be a safe environment variable name.`,
+          );
+        }
+        return variable;
+      };
+      const optionalBoolean = (key) => {
+        if (value[key] === undefined) return false;
+        if (typeof value[key] !== "boolean") {
+          throw new Error(`${path}.${key} must be a boolean.`);
+        }
+        return value[key];
+      };
+      return Object.freeze({
+        name,
+        clientIdEnvironmentVariable: environmentVariable(
+          "clientIdEnvironmentVariable",
+        ),
+        clientSecretEnvironmentVariable: environmentVariable(
+          "clientSecretEnvironmentVariable",
+        ),
+        skipNonceCheck: optionalBoolean("skipNonceCheck"),
+        emailOptional: optionalBoolean("emailOptional"),
+      });
+    });
+    if (new Set(providers.map(({ name }) => name)).size !== providers.length) {
+      throw new Error(
+        "config.supabase.authentication.providers must not contain duplicate providers.",
+      );
+    }
+    const credentialVariables = providers.flatMap((provider) => [
+      provider.clientIdEnvironmentVariable,
+      provider.clientSecretEnvironmentVariable,
+    ]);
+    if (new Set(credentialVariables).size !== credentialVariables.length) {
+      throw new Error(
+        "config.supabase.authentication provider environment variables must be unique.",
+      );
+    }
+    normalizedAuthentication = Object.freeze({
+      enableLocalSignup: true,
+      environmentFile: assertRelativePath(
+        authentication.environmentFile,
+        "config.supabase.authentication.environmentFile",
+      ),
+      providers: Object.freeze(providers),
+    });
+  }
+  const serviceEnvironmentVariables = normalizedAuthentication
+    ? normalizedAuthentication.providers.flatMap((provider) => [
+        provider.clientIdEnvironmentVariable,
+        provider.clientSecretEnvironmentVariable,
+      ])
+    : (supabase?.serviceEnvironmentVariables ?? []);
   if (!Array.isArray(serviceEnvironmentVariables)) {
     throw new Error(
       "config.supabase.serviceEnvironmentVariables must be an array.",
@@ -460,19 +577,23 @@ const normalizeConfig = (input) => {
     );
   }
   if (
-    Boolean(supabase?.serviceEnvironmentFile) !==
-    Boolean(normalizedServiceEnvironmentVariables.length)
+    Boolean(
+      normalizedAuthentication?.environmentFile ??
+      supabase?.serviceEnvironmentFile,
+    ) !== Boolean(normalizedServiceEnvironmentVariables.length)
   ) {
     throw new Error(
       "config.supabase.serviceEnvironmentFile and serviceEnvironmentVariables must be configured together.",
     );
   }
-  const authenticationProviders = safety.authenticationProviders
-    ? assertStringArray(
-        safety.authenticationProviders,
-        "config.safety.authenticationProviders",
-      )
-    : [];
+  const authenticationProviders = normalizedAuthentication
+    ? normalizedAuthentication.providers.map(({ name }) => name)
+    : safety.authenticationProviders
+      ? assertStringArray(
+          safety.authenticationProviders,
+          "config.safety.authenticationProviders",
+        )
+      : [];
   if (runtimeTarget === "postgresql" && authenticationProviders.length > 0) {
     throw new Error(
       "config.safety.authenticationProviders is available only for the Supabase target.",
@@ -500,12 +621,15 @@ const normalizeConfig = (input) => {
             supabase.runtimeWorkdir,
             "config.supabase.runtimeWorkdir",
           ),
-          serviceEnvironmentFile: supabase.serviceEnvironmentFile
-            ? assertRelativePath(
-                supabase.serviceEnvironmentFile,
-                "config.supabase.serviceEnvironmentFile",
-              )
-            : null,
+          authentication: normalizedAuthentication,
+          serviceEnvironmentFile: normalizedAuthentication
+            ? normalizedAuthentication.environmentFile
+            : supabase.serviceEnvironmentFile
+              ? assertRelativePath(
+                  supabase.serviceEnvironmentFile,
+                  "config.supabase.serviceEnvironmentFile",
+                )
+              : null,
           serviceEnvironmentVariables: Object.freeze(
             normalizedServiceEnvironmentVariables,
           ),
@@ -1005,9 +1129,21 @@ export default defineRehearsalConfig({
 		rehearsalConfig: "infrastructure/rehearsal/supabase/config.toml",
 		runtimeWorkdir: ".rehearsal/runtime",
 
-		// Optional local-only identity-provider credentials. Enable both keys together.
-		// serviceEnvironmentFile: ".env.rehearsal-service.local",
-		// serviceEnvironmentVariables: ["LOCAL_IDP_CLIENT_ID", "LOCAL_IDP_SECRET"],
+		// Optional local OAuth connection. Secrets stay in the ignored owner-only file.
+		// Register http://127.0.0.1:${ports.api}/auth/v1/callback with the provider.
+		// authentication: {
+		// 	enableLocalSignup: true,
+		// 	environmentFile: ".env.rehearsal-service.local",
+		// 	providers: [
+		// 		{
+		// 			name: "google",
+		// 			clientIdEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_ID",
+		// 			clientSecretEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_SECRET",
+		// 			skipNonceCheck: false,
+		// 			emailOptional: false,
+		// 		},
+		// 	],
+		// },
 	},
 
 	// Immutable local baseline files. Rehearsal never reads production on your behalf.

package/src/runtime/plan.mjs

@@ -11,6 +11,10 @@ import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { performance } from "node:perf_hooks";
 import { verifyActiveBaseline } from "../baseline/artifact.mjs";
+import {
+  applySupabaseAuthenticationProviders,
+  inspectSupabaseAuthenticationProviderTransition,
+} from "../identity/provider_configuration.mjs";
 import {
   inspectDetectedProject,
   loadRehearsalConfig,
@@ -233,6 +237,9 @@ export const buildRehearsalPlan = async (options = {}) => {
       hostedAccess: config.safety.hostedAccess,
       outboundNetwork: config.safety.outboundNetwork,
       authenticationProviders: config.safety.authenticationProviders,
+      authenticationCallback: config.supabase?.authentication
+        ? `http://127.0.0.1:${config.runtime.ports.api}/auth/v1/callback`
+        : null,
       barriers: [
         "versioned configuration accepts loopback hosts only",
         `runtime uses a dedicated local ${config.runtime.target === "supabase" ? "Supabase workdir" : "PostgreSQL container and volume"} and project id`,
@@ -459,6 +466,32 @@ export const runRehearsalDoctor = async (options = {}) => {
       remediation:
         "Correct the missing project path in the Rehearsal configuration.",
     },
+    ...(config.supabase?.authentication
+      ? [
+          {
+            id: "authentication-runtime-config",
+            label: "Local authentication configuration",
+            run: async () => {
+              const source = await readFile(paths.rehearsalConfig, "utf8");
+              const transition =
+                inspectSupabaseAuthenticationProviderTransition({
+                  source,
+                  authentication: config.supabase.authentication,
+                });
+              applySupabaseAuthenticationProviders({
+                source,
+                authentication: config.supabase.authentication,
+                apiPort: config.runtime.ports.api,
+              });
+              return transition.replacedProviders.length
+                ? `compatible legacy ${transition.replacedProviders.join(", ")} provider configuration will be replaced only in the disposable runtime copy`
+                : "declarative provider configuration can be generated without changing the tracked template";
+            },
+            remediation:
+              "Review the named provider section and make skipNonceCheck or emailOptional match explicitly in config.supabase.authentication; otherwise keep the documented manual provider configuration.",
+          },
+        ]
+      : []),
     {
       id: "sanitization-policy",
       label: "Reviewed sanitization policy",

package/src/targets/supabase.mjs

@@ -44,6 +44,7 @@ import {
 } from "../runtime/migration_history.mjs";
 import { loadRehearsalConfig } from "../project/configuration.mjs";
 import { readRehearsalServiceEnvironment } from "../runtime/service_environment.mjs";
+import { applySupabaseAuthenticationProviders } from "../identity/provider_configuration.mjs";
 import { readBoundRuntimeSanitizationPolicy } from "../baseline/sanitization_policy.mjs";
 import {
   captureLocalPublicSchema,
@@ -315,7 +316,16 @@ const prepareRuntimeWorkdir = async ({ baseline, paths }) => {
     recursive: true,
     mode: 0o700,
   });
-  await cp(configTemplatePath, join(runtimeSupabaseDirectory, "config.toml"));
+  const configTemplate = await readFile(configTemplatePath, "utf8");
+  await writeFile(
+    join(runtimeSupabaseDirectory, "config.toml"),
+    applySupabaseAuthenticationProviders({
+      source: configTemplate,
+      authentication: config.supabase.authentication,
+      apiPort: config.runtime.ports.api,
+    }),
+    { mode: 0o600 },
+  );
   for (const filename of Object.keys(baseline.migrations).sort()) {
     await cp(
       join(paths.migrationsDirectory, filename),