This plugin verifies Faable Auth JWTs on incoming Fastify requests. It fetches the appropriate JWKS for your tenant, validates the token's iss, signature and expiration, and exposes the decoded user via request.user.

Install

npm install @faable/auth-helpers-fastify fastify fastify-plugin

Peer dependencies: fastify ^5.0.0, fastify-plugin ^5.0.1.

Usage

Register the plugin once on your Fastify instance, then guard individual routes with the faableAuth() prehandler.

import Fastify from "fastify";
import faableAuthPlugin from "@faable/auth-helpers-fastify";

const app = Fastify();

await app.register(faableAuthPlugin, {
  domain: "https://<team>.auth.faable.com",
});

app.post("/private", { preHandler: app.faableAuth() }, (req, res) => {
  // req.user        → decoded JWT payload ({ sub, scopes? })
  // req.user_id     → req.user.sub
  // req.faableAuthClientType → "user" | "client"
  return res.send({ message: "Access granted", user_id: req.user_id });
});

// Optional auth — populates req.user when present, never rejects
app.get("/public", { preHandler: app.faableAuth({ required: false }) }, (req) => ({
  authenticated: Boolean(req.user_id),
}));

await app.listen({ port: 3000 });

Configuration

Plugin options

| Option | Type | Default | Description | | -------- | -------- | ---------------------- | --------------------------------------------------------------------------- | | domain | string | FAABLEAUTH_DOMAIN env | Faable Auth tenant URL used as the allowed JWT issuer (iss). Required. |

Prehandler options (faableAuth(options))

| Option | Type | Default | Description | | ---------- | ---------- | ------- | --------------------------------------------------------------------------- | | required | boolean | true | When true, missing/invalid tokens reject with 401 Unauthorized. When false, the request continues with req.user undefined. | | scopes | string[] | [] | Reserved for scope-based access control (currently not enforced). |

Environment variables

| Variable | Description | | -------------------------- | ---------------------------------------------------------- | | FAABLEAUTH_DOMAIN | Tenant URL — fallback when domain is not passed in code. | | FAABLEAUTH_CLIENT_ID | App Client ID (used by other helpers, e.g. axios). | | FAABLEAUTH_CLIENT_SECRET | App Client Secret (used by other helpers, e.g. axios). |

What gets attached to the request

| Property | Type | Description | | -------------------------- | --------------------- | ---------------------------------------------------------------------------------------- | | request.user | { sub, scopes? } | Decoded JWT payload. | | request.user_id | string | Shortcut to request.user.sub. | | request.faableAuthClientType | "user" \| "client" | "user" when sub starts with user_, otherwise "client" (machine-to-machine token). |

License

MIT