Files

4.8 KiB

Security Considerations for r2-upload

Current Security Measures ✅

1. Config File Permissions

  • ✅ ~/.r2-upload.yml is created with 0600 permissions (owner read/write only)
  • ✅ Prevents other users from reading your credentials

2. Presigned URLs

  • ✅ Default expiration: 5 minutes (configurable)
  • ✅ URLs expire automatically
  • ✅ No permanent public access unless explicitly configured

3. UUID Prefixes

  • ✅ Randomized key prefixes prevent filename collisions
  • ✅ Makes guessing file URLs harder

4. Credential Isolation

  • ✅ Credentials stored locally, not in code
  • ✅ Environment variable override option (R2_UPLOAD_CONFIG)

Security Recommendations ⚠️

1. R2 API Token Scope (IMPORTANT)

When creating your R2 API token:

  • ✅ Apply to specific bucket only (not account-wide)
  • ✅ Use minimum permissions: Object Read & Write only
  • ❌ Avoid: Admin permissions, account-wide access

Why: Limits blast radius if credentials are compromised.

2. File Size Limits (Not Currently Implemented)

Consider adding to index.ts:

const MAX_FILE_SIZE = 100 * 1024 * 1024; // 100 MB
const stats = await stat(file_path);
if (stats.size > MAX_FILE_SIZE) {
  throw new Error('File too large');
}

Why: Prevents accidental upload of huge files or DoS.

3. Path Traversal Protection (Partially Protected)

Current protection:

  • ✅ UUID prefix prevents predictable paths
  • ⚠️ User can still specify custom key parameter

Consider sanitizing custom keys:

if (key && (key.includes('..') || key.startsWith('/'))) {
  throw new Error('Invalid key: path traversal detected');
}

4. File Type Restrictions (Not Currently Implemented)

Consider allowlist/blocklist:

const BLOCKED_EXTENSIONS = ['.exe', '.sh', '.bat', '.cmd'];
const ext = path.extname(file_path).toLowerCase();
if (BLOCKED_EXTENSIONS.includes(ext)) {
  throw new Error('File type not allowed');
}

Why: Prevent malicious executable uploads.

5. Audit Logging (Not Currently Implemented)

Log all uploads for security auditing:

console.error(`[AUDIT] Upload: ${file_path} -> ${bucket}/${key} by user`);

6. Rate Limiting (Not Currently Implemented)

Consider tracking upload frequency to prevent abuse.

Best Practices for Users

✅ DO:

  1. Use bucket-specific API tokens with minimal permissions
  2. Keep config file secure (~/.r2-upload.yml should be 600)
  3. Use short expiration times for presigned URLs (default: 5m is good)
  4. Review uploaded files periodically with r2_list
  5. Rotate credentials if you suspect compromise
  6. Use different buckets for different security levels (public vs private)

❌ DON'T:

  1. Don't share presigned URLs publicly unless intended
  2. Don't commit config file to git (already in .gitignore)
  3. Don't use admin/root R2 tokens - create limited tokens
  4. Don't upload sensitive files without encryption
  5. Don't set long expirations (>24h) unless necessary

Threat Model

What we protect against:

  • ✅ Config file read by other users (file permissions)
  • ✅ Permanent unauthorized access (expiring URLs)
  • ✅ Predictable file paths (UUID prefixes)
  • ✅ Credential exposure in code (external config)

What we don't protect against:

  • ⚠️ Large file uploads (no size limits)
  • ⚠️ Malicious file types (no validation)
  • ⚠️ Path traversal in custom keys
  • ⚠️ Rate limiting / abuse
  • ⚠️ File content scanning

For production use, consider:

// Add to index.ts
const SECURITY_CONFIG = {
  maxFileSize: 100 * 1024 * 1024, // 100 MB
  maxExpiration: 24 * 3600, // 24 hours
  allowedExtensions: ['.pdf', '.jpg', '.png', '.gif', '.zip', '.tar.gz'],
  blockedExtensions: ['.exe', '.sh', '.bat', '.cmd', '.dll'],
  requirePathSanitization: true,
  auditLog: true,
};

Incident Response

If credentials are compromised:

  1. Immediately revoke the R2 API token in Cloudflare dashboard
  2. Generate new credentials
  3. Update ~/.r2-upload.yml
  4. Review bucket contents for unauthorized uploads
  5. Delete any suspicious files
  6. Check Cloudflare R2 audit logs

Reporting Security Issues

Found a security issue? Please report responsibly:

  1. Don't open a public GitHub issue
  2. Do contact the maintainer privately
  3. Allow time for a fix before disclosure

Compliance Notes

  • GDPR/Privacy: Don't upload personal data without proper legal basis
  • Encryption: Files are encrypted at rest by R2, but not end-to-end
  • Access logs: R2 provides access logs - enable for compliance
  • Data residency: R2 uses Cloudflare's global network

Updates

  • 2026-01-09: Initial security review - v1.0.0