Skip to main content
← For agents

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.

Checks for a private qURL preview, and what each one shows
ResultPasses whenDoes not show
Local readinessThe app answers on its address with the markerAnything about qURL
Publicationpublish exits 0, and status reads on and servingWho may open it
Authorizationgrants: private is true, and each intended key is in allowed_device_keysThat a browser can use it
DenialAn unrelated identity’s qurl share exits 5 with Resource Not Found (HTTP 404)That browser sessions are kept apart
Authorized accessEach recipient’s browser shows the markerThat the other recipients can
InteractionThe interaction works in each browserThat the session outlasts the test
Cleanupdelete prints deleted true, then share exits 5 with Resource Revoked (HTTP 400)That links or sessions issued earlier stopped working

Run the checks

  1. 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"
  2. 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"
  3. 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"
    )
  4. 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')
  5. 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.

  6. 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.

  7. 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.

Read the skill →

Book a pilot

Tell us what to hide. We’ll scope a pilot.

Enterprise starts with a paid pilot on one application, typically 60 to 90 days, credited in full toward year one if you convert within 60 days. After that, an annual package sized to what you protect, not per seat.