@molecule/api-bonds-default-express 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * `@molecule/api-bonds-default-express` — default API bond wirings and
+ * shared route/handler plumbing for Express-based apps.
+ *
+ * Two halves:
+ *
+ * 1. **`setup<Name>()` bond wirings** (40+): one function per default
+ *    provider (`setupConfigEnv`, `setupDatabasePostgresql`,
+ *    `setupJwtJsonwebtoken`, `setupEmailsMailgun`, `setupUploadsS3`,
+ *    `setupRealtimeSocketio`, `setupAiAnthropic`, …) so per-app
+ *    `api/src/bonds/<name>.ts` files are 1-line re-exports and
+ *    `bonds/index.ts` just calls them in order.
+ * 2. **Shared Express plumbing**: `createBillingRouter` (the fleet's
+ *    Stripe billing endpoints), the `mountDefaultUserAuthRoutes` /
+ *    `mountDefaultDeviceRoutes` / other `mountDefault*Routes` helpers,
+ *    handler guards (`requireAuth`, `requireUser`, `requireOwnership`,
+ *    `getUserId`, `validationError`, `internalError`), zod param schemas,
+ *    `trackAuthEvent`, and a `createMigrator` re-export.
+ *
+ * @example
+ * ```typescript
+ * // api/src/bonds/index.ts — wire defaults at startup, then validate:
+ * import { validateBonds } from '@molecule/api-bond'
+ * import {
+ *   setupConfigEnv,
+ *   setupDatabasePostgresql,
+ *   setupEmailsMailgun,
+ *   setupJwtJsonwebtoken,
+ *   setupSecretsEnv,
+ * } from '@molecule/api-bonds-default-express'
+ *
+ * async function setupBonds(): Promise<void> {
+ *   setupConfigEnv()
+ *   setupSecretsEnv()
+ *   setupDatabasePostgresql()
+ *   setupJwtJsonwebtoken()
+ *   setupEmailsMailgun()
+ *   validateBonds()
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // api/src/routes/billing.ts — the fleet-standard billing endpoints
+ * // (POST /checkout, POST /cancel, GET /status, GET /tiers), mounted by
+ * // the app router at /billing (the real file default-exports the router):
+ * import { createBillingRouter } from '@molecule/api-bonds-default-express'
+ *
+ * // Your app owns these (typically in api/src/tiers.ts):
+ * interface AppLimits { seats: number }
+ * const getPricingTiers = () => []       // your tiers, each with a stripePriceId + limits
+ * const appPlanKeys = { free: 'free', pro: 'pro' }
+ *
+ * const billingRouter = createBillingRouter<AppLimits>({
+ *   getPricingTiers,
+ *   planKeys: appPlanKeys,
+ * })
+ * ```
+ *
+ * @module
+ * @remarks
+ * - **Development falls back to zero-credential providers; production never
+ *   does.** When `NODE_ENV !== 'production'` and a provider's required env
+ *   is missing, the setup wires the capture/local sibling instead and logs
+ *   the swap: mailgun→emails-capture (`MAILGUN_API_KEY`/`MAILGUN_DOMAIN`),
+ *   uploads-s3→uploads-filesystem (`AWS_*`), search-meilisearch→
+ *   search-postgres (`MEILISEARCH_URL`), web-push→push-capture
+ *   (`VAPID_*`), geolocation-mapbox→nominatim (`MAPBOX_ACCESS_TOKEN`),
+ *   cache-redis→cache-memory (`REDIS_URL`). In production the credentialed
+ *   provider is wired regardless — missing env surfaces as loud,
+ *   actionable 503s and boot-report entries, never a silent provider swap.
+ *   So "emails don't arrive in dev" usually means they were CAPTURED (read
+ *   them via the activity/capture tooling), not lost.
+ * - **Realtime setups (`setupRealtimeSocketio`, `setupRealtimeWs`,
+ *   `setupRealtimeSse`) all defer-attach.** Each dynamic-imports its
+ *   provider's `createProvider({ deferAttach: true })`, calls
+ *   `setProvider()`, then `registerServerCreatedHook((server) =>
+ *   provider.attachHttpServer?.(server))` from
+ *   `@molecule/api-server-default-express` — so the realtime transport
+ *   shares the API's HTTP server/port once it exists, instead of a
+ *   standalone port a containerized sandbox / proxied deploy may not
+ *   expose. Add new realtime bonds by mirroring this pattern exactly.
+ * - `createBillingRouter` registers the app's Stripe plan catalogue with
+ *   `@molecule/api-resource-payment` at construction AND re-registers per
+ *   checkout (price-id env vars may resolve after startup); webhook
+ *   handling stays with `@molecule/api-resource-user`'s
+ *   `handlePaymentNotification`. A paid price whose `planKeys` entry is
+ *   missing is skipped WITH a warning — that plan could never be granted.
+ * - Only wire the setups whose packages your app actually installed —
+ *   each one imports its provider package (several lazily via dynamic
+ *   import), so calling a setup for an uninstalled bond fails at that
+ *   import.
+ */
+export * from './billing.js';
+export * from './browser-guard.js';
+export * from './handlers.js';
+export * from './middleware.js';
+export * from './migrate.js';
+export * from './resources.js';
+export * from './routes.js';
+export * from './schemas.js';
+export * from './setup.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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4FG;AAEH,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,102 @@
+/**
+ * `@molecule/api-bonds-default-express` — default API bond wirings and
+ * shared route/handler plumbing for Express-based apps.
+ *
+ * Two halves:
+ *
+ * 1. **`setup<Name>()` bond wirings** (40+): one function per default
+ *    provider (`setupConfigEnv`, `setupDatabasePostgresql`,
+ *    `setupJwtJsonwebtoken`, `setupEmailsMailgun`, `setupUploadsS3`,
+ *    `setupRealtimeSocketio`, `setupAiAnthropic`, …) so per-app
+ *    `api/src/bonds/<name>.ts` files are 1-line re-exports and
+ *    `bonds/index.ts` just calls them in order.
+ * 2. **Shared Express plumbing**: `createBillingRouter` (the fleet's
+ *    Stripe billing endpoints), the `mountDefaultUserAuthRoutes` /
+ *    `mountDefaultDeviceRoutes` / other `mountDefault*Routes` helpers,
+ *    handler guards (`requireAuth`, `requireUser`, `requireOwnership`,
+ *    `getUserId`, `validationError`, `internalError`), zod param schemas,
+ *    `trackAuthEvent`, and a `createMigrator` re-export.
+ *
+ * @example
+ * ```typescript
+ * // api/src/bonds/index.ts — wire defaults at startup, then validate:
+ * import { validateBonds } from '@molecule/api-bond'
+ * import {
+ *   setupConfigEnv,
+ *   setupDatabasePostgresql,
+ *   setupEmailsMailgun,
+ *   setupJwtJsonwebtoken,
+ *   setupSecretsEnv,
+ * } from '@molecule/api-bonds-default-express'
+ *
+ * async function setupBonds(): Promise<void> {
+ *   setupConfigEnv()
+ *   setupSecretsEnv()
+ *   setupDatabasePostgresql()
+ *   setupJwtJsonwebtoken()
+ *   setupEmailsMailgun()
+ *   validateBonds()
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // api/src/routes/billing.ts — the fleet-standard billing endpoints
+ * // (POST /checkout, POST /cancel, GET /status, GET /tiers), mounted by
+ * // the app router at /billing (the real file default-exports the router):
+ * import { createBillingRouter } from '@molecule/api-bonds-default-express'
+ *
+ * // Your app owns these (typically in api/src/tiers.ts):
+ * interface AppLimits { seats: number }
+ * const getPricingTiers = () => []       // your tiers, each with a stripePriceId + limits
+ * const appPlanKeys = { free: 'free', pro: 'pro' }
+ *
+ * const billingRouter = createBillingRouter<AppLimits>({
+ *   getPricingTiers,
+ *   planKeys: appPlanKeys,
+ * })
+ * ```
+ *
+ * @module
+ * @remarks
+ * - **Development falls back to zero-credential providers; production never
+ *   does.** When `NODE_ENV !== 'production'` and a provider's required env
+ *   is missing, the setup wires the capture/local sibling instead and logs
+ *   the swap: mailgun→emails-capture (`MAILGUN_API_KEY`/`MAILGUN_DOMAIN`),
+ *   uploads-s3→uploads-filesystem (`AWS_*`), search-meilisearch→
+ *   search-postgres (`MEILISEARCH_URL`), web-push→push-capture
+ *   (`VAPID_*`), geolocation-mapbox→nominatim (`MAPBOX_ACCESS_TOKEN`),
+ *   cache-redis→cache-memory (`REDIS_URL`). In production the credentialed
+ *   provider is wired regardless — missing env surfaces as loud,
+ *   actionable 503s and boot-report entries, never a silent provider swap.
+ *   So "emails don't arrive in dev" usually means they were CAPTURED (read
+ *   them via the activity/capture tooling), not lost.
+ * - **Realtime setups (`setupRealtimeSocketio`, `setupRealtimeWs`,
+ *   `setupRealtimeSse`) all defer-attach.** Each dynamic-imports its
+ *   provider's `createProvider({ deferAttach: true })`, calls
+ *   `setProvider()`, then `registerServerCreatedHook((server) =>
+ *   provider.attachHttpServer?.(server))` from
+ *   `@molecule/api-server-default-express` — so the realtime transport
+ *   shares the API's HTTP server/port once it exists, instead of a
+ *   standalone port a containerized sandbox / proxied deploy may not
+ *   expose. Add new realtime bonds by mirroring this pattern exactly.
+ * - `createBillingRouter` registers the app's Stripe plan catalogue with
+ *   `@molecule/api-resource-payment` at construction AND re-registers per
+ *   checkout (price-id env vars may resolve after startup); webhook
+ *   handling stays with `@molecule/api-resource-user`'s
+ *   `handlePaymentNotification`. A paid price whose `planKeys` entry is
+ *   missing is skipped WITH a warning — that plan could never be granted.
+ * - Only wire the setups whose packages your app actually installed —
+ *   each one imports its provider package (several lazily via dynamic
+ *   import), so calling a setup for an uninstalled bond fails at that
+ *   import.
+ */
+export * from './billing.js';
+export * from './browser-guard.js';
+export * from './handlers.js';
+export * from './middleware.js';
+export * from './migrate.js';
+export * from './resources.js';
+export * from './routes.js';
+export * from './schemas.js';
+export * from './setup.js';

package/dist/middleware.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Default Express middleware helpers used by the molecule fleet's
+ * `api/src/middleware/<name>.ts` files.
+ *
+ * @module
+ */
+import type { RequestHandler } from 'express';
+/**
+ * Emits an analytics event AND a log entry for an auth-related mutation
+ * (signup, login, password reset, plan change, etc.). Logs at info on
+ * success and warn on auth failure (4xx) so security signal is captured.
+ *
+ * Replaces the per-app `api/src/middleware/auth-analytics.ts` shipped
+ * by 10 fleet apps.
+ *
+ * @example
+ * ```ts
+ * import { trackAuthEvent } from '@molecule/api-bonds-default-express'
+ * router.post('/users/log-in', trackAuthEvent('user.login'), User.logIn)
+ * ```
+ */
+export declare function trackAuthEvent(eventName: string): RequestHandler;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAyB,cAAc,EAAY,MAAM,SAAS,CAAA;AAK9E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAqBhE"}

package/dist/middleware.js

@@ -0,0 +1,41 @@
+/**
+ * Default Express middleware helpers used by the molecule fleet's
+ * `api/src/middleware/<name>.ts` files.
+ *
+ * @module
+ */
+import { track } from '@molecule/api-analytics';
+import { logger } from '@molecule/api-logger';
+/**
+ * Emits an analytics event AND a log entry for an auth-related mutation
+ * (signup, login, password reset, plan change, etc.). Logs at info on
+ * success and warn on auth failure (4xx) so security signal is captured.
+ *
+ * Replaces the per-app `api/src/middleware/auth-analytics.ts` shipped
+ * by 10 fleet apps.
+ *
+ * @example
+ * ```ts
+ * import { trackAuthEvent } from '@molecule/api-bonds-default-express'
+ * router.post('/users/log-in', trackAuthEvent('user.login'), User.logIn)
+ * ```
+ */
+export function trackAuthEvent(eventName) {
+    return (req, res, next) => {
+        res.on('finish', () => {
+            const id = typeof req.params.id === 'string' ? req.params.id : req.params.id?.[0];
+            const ok = res.statusCode >= 200 && res.statusCode < 400;
+            if (ok) {
+                void track({
+                    name: eventName,
+                    properties: { method: req.method, userId: id },
+                });
+                logger.info(`[auth] ${eventName} method=${req.method} userId=${id ?? '-'} status=${res.statusCode}`);
+            }
+            else if (res.statusCode >= 400 && res.statusCode < 500) {
+                logger.warn(`[auth] ${eventName} failed method=${req.method} userId=${id ?? '-'} status=${res.statusCode}`);
+            }
+        });
+        next();
+    };
+}

package/dist/migrate.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Postgres migration runner factory — re-exported from the PostgreSQL
+ * bond.
+ *
+ * The `createMigrator` implementation lives in
+ * `@molecule/api-database-postgresql` because it is Postgres-specific
+ * bootstrapping plumbing (`CREATE DATABASE`, the `pg_database` catalog
+ * probe, raw `pg.Client` connections). This bond-setup package must not
+ * import the concrete `pg` driver directly — it reaches Postgres only
+ * through the `@molecule/api-database-postgresql` bond it already
+ * peer-depends on. App `scripts/migrate.ts` files keep importing
+ * `createMigrator` from here unchanged.
+ *
+ * @module
+ */
+export { createMigrator } from '@molecule/api-database-postgresql';
+//# sourceMappingURL=migrate.d.ts.map

package/dist/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAA"}

package/dist/migrate.js

@@ -0,0 +1,16 @@
+/**
+ * Postgres migration runner factory — re-exported from the PostgreSQL
+ * bond.
+ *
+ * The `createMigrator` implementation lives in
+ * `@molecule/api-database-postgresql` because it is Postgres-specific
+ * bootstrapping plumbing (`CREATE DATABASE`, the `pg_database` catalog
+ * probe, raw `pg.Client` connections). This bond-setup package must not
+ * import the concrete `pg` driver directly — it reaches Postgres only
+ * through the `@molecule/api-database-postgresql` bond it already
+ * peer-depends on. App `scripts/migrate.ts` files keep importing
+ * `createMigrator` from here unchanged.
+ *
+ * @module
+ */
+export { createMigrator } from '@molecule/api-database-postgresql';

package/dist/resources.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Pre-wired default request handler maps for the user + device
+ * resources. Apps that don't need to customize their resource
+ * wiring can re-export these directly from
+ * `App/Resource/<Name>/index.ts`, eliminating the byte-identical
+ * `createRequestHandlerMap(createRequestHandler)` calls that every
+ * flagship app shipped.
+ *
+ * @module
+ */
+import { deviceService } from '@molecule/api-resource-device';
+import { authorization } from '@molecule/api-resource-user';
+/** Pre-wired request handler map for `@molecule/api-resource-user`. */
+export declare const userRequestHandlerMap: import("@molecule/api-resource-user").UserRequestHandlerMap;
+/** Pre-wired request handler map for `@molecule/api-resource-device`. */
+export declare const deviceRequestHandlerMap: import("@molecule/api-resource-device").DeviceRequestHandlerMap;
+export { deviceService, authorization as userAuthorization };
+//# sourceMappingURL=resources.d.ts.map

package/dist/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAEL,aAAa,EACd,MAAM,+BAA+B,CAAA;AACtC,OAAO,EACL,aAAa,EAEd,MAAM,6BAA6B,CAAA;AAEpC,uEAAuE;AACvE,eAAO,MAAM,qBAAqB,6DAAoD,CAAA;AAEtF,yEAAyE;AACzE,eAAO,MAAM,uBAAuB,iEAAsD,CAAA;AAE1F,OAAO,EAAE,aAAa,EAAE,aAAa,IAAI,iBAAiB,EAAE,CAAA"}

package/dist/resources.js

@@ -0,0 +1,18 @@
+/**
+ * Pre-wired default request handler maps for the user + device
+ * resources. Apps that don't need to customize their resource
+ * wiring can re-export these directly from
+ * `App/Resource/<Name>/index.ts`, eliminating the byte-identical
+ * `createRequestHandlerMap(createRequestHandler)` calls that every
+ * flagship app shipped.
+ *
+ * @module
+ */
+import { createRequestHandler } from '@molecule/api-resource';
+import { createRequestHandlerMap as createDeviceRequestHandlerMap, deviceService, } from '@molecule/api-resource-device';
+import { authorization, createRequestHandlerMap as createUserRequestHandlerMap, } from '@molecule/api-resource-user';
+/** Pre-wired request handler map for `@molecule/api-resource-user`. */
+export const userRequestHandlerMap = createUserRequestHandlerMap(createRequestHandler);
+/** Pre-wired request handler map for `@molecule/api-resource-device`. */
+export const deviceRequestHandlerMap = createDeviceRequestHandlerMap(createRequestHandler);
+export { deviceService, authorization as userAuthorization };

package/dist/routes.d.ts

@@ -0,0 +1,124 @@
+import type { Router } from 'express';
+import type { DeviceRequestHandlerMap } from '@molecule/api-resource-device';
+import type { UserRequestHandlerMap } from '@molecule/api-resource-user';
+/**
+ * Composable route-mount helpers for the molecule fleet's default
+ * `api/src/App/router.ts`. Apps assemble their router by calling the
+ * mount* functions they need — `mountDefaultDeviceRoutes`,
+ * `mountDefaultUserAuthRoutes`, etc. — instead of writing 80 lines of
+ * `router.METHOD(path, ...handlers)` calls.
+ *
+ * Each helper takes the router + the corresponding resource handler
+ * map (e.g. `mountDefaultDeviceRoutes(router, Device)`). Helpers are
+ * additive and can be combined freely.
+ *
+ * @module
+ */
+type DeviceMap = DeviceRequestHandlerMap;
+type UserMap = UserRequestHandlerMap;
+/**
+ * Mounts the standard device routes:
+ *
+ * - `GET /devices/push/public-key` (public — the VAPID public key browsers
+ *   need for `pushManager.subscribe({ applicationServerKey })`; bond-gated
+ *   404/503 when no push provider is bonded/configured)
+ * - `GET /devices` (auth+query)
+ * - `GET /devices/:id` (authUser+read)
+ * - `PATCH /devices/:id` (authUser+update)
+ * - `DELETE /devices/:id` (authUser+del)
+ */
+export declare function mountDefaultDeviceRoutes(router: Router, device: DeviceMap): void;
+/**
+ * Mounts the public auth endpoints:
+ *
+ * - `POST /users` (create)
+ * - `POST /users/log-in` (rateLimitAuth + logIn)
+ * - `POST /users/forgot-password` (rateLimitAuth + forgotPassword)
+ *
+ * The credential-bearing routes are fronted by `user.rateLimitAuth` — the
+ * default IP+account brute-force throttle from `@molecule/api-resource-user` —
+ * so generated apps are not left with unthrottled password / TOTP-via-login
+ * guessing. The limiter degrades open (logs a warning) when no rate-limit
+ * provider is bonded, so apps that opt out still boot.
+ */
+export declare function mountDefaultUserAuthRoutes(router: Router, user: UserMap): void;
+/**
+ * Optional OAuth routes — BOTH halves of the flow:
+ *
+ * - `GET /users/oauth/:provider` (rateLimitAuth + oauthAuthorize) —
+ *   initiation: sets the CSRF `oauth_state` + PKCE `oauth_verifier` httpOnly
+ *   cookies and 302-redirects to the bonded provider's authorization URL.
+ *   Without this half the state cookie `logInOAuth` validates is never set,
+ *   so every callback fails 403 (this is exactly how the generated-app fleet
+ *   shipped an exchange endpoint with no way to start the dance). The GET
+ *   carries the same `rateLimitAuth` throttle as the POST: it has no body, so
+ *   only the generous per-IP bucket applies — an abuse ceiling on cookie-mint/
+ *   redirect flooding that a legitimate login (one GET + one POST) never
+ *   approaches. A trip is a 429 JSON on a top-level navigation, which is
+ *   acceptable for that ceiling.
+ * - `POST /users/log-in/oauth` (rateLimitAuth + logInOAuth) — callback
+ *   exchange: verifies state + code with the bonded provider and logs the
+ *   user in.
+ *
+ * Only mount when the app wires an oauth bond. Handlers check the bond
+ * registry at request time, so an unbonded provider yields a clean 404.
+ */
+export declare function mountDefaultUserOAuthLoginRoute(router: Router, user: UserMap): void;
+/**
+ * Optional reset-password route: `POST /users/reset-password` (rateLimitAuth +
+ * resetPassword). Only mount when the app uses the pkg's resetPassword handler
+ * rather than a custom local handler.
+ */
+export declare function mountDefaultUserResetPasswordRoute(router: Router, user: UserMap): void;
+/**
+ * Mounts the authed-self user CRUD routes:
+ *
+ * - `GET /users/me` (auth+readSelf) — session restore; MUST precede `/users/:id`
+ * - `GET /users/:id` (authSelf+read)
+ * - `PATCH /users/:id` (authSelf+update)
+ * - `DELETE /users/:id` (authSelf+del)
+ */
+export declare function mountDefaultUserCrudRoutes(router: Router, user: UserMap): void;
+/**
+ * Mounts password + 2FA security routes:
+ *
+ * - `PATCH /users/:id/password` (authSelf+updatePassword)
+ * - `POST /users/:id/verify-two-factor` (authSelf + rateLimitTwoFactor + verifyTwoFactor)
+ *
+ * The 2FA verification route carries a stricter limiter (`user.rateLimitTwoFactor`)
+ * that temp-locks the second factor per account after consecutive misses.
+ */
+export declare function mountDefaultUserSecurityRoutes(router: Router, user: UserMap): void;
+/**
+ * Mounts plan/billing routes:
+ *
+ * - `PATCH /users/:id/plan` (authSelf+updatePlan)
+ * - `POST /users/payment-notification/:provider` (requireWebhookAuthenticity+handlePaymentNotification)
+ *
+ * The notification route is public (providers POST to it), so it is gated by
+ * `requireWebhookAuthenticity`: signature-verifying webhook providers (Stripe)
+ * pass through, while unsigned server-to-server providers (Apple/Google) require
+ * a shared secret — the endpoint is not open by default.
+ */
+export declare function mountDefaultUserBillingRoutes(router: Router, user: UserMap): void;
+/**
+ * Optional payment-verification routes for apps that support
+ * client-driven payment confirmation (Apple/Google receipt verify).
+ *
+ * Both verbs require `authSelf` ([M3-1]): the handler mutates and returns the
+ * `:id` user, so an unauthenticated / cross-user call must not reach it. The
+ * permissive global `verifyMiddleware()` never blocks, so per-route `authSelf`
+ * is the gate. `authSelf` does NOT break the Stripe Checkout `success_url`
+ * callback — that is a top-level browser navigation which carries the
+ * `sameSite:'lax'` session cookie — and in-handler customer/checkout-session
+ * binding remains as defense-in-depth. This mirrors the hardened declarative
+ * route table (`resources/user/src/routes.ts`) and molecule-dev's live router;
+ * the fix had not been propagated to this mounter, which the generated-app
+ * fleet uses.
+ *
+ * - `GET /users/:id/verify-payment/:provider` (authSelf+verifyPayment)
+ * - `POST /users/:id/verify-payment/:provider` (authSelf+verifyPayment)
+ */
+export declare function mountDefaultUserVerifyPaymentRoutes(router: Router, user: UserMap): void;
+export {};
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAErC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAA;AAC5E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAA;AAExE;;;;;;;;;;;;GAYG;AAEH,KAAK,SAAS,GAAG,uBAAuB,CAAA;AAExC,KAAK,OAAO,GAAG,qBAAqB,CAAA;AAEpC;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAWhF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAU9E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAMnF;AAED;;;;GAIG;AACH,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAGtF;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAW9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAWlF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAQjF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mCAAmC,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAIvF"}

package/dist/routes.js

@@ -0,0 +1,166 @@
+/**
+ * Mounts the standard device routes:
+ *
+ * - `GET /devices/push/public-key` (public — the VAPID public key browsers
+ *   need for `pushManager.subscribe({ applicationServerKey })`; bond-gated
+ *   404/503 when no push provider is bonded/configured)
+ * - `GET /devices` (auth+query)
+ * - `GET /devices/:id` (authUser+read)
+ * - `PATCH /devices/:id` (authUser+update)
+ * - `DELETE /devices/:id` (authUser+del)
+ */
+export function mountDefaultDeviceRoutes(router, device) {
+    // Mounted before /devices/:id so the literal "push" segment can never be
+    // captured as an :id. Guarded like user.readSelf/oauthAuthorize so older
+    // handler maps (and test fixtures) without the handler still mount.
+    if (device.pushPublicKey) {
+        router.get('/devices/push/public-key', device.pushPublicKey);
+    }
+    router.get('/devices', device.auth, device.query);
+    router.get('/devices/:id', device.authUser, device.read);
+    router.patch('/devices/:id', device.authUser, device.update);
+    router.delete('/devices/:id', device.authUser, device.del);
+}
+/**
+ * Mounts the public auth endpoints:
+ *
+ * - `POST /users` (create)
+ * - `POST /users/log-in` (rateLimitAuth + logIn)
+ * - `POST /users/forgot-password` (rateLimitAuth + forgotPassword)
+ *
+ * The credential-bearing routes are fronted by `user.rateLimitAuth` — the
+ * default IP+account brute-force throttle from `@molecule/api-resource-user` —
+ * so generated apps are not left with unthrottled password / TOTP-via-login
+ * guessing. The limiter degrades open (logs a warning) when no rate-limit
+ * provider is bonded, so apps that opt out still boot.
+ */
+export function mountDefaultUserAuthRoutes(router, user) {
+    router.post('/users', user.create);
+    router.post('/users/log-in', user.rateLimitAuth, user.logIn);
+    // Logout — cookie-authed device revocation + credential-cookie clearing.
+    // [M1-1] required so logout clears the httpOnly cookie (else the cookie-based
+    // session restore re-logs-in on the next load).
+    if (user.logout) {
+        router.post('/users/logout', user.auth, user.logout);
+    }
+    router.post('/users/forgot-password', user.rateLimitAuth, user.forgotPassword);
+}
+/**
+ * Optional OAuth routes — BOTH halves of the flow:
+ *
+ * - `GET /users/oauth/:provider` (rateLimitAuth + oauthAuthorize) —
+ *   initiation: sets the CSRF `oauth_state` + PKCE `oauth_verifier` httpOnly
+ *   cookies and 302-redirects to the bonded provider's authorization URL.
+ *   Without this half the state cookie `logInOAuth` validates is never set,
+ *   so every callback fails 403 (this is exactly how the generated-app fleet
+ *   shipped an exchange endpoint with no way to start the dance). The GET
+ *   carries the same `rateLimitAuth` throttle as the POST: it has no body, so
+ *   only the generous per-IP bucket applies — an abuse ceiling on cookie-mint/
+ *   redirect flooding that a legitimate login (one GET + one POST) never
+ *   approaches. A trip is a 429 JSON on a top-level navigation, which is
+ *   acceptable for that ceiling.
+ * - `POST /users/log-in/oauth` (rateLimitAuth + logInOAuth) — callback
+ *   exchange: verifies state + code with the bonded provider and logs the
+ *   user in.
+ *
+ * Only mount when the app wires an oauth bond. Handlers check the bond
+ * registry at request time, so an unbonded provider yields a clean 404.
+ */
+export function mountDefaultUserOAuthLoginRoute(router, user) {
+    if (user.oauthAuthorize) {
+        router.get('/users/oauth/:provider', user.rateLimitAuth, user.oauthAuthorize);
+    }
+    if (!user.logInOAuth)
+        return;
+    router.post('/users/log-in/oauth', user.rateLimitAuth, user.logInOAuth);
+}
+/**
+ * Optional reset-password route: `POST /users/reset-password` (rateLimitAuth +
+ * resetPassword). Only mount when the app uses the pkg's resetPassword handler
+ * rather than a custom local handler.
+ */
+export function mountDefaultUserResetPasswordRoute(router, user) {
+    if (!user.resetPassword)
+        return;
+    router.post('/users/reset-password', user.rateLimitAuth, user.resetPassword);
+}
+/**
+ * Mounts the authed-self user CRUD routes:
+ *
+ * - `GET /users/me` (auth+readSelf) — session restore; MUST precede `/users/:id`
+ * - `GET /users/:id` (authSelf+read)
+ * - `PATCH /users/:id` (authSelf+update)
+ * - `DELETE /users/:id` (authSelf+del)
+ */
+export function mountDefaultUserCrudRoutes(router, user) {
+    // Current user — cookie-authed session restore. Registered before `/users/:id`
+    // so Express doesn't capture `me` as an `:id`. [M1-1] the app's auth client
+    // calls this on init to restore the session from the httpOnly cookie after a
+    // full page load (the in-memory bearer token does not survive a reload).
+    if (user.readSelf) {
+        router.get('/users/me', user.auth, user.readSelf);
+    }
+    router.get('/users/:id', user.authSelf, user.read);
+    router.patch('/users/:id', user.authSelf, user.update);
+    router.delete('/users/:id', user.authSelf, user.del);
+}
+/**
+ * Mounts password + 2FA security routes:
+ *
+ * - `PATCH /users/:id/password` (authSelf+updatePassword)
+ * - `POST /users/:id/verify-two-factor` (authSelf + rateLimitTwoFactor + verifyTwoFactor)
+ *
+ * The 2FA verification route carries a stricter limiter (`user.rateLimitTwoFactor`)
+ * that temp-locks the second factor per account after consecutive misses.
+ */
+export function mountDefaultUserSecurityRoutes(router, user) {
+    router.patch('/users/:id/password', user.authSelf, user.updatePassword);
+    // POST alias for clients that use the auth-client `changePassword` flow,
+    // which historically dispatches POST. Same handler; both verbs accepted.
+    router.post('/users/:id/password', user.authSelf, user.updatePassword);
+    router.post('/users/:id/verify-two-factor', user.authSelf, user.rateLimitTwoFactor, user.verifyTwoFactor);
+}
+/**
+ * Mounts plan/billing routes:
+ *
+ * - `PATCH /users/:id/plan` (authSelf+updatePlan)
+ * - `POST /users/payment-notification/:provider` (requireWebhookAuthenticity+handlePaymentNotification)
+ *
+ * The notification route is public (providers POST to it), so it is gated by
+ * `requireWebhookAuthenticity`: signature-verifying webhook providers (Stripe)
+ * pass through, while unsigned server-to-server providers (Apple/Google) require
+ * a shared secret — the endpoint is not open by default.
+ */
+export function mountDefaultUserBillingRoutes(router, user) {
+    router.patch('/users/:id/plan', user.authSelf, user.updatePlan);
+    if (user.handlePaymentNotification) {
+        const notificationHandlers = user.requireWebhookAuthenticity
+            ? [user.requireWebhookAuthenticity, user.handlePaymentNotification]
+            : [user.handlePaymentNotification];
+        router.post('/users/payment-notification/:provider', ...notificationHandlers);
+    }
+}
+/**
+ * Optional payment-verification routes for apps that support
+ * client-driven payment confirmation (Apple/Google receipt verify).
+ *
+ * Both verbs require `authSelf` ([M3-1]): the handler mutates and returns the
+ * `:id` user, so an unauthenticated / cross-user call must not reach it. The
+ * permissive global `verifyMiddleware()` never blocks, so per-route `authSelf`
+ * is the gate. `authSelf` does NOT break the Stripe Checkout `success_url`
+ * callback — that is a top-level browser navigation which carries the
+ * `sameSite:'lax'` session cookie — and in-handler customer/checkout-session
+ * binding remains as defense-in-depth. This mirrors the hardened declarative
+ * route table (`resources/user/src/routes.ts`) and molecule-dev's live router;
+ * the fix had not been propagated to this mounter, which the generated-app
+ * fleet uses.
+ *
+ * - `GET /users/:id/verify-payment/:provider` (authSelf+verifyPayment)
+ * - `POST /users/:id/verify-payment/:provider` (authSelf+verifyPayment)
+ */
+export function mountDefaultUserVerifyPaymentRoutes(router, user) {
+    if (!user.verifyPayment)
+        return;
+    router.get('/users/:id/verify-payment/:provider', user.authSelf, user.verifyPayment);
+    router.post('/users/:id/verify-payment/:provider', user.authSelf, user.verifyPayment);
+}