S3 Gateway Cost Controls

Gateway cost controls extend Vaulthalla's S3/R2 price-budget model with budgets tied to inbound gateway credentials. They are separate from the upstream request budgets and provider/vault/global price budgets used by sync.

Gateway Budget Scopes

Modes match normal price budgets:

Actual Upstream Usage

Gateway accounting is based on actual upstream use, not route intent. A remote-backed GET might be served from a local encrypted file, a materialized cache file, metadata, or a real upstream download. Only real upstream provider calls consume provider, vault, or global upstream budgets.

Local gateway buckets, metadata-only requests, local/cache hits, and local-first PUT/DELETE/COPY/multipart writes do not consume upstream provider budgets at gateway request time. For remote-backed writes and deletes, sync later owns upstream provider side effects and provider/vault/global ledger entries.

Synthetic Local Usage

Gateway credentials can opt into local/cache accounting:

1vh s3-gateway creds create backup --enforce-budget-for-local-requests2vh s3-gateway creds scope backup set --enforce-budget-for-local-requests3vh s3-gateway creds scope backup set --no-enforce-budget-for-local-requests

When enabled, pure local buckets, remote-cache hits, metadata-only requests, and sync-deferred local-first writes/deletes are recorded as synthetic usage for gateway_credential and gateway_credential_vault budgets only. Synthetic ledger rows include synthetic=true and a source such as local_cache, local_file, metadata, or sync_deferred.

Synthetic local usage uses s3_gateway.synthetic_local_request_cost_usd and never creates provider, vault, or global upstream ledger rows.

CLI Examples

1# Monthly spend cap per key. Key-wide caps are admin-managed.2vh s3-gateway budget set-key backup \3  --monthly 5 \4  --mode enforce \5  --currency USD6 7# Monthly spend cap for one key/vault pair.8vh s3-gateway budget set-key-vault backup \9  --vault archive \10  --monthly 2 \11  --mode enforce \12  --currency USD13 14vh s3-gateway budget status --key backup15vh s3-gateway budget ledger --key backup --limit 50

Disable policies:

1vh s3-gateway budget disable-key backup2vh s3-gateway budget disable-key-vault backup --vault archive

Denial Behavior

Price-budget enforcement returns S3 XML with:

Price-budget denial messages begin with S3 gateway price budget exceeded and include the blocking scope, policy id, window, limit, used-before amount, remaining-before amount, requested cost, currency, provider key, vault id, gateway credential id, operation, and request UUID.

Request-budget denials begin with S3 gateway request budget exceeded and identify the exhausted request kind, such as GET, PUT, DELETE, COPY, or downloaded bytes.

Use budget status and ledger output to distinguish actual upstream use from synthetic local usage:

1vh s3-gateway budget status --key backup --vault archive2vh s3-gateway budget ledger --key backup --limit 25