agentlighthouse-core 0.4.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.
- agentlighthouse_core-0.4.0.dist-info/METADATA +358 -0
- agentlighthouse_core-0.4.0.dist-info/RECORD +78 -0
- agentlighthouse_core-0.4.0.dist-info/WHEEL +4 -0
- agentlighthouse_core-0.4.0.dist-info/entry_points.txt +2 -0
- agentlighthouse_core-0.4.0.dist-info/licenses/LICENSE +21 -0
- al_core/__init__.py +12 -0
- al_core/_bundled/configs/audit.yaml +12 -0
- al_core/_bundled/configs/balanced.yaml +36 -0
- al_core/_bundled/configs/strict.yaml +32 -0
- al_core/_bundled/dashboard/assets/index-CN2LU6nV.css +1 -0
- al_core/_bundled/dashboard/assets/index-DX6cZzRi.js +40 -0
- al_core/_bundled/dashboard/index.html +15 -0
- al_core/_bundled/policies/default-deny.yaml +37 -0
- al_core/a2a/__init__.py +25 -0
- al_core/a2a/envelope.py +60 -0
- al_core/a2a/mediator.py +221 -0
- al_core/app.py +427 -0
- al_core/audit/__init__.py +149 -0
- al_core/audit/db.py +481 -0
- al_core/audit/pg.py +350 -0
- al_core/audit/pool.py +260 -0
- al_core/audit/siem.py +97 -0
- al_core/capability/__init__.py +28 -0
- al_core/capability/budget.py +56 -0
- al_core/capability/gate.py +334 -0
- al_core/capability/hitl.py +331 -0
- al_core/capability/policy.py +270 -0
- al_core/capability/store.py +209 -0
- al_core/capability/taint.py +79 -0
- al_core/cli/__init__.py +1 -0
- al_core/cli/main.py +1275 -0
- al_core/config/__init__.py +436 -0
- al_core/config/watch.py +51 -0
- al_core/detect/__init__.py +23 -0
- al_core/detect/base.py +131 -0
- al_core/detect/bip39_words.py +267 -0
- al_core/detect/budget.py +92 -0
- al_core/detect/detect_secrets_adapter.py +110 -0
- al_core/detect/engine.py +270 -0
- al_core/detect/scanners.py +454 -0
- al_core/egress/__init__.py +27 -0
- al_core/egress/nftables.py +59 -0
- al_core/egress/selftest.py +94 -0
- al_core/embed.py +51 -0
- al_core/gateway/__init__.py +29 -0
- al_core/gateway/content.py +154 -0
- al_core/gateway/decision.py +124 -0
- al_core/gateway/dnspin.py +131 -0
- al_core/gateway/forward.py +261 -0
- al_core/gateway/policy.py +66 -0
- al_core/gateway/ssrf.py +178 -0
- al_core/gateway/vkeys.py +205 -0
- al_core/gateway/web.py +801 -0
- al_core/identity/__init__.py +209 -0
- al_core/jsonstore.py +73 -0
- al_core/keys/__init__.py +141 -0
- al_core/killswitch.py +130 -0
- al_core/learn/__init__.py +17 -0
- al_core/learn/bundle.py +76 -0
- al_core/learn/miner.py +156 -0
- al_core/learn/scanner.py +77 -0
- al_core/learn/testgen.py +107 -0
- al_core/mcp/__init__.py +25 -0
- al_core/mcp/chain.py +147 -0
- al_core/mcp/descriptors.py +111 -0
- al_core/mcp/mediator.py +150 -0
- al_core/mcp/proxy.py +161 -0
- al_core/mcp/session.py +537 -0
- al_core/memory/__init__.py +15 -0
- al_core/memory/guard.py +330 -0
- al_core/memory/store.py +80 -0
- al_core/normalize/__init__.py +254 -0
- al_core/principal.py +59 -0
- al_core/receipt/__init__.py +192 -0
- al_core/resources.py +33 -0
- al_core/runtime.py +471 -0
- al_core/skills/__init__.py +30 -0
- al_core/skills/guard.py +218 -0
al_core/app.py
ADDED
|
@@ -0,0 +1,427 @@
|
|
|
1
|
+
"""Control-plane HTTP surface (health, evidence API, kill switch, dashboard).
|
|
2
|
+
|
|
3
|
+
Runs on the control network. ``/healthz`` reports config validity and the
|
|
4
|
+
receipt chain-verify status. The read-only evidence API (``/api/*``) and the
|
|
5
|
+
static dashboard (``/dashboard``) let an operator see what the plane decided —
|
|
6
|
+
verdict/action breakdowns, block reasons, and recent receipts — sourced from
|
|
7
|
+
the SQLite **mirror** (the JSONL ledger stays canonical). The one control
|
|
8
|
+
action here is the kill switch (``/api/killswitch``).
|
|
9
|
+
|
|
10
|
+
**Tenancy (Phase 6).** Every request resolves to a :class:`Principal` and every
|
|
11
|
+
evidence query is scoped to ``principal.org``. A principal bound to one org
|
|
12
|
+
cannot reach another org's events through *any* endpoint — including a direct
|
|
13
|
+
``/api/receipts/{seq}`` fetch, which returns 404 rather than leaking existence.
|
|
14
|
+
Cross-org (fleet) scope is only ever granted to an ``org=None`` admin.
|
|
15
|
+
|
|
16
|
+
Authentication is injectable (``authenticator``). The default is single-tenant:
|
|
17
|
+
the admin API token grants a fleet admin. The governance layer
|
|
18
|
+
swaps in a multi-org user directory; the scoping enforced here does not change,
|
|
19
|
+
so a governance bug can only narrow what a caller sees, never widen it.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
from __future__ import annotations
|
|
23
|
+
|
|
24
|
+
import secrets
|
|
25
|
+
from contextlib import asynccontextmanager
|
|
26
|
+
from pathlib import Path
|
|
27
|
+
|
|
28
|
+
from fastapi import FastAPI, Request
|
|
29
|
+
from fastapi.responses import JSONResponse, RedirectResponse
|
|
30
|
+
from fastapi.staticfiles import StaticFiles
|
|
31
|
+
|
|
32
|
+
from . import __version__
|
|
33
|
+
from .audit.pool import EvidencePool, RemotePlane
|
|
34
|
+
from .capability.hitl import HitlGate
|
|
35
|
+
from .capability.store import CapabilityStore
|
|
36
|
+
from .principal import Authenticator, Principal
|
|
37
|
+
from .resources import bundled
|
|
38
|
+
from .runtime import Runtime
|
|
39
|
+
|
|
40
|
+
# The built dashboard (Vite → frontend/dist) is served at /dashboard: from
|
|
41
|
+
# inside the wheel when installed, from the repo root in a checkout.
|
|
42
|
+
_DASHBOARD_DIST = bundled("dashboard")
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def bearer(authorization: str | None) -> str | None:
|
|
46
|
+
scheme, _, token = (authorization or "").partition(" ")
|
|
47
|
+
return token.strip() if scheme.lower() == "bearer" and token.strip() else None
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def admin_token_authenticator(expected: str) -> Authenticator:
|
|
51
|
+
"""Single-tenant default: the admin API token grants a fleet admin."""
|
|
52
|
+
|
|
53
|
+
def authenticate(token: str | None) -> Principal | None:
|
|
54
|
+
if token and secrets.compare_digest(token, expected):
|
|
55
|
+
return Principal(subject="admin", role="admin", org=None)
|
|
56
|
+
return None
|
|
57
|
+
|
|
58
|
+
return authenticate
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def create_app(
|
|
62
|
+
config_path: str | Path | None = None,
|
|
63
|
+
*,
|
|
64
|
+
data_dir: str | Path = "data",
|
|
65
|
+
authenticator: Authenticator | None = None,
|
|
66
|
+
**overrides,
|
|
67
|
+
) -> FastAPI:
|
|
68
|
+
runtime = Runtime(config_path, data_dir=data_dir, **overrides)
|
|
69
|
+
if authenticator is None:
|
|
70
|
+
token = runtime.settings.admin_api_token
|
|
71
|
+
if token is None or not token.get_secret_value():
|
|
72
|
+
runtime.close()
|
|
73
|
+
raise ValueError(
|
|
74
|
+
"admin_api_token is required to serve the control-plane API: set "
|
|
75
|
+
"AL_ADMIN_API_TOKEN (or the al_admin_api_token Docker secret)")
|
|
76
|
+
authenticator = admin_token_authenticator(token.get_secret_value())
|
|
77
|
+
authenticate = authenticator
|
|
78
|
+
|
|
79
|
+
# Evidence reads go through a pool: this plane's own ledger plus, when
|
|
80
|
+
# configured (control.dataplane_dir), the data plane's ledger opened
|
|
81
|
+
# READ-ONLY over a shared volume. That is what puts gateway traffic on
|
|
82
|
+
# the dashboard while each chain keeps exactly one writer.
|
|
83
|
+
remotes: list[RemotePlane] = []
|
|
84
|
+
dp_dir = runtime.settings.control.dataplane_dir
|
|
85
|
+
if dp_dir is not None:
|
|
86
|
+
remotes.append(RemotePlane(
|
|
87
|
+
"data", dp_dir, runtime.settings.control.dataplane_pubkey))
|
|
88
|
+
pool = EvidencePool("control" if remotes else "local",
|
|
89
|
+
runtime.ledger.db, remotes)
|
|
90
|
+
|
|
91
|
+
# HITL approvals are filed by the data plane (it runs the tool calls) and
|
|
92
|
+
# resolved here; the data plane reads the resolution back and executes
|
|
93
|
+
# the approved call. With control.approvals_dir both planes already share
|
|
94
|
+
# one approvals store (the runtime opened it). Without it, this plane
|
|
95
|
+
# resolves them in the data plane's own capability store, which needs
|
|
96
|
+
# write access to dataplane_dir.
|
|
97
|
+
approvals_store: CapabilityStore | None = None
|
|
98
|
+
if dp_dir is not None and runtime.settings.control.approvals_dir is None:
|
|
99
|
+
approvals_store = CapabilityStore(Path(dp_dir) / "capability_state.db")
|
|
100
|
+
approvals_gate = HitlGate(timeout_s=runtime.settings.policy.hitl_timeout_s,
|
|
101
|
+
store=approvals_store)
|
|
102
|
+
else:
|
|
103
|
+
approvals_gate = runtime.action_gate.hitl
|
|
104
|
+
|
|
105
|
+
@asynccontextmanager
|
|
106
|
+
async def lifespan(_app: FastAPI):
|
|
107
|
+
runtime.start_config_watch()
|
|
108
|
+
yield
|
|
109
|
+
pool.close()
|
|
110
|
+
if approvals_store is not None:
|
|
111
|
+
approvals_store.close()
|
|
112
|
+
runtime.close()
|
|
113
|
+
|
|
114
|
+
app = FastAPI(title="AgentLighthouse", version=__version__, lifespan=lifespan)
|
|
115
|
+
app.state.runtime = runtime
|
|
116
|
+
|
|
117
|
+
def _principal(request: Request) -> Principal | None:
|
|
118
|
+
return authenticate(bearer(request.headers.get("authorization")))
|
|
119
|
+
|
|
120
|
+
def _unauthorized() -> JSONResponse:
|
|
121
|
+
return JSONResponse(
|
|
122
|
+
{"error": "unauthorized", "detail": "a valid API token is required"},
|
|
123
|
+
status_code=401,
|
|
124
|
+
headers={"WWW-Authenticate": "Bearer"},
|
|
125
|
+
)
|
|
126
|
+
|
|
127
|
+
def _forbidden(capability: str) -> JSONResponse:
|
|
128
|
+
return JSONResponse(
|
|
129
|
+
{"error": "forbidden", "detail": f"capability '{capability}' required"},
|
|
130
|
+
status_code=403,
|
|
131
|
+
)
|
|
132
|
+
|
|
133
|
+
@app.get("/healthz")
|
|
134
|
+
def healthz() -> JSONResponse:
|
|
135
|
+
payload = runtime.healthz()
|
|
136
|
+
code = 200 if payload["status"] == "healthy" else 503
|
|
137
|
+
return JSONResponse(payload, status_code=code)
|
|
138
|
+
|
|
139
|
+
@app.get("/api/session")
|
|
140
|
+
def api_session(request: Request) -> JSONResponse:
|
|
141
|
+
"""Who am I: role, capabilities, and the org(s) I may see."""
|
|
142
|
+
p = _principal(request)
|
|
143
|
+
if p is None:
|
|
144
|
+
return _unauthorized()
|
|
145
|
+
# A tenant sees only its own org in the picker; a fleet admin sees all.
|
|
146
|
+
orgs = ([p.org] if p.org is not None
|
|
147
|
+
else sorted(pool.org_counts().keys()))
|
|
148
|
+
return JSONResponse({
|
|
149
|
+
"authenticated": True,
|
|
150
|
+
"subject": p.subject,
|
|
151
|
+
"role": p.role,
|
|
152
|
+
"capabilities": p.capabilities,
|
|
153
|
+
"org": p.org,
|
|
154
|
+
"orgs": orgs,
|
|
155
|
+
"planes": pool.planes,
|
|
156
|
+
"mode": runtime.settings.mode,
|
|
157
|
+
"env": runtime.settings.env,
|
|
158
|
+
})
|
|
159
|
+
|
|
160
|
+
# -- kill switch (control action; requires the 'configure' capability) ----
|
|
161
|
+
|
|
162
|
+
@app.get("/api/killswitch")
|
|
163
|
+
def api_killswitch_status(request: Request) -> JSONResponse:
|
|
164
|
+
p = _principal(request)
|
|
165
|
+
if p is None:
|
|
166
|
+
return _unauthorized()
|
|
167
|
+
return JSONResponse(runtime.killswitch.status())
|
|
168
|
+
|
|
169
|
+
@app.post("/api/killswitch")
|
|
170
|
+
async def api_killswitch(request: Request) -> JSONResponse:
|
|
171
|
+
"""Engage (default) or disengage the kill switch. Engaging drills the
|
|
172
|
+
whole data plane to deny-all; both transitions emit signed receipts.
|
|
173
|
+
|
|
174
|
+
The switch is fleet-wide by nature — it stops the mediator, not one
|
|
175
|
+
tenant — so it takes the 'configure' capability (admin only)."""
|
|
176
|
+
p = _principal(request)
|
|
177
|
+
if p is None:
|
|
178
|
+
return _unauthorized()
|
|
179
|
+
if not p.can("configure"):
|
|
180
|
+
return _forbidden("configure")
|
|
181
|
+
try:
|
|
182
|
+
body = await request.json()
|
|
183
|
+
except Exception: # noqa: BLE001 — empty body = engage
|
|
184
|
+
body = {}
|
|
185
|
+
if body.get("engage", True):
|
|
186
|
+
status = runtime.killswitch.engage(
|
|
187
|
+
"api", actor=f"user:{p.subject}", reason=body.get("reason"))
|
|
188
|
+
else:
|
|
189
|
+
status = runtime.killswitch.disengage(actor=f"user:{p.subject}")
|
|
190
|
+
return JSONResponse(status)
|
|
191
|
+
|
|
192
|
+
# -- HITL approvals (the operator side of the L4 gate) --------------------
|
|
193
|
+
|
|
194
|
+
@app.get("/api/approvals")
|
|
195
|
+
def api_approvals(request: Request) -> JSONResponse:
|
|
196
|
+
"""Pending approval requests, with age and time-to-lapse. A lapsed
|
|
197
|
+
request never appears here: timeout is a denial, not a queue entry.
|
|
198
|
+
Org-scoped like every other /api/* route: a tenant sees only requests
|
|
199
|
+
filed by its own org's actors."""
|
|
200
|
+
p = _principal(request)
|
|
201
|
+
if p is None:
|
|
202
|
+
return _unauthorized()
|
|
203
|
+
from .audit.db import org_of
|
|
204
|
+
|
|
205
|
+
gate = approvals_gate
|
|
206
|
+
rows = [{
|
|
207
|
+
"request_id": r.request_id,
|
|
208
|
+
"actor": r.actor,
|
|
209
|
+
"tool": r.tool,
|
|
210
|
+
"detail": r.detail,
|
|
211
|
+
"session": r.session,
|
|
212
|
+
"age_s": gate.age_s(r.request_id),
|
|
213
|
+
"remaining_s": gate.remaining_s(r.request_id),
|
|
214
|
+
"timeout_s": r.timeout_s,
|
|
215
|
+
} for r in gate.pending() if p.scope is None or org_of(r.actor) == p.scope]
|
|
216
|
+
return JSONResponse({"count": len(rows), "approvals": rows})
|
|
217
|
+
|
|
218
|
+
@app.post("/api/approvals/{request_id}")
|
|
219
|
+
async def api_resolve_approval(request: Request, request_id: str) -> JSONResponse:
|
|
220
|
+
"""Resolve one pending approval (allow | deny). The resolving actor is
|
|
221
|
+
recorded on the request and in a signed receipt. A lapsed or already-
|
|
222
|
+
resolved request conflicts — existing semantics are preserved exactly:
|
|
223
|
+
a timed-out request cannot be resolved, timeout remains a denial."""
|
|
224
|
+
p = _principal(request)
|
|
225
|
+
if p is None:
|
|
226
|
+
return _unauthorized()
|
|
227
|
+
if not p.can("approve"):
|
|
228
|
+
return _forbidden("approve")
|
|
229
|
+
try:
|
|
230
|
+
body = await request.json()
|
|
231
|
+
except Exception: # noqa: BLE001 — no body = no decision
|
|
232
|
+
body = {}
|
|
233
|
+
decision = body.get("decision")
|
|
234
|
+
if decision not in ("allow", "deny"):
|
|
235
|
+
return JSONResponse(
|
|
236
|
+
{"error": "invalid_decision", "detail": "decision must be 'allow' or 'deny'"},
|
|
237
|
+
status_code=422,
|
|
238
|
+
)
|
|
239
|
+
from .audit.db import org_of
|
|
240
|
+
|
|
241
|
+
gate = approvals_gate
|
|
242
|
+
req = gate.request(request_id)
|
|
243
|
+
if req is None:
|
|
244
|
+
return JSONResponse({"error": "not_found"}, status_code=404)
|
|
245
|
+
if p.scope is not None and org_of(req.actor) != p.scope:
|
|
246
|
+
# another tenant's request is *not found*, never leaked
|
|
247
|
+
return JSONResponse({"error": "not_found"}, status_code=404)
|
|
248
|
+
resolver = f"user:{p.subject}"
|
|
249
|
+
resolved = (gate.approve(request_id, by=resolver) if decision == "allow"
|
|
250
|
+
else gate.deny(request_id, by=resolver))
|
|
251
|
+
if not resolved:
|
|
252
|
+
# lapsed (timeout is a denial) or already resolved
|
|
253
|
+
return JSONResponse(
|
|
254
|
+
{"error": "conflict", "status": gate.status(request_id)},
|
|
255
|
+
status_code=409,
|
|
256
|
+
)
|
|
257
|
+
from .gateway.decision import finding
|
|
258
|
+
|
|
259
|
+
allowed = decision == "allow"
|
|
260
|
+
runtime.record(
|
|
261
|
+
actor=resolver,
|
|
262
|
+
action="mcp_tool_call",
|
|
263
|
+
target=f"hitl:{request_id}",
|
|
264
|
+
verdict="allow" if allowed else "block",
|
|
265
|
+
block_reason=None if allowed else "HITL_DENIED",
|
|
266
|
+
findings=[finding("hitl", "hitl.approved" if allowed else "hitl.denied",
|
|
267
|
+
"low" if allowed else "high", owasp="ASI09")],
|
|
268
|
+
)
|
|
269
|
+
return JSONResponse({
|
|
270
|
+
"request_id": request_id,
|
|
271
|
+
"status": gate.status(request_id),
|
|
272
|
+
"resolved_by": resolver,
|
|
273
|
+
})
|
|
274
|
+
|
|
275
|
+
# -- read-only evidence API (org-scoped for every principal) --------------
|
|
276
|
+
|
|
277
|
+
@app.get("/api/summary")
|
|
278
|
+
def api_summary(request: Request) -> JSONResponse:
|
|
279
|
+
p = _principal(request)
|
|
280
|
+
if p is None:
|
|
281
|
+
return _unauthorized()
|
|
282
|
+
health = runtime.healthz()
|
|
283
|
+
stats = pool.stats(p.scope)
|
|
284
|
+
chains = pool.chains(health["chain"])
|
|
285
|
+
return JSONResponse({
|
|
286
|
+
"mode": health["mode"],
|
|
287
|
+
"env": health["env"],
|
|
288
|
+
"config_hash": health["config_hash"],
|
|
289
|
+
"chain": health["chain"],
|
|
290
|
+
"chains": chains,
|
|
291
|
+
"killswitch": runtime.killswitch.status(),
|
|
292
|
+
"org": p.org,
|
|
293
|
+
**stats,
|
|
294
|
+
})
|
|
295
|
+
|
|
296
|
+
@app.get("/api/receipts")
|
|
297
|
+
def api_receipts(
|
|
298
|
+
request: Request,
|
|
299
|
+
limit: int = 100,
|
|
300
|
+
actor: str | None = None,
|
|
301
|
+
action: str | None = None,
|
|
302
|
+
verdict: str | None = None,
|
|
303
|
+
) -> JSONResponse:
|
|
304
|
+
p = _principal(request)
|
|
305
|
+
if p is None:
|
|
306
|
+
return _unauthorized()
|
|
307
|
+
receipts = pool.recent_filtered(
|
|
308
|
+
limit=limit, actor=actor, action=action, verdict=verdict, org=p.scope,
|
|
309
|
+
)
|
|
310
|
+
return JSONResponse({"count": len(receipts), "receipts": receipts})
|
|
311
|
+
|
|
312
|
+
@app.get("/api/chain")
|
|
313
|
+
def api_chain(request: Request) -> JSONResponse:
|
|
314
|
+
"""Chain-verify status. The chain spans the whole ledger (it is one
|
|
315
|
+
hash chain, by design), so a tenant sees only its integrity verdict —
|
|
316
|
+
never another org's sequence numbers."""
|
|
317
|
+
p = _principal(request)
|
|
318
|
+
if p is None:
|
|
319
|
+
return _unauthorized()
|
|
320
|
+
chains = pool.chains(runtime.healthz()["chain"])
|
|
321
|
+
if p.org is not None: # tenants see integrity verdicts, never lengths
|
|
322
|
+
chains = {plane: {"verified": c["verified"], "error": c["error"],
|
|
323
|
+
"reason": c.get("reason")}
|
|
324
|
+
for plane, c in chains.items()}
|
|
325
|
+
local = chains[pool.local_plane]
|
|
326
|
+
return JSONResponse({**local, "chains": chains})
|
|
327
|
+
|
|
328
|
+
@app.get("/api/search")
|
|
329
|
+
def api_search(
|
|
330
|
+
request: Request,
|
|
331
|
+
q: str | None = None,
|
|
332
|
+
since: str | None = None,
|
|
333
|
+
until: str | None = None,
|
|
334
|
+
actor: str | None = None,
|
|
335
|
+
action: str | None = None,
|
|
336
|
+
verdict: str | None = None,
|
|
337
|
+
org: str | None = None,
|
|
338
|
+
limit: int = 100,
|
|
339
|
+
) -> JSONResponse:
|
|
340
|
+
p = _principal(request)
|
|
341
|
+
if p is None:
|
|
342
|
+
return _unauthorized()
|
|
343
|
+
# A tenant's org filter can only ever narrow *within* its own scope —
|
|
344
|
+
# an org= parameter never widens it (that would be the whole attack).
|
|
345
|
+
scope = p.scope if p.scope is not None else org
|
|
346
|
+
if p.scope is not None and org is not None and org != p.scope:
|
|
347
|
+
return JSONResponse({"count": 0, "receipts": []})
|
|
348
|
+
receipts = pool.search(
|
|
349
|
+
query=q, since=since, until=until, actor=actor,
|
|
350
|
+
action=action, verdict=verdict, org=scope, limit=limit,
|
|
351
|
+
)
|
|
352
|
+
return JSONResponse({"count": len(receipts), "receipts": receipts})
|
|
353
|
+
|
|
354
|
+
@app.get("/api/trends")
|
|
355
|
+
def api_trends(request: Request, buckets: int = 24, span_hours: int = 24) -> JSONResponse:
|
|
356
|
+
p = _principal(request)
|
|
357
|
+
if p is None:
|
|
358
|
+
return _unauthorized()
|
|
359
|
+
buckets = max(1, min(buckets, 200))
|
|
360
|
+
return JSONResponse({"series": pool.time_series(
|
|
361
|
+
buckets=buckets, span_hours=max(1, span_hours), org=p.scope)})
|
|
362
|
+
|
|
363
|
+
@app.get("/api/receipts/{seq}")
|
|
364
|
+
def api_receipt(request: Request, seq: int, plane: str | None = None) -> JSONResponse:
|
|
365
|
+
p = _principal(request)
|
|
366
|
+
if p is None:
|
|
367
|
+
return _unauthorized()
|
|
368
|
+
if plane is not None and plane not in pool.planes:
|
|
369
|
+
return JSONResponse({"error": "not_found"}, status_code=404)
|
|
370
|
+
receipt = pool.receipt_by_seq(seq, p.scope, plane)
|
|
371
|
+
if receipt is None: # another tenant's seq is *not found*, never leaked
|
|
372
|
+
return JSONResponse({"error": "not_found"}, status_code=404)
|
|
373
|
+
return JSONResponse(receipt)
|
|
374
|
+
|
|
375
|
+
@app.get("/api/verify/{seq}")
|
|
376
|
+
def api_verify(request: Request, seq: int, plane: str | None = None) -> JSONResponse:
|
|
377
|
+
p = _principal(request)
|
|
378
|
+
if p is None:
|
|
379
|
+
return _unauthorized()
|
|
380
|
+
if not p.can("verify"):
|
|
381
|
+
return _forbidden("verify")
|
|
382
|
+
if plane is not None and plane not in pool.planes:
|
|
383
|
+
return JSONResponse({"error": "not_found"}, status_code=404)
|
|
384
|
+
receipt = pool.receipt_by_seq(seq, p.scope, plane)
|
|
385
|
+
if receipt is None:
|
|
386
|
+
return JSONResponse({"error": "not_found"}, status_code=404)
|
|
387
|
+
# Verify this receipt's signature + record hash with the standalone
|
|
388
|
+
# verifier (same code third parties run) — the audit "view trace"
|
|
389
|
+
# check. Each plane signs with its own mediator key. The pool's plane
|
|
390
|
+
# tag is presentation-only and must not enter the hashed body.
|
|
391
|
+
from al_verify.verify import verify_receipt
|
|
392
|
+
|
|
393
|
+
body = {k: v for k, v in receipt.items() if k != "plane"}
|
|
394
|
+
try:
|
|
395
|
+
key = pool.public_key_for(plane, runtime.public_key)
|
|
396
|
+
verify_receipt(body, key)
|
|
397
|
+
ok, error = True, None
|
|
398
|
+
except Exception as exc: # noqa: BLE001 — any failure = not verified
|
|
399
|
+
ok, error = False, str(exc)
|
|
400
|
+
return JSONResponse({
|
|
401
|
+
"seq": seq, "plane": receipt.get("plane"), "verified": ok, "error": error,
|
|
402
|
+
"record_hash": receipt.get("record_hash"),
|
|
403
|
+
"prev_hash": receipt.get("prev_hash"),
|
|
404
|
+
"sig": receipt.get("sig"),
|
|
405
|
+
})
|
|
406
|
+
|
|
407
|
+
# -- static dashboard (built Vite app) -----------------------------------
|
|
408
|
+
|
|
409
|
+
@app.get("/dashboard", response_model=None)
|
|
410
|
+
def dashboard_root() -> RedirectResponse | JSONResponse:
|
|
411
|
+
if not (_DASHBOARD_DIST / "index.html").exists():
|
|
412
|
+
return JSONResponse(
|
|
413
|
+
{"error": "dashboard_not_built",
|
|
414
|
+
"detail": "run `npm --prefix frontend install && npm --prefix frontend "
|
|
415
|
+
"run build` to produce frontend/dist"},
|
|
416
|
+
status_code=404,
|
|
417
|
+
)
|
|
418
|
+
return RedirectResponse(url="/dashboard/")
|
|
419
|
+
|
|
420
|
+
if (_DASHBOARD_DIST / "index.html").exists():
|
|
421
|
+
# html=True serves index.html at the mount root and 404s unknown paths;
|
|
422
|
+
# the SPA has no client-side routing, so that is sufficient. The page
|
|
423
|
+
# ships no secrets — its /api/* calls carry the operator's bearer token.
|
|
424
|
+
app.mount("/dashboard", StaticFiles(directory=str(_DASHBOARD_DIST), html=True),
|
|
425
|
+
name="dashboard")
|
|
426
|
+
|
|
427
|
+
return app
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
"""Audit ledger: append-only JSONL (canonical) + SQLite mirror + startup verify.
|
|
2
|
+
|
|
3
|
+
The ``Ledger`` is the single writer of evidence. It owns the ``ReceiptSigner``
|
|
4
|
+
(hash chain), appends each signed receipt to the canonical JSONL first, then
|
|
5
|
+
mirrors it into SQLite for queries. On construction it re-verifies the existing
|
|
6
|
+
JSONL chain against the mediator public key and refuses to run on tamper
|
|
7
|
+
(invariant #7), then resumes the chain from the persisted tail.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import json
|
|
13
|
+
import logging
|
|
14
|
+
from pathlib import Path
|
|
15
|
+
from typing import Any, Iterator, Sequence
|
|
16
|
+
|
|
17
|
+
from cryptography.hazmat.primitives.asymmetric.ed25519 import (
|
|
18
|
+
Ed25519PrivateKey,
|
|
19
|
+
Ed25519PublicKey,
|
|
20
|
+
)
|
|
21
|
+
|
|
22
|
+
from al_verify.canonical import canonicalize
|
|
23
|
+
from al_verify.verify import GENESIS_PREV_HASH, verify_chain
|
|
24
|
+
|
|
25
|
+
from ..receipt import ReceiptSigner
|
|
26
|
+
from .db import SqliteMirror
|
|
27
|
+
|
|
28
|
+
log = logging.getLogger("al.audit")
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class AuditTamperError(Exception):
|
|
32
|
+
"""Raised when the on-disk JSONL chain fails verification on startup."""
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class JsonlLedger:
|
|
36
|
+
"""Append-only canonical receipt log (one JCS line per receipt)."""
|
|
37
|
+
|
|
38
|
+
def __init__(self, path: str | Path) -> None:
|
|
39
|
+
self._path = Path(path)
|
|
40
|
+
self._path.parent.mkdir(parents=True, exist_ok=True)
|
|
41
|
+
|
|
42
|
+
@property
|
|
43
|
+
def path(self) -> Path:
|
|
44
|
+
return self._path
|
|
45
|
+
|
|
46
|
+
def append(self, receipt: dict[str, Any]) -> None:
|
|
47
|
+
line = canonicalize(receipt).decode("utf-8")
|
|
48
|
+
with self._path.open("a", encoding="utf-8", newline="\n") as fh:
|
|
49
|
+
fh.write(line + "\n")
|
|
50
|
+
|
|
51
|
+
def read_all(self) -> list[dict[str, Any]]:
|
|
52
|
+
return list(self.iter_records())
|
|
53
|
+
|
|
54
|
+
def iter_records(self) -> Iterator[dict[str, Any]]:
|
|
55
|
+
if not self._path.exists():
|
|
56
|
+
return
|
|
57
|
+
with self._path.open("r", encoding="utf-8") as fh:
|
|
58
|
+
for lineno, line in enumerate(fh, 1):
|
|
59
|
+
line = line.strip()
|
|
60
|
+
if not line:
|
|
61
|
+
continue
|
|
62
|
+
try:
|
|
63
|
+
yield json.loads(line)
|
|
64
|
+
except json.JSONDecodeError as exc:
|
|
65
|
+
raise AuditTamperError(
|
|
66
|
+
f"{self._path}:{lineno}: not valid JSON: {exc}"
|
|
67
|
+
) from exc
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
class Ledger:
|
|
71
|
+
"""Signs, persists, verifies-on-startup, and mirrors receipts."""
|
|
72
|
+
|
|
73
|
+
def __init__(
|
|
74
|
+
self,
|
|
75
|
+
signing_key: Ed25519PrivateKey,
|
|
76
|
+
public_key: Ed25519PublicKey,
|
|
77
|
+
*,
|
|
78
|
+
jsonl_path: str | Path,
|
|
79
|
+
db_path: str | Path,
|
|
80
|
+
dsn: str | None = None,
|
|
81
|
+
) -> None:
|
|
82
|
+
self._jsonl = JsonlLedger(jsonl_path)
|
|
83
|
+
# The mirror is a query surface, never the source of truth — swapping
|
|
84
|
+
# SQLite for Postgres (the concurrent-writer path) changes nothing about
|
|
85
|
+
# the evidence, only who may write the mirror at once.
|
|
86
|
+
if dsn:
|
|
87
|
+
from .pg import PostgresMirror
|
|
88
|
+
|
|
89
|
+
self._db = PostgresMirror(dsn)
|
|
90
|
+
else:
|
|
91
|
+
self._db = SqliteMirror(db_path)
|
|
92
|
+
|
|
93
|
+
# 1. Verify the existing chain end-to-end; refuse to run on tamper.
|
|
94
|
+
records = self._jsonl.read_all()
|
|
95
|
+
verify_chain(records, public_key) # raises VerificationError on tamper
|
|
96
|
+
|
|
97
|
+
# 2. Reconcile the mirror from the canonical log (mirror is disposable).
|
|
98
|
+
self._db.reconcile(records)
|
|
99
|
+
|
|
100
|
+
# 3. Resume the chain from the persisted tail.
|
|
101
|
+
if records:
|
|
102
|
+
tail = records[-1]
|
|
103
|
+
start_seq = int(tail["seq"]) + 1
|
|
104
|
+
prev_hash = tail["record_hash"]
|
|
105
|
+
else:
|
|
106
|
+
start_seq, prev_hash = 0, GENESIS_PREV_HASH
|
|
107
|
+
self._signer = ReceiptSigner(signing_key, start_seq=start_seq, prev_hash=prev_hash)
|
|
108
|
+
|
|
109
|
+
@property
|
|
110
|
+
def db(self): # noqa: ANN201 — SqliteMirror | PostgresMirror (same surface)
|
|
111
|
+
return self._db
|
|
112
|
+
|
|
113
|
+
@property
|
|
114
|
+
def next_seq(self) -> int:
|
|
115
|
+
return self._signer.next_seq
|
|
116
|
+
|
|
117
|
+
def last_config_change(self) -> dict[str, Any] | None:
|
|
118
|
+
"""The most recent config_change receipt, if any."""
|
|
119
|
+
return self._db.last_config_change()
|
|
120
|
+
|
|
121
|
+
def record(self, **fields: Any) -> dict[str, Any]:
|
|
122
|
+
"""Sign, append to JSONL (canonical), then mirror. Returns the receipt."""
|
|
123
|
+
receipt = self._signer.record(**fields)
|
|
124
|
+
self._jsonl.append(receipt) # source of truth first
|
|
125
|
+
try:
|
|
126
|
+
self._db.upsert_event(receipt)
|
|
127
|
+
except Exception: # noqa: BLE001 — mirror failure must not lose evidence
|
|
128
|
+
log.exception("SQLite mirror write failed for seq=%s (JSONL is intact)", receipt["seq"])
|
|
129
|
+
return receipt
|
|
130
|
+
|
|
131
|
+
def verify(self, public_key: Ed25519PublicKey) -> int:
|
|
132
|
+
return verify_chain(self._jsonl.read_all(), public_key)
|
|
133
|
+
|
|
134
|
+
def close(self) -> None:
|
|
135
|
+
self._db.close()
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
def verify_ledger_file(jsonl_path: str | Path, public_key: Ed25519PublicKey) -> int:
|
|
139
|
+
"""Standalone helper: verify a JSONL ledger's chain. Returns record count."""
|
|
140
|
+
return verify_chain(JsonlLedger(jsonl_path).read_all(), public_key)
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
__all__ = [
|
|
144
|
+
"AuditTamperError",
|
|
145
|
+
"JsonlLedger",
|
|
146
|
+
"Ledger",
|
|
147
|
+
"SqliteMirror",
|
|
148
|
+
"verify_ledger_file",
|
|
149
|
+
]
|