orama cluster and operator

orama cluster

Register the cluster's public name on the chain, retire it, and remove a tenant's
namespace as an operator. Who may create namespaces and the cluster's update
policy are maintainer commands: see 'orama maint cluster'.

orama cluster namespace

orama cluster namespace remove <namespace> [flags]

Remove a namespace and everything in it: its cluster on every node, its
deployments, its stored content (unless another namespace holds the same), its
keys and its grants.

The owner deletes a namespace with 'orama namespace delete'. This is for a
namespace whose owner cannot: the owner's wallet is lost, or it belonged to a
test run's throwaway wallet. Such a namespace keeps its port blocks and
processes on three nodes until an operator removes it.

It needs the operator grant and a wallet on the operator list. --reason is
required and is written to the audit trail with your wallet
(namespace.operator_remove). You are asked to type the namespace name unless
--force is given.

orama cluster register-onchain [flags]

Register an optional public row for this cluster on the Orama chain.

The row is the operator, the cluster id, the base domain, the public
endpoints, and an optional metadata URI. It does not include node addresses,
tenants, or any cluster secret, and registering it does not join a node.

--node is that chain's REST API. The command reads the account there, builds
a SIGN_MODE_DIRECT transaction, asks the RootWallet agent to sign that one
transaction, and broadcasts it. Without --node it prints the sign document
and does not submit anything. --onion sends the same transaction to a validator
onion service through a Tor SOCKS proxy on this machine instead, on a fresh
circuit, and never falls back to the clearnet: when Tor or the service is
unreachable the command fails and the transaction is not sent.

The fee is an explicit amount of norama. There is no default.

orama cluster retire-onchain [flags]

Retire the optional public cluster row. This does not change any node and
does not delete the cluster's namespaces. Without --node the command prints
the sign document and does not submit it.

orama maint cluster

Who may create a namespace on this cluster, and how many one wallet may own.

A new cluster allows only its operators. A cluster that already had a
namespace besides the seeded default, a node, or an operator when this was
upgraded stays open — any signed-in wallet — until an operator changes it.
The per-wallet cap stays 10 until an operator raises or lowers it.

Changing a setting or the creator list needs the operator grant and a wallet
on the operator list, and is written to the audit trail.

orama maint cluster creators

The allowlist consulted when namespace creation is allowlist.

An operator is not on it unless added. An empty list lets nobody create a
namespace, and removing the last wallet does not lock operators out.

orama maint cluster creators add <wallet>

orama maint cluster creators list

orama maint cluster creators remove <wallet>

orama maint cluster settings

orama maint cluster settings set <setting> <value>

namespace-creation is operators, allowlist or open.

  operators   only wallets on the operator list
  allowlist   only wallets added with orama maint cluster creators add
  open        any signed-in wallet

max-namespaces-per-wallet is an integer from 1 to 10000. The default is 10.

The cluster's automatic updates (docs/whitepaper/technical-reference/vol1/29-build-signing-and-release.md, "Auto-update"):

  auto-update      off, notify (the default) or auto. notify reports a newer
                   release in 'orama status'; auto installs it, one node at a
                   time, when the cluster is healthy and the hour is in the window
  update-channel   the release channel to follow: stable (the default) or nightly
  update-window    start-end hours UTC when auto may install, for example 1-5;
                   empty for any hour
  release-repo     the https URL of the release repository; empty (the default)
                   means no updates are looked up

orama maint cluster settings show

orama maint operator

Commands for the wallets on the cluster's operator list.

Every one of them needs the admin grant and a wallet on that list; a namespace's
own admin key is not enough.

orama maint operator add <wallet>

orama maint operator list

orama maint operator remove <wallet>

orama maint operator rotate-secrets [flags]

Rewrite function secrets, push tokens, TURN secrets, deployment
environments and agent tokens onto the versioned envelope (enc:v1:<id>:).
A deployment's environment is written as enc:v2:<id>:, sealed to its namespace
and deployment id, so a copy of the ciphertext in another deployment's row does
not open. This is also what turns on bound writes: until it has run, gateways
keep writing deployment environments in the envelope an older gateway reads.

Without --rotate the IKM does not change: leftover plaintext and the legacy
enc: form are rewritten so a captured snapshot of the old format is no longer
the live one, and Decrypt can fail closed.

With --rotate a new encryption root is generated. Existing ciphertext is
re-encrypted under it. A disk that holds only the previous root cannot open
the new rows. IPFS-Cluster and the mesh bearer are not touched.

Do not run this until every gateway is on a binary that can read enc:v2:.
The walker is idempotent; if it is interrupted, run it again.

orama maint operator rotate-signing-key

Generate a new signing key for the gateway, publish it, and start signing
with it.

Nobody is signed out. The outgoing key keeps verifying the tokens it already
signed until they expire on their own, so both keys are accepted for one
access-token lifetime and then the old one stops.

The key used to be derived from the cluster secret, which meant there was
nothing to rotate to: changing it meant changing the cluster secret, which
invalidates every token in the cluster at once.