This directory documents the implemented StarIntel Server runtime. It is written
from the code in source/starintel-gserver.asd, not from an aspirational
architecture.
Security design documents are explicitly marked DESIGN and do not claim that
the corresponding controls are implemented.
- README — install, run, submit a document, and find the main entry points.
- Architecture — understand startup, components, concurrency, and the repository.
- Document specification — understand the data that moves through the system.
- Actors — build local actors and connect external actor services.
- Messaging — understand routing, delivery, recursion, and loop control.
- Configuration — configure local, container, remote, and tuned deployments.
- HTTP API — call the service.
- HTTP authentication runtime — bootstrap, API-key lifecycle, CORS, request context, revocation behavior, and deployment.
- HTTP authorization runtime — capabilities, tenant/dataset/actor/target policy, route mapping, search isolation, Rabbit provenance, audit, and quotas.
- Docker/Nix stack and testing — operate and verify it.
- HTTP authentication threat model — protected assets, attackers, boundaries, controls, failures, and residual risks. Design contract.
- KV lease authentication boundary — target-lease assets, atomic ownership, fencing, replay controls, and the KV trust boundary. Normative design contract.
- Distributed target lease semantics — canonical lock identity, records, state transitions, operations, idempotency, deadlines, fencing enforcement, races, errors, audit, and recovery. Normative design contract.
- Lease-store protocol usage — Common Lisp examples for canonical identity, acquire, renew, inspect, list, release, serialization, typed outcomes, and owned shutdown.
- HTTP principal and capability contract — principal classes, credentials, capabilities, scopes, decisions, and route mapping. Design contract.
The exported API of every package is documented where it is defined: as Org markup inside Common Lisp docstrings. The reference is rendered into doc/api/index.org — one page per package plus a symbol index.
Regenerate it with:
make docs-api
Coverage is enforced in CI: make doc-coverage fails when any exported
symbol lacks a docstring.
- Next ordered implementation-loop prompt — copy-ready continuation prompt for issue #31 and the transition to #32.
| Area | Status | Notes |
|---|---|---|
| CouchDB database initialization | Active | Creates main, actor-event, and separate authentication databases; upserts required design documents |
| RabbitMQ document ingest | Active | documents.ingest.# |
| RabbitMQ update ingest | Active | documents.updated.#; partial deep merge and conflict retry |
| Target routing | Active | Local Sento actor or actors.<name>.new.target |
| Actor event storage | Active | Local receiver and separate events exchange consumer |
| HTTP API-key authentication | Active | Default-deny bearer authentication, immutable request context, lifecycle routes, exact-origin CORS, and separate credential storage |
| Fine-grained route authorization | Active | Closed capabilities and tenant/dataset/actor/target scopes enforced at HTTP and embedded service boundaries; unmapped routes deny |
| Authentication revocation cache | Active | No credential cache; committed revoke/disable is visible to the next verifier lookup |
| KV target leases | Protocol/Valkey backend | Backend-neutral typed protocol, deterministic unit-test backend, and atomic production Valkey adapter are active; HTTP operations remain 501 until issue #32 wires them into execution |
| Clouseau full-text search | Active in Compose | Search is authenticated and authorization clauses constrain tenant/dataset scope before backend execution |
| URL extractor pattern | Experimental | Actor starts; complete global pattern dispatcher is not evident |
| User-finder/user-hunt actors | Present, inactive | Files are not in the ASDF component list |
| HTTP event endpoint | Stub | /new/event/:id has no implementation; replay authorization is active but backend returns 501 |
| Strict StarIntel 0.9 ingest validation | Partially wired | HTTP boundary validates required envelope fields and schema version; Rabbit ingest remains a separate boundary |
When documentation and code disagree, the current code wins. Correct the docs in the same pull request as behavior changes.
The document model itself lives in lost-rob0t/star-cl. The Python adapter lives in lost-rob0t/starintel-doc. This server transports and stores those documents, but it currently also carries legacy flat 0.8 behavior.