embassy

import { Claims, DomainScopes, JWTHeader, Serializable, TokenOptions, TokenSigningOptions, TokenVerificationOptions } from './types'; export declare class Token { private scopesLastUpdate; private opts; private token; private domainBlobs; claims: Claims; header: JWTHeader; /** * Creates a new Token. * * @param opts - An object mapping of configuration objects * @throws {@link TokenParseError} * Thrown if the provided token cannot be parsed */ constructor(opts?: TokenOptions); /** * Gets the content of a domain-specific option. * * @param domain - The domain containing the requested option * @param key - The name of the option for which the value should be retrieved * @returns The value of the requested option, or undefined */ getOption<T extends Serializable>(domain: string, key: string): T | undefined; /** * Grants the given scope to this token within the specified domain. * * @param domain - The domain that contains the scope to be granted * @param scope - The name of the scope to be granted */ grantScope(domain: string, scope: string): Promise<void>; /** * Grants the given scope to this token. If the scope string contains a `|` * character, the string up to the first `|` will be used as the domain under * which the scope will be grouped. Otherwise, the default domain of `app` * will be used. * * @param combined - The scope string to be granted, optionally containing a * domain in the format `domain|scopeName` */ grantScope(combined: string): Promise<void>; /** * Grants the given array of scopes to this token. * * @param domainScopes - A map of domains to arrays of scopes in that domain * to be granted to the token */ grantScopes(domainScopes: DomainScopes): Promise<void>; /** * Grants the given array of scopes to this token. * * @param combined - An array of strings in the format `domain|scope`. If the * domain portion is missing, the default scope of "app" will be used. */ grantScopes(combined: string[]): Promise<void>; /** * Checks to see whether this token contains the given scope. * * @param domain - The domain that contains the scope to be checked * @param scope - The scope to be checked * @returns `true` if the scope is included in this Token; `false` otherwise. */ hasScope(domain: string, scope: string): Promise<boolean>; /** * Checks to see whether this token contains the given scope. If the scope * string contains a `|` character, the string up to the first `|` will be * used as the domain under which the scope will be grouped. Otherwise, the * default domain of `app` will be used. * * @param combined - The scope string to be checked, optionally containing a * domain in the format `domain|scopeName` */ hasScope(combined: string): Promise<boolean>; /** * Checks this token for the given scopes in the DomainScopes map. * * @param domainScopes - A map of domains to arrays of scopes in that domain * to be checked * @returns `true` if every scope of every domain exists on this Token; * `false` otherwise */ hasScopes(domainScopes: DomainScopes): Promise<boolean>; /** * Checks this token for the given scopes in the provided array. * * @param combined - An array of strings in the format `domain|scope`. If the * domain portion is missing, the default scope of "app" will be used. * @returns `true` if every scope of every domain exists on this Token; * `false` otherwise */ hasScopes(combined: string[]): Promise<boolean>; /** * Revokes a scope that has been previously granted. This method is idempotent * and will not fail when revoking scopes that have not been granted. * * @param domain - The domain that contains the scope to be revoked * @param scope - The name of the scope to be revoked */ revokeScope(domain: string, scope: string): Promise<void>; /** * Revokes a scope that has been previously granted. This method is idempotent * and will not fail when revoking scopes that have not been granted. * * If the scope string contains a `|` character, the string up to the first * `|` will be used as the domain under which the scope will be grouped. * Otherwise, the default domain of `app` will be used. * * @param combined - The scope string to be revoked, optionally containing a * domain in the format `domain|scopeName` */ revokeScope(combined: string): Promise<void>; /** * Revokes a list of scopes that have been previously granted. This method is * idempotent and will not fail when revoking scopes that have not been * granted. * * @param domainScopes - A map of domains to arrays of scopes in that domain * to be revoked from the token */ revokeScopes(domainScopes: DomainScopes): Promise<void>; /** * Revokes a list of scopes that have been previously granted. This method is * idempotent and will not fail when revoking scopes that have not been * granted. * * @param combined - An array of strings in the format `domain|scope`. If the * domain portion is missing, the default scope of "app" will be used. */ revokeScopes(combined: string[]): Promise<void>; /** * Sets a domain-specific option on this token. Options are meant for holding * non-boolean settings. For boolean values, consider defining a new scope for * this domain. All options are stored in the `opt` claim at the top level. * * @param domain - The domain in which to set the given option * @param key - The name of the option to be set * @param val - The value for the option */ setOption(domain: string, key: string, val: Serializable): void; /** * Serializes the claims within this Token and signs them cryptographically. * The result is an encoded JWT token string. * * @param kid - An identifier for the key with which to sign this token. The * private key or HMAC secret must either exist in the `keys` map passed in * the constructor options, or be retrievable by the `getPrivateKey` function * provided to the constructor. * @param opts - Options to configure the token signing process * @returns the signed and encoded token string. * @throws {@link Error} * Throws if options.subject was not specified, and the 'sub' claim has not * been set. A subject is a required claim for a valid JWT. */ sign(kid: string, opts?: TokenSigningOptions): Promise<string>; /** * Verifies a token's validity by checking its signature, expiration time, * and other conditions. * * @param opts - Options to customize how the token is verified * @returns the token's claims when successfully verified. * @throws {@link TokenExpiredError} * Thrown when a token has passed the date in its `exp` claim * @throws {@link JsonWebTokenError} * Thrown for most verification issues, such as a missing or invalid * signature, or mismatched audience or issuer strings * @throws {@link NotBeforeError} * Thrown when the date in the `nbf` claim is in the future */ verify(opts?: TokenVerificationOptions): Promise<Claims>; /** * Decodes the `scope` claim into a mapping of domain string to byte array, * stored in `this.domainBlobs`. */ private decodeBlobs; /** * Encodes `this.domainBlobs` into a single string in the format * `domain1:base64perms1;domain2:base64perms2` (etc) and stores it into the * `scope` claim. */ private encodeBlobs; /** * Retrieves a byte array from the set of domain blobs, resizing it if * necessary. * * @param domain - The domain string for which to get the binary scopes blob * @param minBytes - The number of bytes the resulting array should have in * it, at minimum * @returns The byte array for the given domain */ private getBlob; /** * Retrieves the private key definition for a specified key ID. This function * will first attempt to pull the private key (and associated algorithm) from * the `keys` object passed to the constructor, and if not found there, will * call the `getPrivateKey` function passed to the constructor if one exists. * If a private key is found through that method, it will be saved back to the * provided `keys` object to avoid calling `getPrivateKey` for the same key ID * again. * * @param kid - The key ID of the private key definition to be retrieved * @returns the appropriate private key definition * @throws {@link KeyNotFoundError} * Thrown if the function expires all avenues by which to locate the * referenced private key. */ private getPrivateKeyDefinition; /** * Retrieves the public key for a specified key ID. The algorithm is required * so that the function knows to look for a private "key" for symmetric * signing algorithms, and a public key for asymmetric. If the key not does * exist in the `keys` option passed to the constructor, this function will * attempt to use `getPublicKey` if it exists, caching the successful result * back in the `keys` object for next time. * * @param kid - The key ID of the key to be retrieved * @param algorithm - The algorithm that the key is meant for * @returns the specified verification key, in PEM-encoded format for * asymmetric public keys or the HMAC secret string. * @throws {@link KeyNotFoundError} * Thrown if the function expires all avenues by which to locate the * referenced key. */ private getVerificationKey; /** * Gets the binary components of an individual scope, targeting the bit * that can be read or changed to interact with the encoded scope. * * @param domain - The domain containing the target scope * @param scope - The name of the scope for which to retrieve the components * @param resize - `true` to resize the resulting blob to fit the chosen scope * bit; `false` to return it in the currently stored size * @returns The components of the given scope */ private getScopeComponents; /** * Gets the index of the specified scope from the domainScopes map. If it's * not found, this method attempts to refresh that map with the refreshScopes * method before throwing a ScopeNotFoundError. * * @param domain - The domain containing the target scope * @param scope - The name of the target scope * @param noRetry - `true` to not attempt to refresh the domainScopes map and * retry this function; `false` to throw {@link ScopeNotFoundError} * immediately when a scope doesn't exist in domainScopes. * @returns the index of the target permission * @throws {@link ScopeNotFoundError} * Thrown if the given scope does not exist in the domainScopes object and * did not appear when refreshing the domainScopes. */ private getScopeIndex; }