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.
Files changed (78) hide show
  1. agentlighthouse_core-0.4.0.dist-info/METADATA +358 -0
  2. agentlighthouse_core-0.4.0.dist-info/RECORD +78 -0
  3. agentlighthouse_core-0.4.0.dist-info/WHEEL +4 -0
  4. agentlighthouse_core-0.4.0.dist-info/entry_points.txt +2 -0
  5. agentlighthouse_core-0.4.0.dist-info/licenses/LICENSE +21 -0
  6. al_core/__init__.py +12 -0
  7. al_core/_bundled/configs/audit.yaml +12 -0
  8. al_core/_bundled/configs/balanced.yaml +36 -0
  9. al_core/_bundled/configs/strict.yaml +32 -0
  10. al_core/_bundled/dashboard/assets/index-CN2LU6nV.css +1 -0
  11. al_core/_bundled/dashboard/assets/index-DX6cZzRi.js +40 -0
  12. al_core/_bundled/dashboard/index.html +15 -0
  13. al_core/_bundled/policies/default-deny.yaml +37 -0
  14. al_core/a2a/__init__.py +25 -0
  15. al_core/a2a/envelope.py +60 -0
  16. al_core/a2a/mediator.py +221 -0
  17. al_core/app.py +427 -0
  18. al_core/audit/__init__.py +149 -0
  19. al_core/audit/db.py +481 -0
  20. al_core/audit/pg.py +350 -0
  21. al_core/audit/pool.py +260 -0
  22. al_core/audit/siem.py +97 -0
  23. al_core/capability/__init__.py +28 -0
  24. al_core/capability/budget.py +56 -0
  25. al_core/capability/gate.py +334 -0
  26. al_core/capability/hitl.py +331 -0
  27. al_core/capability/policy.py +270 -0
  28. al_core/capability/store.py +209 -0
  29. al_core/capability/taint.py +79 -0
  30. al_core/cli/__init__.py +1 -0
  31. al_core/cli/main.py +1275 -0
  32. al_core/config/__init__.py +436 -0
  33. al_core/config/watch.py +51 -0
  34. al_core/detect/__init__.py +23 -0
  35. al_core/detect/base.py +131 -0
  36. al_core/detect/bip39_words.py +267 -0
  37. al_core/detect/budget.py +92 -0
  38. al_core/detect/detect_secrets_adapter.py +110 -0
  39. al_core/detect/engine.py +270 -0
  40. al_core/detect/scanners.py +454 -0
  41. al_core/egress/__init__.py +27 -0
  42. al_core/egress/nftables.py +59 -0
  43. al_core/egress/selftest.py +94 -0
  44. al_core/embed.py +51 -0
  45. al_core/gateway/__init__.py +29 -0
  46. al_core/gateway/content.py +154 -0
  47. al_core/gateway/decision.py +124 -0
  48. al_core/gateway/dnspin.py +131 -0
  49. al_core/gateway/forward.py +261 -0
  50. al_core/gateway/policy.py +66 -0
  51. al_core/gateway/ssrf.py +178 -0
  52. al_core/gateway/vkeys.py +205 -0
  53. al_core/gateway/web.py +801 -0
  54. al_core/identity/__init__.py +209 -0
  55. al_core/jsonstore.py +73 -0
  56. al_core/keys/__init__.py +141 -0
  57. al_core/killswitch.py +130 -0
  58. al_core/learn/__init__.py +17 -0
  59. al_core/learn/bundle.py +76 -0
  60. al_core/learn/miner.py +156 -0
  61. al_core/learn/scanner.py +77 -0
  62. al_core/learn/testgen.py +107 -0
  63. al_core/mcp/__init__.py +25 -0
  64. al_core/mcp/chain.py +147 -0
  65. al_core/mcp/descriptors.py +111 -0
  66. al_core/mcp/mediator.py +150 -0
  67. al_core/mcp/proxy.py +161 -0
  68. al_core/mcp/session.py +537 -0
  69. al_core/memory/__init__.py +15 -0
  70. al_core/memory/guard.py +330 -0
  71. al_core/memory/store.py +80 -0
  72. al_core/normalize/__init__.py +254 -0
  73. al_core/principal.py +59 -0
  74. al_core/receipt/__init__.py +192 -0
  75. al_core/resources.py +33 -0
  76. al_core/runtime.py +471 -0
  77. al_core/skills/__init__.py +30 -0
  78. 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
+ ]