[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.

A backend authenticates with exactly one credential. X.509 proxies are not supported, so nothing needs a token and a proxy together.

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. get returns one credential, of the kind the backend asks for:

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

class MyTokenProvider:
    async def get(self, requirements: CredentialRequirements) -> BearerToken:
        # requirements.resource is the endpoint asking; requirements.scopes the operation's scopes
        token = await my_token_service.mint(audience=requirements.resource)
        return 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:

from intercede.auth import SSHPrivateKey, StaticCredentials

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, SSHPrivateKey, SSHPassword. Secrets never appear in repr, JSON or error messages.
  • CredentialRequirements, which names the one kind a backend needs, and the CredentialProvider protocol.
  • StaticCredentials. It holds at most one credential of each kind, so it can serve several backends, and each backend gets only the one it asks for. Asking for a kind it does not hold raises an AuthenticationError.
• Requirements (internal): each backend works out the one credential it needs from its config:
  • ARC and HTCondor-CE ask for a token for their endpoint. Their auth field only accepts "token".
  • SSH asks for a key or a password for user@host:port, as its auth field says.
  • Local, cloud and SSH through an agent ask for nothing.
• Freshness (internal): before each operation, a backend asks the provider again only when it has no credential yet, or when its credential expires within 5 minutes. A provider that fails, returns anything other than the requested kind, or returns an expired credential causes 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

155 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.

[Alexander-Auer]

@aldbr I removed the x509 proxy, so I think it's ready for a review

[aldbr]

You can have different tokens for a same backend.
For instance, a token to submit a job with scope compute.create, and another one to get the status with scope compute.read.
I guess that needs to be taken into account here.

[Alexander-Auer]

Fixed with a small CredentialCache in _backends/credentials.py.

Why it exists: is_stale only looks at a credential's kind and expiry, not its scopes, because tokens are opaque to interCEde. A backend that kept a single token would treat one fetched for compute.read as fresh for compute.create, and submit with it without asking the provider.

What it does: it keeps one credential per CredentialRequirements, so each set of scopes gets its own token. Before an operation, a backend calls await cache.fresh(requirements), and the provider is only asked if that credential is missing or about to expire. A provider may mint a token on every call and backends poll often, so this keeps those calls down.

What it doesn't do: it isn't a store of secrets. It holds credentials in memory only, for one backend, until that backend closes. Where they come from and how they are renewed stays with the provider.

No backend in this PR uses it yet. The HTCondor-CE backend (#35) keeps its own dict per scope today, and I plan to switch that and the SSH transport to this.

[aldbr]

Just wondering whether it's necessary (same for HTCondorCEConfig.auth)

[Alexander-Auer]

I removed them, they were indeed not needed