@lazyingart/agent-web 0.1.40

package/src/service.js

@@ -0,0 +1,408 @@
+import { createHash } from 'node:crypto';
+
+import {
+  createAgintiAgentAdapter,
+  validateAgintiTransportCredential
+} from './aginti-adapter.js';
+import { DirectChatContextCoordinator } from './chat-context.js';
+import {
+  CHAT_SQLITE_APPLICATION_ID,
+  DEFAULT_CHAT_SCHEMA_VERSION,
+  LATEST_CHAT_SCHEMA_VERSION
+} from './chat-migrations.js';
+import { DirectChatStore } from './chat-store.js';
+import { createCloudServer } from './cloud-server.js';
+import { createDeterministicContextSummarizer } from './deterministic-context-summarizer.js';
+import { createLocalLlmConnector } from './localllm-connector.js';
+import { LATEST_SCHEMA_VERSION, SQLITE_APPLICATION_ID } from './migrations.js';
+import {
+  OPERATOR_HEALTH_TIMEOUT_MS,
+  createOperatorHealthReport
+} from './operator-health.js';
+import {
+  createScryptPasswordVerifier,
+  validateScryptPasswordHash
+} from './password-verifier.js';
+import { assertLoadedServiceConfig } from './service-config.js';
+import { checkSqliteFileHealth } from './sqlite-health.js';
+import { CloudIndexStore } from './store.js';
+import { AGINTI_RPC_PATHS } from './web/aginti-protocol.js';
+import {
+  createStandaloneAssetMap,
+  verifyStandaloneAssetMap
+} from './web/asset-map.js';
+
+export const TRUSTED_STANDALONE_BOOTSTRAP_SOURCE = `
+import katex from "./katex.mjs";
+import { createBrowserApp } from "./browser-app.js";
+import { createSafeRenderer } from "./safe-rendering.js";
+
+const renderer = createSafeRenderer({ katex });
+const app = createBrowserApp({ renderer });
+void app.initialize();
+`;
+
+function sha256(value) {
+  return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+
+const OPERATOR_HEALTH_BROWSER_SESSION = sha256('lazying-agent-web/operator-health/v1');
+
+function validateTransportCredential(value, label) {
+  if (typeof value !== 'string' || value.length < 16 || value.length > 4_096
+      || /[\s\u0000-\u001f\u007f]/u.test(value)) {
+    throw new TypeError(`${label} transport credential is invalid`);
+  }
+  return true;
+}
+
+async function buildAssetMap(config) {
+  const assetMap = await createStandaloneAssetMap({
+    bootstrapSource: TRUSTED_STANDALONE_BOOTSTRAP_SOURCE,
+    versionLabel: config.pwa.versionLabel,
+    basePath: '/',
+    title: config.pwa.title,
+    loginPath: '/api/login',
+    name: config.pwa.name,
+    shortName: config.pwa.shortName
+  });
+  verifyStandaloneAssetMap(assetMap);
+  if (assetMap.serviceWorkerRoute !== '/sw.js') {
+    throw new TypeError('standalone PWA service worker must remain at stable /sw.js');
+  }
+  return assetMap;
+}
+
+async function materializeInputs(loadedConfig, { createVerifier = true } = {}) {
+  const loaded = assertLoadedServiceConfig(loadedConfig);
+  let passwordHash = loaded.readCredential('passwordHash');
+  let passwordVerifier;
+  try {
+    if (createVerifier) passwordVerifier = createScryptPasswordVerifier(passwordHash);
+    else validateScryptPasswordHash(passwordHash);
+  } finally {
+    passwordHash = null;
+  }
+  let localLlmCredential = loaded.readCredential('localLlmToken');
+  try {
+    validateTransportCredential(localLlmCredential, 'LocalLLM');
+  } finally {
+    localLlmCredential = null;
+  }
+  if (loaded.config.aginti.enabled) {
+    let agintiCredential = loaded.readCredential('agintiToken');
+    try {
+      validateAgintiTransportCredential(agintiCredential);
+    } finally {
+      agintiCredential = null;
+    }
+  }
+  const assetMap = await buildAssetMap(loaded.config);
+  return Object.freeze({
+    loaded,
+    passwordVerifier,
+    assetMap,
+    localLlmCredentialProvider: loaded.createCredentialProvider('localLlmToken'),
+    ...(loaded.config.aginti.enabled
+      ? { agintiCredentialProvider: loaded.createCredentialProvider('agintiToken') }
+      : {})
+  });
+}
+
+function accountProvisionKey(config) {
+  return `service-account-v1.${sha256(JSON.stringify({
+    principalId: config.account.principalId,
+    username: config.account.username,
+    displayName: config.account.displayName
+  }))}`;
+}
+
+function closeStores(controlStore, directChatStore) {
+  const failures = [];
+  for (const store of [directChatStore, controlStore]) {
+    if (!store) continue;
+    try {
+      store.close();
+    } catch (error) {
+      failures.push(error);
+    }
+  }
+  if (failures.length === 1) throw failures[0];
+  if (failures.length > 1) throw new AggregateError(failures, 'service stores did not close cleanly');
+}
+
+function safeReport(config, assetMap) {
+  return Object.freeze({
+    valid: true,
+    schema: config.schema,
+    listen: Object.freeze({ ...config.listen }),
+    publicOrigin: config.publicOrigin,
+    releaseId: assetMap.releaseVersion,
+    serviceWorkerRoute: assetMap.serviceWorkerRoute,
+    agentEnabled: false,
+    agentConfigured: config.aginti.enabled,
+    directChatEnabled: true
+  });
+}
+
+function safeEdgeRouteManifest(config, assetMap) {
+  verifyStandaloneAssetMap(assetMap);
+  const requestTargets = Object.freeze([...assetMap.routes]);
+  const paths = Object.freeze([...new Set(requestTargets.map((target) => target.split('?', 1)[0]))].sort());
+  if (paths.some((pathname) => typeof pathname !== 'string' || !pathname.startsWith('/'))
+      || requestTargets.some((target) => typeof target !== 'string' || !target.startsWith('/'))) {
+    throw new TypeError('standalone PWA edge route manifest is invalid');
+  }
+  return Object.freeze({
+    schema: 'lazying-agent-web/edge-route-manifest/v1',
+    publicOrigin: config.publicOrigin,
+    releaseId: assetMap.releaseVersion,
+    methods: Object.freeze(['GET', 'HEAD']),
+    paths,
+    requestTargets
+  });
+}
+
+export async function checkStandaloneServiceConfiguration(loadedConfig) {
+  const materialized = await materializeInputs(loadedConfig, { createVerifier: false });
+  return safeReport(materialized.loaded.config, materialized.assetMap);
+}
+
+export async function createStandaloneServiceEdgeRouteManifest(loadedConfig) {
+  const materialized = await materializeInputs(loadedConfig, { createVerifier: false });
+  return safeEdgeRouteManifest(materialized.loaded.config, materialized.assetMap);
+}
+
+export async function checkStandaloneServiceHealth(loadedConfig, {
+  fetchImpl,
+  dependencyTimeoutMs = OPERATOR_HEALTH_TIMEOUT_MS,
+  databaseHealthChecker = checkSqliteFileHealth,
+  clock
+} = {}) {
+  if (fetchImpl !== undefined && typeof fetchImpl !== 'function') {
+    throw new TypeError('fetchImpl must be a function');
+  }
+  if (typeof databaseHealthChecker !== 'function') {
+    throw new TypeError('databaseHealthChecker must be a function');
+  }
+  if (clock !== undefined && typeof clock !== 'function') throw new TypeError('clock must be a function');
+
+  const loaded = assertLoadedServiceConfig(loadedConfig);
+  const config = loaded.config;
+  const assetMap = await buildAssetMap(config);
+  const localLlmConnector = createLocalLlmConnector({
+    baseUrl: config.localLlm.baseUrl,
+    allowedModelAliases: config.localLlm.allowedModelAliases,
+    credentialProvider: loaded.createCredentialProvider('localLlmToken'),
+    ...(fetchImpl === undefined ? {} : { fetchImpl })
+  });
+  const agintiAdapter = config.aginti.enabled
+    ? createAgintiAgentAdapter({
+        upstream: config.aginti.baseUrl,
+        credentialProvider: loaded.createCredentialProvider('agintiToken'),
+        ...(fetchImpl === undefined ? {} : { fetchImpl })
+      })
+    : null;
+  const allowedDirectChatSchemas = config.localLlm.vision.enabled
+    ? [LATEST_CHAT_SCHEMA_VERSION]
+    : [...new Set([DEFAULT_CHAT_SCHEMA_VERSION, LATEST_CHAT_SCHEMA_VERSION])];
+
+  return createOperatorHealthReport({
+    releaseId: assetMap.releaseVersion,
+    cloudIndexProbe: () => databaseHealthChecker({
+      databasePath: config.state.cloudIndexDatabase,
+      expectedApplicationId: SQLITE_APPLICATION_ID,
+      allowedSchemaVersions: [LATEST_SCHEMA_VERSION]
+    }),
+    directChatProbe: () => databaseHealthChecker({
+      databasePath: config.state.directChatDatabase,
+      expectedApplicationId: CHAT_SQLITE_APPLICATION_ID,
+      allowedSchemaVersions: allowedDirectChatSchemas
+    }),
+    localLlmProbe: ({ signal }) => localLlmConnector.readiness({ signal }),
+    agintiProbe: agintiAdapter === null
+      ? null
+      : ({ signal }) => agintiAdapter.rpc(AGINTI_RPC_PATHS.capabilities, {}, {
+          principalId: config.account.principalId,
+          browserSession: OPERATOR_HEALTH_BROWSER_SESSION,
+          signal
+        }),
+    dependencyTimeoutMs,
+    ...(clock === undefined ? {} : { clock })
+  });
+}
+
+export async function createStandaloneService({
+  loadedConfig,
+  fetchImpl,
+  localSummarizer,
+  serverFactory = createCloudServer,
+  clock
+} = {}) {
+  if (typeof serverFactory !== 'function') throw new TypeError('serverFactory must be a function');
+  if (fetchImpl !== undefined && typeof fetchImpl !== 'function') {
+    throw new TypeError('fetchImpl must be a function');
+  }
+  if (localSummarizer !== undefined && localSummarizer !== null
+      && (typeof localSummarizer !== 'object' || localSummarizer.locality !== 'local'
+        || typeof localSummarizer.summarizeDirectChat !== 'function')) {
+    throw new TypeError('localSummarizer must be a local-only Direct Chat summarizer');
+  }
+  if (clock !== undefined && typeof clock !== 'function') throw new TypeError('clock must be a function');
+
+  const materialized = await materializeInputs(loadedConfig);
+  const config = materialized.loaded.config;
+  let controlStore;
+  let directChatStore;
+  let server;
+  try {
+    controlStore = new CloudIndexStore({
+      databasePath: config.state.cloudIndexDatabase,
+      ...(clock === undefined ? {} : { clock })
+    });
+    directChatStore = new DirectChatStore({
+      databasePath: config.state.directChatDatabase,
+      modelAlias: config.localLlm.defaultModelAlias,
+      visionModelAlias: config.localLlm.vision.modelAlias,
+      enableVisionAttachments: config.localLlm.vision.enabled,
+      ...(clock === undefined ? {} : { clock })
+    });
+    const account = controlStore.provisionAccount({
+      accountId: config.account.principalId,
+      issuer: 'local-login',
+      subject: config.account.username,
+      displayName: config.account.displayName,
+      idempotencyKey: accountProvisionKey(config)
+    });
+    if (account.issuer !== 'local-login' || account.subject !== config.account.username
+        || account.displayName !== config.account.displayName) {
+      throw new TypeError('provisioned account does not match the immutable service identity config');
+    }
+    const directChatSummarizer = localSummarizer ?? createDeterministicContextSummarizer();
+    const directChatContext = new DirectChatContextCoordinator({
+      store: directChatStore,
+      localSummarizer: directChatSummarizer
+    });
+    const directChatConnector = createLocalLlmConnector({
+      baseUrl: config.localLlm.baseUrl,
+      allowedModelAliases: config.localLlm.allowedModelAliases,
+      credentialProvider: materialized.localLlmCredentialProvider,
+      ...(fetchImpl === undefined ? {} : { fetchImpl })
+    });
+    const agintiAdapter = config.aginti.enabled
+      ? createAgintiAgentAdapter({
+          upstream: config.aginti.baseUrl,
+          credentialProvider: materialized.agintiCredentialProvider,
+          ...(fetchImpl === undefined ? {} : { fetchImpl })
+        })
+      : null;
+    server = serverFactory({
+      releaseId: materialized.assetMap.releaseVersion,
+      assetMap: materialized.assetMap,
+      publicOrigin: config.publicOrigin,
+      account: {
+        username: config.account.username,
+        principalId: config.account.principalId
+      },
+      passwordVerifier: materialized.passwordVerifier,
+      sessionStore: controlStore,
+      controlStore,
+      directChatStore,
+      directChatContext,
+      directChatSummarizer,
+      directChatConnector,
+      visionEnabled: config.localLlm.vision.enabled,
+      visionModelAlias: config.localLlm.vision.modelAlias,
+      agintiAdapter,
+      requestOutcomeObserver(outcome) {
+        if (outcome.result === 'rejected') {
+          console.warn(JSON.stringify({ event: 'cloud_request_outcome', ...outcome }));
+        }
+      },
+      ...(clock === undefined ? {} : { clock })
+    });
+    if (!server || typeof server.listen !== 'function' || typeof server.shutdown !== 'function'
+        || typeof server.address !== 'function' || typeof server.once !== 'function'
+        || typeof server.removeListener !== 'function') {
+      throw new TypeError('serverFactory returned an invalid graceful server');
+    }
+
+    let startPromise = null;
+    let shutdownPromise = null;
+    let stopped = false;
+    const start = () => {
+      if (stopped) return Promise.reject(new Error('standalone service is already stopped'));
+      if (startPromise) return startPromise;
+      startPromise = new Promise((resolve, reject) => {
+        const onError = (error) => {
+          server.removeListener('error', onError);
+          reject(error);
+        };
+        server.once('error', onError);
+        server.listen(config.listen.port, '127.0.0.1', () => {
+          server.removeListener('error', onError);
+          const address = server.address();
+          if (!address || typeof address !== 'object' || address.address !== '127.0.0.1'
+              || address.port !== config.listen.port) {
+            void shutdown();
+            reject(new Error('server did not bind the exact configured loopback endpoint'));
+            return;
+          }
+          resolve(Object.freeze({ address: '127.0.0.1', port: address.port }));
+        });
+      });
+      return startPromise;
+    };
+    const shutdown = () => {
+      if (shutdownPromise) return shutdownPromise;
+      stopped = true;
+      shutdownPromise = (async () => {
+        const failures = [];
+        try {
+          await server.shutdown();
+        } catch (error) {
+          failures.push(error);
+        }
+        try {
+          closeStores(controlStore, directChatStore);
+        } catch (error) {
+          failures.push(error);
+        }
+        if (failures.length === 1) throw failures[0];
+        if (failures.length > 1) throw new AggregateError(failures, 'standalone service shutdown failed');
+      })();
+      return shutdownPromise;
+    };
+
+    return Object.freeze({
+      kind: 'lazying-agent-standalone-service',
+      releaseId: materialized.assetMap.releaseVersion,
+      listen: Object.freeze({ ...config.listen }),
+      publicOrigin: config.publicOrigin,
+      account: Object.freeze({ ...account }),
+      agentEnabled: false,
+      assetMap: materialized.assetMap,
+      server,
+      controlStore,
+      directChatStore,
+      directChatContext,
+      directChatSummarizer,
+      directChatConnector,
+      agintiAdapter,
+      start,
+      shutdown
+    });
+  } catch (error) {
+    try {
+      if (server?.shutdown) await server.shutdown();
+    } catch {
+      // Preserve the construction failure.
+    }
+    try {
+      closeStores(controlStore, directChatStore);
+    } catch {
+      // Preserve the construction failure.
+    }
+    throw error;
+  }
+}

package/src/sqlite-health.js

@@ -0,0 +1,83 @@
+import { DatabaseSync } from 'node:sqlite';
+import { isAbsolute, resolve } from 'node:path';
+
+import { StorageCorruptionError, ValidationError } from './errors.js';
+import { assertSecureDatabaseFile } from './storage-path.js';
+
+const SQLITE_VERSION_PATTERN = /^\d{1,3}\.\d{1,3}\.\d{1,3}$/u;
+
+function normalizedSchemaVersions(value) {
+  if (!Array.isArray(value) || value.length < 1 || value.length > 4) {
+    throw new ValidationError('allowedSchemaVersions must be a short non-empty array.');
+  }
+  const versions = [...new Set(value)];
+  if (versions.length !== value.length
+      || versions.some((version) => !Number.isSafeInteger(version) || version < 1)) {
+    throw new ValidationError('allowedSchemaVersions contains an invalid schema version.');
+  }
+  return Object.freeze(versions);
+}
+
+export function checkOpenSqliteHealth(database, {
+  expectedApplicationId,
+  allowedSchemaVersions
+} = {}) {
+  if (!database || typeof database.prepare !== 'function') {
+    throw new ValidationError('database must provide prepare().');
+  }
+  if (!Number.isSafeInteger(expectedApplicationId) || expectedApplicationId < 1) {
+    throw new ValidationError('expectedApplicationId is invalid.');
+  }
+  const schemaVersions = normalizedSchemaVersions(allowedSchemaVersions);
+
+  const quickCheck = database.prepare('PRAGMA quick_check').get();
+  if (quickCheck?.quick_check !== 'ok') throw new StorageCorruptionError();
+  if (database.prepare('PRAGMA foreign_key_check').all().length !== 0) {
+    throw new StorageCorruptionError('The database contains invalid ownership references.');
+  }
+  const schemaVersion = Number(database.prepare('PRAGMA user_version').get()?.user_version);
+  const applicationId = Number(database.prepare('PRAGMA application_id').get()?.application_id);
+  if (!schemaVersions.includes(schemaVersion) || applicationId !== expectedApplicationId) {
+    throw new StorageCorruptionError('The database identity or schema version changed unexpectedly.');
+  }
+  const sqliteVersion = database.prepare('SELECT sqlite_version() AS version').get()?.version;
+  if (typeof sqliteVersion !== 'string' || !SQLITE_VERSION_PATTERN.test(sqliteVersion)) {
+    throw new StorageCorruptionError('SQLite returned an invalid runtime version.');
+  }
+  return Object.freeze({ ready: true, schemaVersion, sqliteVersion });
+}
+
+export function checkSqliteFileHealth({
+  databasePath,
+  expectedApplicationId,
+  allowedSchemaVersions
+} = {}) {
+  if (typeof databasePath !== 'string' || !isAbsolute(databasePath)
+      || resolve(databasePath) !== databasePath) {
+    throw new ValidationError('databasePath must be an absolute normalized path.');
+  }
+  assertSecureDatabaseFile(databasePath);
+  let database;
+  try {
+    database = new DatabaseSync(databasePath, { readOnly: true });
+    database.enableLoadExtension(false);
+    database.exec(`
+      PRAGMA busy_timeout = 1000;
+      PRAGMA query_only = ON;
+      PRAGMA trusted_schema = OFF;
+    `);
+    return checkOpenSqliteHealth(database, {
+      expectedApplicationId,
+      allowedSchemaVersions
+    });
+  } catch (error) {
+    if (error instanceof StorageCorruptionError || error instanceof ValidationError) throw error;
+    throw new StorageCorruptionError('The database could not be inspected read-only.', { cause: error });
+  } finally {
+    try {
+      database?.close();
+    } finally {
+      assertSecureDatabaseFile(databasePath);
+    }
+  }
+}

package/src/storage-path.js

@@ -0,0 +1,130 @@
+import {
+  chmodSync,
+  closeSync,
+  constants,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  realpathSync
+} from 'node:fs';
+import { dirname, isAbsolute, parse, resolve, sep } from 'node:path';
+
+import { StorageSecurityError, ValidationError } from './errors.js';
+
+function currentUid() {
+  return typeof process.getuid === 'function' ? process.getuid() : null;
+}
+
+function assertOwned(stat, label) {
+  const uid = currentUid();
+  if (uid !== null && stat.uid !== uid) {
+    throw new StorageSecurityError(`${label} must be owned by the current user.`);
+  }
+}
+
+function assertPrivateMode(stat, label) {
+  if ((stat.mode & 0o077) !== 0) {
+    throw new StorageSecurityError(`${label} must not be accessible by group or other users.`);
+  }
+}
+
+function lstatIfPresent(pathname) {
+  try {
+    return lstatSync(pathname);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function pathComponents(absolutePath) {
+  const { root } = parse(absolutePath);
+  const relative = absolutePath.slice(root.length);
+  const parts = relative.length === 0 ? [] : relative.split(sep).filter(Boolean);
+  const paths = [root];
+  let current = root;
+  for (const part of parts) {
+    current = resolve(current, part);
+    paths.push(current);
+  }
+  return paths;
+}
+
+function assertNoSymlinkComponents(absolutePath) {
+  for (const candidate of pathComponents(absolutePath)) {
+    const stat = lstatIfPresent(candidate);
+    if (!stat) break;
+    if (stat.isSymbolicLink()) {
+      throw new StorageSecurityError(`Storage path component ${JSON.stringify(candidate)} must not be a symbolic link.`);
+    }
+  }
+}
+
+export function prepareSecureDatabasePath(databasePath) {
+  if (typeof databasePath !== 'string' || databasePath.length === 0 || !isAbsolute(databasePath)) {
+    throw new ValidationError('databasePath must be a non-empty absolute filesystem path.');
+  }
+  const resolvedPath = resolve(databasePath);
+  const stateDirectory = dirname(resolvedPath);
+  if (stateDirectory === resolvedPath) {
+    throw new StorageSecurityError('databasePath must name a file inside a private state directory.');
+  }
+
+  assertNoSymlinkComponents(stateDirectory);
+  mkdirSync(stateDirectory, { recursive: true, mode: 0o700 });
+  assertNoSymlinkComponents(stateDirectory);
+
+  const directoryStat = lstatSync(stateDirectory);
+  if (!directoryStat.isDirectory()) {
+    throw new StorageSecurityError('The database parent must be a directory.');
+  }
+  assertOwned(directoryStat, 'The database state directory');
+  assertPrivateMode(directoryStat, 'The database state directory');
+
+  if (realpathSync(stateDirectory) !== stateDirectory) {
+    throw new StorageSecurityError('The database state directory must resolve without indirection.');
+  }
+
+  const noFollow = constants.O_NOFOLLOW ?? 0;
+  const existingDatabase = lstatIfPresent(resolvedPath);
+  if (!existingDatabase) {
+    try {
+      const descriptor = openSync(
+        resolvedPath,
+        constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | noFollow,
+        0o600
+      );
+      closeSync(descriptor);
+      chmodSync(resolvedPath, 0o600);
+    } catch (error) {
+      throw new StorageSecurityError('The database file could not be created without following links.', { cause: error });
+    }
+  } else {
+    assertSecureDatabaseFile(resolvedPath);
+    try {
+      const descriptor = openSync(resolvedPath, constants.O_RDWR | noFollow);
+      closeSync(descriptor);
+    } catch (error) {
+      throw new StorageSecurityError('The database file could not be opened without following links.', { cause: error });
+    }
+  }
+
+  assertSecureDatabaseFile(resolvedPath);
+  return resolvedPath;
+}
+
+export function assertSecureDatabaseFile(databasePath) {
+  assertNoSymlinkComponents(databasePath);
+  const stat = lstatSync(databasePath);
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw new StorageSecurityError('The database path must be a regular file, not a link or device.');
+  }
+  if (stat.nlink !== 1) {
+    throw new StorageSecurityError('The database file must not have additional hard links.');
+  }
+  assertOwned(stat, 'The database file');
+  assertPrivateMode(stat, 'The database file');
+  if (realpathSync(databasePath) !== databasePath) {
+    throw new StorageSecurityError('The database file must resolve without indirection.');
+  }
+}