Frontend Integration

Start in Observe on one route. Use the deployment URL and installed package version supplied for your workspace. Historical host examples and source capabilities do not establish a live service or published release.

Installation

Add the MANDATE script to your HTML:

<script async src="https://gate.x-lock.dev/g.js?k=YOUR_SITE_KEY"></script>

Script Parameters

Same-Origin Collector Alias

High-value deployments can route collector traffic through the customer app or edge hostname instead of exposing gate collector paths directly in browser network logs. Configure the site key with a dedicated collector alias:

{
  "collector": {
    "origin": "https://app.example.com",
    "path_prefix": "/__mndt",
    "proxy_metadata": {
      "mode": "monitor",
      "scope": "customer_alias",
      "kill_switch": false
    }
  }
}

Then proxy the bundle-selected app routes to the matching gate route without rewriting the body. Gate-owned non-alias routes use a daily rotated /rx/<daily>/... prefix by default, while customer alias paths keep your configured stable prefix and proxy to the stable selected gate route:

Keep the prefix dedicated to MANDATE, forward normal request metadata such as User-Agent, Origin, Referer, and X-Forwarded-*, and do not expose proxied collector payloads to page scripts.

For production aliases, sign the proxy metadata so MANDATE can distinguish a real customer proxy from a browser that spoofed X-Mndt-Collector-Path. The proxy should preserve the encrypted request body and add only bounded routing metadata:

import { createHash, createHmac } from "node:crypto";

function signingSecret(siteSecret) {
  const hash = createHash("sha256").update(siteSecret).digest("hex");
  return Buffer.from(`mandate-token-v1:${hash}`, "utf8");
}

function proxySignature({ method, gatePath, collectorPath, timestamp, proxyId, siteSecret }) {
  const base = ["v1", method.toUpperCase(), gatePath, collectorPath, timestamp, proxyId].join("\n");
  return `sha256=${createHmac("sha256", signingSecret(siteSecret)).update(base).digest("hex")}`;
}

function requestShapeSignature({ method, gatePath, protocol, h2Settings, headerOrder, timestamp, siteSecret }) {
  const base = ["v1", method.toUpperCase(), gatePath, protocol || "", h2Settings || "", headerOrder || "", timestamp].join("\n");
  return `sha256=${createHmac("sha256", signingSecret(siteSecret)).update(base).digest("hex")}`;
}

Forward these headers with the proxied collector request:

The gate verifies this metadata for dashboard health reporting by default. Customer Integrations and staff Operations show whether recent customer-alias traffic is ready for a stricter requirement. To link enforcement, the site must set collector.proxy_metadata.mode to enforce and MANDATE operations must set MANDATE_PROXY_METADATA_ENFORCEMENT=true; either MANDATE_PROXY_METADATA_KILL_SWITCH=true or site-level collector.proxy_metadata.kill_switch=true returns the deployment to report-only. Once linked, collector verify/delta traffic for that site must carry valid signed proxy metadata, so direct unsigned calls to canonical /v or /v/delta are blocked instead of treated as fallback traffic. MANDATE still decrypts, scores, and enforces policy on the gate; customer proxy code should not inspect collector payloads or make allow/block decisions.

Token Delivery

MANDATE keeps verification tokens private to the browser-verification runtime by default. Public g.js does not create a token meta tag, dispatch a token event, or expose a stable global token getter.

The production frontend contract is first-party credential attachment: after verification through a customer alias, the gate sets the HttpOnly _mndt credential and same-origin protected requests carry it automatically. The legacy Mndt-Sess name remains accepted. This baseline is in-repository and undeployed; the page does not receive raw token material.

The runtime may also attach x-md-vq plus x-md-w/x-md-h. Backend SDKs

forward the latter as work_proof/integrity_proof, and app code does nothing.

After hosted validation, API responses may rotate HttpOnly md_<seed> purpose

cookies through the SDK; app code does nothing.

In non-production header or dual compatibility mode, the client can automatically add the opaque X-Mndt header to same-origin fetch requests and same-origin non-GET/HEAD XMLHttpRequest requests. Same-origin requests made before verification completes are held until the proof is ready.

await fetch("/api/action", {
  method: "POST",
  body: JSON.stringify({ intent: "submit" }),
});

Production protected routes enforce the cookie credential. Header-mode compatibility backends read and verify:

X-Mndt: <opaque-token>

Legacy Compatibility Bridge

The old page-visible bridge can be restored only outside production for migration shims or trusted diagnostics with MANDATE_TOKEN_BRIDGE=legacy or MANDATE_TOKEN_BRIDGE=diagnostic on the gate. In that mode, g.js publishes meta[name="mndt-token"] and mandate:token events for compatibility.

CAPTCHA migration shims (/compat/*) require the legacy bridge while they are in use. They never scrape polymorphic g.js internals.

SPA Integration

import { useEffect, useState } from "react";

function App() {
  const [ready, setReady] = useState(false);

  useEffect(() => {
    const script = document.createElement("script");
    script.src = "https://gate.x-lock.dev/g.js?k=YOUR_SITE_KEY";
    script.async = true;
    script.onload = () => setReady(true);
    document.head.appendChild(script);

    return () => {
      document.head.removeChild(script);
    };
  }, []);

  async function handleSubmit() {
    await fetch("/api/action", { method: "POST" });
  }

  return <button onClick={handleSubmit} disabled={!ready}>Submit</button>;
}

<script setup>
import { ref, onMounted, onUnmounted } from "vue";

const ready = ref(false);
let scriptEl;

onMounted(() => {
  scriptEl = document.createElement("script");
  scriptEl.src = "https://gate.x-lock.dev/g.js?k=YOUR_SITE_KEY";
  scriptEl.async = true;
  scriptEl.onload = () => (ready.value = true);
  document.head.appendChild(scriptEl);
});

onUnmounted(() => {
  if (scriptEl) document.head.removeChild(scriptEl);
});

async function handleSubmit() {
  await fetch("/api/action", { method: "POST" });
}
</script>

<template>
  <button @click="handleSubmit" :disabled="!ready">Submit</button>
</template>

"use client";

import Script from "next/script";

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <>
      <Script
        src="https://gate.x-lock.dev/g.js?k=YOUR_SITE_KEY"
        strategy="afterInteractive"
      />
      {children}
    </>
  );
}

Content Security Policy

If your site uses a Content Security Policy, add the following directives:

script-src 'self' 'wasm-unsafe-eval' https://gate.x-lock.dev;
connect-src 'self' https://gate.x-lock.dev;
worker-src 'self' blob:;

If you use a same-origin collector alias, keep https://gate.x-lock.dev in script-src for /g.js; collector connect-src can stay on 'self' when /__mndt/* is served by the app origin.

Token Lifecycle

• Tokens are issued after successful background verification
• TTL: 15 minutes from issuance
• The script automatically refreshes tokens before expiry on long-lived pages
• Tokens are single-use (recommended server-side enforcement)

Troubleshooting