@byline/client 3.21.0 → 4.1.0

package/dist/read-context.js

@@ -0,0 +1,36 @@
+/**
+ * Bind one authenticated request identity to a logical ReadContext without
+ * putting forgeable auth state on the public ReadContext shape. Each operation
+ * gets an immutable clone carrying its effective read mode.
+ */
+import { bindReadContextAuthority, compileBeforeReadFilters } from '@byline/core';
+const readSecurityDomains = new WeakMap();
+export function getReadSecurityDomain(client) {
+    let domain = readSecurityDomains.get(client);
+    if (!domain) {
+        domain = {};
+        readSecurityDomains.set(client, domain);
+    }
+    return domain;
+}
+export async function resolveReadRequestContext(client, readContext, readMode, supplied) {
+    const candidate = supplied ?? (await client.resolveRequestContext());
+    const base = Object.freeze({ ...candidate });
+    bindReadContextAuthority(readContext, base);
+    return { ...base, readMode };
+}
+export function resolveReadSecurityFilters(client, definition, requestContext, readContext, bypass) {
+    if (bypass)
+        return Promise.resolve(undefined);
+    return compileBeforeReadFilters({
+        definition,
+        requestContext,
+        readContext,
+        securityDomain: getReadSecurityDomain(client),
+        parseContext: {
+            collections: client.collections,
+            resolveCollectionId: (path) => client.resolveCollectionId(path),
+            logger: client.logger,
+        },
+    });
+}

package/dist/register.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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
+ */
+import type { CollectionRegistry } from '@byline/core';
+/**
+ * Application type registration point (the TanStack Router / Payload
+ * "Register" pattern). `@byline/core/codegen` appends a declaration-merge
+ * block to the app's generated collection types:
+ *
+ * ```ts
+ * declare module '@byline/client' {
+ *   interface Register {
+ *     collections: CollectionFieldsByPath
+ *   }
+ * }
+ * ```
+ *
+ * Once merged, every bare `BylineClient` in the app's program — including
+ * the getters on `@byline/client/server` — resolves to
+ * `BylineClient<CollectionFieldsByPath>`, so `client.collection('news')`
+ * autocompletes collection paths and returns the generated field shapes
+ * with no per-call generics and no type assertions.
+ *
+ * Exactly one application per TypeScript program can augment this
+ * interface: declaration merging is global to the program, so two apps
+ * sharing a tsconfig project would collide. One app per tsconfig (the
+ * supported layout) is safe.
+ */
+export interface Register {
+}
+/**
+ * The app's registered collection registry, or the loose
+ * `CollectionRegistry` fallback when no augmentation is present. The
+ * fallback keeps unaugmented consumers — downstream apps that haven't
+ * migrated, scripts compiled outside the app program, this package's own
+ * tests — compiling exactly as before.
+ */
+export type RegisteredCollections = Register extends {
+    collections: infer TCollections extends CollectionRegistry;
+} ? TCollections : CollectionRegistry;

package/dist/register.js

@@ -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/search.js

@@ -5,7 +5,8 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { applyBeforeRead, assertActorCanPerform, createReadContext, ERR_VALIDATION, getCollectionAdminConfig, resolveItemViewColumns, resolveSearchZones, } from '@byline/core';
+import { assertActorCanPerform, createReadContext, ERR_VALIDATION, getCollectionAdminConfig, resolveItemViewColumns, resolveSearchZones, } from '@byline/core';
+import { resolveReadRequestContext, resolveReadSecurityFilters } from './read-context.js';
 /**
  * Authorise (and optionally hydrate) provider hits, per collection:
  *
@@ -75,8 +76,8 @@ export async function finalizeSearchHits(params) {
             allowedByCollection.set(collectionPath, null);
             continue;
         }
-        const predicate = await applyBeforeRead({ definition, requestContext, readContext: readCtx });
-        if (predicate == null) {
+        const securityFilters = await resolveReadSecurityFilters(client, definition, requestContext, readCtx);
+        if (securityFilters == null) {
             allowedByCollection.set(collectionPath, null);
             continue;
         }
@@ -143,7 +144,9 @@ export async function zoneSearch(client, options) {
     }
     // Per-member read gate: exclude collections the actor can't read; only
     // when *none* are readable does the ability error surface.
-    const requestContext = await client.resolveRequestContext();
+    const readMode = options.status ?? 'published';
+    const readCtx = createReadContext();
+    const requestContext = await resolveReadRequestContext(client, readCtx, readMode);
     const readable = new Set();
     let firstAbilityError;
     for (const member of members) {
@@ -159,11 +162,22 @@ export async function zoneSearch(client, options) {
     if (readable.size === 0) {
         throw firstAbilityError;
     }
+    let aggregateRestricted = readable.size !== members.length;
+    if (!options._bypassBeforeRead) {
+        for (const member of members) {
+            if (!readable.has(member.path))
+                continue;
+            const securityFilters = await resolveReadSecurityFilters(client, member, requestContext, readCtx);
+            if (securityFilters == null)
+                continue;
+            aggregateRestricted = true;
+        }
+    }
     const results = await provider.search({
         query: options.query,
         zone: options.zone,
         locale: options.locale ?? client.defaultLocale,
-        status: options.status === 'any' ? 'any' : 'published',
+        status: readMode,
         where: options.where,
         facets: options.facets,
         limit: options.limit,
@@ -179,6 +193,9 @@ export async function zoneSearch(client, options) {
         status: options.status,
         hydrate: options.hydrate,
         bypassBeforeRead: options._bypassBeforeRead,
+        readContext: readCtx,
     });
-    return { hits, total: results.total, facets: results.facets };
+    return aggregateRestricted
+        ? { hits, total: hits.length }
+        : { hits, total: results.total, facets: results.facets };
 }

package/dist/server/admin-context.d.ts

@@ -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
+ */
+/**
+ * Request-scoped auth context for admin server functions.
+ *
+ * Reads the session cookies, verifies the access token, transparently
+ * refreshes when needed, and returns a `RequestContext` carrying the
+ * authenticated `AdminAuth`. Every admin server fn calls this as its
+ * first step — it is the single point where the admin transport boundary
+ * meets the actor/ability machinery.
+ *
+ * Flow, in order:
+ *
+ *   1. Read the access cookie.
+ *   2. If present, try `sessionProvider.verifyAccessToken`. On success,
+ *      return the context — no DB write, no cookie churn.
+ *   3. On verify failure (or missing access cookie), read the refresh
+ *      cookie. If present, call `sessionProvider.refreshSession` — this
+ *      rotates the refresh token atomically and issues a new access
+ *      token. Write both fresh cookies to the response.
+ *   4. Verify the new access token (populate the actor) and return the
+ *      context.
+ *   5. Any failure along the way clears both cookies so the browser
+ *      stops sending a session the server has already rejected, and
+ *      throws `ERR_UNAUTHENTICATED`.
+ *
+ * Burns a refresh-token rotation only when the access token actually
+ * fails verification — not on every request. The "one session" UX is
+ * the consequence of this helper working invisibly behind each call.
+ *
+ * Resolution is memoized per request (`oncePerRequest`): every call within
+ * one logical request returns the same `RequestContext` instance — same
+ * actor snapshot, same `requestId`. Two invariants depend on this:
+ *
+ *   - The read-authorization layer binds each `ReadContext` to one
+ *     immutable authority token that includes `requestId`; a fresh id per
+ *     call makes any two reads sharing a `ReadContext` (the admin tree
+ *     view, hook-threaded nested reads) throw
+ *     'ReadContext cannot be reused across request authorities'.
+ *   - The refresh path rotates the refresh token; a second unmemoized call
+ *     in the same request would re-run the dance against the
+ *     already-rotated cookie and sign the admin out.
+ */
+import { type RequestContext } from '@byline/auth';
+export declare function getAdminRequestContext(): Promise<RequestContext>;

package/dist/server/admin-context.js

@@ -0,0 +1,125 @@
+/**
+ * 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
+ */
+/**
+ * Request-scoped auth context for admin server functions.
+ *
+ * Reads the session cookies, verifies the access token, transparently
+ * refreshes when needed, and returns a `RequestContext` carrying the
+ * authenticated `AdminAuth`. Every admin server fn calls this as its
+ * first step — it is the single point where the admin transport boundary
+ * meets the actor/ability machinery.
+ *
+ * Flow, in order:
+ *
+ *   1. Read the access cookie.
+ *   2. If present, try `sessionProvider.verifyAccessToken`. On success,
+ *      return the context — no DB write, no cookie churn.
+ *   3. On verify failure (or missing access cookie), read the refresh
+ *      cookie. If present, call `sessionProvider.refreshSession` — this
+ *      rotates the refresh token atomically and issues a new access
+ *      token. Write both fresh cookies to the response.
+ *   4. Verify the new access token (populate the actor) and return the
+ *      context.
+ *   5. Any failure along the way clears both cookies so the browser
+ *      stops sending a session the server has already rejected, and
+ *      throws `ERR_UNAUTHENTICATED`.
+ *
+ * Burns a refresh-token rotation only when the access token actually
+ * fails verification — not on every request. The "one session" UX is
+ * the consequence of this helper working invisibly behind each call.
+ *
+ * Resolution is memoized per request (`oncePerRequest`): every call within
+ * one logical request returns the same `RequestContext` instance — same
+ * actor snapshot, same `requestId`. Two invariants depend on this:
+ *
+ *   - The read-authorization layer binds each `ReadContext` to one
+ *     immutable authority token that includes `requestId`; a fresh id per
+ *     call makes any two reads sharing a `ReadContext` (the admin tree
+ *     view, hook-threaded nested reads) throw
+ *     'ReadContext cannot be reused across request authorities'.
+ *   - The refresh path rotates the refresh token; a second unmemoized call
+ *     in the same request would re-run the dance against the
+ *     already-rotated cookie and sign the admin out.
+ */
+import { ERR_UNAUTHENTICATED } from '@byline/auth';
+import { getServerConfig } from '@byline/core';
+import { v7 as uuidv7 } from 'uuid';
+import { oncePerRequest } from './request-scope.js';
+import { clearSessionCookies, readAccessTokenCookie, readRefreshTokenCookie, setSessionCookies, } from './session-cookies.js';
+function requireSessionProvider() {
+    const provider = getServerConfig().sessionProvider;
+    if (!provider) {
+        throw new Error('No sessionProvider configured on ServerConfig. ' +
+            'Construct a JwtSessionProvider in your server config and pass it to initBylineCore().');
+    }
+    return provider;
+}
+export async function getAdminRequestContext() {
+    return oncePerRequest('byline:admin-request-context', resolveAdminRequestContext);
+}
+async function resolveAdminRequestContext() {
+    const provider = requireSessionProvider();
+    const accessToken = readAccessTokenCookie();
+    // Happy path: valid access token.
+    if (accessToken) {
+        try {
+            const { actor } = await provider.verifyAccessToken(accessToken);
+            return {
+                actor,
+                requestId: uuidv7(),
+                readMode: 'any',
+            };
+        }
+        catch {
+            // Fall through to refresh — we'll burn a rotation only when the
+            // access token genuinely can't verify.
+        }
+    }
+    // Refresh path: swap the refresh cookie for a fresh token pair.
+    const refreshToken = readRefreshTokenCookie();
+    if (!refreshToken) {
+        // Only emit cookie clears when the browser actually sent a stale access
+        // cookie — otherwise the response carries no Set-Cookie at all, which
+        // lets shared caches (Cloudflare) cache public pages for anonymous
+        // visitors. Set-Cookie on the response is a hard bypass signal for CDNs.
+        if (accessToken) {
+            clearSessionCookies();
+        }
+        throw ERR_UNAUTHENTICATED({ message: 'no admin session' });
+    }
+    let refreshed;
+    try {
+        refreshed = await provider.refreshSession({ refreshToken });
+    }
+    catch (err) {
+        clearSessionCookies();
+        throw ERR_UNAUTHENTICATED({
+            message: 'admin session could not be refreshed',
+            cause: err,
+        });
+    }
+    // Write the new cookies so subsequent requests skip the refresh path.
+    setSessionCookies(refreshed);
+    // Verify the freshly-minted access token to extract the actor.
+    let verified;
+    try {
+        verified = await provider.verifyAccessToken(refreshed.accessToken);
+    }
+    catch (err) {
+        clearSessionCookies();
+        throw ERR_UNAUTHENTICATED({
+            message: 'refreshed access token did not verify',
+            cause: err,
+        });
+    }
+    return {
+        actor: verified.actor,
+        requestId: uuidv7(),
+        readMode: 'any',
+    };
+}

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

@@ -0,0 +1,256 @@
+/**
+ * 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 the admin request-context resolver. Registers a fake
+ * `HostRequestBridge` and mocks the config's `sessionProvider` so the
+ * branches can be exercised without a live Postgres or JWT machinery.
+ */
+import { AdminAuth, AuthError, AuthErrorCodes } 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 { 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 { verifyAccessToken, refreshSession } = mocks;
+const { getCookie, setCookie } = bridge;
+function cookiesReturn(values) {
+    getCookie.mockImplementation((name) => values[name]);
+}
+function stubActor() {
+    return new AdminAuth({
+        id: 'admin-1',
+        abilities: ['collections.pages.read'],
+    });
+}
+describe('getAdminRequestContext', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        registerHostRequestBridge(bridge);
+        // Default: no request in scope, so every call resolves fresh. The
+        // per-request memoization tests below override this with a stable
+        // request object.
+        bridge.getRequest.mockReturnValue(undefined);
+    });
+    afterEach(() => {
+        vi.clearAllMocks();
+        globalThis[BRIDGE_SLOT] = previousBridge;
+    });
+    it('returns the actor directly when the access token verifies', async () => {
+        cookiesReturn({
+            byline_access_token: 'valid-access',
+            byline_refresh_token: 'some-refresh',
+        });
+        const actor = stubActor();
+        verifyAccessToken.mockResolvedValueOnce({ actor });
+        const ctx = await getAdminRequestContext();
+        expect(ctx.actor).toBe(actor);
+        expect(ctx.readMode).toBe('any');
+        expect(refreshSession).not.toHaveBeenCalled();
+        expect(setCookie).not.toHaveBeenCalled();
+    });
+    it('refreshes when the access token fails verification', async () => {
+        cookiesReturn({
+            byline_access_token: 'stale-access',
+            byline_refresh_token: 'valid-refresh',
+        });
+        const actor = stubActor();
+        verifyAccessToken.mockRejectedValueOnce(new Error('expired')).mockResolvedValueOnce({ actor });
+        refreshSession.mockResolvedValueOnce({
+            accessToken: 'fresh-access',
+            refreshToken: 'fresh-refresh',
+            accessTokenExpiresAt: new Date(Date.now() + 15 * 60_000),
+            refreshTokenExpiresAt: new Date(Date.now() + 30 * 24 * 60 * 60_000),
+        });
+        const ctx = await getAdminRequestContext();
+        expect(ctx.actor).toBe(actor);
+        expect(refreshSession).toHaveBeenCalledWith({ refreshToken: 'valid-refresh' });
+        // Both access + refresh cookies should have been written with maxAge > 0.
+        expect(setCookie).toHaveBeenCalledTimes(2);
+        const accessCall = setCookie.mock.calls.find((c) => c[0] === 'byline_access_token');
+        expect(accessCall?.[1]).toBe('fresh-access');
+        expect(accessCall?.[2]?.maxAge).toBeGreaterThan(0);
+    });
+    it('refreshes when the access cookie is missing but a refresh cookie exists', async () => {
+        cookiesReturn({ byline_refresh_token: 'only-refresh' });
+        const actor = stubActor();
+        refreshSession.mockResolvedValueOnce({
+            accessToken: 'fresh-access',
+            refreshToken: 'fresh-refresh',
+            accessTokenExpiresAt: new Date(Date.now() + 15 * 60_000),
+            refreshTokenExpiresAt: new Date(Date.now() + 30 * 24 * 60 * 60_000),
+        });
+        verifyAccessToken.mockResolvedValueOnce({ actor });
+        const ctx = await getAdminRequestContext();
+        expect(ctx.actor).toBe(actor);
+        // The access-token path was skipped (no cookie) so verifyAccessToken ran
+        // only for the freshly-issued token.
+        expect(verifyAccessToken).toHaveBeenCalledTimes(1);
+        expect(verifyAccessToken).toHaveBeenCalledWith('fresh-access');
+    });
+    it('throws ERR_UNAUTHENTICATED without emitting Set-Cookie when no cookies are sent', async () => {
+        cookiesReturn({});
+        try {
+            await getAdminRequestContext();
+            expect.fail('expected ERR_UNAUTHENTICATED');
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(AuthError);
+            expect(err.code).toBe(AuthErrorCodes.UNAUTHENTICATED);
+        }
+        // Anonymous visitors must produce zero Set-Cookie headers so shared
+        // caches (Cloudflare) can cache public pages — a Set-Cookie on the
+        // response is a hard bypass signal for CDNs.
+        expect(setCookie).not.toHaveBeenCalled();
+    });
+    it('clears the stale access cookie when only an access token was sent', async () => {
+        cookiesReturn({ byline_access_token: 'stale' });
+        verifyAccessToken.mockRejectedValueOnce(new Error('expired'));
+        try {
+            await getAdminRequestContext();
+            expect.fail('expected ERR_UNAUTHENTICATED');
+        }
+        catch (err) {
+            expect(err.code).toBe(AuthErrorCodes.UNAUTHENTICATED);
+        }
+        const clears = setCookie.mock.calls.filter((c) => c[2]?.maxAge === 0);
+        const clearedNames = new Set(clears.map((c) => c[0]));
+        expect(clearedNames.has('byline_access_token')).toBe(true);
+        expect(clearedNames.has('byline_refresh_token')).toBe(true);
+    });
+    it('clears cookies and throws when refresh itself fails', async () => {
+        cookiesReturn({
+            byline_access_token: 'stale',
+            byline_refresh_token: 'bad-refresh',
+        });
+        verifyAccessToken.mockRejectedValueOnce(new Error('expired'));
+        refreshSession.mockRejectedValueOnce(new Error('revoked'));
+        try {
+            await getAdminRequestContext();
+            expect.fail('expected ERR_UNAUTHENTICATED');
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(AuthError);
+            expect(err.code).toBe(AuthErrorCodes.UNAUTHENTICATED);
+        }
+        const clears = setCookie.mock.calls.filter((c) => c[2]?.maxAge === 0);
+        expect(clears.length).toBe(2);
+    });
+    it('clears cookies and throws when the refreshed access token fails to verify', async () => {
+        cookiesReturn({
+            byline_access_token: 'stale',
+            byline_refresh_token: 'valid',
+        });
+        verifyAccessToken
+            .mockRejectedValueOnce(new Error('expired'))
+            .mockRejectedValueOnce(new Error('still bad'));
+        refreshSession.mockResolvedValueOnce({
+            accessToken: 'fresh-but-somehow-bad',
+            refreshToken: 'fresh-refresh',
+            accessTokenExpiresAt: new Date(Date.now() + 15 * 60_000),
+            refreshTokenExpiresAt: new Date(Date.now() + 30 * 24 * 60 * 60_000),
+        });
+        try {
+            await getAdminRequestContext();
+            expect.fail('expected ERR_UNAUTHENTICATED');
+        }
+        catch (err) {
+            expect(err.code).toBe(AuthErrorCodes.UNAUTHENTICATED);
+        }
+        const clears = setCookie.mock.calls.filter((c) => c[2]?.maxAge === 0);
+        expect(clears.length).toBe(2);
+    });
+    describe('per-request memoization', () => {
+        it('returns the same context instance — and requestId — for every call in one request', async () => {
+            bridge.getRequest.mockReturnValue({ id: 'request-a' });
+            cookiesReturn({
+                byline_access_token: 'valid-access',
+                byline_refresh_token: 'some-refresh',
+            });
+            verifyAccessToken.mockResolvedValue({ actor: stubActor() });
+            const first = await getAdminRequestContext();
+            const second = await getAdminRequestContext();
+            // Reads sharing a ReadContext bind one request authority; the token
+            // includes requestId, so it must be stable within a request.
+            expect(second).toBe(first);
+            expect(second.requestId).toBe(first.requestId);
+            expect(verifyAccessToken).toHaveBeenCalledTimes(1);
+        });
+        it('resolves independently across different requests', async () => {
+            cookiesReturn({
+                byline_access_token: 'valid-access',
+                byline_refresh_token: 'some-refresh',
+            });
+            verifyAccessToken.mockResolvedValue({ actor: stubActor() });
+            bridge.getRequest.mockReturnValue({ id: 'request-a' });
+            const first = await getAdminRequestContext();
+            bridge.getRequest.mockReturnValue({ id: 'request-b' });
+            const second = await getAdminRequestContext();
+            expect(second).not.toBe(first);
+            expect(second.requestId).not.toBe(first.requestId);
+            expect(verifyAccessToken).toHaveBeenCalledTimes(2);
+        });
+        it('burns at most one refresh rotation per request', async () => {
+            bridge.getRequest.mockReturnValue({ id: 'request-a' });
+            cookiesReturn({
+                byline_access_token: 'stale-access',
+                byline_refresh_token: 'valid-refresh',
+            });
+            const actor = stubActor();
+            verifyAccessToken.mockRejectedValueOnce(new Error('expired')).mockResolvedValueOnce({ actor });
+            refreshSession.mockResolvedValueOnce({
+                accessToken: 'fresh-access',
+                refreshToken: 'fresh-refresh',
+                accessTokenExpiresAt: new Date(Date.now() + 15 * 60_000),
+                refreshTokenExpiresAt: new Date(Date.now() + 30 * 24 * 60 * 60_000),
+            });
+            const first = await getAdminRequestContext();
+            // A second unmemoized call would re-run the refresh dance against the
+            // request's stale cookie — now already rotated — and sign the admin out.
+            const second = await getAdminRequestContext();
+            expect(second).toBe(first);
+            expect(refreshSession).toHaveBeenCalledTimes(1);
+        });
+        it('memoizes the unauthenticated rejection within one request', async () => {
+            bridge.getRequest.mockReturnValue({ id: 'request-a' });
+            cookiesReturn({
+                byline_access_token: 'stale',
+                byline_refresh_token: 'bad-refresh',
+            });
+            verifyAccessToken.mockRejectedValue(new Error('expired'));
+            refreshSession.mockRejectedValue(new Error('revoked'));
+            await expect(getAdminRequestContext()).rejects.toMatchObject({
+                code: AuthErrorCodes.UNAUTHENTICATED,
+            });
+            await expect(getAdminRequestContext()).rejects.toMatchObject({
+                code: AuthErrorCodes.UNAUTHENTICATED,
+            });
+            expect(refreshSession).toHaveBeenCalledTimes(1);
+        });
+    });
+});

package/dist/server/browser.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/browser.js

@@ -0,0 +1,18 @@
+/**
+ * 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
+ */
+/**
+ * Browser-condition stub for `@byline/client/server`. Bundlers that
+ * resolve the `browser` export condition land here instead of the real
+ * server entry, so an accidental import from client-side code fails
+ * loudly at load time instead of shipping session machinery to the
+ * browser.
+ */
+throw new Error('@byline/client/server is server-only. Import it from server routes, ' +
+    'loaders, server functions, scripts, or lifecycle hooks — never from ' +
+    'browser code.');
+export {};