@nimbus-sh/core 0.1.0

package/src/vfs/symlink-registry.ts

@@ -0,0 +1,172 @@
+/**
+ * symlink-registry.ts — virtual symlink table backed by a special
+ * JSON file in the SqliteVFS.
+ *
+ * Native symlinks now live in SqliteVFS. This registry remains the durable
+ * compatibility path for symlinks created by older sessions.
+ *
+ * Storage: `/.nimbus-symlinks.json` with shape `{ [linkPath]: target }`.
+ * The registry cache tracks the backing inode revision so direct durable
+ * writes cannot leave clone destination proofs on a stale view.
+ *
+ * Native inodes take precedence when both representations exist.
+ *
+ * Loop guard: `resolveSymlinkChain` follows at most 40 hops (matches
+ * POSIX SYMLOOP_MAX).
+ */
+
+import type { CredentialedVfs, SqliteVFS } from './sqlite-vfs.js';
+import { CRED_KERNEL } from '../runtime/os-contracts.js';
+import { normalizeVfsPath } from './path.js';
+
+export const LEGACY_SYMLINK_REGISTRY_PATH = '.nimbus-symlinks.json';
+
+export class SymlinkRegistry {
+  private vfs: SqliteVFS;
+  private view: CredentialedVfs;
+  private cache: Map<string, string> | null = null;
+  private cacheRevision = -1;
+
+  constructor(vfs: SqliteVFS) {
+    this.vfs = vfs;
+    this.view = vfs.as(CRED_KERNEL);
+  }
+
+  /** Lazy-load the registry and refresh it after direct backing-file writes. */
+  private load(): Map<string, string> {
+    const revision = this.vfs.revision(LEGACY_SYMLINK_REGISTRY_PATH);
+    if (this.cache && this.cacheRevision === revision) return this.cache;
+
+    const next = new Map<string, string>();
+    if (this.view.exists(LEGACY_SYMLINK_REGISTRY_PATH)) {
+      const raw = this.view.readFileString(LEGACY_SYMLINK_REGISTRY_PATH);
+      const parsed: unknown = JSON.parse(raw);
+      if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`[symlink-registry] invalid ${LEGACY_SYMLINK_REGISTRY_PATH}`);
+      }
+      for (const [link, target] of Object.entries(parsed)) {
+        if (typeof target !== 'string') {
+          throw new Error(`[symlink-registry] invalid target for ${link}`);
+        }
+        next.set(link, target);
+      }
+    }
+    this.cache = next;
+    this.cacheRevision = revision;
+    return next;
+  }
+
+  /** Persist a complete registry snapshot before publishing it to readers. */
+  private persist(next: Map<string, string>): void {
+    const obj: Record<string, string> = {};
+    for (const [k, v] of next) obj[k] = v;
+    const created = !this.view.exists(LEGACY_SYMLINK_REGISTRY_PATH);
+    this.view.writeFile(LEGACY_SYMLINK_REGISTRY_PATH, JSON.stringify(obj));
+    if (created) this.view.chown(LEGACY_SYMLINK_REGISTRY_PATH, 1000, 1000);
+    this.cache = next;
+    this.cacheRevision = this.vfs.revision(LEGACY_SYMLINK_REGISTRY_PATH);
+  }
+
+  /** Normalize a path to the VFS internal key convention. */
+  private norm(p: string): string {
+    return normalizeVfsPath(p);
+  }
+
+  /** Create or replace a symlink. Target is stored verbatim (can be
+   *  absolute or relative — interpretation happens at resolve time). */
+  set(linkPath: string, target: string): void {
+    this.vfs.assertMutationAllowed(linkPath);
+    this.vfs.assertMutationAllowed(LEGACY_SYMLINK_REGISTRY_PATH);
+    const next = new Map(this.load());
+    next.set(this.norm(linkPath), target);
+    this.persist(next);
+  }
+
+  /** Remove a symlink. Returns true if it existed. */
+  delete(linkPath: string): boolean {
+    const cache = this.load();
+    const normalized = this.norm(linkPath);
+    if (!cache.has(normalized)) return false;
+    this.vfs.assertMutationAllowed(normalized);
+    this.vfs.assertMutationAllowed(LEGACY_SYMLINK_REGISTRY_PATH);
+    const next = new Map(cache);
+    next.delete(normalized);
+    this.persist(next);
+    return true;
+  }
+
+  assertMutable(...paths: string[]): void {
+    for (const path of paths) this.vfs.assertMutationAllowed(path);
+    this.vfs.assertMutationAllowed(LEGACY_SYMLINK_REGISTRY_PATH);
+  }
+
+  /** Check if `path` is registered as a symlink (no chain resolution). */
+  isSymlink(path: string): boolean {
+    return this.load().has(this.norm(path));
+  }
+
+  /** Get the immediate target of a symlink. Returns null if not a symlink. */
+  readlink(path: string): string | null {
+    const v = this.load().get(this.norm(path));
+    return v === undefined ? null : v;
+  }
+
+  /**
+   * Follow a symlink chain until we hit a non-symlink (or run out of
+   * hops). Returns the resolved path (canonicalized to no-leading-slash).
+   * If the chain breaks (max-hops or missing target), returns the
+   * last-resolved path or null.
+   *
+   * `cwd` is used to resolve RELATIVE symlink targets (target without
+   * leading `/`). POSIX semantics: relative targets resolve from the
+   * symlink's directory, not the current cwd.
+   */
+  resolveChain(startPath: string): string | null {
+    let cur = this.norm(startPath);
+    for (let hops = 0; hops < 40; hops++) {
+      const target = this.load().get(cur);
+      if (target === undefined) return cur;  // not a symlink — done
+      if (target.startsWith('/')) {
+        cur = this.norm(target);
+      } else {
+        // Relative target: resolve from symlink's parent dir.
+        const parent = cur.includes('/') ? cur.substring(0, cur.lastIndexOf('/')) : '';
+        cur = normalizeVfsPath(`${parent}/${target}`);
+      }
+    }
+    // ELOOP
+    return null;
+  }
+
+  /** List all currently-registered symlinks (debugging / ls -la support). */
+  list(): { link: string; target: string }[] {
+    const out: { link: string; target: string }[] = [];
+    for (const [k, v] of this.load()) {
+      out.push({ link: k, target: v });
+    }
+    return out;
+  }
+
+  hasAtOrBelow(path: string): boolean {
+    const root = this.norm(path);
+    for (const link of this.load().keys()) {
+      if (link === root || link.startsWith(`${root}/`)) return true;
+    }
+    return false;
+  }
+}
+
+/**
+ * Return the session-wide registry for a VFS instance. The registry has an
+ * in-memory cache, so all runtime surfaces that share one SqliteVFS must also
+ * share the registry instance to avoid stale symlink reads.
+ */
+const registries = new WeakMap<SqliteVFS, SymlinkRegistry>();
+
+export function getSymlinkRegistry(vfs: SqliteVFS): SymlinkRegistry {
+  const existing = registries.get(vfs);
+  if (existing) return existing;
+  const registry = new SymlinkRegistry(vfs);
+  registries.set(vfs, registry);
+  return registry;
+}

package/src/workspace/nimbus-workspace.ts

@@ -0,0 +1,213 @@
+/**
+ * nimbus-workspace.ts — Nimbus as a component someone else can hold.
+ *
+ * A workspace is a durable filesystem plus a shell over it. It owns no
+ * transport, no session, no socket and no Durable Object: the host supplies
+ * SQLite and gets back `.fs` and `.exec`. That is what makes it embeddable in
+ * a Durable Object that is already busy powering something else, and what
+ * makes it runnable in a plain bun process over `bun:sqlite`.
+ *
+ * The composition here is not new. It is the one `session/init.ts` performs,
+ * lifted out of the session so there is one recipe rather than one per caller
+ * — five unit tests were already hand-rolling it, one of them reaching a
+ * private field to do so. The boot itself still belongs to `Sandbox.create`;
+ * this adds only what a durable, credentialed filesystem needs on top and
+ * nothing the sandbox already knows how to do.
+ */
+
+import { Sandbox } from '../substrate/lifo/sandbox/Sandbox.js';
+import { SandboxFsImpl } from '../substrate/lifo/sandbox/SandboxFs.js';
+import type { CommandResult, RunOptions, SandboxFs } from '../substrate/lifo/sandbox/types.js';
+import type { Kernel } from '../substrate/lifo/kernel/index.js';
+import type { Shell } from '../substrate/lifo/shell/Shell.js';
+import type { ITerminal } from '../substrate/lifo/terminal/ITerminal.js';
+import { SqliteVFS, SqliteVFSProvider } from '../vfs/sqlite-vfs.js';
+import { DEFAULT_MOUNT_POINTS, DEFAULT_PATH } from '../constants.js';
+import { CRED_KERNEL, CRED_SESSION_USER } from '../runtime/os-contracts.js';
+import type { SqlDatabase, TransactionHost } from '../runtime/os-contracts.js';
+import { registerUnixCommands } from '../shell/unix-commands.js';
+import { installPathExecResolver } from '../shell/exec-dispatch.js';
+
+/** Pids are `generation * PID_GEN_STRIDE + seq`; mirrors process-table.ts. */
+const PID_GEN_STRIDE = 1_000_000;
+
+export interface NimbusWorkspaceOptions {
+  /** The host's SQLite. In a Durable Object: `ctx.storage.sql`. */
+  readonly sql: SqlDatabase;
+  /**
+   * Carries `transactionSync`. In a Durable Object: `ctx`.
+   *
+   * Every atomic write in the filesystem rests on this being a real
+   * transaction. An implementation that merely calls the callback converts
+   * each one into a torn write that reports success.
+   */
+  readonly transactions?: TransactionHost;
+  /**
+   * Process-id generation. The workspace revokes every append capability at
+   * or below `generation * 1_000_000` before serving anything, so a value
+   * that repeats across restarts hands a dead process live write authority.
+   * Hosts that persist must supply a counter that never repeats.
+   */
+  readonly generation?: number;
+  /** Top-level directories backed by `sql`. Defaults to DEFAULT_MOUNT_POINTS. */
+  readonly mounts?: readonly string[];
+  readonly env?: Record<string, string>;
+  readonly cwd?: string;
+  /** Absent means headless: `.exec` captures output and nothing is drawn. */
+  readonly terminal?: ITerminal;
+}
+
+/**
+ * A durable filesystem and a shell over it.
+ *
+ * Created with {@link NimbusWorkspace.create} rather than `new` because the
+ * boot it delegates to sources `/etc/profile`, which is genuinely async. A
+ * Durable Object constructor cannot await, so a host constructs the workspace
+ * in its first request rather than in its constructor.
+ */
+export class NimbusWorkspace {
+  /**
+   * Credentialed and mount-aware. Acts as the session user, never as the
+   * kernel: a pid-less caller must not gain more authority than the shell it
+   * writes files for (see CRED_SESSION_USER in os-contracts.ts).
+   */
+  readonly fs: SandboxFs;
+  /** The raw durable filesystem, for hosts that need uid-aware operations. */
+  readonly vfs: SqliteVFS;
+  readonly kernel: Kernel;
+  readonly shell: Shell;
+
+  private constructor(
+    private readonly sandbox: Sandbox,
+    vfs: SqliteVFS,
+    private readonly sql: SqlDatabase,
+  ) {
+    this.vfs = vfs;
+    this.kernel = sandbox.kernel;
+    this.shell = sandbox.shell;
+    // NOT `sandbox.fs`, which wraps the raw kernel VFS. The mount is
+    // kernel-credentialed because the shell re-credentials per command; a host
+    // calling `.fs` has no process behind it and must not inherit that.
+    this.fs = new SandboxFsImpl(
+      sandbox.kernel.vfs.as(CRED_SESSION_USER),
+      () => sandbox.shell.getCwd(),
+    );
+  }
+
+  static async create(options: NimbusWorkspaceOptions): Promise<NimbusWorkspace> {
+    const vfs = new SqliteVFS(options.sql, options.transactions);
+    vfs.revokeAppendWritersThrough((options.generation ?? 1) * PID_GEN_STRIDE);
+
+    const mounts = options.mounts ?? DEFAULT_MOUNT_POINTS;
+    seedBaseFilesystem(vfs, mounts);
+
+    const sandbox = await Sandbox.create({
+      env: options.env,
+      cwd: options.cwd,
+      terminal: options.terminal,
+      providerMounts: mounts.map((mount) => ({
+        virtualPath: '/' + mount,
+        provider: new SqliteVFSProvider(vfs, mount),
+      })),
+    });
+
+    // The durable coreutils replace ~25 lifo builtins. They are the ones that
+    // carry credentials and read this filesystem's uid/gid, so they must win.
+    registerUnixCommands(sandbox.commands.registry, vfs);
+    installPathExecResolver(sandbox.commands.registry, vfs.as(CRED_SESSION_USER), () => sandbox.shell.getCwd());
+
+    return new NimbusWorkspace(sandbox, vfs, options.sql);
+  }
+
+  exec(command: string, options?: RunOptions): Promise<CommandResult> {
+    return this.sandbox.commands.run(command, options);
+  }
+
+  /**
+   * Files, directories and bytes this workspace occupies.
+   *
+   * A host sharing its Durable Object needs this because the filesystem's own
+   * `df` reports the workspace's usage against the whole 10 GB limit, and the
+   * host's rows draw on that same limit without appearing here.
+   */
+  stats(): { files: number; dirs: number; usedBytes: number } {
+    const s = this.vfs.getStats();
+    return { files: s.files, dirs: s.directories, usedBytes: s.usedBytes };
+  }
+
+  /**
+   * Drop this workspace's tables. The host's own rows are untouched.
+   *
+   * Deliberately not `ctx.storage.deleteAll()`, which is what the session's
+   * own destroy uses: a session owns its Durable Object, and a workspace does
+   * not. Calling deleteAll here would erase the data of whatever else the host
+   * keeps in that object.
+   */
+  destroy(): void {
+    for (const table of WORKSPACE_TABLES) {
+      this.sql.exec(`DROP TABLE IF EXISTS ${table}`);
+    }
+  }
+}
+
+/**
+ * Every table the filesystem creates.
+ *
+ * Listed rather than discovered because the namespace is the contract an
+ * embedder is owed: these names, and nothing else in their database, belong
+ * to the workspace. `inodes`, `file_chunks` and `content_lifecycle` are the
+ * three that carry no `vfs_` prefix and so are the ones most likely to
+ * collide with a host's own schema.
+ */
+const WORKSPACE_TABLES = [
+  'inodes',
+  'file_chunks',
+  'content_lifecycle',
+  'vfs_schema_migrations',
+  'vfs_append_receipts',
+  'vfs_append_writer_state',
+  'vfs_append_module_state',
+  'vfs_append_pid_revocations',
+  'vfs_append_acked_gaps',
+] as const;
+
+/**
+ * The directories and account files the shell cannot start without.
+ *
+ * Idempotent by construction: every write is guarded by an existence check, so
+ * a workspace reopened over a populated database keeps whatever the user did
+ * to these files. `/etc/passwd` and `/etc/group` are load-bearing rather than
+ * decorative — `id`, `chown` and `su` resolve names through them.
+ */
+function seedBaseFilesystem(vfs: SqliteVFS, mounts: readonly string[]): void {
+  const fs = vfs.as(CRED_SESSION_USER);
+  const rootFs = vfs.as(CRED_KERNEL);
+
+  // Created AS the session user, so the user owns their own tree. Seeding
+  // these as the kernel is what makes a workspace where `.fs` cannot write.
+  for (const mount of mounts) {
+    if (mount !== 'etc' && !fs.exists(mount)) fs.mkdir(mount, { recursive: true });
+  }
+  for (const dir of ['home/user', 'usr/bin', 'usr/local/bin', 'var/log', 'tmp']) {
+    if (!fs.exists(dir)) fs.mkdir(dir, { recursive: true });
+  }
+
+  if (!rootFs.exists('etc')) rootFs.mkdir('etc', { mode: 0o755 });
+
+  // Root-owned 0644, and re-asserted rather than only created: these decide
+  // what `id`, `chown` and `su` believe, so a user-writable /etc/passwd would
+  // be an authority bug rather than an untidy file.
+  const accountFile = (path: string, content: string): void => {
+    if (!rootFs.exists(path)) rootFs.writeFile(path, content, { mode: 0o644 });
+    const stat = rootFs.stat(path);
+    if (stat.uid !== 0 || stat.gid !== 0) rootFs.chown(path, 0, 0);
+    if ((stat.mode & 0o7777) !== 0o644) rootFs.chmod(path, 0o644);
+  };
+  accountFile('etc/passwd', 'root:x:0:0:root:/root:/bin/sh\nuser:x:1000:1000:Nimbus User:/home/user:/bin/sh\n');
+  accountFile('etc/group', 'root:x:0:\nuser:x:1000:user\n');
+
+  if (!rootFs.exists('etc/profile')) {
+    rootFs.writeFile('etc/profile', `export PATH=${DEFAULT_PATH}\nexport EDITOR=nano\n`);
+    rootFs.chown('etc/profile', CRED_SESSION_USER.uid, CRED_SESSION_USER.gid);
+  }
+}