feat(users): add GET /users/:id/key-fingerprint safety-number endpoint (#162)

Author: Themancalledpg

apps/backend/src/__tests__/users.fingerprint.test.ts

@@ -0,0 +1,169 @@
+/**
+ * Tests for GET /users/:id/key-fingerprint (issue #162)
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import request from 'supertest';
+import express from 'express';
+import { createHash } from 'node:crypto';
+
+// ── Mocks ─────────────────────────────────────────────────────────────────────
+
+const mockUserFindFirst = vi.fn();
+const mockDeviceFindFirst = vi.fn();
+const mockDeviceFindMany = vi.fn();
+
+vi.mock('../db/index.js', () => ({
+  db: {
+    query: {
+      users: { findFirst: mockUserFindFirst, findMany: vi.fn() },
+      devices: { findFirst: mockDeviceFindFirst, findMany: mockDeviceFindMany },
+      wallets: { findFirst: vi.fn() },
+    },
+    update: vi.fn(),
+    select: vi.fn(),
+  },
+}));
+
+vi.mock('../db/schema.js', () => ({
+  users: { id: 'id', username: 'username' },
+  wallets: {},
+  devices: { userId: 'userId', isRevoked: 'isRevoked' },
+}));
+
+vi.mock('drizzle-orm', () => ({
+  eq: vi.fn((col: unknown, val: unknown) => ({ col, val })),
+  and: vi.fn((...args: unknown[]) => args),
+  or: vi.fn((...args: unknown[]) => args),
+  ilike: vi.fn(),
+  exists: vi.fn(),
+  sql: vi.fn(),
+}));
+
+vi.mock('../lib/redis.js', () => ({
+  get redis() {
+    return null;
+  },
+}));
+
+vi.mock('../services/presence.js', () => ({
+  isOnline: vi.fn().mockResolvedValue(false),
+}));
+
+// Stub requireAuth — inject device-id so the real middleware path doesn't run.
+vi.mock('../middleware/auth.js', () => ({
+  requireAuth: (req: express.Request, _res: express.Response, next: express.NextFunction) => {
+    (req as express.Request & { auth: { userId: string } }).auth = { userId: 'caller-id' };
+    next();
+  },
+}));
+
+const { usersRouter } = await import('../routes/users.js');
+
+function makeApp() {
+  const app = express();
+  app.use(express.json());
+  app.use('/users', usersRouter);
+  return app;
+}
+
+// ── Fingerprint derivation helper (mirrors the route implementation) ──────────
+
+function deriveFingerprint(identityKeys: string[]): string {
+  const sorted = [...identityKeys].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  const concatenated = sorted.join('\n');
+  const digest = createHash('sha256').update(concatenated, 'utf8').digest();
+
+  function bytesToSegment(buf: Buffer, offset: number, length: number): string {
+    let value = BigInt(0);
+    for (let i = 0; i < length; i++) {
+      value = (value << BigInt(8)) | BigInt(buf[offset + i]!);
+    }
+    return (value % BigInt('1' + '0'.repeat(30))).toString().padStart(30, '0');
+  }
+
+  return bytesToSegment(digest, 0, 15) + bytesToSegment(digest, 15, 15);
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  // Default: authenticated device is active.
+  mockDeviceFindFirst.mockResolvedValue({ id: 'caller-device', isRevoked: false });
+});
+
+describe('GET /users/:id/key-fingerprint', () => {
+  it('returns 404 when user does not exist', async () => {
+    mockUserFindFirst.mockResolvedValue(undefined);
+
+    const res = await request(makeApp()).get('/users/unknown-id/key-fingerprint');
+
+    expect(res.status).toBe(404);
+    expect(res.body.error).toMatch(/not found/i);
+  });
+
+  it('returns 404 when user has no active devices', async () => {
+    mockUserFindFirst.mockResolvedValue({ id: 'user-1' });
+    mockDeviceFindMany.mockResolvedValue([]);
+
+    const res = await request(makeApp()).get('/users/user-1/key-fingerprint');
+
+    expect(res.status).toBe(404);
+    expect(res.body.error).toMatch(/no active devices/i);
+  });
+
+  it('returns a 60-digit fingerprint and 12 × 5-digit formatted safety number', async () => {
+    mockUserFindFirst.mockResolvedValue({ id: 'user-1' });
+    mockDeviceFindMany.mockResolvedValue([
+      { identityPublicKey: 'a2V5QQ==' },
+      { identityPublicKey: 'a2V5Qg==' },
+    ]);
+
+    const res = await request(makeApp()).get('/users/user-1/key-fingerprint');
+
+    expect(res.status).toBe(200);
+    expect(res.body).toHaveProperty('userId', 'user-1');
+    expect(res.body).toHaveProperty('fingerprint');
+    expect(res.body).toHaveProperty('formatted');
+
+    const { fingerprint, formatted } = res.body as { fingerprint: string; formatted: string };
+
+    // Fingerprint must be exactly 60 numeric digits.
+    expect(fingerprint).toHaveLength(60);
+    expect(fingerprint).toMatch(/^\d{60}$/);
+
+    // Formatted must be 12 groups of 5 digits separated by spaces.
+    expect(formatted).toMatch(/^(\d{5} ){11}\d{5}$/);
+
+    // Raw and formatted must contain the same digits.
+    expect(formatted.replace(/ /g, '')).toBe(fingerprint);
+  });
+
+  it('is deterministic: same keys → same fingerprint regardless of input order', async () => {
+    const keys = ['a2V5Qg==', 'a2V5QQ==']; // reverse order vs. previous test
+
+    mockUserFindFirst.mockResolvedValue({ id: 'user-1' });
+    mockDeviceFindMany.mockResolvedValue(keys.map((k) => ({ identityPublicKey: k })));
+
+    const res = await request(makeApp()).get('/users/user-1/key-fingerprint');
+
+    expect(res.status).toBe(200);
+    const expected = deriveFingerprint(keys);
+    expect(res.body.fingerprint).toBe(expected);
+  });
+
+  it('produces a different fingerprint for different key sets', async () => {
+    const fp1 = deriveFingerprint(['a2V5QQ==']);
+    const fp2 = deriveFingerprint(['a2V5Qg==']);
+    expect(fp1).not.toBe(fp2);
+  });
+
+  it('single-device user gets a valid 60-digit fingerprint', async () => {
+    mockUserFindFirst.mockResolvedValue({ id: 'user-1' });
+    mockDeviceFindMany.mockResolvedValue([{ identityPublicKey: 'c2luZ2xlRGV2aWNlS2V5' }]);
+
+    const res = await request(makeApp()).get('/users/user-1/key-fingerprint');
+
+    expect(res.status).toBe(200);
+    expect(res.body.fingerprint).toHaveLength(60);
+  });
+});

apps/backend/src/routes/users.ts

@@ -1,7 +1,8 @@
+import { createHash } from 'node:crypto';
 import { Router, type Router as RouterType } from 'express';
 import { eq, and, or, ilike, exists, sql } from 'drizzle-orm';
 import { db } from '../db/index.js';
-import { users, wallets } from '../db/schema.js';
+import { users, wallets, devices } from '../db/schema.js';
 import { requireAuth, type AuthRequest } from '../middleware/auth.js';
 import { redis } from '../lib/redis.js';
 import { isOnline } from '../services/presence.js';
@@ -151,6 +152,104 @@ usersRouter.get('/:id/presence', async (req: AuthRequest, res) => {
   res.json({ online });
 });
 
+/**
+ * GET /users/:id/key-fingerprint
+ *
+ * Returns a 60-digit numeric safety number derived from the user's set of
+ * active device identity public keys.  The derivation is deterministic and
+ * identical on all clients:
+ *
+ *   1. Collect all non-revoked device identityPublicKey values for the user.
+ *   2. Sort them lexicographically (UTF-8 byte order on the base64 strings).
+ *   3. Concatenate them separated by a single newline (`\n`).
+ *   4. Compute SHA-256 of the UTF-8-encoded concatenated string.
+ *   5. Take the first 30 bytes of the digest and interpret them as a
+ *      big-endian unsigned integer modulo 10^30, zero-padded to 30 digits.
+ *   6. Repeat with bytes 16–31 and reduce modulo 10^30 to produce a second
+ *      30-digit segment, then concatenate → 60 digits total.
+ *      (This matches Signal's safety-number derivation: two independent
+ *      30-digit numbers from non-overlapping digest halves, formatted in
+ *      groups of 5 separated by spaces.)
+ *
+ * The final value is returned both as a raw 60-character digit string and as
+ * the canonical "groups of 5" display format (12 groups of 5, space-separated).
+ */
+usersRouter.get('/:id/key-fingerprint', async (req: AuthRequest, res) => {
+  const id = req.params['id'] as string;
+
+  try {
+    // Verify the target user exists.
+    const user = await db.query.users.findFirst({
+      where: eq(users.id, id),
+      columns: { id: true },
+    });
+
+    if (!user) {
+      res.status(404).json({ error: 'User not found' });
+      return;
+    }
+
+    // Fetch all active (non-revoked) device identity public keys.
+    const activeDevices = await db.query.devices.findMany({
+      where: and(eq(devices.userId, id), eq(devices.isRevoked, false)),
+      columns: { identityPublicKey: true },
+    });
+
+    if (activeDevices.length === 0) {
+      res.status(404).json({ error: 'No active devices found for this user' });
+      return;
+    }
+
+    // Step 2: sort lexicographically.
+    const sortedKeys = activeDevices
+      .map((d) => d.identityPublicKey)
+      .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+
+    // Step 3: concatenate with newline separator.
+    const concatenated = sortedKeys.join('\n');
+
+    // Step 4: SHA-256.
+    const digest = createHash('sha256').update(concatenated, 'utf8').digest();
+
+    // Steps 5 & 6: produce two 30-digit segments from the 32-byte digest.
+    // Segment A: bytes 0–14 (15 bytes → 120 bits), reduce mod 10^30.
+    // Segment B: bytes 15–29 (15 bytes), reduce mod 10^30.
+    // (15 bytes gives well above the 30 decimal digits we need while keeping
+    // overlap-free regions within 32 digest bytes.)
+    function bytesToSafetySegment(buf: Buffer, offset: number, length: number): string {
+      let value = BigInt(0);
+      for (let i = 0; i < length; i++) {
+        value = (value << BigInt(8)) | BigInt(buf[offset + i]!);
+      }
+      const mod = value % BigInt('1' + '0'.repeat(30));
+      return mod.toString().padStart(30, '0');
+    }
+
+    const segmentA = bytesToSafetySegment(digest, 0, 15);
+    const segmentB = bytesToSafetySegment(digest, 15, 15);
+    const raw = segmentA + segmentB;
+
+    // Format: 12 groups of 5 digits, space-separated (Signal convention).
+    const formatted = raw.match(/.{5}/g)!.join(' ');
+
+    res.json({
+      userId: id,
+      /**
+       * Raw 60-digit numeric fingerprint.  Clients compare this string
+       * after stripping spaces; the formatted version is for display.
+       */
+      fingerprint: raw,
+      /**
+       * Human-readable version in groups of 5, matching Signal's safety
+       * number display format.
+       */
+      formatted,
+    });
+  } catch {
+    res.status(500).json({ error: 'Failed to compute key fingerprint' });
+  }
+});
+
 usersRouter.patch('/me', async (req: AuthRequest, res) => {
   const userId = req.auth!.userId;
   const { username, avatarUrl } = req.body;