@lazyingart/agent-web 0.1.40

package/src/migrations.js

@@ -0,0 +1,231 @@
+import { createHash } from 'node:crypto';
+
+import { StorageCorruptionError, UnsupportedSchemaError } from './errors.js';
+
+export const SQLITE_APPLICATION_ID = 0x4c415757;
+
+const INITIAL_SCHEMA = `
+CREATE TABLE schema_migrations (
+  version INTEGER PRIMARY KEY,
+  name TEXT NOT NULL UNIQUE,
+  checksum TEXT NOT NULL CHECK (
+    length(checksum) = 64 AND checksum NOT GLOB '*[^0-9a-f]*'
+  ),
+  applied_at TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE accounts (
+  id TEXT PRIMARY KEY CHECK (length(id) BETWEEN 1 AND 128),
+  issuer TEXT NOT NULL CHECK (length(issuer) BETWEEN 1 AND 256),
+  subject TEXT NOT NULL CHECK (length(subject) BETWEEN 1 AND 512),
+  display_name TEXT CHECK (display_name IS NULL OR length(display_name) <= 256),
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  UNIQUE (issuer, subject)
+) STRICT;
+
+CREATE TABLE browser_sessions (
+  session_digest TEXT PRIMARY KEY CHECK (
+    length(session_digest) = 64 AND session_digest NOT GLOB '*[^0-9a-f]*'
+  ),
+  account_id TEXT NOT NULL,
+  csrf_digest TEXT NOT NULL CHECK (
+    length(csrf_digest) = 64 AND csrf_digest NOT GLOB '*[^0-9a-f]*'
+  ),
+  created_at TEXT NOT NULL,
+  expires_at TEXT NOT NULL,
+  last_seen_at TEXT NOT NULL,
+  revoked_at TEXT,
+  FOREIGN KEY (account_id) REFERENCES accounts(id) ON DELETE CASCADE
+) STRICT;
+
+CREATE INDEX browser_sessions_account_expiry
+  ON browser_sessions(account_id, expires_at DESC);
+
+CREATE TABLE thread_index (
+  thread_id TEXT PRIMARY KEY CHECK (length(thread_id) BETWEEN 1 AND 128),
+  account_id TEXT NOT NULL,
+  authority TEXT NOT NULL DEFAULT 'aginti' CHECK (authority = 'aginti'),
+  title TEXT NOT NULL DEFAULT '' CHECK (length(title) <= 120),
+  pinned INTEGER NOT NULL DEFAULT 0 CHECK (pinned IN (0, 1)),
+  routing_node_id TEXT CHECK (routing_node_id IS NULL OR length(routing_node_id) BETWEEN 1 AND 128),
+  authority_revision INTEGER CHECK (authority_revision IS NULL OR authority_revision >= 0),
+  last_run_id TEXT CHECK (last_run_id IS NULL OR length(last_run_id) BETWEEN 1 AND 128),
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  last_seen_at TEXT NOT NULL,
+  UNIQUE (account_id, thread_id),
+  FOREIGN KEY (account_id) REFERENCES accounts(id) ON DELETE CASCADE
+) STRICT;
+
+CREATE INDEX thread_index_owner_updated
+  ON thread_index(account_id, updated_at DESC, thread_id DESC);
+
+CREATE TABLE run_cursors (
+  run_id TEXT PRIMARY KEY CHECK (length(run_id) BETWEEN 1 AND 128),
+  account_id TEXT NOT NULL,
+  thread_id TEXT NOT NULL,
+  last_seq INTEGER NOT NULL CHECK (last_seq >= 0),
+  last_event_hash TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  CHECK (
+    (last_seq = 0 AND last_event_hash IS NULL)
+    OR (
+      last_seq > 0
+      AND length(last_event_hash) = 64
+      AND last_event_hash NOT GLOB '*[^0-9a-f]*'
+    )
+  ),
+  UNIQUE (account_id, run_id),
+  FOREIGN KEY (account_id, thread_id) REFERENCES thread_index(account_id, thread_id) ON DELETE CASCADE
+) STRICT;
+
+CREATE INDEX run_cursors_owner_thread_updated
+  ON run_cursors(account_id, thread_id, updated_at DESC, run_id DESC);
+
+CREATE TABLE idempotency_records (
+  account_id TEXT NOT NULL,
+  operation TEXT NOT NULL CHECK (length(operation) BETWEEN 1 AND 128),
+  key_hash TEXT NOT NULL CHECK (
+    length(key_hash) = 64 AND key_hash NOT GLOB '*[^0-9a-f]*'
+  ),
+  request_hash TEXT NOT NULL CHECK (
+    length(request_hash) = 64 AND request_hash NOT GLOB '*[^0-9a-f]*'
+  ),
+  outcome_code TEXT NOT NULL CHECK (outcome_code = 'succeeded'),
+  resource_kind TEXT NOT NULL CHECK (
+    resource_kind IN ('account', 'browser_session', 'thread_index')
+  ),
+  resource_id TEXT NOT NULL CHECK (length(resource_id) BETWEEN 1 AND 128),
+  result_digest TEXT NOT NULL CHECK (
+    length(result_digest) = 64 AND result_digest NOT GLOB '*[^0-9a-f]*'
+  ),
+  created_at TEXT NOT NULL,
+  expires_at TEXT NOT NULL,
+  PRIMARY KEY (account_id, operation, key_hash),
+  FOREIGN KEY (account_id) REFERENCES accounts(id) ON DELETE CASCADE
+) STRICT;
+
+CREATE INDEX idempotency_records_expiry
+  ON idempotency_records(expires_at);
+
+CREATE INDEX idempotency_records_owner_created
+  ON idempotency_records(account_id, created_at DESC);
+`;
+
+function checksum(sql) {
+  return createHash('sha256').update(sql, 'utf8').digest('hex');
+}
+
+export const MIGRATIONS = Object.freeze([
+  Object.freeze({
+    version: 1,
+    name: 'cloud_presentation_index',
+    sql: INITIAL_SCHEMA,
+    checksum: checksum(INITIAL_SCHEMA)
+  })
+]);
+
+export const LATEST_SCHEMA_VERSION = MIGRATIONS.at(-1).version;
+
+function pragmaInteger(database, pragma) {
+  const row = database.prepare(`PRAGMA ${pragma}`).get();
+  const value = row?.[pragma];
+  if (!Number.isSafeInteger(value)) {
+    throw new StorageCorruptionError(`SQLite returned an invalid ${pragma} value.`);
+  }
+  return value;
+}
+
+function assertIntegrity(database) {
+  const integrity = database.prepare('PRAGMA integrity_check').get();
+  if (integrity?.integrity_check !== 'ok') {
+    throw new StorageCorruptionError();
+  }
+  const foreignKeyFailures = database.prepare('PRAGMA foreign_key_check').all();
+  if (foreignKeyFailures.length !== 0) {
+    throw new StorageCorruptionError('The control-plane database contains invalid ownership references.');
+  }
+}
+
+function existingUserTables(database) {
+  return database.prepare(`
+    SELECT name
+    FROM sqlite_schema
+    WHERE type = 'table' AND name NOT LIKE 'sqlite_%'
+    ORDER BY name
+  `).all();
+}
+
+function verifyMigrationLedger(database, currentVersion) {
+  let rows;
+  try {
+    rows = database.prepare(`
+      SELECT version, name, checksum
+      FROM schema_migrations
+      ORDER BY version
+    `).all();
+  } catch (error) {
+    throw new StorageCorruptionError('The migration ledger is missing or unreadable.', { cause: error });
+  }
+  if (rows.length !== currentVersion) {
+    throw new StorageCorruptionError('The migration ledger does not match the schema version.');
+  }
+  for (let index = 0; index < currentVersion; index += 1) {
+    const expected = MIGRATIONS[index];
+    const actual = rows[index];
+    if (
+      Number(actual?.version) !== expected.version ||
+      actual?.name !== expected.name ||
+      actual?.checksum !== expected.checksum
+    ) {
+      throw new StorageCorruptionError(`Migration ${expected.version} failed checksum validation.`);
+    }
+  }
+}
+
+export function applyMigrations(database, appliedAt) {
+  assertIntegrity(database);
+
+  const currentVersion = pragmaInteger(database, 'user_version');
+  const applicationId = pragmaInteger(database, 'application_id');
+  if (currentVersion > LATEST_SCHEMA_VERSION) {
+    throw new UnsupportedSchemaError();
+  }
+  if (currentVersion === 0 && applicationId === 0 && existingUserTables(database).length !== 0) {
+    throw new StorageCorruptionError('Refusing to claim a non-empty, unidentified SQLite database.');
+  }
+  if (currentVersion > 0 && applicationId !== SQLITE_APPLICATION_ID) {
+    throw new StorageCorruptionError('The database belongs to a different application.');
+  }
+  if (applicationId !== 0 && applicationId !== SQLITE_APPLICATION_ID) {
+    throw new StorageCorruptionError('The database application identifier is not recognized.');
+  }
+
+  if (currentVersion > 0) verifyMigrationLedger(database, currentVersion);
+
+  for (const migration of MIGRATIONS.slice(currentVersion)) {
+    database.exec('BEGIN IMMEDIATE');
+    try {
+      database.exec(migration.sql);
+      database.prepare(`
+        INSERT INTO schema_migrations(version, name, checksum, applied_at)
+        VALUES (?, ?, ?, ?)
+      `).run(migration.version, migration.name, migration.checksum, appliedAt);
+      database.exec(`PRAGMA application_id = ${SQLITE_APPLICATION_ID}`);
+      database.exec(`PRAGMA user_version = ${migration.version}`);
+      database.exec('COMMIT');
+    } catch (error) {
+      try {
+        database.exec('ROLLBACK');
+      } catch {
+        // Preserve the original migration failure.
+      }
+      throw new StorageCorruptionError(`Migration ${migration.version} could not be applied.`, { cause: error });
+    }
+  }
+
+  verifyMigrationLedger(database, LATEST_SCHEMA_VERSION);
+  assertIntegrity(database);
+}

package/src/operator-health.js

@@ -0,0 +1,184 @@
+import { COMPONENT_ID, COMPONENT_ROLE } from './contracts.js';
+import { ControlPlaneError, ValidationError } from './errors.js';
+import { nowIso } from './validation.js';
+
+export const OPERATOR_HEALTH_SCHEMA = 'lazying-agent-web/operator-health/v1';
+export const OPERATOR_HEALTH_TIMEOUT_MS = 5_000;
+
+const RELEASE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,127}$/u;
+const MODEL_ALIAS_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/u;
+const SQLITE_VERSION_PATTERN = /^\d{1,3}\.\d{1,3}\.\d{1,3}$/u;
+const STORAGE_FAILURE_REASONS = new Set([
+  'storage_corruption',
+  'storage_security_error',
+  'unsupported_schema'
+]);
+const DEFAULT_CLOCK = () => new Date();
+
+function deepFreeze(value) {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    for (const child of Object.values(value)) deepFreeze(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+function storageFailure(error) {
+  const reason = error instanceof ControlPlaneError && STORAGE_FAILURE_REASONS.has(error.code)
+    ? error.code
+    : 'storage_unavailable';
+  return Object.freeze({ state: 'unavailable', reason });
+}
+
+function storageSuccess(value) {
+  if (!value || value.ready !== true
+      || !Number.isSafeInteger(value.schemaVersion) || value.schemaVersion < 1
+      || typeof value.sqliteVersion !== 'string'
+      || !SQLITE_VERSION_PATTERN.test(value.sqliteVersion)) {
+    throw new TypeError('storage health response is invalid');
+  }
+  return Object.freeze({
+    state: 'ready',
+    schemaVersion: value.schemaVersion,
+    sqliteVersion: value.sqliteVersion
+  });
+}
+
+async function inspectStorage(probe) {
+  try {
+    return storageSuccess(await probe());
+  } catch (error) {
+    return storageFailure(error);
+  }
+}
+
+function timeoutError() {
+  const error = new Error('operator dependency health probe timed out');
+  error.name = 'TimeoutError';
+  return error;
+}
+
+async function withTimeout(probe, timeoutMs) {
+  const controller = new AbortController();
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      const error = timeoutError();
+      controller.abort(error);
+      reject(error);
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([
+      Promise.resolve().then(() => probe({ signal: controller.signal })),
+      timeout
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function dependencyFailure(error) {
+  return Object.freeze({
+    state: 'unavailable',
+    reason: error?.name === 'TimeoutError' ? 'timeout' : 'dependency_unavailable'
+  });
+}
+
+async function inspectLocalLlm(probe, timeoutMs) {
+  try {
+    const value = await withTimeout(probe, timeoutMs);
+    if (!value || typeof value.ready !== 'boolean'
+        || !Array.isArray(value.availableModelAliases)
+        || value.availableModelAliases.length > 64
+        || value.availableModelAliases.some((alias) => (
+          typeof alias !== 'string' || !MODEL_ALIAS_PATTERN.test(alias)
+        ))) {
+      throw new TypeError('LocalLLM health response is invalid');
+    }
+    if (!value.ready) return Object.freeze({ state: 'unavailable', reason: 'model_unavailable' });
+    return Object.freeze({
+      state: 'ready',
+      availableModelAliasCount: value.availableModelAliases.length
+    });
+  } catch (error) {
+    return dependencyFailure(error);
+  }
+}
+
+async function inspectAginti(probe, timeoutMs) {
+  if (probe === null) return Object.freeze({ state: 'not_configured' });
+  try {
+    const value = await withTimeout(probe, timeoutMs);
+    if (!value || typeof value.enabled !== 'boolean') {
+      throw new TypeError('AgInTi health response is invalid');
+    }
+    return Object.freeze({
+      state: 'ready',
+      capabilityEnabled: value.enabled
+    });
+  } catch (error) {
+    return dependencyFailure(error);
+  }
+}
+
+export async function createOperatorHealthReport({
+  releaseId,
+  cloudIndexProbe,
+  directChatProbe,
+  localLlmProbe,
+  agintiProbe = null,
+  dependencyTimeoutMs = OPERATOR_HEALTH_TIMEOUT_MS,
+  clock = DEFAULT_CLOCK
+} = {}) {
+  if (typeof releaseId !== 'string' || !RELEASE_ID_PATTERN.test(releaseId)) {
+    throw new ValidationError('releaseId is invalid.');
+  }
+  if (typeof cloudIndexProbe !== 'function' || typeof directChatProbe !== 'function'
+      || typeof localLlmProbe !== 'function'
+      || (agintiProbe !== null && typeof agintiProbe !== 'function')) {
+    throw new ValidationError('operator health probes must be functions or an absent AgInTi probe.');
+  }
+  if (!Number.isSafeInteger(dependencyTimeoutMs)
+      || dependencyTimeoutMs < 10 || dependencyTimeoutMs > 30_000) {
+    throw new ValidationError('dependencyTimeoutMs is outside the operator health bound.');
+  }
+  if (typeof clock !== 'function') throw new ValidationError('clock must be a function.');
+
+  const checkedAt = nowIso(clock);
+  const [cloudIndexStore, directChatStore, localLlm, aginti] = await Promise.all([
+    inspectStorage(cloudIndexProbe),
+    inspectStorage(directChatProbe),
+    inspectLocalLlm(localLlmProbe, dependencyTimeoutMs),
+    inspectAginti(agintiProbe, dependencyTimeoutMs)
+  ]);
+  const storageReady = cloudIndexStore.state === 'ready' && directChatStore.state === 'ready';
+  const dependenciesReady = localLlm.state === 'ready'
+    && (aginti.state === 'ready' || aginti.state === 'not_configured');
+
+  return deepFreeze({
+    schema: OPERATOR_HEALTH_SCHEMA,
+    checkedAt,
+    status: storageReady ? (dependenciesReady ? 'ready' : 'degraded') : 'unavailable',
+    component: {
+      id: COMPONENT_ID,
+      role: COMPONENT_ROLE,
+      releaseId
+    },
+    scope: {
+      audience: 'operator',
+      publicHttpEndpoint: false,
+      staticShell: 'independent'
+    },
+    storage: { cloudIndexStore, directChatStore },
+    dependencies: {
+      localLlm,
+      aginti,
+      lazyEdge: {
+        state: 'not_probed',
+        healthClaim: false,
+        authority: 'lazyedge'
+      }
+    }
+  });
+}

package/src/password-verifier.js

@@ -0,0 +1,131 @@
+import { scrypt, timingSafeEqual } from 'node:crypto';
+
+const PREFIX = 'scrypt$v=1$n=131072,r=8,p=1$';
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/u;
+const SCRYPT_PARAMETERS = Object.freeze({
+  N: 131_072,
+  r: 8,
+  p: 1,
+  keyLength: 64,
+  maxmem: 256 * 1024 * 1024
+});
+const COMPATIBLE_KEY_LENGTHS = Object.freeze([32, SCRYPT_PARAMETERS.keyLength]);
+
+function canonicalBase64Url(value, name, { minimumBytes, maximumBytes }) {
+  if (typeof value !== 'string' || !BASE64URL_PATTERN.test(value) || value.includes('=')) {
+    throw new TypeError(`${name} must be canonical unpadded base64url`);
+  }
+  let decoded;
+  try {
+    decoded = Buffer.from(value, 'base64url');
+  } catch (error) {
+    throw new TypeError(`${name} is not valid base64url`, { cause: error });
+  }
+  if (decoded.toString('base64url') !== value
+      || decoded.byteLength < minimumBytes || decoded.byteLength > maximumBytes) {
+    decoded.fill(0);
+    throw new TypeError(`${name} has an invalid canonical length`);
+  }
+  return decoded;
+}
+
+function parseRecord(record) {
+  if (typeof record !== 'string' || record.length < PREFIX.length + 2
+      || record.length > 1_024 || /[\s\u0000-\u001f\u007f]/u.test(record)
+      || !record.startsWith(PREFIX)) {
+    throw new TypeError('password credential is not the required fixed scrypt record');
+  }
+  const fields = record.slice(PREFIX.length).split('$');
+  if (fields.length !== 2) throw new TypeError('password credential has an invalid field count');
+  const salt = canonicalBase64Url(fields[0], 'scrypt salt', {
+    minimumBytes: 16,
+    maximumBytes: 64
+  });
+  let digest;
+  try {
+    digest = canonicalBase64Url(fields[1], 'scrypt digest', {
+      minimumBytes: COMPATIBLE_KEY_LENGTHS[0],
+      maximumBytes: SCRYPT_PARAMETERS.keyLength
+    });
+    if (!COMPATIBLE_KEY_LENGTHS.includes(digest.byteLength)) {
+      digest.fill(0);
+      throw new TypeError('scrypt digest has an unsupported canonical length');
+    }
+  } catch (error) {
+    salt.fill(0);
+    throw error;
+  }
+  return { salt, digest, keyLength: digest.byteLength };
+}
+
+function passwordInput(value) {
+  if (typeof value !== 'string' || Buffer.byteLength(value, 'utf8') > 4_096) {
+    throw new TypeError('password must be a bounded string');
+  }
+  return value;
+}
+
+function derive(password, salt, keyLength) {
+  return new Promise((resolve, reject) => {
+    scrypt(password, salt, keyLength, {
+      N: SCRYPT_PARAMETERS.N,
+      r: SCRYPT_PARAMETERS.r,
+      p: SCRYPT_PARAMETERS.p,
+      maxmem: SCRYPT_PARAMETERS.maxmem
+    }, (error, result) => error ? reject(error) : resolve(result));
+  });
+}
+
+function abortReason(signal) {
+  return signal?.reason ?? new DOMException('password verification aborted', 'AbortError');
+}
+
+export function createScryptPasswordVerifier(encodedHash) {
+  const parsed = parseRecord(encodedHash);
+  const salt = Buffer.from(parsed.salt);
+  const expected = Buffer.from(parsed.digest);
+  const keyLength = parsed.keyLength;
+  parsed.salt.fill(0);
+  parsed.digest.fill(0);
+
+  return Object.freeze({
+    algorithm: 'scrypt',
+    parameters: Object.freeze({
+      version: 1,
+      n: SCRYPT_PARAMETERS.N,
+      r: SCRYPT_PARAMETERS.r,
+      p: SCRYPT_PARAMETERS.p,
+      keyLength
+    }),
+    async verify(candidate, { signal } = {}) {
+      const password = passwordInput(candidate);
+      if (signal !== undefined && !(signal instanceof AbortSignal)) {
+        throw new TypeError('signal must be an AbortSignal');
+      }
+      if (signal?.aborted) throw abortReason(signal);
+      const actual = await derive(password, salt, keyLength);
+      try {
+        if (signal?.aborted) throw abortReason(signal);
+        return actual.byteLength === expected.byteLength && timingSafeEqual(actual, expected);
+      } finally {
+        actual.fill(0);
+      }
+    }
+  });
+}
+
+export function validateScryptPasswordHash(encodedHash) {
+  const parsed = parseRecord(encodedHash);
+  parsed.salt.fill(0);
+  parsed.digest.fill(0);
+  return true;
+}
+
+export const PASSWORD_SCRYPT_FORMAT = Object.freeze({
+  prefix: PREFIX,
+  version: 1,
+  n: SCRYPT_PARAMETERS.N,
+  r: SCRYPT_PARAMETERS.r,
+  p: SCRYPT_PARAMETERS.p,
+  keyLength: SCRYPT_PARAMETERS.keyLength
+});