@byline/client 4.0.0 → 4.1.0

package/dist/server/clients.js

@@ -0,0 +1,170 @@
+/**
+ * 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
+ */
+/**
+ * The server-side `BylineClient` singletons — four request-authority
+ * flavours over one shared `getServerConfig()` wiring. All four share the
+ * module-scoped singleton pattern so the SDK's per-instance
+ * `collectionRecordCache` is amortised across the process lifetime; what
+ * differs is only how each resolves its `RequestContext`:
+ *
+ *   - `getPublicBylineClient()` — anonymous, published-only. Strict
+ *     "preview can never apply": use it for RSS/Atom feeds, sitemaps,
+ *     JSON endpoints for third parties, and anything an upstream CDN
+ *     might serve without keying off the `byline_preview` cookie.
+ *   - `getViewerBylineClient()` — the preview-aware sibling. Behaves
+ *     identically to the public client until both the `byline_preview`
+ *     cookie is set **and** a valid admin session resolves; then the
+ *     per-call factory returns the authenticated `AdminAuth` instead of
+ *     the anonymous null actor. Use it on user-facing public reads where
+ *     an admin's preview-mode session should be honoured.
+ *   - `getAdminBylineClient()` — resolves the authenticated admin actor
+ *     per request via `getAdminRequestContext` (session cookies, with the
+ *     transparent refresh dance). Every admin server fn read goes through
+ *     this client, so the full read pipeline (`beforeRead` →
+ *     `findDocuments` → `populate` → `afterRead`) is uniform between
+ *     admin and any external client.
+ *   - `getSystemBylineClient()` — bound to an explicit super-admin
+ *     context for **system / background** work that is not scoped to an
+ *     HTTP request: lifecycle-hook search indexing, maintenance scripts,
+ *     seeds, migrations. Does not read cookies, so it works outside any
+ *     host request runtime. The context is auditable by its stable id.
+ *
+ * Why `assertActorCanPerform` cares (viewer client): the auth layer only
+ * permits anonymous reads when `readMode === 'published'`. If a server fn
+ * passes `status: 'any'` to surface drafts, an anonymous request trips
+ * the gate and throws — but a preview-mode admin sails through. The
+ * source-view selection itself remains a per-call decision: the SDK's
+ * `resolveReadMode` defaults to `'published'` regardless of context, so
+ * every server fn still has to opt in by passing `status: 'any'`.
+ *
+ * The viewer contract for callers:
+ *
+ *   1. Use `getViewerBylineClient()` on any user-facing public read
+ *      where an admin's preview-mode session should be honoured; use
+ *      `getPublicBylineClient()` where preview must never apply.
+ *   2. Call `isPreviewActive()` once per server fn to decide whether to
+ *      pass `status: 'any'` on the read.
+ *
+ * Stale preview cookies fail closed: if the preview cookie is present but
+ * no valid admin session resolves, the viewer factory returns the same
+ * anonymous + `'published'` context the public client would have used, so
+ * the worst case is "preview cookie does nothing".
+ *
+ * In an application whose generated collection types augment `Register`
+ * (see `../register.ts`), every getter here returns a fully typed
+ * `BylineClient` — `client.collection('news')` autocompletes paths and
+ * returns the generated field shapes.
+ */
+import { createRequestContext, createSuperAdminContext } from '@byline/auth';
+import { getServerConfig } from '@byline/core';
+import { createBylineClient } from '../client.js';
+import { getAdminRequestContext } from './admin-context.js';
+import { readPreviewCookie } from './preview-cookies.js';
+import { oncePerRequest } from './request-scope.js';
+let cachedAdminClient;
+export function getAdminBylineClient() {
+    if (cachedAdminClient)
+        return cachedAdminClient;
+    cachedAdminClient = createBylineClient({
+        config: getServerConfig(),
+        // Resolved from the current request's session cookies, memoized per
+        // request: every read in one request binds the same context instance
+        // (and requestId), which the ReadContext authority check requires.
+        // `getAdminRequestContext` runs the refresh dance on its own and throws
+        // `ERR_UNAUTHENTICATED` when no session is present — the client
+        // surfaces the throw verbatim.
+        requestContext: getAdminRequestContext,
+    });
+    return cachedAdminClient;
+}
+let cachedSystemClient;
+export function getSystemBylineClient() {
+    if (cachedSystemClient)
+        return cachedSystemClient;
+    cachedSystemClient = createBylineClient({
+        config: getServerConfig(),
+        requestContext: createSuperAdminContext({ id: 'byline-system-client' }),
+    });
+    return cachedSystemClient;
+}
+/**
+ * Anonymous, published-only context — memoized per request so the
+ * context (and its requestId) is stable across every read in one
+ * request: reads sharing a ReadContext must bind a single request
+ * authority.
+ */
+export function resolvePublicRequestContext() {
+    return oncePerRequest('byline:public-request-context', async () => createRequestContext({ readMode: 'published' }));
+}
+let cachedPublicClient;
+export function getPublicBylineClient() {
+    if (cachedPublicClient)
+        return cachedPublicClient;
+    cachedPublicClient = createBylineClient({
+        config: getServerConfig(),
+        requestContext: resolvePublicRequestContext,
+    });
+    return cachedPublicClient;
+}
+/**
+ * Preview-aware viewer context — memoized per request so every read in
+ * one request binds the same context instance (and requestId): reads
+ * sharing a ReadContext must resolve a single request authority.
+ */
+export function resolveViewerRequestContext() {
+    return oncePerRequest('byline:viewer-request-context', resolveViewerContext);
+}
+async function resolveViewerContext() {
+    // No preview cookie → behave exactly like the public client.
+    // Cheap path; no JWT verification, no DB lookup.
+    if (!readPreviewCookie()) {
+        return createRequestContext({ readMode: 'published' });
+    }
+    // Preview cookie present → try the admin context. A failure means
+    // the cookie is stale (admin signed out, session expired, refresh
+    // rejected). We swallow the error and fall back to the public
+    // context so the page renders instead of erroring.
+    try {
+        const ctx = await getAdminRequestContext();
+        return { ...ctx, readMode: 'any' };
+    }
+    catch {
+        return createRequestContext({ readMode: 'published' });
+    }
+}
+let cachedViewerClient;
+export function getViewerBylineClient() {
+    if (cachedViewerClient)
+        return cachedViewerClient;
+    cachedViewerClient = createBylineClient({
+        config: getServerConfig(),
+        requestContext: resolveViewerRequestContext,
+    });
+    return cachedViewerClient;
+}
+/**
+ * Resolve whether the current request should surface non-published
+ * versions. True iff the preview cookie is set **and** a valid admin
+ * session resolves. Server fns call this once and pass the result to
+ * `status: preview ? 'any' : 'published'` on the SDK read.
+ *
+ * Defensive by design: the cookie alone is not enough. A signed-out
+ * browser carrying an old preview cookie still gets `false` here, which
+ * keeps stray query strings or shared links from leaking drafts.
+ */
+export async function isPreviewActive() {
+    if (!readPreviewCookie())
+        return false;
+    try {
+        await getAdminRequestContext();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/server/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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
+ */
+/**
+ * `@byline/client/server` — the client SDK's server-side entry point.
+ *
+ * Request-bound `BylineClient` getters and the session/preview machinery
+ * behind them, implemented against the `HostRequestBridge` seam
+ * (`@byline/core`) so this surface is host-framework agnostic. A host
+ * adapter (e.g. `@byline/host-tanstack-start`) registers the bridge at
+ * server boot; application code imports the getters from here and never
+ * touches the host framework.
+ *
+ * Server-only: the package's `browser` export condition resolves this
+ * subpath to a stub that throws, so an accidental import from browser
+ * code fails loudly at bundle time rather than leaking server machinery.
+ */
+export { getAdminRequestContext } from './admin-context.js';
+export { getAdminBylineClient, getPublicBylineClient, getSystemBylineClient, getViewerBylineClient, isPreviewActive, resolvePublicRequestContext, resolveViewerRequestContext, } from './clients.js';
+export { clearPreviewCookie, PREVIEW_COOKIE, readPreviewCookie, setPreviewCookie, } from './preview-cookies.js';
+export { oncePerRequest } from './request-scope.js';
+export { ACCESS_TOKEN_COOKIE, clearSessionCookies, REFRESH_TOKEN_COOKIE, readAccessTokenCookie, readRefreshTokenCookie, type SessionCookieTokens, setSessionCookies, } from './session-cookies.js';

package/dist/server/index.js

@@ -0,0 +1,26 @@
+/**
+ * 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
+ */
+/**
+ * `@byline/client/server` — the client SDK's server-side entry point.
+ *
+ * Request-bound `BylineClient` getters and the session/preview machinery
+ * behind them, implemented against the `HostRequestBridge` seam
+ * (`@byline/core`) so this surface is host-framework agnostic. A host
+ * adapter (e.g. `@byline/host-tanstack-start`) registers the bridge at
+ * server boot; application code imports the getters from here and never
+ * touches the host framework.
+ *
+ * Server-only: the package's `browser` export condition resolves this
+ * subpath to a stub that throws, so an accidental import from browser
+ * code fails loudly at bundle time rather than leaking server machinery.
+ */
+export { getAdminRequestContext } from './admin-context.js';
+export { getAdminBylineClient, getPublicBylineClient, getSystemBylineClient, getViewerBylineClient, isPreviewActive, resolvePublicRequestContext, resolveViewerRequestContext, } from './clients.js';
+export { clearPreviewCookie, PREVIEW_COOKIE, readPreviewCookie, setPreviewCookie, } from './preview-cookies.js';
+export { oncePerRequest } from './request-scope.js';
+export { ACCESS_TOKEN_COOKIE, clearSessionCookies, REFRESH_TOKEN_COOKIE, readAccessTokenCookie, readRefreshTokenCookie, setSessionCookies, } from './session-cookies.js';

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

@@ -0,0 +1,19 @@
+/**
+ * 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 PREVIEW_COOKIE = "byline_preview";
+/** True iff the preview cookie is currently set on the request. */
+export declare function readPreviewCookie(): boolean;
+/**
+ * Write the preview cookie. Callers should ensure the request is from a
+ * valid admin session before invoking — the cookie itself is just a flag
+ * and carries no proof of authorisation. See `enablePreviewModeFn` for
+ * the canonical entry point.
+ */
+export declare function setPreviewCookie(): void;
+/** Clear the preview cookie. Safe to call from any context. */
+export declare function clearPreviewCookie(): void;

package/dist/server/preview-cookies.js

@@ -0,0 +1,69 @@
+/**
+ * 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 the front-end *preview mode* toggle.
+ *
+ * Preview mode lets a signed-in admin see draft (and other non-published)
+ * versions on the public host pages without changing any markup or route
+ * structure. The mechanic is intentionally narrow:
+ *
+ *   - A single httpOnly cookie (`byline_preview=1`) carries the user's
+ *     "show me drafts" intent across requests within the same browser
+ *     session.
+ *   - The cookie's mere *presence* is the signal — there is no payload to
+ *     verify. The actual safety check is the admin session: when the
+ *     viewer client (or a server fn) sees the cookie, it tries to resolve
+ *     `getAdminRequestContext()` and only elevates the read mode when a
+ *     valid admin session resolves. A stale preview cookie on an
+ *     anonymous browser falls through to public/published reads silently.
+ *
+ * Cookie attributes:
+ *   - `httpOnly: true`   — inaccessible to JS; toggled only via server fns.
+ *   - `sameSite: 'lax'`  — sent on top-level navigations only.
+ *   - `secure: true` in production — https-only.
+ *   - `path: '/'`        — visible to every public route.
+ *   - `maxAge: 1 day`    — preview is meant to be a short-lived editorial
+ *                          mode, not a permanent state. Admins can
+ *                          re-enable from the admin UI when needed.
+ *
+ * Cookie transport goes through the registered `HostRequestBridge`, so
+ * this module is host-framework agnostic.
+ */
+import { getHostRequestBridge } from '@byline/core';
+export const PREVIEW_COOKIE = 'byline_preview';
+const PREVIEW_MAX_AGE_SECONDS = 60 * 60 * 24; // 1 day
+const IS_PROD = process.env.NODE_ENV === 'production';
+/** True iff the preview cookie is currently set on the request. */
+export function readPreviewCookie() {
+    return getHostRequestBridge().getCookie(PREVIEW_COOKIE) === '1';
+}
+/**
+ * Write the preview cookie. Callers should ensure the request is from a
+ * valid admin session before invoking — the cookie itself is just a flag
+ * and carries no proof of authorisation. See `enablePreviewModeFn` for
+ * the canonical entry point.
+ */
+export function setPreviewCookie() {
+    getHostRequestBridge().setCookie(PREVIEW_COOKIE, '1', {
+        httpOnly: true,
+        sameSite: 'lax',
+        secure: IS_PROD,
+        path: '/',
+        maxAge: PREVIEW_MAX_AGE_SECONDS,
+    });
+}
+/** Clear the preview cookie. Safe to call from any context. */
+export function clearPreviewCookie() {
+    getHostRequestBridge().setCookie(PREVIEW_COOKIE, '', {
+        httpOnly: true,
+        sameSite: 'lax',
+        secure: IS_PROD,
+        path: '/',
+        maxAge: 0,
+    });
+}

package/dist/server/request-context-contract.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-context-contract.test.node.js

@@ -0,0 +1,114 @@
+/**
+ * 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
+ */
+/**
+ * Cross-layer contract test: a real `BylineClient` wired to the real
+ * cookie-derived request factory (`getAdminRequestContext`) over a fake
+ * `HostRequestBridge`, running two operations that share one
+ * `ReadContext`.
+ *
+ * This is the seam every per-layer suite missed when the admin tree view
+ * broke with 'ReadContext cannot be reused across request authorities':
+ * client tests used stable test contexts, auth tests called the factory
+ * once, and tree tests mocked the handle. Here the factory's
+ * request-stability contract (see `BylineClientConfig.requestContext`)
+ * is exercised end-to-end through the SDK's authority binding.
+ */
+import { AdminAuth } from '@byline/auth';
+import { createReadContext, registerHostRequestBridge } from '@byline/core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+const mocks = vi.hoisted(() => ({
+    verifyAccessToken: vi.fn(),
+    refreshSession: vi.fn(),
+}));
+vi.mock('@byline/core', async () => {
+    const actual = await vi.importActual('@byline/core');
+    return {
+        ...actual,
+        getServerConfig: () => ({
+            sessionProvider: {
+                verifyAccessToken: mocks.verifyAccessToken,
+                refreshSession: mocks.refreshSession,
+            },
+        }),
+    };
+});
+import { createBylineClient } from '../client.js';
+import { getAdminRequestContext } from './admin-context.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(),
+};
+const postsCollection = {
+    path: 'posts',
+    labels: { singular: 'Post', plural: 'Posts' },
+    fields: [{ name: 'title', type: 'text', label: 'Title' }],
+};
+function mockDb() {
+    return {
+        commands: { collections: {}, documents: {}, counters: {} },
+        queries: {
+            collections: {
+                getCollectionByPath: vi.fn().mockResolvedValue({ id: 'col-1', version: 1 }),
+            },
+            documents: {
+                findDocuments: vi.fn().mockResolvedValue({ documents: [], total: 0 }),
+                getDocumentsByDocumentIds: vi.fn().mockResolvedValue([]),
+            },
+        },
+    };
+}
+describe('request factory ↔ client authority contract', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        registerHostRequestBridge(bridge);
+        bridge.getRequest.mockReturnValue(undefined);
+        bridge.getCookie.mockImplementation((name) => name === 'byline_access_token' ? 'valid-access' : undefined);
+        mocks.verifyAccessToken.mockResolvedValue({
+            actor: new AdminAuth({ id: 'admin-1', abilities: ['collections.posts.read'] }),
+        });
+    });
+    afterEach(() => {
+        ;
+        globalThis[BRIDGE_SLOT] = previousBridge;
+    });
+    it('two reads sharing a ReadContext bind one authority within a request', async () => {
+        bridge.getRequest.mockReturnValue({ id: 'request-a' });
+        const db = mockDb();
+        const beforeRead = vi.fn(() => ({ title: 'scoped' }));
+        const client = createBylineClient({
+            db,
+            collections: [{ ...postsCollection, hooks: { beforeRead } }],
+            requestContext: getAdminRequestContext,
+        });
+        const readContext = createReadContext();
+        // The admin tree view shape: two top-level reads, one shared ReadContext.
+        await client.collection('posts').find({ status: 'any', _readContext: readContext });
+        await client.collection('posts').find({ status: 'any', _readContext: readContext });
+        expect(db.queries.documents.findDocuments).toHaveBeenCalledTimes(2);
+        // One session verification and one beforeRead compile for the whole
+        // request — the factory resolved a single request-stable context.
+        expect(mocks.verifyAccessToken).toHaveBeenCalledTimes(1);
+        expect(beforeRead).toHaveBeenCalledTimes(1);
+    });
+    it('still rejects a ReadContext carried across two different requests', async () => {
+        const db = mockDb();
+        const client = createBylineClient({
+            db,
+            collections: [{ ...postsCollection, hooks: { beforeRead: () => ({ title: 'scoped' }) } }],
+            requestContext: getAdminRequestContext,
+        });
+        const readContext = createReadContext();
+        bridge.getRequest.mockReturnValue({ id: 'request-a' });
+        await client.collection('posts').find({ status: 'any', _readContext: readContext });
+        bridge.getRequest.mockReturnValue({ id: 'request-b' });
+        await expect(client.collection('posts').find({ status: 'any', _readContext: readContext })).rejects.toThrow('cannot be reused across request authorities');
+    });
+});

package/dist/server/request-context-factories.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-context-factories.test.node.js

@@ -0,0 +1,116 @@
+/**
+ * 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
+ */
+/**
+ * Direct regression coverage for the public and viewer request-context
+ * factories: both must be request-stable (same instance, same requestId,
+ * for every call within one request) so reads sharing a `ReadContext`
+ * bind a single request authority.
+ */
+import { AdminAuth } from '@byline/auth';
+import { registerHostRequestBridge } from '@byline/core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+const mocks = vi.hoisted(() => ({
+    verifyAccessToken: vi.fn(),
+    refreshSession: vi.fn(),
+}));
+vi.mock('@byline/core', async () => {
+    const actual = await vi.importActual('@byline/core');
+    return {
+        ...actual,
+        getServerConfig: () => ({
+            sessionProvider: {
+                verifyAccessToken: mocks.verifyAccessToken,
+                refreshSession: mocks.refreshSession,
+            },
+        }),
+    };
+});
+import { resolvePublicRequestContext, resolveViewerRequestContext } from './clients.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(),
+};
+function cookiesReturn(values) {
+    bridge.getCookie.mockImplementation((name) => values[name]);
+}
+describe('request-context factories', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        registerHostRequestBridge(bridge);
+        bridge.getRequest.mockReturnValue(undefined);
+        cookiesReturn({});
+    });
+    afterEach(() => {
+        ;
+        globalThis[BRIDGE_SLOT] = previousBridge;
+    });
+    describe('resolvePublicRequestContext', () => {
+        it('returns the same anonymous published context for every call in one request', async () => {
+            bridge.getRequest.mockReturnValue({ id: 'request-a' });
+            const first = await resolvePublicRequestContext();
+            const second = await resolvePublicRequestContext();
+            expect(second).toBe(first);
+            expect(first.actor).toBeNull();
+            expect(first.readMode).toBe('published');
+            expect(second.requestId).toBe(first.requestId);
+        });
+        it('resolves independently across requests', async () => {
+            bridge.getRequest.mockReturnValue({ id: 'request-a' });
+            const first = await resolvePublicRequestContext();
+            bridge.getRequest.mockReturnValue({ id: 'request-b' });
+            const second = await resolvePublicRequestContext();
+            expect(second).not.toBe(first);
+            expect(second.requestId).not.toBe(first.requestId);
+        });
+    });
+    describe('resolveViewerRequestContext', () => {
+        it('returns the same anonymous context per request when no preview cookie is set', async () => {
+            bridge.getRequest.mockReturnValue({ id: 'request-a' });
+            const first = await resolveViewerRequestContext();
+            const second = await resolveViewerRequestContext();
+            expect(second).toBe(first);
+            expect(first.actor).toBeNull();
+            expect(first.readMode).toBe('published');
+        });
+        it('returns the same admin any-mode context per request in preview mode', async () => {
+            bridge.getRequest.mockReturnValue({ id: 'request-a' });
+            cookiesReturn({ byline_preview: '1', byline_access_token: 'valid-access' });
+            const actor = new AdminAuth({ id: 'admin-1', abilities: [] });
+            mocks.verifyAccessToken.mockResolvedValue({ actor });
+            const first = await resolveViewerRequestContext();
+            const second = await resolveViewerRequestContext();
+            expect(second).toBe(first);
+            expect(first.actor).toBe(actor);
+            expect(first.readMode).toBe('any');
+            // The viewer context and the nested admin resolution are both
+            // memoized — one session verification per request, not per call.
+            expect(mocks.verifyAccessToken).toHaveBeenCalledTimes(1);
+        });
+        it('falls back to one stable anonymous context when the preview session is stale', async () => {
+            bridge.getRequest.mockReturnValue({ id: 'request-a' });
+            cookiesReturn({ byline_preview: '1', byline_access_token: 'stale' });
+            mocks.verifyAccessToken.mockRejectedValue(new Error('expired'));
+            const first = await resolveViewerRequestContext();
+            const second = await resolveViewerRequestContext();
+            expect(second).toBe(first);
+            expect(first.actor).toBeNull();
+            expect(first.readMode).toBe('published');
+        });
+        it('resolves independently across requests', async () => {
+            bridge.getRequest.mockReturnValue({ id: 'request-a' });
+            const first = await resolveViewerRequestContext();
+            bridge.getRequest.mockReturnValue({ id: 'request-b' });
+            const second = await resolveViewerRequestContext();
+            expect(second).not.toBe(first);
+            expect(second.requestId).not.toBe(first.requestId);
+        });
+    });
+});

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 {};