The Node SDK

@id-partners/authzen-pep is the enforcement point for when there is no gateway: an AuthZEN client, Express middleware, an MCP guard, and a federation entity, in one package with no runtime dependencies. Every setting is an option in code; this page lists all of them with their defaults, then gives complete programs.

Install

npm install @id-partners/authzen-pep

import { AuthzenClient, FederationEntity } from '@id-partners/authzen-pep';
import { authzenMiddleware, pathMapper } from '@id-partners/authzen-pep/express';
import { McpGuard } from '@id-partners/authzen-pep/mcp';

Node 22 or later. ESM only: there is no CommonJS build. Types ship with the package, and so does the source its maps point at.

Until a version is on npm, install the package attached to its GitHub release: npm install ./id-partners-authzen-pep-<version>.tgz.

Upgrading to 0.4.0

0.4.0 closes every way the SDK had of letting a request through that no PDP judged. A configuration that would trust something nobody checked now refuses to start; allowInsecure: true is the escape hatch everywhere, for demos and development, and it says so once at startup.

AuthzenClient

new AuthzenClient(options). The client is the one thing every other piece is built on; the middleware and the guard accept either a client or these options.

Methods: evaluate(request, options), evaluateAll(batch, options) (a boxcar, folded to one verdict, first deny wins so its advice survives; an empty batch is refused before it is sent), evaluations, searchSubject, searchResource. The PDP POST never follows a redirect and refuses an answer over 1 MiB.

Discovery options

discovery: { … } on the client, or new PdpDiscovery({ staticPdp, … }) directly. The rules are the Go PEP's: the resource's echoed resource must be byte-identical, the PDP's policy_decision_point must equal the identifier it was fetched from, a PDP without metadata gets the default paths, a batch is never sent to a PDP that advertises no access_evaluations_endpoint, and a URL outside an allowlist never falls through to a weaker source.

Per-call options

EvaluateOptions, the second argument of evaluate and evaluateAll. The middleware and the guard fill these from the request.

Whatever document named the PDP is forwarded verbatim as context.resource_metadata with context.resource_metadata_source. Those two, request and access_token are the PEP's: the same keys in a mapped or supplied context, at the top level or in a boxcar entry, are removed, and only what the PEP forwards is sent. The SDK enforces none of it.

What a PDP call can end in

Four outcomes, and a fail-open layer may skip only one of them.

Express middleware

authzenMiddleware(options). On permit the request continues and req.authz carries { claims, verdict, request }. On deny nothing downstream runs and the response is the challenge. An error thrown downstream after a permit is the router's, not a PEP failure.

pathMapper(rules, { fallthrough, caseSensitive, subjectType }) builds a map from route rules: { method, pattern, action, resourceType, resourceId?, resourceProperties?, context? }. Patterns take :name segments and * for any number of segments. It matches the way Express routes: segment by segment, each percent-decoded after the split, case-insensitively unless caseSensitive, one trailing slash tolerated, the query ignored, and a GET rule answers HEAD. A path that cannot be decoded is a mapping error. An unmatched route is a deny; pass fallthrough: 'allow' only for paths that carry no policy.

McpGuard

new McpGuard(options), then checkToolCall({ rpc?, claims?, raw?, accessToken?, extraContext? }) or guard.wrap(handler). Every MCP method is governed; unknown methods are denied so future ones fail closed. checkToolCall never throws.

A check takes the parsed message as rpc, the untouched request as raw: { method?, path?, headers, body } (body as a string or as bytes), or both, in which case they must agree. claims are yours to verify: the guard never decodes a token. The guard refuses, without asking the PDP, anything that is not one JSON-RPC request or response object: a batch, a non-string method, a tools/call without a string params.name, an object at any depth holding two member names a case-insensitive parser reads as one (Go's rule: Unicode simple case folding, so Amount beside amount in the arguments counts), and nesting deeper than 64 — exactly as coaz-pep refuses them. Given raw it also refuses a Content-Encoding other than identity (415), a byte-order mark, invalid UTF-8, trailing data, anything that is not JSON, and a member named twice at any depth. A JSON-RPC response — a client answering the server — passes through.

The server-scoped defaults (tools/list, initialize and friends) name this server from the token's aud. An array aud is narrowed to this server's own identifier, or to its only entry; one the guard cannot choose from, or no aud at all, is a -32602. A declared subject.id or resource.id that resolves absent is a -32602 in both dialects.

FederationEntity

new FederationEntity(options) holds a private key and serves the two documents a federated resource publishes: a minimal entity configuration (keys, authorityHints, the entity type; no policy, the controller maintains that) for a trust controller to onboard, and RFC 9728 metadata with signed_metadata.

Methods: publicJwk() (with an RFC 7638 thumbprint as kid), paths() ({ federation, resource } for this identifier), configuration(), protectedResourceMetadata() (a copy each call), and handler(), an Express-style middleware that serves both paths and passes everything else to next.

Verdicts and challenges

A verdict is { allow, kind, reason, detail?, context?, request?, failedOpen? }. reason is safe to show the caller: a PDP's own reason for a policy decision, or a fixed phrase for a failure. detail is what happened — which PDP, which status, which error — for logs, and never goes in a response. failedOpen lists the identifiers of the skipped layers. When the PDP's decision context says how a deny can be resolved, the SDK renders it three consistent ways, the same as the gateways:

pdp_error is 502 on purpose: the PDP being down is our problem, and a 403 would send the caller chasing permissions they already have. Header values built from PDP data lose CR, LF and anything outside printable Latin-1, and are quoted-string escaped inside WWW-Authenticate, so a policy reason can neither forge a header nor make Node refuse one.

Complete samples

A REST API: verified tokens, discovery, layers, the federation face

import express from 'express';
import { readFileSync } from 'node:fs';
import { jwtVerify, createRemoteJWKSet } from 'jose';
import { AuthzenClient, FederationEntity } from '@id-partners/authzen-pep';
import { authzenMiddleware, pathMapper } from '@id-partners/authzen-pep/express';

const app = express();
app.use(express.json());
const jwks = createRemoteJWKSet(new URL('https://as.bank.example/jwks'));

const client = new AuthzenClient({
  url: process.env.AUTHZEN_URL!,                 // the static PDP, always permitted
  apiKey: process.env.AUTHZEN_API_KEY,           // bound to url; a discovered PDP never receives it
  discovery: {
    mode: 'resource',
    pdpAllowlist: ['https://pdp.bank.example', 'https://estate-pdp.bank.example'],
    resourceAllowlist: ['https://api.bank.example'],
    ttlMs: 300_000,
  },
  layers: ['https://estate-pdp.bank.example fail-open', 'resource'],
  failMode: 'closed',
  timeoutMs: 1500,
  onTrace: (t) => log.debug(t),                // t.outcome: permit, deny, refusal or unavailable
});

// The resource's federation face: this service holds the key; the controller holds the policy.
const entity = new FederationEntity({
  entityId: 'https://api.bank.example',
  key: JSON.parse(readFileSync('/etc/bank-api/entity-key.json', 'utf8')),
  authorityHints: ['https://federation.example'],
  asserted: { authzen_policy_decision_points: [process.env.AUTHZEN_URL!] },
});
app.use(entity.handler());                       // /.well-known/openid-federation, /.well-known/oauth-protected-resource

app.use(authzenMiddleware({
  client,
  pep: 'api-edge',
  verifyToken: async (token) => (await jwtVerify(token, jwks, { audience: 'https://api.bank.example' })).payload,
  map: pathMapper([
    { method: 'GET',  pattern: '/accounts/:id/balance', action: 'get_balance',  resourceType: 'account', resourceId: (p) => p.id },
    { method: 'POST', pattern: '/payments',             action: 'make_payment', resourceType: 'payment',
      resourceProperties: (_p, req) => ({ amount: (req.body as { amount?: number })?.amount }) },
  ]),
  resource: 'https://api.bank.example',
  forwardAccessToken: true,                      // the PDP connection is TLS and authenticated
  forwardHeaders: true,                          // X-Auth-* on req.headers
  onDecision: ({ verdict }) => audit.log(verdict.kind, verdict.reason, verdict.detail),
}));

app.get('/accounts/:id/balance', (req, res) => res.json({ balance: 12.5, principal: req.get('x-auth-principal') }));
app.listen(8070);

An MCP server guarding its own tools

import { McpGuard } from '@id-partners/authzen-pep/mcp';

const guard = new McpGuard({
  client: { url: process.env.AUTHZEN_URL!, apiKey: process.env.AUTHZEN_API_KEY },
  tools,                                         // this process IS the MCP server
  pep: 'mcp-edge',                               // every method governed by default; unknown ones denied
  resource: 'https://mcp.bank.example',
  forwardAccessToken: true,
  onDecision: ({ tool, verdict }) => audit.log(tool, verdict),
});

app.post('/mcp', express.raw({ type: 'application/json', inflate: false }), async (req, res) => {
  const claims = await verify(req.get('authorization'));   // yours: the guard never decodes a token
  const v = await guard.checkToolCall({ raw: { headers: req.headers, body: req.body }, claims });
  if (!v.allow) return res.status(v.response!.status).set(v.response!.headers).send(v.response!.body);
  res.json(await runTool(v.message!));
});

An MCP gateway delegating to coaz-pep

const guard = new McpGuard({
  client: { url: process.env.AUTHZEN_URL! },
  upstreamUrl: 'https://mcp.bank.example/mcp',   // required: coaz-pep reads this server's tools/list
  delegate: {
    url: 'http://coaz-pep:9192',
    apiKey: process.env.CHECK_API_TOKEN,         // required: coaz-pep's CHECK_API_TOKEN
    config: { require_token: 'true', require_user_login: 'true' },
  },
  resource: 'https://mcp.bank.example',
  forwardAccessToken: true,
  failMode: 'closed',
});

// Every MCP request goes to coaz-pep, whatever its method.
const v = await guard.checkToolCall({ raw: { method: req.method, path: '/mcp', headers: req.headers, body: rawBody } });
if (!v.allow) return res.status(v.response!.status).set(v.response!.headers).send(v.response!.body);
forwardUpstream(req, v.upstreamHeaders);         // X-Auth-* as coaz-pep asserted them; '' removes
res.set(v.responseHeaders ?? {});                // X-PDP-Fail-Open survives

The engine renders the deny and the SDK relays it verbatim, a 401 challenge included; two renderings of one decision would drift.

What the PDP receives

{
  "subject":  { "type": "user", "id": "customer", "properties": { "client_id": "agent-1", "on_behalf_of": "customer" } },
  "action":   { "name": "make_payment" },
  "resource": { "type": "payment", "id": "…", "properties": { "amount": 50 } },
  "context": {
    "resource_metadata_source": "rfc9728",
    "resource_metadata": { "resource": "https://api.bank.example",
                           "scopes_supported": ["accounts:read", "payments:write"],
                           "acr_values_required": ["urn:idp:loa:mfa"],
                           "authzen_policy_decision_points": ["https://pdp.bank.example"] },
    "request":  { "method": "POST", "path": "/payments" },
    "access_token": "eyJ…"
  }
}

The SDK is tested with vitest (sdk/node/test/, 460 tests on Node 22 and 24) and holds coverage floors of 99% statements and lines, 95% branches and 100% functions.