PR #1782 adds aws_sts_assume_role to the existing gateway-managed provider credential refresh system. The reviewed head is cb10f837 on feat/1576-aws-sts-with-sigv4.
The existing refresh model assumes one refresh state produces one injectable provider credential. That assumption held for OAuth2 refresh token, OAuth2 client credentials, and Google service account JWT strategies. Those strategies mint one access token. An OAuth server may also rotate its refresh token, but that value remains gateway-side refresh material and is not injected into the sandbox.
AWS STS is the first strategy that produces multiple injectable credentials from one operation:
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN
The refresh state records one dynamic credential_key, while the STS minting implementation hardcodes the other two keys. The profile declares all three credentials, but it does not declare that the refresh attached to access_key_id also owns secret_access_key and session_token.
The current relationship is split across three places:
Provider profile
declares access_key_id, secret_access_key, and session_token
Refresh state
records only credential_key, normally AWS_ACCESS_KEY_ID
STS mint implementation
hardcodes AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN
The SigV4 proxy separately looks up the three standard AWS environment-variable names. Changing only the profile would not change either the STS mint output or the proxy lookup.
Relevant code:
providers/aws.yamlandproviders/aws-s3.yamldeclare the credentials and attach refresh only toaccess_key_id.crates/openshell-server/src/provider_refresh.rswrites the primary value understate.credential_keyand hardcodes the two additional credential keys.crates/openshell-server/src/grpc/provider.rs::active_provider_environment_keysreserves onlystate.credential_keyfor a configured refresh state.crates/openshell-supervisor-network/src/l7/rest.rsresolves the exact keysAWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY, andAWS_SESSION_TOKENfor SigV4.
The configure handler checks all three AWS keys against sandboxes that already use the provider. The later sandbox attachment path does not know that an unrotated STS refresh state owns three keys.
One failing sequence is:
- Create an STS-backed provider.
- Configure STS refresh but do not rotate it yet.
- Create another provider that owns
AWS_SECRET_ACCESS_KEY. - Attach both providers to a sandbox.
- Sandbox attachment succeeds because the STS refresh state reserves only
AWS_ACCESS_KEY_ID. - The worker or a manual rotation calls STS and tries to write all three credentials.
- The final provider-update collision check rejects the refresh because
AWS_SECRET_ACCESS_KEYis already owned by the other provider.
The system fails closed and does not silently overwrite a credential. The defect is that it accepts a sandbox configuration that is already known to be incompatible and reports the failure only when credentials are minted.
The same gap can reappear after credentials expire. Expired provider credential keys are excluded from the active environment calculation, while the refresh state continues to reserve only its primary key.
The aws and aws-s3 profiles declare AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN as required credentials without their own refresh declarations. ProviderTypeProfile::allows_empty_provider_credentials() therefore considers them required static credentials rather than outputs of the STS refresh.
CredentialRefreshProfile::is_gateway_mintable() also does not include AwsStsAssumeRole at the reviewed head. Consequently, adding --runtime-credentials to the provider creation command is not sufficient by itself. The manual E2E currently works around the model by creating the provider with a placeholder AWS_ACCESS_KEY_ID and rotating before sandbox attachment.
The API accepts an arbitrary credential_key with aws_sts_assume_role. The primary STS result is written under that requested key, but the SigV4 proxy always looks for AWS_ACCESS_KEY_ID. A configuration using another primary key can be accepted but cannot support the built-in SigV4 path.
The profile's env_vars field describes credential environment-variable names, supports discovery, and helps match a requested credential key to profile refresh defaults. Actual sandbox provider environment values are built from the keys stored in Provider.credentials. For STS, those stored keys are currently selected by state.credential_key plus hardcoded Rust constants.
Add one canonical strategy descriptor or helper that returns all provider credential keys managed by a refresh state.
fn managed_credential_keys(
strategy: ProviderCredentialRefreshStrategy,
primary_key: &str,
) -> Vec<&str> {
match strategy {
ProviderCredentialRefreshStrategy::AwsStsAssumeRole => vec![
primary_key,
"AWS_SECRET_ACCESS_KEY",
"AWS_SESSION_TOKEN",
],
_ => vec![primary_key],
}
}Use the helper in configure-time collision checks, sandbox attachment validation, runtime-resolvability checks, and minted credential application. Also require the STS primary key to be AWS_ACCESS_KEY_ID and add AwsStsAssumeRole to the profile-side gateway-mintable strategy set.
- Small and focused.
- No profile or protobuf migration.
- Appropriate if AWS STS is expected to remain the only multi-output strategy.
- The AWS environment-variable names are stable external standards and are already required by the SigV4 proxy.
- The profile still does not describe the complete refresh output contract.
- Custom profiles cannot remap strategy outputs.
- Strategy ownership remains partly encoded in Rust rather than the provider schema.
- A future multi-output strategy requires another hardcoded branch.
This is likely a focused change across provider_refresh.rs, grpc/provider.rs, profiles.rs, tests, and documentation. It should not require protobuf changes.
Keep refresh attached to one primary credential, but let it reference sibling credential declarations for every additional strategy output.
Recommended shape:
credentials:
- name: access_key_id
env_vars: [AWS_ACCESS_KEY_ID]
refresh:
strategy: aws_sts_assume_role
additional_outputs:
- output: secret_access_key
credential: secret_access_key
- output: session_token
credential: session_token
- name: secret_access_key
env_vars: [AWS_SECRET_ACCESS_KEY]
required: true
- name: session_token
env_vars: [AWS_SESSION_TOKEN]
required: trueoutput is a strategy-defined semantic output name. credential references another credential declaration in the same profile. Keeping both fields avoids coupling custom profile credential names to strategy implementation names.
At configuration time, the gateway resolves the profile relationship into concrete provider credential keys:
primary result -> access_key_id -> AWS_ACCESS_KEY_ID
secret_access_key -> secret_access_key -> AWS_SECRET_ACCESS_KEY
session_token -> session_token -> AWS_SESSION_TOKEN
The resolved mapping should be persisted with the refresh state rather than re-derived on every rotation:
credential_key: AWS_ACCESS_KEY_ID
additional_credential_keys:
secret_access_key: AWS_SECRET_ACCESS_KEY
session_token: AWS_SESSION_TOKENPersisting the resolved mapping prevents a later profile update from silently changing where an existing refresh writes credentials. Reconfiguration would be required to adopt changed output mappings.
The generic mint result then carries semantic outputs rather than concrete environment-variable names:
MintedCredential {
primary: access_key_id,
additional_outputs: HashMap::from([
("secret_access_key", secret_access_key),
("session_token", session_token),
]),
}- Every referenced sibling credential exists in the same profile.
- Output names and credential references are unique.
- An additional-output credential cannot independently own another refresh operation.
- The selected strategy recognizes every declared output.
- All strategy-required outputs are mapped.
- Each referenced credential resolves to one canonical provider credential key.
- For the current SigV4 implementation, the AWS mappings resolve to the exact standard AWS names.
- The primary STS credential resolves to
AWS_ACCESS_KEY_ID.
- The profile becomes the source of truth for multi-output ownership.
- Empty provider creation can correctly treat all three required AWS credentials as runtime-resolvable.
- Collision detection can reserve every future output before the first mint.
- Mint application becomes strategy-output driven rather than environment-name driven.
- Future multi-output strategies can reuse the model.
- Custom profile import and export preserves the complete relationship.
- Requires additive protobuf and YAML schema changes.
- Requires profile serialization, validation, configure-time resolution, refresh-state persistence, and documentation updates.
- Requires a decision for credentials that declare multiple
env_vars. The initial contract should probably require exactly one canonical environment variable for an additional refresh output.
This is a moderate cross-cutting change, likely touching the profile protobuf, stored refresh-state protobuf, profile serde, validation, configure handling, mint application, provider runtime-resolvability, collision detection, built-in profiles, tests, and documentation. The data path already supports multiple returned values, so this is a model and validation change rather than a refresh-system rewrite.
A more general redesign would make refresh operations siblings of credentials and map every strategy output explicitly. This removes the special primary credential but changes the profile model much more substantially.
credentials:
- name: access_key_id
env_vars: [AWS_ACCESS_KEY_ID]
- name: secret_access_key
env_vars: [AWS_SECRET_ACCESS_KEY]
- name: session_token
env_vars: [AWS_SESSION_TOKEN]
refresh_sets:
- strategy: aws_sts_assume_role
outputs:
access_key_id: access_key_id
secret_access_key: secret_access_key
session_token: session_tokenThis is the cleanest fully general model but is not necessary to solve PR #1782. It would require broader CLI and API decisions around how users identify, configure, rotate, and query a refresh set rather than one credential key.
If PR #1782 should establish multi-output refresh as a supported provider capability, Option B is the best long-term shape. It preserves the existing primary-credential model while making additional ownership explicit and reusable.
If the goal is to merge a narrow AWS STS implementation without expanding the provider schema, Option A is acceptable provided all AWS key knowledge is centralized in one strategy descriptor and reused consistently by minting, collision detection, runtime-resolvability, and validation.
Option C should be deferred unless a second use case demonstrates that the primary-credential model itself is the wrong abstraction.
- Configured but unrotated STS provider conflicts with another provider owning
AWS_SECRET_ACCESS_KEY. - Configured but unrotated STS provider conflicts with another provider owning
AWS_SESSION_TOKEN. - Expired STS credentials continue reserving all managed output keys through refresh state.
- Empty
aws-s3provider creation succeeds only when all required outputs are runtime-resolvable. - STS configuration rejects a primary key other than
AWS_ACCESS_KEY_ID. - Profile validation rejects missing, duplicate, unknown, or self-referential additional outputs.
- Profile round-trip through YAML and protobuf preserves additional output mappings.
- A profile update does not silently alter an already configured refresh state's resolved output mapping.
- Is multi-output refresh intended as a general provider feature or an AWS-specific exception?
- Should additional outputs permit multiple environment-variable aliases, or require one canonical environment key?
- Should existing refresh states re-resolve output mappings after a profile update, or remain pinned until explicitly reconfigured?
- Should output identifiers be free-form strategy strings or an enum-like validated set owned by each strategy implementation?
- Should the SigV4 proxy remain hardcoded to standard AWS names, or should signing configuration eventually reference profile credentials?