Clipboard API: Respect User Intent Before Reading

The Clipboard API lets an authorized page write or read system clipboard data, but the API result is not proof that a person intended to disclose content. BotBrowser can replay an owned page with a declared profile and record the visible permission, fallback, and status states; it cannot read a user's real clipboard, grant permission, or decide whether a person meant to share a value. A safe design starts with the task the person requested, then asks for the smallest clipboard operation that completes it.

The W3C Clipboard API specification separates asynchronous clipboard operations from the browser's permission and user-activation rules. MDN's Clipboard API reference describes the browser-facing surface, while the web.dev asynchronous Clipboard guide shows progressive enhancement patterns. Together they support a boundary that matters in production: a resolved promise says what the browser accepted, not what a person has pasted, reviewed, or authorized on a remote service.

TL;DR

• Start from a visible user action and state whether the page will write, read, or convert clipboard data.
• Treat navigator.clipboard.writeText() and navigator.clipboard.readText() as different privacy decisions with separate fallbacks.
• Keep a selectable field, keyboard path, and status message available when secure context, focus, policy, or permission blocks the API.
• Record a redacted operation state such as write-success or read-denied, never the clipboard content.
• Use a synthetic fixture to compare support and failure branches; BotBrowser cannot make a real clipboard or permission decision appear.

Contents

• Define the clipboard action and user intent
• Separate write and read permission paths
• Handle text and rich clipboard formats
• Keep fallback and focus visible
• Record outcomes without collecting secrets
• Verify behavior with a bounded fixture
• Practical conclusion

Define the Clipboard Action And User Intent

Clipboard work begins with a concrete task, not with a background probe. “Copy this invoice number” is a write operation with a visible source value. “Paste a code into this form” is a read operation that should happen after the person chooses the destination. “Import formatted content” may require ClipboardItem and a format allowlist. Write the task into the control label and status text before invoking navigator.clipboard, so a user can predict what will happen.

The browser context matters. The W3C model and MDN guidance describe secure-context requirements and permission checks that can vary with origin, focus, embedding, browser policy, and a transient user activation. A page load is not user intent. Do not call readText() in a timer, hidden iframe, analytics callback, or route prefetch merely because the interface might eventually need a value. A denied or empty result is not evidence that the person has no clipboard content.

Use a small state vocabulary shared by the UI and support record: idle, intent-recorded, write-requested, read-requested, completed, denied, cancelled, unsupported, and failed. The state completed should mean that the page received the browser result and updated its visible control. It should not mean that the operating system displayed a notification, that another application accepted a paste, or that a server stored the value.

The browser permission guide explains why permission state can become an observable browser signal without becoming an identity claim. Apply that boundary here: a clipboard status supports the current interaction, not a persistent profile. Keep the operation tied to a request identifier such as clip-17, and expire it when the task or route changes.

Separate Write And Read Permission Paths

Writing a value chosen by the page usually carries a narrower disclosure risk than reading arbitrary clipboard data. Give the write control a descriptive label, such as “Copy recovery code,” and show the source value nearby. The application can call navigator.clipboard.writeText(value) after the click, then announce write-success or write-denied. If the browser rejects the promise, preserve the value in a selectable field instead of claiming that the copy succeeded.

Reading is a different decision. Ask the person to place focus in the destination field, explain that the page will read the clipboard, and start navigator.clipboard.readText() only from that deliberate action. Avoid a silent read followed by account lookup or suggestion ranking. Clipboard contents can contain passwords, private messages, payment details, or text copied for another application. A read result should be consumed once, validated for the current field, and removed from transient state after the operation.

Feature detection distinguishes an absent API from a rejected request, but it does not predict a permission outcome. Check globalThis.isSecureContext and navigator.clipboard?.writeText or readText before presenting the preferred path. The result table below keeps the product decision separate from the browser observation.

Browser observation	Product state	User-visible action
API method is absent	unsupported	Keep the selectable field or keyboard paste route visible.
Promise rejects with NotAllowedError	denied	Explain that the browser did not permit this operation and keep the fallback.
User closes or leaves the flow	cancelled	Return focus to the original control without retrying automatically.
Promise resolves after a write	completed	Announce that the page handed the selected value to the browser.
Read returns text that fails validation	failed	Keep the field unchanged and show the format requirement.

The Web Share permission boundaries guide covers a related user-initiated capability. Its useful lesson is the same: a fallback is part of the normal contract, not a hidden attempt to circumvent browser policy. Keep the copy or paste alternative visible from the first render.

Handle Text And Rich Clipboard Formats

Text-only flows are easier to explain because the application can set a length and character policy before writing. Trim only when the task says whitespace is irrelevant; otherwise preserve the selected text exactly. For a code field, validate an expected shape such as AB-1234 after reading and reject extra lines without logging the rejected clipboard data. A successful format check means the value fits this field, not that it is authentic or safe for another service.

Rich clipboard operations need a narrower contract. ClipboardItem can expose multiple representations, such as text/plain and text/html, and an application should request or write only the types it needs. Sanitize HTML before inserting it into the document; do not treat the browser's representation as trusted markup. Keep an explicit maximum such as 256 KiB for a fixture and reject unexpected MIME types before parsing. The specification defines the interface, but it does not make application HTML safe or prove that a producer is trustworthy.

Do not silently downgrade a rich read into an arbitrary text import. Tell the person which representation will be used, show a preview when content is complex, and provide an undo or clear action. If text/html is unavailable, the product can offer text/plain with a visible loss-of-formatting note. If the item contains an image, keep the decoding and storage limits in the application contract rather than assuming that a resolved read() promise makes the image harmless.

For writes, set the plain-text representation whenever it is a valid fallback. A copy button that writes only HTML can leave keyboard users or terminal workflows with nothing useful. A simple fixture can express the intended surface:

const value = selectedValue;
const result = { operation: 'write', fixtureId: 'clip-17', state: 'requested' };

if (!globalThis.isSecureContext || !navigator.clipboard?.writeText) {
  result.state = 'unsupported';
} else {
  try {
    await navigator.clipboard.writeText(value);
    result.state = 'write-success';
  } catch (error) {
    result.state = error?.name === 'NotAllowedError' ? 'write-denied' : 'write-failed';
  }
}

The record deliberately excludes value. A test can assert the visible status and field behavior with synthetic clip-17 data without retaining clipboard content. Keep MIME names, limits, and identifiers identical when translating this fixture so another reviewer can compare the same contract.

Keep Fallback And Focus Visible

Progressive enhancement should leave the task usable when the Clipboard API is absent or rejected. A copy action can select a readonly <input> and expose a keyboard-copy instruction. A paste action can leave the field editable so the person can use the operating system shortcut. A rich import can accept a file upload or plain text. These paths must be reachable without opening a permission prompt again.

Status feedback is part of correctness. Announce write-success, read-denied, or unsupported in a live region, move focus to the next meaningful control after a successful action, and return focus to the source control when the request fails. Do not disable the only usable field while a promise is pending. A retry should require a fresh click and should not replay a stale value after navigation or account change.

Keyboard and assistive-technology paths need the same intent boundary as pointer input. A keypress that activates a labelled button is a user action; a page-load effect is not. Keep the accessible name specific, avoid “Continue” for a clipboard operation, and say whether the result is copied, inserted, or merely available for manual selection. Test zoom, high contrast, screen readers, and long localized labels because a status that is clipped can turn a successful write into an ambiguous one.

Embedding changes the fallback decision. A cross-origin frame may face a Permissions Policy or focus boundary even when the top-level page is secure. The frame should explain which owner can fix the problem and offer a first-party handoff only when the application already has one. Never put clipboard text into a query string to move it between frames; pass a short-lived server-authorized reference or ask the person to use the visible field.

Record Outcomes Without Collecting Secrets

Clipboard telemetry should answer “which branch did the product take?” rather than “what was in the clipboard?” An allowlist can include fixtureId, operation, state, mimeType, browserVersion, context, and fallback. It should exclude the text, HTML, image bytes, account identifiers, and full URLs. A read-denied row is useful for support; a copied password is not.

Keep browser and application ownership separate. The browser decides whether the request is exposed and may reject it. The page decides how to validate and display the result. A server may acknowledge a submitted value, but that acknowledgement does not prove that the browser wrote or read the clipboard. Record those stages separately so a timeout or late response cannot overwrite a newer clip-17 attempt.

Permission state is not a safe fingerprint. Browser release, profile choice, focus, policy, user action, and operating-system integration can all change the result. Do not combine clipboard availability with fonts, device lists, or unrelated permission states to create a risk score. The secure-contexts guide gives the broader rule: capability checks should serve a declared function and a bounded review, not identify a person or device.

Retention should be short and explicit. Keep a synthetic fixture record long enough to compare a release, then aggregate the state or delete it according to the application's policy. When a user asks for support, request the smallest redacted identifier that locates the stage. Never ask for a screenshot of private clipboard contents, a complete browser profile, or an unredacted event record.

Verify Behavior With A Bounded Fixture

Use one owned page and one synthetic value to exercise the full state matrix. Start with clip-17, a visible copy button, an editable paste field, and a status live region. Run the fixture in a secure context, then repeat with the API method removed, with a rejected promise, and with the fallback selected. Keep browserVersion, viewport, origin, and fixtureRevision beside the result. The comparison asks which declared field changed; it does not claim that every browser or operating system will behave identically.

The web.dev asynchronous Clipboard guide is useful for progressive enhancement patterns, while the W3C and MDN references define the semantics and browser surface. Recheck all three before changing support language. Do not use an old Chrome announcement or a broken Chrome URL as evidence; the public source set for this topic is the W3C specification, MDN reference, and web.dev guide.

An audit row can remain compact:

{
  "fixtureId": "clip-17",
  "operation": "write",
  "state": "write-success",
  "fallback": "none",
  "mimeType": "text/plain",
  "browserVersion": "156.0",
  "viewport": "1280x800"
}

The row records a browser-facing outcome, not a proof that a person pasted the value. If the first difference is unsupported, inspect secure context and feature detection. If it is write-denied, inspect activation, focus, policy, and the user's decision. If the visible status is wrong while the browser promise resolves, inspect the page state machine and live-region update. Stop at the first meaningful difference instead of collecting clipboard text.

BotBrowser can replay this declared synthetic journey in a controlled context and preserve the profile and viewport inputs used for comparison. It cannot read a real user's clipboard, manufacture a system paste, grant a permission prompt, or certify that a remote application accepted the value. Keep the final decision scoped to the fixture, release, origin, and visible result that were actually observed.

The fixture should exercise ownership transitions as well as happy paths. Start with a fresh route and mark intent-recorded before the click handler schedules any promise. If the user navigates while writeText() is pending, abort the page-owned update and mark the old attempt cancelled; a late resolution must not announce success on the new route. If focus leaves the destination field before readText() begins, keep the request unstarted and return focus to the control that still explains the action.

Run the same matrix with a clean profile and a returning profile, but keep the profile purpose in the record rather than retaining its contents. The clean case checks first-use context and the returning case checks that a remembered decision does not remove the visible explanation. Add one embedded case with a declared Permissions-Policy value and one top-level case with the same synthetic text. A difference between those rows belongs to context ownership, not to a claim that the text or user changed.

Accessibility review should assert the visible contract in every branch. For write-success, the live region should announce the operation and focus should remain near the copied value. For read-denied, the message should name the browser decision and expose the editable field. For unsupported, the field and keyboard instruction should be usable without a second attempt. Capture only boolean assertions such as statusVisible: true or fallbackReachable: true; do not serialize the text that the fixture used.

When a release changes the first branch, update the support note with the exact context and operation. “Clipboard works” is too broad to diagnose a missing write, a denied read, a rich-format rejection, or a focus race. A useful note says operation: readText(), context: embedded, state: read-denied, fallback: manual-paste, and fixtureRevision: 3. That bounded record directs a reviewer to one owned interaction and excludes unrelated browser inventory.

Public Sources

• Clipboard API, W3C
• Clipboard API, MDN
• Async Clipboard, web.dev
• BotBrowser automation consistency

Practical conclusion

Ask for a visible clipboard action, separate write and read decisions, validate formats before use, and keep a selectable fallback on screen. Record only the operation state and declared context; never turn clipboard contents or permission results into identity signals. BotBrowser can repeat an authorized synthetic flow, but the browser, the user, the page, and any server each retain their own boundary.