@molecule/api-server-default-express 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Browser guard — `@molecule/api-server-default-express` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-server-default-express is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `@molecule/api-server-default-express` — drop-in Express server
+ * factory used by the molecule fleet's `api/src/server.ts`.
+ *
+ * `createServerFactory({ setupBonds, runMigrations, getRouter })`
+ * returns a `(port?) => Promise<server>` function that runs
+ * migrations, wires bonds, mounts router + middleware, and starts
+ * an HTTP (or self-signed HTTPS for local dev) listener.
+ *
+ * @example
+ * ```ts
+ * import { createServerFactory } from '@molecule/api-server-default-express'
+ *
+ * // In your app's api/src/server.ts these come from the scaffolded files:
+ * //   import { setupBonds } from './bonds/index.js'
+ * //   import { runMigrations } from './scripts/migrate.js'
+ * const create = createServerFactory({
+ *   setupBonds,
+ *   runMigrations,
+ *   // Router loads lazily AFTER setupBonds() so bond-conditional route
+ *   // maps see fully-registered providers. The module must export
+ *   // `router`. In your app: getRouter: () => import('./App/router.js')
+ *   getRouter: async () => ({ router }),
+ * })
+ *
+ * // Runs migrations → wires bonds → mounts middleware + router at /api →
+ * // listens on PORT (default 4000). The scaffolded server.ts exports
+ * // `create` and invokes it when the file is run directly.
+ * await create()
+ * ```
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './server.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,35 @@
+/**
+ * `@molecule/api-server-default-express` — drop-in Express server
+ * factory used by the molecule fleet's `api/src/server.ts`.
+ *
+ * `createServerFactory({ setupBonds, runMigrations, getRouter })`
+ * returns a `(port?) => Promise<server>` function that runs
+ * migrations, wires bonds, mounts router + middleware, and starts
+ * an HTTP (or self-signed HTTPS for local dev) listener.
+ *
+ * @example
+ * ```ts
+ * import { createServerFactory } from '@molecule/api-server-default-express'
+ *
+ * // In your app's api/src/server.ts these come from the scaffolded files:
+ * //   import { setupBonds } from './bonds/index.js'
+ * //   import { runMigrations } from './scripts/migrate.js'
+ * const create = createServerFactory({
+ *   setupBonds,
+ *   runMigrations,
+ *   // Router loads lazily AFTER setupBonds() so bond-conditional route
+ *   // maps see fully-registered providers. The module must export
+ *   // `router`. In your app: getRouter: () => import('./App/router.js')
+ *   getRouter: async () => ({ router }),
+ * })
+ *
+ * // Runs migrations → wires bonds → mounts middleware + router at /api →
+ * // listens on PORT (default 4000). The scaffolded server.ts exports
+ * // `create` and invokes it when the file is run directly.
+ * await create()
+ * ```
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './server.js';

package/dist/server.d.ts

@@ -0,0 +1,148 @@
+import http from 'node:http';
+import https from 'node:https';
+import express from 'express';
+/** A deliberately-tagged molecule error mapped to a real HTTP status by the API. */
+export interface TaggedError {
+    /** HTTP status to return (e.g. 503 for a missing provider config). */
+    statusCode: number;
+    /** Machine-readable key the app/IDE maps to a friendly message. */
+    errorKey: string;
+    /** Human-readable message. */
+    message: string;
+}
+/**
+ * Classify a thrown value for the API error middleware. Returns a {@link TaggedError}
+ * ONLY for values deliberately tagged by molecule with BOTH a numeric `statusCode`
+ * AND a string `errorKey` — e.g. a provider's config-missing throw (`statusCode: 503`,
+ * `errorKey: 'config.notConfigured'`). These are expected, actionable conditions a
+ * user must resolve (a missing `STRIPE_SECRET_KEY` is theirs to set, not a server bug),
+ * so the middleware surfaces the real status + errorKey instead of an opaque 500 — the
+ * app/IDE can then show "configure X to enable this feature".
+ *
+ * Requiring BOTH fields is deliberate: it keeps arbitrary library errors that merely
+ * carry a `.statusCode` (e.g. an AWS SDK error) from being silently surfaced with a
+ * status molecule never chose. Returns `null` for everything else (→ default 500 path).
+ *
+ * @param error - The thrown value caught by the error middleware.
+ * @returns The classified tagged error, or `null` if it isn't a molecule-tagged error.
+ */
+export declare function classifyTaggedError(error: unknown): TaggedError | null;
+/**
+ * Terminal Express error middleware for the canonical molecule fleet server.
+ *
+ * Resolves a thrown value to exactly one of three sanitized responses and NEVER
+ * delegates to Express's built-in `finalhandler`:
+ *
+ * 1. Bare-string `Unauthorized` / `Unauthorized.` → `401` with the string body
+ *    (so authSelf-style middleware routes to 401 instead of a 500 page).
+ * 2. A deliberately-tagged molecule error ({@link classifyTaggedError}) → its real
+ *    `statusCode` + `{ error, errorKey }` JSON (expected, user-actionable config
+ *    conditions, e.g. a missing `STRIPE_SECRET_KEY` → 503 `config.notConfigured`).
+ * 3. EVERYTHING else (untagged library throws, null derefs, driver errors) → a
+ *    generic `500 { error: 'Internal Server Error' }`, logged server-side AND
+ *    reported to the bonded error tracker (`@molecule/api-error-tracking`'s
+ *    `captureException`, a documented no-op when no tracker is bonded).
+ *
+ * Only case 3 is captured: cases 1–2 (401s, tagged config-missing 503s, and any
+ * other tagged 4xx/5xx) are expected, user-actionable conditions — not defects —
+ * so reporting them would drown real faults in noise.
+ *
+ * Case 3 is the security-critical branch: it is safe-by-construction and does NOT
+ * depend on `NODE_ENV`. Calling `next(error)` here would fall through to Express's
+ * `finalhandler`, which embeds `err.stack` in the HTTP response body whenever
+ * `app.get('env') !== 'production'` (the default when `NODE_ENV` is unset or
+ * `development`), disclosing absolute server paths, module layout, dependency
+ * versions, and query/data fragments. Returning the opaque 500 unconditionally
+ * removes that leak for every flagship app regardless of how it is deployed.
+ *
+ * @param error - The thrown value caught by Express.
+ * @param req - The request (used only as capture context for error tracking).
+ * @param res - The response to write the sanitized error to.
+ * @param _next - The next function (intentionally never called for untagged errors).
+ */
+export declare const errorMiddleware: express.ErrorRequestHandler;
+/** Options for `createServerFactory`. */
+export interface CreateServerOptions {
+    /** App-specific bond wiring (resolves secrets + wires providers). */
+    setupBonds: () => Promise<void>;
+    /** DB migration runner (typically the `createMigrator()`-bound function). */
+    runMigrations: () => Promise<void>;
+    /**
+     * Lazy router import. Loaded AFTER `setupBonds()` so bond-conditional
+     * route maps see fully-registered providers at module-evaluation time.
+     */
+    getRouter: () => Promise<{
+        router: express.Router;
+    }>;
+    /**
+     * Optional hook to mount middleware AFTER cors+cookieParser but
+     * BEFORE the body parser. Use this for routes that need their own
+     * multipart streaming (file uploads via busboy) — the body parser's
+     * `files: 0` config would silently consume the multipart stream.
+     */
+    preBodyParser?: (app: express.Express) => Promise<void> | void;
+    /**
+     * Optional hook called after `setupBonds()` but before the router
+     * import. Use for additional one-shot setup (e.g. entitlements
+     * tier-registry registration that runs after the bonds are wired).
+     */
+    postBondsSetup?: () => Promise<void> | void;
+    /**
+     * Optional hook to mount middleware on `/api` BEFORE the canonical
+     * `app.use('/api', router)` mount. Use for app-specific authed
+     * content handlers (`/api`-prefixed) that need to run before the
+     * resource router.
+     */
+    preApiRouter?: (app: express.Express) => Promise<void> | void;
+}
+/**
+ * Register a hook to run with the HTTP(S) server right before it listens.
+ * Typically called from a bond's setup (e.g. `setupRealtimeSocketio`) during
+ * `setupBonds()`, which runs earlier in `create()` than server construction.
+ *
+ * @param hook - Receives the real `http.Server`/`https.Server`.
+ */
+export declare function registerServerCreatedHook(hook: (server: http.Server | https.Server) => void | Promise<void>): void;
+/**
+ * Global browser-security headers applied to EVERY response (mounted before the
+ * routers in `createServerFactory`, mirroring the molecule.dev platform server).
+ *
+ * Defaults are conservative and framework-agnostic — no app-specific CSP source
+ * lists, just the clickjacking / MIME-sniffing / referrer baseline a JSON API
+ * should always ship:
+ *
+ * - `X-Content-Type-Options: nosniff` — stop MIME-type sniffing.
+ * - `X-Frame-Options: DENY` + `Content-Security-Policy: frame-ancestors 'none'`
+ *   — anti-clickjacking. A generated app that intends to be embedded (iframe)
+ *   can override these in its own middleware.
+ * - `X-XSS-Protection: 0` — disable the legacy, buggy XSS auditor (modern
+ *   correct value; CSP is the real defense).
+ * - `Referrer-Policy: strict-origin-when-cross-origin` — don't leak full URLs
+ *   cross-origin.
+ * - `Strict-Transport-Security` — production only (mirrors the platform server's
+ *   `NODE_ENV` check) so local plain-HTTP dev isn't force-upgraded to HTTPS.
+ *
+ * @param _req - The request (unused).
+ * @param res - The response to set headers on.
+ * @param next - Express next.
+ */
+export declare const securityHeadersMiddleware: express.RequestHandler;
+/**
+ * Returns an Express server-creation function bound to the given
+ * setupBonds / runMigrations / router loaders. The returned `create`
+ * builds the canonical molecule fleet server:
+ *
+ * - Migrations run first, then bonds, then router import.
+ * - Global browser-security headers ({@link securityHeadersMiddleware})
+ *   applied before any router (anti-clickjacking + nosniff + referrer baseline).
+ * - `bodyParser` / `cookieParser` / `cors` middleware applied.
+ * - Router mounted at `/api`.
+ * - `/health` endpoint with `{ status: 'ok', timestamp }`.
+ * - Bare-string `Unauthorized` / `Unauthorized.` errors normalized to 401.
+ * - HTTPS in dev if `process.env.HTTPS` is set, using self-signed
+ *   certs from optional dependency `pem`.
+ * - `process.on('uncaughtException')` + `unhandledRejection` registered
+ *   on first call (idempotent across multiple `create()` invocations).
+ */
+export declare function createServerFactory(opts: CreateServerOptions): (port?: number) => Promise<express.Express | https.Server>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,KAAK,MAAM,YAAY,CAAA;AAG9B,OAAO,OAAO,MAAM,SAAS,CAAA;AAS7B,oFAAoF;AACpF,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAA;IAClB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAA;IAChB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAetE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,eAAe,EAAE,OAAO,CAAC,mBA6CrC,CAAA;AAED,yCAAyC;AACzC,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/B,6EAA6E;IAC7E,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC;;;OAGG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,CAAC,MAAM,CAAA;KAAE,CAAC,CAAA;IACpD;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC9D;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC3C;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAC9D;AAYD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACjE,IAAI,CAEN;AAYD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,yBAAyB,EAAE,OAAO,CAAC,cAU/C,CAAA;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,mBAAmB,GACxB,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAgH5D"}

package/dist/server.js

@@ -0,0 +1,294 @@
+import http from 'node:http';
+import https from 'node:https';
+import process from 'node:process';
+import express from 'express';
+import { captureException } from '@molecule/api-error-tracking';
+import { logger } from '@molecule/api-logger';
+import { bodyParser as bodyParserMiddleware } from '@molecule/api-middleware-body-parser';
+import { cookieParser as cookieParserMiddleware } from '@molecule/api-middleware-cookie-parser';
+import { cors as corsMiddleware } from '@molecule/api-middleware-cors';
+import { buildConfigReport, logConfigReport } from '@molecule/api-secrets';
+/**
+ * Classify a thrown value for the API error middleware. Returns a {@link TaggedError}
+ * ONLY for values deliberately tagged by molecule with BOTH a numeric `statusCode`
+ * AND a string `errorKey` — e.g. a provider's config-missing throw (`statusCode: 503`,
+ * `errorKey: 'config.notConfigured'`). These are expected, actionable conditions a
+ * user must resolve (a missing `STRIPE_SECRET_KEY` is theirs to set, not a server bug),
+ * so the middleware surfaces the real status + errorKey instead of an opaque 500 — the
+ * app/IDE can then show "configure X to enable this feature".
+ *
+ * Requiring BOTH fields is deliberate: it keeps arbitrary library errors that merely
+ * carry a `.statusCode` (e.g. an AWS SDK error) from being silently surfaced with a
+ * status molecule never chose. Returns `null` for everything else (→ default 500 path).
+ *
+ * @param error - The thrown value caught by the error middleware.
+ * @returns The classified tagged error, or `null` if it isn't a molecule-tagged error.
+ */
+export function classifyTaggedError(error) {
+    if (typeof error === 'object' &&
+        error !== null &&
+        typeof error.statusCode === 'number' &&
+        typeof error.errorKey === 'string') {
+        const e = error;
+        return {
+            statusCode: e.statusCode,
+            errorKey: e.errorKey,
+            message: typeof e.message === 'string' ? e.message : 'Error',
+        };
+    }
+    return null;
+}
+/**
+ * Terminal Express error middleware for the canonical molecule fleet server.
+ *
+ * Resolves a thrown value to exactly one of three sanitized responses and NEVER
+ * delegates to Express's built-in `finalhandler`:
+ *
+ * 1. Bare-string `Unauthorized` / `Unauthorized.` → `401` with the string body
+ *    (so authSelf-style middleware routes to 401 instead of a 500 page).
+ * 2. A deliberately-tagged molecule error ({@link classifyTaggedError}) → its real
+ *    `statusCode` + `{ error, errorKey }` JSON (expected, user-actionable config
+ *    conditions, e.g. a missing `STRIPE_SECRET_KEY` → 503 `config.notConfigured`).
+ * 3. EVERYTHING else (untagged library throws, null derefs, driver errors) → a
+ *    generic `500 { error: 'Internal Server Error' }`, logged server-side AND
+ *    reported to the bonded error tracker (`@molecule/api-error-tracking`'s
+ *    `captureException`, a documented no-op when no tracker is bonded).
+ *
+ * Only case 3 is captured: cases 1–2 (401s, tagged config-missing 503s, and any
+ * other tagged 4xx/5xx) are expected, user-actionable conditions — not defects —
+ * so reporting them would drown real faults in noise.
+ *
+ * Case 3 is the security-critical branch: it is safe-by-construction and does NOT
+ * depend on `NODE_ENV`. Calling `next(error)` here would fall through to Express's
+ * `finalhandler`, which embeds `err.stack` in the HTTP response body whenever
+ * `app.get('env') !== 'production'` (the default when `NODE_ENV` is unset or
+ * `development`), disclosing absolute server paths, module layout, dependency
+ * versions, and query/data fragments. Returning the opaque 500 unconditionally
+ * removes that leak for every flagship app regardless of how it is deployed.
+ *
+ * @param error - The thrown value caught by Express.
+ * @param req - The request (used only as capture context for error tracking).
+ * @param res - The response to write the sanitized error to.
+ * @param _next - The next function (intentionally never called for untagged errors).
+ */
+export const errorMiddleware = (error, req, res, _next) => {
+    // Match both the bare `Unauthorized` string and the i18n-resolved
+    // `Unauthorized.` (with trailing period from the resource locale
+    // bond) so authSelf-style middleware reliably routes to 401 instead
+    // of the default Express 500 error page.
+    if (typeof error === 'string' && /^Unauthorized\.?$/.test(error)) {
+        if (!res.headersSent) {
+            res.status(401);
+            res.send(error);
+        }
+        return;
+    }
+    // Deliberately-tagged molecule errors (e.g. a provider config-missing throw:
+    // 503 + 'config.notConfigured') are expected, user-actionable conditions — not
+    // internal bugs. Surface the real status + errorKey so the app/IDE can render a
+    // clean "configure X to enable this feature" instead of an opaque 500.
+    const tagged = classifyTaggedError(error);
+    if (tagged) {
+        // 5xx here means a dependency/config isn't ready, not a server fault — warn,
+        // don't error (an error-level log would falsely read as an app defect).
+        if (tagged.statusCode >= 500) {
+            logger.warn(tagged.message, { errorKey: tagged.errorKey });
+        }
+        if (!res.headersSent) {
+            res.status(tagged.statusCode).json({ error: tagged.message, errorKey: tagged.errorKey });
+        }
+        return;
+    }
+    // Untagged error: a real internal fault. Log the full detail SERVER-SIDE only,
+    // then respond with a generic 500. We deliberately do NOT call `next(error)` —
+    // that would hand control to Express's finalhandler, which leaks `err.stack`
+    // into the response body unless NODE_ENV is exactly 'production'. Safe-by-
+    // construction: no stack, no paths, no NODE_ENV dependency.
+    logger.error(error);
+    // Report the genuine unexpected error to the bonded error tracker. A no-op
+    // when no tracker is bonded, and never throws — safe inside this terminal
+    // handler. The 401/tagged branches above are deliberately NOT captured.
+    // Method/URL only: headers and bodies can carry credentials.
+    captureException(error, {
+        tags: { source: 'express' },
+        request: { method: req.method, url: req.originalUrl },
+    });
+    if (!res.headersSent) {
+        res.status(500).json({ error: 'Internal Server Error' });
+    }
+};
+/**
+ * Generic server-lifecycle hooks invoked with the real HTTP(S) server once it
+ * has been created in `createServerFactory`, before it starts listening. Lets a
+ * bond that must bind to the HTTP server itself — e.g. a Socket.IO realtime
+ * provider sharing the API's port at `/socket.io/` — attach at the right moment,
+ * without the factory hardcoding any specific bond. Drained (run once then
+ * cleared) per `create()` so repeat calls (tests) don't accumulate stale hooks.
+ */
+const serverCreatedHooks = [];
+/**
+ * Register a hook to run with the HTTP(S) server right before it listens.
+ * Typically called from a bond's setup (e.g. `setupRealtimeSocketio`) during
+ * `setupBonds()`, which runs earlier in `create()` than server construction.
+ *
+ * @param hook - Receives the real `http.Server`/`https.Server`.
+ */
+export function registerServerCreatedHook(hook) {
+    serverCreatedHooks.push(hook);
+}
+/**
+ * Run and drain all registered server-created hooks.
+ *
+ * @param server - The HTTP(S) server to hand to each hook.
+ */
+async function runServerCreatedHooks(server) {
+    const hooks = serverCreatedHooks.splice(0);
+    for (const hook of hooks)
+        await hook(server);
+}
+/**
+ * Global browser-security headers applied to EVERY response (mounted before the
+ * routers in `createServerFactory`, mirroring the molecule.dev platform server).
+ *
+ * Defaults are conservative and framework-agnostic — no app-specific CSP source
+ * lists, just the clickjacking / MIME-sniffing / referrer baseline a JSON API
+ * should always ship:
+ *
+ * - `X-Content-Type-Options: nosniff` — stop MIME-type sniffing.
+ * - `X-Frame-Options: DENY` + `Content-Security-Policy: frame-ancestors 'none'`
+ *   — anti-clickjacking. A generated app that intends to be embedded (iframe)
+ *   can override these in its own middleware.
+ * - `X-XSS-Protection: 0` — disable the legacy, buggy XSS auditor (modern
+ *   correct value; CSP is the real defense).
+ * - `Referrer-Policy: strict-origin-when-cross-origin` — don't leak full URLs
+ *   cross-origin.
+ * - `Strict-Transport-Security` — production only (mirrors the platform server's
+ *   `NODE_ENV` check) so local plain-HTTP dev isn't force-upgraded to HTTPS.
+ *
+ * @param _req - The request (unused).
+ * @param res - The response to set headers on.
+ * @param next - Express next.
+ */
+export const securityHeadersMiddleware = (_req, res, next) => {
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('X-Frame-Options', 'DENY');
+    res.setHeader('X-XSS-Protection', '0');
+    res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
+    res.setHeader('Content-Security-Policy', "frame-ancestors 'none'");
+    if (process.env.NODE_ENV === 'production') {
+        res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains; preload');
+    }
+    next();
+};
+let processHandlersRegistered = false;
+/**
+ * Returns an Express server-creation function bound to the given
+ * setupBonds / runMigrations / router loaders. The returned `create`
+ * builds the canonical molecule fleet server:
+ *
+ * - Migrations run first, then bonds, then router import.
+ * - Global browser-security headers ({@link securityHeadersMiddleware})
+ *   applied before any router (anti-clickjacking + nosniff + referrer baseline).
+ * - `bodyParser` / `cookieParser` / `cors` middleware applied.
+ * - Router mounted at `/api`.
+ * - `/health` endpoint with `{ status: 'ok', timestamp }`.
+ * - Bare-string `Unauthorized` / `Unauthorized.` errors normalized to 401.
+ * - HTTPS in dev if `process.env.HTTPS` is set, using self-signed
+ *   certs from optional dependency `pem`.
+ * - `process.on('uncaughtException')` + `unhandledRejection` registered
+ *   on first call (idempotent across multiple `create()` invocations).
+ */
+export function createServerFactory(opts) {
+    return async (port = Number(process.env.PORT) || 4000) => {
+        if (!processHandlersRegistered) {
+            processHandlersRegistered = true;
+            // Genuine unexpected errors — log AND report to the bonded error tracker
+            // (captureException no-ops when no tracker is bonded and never throws).
+            process.on('uncaughtException', (error) => {
+                logger.error(error);
+                captureException(error, { tags: { source: 'uncaughtException' } });
+            });
+            process.on('unhandledRejection', (error) => {
+                logger.error(error);
+                captureException(error, { tags: { source: 'unhandledRejection' } });
+            });
+        }
+        await opts.runMigrations();
+        await opts.setupBonds();
+        if (opts.postBondsSetup)
+            await opts.postBondsSetup();
+        // Import router after bonds are set up — handler maps are built at
+        // module-evaluation time, so bond-conditional handlers need providers
+        // registered first.
+        const { router } = await opts.getRouter();
+        const app = express();
+        app.disable('x-powered-by');
+        // Browser-security headers on every response — mounted before any router so
+        // /api, /health and error responses all carry them (mirrors the platform
+        // server). Anti-clickjacking + nosniff + referrer baseline; HSTS in prod only.
+        app.use(securityHeadersMiddleware);
+        if (opts.preBodyParser) {
+            // Custom-ordering path: mount cors+cookie before custom hooks
+            // (e.g. multipart uploads) which run BEFORE the body parser
+            // would otherwise swallow their streams.
+            app.use(corsMiddleware);
+            app.use(cookieParserMiddleware);
+            await opts.preBodyParser(app);
+            app.use(bodyParserMiddleware);
+        }
+        else {
+            // Canonical ordering — body/cookie/cors stacked in that order.
+            app.use(bodyParserMiddleware);
+            app.use(cookieParserMiddleware);
+            app.use(corsMiddleware);
+        }
+        if (opts.preApiRouter)
+            await opts.preApiRouter(app);
+        app.use('/api', router);
+        app.get('/health', (_req, res) => {
+            res.json({ status: 'ok', timestamp: new Date().toISOString() });
+        });
+        // Terminal sanitizing error handler — safe-by-construction. Untagged errors
+        // get a generic 500 here and never reach Express's stack-leaking finalhandler.
+        app.use(errorMiddleware);
+        let server = app;
+        if (process.env.HTTPS) {
+            // Self-signed cert for local HTTPS dev. `pem` is an optional dep.
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const pem = require('pem');
+            server = await new Promise((resolve, reject) => {
+                pem.createCertificate({ days: 1, selfSigned: true }, (error, keys) => {
+                    if (error)
+                        reject(error);
+                    else
+                        resolve(https.createServer({ key: keys.serviceKey, cert: keys.certificate }, app));
+                });
+            });
+        }
+        // The real HTTP(S) server that lifecycle-coupled bonds (e.g. a Socket.IO
+        // realtime provider) must bind to. In HTTP mode `server` is the Express app,
+        // whose underlying http.Server is otherwise created+discarded by
+        // `app.listen()`; create it explicitly so server-created hooks attach to the
+        // SAME server the API listens on (Socket.IO then serves `/socket.io/` on the
+        // API port). Hooks run before `listen()` so the upgrade handler is ready.
+        const httpServer = process.env.HTTPS
+            ? server
+            : http.createServer(app);
+        await runServerCreatedHooks(httpServer);
+        httpServer.listen(port, () => {
+            logger.info(`Started ${process.env.NODE_ENV} ${process.env.HTTPS ? 'HTTPS' : 'HTTP'} server on port ${port}.`);
+            // Boot-time configuration report: bonds self-register their secret
+            // definitions at import; log which are configured vs missing (each
+            // missing REQUIRED key warns with its description + setup URL) so a
+            // degraded integration is loud and actionable at startup — instead of
+            // surfacing later as a lazy 503 on the first request that needs it.
+            // Fire-and-forget: reporting must never delay or fail the boot.
+            buildConfigReport()
+                .then(logConfigReport)
+                .catch((error) => {
+                logger.debug('boot config report failed', { error });
+            });
+        });
+        return server;
+    };
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@molecule/api-server-default-express",
+  "version": "1.0.0",
+  "description": "Default Express server factory: bonds setup, DB migrations, body/cookie/cors middleware, /api router mount, /health endpoint, 401 normalization, optional HTTPS via self-signed pem certs. Extracts 80-line server.ts shipped by 79 fleet apps.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "server",
+    "default",
+    "express"
+  ],
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10",
+    "@molecule/api-error-tracking": "1.0.0",
+    "@molecule/api-logger": "1.0.0",
+    "@molecule/api-middleware-body-parser": "1.0.0",
+    "@molecule/api-middleware-cookie-parser": "1.0.0",
+    "@molecule/api-middleware-cors": "1.0.0",
+    "express": "5.2.1",
+    "@types/express": "5.0.6"
+  },
+  "peerDependencies": {
+    "@molecule/api-error-tracking": "^1.0.0",
+    "@molecule/api-logger": "^1.0.0",
+    "@molecule/api-middleware-body-parser": "^1.0.0",
+    "@molecule/api-middleware-cookie-parser": "^1.0.0",
+    "@molecule/api-middleware-cors": "^1.0.0",
+    "@molecule/api-secrets": "^1.0.0",
+    "express": "^4.0.0 || ^5.0.0"
+  }
+}