cabloy 5.1.243 → 5.1.245

package/vona/src/suite/a-home/modules/home-user/test/passportSession.test.ts

@@ -0,0 +1,380 @@
+import type { IJwtToken, IPayloadData } from 'vona-module-a-jwt';
+import type { IAuthTokenConfig, TypeAuthTokenMode } from 'vona-module-a-user';
+
+import assert from 'node:assert/strict';
+import { describe, it, mock } from 'node:test';
+import { app } from 'vona-mock';
+import { $getAuthTokenMode, $parseAuthTokenMode } from 'vona-module-a-user';
+
+interface ITestPayloadData extends IPayloadData {
+  token: string;
+}
+
+interface IFixture {
+  userId: string;
+  authId: string;
+  name: string;
+}
+
+const unauthorized = (error: { code?: number }) => error.code === 401;
+
+describe('passportSession.test.ts', { concurrency: false }, () => {
+  it('defaults to auth and rejects invalid modes, stateless sessions and reissue refresh', async () => {
+    assert.equal($parseAuthTokenMode(undefined), 'auth');
+    for (const mode of ['auth', 'session'] as const) {
+      assert.equal($parseAuthTokenMode(mode), mode);
+    }
+    for (const value of ['', 'Session', 'all', null, true, 1]) {
+      assert.throws(() => $parseAuthTokenMode(value), /auth or session/);
+    }
+    await withMode(undefined, async () => {
+      const config = app.ctx.config.modules['a-user'].authToken;
+      assert.equal($getAuthTokenMode(config), 'auth');
+      assert.equal(app.bean.passport.authTokenMode, 'auth');
+    });
+    await withMode('session', async () => {
+      const config = app.ctx.config.modules['a-user'].authToken;
+      assert.equal($getAuthTokenMode(config), 'session');
+      assert.equal(app.bean.passport.authTokenMode, 'session');
+      assert.throws(() => $getAuthTokenMode({ ...config, stateless: true }), /stateful/);
+      assert.throws(
+        () =>
+          $getAuthTokenMode({
+            ...config,
+            strategy: { ...config.strategy, refreshAuthToken: 'reissue' },
+          }),
+        /reissue/,
+      );
+    });
+    await withMode(
+      'session',
+      async () => {
+        assert.throws(() => app.bean.passport.authTokenMode, /stateful/);
+      },
+      { stateless: true },
+    );
+    await withMode(
+      'session',
+      async () => {
+        assert.throws(() => app.bean.passport.authTokenMode, /reissue/);
+      },
+      { strategy: { signin: 'refresh', refreshAuthToken: 'reissue' } },
+    );
+  });
+
+  it('auth mode keeps the shared credential token and logout revokes both logins', async () => {
+    await withFixture(async fixture => {
+      const a = await login('auth', fixture);
+      const b = await login('auth', fixture);
+      const payloadA = await verify('auth', a.accessToken);
+      const payloadB = await verify('auth', b.accessToken);
+      assert.equal(payloadA.token, payloadB.token);
+      await logout('auth', a.accessToken);
+      await rejectedPair('auth', a);
+      await rejectedPair('auth', b);
+    });
+  });
+
+  it('session logins are independent; refresh, reuse and derived tokens retain their session', async () => {
+    await withFixture(async fixture => {
+      const a = await login('session', fixture);
+      const b = await login('session', fixture);
+      const payloadA = await verify('session', a.accessToken);
+      const payloadB = await verify('session', b.accessToken);
+      assert.match(
+        payloadA.token,
+        /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+      );
+      assert.notEqual(payloadA.token, payloadB.token);
+      await withMode('session', async () => {
+        const cache = app.scope('a-user').cacheRedis.authToken;
+        assert.equal(
+          await cache.get(`${fixture.userId}:${fixture.authId}:${payloadA.token}`),
+          payloadA.token,
+        );
+        assert.equal(
+          await cache.get(`${fixture.userId}:${fixture.authId}:${payloadB.token}`),
+          payloadB.token,
+        );
+      });
+      let refreshed = a;
+      for (const strategy of ['refresh', 'reuse'] as const) {
+        refreshed = await withMode(
+          'session',
+          async () => {
+            const jwt = await app.bean.passport.refreshAuthToken(refreshed.refreshToken);
+            assert.equal(
+              (app.ctx.state.passportPayloadData as ITestPayloadData | undefined)?.token,
+              payloadA.token,
+            );
+            return jwt;
+          },
+          { strategy: { signin: 'refresh', refreshAuthToken: strategy } },
+        );
+        assert.equal((await verify('session', refreshed.accessToken)).token, payloadA.token);
+        assert.equal(
+          (await verify('session', refreshed.refreshToken, 'refresh')).token,
+          payloadA.token,
+        );
+      }
+      const derived: [string, 'access' | 'oauth' | 'code'][] = [];
+      for (const create of [
+        () => app.bean.passport.createTempAuthToken(),
+        () => app.bean.passport.createOauthAuthToken(),
+        () => app.bean.passport.createOauthCode(),
+        () => app.bean.passport.createOauthCodeFromOauthAuthToken(a.accessToken),
+      ]) {
+        const token = await withMode('session', async () => {
+          await app.bean.passport.checkAuthToken(a.accessToken);
+          return await create();
+        });
+        derived.push([
+          token,
+          derived.length === 1 ? 'oauth' : derived.length >= 2 ? 'code' : 'access',
+        ]);
+      }
+      for (const [token, client] of derived) {
+        assert.equal((await verify('session', token, client)).token, payloadA.token);
+      }
+      const exchanged = await withMode('session', () =>
+        app.bean.passport.createAuthTokenFromOauthCode(derived[2][0]),
+      );
+      assert.equal((await verify('session', exchanged.accessToken)).token, payloadA.token);
+      await logout('session', refreshed.accessToken);
+      await rejectedPair('session', a);
+      await rejectedPair('session', refreshed);
+      await rejectedPair('session', exchanged);
+      for (const [token, client] of derived) {
+        await withMode('session', () =>
+          assert.rejects(() => app.bean.passport.checkAuthToken(token, client), unauthorized),
+        );
+      }
+      await withMode('session', () =>
+        assert.rejects(
+          () => app.bean.passport.createAuthTokenFromOauthCode(derived[2][0]),
+          unauthorized,
+        ),
+      );
+      await withMode('session', () =>
+        assert.rejects(
+          () => app.bean.passport.createOauthCodeFromOauthAuthToken(a.accessToken),
+          unauthorized,
+        ),
+      );
+      await verify('session', b.accessToken);
+      await verify('session', b.refreshToken, 'refresh');
+    });
+  });
+
+  it('logout at the refresh boundary cannot resurrect a deleted session', async () => {
+    await withFixture(async fixture => {
+      const a = await login('session', fixture);
+      const b = await login('session', fixture);
+      const refreshed = await withMode('session', async () => {
+        const redisToken = app.scope('a-user').service.redisToken;
+        const refresh = redisToken.refresh.bind(redisToken);
+        const boundary = mock.method(
+          redisToken,
+          'refresh',
+          async (payload: IPayloadData, ttl?: number) => {
+            // A separate request deletes the record after verification, before TTL extension.
+            await logout('session', a.accessToken);
+            await refresh(payload, ttl);
+          },
+        );
+        try {
+          const jwt = await app.bean.passport.refreshAuthToken(a.refreshToken);
+          assert.equal(boundary.mock.callCount(), 1);
+          return jwt;
+        } finally {
+          boundary.mock.restore();
+        }
+      });
+      await rejectedPair('session', a);
+      await rejectedPair('session', refreshed);
+      await verify('session', b.accessToken);
+      await verify('session', b.refreshToken, 'refresh');
+    });
+  });
+
+  it('requires verified payload state for session signout and rejects effective stateless overrides', async () => {
+    await withFixture(async fixture => {
+      const jwt = await login('session', fixture);
+      await withMode('session', async () => {
+        const verified = await app.bean.passport.checkAuthToken(jwt.accessToken);
+        assert.ok(verified);
+        assert.equal(app.ctx.state.passportPayloadData, verified.payloadData);
+        await app.bean.passport.setCurrent(verified.passport);
+        assert.equal(app.ctx.state.passportPayloadData, undefined);
+        await assert.rejects(() => app.bean.passport.signout(), unauthorized);
+      });
+      await verify('session', jwt.accessToken);
+      await withMode('session', async () => {
+        const verified = await app.bean.passport.checkAuthToken(jwt.accessToken);
+        assert.ok(verified);
+        await assert.rejects(
+          () => app.bean.passport.signin(verified.passport, { authToken: { stateless: true } }),
+          /stateful/,
+        );
+      });
+      await withMode('session', () =>
+        assert.rejects(
+          () =>
+            app.bean.auth.authenticate('auth-simple:simple', {
+              clientName: 'default',
+              state: { intention: 'login' },
+              clientOptions: {
+                username: fixture.name,
+                password: 'initial-password',
+                authTokenOptions: { stateless: true },
+              },
+            }),
+          /stateful/,
+        ),
+      );
+    });
+  });
+
+  it('kickOut removes all user token shapes independently of mode without prefix collisions', async () => {
+    await withFixture(async fixture => {
+      const a = await login('session', fixture);
+      const b = await login('session', fixture);
+      const auth = await login('auth', fixture);
+      const keys = [
+        `${fixture.userId}:owned-auth`,
+        `${fixture.userId}:owned-auth:owned-session`,
+        `${fixture.userId}0:owned-auth:neighbor`,
+      ];
+      try {
+        await withMode('session', async () => {
+          const cache = app.scope('a-user').cacheRedis.authToken;
+          for (const key of keys) await cache.set('owned-token', key);
+        });
+        await withMode('auth', async () => {
+          const user = await app.bean.user.findOneById(fixture.userId);
+          assert.ok(user);
+          await app.bean.passport.kickOut(user);
+        });
+        await rejectedPair('session', a);
+        await rejectedPair('session', b);
+        await rejectedPair('auth', auth);
+        await withMode('session', async () => {
+          const cache = app.scope('a-user').cacheRedis.authToken;
+          assert.equal(await cache.get(keys[0]), undefined);
+          assert.equal(await cache.get(keys[1]), undefined);
+          assert.equal(await cache.get(keys[2]), 'owned-token');
+        });
+      } finally {
+        await withMode('session', async () => {
+          for (const key of keys) await app.scope('a-user').cacheRedis.authToken.del(key);
+        });
+      }
+    });
+  });
+});
+
+async function withMode<T>(
+  mode: TypeAuthTokenMode | undefined,
+  callback: () => Promise<T>,
+  overrides: Partial<IAuthTokenConfig> = {},
+): Promise<T> {
+  return await app.bean.executor.mockCtx(async () => {
+    const config = app.ctx.config;
+    Object.defineProperty(app.ctx, 'config', {
+      configurable: true,
+      value: {
+        ...config,
+        modules: {
+          ...config.modules,
+          'a-user': {
+            ...config.modules['a-user'],
+            authToken: { ...config.modules['a-user'].authToken, mode, ...overrides },
+          },
+        },
+      },
+    });
+    return await callback();
+  });
+}
+
+async function login(mode: TypeAuthTokenMode, fixture: IFixture): Promise<IJwtToken> {
+  return await withMode(mode, async () => {
+    const jwt = await app.bean.auth.authenticate('auth-simple:simple', {
+      clientName: 'default',
+      state: { intention: 'login' },
+      clientOptions: { username: fixture.name, password: 'initial-password' },
+    });
+    assert.ok(jwt);
+    assert.ok((app.ctx.state.passportPayloadData as ITestPayloadData | undefined)?.token);
+    return jwt;
+  });
+}
+
+async function verify(
+  mode: TypeAuthTokenMode,
+  token: string,
+  client: 'access' | 'refresh' | 'oauth' | 'code' = 'access',
+): Promise<ITestPayloadData> {
+  return await withMode(mode, async () => {
+    const verified = await app.bean.passport.checkAuthToken(token, client);
+    assert.ok(verified);
+    assert.equal(app.ctx.state.passportPayloadData, verified.payloadData);
+    return verified.payloadData as ITestPayloadData;
+  });
+}
+
+async function rejectedPair(mode: TypeAuthTokenMode, jwt: IJwtToken) {
+  await withMode(mode, () =>
+    assert.rejects(() => app.bean.passport.checkAuthToken(jwt.accessToken), unauthorized),
+  );
+  await withMode(mode, () =>
+    assert.rejects(() => app.bean.passport.refreshAuthToken(jwt.refreshToken), unauthorized),
+  );
+}
+
+async function logout(mode: TypeAuthTokenMode, accessToken: string) {
+  await withMode(mode, async () => {
+    await app.bean.passport.checkAuthToken(accessToken);
+    await app.bean.passport.signout();
+    assert.equal(app.ctx.state.passportPayloadData, undefined);
+    assert.equal(app.bean.passport.current, undefined);
+  });
+}
+
+async function withFixture(callback: (fixture: IFixture) => Promise<void>) {
+  let userId: string | undefined;
+  let authSimpleId: string | undefined;
+  try {
+    const fixture = await app.bean.executor.mockCtx(async () => {
+      const name = `passport-session-${crypto.randomUUID()}`;
+      const user = await app.bean.user.register({ name }, true);
+      userId = user.id.toString();
+      const authSimple = await app
+        .scope('auth-simple')
+        .service.authSimple.createForUser(user.id, 'initial-password');
+      assert.ok(authSimple);
+      authSimpleId = authSimple.id.toString();
+      const provider = await app.bean.authProvider.get({
+        providerName: 'auth-simple:simple',
+        clientName: 'default',
+      });
+      const auth = await app
+        .scope('a-auth')
+        .model.auth.get({ userId: user.id, authProviderId: provider.id });
+      assert.ok(auth);
+      return { userId, authId: auth.id.toString(), name };
+    });
+    await callback(fixture);
+  } finally {
+    if (userId) {
+      await app.bean.executor.mockCtx(async () => {
+        const user = await app.bean.user.findOneById(userId!);
+        if (user) await app.bean.passport.kickOut(user);
+        await app.scope('a-auth').model.auth.delete({ userId });
+        if (authSimpleId) await app.scope('auth-simple').model.authSimple.deleteById(authSimpleId);
+        await app.scope('home-user').model.roleUser.delete({ userId });
+        await app.bean.user.removeById(userId!);
+      });
+    }
+  }
+}

package/vona/src/suite-vendor/a-cabloy/modules/a-rbac/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-module-a-rbac",
-  "version": "5.0.18",
+  "version": "5.0.19",
   "description": "",
   "keywords": [
     "Vona Module"

package/vona/src/suite-vendor/a-cabloy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-suite-a-cabloy",
-  "version": "5.1.70",
+  "version": "5.1.71",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "",
   "author": "",
@@ -10,7 +10,7 @@
     "vona-module-a-cabloy": "workspace:^",
     "vona-module-a-layoutprofile": "^5.0.2",
     "vona-module-a-markdown": "^5.0.3",
-    "vona-module-a-rbac": "^5.0.18",
+    "vona-module-a-rbac": "^5.0.19",
     "vona-module-a-socket": "workspace:^",
     "vona-module-a-ssr": "workspace:^",
     "vona-module-a-ssrhmr": "workspace:^"

package/vona/src/suite-vendor/a-vona/modules/a-openapiutils/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-module-a-openapiutils",
-  "version": "5.1.23",
+  "version": "5.1.24",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "",
   "keywords": [

package/vona/src/suite-vendor/a-vona/modules/a-openapiutils/src/lib/decorator/mcp.ts

@@ -11,7 +11,7 @@ function tool(options: IMcpToolOptions): MethodDecorator;
 function tool(options: IMcpToolOptions = {}): ClassDecorator & MethodDecorator {
   return function (target: object, prop?: MetadataKey, descriptor?: PropertyDescriptor) {
     if (prop === undefined && options.name !== undefined) {
-      throw new Error('mcp.tool name is only valid on a controller action');
+      throw new Error('Mcp.tool name is only valid on a controller action');
     }
     // An options object, including an empty one, is the explicit opt-in marker.
     const metadata = appMetadata.getOwnMetadataMap(
@@ -25,4 +25,4 @@ function tool(options: IMcpToolOptions = {}): ClassDecorator & MethodDecorator {
   } as ClassDecorator & MethodDecorator;
 }
 
-export const mcp = { tool };
+export const Mcp = { tool };

package/vona/src/suite-vendor/a-vona/modules/a-permission/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-module-a-permission",
-  "version": "5.1.35",
+  "version": "5.1.36",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "",
   "keywords": [

package/vona/src/suite-vendor/a-vona/modules/a-user/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-module-a-user",
-  "version": "5.1.26",
+  "version": "5.1.27",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "",
   "keywords": [

package/vona/src/suite-vendor/a-vona/modules/a-user/src/bean/bean.passport.ts

@@ -10,13 +10,19 @@ import { catchError, isNil } from '@cabloy/utils';
 import { BeanBase, beanFullNameFromOnionName } from 'vona';
 import { Bean } from 'vona-module-a-bean';
 
-import type { IAuth, IAuthIdRecord, IAuthTokenOptions, ISigninOptions } from '../types/auth.ts';
+import type {
+  IAuth,
+  IAuthIdRecord,
+  IAuthTokenOptions,
+  ISigninOptions,
+  TypeAuthTokenMode,
+} from '../types/auth.ts';
 import type { IAuthTokenAdapter } from '../types/authToken.ts';
 import type { IPassport, IPassportAdapter } from '../types/passport.ts';
 import type { IRole, IRoleNameRecord } from '../types/role.ts';
 import type { IUser, IUserNameRecord } from '../types/user.ts';
 
-import { $getAuthIdSystem } from '../lib/auth.ts';
+import { $getAuthIdSystem, $getAuthTokenMode } from '../lib/auth.ts';
 
 @Bean()
 export class BeanPassport extends BeanBase {
@@ -43,6 +49,10 @@ export class BeanPassport extends BeanBase {
     return this._passportAdapter;
   }
 
+  public get authTokenMode(): TypeAuthTokenMode {
+    return $getAuthTokenMode(this.scope.config.authToken);
+  }
+
   public get isAuthenticated(): boolean {
     const user = this.currentUser;
     return !!user && !user.anonymous;
@@ -71,6 +81,7 @@ export class BeanPassport extends BeanBase {
   }
 
   public async setCurrent(passport: IPassport | undefined) {
+    this.ctx.state.passportPayloadData = undefined;
     this.ctx.state.passport = await this.passportAdapter.setCurrent(passport);
   }
 
@@ -107,9 +118,13 @@ export class BeanPassport extends BeanBase {
         ttl: this.scope.config.authToken.ttl,
       },
     );
-    const payloadData = await this._passportSerialize(passport, authTokenOptions);
+    const payloadData = await this._passportSerialize(passport, authTokenOptions, true);
     // jwt token
-    return await this.bean.jwt.create(payloadData, { dev: passport.auth?.id.toString() === '-1' });
+    const jwt = await this.bean.jwt.create(payloadData, {
+      dev: passport.auth?.id.toString() === '-1',
+    });
+    this.ctx.state.passportPayloadData = payloadData;
+    return jwt;
   }
 
   public async signout(): Promise<void> {
@@ -117,7 +132,10 @@ export class BeanPassport extends BeanBase {
     const passport = this.current;
     if (!passport) return;
     // removeAuthToken
-    const payloadData = await this.passportAdapter.serialize(passport);
+    const payloadData =
+      this.authTokenMode === 'session'
+        ? this._getCurrentPayloadData()
+        : await this.passportAdapter.serialize(passport);
     await this.authTokenAdapter.remove(payloadData);
     // event
     await this.scope.event.signout.emit(passport);
@@ -191,6 +209,7 @@ export class BeanPassport extends BeanBase {
     }
     // setCurrent
     await this.setCurrent(passport);
+    this.ctx.state.passportPayloadData = payloadData;
     return { payloadData, passport };
   }
 
@@ -211,7 +230,9 @@ export class BeanPassport extends BeanBase {
     );
     payloadData = await this._handlePayloadData(payloadData, authTokenOptions);
     // jwt token
-    return await this.bean.jwt.create(payloadData);
+    const jwt = await this.bean.jwt.create(payloadData);
+    this.ctx.state.passportPayloadData = payloadData;
+    return jwt;
   }
 
   // only created by accessToken
@@ -247,7 +268,10 @@ export class BeanPassport extends BeanBase {
 
   public async createOauthCodeFromOauthAuthToken(accessToken: string, options?: IJwtSignOptions) {
     // payloadData
-    const payloadData = await this.bean.jwt.get('access').verify(accessToken);
+    const payloadData =
+      this.authTokenMode === 'session'
+        ? (await this.checkAuthToken(accessToken))?.payloadData
+        : await this.bean.jwt.get('access').verify(accessToken);
     if (!payloadData) return this.app.throw(401);
     // code
     return await this.bean.jwt.createOauthCode(payloadData, options);
@@ -282,7 +306,24 @@ export class BeanPassport extends BeanBase {
     return true;
   }
 
-  private async _passportSerialize(passport: IPassport, authTokenOptions?: IAuthTokenOptions) {
+  private _getCurrentPayloadData(): IPayloadData {
+    const payloadData = this.ctx.state.passportPayloadData;
+    if (!payloadData?.[this.scope.config.payloadData.fields.token]) return this.app.throw(401);
+    return payloadData;
+  }
+
+  private async _passportSerialize(
+    passport: IPassport,
+    authTokenOptions?: IAuthTokenOptions,
+    signin = false,
+  ) {
+    if (this.authTokenMode === 'session') {
+      if (signin) {
+        const payloadData = await this.passportAdapter.serialize(passport);
+        return await this.authTokenAdapter.create(payloadData, authTokenOptions?.ttl);
+      }
+      return await this._handlePayloadData(this._getCurrentPayloadData(), authTokenOptions);
+    }
     // serialize
     const payloadData = await this.passportAdapter.serialize(passport);
     return await this._handlePayloadData(payloadData, authTokenOptions);
@@ -296,6 +337,18 @@ export class BeanPassport extends BeanBase {
     const stateless = authTokenOptions?.stateless;
     const strategy = authTokenOptions?.strategy ?? 'refresh';
     const ttl = authTokenOptions?.ttl;
+    if (this.authTokenMode === 'session') {
+      if (stateless) throw new Error('Session auth-token mode requires stateful authentication');
+      if (strategy === 'reissue') {
+        throw new Error('Session auth-token mode does not support the reissue refresh strategy');
+      }
+      const verified = await this.authTokenAdapter.verify(payloadData);
+      if (!verified) return this.app.throw(401);
+      if (strategy === 'refresh') {
+        await this.authTokenAdapter.refresh(payloadData, ttl);
+      }
+      return payloadData;
+    }
     if (stateless) {
       // do nothing
       return payloadData;
@@ -320,17 +373,26 @@ export class BeanPassport extends BeanBase {
     authTokenOptionsCustom: IAuthTokenOptions | undefined,
     authTokenOptionsDefault: IAuthTokenOptions,
   ) {
-    if (!authProviderId) return authTokenOptionsDefault;
-    const { clientOptions } = await this.bean.authProvider.getClientOptions(
-      {
-        id: authProviderId,
-      },
-      { authTokenOptions: authTokenOptionsCustom ?? {} },
-      {
-        authTokenOptions: authTokenOptionsDefault,
-      },
-    );
-    if (!clientOptions) this.app.throw(403);
-    return clientOptions.authTokenOptions!;
+    let authTokenOptions = authTokenOptionsDefault;
+    if (this.authTokenMode === 'session') {
+      authTokenOptions = { ...authTokenOptions, ...authTokenOptionsCustom };
+    }
+    if (authProviderId) {
+      const { clientOptions } = await this.bean.authProvider.getClientOptions(
+        {
+          id: authProviderId,
+        },
+        { authTokenOptions: authTokenOptionsCustom ?? {} },
+        {
+          authTokenOptions: authTokenOptionsDefault,
+        },
+      );
+      if (!clientOptions) this.app.throw(403);
+      authTokenOptions = clientOptions.authTokenOptions!;
+    }
+    if (this.authTokenMode === 'session' && authTokenOptions.stateless) {
+      throw new Error('Session auth-token mode requires stateful authentication');
+    }
+    return authTokenOptions;
   }
 }

package/vona/src/suite-vendor/a-vona/modules/a-user/src/config/config.ts

@@ -2,12 +2,15 @@ import type { VonaApplication } from 'vona';
 
 import type { ConfigUser } from '../types/auth.ts';
 
-export function config(_app: VonaApplication) {
+import { $parseAuthTokenMode } from '../lib/auth.ts';
+
+export function config(app: VonaApplication) {
   const configUser: ConfigUser = {
     user: {
       autoActivate: false,
     },
     authToken: {
+      mode: $parseAuthTokenMode(app.meta.env.AUTH_TOKEN_MODE),
       stateless: false,
       strategy: {
         refreshAuthToken: 'refresh',

package/vona/src/suite-vendor/a-vona/modules/a-user/src/lib/auth.ts

@@ -1,6 +1,25 @@
 import type { TableIdentity } from 'table-identity';
 
-import type { IAuthIdRecord } from '../types/auth.ts';
+import type { IAuthIdRecord, IAuthTokenConfig, TypeAuthTokenMode } from '../types/auth.ts';
+
+export function $parseAuthTokenMode(value: unknown): TypeAuthTokenMode {
+  if (value === undefined) return 'auth';
+  if (value === 'auth' || value === 'session') return value;
+  throw new Error('AUTH_TOKEN_MODE / authToken.mode must be auth or session');
+}
+
+export function $getAuthTokenMode(config: IAuthTokenConfig): TypeAuthTokenMode {
+  const mode = $parseAuthTokenMode(config.mode);
+  if (mode === 'session') {
+    if (config.stateless) {
+      throw new Error('Session auth-token mode requires stateful authentication');
+    }
+    if (config.strategy.refreshAuthToken === 'reissue') {
+      throw new Error('Session auth-token mode does not support the reissue refresh strategy');
+    }
+  }
+  return mode;
+}
 
 export function $getAuthIdSystem<K extends keyof IAuthIdRecord>(
   _authName: IAuthIdRecord[K],