Add config-gated Supabase Auth and Postgres providers with DEV activation checklist - PR_26166_126-128-supabase-provider-implementation

Author: ToolboxAid

docs_build/dev/reports/coverage_changed_js_guardrail.txt

@@ -7,12 +7,6 @@ Source: Playwright/Chromium built-in V8 coverage from the active Playwright run.
 
 Changed runtime JS files considered:
 (0%) src/dev-runtime/auth/provider-contract-stubs.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/dev-runtime/guest-seeds/tool-metadata-inventory.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/game-journey-mock-repository.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/shared/contracts/tools/toolContractsIndex.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
 
 Guardrail warnings:
 (0%) src/dev-runtime/auth/provider-contract-stubs.mjs - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) src/dev-runtime/guest-seeds/tool-metadata-inventory.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/game-journey-mock-repository.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) src/shared/contracts/tools/toolContractsIndex.js - WARNING: changed runtime JS file missing from coverage; advisory only

docs_build/dev/reports/playwright_v8_coverage_report.txt

@@ -12,42 +12,31 @@ Note: entry percentages use function coverage when available, otherwise line cov
 Note: coverage entries are aggregated across every page/tool where coverageReporter.start(page) and coverageReporter.stop(page) ran.
 
 Exercised tool entry points detected:
-(89%) Toolbox Index - exercised 6 runtime JS files
+(44%) Toolbox Index - exercised 1 runtime JS files
 (0%) Tool Template V2 - not exercised by this Playwright run
-(73%) Theme V2 Shared JS - exercised 2 runtime JS files
+(60%) Theme V2 Shared JS - exercised 6 runtime JS files
 
 Changed runtime JS files covered:
 (0%) src/dev-runtime/auth/provider-contract-stubs.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/dev-runtime/guest-seeds/tool-metadata-inventory.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/game-journey-mock-repository.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/shared/contracts/tools/toolContractsIndex.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
 
 Files with executed line/function counts where available:
-(25%) src/engine/api/session-api-client.js - executed lines 68/68; executed functions 3/12
-(33%) src/engine/api/toolbox-votes-api-client.js - executed lines 46/46; executed functions 2/6
-(53%) src/engine/api/server-api-client.js - executed lines 159/159; executed functions 10/19
+(8%) src/engine/api/session-api-client.js - executed lines 68/68; executed functions 1/12
+(10%) assets/theme-v2/js/local-db-page-data.js - executed lines 299/299; executed functions 3/29
+(33%) src/engine/api/admin-setup-api-client.js - executed lines 13/13; executed functions 1/3
+(36%) src/engine/api/server-api-client.js - executed lines 159/159; executed functions 5/14
+(40%) assets/theme-v2/js/admin-setup-actions.js - executed lines 38/38; executed functions 2/5
+(44%) toolbox/tool-registry-api-client.js - executed lines 152/152; executed functions 11/25
+(60%) src/engine/api/local-db-api-client.js - executed lines 19/19; executed functions 3/5
 (64%) assets/theme-v2/js/tool-display-mode.js - executed lines 209/209; executed functions 9/14
-(68%) toolbox/game-workspace/game-workspace.js - executed lines 281/281; executed functions 19/28
-(69%) admin/tool-votes.js - executed lines 406/406; executed functions 37/54
-(75%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 722/722; executed functions 51/68
-(89%) toolbox/tool-registry-api-client.js - executed lines 152/152; executed functions 25/28
-(91%) toolbox/game-design/game-design.js - executed lines 254/254; executed functions 21/23
-(93%) toolbox/tools-page-accordions.js - executed lines 965/965; executed functions 106/114
-(100%) toolbox/game-design/game-design-api-client.js - executed lines 13/13; executed functions 2/2
-(100%) toolbox/game-workspace/game-workspace-api-client.js - executed lines 12/12; executed functions 2/2
+(67%) admin/db-viewer.js - executed lines 49/49; executed functions 4/6
+(76%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 722/722; executed functions 52/68
+(85%) src/engine/api/local-db-viewer-ui.js - executed lines 479/479; executed functions 77/91
+(100%) assets/theme-v2/js/admin-db-status-panel.js - executed lines 30/30; executed functions 3/3
+(100%) assets/theme-v2/js/login-session.js - executed lines 45/45; executed functions 7/7
 
 Uncovered or low-coverage changed JS files:
 (0%) src/dev-runtime/auth/provider-contract-stubs.mjs - WARNING: uncovered changed runtime JS file; advisory only
-(0%) src/dev-runtime/guest-seeds/tool-metadata-inventory.js - WARNING: uncovered changed runtime JS file; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/game-journey-mock-repository.js - WARNING: uncovered changed runtime JS file; advisory only
-(0%) src/shared/contracts/tools/toolContractsIndex.js - WARNING: uncovered changed runtime JS file; advisory only
 
 Changed JS files considered:
 (0%) src/dev-runtime/auth/provider-contract-stubs.mjs - changed JS file not collected as browser runtime coverage
-(0%) src/dev-runtime/guest-seeds/tool-metadata-inventory.js - changed JS file not collected as browser runtime coverage
-(0%) src/dev-runtime/persistence/tool-repositories/game-journey-mock-repository.js - changed JS file not collected as browser runtime coverage
-(0%) src/shared/contracts/tools/toolContractsIndex.js - changed JS file not collected as browser runtime coverage
 (0%) tests/dev-runtime/SupabaseProviderContractStub.test.mjs - changed JS file not collected as browser runtime coverage
-(0%) tests/playwright/tools/RootToolsFutureState.spec.mjs - changed JS file not collected as browser runtime coverage
-(0%) tests/playwright/tools/ToolboxAdminMetadataSsot.spec.mjs - changed JS file not collected as browser runtime coverage
-(0%) tests/playwright/tools/ToolboxRoutePages.spec.mjs - changed JS file not collected as browser runtime coverage

src/dev-runtime/auth/provider-contract-stubs.mjs

@@ -75,6 +75,40 @@ export function supabasePostgresDiagnostic(env = process.env) {
     : "Supabase Postgres provider stub is configured but not active until a dedicated adapter PR.";
 }
 
+function supabaseUrl(env) {
+  return envValue(env, "GAMEFOUNDRY_SUPABASE_URL").replace(/\/+$/, "");
+}
+
+function supabaseAnonKey(env) {
+  return envValue(env, "GAMEFOUNDRY_SUPABASE_ANON_KEY");
+}
+
+function authHeaders(env, accessToken = "") {
+  const anonKey = supabaseAnonKey(env);
+  const headers = {
+    apikey: anonKey,
+    authorization: `Bearer ${accessToken || anonKey}`,
+    "content-type": "application/json",
+  };
+  return headers;
+}
+
+function requireString(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) {
+    throw new Error(`Supabase Auth ${label} is required.`);
+  }
+  return normalized;
+}
+
+async function readResponseJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    return {};
+  }
+}
+
 function futureProviderMissingConfigWarnings(supabaseAuthMissing, supabasePostgresMissing) {
   const warnings = [];
   if (supabaseAuthMissing.length) {
@@ -97,41 +131,103 @@ function configuredProviderIds(supabaseAuthMissing, supabasePostgresMissing) {
   };
 }
 
-export class SupabaseAuthProviderStub {
-  constructor({ env = process.env } = {}) {
+export class SupabaseAuthProviderAdapter {
+  constructor({ env = process.env, fetchImpl = globalThis.fetch } = {}) {
     this.env = env;
+    this.fetchImpl = fetchImpl;
     this.providerId = SUPABASE_AUTH_PROVIDER_ID;
   }
 
   diagnostic() {
     return supabaseAuthDiagnostic(this.env);
   }
 
-  getCurrentUser() {
-    throw new Error(this.diagnostic());
+  assertConfigured() {
+    const missing = missingEnvKeys(this.env, BROWSER_SAFE_SUPABASE_ENV_KEYS);
+    if (missing.length) {
+      throw new Error(supabaseAuthDiagnostic(this.env));
+    }
+    if (typeof this.fetchImpl !== "function") {
+      throw new Error("Supabase Auth provider requires a server fetch implementation.");
+    }
   }
 
-  signIn() {
-    throw new Error(this.diagnostic());
+  async request(path, { accessToken = "", body = null, method = "GET", operation } = {}) {
+    this.assertConfigured();
+    const response = await this.fetchImpl(`${supabaseUrl(this.env)}${path}`, {
+      body: body === null ? undefined : JSON.stringify(body),
+      headers: authHeaders(this.env, accessToken),
+      method,
+    });
+    const payload = await readResponseJson(response);
+    if (!response.ok) {
+      const message = payload?.error_description || payload?.msg || payload?.message || "No Supabase Auth error message returned.";
+      throw new Error(`Supabase Auth ${operation} failed with HTTP ${response.status}: ${message}`);
+    }
+    return payload;
   }
 
-  signOut() {
-    throw new Error(this.diagnostic());
+  async getCurrentUser({ accessToken } = {}) {
+    this.assertConfigured();
+    return this.request("/auth/v1/user", {
+      accessToken: requireString(accessToken, "access token"),
+      operation: "getCurrentUser",
+    });
   }
 
-  createAccount() {
-    throw new Error(this.diagnostic());
+  async signIn({ email, password } = {}) {
+    this.assertConfigured();
+    return this.request("/auth/v1/token?grant_type=password", {
+      body: {
+        email: requireString(email, "email"),
+        password: requireString(password, "password"),
+      },
+      method: "POST",
+      operation: "signIn",
+    });
   }
 
-  requestPasswordReset() {
-    throw new Error(this.diagnostic());
+  async signOut({ accessToken } = {}) {
+    this.assertConfigured();
+    return this.request("/auth/v1/logout", {
+      accessToken: requireString(accessToken, "access token"),
+      method: "POST",
+      operation: "signOut",
+    });
+  }
+
+  async createAccount({ email, password } = {}) {
+    this.assertConfigured();
+    return this.request("/auth/v1/signup", {
+      body: {
+        email: requireString(email, "email"),
+        password: requireString(password, "password"),
+      },
+      method: "POST",
+      operation: "createAccount",
+    });
+  }
+
+  async requestPasswordReset({ email, redirectTo = "" } = {}) {
+    this.assertConfigured();
+    const body = { email: requireString(email, "email") };
+    if (redirectTo) {
+      body.redirect_to = redirectTo;
+    }
+    return this.request("/auth/v1/recover", {
+      body,
+      method: "POST",
+      operation: "requestPasswordReset",
+    });
   }
 
   requireRole() {
-    throw new Error(this.diagnostic());
+    throw new Error("Supabase Auth role checks require the future app user mapping adapter.");
   }
 }
 
+export const SupabaseAuthProviderStub = SupabaseAuthProviderAdapter;
+
 export class SupabasePostgresProviderStub {
   constructor({ env = process.env } = {}) {
     this.env = env;
@@ -213,11 +309,21 @@ export function createProviderContractSnapshot(env = process.env) {
     },
     supabaseAuth: {
       configured: supabaseAuthMissing.length === 0,
-      diagnostic: supabaseAuthSelected ? supabaseAuthDiagnostic(env) : "Supabase Auth provider stub is inactive.",
+      adapter: {
+        activeByDefault: false,
+        implementation: "config-gated Supabase Auth REST adapter",
+        passwordStorage: "external-provider",
+        serviceRoleSecretsUsed: false,
+      },
+      diagnostic: supabaseAuthSelected ? supabaseAuthDiagnostic(env) : "Supabase Auth provider adapter is inactive.",
       missingBrowserSafeEnvironmentVariables: supabaseAuthSelected ? supabaseAuthMissing : [],
       operations: AUTH_PROVIDER_CONTRACT_OPERATIONS.slice(),
       providerId: SUPABASE_AUTH_PROVIDER_ID,
-      status: supabaseAuthSelected && supabaseAuthMissing.length ? "not-configured" : "stub",
+      status: supabaseAuthSelected && supabaseAuthMissing.length
+        ? "not-configured"
+        : supabaseAuthMissing.length
+          ? "adapter-inactive"
+          : "adapter-ready",
       userMapping: {
         appUserKeyField: "users.key",
         browserAuthoritativeUserKeysAllowed: false,

tests/dev-runtime/SupabaseProviderContractStub.test.mjs

@@ -3,6 +3,7 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { readFile } from "node:fs/promises";
 import {
+  SupabaseAuthProviderAdapter,
   SupabaseAuthProviderStub,
   SupabasePostgresProviderStub,
   createProviderContractSnapshot,
@@ -77,7 +78,10 @@ test("Supabase provider contract stubs keep Local DB active by default", () => {
   assert.equal(snapshot.requestedProviders.authProviderId, "local-db");
   assert.equal(snapshot.requestedProviders.databaseProviderId, "local-db");
   assert.equal(snapshot.boundary, "Browser -> API/Service Contract -> Database");
-  assert.equal(snapshot.supabaseAuth.status, "stub");
+  assert.equal(snapshot.supabaseAuth.status, "adapter-inactive");
+  assert.equal(snapshot.supabaseAuth.adapter.activeByDefault, false);
+  assert.equal(snapshot.supabaseAuth.adapter.passwordStorage, "external-provider");
+  assert.equal(snapshot.supabaseAuth.adapter.serviceRoleSecretsUsed, false);
   assert.deepEqual(snapshot.supabaseAuth.operations, [
     "getCurrentUser",
     "signIn",
@@ -168,15 +172,56 @@ test("Supabase stubs do not expose server-only secret names or values through th
   });
 });
 
-test("Supabase provider classes are stubs only and do not implement runtime sign-in or database access", () => {
+test("Supabase Auth adapter fails visibly when selected without configuration", async () => {
   const auth = new SupabaseAuthProviderStub({ env: { GAMEFOUNDRY_AUTH_PROVIDER: "supabase-auth" } });
+  await assert.rejects(() => auth.getCurrentUser(), /Supabase Auth provider selected but not configured/);
+  await assert.rejects(() => auth.signIn(), /Supabase Auth provider selected but not configured/);
+  await assert.rejects(() => auth.signOut(), /Supabase Auth provider selected but not configured/);
+  await assert.rejects(() => auth.createAccount(), /Supabase Auth provider selected but not configured/);
+  await assert.rejects(() => auth.requestPasswordReset(), /Supabase Auth provider selected but not configured/);
+  assert.throws(() => auth.requireRole(), /future app user mapping adapter/);
+});
+
+test("Supabase Auth adapter uses browser-safe env config without service-role values", async () => {
+  const calls = [];
+  const auth = new SupabaseAuthProviderAdapter({
+    env: {
+      GAMEFOUNDRY_SUPABASE_ANON_KEY: "test-anon-key",
+      GAMEFOUNDRY_SUPABASE_SERVICE_ROLE_KEY: "not-a-real-service-role-test-value",
+      GAMEFOUNDRY_SUPABASE_URL: "https://supabase-dev.example.test/",
+    },
+    fetchImpl: async (url, options) => {
+      calls.push({ options, url });
+      return {
+        json: async () => ({ ok: true, url }),
+        ok: true,
+        status: 200,
+      };
+    },
+  });
+
+  await auth.signIn({ email: "creator@example.test", password: "test-password" });
+  await auth.createAccount({ email: "new@example.test", password: "new-password" });
+  await auth.requestPasswordReset({ email: "reset@example.test", redirectTo: "http://127.0.0.1:5501/account/password-reset.html" });
+  await auth.getCurrentUser({ accessToken: "user-access-token" });
+  await auth.signOut({ accessToken: "user-access-token" });
+
+  assert.deepEqual(calls.map((call) => call.url), [
+    "https://supabase-dev.example.test/auth/v1/token?grant_type=password",
+    "https://supabase-dev.example.test/auth/v1/signup",
+    "https://supabase-dev.example.test/auth/v1/recover",
+    "https://supabase-dev.example.test/auth/v1/user",
+    "https://supabase-dev.example.test/auth/v1/logout",
+  ]);
+  const callText = JSON.stringify(calls);
+  assert.equal(callText.includes("not-a-real-service-role-test-value"), false);
+  assert.equal(calls.every((call) => call.options.headers.apikey === "test-anon-key"), true);
+  assert.equal(calls[3].options.headers.authorization, "Bearer user-access-token");
+  assert.equal(calls[4].options.headers.authorization, "Bearer user-access-token");
+});
+
+test("Supabase Postgres provider class remains stub only and does not implement database access", () => {
   const database = new SupabasePostgresProviderStub({ env: { GAMEFOUNDRY_DB_PROVIDER: "supabase-postgres" } });
-  assert.throws(() => auth.getCurrentUser(), /Supabase Auth provider selected but not configured/);
-  assert.throws(() => auth.signIn(), /Supabase Auth provider selected but not configured/);
-  assert.throws(() => auth.signOut(), /Supabase Auth provider selected but not configured/);
-  assert.throws(() => auth.createAccount(), /Supabase Auth provider selected but not configured/);
-  assert.throws(() => auth.requestPasswordReset(), /Supabase Auth provider selected but not configured/);
-  assert.throws(() => auth.requireRole(), /Supabase Auth provider selected but not configured/);
   assert.throws(() => database.connect(), /Supabase Postgres provider selected but not configured/);
   assert.throws(() => database.getUsers(), /Supabase Postgres provider selected but not configured/);
   assert.throws(() => database.getRoles(), /Supabase Postgres provider selected but not configured/);