Put a human-controlled boundary around in-page agent tools.

01 · Install

Quick start

Today, PageCTRL ships as one dependency-free browser file. Self-host that reviewed file and load it before any script that registers WebMCP tools.

<script src="/pagecontrol.js"></script>
<script type="module">
  const guard = window.PageControl;

  await guard.init({
    appName: "My Store",
    budget: { limit: 300, currency: "USD" },
    defaultMode: "allow",
    defaultMaxPerMinute: 30,
    tools: {
      add_to_cart: { maxAmount: 200, maxQty: 5 },
      checkout: { mode: "approve", chargesBudget: true },
      delete_account: { mode: "deny" },
    },
  });

  // Register tools through PageControl, then lock the reviewed surface.
  await guard.registerTool(myTool);
  guard.seal();
</script>

02 · Configure

Keep credentials on the server

The browser SDK needs no secret. Signed checkout adds two server environments: the merchant app and the separate PageCTRL signing service. Create two different random secrets with openssl rand -base64 32.

Merchant app

Add these values to the repository-root .env.local file for local work, or to the merchant app's Vercel environment for deployment.

# Merchant app — .env.local or Vercel
PAGECONTROL_API_URL=https://api.pagecontrol.app
PAGECONTROL_SERVICE_TOKEN=PASTE_THE_SHARED_RANDOM_SECRET
PAGECONTROL_DASHBOARD_SESSION_SECRET=PASTE_A_DIFFERENT_RANDOM_SECRET

Signing service

Add these values to the Render service environment. The PAGECONTROL_SERVICE_TOKEN value must match the merchant app exactly. The dashboard session secret does not belong in Render. Generate the Ed25519 key with openssl genpkey -algorithm ED25519 -outform DER | base64 and paste its output directly into Render.

# Signing service — Render
PAGECONTROL_SERVICE_TOKEN=PASTE_THE_SHARED_RANDOM_SECRET
PAGECONTROL_PRIVATE_KEY=PASTE_THE_ED25519_PRIVATE_KEY
PAGECONTROL_ALLOWED_ORIGINS=https://your-store.example
PAGECONTROL_ISSUER=https://api.pagecontrol.app

Public verification key

You do not copy a public key into the script or .env. Render derives it from PAGECONTROL_PRIVATE_KEY and publishes it as a public JWK. The merchant server downloads it automatically from PAGECONTROL_API_URLwhile verifying a grant.

• Open the PageCTRL public JWKSafe to inspect and share. It verifies signatures but cannot create them.

• Vercel environment variablesWhere to store the merchant app values and apply them to a deployment.
• Render environment variablesWhere to store the signing token, private key, and allowed origins.
• Merchant dashboardSee the two environments side by side without exposing production secrets.

03 · Understand

One guarded execution path

When native WebMCP exists, PageCTRL registers wrapped tools with document.modelContext. It mirrors the active context to navigator.modelContext for older clients.

1. 1
   Validate

   Reject malformed inputs before merchant code runs.

2. 2
   Enforce

   Resolve modes, rate limits, quantities, amounts, and reserved budget.

3. 3
   Ask

   Keep sensitive calls pending until a person allows or blocks them.

4. 4
   Record

   Redact sensitive strings and append a hash-linked journey entry.

If native WebMCP arrives after page load, PageCTRL watches for 10 seconds and migrates already-guarded tools. Without native support, the same pipeline remains available through its demo shim.

04 · Align

One guard, two beneficiaries

PageCTRL faces both directions. It gives people the confidence to delegate a task, while giving merchants a controlled WebMCP surface instead of unrestricted automation.

05 · Register

Register a guarded tool

A tool uses the normal WebMCP definition. The optional label and guard fields stay inside PageCTRL and are removed before native registration.

await PageControl.registerTool({
  name: "add_to_cart",
  label: "Add to cart",
  description: "Add one catalog item to the cart.",
  inputSchema: {
    type: "object",
    properties: {
      id: { type: "string", minLength: 1 },
      qty: { type: "integer", minimum: 1 },
    },
    required: ["id", "qty"],
  },
  annotations: { readOnlyHint: false },
  guard: {
    getQty: ({ qty }) => qty,
    getCost: ({ id, qty }) => catalog[id].price * qty,
  },
  execute: async ({ id, qty }, { signal }) => {
    return JSON.stringify(await cart.add(id, qty, { signal }));
  },
});

06 · Control

Layer merchant and user policy

The merchant sets the minimum protection. A user can make it stricter immediately. Moving back toward the merchant setting requires explicit confirmation.

// Tightening a rule applies immediately.
PageControl.setUserPolicy("checkout", { mode: "deny" });

// Reducing a user-added restriction requires an explicit human confirmation.
PageControl.setUserPolicy(
  "checkout",
  { mode: "approve" },
  { humanConfirmed: true },
);

07 · Decide

Use the built-in human approval UI

PageCTRL renders its own keyboard-accessible approval dialog with Run once and Block actions. Unanswered requests deny themselves after 60 seconds. Pausing the guard denies every pending request.

The dialog needs no merchant UI code. Public events contain an opaque display handle, never the internal approval id. After seal(), only a browser-trusted click in PageCTRL's controls can resolve the request.

const stop = PageControl.on("approval", ({ pending }) => {
  // Handles are display-only. They cannot settle an approval.
  renderPendingApprovals(pending);
});

// Unsubscribe when your UI unmounts.
stop();

08 · Reference

Client API

09 · Observe

Events

PageControl.on(event, callback) returns an unsubscribe function.

10 · Scope

Protect the action layer, not the whole internet

PageCTRL sees structured WebMCP calls inside the page. It does not sit on the network path, so it cannot see ordinary crawlers, DDoS traffic, or direct server attacks.

11 · Verify

Trust and privacy boundary

Production distribution

This repository does not claim a live PageCTRL CDN. For production distribution, publish an immutable versioned asset and provide its real Subresource Integrity hash. The browser then rejects any changed file, including one served by a compromised CDN.

<script
  src="https://your-cdn.example/pagecontrol/v1.0.0/pagecontrol.js"
  integrity="sha384-YOUR_RELEASE_HASH"
  crossorigin="anonymous">
</script>

HTTPS authenticates the named origin. Subresource Integrity verifies the exact release bytes. Neither stops a malicious merchant from omitting the SDK or drawing a lookalike interface.

The approval component today

The SDK creates the approval dialog, styles it, traps keyboard focus, runs the countdown, and wires the decision. The merchant writes no approval component. Today that dialog still lives in the merchant page, so same-page scripts can inspect or imitate it.

12 · Extend

Roadmap: move trust outside the host page

These are deliberate next layers, not claims about the current release. Each one reduces merchant integration work or moves a trust decision into a stronger browser boundary.

1. 1
   Versioned distribution

   Publish immutable releases from a PageCTRL origin with a real SRI hash and CORS headers.

2. 2
   Placement Web Component

   Add an <page-control-panel> custom element for layout only. The boot script must still load first so no tool registration escapes the guard.

3. 3
   Cross-origin approval frame

   Serve the sensitive decision UI from a PageCTRL origin. The browser same-origin policy then prevents the host page from reading its internal DOM.

4. 4
   Independent verification

   A companion extension can warn when a site claims protection without loading the genuine release.

5. 5
   Browser-owned prompt

   Long term, the browser should own the unforgeable approval surface while PageCTRL supplies policy decisions.

<!-- Roadmap sketch — not available in v1.0.0. -->
<script
  src="https://your-cdn.example/pagecontrol/v1.0.0/pagecontrol.js"
  data-budget="300"
  data-currency="USD">
</script>

<page-control-panel></page-control-panel>

Architecture references

• Stripe Web ElementsSensitive fields are tokenized inside hosted Elements instead of touching the merchant server.
• MDN: Same-origin policyExplains the browser boundary that restricts cross-origin frame access.
• MDN: Custom elementsDefines the standards-based path to an <page-control-panel> placement API.
• Cloudflare bot solutionsShows why scraping and request-level bot control belong at the edge, outside PageCTRL.