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

Hosted authority for protected actions

Every protected browser action should use hosted, live Gate verification.

Local verification is only the explicit DEADMAN incident tier and bounded legacy

compatibility. The browser never calls locked /validate with server credentials.

npm install /absolute/path/to/mandate-integration-kit-v0.4.0/package

Express: Observe, then enforce one route

import { mandateHosted } from "@mandate-security/node/express";

app.post("/api/checkout",
  mandateHosted({
    siteSecret: process.env.MANDATE_SITE_SECRET,
    siteKey: process.env.MANDATE_SITE_KEY,
    apiKey: process.env.MANDATE_API_KEY,
    gateUrl: process.env.MANDATE_GATE_URL,
    credentialMode: "cookie",
    credentialCookieName: "Mndt-Sess",
    highValue: true,
    origin: "https://app.example.com",
    mode: "observe",
    onDecision: decision => console.log({ success: decision.success, action: decision.action }),
  }),
  checkoutHandler,
);

Authenticate the user in your normal middleware. Trusted account identifiers

must come from that authentication, never a browser X-Account-Key header.

When the route is ready, set mode: "enforce". The hosted adapter maps allowed,

denied and configured escalation outcomes before calling the business handler;

it preserves authenticated session/purpose cookies and companion/native updates.

Do not log opaque credentials, full request bodies or private failure reasons.

Managed wrappers

The unpublished candidate adds mandateManagedMiddleware (Express), withMandateManaged

(Next), Go ManagedMiddleware, and Python managed Flask/FastAPI wrappers.

They resolve and validate in one operation using the app/environment-scoped

CLI connection. Verify defaults on; Limit is explicit, with trusted Subject when

configured. Default policy remains Observe. Off/unmatched proceed; invalid or

unavailable authority returns an error. Native enforced replies require an

independently commissioned profile; a caller callback cannot authorize one.

Do not call hosted validation a second time after a managed decision.

Transport and responses

Production browser credentials stay in an HttpOnly cookie. The repository

reader prefers _mndt and accepts legacy Mndt-Sess only when unambiguous;

the currently deployed writer uses Mndt-Sess. Match the live collector/Gate

configuration. Manual hosted helpers support credentialMode: "cookie" and

credentialCookieName: "Mndt-Sess" or "_mndt"; never rename a cookie without a

coordinated writer/reader rollout. Request proof uses x-md-vq, with legacy

x-mndt-req accepted. x-md-w, x-md-h and md_<seed> purpose cookies are

opaque, authenticated transport. Preserve SDK response updates and application

cookies. Do not copy credentials into page storage or logs.

Hosted results keep score null; branch on documented success and action.

The legacy human alias is not proof of human identity. Use generic public errors;

keep diagnostic reasons server-side. In enforce mode hosted throttle maps to

429 with Retry-After; queue to 202 with opaque queueToken; fresh_proof to 401;

step_up to 403 with a customer-owned attempt; block to 403. Native policy

denied/challenge return generic 403 and never forward the business action.

A customer queue retry is an explicit new application request after the indicated

wait, carrying its opaque queue token. SDKs never automatically replay checkout.

See Recipes for complete framework patterns.