@molecule/api-bonds-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/billing.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Default Stripe-backed billing router used by ~117 fleet apps.
+ *
+ * Wraps the bonded Stripe payment provider with the app's plan
+ * catalogue. Each route delegates per-tier validation to the
+ * `getPricingTiers()` function the app supplies. Webhook handling
+ * is delegated to `@molecule/api-resource-user`'s
+ * `handlePaymentNotification` route, which already updates
+ * `users.planKey` / `planExpiresAt` from Stripe events.
+ *
+ * Routes:
+ * - `POST /checkout` — start a subscription (returns Stripe Checkout URL or `updated: true`)
+ * - `POST /cancel`   — cancel at end of current period
+ * - `GET  /status`   — current tier + entitlement snapshot
+ * - `GET  /tiers`    — public pricing data
+ *
+ * @module
+ */
+import { Router } from 'express';
+interface PricingTier {
+    key: string;
+    name?: string;
+    prices: ReadonlyArray<{
+        stripePriceId?: string | null;
+        period?: string;
+        price?: string;
+    }>;
+}
+/**
+ * Factory for the default billing router. The router exposes four
+ * endpoints: `POST /checkout`, `POST /cancel`, `GET /status`, `GET /tiers`.
+ *
+ * @example
+ * ```ts
+ * // api/src/routes/billing.ts
+ * import { createBillingRouter } from '@molecule/api-bonds-default-express'
+ * import { blogPlanKeys, getPricingTiers, type BlogLimits } from '../tiers.js'
+ *
+ * export default createBillingRouter<BlogLimits>({
+ *   getPricingTiers,
+ *   planKeys: blogPlanKeys,
+ * })
+ * ```
+ */
+export declare function createBillingRouter<TLimits>(opts: {
+    /** Returns the app's pricing tiers (with stripePriceId per price). */
+    getPricingTiers: () => ReadonlyArray<PricingTier>;
+    /** App's plan keys object; only `.free` is read here, for the isFree flag in /status. */
+    planKeys: {
+        free: string;
+    } & Record<string, string>;
+}): Router;
+export {};
+//# sourceMappingURL=billing.d.ts.map

package/dist/billing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing.d.ts","sourceRoot":"","sources":["../src/billing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAA+B,MAAM,EAAE,MAAM,SAAS,CAAA;AAc7D,UAAU,WAAW;IACnB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,aAAa,CAAC;QACpB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;QAC7B,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,KAAK,CAAC,EAAE,MAAM,CAAA;KACf,CAAC,CAAA;CACH;AAoED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,IAAI,EAAE;IACjD,sEAAsE;IACtE,eAAe,EAAE,MAAM,aAAa,CAAC,WAAW,CAAC,CAAA;IACjD,yFAAyF;IACzF,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACpD,GAAG,MAAM,CAoIT"}

package/dist/billing.js

@@ -0,0 +1,228 @@
+/**
+ * Default Stripe-backed billing router used by ~117 fleet apps.
+ *
+ * Wraps the bonded Stripe payment provider with the app's plan
+ * catalogue. Each route delegates per-tier validation to the
+ * `getPricingTiers()` function the app supplies. Webhook handling
+ * is delegated to `@molecule/api-resource-user`'s
+ * `handlePaymentNotification` route, which already updates
+ * `users.planKey` / `planExpiresAt` from Stripe events.
+ *
+ * Routes:
+ * - `POST /checkout` — start a subscription (returns Stripe Checkout URL or `updated: true`)
+ * - `POST /cancel`   — cancel at end of current period
+ * - `GET  /status`   — current tier + entitlement snapshot
+ * - `GET  /tiers`    — public pricing data
+ *
+ * @module
+ */
+import { Router } from 'express';
+import { z } from 'zod';
+import { get, getLogger } from '@molecule/api-bond';
+import { getEffectiveTier } from '@molecule/api-entitlements';
+import { t } from '@molecule/api-i18n';
+import { validateBody } from '@molecule/api-middleware-validation';
+import { registerPlans } from '@molecule/api-resource-payment';
+import { getUserId } from './handlers.js';
+const logger = getLogger();
+/**
+ * Derives the app's Stripe plan catalogue from its pricing tiers and
+ * registers it with `@molecule/api-resource-payment`'s plan registry — the
+ * registry `verifyPayment` / `handlePaymentNotification` resolve grants
+ * from. Without this, the registry only holds placeholder product ids and
+ * EVERY successful payment fails plan resolution ("unknown plan"): the user
+ * is charged but never upgraded.
+ *
+ * planKey derivation follows the fleet convention: `planKeys` maps
+ * `${tier.key}Monthly` / `${tier.key}Yearly` (e.g. `proMonthly`) to the
+ * entitlements planKey stored on `users.planKey`. Tiers/prices without a
+ * Stripe price id (the free tier) are skipped; a paid price whose planKeys
+ * entry is missing is skipped WITH a warning, since that plan could never be
+ * granted.
+ *
+ * Idempotent — safe to re-run per request (registration by planKey
+ * overwrites), which also covers price-id env vars that only become
+ * available after startup secret resolution.
+ *
+ * @param getPricingTiers - The app's pricing tiers function.
+ * @param planKeys - The app's planKeys map (see convention above).
+ */
+function registerPlansFromTiers(getPricingTiers, planKeys) {
+    try {
+        const derived = {};
+        for (const tier of getPricingTiers()) {
+            for (const price of tier.prices) {
+                if (!price.stripePriceId)
+                    continue;
+                const period = price.period === 'year' ? 'year' : 'month';
+                const planKeysKey = `${tier.key}${period === 'year' ? 'Yearly' : 'Monthly'}`;
+                const planKey = planKeys[planKeysKey];
+                if (!planKey) {
+                    logger.warn(`billing: no planKeys entry "${planKeysKey}" for tier "${tier.key}" (${period}) — ` +
+                        `its Stripe price ${price.stripePriceId} cannot grant a plan`);
+                    continue;
+                }
+                derived[planKey] = {
+                    planKey,
+                    platformKey: 'stripe',
+                    platformProductId: '',
+                    platformPriceIds: [price.stripePriceId],
+                    alias: period === 'year' ? 'yearly' : 'monthly',
+                    period,
+                    price: price.price ?? '',
+                    autoRenews: true,
+                    title: tier.name ?? tier.key,
+                    titleKey: '',
+                    description: tier.name ?? tier.key,
+                    descriptionKey: '',
+                    capabilities: { premium: true },
+                };
+            }
+        }
+        if (Object.keys(derived).length > 0)
+            registerPlans(derived);
+    }
+    catch (error) {
+        // Registration failing must not take the billing routes down — but a
+        // failure here means paid plans cannot be granted, so say it loudly.
+        logger.error('billing: failed to register plans from pricing tiers', { error });
+    }
+}
+/**
+ * Factory for the default billing router. The router exposes four
+ * endpoints: `POST /checkout`, `POST /cancel`, `GET /status`, `GET /tiers`.
+ *
+ * @example
+ * ```ts
+ * // api/src/routes/billing.ts
+ * import { createBillingRouter } from '@molecule/api-bonds-default-express'
+ * import { blogPlanKeys, getPricingTiers, type BlogLimits } from '../tiers.js'
+ *
+ * export default createBillingRouter<BlogLimits>({
+ *   getPricingTiers,
+ *   planKeys: blogPlanKeys,
+ * })
+ * ```
+ */
+export function createBillingRouter(opts) {
+    const router = Router();
+    // Register the app's plan catalogue so payment verification / webhooks can
+    // resolve grants. Done at construction AND refreshed per checkout (below)
+    // because price-id env vars may only resolve after startup secrets load.
+    registerPlansFromTiers(opts.getPricingTiers, opts.planKeys);
+    const checkoutSchema = z.object({ priceId: z.string().min(1) });
+    /**
+     * Set of valid Stripe price IDs declared in `getPricingTiers()`.
+     * Reads tiers at request-time (not module-init) so the same code
+     * works in test/staging/production where price IDs differ.
+     */
+    const validPriceIds = () => {
+        const set = new Set();
+        for (const tier of opts.getPricingTiers()) {
+            for (const price of tier.prices) {
+                if (price.stripePriceId)
+                    set.add(price.stripePriceId);
+            }
+        }
+        return set;
+    };
+    router.post('/checkout', validateBody(checkoutSchema), async (req, res) => {
+        // Idempotent refresh — guarantees the plan catalogue reflects the same
+        // request-time env the price validation below reads.
+        registerPlansFromTiers(opts.getPricingTiers, opts.planKeys);
+        const userId = getUserId(res);
+        if (!userId) {
+            res.status(401).json({
+                error: t('auth.unauthorized', undefined, {
+                    defaultValue: 'Authentication required.',
+                }),
+            });
+            return;
+        }
+        const { priceId } = req.body;
+        if (!validPriceIds().has(priceId)) {
+            res.status(400).json({
+                error: t('billing.error.unknownPriceId', { priceId }, {
+                    defaultValue: `Unknown priceId "${priceId}".`,
+                }),
+            });
+            return;
+        }
+        const provider = get('payments', 'stripe');
+        if (!provider?.updateSubscription) {
+            res.status(503).json({
+                error: t('billing.error.providerUnavailable', undefined, {
+                    defaultValue: 'Billing provider unavailable. Try again later.',
+                }),
+            });
+            return;
+        }
+        const result = await provider.updateSubscription({ userId, newProductId: priceId });
+        if (result.checkoutUrl) {
+            res.json({ checkoutUrl: result.checkoutUrl });
+            return;
+        }
+        if (result.updated) {
+            res.json({ updated: true, subscription: result.subscription });
+            return;
+        }
+        res.status(502).json({
+            error: t('billing.error.checkoutFailed', undefined, {
+                defaultValue: 'Could not start checkout. Try again later.',
+            }),
+        });
+    });
+    router.post('/cancel', async (_req, res) => {
+        const userId = getUserId(res);
+        if (!userId) {
+            res.status(401).json({
+                error: t('auth.unauthorized', undefined, {
+                    defaultValue: 'Authentication required.',
+                }),
+            });
+            return;
+        }
+        const provider = get('payments', 'stripe');
+        if (!provider?.cancelSubscription) {
+            res.status(503).json({
+                error: t('billing.error.providerUnavailable', undefined, {
+                    defaultValue: 'Billing provider unavailable. Try again later.',
+                }),
+            });
+            return;
+        }
+        const ok = await provider.cancelSubscription({ userId });
+        if (!ok) {
+            res.status(400).json({
+                error: t('billing.error.cancelFailed', undefined, {
+                    defaultValue: 'No active subscription to cancel.',
+                }),
+            });
+            return;
+        }
+        res.json({ canceled: true });
+    });
+    router.get('/status', async (_req, res) => {
+        const userId = getUserId(res);
+        if (!userId) {
+            res.status(401).json({
+                error: t('auth.unauthorized', undefined, {
+                    defaultValue: 'Authentication required.',
+                }),
+            });
+            return;
+        }
+        const tier = await getEffectiveTier(res);
+        res.json({
+            planKey: tier.planKey,
+            category: tier.category,
+            name: tier.name,
+            limits: tier.limits,
+            isFree: tier.planKey === opts.planKeys.free,
+        });
+    });
+    router.get('/tiers', (_req, res) => {
+        res.json({ data: opts.getPricingTiers() });
+    });
+    return router;
+}

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-bonds-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-bonds-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/handlers.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Express handler helpers — extracted from the ~1200 inline duplicates
+ * across the fleet's `api/src/handlers/*.ts` files.
+ *
+ * Replaces three patterns that every fleet handler inlines verbatim:
+ * (1) `getUserId(res)` / `requireUser(res)` reading the JWT session;
+ * (2) `getParamId(req, name)` defending against the express `req.params`
+ * string-or-string[] type union;
+ * (3) `AuthzResult<T>` + `requireOwnership/requireUserOwnership` for
+ * 404-on-IDOR ownership checks against arbitrary tables.
+ *
+ * Also exports `validationError(res, issues)` and `internalError(res, err)`
+ * response helpers that ~21 apps duplicate in their per-app
+ * `api/src/lib/authz.ts`.
+ *
+ * @module
+ */
+import type { Request, RequestHandler, Response } from 'express';
+/**
+ * Read the JWT session userId off `res.locals.session`. Returns null
+ * when there is no session (the auth middleware never ran, or the
+ * request is unauthenticated).
+ */
+export declare function getUserId(res: Response): string | null;
+/**
+ * Like `getUserId` but writes a 401 + returns null when there's no
+ * session. Use at the top of handler bodies to bail early:
+ *
+ * ```ts
+ * const userId = requireUser(res)
+ * if (!userId) return
+ * ```
+ */
+export declare function requireUser(res: Response): string | null;
+/**
+ * Read a route param as a string, defending against the Express
+ * type union `string | string[]` (multi-value when the same param
+ * key appears more than once). Defaults to `'id'`.
+ */
+export declare function getParamId(req: Request, name?: string): string;
+/**
+ * Result of an ownership check. `ok: true` carries the resolved row;
+ * `ok: false` carries the HTTP status the handler should return —
+ * always 404 to avoid leaking row existence to non-owners (the
+ * "no IDOR" rule).
+ */
+export type AuthzResult<T> = {
+    ok: true;
+    row: T;
+} | {
+    ok: false;
+    status: 404;
+};
+/**
+ * Look up a row by id and verify the caller owns it via `owner_id`.
+ * Returns the row on success, 404 when missing OR owned by a different
+ * user (so attackers can't probe row existence).
+ */
+export declare function requireOwnership<T extends {
+    owner_id?: unknown;
+} = Record<string, unknown>>(table: string, id: string, userId: string): Promise<AuthzResult<T>>;
+/**
+ * Variant of `requireOwnership` for tables that scope by `user_id`
+ * instead of `owner_id` (notifications, user-bound preferences, etc.).
+ */
+export declare function requireUserOwnership<T extends {
+    user_id?: unknown;
+} = Record<string, unknown>>(table: string, id: string, userId: string): Promise<AuthzResult<T>>;
+/**
+ * Express middleware that 401s any request lacking `res.locals.session.userId`.
+ * Drop-in for the fleet's 51 inline `requireAuth` copies.
+ *
+ * @example
+ * ```ts
+ * router.use(requireAuth)
+ * router.get('/private', handler)
+ * ```
+ */
+export declare const requireAuth: RequestHandler;
+/**
+ * Standard 400 response for zod / schema validation failures.
+ * Used by ~21 fleet apps' `api/src/lib/authz.ts` files.
+ */
+export declare function validationError(res: Response, issues: unknown): void;
+/**
+ * Standard 500 response that logs the underlying cause before responding
+ * with a generic message. Always pass the original error so silent
+ * catches don't ship to prod under green tests.
+ */
+export declare function internalError(res: Response, error?: unknown): void;
+//# sourceMappingURL=handlers.d.ts.map

package/dist/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../src/handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAgB,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAU9E;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAEtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CASxD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,GAAE,MAAa,GAAG,MAAM,CAGpE;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAA;AAE9E;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/F,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAOzB;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,CAAC,SAAS;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAOpE;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,EAAE,cAYzB,CAAA;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAKpE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CASlE"}

package/dist/handlers.js

@@ -0,0 +1,128 @@
+/**
+ * Express handler helpers — extracted from the ~1200 inline duplicates
+ * across the fleet's `api/src/handlers/*.ts` files.
+ *
+ * Replaces three patterns that every fleet handler inlines verbatim:
+ * (1) `getUserId(res)` / `requireUser(res)` reading the JWT session;
+ * (2) `getParamId(req, name)` defending against the express `req.params`
+ * string-or-string[] type union;
+ * (3) `AuthzResult<T>` + `requireOwnership/requireUserOwnership` for
+ * 404-on-IDOR ownership checks against arbitrary tables.
+ *
+ * Also exports `validationError(res, issues)` and `internalError(res, err)`
+ * response helpers that ~21 apps duplicate in their per-app
+ * `api/src/lib/authz.ts`.
+ *
+ * @module
+ */
+import { findById } from '@molecule/api-database';
+import { t } from '@molecule/api-i18n';
+import { logger } from '@molecule/api-logger';
+/**
+ * Read the JWT session userId off `res.locals.session`. Returns null
+ * when there is no session (the auth middleware never ran, or the
+ * request is unauthenticated).
+ */
+export function getUserId(res) {
+    return res.locals.session?.userId ?? null;
+}
+/**
+ * Like `getUserId` but writes a 401 + returns null when there's no
+ * session. Use at the top of handler bodies to bail early:
+ *
+ * ```ts
+ * const userId = requireUser(res)
+ * if (!userId) return
+ * ```
+ */
+export function requireUser(res) {
+    const id = getUserId(res);
+    if (!id) {
+        res.status(401).json({
+            error: t('auth.unauthorized', {}, { defaultValue: 'Unauthorized' }),
+        });
+        return null;
+    }
+    return id;
+}
+/**
+ * Read a route param as a string, defending against the Express
+ * type union `string | string[]` (multi-value when the same param
+ * key appears more than once). Defaults to `'id'`.
+ */
+export function getParamId(req, name = 'id') {
+    const v = req.params[name];
+    return Array.isArray(v) ? v[0] : v;
+}
+/**
+ * Look up a row by id and verify the caller owns it via `owner_id`.
+ * Returns the row on success, 404 when missing OR owned by a different
+ * user (so attackers can't probe row existence).
+ */
+export async function requireOwnership(table, id, userId) {
+    const row = await findById(table, id);
+    if (!row)
+        return { ok: false, status: 404 };
+    if (String(row.owner_id) !== String(userId)) {
+        return { ok: false, status: 404 };
+    }
+    return { ok: true, row };
+}
+/**
+ * Variant of `requireOwnership` for tables that scope by `user_id`
+ * instead of `owner_id` (notifications, user-bound preferences, etc.).
+ */
+export async function requireUserOwnership(table, id, userId) {
+    const row = await findById(table, id);
+    if (!row)
+        return { ok: false, status: 404 };
+    if (String(row.user_id) !== String(userId)) {
+        return { ok: false, status: 404 };
+    }
+    return { ok: true, row };
+}
+/**
+ * Express middleware that 401s any request lacking `res.locals.session.userId`.
+ * Drop-in for the fleet's 51 inline `requireAuth` copies.
+ *
+ * @example
+ * ```ts
+ * router.use(requireAuth)
+ * router.get('/private', handler)
+ * ```
+ */
+export const requireAuth = (_req, res, next) => {
+    if (!res.locals.session?.userId) {
+        res.status(401).json({
+            error: t('auth.unauthorized', undefined, { defaultValue: 'Unauthorized' }),
+        });
+        return;
+    }
+    next();
+};
+/**
+ * Standard 400 response for zod / schema validation failures.
+ * Used by ~21 fleet apps' `api/src/lib/authz.ts` files.
+ */
+export function validationError(res, issues) {
+    res.status(400).json({
+        error: t('validation.failed', {}, { defaultValue: 'Validation failed' }),
+        issues,
+    });
+}
+/**
+ * Standard 500 response that logs the underlying cause before responding
+ * with a generic message. Always pass the original error so silent
+ * catches don't ship to prod under green tests.
+ */
+export function internalError(res, error) {
+    if (error !== undefined) {
+        logger.error(error);
+    }
+    else {
+        logger.error(new Error('internalError() called without an underlying cause'));
+    }
+    res.status(500).json({
+        error: t('errors.internalServer', {}, { defaultValue: 'Internal server error' }),
+    });
+}