@nggaigc/cli 0.1.0

package/README.md

@@ -0,0 +1,11 @@
+# @nggaigc/cli
+
+NGGAIGC Codex Skill 的 Windows 一命令安装器。
+
+```powershell
+npx --yes @nggaigc/cli@latest install
+```
+
+安装器会先验证内置 Plugin 的 Ed25519 签名、归档哈希和逐文件哈希，再原子安装 Skill。首次运行会打开 NGGAIGC 浏览器授权页；短期授权值只通过浏览器片段和本机回环请求返回，设备凭据只通过标准输入进入 Windows Credential Manager。安装器不接受 API Key、授权码或设备凭据参数，也不从环境变量读取这些值。
+
+当前候选支持 Windows x64/arm64，并要求 Node.js 22.13 或更高的 22.x 版本。

package/dist/bin.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { CliError } from "./errors.js";
+import { runInstall } from "./install.js";
+const messages = {
+    authorizing: "正在打开浏览器，请在 NGGAIGC 页面确认连接…",
+    connected: "NGGAIGC Skill 已安装，设备连接验证成功。",
+    installing: "正在安全安装已签名的 NGGAIGC Skill…",
+    verifying: "正在验证 NGGAIGC 签名安装包…",
+};
+const errorMessages = {
+    ARCHIVE_EXTRACTION_FAILED: "安装包无法安全解压，请稍后重试。",
+    BROWSER_AUTHORIZATION_FAILED: "浏览器授权未完成，请重新运行安装命令。",
+    CONNECTION_VERIFICATION_FAILED: "设备连接验证失败，请重新运行安装命令。",
+    INSTALLATION_FAILED: "本地安装未完成，已有文件不会被静默覆盖。",
+    INVALID_INPUT: "命令格式无效。请仅运行：npx --yes @nggaigc/cli@latest install",
+    PACKAGE_VERIFICATION_FAILED: "安装包签名或完整性验证失败，已停止安装。",
+    RUNTIME_UNSUPPORTED: "请使用 Node.js 22.13 或更高的 22.x 版本。",
+    UNSUPPORTED_PLATFORM: "当前候选仅支持 Windows x64 或 Windows arm64。",
+};
+export async function main(args) {
+    if (args.length !== 1 || args[0] !== "install") {
+        process.stderr.write(`${errorMessages.INVALID_INPUT}\n`);
+        return 1;
+    }
+    try {
+        await runInstall({
+            reporter: (event) => process.stdout.write(`${messages[event]}\n`),
+        });
+        return 0;
+    }
+    catch (error) {
+        const code = error instanceof CliError ? error.code : "INSTALLATION_FAILED";
+        process.stderr.write(`${errorMessages[code] ?? errorMessages.INSTALLATION_FAILED}\n`);
+        return 1;
+    }
+}
+process.exitCode = await main(process.argv.slice(2));

package/dist/bundle.js

@@ -0,0 +1,247 @@
+import { spawn } from "node:child_process";
+import { createHash, createPublicKey, verify as verifySignature, } from "node:crypto";
+import { lstat, readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError } from "./errors.js";
+const manifestKeys = [
+    "artifactId",
+    "artifactPath",
+    "fileCount",
+    "files",
+    "platforms",
+    "schemaVersion",
+    "sha256",
+    "signature",
+    "sizeBytes",
+    "sourceCommit",
+    "version",
+];
+const signatureKeys = ["algorithm", "keyId", "scope", "value"];
+const archiveName = "nggaigc-plugin-1.1.1.zip";
+const trustedKeyId = "ngg-signing-skill-release-1";
+const trustedKeySpkiSha256 = "3d7450a1a26785d900be03e52b4b7d0b2e84fe4e4fcb6f2e903c1371b0b96cee";
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function exactKeys(value, expected) {
+    return (JSON.stringify(Object.keys(value).sort()) ===
+        JSON.stringify([...expected].sort()));
+}
+function safeArchivePath(value) {
+    return (value.length >= 1 &&
+        value.length <= 240 &&
+        !value.startsWith("/") &&
+        !value.includes("\\") &&
+        !value.includes("\0") &&
+        value
+            .split("/")
+            .every((part) => part !== "" && part !== "." && part !== ".."));
+}
+async function json(file) {
+    try {
+        return JSON.parse(await readFile(file, "utf8"));
+    }
+    catch {
+        throw new CliError("PACKAGE_VERIFICATION_FAILED");
+    }
+}
+export async function verifyBundle(input) {
+    try {
+        const manifestValue = await json(input.manifest);
+        const trustValue = await json(input.trust);
+        const signature = record(manifestValue)
+            ? manifestValue.signature
+            : undefined;
+        if (!record(manifestValue) ||
+            !exactKeys(manifestValue, manifestKeys) ||
+            manifestValue.schemaVersion !== "nggaigc-plugin-package/v1" ||
+            manifestValue.artifactId !== "plugin.nggaigc" ||
+            manifestValue.version !== "1.1.1" ||
+            manifestValue.artifactPath !== `packages/plugins/${archiveName}` ||
+            typeof manifestValue.sourceCommit !== "string" ||
+            !/^[a-f0-9]{40}$/.test(manifestValue.sourceCommit) ||
+            typeof manifestValue.sha256 !== "string" ||
+            !/^[a-f0-9]{64}$/.test(manifestValue.sha256) ||
+            typeof manifestValue.sizeBytes !== "number" ||
+            !Number.isSafeInteger(manifestValue.sizeBytes) ||
+            manifestValue.sizeBytes < 1 ||
+            manifestValue.sizeBytes > 64 * 1024 * 1024 ||
+            typeof manifestValue.fileCount !== "number" ||
+            !Number.isSafeInteger(manifestValue.fileCount) ||
+            !Array.isArray(manifestValue.platforms) ||
+            JSON.stringify(manifestValue.platforms) !==
+                JSON.stringify(["win32-x64", "win32-arm64"]) ||
+            !record(manifestValue.files) ||
+            Object.keys(manifestValue.files).length !== manifestValue.fileCount ||
+            Object.entries(manifestValue.files).some(([name, digest]) => !safeArchivePath(name) ||
+                typeof digest !== "string" ||
+                !/^[a-f0-9]{64}$/.test(digest)) ||
+            !record(signature) ||
+            !exactKeys(signature, signatureKeys) ||
+            signature.algorithm !== "ed25519" ||
+            signature.scope !== "artifact-bytes" ||
+            signature.keyId !== trustedKeyId ||
+            typeof signature.value !== "string" ||
+            !record(trustValue) ||
+            !exactKeys(trustValue, ["keys", "schemaVersion"]) ||
+            trustValue.schemaVersion !== "ngg-trusted-package-keys/v1" ||
+            !Array.isArray(trustValue.keys))
+            throw new Error();
+        const trustKeys = trustValue.keys;
+        const trustedKey = trustKeys.find((value) => record(value) &&
+            exactKeys(value, ["keyId", "publicKeyPem"]) &&
+            value.keyId === signature.keyId &&
+            typeof value.publicKeyPem === "string");
+        if (!record(trustedKey) || typeof trustedKey.publicKeyPem !== "string")
+            throw new Error();
+        const publicKey = createPublicKey(trustedKey.publicKeyPem);
+        const publicKeyFingerprint = createHash("sha256")
+            .update(publicKey.export({ type: "spki", format: "der" }))
+            .digest("hex");
+        if (publicKeyFingerprint !== trustedKeySpkiSha256)
+            throw new Error();
+        const archiveFacts = await lstat(input.archive);
+        if (!archiveFacts.isFile() || archiveFacts.isSymbolicLink())
+            throw new Error();
+        const archive = await readFile(input.archive);
+        if (archive.length !== manifestValue.sizeBytes ||
+            createHash("sha256").update(archive).digest("hex") !==
+                manifestValue.sha256 ||
+            !verifySignature(null, archive, publicKey, Buffer.from(signature.value, "base64")))
+            throw new Error();
+        return {
+            archive: path.resolve(input.archive),
+            files: manifestValue.files,
+            version: manifestValue.version,
+        };
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CliError("PACKAGE_VERIFICATION_FAILED");
+    }
+}
+function powershellPath() {
+    return path.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+}
+export async function extractBundle(archive, destination) {
+    const script = fileURLToPath(new URL("../scripts/expand-archive.ps1", import.meta.url));
+    await new Promise((resolve, reject) => {
+        const child = spawn(powershellPath(), [
+            "-NoLogo",
+            "-NoProfile",
+            "-NonInteractive",
+            "-File",
+            script,
+            "-Archive",
+            archive,
+            "-Destination",
+            destination,
+        ], {
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: {
+                SystemRoot: process.env.SystemRoot,
+                LOCALAPPDATA: process.env.LOCALAPPDATA,
+                USERPROFILE: process.env.USERPROFILE,
+                PATH: process.env.PATH,
+            },
+        });
+        let bytes = 0;
+        let failed = false;
+        const limit = (chunk) => {
+            bytes += chunk.length;
+            if (bytes > 64 * 1024) {
+                failed = true;
+                child.kill();
+            }
+        };
+        child.stdout.on("data", limit);
+        child.stderr.on("data", limit);
+        const timer = setTimeout(() => {
+            failed = true;
+            child.kill();
+        }, 30_000);
+        timer.unref();
+        child.once("error", () => {
+            clearTimeout(timer);
+            reject(new CliError("ARCHIVE_EXTRACTION_FAILED"));
+        });
+        child.once("exit", (code) => {
+            clearTimeout(timer);
+            if (failed || code !== 0)
+                reject(new CliError("ARCHIVE_EXTRACTION_FAILED"));
+            else
+                resolve();
+        });
+    });
+}
+async function entries(directory, prefix = "") {
+    let children;
+    try {
+        children = await readdir(directory, { withFileTypes: true });
+    }
+    catch {
+        throw new CliError("PACKAGE_VERIFICATION_FAILED");
+    }
+    const result = [];
+    for (const child of children) {
+        const relative = prefix ? `${prefix}/${child.name}` : child.name;
+        const absolute = path.join(directory, child.name);
+        const facts = await lstat(absolute);
+        if (facts.isSymbolicLink())
+            throw new CliError("PACKAGE_VERIFICATION_FAILED");
+        if (facts.isDirectory())
+            result.push(...(await entries(absolute, relative)));
+        else if (facts.isFile())
+            result.push(relative);
+        else
+            throw new CliError("PACKAGE_VERIFICATION_FAILED");
+    }
+    return result.sort();
+}
+export async function verifyExtractedBundle(directory, expected) {
+    try {
+        const actual = await entries(directory);
+        const expectedNames = Object.keys(expected).sort();
+        if (JSON.stringify(actual) !== JSON.stringify(expectedNames))
+            throw new Error();
+        for (const name of expectedNames) {
+            const file = path.resolve(directory, ...name.split("/"));
+            const relative = path.relative(path.resolve(directory), file);
+            if (relative.startsWith(`..${path.sep}`) ||
+                relative === ".." ||
+                path.isAbsolute(relative))
+                throw new Error();
+            const bytes = await readFile(file);
+            if (createHash("sha256").update(bytes).digest("hex") !== expected[name])
+                throw new Error();
+        }
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CliError("PACKAGE_VERIFICATION_FAILED");
+    }
+}
+export async function verifyInstalledSkill(directory, bundleFiles) {
+    const prefix = "skills/nggaigc/";
+    const expected = Object.fromEntries(Object.entries(bundleFiles)
+        .filter(([name]) => name.startsWith(prefix))
+        .map(([name, digest]) => [name.slice(prefix.length), digest]));
+    try {
+        const actual = await entries(directory);
+        const allowed = [...Object.keys(expected), ".nggaigc-install.json"].sort();
+        if (JSON.stringify(actual) !== JSON.stringify(allowed))
+            throw new Error();
+        for (const [name, digest] of Object.entries(expected)) {
+            const bytes = await readFile(path.resolve(directory, ...name.split("/")));
+            if (createHash("sha256").update(bytes).digest("hex") !== digest)
+                throw new Error();
+        }
+    }
+    catch {
+        throw new CliError("INSTALLATION_FAILED");
+    }
+}

package/dist/errors.js

@@ -0,0 +1,17 @@
+export class CliError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "CliError";
+    }
+}
+export function fixedErrorCode(error) {
+    if (error !== null &&
+        typeof error === "object" &&
+        "code" in error &&
+        typeof error.code === "string" &&
+        /^[A-Z0-9_]{1,64}$/.test(error.code))
+        return error.code;
+    return undefined;
+}

package/dist/install.js

@@ -0,0 +1,167 @@
+import { createRequire } from "node:module";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { extractBundle, verifyBundle, verifyExtractedBundle, verifyInstalledSkill, } from "./bundle.js";
+import { CliError, fixedErrorCode } from "./errors.js";
+function defaultBundle() {
+    const vendor = fileURLToPath(new URL("../vendor/", import.meta.url));
+    return {
+        archive: path.join(vendor, "nggaigc-plugin-1.1.1.zip"),
+        manifest: path.join(vendor, "manifest.json"),
+        trust: path.join(vendor, "trusted-keys.json"),
+    };
+}
+function validateRuntime(platform, architecture) {
+    const [major, minor] = process.versions.node.split(".").map(Number);
+    if (major !== 22 || (minor ?? 0) < 13)
+        throw new CliError("RUNTIME_UNSUPPORTED");
+    if (platform !== "win32")
+        throw new CliError("UNSUPPORTED_PLATFORM");
+    if (architecture !== "x64" && architecture !== "arm64")
+        throw new CliError("UNSUPPORTED_PLATFORM");
+}
+function safeProfile(value) {
+    if (!path.isAbsolute(value) || /[\0\r\n]/.test(value))
+        throw new CliError("INVALID_INPUT");
+    return path.resolve(value);
+}
+async function installedVersion(target) {
+    try {
+        const marker = JSON.parse(await readFile(path.join(target, ".nggaigc-install.json"), "utf8"));
+        if (marker === null ||
+            typeof marker !== "object" ||
+            Array.isArray(marker) ||
+            JSON.stringify(Object.keys(marker).sort()) !==
+                JSON.stringify(["installedAt", "schemaVersion", "version"]) ||
+            !("schemaVersion" in marker) ||
+            marker.schemaVersion !== "nggaigc-local-install/v1" ||
+            !("installedAt" in marker) ||
+            typeof marker.installedAt !== "string" ||
+            !Number.isFinite(Date.parse(marker.installedAt)) ||
+            !("version" in marker) ||
+            typeof marker.version !== "string" ||
+            !/^\d+\.\d+\.\d+$/.test(marker.version))
+            return undefined;
+        return marker.version;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function installSkill(installer, source, profile, expectedVersion, bundleFiles) {
+    const target = path.join(profile, ".agents", "skills", "nggaigc");
+    try {
+        const result = await installer.main(["install", "--profile", profile], {
+            source,
+        });
+        if (result.status !== "installed" || result.version !== expectedVersion)
+            throw new Error();
+        await verifyInstalledSkill(target, bundleFiles);
+        return "installed";
+    }
+    catch (error) {
+        if (fixedErrorCode(error) !== "ALREADY_INSTALLED")
+            throw new CliError("INSTALLATION_FAILED");
+    }
+    const currentVersion = await installedVersion(target);
+    if (!currentVersion)
+        throw new CliError("INSTALLATION_FAILED");
+    if (currentVersion === expectedVersion) {
+        await verifyInstalledSkill(target, bundleFiles);
+        return "unchanged";
+    }
+    try {
+        const result = await installer.main(["update", "--profile", profile], {
+            source,
+        });
+        if (result.status !== "updated" || result.version !== expectedVersion)
+            throw new Error();
+        await verifyInstalledSkill(target, bundleFiles);
+        return "updated";
+    }
+    catch {
+        throw new CliError("INSTALLATION_FAILED");
+    }
+}
+async function connect(launcher, options, report, probe) {
+    let configured;
+    try {
+        if (probe)
+            configured = await probe(launcher);
+        else {
+            const status = await launcher.main(["status"]);
+            if (status === null ||
+                typeof status !== "object" ||
+                !("status" in status) ||
+                status.status !== "connected")
+                throw new Error();
+            await launcher.main(["preflight"]);
+            configured = true;
+        }
+    }
+    catch (error) {
+        if (!probe && fixedErrorCode(error) === "SETUP_REQUIRED")
+            configured = false;
+        else
+            throw new CliError("CONNECTION_VERIFICATION_FAILED");
+    }
+    if (!configured) {
+        report("authorizing");
+        try {
+            const result = await launcher.main(["login"], options);
+            if (result === null ||
+                typeof result !== "object" ||
+                !("status" in result) ||
+                result.status !== "connected")
+                throw new Error();
+        }
+        catch {
+            throw new CliError("BROWSER_AUTHORIZATION_FAILED");
+        }
+    }
+    report("connected");
+}
+function assertDisposableRoot(value, expectedParent) {
+    const relative = path.relative(path.resolve(expectedParent), path.resolve(value));
+    if (relative === "" ||
+        relative === ".." ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative) ||
+        !path.basename(value).startsWith("nggaigc-cli-"))
+        throw new CliError("INSTALLATION_FAILED");
+}
+export async function runInstall(options = {}) {
+    validateRuntime(options.platform ?? process.platform, options.architecture ?? process.arch);
+    const profile = safeProfile(options.profile ?? os.homedir());
+    const report = options.reporter ?? (() => undefined);
+    report("verifying");
+    const bundle = await verifyBundle(options.bundle ?? defaultBundle());
+    const temporaryParent = path.resolve(options.temporaryRoot ?? os.tmpdir());
+    const temporary = await mkdtemp(path.join(temporaryParent, "nggaigc-cli-"));
+    assertDisposableRoot(temporary, temporaryParent);
+    try {
+        const extracted = path.join(temporary, "plugin");
+        await extractBundle(bundle.archive, extracted);
+        await verifyExtractedBundle(extracted, bundle.files);
+        report("installing");
+        const require = createRequire(import.meta.url);
+        const installer = require(path.join(extracted, "installer", "install.cjs"));
+        if (!installer || typeof installer.main !== "function")
+            throw new CliError("INSTALLATION_FAILED");
+        const installation = await installSkill(installer, path.join(extracted, "skills", "nggaigc"), profile, bundle.version, bundle.files);
+        const installedScripts = path.join(profile, ".agents", "skills", "nggaigc", "scripts");
+        const launcher = require(path.join(installedScripts, "launch-ngg-client.cjs"));
+        if (!launcher ||
+            typeof launcher.main !== "function" ||
+            typeof launcher.LauncherError !== "function")
+            throw new CliError("INSTALLATION_FAILED");
+        await connect(launcher, options.launcherOptionsFactory?.(launcher), report, options.connectionProbe);
+        return { status: "connected", installation, version: bundle.version };
+    }
+    finally {
+        assertDisposableRoot(temporary, temporaryParent);
+        await rm(temporary, { recursive: true, force: true });
+    }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@nggaigc/cli",
+  "version": "0.1.0",
+  "description": "Secure one-command NGGAIGC Skill installer for Codex on Windows.",
+  "type": "module",
+  "bin": {
+    "nggaigc": "dist/bin.js"
+  },
+  "files": [
+    "dist/",
+    "scripts/expand-archive.ps1",
+    "vendor/"
+  ],
+  "engines": {
+    "node": ">=22.13.0 <23"
+  },
+  "os": [
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "tsc -p tsconfig.build.json && node scripts/stage-assets.mjs",
+    "test": "vitest run --exclude 'dist/**' --exclude 'src/windows-secure-store.integration.test.ts'",
+    "test:credential:os": "tsc -p tsconfig.build.json && vitest run src/windows-secure-store.integration.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "license": "UNLICENSED"
+}

package/scripts/expand-archive.ps1

@@ -0,0 +1,7 @@
+param(
+  [Parameter(Mandatory = $true)][string]$Archive,
+  [Parameter(Mandatory = $true)][string]$Destination
+)
+
+$ErrorActionPreference = 'Stop'
+Expand-Archive -LiteralPath $Archive -DestinationPath $Destination

package/vendor/manifest.json

@@ -0,0 +1,30 @@
+{
+  "schemaVersion": "nggaigc-plugin-package/v1",
+  "artifactId": "plugin.nggaigc",
+  "version": "1.1.1",
+  "sourceCommit": "6d6869feb01c935f16250beca0d269eef41a4eaa",
+  "artifactPath": "packages/plugins/nggaigc-plugin-1.1.1.zip",
+  "sha256": "f4371dcbfb58d003699ce854472d1a2cb356976c69db633f90b929bae2863bda",
+  "sizeBytes": 106658,
+  "fileCount": 11,
+  "platforms": ["win32-x64", "win32-arm64"],
+  "files": {
+    ".codex-plugin/plugin.json": "705fd28fa3bd4b9ced198cad482bcf7af65144c368b8abcd6aa1504a47b2d25e",
+    "installer/install.cjs": "79b0b610965211dd2faf3f569d93d4f5f84b1055fc2bd11483bfdaf413edea10",
+    "skills/nggaigc/agents/openai.yaml": "4a71357d3904a2dc69b8b495f7c2f83f01d0a3c231558d7d0f10c46cd98aa301",
+    "skills/nggaigc/references/catalog-and-updates.md": "c0ee74bfe9b75dc8ee818f2db55d4fd7d581927ec037452b5971c9b3a9412e93",
+    "skills/nggaigc/references/source.json": "e315fb2f4fe35ce4fefb2c1bed60bb464cc764c3a7c69e3f3c70b7ca8a623051",
+    "skills/nggaigc/scripts/bootstrap-public.json": "ce699de3afa18941cbf9964a4e20b493a3a631f0edc1e0017a45668a9bee21a9",
+    "skills/nggaigc/scripts/launch-ngg-client.cjs": "ab96625cd10194172c18c225ba8eff0e27f1680d826ae6578645f63bcd252146",
+    "skills/nggaigc/scripts/ngg_client.mjs": "252d652b8f853fd0e610deb74a924f2143f7d17e4a34f9d35ee2bbcd800c7011",
+    "skills/nggaigc/scripts/ngg-session.mjs": "5cdcdbcf25b4852b66346f29dc8f77837bda7f680ce97f0ff1d33dc404dfb752",
+    "skills/nggaigc/scripts/windows-credential.ps1": "8b6e323bebd3f86f19e0c2ae5366f4dc68005d57c07d6f699aece366661be6a0",
+    "skills/nggaigc/SKILL.md": "5545ed96d9ab9facc241b0e6d2a18800e693d012190f08037134e9930d21fa8e"
+  },
+  "signature": {
+    "algorithm": "ed25519",
+    "keyId": "ngg-signing-skill-release-1",
+    "scope": "artifact-bytes",
+    "value": "yN8E8C4SfPMSZiOaBI4rDFJKb7EIU+5m2+dKEDGHNn/f/15xOLGiYjS0kCRoCGEDneG4GhpgF1gpX1sL/AeqDg=="
+  }
+}

package/vendor/trusted-keys.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": "ngg-trusted-package-keys/v1",
+  "keys": [
+    {
+      "keyId": "ngg-signing-skill-release-1",
+      "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAo6LYWKIjMYuAtmZdChT+BF4yiO74Xb0vM3yuGnZSK9c=\n-----END PUBLIC KEY-----\n"
+    }
+  ]
+}