server: real AuthProvider — persisted per-workspace tokens, create/revoke, bearer auth across the whole API

[JArmandoAnaya]

Context

Replace the hardcoded dev token with the real (deliberately simple) OSS auth: static
per-workspace tokens via the AuthProvider port. A valid token operates the workspace;
granular permissions are enterprise territory.

Deliverables

• Token entity: name, created_at, hashed secret (store a hash, show the secret once at
  creation), revoked flag.
• AuthProvider default adapter backed by the metadata store; validation on every request
  via FastAPI dependency; 401 with a stable error body when missing/invalid/revoked.
• /health stays unauthenticated.

Acceptance criteria

• Secrets stored hashed; creation returns plaintext exactly once
• Revoked token ⇒ 401 immediately
• Every endpoint except /health rejects unauthenticated requests (walked via the
  OpenAPI route table in a test)

[JArmandoAnaya]

Done — PR #97, squash-merged as e2277f9, branched from 4217ce1. M3 is 3/14.

Migration ledger: FORMAT_VERSION 10 → 11. M3's only migration, as planned. VERSION stayed 0.0.1.dev0, no dependency change, no import-linter change, no new domain event. 1016 tests, up from 919.

What landed

EnvTokenAuthProvider is gone. The port did not widen — verify(token) -> bool stays the narrow seam all three surfaces authenticate through, and minting/revoking are TokenService.

Piece	Where
Token, IssuedToken, generate_secret, hash_secret	kernel/domain/token.py
TokenService — create / get / get_by_name / revoke(confirm=) / list	kernel/services/token_service.py
StoredTokenAuthProvider	kernel/adapters/, the sixth port on WorkspaceService
get_workspace / get_auth_provider / require_token / protected_router()	server/dependencies.py

Acceptance criteria: secrets stored hashed and the plaintext returned exactly once (IssuedToken.secret carries repr=False, so a traceback cannot spill it); a revoked token is 401 immediately, asserted against a live application with no restart and nothing to invalidate; and the OpenAPI route walk is in place as a tripwire.

The three things a later session should not re-derive

openapi.json did not move, and the epic's prediction was wrong about which task moves it first. FastAPI collects security definitions per route, from the route's dependency tree — a module-level HTTPBearer emits nothing while zero routes are protected. components.securitySchemes enters with #27's first endpoint. The scheme's description is set now anyway and a test pins its exact shape, so #27 inherits the diff rather than making the decision.

The acceptance walk is vacuous today, deliberately. /health is the only operation, so it takes the public branch once. What makes it worth committing is the four tests beside it that prove the walk can fail — a route that forgot the token, a guarded route that did not document its 401, a public route that should not be, and a path item carrying a non-operation key.

A misconfigured server answers 500 NOT_A_WORKSPACE, not 401, even with no token, because get_auth_provider depends on get_workspace and FastAPI resolves sub-dependencies before the body. Short-circuiting would mean resolving the provider outside the dependency graph — which takes dependency_overrides with it, and making that work is half of what this issue was for.

Migration 11's trap

First migration since 1 to create a table, so idempotency is Table.create(checkfirst=True) — which brings both indexes with it and side-steps migration 8's expression-index trap entirely.

The part worth writing down: without the drop table token line in _downgrade_to_version_one, test_a_fresh_database_and_a_migrated_one_have_the_same_schema would still pass. The table would survive the downgrade and migration 11 would checkfirst-skip, so a CREATE nobody ran would be reported as agreeing with itself. That undo is not what keeps an existing test honest — it is the only thing that exercises the migration at all. The inverse of migration 9's trap.

Also worth knowing: SqlRepository.list(None) on a non-root entity does not raise — the ValueError fires only for a root entity — it silently returns every row in the table. So StoredTokenAuthProvider takes the workspace id explicitly; list() would be accidentally correct today and a cross-workspace credential leak the day one store holds two.

Decisions recorded so they are not re-litigated

• SHA-256 rather than a KDF, argued in docs/auth.md: a KDF exists for low-entropy human-chosen input, the secret is 256 bits of secrets.token_urlsafe, and verification runs per request against N tokens where a login form's runs once.
• revoked_at, not a bool — revoked is derived, the doctrine that keeps a schema's active version computed.
• One identical 401 for missing / malformed / unknown / revoked, so the response cannot be used to probe which credentials exist.
• Nothing is cached, and a store failure raises rather than answering False: an outage is not a bad credential.
• No TokenCreated/TokenRevoked event. An auth trail a subscriber can silently drop is worse than none; the row is the log and its columns are durable.
• No delete and no rename, and revocation does not free the name.
• Zero MCP tools for token administration (the parity-rule record, in docs/auth.md so mcp: real tools over the SDK — management, schema, ingest, jobs, annotation, releases (the Part III §4 list), confirm:true on destructive ops #35 does not re-open it): minting a credential is a privilege-escalation primitive pointed at the agent's own sandbox, and an agent's "shown once" is a transcript.

Handed to #26

server/dependencies.py::resolve_workspace_root is provisional and says so in its docstring. It already reads VISIONSET_WORKSPACE — the name #26 keeps — so #26 replaces the body and nothing importing it changes. Deliberately missing: the --workspace flag (a server started by import string has no argv) and the upward walk for a visionset.db in a parent.

One constraint #26 should not discover late: import-linter forbids visionset.server importing visionset.cli, so the promoted resolver cannot live in the CLI. It belongs beside DB_FILENAME in kernel/services/workspace_service.py, which already owns the rule that the database file is what marks a directory as a workspace.

Token names are unique per workspace (uq_token_workspace_name, COLLATE NOCASE) so token revoke <name> resolves to one credential — which is what keeps #26 from needing a second M3 migration. require_token_named(uow, name) is public for a caller resolving inside its own transaction. And visionset token create now exits non-zero instead of printing a vst_… that could never authenticate.

Next: #26 — visionset token create/list/revoke with persistence, and the workspace-resolution precedence that #33 and #34 both reuse.