@shipfox/api-auth 2.0.0

package/src/core/errors.ts

@@ -0,0 +1,123 @@
+export class WorkspaceNotFoundError extends Error {
+  constructor(workspaceId: string) {
+    super(`Workspace not found: ${workspaceId}`);
+    this.name = 'WorkspaceNotFoundError';
+  }
+}
+
+export class ApiKeyNotFoundError extends Error {
+  constructor(id: string) {
+    super(`API key not found: ${id}`);
+    this.name = 'ApiKeyNotFoundError';
+  }
+}
+
+export class InvitationNotFoundError extends Error {
+  constructor(id: string) {
+    super(`Invitation not found: ${id}`);
+    this.name = 'InvitationNotFoundError';
+  }
+}
+
+export class InvitationWorkspaceMismatchError extends Error {
+  constructor() {
+    super('Invitation does not belong to this workspace');
+    this.name = 'InvitationWorkspaceMismatchError';
+  }
+}
+
+export class MembershipNotFoundError extends Error {
+  constructor(userId: string, workspaceId: string) {
+    super(`Membership not found for user ${userId} in workspace ${workspaceId}`);
+    this.name = 'MembershipNotFoundError';
+  }
+}
+
+export class UserNotFoundError extends Error {
+  constructor(idOrEmail: string) {
+    super(`User not found: ${idOrEmail}`);
+    this.name = 'UserNotFoundError';
+  }
+}
+
+export class EmailTakenError extends Error {
+  constructor(email: string) {
+    super(`Email already registered: ${email}`);
+    this.name = 'EmailTakenError';
+  }
+}
+
+export class InvalidCredentialsError extends Error {
+  constructor() {
+    super('Invalid credentials');
+    this.name = 'InvalidCredentialsError';
+  }
+}
+
+export class EmailNotVerifiedError extends Error {
+  constructor() {
+    super('Email not verified');
+    this.name = 'EmailNotVerifiedError';
+  }
+}
+
+export class AuthDependencyUnavailableError extends Error {
+  readonly dependency: string;
+  override readonly cause: unknown;
+
+  constructor(dependency: string, cause: unknown) {
+    super(`Authentication dependency unavailable: ${dependency}`);
+    this.name = 'AuthDependencyUnavailableError';
+    this.dependency = dependency;
+    this.cause = cause;
+  }
+}
+
+export class TokenInvalidError extends Error {
+  constructor(reason?: string) {
+    super(reason ? `Invalid token: ${reason}` : 'Invalid token');
+    this.name = 'TokenInvalidError';
+  }
+}
+
+export class TokenExpiredError extends Error {
+  constructor() {
+    super('Token has expired');
+    this.name = 'TokenExpiredError';
+  }
+}
+
+export class TokenAlreadyUsedError extends Error {
+  constructor() {
+    super('Token has already been used');
+    this.name = 'TokenAlreadyUsedError';
+  }
+}
+
+export class MembershipRequiredError extends Error {
+  constructor(workspaceId: string) {
+    super(`Membership required for workspace: ${workspaceId}`);
+    this.name = 'MembershipRequiredError';
+  }
+}
+
+export class LastMemberError extends Error {
+  constructor(workspaceId: string) {
+    super(`Cannot remove the last member of workspace: ${workspaceId}`);
+    this.name = 'LastMemberError';
+  }
+}
+
+export class InvitationEmailMismatchError extends Error {
+  constructor() {
+    super('Invitation email does not match authenticated user');
+    this.name = 'InvitationEmailMismatchError';
+  }
+}
+
+export class OpenInvitationExistsError extends Error {
+  constructor(email: string) {
+    super(`An open invitation already exists for: ${email}`);
+    this.name = 'OpenInvitationExistsError';
+  }
+}

package/src/core/job-lease-token.test.ts

@@ -0,0 +1,201 @@
+import {JOB_LEASE_TOKEN_AUDIENCE} from '@shipfox/api-auth-dto';
+import {signHs256} from '@shipfox/node-jwt';
+import {issueJobLeaseToken, verifyJobLeaseToken} from './job-lease-token.js';
+
+// Matches test/env.ts; the codec reads this same value from config.
+const SECRET = process.env.AUTH_JOB_LEASE_TOKEN_SECRET ?? 'test-lease-secret';
+
+function claims() {
+  return {
+    workflowRunId: crypto.randomUUID(),
+    workflowRunAttemptId: crypto.randomUUID(),
+    jobId: crypto.randomUUID(),
+    jobExecutionId: crypto.randomUUID(),
+    projectId: crypto.randomUUID(),
+    workspaceId: crypto.randomUUID(),
+    runnerSessionId: crypto.randomUUID(),
+  };
+}
+
+describe('job-lease-token', () => {
+  test('issues a token that verifies round-trip', async () => {
+    const input = claims();
+
+    const token = await issueJobLeaseToken(input);
+    const verified = await verifyJobLeaseToken(token);
+
+    expect(verified).not.toBeNull();
+    expect(verified?.workflowRunId).toBe(input.workflowRunId);
+    expect(verified?.workflowRunAttemptId).toBe(input.workflowRunAttemptId);
+    expect(verified?.jobId).toBe(input.jobId);
+    expect(verified?.projectId).toBe(input.projectId);
+    expect(verified?.workspaceId).toBe(input.workspaceId);
+    expect(verified?.runnerSessionId).toBe(input.runnerSessionId);
+    expect(verified?.aud).toBe(JOB_LEASE_TOKEN_AUDIENCE);
+    expect(verified?.iat).toBeTypeOf('number');
+    expect(verified?.exp).toBeGreaterThan(verified?.iat ?? 0);
+  });
+
+  test('omits step scope when issuing a job-scoped token', async () => {
+    const input = claims();
+
+    const token = await issueJobLeaseToken(input);
+    const verified = await verifyJobLeaseToken(token);
+
+    expect(verified?.currentStepId).toBeUndefined();
+    expect(verified?.currentStepAttempt).toBeUndefined();
+  });
+
+  test('round-trips the current step scope when present', async () => {
+    const input = {
+      ...claims(),
+      currentStepId: crypto.randomUUID(),
+      currentStepAttempt: 2,
+    };
+
+    const token = await issueJobLeaseToken(input);
+    const verified = await verifyJobLeaseToken(token);
+
+    expect(verified?.currentStepId).toBe(input.currentStepId);
+    expect(verified?.currentStepAttempt).toBe(input.currentStepAttempt);
+  });
+
+  test('returns claims when metric recording fails after successful verification', async () => {
+    vi.resetModules();
+    vi.doMock('@shipfox/node-opentelemetry', () => ({
+      instanceMetrics: {
+        getMeter: () => ({
+          createCounter: () => ({
+            add: () => {
+              throw new Error('metrics unavailable');
+            },
+          }),
+        }),
+      },
+    }));
+
+    try {
+      const tokenModule = await import('./job-lease-token.js');
+      const input = claims();
+
+      const token = await tokenModule.issueJobLeaseToken(input);
+      const verified = await tokenModule.verifyJobLeaseToken(token);
+
+      expect(verified?.jobId).toBe(input.jobId);
+    } finally {
+      vi.doUnmock('@shipfox/node-opentelemetry');
+      vi.resetModules();
+    }
+  });
+
+  test('accepts UUIDv7 ids (job/run primary keys are uuidv7)', async () => {
+    const input = {
+      workflowRunId: '018f6b1e-7e2a-7b3c-8d4e-5f6a7b8c9d0d',
+      workflowRunAttemptId: '018f6b1e-7e2a-7b3c-8d4e-5f6a7b8c9d0f',
+      jobId: '018f6b1e-7e2a-7b3c-8d4e-5f6a7b8c9d0e',
+      jobExecutionId: '018f6b1e-7e2a-7b3c-8d4e-5f6a7b8c9d10',
+      projectId: crypto.randomUUID(),
+      workspaceId: crypto.randomUUID(),
+      runnerSessionId: crypto.randomUUID(),
+    };
+
+    const token = await issueJobLeaseToken(input);
+    const verified = await verifyJobLeaseToken(token);
+
+    expect(verified?.workflowRunId).toBe(input.workflowRunId);
+    expect(verified?.workflowRunAttemptId).toBe(input.workflowRunAttemptId);
+    expect(verified?.jobId).toBe(input.jobId);
+  });
+
+  test('returns null for a tampered token', async () => {
+    const token = await issueJobLeaseToken(claims());
+    const tampered = `${token.slice(0, -4)}xxxx`;
+
+    const verified = await verifyJobLeaseToken(tampered);
+
+    expect(verified).toBeNull();
+  });
+
+  test('returns null for a token signed with a different secret', async () => {
+    const token = await signHs256({
+      payload: claims(),
+      secret: 'a-different-secret',
+      expiresIn: '90m',
+      audience: JOB_LEASE_TOKEN_AUDIENCE,
+    });
+
+    const verified = await verifyJobLeaseToken(token);
+
+    expect(verified).toBeNull();
+  });
+
+  test('returns null for an expired token', async () => {
+    const token = await signHs256({
+      payload: claims(),
+      secret: SECRET,
+      expiresIn: '-1s',
+      audience: JOB_LEASE_TOKEN_AUDIENCE,
+    });
+
+    const verified = await verifyJobLeaseToken(token);
+
+    expect(verified).toBeNull();
+  });
+
+  test.each(['not.a.token', '', 'a.b.c'])('returns null for invalid input %j', async (input) => {
+    const verified = await verifyJobLeaseToken(input);
+
+    expect(verified).toBeNull();
+  });
+
+  test('returns null for a token with the wrong audience', async () => {
+    const token = await signHs256({
+      payload: claims(),
+      secret: SECRET,
+      expiresIn: '90m',
+      audience: 'some-other-audience',
+    });
+
+    const verified = await verifyJobLeaseToken(token);
+
+    expect(verified).toBeNull();
+  });
+
+  test('returns null for a token with no audience claim', async () => {
+    const token = await signHs256({
+      payload: claims(),
+      secret: SECRET,
+      expiresIn: '90m',
+    });
+
+    const verified = await verifyJobLeaseToken(token);
+
+    expect(verified).toBeNull();
+  });
+
+  test('returns null for a token whose claims fail the schema (non-uuid jobId)', async () => {
+    const token = await signHs256({
+      payload: {...claims(), jobId: 'not-a-uuid'},
+      secret: SECRET,
+      expiresIn: '90m',
+      audience: JOB_LEASE_TOKEN_AUDIENCE,
+    });
+
+    const verified = await verifyJobLeaseToken(token);
+
+    expect(verified).toBeNull();
+  });
+
+  test('returns null for a token whose claims fail the schema (non-uuid projectId)', async () => {
+    const token = await signHs256({
+      payload: {...claims(), projectId: 'not-a-uuid'},
+      secret: SECRET,
+      expiresIn: '90m',
+      audience: JOB_LEASE_TOKEN_AUDIENCE,
+    });
+
+    const verified = await verifyJobLeaseToken(token);
+
+    expect(verified).toBeNull();
+  });
+});

package/src/core/job-lease-token.ts

@@ -0,0 +1,83 @@
+import {
+  JOB_LEASE_TOKEN_AUDIENCE,
+  type JobLeaseTokenClaims,
+  jobLeaseTokenClaimsSchema,
+} from '@shipfox/api-auth-dto';
+import {signHs256, verifyHs256} from '@shipfox/node-jwt';
+import {config} from '#config.js';
+import {recordTokenIssued, recordTokenVerified} from '#metrics/index.js';
+
+// `aud`, `iat` and `exp` are set by the codec (jose); callers supply the business ids only.
+export type IssueJobLeaseTokenParams = Omit<JobLeaseTokenClaims, 'aud' | 'iat' | 'exp'>;
+
+type JobLeaseParamSource = Pick<
+  JobLeaseTokenClaims,
+  | 'workflowRunId'
+  | 'workflowRunAttemptId'
+  | 'jobId'
+  | 'jobExecutionId'
+  | 'projectId'
+  | 'workspaceId'
+  | 'runnerSessionId'
+>;
+
+export function jobLeaseParamsFrom(
+  source: JobLeaseParamSource,
+  stepScope?: {currentStepId: string; currentStepAttempt: number},
+): IssueJobLeaseTokenParams {
+  return {
+    workflowRunId: source.workflowRunId,
+    workflowRunAttemptId: source.workflowRunAttemptId,
+    jobId: source.jobId,
+    jobExecutionId: source.jobExecutionId,
+    projectId: source.projectId,
+    workspaceId: source.workspaceId,
+    runnerSessionId: source.runnerSessionId,
+    ...(stepScope ? stepScope : {}),
+  };
+}
+
+export async function issueJobLeaseToken(claims: IssueJobLeaseTokenParams): Promise<string> {
+  const token = await signHs256({
+    payload: {
+      workflowRunId: claims.workflowRunId,
+      ...(claims.workflowRunAttempt === undefined
+        ? {}
+        : {workflowRunAttempt: claims.workflowRunAttempt}),
+      workflowRunAttemptId: claims.workflowRunAttemptId,
+      jobId: claims.jobId,
+      jobExecutionId: claims.jobExecutionId,
+      projectId: claims.projectId,
+      workspaceId: claims.workspaceId,
+      runnerSessionId: claims.runnerSessionId,
+      ...(claims.currentStepId && claims.currentStepAttempt !== undefined
+        ? {
+            currentStepId: claims.currentStepId,
+            currentStepAttempt: claims.currentStepAttempt,
+          }
+        : {}),
+    },
+    secret: config.AUTH_JOB_LEASE_TOKEN_SECRET,
+    expiresIn: config.AUTH_JOB_LEASE_TOKEN_EXPIRES_IN,
+    audience: JOB_LEASE_TOKEN_AUDIENCE,
+  });
+  recordTokenIssued('job_lease');
+  return token;
+}
+
+/** Returns the claims on success, or `null` for any invalid input — never throws. */
+export async function verifyJobLeaseToken(token: string): Promise<JobLeaseTokenClaims | null> {
+  try {
+    const claims = await verifyHs256({
+      token,
+      secret: config.AUTH_JOB_LEASE_TOKEN_SECRET,
+      schema: jobLeaseTokenClaimsSchema,
+      audience: JOB_LEASE_TOKEN_AUDIENCE,
+    });
+    recordTokenVerified('job_lease', 'ok');
+    return claims;
+  } catch {
+    recordTokenVerified('job_lease', 'rejected');
+    return null;
+  }
+}

package/src/core/jwt.test.ts

@@ -0,0 +1,180 @@
+import {SignJWT} from 'jose';
+import {signUserToken, type TokenMembership, verifyUserToken} from './jwt.js';
+
+const SECRET = 'test-secret-do-not-use-in-prod';
+
+function encodeSecret(secret: string): Uint8Array {
+  return new TextEncoder().encode(secret);
+}
+
+describe('jwt', () => {
+  test('signs a token with memberships and verifies it round-trip', async () => {
+    const userId = crypto.randomUUID();
+    const email = `jwt-${crypto.randomUUID()}@example.com`;
+    const memberships: TokenMembership[] = [
+      {workspaceId: crypto.randomUUID(), role: 'admin'},
+      {workspaceId: crypto.randomUUID(), role: 'admin'},
+    ];
+
+    const token = await signUserToken({
+      userId,
+      email,
+      name: 'Token User',
+      memberships,
+      secret: SECRET,
+      expiresIn: '7d',
+    });
+    const claims = await verifyUserToken({token, secret: SECRET});
+
+    expect(claims.sub).toBe(userId);
+    expect(claims.email).toBe(email);
+    expect(claims.name).toBe('Token User');
+    expect(claims.memberships).toEqual(memberships);
+    expect(claims.iat).toBeTypeOf('number');
+    expect(claims.exp).toBeGreaterThan(claims.iat);
+  });
+
+  test('signs and verifies a token with empty memberships', async () => {
+    const userId = crypto.randomUUID();
+    const email = `jwt-${crypto.randomUUID()}@example.com`;
+
+    const token = await signUserToken({
+      userId,
+      email,
+      memberships: [],
+      secret: SECRET,
+      expiresIn: '7d',
+    });
+    const claims = await verifyUserToken({token, secret: SECRET});
+
+    expect(claims.memberships).toEqual([]);
+  });
+
+  test('verifies legacy tokens without a name claim', async () => {
+    const userId = crypto.randomUUID();
+    const email = `jwt-${crypto.randomUUID()}@example.com`;
+    const token = await new SignJWT({email, memberships: []})
+      .setProtectedHeader({alg: 'HS256'})
+      .setSubject(userId)
+      .setIssuedAt()
+      .setExpirationTime('7d')
+      .sign(encodeSecret(SECRET));
+
+    const claims = await verifyUserToken({token, secret: SECRET});
+
+    expect(claims.sub).toBe(userId);
+    expect(claims.email).toBe(email);
+    expect(claims.name).toBeUndefined();
+  });
+
+  test('rejects expired token', async () => {
+    const userId = crypto.randomUUID();
+    const token = await signUserToken({
+      userId,
+      email: `jwt-${crypto.randomUUID()}@example.com`,
+      memberships: [],
+      secret: SECRET,
+      expiresIn: '-1s',
+    });
+
+    await expect(verifyUserToken({token, secret: SECRET})).rejects.toThrow();
+  });
+
+  test('rejects tampered signature', async () => {
+    const userId = crypto.randomUUID();
+    const token = await signUserToken({
+      userId,
+      email: `jwt-${crypto.randomUUID()}@example.com`,
+      memberships: [],
+      secret: SECRET,
+      expiresIn: '7d',
+    });
+    const tampered = `${token.slice(0, -4)}xxxx`;
+
+    await expect(verifyUserToken({token: tampered, secret: SECRET})).rejects.toThrow();
+  });
+
+  test('rejects malformed token', async () => {
+    await expect(verifyUserToken({token: 'not.a.token', secret: SECRET})).rejects.toThrow();
+  });
+
+  test('rejects token signed with different secret', async () => {
+    const userId = crypto.randomUUID();
+    const token = await signUserToken({
+      userId,
+      email: `jwt-${crypto.randomUUID()}@example.com`,
+      memberships: [],
+      secret: SECRET,
+      expiresIn: '7d',
+    });
+
+    await expect(verifyUserToken({token, secret: 'different-secret'})).rejects.toThrow();
+  });
+
+  test('rejects a token with missing memberships claim', async () => {
+    const token = await new SignJWT({email: `jwt-${crypto.randomUUID()}@example.com`})
+      .setProtectedHeader({alg: 'HS256'})
+      .setSubject(crypto.randomUUID())
+      .setIssuedAt()
+      .setExpirationTime('7d')
+      .sign(encodeSecret(SECRET));
+
+    await expect(verifyUserToken({token, secret: SECRET})).rejects.toThrow();
+  });
+
+  test('rejects a token whose memberships is not an array', async () => {
+    const token = await new SignJWT({
+      email: `jwt-${crypto.randomUUID()}@example.com`,
+      memberships: 'not-an-array',
+    })
+      .setProtectedHeader({alg: 'HS256'})
+      .setSubject(crypto.randomUUID())
+      .setIssuedAt()
+      .setExpirationTime('7d')
+      .sign(encodeSecret(SECRET));
+
+    await expect(verifyUserToken({token, secret: SECRET})).rejects.toThrow();
+  });
+
+  test('rejects a token with non-UUID workspaceId in memberships', async () => {
+    const token = await new SignJWT({
+      email: `jwt-${crypto.randomUUID()}@example.com`,
+      memberships: [{workspaceId: 'not-a-uuid', role: 'admin'}],
+    })
+      .setProtectedHeader({alg: 'HS256'})
+      .setSubject(crypto.randomUUID())
+      .setIssuedAt()
+      .setExpirationTime('7d')
+      .sign(encodeSecret(SECRET));
+
+    await expect(verifyUserToken({token, secret: SECRET})).rejects.toThrow();
+  });
+
+  test('rejects a token with unknown role value', async () => {
+    const token = await new SignJWT({
+      email: `jwt-${crypto.randomUUID()}@example.com`,
+      memberships: [{workspaceId: crypto.randomUUID(), role: 'owner'}],
+    })
+      .setProtectedHeader({alg: 'HS256'})
+      .setSubject(crypto.randomUUID())
+      .setIssuedAt()
+      .setExpirationTime('7d')
+      .sign(encodeSecret(SECRET));
+
+    await expect(verifyUserToken({token, secret: SECRET})).rejects.toThrow();
+  });
+
+  test('rejects a token with non-UUID sub', async () => {
+    const token = await new SignJWT({
+      email: `jwt-${crypto.randomUUID()}@example.com`,
+      memberships: [],
+    })
+      .setProtectedHeader({alg: 'HS256'})
+      .setSubject('not-a-uuid')
+      .setIssuedAt()
+      .setExpirationTime('7d')
+      .sign(encodeSecret(SECRET));
+
+    await expect(verifyUserToken({token, secret: SECRET})).rejects.toThrow();
+  });
+});

package/src/core/jwt.ts

@@ -0,0 +1,66 @@
+import {workspaceRoleSchema} from '@shipfox/api-workspaces-dto';
+import {signHs256, verifyHs256} from '@shipfox/node-jwt';
+import {z} from 'zod';
+import {recordTokenIssued, recordTokenVerified} from '#metrics/index.js';
+
+export const tokenMembershipSchema = z.object({
+  workspaceId: z.string().uuid(),
+  role: workspaceRoleSchema,
+});
+
+export type TokenMembership = z.infer<typeof tokenMembershipSchema>;
+
+export const userTokenClaimsSchema = z.object({
+  sub: z.string().uuid(),
+  email: z.string().email(),
+  name: z.string().nullable().optional(),
+  memberships: z.array(tokenMembershipSchema),
+  iat: z.number().int(),
+  exp: z.number().int(),
+});
+
+export type UserTokenClaims = z.infer<typeof userTokenClaimsSchema>;
+
+export interface SignUserTokenParams {
+  userId: string;
+  email: string;
+  name?: string | null | undefined;
+  memberships: TokenMembership[];
+  secret: string;
+  expiresIn: string;
+}
+
+export interface VerifyUserTokenParams {
+  token: string;
+  secret: string;
+}
+
+export async function signUserToken(params: SignUserTokenParams): Promise<string> {
+  const token = await signHs256({
+    payload: {
+      email: params.email,
+      name: params.name ?? null,
+      memberships: params.memberships,
+    },
+    secret: params.secret,
+    expiresIn: params.expiresIn,
+    subject: params.userId,
+  });
+  recordTokenIssued('session');
+  return token;
+}
+
+export async function verifyUserToken(params: VerifyUserTokenParams): Promise<UserTokenClaims> {
+  try {
+    const claims = await verifyHs256({
+      token: params.token,
+      secret: params.secret,
+      schema: userTokenClaimsSchema,
+    });
+    recordTokenVerified('session', 'ok');
+    return claims;
+  } catch (error) {
+    recordTokenVerified('session', 'rejected');
+    throw error;
+  }
+}

package/src/core/password.test.ts

@@ -0,0 +1,28 @@
+import {hashPassword, verifyPassword} from './password.js';
+
+describe('password', () => {
+  test('hashes a password and verifies it (roundtrip)', async () => {
+    const password = 'correct horse battery staple';
+
+    const hash = await hashPassword({password});
+    const ok = await verifyPassword({password, hash});
+
+    expect(hash).not.toBe(password);
+    expect(hash.startsWith('$argon2')).toBe(true);
+    expect(ok).toBe(true);
+  });
+
+  test('rejects wrong password', async () => {
+    const hash = await hashPassword({password: 'correct horse battery staple'});
+
+    const ok = await verifyPassword({password: 'wrong password', hash});
+
+    expect(ok).toBe(false);
+  });
+
+  test('throws on a corrupt hash string', async () => {
+    await expect(
+      verifyPassword({password: 'anything', hash: 'not-an-argon2-hash'}),
+    ).rejects.toThrow();
+  });
+});

package/src/core/password.ts

@@ -0,0 +1,21 @@
+import {hash, verify} from '@node-rs/argon2';
+
+export interface HashPasswordParams {
+  password: string;
+}
+
+export interface VerifyPasswordParams {
+  password: string;
+  hash: string;
+}
+
+// Algorithm.Argon2id = 2; using literal here to avoid const-enum import under verbatimModuleSyntax.
+const HASH_OPTIONS = {algorithm: 2} as const;
+
+export function hashPassword(params: HashPasswordParams): Promise<string> {
+  return hash(params.password, HASH_OPTIONS);
+}
+
+export function verifyPassword(params: VerifyPasswordParams): Promise<boolean> {
+  return verify(params.hash, params.password);
+}