aweb-naapp-testing 0.2.0__tar.gz

aweb_naapp_testing-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+.venv/
+dist/
+build/
+.DS_Store
+
+# Editor lock/autosave files
+.#*
+\#*\#
+*~

aweb_naapp_testing-0.2.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.5
+Name: aweb-naapp-testing
+Version: 0.2.0
+Summary: Test support for naapps on aweb-naapp: real AWID routes on PostgreSQL, a team-auth v2 signer, a software WebAuthn authenticator, a team owner-act signer and a real local SMTP server. Dev-only; never a production dependency.
+Author-email: "aweb.ai" <hello@aweb.ai>
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: aiosmtpd>=1.4.6
+Requires-Dist: aweb-naapp[hooks,runtime]==0.2.0
+Requires-Dist: awid-service>=0.5.30
+Requires-Dist: cbor2>=5.6.0
+Requires-Dist: cryptography>=46.0.0
+Requires-Dist: dnspython>=2.7.0

aweb_naapp_testing-0.2.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "aweb-naapp-testing"
+version = "0.2.0"
+description = "Test support for naapps on aweb-naapp: real AWID routes on PostgreSQL, a team-auth v2 signer, a software WebAuthn authenticator, a team owner-act signer and a real local SMTP server. Dev-only; never a production dependency."
+license = { text = "MIT" }
+authors = [{ name = "aweb.ai", email = "hello@aweb.ai" }]
+requires-python = ">=3.12"
+dependencies = [
+  "aiosmtpd>=1.4.6",
+  # Released in lockstep with aweb-naapp, from the same tag and at the same version.
+  "aweb-naapp[hooks,runtime]==0.2.0",
+  # The first awid release with the principal-attestation records the runtime reads.
+  "awid-service>=0.5.30",
+  "cbor2>=5.6.0",
+  "cryptography>=46.0.0",
+  "dnspython>=2.7.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aweb_naapp_testing"]
+
+[tool.uv.sources]
+aweb-naapp = { path = "..", editable = true }
+awid-service = { path = "../../awid", editable = true }

aweb_naapp_testing-0.2.0/src/aweb_naapp_testing/__init__.py

@@ -0,0 +1,267 @@
+"""Test support for naapps: real AWID routes on PostgreSQL, and a signer for
+team-auth v2 requests.
+
+The verifier reaches AWID through an in-process ASGI transport. Faults, when a
+test asks for them, are applied to a response only after the real AWID handler
+has produced it, so the cache code, the database and the pagination stay real.
+
+This is a dev-only distribution: it mints throwaway team keys and
+certificates, and no production install depends on it.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from collections.abc import AsyncIterator, Callable
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import httpx
+from awid.attestation_records import ATTESTATION_HEADER, encode_attestation_header, sign_record
+from awid.did import did_from_public_key
+from awid.ratelimit import NoOpRateLimiter
+from awid.registry import RegistryClient
+from awid.signing import canonical_json_bytes, sign_message
+from awid_service.db import AwidDatabaseInfra
+from awid_service.routes.attestation_records import router as awid_attestation_records_router
+from awid_service.routes.did import router as awid_did_router
+from awid_service.routes.teams import router as awid_teams_router
+from fastapi import FastAPI
+from nacl.signing import SigningKey
+from pgdbm import AsyncDatabaseManager, DatabaseConfig
+
+REGISTRY_URL = "https://registry.example"
+SERVICE_TOKEN = "runtime-test-service-token-32-bytes"
+
+ResponseFault = Callable[[httpx.Request, httpx.Response], None]
+
+
+class RecordingTransport(httpx.AsyncBaseTransport):
+    """Delivers every request to real AWID, records it, then applies `fault`."""
+
+    def __init__(self, app: FastAPI) -> None:
+        self._inner = httpx.ASGITransport(app=app)
+        self.calls: list[httpx.Request] = []
+        self.fault: ResponseFault | None = None
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        self.calls.append(request)
+        response = await self._inner.handle_async_request(request)
+        if self.fault is None:
+            return response
+        await response.aread()
+        self.fault(request, response)
+        return response
+
+
+@dataclass
+class Registry:
+    db: Any
+    transport: RecordingTransport
+
+    async def add_team(self, team_id: str, team_did_key: str, *, visibility: str = "public") -> None:
+        name, domain = team_id.split(":", 1)
+        await self.db.execute(
+            "INSERT INTO {{tables.teams}} (domain, name, team_did_key, visibility) VALUES ($1, $2, $3, $4)",
+            domain, name, team_did_key, visibility,
+        )
+
+    async def add_certificate(self, cert: dict[str, Any]) -> None:
+        name, domain = cert["team_id"].split(":", 1)
+        await self.db.execute(
+            "INSERT INTO {{tables.team_certificates}} "
+            "(team_uuid, certificate_id, member_did_key, alias, issued_at) "
+            "SELECT team_uuid, $3, $4, $5, now() FROM {{tables.teams}} WHERE domain = $1 AND name = $2",
+            domain, name, cert["certificate_id"], cert["member_did_key"], cert["alias"],
+        )
+
+    async def revoke(self, certificate_id: str) -> None:
+        await self.db.execute(
+            "UPDATE {{tables.team_certificates}} SET revoked_at = now() WHERE certificate_id = $1",
+            certificate_id,
+        )
+
+    def _client(self) -> RegistryClient:
+        return RegistryClient(registry_url=REGISTRY_URL, transport=self.transport)
+
+    async def register_did(self, key: SigningKey) -> str:
+        """Registers `key` as a new did:aw through AWID's own route; returns the did:aw."""
+        mapping = await self._client().register_did(did_key(key), bytes(key))
+        return mapping.did_aw
+
+    async def rotate_did(self, did_aw: str, old: SigningKey, new: SigningKey) -> None:
+        await self._client().rotate_key(did_aw, did_key(new), bytes(old), bytes(new))
+
+    async def add_custody(self, member: Member, *, custodian_id: str, issuer: SigningKey) -> None:
+        """Publish team-signed records: ``custodian_id`` attests with ``issuer``,
+        and holds ``member``'s certificate."""
+        name, domain = member.team_id.split(":", 1)
+        issued_at = datetime.now(UTC).replace(microsecond=0)
+        common = {"v": 1, "team_id": member.team_id, "team_did_key": member.team_did_key,
+                  "custodian_id": custodian_id, "issued_at": utc_timestamp(issued_at)}
+        custodian = {**common, "type": "aweb.team-custodian", "issuer_did_keys": [did_key(issuer)]}
+        custody = {**common, "type": "aweb.member-custody", "certificate_id": member.certificate_id,
+                   "member_did_key": member.did_key}
+        for table, key_column, record, extra in (
+            ("team_custodians", "custodian_id", custodian, {}),
+            ("member_custody", "certificate_id", custody, {"custodian_id": custodian_id}),
+        ):
+            columns = "".join(f", {column}" for column in extra)
+            values = "".join(f", ${8 + i}" for i in range(len(extra)))
+            await self.db.execute(
+                f"INSERT INTO {{{{tables.{table}}}}} "
+                f"(team_uuid, {key_column}, record_json, signature, team_did_key, issued_at{columns}) "
+                f"SELECT team_uuid, $1, $2, $3, $4, $5::timestamptz{values} FROM {{{{tables.teams}}}} "
+                "WHERE domain = $6 AND name = $7",
+                record[key_column], canonical_json_bytes(record).decode(),
+                sign_record(bytes(member.team_key), record), member.team_did_key,
+                issued_at, domain, name, *extra.values(),
+            )
+
+    async def rotate_team_key(self, team_id: str, team_did_key: str) -> None:
+        name, domain = team_id.split(":", 1)
+        await self.db.execute(
+            "UPDATE {{tables.teams}} SET team_did_key = $3 WHERE domain = $1 AND name = $2",
+            domain, name, team_did_key,
+        )
+
+
+@asynccontextmanager
+async def awid_registry(database_url: str) -> AsyncIterator[Registry]:
+    """Real AWID, with its migrations applied, on the empty database at
+    ``database_url``, reachable through ``Registry.transport``."""
+    pool = await AsyncDatabaseManager.create_shared_pool(
+        DatabaseConfig(connection_string=database_url, schema=None)
+    )
+    infra = AwidDatabaseInfra(schema="awid")
+    try:
+        await infra.initialize(shared_pool=pool, run_migrations=True)
+        app = FastAPI()
+        app.state.db = infra
+        app.state.rate_limiter = NoOpRateLimiter()
+        app.state.awid_service_token = SERVICE_TOKEN
+        app.include_router(awid_teams_router)
+        app.include_router(awid_attestation_records_router)
+        app.include_router(awid_did_router)
+        yield Registry(db=infra.get_manager("aweb"), transport=RecordingTransport(app))
+    finally:
+        await infra.close()
+        await pool.close()
+
+
+def did_key(key: SigningKey) -> str:
+    return did_from_public_key(bytes(key.verify_key))
+
+
+def utc_timestamp(moment: datetime) -> str:
+    return moment.astimezone(UTC).isoformat().replace("+00:00", "Z")
+
+
+@dataclass
+class Member:
+    """A team key and one member certificate signed by it."""
+
+    team_id: str
+    team_key: SigningKey = field(default_factory=SigningKey.generate)
+    member_key: SigningKey = field(default_factory=SigningKey.generate)
+    certificate_id: str = "cert-1"
+    alias: str = "alice"
+    extra_cert_fields: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def team_did_key(self) -> str:
+        return did_key(self.team_key)
+
+    @property
+    def did_key(self) -> str:
+        return did_key(self.member_key)
+
+    def certificate(self) -> dict[str, Any]:
+        cert = {
+            "version": 1,
+            "certificate_id": self.certificate_id,
+            "team_id": self.team_id,
+            "team_did_key": self.team_did_key,
+            "member_did_key": self.did_key,
+            "alias": self.alias,
+            "lifetime": "persistent",
+            "issued_at": "2026-01-01T00:00:00Z",
+            **self.extra_cert_fields,
+        }
+        cert["signature"] = sign_message(bytes(self.team_key), canonical_json_bytes(cert))
+        return cert
+
+    def headers(
+        self,
+        *,
+        aud: str,
+        method: str,
+        path: str,
+        body: bytes = b"",
+        timestamp: str | None = None,
+        payload_changes: dict[str, Any] | None = None,
+        cert: dict[str, Any] | None = None,
+    ) -> dict[str, str]:
+        timestamp = timestamp or utc_timestamp(datetime.now(UTC))
+        payload: dict[str, Any] = {
+            "v": 2,
+            "aud": aud,
+            "method": method,
+            "path": path,
+            "team_id": self.team_id,
+            "timestamp": timestamp,
+            "body_sha256": hashlib.sha256(body).hexdigest(),
+        }
+        for name, value in (payload_changes or {}).items():
+            if value is None:
+                payload.pop(name, None)
+            else:
+                payload[name] = value
+        canonical = canonical_json_bytes(payload)
+        return envelope_headers(
+            did_key=self.did_key,
+            signature=sign_message(bytes(self.member_key), canonical),
+            timestamp=timestamp,
+            signed_payload=canonical,
+            cert=cert if cert is not None else self.certificate(),
+        )
+
+
+def attested(
+    member: Member, headers: dict[str, str], *, issuer: SigningKey, custodian_id: str, channel: str
+) -> dict[str, str]:
+    """``headers`` plus a principal attestation by ``issuer``, bound to their signed payload."""
+    raw = headers["X-AWEB-Signed-Payload"]
+    signed_payload = base64.urlsafe_b64decode(raw + "=" * (-len(raw) % 4))
+    now = datetime.now(UTC).replace(microsecond=0)
+    payload = {
+        "v": 1,
+        "type": "aweb.principal-attestation",
+        "team_id": member.team_id,
+        "certificate_id": member.certificate_id,
+        "member_did_key": member.did_key,
+        "custody": "custodial",
+        "custodian_id": custodian_id,
+        "issuer_did_key": did_key(issuer),
+        "channel": channel,
+        "session_id": "session-1",
+        "iat": utc_timestamp(now),
+        "exp": utc_timestamp(now + timedelta(seconds=120)),
+        "request_binding": hashlib.sha256(signed_payload).hexdigest(),
+    }
+    return {**headers, ATTESTATION_HEADER: encode_attestation_header(bytes(issuer), payload)}
+
+
+def envelope_headers(
+    *, did_key: str, signature: str, timestamp: str, signed_payload: bytes, cert: dict[str, Any]
+) -> dict[str, str]:
+    return {
+        "Authorization": f"DIDKey {did_key} {signature}",
+        "X-AWEB-Timestamp": timestamp,
+        "X-AWEB-Signed-Payload": base64.urlsafe_b64encode(signed_payload).rstrip(b"=").decode(),
+        "X-AWID-Team-Certificate": base64.b64encode(json.dumps(cert).encode()).decode(),
+    }

aweb_naapp_testing-0.2.0/src/aweb_naapp_testing/databases.py

@@ -0,0 +1,27 @@
+"""Test databases that give each naapp test its own schema.
+
+A naapp runs in its own schema: the candidate gate's role carries production's
+search_path=pg_catalog, where an unqualified table resolves to no user schema
+at all. With a schema configured, pgdbm pins the search_path to it on every
+connection.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pgdbm import AsyncDatabaseManager
+
+TEST_SCHEMA = "naapp_test"
+
+
+class SchemaDatabases:
+    """pgdbm's test database factory, giving every database a schema unless the test names one."""
+
+    def __init__(self, factory: Any) -> None:
+        self._factory = factory
+
+    async def create_db(
+        self, suffix: str | None = None, schema: str | None = None, **kwargs: Any
+    ) -> AsyncDatabaseManager:
+        return await self._factory.create_db(suffix, schema or TEST_SCHEMA, **kwargs)

aweb_naapp_testing-0.2.0/src/aweb_naapp_testing/network.py

@@ -0,0 +1,293 @@
+"""Real local DNS and TLS servers for network tests through the egress guard.
+
+The DNS server answers A and AAAA queries from a table the test controls and
+counts every query, so a test can change an answer between two lookups. The
+TLS server presents a certificate from a throwaway CA, records the SNI name,
+request line and headers of every request, and serves a few fixed paths, or
+whatever its ``respond`` callback answers.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import datetime
+import gzip
+import ipaddress
+import json
+import socket
+import ssl
+from collections import Counter
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import dns.flags
+import dns.message
+import dns.rcode
+import dns.rdataclass
+import dns.rdatatype
+import dns.rrset
+from cryptography import x509
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.x509.oid import NameOID
+
+Answer = list[str] | Callable[[int], list[str]]
+
+
+def local_address() -> str:
+    """This host's own non-loopback IPv4 address.
+
+    The guard refuses loopback for every destination, internal ones included,
+    so the TLS server listens on one of the host's own addresses: the one its
+    outbound route uses, or, on a network with no route out (the gate's
+    isolated runner), one its own name resolves to locally. Connecting a UDP
+    socket sends nothing; it only picks the route.
+    """
+    for address in _route_address(), *_named_addresses():
+        if address is not None and not ipaddress.ip_address(address).is_loopback:
+            return address
+    raise RuntimeError("the egress network tests need a non-loopback IPv4 address on this host")
+
+
+def _route_address() -> str | None:
+    probe = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        probe.connect(("192.0.2.1", 9))
+        return str(probe.getsockname()[0])
+    except OSError:
+        return None
+    finally:
+        probe.close()
+
+
+def _named_addresses() -> list[str]:
+    try:
+        infos = socket.getaddrinfo(socket.gethostname(), None, socket.AF_INET)
+    except OSError:
+        return []
+    return [str(info[4][0]) for info in infos]
+
+
+@dataclass
+class DnsServer:
+    """Answers ``records[(name, "A"|"AAAA")]``; a callable gets the query count."""
+
+    records: dict[tuple[str, str], Answer] = field(default_factory=dict)
+    queries: Counter[tuple[str, str]] = field(default_factory=Counter)
+    # Seconds to wait before each answer, as a slow resolver would.
+    delay: float = 0.0
+    port: int = 0
+    _transport: asyncio.DatagramTransport | None = None
+
+    async def start(self) -> None:
+        loop = asyncio.get_running_loop()
+        server = self
+
+        class Protocol(asyncio.DatagramProtocol):
+            def connection_made(self, transport: asyncio.BaseTransport) -> None:
+                self.transport = transport
+
+            def datagram_received(self, data: bytes, addr: tuple[str, int]) -> None:
+                answer = server._answer(data)
+                send = self.transport.sendto  # type: ignore[attr-defined]
+                if server.delay:
+                    loop.call_later(server.delay, send, answer, addr)
+                else:
+                    send(answer, addr)
+
+        transport, _ = await loop.create_datagram_endpoint(Protocol, local_addr=("127.0.0.1", 0))
+        self._transport = transport  # type: ignore[assignment]
+        self.port = transport.get_extra_info("sockname")[1]
+
+    def close(self) -> None:
+        if self._transport is not None:
+            self._transport.close()
+
+    def _answer(self, wire: bytes) -> bytes:
+        query = dns.message.from_wire(wire)
+        response = dns.message.make_response(query)
+        response.flags |= dns.flags.AA
+        question = query.question[0]
+        name = question.name.to_text(omit_final_dot=True).lower()
+        kind = dns.rdatatype.to_text(question.rdtype)
+        self.queries[(name, kind)] += 1
+        if not any(key[0] == name for key in self.records):
+            response.set_rcode(dns.rcode.NXDOMAIN)
+            return response.to_wire()
+        answer = self.records.get((name, kind), [])
+        values = answer(self.queries[(name, kind)]) if callable(answer) else answer
+        if values:
+            response.answer.append(
+                dns.rrset.from_text_list(question.name, 60, dns.rdataclass.IN, kind, values)
+            )
+        return response.to_wire()
+
+
+@dataclass(frozen=True)
+class Certificates:
+    ca_file: Path
+    cert_file: Path
+    key_file: Path
+
+
+def make_certificates(directory: Path, names: list[str], addresses: list[str]) -> Certificates:
+    """A throwaway CA and a server certificate for ``names`` and ``addresses``."""
+    now = datetime.datetime.now(datetime.UTC)
+    ca_key = ec.generate_private_key(ec.SECP256R1())
+    ca_name = x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, "egress test CA")])
+    ca = (
+        x509.CertificateBuilder()
+        .subject_name(ca_name)
+        .issuer_name(ca_name)
+        .public_key(ca_key.public_key())
+        .serial_number(x509.random_serial_number())
+        .not_valid_before(now - datetime.timedelta(minutes=5))
+        .not_valid_after(now + datetime.timedelta(hours=1))
+        .add_extension(x509.BasicConstraints(ca=True, path_length=None), critical=True)
+        .add_extension(
+            x509.KeyUsage(
+                digital_signature=True,
+                content_commitment=False,
+                key_encipherment=False,
+                data_encipherment=False,
+                key_agreement=False,
+                key_cert_sign=True,
+                crl_sign=True,
+                encipher_only=False,
+                decipher_only=False,
+            ),
+            critical=True,
+        )
+        .add_extension(
+            x509.SubjectKeyIdentifier.from_public_key(ca_key.public_key()), critical=False
+        )
+        .sign(ca_key, hashes.SHA256())
+    )
+    key = ec.generate_private_key(ec.SECP256R1())
+    alt_names: list[x509.GeneralName] = [x509.DNSName(name) for name in names]
+    alt_names += [x509.IPAddress(ipaddress.ip_address(address)) for address in addresses]
+    cert = (
+        x509.CertificateBuilder()
+        .subject_name(x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, names[0])]))
+        .issuer_name(ca_name)
+        .public_key(key.public_key())
+        .serial_number(x509.random_serial_number())
+        .not_valid_before(now - datetime.timedelta(minutes=5))
+        .not_valid_after(now + datetime.timedelta(hours=1))
+        .add_extension(x509.SubjectAlternativeName(alt_names), critical=False)
+        .add_extension(x509.BasicConstraints(ca=False, path_length=None), critical=True)
+        .add_extension(
+            x509.ExtendedKeyUsage([x509.oid.ExtendedKeyUsageOID.SERVER_AUTH]), critical=False
+        )
+        .add_extension(
+            x509.AuthorityKeyIdentifier.from_issuer_public_key(ca_key.public_key()),
+            critical=False,
+        )
+        .sign(ca_key, hashes.SHA256())
+    )
+    paths = Certificates(directory / "ca.pem", directory / "server.pem", directory / "server.key")
+    paths.ca_file.write_bytes(ca.public_bytes(serialization.Encoding.PEM))
+    paths.cert_file.write_bytes(cert.public_bytes(serialization.Encoding.PEM))
+    paths.key_file.write_bytes(
+        key.private_bytes(
+            serialization.Encoding.PEM,
+            serialization.PrivateFormat.PKCS8,
+            serialization.NoEncryption(),
+        )
+    )
+    return paths
+
+
+@dataclass
+class Seen:
+    sni: str | None
+    request_line: str
+    headers: list[tuple[str, str]]
+    body: bytes
+
+
+Reply = tuple[int, bytes, list[tuple[str, str]]]
+
+
+@dataclass
+class TlsServer:
+    """An HTTPS/1.1 server on ``host`` with a few fixed paths.
+
+    ``/ok`` answers JSON, ``/redirect`` answers 302 to another host,
+    ``/big?n=`` answers ``n`` bytes, ``/slow`` never answers, ``/encoded``
+    answers a gzip-encoded body, and ``/echo`` returns the request it saw as
+    JSON. When ``respond`` is set it answers every request instead, with a
+    status, a body and headers.
+    """
+
+    certificates: Certificates
+    host: str
+    seen: list[Seen] = field(default_factory=list)
+    respond: Callable[[Seen], Awaitable[Reply]] | None = None
+    port: int = 0
+    _server: asyncio.Server | None = None
+
+    async def start(self) -> None:
+        context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
+        context.load_cert_chain(self.certificates.cert_file, self.certificates.key_file)
+        sni: dict[int, str | None] = {}
+
+        def remember(sock: ssl.SSLObject, name: str | None, _: ssl.SSLContext) -> None:
+            sni[id(sock)] = name
+
+        context.sni_callback = remember  # type: ignore[assignment]
+
+        async def handle(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+            try:
+                await self._handle(reader, writer, sni.get(id(writer.get_extra_info("ssl_object"))))
+            except (ConnectionError, asyncio.IncompleteReadError, ssl.SSLError):
+                pass
+            finally:
+                writer.close()
+
+        self._server = await asyncio.start_server(handle, self.host, 0, ssl=context)
+        self.port = self._server.sockets[0].getsockname()[1]
+
+    async def close(self) -> None:
+        if self._server is not None:
+            self._server.close()
+            await self._server.wait_closed()
+
+    async def _handle(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter, sni: str | None
+    ) -> None:
+        head = await reader.readuntil(b"\r\n\r\n")
+        lines = head.decode("latin-1").split("\r\n")
+        headers = [tuple(line.split(": ", 1)) for line in lines[1:] if line]
+        length = next((int(v) for k, v in headers if k.lower() == "content-length"), 0)
+        body = await reader.readexactly(length) if length else b""
+        seen = Seen(sni, lines[0], [(k, v) for k, v in headers], body)
+        self.seen.append(seen)
+        if self.respond is not None:
+            status, reply, reply_headers = await self.respond(seen)
+            await _respond(writer, status, reply, reply_headers)
+            return
+        path = lines[0].split(" ")[1]
+        if path == "/slow":
+            await asyncio.sleep(3600)
+        if path == "/redirect":
+            await _respond(writer, 302, b"", [("Location", "https://elsewhere.example/next")])
+        elif path.startswith("/big?n="):
+            await _respond(writer, 200, b"x" * int(path.split("=")[1]), [])
+        elif path == "/encoded":
+            await _respond(writer, 200, gzip.compress(b"hidden"), [("Content-Encoding", "gzip")])
+        elif path == "/echo":
+            echoed = {"request_line": seen.request_line, "headers": seen.headers, "sni": sni}
+            await _respond(writer, 200, json.dumps(echoed).encode(), [])
+        else:
+            await _respond(writer, 200, b'{"ok": true}', [("Content-Type", "application/json")])
+
+
+async def _respond(
+    writer: asyncio.StreamWriter, status: int, body: bytes, headers: list[tuple[str, str]]
+) -> None:
+    head = [f"HTTP/1.1 {status} X", f"Content-Length: {len(body)}", "Connection: close"]
+    head += [f"{name}: {value}" for name, value in headers]
+    writer.write(("\r\n".join(head) + "\r\n\r\n").encode("latin-1") + body)
+    await writer.drain()

aweb_naapp_testing-0.2.0/src/aweb_naapp_testing/owner_acts.py

@@ -0,0 +1,104 @@
+"""Real team owner acts for tests.
+
+The team key is registered in the tests' AWID registry, and every act is a
+signed ``aweb.owner-act/1`` verified by the real K2 verifier, its nonce
+consumed in the transaction that applies the act's effect.
+"""
+
+from __future__ import annotations
+
+import base64
+import secrets
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+from nacl.signing import SigningKey
+from pgdbm.core import TransactionManager
+
+from aweb_naapp.hooks.owner_act import APP_ACTS, PREFIX, VerifiedOwnerAct
+from aweb_naapp.hooks.owner_act_nonces import OwnerActVerifier, PreparedOwnerAct
+from aweb_naapp.hooks.strictjson import canonical
+from aweb_naapp.runtime.passkeys import contact_sha256
+from aweb_naapp.runtime.team_auth import AWIDTeamCache
+from aweb_naapp_testing import REGISTRY_URL, SERVICE_TOKEN, did_key
+
+TEAM_ID = "demo:example.com"
+AUDIENCE = "https://app.example.com"
+APP_ID = "example"
+INSTALLATION_ID = "1b4e28ba-2fa1-4d3b-a3f5-ef19b5a7633b"
+
+
+@dataclass
+class TeamOwner:
+    """The team's owner: signs acts with the team key the registry knows."""
+
+    team_key: SigningKey
+    verifier: OwnerActVerifier
+    team_id: str = TEAM_ID
+
+    def sign(self, act: str, subject: dict[str, Any]) -> tuple[bytes, str]:
+        issued = datetime.now(UTC).replace(microsecond=0)
+        fields = {
+            "v": 1,
+            "type": "aweb.owner-act",
+            "act": act,
+            "team_id": self.team_id,
+            "aud": AUDIENCE,
+            "team_key_did": did_key(self.team_key),
+            "subject": subject,
+            "issued_at": issued.strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "expires_at": (issued + timedelta(minutes=5)).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "nonce": secrets.token_hex(16),
+        }
+        signing = PREFIX + canonical(fields)
+        signature = base64.b64encode(self.team_key.sign(signing).signature).decode().rstrip("=")
+        return signing, signature
+
+    async def prepare(self, act: str, subject: dict[str, Any]) -> PreparedOwnerAct:
+        signing, signature = self.sign(act, subject)
+        return await self.verifier.prepare(signing, signature, team_id=self.team_id)
+
+    async def consume(
+        self, tx: TransactionManager, prepared: PreparedOwnerAct, subject: dict[str, Any]
+    ) -> VerifiedOwnerAct:
+        return await self.verifier.consume_in(tx, prepared, expected_subject=subject)
+
+
+def designation_subject(scope: str, contact: str) -> dict[str, Any]:
+    """The subject of an act that designates, or recovers, ``scope``'s approver."""
+    return {
+        "app_id": APP_ID,
+        "installation_id": INSTALLATION_ID,
+        "role": scope,
+        "contact_sha256": contact_sha256(contact),
+    }
+
+
+def revocation_subject(scope: str, subject_ref: str) -> dict[str, Any]:
+    return {
+        "app_id": APP_ID,
+        "installation_id": INSTALLATION_ID,
+        "role": scope,
+        "subject_ref": subject_ref,
+    }
+
+
+async def team_owner(registry, *, team_id: str = TEAM_ID) -> TeamOwner:
+    """Register a real owner key for the team the app fixture actually uses."""
+    key = SigningKey.generate()
+    await registry.add_team(team_id, did_key(key))
+    cache = AWIDTeamCache(
+        registry_url=REGISTRY_URL,
+        ttl_seconds=0,
+        service_token=SERVICE_TOKEN,
+        transport=registry.transport,
+    )
+
+    async def current_team_key(team_id: str) -> str:
+        return (await cache.get(team_id)).team_did_key
+
+    verifier = OwnerActVerifier(
+        scope=APP_ID, audience=AUDIENCE, acts=APP_ACTS, team_key_for=current_team_key
+    )
+    return TeamOwner(team_key=key, verifier=verifier, team_id=team_id)

aweb_naapp_testing-0.2.0/src/aweb_naapp_testing/smtp.py

@@ -0,0 +1,150 @@
+"""A real SMTP server on this host for tests (aiosmtpd), so mail is delivered
+and refused by an actual server rather than a stand-in.
+
+The server listens on 127.0.0.1 with a throwaway certificate for ``localhost``
+(:func:`aweb_naapp_testing.network.make_certificates`). It offers STARTTLS,
+implicit TLS, or neither, and accepts one username and password, only over
+TLS. Recipients in ``refuse`` are rejected; every accepted message is kept in
+``received``. :class:`SilentServer` accepts connections and never answers, for
+timeouts.
+"""
+
+from __future__ import annotations
+
+import logging
+import socket
+import ssl
+import threading
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+from aiosmtpd.controller import Controller
+from aiosmtpd.smtp import AuthResult, LoginPassword
+
+from aweb_naapp_testing.network import Certificates, make_certificates
+
+Mode = Literal["starttls", "implicit", "plain"]
+# aiosmtpd 1.4.6 logs a deprecation of its own Session.login_data on every
+# successful AUTH, even through the current authenticator API.
+logging.getLogger("mail.log").setLevel(logging.ERROR)
+HOST = "localhost"
+ADDRESS = "127.0.0.1"
+
+
+def _free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+        probe.bind((ADDRESS, 0))
+        return int(probe.getsockname()[1])
+
+
+@dataclass
+class Received:
+    mail_from: str
+    rcpt_tos: list[str]
+    content: bytes
+
+
+@dataclass
+class SmtpServer:
+    """A running SMTP server; use it as a context manager."""
+
+    directory: Path
+    mode: Mode = "starttls"
+    username: str = "mailer"
+    password: str = "smtp-test-password"
+    refuse: set[str] = field(default_factory=set)
+    received: list[Received] = field(default_factory=list)
+    port: int = 0
+    certificates: Certificates | None = None
+    _controller: Controller | None = None
+
+    def __enter__(self) -> SmtpServer:
+        self.directory.mkdir(parents=True, exist_ok=True)
+        self.certificates = make_certificates(self.directory, [HOST], [ADDRESS])
+        context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
+        context.load_cert_chain(self.certificates.cert_file, self.certificates.key_file)
+        self.port = _free_port()
+        options: dict[str, Any] = dict(
+            hostname=ADDRESS,
+            port=self.port,
+            server_hostname=HOST,
+            authenticator=self._authenticate,
+            # aiosmtpd counts only STARTTLS as TLS, so an implicit-TLS session
+            # would be refused AUTH if it were required here.
+            auth_require_tls=self.mode == "starttls",
+        )
+        if self.mode == "starttls":
+            options.update(tls_context=context, require_starttls=True)
+        elif self.mode == "implicit":
+            options.update(ssl_context=context)
+        self._controller = Controller(self, **options)
+        self._controller.start()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        if self._controller is not None:
+            self._controller.stop()
+            self._controller = None
+
+    @property
+    def ca_file(self) -> Path:
+        assert self.certificates is not None
+        return self.certificates.ca_file
+
+    def _authenticate(
+        self, server: Any, session: Any, envelope: Any, mechanism: str, auth_data: Any
+    ) -> AuthResult:
+        ok = (
+            isinstance(auth_data, LoginPassword)
+            and auth_data.login.decode() == self.username
+            and auth_data.password.decode() == self.password
+        )
+        return AuthResult(success=ok, handled=False)
+
+    async def handle_RCPT(
+        self, server: Any, session: Any, envelope: Any, address: str, rcpt_options: list[str]
+    ) -> str:
+        if address in self.refuse:
+            return "550 5.1.1 recipient refused"
+        envelope.rcpt_tos.append(address)
+        return "250 OK"
+
+    async def handle_DATA(self, server: Any, session: Any, envelope: Any) -> str:
+        self.received.append(
+            Received(envelope.mail_from, list(envelope.rcpt_tos), bytes(envelope.original_content))
+        )
+        return "250 Message accepted"
+
+
+class SilentServer:
+    """Accepts connections and never sends a greeting; use it as a context manager."""
+
+    def __init__(self) -> None:
+        self._socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self._socket.bind((ADDRESS, 0))
+        self.port = int(self._socket.getsockname()[1])
+        self._accepted: list[socket.socket] = []
+        self._stop = threading.Event()
+
+    def __enter__(self) -> SilentServer:
+        self._socket.listen()
+        self._socket.settimeout(0.1)
+        threading.Thread(target=self._serve, daemon=True).start()
+        return self
+
+    def _serve(self) -> None:
+        while not self._stop.is_set():
+            try:
+                connection, _ = self._socket.accept()
+            except TimeoutError:
+                continue
+            except OSError:
+                return
+            self._accepted.append(connection)
+
+    def __exit__(self, *exc: object) -> None:
+        self._stop.set()
+        for connection in self._accepted:
+            connection.close()
+        self._socket.close()

aweb_naapp_testing-0.2.0/src/aweb_naapp_testing/webauthn.py

@@ -0,0 +1,166 @@
+"""A software WebAuthn authenticator for tests.
+
+It answers the server's real options with real ceremonies: a P-256 credential
+key, CBOR authenticator data, a `packed` self-attestation and ES256 assertion
+signatures over authenticator data and the client data hash, as a platform
+authenticator and browser would produce them. The verifier under test checks
+these with py_webauthn exactly as it checks a browser's.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import struct
+from base64 import urlsafe_b64decode, urlsafe_b64encode
+from dataclasses import dataclass
+
+import cbor2
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import ec
+
+UP, UV, AT = 0x01, 0x04, 0x40
+ES256 = -7
+
+
+def b64url(data: bytes) -> str:
+    return urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def from_b64url(text: str) -> bytes:
+    return urlsafe_b64decode(text + "=" * (-len(text) % 4))
+
+
+@dataclass
+class SoftCredential:
+    credential_id: bytes
+    key: ec.EllipticCurvePrivateKey
+    rp_id: str
+    user_handle: bytes
+    sign_count: int = 0
+
+    def cose_public_key(self) -> bytes:
+        numbers = self.key.public_key().public_numbers()
+        return cbor2.dumps(
+            {
+                1: 2,
+                3: ES256,
+                -1: 1,
+                -2: numbers.x.to_bytes(32, "big"),
+                -3: numbers.y.to_bytes(32, "big"),
+            }
+        )
+
+
+class SoftAuthenticator:
+    def __init__(self, origin: str) -> None:
+        self.origin = origin
+        self.credentials: dict[bytes, SoftCredential] = {}
+
+    def _client_data(self, kind: str, challenge: str, origin: str | None) -> bytes:
+        return json.dumps(
+            {
+                "type": kind,
+                "challenge": challenge,
+                "origin": origin or self.origin,
+                "crossOrigin": False,
+            }
+        ).encode()
+
+    def _sign(self, key: ec.EllipticCurvePrivateKey, auth_data: bytes, client_data: bytes) -> bytes:
+        return key.sign(auth_data + hashlib.sha256(client_data).digest(), ec.ECDSA(hashes.SHA256()))
+
+    def create(
+        self, options: dict, *, origin: str | None = None, user_verified: bool = True
+    ) -> dict:
+        """navigator.credentials.create() for the server's registration options."""
+        rp_id = options["rp"]["id"]
+        credential = SoftCredential(
+            credential_id=os.urandom(32),
+            key=ec.generate_private_key(ec.SECP256R1()),
+            rp_id=rp_id,
+            user_handle=from_b64url(options["user"]["id"]),
+        )
+        flags = UP | AT | (UV if user_verified else 0)
+        attested = (
+            bytes(16)
+            + struct.pack(">H", len(credential.credential_id))
+            + credential.credential_id
+            + credential.cose_public_key()
+        )
+        auth_data = (
+            hashlib.sha256(rp_id.encode()).digest()
+            + bytes([flags])
+            + struct.pack(">I", credential.sign_count)
+            + attested
+        )
+        client_data = self._client_data("webauthn.create", options["challenge"], origin)
+        attestation = cbor2.dumps(
+            {
+                "fmt": "packed",
+                "attStmt": {
+                    "alg": ES256,
+                    "sig": self._sign(credential.key, auth_data, client_data),
+                },
+                "authData": auth_data,
+            }
+        )
+        self.credentials[credential.credential_id] = credential
+        return {
+            "id": b64url(credential.credential_id),
+            "rawId": b64url(credential.credential_id),
+            "type": "public-key",
+            "response": {
+                "clientDataJSON": b64url(client_data),
+                "attestationObject": b64url(attestation),
+                "transports": ["internal"],
+            },
+            "clientExtensionResults": {},
+            "authenticatorAttachment": "platform",
+        }
+
+    def get(
+        self,
+        options: dict,
+        *,
+        origin: str | None = None,
+        user_verified: bool = True,
+        count_step: int = 1,
+    ) -> dict:
+        """navigator.credentials.get() for the server's authentication options."""
+        allowed = [c for c in self.credentials.values() if c.rp_id == options["rpId"]]
+        allow_ids = {item["id"] for item in options.get("allowCredentials", [])}
+        if allow_ids:
+            allowed = [c for c in allowed if b64url(c.credential_id) in allow_ids] or allowed
+        credential = allowed[0]
+        credential.sign_count += count_step
+        flags = UP | (UV if user_verified else 0)
+        auth_data = (
+            hashlib.sha256(credential.rp_id.encode()).digest()
+            + bytes([flags])
+            + struct.pack(">I", credential.sign_count)
+        )
+        client_data = self._client_data("webauthn.get", options["challenge"], origin)
+        return {
+            "id": b64url(credential.credential_id),
+            "rawId": b64url(credential.credential_id),
+            "type": "public-key",
+            "response": {
+                "clientDataJSON": b64url(client_data),
+                "authenticatorData": b64url(auth_data),
+                "signature": b64url(self._sign(credential.key, auth_data, client_data)),
+                "userHandle": b64url(credential.user_handle),
+            },
+            "clientExtensionResults": {},
+            "authenticatorAttachment": "platform",
+        }
+
+    def clone(self) -> SoftAuthenticator:
+        """A copy holding the same keys and counters, as a cloned device would."""
+        twin = SoftAuthenticator(self.origin)
+        twin.credentials = {
+            cid: SoftCredential(c.credential_id, c.key, c.rp_id, c.user_handle, c.sign_count)
+            for cid, c in self.credentials.items()
+        }
+        return twin