@faable/auth-sdk 2.8.27 → 2.9.0

package/README.md

@@ -242,6 +242,26 @@ const members = await api.listTeamMembers({ query: "alice" }).first();
 const isMember = await api.isUserMemberOfTeam("user_xxx", "team_xxx");
 ```
 
+### Roles and permissions
+
+A role grants permissions of your APIs. Assign it to a user at the account level and their tokens for an API with `rbac` enabled carry those permissions (team roles grant none).
+
+```ts
+const role = await api.roleCreate({ name: "support" });
+await api.roleAddPermissions(role.id, {
+  permissions: [{ api: "api_xxx", value: "tickets:write" }],
+});
+
+await api.userAssignRoles("user_xxx", { roles: [role.id] });
+const roles = await api.userRoles("user_xxx");
+const permissions = await api.userPermissions("user_xxx"); // with the role that grants each
+
+await api.userRemoveRoles("user_xxx", { roles: [role.id] });
+await api.roleRemovePermissions(role.id, {
+  permissions: [{ api: "api_xxx", value: "tickets:write" }],
+});
+```
+
 ### Connections
 
 ```ts
@@ -325,6 +345,37 @@ export default async function handler(req, res) {
 
 `WebhookEvent`, `WebhookEventType`, `WebhookEventOf<"user.created">` and `WebhookPayload<"team.member.added">` are generated from the auth OpenAPI, like every other type.
 
+## Protecting your API
+
+Verify the access tokens your API receives and check their permissions:
+
+```ts
+import {
+  AccessTokenError,
+  bearerToken,
+  requirePermissions,
+  verifyAccessToken,
+} from "@faable/auth-sdk";
+
+export default async function handler(req, res) {
+  try {
+    const claims = await verifyAccessToken(bearerToken(req.headers.authorization), {
+      domain: process.env.FAABLEAUTH_DOMAIN!, // https://<tenant>.auth.faable.link
+      audience: "https://api.example.com", // your Api's identifier
+    });
+    requirePermissions(claims, "tickets:write");
+    // … claims.sub is the user (or the client, for machine tokens)
+  } catch (e) {
+    if (e instanceof AccessTokenError) return res.status(e.status).json({ error: e.reason });
+    throw e;
+  }
+}
+```
+
+- `verifyAccessToken` checks the signature against the tenant JWKS (fetched once and cached), `iss`, `aud` and `exp`. It throws `AccessTokenError` with `status` 401.
+- `requirePermissions` throws `AccessTokenError` `insufficient_scope` with `status` 403 and `missing`; `hasPermissions` returns a boolean. Both require **all** the permissions passed.
+- The `permissions` claim needs the Api's `token_dialect` to be `access_token_authz`. With `rbac` on, a user token carries the permissions the client **requested** that the user's roles grant, so request them as scopes.
+
 ## Types
 
 All response shapes are generated from the OpenAPI spec and re-exported from the package root:

package/dist/index.d.ts

@@ -5,5 +5,7 @@ export * from "./api/api-types.js";
 export * from "./api/types.js";
 export { WEBHOOK_HEADERS, DEFAULT_WEBHOOK_TOLERANCE_MS, WebhookVerificationError, verifyWebhookSignature, constructWebhookEvent, readRawBody, } from "./webhooks.js";
 export type { WebhookEventOf, WebhookPayload, WebhookHeaders, WebhookVerificationFailure, VerifyWebhookOptions, VerifiedWebhookEvent, } from "./webhooks.js";
+export { AccessTokenError, bearerToken, verifyAccessToken, permissionsOf, hasPermissions, requirePermissions, } from "./tokens.js";
+export type { AccessTokenClaims, AccessTokenFailure, VerifyAccessTokenOptions, } from "./tokens.js";
 export { authClientCredentials, authApikey, authBearer, authCookie, FaableApiError, } from "@faable/sdk-base";
 export type { ApiParams, ClientCredentialsConfig, ApikeyConfig, BearerConfig, RetryConfig, Fetcher, FetcherConfig, FetcherRequestParams, AuthStrategy, AuthStrategyBuilder, AuthStrategyContext, } from "@faable/sdk-base";

package/dist/index.js

@@ -5,6 +5,8 @@ export * from "./api/api-types.js";
 export * from "./api/types.js";
 // Receiving webhooks: verify the signature, get the event typed.
 export { WEBHOOK_HEADERS, DEFAULT_WEBHOOK_TOLERANCE_MS, WebhookVerificationError, verifyWebhookSignature, constructWebhookEvent, readRawBody, } from "./webhooks.js";
+// Protecting your API: verify a Faable Auth access token, check permissions.
+export { AccessTokenError, bearerToken, verifyAccessToken, permissionsOf, hasPermissions, requirePermissions, } from "./tokens.js";
 // Re-export the auth strategies (and their config/types) from
 // @faable/sdk-base so consumers depend on @faable/auth-sdk ONLY — sdk-base
 // stays a transitive dependency and no app needs to import it directly.

package/dist/tokens.d.ts

@@ -0,0 +1,82 @@
+import { type JWTPayload } from "jose";
+/**
+ * Verifying the access tokens Faable Auth issues for your API, and checking
+ * what they allow.
+ *
+ * An Api with `token_dialect: "access_token_authz"` puts a `permissions` claim
+ * in its tokens: a space-separated string. With `rbac` enabled on the Api,
+ * user tokens carry only the requested permissions that the user's roles
+ * grant; machine tokens (`client_credentials`) carry what the client asked
+ * for, or the whole catalog when it asked for nothing.
+ *
+ * ```ts
+ * const claims = await verifyAccessToken(bearerToken(req.headers.authorization), {
+ *   domain: "https://my-tenant.auth.faable.link",
+ *   audience: "https://api.example.com",
+ * });
+ * requirePermissions(claims, "invites:write"); // throws AccessTokenError (403)
+ * ```
+ */
+/** The claims of a Faable Auth access token. */
+export type AccessTokenClaims = JWTPayload & {
+    sub: string;
+    /** Space-separated granted scopes. */
+    scope?: string;
+    /** Space-separated permissions (`access_token_authz` dialect). */
+    permissions?: string;
+    /** Role names, when the Api has `include_roles_in_access_token`. */
+    roles?: string[];
+    /** Team slugs, when the Api has `include_teams_in_access_token`. */
+    teams?: string[];
+    client_id?: string;
+};
+export type AccessTokenFailure = "missing_token" | "invalid_token" | "insufficient_scope";
+/**
+ * Thrown by {@link verifyAccessToken} (`invalid_token`, `missing_token`: answer
+ * 401) and {@link requirePermissions} (`insufficient_scope`: answer 403).
+ * `status` is the HTTP status to answer with.
+ */
+export declare class AccessTokenError extends Error {
+    readonly reason: AccessTokenFailure;
+    readonly status: 401 | 403;
+    /** For `insufficient_scope`: the permissions the token lacks. */
+    readonly missing?: string[];
+    constructor(reason: AccessTokenFailure, message: string, opts?: {
+        missing?: string[];
+        cause?: unknown;
+    });
+}
+export type VerifyAccessTokenOptions = {
+    /** Your tenant host, e.g. `https://my-tenant.auth.faable.link`. */
+    domain: string;
+    /** The `identifier` of your Api: the token's `aud` must be it. */
+    audience: string | string[];
+    /**
+     * The expected `iss`, when the tenant has a custom domain whose host is not
+     * `domain`. Defaults to `domain`.
+     */
+    issuer?: string;
+    /** Seconds of clock skew to tolerate on `exp` / `nbf`. Default 60. */
+    clockTolerance?: number;
+};
+/**
+ * The token of an `Authorization: Bearer <token>` header, or `undefined`.
+ */
+export declare const bearerToken: (header: string | string[] | null | undefined) => string | undefined;
+/**
+ * Verifies an access token against the tenant's JWKS: signature (RS256),
+ * `iss`, `aud`, `exp`. Returns its claims, or throws {@link AccessTokenError}.
+ */
+export declare const verifyAccessToken: (token: string | null | undefined, options: VerifyAccessTokenOptions) => Promise<AccessTokenClaims>;
+/**
+ * The permissions of a token, as a list. Accepts the claim as Faable Auth
+ * issues it (a space-separated string) and as an array.
+ */
+export declare const permissionsOf: (claims: Pick<AccessTokenClaims, "permissions"> | null | undefined) => string[];
+/** True when the token carries EVERY permission in `required`. */
+export declare const hasPermissions: (claims: Pick<AccessTokenClaims, "permissions"> | null | undefined, required: string | string[]) => boolean;
+/**
+ * Throws {@link AccessTokenError} `insufficient_scope` (403) unless the token
+ * carries every permission in `required`. `missing` names the ones it lacks.
+ */
+export declare const requirePermissions: (claims: Pick<AccessTokenClaims, "permissions"> | null | undefined, required: string | string[]) => void;

package/dist/tokens.js

@@ -0,0 +1,94 @@
+import { createRemoteJWKSet, jwtVerify } from "jose";
+import { getDomain } from "./helpers.js";
+/**
+ * Thrown by {@link verifyAccessToken} (`invalid_token`, `missing_token`: answer
+ * 401) and {@link requirePermissions} (`insufficient_scope`: answer 403).
+ * `status` is the HTTP status to answer with.
+ */
+export class AccessTokenError extends Error {
+    reason;
+    status;
+    /** For `insufficient_scope`: the permissions the token lacks. */
+    missing;
+    constructor(reason, message, opts = {}) {
+        super(message, opts.cause ? { cause: opts.cause } : undefined);
+        this.name = "AccessTokenError";
+        this.reason = reason;
+        this.status = reason === "insufficient_scope" ? 403 : 401;
+        if (opts.missing)
+            this.missing = opts.missing;
+    }
+}
+// One JWKS per issuer, so keys are fetched once and refreshed by jose on an
+// unknown `kid` (a key rotation) instead of on every request.
+const jwksByIssuer = new Map();
+const jwksFor = (issuer) => {
+    let jwks = jwksByIssuer.get(issuer);
+    if (!jwks) {
+        jwks = createRemoteJWKSet(new URL(`${issuer}/.well-known/jwks.json`));
+        jwksByIssuer.set(issuer, jwks);
+    }
+    return jwks;
+};
+/**
+ * The token of an `Authorization: Bearer <token>` header, or `undefined`.
+ */
+export const bearerToken = (header) => {
+    const value = Array.isArray(header) ? header[0] : header;
+    const match = value?.match(/^Bearer\s+(\S+)\s*$/i);
+    return match?.[1];
+};
+/**
+ * Verifies an access token against the tenant's JWKS: signature (RS256),
+ * `iss`, `aud`, `exp`. Returns its claims, or throws {@link AccessTokenError}.
+ */
+export const verifyAccessToken = async (token, options) => {
+    if (!token) {
+        throw new AccessTokenError("missing_token", "No access token");
+    }
+    const issuer = getDomain(options.issuer ?? options.domain);
+    try {
+        const { payload } = await jwtVerify(token, jwksFor(issuer), {
+            issuer,
+            audience: options.audience,
+            algorithms: ["RS256"],
+            clockTolerance: options.clockTolerance ?? 60,
+        });
+        if (typeof payload.sub !== "string") {
+            throw new Error("access token has no sub");
+        }
+        return payload;
+    }
+    catch (err) {
+        throw new AccessTokenError("invalid_token", `Invalid access token: ${err?.message ?? err}`, { cause: err });
+    }
+};
+/**
+ * The permissions of a token, as a list. Accepts the claim as Faable Auth
+ * issues it (a space-separated string) and as an array.
+ */
+export const permissionsOf = (claims) => {
+    const raw = claims?.permissions;
+    if (Array.isArray(raw))
+        return raw.filter((p) => typeof p === "string");
+    if (typeof raw === "string")
+        return raw.split(" ").filter(Boolean);
+    return [];
+};
+const asList = (required) => Array.isArray(required) ? required : [required];
+/** True when the token carries EVERY permission in `required`. */
+export const hasPermissions = (claims, required) => {
+    const held = new Set(permissionsOf(claims));
+    return asList(required).every((p) => held.has(p));
+};
+/**
+ * Throws {@link AccessTokenError} `insufficient_scope` (403) unless the token
+ * carries every permission in `required`. `missing` names the ones it lacks.
+ */
+export const requirePermissions = (claims, required) => {
+    const held = new Set(permissionsOf(claims));
+    const missing = asList(required).filter((p) => !held.has(p));
+    if (missing.length > 0) {
+        throw new AccessTokenError("insufficient_scope", `Missing permission(s): ${missing.join(", ")}`, { missing });
+    }
+};

package/dist/version.js

@@ -9,13 +9,13 @@
 // login pages could not import the SDK at all. Same pattern as auth-js.
 //
 // The sentinels MUST stay byte-identical to the `from` values in `.releaserc`.
-export const version = "2.8.27";
+export const version = "2.9.0";
 // Short git SHA of the released commit. The version dates a build; this names
 // the exact tree, so a canonical log line or an audit entry leads straight to
 // `git show <sha>`. Deliberately NOT hex: an unreleased build (dev, a local
 // link) cannot be mistaken for a real commit — auth only records values that
 // look like a SHA, and this one never will.
-export const commit = "4cbcc80";
+export const commit = "ff21a5a";
 // What this SDK writes in `x-faable-client`. Exported for a consumer that
 // builds a strategy on its own (outside `FaableAuthApi`) and still wants the
 // token request attributed — a bare `authClientCredentials` stamps only what

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faable/auth-sdk",
-  "version": "2.8.27",
+  "version": "2.9.0",
   "author": "Marc Pomar <marc@faable.com>",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,7 +10,8 @@
   },
   "type": "module",
   "dependencies": {
-    "@faable/sdk-base": "^1.7.0"
+    "@faable/sdk-base": "^1.7.0",
+    "jose": "^6.2.13"
   },
   "devDependencies": {
     "@ava/typescript": "^5.0.0",

package/scripts/gen-client.mjs

@@ -148,6 +148,16 @@ const emitMethod = ({ path, httpMethod, op }) => {
     // client/rotateSecret) send an empty object.
     const data = hasBody ? "data" : "{}";
     body = `return this.fetcher.post<OpResult<"${id}">>(${url}, ${data});`;
+  } else if (httpMethod === "delete" && hasBody) {
+    // fetcher.delete takes no body, so a DELETE with one (DELETE
+    // /role/{id}/permissions, /user/{id}/roles) goes through fetcher.request.
+    // Before this branch the `data` argument was declared and then dropped.
+    if (hasQuery) {
+      throw new Error(
+        `gen-client: DELETE with both a body and query params not supported yet (${id}).`,
+      );
+    }
+    body = `return this.fetcher.request<OpResult<"${id}">>({ method: "DELETE", url: ${url}, data });`;
   } else if (hasQuery) {
     // GET/DELETE with query params route through fetcher.request: its `params`
     // is untyped, sidestepping FetcherConfig's string-only constraint, and the