@constructive-io/graphql-server 5.28.9 → 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/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;

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;