gnap-caep-client
    Preparing search index...

    Class GNAPClient

    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.

    Hierarchy (View Summary)

    Index
    metadata: Record<string, any>

    The AS's discovery document.

    • get config(): {
          access?: (string | Record<string, any>)[];
          alg?: string;
          allowInsecureRequests: boolean;
          assertionFormats: any[];
          classId?: string;
          clockToleranceSec: number;
          discoveryCacheTtlMs?: number;
          display?: { logo_uri?: string; name?: string; uri?: string };
          finishUri?: string;
          grantEndpoint: any;
          hashMethod: string;
          httpTimeoutMs: number;
          idToken?: {
              algorithms?: string[];
              audience?: string | string[];
              issuer: string;
              jwksUri?: string;
          };
          keyProof: string;
          maxWaitSec: number;
          requireBoundTokens: boolean;
          signals?: boolean;
          subIdFormats: any[];
          subject: false
          | { assertionFormats?: string[]; subIdFormats?: string[] };
          transactionTtlSec: number;
          useInstanceId: boolean;
      }

      The effective settings, for display.

      Returns {
          access?: (string | Record<string, any>)[];
          alg?: string;
          allowInsecureRequests: boolean;
          assertionFormats: any[];
          classId?: string;
          clockToleranceSec: number;
          discoveryCacheTtlMs?: number;
          display?: { logo_uri?: string; name?: string; uri?: string };
          finishUri?: string;
          grantEndpoint: any;
          hashMethod: string;
          httpTimeoutMs: number;
          idToken?: {
              algorithms?: string[];
              audience?: string | string[];
              issuer: string;
              jwksUri?: string;
          };
          keyProof: string;
          maxWaitSec: number;
          requireBoundTokens: boolean;
          signals?: boolean;
          subIdFormats: any[];
          subject: false
          | { assertionFormats?: string[]; subIdFormats?: string[] };
          transactionTtlSec: number;
          useInstanceId: boolean;
      }

      • Optionalaccess?: (string | Record<string, any>)[]

        The access rights to request by default (section 8): reference strings such as "ssf.read", or objects with type, actions, ...

      • Optionalalg?: string

        Client key algorithm (default ES256).

      • allowInsecureRequests: boolean
      • assertionFormats: any[]
      • OptionalclassId?: string

        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.

      • clockToleranceSec: number
      • OptionaldiscoveryCacheTtlMs?: number

        How long a discovery document is cached (default 1h).

      • Optionaldisplay?: { logo_uri?: string; name?: string; uri?: string }

        What the approval page shows about this client (section 2.3.2): self-declared, never a reason for more trust.

      • OptionalfinishUri?: string

        Where the AS sends the browser back after interaction (the redirect finish URI, section 2.5.2). Required for a redirect interaction.

      • grantEndpoint: any
      • hashMethod: string
      • httpTimeoutMs: number
      • OptionalidToken?: {
            algorithms?: string[];
            audience?: string | string[];
            issuer: string;
            jwksUri?: string;
        }

        Verify an id_token subject assertion against this issuer's keys. Without it, an assertion is kept as received and never decoded.

      • keyProof: string
      • maxWaitSec: number
      • requireBoundTokens: boolean
      • Optionalsignals?: boolean

        CAEP and RISC. Omitted or true is on. false removes ssf.read and ssf.manage from the grant request. The subject request is unchanged.

      • subIdFormats: any[]
      • subject: false | { assertionFormats?: string[]; subIdFormats?: string[] }
      • transactionTtlSec: number
      • useInstanceId: boolean
    • get securityFeatures(): {
          boundTokens: string;
          clientKey: | { alg: string; extractable: boolean; thumbprint: string }
          | undefined;
          continuationOrigin: string;
          finishNonce: string;
          idTokenAssertion: string;
          interactionHash: string;
          keyProof: string;
          subject: string;
          tlsEnforced: boolean;
      }

      Which security features are active, for display and audit.

      Returns {
          boundTokens: string;
          clientKey:
              | { alg: string; extractable: boolean; thumbprint: string }
              | undefined;
          continuationOrigin: string;
          finishNonce: string;
          idTokenAssertion: string;
          interactionHash: string;
          keyProof: string;
          subject: string;
          tlsEnforced: boolean;
      }

    • 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

      • response: string | Record<string, string> | URLSearchParams

        The finish URL, or its query parameters.

      Returns Promise<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.

      Parameters

      • response: string | Record<string, string> | URLSearchParams

      Returns Promise<{ context: any; grantSet: GrantSet }>

    • 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

      • Optionalopts: {
            access?: (string | Record<string, any>)[];
            context?: any;
            expectedSub?: string;
            extra?: Record<string, any>;
            flags?: string[];
            label?: string;
            subject?: boolean;
            user?: Record<string, any>;
        } = {}
        • Optionalaccess?: (string | Record<string, any>)[]

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

        • Optionalcontext?: any

          JSON-serialisable data handed back by completeGrant().

        • OptionalexpectedSub?: string

          Refuse a grant approved by anybody else (account_mismatch).

        • Optionalextra?: Record<string, any>

          Further top-level members of the grant request.

        • Optionalflags?: string[]

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

        • Optionallabel?: string

          A label for the access token.

        • Optionalsubject?: boolean

          false asks for no subject information in this request.

        • Optionaluser?: Record<string, any>

          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.

      Returns Promise<{ context?: any; grantSet?: GrantSet; url?: string }>

    • 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

      • token: string | GrantSet | { access_token: string; bearer?: boolean }
      • url: string
      • Optionalinit: RequestInit & { body?: string } = {}

      Returns Promise<Response>

    • 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

      • grantSet: GrantSet
      • changes: { access: (string | Record<string, any>)[] }

      Returns Promise<GrantSet>

    • 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

      • token: string | GrantSet | { access_token: string; bearer?: boolean }
      • request: {
            body?: string;
            headers?: Record<string, string>;
            method?: string;
            url: string;
        }

      Returns Promise<Record<string, string>>

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

      Parameters

      • grantSet: GrantSet | { continue: { access_token: { value: string }; uri: string } }

      Returns Promise<boolean>