Passwords and credential tools

SoAI handles several things that people casually call passwords, but they do not share one storage or trust model. A WebUI login password, a saved website credential, an API key, and a string produced by random_generate pass through different code paths. Use the path designed for the secret you have.

What SoAI does with each credential

Credential How SoAI handles it What matters
WebUI account password SoAI stores an Argon2 hash and verifies the submitted password against it. The original password cannot be recovered from the database. Use a separate password manager to store this password. The SoAI vault is available only after you sign in, so it cannot recover the password that unlocks the same account.
Saved website credential SoAI encrypts the username and password with the installation encryption key and binds the entry to its owner and website origin. SoAI must be able to decrypt this value for autofill. A person who obtains both the database and the encryption key can do the same.
API key, MCP token, or linked-account secret Each subsystem has its own creation, storage, expiration, and revocation rules. Do not treat these as WebUI passwords or save them in a conversation. Follow Authentication and API keys and the documentation for the owning integration.
random_generate output The tool uses the operating system's cryptographic random source, including when charset is password, then returns the generated string as a normal tool result. The model sees that result. A remote model provider may see it too. This is not the protected vault path.

Choose a strong SoAI account password

SoAI accepts WebUI passwords from 8 to 1,024 characters. Eight characters is the validation floor, not a security recommendation. SoAI does not currently enforce its internal strength scorer, check a password against a breached-password list, or add a second authentication factor to WebUI login.

  • Use a unique password for SoAI. Never reuse one from email, a model provider, an operating-system account, or another service.
  • Prefer a password-manager-generated value of at least 15 characters. A longer passphrase made from unrelated words is a reasonable alternative when you must type it yourself.
  • Length and uniqueness matter more than predictable substitutions or a forced mix of character classes.
  • Keep the password in a reputable password manager protected by a strong, unique master password and multifactor authentication.
  • Do not paste the password into Chat, a prompt, an automation, a project file, a shell command, or a support request.
  • Change it after known or suspected disclosure, reuse on a compromised service, or unauthorized account activity. Routine changes without evidence of compromise usually encourage weaker, predictable passwords.

Login throttling slows online guessing but does not make a weak password safe. The default WebUI guard uses a five-minute window and a maximum of ten failures across client-address and account-related buckets. Keep SoAI behind the private deployment boundary described in Security hardening. If remote access needs a second factor, require it at the VPN or access gateway and make sure clients cannot bypass that boundary to reach SoAI directly.

How the protected credential path works

The protected path consists of five vault tools and two browser autofill tools. These tools do not place the plaintext in their arguments or results. The detailed controls and arguments are in Secrets vault; the security flow is:

  1. vault_login_request or vault_secret_request opens a credential form for the signed-in user.
  2. The user enters the secret in that form, not in the conversation. SoAI returns an opaque handle and optional saved-entry metadata to the model.
  3. The task handoff is encrypted and expires after ten minutes. Once claimed, the credential is held behind an in-memory handle bound to the user and conversation.
  4. If the user saves it, SoAI encrypts the credential in the database and records its owner and website origin.
  5. browser_autofill_secret or browser_autofill_vault checks the live browser origin, resolves the secret on the server, and fills the page without placing the plaintext in tool arguments or results.

vault_list and vault_search return labels, credential identifiers, origin scopes, dates, and a masked username hint. They do not return passwords. vault_delete removes one saved credential. Resetting Password manager deletes every saved credential owned by the signed-in user and invalidates that user's active secret handles.

Where the protection ends

The request and autofill tools do not return plaintext to the model. That is useful, but it is not a guarantee that another enabled browser tool cannot retrieve the value after it has been placed in the page.

  • Prompt injection can still persuade an agent to request or use a credential. Read the site and reason shown in the approval prompt. Reject an unexpected login, an unfamiliar domain, or a request that does not match the task.
  • Origin binding compares the URL scheme, canonical hostname, and explicit port. It blocks use on another origin, but it cannot tell whether the intended site is compromised or whether you approved a convincing lookalike domain.
  • After a successful login, the browser session carries the account's authority. Other enabled browser tools can read or act as that account until the session is cleared or expires.
  • browser_type refuses password and one-time-code fields, but browser_eval can run arbitrary JavaScript in the page. While a filled password remains in the DOM, an evaluation can read it and return it to the model. JavaScript evaluation is enabled by default and is not individually marked for approval.
  • Origin binding controls where SoAI fills a credential. It does not control what scripts already running on that page do with the field value. The destination receives the password, and a compromised destination or injected page script can steal it.
  • Vault encryption protects database contents without the installation key. It does not protect against an attacker who controls the SoAI process, the host account, the browser profile, or both the database and encryption key.
  • Saved entries are isolated by SoAI user ID, but every credential tool still sits behind broad MCP usage (MCP_USE). There is no separate vault ACL action.
  • vault_login_request, both autofill tools, and vault_delete are individually marked for approval in Chat. vault_secret_request still requires the user to complete its credential form. vault_list and vault_search are not individually marked for approval and return their metadata without an approval prompt.
  • Enabling Allow plaintext secret replies for a messaging account bypasses the protected Chat form. The messaging provider may retain the reply in history, notifications, logs, or backups.

Harden credential-tool access

  • Leave vault and autofill tools out of a conversation or automation that does not need them. They are included in the default Execute-mode and automation tool sets, so review those selections before processing untrusted content.
  • When a browser session will receive credentials, set TOOLS.MCP.BROWSER.JS_EVAL_ENABLED to false and leave browser_eval out of the selected tools. This removes the direct path for model-written JavaScript to read a filled password field.
  • Keep per-call approval for autofill. A remembered approval is wider than one deliberate login and is a poor fit for high-value accounts.
  • Do not add credential tools to TOOLS.MCP.SERVER_MODE.EXPOSED_TOOLS. They are absent from the default MCP server exposure list, and the security hardening audit flags them when added.
  • Keep shell access disabled for agents that do not need it. A process with access to the SoAI data directory may reach the database and encryption key outside the vault-tool boundary.
  • Protect backups and the installation encryption key separately. A database backup without the key cannot restore saved credentials; a copy containing both can expose them.
  • Remove credentials that are no longer needed. Deletion has no undo, and changing a password at the destination does not remove the stale vault entry automatically.

If a password may be exposed

  1. Change the password at the system that accepts it. Deleting a vault entry does not revoke the credential at that system.
  2. Revoke that system's active sessions and tokens when it provides those controls.
  3. Delete the old SoAI vault entry and clear any affected browser session before saving or using the replacement.
  4. If the SoAI WebUI password is affected, change it and review active devices. SoAI revokes the account's earlier sessions when the password changes.
  5. If the SoAI host, database, and encryption key may all have been exposed, rotate every credential stored in the vault, not only the one involved in the visible incident.

Related documentation