@talismn/gandalf 0.0.0

package/README.md

@@ -0,0 +1,149 @@
+# @talismn/gandalf
+
+SDK for verifying [Gandalf](../README.md) auth tokens. Fully platform-agnostic — works with Cloudflare Workers, Node.js, Deno, Bun, Express, Hono, and any other JavaScript runtime.
+
+- Offline JWT verification via JWKS
+- In-memory JWKS cache (5-min TTL per isolate)
+- ESM + CJS
+- No dependency on the Fetch API `Request` type
+
+## Installation
+
+```bash
+pnpm add @talismn/gandalf
+```
+
+## Usage
+
+### Verify an access token
+
+```ts
+import { verifyAccessToken, extractBearerToken } from "@talismn/gandalf";
+
+export default {
+  async fetch(request: Request, env: Env) {
+    try {
+      const token = extractBearerToken(request.headers.get("Authorization"));
+      const auth = await verifyAccessToken(token, {
+        // Optional overrides:
+        // jwksUrl: env.GANDALF_JWKS_URL,
+        // issuer: env.GANDALF_ISSUER,
+      });
+
+      // auth.installId — the verified installation ID
+      // auth.claims    — full JWT payload
+
+      return new Response(JSON.stringify({ data: "..." }));
+    } catch (err) {
+      if (err instanceof GandalfAuthError) {
+        return Response.json(
+          { error: "unauthorized", message: err.message },
+          { status: err.status }
+        );
+      }
+      throw err;
+    }
+  },
+};
+```
+
+### Express / Node.js example
+
+```ts
+import { verifyAccessToken, extractBearerToken, GandalfAuthError } from "@talismn/gandalf";
+
+app.use("/v1/*", async (req, res, next) => {
+  try {
+    const token = extractBearerToken(req.headers.authorization);
+    const auth = await verifyAccessToken(token);
+    req.auth = auth;
+    next();
+  } catch (err) {
+    if (err instanceof GandalfAuthError) {
+      return res.status(err.status).json({ error: "unauthorized", message: err.message });
+    }
+    next(err);
+  }
+});
+```
+
+### Hono middleware example
+
+```ts
+import { Hono } from "hono";
+import {
+  verifyAccessToken,
+  extractBearerToken,
+  GandalfAuthError,
+  type AuthContext,
+} from "@talismn/gandalf";
+
+type Env = { Bindings: { GANDALF_JWKS_URL: string } };
+
+const app = new Hono<Env>();
+
+// Auth middleware
+app.use("/v1/*", async (c, next) => {
+  try {
+    const token = extractBearerToken(c.req.header("Authorization"));
+    const auth = await verifyAccessToken(token, {
+      jwksUrl: c.env.GANDALF_JWKS_URL,
+    });
+    c.set("auth", auth);
+    await next();
+  } catch (err) {
+    if (err instanceof GandalfAuthError) {
+      return c.json({ error: "unauthorized", message: err.message }, err.status);
+    }
+    throw err;
+  }
+});
+
+app.get("/v1/prices", (c) => {
+  const auth = c.get("auth") as AuthContext;
+  // auth.installId is available for logging, rate limiting, etc.
+  return c.json({ prices: [] });
+});
+```
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `jwksUrl` | `https://gandalf.talisman.xyz/.well-known/jwks.json` | JWKS endpoint URL |
+| `issuer` | `gandalf.talisman.xyz` | Expected JWT issuer claim |
+| `clockTolerance` | `30` | Seconds of clock skew tolerance for exp/nbf checks |
+
+## JWKS Caching
+
+The SDK caches JWKS in-memory per Worker isolate with a 5-minute TTL. When an unknown `kid` is encountered, `jose`'s `createRemoteJWKSet` automatically refetches.
+
+## API Reference
+
+### `verifyAccessToken(token, opts): Promise<AuthContext>`
+
+Verifies the JWT signature and claims, returns an `AuthContext`.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `token` | `string` | The raw JWT string |
+| `opts` | `VerifyOpts` | Optional verification overrides |
+
+### `extractBearerToken(authHeader): string`
+
+Extracts the raw JWT from an `Authorization` header value (e.g. `"Bearer eyJ..."`). Throws `GandalfAuthError` if the header is missing or malformed.
+
+### `AuthContext`
+
+```ts
+interface AuthContext {
+  installId: string;       // from sub claim "install:<id>"
+  claims: JWTPayload;      // full JWT payload
+}
+```
+
+### Error Classes
+
+| Class | Thrown by | Properties |
+|-------|----------|------------|
+| `GandalfAuthError` | `verifyAccessToken` | `.status: number` |

package/dist/index.cjs

@@ -0,0 +1,97 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  GandalfAuthError: () => GandalfAuthError,
+  extractBearerToken: () => extractBearerToken,
+  getJWKS: () => getJWKS,
+  verifyAccessToken: () => verifyAccessToken
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/jwks.ts
+var import_jose = require("jose");
+var DEFAULT_JWKS_URL = "https://gandalf.talisman.xyz/.well-known/jwks.json";
+var jwksCache = /* @__PURE__ */ new Map();
+var CACHE_TTL_MS = 5 * 60 * 1e3;
+function getJWKS(jwksUrl = DEFAULT_JWKS_URL) {
+  const now = Date.now();
+  const cached = jwksCache.get(jwksUrl);
+  if (cached && now - cached.createdAt < CACHE_TTL_MS) {
+    return cached.jwks;
+  }
+  const jwks = (0, import_jose.createRemoteJWKSet)(new URL(jwksUrl));
+  jwksCache.set(jwksUrl, { jwks, createdAt: now });
+  return jwks;
+}
+
+// src/verify.ts
+var import_jose2 = require("jose");
+var DEFAULT_ISSUER = "gandalf.talisman.xyz";
+function extractBearerToken(authHeader) {
+  if (!authHeader) {
+    throw new GandalfAuthError("Missing Authorization header", 401);
+  }
+  const parts = authHeader.split(" ");
+  if (parts.length !== 2 || parts[0] !== "Bearer" || !parts[1]) {
+    throw new GandalfAuthError(
+      "Invalid Authorization header format. Expected: Bearer <token>",
+      401
+    );
+  }
+  return parts[1];
+}
+async function verifyAccessToken(token, opts = {}) {
+  const jwks = getJWKS(opts.jwksUrl);
+  const issuer = opts.issuer ?? DEFAULT_ISSUER;
+  try {
+    const { payload } = await (0, import_jose2.jwtVerify)(token, jwks, {
+      issuer,
+      clockTolerance: opts.clockTolerance ?? 30
+    });
+    const sub = payload.sub;
+    if (!sub?.startsWith("install:")) {
+      throw new GandalfAuthError("Invalid sub claim format", 401);
+    }
+    const installId = sub.slice("install:".length);
+    return { installId, claims: payload };
+  } catch (err) {
+    if (err instanceof GandalfAuthError) throw err;
+    const message = err instanceof Error ? err.message : "Token verification failed";
+    throw new GandalfAuthError(message, 401);
+  }
+}
+var GandalfAuthError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "GandalfAuthError";
+    this.status = status;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GandalfAuthError,
+  extractBearerToken,
+  getJWKS,
+  verifyAccessToken
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/jwks.ts","../src/verify.ts"],"sourcesContent":["// Core\n\n// JWKS\nexport { getJWKS } from \"./jwks\";\n// Types\nexport type { AuthContext, VerifyOpts } from \"./types\";\nexport {\n\textractBearerToken,\n\tGandalfAuthError,\n\tverifyAccessToken,\n} from \"./verify\";\n","import { createRemoteJWKSet } from \"jose\";\n\nconst DEFAULT_JWKS_URL = \"https://gandalf.talisman.xyz/.well-known/jwks.json\";\n\n/** In-memory JWKS cache keyed by URL */\nconst jwksCache = new Map<\n\tstring,\n\t{ jwks: ReturnType<typeof createRemoteJWKSet>; createdAt: number }\n>();\n\nconst CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes\n\n/**\n * Get a cached JWKS function for the given URL.\n *\n * The returned function is compatible with `jose.jwtVerify()`.\n * On unknown `kid`, jose's `createRemoteJWKSet` automatically refetches.\n */\nexport function getJWKS(\n\tjwksUrl: string = DEFAULT_JWKS_URL,\n): ReturnType<typeof createRemoteJWKSet> {\n\tconst now = Date.now();\n\tconst cached = jwksCache.get(jwksUrl);\n\n\tif (cached && now - cached.createdAt < CACHE_TTL_MS) {\n\t\treturn cached.jwks;\n\t}\n\n\tconst jwks = createRemoteJWKSet(new URL(jwksUrl));\n\tjwksCache.set(jwksUrl, { jwks, createdAt: now });\n\n\treturn jwks;\n}\n","import { jwtVerify } from \"jose\";\nimport { getJWKS } from \"./jwks\";\nimport type { AuthContext, VerifyOpts } from \"./types\";\n\nconst DEFAULT_ISSUER = \"gandalf.talisman.xyz\";\n\n/**\n * Extract a Bearer token from an `Authorization` header value.\n *\n * @param authHeader - The full `Authorization` header string (e.g. `\"Bearer eyJ...\"`).\n * @returns The raw JWT string.\n * @throws GandalfAuthError if the header is missing or malformed.\n */\nexport function extractBearerToken(\n\tauthHeader: string | null | undefined,\n): string {\n\tif (!authHeader) {\n\t\tthrow new GandalfAuthError(\"Missing Authorization header\", 401);\n\t}\n\n\tconst parts = authHeader.split(\" \");\n\tif (parts.length !== 2 || parts[0] !== \"Bearer\" || !parts[1]) {\n\t\tthrow new GandalfAuthError(\n\t\t\t\"Invalid Authorization header format. Expected: Bearer <token>\",\n\t\t\t401,\n\t\t);\n\t}\n\n\treturn parts[1];\n}\n\n/**\n * Verify a Gandalf access token.\n *\n * Verifies the JWT signature and claims, and returns an `AuthContext` on success.\n *\n * @param token - The raw JWT string (not the full Authorization header).\n * @param opts - Optional verification overrides.\n * @throws GandalfAuthError on any verification failure.\n */\nexport async function verifyAccessToken(\n\ttoken: string,\n\topts: VerifyOpts = {},\n): Promise<AuthContext> {\n\t// Get JWKS\n\tconst jwks = getJWKS(opts.jwksUrl);\n\tconst issuer = opts.issuer ?? DEFAULT_ISSUER;\n\n\t// Verify JWT\n\ttry {\n\t\tconst { payload } = await jwtVerify(token, jwks, {\n\t\t\tissuer,\n\t\t\tclockTolerance: opts.clockTolerance ?? 30,\n\t\t});\n\n\t\t// Extract installId from `sub` claim (format: \"install:<id>\")\n\t\tconst sub = payload.sub;\n\t\tif (!sub?.startsWith(\"install:\")) {\n\t\t\tthrow new GandalfAuthError(\"Invalid sub claim format\", 401);\n\t\t}\n\t\tconst installId = sub.slice(\"install:\".length);\n\n\t\treturn { installId, claims: payload };\n\t} catch (err) {\n\t\tif (err instanceof GandalfAuthError) throw err;\n\n\t\tconst message =\n\t\t\terr instanceof Error ? err.message : \"Token verification failed\";\n\t\tthrow new GandalfAuthError(message, 401);\n\t}\n}\n\n/** Error thrown during Gandalf auth verification */\nexport class GandalfAuthError extends Error {\n\tpublic readonly status: number;\n\n\tconstructor(message: string, status: number) {\n\t\tsuper(message);\n\t\tthis.name = \"GandalfAuthError\";\n\t\tthis.status = status;\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,kBAAmC;AAEnC,IAAM,mBAAmB;AAGzB,IAAM,YAAY,oBAAI,IAGpB;AAEF,IAAM,eAAe,IAAI,KAAK;AAQvB,SAAS,QACf,UAAkB,kBACsB;AACxC,QAAM,MAAM,KAAK,IAAI;AACrB,QAAM,SAAS,UAAU,IAAI,OAAO;AAEpC,MAAI,UAAU,MAAM,OAAO,YAAY,cAAc;AACpD,WAAO,OAAO;AAAA,EACf;AAEA,QAAM,WAAO,gCAAmB,IAAI,IAAI,OAAO,CAAC;AAChD,YAAU,IAAI,SAAS,EAAE,MAAM,WAAW,IAAI,CAAC;AAE/C,SAAO;AACR;;;AChCA,IAAAA,eAA0B;AAI1B,IAAM,iBAAiB;AAShB,SAAS,mBACf,YACS;AACT,MAAI,CAAC,YAAY;AAChB,UAAM,IAAI,iBAAiB,gCAAgC,GAAG;AAAA,EAC/D;AAEA,QAAM,QAAQ,WAAW,MAAM,GAAG;AAClC,MAAI,MAAM,WAAW,KAAK,MAAM,CAAC,MAAM,YAAY,CAAC,MAAM,CAAC,GAAG;AAC7D,UAAM,IAAI;AAAA,MACT;AAAA,MACA;AAAA,IACD;AAAA,EACD;AAEA,SAAO,MAAM,CAAC;AACf;AAWA,eAAsB,kBACrB,OACA,OAAmB,CAAC,GACG;AAEvB,QAAM,OAAO,QAAQ,KAAK,OAAO;AACjC,QAAM,SAAS,KAAK,UAAU;AAG9B,MAAI;AACH,UAAM,EAAE,QAAQ,IAAI,UAAM,wBAAU,OAAO,MAAM;AAAA,MAChD;AAAA,MACA,gBAAgB,KAAK,kBAAkB;AAAA,IACxC,CAAC;AAGD,UAAM,MAAM,QAAQ;AACpB,QAAI,CAAC,KAAK,WAAW,UAAU,GAAG;AACjC,YAAM,IAAI,iBAAiB,4BAA4B,GAAG;AAAA,IAC3D;AACA,UAAM,YAAY,IAAI,MAAM,WAAW,MAAM;AAE7C,WAAO,EAAE,WAAW,QAAQ,QAAQ;AAAA,EACrC,SAAS,KAAK;AACb,QAAI,eAAe,iBAAkB,OAAM;AAE3C,UAAM,UACL,eAAe,QAAQ,IAAI,UAAU;AACtC,UAAM,IAAI,iBAAiB,SAAS,GAAG;AAAA,EACxC;AACD;AAGO,IAAM,mBAAN,cAA+B,MAAM;AAAA,EAC3B;AAAA,EAEhB,YAAY,SAAiB,QAAgB;AAC5C,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,SAAS;AAAA,EACf;AACD;","names":["import_jose"]}

package/dist/index.d.cts

@@ -0,0 +1,52 @@
+import { createRemoteJWKSet, JWTPayload } from 'jose';
+
+/**
+ * Get a cached JWKS function for the given URL.
+ *
+ * The returned function is compatible with `jose.jwtVerify()`.
+ * On unknown `kid`, jose's `createRemoteJWKSet` automatically refetches.
+ */
+declare function getJWKS(jwksUrl?: string): ReturnType<typeof createRemoteJWKSet>;
+
+/** Result of a successful token verification */
+interface AuthContext {
+    /** The installation ID extracted from the `sub` claim */
+    installId: string;
+    /** The full decoded JWT payload */
+    claims: JWTPayload;
+}
+/** Options for verifying an access token */
+interface VerifyOpts {
+    /** URL to fetch the JWKS from (default: https://gandalf.talisman.xyz/.well-known/jwks.json) */
+    jwksUrl?: string;
+    /** Expected `iss` claim (default: gandalf.talisman.xyz) */
+    issuer?: string;
+    /** Clock tolerance in seconds for `exp`/`nbf` checks (default: 30) */
+    clockTolerance?: number;
+}
+
+/**
+ * Extract a Bearer token from an `Authorization` header value.
+ *
+ * @param authHeader - The full `Authorization` header string (e.g. `"Bearer eyJ..."`).
+ * @returns The raw JWT string.
+ * @throws GandalfAuthError if the header is missing or malformed.
+ */
+declare function extractBearerToken(authHeader: string | null | undefined): string;
+/**
+ * Verify a Gandalf access token.
+ *
+ * Verifies the JWT signature and claims, and returns an `AuthContext` on success.
+ *
+ * @param token - The raw JWT string (not the full Authorization header).
+ * @param opts - Optional verification overrides.
+ * @throws GandalfAuthError on any verification failure.
+ */
+declare function verifyAccessToken(token: string, opts?: VerifyOpts): Promise<AuthContext>;
+/** Error thrown during Gandalf auth verification */
+declare class GandalfAuthError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+
+export { type AuthContext, GandalfAuthError, type VerifyOpts, extractBearerToken, getJWKS, verifyAccessToken };

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import { createRemoteJWKSet, JWTPayload } from 'jose';
+
+/**
+ * Get a cached JWKS function for the given URL.
+ *
+ * The returned function is compatible with `jose.jwtVerify()`.
+ * On unknown `kid`, jose's `createRemoteJWKSet` automatically refetches.
+ */
+declare function getJWKS(jwksUrl?: string): ReturnType<typeof createRemoteJWKSet>;
+
+/** Result of a successful token verification */
+interface AuthContext {
+    /** The installation ID extracted from the `sub` claim */
+    installId: string;
+    /** The full decoded JWT payload */
+    claims: JWTPayload;
+}
+/** Options for verifying an access token */
+interface VerifyOpts {
+    /** URL to fetch the JWKS from (default: https://gandalf.talisman.xyz/.well-known/jwks.json) */
+    jwksUrl?: string;
+    /** Expected `iss` claim (default: gandalf.talisman.xyz) */
+    issuer?: string;
+    /** Clock tolerance in seconds for `exp`/`nbf` checks (default: 30) */
+    clockTolerance?: number;
+}
+
+/**
+ * Extract a Bearer token from an `Authorization` header value.
+ *
+ * @param authHeader - The full `Authorization` header string (e.g. `"Bearer eyJ..."`).
+ * @returns The raw JWT string.
+ * @throws GandalfAuthError if the header is missing or malformed.
+ */
+declare function extractBearerToken(authHeader: string | null | undefined): string;
+/**
+ * Verify a Gandalf access token.
+ *
+ * Verifies the JWT signature and claims, and returns an `AuthContext` on success.
+ *
+ * @param token - The raw JWT string (not the full Authorization header).
+ * @param opts - Optional verification overrides.
+ * @throws GandalfAuthError on any verification failure.
+ */
+declare function verifyAccessToken(token: string, opts?: VerifyOpts): Promise<AuthContext>;
+/** Error thrown during Gandalf auth verification */
+declare class GandalfAuthError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+
+export { type AuthContext, GandalfAuthError, type VerifyOpts, extractBearerToken, getJWKS, verifyAccessToken };

package/dist/index.js

@@ -0,0 +1,67 @@
+// src/jwks.ts
+import { createRemoteJWKSet } from "jose";
+var DEFAULT_JWKS_URL = "https://gandalf.talisman.xyz/.well-known/jwks.json";
+var jwksCache = /* @__PURE__ */ new Map();
+var CACHE_TTL_MS = 5 * 60 * 1e3;
+function getJWKS(jwksUrl = DEFAULT_JWKS_URL) {
+  const now = Date.now();
+  const cached = jwksCache.get(jwksUrl);
+  if (cached && now - cached.createdAt < CACHE_TTL_MS) {
+    return cached.jwks;
+  }
+  const jwks = createRemoteJWKSet(new URL(jwksUrl));
+  jwksCache.set(jwksUrl, { jwks, createdAt: now });
+  return jwks;
+}
+
+// src/verify.ts
+import { jwtVerify } from "jose";
+var DEFAULT_ISSUER = "gandalf.talisman.xyz";
+function extractBearerToken(authHeader) {
+  if (!authHeader) {
+    throw new GandalfAuthError("Missing Authorization header", 401);
+  }
+  const parts = authHeader.split(" ");
+  if (parts.length !== 2 || parts[0] !== "Bearer" || !parts[1]) {
+    throw new GandalfAuthError(
+      "Invalid Authorization header format. Expected: Bearer <token>",
+      401
+    );
+  }
+  return parts[1];
+}
+async function verifyAccessToken(token, opts = {}) {
+  const jwks = getJWKS(opts.jwksUrl);
+  const issuer = opts.issuer ?? DEFAULT_ISSUER;
+  try {
+    const { payload } = await jwtVerify(token, jwks, {
+      issuer,
+      clockTolerance: opts.clockTolerance ?? 30
+    });
+    const sub = payload.sub;
+    if (!sub?.startsWith("install:")) {
+      throw new GandalfAuthError("Invalid sub claim format", 401);
+    }
+    const installId = sub.slice("install:".length);
+    return { installId, claims: payload };
+  } catch (err) {
+    if (err instanceof GandalfAuthError) throw err;
+    const message = err instanceof Error ? err.message : "Token verification failed";
+    throw new GandalfAuthError(message, 401);
+  }
+}
+var GandalfAuthError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "GandalfAuthError";
+    this.status = status;
+  }
+};
+export {
+  GandalfAuthError,
+  extractBearerToken,
+  getJWKS,
+  verifyAccessToken
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/jwks.ts","../src/verify.ts"],"sourcesContent":["import { createRemoteJWKSet } from \"jose\";\n\nconst DEFAULT_JWKS_URL = \"https://gandalf.talisman.xyz/.well-known/jwks.json\";\n\n/** In-memory JWKS cache keyed by URL */\nconst jwksCache = new Map<\n\tstring,\n\t{ jwks: ReturnType<typeof createRemoteJWKSet>; createdAt: number }\n>();\n\nconst CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes\n\n/**\n * Get a cached JWKS function for the given URL.\n *\n * The returned function is compatible with `jose.jwtVerify()`.\n * On unknown `kid`, jose's `createRemoteJWKSet` automatically refetches.\n */\nexport function getJWKS(\n\tjwksUrl: string = DEFAULT_JWKS_URL,\n): ReturnType<typeof createRemoteJWKSet> {\n\tconst now = Date.now();\n\tconst cached = jwksCache.get(jwksUrl);\n\n\tif (cached && now - cached.createdAt < CACHE_TTL_MS) {\n\t\treturn cached.jwks;\n\t}\n\n\tconst jwks = createRemoteJWKSet(new URL(jwksUrl));\n\tjwksCache.set(jwksUrl, { jwks, createdAt: now });\n\n\treturn jwks;\n}\n","import { jwtVerify } from \"jose\";\nimport { getJWKS } from \"./jwks\";\nimport type { AuthContext, VerifyOpts } from \"./types\";\n\nconst DEFAULT_ISSUER = \"gandalf.talisman.xyz\";\n\n/**\n * Extract a Bearer token from an `Authorization` header value.\n *\n * @param authHeader - The full `Authorization` header string (e.g. `\"Bearer eyJ...\"`).\n * @returns The raw JWT string.\n * @throws GandalfAuthError if the header is missing or malformed.\n */\nexport function extractBearerToken(\n\tauthHeader: string | null | undefined,\n): string {\n\tif (!authHeader) {\n\t\tthrow new GandalfAuthError(\"Missing Authorization header\", 401);\n\t}\n\n\tconst parts = authHeader.split(\" \");\n\tif (parts.length !== 2 || parts[0] !== \"Bearer\" || !parts[1]) {\n\t\tthrow new GandalfAuthError(\n\t\t\t\"Invalid Authorization header format. Expected: Bearer <token>\",\n\t\t\t401,\n\t\t);\n\t}\n\n\treturn parts[1];\n}\n\n/**\n * Verify a Gandalf access token.\n *\n * Verifies the JWT signature and claims, and returns an `AuthContext` on success.\n *\n * @param token - The raw JWT string (not the full Authorization header).\n * @param opts - Optional verification overrides.\n * @throws GandalfAuthError on any verification failure.\n */\nexport async function verifyAccessToken(\n\ttoken: string,\n\topts: VerifyOpts = {},\n): Promise<AuthContext> {\n\t// Get JWKS\n\tconst jwks = getJWKS(opts.jwksUrl);\n\tconst issuer = opts.issuer ?? DEFAULT_ISSUER;\n\n\t// Verify JWT\n\ttry {\n\t\tconst { payload } = await jwtVerify(token, jwks, {\n\t\t\tissuer,\n\t\t\tclockTolerance: opts.clockTolerance ?? 30,\n\t\t});\n\n\t\t// Extract installId from `sub` claim (format: \"install:<id>\")\n\t\tconst sub = payload.sub;\n\t\tif (!sub?.startsWith(\"install:\")) {\n\t\t\tthrow new GandalfAuthError(\"Invalid sub claim format\", 401);\n\t\t}\n\t\tconst installId = sub.slice(\"install:\".length);\n\n\t\treturn { installId, claims: payload };\n\t} catch (err) {\n\t\tif (err instanceof GandalfAuthError) throw err;\n\n\t\tconst message =\n\t\t\terr instanceof Error ? err.message : \"Token verification failed\";\n\t\tthrow new GandalfAuthError(message, 401);\n\t}\n}\n\n/** Error thrown during Gandalf auth verification */\nexport class GandalfAuthError extends Error {\n\tpublic readonly status: number;\n\n\tconstructor(message: string, status: number) {\n\t\tsuper(message);\n\t\tthis.name = \"GandalfAuthError\";\n\t\tthis.status = status;\n\t}\n}\n"],"mappings":";AAAA,SAAS,0BAA0B;AAEnC,IAAM,mBAAmB;AAGzB,IAAM,YAAY,oBAAI,IAGpB;AAEF,IAAM,eAAe,IAAI,KAAK;AAQvB,SAAS,QACf,UAAkB,kBACsB;AACxC,QAAM,MAAM,KAAK,IAAI;AACrB,QAAM,SAAS,UAAU,IAAI,OAAO;AAEpC,MAAI,UAAU,MAAM,OAAO,YAAY,cAAc;AACpD,WAAO,OAAO;AAAA,EACf;AAEA,QAAM,OAAO,mBAAmB,IAAI,IAAI,OAAO,CAAC;AAChD,YAAU,IAAI,SAAS,EAAE,MAAM,WAAW,IAAI,CAAC;AAE/C,SAAO;AACR;;;AChCA,SAAS,iBAAiB;AAI1B,IAAM,iBAAiB;AAShB,SAAS,mBACf,YACS;AACT,MAAI,CAAC,YAAY;AAChB,UAAM,IAAI,iBAAiB,gCAAgC,GAAG;AAAA,EAC/D;AAEA,QAAM,QAAQ,WAAW,MAAM,GAAG;AAClC,MAAI,MAAM,WAAW,KAAK,MAAM,CAAC,MAAM,YAAY,CAAC,MAAM,CAAC,GAAG;AAC7D,UAAM,IAAI;AAAA,MACT;AAAA,MACA;AAAA,IACD;AAAA,EACD;AAEA,SAAO,MAAM,CAAC;AACf;AAWA,eAAsB,kBACrB,OACA,OAAmB,CAAC,GACG;AAEvB,QAAM,OAAO,QAAQ,KAAK,OAAO;AACjC,QAAM,SAAS,KAAK,UAAU;AAG9B,MAAI;AACH,UAAM,EAAE,QAAQ,IAAI,MAAM,UAAU,OAAO,MAAM;AAAA,MAChD;AAAA,MACA,gBAAgB,KAAK,kBAAkB;AAAA,IACxC,CAAC;AAGD,UAAM,MAAM,QAAQ;AACpB,QAAI,CAAC,KAAK,WAAW,UAAU,GAAG;AACjC,YAAM,IAAI,iBAAiB,4BAA4B,GAAG;AAAA,IAC3D;AACA,UAAM,YAAY,IAAI,MAAM,WAAW,MAAM;AAE7C,WAAO,EAAE,WAAW,QAAQ,QAAQ;AAAA,EACrC,SAAS,KAAK;AACb,QAAI,eAAe,iBAAkB,OAAM;AAE3C,UAAM,UACL,eAAe,QAAQ,IAAI,UAAU;AACtC,UAAM,IAAI,iBAAiB,SAAS,GAAG;AAAA,EACxC;AACD;AAGO,IAAM,mBAAN,cAA+B,MAAM;AAAA,EAC3B;AAAA,EAEhB,YAAY,SAAiB,QAAgB;AAC5C,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,SAAS;AAAA,EACf;AACD;","names":[]}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@talismn/gandalf",
+  "version": "0.0.0",
+  "description": "SDK for verifying Gandalf auth tokens in Talisman APIs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TalismanSociety/gandalf.git",
+    "directory": "sdk"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "gandalf",
+    "talisman",
+    "auth",
+    "jwt"
+  ],
+  "license": "UNLICENSED",
+  "dependencies": {
+    "jose": "^6.1.3"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}