feat(passwords): open password-protected docx (#2547)

* feat(passwords): open pssword protected docx

* fix(passwords): wire decrypted bytes through editor init, replaceFile, and type surface

* chore: fix types

* fix(passwords): add doc.open password to agentVisible allowlist and fix lint

Author: harbournick

apps/cli/README.md

@@ -41,6 +41,27 @@ superdoc save --in-place
 superdoc close
 ```
 
+## Encrypted Documents
+
+Open password-protected `.docx` files with `--password` or the `SUPERDOC_DOC_PASSWORD` env var:
+
+```bash
+# Explicit flag
+superdoc open ./secret.docx --password 'mypassword'
+
+# Env var (preferred — avoids password in process listings)
+SUPERDOC_DOC_PASSWORD='mypassword' superdoc open ./secret.docx
+
+# Via call
+superdoc call doc.open --input-json '{"doc":"./secret.docx","password":"mypassword"}'
+```
+
+If the password is missing or incorrect, the CLI returns a structured error with one of these codes:
+- `DOCX_PASSWORD_REQUIRED` — encrypted file, no password supplied
+- `DOCX_PASSWORD_INVALID` — wrong password
+- `DOCX_ENCRYPTION_UNSUPPORTED` — recognized but unsupported encryption method
+- `DOCX_DECRYPTION_FAILED` — crypto failure or corrupt data
+
 ## Choosing the Right Command
 
 ### Which command should I use?

apps/cli/src/__tests__/cli.test.ts

@@ -56,7 +56,13 @@ const TEST_DIR = join(import.meta.dir, 'fixtures-cli');
 const STATE_DIR = join(TEST_DIR, 'state');
 const SAMPLE_DOC = join(TEST_DIR, 'sample.docx');
 const LIST_SAMPLE_DOC = join(TEST_DIR, 'lists-sample.docx');
+const ENCRYPTED_DOC = join(TEST_DIR, 'encrypted.docx');
 const CLI_PACKAGE_JSON_PATH = join(import.meta.dir, '../../package.json');
+const REPO_ROOT = join(import.meta.dir, '../../../..');
+const ENCRYPTED_FIXTURE_SOURCE = join(
+  REPO_ROOT,
+  'packages/super-editor/src/core/ooxml-encryption/fixtures/encrypted-advanced-text.docx',
+);
 
 async function readCliPackageVersion(): Promise<string> {
   const raw = await readFile(CLI_PACKAGE_JSON_PATH, 'utf8');
@@ -205,6 +211,7 @@ describe('superdoc CLI', () => {
     await mkdir(TEST_DIR, { recursive: true });
     await copyFile(await resolveSourceDocFixture(), SAMPLE_DOC);
     await copyFile(await resolveListDocFixture(), LIST_SAMPLE_DOC);
+    await copyFile(ENCRYPTED_FIXTURE_SOURCE, ENCRYPTED_DOC);
     cliPackageVersion = await readCliPackageVersion();
   });
 
@@ -2379,4 +2386,87 @@ describe('superdoc CLI', () => {
     const closeResult = await runCli(['close', '--discard']);
     expect(closeResult.code).toBe(0);
   });
+
+  // -- Encrypted document tests -----------------------------------------------
+
+  // Encrypted tests use 30s timeout — decryption + open is ~4s and can exceed
+  // bun's default 5s budget under full-suite load.
+  test('open encrypted doc with --password succeeds end-to-end', async () => {
+    const result = await runCli(['open', ENCRYPTED_DOC, '--password', 'test123']);
+    expect(result.code).toBe(0);
+
+    const envelope = parseJsonOutput<SuccessEnvelope<{ active: boolean }>>(result);
+    expect(envelope.data.active).toBe(true);
+
+    const closeResult = await runCli(['close', '--discard']);
+    expect(closeResult.code).toBe(0);
+  }, 30_000);
+
+  test('open encrypted doc without password returns DOCX_PASSWORD_REQUIRED', async () => {
+    const result = await runCli(['open', ENCRYPTED_DOC]);
+    expect(result.code).toBe(1);
+
+    const envelope = parseJsonOutput<ErrorEnvelope>(result);
+    expect(envelope.error.code).toBe('DOCX_PASSWORD_REQUIRED');
+  }, 30_000);
+
+  test('open encrypted doc with wrong password returns DOCX_PASSWORD_INVALID', async () => {
+    const result = await runCli(['open', ENCRYPTED_DOC, '--password', 'wrong']);
+    expect(result.code).toBe(1);
+
+    const envelope = parseJsonOutput<ErrorEnvelope>(result);
+    expect(envelope.error.code).toBe('DOCX_PASSWORD_INVALID');
+  }, 30_000);
+
+  test('call doc.open with --input-json password succeeds end-to-end', async () => {
+    const input = JSON.stringify({ doc: ENCRYPTED_DOC, password: 'test123' });
+    const result = await runCli(['call', 'doc.open', '--input-json', input]);
+    expect(result.code).toBe(0);
+
+    const closeResult = await runCli(['close', '--discard']);
+    expect(closeResult.code).toBe(0);
+  }, 30_000);
+
+  test('call doc.open with missing password returns DOCX_PASSWORD_REQUIRED', async () => {
+    const input = JSON.stringify({ doc: ENCRYPTED_DOC });
+    const result = await runCli(['call', 'doc.open', '--input-json', input]);
+    expect(result.code).toBe(1);
+
+    const envelope = parseJsonOutput<ErrorEnvelope>(result);
+    expect(envelope.error.code).toBe('DOCX_PASSWORD_REQUIRED');
+  }, 30_000);
+
+  // -- Env-fallback precedence tests ------------------------------------------
+
+  test('SUPERDOC_DOC_PASSWORD env var is used in direct CLI mode', async () => {
+    const prevEnv = process.env.SUPERDOC_DOC_PASSWORD;
+    try {
+      process.env.SUPERDOC_DOC_PASSWORD = 'test123';
+      // No --password flag — should fall back to env var in direct mode
+      const result = await runCli(['open', ENCRYPTED_DOC]);
+      expect(result.code).toBe(0);
+
+      const closeResult = await runCli(['close', '--discard']);
+      expect(closeResult.code).toBe(0);
+    } finally {
+      if (prevEnv != null) process.env.SUPERDOC_DOC_PASSWORD = prevEnv;
+      else delete process.env.SUPERDOC_DOC_PASSWORD;
+    }
+  }, 30_000);
+
+  test('explicit --password takes precedence over SUPERDOC_DOC_PASSWORD env var', async () => {
+    const prevEnv = process.env.SUPERDOC_DOC_PASSWORD;
+    try {
+      process.env.SUPERDOC_DOC_PASSWORD = 'wrong-env-password';
+      // Explicit password should override the (wrong) env password
+      const result = await runCli(['open', ENCRYPTED_DOC, '--password', 'test123']);
+      expect(result.code).toBe(0);
+
+      const closeResult = await runCli(['close', '--discard']);
+      expect(closeResult.code).toBe(0);
+    } finally {
+      if (prevEnv != null) process.env.SUPERDOC_DOC_PASSWORD = prevEnv;
+      else delete process.env.SUPERDOC_DOC_PASSWORD;
+    }
+  }, 30_000);
 });

apps/cli/src/__tests__/lib/_collab-password-worker.ts

@@ -0,0 +1,114 @@
+/**
+ * Subprocess worker for the collab password forwarding test.
+ * Runs in isolation so mock.module doesn't leak across test files.
+ */
+import { mock } from 'bun:test';
+
+// Track what gets passed to Editor.open
+let editorOpenCalled = false;
+let capturedPassword: string | undefined;
+
+const MockEditor = {
+  open: mock(async (_source: unknown, options: Record<string, unknown> = {}) => {
+    editorOpenCalled = true;
+    capturedPassword = options.password as string | undefined;
+    return {
+      destroy: () => {},
+      exportDocument: async () => new Uint8Array(),
+    };
+  }),
+};
+
+mock.module('superdoc/super-editor', () => ({
+  Editor: MockEditor,
+  BLANK_DOCX_BASE64: '',
+  DocxEncryptionError: class DocxEncryptionError extends Error {
+    code: string;
+    constructor(code: string, message: string) {
+      super(message);
+      this.code = code;
+    }
+  },
+  getDocumentApiAdapters: () => ({}),
+  markdownToPmDoc: () => null,
+  initPartsRuntime: () => ({ dispose: () => {} }),
+}));
+
+mock.module('happy-dom', () => ({
+  Window: class {
+    document = {
+      createElement: () => ({}),
+      body: { appendChild: () => {}, innerHTML: '' },
+    };
+    close() {}
+  },
+}));
+
+const mockYArray = { observe: () => {}, toArray: () => [], toJSON: () => [], length: 0 };
+const mockYMap = { observe: () => {}, get: () => undefined, set: () => {} };
+const mockYDoc = {
+  getXmlFragment: () => ({ toArray: () => [] }),
+  getArray: () => mockYArray,
+  getMap: () => mockYMap,
+  transact: (fn: () => void) => fn(),
+};
+
+mock.module('../../lib/collaboration', () => ({
+  createCollaborationRuntime: () => ({
+    waitForSync: async () => {},
+    ydoc: mockYDoc,
+    provider: { destroy: () => {} },
+    dispose: () => {},
+  }),
+}));
+
+mock.module('../../lib/bootstrap', () => ({
+  DEFAULT_BOOTSTRAP_SETTLING_MS: 0,
+  waitForContentSettling: async () => {},
+  detectRoomState: () => 'empty' as const,
+  resolveBootstrapDecision: () => ({ action: 'seed' as const, source: 'doc' as const }),
+  claimBootstrap: async () => ({ granted: true }),
+  clearBootstrapMarker: () => {},
+  writeBootstrapMarker: () => {},
+  detectBootstrapRace: async () => ({ raceDetected: false }),
+}));
+
+async function main() {
+  const { openCollaborativeDocument } = await import('../../lib/document');
+  const { join } = await import('path');
+
+  const repoRoot = join(import.meta.dir, '../../../../..');
+  const encryptedDoc = join(
+    repoRoot,
+    'packages/super-editor/src/core/ooxml-encryption/fixtures/encrypted-advanced-text.docx',
+  );
+
+  const io = {
+    stdout: () => {},
+    stderr: () => {},
+    readStdinBytes: async () => new Uint8Array(),
+  };
+
+  const profile = {
+    documentId: 'test-doc-id',
+    serverUrl: 'ws://localhost:1234',
+  };
+
+  try {
+    // Pass a real encrypted file path to exercise the file-backed seed branch:
+    // openCollaborativeDocument → shouldSeed=true → docForEditor=encryptedDoc
+    // → openDocument(encryptedDoc, ...) → Editor.open(buffer, { password })
+    await openCollaborativeDocument(encryptedDoc, io, profile, {
+      editorOpenOptions: { password: 'collab-test-secret' },
+    });
+  } catch {
+    // May fail on export or other subsystem — we only care about Editor.open call
+  }
+
+  console.log(JSON.stringify({ editorOpenCalled, capturedPassword }));
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

apps/cli/src/__tests__/lib/collab-password-forwarding.test.ts

@@ -0,0 +1,34 @@
+/**
+ * Verifies that `openCollaborativeDocument` forwards
+ * `editorOpenOptions.password` through to the inner `openDocument` → `Editor.open()` call
+ * when seeding from an encrypted source document.
+ *
+ * This test runs in a subprocess to avoid `mock.module` side effects
+ * contaminating other test files in the same bun process.
+ */
+import { describe, test, expect } from 'bun:test';
+import { join } from 'path';
+
+const WORKER_SCRIPT = join(import.meta.dir, '_collab-password-worker.ts');
+
+describe('openCollaborativeDocument password forwarding', () => {
+  test('password reaches Editor.open() through the collaboration seed path', async () => {
+    const proc = Bun.spawn(['bun', 'run', WORKER_SCRIPT], {
+      cwd: join(import.meta.dir, '../../..'),
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+
+    const exitCode = await proc.exited;
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+
+    if (exitCode !== 0) {
+      throw new Error(`Worker failed (code ${exitCode}):\n${stderr || stdout}`);
+    }
+
+    const result = JSON.parse(stdout.trim());
+    expect(result.editorOpenCalled).toBe(true);
+    expect(result.capturedPassword).toBe('collab-test-secret');
+  });
+});

apps/cli/src/__tests__/lib/host-mode-env-suppression.test.ts

@@ -0,0 +1,87 @@
+/**
+ * Verifies that host mode (SDK-driven) suppresses the SUPERDOC_DOC_PASSWORD
+ * env fallback. Uses `invokeCommand()` — the real programmatic entry point
+ * with proper stateDir and executionMode wiring.
+ */
+import { describe, test, expect, afterEach, beforeAll } from 'bun:test';
+import { invokeCommand } from '../../index';
+import { CliError } from '../../lib/errors';
+import { join } from 'path';
+import { mkdtemp, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+
+const REPO_ROOT = join(import.meta.dir, '../../../../..');
+const ENCRYPTED_DOC = join(
+  REPO_ROOT,
+  'packages/super-editor/src/core/ooxml-encryption/fixtures/encrypted-advanced-text.docx',
+);
+
+const silentIo = {
+  stdout: () => {},
+  stderr: () => {},
+  readStdinBytes: async () => new Uint8Array(),
+};
+
+let testStateDir: string;
+
+beforeAll(async () => {
+  testStateDir = await mkdtemp(join(tmpdir(), 'superdoc-host-test-'));
+});
+
+afterEach(async () => {
+  await rm(testStateDir, { recursive: true, force: true });
+  testStateDir = await mkdtemp(join(tmpdir(), 'superdoc-host-test-'));
+});
+
+/** Call invokeCommand, catching CliErrors into a result object. */
+async function invokeExpectingResult(argv: string[], executionMode: 'oneshot' | 'host', stateDir: string) {
+  try {
+    const result = await invokeCommand(argv, {
+      stateDir,
+      executionMode,
+      ioOverrides: silentIo,
+    });
+    return { code: result.execution?.code ?? 0, error: null };
+  } catch (e) {
+    if (e instanceof CliError) {
+      return { code: 1, error: { code: e.code, message: e.message } };
+    }
+    throw e;
+  }
+}
+
+describe('host-mode env-fallback suppression', () => {
+  const prevEnv = process.env.SUPERDOC_DOC_PASSWORD;
+
+  afterEach(() => {
+    if (prevEnv != null) process.env.SUPERDOC_DOC_PASSWORD = prevEnv;
+    else delete process.env.SUPERDOC_DOC_PASSWORD;
+  });
+
+  test('env password is suppressed in host mode, returning DOCX_PASSWORD_REQUIRED', async () => {
+    process.env.SUPERDOC_DOC_PASSWORD = 'test123';
+
+    const result = await invokeExpectingResult(['open', ENCRYPTED_DOC], 'host', testStateDir);
+
+    expect(result.code).toBe(1);
+    expect(result.error).not.toBeNull();
+    expect(result.error!.code).toBe('DOCX_PASSWORD_REQUIRED');
+  }, 30_000);
+
+  test('env password IS used in direct CLI mode (oneshot)', async () => {
+    process.env.SUPERDOC_DOC_PASSWORD = 'test123';
+
+    const result = await invokeExpectingResult(['open', ENCRYPTED_DOC], 'oneshot', testStateDir);
+
+    // If it failed, the error must NOT be a password error.
+    if (result.code !== 0) {
+      expect(result.error?.code).not.toBe('DOCX_PASSWORD_REQUIRED');
+      expect(result.error?.code).not.toBe('DOCX_PASSWORD_INVALID');
+    }
+
+    // Clean up if open succeeded
+    if (result.code === 0) {
+      await invokeExpectingResult(['close', '--discard'], 'oneshot', testStateDir);
+    }
+  }, 30_000);
+});