@insureco/bio 0.1.0 → 0.3.0

package/dist/index.d.mts

@@ -4,7 +4,7 @@ interface BioAuthConfig {
     clientId: string;
     /** OAuth client secret (env: BIO_CLIENT_SECRET) */
     clientSecret: string;
-    /** Bio-ID issuer URL (env: BIO_ID_URL, default: https://bio.tawa.insureco.io) */
+    /** Bio-ID issuer URL (env: BIO_ID_URL, default: https://bio.tawa.pro) */
     issuer?: string;
     /** Number of retry attempts on transient failures (default: 2) */
     retries?: number;
@@ -13,7 +13,7 @@ interface BioAuthConfig {
 }
 /** Configuration for BioAdmin (admin API client) */
 interface BioAdminConfig {
-    /** Bio-ID base URL (env: BIO_ID_URL, default: https://bio.tawa.insureco.io) */
+    /** Bio-ID base URL (env: BIO_ID_URL, default: https://bio.tawa.pro) */
     baseUrl?: string;
     /** Internal API key for service-to-service auth (env: INTERNAL_API_KEY) */
     internalKey?: string;
@@ -32,6 +32,8 @@ interface AuthorizeOptions {
     scopes?: string[];
     /** CSRF state parameter (auto-generated if not provided) */
     state?: string;
+    /** Optional org slug to pre-select during authorization (for multi-org users) */
+    organization?: string;
 }
 /** Result from getAuthorizationUrl() */
 interface AuthorizeResult {
@@ -85,6 +87,12 @@ interface BioTokenPayload {
     permissions: string[];
     orgId?: string;
     orgSlug?: string;
+    /** Org-specific role slugs within the user's active org (from OrgMembership) */
+    orgRoles?: string[];
+    /** Job title at the active org (from OrgMembership.jobTitle) */
+    orgTitle?: string;
+    /** Additional modules granted by the org specifically (from OrgMembership.enabled_modules) */
+    orgModules?: string[];
     client_id: string;
     scope: string;
     enabled_modules?: string[];
@@ -107,13 +115,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.pro/.well-known/jwks.json) */
+    jwksUri?: string;
+    /** Expected issuer — defaults to accepting bio.insureco.io, bio.tawa.insureco.io, and bio.tawa.pro */
+    issuer?: string;
+    /** Expected audience (client_id) */
+    audience?: string;
+}
 /** User profile from /api/oauth/userinfo or admin API */
 interface BioUser {
     sub: string;
@@ -367,8 +384,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 +400,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

@@ -4,7 +4,7 @@ interface BioAuthConfig {
     clientId: string;
     /** OAuth client secret (env: BIO_CLIENT_SECRET) */
     clientSecret: string;
-    /** Bio-ID issuer URL (env: BIO_ID_URL, default: https://bio.tawa.insureco.io) */
+    /** Bio-ID issuer URL (env: BIO_ID_URL, default: https://bio.tawa.pro) */
     issuer?: string;
     /** Number of retry attempts on transient failures (default: 2) */
     retries?: number;
@@ -13,7 +13,7 @@ interface BioAuthConfig {
 }
 /** Configuration for BioAdmin (admin API client) */
 interface BioAdminConfig {
-    /** Bio-ID base URL (env: BIO_ID_URL, default: https://bio.tawa.insureco.io) */
+    /** Bio-ID base URL (env: BIO_ID_URL, default: https://bio.tawa.pro) */
     baseUrl?: string;
     /** Internal API key for service-to-service auth (env: INTERNAL_API_KEY) */
     internalKey?: string;
@@ -32,6 +32,8 @@ interface AuthorizeOptions {
     scopes?: string[];
     /** CSRF state parameter (auto-generated if not provided) */
     state?: string;
+    /** Optional org slug to pre-select during authorization (for multi-org users) */
+    organization?: string;
 }
 /** Result from getAuthorizationUrl() */
 interface AuthorizeResult {
@@ -85,6 +87,12 @@ interface BioTokenPayload {
     permissions: string[];
     orgId?: string;
     orgSlug?: string;
+    /** Org-specific role slugs within the user's active org (from OrgMembership) */
+    orgRoles?: string[];
+    /** Job title at the active org (from OrgMembership.jobTitle) */
+    orgTitle?: string;
+    /** Additional modules granted by the org specifically (from OrgMembership.enabled_modules) */
+    orgModules?: string[];
     client_id: string;
     scope: string;
     enabled_modules?: string[];
@@ -107,13 +115,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.pro/.well-known/jwks.json) */
+    jwksUri?: string;
+    /** Expected issuer — defaults to accepting bio.insureco.io, bio.tawa.insureco.io, and bio.tawa.pro */
+    issuer?: string;
+    /** Expected audience (client_id) */
+    audience?: string;
+}
 /** User profile from /api/oauth/userinfo or admin API */
 interface BioUser {
     sub: string;
@@ -367,8 +384,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 +400,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);
 
@@ -89,7 +90,7 @@ async function parseJsonResponse(response) {
 }
 
 // src/auth.ts
-var DEFAULT_ISSUER = "https://bio.tawa.insureco.io";
+var DEFAULT_ISSUER = "https://bio.tawa.pro";
 var DEFAULT_SCOPES = ["openid", "profile", "email"];
 var DEFAULT_TIMEOUT_MS = 1e4;
 var BioAuth = class _BioAuth {
@@ -159,6 +160,9 @@ var BioAuth = class _BioAuth {
       code_challenge: codeChallenge,
       code_challenge_method: "S256"
     });
+    if (opts.organization) {
+      params.set("organization", opts.organization);
+    }
     return {
       url: `${this.issuer}/oauth/authorize?${params.toString()}`,
       state,
@@ -380,7 +384,7 @@ function mapIntrospectResponse(raw) {
 }
 
 // src/admin.ts
-var DEFAULT_BASE_URL = "https://bio.tawa.insureco.io";
+var DEFAULT_BASE_URL = "https://bio.tawa.pro";
 var DEFAULT_TIMEOUT_MS2 = 1e4;
 var BioAdmin = class _BioAdmin {
   baseUrl;
@@ -586,8 +590,60 @@ var import_node_crypto3 = __toESM(require("crypto"));
 var DEFAULT_ISSUERS = [
   "https://bio.insureco.io",
   "https://bio.tawa.insureco.io",
+  "https://bio.tawa.pro",
   "http://localhost:6100"
 ];
+var DEFAULT_JWKS_URI = "https://bio.tawa.pro/.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 +654,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 +704,39 @@ 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;
+  let header;
+  try {
+    header = JSON.parse(base64UrlDecode(headerB64));
+  } catch {
+    throw new BioError("Malformed JWT: invalid header encoding", "invalid_token");
+  }
+  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 +745,6 @@ function isTokenExpired(token, bufferSeconds = 30) {
   decodeToken,
   generatePKCE,
   isTokenExpired,
-  verifyToken
+  verifyToken,
+  verifyTokenJWKS
 });

package/dist/index.mjs

@@ -47,7 +47,7 @@ async function parseJsonResponse(response) {
 }
 
 // src/auth.ts
-var DEFAULT_ISSUER = "https://bio.tawa.insureco.io";
+var DEFAULT_ISSUER = "https://bio.tawa.pro";
 var DEFAULT_SCOPES = ["openid", "profile", "email"];
 var DEFAULT_TIMEOUT_MS = 1e4;
 var BioAuth = class _BioAuth {
@@ -117,6 +117,9 @@ var BioAuth = class _BioAuth {
       code_challenge: codeChallenge,
       code_challenge_method: "S256"
     });
+    if (opts.organization) {
+      params.set("organization", opts.organization);
+    }
     return {
       url: `${this.issuer}/oauth/authorize?${params.toString()}`,
       state,
@@ -338,7 +341,7 @@ function mapIntrospectResponse(raw) {
 }
 
 // src/admin.ts
-var DEFAULT_BASE_URL = "https://bio.tawa.insureco.io";
+var DEFAULT_BASE_URL = "https://bio.tawa.pro";
 var DEFAULT_TIMEOUT_MS2 = 1e4;
 var BioAdmin = class _BioAdmin {
   baseUrl;
@@ -544,8 +547,60 @@ import crypto3 from "crypto";
 var DEFAULT_ISSUERS = [
   "https://bio.insureco.io",
   "https://bio.tawa.insureco.io",
+  "https://bio.tawa.pro",
   "http://localhost:6100"
 ];
+var DEFAULT_JWKS_URI = "https://bio.tawa.pro/.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 +611,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 +661,39 @@ 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;
+  let header;
+  try {
+    header = JSON.parse(base64UrlDecode(headerB64));
+  } catch {
+    throw new BioError("Malformed JWT: invalid header encoding", "invalid_token");
+  }
+  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 +701,6 @@ export {
   decodeToken,
   generatePKCE,
   isTokenExpired,
-  verifyToken
+  verifyToken,
+  verifyTokenJWKS
 };

package/package.json

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