From 5c89d27528dd8bb175d52b72e26c022d1d474997 Mon Sep 17 00:00:00 2001 From: Codex Bot Date: Thu, 29 Oct 2026 17:03:55 +0800 Subject: [PATCH] Harden XML round trips, author namespaces and publishing feedback --- apps/waterfall-wiki/db/015_guidance_documents.sql | 2 +- apps/waterfall-wiki/src/content/guides/catalog.ts | 2 +- apps/waterfall-wiki/src/lib/guidance-input.ts | 15 +++++++++------ apps/waterfall-wiki/src/lib/guidance-store.ts | 2 +- .../src/pages/api/documents/[[...path]].ts | 3 ++- apps/waterfall-wiki/src/pages/documents/[id].tsx | 2 +- apps/waterfall-wiki/src/pages/write.tsx | 12 ++++++++---- apps/waterfall-wiki/tests/guidance-integration.ts | 6 ++++-- .../tests/guidance-publishing.test.ts | 4 ++++ docs/linked-guidance/protocol.md | 2 +- docs/linked-guidance/publishing.md | 6 ++++-- 11 files changed, 36 insertions(+), 20 deletions(-) diff --git a/apps/waterfall-wiki/db/015_guidance_documents.sql b/apps/waterfall-wiki/db/015_guidance_documents.sql index e20ce10..ea23d9d 100644 --- a/apps/waterfall-wiki/db/015_guidance_documents.sql +++ b/apps/waterfall-wiki/db/015_guidance_documents.sql @@ -1,5 +1,5 @@ BEGIN; -CREATE TABLE guidance_documents(id text PRIMARY KEY CHECK(id ~ '^user-[a-z0-9-]{1,74}$'), owner_id uuid NOT NULL REFERENCES account_users(id), latest integer NOT NULL DEFAULT 0, deleted_at timestamptz); +CREATE TABLE guidance_documents(id text PRIMARY KEY CHECK(id ~ '^user-[a-z0-9-]{1,74}$'), owner_id uuid NOT NULL REFERENCES account_users(id), latest integer NOT NULL DEFAULT 0, deleted_at timestamptz, CHECK(id LIKE 'user-' || owner_id::text || '-%')); CREATE TABLE guidance_revisions(document_id text NOT NULL REFERENCES guidance_documents(id), revision integer NOT NULL CHECK(revision>0), content jsonb NOT NULL, created_at timestamptz NOT NULL DEFAULT now(), PRIMARY KEY(document_id,revision)); CREATE FUNCTION guidance_immutable() RETURNS trigger LANGUAGE plpgsql AS $$ BEGIN RAISE EXCEPTION 'Published revisions are immutable'; END $$; CREATE TRIGGER guidance_immutable BEFORE UPDATE OR DELETE ON guidance_revisions FOR EACH ROW EXECUTE FUNCTION guidance_immutable(); diff --git a/apps/waterfall-wiki/src/content/guides/catalog.ts b/apps/waterfall-wiki/src/content/guides/catalog.ts index c172aee..f58e68b 100644 --- a/apps/waterfall-wiki/src/content/guides/catalog.ts +++ b/apps/waterfall-wiki/src/content/guides/catalog.ts @@ -7,4 +7,4 @@ export const guides:Guidance[]=[ ]; export function findGuide(id:string,revision?:number){return guides.find(g=>g.id===id&&(revision===undefined||g.revision===revision));} const esc=(s:string)=>s.replace(/[<>&"']/g,c=>({'<':'<','>':'>','&':'&','"':'"',"'":'''}[c]!)); -export function guidanceXml(g:Guidance){const t=(tag:string,s:string)=>` <${tag}>${esc(s)}`;return `\n\n${[t('title',g.title),t('summary',g.summary),t('applies',g.applies),t('body',g.body),...g.steps.map(s=>t('step',s)),...g.links.map(l=>` ${esc(l.label)}`),...g.checks.map(s=>t('check',s))].join('\n')}\n\n`;} +export function guidanceXml(g:Guidance){const t=(tag:string,s:string)=>` <${tag}>${esc(s)}`;return `\n\n${[t('title',g.title),t('summary',g.summary),t('applies',g.applies),t('body',g.body),...g.steps.map(s=>t('step',s)),...g.links.map(l=>` ${esc(l.label)}`),...g.checks.map(s=>t('check',s)),...g.tags.map(s=>t('tag',s))].join('\n')}\n\n`;} diff --git a/apps/waterfall-wiki/src/lib/guidance-input.ts b/apps/waterfall-wiki/src/lib/guidance-input.ts index da7993f..fbadc6c 100644 --- a/apps/waterfall-wiki/src/lib/guidance-input.ts +++ b/apps/waterfall-wiki/src/lib/guidance-input.ts @@ -1,19 +1,22 @@ import { z } from 'zod'; const kind=z.enum(['guide','context','evidence']); -const text=z.string().trim().min(1).max(20000).refine(s=>!/[\u0000-\u0008\u000b\u000c\u000e-\u001f\ufffe\uffff]/.test(s),'非法 XML 字符'); +export const validXmlText=(value:string)=>!/[\u0000-\u0008\u000b\u000c\u000e-\u001f\ufffe\uffff]/.test(value)&&!/[\ud800-\udfff]/u.test(value); +const text=z.string().refine(validXmlText,'非法 XML 字符').trim().min(1).max(20000); export const documentInput=z.object({id:z.string().regex(/^user-[a-z0-9-]{1,74}$/),revision:z.number().int().min(1).max(2147483647),kind,title:text.max(200),summary:text.max(1000),applies:text,body:text,steps:z.array(text).max(100),checks:z.array(text).max(100),links:z.array(z.object({target:z.string().regex(/^[a-z0-9-]{1,79}$/),revision:z.number().int().min(1).max(2147483647),relation:kind,when:text.max(1000),label:text.max(200)}).strict()).max(100),tags:z.array(text.max(80)).max(20)}).strict(); // Deliberately narrow XML 1.0 grammar: no DTD, comments, CDATA, nested markup or arbitrary entities. export function parseDocumentXml(source:string){ + if(!validXmlText(source)||source.includes(']]>'))throw Error('非法 XML 字符'); if(Buffer.byteLength(source)>131072)throw Error('XML 过大'); - let s=source.replace(/^<\?xml version="1.0" encoding="UTF-8"\?>\s*/, ''); + const trimXml=(v:string)=>v.replace(/^[ \t\r\n]+|[ \t\r\n]+$/g,''); + let s=source.replace(/^<\?xml version="1.0" encoding="UTF-8"\?>[ \t\r\n]*/, ''); if(/<\?|{if(/&(?!amp;|lt;|gt;|quot;|apos;)/.test(v))throw Error('非法实体');return v.replace(/&(amp|lt|gt|quot|apos);/g,(_,k)=>({amp:'&',lt:'<',gt:'>',quot:'"',apos:"'"}[k as 'amp'|'lt'|'gt'|'quot'|'apos'] as string));}; - const attrs=(v:string)=>{const result:Record={};while(v.trim()){const m=/^\s+([a-z]+)="([^"<]*)"/.exec(v);if(!m||m[1] in result)throw Error('非法或重复属性');result[m[1]]=decode(m[2]);v=v.slice(m[0].length);}return result;}; - const root=/^]*)>([\s\S]*)<\/guidance>\s*$/.exec(s);if(!root)throw Error('非法根元素');const a=attrs(root[1]); + const attrs=(v:string)=>{const result:Record={};while(trimXml(v)){const m=/^[ \t\r\n]+([a-z]+)="([^"<]*)"/.exec(v);if(!m||m[1] in result)throw Error('非法或重复属性');result[m[1]]=decode(m[2]);v=v.slice(m[0].length);}return result;}; + const root=/^([\s\S]*)<\/guidance>[ \t\r\n]*$/.exec(s);if(!root)throw Error('非法根元素');const a=attrs(root[1]); if(Object.keys(a).sort().join(',')!=='id,kind,lang,revision,xmlns'||a.xmlns!=='urn:linked-guidance:0.1'||a.lang!=='zh-CN'||! /^[1-9][0-9]*$/.test(a.revision))throw Error('不支持的协议或属性'); const result:Record={id:a.id,kind:a.kind,revision:Number(a.revision),steps:[],checks:[],links:[],tags:[]};s=root[2]; - while(s.trim()){const m=/^\s*<(title|summary|applies|body|step|check|link)([^>]*)>([^<]*)<\/\1>/.exec(s);if(!m)throw Error('非法子元素');const [,tag,raw,value]=m;const at=attrs(raw);const v=decode(value); + while(trimXml(s)){const m=/^[ \t\r\n]*<(title|summary|applies|body|step|check|tag|link)((?:[ \t\r\n]+[a-z]+="[^"<]*")*[ \t\r\n]*)>([^<]*)<\/\1>/.exec(s);if(!m)throw Error('非法子元素');const [,tag,raw,value]=m;const at=attrs(raw);const v=decode(value); if(tag==='link'){if(Object.keys(at).sort().join(',')!=='relation,revision,target,when'||! /^[1-9][0-9]*$/.test(at.revision))throw Error('非法链接');(result.links as unknown[]).push({...at,revision:Number(at.revision),label:v});} - else {if(Object.keys(at).length)throw Error('非法属性');if(tag==='step'||tag==='check')(result[tag==='step'?'steps':'checks'] as string[]).push(v);else{if(tag in result)throw Error('重复元素');result[tag]=v;}}s=s.slice(m[0].length);} + else {if(Object.keys(at).length)throw Error('非法属性');if(tag==='step'||tag==='check'||tag==='tag')(result[tag==='step'?'steps':tag==='tag'?'tags':'checks'] as string[]).push(v);else{if(tag in result)throw Error('重复元素');result[tag]=v;}}s=s.slice(m[0].length);} return documentInput.parse(result); } diff --git a/apps/waterfall-wiki/src/lib/guidance-store.ts b/apps/waterfall-wiki/src/lib/guidance-store.ts index a792f6d..590d37a 100644 --- a/apps/waterfall-wiki/src/lib/guidance-store.ts +++ b/apps/waterfall-wiki/src/lib/guidance-store.ts @@ -5,7 +5,7 @@ export async function resolveDocument(id:string,revision?:number):Promise{ +export async function publishDocument(owner:string,value:unknown){const content=documentInput.parse(value);if(!content.id.startsWith('user-'+owner+'-'))throw Error('INVALID_ID');return transaction(async c=>{ await c.query('INSERT INTO guidance_documents(id,owner_id) VALUES($1,$2) ON CONFLICT DO NOTHING',[content.id,owner]); const d=(await c.query('SELECT * FROM guidance_documents WHERE id=$1 FOR UPDATE',[content.id])).rows[0]; if(d.owner_id!==owner)throw Error('FORBIDDEN');if(d.deleted_at||content.revision!==d.latest+1)throw Error('CONFLICT'); diff --git a/apps/waterfall-wiki/src/pages/api/documents/[[...path]].ts b/apps/waterfall-wiki/src/pages/api/documents/[[...path]].ts index 4dcb7f1..26e03b7 100644 --- a/apps/waterfall-wiki/src/pages/api/documents/[[...path]].ts +++ b/apps/waterfall-wiki/src/pages/api/documents/[[...path]].ts @@ -1,3 +1,4 @@ +import { ZodError } from 'zod'; import type { NextApiRequest,NextApiResponse } from 'next'; import { currentAccount } from '@/lib/account'; import { trustedOrigin } from '@/lib/account-crypto'; @@ -21,6 +22,6 @@ export default async function handler(req:NextApiRequest,res:NextApiResponse){ if(id==='preview'){const links=await Promise.all(input.links.map(async l=>({...l,resolved:!!await resolveDocument(l.target,l.revision)})));return res.json({document:input,xml:guidanceXml(input),links});} if(id&&id!==input.id)return res.status(400).json({error:'文档 ID 不匹配'}); return res.status(201).json({document:await publishDocument(user.id,input)}); - }catch(e){const message=e instanceof Error?e.message:'';if(message==='FORBIDDEN')return res.status(403).json({error:'仅作者可编辑'});if(message==='CONFLICT'||(e as {code?:string}).code==='23505')return res.status(409).json({error:'版本冲突:请加载最新版本,已发布版本不可修改'});if(e instanceof Error&&(e.name==='ZodError'||/XML|实体|元素|属性|协议|链接/.test(message)))return res.status(400).json({error:'输入不符合协议'});return res.status(503).json({error:'文档服务暂不可用'});} + }catch(e){if(e instanceof ZodError)return res.status(400).json({error:'输入不符合协议,请检查以下字段',fields:e.issues.slice(0,12).map(i=>i.path.join('.')||'文档')});const message=e instanceof Error?e.message:'';if(message==='INVALID_ID')return res.status(400).json({error:'文档 ID 必须以 user-你的账户ID- 开头,请使用编辑器生成的前缀'});if(message==='FORBIDDEN')return res.status(403).json({error:'仅作者可编辑'});if(message==='CONFLICT'||(e as {code?:string}).code==='23505')return res.status(409).json({error:'版本冲突:请加载最新版本,已发布版本不可修改'});if(e instanceof Error&&(e.name==='ZodError'||/XML|实体|元素|属性|协议|链接/.test(message)))return res.status(400).json({error:'输入不符合协议'});return res.status(503).json({error:'文档服务暂不可用'});} } export const config={api:{bodyParser:{sizeLimit:'128kb'}}}; diff --git a/apps/waterfall-wiki/src/pages/documents/[id].tsx b/apps/waterfall-wiki/src/pages/documents/[id].tsx index a81ec77..8fa2407 100644 --- a/apps/waterfall-wiki/src/pages/documents/[id].tsx +++ b/apps/waterfall-wiki/src/pages/documents/[id].tsx @@ -2,5 +2,5 @@ import type { GetServerSideProps } from 'next'; import type { Guidance } from '@/content/guides/catalog'; import styles from '@/styles/documents.module.css'; type Props={canEdit:boolean;versions:number[];doc:Guidance;links:(Guidance['links'][number]&{resolved:boolean})[]}; -export default function Read({doc,links,canEdit,versions}:Props){return

{doc.title}

{doc.kind} · {doc.id} · 固定版本 {doc.revision}

版本:{versions.map(v=> v{v} )}

{doc.summary}

适用条件

{doc.applies}

{doc.body}

    {doc.steps.map((s,i)=>
  1. {s}
  2. )}

条件链接

{links.map((l,i)=>)}

检查项

    {doc.checks.map((s,i)=>
  • {s}
  • )}
读取规范 XML{canEdit&&

}
;} +export default function Read({doc,links,canEdit,versions}:Props){return

{doc.title}

{doc.kind} · {doc.id} · 固定版本 {doc.revision}

版本:{versions.map(v=> v{v} )}

{doc.summary}

适用条件

{doc.applies}

{doc.body}

    {doc.steps.map((s,i)=>
  1. {s}
  2. )}

条件链接

{links.map((l,i)=>)}

检查项

    {doc.checks.map((s,i)=>
  • {s}
  • )}
读取规范 XML{canEdit&&

}
;} export const getServerSideProps:GetServerSideProps=async({params,query,res,req})=>{res.setHeader('Cache-Control','no-store');const revision=query.revision;if(revision!==undefined&&(typeof revision!=='string'||! /^[1-9][0-9]{0,9}$/.test(revision)||Number(revision)>2147483647))return {notFound:true};const {resolveDocument}=await import('@/lib/guidance-store');const doc=await resolveDocument(String(params?.id),revision===undefined?undefined:Number(revision));if(!doc)return {notFound:true};const links=await Promise.all(doc.links.map(async l=>({...l,resolved:!!await resolveDocument(l.target,l.revision)})));const {db}=await import('@/lib/db');const {currentAccount}=await import('@/lib/account');const user=await currentAccount(new Request('http://internal',{headers:{cookie:req.headers.cookie||''}}));const owner=await db().query('SELECT owner_id FROM guidance_documents WHERE id=$1',[doc.id]);const rows=await db().query('SELECT revision FROM guidance_revisions WHERE document_id=$1 ORDER BY revision DESC',[doc.id]);return {props:{doc,links,canEdit:!!user&&owner.rows[0]?.owner_id===user.id,versions:rows.rows.map(r=>r.revision)}};}; diff --git a/apps/waterfall-wiki/src/pages/write.tsx b/apps/waterfall-wiki/src/pages/write.tsx index 49668f5..e42290f 100644 --- a/apps/waterfall-wiki/src/pages/write.tsx +++ b/apps/waterfall-wiki/src/pages/write.tsx @@ -1,10 +1,14 @@ -import { useState } from 'react'; +import { useEffect,useState } from 'react'; import type { Guidance } from '@/content/guides/catalog'; import styles from '@/styles/documents.module.css'; const blank:Guidance={id:'user-',revision:1,kind:'guide',title:'',summary:'',applies:'',body:'',steps:[],checks:[],links:[],tags:[]}; export default function Write(){ + const [busy,setBusy]=useState(false),[published,setPublished]=useState<{id:string;revision:number}|null>(null); const [doc,setDoc]=useState(blank),[xml,setXml]=useState(''),[mode,setMode]=useState(false),[message,setMessage]=useState(''),[preview,setPreview]=useState<{document:Guidance;xml:string;links:{label:string;when:string;resolved:boolean}[]}|null>(null); - async function load(){const r=await fetch('/api/documents/'+encodeURIComponent(doc.id));const b=await r.json();if(r.ok){setDoc({...b.document,revision:b.document.revision+1});setPreview(null);setMessage('已加载,保存将创建新版本');}else setMessage(b.error);} - async function submit(action:string){setMessage('处理中…');const r=await fetch('/api/documents'+(action==='preview'?'/preview':''),{method:'POST',headers:{'Content-Type':mode?'application/xml':'application/json'},body:mode?xml:JSON.stringify(doc)});const b=await r.json();if(!r.ok)return setMessage(b.error);if(action==='preview'){setPreview(b);setMessage('预览成功,尚未发布');}else{setDoc({...b.document,revision:b.document.revision+1});setMessage('已发布版本 '+b.document.revision);setPreview(null);}} - return

发布独立文档

需要已验证邮箱。每次发布创建不可变版本;只有原作者可以更新或撤下。

{mode?