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
22 changes: 21 additions & 1 deletion apps/web/contents/addons/v2-supply-chain.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: The signed executable release protocol, byte-level verifier and pri

# Reviewed executable v2 packages

NextGuide supports **read-only verification** of independently reviewed v2 executable archives. This does not enable production execution. The private ngapi server currently approves content-only v1 releases; v2 requires a separate registry deployment.
NextGuide supports **read-only verification and private Account Mode staging** of independently reviewed v2 executable archives, with owner permission-consent records. This does not enable production execution. The private ngapi server currently approves content-only v1 releases; v2 requires a separate registry deployment.

## Source to trusted bytes

Expand Down Expand Up @@ -38,6 +38,26 @@ The registry backend must verify independent review, reproducible build provenan

**The private ngapi service has not been upgraded by this milestone.** Before server deployment, prepare and test a private patch against the actual VPS backend, with a backup and rollback procedure.

## Account Mode private v2 staging

The Account Mode **Add-ons** page now has a separate **Executable extensions** review panel below the existing, working v1 Markdown marketplace. Once your privately hosted ngapi implements the signed v2 endpoint and its public key is pinned to the host, the panel can browse reviewed v2 releases, show independent reviewer identity, version, compatibility, exact archive digest and requested capabilities.

The server-side staging journal lives outside the Next.js project and stores only immutable, reviewed package bytes, bounded state history and version-specific permission approvals. It uses cross-process locking, atomic journal revisions and exact SHA-256 checks. Staged executable add-ons are always **blocked from execution**; no enabled flag or host-process module loader exists.

Owner actions:

- **Stage reviewed release:** Download the signed GitHub artifact, verify every byte, check compatibility and latest active signed status again, and save it privately with no grants.
- **Review and approve capabilities:** Require owner session, same-origin request, explicit consent and exact pinned version/digest/permission list. Permission approval is a record only, never an execution grant.
- **Update and rollback:** Only to signed active versions. Clear *all* prior grants and require fresh review. If the registry is expired, unreachable or revoked, the action fails closed.
- **Revoke permissions and uninstall:** Work offline to let the owner disable previously granted privileges or remove the staged add-on from the journal even when the signed registry is unavailable.
- **History:** The last 100 successful actions are stored privately. No executable code or credentials are exposed through the API response.

Trusted Account Mode server configuration uses **NEXTGUIDE_ADDON_V2_REGISTRY_URL** set to the trusted HTTPS `/v2/registry` endpoint and **NEXTGUIDE_ADDON_V2_PUBLIC_KEY_B64** containing the base64-encoded pinned PEM public key. Never place a private signing key or public registry URL in browser-provided request data.

The generated studio API uses existing site-owner session validation and origin protection for all changes. **Existing Account Mode installations must preview and explicitly apply a generated-route refresh** using the `nextguide upgrade --refresh-generated --dry-run` command and then `--refresh-generated`; NextGuide does not silently overwrite previously installed routes.

No private ngapi v2 server upgrade has happened. Until the registry service is implemented, the panel shows configuration/unavailable status and retains safe offline access to existing staged state. The released `0.0.1-alpha.2` package also does not meet manifests requiring `>=1.0.0`, intentionally preventing premature alpha staging.

## Remaining execution gates

The experimental Linux Bubblewrap runner still needs cgroup memory/process limits and independent sandbox testing. Windows has no approved secure backend yet. Browser UI execution requires separate origin/frame isolation. The private v2 installer must transactionally pin approved versions, obtain explicit site-owner grants and recheck revocations before each activation.
Expand Down
17 changes: 16 additions & 1 deletion packages/nextguide/lib/account-studio-template.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ const STUDIO_API = `// Generated by NextGuide CLI. Edit freely; NextGuide never
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 { createAccountAddonManager } from "nextguide/extensions/site-manager"
import { createAccountV2AddonManager } from "nextguide/extensions/v2-site-manager"


function response(data__DATA_TYPE__, status = 200) {
Expand Down Expand Up @@ -70,6 +71,9 @@ export async function GET(request__REQUEST_TYPE__, { params }__PARAM_TYPE__) {
if (action === "addons") {
return response(await createAccountAddonManager({ project: process.cwd() }).catalog())
}
if (action === "addons-v2") {
return response(await createAccountV2AddonManager({ 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") ?? ""))
if (action === "settings") return response(getStudioSettings(process.cwd()))
Expand All @@ -82,9 +86,20 @@ 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","addon-install","addon-toggle","addon-rollback","addon-uninstall"].includes(action))
if (!["save-page","delete-page","save-settings","save-navigation","upload-media","delete-media","addon-install","addon-toggle","addon-rollback","addon-uninstall","addon-v2-stage","addon-v2-grant","addon-v2-revoke","addon-v2-rollback","addon-v2-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-v2-")) {
// Owner session, same-origin and JSON size checked above. Never accept
// filesystem paths, module source, signing keys, or a caller-defined URL.
const manager = createAccountV2AddonManager({ project: process.cwd() })
if (action === "addon-v2-stage") return response(await manager.stage(input))
if (action === "addon-v2-grant") return response(await manager.grant(input))
if (action === "addon-v2-revoke") return response(manager.revoke(input))
if (action === "addon-v2-rollback") return response(await manager.rollback(input))
if (action === "addon-v2-uninstall") return response(manager.uninstall(input))
return response({ error: "Not found" }, 404)
}
if (action.startsWith("addon-")) {
const addons = createAccountAddonManager({ project: process.cwd() })
if (action === "addon-install") return response(await addons.install(input))
Expand Down
60 changes: 60 additions & 0 deletions packages/nextguide/lib/extension-v2-site-manager.d.mts
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
import type {
V2Capability,ReviewedV2Release
} from "./extension-v2-catalog.mjs"
export interface StagedV2Addon {
id:string
name:string
version:string
digest:string
requestedPermissions:V2Capability[]
grantedPermissions:V2Capability[]
availableVersions:string[]
reviewer:string
reviewedAt:string
execution:"blocked"
}
export interface V2Activity {
revision:number
at:string
operation:"stage"|"update"|"grant"|"revoke"|"rollback"|"uninstall"
id:string
version:string
}
export interface V2StagingCatalog {
configured:boolean
registryUnavailable:boolean
releases:Array<ReviewedV2Release & {compatible:boolean}>
installed:{revision:number;addons:StagedV2Addon[];history:V2Activity[]}
nextguideVersion:string
executionAvailable:false
}
export declare function createAccountV2AddonManager(options?:{
project?:string
dataDir?:string
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<V2StagingCatalog>
stage(input:{
id:string;version:string;expectedRevision:number;consent:true
}):Promise<{revision:number;addon:StagedV2Addon;executionAvailable:false}>
grant(input:{
id:string;version:string;digest:string
permissions:V2Capability[]
expectedRevision:number;consent:true
}):Promise<{revision:number;addon:StagedV2Addon;executionAvailable:false}>
revoke(input:{
id:string;expectedRevision:number;consent:true
}):{revision:number;addon:StagedV2Addon;executionAvailable:false}
rollback(input:{
id:string;version:string;expectedRevision:number;consent:true
}):Promise<{revision:number;addon:StagedV2Addon;executionAvailable:false}>
uninstall(input:{
id:string;expectedRevision:number;consent:true
}):{revision:number;removed:string;privateDataPreserved:true;executionAvailable:false}
}
Loading
Loading