mecord-connect 1.0.0

package/runtime/app/src/core/device-registry.js

@@ -0,0 +1,477 @@
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { DeviceIdentityStore,                           } from './device-identity.js';
+import { OperatorError } from './errors.js';
+import { readDurableStateText, writeDurableStateText } from './durable-state.js';
+
+const MAX_DEVICES = 1000;
+const MAX_CHALLENGES = 2048;
+const MAX_ACTIVE_CHALLENGES = 128;
+const MAX_TTL_MS = 5 * 60_000;
+const MIN_TTL_MS = 30_000;
+const CHALLENGE_RETENTION_MS = 24 * 60 * 60_000;
+const DEVICE_NAME_MAX = 128;
+const REASON_MAX = 512;
+const PURPOSE = 'operator-pairing-v1';
+
+                                         
+             
+                          
+                      
+                         
+                            
+                
+                   
+                    
+                                
+ 
+
+                                  
+                      
+                             
+                    
+ 
+
+                                   
+                   
+                     
+                    
+                       
+                      
+                               
+                   
+                     
+                         
+ 
+
+                                                                                                                                         
+                                                                                                
+
+                        
+                                                                                    
+
+export class DeviceRegistryStore {
+  #file        ;
+  #clock       ;
+  #onRevoke                   ;
+  #queue                = Promise.resolve();
+
+  constructor(stateDir        , options                                                 = {}) {
+    this.#file = path.join(path.resolve(stateDir), 'device-registry.json');
+    this.#clock = options.clock ?? (() => new Date());
+    this.#onRevoke = options.onRevoke;
+  }
+
+  async listDevices()                              {
+    const state = await this.#read();
+    return state.devices.map((device) => ({ ...device }));
+  }
+
+  async issuePairingChallenge(
+    issuer                      ,
+    options                                                    = {}
+  )                                  {
+    const normalizedIssuer = normalizePublicIdentity(issuer);
+    const ttlMs = boundedTtl(options.ttlMs ?? 120_000);
+    const expectedPeerDeviceId = options.expectedPeerDeviceId === undefined
+      ? undefined
+      : validUuid(options.expectedPeerDeviceId, 'expectedPeerDeviceId');
+    const now = this.#clock();
+    const challenge                  = {
+      version: 1,
+      purpose: PURPOSE,
+      challengeId: crypto.randomUUID(),
+      issuerDeviceId: normalizedIssuer.deviceId,
+      issuerFingerprint: normalizedIssuer.fingerprint,
+      nonce: crypto.randomBytes(32).toString('base64url'),
+      issuedAt: now.toISOString(),
+      expiresAt: new Date(now.getTime() + ttlMs).toISOString(),
+      expectedPeerDeviceId
+    };
+
+    await this.#mutate((state) => {
+      pruneChallenges(state, now.getTime());
+      const activeChallenges = state.challenges.filter((candidate) => !candidate.consumedAt && Date.parse(candidate.expiresAt) > now.getTime()).length;
+      if (activeChallenges >= MAX_ACTIVE_CHALLENGES) throw new OperatorError('PAIRING_CHALLENGE_LIMIT', `At most ${MAX_ACTIVE_CHALLENGES} active pairing challenges may be retained.`);
+      while (state.challenges.length >= MAX_CHALLENGES) {
+        const reclaimIndex = state.challenges.findIndex((candidate) => Boolean(candidate.consumedAt) || Date.parse(candidate.expiresAt) <= now.getTime());
+        if (reclaimIndex < 0) break;
+        state.challenges.splice(reclaimIndex, 1);
+      }
+      if (state.challenges.length >= MAX_CHALLENGES) throw new OperatorError('PAIRING_CHALLENGE_LIMIT', 'Pairing challenge retention limit reached.');
+      state.challenges.push(challenge);
+    });
+    return publicChallenge(challenge);
+  }
+
+  async verifyPairingForEnrollment(response                 , options                                 = {})                                {
+    if (!response || typeof response !== 'object') throw new OperatorError('PAIRING_RESPONSE_INVALID', 'Pairing response is invalid.');
+    const challengeId = validUuid(response.challengeId, 'challengeId');
+    const peer = normalizePublicIdentity(response.peer);
+    const signature = String(response.signature ?? '');
+    if (!/^[A-Za-z0-9_-]{40,256}$/.test(signature)) throw new OperatorError('PAIRING_SIGNATURE_INVALID', 'Pairing response signature is malformed.');
+    return await this.#mutate((state) => {
+      const now = this.#clock();
+      pruneChallenges(state, now.getTime());
+      const challenge = state.challenges.find((candidate) => candidate.challengeId === challengeId);
+      if (!challenge) throw new OperatorError('PAIRING_CHALLENGE_NOT_FOUND', 'Pairing challenge was not found or is no longer retained.');
+      if (!challenge.consumedAt && Date.parse(challenge.expiresAt) < now.getTime()) throw new OperatorError('PAIRING_CHALLENGE_EXPIRED', 'Pairing challenge has expired.');
+      if (challenge.expectedPeerDeviceId && challenge.expectedPeerDeviceId !== peer.deviceId) throw new OperatorError('PAIRING_PEER_MISMATCH', 'Pairing response came from a different device than the challenge expected.');
+      let verified = false;
+      try { verified = crypto.verify(null, pairingPayload(challenge, peer), peer.publicKeyPem, Buffer.from(signature, 'base64url')); } catch { verified = false; }
+      if (!verified) throw new OperatorError('PAIRING_SIGNATURE_INVALID', 'Pairing response signature could not be verified.');
+      if (challenge.consumedAt) {
+        const exact = challenge.consumedPeerDeviceId === peer.deviceId && challenge.consumedPeerFingerprint === peer.fingerprint;
+        if (options.allowExactReplay && exact) return { ...peer };
+        throw new OperatorError('PAIRING_CHALLENGE_REPLAY', 'Pairing challenge has already been consumed.');
+      }
+      challenge.consumedAt = now.toISOString();
+      challenge.consumedPeerDeviceId = peer.deviceId;
+      challenge.consumedPeerFingerprint = peer.fingerprint;
+      return { ...peer };
+    });
+  }
+  async registerVerifiedPeer(peerInput                      )                            {
+    return (await this.registerVerifiedPeerTracked(peerInput)).device;
+  }
+
+  async registerVerifiedPeerTracked(peerInput                      )                                                          {
+    const peer = normalizePublicIdentity(peerInput);
+    return await this.#mutate((state) => {
+      const sameId = state.devices.find((device) => device.deviceId === peer.deviceId);
+      const sameFingerprint = state.devices.find((device) => device.fingerprint === peer.fingerprint);
+      if (sameId && sameId.fingerprint !== peer.fingerprint) throw new OperatorError('DEVICE_IDENTITY_CONFLICT', 'The device ID is already registered with a different public key.');
+      if (sameFingerprint && sameFingerprint.deviceId !== peer.deviceId) throw new OperatorError('DEVICE_IDENTITY_CONFLICT', 'The public-key fingerprint is already registered to a different device ID.');
+      if (sameId?.status === 'revoked') throw new OperatorError('DEVICE_REVOKED', 'This device identity is revoked and cannot be silently reactivated.');
+      if (!sameId && state.devices.length >= MAX_DEVICES) throw new OperatorError('DEVICE_REGISTRY_LIMIT', `At most ${MAX_DEVICES} peer devices may be registered.`);
+      const pairedAt = this.#clock().toISOString();
+      const registered                   = sameId ?? { ...peer, status: 'active', pairedAt };
+      if (!sameId) state.devices.push(registered);
+      else {
+        sameId.deviceName = peer.deviceName;
+        sameId.createdAt = peer.createdAt;
+        sameId.publicKeyPem = peer.publicKeyPem;
+        sameId.pairedAt = pairedAt;
+      }
+      return { device: { ...registered }, created: !sameId };
+    });
+  }
+
+  async unregisterActiveDevice(deviceIdInput        , expectedFingerprintInput         )                   {
+    const deviceId = validUuid(deviceIdInput, 'deviceId');
+    const expectedFingerprint = expectedFingerprintInput === undefined ? undefined : String(expectedFingerprintInput);
+    if (expectedFingerprint !== undefined && !/^[A-Za-z0-9_-]{32,128}$/.test(expectedFingerprint)) {
+      throw new OperatorError('DEVICE_IDENTITY_INVALID', 'Expected device fingerprint is invalid.');
+    }
+    return await this.#mutate((state) => {
+      const index = state.devices.findIndex((device) => device.deviceId === deviceId);
+      if (index < 0) return false;
+      const device = state.devices[index] ;
+      if (device.status === 'revoked') return false;
+      if (expectedFingerprint && device.fingerprint !== expectedFingerprint) {
+        throw new OperatorError('DEVICE_IDENTITY_CONFLICT', 'Device registration fingerprint changed before rollback.');
+      }
+      state.devices.splice(index, 1);
+      return true;
+    });
+  }
+
+  async completePairing(response                 , options                                 = {})                            {
+    if (!response || typeof response !== 'object') throw new OperatorError('PAIRING_RESPONSE_INVALID', 'Pairing response is invalid.');
+    const challengeId = validUuid(response.challengeId, 'challengeId');
+    const peer = normalizePublicIdentity(response.peer);
+    const signature = String(response.signature ?? '');
+    if (!/^[A-Za-z0-9_-]{40,256}$/.test(signature)) {
+      throw new OperatorError('PAIRING_SIGNATURE_INVALID', 'Pairing response signature is malformed.');
+    }
+
+    return await this.#mutate((state) => {
+      const now = this.#clock();
+      pruneChallenges(state, now.getTime());
+      const challenge = state.challenges.find((candidate) => candidate.challengeId === challengeId);
+      if (!challenge) throw new OperatorError('PAIRING_CHALLENGE_NOT_FOUND', 'Pairing challenge was not found or is no longer retained.');
+      if (!challenge.consumedAt && Date.parse(challenge.expiresAt) < now.getTime()) throw new OperatorError('PAIRING_CHALLENGE_EXPIRED', 'Pairing challenge has expired.');
+      if (challenge.expectedPeerDeviceId && challenge.expectedPeerDeviceId !== peer.deviceId) {
+        throw new OperatorError('PAIRING_PEER_MISMATCH', 'Pairing response came from a different device than the challenge expected.');
+      }
+
+      const payload = pairingPayload(challenge, peer);
+      let verified = false;
+      try {
+        verified = crypto.verify(null, payload, peer.publicKeyPem, Buffer.from(signature, 'base64url'));
+      } catch {
+        verified = false;
+      }
+      if (!verified) throw new OperatorError('PAIRING_SIGNATURE_INVALID', 'Pairing response signature could not be verified.');
+
+      const sameId = state.devices.find((device) => device.deviceId === peer.deviceId);
+      const sameFingerprint = state.devices.find((device) => device.fingerprint === peer.fingerprint);
+      if (challenge.consumedAt) {
+        if (options.allowExactReplay && sameId && sameId.status === 'active' && sameId.fingerprint === peer.fingerprint) return { ...sameId };
+        throw new OperatorError('PAIRING_CHALLENGE_REPLAY', 'Pairing challenge has already been consumed.');
+      }
+      if (sameId && sameId.fingerprint !== peer.fingerprint) {
+        throw new OperatorError('DEVICE_IDENTITY_CONFLICT', 'The device ID is already registered with a different public key.');
+      }
+      if (sameFingerprint && sameFingerprint.deviceId !== peer.deviceId) {
+        throw new OperatorError('DEVICE_IDENTITY_CONFLICT', 'The public-key fingerprint is already registered to a different device ID.');
+      }
+      if (sameId?.status === 'revoked') {
+        throw new OperatorError('DEVICE_REVOKED', 'This device identity is revoked and cannot be silently reactivated by pairing.');
+      }
+      if (!sameId && state.devices.length >= MAX_DEVICES) {
+        throw new OperatorError('DEVICE_REGISTRY_LIMIT', `At most ${MAX_DEVICES} peer devices may be registered.`);
+      }
+
+      const pairedAt = now.toISOString();
+      const registered                   = sameId ?? {
+        deviceId: peer.deviceId,
+        deviceName: peer.deviceName,
+        createdAt: peer.createdAt,
+        publicKeyPem: peer.publicKeyPem,
+        fingerprint: peer.fingerprint,
+        status: 'active',
+        pairedAt
+      };
+      if (!sameId) state.devices.push(registered);
+      else {
+        sameId.deviceName = peer.deviceName;
+        sameId.createdAt = peer.createdAt;
+        sameId.publicKeyPem = peer.publicKeyPem;
+        sameId.pairedAt = pairedAt;
+      }
+      challenge.consumedAt = pairedAt;
+      return { ...registered };
+    });
+  }
+
+  async revokeDevice(deviceIdInput        , reasonInput         )                            {
+    const deviceId = validUuid(deviceIdInput, 'deviceId');
+    const reason = reasonInput === undefined ? undefined : boundedReason(reasonInput);
+    const outcome = await this.#mutate((state) => {
+      const device = state.devices.find((candidate) => candidate.deviceId === deviceId);
+      if (!device) throw new OperatorError('DEVICE_NOT_FOUND', 'Registered device was not found.');
+      if (device.status === 'revoked') return { device: { ...device }, changed: false };
+      device.status = 'revoked';
+      device.revokedAt = this.#clock().toISOString();
+      device.revokedReason = reason;
+      return { device: { ...device }, changed: true };
+    });
+    if (outcome.changed) await this.#onRevoke?.(deviceId, reason);
+    return outcome.device;
+  }
+
+  async verifyDeviceSignature(deviceIdInput        , payload            , signatureInput        )                   {
+    const deviceId = validUuid(deviceIdInput, 'deviceId');
+    const signature = String(signatureInput ?? '');
+    const state = await this.#read();
+    const device = state.devices.find((candidate) => candidate.deviceId === deviceId);
+    if (!device) throw new OperatorError('DEVICE_NOT_FOUND', 'Registered device was not found.');
+    if (device.status !== 'active') throw new OperatorError('DEVICE_REVOKED', 'Registered device is revoked.');
+    try {
+      return crypto.verify(null, payload, device.publicKeyPem, Buffer.from(signature, 'base64url'));
+    } catch {
+      return false;
+    }
+  }
+
+  async #read()                         {
+    try {
+      const text = await readDurableStateText(this.#file, {
+        maxBytes: 2 * 1024 * 1024,
+        errorCode: 'DEVICE_REGISTRY_CORRUPT',
+        invalidMessage: 'Device registry is invalid.'
+      });
+      return validateState(JSON.parse(text));
+    } catch (error) {
+      if ((error                         ).code === 'ENOENT') return { version: 1, devices: [], challenges: [] };
+      if (error instanceof OperatorError) throw error;
+      throw new OperatorError('DEVICE_REGISTRY_CORRUPT', 'Device registry could not be read.');
+    }
+  }
+
+  async #write(stateInput               )                {
+    const state = validateState(stateInput);
+    await writeDurableStateText(this.#file, JSON.stringify(state, null, 2), {
+      maxBytes: 2 * 1024 * 1024,
+      errorCode: 'DEVICE_REGISTRY_CORRUPT',
+      invalidMessage: 'Device registry is invalid.'
+    });
+  }
+
+  async #mutate   (mutator                                          )             {
+    let resolveTurn             ;
+    const previous = this.#queue;
+    this.#queue = new Promise      ((resolve) => { resolveTurn = resolve; });
+    await previous;
+    try {
+      const state = await this.#read();
+      const result = await mutator(state);
+      await this.#write(state);
+      return result;
+    } finally {
+      resolveTurn();
+    }
+  }
+}
+
+export async function answerPairingChallenge(
+  challengeInput                        ,
+  identityStore                     ,
+  deviceName         
+)                           {
+  const challenge = validateChallenge(challengeInput);
+  const peer = normalizePublicIdentity(await identityStore.loadOrCreate(deviceName));
+  if (challenge.expectedPeerDeviceId && challenge.expectedPeerDeviceId !== peer.deviceId) {
+    throw new OperatorError('PAIRING_PEER_MISMATCH', 'This pairing challenge is intended for a different device.');
+  }
+  const signature = await identityStore.sign(pairingPayload(challenge, peer));
+  return { challengeId: challenge.challengeId, peer, signature };
+}
+
+function pairingPayload(challengeInput                        , peerInput                      )         {
+  const challenge = validateChallenge(challengeInput);
+  const peer = normalizePublicIdentity(peerInput);
+  return Buffer.from(JSON.stringify({
+    version: 1,
+    purpose: PURPOSE,
+    challengeId: challenge.challengeId,
+    issuerDeviceId: challenge.issuerDeviceId,
+    issuerFingerprint: challenge.issuerFingerprint,
+    nonce: challenge.nonce,
+    issuedAt: challenge.issuedAt,
+    expiresAt: challenge.expiresAt,
+    expectedPeerDeviceId: challenge.expectedPeerDeviceId ?? null,
+    peerDeviceId: peer.deviceId,
+    peerDeviceName: peer.deviceName,
+    peerCreatedAt: peer.createdAt,
+    peerFingerprint: peer.fingerprint,
+    peerPublicKeyPem: peer.publicKeyPem
+  }), 'utf8');
+}
+
+function normalizePublicIdentity(input                      )                       {
+  if (!input || typeof input !== 'object') throw new OperatorError('DEVICE_IDENTITY_INVALID', 'Public device identity is invalid.');
+  const deviceId = validUuid(String(input.deviceId ?? ''), 'deviceId');
+  const deviceName = boundedDeviceName(String(input.deviceName ?? ''));
+  const createdAt = validIsoDate(String(input.createdAt ?? ''), 'createdAt');
+  let publicKey                  ;
+  try { publicKey = crypto.createPublicKey(String(input.publicKeyPem ?? '')); }
+  catch { throw new OperatorError('DEVICE_IDENTITY_INVALID', 'Public device key is invalid.'); }
+  if (publicKey.asymmetricKeyType !== 'ed25519') throw new OperatorError('DEVICE_IDENTITY_INVALID', 'Public device key must be Ed25519.');
+  const publicKeyPem = publicKey.export({ type: 'spki', format: 'pem' }).toString();
+  const fingerprint = crypto.createHash('sha256').update(publicKeyPem).digest('base64url');
+  if (fingerprint !== String(input.fingerprint ?? '')) {
+    throw new OperatorError('DEVICE_IDENTITY_INVALID', 'Public device fingerprint does not match the public key.');
+  }
+  return { deviceId, deviceName, createdAt, publicKeyPem, fingerprint };
+}
+
+function validateChallenge(input                        )                         {
+  if (!input || typeof input !== 'object' || input.version !== 1 || input.purpose !== PURPOSE) {
+    throw new OperatorError('PAIRING_CHALLENGE_INVALID', 'Pairing challenge is invalid.');
+  }
+  const challengeId = validUuid(String(input.challengeId ?? ''), 'challengeId');
+  const issuerDeviceId = validUuid(String(input.issuerDeviceId ?? ''), 'issuerDeviceId');
+  const issuerFingerprint = String(input.issuerFingerprint ?? '');
+  if (!/^[A-Za-z0-9_-]{32,128}$/.test(issuerFingerprint)) throw new OperatorError('PAIRING_CHALLENGE_INVALID', 'Pairing issuer fingerprint is invalid.');
+  const nonce = String(input.nonce ?? '');
+  if (!/^[A-Za-z0-9_-]{40,128}$/.test(nonce)) throw new OperatorError('PAIRING_CHALLENGE_INVALID', 'Pairing nonce is invalid.');
+  const issuedAt = validIsoDate(String(input.issuedAt ?? ''), 'issuedAt');
+  const expiresAt = validIsoDate(String(input.expiresAt ?? ''), 'expiresAt');
+  const issued = Date.parse(issuedAt);
+  const expires = Date.parse(expiresAt);
+  if (expires <= issued || expires - issued > MAX_TTL_MS) throw new OperatorError('PAIRING_CHALLENGE_INVALID', 'Pairing challenge lifetime is invalid.');
+  const expectedPeerDeviceId = input.expectedPeerDeviceId === undefined ? undefined : validUuid(input.expectedPeerDeviceId, 'expectedPeerDeviceId');
+  return { version: 1, purpose: PURPOSE, challengeId, issuerDeviceId, issuerFingerprint, nonce, issuedAt, expiresAt, expectedPeerDeviceId };
+}
+
+function validateState(input               )                {
+  if (!input || typeof input !== 'object' || input.version !== 1 || !Array.isArray(input.devices) || !Array.isArray(input.challenges)) {
+    throw new OperatorError('DEVICE_REGISTRY_CORRUPT', 'Device registry structure is invalid.');
+  }
+  if (input.devices.length > MAX_DEVICES || input.challenges.length > MAX_CHALLENGES) {
+    throw new OperatorError('DEVICE_REGISTRY_CORRUPT', 'Device registry exceeds bounded entry limits.');
+  }
+  const ids = new Set        ();
+  const fingerprints = new Set        ();
+  const devices = input.devices.map((raw) => {
+    const peer = normalizePublicIdentity(raw);
+    if (ids.has(peer.deviceId) || fingerprints.has(peer.fingerprint)) throw new OperatorError('DEVICE_REGISTRY_CORRUPT', 'Device registry contains duplicate identities.');
+    ids.add(peer.deviceId);
+    fingerprints.add(peer.fingerprint);
+    const status = raw.status === 'revoked' ? 'revoked' : raw.status === 'active' ? 'active' : null;
+    if (!status) throw new OperatorError('DEVICE_REGISTRY_CORRUPT', 'Registered device status is invalid.');
+    const pairedAt = validIsoDate(String(raw.pairedAt ?? ''), 'pairedAt');
+    const revokedAt = raw.revokedAt === undefined ? undefined : validIsoDate(String(raw.revokedAt), 'revokedAt');
+    const revokedReason = raw.revokedReason === undefined ? undefined : boundedReason(String(raw.revokedReason));
+    if (status === 'active' && revokedAt) throw new OperatorError('DEVICE_REGISTRY_CORRUPT', 'Active device cannot have a revocation timestamp.');
+    return { ...peer, status, pairedAt, revokedAt, revokedReason }                           ;
+  });
+  const challengeIds = new Set        ();
+  const challenges = input.challenges.map((raw) => {
+    const challenge = validateChallenge(raw);
+    if (challengeIds.has(challenge.challengeId)) throw new OperatorError('DEVICE_REGISTRY_CORRUPT', 'Duplicate pairing challenge ID.');
+    challengeIds.add(challenge.challengeId);
+    const consumedAt = raw.consumedAt === undefined ? undefined : validIsoDate(String(raw.consumedAt), 'consumedAt');
+    const consumedPeerDeviceId = raw.consumedPeerDeviceId === undefined ? undefined : validUuid(String(raw.consumedPeerDeviceId), 'consumedPeerDeviceId');
+    const consumedPeerFingerprint = raw.consumedPeerFingerprint === undefined ? undefined : String(raw.consumedPeerFingerprint);
+    if (consumedPeerFingerprint !== undefined && !/^[A-Za-z0-9_-]{32,128}$/.test(consumedPeerFingerprint)) throw new OperatorError('DEVICE_REGISTRY_CORRUPT', 'Consumed pairing peer fingerprint is invalid.');
+    if (Boolean(consumedPeerDeviceId) !== Boolean(consumedPeerFingerprint) || (!consumedAt && consumedPeerDeviceId)) throw new OperatorError('DEVICE_REGISTRY_CORRUPT', 'Consumed pairing replay authority is inconsistent.');
+    return { ...challenge, consumedAt, consumedPeerDeviceId, consumedPeerFingerprint };
+  });
+  return { version: 1, devices, challenges };
+}
+
+function pruneChallenges(state               , nowMs        )       {
+  state.challenges = state.challenges.filter((challenge) => {
+    const reference = challenge.consumedAt ? Date.parse(challenge.consumedAt) : Date.parse(challenge.expiresAt);
+    return nowMs - reference <= CHALLENGE_RETENTION_MS;
+  });
+}
+
+function boundedTtl(value        )         {
+  if (!Number.isInteger(value) || value < MIN_TTL_MS || value > MAX_TTL_MS) {
+    throw new OperatorError('PAIRING_TTL_INVALID', `Pairing TTL must be an integer between ${MIN_TTL_MS} and ${MAX_TTL_MS} ms.`);
+  }
+  return value;
+}
+
+function validUuid(value        , label        )         {
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)) {
+    throw new OperatorError('DEVICE_IDENTITY_INVALID', `${label} must be a UUID.`);
+  }
+  return value.toLowerCase();
+}
+
+function boundedDeviceName(value        )         {
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.length > DEVICE_NAME_MAX || /[\0\r\n]/.test(trimmed)) throw new OperatorError('DEVICE_IDENTITY_INVALID', 'Device name is invalid.');
+  return trimmed;
+}
+
+function boundedReason(value        )         {
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.length > REASON_MAX || /\0/.test(trimmed)) throw new OperatorError('DEVICE_REVOCATION_REASON_INVALID', 'Revocation reason is invalid.');
+  return trimmed;
+}
+
+function validIsoDate(value        , label        )         {
+  const time = Date.parse(value);
+  if (!Number.isFinite(time) || new Date(time).toISOString() !== value) throw new OperatorError('DEVICE_IDENTITY_INVALID', `${label} must be an ISO timestamp.`);
+  return value;
+}
+
+function publicChallenge(challenge                 )                         {
+  return {
+    version: 1,
+    purpose: PURPOSE,
+    challengeId: challenge.challengeId,
+    issuerDeviceId: challenge.issuerDeviceId,
+    issuerFingerprint: challenge.issuerFingerprint,
+    nonce: challenge.nonce,
+    issuedAt: challenge.issuedAt,
+    expiresAt: challenge.expiresAt,
+    expectedPeerDeviceId: challenge.expectedPeerDeviceId
+  };
+}

package/runtime/app/src/core/device-reset.js

@@ -0,0 +1,178 @@
+import path from 'node:path';
+import { OperatorError } from './errors.js';
+import { readDurableStateText, writeDurableStateText } from './durable-state.js';
+
+const MAX_RECORDS = 4096;
+const RETENTION_MS = 24 * 60 * 60_000;
+const MAX_STATE_BYTES = 2 * 1024 * 1024;
+
+                        
+
+                                    
+                     
+                   
+                    
+                              
+                                  
+                      
+                    
+                       
+ 
+
+                                                               
+
+export class DeviceResetStore {
+  #file        ;
+  #clock       ;
+  #queue                = Promise.resolve();
+
+  constructor(stateDir        , options                    = {}) {
+    this.#file = path.join(path.resolve(stateDir), 'device-resets.json');
+    this.#clock = options.clock ?? (() => new Date());
+  }
+
+  async get(sessionJtiInput        )                                    {
+    const sessionJti = validUuid(sessionJtiInput, 'sessionJti');
+    const state = await this.#read();
+    const record = state.records.find((candidate) => candidate.sessionJti === sessionJti);
+    return record ? clone(record) : null;
+  }
+
+  async begin(input   
+                       
+                     
+                      
+                                
+   )                             {
+    const sessionJti = validUuid(input.sessionJti, 'sessionJti');
+    const deviceId = validUuid(input.deviceId, 'deviceId');
+    const accountId = validUuid(input.accountId, 'accountId');
+    const authorityGeneration = validGeneration(input.authorityGeneration);
+    return await this.#mutate((state) => {
+      const now = this.#clock();
+      prune(state, now.getTime());
+      const existing = state.records.find((candidate) => candidate.sessionJti === sessionJti);
+      if (existing) {
+        if (existing.deviceId !== deviceId || existing.accountId !== accountId || existing.authorityGeneration !== authorityGeneration) {
+          throw new OperatorError('DEVICE_RESET_STATE_MISMATCH', 'Device reset authority no longer matches the recorded reset request.');
+        }
+        return clone(existing);
+      }
+      if (state.records.length >= MAX_RECORDS) throw new OperatorError('DEVICE_RESET_LIMIT', `At most ${MAX_RECORDS} device reset records may be retained.`);
+      const created                    = {
+        sessionJti, deviceId, accountId, authorityGeneration,
+        phase: 'REQUESTED', requestedAt: now.toISOString(), updatedAt: now.toISOString()
+      };
+      state.records.push(created);
+      return clone(created);
+    });
+  }
+
+  async complete(sessionJtiInput        )                             {
+    const sessionJti = validUuid(sessionJtiInput, 'sessionJti');
+    return await this.#mutate((state) => {
+      const record = state.records.find((candidate) => candidate.sessionJti === sessionJti);
+      if (!record) throw new OperatorError('DEVICE_RESET_NOT_FOUND', 'Device reset request was not found.');
+      if (record.phase === 'COMPLETE') return clone(record);
+      const now = this.#clock().toISOString();
+      record.phase = 'COMPLETE';
+      record.updatedAt = now;
+      record.completedAt = now;
+      return clone(record);
+    });
+  }
+
+  async #read()                      {
+    try {
+      const text = await readDurableStateText(this.#file, {
+        maxBytes: MAX_STATE_BYTES,
+        errorCode: 'DEVICE_RESET_STATE_CORRUPT',
+        invalidMessage: 'Device reset state is invalid.'
+      });
+      return validateState(JSON.parse(text));
+    } catch (error) {
+      if ((error                         ).code === 'ENOENT') return { version: 1, records: [] };
+      if (error instanceof OperatorError) throw error;
+      throw new OperatorError('DEVICE_RESET_STATE_CORRUPT', 'Device reset state could not be read.');
+    }
+  }
+  async #write(stateInput            )                {
+    const state = validateState(stateInput);
+    await writeDurableStateText(this.#file, JSON.stringify(state, null, 2), {
+      maxBytes: MAX_STATE_BYTES,
+      errorCode: 'DEVICE_RESET_STATE_CORRUPT',
+      invalidMessage: 'Device reset state is invalid.'
+    });
+  }
+
+  async #mutate   (mutator                                       )             {
+    let release             ;
+    const previous = this.#queue;
+    this.#queue = new Promise      ((resolve) => { release = resolve; });
+    await previous;
+    try {
+      const state = await this.#read();
+      const result = await mutator(state);
+      await this.#write(state);
+      return result;
+    } finally {
+      release();
+    }
+  }
+}
+
+function validateState(input            )             {
+  if (!input || typeof input !== 'object' || input.version !== 1 || !Array.isArray(input.records) || input.records.length > MAX_RECORDS) {
+    throw new OperatorError('DEVICE_RESET_STATE_CORRUPT', 'Device reset state structure is invalid.');
+  }
+  const seen = new Set        ();
+  const records = input.records.map((raw) => {
+    const sessionJti = validUuid(String(raw.sessionJti ?? ''), 'sessionJti');
+    if (seen.has(sessionJti)) throw new OperatorError('DEVICE_RESET_STATE_CORRUPT', 'Device reset state contains duplicate session IDs.');
+    seen.add(sessionJti);
+    const deviceId = validUuid(String(raw.deviceId ?? ''), 'deviceId');
+    const accountId = validUuid(String(raw.accountId ?? ''), 'accountId');
+    const authorityGeneration = validGeneration(Number(raw.authorityGeneration));
+    const phase = raw.phase === 'REQUESTED' ? 'REQUESTED' : raw.phase === 'COMPLETE' ? 'COMPLETE' : null;
+    if (!phase) throw new OperatorError('DEVICE_RESET_STATE_CORRUPT', 'Device reset phase is invalid.');
+    const requestedAt = validIso(String(raw.requestedAt ?? ''), 'requestedAt');
+    const updatedAt = validIso(String(raw.updatedAt ?? ''), 'updatedAt');
+    const completedAt = raw.completedAt === undefined ? undefined : validIso(String(raw.completedAt), 'completedAt');
+    if (phase === 'REQUESTED' && completedAt) throw new OperatorError('DEVICE_RESET_STATE_CORRUPT', 'Pending device reset cannot have a completion timestamp.');
+    if (phase === 'COMPLETE' && !completedAt) throw new OperatorError('DEVICE_RESET_STATE_CORRUPT', 'Completed device reset must have a completion timestamp.');
+    if (Date.parse(updatedAt) < Date.parse(requestedAt) || (completedAt && Date.parse(completedAt) < Date.parse(requestedAt))) {
+      throw new OperatorError('DEVICE_RESET_STATE_CORRUPT', 'Device reset timestamps are inconsistent.');
+    }
+    return { sessionJti, deviceId, accountId, authorityGeneration, phase, requestedAt, updatedAt, completedAt }                            ;
+  });
+  return { version: 1, records };
+}
+function prune(state            , nowMs        )       {
+  state.records = state.records.filter((record) => record.phase !== 'COMPLETE' || nowMs - Date.parse(record.completedAt ) <= RETENTION_MS);
+}
+
+function clone(record                   )                    {
+  return { ...record };
+}
+
+function validGeneration(value        )         {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new OperatorError('DEVICE_RESET_STATE_CORRUPT', 'Device reset authority generation is invalid.');
+  }
+  return value;
+}
+
+function validUuid(value        , label        )         {
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)) {
+    throw new OperatorError('DEVICE_RESET_STATE_CORRUPT', `${label} must be a UUID.`);
+  }
+  return value.toLowerCase();
+}
+
+function validIso(value        , label        )         {
+  const time = Date.parse(value);
+  if (!Number.isFinite(time) || new Date(time).toISOString() !== value) {
+    throw new OperatorError('DEVICE_RESET_STATE_CORRUPT', `${label} must be an ISO timestamp.`);
+  }
+  return value;
+}