@shipfox/api-auth 2.0.0

package/src/metrics/instance.test.ts

@@ -0,0 +1,69 @@
+const metricMocks = vi.hoisted(() => {
+  const counters = new Map<string, {add: ReturnType<typeof vi.fn>}>();
+  const createCounter = vi.fn((name: string) => {
+    const counter = {add: vi.fn()};
+    counters.set(name, counter);
+    return counter;
+  });
+
+  return {counters, createCounter};
+});
+
+vi.mock('@shipfox/node-opentelemetry', () => ({
+  instanceMetrics: {
+    getMeter: () => ({
+      createCounter: metricMocks.createCounter,
+    }),
+  },
+}));
+
+const metrics = await import('./instance.js');
+
+function counterAdd(name: string): ReturnType<typeof vi.fn> {
+  const counter = metricMocks.counters.get(name);
+  if (!counter) throw new Error(`Missing counter: ${name}`);
+  return counter.add;
+}
+
+describe('auth metrics', () => {
+  beforeEach(() => {
+    for (const counter of metricMocks.counters.values()) {
+      counter.add.mockReset();
+    }
+  });
+
+  it('records auth rate-limit checks with low-cardinality labels', () => {
+    metrics.recordAuthRateLimitCheck({
+      action: 'login',
+      scope: 'ip',
+      outcome: 'blocked',
+    });
+
+    expect(counterAdd('auth_rate_limit_checks')).toHaveBeenCalledWith(1, {
+      action: 'login',
+      scope: 'ip',
+      outcome: 'blocked',
+    });
+  });
+
+  it('records auth rate-limit prune failures', () => {
+    metrics.recordAuthRateLimitPruneFailure();
+
+    expect(counterAdd('auth_rate_limit_prune_failures')).toHaveBeenCalledWith(1);
+  });
+
+  it('does not let metric failures affect callers', () => {
+    counterAdd('auth_rate_limit_checks').mockImplementationOnce(() => {
+      throw new Error('metrics unavailable');
+    });
+
+    const act = () =>
+      metrics.recordAuthRateLimitCheck({
+        action: 'email-send',
+        scope: 'email',
+        outcome: 'unavailable',
+      });
+
+    expect(act).not.toThrow();
+  });
+});

package/src/metrics/instance.ts

@@ -0,0 +1,77 @@
+import {instanceMetrics} from '@shipfox/node-opentelemetry';
+
+export type AuthTokenType = 'session' | 'job_lease' | 'runner_session';
+export type AuthTokenVerificationOutcome = 'ok' | 'rejected';
+export type AuthTokenRefreshOutcome = 'rotated' | 'grace' | 'rejected';
+export type AuthRateLimitAction = 'login' | 'email-send';
+export type AuthRateLimitScope = 'ip' | 'email';
+export type AuthRateLimitOutcome = 'allowed' | 'blocked' | 'unavailable';
+
+const meter = instanceMetrics.getMeter('auth');
+
+const tokenIssuedCount = meter.createCounter<{token_type: AuthTokenType}>('auth_token_issued', {
+  description: 'Tokens issued by token type',
+});
+
+const tokenVerifiedCount = meter.createCounter<{
+  token_type: AuthTokenType;
+  outcome: AuthTokenVerificationOutcome;
+}>('auth_token_verified', {description: 'Token verification attempts by token type and outcome'});
+
+const tokenRefreshedCount = meter.createCounter<{outcome: AuthTokenRefreshOutcome}>(
+  'auth_token_refreshed',
+  {description: 'Refresh-token exchanges by outcome'},
+);
+
+const rateLimitCheckCount = meter.createCounter<{
+  action: AuthRateLimitAction;
+  scope: AuthRateLimitScope;
+  outcome: AuthRateLimitOutcome;
+}>('auth_rate_limit_checks', {
+  description: 'Authentication rate limit checks by action, scope, and outcome',
+});
+
+const rateLimitPruneFailureCount = meter.createCounter('auth_rate_limit_prune_failures', {
+  description: 'Authentication rate limit prune failures',
+});
+
+function recordMetric(record: () => void): void {
+  try {
+    record();
+  } catch {
+    // Metrics must not affect authentication outcomes.
+  }
+}
+
+export function recordTokenIssued(tokenType: AuthTokenType): void {
+  recordMetric(() => tokenIssuedCount.add(1, {token_type: tokenType}));
+}
+
+export function recordTokenVerified(
+  tokenType: AuthTokenType,
+  outcome: AuthTokenVerificationOutcome,
+): void {
+  recordMetric(() => tokenVerifiedCount.add(1, {token_type: tokenType, outcome}));
+}
+
+export function recordTokenRefreshed(outcome: AuthTokenRefreshOutcome): void {
+  recordMetric(() => tokenRefreshedCount.add(1, {outcome}));
+}
+
+export function recordAuthRateLimitCheck(params: {
+  action: AuthRateLimitAction;
+  scope: AuthRateLimitScope;
+  outcome: AuthRateLimitOutcome;
+}): void {
+  recordMetric(() =>
+    rateLimitCheckCount.add(1, {
+      action: params.action,
+      scope: params.scope,
+      outcome: params.outcome,
+    }),
+  );
+}
+
+export function recordAuthRateLimitPruneFailure(): void {
+  recordMetric(() => rateLimitPruneFailureCount.add(1));
+}

package/src/presentation/auth/bearer-token-auth.test.ts

@@ -0,0 +1,99 @@
+import {errorHandler} from '@shipfox/node-fastify';
+import type {FastifyInstance, FastifyRequest} from 'fastify';
+import Fastify from 'fastify';
+import {serializerCompiler, validatorCompiler} from 'fastify-type-provider-zod';
+import {createBearerTokenAuthMethod} from './bearer-token-auth.js';
+
+const CONTEXT_KEY = 'testContext';
+
+interface TestClaims {
+  subject: string;
+}
+
+describe('bearer-token-auth', () => {
+  let app: FastifyInstance;
+  let verifyToken: ReturnType<typeof vi.fn<(token: string) => Promise<TestClaims | null>>>;
+
+  beforeEach(async () => {
+    verifyToken = vi.fn<(token: string) => Promise<TestClaims | null>>();
+    app = Fastify();
+    app.setValidatorCompiler(validatorCompiler);
+    app.setSerializerCompiler(serializerCompiler);
+    app.setErrorHandler(errorHandler);
+
+    const authMethod = createBearerTokenAuthMethod({
+      name: 'test-bearer',
+      verifyToken,
+      invalidTokenError: {message: 'Invalid test bearer token', code: 'invalid-test-token'},
+      setContext: (request, claims) => {
+        (request as FastifyRequest & Record<typeof CONTEXT_KEY, typeof claims>)[CONTEXT_KEY] =
+          claims;
+      },
+    });
+
+    app.addHook('onRequest', async (request, reply) => {
+      await authMethod.authenticate(request, reply);
+    });
+
+    app.get('/protected', (request) => {
+      return {
+        context: (request as FastifyRequest & Record<typeof CONTEXT_KEY, unknown>)[CONTEXT_KEY],
+      };
+    });
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  test('valid bearer token sets context on the request', async () => {
+    verifyToken.mockResolvedValue({subject: 'runner-1'});
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/protected',
+      headers: {authorization: 'Bearer valid-token'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(verifyToken).toHaveBeenCalledWith('valid-token');
+    expect(res.json().context).toEqual({subject: 'runner-1'});
+  });
+
+  test('missing bearer token returns the shared unauthorized response', async () => {
+    const res = await app.inject({method: 'GET', url: '/protected'});
+
+    expect(res.statusCode).toBe(401);
+    expect(res.json()).toEqual({code: 'unauthorized'});
+    expect(verifyToken).not.toHaveBeenCalled();
+  });
+
+  test('invalid bearer token returns the configured unauthorized response', async () => {
+    verifyToken.mockResolvedValue(null);
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/protected',
+      headers: {authorization: 'Bearer invalid-token'},
+    });
+
+    expect(res.statusCode).toBe(401);
+    expect(res.json()).toEqual({code: 'invalid-test-token'});
+    expect(verifyToken).toHaveBeenCalledWith('invalid-token');
+  });
+
+  test('thrown verifier errors return the configured unauthorized response', async () => {
+    verifyToken.mockRejectedValue(new Error('bad signature'));
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/protected',
+      headers: {authorization: 'Bearer invalid-token'},
+    });
+
+    expect(res.statusCode).toBe(401);
+    expect(res.json()).toEqual({code: 'invalid-test-token'});
+    expect(verifyToken).toHaveBeenCalledWith('invalid-token');
+  });
+});

package/src/presentation/auth/bearer-token-auth.ts

@@ -0,0 +1,51 @@
+import {type AuthMethod, ClientError, extractBearerToken} from '@shipfox/node-fastify';
+import type {FastifyRequest} from 'fastify';
+
+interface UnauthorizedErrorParams {
+  message: string;
+  code: string;
+}
+
+interface BearerTokenAuthMethodOptions<TClaims> {
+  name: string;
+  verifyToken: (token: string) => Promise<TClaims | null>;
+  invalidTokenError: UnauthorizedErrorParams;
+  setContext: (request: FastifyRequest, claims: TClaims) => void;
+}
+
+const missingBearerError: UnauthorizedErrorParams = {
+  message: 'Missing or invalid Authorization header',
+  code: 'unauthorized',
+};
+
+export function createBearerTokenAuthMethod<TClaims>(
+  options: BearerTokenAuthMethodOptions<TClaims>,
+): AuthMethod {
+  return {
+    name: options.name,
+    authenticate: async (request) => {
+      const token = extractBearerToken(request.headers.authorization);
+      if (!token) throwUnauthorized(missingBearerError);
+
+      const claims = await verifyBearerToken(token, options.verifyToken);
+      if (!claims) throwUnauthorized(options.invalidTokenError);
+
+      options.setContext(request, claims);
+    },
+  };
+}
+
+async function verifyBearerToken<TClaims>(
+  token: string,
+  verifyToken: (token: string) => Promise<TClaims | null>,
+): Promise<TClaims | null> {
+  try {
+    return await verifyToken(token);
+  } catch {
+    return null;
+  }
+}
+
+function throwUnauthorized(error: UnauthorizedErrorParams): never {
+  throw new ClientError(error.message, error.code, {status: 401});
+}

package/src/presentation/auth/jwt-auth.test.ts

@@ -0,0 +1,136 @@
+import type {FastifyInstance} from 'fastify';
+import Fastify from 'fastify';
+import {serializerCompiler, validatorCompiler} from 'fastify-type-provider-zod';
+import {signUserToken} from '#core/jwt.js';
+import {createUser, findUserById} from '#db/users.js';
+import {createJwtAuthMethod, getClientContext} from './jwt-auth.js';
+
+const SECRET = 'test-secret';
+
+function emailFor(suffix: string): string {
+  return `${suffix}-${crypto.randomUUID()}@example.com`;
+}
+
+describe('jwt-auth', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = Fastify();
+    app.setValidatorCompiler(validatorCompiler);
+    app.setSerializerCompiler(serializerCompiler);
+
+    const authMethod = createJwtAuthMethod();
+    app.addHook('onRequest', async (request, reply) => {
+      await authMethod.authenticate(request, reply);
+    });
+
+    app.get('/protected', (request) => {
+      return {client: getClientContext(request)};
+    });
+    await app.ready();
+  });
+
+  test('decorates request.client on success', async () => {
+    const user = await createUser({email: emailFor('jwt-ok'), hashedPassword: 'h'});
+    const token = await signUserToken({
+      userId: user.id,
+      email: user.email,
+      name: 'JWT User',
+      memberships: [],
+      secret: SECRET,
+      expiresIn: '7d',
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/protected',
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().client.userId).toBe(user.id);
+    expect(res.json().client.email).toBe(user.email);
+    expect(res.json().client.name).toBe('JWT User');
+  });
+
+  test('401 on missing Authorization header', async () => {
+    const res = await app.inject({method: 'GET', url: '/protected'});
+
+    expect(res.statusCode).toBe(401);
+  });
+
+  test('401 on wrong scheme', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: '/protected',
+      headers: {authorization: 'Basic xxx'},
+    });
+
+    expect(res.statusCode).toBe(401);
+  });
+
+  test('401 on expired token', async () => {
+    const user = await createUser({email: emailFor('jwt-exp'), hashedPassword: 'h'});
+    const token = await signUserToken({
+      userId: user.id,
+      email: user.email,
+      memberships: [],
+      secret: SECRET,
+      expiresIn: '-1s',
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/protected',
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(401);
+  });
+
+  test('401 on tampered signature', async () => {
+    const user = await createUser({email: emailFor('jwt-tamper'), hashedPassword: 'h'});
+    const token = await signUserToken({
+      userId: user.id,
+      email: user.email,
+      memberships: [],
+      secret: SECRET,
+      expiresIn: '7d',
+    });
+    const tampered = `${token.slice(0, -4)}xxxx`;
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/protected',
+      headers: {authorization: `Bearer ${tampered}`},
+    });
+
+    expect(res.statusCode).toBe(401);
+  });
+
+  test('does not read user state during JWT validation', async () => {
+    const userId = crypto.randomUUID();
+    const email = emailFor('jwt-stateless');
+    const token = await signUserToken({
+      userId,
+      email,
+      memberships: [],
+      secret: SECRET,
+      expiresIn: '7d',
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/protected',
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().client.userId).toBe(userId);
+    expect(res.json().client.email).toBe(email);
+  });
+
+  test('helpers remain available', () => {
+    expect(typeof findUserById).toBe('function');
+  });
+});

package/src/presentation/auth/jwt-auth.ts

@@ -0,0 +1,39 @@
+import {
+  AUTH_USER,
+  buildUserContext,
+  getUserContext,
+  setUserContext,
+  type UserContext,
+} from '@shipfox/api-auth-context';
+import type {AuthMethod} from '@shipfox/node-fastify';
+import type {FastifyRequest} from 'fastify';
+import {config} from '#config.js';
+import {verifyUserToken} from '#core/jwt.js';
+import {createBearerTokenAuthMethod} from './bearer-token-auth.js';
+
+export type ClientContext = UserContext;
+
+export interface CreateJwtAuthMethodOptions {
+  secret: string;
+}
+
+export function getClientContext(request: FastifyRequest): ClientContext | null {
+  return getUserContext(request);
+}
+
+export function createJwtAuthMethod(): AuthMethod {
+  return createBearerTokenAuthMethod({
+    name: AUTH_USER,
+    verifyToken: (token) => verifyUserToken({token, secret: config.AUTH_JWT_SECRET}),
+    invalidTokenError: {message: 'Invalid or expired token', code: 'unauthorized'},
+    setContext: (request, claims) => {
+      const clientContext: ClientContext = buildUserContext({
+        userId: claims.sub,
+        email: claims.email,
+        name: claims.name ?? null,
+        memberships: claims.memberships,
+      });
+      setUserContext(request, clientContext);
+    },
+  });
+}

package/src/presentation/auth/lease-token-auth.test.ts

@@ -0,0 +1,56 @@
+import {getLeasedJobContext} from '@shipfox/api-auth-context';
+import {JOB_LEASE_TOKEN_AUDIENCE} from '@shipfox/api-auth-dto';
+import type {FastifyInstance} from 'fastify';
+import Fastify from 'fastify';
+import {serializerCompiler, validatorCompiler} from 'fastify-type-provider-zod';
+import {issueJobLeaseToken} from '#core/job-lease-token.js';
+import {createLeaseTokenAuthMethod} from './lease-token-auth.js';
+
+describe('lease-token-auth', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = Fastify();
+    app.setValidatorCompiler(validatorCompiler);
+    app.setSerializerCompiler(serializerCompiler);
+
+    const authMethod = createLeaseTokenAuthMethod();
+    app.addHook('onRequest', async (request, reply) => {
+      await authMethod.authenticate(request, reply);
+    });
+
+    app.get('/protected', (request) => {
+      return {leasedJob: getLeasedJobContext(request)};
+    });
+    await app.ready();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('valid lease token sets leased job context on the request', async () => {
+    const claims = {
+      workflowRunId: crypto.randomUUID(),
+      workflowRunAttemptId: crypto.randomUUID(),
+      jobId: crypto.randomUUID(),
+      jobExecutionId: crypto.randomUUID(),
+      projectId: crypto.randomUUID(),
+      workspaceId: crypto.randomUUID(),
+      runnerSessionId: crypto.randomUUID(),
+    };
+    const token = await issueJobLeaseToken(claims);
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/protected',
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().leasedJob).toMatchObject({
+      ...claims,
+      aud: JOB_LEASE_TOKEN_AUDIENCE,
+    });
+  });
+});

package/src/presentation/auth/lease-token-auth.ts

@@ -0,0 +1,25 @@
+import {AUTH_LEASED_JOB, setLeasedJobContext} from '@shipfox/api-auth-context';
+import type {AuthMethod} from '@shipfox/node-fastify';
+import {verifyJobLeaseToken} from '#core/job-lease-token.js';
+import {createBearerTokenAuthMethod} from './bearer-token-auth.js';
+
+/**
+ * Trust boundary: the signed token is the sole authority — `claims.jobId` scopes
+ * every runner request to exactly one job. `workflowRunId`/`workflowRunAttemptId`/`workspaceId`
+ * are carried for consumers but are NOT verified against the database here.
+ *
+ * Revocation tradeoff: `runnerSessionId` is carried in the claims but is not checked
+ * against runner-session storage, so a lease minted before its registration token is
+ * revoked stays usable until it expires (`AUTH_JOB_LEASE_TOKEN_EXPIRES_IN`, 90m).
+ * Accepted deliberately for a short-lived, job-scoped capability token; tightening
+ * this would mean a per-request DB lookup on the hot status-reporting path. See the
+ * "Security model" section in the package README for the full rationale.
+ */
+export function createLeaseTokenAuthMethod(): AuthMethod {
+  return createBearerTokenAuthMethod({
+    name: AUTH_LEASED_JOB,
+    verifyToken: verifyJobLeaseToken,
+    invalidTokenError: {message: 'Invalid or expired job lease token', code: 'unauthorized'},
+    setContext: setLeasedJobContext,
+  });
+}

package/src/presentation/auth/refresh-cookie.test.ts

@@ -0,0 +1,39 @@
+import fastify from 'fastify';
+import {authCookiePlugin, getRefreshTokenCookie, setRefreshTokenCookie} from '#index.js';
+
+vi.mock('#config.js', () => ({
+  config: {
+    AUTH_REFRESH_COOKIE_NAME: 'shipfox_refresh_token',
+    AUTH_REFRESH_TOKEN_EXPIRES_IN_DAYS: 14,
+  },
+}));
+
+describe('auth cookie extension point', () => {
+  test('a separately composed callback route can set and read the refresh cookie', async () => {
+    const app = fastify();
+    app.register(authCookiePlugin);
+    app.post('/auth/callbacks/session', (_request, reply) => {
+      setRefreshTokenCookie(reply, 'callback-refresh-token');
+      reply.code(204).send();
+    });
+    app.get('/auth/callbacks/session', (request) => ({
+      refresh_token: getRefreshTokenCookie(request) ?? null,
+    }));
+    await app.ready();
+
+    const callback = await app.inject({method: 'POST', url: '/auth/callbacks/session'});
+    const cookie = callback.headers['set-cookie'];
+    const session = await app.inject({
+      method: 'GET',
+      url: '/auth/callbacks/session',
+      headers: {cookie: Array.isArray(cookie) ? cookie[0] : cookie},
+    });
+
+    expect(callback.statusCode).toBe(204);
+    expect(cookie).toContain('shipfox_refresh_token=callback-refresh-token');
+    expect(cookie).toContain('Path=/auth');
+    expect(session.json()).toEqual({refresh_token: 'callback-refresh-token'});
+
+    await app.close();
+  });
+});

package/src/presentation/auth/refresh-cookie.ts

@@ -0,0 +1,34 @@
+import cookie from '@fastify/cookie';
+import type {FastifyReply, FastifyRequest} from 'fastify';
+import {config} from '#config.js';
+
+const REFRESH_COOKIE_PATH = '/auth';
+
+export const authCookiePlugin = cookie;
+
+function refreshCookieMaxAgeSeconds(): number {
+  return config.AUTH_REFRESH_TOKEN_EXPIRES_IN_DAYS * 24 * 60 * 60;
+}
+
+export function getRefreshTokenCookie(request: FastifyRequest): string | undefined {
+  return request.cookies[config.AUTH_REFRESH_COOKIE_NAME];
+}
+
+export function setRefreshTokenCookie(reply: FastifyReply, refreshToken: string): void {
+  reply.setCookie(config.AUTH_REFRESH_COOKIE_NAME, refreshToken, {
+    httpOnly: true,
+    secure: true,
+    sameSite: 'lax',
+    path: REFRESH_COOKIE_PATH,
+    maxAge: refreshCookieMaxAgeSeconds(),
+  });
+}
+
+export function clearRefreshTokenCookie(reply: FastifyReply): void {
+  reply.clearCookie(config.AUTH_REFRESH_COOKIE_NAME, {
+    httpOnly: true,
+    secure: true,
+    sameSite: 'lax',
+    path: REFRESH_COOKIE_PATH,
+  });
+}

package/src/presentation/auth/runner-session-auth.test.ts

@@ -0,0 +1,54 @@
+import {getRunnerSessionContext} from '@shipfox/api-auth-context';
+import {RUNNER_SESSION_TOKEN_AUDIENCE} from '@shipfox/api-auth-dto';
+import type {FastifyInstance} from 'fastify';
+import Fastify from 'fastify';
+import {serializerCompiler, validatorCompiler} from 'fastify-type-provider-zod';
+import {issueRunnerSessionToken} from '#core/runner-session-token.js';
+import {createRunnerSessionAuthMethod} from './runner-session-auth.js';
+
+describe('runner-session-auth', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = Fastify();
+    app.setValidatorCompiler(validatorCompiler);
+    app.setSerializerCompiler(serializerCompiler);
+
+    const authMethod = createRunnerSessionAuthMethod();
+    app.addHook('onRequest', async (request, reply) => {
+      await authMethod.authenticate(request, reply);
+    });
+
+    app.get('/protected', (request) => {
+      return {runnerSession: getRunnerSessionContext(request)};
+    });
+    await app.ready();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('valid session token sets runner session context on the request', async () => {
+    const claims = {
+      runnerSessionId: crypto.randomUUID(),
+      workspaceId: crypto.randomUUID(),
+      scope: 'workspace' as const,
+      labels: ['linux', 'x64'],
+      maxClaims: null,
+    };
+    const token = await issueRunnerSessionToken(claims);
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/protected',
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().runnerSession).toMatchObject({
+      ...claims,
+      aud: RUNNER_SESSION_TOKEN_AUDIENCE,
+    });
+  });
+});