@majikah/majik-signature 0.7.2 → 0.8.0

package/dist/cli-core/index.d.ts

@@ -0,0 +1,5 @@
+export type * from "./types";
+export * from "./io";
+export * from "./key";
+export * from "./output";
+export * from "./operations";

package/dist/cli-core/index.js

@@ -0,0 +1,4 @@
+export * from "./io";
+export * from "./key";
+export * from "./output";
+export * from "./operations";

package/dist/cli-core/io.d.ts

@@ -0,0 +1,40 @@
+/**
+ * src/cli/io.ts
+ *
+ * Node.js filesystem helpers for the Majik Signature CLI.
+ */
+import type { FolderFile } from "./types";
+/**
+ * Convert a filesystem path into the normalized relative-path convention
+ * used by MajikSignatureMap.
+ */
+export declare function relativePosix(root: string, target: string): string;
+export declare function mimeTypeForPath(path: string): string;
+export declare function isMajikArtifact(path: string): boolean;
+export declare function pathExists(path: string): Promise<boolean>;
+export declare function ensureDirectory(path: string): Promise<void>;
+export declare function readBytes(path: string): Promise<Uint8Array>;
+export declare function readText(path: string): Promise<string>;
+export declare function readBlob(path: string): Promise<Blob>;
+export declare function readJsonFile<T = unknown>(path: string): Promise<T>;
+export declare function writeBytes(path: string, bytes: Uint8Array, overwrite: boolean): Promise<void>;
+export declare function writeBlob(path: string, blob: Blob, overwrite: boolean): Promise<void>;
+export declare function writeJsonFile(path: string, value: unknown, overwrite: boolean): Promise<void>;
+export declare function writeText(path: string, value: string, overwrite: boolean): Promise<void>;
+/**
+ * Read all regular files underneath a folder into memory.
+ *
+ * This is intentional for MJKSMAP operations because the CLI may need both
+ * the file bytes and the generated manifest/bundle during a single operation.
+ */
+export declare function readFolderFiles(rootPath: string): Promise<FolderFile[]>;
+export declare function getPathKind(inputPath: string): Promise<"file" | "directory">;
+export declare function resolveCliPath(path: string): string;
+export declare function outputPathForDetachedFile(inputPath: string): string;
+export declare function outputPathForMap(inputDirectory: string): string;
+export declare function outputPathForMapBundle(inputDirectory: string, mapPath: string): string;
+export declare function getPackageVersion(): Promise<string>;
+export declare function summarizeFiles(files: FolderFile[]): {
+    count: number;
+    bytes: number;
+};

package/dist/cli-core/io.js

@@ -0,0 +1,227 @@
+/**
+ * src/cli/io.ts
+ *
+ * Node.js filesystem helpers for the Majik Signature CLI.
+ */
+import { access, mkdir, readFile, readdir, stat, writeFile, } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, } from "node:path";
+import { fileURLToPath } from "node:url";
+const MIME_TYPES = {
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".csv": "text/csv",
+    ".json": "application/json",
+    ".xml": "application/xml",
+    ".html": "text/html",
+    ".htm": "text/html",
+    ".pdf": "application/pdf",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".mp3": "audio/mpeg",
+    ".wav": "audio/wav",
+    ".flac": "audio/flac",
+    ".mp4": "video/mp4",
+    ".mkv": "video/x-matroska",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    ".zip": "application/zip",
+    ".exe": "application/vnd.microsoft.portable-executable",
+    ".msi": "application/x-msi",
+    ".msix": "application/msix",
+    ".deb": "application/vnd.debian.binary-package",
+    ".mjksig": "application/vnd.majikah.mjksig",
+    ".mjksmap": "application/vnd.majikah.mjksmap",
+};
+const MAJIK_ARTIFACT_EXTENSIONS = new Set([".mjksig", ".mjksmap"]);
+function normalizeSlashes(value) {
+    return value.replaceAll("\\", "/");
+}
+/**
+ * Convert a filesystem path into the normalized relative-path convention
+ * used by MajikSignatureMap.
+ */
+export function relativePosix(root, target) {
+    return normalizeSlashes(relative(root, target)).replace(/^\/+/, "").trim();
+}
+export function mimeTypeForPath(path) {
+    return MIME_TYPES[extname(path).toLowerCase()] ?? "application/octet-stream";
+}
+export function isMajikArtifact(path) {
+    return MAJIK_ARTIFACT_EXTENSIONS.has(extname(path).toLowerCase());
+}
+export async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function ensureDirectory(path) {
+    await mkdir(path, {
+        recursive: true,
+    });
+}
+export async function readBytes(path) {
+    return new Uint8Array(await readFile(path));
+}
+export async function readText(path) {
+    return readFile(path, "utf8");
+}
+export async function readBlob(path) {
+    const bytes = await readBytes(path);
+    return new Blob([bytes], {
+        type: mimeTypeForPath(path),
+    });
+}
+export async function readJsonFile(path) {
+    const text = await readText(path);
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON in "${path}": ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function writeBytes(path, bytes, overwrite) {
+    if (!overwrite && (await pathExists(path))) {
+        throw new Error(`Output already exists: "${path}". Use --overwrite to replace it.`);
+    }
+    await ensureDirectory(dirname(path));
+    await writeFile(path, bytes);
+}
+export async function writeBlob(path, blob, overwrite) {
+    const bytes = new Uint8Array(await blob.arrayBuffer());
+    await writeBytes(path, bytes, overwrite);
+}
+export async function writeJsonFile(path, value, overwrite) {
+    const json = JSON.stringify(value, null, 2) + "\n";
+    await writeText(path, json, overwrite);
+}
+export async function writeText(path, value, overwrite) {
+    if (!overwrite && (await pathExists(path))) {
+        throw new Error(`Output already exists: "${path}". Use --overwrite to replace it.`);
+    }
+    await ensureDirectory(dirname(path));
+    await writeFile(path, value, "utf8");
+}
+async function walkDirectory(root, current, output) {
+    const entries = await readdir(current, {
+        withFileTypes: true,
+    });
+    for (const entry of entries) {
+        const absolutePath = join(current, entry.name);
+        /**
+         * Do not follow symlinks. This avoids directory cycles and prevents a
+         * folder signing operation from unexpectedly escaping its input tree.
+         */
+        if (entry.isSymbolicLink()) {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            await walkDirectory(root, absolutePath, output);
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        /**
+         * Existing Majik Signature sidecars/manifests are artifacts, not source
+         * files for a subsequent folder operation.
+         */
+        if (isMajikArtifact(absolutePath)) {
+            continue;
+        }
+        const fileStat = await stat(absolutePath);
+        output.push({
+            absolutePath,
+            relativePath: relativePosix(root, absolutePath),
+            blob: await readBlob(absolutePath),
+            size: fileStat.size,
+            mimeType: mimeTypeForPath(absolutePath),
+        });
+    }
+}
+/**
+ * Read all regular files underneath a folder into memory.
+ *
+ * This is intentional for MJKSMAP operations because the CLI may need both
+ * the file bytes and the generated manifest/bundle during a single operation.
+ */
+export async function readFolderFiles(rootPath) {
+    const root = resolve(rootPath);
+    const rootStat = await stat(root);
+    if (!rootStat.isDirectory()) {
+        throw new Error(`Expected a directory: "${root}"`);
+    }
+    const result = [];
+    await walkDirectory(root, root, result);
+    result.sort((a, b) => a.relativePath.localeCompare(b.relativePath, undefined, {
+        sensitivity: "base",
+    }));
+    return result;
+}
+export async function getPathKind(inputPath) {
+    const target = resolve(inputPath);
+    let fileStat;
+    try {
+        fileStat = await stat(target);
+    }
+    catch {
+        throw new Error(`Path does not exist: "${target}"`);
+    }
+    if (fileStat.isDirectory()) {
+        return "directory";
+    }
+    if (fileStat.isFile()) {
+        return "file";
+    }
+    throw new Error(`Unsupported filesystem object: "${target}"`);
+}
+export function resolveCliPath(path) {
+    if (isAbsolute(path)) {
+        return resolve(path);
+    }
+    return resolve(process.cwd(), path);
+}
+export function outputPathForDetachedFile(inputPath) {
+    return `${inputPath}.mjksig`;
+}
+export function outputPathForMap(inputDirectory) {
+    return join(inputDirectory, "signatures.mjksmap");
+}
+export function outputPathForMapBundle(inputDirectory, mapPath) {
+    const directoryName = basename(inputDirectory);
+    const mapName = basename(mapPath, extname(mapPath));
+    return join(dirname(mapPath), `${directoryName || mapName}.mjksbundle.zip`);
+}
+export async function getPackageVersion() {
+    const currentFile = fileURLToPath(import.meta.url);
+    /**
+     * dist/cli/io.js
+     *   ↑ ../
+     * dist/cli
+     *   ↑ ../
+     * dist
+     *   ↑ package root
+     */
+    const packageJsonPath = resolve(dirname(currentFile), "../../package.json");
+    try {
+        const packageJson = await readJsonFile(packageJsonPath);
+        return packageJson.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+export function summarizeFiles(files) {
+    return {
+        count: files.length,
+        bytes: files.reduce((total, file) => total + file.size, 0),
+    };
+}

package/dist/cli-core/key.d.ts

@@ -0,0 +1,37 @@
+/**
+ * src/cli/key.ts
+ *
+ * Majik Key loading/unlocking for the npm CLI.
+ *
+ * The npm CLI intentionally consumes explicit JSON key backups instead of
+ * reaching into the desktop application's account store.
+ */
+import { MajikKey } from "@majikah/majik-key";
+export type LoadedMajikKey = MajikKey;
+/**
+ * Read a passphrase without echoing it to the terminal.
+ *
+ * On Windows and Unix terminals we use raw TTY mode rather than relying on
+ * readline's normal line editor, which would echo characters.
+ */
+export declare function promptForPassphrase(message?: string): Promise<string>;
+/**
+ * Load a MajikKey without unlocking it.
+ *
+ * This is used by verification and allowlist construction because those
+ * operations only need public-key material.
+ */
+export declare function loadMajikKey(keyPath: string): Promise<LoadedMajikKey>;
+/**
+ * Load and unlock a signing-capable MajikKey.
+ *
+ * Passphrase resolution order:
+ *
+ * 1. MAJIK_KEY_PASSPHRASE
+ * 2. interactive hidden terminal prompt
+ */
+export declare function loadSigningKey(keyPath: string): Promise<LoadedMajikKey>;
+/**
+ * Explicitly lock a key after the operation.
+ */
+export declare function lockKey(key: LoadedMajikKey): void;

package/dist/cli-core/key.js

@@ -0,0 +1,165 @@
+/**
+ * src/cli/key.ts
+ *
+ * Majik Key loading/unlocking for the npm CLI.
+ *
+ * The npm CLI intentionally consumes explicit JSON key backups instead of
+ * reaching into the desktop application's account store.
+ */
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { MajikKey } from "@majikah/majik-key";
+import { readJsonFile, resolveCliPath } from "./io";
+/**
+ * Read a passphrase without echoing it to the terminal.
+ *
+ * On Windows and Unix terminals we use raw TTY mode rather than relying on
+ * readline's normal line editor, which would echo characters.
+ */
+export async function promptForPassphrase(message = "Majik Key passphrase: ") {
+    /**
+     * Non-interactive automation must take precedence over TTY detection.
+     *
+     * Vitest, CI, npm scripts, pipes, and other non-interactive environments
+     * do not expose stdin/stdout as TTYs, but MAJIK_KEY_PASSPHRASE is explicitly
+     * supported for exactly these cases.
+     */
+    const envPassphrase = process.env.MAJIK_KEY_PASSPHRASE;
+    if (envPassphrase !== undefined) {
+        return envPassphrase;
+    }
+    /**
+     * Only require a TTY when we actually need to ask the user interactively.
+     */
+    if (!input.isTTY || !output.isTTY) {
+        throw new Error("A passphrase is required, but stdin is not an interactive terminal. " +
+            "Set MAJIK_KEY_PASSPHRASE for non-interactive use.");
+    }
+    const rl = createInterface({
+        input,
+        output,
+    });
+    /**
+     * readline does not provide a portable hidden-input switch.
+     * Temporarily switch stdin to raw mode and collect characters ourselves.
+     */
+    rl.pause();
+    return new Promise((resolve, reject) => {
+        const stdin = input;
+        let value = "";
+        let cleanedUp = false;
+        const cleanup = () => {
+            if (cleanedUp)
+                return;
+            cleanedUp = true;
+            stdin.setRawMode?.(false);
+            stdin.pause();
+            stdin.removeListener("data", onData);
+            try {
+                rl.close();
+            }
+            catch {
+                // Cleanup only.
+            }
+            process.stdout.write("\n");
+        };
+        const onData = (chunk) => {
+            const text = chunk.toString("utf8");
+            for (const character of text) {
+                if (character === "\u0003") {
+                    cleanup();
+                    reject(new Error("Operation cancelled."));
+                    return;
+                }
+                if (character === "\r" || character === "\n") {
+                    const result = value;
+                    cleanup();
+                    resolve(result);
+                    return;
+                }
+                if (character === "\u0008" || character === "\u007f") {
+                    value = value.slice(0, -1);
+                    continue;
+                }
+                value += character;
+            }
+        };
+        try {
+            process.stdout.write(message);
+            stdin.setEncoding("utf8");
+            stdin.setRawMode?.(true);
+            stdin.resume();
+            stdin.on("data", onData);
+        }
+        catch (error) {
+            cleanup();
+            reject(error);
+        }
+    });
+}
+function assertSupportedKeyPath(path) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".json")) {
+        return;
+    }
+    if (lower.endsWith(".png")) {
+        throw new Error("PNG Majik Key backups are not supported by the current npm SDK CLI " +
+            "because @majikah/majik-key does not currently expose the PNG-backup " +
+            "restore API used by the desktop application. Use a .json backup.");
+    }
+    throw new Error(`Unsupported Majik Key file "${path}". Expected a .json backup.`);
+}
+/**
+ * Load a MajikKey without unlocking it.
+ *
+ * This is used by verification and allowlist construction because those
+ * operations only need public-key material.
+ */
+export async function loadMajikKey(keyPath) {
+    const resolvedPath = resolveCliPath(keyPath);
+    assertSupportedKeyPath(resolvedPath);
+    const json = await readJsonFile(resolvedPath);
+    try {
+        return MajikKey.fromJSON(json);
+    }
+    catch (error) {
+        throw new Error(`Failed to load Majik Key "${resolvedPath}": ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Load and unlock a signing-capable MajikKey.
+ *
+ * Passphrase resolution order:
+ *
+ * 1. MAJIK_KEY_PASSPHRASE
+ * 2. interactive hidden terminal prompt
+ */
+export async function loadSigningKey(keyPath) {
+    const key = await loadMajikKey(keyPath);
+    if (!key.hasSigningKeys) {
+        throw new Error("The supplied Majik Key does not contain Ed25519 + ML-DSA-87 signing keys.");
+    }
+    if (!key.isUnlocked) {
+        const passphrase = await promptForPassphrase();
+        await key.unlock(passphrase);
+    }
+    if (!key.isUnlocked) {
+        throw new Error("Majik Key remained locked after unlock.");
+    }
+    return key;
+}
+/**
+ * Explicitly lock a key after the operation.
+ */
+export function lockKey(key) {
+    try {
+        if (key.isUnlocked) {
+            key.lock();
+        }
+    }
+    catch {
+        /**
+         * Cleanup should never replace the original operation result/error.
+         */
+    }
+}

package/dist/cli-core/operations.d.ts

@@ -0,0 +1,22 @@
+/**
+ * src/cli/operations.ts
+ *
+ * High-level filesystem operations for the Majik Signature CLI.
+ *
+ * This file intentionally does NOT reproduce the desktop application's
+ * CliRequest / IPC architecture.
+ *
+ * CLI
+ *   ↓
+ * typed options
+ *   ↓
+ * existing MajikSignature SDK
+ *   ↓
+ * filesystem
+ */
+import type { CanSignCliOptions, CliResult, InspectCliOptions, SealCliOptions, SignCliOptions, VerifyCliOptions } from "./types.js";
+export declare function runSign(options: SignCliOptions): Promise<CliResult>;
+export declare function runVerify(options: VerifyCliOptions): Promise<CliResult>;
+export declare function runSeal(options: SealCliOptions): Promise<CliResult>;
+export declare function runCanSign(options: CanSignCliOptions): Promise<CliResult>;
+export declare function runInspect(options: InspectCliOptions): Promise<CliResult>;