Secrets

Your agents work with things that must stay private: the sign-in a connector holds for Slack, an API key a session needs in a VM, the cookies and passkeys that keep you signed in to a site in a web pane, and Mod's own sign-in. This page is about where those live and who can reach them.

The rule behind all of it: Mod holds no secret it can avoid holding. A secret goes to your operating system's keychain on the device that needs it, and Mod keeps only the right to ask for it.

How it works

Never in the shared state. A secret never goes into a document, a release, a session's log or anything else that syncs. Everything in storage is meant to be on every device and readable by every agent you share it with, so it is the wrong place for a key.

Connector sign-ins. A connector has two halves. Its definition, the tools it offers and the hosts it may reach, is installed on your World and syncs like an app. Its binding, your actual token, belongs to one person on one machine, in that machine's keychain. Installing a connector grants nobody anything; connecting it is a separate act. The connector's code never sees the token: it is added to each request on the way out.

API keys for a VM. When an agent in a VM needs to call a service with your key, it asks for a grant. On your yes, you put the key in your Mac's Keychain yourself. The VM only gets a URL, and your Mac adds the key on the way out to that one host, so the key never enters the VM or passes through the agent. See authentication.

Logins in web panes. A web page in Mod keeps its cookies and storage in its own persisted browser session, apart from the app, so a login survives a reopen and the page cannot read Mod's own storage. A site can offer a passkey through Touch ID: a passkey made inside a pane is held by macOS, in Mod's keychain group, and Mod can ask for it but cannot read it.

Device and session keys. Each device makes its own key on first run and keeps it in the keychain. It is how the device proves itself to the relay, and in the sharing model how a person holds their devices. A session's key is held by the host that runs it, never inside the VM. See identity.

Using it as you build

Agents ask for what they need and never handle the secret itself:

request_grant   { "name": "example-api", "host": "api.example.com" }
list_grants
remove_grant    { "name": "example-api" }

On your yes, the VM reaches https://api.example.com/ through a URL in MOD_GRANT_EXAMPLE_API_URL, with your key added on the way out. Removing a grant stops its requests at once; the key stays in your Keychain for you to delete.

A package that needs a credential is a connector: it declares the hosts it reaches, and each person who installs it connects their own account. Code you write never reads a token. It calls the connector's tools, and the token is attached on the way out.

What we are designing

These are open, and not yet agreed in an RFC.

• Syncing secrets you choose to share between your own devices. Today each machine connects a connector, and holds a grant's key, once. Your devices already hold keys of their own under the sharing model (RFC 0345), so a secret could travel end-to-end encrypted to the devices you add, and never be readable by the relay. being designed
• One place to see and revoke what you have stored. Connector sign-ins, grants and web logins each have their own home today. being designed
• Helping you hold other private information, such as recovery codes or a shared team key, without Mod becoming a password manager that can read them. being designed

Limits

• Mod's own sign-in, and connector sign-ins, are kept in files readable only by you, not yet in the Keychain (RFC 0291). soon
• A passkey already in iCloud Keychain cannot be used from a web pane. A passkey you add from inside the pane can.
• Keychain storage is macOS only. Linux servers keep their own sign-ins on disk.