Vaulthalla Logo

S3 Gateway

S3 Gateway is Vaulthalla's S3-compatible protocol surface. It is not a vault type. A gateway bucket is an S3 bucket name exposed by Vaulthalla and bound to a Vaulthalla vault, and an S3 object key maps to a vault-relative path.

Downstream S3 clients such as AWS CLI, rclone, MinIO mc, SDKs, and backup applications connect to Vaulthalla's gateway endpoint with a gateway credential. Those inbound credentials are separate from upstream provider credentials created with vh api-key for Vaulthalla to access AWS S3, Cloudflare R2, or another compatible provider.

Gateway credentials are RBAC-native. A request is allowed only when the effective principal's normal Vaulthalla RBAC allows the action and the credential scope permits it. user_access uses principal RBAC only. vault_allowlist uses selected vaults plus a key-level default vault role, with optional per-vault exceptions. global covers gateway bucket bindings but still requires a key-level default vault role.

How It Fits

ConceptMeaning
Downstream S3 clientAWS CLI, rclone, MinIO mc, SDKs, or apps talking to Vaulthalla.
Gateway credentialInbound S3 access key and secret issued by Vaulthalla for downstream clients.
Gateway bucketS3 bucket name exposed by Vaulthalla and bound to a Vaulthalla vault.
Upstream S3/R2 bucketExternal AWS S3, Cloudflare R2, or compatible bucket that Vaulthalla uses as storage for an S3/R2 vault.
Upstream provider credentialvh api-key credential used by Vaulthalla to talk to the upstream provider.

Local gateway buckets expose encrypted local Vaulthalla vaults through S3. Remote-backed gateway buckets expose Vaulthalla S3/R2 vaults to downstream S3 clients, acting as a Vaulthalla-controlled proxy/cache surface over the vault's upstream S3/R2 bucket.

Operation Model

  • Buckets map to vaults.
  • Object keys map to vault-relative paths.
  • LIST is metadata-only; it does not decrypt bodies, compute plaintext ETags, refresh manifests, or call upstream S3/R2.
  • For remote-backed gateway buckets, PUT and DELETE are local-first. The gateway mutates Vaulthalla state immediately, and sync owns eventual upstream provider side effects.
  • GET can be local/cache served or can download a remote-only object when the vault policy allows it.
  • Gateway key and key/vault budgets can account for actual upstream use and, when enabled per credential, synthetic local/cache request usage.

Endpoints

Vaulthalla supports two gateway endpoint shapes:

EndpointTypical URLUse
Direct listenerhttp://127.0.0.1:39000Local tools, development, private host access, and smoke validation.
Managed S3-domain endpointhttps://s3.vaulthalla.example.comPublic or LAN reverse-proxy access through managed Nginx.

The managed S3-domain endpoint uses path-style public reverse-proxy mode. Downstream clients should generally enable path-style addressing so requests sign and send ordinary S3 paths such as /archive/reports/file.txt.

Guides

Setup

Enable the service, configure the listener, publish the managed Nginx S3 domain, and follow web console or CLI workflows.

Clients

Connect AWS CLI, rclone, and MinIO mc, including directory uploads, downloads, deletes, and multipart behavior.

Credentials And Scopes

Create inbound gateway credentials, choose scope modes, assign vault roles, configure path overrides, and avoid upstream key reuse.

Buckets

Create local gateway buckets, bind existing vaults, and expose remote-backed S3/R2 vaults as proxy/cache buckets.

Cost Controls

Use per-key and per-key/vault gateway budgets, actual upstream accounting, synthetic local accounting, and denial diagnostics.

Semantics

Understand LIST, HEAD, GET, PUT, DELETE, ETags, multipart storage, backfill, and current S3 feature limitations.

Validation

Run Playwright, local smoke, remote R2/S3 smoke, and merge-ready validation for the gateway feature.