fix(html-view): address review — scope, source view, tests, docs

- Refuse to mint for an HTML file in a hidden directory or directly in a
  broad root (/, home, tmpdir, cases and user-space roots): the capability
  serves the directory tree recursively to the page's own scripts.
- Keep HTML's source view and editor: a Page pill (per-device htmlRendered,
  like MD) toggles to the file-content text path, and a refused mint (remote
  case, broad root, hidden dir) falls through to it automatically.
- Tests: html-view auth exemption edges, revocation on logout / admin logout /
  user deletion, out-of-workspace mint (blocked tree, confinement), hidden
  and broad roots.
- Docs: Working-With-Files, architecture-invariants, security-architecture,
  the file-routes comment and CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
stefaan van hoofandClaude Opus 5.5 committed 2026-10-08 09:21:55 +02:00
1 parent 56978f2cc9
commit 91bdaee724
11 files changed
+275 -27

No files matched your search

+68 -2
View File
@@ -8,10 +8,10 @@
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { homedir, tmpdir } from 'node:os';
import { join } from 'node:path';
import { createRouteTestHarness, type RouteTestHarness } from './_route-test-utils.js';
import { registerHtmlViewRoutes } from '../../src/web/routes/html-view-routes.js';
import { isBroadHtmlViewRoot, registerHtmlViewRoutes } from '../../src/web/routes/html-view-routes.js';
import { capabilityFromHtmlViewPath, htmlViewCapabilities } from '../../src/html-view-capabilities.js';
describe('html-view routes', () => {
@@ -106,4 +106,70 @@ describe('html-view routes', () => {
it('reuses one capability per directory', async () => {
expect(await openUrl()).toBe(await openUrl());
});
describe('outside the workspace', () => {
let outsideDir: string;
const saved = {
confine: process.env.CODEMAN_ATTACHMENT_CONFINE,
blocked: process.env.CODEMAN_ATTACHMENT_BLOCKED_PATHS,
};
beforeEach(() => {
outsideDir = join(root, 'reports');
mkdirSync(outsideDir);
writeFileSync(join(outsideDir, 'report.html'), '<p>report</p>');
});
afterEach(() => {
for (const [key, value] of [
['CODEMAN_ATTACHMENT_CONFINE', saved.confine],
['CODEMAN_ATTACHMENT_BLOCKED_PATHS', saved.blocked],
] as const) {
if (value === undefined) delete process.env[key];
else process.env[key] = value;
}
});
it('mints for a page under the attachment guard', async () => {
expect((await open(join(outsideDir, 'report.html'))).statusCode).toBe(200);
});
it('refuses a page in a blocked tree', async () => {
process.env.CODEMAN_ATTACHMENT_BLOCKED_PATHS = outsideDir;
expect((await open(join(outsideDir, 'report.html'))).statusCode).toBe(403);
});
it('refuses every out-of-workspace page when attachments are confined to the workspace', async () => {
process.env.CODEMAN_ATTACHMENT_CONFINE = '1';
expect((await open(join(outsideDir, 'report.html'))).statusCode).toBe(403);
// The workspace itself is still fine.
expect((await open(join(workspace, 'index.html'))).statusCode).toBe(200);
});
});
it('refuses an HTML file inside a hidden directory, in or out of the workspace', async () => {
mkdirSync(join(workspace, '.cache'));
writeFileSync(join(workspace, '.cache', 'r.html'), '<p>r</p>');
writeFileSync(join(workspace, '.cache', 'token.json'), '{}');
expect((await open(join(workspace, '.cache', 'r.html'))).statusCode).toBe(403);
mkdirSync(join(root, '.hidden'));
writeFileSync(join(root, '.hidden', 'r.html'), '<p>r</p>');
expect((await open(join(root, '.hidden', 'r.html'))).statusCode).toBe(403);
});
it('treats the filesystem root, home and the temp dir as too broad to serve', () => {
expect(isBroadHtmlViewRoot('/')).toBe(true);
expect(isBroadHtmlViewRoot(homedir())).toBe(true);
expect(isBroadHtmlViewRoot(tmpdir())).toBe(true);
expect(isBroadHtmlViewRoot(workspace)).toBe(false);
});
it('refuses a page sitting directly in the temp dir', async () => {
const page = join(tmpdir(), `html-view-broad-${process.pid}.html`);
writeFileSync(page, '<p>broad</p>');
try {
expect((await open(page)).statusCode).toBe(403);
} finally {
rmSync(page, { force: true });
}
});
});