fivefold 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. fivefold/__init__.py +4 -0
  2. fivefold/_data/db/bootstrap.sql +26 -0
  3. fivefold/_data/db/migrations/0001_schemas.sql +67 -0
  4. fivefold/_data/db/migrations/0002_gateway.sql +224 -0
  5. fivefold/_data/db/migrations/0003_gateway_record_0010.sql +91 -0
  6. fivefold/_data/db/migrations/0004_harness.sql +141 -0
  7. fivefold/_data/db/migrations/0005_sim.sql +679 -0
  8. fivefold/_data/db/migrations/0006_gateway_reads.sql +66 -0
  9. fivefold/_data/db/migrations/0007_eval.sql +33 -0
  10. fivefold/_data/db/migrations/0008_run_stop.sql +18 -0
  11. fivefold/_data/db/migrations/0009_message_copies.sql +69 -0
  12. fivefold/_data/db/migrations/0010_gateway_g1_check.sql +14 -0
  13. fivefold/_data/db/migrations/0011_model_calls.sql +37 -0
  14. fivefold/_data/db/migrations/0012_recovery_latency.sql +23 -0
  15. fivefold/_data/db/migrations/0013_split_topology.sql +33 -0
  16. fivefold/_data/db/migrations/0014_tool_call_args.sql +20 -0
  17. fivefold/_data/db/registry/0001_registry.sql +31 -0
  18. fivefold/_data/faults/expected.yaml +406 -0
  19. fivefold/_data/scenarios/dev/dev-001-single-po.yaml +45 -0
  20. fivefold/_data/scenarios/dev/dev-002-human-approval.yaml +47 -0
  21. fivefold/agents/__init__.py +7 -0
  22. fivefold/agents/branch.py +187 -0
  23. fivefold/agents/checkpoint.py +77 -0
  24. fivefold/agents/connection.py +153 -0
  25. fivefold/agents/live.py +492 -0
  26. fivefold/agents/policy.py +426 -0
  27. fivefold/agents/remote.py +333 -0
  28. fivefold/agents/replay.py +170 -0
  29. fivefold/agents/scripted.py +122 -0
  30. fivefold/agents/tools.py +229 -0
  31. fivefold/agents/worker.py +164 -0
  32. fivefold/domain/__init__.py +5 -0
  33. fivefold/domain/api.py +517 -0
  34. fivefold/domain/authority.py +149 -0
  35. fivefold/domain/contracts.py +80 -0
  36. fivefold/domain/identity.py +113 -0
  37. fivefold/domain/prices.py +178 -0
  38. fivefold/domain/report.py +92 -0
  39. fivefold/domain/rules.py +346 -0
  40. fivefold/domain/scenario.py +524 -0
  41. fivefold/evaluator/__init__.py +155 -0
  42. fivefold/evaluator/__main__.py +127 -0
  43. fivefold/evaluator/authorization.py +146 -0
  44. fivefold/evaluator/checks.py +331 -0
  45. fivefold/evaluator/evaluate.py +109 -0
  46. fivefold/evaluator/evidence.py +392 -0
  47. fivefold/evaluator/freshness.py +136 -0
  48. fivefold/evaluator/liveness.py +236 -0
  49. fivefold/evaluator/load.py +354 -0
  50. fivefold/evaluator/metrics.py +95 -0
  51. fivefold/evaluator/records.py +452 -0
  52. fivefold/evaluator/recovery.py +209 -0
  53. fivefold/evaluator/report.py +1096 -0
  54. fivefold/evaluator/result.py +344 -0
  55. fivefold/evaluator/store.py +83 -0
  56. fivefold/faults/__init__.py +5 -0
  57. fivefold/faults/catalog.py +278 -0
  58. fivefold/faults/plan.py +538 -0
  59. fivefold/gateway/__init__.py +6 -0
  60. fivefold/gateway/admin.py +179 -0
  61. fivefold/gateway/admin_api.py +398 -0
  62. fivefold/gateway/codec.py +372 -0
  63. fivefold/gateway/destination.py +64 -0
  64. fivefold/gateway/dispatcher.py +379 -0
  65. fivefold/gateway/freshness.py +83 -0
  66. fivefold/gateway/invariants.py +761 -0
  67. fivefold/gateway/memory.py +277 -0
  68. fivefold/gateway/pg_store.py +657 -0
  69. fivefold/gateway/records.py +592 -0
  70. fivefold/gateway/server.py +102 -0
  71. fivefold/gateway/sim_client.py +295 -0
  72. fivefold/gateway/state_machine.py +376 -0
  73. fivefold/gateway/steps.py +897 -0
  74. fivefold/gateway/store.py +635 -0
  75. fivefold/gateway/tools.py +424 -0
  76. fivefold/gateway/twin.py +199 -0
  77. fivefold/gateway/wire.py +138 -0
  78. fivefold/harness/__init__.py +6 -0
  79. fivefold/harness/actors.py +230 -0
  80. fivefold/harness/cells.py +303 -0
  81. fivefold/harness/clock.py +209 -0
  82. fivefold/harness/demo.py +397 -0
  83. fivefold/harness/fault_effects.py +122 -0
  84. fivefold/harness/live_options.py +159 -0
  85. fivefold/harness/log.py +540 -0
  86. fivefold/harness/mcp_link.py +409 -0
  87. fivefold/harness/migrations.py +520 -0
  88. fivefold/harness/models.py +368 -0
  89. fivefold/harness/registry.py +105 -0
  90. fivefold/harness/reports.py +100 -0
  91. fivefold/harness/rng.py +57 -0
  92. fivefold/harness/run.py +881 -0
  93. fivefold/harness/scheduler.py +441 -0
  94. fivefold/harness/sim_points.py +215 -0
  95. fivefold/harness/split/__init__.py +34 -0
  96. fivefold/harness/split/__main__.py +275 -0
  97. fivefold/harness/split/credentials.py +74 -0
  98. fivefold/harness/split/faults.py +75 -0
  99. fivefold/harness/split/gateway.py +769 -0
  100. fivefold/harness/split/hops.py +291 -0
  101. fivefold/harness/split/lifecycle.py +322 -0
  102. fivefold/harness/split/rundir.py +152 -0
  103. fivefold/harness/split/service.py +157 -0
  104. fivefold/harness/split/simulator.py +432 -0
  105. fivefold/harness/study.py +643 -0
  106. fivefold/harness/transport.py +533 -0
  107. fivefold/paths.py +24 -0
  108. fivefold/py.typed +0 -0
  109. fivefold/recorder/__init__.py +18 -0
  110. fivefold/recorder/__main__.py +308 -0
  111. fivefold/recorder/cassette.py +322 -0
  112. fivefold/recorder/playback.py +316 -0
  113. fivefold/recorder/recording.py +133 -0
  114. fivefold/sim/__init__.py +37 -0
  115. fivefold/sim/config.py +52 -0
  116. fivefold/sim/endpoint.py +176 -0
  117. fivefold/sim/ledger.py +583 -0
  118. fivefold/sim/service.py +834 -0
  119. fivefold/viewer/__init__.py +14 -0
  120. fivefold/viewer/__main__.py +75 -0
  121. fivefold/viewer/app.py +122 -0
  122. fivefold/viewer/records.py +108 -0
  123. fivefold/viewer/source.py +196 -0
  124. fivefold/viewer/timeline.py +61 -0
  125. fivefold-0.1.0.dist-info/METADATA +169 -0
  126. fivefold-0.1.0.dist-info/RECORD +128 -0
  127. fivefold-0.1.0.dist-info/WHEEL +4 -0
  128. fivefold-0.1.0.dist-info/licenses/LICENSE +202 -0
@@ -0,0 +1,179 @@
1
+ """The gateway's admin path, in process: open escalations and their resolution (0003).
2
+
3
+ Escalation hands an action whose outcome is unknown to a human: after the `escalated`
4
+ note, only an attestation moves the action (0010, reading 7). A human resolves an
5
+ escalation through the admin API by attesting that the action committed, naming the
6
+ effect, or that it did not (0003, escalation). `GatewayAdmin` is the core of that API,
7
+ in the gateway's process. In-process runs call it directly, as the scripted resolver
8
+ does; `admin_api.py` serves it over HTTP, with the gateway's records, for a gateway
9
+ served over HTTP. It reads time only from the run's virtual clock (0009), and it never
10
+ contacts the simulator: the human checks the world out of band, and the gateway records
11
+ what the human attests.
12
+
13
+ - `open_escalations` lists the escalations no one has resolved yet, in escalation-id
14
+ order, with what a human needs to check each one: the action, the approval its
15
+ attempts cite, when the escalation opened, when the action was last sent, and from
16
+ when "not committed" can be attested.
17
+ - `resolve` attests one escalation through the store's `attest`: T11 or T12, with reason
18
+ `human_attested`. The store refuses "not committed" before S past the action's latest
19
+ send, and accepts an attestation that names an effect at any time (0010, reading 8).
20
+ Every wait on the action then ends at once, as it does after a step of its driver. A
21
+ refusal is named after the store refused: `EscalationResolved` for an escalation
22
+ resolved already, `BeforeSettleTime` for "not committed" too early. Both are
23
+ `StepRefused`, and the store's rules decide either way.
24
+ """
25
+
26
+ from __future__ import annotations
27
+
28
+ from collections.abc import Mapping
29
+ from dataclasses import dataclass
30
+
31
+ from fivefold.gateway import steps
32
+ from fivefold.gateway.dispatcher import Dispatcher
33
+ from fivefold.gateway.records import ActionResult, Escalation, Resolution, check_text
34
+ from fivefold.gateway.steps import StepRefused
35
+ from fivefold.gateway.store import ActionStore, in_action_order, view_of
36
+ from fivefold.harness.scheduler import Scheduler
37
+
38
+
39
+ class UnknownEscalation(LookupError):
40
+ """No action of the run has an escalation with this id."""
41
+
42
+
43
+ class EscalationResolved(StepRefused):
44
+ """The escalation is resolved already: each one is resolved once (0003, escalation).
45
+
46
+ `escalation` is the escalation as it was resolved: when, how and by whom.
47
+ """
48
+
49
+ def __init__(self, message: str, escalation: Escalation) -> None:
50
+ super().__init__(message)
51
+ self.escalation = escalation
52
+
53
+
54
+ class BeforeSettleTime(StepRefused):
55
+ """An attestation of "not committed" before S past the latest send (0010, reading 8).
56
+
57
+ `not_committed_from_vt` is the first virtual time at which it can be made.
58
+ """
59
+
60
+ def __init__(self, message: str, not_committed_from_vt: int) -> None:
61
+ super().__init__(message)
62
+ self.not_committed_from_vt = not_committed_from_vt
63
+
64
+
65
+ @dataclass(frozen=True)
66
+ class OpenEscalation:
67
+ """An escalation no one has resolved yet, as the admin path lists it (0003)."""
68
+
69
+ escalation_id: str
70
+ action_id: str
71
+ intent_id: str
72
+ operation: str
73
+ target: str
74
+ args: Mapping[str, str | int]
75
+ approval_id: str
76
+ """The approval the action's grant names. Every attempt of the action cites it, and
77
+ no attempt of another action does (0002, rules 12 and 13)."""
78
+ opened_vt: int
79
+ last_sent_vt: int
80
+ """When the action's latest attempt was sent. "Not committed" can be attested only
81
+ at or after S past it (0010, reading 8)."""
82
+ not_committed_from_vt: int
83
+ """`last_sent_vt` plus S: from then on, every request of the action has committed or
84
+ never will (0005), and "not committed" can be attested."""
85
+
86
+
87
+ class GatewayAdmin:
88
+ """The admin path of one gateway: its open escalations, and their resolution."""
89
+
90
+ def __init__(self, scheduler: Scheduler, store: ActionStore, dispatcher: Dispatcher) -> None:
91
+ self._scheduler = scheduler
92
+ self._store = store
93
+ self._dispatcher = dispatcher
94
+
95
+ def open_escalations(self) -> tuple[OpenEscalation, ...]:
96
+ """Every escalation no one has resolved yet, in escalation-id order."""
97
+ snapshot = self._store.snapshot()
98
+ escalated = [e.action_id for e in snapshot.escalations.values() if e.resolved_vt is None]
99
+ settle_ms = self._store.settings.settle_ms
100
+ found: list[OpenEscalation] = []
101
+ for action_id in in_action_order(escalated):
102
+ view = view_of(snapshot, action_id)
103
+ escalation, grant = view.escalation, view.grant
104
+ if escalation is None or grant is None or not view.attempts:
105
+ raise AssertionError(f"{action_id} is escalated with no grant or no send")
106
+ action = view.action
107
+ last_sent_vt = max(attempt.sent_vt for attempt in view.attempts)
108
+ found.append(
109
+ OpenEscalation(
110
+ escalation_id=escalation.escalation_id,
111
+ action_id=action_id,
112
+ intent_id=action.intent_id,
113
+ operation=action.operation,
114
+ target=action.target,
115
+ args=action.args,
116
+ approval_id=grant.approval_id,
117
+ opened_vt=escalation.opened_vt,
118
+ last_sent_vt=last_sent_vt,
119
+ not_committed_from_vt=last_sent_vt + settle_ms,
120
+ )
121
+ )
122
+ return tuple(found)
123
+
124
+ def resolve(
125
+ self,
126
+ escalation_id: str,
127
+ resolution: Resolution,
128
+ effect_id: str | None = None,
129
+ *,
130
+ actor: str,
131
+ ) -> ActionResult:
132
+ """Attest an escalated action's outcome now: T11 or T12, `human_attested` (0003).
133
+
134
+ `effect_id` names the effect for `committed` and is None for `not_committed`.
135
+ `actor` names the human, as the escalation records it. Returns the action's
136
+ result after the attestation.
137
+
138
+ Raises `UnknownEscalation` for an id no action has; `EscalationResolved` for an
139
+ escalation already resolved; `BeforeSettleTime` for "not committed" before S past
140
+ the action's latest send; and `ValueError` for an effect id that does not fit the
141
+ resolution. The two refusals are `StepRefused`, raised once the store refused.
142
+ """
143
+ if not actor:
144
+ raise ValueError("an attestation names the human who made it")
145
+ check_text(actor, "the actor")
146
+ if effect_id is not None:
147
+ check_text(effect_id, "the effect id")
148
+ escalation = self._store.snapshot().escalations.get(escalation_id)
149
+ if escalation is None:
150
+ raise UnknownEscalation(escalation_id)
151
+ action_id = escalation.action_id
152
+ try:
153
+ self._store.attest(action_id, resolution, effect_id, actor, self._scheduler.now)
154
+ except StepRefused as refused:
155
+ named = self._named(action_id, resolution, refused)
156
+ if named is None:
157
+ raise
158
+ raise named from refused
159
+ self._dispatcher.wake(action_id)
160
+ return steps.result_for(self._store.view(action_id))
161
+
162
+ def _named(
163
+ self, action_id: str, resolution: Resolution, refused: StepRefused
164
+ ) -> StepRefused | None:
165
+ """Why the store refused an attestation, read from the records after it did."""
166
+ view = self._store.view(action_id)
167
+ escalation = view.escalation
168
+ if escalation is not None and escalation.resolved_vt is not None:
169
+ message = (
170
+ f"{escalation.escalation_id} is resolved already: {escalation.resolution},"
171
+ f" attested by {escalation.actor} at vt {escalation.resolved_vt}"
172
+ )
173
+ return EscalationResolved(message, escalation)
174
+ if resolution is Resolution.NOT_COMMITTED and view.attempts:
175
+ last_sent_vt = max(attempt.sent_vt for attempt in view.attempts)
176
+ due = last_sent_vt + self._store.settings.settle_ms
177
+ if self._scheduler.now < due:
178
+ return BeforeSettleTime(str(refused), due)
179
+ return None
@@ -0,0 +1,398 @@
1
+ """The gateway's admin API over HTTP, built with FastAPI (0002 rule 22, 0003, 0010).
2
+
3
+ `admin_app` serves one gateway's admin path as JSON. It lists the gateway's actions,
4
+ grants and action events and its open escalations, and it resolves an escalation when a
5
+ human attests what happened: committed, naming the effect, or not committed (0003,
6
+ escalation). It never issues or revokes approvals; that happens in the approvals service
7
+ (0002, rule 22). In-process runs and the demos call `GatewayAdmin` directly, as the
8
+ scripted resolver does. This app is for a gateway served over HTTP, which mounts it, for
9
+ example under `/admin`. Paths below are relative to that mount.
10
+
11
+ - `GET /actions`: `actions`, every action in action-id order, with its state, intent,
12
+ operation, target, arguments, grant, the approval its grant names and its effect id.
13
+ - `GET /actions/{action_id}`: the `action`, its `escalation` (or null) and its
14
+ `events`, in seq order.
15
+ - `GET /grants`: `grants`, every grant in action-id order.
16
+ - `GET /events?from_seq=N`: `events`, the run's action events with seq N or more, in
17
+ seq order. N defaults to 0, which gives all of them.
18
+ - `GET /escalations`: `escalations`, the open ones, as `GatewayAdmin.open_escalations`
19
+ lists them, each with `not_committed_from_vt`.
20
+ - `POST /escalations/{escalation_id}/resolve`: the action's result after the
21
+ attestation, in the shape the agent sees (0003).
22
+
23
+ The resolve request is `{"resolution": "committed", "effect_id": "PO-0001", "actor":
24
+ "ops-1"}`, or `not_committed` with no effect id. It goes through `GatewayAdmin.resolve`,
25
+ so the store's rules and the dispatcher's wake apply unchanged: T11 or T12, with reason
26
+ `human_attested`, and every wait on the action ends at once.
27
+
28
+ Every error answers `{"reason": ..., "message": ...}`:
29
+
30
+ - 401 without the bearer token: `missing_token`, `wrong_scheme` or `invalid_token`;
31
+ - 404 for an unknown action, escalation or path: `unknown_action`, `unknown_escalation`
32
+ or `not_found` (405 `method_not_allowed` for a known path with another method);
33
+ - 409 for a step the store refused: `escalation_resolved`, with the `escalation` as it
34
+ was resolved, or `before_settle_time`, with `not_committed_from_vt`, when "not
35
+ committed" comes before S past the action's latest send (0010, reading 8), or
36
+ `step_refused` for any other refusal, with the store's message;
37
+ - 422 `invalid_request` for input that does not parse;
38
+ - 500 `internal_error` for anything else.
39
+
40
+ Authentication: every HTTP request needs `Authorization: Bearer TOKEN` (RFC 6750), with
41
+ the token the app was built with, before routing, so an unknown path needs it too. A
42
+ deployment reads the token from `FIVEFOLD_ADMIN_API_TOKEN` (`token_from_environment`).
43
+ The app compares SHA-256 digests of the two tokens in constant time, so how long a
44
+ refusal takes says nothing about the token, not even its length. The app refuses to be
45
+ built with an empty token, because the admin API attests outcomes, or with a token that
46
+ RFC 6750 does not allow.
47
+
48
+ Time and reach: the app reads time only through `GatewayAdmin`, from the gateway's
49
+ scheduler (0009). It never contacts the simulator, and holds no simulator client and no
50
+ credential: it reads the gateway's records and calls the admin path. FastAPI's own
51
+ telemetry is off, so a request reads no wall clock, and no environment variable can make
52
+ the app export anything.
53
+
54
+ Every handler is a coroutine, so FastAPI runs it on the event loop that serves the app,
55
+ never in a worker thread. Serve the app on the gateway's own event loop: the handlers
56
+ call the store and the dispatcher directly, a store is used from one thread at a time,
57
+ and the dispatcher's wake sets the loop's events. Under the deterministic scheduler, a
58
+ request made in a scheduler event, such as one through httpx's ASGI transport, waits on
59
+ no timer and on no real wait, so `settle` lets it finish before the next event fires:
60
+ it acts at that event's virtual time, as a call to `GatewayAdmin` there would.
61
+
62
+ FastAPI and Starlette APIs used, checked in the installed source (fastapi 0.162.7,
63
+ starlette 1.10.0): `FastAPI(openapi_url=, docs_url=, redoc_url=, telemetry=)`,
64
+ `FastAPI.get`, `FastAPI.post`, `FastAPI.exception_handler`, `FastAPI.add_middleware`,
65
+ `fastapi.Query`, `fastapi.exceptions.RequestValidationError.errors`,
66
+ `fastapi.responses.JSONResponse`, `starlette.exceptions.HTTPException`,
67
+ `starlette.datastructures.Headers(scope=)` and the types in `starlette.types`.
68
+ """
69
+
70
+ from __future__ import annotations
71
+
72
+ import hashlib
73
+ import hmac
74
+ import os
75
+ import re
76
+ from collections.abc import Mapping
77
+ from typing import Annotated, Protocol
78
+
79
+ from fastapi import FastAPI, Query, Request
80
+ from fastapi.exceptions import RequestValidationError
81
+ from fastapi.responses import JSONResponse
82
+ from pydantic import BaseModel, ConfigDict, StringConstraints, model_validator
83
+ from starlette.datastructures import Headers
84
+ from starlette.exceptions import HTTPException as StarletteHTTPException
85
+ from starlette.types import ASGIApp, Receive, Scope, Send
86
+
87
+ from fivefold.domain.api import Id
88
+ from fivefold.gateway import wire
89
+ from fivefold.gateway.admin import (
90
+ BeforeSettleTime,
91
+ EscalationResolved,
92
+ GatewayAdmin,
93
+ OpenEscalation,
94
+ UnknownEscalation,
95
+ )
96
+ from fivefold.gateway.codec import to_json
97
+ from fivefold.gateway.records import Action, ActionEvent, Escalation, Grant, Resolution, Snapshot
98
+ from fivefold.gateway.steps import StepRefused, action_number
99
+ from fivefold.gateway.store import UnknownAction, view_of
100
+
101
+ TOKEN_VARIABLE = "FIVEFOLD_ADMIN_API_TOKEN"
102
+ """The environment variable a deployment reads the admin API's bearer token from."""
103
+
104
+ REALM = "fivefold-admin"
105
+ """The realm a 401 answer names in its `WWW-Authenticate` header (RFC 6750)."""
106
+
107
+ _TOKEN = re.compile(r"[A-Za-z0-9\-._~+/]+=*")
108
+ """RFC 6750's `b64token`: what a bearer token may hold."""
109
+
110
+ Json = dict[str, object]
111
+
112
+ Actor = Annotated[str, StringConstraints(pattern=r"^[^\x00-\x1f\x7f]{1,200}$")]
113
+ """The human who attests: 1 to 200 characters, no control characters."""
114
+
115
+
116
+ class GatewayRecords(Protocol):
117
+ """The admin API's read path: the gateway's records as one consistent snapshot.
118
+
119
+ Every `ActionStore` is one. A gateway may pass the store its admin path uses, or a
120
+ further store of the same run on its own connection.
121
+ """
122
+
123
+ def snapshot(self) -> Snapshot:
124
+ """Every gateway record of the run, as one read sees them."""
125
+ ...
126
+
127
+ def events_from(self, seq: int) -> tuple[ActionEvent, ...]:
128
+ """The run's action events with seq `seq` or more, in seq order. `GET /events`
129
+ reads only these, so polling it never reads the rest of the run."""
130
+ ...
131
+
132
+
133
+ class Attestation(BaseModel):
134
+ """What a human attests about an escalated action (0003, escalation)."""
135
+
136
+ model_config = ConfigDict(extra="forbid", frozen=True)
137
+
138
+ resolution: Resolution
139
+ effect_id: Id | None = None
140
+ actor: Actor
141
+
142
+ @model_validator(mode="after")
143
+ def _effect_fits(self) -> Attestation:
144
+ if (self.resolution is Resolution.COMMITTED) != (self.effect_id is not None):
145
+ raise ValueError("effect_id names the effect for committed, and only for committed")
146
+ return self
147
+
148
+
149
+ def token_from_environment(environ: Mapping[str, str] | None = None) -> str:
150
+ """The admin API's bearer token, from `FIVEFOLD_ADMIN_API_TOKEN`.
151
+
152
+ Raises `ValueError` when the variable is missing or empty. `environ` defaults to the
153
+ process's environment.
154
+ """
155
+ token = (os.environ if environ is None else environ).get(TOKEN_VARIABLE, "")
156
+ if not token:
157
+ raise ValueError(f"set {TOKEN_VARIABLE} to the admin API's bearer token")
158
+ return token
159
+
160
+
161
+ def admin_app(admin: GatewayAdmin, records: GatewayRecords, *, token: str) -> FastAPI:
162
+ """The admin API of one gateway, as an ASGI app; see the module docstring.
163
+
164
+ `admin` is the gateway's admin path, `records` its read path and `token` the bearer
165
+ token every request must carry. Raises `ValueError` for an empty token, or one with a
166
+ character RFC 6750 does not allow.
167
+ """
168
+ if not token:
169
+ raise ValueError("the admin API needs a bearer token: it attests outcomes")
170
+ if not _TOKEN.fullmatch(token):
171
+ raise ValueError(
172
+ "a bearer token holds letters, digits and -._~+/, then any number of = (RFC 6750)"
173
+ )
174
+ app = FastAPI(
175
+ title="FiveFold gateway admin API",
176
+ openapi_url=None,
177
+ docs_url=None,
178
+ redoc_url=None,
179
+ telemetry={"tracing": False, "metrics": False, "logs": False, "auto_configure": False},
180
+ )
181
+ app.add_middleware(BearerToken, digest=_digest(token))
182
+
183
+ @app.exception_handler(StarletteHTTPException)
184
+ async def http_error(request: Request, error: StarletteHTTPException) -> JSONResponse:
185
+ reasons = {404: "not_found", 405: "method_not_allowed"}
186
+ reason = reasons.get(error.status_code, "http_error")
187
+ return _error(error.status_code, reason, str(error.detail), headers=error.headers)
188
+
189
+ @app.exception_handler(RequestValidationError)
190
+ async def invalid_request(request: Request, error: RequestValidationError) -> JSONResponse:
191
+ return _error(422, "invalid_request", _problems(error))
192
+
193
+ @app.exception_handler(Exception)
194
+ async def internal_error(request: Request, error: Exception) -> JSONResponse:
195
+ return _error(500, "internal_error", "the gateway could not serve this request")
196
+
197
+ @app.get("/actions")
198
+ async def list_actions() -> JSONResponse:
199
+ snapshot = records.snapshot()
200
+ actions = sorted(snapshot.actions.values(), key=lambda a: action_number(a.action_id))
201
+ return JSONResponse({"actions": [_action(a, _grant_of(snapshot, a)) for a in actions]})
202
+
203
+ @app.get("/actions/{action_id}")
204
+ async def get_action(action_id: str) -> JSONResponse:
205
+ try:
206
+ view = view_of(records.snapshot(), action_id)
207
+ except UnknownAction:
208
+ return _error(404, "unknown_action", f"no action {action_id}")
209
+ escalation = view.escalation
210
+ return JSONResponse(
211
+ {
212
+ "action": _action(view.action, view.grant),
213
+ "escalation": None if escalation is None else _escalation(escalation),
214
+ "events": [_event(event) for event in view.events],
215
+ }
216
+ )
217
+
218
+ @app.get("/grants")
219
+ async def list_grants() -> JSONResponse:
220
+ grants = sorted(
221
+ records.snapshot().grants.values(), key=lambda g: action_number(g.action_id)
222
+ )
223
+ return JSONResponse({"grants": [_grant(grant) for grant in grants]})
224
+
225
+ @app.get("/events")
226
+ async def list_events(from_seq: Annotated[int, Query(ge=0)] = 0) -> JSONResponse:
227
+ events = [_event(e) for e in records.events_from(from_seq)]
228
+ return JSONResponse({"events": events})
229
+
230
+ @app.get("/escalations")
231
+ async def list_escalations() -> JSONResponse:
232
+ escalations = [_open_escalation(e) for e in admin.open_escalations()]
233
+ return JSONResponse({"escalations": escalations})
234
+
235
+ @app.post("/escalations/{escalation_id}/resolve")
236
+ async def resolve(escalation_id: str, attestation: Attestation) -> JSONResponse:
237
+ try:
238
+ result = admin.resolve(
239
+ escalation_id,
240
+ attestation.resolution,
241
+ attestation.effect_id,
242
+ actor=attestation.actor,
243
+ )
244
+ except UnknownEscalation:
245
+ return _error(404, "unknown_escalation", f"no escalation {escalation_id}")
246
+ except EscalationResolved as refused:
247
+ resolved = _escalation(refused.escalation)
248
+ return _error(409, "escalation_resolved", str(refused), escalation=resolved)
249
+ except BeforeSettleTime as refused:
250
+ due = refused.not_committed_from_vt
251
+ return _error(409, "before_settle_time", str(refused), not_committed_from_vt=due)
252
+ except StepRefused as refused:
253
+ return _error(409, "step_refused", str(refused))
254
+ except ValueError as invalid:
255
+ return _error(422, "invalid_request", str(invalid))
256
+ return JSONResponse(wire.action(result))
257
+
258
+ return app
259
+
260
+
261
+ class BearerToken:
262
+ """ASGI middleware that refuses every HTTP request without the app's bearer token.
263
+
264
+ It runs before routing, so every path needs the token. `digest` is the SHA-256 of
265
+ the token. Other scopes pass through: the lifespan, and WebSockets, which no route
266
+ serves, so the router closes them.
267
+ """
268
+
269
+ def __init__(self, app: ASGIApp, digest: bytes) -> None:
270
+ self._app = app
271
+ self._digest = digest
272
+
273
+ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
274
+ if scope["type"] == "http":
275
+ refusal = self._refusal(Headers(scope=scope).get("authorization"))
276
+ if refusal is not None:
277
+ await refusal(scope, receive, send)
278
+ return
279
+ await self._app(scope, receive, send)
280
+
281
+ def _refusal(self, header: str | None) -> JSONResponse | None:
282
+ """The 401 answer for this Authorization header, or None when the token is right."""
283
+ if header is None:
284
+ return _unauthorized("missing_token", "send Authorization: Bearer TOKEN")
285
+ scheme, _, credentials = header.partition(" ")
286
+ if scheme.lower() != "bearer":
287
+ return _unauthorized("wrong_scheme", "the admin API takes a bearer token")
288
+ if not hmac.compare_digest(_digest(credentials.strip()), self._digest):
289
+ return _unauthorized("invalid_token", "this is not the gateway's admin token")
290
+ return None
291
+
292
+
293
+ def _digest(token: str) -> bytes:
294
+ return hashlib.sha256(token.encode("utf-8")).digest()
295
+
296
+
297
+ def _unauthorized(reason: str, message: str) -> JSONResponse:
298
+ challenge = f'Bearer realm="{REALM}"'
299
+ if reason == "invalid_token":
300
+ challenge += ', error="invalid_token"'
301
+ return _error(401, reason, message, headers={"WWW-Authenticate": challenge})
302
+
303
+
304
+ def _error(
305
+ status: int,
306
+ reason: str,
307
+ message: str,
308
+ *,
309
+ headers: Mapping[str, str] | None = None,
310
+ **extra: object,
311
+ ) -> JSONResponse:
312
+ body: Json = {"reason": reason, "message": message, **extra}
313
+ return JSONResponse(body, status_code=status, headers=headers)
314
+
315
+
316
+ def _problems(error: RequestValidationError) -> str:
317
+ """One clause per problem, naming where it is: `body.resolution: Input should be ...`."""
318
+ lines = []
319
+ for problem in error.errors():
320
+ where = ".".join(str(part) for part in problem.get("loc", ()))
321
+ message = str(problem.get("msg", "invalid"))
322
+ lines.append(f"{where}: {message}" if where else message)
323
+ return "; ".join(lines)
324
+
325
+
326
+ # Records as JSON ---------------------------------------------------------------------------
327
+
328
+
329
+ def _grant_of(snapshot: Snapshot, action: Action) -> Grant | None:
330
+ return None if action.grant_id is None else snapshot.grants.get(action.grant_id)
331
+
332
+
333
+ def _action(action: Action, grant: Grant | None) -> Json:
334
+ return {
335
+ "action_id": action.action_id,
336
+ "intent_id": action.intent_id,
337
+ "operation": action.operation,
338
+ "target": action.target,
339
+ "args": dict(action.args),
340
+ "state": str(action.state),
341
+ "contract": str(action.contract),
342
+ "grant_id": action.grant_id,
343
+ "approval_id": None if grant is None else grant.approval_id,
344
+ "effect_id": action.effect_id,
345
+ "created_vt": action.created_vt,
346
+ "updated_vt": action.updated_vt,
347
+ }
348
+
349
+
350
+ def _grant(grant: Grant) -> Json:
351
+ return {
352
+ "grant_id": grant.grant_id,
353
+ "action_id": grant.action_id,
354
+ "approval_id": grant.approval_id,
355
+ "state": str(grant.state),
356
+ "requested_vt": grant.requested_vt,
357
+ "consumed_vt": grant.consumed_vt,
358
+ }
359
+
360
+
361
+ def _event(event: ActionEvent) -> Json:
362
+ return {
363
+ "seq": event.seq,
364
+ "action_id": event.action_id,
365
+ "kind": str(event.kind),
366
+ "from_state": None if event.from_state is None else str(event.from_state),
367
+ "to_state": str(event.to_state),
368
+ "reason": str(event.reason),
369
+ "details": to_json(event.details),
370
+ "vt": event.vt,
371
+ }
372
+
373
+
374
+ def _escalation(escalation: Escalation) -> Json:
375
+ return {
376
+ "escalation_id": escalation.escalation_id,
377
+ "action_id": escalation.action_id,
378
+ "opened_vt": escalation.opened_vt,
379
+ "resolved_vt": escalation.resolved_vt,
380
+ "resolution": None if escalation.resolution is None else str(escalation.resolution),
381
+ "effect_id": escalation.effect_id,
382
+ "actor": escalation.actor,
383
+ }
384
+
385
+
386
+ def _open_escalation(escalation: OpenEscalation) -> Json:
387
+ return {
388
+ "escalation_id": escalation.escalation_id,
389
+ "action_id": escalation.action_id,
390
+ "intent_id": escalation.intent_id,
391
+ "operation": escalation.operation,
392
+ "target": escalation.target,
393
+ "args": dict(escalation.args),
394
+ "approval_id": escalation.approval_id,
395
+ "opened_vt": escalation.opened_vt,
396
+ "last_sent_vt": escalation.last_sent_vt,
397
+ "not_committed_from_vt": escalation.not_committed_from_vt,
398
+ }