zurik 1.0.3 → 2.0.0

package/bin/zurik.js

@@ -1,95 +1,261 @@
 #!/usr/bin/env node
 
+import fs from "fs";
+import path from "path";
 import * as readline from "readline";
-import encryptFiles from "../lib/encrypt.js";
-import decryptFiles from "../lib/decrypt.js";
+import { fileURLToPath } from "url";
+import { encrypt, decrypt, status, resolveRoot, ZurikError, ERROR_CODES, MIN_PASSWORD_LENGTH } from "../lib/index.js";
 
-const args = process.argv.slice(2);
+const PKG_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+const VERSION = JSON.parse(fs.readFileSync(path.join(PKG_DIR, "package.json"), "utf8")).version;
 
+const EXIT = { OK: 0, ERROR: 1, USAGE: 2 };
+const COMMANDS = { encrypt: "encrypt", "-e": "encrypt", decrypt: "decrypt", "-d": "decrypt", status: "status", "-s": "status", skill: "skill", help: "help" };
 
-function readPassword() {
-  return new Promise((resolve) => {
-    const rl = readline.createInterface({
-      input: process.stdin,
-      output: process.stdout,
-      terminal: false
-    });
+const HELP = `zurik ${VERSION} — encrypt project secrets into a single .zurik bundle
 
-    if (process.stdin.isTTY) {
-      process.stdin.setRawMode(true);
-    }
+Usage:
+  zurik encrypt  [options]   Encrypt files listed in .gitencrypt into .zurik   (alias: -e)
+  zurik decrypt  [options]   Restore files from .zurik                         (alias: -d)
+  zurik status   [options]   Show which files are in sync, without decrypting   (alias: -s)
+  zurik skill                Print instructions for AI agents (SKILL.md)
+  zurik help [--json]        Show this help; --json prints a machine-readable spec
 
-    process.stdout.write("Password: ");
+Options:
+  -p, --password [value]     Prompt for the password (or read a line from piped stdin);
+                             with a value, use it inline (visible in ps / shell history)
+  --password-stdin           Read the password from the first line of stdin
+  --password-file <path>     Read the password from a file
+  -f, --force                Decrypt: overwrite local files that differ from .zurik
+  -n, --dry-run              Report what would happen without writing anything
+  --json                     Print one JSON object on stdout (results and errors)
+  --no-input                 Never prompt; fail with E_NO_PASSWORD instead
+  -C, --cwd <dir>            Run as if started in <dir>
+  -v, --version              Print the version
 
-    let password = "";
+Password sources, first match wins: --password value, --password-file, --password-stdin,
+-p prompt, $ZURIK_PASSWORD, $ZURIK_PASSWORD_FILE, then an interactive prompt if stdin is
+a terminal (never with --json, --no-input or $CI). Encrypting needs ${MIN_PASSWORD_LENGTH}+ characters.
 
-    process.stdin.on("data", (char) => {
-      char = char.toString();
+zurik uses the nearest parent directory containing .gitencrypt (encrypt), .zurik (decrypt)
+or either (status). Exit codes: 0 success, 1 error, 2 usage error.`;
 
-      if (char === "\n" || char === "\r" || char === "\u0004") {
-        process.stdin.pause();
-        if (process.stdin.isTTY) {
-          process.stdin.setRawMode(false);
-        }
-        rl.close();
-        console.log();
-        resolve(password);
-      } else if (char === "\u007f" || char === "\b") {
-        // Backspace
-        if (password.length > 0) {
-          password = password.slice(0, -1);
-          process.stdout.clearLine(0);
-          process.stdout.cursorTo(0);
-          process.stdout.write("Password: " + "*".repeat(password.length));
+function usageError(message) {
+  return new ZurikError("E_USAGE", message);
+}
+
+function parseArgs(argv) {
+  const opts = { command: null, json: false, force: false, dryRun: false, noInput: false, help: false, version: false };
+
+  // Support --flag=value for long options.
+  const args = argv.flatMap(a => (a.startsWith("--") && a.includes("=") ? [a.slice(0, a.indexOf("=")), a.slice(a.indexOf("=") + 1)] : [a]));
+
+  const takeValue = (i, flag) => {
+    if (args[i + 1] === undefined) throw usageError(`${flag} requires a value`);
+    return args[i + 1];
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (COMMANDS[a]) {
+      if (opts.command && opts.command !== COMMANDS[a]) throw usageError("Specify only one command");
+      opts.command = COMMANDS[a];
+      continue;
+    }
+    switch (a) {
+      case "-p":
+      case "--password": {
+        const next = args[i + 1];
+        if (next !== undefined && !next.startsWith("-") && !COMMANDS[next]) {
+          opts.password = next;
+          i++;
+        } else {
+          opts.promptPassword = true;
         }
-      } else if (char === "\u0003") {
-        // Ctrl+C
-        console.log();
-        process.exit(0);
-      } else {
-        password += char;
-        process.stdout.write("*");
+        break;
       }
+      case "--password-stdin": opts.passwordStdin = true; break;
+      case "--password-file": opts.passwordFile = takeValue(i++, a); break;
+      case "-f": case "--force": opts.force = true; break;
+      case "-n": case "--dry-run": opts.dryRun = true; break;
+      case "--json": opts.json = true; break;
+      case "--no-input": opts.noInput = true; break;
+      case "-C": case "--cwd": opts.cwd = takeValue(i++, a); break;
+      case "-h": case "--help": opts.help = true; break;
+      case "-v": case "--version": opts.version = true; break;
+      default: throw usageError(`Unknown argument: ${a}`);
+    }
+  }
+  return opts;
+}
+
+// ---------- password input ----------
+
+function readLineFromStdin() {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, terminal: false });
+    let done = false;
+    rl.once("line", (line) => {
+      done = true;
+      rl.close();
+      resolve(line.replace(/\r$/, ""));
+    });
+    rl.once("close", () => {
+      if (!done) resolve("");
     });
   });
 }
 
+// Prompt goes to stderr so stdout stays clean for --json.
+function promptPassword() {
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    const out = process.stderr;
+    let password = "";
 
-async function extractPassword() {
-  const pIndex = args.indexOf("-p");
-  if (pIndex !== -1) {
-    if (args[pIndex + 1] && !args[pIndex + 1].startsWith("-")) {
-      return args[pIndex + 1];
-    }
+    const cleanup = () => {
+      stdin.removeListener("data", onData);
+      stdin.setRawMode(false);
+      stdin.pause();
+      out.write("\n");
+    };
 
-    return await readPassword()
-  }
-  return process.env.ZURIK_PASSWORD || null;
+    const onData = (chunk) => {
+      // A chunk may contain several characters (e.g. when pasting).
+      for (const char of chunk.toString("utf8")) {
+        if (char === "\n" || char === "\r" || char === "\u0004") {
+          cleanup();
+          resolve(password);
+          return;
+        } else if (char === "\u0003") {
+          cleanup();
+          process.exit(130);
+        } else if (char === "\u007f" || char === "\b") {
+          if (password.length > 0) {
+            password = [...password].slice(0, -1).join("");
+            out.write("\b \b");
+          }
+        } else {
+          password += char;
+          out.write("*");
+        }
+      }
+    };
+
+    out.write("Password: ");
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on("data", onData);
+  });
 }
 
-async function run() {
-  const password = await extractPassword();
-  if (!password) {
-    console.error("Missing password. Use -p <password> or set ZURIK_PASSWORD environment variable.");
-    process.exit(1);
+function readPasswordFile(file) {
+  try {
+    return fs.readFileSync(file, "utf8").replace(/\r?\n$/, "");
+  } catch (err) {
+    throw new ZurikError("E_NO_PASSWORD", `Cannot read password file ${file}: ${err.code ?? err.message}`);
   }
+}
 
-  if (args.includes("-e")) {
-    await encryptFiles(password);
-    return;
-  }
+async function resolvePassword(opts) {
+  const interactive = process.stdin.isTTY && !opts.noInput && !opts.json && !process.env.CI;
+
+  if (opts.password) return opts.password;
+  if (opts.passwordFile) return readPasswordFile(opts.passwordFile);
+  if (opts.passwordStdin) return readLineFromStdin();
+  if (opts.promptPassword) return process.stdin.isTTY ? promptPassword() : readLineFromStdin();
+  if (process.env.ZURIK_PASSWORD) return process.env.ZURIK_PASSWORD;
+  if (process.env.ZURIK_PASSWORD_FILE) return readPasswordFile(process.env.ZURIK_PASSWORD_FILE);
+  if (interactive) return promptPassword();
+  return "";
+}
 
-  if (args.includes("-d")) {
-    await decryptFiles(password);
-    return;
+// ---------- output ----------
+
+function printHuman(result) {
+  const prefix = result.dryRun ? "[dry run] would be " : "";
+  const log = (s) => process.stdout.write(s + "\n");
+
+  if (result.command === "encrypt") {
+    for (const f of result.files) log(`  ${prefix}encrypted  ${f.path}`);
+    if (result.gitignoreAdded.length) log(`  ${prefix}added to .gitignore: ${result.gitignoreAdded.join(", ")}`);
+    log(`${result.dryRun ? "Would encrypt" : "Encrypted"} ${result.files.length} file(s) into .zurik`);
+  } else if (result.command === "decrypt") {
+    for (const f of result.files) log(`  ${f.action === "unchanged" ? "" : prefix}${f.action.padEnd(9)}  ${f.path}`);
+    log(`${result.dryRun ? "Would decrypt" : "Decrypted"} ${result.files.length} file(s) from .zurik`);
+  } else if (result.command === "status") {
+    if (!result.bundleExists) log("No .zurik bundle yet.");
+    for (const f of result.files) log(`  ${f.state.padEnd(15)}  ${f.path}${f.listed ? "" : "  (not in .gitencrypt)"}`);
+    log(result.inSync ? "All files in sync." : "Out of sync.");
   }
+}
+
+function helpSpec() {
+  return {
+    name: "zurik",
+    version: VERSION,
+    commands: {
+      encrypt: { options: ["password*", "dryRun", "cwd"], result: "{ files: [{ path, action: 'encrypted' }], gitignoreAdded: [path] }" },
+      decrypt: { options: ["password*", "force", "dryRun", "cwd"], result: "{ files: [{ path, action: 'created'|'updated'|'unchanged' }] }" },
+      status: { options: ["password (only if .zurik exists)", "cwd"], result: "{ bundleExists, inSync, files: [{ path, state: 'in-sync'|'modified'|'missing-locally'|'not-in-bundle'|'missing', listed }] }" },
+    },
+    passwordSources: ["--password <value>", "--password-file <path>", "--password-stdin", "$ZURIK_PASSWORD", "$ZURIK_PASSWORD_FILE"],
+    minPasswordLength: MIN_PASSWORD_LENGTH,
+    output: "With --json, stdout is exactly one JSON object: { ok: true, command, root, ... } or { ok: false, error: { code, message, details } }",
+    exitCodes: { 0: "success", 1: "error (see error.code)", 2: "usage error" },
+    errorCodes: ERROR_CODES,
+  };
+}
+
+// ---------- main ----------
 
-  console.log("Usage:");
-  console.log("  npx zurik -e [-p password]   Encrypt");
-  console.log("  npx zurik -d [-p password]   Decrypt");
+async function main() {
+  let opts = { json: process.argv.includes("--json") };
+  try {
+    opts = parseArgs(process.argv.slice(2));
+
+    if (opts.version) return void console.log(VERSION);
+    if (opts.help || opts.command === "help") {
+      return void console.log(opts.json ? JSON.stringify(helpSpec(), null, 2) : HELP);
+    }
+    if (opts.command === "skill") {
+      return void process.stdout.write(fs.readFileSync(path.join(PKG_DIR, "skills", "zurik", "SKILL.md"), "utf8"));
+    }
+    if (!opts.command) {
+      if (opts.json) throw usageError("No command given");
+      console.log(HELP);
+      process.exitCode = EXIT.USAGE;
+      return;
+    }
+
+    const base = { cwd: opts.cwd ? path.resolve(opts.cwd) : process.cwd() };
+
+    // status only needs a password when there is a bundle to compare against.
+    const needsPassword =
+      opts.command !== "status" || fs.existsSync(path.join(resolveRoot("status", base), ".zurik"));
+    const password = needsPassword ? await resolvePassword(opts) : undefined;
+    if (needsPassword && !password) {
+      throw new ZurikError(
+        "E_NO_PASSWORD",
+        "No password provided. Use --password-file, --password-stdin, $ZURIK_PASSWORD or -p."
+      );
+    }
+
+    const run = { encrypt, decrypt, status }[opts.command];
+    const result = await run({ ...base, password, force: opts.force, dryRun: opts.dryRun });
+
+    if (opts.json) console.log(JSON.stringify({ ok: true, ...result }));
+    else printHuman(result);
+  } catch (err) {
+    const error =
+      err instanceof ZurikError
+        ? { code: err.code, message: err.message, details: err.details }
+        : { code: "E_INTERNAL", message: err.message, details: {} };
+
+    if (opts.json) console.log(JSON.stringify({ ok: false, error }));
+    else console.error(`zurik: ${error.message}`);
+    process.exitCode = error.code === "E_USAGE" ? EXIT.USAGE : EXIT.ERROR;
+  }
 }
 
-run().catch(err => {
-  console.error(err.message);
-  process.exit(1);
-});
+main();

package/lib/bundle.js

@@ -0,0 +1,63 @@
+import fs from "fs";
+import path from "path";
+import { decryptData } from "./crypto.js";
+import { ZurikError } from "./errors.js";
+import { safeRelativePath } from "./paths.js";
+
+export const LIST_FILE = ".gitencrypt";
+export const BUNDLE_FILE = ".zurik";
+
+// Bundles from older versions carry no modes; secrets default to owner-only.
+const DEFAULT_MODE = 0o600;
+
+// Paths listed in .gitencrypt, normalized and de-duplicated. `null` if the file doesn't exist.
+export function readFileList(root) {
+  const listPath = path.join(root, LIST_FILE);
+  if (!fs.existsSync(listPath)) return null;
+
+  return [
+    ...new Set(
+      fs
+        .readFileSync(listPath, "utf8")
+        .split("\n")
+        .map(x => x.trim())
+        .filter(x => x && !x.startsWith("#"))
+        .map(f => safeRelativePath(f, root))
+    ),
+  ];
+}
+
+// Decrypts .zurik and returns [{ path, content: Buffer, mode }]. Every path is validated.
+export async function readBundle(root, password) {
+  const bundlePath = path.join(root, BUNDLE_FILE);
+  if (!fs.existsSync(bundlePath)) {
+    throw new ZurikError("E_NO_BUNDLE", `${BUNDLE_FILE} not found in ${root}`);
+  }
+
+  const plaintext = await decryptData(fs.readFileSync(bundlePath, "utf8"), password);
+
+  let data;
+  try {
+    data = JSON.parse(plaintext);
+  } catch {
+    throw new ZurikError("E_CORRUPT", "Invalid .zurik bundle");
+  }
+  if (!data || typeof data.files !== "object" || data.files === null) {
+    throw new ZurikError("E_CORRUPT", "Invalid .zurik bundle");
+  }
+
+  const modes = data.modes && typeof data.modes === "object" ? data.modes : {};
+
+  return Object.entries(data.files).map(([filePath, base64]) => ({
+    path: safeRelativePath(filePath, root),
+    content: Buffer.from(base64, "base64"),
+    mode: Number.isInteger(modes[filePath]) ? modes[filePath] & 0o777 : DEFAULT_MODE,
+  }));
+}
+
+// "missing" | "same" | "different" for a local file compared with `content`.
+export function compareLocal(root, relPath, content) {
+  const abs = path.join(root, relPath);
+  if (!fs.existsSync(abs)) return "missing";
+  return fs.readFileSync(abs).equals(content) ? "same" : "different";
+}

package/lib/crypto.js

@@ -1,11 +1,25 @@
 import crypto from "crypto";
+import { ZurikError } from "./errors.js";
 
 const ALGO = "aes-256-gcm";
-const IV_LENGTH = 16;
+const SALT_LENGTH = 16;
+const TAG_LENGTH = 16;
 
-function deriveKey(password) {
+// Current format: "zurik2:" + base64( logN | r | p | salt(16) | iv(12) | tag(16) | ciphertext )
+// The KDF params are authenticated as GCM additional data, so they can't be altered.
+const V2_PREFIX = "zurik2:";
+const V2_IV_LENGTH = 12;
+const KDF = { logN: 17, r: 8, p: 1 }; // N = 2^17 ≈ 128 MiB of memory per guess
+
+// Upper bounds so a crafted file can't make decryption allocate gigabytes.
+const MAX_KDF = { logN: 20, r: 16, p: 4 };
+
+export const MIN_PASSWORD_LENGTH = 16;
+
+function deriveKey(password, salt, { logN, r, p }) {
+  const N = 2 ** logN;
   return new Promise((resolve, reject) => {
-    crypto.scrypt(password, "zurik_fixed_salt", 32, (err, key) => {
+    crypto.scrypt(password, salt, 32, { N, r, p, maxmem: 2 * 128 * N * r + 1024 * 1024 }, (err, key) => {
       if (err) reject(err);
       else resolve(key);
     });
@@ -13,29 +27,77 @@ function deriveKey(password) {
 }
 
 export async function encryptData(data, password) {
-  const key = await deriveKey(password);
-  const iv = crypto.randomBytes(IV_LENGTH);
-  const cipher = crypto.createCipheriv(ALGO, key, iv);
+  const params = Buffer.from([KDF.logN, KDF.r, KDF.p]);
+  const salt = crypto.randomBytes(SALT_LENGTH);
+  const iv = crypto.randomBytes(V2_IV_LENGTH);
+  const key = await deriveKey(password, salt, KDF);
 
+  const cipher = crypto.createCipheriv(ALGO, key, iv);
+  cipher.setAAD(params);
   const encrypted = Buffer.concat([cipher.update(data), cipher.final()]);
   const tag = cipher.getAuthTag();
 
-  return Buffer.concat([iv, tag, encrypted]).toString("base64");
+  return V2_PREFIX + Buffer.concat([params, salt, iv, tag, encrypted]).toString("base64");
+}
+
+export async function decryptData(text, password) {
+  text = text.trim();
+  return text.startsWith(V2_PREFIX)
+    ? decryptV2(text.slice(V2_PREFIX.length), password)
+    : decryptV1(text, password);
 }
 
-export async function decryptData(base64, password) {
+async function decryptV2(base64, password) {
   const buffer = Buffer.from(base64, "base64");
+  const headerLength = 3 + SALT_LENGTH + V2_IV_LENGTH + TAG_LENGTH;
+  if (buffer.length < headerLength) {
+    throw new ZurikError("E_CORRUPT", "Corrupted .zurik file");
+  }
+
+  const params = buffer.subarray(0, 3);
+  const kdf = { logN: params[0], r: params[1], p: params[2] };
+  if (
+    kdf.logN < 1 || kdf.logN > MAX_KDF.logN ||
+    kdf.r < 1 || kdf.r > MAX_KDF.r ||
+    kdf.p < 1 || kdf.p > MAX_KDF.p
+  ) {
+    throw new ZurikError("E_CORRUPT", "Corrupted .zurik file: unsupported key derivation parameters");
+  }
 
-  const iv = buffer.subarray(0, 16);
-  const tag = buffer.subarray(16, 32);
-  const ciphertext = buffer.subarray(32);
+  let offset = 3;
+  const salt = buffer.subarray(offset, (offset += SALT_LENGTH));
+  const iv = buffer.subarray(offset, (offset += V2_IV_LENGTH));
+  const tag = buffer.subarray(offset, (offset += TAG_LENGTH));
+  const ciphertext = buffer.subarray(offset);
 
-  const key = await deriveKey(password);
+  const key = await deriveKey(password, salt, kdf);
   const decipher = crypto.createDecipheriv(ALGO, key, iv);
+  decipher.setAAD(params);
   decipher.setAuthTag(tag);
+  return finish(decipher, ciphertext);
+}
+
+// Legacy format (zurik <= 1.0.5): base64( salt(16) | iv(16) | tag(16) | ciphertext ), default scrypt params.
+async function decryptV1(base64, password) {
+  const buffer = Buffer.from(base64, "base64");
+  if (buffer.length < 48) {
+    throw new ZurikError("E_CORRUPT", "Corrupted .zurik file");
+  }
+  const salt = buffer.subarray(0, 16);
+  const iv = buffer.subarray(16, 32);
+  const tag = buffer.subarray(32, 48);
+  const ciphertext = buffer.subarray(48);
+
+  const key = await deriveKey(password, salt, { logN: 14, r: 8, p: 1 });
+  const decipher = crypto.createDecipheriv(ALGO, key, iv);
+  decipher.setAuthTag(tag);
+  return finish(decipher, ciphertext);
+}
 
-  return Buffer.concat([
-    decipher.update(ciphertext),
-    decipher.final()
-  ]);
+function finish(decipher, ciphertext) {
+  try {
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  } catch {
+    throw new ZurikError("E_WRONG_PASSWORD", "Decryption failed: wrong password or corrupted .zurik file");
+  }
 }

package/lib/decrypt.js

@@ -1,19 +1,35 @@
 import fs from "fs";
 import path from "path";
-import { decryptData } from "./crypto.js";
+import { ZurikError } from "./errors.js";
+import { compareLocal, readBundle } from "./bundle.js";
 
-export default async function decryptFiles(password) {
-  if (!fs.existsSync(".zurik")) {
-    throw new Error(".zurik not found");
-  }
+const ACTION = { missing: "created", same: "unchanged", different: "updated" };
+
+export default async function decryptFiles({ root, password, force = false, dryRun = false }) {
+  const entries = (await readBundle(root, password)).map(entry => ({
+    ...entry,
+    action: ACTION[compareLocal(root, entry.path, entry.content)],
+  }));
 
-  const blob = fs.readFileSync(".zurik", "utf8");
-  const jsonStr = await decryptData(blob, password);
-  const data = JSON.parse(jsonStr);
+  const conflicts = entries.filter(e => e.action === "updated").map(e => e.path);
+  if (conflicts.length > 0 && !force) {
+    throw new ZurikError(
+      "E_WOULD_OVERWRITE",
+      `These local files differ from .zurik and would be overwritten (use --force):\n  ${conflicts.join("\n  ")}`,
+      { files: conflicts }
+    );
+  }
 
-  for (const [filePath, base64] of Object.entries(data.files)) {
-    const buffer = Buffer.from(base64, "base64");
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, buffer);
+  if (!dryRun) {
+    for (const { path: relPath, content, mode, action } of entries) {
+      const abs = path.join(root, relPath);
+      if (action !== "unchanged") {
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, content, { mode });
+      }
+      fs.chmodSync(abs, mode); // `mode` above only applies when the file is created
+    }
   }
+
+  return { files: entries.map(({ path, action }) => ({ path, action })) };
 }

package/lib/encrypt.js

@@ -1,50 +1,68 @@
 import fs from "fs";
-import { encryptData } from "./crypto.js";
+import path from "path";
+import { encryptData, MIN_PASSWORD_LENGTH } from "./crypto.js";
+import { ZurikError } from "./errors.js";
+import { BUNDLE_FILE, LIST_FILE, readFileList } from "./bundle.js";
 
-export default async function encryptFiles(password) {
-  const listFile = ".gitencrypt";
-
-  if (!fs.existsSync(listFile)) {
-    throw new Error(".gitencrypt not found");
+export default async function encryptFiles({ root, password, dryRun = false }) {
+  // Only enforced when encrypting, so bundles made with shorter passwords still decrypt.
+  if ([...password].length < MIN_PASSWORD_LENGTH) {
+    throw new ZurikError(
+      "E_WEAK_PASSWORD",
+      `Password must be at least ${MIN_PASSWORD_LENGTH} characters. ` +
+        "Use a generated passphrase, e.g. from your password manager or `openssl rand -base64 24`."
+    );
   }
 
-  const fileList = fs
-    .readFileSync(listFile, "utf8")
-    .split("\n")
-    .map(x => x.trim())
-    .filter(Boolean);
-
+  const fileList = readFileList(root);
+  if (fileList === null) {
+    throw new ZurikError("E_NO_LIST", `${LIST_FILE} not found in ${root}`);
+  }
   if (fileList.length === 0) {
-    throw new Error("No files listed in .gitencrypt");
+    throw new ZurikError("E_EMPTY_LIST", `No files listed in ${LIST_FILE}`);
   }
 
-  const bundle = { version: 1, files: {} };
+  // Refuse to write a partial bundle: it would silently overwrite secrets in the existing .zurik.
+  const missing = fileList.filter(f => !fs.existsSync(path.join(root, f)));
+  if (missing.length > 0) {
+    throw new ZurikError(
+      "E_MISSING_FILES",
+      `Missing files listed in ${LIST_FILE} (run 'zurik decrypt' first?):\n  ${missing.join("\n  ")}`,
+      { files: missing }
+    );
+  }
 
-  for (const filePath of fileList) {
-    if (!fs.existsSync(filePath)) {
-      console.warn(`Skipping missing file: ${filePath}`);
-      continue;
-    }
+  // `modes` is optional so bundles stay readable by older zurik versions.
+  const bundle = { version: 1, files: {}, modes: {} };
 
-    const content = fs.readFileSync(filePath);
-    bundle.files[filePath] = content.toString("base64");
+  for (const filePath of fileList) {
+    const abs = path.join(root, filePath);
+    bundle.files[filePath] = fs.readFileSync(abs).toString("base64");
+    bundle.modes[filePath] = fs.statSync(abs).mode & 0o777;
   }
 
   const encrypted = await encryptData(JSON.stringify(bundle), password);
-  fs.writeFileSync(".zurik", encrypted);
+  const gitignoreAdded = updateGitignore(root, fileList, dryRun);
+
+  if (!dryRun) {
+    fs.writeFileSync(path.join(root, BUNDLE_FILE), encrypted);
+  }
 
-  updateGitignore(fileList);
+  return {
+    files: fileList.map(p => ({ path: p, action: "encrypted" })),
+    gitignoreAdded,
+  };
 }
 
-function updateGitignore(fileList) {
-  const gi = ".gitignore";
-  let text = fs.existsSync(gi) ? fs.readFileSync(gi, "utf8") : "";
+// Appends listed files that .gitignore doesn't already contain as a whole line. Returns what was (or would be) added.
+function updateGitignore(root, fileList, dryRun) {
+  const gi = path.join(root, ".gitignore");
+  const text = fs.existsSync(gi) ? fs.readFileSync(gi, "utf8") : "";
+  const lines = new Set(text.split("\n").map(x => x.trim()));
 
-  for (const file of fileList) {
-    if (!text.includes(file)) {
-      text += `\n${file}`;
-    }
+  const toAdd = fileList.filter(f => !lines.has(f) && !lines.has(`/${f}`));
+  if (toAdd.length > 0 && !dryRun) {
+    fs.writeFileSync(gi, [text.trimEnd(), ...toAdd].filter(Boolean).join("\n") + "\n");
   }
-
-  fs.writeFileSync(gi, text.trim() + "\n");
+  return toAdd;
 }

package/lib/errors.js

@@ -0,0 +1,25 @@
+// Stable error codes. Agents and scripts should branch on `code`, not on `message`.
+export const ERROR_CODES = {
+  E_USAGE: "Invalid command line arguments",
+  E_NO_PASSWORD: "No password was provided",
+  E_WEAK_PASSWORD: "Password is too short to encrypt with",
+  E_WRONG_PASSWORD: "Wrong password, or the bundle was modified",
+  E_CORRUPT: "The .zurik file is not a valid bundle",
+  E_NOT_FOUND: "No .gitencrypt / .zurik found in this directory or any parent",
+  E_NO_LIST: ".gitencrypt is missing",
+  E_EMPTY_LIST: ".gitencrypt lists no files",
+  E_NO_BUNDLE: ".zurik is missing",
+  E_MISSING_FILES: "Files listed in .gitencrypt do not exist (details.files)",
+  E_WOULD_OVERWRITE: "Local files differ from the bundle; rerun with --force (details.files)",
+  E_UNSAFE_PATH: "A path is absolute or outside the project (details.path)",
+  E_INTERNAL: "Unexpected internal error",
+};
+
+export class ZurikError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "ZurikError";
+    this.code = code;
+    this.details = details;
+  }
+}

package/lib/index.js

@@ -0,0 +1,60 @@
+// Programmatic API. Every function returns a plain result object and throws ZurikError
+// (with a stable `code`) on failure. Nothing is printed and process.cwd() is never changed.
+import path from "path";
+import encryptFiles from "./encrypt.js";
+import decryptFiles from "./decrypt.js";
+import statusFiles from "./status.js";
+import { BUNDLE_FILE, LIST_FILE } from "./bundle.js";
+import { ZurikError, ERROR_CODES } from "./errors.js";
+import { findProjectRoot } from "./paths.js";
+import { MIN_PASSWORD_LENGTH } from "./crypto.js";
+
+export { ZurikError, ERROR_CODES, MIN_PASSWORD_LENGTH };
+
+const MARKERS = {
+  encrypt: [LIST_FILE],
+  decrypt: [BUNDLE_FILE],
+  status: [LIST_FILE, BUNDLE_FILE],
+};
+
+// `root` is used as-is; otherwise the nearest parent of `cwd` holding the command's marker file.
+export function resolveRoot(command, { root, cwd = process.cwd() } = {}) {
+  if (root) return path.resolve(root);
+  const markers = MARKERS[command];
+  const found = findProjectRoot(markers, cwd);
+  if (!found) {
+    throw new ZurikError(
+      "E_NOT_FOUND",
+      `${markers.join(" or ")} not found in ${path.resolve(cwd)} or any parent directory`
+    );
+  }
+  return found;
+}
+
+function requirePassword(password) {
+  if (typeof password !== "string" || password.length === 0) {
+    throw new ZurikError("E_NO_PASSWORD", "A password is required");
+  }
+}
+
+/** Encrypt the files listed in .gitencrypt into .zurik. Options: { password, root?, cwd?, dryRun? } */
+export async function encrypt(options = {}) {
+  requirePassword(options.password);
+  const root = resolveRoot("encrypt", options);
+  const dryRun = Boolean(options.dryRun);
+  return { command: "encrypt", root, dryRun, ...(await encryptFiles({ ...options, root, dryRun })) };
+}
+
+/** Decrypt .zurik into the working tree. Options: { password, root?, cwd?, force?, dryRun? } */
+export async function decrypt(options = {}) {
+  requirePassword(options.password);
+  const root = resolveRoot("decrypt", options);
+  const dryRun = Boolean(options.dryRun);
+  return { command: "decrypt", root, dryRun, ...(await decryptFiles({ ...options, root, dryRun })) };
+}
+
+/** Compare .gitencrypt, .zurik and local files. The password is only needed when .zurik exists. */
+export async function status(options = {}) {
+  const root = resolveRoot("status", options);
+  return { command: "status", root, ...(await statusFiles({ ...options, root })) };
+}

package/lib/paths.js

@@ -0,0 +1,32 @@
+import fs from "fs";
+import path from "path";
+import { ZurikError } from "./errors.js";
+
+// Walks up from `start` to the nearest directory containing any of `markers`; null if none.
+export function findProjectRoot(markers, start = process.cwd()) {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (markers.some(m => fs.existsSync(path.join(dir, m)))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// Normalizes a bundle path and ensures it stays inside `root`. Returns a "/"-separated relative path.
+export function safeRelativePath(filePath, root) {
+  if (typeof filePath !== "string" || filePath.length === 0 || path.isAbsolute(filePath)) {
+    throw new ZurikError("E_UNSAFE_PATH", `Refusing unsafe path: ${filePath}`, { path: filePath });
+  }
+
+  const resolved = path.resolve(root, filePath);
+  const rel = path.relative(root, resolved);
+
+  if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) {
+    throw new ZurikError("E_UNSAFE_PATH", `Refusing path outside project directory: ${filePath}`, {
+      path: filePath,
+    });
+  }
+
+  return rel.split(path.sep).join("/");
+}

package/lib/status.js

@@ -0,0 +1,39 @@
+import fs from "fs";
+import path from "path";
+import { BUNDLE_FILE, compareLocal, readBundle, readFileList } from "./bundle.js";
+import { ZurikError } from "./errors.js";
+
+// Per-file state, comparing .gitencrypt, .zurik and the working tree. Never reveals file contents.
+//   in-sync          local file matches the bundle
+//   modified         local file differs from the bundle  -> encrypt to save it, or decrypt --force to discard
+//   missing-locally  in the bundle, not on disk          -> decrypt
+//   not-in-bundle    listed and on disk, not in bundle   -> encrypt
+//   missing          listed, but neither on disk nor in the bundle
+// `listed` is false for files in the bundle that were removed from .gitencrypt (the next encrypt drops them).
+export default async function status({ root, password }) {
+  const listed = new Set(readFileList(root) ?? []);
+  const bundleExists = fs.existsSync(path.join(root, BUNDLE_FILE));
+  if (bundleExists && (typeof password !== "string" || password.length === 0)) {
+    throw new ZurikError("E_NO_PASSWORD", `A password is required to compare against ${BUNDLE_FILE}`);
+  }
+  const bundle = bundleExists ? await readBundle(root, password) : [];
+  const inBundle = new Map(bundle.map(e => [e.path, e.content]));
+
+  const STATE = { missing: "missing-locally", same: "in-sync", different: "modified" };
+  const paths = [...new Set([...listed, ...inBundle.keys()])].sort();
+
+  const files = paths.map(p => {
+    const state = inBundle.has(p)
+      ? STATE[compareLocal(root, p, inBundle.get(p))]
+      : fs.existsSync(path.join(root, p))
+        ? "not-in-bundle"
+        : "missing";
+    return { path: p, state, listed: listed.has(p) };
+  });
+
+  return {
+    bundleExists,
+    inSync: files.length > 0 && files.every(f => f.state === "in-sync" && f.listed),
+    files,
+  };
+}

package/package.json

@@ -1,10 +1,26 @@
 {
   "name": "zurik",
-  "version": "1.0.3",
+  "version": "2.0.0",
   "description": "CLI tool for encrypting and decrypting sensitive project files into a single .zurik bundle.",
   "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
   "bin": {
-    "zurik": "./bin/zurik.js"
+    "zurik": "bin/zurik.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "skills"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
   },
   "keywords": [
     "encryption",
@@ -13,12 +29,16 @@
     "aes",
     "gcm",
     "git",
-    "files"
+    "files",
+    "secrets",
+    "dotenv",
+    "ai-agents",
+    "automation"
   ],
   "author": "Safi",
   "repository": {
     "type": "git",
-    "url": "git@github.com:apotox/zurik.git"
+    "url": "git+ssh://git@github.com/apotox/zurik.git"
   },
   "license": "MIT"
 }

package/readme.md

@@ -6,47 +6,156 @@ It collects file paths from `.gitencrypt`, bundles them into a single `.zurik` f
 ## Features
 
 - Encrypt multiple files into a **single** `.zurik` bundle
-- AES-256-GCM authenticated encryption
-- Automatically append sensitive files to `.gitignore` when encrypting.
+- AES-256-GCM authenticated encryption with a scrypt-derived key
+- Automatically appends sensitive files to `.gitignore` when encrypting
+- Preserves file permissions; never overwrites changed local files without `--force`
+- Built for automation and AI agents: `--json` output, stable error codes, `status` and `--dry-run`, never blocks on a prompt, and a library API
 
 ## Installation
 
-You can run it directly using `npx`:
+Requires Node.js 18 or newer. Run it directly with `npx`, or install it globally:
 
 ```sh
-export ZURIK_PASSWORD="your-secret"
-npx zurik -e
-
-# or install it globally
+npx zurik help
 npm install -g zurik
+```
+
+## Choosing a password
+
+Anyone who obtains `.zurik` can try passwords offline, as fast as their hardware allows. zurik makes each guess expensive (scrypt with N=2¹⁷, ~128 MiB of memory per guess), but only a strong password actually protects the files.
 
-# also you can pass the password as an argument
-npx zurik -e -p "your-password"
+- Passwords must be at least **16 characters** to encrypt.
+- Use a randomly generated one, stored in a password manager or your CI secret store:
 
-# or you can type the password interactively
-npx zurik -e -p
+  ```sh
+  openssl rand -base64 24
+  ```
+
+## Providing the password
+
+In order of preference:
+
+```sh
+# 1. interactive prompt (zurik prompts automatically in a terminal when no other source is set)
+npx zurik encrypt
+
+# 2. environment variable or a file, e.g. in CI or an agent's environment
+export ZURIK_PASSWORD="your-secret"          # or: export ZURIK_PASSWORD_FILE=~/.secrets/zurik
+npx zurik encrypt
+npx zurik encrypt --password-file ~/.secrets/zurik
+
+# 3. piped from a password manager or secret store
+pass show my-project/zurik | npx zurik decrypt --password-stdin
+
+# 4. inline (avoid: visible in `ps` and saved in shell history)
+npx zurik encrypt -p "your-password"
 ```
 
+zurik never prompts when stdin is not a terminal, or with `--json`, `--no-input` or `$CI` set; it fails with `E_NO_PASSWORD` instead of hanging.
+
 ## Usage
+
 ### Encrypt files
-- create *.gitencrypt* file in the root of your project
-- add paths to files you want to encrypt, one per line
-- for example:
-```txt
-# .gitencrypt
-src/config.json
-src/secret.txt
-```
-- run the command below
+
+1. Create a `.gitencrypt` file in the root of your project.
+2. Add the paths of the files you want to encrypt, one per line. Lines starting with `#` are ignored, and paths must be inside the project.
+
+   ```txt
+   # secrets for local development
+   src/config.json
+   src/secret.txt
+   ```
+
+3. Run:
+
+   ```sh
+   npx zurik encrypt
+   ```
+
+The files are encrypted into `.zurik`, and any that are not already listed in `.gitignore` are appended to it. Commit `.zurik` and `.gitencrypt`.
+
+Every listed file must exist. If any is missing, nothing is written, so an existing `.zurik` is never overwritten with a partial bundle. On a fresh clone, run `zurik decrypt` first.
+
+### Decrypt files
+
 ```sh
-npx zurik -e -p "your-password"
+npx zurik decrypt
 ```
-- the encrypted files will be saved in `.zurik` file
-- it will also add the encrypted files to `.gitignore` if they are not already ignored
 
-### Decrypt files
-- run the command below to decrypt the files
+Files are restored to their original paths with their original permissions. If a local file has changed since it was encrypted, zurik lists the affected files and stops; pass `--force` to overwrite them.
+
+### Check status
+
+```sh
+npx zurik status
+```
+
+Shows, for every file, whether it is `in-sync`, `modified`, `missing-locally`, `not-in-bundle` or `missing`, without writing anything or printing contents. The password is only needed once `.zurik` exists.
+
+Add `--dry-run` (`-n`) to `encrypt` or `decrypt` to see what would happen without writing anything.
+
+You can run zurik from any subdirectory: it uses the nearest parent directory containing `.gitencrypt` (encrypt), `.zurik` (decrypt) or either (status). `--cwd <dir>` runs it against another directory.
+
+The short flags from earlier versions still work: `-e` (encrypt), `-d` (decrypt), `-s` (status).
+
+## Use with AI agents and automation
+
+zurik lets an agent manage secrets without the secrets, or the password, ever entering its context: it never prints file contents, and the password comes from the environment.
+
+**Give your agent the skill.** `zurik skill` prints a `SKILL.md` that tells an agent when to use zurik, how to supply the password safely, and how to handle each error (including asking before `--force`):
+
+```sh
+# Claude Code (project-level; use ~/.claude/skills for all projects)
+mkdir -p .claude/skills/zurik && npx zurik skill > .claude/skills/zurik/SKILL.md
+```
+
+For other agents, add the output to `AGENTS.md`, or add this line:
+
+```md
+Secrets are managed with zurik (.gitencrypt / .zurik). Run `npx zurik skill` for instructions; never read or print secret files or the password.
+```
+
+**Provide the password** through `ZURIK_PASSWORD` or `ZURIK_PASSWORD_FILE` in the agent's environment, never in the prompt.
+
+**Machine-readable interface.** With `--json`, stdout is exactly one JSON object:
+
+```sh
+$ npx zurik status --json
+{"ok":true,"command":"status","root":"/repo","bundleExists":true,"inSync":false,
+ "files":[{"path":".env","state":"modified","listed":true}]}
+
+$ npx zurik decrypt --json
+{"ok":false,"error":{"code":"E_WOULD_OVERWRITE","message":"...","details":{"files":[".env"]}}}
+```
+
+Branch on `error.code`. Exit codes are `0` success, `1` error and `2` usage error. `npx zurik help --json` prints the full spec: commands, result shapes, password sources and every error code.
+
+**Library API** for harnesses and scripts. It returns the same objects as `--json`, throws `ZurikError` with a `code`, prints nothing and never changes `process.cwd()`:
+
+```js
+import { encrypt, decrypt, status, ZurikError } from "zurik";
+
+const s = await status({ cwd: "/repo", password: process.env.ZURIK_PASSWORD });
+if (!s.inSync) {
+  try {
+    await decrypt({ root: "/repo", password: process.env.ZURIK_PASSWORD });
+  } catch (err) {
+    if (err instanceof ZurikError && err.code === "E_WOULD_OVERWRITE") console.log(err.details.files);
+    else throw err;
+  }
+}
+```
+
+Options: `password`, `cwd` (search for the project root from here) or `root` (use exactly), `force` and `dryRun`.
+
+## Bundle format
+
+`.zurik` is a text file: `zurik2:` followed by base64 of `logN | r | p | salt (16) | iv (12) | tag (16) | ciphertext`. The scrypt parameters are authenticated as AES-GCM additional data, so they cannot be altered to weaken the key.
+
+Bundles written by zurik 1.0.5 and earlier (no `zurik2:` prefix) still decrypt, including those with passwords shorter than 16 characters. The next `zurik encrypt` rewrites them in the new format, and at that point the password must meet the minimum length.
+
+## Development
+
 ```sh
-npx zurik -d -p "your-password"
+npm test
 ```
-- the decrypted files will be saved in the same directory as the original files

package/skills/zurik/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: zurik
+description: Encrypt, decrypt and check project secrets (.env files, keys, config) that are stored in a .zurik bundle and listed in .gitencrypt. Use whenever a repo contains .zurik or .gitencrypt, when secret files are missing after a clone, when the user asks to encrypt/commit/share/restore secrets, or before editing or committing a file listed in .gitencrypt. Prefer it over reading, copying, printing or hand-encrypting secret files.
+---
+
+# zurik
+
+zurik keeps a project's secret files encrypted in one committed file, `.zurik`. The plaintext files are listed in `.gitencrypt` and are git-ignored. zurik never prints file contents, so you can manage secrets without them entering your context.
+
+Run it with `npx zurik` (or `zurik` if it's installed). Always pass `--json` and branch on `ok` / `error.code`, never on message text.
+
+## Commands
+
+| Goal | Command |
+|---|---|
+| See what's out of sync (safe, read-only) | `npx zurik status --json` |
+| Restore secrets after a clone | `npx zurik decrypt --json` |
+| Save changes to secret files into `.zurik` | `npx zurik encrypt --json` |
+| Preview without writing anything | add `--dry-run` |
+| Machine-readable spec of all options and codes | `npx zurik help --json` |
+
+`--cwd <dir>` runs against another directory. zurik uses the nearest parent directory containing `.gitencrypt` / `.zurik`.
+
+## Password: never put it in your context
+
+- Do **not** ask the user to paste the password into the chat. Do **not** use `-p <password>` or `--password <value>`: that puts it in the transcript, the shell history and the process list.
+- Use what the environment already provides, in this order: `$ZURIK_PASSWORD`, `$ZURIK_PASSWORD_FILE`, or `--password-file <path>` / `--password-stdin` piped from a secret manager the user names (e.g. `op read ... | npx zurik decrypt --password-stdin --json`).
+- On `E_NO_PASSWORD`, stop and tell the user to set `ZURIK_PASSWORD` (or `ZURIK_PASSWORD_FILE`) in the environment the agent runs in. Don't guess or generate one for an existing bundle.
+- zurik never prompts when stdin isn't a terminal or when `--json` is set, so it won't hang.
+
+## Workflow
+
+1. `status --json` first. States: `in-sync`, `modified` (local differs from bundle), `missing-locally` (run decrypt), `not-in-bundle` (run encrypt), `missing` (listed but absent everywhere). `listed: false` means it's in the bundle but was removed from `.gitencrypt`.
+2. After a clone or when files are `missing-locally`: `decrypt --json`.
+3. After you or the user changed a secret file: `encrypt --json`, then commit `.zurik` (and `.gitencrypt` / `.gitignore` if they changed). Never commit the plaintext files.
+4. To protect a new secret file: append its path to `.gitencrypt`, then `encrypt --json`. zurik adds it to `.gitignore` for you.
+
+## Errors
+
+| `error.code` | What to do |
+|---|---|
+| `E_NO_PASSWORD` | Ask the user to provide the password via the environment (see above). |
+| `E_WRONG_PASSWORD` | Wrong password or tampered bundle. Tell the user; don't retry with guesses. |
+| `E_WOULD_OVERWRITE` | `error.details.files` have local changes. **Ask the user** before rerunning with `--force`; it discards those changes. If they should be kept, run `encrypt` instead. |
+| `E_MISSING_FILES` | `error.details.files` are listed but absent. Usually run `decrypt` first, or remove them from `.gitencrypt` if they're obsolete. |
+| `E_WEAK_PASSWORD` | Encrypting needs 16+ characters. The user must choose a longer password. |
+| `E_NOT_FOUND`, `E_NO_LIST`, `E_NO_BUNDLE`, `E_EMPTY_LIST` | Nothing to work on at this location; check `--cwd` or set up `.gitencrypt`. |
+| `E_UNSAFE_PATH` | A path is absolute or outside the project. Fix `.gitencrypt`; for a bundle, treat it as suspicious and tell the user. |
+
+Exit codes: `0` success, `1` error, `2` usage error.
+
+## Rules
+
+- Don't `cat`, print, summarize or copy decrypted secret files unless the user explicitly asks to see them. Edit them in place when a task requires it.
+- Don't use `--force` without the user's go-ahead.
+- Don't delete `.zurik`, and don't remove entries from `.gitencrypt` unless asked.

package/.github/workflows/publish.yml

@@ -1,31 +0,0 @@
-name: Publish to npm
-
-on:
-  push:
-    tags:
-      - 'v*.*.*'
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Set up Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Install deps
-        run: npm ci
-
-      - name: Build
-        run: npm run build --if-present
-
-      - name: Publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: npm publish --access public