Skip to content
the absolute minimum to make JSON Web Tokens on deno. Based on JWT and JWS specifications.
TypeScript
Branch: master
Clone or download
Latest commit 9197777 Oct 15, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Fixed typo and test travis Oct 12, 2019
.travis.yml added the .travis.yml file and made minor changes Oct 1, 2019
LICENSE
README.md
create.ts fixed minor mistake Oct 15, 2019
test.ts fixed travis test Oct 12, 2019
validate.ts validateJwt returns the JWT object now and made small improvements Oct 12, 2019

README.md

djwt

The absolute minimum to make JSON Web Tokens on deno. Based on JWT and JWS specifications.

This library is a registered Deno Module and accessible through the https://deno.land/x/ service.

Features

We use the mandatory Compact Serialization process where a web token is represented as the concatenation of

'BASE64URL(UTF8(JWS Protected Header))' || '.' || 'BASE64URL(JWS Payload)' ||'.'|| 'BASE64URL(JWS Signature)'

...to generate JWTs which look in their finalized form like this:

 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
 .
 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
 .
 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Cryptographic Algorithm

Of the signature and MAC algorithms defined in the JSON Web Algorithms (JWA) specification, only HMAC SHA-256 ("HS256"), HMAC SHA-512 ("HS512") and none have been implemented already. But more shall come soon.

Expiration Time

The optional exp claim identifies the expiration time on or after which the JWT must not be accepted for processing. This library checks if the current date/time is before the expiration date/time listed in the exp claim.

Critical Header

This library supports the Critical Header Parameter crit which is described in the JWS specification here.

Look up this example to see how the crit header parameter works.

API

The API consists mostly of the two functions makeJwt and validateJwt, generating and validating a JWT, respectively.

You can omit the JWT payload and its claims if you only need the signing and verification feature of the JWS. The function makeJwt returns the url-safe encoded JWT:

makeJwt(header: Jose, claims: Claims, key: string): string

The function validateJwt returns a promise which - if the JWT is valid - resolves to the JWT as JavaScript object: {header, payload, signature}.

validateJwt(jwt: string, key: string, throwErrors: boolean = true, critHandlers: Handlers = {}): Promise

Additionally there is the helper function setExpiration which simplifies setting an expiration date.

setExpiration(exp: number | Date): number

// A specific date:
setExpiration(new Date("2020-07-01"))
// One hour from now:
setExpiration(new Date().getTime() + 60 * 60 * 1000)

Example

Try djwt out with this simple server example:

The server will respond to a GET request with a newly created JWT.
On the other hand, if you send a JWT as data along with a POST request, the server will check the validity of the JWT.

import { serve } from "https://deno.land/std/http/server.ts"
import { encode, decode } from "https://deno.land/std/strings/mod.ts"
import makeJwt, { setExpiration } from "https://deno.land/x/djwt/create.ts"
import validateJwt from "https://deno.land/x/djwt/validate.ts"

const key = "abc123"
const claims = {
  iss: "joe",
  exp: setExpiration(new Date().getTime() + 60000),
}
const header = {
  alg: "HS512",
  typ: "JWT",
}
;(async () => {
  for await (const req of serve("0.0.0.0:8000")) {
    if (req.method === "GET") {
      const jwt = makeJwt(header, claims, key)
      req.respond({ body: encode(jwt + "\n") })
    } else {
      const requestBody = decode(await req.body())
      ;(await validateJwt(requestBody, key, false))
        ? req.respond({ body: encode("Valid JWT\n") })
        : req.respond({ status: 401, body: encode("Invalid JWT\n") })
    }
  }
})()

Contribution

Every kind of contribution to this project is highly appreciated.

Todo

  1. Add more optional features from the JWT and JWS specifications
  2. Improve documentation
  3. Make more tests
You can’t perform that action at this time.