bytifi 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # Bytifi CLI
 
-Official command-line tool for encrypting and uploading files to [Bytifi](https://bytifi.com).
+Official command-line tool for encrypting, uploading, and decrypting files with [Bytifi](https://bytifi.com).
 
 ## Install
 
@@ -49,11 +49,61 @@ Prefer the environment variable — keys on the command line can appear in shell
 
 ## Usage
 
+### Upload
+
 ```bash
 bytifi upload ./photo.png
-bytifi upload ./photo.png --api-key usk_your_api_key_here
-bytifi upload ./photo.png --expires 60 --json
-bytifi upload ./large.iso -q
+bytifi upload "./my video (1).mp4"
+bytifi upload ./report.pdf --expires 60 --delete-on-download
+bytifi upload ./large.iso --json > upload.json
+bytifi upload ./photo.png -q
+```
+
+Upload accepts **one file at a time**. Quote paths that contain spaces. Avoid shell globs like `**` — your shell may expand them into dozens of paths.
+
+### Decrypt from a link
+
+Download and decrypt directly from a share URL or link token. No API key required.
+
+```bash
+bytifi decrypt 'https://bytifi.com/link?link=LINK_ID#token=ENCRYPTION_TOKEN'
+bytifi decrypt LINK_ID --token ENCRYPTION_TOKEN -o ./restored.mp4
+```
+
+### Decrypt a downloaded encrypted file
+
+If you already downloaded the encrypted blob from `/f/LINK_ID` (browser, curl, etc.):
+
+```bash
+# Easiest — use the upload JSON from when you uploaded
+bytifi decrypt ./downloaded-file --upload-json upload.json
+
+# Or pass both values manually
+bytifi decrypt "./my video (1).mp4" \
+  --link LINK_ID \
+  --token ENCRYPTION_TOKEN
+```
+
+#### Link ID vs encryption token
+
+Bytifi uses two different values — don't swap them:
+
+| Name | Upload JSON field | Example location |
+|------|-------------------|------------------|
+| **Link ID** | `token` | `/f/QeVuslvdaP-okMxG`, `link?link=QeVuslvdaP-okMxG` |
+| **Encryption token** | `encryptionToken` | `#token=2LTlmBrDkO4GJg0...` in `shareUrl` |
+
+- `--link` = link ID (short, ~16 chars)
+- `--token` = encryption key (long, ~43 chars)
+
+### Offline decrypt workflow
+
+Save metadata when you upload, so you can decrypt after the link expires:
+
+```bash
+bytifi upload ./report.pdf --json > upload.json
+curl -L "$(jq -r .encryptedFile upload.json)" -o report.encrypted
+bytifi decrypt ./report.encrypted --upload-json upload.json -o ./report.pdf
 ```
 
 Without a global install:
@@ -65,7 +115,7 @@ npm exec bytifi -- upload ./photo.png --api-key usk_your_api_key_here
 
 Note: with `npm exec`, put `--` before the file path so npm does not swallow `--api-key`.
 
-### Options
+### Upload options
 
 | Flag | Description |
 |------|-------------|
@@ -78,20 +128,47 @@ Note: with `npm exec`, put `--` before the file path so npm does not swallow `--
 | `--mime-type` | Override detected MIME type |
 | `--base-url` | API base URL (default: `https://bytifi.com`) |
 
+### Decrypt options
+
+| Flag | Description |
+|------|-------------|
+| `--token` | Encryption key from `#token=...` (`encryptionToken` in upload JSON) |
+| `--link` | Link ID from upload JSON `token` field (`/f/TOKEN`) |
+| `--upload-json` | Upload `--json` output file (recommended for downloaded files) |
+| `--meta` | Saved `clientEncryptionMeta` JSON for offline decrypt |
+| `--share-url` | Share URL to read token/metadata while decrypting a local file |
+| `-o, --output` | Output file path |
+| `--output-dir` | Output directory when saving under the original filename |
+| `--json` | Machine-readable JSON output |
+| `-q, --quiet` | Print only the output file path |
+| `--verbose` | Print error details to stderr |
+| `--base-url` | API base URL (default: `https://bytifi.com`) |
+
 Exit codes: `0` success, `1` usage error, `2` API error, `3` network error.
 
-JSON output (`--json`) includes `shareUrl`, `downloadUrl`, `encryptionToken`, `expiresAt`, and `token`.
+JSON output (`--json`) for upload includes `shareUrl`, `encryptedFile`, `encryptionToken`, `clientEncryptionMeta`, `expiresAt`, and `token`.
+
+JSON output for decrypt includes `outputPath`, `originalName`, `size`, `mimeType`, `expiresAt`, `linkToken`, `storageMode`, and `sourcePath` (for local decrypt).
 
 Files over ~100 MB encrypted use multipart upload automatically. Progress prints to stderr unless `--json` or `--quiet` is set.
 
 ## How it works
 
+**Upload**
+
 1. Encrypts the file locally with AES-GCM (same format as the website)
 2. Uploads encrypted bytes via the public API (parallel part uploads for large files)
 3. Prints a share URL including `#token=...`
 
+**Decrypt**
+
+1. Reads link metadata from `/api/link/:token`, from `--upload-json`, or from `--meta`
+2. Downloads the encrypted file (unless you pass a local encrypted file)
+3. Decrypts locally and writes the original file to disk
+
 ## Development
 
 ```bash
-node bin/bytifi.js upload ./file.png --json
+node bin/bytifi.js upload ./file.png --json > upload.json
+node bin/bytifi.js decrypt ./file.encrypted --upload-json upload.json
 ```

package/bin/bytifi.js

@@ -4,18 +4,21 @@ import fs from 'node:fs/promises'
 import path from 'node:path'
 import process from 'node:process'
 import { createRequire } from 'node:module'
+import { decryptFile } from '../lib/decrypt.js'
 import { BytifiApiError, BytifiNetworkError, uploadFile } from '../lib/upload.js'
 
 const require = createRequire(import.meta.url)
 const { version } = require('../package.json')
 
 function printHelp() {
-  process.stdout.write(`Bytifi CLI v${version} — encrypt and upload files
+  process.stdout.write(`Bytifi CLI v${version} — encrypt, upload, and decrypt files
 
 Usage:
   bytifi upload <file> [options]
+  bytifi decrypt <url-or-token> [options]
+  bytifi decrypt <encrypted-file> [options]
 
-Options:
+Upload options:
   -k, --api-key <key>       API key (default: BYTIFI_API_KEY env var)
   -e, --expires <minutes>   Link lifetime: 5|15|30|60|120 (default: 30)
       --delete-on-download  Remove file after first download
@@ -24,6 +27,21 @@ Options:
       --verbose             Show API error details on stderr
       --mime-type <type>    Override detected MIME type
       --base-url <url>      API base URL (default: https://bytifi.com)
+
+Decrypt options:
+      --token <token>       Encryption key from #token=... (not the link ID)
+      --link <token>        Link ID from upload JSON "token" field (/f/TOKEN)
+      --upload-json <path>  Upload --json output (easiest for downloaded files)
+      --meta <path>         Saved clientEncryptionMeta JSON (offline decrypt)
+      --share-url <url>     Share URL for token/metadata when decrypting a local file
+  -o, --output <path>       Output file path (default: original filename)
+      --output-dir <dir>    Directory for decrypted file (default: cwd)
+      --json                Print machine-readable JSON to stdout
+  -q, --quiet               Print only the output file path
+      --verbose             Show error details on stderr
+      --base-url <url>      API base URL (default: https://bytifi.com)
+
+Global:
   -V, --version             Show version
   -h, --help                Show this help
 
@@ -35,7 +53,14 @@ Exit codes:
 
 Examples:
   bytifi upload ./photo.png
-  BYTIFI_API_KEY=usk_... bytifi upload report.pdf --expires 60 --json
+  bytifi upload ./video.mp4 --expires 60 --json > upload.json
+  bytifi upload ./large.iso -q
+
+  bytifi decrypt 'https://bytifi.com/link?link=abc#token=...'
+  bytifi decrypt abc --token 'ENCRYPTION_TOKEN' -o ./restored.mp4
+
+  bytifi decrypt ./downloaded.encrypted --upload-json upload.json
+  bytifi decrypt "./my file(1).mp4" --link abc --token 'ENCRYPTION_TOKEN'
 `)
 }
 
@@ -47,7 +72,7 @@ function readFlagValue(argv, index, flagName) {
   return value
 }
 
-function parseArgs(argv) {
+function parseUploadArgs(argv) {
   const positional = []
   const options = {
     apiKey: process.env.BYTIFI_API_KEY || '',
@@ -134,6 +159,110 @@ function parseArgs(argv) {
   return { positional, options }
 }
 
+function parseDecryptArgs(argv) {
+  const positional = []
+  const options = {
+    encryptionToken: '',
+    linkToken: '',
+    metaPath: '',
+    uploadJsonPath: '',
+    shareUrl: '',
+    output: '',
+    outputDirectory: '',
+    json: false,
+    quiet: false,
+    verbose: false,
+    baseUrl: 'https://bytifi.com',
+    help: false,
+    version: false,
+  }
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+
+    if (arg === '--help' || arg === '-h') {
+      options.help = true
+      continue
+    }
+
+    if (arg === '--version' || arg === '-V') {
+      options.version = true
+      continue
+    }
+
+    if (arg === '--json') {
+      options.json = true
+      continue
+    }
+
+    if (arg === '--quiet' || arg === '-q') {
+      options.quiet = true
+      continue
+    }
+
+    if (arg === '--verbose') {
+      options.verbose = true
+      continue
+    }
+
+    if (arg === '--token') {
+      options.encryptionToken = readFlagValue(argv, index, arg)
+      index += 1
+      continue
+    }
+
+    if (arg === '--link') {
+      options.linkToken = readFlagValue(argv, index, arg)
+      index += 1
+      continue
+    }
+
+    if (arg === '--meta') {
+      options.metaPath = readFlagValue(argv, index, arg)
+      index += 1
+      continue
+    }
+
+    if (arg === '--upload-json') {
+      options.uploadJsonPath = readFlagValue(argv, index, arg)
+      index += 1
+      continue
+    }
+
+    if (arg === '--share-url') {
+      options.shareUrl = readFlagValue(argv, index, arg)
+      index += 1
+      continue
+    }
+
+    if (arg === '--output' || arg === '-o') {
+      options.output = readFlagValue(argv, index, arg)
+      index += 1
+      continue
+    }
+
+    if (arg === '--output-dir') {
+      options.outputDirectory = readFlagValue(argv, index, arg)
+      index += 1
+      continue
+    }
+
+    if (arg === '--base-url') {
+      options.baseUrl = readFlagValue(argv, index, arg)
+      index += 1
+      continue
+    }
+
+    if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}`)
+    }
+
+    positional.push(arg)
+  }
+
+  return { positional, options }
+}
+
 function validateExpires(minutes) {
   const allowed = new Set([5, 15, 30, 60, 120])
   if (!allowed.has(minutes)) {
@@ -141,8 +270,8 @@ function validateExpires(minutes) {
   }
 }
 
-function writeProgress(percent) {
-  process.stderr.write(`\rEncrypting and uploading: ${percent}%`)
+function writeProgress(label, percent) {
+  process.stderr.write(`\r${label}: ${percent}%`)
 }
 
 function clearProgressLine() {
@@ -188,7 +317,7 @@ async function runUpload(filePath, options) {
         ? (percent) => {
             if (percent !== lastPercent) {
               lastPercent = percent
-              writeProgress(percent)
+              writeProgress('Encrypting and uploading', percent)
             }
           }
         : undefined,
@@ -209,7 +338,64 @@ async function runUpload(filePath, options) {
     }
 
     process.stdout.write(`Share URL:\n${result.shareUrl}\n`)
-    process.stdout.write(`Download URL:\n${result.downloadUrl}\n`)
+    process.stdout.write(`Encrypted file:\n${result.encryptedFile}\n`)
+    process.stdout.write(`Expires: ${result.expiresAt}\n`)
+  } finally {
+    process.off('SIGINT', handleSignal)
+    process.off('SIGTERM', handleSignal)
+  }
+}
+
+async function runDecrypt(input, options) {
+  const abortController = new AbortController()
+
+  const handleSignal = () => {
+    abortController.abort()
+  }
+
+  process.on('SIGINT', handleSignal)
+  process.on('SIGTERM', handleSignal)
+
+  const showProgress = !options.quiet && !options.json
+  let lastPercent = -1
+
+  try {
+    const result = await decryptFile(input, {
+      encryptionToken: options.encryptionToken,
+      linkToken: options.linkToken,
+      metaPath: options.metaPath,
+      uploadJsonPath: options.uploadJsonPath,
+      shareUrl: options.shareUrl,
+      output: options.output || undefined,
+      outputDirectory: options.outputDirectory || undefined,
+      baseUrl: options.baseUrl,
+      signal: abortController.signal,
+      onProgress: showProgress
+        ? (percent) => {
+            if (percent !== lastPercent) {
+              lastPercent = percent
+              writeProgress('Downloading and decrypting', percent)
+            }
+          }
+        : undefined,
+    })
+
+    if (showProgress) {
+      clearProgressLine()
+    }
+
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+      return
+    }
+
+    if (options.quiet) {
+      process.stdout.write(`${result.outputPath}\n`)
+      return
+    }
+
+    process.stdout.write(`Saved: ${result.outputPath}\n`)
+    process.stdout.write(`Original name: ${result.originalName}\n`)
     process.stdout.write(`Expires: ${result.expiresAt}\n`)
   } finally {
     process.off('SIGINT', handleSignal)
@@ -224,7 +410,7 @@ function exitCodeForError(error) {
 }
 
 function printError(error, verbose) {
-  process.stderr.write(`${error.message || 'Upload failed.'}\n`)
+  process.stderr.write(`${error.message || 'Command failed.'}\n`)
 
   if (!verbose) return
 
@@ -255,41 +441,74 @@ async function main() {
     process.exit(0)
   }
 
-  if (command !== 'upload') {
-    if (command === 'help') {
+  if (command === 'help') {
+    printHelp()
+    process.exit(0)
+  }
+
+  if (command === 'upload') {
+    const { positional, options } = parseUploadArgs(rest)
+
+    if (options.help) {
       printHelp()
       process.exit(0)
     }
 
-    throw new Error(`Unknown command: ${command}`)
-  }
+    if (options.version) {
+      process.stdout.write(`${version}\n`)
+      process.exit(0)
+    }
 
-  const { positional, options } = parseArgs(rest)
+    if (options.json && options.quiet) {
+      throw new Error('Use either --json or --quiet, not both.')
+    }
 
-  if (options.help) {
-    printHelp()
-    process.exit(0)
-  }
+    const filePath = positional[0]
+    if (!filePath) {
+      throw new Error('Missing file path. Usage: bytifi upload <file>')
+    }
 
-  if (options.version) {
-    process.stdout.write(`${version}\n`)
-    process.exit(0)
-  }
+    if (positional.length > 1) {
+      throw new Error(
+        `Upload accepts one file at a time (got ${positional.length}). Quote paths with spaces and avoid shell globs like **.`,
+      )
+    }
 
-  if (options.json && options.quiet) {
-    throw new Error('Use either --json or --quiet, not both.')
+    await runUpload(filePath, options)
+    return
   }
 
-  const filePath = positional[0]
-  if (!filePath) {
-    throw new Error('Missing file path. Usage: bytifi upload <file>')
-  }
+  if (command === 'decrypt') {
+    const { positional, options } = parseDecryptArgs(rest)
+
+    if (options.help) {
+      printHelp()
+      process.exit(0)
+    }
+
+    if (options.version) {
+      process.stdout.write(`${version}\n`)
+      process.exit(0)
+    }
+
+    if (options.json && options.quiet) {
+      throw new Error('Use either --json or --quiet, not both.')
+    }
+
+    const input = positional[0]
+    if (!input) {
+      throw new Error('Missing input. Usage: bytifi decrypt <url-or-token|encrypted-file>')
+    }
+
+    if (positional.length > 1) {
+      process.stderr.write(`Warning: ignoring extra arguments: ${positional.slice(1).join(', ')}\n`)
+    }
 
-  if (positional.length > 1) {
-    process.stderr.write(`Warning: ignoring extra files: ${positional.slice(1).join(', ')}\n`)
+    await runDecrypt(input, options)
+    return
   }
 
-  await runUpload(filePath, options)
+  throw new Error(`Unknown command: ${command}`)
 }
 
 main().catch((error) => {

package/lib/crypto.js

@@ -200,6 +200,49 @@ export function importToken(token) {
   return tokenBytes
 }
 
+export function normalizeClientEncryptionMeta(rawMeta) {
+  if (!rawMeta || typeof rawMeta !== 'object') return null
+
+  const chunkSize = Number(rawMeta.chunkSize)
+  const chunkCount = Number(rawMeta.chunkCount)
+  const originalSize = Number(rawMeta.originalSize)
+
+  if (!Number.isFinite(chunkSize) || chunkSize <= 0) return null
+  if (!Number.isFinite(chunkCount) || chunkCount <= 0) return null
+  if (!Number.isFinite(originalSize) || originalSize < 0) return null
+  if (typeof rawMeta.noncePrefix !== 'string' || !rawMeta.noncePrefix) return null
+
+  return {
+    version: Number(rawMeta.version) || 1,
+    algorithm: String(rawMeta.algorithm || 'AES-GCM'),
+    chunkSize,
+    chunkCount,
+    noncePrefix: rawMeta.noncePrefix,
+    originalSize,
+    mimeType: String(rawMeta.mimeType || 'application/octet-stream'),
+  }
+}
+
+export function buildEncryptedChunkPlan(meta) {
+  const chunks = []
+  let offset = 0
+
+  for (let chunkIndex = 0; chunkIndex < meta.chunkCount; chunkIndex += 1) {
+    const start = chunkIndex * meta.chunkSize
+    const plainSize = Math.min(meta.originalSize - start, meta.chunkSize)
+    const encryptedSize = plainSize + 16
+
+    chunks.push({ chunkIndex, encryptedSize, plainSize })
+    offset += encryptedSize
+  }
+
+  return {
+    chunks,
+    totalEncryptedSize: offset,
+    totalPlainSize: meta.originalSize,
+  }
+}
+
 function guessMimeType(filename) {
   const ext = path.extname(filename).toLowerCase()
   const map = {

package/lib/decrypt.js

@@ -0,0 +1,765 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import process from 'node:process'
+import {
+  buildEncryptedChunkPlan,
+  decryptChunk,
+  importToken,
+  normalizeClientEncryptionMeta,
+} from './crypto.js'
+import { fromBase64Url } from './base64url.js'
+import { BytifiApiError, BytifiNetworkError } from './upload.js'
+
+const DEFAULT_BASE_URL = 'https://bytifi.com'
+
+function normalizeBaseUrl(baseUrl) {
+  return String(baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '')
+}
+
+async function readResponseBody(response) {
+  const text = await response.text()
+  if (!text) return null
+
+  try {
+    return JSON.parse(text)
+  } catch {
+    return text
+  }
+}
+
+async function publicFetch(baseUrl, requestPath, { signal } = {}) {
+  const url = `${normalizeBaseUrl(baseUrl)}${requestPath}`
+
+  let response
+
+  try {
+    response = await fetch(url, { signal })
+  } catch (error) {
+    if (signal?.aborted) {
+      throw new Error('Decrypt aborted.')
+    }
+    throw new BytifiNetworkError(error.message || 'Network request failed.', { cause: error })
+  }
+
+  const payload = await readResponseBody(response)
+
+  if (!response.ok) {
+    const message = typeof payload === 'object' && payload?.error
+      ? payload.error
+      : typeof payload === 'string' && payload
+        ? payload
+        : `Request failed with status ${response.status}.`
+    throw new BytifiApiError(message, { status: response.status, body: payload })
+  }
+
+  return payload
+}
+
+export function parseDecryptInput(input, { encryptionToken = '', baseUrl = DEFAULT_BASE_URL } = {}) {
+  const trimmed = String(input || '').trim()
+  if (!trimmed) {
+    throw new Error('Missing share URL or link token.')
+  }
+
+  let resolvedBaseUrl = normalizeBaseUrl(baseUrl)
+  let linkToken = ''
+  let resolvedEncryptionToken = String(encryptionToken || '').trim()
+
+  if (/^https?:\/\//i.test(trimmed) || trimmed.startsWith('/')) {
+    const url = new URL(trimmed, `${resolvedBaseUrl}/`)
+
+    if (url.origin !== 'null:') {
+      resolvedBaseUrl = `${url.protocol}//${url.host}`
+    }
+
+    const hashParams = new URLSearchParams(url.hash.startsWith('#') ? url.hash.slice(1) : url.hash)
+    if (!resolvedEncryptionToken) {
+      resolvedEncryptionToken = hashParams.get('token') || ''
+    }
+
+    linkToken = url.searchParams.get('link') || ''
+
+    if (!linkToken) {
+      const fileMatch = url.pathname.match(/^\/f\/([^/]+)/)
+      linkToken = fileMatch?.[1] || ''
+    }
+  } else {
+    linkToken = trimmed
+  }
+
+  if (!linkToken) {
+    throw new Error('Could not find a link token in the input URL.')
+  }
+
+  if (!resolvedEncryptionToken) {
+    throw new Error(
+      'Missing encryption token. Pass --token with the `#token=...` value from the share URL '
+      + '(stored as `encryptionToken` in upload JSON). This is not the same as the link ID.',
+    )
+  }
+
+  return {
+    baseUrl: resolvedBaseUrl,
+    linkToken,
+    encryptionToken: resolvedEncryptionToken,
+  }
+}
+
+export function parseShareReference(input, { encryptionToken = '', baseUrl = DEFAULT_BASE_URL } = {}) {
+  const trimmed = String(input || '').trim()
+  if (!trimmed) {
+    return {
+      baseUrl: normalizeBaseUrl(baseUrl),
+      linkToken: '',
+      encryptionToken: String(encryptionToken || '').trim(),
+    }
+  }
+
+  if (!/^https?:\/\//i.test(trimmed) && !trimmed.startsWith('/')) {
+    return {
+      baseUrl: normalizeBaseUrl(baseUrl),
+      linkToken: trimmed,
+      encryptionToken: String(encryptionToken || '').trim(),
+    }
+  }
+
+  const url = new URL(trimmed, `${normalizeBaseUrl(baseUrl)}/`)
+  const hashParams = new URLSearchParams(url.hash.startsWith('#') ? url.hash.slice(1) : url.hash)
+
+  return {
+    baseUrl: `${url.protocol}//${url.host}`,
+    linkToken: url.searchParams.get('link') || url.pathname.match(/^\/f\/([^/]+)/)?.[1] || '',
+    encryptionToken: String(encryptionToken || hashParams.get('token') || '').trim(),
+  }
+}
+
+function looksLikeRemoteInput(input) {
+  const trimmed = String(input || '').trim()
+  return /^https?:\/\//i.test(trimmed)
+    || trimmed.startsWith('/link')
+    || trimmed.startsWith('/f/')
+}
+
+async function pathExists(inputPath) {
+  try {
+    await fs.access(path.resolve(inputPath))
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function readMetaFile(metaPath) {
+  const raw = await fs.readFile(path.resolve(metaPath), 'utf8')
+  const parsed = JSON.parse(raw)
+  const meta = normalizeClientEncryptionMeta(parsed?.clientEncryptionMeta || parsed)
+
+  if (!meta) {
+    throw new Error('Invalid encryption metadata file.')
+  }
+
+  return meta
+}
+
+async function resolveEncryptionMeta({
+  metaPath = '',
+  inlineMeta = null,
+  linkToken = '',
+  baseUrl = DEFAULT_BASE_URL,
+  signal,
+}) {
+  if (inlineMeta) {
+    return { meta: inlineMeta }
+  }
+
+  if (metaPath) {
+    return { meta: await readMetaFile(metaPath) }
+  }
+
+  if (!linkToken) {
+    throw new Error(
+      'Missing link metadata for a downloaded file. Pass --upload-json upload.json, --link LINK_ID, or --meta meta.json.\n'
+      + 'The link ID is the `token` field in upload JSON (also appears as /f/TOKEN and link?link=TOKEN).',
+    )
+  }
+
+  const linkInfo = await fetchLinkInfo(baseUrl, linkToken, signal)
+
+  if (linkInfo.status === 'expired') {
+    throw new Error('This file link has expired.')
+  }
+
+  if (!linkInfo.clientEncrypted) {
+    throw new Error('This link is not an encrypted file.')
+  }
+
+  const meta = normalizeClientEncryptionMeta(linkInfo.clientEncryptionMeta)
+  if (!meta) {
+    throw new Error('Invalid encryption metadata for this file.')
+  }
+
+  return { meta, linkInfo }
+}
+
+function sanitizeOutputName(filename) {
+  const base = path.basename(String(filename || 'download').replace(/[\0\r\n]/g, ''))
+  return base || 'download'
+}
+
+async function fetchLinkInfo(baseUrl, linkToken, signal) {
+  return publicFetch(baseUrl, `/api/link/${encodeURIComponent(linkToken)}`, { signal })
+}
+
+async function fetchEncryptedPart(baseUrl, linkToken, partNumber, signal) {
+  const response = await fetch(
+    `${normalizeBaseUrl(baseUrl)}/f/${encodeURIComponent(linkToken)}/p/${partNumber}`,
+    { signal },
+  )
+
+  if (!response.ok) {
+    const text = await response.text()
+    throw new BytifiApiError(text || `Failed to download part ${partNumber}.`, {
+      status: response.status,
+      body: text,
+    })
+  }
+
+  return Buffer.from(await response.arrayBuffer())
+}
+
+async function decryptFromParts({
+  baseUrl,
+  linkToken,
+  meta,
+  tokenBytes,
+  noncePrefix,
+  outputPath,
+  onProgress,
+  signal,
+}) {
+  const { chunks } = buildEncryptedChunkPlan(meta)
+  const fileHandle = await fs.open(outputPath, 'w')
+  let decryptedBytes = 0
+
+  try {
+    for (let index = 0; index < chunks.length; index += 1) {
+      if (signal?.aborted) {
+        throw new Error('Decrypt aborted.')
+      }
+
+      const chunk = chunks[index]
+      const encryptedPart = await fetchEncryptedPart(baseUrl, linkToken, chunk.chunkIndex + 1, signal)
+      const plainPart = decryptChunk(encryptedPart, tokenBytes, noncePrefix, chunk.chunkIndex)
+
+      await fileHandle.write(plainPart)
+      decryptedBytes += plainPart.length
+      onProgress?.(Math.round((decryptedBytes / meta.originalSize) * 100))
+    }
+  } finally {
+    await fileHandle.close()
+  }
+}
+
+async function decryptFromSingleFile({
+  encryptedFileUrl,
+  meta,
+  tokenBytes,
+  noncePrefix,
+  outputPath,
+  onProgress,
+  signal,
+}) {
+  const { chunks, totalEncryptedSize } = buildEncryptedChunkPlan(meta)
+  const response = await fetch(encryptedFileUrl, { signal })
+
+  if (!response.ok) {
+    const text = await response.text()
+    throw new BytifiApiError(text || 'Failed to download encrypted file.', {
+      status: response.status,
+      body: text,
+    })
+  }
+
+  if (!response.body) {
+    const encryptedBuffer = Buffer.from(await response.arrayBuffer())
+    await writeDecryptedBuffer(encryptedBuffer, chunks, meta, tokenBytes, noncePrefix, outputPath, onProgress, signal)
+    return
+  }
+
+  const reader = response.body.getReader()
+  const fileHandle = await fs.open(outputPath, 'w')
+  const pending = []
+  let pendingLength = 0
+  let downloadedBytes = 0
+  let nextChunkIndex = 0
+  let decryptedBytes = 0
+
+  const takeBytes = (length) => {
+    while (pendingLength < length) {
+      return null
+    }
+
+    const out = Buffer.alloc(length)
+    let offset = 0
+
+    while (offset < length) {
+      const head = pending[0]
+      const take = Math.min(length - offset, head.length)
+      head.copy(out, offset, 0, take)
+      offset += take
+
+      if (take === head.length) {
+        pending.shift()
+      } else {
+        pending[0] = head.subarray(take)
+      }
+      pendingLength -= take
+    }
+
+    return out
+  }
+
+  try {
+    while (nextChunkIndex < chunks.length) {
+      if (signal?.aborted) {
+        throw new Error('Decrypt aborted.')
+      }
+
+      const chunk = chunks[nextChunkIndex]
+
+      while (pendingLength < chunk.encryptedSize) {
+        const { done, value } = await reader.read()
+        if (done) break
+        const buffer = Buffer.from(value)
+        pending.push(buffer)
+        pendingLength += buffer.length
+        downloadedBytes += buffer.length
+        onProgress?.(Math.min(99, Math.round((downloadedBytes / totalEncryptedSize) * 100)))
+      }
+
+      const encryptedChunk = takeBytes(chunk.encryptedSize)
+      if (!encryptedChunk) {
+        throw new Error('Encrypted file ended before all parts were downloaded.')
+      }
+
+      const plainPart = decryptChunk(encryptedChunk, tokenBytes, noncePrefix, chunk.chunkIndex)
+      await fileHandle.write(plainPart)
+      decryptedBytes += plainPart.length
+      nextChunkIndex += 1
+      onProgress?.(Math.min(99, Math.round((decryptedBytes / meta.originalSize) * 100)))
+    }
+  } finally {
+    await reader.cancel().catch(() => {})
+    await fileHandle.close()
+  }
+
+  onProgress?.(100)
+}
+
+async function writeDecryptedBuffer(encryptedBuffer, chunks, meta, tokenBytes, noncePrefix, outputPath, onProgress, signal) {
+  const fileHandle = await fs.open(outputPath, 'w')
+  let offset = 0
+  let decryptedBytes = 0
+
+  try {
+    for (const chunk of chunks) {
+      if (signal?.aborted) {
+        throw new Error('Decrypt aborted.')
+      }
+
+      const encryptedChunk = encryptedBuffer.subarray(offset, offset + chunk.encryptedSize)
+      if (encryptedChunk.length !== chunk.encryptedSize) {
+        throw new Error('Encrypted file ended before all parts were downloaded.')
+      }
+
+      const plainPart = decryptChunk(encryptedChunk, tokenBytes, noncePrefix, chunk.chunkIndex)
+      await fileHandle.write(plainPart)
+      offset += chunk.encryptedSize
+      decryptedBytes += plainPart.length
+      onProgress?.(Math.round((decryptedBytes / meta.originalSize) * 100))
+    }
+  } finally {
+    await fileHandle.close()
+  }
+
+  onProgress?.(100)
+}
+
+async function decryptFromLocalSingleFile({
+  encryptedFilePath,
+  meta,
+  tokenBytes,
+  noncePrefix,
+  outputPath,
+  onProgress,
+  signal,
+}) {
+  const { chunks } = buildEncryptedChunkPlan(meta)
+  const stat = await fs.stat(encryptedFilePath)
+
+  if (stat.size <= 64 * 1024 * 1024) {
+    const encryptedBuffer = await fs.readFile(encryptedFilePath)
+    await writeDecryptedBuffer(encryptedBuffer, chunks, meta, tokenBytes, noncePrefix, outputPath, onProgress, signal)
+    return
+  }
+
+  const fileHandle = await fs.open(encryptedFilePath, 'r')
+  const outputHandle = await fs.open(outputPath, 'w')
+  let offset = 0
+  let decryptedBytes = 0
+
+  try {
+    for (const chunk of chunks) {
+      if (signal?.aborted) {
+        throw new Error('Decrypt aborted.')
+      }
+
+      const encryptedChunk = Buffer.alloc(chunk.encryptedSize)
+      const { bytesRead } = await fileHandle.read(encryptedChunk, 0, chunk.encryptedSize, offset)
+
+      if (bytesRead !== chunk.encryptedSize) {
+        throw new Error('Encrypted file ended before all parts were read.')
+      }
+
+      const plainPart = decryptChunk(encryptedChunk, tokenBytes, noncePrefix, chunk.chunkIndex)
+      await outputHandle.write(plainPart)
+      offset += chunk.encryptedSize
+      decryptedBytes += plainPart.length
+      onProgress?.(Math.round((decryptedBytes / meta.originalSize) * 100))
+    }
+  } finally {
+    await fileHandle.close()
+    await outputHandle.close()
+  }
+
+  onProgress?.(100)
+}
+
+async function listLocalPartFiles(dirPath) {
+  const entries = await fs.readdir(dirPath)
+  const parts = entries
+    .map((name) => {
+      const match = name.match(/^(\d+)(?:\.part)?$/)
+      return match ? { partNumber: Number(match[1]), name } : null
+    })
+    .filter(Boolean)
+    .sort((left, right) => left.partNumber - right.partNumber)
+
+  if (parts.length === 0) {
+    throw new Error('No numbered part files found in directory. Expected names like 1, 2, or 1.part, 2.part.')
+  }
+
+  return parts
+}
+
+async function decryptFromLocalParts({
+  partsDirectory,
+  meta,
+  tokenBytes,
+  noncePrefix,
+  outputPath,
+  onProgress,
+  signal,
+}) {
+  const { chunks } = buildEncryptedChunkPlan(meta)
+  const parts = await listLocalPartFiles(partsDirectory)
+
+  if (parts.length !== chunks.length) {
+    throw new Error(`Expected ${chunks.length} part files, found ${parts.length}.`)
+  }
+
+  const fileHandle = await fs.open(outputPath, 'w')
+  let decryptedBytes = 0
+
+  try {
+    for (const chunk of chunks) {
+      if (signal?.aborted) {
+        throw new Error('Decrypt aborted.')
+      }
+
+      const partNumber = chunk.chunkIndex + 1
+      const partEntry = parts[chunk.chunkIndex]
+
+      if (!partEntry || partEntry.partNumber !== partNumber) {
+        throw new Error(`Missing local part file ${partNumber}.`)
+      }
+
+      const encryptedPart = await fs.readFile(path.join(partsDirectory, partEntry.name))
+      const plainPart = decryptChunk(encryptedPart, tokenBytes, noncePrefix, chunk.chunkIndex)
+
+      await fileHandle.write(plainPart)
+      decryptedBytes += plainPart.length
+      onProgress?.(Math.round((decryptedBytes / meta.originalSize) * 100))
+    }
+  } finally {
+    await fileHandle.close()
+  }
+
+  onProgress?.(100)
+}
+
+function hintTokenConfusion(encryptionToken, linkToken) {
+  const token = String(encryptionToken || '').trim()
+
+  if (!token || linkToken) return
+
+  if (token.length <= 20) {
+    throw new Error(
+      `"${token}" looks like a link ID, not an encryption token.\n`
+      + 'Use --link for the link ID (`token` in upload JSON) and --token for the encryption key (`encryptionToken`).\n'
+      + 'Easiest: bytifi decrypt ./file.encrypted --upload-json upload.json',
+    )
+  }
+}
+
+export async function loadUploadJson(uploadJsonPath) {
+  const raw = await fs.readFile(path.resolve(uploadJsonPath), 'utf8')
+  let parsed
+
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new Error('Invalid upload JSON file.')
+  }
+
+  const meta = normalizeClientEncryptionMeta(parsed.clientEncryptionMeta)
+  if (!meta) {
+    throw new Error('Upload JSON is missing clientEncryptionMeta.')
+  }
+
+  const encryptionToken = String(parsed.encryptionToken || '').trim()
+  if (!encryptionToken) {
+    throw new Error('Upload JSON is missing encryptionToken.')
+  }
+
+  return {
+    linkToken: String(parsed.token || '').trim(),
+    encryptionToken,
+    meta,
+    originalName: parsed.originalName || 'download',
+    shareUrl: parsed.shareUrl || '',
+    expiresAt: parsed.expiresAt || null,
+  }
+}
+
+async function applyUploadJsonDefaults(options) {
+  if (!options.uploadJsonPath) {
+    return options
+  }
+
+  const upload = await loadUploadJson(options.uploadJsonPath)
+
+  return {
+    ...options,
+    linkToken: options.linkToken || upload.linkToken,
+    encryptionToken: options.encryptionToken || upload.encryptionToken,
+    inlineMeta: options.inlineMeta || upload.meta,
+    originalName: options.originalName || upload.originalName,
+    shareUrl: options.shareUrl || upload.shareUrl,
+    uploadExpiresAt: upload.expiresAt,
+  }
+}
+
+function resolveEncryptionToken(encryptionToken, shareReference, linkToken = '') {
+  const resolved = String(encryptionToken || shareReference?.encryptionToken || '').trim()
+
+  hintTokenConfusion(resolved, linkToken)
+
+  if (!resolved) {
+    throw new Error(
+      'Missing encryption token. Pass --token with the `#token=...` value from the share URL '
+      + '(stored as `encryptionToken` in upload JSON), or use --upload-json upload.json.',
+    )
+  }
+
+  return resolved
+}
+
+function buildDecryptResult({
+  outputPath,
+  originalName,
+  size,
+  mimeType,
+  expiresAt = null,
+  linkToken = '',
+  storageMode = 'single',
+  sourcePath = '',
+}) {
+  return {
+    outputPath,
+    originalName,
+    size,
+    mimeType,
+    expiresAt,
+    linkToken,
+    storageMode,
+    sourcePath,
+  }
+}
+
+async function decryptLocalFile(inputPath, options = {}) {
+  const resolvedOptions = await applyUploadJsonDefaults(options)
+  const absolutePath = path.resolve(inputPath)
+  const stat = await fs.stat(absolutePath)
+  const shareReference = parseShareReference(resolvedOptions.shareUrl || '', {
+    encryptionToken: resolvedOptions.encryptionToken,
+    baseUrl: resolvedOptions.baseUrl,
+  })
+  const linkToken = resolvedOptions.linkToken || shareReference.linkToken
+
+  if (
+    !resolvedOptions.uploadJsonPath
+    && !resolvedOptions.metaPath
+    && !resolvedOptions.inlineMeta
+    && !linkToken
+  ) {
+    hintTokenConfusion(resolvedOptions.encryptionToken, '')
+  }
+
+  const resolved = await resolveEncryptionMeta({
+    metaPath: resolvedOptions.metaPath,
+    inlineMeta: resolvedOptions.inlineMeta,
+    linkToken,
+    baseUrl: resolvedOptions.baseUrl || shareReference.baseUrl,
+    signal: resolvedOptions.signal,
+  })
+  const meta = resolved.meta || resolved
+  const linkInfo = resolved.linkInfo || null
+  const encryptionToken = resolveEncryptionToken(
+    resolvedOptions.encryptionToken,
+    shareReference,
+    linkToken,
+  )
+  const tokenBytes = importToken(encryptionToken)
+  const noncePrefix = fromBase64Url(meta.noncePrefix)
+  const originalName = linkInfo?.originalName || resolvedOptions.originalName || 'download'
+  const outputName = sanitizeOutputName(resolvedOptions.output ? path.basename(resolvedOptions.output) : originalName)
+  const outputPath = path.resolve(
+    resolvedOptions.output || path.join(resolvedOptions.outputDirectory || process.cwd(), outputName),
+  )
+
+  await fs.mkdir(path.dirname(outputPath), { recursive: true })
+
+  if (stat.isDirectory()) {
+    await decryptFromLocalParts({
+      partsDirectory: absolutePath,
+      meta,
+      tokenBytes,
+      noncePrefix,
+      outputPath,
+      onProgress: resolvedOptions.onProgress,
+      signal: resolvedOptions.signal,
+    })
+
+    return buildDecryptResult({
+      outputPath,
+      originalName,
+      size: meta.originalSize,
+      mimeType: meta.mimeType,
+      expiresAt: linkInfo?.expiresAt || resolvedOptions.uploadExpiresAt || null,
+      linkToken,
+      storageMode: 'parts',
+      sourcePath: absolutePath,
+    })
+  }
+
+  await decryptFromLocalSingleFile({
+    encryptedFilePath: absolutePath,
+    meta,
+    tokenBytes,
+    noncePrefix,
+    outputPath,
+    onProgress: resolvedOptions.onProgress,
+    signal: resolvedOptions.signal,
+  })
+
+  return buildDecryptResult({
+    outputPath,
+    originalName,
+    size: meta.originalSize,
+    mimeType: meta.mimeType,
+    expiresAt: linkInfo?.expiresAt || resolvedOptions.uploadExpiresAt || null,
+    linkToken,
+    storageMode: 'single',
+    sourcePath: absolutePath,
+  })
+}
+
+export async function decryptFile(input, options = {}) {
+  const resolvedOptions = await applyUploadJsonDefaults(options)
+  const trimmedInput = String(input || '').trim()
+  if (!trimmedInput) {
+    throw new Error('Missing share URL, link token, or encrypted file path.')
+  }
+
+  if (resolvedOptions.localFile || (!looksLikeRemoteInput(trimmedInput) && await pathExists(trimmedInput))) {
+    return decryptLocalFile(trimmedInput, resolvedOptions)
+  }
+
+  const parsed = parseDecryptInput(trimmedInput, {
+    encryptionToken: resolvedOptions.encryptionToken,
+    baseUrl: resolvedOptions.baseUrl,
+  })
+
+  const linkInfo = await fetchLinkInfo(parsed.baseUrl, parsed.linkToken, resolvedOptions.signal)
+
+  if (linkInfo.status === 'expired') {
+    throw new Error('This file link has expired.')
+  }
+
+  if (!linkInfo.clientEncrypted) {
+    throw new Error('This link is not an encrypted file.')
+  }
+
+  const meta = normalizeClientEncryptionMeta(linkInfo.clientEncryptionMeta)
+  if (!meta) {
+    throw new Error('Invalid encryption metadata for this file.')
+  }
+
+  const tokenBytes = importToken(parsed.encryptionToken)
+  const noncePrefix = fromBase64Url(meta.noncePrefix)
+  const outputName = sanitizeOutputName(
+    resolvedOptions.output ? path.basename(resolvedOptions.output) : linkInfo.originalName,
+  )
+  const outputPath = path.resolve(
+    resolvedOptions.output || path.join(resolvedOptions.outputDirectory || process.cwd(), outputName),
+  )
+
+  await fs.mkdir(path.dirname(outputPath), { recursive: true })
+
+  if (linkInfo.storageMode === 'parts') {
+    await decryptFromParts({
+      baseUrl: parsed.baseUrl,
+      linkToken: parsed.linkToken,
+      meta,
+      tokenBytes,
+      noncePrefix,
+      outputPath,
+      onProgress: resolvedOptions.onProgress,
+      signal: resolvedOptions.signal,
+    })
+  } else {
+    const encryptedFileUrl = linkInfo.downloadUrl
+      || `${parsed.baseUrl}/f/${encodeURIComponent(parsed.linkToken)}`
+
+    await decryptFromSingleFile({
+      encryptedFileUrl,
+      meta,
+      tokenBytes,
+      noncePrefix,
+      outputPath,
+      onProgress: resolvedOptions.onProgress,
+      signal: resolvedOptions.signal,
+    })
+  }
+
+  return buildDecryptResult({
+    outputPath,
+    originalName: linkInfo.originalName,
+    size: linkInfo.size,
+    mimeType: linkInfo.mimeType,
+    expiresAt: linkInfo.expiresAt,
+    linkToken: parsed.linkToken,
+    storageMode: linkInfo.storageMode || 'single',
+  })
+}

package/lib/upload.js

@@ -123,9 +123,10 @@ function buildResult(payload, context, shareUrl) {
   return {
     shareUrl,
     url: payload.url,
-    downloadUrl: payload.downloadUrl,
+    encryptedFile: payload.downloadUrl,
     token: payload.token,
     encryptionToken: context.token,
+    clientEncryptionMeta: context.meta,
     originalName: payload.originalName || context.originalName,
     size: payload.size,
     expiresAt: payload.expiresAt,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bytifi",
-  "version": "0.1.2",
-  "description": "Official Bytifi CLI — encrypt and upload files from the terminal",
+  "version": "0.1.4",
+  "description": "Official Bytifi CLI — encrypt, upload, and decrypt files from the terminal",
   "type": "module",
   "bin": {
     "bytifi": "./bin/bytifi.js"
@@ -15,6 +15,7 @@
   },
   "scripts": {
     "upload": "node bin/bytifi.js upload",
+    "decrypt": "node bin/bytifi.js decrypt",
     "build:bundle": "esbuild bin/bytifi.js --bundle --platform=node --format=cjs --outfile=dist/bytifi-bundle.cjs",
     "build:win": "npm run build:bundle && pkg dist/bytifi-bundle.cjs --targets node22-win-x64 --output dist/bytifi.exe --compress GZip"
   },