Class: JWS

@nginstack/engine/lib/jose/JWS~ JWS


new JWS()

Classe utilizada para geração, leitura e validação de tokens JWS.

A versão atual não suporta tokens com conteúdo binário, apenas tokens formados por um conjunto de declarações.

O formato de serialização utilizado é o formato compacto.

Members


algorithm :Algorithm

Identifica o algoritmo criptográfico utilizado para assinar este token.

Esta propriedade corresponde à declaração "alg" em headers. Ao ler ou atribuir esta propriedade, o valor será lido ou atribuído em headers.

Type:
  • Algorithm
Default Value:
  • 'HS256'
Example
const jws = new JWS();
jws.algorithm = 'RS256';
jws.headers.alg // => 'RS256'

audience :string

Identifica a quem esse token se destina. O token deverá ser rejeitado se o valor informado não for o esperado por quem for processar o token.

Esta propriedade corresponde à declaração "aud" em claims. Ao ler ou atribuir esta propriedade, o valor será lido ou atribuído em claims.

Type:
  • string
Example
const jws = new JWS();
jws.audience = 'test';
jws.claims.aud // => 'test'

claims :Record.<string, (string|number|boolean)>

Objeto que representa um conjunto de declarações, no formato chave/valor, e que compõem o conteúdo do token.

Type:
  • Record.<string, (string|number|boolean)>

criticalHeaders :Array

Identifica os cabeçalhos críticos. Cabeçalhos críticos precisam ser suportados pelo receptor do token.

Type:
  • Array

expiresAt :Date

Identifica o momento a partir do qual esse token deve ser considerado expirado. Ao ler um token, se essa propriedade estiver definida e corresponder a um momento no passado, o token deve ser rejeitado.

Esta propriedade corresponde à declaração "exp" em claims. Ao ler ou atribuir esta propriedade, o valor será lido ou atribuído em claims.

Type:
  • Date
Example
const jws = new JWS();
jws.expiresAt = incDate(new Date());
jws.expiresAt  // => (date object)
jws.claims.exp // => (date in seconds)

headers :Record.<string, (string|number|boolean)>

Objeto contendo as propriedades de cabeçalho do token.

Type:
  • Record.<string, (string|number|boolean)>

issuedAt :Date

Identifica o momento em que esse token foi emitido. No momento da assinatura, se essa propriedade não estiver preenchida, ela será preenchida automaticamente. Esse comportamento pode ser desativado informando a propriedade 'disableDefaultTimestamp' com valor 'true' nas opções de assinatura.

Esta propriedade corresponde à declaração "iat" em claims. Ao ler ou atribuir esta propriedade, o valor será lido ou atribuído em claims.

Type:
  • Date
Example
const jws = new JWS();
jws.issuedAt = new Date();
jws.claims.iat // => (date in seconds)

issuer :string

Identifica o emissor do token.

Esta propriedade corresponde à declaração "iss" em claims. Ao ler ou atribuir esta propriedade, o valor será lido ou atribuído em claims.

Type:
  • string
Example
const jws = new JWS();
jws.issuer = 'NGINSTACK';
jws.claims.iss // => 'NGINSTACK'

jwtId :string

Identificador único do token. O emissor do token deve garantir que dois tokens não possuam um mesmo valor para essa propriedade.

Esta propriedade corresponde à declaração "jti" em claims. Ao ler ou atribuir esta propriedade, o valor será lido ou atribuído em claims.

Type:
  • string
Example
const jws = new JWS();
jws.jwtId = 'A unique ID';
jws.claims.jti // => 'A unique ID'

keyId :string

Identifica a chave que foi utilizada para assinar este token.

Esta propriedade corresponde à declaração "kid" em headers. Ao ler ou atribuir esta propriedade, o valor será lido ou atribuído em headers.

Type:
  • string
Example
const jws = new JWS();
jws.keyId = 'A unique ID';
jws.headers.kid // => 'A unique ID'

notBefore :Date

Identifica o momento em que esse token passa a valer. Ao ler um token, se essa propriedade estiver definida e corresponder a um momento no futuro, o token deve ser rejeitado.

Esta propriedade corresponde à declaração "nbf" em claims. Ao ler ou atribuir esta propriedade, o valor será lido ou atribuído em claims.

Type:
  • Date
Example
const jws = new JWS();
jws.notBefore = new Date();
jws.notBefore  // => (date object)
jws.claims.nbf // => (date in seconds)

subject :string

Identifica o assunto ao qual o token se refere.

Esta propriedade corresponde à declaração "sub" em claims. Ao ler ou atribuir esta propriedade, o valor será lido ou atribuído em claims.

Type:
  • string
Example
const jws = new JWS();
jws.subject = 'test';
jws.claims.sub // => 'test'

Methods


<static> parse(token, key [, options])

Realiza o parse e validação do token recebido, retornando uma instância da classe JWS.

Parameters:
Name Type Argument Description
token string

Token para leitura.

key string | ArrayBuffer | Uint8Array | CryptoPKey

Chave de criptografia utilizada na validação da assinatura. Se for uma instância de CryptoPKey, nela deve haver uma chave pública criada ou importada. Se for uma String, será utilizada a sua representação binária em UTF-8.

options VerifyOptions <optional>

Opções de verificação do token.

Returns:

Instância da classe JWS populada com os dados do token.

Type
JWS
Examples
const jws = JWS.parse('AAA.BBB.CCC', 'password');
const publicKey = CryptoPKey.importPublicKey('der', File.stringFromFile('filename'), 'RSA');
const jws = JWS.parse('AAA.BBB.CCC', publicKey);

<static> parseHeader(token)

Realiza o parse apenas do cabeçalho, sem realizar qualquer validação. Este método é util, por exemplo, para obter o identificador da chave JWK utilizada na assinatura do token.

Parameters:
Name Type Description
token string

Token JWS que se deseja inspecionar os dados do cabeçalho.

Returns:

Objeto javascript com as propriedades correspondendo aos campos do cabeçalho.

Type
Object

<static> sign(payload, key [, options])

Realiza a assinatura dos dados do token. Se o conteúdo for um objeto e não houver a propriedade 'iat' preenchida, ela será preenchida automaticamente com data e hora corrente. Esse comportamento pode ser desativado informando a propriedade 'disableDefaultTimestamp' com valor 'true' nas opções de assinatura.

Parameters:
Name Type Argument Description
payload Object

Objeto com as declarações.

key string | ArrayBuffer | Uint8Array | CryptoPKey

Chave de criptografia utilizada na assinatura. Se for uma instância de CryptoPKey, nela deve haver uma chave privada criada ou importada. Se for uma String, será utilizada a sua representação binária em UTF-8.

options Object <optional>

Parâmetros adicionais.

Properties
Name Type Argument Description
algorithm string <optional>

Identifica o algoritmo criptográfico utilizado para assinar este token.

issuer string <optional>

Identifica o emissor do token.

subject string <optional>

Identifica o assunto ao qual o token se refere.

audience string <optional>

Identifica a quem esse token se destina.

issuedAt Date <optional>

Identifica o momento em que esse token foi emitido.

notBefore Date <optional>

Identifica o momento em que esse token passa a valer.

expiresAt Date <optional>

Identifica o momento a partir do qual esse token deve ser considerado expirado.

jwtId string <optional>

Identificador único do token.

keyId string <optional>

Identifica a chave que foi utilizada para assinar este token.

customHeaders Object <optional>

Identifica os cabeçalhos customizados.

criticalHeaders Array <optional>

Identifica os cabeçalhos críticos.

disableDefaultTimestamp boolean <optional>

Informa que a propriedade 'iat' do token gerado não deve ser preenchida com a data atual, caso não tenha sido informada.

Returns:

Token JWS assinado.

Type
string

<static> verify(token, key [, options])

Verifica a assinatura e demais informações contidas no token. Entre as opções passadas pode haver opções de desativação de verificação de algum ponto como data de expiração, por exemplo.

Parameters:
Name Type Argument Description
token string

Conteúdo do token a ser validado.

key string | CryptoPKey

Chave de criptografia que deve ser utilizada na validação. Se for uma instância de CryptoPKey, nela deve haver uma chave pública criada ou importada.

options VerifyOptions <optional>

Opções de verificação do token.

Returns:

Objeto que representa o conteúdo do token.

Type
Object

sign(key [, options])

Realiza a assinatura deste token, retornando uma string com a sua representação compacta.

Se o conteúdo for um objeto e não houver a propriedade 'iat' preenchida, ela será preenchida automaticamente com data e hora corrente. Esse comportamento pode ser desativado informando a propriedade 'disableDefaultTimestamp' com valor 'true' nas opções de assinatura.

Parameters:
Name Type Argument Description
key string | CryptoPKey

Chave de criptografia utilizada na assinatura. Se for uma instância de CryptoPKey, nela deve haver uma chave privada criada ou importada.

options Object <optional>

Parâmetros adicionais.

Properties
Name Type Argument Description
disableDefaultTimestamp boolean <optional>

Informa que a propriedade 'iat' do token gerado não deve ser preenchida com a data atual, caso não tenha sido informada.

Returns:

Token montado e assinado.

Type
string
Examples
const jws = new JWS();
jws.issuer = 'NGINSTACK';
jws.claims.name = 'José';
const token = jws.sign('password');
const privateKey = CryptoPKey.importPrivateKey('der', File.stringFromFile('filename'), 'RSA');
const jws = new JWS();
jws.issuer = 'NGINSTACK';
jws.claims.name = 'José';
jws.algorithm = Algorithm.RS256;
const token = jws.sign(privateKey);