# Pattern: STS Credential Vending

Status: reviewed
Readiness target: RL3 production
Primary owners: NetKingdom, flex-auth, Railiance platform

## Problem

Applications need object-storage access, but long-lived access keys in
application pods, repositories, or tenant namespaces create a durable
compromise path. Provider-specific bucket policy alone is not enough for
NetKingdom because access decisions must include identity, tenant,
resource, action, TTL, assurance, and audit context.

## Context

Use this pattern when a workload, service, agent, or human needs
temporary access to S3-compatible object storage. The first target
consumer is `artifact-store`, but the pattern is intended for any
NetKingdom-enabled platform or tenant workload.

The pattern applies across AWS S3, Ceph RGW, MinIO/AIStor, Cloudflare R2,
and OpenBao-assisted broker paths.

## Forces

- Provider-native STS gives strong backend expiration semantics, but
  providers differ in API shape and OIDC support.
- Applications need a simple credential contract, but security decisions
  require rich context.
- OpenBao can protect parent credentials and audit broker operations, but
  must not become the authorization policy engine.
- Tenant administrators need self-service within tenant scope, but must
  not receive platform-root object-store or OpenBao authority.
- Temporary credentials reduce blast radius, but consumers must refresh
  safely and support session tokens.

## Solution

Introduce a credential-vending service that accepts a NetKingdom IAM
Profile token or workload identity, asks flex-auth for an authorization
decision, and exchanges approved requests for provider-native temporary
credentials or an OpenBao-assisted broker path.

The consumer receives normalized credentials:

```text
access key id
secret access key
session token
expiration
scope metadata
decision/audit correlation id
```

## Implementation Sketch

1. Caller authenticates through key-cape or Keycloak.
2. Credential-vending service validates issuer, audience, subject,
   tenant, expiration, and assurance evidence.
3. Service builds a flex-auth request with protected-system id, bucket,
   prefix/object, actions, TTL, actor, tenant, and context.
4. flex-auth evaluates policy, delegated to Topaz where appropriate.
5. Deny returns a stable reason code and audit id.
6. Allow invokes backend exchange:
   - AWS STS `AssumeRoleWithWebIdentity`;
   - Ceph RGW STS;
   - MinIO/AIStor STS;
   - Cloudflare R2 temporary credential API;
   - OpenBao-assisted broker path for protected parent material.
7. Service records identity, policy, backend, lease, and audit metadata.
8. Consumer refreshes before expiration.

## Failure Modes

| Failure | Mitigation |
| --- | --- |
| Consumer lacks `AWS_SESSION_TOKEN` support | keep static bridge only as transitional; add session token refs |
| flex-auth unavailable | fail closed except documented emergency platform workflows |
| OpenBao unavailable | fail if parent material or broker config is required |
| Backend STS unavailable | return retryable backend error; do not fall back to root credentials |
| Tenant mismatch | deny with stable reason code |
| TTL too long | reduce to policy maximum or deny |
| Audit sink unavailable | deny privileged/platform-scoped requests; buffer only if policy permits |

## Related Capabilities

- Object storage access.
- Authorization and access control.
- Secrets, keys, and credentials.
- Tenant isolation.
- Observability, detection, and audit.

## Maturity

Reviewed. The pattern has architecture and ADR coverage in NetKingdom.
It should not be marked canonical until artifact-store temporary session
token support and at least one backend exchange path are verified.

## Verification

- IAM Profile validation rejects wrong issuer or audience.
- flex-auth decision includes tenant, protected system, bucket/prefix,
  action set, TTL, obligations, and deny reason.
- Backend returns access key id, secret access key, session token, and
  expiration.
- OpenBao audit record exists when parent material or broker config is
  accessed.
- Consumer refreshes before expiration.
- Deny paths emit stable reason codes.

## References

- NetKingdom `docs/object-storage-sts-credential-vending.md`.
- NetKingdom `ADR-0008 - Object Storage STS Credential Vending Boundary`.
- Railiance Platform `docs/openbao.md`.
- Artifact-store `ARTIFACT-STORE-WP-0007`.