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
4 changes: 4 additions & 0 deletions apps/web/contents/addons/_meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,10 @@
"slug": "permissions",
"title": "Permissions & security"
},
{
"slug": "v2-supply-chain",
"title": "Reviewed v2 packages"
},
{
"slug": "publishing",
"title": "Publishing & review"
Expand Down
6 changes: 6 additions & 0 deletions apps/web/contents/addons/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,12 @@ The developer publisher supports GitHub App sign-in, repository selection, prefl

The extension host is not a security sandbox. Executable add-ons require a separate isolated runner, verified artifacts and owner-approved permissions before we can offer them in the marketplace.

## Executable v2 developer and review track

The [official add-on template](https://github.com/m1nsook/NextGuide-Addons) now provides a complete **offline v2 JavaScript/TypeScript developer lab**, including Bun compilation, deterministic archive packaging, source-bound SHA-256 and an example brokered admin page. NextGuide itself can verify short-lived, independently signed v2 review metadata, the exact archive, source and compiled bytes, and safely download them through a DNS-pinned GitHub asset transport.

This **does not** make executable packages publishable through the current v1-only private ngapi registry or installable in Account Mode. See [Reviewed v2 packages](/addons/v2-supply-chain) for the signed protocol and remaining security gates.

## Documentation routes

Add-on developer docs live under `/addons` with a dedicated sidebar, search, and page navigation. For framework basics, visit [NextGuide documentation](/docs); for UI component examples, see the [component catalog](/components).
Expand Down
45 changes: 45 additions & 0 deletions apps/web/contents/addons/v2-supply-chain.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
---
title: Reviewed v2 packages
description: The signed executable release protocol, byte-level verifier and private registry rollout boundary.
---

# 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.

## Source to trusted bytes

1. Author a JavaScript/TypeScript extension in the [NextGuide-Addons template](https://github.com/m1nsook/NextGuide-Addons), 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

<CodeWindow title="NextGuide v2 signed release intake (trusted Node host only)" language="typescript" code={"import { createVerifiedV2RegistryClient } from \"nextguide/extensions/v2-catalog\"\nimport { downloadReviewedV2Release } from \"nextguide/extensions/download\"\n\nconst pinnedPublicKeyPem = process.env.NEXTGUIDE_V2_PUBLIC_KEY_PEM!\nconst registry = createVerifiedV2RegistryClient({\n registryUrl: \"https://ngapi.m1nsook.com/v2/registry\",\n pinnedPublicKeyPem,\n})\nconst envelope = await registry.fetchSignedEnvelope()\nconst result = await downloadReviewedV2Release({\n envelope, pinnedPublicKeyPem,\n id: \"acme.storage\", version: \"1.0.0\",\n})\n// 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.

## 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](https://github.com/m1nsook/NextGuide/issues/101).
16 changes: 16 additions & 0 deletions packages/nextguide/lib/extension-download.d.mts
Original file line number Diff line number Diff line change
Expand Up @@ -11,3 +11,19 @@ export declare function downloadVerifiedContentRelease(options: {
signal?: AbortSignal
timeoutMs?: number
}): Promise<Buffer>


import type { VerifiedV2Artifact } from "./extension-v2-artifacts.mjs"
/** Read-only verified executable package intake. Not an installer or runner. */
export declare function downloadReviewedV2Release(options:{
envelope:unknown
pinnedPublicKeyPem:string
id:string
version:string
resolver?:(host:string,opts:{family:number;all:boolean;verbatim:boolean})=>
Promise<Array<{address:string;family:number}>>
transport?:(...args:any[])=>any
signal?:AbortSignal
timeoutMs?:number
now?:()=>number
}):Promise<{archive:Buffer;verified:VerifiedV2Artifact}>
55 changes: 54 additions & 1 deletion packages/nextguide/lib/extension-download.mjs
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/**
* Strict, read-only downloader for *signed* v1 GitHub Release artifacts.
* Strict, read-only downloader for signed, reviewed GitHub Release artifacts.
*
* This is host-side Node code, not an add-on network capability. The target
* URL comes only from a verified signed registry release. GitHub's asset
Expand All @@ -11,6 +11,8 @@ import { lookup as dnsLookup } from "node:dns/promises"
import { request as httpsRequest } from "node:https"
import { verifySignedRegistryEnvelope } from "./extension-catalog.mjs"
import { verifyApprovedContentArchive } from "./extension-artifacts.mjs"
import { verifySignedV2RegistryEnvelope } from "./extension-v2-catalog.mjs"
import { verifyReviewedV2Archive } from "./extension-v2-artifacts.mjs"
import { isPublicExtensionIPv4 } from "./extension-network.mjs"

const MAX_BYTES = 3 * 1024 * 1024
Expand Down Expand Up @@ -187,3 +189,54 @@ export async function downloadVerifiedContentRelease({
}
return fail("DOWNLOAD_FAILED", "Could not download reviewed artifact")
}


/**
* V2 read-only review intake: downloads only an active, nonexpired, signed
* release, enforces public IPv4 DNS/TLS/CDN confinement, and verifies every
* executable/source byte. It DOES NOT install, grant permissions or run code.
*
* This is intentionally independent of the v1 Account Mode installer. The
* private registry must serve a separately signed /v2/registry index before
* any public v2 release can pass these checks.
*/
export async function downloadReviewedV2Release({
envelope,pinnedPublicKeyPem,id,version,
resolver=dnsLookup,transport=httpsRequest,
signal,timeoutMs=15000,now=()=>Date.now(),
}={}){
if(!ID.test(id) || !VERSION.test(version) ||
typeof resolver!=="function" || typeof transport!=="function" ||
!Number.isSafeInteger(timeoutMs) || timeoutMs<100 || timeoutMs>30000 ||
typeof now!=="function" || !Number.isFinite(now())){
fail("CONFIGURATION","Invalid v2 release request or trusted downloader options")
}
// Authenticate and check expiry BEFORE ANY DNS request or HTTPS fetch.
const catalog=verifySignedV2RegistryEnvelope(envelope,pinnedPublicKeyPem,{now:now()})
const release=catalog.releases.find(r=>
r.manifest.id===id && r.manifest.version===version)
if(!release || release.status!=="active" ||
release.size<32 || release.size>MAX_BYTES){
fail("NOT_APPROVED","No active, reviewed signed v2 release")
}
const first=release.assetUrl
let current=safeUrl(first,first,false)
const timer=AbortSignal.timeout(timeoutMs)
const active=signal?AbortSignal.any([signal,timer]):timer
for(let attempt=0;attempt<=MAX_REDIRECTS;attempt++){
if(active.aborted)throw cancelled()
const result=await pinnedGet(current,release.size,{resolver,transport,signal:active})
if(result.bytes){
// The v2 release key and archive/source/bundle digest are rechecked
// before returning the original bytes for private storage/review.
const verified=verifyReviewedV2Archive({
envelope,pinnedPublicKeyPem,id,version,archive:result.bytes,
now:now(),
})
return {archive:result.bytes,verified}
}
if(attempt===MAX_REDIRECTS)fail("INVALID_REDIRECT","GitHub asset redirected too many times")
current=safeUrl(result.redirect,first,true)
}
return fail("DOWNLOAD_FAILED","Reviewed v2 release could not be downloaded")
}
24 changes: 24 additions & 0 deletions packages/nextguide/lib/extension-v2-artifacts.d.mts
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
import type {
V2ExecutableManifest,V2ReviewAttestation
} from "./extension-v2-catalog.mjs"
/**
* Approved source and compiled code BYTES in memory, not an execution grant.
* Must never be imported into Next.js. OS sandbox and owner permissions required.
*/
export interface VerifiedV2Artifact {
id:string
version:string
manifest:V2ExecutableManifest
archiveSha256:string
source:{path:string;sha256:string;text:string}
compiled:{path:"dist/server.mjs";sha256:string;code:string}
review:V2ReviewAttestation
}
export declare function verifyReviewedV2Archive(options:{
envelope:unknown
pinnedPublicKeyPem:string
id:string
version:string
archive:Uint8Array
now?:number
}):VerifiedV2Artifact
193 changes: 193 additions & 0 deletions packages/nextguide/lib/extension-v2-artifacts.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,193 @@
/**
* Read-only byte verifier for reviewed NextGuide executable v2 archives.
*
* Requires a fresh Ed25519-signed private ngapi v2 release approval. Confirms
* exact GitHub asset digest and immutable independently reviewed source, build
* and capability metadata before returning bytes in memory.
*
* No path extraction, no import(), no code execution, no permission grants.
*/
import { createHash } from "node:crypto"
import { gunzipSync } from "node:zlib"
import { verifySignedV2RegistryEnvelope } from "./extension-v2-catalog.mjs"

const MAX_ARCHIVE=3*1024*1024
const MAX_TAR=3*1024*1024
const MAX_MEMBER=1024*1024
const MAX_SOURCE=512*1024
const MAX_MEMBERS=5
const HASH=/^[a-f0-9]{64}$/
const PATH=/^[A-Za-z0-9_-][A-Za-z0-9_.-]*(?:\/[A-Za-z0-9_-][A-Za-z0-9_.-]*)*$/
const PNG=Buffer.from([137,80,78,71,13,10,26,10])
const RECORD_KEYS=new Set(["path","size","sha256"])
const INDEX_KEYS=new Set([
"schemaVersion","format","manifest","source","server","icon","permissions"
])
function fail(message){throw Error("NextGuide v2 artifact: "+message)}
function record(v){return v!==null && typeof v==="object" && !Array.isArray(v)}
function sha(bytes){return createHash("sha256").update(bytes).digest("hex")}
function utf8(bytes,label){
try {return new TextDecoder("utf-8",{fatal:true}).decode(bytes)}
catch {fail("Invalid UTF-8 in "+label)}
}
function parse(bytes,label){
let obj
try {obj=JSON.parse(utf8(bytes,label))}
catch {fail("Invalid JSON in "+label)}
if(!record(obj))fail(label+" must be a JSON object")
return obj
}
function stable(value){
if(Array.isArray(value))return "["+value.map(stable).join(",")+"]"
if(record(value))return "{"+Object.keys(value).sort()
.map(key=>JSON.stringify(key)+":"+stable(value[key])).join(",")+"}"
return JSON.stringify(value)
}
function safePath(path){
return typeof path==="string" && path.length<=100 &&
PATH.test(path) && path.split("/").every(x=>
x!=="." && x!==".." && !x.startsWith(".") && !x.endsWith("."))
}
function octal(bytes){
const raw=bytes.toString("ascii").replace(/\0.*$/,"").trim()
if(!/^[0-7]+$/.test(raw))fail("Malformed octal tar field")
const n=Number.parseInt(raw,8)
if(!Number.isSafeInteger(n))fail("Oversized tar number")
return n
}
function archiveFiles(archive){
if(!(archive instanceof Uint8Array) || archive.length<32 ||
archive.length>MAX_ARCHIVE || archive[0]!==0x1f || archive[1]!==0x8b){
fail("Expected bounded gzip archive")
}
let tar
try{tar=gunzipSync(archive,{maxOutputLength:MAX_TAR})}
catch{fail("Corrupt gzip or decompression quota exceeded")}
const files=new Map()
let offset=0,closed=false
while(offset+512<=tar.length){
const header=tar.subarray(offset,offset+512)
if(header.every(x=>x===0)){
if(tar.length-offset<1024 ||
tar.subarray(offset).some(x=>x!==0))fail("Invalid tar terminator")
closed=true
break
}
if(header.subarray(257,263).toString("ascii")!=="ustar\0" ||
header.subarray(263,265).toString("ascii")!=="00" ||
header[156]!==48 ||
header.subarray(345,500).some(x=>x!==0)) {
fail("Only regular ustar files are supported (no links or extensions)")
}
const chksum=Buffer.from(header)
chksum.fill(32,148,156)
if(chksum.reduce((a,b)=>a+b,0)!==octal(header.subarray(148,156))) {
fail("Tar header checksum changed")
}
const pathEnd=header.subarray(0,100).indexOf(0)
const name=utf8(header.subarray(0,pathEnd<0?100:pathEnd),"tar path")
if(!safePath(name) || files.has(name.toLowerCase()))fail("Unsafe or colliding tar path")
const size=octal(header.subarray(124,136))
const start=offset+512,finish=start+size
const next=start+Math.ceil(size/512)*512
if(size<1 || size>MAX_MEMBER || next>tar.length ||
tar.subarray(finish,next).some(x=>x!==0))fail("Invalid archive member size or padding")
files.set(name.toLowerCase(),{name,bytes:Buffer.from(tar.subarray(start,finish))})
if(files.size>MAX_MEMBERS)fail("Too many executable archive members")
offset=next
}
if(!closed)fail("Tar end-of-archive blocks missing")
return files
}
function checkedFile(files,ref,label,maxSize){
if(!record(ref) || Object.keys(ref).sort().join(",")!=="path,sha256,size" ||
!safePath(ref.path) || !HASH.test(ref.sha256) ||
!Number.isSafeInteger(ref.size) || ref.size<1 || ref.size>maxSize) {
fail("Invalid "+label+" integrity record")
}
const found=files.get(ref.path.toLowerCase())
if(!found || found.name!==ref.path || found.bytes.length!==ref.size ||
sha(found.bytes)!==ref.sha256)fail("Reviewed "+label+" digest/size mismatch")
return found.bytes
}
function checkedIndex(files,release){
const indexMember=files.get("nextguide-integrity.json")
const manifestMember=files.get("nextguide-addon.json")
if(!indexMember || !manifestMember)fail("Missing v2 manifest or integrity index")
const index=parse(indexMember.bytes,"nextguide-integrity.json")
if(!Object.keys(index).every(x=>INDEX_KEYS.has(x)) ||
index.schemaVersion!==2 ||
index.format!=="nextguide-single-server-v2" ||
!Array.isArray(index.permissions) ||
stable(index.permissions)!==stable(release.manifest.permissions) ||
!record(index.source) ||
index.source.path!==release.review.sourcePath ||
!record(index.server) || index.server.path!=="dist/server.mjs" ||
!record(index.manifest) || index.manifest.path!=="nextguide-addon.json"){
fail("Unapproved v2 integrity descriptor or permissions")
}
const manifestBytes=checkedFile(files,index.manifest,"manifest",65536)
const sourceBytes=checkedFile(files,index.source,"source",MAX_SOURCE)
const serverBytes=checkedFile(files,index.server,"server",MAX_MEMBER)
if(sha(manifestBytes)!==release.review.manifestSha256 ||
sha(sourceBytes)!==release.review.sourceSha256 ||
sha(serverBytes)!==release.review.serverSha256) {
fail("Reviewed v2 source/bundle attestations do not match the archive")
}
const manifest=parse(manifestBytes,"nextguide-addon.json")
if(stable(manifest)!==stable(release.manifest))fail("Archive manifest differs from signed v2 release")
const names=[
"nextguide-integrity.json","nextguide-addon.json",
index.source.path,"dist/server.mjs"
]
if(manifest.icon!==undefined){
names.push(manifest.icon)
if(!record(index.icon) || index.icon.path!==manifest.icon){
fail("Icon integrity record missing or inconsistent")
}
const icon=checkedFile(files,index.icon,"PNG icon",256*1024)
if(icon.length<45 || !icon.subarray(0,8).equals(PNG) ||
icon.subarray(12,16).toString("ascii")!=="IHDR" ||
icon.readUInt32BE(8)!==13 ||
icon.readUInt32BE(16)<32 || icon.readUInt32BE(20)<32 ||
icon.readUInt32BE(16)>1024 || icon.readUInt32BE(20)>1024){
fail("Invalid reviewed PNG icon")
}
} else if(index.icon!==undefined)fail("Unexpected unsigned icon")
if(files.size!==names.length ||
new Set(names.map(x=>x.toLowerCase())).size!==names.length ||
names.some(x=>!files.has(x.toLowerCase()))) {
fail("Executable archive contains unreviewed or duplicate members")
}
const code=utf8(serverBytes,"compiled server")
// Only data is returned. Callers must still enforce grants and OS sandboxing.
return {
manifest:JSON.parse(JSON.stringify(manifest)),
archiveSha256:release.digest,
source:{path:index.source.path,sha256:index.source.sha256,
text:utf8(sourceBytes,"reviewable source")},
compiled:{path:"dist/server.mjs",sha256:index.server.sha256,code},
review:JSON.parse(JSON.stringify(release.review)),
}
}

/**
* Verifies the exact release from the signed, expiry-bound v2 catalog.
* An active release remains non-executable until an independently approved
* installed-site permission grant and actual secure OS sandbox exist.
*/
export function verifyReviewedV2Archive({
envelope,pinnedPublicKeyPem,id,version,archive,now=Date.now(),
}={}){
const catalog=verifySignedV2RegistryEnvelope(envelope,pinnedPublicKeyPem,{now})
const release=catalog.releases.find(r=>
r.manifest.id===id && r.manifest.version===version)
if(!release || release.status!=="active")fail("V2 release is missing or revoked")
if(!(archive instanceof Uint8Array) ||
archive.byteLength!==release.size ||
sha(archive)!==release.digest){
fail("Archive SHA-256 or size differs from signed v2 review")
}
const content=checkedIndex(archiveFiles(archive),release)
return {...content,id,version}
}
Loading
Loading