@solidxai/core 0.1.15 → 0.1.16-beta.0

package/src/commands/run-tests.command.ts

@@ -9,6 +9,7 @@ import { runFromMetadata } from 'src/testing/runner/run-from-metadata';
 import type { TestingMetadata } from 'src/testing/contracts/testing-metadata.types';
 import { SpecRegistry } from 'src/testing/core/spec-registry';
 import { SettingService } from 'src/services/setting.service';
+import { WorkflowSecretService } from 'src/services/workflow-secret.service';
 import type { SolidCoreSetting } from 'src/services/settings/default-settings-provider.service';
 
 interface TestRunCommandOptions {
@@ -41,6 +42,7 @@ export class TestRunCommand extends CommandRunner {
   constructor(
     private readonly moduleMetadataHelperService: ModuleMetadataHelperService,
     private readonly settingService: SettingService,
+    private readonly workflowSecretService: WorkflowSecretService,
   ) {
     super();
   }
@@ -134,6 +136,7 @@ export class TestRunCommand extends CommandRunner {
             retries: options?.retries,
           },
           options: { printApiLogs },
+          resolveSecrets: (keys) => this.workflowSecretService.resolveAvailable(keys),
           specs: specEntries.length
             ? (registry) => loadSpecRegistrations(specEntries, metadataPath, registry)
             : undefined,

package/src/controllers/test-run.controller.ts

@@ -0,0 +1,44 @@
+import { randomUUID } from 'crypto';
+import { Body, Controller, HttpCode, HttpStatus, Post } from '@nestjs/common';
+import { ApiTags } from '@nestjs/swagger';
+
+import { Auth } from 'src/decorators/auth.decorator';
+import { Public } from 'src/decorators/public.decorator';
+import { AuthType } from 'src/enums/auth-type.enum';
+import { PublisherFactory } from 'src/services/queues/publisher-factory.service';
+import {
+  TestRunJobPayload,
+  TestRunRequestDto,
+} from 'src/dtos/test-run-request.dto';
+
+/**
+ * Triggers a BDD test run from CUSTOM INPUT (inline scenarios). Enqueues the run and
+ * returns immediately; a worker (QUEUES_SERVICE_ROLE=subscriber) executes it and
+ * streams lifecycle webhooks to `dto.webhookUrl`. Reusable by any Solid app
+ * (testingHub calls this from its StartRunController).
+ */
+@Auth(AuthType.None)
+@Controller('test-runs')
+@ApiTags('Solid Core')
+export class TestRunController {
+  constructor(private readonly publisherFactory: PublisherFactory<TestRunJobPayload>) {}
+
+  @Public()
+  @Post()
+  @HttpCode(HttpStatus.ACCEPTED)
+  // Accept the raw body (not the typed DTO) so the global ValidationPipe's
+  // implicit-conversion does not coerce inline scenario objects into empty arrays.
+  async trigger(@Body() dto: TestRunRequestDto & Record<string, any>) {
+    const runId = randomUUID();
+    const jobId = await this.publisherFactory.publish(
+      {
+        payload: { ...dto, runId },
+        parentEntity: 'testRun',
+      },
+      'TestRunQueuePublisher',
+      dto.broker,
+    );
+
+    return { runId, jobId, status: 'queued' };
+  }
+}

package/src/dtos/test-run-request.dto.ts

@@ -0,0 +1,130 @@
+import {
+  IsArray,
+  IsBoolean,
+  IsObject,
+  IsOptional,
+  IsString,
+} from 'class-validator';
+
+import type {
+  ScenarioSpec,
+  ScenarioType,
+  TestingDataRecord,
+  TestingRoleSpec,
+  TestingUserSpec,
+} from '../testing/contracts/testing-metadata.types';
+
+/**
+ * Per-scenario capture toggles. Structurally compatible with the typed
+ * `CaptureOptions` introduced in Phase 2 (A3, in adapters/ui/ui.types.ts).
+ */
+export interface CaptureOptionsInput {
+  console?: boolean;
+  network?: boolean;
+  screenshotOnFailure?: boolean;
+  screenshotAtEnd?: boolean;
+  video?: boolean;
+  har?: boolean;
+}
+
+/**
+ * Body of `POST /test-runs`. Carries the FULL test definition inline (scenarios +
+ * optional data/roles/users — the `testing` block minus `specs`), so the runner is
+ * location-agnostic and never reads a fixed module/path. `specs` (custom step code)
+ * cannot travel inline and must be deployed on the worker.
+ */
+export class TestRunRequestDto {
+  @IsOptional()
+  @IsArray()
+  scenarios?: ScenarioSpec[];
+
+  @IsOptional()
+  @IsString()
+  scenariosPath?: string;
+
+  @IsOptional()
+  @IsArray()
+  data?: TestingDataRecord[];
+
+  @IsOptional()
+  @IsArray()
+  roles?: TestingRoleSpec[];
+
+  @IsOptional()
+  @IsArray()
+  users?: TestingUserSpec[];
+
+  /** API base URL for relative request URLs. */
+  @IsOptional()
+  @IsString()
+  baseUrl?: string;
+
+  /** UI base URL for relative navigation (Playwright). */
+  @IsOptional()
+  @IsString()
+  uiBaseUrl?: string;
+
+  @IsOptional()
+  @IsString()
+  type?: ScenarioType;
+
+  @IsOptional()
+  @IsString()
+  env?: string;
+
+  @IsOptional()
+  @IsBoolean()
+  headless?: boolean;
+
+  @IsOptional()
+  @IsBoolean()
+  recordVideo?: boolean;
+
+  @IsOptional()
+  @IsArray()
+  includeTags?: string[];
+
+  @IsOptional()
+  @IsArray()
+  scenarioIds?: string[];
+
+  @IsOptional()
+  @IsArray()
+  skipScenarioIds?: string[];
+
+  /** Where lifecycle events are POSTed (e.g. testingHub ingest endpoint). */
+  @IsString()
+  webhookUrl!: string;
+
+  /** Correlation id supplied by the caller (e.g. testingHub TestRun id). */
+  @IsOptional()
+  @IsString()
+  externalRunId?: string;
+
+  /**
+   * Per-run env variables for `${env:X}` interpolation — e.g. { BASE_URL: app.url }
+   * so scenarios target the application under test rather than the runner itself.
+   * (Distinct from `env` above, which is the dev/uat/prod environment label.)
+   */
+  @IsOptional()
+  @IsObject()
+  variables?: Record<string, string>;
+
+  @IsOptional()
+  @IsObject()
+  capture?: CaptureOptionsInput;
+
+  @IsOptional()
+  @IsBoolean()
+  printApiLogs?: boolean;
+
+  /** Queue broker override: database | redis | rabbitmq (default: database). */
+  @IsOptional()
+  @IsString()
+  broker?: string;
+}
+
+/** Queue payload = the request plus the runner-generated run id. */
+export interface TestRunJobPayload extends TestRunRequestDto {
+  runId: string;
+}

package/src/guards/access-token.guard.ts

@@ -13,6 +13,7 @@ import { REQUEST_USER_KEY } from "../constants";
 import { PermissionMetadataService } from '../services/permission-metadata.service';
 import { ClsService } from 'nestjs-cls';
 import { ActiveSessionStorageService } from "../services/active-session-storage.service";
+import { AccessTokenDenylistService } from "../services/access-token-denylist.service";
 import { SettingService } from '../services/setting.service';
 import { createHash } from "crypto";
 
@@ -22,6 +23,7 @@ export class AccessTokenGuard implements CanActivate {
     private readonly jwtService: JwtService,
     private readonly permissionsService: PermissionMetadataService,
     private readonly activeSessionStorage: ActiveSessionStorageService,
+    private readonly accessTokenDenylist: AccessTokenDenylistService,
     private readonly settingService: SettingService,
     private readonly cls: ClsService
   ) { }
@@ -47,6 +49,13 @@ export class AccessTokenGuard implements CanActivate {
         jwtConfiguration
       );
 
+      // Immediate access-token revocation. Runs BEFORE the concurrent-login
+      // check on purpose: rejecting a revoked token first stops it reaching the
+      // adopt-on-empty branch below and reclaiming the active session slot.
+      // No setting check here - isRevoked short-circuits when the feature is
+      // off, without touching the cache.
+      await this.validateNotRevoked(payload, token);
+
       // Prevent Concurrent Login Feature
       await this.validateConcurrentLoginSession(payload, token);
 
@@ -83,6 +92,45 @@ export class AccessTokenGuard implements CanActivate {
     return createHash('sha256').update(token).digest('hex');
   }
 
+  /**
+   * The key this token's session is denylisted under.
+   *
+   * Deliberately NOT merged with resolveSessionId above, which differs only by
+   * the deviceKey step. Merging them would change validateConcurrentLoginSession
+   * for tokens issued while preventConcurrentLogins was off that are still live
+   * when it is switched on: those resolve to sha256(token) today and would
+   * resolve to deviceKey instead. The divergence is invisible in normal
+   * operation - that check only runs while the setting is on, and tokens issued
+   * in that state never carry a deviceKey - so the two formulas already agree
+   * for every token it sees. Only toggle-crossover tokens tell them apart.
+   */
+  private resolveRevocationKey(payload: ActiveUserData, token: string): string {
+    return (
+      payload.sessionId ??
+      payload.deviceKey ??
+      createHash('sha256').update(token).digest('hex')
+    );
+  }
+
+  private async validateNotRevoked(payload: ActiveUserData, token: string): Promise<void> {
+    // isRevoked would short-circuit on its own, but resolving the key first can
+    // cost a sha256 for a token carrying neither claim. Checking here keeps the
+    // opted-out path genuinely free.
+    if (!this.accessTokenDenylist.isEnabled()) {
+      return;
+    }
+
+    const revocationKey = this.resolveRevocationKey(payload, token);
+    const revoked = await this.accessTokenDenylist.isRevoked(
+      payload.sub,
+      revocationKey,
+      payload.iat,
+    );
+    if (revoked) {
+      throw new UnauthorizedException(ERROR_MESSAGES.SESSION_INVALID);
+    }
+  }
+
   private async validateConcurrentLoginSession(payload: ActiveUserData, token: string,): Promise<void> {
     if (!this.settingService.getConfigValue<SolidCoreSetting>("preventConcurrentLogins",)) {
       return;

package/src/index.ts

@@ -319,6 +319,15 @@ export * from './jobs/redis/smtp-email-subscriber-redis.service'
 export * from './jobs/redis/test-queue-publisher-redis.service'
 export * from './jobs/redis/test-queue-options-redis'
 export * from './jobs/redis/test-queue-subscriber-redis.service'
+export * from './jobs/database/test-run-queue-publisher-database.service'
+export * from './jobs/database/test-run-queue-subscriber-database.service'
+export * from './controllers/test-run.controller'
+export * from './dtos/test-run-request.dto'
+export * from './testing/reporter/lifecycle-events.types'
+export * from './testing/reporter/lifecycle-webhook-reporter'
+export * from './testing/reporter/artifact-sink'
+export * from './testing/reporter/file-service-artifact-sink'
+export * from './services/file/file-service.interface'
 export * from './jobs/redis/three60-whatsapp-publisher-redis.service'
 export * from './jobs/redis/three60-whatsapp-queue-options-redis'
 export * from './jobs/redis/three60-whatsapp-subscriber-redis.service'
@@ -339,7 +348,7 @@ export * from './services/selection-providers/list-of-values-selection-providers
 export * from './seeders/permission-metadata-seeder.service'
 export * from './seeders/module-metadata-seeder.service'
 
-// export * from './services/access-token-storage.service'
+export * from './services/access-token-denylist.service'
 export * from './services/action-metadata.service'
 export * from './services/authentication.service'
 export * from './services/bcrypt.service'
@@ -471,3 +480,14 @@ export * from './solid-core.module'
 export * from './winston.logger'
 
 export { ERROR_MESSAGES } from './constants/error-messages'
+// Needed by consuming projects composing their own logout, so they can return
+// the same response body as the built-in one.
+export { SUCCESS_MESSAGES } from './constants/success-messages'
+
+// Named rather than `export *` so the testing internals stay private: consumers only need
+// to provision the browser, which Test Hub does on module init.
+export {
+  ensureChromiumInstalled,
+  isChromiumInstalled,
+  cancelChromiumInstall,
+} from './testing/adapters/ui/browser-provisioner'

package/src/interfaces/active-user-data.interface.ts

@@ -37,6 +37,14 @@ export interface ActiveUserData {
    */
   roles: string[];
 
+  /**
+   * Standard JWT "issued at", in whole seconds. Stamped automatically by
+   * signAsync on every token - declared here only because it was never typed.
+   * Compared against a revocation instant to decide whether this token predates
+   * a logout.
+   */
+  iat?: number;
+
   /**
    * The subject's (user) permissions.
    * These are not part of the JWT token, we query them from the database each time the access-token guard is run. 

package/src/jobs/database/test-run-queue-options-database.ts

@@ -0,0 +1,9 @@
+import { BrokerType } from "../../interfaces";
+
+const QUEUE_NAME = 'solid_test_run_queue_db';
+
+export default {
+    name: QUEUE_NAME,
+    type: BrokerType.Database,
+    queueName: QUEUE_NAME,
+};

package/src/jobs/database/test-run-queue-publisher-database.service.ts

@@ -0,0 +1,24 @@
+import { Injectable } from '@nestjs/common';
+
+import testRunQueueConfig from './test-run-queue-options-database';
+import { MqMessageQueueService } from '../../services/mq-message-queue.service';
+import { MqMessageService } from '../../services/mq-message.service';
+import { QueuesModuleOptions } from "../../interfaces";
+import { DatabasePublisher } from 'src/services/queues/database-publisher.service';
+import { TestRunJobPayload } from '../../dtos/test-run-request.dto';
+
+@Injectable()
+export class TestRunQueuePublisherDatabase extends DatabasePublisher<TestRunJobPayload> {
+    constructor(
+        protected readonly mqMessageService: MqMessageService,
+        protected readonly mqMessageQueueService: MqMessageQueueService,
+    ) {
+        super(mqMessageService, mqMessageQueueService);
+    }
+
+    options(): QueuesModuleOptions {
+        return {
+            ...testRunQueueConfig
+        }
+    }
+}

package/src/jobs/database/test-run-queue-subscriber-database.service.ts

@@ -0,0 +1,122 @@
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import { HttpService } from '@nestjs/axios';
+
+import { QueueMessage } from 'src/interfaces/mq';
+import testRunQueueConfig from './test-run-queue-options-database';
+import { MqMessageService } from '../../services/mq-message.service';
+import { MqMessageQueueService } from '../../services/mq-message-queue.service';
+import { QueuesModuleOptions } from "../../interfaces";
+import { DatabaseSubscriber } from 'src/services/queues/database-subscriber.service';
+import { PollerService } from 'src/services/poller.service';
+import { runFromMetadata } from '../../testing/runner/run-from-metadata';
+import { readScenariosFile } from '../../testing/runner/read-scenarios-file';
+import {
+  LifecycleWebhookReporter,
+  WebhookPostFn,
+} from '../../testing/reporter/lifecycle-webhook-reporter';
+import { FileServiceArtifactSink } from '../../testing/reporter/file-service-artifact-sink';
+import { FILE_SERVICE, IFileService } from '../../services/file/file-service.interface';
+import { TestRunJobPayload } from '../../dtos/test-run-request.dto';
+import { WorkflowSecretService } from '../../services/workflow-secret.service';
+
+/**
+ * Executes a queued test run on the worker tier (QUEUES_SERVICE_ROLE=subscriber).
+ * Resolves scenarios from `scenariosPath` (read from disk here, at execution time —
+ * the worker shares the filesystem with the caller) or from inline `scenarios`, then
+ * runs them via {@link runFromMetadata} with a {@link LifecycleWebhookReporter} that
+ * streams run.start → scenario.* → run.end to the caller's webhookUrl. A failing TEST
+ * is NOT a failing JOB: failures (including an unreadable scenario file) are reported
+ * over the webhook (run.end ok:false) and the job still completes, so the queue does
+ * not retry a deterministically-failing test run.
+ */
+@Injectable()
+export class TestRunQueueSubscriberDatabase extends DatabaseSubscriber<TestRunJobPayload> {
+    private readonly testRunLogger = new Logger(TestRunQueueSubscriberDatabase.name);
+
+    constructor(
+        readonly mqMessageService: MqMessageService,
+        readonly mqMessageQueueService: MqMessageQueueService,
+        readonly poller: PollerService,
+        private readonly httpService: HttpService,
+        @Inject(FILE_SERVICE) private readonly fileService: IFileService,
+        private readonly workflowSecretService: WorkflowSecretService,
+    ) {
+        super(mqMessageService, mqMessageQueueService, poller);
+    }
+
+    options(): QueuesModuleOptions {
+        return {
+            ...testRunQueueConfig
+        }
+    }
+
+    async subscribe(message: QueueMessage<TestRunJobPayload>) {
+        const p = message.payload;
+        this.testRunLogger.debug(`Starting test run ${p.runId} (externalRunId=${p.externalRunId})`);
+
+        const post: WebhookPostFn = async (url, body, opts) => {
+            const res = await this.httpService.axiosRef.post(url, body, {
+                headers: { 'Content-Type': 'application/json', ...(opts.headers ?? {}) },
+                timeout: opts.timeoutMs ?? 10_000,
+                validateStatus: () => true,
+            });
+            return { ok: res.status >= 200 && res.status < 300, status: res.status };
+        };
+
+        // Persist binary artifacts (screenshots, whole-run video) to shared storage via the
+        // core FILE_SERVICE (disk by default, S3 when DEFAULT_FILE_SERVICE=s3) instead of
+        // shipping them inline / storing blobs in the DB.
+        const artifactSink = new FileServiceArtifactSink(this.fileService, { prefix: 'testing-hub' });
+
+        const reporter = new LifecycleWebhookReporter({
+            webhookUrl: p.webhookUrl,
+            runName: p.externalRunId ?? p.runId,
+            externalRunId: p.externalRunId,
+            runId: p.runId,
+            post,
+            artifactSink,
+        });
+
+        let scenarios = p.scenarios;
+        let data = p.data;
+        if (p.scenariosPath) {
+            const read = readScenariosFile(p.scenariosPath);
+            if (!read.ok) {
+                const reason = `Scenario file unreadable: ${p.scenariosPath} (${read.error})`;
+                this.testRunLogger.warn(`Test run ${p.runId} — ${reason}`);
+                reporter.onRunStart({ total: 0, startedAt: new Date().toISOString(), scenarioIds: [] });
+                await reporter.flushPending(1, reason);
+                return { runId: p.runId, exitCode: 1 };
+            }
+            scenarios = read.scenarios;
+            data = read.data ?? data;
+            this.testRunLogger.debug(`Test run ${p.runId} loaded ${scenarios.length} scenario(s) from ${p.scenariosPath}`);
+        }
+
+        let exitCode = 0;
+        try {
+            await runFromMetadata({
+                scenarios,
+                data,
+                includeTags: p.includeTags,
+                scenarioIds: p.scenarioIds,
+                skipScenarioIds: p.skipScenarioIds,
+                reporter,
+                env: p.variables,
+                api: { baseUrl: p.baseUrl },
+                ui: { baseUrl: p.uiBaseUrl, headless: p.headless ?? true, capture: p.capture, recordVideo: p.recordVideo ?? true },
+                options: { printApiLogs: p.printApiLogs ?? true },
+                externalRunId: p.externalRunId,
+                resolveSecrets: (keys) => this.workflowSecretService.resolveAvailable(keys),
+            });
+        } catch (err: any) {
+            // A failed scenario is surfaced via the run.end webhook, not as a job failure.
+            exitCode = 1;
+            this.testRunLogger.warn(`Test run ${p.runId} completed with failures: ${err?.message ?? err}`);
+        } finally {
+            await reporter.flushPending(exitCode);
+        }
+
+        return { runId: p.runId, exitCode };
+    }
+}

package/src/seeders/seed-data/solid-core-metadata.json

@@ -14958,6 +14958,7 @@
           "enableGlobalSearch": true,
           "create": false,
           "edit": false,
+          "delete": false,
           "import": false,
           "export": false,
           "allowedViews": [
@@ -15089,7 +15090,8 @@
           "label": "User Activity History",
           "className": "grid",
           "showAddFormButton": false,
-          "showEditFormButton": false
+          "showEditFormButton": false,
+          "showDeleteFormButton": false
         },
         "children": [
           {

package/src/services/access-token-denylist.service.ts

@@ -0,0 +1,145 @@
+import { CACHE_MANAGER } from "@nestjs/cache-manager";
+import { Inject, Injectable } from "@nestjs/common";
+import { Cache } from "cache-manager";
+import type { SolidCoreSetting } from "src/services/settings/default-settings-provider.service";
+import { SettingService } from "./setting.service";
+
+// The denylist entry must outlive the longest-lived access token it could
+// match. Any token an entry rejects was issued before the revocation, so it
+// dies by revokedAt + accessTokenTtl at the latest; after that `exp` rejects it
+// and the entry is dead weight. Mirrors STATE_TTL_BUFFER_SECONDS in
+// refresh-token-ids-storage.service.ts.
+const ENTRY_TTL_BUFFER_SECONDS = 60;
+
+/**
+ * Immediate access-token revocation, opt-in via `invalidateAccessTokenOnLogout`.
+ *
+ * Entries record WHEN a session was revoked rather than merely that it was, and
+ * the guard compares that instant against the token's own `iat`. The timestamp
+ * is what makes a session-scoped key safe: some keys are reused across logins -
+ * API-key auth passes a stable `apikey-<id>` deviceKey, and the per-user key
+ * below is shared by every login that user will ever make - so a boolean entry
+ * would have to either reject the newly minted token too, or be cleared on
+ * re-issue and thereby revive the still-unexpired token the logout killed.
+ * Comparing against `iat` needs neither: tokens minted after the revocation
+ * pass, tokens minted before it fail, and nothing is ever cleared.
+ *
+ * This service owns the setting check - callers never branch on it. One source
+ * of truth instead of three call sites that can drift, no `if (enabled)` nesting
+ * in logout(), and a consuming project using the public seam cannot write
+ * entries that nothing will ever read. `getConfigValue` is a synchronous
+ * in-memory lookup, so a deployment that has not opted in pays nothing and
+ * issues no I/O.
+ */
+@Injectable()
+export class AccessTokenDenylistService {
+  constructor(
+    @Inject(CACHE_MANAGER) private readonly cacheManager: Cache,
+    private readonly settingService: SettingService,
+  ) {}
+
+  isEnabled(): boolean {
+    return (
+      this.settingService.getConfigValue<SolidCoreSetting>(
+        "invalidateAccessTokenOnLogout",
+      ) === true
+    );
+  }
+
+  /**
+   * Revoke every access token belonging to one session. A no-op when the
+   * feature is off, and when no session key could be resolved - which spares
+   * the caller a null check.
+   */
+  async revokeSession(userId: number, sessionKey?: string): Promise<void> {
+    if (!this.isEnabled() || !sessionKey) {
+      return;
+    }
+    await this.cacheManager.set(
+      this.getSessionKey(userId, sessionKey),
+      this.revokedAt(),
+      this.getEntryTtlMs(),
+    );
+  }
+
+  /**
+   * Revoke every access token for a user, across all sessions - `allDevices`.
+   *
+   * Needs no claim on the token and no enumeration of buckets: every
+   * outstanding token was necessarily issued before the logout that writes
+   * this, so one entry sweeps them all.
+   */
+  async revokeAllForUser(userId: number): Promise<void> {
+    if (!this.isEnabled()) {
+      return;
+    }
+    await this.cacheManager.set(
+      this.getUserKey(userId),
+      this.revokedAt(),
+      this.getEntryTtlMs(),
+    );
+  }
+
+  /**
+   * True when the token was issued before either revocation instant that could
+   * apply to it - its own session's, or its user's.
+   *
+   * Returns false without touching the cache when the feature is off, which is
+   * why the guard needs no setting check of its own.
+   */
+  async isRevoked(
+    userId: number,
+    sessionKey: string,
+    issuedAtSeconds?: number,
+  ): Promise<boolean> {
+    if (!this.isEnabled()) {
+      return false;
+    }
+
+    // A token with no `iat` cannot be placed relative to a revocation. Tokens
+    // signed by @nestjs/jwt always carry one, so this is a malformed-payload
+    // guard rather than a real case; refuse rather than fail open.
+    if (typeof issuedAtSeconds !== "number") {
+      return true;
+    }
+
+    const [sessionRevokedAt, userRevokedAt] = await Promise.all([
+      this.cacheManager.get<number>(this.getSessionKey(userId, sessionKey)),
+      this.cacheManager.get<number>(this.getUserKey(userId)),
+    ]);
+
+    const revokedAt = Math.max(sessionRevokedAt ?? 0, userRevokedAt ?? 0);
+    return issuedAtSeconds * 1000 < revokedAt;
+  }
+
+  /**
+   * `iat` has whole-second resolution, so a token minted in the same second as
+   * the revocation is indistinguishable from one minted just before it.
+   * Rounding up resolves that ambiguity toward revoking: an automated client
+   * re-authenticating inside the window gets one 401 and succeeds on retry,
+   * whereas rounding down would leave a genuinely revoked token valid for up to
+   * a second. No human path can reach the window at all - logout invalidates
+   * the refresh token, so the next access token only exists after a fresh login.
+   */
+  private revokedAt(): number {
+    return (Math.floor(Date.now() / 1000) + 1) * 1000;
+  }
+
+  private getSessionKey(userId: number, sessionKey: string): string {
+    return `revoked-session-${userId}-${sessionKey}`;
+  }
+
+  private getUserKey(userId: number): string {
+    return `revoked-user-${userId}`;
+  }
+
+  // cache-manager v5 expects milliseconds; accessTokenTtl is configured in
+  // seconds. Read from the setting rather than hardcoded so that raising
+  // accessTokenTtl keeps entries long enough to outlive the tokens they match.
+  private getEntryTtlMs(): number {
+    const accessTokenTtlSeconds = Number(
+      this.settingService.getConfigValue<SolidCoreSetting>("accessTokenTtl"),
+    );
+    return (accessTokenTtlSeconds + ENTRY_TTL_BUFFER_SECONDS) * 1000;
+  }
+}