Add admin-managed OAuth sign-in flow

docs/plan/oauth/oauth-implementation-followup.md

@@ -0,0 +1,31 @@
+# OAuth Implementation Follow-up
+
+## Identity Providers Module Scope
+
+- Investigate the platform `identity_providers_module` record whose `scope` is currently `app`. For platform-level OAuth configuration, the expected scope appears to be `platform`; keeping it as `app` may be a provisioning or migration artifact and can make platform OAuth semantics ambiguous.
+
+## Identity Auth Function Metadata
+
+- Consider making `sign_in_identity_function` and `sign_up_identity_function` metadata-driven. These functions are generated by the user auth module, but the current express-context config uses hardcoded function names. A future database/schema update could expose these function names through module metadata, similar to other auth functions.
+
+## Auth Settings Interval Parsing
+
+- Fix cookie/session duration parsing after the OAuth loader work lands. `app_settings_auth.cookie_max_age`, `remember_me_duration`, and `oauth_state_max_age` are PostgreSQL `interval` columns; `pg` returns them as `PostgresInterval` objects such as `{ days: 14 }` or `{ minutes: 10 }`. The current GraphQL server cookie helper still parses these values as second strings with `parseInt`, so loader-backed auth settings can silently fall back to defaults. This is an existing cookie auth settings compatibility issue exposed by the OAuth/auth settings loader path and should be handled in a follow-up PR.
+
+## Loader Cache Invalidation and TTL Semantics
+
+- Revisit `createModuleLoader` cache expiration and invalidation semantics. The current implementation uses `updateAgeOnGet: true`, so each cache hit refreshes the TTL and frequently accessed config may not expire while traffic continues. The reference branch changed the default to `false`, but the desired behavior should be decided together with explicit invalidation for writes performed by our own systems.
+
+- Known changes made through this process, such as admin APIs updating auth settings or identity providers, should invalidate the relevant loader cache after the database write succeeds. The current auth settings update path invalidates `authSettingsLoader`, but identity provider admin writes do not yet invalidate the cached OAuth provider config. Recommended shape: loaders own read, transform, cache, and invalidate; services or repositories own validate, authorize, write, audit, and post-write invalidate. For example, `identityProvidersService.updateProvider(ctx, input)` writes the provider config and then calls a targeted invalidation such as `registry.invalidate(ctx.databaseId, "identityProviders")` or the equivalent loader-specific invalidation API.
+
+- Unknown external changes, such as manual SQL, migrations, or another service updating module configuration, cannot be invalidated precisely by this process. Baseline approach: keep `updateAgeOnGet: false` so TTL remains a bounded staleness window, then reload from the database on the next read after TTL expiry. If stronger freshness is needed later, add an optional lightweight fingerprint probe near loader resolution, for example `getFingerprint(ctx)` using `updated_at`, version, or checksum plus `revalidateAfterMs` as the minimum interval between probes. This lets loaders detect external changes faster than full TTL expiry without fully reloading config on every request.
+
+- Recommendation: set `updateAgeOnGet` to `false`, add explicit post-write invalidation for known admin writes, and rely on TTL as the fallback for unknown external changes. Add fingerprint probing only if TTL-based staleness becomes too slow in practice.
+
+## API Service Cache Loader Snapshots
+
+- Revisit `graphql/server/src/middleware/api.ts` storing resolved loader values inside the cached `ApiStructure`. The API resolver currently resolves mutable module settings such as `authSettings`, `corsOrigins`, `databaseSettings`, `pubkeyChallengeSettings`, and `webauthnSettings`, then stores the whole API structure in `svcCache`, whose TTL is effectively long-lived. This can bypass each loader's own TTL and invalidation path; for example, `updateAuthSettings()` invalidates `authSettingsLoader`, but middleware that reads `req.api.authSettings` could still see the old value from `svcCache`. Consider narrowing `svcCache` to stable API routing fields only, resolving mutable module settings through `ctx.useModule(...)` at use sites, or adding coordinated `svcCache` invalidation whenever loader-backed settings are updated.
+
+## Env Config Consolidation
+
+- Consider moving existing CAPTCHA and upload environment variables into the shared `@pgpmjs/env` config surface in a separate cleanup PR. The reference OAuth branch added `RECAPTCHA_SECRET_KEY` and `MAX_UPLOAD_FILE_SIZE` to `PgpmOptions`, but this OAuth migration keeps those existing middleware paths on direct `process.env` reads to avoid widening the PR scope beyond OAuth/server admin APIs.

graphql/env/__tests__/__snapshots__/merge.test.ts.snap

@@ -100,6 +100,7 @@ exports[`getEnvOptions merges pgpm defaults, graphql defaults, config, env, and
       "useTx": false,
     },
   },
+  "oauth": {},
   "pg": {
     "database": "config-db",
     "host": "override-host",

graphql/server/package.json

@@ -45,13 +45,15 @@
     "@constructive-io/express-context": "workspace:^",
     "@constructive-io/graphql-env": "workspace:^",
     "@constructive-io/graphql-types": "workspace:^",
+    "@constructive-io/oauth": "workspace:^",
     "@constructive-io/s3-utils": "workspace:^",
     "@constructive-io/url-domains": "workspace:^",
     "@graphile-contrib/pg-many-to-many": "2.0.0-rc.2",
     "@pgpmjs/env": "workspace:^",
     "@pgpmjs/logger": "workspace:^",
     "@pgpmjs/server-utils": "workspace:^",
     "@pgpmjs/types": "workspace:^",
+    "@pgsql/quotes": "^17.1.0",
     "agentic-server": "workspace:*",
     "cors": "^2.8.6",
     "deepmerge": "^4.3.1",

graphql/server/src/index.ts

@@ -3,6 +3,8 @@ export * from './server';
 // Export middleware for use in testing packages
 export { createApiMiddleware, getSubdomain, getApiConfig } from './middleware/api';
 export { createAuthenticateMiddleware } from './middleware/auth';
+export { createIdentityProvidersRouter } from './middleware/identity-providers';
+export { createAppSettingsAuthRouter } from './middleware/app-settings-auth';
 export { cors } from './middleware/cors';
 export { graphile } from './middleware/graphile';
 export { flush, flushService } from './middleware/flush';

graphql/server/src/middleware/app-settings-auth.ts

@@ -0,0 +1,268 @@
+/**
+ * App Settings Auth API
+ *
+ * Express router for managing auth settings (cookie config, captcha, OAuth settings).
+ * Requires administrator role. Reads/writes to app_settings_auth table via
+ * the authSettings loader.
+ *
+ * Routes:
+ *   GET   /app-settings-auth  → get current settings
+ *   PATCH /app-settings-auth  → update settings
+ */
+
+import express, { Router, Request, Response } from 'express';
+import { Logger } from '@pgpmjs/logger';
+import { QuoteUtils } from '@pgsql/quotes';
+import {
+  authSettingsLoader,
+  type AuthSettings,
+  type ConstructiveContext,
+} from '@constructive-io/express-context';
+
+import './types';
+
+const log = new Logger('app-settings-auth');
+
+// ─── SQL ────────────────────────────────────────────────────────────────────
+
+const AUTH_SETTINGS_DISCOVERY_SQL = `
+  SELECT s.schema_name, sm.auth_settings_table AS table_name
+  FROM metaschema_modules_public.sessions_module sm
+  JOIN metaschema_public.schema s ON s.id = sm.schema_id
+  WHERE sm.database_id = $1
+  LIMIT 1
+`;
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+interface AuthSettingsTableRef {
+  schemaName: string;
+  tableName: string;
+}
+
+interface UpdateAuthSettingsInput {
+  allowIdentitySignIn?: boolean;
+  allowIdentitySignUp?: boolean;
+  cookieSecure?: boolean;
+  cookieSamesite?: string;
+  cookieDomain?: string | null;
+  cookieHttponly?: boolean;
+  cookieMaxAge?: string | null;
+  cookiePath?: string;
+  rememberMeDuration?: string | null;
+  enableCaptcha?: boolean;
+  captchaSiteKey?: string | null;
+  oauthStateMaxAge?: string | null;
+  oauthRequireVerifiedEmail?: boolean;
+  oauthErrorRedirectPath?: string | null;
+}
+
+type UpdateAuthSettingsResult =
+  | 'updated'
+  | 'not_configured'
+  | 'no_fields';
+
+const UPDATE_FIELD_MAP: Record<
+  keyof UpdateAuthSettingsInput,
+  { column: string; castInterval?: boolean }
+> = {
+  allowIdentitySignIn: { column: 'allow_identity_sign_in' },
+  allowIdentitySignUp: { column: 'allow_identity_sign_up' },
+  cookieSecure: { column: 'cookie_secure' },
+  cookieSamesite: { column: 'cookie_samesite' },
+  cookieDomain: { column: 'cookie_domain' },
+  cookieHttponly: { column: 'cookie_httponly' },
+  cookieMaxAge: { column: 'cookie_max_age', castInterval: true },
+  cookiePath: { column: 'cookie_path' },
+  rememberMeDuration: { column: 'remember_me_duration', castInterval: true },
+  enableCaptcha: { column: 'enable_captcha' },
+  captchaSiteKey: { column: 'captcha_site_key' },
+  oauthStateMaxAge: { column: 'oauth_state_max_age', castInterval: true },
+  oauthRequireVerifiedEmail: { column: 'oauth_require_verified_email' },
+  oauthErrorRedirectPath: { column: 'oauth_error_redirect_path' },
+};
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+async function isAppMember(ctx: ConstructiveContext): Promise<boolean> {
+  const userId = ctx.userId;
+  if (!userId) return false;
+
+  const sql = `
+    SELECT 1 FROM constructive_memberships_private.app_memberships_sprt
+    WHERE actor_id = $1
+    LIMIT 1
+  `;
+  const result = await ctx.pool.query(sql, [userId]);
+  return result.rows.length > 0;
+}
+
+async function requireAppMember(ctx: ConstructiveContext, res: Response): Promise<boolean> {
+  if (!(await isAppMember(ctx))) {
+    res.status(403).json({ error: 'MEMBERSHIP_REQUIRED' });
+    return false;
+  }
+  return true;
+}
+
+function sendAuthSettings(res: Response, settings: AuthSettings): void {
+  res.json({
+    allowIdentitySignIn: settings.allowIdentitySignIn,
+    allowIdentitySignUp: settings.allowIdentitySignUp,
+    cookieSecure: settings.cookieSecure,
+    cookieSamesite: settings.cookieSamesite,
+    cookieDomain: settings.cookieDomain,
+    cookieHttponly: settings.cookieHttponly,
+    cookieMaxAge: settings.cookieMaxAge,
+    cookiePath: settings.cookiePath,
+    rememberMeDuration: settings.rememberMeDuration,
+    enableCaptcha: settings.enableCaptcha,
+    captchaSiteKey: settings.captchaSiteKey,
+    oauthStateMaxAge: settings.oauthStateMaxAge,
+    oauthRequireVerifiedEmail: settings.oauthRequireVerifiedEmail,
+    oauthErrorRedirectPath: settings.oauthErrorRedirectPath,
+  });
+}
+
+async function discoverAuthSettingsTable(
+  ctx: ConstructiveContext,
+): Promise<AuthSettingsTableRef | null> {
+  if (!ctx.databaseId) return null;
+
+  const discovery = await ctx.pool.query<{ schema_name: string; table_name: string }>(
+    AUTH_SETTINGS_DISCOVERY_SQL,
+    [ctx.databaseId],
+  );
+  const resolved = discovery.rows[0];
+  if (!resolved) return null;
+
+  return {
+    schemaName: resolved.schema_name,
+    tableName: resolved.table_name,
+  };
+}
+
+function buildUpdateAuthSettingsQuery(
+  schemaName: string,
+  tableName: string,
+  patch: UpdateAuthSettingsInput,
+): { sql: string; values: unknown[] } | null {
+  const authSettingsTable = QuoteUtils.quoteQualifiedIdentifier(
+    schemaName,
+    tableName,
+  );
+  const setClauses: string[] = [];
+  const values: unknown[] = [];
+  let paramIndex = 1;
+
+  for (const [field, config] of Object.entries(UPDATE_FIELD_MAP) as Array<
+    [keyof UpdateAuthSettingsInput, { column: string; castInterval?: boolean }]
+  >) {
+    if (field in patch) {
+      const cast = config.castInterval ? '::interval' : '';
+      setClauses.push(
+        `${QuoteUtils.quoteIdentifier(config.column)} = $${paramIndex++}${cast}`,
+      );
+      values.push(patch[field]);
+    }
+  }
+
+  if (setClauses.length === 0) return null;
+
+  return {
+    sql: `
+      UPDATE ${authSettingsTable}
+      SET ${setClauses.join(', ')}
+    `,
+    values,
+  };
+}
+
+async function updateAuthSettings(
+  ctx: ConstructiveContext,
+  patch: UpdateAuthSettingsInput,
+): Promise<UpdateAuthSettingsResult> {
+  const table = await discoverAuthSettingsTable(ctx);
+  if (!table) return 'not_configured';
+
+  const update = buildUpdateAuthSettingsQuery(
+    table.schemaName,
+    table.tableName,
+    patch,
+  );
+  if (!update) return 'no_fields';
+
+  await ctx.pool.query(update.sql, update.values);
+  if (ctx.databaseId) {
+    authSettingsLoader.invalidate(ctx.databaseId);
+  }
+
+  return 'updated';
+}
+
+// ─── Router ─────────────────────────────────────────────────────────────────
+
+export function createAppSettingsAuthRouter(): Router {
+  const router = Router();
+
+  // Parse JSON body for PATCH requests
+  router.use(express.json());
+
+  /**
+   * GET /app-settings-auth
+   * Get current auth settings
+   */
+  router.get('/app-settings-auth', async (req: Request, res: Response) => {
+    const ctx = req.constructive;
+    if (!ctx) {
+      return res.status(500).json({ error: 'Missing context' });
+    }
+
+    if (!(await requireAppMember(ctx, res))) return;
+
+    try {
+      const settings = await ctx.useModule('authSettings');
+      if (!settings) {
+        return res.status(404).json({ error: 'Auth settings not found' });
+      }
+
+      sendAuthSettings(res, settings);
+    } catch (error) {
+      log.error('[app-settings-auth] Failed to get settings:', error);
+      res.status(500).json({ error: 'Failed to get settings' });
+    }
+  });
+
+  /**
+   * PATCH /app-settings-auth
+   * Update auth settings
+   */
+  router.patch('/app-settings-auth', async (req: Request, res: Response) => {
+    const ctx = req.constructive;
+    if (!ctx) {
+      return res.status(500).json({ error: 'Missing context' });
+    }
+
+    if (!(await requireAppMember(ctx, res))) return;
+
+    const body = req.body as UpdateAuthSettingsInput;
+
+    try {
+      const result = await updateAuthSettings(ctx, body);
+      if (result === 'not_configured') {
+        return res.status(404).json({ error: 'Auth settings module not configured' });
+      }
+      if (result === 'no_fields') {
+        return res.status(400).json({ error: 'No fields to update' });
+      }
+
+      log.info('[app-settings-auth] Updated settings');
+      res.json({ success: true });
+    } catch (error) {
+      log.error('[app-settings-auth] Failed to update settings:', error);
+      res.status(500).json({ error: 'Failed to update settings' });
+    }
+  });
+
+  return router;
+}

graphql/server/src/middleware/cookie.ts

@@ -24,10 +24,10 @@ export const getSessionCookieConfig = (
 ): CookieConfig => {
   const DEFAULT_MAX_AGE = 86400; // 24 hours
   let maxAge = DEFAULT_MAX_AGE;
-  if (rememberMe && authSettings?.rememberMeDuration) {
+  if (rememberMe && typeof authSettings?.rememberMeDuration === 'string') {
     const parsed = parseInt(authSettings.rememberMeDuration, 10);
     if (!isNaN(parsed)) maxAge = parsed;
-  } else if (authSettings?.cookieMaxAge) {
+  } else if (typeof authSettings?.cookieMaxAge === 'string') {
     const parsed = parseInt(authSettings.cookieMaxAge, 10);
     if (!isNaN(parsed)) maxAge = parsed;
   }