Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
73 commits
Select commit Hold shift + click to select a range
ca745e4
feat: Models the core contract needs
Alexander-Auer Oct 2, 2026
da8fb42
Feat: Protocols and Exceptions added for the core contract
Alexander-Auer Oct 2, 2026
58a5886
Feat: Private protocols for the BatchBackend
Alexander-Auer Oct 2, 2026
135879a
feat: a fake backend to run unit tests against
Alexander-Auer Oct 6, 2026
c97a24d
fix: some code cleanup in the helper functions
Alexander-Auer Oct 6, 2026
a5cda76
feat: setup for the unit test suite
Alexander-Auer Oct 6, 2026
db0683c
chore: style fix
Alexander-Auer Oct 6, 2026
a3eef9a
chore: styling, unit test fixture
Alexander-Auer Oct 6, 2026
f9dbb4c
chore: single letter var `h` refering to hanlde changed to `handle`
Alexander-Auer Oct 6, 2026
9fbd6f0
fix: unused parameter in `test_injected_failure_is_reported_per_job()…
Alexander-Auer Oct 6, 2026
1890fb6
chore: Making room in local fork for my documentation so i can easily…
Alexander-Auer Oct 7, 2026
cad5cea
fix: placed in the wrong folder :/
Alexander-Auer Oct 7, 2026
835c7aa
chore: added testplan
Alexander-Auer Oct 7, 2026
9332673
feat: Models the core contract needs
Alexander-Auer Oct 2, 2026
c77a73c
Feat: Protocols and Exceptions added for the core contract
Alexander-Auer Oct 2, 2026
3171383
Feat: Private protocols for the BatchBackend
Alexander-Auer Oct 2, 2026
0ecafb7
feat: a fake backend to run unit tests against
Alexander-Auer Oct 6, 2026
4c054e5
fix: some code cleanup in the helper functions
Alexander-Auer Oct 6, 2026
d311a91
feat: setup for the unit test suite
Alexander-Auer Oct 6, 2026
9831cab
chore: style fix
Alexander-Auer Oct 6, 2026
cf68d07
chore: styling, unit test fixture
Alexander-Auer Oct 6, 2026
bd78383
chore: single letter var `h` refering to hanlde changed to `handle`
Alexander-Auer Oct 6, 2026
1f185a0
fix: unused parameter in `test_injected_failure_is_reported_per_job()…
Alexander-Auer Oct 6, 2026
8f33853
Merge branch 'feat/core-contract' of github.com:Alexander-Auer/interc…
Alexander-Auer Oct 7, 2026
deeb558
fix: made the OutputSpec optional as it is not suppoerted by all and …
Alexander-Auer Oct 7, 2026
5d18685
Feat: Core contract issue #16 (#1)
Alexander-Auer Oct 7, 2026
51d56e8
fix: These documents should not exist in this way in the main repository
Alexander-Auer Oct 7, 2026
bb1427c
fix: None check for the outputs in submissionspec
Alexander-Auer Oct 7, 2026
aec9426
chore: trailing white spaces
Alexander-Auer Oct 7, 2026
d8d5413
chore: fixed pre commit locally
Alexander-Auer Oct 7, 2026
7be1814
chore: removed pdf, as they just take up space and no one will use th…
Alexander-Auer Oct 9, 2026
a916473
fix: JobHandle key is now a combination of the handle's fields instea…
Alexander-Auer Oct 19, 2026
1e46227
Merge branch 'main' into feat/core-contract
Alexander-Auer Oct 19, 2026
6c13e44
feat: backend configuration and a closed registry
Alexander-Auer Oct 19, 2026
dcf68e0
test: expand unit test coverage to every logical case
Alexander-Auer Oct 20, 2026
b6946d6
feat: credential models and provider-based supply
Alexander-Auer Oct 20, 2026
f046db0
Merge branch 'main' into feat/core-contract
Alexander-Auer Oct 23, 2026
ceb3c21
test: trim the unit tests to logical cases that can happen
Alexander-Auer Oct 23, 2026
9858175
Merge branch 'feat/core-contract' into stack/registry
Alexander-Auer Oct 23, 2026
ef717e2
test: trim the registry and configuration tests to logical cases
Alexander-Auer Oct 23, 2026
a2c106d
Merge branch 'stack/registry' into stack/test-expansion
Alexander-Auer Oct 23, 2026
838578e
test: trim the expanded tests to logical cases that can happen
Alexander-Auer Oct 23, 2026
ce476b9
Merge branch 'stack/test-expansion' into stack/credential-models
Alexander-Auer Oct 23, 2026
1931408
test: trim the credential tests to logical cases that can happen
Alexander-Auer Oct 23, 2026
893ab2d
docs: follow the Diátaxis structure for the user documentation
Alexander-Auer Oct 23, 2026
7b9ca48
fix: address the review of the core contract
Alexander-Auer Oct 23, 2026
aac93fe
Merge branch 'feat/core-contract' into stack/registry
Alexander-Auer Oct 23, 2026
2cfc4dc
fix: no references to the ADRs in the registry and configuration
Alexander-Auer Oct 23, 2026
951de16
Merge branch 'stack/registry' into stack/test-expansion
Alexander-Auer Oct 23, 2026
168bab7
Merge branch 'stack/test-expansion' into stack/credential-models
Alexander-Auer Oct 23, 2026
a1166ea
fix: no references to the ADRs in the credential code
Alexander-Auer Oct 23, 2026
cd4d127
Merge DIRACGrid main into stack/registry (the core contract, squash-m…
Alexander-Auer Oct 26, 2026
7380539
fix: apply the core contract review to the registry
Alexander-Auer Oct 26, 2026
d2a00f9
refactor: rename registry.backend() to get_backend()
Alexander-Auer Oct 26, 2026
055c31e
refactor!: one public configuration model per backend kind
Alexander-Auer Oct 26, 2026
b8fb65f
docs: generate the configuration reference from the models
Alexander-Auer Oct 26, 2026
4e6758f
Merge branch 'stack/registry' into stack/test-expansion
Alexander-Auer Oct 26, 2026
46dc501
test: remove leftovers of the flat configuration model
Alexander-Auer Oct 26, 2026
b068c5e
Merge branch 'stack/test-expansion' into stack/credential-models
Alexander-Auer Oct 26, 2026
3923887
fix: Rename FakeSettings to FakeConfig to stay in line with the revie…
Alexander-Auer Oct 26, 2026
a10537a
Merge remote-tracking branch 'origin/stack/registry' into stack/test-…
Alexander-Auer Oct 27, 2026
24df600
test: keep the existing model tests where they are
Alexander-Auer Oct 27, 2026
dcde224
Merge DIRACGrid main into stack/test-expansion (the registry, squash-…
Alexander-Auer Oct 27, 2026
1514a5b
test: a configuration that is not a mapping is refused
Alexander-Auer Oct 27, 2026
0b79099
Merge branch 'stack/test-expansion' into stack/credential-models
Alexander-Auer Oct 27, 2026
d419ccf
Merge DIRACGrid main into stack/credential-models (the test expansion…
Alexander-Auer Oct 27, 2026
e83c067
fix: credential errors never repeat the value they were given
Alexander-Auer Oct 27, 2026
904138f
fix: a provider's error text stays out of the AuthenticationError
Alexander-Auer Oct 27, 2026
ca1fe28
docs: document the credential fields in the API reference
Alexander-Auer Oct 27, 2026
f104906
docs: Google-style docstrings for the credential functions
Alexander-Auer Oct 27, 2026
031b670
fix: Removed the x509 proxy as it will not be used anymore, and also …
Alexander-Auer Nov 4, 2026
cedffad
Merge branch 'main' into stack/credential-models
Alexander-Auer Nov 4, 2026
11e435b
fix: Added a small credentialcache so each scope can get its own toke…
Alexander-Auer Nov 5, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/user/reference/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,14 @@ Anything else, including every name starting with `_`, is internal.

::: intercede.registry

## Credentials

::: intercede.auth.models

::: intercede.auth.protocols

::: intercede.auth.providers

## Exceptions

::: intercede.exceptions
192 changes: 192 additions & 0 deletions src/intercede/_backends/credentials.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,192 @@
"""What a backend asks its credential provider for, when, and what it accepts back.

``credential_requirements`` turns a configuration into what to ask for. This is
also the one place freshness is decided. A backend holds a ``CredentialCache``,
and before each operation asks it for that operation's credential: the provider
is asked only when there is none yet or it is about to expire. Where credentials
come from, and how they are renewed, stays the consumer's business, inside its
provider.
"""

from __future__ import annotations

from datetime import UTC, datetime, timedelta

from intercede.auth.models import (
BearerToken,
Credential,
CredentialRequirements,
SSHPassword,
SSHPrivateKey,
)
from intercede.auth.protocols import CredentialProvider
from intercede.config import (
ARCConfig,
BackendConfig,
BatchSSHConfig,
HTCondorCEConfig,
)
from intercede.exceptions import AuthenticationError, InterCEdeError

# What each configured SSH auth mode asks the credential provider for.
# "agent" is absent on purpose: an SSH agent holds the key, so nothing is asked.
AUTH_KINDS: dict[str, type[Credential]] = {
"key": SSHPrivateKey,
"password": SSHPassword,
}

# Ask again this long before a credential expires, so it cannot run out in the
# middle of an operation. A library default; whether a provider should be able
# to change it is still open.
DEFAULT_MARGIN = timedelta(minutes=5)


def credential_requirements(
config: BackendConfig, scopes: frozenset[str] = frozenset()
) -> CredentialRequirements | None:
"""Say what a backend must ask its provider for.

Args:
config: The backend's validated configuration.
scopes: The scopes of the operation about to run, for token-based
backends; ignored by the others.

Returns:
What to ask for, or None when the backend needs no credential: it runs
on this host, or an SSH agent holds the key.
"""
if isinstance(config, ARCConfig | HTCondorCEConfig):
# The endpoint is the resource, so a token is minted for this CE's audience.
return CredentialRequirements(
resource=config.endpoint,
kind=BearerToken,
scopes=scopes,
)
if isinstance(config, BatchSSHConfig) and config.auth != "agent":
# The resource is the login, ``user@host:port``: a provider finds the key
# or password by it, and the same host can take different users.
return CredentialRequirements(
resource=f"{config.user}@{config.host}:{config.port}",
kind=AUTH_KINDS[config.auth],
)
return None


def is_stale(
credential: Credential | None,
requirements: CredentialRequirements,
*,
margin: timedelta = DEFAULT_MARGIN,
now: datetime | None = None,
) -> bool:
"""Tell whether ``credential`` cannot serve ``requirements`` for ``margin`` more.

A credential that never expires is never stale. Only the kind and the expiry
are checked, not the scopes, since a token is opaque to interCEde: ``credential``
must have been given for these same requirements, as ``CredentialCache`` ensures.

Args:
credential: The one the backend holds, or None before its first request.
requirements: What the backend needs for the operation about to run.
margin: How long the credential must stay valid from now.
now: The current time; tests pass a fixed one.

Returns:
True when there is no credential yet, when it is of another kind than
required, or when it expires within ``margin``.
"""
if not isinstance(credential, requirements.kind):

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

return True
if credential.expires_at is None:
return False
return credential.expires_at - margin <= (now or datetime.now(UTC))


async def refresh_if_stale(
current: Credential | None,
requirements: CredentialRequirements,
provider: CredentialProvider,
*,
margin: timedelta = DEFAULT_MARGIN,
now: datetime | None = None,
) -> Credential:
"""Return ``current`` while it is fresh, otherwise a new one from ``provider``.

Args:
current: The credential the backend holds, or None before its first request.
requirements: What the backend needs for the operation about to run.
provider: The consumer's provider, asked only when ``current`` is stale.
margin: How long the credential must stay valid from now.
now: The current time; tests pass a fixed one.

Returns:
The credential to authenticate with: ``current``, or the provider's new one.

Raises:
AuthenticationError: The provider failed, returned something other than
the required kind, or returned a credential that has already expired.
Always a failure of the whole operation, never a per-job outcome.
"""
if not is_stale(current, requirements, margin=margin, now=now):
assert current is not None # is_stale() is True for None
return current

try:
fresh = await provider.get(requirements)
except InterCEdeError:
raise # already typed, e.g. an AuthenticationError from the provider
except Exception as exc:
# Only the type: the provider's message may hold a token or a secret URL.
# The exception itself stays available as __cause__.
raise AuthenticationError(
f"the credential provider failed for {requirements.resource} "
f"with {type(exc).__name__}"
) from exc

if not isinstance(fresh, requirements.kind):
raise AuthenticationError(
f"the credential provider returned a {type(fresh).__name__} "
f"for {requirements.resource}, not a {requirements.kind.__name__}"
)
# Expiring within the margin is accepted (it is asked again next time);
# already expired is not, since it cannot authenticate anything.
if is_stale(fresh, requirements, margin=timedelta(0), now=now):
raise AuthenticationError(
f"the credential provider returned an expired credential "
f"for {requirements.resource}"
)
return fresh


class CredentialCache:
"""Keeps one credential per requirements for one backend, so each scope gets its own token.

The provider is asked again only when that credential is missing or about to expire.
"""

def __init__(self, provider: CredentialProvider) -> None:
self._provider = provider
self._held: dict[CredentialRequirements, Credential] = {}

async def fresh(self, requirements: CredentialRequirements) -> Credential:
"""Return the credential for these requirements, asking the provider if needed.

Args:
requirements: What the backend needs for the operation about to run.

Returns:
The credential to authenticate with.

Raises:
AuthenticationError: The provider failed, returned something other than
the required kind, or returned a credential that has already expired.
"""
credential = await refresh_if_stale(
self._held.get(requirements), requirements, self._provider
)
self._held[requirements] = credential
return credential

def clear(self) -> None:
"""Forget every credential, as a backend does when it closes."""
self._held.clear()
11 changes: 9 additions & 2 deletions src/intercede/_backends/fake.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
from typing import Self

from intercede._backends.config import FakeConfig
from intercede.auth.protocols import CredentialProvider
from intercede.exceptions import (
InterCEdeError,
ResourceUnavailableError,
Expand Down Expand Up @@ -94,11 +95,15 @@ def __init__(
self._closed = False

@classmethod
def from_settings(cls, settings: FakeConfig) -> Self:
def from_settings(
cls, settings: FakeConfig, credentials: CredentialProvider
) -> Self:
"""Build the fake from its settings; how the registry constructs it.

Args:
settings: The fake's settings: only the resource it reports.
credentials: Never asked: nothing leaves the process, so the fake
needs no credentials.

Returns:
A new fake, not yet opened.
Expand Down Expand Up @@ -379,4 +384,6 @@ def _write_job_files(
_kill: type[Killable] = FakeBackend
_purge: type[Purgeable] = FakeBackend
_diag: type[Diagnosable] = FakeBackend
_built_by_registry: Callable[[FakeConfig], JobBackend] = FakeBackend.from_settings
_built_by_registry: Callable[[FakeConfig, CredentialProvider], JobBackend] = (
FakeBackend.from_settings
)
28 changes: 28 additions & 0 deletions src/intercede/auth/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
"""Backend credentials: typed, declared, supplied by a provider.

A consumer implements a ``CredentialProvider``, which returns the one credential
a backend asks for. Configuration never holds a secret: it only says how a backend
logs in, and the provider supplies the credential at run time.
"""

from __future__ import annotations

from intercede.auth.models import (
BearerToken,
Credential,
CredentialRequirements,
SSHPassword,
SSHPrivateKey,
)
from intercede.auth.protocols import CredentialProvider
from intercede.auth.providers import StaticCredentials

__all__ = [
"BearerToken",
"Credential",
"CredentialProvider",
"CredentialRequirements",
"SSHPassword",
"SSHPrivateKey",
"StaticCredentials",
]
106 changes: 106 additions & 0 deletions src/intercede/auth/models.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
"""The public credential models a consumer of interCEde can use.

Credentials are immutable values. Secret material is held in pydantic's secret
types, so a credential cannot be printed or logged by accident: ``repr``,
``str`` and JSON all show ``**********``, and the content is only readable on
purpose, with ``get_secret_value()``.
"""

from __future__ import annotations

from typing import Self

from pydantic import (
AwareDatetime,
ConfigDict,
SecretBytes,
SecretStr,
model_validator,
)

from intercede.models import _Model

__all__ = [
"BearerToken",
"Credential",
"CredentialRequirements",
"SSHPassword",
"SSHPrivateKey",
]


# --------------------------------------------------------------------------
# Credential values
# --------------------------------------------------------------------------


class Credential(_Model):
"""Base of every credential: the one field the freshness check needs.

Not used on its own: a provider returns one of the concrete kinds below.
"""

# Added to _Model's settings: a value given by mistake may be the secret
# itself, so no error message repeats one.
model_config = ConfigDict(hide_input_in_errors=True, use_attribute_docstrings=True)

expires_at: AwareDatetime | None = None
"""When the credential stops working, with a timezone, so it can be compared
with the current time. None means it never expires, as for SSH secrets."""


class BearerToken(Credential):
"""A token for the channel to a CE. Opaque to interCEde."""

value: SecretStr
"""The token itself."""


class SSHPrivateKey(Credential):
"""An SSH private key: the key itself, never a path on some host."""

pem: SecretBytes
"""The private key, PEM-encoded."""

passphrase: SecretStr | None = None
"""The passphrase the key is encrypted with, or None if it is not."""


class SSHPassword(Credential):
"""A password for an SSH login."""

value: SecretStr
"""The password itself."""


# --------------------------------------------------------------------------
# What a backend asks for
# --------------------------------------------------------------------------


class CredentialRequirements(_Model):
"""What a backend asks its provider for.

The backend computes it from its own configuration and keeps it to itself:
a consumer only meets it as the argument to its provider's ``get``.
"""

model_config = ConfigDict(use_attribute_docstrings=True)

resource: str
"""Which backend instance is asking: the endpoint it talks to, the same
string as ``JobHandle.resource``. For a token this is also the audience,
in the form that CE expects."""

kind: type[Credential]
"""The kind of credential needed: a backend authenticates with exactly one."""

scopes: frozenset[str] = frozenset()
"""For a token, the scopes of the operation about to run; empty for the
other kinds."""

@model_validator(mode="after")
def _concrete_kind(self) -> Self:
if self.kind is Credential:
raise ValueError("kind must be a concrete kind, not the Credential base")
return self
Loading
Loading