# ywt
ywt is a suite of Gleam-native JWT packages. This is the `ywt_webcrypto` package, providing cryptographic routines
using the `SubtleCrypto` web api to ywt. It supports the server as well as the browser.
[](https://hex.pm/packages/ywt_core)
[](https://hexdocs.pm/ywt_core/)
[](https://hex.pm/packages/ywt_erlang)
[](https://hexdocs.pm/ywt_erlang/)
[](https://hex.pm/packages/ywt_webcrypto)
[](https://hexdocs.pm/ywt_webcrypto/)
```sh
gleam add ywt_core@1 ywt_webcrypto@1
```
ywt supports symmetrically as well as asymmetrically signed JWTs and can be used
on the client as well as the server using an almost identical API.
Instead of wrapping existing libraries, ywt uses the underlying platform APIs
for cryptography - the `public_key` application and `WebCrypto` - directly with
minimal amounts of straightforward FFI. This keeps most code related to parsing,
validating and signing JWTs in pure Gleam, reducing the surface area.
## Supported Algorithms
- `HS256` - HMAC with SHA-256
- `HS384` - HMAC with SHA-384
- `HS512` - HMAC with SHA-512
- `ES256` - ECDSA using the P-256 (secp256r1) curve and SHA-256
- `ES384` - ECDSA using the P-384 (secp384r1) curve and SHA-384
- `ES512` - ECDSA using the P-512 (secp521r1) curve and SHA-512
- `RS256` - RSA PKCS#1 v1.5 with SHA-256
- `RS384` - RSA PKCS#1 v1.5 with SHA-384
- `RS512` - RSA PKCS#1 v1.5 with SHA-512
- `PS256` - RSA PSS with SHA-256
- `PS384` - RSA PSS with SHA-384
- `PS512` - RSA PSS with SHA-512
## Important Security Considerations
JWTs are often misused. You can think of them as signed structured cookies.
All information you store in a JWT is publically readable even without access
to a coresponding key and/or after the token has expired or got revoked.
JWTs do not have a built-in method for revokation. ywt does does not add claims
by default. It is paramount to at least at an `expired_at` claim. The standard
requires implementations to reject tokens and keys with unknown fields, but
ywt silently ignores them as a consequence of using the `decode` API. ywt does
not validate `key_ops` or `use` fields. ywt does not support validating a
certificate chain or encrypted/nested keys.
## Example
```gleam
import gleam/string
import gleam/dynamic/decode
import gleam/io
import gleam/json
import gleam/time/duration
import ywt
import ywt/algorithm
import ywt/claim
import ywt/verify_key
pub fn main() -> Nil {
// Generate a new, random signing key
let signing_key = ywt.generate_key(algorithm.es384)
// Create user payload data
let payload = [
#("sub", json.string("user123")),
#("role", json.string("admin")),
]
// Define security claims
let claims = [
claim.expires_at(max_age: duration.hours(1), leeway: duration.minutes(5)),
claim.issuer("https://auth.myapp.com", []),
claim.audience("https://api.myapp.com", []),
]
// Create and sign the JWT
let jwt = ywt.encode(payload, claims, signing_key)
io.println("Signed JWT: " <> jwt)
// Extract verification key (for distribution to other services)
let verify_key = verify_key.derived(signing_key)
io.println(
"Public verification key: " <> json.to_string(verify_key.to_jwk(verify_key)),
)
// Verify the JWT
let decoder = {
use id <- decode.field("sub", decode.string)
use role <- decode.field("role", decode.string)
decode.success(#(id, role))
}
let result = ywt.decode(jwt, using: decoder, claims:, keys: [verify_key])
case result {
Ok(#(id, role)) -> {
io.println("JWT verified successfully!")
io.println("User id: " <> id)
io.println("User role: " <> role)
}
Error(ywt.TokenExpired(_expired_at)) -> {
io.println("Token expired!")
}
Error(ywt.InvalidSignature) -> {
io.println("Invalid signature - token may be forged")
}
Error(error) -> {
io.println("JWT verification failed: " <> string.inspect(error))
}
}
}
```
## Development
Tests are shared by both targets and can be run from their individual package directories.
## Resources:
- JWT debugger: [jwt.io](https://jwt.io/)
- JWT (Json Web Tokens): [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519)
- JWS (Json Web Signatures): [RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515)
- JWK (Json Web Keys): [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517)
- JWA (Json Web Algorithms): [RFC 7518](https://datatracker.ietf.org/doc/html/rfc7518)
- Elliptic Curve Cryptography: [RFC 5480](https://www.rfc-editor.org/rfc/rfc5480)
- RSA: [RFC 3447](https://datatracker.ietf.org/doc/html/rfc3447)
- HMAC: [RFC 2104](https://datatracker.ietf.org/doc/html/rfc2104)
- Erlang `public_key` module: [Docs](https://www.erlang.org/doc/apps/public_key/public_key.html)
- Erlang-JOSE : [github](https://github.com/potatosalad/erlang-jose/)
- WebCrypto/SubtleCrypto: [MDN](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto)
- jsonwebtoken library: [npm](https://www.npmjs.com/package/jsonwebtoken)
