curu-memory 0.2.0__py3-none-any.whl

curu_memory/access.py

@@ -0,0 +1,562 @@
+"""The access store, the roles and the readable spaces of a principal (ADR-016).
+
+`access.sqlite` in the data directory holds the persons, the teams and the members. It
+holds no token and no secret. `role_in` is the one place that gives a role, so each check
+of each transport agrees.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import sqlite3
+import threading
+from collections.abc import Generator, Sequence
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+from curu_memory.ports import GLOBAL, IndexStore, parse_space
+
+READ = 1
+WRITE = 2
+ADMIN = 3
+ROLE_NAMES = {READ: "read", WRITE: "write", ADMIN: "admin"}
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS persons (handle TEXT PRIMARY KEY, owner INTEGER NOT NULL);
+CREATE TABLE IF NOT EXISTS teams (slug TEXT PRIMARY KEY);
+CREATE TABLE IF NOT EXISTS members (
+    slug TEXT NOT NULL REFERENCES teams (slug) ON DELETE CASCADE,
+    handle TEXT NOT NULL REFERENCES persons (handle) ON DELETE CASCADE,
+    PRIMARY KEY (slug, handle)
+);
+CREATE TABLE IF NOT EXISTS agents (
+    name TEXT PRIMARY KEY,
+    person TEXT NOT NULL REFERENCES persons (handle) ON DELETE CASCADE,
+    issuer TEXT NOT NULL,
+    subject TEXT,
+    client_id TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS agents_by_subject ON agents (issuer, subject);
+CREATE UNIQUE INDEX IF NOT EXISTS agents_by_client ON agents (issuer, client_id);
+CREATE TABLE IF NOT EXISTS grants (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    agent TEXT NOT NULL REFERENCES agents (name) ON DELETE CASCADE,
+    space TEXT NOT NULL,
+    role INTEGER NOT NULL,
+    starts TEXT NOT NULL,
+    ends TEXT NOT NULL,
+    revoked TEXT
+);
+"""
+
+#: The default and the longest life of a grant, in days (ADR-016).
+DEFAULT_GRANT_DAYS = 90
+MAX_GRANT_DAYS = 366
+
+
+class AccessRefused(Exception):
+    """The rules refuse a change of the access store. The message says why."""
+
+
+@dataclass(frozen=True)
+class Person:
+    handle: str
+    owner: bool
+    #: The OIDC issuer and subject of the person, or None (spec 012).
+    issuer: str | None = None
+    subject: str | None = None
+
+
+@dataclass(frozen=True)
+class Agent:
+    """A program that acts for one person, with grants that the person issues (ADR-018)."""
+
+    name: str
+    person: str
+    issuer: str
+    subject: str | None = None
+    client_id: str | None = None
+
+
+@dataclass(frozen=True)
+class Grant:
+    id: int
+    agent: str
+    space: str
+    role: int
+    starts: datetime
+    ends: datetime
+    revoked: datetime | None = None
+
+    def live(self, now: datetime) -> bool:
+        return self.revoked is None and self.starts <= now < self.ends
+
+
+@dataclass(frozen=True)
+class Principal:
+    """The caller of a request: a person, an agent, or anonymous with no handle.
+
+    For an agent, `handle` is the person that it acts for, and `agent` is its name.
+    """
+
+    handle: str | None
+    agent: str | None = None
+
+    @classmethod
+    def person(cls, handle: str) -> Principal:
+        return cls(handle)
+
+    @classmethod
+    def for_agent(cls, name: str, acts_for: str) -> Principal:
+        return cls(acts_for, name)
+
+    @property
+    def label(self) -> str:
+        """The name of the principal in the audit log."""
+        if self.agent:
+            return f"agent:{self.agent}"
+        return f"person:{self.handle}" if self.handle else "anonymous"
+
+    @property
+    def acts_for(self) -> str | None:
+        """The person that an agent acts for. None for a person and for anonymous."""
+        return self.handle if self.agent else None
+
+
+ANONYMOUS = Principal(None)
+
+
+def check_handle(handle: str, kind: str = "handle") -> str:
+    """A handle or a team slug: 1 to 40 characters from a to z, 0 to 9 and -, first a letter."""
+    try:
+        parse_space(f"personal/{handle}")
+    except ValueError:
+        raise ValueError(
+            f"the {kind} {handle!r} is not valid. A {kind} has 1 to 40 characters "
+            "from a to z, 0 to 9 and -, and the first character is a letter."
+        ) from None
+    return handle
+
+
+def role_in(person: Person | None, space: str, teams: Sequence[str]) -> int | None:
+    """The role of a person in a space, from the table of ADR-016, or None.
+
+    `teams` holds the slugs of the teams of the person.
+    """
+    if person is None:
+        return None
+    if space == GLOBAL:
+        return ADMIN if person.owner else READ
+    tier, _, name = space.partition("/")
+    if tier == "team":
+        if person.owner:
+            return ADMIN
+        return WRITE if name in teams else None
+    if tier == "personal":
+        # Only the person reads a personal space. An owner does not (ADR-016).
+        return ADMIN if name == person.handle else None
+    return None
+
+
+def readable_spaces_of(
+    principal: Principal, access: AccessStore, index: IndexStore
+) -> tuple[str, ...]:
+    """The spaces where the principal has a role, in name order.
+
+    With no principal, the caller reads `global` only (research R-3). A handle that is
+    not registered, for example a removed person, reads nothing.
+    """
+    if principal.handle is None:
+        return (GLOBAL,)
+    if principal.agent is not None:
+        return _agent_spaces(principal.agent, access)
+    person = access.person(principal.handle)
+    if person is None:
+        return ()
+    teams = access.teams_of(person.handle)
+    candidates = {GLOBAL, f"personal/{person.handle}", *index.spaces()}
+    candidates.update(f"team/{slug}" for slug in access.teams())
+    return tuple(sorted(s for s in candidates if role_in(person, s, teams) is not None))
+
+
+def _agent_spaces(name: str, access: AccessStore) -> tuple[str, ...]:
+    agent = access.agent(name)
+    if agent is None:
+        return ()
+    now = _now()
+    spaces = {g.space for g in access.grants(agent=name) if g.live(now)}
+    return tuple(sorted(s for s in spaces if role_of_agent(agent, s, access, now=now)))
+
+
+def role_of_agent(
+    agent: Agent, space: str, access: AccessStore, *, now: datetime | None = None
+) -> int | None:
+    """The role of an agent in a space: the weaker of its strongest live grant there and
+    the current role of its person (ADR-016, ADR-018)."""
+    now = now or _now()
+    roles = [g.role for g in access.grants(agent=agent.name) if g.space == space and g.live(now)]
+    if not roles:
+        return None
+    person = access.person(agent.person)
+    own = role_in(person, space, access.teams_of(agent.person)) if person else None
+    if own is None:
+        return None
+    return min(max(roles), own)
+
+
+def _now() -> datetime:
+    return datetime.now(UTC)
+
+
+def hidden_space(
+    index: IndexStore,
+    readable: Sequence[str],
+    *,
+    concept_id: str | None = None,
+    sha256: str | None = None,
+) -> str | None:
+    """The space that holds a concept or a media file that the caller cannot read, or None.
+
+    Only the audit log uses it. The caller gets the answer for a missing concept.
+    """
+    for space in index.spaces():
+        if space in readable:
+            continue
+        if concept_id is not None and index.get([space], concept_id) is not None:
+            return space
+        if sha256 is not None and index.media_bytes([space], sha256) is not None:
+            return space
+    return None
+
+
+class AccessStore:
+    """The persons, the teams and the members, in `access.sqlite` of the data directory."""
+
+    def __init__(self, data_dir: Path) -> None:
+        self._path = Path(data_dir) / "access.sqlite"
+        self._lock = threading.Lock()
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    def _connect(self) -> sqlite3.Connection:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        connection = sqlite3.connect(self._path)
+        connection.execute("PRAGMA foreign_keys = ON")
+        connection.executescript(_SCHEMA)
+        columns = {row[1] for row in connection.execute("PRAGMA table_info(persons)")}
+        if "issuer" not in columns:
+            # A store of spec 011 gets the subject link of spec 012 at its next open.
+            connection.executescript(
+                "ALTER TABLE persons ADD COLUMN issuer TEXT;"
+                "ALTER TABLE persons ADD COLUMN subject TEXT;"
+            )
+        connection.execute(
+            "CREATE UNIQUE INDEX IF NOT EXISTS persons_by_subject ON persons (issuer, subject)"
+        )
+        return connection
+
+    def _read(self, sql: str, parameters: Sequence[object] = ()) -> list[tuple]:
+        # A store that does not exist has no person, so a read makes no file.
+        if not self._path.exists():
+            return []
+        with self._lock:
+            connection = self._connect()
+            try:
+                return connection.execute(sql, parameters).fetchall()
+            finally:
+                connection.close()
+
+    @contextlib.contextmanager
+    def _transaction(self) -> Generator[sqlite3.Connection]:
+        """One write transaction. BEGIN IMMEDIATE holds the write lock from the first check,
+        so the checks and the change of two processes do not mix (review of spec 011)."""
+        with self._lock:
+            connection = self._connect()
+            connection.isolation_level = None
+            try:
+                connection.execute("BEGIN IMMEDIATE")
+                try:
+                    yield connection
+                except BaseException:
+                    connection.execute("ROLLBACK")
+                    raise
+                connection.execute("COMMIT")
+            except sqlite3.IntegrityError as error:
+                raise AccessRefused(
+                    f"The change conflicts with the access store: {error}."
+                ) from None
+            finally:
+                connection.close()
+
+    # -- reads ---------------------------------------------------------------
+
+    def persons(self) -> list[Person]:
+        rows = self._read(f"SELECT {_PERSON} FROM persons ORDER BY handle")
+        return [_person(row) for row in rows]
+
+    def person(self, handle: str) -> Person | None:
+        rows = self._read(f"SELECT {_PERSON} FROM persons WHERE handle = ?", (handle,))
+        return _person(rows[0]) if rows else None
+
+    def person_by_subject(self, issuer: str, subject: str) -> Person | None:
+        """The person of a token: its `iss` and `sub` (ADR-015)."""
+        rows = self._read(
+            f"SELECT {_PERSON} FROM persons WHERE issuer = ? AND subject = ?", (issuer, subject)
+        )
+        return _person(rows[0]) if rows else None
+
+    def teams(self) -> tuple[str, ...]:
+        return tuple(row[0] for row in self._read("SELECT slug FROM teams ORDER BY slug"))
+
+    def members(self, slug: str) -> tuple[str, ...]:
+        rows = self._read("SELECT handle FROM members WHERE slug = ? ORDER BY handle", (slug,))
+        return tuple(row[0] for row in rows)
+
+    def teams_of(self, handle: str) -> tuple[str, ...]:
+        rows = self._read("SELECT slug FROM members WHERE handle = ? ORDER BY slug", (handle,))
+        return tuple(row[0] for row in rows)
+
+    # -- changes -------------------------------------------------------------
+
+    def add_person(
+        self,
+        handle: str,
+        *,
+        owner: bool = False,
+        issuer: str | None = None,
+        subject: str | None = None,
+    ) -> Person:
+        check_handle(handle)
+        with self._transaction() as db:
+            if _one(db, "SELECT 1 FROM persons WHERE handle = ?", handle):
+                raise AccessRefused(f"The person {handle!r} exists.")
+            _check_subject_free(db, issuer, subject)
+            # The first person is an owner, so the instance always has one (ADR-016).
+            owner = owner or not _one(db, "SELECT 1 FROM persons")
+            db.execute(
+                "INSERT INTO persons (handle, owner, issuer, subject) VALUES (?, ?, ?, ?)",
+                (handle, int(owner), issuer, subject),
+            )
+        return Person(handle, owner, issuer, subject)
+
+    def link_person(self, handle: str, issuer: str, subject: str) -> None:
+        """Give a person the `iss` and `sub` of their tokens. It replaces an old link."""
+        with self._transaction() as db:
+            if not _one(db, "SELECT 1 FROM persons WHERE handle = ?", handle):
+                raise AccessRefused(f"No person has the handle {handle!r}.")
+            _check_subject_free(db, issuer, subject, handle)
+            db.execute(
+                "UPDATE persons SET issuer = ?, subject = ? WHERE handle = ?",
+                (issuer, subject, handle),
+            )
+
+    def remove_person(self, handle: str) -> None:
+        with self._transaction() as db:
+            row = _one(db, "SELECT owner FROM persons WHERE handle = ?", handle)
+            if row is None:
+                raise AccessRefused(f"No person has the handle {handle!r}.")
+            owners = _one(db, "SELECT count(*) FROM persons WHERE owner = 1")
+            if row[0] and owners is not None and owners[0] == 1:
+                raise AccessRefused(
+                    f"{handle!r} is the last instance owner. Add another owner first."
+                )
+            db.execute("DELETE FROM persons WHERE handle = ?", (handle,))
+
+    def add_team(self, slug: str) -> None:
+        check_handle(slug, "slug")
+        with self._transaction() as db:
+            if _one(db, "SELECT 1 FROM teams WHERE slug = ?", slug):
+                raise AccessRefused(f"The team {slug!r} exists.")
+            db.execute("INSERT INTO teams VALUES (?)", (slug,))
+
+    def remove_team(self, slug: str) -> None:
+        with self._transaction() as db:
+            if not _one(db, "SELECT 1 FROM teams WHERE slug = ?", slug):
+                raise AccessRefused(f"No team has the slug {slug!r}.")
+            db.execute("DELETE FROM teams WHERE slug = ?", (slug,))
+
+    def add_member(self, slug: str, handle: str) -> None:
+        with self._transaction() as db:
+            if not _one(db, "SELECT 1 FROM teams WHERE slug = ?", slug):
+                raise AccessRefused(f"No team has the slug {slug!r}. Add the team first.")
+            if not _one(db, "SELECT 1 FROM persons WHERE handle = ?", handle):
+                raise AccessRefused(f"No person has the handle {handle!r}. Add the person first.")
+            if _one(db, "SELECT 1 FROM members WHERE slug = ? AND handle = ?", slug, handle):
+                raise AccessRefused(f"{handle!r} is already a member of {slug!r}.")
+            db.execute("INSERT INTO members VALUES (?, ?)", (slug, handle))
+
+    # -- agents and grants (spec 013) -------------------------------------------
+
+    def agents(self) -> list[Agent]:
+        rows = self._read(f"SELECT {_AGENT} FROM agents ORDER BY name")
+        return [Agent(*row) for row in rows]
+
+    def agent(self, name: str) -> Agent | None:
+        rows = self._read(f"SELECT {_AGENT} FROM agents WHERE name = ?", (name,))
+        return Agent(*rows[0]) if rows else None
+
+    def agent_by_subject(self, issuer: str, subject: str) -> Agent | None:
+        rows = self._read(
+            f"SELECT {_AGENT} FROM agents WHERE issuer = ? AND subject = ?", (issuer, subject)
+        )
+        return Agent(*rows[0]) if rows else None
+
+    def agent_by_client(self, issuer: str, client_id: str) -> Agent | None:
+        rows = self._read(
+            f"SELECT {_AGENT} FROM agents WHERE issuer = ? AND client_id = ?", (issuer, client_id)
+        )
+        return Agent(*rows[0]) if rows else None
+
+    def add_agent(
+        self,
+        name: str,
+        *,
+        person: str,
+        issuer: str,
+        subject: str | None = None,
+        client_id: str | None = None,
+    ) -> Agent:
+        check_handle(name, "agent name")
+        if (subject is None) == (client_id is None):
+            raise AccessRefused("Give the agent a subject or a client identifier, not both.")
+        with self._transaction() as db:
+            if _one(db, "SELECT 1 FROM agents WHERE name = ?", name):
+                raise AccessRefused(f"The agent {name!r} exists.")
+            if not _one(db, "SELECT 1 FROM persons WHERE handle = ?", person):
+                raise AccessRefused(f"No person has the handle {person!r}. Add the person first.")
+            if subject is not None:
+                _check_subject_free(db, issuer, subject)
+            if client_id is not None and _one(
+                db, "SELECT 1 FROM agents WHERE issuer = ? AND client_id = ?", issuer, client_id
+            ):
+                raise AccessRefused(f"Another agent has the client {client_id!r} of this issuer.")
+            db.execute(
+                "INSERT INTO agents (name, person, issuer, subject, client_id) "
+                "VALUES (?, ?, ?, ?, ?)",
+                (name, person, issuer, subject, client_id),
+            )
+        return Agent(name, person, issuer, subject, client_id)
+
+    def remove_agent(self, name: str) -> None:
+        with self._transaction() as db:
+            if not _one(db, "SELECT 1 FROM agents WHERE name = ?", name):
+                raise AccessRefused(f"No agent has the name {name!r}.")
+            db.execute("DELETE FROM agents WHERE name = ?", (name,))
+
+    def grants(self, *, agent: str | None = None) -> list[Grant]:
+        sql = "SELECT id, agent, space, role, starts, ends, revoked FROM grants"
+        rows = (
+            self._read(sql + " WHERE agent = ? ORDER BY id", (agent,))
+            if agent is not None
+            else self._read(sql + " ORDER BY id")
+        )
+        return [_grant(row) for row in rows]
+
+    def add_grant(
+        self,
+        agent: str,
+        *,
+        space: str,
+        role: int,
+        days: int = DEFAULT_GRANT_DAYS,
+        now: datetime | None = None,
+    ) -> Grant:
+        """Give an agent one role in one space. It cannot be stronger than its person."""
+        if not 1 <= days <= MAX_GRANT_DAYS:
+            raise ValueError(f"a grant lasts from 1 to {MAX_GRANT_DAYS} days, not {days}")
+        if role not in ROLE_NAMES:
+            raise ValueError(f"the role {role!r} is not read, write or admin")
+        parse_space(space)
+        found = self.agent(agent)
+        if found is None:
+            raise AccessRefused(f"No agent has the name {agent!r}.")
+        person = self.person(found.person)
+        own = role_in(person, space, self.teams_of(found.person)) if person else None
+        if own is None or role > own:
+            raise AccessRefused(
+                f"The person {found.person!r} has no role {ROLE_NAMES[role]!r} in {space}, "
+                "and a grant cannot give more than its person has."
+            )
+        starts = now or _now()
+        ends = starts + timedelta(days=days)
+        with self._transaction() as db:
+            cursor = db.execute(
+                "INSERT INTO grants (agent, space, role, starts, ends) VALUES (?, ?, ?, ?, ?)",
+                (agent, space, role, starts.isoformat(), ends.isoformat()),
+            )
+            grant_id = int(cursor.lastrowid or 0)
+        return Grant(grant_id, agent, space, role, starts, ends)
+
+    def revoke_grant(self, grant_id: int, *, now: datetime | None = None) -> Grant:
+        with self._transaction() as db:
+            row = _one(
+                db,
+                "SELECT id, agent, space, role, starts, ends, revoked FROM grants WHERE id = ?",
+                grant_id,
+            )
+            if row is None:
+                raise AccessRefused(f"No grant has the identifier {grant_id}.")
+            when = (now or _now()).isoformat()
+            db.execute(
+                "UPDATE grants SET revoked = COALESCE(revoked, ?) WHERE id = ?", (when, grant_id)
+            )
+        return _grant(row)
+
+    def remove_member(self, slug: str, handle: str) -> None:
+        with self._transaction() as db:
+            if not _one(db, "SELECT 1 FROM members WHERE slug = ? AND handle = ?", slug, handle):
+                raise AccessRefused(f"{handle!r} is not a member of {slug!r}.")
+            db.execute("DELETE FROM members WHERE slug = ? AND handle = ?", (slug, handle))
+
+
+_PERSON = "handle, owner, issuer, subject"
+
+
+_AGENT = "name, person, issuer, subject, client_id"
+
+
+def _grant(row: Sequence[object]) -> Grant:
+    grant_id, agent, space, role, starts, ends, revoked = row
+    return Grant(
+        int(str(grant_id)),
+        str(agent),
+        str(space),
+        int(str(role)),
+        datetime.fromisoformat(str(starts)),
+        datetime.fromisoformat(str(ends)),
+        datetime.fromisoformat(str(revoked)) if revoked else None,
+    )
+
+
+def _person(row: Sequence[object]) -> Person:
+    handle, owner, issuer, subject = row
+    return Person(
+        str(handle),
+        bool(owner),
+        None if issuer is None else str(issuer),
+        None if subject is None else str(subject),
+    )
+
+
+def _check_subject_free(
+    db: sqlite3.Connection, issuer: str | None, subject: str | None, handle: str | None = None
+) -> None:
+    """Refuse a pair of issuer and subject that another person has. `handle` is the person
+    that gets the pair: a pair that this person already has is free for it."""
+    if (issuer is None) != (subject is None):
+        raise AccessRefused("Give the issuer and the subject together.")
+    owner = _one(db, "SELECT handle FROM persons WHERE issuer = ? AND subject = ?", issuer, subject)
+    if issuer is not None and owner is not None and owner[0] != handle:
+        raise AccessRefused(f"Another person has the subject {subject!r} of this issuer.")
+    # A subject of an agent is not free for a person either (ADR-017, ADR-018).
+    if issuer is not None and _one(
+        db, "SELECT 1 FROM agents WHERE issuer = ? AND subject = ?", issuer, subject
+    ):
+        raise AccessRefused(f"An agent has the subject {subject!r} of this issuer.")
+
+
+def _one(connection: sqlite3.Connection, sql: str, *parameters: object) -> tuple | None:
+    return connection.execute(sql, parameters).fetchone()

curu_memory/audit.py

@@ -0,0 +1,63 @@
+"""The audit log: one JSON line for each change of access and each refused read (ADR-016).
+
+A line never holds a token, a question, a concept identifier, a title or media. Each
+line goes to the file with one write in append mode, so the lines of two processes do
+not mix (research R-5).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+
+_LOG = logging.getLogger(__name__)
+FILE_NAME = "audit.jsonl"
+CHANGED = "changed"
+REFUSED = "refused"
+
+
+class AuditLog:
+    def __init__(self, data_dir: Path) -> None:
+        self._path = Path(data_dir) / FILE_NAME
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    def write(
+        self,
+        principal: str,
+        action: str,
+        space: str | None,
+        outcome: str,
+        reason: str,
+        *,
+        subject: str | None = None,
+        acts_for: str | None = None,
+    ) -> None:
+        """Add one line. `subject` is the handle or the slug of a change, never content."""
+        entry = {
+            "time": datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "principal": principal,
+            "acts_for": acts_for,
+            "action": action,
+            "space": space,
+            "outcome": outcome,
+            "reason": reason,
+            "subject": subject,
+        }
+        line = (json.dumps(entry, sort_keys=True, ensure_ascii=False) + "\n").encode()
+        try:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            descriptor = os.open(self._path, os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o600)
+            try:
+                os.write(descriptor, line)
+            finally:
+                os.close(descriptor)
+        except OSError as error:
+            # A failed write must not change the answer of the caller, because the
+            # answer for a hidden concept must be the answer for a missing one.
+            _LOG.error("curu-memory cannot write the audit log %s: %s", self._path, error)

curu_memory/auth.py

@@ -0,0 +1,41 @@
+"""The inbound bearer token of the HTTP transport (research R-9).
+
+The SDK calls `StaticTokenVerifier.verify_token` for each HTTP request. When it
+gives None, the SDK sends HTTP 401 with `WWW-Authenticate: Bearer`, and no tool runs.
+"""
+
+from __future__ import annotations
+
+import hmac
+
+from mcp.server.auth.provider import AccessToken
+from mcp.server.auth.settings import AuthSettings
+
+MIN_TOKEN_LENGTH = 32
+CLIENT_ID = "curu-memory-operator"
+
+# AuthSettings requires an issuer, but a static token has none. With no
+# resource_server_url, the SDK publishes no metadata, so nobody reads this URL.
+PLACEHOLDER_ISSUER = "http://localhost/curu-memory-static-token"
+
+
+class StaticTokenVerifier:
+    """Accept one token, compared in constant time. The token never leaves this object."""
+
+    def __init__(self, token: str) -> None:
+        if len(token) < MIN_TOKEN_LENGTH:
+            raise ValueError(f"The inbound token must have {MIN_TOKEN_LENGTH} characters or more.")
+        self._token = token.encode()
+
+    def __repr__(self) -> str:
+        return "StaticTokenVerifier(token=<hidden>)"
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        if not hmac.compare_digest(token.encode(), self._token):
+            return None
+        # The SDK puts this object in the request context, so it holds no secret.
+        return AccessToken(token="static", client_id=CLIENT_ID, scopes=[])
+
+
+def auth_settings() -> AuthSettings:
+    return AuthSettings(issuer_url=PLACEHOLDER_ISSUER, resource_server_url=None)