@majikah/majik-signature 0.7.2 → 0.8.1

package/README.md

@@ -11,44 +11,132 @@ Beyond signing raw bytes, Majik Signature can **embed signatures directly into a
 
 ## Table of Contents
 
-- [Why Majik Signature](#why-majik-signature)
-- [Security Architecture](#security-architecture)
-- [Overview](#overview)
-- [Features](#features)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-  - [Signing Raw Content](#signing-raw-content)
-  - [File Embedding](#file-embedding)
-  - [Detached Signing](#detached-signing)
-  - [Multi-Signature Files & Allowlists](#multi-signature-files--allowlists)
-  - [Sealing an Envelope](#sealing-an-envelope)
-  - [Trusted Timestamps (TSA)](#trusted-timestamps-tsa)
-  - [Batch Signing a Folder](#batch-signing-a-folder)
-  - [Verifying Signing Order](#verifying-signing-order)
-  - [Chain Anchoring](#chain-anchoring)
-- [API Reference](#api-reference)
-  - [Content Signing](#content-signing-bytesstrings)
-  - [File Embedding](#file-embedding-api)
-  - [Detached Signing & MajikSignatureEnvelope](#detached-signing--majiksignatureenvelope-api)
-  - [Multi-Signature & Allowlist](#multi-signature--allowlist-api)
-  - [Sealing](#sealing-api)
-  - [Trusted Timestamps](#trusted-timestamps-api)
-  - [Batch Signing & MajikSignatureMap](#batch-signing--majiksignaturemap-api)
-  - [Signature Order Verification](#signature-order-verification-api)
-  - [Chain Anchoring API](#chain-anchoring-api)
-  - [Image Stamping (Experimental)](#image-stamping-experimental)
-  - [Serialization](#serialization)
-- [Supported File Formats](#supported-file-formats)
-- [Signature & Envelope Structure](#signature--envelope-structure)
-- [Binary Container Formats (MJKSIG / MJKSMAP)](#binary-container-formats-mjksig--mjksmap)
-- [Error Handling](#error-handling)
-- [Security Considerations](#security-considerations)
-- [The Majikah Ecosystem](#the-majikah-ecosystem)
-- [Related Projects](#related-projects)
-- [Contributing](#contributing)
-- [License](#license)
-- [Author](#author)
-- [Contact](#contact)
+- [Majik Signature](#majik-signature)
+  - [Table of Contents](#table-of-contents)
+  - [Why Majik Signature](#why-majik-signature)
+  - [Security Architecture](#security-architecture)
+    - [1. Hybrid Dual-Algorithm Signing](#1-hybrid-dual-algorithm-signing)
+    - [2. Canonical Payload Binding](#2-canonical-payload-binding)
+    - [3. Content-Agnostic Hashing](#3-content-agnostic-hashing)
+    - [4. File Embedding \& Detachment Integrity](#4-file-embedding--detachment-integrity)
+    - [5. Multi-Party Signing, Allowlists \& Sealing](#5-multi-party-signing-allowlists--sealing)
+    - [6. File Versioning for Visually-Mutating Multi-Sig Workflows](#6-file-versioning-for-visually-mutating-multi-sig-workflows)
+    - [7. Trusted Timestamps (TSA)](#7-trusted-timestamps-tsa)
+    - [8. Chain Anchoring](#8-chain-anchoring)
+  - [Overview](#overview)
+    - [What is a Majik Signature?](#what-is-a-majik-signature)
+    - [Use Cases](#use-cases)
+  - [Features](#features)
+    - [Security \& Post-Quantum Readiness](#security--post-quantum-readiness)
+    - [Multi-Party Signing](#multi-party-signing)
+    - [Detached Signing \& Batch Workflows](#detached-signing--batch-workflows)
+    - [Content Format Support](#content-format-support)
+    - [Developer Experience](#developer-experience)
+    - [Serialization \& Portability](#serialization--portability)
+  - [Installation](#installation)
+  - [Command-Line Interface](#command-line-interface)
+    - [`mjksig` — Sign, Verify, Seal, Inspect](#mjksig--sign-verify-seal-inspect)
+    - [Run with `npx`](#run-with-npx)
+    - [CLI Documentation](#cli-documentation)
+  - [Quick Start](#quick-start)
+    - [Signing Raw Content](#signing-raw-content)
+    - [File Embedding](#file-embedding)
+    - [Detached Signing](#detached-signing)
+    - [Multi-Signature Files \& Allowlists](#multi-signature-files--allowlists)
+    - [Sealing an Envelope](#sealing-an-envelope)
+    - [Trusted Timestamps (TSA)](#trusted-timestamps-tsa)
+    - [Batch Signing a Folder](#batch-signing-a-folder)
+    - [Verifying Signing Order](#verifying-signing-order)
+    - [Chain Anchoring](#chain-anchoring)
+    - [File Versioning \& Multi-Sig Revisions](#file-versioning--multi-sig-revisions)
+  - [API Reference](#api-reference)
+    - [Content Signing (bytes/strings)](#content-signing-bytesstrings)
+      - [`MajikSignature.sign(content, key, options?)`](#majiksignaturesigncontent-key-options)
+      - [`MajikSignature.verify(content, signature, publicKeys)`](#majiksignatureverifycontent-signature-publickeys)
+      - [`MajikSignature.verifyWithKey(content, signature, key)`](#majiksignatureverifywithkeycontent-signature-key)
+      - [`MajikSignature.publicKeysFromMajikKey(key)`](#majiksignaturepublickeysfrommajikkeykey)
+      - [`signature.extractPublicKeys()` *(instance method)*](#signatureextractpublickeys-instance-method)
+      - [`signature.validate()` / `signature.isValid()`](#signaturevalidate--signatureisvalid)
+      - [`MajikSignature.fromJSON(json)` / `MajikSignature.deserialize(base64)`](#majiksignaturefromjsonjson--majiksignaturedeserializebase64)
+    - [File Embedding API](#file-embedding-api)
+      - [`MajikSignature.signFile(file, key, options?)`](#majiksignaturesignfilefile-key-options)
+      - [`MajikSignature.verifyFile(file, keyOrPublicKeys, options?)`](#majiksignatureverifyfilefile-keyorpublickeys-options)
+      - [`signature.embedIn(file, options?)` *(instance method)*](#signatureembedinfile-options-instance-method)
+      - [`MajikSignature.extractFrom(file, options?)`](#majiksignatureextractfromfile-options)
+      - [`MajikSignature.stripFrom(file, options?)`](#majiksignaturestripfromfile-options)
+      - [`MajikSignature.isSigned(file, options?)`](#majiksignatureissignedfile-options)
+    - [Detached Signing \& MajikSignatureEnvelope API](#detached-signing--majiksignatureenvelope-api)
+      - [`MajikSignature.signFileDetached(file, key, options?)`](#majiksignaturesignfiledetachedfile-key-options)
+      - [`MajikSignature.verifyFileDetached(file, envelope, keyOrPublicKeys, options?)`](#majiksignatureverifyfiledetachedfile-envelope-keyorpublickeys-options)
+      - [`MajikSignatureEnvelope`](#majiksignatureenvelope)
+    - [Multi-Signature \& Allowlist API](#multi-signature--allowlist-api)
+      - [`MajikSignature.expectedSignerFromKey(key)`](#majiksignatureexpectedsignerfromkeykey)
+      - [`MajikSignature.getAllowlist(file, options?)`](#majiksignaturegetallowlistfile-options)
+      - [`MajikSignature.canSign(file, key, options?)`](#majiksignaturecansignfile-key-options)
+      - [`MajikSignature.getSignatories(file, options?, filter?)`](#majiksignaturegetsignatoriesfile-options-filter)
+      - [`MajikSignature.getIssuer(file, options?)`](#majiksignaturegetissuerfile-options)
+      - [`MajikSignature.getEnvelopeInfo(file, options?)`](#majiksignaturegetenvelopeinfofile-options)
+      - [`MajikSignature.isMultiSig(file, options?)`](#majiksignatureismultisigfile-options)
+    - [Sealing API](#sealing-api)
+      - [`MajikSignature.seal(file, key, options?)`](#majiksignaturesealfile-key-options)
+      - [`MajikSignature.verifySeal(file, options?)`](#majiksignatureverifysealfile-options)
+      - [`MajikSignature.getSealInfo(file, options?)`](#majiksignaturegetsealinfofile-options)
+      - [`MajikSignature.isSealed(file, options?)`](#majiksignatureissealedfile-options)
+    - [Trusted Timestamps API](#trusted-timestamps-api)
+      - [`signature.buildTSARequestPayload()`](#signaturebuildtsarequestpayload)
+      - [`MajikSignature.signTSA(request, key, tsa, options?)`](#majiksignaturesigntsarequest-key-tsa-options)
+      - [`signature.addTSA(timestamp)`](#signatureaddtsatimestamp)
+      - [`signature.verifyTSA()`](#signatureverifytsa)
+      - [`signature.hasTSA`](#signaturehastsa)
+    - [Batch Signing \& MajikSignatureMap API](#batch-signing--majiksignaturemap-api)
+      - [`MajikSignature.signBatchDetached(files, key, options?)`](#majiksignaturesignbatchdetachedfiles-key-options)
+      - [`MajikSignature.verifyFilesFromMjksMap(map, files, publicKeys, options?)`](#majiksignatureverifyfilesfrommjksmapmap-files-publickeys-options)
+      - [`MajikSignature.verifyFilesFromMjksMapWithKey(map, files, key, options?)`](#majiksignatureverifyfilesfrommjksmapwithkeymap-files-key-options)
+      - [`MajikSignature.summarizeBatchVerification(results)`](#majiksignaturesummarizebatchverificationresults)
+      - [`MajikSignatureMap`](#majiksignaturemap)
+    - [Signature Order Verification API](#signature-order-verification-api)
+      - [`MajikSignature.verifyFileOrder(file, expectedOrder, options?)`](#majiksignatureverifyfileorderfile-expectedorder-options)
+      - [`MajikSignature.verifyFileDetachedOrder(file, envelope, expectedOrder, options?)`](#majiksignatureverifyfiledetachedorderfile-envelope-expectedorder-options)
+      - [`MajikSignature.normalizeExpectedOrder(expectedOrder)`](#majiksignaturenormalizeexpectedorderexpectedorder)
+    - [Chain Anchoring API (Experimental)](#chain-anchoring-api-experimental)
+      - [`MajikSignature.canAnchor(file, options?)`](#majiksignaturecananchorfile-options)
+      - [`MajikSignature.buildChainAnchorMemo(sealHash)`](#majiksignaturebuildchainanchormemosealhash)
+      - [`MajikSignature.registerChainAnchor(file, anchor, options?)`](#majiksignatureregisterchainanchorfile-anchor-options)
+      - [`MajikSignature.getChainAnchors(file, options?)`](#majiksignaturegetchainanchorsfile-options)
+    - [File Versioning API](#file-versioning-api)
+      - [`MajikSignature.signFile(file, key, options?)` — versioning-relevant options](#majiksignaturesignfilefile-key-options--versioning-relevant-options)
+      - [`MajikSignature.verifyFileChain(file, options?)`](#majiksignatureverifyfilechainfile-options)
+      - [`MajikSignature.verifyFileRevisions(finalFile, revisions, options?)`](#majiksignatureverifyfilerevisionsfinalfile-revisions-options)
+      - [`MajikSignature.verifyCommitment(signature, publicKeys, now?)`](#majiksignatureverifycommitmentsignature-publickeys-now)
+    - [Image Stamping (Experimental)](#image-stamping-experimental)
+    - [Serialization](#serialization)
+      - [`signature.toJSON()` / `MajikSignature.fromJSON(json)`](#signaturetojson--majiksignaturefromjsonjson)
+      - [`signature.serialize()` / `MajikSignature.deserialize(base64)`](#signatureserialize--majiksignaturedeserializebase64)
+      - [`envelope.toJSON()` / `MajikSignatureEnvelope.fromJSON(json)`](#envelopetojson--majiksignatureenvelopefromjsonjson)
+      - [`envelope.serialize()` / `MajikSignatureEnvelope.deserialize(base64)`](#envelopeserialize--majiksignatureenvelopedeserializebase64)
+      - [`envelope.toMJKSIG()` / `MajikSignatureEnvelope.fromMJKSIG(input)`](#envelopetomjksig--majiksignatureenvelopefrommjksiginput)
+  - [Supported File Formats](#supported-file-formats)
+  - [Signature \& Envelope Structure](#signature--envelope-structure)
+  - [Binary Container Formats (MJKSIG / MJKSMAP)](#binary-container-formats-mjksig--mjksmap)
+  - [Error Handling](#error-handling)
+  - [Security Considerations](#security-considerations)
+    - [What is Guaranteed](#what-is-guaranteed)
+    - [What is Your Responsibility](#what-is-your-responsibility)
+    - [What NOT to Do](#what-not-to-do)
+    - [What TO Do](#what-to-do)
+  - [The Majikah Ecosystem](#the-majikah-ecosystem)
+    - [Majik Signature — Standalone App](#majik-signature--standalone-app)
+    - [🧾 Majik Buwiz](#-majik-buwiz)
+    - [💬 Majik Message](#-majik-message)
+    - [🪪 Majik Universal ID](#-majik-universal-id)
+  - [Related Projects](#related-projects)
+    - [Majik Key](#majik-key)
+    - [Majik Message](#majik-message)
+  - [Contributing](#contributing)
+  - [License](#license)
+  - [Author](#author)
+  - [Contact](#contact)
+
 
 ---
 
@@ -260,6 +348,66 @@ npm install @majikah/majik-key
 
 No native bindings. Works in Node.js 18+, modern browsers, Deno, Bun, and Tauri.
 
+---
+
+## Command-Line Interface
+
+### `mjksig` — Sign, Verify, Seal, Inspect
+
+Majik Signature includes a full-featured CLI for working with signed files directly from your terminal.
+
+The `mjksig` CLI supports:
+
+* Embedded and detached signing
+* MJKSMAP folder signing and verification
+* Multi-signature allowlists and co-signing
+* Envelope sealing
+* Signing-permission checks
+* Signature inspection
+* Batch workflows
+* Machine-readable `--json` output
+* Interactive and non-interactive signing-key passphrases
+
+### Run with `npx`
+
+No global installation required:
+
+```bash
+npx @majikah/majik-signature --help
+```
+
+Sign a file:
+
+```bash
+npx @majikah/majik-signature sign report.pdf --key alice.json
+```
+
+Verify a file:
+
+```bash
+npx @majikah/majik-signature verify report.pdf
+```
+
+Or install globally and use the `mjksig` command directly:
+
+```bash
+npm install -g @majikah/majik-signature
+```
+
+```bash
+mjksig --help
+```
+
+For automation and CI environments, signing-key passphrases can be supplied through `MAJIK_KEY_PASSPHRASE`.
+
+### CLI Documentation
+
+For the complete command reference, workflow combinations, options, compatibility rules, examples, exit codes, automation guidance, and `npx` usage, see:
+
+
+[![CLIREADME](https://img.shields.io/badge/Read_the_CLI_Documentation_Here-EA7F05?style=for-the-badge&logoColor=ea7f05)](./CLI_README.md)
+
+
 ---
 
 ## Quick Start

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

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

package/dist/cli-core/index.js

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

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.js";
+/**
+ * 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;