TS JOSE

Wrap functions of JOSE in steady interface.

[!Note]

This package's version will FOLLOW the version of JOSE

• JWT
  • verify
  • sign
  • decrypt
  • encrypt
• JWS
  • verify
  • sign
• JWE
  • decrypt
  • encrypt
• JWK
• JWKS

JWT

verify

JOSE ref

Additional options

| name | Description | | ---- | ---------------------------- | | kid | Using specific key in JWKS | | jti | Verify payload jti |

// `key` must be JWK or JWKS.
await JWT.verify(token, key, options);
// Use embedded key instead given one.
await JWT.verify(token, undefined, options);

sign

• JOSE ref for payload
• JOSE ref for header

Using JOSE options

| name | Referrer | | --------- | ----------------- | | issuer | setIssuer | | audience | setAudience | | subject | setSubject | | exp | setExpirationTime | | jti | setJti | | notBefore | setNotBefore | | iat | setIssuedAt | | typ | Header | | kid | Header | | alg | Header |

Additional options

| name | type | default | description | | ---- | --------- | ------- | ------------------------------ | | jwk | boolean | false | Whether embedded key to header |

await JWT.sign(payload, key, options); // key must be JWK or JWKS

decrypt

JOSE ref

Additional options

| name | Description | | ---- | ---------------------------- | | kid | Using specific key in JWKS | | enc | Encrypt algorithm | | alg | Key management algorithm |

await JWT.decrypt(cypher, key, options);

encrypt

JOSE ref

Using JOSE options

| name | Referrer | | --------- | ----------------- | | issuer | setIssuer | | audience | setAudience | | subject | setSubject | | exp | setExpirationTime | | jti | setJti | | notBefore | setNotBefore | | iat | setIssuedAt | | typ | Header | | kid | Header | | enc | Header | | alg | Header |

await JWT.encrypt(payload, key, options);

JWS

You can sign pure string.

verify

JOSE ref

await JWS.verify(data, key, options);

sign

JOSE ref

Only using below JWT.sign's options:

• typ
• kid
• alg
• jwk

await JWS.sign('some-data', key, options);

JWE

You can encrypt pure string.

decrypt

JOSE ref

Additional options

Same as JWT.decrypt

await JWE.decrypt(cypher, key, options);

encrypt

JOSE ref

Only using below JWT.encrypt's options:

• kid
• alg
• enc

await JWE.encrypt('some-data', key, options);

JWK

JOSE ref

// generate key
const key: JWK = await JWK.generate('ES256', {
  kid: 'some-id',
  use: 'sig',
  // crv: string, some algorithms need to add curve - EdDSA
  // modulusLength: number, some algorithms need to add length - RSA
});

// object to JWK
const key: JWK = await JWK.fromObject({
  kid: 'some-id',
  alg: 'ES256',
  kty: 'EC',
  crv: 'P-256',
  x: '123',
  y: '456',
  d: '789',
});

// JWK to object
const keyObject: JWKObject = key.toObject(false); // true to output private object, default: false

// private JWK to public JWK
const newKey: JWK = await key.toPublic();

// get key's status
key.isPrivate;

// check key "id", "use", "alg"
try {
  // return `this` if all pass
  key.getKey({ kid: 'some-id', use: 'sig', alg: 'ES256' });
} catch (err) {
  // throw error if this key has different metadata from options
}

JWKS

// object to JWKS
const keys = await JWKS.fromObject({
  keys: [
    {
      alg: 'ES256',
      kty: 'EC',
      x: '123',
      y: '456',
    },
  ],
});

// get key from store in specific options
try {
  const key: JWK = keys.getKey({ kid: 'some-id', use: 'sig', alg: 'ES256' });
} catch (err) {
  // throw error if not found
}
const key: JWK = keys.getKeyByKid('some-id');
const key: JWK = keys.getKeyByUse('sig');
const key: JWK = keys.getKeyByAlg('ES256');
const publicKeys = await keys.toPublic();