diff --git a/apps/web/contents/addons/api.mdx b/apps/web/contents/addons/api.mdx index cab0e6e..a87a3c2 100644 --- a/apps/web/contents/addons/api.mdx +++ b/apps/web/contents/addons/api.mdx @@ -91,7 +91,7 @@ Security constraints: - Only **Account Mode** may create the journal; Developer Mode is rejected. - An enabled release is still **data-only Markdown**. It must never execute scripts, MDX expressions or untrusted HTML. - Activating or reading a release rechecks its signed status and locally stored digest; revoked or stale releases fail closed. The registry must refresh its signed index at least hourly for state changes to succeed. -- There is no automated downloader, dashboard installation endpoint, public docs rendering integration, or installed-site UI yet. The module is a server-side foundation, not a completed marketplace workflow. +- The Account Mode dashboard now includes the reviewed v1 downloader and installation actions. A generated public route serves only explicitly enabled, still-approved Markdown, rendered as safe React text—not executable MDX. Sidebar/search integration and privileged v2 extensions remain separate milestones. - Explicit browser consent and permission diffs remain required for future executable v2 add-ons. ## Fetch approved archives without arbitrary redirects diff --git a/apps/web/contents/addons/marketplace.mdx b/apps/web/contents/addons/marketplace.mdx index 9049dae..7e08b17 100644 --- a/apps/web/contents/addons/marketplace.mdx +++ b/apps/web/contents/addons/marketplace.mdx @@ -6,7 +6,7 @@ description: Browse signed content add-ons, manage reviewed versions and underst # Account Mode add-ons -The Account Mode studio now supports signed **content-only v1** add-on installation, version pinning, enable/disable state, verified updates, rollback and uninstall. These actions are available only to a signed-in site owner and require the independent registry's Ed25519 signature. **Installed content is stored privately but is not yet automatically mounted as public documentation pages.** Executable v2 add-ons remain disabled. +The Account Mode studio now supports signed **content-only v1** add-on installation, version pinning, enable/disable state, verified updates, rollback and uninstall. These actions are available only to a signed-in site owner and require the independent registry's Ed25519 signature. **Enabled reviewed Markdown pages are published through a dedicated Account Mode route, with registry and stored-archive verification on every request.** Executable v2 add-ons remain disabled. ## Connect a reviewed registry @@ -25,7 +25,7 @@ The registry must issue a newly signed index at least once an hour: stale metada 2. Search or filter reviewed releases and open **View details**. 3. Check publisher identity, license, NextGuide compatibility and requested permissions. 4. Confirm **Install reviewed content**. The site downloads only the signed GitHub Release and verifies its bytes before writing immutable files to private storage. -5. Use **Enable/Disable** to change the stored content state. The public docs integration is a separate milestone; enabling does not automatically publish pages yet. +5. Use **Enable/Disable** to control whether the reviewed Markdown pages can be opened at your site's `/docs/addons//` route. Each request re-verifies signed approval and local archive integrity. 6. Use **Update** when a higher reviewed version is available, or **Roll back** to a previously saved, still-approved version. Rollback leaves the add-on disabled for explicit re-enabling. 7. **Uninstall** clears its installed entry but preserves separate private settings and historical archive blobs for recovery. @@ -37,6 +37,6 @@ Published v1 examples currently declare NextGuide `>=1.0.0 <2.0.0`. A site still The server validates owner sessions and request origin on every mutation. Installed data is never placed in `content/docs` or public assets. The journal checks the signed release metadata, exact SHA-256, compatible package version and current approval status. Conflicting update requests are rejected using an installation revision, and a damaged archive cannot be enabled. -The UI uses NextGuide's native Account Mode components. No Docker requirement or new npm package is introduced. +The UI uses NextGuide's native Account Mode components. Pages are rendered with NextGuide's safe Markdown subset, **not** MDX, so raw HTML and JavaScript are never executed. Disabled, revoked, invalid or stale releases are not served. Add-on pages do not automatically enter the public docs sidebar or search index yet. No Docker requirement or new npm package is introduced. See [Updates and removal](/addons/updates), [Security and permissions](/addons/permissions), and [runtime API](/addons/api). Follow [roadmap #101](https://github.com/m1nsook/NextGuide/issues/101) for executable v2 and public rendering integration. diff --git a/apps/web/contents/addons/updates.mdx b/apps/web/contents/addons/updates.mdx index 43fc6fd..55a1cb6 100644 --- a/apps/web/contents/addons/updates.mdx +++ b/apps/web/contents/addons/updates.mdx @@ -33,7 +33,7 @@ The owner-facing **Add-ons** page can install, enable/disable, update, roll back Owner authentication and same-origin checks apply to every mutation. A concurrent change requires refreshing the page rather than overwriting another update. A revoked or stale release cannot be reactivated or rolled back. -The Account Mode site does not yet mount installed Markdown pages into public documentation. Executable add-ons, privileged permissions, secrets, React components and automatic background update checks remain future milestones. Legacy v1 content is never compiled as untrusted MDX. +Enabled, reviewed v1 Markdown content can be opened at the site's dedicated `/docs/addons//` route (or `/addons//` when the docs base is root). Add-on pages do not yet join the public docs sidebar and search index. Executable add-ons, privileged permissions, secrets, React components and automatic background update checks remain future milestones. Legacy v1 content is never compiled as untrusted MDX. For details see [Account Mode marketplace](/addons/marketplace) and [runtime API](/addons/api). diff --git a/packages/nextguide/lib/account-addon-page-template.mjs b/packages/nextguide/lib/account-addon-page-template.mjs new file mode 100644 index 0000000..58fdc42 --- /dev/null +++ b/packages/nextguide/lib/account-addon-page-template.mjs @@ -0,0 +1,72 @@ +/** + * Generated Account Mode public Markdown add-on route. + * + * This route NEVER compiles untrusted files as MDX or imports extension code. + * It renders only verified, explicitly enabled v1 Markdown through NextGuide's + * safe React Markdown subset, with raw HTML displayed as text. + */ +const TEMPLATE = `// Generated by NextGuide CLI. Edit freely; NextGuide never overwrites these files. +import { cache } from "react" +import { connection } from "next/server" +import { notFound } from "next/navigation" +import { Markdown } from "nextguide/components" +import { createAccountAddonManager } from "nextguide/extensions/site-manager" + +const addonId = /^[a-z0-9]+(?:-[a-z0-9]+)*\\.[a-z0-9]+(?:-[a-z0-9]+)*$/ +const pageSegment = /^[a-zA-Z0-9_-]+(?:\\.[a-zA-Z0-9_-]+)*$/ + +const readPage = cache(async (id__ID_TYPE__, rawPage__PAGE_TYPE__) => { + // Account Mode is intentionally request-time only; no static export or ISR. + await connection() + if (!addonId.test(id) || rawPage.length > 180 || + (rawPage && rawPage.split("/").some(part => !part || !pageSegment.test(part)))) return null + const slug = rawPage === "" ? "index" : rawPage + try { + const addon = await createAccountAddonManager({ project: process.cwd() }).readEnabled({ id }) + if (!addon || !addon.manifest || !addon.manifest.entrypoints) return null + const root = String(addon.manifest.entrypoints.content || "") + const target = root + "/" + slug + ".md" + const entry = addon.pages.find(item => item.path === target) + if (!entry) return null + const title = slug === "index" ? String(addon.manifest.name || id) + : (slug.split("/").at(-1) ?? slug).replace(/[-_]/g, " ") + return { title, id, version: addon.version, markdown: entry.markdown } + } catch { + // Missing signed freshness, revoked release, corrupt blob, bad config or + // failed registry requests must never reveal private state publicly. + return null + } +}) + +export async function generateMetadata({ params }__PARAM_TYPE__) { + const { id, page = [] } = await params + const selected = await readPage(id, page.join("/")) + return selected + ? { title: selected.title + " · Add-ons", robots: { index: false, follow: false } } + : { title: "Add-on unavailable", robots: { index: false, follow: false } } +} + +export default async function InstalledAddonPage({ params }__PARAM_TYPE__) { + const { id, page = [] } = await params + const selected = await readPage(id, page.join("/")) + if (!selected) notFound() + return ( +
+
+

Reviewed add-on · {selected.id} · v{selected.version}

+

{selected.title}

+
+
+ {selected.markdown} +
+
+ ) +} +` + +export function accountAddonDocsRouteSource(typed = true) { + return TEMPLATE + .replaceAll("__ID_TYPE__", typed ? ": string" : "") + .replaceAll("__PAGE_TYPE__", typed ? ": string" : "") + .replaceAll("__PARAM_TYPE__", typed ? ": { params: Promise<{ id: string; page?: string[] }> }" : "") +} diff --git a/packages/nextguide/lib/account-starter.mjs b/packages/nextguide/lib/account-starter.mjs index 44f2abb..9c070bf 100644 --- a/packages/nextguide/lib/account-starter.mjs +++ b/packages/nextguide/lib/account-starter.mjs @@ -5,6 +5,7 @@ import { join, resolve } from "node:path" import { accountFile, createBootstrap } from "./account-auth.mjs" import { applyPlan, planDeveloperProject } from "./init.mjs" import { fullStudioRouteSource } from "./account-studio-template.mjs" +import { accountAddonDocsRouteSource } from "./account-addon-page-template.mjs" import { installMonacoAssets } from "./monaco-assets.mjs" const PAGE = `// Generated by NextGuide CLI. Edit freely; NextGuide never overwrites these files. @@ -185,6 +186,7 @@ export function accountStarterFiles(folder, typed, docsPath) { [folder + "/api/nextguide/account/[action]/route." + routeExt]: api, [folder + "/api/nextguide/studio/[action]/route." + routeExt]: fullStudioRouteSource(typed), [folder + "/nextguide/media/[name]/route." + routeExt]: media, + [folder + (docsPath === "/" ? "/(nextguide)" : docsPath) + "/addons/[id]/[[...page]]/page." + ext]: accountAddonDocsRouteSource(typed), } } diff --git a/packages/nextguide/lib/extension-site-manager.d.mts b/packages/nextguide/lib/extension-site-manager.d.mts index d5dda3d..f32b9c6 100644 --- a/packages/nextguide/lib/extension-site-manager.d.mts +++ b/packages/nextguide/lib/extension-site-manager.d.mts @@ -59,7 +59,7 @@ export declare function createAccountAddonManager(options?: { readEnabled(input: {id: string}): Promise + manifest: { name: string; entrypoints: { content: string } } & Record icon: { path: string; bytes: Buffer } pages: Array<{ path: string; markdown: string }> }> diff --git a/packages/nextguide/package.json b/packages/nextguide/package.json index 1a3acce..8c55e05 100644 --- a/packages/nextguide/package.json +++ b/packages/nextguide/package.json @@ -16,9 +16,9 @@ ], "scripts": { "build": "node scripts/build.mjs", - "test": "node scripts/build.mjs && node --test test/cli-ui.test.mjs test/account-ui-isolation.test.mjs test/account-semantics-icons.test.mjs test/doctor.test.mjs test/init.test.mjs test/distribution.test.mjs test/page.test.mjs test/page-cli.test.mjs test/version.test.mjs test/upgrade.test.mjs test/account-auth.test.mjs test/account-init.test.mjs test/account-cms.test.mjs test/extensions.test.mjs test/extension-runtime.test.mjs test/extension-storage.test.mjs test/extension-catalog.test.mjs test/extension-network.test.mjs test/extension-isolation.test.mjs test/extension-artifacts.test.mjs test/extension-install-state.test.mjs test/extension-download.test.mjs test/extension-site-manager.test.mjs test/docs-chatgpt.test.mjs", + "test": "node scripts/build.mjs && node --test test/cli-ui.test.mjs test/account-ui-isolation.test.mjs test/account-semantics-icons.test.mjs test/doctor.test.mjs test/init.test.mjs test/distribution.test.mjs test/page.test.mjs test/page-cli.test.mjs test/version.test.mjs test/upgrade.test.mjs test/account-auth.test.mjs test/account-init.test.mjs test/account-cms.test.mjs test/extensions.test.mjs test/extension-runtime.test.mjs test/extension-storage.test.mjs test/extension-catalog.test.mjs test/extension-network.test.mjs test/extension-isolation.test.mjs test/extension-artifacts.test.mjs test/extension-install-state.test.mjs test/extension-download.test.mjs test/extension-site-manager.test.mjs test/addon-page.test.mjs test/docs-chatgpt.test.mjs", "test:dist": "node --test test/distribution.test.mjs", - "prepack": "node scripts/build.mjs && node --test test/cli-ui.test.mjs test/account-ui-isolation.test.mjs test/account-semantics-icons.test.mjs test/doctor.test.mjs test/init.test.mjs test/distribution.test.mjs test/page.test.mjs test/page-cli.test.mjs test/version.test.mjs test/upgrade.test.mjs test/account-auth.test.mjs test/account-init.test.mjs test/account-cms.test.mjs test/extensions.test.mjs test/extension-runtime.test.mjs test/extension-storage.test.mjs test/extension-catalog.test.mjs test/extension-network.test.mjs test/extension-isolation.test.mjs test/extension-artifacts.test.mjs test/extension-install-state.test.mjs test/extension-download.test.mjs test/extension-site-manager.test.mjs test/docs-chatgpt.test.mjs", + "prepack": "node scripts/build.mjs && node --test test/cli-ui.test.mjs test/account-ui-isolation.test.mjs test/account-semantics-icons.test.mjs test/doctor.test.mjs test/init.test.mjs test/distribution.test.mjs test/page.test.mjs test/page-cli.test.mjs test/version.test.mjs test/upgrade.test.mjs test/account-auth.test.mjs test/account-init.test.mjs test/account-cms.test.mjs test/extensions.test.mjs test/extension-runtime.test.mjs test/extension-storage.test.mjs test/extension-catalog.test.mjs test/extension-network.test.mjs test/extension-isolation.test.mjs test/extension-artifacts.test.mjs test/extension-install-state.test.mjs test/extension-download.test.mjs test/extension-site-manager.test.mjs test/addon-page.test.mjs test/docs-chatgpt.test.mjs", "test:unit": "bunx vitest run", "check-types": "node scripts/build.mjs" }, diff --git a/packages/nextguide/src/account/addon-marketplace.tsx b/packages/nextguide/src/account/addon-marketplace.tsx index 8c11de4..0302521 100644 --- a/packages/nextguide/src/account/addon-marketplace.tsx +++ b/packages/nextguide/src/account/addon-marketplace.tsx @@ -158,7 +158,7 @@ function actionDescription(action: Action | null) { } /** Owner-only Account Mode UI. All mutations go through session and origin-checked routes. */ -export function AccountAddonMarketplace() { +export function AccountAddonMarketplace({basePath="/docs"}: {basePath?: string}) { const [catalog, setCatalog] = React.useState(null) const [loading, setLoading] = React.useState(true) const [busy, setBusy] = React.useState(false) @@ -264,6 +264,7 @@ export function AccountAddonMarketplace() { {addon.name} {addon.id} · v{addon.version} · {addon.enabled?"Enabled":"Disabled"} + {addon.enabled && Open content} {releases.some(x=>x.manifest.id===addon.id) && } Images{overview!.media.length} files
{overview!.media.length ? overview!.media.map(item =>

{item.name}

{item.url}

) :

No images uploaded yet.

}
} - {view === "addons" && } + {view === "addons" && } {view === "security" && <>

Security

Manage authenticator access, recovery codes, and active sessions.

Authenticator & recoveryChanging your authenticator requires a valid current code or unused recovery code. Recovery renewal requires your authenticator. setSecurityCode(e.target.value)} autoComplete="off" placeholder="000000 or NG-XXXX-..." maxLength={27}/>
diff --git a/packages/nextguide/test/account-init.test.mjs b/packages/nextguide/test/account-init.test.mjs index 4edd6b1..e8bfe91 100644 --- a/packages/nextguide/test/account-init.test.mjs +++ b/packages/nextguide/test/account-init.test.mjs @@ -6,6 +6,7 @@ import { join } from "node:path" import { initAccount } from "../lib/account-starter.mjs" import { accountFile } from "../lib/account-auth.mjs" import ts from "typescript" +import { accountAddonDocsRouteSource as routeTemplate } from "../lib/account-addon-page-template.mjs" function fixture(router = "src/app", typed = true) { const project = mkdtempSync(join(tmpdir(), "nextguide-account-init-")) @@ -33,7 +34,7 @@ test("App Router Account Mode scaffolds protected routes and owner token without const result = initAccount(project, inspection) assert.equal(result.mode, "account") assert.ok(result.bootstrapToken.length >= 30) - assert.equal(result.created.length, 23) + assert.equal(result.created.length, 24) for (const name of result.created.filter(path => /\\.[jt]sx?$/.test(path))) { const content = readFileSync(join(project, name), "utf8") const parsed = ts.createSourceFile(name, content, ts.ScriptTarget.Latest, true) @@ -48,6 +49,15 @@ test("App Router Account Mode scaffolds protected routes and owner token without assert.match(source, /--ng-preview-inter/, route + " should supply the Account Mode font variable") } assert.ok(existsSync(join(project, "src/app/admin/page.tsx"))) + const addOnRoute = readFileSync(join(project, + "src/app/docs/addons/[id]/[[...page]]/page.tsx"), "utf8") + assert.match(addOnRoute, /createAccountAddonManager/) + assert.match(addOnRoute, /readEnabled/) + assert.match(addOnRoute, //) + assert.match(addOnRoute, /await connection\(\)/) + assert.match(addOnRoute, /robots: \{ index: false/) + assert.doesNotMatch(addOnRoute, /parseMdx|eval\(|import\(.*addon/) + assert.ok(existsSync(join(project, "public/_nextguide/monaco/vs/loader.js")), "local Monaco bundle missing") assert.ok(existsSync(join(project, "public/_nextguide/monaco/vs/LICENSE.txt")), "Microsoft MIT notice missing") assert.match(readFileSync(join(project, "src/app/admin/page.tsx"), "utf8"), /await connection\(\)/) @@ -157,7 +167,7 @@ test("Account Mode add-on lifecycle routes stay owner-authenticated and read-onl "POST must authenticate before mutating add-ons") assert.ok(post.indexOf("if (!sameOrigin(request))") < post.indexOf('action.startsWith("addon-")'), "POST must enforce same-origin before any add-on mutation") - assert.match(view,//) + assert.ok(view.includes("")) assert.match(view,/id: "addons", label: "Add-ons"/) assert.match(market,/credentials:"same-origin"/) assert.match(market,/{ + const {accountAddonDocsRouteSource}=requireAddonDocsTemplate() + const typescript=accountAddonDocsRouteSource(true) + const javascript=accountAddonDocsRouteSource(false) + for(const [name,source] of [["page.tsx",typescript],["page.jsx",javascript]]) { + const parsed=ts.createSourceFile(name,source,ts.ScriptTarget.Latest,true, + name.endsWith(".tsx")?ts.ScriptKind.TSX:ts.ScriptKind.JSX) + assert.equal(parsed.parseDiagnostics.length,0, + parsed.parseDiagnostics.map(d=>ts.flattenDiagnosticMessageText(d.messageText," ")).join("; ")) + assert.match(source,/createAccountAddonManager/) + assert.match(source,/readEnabled/) + assert.match(source,/const addonId =/) + assert.match(source,/Markdown/) + assert.doesNotMatch(source,/parseMdx|serializeMdx|dangerouslySetInnerHTML/) + } + assert.doesNotMatch(javascript, /__PARAM_TYPE__|__ID_TYPE__|__PAGE_TYPE__/) +}) + +function requireAddonDocsTemplate() { + // statically imported below through Node's native ESM test runner + return {accountAddonDocsRouteSource: routeTemplate} +} diff --git a/packages/nextguide/test/addon-page.test.mjs b/packages/nextguide/test/addon-page.test.mjs new file mode 100644 index 0000000..cb23371 --- /dev/null +++ b/packages/nextguide/test/addon-page.test.mjs @@ -0,0 +1,25 @@ +import test from "node:test" +import assert from "node:assert/strict" +import React from "react" +import { renderToStaticMarkup } from "react-dom/server" +import { Markdown } from "../dist/components/markdown.js" + +test("installed Markdown renderer escapes raw HTML and never creates scripts",()=>{ + const output=renderToStaticMarkup(React.createElement(Markdown,{ + children:"# Reviewed page\n\n\n\n\n\n[unsafe](javascript:alert(1))\n\n**Safe text**" + })) + assert.doesNotMatch(output,/]*onerror|href="javascript:/i) + assert.match(output,/<script>/) + assert.match(output,/<img src=x onerror=alert\(1\)>/) + assert.match(output,/Safe text/) +}) + +test("safe Markdown links remain URL-sanitized and external links are nofollow",()=>{ + const output=renderToStaticMarkup(React.createElement(Markdown,{ + children:"Visit [the website](https://example.com/docs) or [documentation](/docs)." + })) + assert.match(output,/href="https:\/\/example\.com\/docs"/) + assert.match(output,/rel="noopener noreferrer nofollow"/) + assert.match(output,/href="\/docs"/) + assert.doesNotMatch(output,/dangerouslySetInnerHTML/) +})