lighthouse-cli 0.16.0__py3-none-any.whl

lighthouse/commands/stack.py

@@ -0,0 +1,103 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""`lighthouse stack`: Get my stack, as files in a directory.
+
+    lighthouse stack                                  # what the stack holds
+    lighthouse stack --out ./lighthouse               # every file, written there
+    lighthouse stack --out ./lh --cloud onprem --profile always_on --deployment edge-1
+
+Reads `GET /api/v1/run-targets/stack`, as the person: the stack is a client
+administrator's, at their own keyboard, so the request goes with the
+person's own portal session (`cloudflared access login https://<host>`),
+never a token. With `--out`, each file is written where the portal says it
+goes (`gateway/policy.yaml`, `secrets/aal-reader-public-key`, ...), scripts
+executable; then, on your own servers, `./lighthouse-start.sh` starts it.
+
+**It overwrites nothing** unless `--force`, and it never touches a file the
+stack does not name: the secrets `lighthouse-start.sh` made, and the ones
+you filled in, stay as they are when you fetch a newer stack over an older
+one with `--force`. Nothing it writes is a secret: Atlantic's two public keys
+are public halves.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import stat
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from lighthouse.commands import connect as _connect
+from lighthouse.exits import USAGE, CliError
+from lighthouse.main import Command, Context
+from lighthouse.out import Out
+
+
+def _configure(ap: argparse.ArgumentParser) -> None:
+    ap.add_argument("--cloud", help="aws, azure, gcp or onprem (default: the one chosen)")
+    ap.add_argument("--region", help="the region (default: the one chosen)")
+    ap.add_argument("--profile", help="always_on or ephemeral (default: the one chosen)")
+    ap.add_argument("--deployment",
+                    help="which of your active deployments the files are for")
+    ap.add_argument("--out", help="write every file into this directory")
+    ap.add_argument("--force", action="store_true",
+                    help="overwrite files the stack names that already exist there")
+
+
+def _where(out: Path, name: str) -> Path:
+    """The file's path under `out`. A name is relative and stays inside: the
+    service's answer is trusted to describe files, never to place them."""
+    rel = PurePosixPath(name)
+    if rel.is_absolute() or ".." in rel.parts or not rel.parts:
+        raise CliError(f"the stack names a file outside its directory: {name}", error="refused")
+    return out.joinpath(*rel.parts)
+
+
+def stack(ctx: Context) -> dict[str, Any]:
+    a = ctx.args
+    host = ctx.host
+    params = {k: getattr(a, k) for k in ("cloud", "region", "profile", "deployment")
+              if getattr(a, k)}
+    client = ctx.new_client(host, None, session=_connect.person_session(host))
+    try:
+        body = client.request("GET", "/api/v1/run-targets/stack", params=params) or {}
+    finally:
+        client.close()
+    files = body.get("files") or []
+    rows = [{"name": f.get("name"), "format": f.get("format"), "what": f.get("what"),
+             "written": False} for f in files]
+    out = Path(a.out) if a.out else None
+    if out is not None:
+        targets = [_where(out, str(f.get("name") or "")) for f in files]
+        exists = [str(t) for t in targets if t.exists()]
+        if exists and not a.force:
+            raise CliError(f"{len(exists)} of the stack's files already exist in {out}",
+                           code=USAGE, error="exists",
+                           hint="--force overwrites the files the stack names, and nothing else")
+        for f, target, row in zip(files, targets, rows, strict=True):
+            target.parent.mkdir(parents=True, exist_ok=True)
+            if target.parent.name == "secrets":
+                os.chmod(target.parent, 0o700)
+            target.write_text(str(f.get("content") or ""), encoding="utf-8")
+            if f.get("format") == "shell":
+                target.chmod(target.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+            row["written"] = True
+    start = next((r["name"] for r in rows if r["name"] == "lighthouse-start.sh"), None)
+    return {"ok": True, "cloud": body.get("cloud"), "region": body.get("region"),
+            "profile": body.get("profile"), "infra_ref": body.get("infra_ref"),
+            "out": str(out) if out is not None else None, "files": rows,
+            "next": (f"cd {out} && ./{start}" if out is not None and start else
+                     body.get("applies"))}
+
+
+def _show(out: Out, body: dict[str, Any]) -> None:
+    out.pairs([("where", f"{body['cloud']} {body['region']}"), ("profile", body["profile"]),
+               ("infrastructure", body["infra_ref"]), ("written to", body["out"])])
+    out.table(["file", "kind", "written"],
+              [[r["name"], r["format"], "yes" if r["written"] else "no"] for r in body["files"]])
+    if body.get("next"):
+        out.note(str(body["next"]))
+
+
+COMMANDS = (Command("stack", "Get my stack: the files that run LightHouse where you chose",
+                    _configure, stack, _show),)

lighthouse/commands/terms.py

@@ -0,0 +1,50 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""`lighthouse terms`: the commercial terms in force for this tenant.
+
+    lighthouse terms
+    lighthouse terms --json
+
+Reads `GET /api/v1/billing/terms`: the payment model,
+the credit limit, the payment terms, the margins, the suspension notice, and
+for each one whether it is AAL's published default or something agreed for this
+client, with the version and when it took effect.
+
+**Read only.** Accepting a term is a person's act, recorded against them with
+the version and the time; a token never accepts anything
+(`docs/adr/0012-delegated-credentials.md`). This command exists because a
+developer writing a billing integration needs to read the terms their code must
+honour, not because terms should be changed from a shell.
+"""
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from lighthouse.main import Command, Context
+from lighthouse.out import Out
+
+
+def _configure(ap: argparse.ArgumentParser) -> None:
+    ap.add_argument("--term", help="one term by its key")
+
+
+def terms(ctx: Context) -> dict[str, Any]:
+    body = ctx.client().get("/api/v1/billing/terms")
+    rows = body.get("terms") or []
+    if ctx.args.term:
+        rows = [r for r in rows if r.get("key") == ctx.args.term]
+    return {"ok": True, **body, "terms": rows}
+
+
+def _show(out: Out, body: dict[str, Any]) -> None:
+    out.table(["term", "meaning", "set by", "direction", "version", "in force from"],
+              [[r.get("key"), r.get("label"), (r.get("in_force") or {}).get("set_by"),
+                (r.get("in_force") or {}).get("direction"),
+                (r.get("in_force") or {}).get("version"),
+                (r.get("in_force") or {}).get("effective_from")] for r in body["terms"]])
+    out.note("accepting a term is a person's act, recorded against them in the portal")
+
+
+COMMANDS = (Command("terms", "the commercial terms in force for this tenant",
+                    _configure, terms, _show),)

lighthouse/commands/whoami.py

@@ -0,0 +1,80 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""`lighthouse whoami`: who the CLI is, where, and with what reach.
+
+    lighthouse whoami
+    lighthouse whoami --json
+
+The first thing anybody runs when a pipeline misbehaves, so it answers the four
+questions that matter — which tenant, which person, which role, which scopes —
+and where the credential came from (`keychain` or `environment`) and what kind it
+is (a delegated token or a machine key). It makes one
+request, `GET /api/v1/me`, and exits 3 when there is no credential, so
+`lighthouse whoami >/dev/null || lighthouse login` is a sound idiom.
+"""
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from lighthouse import i18n
+from lighthouse.i18n import t
+from lighthouse.main import Command, Context
+from lighthouse.out import Out
+
+
+def _configure(ap: argparse.ArgumentParser) -> None:
+    ap.add_argument("--profiles", action="store_true",
+                    help="list every host signed in on this machine as well")
+
+
+def whoami(ctx: Context) -> dict[str, Any]:
+    host = ctx.host
+    credential = ctx.store.require(host)
+    me = ctx.client().get("/api/v1/me")
+    # The viewer's effective language (contract 1.29), kept so the next run
+    # speaks it without a request (i18n.py).
+    i18n.remember(ctx.config.path.parent, host, ((me.get("locale") or {}).get("language")))
+    viewer = me.get("viewer") or {}
+    client = me.get("client") or {}
+    out: dict[str, Any] = {
+        "ok": True, "host": host,
+        "tenant": {"name": client.get("name"), "tenant_id": client.get("tenant_id"),
+                   "portal_url": client.get("portal_url")},
+        "viewer": {"email": viewer.get("email"), "name": viewer.get("name"),
+                   "role": viewer.get("role"), "kind": viewer.get("kind"),
+                   "provider": (viewer.get("provider") or {}).get("name")},
+        "credential": credential.redacted(),
+        "contract_revision": me.get("contract_revision"),
+    }
+    if getattr(ctx.args, "profiles", False):
+        out["profiles"] = [{"name": p.name, "host": p.host,
+                            "current": p.name == ctx.config.current}
+                           for p in sorted(ctx.config.profiles.values(), key=lambda p: p.name)]
+    return out
+
+
+def _show(out: Out, body: dict[str, Any]) -> None:
+    credential = body["credential"]
+    out.pairs([("tenant", body["tenant"]["name"]),
+               ("host", body["host"]),
+               ("person", body["viewer"]["email"]),
+               ("role", body["viewer"]["role"]),
+               ("signed in with", body["viewer"]["provider"]),
+               ("scopes", " ".join(credential["scopes"]) or t("whoami.all_reach")),
+               ("credential from", credential["source"]),
+               ("credential kind", t("whoami.machine_key") if credential.get("kind") == "machine"
+                else t("whoami.delegated_token")),
+               ("expires", credential["expires_at"] or (
+                   t("whoami.never_by_time") if credential.get("kind") == "machine" else None))])
+    if credential["source"] == "environment":
+        if credential.get("kind") == "machine":
+            out.note(t("whoami.note_machine_key"))
+        else:
+            out.note(t("whoami.note_delegated_token"))
+    for profile in body.get("profiles") or []:
+        out.say(f"  {'*' if profile['current'] else ' '} {profile['name']}  {profile['host']}")
+
+
+COMMANDS = (Command("whoami", "who this CLI is signed in as, and with what reach",
+                    _configure, whoami, _show),)

lighthouse/config.py

@@ -0,0 +1,141 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Which tenant a command talks to, and the profile file that remembers it.
+
+A LightHouse tenant *is* a hostname: `https://<tenant id>.atlanticagenticlabs.com`
+(`docs/adr/0001-opaque-tenant-ids.md`). So every command needs a host, and
+gets one from the first of these that is set:
+
+1. `--host` on the command line;
+2. `LIGHTHOUSE_HOST` in the environment;
+3. the current profile in `~/.config/lighthouse/config.toml`
+   (`$XDG_CONFIG_HOME` is honoured where it is set);
+4. nothing — and the command says so and stops, rather than guessing.
+
+**The file holds no secrets**: host names, a profile name, and which profile is
+current. Credentials are in the OS keychain (credentials.py). It is written
+with mode 0600 all the same, because it names a company's tenants.
+
+Written as TOML and read with the standard library's `tomllib`, so the CLI
+carries no parser of its own for a file a person may edit by hand.
+"""
+from __future__ import annotations
+
+import os
+import re
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from lighthouse.exits import USAGE, CliError
+from lighthouse.i18n import t
+
+ENV_HOST = "LIGHTHOUSE_HOST"
+ENV_CONFIG = "LIGHTHOUSE_CONFIG"
+DEFAULT_BASE = "atlanticagenticlabs.com"
+# A hostname, nothing else: no scheme, no path, no port. A command that took a
+# URL would let a mistyped one send a credential somewhere unintended.
+_HOST = re.compile(r"^[a-z0-9]([a-z0-9-]{0,62}\.)+[a-z]{2,}$")
+
+
+class NoHost(CliError):
+    def __init__(self) -> None:
+        super().__init__(t("err.no_host"), code=USAGE, error="no_host", hint=t("hint.no_host"))
+
+
+def clean_host(given: str) -> str:
+    """A bare hostname from what a person typed. A URL is accepted and reduced
+    to its host, because everyone pastes one; anything else is refused."""
+    value = (given or "").strip().lower()
+    value = re.sub(r"^https?://", "", value).split("/")[0].split("?")[0]
+    value = value.rsplit(":", 1)[0] if value.count(":") == 1 else value
+    if "." not in value:
+        value = f"{value}.{DEFAULT_BASE}"       # a bare tenant id
+    if not _HOST.match(value):
+        raise CliError(t("err.bad_host", given=repr(given)), code=USAGE, error="bad_host",
+                       hint=t("hint.bad_host"))
+    return value
+
+
+@dataclass
+class Profile:
+    name: str
+    host: str
+
+
+@dataclass
+class Config:
+    path: Path
+    current: str | None = None
+    profiles: dict[str, Profile] = field(default_factory=dict)
+
+    # -- reading ---------------------------------------------------------------
+
+    @classmethod
+    def directory(cls, env: dict[str, str]) -> Path:
+        if env.get(ENV_CONFIG):
+            return Path(env[ENV_CONFIG]).expanduser().parent
+        base = env.get("XDG_CONFIG_HOME") or str(Path(env.get("HOME", "~")) / ".config")
+        return Path(base).expanduser() / "lighthouse"
+
+    @classmethod
+    def load(cls, env: dict[str, str] | None = None) -> Config:
+        env = env if env is not None else dict(os.environ)
+        path = Path(env[ENV_CONFIG]).expanduser() if env.get(ENV_CONFIG) \
+            else cls.directory(env) / "config.toml"
+        if not path.exists():
+            return cls(path)
+        try:
+            data: dict[str, Any] = tomllib.loads(path.read_text())
+        except (OSError, tomllib.TOMLDecodeError) as e:
+            raise CliError(t("err.bad_config", path=path, error=e), error="bad_config",
+                           hint=t("hint.bad_config")) from None
+        profiles = {}
+        for name, row in (data.get("profiles") or {}).items():
+            if isinstance(row, dict) and row.get("host"):
+                profiles[str(name)] = Profile(str(name), clean_host(str(row["host"])))
+        current = data.get("current")
+        return cls(path, str(current) if current else None, profiles)
+
+    # -- writing ---------------------------------------------------------------
+
+    def save(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        lines = []
+        if self.current:
+            lines.append(f'current = "{self.current}"\n')
+        for name in sorted(self.profiles):
+            lines.append(f'\n[profiles."{name}"]\nhost = "{self.profiles[name].host}"\n')
+        self.path.write_text("# Written by `lighthouse`. Host names only: credentials are in "
+                             "the operating system keychain.\n" + "".join(lines))
+        os.chmod(self.path, 0o600)
+
+    def remember(self, host: str, *, name: str | None = None, make_current: bool = True) -> Profile:
+        profile = Profile(name or host.split(".")[0], host)
+        self.profiles[profile.name] = profile
+        if make_current or self.current is None:
+            self.current = profile.name
+        self.save()
+        return profile
+
+    def forget(self, host: str) -> None:
+        for name in [n for n, p in self.profiles.items() if p.host == host]:
+            del self.profiles[name]
+            if self.current == name:
+                self.current = next(iter(sorted(self.profiles)), None)
+        self.save()
+
+    # -- resolution ---------------------------------------------------------------
+
+    def host_for(self, given: str | None, env: dict[str, str] | None = None) -> str:
+        env = env if env is not None else {}
+        if given:
+            return clean_host(given)
+        if env.get(ENV_HOST):
+            return clean_host(env[ENV_HOST])
+        if self.current and self.current in self.profiles:
+            return self.profiles[self.current].host
+        if len(self.profiles) == 1:
+            return next(iter(self.profiles.values())).host
+        raise NoHost()

lighthouse/credentials.py

@@ -0,0 +1,233 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Where the credential lives: the operating system's keychain, and nowhere else.
+
+`lighthouse login` stores the access and refresh tokens through `keyring`, so
+on macOS they are in the login Keychain, on Linux in the Secret Service
+(GNOME Keyring, KWallet) and on Windows in the Credential Locker. **No token is
+ever written to a file**, in the repository or out of it: a dotfile of
+credentials is the thing that ends up committed, copied into a container image,
+or read by every process on a shared machine.
+
+One entry per host, under the service name `lighthouse` and the account name
+`<host>`, so a developer can be signed in to several tenants at once and
+`lighthouse logout --all` can find them all. The profile file
+(`~/.config/lighthouse/config.toml`, config.py) records *which hosts exist* and
+which is current — names, never secrets.
+
+**In CI there is no keychain**, and a pipeline must not be asked to unlock one.
+So `LIGHTHOUSE_TOKEN` is read first and, when it is set, nothing is read from
+or written to the keychain at all. That is the documented way to use this CLI
+in a pipeline: put a token in a masked variable, and the CLI never touches a
+credential store.
+
+**A machine key is the CI credential.** `LIGHTHOUSE_TOKEN` takes either a
+delegated token (`lhat-...`, eight hours, never refreshed under the variable) or
+a machine key (`aalcp-...` from the portal's Keys page: no refresh, and no
+expiry by time). Because every tenant host is behind Cloudflare Access except
+the OAuth endpoints, a pipeline also sets `LIGHTHOUSE_ACCESS_CLIENT_ID` and
+`LIGHTHOUSE_ACCESS_CLIENT_SECRET`, the tenant's Access service token. `login`
+can keep that pair in the keychain beside the delegated token.
+
+If the keychain is unreachable (a headless Linux box with no Secret Service,
+say), the CLI says so and names the environment variable, rather than falling
+back to a file. A silent fallback to disk would be the one behaviour nobody
+would notice and everybody would regret.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field, replace
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+from lighthouse.exits import USAGE, CliError, NotSignedIn
+from lighthouse.i18n import t
+
+log = logging.getLogger(__name__)
+
+SERVICE = "lighthouse"
+ENV_TOKEN = "LIGHTHOUSE_TOKEN"  # noqa: S105  # nosec B105 - a variable name
+# The tenant's Cloudflare Access service token. Every tenant host sits behind
+# Cloudflare Access except the OAuth endpoints, so every other request carries
+# these two as `CF-Access-Client-Id` and `CF-Access-Client-Secret`.
+ENV_ACCESS_ID = "LIGHTHOUSE_ACCESS_CLIENT_ID"
+ENV_ACCESS_SECRET = "LIGHTHOUSE_ACCESS_CLIENT_SECRET"  # noqa: S105  # nosec B105 - a variable name
+MACHINE_PREFIX = "aalcp-"
+# Refresh this long before expiry rather than on the first 401, so a long
+# pipeline does not fail at the moment the token lapses.
+EARLY = timedelta(minutes=5)
+
+
+@dataclass(frozen=True)
+class Credential:
+    host: str
+    access_token: str
+    refresh_token: str | None
+    expires_at: datetime | None
+    email: str | None
+    scopes: tuple[str, ...]
+    source: str = "keychain"        # keychain | environment
+    # The tenant's Cloudflare Access service token, when one is configured.
+    access_client_id: str | None = None
+    access_client_secret: str | None = field(default=None, repr=False)
+
+    @property
+    def kind(self) -> str:
+        """`machine` for a key from the portal's Keys page (`aalcp-...`, never
+        expires by time, never refreshed); `delegated` for a token a person
+        approved (`lhat-...`, eight hours)."""
+        return "machine" if self.access_token.startswith(MACHINE_PREFIX) else "delegated"
+
+    def access(self) -> tuple[str, str] | None:
+        if self.access_client_id and self.access_client_secret:
+            return self.access_client_id, self.access_client_secret
+        return None
+
+    def stale(self, now: datetime | None = None) -> bool:
+        if self.expires_at is None:
+            return False
+        return self.expires_at - EARLY <= (now or datetime.now(UTC))
+
+    def redacted(self) -> dict[str, Any]:
+        """Everything about the credential except the credential."""
+        return {"host": self.host, "email": self.email, "scopes": list(self.scopes),
+                "kind": self.kind, "access_service_token": self.access() is not None,
+                "expires_at": self.expires_at.isoformat() if self.expires_at else None,
+                "source": self.source, "refreshable": self.refresh_token is not None}
+
+
+class KeychainUnavailable(CliError):
+    def __init__(self, detail: str) -> None:
+        super().__init__(f"the operating system keychain is not available: {detail}",
+                         error="keychain_unavailable",
+                         hint=f"in CI, set {ENV_TOKEN} to a machine key instead; "
+                              f"this CLI never writes a credential to a file")
+
+
+def access_from_env(env: dict[str, str]) -> tuple[str, str] | None:
+    """The Access service token named by the environment, or None.
+
+    Both or neither: one without the other can never authenticate, and a CI job
+    that sets half of it should hear so now rather than from Cloudflare later.
+    """
+    client_id = (env.get(ENV_ACCESS_ID) or "").strip()
+    secret = (env.get(ENV_ACCESS_SECRET) or "").strip()
+    if client_id and secret:
+        return client_id, secret
+    if client_id or secret:
+        missing = ENV_ACCESS_SECRET if client_id else ENV_ACCESS_ID
+        raise CliError(t("err.access_token_incomplete", missing=missing),
+                       code=USAGE, error="access_token_incomplete",
+                       hint=t("hint.access_token_incomplete", id=ENV_ACCESS_ID, secret=ENV_ACCESS_SECRET))
+    return None
+
+
+class Store:
+    """The keychain, or the environment. `backend` is injected by the tests;
+    nothing in the test suite touches a real keychain."""
+
+    def __init__(self, backend: Any = None, env: dict[str, str] | None = None) -> None:
+        self._backend = backend
+        self.env = env if env is not None else {}
+
+    # -- the backend ---------------------------------------------------------------
+
+    @property
+    def backend(self) -> Any:
+        if self._backend is None:
+            try:
+                import keyring
+            except Exception as e:                      # pragma: no cover - import failure
+                raise KeychainUnavailable(str(e)) from None
+            self._backend = keyring
+        return self._backend
+
+    def _get(self, host: str) -> str | None:
+        try:
+            got = self.backend.get_password(SERVICE, host)
+            return str(got) if got is not None else None
+        except Exception as e:
+            raise KeychainUnavailable(type(e).__name__) from None
+
+    def _set(self, host: str, blob: str) -> None:
+        try:
+            self.backend.set_password(SERVICE, host, blob)
+        except Exception as e:
+            raise KeychainUnavailable(type(e).__name__) from None
+
+    def _delete(self, host: str) -> None:
+        try:
+            self.backend.delete_password(SERVICE, host)
+        except Exception as e:  # noqa: S110  # nosec B110 - see below
+            # Deleting what is not there is success, and every backend raises a
+            # different exception for it. `logout` must not fail because the
+            # entry had already gone: the point of the command is that nothing
+            # is left, and nothing is.
+            log.debug("nothing to delete from the keychain: %s", type(e).__name__)
+
+    # -- reading and writing ---------------------------------------------------------
+
+    def load(self, host: str) -> Credential | None:
+        """The credential for `host`: the environment first, then the keychain.
+
+        `LIGHTHOUSE_TOKEN` wins and short-circuits: when it is set the keychain
+        is not consulted at all, so a pipeline never prompts for one and a
+        developer can override what is stored for one command.
+        """
+        from_env = access_from_env(self.env)
+        token = (self.env.get(ENV_TOKEN) or "").strip()
+        if token:
+            return Credential(host, token, None, None, None, (), source="environment",
+                              access_client_id=from_env[0] if from_env else None,
+                              access_client_secret=from_env[1] if from_env else None)
+        blob = self._get(host)
+        if not blob:
+            return None
+        try:
+            data = json.loads(blob)
+        except ValueError:
+            log.debug("the stored credential is not readable; treating it as absent")
+            return None
+        expires = data.get("expires_at")
+        cred = Credential(
+            host, data.get("access_token", ""), data.get("refresh_token"),
+            datetime.fromisoformat(expires) if expires else None,
+            data.get("email"), tuple(data.get("scopes") or ()),
+            access_client_id=data.get("access_client_id"),
+            access_client_secret=data.get("access_client_secret"))
+        if from_env:                # the environment overrides what was stored
+            cred = replace(cred, access_client_id=from_env[0], access_client_secret=from_env[1])
+        return cred
+
+    def save(self, host: str, token: dict[str, Any], *, email: str | None = None,
+             now: datetime | None = None, access_client_id: str | None = None,
+             access_client_secret: str | None = None) -> Credential:
+        """Store what the token endpoint returned. `expires_in` is turned into
+        an absolute time here, so a credential read tomorrow is not believed."""
+        now = now or datetime.now(UTC)
+        expires = now + timedelta(seconds=int(token.get("expires_in") or 0)) \
+            if token.get("expires_in") else None
+        cred = Credential(host, str(token["access_token"]), token.get("refresh_token"),
+                          expires, email, tuple((token.get("scope") or "").split()),
+                          access_client_id=access_client_id,
+                          access_client_secret=access_client_secret)
+        blob = {
+            "access_token": cred.access_token, "refresh_token": cred.refresh_token,
+            "expires_at": cred.expires_at.isoformat() if cred.expires_at else None,
+            "email": cred.email, "scopes": list(cred.scopes)}
+        if cred.access():
+            blob["access_client_id"] = cred.access_client_id
+            blob["access_client_secret"] = cred.access_client_secret
+        self._set(host, json.dumps(blob))
+        return cred
+
+    def forget(self, host: str) -> None:
+        self._delete(host)
+
+    def require(self, host: str) -> Credential:
+        cred = self.load(host)
+        if cred is None or not cred.access_token:
+            raise NotSignedIn(host)
+        return cred