@secure-exec/core 0.2.0-rc.2 → 0.2.0

package/dist/vfs/types.d.ts

@@ -0,0 +1,210 @@
+/**
+ * VFS storage layer interfaces.
+ *
+ * FsMetadataStore owns the filesystem tree (inodes, directory entries, symlinks,
+ * chunk mapping). FsBlockStore is a dumb key-value byte store for file content.
+ * ChunkedVFS composes the two into a VirtualFileSystem.
+ */
+export type InodeType = "file" | "directory" | "symlink";
+export interface CreateInodeAttrs {
+    type: InodeType;
+    mode: number;
+    uid: number;
+    gid: number;
+    /** Required for symlinks. */
+    symlinkTarget?: string;
+}
+export interface InodeMeta {
+    ino: number;
+    type: InodeType;
+    mode: number;
+    uid: number;
+    gid: number;
+    size: number;
+    nlink: number;
+    atimeMs: number;
+    mtimeMs: number;
+    ctimeMs: number;
+    birthtimeMs: number;
+    /**
+     * 'inline': content stored in inlineContent (small files).
+     * 'chunked': content stored as blocks in the block store.
+     */
+    storageMode: "inline" | "chunked";
+    /** Inline content for small files. Null if chunked. */
+    inlineContent: Uint8Array | null;
+}
+export interface DentryInfo {
+    name: string;
+    ino: number;
+    type: InodeType;
+}
+export interface DentryStatInfo extends DentryInfo {
+    stat: InodeMeta;
+}
+/**
+ * Owns the filesystem tree, inode metadata, and chunk mapping.
+ * No file content. All path resolution happens here.
+ *
+ * Implementations:
+ * - InMemoryMetadataStore: pure JS Map-based, for ephemeral VMs and tests.
+ * - SqliteMetadataStore: SQLite-backed, for persistent local and cloud storage.
+ */
+export interface FsMetadataStore {
+    /**
+     * Execute a callback atomically. All metadata mutations within
+     * the callback either fully commit or fully roll back.
+     * SQLite: wraps in BEGIN/COMMIT.
+     * InMemory: just calls the callback (single-threaded JS, no rollback needed).
+     */
+    transaction<T>(fn: () => Promise<T>): Promise<T>;
+    /** Create a new inode. Returns the allocated inode number. */
+    createInode(attrs: CreateInodeAttrs): Promise<number>;
+    /** Get inode metadata by number. Returns null if not found. */
+    getInode(ino: number): Promise<InodeMeta | null>;
+    /** Update inode metadata fields (partial update). */
+    updateInode(ino: number, updates: Partial<InodeMeta>): Promise<void>;
+    /** Delete an inode and all associated data (chunk map, symlink target). */
+    deleteInode(ino: number): Promise<void>;
+    /** Look up a child name in a directory. Returns child ino or null. */
+    lookup(parentIno: number, name: string): Promise<number | null>;
+    /** Create a directory entry. Throws EEXIST if name already exists. */
+    createDentry(parentIno: number, name: string, childIno: number, type: InodeType): Promise<void>;
+    /** Remove a directory entry. Does NOT delete the child inode. */
+    removeDentry(parentIno: number, name: string): Promise<void>;
+    /** List all entries in a directory. */
+    listDir(parentIno: number): Promise<DentryInfo[]>;
+    /**
+     * List all entries with full inode metadata (avoids N+1).
+     * SQLite: single JOIN query. InMemory: iterate + Map lookup.
+     */
+    listDirWithStats(parentIno: number): Promise<DentryStatInfo[]>;
+    /**
+     * Move a directory entry. Atomic: removes from src parent,
+     * adds to dst parent. Handles same-parent rename.
+     */
+    renameDentry(srcParentIno: number, srcName: string, dstParentIno: number, dstName: string): Promise<void>;
+    /**
+     * Walk the dentry tree from root, following symlinks.
+     * Returns the resolved inode number.
+     * Throws ENOENT if any component does not exist.
+     * Throws ELOOP if symlink depth exceeds 40 (SYMLOOP_MAX).
+     */
+    resolvePath(path: string): Promise<number>;
+    /**
+     * Resolve all intermediate path components but NOT the final one.
+     * Returns the parent inode and the final component name.
+     * Used for lstat, readlink, unlink, and creating new entries.
+     * Throws ENOENT if any intermediate component does not exist.
+     */
+    resolveParentPath(path: string): Promise<{
+        parentIno: number;
+        name: string;
+    }>;
+    /** Get the symlink target for a symlink inode. */
+    readSymlink(ino: number): Promise<string>;
+    /** Get the block store key for a chunk. Null if not set (sparse hole). */
+    getChunkKey(ino: number, chunkIndex: number): Promise<string | null>;
+    /** Set the block store key for a chunk. Creates or updates. */
+    setChunkKey(ino: number, chunkIndex: number, key: string): Promise<void>;
+    /** Get all chunk keys for a file, ordered by chunk index. */
+    getAllChunkKeys(ino: number): Promise<{
+        chunkIndex: number;
+        key: string;
+    }[]>;
+    /** Delete all chunk mappings for an inode. Returns the deleted keys. */
+    deleteAllChunks(ino: number): Promise<string[]>;
+    /**
+     * Delete chunk mappings for indices >= startIndex.
+     * Returns the deleted keys. Used by truncate.
+     */
+    deleteChunksFrom(ino: number, startIndex: number): Promise<string[]>;
+}
+/**
+ * Dumb key-value byte store. Knows nothing about files, directories, or inodes.
+ *
+ * Error contracts:
+ * - read/readRange: throw KernelError("ENOENT") if key not found.
+ * - readRange beyond block size: return available bytes (short read).
+ * - write: overwrite if key exists.
+ * - delete/deleteMany: no-op for non-existent keys.
+ * - copy: throw KernelError("ENOENT") if source key not found.
+ */
+export interface FsBlockStore {
+    /** Read an entire block. Throws if key not found. */
+    read(key: string): Promise<Uint8Array>;
+    /** Read a byte range within a block. Throws if key not found. */
+    readRange(key: string, offset: number, length: number): Promise<Uint8Array>;
+    /** Write a block (creates or overwrites). */
+    write(key: string, data: Uint8Array): Promise<void>;
+    /** Delete a block. No-op if key does not exist. */
+    delete(key: string): Promise<void>;
+    /** Delete multiple blocks. No-op for keys that don't exist. */
+    deleteMany(keys: string[]): Promise<void>;
+    /**
+     * Server-side copy. Optional.
+     * If not implemented, callers fall back to read + write.
+     */
+    copy?(srcKey: string, dstKey: string): Promise<void>;
+}
+export interface VersionMeta {
+    version: number;
+    size: number;
+    createdAt: number;
+    storageMode: "inline" | "chunked";
+    inlineContent: Uint8Array | null;
+}
+/**
+ * Optional versioning extension for FsMetadataStore.
+ *
+ * Implementations that support versioning (e.g., SqliteMetadataStore) can
+ * implement this interface to allow ChunkedVFS to snapshot, list, and
+ * restore file versions.
+ *
+ * Both SqliteMetadataStore and InMemoryMetadataStore implement versioning
+ * when the `versioning` option is enabled at construction time.
+ */
+export interface FsMetadataStoreVersioning {
+    /** Snapshot current chunk map + size. Returns the version number. */
+    createVersion(ino: number): Promise<number>;
+    /** Get version info. Returns null if the version does not exist. */
+    getVersion(ino: number, version: number): Promise<VersionMeta | null>;
+    /** List versions, newest first. */
+    listVersions(ino: number): Promise<VersionMeta[]>;
+    /** Get chunk map for a specific version. */
+    getVersionChunkMap(ino: number, version: number): Promise<{
+        chunkIndex: number;
+        key: string;
+    }[]>;
+    /**
+     * Delete version records. Returns block keys that are no longer
+     * referenced by ANY version or the current chunk map.
+     */
+    deleteVersions(ino: number, versions: number[]): Promise<string[]>;
+    /** Restore current chunk map to match a version. */
+    restoreVersion(ino: number, version: number): Promise<void>;
+}
+export type RetentionPolicy = 
+/** Keep the N most recent versions. Delete the rest immediately. */
+{
+    type: "count";
+    keep: number;
+}
+/** Keep versions newer than maxAgeMs. Delete older immediately. */
+ | {
+    type: "age";
+    maxAgeMs: number;
+}
+/**
+ * Mark old metadata as pruned but do NOT delete blocks.
+ * Used with block stores that have their own TTL/lifecycle
+ * (e.g., S3 lifecycle rules). The block store handles cleanup.
+ */
+ | {
+    type: "deferred";
+};
+export interface VersionInfo {
+    version: number;
+    size: number;
+    createdAt: number;
+}

package/dist/vfs/types.js

@@ -0,0 +1,8 @@
+/**
+ * VFS storage layer interfaces.
+ *
+ * FsMetadataStore owns the filesystem tree (inodes, directory entries, symlinks,
+ * chunk mapping). FsBlockStore is a dumb key-value byte store for file content.
+ * ChunkedVFS composes the two into a VirtualFileSystem.
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@secure-exec/core",
-  "version": "0.2.0-rc.2",
+  "version": "0.2.0",
   "type": "module",
   "license": "Apache-2.0",
   "main": "./dist/index.js",
@@ -79,14 +79,33 @@
       "types": "./dist/shared/*.d.ts",
       "import": "./dist/shared/*.js",
       "default": "./dist/shared/*.js"
+    },
+    "./test/vfs-conformance": {
+      "types": "./dist/test/vfs-conformance.d.ts",
+      "import": "./dist/test/vfs-conformance.js",
+      "default": "./dist/test/vfs-conformance.js"
+    },
+    "./test/block-store-conformance": {
+      "types": "./dist/test/block-store-conformance.d.ts",
+      "import": "./dist/test/block-store-conformance.js",
+      "default": "./dist/test/block-store-conformance.js"
+    },
+    "./test/metadata-store-conformance": {
+      "types": "./dist/test/metadata-store-conformance.d.ts",
+      "import": "./dist/test/metadata-store-conformance.js",
+      "default": "./dist/test/metadata-store-conformance.js"
     }
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.10.2",
     "@xterm/headless": "^6.0.0",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8"
   },
+  "dependencies": {
+    "better-sqlite3": "^12.8.0"
+  },
   "scripts": {
     "check-types:src": "tsc --noEmit",
     "check-types:isolate-runtime": "tsc -p tsconfig.isolate-runtime.json --noEmit",

package/dist/kernel/inode-table.d.ts

@@ -1,43 +0,0 @@
-/**
- * Inode table with refcounting and deferred unlink.
- *
- * Provides a POSIX-style inode layer: hard link counts (nlink),
- * open FD reference counting (openRefCount), and deferred deletion
- * when nlink reaches 0 but FDs are still open.
- */
-export interface Inode {
-    readonly ino: number;
-    nlink: number;
-    openRefCount: number;
-    mode: number;
-    uid: number;
-    gid: number;
-    size: number;
-    atime: Date;
-    mtime: Date;
-    ctime: Date;
-    birthtime: Date;
-}
-export declare class InodeTable {
-    private inodes;
-    private nextIno;
-    /** Allocate a new inode with the given mode, uid, gid. Returns the inode. */
-    allocate(mode: number, uid: number, gid: number): Inode;
-    /** Look up an inode by number. */
-    get(ino: number): Inode | null;
-    /** Increment hard link count (new directory entry pointing to this inode). */
-    incrementLinks(ino: number): void;
-    /** Decrement hard link count (directory entry removed). */
-    decrementLinks(ino: number): void;
-    /** Increment open FD reference count. */
-    incrementOpenRefs(ino: number): void;
-    /** Decrement open FD reference count. */
-    decrementOpenRefs(ino: number): void;
-    /** True when nlink=0 AND openRefCount=0 — inode data can be freed. */
-    shouldDelete(ino: number): boolean;
-    /** Remove the inode from the table. Called after shouldDelete returns true. */
-    delete(ino: number): void;
-    /** Number of inodes in the table. */
-    get size(): number;
-    private requireInode;
-}

package/dist/kernel/inode-table.js

@@ -1,85 +0,0 @@
-/**
- * Inode table with refcounting and deferred unlink.
- *
- * Provides a POSIX-style inode layer: hard link counts (nlink),
- * open FD reference counting (openRefCount), and deferred deletion
- * when nlink reaches 0 but FDs are still open.
- */
-import { KernelError } from "./types.js";
-export class InodeTable {
-    inodes = new Map();
-    nextIno = 1;
-    /** Allocate a new inode with the given mode, uid, gid. Returns the inode. */
-    allocate(mode, uid, gid) {
-        const now = new Date();
-        const inode = {
-            ino: this.nextIno++,
-            nlink: 1,
-            openRefCount: 0,
-            mode,
-            uid,
-            gid,
-            size: 0,
-            atime: now,
-            mtime: now,
-            ctime: now,
-            birthtime: now,
-        };
-        this.inodes.set(inode.ino, inode);
-        return inode;
-    }
-    /** Look up an inode by number. */
-    get(ino) {
-        return this.inodes.get(ino) ?? null;
-    }
-    /** Increment hard link count (new directory entry pointing to this inode). */
-    incrementLinks(ino) {
-        const inode = this.requireInode(ino);
-        inode.nlink++;
-        inode.ctime = new Date();
-    }
-    /** Decrement hard link count (directory entry removed). */
-    decrementLinks(ino) {
-        const inode = this.requireInode(ino);
-        if (inode.nlink <= 0) {
-            throw new KernelError("EINVAL", `inode ${ino} nlink already 0`);
-        }
-        inode.nlink--;
-        inode.ctime = new Date();
-    }
-    /** Increment open FD reference count. */
-    incrementOpenRefs(ino) {
-        const inode = this.requireInode(ino);
-        inode.openRefCount++;
-    }
-    /** Decrement open FD reference count. */
-    decrementOpenRefs(ino) {
-        const inode = this.requireInode(ino);
-        if (inode.openRefCount <= 0) {
-            throw new KernelError("EINVAL", `inode ${ino} openRefCount already 0`);
-        }
-        inode.openRefCount--;
-    }
-    /** True when nlink=0 AND openRefCount=0 — inode data can be freed. */
-    shouldDelete(ino) {
-        const inode = this.inodes.get(ino);
-        if (!inode)
-            return false;
-        return inode.nlink === 0 && inode.openRefCount === 0;
-    }
-    /** Remove the inode from the table. Called after shouldDelete returns true. */
-    delete(ino) {
-        this.inodes.delete(ino);
-    }
-    /** Number of inodes in the table. */
-    get size() {
-        return this.inodes.size;
-    }
-    requireInode(ino) {
-        const inode = this.inodes.get(ino);
-        if (!inode) {
-            throw new KernelError("ENOENT", `inode ${ino} not found`);
-        }
-        return inode;
-    }
-}