synomem 0.1.0

package/src/config.ts

@@ -0,0 +1,170 @@
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { SynomemError } from './errors.js';
+import type { SynomemConfig, SynomemConfigOverrides } from './types.js';
+
+export const defaultConfig: SynomemConfig = {
+  schemaVersion: 3,
+  backend: { kind: 'local' },
+  workspaceId: 'workspace',
+  defaultVisibility: 'workspace',
+  allowSelfAwards: false,
+  allowCrossAgentTodos: true,
+  allowAgentCreationViaMcp: false,
+  allowRebuildViaMcp: false,
+  includePrivateInStats: false,
+  projection: {
+    writeWinsMarkdown: true,
+    writeMemoryMarkdown: true,
+    writeTodosMarkdown: true,
+    writeInboxEntries: true,
+  },
+};
+
+const backendSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('local') }),
+  z.object({
+    kind: z.literal('remote'),
+    baseUrl: z.url().refine(
+      (value) => {
+        try {
+          const parsed = new URL(value);
+          const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(parsed.hostname);
+          return (
+            (parsed.protocol === 'https:' || (parsed.protocol === 'http:' && loopback)) &&
+            !parsed.username &&
+            !parsed.password &&
+            !parsed.search &&
+            !parsed.hash &&
+            parsed.pathname === '/'
+          );
+        } catch {
+          return false;
+        }
+      },
+      { message: 'Remote baseUrl must be an HTTPS origin (loopback HTTP is allowed).' },
+    ),
+    workspaceId: z.string().trim().min(1).max(100),
+  }),
+]);
+
+const policySchema = z.object({
+  workspaceId: z.string().trim().min(1).max(100),
+  defaultVisibility: z.enum(['private', 'workspace', 'public']),
+  allowSelfAwards: z.boolean(),
+  allowCrossAgentTodos: z.boolean(),
+  allowAgentCreationViaMcp: z.boolean(),
+  allowRebuildViaMcp: z.boolean(),
+  includePrivateInStats: z.boolean(),
+  projection: z.object({
+    writeWinsMarkdown: z.boolean(),
+    writeMemoryMarkdown: z.boolean(),
+    writeTodosMarkdown: z.boolean(),
+    writeInboxEntries: z.boolean(),
+  }),
+});
+
+const legacyConfigSchema = policySchema.extend({ schemaVersion: z.literal(2) });
+
+export const configSchema = policySchema.extend({
+  schemaVersion: z.literal(3),
+  backend: backendSchema,
+});
+
+export function resolveHome(explicitHome?: string): string {
+  const candidate = explicitHome ?? process.env.SYNOMEM_HOME ?? resolve(homedir(), '.agents');
+  if (candidate.includes('\0')) throw new SynomemError('UNSAFE_PATH', 'Storage home contains NUL.');
+  return resolve(candidate);
+}
+
+export function mergeConfig(
+  fileConfig: unknown,
+  explicit?: SynomemConfigOverrides,
+  env: NodeJS.ProcessEnv = process.env,
+): SynomemConfig {
+  const parsedFile = parseFileConfig(fileConfig);
+  if (!parsedFile.success) {
+    throw new SynomemError('CONFIG_INVALID', 'Synomem configuration file is invalid.', {
+      issues: parsedFile.error.issues,
+    });
+  }
+  const fromFile = parsedFile.data;
+  const fromEnvironment = environmentConfig(env);
+  const merged: SynomemConfig = {
+    ...fromFile,
+    ...fromEnvironment,
+    ...explicit,
+    projection: {
+      ...fromFile.projection,
+      ...fromEnvironment.projection,
+      ...explicit?.projection,
+    },
+    schemaVersion: 3,
+  };
+  const result = configSchema.safeParse(merged);
+  if (!result.success) {
+    throw new SynomemError('CONFIG_INVALID', 'Synomem configuration is invalid.', {
+      issues: result.error.issues,
+    });
+  }
+  return result.data;
+}
+
+function parseFileConfig(fileConfig: unknown) {
+  if (fileConfig === undefined) return { success: true as const, data: defaultConfig };
+  const current = configSchema.safeParse(fileConfig);
+  if (current.success) return current;
+  const legacy = legacyConfigSchema.safeParse(fileConfig);
+  if (legacy.success) {
+    return {
+      success: true as const,
+      data: { ...legacy.data, schemaVersion: 3 as const, backend: { kind: 'local' as const } },
+    };
+  }
+  return current;
+}
+
+function optionalBoolean(env: NodeJS.ProcessEnv, name: string): boolean | undefined {
+  const value = env[name];
+  if (value === undefined) return undefined;
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  throw new SynomemError('CONFIG_INVALID', `${name} must be true or false.`);
+}
+
+function environmentConfig(env: NodeJS.ProcessEnv): SynomemConfigOverrides {
+  const visibility = env.SYNOMEM_DEFAULT_VISIBILITY;
+  if (visibility && !['private', 'workspace', 'public'].includes(visibility)) {
+    throw new SynomemError(
+      'CONFIG_INVALID',
+      'SYNOMEM_DEFAULT_VISIBILITY must be private, workspace, or public.',
+    );
+  }
+
+  const writeWinsMarkdown = optionalBoolean(env, 'SYNOMEM_WRITE_WINS_MARKDOWN');
+  const writeMemoryMarkdown = optionalBoolean(env, 'SYNOMEM_WRITE_MEMORY_MARKDOWN');
+  const writeTodosMarkdown = optionalBoolean(env, 'SYNOMEM_WRITE_TODOS_MARKDOWN');
+  const writeInboxEntries = optionalBoolean(env, 'SYNOMEM_WRITE_INBOX_ENTRIES');
+  const allowSelfAwards = optionalBoolean(env, 'SYNOMEM_ALLOW_SELF_AWARDS');
+  const allowCrossAgentTodos = optionalBoolean(env, 'SYNOMEM_ALLOW_CROSS_AGENT_TODOS');
+  const allowAgentCreationViaMcp = optionalBoolean(env, 'SYNOMEM_ALLOW_AGENT_CREATION_VIA_MCP');
+  const allowRebuildViaMcp = optionalBoolean(env, 'SYNOMEM_ALLOW_REBUILD_VIA_MCP');
+  const includePrivateInStats = optionalBoolean(env, 'SYNOMEM_INCLUDE_PRIVATE_IN_STATS');
+  const projection = {
+    ...(writeWinsMarkdown !== undefined ? { writeWinsMarkdown } : {}),
+    ...(writeMemoryMarkdown !== undefined ? { writeMemoryMarkdown } : {}),
+    ...(writeTodosMarkdown !== undefined ? { writeTodosMarkdown } : {}),
+    ...(writeInboxEntries !== undefined ? { writeInboxEntries } : {}),
+  };
+
+  return {
+    ...(visibility ? { defaultVisibility: visibility as SynomemConfig['defaultVisibility'] } : {}),
+    ...(allowSelfAwards !== undefined ? { allowSelfAwards } : {}),
+    ...(allowCrossAgentTodos !== undefined ? { allowCrossAgentTodos } : {}),
+    ...(allowAgentCreationViaMcp !== undefined ? { allowAgentCreationViaMcp } : {}),
+    ...(allowRebuildViaMcp !== undefined ? { allowRebuildViaMcp } : {}),
+    ...(includePrivateInStats !== undefined ? { includePrivateInStats } : {}),
+    ...(Object.keys(projection).length ? { projection } : {}),
+  };
+}

package/src/credentials.ts

@@ -0,0 +1,194 @@
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { SynomemError } from './errors.js';
+import type { ActorIdentity } from './types.js';
+
+const serviceName = 'ai.synomem.credentials';
+const maximumOutputBytes = 128 * 1024;
+
+export interface StoredOAuthCredential {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: number;
+  tokenEndpoint: string;
+  clientId: string;
+  resource: string;
+  scope: string;
+}
+
+export interface CredentialStore {
+  get(reference: string): Promise<StoredOAuthCredential | undefined>;
+  set(reference: string, credential: StoredOAuthCredential): Promise<void>;
+  delete(reference: string): Promise<boolean>;
+}
+
+export function credentialReference(
+  baseUrl: string,
+  workspaceId: string,
+  actor: ActorIdentity,
+): string {
+  return createHash('sha256')
+    .update(
+      JSON.stringify({
+        baseUrl: new URL(baseUrl).origin,
+        workspaceId,
+        actor: { kind: actor.kind, id: actor.id },
+      }),
+    )
+    .digest('base64url');
+}
+
+interface CommandResult {
+  stdout: string;
+  stderr: string;
+  code: number;
+}
+
+export type CredentialCommandRunner = (
+  executable: string,
+  arguments_: string[],
+  input?: string,
+) => Promise<CommandResult>;
+
+async function command(
+  executable: string,
+  arguments_: string[],
+  input?: string,
+): Promise<CommandResult> {
+  return await new Promise((resolve, reject) => {
+    const child = spawn(executable, arguments_, { stdio: ['pipe', 'pipe', 'pipe'] });
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    let bytes = 0;
+    const collect = (target: Buffer[]) => (chunk: Buffer) => {
+      bytes += chunk.byteLength;
+      if (bytes > maximumOutputBytes) {
+        child.kill();
+        reject(new SynomemError('INTERNAL_ERROR', 'Credential helper output was too large.'));
+        return;
+      }
+      target.push(chunk);
+    };
+    child.stdout.on('data', collect(stdout));
+    child.stderr.on('data', collect(stderr));
+    child.once('error', reject);
+    child.once('close', (code) =>
+      resolve({
+        stdout: Buffer.concat(stdout).toString('utf8'),
+        stderr: Buffer.concat(stderr).toString('utf8'),
+        code: code ?? 1,
+      }),
+    );
+    child.stdin.end(input);
+  });
+}
+
+function parseCredential(value: string): StoredOAuthCredential {
+  try {
+    const parsed = JSON.parse(value) as Partial<StoredOAuthCredential>;
+    if (
+      typeof parsed.accessToken !== 'string' ||
+      typeof parsed.tokenEndpoint !== 'string' ||
+      typeof parsed.clientId !== 'string' ||
+      typeof parsed.resource !== 'string' ||
+      typeof parsed.scope !== 'string'
+    ) {
+      throw new Error();
+    }
+    return parsed as StoredOAuthCredential;
+  } catch {
+    throw new SynomemError('AUTH_REQUIRED', 'Stored Synomem credentials are malformed.');
+  }
+}
+
+export class OsCredentialStore implements CredentialStore {
+  private readonly platform: NodeJS.Platform;
+  private readonly run: CredentialCommandRunner;
+
+  constructor(options: { platform?: NodeJS.Platform; run?: CredentialCommandRunner } = {}) {
+    this.platform = options.platform ?? process.platform;
+    this.run = options.run ?? command;
+  }
+
+  async get(reference: string): Promise<StoredOAuthCredential | undefined> {
+    const result =
+      this.platform === 'darwin'
+        ? await this.run('/usr/bin/security', [
+            'find-generic-password',
+            '-a',
+            reference,
+            '-s',
+            serviceName,
+            '-w',
+          ])
+        : this.platform === 'linux'
+          ? await this.run('secret-tool', ['lookup', 'service', serviceName, 'account', reference])
+          : this.unsupported();
+    if (result.code !== 0) return undefined;
+    return parseCredential(result.stdout.trim());
+  }
+
+  async set(reference: string, credential: StoredOAuthCredential): Promise<void> {
+    const serialized = JSON.stringify(credential);
+    const result =
+      this.platform === 'darwin'
+        ? await this.run(
+            '/usr/bin/security',
+            [
+              'add-generic-password',
+              '-a',
+              reference,
+              '-s',
+              serviceName,
+              '-l',
+              'Synomem OAuth credential',
+              '-U',
+              '-w',
+            ],
+            `${serialized}\n`,
+          )
+        : this.platform === 'linux'
+          ? await this.run(
+              'secret-tool',
+              [
+                'store',
+                '--label=Synomem OAuth credential',
+                'service',
+                serviceName,
+                'account',
+                reference,
+              ],
+              serialized,
+            )
+          : this.unsupported();
+    if (result.code !== 0) {
+      throw new SynomemError(
+        'AUTH_REQUIRED',
+        'The operating-system credential store rejected the credential.',
+      );
+    }
+  }
+
+  async delete(reference: string): Promise<boolean> {
+    const result =
+      this.platform === 'darwin'
+        ? await this.run('/usr/bin/security', [
+            'delete-generic-password',
+            '-a',
+            reference,
+            '-s',
+            serviceName,
+          ])
+        : this.platform === 'linux'
+          ? await this.run('secret-tool', ['clear', 'service', serviceName, 'account', reference])
+          : this.unsupported();
+    return result.code === 0;
+  }
+
+  private unsupported(): never {
+    throw new SynomemError(
+      'CONFIG_INVALID',
+      'Interactive credential storage is currently supported on macOS and Linux with secret-tool.',
+    );
+  }
+}

package/src/errors.ts

@@ -0,0 +1,64 @@
+import { ZodError } from 'zod';
+
+export const errorCodes = [
+  'INVALID_INPUT',
+  'INVALID_AGENT_ID',
+  'INVALID_EVENT',
+  'UNSUPPORTED_EVENT',
+  'AGENT_NOT_FOUND',
+  'AGENT_EXISTS',
+  'ALIAS_CONFLICT',
+  'KUDOS_NOT_FOUND',
+  'ITEM_NOT_FOUND',
+  'MEMO_NOT_FOUND',
+  'NOTE_NOT_FOUND',
+  'TODO_NOT_FOUND',
+  'REVISION_CONFLICT',
+  'IDEMPOTENCY_CONFLICT',
+  'MUTATION_FORBIDDEN',
+  'SELF_AWARD_FORBIDDEN',
+  'ACKNOWLEDGMENT_FORBIDDEN',
+  'REVOCATION_FORBIDDEN',
+  'READ_ONLY',
+  'DATABASE_BUSY',
+  'DATABASE_CORRUPT',
+  'UNSUPPORTED_SCHEMA',
+  'UNSAFE_PATH',
+  'POLICY_FORBIDDEN',
+  'CONFIG_INVALID',
+  'AUTH_REQUIRED',
+  'AUTH_FORBIDDEN',
+  'REMOTE_UNAVAILABLE',
+  'REMOTE_PROTOCOL',
+  'RATE_LIMITED',
+  'INTERNAL_ERROR',
+] as const;
+
+export type SynomemErrorCode = (typeof errorCodes)[number];
+
+export class SynomemError extends Error {
+  readonly code: SynomemErrorCode;
+  readonly details?: Record<string, unknown>;
+
+  constructor(code: SynomemErrorCode, message: string, details?: Record<string, unknown>) {
+    super(message);
+    this.name = 'SynomemError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export function asSynomemError(error: unknown): SynomemError {
+  if (error instanceof SynomemError) return error;
+  if (error instanceof ZodError) {
+    return new SynomemError('INVALID_INPUT', 'Input validation failed.', { issues: error.issues });
+  }
+  const message = error instanceof Error ? error.message : 'Unexpected Synomem error';
+  if (/SQLITE_BUSY|database is locked/i.test(message)) {
+    return new SynomemError('DATABASE_BUSY', 'The Synomem database is busy; retry shortly.');
+  }
+  if (/malformed|not a database|database disk image/i.test(message)) {
+    return new SynomemError('DATABASE_CORRUPT', 'The Synomem database failed an integrity check.');
+  }
+  return new SynomemError('INTERNAL_ERROR', message);
+}

package/src/fs-utils.ts

@@ -0,0 +1,85 @@
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, relative, resolve, sep } from 'node:path';
+import { SynomemError } from './errors.js';
+
+export function ensureDirectory(path: string): void {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+}
+
+export function assertNoSymlinkEscape(home: string, target: string): void {
+  const root = realpathSync(home);
+  const lexicalRoot = resolve(home);
+  const resolved = resolve(target);
+  const rel = relative(lexicalRoot, resolved);
+  if (rel === '..' || rel.startsWith(`..${sep}`) || resolve(lexicalRoot, rel) !== resolved) {
+    throw new SynomemError('UNSAFE_PATH', 'Path escapes the configured Synomem home.');
+  }
+
+  let current = root;
+  for (const part of rel.split(sep).filter(Boolean)) {
+    current = resolve(current, part);
+    if (existsSync(current) && lstatSync(current).isSymbolicLink()) {
+      throw new SynomemError(
+        'UNSAFE_PATH',
+        `Refusing to traverse symbolic link: ${relative(root, current)}`,
+      );
+    }
+  }
+}
+
+export function atomicWriteFile(path: string, content: string, mode = 0o600): void {
+  atomicWrite(path, content, mode, true);
+}
+
+/** Atomically replace rebuildable derived data without forcing it to stable storage. */
+export function atomicWriteDerivedFile(path: string, content: string, mode = 0o600): void {
+  atomicWrite(path, content, mode, false);
+}
+
+function atomicWrite(path: string, content: string, mode: number, durable: boolean): void {
+  ensureDirectory(dirname(path));
+  const temporary = resolve(
+    dirname(path),
+    `.${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.tmp`,
+  );
+  let descriptor: number | undefined;
+  try {
+    descriptor = openSync(temporary, 'wx', mode);
+    writeFileSync(descriptor, content, 'utf8');
+    if (durable) fsyncSync(descriptor);
+    closeSync(descriptor);
+    descriptor = undefined;
+    renameSync(temporary, path);
+    if (durable)
+      try {
+        const directoryDescriptor = openSync(dirname(path), 'r');
+        try {
+          fsyncSync(directoryDescriptor);
+        } finally {
+          closeSync(directoryDescriptor);
+        }
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (!['EINVAL', 'EISDIR', 'EPERM'].includes(code ?? '')) throw error;
+      }
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+    if (existsSync(temporary)) unlinkSync(temporary);
+  }
+}
+
+export function readJsonFile(path: string): unknown {
+  return JSON.parse(readFileSync(path, 'utf8')) as unknown;
+}