hadoku-scrape-sdk 0.1.3__tar.gz

hadoku_scrape_sdk-0.1.3/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 WolffM
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

hadoku_scrape_sdk-0.1.3/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: hadoku-scrape-sdk
+Version: 0.1.3
+Summary: The runtime hadoku-scrape plugins build on: plugin contract, browser stack, run log, events, test floor
+License-Expression: ISC
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: browser-cookie3<1.0,>=0.19.0
+Requires-Dist: fastapi<1.0,>=0.109.0
+Requires-Dist: hadoku-execlog>=0.1.0
+Requires-Dist: httpx[socks]<1.0,>=0.27.0
+Requires-Dist: patchright<2.0,>=1.49.0
+Requires-Dist: playwright<2.0,>=1.62.0
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: pyvirtualdisplay<4.0,>=3.0
+Requires-Dist: structlog<25.0,>=24.0.0
+Requires-Dist: tenacity<9.0,>=8.2.0
+Provides-Extra: testing
+Requires-Dist: pytest==8.4.2; extra == "testing"
+Requires-Dist: pytest-asyncio<2,>=1.2; extra == "testing"
+Requires-Dist: pytest-timeout<3.0,>=2.2.0; extra == "testing"
+Requires-Dist: respx<1.0,>=0.21.0; extra == "testing"
+Requires-Dist: httpx2<3.0,>=2.9; extra == "testing"
+Requires-Dist: typer<1.0,>=0.15.0; extra == "testing"
+Dynamic: license-file
+
+# hadoku-scrape-sdk
+
+The runtime that hadoku-scrape plugins are built on. A plugin is a scraper that
+lives in its own repo and runs inside the hadoku-scrape service. This package is
+everything such a plugin imports, and nothing of the service around it.
+
+```sh
+pip install hadoku-scrape-sdk            # runtime
+pip install 'hadoku-scrape-sdk[testing]' # + the pinned test stack and test floor
+```
+
+## What's in it
+
+| Module | What it gives a plugin |
+|---|---|
+| `hadoku_sdk.plugins` | `ScraperPlugin`, `UrlScraper`: the contract. `python -m hadoku_sdk.plugins` checks every enabled plugin loads |
+| `hadoku_sdk.db.engine`, `.db.execution_log` | The SQLite engine (`init_db`, `get_connection`) and `execution_run`, the run log every scrape writes through |
+| `hadoku_sdk.runtime` | `Severity` and events (`ctx.event(...)`), run pacing, the run gate |
+| `hadoku_sdk.browser` | Browser manager (Patchright, persistent profiles, stealth), sessions, preflight checks |
+| `hadoku_sdk.proxy` | HTTP client with proxy escalation |
+| `hadoku_sdk.auth.cookies` | Browser-cookie import |
+| `hadoku_sdk.api.middleware` | Auth dependencies (`require_service`, ...), error types, `spawn_tracked` for fire-and-forget routes |
+| `hadoku_sdk.scrapers.base` | `BaseScraper`, `ScraperResult` for URL-dispatch scrapers |
+| `hadoku_sdk.observability.logging` | `get_logger` (structlog) |
+| `hadoku_sdk.testing` | The autouse test floor: an isolated DB per test, no real browsers |
+
+## A plugin
+
+```python
+# my_plugins/thing/plugin.py
+from pathlib import Path
+from hadoku_sdk.plugins import ScraperPlugin
+
+PLUGIN = ScraperPlugin(
+    name="thing",
+    routers=[router],                 # FastAPI, prefix /api/v1/<yours>
+    cli={"thing": thing_app},         # Typer, mounted as `hs thing`
+    migrations=Path(__file__).parent / "migrations",   # NNN_*.sql
+    on_startup=[seed],
+)
+```
+
+```toml
+# pyproject.toml
+[project.entry-points."hadoku_scrape.plugins"]
+thing = "my_plugins.thing.plugin:PLUGIN"
+```
+
+The host's `plugins.toml` decides which installed plugins actually load.
+
+## Tests
+
+```python
+# tests/conftest.py
+import os
+from pathlib import Path
+os.environ["HADOKU_PLUGINS_MANIFEST"] = str(Path(__file__).parent / "resources" / "plugins.toml")
+pytest_plugins = ["hadoku_sdk.testing.pytest_plugin"]
+```
+
+```python
+# tests/unit/conftest.py
+from hadoku_sdk.testing.unit import _instant_sleep, _silence_discord_notify  # noqa: F401
+```
+
+## Rules a plugin follows
+
+- Notifications go through `ctx.event(name, payload, severity=...)` on the run
+  context, never a direct Discord call. The host routes them.
+- Timestamps are UTC. Never `datetime.utcnow()`.
+- Never log credentials, cookies or API keys.
+- No lazy imports inside functions that run on background threads.
+- Drive browsers through `hadoku_sdk.browser.manager`. Never hardcode locale or
+  timezone.
+
+License: ISC.

hadoku_scrape_sdk-0.1.3/README.md

@@ -0,0 +1,76 @@
+# hadoku-scrape-sdk
+
+The runtime that hadoku-scrape plugins are built on. A plugin is a scraper that
+lives in its own repo and runs inside the hadoku-scrape service. This package is
+everything such a plugin imports, and nothing of the service around it.
+
+```sh
+pip install hadoku-scrape-sdk            # runtime
+pip install 'hadoku-scrape-sdk[testing]' # + the pinned test stack and test floor
+```
+
+## What's in it
+
+| Module | What it gives a plugin |
+|---|---|
+| `hadoku_sdk.plugins` | `ScraperPlugin`, `UrlScraper`: the contract. `python -m hadoku_sdk.plugins` checks every enabled plugin loads |
+| `hadoku_sdk.db.engine`, `.db.execution_log` | The SQLite engine (`init_db`, `get_connection`) and `execution_run`, the run log every scrape writes through |
+| `hadoku_sdk.runtime` | `Severity` and events (`ctx.event(...)`), run pacing, the run gate |
+| `hadoku_sdk.browser` | Browser manager (Patchright, persistent profiles, stealth), sessions, preflight checks |
+| `hadoku_sdk.proxy` | HTTP client with proxy escalation |
+| `hadoku_sdk.auth.cookies` | Browser-cookie import |
+| `hadoku_sdk.api.middleware` | Auth dependencies (`require_service`, ...), error types, `spawn_tracked` for fire-and-forget routes |
+| `hadoku_sdk.scrapers.base` | `BaseScraper`, `ScraperResult` for URL-dispatch scrapers |
+| `hadoku_sdk.observability.logging` | `get_logger` (structlog) |
+| `hadoku_sdk.testing` | The autouse test floor: an isolated DB per test, no real browsers |
+
+## A plugin
+
+```python
+# my_plugins/thing/plugin.py
+from pathlib import Path
+from hadoku_sdk.plugins import ScraperPlugin
+
+PLUGIN = ScraperPlugin(
+    name="thing",
+    routers=[router],                 # FastAPI, prefix /api/v1/<yours>
+    cli={"thing": thing_app},         # Typer, mounted as `hs thing`
+    migrations=Path(__file__).parent / "migrations",   # NNN_*.sql
+    on_startup=[seed],
+)
+```
+
+```toml
+# pyproject.toml
+[project.entry-points."hadoku_scrape.plugins"]
+thing = "my_plugins.thing.plugin:PLUGIN"
+```
+
+The host's `plugins.toml` decides which installed plugins actually load.
+
+## Tests
+
+```python
+# tests/conftest.py
+import os
+from pathlib import Path
+os.environ["HADOKU_PLUGINS_MANIFEST"] = str(Path(__file__).parent / "resources" / "plugins.toml")
+pytest_plugins = ["hadoku_sdk.testing.pytest_plugin"]
+```
+
+```python
+# tests/unit/conftest.py
+from hadoku_sdk.testing.unit import _instant_sleep, _silence_discord_notify  # noqa: F401
+```
+
+## Rules a plugin follows
+
+- Notifications go through `ctx.event(name, payload, severity=...)` on the run
+  context, never a direct Discord call. The host routes them.
+- Timestamps are UTC. Never `datetime.utcnow()`.
+- Never log credentials, cookies or API keys.
+- No lazy imports inside functions that run on background threads.
+- Drive browsers through `hadoku_sdk.browser.manager`. Never hardcode locale or
+  timezone.
+
+License: ISC.

hadoku_scrape_sdk-0.1.3/hadoku_scrape_sdk.egg-info/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: hadoku-scrape-sdk
+Version: 0.1.3
+Summary: The runtime hadoku-scrape plugins build on: plugin contract, browser stack, run log, events, test floor
+License-Expression: ISC
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: browser-cookie3<1.0,>=0.19.0
+Requires-Dist: fastapi<1.0,>=0.109.0
+Requires-Dist: hadoku-execlog>=0.1.0
+Requires-Dist: httpx[socks]<1.0,>=0.27.0
+Requires-Dist: patchright<2.0,>=1.49.0
+Requires-Dist: playwright<2.0,>=1.62.0
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: pyvirtualdisplay<4.0,>=3.0
+Requires-Dist: structlog<25.0,>=24.0.0
+Requires-Dist: tenacity<9.0,>=8.2.0
+Provides-Extra: testing
+Requires-Dist: pytest==8.4.2; extra == "testing"
+Requires-Dist: pytest-asyncio<2,>=1.2; extra == "testing"
+Requires-Dist: pytest-timeout<3.0,>=2.2.0; extra == "testing"
+Requires-Dist: respx<1.0,>=0.21.0; extra == "testing"
+Requires-Dist: httpx2<3.0,>=2.9; extra == "testing"
+Requires-Dist: typer<1.0,>=0.15.0; extra == "testing"
+Dynamic: license-file
+
+# hadoku-scrape-sdk
+
+The runtime that hadoku-scrape plugins are built on. A plugin is a scraper that
+lives in its own repo and runs inside the hadoku-scrape service. This package is
+everything such a plugin imports, and nothing of the service around it.
+
+```sh
+pip install hadoku-scrape-sdk            # runtime
+pip install 'hadoku-scrape-sdk[testing]' # + the pinned test stack and test floor
+```
+
+## What's in it
+
+| Module | What it gives a plugin |
+|---|---|
+| `hadoku_sdk.plugins` | `ScraperPlugin`, `UrlScraper`: the contract. `python -m hadoku_sdk.plugins` checks every enabled plugin loads |
+| `hadoku_sdk.db.engine`, `.db.execution_log` | The SQLite engine (`init_db`, `get_connection`) and `execution_run`, the run log every scrape writes through |
+| `hadoku_sdk.runtime` | `Severity` and events (`ctx.event(...)`), run pacing, the run gate |
+| `hadoku_sdk.browser` | Browser manager (Patchright, persistent profiles, stealth), sessions, preflight checks |
+| `hadoku_sdk.proxy` | HTTP client with proxy escalation |
+| `hadoku_sdk.auth.cookies` | Browser-cookie import |
+| `hadoku_sdk.api.middleware` | Auth dependencies (`require_service`, ...), error types, `spawn_tracked` for fire-and-forget routes |
+| `hadoku_sdk.scrapers.base` | `BaseScraper`, `ScraperResult` for URL-dispatch scrapers |
+| `hadoku_sdk.observability.logging` | `get_logger` (structlog) |
+| `hadoku_sdk.testing` | The autouse test floor: an isolated DB per test, no real browsers |
+
+## A plugin
+
+```python
+# my_plugins/thing/plugin.py
+from pathlib import Path
+from hadoku_sdk.plugins import ScraperPlugin
+
+PLUGIN = ScraperPlugin(
+    name="thing",
+    routers=[router],                 # FastAPI, prefix /api/v1/<yours>
+    cli={"thing": thing_app},         # Typer, mounted as `hs thing`
+    migrations=Path(__file__).parent / "migrations",   # NNN_*.sql
+    on_startup=[seed],
+)
+```
+
+```toml
+# pyproject.toml
+[project.entry-points."hadoku_scrape.plugins"]
+thing = "my_plugins.thing.plugin:PLUGIN"
+```
+
+The host's `plugins.toml` decides which installed plugins actually load.
+
+## Tests
+
+```python
+# tests/conftest.py
+import os
+from pathlib import Path
+os.environ["HADOKU_PLUGINS_MANIFEST"] = str(Path(__file__).parent / "resources" / "plugins.toml")
+pytest_plugins = ["hadoku_sdk.testing.pytest_plugin"]
+```
+
+```python
+# tests/unit/conftest.py
+from hadoku_sdk.testing.unit import _instant_sleep, _silence_discord_notify  # noqa: F401
+```
+
+## Rules a plugin follows
+
+- Notifications go through `ctx.event(name, payload, severity=...)` on the run
+  context, never a direct Discord call. The host routes them.
+- Timestamps are UTC. Never `datetime.utcnow()`.
+- Never log credentials, cookies or API keys.
+- No lazy imports inside functions that run on background threads.
+- Drive browsers through `hadoku_sdk.browser.manager`. Never hardcode locale or
+  timezone.
+
+License: ISC.

hadoku_scrape_sdk-0.1.3/hadoku_scrape_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,60 @@
+LICENSE
+README.md
+pyproject.toml
+hadoku_scrape_sdk.egg-info/PKG-INFO
+hadoku_scrape_sdk.egg-info/SOURCES.txt
+hadoku_scrape_sdk.egg-info/dependency_links.txt
+hadoku_scrape_sdk.egg-info/requires.txt
+hadoku_scrape_sdk.egg-info/top_level.txt
+hadoku_sdk/__init__.py
+hadoku_sdk/config.py
+hadoku_sdk/paths.py
+hadoku_sdk/api/__init__.py
+hadoku_sdk/api/middleware/__init__.py
+hadoku_sdk/api/middleware/auth.py
+hadoku_sdk/api/middleware/errors.py
+hadoku_sdk/api/middleware/fire_and_forget.py
+hadoku_sdk/api/middleware/lock_release.py
+hadoku_sdk/api/middleware/whoami.py
+hadoku_sdk/api/models/__init__.py
+hadoku_sdk/api/models/responses.py
+hadoku_sdk/auth/__init__.py
+hadoku_sdk/auth/cookies.py
+hadoku_sdk/browser/__init__.py
+hadoku_sdk/browser/cdpfree.py
+hadoku_sdk/browser/linkedin.py
+hadoku_sdk/browser/manager.py
+hadoku_sdk/browser/preflight.py
+hadoku_sdk/browser/session.py
+hadoku_sdk/browser/stealth.py
+hadoku_sdk/db/__init__.py
+hadoku_sdk/db/engine.py
+hadoku_sdk/db/execution_log.py
+hadoku_sdk/db/migrations/001_execution_log.sql
+hadoku_sdk/db/migrations/002_run_pacing.sql
+hadoku_sdk/db/migrations/003_execution_log_owner.sql
+hadoku_sdk/observability/__init__.py
+hadoku_sdk/observability/aggregator.py
+hadoku_sdk/observability/discord_notify.py
+hadoku_sdk/observability/logging.py
+hadoku_sdk/plugins/__init__.py
+hadoku_sdk/plugins/__main__.py
+hadoku_sdk/plugins/manifest.py
+hadoku_sdk/proxy/__init__.py
+hadoku_sdk/proxy/base.py
+hadoku_sdk/proxy/client.py
+hadoku_sdk/proxy/escalation.py
+hadoku_sdk/runtime/__init__.py
+hadoku_sdk/runtime/events.py
+hadoku_sdk/runtime/gate.py
+hadoku_sdk/runtime/pacing.py
+hadoku_sdk/runtime/reaper.py
+hadoku_sdk/scrapers/__init__.py
+hadoku_sdk/scrapers/base.py
+hadoku_sdk/scrapers/utils/__init__.py
+hadoku_sdk/scrapers/utils/cloudflare_errors.py
+hadoku_sdk/scrapers/utils/cloudflare_kv.py
+hadoku_sdk/scrapers/utils/config.py
+hadoku_sdk/testing/__init__.py
+hadoku_sdk/testing/pytest_plugin.py
+hadoku_sdk/testing/unit.py

hadoku_scrape_sdk-0.1.3/hadoku_scrape_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hadoku_scrape_sdk-0.1.3/hadoku_scrape_sdk.egg-info/requires.txt

@@ -0,0 +1,18 @@
+browser-cookie3<1.0,>=0.19.0
+fastapi<1.0,>=0.109.0
+hadoku-execlog>=0.1.0
+httpx[socks]<1.0,>=0.27.0
+patchright<2.0,>=1.49.0
+playwright<2.0,>=1.62.0
+pydantic<3.0,>=2.0
+pyvirtualdisplay<4.0,>=3.0
+structlog<25.0,>=24.0.0
+tenacity<9.0,>=8.2.0
+
+[testing]
+pytest==8.4.2
+pytest-asyncio<2,>=1.2
+pytest-timeout<3.0,>=2.2.0
+respx<1.0,>=0.21.0
+httpx2<3.0,>=2.9
+typer<1.0,>=0.15.0

hadoku_scrape_sdk-0.1.3/hadoku_scrape_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+hadoku_sdk

hadoku_scrape_sdk-0.1.3/hadoku_sdk/__init__.py

@@ -0,0 +1 @@
+"""hadoku-scrape SDK: what a scraper plugin builds on, without the service around it."""

hadoku_scrape_sdk-0.1.3/hadoku_sdk/api/__init__.py

@@ -0,0 +1 @@
+"""Part of hadoku-scrape-sdk."""

hadoku_scrape_sdk-0.1.3/hadoku_sdk/api/middleware/__init__.py

@@ -0,0 +1 @@
+"""Part of hadoku-scrape-sdk."""

hadoku_scrape_sdk-0.1.3/hadoku_sdk/api/middleware/auth.py

@@ -0,0 +1,181 @@
+"""Tier-aware API authentication.
+
+The edge in front of the service resolves the caller's session/key and
+injects ``X-User-Key`` on the proxied request. The backend
+holds **no key arrays of its own** — it delegates tier resolution to the
+platform's authoritative ``/session/whoami`` endpoint (see
+:mod:`hadoku_sdk.api.middleware.whoami`), cached per key. This works for
+both edge-tunnelled callers and the direct service-to-service callers
+that bypass the edge.
+
+Tiers:
+  - ``admin``    operator key, full access
+  - ``service``  internal sibling-service key — full access EXCEPT routes explicitly
+                 admin-only, and only for a key on the ``scraper-service``
+                 access list
+  - ``friend``   trusted human, read-only observability access
+  - ``public``   no key / unrecognised key
+
+Per-route deps name the *minimum* tier accepted; admin is implicit.
+
+  - ``require_admin``    admin only
+  - ``require_service``  service or higher AND on ``scraper-service`` (default
+                         for routes that mutate state / consume resources /
+                         call external APIs). Service tier is every service
+                         key on the platform, and people hold them too; the list
+                         names the callers that drive the scraper. Admin is
+                         not exempt: the operator is on the list.
+  - ``require_friend``   friend or higher (dashboard / observability /
+                         contributor-friendly trigger endpoints — anything
+                         a trusted human should be able to hit)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from fastapi import Depends, Request
+
+from hadoku_sdk.api.middleware.errors import AuthenticationError, AuthorizationError
+from hadoku_sdk.api.middleware.whoami import resolve_identity_from_key
+from hadoku_sdk.observability.logging import get_logger
+
+log = get_logger("api.auth")
+
+
+class Tier(str, Enum):
+    """The tier ladder. Mirrors `_VALID_TIERS` in `whoami.py`: if a tier exists
+    there and not here, `_resolve_auth` raises `ValueError` on it, which is a 500
+    rather than a 403. Edge tier names beyond these are mapped onto them with
+    `whoami.alias_tier`.
+    """
+
+    ADMIN = "admin"
+    MEMBER = "member"
+    SERVICE = "service"
+    FRIEND = "friend"
+    PUBLIC = "public"
+
+
+# LOW to HIGH. Gates compare RANK, never identity or membership: `tier is Tier.ADMIN`
+# and `tier not in (Tier.ADMIN, Tier.SERVICE)` both lock out any tier that sits ABOVE
+# the one being named, which is the opposite of what a minimum-tier gate means.
+_RANK: dict[Tier, int] = {
+    Tier.PUBLIC: 0,
+    Tier.FRIEND: 1,
+    Tier.SERVICE: 2,
+    Tier.MEMBER: 3,
+    Tier.ADMIN: 4,
+}
+
+
+def tier_at_least(tier: Tier, minimum: Tier) -> bool:
+    """True when `tier` sits at or above `minimum` on the ladder."""
+    return _RANK.get(tier, -1) >= _RANK[minimum]
+
+
+@dataclass(frozen=True)
+class AuthContext:
+    """Resolved caller identity. Yielded by the require_* deps so route
+    handlers can stamp audit fields without ever touching the raw key."""
+
+    tier: Tier
+    masked_key: str
+    #: The platform's stable per-user UUID, straight from whoami — which the
+    #: resolver has to call anyway to get the tier. Durable across sessions and
+    #: devices, so it is the right key for anything stored per person. None
+    #: when whoami did not supply one (anonymous, transient failure, or a test
+    #: override), which callers must handle rather than assume.
+    user_id: str | None = None
+    #: On the ``scraper-service`` access list (whoami answers it per key).
+    member: bool = False
+
+    def __str__(self) -> str:
+        # The userId, not the masked key: this is what lands in an f-string,
+        # and from there in whatever the f-string is written to.
+        return f"{self.tier.value}:{self.user_id or 'no-user'}"
+
+
+def _mask(key: str) -> str:
+    return f"{key[:4]}…{key[-2:]}" if len(key) > 8 else "****"
+
+
+def _extract_key(request: Request) -> str | None:
+    """Read the caller key from ``X-User-Key``. Bearer tokens are no longer
+    accepted at the backend — the edge translates session/cookie/Bearer
+    forms into ``X-User-Key`` before proxying."""
+    raw = request.headers.get("X-User-Key", "").strip()
+    return raw or None
+
+
+async def _resolve_auth(request: Request) -> AuthContext:
+    """Resolve the caller's tier or raise 401 if no key was sent.
+
+    Delegates classification to the cached whoami resolver. Returns
+    ``AuthContext(tier=PUBLIC, ...)`` (rather than raising) when a key was
+    sent but whoami didn't recognise it — the per-route dep decides whether
+    to 403.
+    """
+    key = _extract_key(request)
+    path = str(request.url.path)
+    client_ip = request.client.host if request.client else "unknown"
+
+    if not key:
+        log.warning("auth_missing_key", path=path, client_ip=client_ip)
+        raise AuthenticationError("X-User-Key header is required")
+
+    masked = _mask(key)
+    # The resolver returns one of the tiers in `whoami._VALID_TIERS` (it clamps
+    # anything unrecognised to "public"). This raises ValueError if that list and
+    # `Tier` ever drift apart again — keep them in step; the test asserts it.
+    identity = resolve_identity_from_key(key)
+    tier = Tier(identity.tier)
+
+    if tier is Tier.PUBLIC:
+        log.warning("auth_unknown_key", path=path, client_ip=client_ip, masked_key=masked)
+    else:
+        log.debug("auth_resolved", path=path, tier=tier.value, masked_key=masked)
+
+    return AuthContext(
+        tier=tier, masked_key=masked, user_id=identity.user_id, member=identity.member
+    )
+
+
+def require_admin(auth: AuthContext = Depends(_resolve_auth)) -> AuthContext:
+    """Admin-only. Used for: operator-only routes, anything that touches
+    credentials or executes destructive flows."""
+    if not tier_at_least(auth.tier, Tier.ADMIN):
+        raise AuthorizationError(f"admin tier required (got {auth.tier.value})")
+    return auth
+
+
+def require_service(
+    request: Request, auth: AuthContext = Depends(_resolve_auth)
+) -> AuthContext:
+    """Minimum tier service, and on the ``scraper-service`` list. Default for
+    routes that mutate state / call external APIs / consume sibling-service
+    resources."""
+    if not tier_at_least(auth.tier, Tier.SERVICE):
+        raise AuthorizationError(f"service tier required (got {auth.tier.value})")
+    if not auth.member:
+        # The user id names who to add (`access-list add scraper-service <name>`)
+        # if this caller is one the scraper should serve.
+        log.warning(
+            "auth_not_listed",
+            path=str(request.url.path),
+            tier=auth.tier.value,
+            user_id=auth.user_id,
+        )
+        raise AuthorizationError("not on the scraper-service access list")
+    return auth
+
+
+def require_friend(auth: AuthContext = Depends(_resolve_auth)) -> AuthContext:
+    """Minimum tier: friend. Use for dashboard / observability surfaces and
+    contributor-friendly trigger endpoints — anything a trusted human
+    should be able to hit. Service + admin pass too (admin always passes
+    everything by virtue of being the top tier)."""
+    if not tier_at_least(auth.tier, Tier.FRIEND):
+        raise AuthorizationError(f"friend tier required (got {auth.tier.value})")
+    return auth