@rcrsr/rill 0.8.0 → 0.8.2

package/dist/ext/fs/sandbox.js

@@ -0,0 +1,208 @@
+/**
+ * fs Extension Sandbox Module
+ *
+ * Path resolution and validation implementing 9-step security sequence.
+ * Prevents path traversal and symlink attacks via realpath() defense.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { RuntimeError } from '../../error-classes.js';
+// ============================================================
+// PATH RESOLUTION
+// ============================================================
+/**
+ * Resolves and validates path within mount boundaries.
+ *
+ * 9-step path resolution sequence (spec lines 331-342):
+ * 1. Resolve mount name to MountConfig
+ * 2. Use mount's resolved physical path (from creation time)
+ * 3. Join resolved mount base with script's relative path argument
+ * 4. Normalize with path.resolve() to collapse .. segments
+ * 5. Resolve final path with fs.realpath() (symlink defense)
+ * 6. Verify resolved path starts with mount's resolved base (startsWith())
+ * 7. If glob set, verify filename matches pattern
+ * 8. Check mode permits operation
+ * 9. Return validated path for node:fs operation
+ *
+ * @param mountName - Mount identifier from script
+ * @param relativePath - Script-provided path relative to mount
+ * @param mounts - Mount configuration map
+ * @param operation - Operation type for mode validation
+ * @param createMode - For write operations creating new files (checks parent dir)
+ * @returns Validated absolute path
+ * @throws RuntimeError - EC-1 (unknown mount), EC-2 (path escape), EC-3 (glob), EC-4 (mode), EC-7 (permission)
+ */
+export async function resolvePath(mountName, relativePath, mounts, operation, createMode = false) {
+    // Step 1: Resolve mount name to MountConfig
+    // EC-1: Unknown mount name
+    const mount = mounts[mountName];
+    if (!mount) {
+        throw new RuntimeError('RILL-R017', `mount "${mountName}" not configured`, undefined, { mountName });
+    }
+    // Step 2: Use mount's resolved physical path (set at creation time)
+    const mountBase = mount.resolvedPath;
+    if (!mountBase) {
+        throw new RuntimeError('RILL-R017', `mount "${mountName}" not initialized (missing resolvedPath)`, undefined, { mountName });
+    }
+    // Step 3: Join resolved mount base with script's relative path
+    const joined = path.join(mountBase, relativePath);
+    // Step 4: Normalize with path.resolve() to collapse .. segments
+    const normalized = path.resolve(joined);
+    // Step 6 (early check): Verify normalized path starts with mount base before realpath
+    // This catches path traversal attempts even when the target doesn't exist
+    // EC-2: Path escapes boundary
+    if (!normalized.startsWith(mountBase + path.sep) &&
+        normalized !== mountBase) {
+        throw new RuntimeError('RILL-R018', 'path escapes mount boundary', undefined, { mountName, path: relativePath, normalized, mountBase });
+    }
+    // Step 5: Resolve final path with fs.realpath() (symlink defense)
+    // For write operations creating new files, resolve parent directory instead
+    let resolvedPath;
+    try {
+        if (createMode) {
+            // New file write: resolve parent directory
+            const parentDir = path.dirname(normalized);
+            const resolvedParent = await fs.realpath(parentDir);
+            const filename = path.basename(normalized);
+            resolvedPath = path.join(resolvedParent, filename);
+        }
+        else {
+            // Existing file: resolve full path
+            resolvedPath = await fs.realpath(normalized);
+        }
+    }
+    catch (error) {
+        // EC-7: Permission denied or ENOENT
+        if (error && typeof error === 'object' && 'code' in error) {
+            const code = error.code;
+            if (code === 'EACCES' || code === 'EPERM') {
+                throw new RuntimeError('RILL-R021', `permission denied: ${normalized}`, undefined, { path: normalized, code });
+            }
+            // For ENOENT on createMode, this is expected (new file)
+            // For ENOENT on read mode, propagate as path doesn't exist
+            if (code === 'ENOENT') {
+                if (createMode) {
+                    // Parent directory doesn't exist for new file write
+                    throw new RuntimeError('RILL-R021', `parent directory does not exist: ${path.dirname(normalized)}`, undefined, { path: normalized });
+                }
+                else {
+                    // File doesn't exist for read
+                    throw new RuntimeError('RILL-R021', `file not found: ${normalized}`, undefined, { path: normalized });
+                }
+            }
+        }
+        throw error;
+    }
+    // Step 6 (post-realpath): Verify resolved path still within mount (symlink defense)
+    // EC-2: Path escapes boundary via symlink
+    if (!resolvedPath.startsWith(mountBase + path.sep) &&
+        resolvedPath !== mountBase) {
+        throw new RuntimeError('RILL-R018', 'path escapes mount boundary', undefined, { mountName, path: relativePath, resolvedPath, mountBase });
+    }
+    // Step 7: If glob set, verify filename matches pattern
+    // EC-3: Glob mismatch
+    if (mount.glob) {
+        const filename = path.basename(resolvedPath);
+        if (!matchesGlob(filename, mount.glob)) {
+            throw new RuntimeError('RILL-R019', `file type not permitted in mount "${mountName}"`, undefined, { mountName, glob: mount.glob, filename });
+        }
+    }
+    // Step 8: Check mode permits operation
+    // EC-4: Mode violation
+    if (!checkMode(mount.mode, operation)) {
+        throw new RuntimeError('RILL-R020', `mount "${mountName}" does not permit ${operation}`, undefined, { mountName, mode: mount.mode, operation });
+    }
+    // Step 9: Return validated path for node:fs operation
+    return resolvedPath;
+}
+// ============================================================
+// GLOB MATCHING
+// ============================================================
+/**
+ * Simple glob pattern matching (spec lines 346-354).
+ *
+ * Supported patterns:
+ * - *.csv - Files ending in .csv
+ * - *.{json,yaml} - Files ending in .json or .yaml
+ * - * - All files (default when omitted)
+ * - **\/*.csv - CSV files at any depth (for find() only)
+ *
+ * No third-party glob library. Uses path.extname() checks.
+ *
+ * @param filename - Filename to match (basename only)
+ * @param pattern - Glob pattern
+ * @returns true if filename matches pattern
+ */
+export function matchesGlob(filename, pattern) {
+    // Pattern: * (all files)
+    if (pattern === '*') {
+        return true;
+    }
+    // Pattern: *.ext (single extension)
+    if (pattern.startsWith('*.') && !pattern.includes('{')) {
+        const ext = pattern.slice(1); // Remove leading *
+        return filename.endsWith(ext);
+    }
+    // Pattern: *.{ext1,ext2} (multiple extensions)
+    if (pattern.startsWith('*.{') && pattern.endsWith('}')) {
+        const extensionsStr = pattern.slice(3, -1); // Extract between *.{ and }
+        const extensions = extensionsStr.split(',').map((e) => `.${e.trim()}`);
+        return extensions.some((ext) => filename.endsWith(ext));
+    }
+    // Pattern: **/*.ext (recursive, any depth)
+    if (pattern.startsWith('**/')) {
+        const subPattern = pattern.slice(3); // Remove leading **/
+        return matchesGlob(filename, subPattern);
+    }
+    // Unknown pattern: no match (conservative)
+    return false;
+}
+// ============================================================
+// MODE VALIDATION
+// ============================================================
+/**
+ * Checks if mount mode permits operation.
+ *
+ * @param mode - Mount access mode
+ * @param operation - Operation type
+ * @returns true if operation permitted
+ */
+export function checkMode(mode, operation) {
+    if (mode === 'read-write')
+        return true;
+    if (mode === 'read' && operation === 'read')
+        return true;
+    if (mode === 'write' && operation === 'write')
+        return true;
+    return false;
+}
+// ============================================================
+// MOUNT INITIALIZATION
+// ============================================================
+/**
+ * Resolves mount path at creation time (Step 2 of sequence).
+ *
+ * Mutates MountConfig to set resolvedPath field.
+ *
+ * @param mount - Mount configuration
+ * @throws RuntimeError - If mount path invalid or inaccessible
+ */
+export async function initializeMount(mount) {
+    try {
+        // Resolve mount path with fs.realpath() at creation time (spec line 333)
+        mount.resolvedPath = await fs.realpath(mount.path);
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error) {
+            const code = error.code;
+            if (code === 'ENOENT') {
+                throw new RuntimeError('RILL-R017', `mount path does not exist: ${mount.path}`, undefined, { path: mount.path });
+            }
+            if (code === 'EACCES' || code === 'EPERM') {
+                throw new RuntimeError('RILL-R021', `permission denied: ${mount.path}`, undefined, { path: mount.path, code });
+            }
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/ext/fs/sandbox.js.map

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

package/dist/ext/kv/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * KV Extension Factory
+ *
+ * Provides key-value store operations with JSON persistence and schema validation.
+ * Supports both open mode (any key/value) and declared mode (schema-defined keys only).
+ */
+import type { ExtensionResult } from '../../runtime/ext/extensions.js';
+import { type SchemaEntry } from './store.js';
+/** KV extension configuration */
+export interface KvConfig {
+    /** Path to store file */
+    store: string;
+    /** Schema definitions (optional, enables declared mode) */
+    schema?: Record<string, SchemaEntry> | undefined;
+    /** Maximum entries (default: 10000) */
+    maxEntries?: number | undefined;
+    /** Maximum value size in bytes (default: 102400 = 100KB) */
+    maxValueSize?: number | undefined;
+    /** Maximum store size in bytes (default: 10485760 = 10MB) */
+    maxStoreSize?: number | undefined;
+    /** Write policy: 'dispose' (default) or 'immediate' */
+    writePolicy?: 'dispose' | 'immediate' | undefined;
+}
+export type { SchemaEntry };
+/**
+ * Create KV extension with persistent storage.
+ *
+ * Initializes store by loading existing file or creating with schema defaults.
+ * Returns 8 functions: get, set, delete, keys, has, clear, getAll, schema.
+ *
+ * @param config - Store configuration
+ * @returns ExtensionResult with 8 KV functions and dispose handler
+ * @throws RuntimeError if store file is corrupt (EC-25)
+ *
+ * @example
+ * ```typescript
+ * const kvExt = createKvExtension({
+ *   store: './data/state.json',
+ *   schema: {
+ *     count: { type: 'number', default: 0 }
+ *   }
+ * });
+ * ```
+ */
+export declare function createKvExtension(config: KvConfig): ExtensionResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/ext/kv/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ext/kv/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAEvE,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAM3D,iCAAiC;AACjC,MAAM,WAAW,QAAQ;IACvB,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,SAAS,CAAC;IACjD,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,uDAAuD;IACvD,WAAW,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;CACnD;AAGD,YAAY,EAAE,WAAW,EAAE,CAAC;AAM5B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,QAAQ,GAAG,eAAe,CA2MnE"}

package/dist/ext/kv/index.js

@@ -0,0 +1,215 @@
+/**
+ * KV Extension Factory
+ *
+ * Provides key-value store operations with JSON persistence and schema validation.
+ * Supports both open mode (any key/value) and declared mode (schema-defined keys only).
+ */
+import { createStore } from './store.js';
+// ============================================================
+// FACTORY
+// ============================================================
+/**
+ * Create KV extension with persistent storage.
+ *
+ * Initializes store by loading existing file or creating with schema defaults.
+ * Returns 8 functions: get, set, delete, keys, has, clear, getAll, schema.
+ *
+ * @param config - Store configuration
+ * @returns ExtensionResult with 8 KV functions and dispose handler
+ * @throws RuntimeError if store file is corrupt (EC-25)
+ *
+ * @example
+ * ```typescript
+ * const kvExt = createKvExtension({
+ *   store: './data/state.json',
+ *   schema: {
+ *     count: { type: 'number', default: 0 }
+ *   }
+ * });
+ * ```
+ */
+export function createKvExtension(config) {
+    // Apply defaults
+    const maxEntries = config.maxEntries ?? 10000;
+    const maxValueSize = config.maxValueSize ?? 102400; // 100KB
+    const maxStoreSize = config.maxStoreSize ?? 10485760; // 10MB
+    const writePolicy = config.writePolicy ?? 'dispose';
+    // Store will be initialized lazily on first operation
+    let storePromise = null;
+    let storeInstance = null;
+    // Helper to get or create store
+    const getStore = async () => {
+        if (storeInstance)
+            return storeInstance;
+        if (!storePromise) {
+            storePromise = createStore({
+                store: config.store,
+                schema: config.schema,
+                maxEntries,
+                maxValueSize,
+                maxStoreSize,
+                writePolicy,
+            });
+        }
+        storeInstance = await storePromise;
+        return storeInstance;
+    };
+    // ============================================================
+    // FUNCTIONS
+    // ============================================================
+    /**
+     * Get value or schema default.
+     * IR-15, EC-20 (key not in schema)
+     * Returns empty string for missing keys in open mode.
+     */
+    const get = async (args) => {
+        const store = await getStore();
+        const key = args[0];
+        const value = store.get(key);
+        // In rill, functions cannot return undefined - return empty string for missing keys in open mode
+        return value !== undefined ? value : '';
+    };
+    /**
+     * Set value with validation.
+     * IR-16, EC-20-24
+     */
+    const set = async (args) => {
+        const store = await getStore();
+        const key = args[0];
+        const value = args[1];
+        await store.set(key, value);
+        return true;
+    };
+    /**
+     * Delete key.
+     * IR-17
+     */
+    const deleteKey = async (args) => {
+        const store = await getStore();
+        const key = args[0];
+        return store.delete(key);
+    };
+    /**
+     * Get all keys.
+     * IR-18
+     */
+    const keys = async () => {
+        const store = await getStore();
+        return store.keys();
+    };
+    /**
+     * Check key existence.
+     * IR-19
+     */
+    const has = async (args) => {
+        const store = await getStore();
+        const key = args[0];
+        return store.has(key);
+    };
+    /**
+     * Clear all keys (restores schema defaults if declared mode).
+     * IR-20
+     */
+    const clear = async () => {
+        const store = await getStore();
+        store.clear();
+        return true;
+    };
+    /**
+     * Get all entries as dict.
+     * IR-21
+     */
+    const getAll = async () => {
+        const store = await getStore();
+        return store.getAll();
+    };
+    /**
+     * Get schema information (empty list in open mode).
+     * IR-22
+     */
+    const schema = async () => {
+        if (!config.schema) {
+            return []; // Open mode - no schema
+        }
+        // Declared mode - return schema entries as list of dicts
+        const result = [];
+        for (const [key, entry] of Object.entries(config.schema)) {
+            result.push({
+                key,
+                type: entry.type,
+                description: entry.description ?? '',
+            });
+        }
+        return result;
+    };
+    // ============================================================
+    // DISPOSE
+    // ============================================================
+    /**
+     * Flush state to disk on dispose.
+     */
+    const dispose = async () => {
+        if (storeInstance) {
+            await storeInstance.flush();
+        }
+    };
+    // ============================================================
+    // EXTENSION RESULT
+    // ============================================================
+    const result = {
+        get: {
+            params: [{ name: 'key', type: 'string', description: 'Key to retrieve' }],
+            fn: get,
+            description: 'Get value or schema default',
+            returnType: 'any',
+        },
+        set: {
+            params: [
+                { name: 'key', type: 'string', description: 'Key to set' },
+                { name: 'value', type: 'string', description: 'Value to store' },
+            ],
+            fn: set,
+            description: 'Set value with validation',
+            returnType: 'bool',
+        },
+        delete: {
+            params: [{ name: 'key', type: 'string', description: 'Key to delete' }],
+            fn: deleteKey,
+            description: 'Delete key',
+            returnType: 'bool',
+        },
+        keys: {
+            params: [],
+            fn: keys,
+            description: 'Get all keys',
+            returnType: 'list',
+        },
+        has: {
+            params: [{ name: 'key', type: 'string', description: 'Key to check' }],
+            fn: has,
+            description: 'Check key existence',
+            returnType: 'bool',
+        },
+        clear: {
+            params: [],
+            fn: clear,
+            description: 'Clear all keys',
+            returnType: 'bool',
+        },
+        getAll: {
+            params: [],
+            fn: getAll,
+            description: 'Get all entries as dict',
+            returnType: 'dict',
+        },
+        schema: {
+            params: [],
+            fn: schema,
+            description: 'Get schema information',
+            returnType: 'list',
+        },
+    };
+    result.dispose = dispose;
+    return result;
+}
+//# sourceMappingURL=index.js.map

package/dist/ext/kv/index.js.map

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

package/dist/ext/kv/store.d.ts

@@ -0,0 +1,46 @@
+/**
+ * KV Store Implementation
+ *
+ * Provides JSON-based key-value persistence with schema validation.
+ * Lifecycle: Load (read store file) -> Execute (in-memory operations) -> Flush (atomic write on dispose)
+ */
+import type { RillValue } from '../../runtime/core/values.js';
+/** Schema entry defining type and default for a key */
+export interface SchemaEntry {
+    type: 'string' | 'number' | 'bool' | 'list' | 'dict';
+    default: RillValue;
+    description?: string | undefined;
+}
+/** Store configuration */
+export interface StoreConfig {
+    /** Path to store file */
+    store: string;
+    /** Schema definitions (optional, enables declared mode) */
+    schema?: Record<string, SchemaEntry> | undefined;
+    /** Maximum entries (default: 10000) */
+    maxEntries?: number | undefined;
+    /** Maximum value size in bytes (default: 102400 = 100KB) */
+    maxValueSize?: number | undefined;
+    /** Maximum store size in bytes (default: 10485760 = 10MB) */
+    maxStoreSize?: number | undefined;
+    /** Write policy: 'dispose' (default) or 'immediate' */
+    writePolicy?: 'dispose' | 'immediate' | undefined;
+}
+/**
+ * Create KV store with JSON persistence.
+ *
+ * @param config - Store configuration
+ * @returns Store operations object
+ * @throws RuntimeError if store file is corrupt (EC-25)
+ */
+export declare function createStore(config: StoreConfig): Promise<{
+    get: (key: string) => RillValue | undefined;
+    set: (key: string, value: RillValue) => Promise<void>;
+    delete: (key: string) => boolean;
+    keys: () => string[];
+    has: (key: string) => boolean;
+    clear: () => void;
+    getAll: () => Record<string, RillValue>;
+    flush: () => Promise<void>;
+}>;
+//# sourceMappingURL=store.d.ts.map

package/dist/ext/kv/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/ext/kv/store.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAM9D,uDAAuD;AACvD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACrD,OAAO,EAAE,SAAS,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED,0BAA0B;AAC1B,MAAM,WAAW,WAAW;IAC1B,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,SAAS,CAAC;IACjD,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,uDAAuD;IACvD,WAAW,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;CACnD;AAMD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC;IAC9D,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,GAAG,SAAS,CAAC;IAC5C,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACjC,IAAI,EAAE,MAAM,MAAM,EAAE,CAAC;IACrB,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAC9B,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,MAAM,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACxC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,CAAC,CAmTD"}