mecord-connect 1.0.0

package/runtime/app/src/core/runtime.js

@@ -0,0 +1,136 @@
+                                                                                                                                 
+import { PolicyEngine } from './policy.js';
+import { CapabilityRouter } from './router.js';
+import { evidence } from './evidence.js';
+import { OperatorError } from './errors.js';
+import { assertCanonicalRisk, capabilityRiskRule } from './capability-policy.js';
+                                                               
+
+export class OperatorRuntime {
+           router                  ;
+           policy = new PolicyEngine();
+
+  constructor(options                                  = {}) {
+    this.router = new CapabilityRouter({ learning: options.learning });
+  }
+
+  register(provider                    )       {
+    this.router.register(provider);
+    return this;
+  }
+
+  async supportedCapabilities(capabilities                   )                    {
+    const supported           = [];
+    for (const capability of [...new Set(capabilities)].sort()) {
+      const action                = {
+        id: `capability-probe:${capability}`,
+        capability,
+        risk: 'read',
+        input: {},
+        provenance: { kind: 'runtime' }
+      };
+      if (await this.router.advertises(action)) supported.push(capability);
+    }
+    return supported;
+  }
+
+  async execute(action               , permissions                   , context                             = {})                        {
+    const start = performance.now();
+    if (context.signal?.aborted) return abortedResult(action, start);
+    let canonicalAction = action;
+    try {
+      this.policy.authorizeBase(action, permissions);
+      const rule = capabilityRiskRule(action.capability);
+      const canonicalRisk = rule === 'dynamic' ? await this.router.resolveRisk(action) : rule;
+      assertCanonicalRisk(action, canonicalRisk);
+      canonicalAction = { ...action, risk: canonicalRisk };
+      this.policy.authorizeRisk(canonicalAction, permissions);
+    } catch (error) {
+      const op = error instanceof OperatorError ? error : new OperatorError('POLICY_ERROR', String(error));
+      return {
+        ok: false,
+        capability: action.capability,
+        provider: 'policy',
+        evidence: [evidence('policy', 'fail', op.message, { code: op.code })],
+        error: { code: op.code, message: op.message, retryable: false },
+        durationMs: Math.round(performance.now() - start)
+      };
+    }
+
+    let ranked                                               ;
+    try {
+      ranked = await this.router.rank(canonicalAction, context.learningContext ?? 'global');
+    } catch (error) {
+      const op = error instanceof OperatorError
+        ? error
+        : new OperatorError('ROUTING_STATE_ERROR', error instanceof Error ? error.message : String(error));
+      return {
+        ok: false,
+        capability: action.capability,
+        provider: 'router',
+        evidence: [evidence('routing', 'fail', 'Provider ranking failed closed before execution.', { code: op.code })],
+        error: { code: op.code, message: op.message, retryable: false },
+        durationMs: Math.round(performance.now() - start)
+      };
+    }
+    if (ranked.length === 0) {
+      return {
+        ok: false,
+        capability: action.capability,
+        provider: 'router',
+        evidence: [evidence('routing', 'fail', `No provider supports ${action.capability}.`)],
+        error: { code: 'CAPABILITY_UNAVAILABLE', message: `No provider supports ${action.capability}.`, retryable: false },
+        durationMs: Math.round(performance.now() - start)
+      };
+    }
+
+    const failures = [];
+    for (const { provider, score, baseScore, learnedAdjustment } of ranked) {
+      try {
+        if (context.signal?.aborted) return abortedResult(canonicalAction, start);
+        const result = await provider.execute(canonicalAction, context);
+        result.evidence.unshift(evidence('routing', 'info', `Selected ${provider.name}.`, { score, baseScore, learnedAdjustment }));
+        result.durationMs = Math.round(performance.now() - start);
+        if (result.ok) return result;
+        failures.push(result.error ?? { code: 'PROVIDER_FAILED', message: `${provider.name} failed.` });
+      } catch (error) {
+        if (context.signal?.aborted || isAbortError(error)) return abortedResult(canonicalAction, start);
+        const op = error instanceof OperatorError
+          ? error
+          : new OperatorError('PROVIDER_EXCEPTION', error instanceof Error ? error.message : String(error), { retryable: true });
+        failures.push({ code: op.code, message: op.message, retryable: op.retryable });
+        if (!op.retryable) break;
+      }
+    }
+
+    const last = failures.at(-1) ?? { code: 'EXECUTION_FAILED', message: 'Execution failed.' };
+    return {
+      ok: false,
+      capability: action.capability,
+      provider: ranked[0].provider.name,
+      evidence: [evidence('execution', 'fail', last.message, { failures })],
+      error: last,
+      durationMs: Math.round(performance.now() - start)
+    };
+  }
+
+  async close()                {
+    await this.router.closeAll();
+  }
+}
+
+
+function isAbortError(error         )          {
+  return error instanceof Error && (error.name === 'AbortError' || error.message === 'The operation was aborted');
+}
+
+function abortedResult(action               , start        )               {
+  return {
+    ok: false,
+    capability: action.capability,
+    provider: 'runtime',
+    evidence: [evidence('execution', 'fail', 'Execution was cancelled before completion.', { code: 'EXECUTION_ABORTED' })],
+    error: { code: 'EXECUTION_ABORTED', message: 'Execution was cancelled before completion.', retryable: false },
+    durationMs: Math.round(performance.now() - start)
+  };
+}

package/runtime/app/src/core/scoped-path-syntax.js

@@ -0,0 +1,16 @@
+import path from 'node:path';
+
+                              
+                                              
+                                                       
+                                        
+
+export function normalizeScopedPathSyntax(inputPath        )                   {
+  if (path.isAbsolute(inputPath)) {
+    return { kind: 'native-absolute', value: path.resolve(inputPath) };
+  }
+  if (process.platform !== 'win32' && path.win32.isAbsolute(inputPath)) {
+    return { kind: 'foreign-windows-absolute', value: inputPath };
+  }
+  return { kind: 'relative', value: inputPath.replace(/\\/g, path.sep) };
+}

package/runtime/app/src/core/session-token.js

@@ -0,0 +1,498 @@
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { DeviceIdentityStore } from './device-identity.js';
+import { DeviceRegistryStore,                       } from './device-registry.js';
+import { OperatorError } from './errors.js';
+import { readDurableStateText, writeDurableStateText } from './durable-state.js';
+
+const PURPOSE = 'operator-session-v1';
+const MAX_TOKEN_BYTES = 16 * 1024;
+const MAX_PAYLOAD_BYTES = 8 * 1024;
+const DEFAULT_TTL_MS = 30 * 60_000;
+const MAX_TTL_MS = 30 * 60_000;
+const MIN_TTL_MS = 30_000;
+const MAX_SCOPES = 64;
+const MAX_RECORDS = 4096;
+const RETENTION_MS = 24 * 60 * 60_000;
+const RESET_RECEIPT_RECOVERY_MS = 24 * 60 * 60_000;
+
+                        
+                                                                                                         
+
+                                       
+             
+                          
+              
+                         
+                            
+                          
+                             
+                   
+                   
+                   
+                    
+ 
+
+                                                                                                                                             
+                               
+                     
+                         
+ 
+
+                                                                  
+
+export class DeviceSessionTokenStore {
+  #file        ;
+  #identity                     ;
+  #registry                     ;
+  #clock       ;
+  #onRevoke                    ;
+  #queue                = Promise.resolve();
+
+  constructor(stateDir        , identity                     , registry                     , options                                                  = {}) {
+    this.#file = path.join(path.resolve(stateDir), 'device-sessions.json');
+    this.#identity = identity;
+    this.#registry = registry;
+    this.#clock = options.clock ?? (() => new Date());
+    this.#onRevoke = options.onRevoke;
+  }
+
+  async issue(options                                                                                 )                                                            {
+    const local = await this.#identity.loadOrCreate();
+    const peer = await this.#activePeer(options.subjectDeviceId);
+    const audience = validAudience(options.audience);
+    const scopes = validScopes(options.scopes);
+    const ttlMs = boundedTtl(options.ttlMs ?? DEFAULT_TTL_MS);
+    const now = this.#clock();
+    const payload                       = {
+      version: 1,
+      purpose: PURPOSE,
+      jti: crypto.randomUUID(),
+      issuerDeviceId: local.deviceId,
+      issuerFingerprint: local.fingerprint,
+      subjectDeviceId: peer.deviceId,
+      subjectFingerprint: peer.fingerprint,
+      audience,
+      scopes,
+      issuedAt: now.toISOString(),
+      expiresAt: new Date(now.getTime() + ttlMs).toISOString()
+    };
+    const payloadBytes = encodePayload(payload);
+    const signature = await this.#identity.sign(payloadBytes);
+    const token = `${payloadBytes.toString('base64url')}.${signature}`;
+    if (Buffer.byteLength(token, 'utf8') > MAX_TOKEN_BYTES) throw new OperatorError('SESSION_TOKEN_TOO_LARGE', 'Generated session token exceeded the bounded size.');
+
+    await this.#mutate((state) => {
+      prune(state, now.getTime());
+      if (state.issued.length >= MAX_RECORDS) throw new OperatorError('SESSION_RECORD_LIMIT', `At most ${MAX_RECORDS} session records may be retained.`);
+      state.issued.push(recordFrom(payload));
+    });
+    return { token, payload };
+  }
+
+  async issueOrRecover(options                                                                                              )                                                            {
+    const jti = validUuid(options.jti, 'jti');
+    const local = await this.#identity.loadOrCreate();
+    const peer = await this.#activePeer(options.subjectDeviceId);
+    const audience = validAudience(options.audience);
+    const scopes = validScopes(options.scopes);
+    const ttlMs = boundedTtl(options.ttlMs ?? DEFAULT_TTL_MS);
+    const record = await this.#mutate((state) => {
+      const now = this.#clock();
+      prune(state, now.getTime());
+      const existing = state.issued.find((candidate) => candidate.jti === jti);
+      if (existing) {
+        if (existing.status !== 'active' || Date.parse(existing.expiresAt) <= now.getTime()) throw new OperatorError('SESSION_REVOKED', 'Enrollment session is no longer active.');
+        if (existing.issuerDeviceId !== local.deviceId || existing.subjectDeviceId !== peer.deviceId || existing.audience !== audience || JSON.stringify(existing.scopes) !== JSON.stringify(scopes)) {
+          throw new OperatorError('SESSION_STATE_MISMATCH', 'Enrollment session identity or scope changed.');
+        }
+        return { ...existing, scopes: [...existing.scopes] };
+      }
+      if (state.issued.length >= MAX_RECORDS) throw new OperatorError('SESSION_RECORD_LIMIT', `At most ${MAX_RECORDS} session records may be retained.`);
+      const created                      = {
+        jti, issuerDeviceId: local.deviceId, subjectDeviceId: peer.deviceId, audience, scopes: [...scopes],
+        issuedAt: now.toISOString(), expiresAt: new Date(now.getTime() + ttlMs).toISOString(), status: 'active'
+      };
+      state.issued.push(created);
+      return { ...created, scopes: [...created.scopes] };
+    });
+    return await this.#reissue(record);
+  }
+
+  async rotate(jtiInput        , options                     = {})                                                            {
+    const jti = validUuid(jtiInput, 'jti');
+    const snapshotState = await this.#read();
+    const snapshot = snapshotState.issued.find((candidate) => candidate.jti === jti);
+    if (!snapshot) throw new OperatorError('SESSION_NOT_FOUND', 'Issued session was not found.');
+    const now = this.#clock();
+    if (snapshot.status !== 'active') {
+      const successorJti = rotatedSuccessorJti(snapshot.revokedReason);
+      const successor = successorJti ? snapshotState.issued.find((candidate) => candidate.jti === successorJti) : undefined;
+      if (!successor || successor.status !== 'active' || Date.parse(successor.expiresAt) <= now.getTime()) {
+        throw new OperatorError('SESSION_REVOKED', 'Issued session is revoked.');
+      }
+      return await this.#reissue(successor);
+    }
+    if (Date.parse(snapshot.expiresAt) <= now.getTime()) throw new OperatorError('SESSION_EXPIRED', 'Issued session has expired.');
+
+    const local = await this.#identity.loadOrCreate();
+    const peer = await this.#activePeer(snapshot.subjectDeviceId);
+    const ttlMs = boundedTtl(options.ttlMs ?? DEFAULT_TTL_MS);
+    const payload                       = {
+      version: 1,
+      purpose: PURPOSE,
+      jti: crypto.randomUUID(),
+      issuerDeviceId: local.deviceId,
+      issuerFingerprint: local.fingerprint,
+      subjectDeviceId: peer.deviceId,
+      subjectFingerprint: peer.fingerprint,
+      audience: snapshot.audience,
+      scopes: [...snapshot.scopes],
+      issuedAt: now.toISOString(),
+      expiresAt: new Date(now.getTime() + ttlMs).toISOString()
+    };
+    const payloadBytes = encodePayload(payload);
+    const signature = await this.#identity.sign(payloadBytes);
+    const token = `${payloadBytes.toString('base64url')}.${signature}`;
+    if (Buffer.byteLength(token, 'utf8') > MAX_TOKEN_BYTES) throw new OperatorError('SESSION_TOKEN_TOO_LARGE', 'Generated session token exceeded the bounded size.');
+
+    await this.#mutate((state) => {
+      prune(state, now.getTime());
+      const current = state.issued.find((candidate) => candidate.jti === jti);
+      if (!current) throw new OperatorError('SESSION_NOT_FOUND', 'Issued session was not found during rotation.');
+      if (current.status !== 'active') throw new OperatorError('SESSION_REVOKED', 'Issued session was revoked during rotation.');
+      if (Date.parse(current.expiresAt) <= now.getTime()) throw new OperatorError('SESSION_EXPIRED', 'Issued session expired during rotation.');
+      if (current.subjectDeviceId !== snapshot.subjectDeviceId || current.audience !== snapshot.audience || JSON.stringify(current.scopes) !== JSON.stringify(snapshot.scopes)) {
+        throw new OperatorError('SESSION_STATE_MISMATCH', 'Issued session changed during rotation.');
+      }
+      if (state.issued.length >= MAX_RECORDS) throw new OperatorError('SESSION_RECORD_LIMIT', `At most ${MAX_RECORDS} session records may be retained.`);
+      current.status = 'revoked';
+      current.revokedAt = now.toISOString();
+      current.revokedReason = `rotated:${payload.jti}`;
+      state.issued.push(recordFrom(payload));
+    });
+    await this.#onRevoke?.(jti, snapshot.subjectDeviceId, `rotated:${payload.jti}`);
+    return { token, payload };
+  }
+
+  async revoke(jtiInput        , reasonInput         )                               {
+    const jti = validUuid(jtiInput, 'jti');
+    const reason = reasonInput === undefined ? undefined : validReason(reasonInput);
+    const outcome = await this.#mutate((state) => {
+      const record = state.issued.find((candidate) => candidate.jti === jti);
+      if (!record) throw new OperatorError('SESSION_NOT_FOUND', 'Issued session was not found.');
+      if (record.status === 'revoked') return { record: { ...record, scopes: [...record.scopes] }, changed: false };
+      record.status = 'revoked';
+      record.revokedAt = this.#clock().toISOString();
+      record.revokedReason = reason;
+      return { record: { ...record, scopes: [...record.scopes] }, changed: true };
+    });
+    if (outcome.changed) await this.#onRevoke?.(jti, outcome.record.subjectDeviceId, reason);
+    return outcome.record;
+  }
+
+  async listIssued(limit = 100)                                 {
+    const parsedLimit = Number(limit);
+    const bounded = Number.isFinite(parsedLimit) ? Math.min(Math.max(Math.trunc(parsedLimit), 1), 500) : 100;
+    const state = await this.#read();
+    return state.issued.slice(-bounded).reverse().map((record) => ({ ...record, scopes: [...record.scopes] }));
+  }
+
+  async verify(tokenInput        , options                                                                                   )                                {
+    return await this.#verifyToken(tokenInput, options, false);
+  }
+
+  async verifyForRotation(tokenInput        , options                                                                                   )                                {
+    return await this.#verifyToken(tokenInput, options, true);
+  }
+
+  async #verifyToken(tokenInput        , options                                                                                   , allowRotatedRetry         )                                {
+    const { payload, payloadBytes, signature } = parseToken(tokenInput);
+    const audience = validAudience(options.audience);
+    if (payload.audience !== audience) throw new OperatorError('SESSION_AUDIENCE_MISMATCH', 'Session token audience does not match this service.');
+    const requiredScopes = validScopes(options.requiredScopes ?? []);
+    for (const scope of requiredScopes) {
+      if (!payload.scopes.includes(scope)) throw new OperatorError('SESSION_SCOPE_DENIED', `Session token is missing required scope ${scope}.`);
+    }
+    if (options.expectedSubjectDeviceId && payload.subjectDeviceId !== validUuid(options.expectedSubjectDeviceId, 'expectedSubjectDeviceId')) {
+      throw new OperatorError('SESSION_SUBJECT_MISMATCH', 'Session token subject does not match the expected device.');
+    }
+    const now = this.#clock().getTime();
+    if (Date.parse(payload.issuedAt) > now + 30_000) throw new OperatorError('SESSION_NOT_YET_VALID', 'Session token issue time is too far in the future.');
+    if (Date.parse(payload.expiresAt) <= now) throw new OperatorError('SESSION_EXPIRED', 'Session token has expired.');
+
+    const local = await this.#identity.loadOrCreate();
+    let verified = false;
+    if (payload.issuerDeviceId === local.deviceId) {
+      if (payload.issuerFingerprint !== local.fingerprint) throw new OperatorError('SESSION_ISSUER_MISMATCH', 'Local issuer fingerprint does not match this device.');
+      verified = await this.#identity.verify(payloadBytes, signature);
+      const record = (await this.#read()).issued.find((candidate) => candidate.jti === payload.jti);
+      if (!record) throw new OperatorError('SESSION_NOT_FOUND', 'Locally issued session is not present in the session registry.');
+      if (record.status !== 'active' && !(allowRotatedRetry && rotatedSuccessorJti(record.revokedReason))) {
+        throw new OperatorError('SESSION_REVOKED', 'Session token has been revoked.');
+      }
+      if (!sameRecord(record, payload)) throw new OperatorError('SESSION_STATE_MISMATCH', 'Session token no longer matches its issued registry record.');
+    } else {
+      const issuer = await this.#activePeer(payload.issuerDeviceId);
+      if (issuer.fingerprint !== payload.issuerFingerprint) throw new OperatorError('SESSION_ISSUER_MISMATCH', 'Remote issuer fingerprint does not match the paired device.');
+      verified = await this.#registry.verifyDeviceSignature(payload.issuerDeviceId, payloadBytes, signature);
+    }
+    if (!verified) throw new OperatorError('SESSION_SIGNATURE_INVALID', 'Session token signature could not be verified.');
+
+    const subject = payload.subjectDeviceId === local.deviceId ? local : await this.#activePeer(payload.subjectDeviceId);
+    if (subject.fingerprint !== payload.subjectFingerprint) throw new OperatorError('SESSION_SUBJECT_MISMATCH', 'Session token subject fingerprint does not match the registered device.');
+    return payload;
+  }
+
+  async verifyForResetReceipt(tokenInput        , options                                                 )                                {
+    const { payload, payloadBytes, signature } = parseToken(tokenInput);
+    const audience = validAudience(options.audience);
+    if (payload.audience !== audience) throw new OperatorError('SESSION_AUDIENCE_MISMATCH', 'Session token audience does not match reset receipt authority.');
+    for (const scope of validScopes(options.requiredScopes ?? [])) {
+      if (!payload.scopes.includes(scope)) throw new OperatorError('SESSION_SCOPE_DENIED', `Session token is missing required scope ${scope}.`);
+    }
+    const now = this.#clock().getTime();
+    if (Date.parse(payload.issuedAt) > now + 30_000 || now - Date.parse(payload.expiresAt) > RESET_RECEIPT_RECOVERY_MS) {
+      throw new OperatorError('SESSION_RESET_RECEIPT_EXPIRED', 'Session token is outside the reset receipt recovery window.');
+    }
+    const local = await this.#identity.loadOrCreate();
+    if (payload.issuerDeviceId !== local.deviceId || payload.issuerFingerprint !== local.fingerprint) throw new OperatorError('SESSION_ISSUER_MISMATCH', 'Reset receipt token issuer does not match this relay.');
+    if (!(await this.#identity.verify(payloadBytes, signature))) throw new OperatorError('SESSION_SIGNATURE_INVALID', 'Reset receipt token signature could not be verified.');
+    return payload;
+  }
+
+  async isActive(jtiInput        , expectedSubjectDeviceId         )                   {
+    const jti = validUuid(jtiInput, 'jti');
+    const expectedSubject = expectedSubjectDeviceId === undefined ? undefined : validUuid(expectedSubjectDeviceId, 'expectedSubjectDeviceId');
+    const record = (await this.#read()).issued.find((candidate) => candidate.jti === jti);
+    if (!record || record.status !== 'active' || Date.parse(record.expiresAt) <= this.#clock().getTime()) return false;
+    if (expectedSubject && record.subjectDeviceId !== expectedSubject) return false;
+    try {
+      await this.#activePeer(record.subjectDeviceId);
+    } catch (error) {
+      if (error instanceof OperatorError && ['DEVICE_NOT_FOUND', 'DEVICE_REVOKED'].includes(error.code)) return false;
+      throw error;
+    }
+    return true;
+  }
+
+  async purgeForDevice(deviceIdInput        )                  {
+    const deviceId = validUuid(deviceIdInput, 'deviceId');
+    return await this.#mutate((state) => {
+      const before = state.issued.length;
+      state.issued = state.issued.filter((record) => record.subjectDeviceId !== deviceId && record.issuerDeviceId !== deviceId);
+      return before - state.issued.length;
+    });
+  }
+
+  async #reissue(record                     )                                                            {
+    const local = await this.#identity.loadOrCreate();
+    if (record.issuerDeviceId !== local.deviceId) throw new OperatorError('SESSION_STATE_MISMATCH', 'Rotated session issuer no longer matches this authority.');
+    const peer = await this.#activePeer(record.subjectDeviceId);
+    const payload                       = {
+      version: 1, purpose: PURPOSE, jti: record.jti, issuerDeviceId: local.deviceId, issuerFingerprint: local.fingerprint,
+      subjectDeviceId: peer.deviceId, subjectFingerprint: peer.fingerprint, audience: record.audience, scopes: [...record.scopes],
+      issuedAt: record.issuedAt, expiresAt: record.expiresAt
+    };
+    const payloadBytes = encodePayload(payload);
+    const signature = await this.#identity.sign(payloadBytes);
+    const token = `${payloadBytes.toString('base64url')}.${signature}`;
+    if (Buffer.byteLength(token, 'utf8') > MAX_TOKEN_BYTES) throw new OperatorError('SESSION_TOKEN_TOO_LARGE', 'Generated session token exceeded the bounded size.');
+    return { token, payload };
+  }
+
+  async #activePeer(deviceIdInput        )                            {
+    const deviceId = validUuid(deviceIdInput, 'deviceId');
+    const peer = (await this.#registry.listDevices()).find((candidate) => candidate.deviceId === deviceId);
+    if (!peer) throw new OperatorError('DEVICE_NOT_FOUND', 'Session peer device is not paired.');
+    if (peer.status !== 'active') throw new OperatorError('DEVICE_REVOKED', 'Session peer device is revoked.');
+    return peer;
+  }
+
+  async #read()                        {
+    try {
+      const text = await readDurableStateText(this.#file, {
+        maxBytes: 2 * 1024 * 1024,
+        errorCode: 'SESSION_STATE_CORRUPT',
+        invalidMessage: 'Session registry is invalid.'
+      });
+      return validateState(JSON.parse(text));
+    } catch (error) {
+      if ((error                         ).code === 'ENOENT') return { version: 1, issued: [] };
+      if (error instanceof OperatorError) throw error;
+      throw new OperatorError('SESSION_STATE_CORRUPT', 'Session 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: 'SESSION_STATE_CORRUPT',
+      invalidMessage: 'Session registry 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 encodePayload(payloadInput                      )         {
+  const payload = validatePayload(payloadInput);
+  const bytes = Buffer.from(JSON.stringify({
+    version: 1,
+    purpose: PURPOSE,
+    jti: payload.jti,
+    issuerDeviceId: payload.issuerDeviceId,
+    issuerFingerprint: payload.issuerFingerprint,
+    subjectDeviceId: payload.subjectDeviceId,
+    subjectFingerprint: payload.subjectFingerprint,
+    audience: payload.audience,
+    scopes: payload.scopes,
+    issuedAt: payload.issuedAt,
+    expiresAt: payload.expiresAt
+  }), 'utf8');
+  if (bytes.byteLength > MAX_PAYLOAD_BYTES) throw new OperatorError('SESSION_TOKEN_TOO_LARGE', 'Session token payload exceeds the bounded size.');
+  return bytes;
+}
+
+function parseToken(tokenInput        )                                                                             {
+  const token = String(tokenInput ?? '');
+  if (!token || Buffer.byteLength(token, 'utf8') > MAX_TOKEN_BYTES) throw new OperatorError('SESSION_TOKEN_INVALID', 'Session token is missing or too large.');
+  const parts = token.split('.');
+  if (parts.length !== 2 || !parts[0] || !/^[A-Za-z0-9_-]{40,256}$/.test(parts[1])) throw new OperatorError('SESSION_TOKEN_INVALID', 'Session token format is invalid.');
+  let payloadBytes        ;
+  let parsed         ;
+  try {
+    payloadBytes = Buffer.from(parts[0], 'base64url');
+    if (payloadBytes.byteLength > MAX_PAYLOAD_BYTES) throw new Error('large');
+    parsed = JSON.parse(payloadBytes.toString('utf8'));
+  } catch { throw new OperatorError('SESSION_TOKEN_INVALID', 'Session token payload is invalid.'); }
+  const payload = validatePayload(parsed                        );
+  if (!payloadBytes.equals(encodePayload(payload))) throw new OperatorError('SESSION_TOKEN_INVALID', 'Session token payload is not in canonical form.');
+  return { payload, payloadBytes, signature: parts[1] };
+}
+
+function validatePayload(input                      )                       {
+  if (!input || typeof input !== 'object' || input.version !== 1 || input.purpose !== PURPOSE) throw new OperatorError('SESSION_TOKEN_INVALID', 'Session token payload version or purpose is invalid.');
+  const jti = validUuid(String(input.jti ?? ''), 'jti');
+  const issuerDeviceId = validUuid(String(input.issuerDeviceId ?? ''), 'issuerDeviceId');
+  const subjectDeviceId = validUuid(String(input.subjectDeviceId ?? ''), 'subjectDeviceId');
+  const issuerFingerprint = validFingerprint(String(input.issuerFingerprint ?? ''), 'issuerFingerprint');
+  const subjectFingerprint = validFingerprint(String(input.subjectFingerprint ?? ''), 'subjectFingerprint');
+  const audience = validAudience(String(input.audience ?? ''));
+  const scopes = validScopes(input.scopes);
+  const issuedAt = validIso(String(input.issuedAt ?? ''), 'issuedAt');
+  const expiresAt = validIso(String(input.expiresAt ?? ''), 'expiresAt');
+  const lifetime = Date.parse(expiresAt) - Date.parse(issuedAt);
+  if (lifetime < MIN_TTL_MS || lifetime > MAX_TTL_MS) throw new OperatorError('SESSION_TOKEN_INVALID', 'Session token lifetime is outside the allowed range.');
+  return { version: 1, purpose: PURPOSE, jti, issuerDeviceId, issuerFingerprint, subjectDeviceId, subjectFingerprint, audience, scopes, issuedAt, expiresAt };
+}
+
+function validateState(input              )               {
+  if (!input || typeof input !== 'object' || input.version !== 1 || !Array.isArray(input.issued) || input.issued.length > MAX_RECORDS) throw new OperatorError('SESSION_STATE_CORRUPT', 'Session registry structure is invalid.');
+  const seen = new Set        ();
+  const issued = input.issued.map((raw) => {
+    const jti = validUuid(String(raw.jti ?? ''), 'jti');
+    if (seen.has(jti)) throw new OperatorError('SESSION_STATE_CORRUPT', 'Session registry contains duplicate token IDs.');
+    seen.add(jti);
+    const issuerDeviceId = validUuid(String(raw.issuerDeviceId ?? ''), 'issuerDeviceId');
+    const subjectDeviceId = validUuid(String(raw.subjectDeviceId ?? ''), 'subjectDeviceId');
+    const audience = validAudience(String(raw.audience ?? ''));
+    const scopes = validScopes(raw.scopes);
+    const issuedAt = validIso(String(raw.issuedAt ?? ''), 'issuedAt');
+    const expiresAt = validIso(String(raw.expiresAt ?? ''), 'expiresAt');
+    const status = raw.status === 'active' ? 'active' : raw.status === 'revoked' ? 'revoked' : null;
+    if (!status) throw new OperatorError('SESSION_STATE_CORRUPT', 'Session status is invalid.');
+    const revokedAt = raw.revokedAt === undefined ? undefined : validIso(String(raw.revokedAt), 'revokedAt');
+    const revokedReason = raw.revokedReason === undefined ? undefined : validReason(String(raw.revokedReason));
+    if (status === 'active' && revokedAt) throw new OperatorError('SESSION_STATE_CORRUPT', 'Active session cannot have a revocation timestamp.');
+    return { jti, issuerDeviceId, subjectDeviceId, audience, scopes, issuedAt, expiresAt, status, revokedAt, revokedReason }                              ;
+  });
+  return { version: 1, issued };
+}
+
+function recordFrom(payload                      )                      {
+  return {
+    jti: payload.jti,
+    issuerDeviceId: payload.issuerDeviceId,
+    subjectDeviceId: payload.subjectDeviceId,
+    audience: payload.audience,
+    scopes: [...payload.scopes],
+    issuedAt: payload.issuedAt,
+    expiresAt: payload.expiresAt,
+    status: 'active'
+  };
+}
+
+function sameRecord(record                     , payload                      )          {
+  return record.jti === payload.jti && record.issuerDeviceId === payload.issuerDeviceId && record.subjectDeviceId === payload.subjectDeviceId && record.audience === payload.audience && record.issuedAt === payload.issuedAt && record.expiresAt === payload.expiresAt && JSON.stringify(record.scopes) === JSON.stringify(payload.scopes);
+}
+
+function prune(state              , nowMs        )       {
+  state.issued = state.issued.filter((record) => {
+    if (record.status === 'revoked' && rotatedSuccessorJti(record.revokedReason)) {
+      return Date.parse(record.expiresAt) > nowMs;
+    }
+    return nowMs - Date.parse(record.expiresAt) <= RETENTION_MS;
+  });
+}
+
+function boundedTtl(value        )         {
+  if (!Number.isInteger(value) || value < MIN_TTL_MS || value > MAX_TTL_MS) throw new OperatorError('SESSION_TTL_INVALID', `Session TTL must be between ${MIN_TTL_MS} and ${MAX_TTL_MS} ms.`);
+  return value;
+}
+
+function validScopes(input         )           {
+  if (!Array.isArray(input) || input.length > MAX_SCOPES) throw new OperatorError('SESSION_SCOPE_INVALID', `Session scopes must contain at most ${MAX_SCOPES} entries.`);
+  const scopes = input.map((scope) => String(scope));
+  for (const scope of scopes) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:/*-]{0,127}$/.test(scope)) throw new OperatorError('SESSION_SCOPE_INVALID', `Invalid session scope ${scope}.`);
+  }
+  return [...new Set(scopes)].sort();
+}
+
+function validAudience(value        )         {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value)) throw new OperatorError('SESSION_AUDIENCE_INVALID', 'Session audience is invalid.');
+  return value;
+}
+
+function validFingerprint(value        , label        )         {
+  if (!/^[A-Za-z0-9_-]{32,128}$/.test(value)) throw new OperatorError('SESSION_TOKEN_INVALID', `${label} 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('SESSION_TOKEN_INVALID', `${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('SESSION_TOKEN_INVALID', `${label} must be an ISO timestamp.`);
+  return value;
+}
+
+function rotatedSuccessorJti(reason                    )                     {
+  if (!reason?.startsWith('rotated:')) return undefined;
+  const candidate = reason.slice('rotated:'.length);
+  return /^[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(candidate) ? candidate.toLowerCase() : undefined;
+}
+
+function validReason(value        )         {
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.length > 512 || /\0/.test(trimmed)) throw new OperatorError('SESSION_REVOCATION_REASON_INVALID', 'Session revocation reason is invalid.');
+  return trimmed;
+}