The Node SDK

@id-partners/authzen-pep adds policy enforcement to a Node.js service. It includes an AuthZEN client and Express middleware. McpGuard handles MCP requests. FederationEntity publishes signed resource metadata. The package has no runtime dependencies. Configure it through options in code.

Install

npm install ./id-partners-authzen-pep-<version>.tgz

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';

Requires Node.js 22 or later. The package uses ECMAScript modules (ESM). It includes TypeScript declarations and source maps with their source files.

Download the package from its GitHub release before running the install command. Public npm publishing is optional in the release workflow.

Upgrading past 0.4.2: one refusal contract

Every refusal now follows the contract all four PEPs share, so a client gets the same answer from this SDK as from the gateways. This changes what a client gets back and some public types.

Upgrading to 0.4.0

Version 0.4.0 requires explicit token verification and discovery security settings. Missing required settings prevent startup. allowInsecure: true bypasses these checks for development and demos. The SDK logs the override at startup.

AuthzenClient

Create the client with new AuthzenClient(options). The middleware and MCP guard accept a client instance or the same options.

Methods: evaluate(request, options), evaluateAll(batch, options) (a boxcar, folded to one verdict: the first deny wins so its advice survives, and a permit carries every evaluation's obligations; 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 PDP evaluates the resource's requirements.

PDP call outcomes

A fail-open setting skips only an unavailable PDP. The table defines each outcome.

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?, refusal?, 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. A deny carries refusal, rendered by the decision contract every PEP in this repository shares (core/authzen/refusal) and held to the same vectors (core/authzen/refusal/testdata/challenges/cases.json): the same status, JSON body and WWW-Authenticate as coaz-pep, the Kong plugins and the PingAccess rule. toHttpChallenge(verdict, conf) and toChallenge(verdict, conf) render it; conf is a RefusalConfig (pep, stepUpScope, resourceMetadata) or the PEP label alone, and the middleware and the guard fill it from their own options. kind is the coarse class, for code that switches on it:

A challenge flag that is JSON true refuses a permit as well as a deny ("true" and 1 do not count): identity_proofing_required first, then step_up_required, then authn_required, each with the parameters it owns (doctype or identity_proofing_doctype; scope or step_up_scope, else stepUpScope; acr_values). Otherwise a deny's context.error names the refusal, from the contract's list less the PEP's own (invalid_dpop_proof, invalid_request, request_too_large, temporarily_unavailable); any other value is access_denied. context.error_description, else reason, is the description, and the PDP never chooses the status. max_age is read only for insufficient_user_authentication, and only as a whole number of seconds from 0 to 2³¹-1; anything else is left out. Permitting layers and boxcar permits keep each other's obligations: the first to require something owns its parameters and its description. resource_metadata is the route's own RFC 9728 URL, built from resource, never a PDP's.

A PDP that names a missing scope, from the shared vectors:

// context: { "error": "insufficient_scope", "error_description": "Missing scope: accounts:read.", "scope": "accounts:read" }
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="accounts:read", resource_metadata="https://api.bank.example/.well-known/oauth-protected-resource"

{"status":403,"error":"insufficient_scope","error_description":"Missing scope: accounts:read.",
 "scope":"accounts:read",
 "authz_challenge":{"type":"resource_authorisation","scope":"accounts:read",
                    "reason":"Missing scope: accounts:read.","pep":"test-pep"}}

pdp_error is a 503 and fails closed: the PDP being down is our problem, and a 403 would send the caller chasing permissions they already have. WWW-Authenticate carries no error_description. A parameter value built from PDP data is quoted by the rule every PEP applies byte for byte: CR, LF and tab become a space, anything else outside printable ASCII is dropped, and backslash and double quote are escaped, so a policy value can neither add a parameter, forge a header nor make Node refuse one.

Complete samples

A REST API: verified tokens, discovery, layers, the metadata publisher

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_set: { combining: 'deny-overrides', members: [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 denial by the same contract, challenge included. The SDK relays it unchanged.

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_set": { "combining": "deny-overrides", "members": ["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.