Files

William Gill 12bf35caf8 anchorage v1.0 initial tree

Greenfield Go multi-tenant IPFS Pinning Service wire-compatible with the
IPFS Pinning Services API spec. Paired 1:1 with Kubo over localhost RPC,
clustered via embedded NATS JetStream, Postgres source-of-truth with
RLS-enforced tenancy, Fiber + huma v2 for the HTTP surface, Authentik
OIDC for session login with kid-rotated HS256 JWT API tokens.

Feature-complete against the 22-milestone build plan, including the
ship-it v1.0 gap items:

  * admin CLIs: drain/uncordon, maintenance, mint-token, rotate-key,
    prune-denylist, rebalance --dry-run, cache-stats, cluster-presences
  * TTL leader election via NATS KV, fence tokens, JetStream dedup
  * rebalancer (plan/apply split), reconciler, requeue sweeper
  * ristretto caches with NATS-backed cross-node invalidation
    (placements live-nodes + token denylist)
  * maintenance watchdog for stuck cluster-pause flag
  * Prometheus /metrics with CIDR ACL, HTTP/pin/scheduler/cache gauges
  * rate limiting: session (10/min) + anonymous global (120/min)
  * integration tests: rebalance, refcount multi-org, RLS belt
  * goreleaser (tar + deb/rpm/apk + Alpine Docker) targeting Gitea

Stack: Cobra/Viper, Fiber v2 + huma v2, embedded NATS JetStream,
pgx/sqlc/golang-migrate, ristretto, TypeID, prometheus/client_golang,
testcontainers-go.

2026-04-16 18:13:36 -05:00

1.7 KiB

Raw Permalink Blame History

Authentication

Setting up Authentik? See authentik-setup.md for the step-by-step provider + application + property-mapping walkthrough and the matching anchorage.yaml snippet.

Actors

Browser users — authenticate once via Authentik (OIDC, Authorization Code + PKCE). anchorage validates Authentik's ID token against its JWKS, upserts the user, issues a short-lived session cookie.
Programmatic clients (kubo's ipfs pin remote, CI pipelines, scripts) — present Authorization: Bearer <jwt> where the JWT was minted by anchorage itself.

Token lifecycle

Signed-in user calls POST /v1/tokens with a label + scopes.
anchorage signs a JWT: {sub, org, role, scopes, jti, iat, exp}. The jti is a TypeID (tok_...). Only the metadata (label, scopes, expires_at) is persisted; the signed string is returned to the user once.
Client presents the JWT. Middleware validates signature + expiry + denylist (token_denylist keyed by jti).
Revocation writes the jti to token_denylist with its natural expiry; the row is pruned hourly.

Why JWT + denylist rather than opaque DB tokens

Denylist is only consulted for revoked tokens — a warm token/deny ristretto cache means the hot path is zero DB reads.
Claims travel with the request — RLS can set anchorage.org_id per-transaction from the JWT without another lookup.
Short TTLs (default 24h) plus revocation cover the usual "compromised token" threat model without requiring per-request DB hits.

Sysadmin bootstrap

bootstrap.sysadmins: [admin@example.com, ...] in config. First Authentik login for any listed email promotes the user to is_sysadmin=true. The config is only consulted on first login; later changes need the admin CLI.

1.7 KiB Raw Permalink Blame History