safedrop-cli 1.0.0

package/API.md

@@ -0,0 +1,197 @@
+# SafeDrop public API contract
+
+This document describes **only the public HTTP endpoints the CLI consumes**. It
+is the contract between any SafeDrop client (browser or CLI) and the SafeDrop
+backend. It deliberately documents nothing about the server's internals
+(storage, Redis keys, token signing, rate-limit internals).
+
+All request/response bodies are JSON unless noted. The `--api` base URL is
+prefixed to every path below. For the hosted app that base is
+`https://safedrop.ma/api`; for local development it is `http://localhost:4000`.
+
+Throughout, **`uploadCode`** is a 16-character identifier and **`handshakeCode`**
+is a 16-character identifier.
+
+---
+
+## Sender endpoints
+
+### `POST /initiate-upload`
+
+Reserve an upload slot and obtain a presigned storage URL.
+
+**Request body** (all optional):
+
+```json
+{ "customExpirationSeconds": 3600 }
+```
+
+`customExpirationSeconds` clamps to the server's allowed range (max 24h); omit it
+for the default TTL (15 minutes).
+
+**Response `200`:**
+
+```json
+{
+  "uploadCode": "abcdef0123456789",
+  "url": "https://.../presigned-put-url",
+  "sseToken": "…",
+  "senderToken": "…",
+  "maxFileSizeMB": 1024,
+  "uploadTTLSeconds": 900
+}
+```
+
+- `url` — presigned `PUT` URL for the encrypted bytes.
+- `senderToken` — secret proving you are the sender; required to finalize,
+  authorize, and cancel. Never share it.
+
+### `PUT <presigned url>`
+
+Upload the **encrypted** file bytes directly to storage.
+
+- Header: `Content-Type: application/octet-stream`
+- Body: the raw ciphertext payload (`IV || ciphertext || GCM tag`).
+- Success: HTTP `2xx`.
+
+### `POST /upload/:uploadCode/finalize`
+
+Attach the encrypted filename and commit the upload.
+
+**Request body:**
+
+```json
+{ "encryptedFilename": "<base64>", "senderToken": "…" }
+```
+
+**Response `200`:** `{ "message": "Upload finalized successfully." }`
+
+Errors: `400` missing filename, `401` missing sender token, `403` bad sender
+token, `404` bytes not uploaded, `413` file exceeds size limit.
+
+### `DELETE /upload/:uploadCode`  (sender cancellation)
+
+**Request body:** `{ "senderToken": "…" }`
+
+Terminates the session and deletes the encrypted copy. `403` on bad token.
+
+---
+
+## Receiver endpoints
+
+### `POST /handshake/initiate`
+
+Begin a receive handshake for an upload.
+
+**Request body:** `{ "uploadCode": "abcdef0123456789" }`
+
+**Response `200`:**
+
+```json
+{ "handshakeCode": "…", "recipientToken": "…", "sseToken": "…" }
+```
+
+- `handshakeCode` — read this to the sender so they can authorize you.
+- `recipientToken` — secret used to poll for the download token and to cancel.
+
+Errors: `404` invalid or expired upload code.
+
+### `GET /handshake/token/:uploadCode`
+
+Poll for the download token. Returns it once the sender has authorized.
+
+- Header: `Authorization: Bearer <recipientToken>`
+
+**Response `200`:** `{ "downloadToken": "<jwt>" }`
+
+**Response `404`:** `{ "error": "Token not found or expired." }` — not yet
+authorized; keep polling.
+
+**Response `403`:** the recipient token is invalid or the session was cancelled.
+
+> The download token is single-issue: once returned, the recipient token is
+> consumed.
+
+### `GET /upload/:uploadCode`  (download)
+
+Download the encrypted file.
+
+- Header: `Authorization: Bearer <downloadToken>`
+
+**Response `200`:**
+
+- Body: the raw ciphertext payload.
+- Header `X-Encrypted-Filename`: the base64 encrypted filename to decrypt
+  locally.
+
+The server **deletes its stored copy** as soon as the response finishes
+streaming. Errors: `401`/`403` bad token, `404` metadata missing/expired.
+
+### `DELETE /handshake/:uploadCode`  (recipient cancellation)
+
+- Header: `Authorization: Bearer <recipientToken>` (a valid download token is
+  also accepted).
+
+Terminates the session.
+
+---
+
+## Authorization (sender side)
+
+### `POST /handshake/authorize`
+
+The sender calls this with the handshake code the receiver gave them.
+
+**Request body:**
+
+```json
+{ "uploadCode": "abcdef0123456789", "handshakeCode": "…" }
+```
+
+**Response `200`:** `{ "message": "Download authorized" }`
+
+Errors: `403` wrong handshake code, `404` session terminated/expired, `429` too
+many failed attempts (the session is terminated for safety).
+
+---
+
+## Real-time events (optional)
+
+The server exposes Server-Sent Events at `GET /session-events/:sseToken`
+carrying `status-authorized` and `session-terminated` messages. The CLI does
+**not** require SSE — it polls `GET /handshake/token/:uploadCode` instead, which
+the browser also does as a fallback. SSE is documented here only for
+completeness.
+
+---
+
+## Client-side payload formats
+
+These are computed entirely on the client; the server treats them as opaque.
+
+### Encryption payload
+
+```
+payload = IV (12 bytes) || ciphertext || GCM auth tag (16 bytes)
+```
+
+- Algorithm: **AES-256-GCM**.
+- Key: 256-bit, shared as 64 lowercase hex characters.
+- The filename is encrypted the same way, but its plaintext is encoded as
+  **UTF-16LE** before encryption, then base64-encoded for the
+  `X-Encrypted-Filename` header / `encryptedFilename` field.
+
+### Combined share code
+
+```
+combinedCode = base64( JSON.stringify({ uploadCode, key, fullSecurity }) )
+```
+
+### Share link
+
+```
+https://<host>/#code=<combinedCode>
+```
+
+The code lives in the **URL fragment** (`#`), which browsers never transmit to a
+server.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SafeDrop
+
+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,185 @@
+# safedrop-cli
+
+Zero-knowledge, end-to-end encrypted file transfer from your terminal — fully
+compatible with the [SafeDrop](https://safedrop.ma) web app.
+
+Files are **encrypted on your machine before upload** and **decrypted on the
+receiver's machine after download**. The SafeDrop server only ever sees
+ciphertext: it never receives your plaintext files, your real filenames, or
+your encryption keys.
+
+A file sent from the CLI can be received in the browser, and a file sent from
+the browser can be received by the CLI — they use the identical encryption and
+code format.
+
+---
+
+## Install
+
+```bash
+npm install -g safedrop-cli
+```
+
+Or run without installing:
+
+```bash
+npx safedrop-cli send ./report.pdf
+```
+
+Requires **Node.js 18+** (uses the built-in `fetch` and `crypto`). The package
+has **zero runtime dependencies**, so it is small and easy to audit.
+
+---
+
+## Quick start
+
+### Send a file
+
+```bash
+safedrop send ./report.pdf
+```
+
+The CLI encrypts the file locally, uploads the ciphertext, and prints a **share
+code** (and a share link if you point it at a hosted SafeDrop). Give that code
+to your receiver. Then the receiver runs `receive`, reads you back a short
+**handshake code**, you paste it in, and the transfer is authorized.
+
+### Receive a file
+
+```bash
+safedrop receive eyJ1cGxvYWRDb2RlIjoi...
+```
+
+The CLI parses the code, shows you a handshake code to read to the sender, waits
+for them to authorize, then downloads and decrypts the file to your current
+directory.
+
+---
+
+## Commands
+
+```
+safedrop send <file> [options]
+safedrop receive <code-or-link> [options]
+```
+
+### `send` options
+
+| Option | Description |
+|---|---|
+| `--ttl <minutes>` | How long the transfer stays available before it expires. Default `15`, max `1440` (24h). |
+| `--secure` | Enable full-security mode: both sides compare an out-of-band 3-word safety code to detect interception. |
+| `--api <base-url>` | SafeDrop API base URL. Defaults to `http://localhost:4000`, or the `SAFEDROP_API` env var. |
+
+### `receive` options
+
+| Option | Description |
+|---|---|
+| `--output`, `-o <path>` | Where to save the file. A directory (saves under the sender's filename) or a full file path. |
+| `--api <base-url>` | SafeDrop API base URL. Defaults to `http://localhost:4000`, or the `SAFEDROP_API` env var. |
+
+### Pointing at a hosted SafeDrop
+
+The production web app serves its API under `/api`:
+
+```bash
+safedrop send ./report.pdf --api https://safedrop.ma/api
+# or set it once:
+export SAFEDROP_API=https://safedrop.ma/api
+safedrop send ./report.pdf
+```
+
+---
+
+## Examples
+
+```bash
+# Send with a 1-hour expiry and full-security verification
+safedrop send ./contract.pdf --ttl 60 --secure
+
+# Receive from a full browser link into your Downloads folder
+safedrop receive "https://safedrop.ma/#code=eyJ1cGxv..." -o ~/Downloads/
+
+# Receive and save under a specific name
+safedrop receive eyJ1cGxv... -o ./received-contract.pdf
+```
+
+See [`examples/transcript-sender.txt`](examples/transcript-sender.txt) and
+[`examples/transcript-receiver.txt`](examples/transcript-receiver.txt) for full
+end-to-end terminal walkthroughs.
+
+---
+
+## How a transfer works
+
+```
+SENDER                          SAFEDROP SERVER                    RECEIVER
+------                          ---------------                    --------
+encrypt file + name locally
+generate AES-256 key
+   │ POST /initiate-upload ───────────▶ uploadCode, presigned URL,
+   │                                    senderToken
+   │ PUT ciphertext ──────────────────▶ (stores ciphertext only)
+   │ POST /upload/:code/finalize ─────▶ (stores encrypted filename)
+print share code  ◀────────────────────────────────────────────  paste code
+                                                                   POST /handshake/initiate
+                                    handshakeCode ◀──────────────  (gets handshake code)
+read handshake code  ◀──────────────────────────────────────────  read it aloud
+   │ POST /handshake/authorize ───────▶ issues download token
+                                                  poll /handshake/token/:code ◀──
+                                    downloadToken ─────────────────────────────▶
+                                                  GET /upload/:code ◀───────────
+                                    ciphertext ────────────────────────────────▶
+                                    (server deletes its copy)      decrypt locally,
+                                                                   save to disk
+```
+
+The **key never leaves the client**. The server stores only the encrypted bytes
+and the encrypted filename, and deletes both the moment the download completes.
+
+---
+
+## Using it as a library
+
+The encryption and code helpers are exported so you can build your own tools:
+
+```js
+import {
+  encryptBuffer, decryptBuffer,
+  encodeCombinedCode, decodeCombinedCode,
+  SafeDropApi,
+} from 'safedrop-cli';
+```
+
+These are the same building blocks the CLI uses. See [`API.md`](API.md) for the
+HTTP contract and [`SECURITY.md`](SECURITY.md) for the threat model.
+
+---
+
+## Security at a glance
+
+- **AES-256-GCM** authenticated encryption, done entirely client-side.
+- The server is **zero-knowledge**: no keys, no plaintext, no real filenames.
+- Share **codes/links carry the key in the URL fragment** (`#code=...`), which
+  browsers never send to servers.
+- The CLI **never logs** file contents or keys; the share code is the only
+  secret it prints, and only because sharing it is the entire purpose.
+- Downloaded filenames are **sanitized** — path traversal is refused and local
+  files are **never overwritten without confirmation**.
+
+Full details in [`SECURITY.md`](SECURITY.md).
+
+---
+
+## Development
+
+```bash
+npm test        # runs the cross-compatibility, code-parsing, and path tests
+```
+
+The crypto tests encrypt with the CLI and decrypt using the **actual Web Crypto
+API** (and vice versa) to guarantee browser ⇄ CLI compatibility.
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,144 @@
+# SafeDrop CLI security model
+
+SafeDrop is **zero-knowledge**: the server stores and relays data it cannot
+read. This document explains the guarantees the CLI provides, how it provides
+them, and what is explicitly out of scope.
+
+---
+
+## The core guarantee
+
+> The SafeDrop server never receives plaintext file contents, plaintext
+> filenames, or encryption keys.
+
+Everything sensitive is encrypted and decrypted **on the client**. The CLI is
+just another zero-knowledge client, identical in behavior to the browser app.
+
+| Data | Where it is in plaintext | What the server sees |
+|---|---|---|
+| File contents | Sender's & receiver's machines only | AES-256-GCM ciphertext |
+| Real filename | Sender's & receiver's machines only | Encrypted, base64 blob |
+| Encryption key | Sender's machine, then the share code | Never |
+
+---
+
+## Cryptography
+
+- **AES-256-GCM** authenticated encryption (confidentiality + integrity). A
+  tampered or truncated payload fails decryption rather than producing garbage.
+- Keys are **256-bit**, generated with the OS CSPRNG (`crypto.randomBytes`).
+- A fresh **96-bit IV** is generated per encryption (`crypto.randomBytes(12)`)
+  and prepended to the payload.
+- Wire format: `IV (12B) || ciphertext || GCM tag (16B)` — byte-for-byte
+  identical to the browser's Web Crypto output, so files cross between the two
+  clients transparently. This is enforced by tests that decrypt CLI output with
+  the real Web Crypto API and vice versa.
+- Filenames are encrypted with the same scheme; their plaintext is UTF-16LE so
+  the bytes match the browser exactly.
+
+The CLI does **not** invent its own protocol — it reuses the established
+SafeDrop client format. No backend logic is reimplemented; the CLI only calls
+the documented HTTP API ([`API.md`](API.md)).
+
+---
+
+## Key distribution and links
+
+- The encryption key travels **only inside the share code**, which the sender
+  hands to the receiver out-of-band (chat, in person, etc.).
+- The combined code is `base64(JSON{ uploadCode, key, fullSecurity })`.
+- The browser share link places the code in the **URL fragment**
+  (`https://host/#code=...`). Fragments are never sent to the server in an HTTP
+  request, so navigating to a link does not leak the key to the host.
+- The CLI prints the share code to **stdout** and all status/log output to
+  **stderr**, so you can capture the code cleanly (e.g. `safedrop send f >
+  code.txt`) without log noise, and logs never carry the secret by accident.
+
+---
+
+## Optional MITM protection: full-security mode (`--secure`)
+
+When enabled, both sides derive a **3-word Short Authentication String (SAS)**
+from `SHA-256(key)` and compare it over a trusted channel (e.g. read it aloud on
+a call). If the words differ, the key was tampered with in transit and the
+transfer is aborted. The wordlist and derivation match the browser exactly, so a
+browser sender and CLI receiver (or vice versa) compute the same words.
+
+---
+
+## What the CLI does and does not log
+
+- **Never logged:** file contents, encryption keys, sender/recipient/download
+  tokens.
+- **Printed once, intentionally:** the share code (sender) and the handshake
+  code (receiver). These are the secrets you are meant to share — that is the
+  entire purpose of the command. The share code is written to stdout; with
+  `--secure` the safety code is shown so you can verify it.
+- Secrets are not written to any cache, history, or temp file by the CLI.
+
+---
+
+## Safe handling of downloaded files
+
+The decrypted filename comes from the sender and is therefore **untrusted
+input** after decryption. The CLI:
+
+- **Strips directory components** from the sender's filename (`../`, absolute
+  paths, drive letters, Windows separators) — a malicious name can only ever
+  resolve to a basename inside the chosen output directory.
+- **Refuses path traversal**: the resolved path is verified to stay within its
+  parent directory, otherwise the write is rejected.
+- **Neutralizes dangerous names**: control characters and Windows-illegal
+  characters are removed; reserved device names (`CON`, `NUL`, `COM1`, …) are
+  prefixed.
+- **Never overwrites without confirmation**: if the target exists you are asked;
+  declining writes to `name (1).ext`, `name (2).ext`, … instead.
+
+See [`test/paths.test.js`](test/paths.test.js) for the enforced behaviors.
+
+---
+
+## Availability, expiry, and cancellation
+
+- Transfers **expire** server-side after their TTL; the CLI reports expiry
+  cleanly on both sides rather than hanging.
+- **Either side can cancel.** The sender's `Ctrl-C` (or empty handshake input)
+  calls `DELETE /upload/:code`; the receiver's `Ctrl-C` calls
+  `DELETE /handshake/:code`. Both delete the encrypted server copy.
+- The server deletes the stored ciphertext the instant the download completes,
+  so each code is **single-use**.
+
+---
+
+## Validation and limits
+
+- File size is checked against the server limit (1024 MB) **before** upload, and
+  the server re-checks on finalize.
+- Network errors are translated into actionable messages (connection refused,
+  DNS failure, TLS problems, timeouts) instead of raw stack traces.
+
+---
+
+## Threat model — out of scope
+
+SafeDrop does **not** defend against:
+
+- A **compromised endpoint** (malware on the sender's or receiver's machine).
+  Plaintext exists there by necessity.
+- The sender **sending the code to the wrong person**, or an attacker who
+  obtains the code before the legitimate receiver (use `--secure` to detect a
+  key swap; protect the channel you share the code over).
+- **Traffic analysis** (the server learns file size and timing).
+- **Denial of service** against the server.
+
+Because the share code contains the key, **anyone who obtains the code can
+decrypt the file** until the transfer is downloaded, cancelled, or expires.
+Treat the code like a password and prefer ephemeral, trusted channels.
+
+---
+
+## Reporting
+
+This CLI is open source and dependency-free for auditability. Please report
+suspected vulnerabilities privately to the SafeDrop maintainers rather than
+opening a public issue.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "safedrop-cli",
+  "version": "1.0.0",
+  "description": "Zero-knowledge, end-to-end encrypted file transfer from your terminal. Fully compatible with the SafeDrop web app.",
+  "type": "module",
+  "bin": {
+    "safedrop": "src/cli.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./crypto": "./src/crypto.js",
+    "./code": "./src/code.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "API.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/",
+    "start": "node src/cli.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "safedrop",
+    "encryption",
+    "aes-256-gcm",
+    "zero-knowledge",
+    "file-transfer",
+    "e2ee",
+    "cli",
+    "secure"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/safedrop/safedrop-cli.git"
+  },
+  "dependencies": {}
+}