@constructive-io/graphql-server 5.28.8 → 5.29.0

package/esm/plugins/webauthn-plugin.js

@@ -0,0 +1,392 @@
+import '../middleware/types';
+import { QuoteUtils } from '@pgsql/quotes';
+import { generateAuthenticationOptions, generateRegistrationOptions, verifyAuthenticationResponse, verifyRegistrationResponse } from '@simplewebauthn/server';
+import { isoBase64URL } from '@simplewebauthn/server/helpers';
+import { context as grafastContext, lambda, object } from 'grafast';
+import { SYSTEM_LANE_ROLE } from 'graphile-plugin-utils';
+import { extendSchema, gql } from 'graphile-utils';
+const CONTEXT_KEY = 'constructiveWebauthn';
+const REGISTER_CHALLENGE = 'webauthn_register_challenge';
+const SIGN_IN_CHALLENGE = 'webauthn_sign_in_challenge';
+const MAX_NAME_LENGTH = 256;
+const MAX_RESPONSE_BYTES = 64 * 1024;
+const getExpressRequest = (requestContext) => requestContext?.expressv4?.req;
+const fail = (code, message) => {
+    const err = new Error(message);
+    err.extensions = { code };
+    throw err;
+};
+/** Apply the request's settings transaction-locally, optionally overriding its role. */
+const applySettings = async (tx, pgSettings, role) => {
+    const entries = Object.entries(pgSettings ?? {}).filter(([key]) => !role || key !== 'role');
+    if (role)
+        entries.push(['role', role]);
+    if (entries.length === 0)
+        return;
+    await tx.query({
+        text: 'SELECT set_config(el->>0, el->>1, true) FROM json_array_elements($1::json) el',
+        values: [JSON.stringify(entries)]
+    });
+};
+const withRequestLane = (withPgClient, pgSettings, cb) => withPgClient(null, (client) => client.withTransaction(async (tx) => {
+    await applySettings(tx, pgSettings);
+    return cb(tx);
+}));
+const withVerifierLane = (withPgClient, pgSettings, cb) => withPgClient(null, (client) => client.withTransaction(async (tx) => {
+    await applySettings(tx, pgSettings, SYSTEM_LANE_ROLE);
+    return cb(tx);
+}));
+const procedure = (settings, name) => QuoteUtils.quoteQualifiedIdentifier(settings.schema, name);
+const requireSettings = (ctx) => {
+    const settings = ctx?.settings;
+    if (!settings)
+        throw new Error('WebauthnPlugin is loaded but the request resolved no webauthnSettings');
+    return settings;
+};
+const requireUserId = (pgSettings) => {
+    const userId = pgSettings?.['jwt.claims.user_id'];
+    if (!userId)
+        fail('UNAUTHENTICATED', 'Passkey registration requires a signed-in user');
+    return userId;
+};
+const payloadObject = (operation, value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`${operation} returned no payload`);
+    }
+    return value;
+};
+const payloadString = (operation, payload, key) => {
+    const value = payload[key];
+    if (typeof value !== 'string' || !value)
+        throw new Error(`${operation} returned no ${key}`);
+    return value;
+};
+const credentialDescriptors = (operation, value) => {
+    if (value === null || value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error(`${operation} returned invalid credentials`);
+    return value.map((entry) => {
+        const descriptor = payloadObject(operation, entry);
+        const transports = descriptor.transports ?? [];
+        if (!Array.isArray(transports) || !transports.every((t) => typeof t === 'string')) {
+            throw new Error(`${operation} returned invalid credential transports`);
+        }
+        return {
+            id: payloadString(operation, descriptor, 'id'),
+            transports: transports
+        };
+    });
+};
+const requireJsonObject = (value, field) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        fail('BAD_USER_INPUT', `${field} must be a WebAuthn credential JSON object`);
+    }
+    if (JSON.stringify(value).length > MAX_RESPONSE_BYTES) {
+        fail('BAD_USER_INPUT', `${field} is too large`);
+    }
+    return value;
+};
+const challengeMatches = async (tx, settings, challengeName, challenge, challengeId) => {
+    const { rows } = await tx.query({
+        text: `SELECT ${procedure(settings, 'webauthn_challenge_matches')}($1, $2, $3::uuid) AS matches`,
+        values: [challengeName, challenge, challengeId]
+    });
+    return rows[0]?.matches === true;
+};
+/**
+ * SimpleWebAuthn reports a response that fails verification by throwing; give
+ * that a public code. A database error from the challenge lookup inside it
+ * keeps its own.
+ */
+const verifying = async (verify) => {
+    try {
+        return await verify();
+    }
+    catch (err) {
+        if (typeof err?.code === 'string' && err.severity)
+            throw err;
+        return fail('WEBAUTHN_VERIFICATION_FAILED', err?.message ?? String(err));
+    }
+};
+const userVerification = (settings) => settings.requireUserVerification ? 'required' : 'preferred';
+const lookupCurrentUser = async (tx, req) => {
+    const surface = await req?.constructive?.useModule('authSurface');
+    if (!surface)
+        return { username: null, displayName: null };
+    const { rows } = await tx.query({
+        text: `SELECT username, display_name FROM ${QuoteUtils.quoteQualifiedIdentifier(surface.publicSchema, 'current_user')}()`
+    });
+    const row = rows[0];
+    return {
+        username: typeof row?.username === 'string' ? row.username : null,
+        displayName: typeof row?.display_name === 'string' ? row.display_name : null
+    };
+};
+const resolveArgs = (fieldArgs) => object({
+    input: fieldArgs.getRaw('input'),
+    withPgClient: grafastContext().get('withPgClient'),
+    pgSettings: grafastContext().get('pgSettings'),
+    webauthn: grafastContext().get(CONTEXT_KEY)
+});
+export const WebauthnPlugin = {
+    ...extendSchema(() => ({
+        typeDefs: gql `
+      input WebauthnRegisterBeginInput {
+        clientMutationId: String
+      }
+
+      type WebauthnRegisterBeginPayload {
+        """PublicKeyCredentialCreationOptionsJSON for navigator.credentials.create()."""
+        options: JSON!
+        """The user handle to echo back to webauthnRegisterFinish."""
+        webauthnUserId: String!
+      }
+
+      input WebauthnRegisterFinishInput {
+        """The browser's RegistrationResponseJSON."""
+        response: JSON!
+        webauthnUserId: String!
+        """A label for the passkey."""
+        name: String
+      }
+
+      type WebauthnRegisterFinishPayload {
+        credentialId: String!
+      }
+
+      input WebauthnSignInBeginInput {
+        clientMutationId: String
+      }
+
+      type WebauthnSignInBeginPayload {
+        """PublicKeyCredentialRequestOptionsJSON for navigator.credentials.get()."""
+        options: JSON!
+        """Names the pending challenge; echo it back to webauthnSignInFinish."""
+        challengeId: UUID!
+      }
+
+      input WebauthnSignInFinishInput {
+        """The browser's AuthenticationResponseJSON."""
+        response: JSON!
+        challengeId: UUID!
+      }
+
+      type WebauthnSignInFinishPayload {
+        accessToken: String!
+        accessTokenExpiresAt: Datetime!
+        userId: UUID!
+      }
+
+      extend type Mutation {
+        """Begin registering a passkey for the signed-in user."""
+        webauthnRegisterBegin(input: WebauthnRegisterBeginInput): WebauthnRegisterBeginPayload
+        """Verify the browser's registration response and store the passkey."""
+        webauthnRegisterFinish(input: WebauthnRegisterFinishInput!): WebauthnRegisterFinishPayload
+        """Begin a passkey sign-in (discoverable when signed out)."""
+        webauthnSignInBegin(input: WebauthnSignInBeginInput): WebauthnSignInBeginPayload
+        """Verify the browser's assertion and mint a session."""
+        webauthnSignInFinish(input: WebauthnSignInFinishInput!): WebauthnSignInFinishPayload
+      }
+    `,
+        plans: {
+            Mutation: {
+                webauthnRegisterBegin(_$mutation, fieldArgs) {
+                    return lambda(resolveArgs(fieldArgs), async ({ withPgClient, pgSettings, webauthn }) => {
+                        const settings = requireSettings(webauthn);
+                        const userId = requireUserId(pgSettings);
+                        const { registration, user } = await withRequestLane(withPgClient, pgSettings, async (tx) => {
+                            const { rows } = await tx.query({
+                                text: `SELECT ${procedure(settings, 'webauthn_begin_registration')}($1::uuid) AS result`,
+                                values: [userId]
+                            });
+                            const payload = payloadObject('webauthn_begin_registration', rows[0]?.result);
+                            return {
+                                registration: {
+                                    challenge: payloadString('webauthn_begin_registration', payload, 'challenge'),
+                                    webauthnUserId: payloadString('webauthn_begin_registration', payload, 'webauthn_user_id'),
+                                    excludeCredentials: credentialDescriptors('webauthn_begin_registration', payload.excludeCredentials)
+                                },
+                                user: await lookupCurrentUser(tx, webauthn?.req)
+                            };
+                        });
+                        const authenticatorSelection = {
+                            residentKey: settings.residentKey,
+                            userVerification: userVerification(settings)
+                        };
+                        const options = await generateRegistrationOptions({
+                            // The tenant mints the challenge already base64url-encoded; a
+                            // string challenge would be re-encoded as UTF-8 and the browser
+                            // would echo a value the tenant never stored.
+                            challenge: isoBase64URL.toBuffer(registration.challenge),
+                            rpID: settings.rpId,
+                            rpName: settings.rpName,
+                            attestationType: settings.attestationType,
+                            authenticatorSelection,
+                            excludeCredentials: registration.excludeCredentials,
+                            timeout: settings.challengeExpirySeconds * 1000,
+                            userID: new TextEncoder().encode(registration.webauthnUserId),
+                            userName: user.username ?? userId,
+                            userDisplayName: user.displayName ?? user.username ?? userId
+                        });
+                        return { options, webauthnUserId: registration.webauthnUserId };
+                    });
+                },
+                webauthnRegisterFinish(_$mutation, fieldArgs) {
+                    return lambda(resolveArgs(fieldArgs), async ({ input, withPgClient, pgSettings, webauthn }) => {
+                        const settings = requireSettings(webauthn);
+                        const userId = requireUserId(pgSettings);
+                        const response = requireJsonObject(input?.response, 'response');
+                        const webauthnUserId = input?.webauthnUserId;
+                        const name = input?.name ?? null;
+                        if (name !== null && name.length > MAX_NAME_LENGTH) {
+                            fail('BAD_USER_INPUT', `name must be at most ${MAX_NAME_LENGTH} characters`);
+                        }
+                        const verified = await withVerifierLane(withPgClient, pgSettings, (tx) => verifying(() => verifyRegistrationResponse({
+                            response,
+                            expectedChallenge: (challenge) => challengeMatches(tx, settings, REGISTER_CHALLENGE, challenge, null),
+                            expectedOrigin: settings.originAllowlist,
+                            expectedRPID: settings.rpId,
+                            requireUserVerification: settings.requireUserVerification
+                        })));
+                        if (!verified.verified)
+                            fail('WEBAUTHN_VERIFICATION_FAILED', 'WebAuthn registration verification failed');
+                        const { credential, credentialDeviceType, credentialBackedUp } = verified.registrationInfo;
+                        const credentialId = await withVerifierLane(withPgClient, pgSettings, async (tx) => {
+                            const { rows } = await tx.query({
+                                text: `SELECT ${procedure(settings, 'webauthn_finish_registration')}(
+                  $1, $2, $3, $4, $5, $6, $7, $8, $9, $10
+                ) AS id`,
+                                values: [
+                                    credential.id,
+                                    Buffer.from(credential.publicKey),
+                                    credential.counter,
+                                    credential.transports ?? [],
+                                    credentialDeviceType,
+                                    // SimpleWebAuthn reports backup eligibility through the
+                                    // device type; backed-up is the separate current-state flag.
+                                    credentialDeviceType === 'multiDevice',
+                                    credentialBackedUp,
+                                    webauthnUserId,
+                                    userId,
+                                    name
+                                ]
+                            });
+                            return payloadString('webauthn_finish_registration', rows[0] ?? {}, 'id');
+                        });
+                        return { credentialId };
+                    });
+                },
+                webauthnSignInBegin(_$mutation, fieldArgs) {
+                    return lambda(resolveArgs(fieldArgs), async ({ withPgClient, pgSettings, webauthn }) => {
+                        const settings = requireSettings(webauthn);
+                        const signIn = await withRequestLane(withPgClient, pgSettings, async (tx) => {
+                            const { rows } = await tx.query({
+                                text: `SELECT ${procedure(settings, 'webauthn_begin_sign_in')}($1::uuid) AS result`,
+                                values: [pgSettings?.['jwt.claims.user_id'] ?? null]
+                            });
+                            const payload = payloadObject('webauthn_begin_sign_in', rows[0]?.result);
+                            return {
+                                challenge: payloadString('webauthn_begin_sign_in', payload, 'challenge'),
+                                challengeId: payloadString('webauthn_begin_sign_in', payload, 'challengeId'),
+                                allowCredentials: credentialDescriptors('webauthn_begin_sign_in', payload.allowCredentials)
+                            };
+                        });
+                        const options = await generateAuthenticationOptions({
+                            challenge: isoBase64URL.toBuffer(signIn.challenge),
+                            rpID: settings.rpId,
+                            allowCredentials: signIn.allowCredentials,
+                            userVerification: userVerification(settings),
+                            timeout: settings.challengeExpirySeconds * 1000
+                        });
+                        return { options, challengeId: signIn.challengeId };
+                    });
+                },
+                webauthnSignInFinish(_$mutation, fieldArgs) {
+                    return lambda(resolveArgs(fieldArgs), async ({ input, withPgClient, pgSettings, webauthn }) => {
+                        const settings = requireSettings(webauthn);
+                        const response = requireJsonObject(input?.response, 'response');
+                        const challengeId = input?.challengeId;
+                        const credentialId = response.id;
+                        if (typeof credentialId !== 'string' || !credentialId) {
+                            fail('BAD_USER_INPUT', 'response.id is required');
+                        }
+                        // One transaction: the challenge read, the counter check and the
+                        // session mint see the same state, and a refusal undoes them all.
+                        const row = await withVerifierLane(withPgClient, pgSettings, async (tx) => {
+                            const { rows: credentialRows } = await tx.query({
+                                text: `SELECT public_key, sign_count, transports
+                  FROM ${procedure(settings, 'webauthn_credential_for_assertion')}($1, $2::uuid)`,
+                                values: [credentialId, challengeId]
+                            });
+                            const stored = credentialRows[0];
+                            if (!stored || !(stored.public_key instanceof Uint8Array)) {
+                                throw new Error('webauthn_credential_for_assertion returned no public key');
+                            }
+                            const publicKey = Uint8Array.from(stored.public_key);
+                            const transports = stored.transports;
+                            if (!Array.isArray(transports) || !transports.every((t) => typeof t === 'string')) {
+                                throw new Error('webauthn_credential_for_assertion returned invalid transports');
+                            }
+                            const signCount = Number(stored.sign_count);
+                            if (!Number.isSafeInteger(signCount) || signCount < 0) {
+                                throw new Error('webauthn_credential_for_assertion returned invalid sign count');
+                            }
+                            const verified = await verifying(() => verifyAuthenticationResponse({
+                                response,
+                                expectedChallenge: (challenge) => challengeMatches(tx, settings, SIGN_IN_CHALLENGE, challenge, challengeId),
+                                expectedOrigin: settings.originAllowlist,
+                                expectedRPID: settings.rpId,
+                                credential: {
+                                    id: credentialId,
+                                    publicKey,
+                                    counter: signCount,
+                                    transports: transports
+                                },
+                                requireUserVerification: settings.requireUserVerification
+                            }));
+                            if (!verified.verified) {
+                                fail('WEBAUTHN_VERIFICATION_FAILED', 'WebAuthn authentication verification failed');
+                            }
+                            const { rows } = await tx.query({
+                                text: `SELECT user_id, access_token, access_token_expires_at
+                  FROM ${procedure(settings, 'webauthn_finish_sign_in')}($1, $2, $3, $4, $5::uuid)`,
+                                values: [
+                                    credentialId,
+                                    verified.authenticationInfo.newCounter,
+                                    verified.authenticationInfo.credentialBackedUp,
+                                    'bearer',
+                                    challengeId
+                                ]
+                            });
+                            return rows[0];
+                        });
+                        if (!row?.access_token || !row.user_id) {
+                            throw new Error('webauthn_finish_sign_in minted no session');
+                        }
+                        return {
+                            accessToken: row.access_token,
+                            accessTokenExpiresAt: row.access_token_expires_at,
+                            userId: row.user_id
+                        };
+                    });
+                }
+            }
+        }
+    })),
+    name: 'WebauthnPlugin',
+    version: '0.0.0',
+    description: 'WebAuthn passkey registration and sign-in mutations, verified in the server.',
+    grafast: {
+        middleware: {
+            prepareArgs(next, event) {
+                const req = getExpressRequest(event.args.requestContext);
+                // Read per request, not baked into the cached schema: a tenant
+                // changing its RP ID or origins takes effect with the next request.
+                const ctx = { settings: req?.api?.webauthnSettings, req };
+                event.args.contextValue[CONTEXT_KEY] = ctx;
+                return next();
+            }
+        }
+    }
+};

package/esm/server.js

@@ -19,7 +19,7 @@ import { createApiMiddleware } from './middleware/api';
 import { createAuthenticateMiddleware } from './middleware/auth';
 // Auth cookie handling is done via AuthCookiePlugin in grafserv
 import { createCaptchaMiddleware } from './middleware/captcha';
-import { parseCookieValue, SESSION_COOKIE_NAME } from './middleware/cookie';
+import { parseCookieValue, rejectInvalidSessionCookieHeader, SESSION_COOKIE_NAME } from './middleware/cookie';
 import { cors } from './middleware/cors';
 import { errorHandler, notFoundHandler } from './middleware/error-handler';
 import { favicon } from './middleware/favicon';
@@ -189,6 +189,9 @@ class Server {
         };
         app.use(csrfSetToken); // Set CSRF token cookie on all requests
         app.use('/graphql', csrfProtect); // Enforce CSRF on GraphQL mutations
+        // The session-cookie opt-out does not bypass CSRF: it only stops sign-in
+        // responses from setting cookies (see AuthCookiePlugin).
+        app.use('/graphql', rejectInvalidSessionCookieHeader);
         // LLM Agent REST API — mounted before graphile so SSE streaming
         // routes are handled without going through PostGraphile
         app.use(createAgenticRouter());

package/middleware/cookie.d.ts

@@ -1,7 +1,14 @@
-import type { Request, Response } from 'express';
+import type { NextFunction, Request, Response } from 'express';
 import type { AuthSettings } from '../types';
 export declare const SESSION_COOKIE_NAME = "constructive_session";
 export declare const DEVICE_TOKEN_COOKIE_NAME = "constructive_device_token";
+/**
+ * Request header a non-browser client (native app, CLI, server) sends to opt
+ * out of auth cookies: sign-in mutations then return the access token in the
+ * response body only and set neither the session nor the device-token cookie.
+ */
+export declare const SESSION_COOKIE_HEADER = "X-Constructive-Session-Cookie";
+export declare const SESSION_COOKIE_OMIT = "omit";
 export interface CookieConfig {
     secure: boolean;
     sameSite: 'strict' | 'lax' | 'none';
@@ -34,6 +41,16 @@ export declare const setDeviceTokenCookie: (res: Response, deviceToken: string,
  * Clear the device token cookie.
  */
 export declare const clearDeviceTokenCookie: (res: Response, config: CookieConfig) => void;
+/**
+ * True when the request opted out of auth cookies via `SESSION_COOKIE_HEADER`.
+ */
+export declare const isSessionCookieOmitted: (req: Request) => boolean;
+/**
+ * Reject a `SESSION_COOKIE_HEADER` with any value but `omit`, before the
+ * request executes, so a misspelt opt-out fails loudly instead of setting the
+ * cookie the client asked not to receive.
+ */
+export declare const rejectInvalidSessionCookieHeader: (req: Request, _res: Response, next: NextFunction) => void;
 /**
  * Parse a cookie value from the raw Cookie header.
  * Avoids pulling in cookie-parser as a dependency.

package/middleware/cookie.js

@@ -1,8 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getSessionTokenFromRequest = exports.getDeviceTokenFromRequest = exports.parseCookieValue = exports.clearDeviceTokenCookie = exports.setDeviceTokenCookie = exports.clearSessionCookie = exports.setSessionCookie = exports.getDeviceTokenCookieConfig = exports.getSessionCookieConfig = exports.DEVICE_TOKEN_COOKIE_NAME = exports.SESSION_COOKIE_NAME = void 0;
+exports.getSessionTokenFromRequest = exports.getDeviceTokenFromRequest = exports.parseCookieValue = exports.rejectInvalidSessionCookieHeader = exports.isSessionCookieOmitted = exports.clearDeviceTokenCookie = exports.setDeviceTokenCookie = exports.clearSessionCookie = exports.setSessionCookie = exports.getDeviceTokenCookieConfig = exports.getSessionCookieConfig = exports.SESSION_COOKIE_OMIT = exports.SESSION_COOKIE_HEADER = exports.DEVICE_TOKEN_COOKIE_NAME = exports.SESSION_COOKIE_NAME = void 0;
+const api_errors_1 = require("../errors/api-errors");
 exports.SESSION_COOKIE_NAME = 'constructive_session';
 exports.DEVICE_TOKEN_COOKIE_NAME = 'constructive_device_token';
+/**
+ * Request header a non-browser client (native app, CLI, server) sends to opt
+ * out of auth cookies: sign-in mutations then return the access token in the
+ * response body only and set neither the session nor the device-token cookie.
+ */
+exports.SESSION_COOKIE_HEADER = 'X-Constructive-Session-Cookie';
+exports.SESSION_COOKIE_OMIT = 'omit';
 const DEVICE_TOKEN_MAX_AGE = 90 * 24 * 60 * 60; // 90 days in seconds
 /**
  * Build cookie config from AuthSettings with optional remember_me override.
@@ -98,6 +106,24 @@ const clearDeviceTokenCookie = (res, config) => {
     });
 };
 exports.clearDeviceTokenCookie = clearDeviceTokenCookie;
+/**
+ * True when the request opted out of auth cookies via `SESSION_COOKIE_HEADER`.
+ */
+const isSessionCookieOmitted = (req) => req.get(exports.SESSION_COOKIE_HEADER) === exports.SESSION_COOKIE_OMIT;
+exports.isSessionCookieOmitted = isSessionCookieOmitted;
+/**
+ * Reject a `SESSION_COOKIE_HEADER` with any value but `omit`, before the
+ * request executes, so a misspelt opt-out fails loudly instead of setting the
+ * cookie the client asked not to receive.
+ */
+const rejectInvalidSessionCookieHeader = (req, _res, next) => {
+    const value = req.get(exports.SESSION_COOKIE_HEADER);
+    if (value !== undefined && value !== exports.SESSION_COOKIE_OMIT) {
+        return next(new api_errors_1.InvalidSessionCookieHeaderError(exports.SESSION_COOKIE_HEADER, value, exports.SESSION_COOKIE_OMIT));
+    }
+    next();
+};
+exports.rejectInvalidSessionCookieHeader = rejectInvalidSessionCookieHeader;
 /**
  * Parse a cookie value from the raw Cookie header.
  * Avoids pulling in cookie-parser as a dependency.

package/middleware/error-handler.js

@@ -5,32 +5,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.notFoundHandler = exports.errorHandler = void 0;
 require("./types");
-const env_1 = require("@pgpmjs/env");
 const logger_1 = require("@pgpmjs/logger");
 const _50x_1 = __importDefault(require("../errors/50x"));
 const _404_message_1 = __importDefault(require("../errors/404-message"));
 const api_errors_1 = require("../errors/api-errors");
 const log = new logger_1.Logger('error-handler');
-const isDevelopment = () => (0, env_1.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 ((0, api_errors_1.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_');
@@ -40,7 +25,7 @@ const categorizeError = (err) => {
         return {
             statusCode: err.statusCode,
             code: err.code,
-            message: sanitizeMessage(err),
+            message: err.message,
             logLevel: err.statusCode >= 500 ? 'error' : 'warn',
         };
     }
@@ -49,12 +34,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)) {
@@ -78,7 +63,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 });
     }
 };
 const errorHandler = (err, req, res, _next) => {

package/middleware/format-error.d.ts

@@ -0,0 +1,28 @@
+import { type ErrorContext } from '@constructive-io/errors';
+import { type GraphQLError, type GraphQLFormattedError } from 'graphql';
+/**
+ * Normalize any GraphQL/database error into a canonical Constructive shape.
+ *
+ * Database errors surface through Grafast without a populated `extensions.code`
+ * (the semantic code lives in the message, and any SQLSTATE/DETAIL lives on the
+ * underlying pg error at `originalError`). We parse `originalError` first so we
+ * can recover the structured code, then fall back to the GraphQL error itself.
+ */
+export declare const normalizeError: (error: GraphQLError) => {
+    code: string | null;
+    context: ErrorContext;
+    class: "public" | "internal";
+};
+/**
+ * Format every GraphQL error the same way, in every environment. Nothing is
+ * masked: the client always receives the real message.
+ *
+ * 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 declare const formatError: (error: GraphQLError) => GraphQLFormattedError;