nebula-notebook 0.2.16 → 0.2.17

package/node-server/dist/fs/fs-service.js

@@ -50,6 +50,72 @@ const default_kernel_1 = require("../kernel/default-kernel");
 const registry_1 = require("./notebook-formats/registry");
 const percent_1 = require("./notebook-formats/percent");
 const display_data_1 = require("../output/display-data");
+const sealed_path_1 = require("./sealed-path");
+const JUPYTER_CELL_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+function isValidJupyterCellId(value) {
+    return typeof value === 'string' && JUPYTER_CELL_ID_PATTERN.test(value);
+}
+/**
+ * Resolve stable, unique IDs for every cell in an imported notebook.
+ *
+ * Native nbformat IDs own the namespace before legacy metadata fallbacks are
+ * considered. This prevents an earlier legacy-only or malformed cell from
+ * stealing a valid native ID from a later cell. The first occurrence of a
+ * duplicate native ID remains canonical; later duplicates are repaired using
+ * an otherwise-unclaimed legacy ID or a deterministic position-based ID.
+ */
+function resolveJupyterCellIds(cells) {
+    const resolved = new Array(cells.length);
+    const nativeOwners = new Map();
+    cells.forEach((cell, index) => {
+        if (isValidJupyterCellId(cell.id) && !nativeOwners.has(cell.id)) {
+            nativeOwners.set(cell.id, index);
+        }
+    });
+    const reservedNativeIds = new Set(nativeOwners.keys());
+    const used = new Set();
+    for (const [id, index] of nativeOwners) {
+        resolved[index] = id;
+        used.add(id);
+    }
+    cells.forEach((cell, index) => {
+        if (resolved[index] !== undefined)
+            return;
+        const legacyId = cell.metadata?.nebula_id;
+        if (isValidJupyterCellId(legacyId)
+            && !reservedNativeIds.has(legacyId)
+            && !used.has(legacyId)) {
+            resolved[index] = legacyId;
+            used.add(legacyId);
+        }
+    });
+    cells.forEach((_cell, index) => {
+        if (resolved[index] !== undefined)
+            return;
+        const base = `cell-${index}`;
+        let candidate = base;
+        let suffix = 1;
+        while (reservedNativeIds.has(candidate) || used.has(candidate)) {
+            candidate = `${base}-${suffix}`;
+            suffix += 1;
+        }
+        resolved[index] = candidate;
+        used.add(candidate);
+    });
+    return resolved;
+}
+function validateJupyterCellIds(cells) {
+    const seen = new Set();
+    cells.forEach((cell, index) => {
+        if (!isValidJupyterCellId(cell.id)) {
+            throw new Error(`Invalid Jupyter cell ID at index ${index}: expected 1-64 ASCII letters, digits, hyphens, or underscores`);
+        }
+        if (seen.has(cell.id)) {
+            throw new Error(`Duplicate Jupyter cell ID at index ${index}: ${cell.id}`);
+        }
+        seen.add(cell.id);
+    });
+}
 const NEBULA_DIR = path.join(os.homedir(), '.nebula');
 const USER_CONFIG_PATH = path.join(NEBULA_DIR, 'config.json');
 const PROJECT_CONFIG_PATH = path.join(__dirname, '..', '..', '..', '.nebula-config.json');
@@ -317,6 +383,10 @@ class FilesystemService {
      * Prevents partial/corrupt files on interruption.
      */
     atomicWriteFileSync(targetPath, data) {
+        // Keep the immutability check at the lowest shared write primitive as a
+        // backstop for future notebook mutation APIs. ReplaySealService bypasses
+        // FilesystemService and writes its staging/seal artifacts directly.
+        (0, sealed_path_1.assertPathMutable)(targetPath, { operation: 'write' });
         const dir = path.dirname(targetPath);
         if (!fs.existsSync(dir)) {
             fs.mkdirSync(dir, { recursive: true });
@@ -361,6 +431,7 @@ class FilesystemService {
      * notebook file itself stays fully durable.
      */
     async atomicWriteFile(targetPath, data, opts = {}) {
+        (0, sealed_path_1.assertPathMutable)(targetPath, { operation: 'write' });
         const durable = opts.durable !== false;
         const dir = path.dirname(targetPath);
         await fs_1.promises.mkdir(dir, { recursive: true });
@@ -611,6 +682,7 @@ class FilesystemService {
      */
     writeFile(filePath, content, fileType = 'text') {
         const normalizedPath = this.normalizePath(filePath);
+        (0, sealed_path_1.assertPathMutable)(normalizedPath, { operation: 'write' });
         // Create parent directories if needed
         const parentDir = path.dirname(normalizedPath);
         if (parentDir && !fs.existsSync(parentDir)) {
@@ -629,6 +701,7 @@ class FilesystemService {
      */
     createFile(filePath, isDirectory = false) {
         const normalizedPath = this.normalizePath(filePath);
+        (0, sealed_path_1.assertPathMutable)(normalizedPath, { operation: 'create a file in' });
         if (fs.existsSync(normalizedPath)) {
             throw new Error(`Path already exists: ${normalizedPath}`);
         }
@@ -779,6 +852,7 @@ class FilesystemService {
      */
     deleteFile(filePath) {
         const normalizedPath = this.normalizePath(filePath);
+        (0, sealed_path_1.assertPathMutable)(normalizedPath, { operation: 'delete', protectDescendants: true });
         if (!fs.existsSync(normalizedPath)) {
             throw new Error(`Path not found: ${normalizedPath}`);
         }
@@ -830,6 +904,8 @@ class FilesystemService {
     renameFile(oldPath, newPath) {
         const normalizedOld = this.normalizePath(oldPath);
         const normalizedNew = this.normalizePath(newPath);
+        (0, sealed_path_1.assertPathMutable)(normalizedOld, { operation: 'move', protectDescendants: true });
+        (0, sealed_path_1.assertPathMutable)(normalizedNew, { operation: 'move a file into' });
         if (!fs.existsSync(normalizedOld)) {
             throw new Error(`Path not found: ${normalizedOld}`);
         }
@@ -900,6 +976,7 @@ class FilesystemService {
      */
     duplicateFile(filePath) {
         const normalizedPath = this.normalizePath(filePath);
+        (0, sealed_path_1.assertPathMutable)(normalizedPath, { operation: 'duplicate', protectDescendants: true });
         if (!fs.existsSync(normalizedPath)) {
             throw new Error(`File not found: ${normalizedPath}`);
         }
@@ -946,6 +1023,7 @@ class FilesystemService {
      */
     async uploadFile(destDir, tempFilePath, originalName, onConflict = 'rename') {
         const normalizedDir = this.normalizePath(destDir);
+        (0, sealed_path_1.assertPathMutable)(normalizedDir, { operation: 'upload into' });
         if (!fs.existsSync(normalizedDir)) {
             throw new Error(`Directory not found: ${normalizedDir}`);
         }
@@ -955,6 +1033,7 @@ class FilesystemService {
         }
         // Determine final path
         let finalPath = path.join(normalizedDir, originalName);
+        (0, sealed_path_1.assertPathMutable)(finalPath, { operation: 'upload' });
         if (fs.existsSync(finalPath) && onConflict !== 'overwrite') {
             if (onConflict === 'fail') {
                 throw new Error(`already exists: ${finalPath}`);
@@ -1157,10 +1236,11 @@ class FilesystemService {
         const notebook = JSON.parse(raw);
         const metadataKernel = notebook.metadata?.kernelspec?.name;
         const kernelspec = metadataKernel || 'python3';
+        const cellIds = resolveJupyterCellIds(notebook.cells || []);
         const cells = notebook.cells.map((nbCell, i) => {
             let cellType = nbCell.cell_type === 'markdown' ? 'markdown' : 'code';
             const content = this.sourceToString(nbCell.source);
-            const cellId = nbCell.metadata?.nebula_id || nbCell.id || `cell-${i}`;
+            const cellId = cellIds[i];
             const outputs = this.convertOutputs(nbCell.outputs, i);
             const cell = {
                 id: cellId,
@@ -1225,10 +1305,12 @@ class FilesystemService {
      */
     async saveNotebookCells(notebookPath, cells, kernelName, notebookMetadata) {
         const normalizedPath = this.normalizePath(notebookPath);
+        (0, sealed_path_1.assertPathMutable)(normalizedPath, { operation: 'save' });
         const formatAdapter = (0, registry_1.getFormatAdapter)(normalizedPath);
         if (formatAdapter) {
             return await this.saveTextNotebookCells(formatAdapter, normalizedPath, cells, kernelName, notebookMetadata);
         }
+        validateJupyterCellIds(cells);
         // Load existing notebook metadata if file exists.
         // Prefer a fast scan for the top-level metadata object so we avoid
         // parsing the full notebook on every save. Fall back to full JSON
@@ -1269,11 +1351,14 @@ class FilesystemService {
         if (sentinelCells.length > 0) {
             try {
                 const existing = JSON.parse(await fs_1.promises.readFile(normalizedPath, 'utf-8'));
-                for (const jc of existing.cells || []) {
-                    const nid = jc.metadata?.nebula_id;
-                    if (nid)
-                        priorOutputs.set(String(nid), { outputs: jc.outputs || [], execution_count: jc.execution_count ?? null });
-                }
+                const existingCells = existing.cells || [];
+                const existingCellIds = resolveJupyterCellIds(existingCells);
+                existingCells.forEach((jc, index) => {
+                    priorOutputs.set(existingCellIds[index], {
+                        outputs: jc.outputs || [],
+                        execution_count: jc.execution_count ?? null,
+                    });
+                });
             }
             catch {
                 return { success: false, mtime: 0, needsFull: true };
@@ -1284,10 +1369,10 @@ class FilesystemService {
             }
         }
         const nbCells = cells.map((cell) => {
-            const preservedMetadata = cell._metadata || {};
+            const preservedMetadata = { ...(cell._metadata || {}) };
+            delete preservedMetadata.nebula_id;
             const cellMetadata = {
                 ...preservedMetadata,
-                nebula_id: cell.id,
             };
             if (cell.scrolled !== undefined) {
                 cellMetadata.scrolled = cell.scrolled;
@@ -1296,6 +1381,7 @@ class FilesystemService {
                 cellMetadata.scrolled_height = cell.scrolledHeight;
             }
             const nbCell = {
+                id: cell.id,
                 cell_type: cell.type,
                 source: this.stringToSource(cell.content),
                 metadata: cellMetadata,
@@ -1359,6 +1445,7 @@ class FilesystemService {
      * Uses a small journal + atomic writes to avoid partial files.
      */
     async saveNotebookBundle(notebookPath, cells, kernelName, history, session, notebookMetadata) {
+        (0, sealed_path_1.assertPathMutable)(this.normalizePath(notebookPath), { operation: 'save' });
         return await this.withWriteLock(notebookPath, async () => {
             const normalizedPath = this.normalizePath(notebookPath);
             const historyPath = history ? this.getHistoryPath(notebookPath) : undefined;
@@ -1499,6 +1586,7 @@ class FilesystemService {
      * Update notebook-level metadata without modifying cells
      */
     async updateNotebookMetadata(notebookPath, metadataUpdates) {
+        (0, sealed_path_1.assertPathMutable)(this.normalizePath(notebookPath), { operation: 'update metadata for' });
         return await this.withWriteLock(notebookPath, async () => {
             const normalizedPath = this.normalizePath(notebookPath);
             try {
@@ -1603,6 +1691,7 @@ class FilesystemService {
      * Set agent permission and ensure newly-permitted notebooks are immediately editable.
      */
     async setAgentPermission(notebookPath, permitted) {
+        (0, sealed_path_1.assertPathMutable)(this.normalizePath(notebookPath), { operation: 'change permissions for' });
         return await this.withWriteLock(notebookPath, async () => {
             const normalizedPath = this.normalizePath(notebookPath);
             if (!fs.existsSync(normalizedPath)) {
@@ -1765,6 +1854,7 @@ class FilesystemService {
      * Save operation history for a notebook
      */
     async saveHistory(notebookPath, history) {
+        (0, sealed_path_1.assertPathMutable)(this.normalizePath(notebookPath), { operation: 'write history for' });
         const historyPath = this.getHistoryPath(notebookPath);
         // Create .nebula directory if needed
         const nebulaDir = path.dirname(historyPath);
@@ -1828,6 +1918,11 @@ class FilesystemService {
      * of corrupting).
      */
     reconcileExternalTextEdits(notebookPath, history) {
+        // Reconciliation is normally a helpful read-time repair, but it persists
+        // history/last-save sidecars. A sealed snapshot must stay byte-for-byte
+        // immutable even when reached through an otherwise read-only API.
+        if ((0, sealed_path_1.classifySealedPath)(this.normalizePath(notebookPath)).sealed)
+            return history;
         const adapter = (0, registry_1.getFormatAdapter)(notebookPath);
         if (!adapter || history.length === 0)
             return history;
@@ -1942,6 +2037,7 @@ class FilesystemService {
      * Save session state for a notebook
      */
     async saveSession(notebookPath, session) {
+        (0, sealed_path_1.assertPathMutable)(this.normalizePath(notebookPath), { operation: 'write session state for' });
         const sessionPath = this.getSessionPath(notebookPath);
         // Create .nebula directory if needed
         const nebulaDir = path.dirname(sessionPath);

package/node-server/dist/fs/index.d.ts

@@ -3,3 +3,4 @@
  */
 export * from './types';
 export * from './fs-service';
+export * from './sealed-path';

package/node-server/dist/fs/index.js

@@ -19,3 +19,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
 __exportStar(require("./fs-service"), exports);
+__exportStar(require("./sealed-path"), exports);

package/node-server/dist/fs/sealed-path.d.ts

@@ -0,0 +1,41 @@
+export interface SealedPathInfo {
+    sealed: true;
+    sealId: string;
+    sealedRoot: string;
+    canonicalPath: string;
+}
+export type PathSealClassification = SealedPathInfo | {
+    sealed: false;
+};
+/**
+ * A public Nebula API attempted to mutate immutable replay evidence.
+ * ReplaySealService intentionally writes with node:fs and does not cross this
+ * public mutation boundary.
+ */
+export declare class SealedPathLockedError extends Error {
+    readonly name = "SealedPathLockedError";
+    readonly code = "sealed_read_only";
+    readonly statusCode = 403;
+    readonly sealId: string;
+    readonly lockedPath: string;
+    constructor(info: SealedPathInfo, operation?: string);
+}
+/**
+ * Derive sealed state from the filesystem path, never from caller-supplied UI
+ * mode. Both the lexical path and its resolved target are checked: a symlink
+ * cannot smuggle a write into a seal, while a symlink inside a seal cannot
+ * make its lexical entry mutable.
+ */
+export declare function classifySealedPath(filePath: string): PathSealClassification;
+/** Find a seal that a recursive delete/rename of `directory` would destroy. */
+export declare function findSealedDescendant(directory: string): SealedPathInfo | null;
+export declare function assertPathMutable(filePath: string, options?: {
+    operation?: string;
+    protectDescendants?: boolean;
+}): void;
+export declare function sealedErrorBody(error: SealedPathLockedError): {
+    code: string;
+    detail: string;
+    seal_id: string;
+    path: string;
+};

package/node-server/dist/fs/sealed-path.js

@@ -0,0 +1,228 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SealedPathLockedError = void 0;
+exports.classifySealedPath = classifySealedPath;
+exports.findSealedDescendant = findSealedDescendant;
+exports.assertPathMutable = assertPathMutable;
+exports.sealedErrorBody = sealedErrorBody;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * A public Nebula API attempted to mutate immutable replay evidence.
+ * ReplaySealService intentionally writes with node:fs and does not cross this
+ * public mutation boundary.
+ */
+class SealedPathLockedError extends Error {
+    name = 'SealedPathLockedError';
+    code = 'sealed_read_only';
+    statusCode = 403;
+    sealId;
+    lockedPath;
+    constructor(info, operation = 'modify') {
+        super(`Cannot ${operation} sealed evidence ${info.sealId}: ${info.canonicalPath}`);
+        this.sealId = info.sealId;
+        this.lockedPath = info.canonicalPath;
+    }
+}
+exports.SealedPathLockedError = SealedPathLockedError;
+function classifyAbsolutePath(absolutePath) {
+    const normalized = path.resolve(absolutePath);
+    const root = path.parse(normalized).root;
+    const components = normalized.slice(root.length).split(path.sep).filter(Boolean);
+    for (let index = 0; index <= components.length - 3; index += 1) {
+        if (components[index] !== '.nebula' || components[index + 1] !== 'seals')
+            continue;
+        const sealId = components[index + 2];
+        if (!sealId)
+            continue;
+        return {
+            sealed: true,
+            sealId,
+            sealedRoot: path.join(root, ...components.slice(0, index + 3)),
+            canonicalPath: normalized,
+        };
+    }
+    // Replay metadata outside the immutable snapshot directory is equally part
+    // of the scientific record. Public FS/notebook routes must not rewrite the
+    // hash chain, its content-addressed blobs, or durable replay job registry.
+    for (let index = 0; index < components.length; index += 1) {
+        if (components[index] !== '.nebula')
+            continue;
+        const remainder = components.slice(index + 1);
+        const isLedger = remainder.length === 1
+            && remainder[0].endsWith('.provenance.jsonl');
+        const isBlob = remainder.length >= 3
+            && remainder[0] === 'provenance'
+            && remainder[1] === 'blobs';
+        const isReplayRegistry = remainder.length >= 2
+            && remainder[0] === 'replay-seal-jobs';
+        if (!isLedger && !isBlob && !isReplayRegistry)
+            continue;
+        const evidenceId = isLedger
+            ? remainder[0]
+            : isReplayRegistry
+                ? 'replay-seal-jobs'
+                : 'provenance-blobs';
+        return {
+            sealed: true,
+            sealId: evidenceId,
+            sealedRoot: path.join(root, ...components.slice(0, index + 2)),
+            canonicalPath: normalized,
+        };
+    }
+    return { sealed: false };
+}
+/** Resolve symlinks even when the final destination does not exist yet. */
+function realpathThroughNearestExistingAncestor(absolutePath) {
+    let cursor = path.resolve(absolutePath);
+    const suffix = [];
+    while (!fs.existsSync(cursor)) {
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            return path.resolve(absolutePath);
+        suffix.unshift(path.basename(cursor));
+        cursor = parent;
+    }
+    try {
+        return path.resolve(fs.realpathSync.native(cursor), ...suffix);
+    }
+    catch {
+        return path.resolve(absolutePath);
+    }
+}
+/**
+ * Derive sealed state from the filesystem path, never from caller-supplied UI
+ * mode. Both the lexical path and its resolved target are checked: a symlink
+ * cannot smuggle a write into a seal, while a symlink inside a seal cannot
+ * make its lexical entry mutable.
+ */
+function classifySealedPath(filePath) {
+    const lexical = classifyAbsolutePath(path.resolve(filePath));
+    if (lexical.sealed)
+        return lexical;
+    return classifyAbsolutePath(realpathThroughNearestExistingAncestor(filePath));
+}
+function sealRootInDirectory(directory) {
+    const candidateRoots = path.basename(directory) === '.nebula'
+        ? [path.join(directory, 'seals')]
+        : [path.join(directory, '.nebula', 'seals')];
+    const nebulaDirectory = path.basename(directory) === '.nebula'
+        ? directory
+        : path.join(directory, '.nebula');
+    try {
+        const metadataEntries = fs.readdirSync(nebulaDirectory, { withFileTypes: true });
+        const protectedEntry = metadataEntries.find((item) => item.name.endsWith('.provenance.jsonl')
+            || item.name === 'provenance'
+            || item.name === 'replay-seal-jobs');
+        if (protectedEntry) {
+            const info = classifySealedPath(path.join(nebulaDirectory, protectedEntry.name));
+            if (info.sealed)
+                return info;
+        }
+    }
+    catch {
+        // No server-owned provenance metadata below this directory.
+    }
+    for (const sealsDir of candidateRoots) {
+        let entries;
+        try {
+            entries = fs.readdirSync(sealsDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        const entry = entries.find(item => item.name !== '.' && item.name !== '..');
+        if (!entry)
+            continue;
+        const info = classifySealedPath(path.join(sealsDir, entry.name));
+        if (info.sealed)
+            return info;
+    }
+    return null;
+}
+/** Find a seal that a recursive delete/rename of `directory` would destroy. */
+function findSealedDescendant(directory) {
+    const normalized = path.resolve(directory);
+    let stat;
+    try {
+        stat = fs.lstatSync(normalized);
+    }
+    catch {
+        return null;
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        return null;
+    const stack = [normalized];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        const direct = sealRootInDirectory(current);
+        if (direct)
+            return direct;
+        let entries;
+        try {
+            entries = fs.readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.isSymbolicLink())
+                continue;
+            if (entry.name === '.nebula')
+                continue; // Checked directly above.
+            stack.push(path.join(current, entry.name));
+        }
+    }
+    return null;
+}
+function assertPathMutable(filePath, options = {}) {
+    const info = classifySealedPath(filePath);
+    if (info.sealed)
+        throw new SealedPathLockedError(info, options.operation);
+    if (options.protectDescendants) {
+        const descendant = findSealedDescendant(filePath);
+        if (descendant)
+            throw new SealedPathLockedError(descendant, options.operation);
+    }
+}
+function sealedErrorBody(error) {
+    return {
+        code: error.code,
+        detail: error.message,
+        seal_id: error.sealId,
+        path: error.lockedPath,
+    };
+}

package/node-server/dist/fs/types.d.ts

@@ -91,8 +91,8 @@ export interface SaveNotebookResult {
 /**
  * Sentinel the client puts in place of a code cell's outputs when they are
  * unchanged since its last successful save. The server re-uses the outputs
- * already in the file (matched by nebula_id), so autosaves don't re-upload
- * megabytes of unchanged base64 images over slow uplinks.
+ * already in the file (matched by canonical Jupyter cell ID), so autosaves
+ * don't re-upload megabytes of unchanged base64 images over slow uplinks.
  */
 export declare const OUTPUTS_UNCHANGED_SENTINEL = "__nebula-outputs-unchanged-v1__";
 export interface JupyterCellMetadata {
@@ -102,6 +102,8 @@ export interface JupyterCellMetadata {
     [key: string]: unknown;
 }
 export interface JupyterCell {
+    /** Stable nbformat 4.5 cell identifier. Older notebooks may omit it. */
+    id?: string;
     cell_type: 'code' | 'markdown' | 'raw';
     source: string | string[];
     metadata: JupyterCellMetadata;

package/node-server/dist/fs/types.js

@@ -7,7 +7,7 @@ exports.OUTPUTS_UNCHANGED_SENTINEL = void 0;
 /**
  * Sentinel the client puts in place of a code cell's outputs when they are
  * unchanged since its last successful save. The server re-uses the outputs
- * already in the file (matched by nebula_id), so autosaves don't re-upload
- * megabytes of unchanged base64 images over slow uplinks.
+ * already in the file (matched by canonical Jupyter cell ID), so autosaves
+ * don't re-upload megabytes of unchanged base64 images over slow uplinks.
  */
 exports.OUTPUTS_UNCHANGED_SENTINEL = '__nebula-outputs-unchanged-v1__';

package/node-server/dist/index.js

@@ -91,6 +91,8 @@ const notebook_websocket_1 = require("./notebook/notebook-websocket");
 // Idle auto-release (client mode, opt-in via NEBULA_IDLE_EXIT_MINUTES)
 const idle_exit_1 = require("./idle-exit");
 const pty_manager_1 = require("./terminal/pty-manager");
+const bind_host_1 = require("./server/bind-host");
+const cors_origin_1 = require("./server/cors-origin");
 const PORT = process.env.PORT || process.env.NODE_SERVER_PORT || 3000;
 const DEV_MODE = process.env.DEV_MODE === 'true' || process.argv.includes('--dev');
 const BODY_LIMIT = process.env.NEBULA_BODY_LIMIT ||
@@ -138,6 +140,7 @@ const getArgValue = (name) => {
     }
     return null;
 };
+let BIND_HOST = (0, bind_host_1.resolveBindHost)(process.argv, process.env);
 const WORKDIR = getArgValue('--workdir') || process.env.NEBULA_WORKDIR || process.env.npm_config_workdir;
 const PRESERVE_KERNELS = resolveBooleanFlag(['--preserve-kernels', '--preserve-kernel'], ['--no-preserve-kernels', '--no-preserve-kernel'], ['NEBULA_PRESERVE_KERNELS'], ['npm_config_preserve_kernels'], DEV_MODE);
 const REATTACH_KERNELS = resolveBooleanFlag(['--reattach-kernels', '--reattach-kernel'], ['--no-reattach-kernels', '--no-reattach-kernel'], ['NEBULA_REATTACH_KERNELS'], ['npm_config_reattach_kernels'], DEV_MODE);
@@ -297,20 +300,19 @@ async function createApp() {
         origin: (origin, cb) => {
             if (!origin)
                 return cb(null, true); // non-browser client or same-origin
-            if (extraOrigins.includes(origin))
+            if ((0, cors_origin_1.isTrustedBrowserOrigin)(origin, extraOrigins))
                 return cb(null, true);
-            try {
-                const { hostname } = new URL(origin);
-                if (hostname === 'localhost' || hostname === '::1' || hostname === '127.0.0.1' || hostname.startsWith('127.')) {
-                    return cb(null, true);
-                }
-            }
-            catch { /* malformed Origin — treat as disallowed */ }
             cb(null, false); // no CORS headers -> browser blocks the cross-origin page
         },
         credentials: true,
         methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
-        allowedHeaders: ['Content-Type', 'Authorization', 'X-API-Key', 'X-API-Provider'],
+        allowedHeaders: [
+            'Content-Type',
+            'Authorization',
+            'X-API-Key',
+            'X-API-Provider',
+            'Idempotency-Key',
+        ],
     });
     // Register multipart support (replaces multer)
     await fastify.register(multipart_1.default, {
@@ -480,15 +482,21 @@ async function main() {
             process.exit(1);
         }
     }
-    const authDisabled = process.argv.includes('--noauth') ||
+    const explicitNoAuth = process.argv.includes('--noauth') ||
         process.argv.includes('--no-auth') ||
         process.env.NO_AUTH === 'true' ||
         process.env.NEBULA_NO_AUTH === 'true' ||
         process.env.npm_config_noauth === 'true' ||
         process.env.npm_config_noauth === '1' ||
         process.env.npm_config_no_auth === 'true' ||
-        process.env.npm_config_no_auth === '1' ||
-        CLIENT_MODE;
+        process.env.npm_config_no_auth === '1';
+    if (explicitNoAuth) {
+        // Loopback default when no host was chosen; refuses an explicit
+        // non-loopback host. Client mode is exempt: it binds the network on
+        // purpose (login node must reach it) behind the cluster secret.
+        BIND_HOST = (0, bind_host_1.resolveNoAuthBindHost)(process.argv, process.env);
+    }
+    const authDisabled = explicitNoAuth || CLIENT_MODE;
     if (authDisabled) {
         auth_2.authService.disableAuth();
         console.log(`[Auth] Disabled (${CLIENT_MODE ? 'client mode' : '--noauth'})`);
@@ -531,7 +539,7 @@ async function main() {
     // Setup static file serving
     await setupStaticServing(fastify);
     // Start HTTP server on main port
-    await fastify.listen({ port: Number(PORT), host: '0.0.0.0' });
+    await fastify.listen({ port: Number(PORT), host: BIND_HOST });
     // Get the raw Node.js server for WebSocket handling
     const server = fastify.server;
     // Setup WebSocket routing (kernel)
@@ -599,6 +607,7 @@ async function main() {
             '   Nebula Notebook is running',
             '',
             `   Open:      http://localhost:${PORT}`,
+            `   Bind:      ${BIND_HOST}:${PORT}`,
             `   Network:   http://${host}:${PORT}`,
             `   Files:     ${rootDir}`,
             `   Compute:   ${schedulerDetected