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.
This commit is contained in:
commit
12bf35caf8
112 files changed
+16884
No files matched your search
@@ -0,0 +1,265 @@
|
||||
package cmd
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"io"
|
||||
"net/http"
|
||||
"net/url"
|
||||
"os"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
)
|
||||
|
||||
// newAdminCmd groups operational commands (drain, maintenance, ...).
|
||||
//
|
||||
// Every subcommand is a thin HTTP client against the running
|
||||
// anchorage's /v1/admin/* endpoints. The CLI never opens its own NATS
|
||||
// server or database handle — that keeps the "two anchorages with one
|
||||
// DataDir" footgun from being easy to trip over.
|
||||
func newAdminCmd(flags *globalFlags) *cobra.Command {
|
||||
admin := &cobra.Command{
|
||||
Use: "admin",
|
||||
Short: "Operational commands (drain, maintenance mode, ...)",
|
||||
}
|
||||
admin.PersistentFlags().StringVar(&flags.adminURL, "server", defaultAdminURL(), "base URL of a running anchorage instance (env: ANCHORAGE_ADMIN_URL)")
|
||||
admin.PersistentFlags().StringVar(&flags.adminToken, "token", os.Getenv("ANCHORAGE_ADMIN_TOKEN"), "sysadmin API token (env: ANCHORAGE_ADMIN_TOKEN)")
|
||||
|
||||
admin.AddCommand(newDrainCmd(flags))
|
||||
admin.AddCommand(newUncordonCmd(flags))
|
||||
admin.AddCommand(newMaintenanceCmd(flags))
|
||||
admin.AddCommand(newMintTokenCmd(flags))
|
||||
admin.AddCommand(newGrantSysadminCmd(flags))
|
||||
admin.AddCommand(newRotateKeyCmd(flags))
|
||||
admin.AddCommand(newPruneDenylistCmd(flags))
|
||||
admin.AddCommand(newRebalanceCmd(flags))
|
||||
admin.AddCommand(newCacheStatsCmd(flags))
|
||||
admin.AddCommand(newClusterPresencesCmd(flags))
|
||||
return admin
|
||||
}
|
||||
|
||||
func newClusterPresencesCmd(flags *globalFlags) *cobra.Command {
|
||||
return &cobra.Command{
|
||||
Use: "cluster-presences",
|
||||
Short: "Real-time NATS heartbeat view from the server you're pointed at",
|
||||
Long: `Returns the in-memory heartbeat map maintained by the anchorage
|
||||
instance answering the request. Each entry is a peer's most recent
|
||||
node.heartbeat.<id> broadcast plus its age in seconds.
|
||||
|
||||
Distinct from the DB 'nodes' table: this is the real-time NATS view,
|
||||
updated every heartbeat interval, while the DB status is only flipped
|
||||
to 'down' by the leader's stale sweeper every downAfter seconds.
|
||||
Operators diagnosing "the DB says X is up but nobody's heard from it"
|
||||
should compare the two.`,
|
||||
Args: cobra.NoArgs,
|
||||
RunE: func(cmd *cobra.Command, _ []string) error {
|
||||
return adminGET(cmd.OutOrStdout(), flags, "/v1/admin/cluster/presences")
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
func newPruneDenylistCmd(flags *globalFlags) *cobra.Command {
|
||||
return &cobra.Command{
|
||||
Use: "prune-denylist",
|
||||
Short: "Delete denylist rows whose expires_at has passed",
|
||||
Args: cobra.NoArgs,
|
||||
RunE: func(cmd *cobra.Command, _ []string) error {
|
||||
return adminPOST(cmd.OutOrStdout(), flags, "/v1/admin/tokens/prune-denylist", nil)
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
func newRebalanceCmd(flags *globalFlags) *cobra.Command {
|
||||
var apply bool
|
||||
c := &cobra.Command{
|
||||
Use: "rebalance",
|
||||
Short: "Preview (default) or execute (--apply) a one-shot rebalance pass",
|
||||
Long: `Walks the current placements table and reports what the rebalancer
|
||||
would move to restore replica counts on nodes that transitioned to
|
||||
down / drained. Useful for catch-up after a cluster-maintenance window.
|
||||
|
||||
Default is a dry-run: no placements are moved. Pass --apply to execute.
|
||||
The scheduled leader loop keeps running regardless.`,
|
||||
Args: cobra.NoArgs,
|
||||
RunE: func(cmd *cobra.Command, _ []string) error {
|
||||
body := map[string]any{"apply": apply}
|
||||
return adminPOST(cmd.OutOrStdout(), flags, "/v1/admin/rebalance", body)
|
||||
},
|
||||
}
|
||||
c.Flags().BoolVar(&apply, "apply", false, "execute the moves (default is a dry-run preview)")
|
||||
return c
|
||||
}
|
||||
|
||||
func newCacheStatsCmd(flags *globalFlags) *cobra.Command {
|
||||
return &cobra.Command{
|
||||
Use: "cache-stats",
|
||||
Short: "Report per-cache hits / misses / evictions",
|
||||
Args: cobra.NoArgs,
|
||||
RunE: func(cmd *cobra.Command, _ []string) error {
|
||||
return adminGET(cmd.OutOrStdout(), flags, "/v1/admin/cache-stats")
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
func newGrantSysadminCmd(flags *globalFlags) *cobra.Command {
|
||||
return &cobra.Command{
|
||||
Use: "grant-sysadmin <email>",
|
||||
Short: "Promote a previously-logged-in user to sysadmin",
|
||||
Long: `Promotes an existing anchorage user (identified by the email Authentik
|
||||
puts in the id_token) to sysadmin. The user must have completed at
|
||||
least one OIDC login before this command can find them; it is not the
|
||||
first-boot bootstrap path (that's bootstrap.sysadmins in config).`,
|
||||
Args: cobra.ExactArgs(1),
|
||||
RunE: func(cmd *cobra.Command, args []string) error {
|
||||
path := "/v1/admin/users/" + url.PathEscape(args[0]) + "/grant-sysadmin"
|
||||
return adminPOST(cmd.OutOrStdout(), flags, path, nil)
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
func defaultAdminURL() string {
|
||||
if u := os.Getenv("ANCHORAGE_ADMIN_URL"); u != "" {
|
||||
return u
|
||||
}
|
||||
return "http://localhost:8080"
|
||||
}
|
||||
|
||||
func newDrainCmd(flags *globalFlags) *cobra.Command {
|
||||
return &cobra.Command{
|
||||
Use: "drain <nodeID>",
|
||||
Short: "Mark a node drained (removes it from placement, keeps heartbeats)",
|
||||
Args: cobra.ExactArgs(1),
|
||||
RunE: func(cmd *cobra.Command, args []string) error {
|
||||
return adminPOST(cmd.OutOrStdout(), flags, "/v1/admin/nodes/"+args[0]+"/drain", nil)
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
func newUncordonCmd(flags *globalFlags) *cobra.Command {
|
||||
return &cobra.Command{
|
||||
Use: "uncordon <nodeID>",
|
||||
Short: "Clear drained status and rejoin the work queue",
|
||||
Args: cobra.ExactArgs(1),
|
||||
RunE: func(cmd *cobra.Command, args []string) error {
|
||||
return adminPOST(cmd.OutOrStdout(), flags, "/v1/admin/nodes/"+args[0]+"/uncordon", nil)
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
func newMaintenanceCmd(flags *globalFlags) *cobra.Command {
|
||||
maint := &cobra.Command{
|
||||
Use: "maintenance",
|
||||
Short: "Cluster-wide maintenance mode",
|
||||
}
|
||||
maint.AddCommand(newMaintenanceOnCmd(flags))
|
||||
maint.AddCommand(newMaintenanceOffCmd(flags))
|
||||
maint.AddCommand(newMaintenanceStatusCmd(flags))
|
||||
return maint
|
||||
}
|
||||
|
||||
func newMaintenanceOnCmd(flags *globalFlags) *cobra.Command {
|
||||
var reason string
|
||||
var ttl time.Duration
|
||||
c := &cobra.Command{
|
||||
Use: "on",
|
||||
Short: "Enable cluster-wide maintenance (pauses rebalancer + sweeper)",
|
||||
Args: cobra.NoArgs,
|
||||
RunE: func(cmd *cobra.Command, _ []string) error {
|
||||
body := map[string]any{}
|
||||
if reason != "" {
|
||||
body["reason"] = reason
|
||||
}
|
||||
if ttl > 0 {
|
||||
// encode duration as nanoseconds for Go's JSON decoder
|
||||
body["ttl"] = int64(ttl)
|
||||
}
|
||||
return adminPOST(cmd.OutOrStdout(), flags, "/v1/admin/maintenance/on", body)
|
||||
},
|
||||
}
|
||||
c.Flags().StringVar(&reason, "reason", "", "free-form reason (audit record)")
|
||||
c.Flags().DurationVar(&ttl, "ttl", 0, "auto-disable after this duration (e.g. 30m)")
|
||||
return c
|
||||
}
|
||||
|
||||
func newMaintenanceOffCmd(flags *globalFlags) *cobra.Command {
|
||||
return &cobra.Command{
|
||||
Use: "off",
|
||||
Short: "Disable cluster-wide maintenance",
|
||||
Args: cobra.NoArgs,
|
||||
RunE: func(cmd *cobra.Command, _ []string) error {
|
||||
return adminPOST(cmd.OutOrStdout(), flags, "/v1/admin/maintenance/off", nil)
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
func newMaintenanceStatusCmd(flags *globalFlags) *cobra.Command {
|
||||
return &cobra.Command{
|
||||
Use: "status",
|
||||
Short: "Print current cluster-maintenance state",
|
||||
Args: cobra.NoArgs,
|
||||
RunE: func(cmd *cobra.Command, _ []string) error {
|
||||
return adminGET(cmd.OutOrStdout(), flags, "/v1/admin/maintenance")
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
func adminPOST(out io.Writer, flags *globalFlags, path string, body any) error {
|
||||
return adminCall(out, flags, http.MethodPost, path, body)
|
||||
}
|
||||
|
||||
func adminGET(out io.Writer, flags *globalFlags, path string) error {
|
||||
return adminCall(out, flags, http.MethodGet, path, nil)
|
||||
}
|
||||
|
||||
func adminCall(out io.Writer, flags *globalFlags, method, path string, body any) error {
|
||||
base, err := url.Parse(flags.adminURL)
|
||||
if err != nil {
|
||||
return fmt.Errorf("admin: bad --server url: %w", err)
|
||||
}
|
||||
u := base.JoinPath(path)
|
||||
|
||||
var rdr io.Reader
|
||||
if body != nil {
|
||||
b, err := json.Marshal(body)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
rdr = bytes.NewReader(b)
|
||||
}
|
||||
req, err := http.NewRequest(method, u.String(), rdr)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if flags.adminToken == "" {
|
||||
return fmt.Errorf("admin: --token (or ANCHORAGE_ADMIN_TOKEN) is required — mint a sysadmin token first")
|
||||
}
|
||||
req.Header.Set("Authorization", "Bearer "+flags.adminToken)
|
||||
if body != nil {
|
||||
req.Header.Set("Content-Type", "application/json")
|
||||
}
|
||||
|
||||
resp, err := http.DefaultClient.Do(req)
|
||||
if err != nil {
|
||||
return fmt.Errorf("admin: %s: %w", u, err)
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
b, _ := io.ReadAll(resp.Body)
|
||||
if resp.StatusCode >= 400 {
|
||||
return fmt.Errorf("admin: %s %s → %d: %s", method, path, resp.StatusCode, strings.TrimSpace(string(b)))
|
||||
}
|
||||
// Pretty-print JSON; fall back to raw for empty/non-JSON bodies.
|
||||
if len(bytes.TrimSpace(b)) > 0 {
|
||||
var pretty bytes.Buffer
|
||||
if err := json.Indent(&pretty, b, "", " "); err == nil {
|
||||
fmt.Fprintln(out, pretty.String())
|
||||
return nil
|
||||
}
|
||||
fmt.Fprintln(out, string(b))
|
||||
return nil
|
||||
}
|
||||
fmt.Fprintf(out, "admin: %s %s OK\n", method, path)
|
||||
return nil
|
||||
}
|
||||
@@ -0,0 +1,100 @@
|
||||
package cmd
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
"anchorage/internal/pkg/config"
|
||||
"anchorage/internal/pkg/store/postgres"
|
||||
)
|
||||
|
||||
// newMigrateCmd groups schema-migration subcommands under `anchorage migrate`.
|
||||
func newMigrateCmd(flags *globalFlags) *cobra.Command {
|
||||
migrate := &cobra.Command{
|
||||
Use: "migrate",
|
||||
Short: "Manage the anchorage Postgres schema",
|
||||
}
|
||||
migrate.AddCommand(newMigrateUpCmd(flags))
|
||||
migrate.AddCommand(newMigrateDownCmd(flags))
|
||||
migrate.AddCommand(newMigrateStatusCmd(flags))
|
||||
return migrate
|
||||
}
|
||||
|
||||
func newMigrateUpCmd(flags *globalFlags) *cobra.Command {
|
||||
return &cobra.Command{
|
||||
Use: "up",
|
||||
Short: "Apply all pending migrations",
|
||||
Args: cobra.NoArgs,
|
||||
RunE: func(cmd *cobra.Command, _ []string) error {
|
||||
cfg, err := loadConfigForMigrate(flags)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if err := postgres.MigrateDSN(cmd.Context(), cfg.Postgres.DSN, postgres.MigrateUp, postgres.MigrateOptions{}); err != nil {
|
||||
return fmt.Errorf("migrate up: %w", err)
|
||||
}
|
||||
fmt.Fprintln(cmd.OutOrStdout(), "migrate: up OK")
|
||||
return nil
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
func newMigrateDownCmd(flags *globalFlags) *cobra.Command {
|
||||
var yes bool
|
||||
c := &cobra.Command{
|
||||
Use: "down",
|
||||
Short: "Revert every applied migration (destructive; dev/test only)",
|
||||
Args: cobra.NoArgs,
|
||||
RunE: func(cmd *cobra.Command, _ []string) error {
|
||||
if !yes {
|
||||
return fmt.Errorf("refusing to run destructive migration; pass --yes to confirm")
|
||||
}
|
||||
cfg, err := loadConfigForMigrate(flags)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if err := postgres.MigrateDSN(cmd.Context(), cfg.Postgres.DSN, postgres.MigrateDown, postgres.MigrateOptions{}); err != nil {
|
||||
return fmt.Errorf("migrate down: %w", err)
|
||||
}
|
||||
fmt.Fprintln(cmd.OutOrStdout(), "migrate: down OK")
|
||||
return nil
|
||||
},
|
||||
}
|
||||
c.Flags().BoolVar(&yes, "yes", false, "confirm that you understand this drops the whole schema")
|
||||
return c
|
||||
}
|
||||
|
||||
func newMigrateStatusCmd(flags *globalFlags) *cobra.Command {
|
||||
return &cobra.Command{
|
||||
Use: "status",
|
||||
Short: "Print the currently-applied migration version",
|
||||
Args: cobra.NoArgs,
|
||||
RunE: func(cmd *cobra.Command, _ []string) error {
|
||||
cfg, err := loadConfigForMigrate(flags)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
v, dirty, err := postgres.MigrationVersion(cmd.Context(), cfg.Postgres.DSN)
|
||||
if err != nil {
|
||||
return fmt.Errorf("read migration version: %w", err)
|
||||
}
|
||||
fmt.Fprintf(cmd.OutOrStdout(), "migrate: version=%d dirty=%v\n", v, dirty)
|
||||
return nil
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
// loadConfigForMigrate loads the config with AllowMissing=true (so --config
|
||||
// being absent is fine if the DSN comes from env) but rejects the run if
|
||||
// there's still no DSN.
|
||||
func loadConfigForMigrate(flags *globalFlags) (*config.Config, error) {
|
||||
cfg, err := config.Load(config.LoadOptions{Path: flags.configPath, AllowMissing: true})
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("load config: %w", err)
|
||||
}
|
||||
if cfg.Postgres.DSN == "" {
|
||||
return nil, fmt.Errorf("postgres.dsn is required (config file or ANCHORAGE_POSTGRES_DSN)")
|
||||
}
|
||||
return cfg, nil
|
||||
}
|
||||
@@ -0,0 +1,258 @@
|
||||
package cmd
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"fmt"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
"anchorage/internal/pkg/config"
|
||||
"anchorage/internal/pkg/ids"
|
||||
"anchorage/internal/pkg/token"
|
||||
)
|
||||
|
||||
// DefaultIPFSClientTTL is the ceiling for IPFS-client tokens: 1 year
|
||||
// plus a 30-day rotation grace window. That matches the config-level
|
||||
// auth.apiToken.maxTTL default so `mint-token` can pick this TTL
|
||||
// without tripping the signer's max-TTL guard (the signer doesn't
|
||||
// currently enforce a ceiling, but this keeps the numbers honest).
|
||||
const DefaultIPFSClientTTL = 9480 * time.Hour
|
||||
|
||||
// newMintTokenCmd mints a standalone JWT off the configured signing
|
||||
// key, printing the signed string to stdout. It does NOT talk to a
|
||||
// running anchorage — it reads the key off disk directly, so it works
|
||||
// before any OIDC user exists.
|
||||
//
|
||||
// Primary use case: handing an IPFS client a bearer token.
|
||||
//
|
||||
// anchorage admin mint-token --role sysadmin > /etc/anchorage/client.jwt
|
||||
// ipfs pin remote service add anchor https://anchor.example.com/v1 $(cat /etc/anchorage/client.jwt)
|
||||
// ipfs pin remote add --service=anchor bafybeig...
|
||||
//
|
||||
// A minted token bypasses the active-token / denylist caches because
|
||||
// it was never registered through POST /v1/tokens — this is deliberate.
|
||||
// Operators who need revocation should write the jti to the denylist
|
||||
// via the /v1/tokens API or rotate the signing key.
|
||||
func newMintTokenCmd(flags *globalFlags) *cobra.Command {
|
||||
var (
|
||||
role string
|
||||
orgArg string
|
||||
userArg string
|
||||
ttl time.Duration
|
||||
scopes []string
|
||||
label string
|
||||
issuer string
|
||||
audience string
|
||||
keyPath string
|
||||
kidFlag string
|
||||
verbose bool
|
||||
)
|
||||
|
||||
c := &cobra.Command{
|
||||
Use: "mint-token",
|
||||
Short: "Mint a standalone JWT for CLI / IPFS-client usage",
|
||||
Long: `Mints a signed JWT locally from the configured signing key and
|
||||
prints it to stdout. Suitable for break-glass admin access, for
|
||||
providing a long-lived bearer token to 'ipfs pin remote', or for
|
||||
scripts / CI pipelines that need to call anchorage without going
|
||||
through the interactive Authentik login.
|
||||
|
||||
The default role is 'sysadmin' — which enables /v1/admin/* endpoints
|
||||
(drain, uncordon, maintenance). Downgrade to 'orgadmin' or 'member'
|
||||
when handing a token to a specific org.
|
||||
|
||||
The default TTL is ` + DefaultIPFSClientTTL.String() + ` (1 year + 30-day rotation
|
||||
grace) to match the apiToken.maxTTL ceiling. Shorten it with --ttl
|
||||
for short-lived tokens:
|
||||
|
||||
anchorage admin mint-token --role member --ttl 24h --org org_...
|
||||
|
||||
Minted tokens DO NOT appear in 'list my tokens' (they aren't
|
||||
registered via POST /v1/tokens) and cannot be revoked individually
|
||||
except by denylisting the jti or rotating the signing key.`,
|
||||
Args: cobra.NoArgs,
|
||||
RunE: func(cmd *cobra.Command, _ []string) error {
|
||||
cfg, err := config.Load(config.LoadOptions{Path: flags.configPath, AllowMissing: true})
|
||||
if err != nil {
|
||||
return fmt.Errorf("load config: %w", err)
|
||||
}
|
||||
|
||||
// Defaults: reach into the config's primary signingKey entry
|
||||
// so operators who run mint-token alongside their configured
|
||||
// server get correct key path + kid automatically.
|
||||
primary, havePrimary := primarySigningKey(cfg)
|
||||
if keyPath == "" && havePrimary {
|
||||
keyPath = primary.Path
|
||||
}
|
||||
if kidFlag == "" && havePrimary {
|
||||
kidFlag = primary.ID
|
||||
}
|
||||
if issuer == "" {
|
||||
issuer = cfg.Auth.Authentik.Issuer
|
||||
}
|
||||
if audience == "" {
|
||||
audience = cfg.Auth.Authentik.Audience
|
||||
}
|
||||
if ttl <= 0 {
|
||||
ttl = DefaultIPFSClientTTL
|
||||
}
|
||||
if !validRole(role) {
|
||||
return fmt.Errorf("bad --role %q: must be sysadmin, orgadmin, or member", role)
|
||||
}
|
||||
|
||||
// Pick between a real key file and the built-in dev key.
|
||||
var key []byte
|
||||
if keyPath != "" {
|
||||
k, err := loadSingleKey(keyPath)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
key = k
|
||||
} else {
|
||||
key = []byte(token.DevOnlySigningKey)
|
||||
if kidFlag == "" {
|
||||
kidFlag = token.DevKeyID
|
||||
}
|
||||
}
|
||||
if kidFlag == "" {
|
||||
return fmt.Errorf("--kid is required (or configure auth.apiToken.signingKeys in anchorage.yaml)")
|
||||
}
|
||||
|
||||
// nil TokenStore: standalone mint, no denylist check on verify
|
||||
// and no api_tokens row written. Standalone by design.
|
||||
signer, err := token.NewSigner([]token.SigningKey{
|
||||
{ID: kidFlag, Key: key, Primary: true},
|
||||
}, issuer, audience, nil)
|
||||
if err != nil {
|
||||
return fmt.Errorf("signer: %w", err)
|
||||
}
|
||||
|
||||
orgID, err := resolveOrg(orgArg, role)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
userID, err := resolveUser(userArg)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
jwt, claims, err := signer.Mint(cmd.Context(), orgID, userID, role, scopes, ttl)
|
||||
if err != nil {
|
||||
return fmt.Errorf("mint: %w", err)
|
||||
}
|
||||
|
||||
// A token with empty issuer / audience will fail the running
|
||||
// anchorage's Parse() check (enforced via jwt.WithIssuer /
|
||||
// jwt.WithAudience). Warn loudly so an operator doesn't
|
||||
// silently mint a dud.
|
||||
if issuer == "" || audience == "" {
|
||||
fmt.Fprintln(cmd.ErrOrStderr(),
|
||||
"warning: issuer or audience is empty — this token will NOT verify against a running anchorage "+
|
||||
"that has auth.authentik.issuer / audience set in its config. Re-run with --issuer and "+
|
||||
"--audience matching the server's config, or populate them via anchorage.yaml.")
|
||||
}
|
||||
|
||||
// Primary output — just the token, so shell piping works:
|
||||
// TOKEN=$(anchorage admin mint-token)
|
||||
fmt.Fprintln(cmd.OutOrStdout(), jwt)
|
||||
|
||||
if verbose {
|
||||
// Metadata to stderr so it doesn't contaminate piped output.
|
||||
fmt.Fprintf(cmd.ErrOrStderr(),
|
||||
"# jti %s\n"+
|
||||
"# role %s\n"+
|
||||
"# org %s\n"+
|
||||
"# user %s\n"+
|
||||
"# issuer %s\n"+
|
||||
"# aud %s\n"+
|
||||
"# expires %s\n"+
|
||||
"# label %s\n",
|
||||
claims.ID, claims.Role, claims.Org, claims.User,
|
||||
claims.Issuer, strings.Join([]string(claims.Audience), ","),
|
||||
claims.ExpiresAt.Time.Format(time.RFC3339), label)
|
||||
}
|
||||
return nil
|
||||
},
|
||||
}
|
||||
|
||||
c.Flags().StringVar(&role, "role", "sysadmin", "role: sysadmin | orgadmin | member")
|
||||
c.Flags().StringVar(&orgArg, "org", "", "org TypeID (auto-generated if empty; not required for sysadmin)")
|
||||
c.Flags().StringVar(&userArg, "user", "", "user TypeID (auto-generated if empty)")
|
||||
c.Flags().DurationVar(&ttl, "ttl", DefaultIPFSClientTTL, "token lifetime (max config.auth.apiToken.maxTTL)")
|
||||
c.Flags().StringSliceVar(&scopes, "scope", nil, "scope (repeatable): pin:read, pin:write, ...")
|
||||
c.Flags().StringVar(&label, "label", "cli-mint", "free-form label (emitted in --verbose output)")
|
||||
c.Flags().StringVar(&issuer, "issuer", "", "override JWT issuer (default: config auth.authentik.issuer)")
|
||||
c.Flags().StringVar(&audience, "audience", "", "override JWT audience (default: config auth.authentik.audience)")
|
||||
c.Flags().StringVar(&kidFlag, "kid", "", "key id to stamp into the JWT `kid` header (default: the primary entry in auth.apiToken.signingKeys; "+token.DevKeyID+" when no keys are configured)")
|
||||
c.Flags().StringVar(&keyPath, "signing-key", "", "override signing key path (default: the primary entry in auth.apiToken.signingKeys; built-in dev key when none configured)")
|
||||
c.Flags().BoolVarP(&verbose, "verbose", "v", false, "print jti + expiry + claims to stderr")
|
||||
|
||||
return c
|
||||
}
|
||||
|
||||
// validRole mirrors the roles that actually mean something to the
|
||||
// authz middleware. Keeping this gated at mint time avoids the
|
||||
// confusing runtime path where a token with role="admin" (typo) is
|
||||
// silently demoted to unauthenticated.
|
||||
func validRole(r string) bool {
|
||||
switch r {
|
||||
case "sysadmin", "orgadmin", "member":
|
||||
return true
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// primarySigningKey picks the entry flagged primary from the config.
|
||||
// Returns (zero, false) when no keys are configured — mint-token falls
|
||||
// back to the built-in dev key in that case.
|
||||
func primarySigningKey(cfg *config.Config) (config.SigningKeyConfig, bool) {
|
||||
for _, k := range cfg.Auth.APIToken.SigningKeys {
|
||||
if k.Primary {
|
||||
return k, true
|
||||
}
|
||||
}
|
||||
return config.SigningKeyConfig{}, false
|
||||
}
|
||||
|
||||
// loadSingleKey is the mint-token-only wrapper over token.LoadSigningKeys
|
||||
// that expects exactly one file. Kept local so mint-token doesn't have
|
||||
// to construct a full rotation spec for the single-key case.
|
||||
func loadSingleKey(path string) ([]byte, error) {
|
||||
keys, err := token.LoadSigningKeys([]token.KeyFileSpec{
|
||||
{ID: "mint-one-shot", Path: path, Primary: true},
|
||||
})
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return keys[0].Key, nil
|
||||
}
|
||||
|
||||
func resolveOrg(s, role string) (ids.OrgID, error) {
|
||||
if s == "" {
|
||||
if role == "sysadmin" {
|
||||
// Sysadmin tokens don't need a real org; admin endpoints
|
||||
// use the role, not the org. Mint a fresh one so the JWT
|
||||
// is well-formed.
|
||||
id, err := ids.NewOrg()
|
||||
if err != nil {
|
||||
return ids.OrgID{}, fmt.Errorf("generate org id: %w", err)
|
||||
}
|
||||
return id, nil
|
||||
}
|
||||
return ids.OrgID{}, errors.New("--org is required for non-sysadmin roles")
|
||||
}
|
||||
return ids.ParseOrg(s)
|
||||
}
|
||||
|
||||
func resolveUser(s string) (ids.UserID, error) {
|
||||
if s == "" {
|
||||
id, err := ids.NewUser()
|
||||
if err != nil {
|
||||
return ids.UserID{}, fmt.Errorf("generate user id: %w", err)
|
||||
}
|
||||
return id, nil
|
||||
}
|
||||
return ids.ParseUser(s)
|
||||
}
|
||||
@@ -0,0 +1,55 @@
|
||||
// Package cmd assembles the anchorage Cobra command tree.
|
||||
//
|
||||
// Each sub-command lives in its own file (serve.go, version.go, ...). The
|
||||
// root command is intentionally minimal: it sets up the tree and delegates
|
||||
// all wiring to the composition root in internal/app/anchorage, which is
|
||||
// created lazily by the sub-commands that need it.
|
||||
package cmd
|
||||
|
||||
import (
|
||||
"github.com/spf13/cobra"
|
||||
)
|
||||
|
||||
// globalFlags carries flags that every subcommand inherits via
|
||||
// PersistentFlags. Exposed as a struct so sub-commands can read them without
|
||||
// re-parsing the command line.
|
||||
type globalFlags struct {
|
||||
configPath string
|
||||
// Admin-only flags, populated by newAdminCmd's PersistentFlags.
|
||||
adminURL string
|
||||
adminToken string
|
||||
}
|
||||
|
||||
// newRootCmd builds the top-level `anchorage` command.
|
||||
//
|
||||
// A factory is used (rather than a package-global var) so tests can construct
|
||||
// a fresh command tree with isolated flags.
|
||||
func newRootCmd() *cobra.Command {
|
||||
flags := &globalFlags{}
|
||||
|
||||
root := &cobra.Command{
|
||||
Use: "anchorage",
|
||||
Short: "anchorage — highly-available IPFS Pinning Service",
|
||||
Long: "anchorage runs the IPFS Pinning Service API, cluster coordination, and WebSocket event fan-out for a paired Kubo daemon.",
|
||||
SilenceUsage: true,
|
||||
SilenceErrors: true,
|
||||
}
|
||||
|
||||
root.PersistentFlags().StringVarP(&flags.configPath, "config", "c", "",
|
||||
"path to anchorage config file (default: ./configs/anchorage.yaml, $HOME/.anchorage, /etc/anchorage)")
|
||||
|
||||
root.AddCommand(newVersionCmd())
|
||||
root.AddCommand(newServeCmd(flags))
|
||||
root.AddCommand(newMigrateCmd(flags))
|
||||
root.AddCommand(newAdminCmd(flags))
|
||||
|
||||
return root
|
||||
}
|
||||
|
||||
// Execute runs the anchorage command tree against os.Args.
|
||||
//
|
||||
// It is intentionally the only exported symbol in this package so main.go
|
||||
// stays a thin wrapper.
|
||||
func Execute() error {
|
||||
return newRootCmd().Execute()
|
||||
}
|
||||
@@ -0,0 +1,110 @@
|
||||
package cmd
|
||||
|
||||
import (
|
||||
"crypto/rand"
|
||||
"encoding/base64"
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"time"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
)
|
||||
|
||||
// newRotateKeyCmd generates a fresh random signing key on disk and
|
||||
// prints the YAML snippet an operator pastes into anchorage.yaml to
|
||||
// register it alongside the existing primary key.
|
||||
//
|
||||
// The command is strictly offline — it never contacts a running
|
||||
// anchorage. After writing the new key file + updating config, the
|
||||
// operator restarts the fleet to pick up the secondary key, then at
|
||||
// a later step flips `primary: true` onto it and restarts again.
|
||||
//
|
||||
// Full procedure lives in deploy/README.md under "Rotating the JWT
|
||||
// signing key".
|
||||
func newRotateKeyCmd(flags *globalFlags) *cobra.Command {
|
||||
var (
|
||||
outPath string
|
||||
keyID string
|
||||
bytes int
|
||||
overwrite bool
|
||||
)
|
||||
c := &cobra.Command{
|
||||
Use: "rotate-signing-key",
|
||||
Short: "Generate a new JWT signing key and emit the config snippet for rotation overlap",
|
||||
Long: `Generates a random HMAC key, writes it to --out with 0600 perms,
|
||||
and prints a YAML fragment to stdout showing how to add it to your
|
||||
anchorage.yaml under auth.apiToken.signingKeys.
|
||||
|
||||
This is the first step of a rotation; see deploy/README.md for the
|
||||
full three-step procedure (add as secondary → flip primary → drop
|
||||
retired key).
|
||||
|
||||
The command never touches a running anchorage. Restart the fleet
|
||||
after editing the config.`,
|
||||
Args: cobra.NoArgs,
|
||||
RunE: func(cmd *cobra.Command, _ []string) error {
|
||||
if keyID == "" {
|
||||
keyID = time.Now().UTC().Format("2006-01-02")
|
||||
}
|
||||
if outPath == "" {
|
||||
outPath = filepath.Join(".", fmt.Sprintf("anchorage-jwt-%s.key", keyID))
|
||||
}
|
||||
if bytes < 32 {
|
||||
return fmt.Errorf("bad --bytes %d: minimum 32", bytes)
|
||||
}
|
||||
|
||||
if !overwrite {
|
||||
if _, err := os.Stat(outPath); err == nil {
|
||||
return fmt.Errorf("refusing to overwrite %s (pass --force to allow)", outPath)
|
||||
}
|
||||
}
|
||||
|
||||
raw := make([]byte, bytes)
|
||||
if _, err := rand.Read(raw); err != nil {
|
||||
return fmt.Errorf("read randomness: %w", err)
|
||||
}
|
||||
encoded := []byte(base64.StdEncoding.EncodeToString(raw))
|
||||
if err := os.WriteFile(outPath, encoded, 0o600); err != nil {
|
||||
return fmt.Errorf("write %s: %w", outPath, err)
|
||||
}
|
||||
|
||||
// Primary output: the YAML snippet. Use stderr for the
|
||||
// "wrote key" affordance so stdout stays clean if an operator
|
||||
// wants to pipe it into their config.
|
||||
fmt.Fprintf(cmd.ErrOrStderr(),
|
||||
"# wrote %d-byte key to %s (base64-encoded, %d chars)\n",
|
||||
bytes, outPath, len(encoded))
|
||||
|
||||
fmt.Fprintf(cmd.OutOrStdout(), `# Append this entry to auth.apiToken.signingKeys in anchorage.yaml.
|
||||
# Keep the existing primary key entry; restart the fleet so every
|
||||
# node loads both keys before flipping primary: true over here.
|
||||
|
||||
auth:
|
||||
apiToken:
|
||||
signingKeys:
|
||||
# ... existing keys above, primary: true on ONE of them ...
|
||||
- id: %q
|
||||
path: %q
|
||||
primary: false
|
||||
`, keyID, absOrAs(outPath))
|
||||
return nil
|
||||
},
|
||||
}
|
||||
c.Flags().StringVar(&outPath, "out", "", "write the new key here (default: ./anchorage-jwt-<yyyy-mm-dd>.key)")
|
||||
c.Flags().StringVar(&keyID, "id", "", "kid/label for the key (default: yyyy-mm-dd)")
|
||||
c.Flags().IntVar(&bytes, "bytes", 48, "raw key length before base64 encoding (>=32)")
|
||||
c.Flags().BoolVar(&overwrite, "force", false, "overwrite an existing file at --out")
|
||||
return c
|
||||
}
|
||||
|
||||
// absOrAs returns an absolute form of p if that succeeds, else p as given.
|
||||
// Used purely for the YAML snippet — operators tend to run the command
|
||||
// from /etc/anchorage or similar, and pasting an absolute path is
|
||||
// friendlier than a relative one.
|
||||
func absOrAs(p string) string {
|
||||
if abs, err := filepath.Abs(p); err == nil {
|
||||
return abs
|
||||
}
|
||||
return p
|
||||
}
|
||||
@@ -0,0 +1,39 @@
|
||||
package cmd
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"os/signal"
|
||||
"syscall"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
app "anchorage/internal/app/anchorage"
|
||||
"anchorage/internal/pkg/config"
|
||||
)
|
||||
|
||||
// newServeCmd runs the anchorage server.
|
||||
func newServeCmd(flags *globalFlags) *cobra.Command {
|
||||
return &cobra.Command{
|
||||
Use: "serve",
|
||||
Short: "Run the anchorage HTTP + cluster coordinator",
|
||||
Args: cobra.NoArgs,
|
||||
RunE: func(cmd *cobra.Command, _ []string) error {
|
||||
cfg, err := config.Load(config.LoadOptions{Path: flags.configPath, AllowMissing: true})
|
||||
if err != nil {
|
||||
return fmt.Errorf("load config: %w", err)
|
||||
}
|
||||
|
||||
ctx, stop := signal.NotifyContext(cmd.Context(), syscall.SIGINT, syscall.SIGTERM)
|
||||
defer stop()
|
||||
|
||||
a, err := app.New(ctx, cfg)
|
||||
if err != nil {
|
||||
return fmt.Errorf("init app: %w", err)
|
||||
}
|
||||
defer a.Close(context.Background())
|
||||
|
||||
return a.Run(ctx)
|
||||
},
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,69 @@
|
||||
package cmd
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"runtime"
|
||||
"runtime/debug"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
)
|
||||
|
||||
// Build metadata — overridden via -ldflags at release time.
|
||||
//
|
||||
// go build -ldflags "-X anchorage/internal/cmd.version=v0.1.0 -X anchorage/internal/cmd.commit=<sha> -X anchorage/internal/cmd.date=<iso8601>"
|
||||
var (
|
||||
version = "dev"
|
||||
commit = ""
|
||||
date = ""
|
||||
)
|
||||
|
||||
// newVersionCmd prints build metadata and exits.
|
||||
//
|
||||
// Falls back to debug.ReadBuildInfo() for commit/date so `go install` and
|
||||
// `go run` produce useful output even without ldflags.
|
||||
func newVersionCmd() *cobra.Command {
|
||||
return &cobra.Command{
|
||||
Use: "version",
|
||||
Short: "Print anchorage version and build metadata",
|
||||
Args: cobra.NoArgs,
|
||||
RunE: func(cmd *cobra.Command, _ []string) error {
|
||||
v, c, d := resolveBuildInfo()
|
||||
out := cmd.OutOrStdout()
|
||||
fmt.Fprintf(out, "anchorage %s\n", v)
|
||||
if c != "" {
|
||||
fmt.Fprintf(out, " commit: %s\n", c)
|
||||
}
|
||||
if d != "" {
|
||||
fmt.Fprintf(out, " built: %s\n", d)
|
||||
}
|
||||
fmt.Fprintf(out, " runtime: %s %s/%s\n", runtime.Version(), runtime.GOOS, runtime.GOARCH)
|
||||
return nil
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
// resolveBuildInfo prefers ldflag-injected values and falls back to the
|
||||
// module's embedded vcs info when unset.
|
||||
func resolveBuildInfo() (v, c, d string) {
|
||||
v, c, d = version, commit, date
|
||||
if c != "" && d != "" {
|
||||
return
|
||||
}
|
||||
info, ok := debug.ReadBuildInfo()
|
||||
if !ok {
|
||||
return
|
||||
}
|
||||
for _, s := range info.Settings {
|
||||
switch s.Key {
|
||||
case "vcs.revision":
|
||||
if c == "" {
|
||||
c = s.Value
|
||||
}
|
||||
case "vcs.time":
|
||||
if d == "" {
|
||||
d = s.Value
|
||||
}
|
||||
}
|
||||
}
|
||||
return
|
||||
}
|
||||
Reference in new issue
Block a user