Omniscio

Automation Credentials (saved secrets for v2 actions)

Automation Credentials — the manager that stores the API tokens, webhook URLs, service-account keys and SMTP passwords that the v2 automation actions resolve at run time, the per-kind secret editors, the high-risk write gate, and the metadata-only CLI routes.

On this page

What it is

The Automation Credentials manager is where you store the API tokens, webhook URLs, service-account keys, and SMTP passwords that the new v2 automation actions need at run time. Without it, every Slack / GitHub / SMTP action would have to embed its secret in the action's JSON config — which would leak it into the database row, into automation backups, and into the inbox approval payload an external AI sees before you click Approve. Instead, an action carries only a credentialId reference, and the executor resolves the real secret from this manager (decrypted in the main process) at the moment it needs it.

Where to find it

How to use it

  1. Open the panel. Go to Settings → Automations → Credentials (the Credentials tab of the Automations hub, key icon). The header explains what credentials are and confirms that secrets are encrypted using the OS keyring.

  2. Decide whether you need the high-risk gate. The first control is a toggle labeled Allow high-risk credential kinds. It's off by default. Two of the nine credential kinds are classified high-risk because they hand out broad data access or outbound-abuse potential: google-service-account (broad GCP / Workspace access on the project the key belongs to) and smtp (full outbound mail relay, useful as a spam / phishing vector if leaked). With the toggle off, you can still view, rename, and delete an existing high-risk credential, but creating a new one or rotating its secret is blocked at the IPC handler with a clear error message. The other seven kinds (Slack, GitHub, Sentry, Discord webhook, Notion, Telegram, generic HTTP auth) are scoped enough to never be gated.

  3. Add a credential. Click Add credential at the bottom of the list. A modal titled New credential opens with three fields: a Kind dropdown populated from the registry (slack, github, sentry, discord-webhook, notion-token, telegram-bot, http-auth, google-service-account, smtp), a friendly Name so you can find it later, and a per-kind secret editor that swaps fields based on the kind you pick:

    • slack / telegram-bot — single Bot token password field
    • github / sentry / notion-token — single Token password field
    • discord-webhook — Webhook URL text field
    • http-auth — Scheme selector (bearer / basic / header) with the matching sub-fields underneath
    • google-service-account — Client email plus a tall monospaced Private key textarea
    • smtp — Host, Port, TLS checkbox, Username, Password

    Press Save (or Ctrl+Enter / Cmd+Enter anywhere inside the modal). The server validates the secret shape against the per-kind Zod schema before encrypting; a mismatch surfaces inline as a red error message in the modal — no save happens.

  4. Use it in an action. Open an automation in the v2 editor. For any action that has a credentialKind field (currently slack.send-message, discord.send-message, email.send-via-smtp, github.add-comment, github.create-issue, google-sheets.append-row, http.request, notion.append-block, notion.create-page, and telegram.send-message), the config panel renders a compact <select> — the Credential picker — with the placeholder — Pick a saved credential — and one option per credential of that kind. If the high-risk gate is off, gated rows render disabled with a trailing (blocked) suffix and a callout below the picker links you back to the toggle. If you have no credentials of that kind yet, the picker shows an empty-state with an Add credential button that deep-links to this Settings page.

  5. Rotate or rename a credential. Each list row has three buttons: Rename, Rotate, Delete. Rename opens an inline name-only editor — never gated. Rotate opens an inline secret-only editor with the same per-kind fields as the create modal; rotating a high-risk credential re-checks the gate. Delete prompts you with a danger-variant confirmation explaining that any automations using the credential will fail until you pick a replacement.

  6. The id is what gets referenced. Actions point at credentials by their UUID, not by name — so renaming a credential is safe (no automations break) but deleting one is destructive. When the credential is missing at run time, the resolver throws a clear, user-actionable error into the automation run log instead of silently no-op'ing with an empty secret.

How it behaves

How it works

The settings panel lives at AutomationCredentialsSettings.tsx and is the sole consumer of useAutomationCredentialsStore() from automation-credentials-store.ts. The store is a thin Zustand wrapper over four IPC handlers — automation:credential-list / -create / -update / -delete — defined in automation-credential-handlers.ts. The store deliberately re-fetches after every mutation rather than merging optimistically: the encrypted-blob round-trip means a parallel un-encrypted shadow copy would be the only way to merge locally, and the operations are infrequent enough that a refetch is cheap.

The nine per-kind Zod schemas + the high-risk allow-list live in automation-credential-schemas.ts so both processes import the same source of truth. The credential service at automation-credentials.ts layers four guarantees on top of the dumb persistence layer:

  • Encryption — delegated to the canonical encryptCredential / decryptCredential helpers, which prefix the ciphertext with enc: and use Electron's safeStorage (Windows DPAPI / macOS Keychain / Linux libsecret). When the keyring is unavailable, encryption throws — the service fails CLOSED and nothing is persisted as plaintext. A wrapped, user-actionable error message replaces the internal jargon.
  • Per-kind shape validation — the Zod schema for the credential's kind is parsed on create, on every secret-bearing update, and again on resolve as defense in depth against a corrupt or pre-schema blob.
  • High-risk write-gate — checked in BOTH the IPC handler (so the error envelope is shaped by the handler, not the service) AND inside the service (so non-IPC callers can't bypass it). Both layers fail CLOSED on a missing setting flag.
  • Secrets never cross IPC — listCredentialsMetadata returns id / kind / name / timestamps only, augmented in the handler with isHighRisk: boolean. The store carries that shape verbatim; the unit test cross-checks that JSON.stringify(state) doesn't contain a secret string after a create.

The Credential picker component at CredentialPicker.tsx is a read-only sibling of the settings panel — it never creates, edits, or deletes, only filters the store to its kind prop and renders the gated rows as disabled <option>s. The picker mirrors the IPC-level write-gate for visual feedback but never enforces it — the handler is the sole authority. The empty-state's Add credential button deep-links via navigateToSettingsProject({ section: 'automation-credentials' }).

Resolution happens at run start, never mid-run: the executor calls resolveCredential(id, { automationId, runId }), the service decrypts, JSON-parses, re-validates, and audit-logs the successful resolve to credential_access_log. Failed resolves are NOT logged — nothing usable was returned, so there's nothing to record as "accessed"; the thrown error lands in the automation run log instead.

Where this fits in the v2 automation flow

This page is the secrets-storage layer that the v2 action chain depends on. The integration-by-id model (action references credentialId, never the secret itself) is what lets credentials be rotated without editing every automation, and what keeps the inbox approval payload clean — when an external AI queues an automation create through the CLI server, the approval modal shows you the credentialId reference, not the secret. See automations-and-auto-replies.md for the full action-chain model, the cron-like / message / session-state triggers, and the per-rule preset catalog.

Testing this pane

The pane's spec is automation-credentials-settings.test.tsx (F211). It is the only spec that renders AutomationCredentialsSettings — before it the pane had zero test importers, and the nearest specs covered the pure helpers, the SMTP port field and the main-process IPC handlers instead. It pins the behaviours a regression would silently break:

  • creating with a blank name is blocked with no IPC call;
  • the create form defaults to the slack kind, and switching kind from github to notion-token carries the typed token across (both kinds share that field, so a regression would silently discard a pasted secret);
  • rotate sends only { secret } for the selected id, and rename sends only { name };
  • delete is confirm-gated — Cancel deletes nothing — and a failed delete toasts humanized copy with no raw machine token in it.

Spec mechanics that are easy to get wrong when editing it:

  • The confirm is the real stack. useConfirmDialog + ConfirmDialog + DialogShell render the prompt; the credentials store is mocked, so the spec exercises the pane's logic rather than the store's IPC plumbing (covered elsewhere). framer-motion is neutralised so the portal mounts synchronously in jsdom, and useEscapeClose is mocked.
  • The delete confirm is an alertdialog. The pane opens it with variant: 'danger', and ConfirmDialog renders role="alertdialog" for that variant (destructive-confirm-is-an-alertdialog in .claude/memory/contracts/frontend-modal-contract.md). Query alertdialog in every assertion about this prompt — a dialog query never matches, and a negative queryByRole('dialog') after Cancel is vacuous because it could never match in the first place.
  • rowFor(name) scopes a query to one credential row. It walks up from the name to the smallest ancestor that also carries that row's own Delete button; the settings panel itself would match a bare closest, so the button's presence is what bounds the walk.
  • Two rows on purpose. The fixture holds a GitHub credential and a Slack one so "the clicked credential" is distinguishable from "some row" when asserting the id that reaches the store.
  • The fixture lives inside the vi.mock factory. vi.mock is hoisted above the module body, so a top-level const holding the rows would still be in its temporal dead zone when the factory runs.
  • The kind picker has no accessible name (its <label> is not htmlFor-linked), so chooseKind drives the lone combobox rather than querying by label.
  • Rename reuses its input node. getByDisplayValue normalizes whitespace, so a whitespace-only value can never be matched by re-querying; the case keeps the node it already has and changes it again.
  • automations-and-auto-replies.md — the parent feature; v2 actions reference credentials stored here
  • cli-pending-actions.md — the approval queue an external AI uses; automation-rule creates ride on the separate per-row approval_status='pending' flag described there

Last verified 2026-09-23