Skip to content

Storage Service (PPP Backend) ​

This document explains how PPP backend code targets object storage and how storage object keys are built.

Storage is provider-selected via STORAGE_PROVIDER — exactly one of two implementations is active at a time, never a silent fallback (ADR-0006, superseding ADR-0002):

  • azure-blob — Azure Blob Storage (AzureBlobProvider). The legacy provider, used by any environment still running on Azure Container Apps.
  • filesystem — NAS-hosted filesystem storage (FilesystemStorageProvider), backing PPP's Synology NAS deployment. See deploy/nas/docker-compose.nas.yml and ADR-0006 (docs/site/architecture/decisions/0006-nas-hosted-storage-and-runtime.md) for the migration this supports.

createStorageProvider() throws if STORAGE_PROVIDER is unset or unrecognised — there is no default to silently fall back to.

Environment Variables ​

Common ​

  • STORAGE_PROVIDER
    • Selects the backing store: azure-blob or filesystem. Required — no default.
  • STORAGE_KEY_PREFIX
    • Optional prefix applied to all storage object keys (e.g. ppp-dev to isolate environments in a shared account/volume). Applied identically by both providers via the shared applyKeyPrefix helper.

azure-blob ​

  • AZURE_STORAGE_ACCOUNT
    • Azure Storage account name (required).
  • AZURE_STORAGE_CONTAINER
    • Blob container name (required).
  • AZURE_STORAGE_ACCOUNT_KEY
    • Shared-key credential used to sign SAS URLs. Alternatively set AZURE_STORAGE_CONNECTION_STRING. If neither is present, the provider falls back to DefaultAzureCredential (Managed Identity in Azure Container Apps) and uses a user-delegation key for SAS.

filesystem ​

  • STORAGE_OBJECTS_ROOT
    • Absolute path to the write root on disk (required). On the NAS deployment this is the bind-mounted ppp-objects volume (/data/objects inside the container).
  • STORAGE_SIGNING_SECRET
    • HMAC-SHA256 secret used to sign the time-limited tokens getSignedReadUrl/getSignedUploadUrl mint in place of an Azure SAS query string (required). Env-first, same convention as CPD_APPROVAL_SECRET.
  • API_BASE_URL
    • This backend's own externally-reachable base URL, used to build the signed-URL host (e.g. the Cloudflare Tunnel hostname). Not WEB_APP_BASE_URL, which is the frontend's URL.

Key Prefixing Rules ​

All storage keys go through a single normalization step, identical for both providers:

  • If STORAGE_KEY_PREFIX is set, the prefix is prepended to every key.
  • The prefix is idempotent (a key already containing it will not be double-prefixed).
  • If the key uses the public namespace, the prefix is applied after public/.

Examples (with STORAGE_KEY_PREFIX=ppp-dev):

text
input key:      ppp/cpd_activity_files/file.pdf
stored key:     ppp-dev/ppp/cpd_activity_files/file.pdf

input key:      public/ppp/cv/123_file.pdf
stored key:     public/ppp-dev/ppp/cv/123_file.pdf

Signed Upload/Read URLs ​

azure-blob — Azure SAS ​

Upload URLs are short-lived Azure Blob SAS URLs (create/write permission, ~5 minutes) scoped to the public namespace:

  • Requested key: ppp/cpd_activity_files/file.pdf
  • Signed key: public/<prefix>/ppp/cpd_activity_files/file.pdf

The client uploads with an HTTP PUT to the SAS URL and must send the x-ms-blob-type: BlockBlob header. Signed read URLs default to a 1-hour expiry; Passport-scoped blobs are capped at 15 minutes.

Credential resolution order: AZURE_STORAGE_CONNECTION_STRING if set, else AZURE_STORAGE_ACCOUNT_KEY via StorageSharedKeyCredential, else DefaultAzureCredential (Managed Identity, no static key required).

filesystem — self-issued HMAC tokens ​

A filesystem has no native SAS equivalent, so FilesystemStorageProvider mints its own signed URL: an HMAC-SHA256-signed, time-limited token verified by a route this same backend serves — GET /storage/signed/:token for reads, PUT /storage/signed/:token for uploads. Same expiry conventions as Azure (5 min upload / 1 hour read / 15 min Passport-scoped) and the same public/-prefixing convention for upload keys, so callers see identical behaviour across providers. The route is only registered when STORAGE_PROVIDER=filesystem — it does not exist in the Azure-hosted image.

The frontend's existing x-ms-blob-type: BlockBlob upload header (instances/ppp/src/utils/storageClient.ts) is Azure-specific but harmless against this route — it is silently ignored.

  • packages/backend-ppp-core/src/utils/storage/azure-blob-provider.ts — Azure Blob provider (SAS, upload/read/delete, key normalization)
  • packages/backend-ppp-core/src/utils/storage/filesystem-provider.ts — NAS-hosted filesystem provider (HMAC-signed URLs, path-traversal guard)
  • packages/backend-ppp-core/src/utils/storage/index.ts — createStorageProvider (selects provider from STORAGE_PROVIDER, no default)
  • api/backend-ppp/entrypoints/api-container.ts — registers the /storage/signed/:token route when STORAGE_PROVIDER=filesystem
  • api/backend-core/src/services/core/StorageService/index.ts

Internal documentation — org members only