@constructive-io/graphql-server 5.28.8 → 5.29.0

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

@@ -3,43 +3,24 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.maskError = exports.normalizeError = void 0;
+exports.formatError = exports.normalizeError = void 0;
 const node_crypto_1 = __importDefault(require("node:crypto"));
 const errors_1 = require("@constructive-io/errors");
-const env_1 = require("@pgpmjs/env");
 const logger_1 = require("@pgpmjs/logger");
-const maskErrorLog = new logger_1.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) && ((0, errors_1.classify)(code) === 'public' || GRAPHQL_PROTOCOL_CODES.has(code));
+const formatErrorLog = new logger_1.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.
  */
@@ -69,8 +50,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.
  *
@@ -87,21 +70,21 @@ const normalizeError = (error) => {
 };
 exports.normalizeError = normalizeError;
 /**
- * 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.
  */
-const maskError = (error) => {
+const formatError = (error) => {
     const { code, context, class: errorClass } = (0, exports.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;
@@ -110,34 +93,26 @@ 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) || (0, env_1.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 = node_crypto_1.default.randomBytes(8).toString('hex');
+        extensions.errorId = errorId;
+        formatErrorLog.error(`[graphql-error:${errorId}]`, error);
     }
-    // Mask internal/unknown errors with a reference ID.
-    const errorId = node_crypto_1.default.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
     };
 };
-exports.maskError = maskError;
+exports.formatError = formatError;

package/middleware/graphile.js

@@ -7,7 +7,6 @@ exports.clearInFlightMap = clearInFlightMap;
 require("./types"); // for Request type
 const errors_1 = require("@constructive-io/errors");
 const express_context_1 = require("@constructive-io/express-context");
-const env_1 = require("@pgpmjs/env");
 const logger_1 = require("@pgpmjs/logger");
 const graphile_cache_1 = require("graphile-cache");
 const graphile_function_bindings_1 = require("graphile-function-bindings");
@@ -20,10 +19,10 @@ const graphql_response_1 = require("../errors/graphql-response");
 const auth_cookie_plugin_1 = require("../plugins/auth-cookie-plugin");
 const error_events_plugin_1 = require("../plugins/error-events-plugin");
 const request_protection_plugin_1 = require("../plugins/request-protection-plugin");
+const webauthn_plugin_1 = require("../plugins/webauthn-plugin");
+const format_error_1 = require("./format-error");
 const graphile_introspection_1 = require("./graphile-introspection");
-const mask_error_1 = require("./mask-error");
 const graphile_build_stats_1 = require("./observability/graphile-build-stats");
-const isDev = () => (0, env_1.getNodeEnv)() === 'development';
 // =============================================================================
 // Single-Flight Pattern: In-Flight Tracking
 // =============================================================================
@@ -63,7 +62,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 (0, graphile_introspection_1.makeIntrospectionWiring)(pool, schemas, graphileOptions, undefined, introspectionRole);
     const configuredPreset = graphileOptions?.preset ?? {};
     const grafastCachePreset = (0, graphile_settings_1.createGrafastCacheLimitsPreset)(graphileOptions?.grafastCache);
@@ -83,6 +82,9 @@ const buildPreset = async (pool, schemas, anonRole, roleName, introspectionRole,
             auth_cookie_plugin_1.AuthCookiePlugin,
             request_protection_plugin_1.RequestProtectionPlugin,
             (0, error_events_plugin_1.createErrorEventsPlugin)(pool),
+            // Only when the tenant provisioned the WebAuthn module; the policy
+            // itself is read per request from `req.api.webauthnSettings`.
+            ...(webauthn ? [webauthn_plugin_1.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
@@ -109,10 +111,10 @@ const buildPreset = async (pool, schemas, anonRole, roleName, introspectionRole,
             graphiqlPath: '/graphiql',
             graphiql: true,
             graphiqlOnGraphQLGET: false,
-            maskError: mask_error_1.maskError
+            maskError: format_error_1.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;
@@ -315,7 +317,7 @@ 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 (0, graphile_build_stats_1.observeGraphileBuild)({
                     cacheKey: key,
                     serviceKey: key,
@@ -349,7 +351,7 @@ const graphile = (opts) => {
             log.error(`${label} PostGraphile middleware error`, e);
             if (!res.headersSent) {
                 (0, graphql_response_1.respondWithGraphQLError)(res, errors_1.errors.INTERNAL_FAILURE({
-                    details: isDev() ? e?.message ?? String(e) : 'An unexpected error occurred'
+                    details: e?.message ?? String(e)
                 }));
                 return;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-server",
-  "version": "5.28.8",
+  "version": "5.29.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "Constructive GraphQL Server",
   "main": "index.js",
@@ -30,8 +30,7 @@
     "debug:heap:capture": "node scripts/capture-heap-snapshot.mjs",
     "lint": "eslint . --fix",
     "test": "jest --passWithNoTests",
-    "test:watch": "jest --watch",
-    "bucket:create": "ts-node src/scripts/create-bucket.ts"
+    "test:watch": "jest --watch"
   },
   "keywords": [
     "server",
@@ -42,20 +41,22 @@
   ],
   "dependencies": {
     "@agentic-kit/ollama": "2.15.0",
-    "@constructive-io/csrf": "^0.30.0",
-    "@constructive-io/errors": "^0.22.0",
-    "@constructive-io/express-context": "^0.33.5",
-    "@constructive-io/graphql-env": "^3.34.5",
-    "@constructive-io/graphql-types": "^3.33.5",
+    "@constructive-io/csrf": "^0.30.1",
+    "@constructive-io/errors": "^0.24.0",
+    "@constructive-io/express-context": "^0.33.7",
+    "@constructive-io/graphql-env": "^3.35.0",
+    "@constructive-io/graphql-types": "^3.34.0",
     "@constructive-io/llm-env": "^0.15.0",
-    "@constructive-io/query-builder": "^3.16.6",
+    "@constructive-io/query-builder": "^3.16.8",
     "@constructive-io/s3-utils": "^2.34.0",
     "@constructive-io/url-domains": "^2.31.0",
     "@graphile-contrib/pg-many-to-many": "2.0.0-rc.2",
-    "@pgpmjs/env": "^2.46.2",
+    "@pgpmjs/env": "^2.47.0",
     "@pgpmjs/logger": "^2.26.0",
-    "@pgpmjs/server-utils": "^3.29.5",
-    "@pgpmjs/types": "^2.56.2",
+    "@pgpmjs/server-utils": "^3.29.7",
+    "@pgpmjs/types": "^2.57.0",
+    "@pgsql/quotes": "^18.2.4",
+    "@simplewebauthn/server": "13.3.2",
     "cors": "^2.8.6",
     "deepmerge": "^4.3.1",
     "express": "^5.2.1",
@@ -64,17 +65,18 @@
     "grafserv": "1.0.1",
     "graphile-build": "5.1.1",
     "graphile-build-pg": "5.1.3",
-    "graphile-cache": "^4.14.5",
+    "graphile-cache": "^4.14.7",
     "graphile-config": "1.1.0",
-    "graphile-function-bindings": "^1.17.6",
-    "graphile-scoped-introspection": "^0.4.6",
-    "graphile-settings": "^6.24.7",
+    "graphile-function-bindings": "^1.17.8",
+    "graphile-plugin-utils": "^1.13.0",
+    "graphile-scoped-introspection": "^0.4.8",
+    "graphile-settings": "^6.25.0",
     "graphile-utils": "5.0.3",
     "graphql": "16.13.0",
     "graphql-upload": "^13.0.0",
     "lru-cache": "^11.2.7",
     "pg": "^8.21.0",
-    "pg-cache": "^3.29.5",
+    "pg-cache": "^3.29.7",
     "pg-env": "^1.32.0",
     "pg-query-context": "^2.31.0",
     "pg-sql2": "5.0.1",
@@ -91,11 +93,11 @@
     "@types/request-ip": "^0.0.41",
     "@types/supertest": "^7.2.1",
     "cookie-parser": "^1.4.7",
-    "graphile-test": "5.17.6",
+    "graphile-test": "5.17.8",
     "makage": "^0.8.0",
     "nodemon": "^3.1.14",
     "supertest": "^7.2.2",
     "ts-node": "^10.9.2"
   },
-  "gitHead": "31fb086361c3e2f3806d7945abe5074b3ce58f76"
+  "gitHead": "1f3501d518e175803a1a3372cf9249922d82bfe5"
 }

package/plugins/auth-cookie-plugin.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthCookiePlugin = void 0;
 require("../middleware/types");
 const logger_1 = require("@pgpmjs/logger");
+const graphql_1 = require("graphql");
 const cookie_1 = require("../middleware/cookie");
 const log = new logger_1.Logger('auth-cookie');
 /**
@@ -69,6 +70,7 @@ const SIGN_IN_MUTATIONS = new Set([
     'completeMfaChallenge',
     'signInOneTimeToken',
     'signInCrossOrigin',
+    'webauthnSignInFinish',
 ]);
 /**
  * Auth mutations that should clear the session cookie.
@@ -79,26 +81,21 @@ const SIGN_OUT_MUTATIONS = new Set([
     'revokeAllSessions',
 ]);
 /**
- * Extract mutation names from a GraphQL query string.
+ * Top-level field names of the mutation that will execute: the operation
+ * picked by `operationName`, so other operations in the document never count.
  */
-const extractMutationNames = (query) => {
-    const mutations = [];
-    if (!/^\s*mutation\b/i.test(query)) {
-        return mutations;
+const extractMutationNames = (query, operationName) => {
+    let document;
+    try {
+        document = (0, graphql_1.parse)(query);
     }
-    const bodyStart = query.indexOf('{');
-    if (bodyStart === -1)
-        return mutations;
-    const bodyContent = query.slice(bodyStart + 1);
-    const fieldPattern = /(\w+)\s*(?:\(|{)/g;
-    let match;
-    while ((match = fieldPattern.exec(bodyContent)) !== null) {
-        const name = match[1];
-        if (name !== 'mutation' && name !== 'query' && name !== 'fragment') {
-            mutations.push(name);
-        }
+    catch {
+        return [];
     }
-    return mutations;
+    const operation = (0, graphql_1.getOperationAST)(document, operationName);
+    if (operation?.operation !== 'mutation')
+        return [];
+    return operation.selectionSet.selections.flatMap((selection) => selection.kind === graphql_1.Kind.FIELD ? [selection.name.value] : []);
 };
 /**
  * Extract access token from mutation response.
@@ -201,7 +198,7 @@ exports.AuthCookiePlugin = {
                         return result;
                     }
                     // Extract mutation names
-                    const mutationNames = extractMutationNames(body.query);
+                    const mutationNames = extractMutationNames(body.query, body.operationName);
                     if (mutationNames.length === 0) {
                         return result;
                     }
@@ -216,24 +213,25 @@ exports.AuthCookiePlugin = {
                         // Parse response body
                         const payload = bufferResult.buffer.toString('utf8');
                         const graphqlResponse = JSON.parse(payload);
-                        // Skip if there are GraphQL errors
-                        if (graphqlResponse.errors?.length || !graphqlResponse.data) {
-                            return result;
-                        }
-                        const data = graphqlResponse.data;
+                        const succeeded = !graphqlResponse.errors?.length && Boolean(graphqlResponse.data);
+                        const data = graphqlResponse.data ?? {};
                         const authSettings = req.api?.authSettings;
                         const cookiesToSet = [];
-                        // Handle sign-out mutations
-                        if (signOutMutation && data[signOutMutation]) {
-                            log.info('[auth-cookie] Sign-out mutation succeeded, clearing session cookie');
+                        // signOut always clears the cookies, whatever the mutation returned
+                        // and however the request authenticated: a Bearer client that was
+                        // once handed a session cookie must not keep sending it afterwards.
+                        // revokeSession/revokeAllSessions clear them only on success.
+                        if (signOutMutation === 'signOut' || (signOutMutation && succeeded && data[signOutMutation])) {
+                            log.info(`[auth-cookie] ${signOutMutation}: clearing session cookie`);
                             const config = (0, cookie_1.getSessionCookieConfig)(authSettings);
                             cookiesToSet.push(serializeClearCookie(cookie_1.SESSION_COOKIE_NAME, config));
                             // Also clear device token on sign-out
                             const deviceConfig = (0, cookie_1.getDeviceTokenCookieConfig)(authSettings);
                             cookiesToSet.push(serializeClearCookie(cookie_1.DEVICE_TOKEN_COOKIE_NAME, deviceConfig));
                         }
-                        // Handle sign-in mutations
-                        if (signInMutation) {
+                        // Handle sign-in mutations; a client that sent the opt-out header
+                        // reads the token from the response body and gets no cookies.
+                        if (signInMutation && succeeded && !(0, cookie_1.isSessionCookieOmitted)(req)) {
                             const accessToken = extractAccessToken(data, signInMutation);
                             if (accessToken) {
                                 const rememberMe = hasRememberMe(body.variables);

package/plugins/error-events-plugin.js

@@ -6,17 +6,17 @@ const logger_1 = require("@pgpmjs/logger");
 const graphql_1 = require("graphql");
 const pg_1 = require("pg");
 const pg_query_context_1 = require("pg-query-context");
-const mask_error_1 = require("../middleware/mask-error");
+const format_error_1 = require("../middleware/format-error");
 const log = new logger_1.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 ?? []) {
-        const { code, class: errorClass } = (0, mask_error_1.normalizeError)(error);
+        const { code, class: errorClass } = (0, format_error_1.normalizeError)(error);
         if (code && errorClass === 'public')
             return code;
     }

package/plugins/webauthn-plugin.d.ts

@@ -0,0 +1,3 @@
+import '../middleware/types';
+import type { GraphileConfig } from 'graphile-config';
+export declare const WebauthnPlugin: GraphileConfig.Plugin;