Securing Private Files & Signed URLs

import { StorageClient } from '@dcd-sdk/storage-client';

const storage = new StorageClient({
  endpoint: process.env.DCD_STORAGE_ENDPOINT!,
  apiKey: process.env.DCD_STORAGE_API_KEY!,
});

// 1. Upload confidential invoice as private
const asset = await storage.upload('./invoices/inv-2026-904.pdf', {
  folder: 'billing/invoices',
  access: 'private',
});

// 2. Generate a 15-minute temporary download link
const signedDownloadUrl = await storage.getSignedUrl(asset.publicId, {
  expiresInSeconds: 900,
  resourceType: 'raw',
});

console.log('Secure Link:', signedDownloadUrl);

Not all files belong on an unrestricted public CDN. Customer invoices, tax filings, passport scans, internal contracts, and database snapshots must never be visible to search engine crawlers or brute-forced by scrapers.

DevCloudDesk includes cryptographic HMAC-SHA256 asset protection out of the box.

---

Public vs Private Assets#

---

Step 1: Uploading Files as Private#

Set access: 'private' in the upload options. The storage server stores the file with private ACL flags in its local index.

---

Step 2: Generating Expiring Signed URLs#

When an authorized user requests to view or download their private file, generate a time-limited signed URL on your backend.

Method Options#

---

How Signature Verification Works#

bashCopy
┌─────────────────────────────────────────────────────────────┐
│ 1. Client Browser requests URL:                             │
│    GET /raw/upload/invoices/inv-904.pdf?exp=1792600600&sig=..│
└───────────────────────────┬─────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. Storage Server Checks Expiration:                        │
│    Is Current Timestamp > 1792600600?                       │
│    YES ──► Return 401 Unauthorized ("Signed URL Expired")   │
│    NO  ──► Proceed to HMAC validation                       │
└───────────────────────────┬─────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. Storage Server Computes HMAC:                            │
│    hmac_sha256("raw/invoices/inv-904.pdf:1792600600", KEY)  │
│    Matches provided ?sig query param?                       │
│    NO  ──► Return 403 Forbidden ("Invalid Signature")       │
│    YES ──► Stream file with "Cache-Control: private"        │
└─────────────────────────────────────────────────────────────┘

1. Tamper Resistance: If a client alters the expiration timestamp (exp) or tries to change the file path, the calculated HMAC hash fails to match, resulting in an immediate 403 Forbidden.
2. Zero In-Memory State: The server does not maintain an expiration database. Verification is pure cryptographic math executed in sub-millisecond CPU time.
3. Cache Privacy: Responses include Cache-Control: private, no-store, no-cache headers, ensuring public proxies never leak confidential customer data.

---

Changing File Visibility Later#

If an asset was originally uploaded as private and needs to become publicly accessible (or vice versa), update its access mode using the administrative API: