🔒 Keep the module map out of customer Wiki reads and serve only Markdown pages under wiki/

This commit is contained in:
wishforge 2026-11-08 22:46:22 -08:00
parent 4118e30872
commit 147c3e3e18
4 changed files with 106 additions and 12 deletions

View File

@ -5,6 +5,25 @@ import { requireHuman } from './policy.js';
export type WikiFile = { path: string; content: string };
export type WikiSnapshot = { version: string; files: WikiFile[]; project: Project };
/**
* Who the Wiki is being read for. Customers keep to the pages written for them: the entry page,
* the feature guides and the business glossary. The module map under `wiki/modules/` is a map of
* the codebase, so it never reaches a customer prompt, a customer answer or a customer source list.
*/
export type WikiScope = 'customer' | 'all';
const CUSTOMER_WIKI = /^wiki\/(?:index|features\/[A-Za-z0-9._-]+|glossary\/[A-Za-z0-9._-]+)\.md$/;
export const customerWikiPath = (path: string) => CUSTOMER_WIKI.test(path);
export function wikiFilesFor(scope: WikiScope, files: WikiFile[]): WikiFile[] {
return scope === 'all' ? files : files.filter(file => customerWikiPath(file.path));
}
const WIKI_PAGE = /^wiki(?:\/[A-Za-z0-9._-]+)+\.md$/;
/** A Wiki page path is one Markdown file under `wiki/`; no traversal, no escape, no extension games. */
export function assertWikiPath(value: unknown): string {
const path = typeof value === 'string' ? value.trim() : '';
if (path.length > 256 || !WIKI_PAGE.test(path) || path.split('/').includes('..'))
throw new DomainError('INVALID_WIKI_PATH', 'Use a Markdown page under wiki/, such as wiki/features/wishes.md', 400);
return path;
}
export function codeReferences(projectId: string, version: string, content: string) {
const found = new Map<string, { path: string; line?: number; url: string }>();
@ -75,13 +94,14 @@ export class ProjectWiki {
return response.json() as Promise<{ version: string; files?: WikiFile[]; file?: WikiFile }>;
}
async snapshot(actor: Actor, projectId: string): Promise<WikiSnapshot> {
async snapshot(actor: Actor, projectId: string, scope: WikiScope = 'customer'): Promise<WikiSnapshot> {
const project = await this.project(actor, projectId);
const result = await this.readRepository(project);
return { project, version: result.version, files: result.files ?? [] };
return { project, version: result.version, files: wikiFilesFor(scope, result.files ?? []) };
}
async source(actor: Actor, projectId: string, path: string, expectedVersion?: string) {
async source(actor: Actor, projectId: string, rawPath: string, expectedVersion?: string) {
const path = assertWikiPath(rawPath);
const project = await this.project(actor, projectId);
const result = await this.readRepository(project, path);
if (expectedVersion && result.version !== expectedVersion)

View File

@ -26,13 +26,20 @@ export interface GitClaims {
refPrefix?: string;
}
const REF_PREFIX = /^refs\/heads\/[A-Za-z0-9][A-Za-z0-9._-]{0,63}\/$/;
const REPOSITORY_FILE = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,255}$/;
function repositoryFile(value: unknown) {
/** Wiki pages are Markdown files under `wiki/`; nothing else in the repository is readable here. */
const WIKI_FILE = /^wiki(?:\/[A-Za-z0-9._-]+)+\.md$/;
function wikiFile(value: unknown) {
const file = String(value ?? '');
if (!REPOSITORY_FILE.test(file) || file.includes('..') || file.endsWith('/'))
throw new RuntimeError('INVALID_PATH', 'Repository file path is not safe');
if (file.length > 256 || !WIKI_FILE.test(file) || file.split('/').includes('..'))
throw new RuntimeError('INVALID_PATH', 'Use a Markdown page under wiki/, such as wiki/features/wishes.md');
return file;
}
/** `git ls-tree` reports a symbolic link or a directory; neither is a Wiki page we may serve. */
function regularBlob(entry: string) {
const [meta = ''] = entry.split('\t');
const [mode = '', type = ''] = meta.split(' ');
return mode !== '120000' && type === 'blob';
}
const gitEnv = () => ({
PATH: process.env.PATH,
LANG: 'C.UTF-8',
@ -259,18 +266,22 @@ export async function createGitService(config: GitServiceConfig) {
const branch = requireBranchName(String(body.branch ?? 'main'));
const version = (await git(repository, ['rev-parse', '--verify', `${branch}^{commit}`])).trim();
if (body.path !== undefined) {
const file = repositoryFile(body.path);
const file = wikiFile(body.path);
const entry = (await git(repository, ['ls-tree', branch, '--', file])).trim();
if (!entry) throw new RuntimeError('NOT_FOUND', 'Wiki page not found');
if (!regularBlob(entry)) throw new RuntimeError('INVALID_PATH', 'Wiki pages must be regular files');
const content = await git(repository, ['show', `${branch}:${file}`]);
if (Buffer.byteLength(content) > 512 * 1024)
throw new RuntimeError('PAYLOAD_TOO_LARGE', 'File is too large');
json(response, 200, { version, file: { path: file, content } });
return;
}
const listed = await git(repository, ['ls-tree', '-r', '--name-only', branch, '--', 'wiki']);
const listed = await git(repository, ['ls-tree', '-r', branch, '--', 'wiki']);
const paths = listed
.split('\n')
.filter(file => file.endsWith('.md'))
.slice(0, 100);
.filter(line => line.endsWith('.md') && regularBlob(line) && WIKI_FILE.test(line.split('\t').at(-1)!))
.slice(0, 100)
.map(line => line.split('\t').at(-1)!);
const files = [];
for (const file of paths) {
const content = await git(repository, ['show', `${branch}:${file}`]);

View File

@ -66,6 +66,15 @@ it('provisions a real bare repository and serves authenticated clone/CAS push ov
expect(response.status).toBe(200);
return response.json() as Promise<Record<string, string>>;
};
const reject = async (route: string, body: unknown) => {
const response = await fetch(`${base}${route}`, {
method: 'POST',
headers: { authorization: `Bearer ${admin}`, 'content-type': 'application/json' },
body: JSON.stringify(body),
});
expect(response.status).toBe(400);
return response.json() as Promise<{ error: string }>;
};
try {
const repo = await post('/repos', { tenantId: 'tenant', projectId: 'project', defaultBranch: 'release/v1' });
expect(repo.initialCommit).toMatch(/^[a-f0-9]{40}$/);
@ -89,11 +98,15 @@ it('provisions a real bare repository and serves authenticated clone/CAS push ov
});
await writeFile(path.join(checkout.workspace, 'README.md'), 'A persistent project\n');
await mkdir(path.join(checkout.workspace, 'wiki', 'features'), { recursive: true });
await mkdir(path.join(checkout.workspace, 'wiki', 'modules'), { recursive: true });
await writeFile(path.join(checkout.workspace, 'wiki', 'index.md'), '# Project Wiki\n');
await writeFile(path.join(checkout.workspace, 'wiki', 'modules', 'api.md'), '# API module\nInternal map.\n');
await writeFile(
path.join(checkout.workspace, 'wiki', 'features', 'wish.md'),
'# Wish\nSee `apps/api/src/http.ts:416`.\n',
);
// A symbolic link inside the Wiki is not a page: reading it would leave the repository.
await symlink('../../../README.md', path.join(checkout.workspace, 'wiki', 'features', 'link.md'));
const checkpoint = await git.checkpoint(checkout.workspace, checkout.baseCommit, 'run', 'test');
const push = {
repository: checkout.workspace,
@ -114,7 +127,8 @@ it('provisions a real bare repository and serves authenticated clone/CAS push ov
expect(second.baseCommit).toBe(checkpoint.sourceCommit);
const wiki = await post('/wiki', { tenantId: 'tenant', projectId: 'project', branch: 'release/v1' });
expect(wiki.version).toBe(checkpoint.sourceCommit);
expect(wiki.files).toHaveLength(2);
expect(wiki.files).toHaveLength(3);
expect(JSON.stringify(wiki.files)).not.toContain('link.md');
const source = await post('/wiki', {
tenantId: 'tenant',
projectId: 'project',
@ -125,6 +139,11 @@ it('provisions a real bare repository and serves authenticated clone/CAS push ov
path: 'wiki/features/wish.md',
content: expect.stringContaining('apps/api/src/http.ts:416'),
});
// Only Markdown pages under wiki/ are readable, and never through a symbolic link.
for (const unsafe of ['wiki/features/link.md', 'wiki/../README.md', 'README.md', 'wiki/features/wish.txt'])
expect(
await reject('/wiki', { tenantId: 'tenant', projectId: 'project', branch: 'release/v1', path: unsafe }),
).toMatchObject({ error: 'INVALID_PATH' });
const afterPush = await post('/repos', { tenantId: 'tenant', projectId: 'project', defaultBranch: 'other' });
expect(afterPush.defaultBranch).toBe('release/v1');
expect(afterPush.initialCommit).toBe(checkpoint.sourceCommit);

View File

@ -26,6 +26,9 @@ const files = [
path: 'wiki/features/wishes.md',
content: '# 提交 Wish\n填写目标和验收标准。\n依据 `apps/web/src/features/runs.tsx:416`。',
},
{ path: 'wiki/glossary/terms.md', content: '# 术语\n愿望是一次改动请求。' },
// The module map is a map of the codebase: it must never reach a customer prompt or answer.
{ path: 'wiki/modules/api.md', content: '# API 模块\n内部代码地图,客户不可见。' },
];
beforeEach(async () => {
store = new MemoryStore();
@ -211,6 +214,47 @@ describe('project Copilot API', () => {
});
});
it('keeps the internal module map out of customer retrieval, prompts and sources', async () => {
const prompts: string[] = [];
const service = new Copilot(
control,
env,
async request => {
prompts.push(request.prompt);
return { kind: 'faq', answer: '在项目页面填写目标和验收标准后提交。' };
},
wiki,
);
const session = await service.createSession(owner, projectId);
const answered = await service.ask(owner, projectId, session.id, input('提交 Wish 要求什么'));
expect(prompts.join('\n')).not.toContain('wiki/modules');
expect(JSON.stringify(answered)).not.toContain('wiki/modules');
});
it('serves customers only the entry page, feature guides and glossary, and refuses unsafe paths', async () => {
await store.transaction('demo', async tx => {
await tx.put('project', { ...snapshot, repositoryStorage: 'platform', repositoryStatus: 'ready' });
});
const service = new ProjectWiki(
store,
{ ...env, WF_GIT_SERVICE_URL: 'https://git.example', WF_GIT_ADMIN_TOKEN: 'server-side-fixture' },
async () =>
new Response(JSON.stringify({ version: 'c'.repeat(40), files }), {
status: 200,
headers: { 'Content-Type': 'application/json' },
}),
);
const customer = await service.snapshot(owner, projectId);
expect(customer.files.map(file => file.path)).toEqual([
'wiki/index.md',
'wiki/features/wishes.md',
'wiki/glossary/terms.md',
]);
expect((await service.snapshot(owner, projectId, 'all')).files).toHaveLength(4);
for (const unsafe of ['wiki/../README.md', '/etc/passwd', 'wiki/features/wish.txt', 'apps/api/src/http.ts'])
await expect(service.source(owner, projectId, unsafe)).rejects.toMatchObject({ code: 'INVALID_WIKI_PATH' });
});
it('enforces project access and rejects a stale Wiki version at the source API', async () => {
await store.transaction('demo', async tx => {
await tx.put('project', { ...snapshot, repositoryStorage: 'platform', repositoryStatus: 'ready' });