chore: consolidate new foundation and archive v1 (#1495)
This commit is contained in:
@@ -0,0 +1,133 @@
|
||||
# Seat Identity & Credentials Guide
|
||||
|
||||
Every agent that touches a Mosaic-managed git host acts as a named seat with its own credential.
|
||||
This guide is how that works on a host, and what an agent must never do with it.
|
||||
|
||||
The mechanism below is the framework's. The specific paths, seats and stores are per-host:
|
||||
measure yours before trusting any of them.
|
||||
|
||||
## The rule
|
||||
|
||||
**One seat, one identity, one token file.** A seat never borrows another seat's credential, never
|
||||
falls back to a shared owner account, and never carries a second copy of its own token. A second
|
||||
copy is drift, and drift surfaces as the stale copy returning 401 — which reads as a revoked
|
||||
token and sends whoever debugs it somewhere else entirely.
|
||||
|
||||
A credential refusal is correct behavior, not a bug to route around. If git refuses with a
|
||||
fail-closed diagnostic, the fix is to provision or correct _your_ identity. Escalate; do not
|
||||
substitute.
|
||||
|
||||
## How a credential is resolved
|
||||
|
||||
Find the helper the way **git** does, not with `command -v`. Git runs whatever
|
||||
`credential.helper` names, and on a Mosaic host that is an absolute path — so a PATH lookup
|
||||
answers a different question and the two disagree the moment the PATH copy is removed. It was
|
||||
removed on hosts that have completed that migration.
|
||||
|
||||
```bash
|
||||
git config --get-all credential.helper # every helper, in the order git tries them
|
||||
```
|
||||
|
||||
Git tries **each** configured helper in turn until one supplies a credential. A fail-closed
|
||||
helper supplies nothing, so a second helper configured behind it silently becomes the one that
|
||||
answers. When you care which binary serves a credential, read the whole list.
|
||||
Resolve all three forms git accepts — absolute path, `!command`, and a bare name looked up on
|
||||
PATH — not just the one your host happens to use.
|
||||
|
||||
The helper resolves the identity in this order:
|
||||
|
||||
1. `$MOSAIC_GIT_IDENTITY`
|
||||
2. `git config --get mosaic.gitIdentity`
|
||||
3. the username git supplied on stdin
|
||||
|
||||
It maps the host to a store prefix — `git.mosaicstack.dev` to `gitea-mosaicstack`,
|
||||
`git.uscllc.com` to `gitea-usc`. Any other host is declined quietly with rc=0, which is not an
|
||||
error and raises no escalation.
|
||||
|
||||
Then it chooses **one** of two stores, and reads exactly one file:
|
||||
|
||||
```
|
||||
brain_home = ${MOSAIC_BRAIN_HOME:-$HOME/.mosaic}
|
||||
|
||||
seat — when $brain_home/fleet/agents/<identity>/ EXISTS
|
||||
$brain_home/fleet/agents/<identity>/secrets/<prefix>-<identity>.token
|
||||
service — otherwise
|
||||
~/.config/mosaic/secrets/gitea-tokens/<prefix>-<identity>.token
|
||||
```
|
||||
|
||||
**There is no precedence between the two and no fallback from one to the other.** The existence
|
||||
of the seat directory decides it. A seat that has a directory and an empty slot fails closed; it
|
||||
does not reach the service store. That is the intended behavior — the alternative is an agent
|
||||
silently acting as somebody else.
|
||||
|
||||
If the file is unreadable the helper **fails closed**: it refuses and writes a durable record to
|
||||
the escalation spool. It does not fall back to a shared account. The record is what exists — any
|
||||
alerting built on top of it is a separate, best-effort concern and is not performed by the helper,
|
||||
so do not wait for a notification that nothing sends. That fallback is what made
|
||||
`usc/uconnect#3084` unattributable, and it was removed deliberately.
|
||||
|
||||
Verify the helper you actually have:
|
||||
|
||||
```bash
|
||||
h=$(git config --get credential.helper)
|
||||
grep -c 'FAIL CLOSED' "$h" # expect >= 1
|
||||
grep -c 'fleet/agents' "$h" # expect >= 1; 0 means it predates mosaicstack#1311
|
||||
```
|
||||
|
||||
## Where a seat's token lives
|
||||
|
||||
The seat slot is the **only** copy:
|
||||
|
||||
```
|
||||
~/.mosaic/fleet/agents/<seat>/secrets/<prefix>-<seat>.token real file, mode 600
|
||||
```
|
||||
|
||||
The framework store at `~/.config/mosaic/secrets/gitea-tokens/` holds tokens for **service
|
||||
identities only** — identities with no seat directory. A seat's token does not belong there.
|
||||
|
||||
Before mosaicstack#1311 the deployed helper knew only the service store, and seats were bridged
|
||||
with a symlink from the store into the slot. **Those bridges must be removed once a seat-aware helper is deployed, and must not be
|
||||
recreated.** Remove them only after the helper can reach the slot without them; the reverse order
|
||||
takes every seat offline. A symlink
|
||||
is not how a system finds a credential; the helper resolving the right store is.
|
||||
|
||||
`.principal` and `.scopes` beside the token are grant records, not secrets. They are tracked. The
|
||||
`.token` never is.
|
||||
|
||||
### Provisioning a new seat
|
||||
|
||||
1. Create `~/.mosaic/fleet/agents/<seat>/secrets/` mode 700.
|
||||
2. Write `.principal` (the Gitea login) and `.scopes` (the granted scopes), mode 600.
|
||||
3. The estate operator mints the token into the seat slot, mode 600. Agents do not mint their
|
||||
own, and do not ask another agent to mint one for them.
|
||||
4. Verify with an authenticated `GET /user` and confirm the returned login is the seat, **not the
|
||||
minting account**. Record the date in `ENTITY.md`. Never record the value.
|
||||
|
||||
There is no step that links the framework store to the slot. A seat-aware helper reads the slot
|
||||
directly; a store entry pointing at a slot is the bridge described in **Where a seat's token lives** above,
|
||||
and it is not part of provisioning.
|
||||
|
||||
Until step 3, the seat is unminted and its git writes fail closed. That is the designed state and
|
||||
is safe to launch in — the seat is told at launch so it does not discover it mid-task.
|
||||
|
||||
## Acting as yourself
|
||||
|
||||
Name the identity on every invocation:
|
||||
|
||||
```bash
|
||||
MOSAIC_GIT_IDENTITY=<seat> git push
|
||||
git -c user.name=<seat> -c user.email=<seat>@mosaicstack.dev commit -m "..."
|
||||
```
|
||||
|
||||
**Never persist `git config mosaic.gitIdentity` inside a `~/src/stack` worktree.** Every worktree
|
||||
of that clone shares one `.git/config`, so a persisted identity there silently rewrites the
|
||||
identity of every other seat working in that clone. The per-invocation form has no exception.
|
||||
|
||||
## Handling
|
||||
|
||||
1. **Never print a token value.** Compare by SHA-256 digest, or write `<REDACTED>`.
|
||||
2. **Never stage a `.token`, `secrets.json`, or `ENTITY.md`.** Stage explicit paths and **never
|
||||
`git add -A`** — `secrets/*.principal` and `secrets/*.scopes` are covered by no ignore rule.
|
||||
3. **Never place a token in an environment variable** in an interactive session. A `declare -x`
|
||||
dump has leaked the whole environment to a terminal before.
|
||||
4. **No real credential or operator data on a sandbox VM, ever.**
|
||||
Reference in New Issue
Block a user