pavilion 0.1.0__tar.gz

pavilion-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.3
+Name: pavilion
+Version: 0.1.0
+Summary: Add your description here
+Author: laconal
+Author-email: laconal <asliddin.forwork@gmail.com>
+Requires-Dist: cryptography>=50.0.2
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: ruamel-yaml>=0.19.1
+Requires-Dist: typer>=0.27.2
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# pavilion
+
+A project scaffolder built with Typer.
+
+## Install
+
+```sh
+uv tool install .        # or: uv run pavilion ...
+```
+
+## Usage
+
+```sh
+pavilion add service list             # show available services
+pavilion add service redis            # add redis to the compose file in the current dir
+pavilion add service postgres        # pick a version with the arrow keys
+pavilion add service postgres --version 17   # non-interactive
+pavilion add service redis -f infra/compose.yaml
+pavilion add service redis --force    # overwrite an existing redis service
+```
+
+Pavilion edits the first of `compose.yaml`, `compose.yml`, `docker-compose.yaml` or
+`docker-compose.yml` it finds, or creates `docker-compose.yml`. Existing comments and
+ordering are preserved.
+
+Available services: `redis` (8, 7) and `postgres` (18, 17, 16, 15). Without `--version`,
+pavilion asks interactively; when there's no terminal (CI, pipes) it uses the newest.
+
+Postgres defaults (`postgres` / `postgres`, database `app`) can be overridden with
+`POSTGRES_USER`, `POSTGRES_PASSWORD` and `POSTGRES_DB` in a `.env` file.
+
+### Keys
+
+```sh
+pavilion add keys                     # pick an algorithm with the arrow keys
+pavilion add keys ES256               # RS256 | ES256 | EdDSA (case-insensitive)
+pavilion add keys EdDSA -d config/jwt # custom directory (default: secrets)
+pavilion add keys RS256 --rsa-bits 4096  # RSA key size (default 2048, prompted if omitted)
+pavilion add keys RS256 --force       # replace an existing key pair
+pavilion add keys EdDSA --refresh     # refresh-token pair: private_refresh.pem, public_refresh.pem
+```
+
+Writes `private.pem` (PKCS#8, mode 0600) and `public.pem` (SubjectPublicKeyInfo).
+The directory gets its own `.gitignore` so keys are never committed by accident.
+
+### Auth
+
+```sh
+pavilion add auth                     # answer the prompts with the arrow keys
+pavilion add auth --transport cookie --algorithm ES256 --hashing argon2
+pavilion add auth --transport header --strategy symmetric
+pavilion add auth --algorithm RS256 --rsa-bits 3072 --refresh-keys separate
+pavilion add auth --access-ttl 30m --refresh-ttl 7d
+```
+
+Generates a framework-agnostic `auth/` package (`-d` to change) built on JWT access and
+refresh tokens. Their lifetimes default to 3h and 24h; enter them as `30m`, `3h`, `7d`
+or `90s` (a bare number means hours), and the refresh TTL must be the longer one.
+
+| File | Contents |
+|---|---|
+| `tokens.py` | create/verify access and refresh tokens |
+| `service.py` | `AuthService.login / refresh / logout / authenticate` |
+| `passwords.py` | `hash_password` / `verify_password` (Argon2 or bcrypt) |
+| `cookies.py` (`--transport cookie`) | HttpOnly cookie settings for `response.set_cookie(**cookie.kwargs)` |
+
+With `--transport header` clients send `Authorization: Bearer <access token>`; with
+`--transport cookie` the tokens are set as HttpOnly cookies (the refresh cookie is
+`SameSite=Strict` and only sent to `/auth`).
+
+Implement `UserRepository.get_by_username()` for your user model; see the generated
+`__init__.py` for an example. Asymmetric signing reuses (or creates) the key pair in
+`secrets/`; symmetric creates `secrets/jwt_secret`. With `--refresh-keys separate`,
+refresh tokens are signed with their own keys/secret (`secrets/private_refresh.pem` and
+`public_refresh.pem`, or `secrets/jwt_secret_refresh`), so a leaked
+access key can't forge refresh tokens. The in-memory revoked-token store is for
+development; back it with Redis or a database in production.
+
+## Development
+
+Each `pavilion add ...` feature lives in its own folder under `src/pavilion/`, with its
+command (`cli.py`) next to the logic behind it:
+
+```
+cli.py              root app; wires the feature commands together
+ui.py               shared menus, prompts and error exits
+compose/            add service   (file.py edits the compose file; services/ has one module per service)
+keys/               add keys      (generate.py)
+auth/               add auth      (config.py, scaffold.py, templates/)
+```
+
+To add a compose service, create `compose/services/<name>.py` with a `ServiceSpec` and
+register it in `compose/services/__init__.py`. Tests mirror this layout under `tests/`.
+
+
+```sh
+uv run pytest
+```

pavilion-0.1.0/README.md

@@ -0,0 +1,98 @@
+# pavilion
+
+A project scaffolder built with Typer.
+
+## Install
+
+```sh
+uv tool install .        # or: uv run pavilion ...
+```
+
+## Usage
+
+```sh
+pavilion add service list             # show available services
+pavilion add service redis            # add redis to the compose file in the current dir
+pavilion add service postgres        # pick a version with the arrow keys
+pavilion add service postgres --version 17   # non-interactive
+pavilion add service redis -f infra/compose.yaml
+pavilion add service redis --force    # overwrite an existing redis service
+```
+
+Pavilion edits the first of `compose.yaml`, `compose.yml`, `docker-compose.yaml` or
+`docker-compose.yml` it finds, or creates `docker-compose.yml`. Existing comments and
+ordering are preserved.
+
+Available services: `redis` (8, 7) and `postgres` (18, 17, 16, 15). Without `--version`,
+pavilion asks interactively; when there's no terminal (CI, pipes) it uses the newest.
+
+Postgres defaults (`postgres` / `postgres`, database `app`) can be overridden with
+`POSTGRES_USER`, `POSTGRES_PASSWORD` and `POSTGRES_DB` in a `.env` file.
+
+### Keys
+
+```sh
+pavilion add keys                     # pick an algorithm with the arrow keys
+pavilion add keys ES256               # RS256 | ES256 | EdDSA (case-insensitive)
+pavilion add keys EdDSA -d config/jwt # custom directory (default: secrets)
+pavilion add keys RS256 --rsa-bits 4096  # RSA key size (default 2048, prompted if omitted)
+pavilion add keys RS256 --force       # replace an existing key pair
+pavilion add keys EdDSA --refresh     # refresh-token pair: private_refresh.pem, public_refresh.pem
+```
+
+Writes `private.pem` (PKCS#8, mode 0600) and `public.pem` (SubjectPublicKeyInfo).
+The directory gets its own `.gitignore` so keys are never committed by accident.
+
+### Auth
+
+```sh
+pavilion add auth                     # answer the prompts with the arrow keys
+pavilion add auth --transport cookie --algorithm ES256 --hashing argon2
+pavilion add auth --transport header --strategy symmetric
+pavilion add auth --algorithm RS256 --rsa-bits 3072 --refresh-keys separate
+pavilion add auth --access-ttl 30m --refresh-ttl 7d
+```
+
+Generates a framework-agnostic `auth/` package (`-d` to change) built on JWT access and
+refresh tokens. Their lifetimes default to 3h and 24h; enter them as `30m`, `3h`, `7d`
+or `90s` (a bare number means hours), and the refresh TTL must be the longer one.
+
+| File | Contents |
+|---|---|
+| `tokens.py` | create/verify access and refresh tokens |
+| `service.py` | `AuthService.login / refresh / logout / authenticate` |
+| `passwords.py` | `hash_password` / `verify_password` (Argon2 or bcrypt) |
+| `cookies.py` (`--transport cookie`) | HttpOnly cookie settings for `response.set_cookie(**cookie.kwargs)` |
+
+With `--transport header` clients send `Authorization: Bearer <access token>`; with
+`--transport cookie` the tokens are set as HttpOnly cookies (the refresh cookie is
+`SameSite=Strict` and only sent to `/auth`).
+
+Implement `UserRepository.get_by_username()` for your user model; see the generated
+`__init__.py` for an example. Asymmetric signing reuses (or creates) the key pair in
+`secrets/`; symmetric creates `secrets/jwt_secret`. With `--refresh-keys separate`,
+refresh tokens are signed with their own keys/secret (`secrets/private_refresh.pem` and
+`public_refresh.pem`, or `secrets/jwt_secret_refresh`), so a leaked
+access key can't forge refresh tokens. The in-memory revoked-token store is for
+development; back it with Redis or a database in production.
+
+## Development
+
+Each `pavilion add ...` feature lives in its own folder under `src/pavilion/`, with its
+command (`cli.py`) next to the logic behind it:
+
+```
+cli.py              root app; wires the feature commands together
+ui.py               shared menus, prompts and error exits
+compose/            add service   (file.py edits the compose file; services/ has one module per service)
+keys/               add keys      (generate.py)
+auth/               add auth      (config.py, scaffold.py, templates/)
+```
+
+To add a compose service, create `compose/services/<name>.py` with a `ServiceSpec` and
+register it in `compose/services/__init__.py`. Tests mirror this layout under `tests/`.
+
+
+```sh
+uv run pytest
+```

pavilion-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "pavilion"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "cryptography>=50.0.2",
+    "jinja2>=3.1.6",
+    "questionary>=2.1.1",
+    "ruamel-yaml>=0.19.1",
+    "typer>=0.27.2",
+]
+
+[[project.authors]]
+name = "laconal"
+email = "asliddin.forwork@gmail.com"
+
+[project.scripts]
+pavilion = "pavilion:main"
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "argon2-cffi>=25.1.0",
+    "bcrypt>=5.0.0",
+    "pyjwt[crypto]>=2.15.1",
+    "pytest>=9.1.1",
+]

pavilion-0.1.0/pyproject.toml.orig

@@ -0,0 +1,31 @@
+[project]
+name = "pavilion"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "laconal", email = "asliddin.forwork@gmail.com" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "cryptography>=50.0.2",
+    "jinja2>=3.1.6",
+    "questionary>=2.1.1",
+    "ruamel-yaml>=0.19.1",
+    "typer>=0.27.2",
+]
+
+[project.scripts]
+pavilion = "pavilion:main"
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "argon2-cffi>=25.1.0",
+    "bcrypt>=5.0.0",
+    "pyjwt[crypto]>=2.15.1",
+    "pytest>=9.1.1",
+]

pavilion-0.1.0/src/pavilion/__init__.py

@@ -0,0 +1,5 @@
+from pavilion.cli import app
+
+
+def main() -> None:
+    app()

pavilion-0.1.0/src/pavilion/auth/__init__.py

@@ -0,0 +1 @@
+"""Auth package scaffolding (`pavilion add auth`)."""

pavilion-0.1.0/src/pavilion/auth/cli.py

@@ -0,0 +1,173 @@
+"""`pavilion add auth`"""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from pavilion import ui
+from pavilion.auth.config import AuthConfig, Hashing, RefreshKeys, Strategy, Transport
+from pavilion.auth.scaffold import AuthFilesExistError, key_pairs, scaffold_auth
+from pavilion.auth.ttl import DEFAULT_ACCESS_TTL, DEFAULT_REFRESH_TTL, TTL, validate_ttls
+from pavilion.keys.cli import RsaBitsOption, check_rsa_bits, choose_algorithm, choose_rsa_bits
+from pavilion.keys.generate import (
+    DEFAULT_SECRETS_DIR,
+    Algorithm,
+    KeyMismatchError,
+    KeyPair,
+)
+
+REFRESH_KEY_LABELS = {
+    Strategy.ASYMMETRIC: "Separate key pair  (a leaked access key can't forge refresh tokens)",
+    Strategy.SYMMETRIC: "Separate secret    (a leaked access secret can't forge refresh tokens)",
+}
+
+
+
+def _parse_ttl(text: str) -> TTL:
+    try:
+        return TTL.parse(text)
+    except ValueError as e:
+        raise typer.BadParameter(str(e)) from None
+
+
+def _ttl_option(flag: str, default: TTL, token: str) -> typer.models.OptionInfo:
+    return typer.Option(
+        flag,
+        parser=_parse_ttl,
+        metavar="DURATION",
+        help=f"{token} token lifetime, e.g. 30m, 3h, 7d (default {default}). Prompts if omitted.",
+        show_default=False,
+    )
+
+
+def _choose_ttl(message: str, default: TTL, longer_than: TTL | None = None) -> TTL:
+    def validate(answer: str) -> bool | str:
+        try:
+            ttl = TTL.parse(answer)
+            if longer_than is not None:
+                validate_ttls(longer_than, ttl)
+        except ValueError as e:
+            return str(e)
+        return True
+
+    return TTL.parse(ui.text(message, str(default), validate))
+
+
+def add_auth(
+    transport: Annotated[
+        Transport | None,
+        typer.Option(help="How tokens travel: Authorization header or cookies.", show_default=False),
+    ] = None,
+    strategy: Annotated[
+        Strategy | None, typer.Option(help="Token signing strategy.", show_default=False)
+    ] = None,
+    algorithm: Annotated[
+        Algorithm | None,
+        typer.Option(
+            case_sensitive=False, help="Asymmetric JWT algorithm.", show_default=False
+        ),
+    ] = None,
+    rsa_bits: RsaBitsOption = None,
+    refresh_keys: Annotated[
+        RefreshKeys | None,
+        typer.Option(help="Sign refresh tokens with their own keys.", show_default=False),
+    ] = None,
+    access_ttl: Annotated[
+        TTL | None, _ttl_option("--access-ttl", DEFAULT_ACCESS_TTL, "Access")
+    ] = None,
+    refresh_ttl: Annotated[
+        TTL | None, _ttl_option("--refresh-ttl", DEFAULT_REFRESH_TTL, "Refresh")
+    ] = None,
+    hashing: Annotated[
+        Hashing | None, typer.Option(help="Password hashing.", show_default=False)
+    ] = None,
+    directory: Annotated[
+        Path, typer.Option("--dir", "-d", help="Directory for the generated package.")
+    ] = Path("auth"),
+    force: Annotated[
+        bool, typer.Option("--force", help="Overwrite existing auth files.")
+    ] = False,
+) -> None:
+    """Generate an auth package: JWT access/refresh tokens, password hashing, login/refresh/logout.
+
+    Prompts for any choice not given as an option.
+    """
+    transport = transport or ui.select(
+        "Authentication transport:",
+        {
+            Transport.HEADER: "JWT in Authorization header  (Bearer token)",
+            Transport.COOKIE: "JWT in cookies               (HttpOnly)",
+        },
+    )
+    strategy = strategy or ui.select(
+        "Token/signing strategy:",
+        {
+            Strategy.ASYMMETRIC: "Asymmetric  (private key signs, public key verifies)",
+            Strategy.SYMMETRIC: "Symmetric   (HS256, one shared secret)",
+        },
+    )
+    if strategy is Strategy.SYMMETRIC and algorithm:
+        raise typer.BadParameter("only applies to --strategy asymmetric", param_hint="--algorithm")
+    if strategy is Strategy.ASYMMETRIC:
+        algorithm = algorithm or choose_algorithm("Algorithm:", default=Algorithm.EdDSA)
+    check_rsa_bits(rsa_bits, algorithm)
+    refresh_keys = refresh_keys or ui.select(
+        "Refresh token keys:",
+        {
+            RefreshKeys.SHARED: "Same as access tokens",
+            RefreshKeys.SEPARATE: REFRESH_KEY_LABELS[strategy],
+        },
+    )
+    if algorithm is Algorithm.RS256 and rsa_bits is None:
+        # Existing keys get reused, so only ask for a size when new ones will be made.
+        separate = refresh_keys is RefreshKeys.SEPARATE
+        if any(not keys.private.exists() for keys in key_pairs(DEFAULT_SECRETS_DIR, separate)):
+            rsa_bits = choose_rsa_bits()
+    access_ttl = access_ttl or _choose_ttl("Access token TTL:", DEFAULT_ACCESS_TTL)
+    refresh_ttl = refresh_ttl or _choose_ttl(
+        "Refresh token TTL:", DEFAULT_REFRESH_TTL, longer_than=access_ttl
+    )
+    try:
+        validate_ttls(access_ttl, refresh_ttl)
+    except ValueError as e:
+        raise typer.BadParameter(str(e), param_hint="--access-ttl/--refresh-ttl") from None
+    hashing = hashing or ui.select(
+        "Password hashing:", {Hashing.ARGON2: "Argon2", Hashing.BCRYPT: "bcrypt"}
+    )
+
+    config = AuthConfig(
+        transport=transport,
+        hashing=hashing,
+        strategy=strategy,
+        algorithm=algorithm,
+        refresh_keys=refresh_keys,
+        access_ttl=access_ttl,
+        refresh_ttl=refresh_ttl,
+    )
+    try:
+        result = scaffold_auth(
+            config, directory, DEFAULT_SECRETS_DIR, rsa_key_size=rsa_bits, force=force
+        )
+    except AuthFilesExistError as e:
+        raise ui.fail(
+            f"Auth files already exist: {', '.join(map(str, e.paths))}. Use --force to overwrite."
+        )
+    except KeyMismatchError as e:
+        size = f" --rsa-bits {rsa_bits}" if rsa_bits else ""
+        target = " --refresh" if e.keys == KeyPair.in_dir(DEFAULT_SECRETS_DIR, refresh=True) else ""
+        raise ui.fail(
+            f"{e}.\nPick a matching option, or replace the keys with "
+            f"`pavilion add keys {algorithm}{size}{target} --force`.",
+            color=typer.colors.RED,
+        )
+
+    typer.secho(f"Generated {directory}/ ({config.describe()}):", fg=typer.colors.GREEN)
+    for path in result.files:
+        typer.echo(f"  {path}")
+    for path in result.removed:
+        typer.echo(f"  {path} (removed, not used by this configuration)")
+    for note in result.secrets_notes:
+        typer.echo(note)
+    deps = " ".join(f"'{d}'" if "[" in d else d for d in config.dependencies)
+    typer.echo(f"\nNext: uv add {deps}")

pavilion-0.1.0/src/pavilion/auth/config.py

@@ -0,0 +1,77 @@
+"""The choices behind a generated auth package."""
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from pavilion.auth.ttl import DEFAULT_ACCESS_TTL, DEFAULT_REFRESH_TTL, TTL
+from pavilion.keys.generate import Algorithm
+
+SYMMETRIC_ALGORITHM = "HS256"
+
+
+class Transport(StrEnum):
+    """How the access/refresh tokens travel between client and server."""
+
+    HEADER = "header"
+    COOKIE = "cookie"
+
+class Strategy(StrEnum):
+    ASYMMETRIC = "asymmetric"
+    SYMMETRIC = "symmetric"
+
+class Hashing(StrEnum):
+    ARGON2 = "argon2"
+    BCRYPT = "bcrypt"
+
+class RefreshKeys(StrEnum):
+    SHARED = "shared"
+    SEPARATE = "separate"
+
+# Output file name -> template path (relative to auth/templates), for every transport.
+COMMON_TEMPLATES = {
+    "__init__.py": "__init__.py.jinja",
+    "passwords.py": "passwords.py.jinja",
+    "tokens.py": "tokens.py.jinja",
+    "service.py": "service.py.jinja",
+}
+COOKIE_TEMPLATES = {"cookies.py": "cookies.py.jinja"}
+# Every file pavilion may generate, so `--force` can remove ones a new config doesn't use.
+ALL_OUTPUT_FILES = frozenset(COMMON_TEMPLATES) | frozenset(COOKIE_TEMPLATES)
+
+@dataclass(frozen=True)
+class AuthConfig:
+    transport: Transport
+    strategy: Strategy
+    hashing: Hashing
+    algorithm: Algorithm | None = None  # asymmetric only
+    refresh_keys: RefreshKeys = RefreshKeys.SHARED
+    access_ttl: TTL = DEFAULT_ACCESS_TTL
+    refresh_ttl: TTL = DEFAULT_REFRESH_TTL
+
+    @property
+    def separate_refresh_keys(self) -> bool:
+        return self.refresh_keys is RefreshKeys.SEPARATE
+
+    @property
+    def jwt_algorithm(self) -> str:
+        return str(self.algorithm) if self.strategy is Strategy.ASYMMETRIC else SYMMETRIC_ALGORITHM
+
+    @property
+    def templates(self) -> dict[str, str]:
+        """Output file name -> template path (relative to auth/templates)."""
+        if self.transport is Transport.COOKIE:
+            return COMMON_TEMPLATES | COOKIE_TEMPLATES
+        return COMMON_TEMPLATES
+
+    @property
+    def dependencies(self) -> list[str]:
+        # Asymmetric algorithms need PyJWT's `cryptography` extra.
+        jwt = "pyjwt[crypto]" if self.strategy is Strategy.ASYMMETRIC else "pyjwt"
+        return [jwt, "argon2-cffi" if self.hashing is Hashing.ARGON2 else "bcrypt"]
+
+    def describe(self) -> str:
+        hashing = "Argon2" if self.hashing is Hashing.ARGON2 else "bcrypt"
+        via = "cookies" if self.transport is Transport.COOKIE else "header"
+        refresh = ", separate refresh keys" if self.separate_refresh_keys else ""
+        ttls = f"access {self.access_ttl} / refresh {self.refresh_ttl}"
+        return f"JWT {self.jwt_algorithm} via {via} ({self.strategy}{refresh}), {ttls}, {hashing}"

pavilion-0.1.0/src/pavilion/auth/scaffold.py

@@ -0,0 +1,121 @@
+"""Rendering an auth package (tokens, cookies, password hashing, login/refresh/logout)."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from jinja2 import Environment, PackageLoader, StrictUndefined
+
+from pavilion.auth.config import ALL_OUTPUT_FILES, AuthConfig, Strategy, Transport
+from pavilion.keys.generate import (
+    Algorithm,
+    KeyPair,
+    check_keys,
+    ensure_keys,
+    ensure_secret,
+    read_rsa_key_size,
+    secret_path,
+)
+
+
+class AuthFilesExistError(Exception):
+    def __init__(self, paths: list[Path]):
+        super().__init__(", ".join(map(str, paths)))
+        self.paths = paths
+
+
+@dataclass(frozen=True)
+class AuthResult:
+    files: list[Path]
+    # Files from a previous run that this config doesn't use (deleted with --force).
+    removed: list[Path]
+    # Human-readable notes about the keys/secrets used: access first, then refresh.
+    secrets_notes: list[str]
+
+
+_env = Environment(
+    loader=PackageLoader("pavilion.auth", "templates"),
+    undefined=StrictUndefined,
+    trim_blocks=True,
+    lstrip_blocks=True,
+    keep_trailing_newline=True,
+)
+
+
+def key_pairs(secrets_dir: Path, separate_refresh_keys: bool) -> list[KeyPair]:
+    """Asymmetric key pairs used: access tokens first, then refresh tokens if separate."""
+    access = KeyPair.in_dir(secrets_dir)
+    if separate_refresh_keys:
+        return [access, KeyPair.in_dir(secrets_dir, refresh=True)]
+    return [access]
+
+
+def _prepare_secrets(
+    config: AuthConfig, secrets_dir: Path, rsa_key_size: int | None
+) -> list[str]:
+    def verb(created: bool) -> str:
+        return "Generated" if created else "Using existing"
+
+    if config.strategy is Strategy.SYMMETRIC:
+        paths = [secret_path(secrets_dir)]
+        if config.separate_refresh_keys:
+            paths.append(secret_path(secrets_dir, refresh=True))
+        return [f"{verb(ensure_secret(path))} HS256 secret: {path}" for path in paths]
+
+    assert config.algorithm is not None
+    pairs = key_pairs(secrets_dir, config.separate_refresh_keys)
+    # Validate every pair first so a mismatch in one doesn't leave new keys behind.
+    for keys in pairs:
+        check_keys(keys, config.algorithm, rsa_key_size)
+    notes = []
+    for keys in pairs:
+        created = ensure_keys(keys, config.algorithm, rsa_key_size)
+        label = str(config.algorithm)
+        if config.algorithm is Algorithm.RS256:
+            label += f" ({read_rsa_key_size(keys.private)}-bit)"
+        notes.append(f"{verb(created)} {label} key pair: {keys.private}, {keys.public}")
+    return notes
+
+
+def scaffold_auth(
+    config: AuthConfig,
+    directory: Path,
+    secrets_dir: Path,
+    *,
+    rsa_key_size: int | None = None,
+    force: bool = False,
+) -> AuthResult:
+    """Render the auth package into `directory` and make sure signing material exists.
+
+    `rsa_key_size` applies to newly generated RS256 keys (default 2048); when given,
+    existing RS256 keys must match it.
+
+    Raises AuthFilesExistError or KeyMismatchError before writing anything.
+    """
+    targets = {directory / name: template for name, template in config.templates.items()}
+    existing = sorted(p for name in ALL_OUTPUT_FILES if (p := directory / name).exists())
+    if existing and not force:
+        raise AuthFilesExistError(existing)
+    stale = [path for path in existing if path not in targets]
+
+    secrets_notes = _prepare_secrets(config, secrets_dir, rsa_key_size)
+
+    context = {
+        "cookie": config.transport is Transport.COOKIE,
+        "hashing": str(config.hashing),
+        "asymmetric": config.strategy is Strategy.ASYMMETRIC,
+        "algorithm": config.jwt_algorithm,
+        "separate_refresh_keys": config.separate_refresh_keys,
+        "access_ttl": config.access_ttl.python(),
+        "refresh_ttl": config.refresh_ttl.python(),
+        "access_keys": KeyPair.in_dir(secrets_dir),
+        "refresh_keys": KeyPair.in_dir(secrets_dir, refresh=True),
+        "access_secret": secret_path(secrets_dir).as_posix(),
+        "refresh_secret": secret_path(secrets_dir, refresh=True).as_posix(),
+        "package": directory.name,
+    }
+    directory.mkdir(parents=True, exist_ok=True)
+    for path, template in targets.items():
+        path.write_text(_env.get_template(template).render(context))
+    for path in stale:
+        path.unlink()
+    return AuthResult(files=list(targets), removed=stale, secrets_notes=secrets_notes)