Verify private access for browser agents
How can an agent prove that the intended recipients can use a private preview and an unrelated device cannot?
Call a qURL™ preview verified only when separate checks pass: the app answers locally, qurl grants shows it private with the intended device keys, an unrelated qURL identity gets “Resource Not Found”, each recipient opens its own link in its own browser and sees this run’s marker, and cleanup is confirmed. A publish, a valid JSON document or one working browser proves only its own step.
Checked against the qURL CLI source of 3.6.1 and 3.7.1. The denial and revoked answers were reproduced with both releases. The browser steps follow the documented session behaviour and were not run for this page: no browser, Playwright or hosted-browser run backs them. Verified .
Define the test before you run it
Put a marker that is unique to this run in the app, such as a heading with a random word, and one small interaction whose result you can see, such as a button that changes a line of text. Write down the target address, the owner’s state directory, each intended recipient’s device public key, and the CRID once it exists.
Browser automation such as Playwright, and hosted browsers such as Browserbase, are where the recipients run here. They are not part of qURL, and this page has not been run in them.
Report each result on its own
Each check below shows one thing. Report every result separately, with the release and the environment it ran in, so a reader can see which one failed.
| Result | Passes when | Does not show |
|---|---|---|
| Local readiness | The app answers on its address with the marker | Anything about qURL |
| Publication | publish exits 0, and status reads on and serving | Who may open it |
| Authorization | grants: private is true, and each intended key is in allowed_device_keys | That a browser can use it |
| Denial | An unrelated identity’s qurl share exits 5 with Resource Not Found (HTTP 404) | That browser sessions are kept apart |
| Authorized access | Each recipient’s browser shows the marker | That the other recipients can |
| Interaction | The interaction works in each browser | That the session outlasts the test |
| Cleanup | delete prints deleted true, then share exits 5 with Resource Revoked (HTTP 400) | That links or sessions issued earlier stopped working |
Run the checks
Check the app without qURL
Ask the app directly first, so an app that failed to start is not mistaken for an access problem later.
[ -n "$MARKER" ] && response=$(curl -fsS http://127.0.0.1:3000) && printf '%s\n' "$response" | grep -qF -- "$MARKER" && echo "local: ok"Check the grants as the owner
Run this with the owner’s state. It passes only when the resource is private and both intended keys are on its list; add one any() for each further recipient.
qurl grants "$CRID" -o json | jq -e --arg a "$KEY_A" --arg b "$KEY_B" \ '.private == true and any(.allowed_device_keys[]; . == $a) and any(.allowed_device_keys[]; . == $b)' >/dev/null && echo "authorization: ok"Check that an unrelated device is denied
Use an identity that was never allowed: a fresh state directory gives you one. It shows that the service refuses a device that is not on the list. It does not test browsers, and the fresh identity owns nothing, so its directory can be removed afterwards.
( stranger=$(mktemp -d) || exit 1 trap 'rm -rf "$stranger"' EXIT err="$stranger/share.err" code=0 QURL_CONNECTOR_STATE_DIR="$stranger/state" qurl share "$CRID" --ttl 1m >/dev/null 2>"$err" || code=$? [ "$code" -eq 5 ] && grep -q 'Resource Not Found (HTTP 404)' "$err" && echo "denial: ok" )Mint one link for each recipient
Each allowed recipient runs qurl share with its own state, so each link is its own. A one-time link opens once: don’t open it, and don’t let a link-preview scanner see it, before the recipient’s browser does. A plain HTTP fetch cannot use it, because the credential sits after the # and is never sent, so a fetch is no health check either.
link=$(qurl share "$CRID" --ttl 15m -o json | jq -er 'select(.single_use == true) | .qurl')Open each link in its own browser context
Use a browser: a new Playwright browser context, or a new hosted-browser session, for each recipient. Check the marker and do the interaction in each. An HTTP client or a fetch tool gets the opener page instead of the app.
Keep each session for the test
A session belongs to the browser that opened the link, through that browser’s cookies. Keep the same context for the whole test: a new context, or cleared cookies, needs a new link. The session lasts 1 hour by default; qurl share --session-duration changes that. A script that opens a link with the qURL Go SDK is a different path: it is admitted by its network address, so don’t use it as evidence for a browser recipient.
Clean up and record the result
After asking the user, delete the resource with the owner’s state and confirm it. Stop the publish process and remove the recipients’ test state once nothing needs it. Record the releases, the commands, the exit codes and the sanitized outputs, never a link or a state directory. A refused share shows that no new link can be made. If your report says that open sessions ended, reload each recipient’s page after the delete and record what it showed.
( err=$(mktemp) || exit 1 trap 'rm -f "$err"' EXIT qurl delete "$CRID" --yes -o json | jq -e --arg c "$CRID" '.id == $c and .deleted == true' >/dev/null && { code=0; qurl share "$CRID" --ttl 1m >/dev/null 2>"$err" || code=$?; [ "$code" -eq 5 ]; } && grep -q 'Resource Revoked (HTTP 400)' "$err" && echo "cleanup: ok" )
Frequently Asked Questions
Is a working publish enough to call a private preview done?
No. A publish shows that the resource exists, and status shows that it is serving. Neither shows who may open it, that a recipient can use it in a browser, or that a stranger is refused.
Why not curl the access link to check it?
An HTTP client never sends the part of the URL after #, where the credential is, so it gets the opener page instead of the app. The check tells you nothing, and a browser-capable scanner could use up a one-time link instead.
Does an unrelated device’s denial prove browser isolation?
No. It shows that the service refuses a qURL identity that is not on the list. That a browser session cannot be used from another browser is a separate claim; test it in the browsers themselves if you report it.
Can two browser contexts share one link?
No. A one-time link starts one session, for the first browser that opens it. Mint a link for each recipient.
Was this tested with Playwright or Browserbase?
No. The browser steps are a generic recipe reviewed against qURL’s documented behaviour. Label your own result tested only for the environment you actually ran.
Give your agent the qURL skill
One file teaches a coding agent to publish an app privately, let people and other agents in, and recover when the CLI stops it. No account, no API key.