@constructive-io/graphql-server 4.17.0 → 4.18.0

package/esm/middleware/api.js

@@ -75,6 +75,34 @@ const RLS_MODULE_SQL = `
   WHERE api_id = $1 AND name = 'rls_module'
   LIMIT 1
 `;
+/**
+ * Discover auth settings table location via public metaschema tables.
+ * Joins sessions_module with metaschema_public.schema to resolve
+ * the schema name + table name without touching private schemas.
+ */
+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
+  LIMIT 1
+`;
+/**
+ * Query auth settings from the discovered table.
+ * Schema and table name are resolved dynamically from metaschema modules.
+ */
+const AUTH_SETTINGS_SQL = (schemaName, tableName) => `
+  SELECT
+    cookie_secure,
+    cookie_samesite,
+    cookie_domain,
+    cookie_httponly,
+    cookie_max_age,
+    cookie_path,
+    enable_captcha,
+    captcha_site_key
+  FROM "${schemaName}"."${tableName}"
+  LIMIT 1
+`;
 // =============================================================================
 // Helpers
 // =============================================================================
@@ -127,7 +155,21 @@ const toRlsModule = (row) => {
         currentUserAgent: d.current_user_agent,
     };
 };
-const toApiStructure = (row, opts, rlsModuleRow) => ({
+const toAuthSettings = (row) => {
+    if (!row)
+        return undefined;
+    return {
+        cookieSecure: row.cookie_secure,
+        cookieSamesite: row.cookie_samesite,
+        cookieDomain: row.cookie_domain,
+        cookieHttponly: row.cookie_httponly,
+        cookieMaxAge: row.cookie_max_age,
+        cookiePath: row.cookie_path,
+        enableCaptcha: row.enable_captcha,
+        captchaSiteKey: row.captcha_site_key,
+    };
+};
+const toApiStructure = (row, opts, rlsModuleRow, authSettingsRow) => ({
     apiId: row.api_id,
     dbname: row.dbname || opts.pg?.database || '',
     anonRole: row.anon_role || 'anon',
@@ -138,6 +180,7 @@ const toApiStructure = (row, opts, rlsModuleRow) => ({
     domains: [],
     databaseId: row.database_id,
     isPublic: row.is_public,
+    authSettings: toAuthSettings(authSettingsRow ?? null),
 });
 const createAdminStructure = (opts, schemas, databaseId) => ({
     dbname: opts.pg?.database ?? '',
@@ -172,6 +215,32 @@ const queryRlsModule = async (pool, apiId) => {
     const result = await pool.query(RLS_MODULE_SQL, [apiId]);
     return result.rows[0] ?? null;
 };
+/**
+ * Load server-relevant auth settings from the tenant DB.
+ * Discovers the auth settings table dynamically by joining
+ * metaschema_modules_public.sessions_module with metaschema_public.schema
+ * (both public schemas). Fails gracefully if modules or table don't exist yet.
+ */
+const queryAuthSettings = async (opts, dbname) => {
+    try {
+        const tenantPool = getPgPool({ ...opts.pg, database: dbname });
+        // Discover the auth settings schema + table name from public metaschema tables
+        const discovery = await tenantPool.query(AUTH_SETTINGS_DISCOVERY_SQL);
+        const resolved = discovery.rows[0];
+        if (!resolved) {
+            log.debug('[auth-settings] No sessions_module row found in tenant DB');
+            return null;
+        }
+        // Query the discovered auth settings table
+        const result = await tenantPool.query(AUTH_SETTINGS_SQL(resolved.schema_name, resolved.table_name));
+        return result.rows[0] ?? null;
+    }
+    catch (e) {
+        // Table/module may not exist yet if the 2FA migration hasn't been applied
+        log.debug(`[auth-settings] Failed to load auth settings: ${e.message}`);
+        return null;
+    }
+};
 // =============================================================================
 // Resolution Logic
 // =============================================================================
@@ -223,8 +292,9 @@ const resolveApiNameHeader = async (ctx) => {
         return null;
     }
     const rlsModule = await queryRlsModule(pool, row.api_id);
-    log.debug(`[api-name-lookup] resolved schemas: [${row.schemas?.join(', ')}], rlsModule: ${rlsModule ? 'found' : 'none'}`);
-    return toApiStructure(row, opts, rlsModule);
+    const authSettings = await queryAuthSettings(opts, row.dbname);
+    log.debug(`[api-name-lookup] resolved schemas: [${row.schemas?.join(', ')}], rlsModule: ${rlsModule ? 'found' : 'none'}, authSettings: ${authSettings ? 'found' : 'none'}`);
+    return toApiStructure(row, opts, rlsModule, authSettings);
 };
 const resolveMetaSchemaHeader = (ctx, validatedSchemas) => {
     return createAdminStructure(ctx.opts, validatedSchemas, ctx.headers.databaseId);
@@ -239,8 +309,9 @@ const resolveDomainLookup = async (ctx) => {
         return null;
     }
     const rlsModule = await queryRlsModule(pool, row.api_id);
-    log.debug(`[domain-lookup] resolved schemas: [${row.schemas?.join(', ')}], rlsModule: ${rlsModule ? 'found' : 'none'}`);
-    return toApiStructure(row, opts, rlsModule);
+    const authSettings = await queryAuthSettings(opts, row.dbname);
+    log.debug(`[domain-lookup] resolved schemas: [${row.schemas?.join(', ')}], rlsModule: ${rlsModule ? 'found' : 'none'}, authSettings: ${authSettings ? 'found' : 'none'}`);
+    return toApiStructure(row, opts, rlsModule, authSettings);
 };
 const buildDevFallbackError = async (ctx, req) => {
     if (getNodeEnv() !== 'development')

package/esm/middleware/auth.js

@@ -5,6 +5,19 @@ import pgQueryContext from 'pg-query-context';
 import './types'; // for Request type
 const log = new Logger('auth');
 const isDev = () => getNodeEnv() === 'development';
+/** Default cookie name for session tokens. */
+const SESSION_COOKIE_NAME = 'constructive_session';
+/**
+ * Extract a named cookie value from the raw Cookie header.
+ * Avoids pulling in cookie-parser as a dependency.
+ */
+const parseCookieToken = (req, cookieName) => {
+    const header = req.headers.cookie;
+    if (!header)
+        return undefined;
+    const match = header.split(';').find((c) => c.trim().startsWith(`${cookieName}=`));
+    return match ? decodeURIComponent(match.split('=')[1].trim()) : undefined;
+};
 export const createAuthenticateMiddleware = (opts) => {
     return async (req, res, next) => {
         const api = req.api;
@@ -36,8 +49,14 @@ export const createAuthenticateMiddleware = (opts) => {
             let token = {};
             log.info(`[auth] authorization header present=${!!authorization}, ` +
                 `authType=${authType ?? 'none'}, hasToken=${!!authToken}`);
-            if (authType?.toLowerCase() === 'bearer' && authToken) {
-                log.info('[auth] Processing bearer token authentication');
+            // Resolve the credential: prefer Bearer header, fall back to session cookie
+            const cookieToken = parseCookieToken(req, SESSION_COOKIE_NAME);
+            const effectiveToken = (authType?.toLowerCase() === 'bearer' && authToken)
+                ? authToken
+                : cookieToken;
+            const tokenSource = (authType?.toLowerCase() === 'bearer' && authToken) ? 'bearer' : (cookieToken ? 'cookie' : 'none');
+            if (effectiveToken) {
+                log.info(`[auth] Processing ${tokenSource} authentication`);
                 const context = {
                     'jwt.claims.ip_address': req.clientIp,
                 };
@@ -54,7 +73,7 @@ export const createAuthenticateMiddleware = (opts) => {
                         client: pool,
                         context,
                         query: authQuery,
-                        variables: [authToken],
+                        variables: [effectiveToken],
                     });
                     log.info(`[auth] Query result: rowCount=${result?.rowCount}`);
                     if (result?.rowCount === 0) {
@@ -83,7 +102,7 @@ export const createAuthenticateMiddleware = (opts) => {
                 }
             }
             else {
-                log.info('[auth] No bearer token provided, using anonymous auth');
+                log.info('[auth] No credential provided (no bearer token or session cookie), using anonymous auth');
             }
             req.token = token;
         }

package/esm/middleware/captcha.js

@@ -0,0 +1,111 @@
+import { Logger } from '@pgpmjs/logger';
+import './types'; // for Request type
+const log = new Logger('captcha');
+/** Google reCAPTCHA verification endpoint */
+const RECAPTCHA_VERIFY_URL = 'https://www.google.com/recaptcha/api/siteverify';
+/**
+ * Header name the client sends the CAPTCHA response token in.
+ * Follows the common pattern: X-Captcha-Token.
+ */
+const CAPTCHA_HEADER = 'x-captcha-token';
+/**
+ * GraphQL mutation names that require CAPTCHA verification when enabled.
+ * Only sign-up and password-reset are gated; normal sign-in is not.
+ */
+const CAPTCHA_PROTECTED_OPERATIONS = new Set([
+    'signUp',
+    'signUpWithMagicLink',
+    'signUpWithSms',
+    'resetPassword',
+    'requestPasswordReset',
+]);
+/**
+ * Attempt to extract the GraphQL operation name from the request body.
+ * Works for both JSON and already-parsed bodies.
+ */
+const getOperationName = (req) => {
+    const body = req.body;
+    if (!body)
+        return undefined;
+    // Already parsed (express.json ran first)
+    if (typeof body === 'object' && body.operationName) {
+        return body.operationName;
+    }
+    return undefined;
+};
+/**
+ * Verify a reCAPTCHA token with Google's API.
+ */
+const verifyToken = async (token, secretKey) => {
+    try {
+        const params = new URLSearchParams({ secret: secretKey, response: token });
+        const res = await fetch(RECAPTCHA_VERIFY_URL, {
+            method: 'POST',
+            body: params,
+        });
+        const data = (await res.json());
+        if (!data.success) {
+            log.debug(`[captcha] Verification failed: ${data['error-codes']?.join(', ') ?? 'unknown'}`);
+        }
+        return data.success;
+    }
+    catch (e) {
+        log.error('[captcha] Error verifying token:', e.message);
+        return false;
+    }
+};
+/**
+ * Creates a CAPTCHA verification middleware.
+ *
+ * When `enable_captcha` is true in app_auth_settings, this middleware checks
+ * the X-Captcha-Token header on protected mutations (sign-up, password reset).
+ * The secret key is read from the RECAPTCHA_SECRET_KEY environment variable
+ * (the public site key is stored in app_auth_settings for the frontend).
+ *
+ * Skips verification when:
+ *  - CAPTCHA is not enabled in auth settings
+ *  - The request is not a protected mutation
+ *  - No secret key is configured server-side
+ */
+export const createCaptchaMiddleware = () => {
+    return async (req, res, next) => {
+        const authSettings = req.api?.authSettings;
+        // Skip if CAPTCHA is not enabled
+        if (!authSettings?.enableCaptcha) {
+            return next();
+        }
+        // Only gate protected operations
+        const opName = getOperationName(req);
+        if (!opName || !CAPTCHA_PROTECTED_OPERATIONS.has(opName)) {
+            return next();
+        }
+        // Secret key must be set server-side (env var, not stored in DB for security)
+        const secretKey = process.env.RECAPTCHA_SECRET_KEY;
+        if (!secretKey) {
+            log.warn('[captcha] enable_captcha is true but RECAPTCHA_SECRET_KEY env var is not set; skipping verification');
+            return next();
+        }
+        const captchaToken = req.get(CAPTCHA_HEADER);
+        if (!captchaToken) {
+            res.status(200).json({
+                errors: [{
+                        message: 'CAPTCHA verification required',
+                        extensions: { code: 'CAPTCHA_REQUIRED' },
+                    }],
+            });
+            return;
+        }
+        const valid = await verifyToken(captchaToken, secretKey);
+        if (!valid) {
+            res.status(200).json({
+                errors: [{
+                        message: 'CAPTCHA verification failed',
+                        extensions: { code: 'CAPTCHA_FAILED' },
+                    }],
+            });
+            return;
+        }
+        log.info(`[captcha] Verified for operation=${opName}`);
+        next();
+    };
+};

package/esm/middleware/graphile.js

@@ -158,14 +158,25 @@ const buildPreset = (pool, schemas, anonRole, roleName) => {
                         context['jwt.claims.user_agent'] = req.get('User-Agent');
                     }
                     if (req.token?.user_id) {
-                        return {
-                            pgSettings: {
-                                role: roleName,
-                                'jwt.claims.token_id': req.token.id,
-                                'jwt.claims.user_id': req.token.user_id,
-                                ...context,
-                            },
+                        const pgSettings = {
+                            role: roleName,
+                            'jwt.claims.token_id': req.token.id,
+                            'jwt.claims.user_id': req.token.user_id,
+                            ...context,
                         };
+                        // Propagate credential metadata as JWT claims so PG functions
+                        // can read them via current_setting('jwt.claims.access_level') etc.
+                        if (req.token.access_level) {
+                            pgSettings['jwt.claims.access_level'] = req.token.access_level;
+                        }
+                        if (req.token.kind) {
+                            pgSettings['jwt.claims.kind'] = req.token.kind;
+                        }
+                        // Enforce read-only transactions for read_only credentials (API keys, etc.)
+                        if (req.token.access_level === 'read_only') {
+                            pgSettings['default_transaction_read_only'] = 'on';
+                        }
+                        return { pgSettings };
                     }
                 }
                 return {

package/esm/server.js

@@ -21,6 +21,7 @@ import { createDebugDatabaseMiddleware } from './middleware/observability/debug-
 import { debugMemory } from './middleware/observability/debug-memory';
 import { localObservabilityOnly } from './middleware/observability/guard';
 import { createRequestLogger } from './middleware/observability/request-logger';
+import { createCaptchaMiddleware } from './middleware/captcha';
 import { createUploadAuthenticateMiddleware, uploadRoute } from './middleware/upload';
 import { startDebugSampler } from './diagnostics/debug-sampler';
 const log = new Logger('server');
@@ -132,6 +133,7 @@ class Server {
         app.use(api);
         app.post('/upload', uploadAuthenticate, ...uploadRoute);
         app.use(authenticate);
+        app.use(createCaptchaMiddleware());
         app.use(graphile(effectiveOpts));
         app.use(flush);
         // Error handling - MUST be LAST

package/middleware/api.js

@@ -81,6 +81,34 @@ const RLS_MODULE_SQL = `
   WHERE api_id = $1 AND name = 'rls_module'
   LIMIT 1
 `;
+/**
+ * Discover auth settings table location via public metaschema tables.
+ * Joins sessions_module with metaschema_public.schema to resolve
+ * the schema name + table name without touching private schemas.
+ */
+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
+  LIMIT 1
+`;
+/**
+ * Query auth settings from the discovered table.
+ * Schema and table name are resolved dynamically from metaschema modules.
+ */
+const AUTH_SETTINGS_SQL = (schemaName, tableName) => `
+  SELECT
+    cookie_secure,
+    cookie_samesite,
+    cookie_domain,
+    cookie_httponly,
+    cookie_max_age,
+    cookie_path,
+    enable_captcha,
+    captcha_site_key
+  FROM "${schemaName}"."${tableName}"
+  LIMIT 1
+`;
 // =============================================================================
 // Helpers
 // =============================================================================
@@ -135,7 +163,21 @@ const toRlsModule = (row) => {
         currentUserAgent: d.current_user_agent,
     };
 };
-const toApiStructure = (row, opts, rlsModuleRow) => ({
+const toAuthSettings = (row) => {
+    if (!row)
+        return undefined;
+    return {
+        cookieSecure: row.cookie_secure,
+        cookieSamesite: row.cookie_samesite,
+        cookieDomain: row.cookie_domain,
+        cookieHttponly: row.cookie_httponly,
+        cookieMaxAge: row.cookie_max_age,
+        cookiePath: row.cookie_path,
+        enableCaptcha: row.enable_captcha,
+        captchaSiteKey: row.captcha_site_key,
+    };
+};
+const toApiStructure = (row, opts, rlsModuleRow, authSettingsRow) => ({
     apiId: row.api_id,
     dbname: row.dbname || opts.pg?.database || '',
     anonRole: row.anon_role || 'anon',
@@ -146,6 +188,7 @@ const toApiStructure = (row, opts, rlsModuleRow) => ({
     domains: [],
     databaseId: row.database_id,
     isPublic: row.is_public,
+    authSettings: toAuthSettings(authSettingsRow ?? null),
 });
 const createAdminStructure = (opts, schemas, databaseId) => ({
     dbname: opts.pg?.database ?? '',
@@ -180,6 +223,32 @@ const queryRlsModule = async (pool, apiId) => {
     const result = await pool.query(RLS_MODULE_SQL, [apiId]);
     return result.rows[0] ?? null;
 };
+/**
+ * Load server-relevant auth settings from the tenant DB.
+ * Discovers the auth settings table dynamically by joining
+ * metaschema_modules_public.sessions_module with metaschema_public.schema
+ * (both public schemas). Fails gracefully if modules or table don't exist yet.
+ */
+const queryAuthSettings = async (opts, dbname) => {
+    try {
+        const tenantPool = (0, pg_cache_1.getPgPool)({ ...opts.pg, database: dbname });
+        // Discover the auth settings schema + table name from public metaschema tables
+        const discovery = await tenantPool.query(AUTH_SETTINGS_DISCOVERY_SQL);
+        const resolved = discovery.rows[0];
+        if (!resolved) {
+            log.debug('[auth-settings] No sessions_module row found in tenant DB');
+            return null;
+        }
+        // Query the discovered auth settings table
+        const result = await tenantPool.query(AUTH_SETTINGS_SQL(resolved.schema_name, resolved.table_name));
+        return result.rows[0] ?? null;
+    }
+    catch (e) {
+        // Table/module may not exist yet if the 2FA migration hasn't been applied
+        log.debug(`[auth-settings] Failed to load auth settings: ${e.message}`);
+        return null;
+    }
+};
 // =============================================================================
 // Resolution Logic
 // =============================================================================
@@ -231,8 +300,9 @@ const resolveApiNameHeader = async (ctx) => {
         return null;
     }
     const rlsModule = await queryRlsModule(pool, row.api_id);
-    log.debug(`[api-name-lookup] resolved schemas: [${row.schemas?.join(', ')}], rlsModule: ${rlsModule ? 'found' : 'none'}`);
-    return toApiStructure(row, opts, rlsModule);
+    const authSettings = await queryAuthSettings(opts, row.dbname);
+    log.debug(`[api-name-lookup] resolved schemas: [${row.schemas?.join(', ')}], rlsModule: ${rlsModule ? 'found' : 'none'}, authSettings: ${authSettings ? 'found' : 'none'}`);
+    return toApiStructure(row, opts, rlsModule, authSettings);
 };
 const resolveMetaSchemaHeader = (ctx, validatedSchemas) => {
     return createAdminStructure(ctx.opts, validatedSchemas, ctx.headers.databaseId);
@@ -247,8 +317,9 @@ const resolveDomainLookup = async (ctx) => {
         return null;
     }
     const rlsModule = await queryRlsModule(pool, row.api_id);
-    log.debug(`[domain-lookup] resolved schemas: [${row.schemas?.join(', ')}], rlsModule: ${rlsModule ? 'found' : 'none'}`);
-    return toApiStructure(row, opts, rlsModule);
+    const authSettings = await queryAuthSettings(opts, row.dbname);
+    log.debug(`[domain-lookup] resolved schemas: [${row.schemas?.join(', ')}], rlsModule: ${rlsModule ? 'found' : 'none'}, authSettings: ${authSettings ? 'found' : 'none'}`);
+    return toApiStructure(row, opts, rlsModule, authSettings);
 };
 const buildDevFallbackError = async (ctx, req) => {
     if ((0, env_1.getNodeEnv)() !== 'development')

package/middleware/auth.js

@@ -11,6 +11,19 @@ const pg_query_context_1 = __importDefault(require("pg-query-context"));
 require("./types"); // for Request type
 const log = new logger_1.Logger('auth');
 const isDev = () => (0, env_1.getNodeEnv)() === 'development';
+/** Default cookie name for session tokens. */
+const SESSION_COOKIE_NAME = 'constructive_session';
+/**
+ * Extract a named cookie value from the raw Cookie header.
+ * Avoids pulling in cookie-parser as a dependency.
+ */
+const parseCookieToken = (req, cookieName) => {
+    const header = req.headers.cookie;
+    if (!header)
+        return undefined;
+    const match = header.split(';').find((c) => c.trim().startsWith(`${cookieName}=`));
+    return match ? decodeURIComponent(match.split('=')[1].trim()) : undefined;
+};
 const createAuthenticateMiddleware = (opts) => {
     return async (req, res, next) => {
         const api = req.api;
@@ -42,8 +55,14 @@ const createAuthenticateMiddleware = (opts) => {
             let token = {};
             log.info(`[auth] authorization header present=${!!authorization}, ` +
                 `authType=${authType ?? 'none'}, hasToken=${!!authToken}`);
-            if (authType?.toLowerCase() === 'bearer' && authToken) {
-                log.info('[auth] Processing bearer token authentication');
+            // Resolve the credential: prefer Bearer header, fall back to session cookie
+            const cookieToken = parseCookieToken(req, SESSION_COOKIE_NAME);
+            const effectiveToken = (authType?.toLowerCase() === 'bearer' && authToken)
+                ? authToken
+                : cookieToken;
+            const tokenSource = (authType?.toLowerCase() === 'bearer' && authToken) ? 'bearer' : (cookieToken ? 'cookie' : 'none');
+            if (effectiveToken) {
+                log.info(`[auth] Processing ${tokenSource} authentication`);
                 const context = {
                     'jwt.claims.ip_address': req.clientIp,
                 };
@@ -60,7 +79,7 @@ const createAuthenticateMiddleware = (opts) => {
                         client: pool,
                         context,
                         query: authQuery,
-                        variables: [authToken],
+                        variables: [effectiveToken],
                     });
                     log.info(`[auth] Query result: rowCount=${result?.rowCount}`);
                     if (result?.rowCount === 0) {
@@ -89,7 +108,7 @@ const createAuthenticateMiddleware = (opts) => {
                 }
             }
             else {
-                log.info('[auth] No bearer token provided, using anonymous auth');
+                log.info('[auth] No credential provided (no bearer token or session cookie), using anonymous auth');
             }
             req.token = token;
         }

package/middleware/captcha.d.ts

@@ -0,0 +1,16 @@
+import type { RequestHandler } from 'express';
+import './types';
+/**
+ * Creates a CAPTCHA verification middleware.
+ *
+ * When `enable_captcha` is true in app_auth_settings, this middleware checks
+ * the X-Captcha-Token header on protected mutations (sign-up, password reset).
+ * The secret key is read from the RECAPTCHA_SECRET_KEY environment variable
+ * (the public site key is stored in app_auth_settings for the frontend).
+ *
+ * Skips verification when:
+ *  - CAPTCHA is not enabled in auth settings
+ *  - The request is not a protected mutation
+ *  - No secret key is configured server-side
+ */
+export declare const createCaptchaMiddleware: () => RequestHandler;

package/middleware/captcha.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCaptchaMiddleware = void 0;
+const logger_1 = require("@pgpmjs/logger");
+require("./types"); // for Request type
+const log = new logger_1.Logger('captcha');
+/** Google reCAPTCHA verification endpoint */
+const RECAPTCHA_VERIFY_URL = 'https://www.google.com/recaptcha/api/siteverify';
+/**
+ * Header name the client sends the CAPTCHA response token in.
+ * Follows the common pattern: X-Captcha-Token.
+ */
+const CAPTCHA_HEADER = 'x-captcha-token';
+/**
+ * GraphQL mutation names that require CAPTCHA verification when enabled.
+ * Only sign-up and password-reset are gated; normal sign-in is not.
+ */
+const CAPTCHA_PROTECTED_OPERATIONS = new Set([
+    'signUp',
+    'signUpWithMagicLink',
+    'signUpWithSms',
+    'resetPassword',
+    'requestPasswordReset',
+]);
+/**
+ * Attempt to extract the GraphQL operation name from the request body.
+ * Works for both JSON and already-parsed bodies.
+ */
+const getOperationName = (req) => {
+    const body = req.body;
+    if (!body)
+        return undefined;
+    // Already parsed (express.json ran first)
+    if (typeof body === 'object' && body.operationName) {
+        return body.operationName;
+    }
+    return undefined;
+};
+/**
+ * Verify a reCAPTCHA token with Google's API.
+ */
+const verifyToken = async (token, secretKey) => {
+    try {
+        const params = new URLSearchParams({ secret: secretKey, response: token });
+        const res = await fetch(RECAPTCHA_VERIFY_URL, {
+            method: 'POST',
+            body: params,
+        });
+        const data = (await res.json());
+        if (!data.success) {
+            log.debug(`[captcha] Verification failed: ${data['error-codes']?.join(', ') ?? 'unknown'}`);
+        }
+        return data.success;
+    }
+    catch (e) {
+        log.error('[captcha] Error verifying token:', e.message);
+        return false;
+    }
+};
+/**
+ * Creates a CAPTCHA verification middleware.
+ *
+ * When `enable_captcha` is true in app_auth_settings, this middleware checks
+ * the X-Captcha-Token header on protected mutations (sign-up, password reset).
+ * The secret key is read from the RECAPTCHA_SECRET_KEY environment variable
+ * (the public site key is stored in app_auth_settings for the frontend).
+ *
+ * Skips verification when:
+ *  - CAPTCHA is not enabled in auth settings
+ *  - The request is not a protected mutation
+ *  - No secret key is configured server-side
+ */
+const createCaptchaMiddleware = () => {
+    return async (req, res, next) => {
+        const authSettings = req.api?.authSettings;
+        // Skip if CAPTCHA is not enabled
+        if (!authSettings?.enableCaptcha) {
+            return next();
+        }
+        // Only gate protected operations
+        const opName = getOperationName(req);
+        if (!opName || !CAPTCHA_PROTECTED_OPERATIONS.has(opName)) {
+            return next();
+        }
+        // Secret key must be set server-side (env var, not stored in DB for security)
+        const secretKey = process.env.RECAPTCHA_SECRET_KEY;
+        if (!secretKey) {
+            log.warn('[captcha] enable_captcha is true but RECAPTCHA_SECRET_KEY env var is not set; skipping verification');
+            return next();
+        }
+        const captchaToken = req.get(CAPTCHA_HEADER);
+        if (!captchaToken) {
+            res.status(200).json({
+                errors: [{
+                        message: 'CAPTCHA verification required',
+                        extensions: { code: 'CAPTCHA_REQUIRED' },
+                    }],
+            });
+            return;
+        }
+        const valid = await verifyToken(captchaToken, secretKey);
+        if (!valid) {
+            res.status(200).json({
+                errors: [{
+                        message: 'CAPTCHA verification failed',
+                        extensions: { code: 'CAPTCHA_FAILED' },
+                    }],
+            });
+            return;
+        }
+        log.info(`[captcha] Verified for operation=${opName}`);
+        next();
+    };
+};
+exports.createCaptchaMiddleware = createCaptchaMiddleware;

package/middleware/graphile.js

@@ -167,14 +167,25 @@ const buildPreset = (pool, schemas, anonRole, roleName) => {
                         context['jwt.claims.user_agent'] = req.get('User-Agent');
                     }
                     if (req.token?.user_id) {
-                        return {
-                            pgSettings: {
-                                role: roleName,
-                                'jwt.claims.token_id': req.token.id,
-                                'jwt.claims.user_id': req.token.user_id,
-                                ...context,
-                            },
+                        const pgSettings = {
+                            role: roleName,
+                            'jwt.claims.token_id': req.token.id,
+                            'jwt.claims.user_id': req.token.user_id,
+                            ...context,
                         };
+                        // Propagate credential metadata as JWT claims so PG functions
+                        // can read them via current_setting('jwt.claims.access_level') etc.
+                        if (req.token.access_level) {
+                            pgSettings['jwt.claims.access_level'] = req.token.access_level;
+                        }
+                        if (req.token.kind) {
+                            pgSettings['jwt.claims.kind'] = req.token.kind;
+                        }
+                        // Enforce read-only transactions for read_only credentials (API keys, etc.)
+                        if (req.token.access_level === 'read_only') {
+                            pgSettings['default_transaction_read_only'] = 'on';
+                        }
+                        return { pgSettings };
                     }
                 }
                 return {

package/middleware/types.d.ts

@@ -2,6 +2,8 @@ import type { ApiStructure } from '../types';
 export type ConstructiveAPIToken = {
     id?: string;
     user_id?: string;
+    access_level?: string;
+    kind?: string;
     [key: string]: unknown;
 };
 declare global {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-server",
-  "version": "4.17.0",
+  "version": "4.18.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "Constructive GraphQL Server",
   "main": "index.js",
@@ -41,38 +41,38 @@
     "backend"
   ],
   "dependencies": {
-    "@constructive-io/graphql-env": "^3.5.4",
-    "@constructive-io/graphql-types": "^3.4.4",
-    "@constructive-io/s3-utils": "^2.10.2",
-    "@constructive-io/upload-names": "^2.10.2",
-    "@constructive-io/url-domains": "^2.10.2",
+    "@constructive-io/graphql-env": "^3.6.0",
+    "@constructive-io/graphql-types": "^3.5.0",
+    "@constructive-io/s3-utils": "^2.11.0",
+    "@constructive-io/upload-names": "^2.11.0",
+    "@constructive-io/url-domains": "^2.11.0",
     "@graphile-contrib/pg-many-to-many": "2.0.0-rc.2",
     "@graphile/simplify-inflection": "8.0.0",
-    "@pgpmjs/env": "^2.17.0",
-    "@pgpmjs/logger": "^2.5.2",
-    "@pgpmjs/server-utils": "^3.5.4",
-    "@pgpmjs/types": "^2.21.0",
+    "@pgpmjs/env": "^2.18.0",
+    "@pgpmjs/logger": "^2.6.0",
+    "@pgpmjs/server-utils": "^3.6.0",
+    "@pgpmjs/types": "^2.22.0",
     "@pgsql/quotes": "^17.1.0",
     "cors": "^2.8.6",
     "deepmerge": "^4.3.1",
     "express": "^5.2.1",
-    "gql-ast": "^3.4.2",
+    "gql-ast": "^3.5.0",
     "grafast": "1.0.0",
     "grafserv": "1.0.0",
     "graphile-build": "5.0.0",
     "graphile-build-pg": "5.0.0",
-    "graphile-cache": "^3.4.4",
+    "graphile-cache": "^3.5.0",
     "graphile-config": "1.0.0",
-    "graphile-settings": "^4.20.2",
+    "graphile-settings": "^4.21.0",
     "graphile-utils": "5.0.0",
     "graphql": "16.13.0",
     "graphql-upload": "^13.0.0",
     "lru-cache": "^11.2.7",
     "multer": "^2.1.1",
     "pg": "^8.20.0",
-    "pg-cache": "^3.4.4",
-    "pg-env": "^1.8.2",
-    "pg-query-context": "^2.9.2",
+    "pg-cache": "^3.5.0",
+    "pg-env": "^1.9.0",
+    "pg-query-context": "^2.10.0",
     "pg-sql2": "5.0.0",
     "postgraphile": "5.0.0",
     "request-ip": "^3.3.0"
@@ -85,10 +85,10 @@
     "@types/multer": "^2.1.0",
     "@types/pg": "^8.18.0",
     "@types/request-ip": "^0.0.41",
-    "graphile-test": "4.8.1",
+    "graphile-test": "4.9.0",
     "makage": "^0.3.0",
     "nodemon": "^3.1.14",
     "ts-node": "^10.9.2"
   },
-  "gitHead": "d4ab16de23b2434617e820fcffaec0f008a7b6a0"
+  "gitHead": "1b3af3c5189b9ca2e765b9239a4b287099e64a03"
 }

package/server.js

@@ -27,6 +27,7 @@ const debug_db_1 = require("./middleware/observability/debug-db");
 const debug_memory_1 = require("./middleware/observability/debug-memory");
 const guard_1 = require("./middleware/observability/guard");
 const request_logger_1 = require("./middleware/observability/request-logger");
+const captcha_1 = require("./middleware/captcha");
 const upload_1 = require("./middleware/upload");
 const debug_sampler_1 = require("./diagnostics/debug-sampler");
 const log = new logger_1.Logger('server');
@@ -139,6 +140,7 @@ class Server {
         app.use(api);
         app.post('/upload', uploadAuthenticate, ...upload_1.uploadRoute);
         app.use(authenticate);
+        app.use((0, captcha_1.createCaptchaMiddleware)());
         app.use((0, graphile_1.graphile)(effectiveOpts));
         app.use(flush_1.flush);
         // Error handling - MUST be LAST

package/types.d.ts

@@ -38,6 +38,23 @@ export interface RlsModule {
     currentIpAddress: string;
     currentUserAgent: string;
 }
+/**
+ * Server-visible subset of app_auth_settings (lives in the tenant DB private schema).
+ * Discovered dynamically via metaschema_modules_public.sessions_module.
+ * Loaded once per API resolution and cached alongside the ApiStructure.
+ */
+export interface AuthSettings {
+    /** Cookie configuration */
+    cookieSecure?: boolean;
+    cookieSamesite?: string;
+    cookieDomain?: string | null;
+    cookieHttponly?: boolean;
+    cookieMaxAge?: string | null;
+    cookiePath?: string;
+    /** reCAPTCHA / CAPTCHA */
+    enableCaptcha?: boolean;
+    captchaSiteKey?: string | null;
+}
 export interface ApiStructure {
     apiId?: string;
     dbname: string;
@@ -49,6 +66,7 @@ export interface ApiStructure {
     domains?: string[];
     databaseId?: string;
     isPublic?: boolean;
+    authSettings?: AuthSettings;
 }
 export type ApiError = {
     errorHtml: string;