@molecule/api-resource-user 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/authorization.d.ts

@@ -0,0 +1,107 @@
+/**
+ * JWT session authorization for user resources.
+ *
+ * Provides middleware to verify, set, and refresh JWT tokens.
+ *
+ * @module
+ */
+import './secrets.js';
+import type { MoleculeRequest, MoleculeRequestHandler, MoleculeResponse } from '@molecule/api-resource';
+import type { Session } from './schema.js';
+/**
+ * Resolve the actual cookie name for an auth cookie.
+ *
+ * In production the auth-bearing cookies get the `__Host-` prefix. Browsers
+ * reject any `__Host-`-prefixed cookie that carries a `Domain` attribute (and
+ * require `Secure` + `Path=/`), so a sibling subdomain (e.g. a tenant preview
+ * at `<token>.preview.molecule.dev`) can no longer create a colliding
+ * `.molecule.dev`-scoped duplicate that shadows the platform's real session
+ * cookie — closing the cross-tenant cookie-tossing / session-fixation hole.
+ *
+ * In dev/test the cookies are not `Secure` (plain HTTP origins), so a
+ * `__Host-` cookie would be rejected by the browser; use the plain name there.
+ *
+ * Exported so consumers (e.g. molecule-dev's guest-session / OAuth-state code)
+ * set and read the exact same name the platform expects.
+ *
+ * @param base - The base cookie name (e.g. `'token'`, `'sessionId'`).
+ * @returns The environment-appropriate cookie name.
+ */
+export declare const getAuthCookieName: (base: string) => string;
+/**
+ * Base cookie attributes shared by EVERY auth cookie this resource sets and
+ * clears — the single source of truth so a SET and its matching CLEAR always
+ * agree (a mismatched attribute leaves an undeletable cookie) and every auth
+ * cookie gets identical behaviour.
+ *
+ * - **Cross-site preview** (see {@link isCrossSitePreview}) → `{ secure: true,
+ *   sameSite: 'none', partitioned: true, path: '/' }`. The molecule.dev live
+ *   preview renders the app in a CROSS-SITE iframe; browsers evaluate SameSite
+ *   against the TOP-LEVEL site, so a `Lax`/`Strict` cookie is neither stored nor
+ *   sent on ANY preview request — the httpOnly session cookie vanishes on every
+ *   iframe reload and the user is logged out of their own app. `SameSite=None`
+ *   makes it cross-site-sendable (which REQUIRES `Secure` — permitted over http
+ *   on the potentially-trustworthy `localhost` / `127.0.0.1` origins), and
+ *   `Partitioned` (CHIPS) keeps it working when third-party cookies are blocked
+ *   (Brave/Chrome), which `None` alone does not. Applies whether the platform is
+ *   dev or prod, because the preview app is cross-site either way.
+ * - **Production, top-level** → `{ secure: true, sameSite: 'lax', path: '/' }`.
+ *   The correct, CSRF-hardened default; pairs with the `__Host-` prefix (see
+ *   {@link getAuthCookieName}). NEVER weaken it.
+ * - **Development, top-level** → `{ secure: false, sameSite: 'lax', path: '/' }`.
+ *   The original dev posture (plain http, not `Secure`) — used by the molecule.dev
+ *   IDE and by a developer running their generated app locally. Both are top-level
+ *   documents, so `Lax` is correct and `Secure`/`None`/`Partitioned` would be both
+ *   unnecessary and (as above) actively harmful.
+ *
+ * `httpOnly` and `maxAge` are intentionally omitted: the SET call adds those per
+ * cookie, and the CLEAR call spreads these attributes verbatim so the deletion
+ * targets the exact same (possibly Partitioned) cookie jar.
+ *
+ * @returns The environment-appropriate base cookie options.
+ */
+export declare const getAuthCookieOptions: () => {
+    secure: boolean;
+    sameSite: "lax" | "none";
+    partitioned?: boolean;
+    path: string;
+};
+/**
+ * Evict a single device's positive entry from the device-exists cache so the
+ * next authorization check for that device re-consults the database.
+ *
+ * Call this from any in-process revocation path that deletes a specific device
+ * row (e.g. a logout handler that knows the `deviceId`) so the revocation is
+ * effective immediately on this instance rather than after the cache TTL.
+ *
+ * @param deviceId - The device id whose cached "exists" result should be dropped.
+ */
+export declare const invalidateDeviceExistsCache: (deviceId: string) => void;
+/**
+ * Evict ALL positive entries from the device-exists cache.
+ *
+ * Call this from in-process bulk revocation paths that delete every device for
+ * a user (password change/reset, account deletion, OAuth account-claim) where
+ * the affected device ids are not enumerated — the cache is keyed by deviceId,
+ * not userId, so a full clear is the correct way to guarantee none of the
+ * just-deleted devices keep authenticating on this instance. The normal-path
+ * per-request DB-cost reduction is preserved: the cache simply repopulates on
+ * subsequent requests; only these rare revocation events pay a brief re-check.
+ */
+export declare const invalidateAllDeviceExistsCache: () => void;
+/**
+ * Set authorization headers and cookie for a session.
+ *
+ * @param _req - The request object (unused; reserved for handler signature parity).
+ * @param res - The response object.
+ * @param session - The session.
+ * @returns The signed JWT token string, or null if signing failed.
+ */
+export declare const set: (_req: MoleculeRequest, res: MoleculeResponse, session: Session) => string | null;
+/**
+ * Middleware that verifies the JWT token from the `Authorization` header and sets `res.locals.session`.
+ * Falls back to cookie-based session for browser clients. Auto-refreshes tokens older than `JWT_REFRESH_TIME`.
+ * @returns An Express-compatible middleware function.
+ */
+export declare const verifyMiddleware: () => MoleculeRequestHandler;
+//# sourceMappingURL=authorization.d.ts.map

package/dist/authorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization.d.ts","sourceRoot":"","sources":["../src/authorization.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,cAAc,CAAA;AAMrB,OAAO,KAAK,EACV,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EACjB,MAAM,wBAAwB,CAAA;AAE/B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAwB1C;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,KAAG,MACP,CAAA;AA4B1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,oBAAoB,QAAO;IACtC,MAAM,EAAE,OAAO,CAAA;IACf,QAAQ,EAAE,KAAK,GAAG,MAAM,CAAA;IACxB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,IAAI,EAAE,MAAM,CAAA;CAQb,CAAA;AAiDD;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,GAAI,UAAU,MAAM,KAAG,IAE9D,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8BAA8B,QAAO,IAEjD,CAAA;AAsDD;;;;;;;GAOG;AACH,eAAO,MAAM,GAAG,GACd,MAAM,eAAe,EACrB,KAAK,gBAAgB,EACrB,SAAS,OAAO,KACf,MAAM,GAAG,IA6DX,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,QAAO,sBAsEnC,CAAA"}

package/dist/authorization.js

@@ -0,0 +1,375 @@
+/**
+ * JWT session authorization for user resources.
+ *
+ * Provides middleware to verify, set, and refresh JWT tokens.
+ *
+ * @module
+ */
+// Side-effect import: registers this resource's secret definitions so the
+// runtime registry is populated even when authorization.js is imported directly
+// (not through the package barrel).
+import './secrets.js';
+import { v4 as uuid } from 'uuid';
+import { get, getLogger } from '@molecule/api-bond';
+import { get as getConfig } from '@molecule/api-config';
+import { decode, sign, verify as jwtVerify } from '@molecule/api-jwt';
+const logger = getLogger();
+const getJwtRefreshTime = () => {
+    try {
+        return Number(getConfig('JWT_REFRESH_TIME', '30d')) || 1000 * 60 * 30; // 30 minutes
+    }
+    catch (_error) {
+        // Config read is optional — fall back to the hard-coded default safely.
+        return 1000 * 60 * 30; // 30 minutes default
+    }
+};
+const isProduction = () => {
+    try {
+        return getConfig('NODE_ENV') === 'production';
+    }
+    catch (_error) {
+        // Config read is optional — treat an unreadable env as non-production so
+        // we never accidentally emit `__Host-` cookies on an insecure (non-HTTPS)
+        // origin where the browser would silently reject them.
+        return false;
+    }
+};
+/**
+ * Resolve the actual cookie name for an auth cookie.
+ *
+ * In production the auth-bearing cookies get the `__Host-` prefix. Browsers
+ * reject any `__Host-`-prefixed cookie that carries a `Domain` attribute (and
+ * require `Secure` + `Path=/`), so a sibling subdomain (e.g. a tenant preview
+ * at `<token>.preview.molecule.dev`) can no longer create a colliding
+ * `.molecule.dev`-scoped duplicate that shadows the platform's real session
+ * cookie — closing the cross-tenant cookie-tossing / session-fixation hole.
+ *
+ * In dev/test the cookies are not `Secure` (plain HTTP origins), so a
+ * `__Host-` cookie would be rejected by the browser; use the plain name there.
+ *
+ * Exported so consumers (e.g. molecule-dev's guest-session / OAuth-state code)
+ * set and read the exact same name the platform expects.
+ *
+ * @param base - The base cookie name (e.g. `'token'`, `'sessionId'`).
+ * @returns The environment-appropriate cookie name.
+ */
+export const getAuthCookieName = (base) => isProduction() ? `__Host-${base}` : base;
+/**
+ * Whether this API serves an app embedded in a CROSS-SITE iframe — i.e. the
+ * molecule.dev live preview, where the app renders at `127.0.0.1:<port>` inside
+ * the `localhost:3000` (prod: `*.preview.molecule.dev` inside `molecule.dev`)
+ * IDE. The platform sets `MOL_CROSS_SITE_COOKIES=1` in the sandbox container's
+ * env for exactly this case; a normally-deployed or locally-run app (which is a
+ * TOP-LEVEL document) never sets it.
+ *
+ * This is deliberately NOT derived from `NODE_ENV`: the molecule.dev IDE itself
+ * and a developer running their generated app locally are BOTH non-production
+ * AND top-level, so keying cross-site cookies off `NODE_ENV` wrongly forced
+ * `SameSite=None; Partitioned` onto those top-level sessions — which then
+ * coexisted with the browser's pre-existing `Lax` cookie of the same name in a
+ * SEPARATE jar, sending a duplicate `token` header and breaking auth.
+ *
+ * @returns `true` only when the app is served cross-site in the preview iframe.
+ */
+const isCrossSitePreview = () => {
+    try {
+        return getConfig('MOL_CROSS_SITE_COOKIES') === '1';
+    }
+    catch (_error) {
+        // Config read is optional — absence means "not the preview" (top-level).
+        return false;
+    }
+};
+/**
+ * Base cookie attributes shared by EVERY auth cookie this resource sets and
+ * clears — the single source of truth so a SET and its matching CLEAR always
+ * agree (a mismatched attribute leaves an undeletable cookie) and every auth
+ * cookie gets identical behaviour.
+ *
+ * - **Cross-site preview** (see {@link isCrossSitePreview}) → `{ secure: true,
+ *   sameSite: 'none', partitioned: true, path: '/' }`. The molecule.dev live
+ *   preview renders the app in a CROSS-SITE iframe; browsers evaluate SameSite
+ *   against the TOP-LEVEL site, so a `Lax`/`Strict` cookie is neither stored nor
+ *   sent on ANY preview request — the httpOnly session cookie vanishes on every
+ *   iframe reload and the user is logged out of their own app. `SameSite=None`
+ *   makes it cross-site-sendable (which REQUIRES `Secure` — permitted over http
+ *   on the potentially-trustworthy `localhost` / `127.0.0.1` origins), and
+ *   `Partitioned` (CHIPS) keeps it working when third-party cookies are blocked
+ *   (Brave/Chrome), which `None` alone does not. Applies whether the platform is
+ *   dev or prod, because the preview app is cross-site either way.
+ * - **Production, top-level** → `{ secure: true, sameSite: 'lax', path: '/' }`.
+ *   The correct, CSRF-hardened default; pairs with the `__Host-` prefix (see
+ *   {@link getAuthCookieName}). NEVER weaken it.
+ * - **Development, top-level** → `{ secure: false, sameSite: 'lax', path: '/' }`.
+ *   The original dev posture (plain http, not `Secure`) — used by the molecule.dev
+ *   IDE and by a developer running their generated app locally. Both are top-level
+ *   documents, so `Lax` is correct and `Secure`/`None`/`Partitioned` would be both
+ *   unnecessary and (as above) actively harmful.
+ *
+ * `httpOnly` and `maxAge` are intentionally omitted: the SET call adds those per
+ * cookie, and the CLEAR call spreads these attributes verbatim so the deletion
+ * targets the exact same (possibly Partitioned) cookie jar.
+ *
+ * @returns The environment-appropriate base cookie options.
+ */
+export const getAuthCookieOptions = () => {
+    if (isCrossSitePreview()) {
+        return { secure: true, sameSite: 'none', partitioned: true, path: '/' };
+    }
+    return isProduction()
+        ? { secure: true, sameSite: 'lax', path: '/' }
+        : { secure: false, sameSite: 'lax', path: '/' };
+};
+/**
+ * Read an auth cookie by its base name. In production the cookie is `__Host-`-
+ * prefixed (untossable: browsers reject `__Host-` cookies carrying a Domain), so
+ * we read ONLY that name and do NOT fall back to the plain name. [C4-1] Accepting
+ * the plain name in production re-opens cookie-tossing session fixation: a tenant
+ * on a sibling `*.molecule.dev` preview can write a `.molecule.dev`-scoped plain
+ * cookie that a plain-name fallback would honor. The `__Host-`-prefixed name is the
+ * only legitimate production cookie; sessions still carrying a plain cookie simply
+ * re-authenticate on the deploy that flips the prefix on. In dev there is no prefix,
+ * so the (plain) name returned by getAuthCookieName is the real cookie.
+ *
+ * @param cookies - The request cookies map.
+ * @param base - The base cookie name.
+ * @returns The cookie value, or `undefined` if absent.
+ */
+const readAuthCookie = (cookies, base) => {
+    const primary = cookies?.[getAuthCookieName(base)];
+    if (isProduction())
+        return primary;
+    return primary ?? cookies?.[base];
+};
+/**
+ * Short-TTL positive cache for "device still exists" lookups, to bound the
+ * per-request DB cost of server-side session-revocation enforcement.
+ *
+ * Caching model and its honest revocation guarantee:
+ * - Only POSITIVE results (device exists) are cached; a definitive "device not
+ *   found" result is NEVER cached, and a found row drops any stale entry. So a
+ *   revoked device is rejected as soon as the cache misses or expires.
+ * - Revocations performed IN THIS PROCESS (logout, remote device removal,
+ *   password change/reset, account deletion — the user-resource handlers that
+ *   wipe device rows) are made effective IMMEDIATELY by actively evicting the
+ *   cache via {@link invalidateDeviceExistsCache} / {@link invalidateAllDeviceExistsCache}
+ *   at the revocation call site. The very next request re-checks the DB and is
+ *   rejected — there is no residual window for in-process revocation.
+ * - Revocations performed by ANOTHER process (a different API instance in a
+ *   multi-instance deployment, or a direct DB delete) cannot evict THIS
+ *   process's in-memory cache, so a token whose positive entry was warmed here
+ *   within the last `deviceExistsCacheTtlMs` may keep authenticating on THIS
+ *   instance for up to that window (≤10s) before the entry expires and the DB
+ *   is consulted again. This is the deliberate eventual-consistency tradeoff of
+ *   a per-process cache; lower the TTL or back the cache with a shared
+ *   pub/sub store to shrink it further.
+ */
+const deviceExistsCacheTtlMs = 10_000;
+const deviceExistsCache = new Map();
+/**
+ * Evict a single device's positive entry from the device-exists cache so the
+ * next authorization check for that device re-consults the database.
+ *
+ * Call this from any in-process revocation path that deletes a specific device
+ * row (e.g. a logout handler that knows the `deviceId`) so the revocation is
+ * effective immediately on this instance rather than after the cache TTL.
+ *
+ * @param deviceId - The device id whose cached "exists" result should be dropped.
+ */
+export const invalidateDeviceExistsCache = (deviceId) => {
+    deviceExistsCache.delete(deviceId);
+};
+/**
+ * Evict ALL positive entries from the device-exists cache.
+ *
+ * Call this from in-process bulk revocation paths that delete every device for
+ * a user (password change/reset, account deletion, OAuth account-claim) where
+ * the affected device ids are not enumerated — the cache is keyed by deviceId,
+ * not userId, so a full clear is the correct way to guarantee none of the
+ * just-deleted devices keep authenticating on this instance. The normal-path
+ * per-request DB-cost reduction is preserved: the cache simply repopulates on
+ * subsequent requests; only these rare revocation events pay a brief re-check.
+ */
+export const invalidateAllDeviceExistsCache = () => {
+    deviceExistsCache.clear();
+};
+/**
+ * Determine whether a session's device is still active (i.e. has not been
+ * revoked by logout, remote device removal, or a password reset). This is the
+ * server-side revocation check that makes those controls actually terminate a
+ * session instead of leaving the JWT valid until natural expiry.
+ *
+ * Behaviour:
+ * - If no device bond exposing `exists` is wired (e.g. an app that doesn't
+ *   track devices), revocation cannot be enforced, so the session is allowed
+ *   (backward-compatible — no functionality regression).
+ * - If `exists` returns `false`, the device was revoked → reject.
+ * - If the lookup throws (transient infra failure), the session is allowed
+ *   (best-effort, fail-open on errors only) and the error is logged, so a DB
+ *   blip does not log out the entire platform. A genuine revocation returns a
+ *   definitive `false`, which is always honoured.
+ *
+ * @param deviceId - The device id from the verified session.
+ * @returns `true` if the session may proceed, `false` if it was revoked.
+ */
+const isDeviceActive = async (deviceId) => {
+    const deviceService = get('device');
+    // No device-tracking bond, or a bond that predates the `exists` capability —
+    // cannot enforce revocation here; do not break auth.
+    if (typeof deviceService?.exists !== 'function') {
+        return true;
+    }
+    const cachedAt = deviceExistsCache.get(deviceId);
+    if (cachedAt !== undefined && Date.now() - cachedAt < deviceExistsCacheTtlMs) {
+        return true;
+    }
+    try {
+        const exists = await deviceService.exists(deviceId);
+        if (exists) {
+            deviceExistsCache.set(deviceId, Date.now());
+            return true;
+        }
+        // Definitive revocation — drop any stale positive cache entry and reject.
+        deviceExistsCache.delete(deviceId);
+        return false;
+    }
+    catch (error) {
+        // Best-effort: a transient lookup failure must not log out everyone.
+        logger.warn('authorization: device revocation check failed; allowing session', {
+            deviceId,
+            error,
+        });
+        return true;
+    }
+};
+/**
+ * Set authorization headers and cookie for a session.
+ *
+ * @param _req - The request object (unused; reserved for handler signature parity).
+ * @param res - The response object.
+ * @param session - The session.
+ * @returns The signed JWT token string, or null if signing failed.
+ */
+export const set = (_req, res, session) => {
+    try {
+        // Create a session ID for web browser clients.
+        if (!session.id) {
+            session.id = uuid();
+        }
+        // Strip JWT-specific claims from the session before re-signing —
+        // sign() sets expiresIn which conflicts with an existing exp property.
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { exp, iat, nbf, ...sessionPayload } = session;
+        const token = sign(sessionPayload);
+        if (token) {
+            res.setHeader('Authorization', `Bearer ${token}`);
+            // Set as cookies for web browser clients.
+            // In production the names are `__Host-`-prefixed (see getAuthCookieName),
+            // which REQUIRES Secure + Path=/ + NO Domain — all satisfied by
+            // getAuthCookieOptions() — and makes the cookies unshadowable by a sibling
+            // subdomain. In the sandbox live-preview iframe those same options switch to
+            // SameSite=None + Secure + Partitioned so the cross-site iframe actually
+            // keeps them (otherwise the session vanishes on every reload).
+            const cookieOptions = getAuthCookieOptions();
+            const maxAge = 1000 * 60 * 60 * 24 * 7; // 7 days (match JWT expiry)
+            res.cookie(getAuthCookieName('token'), token, {
+                ...cookieOptions,
+                httpOnly: true,
+                maxAge,
+            });
+            res.cookie(getAuthCookieName('sessionId'), session.id, {
+                ...cookieOptions,
+                httpOnly: true,
+                maxAge,
+            });
+            // [M1-1] Non-httpOnly session-PRESENCE hint (carries no token — just "1").
+            // The bearer token is in-memory + the httpOnly `token` cookie (both
+            // JS-unreadable), so on a fresh load the app can't tell "logged in" from
+            // "anonymous" without probing the server. This readable hint lets the auth
+            // client's initialize() probe the cookie-restore endpoint ONLY when a
+            // session plausibly exists — so anonymous/public page loads make ZERO API
+            // calls (no /users/me, no 401). A tossed/forged hint only costs one
+            // harmless 401 probe; it grants nothing (the real credential stays
+            // httpOnly). Cleared by logout alongside the credential cookies.
+            res.cookie('mol_auth', '1', {
+                ...cookieOptions,
+                httpOnly: false,
+                maxAge,
+            });
+            return token;
+        }
+    }
+    catch (error) {
+        logger.error(error);
+    }
+    return null;
+};
+/**
+ * Middleware that verifies the JWT token from the `Authorization` header and sets `res.locals.session`.
+ * Falls back to cookie-based session for browser clients. Auto-refreshes tokens older than `JWT_REFRESH_TIME`.
+ * @returns An Express-compatible middleware function.
+ */
+export const verifyMiddleware = () => async (req, res, next) => {
+    try {
+        // Get token from Authorization header, falling back to the `token`
+        // cookie that `set()` writes alongside the header. The JSDoc above
+        // promises this fallback for browser clients; without it the cookie
+        // we hand out is decorative — every page-driven request after login
+        // gets a 401, even though the cookie is sitting right there. We still
+        // verify the signature via `jwtVerify` so a tampered cookie value is
+        // never trusted (no decode-fallback bypass).
+        const rawAuth = req.headers.authorization;
+        const authHeader = Array.isArray(rawAuth) ? rawAuth[0] : rawAuth;
+        const headerToken = authHeader?.startsWith('Bearer ') ? authHeader.slice(7) : null;
+        const cookies = req.cookies;
+        const cookieToken = readAuthCookie(cookies, 'token');
+        const token = headerToken ?? (typeof cookieToken === 'string' && cookieToken ? cookieToken : null);
+        if (!token) {
+            return next();
+        }
+        // Try to verify the token.
+        let session = null;
+        try {
+            session = jwtVerify(token);
+        }
+        catch (_error) {
+            // Token is invalid or expired — do NOT accept unverified tokens.
+            // Previous code used decode() (no signature check) as a fallback,
+            // which allowed expired/tampered tokens to be accepted if a cookie matched.
+            // This was an authentication bypass. Require re-authentication instead.
+        }
+        if (session?.userId && session?.deviceId) {
+            // Server-side session revocation. A logged-out / remotely-revoked /
+            // password-reset device row is deleted; that MUST invalidate every copy
+            // of the JWT, not just the browser that called logout. Without this a
+            // valid signature alone keeps the session alive until natural expiry
+            // (default 7 days), so logout is purely cosmetic. Check BEFORE exposing
+            // the session so a revoked token never reaches a handler.
+            if (!(await isDeviceActive(session.deviceId))) {
+                return next();
+            }
+            res.locals.session = session;
+            // Auto-refresh the token if it's old enough.
+            try {
+                const decoded = decode(token);
+                if (decoded?.iat) {
+                    const tokenAge = Date.now() - decoded.iat * 1000;
+                    if (tokenAge > getJwtRefreshTime()) {
+                        // Update device last seen timestamp via bond.
+                        await get('device')?.updateLastSeen(session.deviceId);
+                        // Issue a fresh token.
+                        set(req, res, session);
+                    }
+                }
+            }
+            catch (_error) {
+                // Non-critical — token refresh is best-effort; continue with existing session.
+            }
+        }
+    }
+    catch (error) {
+        logger.error('authorization.verify error:', error);
+    }
+    return next();
+};
+//# sourceMappingURL=authorization.js.map

package/dist/authorization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization.js","sourceRoot":"","sources":["../src/authorization.ts"],"names":[],"mappings":"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"}

package/dist/authorizers/auth.d.ts

@@ -0,0 +1,8 @@
+import type { MoleculeRequestHandler } from '@molecule/api-resource';
+/**
+ * Middleware that checks if the request has an authenticated session (`res.locals.session.userId`).
+ * Calls `next()` on success or `next('Unauthorized')` on failure.
+ * @returns An Express-compatible middleware function.
+ */
+export declare const auth: () => MoleculeRequestHandler;
+//# sourceMappingURL=auth.d.ts.map

package/dist/authorizers/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/authorizers/auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAEpE;;;;GAIG;AACH,eAAO,MAAM,IAAI,QAAO,sBAUvB,CAAA"}

package/dist/authorizers/auth.js

@@ -0,0 +1,19 @@
+import { t } from '@molecule/api-i18n';
+/**
+ * Middleware that checks if the request has an authenticated session (`res.locals.session.userId`).
+ * Calls `next()` on success or `next('Unauthorized')` on failure.
+ * @returns An Express-compatible middleware function.
+ */
+export const auth = () => (req, res, next) => {
+    try {
+        const { session } = res.locals;
+        if (session?.userId) {
+            return next();
+        }
+    }
+    catch (_error) {
+        // Safe to ignore: if session access throws, we fall through to Unauthorized below.
+    }
+    return next(t('resource.error.unauthorized', undefined, { defaultValue: 'Unauthorized' }));
+};
+//# sourceMappingURL=auth.js.map

package/dist/authorizers/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/authorizers/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAGtC;;;;GAIG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,GAA2B,EAAE,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;IACnE,IAAI,CAAC;QACH,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC,MAAM,CAAA;QAC9B,IAAI,OAAO,EAAE,MAAM,EAAE,CAAC;YACpB,OAAO,IAAI,EAAE,CAAA;QACf,CAAC;IACH,CAAC;IAAC,OAAO,MAAM,EAAE,CAAC;QAChB,mFAAmF;IACrF,CAAC;IACD,OAAO,IAAI,CAAC,CAAC,CAAC,6BAA6B,EAAE,SAAS,EAAE,EAAE,YAAY,EAAE,cAAc,EAAE,CAAC,CAAC,CAAA;AAC5F,CAAC,CAAA"}