@synopackageland/cli 0.1.0

package/dist/mock-broker/server.js

@@ -0,0 +1,350 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { exportJWK, generateKeyPair, SignJWT } from "jose";
+import { MOCK_ISSUER } from "@synopackageland/dev-sdk/node";
+import { FileStoreError, MockFileStore } from "./files.js";
+import { createMockOidcContext, handleMockOidc } from "./oidc.js";
+export const FAKE_USER = {
+    subject: "mock-user-001",
+    username: "mock.user",
+    displayName: "Mock User",
+};
+let keyPairPromise = null;
+async function getKeyPair() {
+    if (!keyPairPromise) {
+        keyPairPromise = generateKeyPair("RS256");
+    }
+    return keyPairPromise;
+}
+function sendJson(res, status, body) {
+    res.statusCode = status;
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(JSON.stringify(body));
+}
+function sendError(res, status, code, message, requestId) {
+    sendJson(res, status, {
+        error: { code, message, requestId, details: {} },
+    });
+}
+async function issueToken(packageId) {
+    const { privateKey } = await getKeyPair();
+    return new SignJWT({
+        username: FAKE_USER.username,
+        displayName: FAKE_USER.displayName,
+        mock: true,
+    })
+        .setProtectedHeader({ alg: "RS256" })
+        .setIssuer(MOCK_ISSUER)
+        .setAudience(packageId)
+        .setSubject(FAKE_USER.subject)
+        .setIssuedAt()
+        .setExpirationTime("1h")
+        .sign(privateKey);
+}
+async function verifyToken(token, packageId) {
+    const { importJWK, jwtVerify } = await import("jose");
+    const { publicKey } = await getKeyPair();
+    const jwk = await exportJWK(publicKey);
+    const key = await importJWK(jwk, "RS256");
+    return jwtVerify(token, key, {
+        issuer: MOCK_ISSUER,
+        audience: packageId,
+    });
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+function readBodyBuffer(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+function bearer(header) {
+    const value = Array.isArray(header) ? header[0] : header;
+    const match = value?.match(/^Bearer\s+(.+)$/i);
+    return match?.[1];
+}
+function parseRange(header) {
+    const value = Array.isArray(header) ? header[0] : header;
+    if (!value) {
+        return undefined;
+    }
+    const match = value.match(/^bytes=(\d+)-(\d+)?$/);
+    if (!match) {
+        return undefined;
+    }
+    return { start: Number(match[1]), end: match[2] !== undefined ? Number(match[2]) : undefined };
+}
+function mapRoute(method, url) {
+    const path = url.pathname.replace(/\/$/, "") || "/";
+    if (method === "GET" && path === "/api/v1/files") {
+        return { operation: "list", needsJson: false };
+    }
+    if (method === "GET" && path.endsWith("/files/stat")) {
+        return { operation: "stat", needsJson: false };
+    }
+    if (method === "GET" && path.endsWith("/files/download")) {
+        return { operation: "download", needsJson: false };
+    }
+    if ((method === "PUT" || method === "POST") && path.endsWith("/files/upload")) {
+        return { operation: "upload", needsJson: false };
+    }
+    if (method === "POST" && path.endsWith("/files/mkdir")) {
+        return { operation: "mkdir", needsJson: true };
+    }
+    if (method === "POST" && path.endsWith("/files/rename")) {
+        return { operation: "rename", needsJson: true };
+    }
+    if (method === "POST" && path.endsWith("/files/move")) {
+        return { operation: "move", needsJson: true };
+    }
+    if (method === "POST" && path.endsWith("/files/copy")) {
+        return { operation: "copy", needsJson: true };
+    }
+    if (method === "POST" && path.endsWith("/files/trash")) {
+        return { operation: "trash", needsJson: true };
+    }
+    return null;
+}
+async function requireAuth(req, res, packageId, requestId) {
+    const token = bearer(req.headers.authorization);
+    if (!token) {
+        sendError(res, 401, "UNAUTHENTICATED", "需要 User Context。", requestId);
+        return false;
+    }
+    try {
+        await verifyToken(token, packageId);
+        return true;
+    }
+    catch {
+        sendError(res, 401, "UNAUTHENTICATED", "需要 User Context。", requestId);
+        return false;
+    }
+}
+function handleStoreError(res, error, requestId) {
+    if (error instanceof FileStoreError) {
+        sendError(res, error.status, error.code, error.message, requestId);
+        return;
+    }
+    sendError(res, 500, "INTERNAL_ERROR", "Mock Broker 發生錯誤。", requestId);
+}
+async function handleFiles(req, res, url, store, packageId, requestId) {
+    const mapped = mapRoute(req.method ?? "GET", url);
+    if (!mapped) {
+        sendError(res, 404, "NOT_FOUND", "找不到資源。", requestId);
+        return;
+    }
+    if (!(await requireAuth(req, res, packageId, requestId))) {
+        return;
+    }
+    const overwrite = url.searchParams.get("overwrite") === "true";
+    const json = mapped.needsJson
+        ? JSON.parse((await readBody(req)) || "{}")
+        : {};
+    const bodyOverwrite = json.overwrite === true;
+    const effectiveOverwrite = overwrite || bodyOverwrite;
+    const path = String(json.path ?? url.searchParams.get("path") ?? "");
+    const to = json.to !== undefined ? String(json.to) : undefined;
+    try {
+        switch (mapped.operation) {
+            case "list": {
+                const items = store.list(path);
+                sendJson(res, 200, { items });
+                return;
+            }
+            case "stat": {
+                sendJson(res, 200, store.stat(path));
+                return;
+            }
+            case "download": {
+                const range = parseRange(req.headers.range);
+                const result = store.download(path, range);
+                const hasRange = Boolean(range);
+                res.statusCode = hasRange ? 206 : 200;
+                res.setHeader("content-type", "application/octet-stream");
+                res.setHeader("accept-ranges", "bytes");
+                res.setHeader("content-length", String(result.size));
+                if (hasRange && range) {
+                    const end = range.end ?? range.start + result.size - 1;
+                    res.setHeader("content-range", `bytes ${range.start}-${end}/${result.totalSize}`);
+                }
+                if (result.stream) {
+                    result.stream.pipe(res);
+                    return;
+                }
+                res.end(result.buffer);
+                return;
+            }
+            case "upload": {
+                const body = await readBodyBuffer(req);
+                store.upload(path, body, effectiveOverwrite);
+                sendJson(res, 200, { path });
+                return;
+            }
+            case "mkdir": {
+                store.mkdir(path);
+                sendJson(res, 200, { path });
+                return;
+            }
+            case "rename": {
+                const destination = to ?? "";
+                store.rename(path, destination, effectiveOverwrite);
+                sendJson(res, 200, { path: destination });
+                return;
+            }
+            case "move": {
+                const destination = to ?? "";
+                store.move(path, destination, effectiveOverwrite);
+                sendJson(res, 200, { path: destination });
+                return;
+            }
+            case "copy": {
+                const destination = to ?? "";
+                store.copy(path, destination, effectiveOverwrite);
+                sendJson(res, 200, { path: destination });
+                return;
+            }
+            case "trash": {
+                store.trash(path);
+                sendJson(res, 200, { path });
+                return;
+            }
+        }
+    }
+    catch (error) {
+        handleStoreError(res, error, requestId);
+    }
+}
+function isFilesRoute(pathname, method) {
+    const path = pathname.replace(/\/$/, "") || "/";
+    if (method === "GET" && path === "/api/v1/files") {
+        return true;
+    }
+    return path.startsWith("/api/v1/files/");
+}
+export async function startMockBroker(options) {
+    const fileStore = new MockFileStore({
+        filesRoot: options.filesRoot,
+        recycleBinDisabled: options.recycleBinDisabled,
+    });
+    const oidc = createMockOidcContext(options.packageId, FAKE_USER, options.oidc);
+    const server = createServer(async (req, res) => {
+        const requestId = randomUUID();
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const pathname = url.pathname;
+        const method = req.method ?? "GET";
+        try {
+            if (await handleMockOidc(req, res, url, oidc)) {
+                return;
+            }
+            if (req.method === "GET" && pathname === "/.well-known/jwks.json") {
+                const { publicKey } = await getKeyPair();
+                const jwk = await exportJWK(publicKey);
+                jwk.alg = "RS256";
+                jwk.use = "sig";
+                jwk.kid = createHash("sha256").update(JSON.stringify(jwk)).digest("hex").slice(0, 16);
+                sendJson(res, 200, { keys: [jwk] });
+                return;
+            }
+            if (pathname === "/api/v1/auth/login" && req.method === "POST") {
+                await readBody(req);
+                const accessToken = await issueToken(options.packageId);
+                sendJson(res, 200, { user: FAKE_USER, accessToken });
+                return;
+            }
+            if ((pathname === "/.well-known/jwks.json" || pathname === "/api/v1/.well-known/jwks.json") &&
+                req.method === "GET") {
+                const { publicKey } = await getKeyPair();
+                const jwk = await exportJWK(publicKey);
+                jwk.alg = "RS256";
+                jwk.use = "sig";
+                jwk.kid = createHash("sha256").update(JSON.stringify(jwk)).digest("hex").slice(0, 16);
+                sendJson(res, 200, { keys: [jwk] });
+                return;
+            }
+            if (pathname === "/api/v1/oauth/device_authorization" && req.method === "POST") {
+                await readBody(req);
+                sendJson(res, 200, {
+                    device_code: "mock-device-code",
+                    user_code: "WDJB-MJHT",
+                    verification_uri: `${`http://127.0.0.1`}/oauth/device`,
+                    verification_uri_complete: "/oauth/device?user_code=WDJB-MJHT",
+                    expires_in: 600,
+                    interval: 1,
+                });
+                return;
+            }
+            if (pathname === "/api/v1/oauth/device/approve" && req.method === "POST") {
+                await readBody(req);
+                sendJson(res, 200, { ok: true, user: FAKE_USER });
+                return;
+            }
+            if (pathname === "/api/v1/oauth/token" && req.method === "POST") {
+                await readBody(req);
+                const accessToken = await issueToken(options.packageId);
+                sendJson(res, 200, {
+                    access_token: accessToken,
+                    refresh_token: "mock-refresh",
+                    token_type: "Bearer",
+                    expires_in: 300,
+                    user: FAKE_USER,
+                });
+                return;
+            }
+            if (pathname === "/api/v1/session/renew" && req.method === "POST") {
+                const accessToken = await issueToken(options.packageId);
+                sendJson(res, 200, { user: FAKE_USER, accessToken });
+                return;
+            }
+            if (pathname === "/api/v1/session/logout" && req.method === "POST") {
+                sendJson(res, 200, { ok: true });
+                return;
+            }
+            if (pathname === "/api/v1/session" && req.method === "GET") {
+                const auth = req.headers.authorization ?? "";
+                const match = auth.match(/^Bearer\s+(.+)$/i);
+                if (!match) {
+                    sendError(res, 401, "UNAUTHENTICATED", "需要 User Context。", requestId);
+                    return;
+                }
+                await verifyToken(match[1], options.packageId);
+                sendJson(res, 200, { user: FAKE_USER });
+                return;
+            }
+            if (isFilesRoute(pathname, method)) {
+                await handleFiles(req, res, url, fileStore, options.packageId, requestId);
+                return;
+            }
+            sendError(res, 404, "NOT_FOUND", "找不到資源。", requestId);
+        }
+        catch {
+            sendError(res, 500, "INTERNAL_ERROR", "Mock Broker 發生錯誤。", requestId);
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port ?? 0, "127.0.0.1", () => resolve());
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") {
+        throw new Error("無法啟動 mock Broker。");
+    }
+    const baseUrl = `http://127.0.0.1:${address.port}`;
+    return {
+        baseUrl,
+        jwksUrl: `${baseUrl}/.well-known/jwks.json`,
+        packageId: options.packageId,
+        server,
+        close: () => new Promise((resolve, reject) => {
+            server.close((error) => (error ? reject(error) : resolve()));
+        }),
+    };
+}

package/dist/publish/build-ledger.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Append-only Package Build ledger (Curated CI authority).
+ * InMemoryBuildLedger is the disk-free stub. Durable merge-CI persistence is FileBuildLedger.
+ */
+export interface BuildLedger {
+    /** Atomically allocate the next Package Build for an App Package identity. */
+    allocate(packageIdentity: string): number;
+    /** Record a failed publish after allocation. The build number is not recycled. */
+    markPublishFailed(packageIdentity: string, build: number): void;
+}
+export interface BuildLedgerSnapshot {
+    nextBuild: number;
+    consumed: readonly number[];
+}
+/** In-memory stub for unit tests that must not touch disk. */
+export declare class InMemoryBuildLedger implements BuildLedger {
+    private nextByIdentity;
+    private consumedByIdentity;
+    allocate(packageIdentity: string): number;
+    markPublishFailed(_packageIdentity: string, _build: number): void;
+    snapshot(packageIdentity: string): BuildLedgerSnapshot;
+}

package/dist/publish/build-ledger.js

@@ -0,0 +1,26 @@
+/**
+ * Append-only Package Build ledger (Curated CI authority).
+ * InMemoryBuildLedger is the disk-free stub. Durable merge-CI persistence is FileBuildLedger.
+ */
+/** In-memory stub for unit tests that must not touch disk. */
+export class InMemoryBuildLedger {
+    nextByIdentity = new Map();
+    consumedByIdentity = new Map();
+    allocate(packageIdentity) {
+        const next = (this.nextByIdentity.get(packageIdentity) ?? 0) + 1;
+        this.nextByIdentity.set(packageIdentity, next);
+        const consumed = this.consumedByIdentity.get(packageIdentity) ?? [];
+        consumed.push(next);
+        this.consumedByIdentity.set(packageIdentity, consumed);
+        return next;
+    }
+    markPublishFailed(_packageIdentity, _build) {
+        // Append-only: allocation already consumed the build number.
+    }
+    snapshot(packageIdentity) {
+        return {
+            nextBuild: this.nextByIdentity.get(packageIdentity) ?? 0,
+            consumed: [...(this.consumedByIdentity.get(packageIdentity) ?? [])],
+        };
+    }
+}

package/dist/publish/community-path.d.ts

@@ -0,0 +1,6 @@
+export declare const COMMUNITY_APPS_DIR = "synopkgland-community-apps";
+export declare const COMMUNITY_APPS_APPS_DIR = "apps";
+export declare function resolveCommunityAppsRoot(startDir: string): string | null;
+export declare function communityAppDirectory(communityRoot: string, packageIdentity: string): string;
+export declare function assertDirectoryMatchesPackage(packageIdentity: string, appDirectory: string): void;
+export declare function listCommunityAppDirectories(communityRoot: string): string[];

package/dist/publish/community-path.js

@@ -0,0 +1,41 @@
+import { existsSync, readdirSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+export const COMMUNITY_APPS_DIR = "synopkgland-community-apps";
+export const COMMUNITY_APPS_APPS_DIR = "apps";
+export function resolveCommunityAppsRoot(startDir) {
+    const fromEnv = process.env.SYNOPKGLAND_COMMUNITY_APPS_ROOT?.trim();
+    if (fromEnv) {
+        return resolve(fromEnv);
+    }
+    let current = resolve(startDir);
+    while (true) {
+        const candidate = join(current, COMMUNITY_APPS_DIR);
+        if (existsSync(join(candidate, COMMUNITY_APPS_APPS_DIR))) {
+            return candidate;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+export function communityAppDirectory(communityRoot, packageIdentity) {
+    return join(communityRoot, COMMUNITY_APPS_APPS_DIR, packageIdentity);
+}
+export function assertDirectoryMatchesPackage(packageIdentity, appDirectory) {
+    const directoryName = basename(appDirectory);
+    if (directoryName !== packageIdentity) {
+        throw new Error(`Community Apps 目錄名必須等於 package：預期 ${packageIdentity}，實際 ${directoryName}。`);
+    }
+}
+export function listCommunityAppDirectories(communityRoot) {
+    const appsRoot = join(communityRoot, COMMUNITY_APPS_APPS_DIR);
+    if (!existsSync(appsRoot)) {
+        return [];
+    }
+    return readdirSync(appsRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => join(appsRoot, entry.name))
+        .filter((dir) => existsSync(join(dir, "synology-app.yaml")));
+}

package/dist/publish/curated-release.d.ts

@@ -0,0 +1,78 @@
+import { type JWK } from "jose";
+import { type CuratedReleasePublisher } from "@synopackageland/package-source/publish-spk";
+import { type AppPackageAttestationClaims, type CuratedAppPackageAttestationInput, type CuratedReleaseAttestationClaims, type CuratedReleaseAttestationInput } from "../attestation/app-package.js";
+import { type BuildSpkOptions, type BuildSpkResult } from "../build-spk/generator.js";
+import { type ProjectRoot } from "../discovery.js";
+import type { ComposeDocument } from "../types.js";
+import type { BuildLedger } from "./build-ledger.js";
+export declare const CURATED_ATTESTATION_PRIVATE_JWK_ENV = "SYNOPKGLAND_CURATED_ATTESTATION_PRIVATE_JWK";
+export declare const CURATED_ATTESTATION_PRIVATE_PKCS8_ENV = "SYNOPKGLAND_CURATED_ATTESTATION_PRIVATE_PKCS8";
+export declare const CURATED_ATTESTATION_KID_ENV = "SYNOPKGLAND_CURATED_ATTESTATION_KID";
+export { CURATED_ATTESTATION_KEYRING_ENV, CURATED_ATTESTATION_KEYRING_PATH_ENV } from "../attestation/keyring.js";
+export declare class CuratedReleaseError extends Error {
+    readonly code: string;
+    constructor(code: string, message?: string);
+}
+export interface CuratedAttestationSignInput extends CuratedAppPackageAttestationInput {
+}
+export interface CuratedReleaseSignInput extends CuratedReleaseAttestationInput {
+}
+export interface CuratedAttestationSigner {
+    /** Sign the v2 token that will be embedded before the SPK is built. */
+    sign(input: CuratedAttestationSignInput): Promise<{
+        token: string;
+        attestationDigest: string;
+        claims?: AppPackageAttestationClaims;
+    }>;
+    /** Sign the v1 detached token after the final SPK digest is known. */
+    signRelease?: (input: CuratedReleaseSignInput) => Promise<{
+        token: string;
+        attestationDigest: string;
+        claims?: CuratedReleaseAttestationClaims;
+    }>;
+    /** Production signers use this to verify the actual JWT signature before publish. */
+    verify?: (token: string, kind: "embedded" | "release") => Promise<void>;
+    /** Public trust-root JWK passed to the Package Source publication boundary. */
+    verificationJwk?: JWK;
+}
+export interface CuratedReleaseOptions {
+    project: ProjectRoot;
+    /** A Build already allocated by protected-main CI. This function never allocates. */
+    build: number;
+    signer: CuratedAttestationSigner;
+    publisher: CuratedReleasePublisher;
+    ledger?: BuildLedger;
+    buildSpk?: (options: BuildSpkOptions) => Promise<BuildSpkResult>;
+}
+export interface CuratedReleaseResult {
+    packageIdentity: string;
+    packageBuild: number;
+    version: string;
+    artifactKey: string;
+    artifactDigest: string;
+    attestationKey: string;
+    /** Digest of the embedded token's canonical claims. */
+    embeddedAttestationDigest: string;
+    /** Digest/jti of the detached token's canonical claims. */
+    attestationDigest: string;
+}
+export interface CuratedComposeGateResult {
+    ok: boolean;
+    errors: string[];
+}
+/**
+ * The release-only Compose gate. Development Compose may use tags and build:;
+ * a trusted release may contain neither and every service must pin a digest.
+ */
+export declare function validateCuratedCompose(compose: ComposeDocument): CuratedComposeGateResult;
+export declare function isPublicOciDigest(image: string): boolean;
+/** Execute the trusted dual-envelope release state machine for one allocated Build. */
+export declare function releaseCurated(options: CuratedReleaseOptions): Promise<CuratedReleaseResult>;
+export declare const runCuratedRelease: typeof releaseCurated;
+export declare function createCuratedAttestationSignerFromEnv(env?: NodeJS.Dict<string>): Promise<CuratedAttestationSigner>;
+export declare function runCuratedReleaseCli(argv?: string[], env?: NodeJS.Dict<string>): Promise<number>;
+/**
+ * Canonical App Bundle digest. Only the three declared bundle areas are
+ * included; archive metadata and presentation files can never affect it.
+ */
+export declare function digestReleaseBundle(project: ProjectRoot): string;