@dbarjs/dead-drop 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eduardo Barros
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# @dbarjs/dead-drop
+
+The CLI for the [Dead Drop](https://github.com/dbarjs/dead-drop-app) privacy-first relay. Encrypts a project directory end-to-end with a passphrase, uploads it as a single-use Drop, and lets the recipient retrieve it exactly once.
+
+## Install
+
+```sh
+pnpm i -g @dbarjs/dead-drop
+# or
+npm i -g @dbarjs/dead-drop
+```
+
+Requires Node.js ≥ 20.
+
+## Copy a project (sender)
+
+```sh
+dead-drop copy ./my-project --api https://drops.example.com
+```
+
+You'll be prompted for a passphrase. The CLI derives an AES-256 key from it, encrypts each file in-place, and uploads to the Dead Drop API. On success it prints the Drop URL — share that and the passphrase out-of-band with the recipient.
+
+## Cut a Drop (recipient)
+
+```sh
+dead-drop cut https://drops.example.com/api/drops/01ABC.../index --out ./recovered
+```
+
+You can also pass a bare ULID and an `--api` flag:
+
+```sh
+dead-drop cut 01ABC... --out ./recovered --api https://drops.example.com
+```
+
+Enter the same passphrase the sender used. Each file is fetched, decrypted, and written under `--out`. **Reading consumes the file** — the second cut sees `404` for any file that was already taken.
+
+## Configuration
+
+| Env var | Effect |
+| --- | --- |
+| `DEAD_DROP_API_URL` | Default base URL when `--api` is omitted. Falls back to `http://localhost:3000`. |
+
+## Local development (inside this monorepo)
+
+From the repo root, run the CLI directly via the workspace filter:
+
+```sh
+pnpm -F @dbarjs/dead-drop dev copy ./test-fixture
+pnpm -F @dbarjs/dead-drop dev cut https://localhost:3000/api/drops/<ulid>/index --out ./recovered
+pnpm -F @dbarjs/dead-drop build
+```
+
+The `dev` script runs `tsx src/cli.ts <args>` directly from source — no build step needed during iteration.
+
+## Security notes
+
+- Your passphrase never leaves your machine. It's run through PBKDF2-SHA256 (600k iterations) to derive the AES-GCM key. The server stores ciphertext only.
+- Lose the passphrase and the Drop is unrecoverable. There is no reset.
+- The server *can* see file metadata (paths, sizes, content hashes). It cannot see file contents.
+- Each file burns on first download. A mid-download network failure means that file is permanently lost.
+- Drops expire 24 hours after creation regardless of read state.

package/dist/cli.d.mts

@@ -0,0 +1 @@
+

package/dist/cli.d.ts

@@ -0,0 +1 @@
+

package/dist/cli.mjs

@@ -0,0 +1,365 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'node:url';
+import { defineCommand, runMain } from 'citty';
+import { readPackageJSON } from 'pkg-types';
+import { consola } from 'consola';
+import { join, relative, resolve, sep, dirname } from 'pathe';
+import { stat, readdir, readFile, mkdir, writeFile } from 'node:fs/promises';
+import { ofetch } from 'ofetch';
+
+const SALT_BYTES = 16;
+const NONCE_BYTES = 12;
+const PBKDF2_ITERATIONS = 6e5;
+async function deriveKey(passphrase, salt) {
+  const baseKey = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(passphrase),
+    "PBKDF2",
+    false,
+    ["deriveKey"]
+  );
+  return crypto.subtle.deriveKey(
+    { name: "PBKDF2", salt, iterations: PBKDF2_ITERATIONS, hash: "SHA-256" },
+    baseKey,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"]
+  );
+}
+async function encryptBytes(plaintext, key) {
+  const nonce = crypto.getRandomValues(new Uint8Array(NONCE_BYTES));
+  const cipher = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv: nonce },
+    key,
+    plaintext
+  );
+  return { ciphertext: new Uint8Array(cipher), nonce };
+}
+async function decryptBytes(ciphertext, key, nonce) {
+  const plain = await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv: nonce },
+    key,
+    ciphertext
+  );
+  return new Uint8Array(plain);
+}
+async function sha256Hex(bytes) {
+  const hash = await crypto.subtle.digest("SHA-256", bytes);
+  return [...new Uint8Array(hash)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function randomSalt() {
+  return crypto.getRandomValues(new Uint8Array(SALT_BYTES));
+}
+function toBase64(bytes) {
+  return Buffer.from(bytes).toString("base64");
+}
+function fromBase64(b64) {
+  return new Uint8Array(Buffer.from(b64, "base64"));
+}
+
+const IGNORED_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  ".nuxt",
+  ".output",
+  ".nitro",
+  ".cache",
+  "dist"
+]);
+async function* walkDirectory(rootDir) {
+  const root = await stat(rootDir);
+  if (!root.isDirectory()) {
+    throw new Error(`${rootDir} is not a directory`);
+  }
+  yield* walkInto(rootDir, rootDir);
+}
+async function* walkInto(rootDir, current) {
+  const entries = await readdir(current, { withFileTypes: true });
+  for (const entry of entries) {
+    if (IGNORED_DIRS.has(entry.name)) continue;
+    const absPath = join(current, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkInto(rootDir, absPath);
+    } else if (entry.isFile()) {
+      const relPath = relative(rootDir, absPath);
+      const bytes = new Uint8Array(await readFile(absPath));
+      yield { absPath, relPath, bytes };
+    }
+  }
+}
+
+function createApi(baseURL) {
+  return ofetch.create({ baseURL });
+}
+async function createDrop(api, body) {
+  return api("/api/drops", {
+    method: "POST",
+    body
+  });
+}
+async function appendFile(api, dropId, body) {
+  return api(`/api/drops/${dropId}/files`, {
+    method: "POST",
+    body
+  });
+}
+async function getIndex(api, dropId) {
+  return api(`/api/drops/${dropId}`);
+}
+async function burnFile(api, dropId, fileId) {
+  try {
+    const res = await api(`/api/drops/${dropId}/files/${fileId}`);
+    return { burned: true, data: res.data };
+  } catch (err) {
+    if (err?.response?.status === 404) {
+      return { burned: false };
+    }
+    throw err;
+  }
+}
+
+const CTRL_C = "";
+const BACKSPACE = "\x7F";
+const ENTER = "\r";
+const NEWLINE = "\n";
+const EOT = "";
+async function promptPassphrase(label = "Passphrase") {
+  const stdin = process.stdin;
+  if (!stdin.isTTY) {
+    let buf = "";
+    stdin.setEncoding("utf8");
+    for await (const chunk of stdin) {
+      buf += chunk;
+    }
+    return buf.replace(/\r?\n$/, "");
+  }
+  process.stdout.write(`${label}: `);
+  return new Promise((resolve, reject) => {
+    let buf = "";
+    const cleanup = () => {
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdin.off("data", onData);
+    };
+    const onData = (chunk) => {
+      const text = chunk.toString("utf8");
+      for (const ch of text) {
+        if (ch === ENTER || ch === NEWLINE) {
+          cleanup();
+          process.stdout.write("\n");
+          resolve(buf);
+          return;
+        }
+        if (ch === CTRL_C) {
+          cleanup();
+          process.stdout.write("\n");
+          reject(new Error("Interrupted"));
+          return;
+        }
+        if (ch === EOT) {
+          cleanup();
+          process.stdout.write("\n");
+          resolve(buf);
+          return;
+        }
+        if (ch === BACKSPACE || ch === "\b") {
+          buf = buf.slice(0, -1);
+          continue;
+        }
+        if (ch.charCodeAt(0) < 32) continue;
+        buf += ch;
+      }
+    };
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on("data", onData);
+  });
+}
+
+const DEFAULT_BASE_URL = "http://localhost:3000";
+function resolveBaseUrl(flag) {
+  const raw = flag ?? process.env.DEAD_DROP_API_URL ?? DEFAULT_BASE_URL;
+  return raw.replace(/\/+$/, "");
+}
+const ULID_RE = /[0-9A-HJKMNP-TV-Z]{26}/;
+function parseDropTarget(input, apiFlag) {
+  if (/^https?:\/\//i.test(input)) {
+    const url = new URL(input);
+    const match = url.pathname.match(/\/api\/drops\/([0-9A-HJKMNP-TV-Z]{26})(?:\/index)?\/?$/);
+    if (!match) {
+      throw new Error(`Cannot parse dropId from URL: ${input}`);
+    }
+    return {
+      dropId: match[1],
+      baseUrl: `${url.protocol}//${url.host}`
+    };
+  }
+  if (!ULID_RE.test(input)) {
+    throw new Error(`Not a valid dropId or Drop URL: ${input}`);
+  }
+  return { dropId: input, baseUrl: resolveBaseUrl(apiFlag) };
+}
+
+const copy = defineCommand({
+  meta: {
+    name: "copy",
+    description: "Encrypt a directory and upload it as a Drop."
+  },
+  args: {
+    directory: {
+      type: "positional",
+      required: true,
+      description: "Path to the directory to copy."
+    },
+    api: {
+      type: "string",
+      description: "API base URL (overrides $DEAD_DROP_API_URL, default http://localhost:3000)."
+    }
+  },
+  async run({ args }) {
+    const rootDir = resolve(args.directory);
+    const baseUrl = resolveBaseUrl(args.api);
+    const api = createApi(baseUrl);
+    const passphrase = await promptPassphrase();
+    if (!passphrase) {
+      consola.error("Passphrase required.");
+      process.exit(2);
+    }
+    const salt = randomSalt();
+    const key = await deriveKey(passphrase, salt);
+    const kdf = {
+      algorithm: "PBKDF2-SHA256",
+      iterations: PBKDF2_ITERATIONS,
+      salt: toBase64(salt)
+    };
+    let dropId = null;
+    let count = 0;
+    for await (const file of walkDirectory(rootDir)) {
+      const { ciphertext, nonce } = await encryptBytes(file.bytes, key);
+      const contentHash = await sha256Hex(file.bytes);
+      const entry = {
+        path: file.relPath,
+        rawSize: file.bytes.byteLength,
+        ciphertextSize: ciphertext.byteLength,
+        contentHash,
+        nonce: toBase64(nonce)
+      };
+      const data = toBase64(ciphertext);
+      if (dropId === null) {
+        const res = await createDrop(api, { kdf, file: entry, data });
+        dropId = res.dropId;
+        consola.log(`+ ${file.relPath}  (drop ${dropId})`);
+      } else {
+        await appendFile(api, dropId, { file: entry, data });
+        consola.log(`+ ${file.relPath}`);
+      }
+      count++;
+    }
+    if (count === 0 || dropId === null) {
+      consola.error("No files found to upload.");
+      process.exit(1);
+    }
+    consola.log("");
+    consola.success(`Copied ${count} file${count === 1 ? "" : "s"}.`);
+    consola.log(`Drop ID:  ${dropId}`);
+    consola.log(`Index:    ${baseUrl}/api/drops/${dropId}`);
+    consola.log("");
+    consola.log(`To cut:   dead-drop cut ${baseUrl}/api/drops/${dropId} --out <dir>`);
+  }
+});
+
+function safeJoin(outDir, relPath) {
+  const outAbs = resolve(outDir);
+  const target = resolve(outAbs, relPath);
+  if (target !== outAbs && !target.startsWith(outAbs + sep)) {
+    throw new Error(`unsafe path escapes output directory: ${relPath}`);
+  }
+  return target;
+}
+
+const cut = defineCommand({
+  meta: {
+    name: "cut",
+    description: "Fetch a Drop, decrypt, and write to disk (burns each file as it goes)."
+  },
+  args: {
+    target: {
+      type: "positional",
+      required: true,
+      description: "Drop URL or bare dropId (ULID)."
+    },
+    out: {
+      type: "string",
+      required: true,
+      description: "Output directory where decrypted files are written."
+    },
+    api: {
+      type: "string",
+      description: "API base URL when passing a bare dropId (overrides $DEAD_DROP_API_URL)."
+    }
+  },
+  async run({ args }) {
+    const { dropId, baseUrl } = parseDropTarget(args.target, args.api);
+    const outDir = resolve(args.out);
+    const api = createApi(baseUrl);
+    const passphrase = await promptPassphrase();
+    if (!passphrase) {
+      consola.error("Passphrase required.");
+      process.exit(2);
+    }
+    const index = await getIndex(api, dropId);
+    const salt = fromBase64(index.kdf.salt);
+    const key = await deriveKey(passphrase, salt);
+    let written = 0;
+    let alreadyGone = 0;
+    let failed = 0;
+    for (const entry of index.files) {
+      const burn = await burnFile(api, dropId, entry.fileId);
+      if (!burn.burned) {
+        consola.log(`- ${entry.path}  (already cut)`);
+        alreadyGone++;
+        continue;
+      }
+      try {
+        const ciphertext = fromBase64(burn.data);
+        const nonce = fromBase64(entry.nonce);
+        const plaintext = await decryptBytes(ciphertext, key, nonce);
+        const actualHash = await sha256Hex(plaintext);
+        if (actualHash !== entry.contentHash) {
+          consola.fail(`${entry.path}  (content hash mismatch)`);
+          failed++;
+          continue;
+        }
+        const target = safeJoin(outDir, entry.path);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, plaintext);
+        consola.log(`+ ${entry.path}`);
+        written++;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes("decrypt")) {
+          consola.fail(`${entry.path}  (decryption failed \u2014 wrong passphrase?)`);
+        } else {
+          consola.fail(`${entry.path}  (${msg})`);
+        }
+        failed++;
+      }
+    }
+    consola.log("");
+    consola.success(
+      `Cut ${written} file${written === 1 ? "" : "s"}` + (alreadyGone ? `, ${alreadyGone} already cut` : "") + (failed ? `, ${failed} failed` : "") + "."
+    );
+    if (failed > 0) process.exit(1);
+  }
+});
+
+const pkg = await readPackageJSON(fileURLToPath(new URL("../package.json", import.meta.url)));
+const main = defineCommand({
+  meta: {
+    name: "dead-drop",
+    version: pkg.version,
+    description: pkg.description
+  },
+  subCommands: { copy, cut }
+});
+runMain(main);

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@dbarjs/dead-drop",
+  "version": "0.1.0",
+  "description": "Privacy-first dead-drop CLI: copy a project directory; the recipient cuts it once.",
+  "type": "module",
+  "bin": {
+    "dead-drop": "./dist/cli.mjs"
+  },
+  "main": "./dist/cli.mjs",
+  "types": "./dist/cli.d.mts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "citty": "^0.1.6",
+    "consola": "^3.4.2",
+    "ofetch": "^1.5.1",
+    "pathe": "^1.1.2",
+    "pkg-types": "^1.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.8.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "unbuild": "^3.5.0",
+    "vitest": "^4.1.6"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "unbuild",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}