gnap-caep-risc-nodejs

A server-side GNAP client for a traditional Node.js web application, and a CAEP and RISC Shared Signals receiver. TypeScript, usable from JavaScript, no runtime dependency.

The overlapping configuration names match gnap-caep-js. That library runs in a browser and sends a class_id. This one holds the private key, registers it, and proves it with mutual TLS, an HTTP message signature, or a detached JWS.

import { GnapClient } from 'gnap-caep-risc-nodejs';

const gnap = GnapClient.fromFile('gnap.json');
const started = await gnap.requestGrant();
const done = await gnap.finishRedirect(query, { allowedIds });

The walkthrough is the server-side guide. Events are Handling CAEP and RISC events. The license is the MIT License.

Configuration

Field  
grantEndpoint Required. https://idp.example/gnap. http only with allowInsecure.
application Required. The registered application’s identifier. Not sent as class_id. Also accepted as an ID token audience.
privateKey Required. PEM PKCS#8, file:path, env:NAME, or a path.
transmitterIssuer gnap-caep-js’s name for the Shared Signals issuer. ssf.transmitter wins when both are set. Ignored when signals is false.
idTokenIssuer Issuer of subject ID tokens. Defaults to the grant endpoint’s origin.
classId Optional. Sent as client.class_id only when set. The demo does not set it.
display { name, uri }, sent with the key on the first grant.
access Rights. Default ssf.read and ssf.manage. signals: false removes those two.
signals CAEP and RISC. Default on (omitted or true). false turns them off.
subIdFormats Default iss_sub, account, opaque. Filtered to what the grant server advertises.
assertionFormats Default id_token.
keyProof mtls, httpsig, or jwsd. Default mtls when certificate is set, otherwise httpsig.
certificate PEM. Required for mutual TLS. A chain is leaf first: the key is the leaf, and the handshake sends the whole chain.
finishUri Redirect or push target. Loopback http is allowed.
finishMethod redirect (default) or push.
interactionStart Default ["redirect"].
hashMethod Only sha-256. Omitted from the request, which is the default method.
requireBoundTokens Default true. A bearer flag is then an error.
useInstanceId Default true. After the first response, client is the instance id string.
tlsCa CA trust chain for the authorization server’s TLS listener. PEM, file:path, env:NAME, or a path, trusted in addition to node’s own store. A missing file is ignored.
allowInsecure Allow an http grant endpoint and a non-loopback http finish URI. Default false.
clockToleranceSec ID token skew. Default 30.
maxWaitSec The longest one continuation may be delayed by continue.wait or too_fast. Default 30.
transactionTtlSec How long a pending interaction is kept. Default 600.
ssf.transmitter The transmitter’s issuer. Not used when signals is false.
ssf.pollIntervalMs Pause between polls when nothing else is waiting. The receiver’s own default is 5000.

signals defaults to on. Omitted is the same as true, and the resolved configuration leaves the flag out. signals: false turns CAEP and RISC off. It drops the rights ssf.read and ssf.manage (a string is trimmed first; an object is dropped only when type is exactly one of those two) and does not fill ssf, so the client does not require transmitter metadata and does not fetch /.well-known/ssf-configuration. The grant’s subject request is unchanged. If those two were the only rights, set access to a right the authorization server grants. The resolved configuration includes signals: false only in that case. Callers test config.signals !== false.

GnapClient.fromFile(path) reads the file and the key. It does not discover. GnapClient.resolve(object, baseDir) and GnapClient.create(resolved) build one from an object. Relative paths start at baseDir, which for a file is the file’s directory.

Grant

requestGrant({ access, user, expectedSub, context, subject }) returns { redirectUrl, pending } or { grant } when the server issues the token immediately. Keep pending.id with the browser. The continuation token stays here.

finishRedirect(query, { allowedIds }) completes a redirect. allowedIds is required. An id that is not in it does not consume the pending. The hash is single use and compared in constant time. A front-channel token (access_token, id_token, token, value, continue, refresh_token) is refused. Duplicate query parameters are refused.

finishPush(body) completes { hash, interact_ref } posted by the authorization server. The hash is the authenticator; there is no allowedIds.

authorizationHeaders(grant, { method, url, body }) returns Authorization: GNAP and the proof headers. Pass the exact body that will be sent. call sends that request. rotate posts to the manage URI. revoke deletes the continuation URI. ensureFresh rotates when expiresAt is within 60 seconds or already past.

tls() is ca, and for mutual TLS the certificate and the PKCS#8 key. security describes the posture. instanceId is set from the first response that carries one.

A continue or manage URI on another origin, or one with user information (user:password@), throws before the request is sent. too_fast adopts the continuation in the error body, waits, and retries inside maxWaitSec. A zero wait is retried at most twice.

Subject

An id_token assertion is verified against the issuer’s JWKS: iss equals idTokenIssuer, sub and exp are present, the times sit inside the skew, and aud intersects the instance id and the application identifier when either is known. iss_sub.sub must equal the token’s sub. HMAC and none are refused. Without an id_token, sub falls back to an opaque id and then an account URI, and assertionVerified is false.

Errors

GnapError has code (config, discovery, protocol, validation, signature, ssf) and, when the authorization server named one, gnapError (user_denied, too_fast, …). continuation is the handle from a too_fast body. context is whatever requestGrant was given, on a finish that fails after the pending was found.

Shared Signals

With signals left on, SignalsReceiver polls one stream. signals: false does not start it and does not contact a transmitter. SignalsReceiver stays exported for a caller that builds one itself. headers receives { method, url, body } so the proof covers the body. track / untrack maintain the session index. on(type, handler) and on('*') see each verified event. endOn defaults to session-revoked, account-disabled, account-purged, credential-compromise, and sessions-revoked. verify(state) asks for a verification event.

EVENT, CAEP_EVENTS, RISC_EVENTS, DEFAULT_EVENTS_REQUESTED, and DEFAULT_ENDING_EVENTS are the event URIs. MemorySessionIndex is the default index. trackedFromPerson builds a row from a GNAP subject.

Key generation

npx gnap-caep-risc-nodejs generate-key --config gnap.json [--cn name] [--days 1095] [--force]

P-256, PKCS#8, and a self-signed certificate. Existing files are kept unless --force is set.