@byline/client 5.0.0 → 5.1.0

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

@@ -6,45 +6,13 @@
  * Copyright (c) Infonomic Company Limited
  */
 /**
- * Request-scoped auth context for admin server functions.
+ * Verification-only request context. Renewal belongs to the explicit host endpoint.
  *
- * 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.
+ * oncePerRequest preserves the same context, actor snapshot, and requestId for
+ * every call in one logical request. The read-authorization layer binds each
+ * ReadContext to one authority token including requestId. Generating a new id
+ * per call would make nested reads sharing a ReadContext throw:
+ * "ReadContext cannot be reused across request authorities".
  */
 import { type RequestContext } from '@byline/auth';
 export declare function getAdminRequestContext(): Promise<RequestContext>;

package/dist/server/admin-context.js

@@ -6,120 +6,33 @@
  * Copyright (c) Infonomic Company Limited
  */
 /**
- * Request-scoped auth context for admin server functions.
+ * Verification-only request context. Renewal belongs to the explicit host endpoint.
  *
- * 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.
+ * oncePerRequest preserves the same context, actor snapshot, and requestId for
+ * every call in one logical request. The read-authorization layer binds each
+ * ReadContext to one authority token including requestId. Generating a new id
+ * per call would make nested reads sharing a ReadContext throw:
+ * "ReadContext cannot be reused across request authorities".
  */
-import { ERR_UNAUTHENTICATED } from '@byline/auth';
+import { ERR_ACCESS_EXPIRED, 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();
+import { readAccessTokenCookie, readRefreshTokenCookie } from './session-cookies.js';
+export function getAdminRequestContext() {
+    return oncePerRequest('byline:admin-request-context', async () => {
+        const provider = getServerConfig().sessionProvider;
+        if (!provider)
+            throw new Error('no sessionProvider configured');
+        const access = readAccessTokenCookie();
+        if (!access) {
+            if (readRefreshTokenCookie())
+                throw ERR_ACCESS_EXPIRED({ message: 'access credential absent; explicit renewal required' });
+            throw ERR_UNAUTHENTICATED({ message: 'no admin session' });
         }
-        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',
-    };
+        const { actor, sessionId } = await provider.verifyAccessToken(access);
+        if (!sessionId)
+            throw new Error('session provider omitted login identity');
+        return { actor, sessionId, requestId: uuidv7(), readMode: 'any' };
+    });
 }

package/dist/server/admin-context.test.node.js

@@ -10,7 +10,7 @@
  * `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 { AdminAuth, AuthError, AuthErrorCodes, ERR_ACCESS_EXPIRED, ERR_REVOKED_TOKEN, } from '@byline/auth';
 import { registerHostRequestBridge } from '@byline/core';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 const mocks = vi.hoisted(() => ({
@@ -67,51 +67,30 @@ describe('getAdminRequestContext', () => {
             byline_refresh_token: 'some-refresh',
         });
         const actor = stubActor();
-        verifyAccessToken.mockResolvedValueOnce({ actor });
+        verifyAccessToken.mockResolvedValueOnce({ actor, sessionId: 'test-login' });
         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.each([
+        ERR_ACCESS_EXPIRED({ message: 'expired' }),
+        ERR_REVOKED_TOKEN({ message: 'revoked' }),
+        new Error('database unavailable'),
+    ])('never renews or writes cookies after verification failure: %s', async (error) => {
+        cookiesReturn({ byline_access_token: 'old', byline_refresh_token: 'retained' });
+        verifyAccessToken.mockRejectedValueOnce(error);
+        await expect(getAdminRequestContext()).rejects.toBe(error);
+        expect(refreshSession).not.toHaveBeenCalled();
+        expect(setCookie).not.toHaveBeenCalled();
     });
-    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('reports explicit renewal required when only the persistent refresh cookie survives', async () => {
+        cookiesReturn({ byline_refresh_token: 'retained' });
+        await expect(getAdminRequestContext()).rejects.toMatchObject({ code: 'ERR_ACCESS_EXPIRED' });
+        expect(verifyAccessToken).not.toHaveBeenCalled();
+        expect(refreshSession).not.toHaveBeenCalled();
+        expect(setCookie).not.toHaveBeenCalled();
     });
     it('throws ERR_UNAUTHENTICATED without emitting Set-Cookie when no cookies are sent', async () => {
         cookiesReturn({});
@@ -128,63 +107,6 @@ describe('getAdminRequestContext', () => {
         // 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' });
@@ -192,7 +114,7 @@ describe('getAdminRequestContext', () => {
                 byline_access_token: 'valid-access',
                 byline_refresh_token: 'some-refresh',
             });
-            verifyAccessToken.mockResolvedValue({ actor: stubActor() });
+            verifyAccessToken.mockResolvedValue({ actor: stubActor(), sessionId: 'test-login' });
             const first = await getAdminRequestContext();
             const second = await getAdminRequestContext();
             // Reads sharing a ReadContext bind one request authority; the token
@@ -206,7 +128,7 @@ describe('getAdminRequestContext', () => {
                 byline_access_token: 'valid-access',
                 byline_refresh_token: 'some-refresh',
             });
-            verifyAccessToken.mockResolvedValue({ actor: stubActor() });
+            verifyAccessToken.mockResolvedValue({ actor: stubActor(), sessionId: 'test-login' });
             bridge.getRequest.mockReturnValue({ id: 'request-a' });
             const first = await getAdminRequestContext();
             bridge.getRequest.mockReturnValue({ id: 'request-b' });
@@ -215,42 +137,15 @@ describe('getAdminRequestContext', () => {
             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);
+        it('memoizes expiry without any rotation or cookie write', async () => {
+            bridge.getRequest.mockReturnValue({});
+            cookiesReturn({ byline_access_token: 'expired', byline_refresh_token: 'retained' });
+            verifyAccessToken.mockRejectedValue(ERR_ACCESS_EXPIRED({ message: 'expired' }));
+            await expect(getAdminRequestContext()).rejects.toMatchObject({ code: 'ERR_ACCESS_EXPIRED' });
+            await expect(getAdminRequestContext()).rejects.toMatchObject({ code: 'ERR_ACCESS_EXPIRED' });
+            expect(verifyAccessToken).toHaveBeenCalledOnce();
+            expect(refreshSession).not.toHaveBeenCalled();
+            expect(setCookie).not.toHaveBeenCalled();
         });
     });
 });

package/dist/server/request-context-contract.test.node.js

@@ -73,6 +73,7 @@ describe('request factory ↔ client authority contract', () => {
         bridge.getRequest.mockReturnValue(undefined);
         bridge.getCookie.mockImplementation((name) => name === 'byline_access_token' ? 'valid-access' : undefined);
         mocks.verifyAccessToken.mockResolvedValue({
+            sessionId: 'test-login',
             actor: new AdminAuth({ id: 'admin-1', abilities: ['collections.posts.read'] }),
         });
     });

package/dist/server/request-context-factories.test.node.js

@@ -84,7 +84,7 @@ describe('request-context factories', () => {
             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 });
+            mocks.verifyAccessToken.mockResolvedValue({ actor, sessionId: 'test-login' });
             const first = await resolveViewerRequestContext();
             const second = await resolveViewerRequestContext();
             expect(second).toBe(first);

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/client",
   "private": false,
   "license": "MPL-2.0",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -44,21 +44,21 @@
   ],
   "dependencies": {
     "uuid": "^14.0.2",
-    "@byline/auth": "5.0.0",
-    "@byline/core": "5.0.0"
+    "@byline/auth": "5.1.0",
+    "@byline/core": "5.1.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.10",
-    "@types/node": "^26.4.0",
+    "@biomejs/biome": "2.5.12",
+    "@types/node": "^26.5.0",
     "chokidar": "^5.0.0",
     "chokidar-cli": "^3.0.0",
     "dotenv": "^17.4.2",
     "npm-run-all": "^4.1.5",
-    "tsc-alias": "^1.9.2",
+    "tsc-alias": "^1.9.4",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.11",
-    "@byline/search-postgres": "5.0.0",
-    "@byline/db-postgres": "5.0.0"
+    "vitest": "^5.0.0",
+    "@byline/db-postgres": "5.1.0",
+    "@byline/search-postgres": "5.1.0"
   },
   "publishConfig": {
     "access": "public",