web_server_file_tickets.py 7.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177
  1. """Path-bound tickets for browser file URLs (``/api/fs/download``, ``/api/files/stream``).
  2. A download link or an ``<audio>``/``<video>`` source cannot send the session
  3. header, and the session token grants host shells and file access, so it must
  4. never appear in a URL the browser records (download history, "Copy video
  5. address"). An authenticated ``POST /api/files/ticket`` mints a ticket that lets
  6. the loopback token gate admit GET/HEAD of exactly one route + query and nothing
  7. else. A browser retries a failed download by requesting the same URL, and the
  8. gate spends a download ticket's use before the file is even opened, so a failed
  9. or cut-off first response has already used one. A download ticket therefore
  10. admits up to ``DOWNLOAD_MAX_REDEMPTIONS`` requests (GET or HEAD) within
  11. ``DOWNLOAD_TTL_SECONDS`` of minting, then dies. A media element issues many
  12. Range requests for one source, so a stream ticket is reusable until it expires.
  13. Each ticket captures the resolved file (on the profile's SSH workspace
  14. when it has one, as for native Desktop's download) and the named profile homes it
  15. belongs to; the resource opener refuses it once one of those homes is missing or
  16. deleted (``hermes_constants.assert_named_profile_home_live``). A ticket minted for
  17. a request that presented the browser session token records that credential's
  18. generation (``hermes_cli.browser_credential``) and redeems only while it is
  19. current, like a socket ticket, so signing out ends it even when the sign-out lands
  20. while the ticket is being minted; signing out also drops it from the store. A
  21. ticket minted with any other credential outlives a sign-out. In-memory only:
  22. tickets die with the process, like the token.
  23. """
  24. from __future__ import annotations
  25. import secrets
  26. import threading
  27. import time
  28. from dataclasses import dataclass, replace
  29. from pathlib import Path, PurePath
  30. from typing import TYPE_CHECKING, Any, Iterable, Mapping
  31. from hermes_cli import browser_credential
  32. if TYPE_CHECKING:
  33. from starlette.requests import Request
  34. DOWNLOAD_TTL_SECONDS = 60
  35. #: Requests one download ticket admits: the first fetch and two repeats of that
  36. #: same URL. Kept small because the URL sits in download history and proxy logs.
  37. DOWNLOAD_MAX_REDEMPTIONS = 3
  38. #: A transcript video may be played long after it mounted; seeking past the
  39. #: buffered range needs the ticket again.
  40. STREAM_TTL_SECONDS = 60 * 60
  41. _MAX_TICKETS = 1024
  42. #: A download reads the file where the profile's workspace is, like native Desktop's download;
  43. #: media plays through the managed stream route.
  44. ROUTES: Mapping[str, str] = {"download": "/api/fs/download", "stream": "/api/files/stream"}
  45. _Scope = tuple[str, tuple[tuple[str, str], ...]]
  46. @dataclass(frozen=True)
  47. class FileAuthority:
  48. """Private, resolved resource identity; none of this is supplied by a ticket holder."""
  49. target: PurePath
  50. homes: tuple[Path, ...]
  51. #: The SSH workspace reader the file is read through (``target`` is then a path on that
  52. #: machine), or None for a file on this host.
  53. workspace: Any = None
  54. def check_live(self) -> None:
  55. """``FileNotFoundError`` once a named profile home this file belongs to is missing or deleted."""
  56. from hermes_constants import assert_named_profile_home_live
  57. for home in self.homes:
  58. assert_named_profile_home_live(home)
  59. @dataclass(frozen=True)
  60. class _Ticket:
  61. scope: _Scope
  62. expires_at: float
  63. #: Requests (GET or HEAD) a download ticket still admits; None for a stream ticket, which
  64. #: lasts until it expires.
  65. uses_left: int | None
  66. authority: FileAuthority
  67. #: Generation of the browser credential the minting request presented
  68. #: (``hermes_cli.browser_credential``; None for any other credential): the ticket redeems only
  69. #: while it is current, so a sign-out that lands between the request's admission and the mint
  70. #: still ends it.
  71. generation: str | None = None
  72. _lock = threading.Lock()
  73. _tickets: dict[str, _Ticket] = {}
  74. def _scope(route_path: str, query: Iterable[tuple[str, str]]) -> _Scope:
  75. return route_path, tuple(sorted(query))
  76. def session_token_of(request: Request) -> str | None:
  77. """The browser session token *request* was admitted with on the loopback gate, or None when it
  78. came with any other credential (a sign-in, a native client's grant, a service token)."""
  79. from hermes_cli.web_server import _SESSION_HEADER_NAME
  80. if (getattr(request.app.state, "auth_required", False)
  81. or getattr(request.state, "native_http_principal", None)
  82. or getattr(request.state, "token_authenticated", False)):
  83. return None
  84. return (request.headers.get(_SESSION_HEADER_NAME)
  85. or request.headers.get("authorization", "").removeprefix("Bearer ") or None)
  86. def mint(route: str, query: Mapping[str, str], *, authority: FileAuthority,
  87. session_token: str | None = None) -> str:
  88. """Ticket for GET/HEAD of ``ROUTES[route]`` with exactly ``query`` (plus ``ticket``); minted for
  89. a request admitted with *session_token*, it records that browser credential's generation and
  90. redeems only while it is current."""
  91. route_path = ROUTES[route]
  92. download = route == "download"
  93. now = time.monotonic()
  94. ticket = secrets.token_urlsafe(32)
  95. entry = _Ticket(
  96. scope=_scope(route_path, query.items()),
  97. expires_at=now + (DOWNLOAD_TTL_SECONDS if download else STREAM_TTL_SECONDS),
  98. uses_left=DOWNLOAD_MAX_REDEMPTIONS if download else None,
  99. authority=authority,
  100. generation=None if session_token is None else browser_credential.generation_of(session_token),
  101. )
  102. with _lock:
  103. for stale in [key for key, value in _tickets.items() if value.expires_at <= now]:
  104. del _tickets[stale]
  105. while len(_tickets) >= _MAX_TICKETS:
  106. del _tickets[next(iter(_tickets))]
  107. _tickets[ticket] = entry
  108. return ticket
  109. def revoke_replaced() -> int:
  110. """Drop every ticket minted under a browser credential that has since been replaced (sign-out);
  111. tickets minted with any other credential stay. Returns how many were dropped."""
  112. with _lock:
  113. replaced = [key for key, value in _tickets.items()
  114. if value.generation is not None and not browser_credential.is_current(value.generation)]
  115. for key in replaced:
  116. del _tickets[key]
  117. return len(replaced)
  118. def _spend_use(ticket: str, entry: _Ticket) -> None:
  119. """Count one admitted request against a download ticket, dropping it at its last use. Caller
  120. holds ``_lock``. A stream ticket has no count."""
  121. if entry.uses_left is None:
  122. return
  123. if entry.uses_left > 1:
  124. _tickets[ticket] = replace(entry, uses_left=entry.uses_left - 1)
  125. else:
  126. del _tickets[ticket]
  127. def redeem(request: Request) -> bool:
  128. """True when ``?ticket=`` authorizes this exact request; spends one of a download ticket's uses.
  129. A ticket minted under a browser credential that has since been replaced is dropped instead."""
  130. ticket = request.query_params.get("ticket", "")
  131. if not ticket or request.method not in ("GET", "HEAD"):
  132. return False
  133. scope = _scope(request.url.path, ((k, v) for k, v in request.query_params.multi_items() if k != "ticket"))
  134. with _lock:
  135. entry = _tickets.get(ticket)
  136. if entry is None or entry.scope != scope or entry.expires_at <= time.monotonic():
  137. return False
  138. if entry.generation is not None and not browser_credential.is_current(entry.generation):
  139. del _tickets[ticket]
  140. return False
  141. _spend_use(ticket, entry)
  142. # Carry the captured authority through middleware to the resource opener.
  143. # A middleware-only check would race deletion before FileResponse opens it.
  144. request.state.file_ticket_authority = entry.authority
  145. return True
  146. browser_credential.on_rotate("file tickets", revoke_replaced)