@byline/client 4.0.0 → 4.1.0

package/dist/client.d.ts

@@ -8,13 +8,14 @@
 import { type RequestContext } from '@byline/auth';
 import type { BylineLogger, CollectionDefinition, CollectionRegistry, IDbAdapter, IStorageProvider, RichTextPopulateFn, RichTextToTextFn, SearchProvider, SlugifierFn } from '@byline/core';
 import { CollectionHandle } from './collection-handle.js';
+import type { RegisteredCollections } from './register.js';
 import type { BylineClientConfig, ClientSearchResults, ZoneSearchOptions } from './types.js';
 /**
  * The main Byline client instance. Holds the database adapter, collection
  * definitions, and optional storage provider. Use `collection(path)` to get
  * a scoped handle for querying and mutating documents.
  */
-export declare class BylineClient<TRegistry extends CollectionRegistry = CollectionRegistry> {
+export declare class BylineClient<TRegistry extends CollectionRegistry = RegisteredCollections> {
     readonly db: IDbAdapter;
     readonly collections: readonly CollectionDefinition[];
     readonly storage: IStorageProvider | undefined;
@@ -71,6 +72,8 @@ export declare class BylineClient<TRegistry extends CollectionRegistry = Collect
     resolveCollectionId(path: string): Promise<string>;
 }
 /**
- * Create a new Byline client instance.
+ * Create a new Byline client instance. The registry generic defaults to
+ * `RegisteredCollections`, so in an app whose generated types augment
+ * `Register` the returned client is fully typed with no explicit generic.
  */
-export declare function createBylineClient<TRegistry extends CollectionRegistry = CollectionRegistry>(config: BylineClientConfig): BylineClient<TRegistry>;
+export declare function createBylineClient<TRegistry extends CollectionRegistry = RegisteredCollections>(config: BylineClientConfig): BylineClient<TRegistry>;

package/dist/client.js

@@ -174,7 +174,9 @@ export class BylineClient {
     }
 }
 /**
- * Create a new Byline client instance.
+ * Create a new Byline client instance. The registry generic defaults to
+ * `RegisteredCollections`, so in an app whose generated types augment
+ * `Register` the returned client is fully typed with no explicit generic.
  */
 export function createBylineClient(config) {
     return new BylineClient(config);

package/dist/index.d.ts

@@ -8,4 +8,5 @@
 export { type AuditLogEntry, type AuditLogPage, type ChangeStatusResult, type CreateDocumentResult, type CycleRelationValue, createReadContext, type DeleteDocumentResult, ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION, type PopulatedRelationValue, type PopulateFieldOptions, type PopulateFieldSpec, type PopulateMap, type PopulateSpec, type ReadContext, type ReadMode, type RestoreVersionResult, type UnpublishResult, type UnresolvedRelationValue, type UpdateDocumentResult, } from '@byline/core';
 export { BylineClient, createBylineClient } from './client.js';
 export { CollectionHandle } from './collection-handle.js';
+export type { Register, RegisteredCollections } from './register.js';
 export type { AuditLogOptions, BylineClientConfig, ClientDocument, ClientSearchResults, CollectionSearchOptions, CreateOptions, FilterOperators, FindByIdOptions, FindByPathOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeOptions, GetTreeParentOptions, HydratedSearchHit, PlaceTreeNodeOptions, PopulatedRelation, ReindexResult, RemoveFromTreeOptions, SearchFacetBucket, SearchHit, SearchResults, SortDirection, SortSpec, TreeNode, TreeParentResult, UpdateOptions, WhereClause, WhereValue, WithPopulated, WithPopulatedMany, ZoneSearchOptions, } from './types.js';

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

package/dist/server/clients.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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 { type RequestContext } from '@byline/auth';
+import { type BylineClient } from '../client.js';
+export declare function getAdminBylineClient(): BylineClient;
+export declare function getSystemBylineClient(): BylineClient;
+/**
+ * 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 declare function resolvePublicRequestContext(): Promise<RequestContext>;
+export declare function getPublicBylineClient(): BylineClient;
+/**
+ * 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 declare function resolveViewerRequestContext(): Promise<RequestContext>;
+export declare function getViewerBylineClient(): BylineClient;
+/**
+ * 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 declare function isPreviewActive(): Promise<boolean>;