# Capability: Object Storage Access

Status: draft
Readiness target: RL3 production
Primary owners: NetKingdom, Railiance platform, artifact-store

## Intent

Provide safe object-storage access for platform and tenant workloads
without giving applications long-lived root credentials or making each
application own storage authorization policy.

## Scope

Included:

- identity-backed access requests;
- bucket, prefix, action, tenant, and TTL scoping;
- temporary credentials with session token and expiration;
- audit correlation across identity, authorization, OpenBao, backend,
  and workload events;
- transitional static credential bridge where STS is not ready.

Excluded:

- object-storage backend deployment;
- product-specific artifact package semantics;
- replacing flex-auth with provider-specific bucket policy;
- exposing parent object-store credentials to tenant workloads.

## Threats Addressed

- leaked long-lived object-store access keys;
- application repos becoming policy owners for storage access;
- cross-tenant bucket or prefix access;
- workloads using platform-root object-store credentials;
- unaudited access to generated artifacts, backups, reports, and
  evidence packages;
- failure to revoke or expire credentials after task completion.

## Required Controls

- IAM Profile token validation for human, service, and agent callers.
- flex-auth decision envelope for protected system, tenant, resource,
  action set, TTL, assurance, obligations, and deny reason.
- Provider-native temporary credentials where the backend supports them.
- OpenBao custody for parent credentials, broker configuration, delivery
  secrets, and audit records where used.
- Consumer support for `AWS_SESSION_TOKEN` and expiration-aware refresh.
- Durable audit sink and correlation id.

## Implementation Options

| Option | Use when | Notes |
| --- | --- | --- |
| AWS STS `AssumeRoleWithWebIdentity` | AWS-native object storage | Strong native fit; use IAM OIDC provider and role trust policies |
| Ceph RGW STS | self-hosted Ceph object storage | Use when RGW IAM/STS maturity fits deployment risk |
| MinIO/AIStor STS | lightweight or self-hosted S3-compatible storage | Good fit if consumers support session tokens |
| Cloudflare R2 temporary credentials | Cloudflare object storage | Requires backend-specific broker protecting parent credentials |
| Transitional static bridge | before STS support is ready | Store scoped static credentials in OpenBao; rotate and retire quickly |

## Platform Responsibility

- define issuer, audience, tenant, and assurance requirements;
- define flex-auth resource/action vocabulary;
- operate or approve the credential-vending service;
- protect backend parent credentials through OpenBao;
- provide audit retention and break-glass procedure.

## Product Responsibility

- use temporary credentials rather than root/static credentials;
- refresh credentials before expiration;
- include correlation ids in storage operations where possible;
- handle deny and expiration cleanly;
- avoid embedding policy decisions in application code.

## Tenant Responsibility

- request access only to registered tenant resources;
- manage tenant-scoped groups or memberships where delegated;
- review tenant-visible audit events where available.

## Readiness Criteria

| Level | Criteria |
| --- | --- |
| RL1 | static scoped credentials are not committed; object-store root credentials are not used |
| RL2 | tenant/bucket/prefix mapping exists; OpenBao or equivalent custody protects credentials |
| RL3 | temporary credentials, session token support, flex-auth decisions, audit correlation, and refresh behavior are verified |
| RL4 | tenant-visible audit, dual control for platform-scoped access, restore/revocation drills, and standards mapping are complete |

## Evidence

- `docs/object-storage-sts-credential-vending.md`
- `ADR-0008 - Object Storage STS Credential Vending Boundary`
- artifact-store support for `AWS_SESSION_TOKEN`
- OpenBao audit record for broker/parent credential access
- flex-auth decision record with stable reason codes
- backend credential expiration and revocation proof

## Related Patterns

- `pattern-sts-credential-vending.md`
- secret zero avoidance
- delegated authorization
- workload identity
- central audit ledger

## Related Standards

- NIST CSF Protect and Detect functions.
- OWASP API Security broken object-level authorization risk.
- SLSA and artifact integrity patterns where object storage holds release
  artifacts or provenance.