Skip to main content

How NodeVault works

NodeVault seals a credential's secrets with a key that only your organization's nodes hold. Jaah stores and relays the sealed secrets, but it never holds the key that opens them. A leaked Jaah database, backup, log or encryption key can't reveal a secret entered with NodeVault on.

Without NodeVault, a credential's secrets are encrypted with a key Jaah manages. With it, the key is yours: your browser makes it, you keep a passphrase-protected backup of it, and your nodes keep it on their own disk. A task on one of your nodes still gets the secret in plain text when it fetches the credential, so nothing about how tasks use credentials changes.

NodeVault is part of some plans. An Org Owner or Org Admin sets it up once, under Settings, then NodeVault. For the steps, see Set up NodeVault and Rotate the NodeVault key. For every control on the screen, see Settings.

Terms​

TermMeaning
NodeVault keyYour organization's key pair. The private half opens NodeVault secrets; the public half seals them. Jaah keeps only the public half.
BackupA file holding the private key, locked with a passphrase you choose. Jaah keeps no copy.
Identity keyA key each node makes for itself. Your browser wraps the NodeVault key to it, so only that node can unwrap its copy.
NodeVault credentialA credential whose NodeVault box is ticked. Its secrets are sealed with your NodeVault key.
Current keyThe key new NodeVault secrets are sealed with.
Previous keyA key that was current before a rotation. Nodes keep it until you retire it.

Where the key goes​

Setup happens in your browser. It makes the key pair, wraps a copy of the private key to each node's identity key, and sends only those wrapped copies. Jaah passes them on; each node unwraps its own copy and stores the key.

A node that joins your organization later gets the key from a node that already holds it, again as a copy only the new node can unwrap. New nodes get the key automatically, so check them on Settings, then NodeVault, and in the audit log: compare a node's Fingerprint in that list with what jaah nodevault fingerprint prints on the machine.

How a task gets a secret​

When you save a NodeVault credential, your browser seals each secret with the public key before it leaves the page. Jaah stores the sealed value. When a task on one of your nodes fetches the credential, that node opens it and hands the task the plain value.

Only your nodes can open a NodeVault secret, so a credential Jaah's own servers use — for example a GitHub App connection or anything signed in through OAuth — can't be a NodeVault credential. The form says why when the box can't be ticked.

The key's life​

You set the key up once. Later you can rotate to a new one; the old key then becomes a previous key, and your nodes keep it until you retire it. Retiring is allowed only once no credential uses that key.

  • Set up makes the first key, sends it to your nodes and, if you choose, moves existing credentials into NodeVault.
  • Rotate key makes a new current key. A node that holds both keys re-seals every NodeVault secret under the new one, so Jaah never sees the secrets.
  • Retire deletes a previous key from every node. It can't be undone.

Rotating does not protect you if your current key was exposed: the new key is wrapped under the old one. If you think a key leaked, re-enter each secret instead, or change it with the service it belongs to.

Plans and NodeVault​

Your planWhat you can do
Doesn't include NodeVaultSettings, then NodeVault says Not included in your plan, and the NodeVault box on a credential can't be ticked.
Includes it, not set up yetSet up is available. The NodeVault box says NodeVault isn't set up yet.
Includes it, set upNew credentials start with NodeVault ticked wherever it can be used.
No longer includes it after setupExisting NodeVault credentials keep working. You can't set up, rotate, retire or add new NodeVault credentials, and moving credentials is skip-only. A credential can still leave NodeVault.

What NodeVault doesn't cover​

  • A task gets the secret in plain text. If the agent prints it, it can land in the session transcript and reach the model provider.
  • The console's own code comes from Jaah. NodeVault protects you from a breach of Jaah, not from Jaah itself acting in bad faith.
  • On nodes Jaah hosts for you, Jaah has root access.
  • New nodes in your organization get the key automatically. A node added by someone in control of Jaah's servers would get it too, so check new nodes in the audit log and on Settings, then NodeVault.
  • Moving an existing credential means Jaah's server opens it one last time to re-seal it. To avoid that, re-enter the secret instead. Older Jaah backups may still hold the value as it was before the move, so change it with the service it belongs to after moving.

Every key generation, upload, delivery, rotation, move and retirement is in the audit log: on Audit, the Users tab with Area set to NodeVault. See Audit.