Add governance and identity registry scaffolding
This commit is contained in:
Conrad Kramer
parent
1da00ecdf3
commit
f6a7f0922d
13 changed files with 612 additions and 21 deletions
|
|
@ -58,3 +58,17 @@ evolution/
|
|||
```
|
||||
|
||||
Use ASCII Markdown. Keep metadata at the top of each proposal so tooling and future agents can parse it quickly.
|
||||
|
||||
## BEP Helper
|
||||
|
||||
Use the `bep` helper under `Scripts/` to browse or list proposals:
|
||||
|
||||
- `Scripts/bep` opens a quick browser for `evolution/`.
|
||||
- `Scripts/bep list --status Draft` lists proposals by status.
|
||||
- `Scripts/bep open BEP-0005` opens a proposal in `$EDITOR`.
|
||||
|
||||
Validate proposal metadata with:
|
||||
|
||||
```bash
|
||||
python3 Scripts/check-bep-metadata.py
|
||||
```
|
||||
|
|
|
|||
|
|
@ -0,0 +1,78 @@
|
|||
# `BEP-0005` - Daemon IPC and Apple Boundary
|
||||
|
||||
```text
|
||||
Status: Draft
|
||||
Proposal: BEP-0005
|
||||
Authors: gpt-5.4
|
||||
Coordinator: gpt-5.4
|
||||
Reviewers: Pending
|
||||
Constitution Sections: II, III, IV, V
|
||||
Implementation PRs: Pending
|
||||
Decision Date: Pending
|
||||
```
|
||||
|
||||
## Summary
|
||||
|
||||
Burrow should formalize one Apple/runtime boundary: Apple clients speak only to the daemon over gRPC on the app-group Unix socket, and the daemon owns all external control-plane, helper-process, and runtime coordination work. This prevents UI code from accreting side HTTP paths or ad hoc control-plane integrations that bypass the system Burrow is supposed to own.
|
||||
|
||||
## Motivation
|
||||
|
||||
- The current Tailnet work already showed the failure mode: Swift UI code started reaching around the daemon boundary to talk to helper HTTP endpoints directly.
|
||||
- Apple-specific process ownership is easy to blur between the app, the network extension, and helper daemons unless the contract is explicit.
|
||||
- If Burrow wants a durable multi-runtime architecture, the daemon must remain the only orchestration boundary between clients and control/data-plane behavior.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
- Apple UI and Apple support libraries may call only daemon gRPC methods over the declared Burrow Unix socket.
|
||||
- Direct Swift calls to external control-plane HTTP APIs, localhost helper HTTP servers, or runtime-specific subprocesses are forbidden.
|
||||
- The daemon is responsible for:
|
||||
- discovery of Tailnet authorities and related metadata
|
||||
- control-plane session setup and tracking
|
||||
- login/session lifecycle brokering
|
||||
- runtime start/stop/reconcile
|
||||
- translating helper or bridge processes into stable daemon RPCs
|
||||
- `burrow/src/control/` owns transport-neutral control-plane semantics such as discovery, authority normalization, and request/response shaping.
|
||||
- Apple UI owns presentation only:
|
||||
- forms
|
||||
- local state
|
||||
- presenting returned auth URLs or statuses
|
||||
- surfacing daemon availability and errors
|
||||
- Any new Apple-facing runtime capability requires a daemon RPC first.
|
||||
|
||||
## Security and Operational Considerations
|
||||
|
||||
- Keeping control-plane I/O out of Swift UI reduces accidental secret, token, and callback sprawl across app code.
|
||||
- The daemon boundary makes testing and kill-switch behavior tractable because runtime integration is localized.
|
||||
- Apple daemon lifecycle ownership must be explicit: either the app ensures the daemon is running before RPC or the extension owns it and the UI surfaces daemon-unavailable state clearly.
|
||||
|
||||
## Contributor Playbook
|
||||
|
||||
- Before adding a new Apple-side workflow, identify the daemon RPC that should own it.
|
||||
- If the RPC does not exist, add the protocol shape in `proto/burrow.proto`, implement it in the daemon, and only then wire Swift UI.
|
||||
- Verify that no Swift UI or support code calls external control-plane HTTP endpoints directly.
|
||||
- For Tailnet and similar flows, test:
|
||||
- daemon unavailable behavior
|
||||
- successful RPC path
|
||||
- error propagation through the UI
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- Let Apple UI call control-plane endpoints directly for convenience. Rejected because it creates parallel orchestration paths and breaks the daemon contract.
|
||||
- Allow one-off exceptions for login helpers. Rejected because those exceptions become the architecture.
|
||||
|
||||
## Impact on Other Work
|
||||
|
||||
- Governs the Tailnet refactor and future Apple runtime work.
|
||||
- Interacts with BEP-0002 control-plane bootstrap and BEP-0003 transport refactoring.
|
||||
|
||||
## Decision
|
||||
|
||||
Pending.
|
||||
|
||||
## References
|
||||
|
||||
- `Apple/UI/`
|
||||
- `Apple/Core/`
|
||||
- `Apple/NetworkExtension/`
|
||||
- `burrow/src/daemon/`
|
||||
- `burrow/src/control/`
|
||||
|
|
@ -0,0 +1,71 @@
|
|||
# `BEP-0006` - Tailnet Authority-First Control Plane
|
||||
|
||||
```text
|
||||
Status: Draft
|
||||
Proposal: BEP-0006
|
||||
Authors: gpt-5.4
|
||||
Coordinator: gpt-5.4
|
||||
Reviewers: Pending
|
||||
Constitution Sections: I, II, IV, V
|
||||
Implementation PRs: Pending
|
||||
Decision Date: Pending
|
||||
```
|
||||
|
||||
## Summary
|
||||
|
||||
Burrow should treat Tailnet as one protocol family. Tailscale-managed and self-hosted Headscale-style deployments differ by authority, policy, and auth details, not by a distinct user-facing protocol. Burrow’s config and UI should therefore be authority-first rather than provider-first.
|
||||
|
||||
## Motivation
|
||||
|
||||
- Splitting Tailscale and Headscale into separate user-facing providers causes fake architectural divergence.
|
||||
- Discovery already naturally returns an authority and optional issuer; that is the stable contract users actually need.
|
||||
- Future managed or enterprise deployments should fit the same model without requiring another protocol picker.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
- Tailnet configuration is centered on:
|
||||
- account
|
||||
- identity
|
||||
- authority/login server URL
|
||||
- optional tailnet name
|
||||
- optional hostname
|
||||
- auth method/material
|
||||
- User-facing surfaces should not force a protocol choice between Tailscale and Headscale.
|
||||
- Provider inference may remain internal metadata for compatibility and diagnostics:
|
||||
- default managed Tailscale authority
|
||||
- custom self-hosted authority
|
||||
- Burrow-owned authority when explicitly applicable
|
||||
- Discovery returns authority and related metadata; editing the authority is the mechanism that moves a configuration from managed default to custom control server.
|
||||
- The daemon and control layer own provider inference; the UI should primarily present “Tailnet” plus the selected authority.
|
||||
|
||||
## Security and Operational Considerations
|
||||
|
||||
- Authority-first config reduces UI complexity and makes misconfiguration easier to reason about.
|
||||
- Provider-specific assumptions must not leak into packet or control-plane semantics unless the authority actually requires them.
|
||||
- Auth material must remain authority-scoped and identity-scoped in daemon storage.
|
||||
|
||||
## Contributor Playbook
|
||||
|
||||
- Remove provider pickers from Tailnet UI unless a concrete protocol difference requires one.
|
||||
- Store the authority explicitly in payloads and infer provider internally only when needed.
|
||||
- Prefer tests that validate authority normalization and discovery behavior over UI-provider branching.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- Keep separate user-facing providers for Tailscale and Headscale. Rejected because it models deployment shape as protocol shape.
|
||||
- Collapse all control planes into one opaque Burrow provider. Rejected because the authority still matters operationally and diagnostically.
|
||||
|
||||
## Impact on Other Work
|
||||
|
||||
- Refines BEP-0002’s Tailscale-shaped control-plane work.
|
||||
- Constrains the Tailnet Apple refactor and future daemon control-plane storage.
|
||||
|
||||
## Decision
|
||||
|
||||
Pending.
|
||||
|
||||
## References
|
||||
|
||||
- `burrow/src/control/`
|
||||
- `Apple/UI/Networks/`
|
||||
- `proto/burrow.proto`
|
||||
|
|
@ -0,0 +1,73 @@
|
|||
# `BEP-0007` - Identity Registry and Operator Bootstrap
|
||||
|
||||
```text
|
||||
Status: Draft
|
||||
Proposal: BEP-0007
|
||||
Authors: gpt-5.4
|
||||
Coordinator: gpt-5.4
|
||||
Reviewers: Pending
|
||||
Constitution Sections: II, III, IV, V
|
||||
Implementation PRs: Pending
|
||||
Decision Date: Pending
|
||||
```
|
||||
|
||||
## Summary
|
||||
|
||||
Burrow should maintain one canonical registry for project identities, aliases, bootstrap users, SSH keys, and admin-group mappings. Forgejo, Authentik, and related bootstrap configuration should derive from that registry instead of hardcoding overlapping identity facts in multiple modules.
|
||||
|
||||
## Motivation
|
||||
|
||||
- Burrow currently hardcodes operator and admin/bootstrap user facts directly in host configuration.
|
||||
- Multi-account and self-hosted identity are becoming core architecture, not incidental infra details.
|
||||
- A single registry reduces drift across Forgejo, Authentik, Headscale, SSH authorization, and future control-plane bootstrap.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
- Add a root-level identity registry (`contributors.nix`) as the canonical source of truth for:
|
||||
- usernames
|
||||
- display names
|
||||
- canonical emails
|
||||
- external source emails or aliases
|
||||
- admin scope
|
||||
- bootstrap eligibility
|
||||
- forge authorized SSH keys
|
||||
- named roles
|
||||
- Consume that registry from host configuration for:
|
||||
- Forgejo authorized keys
|
||||
- Forgejo bootstrap admin defaults
|
||||
- Authentik bootstrap users
|
||||
- Burrow user/admin group names
|
||||
- Future work may derive contributor docs, OIDC bootstrap, and additional runtime configuration from the same registry.
|
||||
|
||||
## Security and Operational Considerations
|
||||
|
||||
- Identity drift is a security bug when it affects admin groups, bootstrap accounts, or SSH authorization.
|
||||
- The registry stores metadata only; secrets remain in agenix or other declared secret paths.
|
||||
- Changes to the registry should receive explicit review because they affect access and governance.
|
||||
|
||||
## Contributor Playbook
|
||||
|
||||
- Edit `contributors.nix` first when changing operator, admin, alias, or bootstrap identity state.
|
||||
- Derive runtime configuration from the registry instead of duplicating the same facts elsewhere.
|
||||
- Keep secret references separate from identity metadata.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- Continue hardcoding users in module options. Rejected because drift is inevitable once Forgejo, Authentik, and Headscale all depend on the same identities.
|
||||
- Create separate per-service user lists. Rejected because it duplicates governance facts and weakens review.
|
||||
|
||||
## Impact on Other Work
|
||||
|
||||
- Supports forge auth, Authentik group sync, and future multi-account Burrow control-plane work.
|
||||
- Creates the basis for stronger contributor and operator provenance later.
|
||||
|
||||
## Decision
|
||||
|
||||
Pending.
|
||||
|
||||
## References
|
||||
|
||||
- `contributors.nix`
|
||||
- `nixos/hosts/burrow-forge/default.nix`
|
||||
- `nixos/modules/burrow-authentik.nix`
|
||||
- `nixos/modules/burrow-forge.nix`
|
||||
Loading…
Add table
Add a link
Reference in a new issue