@insureco/bio 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -107,13 +107,22 @@ interface BioClientTokenPayload {
     orgId?: string;
     orgSlug?: string;
 }
-/** Options for local JWT verification */
+/** Options for local JWT verification (HS256) */
 interface VerifyOptions {
     /** Expected issuer (default: config issuer) */
     issuer?: string;
     /** Expected audience (client_id) */
     audience?: string;
 }
+/** Options for JWKS-based JWT verification (RS256) */
+interface JWKSVerifyOptions {
+    /** JWKS endpoint URL (default: https://bio.tawa.insureco.io/.well-known/jwks.json) */
+    jwksUri?: string;
+    /** Expected issuer — defaults to accepting both bio.insureco.io and bio.tawa.insureco.io */
+    issuer?: string;
+    /** Expected audience (client_id) */
+    audience?: string;
+}
 /** User profile from /api/oauth/userinfo or admin API */
 interface BioUser {
     sub: string;
@@ -367,8 +376,10 @@ declare function generatePKCE(): {
 };
 
 /**
- * Verify a Bio-ID JWT access token using HS256.
+ * Verify a Bio-ID JWT access token using HS256 (legacy / internal use).
  * Checks algorithm, signature (constant-time), expiration, issuer, and audience.
+ *
+ * @deprecated Prefer verifyTokenJWKS() for RS256 tokens issued by Bio-ID ≥ 0.2.
  */
 declare function verifyToken(token: string, secret: string, options?: VerifyOptions): BioTokenPayload;
 /**
@@ -381,5 +392,20 @@ declare function decodeToken(token: string): BioTokenPayload | null;
  * Returns true if expired or unparseable.
  */
 declare function isTokenExpired(token: string, bufferSeconds?: number): boolean;
+/**
+ * Verify a Bio-ID JWT access token using RS256 and the public JWKS endpoint.
+ *
+ * No shared secret required — fetches Bio-ID's public key and verifies locally.
+ * The JWKS is cached in-process for 24 hours and auto-refreshed on key rotation.
+ *
+ * @example
+ * ```ts
+ * import { verifyTokenJWKS } from '@insureco/bio'
+ *
+ * const payload = await verifyTokenJWKS(req.headers.authorization.slice(7))
+ * console.log(payload.bioId, payload.orgSlug)
+ * ```
+ */
+declare function verifyTokenJWKS(token: string, options?: JWKSVerifyOptions): Promise<BioTokenPayload>;
 
-export { type AdminResponse, type AuthorizeOptions, type AuthorizeResult, type BioAddress, BioAdmin, type BioAdminConfig, BioAuth, type BioAuthConfig, type BioClientTokenPayload, type BioDepartment, BioError, type BioMessaging, type BioOAuthClient, type BioRole, type BioTokenPayload, type BioUser, type CreateClientData, type CreateDepartmentData, type CreateRoleData, type IntrospectResult, type TokenResponse, type UpdateUserData, type UserFilters, type VerifyOptions, decodeToken, generatePKCE, isTokenExpired, verifyToken };
+export { type AdminResponse, type AuthorizeOptions, type AuthorizeResult, type BioAddress, BioAdmin, type BioAdminConfig, BioAuth, type BioAuthConfig, type BioClientTokenPayload, type BioDepartment, BioError, type BioMessaging, type BioOAuthClient, type BioRole, type BioTokenPayload, type BioUser, type CreateClientData, type CreateDepartmentData, type CreateRoleData, type IntrospectResult, type JWKSVerifyOptions, type TokenResponse, type UpdateUserData, type UserFilters, type VerifyOptions, decodeToken, generatePKCE, isTokenExpired, verifyToken, verifyTokenJWKS };

package/dist/index.d.ts

@@ -107,13 +107,22 @@ interface BioClientTokenPayload {
     orgId?: string;
     orgSlug?: string;
 }
-/** Options for local JWT verification */
+/** Options for local JWT verification (HS256) */
 interface VerifyOptions {
     /** Expected issuer (default: config issuer) */
     issuer?: string;
     /** Expected audience (client_id) */
     audience?: string;
 }
+/** Options for JWKS-based JWT verification (RS256) */
+interface JWKSVerifyOptions {
+    /** JWKS endpoint URL (default: https://bio.tawa.insureco.io/.well-known/jwks.json) */
+    jwksUri?: string;
+    /** Expected issuer — defaults to accepting both bio.insureco.io and bio.tawa.insureco.io */
+    issuer?: string;
+    /** Expected audience (client_id) */
+    audience?: string;
+}
 /** User profile from /api/oauth/userinfo or admin API */
 interface BioUser {
     sub: string;
@@ -367,8 +376,10 @@ declare function generatePKCE(): {
 };
 
 /**
- * Verify a Bio-ID JWT access token using HS256.
+ * Verify a Bio-ID JWT access token using HS256 (legacy / internal use).
  * Checks algorithm, signature (constant-time), expiration, issuer, and audience.
+ *
+ * @deprecated Prefer verifyTokenJWKS() for RS256 tokens issued by Bio-ID ≥ 0.2.
  */
 declare function verifyToken(token: string, secret: string, options?: VerifyOptions): BioTokenPayload;
 /**
@@ -381,5 +392,20 @@ declare function decodeToken(token: string): BioTokenPayload | null;
  * Returns true if expired or unparseable.
  */
 declare function isTokenExpired(token: string, bufferSeconds?: number): boolean;
+/**
+ * Verify a Bio-ID JWT access token using RS256 and the public JWKS endpoint.
+ *
+ * No shared secret required — fetches Bio-ID's public key and verifies locally.
+ * The JWKS is cached in-process for 24 hours and auto-refreshed on key rotation.
+ *
+ * @example
+ * ```ts
+ * import { verifyTokenJWKS } from '@insureco/bio'
+ *
+ * const payload = await verifyTokenJWKS(req.headers.authorization.slice(7))
+ * console.log(payload.bioId, payload.orgSlug)
+ * ```
+ */
+declare function verifyTokenJWKS(token: string, options?: JWKSVerifyOptions): Promise<BioTokenPayload>;
 
-export { type AdminResponse, type AuthorizeOptions, type AuthorizeResult, type BioAddress, BioAdmin, type BioAdminConfig, BioAuth, type BioAuthConfig, type BioClientTokenPayload, type BioDepartment, BioError, type BioMessaging, type BioOAuthClient, type BioRole, type BioTokenPayload, type BioUser, type CreateClientData, type CreateDepartmentData, type CreateRoleData, type IntrospectResult, type TokenResponse, type UpdateUserData, type UserFilters, type VerifyOptions, decodeToken, generatePKCE, isTokenExpired, verifyToken };
+export { type AdminResponse, type AuthorizeOptions, type AuthorizeResult, type BioAddress, BioAdmin, type BioAdminConfig, BioAuth, type BioAuthConfig, type BioClientTokenPayload, type BioDepartment, BioError, type BioMessaging, type BioOAuthClient, type BioRole, type BioTokenPayload, type BioUser, type CreateClientData, type CreateDepartmentData, type CreateRoleData, type IntrospectResult, type JWKSVerifyOptions, type TokenResponse, type UpdateUserData, type UserFilters, type VerifyOptions, decodeToken, generatePKCE, isTokenExpired, verifyToken, verifyTokenJWKS };

package/dist/index.js

@@ -36,7 +36,8 @@ __export(index_exports, {
   decodeToken: () => decodeToken,
   generatePKCE: () => generatePKCE,
   isTokenExpired: () => isTokenExpired,
-  verifyToken: () => verifyToken
+  verifyToken: () => verifyToken,
+  verifyTokenJWKS: () => verifyTokenJWKS
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -588,6 +589,57 @@ var DEFAULT_ISSUERS = [
   "https://bio.tawa.insureco.io",
   "http://localhost:6100"
 ];
+var DEFAULT_JWKS_URI = "https://bio.tawa.insureco.io/.well-known/jwks.json";
+var JWKS_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+var jwksCache = /* @__PURE__ */ new Map();
+async function fetchJWKS(uri) {
+  const cached = jwksCache.get(uri);
+  if (cached && Date.now() - cached.fetchedAt < JWKS_CACHE_TTL_MS) {
+    return cached.keys;
+  }
+  const response = await fetch(uri, {
+    headers: { Accept: "application/json" },
+    signal: AbortSignal.timeout(5e3)
+  });
+  if (!response.ok) {
+    throw new BioError(`JWKS fetch failed: ${response.status}`, "jwks_fetch_failed");
+  }
+  const data = await response.json();
+  jwksCache.set(uri, { keys: data.keys, fetchedAt: Date.now() });
+  return data.keys;
+}
+async function importRS256Key(jwk) {
+  return globalThis.crypto.subtle.importKey(
+    "jwk",
+    jwk,
+    { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+    false,
+    ["verify"]
+  );
+}
+async function verifyRS256Signature(headerB64, payloadB64, signatureB64, jwksUri, kid, retrying = false) {
+  const keys = await fetchJWKS(jwksUri);
+  const targetKey = kid ? keys.find((k) => k.kid === kid) ?? keys[0] : keys[0];
+  if (!targetKey) {
+    throw new BioError("No matching key found in JWKS", "invalid_token");
+  }
+  const cryptoKey = await importRS256Key(targetKey);
+  const data = new TextEncoder().encode(`${headerB64}.${payloadB64}`);
+  const signature = Buffer.from(signatureB64, "base64url");
+  const valid = await globalThis.crypto.subtle.verify(
+    "RSASSA-PKCS1-v1_5",
+    cryptoKey,
+    signature,
+    data
+  );
+  if (!valid) {
+    if (!retrying) {
+      jwksCache.delete(jwksUri);
+      return verifyRS256Signature(headerB64, payloadB64, signatureB64, jwksUri, kid, true);
+    }
+    throw new BioError("Invalid JWT signature", "invalid_signature");
+  }
+}
 function base64UrlDecode(str) {
   return Buffer.from(str, "base64url").toString("utf8");
 }
@@ -598,6 +650,12 @@ function verifyToken(token, secret, options) {
   }
   const [headerB64, payloadB64, signatureB64] = parts;
   const header = JSON.parse(base64UrlDecode(headerB64));
+  if (header.alg === "RS256") {
+    throw new BioError(
+      "Token uses RS256 \u2014 use verifyTokenJWKS() instead of verifyToken()",
+      "unsupported_alg"
+    );
+  }
   if (header.alg !== "HS256") {
     throw new BioError(`Unsupported algorithm: ${header.alg}`, "unsupported_alg");
   }
@@ -642,6 +700,34 @@ function isTokenExpired(token, bufferSeconds = 30) {
   const now = Math.floor(Date.now() / 1e3);
   return payload.exp < now + bufferSeconds;
 }
+async function verifyTokenJWKS(token, options) {
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    throw new BioError("Malformed JWT: expected 3 parts", "invalid_token");
+  }
+  const [headerB64, payloadB64, signatureB64] = parts;
+  const header = JSON.parse(base64UrlDecode(headerB64));
+  if (header.alg !== "RS256") {
+    throw new BioError(
+      `Expected RS256 token, got ${header.alg}. Use verifyToken() for HS256.`,
+      "unsupported_alg"
+    );
+  }
+  const jwksUri = options?.jwksUri ?? DEFAULT_JWKS_URI;
+  await verifyRS256Signature(headerB64, payloadB64, signatureB64, jwksUri, header.kid);
+  const payload = JSON.parse(base64UrlDecode(payloadB64));
+  const now = Math.floor(Date.now() / 1e3);
+  if (!payload.exp) throw new BioError("Token missing expiration claim", "invalid_token");
+  if (payload.exp < now) throw new BioError("Token has expired", "token_expired");
+  const allowedIssuers = options?.issuer ? [options.issuer] : DEFAULT_ISSUERS;
+  if (!allowedIssuers.includes(payload.iss)) {
+    throw new BioError(`Unknown issuer: ${payload.iss}`, "invalid_issuer");
+  }
+  if (options?.audience && payload.aud !== options.audience) {
+    throw new BioError(`Invalid audience: ${payload.aud}`, "invalid_audience");
+  }
+  return payload;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BioAdmin,
@@ -650,5 +736,6 @@ function isTokenExpired(token, bufferSeconds = 30) {
   decodeToken,
   generatePKCE,
   isTokenExpired,
-  verifyToken
+  verifyToken,
+  verifyTokenJWKS
 });

package/dist/index.mjs

@@ -546,6 +546,57 @@ var DEFAULT_ISSUERS = [
   "https://bio.tawa.insureco.io",
   "http://localhost:6100"
 ];
+var DEFAULT_JWKS_URI = "https://bio.tawa.insureco.io/.well-known/jwks.json";
+var JWKS_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+var jwksCache = /* @__PURE__ */ new Map();
+async function fetchJWKS(uri) {
+  const cached = jwksCache.get(uri);
+  if (cached && Date.now() - cached.fetchedAt < JWKS_CACHE_TTL_MS) {
+    return cached.keys;
+  }
+  const response = await fetch(uri, {
+    headers: { Accept: "application/json" },
+    signal: AbortSignal.timeout(5e3)
+  });
+  if (!response.ok) {
+    throw new BioError(`JWKS fetch failed: ${response.status}`, "jwks_fetch_failed");
+  }
+  const data = await response.json();
+  jwksCache.set(uri, { keys: data.keys, fetchedAt: Date.now() });
+  return data.keys;
+}
+async function importRS256Key(jwk) {
+  return globalThis.crypto.subtle.importKey(
+    "jwk",
+    jwk,
+    { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+    false,
+    ["verify"]
+  );
+}
+async function verifyRS256Signature(headerB64, payloadB64, signatureB64, jwksUri, kid, retrying = false) {
+  const keys = await fetchJWKS(jwksUri);
+  const targetKey = kid ? keys.find((k) => k.kid === kid) ?? keys[0] : keys[0];
+  if (!targetKey) {
+    throw new BioError("No matching key found in JWKS", "invalid_token");
+  }
+  const cryptoKey = await importRS256Key(targetKey);
+  const data = new TextEncoder().encode(`${headerB64}.${payloadB64}`);
+  const signature = Buffer.from(signatureB64, "base64url");
+  const valid = await globalThis.crypto.subtle.verify(
+    "RSASSA-PKCS1-v1_5",
+    cryptoKey,
+    signature,
+    data
+  );
+  if (!valid) {
+    if (!retrying) {
+      jwksCache.delete(jwksUri);
+      return verifyRS256Signature(headerB64, payloadB64, signatureB64, jwksUri, kid, true);
+    }
+    throw new BioError("Invalid JWT signature", "invalid_signature");
+  }
+}
 function base64UrlDecode(str) {
   return Buffer.from(str, "base64url").toString("utf8");
 }
@@ -556,6 +607,12 @@ function verifyToken(token, secret, options) {
   }
   const [headerB64, payloadB64, signatureB64] = parts;
   const header = JSON.parse(base64UrlDecode(headerB64));
+  if (header.alg === "RS256") {
+    throw new BioError(
+      "Token uses RS256 \u2014 use verifyTokenJWKS() instead of verifyToken()",
+      "unsupported_alg"
+    );
+  }
   if (header.alg !== "HS256") {
     throw new BioError(`Unsupported algorithm: ${header.alg}`, "unsupported_alg");
   }
@@ -600,6 +657,34 @@ function isTokenExpired(token, bufferSeconds = 30) {
   const now = Math.floor(Date.now() / 1e3);
   return payload.exp < now + bufferSeconds;
 }
+async function verifyTokenJWKS(token, options) {
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    throw new BioError("Malformed JWT: expected 3 parts", "invalid_token");
+  }
+  const [headerB64, payloadB64, signatureB64] = parts;
+  const header = JSON.parse(base64UrlDecode(headerB64));
+  if (header.alg !== "RS256") {
+    throw new BioError(
+      `Expected RS256 token, got ${header.alg}. Use verifyToken() for HS256.`,
+      "unsupported_alg"
+    );
+  }
+  const jwksUri = options?.jwksUri ?? DEFAULT_JWKS_URI;
+  await verifyRS256Signature(headerB64, payloadB64, signatureB64, jwksUri, header.kid);
+  const payload = JSON.parse(base64UrlDecode(payloadB64));
+  const now = Math.floor(Date.now() / 1e3);
+  if (!payload.exp) throw new BioError("Token missing expiration claim", "invalid_token");
+  if (payload.exp < now) throw new BioError("Token has expired", "token_expired");
+  const allowedIssuers = options?.issuer ? [options.issuer] : DEFAULT_ISSUERS;
+  if (!allowedIssuers.includes(payload.iss)) {
+    throw new BioError(`Unknown issuer: ${payload.iss}`, "invalid_issuer");
+  }
+  if (options?.audience && payload.aud !== options.audience) {
+    throw new BioError(`Invalid audience: ${payload.aud}`, "invalid_audience");
+  }
+  return payload;
+}
 export {
   BioAdmin,
   BioAuth,
@@ -607,5 +692,6 @@ export {
   decodeToken,
   generatePKCE,
   isTokenExpired,
-  verifyToken
+  verifyToken,
+  verifyTokenJWKS
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@insureco/bio",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "SDK for Bio-ID SSO integration on the Tawa platform",
   "main": "dist/index.js",
   "module": "dist/index.mjs",