Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion apps/web/contents/addons/api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions apps/web/contents/addons/marketplace.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: Browse signed content add-ons, manage reviewed versions and underst
# Account Mode add-ons

<Callout kind="info" title="Reviewed Markdown 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.
</Callout>

## Connect a reviewed registry
Expand All @@ -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/<publisher.addon>/` 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.

Expand All @@ -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.
2 changes: 1 addition & 1 deletion apps/web/contents/addons/updates.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Callout kind="warning" title="Current milestone boundaries">
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/<publisher.addon>/` route (or `/addons/<id>/` 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.
</Callout>

For details see [Account Mode marketplace](/addons/marketplace) and [runtime API](/addons/api).
72 changes: 72 additions & 0 deletions packages/nextguide/lib/account-addon-page-template.mjs
Original file line number Diff line number Diff line change
@@ -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 (
<main className="mx-auto w-full max-w-4xl space-y-7 px-5 py-10 sm:px-10">
<div className="space-y-2 border-b pb-6">
<p className="text-xs font-medium uppercase tracking-wide text-muted-foreground">Reviewed add-on · {selected.id} · v{selected.version}</p>
<h1 className="text-3xl font-semibold tracking-tight">{selected.title}</h1>
</div>
<article className="prose prose-neutral dark:prose-invert max-w-none">
<Markdown>{selected.markdown}</Markdown>
</article>
</main>
)
}
`

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[] }> }" : "")
}
2 changes: 2 additions & 0 deletions packages/nextguide/lib/account-starter.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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),
}
}

Expand Down
2 changes: 1 addition & 1 deletion packages/nextguide/lib/extension-site-manager.d.mts
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ export declare function createAccountAddonManager(options?: {
readEnabled(input: {id: string}): Promise<null | {
id: string
version: string
manifest: Record<string, unknown>
manifest: { name: string; entrypoints: { content: string } } & Record<string, unknown>
icon: { path: string; bytes: Buffer }
pages: Array<{ path: string; markdown: string }>
}>
Expand Down
4 changes: 2 additions & 2 deletions packages/nextguide/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
},
Expand Down
3 changes: 2 additions & 1 deletion packages/nextguide/src/account/addon-marketplace.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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<Catalog | null>(null)
const [loading, setLoading] = React.useState(true)
const [busy, setBusy] = React.useState(false)
Expand Down Expand Up @@ -264,6 +264,7 @@ export function AccountAddonMarketplace() {
<CardTitle className="text-base">{addon.name}</CardTitle>
<CardDescription>{addon.id} · v{addon.version} · {addon.enabled?"Enabled":"Disabled"}</CardDescription>
</CardHeader><CardContent className="flex flex-wrap gap-2">
{addon.enabled && <a className="inline-flex h-8 items-center rounded-md border px-3 text-sm font-medium hover:bg-muted" href={(basePath==="/"?"":basePath)+"/addons/"+encodeURIComponent(addon.id)+"/"} target="_blank" rel="noopener noreferrer">Open content</a>}
{releases.some(x=>x.manifest.id===addon.id) && <Button variant="outline" size="sm"
disabled={busy} onClick={()=>setChosen(addon.id)}>Details</Button>}
<Button variant="outline" size="sm" disabled={busy || (!addon.enabled && !catalog.catalogFresh)} onClick={()=>
Expand Down
2 changes: 1 addition & 1 deletion packages/nextguide/src/account/studio.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -323,7 +323,7 @@ export function AccountStudio({ basePath = "/docs" }: { basePath?: string }) {
<Card><CardHeader><CardTitle>Upload image</CardTitle><CardDescription>PNG, JPEG, WebP or GIF, maximum 2 MB.</CardDescription></CardHeader><CardContent className="flex flex-wrap items-center gap-3"><Input type="file" accept="image/png,image/jpeg,image/webp,image/gif" className="w-full max-w-md" onChange={e => setUpload(e.target.files?.[0] || null)}/><Button onClick={uploadMedia} disabled={!upload || busy}><HardDriveUpload className="size-4"/>Upload</Button></CardContent></Card>
<Card><CardHeader><CardTitle>Images</CardTitle><CardDescription>{overview!.media.length} files</CardDescription></CardHeader><CardContent><div className="divide-y divide-border overflow-hidden rounded-lg border border-border">{overview!.media.length ? overview!.media.map(item => <div key={item.name} className="flex flex-wrap items-center gap-3 p-3"><FileText className="size-4 text-muted-foreground"/><div className="min-w-0 flex-1"><p className="truncate text-sm font-medium">{item.name}</p><p className="truncate text-xs text-muted-foreground">{item.url}</p></div><Button variant="outline" size="sm" onClick={() => navigator.clipboard.writeText(item.url)}><Copy className="size-4"/>Copy URL</Button><Button variant="destructive" size="sm" onClick={() => deleteMedia(item.name)} disabled={busy}><Trash2 className="size-4"/>Delete</Button></div>) : <p className="p-5 text-sm text-muted-foreground">No images uploaded yet.</p>}</div></CardContent></Card>
</>}
{view === "addons" && <AccountAddonMarketplace />}
{view === "addons" && <AccountAddonMarketplace basePath={basePath} />}
{view === "security" && <>
<div><h1 className="text-2xl font-semibold tracking-tight">Security</h1><p className="mt-1 text-sm text-muted-foreground">Manage authenticator access, recovery codes, and active sessions.</p></div>
<Card><CardHeader><CardTitle>Authenticator & recovery</CardTitle><CardDescription>Changing your authenticator requires a valid current code or unused recovery code. Recovery renewal requires your authenticator.</CardDescription></CardHeader><CardContent className="space-y-4"><Field label="Current code or recovery code"><Input value={securityCode} onChange={e => setSecurityCode(e.target.value)} autoComplete="off" placeholder="000000 or NG-XXXX-..." maxLength={27}/></Field><div className="flex flex-wrap gap-2"><Button variant="outline" disabled={busy || !(securityCode.length === 6 || /^NG-(?:[a-fA-F0-9]{4}-){4}[a-fA-F0-9]{4}$/.test(securityCode.trim()))} onClick={() => act(async () => { const result = await secureAction<{qrDataUrl:string;manualKey:string}>("rotate-begin", {code:securityCode.trim()});setNewQr(result.qrDataUrl);setNewSecret(result.manualKey);setSecurityCode("") })}>Change authenticator</Button><Button variant="outline" disabled={busy || securityCode.length !== 6} onClick={() => act(async () => { const result = await secureAction<{recoveryCodes:string[]}>("recovery-renew",{code:securityCode.trim()});setRecoveryCodes(result.recoveryCodes);setRecoverySaved(false);setSecurityCode("") }, "Recovery codes replaced. Save the new codes.")}>Replace recovery codes</Button></div>
Expand Down
Loading
Loading