@byline/client 4.0.0 → 4.2.0

package/dist/server/request-scope.d.ts

@@ -0,0 +1,17 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Resolve `factory` at most once per HTTP request for a given `key`. The
+ * returned promise is memoized on the current request — rejections
+ * included, since a request's cookies cannot change mid-flight and retrying
+ * a failed refresh would burn a second rotation on an already-rotated
+ * token. Outside a request (seed scripts, unit tests, background jobs) —
+ * or before a host bridge is registered — there is no request to key on
+ * and the factory runs unmemoized.
+ */
+export declare function oncePerRequest<T>(key: string, factory: () => Promise<T>): Promise<T>;

package/dist/server/request-scope.js

@@ -0,0 +1,50 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Per-request memoization for `RequestContext` factories.
+ *
+ * `RequestContext.requestId` is documented as "per logical request", and
+ * the read-authorization layer binds every `ReadContext` to one immutable
+ * request authority whose token includes that id. A factory that mints a
+ * fresh context per call breaks both contracts as soon as two reads share
+ * a `ReadContext` (the admin tree view, hook-threaded nested reads):
+ * the second bind sees a different authority token and throws
+ * 'ReadContext cannot be reused across request authorities'.
+ *
+ * Memoizing on the current request (via the registered
+ * `HostRequestBridge`) makes every context factory request-stable. It
+ * also means at most one session verification — and at most one
+ * refresh-token rotation — per request, instead of one per call.
+ */
+import { tryGetHostRequestBridge } from '@byline/core';
+const requestScopes = new WeakMap();
+/**
+ * Resolve `factory` at most once per HTTP request for a given `key`. The
+ * returned promise is memoized on the current request — rejections
+ * included, since a request's cookies cannot change mid-flight and retrying
+ * a failed refresh would burn a second rotation on an already-rotated
+ * token. Outside a request (seed scripts, unit tests, background jobs) —
+ * or before a host bridge is registered — there is no request to key on
+ * and the factory runs unmemoized.
+ */
+export function oncePerRequest(key, factory) {
+    const request = tryGetHostRequestBridge()?.getRequest();
+    if (!request)
+        return factory();
+    let scope = requestScopes.get(request);
+    if (!scope) {
+        scope = new Map();
+        requestScopes.set(request, scope);
+    }
+    const existing = scope.get(key);
+    if (existing)
+        return existing;
+    const pending = factory();
+    scope.set(key, pending);
+    return pending;
+}

package/dist/server/request-scope.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/server/request-scope.test.node.js

@@ -0,0 +1,89 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Unit coverage for per-request memoization. Registers a fake
+ * `HostRequestBridge` so "which request am I in" can be simulated: a
+ * stable object per request, or `undefined` when running outside a
+ * request.
+ */
+import { registerHostRequestBridge } from '@byline/core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { oncePerRequest } from './request-scope.js';
+const BRIDGE_SLOT = Symbol.for('__byline_host_request_bridge__');
+const previousBridge = globalThis[BRIDGE_SLOT];
+const bridge = {
+    getRequest: vi.fn(),
+    getCookie: vi.fn(),
+    setCookie: vi.fn(),
+};
+describe('oncePerRequest', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        registerHostRequestBridge(bridge);
+        // Default: no request in scope, so every call resolves fresh.
+        bridge.getRequest.mockReturnValue(undefined);
+    });
+    afterEach(() => {
+        ;
+        globalThis[BRIDGE_SLOT] = previousBridge;
+    });
+    it('resolves the factory once per request per key', async () => {
+        bridge.getRequest.mockReturnValue({ id: 'request-a' });
+        const factory = vi.fn(async () => ({ token: Math.random() }));
+        const first = await oncePerRequest('ctx', factory);
+        const second = await oncePerRequest('ctx', factory);
+        expect(second).toBe(first);
+        expect(factory).toHaveBeenCalledTimes(1);
+    });
+    it('keys memoization by request identity', async () => {
+        const requestA = { id: 'a' };
+        const requestB = { id: 'b' };
+        const factory = vi.fn(async () => ({ token: Math.random() }));
+        bridge.getRequest.mockReturnValue(requestA);
+        const first = await oncePerRequest('ctx', factory);
+        bridge.getRequest.mockReturnValue(requestB);
+        const second = await oncePerRequest('ctx', factory);
+        expect(second).not.toBe(first);
+        expect(factory).toHaveBeenCalledTimes(2);
+    });
+    it('isolates entries by key within one request', async () => {
+        bridge.getRequest.mockReturnValue({ id: 'request-a' });
+        const admin = vi.fn(async () => 'admin-context');
+        const publicCtx = vi.fn(async () => 'public-context');
+        await expect(oncePerRequest('admin', admin)).resolves.toBe('admin-context');
+        await expect(oncePerRequest('public', publicCtx)).resolves.toBe('public-context');
+        await expect(oncePerRequest('admin', admin)).resolves.toBe('admin-context');
+        expect(admin).toHaveBeenCalledTimes(1);
+        expect(publicCtx).toHaveBeenCalledTimes(1);
+    });
+    it('memoizes rejections for the remainder of the request', async () => {
+        bridge.getRequest.mockReturnValue({ id: 'request-a' });
+        const factory = vi.fn(async () => {
+            throw new Error('no admin session');
+        });
+        await expect(oncePerRequest('ctx', factory)).rejects.toThrow('no admin session');
+        await expect(oncePerRequest('ctx', factory)).rejects.toThrow('no admin session');
+        expect(factory).toHaveBeenCalledTimes(1);
+    });
+    it('runs unmemoized outside a request', async () => {
+        const factory = vi.fn(async () => ({ token: Math.random() }));
+        const first = await oncePerRequest('ctx', factory);
+        const second = await oncePerRequest('ctx', factory);
+        expect(second).not.toBe(first);
+        expect(factory).toHaveBeenCalledTimes(2);
+    });
+    it('runs unmemoized when no host bridge is registered', async () => {
+        ;
+        globalThis[BRIDGE_SLOT] = undefined;
+        const factory = vi.fn(async () => ({ token: Math.random() }));
+        const first = await oncePerRequest('ctx', factory);
+        const second = await oncePerRequest('ctx', factory);
+        expect(second).not.toBe(first);
+        expect(factory).toHaveBeenCalledTimes(2);
+    });
+});

package/dist/server/session-cookies.d.ts

@@ -0,0 +1,34 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export declare const ACCESS_TOKEN_COOKIE = "byline_access_token";
+export declare const REFRESH_TOKEN_COOKIE = "byline_refresh_token";
+/** Read the access-token cookie. Returns undefined when not present. */
+export declare function readAccessTokenCookie(): string | undefined;
+/** Read the refresh-token cookie. Returns undefined when not present. */
+export declare function readRefreshTokenCookie(): string | undefined;
+export interface SessionCookieTokens {
+    accessToken: string;
+    refreshToken: string;
+    accessTokenExpiresAt: Date;
+    refreshTokenExpiresAt: Date;
+}
+/**
+ * Write both access and refresh cookies. Called after sign-in and after
+ * every transparent refresh in `getAdminRequestContext()`.
+ *
+ * `maxAge` is derived from each token's own expiry claim so the browser
+ * drops the cookies at the same moment the server would reject them —
+ * saves round trips when the refresh token has fully expired.
+ */
+export declare function setSessionCookies(tokens: SessionCookieTokens): void;
+/**
+ * Clear both session cookies. Called on sign-out and on any auth failure
+ * during `getAdminRequestContext()` (ensures the browser does not keep
+ * trying a token that the server has already rejected).
+ */
+export declare function clearSessionCookies(): void;

package/dist/server/session-cookies.js

@@ -0,0 +1,95 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Cookie helpers for admin session management.
+ *
+ * Two separate httpOnly cookies, one for each token half:
+ *
+ *   - `byline_access_token`  — short-lived JWT; sent on every request.
+ *   - `byline_refresh_token` — long-lived opaque string; sent back only
+ *                              when the access cookie is missing or
+ *                              expired, to mint a new access token.
+ *
+ * Presenting "one session" to the user is a function of the middleware —
+ * `getAdminRequestContext()` transparently refreshes the access cookie
+ * using the refresh cookie, so the UI layer doesn't have to care.
+ *
+ * All cookies set here use:
+ *   - `httpOnly: true`   — inaccessible to JavaScript (XSS-hardened).
+ *   - `sameSite: 'lax'`  — sent on top-level navigations but not
+ *                          cross-origin subrequests (reasonable default
+ *                          for an admin SSR app).
+ *   - `secure: true` in production — https-only; dev keeps it off so
+ *                          cookies work on http://localhost.
+ *   - `path: '/'`        — available everywhere in the app.
+ *
+ * Cookie transport goes through the registered `HostRequestBridge`, so
+ * this module is host-framework agnostic.
+ */
+import { getHostRequestBridge } from '@byline/core';
+export const ACCESS_TOKEN_COOKIE = 'byline_access_token';
+export const REFRESH_TOKEN_COOKIE = 'byline_refresh_token';
+const IS_PROD = process.env.NODE_ENV === 'production';
+/** Read the access-token cookie. Returns undefined when not present. */
+export function readAccessTokenCookie() {
+    return getHostRequestBridge().getCookie(ACCESS_TOKEN_COOKIE);
+}
+/** Read the refresh-token cookie. Returns undefined when not present. */
+export function readRefreshTokenCookie() {
+    return getHostRequestBridge().getCookie(REFRESH_TOKEN_COOKIE);
+}
+/**
+ * Write both access and refresh cookies. Called after sign-in and after
+ * every transparent refresh in `getAdminRequestContext()`.
+ *
+ * `maxAge` is derived from each token's own expiry claim so the browser
+ * drops the cookies at the same moment the server would reject them —
+ * saves round trips when the refresh token has fully expired.
+ */
+export function setSessionCookies(tokens) {
+    const bridge = getHostRequestBridge();
+    const now = Date.now();
+    const accessMaxAgeSeconds = Math.max(0, Math.floor((tokens.accessTokenExpiresAt.getTime() - now) / 1000));
+    const refreshMaxAgeSeconds = Math.max(0, Math.floor((tokens.refreshTokenExpiresAt.getTime() - now) / 1000));
+    bridge.setCookie(ACCESS_TOKEN_COOKIE, tokens.accessToken, {
+        httpOnly: true,
+        sameSite: 'lax',
+        secure: IS_PROD,
+        path: '/',
+        maxAge: accessMaxAgeSeconds,
+    });
+    bridge.setCookie(REFRESH_TOKEN_COOKIE, tokens.refreshToken, {
+        httpOnly: true,
+        sameSite: 'lax',
+        secure: IS_PROD,
+        path: '/',
+        maxAge: refreshMaxAgeSeconds,
+    });
+}
+/**
+ * Clear both session cookies. Called on sign-out and on any auth failure
+ * during `getAdminRequestContext()` (ensures the browser does not keep
+ * trying a token that the server has already rejected).
+ */
+export function clearSessionCookies() {
+    const bridge = getHostRequestBridge();
+    bridge.setCookie(ACCESS_TOKEN_COOKIE, '', {
+        httpOnly: true,
+        sameSite: 'lax',
+        secure: IS_PROD,
+        path: '/',
+        maxAge: 0,
+    });
+    bridge.setCookie(REFRESH_TOKEN_COOKIE, '', {
+        httpOnly: true,
+        sameSite: 'lax',
+        secure: IS_PROD,
+        path: '/',
+        maxAge: 0,
+    });
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/client",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -31,14 +31,21 @@
       "import": "./dist/index.js",
       "require": "./dist/index.js"
     },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "browser": "./dist/server/browser.js",
+      "import": "./dist/server/index.js",
+      "require": "./dist/server/index.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@byline/core": "4.0.0",
-    "@byline/auth": "4.0.0"
+    "uuid": "^14.0.1",
+    "@byline/core": "4.2.0",
+    "@byline/auth": "4.2.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
@@ -51,8 +58,8 @@
     "tsx": "^4.23.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10",
-    "@byline/db-postgres": "4.0.0",
-    "@byline/search-postgres": "4.0.0"
+    "@byline/db-postgres": "4.2.0",
+    "@byline/search-postgres": "4.2.0"
   },
   "publishConfig": {
     "access": "public",