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
1 change: 1 addition & 0 deletions apps/web/contents/addons/api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ The single `nextguide` package now exposes these building blocks:
| `nextguide/extensions/artifacts` | Read-only v1 content archive verifier: signature, exact release size/hash and safe tar members; does not install or execute files |
| `nextguide/extensions/download` | Strict signed GitHub artifact downloader with pinned public-IPv4 DNS, TLS, and limited trusted GitHub CDN redirects |
| `nextguide/extensions/install-state` | Server-only Account Mode journal for signed v1 content releases, version pinning, disable, verified rollback, and uninstall without executing code |
| `nextguide/extensions/site-manager` | Owner-authenticated host-side orchestration: signed discovery, safe download, lifecycle actions and revision checks |
| `nextguide/extensions/network` | Restricted, host-only outbound HTTPS adapter with pinned DNS and response limits |
| `nextguide/extensions/isolation` | Experimental Linux bubblewrap/prlimit process launcher for SHA-256-pinned compiled modules; no Windows or automatic fallback |

Expand Down
49 changes: 25 additions & 24 deletions apps/web/contents/addons/marketplace.mdx
Original file line number Diff line number Diff line change
@@ -1,41 +1,42 @@
---
title: Account Mode add-on discovery
description: Read-only verified registry browsing in the Account Mode studio; installation is still planned.
title: Account Mode marketplace
description: Browse signed content add-ons, manage reviewed versions and understand executable-extension restrictions.
---

# Account Mode add-ons

<Callout kind="info" title="Signed catalog preview">
The Account Mode studio now includes **Add-ons** in the sidebar. Once configured, it can browse current approved **content-only v1** registry releases, filter categories, search publishers and open a full add-on detail view. Listings are verified with the site's pinned Ed25519 key on the server before being shown. **Install, enable, update and uninstall are not implemented.**
<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.
</Callout>

## Connect the signed catalog
## Connect a reviewed registry

Set the following environment variables on your persistent Account Mode Next.js server:
Configure the trusted catalog on a persistent Account Mode Node server:

<CodeWindow title="Account Mode environment configuration" language="bash" code={"NEXTGUIDE_ADDON_REGISTRY_URL=https://your-approved-registry.example/v1/registry\nNEXTGUIDE_ADDON_REGISTRY_PUBLIC_KEY_B64=YOUR_TRUSTED_BASE64_ENCODED_ED25519_PEM"} />
<CodeWindow title="Account Mode registry environment" language="bash" code={"NEXTGUIDE_ADDON_REGISTRY_URL=https://your-approved-registry.example/v1/registry\nNEXTGUIDE_ADDON_REGISTRY_PUBLIC_KEY_B64=YOUR_BASE64_ENCODED_TRUSTED_PUBLIC_ED25519_PEM"} />

The Base64 value is the trusted registry's **public** Ed25519 PEM key, encoded as UTF-8 then Base64. Obtain the exact public key through a trusted, independent channel; never accept a signing key merely because an unsigned registry response supplied it. Do not put the registry configuration in a `NEXT_PUBLIC_` variable.
The Base64 value contains a PEM-format **public** key, retrieved through a separately trusted channel. Never load the signing key from unsigned registry metadata or expose the configuration through a `NEXT_PUBLIC_` variable. Your `NEXTGUIDE_DATA_DIR` must point outside the Next.js site, and the runtime must have access to its own persistent private storage.

If those variables are missing, the Add-ons page explains that the catalog connection is not configured. If the signature or endpoint is invalid, the server rejects the response; it never falls back to unsigned data. Only a logged-in Account Mode owner can access the discovery API.
The registry must issue a newly signed index at least once an hour: stale metadata refuses installation, enabling and rollback, rather than silently using potentially revoked information.

## Current and future actions
## Install and manage content

| Action | Status |
| --- | --- |
| Discover | Search and filter approved content-only releases in Account Mode |
| Inspect | Full detail view with author, signed release, compatibility, license and requested permissions |
| Install | Planned: verify artifact bytes, request permission approval and persist installed state |
| Configure | Planned: store scoped settings and trusted credential handles |
| Enable/disable | Planned: start and stop a reviewed extension safely |
| Update | Planned: permission-diff review and transactional integrity checks |
| Rollback | Planned: restore a previously reviewed, compatible version |
| Uninstall | Planned: remove files safely, with a private-data retention choice |
1. Sign in to Account Mode and open **Add-ons**.
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.
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.

The existing extension capability broker, isolated runner prototype and signed content archive verifier are foundations. They do not make executable marketplace add-ons safe to install today.
<Callout kind="warning" title="Compatibility and executable permissions">
Published v1 examples currently declare NextGuide `>=1.0.0 <2.0.0`. A site still running `0.0.1-alpha.2` is intentionally shown as **incompatible**, not allowed to bypass the publisher's declared version range. This is a release gate, not a failed install. Code-capable extensions, React widgets, secret handles and server jobs still require additional review, sandbox hardening and permission approvals.
</Callout>

## Security and rollback

## Security requirements before executable add-ons
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.

Executable add-ons require independent code review, properly signed v2 artifacts, hardened OS sandboxing and resource controls, and browser-frame isolation for custom React components. The private registry service remains separately deployed and is **not** part of this public repository.
The UI uses NextGuide's native Account Mode components. No Docker requirement or new npm package is introduced.

Track implementation in [roadmap issue #101](https://github.com/m1nsook/NextGuide/issues/101). To publish a currently supported content add-on, start with [Getting started](/addons/getting-started).
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.
43 changes: 24 additions & 19 deletions apps/web/contents/addons/updates.mdx
Original file line number Diff line number Diff line change
@@ -1,34 +1,39 @@
---
title: Updates & removal
description: Publish new versions, revoke old releases and understand add-on withdrawal.
title: Updates and removal
description: Publisher updates, Account Mode version pinning and verified rollback for content add-ons.
---

# Updates and removal

NextGuide keeps GitHub release artifacts immutable. Every update is independently checked and must be manually approved before it becomes available in the signed catalog.
## Publisher workflow

## Publish an update
Every new add-on version requires its own independently reviewed immutable GitHub Release, committed source provenance and signed registry approval.

1. Update the add-on files and increase `version` in `nextguide-addon.json`.
2. Commit and push changes to the same GitHub repository.
3. Open the [NextGuide Publisher GitHub App](https://github.com/apps/nextguide-publisher) and select the repository through its publisher portal.
4. Validate the release and submit the new version.
5. Check the pending review and wait for approval.
1. Increase `version` in `nextguide-addon.json`.
2. Commit and push the changed files to the source repository.
3. Open the [NextGuide Publisher GitHub App](https://github.com/apps/nextguide-publisher) and select the repository.
4. Validate and submit the new version for independent review.
5. Wait for the signed registry to contain the approved release.

<CodeWindow title="Version update example" language="json" code={"{\n \"id\": \"acme.hello-world\",\n \"version\": \"0.2.0\",\n \"repository\": \"https://github.com/acme/hello-world\"\n}"} />
Do not overwrite existing GitHub Release assets to make a silent change. Create a new version instead.

## Removing a published add-on
## Account Mode installation lifecycle

A verified publisher can withdraw their own add-on; authorized moderation can revoke releases. These are **catalog actions**: approved versions are marked revoked in the signed index, and pending submissions are withdrawn.
The owner-facing **Add-ons** page can install, enable/disable, update, roll back and uninstall **content-only v1** releases when the site's NextGuide package satisfies their declared compatibility range.

Removal does **not** silently delete GitHub Releases, erase the review audit log, or uninstall copies already installed on user sites.
| Action | What happens |
| --- | --- |
| Install | Recheck signed registry, verify exact remote archive and place content in private storage, initially disabled |
| Enable | Recheck latest signed approval and local integrity before marking content enabled |
| Disable | Mark content disabled without deleting settings |
| Update | Recheck the newer reviewed version, then atomically advance the pinned version |
| Rollback | Verify an already stored, still-approved version and restore it in a disabled state |
| Uninstall | Remove the installed record; preserve private add-on settings and historical blobs for recovery |

## Future in-site update manager
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.

Account Mode's planned marketplace will separately support installing, enabling, disabling, updating, rolling back and uninstalling add-ons. It must verify the artifact digest, compatible NextGuide version, signed catalog and permissions, and must handle revoked releases safely.

<Callout kind="info" title="Publisher vs. installer">
The [publisher GitHub App](https://github.com/apps/nextguide-publisher) is for **developers**. The planned marketplace belongs inside **each site's own Account Mode dashboard**.
<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.
</Callout>

Read [Marketplace (planned)](/addons/marketplace) and [Permissions & security](/addons/permissions).
For details see [Account Mode marketplace](/addons/marketplace) and [runtime API](/addons/api).
37 changes: 29 additions & 8 deletions packages/nextguide/lib/account-studio-template.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
const STUDIO_API = `// Generated by NextGuide CLI. Edit freely; NextGuide never overwrites these files.
import { ACCOUNT_COOKIE, AccountError, verifySession, sameOrigin } from "nextguide/account/server"
import { listStudioPages, readStudioPage, saveStudioPage, deleteStudioPage, getStudioNavigation, setStudioNavigation, getStudioSettings, saveStudioSettings, listStudioMedia, uploadStudioMedia, deleteStudioMedia } from "nextguide/account/cms"
import { createVerifiedRegistryClient } from "nextguide/extensions/catalog"
import { createAccountAddonManager } from "nextguide/extensions/site-manager"


function response(data__DATA_TYPE__, status = 200) {
Expand Down Expand Up @@ -32,6 +32,24 @@ async function body(request__REQUEST_TYPE__, limit = 3_000_000) {
}
function errorResponse(error__ERROR_TYPE__) {
if (error instanceof AccountError) return response({ error: error.message }, error.status)
const allowed = new Map([
["INVALID_REQUEST",400], ["CONSENT_REQUIRED",403], ["INCOMPATIBLE",409],
["NOT_APPROVED",409], ["DOWNGRADE",409], ["NOT_INSTALLED",404], ["CONFLICT",409],
["CAPACITY",409], ["PERMISSION_DENIED",403], ["STALE_CATALOG",503], ["BUSY",503],
["MODE_DENIED",403], ["MISSING_ARTIFACT",409], ["CORRUPT_ARTIFACT",409],
["NO_REGISTRY",503], ["UNSAFE_STORAGE",503], ["DAMAGED_STATE",503],
])
const code = error && typeof error === "object" && "code" in error ? String(error.code) : ""
if (allowed.has(code)) {
const safe = new Map([
["CONFLICT","Add-on state changed. Refresh and try again."],
["NOT_APPROVED","This release is not approved, is revoked or is incompatible."],
["STALE_CATALOG","The signed registry metadata needs to be refreshed."],
["INCOMPATIBLE","This add-on is incompatible with your installed NextGuide version."],
["CONSENT_REQUIRED","Confirm the requested installation change before continuing."],
])
return response({ error: safe.get(code) || "Add-on operation denied (" + code + ")." }, allowed.get(code) || 503)
}
console.error("[nextguide/studio] Studio error", error instanceof Error ? error.name : "Unknown")
return response({ error: "Studio service failed. Check server logs." }, 503)
}
Expand All @@ -50,12 +68,7 @@ export async function GET(request__REQUEST_TYPE__, { params }__PARAM_TYPE__) {
media: listStudioMedia(process.cwd()),
})
if (action === "addons") {
const registryUrl = process.env.NEXTGUIDE_ADDON_REGISTRY_URL
const encodedPublicKey = process.env.NEXTGUIDE_ADDON_REGISTRY_PUBLIC_KEY_B64
if (!registryUrl || !encodedPublicKey) return response({ configured: false, releases: [] })
const pinnedPublicKeyPem = Buffer.from(encodedPublicKey, "base64").toString("utf8")
const registry = createVerifiedRegistryClient({ registryUrl, pinnedPublicKeyPem })
return response({ configured: true, releases: await registry.listApproved() })
return response(await createAccountAddonManager({ project: process.cwd() }).catalog())
}
if (action === "page") return response(readStudioPage(process.cwd(), url.searchParams.get("slug") ?? ""))
if (action === "navigation") return response(getStudioNavigation(process.cwd(), url.searchParams.get("folder") ?? ""))
Expand All @@ -69,9 +82,17 @@ export async function POST(request__REQUEST_TYPE__, { params }__PARAM_TYPE__) {
if (!authorized(request)) return response({ error: "Sign in to access the editor." }, 401)
if (!sameOrigin(request)) return response({ error: "Invalid origin." }, 403)
const action = (await params).action
if (!["save-page","delete-page","save-settings","save-navigation","upload-media","delete-media"].includes(action))
if (!["save-page","delete-page","save-settings","save-navigation","upload-media","delete-media","addon-install","addon-toggle","addon-rollback","addon-uninstall"].includes(action))
return response({ error: "Not found" }, 404)
const input = await body(request, action === "upload-media" ? 3_000_000 : 450_000)
if (action.startsWith("addon-")) {
const addons = createAccountAddonManager({ project: process.cwd() })
if (action === "addon-install") return response(await addons.install(input))
if (action === "addon-toggle") return response(await addons.toggle(input))
if (action === "addon-rollback") return response(await addons.rollback(input))
if (action === "addon-uninstall") return response(addons.uninstall(input))
return response({ error: "Not found" }, 404)
}
if (action === "save-page") return response(saveStudioPage(process.cwd(), input))
if (action === "delete-page") return response(deleteStudioPage(process.cwd(), input.slug, input.version))
if (action === "save-settings") return response(saveStudioSettings(process.cwd(), input))
Expand Down
8 changes: 6 additions & 2 deletions packages/nextguide/lib/extension-catalog.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ export function createVerifiedRegistryClient({ registryUrl, pinnedPublicKeyPem,
const publicKey = createPublicKey(pinnedPublicKeyPem)
if (publicKey.asymmetricKeyType !== "ed25519") fail("Pinned key must be Ed25519")
return {
async fetchVerified() {
async fetchSignedEnvelope() {
const response = await fetchImpl(url.toString(), {
method: "GET", redirect: "error", cache: "no-store",
signal: AbortSignal.timeout(8000),
Expand All @@ -142,7 +142,11 @@ export function createVerifiedRegistryClient({ registryUrl, pinnedPublicKeyPem,
let envelope
try { envelope = JSON.parse(Buffer.concat(chunks).toString("utf8")) }
catch { fail("Invalid registry response JSON") }
return verifySignedRegistryEnvelope(envelope, pinnedPublicKeyPem)
verifySignedRegistryEnvelope(envelope, pinnedPublicKeyPem)
return envelope
},
async fetchVerified() {
return verifySignedRegistryEnvelope(await this.fetchSignedEnvelope(), pinnedPublicKeyPem)
},
async listApproved() {
return listVerifiedAddons(await this.fetchVerified())
Expand Down
66 changes: 66 additions & 0 deletions packages/nextguide/lib/extension-site-manager.d.mts
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
import type { InstalledAddon } from "./extension-install-state.mjs"
export type AccountAddonCatalog = {
configured: boolean
catalogFresh: boolean
releases: Array<{
manifest: {
id: string
name: string
version: string
category: string
compatibility: { mode: "account"; nextguide: string }
permissions: string[]
}
compatible: boolean
digest: string
size: number
reviewer: string
status: string
[key: string]: unknown
}>
installed: { revision: number; addons: InstalledAddon[] }
nextguideVersion: string
}
export declare function createAccountAddonManager(options?: {
project?: string
dataDir?: string
/** Trusted test override; installed package version is used by default. */
nextguideVersion?: string
registryUrl?: string
pinnedPublicKeyPem?: string
now?: () => number
registryFetch?: typeof fetch
resolver?: (...args: any[]) => Promise<Array<{ address: string; family: number }>>
transport?: (...args: any[]) => any
}): {
catalog(): Promise<AccountAddonCatalog>
install(input: {
id: string
version: string
expectedRevision: number
consent: true
}): Promise<{revision: number; addon: InstalledAddon}>
toggle(input: {
id: string
enabled: boolean
expectedRevision: number
}): Promise<{revision: number; addon: InstalledAddon}>
rollback(input: {
id: string
version: string
expectedRevision: number
consent: true
}): Promise<{revision: number; addon: InstalledAddon}>
uninstall(input: {
id: string
expectedRevision: number
consent: true
}): {revision: number; removed: string; privateDataPreserved: true}
readEnabled(input: {id: string}): Promise<null | {
id: string
version: string
manifest: Record<string, unknown>
icon: { path: string; bytes: Buffer }
pages: Array<{ path: string; markdown: string }>
}>
}
Loading
Loading