@constructive-io/graphql-server 5.28.9 → 5.29.0

package/esm/middleware/error-handler.js

@@ -1,30 +1,15 @@
 import './types';
-import { getNodeEnv } from '@pgpmjs/env';
 import { Logger } from '@pgpmjs/logger';
 import errorPage50x from '../errors/50x';
 import errorPage404Message from '../errors/404-message';
 import { isApiError } from '../errors/api-errors';
 const log = new Logger('error-handler');
-const isDevelopment = () => getNodeEnv() === 'development';
 const wantsJson = (req) => {
     const accept = req.get('Accept') || '';
     return accept.includes('application/json')
         || accept.includes('application/graphql-response+json')
         || Boolean(req.is('json'));
 };
-const sanitizeMessage = (error) => {
-    if (isDevelopment())
-        return error.message;
-    if (isApiError(error))
-        return error.message;
-    if (error.message?.includes('ECONNREFUSED'))
-        return 'Service temporarily unavailable';
-    if (error.message?.includes('timeout') || error.message?.includes('ETIMEDOUT'))
-        return 'Request timed out';
-    if (error.message?.includes('does not exist'))
-        return 'The requested resource does not exist';
-    return 'An unexpected error occurred';
-};
 const isCsrfError = (err) => {
     const code = err.code;
     return typeof code === 'string' && code.startsWith('CSRF_');
@@ -34,7 +19,7 @@ const categorizeError = (err) => {
         return {
             statusCode: err.statusCode,
             code: err.code,
-            message: sanitizeMessage(err),
+            message: err.message,
             logLevel: err.statusCode >= 500 ? 'error' : 'warn',
         };
     }
@@ -43,12 +28,12 @@ const categorizeError = (err) => {
         return { statusCode: 403, code, message: err.message, logLevel: 'warn' };
     }
     if (err.message?.includes('ECONNREFUSED') || err.message?.includes('connection terminated')) {
-        return { statusCode: 503, code: 'SERVICE_UNAVAILABLE', message: sanitizeMessage(err), logLevel: 'error' };
+        return { statusCode: 503, code: 'SERVICE_UNAVAILABLE', message: err.message, logLevel: 'error' };
     }
     if (err.message?.includes('timeout') || err.message?.includes('ETIMEDOUT')) {
-        return { statusCode: 504, code: 'GATEWAY_TIMEOUT', message: sanitizeMessage(err), logLevel: 'error' };
+        return { statusCode: 504, code: 'GATEWAY_TIMEOUT', message: err.message, logLevel: 'error' };
     }
-    return { statusCode: 500, code: 'INTERNAL_ERROR', message: sanitizeMessage(err), logLevel: 'error' };
+    return { statusCode: 500, code: 'INTERNAL_ERROR', message: err.message, logLevel: 'error' };
 };
 const sendResponse = (req, res, { statusCode, code, message }) => {
     if (wantsJson(req)) {
@@ -72,7 +57,7 @@ const logError = (err, req, level) => {
         log[level]({ event: 'api_error', code: err.code, statusCode: err.statusCode, message: err.message, ...context });
     }
     else {
-        log[level]({ event: 'unexpected_error', name: err.name, message: err.message, stack: isDevelopment() ? err.stack : undefined, ...context });
+        log[level]({ event: 'unexpected_error', name: err.name, message: err.message, stack: err.stack, ...context });
     }
 };
 export const errorHandler = (err, req, res, _next) => {

package/esm/middleware/{mask-error.js → format-error.js}

@@ -1,39 +1,20 @@
 import crypto from 'node:crypto';
-import { classify, parse } from '@constructive-io/errors';
-import { getNodeEnv } from '@pgpmjs/env';
+import { parse } from '@constructive-io/errors';
 import { Logger } from '@pgpmjs/logger';
-const maskErrorLog = new Logger('graphile:maskError');
-/**
- * GraphQL framework protocol codes. These originate in the GraphQL/grafast
- * transport layer (not in constructive-db), so they are not Constructive domain
- * codes in the `@constructive-io/errors` registry. They are always safe to
- * surface — they carry no sensitive detail. Everything else (auth, account,
- * resource, constraint, and every constructive-db code) is classified by the
- * registry, which is the single source of truth for public vs. internal.
- */
-const GRAPHQL_PROTOCOL_CODES = new Set([
-    'GRAPHQL_VALIDATION_FAILED',
-    'GRAPHQL_PARSE_FAILED',
-    'PERSISTED_QUERY_NOT_FOUND',
-    'PERSISTED_QUERY_NOT_SUPPORTED'
-]);
-/** A code is safe to surface when the registry classifies it public, or it is a
- * GraphQL framework protocol code. */
-const isPublicCode = (code) => Boolean(code) && (classify(code) === 'public' || GRAPHQL_PROTOCOL_CODES.has(code));
+const formatErrorLog = new Logger('graphile:formatError');
 /**
  * An error the GraphQL layer raised about the *request*, before any resolver
  * ran: an unknown input field, a value of the wrong type, a missing required
  * variable. graphql-js reports variable coercion without an `extensions.code`
  * (unlike parse/validation, which carry `GRAPHQL_PARSE_FAILED` /
- * `GRAPHQL_VALIDATION_FAILED`), so code-based classification alone reads it as
- * unknown and masks it — telling a client its own malformed query was a server
- * failure, with a reference id pointing at nothing.
+ * `GRAPHQL_VALIDATION_FAILED`), so code-based classification alone would read
+ * it as a server failure instead of the client's own malformed query.
  *
  * A request error is answered before a field is resolved, so it carries no
  * response `path` — every execution error has one. Coercion wraps the inner
  * complaint about the value, so `originalError` may be set, but only ever to
  * another GraphQL-layer error: anything a resolver or the database threw arrives
- * as a foreign error (a pg error, an `Error`) and is masked as before. The wrap
+ * as a foreign error (a pg error, an `Error`). The wrap
  * is recognized by name rather than by `instanceof`, because the error is raised
  * by whichever copy of graphql-js grafast resolved, not by this package's.
  */
@@ -63,8 +44,10 @@ const withoutInputValues = (error) => {
         .replace(/^Value "[\s\S]*" does not exist in/, 'Value does not exist in');
     return `${variable} got invalid value${at}; ${complaint}`;
 };
-/** The code a surfaced request error carries when graphql-js supplied none. */
+/** The code a request error carries when graphql-js supplied none. */
 const BAD_USER_INPUT = 'BAD_USER_INPUT';
+/** The code any other error carries when nothing supplied one. */
+const INTERNAL_SERVER_ERROR = 'INTERNAL_SERVER_ERROR';
 /**
  * Normalize any GraphQL/database error into a canonical Constructive shape.
  *
@@ -80,21 +63,21 @@ export const normalizeError = (error) => {
     return { code: parsed.code, context: parsed.context, class: parsed.class };
 };
 /**
- * Production-aware error handling backed by `@constructive-io/errors`.
+ * Format every GraphQL error the same way, in every environment. Nothing is
+ * masked: the client always receives the real message.
  *
- * 1. Enrich `extensions.code`/`class`/`context` from the parsed error so clients
- *    always receive a machine-readable code (fixing the gap where database
- *    errors reached clients as a bare message with empty `extensions`).
- * 2. Surface public (registered/allowlisted) errors as-is.
- * 3. In development, pass everything through (enriched) for debugging.
- * 4. In production, mask internal/unknown errors behind a reference ID and log
- *    the original.
+ * 1. Lift the structured code onto `extensions.code`/`class`/`context` from the
+ *    parsed error, so database errors reach clients with a machine-readable
+ *    code instead of a bare message with empty `extensions`.
+ * 2. A request error graphql-js raised without a code is `BAD_USER_INPUT`.
+ * 3. Any other error without a code is `INTERNAL_SERVER_ERROR`.
+ * 4. Every internal error (unknown, or registered as internal) carries an
+ *    `errorId` and is logged under it, so a report can be matched to the log.
  */
-export const maskError = (error) => {
+export const formatError = (error) => {
     const { code, context, class: errorClass } = normalizeError(error);
-    // Lift the structured code onto extensions for every recognized error so
-    // clients always receive a machine-readable code (`extensions` is read-only
-    // on GraphQLError, so we build a formatted error rather than mutating it).
+    // `extensions` is read-only on GraphQLError, so build a formatted error
+    // rather than mutating it.
     const extensions = { ...error.extensions };
     if (code) {
         extensions.code = code;
@@ -103,33 +86,25 @@ export const maskError = (error) => {
             extensions.context = context;
         }
     }
-    const effectiveCode = code ?? error.extensions?.code;
-    if (!effectiveCode && isRequestError(error)) {
-        extensions.code = BAD_USER_INPUT;
-        return {
-            message: withoutInputValues(error),
-            ...(error.locations ? { locations: error.locations } : {}),
-            extensions,
-        };
+    let internal = Boolean(code) && errorClass === 'internal';
+    let message = error.message;
+    if (!code && !error.extensions?.code) {
+        const requestError = isRequestError(error);
+        if (requestError)
+            message = withoutInputValues(error);
+        extensions.code = requestError ? BAD_USER_INPUT : INTERNAL_SERVER_ERROR;
+        internal = !requestError;
     }
-    if (isPublicCode(effectiveCode) || getNodeEnv() === 'development') {
-        // Note: grafserv strips originalError and internal extensions before
-        // serializing to the client, so returning the enriched error is safe.
-        return {
-            message: error.message,
-            ...(error.locations ? { locations: error.locations } : {}),
-            ...(error.path ? { path: error.path } : {}),
-            extensions,
-        };
+    if (internal) {
+        const errorId = crypto.randomBytes(8).toString('hex');
+        extensions.errorId = errorId;
+        formatErrorLog.error(`[graphql-error:${errorId}]`, error);
     }
-    // Mask internal/unknown errors with a reference ID.
-    const errorId = crypto.randomBytes(8).toString('hex');
-    maskErrorLog.error(`[masked-error:${errorId}]`, error);
+    // grafserv strips originalError before serializing to the client.
     return {
-        message: `An unexpected error occurred. Reference: ${errorId}`,
-        extensions: {
-            code: 'INTERNAL_SERVER_ERROR',
-            errorId
-        }
+        message,
+        ...(error.locations ? { locations: error.locations } : {}),
+        ...(error.path ? { path: error.path } : {}),
+        extensions
     };
 };

package/esm/middleware/graphile.js

@@ -1,7 +1,6 @@
 import './types'; // for Request type
 import { errors } from '@constructive-io/errors';
 import { DEFAULT_REQUEST_PROTECTION, protectionPgSettings } from '@constructive-io/express-context';
-import { getNodeEnv } from '@pgpmjs/env';
 import { Logger } from '@pgpmjs/logger';
 import { createGraphileInstance, graphileCache } from 'graphile-cache';
 import { createFunctionBindingsPlugin } from 'graphile-function-bindings';
@@ -14,10 +13,10 @@ import { respondWithGraphQLError } from '../errors/graphql-response';
 import { AuthCookiePlugin } from '../plugins/auth-cookie-plugin';
 import { createErrorEventsPlugin } from '../plugins/error-events-plugin';
 import { RequestProtectionPlugin } from '../plugins/request-protection-plugin';
+import { WebauthnPlugin } from '../plugins/webauthn-plugin';
+import { formatError } from './format-error';
 import { makeIntrospectionWiring } from './graphile-introspection';
-import { maskError } from './mask-error';
 import { observeGraphileBuild } from './observability/graphile-build-stats';
-const isDev = () => getNodeEnv() === 'development';
 // =============================================================================
 // Single-Flight Pattern: In-Flight Tracking
 // =============================================================================
@@ -57,7 +56,7 @@ const reqLabel = (req) => (req.requestId ? `[${req.requestId}]` : '[req]');
  * plugin preset.  Without settings the default preset is used
  * (everything on except aggregates).
  */
-const buildPreset = async (pool, schemas, anonRole, roleName, introspectionRole, graphileOptions, databaseSettings, apiId, compute) => {
+const buildPreset = async (pool, schemas, anonRole, roleName, introspectionRole, graphileOptions, databaseSettings, apiId, compute, webauthn) => {
     const introspection = await makeIntrospectionWiring(pool, schemas, graphileOptions, undefined, introspectionRole);
     const configuredPreset = graphileOptions?.preset ?? {};
     const grafastCachePreset = createGrafastCacheLimitsPreset(graphileOptions?.grafastCache);
@@ -77,6 +76,9 @@ const buildPreset = async (pool, schemas, anonRole, roleName, introspectionRole,
             AuthCookiePlugin,
             RequestProtectionPlugin,
             createErrorEventsPlugin(pool),
+            // Only when the tenant provisioned the WebAuthn module; the policy
+            // itself is read per request from `req.api.webauthnSettings`.
+            ...(webauthn ? [WebauthnPlugin] : []),
             // Only registered when the compute module is provisioned for this
             // database — all schema/table names come from the constructive
             // metaschema (express-context compute module loader); the plugin has
@@ -103,10 +105,10 @@ const buildPreset = async (pool, schemas, anonRole, roleName, introspectionRole,
             graphiqlPath: '/graphiql',
             graphiql: true,
             graphiqlOnGraphQLGET: false,
-            maskError
+            maskError: formatError
         },
         grafast: {
-            explain: process.env.NODE_ENV === 'development',
+            explain: graphileOptions?.explain === true,
             context: (requestContext) => {
                 // In grafserv/express/v4, the request is available at requestContext.expressv4.req
                 const req = requestContext?.expressv4?.req;
@@ -309,7 +311,7 @@ export const graphile = (opts) => {
             // concurrent requests coalesce while optional plugin modules load.
             const creationPromise = (async () => {
                 const compute = api.apiId ? await req.constructive?.useModule('compute') : undefined;
-                const preset = await buildPreset(pool, schema || [], anonRole, roleName, opts.api?.introspectionRole, opts.graphile, api.databaseSettings, api.apiId, compute);
+                const preset = await buildPreset(pool, schema || [], anonRole, roleName, opts.api?.introspectionRole, opts.graphile, api.databaseSettings, api.apiId, compute, Boolean(api.webauthnSettings));
                 return observeGraphileBuild({
                     cacheKey: key,
                     serviceKey: key,
@@ -343,7 +345,7 @@ export const graphile = (opts) => {
             log.error(`${label} PostGraphile middleware error`, e);
             if (!res.headersSent) {
                 respondWithGraphQLError(res, errors.INTERNAL_FAILURE({
-                    details: isDev() ? e?.message ?? String(e) : 'An unexpected error occurred'
+                    details: e?.message ?? String(e)
                 }));
                 return;
             }

package/esm/plugins/auth-cookie-plugin.js

@@ -67,6 +67,7 @@ const SIGN_IN_MUTATIONS = new Set([
     'completeMfaChallenge',
     'signInOneTimeToken',
     'signInCrossOrigin',
+    'webauthnSignInFinish',
 ]);
 /**
  * Auth mutations that should clear the session cookie.

package/esm/plugins/error-events-plugin.js

@@ -3,13 +3,13 @@ import { Logger } from '@pgpmjs/logger';
 import { getOperationAST } from 'graphql';
 import { escapeIdentifier } from 'pg';
 import { withPgClient } from 'pg-query-context';
-import { normalizeError } from '../middleware/mask-error';
+import { normalizeError } from '../middleware/format-error';
 const log = new Logger('error-events');
 const getExpressRequest = (requestContext) => requestContext?.expressv4?.req;
 /**
  * The first structured, public-classified registry code among the errors.
- * Internal/unknown errors are bugs, not refusals: they are masked and logged
- * by `maskError` and never recorded as tenant events.
+ * Internal/unknown errors are bugs, not refusals: they are logged by
+ * `formatError` and never recorded as tenant events.
  */
 const refusalCode = (errors) => {
     for (const error of errors ?? []) {