Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
79 commits
Select commit Hold shift + click to select a range
81beec4
Document on-prem small-team user access architecture and roadmap
dbowm91 Oct 13, 2026
2ac1e16
Plan local admin credentials, sessions, and principal attribution
dbowm91 Oct 13, 2026
2193865
Plan model access profiles, durable user budgets, admin UI, and quali…
dbowm91 Oct 13, 2026
0d6ebcd
Register on-prem user access milestones and dependency handoffs
dbowm91 Oct 13, 2026
b4f769b
Start on-prem user access M001
dbowm91 Oct 13, 2026
ecdc313
Add local admin and personal credential bootstrap
dbowm91 Oct 13, 2026
1a2d329
Move on-prem user M001 into closure
dbowm91 Oct 13, 2026
311d111
Close on-prem user M001 with SBC condition
dbowm91 Oct 13, 2026
dcf184f
Start on-prem user M002
dbowm91 Oct 13, 2026
087953a
Implement browser sessions and route authorization
dbowm91 Oct 13, 2026
f4a1861
Move on-prem user M002 to closure
dbowm91 Oct 13, 2026
bc69344
Close on-prem user M002 and ready M003
dbowm91 Oct 13, 2026
af0cb92
Start on-prem user M003
dbowm91 Oct 13, 2026
9af8787
Propagate user identity through inference
dbowm91 Oct 13, 2026
98f90b8
Move on-prem user M003 to closure
dbowm91 Oct 13, 2026
1007dfb
Close on-prem user M003 and ready M004
dbowm91 Oct 13, 2026
3cee6fe
Start on-prem user M004
dbowm91 Oct 13, 2026
f537df4
Add per-user model policy profiles
dbowm91 Oct 14, 2026
1a4ae78
Move on-prem user M004 to closing
dbowm91 Oct 14, 2026
c53bf4d
Test concurrent model policy refresh
dbowm91 Oct 14, 2026
9d2a176
Close on-prem user M004 and ready M005
dbowm91 Oct 14, 2026
03f6bbf
Start on-prem user M005
dbowm91 Oct 14, 2026
49dc6ce
Add durable user budget enforcement
dbowm91 Oct 14, 2026
0bf3e71
Begin closing on-prem user budgets
dbowm91 Oct 14, 2026
5bf0cfe
Close on-prem user budget milestone conditionally
dbowm91 Oct 14, 2026
e43fd78
Start on-prem user administration milestone
dbowm91 Oct 14, 2026
a3f2d00
Add on-prem user administration and qualification
dbowm91 Oct 14, 2026
1aeb892
Begin closing on-prem admin milestone
dbowm91 Oct 14, 2026
e035b9a
Close on-prem admin milestone conditionally
dbowm91 Oct 14, 2026
29c4e2b
Start on-prem qualification milestone
dbowm91 Oct 14, 2026
235d717
Update on-prem qualification registry
dbowm91 Oct 14, 2026
64f0062
Begin closing on-prem qualification milestone
dbowm91 Oct 14, 2026
81f7bbd
Close on-prem qualification conditionally
dbowm91 Oct 14, 2026
c18dcc2
Record on-prem qualification CI results
dbowm91 Oct 14, 2026
8f8ba4d
Plan corrective budget guarantees and on-prem qualification
dbowm91 Oct 14, 2026
01ea958
Reopen on-prem roadmap and register corrective dependency gates
dbowm91 Oct 14, 2026
b0e8715
Correct milestone anchors in on-prem handoff plans
dbowm91 Oct 14, 2026
49a0f84
Activate on-prem user access M008 hard token/cost admission corrective
dbowm91 Oct 14, 2026
0149a6c
Implement on-prem user access M008 hard token/cost admission corrective
dbowm91 Oct 14, 2026
ca77c54
Cover M008 proof carriage from admission through claim snapshot
dbowm91 Oct 14, 2026
fc2dabb
Close on-prem user access M008 and promote M009 to ready
dbowm91 Oct 14, 2026
372f0e1
Activate on-prem user access M009 global budget intersection corrective
dbowm91 Oct 14, 2026
04264a1
Implement on-prem user access M009 global budget intersection corrective
dbowm91 Oct 14, 2026
ea56ddc
Close on-prem user access M009 and promote M010 to ready
dbowm91 Oct 14, 2026
f704af2
Activate on-prem user access M013 transcode-eligibility corrective
dbowm91 Oct 14, 2026
4699ce1
Restore transcode protocols on the admission routing bridge
dbowm91 Oct 14, 2026
1218423
Close on-prem user access M013 transcode-eligibility corrective
dbowm91 Oct 14, 2026
542a2f2
Activate on-prem user access M010 budget crash recovery
dbowm91 Oct 14, 2026
be6248f
Implement on-prem user access M010 budget crash recovery and schema-5…
dbowm91 Oct 14, 2026
50d0f72
Close on-prem user access M010 budget crash recovery
dbowm91 Oct 14, 2026
ecda22b
Record M010 hosted CI outcomes and external findings
dbowm91 Oct 14, 2026
b13b866
Integrate on-prem user access M011 browser qualification
dbowm91 Oct 14, 2026
10eeee2
Re-freeze on-prem browser reference for merged budget UI
dbowm91 Oct 14, 2026
89012fe
Activate on-prem user access M012 at 10eeee25
dbowm91 Oct 14, 2026
b1f6d20
Add M012 SBC runner boundary contracts
dbowm91 Oct 14, 2026
820fdc9
Record M012 blocked closure with tooling foundation
dbowm91 Oct 14, 2026
161ba3e
Record M012 head CI outcomes in blocked closure
dbowm91 Oct 14, 2026
3c7def1
Close on-prem user access M012 physical SBC qualification on Pi 5
dbowm91 Oct 14, 2026
cd17671
Plan Rustls audit fix, adversarial auth review, and PR integration gates
dbowm91 Oct 15, 2026
bf16be5
Plan independent Pi 5 MMC concurrent-tail attribution
dbowm91 Oct 15, 2026
5881b20
Register security merge gates and separate nonblocking MMC diagnostics
dbowm91 Oct 15, 2026
d2c0830
Resolve corrective milestone source-roadmap anchors
dbowm91 Oct 15, 2026
0331705
Close Pi 5 MMC tail attribution
dbowm91 Oct 15, 2026
6f43611
Record M001 closure commit reference
dbowm91 Oct 15, 2026
80852e9
plans: activate on-prem M014 Rustls corrective
dbowm91 Oct 15, 2026
7462263
security: update Rustls to patched 0.23.46
dbowm91 Oct 15, 2026
c4e1154
plans: close on-prem M014 Rustls corrective
dbowm91 Oct 15, 2026
5dc9c38
plans: activate on-prem M015 threat review
dbowm91 Oct 15, 2026
b4d1563
Extend SBC concurrency attribution controls
dbowm91 Oct 15, 2026
b90234b
Fix on-prem login throttle isolation
dbowm91 Oct 15, 2026
6c2e1bd
Record supplemental Pi NVMe qualification
dbowm91 Oct 15, 2026
60bdeac
Correct M001 storage target to microSD
dbowm91 Oct 15, 2026
a526980
Harden on-prem authentication boundaries
dbowm91 Oct 15, 2026
8e36248
Record bounded microSD budget smoke run
dbowm91 Oct 15, 2026
deb1622
Harden privileged on-prem writes
dbowm91 Oct 15, 2026
d8fd9c2
Enforce hard budget and browser access boundaries
dbowm91 Oct 15, 2026
d5683b1
Close on-prem user M015 and unblock M016
dbowm91 Oct 15, 2026
3d68c71
Start on-prem user M016 reconciliation
dbowm91 Oct 15, 2026
d2fb281
Close on-prem user M016 with merge hold
dbowm91 Oct 15, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 44 additions & 8 deletions architecture/deep-dive-dashboard.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,10 @@ Back to [Architecture](README.md). See also the review index in
[overview.md](overview.md) (§§3, 12): §3 is the birds-eye route topology,
this file is the dashboard authority.

`rust/src/server/dashboard/` is the dashboard subsystem (17 files: 8
top-level plus 9 under `render/`). Its `mod.rs` is a
`rust/src/server/dashboard/` is the dashboard subsystem (19 files: 9
top-level plus 10 under `render/`). Its `admin.rs` owns bounded user,
profile, usage, audit, and personal-token page handlers; `render/admin.rs`
owns their pure HTML projections. Its `mod.rs` is a
thin facade that preserves the route entry points consumed by
`rust/src/server/mod.rs`. `routes.rs` owns page request parsing and bounded
data gathering; `api.rs` owns dashboard JSON request parsing and projections;
Expand Down Expand Up @@ -48,7 +50,7 @@ unconditionally (inference at `/v1/chat/completions`, `/v1/messages`,
`/static/dashboard.js`, `/static/chart.js` (served from
`chart.umd.min.js`), `/static/favicon.svg`, `/static/theme.css`). The
remaining dashboard surface below is dashboard-gated: it is registered
only when `[dashboard].enabled`, for 14 pages + 8 JSON endpoints.
only when `[dashboard].enabled`, for 17 dashboard-gated pages + 8 JSON endpoints.

When `[dashboard].enabled`, the router additionally serves `/`, `/accounts`, `/models`,
`/models/{*model_id}`, `/latency`, `/events`, `/timeseries`, `/bandwidth`,
Expand Down Expand Up @@ -98,6 +100,18 @@ responses, and rendering escapes operator/provider-controlled values. Runtime
and generation views distinguish active and retiring ownership without exposing
raw prompts, credentials, cache keys, or provider bodies.

The admin/member surface is owned by `dashboard/admin.rs` and the pure
`render/admin.rs` renderer. `/users`, `/profiles`, and `/admin/audit` are
registered only with the dashboard. `/my-account`, `/my-account/models`, and
`/usage` are browser-session routes; all remain private after identity
initialization even when `dashboard.public = true`. Admin handlers require an
active admin browser principal and every mutation checks same-origin plus the
session-bound CSRF token. Agent credentials cannot enter this surface.
Personal credential plaintext is rendered only in the creation response,
which is `no-store`; subsequent account reads contain only bounded labels and
metadata. The persistent audit projection stores actor, action, target kind,
target ID, and time, without request content or secrets.

## Rendering and themes

Pages share one layout (`render_dashboard_layout`) with period/theme
Expand All @@ -118,11 +132,14 @@ the embedded `rust/assets/dashboard/themes/*.toml` set parsed into CSS
variables. Static assets carry explicit cache headers; failures to read
dashboard data never block inference.

Default auth posture: `[dashboard].public` defaults to `true`, so ordinary
pages and non-sensitive stats data render without an API key. Inference
(`/v1/*`), integration (`/api/integrations/*`), and runtime/update/status
endpoints never inherit that exemption and stay authenticated;
`eggpool dashboard public --off` restores key auth on ordinary pages and data.
Legacy auth posture: `[dashboard].public` defaults to `true`, so ordinary
pages and non-sensitive stats data in `legacy_unmigrated` deployments render
without an API key. After identity initialization, dashboard pages and every
`/api/*` route require a browser session regardless of this setting; agent
tokens remain limited to inference, model discovery, and the integration
profile. `eggpool dashboard public --off` retains its legacy behavior, while
`eggpool users enable-managed` requires `dashboard.public = false` before the
managed transition.

## Safety invariants

Expand Down Expand Up @@ -199,12 +216,31 @@ remain unavailable rather than being inferred by page rendering.
The milestone evidence and source-to-panel review are recorded in
`plans/closure/dashboard/004-status.md`.

## On-prem admin and member browser qualification

The frozen Python oracle in `scripts/dashboard_parity/` only ever implemented the
historical M001-M012 pages. It is therefore the reference for those routes alone
and is never reopened as evidence for the on-prem user-access pages. Those pages
are owned by EggPool and are qualified by `scripts/dashboard_parity/on_prem.py`,
which starts one managed instance, bootstraps an administrator through
`eggpool users bootstrap`, and drives a real browser through both roles against
a Rust-owned approved reference at
`tests/fixtures/dashboard-on-prem-browser/reference.json`.

Browser sign-in is gated by `server::auth::same_origin`. A same-origin browser
form POST sends `Origin` and `Referer` together, so every provenance header that
is present must agree with the request `Host`; duplicated or userinfo-bearing
provenance still fails closed. Accepting only a lone `Origin` would have rejected
every real browser while still admitting a bare `Referer`.

## Verification

```bash
cargo test --manifest-path rust/Cargo.toml --test server_transport -- --test-threads=1
cargo test --manifest-path rust/Cargo.toml --test status_command -- --test-threads=1
cargo test --manifest-path rust/Cargo.toml --lib server::dashboard::tests -- --test-threads=1
cargo test --manifest-path rust/Cargo.toml --test on_prem_admin_ui -- --test-threads=1
uv run python scripts/qualification_dashboard_parity.py --screenshots
uv run python scripts/qualification_dashboard_parity.py --shutdown-restart
uv run python scripts/qualification_dashboard_parity.py --skip-build --on-prem
```
70 changes: 69 additions & 1 deletion architecture/deep-dive-database.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,72 @@ Commit/rollback ambiguity fails closed: body failure maps to `Transaction`/`Sqli

## Migrations

Migrations are embedded from `rust/assets/db/migrations/` (zero-padded `0001_*.sql`…`0054_*.sql` = versions 1–54) with `checksums.json` (`files` map, 54 entries): v1–v54, 54 files, validated by `MigrationRunner::validate_embedded_checksums` before any database use (`canonical_inventory_is_complete_and_immutable` guards first = 1, last = 54, len = 54). `MigrationRunner::run` keeps the `_migrations` ledger, rejects unknown versions and ledger-name mismatches, refuses read-only migration, and applies all pending migrations in one atomic transaction. History is never rewritten or renumbered; restore validation additionally checks the staged ledger against this inventory.
Migrations are embedded from `rust/assets/db/migrations/` (zero-padded `0001_*.sql`…`0062_*.sql` = versions 1–62) with `checksums.json` (`files` map, 62 entries), validated by `MigrationRunner::validate_embedded_checksums` before any database use. Migration 55 adds downstream identity and credential storage without repurposing upstream `accounts`; migration 56 adds browser sessions and CSRF digests; migration 57 adds user/auth-epoch attribution to request rows and selector-parent linkage; migration 58 adds local model-policy profiles, exact rules, per-user overrides, instance denials, and a monotonic policy revision; migration 59 adds user budget rules, request holds, attempt usage, audit, and bounded user/model/time rollups; migration 60 adds bounded secret-free administrative audit events; migration 61 adds the hard/estimated enforcement mode, worst-case hold facts, and price provenance to the budget tables; migration 62 adds the instance-global budget scope (rules, request holds, per-model usage buckets, audit, policy-revision triggers) with no user reference. Schema history is never rewritten or renumbered. `MigrationRunner::run` keeps the `_migrations` ledger, rejects unknown versions and ledger-name mismatches, refuses read-only migration, and applies all pending migrations in one atomic transaction. Restore validation additionally checks the staged ledger against this inventory.

`users`, `user_credentials`, and `user_access_state` hold usernames, password
hashes, downstream roles, token digests, scopes, and explicit transition state.
The initial admin and first personal token are committed atomically. Backups
therefore carry the identity records and non-recoverable credential digests;
plaintext passwords and API tokens are never stored.
On a brand-new schema, migration entrypoints record `fresh_uninitialized`;
onboarding can complete bootstrap after an interrupted setup, and a keyless
fresh listener refuses to start. Existing databases start in
`legacy_unmigrated` and retain their configured authentication until local
identity initialization. Migration 56 adds opaque `web_sessions` with
session-token and CSRF digests, expiry, idle-use, and revocation state; password
reset revokes sessions in the same transaction as the credential revocation.
Request rows keep a nullable historical `user_id` without a foreign key, so
disabling or removing a local user cannot erase request attribution. New
authenticated publications snapshot the user, credential/session ID, auth
epoch, and principal kind in the same publication transaction. Internal
semantic selector rows carry a parent proxy request ID and are excluded from
logical user history queries. `identity::recent_user_requests` uses the
`(user_id, started_at DESC, id DESC)` index, clamps reads to 500 rows, and
returns content-free request facts.

`model_policy` owns migration-58 profile and exact-model policy access. Policy
mutations advance the singleton revision in the same SQLite transaction;
database triggers also advance it when user state, role, or auth epoch changes.
The bounded process cache checks that revision before serving a new request,
then retains an immutable policy snapshot for the admitted request. Exact
instance denial has highest precedence, followed by user override, assigned
profile rule, and the role-safe default. Policy state remains separate from
provider topology and provider-account quota.

`user_budget` keeps downstream budget enforcement separate from upstream
`reservations`, `AccountQuota`, and provider scoring. Daily and monthly windows
use UTC calendar boundaries. Publication checks exact user/model and
user-aggregate rules and inserts an active hold in the same transaction as the
request/attempt/provider reservation; a concurrent last-slot request cannot
pass on a stale preflight. Retries extend that logical hold without
incrementing its request count. Rules carry an explicit `hard`/`estimated`
enforcement mode (migration 61; pre-existing rows are estimated, promotion is
an explicit admin operation): estimated holds keep the request-size token
projection and fallback microdollars, while hard holds reserve the admission
worst case (input bound plus caller output cap, cost converted at the
operator-configured `[providers.<id>.budget]` tariff) and record the bound
plus price provenance on the reservation row. Unbounded output, unknown tariff,
or arithmetic overflow denies with `BudgetNotEnforceable` before any upstream
submission. Attempt facts are idempotently retained, and
terminal finalization settles one daily and one monthly usage bucket in the
same transaction that terminalizes the request. Unknown usage consumes the
remaining estimate and increments explicit unknown counters; provider-reported
usage above a hard hold is settled visibly, never clamped. Instance-global
ceilings (`instance_budget`) reuse the same hold formulas and the M008 tariff
trust boundary in the same publication transaction: global rules aggregate
across per-model usage rows with bounded indexed sums (no full history scan
under the gate), retries extend without consuming a second request, and
settlement folds the shared attempt rows. Instance rows carry no user
reference, so user disable/delete preserves history; with no matching
instance rule, publication takes no instance hold and writes no instance rows.
Provider-reported,
locally estimated, and reservation-fallback microdollars remain distinct in the
user rollup. Rule changes retain an actor/version/mode audit row. `GET
/api/user-budget` returns only the authenticated user's data unless an active
admin asks for a target `user_id`; each rule reports its enforcement mode.
Migration 60 adds `user_admin_audit`, a
bounded, secret-free actor/action/target record written transactionally with
user, token, and profile administration mutations.

## Publication and finalization transactions

Expand Down Expand Up @@ -67,6 +132,9 @@ Persistence M004 (`plans/closure/persistence/004-status.md`) collected 14 accept
- Migrations immutable and checksum-pinned; unknown or mismatched ledgers fail closed.
- `backup_to` is a primitive; orchestration, validation, and restore stay in `operations/backup.rs`.
- Startup reconciliation repairs only covered states; ambiguity never resolves silently.
Covered budget states: active user/instance holds on interrupted requests
are released without folding usage; settled holds, usage buckets, and
attempt-usage facts are never mutated by reconciliation.

## Verification

Expand Down
20 changes: 20 additions & 0 deletions architecture/deep-dive-integrations.md
Original file line number Diff line number Diff line change
Expand Up @@ -229,6 +229,14 @@ must-revalidate`, `ETag: "<revision>"` with `If-None-Match` → `304`.
Errors are bounded and generic (`401`/`403` auth, `503` unavailable with no
internal body).

For a personal user principal, model rows and virtual aliases are filtered by
the same effective model policy used at inference admission. The portable body
revision remains its sanitized content hash; the HTTP ETag adds the persisted
policy revision (`<content-revision>-p<policy-revision>`) so edits that do not
change the visible projection still invalidate desktop caches. Restricted
users with no assigned profile default-deny unknown models; administrators
without an explicit profile retain the historical unrestricted default.

## OpenCode provider contracts

Both variants render from the same conservative projection and never claim
Expand Down Expand Up @@ -344,3 +352,15 @@ duplicates renderers:
proxy/agent/daemon, or
dashboard assets, so publishing a Windows helper never implies Windows
proxy support.

## Personal client credentials

After local identity initialization, a user can issue a personal agent token
from `/my-account` or an active administrator can issue one for a selected
member. The one-time `epk1` plaintext is returned in a no-store browser
response; the account page displays only bounded credential metadata and
revocation controls. Desktop clients continue to read the user's token from
`EGGPOOL_API_KEY`; `configremote`, Codex, OpenCode, and `eggpool-connect` do
not embed a global administrator key. Agent tokens remain scoped to inference,
model discovery, the versioned integration profile, and the user's budget
view. They do not authorize dashboard or administration routes.
6 changes: 6 additions & 0 deletions architecture/deep-dive-observability.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,12 @@ correctness-critical request/accounting lifecycle rows stay durable.
Shutdown performs one deadline-bounded metrics flush before the database
closes.

Downstream user ownership lives on durable request rows, separate from the
provider/account-keyed `usage_rollups` dimensions. User history is queried by
owner through a bounded indexed repository and excludes internal selector
children from logical-request views. Routine metrics, routing traces, and
diagnostics still omit user IDs, credential IDs, scopes, prompts, and tokens.

## Verification

```bash
Expand Down
Loading
Loading