ts-jose

TS JOSE

Wrap functions of JOSE in steady interface.

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

JWT

verify

ref

const options = {
  algorithms: ['a1', 'a2'], // accepted algorithms
  audience: 'hi', // string or string[], accept audience
  clockTolerance: '3s',
  complete: true, // true to return header+payload else return payload only, default: false
  crit: { 'some-key': true },
  currentDate: new Date(),
  issuer: 'some-issuer', // issuer, who made this token
  jti: 'some-token-id', // token id, often be random
  maxTokenAge: '5m', // expiration
  subject: 'some-user-id', // what this token represent, often be user ID
  typ: 'ac+jwt', // make it easy to decide what token is this
};

await JWT.verify(token, key, options); // key must be JWK or JWKS
await JWT.verify(token, undefined, options); // this will try to verify by embedded key

sign

ref

const options = {
  alg: 'ES256',
  audience: 'hi', // string or string[]
  exp: '3h', // string or number, 3h means expired in 3 hours, detail in [ref]
  iat: 123,
  issuer: 'some-issuer', // issuer, who made this token
  jti: 'some-token-id', // token id, often be random
  jwk: true, // true to embedded key, default: false
  kid: 'some-key-id', // often use to specify key in key store
  notBefore: '1s', // string or number, invalid if earlier than this time
  subject: 'some-user-id', // what this token represent, often be user ID
  typ: 'ac+jwt', // make it easy to decide what token is this
};

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

decrypt

ref

const options = {
  audience: 'hi', // string or string[]
  clockTolerance: '3s',
  complete: true, // true to return header+payload else return payload only, default: false
  enc: ['A128GCM'], // string or string[], content encryption algorithms
  crit: { 'some-key': true },
  currentDate: new Date(),
  issuer: 'some-issuer',
  jti: 'some-token-id',
  alg: ['ECDH-ES+A128KW'], // string or string[], key management algorithms
  kid: 'some-key-id',
  maxTokenAge: '5m',
  typ: 'ac+jwt', // make it easy to decide what token is this
};

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

encrypt

ref

const options = {
  alg: 'A128GCMKW', // key management
  audience: 'hi', // string or string[], accepted audience
  crit: { 'some-key': true },
  enc: 'A128CBC-HS256', // encrypt algorithm
  exp: '3h', // string or number
  iat: 123,
  issuer: 'some-issuer',
  jti: 'some-token-id',
  kid: 'some-key-id',
  notBefore: '1s',
};

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

JWS

You can sign pure string.

verify

ref

const options = {
  algorithms: ['ES256', 'ES192'],
  crit: { key: true },
  typ: 'some-type',
};

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

sign

ref

const options = {
  alg: 'ES256',
  kid: 'some-key-id',
  jwk: true, // embedded key
  typ: 'some-type',
};

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

JWE

You can encrypt pure string.

decrypt

ref

const options = {
  alg: 'ECDH-ES+A128KW', // string or string[]
  enc: ['A128GCM'], // string or string[]
  kid: 'some-key-id',
};

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

encrypt

ref

const options = {
  alg: 'ECDH-ES+A128KW', // string
  enc: 'A128GCM', // string
  crit: { 'some-key': true },
  kid: 'some-key-id',
};

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

JWK

ref

// generate key
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
await JWK.fromObject({
  kid: 'some-id',
  alg: 'ES256',
  kty: 'EC',
  crv: 'P-256',
  x: '123',
  y: '456',
  d: '789',
});

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

// private JWK to public JWK
await key.toPublic();

// get key's status
key.isisPrivate;

// check key "id", "use", "alg"
try {
  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('ES256', {
  keys: [
    {
      alg: 'ES256',
      kty: 'EC',
      x: '123',
      y: '456',
    },
  ],
});

keys.getKey({ kid: 'some-id', use: 'sig', alg: 'ES256' });
keys.getKeyByKid('some-id');
keys.getKeyByUse('sig');
keys.getKeyByAlg('ES256');