Password Reveal

When to useCopy Anchor Link

• The user asks for a secret they're entitled to see and a tool returned it: a shared Wi-Fi password, backup codes, an API key they just created, a door code.
• The user wants a new strong password. Use kind: "generated" so it's made in their browser and the agent never sees it.

When not to useCopy Anchor Link

• The agent hasn't checked that the user may see the secret. Check access first; never reveal someone else's credentials.
• The agent doesn't have the secret from a tool result. It never invents, guesses or reconstructs one.
• The value isn't secret (a booking reference, an order number). Show it as text.
• The user wants a guest network as a scannable code. Use the QR Code.

Security rulesCopy Anchor Link

These are enforced in the component, not left to the agent:

Best effort means best effort. Most browsers don't grant clipboard read without a prompt, so on most devices the component can't clear the clipboard and says so ("Copied. Clear your clipboard when you're done."). It never prompts for clipboard access and never overwrites something else the user copied since. Clipboard history tools and synced clipboards can keep a copy regardless.

Keep the secret out of the model. The masking protects the screen, not the transcript. Where you can, have the host's reveal_secret tool fetch the secret server-side and pass value to the UI only, rather than having the model copy it into the tool call. Don't persist value in chat history you replay to the model, and drop it from stored history for one-time codes.

How the agent should use itCopy Anchor Link

• Pass the value exactly as the tool returned it. value is data-bound: it comes from a tool result, never from model free text. Never repeat it in the reply, a summary or another tool call.
• For a new password, use kind: "generated" with generate options (length 12–64, symbols, numbers, uppercase, exclude for characters the target site rejects). Don't put a password the model made up in value.
• Set oneTime for recovery and one-time codes, rotatable when the agent can issue a replacement, and expiresAt when the secret lapses (shown as "Expires in 23 h").
• Put where to use it in hint (the network, the door, the service), never the secret.
• On rotated-request, issue a new secret and show a new card. The old card stays hidden.
• Lifecycle: when the secret itself lapses (a temporary door code, a short-lived token), set expiresAt on the call and pass the same value as the expiresAt prop, so the card shows "Expires in 23 h" and the Renderer turns it inert afterwards. When a rotation replaces it, mark the old call superseded by the new one. fetchedAt isn't needed.

InteractionCopy Anchor Link

Icon-only controls have full accessible names ("Reveal Guest Wi-Fi password") and fixed-text tooltips, never the secret. The kind (Password, Codes, …) is read to screen readers; one-time cards add one line, "Shown once. Save it before it hides."

Codes (kind: "codes") are revealed as a numbered two-column grid. revealed and copied can repeat; rotated-request and dismiss end the card.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/password-reveal.json

UsageCopy Anchor Link

import { tool } from "ai"
import { passwordRevealTool } from "@/components/genui/password-reveal.schema"

const tools = {
  [passwordRevealTool.name]: tool({
    description: passwordRevealTool.description,
    inputSchema: passwordRevealTool.inputSchema,
  }),
}

onResult receives an action, never the secret:

{ action: "revealed" } // or "copied", "rotated-request", "dismiss"

Only rotated-request needs the agent's attention; the others are for your analytics.

With LangGraphCopy Anchor Link

Push it from a graph node with ui.push({ name: "reveal_secret", props: { toolCallId, ...args } }, { message }), and render the thread's UI messages with the Renderer. Fetch the secret inside the node and put it in props only, not in the message the model reads.

Restoring from historyCopy Anchor Link

Pass the stored result back as result. dismiss and rotated-request restore the closed card, and any result on a oneTime secret restores it as already shown. The secret is never shown again from history, and onResult isn't called.

<PasswordReveal
  {...part.input}
  result={part.state === "output-available" ? part.output : undefined}
/>

SchemaCopy Anchor Link

Host props: status (streaming, ready, consumed, dismissed, rotation-requested), onResult, result and className.

SourceCopy Anchor Link