Operators and authentication

#Operator keys

scafo operator keygen --register

A key pair is written to ./scafo-operator.json by default, under an id of the form op-<hex>. --out names another file, --id pins the id. The public half is registered at _scafo/operators/<id>.json.

Operator and node ids share one keyspace and cannot collide; registering a node under a trusted key's id is refused with reference-held.

Tokens are short-lived, single-use EdDSA bearer tokens with a hard 60-second lifetime ceiling, audience scafo-node.

#Roles and scopes

A scope entry is one of three things: *, an exact application name, or a prefix glob — a run of name characters, which may end in a hyphen, followed by one trailing *.

A * anywhere else in an entry is invalid-input. An empty scope list is refused too: a key that reaches nothing is not a grant.

One action asks for more than the application it names: claiming a custom domain with its subdomains also decides what <name>-<env> answers on, so it takes a key whose scope reaches shop-* and not only shop.

A call naming an application the key does not reach is refused with auth-scope, without disclosing whether the application exists. Scoped callers see only their own key lineage and the applications they reach; scope-filtered responses carry scoped: true, and a non-admin's view of an application omits the fleet-owned labels.

#Bucket credentials are root

Bucket credentials rewrite the registry directly and outrank every operator key. Some commands use them on purpose — fleet nodes, trust, metrics, traces, deployment prune, the scafo app verbs that can write the bucket directly, and --register — because they must work when no node is up. Keep them out of tenant workflows and out of the ingress.

#Remotes

A remote names an installation and holds the key that speaks to it. Remotes live in the operator home: $SCAFO_HOME when set (must be absolute), else $XDG_CONFIG_HOME/scafo, else ~/.scafo.

scafo remote add prod \
  --endpoint https://node-a.example.com \
  --endpoint https://node-b.example.com \
  --register
scafo remote list
scafo remote export prod --out prod-remote.json
scafo remote remove prod

--register on remote add reads the bucket from the config file named by --config and from the environment — remote add takes no bucket flags of its own, because its --endpoint names a node — and admits admin tier only.

A key is resolved for a command in this order: --key (a keygen file, an exported remote file, or an inline base64: value), then SCAFO_OPERATOR_KEY in the same three forms, then the key of the remote the invocation resolved to, and finally ./scafo-operator.json when the home holds no remote at all. The remote itself comes from --remote, then SCAFO_REMOTE, then the remote pin in the config file named by --config, then the only remote in the home.

#Enrolling somebody else

scafo operator show --key ./mykey.json
scafo operator enroll ./their-key.pub.json --remote prod --role operator --apps shop --apps 'shop-*'
scafo operator list --remote prod
scafo operator revoke --id op-1a2b3c --remote prod

The registry additionally preserves the last trusted key and the last admin.

#Rotation

scafo operator rotate --remote prod
scafo operator rotate --remote prod --keep-old
scafo operator rotate --remote prod --purge-old

Rotation registers the new key as superseding the old one, proves the new key against the node, then drops the old. --keep-old stops after the flip, leaving both trusted; --purge-old deletes the old key file once it is untrusted.

#Node tokens and workload tokens

scafo deploy --token <t> presents a token instead of signing one. A single-use node token cannot also poll the deploy status; that attempt fails with a clarified auth-invalid.

#auth-invalid versus trust-mismatch

#Public and privileged surfaces