@accelflow/space-content 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -1,8 +1,8 @@
-# Space build content SDK (unpublished)
+# Space build content SDK
 
 Node 24+ build-time content synchronization for Space Headless CMS, with optional browser-safe table-of-contents presentation. Licensed under MIT.
 
-The initial npm release is being prepared; the commands below apply once it is published.
+The beta package is available on npm.
 
 ```sh
 npm install @accelflow/space-content@beta
@@ -49,12 +49,16 @@ authorization. Verified complete objects survive a transport retry; partial
 objects restart. Missing terminal markers, checksum failures, foreign objects,
 or schema errors fail the build. No stale/offline fallback is used.
 
-Current limits: 4,096 unique objects per batch, 64 MiB per object, 1 GiB total;
-API publication adapter additionally limits assets to 16 MiB each. Retry count
-is bounded (default 2). Larger manifest sharding, partial-object resume,
-framework-specific adapters, cache GC and npm publication are follow-up work.
+Transport limits: 4,096 unique objects per snapshot, 250,000,000 bytes per object,
+1 GiB per snapshot. Space applies the effective plan at upload (Free 10 MB, Team
+50 MB, Enterprise 250 MB, decimal bytes). Delivery accepts those admitted files;
+it does not re-count them as new storage usage or apply a lower per-file quota.
+The snapshot budget is a separate operational limit. Large objects stream to disk;
+complete objects are hash-verified before cache reuse. Partial objects restart on
+retry (default 2 retries). Cache GC and snapshot sharding remain host responsibilities.
+Large attachments require the matching Space delivery service update.
 
-Tests: `npm test` from this repository root (no dependencies required).
+Tests: `npm ci --ignore-scripts` then `npm test` from this repository root.
 Server, Worker and real-cloud integration tests remain in the Space service
 repository; the tests here exercise the client with synthetic protocol fixtures.
 
@@ -82,3 +86,33 @@ In Next.js, use this browser entry in a client component effect and return the c
 ## Release preparation
 
 See [RELEASING.md](RELEASING.md) for packaging checks, initial publication and OIDC setup.
+
+## JSON and HTML rendering
+
+```js
+import {renderArticleBody} from '@accelflow/space-content/render';
+const html = renderArticleBody(article.body, {
+  assets: content.assets, locale: 'ja', pdfMode: 'link',
+  renderers: {paragraph: ({children}) => `<p>${children}</p>`},
+});
+```
+
+Use this Node/build-time entry for both JSON (default) and legacy HTML. It renders
+headings, TOC, formatting, lists, tables, columns, links, images and attachment
+IDs, then sanitizes all output, including custom renderer output. Callbacks are
+trusted application code, never stored executable templates. Unknown nodes retain
+safe children. Dynamic smart links fall back to their label; supply a custom
+renderer for application-specific behavior. Use `resolveArticle` and
+`resolveSubArticles` for routes and child navigation.
+
+PDFs default to download links. `pdfMode: 'embed'` permits only local PDF paths
+listed in the manifest, with an empty sandbox and no referrer, plus a download
+link. Browser PDF viewers may not work in a sandbox; the link remains available.
+Arbitrary iframes, scripts, event handlers, inline styles, SVG and unsafe URLs
+are removed. JSON is not inherently trusted. The browser-only TOC module and its
+responsive CSS can be used unchanged with rendered JSON.
+
+Serve copied assets with their manifest MIME and `X-Content-Type-Options: nosniff`.
+Force Content-Disposition attachment for non-raster, non-PDF types (especially
+HTML/SVG); they must never execute at the site's origin. The examples emit those
+headers for Cloudflare-style hosts; configure equivalent rules on other hosts.

package/node.mjs

@@ -1,5 +1,6 @@
+import {createReadStream} from 'node:fs';
 import { createHash, randomUUID } from 'node:crypto';
-import { mkdir, readFile, writeFile, rename, rm, lstat } from 'node:fs/promises';
+import { mkdir, readFile, writeFile, rename, rm, lstat, open, copyFile } from 'node:fs/promises';
 import { resolve, join } from 'node:path';
 const sha = bytes => createHash('sha256').update(bytes).digest('hex');
 const hashPattern = /^[a-f0-9]{64}$/;
@@ -12,7 +13,7 @@ function validateManifest(m, accountId, workspaceId) {
     const objects = new Map();
     let total = 0;
     for (const o of m.objects) {
-        if (!hashPattern.test(o.hash) || !Number.isSafeInteger(o.size) || o.size < 0 || o.size > 64 * 1024 * 1024 || objects.has(o.hash))
+        if (!hashPattern.test(o.hash) || !Number.isSafeInteger(o.size) || o.size < 0 || o.size > 250_000_000 || objects.has(o.hash))
             throw Error('invalid_manifest');
         objects.set(o.hash, o);
         total += o.size;
@@ -23,7 +24,7 @@ function validateManifest(m, accountId, workspaceId) {
         if (typeof a.id !== 'string' || typeof a.slug !== 'string' || typeof a.title !== 'string' || !objects.has(a.bodyHash) || !objects.has(a.metadataHash))
             throw Error('invalid_manifest');
     for (const a of m.assets)
-        if (typeof a.id !== 'string' || typeof a.contentType !== 'string' || typeof a.filename !== 'string' || !objects.has(a.hash))
+        if (typeof a.id !== 'string' || typeof a.contentType !== 'string' || typeof a.filename !== 'string' || /[\r\n\x00]/.test(a.filename) || !/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/i.test(a.contentType) || !objects.has(a.hash))
             throw Error('invalid_manifest');
     return objects;
 }
@@ -67,24 +68,14 @@ class Reader {
         chunks.push(b[0]);
     } throw Error('frame_too_large'); }
 }
-async function cacheRead(path, o) { try {
-    if (!(await lstat(path)).isFile() || (await lstat(path)).isSymbolicLink())
-        return null;
-    const b = await readFile(path);
-    return b.length === o.size && sha(b) === o.hash ? b : null;
+async function cacheValid(path,o) {
+ try {
+  const stat=await lstat(path);if(!stat.isFile()||stat.isSymbolicLink()||stat.size!==o.size)return false;
+  const digest=createHash('sha256');for await(const chunk of createReadStream(path))digest.update(chunk);
+  return digest.digest('hex')===o.hash;
+ }catch(e){if(e.code==='ENOENT')return false;throw e;}
 }
-catch (e) {
-    if (e.code === 'ENOENT')
-        return null;
-    throw e;
-} }
-async function save(path, data) { const temp = path + '.' + randomUUID() + '.partial'; try {
-    await writeFile(temp, data, { flag: 'wx', mode: 0o600 });
-    await rename(temp, path);
-}
-finally {
-    await rm(temp, { force: true });
-} }
+async function cacheRead(path,o) {return await cacheValid(path,o)?readFile(path):null;}
 async function safeDirectory(path) { await mkdir(path, { recursive: true, mode: 0o700 }); const s = await lstat(path); if (s.isSymbolicLink() || !s.isDirectory())
     throw Error('unsafe_cache_directory'); }
 /** Build-time only. cacheDir must be a private, trusted directory; never expose it to untrusted PRs. */
@@ -112,7 +103,7 @@ export async function syncContent({ apiUrl, downloadOrigin, accountId, workspace
     await safeDirectory(namespace);
     const missing = [];
     for (const o of objects.values())
-        if (!await cacheRead(join(namespace, o.hash), o))
+        if (!await cacheValid(join(namespace, o.hash), o))
             missing.push(o.hash);
     let pending = missing, downloads = 0;
     for (let attempt = 0; pending.length; attempt++) {
@@ -145,18 +136,18 @@ export async function syncContent({ apiUrl, downloadOrigin, accountId, workspace
                 const item = await reader.line(), expected = objects.get(item.hash);
                 if (!remaining.has(item.hash) || !expected || item.size !== expected.size)
                     throw Error('unexpected_object');
-                const data = Buffer.alloc(item.size);
-                let offset = 0;
-                while (offset < data.length) {
-                    const chunk = await reader.take(data.length - offset);
-                    if (!chunk)
-                        throw Error('truncated_stream');
-                    data.set(chunk, offset);
-                    offset += chunk.length;
-                }
-                if (sha(data) !== item.hash)
-                    throw Error('object_checksum_mismatch');
-                await save(join(namespace, item.hash), data);
+                const path=join(namespace,item.hash), temp=path+'.'+randomUUID()+'.partial';
+                const file=await open(temp,'wx',0o600), digest=createHash('sha256');
+                try {
+                    let received=0;
+                    while(received<item.size) {
+                        const chunk=await reader.take(item.size-received);
+                        if(!chunk)throw Error('truncated_stream');
+                        received+=chunk.length;digest.update(chunk);await file.writeFile(chunk);
+                    }
+                    if(digest.digest('hex')!==item.hash)throw Error('object_checksum_mismatch');
+                    await file.close();await rename(temp,path);
+                } finally {await file.close().catch(()=>{});await rm(temp,{force:true});}
                 remaining.delete(item.hash);
                 downloads++;
             }
@@ -174,7 +165,7 @@ export async function syncContent({ apiUrl, downloadOrigin, accountId, workspace
         }
         pending = [];
         for (const o of missing.map(h => objects.get(h)))
-            if (!await cacheRead(join(namespace, o.hash), o))
+            if (!await cacheValid(join(namespace, o.hash), o))
                 pending.push(o.hash);
         // A missing terminal marker is never accepted even when every object arrived.
         if (!complete && !pending.length)
@@ -194,10 +185,10 @@ export async function syncContent({ apiUrl, downloadOrigin, accountId, workspace
         }
         await safeDirectory(join(generation, 'space-assets'));
         for (const a of manifest.assets) {
-            const data = await cacheRead(join(namespace, a.hash), objects.get(a.hash));
-            if (!data)
+            const valid = await cacheValid(join(namespace, a.hash), objects.get(a.hash));
+            if (!valid)
                 throw Error('cache_corrupt');
-            await writeFile(join(generation, 'space-assets', a.hash), data);
+            await copyFile(join(namespace,a.hash),join(generation,'space-assets',a.hash));
         }
         await writeFile(join(generation, 'content.json'), JSON.stringify({ snapshotId: manifest.snapshotId, format: manifest.format, articles, assets: manifest.assets }));
         return { snapshotDir: generation, manifest, diagnostics: { downloadedObjects: downloads, cacheHits: objects.size - missing.length } };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@accelflow/space-content",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.2",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -14,7 +14,11 @@
       "types": "./toc.d.mts",
       "import": "./toc.mjs"
     },
-    "./toc.css": "./toc.css"
+    "./toc.css": "./toc.css",
+    "./render": {
+      "types": "./render.d.mts",
+      "import": "./render.mjs"
+    }
   },
   "scripts": {
     "test": "node --test test/*.test.mjs",
@@ -28,7 +32,9 @@
     "toc.mjs",
     "toc.d.mts",
     "toc.css",
-    "LICENSE"
+    "LICENSE",
+    "render.mjs",
+    "render.d.mts"
   ],
   "description": "Build-time Headless CMS content sync and customizable table of contents for Accelflow Space",
   "license": "MIT",
@@ -43,5 +49,8 @@
   "publishConfig": {
     "access": "public",
     "tag": "beta"
+  },
+  "dependencies": {
+    "sanitize-html": "^2.18.0"
   }
 }

package/render.d.mts

@@ -0,0 +1,11 @@
+export interface ContentNode { type: string; text?: string; attrs?: Record<string, unknown>; marks?: Array<{type:string;attrs?:Record<string,unknown>}>; content?: ContentNode[]; }
+export interface ContentAsset {id:string;hash:string;contentType:string;filename:string;}
+export interface RenderOptions {
+ assets?: ContentAsset[]; locale?: 'ja'|'en'; pdfMode?: 'link'|'embed';
+ renderers?: Record<string,(context:{node:ContentNode;children:string;defaultHtml:string;escapeHtml:typeof escapeHtml})=>string>;
+ resolveArticle?: (attrs:Record<string,unknown>)=>{href:string;title?:string}|undefined;
+ resolveSubArticles?: (attrs:Record<string,unknown>)=>Array<{href:string;title:string}>;
+}
+export function escapeHtml(value:unknown):string;
+export function sanitizeArticleHtml(html:string, options?:RenderOptions):string;
+export function renderArticleBody(body:ContentNode|string, options?:RenderOptions):string;

package/render.mjs

@@ -0,0 +1,95 @@
+import sanitizeHtml from 'sanitize-html';
+import {renderTableOfContents} from './toc.mjs';
+export const escapeHtml = value => String(value ?? '').replace(/[&<>"']/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+const hash = /^[a-f0-9]{64}$/;
+const raster = new Set(['image/png','image/jpeg','image/gif','image/webp','image/avif']);
+function assetsIndex(assets = []) {
+ const ids = new Map(), paths = new Map();
+ for (const a of assets) {
+  if (!a || typeof a.id !== 'string' || !hash.test(a.hash) || typeof a.contentType !== 'string' || typeof a.filename !== 'string' || ids.has(a.id)) throw Error('invalid_render_asset');
+  ids.set(a.id,a); paths.set('/space-assets/'+a.hash,a);
+ }
+ return {ids,paths};
+}
+function safeUrl(value, image = false) {
+ if (typeof value !== 'string' || /[\u0000-\u0020\u007f\\]/.test(value)) return '';
+ if (/^(?:\/(?!\/)|#)/.test(value)) return value;
+ try {const u=new URL(value);return !u.username && !u.password && (image ? u.protocol==='https:' : ['https:','http:','mailto:','tel:'].includes(u.protocol)) ? value : '';} catch {return '';}
+}
+/** Build-time HTML sanitizer. Only known local PDF assets may be embedded, opt-in. */
+export function sanitizeArticleHtml(html, {assets = [], pdfMode = 'link'} = {}) {
+ if (typeof html !== 'string') throw Error('invalid_html_body');
+ const {paths}=assetsIndex(assets);
+ return sanitizeHtml(html, {
+  nonBooleanAttributes: sanitizeHtml.defaults.nonBooleanAttributes.filter(a=>a!=='sandbox'),
+  allowedTags: [...sanitizeHtml.defaults.allowedTags,'img','details','summary','nav',...(pdfMode==='embed'?['iframe']:[])],
+  allowedAttributes: {
+   '*':['id','class'], a:['href','title','data-level','download'],
+   img:['src','alt','title','width','height','loading','referrerpolicy'],
+   nav:['data-table-of-contents','data-max-level','aria-label'], details:['open','data-space-toc'],
+   li:['data-level','data-checked'], ol:['start'], td:['colspan','rowspan'], th:['colspan','rowspan','scope'],
+   iframe:['src','title','sandbox','loading','referrerpolicy'],
+  },
+  allowedClasses:{'*':['*']},
+  allowedSchemes:['https','http','mailto','tel'], allowedSchemesByTag:{img:['https'],iframe:[]}, allowProtocolRelative:false,
+  transformTags: {
+   iframe: (tagName, attrs) => ({tagName,attribs:{src:attrs.src??'',title:attrs.title??'PDF',sandbox:'',loading:'lazy',referrerpolicy:'no-referrer'}}),
+  },
+  exclusiveFilter: frame => frame.tag==='iframe' && !(pdfMode==='embed' && paths.get(frame.attribs.src)?.contentType==='application/pdf'),
+ });
+}
+/** Render Space's Tiptap JSON document. Custom callbacks are trusted code; their HTML is still sanitized. */
+export function renderArticleBody(body, options = {}) {
+ if (typeof body==='string') return sanitizeArticleHtml(body,options);
+ if (!body || body.type!=='doc' || !Array.isArray(body.content)) throw Error('invalid_document');
+ const {ids}=assetsIndex(options.assets), headings=[], anchors=new Map(), used=new Set();let count=0;
+ const text=n=>n.type==='text'?String(n.text??''):(n.content??[]).map(text).join('');
+ function inspect(n,depth=0) {
+  if (!n || typeof n!=='object' || typeof n.type!=='string' || ++count>100000 || depth>64 || (n.content!==undefined&&!Array.isArray(n.content))) throw Error('invalid_document');
+  for(const child of n.content??[])inspect(child,depth+1);
+ }
+ inspect(body);
+ function collect(n) {
+  if(n.type==='tableOfContents')return;
+  if(n.type==='heading') {const level=Number.isInteger(n.attrs?.level)&&n.attrs.level>=1&&n.attrs.level<=6?n.attrs.level:2;const title=text(n);let id=typeof n.attrs?.id==='string'&&/^[\p{L}\p{N}_-]+$/u.test(n.attrs.id)?n.attrs.id:title.toLowerCase().replace(/[^\p{L}\p{N}_-]+/gu,'-').replace(/^-|-$/g,'')||'heading';const base=id;let index=2;while(used.has(id))id=base+'-'+index++;used.add(id);anchors.set(n,id);headings.push({id,level,text:title});}
+  for(const child of n.content??[])collect(child);
+ }
+ collect(body);
+ const e=escapeHtml;
+ const wrap=(tag,children,attrs='')=>`<${tag}${attrs}>${children}</${tag}>`;
+ function render(n) {
+  const a=n.attrs??{}, children=(n.content??[]).map(render).join('');
+  let html='';
+  if(n.type==='text') {
+   html=e(n.text);
+   for(const mark of Array.isArray(n.marks)?n.marks:[]) {const tag={bold:'strong',italic:'em',underline:'u',strike:'s',code:'code'}[mark?.type];if(tag)html=wrap(tag,html);else if(mark?.type==='link'){const href=safeUrl(mark.attrs?.href);if(href)html=wrap('a',html,` href="${e(href)}"`);}}
+  } else if(n.type==='heading') html=wrap('h'+(Number.isInteger(a.level)&&a.level>=1&&a.level<=6?a.level:2),children,` id="${e(anchors.get(n))}"`);
+  else if(n.type==='tableOfContents') html=renderTableOfContents(headings,{locale:options.locale??'ja',maxLevel:a.maxLevel===2?2:3});
+  else if(n.type==='image') {const src=safeUrl(a.src,true);html=src?`<img src="${e(src)}" alt="${e(a.alt)}" loading="lazy" referrerpolicy="no-referrer">`:'';}
+  else if(n.type==='attachment') {
+   const asset=ids.get(a.attachmentId);if(!asset)throw Error('attachment_not_in_manifest');
+   const src='/space-assets/'+asset.hash, label=e(asset.filename);
+   html=raster.has(asset.contentType)?`<img src="${src}" alt="${label}" loading="lazy">`:`<a href="${src}" download="${label}">${label}</a>`;
+   if(asset.contentType==='application/pdf'&&options.pdfMode==='embed')html=`<iframe class="space-pdf" src="${src}" title="${label}" sandbox="" loading="lazy" referrerpolicy="no-referrer"></iframe>`+html;
+  } else if(n.type==='externalLinkCard') {const href=safeUrl(a.href);html=href?wrap('a',e(a.title||href),` href="${e(href)}"`):e(a.title);}
+  else if(n.type==='articleReference') {const target=options.resolveArticle?.(a);const href=safeUrl(target?.href);const label=e(a.labelMode==='custom'?a.customLabel:target?.title??a.fallbackTitle??a.title??'');html=href?wrap('a',label,` href="${e(href)}"`):label;}
+  else if(n.type==='smartLink') html=e(a.label??a.categoryLabel??'');
+  else if(n.type==='subArticleList') html=wrap('nav',wrap('ol',(options.resolveSubArticles?.(a)??[]).map(x=>{const href=safeUrl(x.href);return href?wrap('li',wrap('a',e(x.title),` href="${e(href)}"`)):'';}).join('')));
+  else if(n.type==='hardBreak')html='<br>';
+  else if(n.type==='horizontalRule')html='<hr>';
+  else if(n.type==='codeBlock')html=wrap('pre',wrap('code',e(text(n)),` class="language-${e(String(a.language??'text').replace(/[^\w-]/g,''))}"`));
+  else if(n.type==='columnLayout')html=wrap('div',children,' class="space-columns"');
+  else if(n.type==='column')html=wrap('div',children,' class="space-column"');
+  else {
+   const tag={doc:null,paragraph:'p',bulletList:'ul',orderedList:'ol',listItem:'li',taskList:'ul',taskItem:'li',blockquote:'blockquote',table:'table',tableRow:'tr',tableCell:'td',tableHeader:'th'}[n.type];
+   let attrs='';
+   if(n.type==='orderedList'&&Number.isSafeInteger(a.start)&&a.start>0)attrs=` start="${a.start}"`;
+   if(n.type==='taskItem')attrs=` class="space-task" data-checked="${a.checked===true}"`;
+   if(['tableCell','tableHeader'].includes(n.type))for(const key of ['colspan','rowspan'])if(Number.isInteger(a[key])&&a[key]>0&&a[key]<=100)attrs+=` ${key}="${a[key]}"`;
+   html=tag?wrap(tag,children,attrs):children;
+  }
+  const custom=Object.hasOwn(options.renderers??{},n.type)?options.renderers[n.type]:null;
+  return custom?custom({node:n,children,defaultHtml:html,escapeHtml:e}):html;
+ }
+ return sanitizeArticleHtml(render(body),options);
+}