@shipfox/api-runners 2.0.0

package/src/core/provisioned-runners.ts

@@ -0,0 +1,301 @@
+import type {ProvisionedRunner, ProvisionedRunnerState} from '#core/entities/provisioned-runner.js';
+import {
+  isTerminalState,
+  listActiveProvisionedRunners,
+  listActiveRunningJobExecutions,
+  type ProvisionedRunnerReportEvent,
+  reconcileProvisionedRunners as reconcileProvisionedRunnersDb,
+  reportProvisionedRunners as reportProvisionedRunnersDb,
+} from '#db/index.js';
+import type {
+  ActiveRunningJobExecution,
+  ProvisionedRunnerBoundJobExecution,
+} from '#db/job-executions.js';
+import {
+  provisionedRunnerAbsentTerminatedCount,
+  provisionedRunnerReconcileCallCount,
+  provisionedRunnerReportCount,
+  provisionedRunnerTerminateIntentHonoredCount,
+  provisionedRunnerTerminateIntentIssuedCount,
+  reservationReleasedCount,
+} from '#metrics/instance.js';
+import {config} from '../config.js';
+
+export interface ReportProvisionedRunnersParams {
+  workspaceId: string;
+  provisionerId: string;
+  events: ProvisionedRunnerReportEvent[];
+}
+
+export interface ReportProvisionedRunnersResult {
+  accepted: number;
+  reservationsReleased: number;
+}
+
+export interface ReconcileProvisionedRunnersParams {
+  workspaceId: string;
+  provisionerId: string;
+  observedProvisionedRunnerIds: string[];
+}
+
+export type ReconcileDesiredIntent = 'keep' | 'terminate';
+type ReconcileDesiredIntentReason = 'job-cancelled' | 'terminal-state';
+
+export interface ReconciledBoundJobExecution {
+  jobId: string;
+  jobExecutionId: string;
+  workflowRunAttemptId: string;
+  lastHeartbeatAt: Date;
+  cancellationRequestedAt: Date | null;
+}
+
+export interface ReconciledProvisionedRunner {
+  provisionedRunnerId: string;
+  state: ProvisionedRunnerState | null;
+  reservationId: string | null;
+  runnerSessionId: string | null;
+  boundJobExecution: ReconciledBoundJobExecution | null;
+  desiredIntent: ReconcileDesiredIntent;
+  desiredIntentReason: ReconcileDesiredIntentReason | null;
+}
+
+export interface ReconcileProvisionedRunnersResult {
+  runners: ReconciledProvisionedRunner[];
+  terminatedAbsentProvisionedRunnerIds: string[];
+}
+
+export type ActiveRunnerState = 'starting' | 'running' | 'stopping' | 'busy';
+
+export interface ActiveRunner {
+  runnerSessionId: string | null;
+  provisionedRunnerId: string | null;
+  provisionerId: string | null;
+  state: ActiveRunnerState;
+  labels: string[];
+  templateKey: string | null;
+  providerKind: string | null;
+  jobId: string | null;
+  workflowRunAttemptId: string | null;
+  projectId: string | null;
+  reportedAt: Date | null;
+  lastHeartbeatAt: Date | null;
+}
+
+export async function reportProvisionedRunners(
+  params: ReportProvisionedRunnersParams,
+): Promise<ReportProvisionedRunnersResult> {
+  const result = await reportProvisionedRunnersDb(params);
+
+  for (const event of params.events) {
+    provisionedRunnerReportCount.add(1, {state: event.state});
+  }
+  for (const intent of result.terminateIntentsHonored) {
+    provisionedRunnerTerminateIntentHonoredCount.add(1, {reason: intent.reason});
+  }
+  if (result.reservationsReleased > 0) reservationReleasedCount.add(result.reservationsReleased);
+
+  return result;
+}
+
+export async function reconcileProvisionedRunners(
+  params: ReconcileProvisionedRunnersParams,
+): Promise<ReconcileProvisionedRunnersResult> {
+  const result = await reconcileProvisionedRunnersDb({
+    ...params,
+    terminateGraceSeconds: config.RUNNER_RECONCILE_TERMINATE_GRACE_SECONDS,
+  });
+
+  if (result.reservationsReleased > 0) reservationReleasedCount.add(result.reservationsReleased);
+  provisionedRunnerReconcileCallCount.add(1);
+  if (result.absentIds.length > 0)
+    provisionedRunnerAbsentTerminatedCount.add(result.absentIds.length);
+
+  const runners = reconcileProvisionedRunnersFromDbResult({
+    observedProvisionedRunnerIds: params.observedProvisionedRunnerIds,
+    observedRows: result.observedRows,
+    boundJobExecutionsByProvisionedRunnerId: result.boundJobExecutionsByProvisionedRunnerId,
+  });
+  for (const runner of runners) {
+    if (runner.desiredIntentReason) {
+      provisionedRunnerTerminateIntentIssuedCount.add(1, {
+        surface: 'reconcile',
+        reason: runner.desiredIntentReason,
+      });
+    }
+  }
+
+  return {
+    runners,
+    terminatedAbsentProvisionedRunnerIds: result.absentIds,
+  };
+}
+
+export function reconcileProvisionedRunnersFromDbResult(params: {
+  observedProvisionedRunnerIds: string[];
+  observedRows: ProvisionedRunner[];
+  boundJobExecutionsByProvisionedRunnerId: Map<string, ProvisionedRunnerBoundJobExecution>;
+}): ReconciledProvisionedRunner[] {
+  const rowsByProvisionedRunnerId = new Map(
+    params.observedRows.map((row) => [row.provisionedRunnerId, row]),
+  );
+
+  return params.observedProvisionedRunnerIds.map((provisionedRunnerId) => {
+    const row = rowsByProvisionedRunnerId.get(provisionedRunnerId);
+    const boundJobExecution =
+      params.boundJobExecutionsByProvisionedRunnerId.get(provisionedRunnerId);
+
+    const desiredIntentReason = getDesiredIntentReason(row, boundJobExecution);
+
+    return {
+      provisionedRunnerId,
+      state: row?.state ?? null,
+      reservationId: row?.reservationId ?? null,
+      runnerSessionId: row?.runnerSessionId ?? null,
+      boundJobExecution: boundJobExecution
+        ? toReconciledBoundJobExecution(boundJobExecution)
+        : null,
+      desiredIntent: desiredIntentReason ? 'terminate' : 'keep',
+      desiredIntentReason,
+    };
+  });
+}
+
+export async function listActiveRunners(params: {workspaceId: string}): Promise<ActiveRunner[]> {
+  const [provisionedRunnerRows, jobExecutionRows] = await Promise.all([
+    listActiveProvisionedRunners({
+      workspaceId: params.workspaceId,
+      windowSeconds: config.RUNNER_ACTIVE_WINDOW_SECONDS,
+    }),
+    listActiveRunningJobExecutions({
+      workspaceId: params.workspaceId,
+      windowSeconds: config.RUNNER_ACTIVE_WINDOW_SECONDS,
+    }),
+  ]);
+
+  return mergeActiveRunners(provisionedRunnerRows, jobExecutionRows);
+}
+
+function toReconciledBoundJobExecution(
+  jobExecution: ProvisionedRunnerBoundJobExecution,
+): ReconciledBoundJobExecution {
+  return {
+    jobId: jobExecution.jobId,
+    jobExecutionId: jobExecution.jobExecutionId,
+    workflowRunAttemptId: jobExecution.workflowRunAttemptId,
+    lastHeartbeatAt: jobExecution.lastHeartbeatAt,
+    cancellationRequestedAt: jobExecution.cancellationRequestedAt,
+  };
+}
+
+export function desiredIntent(
+  row: ProvisionedRunner | undefined,
+  boundJobExecution: ProvisionedRunnerBoundJobExecution | undefined,
+): ReconcileDesiredIntent {
+  return getDesiredIntentReason(row, boundJobExecution) ? 'terminate' : 'keep';
+}
+
+function getDesiredIntentReason(
+  row: ProvisionedRunner | undefined,
+  boundJobExecution: ProvisionedRunnerBoundJobExecution | undefined,
+): ReconcileDesiredIntentReason | null {
+  if (!row) return null;
+  if (isTerminalState(row.state)) return 'terminal-state';
+  if (boundJobExecution?.cancellationRequestedAt) return 'job-cancelled';
+  return null;
+}
+
+function mergeActiveRunners(
+  provisionedRunners: ProvisionedRunner[],
+  jobExecutions: ActiveRunningJobExecution[],
+): ActiveRunner[] {
+  const jobExecutionsByRunnerSessionId = new Map<string, ActiveRunningJobExecution[]>();
+  const jobExecutionsByProvisionedRunnerId = new Map<string, ActiveRunningJobExecution[]>();
+  for (const jobExecution of jobExecutions) {
+    const runnerJobExecutions =
+      jobExecutionsByRunnerSessionId.get(jobExecution.runnerSessionId) ?? [];
+    runnerJobExecutions.push(jobExecution);
+    jobExecutionsByRunnerSessionId.set(jobExecution.runnerSessionId, runnerJobExecutions);
+
+    if (jobExecution.provisionerId && jobExecution.provisionedRunnerId) {
+      const key = provisionedRunnerKey(
+        jobExecution.provisionerId,
+        jobExecution.provisionedRunnerId,
+      );
+      const provisionedRunnerJobExecutions = jobExecutionsByProvisionedRunnerId.get(key) ?? [];
+      provisionedRunnerJobExecutions.push(jobExecution);
+      jobExecutionsByProvisionedRunnerId.set(key, provisionedRunnerJobExecutions);
+    }
+  }
+
+  const merged: ActiveRunner[] = [];
+  const usedJobExecutionIds = new Set<string>();
+
+  for (const provisionedRunner of provisionedRunners) {
+    const provisionedRunnerJobExecutions =
+      jobExecutionsByProvisionedRunnerId.get(
+        provisionedRunnerKey(
+          provisionedRunner.provisionerId,
+          provisionedRunner.provisionedRunnerId,
+        ),
+      ) ??
+      (provisionedRunner.runnerSessionId
+        ? jobExecutionsByRunnerSessionId.get(provisionedRunner.runnerSessionId)
+        : undefined);
+    if (!provisionedRunnerJobExecutions || provisionedRunnerJobExecutions.length === 0) {
+      merged.push(toActiveRunner(provisionedRunner, undefined));
+      continue;
+    }
+
+    let emitted = false;
+    for (const jobExecution of provisionedRunnerJobExecutions) {
+      if (usedJobExecutionIds.has(jobExecution.jobExecutionId)) continue;
+      usedJobExecutionIds.add(jobExecution.jobExecutionId);
+      merged.push(toActiveRunner(provisionedRunner, jobExecution));
+      emitted = true;
+    }
+    if (!emitted) merged.push(toActiveRunner(provisionedRunner, undefined));
+  }
+
+  for (const jobExecution of jobExecutions) {
+    if (usedJobExecutionIds.has(jobExecution.jobExecutionId)) continue;
+    merged.push(toActiveRunner(undefined, jobExecution));
+  }
+
+  return merged.sort(compareActiveRunners);
+}
+
+function provisionedRunnerKey(provisionerId: string, provisionedRunnerId: string): string {
+  return `${provisionerId}:${provisionedRunnerId}`;
+}
+
+function toActiveRunner(
+  provisionedRunner: ProvisionedRunner | undefined,
+  jobExecution: ActiveRunningJobExecution | undefined,
+): ActiveRunner {
+  return {
+    runnerSessionId: provisionedRunner?.runnerSessionId ?? jobExecution?.runnerSessionId ?? null,
+    provisionedRunnerId:
+      provisionedRunner?.provisionedRunnerId ?? jobExecution?.provisionedRunnerId ?? null,
+    provisionerId: provisionedRunner?.provisionerId ?? jobExecution?.provisionerId ?? null,
+    state: jobExecution ? 'busy' : toActiveRunnerState(provisionedRunner?.state ?? 'running'),
+    labels: provisionedRunner?.labels ?? jobExecution?.runnerLabels ?? [],
+    templateKey: provisionedRunner?.templateKey ?? null,
+    providerKind: provisionedRunner?.providerKind ?? null,
+    jobId: jobExecution?.jobId ?? null,
+    workflowRunAttemptId: jobExecution?.workflowRunAttemptId ?? null,
+    projectId: jobExecution?.projectId ?? null,
+    reportedAt: provisionedRunner?.reportedAt ?? null,
+    lastHeartbeatAt: jobExecution?.lastHeartbeatAt ?? null,
+  };
+}
+
+function toActiveRunnerState(state: ProvisionedRunnerState): ActiveRunnerState {
+  if (state === 'starting' || state === 'stopping') return state;
+  return 'running';
+}
+
+function compareActiveRunners(a: ActiveRunner, b: ActiveRunner): number {
+  const aTime = Math.max(a.lastHeartbeatAt?.getTime() ?? 0, a.reportedAt?.getTime() ?? 0);
+  const bTime = Math.max(b.lastHeartbeatAt?.getTime() ?? 0, b.reportedAt?.getTime() ?? 0);
+  return bTime - aTime;
+}

package/src/core/provisioner-tokens.test.ts

@@ -0,0 +1,61 @@
+import {hashOpaqueToken, tokenTypeParts} from '@shipfox/node-tokens';
+import {eq} from 'drizzle-orm';
+import {db} from '#db/db.js';
+import {provisionerTokens} from '#db/schema/provisioner-tokens.js';
+import {provisionerTokenFactory} from '#test/index.js';
+import {
+  createWorkspaceProvisionerToken,
+  listUsableProvisionerTokens,
+  revokeWorkspaceProvisionerToken,
+} from './provisioner-tokens.js';
+
+describe('provisioner token core', () => {
+  it('creates a workspace provisioner token and stores only the hash', async () => {
+    const workspaceId = crypto.randomUUID();
+    const createdByUserId = crypto.randomUUID();
+
+    const result = await createWorkspaceProvisionerToken({
+      workspaceId,
+      createdByUserId,
+      name: 'local provisioner',
+      ttlSeconds: 3600,
+    });
+
+    expect(result.rawToken.startsWith(`sf_${tokenTypeParts.provisionerToken}_`)).toBe(true);
+    expect(result.token.workspaceId).toBe(workspaceId);
+    expect(result.token.createdByUserId).toBe(createdByUserId);
+    expect(result.token.expiresAt).toBeInstanceOf(Date);
+    expect(result.token.prefix).toBe(result.rawToken.slice(0, 12));
+    const rows = await db()
+      .select()
+      .from(provisionerTokens)
+      .where(eq(provisionerTokens.id, result.token.id));
+    expect(rows[0]?.hashedToken).toBe(hashOpaqueToken(result.rawToken));
+    expect(rows[0]?.hashedToken).not.toBe(result.rawToken);
+  });
+
+  it('lists usable tokens and excludes revoked tokens after revoke', async () => {
+    const workspaceId = crypto.randomUUID();
+    const token = await provisionerTokenFactory.create({workspaceId});
+    const revokedByUserId = crypto.randomUUID();
+
+    const beforeRevoke = await listUsableProvisionerTokens(workspaceId);
+    await revokeWorkspaceProvisionerToken({tokenId: token.id, workspaceId, revokedByUserId});
+    const afterRevoke = await listUsableProvisionerTokens(workspaceId);
+
+    expect(beforeRevoke.map((item) => item.id)).toEqual([token.id]);
+    expect(afterRevoke).toEqual([]);
+  });
+
+  it('throws when revoking a token outside the workspace', async () => {
+    const token = await provisionerTokenFactory.create({workspaceId: crypto.randomUUID()});
+
+    const result = revokeWorkspaceProvisionerToken({
+      tokenId: token.id,
+      workspaceId: crypto.randomUUID(),
+      revokedByUserId: crypto.randomUUID(),
+    });
+
+    await expect(result).rejects.toThrow(`Provisioner token not found: ${token.id}`);
+  });
+});

package/src/core/provisioner-tokens.ts

@@ -0,0 +1,61 @@
+import {extractDisplayPrefix, generateOpaqueToken, hashOpaqueToken} from '@shipfox/node-tokens';
+import {
+  createProvisionerToken,
+  listActiveProvisionerTokens,
+  listUsableProvisionerTokensByWorkspaceId,
+  revokeProvisionerToken,
+} from '#db/provisioner-tokens.js';
+import {config} from '../config.js';
+import type {ActiveProvisionerToken, ProvisionerToken} from './entities/provisioner-token.js';
+import {ProvisionerTokenNotFoundError} from './errors.js';
+
+export interface CreateWorkspaceProvisionerTokenParams {
+  workspaceId: string;
+  createdByUserId: string;
+  name?: string | undefined;
+  ttlSeconds?: number | undefined;
+}
+
+export interface CreateWorkspaceProvisionerTokenResult {
+  token: ProvisionerToken;
+  rawToken: string;
+}
+
+export async function createWorkspaceProvisionerToken(
+  params: CreateWorkspaceProvisionerTokenParams,
+): Promise<CreateWorkspaceProvisionerTokenResult> {
+  const rawToken = generateOpaqueToken('provisionerToken');
+  const expiresAt = params.ttlSeconds ? new Date(Date.now() + params.ttlSeconds * 1000) : undefined;
+
+  const token = await createProvisionerToken({
+    workspaceId: params.workspaceId,
+    hashedToken: hashOpaqueToken(rawToken),
+    prefix: extractDisplayPrefix(rawToken),
+    name: params.name,
+    createdByUserId: params.createdByUserId,
+    expiresAt,
+  });
+
+  return {token, rawToken};
+}
+
+export function listUsableProvisionerTokens(workspaceId: string): Promise<ProvisionerToken[]> {
+  return listUsableProvisionerTokensByWorkspaceId(workspaceId);
+}
+
+export function listActiveProvisioners(workspaceId: string): Promise<ActiveProvisionerToken[]> {
+  return listActiveProvisionerTokens({
+    workspaceId,
+    windowSeconds: config.PROVISIONER_ACTIVE_WINDOW_SECONDS,
+  });
+}
+
+export async function revokeWorkspaceProvisionerToken(params: {
+  tokenId: string;
+  workspaceId: string;
+  revokedByUserId: string;
+}): Promise<ProvisionerToken> {
+  const token = await revokeProvisionerToken(params);
+  if (!token) throw new ProvisionerTokenNotFoundError(params.tokenId);
+  return token;
+}

package/src/core/rate-limit.test.ts

@@ -0,0 +1,158 @@
+import {vi} from '@shipfox/vitest/vi';
+import {eq, sql} from 'drizzle-orm';
+import {db} from '#db/db.js';
+import {runnersRateLimits} from '#db/schema/rate-limits.js';
+import {
+  checkRunnersRateLimit,
+  hashRunnersRateLimitIdentifier,
+  RunnersRateLimitUnavailableError,
+} from './rate-limit.js';
+
+const HMAC_HEX_PATTERN = /^[a-f0-9]{64}$/;
+
+describe('checkRunnersRateLimit', () => {
+  it('hashes identifiers without storing the raw identifier', async () => {
+    const identifier = `provisioner-${crypto.randomUUID()}`;
+    const identifierHmac = hashRunnersRateLimitIdentifier({
+      action: 'provisioner-mint',
+      scope: 'provisioner',
+      identifier,
+    });
+
+    await checkRunnersRateLimit({
+      action: 'provisioner-mint',
+      scope: 'provisioner',
+      identifier,
+      limit: 1,
+      windowSeconds: 60,
+      now: new Date('2026-06-23T00:00:10Z'),
+    });
+
+    const rows = await db()
+      .select({identifierHmac: runnersRateLimits.identifierHmac})
+      .from(runnersRateLimits)
+      .where(eq(runnersRateLimits.identifierHmac, identifierHmac));
+    expect(identifierHmac).toMatch(HMAC_HEX_PATTERN);
+    expect(identifierHmac).not.toContain(identifier);
+    expect(rows).toEqual([{identifierHmac}]);
+  });
+
+  it('rejects the first over-limit attempt with retry-after seconds', async () => {
+    const identifier = `ephemeral-${crypto.randomUUID()}`;
+    const now = new Date('2026-06-23T00:00:10Z');
+
+    await checkRunnersRateLimit({
+      action: 'ephemeral-register',
+      scope: 'ephemeral-token',
+      identifier,
+      limit: 2,
+      windowSeconds: 60,
+      now,
+    });
+    await checkRunnersRateLimit({
+      action: 'ephemeral-register',
+      scope: 'ephemeral-token',
+      identifier,
+      limit: 2,
+      windowSeconds: 60,
+      now,
+    });
+    const result = checkRunnersRateLimit({
+      action: 'ephemeral-register',
+      scope: 'ephemeral-token',
+      identifier,
+      limit: 2,
+      windowSeconds: 60,
+      now,
+    });
+
+    await expect(result).rejects.toMatchObject({
+      name: 'RunnersRateLimitExceededError',
+      retryAfterSeconds: 50,
+    });
+  });
+
+  it('fails closed when the limiter query times out', async () => {
+    const identifier = `provisioner-${crypto.randomUUID()}`;
+    const identifierHmac = hashRunnersRateLimitIdentifier({
+      action: 'provisioner-mint',
+      scope: 'provisioner',
+      identifier,
+    });
+    await db()
+      .insert(runnersRateLimits)
+      .values({
+        action: 'provisioner-mint',
+        scope: 'provisioner',
+        identifierHmac,
+        windowStart: new Date('2026-06-23T00:03:00Z'),
+        count: 1,
+        expiresAt: new Date('2026-06-23T00:04:00Z'),
+      });
+
+    await db().transaction(async (tx) => {
+      await tx.execute(sql`
+        SELECT 1
+        FROM runners_rate_limits
+        WHERE identifier_hmac = ${identifierHmac}
+        FOR UPDATE
+      `);
+      const result = checkRunnersRateLimit({
+        action: 'provisioner-mint',
+        scope: 'provisioner',
+        identifier,
+        limit: 1,
+        windowSeconds: 60,
+        now: new Date('2026-06-23T00:03:30Z'),
+        timeoutMs: 10,
+      });
+
+      await expect(result).rejects.toBeInstanceOf(RunnersRateLimitUnavailableError);
+    });
+  });
+
+  it('uses the configured shared identifier secret when present', async () => {
+    vi.resetModules();
+    vi.doMock('#config.js', () => ({
+      config: {
+        RATE_LIMIT_IDENTIFIER_SECRET: 'configured-secret',
+        RUNNERS_RATE_LIMIT_TIMEOUT_MS: 250,
+      },
+    }));
+    vi.doMock('@shipfox/api-auth/config', () => ({
+      config: {
+        AUTH_JWT_SECRET: 'jwt-secret',
+      },
+    }));
+
+    try {
+      const configuredSecretModule = await import('./rate-limit.js');
+      const configuredSecretHash = configuredSecretModule.hashRunnersRateLimitIdentifier({
+        action: 'provisioner-mint',
+        scope: 'provisioner',
+        identifier: 'provisioner-token-id',
+      });
+      vi.doMock('#config.js', () => ({
+        config: {
+          RATE_LIMIT_IDENTIFIER_SECRET: undefined,
+          RUNNERS_RATE_LIMIT_TIMEOUT_MS: 250,
+        },
+      }));
+      vi.resetModules();
+      const derivedSecretModule = await import('./rate-limit.js');
+      const derivedSecretHash = derivedSecretModule.hashRunnersRateLimitIdentifier({
+        action: 'provisioner-mint',
+        scope: 'provisioner',
+        identifier: 'provisioner-token-id',
+      });
+
+      expect(configuredSecretHash).toMatch(HMAC_HEX_PATTERN);
+      expect(derivedSecretHash).toMatch(HMAC_HEX_PATTERN);
+      expect(configuredSecretHash).not.toBe(derivedSecretHash);
+    } finally {
+      vi.doUnmock('#config.js');
+      vi.doUnmock('@shipfox/api-auth/config');
+      vi.resetModules();
+    }
+  });
+});

package/src/core/rate-limit.ts

@@ -0,0 +1,121 @@
+import {createHmac} from 'node:crypto';
+import {config as authConfig} from '@shipfox/api-auth/config';
+import {
+  checkRateLimit,
+  hashRateLimitIdentifier,
+  RateLimitExceededError,
+  type RateLimitOutcome,
+  type RateLimitPolicy,
+  RateLimitUnavailableError,
+} from '@shipfox/node-rate-limit';
+import {config} from '#config.js';
+import {consumeRunnersRateLimit, pruneExpiredRunnersRateLimits} from '#db/rate-limits.js';
+import {recordRunnersRateLimitCheck, recordRunnersRateLimitPruneFailure} from '#metrics/index.js';
+
+export type RunnersRateLimitAction = 'provisioner-mint' | 'ephemeral-register';
+export type RunnersRateLimitScope = 'provisioner' | 'ephemeral-token';
+export type RunnersRateLimitOutcome = RateLimitOutcome;
+export type RunnersRateLimitPolicy = RateLimitPolicy;
+
+export interface CheckRunnersRateLimitParams extends RunnersRateLimitPolicy {
+  action: RunnersRateLimitAction;
+  scope: RunnersRateLimitScope;
+  identifier: string;
+  now?: Date | undefined;
+  timeoutMs?: number | undefined;
+}
+
+export class RunnersRateLimitExceededError extends RateLimitExceededError<
+  RunnersRateLimitAction,
+  RunnersRateLimitScope
+> {
+  constructor(params: {
+    action: RunnersRateLimitAction;
+    scope: RunnersRateLimitScope;
+    retryAfterSeconds: number;
+    identifierHmacPrefix: string;
+  }) {
+    super(params);
+    this.name = 'RunnersRateLimitExceededError';
+  }
+}
+
+export class RunnersRateLimitUnavailableError extends RateLimitUnavailableError<
+  RunnersRateLimitAction,
+  RunnersRateLimitScope
+> {
+  constructor(params: {
+    action: RunnersRateLimitAction;
+    scope: RunnersRateLimitScope;
+    identifierHmacPrefix: string;
+    cause: unknown;
+  }) {
+    super(params);
+    this.name = 'RunnersRateLimitUnavailableError';
+  }
+}
+
+const IDENTIFIER_HASH_DOMAIN = 'shipfox.runners.rate-limit.identifier.v1';
+const IDENTIFIER_SECRET_DERIVATION_DOMAIN = 'shipfox.runners.rate-limit.identifier-secret.v1';
+
+export function hashRunnersRateLimitIdentifier(params: {
+  action: RunnersRateLimitAction;
+  scope: RunnersRateLimitScope;
+  identifier: string;
+}): string {
+  return hashRateLimitIdentifier({
+    action: params.action,
+    scope: params.scope,
+    identifier: params.identifier,
+    secret: effectiveIdentifierSecret(),
+    domain: IDENTIFIER_HASH_DOMAIN,
+  });
+}
+
+export async function checkRunnersRateLimit(params: CheckRunnersRateLimitParams): Promise<void> {
+  try {
+    await checkRateLimit({
+      action: params.action,
+      scope: params.scope,
+      identifier: params.identifier,
+      limit: params.limit,
+      windowSeconds: params.windowSeconds,
+      identifierSecret: effectiveIdentifierSecret(),
+      identifierHashDomain: IDENTIFIER_HASH_DOMAIN,
+      consume: consumeRunnersRateLimit,
+      prune: pruneExpiredRunnersRateLimits,
+      onCheck: recordRunnersRateLimitCheck,
+      onPruneFailure: recordRunnersRateLimitPruneFailure,
+      now: params.now,
+      timeoutMs: params.timeoutMs ?? config.RUNNERS_RATE_LIMIT_TIMEOUT_MS,
+    });
+  } catch (error) {
+    if (error instanceof RateLimitExceededError) {
+      throw new RunnersRateLimitExceededError({
+        action: error.action,
+        scope: error.scope,
+        retryAfterSeconds: error.retryAfterSeconds,
+        identifierHmacPrefix: error.identifierHmacPrefix,
+      });
+    }
+    if (error instanceof RateLimitUnavailableError) {
+      throw new RunnersRateLimitUnavailableError({
+        action: error.action,
+        scope: error.scope,
+        identifierHmacPrefix: error.identifierHmacPrefix,
+        cause: error.cause,
+      });
+    }
+    throw error;
+  }
+}
+
+function effectiveIdentifierSecret(): Buffer | string {
+  if (config.RATE_LIMIT_IDENTIFIER_SECRET) {
+    return config.RATE_LIMIT_IDENTIFIER_SECRET;
+  }
+
+  return createHmac('sha256', authConfig.AUTH_JWT_SECRET)
+    .update(IDENTIFIER_SECRET_DERIVATION_DOMAIN)
+    .digest();
+}