Proposal: Oracle Cloud Infrastructure request signing and principal minting (credential_signing: oci, oci_* refresh strategies)

[fede-kamel]

Summary

Add first-class Oracle Cloud Infrastructure (OCI) support to the credential proxy in two
steps that follow existing precedent exactly:

1. credential_signing: oci on REST endpoints: the sandbox supervisor's proxy signs
   requests with OCI's RSA-SHA256 HTTP Signature scheme using credentials resolved from
   the endpoint-bound provider, so the sandbox never holds a key. Sibling of sigv4,
   sigv4:body and sigv4:no_body.
2. Three gateway-side provider refresh strategies, oci_instance_principal,
   oci_resource_principal and oci_oke_workload_identity, that mint a security token
   (OCI_KEY_ID = ST$<token>) and co-mint an ephemeral RSA session key
   (OCI_PRIVATE_KEY) through additional_outputs. Counterpart of aws_sts_assume_role.

Issues: #3960 (signing), #3961 (minting). Implementation: #3962 and #3975 (stacked).
Umbrella and history: #3879. Merged precedent for OCI in the repository:
providers/oci-genai.yaml (#3904), which only covers the bearer-authenticated
OpenAI-compatible endpoint.

Motivation

OpenShell replaces secrets with placeholders in the sandbox and resolves them in HTTP
headers at the proxy. That works for bearer and basic auth, and it is why oci-genai
works today. Every other OCI API (native Generative AI at /20231130, Object Storage,
Vault, Compute, Functions, OKE control plane) is request-signed: an RSA-SHA256 signature
over date (request-target) host, plus content-length content-type x-content-sha256
for requests with a body, with keyId either <tenancy>/<user>/<fingerprint> (API key)
or ST$<security-token> (session, instance, resource or workload principal). Header
substitution cannot repair a signature made with a placeholder key.

The workarounds are the ones the project already rejects for AWS: inject the real
private key into the sandbox as a plain value, or run a signing bridge per service
outside the sandbox and grant the sandbox egress to it. SigV4 (#1631) and STS (#1576)
solved this for AWS; OCI needs the same two pieces. Oracle Cloud is a launch partner of
the Open Agent Safety Platform and hosts a growing share of NVIDIA GPU capacity, so
agents running there are an expected population.

Non-goals

• Changing the placeholder model or the gateway/supervisor/sandbox boundary.
• Region or service scoping of signatures (OCI signatures are host-bound, not
  region-scoped, so no signing_service is needed).
• A generic signing abstraction over SigV4 and OCI; two sibling modules are simpler to
  review than a shared one.
• Passphrase-protected private keys (rejected with a clear message; the proxy has nowhere
  safe to source a passphrase).
• Non-commercial realm specifics; they only change hostnames, which the policy already
  controls.
• OCI Vault as a credential driver or OKE as a compute driver; both are gRPC-over-UDS
  extensions that need no upstream change.

Proposal, part 1: credential_signing: oci

Behaviour when an endpoint sets credential_signing: oci (policy YAML or a provider
profile endpoint):

1. TLS terminates as usual for protocol: rest.
2. The proxy strips the client's authorization, date, x-date, x-content-sha256
   and expect headers before the fail-closed placeholder scan, so a client-side attempt
   never leaks upstream.
3. It resolves OCI_KEY_ID and OCI_PRIVATE_KEY from the endpoint-bound provider
   through the existing SecretResolver.
4. It sets date (RFC 7231), computes x-content-sha256 for POST, PUT and PATCH
   bodies, builds the signing string in the OCI SDK's header order, and signs RSA PKCS#1
   v1.5 SHA-256.
5. It injects Authorization: Signature algorithm="rsa-sha256",headers="...",keyId="...",signature="...",version="1"
   and forwards. The host that is signed is the exact host the proxy forwards to.

endpoints:
  - host: "inference.generativeai.*.oci.oraclecloud.com"
    port: 443
    protocol: rest
    credential_signing: oci
    rules:
      - allow: { method: POST, path: "/20231130/actions/chat" }
  - host: "objectstorage.*.oraclecloud.com"
    port: 443
    protocol: rest
    credential_signing: oci
    access: read-write

Design decisions, including the points raised by the triage review on #3960:

• Single-line private key. Provider values reject CR/LF, so OCI_PRIVATE_KEY is
  standard base64 of the PEM file (base64 -w0 < oci_api_key.pem), the documented form.
  Base64 of raw PKCS#8 or PKCS#1 DER and \n-escaped PEM are also accepted.
  Passphrase-protected keys are rejected; the issue's optional
  OCI_PRIVATE_KEY_PASSPHRASE is dropped so issue and PR agree.
• One key id, every principal. OCI_KEY_ID is the API-key triple or an ST$ token,
  so the same signer serves API keys today and minted principals later. Debug output
  never prints the key id, because for principals it is the token.
• signing_service becomes optional for oci. Policy validation and the runtime
  check require it only for the sigv4* values. The server-side credential-source
  precondition is keyed by scheme (OCI_KEY_ID + OCI_PRIVATE_KEY for oci, the AWS
  names for sigv4*).
• Bodies. Signed bodies are buffered up to the same 10 MiB cap as SigV4 and chunked
  bodies are rejected before anything reaches upstream. OCI's own SDKs omit the body
  headers for Object Storage PutObject and UploadPart (enforce_content_headers=False
  in the Python SDK), so an oci:no_body mode mirroring sigv4:no_body is the natural
  follow-up for large uploads. It is left out of feat(sandbox): proxy-side OCI request signing for CONNECT tunnels #3962 to keep the first PR reviewable;
  happy to include it if the community prefers one PR.
• Crypto through the facade. The signer imports the key with
  openshell_crypto::pki::KeyPair::from_pkcs8_der (PKCS#1 input is wrapped in a PKCS#8
  envelope first), signs through the facade key, and hashes bodies with
  openshell_crypto::sha256. No direct aws-lc-rs or sha2 use, so the OpenSSL and
  FIPS backend selections apply to OCI signing too. Tests use a fixture RSA key like the
  existing fixtures in openshell-cli and openshell-server.
• Example profiles (reviewable YAML only, per Remove the inference provider table and provider profile telemetry buckets #3906): oci.yaml (endpointless, pairs
  with credential_binding), oci-object-storage.yaml, oci-genai-native.yaml. Docs:
  oci listed next to sigv4 in the credential_signing field docs and the policy
  skill.

Proposal, part 2: OCI principal refresh strategies

Three strategies added to the ProviderCredentialRefreshStrategy enum after
AWS_STS_ASSUME_ROLE = 6, dispatched in the gateway's provider refresh code next to
mint_aws_sts_assume_role:

Strategy	Where the gateway runs	How the token is minted
oci_instance_principal	OCI Compute	Federate the instance certificate at auth.<region>.oraclecloud.com/v1/x509
oci_resource_principal	OCI Functions and other RPST hosts	Republish the platform-rotated RPST and its session key
oci_oke_workload_identity	OKE enhanced clusters	Exchange the projected service-account token at the OKE proxymux (:12250/resourcePrincipalSessionTokens)

Each mints OCI_KEY_ID = ST$<token> as the primary credential and co-mints
OCI_PRIVATE_KEY (for the two strategies where the gateway generates the session key)
through additional_outputs. Expiry is the token's JWT exp, capped by
max_lifetime_seconds. The sandbox sees placeholders only, and the signing path from
part 1 consumes the pair unchanged.

Responses to the triage review on #3961, to be adopted in #3975 before it leaves draft:

1. Endpoints and paths. feat(providers): gateway-minted OCI principal refresh strategies #3975 already derives the identity endpoints (instance
   metadata, auth.<region>.<realm>/v1/x509, the OKE proxymux) from the environment and
   rejects endpoint material through the configure API (CWE-918, mirroring the STS
   sts_endpoint_url rule); loopback overrides exist only under cfg(test). The
   remaining gap is the resource-principal file paths (rpst_file, private_key_file),
   which move from provider material to gateway configuration before the PR leaves draft.
2. Gateway-level opt-in. To be added: all three strategies hand the gateway's own
   principal to any provider configured with them, and IAM dynamic-group scoping applies
   to the gateway, not to sandboxes. Operators will enable principal minting explicitly
   in gateway configuration; the default is off.
3. Resource principal key. For oci_resource_principal the session key comes from
   the platform; the issue text is corrected.
4. Ephemeral RSA keys go through the facade. Done on 2026-11-04: RSA key generation
   is added to openshell-crypto for the AWS-LC backend (the OpenSSL backend already
   generates RSA keys), and the session key, signing and hashing all go through the
   facade, so the strategies respect backend selection and the dependency guardrail. The
   one non-facade hash is the SHA-1 fingerprint of the instance certificate that OCI
   requires in the <tenancy>/fed-x509/<fingerprint> key id; it is a protocol
   identifier, not an authenticity proof, and is documented as such in CRYPTO.md, like
   the existing WebSocket SHA-1 exception.

Security model

• The sandbox never holds a private key or a token: placeholders only, as today.
• Client-supplied signing headers are stripped before the fail-closed scan.
• The signed host is the forwarded host; policy decides which hosts exist.
• Minting uses the gateway's ambient identity, opt-in, with endpoints from operator
  configuration.
• Debug output and errors carry no key material and never print key ids.
• openshell-crypto owns all cryptographic operations.

Implementation state and verification

• feat(sandbox): proxy-side OCI request signing for CONNECT tunnels #3962 (signing): rebased on current main (v0.1.7) and ported to the crypto facade on
  2026-11-04. Verified: 16 unit and proxy tests; live signer tests against Object Storage
  and native Generative AI with an API-key principal and a session-token principal; a
  full end-to-end run through a gateway and supervisor built from the branch (bucket and
  object lifecycle, native chat, multimodal chat, denials by preset, placeholders only in
  the sandbox). Table in the PR.
• feat(providers): gateway-minted OCI principal refresh strategies #3975 (minting): stacked on feat(sandbox): proxy-side OCI request signing for CONNECT tunnels #3962; wiremock tests pin the OCI SDK wire shapes; full
  suites of six crates pass locally. Not yet verified: a live mint on OCI Compute, OKE or
  Functions, because the development gateway runs on a laptop. The token-plus-key
  transport it produces was proven live in the signing work.
• Both PRs link their issues; CI needs a maintainer /ok to test.

What we ask the community to decide

1. Accept feat(sandbox): proxy-side OCI request signing for CONNECT tunnels (credential_signing: oci) #3960 and feat(providers): add OCI principal refresh strategies (instance, resource, OKE workload identity) #3961 (state:accepted), together, since minted credentials have no
   consumer without signing.
2. Whether an RFC is wanted. If yes, assign the number and I will write it from this
   document using rfc/0000-template.
3. Whether oci:no_body belongs in feat(sandbox): proxy-side OCI request signing for CONNECT tunnels #3962 or in a follow-up.
4. Review order: feat(sandbox): proxy-side OCI request signing for CONNECT tunnels #3962 first, then feat(providers): gateway-minted OCI principal refresh strategies #3975 after it lands.