| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177 |
- """Path-bound tickets for browser file URLs (``/api/fs/download``, ``/api/files/stream``).
- A download link or an ``<audio>``/``<video>`` source cannot send the session
- header, and the session token grants host shells and file access, so it must
- never appear in a URL the browser records (download history, "Copy video
- address"). An authenticated ``POST /api/files/ticket`` mints a ticket that lets
- the loopback token gate admit GET/HEAD of exactly one route + query and nothing
- else. A browser retries a failed download by requesting the same URL, and the
- gate spends a download ticket's use before the file is even opened, so a failed
- or cut-off first response has already used one. A download ticket therefore
- admits up to ``DOWNLOAD_MAX_REDEMPTIONS`` requests (GET or HEAD) within
- ``DOWNLOAD_TTL_SECONDS`` of minting, then dies. A media element issues many
- Range requests for one source, so a stream ticket is reusable until it expires.
- Each ticket captures the resolved file (on the profile's SSH workspace
- when it has one, as for native Desktop's download) and the named profile homes it
- belongs to; the resource opener refuses it once one of those homes is missing or
- deleted (``hermes_constants.assert_named_profile_home_live``). A ticket minted for
- a request that presented the browser session token records that credential's
- generation (``hermes_cli.browser_credential``) and redeems only while it is
- current, like a socket ticket, so signing out ends it even when the sign-out lands
- while the ticket is being minted; signing out also drops it from the store. A
- ticket minted with any other credential outlives a sign-out. In-memory only:
- tickets die with the process, like the token.
- """
- from __future__ import annotations
- import secrets
- import threading
- import time
- from dataclasses import dataclass, replace
- from pathlib import Path, PurePath
- from typing import TYPE_CHECKING, Any, Iterable, Mapping
- from hermes_cli import browser_credential
- if TYPE_CHECKING:
- from starlette.requests import Request
- DOWNLOAD_TTL_SECONDS = 60
- #: Requests one download ticket admits: the first fetch and two repeats of that
- #: same URL. Kept small because the URL sits in download history and proxy logs.
- DOWNLOAD_MAX_REDEMPTIONS = 3
- #: A transcript video may be played long after it mounted; seeking past the
- #: buffered range needs the ticket again.
- STREAM_TTL_SECONDS = 60 * 60
- _MAX_TICKETS = 1024
- #: A download reads the file where the profile's workspace is, like native Desktop's download;
- #: media plays through the managed stream route.
- ROUTES: Mapping[str, str] = {"download": "/api/fs/download", "stream": "/api/files/stream"}
- _Scope = tuple[str, tuple[tuple[str, str], ...]]
- @dataclass(frozen=True)
- class FileAuthority:
- """Private, resolved resource identity; none of this is supplied by a ticket holder."""
- target: PurePath
- homes: tuple[Path, ...]
- #: The SSH workspace reader the file is read through (``target`` is then a path on that
- #: machine), or None for a file on this host.
- workspace: Any = None
- def check_live(self) -> None:
- """``FileNotFoundError`` once a named profile home this file belongs to is missing or deleted."""
- from hermes_constants import assert_named_profile_home_live
- for home in self.homes:
- assert_named_profile_home_live(home)
- @dataclass(frozen=True)
- class _Ticket:
- scope: _Scope
- expires_at: float
- #: Requests (GET or HEAD) a download ticket still admits; None for a stream ticket, which
- #: lasts until it expires.
- uses_left: int | None
- authority: FileAuthority
- #: Generation of the browser credential the minting request presented
- #: (``hermes_cli.browser_credential``; None for any other credential): the ticket redeems only
- #: while it is current, so a sign-out that lands between the request's admission and the mint
- #: still ends it.
- generation: str | None = None
- _lock = threading.Lock()
- _tickets: dict[str, _Ticket] = {}
- def _scope(route_path: str, query: Iterable[tuple[str, str]]) -> _Scope:
- return route_path, tuple(sorted(query))
- def session_token_of(request: Request) -> str | None:
- """The browser session token *request* was admitted with on the loopback gate, or None when it
- came with any other credential (a sign-in, a native client's grant, a service token)."""
- from hermes_cli.web_server import _SESSION_HEADER_NAME
- if (getattr(request.app.state, "auth_required", False)
- or getattr(request.state, "native_http_principal", None)
- or getattr(request.state, "token_authenticated", False)):
- return None
- return (request.headers.get(_SESSION_HEADER_NAME)
- or request.headers.get("authorization", "").removeprefix("Bearer ") or None)
- def mint(route: str, query: Mapping[str, str], *, authority: FileAuthority,
- session_token: str | None = None) -> str:
- """Ticket for GET/HEAD of ``ROUTES[route]`` with exactly ``query`` (plus ``ticket``); minted for
- a request admitted with *session_token*, it records that browser credential's generation and
- redeems only while it is current."""
- route_path = ROUTES[route]
- download = route == "download"
- now = time.monotonic()
- ticket = secrets.token_urlsafe(32)
- entry = _Ticket(
- scope=_scope(route_path, query.items()),
- expires_at=now + (DOWNLOAD_TTL_SECONDS if download else STREAM_TTL_SECONDS),
- uses_left=DOWNLOAD_MAX_REDEMPTIONS if download else None,
- authority=authority,
- generation=None if session_token is None else browser_credential.generation_of(session_token),
- )
- with _lock:
- for stale in [key for key, value in _tickets.items() if value.expires_at <= now]:
- del _tickets[stale]
- while len(_tickets) >= _MAX_TICKETS:
- del _tickets[next(iter(_tickets))]
- _tickets[ticket] = entry
- return ticket
- def revoke_replaced() -> int:
- """Drop every ticket minted under a browser credential that has since been replaced (sign-out);
- tickets minted with any other credential stay. Returns how many were dropped."""
- with _lock:
- replaced = [key for key, value in _tickets.items()
- if value.generation is not None and not browser_credential.is_current(value.generation)]
- for key in replaced:
- del _tickets[key]
- return len(replaced)
- def _spend_use(ticket: str, entry: _Ticket) -> None:
- """Count one admitted request against a download ticket, dropping it at its last use. Caller
- holds ``_lock``. A stream ticket has no count."""
- if entry.uses_left is None:
- return
- if entry.uses_left > 1:
- _tickets[ticket] = replace(entry, uses_left=entry.uses_left - 1)
- else:
- del _tickets[ticket]
- def redeem(request: Request) -> bool:
- """True when ``?ticket=`` authorizes this exact request; spends one of a download ticket's uses.
- A ticket minted under a browser credential that has since been replaced is dropped instead."""
- ticket = request.query_params.get("ticket", "")
- if not ticket or request.method not in ("GET", "HEAD"):
- return False
- scope = _scope(request.url.path, ((k, v) for k, v in request.query_params.multi_items() if k != "ticket"))
- with _lock:
- entry = _tickets.get(ticket)
- if entry is None or entry.scope != scope or entry.expires_at <= time.monotonic():
- return False
- if entry.generation is not None and not browser_credential.is_current(entry.generation):
- del _tickets[ticket]
- return False
- _spend_use(ticket, entry)
- # Carry the captured authority through middleware to the resource opener.
- # A middleware-only check would race deletion before FileResponse opens it.
- request.state.file_ticket_authority = entry.authority
- return True
- browser_credential.on_rotate("file tickets", revoke_replaced)
|