terp-cap-mfa 0.27.0__tar.gz

terp_cap_mfa-0.27.0/.gitignore

@@ -0,0 +1,73 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.venv-*/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# uv
+uv.lock
+
+# Node
+node_modules/
+.pnpm-store/
+*.tsbuildinfo
+
+# Playwright (conformance e2e) artifacts
+test-results/
+playwright-report/
+blob-report/
+playwright/.cache/
+.last-run.json
+
+# Local frontend template render checks
+apps/example/_frontend_tpl_check/
+
+# Editor / OS
+.DS_Store
+.idea/
+*.local
+
+# Local environment overrides — never commit (a real .env may hold SECRET_KEY).
+# The tracked template is `.env.example`.
+.env
+.env.*
+!.env.example
+!.env.example.jinja
+# Rendered app-declared variables (environment.schema.json) — may hold secrets.
+.app.env
+# Per-service renders (a declaration scoped with "services"). A SEPARATE pattern
+# because `.app.env` above is an exact name, not a glob: it does not match
+# `.app.worker.env`, so without this line the one file that exists to hold a single
+# worker's credentials would be the one file in the seam that gets committed.
+# `.app.env.example` stays tracked -- it does not end in `.env`, so neither line
+# claims it.
+.app.*.env
+# `terp smoke`'s throwaway database. Left in place deliberately after a failure — it is
+# the state the chain died on — so it must not show up as an untracked file.
+.terp-smoke.db
+
+# graphify: a knowledge graph an agent builds FROM this repository. Derived
+# data that is rebuilt on demand and goes stale the moment the code moves.
+graphify-out/
+
+# Playwright browsers recorded to a repo-local path. Needed rather than optional on
+# Windows: the default location under %LOCALAPPDATA% is refused execution by Group
+# Policy on a managed machine ("spawn UNKNOWN" with the binary present and complete),
+# so recording the win32 half of a baseline pair requires PLAYWRIGHT_BROWSERS_PATH
+# pointing somewhere policy allows. 700MB, and nothing in the repo should ever carry it.
+apps/workbench/.playwright-browsers/
+
+# Agent-session git worktrees. Local scratch checkouts of this repository, so a `git add -A`
+# would otherwise stage them as embedded repositories — which it did once, and the commit had
+# to be amended.
+.claude/worktrees/

terp_cap_mfa-0.27.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.5
+Name: terp-cap-mfa
+Version: 0.27.0
+Summary: Terp MFA capability — a TOTP second factor with recovery codes, sealed at rest and recorded in the token that results.
+Project-URL: Repository, https://github.com/AITT-NL/terp-framework
+Project-URL: Changelog, https://github.com/AITT-NL/terp-framework/blob/main/CHANGELOG.md
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: cryptography>=50
+Requires-Dist: terp-core==0.27.0

terp_cap_mfa-0.27.0/escape-hatch-budget.json

@@ -0,0 +1,3 @@
+{
+  "arch-allow-schemas-exclude-sensitive-fields": 1
+}

terp_cap_mfa-0.27.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "terp-cap-mfa"
+version = "0.27.0"
+description = "Terp MFA capability — a TOTP second factor with recovery codes, sealed at rest and recorded in the token that results."
+requires-python = ">=3.13"
+license = "Apache-2.0"
+dependencies = [
+    "terp-core==0.27.0",
+    # The enrolment secret is sealed at rest with the same Fernet-over-HKDF shape the
+    # webhooks capability uses for its signing secret, under an MFA-specific label.
+    "cryptography>=50",
+]
+
+# A LIBRARY capability: it owns tables and a router, and declares NO `terp.capabilities`
+# auto-discovery entry point. A second factor is not something an application should
+# acquire by installing a package — the login route has to consult it, which is an
+# explicit wiring decision (`build_login_module(second_factor=...)`), and mounting
+# enrolment in an app whose login never checks a factor would publish a control that
+# does nothing.
+
+# Owns the `mfa_enrolment` and `mfa_recovery_code` tables, so it ships an independent,
+# linear Alembic history (its own `alembic_version_mfa` table). `terp migrate` discovers
+# this via the `terp.migrations` group (ADR 0027).
+[project.entry-points."terp.migrations"]
+mfa = "terp.capabilities.mfa"
+
+# PEP 420 namespace package: this distribution owns only `terp.capabilities.mfa`.
+[tool.hatch.build.targets.wheel]
+sources = ["src"]
+only-include = ["src/terp/capabilities/mfa"]
+
+# Where this package comes from. The shipped changelog (`terp guide changelog`)
+# ends at the installed version; the notes for a release you do not have yet
+# live at these URLs, which `pip show` and the index page both surface.
+[project.urls]
+Repository = "https://github.com/AITT-NL/terp-framework"
+Changelog = "https://github.com/AITT-NL/terp-framework/blob/main/CHANGELOG.md"

terp_cap_mfa-0.27.0/src/terp/capabilities/mfa/__init__.py

@@ -0,0 +1,105 @@
+"""terp.capabilities.mfa — a TOTP second factor, with recovery codes (ADR 0151).
+
+Authentication in this platform was password-only, with OIDC as the single way to
+delegate a second factor to somebody else's identity provider. An application whose most
+dangerous surface is reached by an ordinary admin password — the parameters and
+credential references that touch production systems — had no answer to offer.
+
+This capability is that answer, and it is deliberately the smaller half of one:
+
+* :mod:`~terp.capabilities.mfa.totp` implements RFC 6238 on the standard library, and is
+  held to the specification's own **test vectors** rather than to its author's
+  confidence.
+* :mod:`~terp.capabilities.mfa.sealing` seals the shared secret at rest under an
+  MFA-specific HKDF label. The secret *is* the factor and is never rotated by the person
+  who owns it, so a plaintext leak hands over every enrolled account silently.
+* :mod:`~terp.capabilities.mfa.recovery` issues single-use recovery codes, shown once and
+  stored as digests — because a second factor with no way back in is a way to lose an
+  account, and the support process that grows around that gap is weaker than the factor.
+* The self-scoped router at ``/api/v1/mfa`` sets a factor up, proves it, reports it and
+  removes it. Every route acts on the caller's own account and none takes a subject id.
+
+**Enrolment is two steps on purpose.** A secret is issued, and gates nothing until a code
+generated from it comes back. A secret that was mis-scanned and treated as live is a
+lockout at the next login, which is the failure that makes people turn the feature off.
+
+A **library** capability: it declares no ``terp.capabilities`` auto-discovery entry point.
+A second factor is not something an app should acquire by installing a package — the
+login route has to consult it, which is an explicit wiring decision — and mounting
+enrolment in an app whose login never checks a factor would publish a control that does
+nothing.
+"""
+
+from __future__ import annotations
+
+from terp.capabilities.mfa.models import MfaEnrolment, MfaRecoveryCode
+from terp.capabilities.mfa.operations import (
+    MFA_CONFIRM,
+    MFA_DISABLE,
+    MFA_ENROL,
+    MFA_OPERATIONS,
+    MFA_STATUS,
+)
+from terp.capabilities.mfa.recovery import CODE_COUNT, generate_codes
+from terp.capabilities.mfa.router import (
+    DEFAULT_ISSUER,
+    active_mfa_issuer,
+    build_mfa_module,
+    configure_mfa_issuer,
+    module,
+    reset_mfa_issuer,
+    router,
+)
+from terp.capabilities.mfa.schemas import (
+    MfaCodeRequest,
+    MfaEnrolmentCreate,
+    MfaEnrolmentRead,
+    MfaEnrolmentUpdate,
+    MfaSecretIssued,
+    MfaStatusRead,
+)
+from terp.capabilities.mfa.sealing import (
+    MfaSecretError,
+    is_sealed_secret,
+    seal_secret,
+    unseal_secret,
+)
+from terp.capabilities.mfa.service import (
+    MfaAlreadyEnrolledError,
+    MfaCodeInvalidError,
+    MfaNotEnrolledError,
+    MfaService,
+)
+
+__all__ = [
+    "CODE_COUNT",
+    "DEFAULT_ISSUER",
+    "MFA_CONFIRM",
+    "MFA_DISABLE",
+    "MFA_ENROL",
+    "MFA_OPERATIONS",
+    "MFA_STATUS",
+    "MfaAlreadyEnrolledError",
+    "MfaCodeInvalidError",
+    "MfaCodeRequest",
+    "MfaEnrolment",
+    "MfaEnrolmentCreate",
+    "MfaEnrolmentRead",
+    "MfaEnrolmentUpdate",
+    "MfaNotEnrolledError",
+    "MfaRecoveryCode",
+    "MfaSecretError",
+    "MfaSecretIssued",
+    "MfaService",
+    "MfaStatusRead",
+    "active_mfa_issuer",
+    "build_mfa_module",
+    "configure_mfa_issuer",
+    "generate_codes",
+    "is_sealed_secret",
+    "module",
+    "reset_mfa_issuer",
+    "router",
+    "seal_secret",
+    "unseal_secret",
+]

terp_cap_mfa-0.27.0/src/terp/capabilities/mfa/migrations/versions/a3f9c1e7b204_create_mfa_tables.py

@@ -0,0 +1,75 @@
+"""create mfa enrolment and recovery-code tables
+
+Revision ID: a3f9c1e7b204
+Revises:
+Create Date: 2026-09-18 15:10:00.000000
+
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'a3f9c1e7b204'
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'mfa_enrolment',
+        sa.Column('id', sa.Uuid(), nullable=False),
+        sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+        sa.Column('version', sa.Integer(), nullable=False),
+        sa.Column('user_id', sa.Uuid(), nullable=False),
+        sa.Column('secret', sqlmodel.sql.sqltypes.AutoString(length=512), nullable=False),
+        sa.Column('confirmed_at', sa.DateTime(timezone=True), nullable=True),
+        sa.Column('last_used_step', sa.Integer(), nullable=True),
+        sa.PrimaryKeyConstraint('id'),
+    )
+    op.create_index(op.f('ix_mfa_enrolment_user_id'), 'mfa_enrolment', ['user_id'], unique=True)
+    # Indexed because the login path asks "is this subject enrolled and live?" on every
+    # attempt, and a started-but-unconfirmed row must not answer yes.
+    op.create_index(
+        op.f('ix_mfa_enrolment_confirmed_at'), 'mfa_enrolment', ['confirmed_at'], unique=False
+    )
+
+    op.create_table(
+        'mfa_recovery_code',
+        sa.Column('id', sa.Uuid(), nullable=False),
+        sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+        sa.Column('version', sa.Integer(), nullable=False),
+        sa.Column('enrolment_id', sa.Uuid(), nullable=False),
+        sa.Column('code_hash', sqlmodel.sql.sqltypes.AutoString(length=64), nullable=False),
+        sa.Column('used_at', sa.DateTime(timezone=True), nullable=True),
+        # CASCADE: a recovery code is a PART of its enrolment, so disabling the factor
+        # destroys the codes with it and leaves nothing usable behind.
+        sa.ForeignKeyConstraint(['enrolment_id'], ['mfa_enrolment.id'], ondelete='CASCADE'),
+        sa.PrimaryKeyConstraint('id'),
+    )
+    op.create_index(
+        op.f('ix_mfa_recovery_code_enrolment_id'),
+        'mfa_recovery_code',
+        ['enrolment_id'],
+        unique=False,
+    )
+    op.create_index(
+        op.f('ix_mfa_recovery_code_code_hash'), 'mfa_recovery_code', ['code_hash'], unique=False
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(op.f('ix_mfa_recovery_code_code_hash'), table_name='mfa_recovery_code')
+    op.drop_index(op.f('ix_mfa_recovery_code_enrolment_id'), table_name='mfa_recovery_code')
+    op.drop_table('mfa_recovery_code')
+    op.drop_index(op.f('ix_mfa_enrolment_confirmed_at'), table_name='mfa_enrolment')
+    op.drop_index(op.f('ix_mfa_enrolment_user_id'), table_name='mfa_enrolment')
+    op.drop_table('mfa_enrolment')

terp_cap_mfa-0.27.0/src/terp/capabilities/mfa/models.py

@@ -0,0 +1,86 @@
+"""The two tables a second factor needs: one enrolment per subject, and its recovery codes.
+
+``MfaEnrolment`` is keyed by ``user_id`` and **unique** on it. One subject has one second
+factor: a second row would mean two secrets both valid, which is a factor that cannot be
+revoked by replacing it.
+
+``confirmed_at`` is what separates a *started* enrolment from a *live* one, and it is the
+reason enrolment is two steps rather than one. A secret issued but never proved is not a
+second factor — the person may have mistyped it into their authenticator, or scanned
+nothing at all — and treating it as live would lock them out of their own account at the
+next login. So the row exists from the moment the secret is issued (it has to: the server
+must remember what it offered), and it gates nothing until a code generated from it comes
+back.
+
+``MfaRecoveryCode`` holds one row per issued code, storing a digest and never the code.
+``used_at`` stamps consumption rather than deleting the row: a spent recovery code is
+something an operator wants to see in the trail, and a deleted row answers no questions.
+The reference to the enrolment declares ``CASCADE`` because a recovery code is a *part*
+of its enrolment — disabling the factor destroys the codes with it, which is the one
+behaviour that leaves nothing usable behind.
+"""
+
+from __future__ import annotations
+
+import datetime
+import uuid
+from typing import Final
+
+from sqlalchemy import DateTime
+from sqlmodel import Field
+
+from terp.core import BaseTable, OnDelete, Ref
+
+from terp.capabilities.mfa.recovery import CODE_HASH_LENGTH
+
+#: Caps every caller-independent string column. The secret is sealed before it is
+#: stored, and Fernet output is comfortably inside this.
+SECRET_MAX: Final[int] = 512
+
+
+class MfaEnrolment(BaseTable, table=True):
+    """One subject's second factor: the sealed shared secret and whether it is live.
+
+    ``id`` / ``created_at`` / ``updated_at`` / ``version`` are inherited from
+    ``BaseTable``. ``secret`` is **never** serialised out of the API boundary — no read
+    DTO carries it, and the enrolment response returns the plaintext exactly once, at
+    the moment it is generated, because an authenticator app has to be given it.
+    """
+
+    __tablename__ = "mfa_enrolment"
+
+    user_id: uuid.UUID = Field(index=True, unique=True)
+    secret: str = Field(max_length=SECRET_MAX)
+    #: ``None`` until a code generated from the secret comes back. A started enrolment
+    #: gates nothing; see the module docstring for why that is not an oversight.
+    confirmed_at: datetime.datetime | None = Field(  # type: ignore[call-overload]
+        default=None,
+        sa_type=DateTime(timezone=True),
+        nullable=True,
+        index=True,
+    )
+
+    #: The TOTP step a successful verification last spent. A code is valid for its whole
+    #: window, so without this the same six digits authenticate again for as long as that
+    #: window lasts -- ninety seconds at the default drift -- and anyone who saw them once
+    #: can use them. RFC 6238 section 5.2 puts the duty to refuse the second use on the
+    #: verifier, and this column is the verifier's memory. ``None`` until the first
+    #: successful verification, which is also why it cannot be inferred from ``updated_at``.
+    last_used_step: int | None = Field(default=None, nullable=True)
+
+
+class MfaRecoveryCode(BaseTable, table=True):
+    """One single-use recovery code, stored as a digest and stamped when spent."""
+
+    __tablename__ = "mfa_recovery_code"
+
+    enrolment_id: uuid.UUID = Ref("mfa_enrolment.id", on_delete=OnDelete.CASCADE, index=True)
+    code_hash: str = Field(max_length=CODE_HASH_LENGTH, index=True)
+    used_at: datetime.datetime | None = Field(  # type: ignore[call-overload]
+        default=None,
+        sa_type=DateTime(timezone=True),
+        nullable=True,
+    )
+
+
+__all__ = ["SECRET_MAX", "MfaEnrolment", "MfaRecoveryCode"]

terp_cap_mfa-0.27.0/src/terp/capabilities/mfa/operations.py

@@ -0,0 +1,41 @@
+"""Operation declarations for the ``mfa`` capability's self-scoped routes.
+
+Each route declares what it does in plain English (ADR 0102), so a non-technical reader
+sees the effect of setting up, proving, inspecting or removing a second factor without
+reading HTTP verbs and paths.
+"""
+
+from __future__ import annotations
+
+from terp.core import OperationDefinition
+
+MFA_STATUS = OperationDefinition(
+    id="mfa.status", label="Check whether a second factor is set up"
+)
+MFA_ENROL = OperationDefinition(
+    id="mfa.enrol", label="Start setting up a second factor"
+)
+MFA_CONFIRM = OperationDefinition(
+    id="mfa.confirm", label="Finish setting up a second factor"
+)
+MFA_DISABLE = OperationDefinition(id="mfa.disable", label="Remove the second factor")
+
+#: Every operation this capability's routes declare, in declaration order.
+#:
+#: An app folds the capability into its :class:`~terp.core.OperationCatalog` by splatting
+#: this (``*MFA_OPERATIONS``) rather than naming each constant, so a release that adds a
+#: route here cannot refuse a ``STRICT`` app's boot (ADR 0126).
+MFA_OPERATIONS: tuple[OperationDefinition, ...] = (
+    MFA_STATUS,
+    MFA_ENROL,
+    MFA_CONFIRM,
+    MFA_DISABLE,
+)
+
+__all__ = [
+    "MFA_CONFIRM",
+    "MFA_DISABLE",
+    "MFA_ENROL",
+    "MFA_OPERATIONS",
+    "MFA_STATUS",
+]

terp_cap_mfa-0.27.0/src/terp/capabilities/mfa/recovery.py

@@ -0,0 +1,88 @@
+"""Recovery codes: the way back in when the phone is gone.
+
+A second factor that cannot be recovered is a way to lose an account, and the support
+process that grows around that gap — "ring us and we will turn it off" — is a social-
+engineering surface far weaker than the factor it rescues. So enrolment issues a fixed
+set of single-use codes, shown once.
+
+Three properties, each of which is the whole point of that property:
+
+* **Shown once, stored hashed.** The row holds ``sha256`` of the code, never the code.
+  A plain hash is right here and a slow KDF would be wrong: these are 80-bit random
+  strings this module generated, not human-chosen passwords, so there is no dictionary
+  to mount and nothing for a work factor to buy. (The enrolment *secret* is sealed
+  rather than hashed for the opposite reason — verification needs to reproduce it.)
+* **Single use.** A code that still worked after being used is a password with extra
+  steps. Consumption stamps the row, and the stamped row stays for the trail.
+* **Constant-time comparison**, over every stored code. Hashes make timing much less
+  interesting than it is for the TOTP code, but the loop costs nothing and the habit is
+  the thing that survives a later change to the format.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import secrets
+from typing import Final
+
+#: How many codes an enrolment issues. Ten is the common default: enough that losing a
+#: printout is survivable, few enough that a person keeps them somewhere deliberate.
+CODE_COUNT: Final[int] = 10
+
+#: Bytes of entropy per code (80 bits), rendered as base32 without padding.
+_CODE_BYTES: Final[int] = 10
+
+#: The stored digest's width, mirrored by the column cap.
+CODE_HASH_LENGTH: Final[int] = 64
+
+
+def generate_codes(count: int = CODE_COUNT) -> list[str]:
+    """*count* fresh recovery codes, in the form the person is shown once.
+
+    Grouped with a hyphen because these get written down and read back by hand, and an
+    unbroken sixteen-character string is where transcription errors come from.
+    """
+    codes: list[str] = []
+    for _ in range(count):
+        raw = base32(secrets.token_bytes(_CODE_BYTES))
+        codes.append(f"{raw[:4]}-{raw[4:8]}-{raw[8:12]}-{raw[12:16]}")
+    return codes
+
+
+def base32(value: bytes) -> str:
+    """Unpadded, upper-case base32 — the alphabet people can read back reliably."""
+    import base64
+
+    return base64.b32encode(value).decode("ascii").rstrip("=")
+
+
+def normalise(code: str) -> str:
+    """The comparable form of a typed code: no spaces or hyphens, upper-case.
+
+    People retype these from paper, so the separators and the case are presentation
+    rather than content. Normalising at the boundary keeps that judgement in one place
+    instead of at every comparison.
+    """
+    return code.strip().replace("-", "").replace(" ", "").upper()
+
+
+def hash_code(code: str) -> str:
+    """The stored digest of *code*."""
+    return hashlib.sha256(normalise(code).encode("utf-8")).hexdigest()
+
+
+def matches(code: str, stored_hash: str) -> bool:
+    """Whether *code* hashes to *stored_hash*, compared in constant time."""
+    return hmac.compare_digest(hash_code(code), stored_hash)
+
+
+__all__ = [
+    "CODE_COUNT",
+    "CODE_HASH_LENGTH",
+    "base32",
+    "generate_codes",
+    "hash_code",
+    "matches",
+    "normalise",
+]

terp_cap_mfa-0.27.0/src/terp/capabilities/mfa/router.py

@@ -0,0 +1,194 @@
+"""The self-scoped second-factor router: set one up, prove it, inspect it, remove it.
+
+Every route here acts on **the caller's own** account, read from the authenticated
+principal. None takes a subject id, so none can be turned into a way to enrol, inspect or
+disable somebody else's factor — the shape ``GET /me`` uses, and for the same reason: an
+id parameter on a self-scoped route is an object-level authorization bug waiting for the
+first person who tries another id.
+
+Mounted at the VIEWER tier for both reads and writes: any authenticated caller manages
+their own factor, because a read-only account is not a second-class one.
+There is deliberately no administrative *disable* route. An operator who can turn off
+somebody else's second factor is the weakest link in the control, and support-desk
+disabling is the social-engineering path that defeats MFA in practice — a person who has
+lost their phone uses a recovery code, which is why the enrolment issues them.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+from fastapi import APIRouter, Depends
+
+from terp.core import (
+    AuthenticationError,
+    ModuleSpec,
+    Policy,
+    Principal,
+    Roles,
+    SessionDep,
+    get_principal,
+    operation,
+)
+
+from terp.capabilities.mfa.operations import (
+    MFA_CONFIRM,
+    MFA_DISABLE,
+    MFA_ENROL,
+    MFA_STATUS,
+)
+from terp.capabilities.mfa.schemas import (
+    MfaCodeRequest,
+    MfaEnrolmentRead,
+    MfaSecretIssued,
+    MfaStatusRead,
+)
+from terp.capabilities.mfa.service import MfaService
+
+router = APIRouter(tags=["mfa"])
+_service = MfaService()
+
+#: The label an authenticator app shows beside the generated codes. A person may hold
+#: accounts in several systems, and the issuer is the only thing distinguishing one
+#: six-digit row from another, so it is the deployment's own name — the framework cannot
+#: know it and declines to guess, defaulting to its own name rather than inventing one.
+DEFAULT_ISSUER: Final[str] = "Terp"
+
+# The active issuer (module-level, composition-root-configured — the same seam shape the
+# files capability uses for its upload limit). Never client data: it is baked into every
+# enrolment QR code, so a caller who could set it could make their enrolment impersonate
+# another system in the victim's authenticator app.
+_issuer: str = DEFAULT_ISSUER
+
+
+def configure_mfa_issuer(name: str) -> None:
+    """Name the deployment in the codes its people enrol (a composition-root line).
+
+    Validated eagerly so a mis-wired root fails at boot rather than at the first
+    enrolment — and a blank issuer is the failure worth catching, because it produces a
+    QR code that scans cleanly and then shows up in the authenticator app as an unlabelled
+    row the person cannot tell from any other.
+    """
+    global _issuer
+    cleaned = name.strip()
+    if not cleaned:
+        raise ValueError("the MFA issuer must be a non-empty name")
+    _issuer = cleaned
+
+
+def active_mfa_issuer() -> str:
+    """The issuer new enrolments are currently labelled with."""
+    return _issuer
+
+
+def reset_mfa_issuer() -> None:
+    """Restore the default issuer (the test-isolation reset)."""
+    global _issuer
+    _issuer = DEFAULT_ISSUER
+
+
+def _caller(principal: Principal | None) -> Principal:
+    """The authenticated caller, or a clean 401.
+
+    The module guard rejects an anonymous caller before any handler runs; this keeps the
+    router correct — a 401, never an ``AttributeError`` — if it is ever mounted without
+    one.
+    """
+    if principal is None:
+        raise AuthenticationError()
+    return principal
+
+
+@router.get("/", response_model=MfaStatusRead)
+@operation(MFA_STATUS)
+def read_status(
+    session: SessionDep, principal: Principal | None = Depends(get_principal)
+) -> MfaStatusRead:
+    from sqlmodel import select
+
+    from terp.capabilities.mfa.models import MfaRecoveryCode
+
+    caller = _caller(principal)
+    enrolment = _service.enrolment_for(session, caller.id)
+    remaining = 0
+    if enrolment is not None:
+        remaining = len(
+            session.exec(
+                select(MfaRecoveryCode).where(
+                    MfaRecoveryCode.enrolment_id == enrolment.id,
+                    MfaRecoveryCode.used_at.is_(None),  # type: ignore[union-attr]
+                )
+            ).all()
+        )
+    return MfaStatusRead(
+        enrolled=enrolment is not None,
+        confirmed=enrolment is not None and enrolment.confirmed_at is not None,
+        recovery_codes_remaining=remaining,
+    )
+
+
+@router.post("/", response_model=MfaSecretIssued, status_code=201)
+@operation(MFA_ENROL)
+def begin_enrolment(
+    session: SessionDep, principal: Principal | None = Depends(get_principal)
+) -> MfaSecretIssued:
+    # The only response in this capability that carries a plaintext secret, and the only
+    # moment one crosses the boundary: an authenticator app cannot be enrolled without
+    # it. It is not stored in this form and no read DTO can return it again.
+    caller = _caller(principal)
+    return _service.begin_enrolment(
+        session,
+        caller.id,
+        account=str(caller.id),
+        issuer=active_mfa_issuer(),
+    )
+
+
+@router.post("/confirm", response_model=MfaEnrolmentRead)
+@operation(MFA_CONFIRM)
+def confirm_enrolment(
+    payload: MfaCodeRequest,
+    session: SessionDep,
+    principal: Principal | None = Depends(get_principal),
+) -> MfaEnrolmentRead:
+    caller = _caller(principal)
+    return MfaEnrolmentRead.model_validate(
+        _service.confirm_enrolment(session, caller.id, payload.code)
+    )
+
+
+@router.delete("/", status_code=204)
+@operation(MFA_DISABLE)
+def disable(
+    session: SessionDep, principal: Principal | None = Depends(get_principal)
+) -> None:
+    caller = _caller(principal)
+    _service.disable(session, caller.id)
+
+
+def build_mfa_module(*, name: str = "mfa") -> ModuleSpec:
+    """The self-scoped second-factor ``ModuleSpec`` (any authenticated caller).
+
+    VIEWER on the write tier, not the EDITOR a bare ``Policy.default()`` would impose.
+    Enrolling is a POST, but it changes nothing except the caller's own security, and a
+    read-only account is not a second-class one: gating this at EDITOR would deny a
+    second factor to exactly the accounts an application hands out most freely, which
+    inverts the control.
+    """
+    return ModuleSpec(
+        name=name, router=router, policy=Policy(read=Roles.VIEWER, write=Roles.VIEWER)
+    )
+
+
+module = build_mfa_module()
+
+
+__all__ = [
+    "DEFAULT_ISSUER",
+    "active_mfa_issuer",
+    "build_mfa_module",
+    "configure_mfa_issuer",
+    "module",
+    "reset_mfa_issuer",
+    "router",
+]

terp_cap_mfa-0.27.0/src/terp/capabilities/mfa/schemas.py

@@ -0,0 +1,88 @@
+"""MFA DTOs.
+
+``MfaEnrolmentCreate`` is **server-built only**: the service generates the secret and
+seals it before constructing this, so a client never supplies either. ``MfaEnrolmentRead``
+carries no secret at all — not sealed, not masked, not present. The one moment a
+plaintext secret crosses the boundary is :class:`MfaSecretIssued`, returned exactly once
+from the enrolment call, because an authenticator app cannot be enrolled without it.
+
+``MfaSecretIssued`` is deliberately not a read DTO of the row. It is the response to one
+action, and it exists as its own type so nothing can be tempted to return it from a
+listing later.
+"""
+
+from __future__ import annotations
+
+import datetime
+import uuid
+
+from sqlmodel import Field
+
+from terp.core import BaseSchema, BaseUpdateSchema
+
+from terp.capabilities.mfa.models import SECRET_MAX
+
+_CODE_MAX = 32
+
+
+class MfaEnrolmentCreate(BaseSchema):
+    """The enrolment row — constructed by the service, never posted by a client."""
+
+    user_id: uuid.UUID
+    secret: str = Field(min_length=1, max_length=SECRET_MAX)
+
+
+class MfaEnrolmentUpdate(BaseUpdateSchema):
+    """Patch the enrolment's live-ness (OCC via the inherited required ``version``).
+
+    Only ``confirmed_at`` is patchable, and only the service sets it. The secret is
+    append-only: replacing a factor means disabling it and enrolling again, which is two
+    audited acts rather than one silent one.
+    """
+
+    confirmed_at: datetime.datetime | None = None
+    last_used_step: int | None = None
+
+
+class MfaEnrolmentRead(BaseSchema):
+    """What a caller may learn about their own enrolment: that it exists, and whether it is live."""
+
+    id: uuid.UUID
+    user_id: uuid.UUID
+    confirmed_at: datetime.datetime | None
+    version: int
+    created_at: datetime.datetime
+    updated_at: datetime.datetime
+
+
+class MfaSecretIssued(BaseSchema):
+    """The one-time response to starting an enrolment: the secret, its URI, the codes."""
+
+    # arch-allow-schemas-exclude-sensitive-fields: an authenticator app cannot be enrolled without the shared secret, so this one response must carry it. It is returned exactly once, at the moment it is generated, never read back from the row (which holds it sealed), and carried by no other DTO -- MfaEnrolmentRead has no secret field at all.
+    secret: str
+    provisioning_uri: str
+    recovery_codes: list[str]
+
+
+class MfaCodeRequest(BaseSchema):
+    """A submitted code — a TOTP digit string or a recovery code."""
+
+    code: str = Field(min_length=1, max_length=_CODE_MAX)
+
+
+class MfaStatusRead(BaseSchema):
+    """Whether the caller has a live second factor, and how many recovery codes remain."""
+
+    enrolled: bool
+    confirmed: bool
+    recovery_codes_remaining: int
+
+
+__all__ = [
+    "MfaCodeRequest",
+    "MfaEnrolmentCreate",
+    "MfaEnrolmentRead",
+    "MfaEnrolmentUpdate",
+    "MfaSecretIssued",
+    "MfaStatusRead",
+]

terp_cap_mfa-0.27.0/src/terp/capabilities/mfa/sealing.py

@@ -0,0 +1,91 @@
+"""At-rest sealing for the TOTP shared secret.
+
+The enrolment secret *is* the second factor: anyone holding it can generate the codes
+for that account forever, and unlike a password it is never rotated by the person who
+owns it. A database leak of plaintext secrets would therefore hand over every enrolled
+account's second factor silently — the victims' phones keep producing the same codes the
+attacker now produces, so nothing about the account looks wrong.
+
+The cipher is a deliberate sibling of ``terp.capabilities.webhooks.sealing`` rather than
+a call into it: Fernet (AES128-CBC + HMAC-SHA256) keyed from the live ``SECRET_KEY``
+through HKDF with an **MFA-specific** ``info`` label. Domain separation is the point — a
+sealed value from one domain must not decrypt in another, so a leaked webhook secret is
+not an enrolment secret and neither is a sealed config value.
+
+Unlike the webhook secret there is **no legacy tolerance**. That capability passes an
+unsealed value through unchanged, because rows predating its sealing control exist and
+must keep delivering. No row here predates this control, so a secret that does not
+carry the sealed prefix is not a legacy value — it is a bug or a tampered row, and
+reading it as a valid factor would be the one mistake this module exists to prevent.
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Final
+
+from terp.core import AppError, get_settings
+
+#: The portable sealed format (shared shape with ``terp.core.secrets``, distinct key).
+_SEAL_PREFIX: Final[str] = "enc:v1:"
+
+# Domain separation: the MFA-seal key is derived from SECRET_KEY with this label, never
+# SECRET_KEY itself and never another capability's derivation.
+_HKDF_INFO: Final[bytes] = b"terp.capabilities.mfa.totp-seal.v1"
+
+
+class MfaSecretError(AppError):
+    """500 — an enrolment secret could not be read under the current ``SECRET_KEY``.
+
+    Deliberately a 500 and deliberately not "invalid code": the caller did nothing
+    wrong, and reporting it as a failed verification would tell an operator their users
+    are typing the wrong digits while the real fault is a rotated key or a damaged row.
+    """
+
+    status_code = 500
+    code = "mfa_secret_error"
+    default_message = "The second-factor enrolment could not be read."
+
+
+def _cipher():  # the return type lives in the `cryptography` dependency
+    """The sealing cipher, keyed from the live ``SECRET_KEY`` via HKDF."""
+    from cryptography.fernet import Fernet
+    from cryptography.hazmat.primitives import hashes
+    from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+    derived = HKDF(
+        algorithm=hashes.SHA256(), length=32, salt=None, info=_HKDF_INFO
+    ).derive(get_settings().SECRET_KEY.encode("utf-8"))
+    return Fernet(base64.urlsafe_b64encode(derived))
+
+
+def is_sealed_secret(value: str) -> bool:
+    """Whether *value* carries the sealed ``enc:v1:`` format."""
+    return value.startswith(_SEAL_PREFIX)
+
+
+def seal_secret(plaintext: str) -> str:
+    """Seal a TOTP shared secret for at-rest storage."""
+    token = _cipher().encrypt(plaintext.encode("utf-8"))
+    return _SEAL_PREFIX + token.decode("ascii")
+
+
+def unseal_secret(stored: str) -> str:
+    """The verification-time plaintext of *stored* — fail-closed on anything else.
+
+    A value with no sealed prefix raises rather than being used: see the module
+    docstring for why this capability has no legacy-plaintext path.
+    """
+    if not is_sealed_secret(stored):
+        raise MfaSecretError()
+    from cryptography.fernet import InvalidToken
+
+    try:
+        return (
+            _cipher().decrypt(stored.removeprefix(_SEAL_PREFIX).encode("ascii")).decode("utf-8")
+        )
+    except InvalidToken as exc:
+        raise MfaSecretError() from exc
+
+
+__all__ = ["MfaSecretError", "is_sealed_secret", "seal_secret", "unseal_secret"]

terp_cap_mfa-0.27.0/src/terp/capabilities/mfa/service.py

@@ -0,0 +1,247 @@
+"""The second-factor service: enrol, confirm, verify, disable.
+
+Every write here goes through :class:`~terp.core.BaseService`'s audited chokepoint, so
+enrolling and disabling a factor land in the trail like any other change. That matters
+more than usual for this table: *disabling* a second factor is the single most useful
+thing an attacker who has taken an account can do to keep it, and a disable that left no
+record would be invisible.
+
+Verifying is a **write too**, which reads as a surprise and is not one: a second factor
+that can be used twice is not a second factor, so accepting a code has to record that it
+was accepted. A TOTP code moves the enrolment's high-water mark; a recovery code is
+stamped spent. Both go through the same chokepoint as everything else here — the
+``mutations_emit_audit`` rule requires it, and a factor being exercised is a thing the
+trail should carry. It happens during a login, before there is a session at all, so the
+actor on those records is the login rather than a signed-in person.
+"""
+
+from __future__ import annotations
+
+import datetime
+import uuid
+
+from sqlmodel import Session, select
+
+from terp.core import AppError, BaseService
+
+from terp.capabilities.mfa import recovery, totp
+from terp.capabilities.mfa.models import MfaEnrolment, MfaRecoveryCode
+from terp.capabilities.mfa.schemas import (
+    MfaEnrolmentCreate,
+    MfaEnrolmentUpdate,
+    MfaSecretIssued,
+)
+from terp.capabilities.mfa.sealing import seal_secret, unseal_secret
+
+
+class MfaAlreadyEnrolledError(AppError):
+    """409 — this subject already has a live second factor.
+
+    Refused rather than silently replaced: overwriting a live enrolment is exactly the
+    move an attacker makes with a stolen session, and it would read as an ordinary
+    "set up authenticator" request. Replacing one means disabling it first, which is a
+    separate, audited act.
+    """
+
+    status_code = 409
+    code = "mfa_already_enrolled"
+    default_message = "A second factor is already enrolled for this account."
+
+
+class MfaNotEnrolledError(AppError):
+    """404 — there is no enrolment to confirm, verify against, or disable."""
+
+    status_code = 404
+    code = "mfa_not_enrolled"
+    default_message = "No second factor is enrolled for this account."
+
+
+class MfaCodeInvalidError(AppError):
+    """401 — the code did not verify.
+
+    One error for a wrong TOTP code and a wrong recovery code, on purpose: telling a
+    caller *which* of the two they got wrong tells them which one they are closer to,
+    and neither answer helps somebody typing their own code.
+    """
+
+    status_code = 401
+    code = "mfa_code_invalid"
+    default_message = "That code is not valid."
+
+
+def _utc_now() -> datetime.datetime:
+    """UTC ``now`` provider — private so tests can drive the clock."""
+    return datetime.datetime.now(datetime.UTC)
+
+
+class MfaService(BaseService[MfaEnrolment, MfaEnrolmentCreate, MfaEnrolmentUpdate]):
+    model = MfaEnrolment
+
+    def enrolment_for(self, session: Session, user_id: uuid.UUID) -> MfaEnrolment | None:
+        """This subject's enrolment row, confirmed or not."""
+        return session.exec(
+            select(MfaEnrolment).where(MfaEnrolment.user_id == user_id)
+        ).first()
+
+    def is_enrolled(self, session: Session, user_id: uuid.UUID) -> bool:
+        """Whether a **confirmed** second factor stands between this subject and a session.
+
+        Only a confirmed enrolment counts. A started-but-unproved one must not gate a
+        login, or a mis-scanned QR code becomes a lockout.
+        """
+        enrolment = self.enrolment_for(session, user_id)
+        return enrolment is not None and enrolment.confirmed_at is not None
+
+    def begin_enrolment(
+        self, session: Session, user_id: uuid.UUID, *, account: str, issuer: str
+    ) -> MfaSecretIssued:
+        """Issue a secret and recovery codes. The plaintext is returned exactly once.
+
+        An *unconfirmed* row is replaced rather than refused: somebody who started an
+        enrolment, closed the tab and came back has no way to recover the first secret,
+        and refusing them would leave a row nobody can confirm and nobody can clear. A
+        *confirmed* row is refused (see :class:`MfaAlreadyEnrolledError`).
+        """
+        existing = self.enrolment_for(session, user_id)
+        if existing is not None:
+            if existing.confirmed_at is not None:
+                raise MfaAlreadyEnrolledError()
+            self._purge_recovery_codes(session, existing.id)
+            self.delete(session, existing.id)
+
+        secret = totp.generate_secret()
+        enrolment = self.create(
+            session,
+            MfaEnrolmentCreate(user_id=user_id, secret=seal_secret(secret)),
+        )
+        codes = recovery.generate_codes()
+        for code in codes:
+            self._save_recovery_code(session, enrolment.id, recovery.hash_code(code))
+        return MfaSecretIssued(
+            secret=secret,
+            provisioning_uri=totp.provisioning_uri(secret, account=account, issuer=issuer),
+            recovery_codes=codes,
+        )
+
+    def confirm_enrolment(self, session: Session, user_id: uuid.UUID, code: str) -> MfaEnrolment:
+        """Prove the secret arrived intact, and make the factor live."""
+        enrolment = self.enrolment_for(session, user_id)
+        if enrolment is None:
+            raise MfaNotEnrolledError()
+        if enrolment.confirmed_at is not None:
+            raise MfaAlreadyEnrolledError()
+        step = totp.verify_step(unseal_secret(enrolment.secret), code)
+        if step is None:
+            raise MfaCodeInvalidError()
+        # The confirming code is spent by confirming. Recording it here is what stops it
+        # being handed straight back as the first login factor, which is a replay across
+        # two endpoints rather than two calls to one.
+        return self.update(
+            session,
+            enrolment.id,
+            MfaEnrolmentUpdate(
+                confirmed_at=_utc_now(), last_used_step=step, version=enrolment.version
+            ),
+        )
+
+    def verify(self, session: Session, user_id: uuid.UUID, code: str) -> bool:
+        """Whether *code* satisfies this subject's second factor.
+
+        Accepts a TOTP code or an unspent recovery code, and spends the latter. Returns
+        ``False`` rather than raising for a subject with no confirmed enrolment: the
+        caller is the login route, and "this account has no second factor" is its
+        question to ask beforehand, not an error to handle here.
+        """
+        enrolment = self.enrolment_for(session, user_id)
+        if enrolment is None or enrolment.confirmed_at is None:
+            return False
+        step = totp.verify_step(unseal_secret(enrolment.secret), code)
+        if step is not None:
+            return self._spend_step(session, enrolment, step)
+        return self._consume_recovery_code(session, enrolment.id, code)
+
+    def disable(self, session: Session, user_id: uuid.UUID) -> None:
+        """Remove the factor and every recovery code with it (an audited delete)."""
+        enrolment = self.enrolment_for(session, user_id)
+        if enrolment is None:
+            raise MfaNotEnrolledError()
+        self._purge_recovery_codes(session, enrolment.id)
+        self.delete(session, enrolment.id)
+
+    def _purge_recovery_codes(self, session: Session, enrolment_id: uuid.UUID) -> None:
+        """Delete this enrolment's codes through the audited chokepoint.
+
+        Explicit, rather than leaning on the foreign key's ``ON DELETE CASCADE``. The
+        cascade is declared and is the right backstop, but it only fires where the
+        database enforces foreign keys -- SQLite does not, unless asked -- so a service
+        that relied on it would leave live recovery codes behind on one backend and not
+        another. A spent-looking factor whose codes still authenticate is the worst of
+        the available failures, so the deletion is stated here and the cascade is
+        defence in depth.
+        """
+        for row in session.exec(
+            select(MfaRecoveryCode).where(MfaRecoveryCode.enrolment_id == enrolment_id)
+        ).all():
+            self._remove(session, row)
+
+    def _save_recovery_code(
+        self, session: Session, enrolment_id: uuid.UUID, code_hash: str
+    ) -> None:
+        """Persist one code digest through the audited chokepoint."""
+        from terp.core import AuditAction
+
+        self._save(
+            session,
+            MfaRecoveryCode(enrolment_id=enrolment_id, code_hash=code_hash),
+            AuditAction.CREATED,
+        )
+
+    def _spend_step(self, session: Session, enrolment: MfaEnrolment, step: int) -> bool:
+        """Accept *step* once, and never again for this enrolment."""
+        from terp.core import AuditAction
+
+        # `<=`, not `==`: the drift window reaches one step BACK, so after a code from the
+        # current step is spent the previous step is still inside the window and its code
+        # would otherwise verify. Refusing everything at or below the high-water mark closes
+        # the window behind the caller rather than just the one code they used.
+        if enrolment.last_used_step is not None and step <= enrolment.last_used_step:
+            return False
+        enrolment.last_used_step = step
+        # Through the chokepoint, like every other mutation here: `mutations_emit_audit`
+        # requires it, and a second factor being exercised is a thing the trail should carry.
+        self._save(session, enrolment, AuditAction.UPDATED)
+        return True
+
+    def _consume_recovery_code(
+        self, session: Session, enrolment_id: uuid.UUID, code: str
+    ) -> bool:
+        """Spend an unspent recovery code matching *code*, if there is one.
+
+        Every candidate is compared even after a match is found, so the work does not
+        depend on which code was presented.
+        """
+        from terp.core import AuditAction
+
+        rows = session.exec(
+            select(MfaRecoveryCode).where(
+                MfaRecoveryCode.enrolment_id == enrolment_id,
+                MfaRecoveryCode.used_at.is_(None),  # type: ignore[union-attr]
+            )
+        ).all()
+        found: MfaRecoveryCode | None = None
+        for row in rows:
+            if recovery.matches(code, row.code_hash) and found is None:
+                found = row
+        if found is None:
+            return False
+        found.used_at = _utc_now()
+        self._save(session, found, AuditAction.UPDATED)
+        return True
+
+
+__all__ = [
+    "MfaAlreadyEnrolledError",
+    "MfaCodeInvalidError",
+    "MfaNotEnrolledError",
+    "MfaService",
+]

terp_cap_mfa-0.27.0/src/terp/capabilities/mfa/totp.py

@@ -0,0 +1,159 @@
+"""RFC 6238 time-based one-time passwords, on the standard library.
+
+No dependency for this. TOTP is HMAC-SHA1 over a counter derived from the clock
+(RFC 4226 truncation, RFC 6238 time step) — about twenty lines against ``hmac`` and
+``hashlib``, and the specification ships **test vectors**, so correctness here is
+checkable rather than asserted. Those vectors are in the suite; a change that broke the
+algorithm could not stay green.
+
+The alternative was a dependency for twenty lines of well-specified arithmetic, which is
+a supply-chain edge every consumer inherits. Where that trade would go the other way is
+anything requiring primitive design — and this requires none: the primitive is
+``hmac.new``, which is the standard library's.
+
+Two properties the arithmetic does not give you, and which a caller cannot add
+afterwards:
+
+* **Comparison is constant-time.** A code is a shared secret for thirty seconds and
+  ``==`` on strings leaks its prefix through timing. :func:`verify` uses
+  ``hmac.compare_digest`` on every candidate.
+* **Drift is bounded and symmetric.** Phone clocks are wrong. A window of one step
+  either side (±30 s by default) is the RFC's own suggestion; widening it multiplies the
+  codes a guesser may hit, so it is a parameter with a small default rather than
+  something a call site improvises.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import secrets
+import struct
+import time
+from typing import Final
+
+#: The RFC 6238 default time step. Not configurable: an authenticator app assumes it,
+#: and a deployment that changed it would produce codes no enrolled phone can generate.
+TIME_STEP_SECONDS: Final[int] = 30
+
+#: Digits in a generated code. Six is what every authenticator app shows.
+DIGITS: Final[int] = 6
+
+#: How many steps either side of the current one are accepted. One step (±30 s) covers
+#: ordinary phone-clock drift and the time a person takes to type. Each extra step is
+#: another code a guesser may hit, so this stays small and is stated rather than tuned.
+DEFAULT_DRIFT_STEPS: Final[int] = 1
+
+#: Bytes of entropy in a generated shared secret (160 bits, the RFC 4226 recommendation
+#: for HMAC-SHA1).
+_SECRET_BYTES: Final[int] = 20
+
+
+def generate_secret() -> str:
+    """A fresh base32 shared secret, in the form an authenticator app expects."""
+    return base64.b32encode(secrets.token_bytes(_SECRET_BYTES)).decode("ascii").rstrip("=")
+
+
+def _counter_code(secret: str, counter: int) -> str:
+    """The RFC 4226 HOTP value for *counter* — the whole of the arithmetic."""
+    # Base32 alphabets in the wild arrive unpadded and lower-cased; normalise both rather
+    # than making every caller remember to.
+    normalised = secret.strip().replace(" ", "").upper()
+    padding = "=" * (-len(normalised) % 8)
+    key = base64.b32decode(normalised + padding, casefold=True)
+    digest = hmac.new(key, struct.pack(">Q", counter), hashlib.sha1).digest()
+    # Dynamic truncation (RFC 4226 §5.3): the low nibble of the last byte picks the
+    # offset, and the high bit of the selected word is masked off so the result is
+    # positive on every platform's signed interpretation.
+    offset = digest[-1] & 0x0F
+    (truncated,) = struct.unpack(">I", digest[offset : offset + 4])
+    return str((truncated & 0x7FFF_FFFF) % (10**DIGITS)).zfill(DIGITS)
+
+
+def generate(secret: str, *, at: float | None = None) -> str:
+    """The code *secret* produces now (or at *at*, a UNIX timestamp)."""
+    moment = time.time() if at is None else at
+    return _counter_code(secret, int(moment // TIME_STEP_SECONDS))
+
+
+def verify_step(
+    secret: str,
+    code: str,
+    *,
+    at: float | None = None,
+    drift_steps: int = DEFAULT_DRIFT_STEPS,
+) -> int | None:
+    """Which time step *code* satisfies for *secret*, or ``None`` if none does.
+
+    The step is returned rather than a bare yes, because a caller cannot enforce
+    single use without knowing which code was spent: a code is valid for its whole
+    window, so "it verified" is true again thirty seconds later for the same six
+    digits. RFC 6238 section 5.2 puts the duty on the verifier, and the verifier is the
+    only party holding the state to discharge it.
+
+    Every candidate is compared in constant time **and** every candidate is compared:
+    returning early on the first match would leak, through timing, which step matched,
+    and with it the direction and size of the caller's clock error. The match is
+    recorded and the loop runs to the end.
+    """
+    candidate = code.strip().replace(" ", "")
+    if len(candidate) != DIGITS or not candidate.isdigit():
+        return None
+    moment = time.time() if at is None else at
+    step = int(moment // TIME_STEP_SECONDS)
+    matched: int | None = None
+    for offset in range(-drift_steps, drift_steps + 1):
+        expected = _counter_code(secret, step + offset)
+        hit = hmac.compare_digest(expected, candidate)
+        matched = step + offset if hit else matched
+    return matched
+
+
+def verify(
+    secret: str,
+    code: str,
+    *,
+    at: float | None = None,
+    drift_steps: int = DEFAULT_DRIFT_STEPS,
+) -> bool:
+    """Whether *code* is valid for *secret* now, within the drift window.
+
+    Answers the question without the step, for callers that hold no state to spend it
+    against. A caller that stores an enrolment wants :func:`verify_step`.
+    """
+    return verify_step(secret, code, at=at, drift_steps=drift_steps) is not None
+
+
+def provisioning_uri(secret: str, *, account: str, issuer: str) -> str:
+    """The ``otpauth://`` URI an authenticator app scans as a QR code.
+
+    Built here rather than by a caller because the parameter names are part of the
+    de-facto standard every app implements, and a typo in one produces an enrolment that
+    scans cleanly and then never matches.
+    """
+    from urllib.parse import quote, urlencode
+
+    label = quote(f"{issuer}:{account}", safe="")
+    query = urlencode(
+        {
+            "secret": secret,
+            "issuer": issuer,
+            "algorithm": "SHA1",
+            "digits": DIGITS,
+            "period": TIME_STEP_SECONDS,
+        }
+    )
+    return f"otpauth://totp/{label}?{query}"
+
+
+__all__ = [
+    "DEFAULT_DRIFT_STEPS",
+    "DIGITS",
+    "TIME_STEP_SECONDS",
+    "generate",
+    "generate_secret",
+    "provisioning_uri",
+    "verify",
+    "verify_step",
+]