import { createRemoteJWKSet, customFetch, errors as joseErrors, jwtVerify } from 'jose';
import { ASYMMETRIC_JWS_ALGS } from './algs.js';
import { discoverGrantServer, discoverOpenIdProvider, validateGrantServerMetadata } from './discovery.js';
import { GNAPClientError, GNAPError, ValidationError } from './errors.js';
import { GrantSet } from './grant-set.js';
import { httpRequest, readJson } from './http.js';
import { signRequest } from './httpsig.js';
import { CLIENT_KEY_ALGS, ClientKey, MemoryKeyStore } from './keys.js';
import { MemoryTokenStore, TransactionStore } from './stores.js';
import { base64url, Emitter, isSecureUrl, randomToken, timingSafeEqual } from './util.js';
/** Interaction hash methods (RFC 9635 section 4.2.3) this library computes, and their WebCrypto names. */
const HASH_METHODS = { 'sha-256': 'SHA-256', 'sha-512': 'SHA-512' };
/** Parameters that never arrive at a redirect finish URI: GNAP never sends a token through the browser. */
const FRONT_CHANNEL_TOKENS = ['access_token', 'id_token', 'token', 'value', 'continue', 'refresh_token'];
/** Rights dropped from a grant when `signals` is false. A string is matched after trim; an object's `type` is exact. */
const SIGNAL_RIGHTS = new Set(['ssf.read', 'ssf.manage']);
function isSignalRight(right) {
if (typeof right === 'string') return SIGNAL_RIGHTS.has(right.trim());
return !!right && typeof right === 'object' && typeof right.type === 'string' && SIGNAL_RIGHTS.has(right.type);
}
/** Grant request members `extra` may not set: the client sets them, and the callback relies on them. */
const RESERVED_REQUEST_MEMBERS = Object.freeze(['client', 'interact']);
/** Claims of a verified `id_token` assertion this client keeps in `claims`, for display and matching. */
const PROFILE_CLAIMS = ['name', 'given_name', 'family_name', 'preferred_username', 'email', 'email_verified',
'phone_number', 'phone_number_verified', 'picture', 'acr', 'amr', 'auth_time', 'sid'];
/**
* @typedef {object} GNAPClientConfig
* @property {string} [grantEndpoint] The AS's grant endpoint, e.g. `https://as.example.com/gnap`.
* Its discovery document is read with an OPTIONS request (RFC 9635 section 9).
* @property {Record<string, any>} [metadata] A discovery document to use instead of discovering one.
* @property {string} [finishUri] Where the AS sends the browser back after interaction
* (the redirect finish URI, section 2.5.2). Required for a redirect interaction.
* @property {Array<string|Record<string, any>>} [access] The access rights to request by default
* (section 8): reference strings such as `"ssf.read"`, or objects with `type`, `actions`, ...
* @property {boolean} [signals] CAEP and RISC. Omitted or `true` is on. `false` removes
* `ssf.read` and `ssf.manage` from the grant request. The subject request is unchanged.
* @property {{ subIdFormats?: string[], assertionFormats?: string[] }|false} [subject] Who the resource
* owner is (section 2.2). Default `{ subIdFormats: ['iss_sub', 'opaque'] }`. `false` asks for nothing.
* @property {{ name?: string, uri?: string, logo_uri?: string }} [display] What the approval page shows
* about this client (section 2.3.2): self-declared, never a reason for more trust.
* @property {string} [classId] The client's `class_id` (section 2.3): the identifier of the registered
* application this key is an instance of. An AS that accepts unregistered instances (iya-sts:
* `gnap.unregisteredInstances`, the default) then accepts a browser's key with no registration of its own.
* @property {ClientKey} [key] The client key. Default: loaded from, or created in, `keyStore`.
* @property {import('./keys.js').KeyStore} [keyStore] Where the key is kept (default memory: a new client
* instance every page load). Use `new IndexedDBKeyStore()` to keep a non-extractable key.
* @property {string} [alg] Client key algorithm (default ES256).
* @property {boolean} [useInstanceId] Send the `instance_id` the AS handed out (section 3.5) instead of
* the key by value in later requests. Default false.
* @property {import('./stores.js').TokenStore} [instanceStore] Where an instance_id is remembered.
* @property {boolean} [requireBoundTokens] Refuse an access token issued with the `bearer` flag
* (section 3.2.1): this client asks for key-bound tokens. Default true.
* @property {'sha-256'|'sha-512'} [hashMethod] The interaction hash method to ask for (default sha-256).
* @property {{ issuer: string, jwksUri?: string, audience?: string|string[], algorithms?: string[] }} [idToken]
* Verify an `id_token` subject assertion against this issuer's keys. Without it, an assertion is
* kept as received and never decoded.
* @property {TransactionStore} [transactionStore] Where pending grants wait for the callback (default sessionStorage).
* @property {number} [transactionTtlSec] How long a pending grant stays redeemable (default 600).
* @property {number} [maxWaitSec] The longest `wait` (section 3.1) the client sleeps for a `too_fast`
* continuation before giving up (default 10).
* @property {boolean} [allowInsecureRequests] Allow non-TLS endpoints and finish URIs other than loopback (default false).
* @property {number} [clockToleranceSec] Allowed clock skew for an id_token assertion (default 30).
* @property {number} [httpTimeoutMs] Per-request timeout (default 10000).
* @property {number} [discoveryCacheTtlMs] How long a discovery document is cached (default 1h).
* @property {typeof fetch} [fetch] Custom fetch implementation.
*/
/**
* A GNAP client instance (RFC 9635) for a browser app: it identifies itself by a key, signs every request
* with it (HTTP message signatures), asks the resource owner to approve a grant through a redirect
* interaction, and learns who they are from the grant's subject information. Its access tokens are bound
* to the key.
*
* Emits: "tokens" (GrantSet) whenever the AS issues a new access token.
*/
export class GNAPClient extends Emitter {
/** The AS's discovery document. @type {Record<string, any>} */
metadata;
/** @type {ClientKey} */
key;
#config;
#jwks;
#usedHashes = new Map();
#subIdFormats = [];
#assertionFormats = [];
/** @param {GNAPClientConfig} config */
constructor(config) {
super();
const grantEndpoint = config?.grantEndpoint ?? config?.metadata?.grant_request_endpoint;
if (!grantEndpoint) throw new TypeError('grantEndpoint or metadata is required');
for (const unsupported of ['clientSecret', 'clientId']) {
if (config[unsupported] !== undefined) {
throw new TypeError(`${unsupported} is not a GNAP concept: a GNAP client is identified by its key`);
}
}
this.#config = {
clockToleranceSec: 30,
httpTimeoutMs: 10_000,
transactionTtlSec: 600,
maxWaitSec: 10,
hashMethod: 'sha-256',
requireBoundTokens: true,
useInstanceId: false,
allowInsecureRequests: false,
subject: { subIdFormats: ['iss_sub', 'opaque'] },
...config,
grantEndpoint,
};
if (!HASH_METHODS[this.#config.hashMethod]) {
throw new TypeError(`hashMethod must be one of ${Object.keys(HASH_METHODS).join(', ')}`);
}
if (this.#config.signals === undefined) this.#config.signals = true;
else if (typeof this.#config.signals !== 'boolean') throw new TypeError('signals must be true or false');
if (this.#config.access !== undefined && !Array.isArray(this.#config.access)) throw new TypeError('access must be an array');
this.#config.transactionStore ??= new TransactionStore({ prefix: 'gnap-caep-client:grant:' });
this.#config.instanceStore ??= new MemoryTokenStore();
}
/**
* Creates a client and loads the AS's discovery document.
* @param {GNAPClientConfig} config
* @returns {Promise<GNAPClient>}
*/
static async discover(config) {
const client = new GNAPClient(config);
await client.init();
return client;
}
/** The grant endpoint (the AS's identity, as an issuer is in OAuth). */
get grantEndpoint() { return this.#config.grantEndpoint; }
/** The effective settings, for display. */
get config() {
const { metadata, transactionStore, instanceStore, keyStore, key, fetch: _f, ...rest } = this.#config;
return { ...rest, keyProof: 'httpsig', subIdFormats: this.#subIdFormats, assertionFormats: this.#assertionFormats };
}
/** Which security features are active, for display and audit. */
get securityFeatures() {
return {
keyProof: 'httpsig (RFC 9421) with Content-Digest (RFC 9530), tag "gnap"',
clientKey: this.key ? { alg: this.key.alg, thumbprint: this.key.thumbprint, extractable: !!this.key.keyPair?.privateKey?.extractable } : undefined,
boundTokens: this.#config.requireBoundTokens ? 'required: a bearer token is refused' : 'preferred',
interactionHash: `${this.#config.hashMethod}, checked in constant time; each pending grant single use and expiring`,
finishNonce: 'random 256-bit per grant request',
continuationOrigin: 'continuation and management URIs must be on the grant endpoint\'s origin',
subject: this.#subIdFormats.length ? this.#subIdFormats.join(', ') : 'not requested',
idTokenAssertion: this.#config.idToken ? `verified against ${this.#config.idToken.issuer}` : 'not verified (kept, never decoded)',
tlsEnforced: !this.#config.allowInsecureRequests,
};
}
async init() {
const c = this.#config;
if (!c.allowInsecureRequests && !isSecureUrl(c.grantEndpoint)) {
throw new ValidationError(`grantEndpoint must use https: ${c.grantEndpoint}`, { code: 'insecure_endpoint' });
}
if (c.finishUri && !c.allowInsecureRequests && !isSecureUrl(c.finishUri)) {
throw new ValidationError(`finishUri must use https (or loopback http): ${c.finishUri}`, { code: 'insecure_redirect_uri' });
}
this.metadata = c.metadata
? validateGrantServerMetadata(c.metadata, c.metadata.grant_request_endpoint === undefined ? undefined : c.grantEndpoint)
: await discoverGrantServer(c.grantEndpoint, { timeoutMs: c.httpTimeoutMs, fetch: c.fetch, cacheTtlMs: c.discoveryCacheTtlMs });
const m = this.metadata;
const proofs = m.key_proofs_supported;
if (Array.isArray(proofs) && !proofs.includes('httpsig')) {
throw new ValidationError(`The AS does not accept httpsig key proofs (it offers ${proofs.join(', ') || 'none'})`, { code: 'key_proof_not_supported' });
}
if (c.finishUri) {
if (Array.isArray(m.interaction_start_modes_supported) && !m.interaction_start_modes_supported.includes('redirect')) {
throw new ValidationError('The AS does not offer the redirect interaction start mode', { code: 'interaction_not_supported' });
}
if (Array.isArray(m.interaction_finish_methods_supported) && !m.interaction_finish_methods_supported.includes('redirect')) {
throw new ValidationError('The AS does not offer the redirect interaction finish method', { code: 'interaction_not_supported' });
}
}
// Ask only for what the AS says it can answer; ask for nothing it cannot.
const want = c.subject === false ? {} : (c.subject ?? {});
const supported = (list, offered) => (Array.isArray(offered) ? (list ?? []).filter((f) => offered.includes(f)) : [...(list ?? [])]);
this.#subIdFormats = supported(want.subIdFormats, m.sub_id_formats_supported);
this.#assertionFormats = supported(want.assertionFormats, m.assertion_formats_supported);
if (!c.key) {
const alg = c.alg ?? 'ES256';
if (!CLIENT_KEY_ALGS.includes(alg)) throw new ValidationError(`Unsupported client key alg ${alg}`);
c.key = await ClientKey.loadOrCreate(c.keyStore ?? new MemoryKeyStore(), { alg });
}
this.key = c.key;
if (c.idToken) {
if (!c.idToken.issuer) throw new TypeError('idToken.issuer is required');
let jwksUri = c.idToken.jwksUri;
if (!jwksUri) {
jwksUri = (await discoverOpenIdProvider(c.idToken.issuer, { timeoutMs: c.httpTimeoutMs, fetch: c.fetch, cacheTtlMs: c.discoveryCacheTtlMs })).jwks_uri;
}
if (!c.allowInsecureRequests && !isSecureUrl(jwksUri)) throw new ValidationError(`jwks_uri must use https: ${jwksUri}`, { code: 'insecure_endpoint' });
this.#jwks = createRemoteJWKSet(new URL(jwksUri), { timeoutDuration: c.httpTimeoutMs, ...(c.fetch ? { [customFetch]: c.fetch } : {}) });
}
c.transactionStore.sweep?.(c.transactionTtlSec * 1000);
return this;
}
#requireInit() {
if (!this.metadata || !this.key) throw new GNAPClientError('Client not initialised; call init() or GNAPClient.discover()');
}
// ---------------------------------------------------------------------------
// The grant request (RFC 9635 section 2)
// ---------------------------------------------------------------------------
/**
* Starts a grant: a signed request to the grant endpoint asking for an access token and, unless turned
* off, who the resource owner is, with a redirect interaction that finishes at `finishUri`.
*
* When the AS needs the resource owner, this resolves `{ url }`: send the browser there, and complete
* the grant on the finish URI with `completeGrant()`. When it issues the token at once (a trusted
* client), it resolves `{ grantSet }` and nothing waits.
*
* @param {object} [opts]
* @param {Array<string|Record<string, any>>} [opts.access] Access rights; default the configured ones.
* When `signals` is false, `ssf.read` and `ssf.manage` are removed from this list.
* @param {string} [opts.label] A label for the access token.
* @param {string[]} [opts.flags] Access token flags to ask for (e.g. `durable`). `bearer` is refused
* while `requireBoundTokens` is on.
* @param {Record<string, any>} [opts.user] Who the client believes the user is (section 2.4): e.g.
* `{ sub_ids: [{ format: 'iss_sub', iss, sub }] }`, or an opaque user reference string.
* @param {string} [opts.expectedSub] Refuse a grant approved by anybody else (`account_mismatch`).
* @param {boolean} [opts.subject] `false` asks for no subject information in this request.
* @param {any} [opts.context] JSON-serialisable data handed back by `completeGrant()`.
* @param {Record<string, any>} [opts.extra] Further top-level members of the grant request.
* @returns {Promise<{ url?: string, grantSet?: GrantSet, context?: any }>}
*/
async createGrantRequest(opts = {}) {
this.#requireInit();
const c = this.#config;
let access = opts.access ?? c.access;
if (!Array.isArray(access) || !access.length) throw new TypeError('access is required: the rights to ask for (RFC 9635 section 8)');
if (c.signals === false) {
access = access.filter((right) => !isSignalRight(right));
if (!access.length) {
throw new TypeError('signals is false and access has no rights left after ssf.read and ssf.manage were removed; the caller must name a right this authorization server grants');
}
}
const flags = opts.flags ?? [];
if (c.requireBoundTokens && flags.includes('bearer')) throw new TypeError('The bearer flag is refused while requireBoundTokens is on');
const reserved = Object.keys(opts.extra ?? {}).filter((k) => RESERVED_REQUEST_MEMBERS.includes(k));
if (reserved.length) throw new TypeError(`extra may not set ${reserved.join(', ')}: the client sets them itself`);
const body = { ...opts.extra };
body.access_token = { access, ...(opts.label ? { label: opts.label } : {}), ...(flags.length ? { flags } : {}) };
body.client = await this.#clientMember();
const nonce = randomToken();
if (c.finishUri) {
body.interact = {
start: ['redirect'],
finish: { method: 'redirect', uri: c.finishUri, nonce, ...(c.hashMethod !== 'sha-256' ? { hash_method: c.hashMethod } : {}) },
};
}
if (opts.subject !== false && (this.#subIdFormats.length || this.#assertionFormats.length)) {
body.subject = {
...(this.#subIdFormats.length ? { sub_id_formats: this.#subIdFormats } : {}),
...(this.#assertionFormats.length ? { assertion_formats: this.#assertionFormats } : {}),
};
}
if (opts.user !== undefined) body.user = opts.user;
const answer = await this.#signedJson('POST', c.grantEndpoint, { body });
await this.#rememberInstance(answer);
if (answer?.interact) {
const redirect = answer.interact.redirect;
if (typeof redirect !== 'string') {
throw new ValidationError('The AS answered with an interaction this client did not ask for (no interact.redirect)', { code: 'interaction_not_supported', response: answer });
}
if (!c.allowInsecureRequests && !isSecureUrl(redirect)) throw new ValidationError(`interact.redirect must use https: ${redirect}`, { code: 'insecure_endpoint' });
if (typeof answer.interact.finish !== 'string' || !answer.interact.finish) {
throw new ValidationError('The AS did not return its interaction finish nonce (interact.finish)', { code: 'invalid_grant_response' });
}
const cont = this.#checkContinue(answer.continue);
c.transactionStore.set(nonce, {
clientNonce: nonce,
serverNonce: answer.interact.finish,
hashMethod: c.hashMethod,
continue: cont,
grantEndpoint: c.grantEndpoint,
keyThumbprint: this.key.thumbprint,
expectedSub: opts.expectedSub,
context: opts.context,
bearerAllowed: !c.requireBoundTokens,
createdAt: Date.now(),
});
return { url: redirect, context: opts.context };
}
if (answer?.access_token) {
const grantSet = await this.#grantSetFrom(answer, {});
await this.#checkExpectedSub(grantSet, opts.expectedSub);
this.emit('tokens', grantSet);
return { grantSet, context: opts.context };
}
throw new ValidationError('The AS answered with neither an interaction nor an access token; a grant that waits for somebody elsewhere is not supported',
{ code: 'invalid_grant_response', response: answer });
}
/**
* Completes a grant on the finish URI: finds the pending grant whose interaction hash (section 4.2.3)
* the returned `hash` is, removes it (single use), and continues the grant with `interact_ref` to
* receive the access token and the subject information.
*
* @param {URLSearchParams|Record<string,string>|string} response The finish URL, or its query parameters.
* @returns {Promise<GrantSet>}
*/
async callback(response) {
return (await this.completeGrant(response)).grantSet;
}
/**
* `callback()`, also answering the `context` the request was created with. A refusal by the resource
* owner is a GNAPError `user_denied` carrying that context as `err.context`.
* @param {URLSearchParams|Record<string,string>|string} response
* @returns {Promise<{ grantSet: GrantSet, context: any }>}
*/
async completeGrant(response) {
this.#requireInit();
const c = this.#config;
const p = toParams(response);
const injected = FRONT_CHANNEL_TOKENS.filter((k) => p.has(k));
if (injected.length) throw new ValidationError(`The finish redirect carries ${injected.join(', ')}; GNAP never sends tokens through the browser`, { code: 'front_channel_token' });
for (const k of new Set(p.keys())) {
if (p.getAll(k).length > 1) throw new ValidationError(`The finish redirect repeats "${k}"`, { code: 'duplicate_parameter' });
}
const hash = p.get('hash');
const interactRef = p.get('interact_ref');
if (!hash || !interactRef) {
if (p.get('error')) throw new GNAPError({ error: p.get('error'), error_description: p.get('error_description') ?? undefined });
throw new ValidationError('The finish redirect has no hash or interact_ref', { code: 'hash_missing' });
}
// THE HASH IS THE STATE. Recompute it with each pending grant's nonces; the one it matches is ours.
let id;
let transaction;
for (const candidate of c.transactionStore.ids()) {
const t = c.transactionStore.peek(candidate);
if (!t?.clientNonce || !t.serverNonce) continue;
const expected = await interactionHash(t.clientNonce, t.serverNonce, interactRef, t.grantEndpoint, t.hashMethod);
if (await timingSafeEqual(hash, expected)) {
id = candidate;
transaction = t;
break;
}
}
if (!transaction || !c.transactionStore.take(id)) {
const reused = this.#usedHashes.has(hash);
throw new ValidationError(reused
? 'This interaction finish was already used'
: 'The interaction hash matches no grant in progress (unknown, already used, tampered with, or from another tab)',
{ code: reused ? 'interaction_reused' : 'hash_mismatch' });
}
this.#rememberHash(hash);
if (Date.now() - transaction.createdAt > c.transactionTtlSec * 1000) {
throw new ValidationError(`The approval took longer than ${c.transactionTtlSec}s; start again`, { code: 'transaction_expired' });
}
if (transaction.grantEndpoint !== c.grantEndpoint || transaction.keyThumbprint !== this.key.thumbprint) {
throw new ValidationError('This grant was started with another authorization server or client key', { code: 'grant_endpoint_mismatch' });
}
let answer;
try {
answer = await this.#continue(transaction.continue, 'POST', { interact_ref: interactRef });
} catch (err) {
if (err instanceof GNAPClientError) err.context = transaction.context;
throw err;
}
if (!answer?.access_token) {
// RFC 9635 section 4.2.1: a denied interaction still finishes; the continuation then issues nothing.
const err = new GNAPError({ error: 'user_denied', error_description: 'The resource owner did not approve the grant', response: answer });
err.context = transaction.context;
throw err;
}
let grantSet;
try {
grantSet = await this.#grantSetFrom(answer, { previousContinue: transaction.continue });
await this.#checkExpectedSub(grantSet, transaction.expectedSub);
} catch (err) {
if (err instanceof GNAPClientError) err.context = transaction.context;
throw err;
}
this.emit('tokens', grantSet);
return { grantSet, context: transaction.context };
}
async #checkExpectedSub(grantSet, expectedSub) {
if (expectedSub === undefined || grantSet.claims?.sub === expectedSub) return;
await this.revokeGrant(grantSet).catch(() => {});
throw new ValidationError('The grant was approved by a different person from the one requested', {
code: 'account_mismatch', response: { expected: expectedSub, sub: grantSet.claims?.sub },
});
}
#rememberHash(hash) {
const now = Date.now();
this.#usedHashes.set(hash, now);
const cutoff = now - this.#config.transactionTtlSec * 1000;
for (const [h, at] of this.#usedHashes) {
if (at >= cutoff && this.#usedHashes.size <= 1000) break;
this.#usedHashes.delete(h);
}
}
// ---------------------------------------------------------------------------
// Continuing, modifying and revoking the grant (section 5)
// ---------------------------------------------------------------------------
/**
* Modifies the grant (section 5.3) onto different access rights; the AS may need the resource owner
* again, which this client then refuses (`interaction_required`). Resolves a new GrantSet.
* @param {GrantSet} grantSet
* @param {{ access: Array<string|Record<string, any>> }} changes
* @returns {Promise<GrantSet>}
*/
async modifyGrant(grantSet, { access }) {
this.#requireInit();
const previous = GrantSet.from(grantSet);
if (!previous.continue) throw new GNAPClientError('This grant cannot be continued (no continue)', { code: 'no_continuation' });
const answer = await this.#continue(previous.continue, 'PATCH', { access_token: { access } });
if (answer?.interact) throw new GNAPClientError('The AS needs the resource owner again for this change; start a new grant', { code: 'interaction_required', response: answer });
if (!answer?.access_token) throw new ValidationError('The modification issued no access token', { code: 'invalid_grant_response', response: answer });
const next = await this.#grantSetFrom(answer, { previousContinue: previous.continue, previous });
this.emit('tokens', next);
return next;
}
/**
* Revokes the whole grant (section 5.4): every token issued under it stops working. Resolves false when
* the grant cannot be continued.
* @param {GrantSet|{ continue: { uri: string, access_token: { value: string } } }} grantSet
* @returns {Promise<boolean>}
*/
async revokeGrant(grantSet) {
this.#requireInit();
const cont = grantSet?.continue;
if (!cont?.uri || !cont.access_token?.value) return false;
await this.#continue(cont, 'DELETE');
return true;
}
async #continue(cont, method, body) {
let checked = this.#checkContinue(cont);
let waited = 0;
for (;;) {
try {
return await this.#signedJson(method, checked.uri, { body, token: checked.access_token.value });
} catch (err) {
// Section 3.6 too_fast: wait as told (or a second) and try again, within maxWaitSec in all.
if (!(err instanceof GNAPError) || err.error !== 'too_fast') throw err;
const wait = Math.max(1, Number(err.continue?.wait ?? checked.wait ?? 1));
if (waited + wait > this.#config.maxWaitSec) throw err;
waited += wait;
// The error's continue object replaces the one just used: an AS may rotate the continuation token
// with it (iya-sts does), and the old token is then refused as invalid_continuation.
if (err.continue?.access_token?.value) checked = this.#checkContinue(err.continue);
await new Promise((resolve) => setTimeout(resolve, wait * 1000));
}
}
}
/**
* A `continue` object the AS returned, checked: a continuation token goes to its URI, so the URI must
* be on the grant endpoint's origin and use TLS.
*/
#checkContinue(cont) {
if (!cont || typeof cont.uri !== 'string' || typeof cont.access_token?.value !== 'string') {
throw new ValidationError('The AS returned no usable continue object', { code: 'invalid_grant_response', response: cont });
}
this.#checkSameOrigin(cont.uri, 'continue.uri');
if (cont.wait !== undefined && !(Number.isFinite(Number(cont.wait)) && Number(cont.wait) >= 0)) {
throw new ValidationError(`Invalid continue.wait ${cont.wait}`, { code: 'invalid_grant_response' });
}
return { uri: cont.uri, access_token: { value: cont.access_token.value }, ...(cont.wait !== undefined ? { wait: Number(cont.wait) } : {}) };
}
#checkSameOrigin(uri, what) {
let u;
try {
u = new URL(uri);
} catch {
throw new ValidationError(`${what} is not a URL: ${uri}`, { code: 'invalid_grant_response' });
}
if (!this.#config.allowInsecureRequests && !isSecureUrl(u.href)) throw new ValidationError(`${what} must use https: ${uri}`, { code: 'insecure_endpoint' });
if (u.origin !== new URL(this.#config.grantEndpoint).origin) {
throw new ValidationError(`${what} ${uri} is not on the grant endpoint's origin; not sending a token there`, { code: 'untrusted_endpoint' });
}
}
// ---------------------------------------------------------------------------
// Token management (section 6)
// ---------------------------------------------------------------------------
/**
* Rotates the access token (section 6.1): the AS issues a new one and the old one stops working. The
* grant's continuation and subject carry over. A key-bound token is never rotated into a bearer one.
* @param {GrantSet} grantSet
* @returns {Promise<GrantSet>}
*/
async rotate(grantSet) {
this.#requireInit();
const previous = GrantSet.from(grantSet);
if (!previous.canRotate()) throw new GNAPClientError('This access token cannot be rotated (no manage URI)', { code: 'no_management' });
this.#checkSameOrigin(previous.manage.uri, 'manage.uri');
const answer = await this.#signedJson('POST', previous.manage.uri, { token: previous.manage.access_token.value });
if (!answer?.access_token) throw new ValidationError('The rotation returned no access token', { code: 'invalid_grant_response', response: answer });
const next = await this.#grantSetFrom({ ...answer, subject: undefined }, { previous, previousContinue: previous.continue });
if (!previous.bearer && next.bearer) {
throw new ValidationError('Rotating a key-bound token returned a bearer token', { code: 'bearer_downgrade' });
}
this.emit('tokens', next);
return next;
}
/**
* Revokes the access token (section 6.2). Resolves false when it has no management URI.
* @param {GrantSet} grantSet
* @returns {Promise<boolean>}
*/
async revokeToken(grantSet) {
this.#requireInit();
const ts = GrantSet.from(grantSet);
if (!ts?.canRotate()) return false;
this.#checkSameOrigin(ts.manage.uri, 'manage.uri');
await this.#signedJson('DELETE', ts.manage.uri, { token: ts.manage.access_token.value });
return true;
}
// ---------------------------------------------------------------------------
// Calling resource servers (section 7.2)
// ---------------------------------------------------------------------------
/**
* The headers for a request to a resource server with an access token: `Authorization: GNAP <token>` and,
* for a key-bound token, an HTTP message signature covering the method, the URI, the token and the
* content digest.
*
* @param {GrantSet|{ access_token: string, bearer?: boolean }|string} token
* @param {{ method?: string, url: string, body?: string, headers?: Record<string, string> }} request
* @returns {Promise<Record<string, string>>}
*/
async resourceHeaders(token, { method = 'GET', url, body, headers = {} }) {
this.#requireInit();
const { access_token: value, bearer } = typeof token === 'string' ? { access_token: token, bearer: false } : token;
if (typeof value !== 'string' || !value) throw new GNAPClientError('No access token', { code: 'no_tokens' });
const authorization = `GNAP ${value}`;
if (bearer) return { authorization };
if (body !== undefined && typeof body !== 'string') throw new TypeError('A signed request body must be a string (its digest is signed)');
return { authorization, ...(await signRequest({ method, url, headers: { ...headers, authorization }, body, key: this.key })) };
}
/**
* fetch() against a resource server with an access token, signed with the client key. The body, when
* there is one, must be a string: its digest is part of the signature.
* @param {GrantSet|{ access_token: string, bearer?: boolean }|string} token
* @param {string} url
* @param {RequestInit & { body?: string }} [init]
*/
async fetchResource(token, url, init = {}) {
const method = init.method ?? 'GET';
const headers = Object.fromEntries(new Headers(init.headers ?? {}).entries());
const signed = await this.resourceHeaders(token, { method, url, body: init.body ?? undefined, headers });
return httpRequest(url, { timeoutMs: this.#config.httpTimeoutMs, fetch: this.#config.fetch, ...init, headers: { ...headers, ...signed } });
}
// ---------------------------------------------------------------------------
// Internals
// ---------------------------------------------------------------------------
async #clientMember() {
const c = this.#config;
if (c.useInstanceId) {
const held = await c.instanceStore.get(this.#instanceKey());
if (held?.instance_id) return held.instance_id;
}
return {
key: this.key.keyObject(),
...(c.display ? { display: c.display } : {}),
...(c.classId ? { class_id: c.classId } : {}),
};
}
#instanceKey() { return `instance:${this.#config.grantEndpoint}:${this.key.thumbprint}`; }
async #rememberInstance(answer) {
if (this.#config.useInstanceId && typeof answer?.instance_id === 'string' && answer.instance_id) {
await this.#config.instanceStore.set(this.#instanceKey(), { instance_id: answer.instance_id });
}
}
/** A signed request with a JSON body (or none), answered as JSON. */
async #signedJson(method, url, { body, token } = {}) {
const text = body === undefined ? undefined : JSON.stringify(body);
const headers = { accept: 'application/json' };
if (text !== undefined) headers['content-type'] = 'application/json';
if (token) headers.authorization = `GNAP ${token}`;
Object.assign(headers, await signRequest({ method, url, headers, body: text, key: this.key }));
const res = await httpRequest(url, { timeoutMs: this.#config.httpTimeoutMs, fetch: this.#config.fetch, method, headers, body: text });
return readJson(res);
}
/** Builds and checks a GrantSet from a grant, continuation, modification or rotation response. */
async #grantSetFrom(answer, { previous, previousContinue } = {}) {
const c = this.#config;
const at = answer.access_token;
if (Array.isArray(at)) throw new ValidationError('The AS issued several access tokens; this client asks for one', { code: 'invalid_grant_response' });
if (!at || typeof at.value !== 'string' || !at.value) throw new ValidationError('The access token has no value', { code: 'invalid_grant_response' });
if (at.key !== undefined) {
throw new ValidationError('The access token is bound to a key other than this client\'s, which this client cannot prove', { code: 'invalid_grant_response' });
}
const flags = Array.isArray(at.flags) ? at.flags.filter((f) => typeof f === 'string') : [];
const bearer = flags.includes('bearer');
if (bearer && c.requireBoundTokens) {
throw new ValidationError('The AS issued a bearer token, and this client requires key-bound tokens', { code: 'bearer_downgrade' });
}
if (at.expires_in !== undefined && !(Number.isFinite(Number(at.expires_in)) && Number(at.expires_in) >= 0)) {
throw new ValidationError(`Invalid expires_in ${at.expires_in}`, { code: 'invalid_grant_response' });
}
let manage;
if (at.manage !== undefined) {
if (typeof at.manage?.uri !== 'string' || typeof at.manage.access_token?.value !== 'string') {
throw new ValidationError('The access token\'s manage object is malformed', { code: 'invalid_grant_response' });
}
this.#checkSameOrigin(at.manage.uri, 'manage.uri');
manage = { uri: at.manage.uri, access_token: { value: at.manage.access_token.value } };
}
const cont = answer.continue !== undefined ? this.#checkContinue(answer.continue) : previousContinue;
const subject = answer.subject ?? previous?.subject;
const claims = answer.subject !== undefined ? await this.#validateSubject(answer.subject) : previous?.claims;
return new GrantSet({
access_token: at.value,
bearer,
flags,
...(at.label !== undefined ? { label: String(at.label) } : {}),
access: Array.isArray(at.access) ? at.access : previous?.access,
manage,
continue: cont,
grant_id: grantIdOf(cont?.uri) ?? previous?.grant_id,
instance_id: typeof answer.instance_id === 'string' ? answer.instance_id : previous?.instance_id,
grant_endpoint: c.grantEndpoint,
key_thumbprint: this.key.thumbprint,
subject,
...(at.expires_in !== undefined ? { expires_in: Number(at.expires_in) } : {}),
}, claims);
}
/**
* Who the resource owner is (RFC 9635 section 3.4): an `iss_sub` identifier gives `iss` and `sub`; an
* `opaque` one gives `sub`, with the grant endpoint as `iss`. An `id_token` assertion is verified when
* `idToken` is configured, must be about the same subject, and adds its profile claims; otherwise it is
* kept as received and never decoded.
*/
async #validateSubject(subject) {
if (subject === null || typeof subject !== 'object' || Array.isArray(subject)) {
throw new ValidationError('The subject information is not an object', { code: 'invalid_subject' });
}
const subIds = subject.sub_ids ?? [];
if (!Array.isArray(subIds) || subIds.some((s) => !s || typeof s !== 'object' || typeof s.format !== 'string')) {
throw new ValidationError('subject.sub_ids must be an array of subject identifiers', { code: 'invalid_subject' });
}
const claims = {};
const issSub = subIds.find((s) => s.format === 'iss_sub');
const opaque = subIds.find((s) => s.format === 'opaque');
if (issSub) {
if (typeof issSub.iss !== 'string' || typeof issSub.sub !== 'string' || !issSub.sub) {
throw new ValidationError('An iss_sub subject identifier needs iss and sub strings', { code: 'invalid_subject' });
}
claims.iss = issSub.iss;
claims.sub = issSub.sub;
} else if (opaque) {
if (typeof opaque.id !== 'string' || !opaque.id) throw new ValidationError('An opaque subject identifier needs an id', { code: 'invalid_subject' });
claims.iss = this.#config.grantEndpoint;
claims.sub = opaque.id;
}
if (opaque?.id && typeof opaque.id === 'string') claims.opaque_id = opaque.id;
// RFC 9493 `account` (RFC 7565 `acct:userpart@host`): the person's username at the AS. iya-sts writes
// the directory uid as the user part, so it names the person where `sub` is an opaque identifier.
const account = subIds.find((s) => s.format === 'account' && typeof s.uri === 'string');
const acct = account && /^acct:([^@]+)@(.+)$/.exec(account.uri);
if (acct) {
let uid = acct[1];
try {
uid = decodeURIComponent(uid);
} catch {
// A user part that is not valid percent-encoding is kept as sent.
}
claims.uid = uid;
claims.account = account.uri;
}
claims.sub_ids = subIds;
const assertions = Array.isArray(subject.assertions) ? subject.assertions : [];
const idToken = assertions.find((a) => a?.format === 'id_token' && typeof a.value === 'string');
if (idToken && this.#jwks) {
const cfg = this.#config.idToken;
let verified;
try {
({ payload: verified } = await jwtVerify(idToken.value, this.#jwks, {
algorithms: cfg.algorithms ?? ASYMMETRIC_JWS_ALGS,
issuer: cfg.issuer,
...(cfg.audience !== undefined ? { audience: cfg.audience } : {}),
clockTolerance: this.#config.clockToleranceSec,
requiredClaims: ['iss', 'sub', 'exp'],
}));
} catch (err) {
const msg = err instanceof joseErrors.JOSEError ? err.message : String(err);
throw new ValidationError(`The id_token assertion failed validation: ${msg}`, { code: 'invalid_assertion', cause: err });
}
// Section 3.4: every identifier and assertion in one subject names the same person.
if (claims.sub !== undefined && issSub && verified.sub !== claims.sub) {
throw new ValidationError('The id_token assertion is about somebody other than the subject identifier', { code: 'subject_mismatch' });
}
if (claims.sub === undefined || !issSub) {
claims.iss = verified.iss;
claims.sub = verified.sub;
}
for (const k of PROFILE_CLAIMS) if (verified[k] !== undefined && claims[k] === undefined) claims[k] = verified[k];
claims.assertion_verified = true;
}
return claims.sub === undefined ? undefined : claims;
}
}
/** RFC 9635 section 4.2.3: base64url(H(client nonce \n server nonce \n interact_ref \n grant endpoint)). */
export async function interactionHash(clientNonce, serverNonce, interactRef, grantEndpoint, method = 'sha-256') {
const alg = HASH_METHODS[method];
if (!alg) throw new ValidationError(`Unsupported interaction hash method ${method}`);
const input = new TextEncoder().encode([clientNonce, serverNonce, interactRef, grantEndpoint].join('\n'));
return base64url(new Uint8Array(await crypto.subtle.digest(alg, input)));
}
function grantIdOf(uri) {
if (typeof uri !== 'string') return undefined;
try {
const last = new URL(uri).pathname.split('/').filter(Boolean).pop();
return last ? decodeURIComponent(last) : undefined;
} catch {
return undefined;
}
}
function toParams(input) {
if (input instanceof URLSearchParams) return input;
if (typeof input === 'string') {
if (/^[a-z][a-z0-9+.-]*:/i.test(input) || input.startsWith('/')) {
const u = new URL(input, 'http://localhost');
const all = new URLSearchParams(u.search);
if (u.hash.length > 1) for (const [k, v] of new URLSearchParams(u.hash.slice(1))) all.append(k, v);
return all;
}
return new URLSearchParams(input.replace(/^[?#]/, ''));
}
return new URLSearchParams(Object.entries(input ?? {}).filter(([, v]) => typeof v === 'string'));
}