Class: GNAPClient

GNAPClient(config)

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.

Constructor

new GNAPClient(config)

Parameters:
Name Type Description
config GNAPClientConfig
Source:

Classes

GNAPClient

Members

config

The effective settings, for display.

Source:

grantEndpoint

The grant endpoint (the AS's identity, as an issuer is in OAuth).

Source:

key :ClientKey

Type:
Source:

metadata

The AS's discovery document. @type {Record<string, any>}

Source:

securityFeatures

Which security features are active, for display and audit.

Source:

Methods

(async) callback(response) → {Promise.<GrantSet>}

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.

Parameters:
Name Type Description
response URLSearchParams | Record.<string, string> | string

The finish URL, or its query parameters.

Source:
Returns:
Type
Promise.<GrantSet>

(async) completeGrant(response) → {Promise.<{grantSet: GrantSet, context: any}>}

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.

Parameters:
Name Type Description
response URLSearchParams | Record.<string, string> | string
Source:
Returns:
Type
Promise.<{grantSet: GrantSet, context: any}>

(async) createGrantRequest(optsopt) → {Promise}

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.

Parameters:
Name Type Attributes Description
opts object <optional>
Properties
Name Type Attributes Description
access Array.<(string|Record.<string, any>)> <optional>

Access rights; default the configured ones. When signals is false, ssf.read and ssf.manage are removed from this list.

label string <optional>

A label for the access token.

flags Array.<string> <optional>

Access token flags to ask for (e.g. durable). bearer is refused while requireBoundTokens is on.

user Record.<string, any> <optional>

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.

expectedSub string <optional>

Refuse a grant approved by anybody else (account_mismatch).

subject boolean <optional>

false asks for no subject information in this request.

context any <optional>

JSON-serialisable data handed back by completeGrant().

extra Record.<string, any> <optional>

Further top-level members of the grant request.

Source:
Returns:

(TypeScript: Promise<{ url?: string, grantSet?: GrantSet, context?: any }>)

Type
Promise

(async) fetchResource(token, url, initopt)

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.

Parameters:
Name Type Attributes Description
token *

(TypeScript: GrantSet|{ access_token: string, bearer?: boolean }|string)

url string
init * <optional>

(TypeScript: RequestInit & { body?: string })

Source:

(async) modifyGrant(grantSet, changes) → {Promise.<GrantSet>}

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.

Parameters:
Name Type Description
grantSet GrantSet
changes Object
Source:
Returns:
Type
Promise.<GrantSet>

(async) resourceHeaders(token, request) → {Promise.<Record.<string, string>>}

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.

Parameters:
Name Type Description
token *

(TypeScript: GrantSet|{ access_token: string, bearer?: boolean }|string)

request Object

(TypeScript: { method?: string, url: string, body?: string, headers?: Record<string, string> })

Source:
Returns:
Type
Promise.<Record.<string, string>>

(async) revokeGrant(grantSet) → {Promise.<boolean>}

Revokes the whole grant (section 5.4): every token issued under it stops working. Resolves false when the grant cannot be continued.

Parameters:
Name Type Description
grantSet GrantSet | Object
Source:
Returns:
Type
Promise.<boolean>

(async) revokeToken(grantSet) → {Promise.<boolean>}

Revokes the access token (section 6.2). Resolves false when it has no management URI.

Parameters:
Name Type Description
grantSet GrantSet
Source:
Returns:
Type
Promise.<boolean>

(async) rotate(grantSet) → {Promise.<GrantSet>}

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.

Parameters:
Name Type Description
grantSet GrantSet
Source:
Returns:
Type
Promise.<GrantSet>

(async, static) discover(config) → {Promise.<GNAPClient>}

Creates a client and loads the AS's discovery document.

Parameters:
Name Type Description
config GNAPClientConfig
Source:
Returns:
Type
Promise.<GNAPClient>