Reviewed executable v2 packages

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

1. Author a JavaScript/TypeScript extension in the NextGuide-Addons template, then build the deterministic v2 archive.
2. Publish an immutable GitHub Release linked to a specific source commit.
3. An independent reviewer validates original source, exact bundle, requested capabilities, reproducible build and package integrity.
4. The private ngapi operator signs the reviewed release with Ed25519. The signature binds repository, commit, manifest, source SHA-256, compiled bundle SHA-256, reviewer, requested permissions and active/revoked status.
5. An Account Mode host pins the public verification key, fetches a short-lived signed index and downloads only that exact approved GitHub artifact through DNS-pinned HTTPS.
6. Installation and execution still require an explicit site-owner permission grant and production-approved OS isolation.

Versioned registry contract

The future signed index lives at the separate HTTPS path /v2/registry and has schemaVersion 2, issue and expiration timestamps (maximum six-hour signed lifetime), and a list of immutable reviewed releases. Its signatures and release formats cannot be confused with the working v1 content-only format.

Every signed release must include a complete v2 Account Mode manifest and a review attestation with the original commit, review identity, original source and compiled bundle digests. The archive uses the narrow single-file server developer format: original source file, compiled server module, exact manifest, and a per-member SHA-256 integrity descriptor. An optional signed PNG icon is supported.

The verifier rejects unapproved executable permissions, revoked or expired metadata, invalid keys and signatures, mismatching byte hashes, unexpected archive files, symlinks, unsafe paths and decompression bombs.

Verify a release without executing it

import { createVerifiedV2RegistryClient } from "nextguide/extensions/v2-catalog"
import { downloadReviewedV2Release } from "nextguide/extensions/download"

const pinnedPublicKeyPem = process.env.NEXTGUIDE_V2_PUBLIC_KEY_PEM!
const registry = createVerifiedV2RegistryClient({
  registryUrl: "https://ngapi.m1nsook.com/v2/registry",
  pinnedPublicKeyPem,
})
const envelope = await registry.fetchSignedEnvelope()
const result = await downloadReviewedV2Release({
  envelope, pinnedPublicKeyPem,
  id: "acme.storage", version: "1.0.0",
})
// The verified compiled bytes are DATA. Never import or run them here.

For already-downloaded archives use the nextguide/extensions/v2-artifacts verifier. The nextguide/extensions/v2-catalog module also provides a permission-diff helper; identifying newly requested permissions is not a grant.

The signed catalog and archive are checked independently, without writing third-party code to disk or importing it into the Next.js host.

Private ngapi deployment requirements

The registry backend must verify independent review, reproducible build provenance and immutable GitHub assets before signing. Signed indexes need expiration, revocation and signing-key rotation procedures. Server-side authorization must never accept a publisher-supplied reviewer field as proof without authenticated staff approval. No private keys or private registry server implementation belong in the public NextGuide package.

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.

Do not treat an Ed25519 signature as permission to execute JavaScript. See the security roadmap.