synomem 0.1.0

package/SECURITY.md

@@ -0,0 +1,117 @@
+# Security policy
+
+## Supported versions and reporting
+
+Synomem is pre-release. Security fixes target the latest release and `main`. Report vulnerabilities
+through GitHub private vulnerability reporting for `Coaden/synomem`; do not open a public issue with
+exploit details, secrets, or private record data.
+
+## Trust model
+
+Synomem is a local audit-friendly record, not a tamper-proof ledger.
+
+- The local filesystem owner can alter the database, configuration, binaries, and projections.
+- Actor-bound MCP processes prevent ordinary callers from selecting another actor per tool call;
+  they do not cryptographically prove who launched the process.
+- The CLI intentionally permits a local human to choose an actor within the local-owner boundary.
+- MCP clients can invoke mutations available to the configured actor and are trusted local software.
+- Visibility policies constrain application behavior, not the filesystem owner.
+
+## Authorization model
+
+- Humans have local administrative authority.
+- Actor principals are the `(kind, id)` pair. A system or agent does not inherit another kind's
+  author access merely because its textual ID matches.
+- Agents may acknowledge only their own kudos and change only memo state addressed to them.
+- Agents may create and revise only their own notes.
+- Todo creators and assignees may change a todo; cross-agent assignment is configurable.
+- System actors are automation identities with no implicit agent or administrative authority.
+- Administrative MCP tools are disabled by default.
+
+`private` records remain visible to their direct participants. `workspace` records are visible to
+authorized actors in the local workspace. `public` means eligible for public export; it does not
+automatically publish anything.
+
+## Filesystem and SQLite
+
+- IDs reject traversal syntax, separators, controls, and reserved names.
+- Existing symlink components are rejected, and all derived paths stay under the configured home.
+- Cleanup removes only regular files recorded in the generated-files manifest.
+- Database, WAL, shared-memory, configuration, projection, export, and backup files are restricted to
+  the local user where POSIX modes are available.
+- WAL, foreign keys, full synchronization, bounded busy waits, and transactions reduce corruption
+  and concurrency risks.
+- Database triggers reject event updates and deletes. Lifecycle changes append events.
+- Backups use SQLite `VACUUM INTO`; never copy a live database naively.
+- Never use Git, Dropbox, generic network storage, or file-copy synchronization as a multi-writer
+  protocol for the live database.
+
+## Sensitive content
+
+Synomem never captures tool output automatically. Do not record:
+
+- tokens, passwords, cookies, private keys, authentication headers, or environment values;
+- raw sensitive tool arguments or outputs;
+- private file contents or whole chat transcripts;
+- sensitive URLs or query strings;
+- personal information unnecessary for the durable purpose.
+
+Evidence is descriptive metadata such as a safe task reference, relative file path, commit, URL, or
+sanitized tool description. Memos, notes, and todos often contain operational detail, so use the
+least content necessary. Review every export before sharing it.
+
+## Malformed and future data
+
+Canonical payloads are validated on read. Diagnostics identify malformed or unsupported rows by
+storage ID. Writes and full rebuilds fail closed when installed code cannot interpret the complete
+event stream. Raw JSON and JSONL export remains available for recovery.
+
+Read-only clients never migrate databases. Newer database versions fail before queries interpret
+their schema. Use `synomem backup` before any migration that cannot be safely reversed.
+
+## Nonrepudiation and hosted operation
+
+Append-only application behavior makes ordinary changes explicit, but an unsigned database owned by
+the local user can be rewritten. Do not describe Synomem as cryptographically tamper-proof or legally
+nonrepudiable.
+
+The local data plane and stdio MCP server expose no inbound network listener or hosted trust
+boundary. `synomem auth login` temporarily opens an exact loopback OAuth callback and closes it when
+the flow finishes. A hosted service requires server-side authentication, authorization, workspace
+isolation, transport security, conflict handling, availability controls, audit policy, and explicit
+migration. Client-side checks alone are insufficient.
+
+The experimental remote client accepts only HTTPS origins, with an explicit loopback HTTP exception
+for development. It does not follow redirects, bounds response bodies, keeps credentials out of
+configuration and request bodies, and never sends its expected actor as authority. The future
+server must derive actor and workspace authority from a validated audience-bound credential; these
+client checks are not a substitute for server-side authorization.
+
+Backend configuration may contain a remote service origin and workspace identifier, but never an
+access token, refresh token, password, or private key. The SQLite-backed client fails closed when it
+encounters a remote backend and does so before creating or opening a database. This prevents a
+misconfigured remote workspace from silently diverging into local state.
+
+Interactive CLI credentials are stored in macOS Keychain or Linux Secret Service and keyed to the
+service, workspace, and stable actor pair. The macOS helper receives secret JSON through stdin
+rather than command-line arguments. OAuth login requires PKCE S256, validates callback state, binds
+the token request to the discovered resource, refuses non-HTTPS authorization/token endpoints, and
+verifies the returned credential against the configured actor before retaining it.
+
+The local import client snapshots SQLite with `VACUUM INTO`, validates bounded event/profile counts
+and a whole-bundle checksum, and requires separate preview and confirmation commands. The remote
+service—not this package—is responsible for administrative authorization, signed-plan validation,
+empty-target enforcement, and atomic ingestion.
+
+## Skill installer
+
+No install hook changes agent configuration. `synomem skill install` and `uninstall` are explicit and
+dry-run unless `--yes` is supplied. They recognize verified Claude Code, Codex, Hermes, OpenClaw,
+Cursor, and local Grok layouts; honor documented runtime-home overrides; never create a missing
+runtime home; constrain changes to `skills/synomem`; and refuse unowned conflicts without `--force`.
+Copied skill files preserve their packaged permission modes, including execute bits needed by helper
+scripts. Skill bundles are operational instructions rather than confidential Synomem data; the
+`0600`/`0700` data-file policy above does not apply to them. The ownership stamp is written `0600`
+where POSIX modes are available.
+The installer prints MCP setup commands where the harness has a verified noninteractive command but
+does not execute them or rewrite shared MCP configuration.

package/dist/backend.d.ts

@@ -0,0 +1,9 @@
+import { SynomemClient } from './client.js';
+import { RemoteSynomemService } from './remote.js';
+import type { SynomemServiceFactory } from './service.js';
+import type { SynomemBackendConfig, SynomemClientOptions, SynomemConfig } from './types.js';
+export declare function readSynomemConfig(explicitHome?: string, env?: NodeJS.ProcessEnv): SynomemConfig | undefined;
+export declare function writeSynomemBackend(backend: SynomemBackendConfig, explicitHome?: string): SynomemConfig;
+export declare function createConfiguredService(options?: SynomemClientOptions, env?: NodeJS.ProcessEnv): SynomemClient | RemoteSynomemService;
+export declare const configuredServiceFactory: SynomemServiceFactory;
+//# sourceMappingURL=backend.d.ts.map

package/dist/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAS5C,OAAO,EAAiC,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGlF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,EAEV,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACd,MAAM,YAAY,CAAC;AAYpB,wBAAgB,iBAAiB,CAC/B,YAAY,CAAC,EAAE,MAAM,EACrB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,aAAa,GAAG,SAAS,CAQ3B;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,oBAAoB,EAC7B,YAAY,CAAC,EAAE,MAAM,GACpB,aAAa,CAef;AAED,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,oBAAyB,EAClC,GAAG,GAAE,MAAM,CAAC,UAAwB,wCAmBrC;AAED,eAAO,MAAM,wBAAwB,EAAE,qBACL,CAAC"}

package/dist/backend.js

@@ -0,0 +1,60 @@
+import { chmodSync, existsSync, lstatSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { ulid } from 'ulid';
+import { SynomemClient } from './client.js';
+import { defaultConfig, mergeConfig, resolveHome } from './config.js';
+import { SynomemError } from './errors.js';
+import { assertNoSymlinkEscape, atomicWriteFile, ensureDirectory, readJsonFile, } from './fs-utils.js';
+import { environmentCredentialProvider, RemoteSynomemService } from './remote.js';
+import { credentialReference, OsCredentialStore } from './credentials.js';
+import { StoredCredentialProvider } from './oauth.js';
+function configLocation(explicitHome) {
+    const home = resolveHome(explicitHome);
+    const storageDirectory = join(home, 'synomem');
+    return { home, storageDirectory, configPath: join(storageDirectory, 'config.json') };
+}
+export function readSynomemConfig(explicitHome, env = process.env) {
+    const { home, storageDirectory, configPath } = configLocation(explicitHome);
+    if (!existsSync(configPath))
+        return undefined;
+    if (!existsSync(home) || lstatSync(home).isSymbolicLink()) {
+        throw new SynomemError('UNSAFE_PATH', 'The configured Synomem home is unsafe.');
+    }
+    assertNoSymlinkEscape(home, storageDirectory);
+    return mergeConfig(readJsonFile(configPath), undefined, env);
+}
+export function writeSynomemBackend(backend, explicitHome) {
+    const { home, storageDirectory, configPath } = configLocation(explicitHome);
+    if (!existsSync(home))
+        mkdirSync(home, { recursive: true, mode: 0o700 });
+    if (lstatSync(home).isSymbolicLink()) {
+        throw new SynomemError('UNSAFE_PATH', 'The configured Synomem home cannot be a symbolic link.');
+    }
+    ensureDirectory(storageDirectory);
+    assertNoSymlinkEscape(home, storageDirectory);
+    chmodSync(storageDirectory, 0o700);
+    const existing = existsSync(configPath)
+        ? mergeConfig(readJsonFile(configPath), undefined, {})
+        : { ...defaultConfig, workspaceId: ulid() };
+    const config = mergeConfig({ ...existing, backend }, undefined, {});
+    atomicWriteFile(configPath, `${JSON.stringify(config, null, 2)}\n`);
+    return config;
+}
+export function createConfiguredService(options = {}, env = process.env) {
+    const persisted = readSynomemConfig(options.home, env);
+    const backend = options.config?.backend ?? persisted?.backend ?? defaultConfig.backend;
+    if (backend.kind === 'local')
+        return new SynomemClient(options);
+    const expectedActor = options.actor ?? { kind: 'system', id: 'workspace' };
+    return new RemoteSynomemService({
+        baseUrl: backend.baseUrl,
+        workspaceId: backend.workspaceId,
+        expectedActor,
+        credentialProvider: env.SYNOMEM_ACCESS_TOKEN
+            ? environmentCredentialProvider(env)
+            : new StoredCredentialProvider(credentialReference(backend.baseUrl, backend.workspaceId, expectedActor), new OsCredentialStore(), env),
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+}
+export const configuredServiceFactory = (options) => createConfiguredService(options);
+//# sourceMappingURL=backend.js.map

package/dist/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { type CredentialStore } from './credentials.js';
+import { type OAuthLoginOptions } from './oauth.js';
+import { type ImportBundle, type ImportPreview, type ImportResult } from './import.js';
+import type { ActorIdentity } from './types.js';
+import type { SynomemServiceFactory } from './service.js';
+export interface CliIo {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+}
+export interface CliDependencies {
+    credentialStore?: CredentialStore;
+    oauthLogin?: (options: OAuthLoginOptions) => Promise<void>;
+    env?: NodeJS.ProcessEnv;
+    verifyRemoteCredential?: (options: {
+        baseUrl: string;
+        workspaceId: string;
+        actor: ActorIdentity;
+        reference: string;
+        credentialStore: CredentialStore;
+    }) => Promise<void>;
+    createImportBundle?: (home: string) => Promise<ImportBundle>;
+    remoteImport?: (options: {
+        baseUrl: string;
+        workspaceId: string;
+        actor: ActorIdentity;
+        bundle: ImportBundle;
+        planId?: string;
+    }) => Promise<ImportPreview | ImportResult>;
+}
+export declare function createCli(io?: CliIo, serviceFactory?: SynomemServiceFactory, dependencies?: CliDependencies): Command;
+export declare function runCli(argv?: string[], io?: CliIo, serviceFactory?: SynomemServiceFactory, dependencies?: CliDependencies): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAKA,OAAO,EAAE,OAAO,EAA0B,MAAM,WAAW,CAAC;AAE5D,OAAO,EAA0C,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAIhG,OAAO,EAA4C,KAAK,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE9F,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AASrB,OAAO,KAAK,EACV,aAAa,EAQd,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAkB,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1E,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE;QACjC,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,aAAa,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe,EAAE,eAAe,CAAC;KAClC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpB,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAC7D,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE;QACvB,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,aAAa,CAAC;QACrB,MAAM,EAAE,YAAY,CAAC;QACrB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,KAAK,OAAO,CAAC,aAAa,GAAG,YAAY,CAAC,CAAC;CAC7C;AAkMD,wBAAgB,SAAS,CACvB,EAAE,GAAE,KAAiB,EACrB,cAAc,GAAE,qBAAgD,EAChE,YAAY,GAAE,eAAoB,GACjC,OAAO,CA+yCT;AAED,wBAAsB,MAAM,CAC1B,IAAI,WAAe,EACnB,EAAE,GAAE,KAAiB,EACrB,cAAc,GAAE,qBAAgD,EAChE,YAAY,GAAE,eAAoB,GACjC,OAAO,CAAC,MAAM,CAAC,CAqBjB"}