bytifi 0.1.3 → 0.1.5

package/README.md

@@ -53,45 +53,57 @@ Prefer the environment variable — keys on the command line can appear in shell
 
 ```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
 ```
 
-### Decrypt
+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.
 
-Download and decrypt a shared file locally, or decrypt a file you already downloaded from `/f/...`. No API key required.
+### 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
-# From share URL (downloads + decrypts)
-bytifi decrypt 'https://bytifi.com/link?link=TOKEN#token=ENCRYPTION_TOKEN'
-bytifi decrypt TOKEN --token ENCRYPTION_TOKEN -o ./restored-file.pdf
-
-# From a downloaded encrypted file
-bytifi decrypt ./downloaded.encrypted --link TOKEN --token ENCRYPTION_TOKEN
-bytifi decrypt ./downloaded.encrypted --meta ./upload-meta.json --token ENCRYPTION_TOKEN
-bytifi decrypt ./parts/ --link TOKEN --token ENCRYPTION_TOKEN
+# 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
 ```
 
-Use the full share URL (with `#token=...`) when possible. For `/f/...` downloads, pass the encryption token with `--token` and either `--link` (fetches metadata from the API) or `--meta` (saved `clientEncryptionMeta` JSON from upload `--json` output).
+#### Link ID vs encryption token
+
+Bytifi uses two different values — don't swap them:
+
+| Name | Upload JSON field | Example location |
+|------|-------------------|------------------|
+| **Link ID** | `link` | `/f/QeVuslvdaP-okMxG`, `link?link=QeVuslvdaP-okMxG` |
+| **Encryption token** | `encryptionToken` | `#token=2LTlmBrDkO4GJg0...` in `shareUrl` |
 
-#### Offline decrypt workflow
+- `--link` = link ID (short, ~16 chars)
+- `--token` = encryption key (long, ~43 chars)
 
-Save metadata when you upload, so you can decrypt a downloaded `/f/...` file even after the link expires:
+### Offline decrypt workflow
+
+Save metadata when you upload, so you can decrypt after the link expires:
 
 ```bash
-# 1. Upload and save the JSON output
 bytifi upload ./report.pdf --json > upload.json
-
-# 2. Download the encrypted file manually (browser, curl, etc.)
 curl -L "$(jq -r .encryptedFile upload.json)" -o report.encrypted
-
-# 3. Save metadata and decrypt locally (no API call needed)
-jq -c .clientEncryptionMeta upload.json > report.meta.json
-bytifi decrypt ./report.encrypted \
-  --meta ./report.meta.json \
-  --token "$(jq -r .encryptionToken upload.json)" \
-  -o ./report.pdf
+bytifi decrypt ./report.encrypted --upload-json upload.json -o ./report.pdf
 ```
 
 Without a global install:
@@ -120,9 +132,10 @@ Note: with `npm exec`, put `--` before the file path so npm does not swallow `--
 
 | Flag | Description |
 |------|-------------|
-| `--token` | Encryption token (required if not in URL `#token=...`) |
-| `--link` | Link token for metadata when decrypting a local encrypted file |
-| `--meta` | Saved `clientEncryptionMeta` JSON for offline local decrypt |
+| `--token` | Encryption key from `#token=...` (`encryptionToken` in upload JSON) |
+| `--link` | Link ID from upload JSON `link` field (`/f/LINK_ID`) |
+| `--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 |
@@ -133,9 +146,9 @@ Note: with `npm exec`, put `--` before the file path so npm does not swallow `--
 
 Exit codes: `0` success, `1` usage error, `2` API error, `3` network error.
 
-JSON output (`--json`) for upload includes `shareUrl`, `encryptedFile`, `encryptionToken`, `clientEncryptionMeta`, `expiresAt`, and `token`.
+JSON output (`--json`) for upload includes `shareUrl`, `encryptedFile`, `link`, `encryptionToken`, `clientEncryptionMeta`, and `expiresAt`.
 
-JSON output for decrypt includes `outputPath`, `originalName`, `size`, `mimeType`, `expiresAt`, `linkToken`, `storageMode`, and `sourcePath` (for local decrypt).
+JSON output for decrypt includes `outputPath`, `originalName`, `size`, `mimeType`, `expiresAt`, `link`, `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.
 
@@ -149,13 +162,13 @@ Files over ~100 MB encrypted use multipart upload automatically. Progress prints
 
 **Decrypt**
 
-1. Reads link metadata from `/api/link/:token`, or from a saved `--meta` JSON file
-2. Downloads the encrypted file (single blob or per-part for large uploads), unless you pass a local encrypted file
+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 decrypt ./file.encrypted --meta ./meta.json --token '...'
+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

@@ -29,9 +29,10 @@ Upload options:
       --base-url <url>      API base URL (default: https://bytifi.com)
 
 Decrypt options:
-      --token <token>       Encryption token (if not in URL #token=...)
-      --link <token>        Link token for metadata (local encrypted files)
-      --meta <path>         Saved clientEncryptionMeta JSON (offline local decrypt)
+      --token <token>       Encryption key from #token=... (not the link ID)
+      --link <id>           Link ID from upload JSON "link" field (/f/LINK_ID)
+      --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)
@@ -52,12 +53,14 @@ Exit codes:
 
 Examples:
   bytifi upload ./photo.png
-  BYTIFI_API_KEY=usk_... bytifi upload report.pdf --expires 60 --json
-  bytifi decrypt 'https://bytifi.com/link?link=abc123#token=...'
-  bytifi decrypt abc123 --token '...' -o ./report.pdf
-  bytifi decrypt ./downloaded.encrypted --link abc123 --token '...'
-  bytifi decrypt ./downloaded.encrypted --meta ./upload-meta.json --token '...'
-  bytifi decrypt ./parts/ --link abc123 --token '...'
+  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'
 `)
 }
 
@@ -162,6 +165,7 @@ function parseDecryptArgs(argv) {
     encryptionToken: '',
     linkToken: '',
     metaPath: '',
+    uploadJsonPath: '',
     shareUrl: '',
     output: '',
     outputDirectory: '',
@@ -219,6 +223,12 @@ function parseDecryptArgs(argv) {
       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
@@ -354,6 +364,7 @@ async function runDecrypt(input, options) {
       encryptionToken: options.encryptionToken,
       linkToken: options.linkToken,
       metaPath: options.metaPath,
+      uploadJsonPath: options.uploadJsonPath,
       shareUrl: options.shareUrl,
       output: options.output || undefined,
       outputDirectory: options.outputDirectory || undefined,
@@ -458,7 +469,9 @@ async function main() {
     }
 
     if (positional.length > 1) {
-      process.stderr.write(`Warning: ignoring extra files: ${positional.slice(1).join(', ')}\n`)
+      throw new Error(
+        `Upload accepts one file at a time (got ${positional.length}). Quote paths with spaces and avoid shell globs like **.`,
+      )
     }
 
     await runUpload(filePath, options)

package/lib/decrypt.js

@@ -92,7 +92,10 @@ export function parseDecryptInput(input, { encryptionToken = '', baseUrl = DEFAU
   }
 
   if (!resolvedEncryptionToken) {
-    throw new Error('Missing encryption token. Include #token=... in the URL or pass --token.')
+    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 {
@@ -160,16 +163,24 @@ async function readMetaFile(metaPath) {
 
 async function resolveEncryptionMeta({
   metaPath = '',
+  inlineMeta = null,
   linkToken = '',
   baseUrl = DEFAULT_BASE_URL,
   signal,
 }) {
+  if (inlineMeta) {
+    return { meta: inlineMeta }
+  }
+
   if (metaPath) {
-    return readMetaFile(metaPath)
+    return { meta: await readMetaFile(metaPath) }
   }
 
   if (!linkToken) {
-    throw new Error('Pass --link to fetch encryption metadata, or --meta with a saved metadata JSON file.')
+    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 `link` field in upload JSON (also appears as /f/LINK_ID and link?link=LINK_ID).',
+    )
   }
 
   const linkInfo = await fetchLinkInfo(baseUrl, linkToken, signal)
@@ -487,11 +498,78 @@ async function decryptFromLocalParts({
   onProgress?.(100)
 }
 
-function resolveEncryptionToken(encryptionToken, shareReference) {
+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 (`link` 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.link || 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 or include #token=... in --share-url.')
+    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
@@ -513,34 +591,52 @@ function buildDecryptResult({
     size,
     mimeType,
     expiresAt,
-    linkToken,
+    link: 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(options.shareUrl || '', {
-    encryptionToken: options.encryptionToken,
-    baseUrl: options.baseUrl,
+  const shareReference = parseShareReference(resolvedOptions.shareUrl || '', {
+    encryptionToken: resolvedOptions.encryptionToken,
+    baseUrl: resolvedOptions.baseUrl,
   })
-  const linkToken = options.linkToken || shareReference.linkToken
+  const linkToken = resolvedOptions.linkToken || shareReference.linkToken
+
+  if (
+    !resolvedOptions.uploadJsonPath
+    && !resolvedOptions.metaPath
+    && !resolvedOptions.inlineMeta
+    && !linkToken
+  ) {
+    hintTokenConfusion(resolvedOptions.encryptionToken, '')
+  }
+
   const resolved = await resolveEncryptionMeta({
-    metaPath: options.metaPath,
+    metaPath: resolvedOptions.metaPath,
+    inlineMeta: resolvedOptions.inlineMeta,
     linkToken,
-    baseUrl: options.baseUrl || shareReference.baseUrl,
-    signal: options.signal,
+    baseUrl: resolvedOptions.baseUrl || shareReference.baseUrl,
+    signal: resolvedOptions.signal,
   })
   const meta = resolved.meta || resolved
   const linkInfo = resolved.linkInfo || null
-  const encryptionToken = resolveEncryptionToken(options.encryptionToken, shareReference)
+  const encryptionToken = resolveEncryptionToken(
+    resolvedOptions.encryptionToken,
+    shareReference,
+    linkToken,
+  )
   const tokenBytes = importToken(encryptionToken)
   const noncePrefix = fromBase64Url(meta.noncePrefix)
-  const originalName = linkInfo?.originalName || options.originalName || 'download'
-  const outputName = sanitizeOutputName(options.output ? path.basename(options.output) : originalName)
-  const outputPath = path.resolve(options.output || path.join(options.outputDirectory || process.cwd(), outputName))
+  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 })
 
@@ -551,8 +647,8 @@ async function decryptLocalFile(inputPath, options = {}) {
       tokenBytes,
       noncePrefix,
       outputPath,
-      onProgress: options.onProgress,
-      signal: options.signal,
+      onProgress: resolvedOptions.onProgress,
+      signal: resolvedOptions.signal,
     })
 
     return buildDecryptResult({
@@ -560,7 +656,7 @@ async function decryptLocalFile(inputPath, options = {}) {
       originalName,
       size: meta.originalSize,
       mimeType: meta.mimeType,
-      expiresAt: linkInfo?.expiresAt || null,
+      expiresAt: linkInfo?.expiresAt || resolvedOptions.uploadExpiresAt || null,
       linkToken,
       storageMode: 'parts',
       sourcePath: absolutePath,
@@ -573,8 +669,8 @@ async function decryptLocalFile(inputPath, options = {}) {
     tokenBytes,
     noncePrefix,
     outputPath,
-    onProgress: options.onProgress,
-    signal: options.signal,
+    onProgress: resolvedOptions.onProgress,
+    signal: resolvedOptions.signal,
   })
 
   return buildDecryptResult({
@@ -582,7 +678,7 @@ async function decryptLocalFile(inputPath, options = {}) {
     originalName,
     size: meta.originalSize,
     mimeType: meta.mimeType,
-    expiresAt: linkInfo?.expiresAt || null,
+    expiresAt: linkInfo?.expiresAt || resolvedOptions.uploadExpiresAt || null,
     linkToken,
     storageMode: 'single',
     sourcePath: absolutePath,
@@ -590,21 +686,22 @@ async function decryptLocalFile(inputPath, options = {}) {
 }
 
 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 (options.localFile || (!looksLikeRemoteInput(trimmedInput) && await pathExists(trimmedInput))) {
-    return decryptLocalFile(trimmedInput, options)
+  if (resolvedOptions.localFile || (!looksLikeRemoteInput(trimmedInput) && await pathExists(trimmedInput))) {
+    return decryptLocalFile(trimmedInput, resolvedOptions)
   }
 
   const parsed = parseDecryptInput(trimmedInput, {
-    encryptionToken: options.encryptionToken,
-    baseUrl: options.baseUrl,
+    encryptionToken: resolvedOptions.encryptionToken,
+    baseUrl: resolvedOptions.baseUrl,
   })
 
-  const linkInfo = await fetchLinkInfo(parsed.baseUrl, parsed.linkToken, options.signal)
+  const linkInfo = await fetchLinkInfo(parsed.baseUrl, parsed.linkToken, resolvedOptions.signal)
 
   if (linkInfo.status === 'expired') {
     throw new Error('This file link has expired.')
@@ -621,8 +718,12 @@ export async function decryptFile(input, options = {}) {
 
   const tokenBytes = importToken(parsed.encryptionToken)
   const noncePrefix = fromBase64Url(meta.noncePrefix)
-  const outputName = sanitizeOutputName(options.output ? path.basename(options.output) : linkInfo.originalName)
-  const outputPath = path.resolve(options.output || path.join(options.outputDirectory || process.cwd(), outputName))
+  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 })
 
@@ -634,8 +735,8 @@ export async function decryptFile(input, options = {}) {
       tokenBytes,
       noncePrefix,
       outputPath,
-      onProgress: options.onProgress,
-      signal: options.signal,
+      onProgress: resolvedOptions.onProgress,
+      signal: resolvedOptions.signal,
     })
   } else {
     const encryptedFileUrl = linkInfo.downloadUrl
@@ -647,8 +748,8 @@ export async function decryptFile(input, options = {}) {
       tokenBytes,
       noncePrefix,
       outputPath,
-      onProgress: options.onProgress,
-      signal: options.signal,
+      onProgress: resolvedOptions.onProgress,
+      signal: resolvedOptions.signal,
     })
   }
 

package/lib/upload.js

@@ -124,7 +124,7 @@ function buildResult(payload, context, shareUrl) {
     shareUrl,
     url: payload.url,
     encryptedFile: payload.downloadUrl,
-    token: payload.token,
+    link: payload.token,
     encryptionToken: context.token,
     clientEncryptionMeta: context.meta,
     originalName: payload.originalName || context.originalName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bytifi",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Official Bytifi CLI — encrypt, upload, and decrypt files from the terminal",
   "type": "module",
   "bin": {