[Alexander-Auer]

feat: credentials (models, provider, freshness)

Part of #17. Follows #29 (merged).

Backends get their credentials from a provider that the consumer owns. Configuration never holds a secret.

How a consumer uses it

The consumer supplies the credentials: it creates a CredentialProvider, passes it to get_backend, and closes it when done. interCEde only decides when to ask, never where credentials come from, and never closes the provider.

A provider is any object with an async get method and async with support:

from intercede import registry
from intercede.auth import BearerToken, CredentialRequirements, CredentialSet

class MyTokenProvider:
    async def get(self, requirements: CredentialRequirements) -> CredentialSet:
        # requirements.resource is the endpoint asking; requirements.scopes the operation's scopes
        token = await my_token_service.mint(audience=requirements.resource)
        return CredentialSet([BearerToken(value=token.value, expires_at=token.expires_at)])

    async def __aenter__(self): return self
    async def __aexit__(self, *exc): ...

async with MyTokenProvider() as credentials:
    async with registry.get_backend(config, credentials) as ce:
        await ce.submit(spec, copies)

For fixed credentials, for example a key read from a file, the consumer can use StaticCredentials instead of writing a provider:

async with StaticCredentials([SSHPrivateKey(pem=key_bytes)]) as credentials:
    ...

One provider can be shared by every backend the consumer drives.

What's added

• intercede.auth (public):
  • Credential types: BearerToken, X509Proxy, SSHPrivateKey, SSHPassword. Secrets never appear in repr, JSON or error messages.
  • CredentialSet, CredentialRequirements and the CredentialProvider protocol.
  • StaticCredentials.
• Requirements (internal): each backend works out what to ask for from its config's auth field:
  • ARC and HTCondor-CE ask for a token, and optionally a proxy, for their endpoint.
  • SSH asks for a key or a password for user@host:port.
  • Local, cloud and SSH through an agent ask for nothing.
• Freshness (internal): before each operation, a backend asks the provider again only when a credential is missing or expires within 5 minutes. Any provider failure becomes an AuthenticationError for the whole operation, never a per-job failure.
• Registry: get_backend(config, credentials) passes the provider to backends and transports. Anything that isn't a provider raises a ConfigurationError. Building a backend never calls the provider.

Breaking change

registry.get_backend(config) now takes a second argument, credentials.

Open points

• There is no credential type for cloud API keys yet.
• Should a provider be able to change the 5-minute margin?

Tests

157 tests pass on Python 3.11 and 3.13, with 99% coverage. test_credentials.py imports intercede._backends.credentials directly, because no real backend uses it yet.