@auxiora/bridge 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,82 @@
+/** Capabilities a device node can provide. */
+export type DeviceCapability = 'camera' | 'screen' | 'microphone' | 'location' | 'notifications' | 'clipboard' | 'sensors';
+/** Platform of the device. */
+export type DevicePlatform = 'ios' | 'android' | 'macos' | 'windows' | 'linux' | 'web';
+/** Connection state for a device. */
+export type DeviceConnectionState = 'connecting' | 'paired' | 'online' | 'offline';
+/** Information about a paired device. */
+export interface DeviceInfo {
+    /** Unique device identifier. */
+    id: string;
+    /** User-facing device name. */
+    name: string;
+    /** Device platform. */
+    platform: DevicePlatform;
+    /** Capabilities this device supports. */
+    capabilities: DeviceCapability[];
+    /** Current connection state. */
+    state: DeviceConnectionState;
+    /** When the device was first paired. */
+    pairedAt: number;
+    /** When the device was last seen online. */
+    lastSeen: number;
+}
+/** Pairing code issued by the server. */
+export interface PairingCode {
+    /** The short code the user enters on the device. */
+    code: string;
+    /** When the code expires (unix ms). */
+    expiresAt: number;
+    /** Whether the code has been used. */
+    used: boolean;
+}
+/** Configuration for the Bridge server. */
+export interface BridgeConfig {
+    /** Maximum number of paired devices. */
+    maxDevices: number;
+    /** Pairing code length (digits). */
+    codeLength: number;
+    /** Pairing code expiry in seconds. */
+    codeExpirySeconds: number;
+    /** Heartbeat interval in milliseconds. */
+    heartbeatIntervalMs: number;
+    /** Consider device offline after this many missed heartbeats. */
+    offlineAfterMissedHeartbeats: number;
+}
+export declare const DEFAULT_BRIDGE_CONFIG: BridgeConfig;
+/** Messages sent between Bridge server and device nodes. */
+export type BridgeMessageType = 'pair_request' | 'pair_accepted' | 'pair_rejected' | 'heartbeat' | 'heartbeat_ack' | 'capability_request' | 'capability_response' | 'device_info' | 'disconnect' | 'error';
+/** A message in the Bridge protocol. */
+export interface BridgeMessage {
+    type: BridgeMessageType;
+    /** Correlation ID for request/response matching. */
+    id?: string;
+    /** The sending device ID (set by server for forwarded messages). */
+    deviceId?: string;
+    /** Message-specific payload. */
+    payload?: unknown;
+    /** Timestamp (unix ms). */
+    timestamp: number;
+}
+/** Payload for pair_request. */
+export interface PairRequestPayload {
+    code: string;
+    deviceName: string;
+    platform: DevicePlatform;
+    capabilities: DeviceCapability[];
+}
+/** Payload for capability_request. */
+export interface CapabilityRequestPayload {
+    capability: DeviceCapability;
+    action: string;
+    params?: Record<string, unknown>;
+}
+/** Payload for capability_response. */
+export interface CapabilityResponsePayload {
+    capability: DeviceCapability;
+    action: string;
+    success: boolean;
+    data?: unknown;
+    error?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,MAAM,MAAM,gBAAgB,GACxB,QAAQ,GACR,QAAQ,GACR,YAAY,GACZ,UAAU,GACV,eAAe,GACf,WAAW,GACX,SAAS,CAAC;AAEd,8BAA8B;AAC9B,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,CAAC;AAEvF,qCAAqC;AACrC,MAAM,MAAM,qBAAqB,GAAG,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEnF,yCAAyC;AACzC,MAAM,WAAW,UAAU;IACzB,gCAAgC;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,QAAQ,EAAE,cAAc,CAAC;IACzB,yCAAyC;IACzC,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,gCAAgC;IAChC,KAAK,EAAE,qBAAqB,CAAC;IAC7B,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,yCAAyC;AACzC,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,IAAI,EAAE,OAAO,CAAC;CACf;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,0CAA0C;IAC1C,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iEAAiE;IACjE,4BAA4B,EAAE,MAAM,CAAC;CACtC;AAED,eAAO,MAAM,qBAAqB,EAAE,YAMnC,CAAC;AAEF,4DAA4D;AAC5D,MAAM,MAAM,iBAAiB,GACzB,cAAc,GACd,eAAe,GACf,eAAe,GACf,WAAW,GACX,eAAe,GACf,oBAAoB,GACpB,qBAAqB,GACrB,aAAa,GACb,YAAY,GACZ,OAAO,CAAC;AAEZ,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,iBAAiB,CAAC;IACxB,oDAAoD;IACpD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,gCAAgC;AAChC,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,cAAc,CAAC;IACzB,YAAY,EAAE,gBAAgB,EAAE,CAAC;CAClC;AAED,sCAAsC;AACtC,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,uCAAuC;AACvC,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/types.js

@@ -0,0 +1,8 @@
+export const DEFAULT_BRIDGE_CONFIG = {
+    maxDevices: 10,
+    codeLength: 6,
+    codeExpirySeconds: 300,
+    heartbeatIntervalMs: 30_000,
+    offlineAfterMissedHeartbeats: 3,
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA0DA,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IACjD,UAAU,EAAE,EAAE;IACd,UAAU,EAAE,CAAC;IACb,iBAAiB,EAAE,GAAG;IACtB,mBAAmB,EAAE,MAAM;IAC3B,4BAA4B,EAAE,CAAC;CAChC,CAAC"}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@auxiora/bridge",
+  "version": "1.0.0",
+  "description": "Bridge protocol for device pairing — connects mobile and desktop nodes to the server",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@auxiora/logger": "1.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/__tests__/bridge.test.ts

@@ -0,0 +1,411 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { DeviceRegistry } from '../registry.js';
+import { PairingFlow } from '../pairing.js';
+import { BridgeServer, WS_OPEN, type BridgeSocket } from '../server.js';
+import type { DeviceInfo, BridgeMessage } from '../types.js';
+
+function makeMockSocket(): BridgeSocket & { sent: string[]; closed: boolean } {
+  return {
+    sent: [],
+    closed: false,
+    readyState: WS_OPEN,
+    send(data: string) { this.sent.push(data); },
+    close() { this.closed = true; this.readyState = 3; },
+  };
+}
+
+function parseMessage(raw: string): BridgeMessage {
+  return JSON.parse(raw) as BridgeMessage;
+}
+
+describe('DeviceRegistry', () => {
+  let registry: DeviceRegistry;
+
+  const device1: DeviceInfo = {
+    id: 'dev-1',
+    name: 'iPhone',
+    platform: 'ios',
+    capabilities: ['camera', 'location', 'notifications'],
+    state: 'online',
+    pairedAt: Date.now(),
+    lastSeen: Date.now(),
+  };
+
+  const device2: DeviceInfo = {
+    id: 'dev-2',
+    name: 'MacBook',
+    platform: 'macos',
+    capabilities: ['screen', 'clipboard', 'notifications'],
+    state: 'online',
+    pairedAt: Date.now(),
+    lastSeen: Date.now(),
+  };
+
+  beforeEach(() => {
+    registry = new DeviceRegistry(5);
+  });
+
+  it('registers and retrieves a device', () => {
+    registry.register(device1);
+    const found = registry.get('dev-1');
+    expect(found).toBeDefined();
+    expect(found!.name).toBe('iPhone');
+    expect(found!.platform).toBe('ios');
+  });
+
+  it('returns a copy of device info', () => {
+    registry.register(device1);
+    const found = registry.get('dev-1')!;
+    found.name = 'Modified';
+    expect(registry.get('dev-1')!.name).toBe('iPhone');
+  });
+
+  it('returns undefined for unknown device', () => {
+    expect(registry.get('nonexistent')).toBeUndefined();
+  });
+
+  it('lists all devices', () => {
+    registry.register(device1);
+    registry.register(device2);
+    expect(registry.getAll()).toHaveLength(2);
+  });
+
+  it('filters by capability', () => {
+    registry.register(device1);
+    registry.register(device2);
+    const withCamera = registry.getByCapability('camera');
+    expect(withCamera).toHaveLength(1);
+    expect(withCamera[0].id).toBe('dev-1');
+  });
+
+  it('filters online devices', () => {
+    registry.register(device1);
+    registry.register({ ...device2, state: 'offline' });
+    const online = registry.getOnline();
+    expect(online).toHaveLength(1);
+  });
+
+  it('unregisters a device', () => {
+    registry.register(device1);
+    expect(registry.unregister('dev-1')).toBe(true);
+    expect(registry.get('dev-1')).toBeUndefined();
+    expect(registry.size).toBe(0);
+  });
+
+  it('enforces max device limit', () => {
+    const small = new DeviceRegistry(1);
+    small.register(device1);
+    expect(() => small.register(device2)).toThrow('Maximum device limit (1) reached');
+  });
+
+  it('allows re-registering existing device', () => {
+    const small = new DeviceRegistry(1);
+    small.register(device1);
+    small.register({ ...device1, name: 'Updated iPhone' });
+    expect(small.get('dev-1')!.name).toBe('Updated iPhone');
+  });
+
+  it('updates connection state', () => {
+    registry.register(device1);
+    registry.setState('dev-1', 'offline');
+    expect(registry.get('dev-1')!.state).toBe('offline');
+  });
+
+  it('updates lastSeen on heartbeat', () => {
+    registry.register({ ...device1, lastSeen: 1000 });
+    registry.heartbeat('dev-1');
+    expect(registry.get('dev-1')!.lastSeen).toBeGreaterThan(1000);
+  });
+
+  it('detects timed-out devices', () => {
+    registry.register({ ...device1, lastSeen: Date.now() - 100_000 });
+    const timedOut = registry.checkTimeouts(60_000);
+    expect(timedOut).toEqual(['dev-1']);
+    expect(registry.get('dev-1')!.state).toBe('offline');
+  });
+
+  it('reports capacity', () => {
+    const small = new DeviceRegistry(1);
+    expect(small.hasCapacity()).toBe(true);
+    small.register(device1);
+    expect(small.hasCapacity()).toBe(false);
+  });
+});
+
+describe('PairingFlow', () => {
+  let pairing: PairingFlow;
+
+  beforeEach(() => {
+    pairing = new PairingFlow({ codeLength: 6, codeExpirySeconds: 300 });
+  });
+
+  afterEach(() => {
+    pairing.destroy();
+  });
+
+  it('generates a code of correct length', () => {
+    const code = pairing.generateCode();
+    expect(code.code).toHaveLength(6);
+    expect(code.used).toBe(false);
+    expect(code.expiresAt).toBeGreaterThan(Date.now());
+  });
+
+  it('validates a fresh code', () => {
+    const code = pairing.generateCode();
+    expect(pairing.validate(code.code)).toBe(true);
+  });
+
+  it('rejects unknown code', () => {
+    expect(pairing.validate('000000')).toBe(false);
+  });
+
+  it('consumes a code', () => {
+    const code = pairing.generateCode();
+    expect(pairing.consume(code.code)).toBe(true);
+    // Cannot consume again
+    expect(pairing.consume(code.code)).toBe(false);
+    // Cannot validate consumed code
+    expect(pairing.validate(code.code)).toBe(false);
+  });
+
+  it('revokes a code', () => {
+    const code = pairing.generateCode();
+    expect(pairing.revoke(code.code)).toBe(true);
+    expect(pairing.validate(code.code)).toBe(false);
+  });
+
+  it('rejects expired codes', () => {
+    const code = pairing.generateCode();
+    // Manually expire
+    vi.spyOn(Date, 'now').mockReturnValue(Date.now() + 400_000);
+    expect(pairing.validate(code.code)).toBe(false);
+    vi.restoreAllMocks();
+  });
+
+  it('lists active codes', () => {
+    pairing.generateCode();
+    pairing.generateCode();
+    const consumed = pairing.generateCode();
+    pairing.consume(consumed.code);
+
+    const active = pairing.getActiveCodes();
+    expect(active).toHaveLength(2);
+  });
+
+  it('cleans up expired and consumed codes', () => {
+    const c1 = pairing.generateCode();
+    pairing.consume(c1.code);
+    pairing.generateCode(); // still active
+
+    const removed = pairing.cleanup();
+    expect(removed).toBe(1);
+  });
+});
+
+describe('BridgeServer', () => {
+  let server: BridgeServer;
+
+  beforeEach(() => {
+    server = new BridgeServer({ maxDevices: 5, codeLength: 6, codeExpirySeconds: 300 });
+  });
+
+  afterEach(() => {
+    server.stop();
+  });
+
+  it('generates pairing codes', () => {
+    const code = server.generatePairingCode();
+    expect(code).toHaveLength(6);
+  });
+
+  it('handles device connection', () => {
+    const socket = makeMockSocket();
+    server.handleConnection(socket, 'conn-1');
+    expect(server.getConnectionCount()).toBe(1);
+  });
+
+  it('handles full pairing flow', async () => {
+    const socket = makeMockSocket();
+    server.handleConnection(socket, 'conn-1');
+
+    const code = server.generatePairingCode();
+
+    await server.handleMessage('conn-1', JSON.stringify({
+      type: 'pair_request',
+      id: 'req-1',
+      payload: {
+        code,
+        deviceName: 'Test Phone',
+        platform: 'android',
+        capabilities: ['camera', 'location'],
+      },
+      timestamp: Date.now(),
+    }));
+
+    expect(socket.sent).toHaveLength(1);
+    const response = parseMessage(socket.sent[0]);
+    expect(response.type).toBe('pair_accepted');
+    expect(response.deviceId).toBeDefined();
+
+    // Device should be in registry
+    const devices = server.registry.getAll();
+    expect(devices).toHaveLength(1);
+    expect(devices[0].name).toBe('Test Phone');
+    expect(devices[0].platform).toBe('android');
+    expect(devices[0].capabilities).toEqual(['camera', 'location']);
+  });
+
+  it('rejects invalid pairing code', async () => {
+    const socket = makeMockSocket();
+    server.handleConnection(socket, 'conn-1');
+
+    await server.handleMessage('conn-1', JSON.stringify({
+      type: 'pair_request',
+      id: 'req-1',
+      payload: {
+        code: '999999',
+        deviceName: 'Test Phone',
+        platform: 'android',
+        capabilities: [],
+      },
+      timestamp: Date.now(),
+    }));
+
+    const response = parseMessage(socket.sent[0]);
+    expect(response.type).toBe('pair_rejected');
+  });
+
+  it('rejects incomplete pair request', async () => {
+    const socket = makeMockSocket();
+    server.handleConnection(socket, 'conn-1');
+
+    await server.handleMessage('conn-1', JSON.stringify({
+      type: 'pair_request',
+      id: 'req-1',
+      payload: { code: '123456' },
+      timestamp: Date.now(),
+    }));
+
+    const response = parseMessage(socket.sent[0]);
+    expect(response.type).toBe('error');
+  });
+
+  it('handles heartbeat from paired device', async () => {
+    const socket = makeMockSocket();
+    server.handleConnection(socket, 'conn-1');
+
+    // Pair the device first
+    const code = server.generatePairingCode();
+    await server.handleMessage('conn-1', JSON.stringify({
+      type: 'pair_request',
+      id: 'req-1',
+      payload: {
+        code,
+        deviceName: 'Phone',
+        platform: 'ios',
+        capabilities: [],
+      },
+      timestamp: Date.now(),
+    }));
+
+    socket.sent.length = 0;
+
+    await server.handleMessage('conn-1', JSON.stringify({
+      type: 'heartbeat',
+      id: 'hb-1',
+      timestamp: Date.now(),
+    }));
+
+    expect(socket.sent).toHaveLength(1);
+    const response = parseMessage(socket.sent[0]);
+    expect(response.type).toBe('heartbeat_ack');
+  });
+
+  it('handles device disconnection', async () => {
+    const socket = makeMockSocket();
+    server.handleConnection(socket, 'conn-1');
+
+    // Pair device
+    const code = server.generatePairingCode();
+    await server.handleMessage('conn-1', JSON.stringify({
+      type: 'pair_request',
+      id: 'req-1',
+      payload: {
+        code,
+        deviceName: 'Phone',
+        platform: 'ios',
+        capabilities: ['camera'],
+      },
+      timestamp: Date.now(),
+    }));
+
+    const deviceId = server.registry.getAll()[0].id;
+    server.handleDisconnection('conn-1');
+
+    expect(server.registry.get(deviceId)!.state).toBe('offline');
+    expect(server.getConnectionCount()).toBe(0);
+  });
+
+  it('handles invalid JSON gracefully', async () => {
+    const socket = makeMockSocket();
+    server.handleConnection(socket, 'conn-1');
+
+    await server.handleMessage('conn-1', 'not-json{');
+    const response = parseMessage(socket.sent[0]);
+    expect(response.type).toBe('error');
+  });
+
+  it('handles unknown message type', async () => {
+    const socket = makeMockSocket();
+    server.handleConnection(socket, 'conn-1');
+
+    await server.handleMessage('conn-1', JSON.stringify({
+      type: 'unknown_type',
+      timestamp: Date.now(),
+    }));
+
+    const response = parseMessage(socket.sent[0]);
+    expect(response.type).toBe('error');
+    expect((response.payload as { message: string }).message).toContain('Unknown message type');
+  });
+
+  it('fires event on device paired', async () => {
+    const paired: DeviceInfo[] = [];
+    server.onEvent({ onDevicePaired: (d) => paired.push(d) });
+
+    const socket = makeMockSocket();
+    server.handleConnection(socket, 'conn-1');
+    const code = server.generatePairingCode();
+
+    await server.handleMessage('conn-1', JSON.stringify({
+      type: 'pair_request',
+      id: 'req-1',
+      payload: {
+        code,
+        deviceName: 'Phone',
+        platform: 'android',
+        capabilities: [],
+      },
+      timestamp: Date.now(),
+    }));
+
+    expect(paired).toHaveLength(1);
+    expect(paired[0].name).toBe('Phone');
+  });
+
+  it('rejects capability request for unknown device', async () => {
+    await expect(
+      server.requestCapability('unknown', 'camera', 'capture'),
+    ).rejects.toThrow('Device not found');
+  });
+
+  it('stops cleanly', () => {
+    server.start();
+    const socket = makeMockSocket();
+    server.handleConnection(socket, 'conn-1');
+
+    server.stop();
+    expect(socket.closed).toBe(true);
+    expect(server.getConnectionCount()).toBe(0);
+  });
+});

package/src/index.ts

@@ -0,0 +1,22 @@
+export type {
+  DeviceCapability,
+  DevicePlatform,
+  DeviceConnectionState,
+  DeviceInfo,
+  PairingCode,
+  BridgeConfig,
+  BridgeMessageType,
+  BridgeMessage,
+  PairRequestPayload,
+  CapabilityRequestPayload,
+  CapabilityResponsePayload,
+} from './types.js';
+export { DEFAULT_BRIDGE_CONFIG } from './types.js';
+export { DeviceRegistry } from './registry.js';
+export { PairingFlow } from './pairing.js';
+export {
+  BridgeServer,
+  WS_OPEN,
+  type BridgeSocket,
+  type BridgeEventHandler,
+} from './server.js';

package/src/pairing.ts

@@ -0,0 +1,129 @@
+import { getLogger } from '@auxiora/logger';
+import * as crypto from 'node:crypto';
+import type { PairingCode, BridgeConfig } from './types.js';
+import { DEFAULT_BRIDGE_CONFIG } from './types.js';
+
+const logger = getLogger('bridge:pairing');
+
+/**
+ * Manages pairing code generation, validation, and expiry
+ * for the device pairing flow.
+ */
+export class PairingFlow {
+  private activeCodes = new Map<string, PairingCode>();
+  private config: BridgeConfig;
+  private cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(config?: Partial<BridgeConfig>) {
+    this.config = { ...DEFAULT_BRIDGE_CONFIG, ...config };
+  }
+
+  /** Generate a new pairing code. */
+  generateCode(): PairingCode {
+    const code = this.makeCode(this.config.codeLength);
+    const pairingCode: PairingCode = {
+      code,
+      expiresAt: Date.now() + this.config.codeExpirySeconds * 1000,
+      used: false,
+    };
+
+    this.activeCodes.set(code, pairingCode);
+    logger.info('Pairing code generated', { code });
+    return { ...pairingCode };
+  }
+
+  /** Validate a pairing code. Returns true if the code is valid and not expired. */
+  validate(code: string): boolean {
+    const pairingCode = this.activeCodes.get(code);
+    if (!pairingCode) {
+      return false;
+    }
+    if (pairingCode.used) {
+      return false;
+    }
+    if (Date.now() > pairingCode.expiresAt) {
+      this.activeCodes.delete(code);
+      return false;
+    }
+    return true;
+  }
+
+  /** Consume a pairing code, marking it as used. Returns true if successful. */
+  consume(code: string): boolean {
+    if (!this.validate(code)) {
+      return false;
+    }
+    const pairingCode = this.activeCodes.get(code)!;
+    pairingCode.used = true;
+    logger.info('Pairing code consumed', { code });
+    return true;
+  }
+
+  /** Revoke an active pairing code. */
+  revoke(code: string): boolean {
+    const removed = this.activeCodes.delete(code);
+    if (removed) {
+      logger.info('Pairing code revoked', { code });
+    }
+    return removed;
+  }
+
+  /** Get all active (non-expired, non-used) codes. */
+  getActiveCodes(): PairingCode[] {
+    const now = Date.now();
+    const active: PairingCode[] = [];
+
+    for (const pc of this.activeCodes.values()) {
+      if (!pc.used && now <= pc.expiresAt) {
+        active.push({ ...pc });
+      }
+    }
+
+    return active;
+  }
+
+  /** Remove expired codes. */
+  cleanup(): number {
+    const now = Date.now();
+    let removed = 0;
+
+    for (const [code, pc] of this.activeCodes) {
+      if (pc.used || now > pc.expiresAt) {
+        this.activeCodes.delete(code);
+        removed++;
+      }
+    }
+
+    return removed;
+  }
+
+  /** Start automatic cleanup timer. */
+  startCleanup(intervalMs = 60_000): void {
+    this.stopCleanup();
+    this.cleanupTimer = setInterval(() => this.cleanup(), intervalMs);
+  }
+
+  /** Stop automatic cleanup timer. */
+  stopCleanup(): void {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+  }
+
+  /** Destroy the pairing flow, clearing all codes and stopping timers. */
+  destroy(): void {
+    this.stopCleanup();
+    this.activeCodes.clear();
+  }
+
+  /** Generate a random numeric code of the given length. */
+  private makeCode(length: number): string {
+    const bytes = crypto.randomBytes(length);
+    let code = '';
+    for (let i = 0; i < length; i++) {
+      code += (bytes[i] % 10).toString();
+    }
+    return code;
+  }
+}