@insureco/bio 0.1.0

package/dist/index.mjs

@@ -0,0 +1,611 @@
+// src/auth.ts
+import crypto2 from "crypto";
+
+// src/errors.ts
+var BioError = class extends Error {
+  /** HTTP status code (if from an API response) */
+  statusCode;
+  /** Machine-readable error code (e.g. 'invalid_grant', 'token_expired') */
+  code;
+  /** Additional error details from the API */
+  details;
+  constructor(message, code, statusCode, details) {
+    super(message);
+    this.name = "BioError";
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+  }
+};
+
+// src/pkce.ts
+import crypto from "crypto";
+function generatePKCE() {
+  const codeVerifier = crypto.randomBytes(32).toString("base64url");
+  const codeChallenge = crypto.createHash("sha256").update(codeVerifier).digest("base64url");
+  return { codeVerifier, codeChallenge };
+}
+
+// src/utils.ts
+function retryDelay(attempt) {
+  const baseDelay = Math.min(1e3 * 2 ** attempt, 5e3);
+  return baseDelay * (0.5 + Math.random() * 0.5);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function parseJsonResponse(response) {
+  try {
+    return await response.json();
+  } catch {
+    throw new BioError(
+      `Bio-ID returned ${response.status} with non-JSON body`,
+      "parse_error",
+      response.status
+    );
+  }
+}
+
+// src/auth.ts
+var DEFAULT_ISSUER = "https://bio.tawa.insureco.io";
+var DEFAULT_SCOPES = ["openid", "profile", "email"];
+var DEFAULT_TIMEOUT_MS = 1e4;
+var BioAuth = class _BioAuth {
+  clientId;
+  clientSecret;
+  issuer;
+  retries;
+  timeoutMs;
+  constructor(config) {
+    if (!config.clientId) {
+      throw new BioError("clientId is required", "config_error");
+    }
+    if (!config.clientSecret) {
+      throw new BioError("clientSecret is required", "config_error");
+    }
+    this.clientId = config.clientId;
+    this.clientSecret = config.clientSecret;
+    this.issuer = (config.issuer ?? DEFAULT_ISSUER).replace(/\/$/, "");
+    this.retries = config.retries ?? 2;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+  /**
+   * Create a BioAuth from environment variables.
+   *
+   * Reads: BIO_CLIENT_ID, BIO_CLIENT_SECRET, BIO_ID_URL
+   */
+  static fromEnv() {
+    const clientId = process.env.BIO_CLIENT_ID;
+    const clientSecret = process.env.BIO_CLIENT_SECRET;
+    if (!clientId) {
+      throw new BioError(
+        "BIO_CLIENT_ID environment variable is required",
+        "config_error"
+      );
+    }
+    if (!clientSecret) {
+      throw new BioError(
+        "BIO_CLIENT_SECRET environment variable is required",
+        "config_error"
+      );
+    }
+    return new _BioAuth({
+      clientId,
+      clientSecret,
+      issuer: process.env.BIO_ID_URL
+    });
+  }
+  /**
+   * Build an authorization URL with PKCE for redirecting the user to Bio-ID.
+   *
+   * Returns the URL, state, and PKCE verifier/challenge.
+   * Store the state and codeVerifier securely (e.g. in a cookie) for the callback.
+   */
+  getAuthorizationUrl(opts) {
+    if (!opts.redirectUri) {
+      throw new BioError("redirectUri is required", "validation_error");
+    }
+    const state = opts.state ?? crypto2.randomBytes(16).toString("hex");
+    const { codeVerifier, codeChallenge } = generatePKCE();
+    const scopes = opts.scopes ?? DEFAULT_SCOPES;
+    const params = new URLSearchParams({
+      client_id: this.clientId,
+      redirect_uri: opts.redirectUri,
+      response_type: "code",
+      scope: scopes.join(" "),
+      state,
+      code_challenge: codeChallenge,
+      code_challenge_method: "S256"
+    });
+    return {
+      url: `${this.issuer}/oauth/authorize?${params.toString()}`,
+      state,
+      codeVerifier,
+      codeChallenge
+    };
+  }
+  /**
+   * Exchange an authorization code for tokens.
+   *
+   * Called in your OAuth callback handler after the user authorizes.
+   */
+  async exchangeCode(code, codeVerifier, redirectUri) {
+    if (!code) throw new BioError("code is required", "validation_error");
+    if (!codeVerifier) throw new BioError("codeVerifier is required", "validation_error");
+    if (!redirectUri) throw new BioError("redirectUri is required", "validation_error");
+    return this.tokenRequest({
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: redirectUri,
+      client_id: this.clientId,
+      client_secret: this.clientSecret,
+      code_verifier: codeVerifier
+    });
+  }
+  /**
+   * Refresh an expired access token using a refresh token.
+   *
+   * Returns new access_token and a rotated refresh_token.
+   */
+  async refreshToken(refreshToken) {
+    if (!refreshToken) throw new BioError("refreshToken is required", "validation_error");
+    return this.tokenRequest({
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+      client_id: this.clientId,
+      client_secret: this.clientSecret
+    });
+  }
+  /**
+   * Get a client credentials token for service-to-service auth.
+   *
+   * No user context — the token identifies your OAuth client only.
+   */
+  async getClientCredentialsToken(scopes) {
+    const params = {
+      grant_type: "client_credentials",
+      client_id: this.clientId,
+      client_secret: this.clientSecret
+    };
+    if (scopes?.length) {
+      params.scope = scopes.join(" ");
+    }
+    return this.tokenRequest(params);
+  }
+  /**
+   * Fetch the authenticated user's profile from the userinfo endpoint.
+   */
+  async getUserInfo(accessToken) {
+    const raw = await this.request(
+      "GET",
+      "/api/oauth/userinfo",
+      void 0,
+      { Authorization: `Bearer ${accessToken}` }
+    );
+    return mapUserInfoResponse(raw);
+  }
+  /**
+   * Revoke a token (typically the refresh token on logout).
+   */
+  async revokeToken(token, hint) {
+    const body = new URLSearchParams({
+      token,
+      client_id: this.clientId,
+      client_secret: this.clientSecret
+    });
+    if (hint) {
+      body.set("token_type_hint", hint);
+    }
+    const response = await this.fetchWithRetry("POST", `${this.issuer}/api/oauth/revoke`, {
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: body.toString()
+    });
+    if (!response.ok) {
+      const json = await parseJsonResponse(response);
+      throw new BioError(
+        json.error_description ?? json.error ?? `Revocation failed (${response.status})`,
+        "revocation_error",
+        response.status
+      );
+    }
+  }
+  /**
+   * Introspect a token to check if it's active and get user/client context.
+   *
+   * Does not require JWT_SECRET — validates against Bio-ID server.
+   */
+  async introspect(token) {
+    const raw = await this.request("POST", "/api/auth/introspect", { token });
+    return mapIntrospectResponse(raw);
+  }
+  // ── Private helpers ──────────────────────────────────────────────────────
+  async tokenRequest(params) {
+    const response = await this.fetchWithRetry(
+      "POST",
+      `${this.issuer}/api/oauth/token`,
+      {
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams(params).toString()
+      }
+    );
+    const json = await parseJsonResponse(response);
+    if (!response.ok) {
+      throw new BioError(
+        json.error_description ?? json.error ?? `Token request failed (${response.status})`,
+        json.error ?? "token_error",
+        response.status,
+        json
+      );
+    }
+    return json;
+  }
+  async request(method, path, body, extraHeaders) {
+    const headers = {
+      ...extraHeaders
+    };
+    if (body) {
+      headers["Content-Type"] = "application/json";
+    }
+    const response = await this.fetchWithRetry(
+      method,
+      `${this.issuer}${path}`,
+      {
+        headers,
+        body: body ? JSON.stringify(body) : void 0
+      }
+    );
+    const json = await parseJsonResponse(response);
+    if (!response.ok) {
+      throw new BioError(
+        json.error ?? `Bio-ID returned ${response.status}`,
+        json.error ?? "api_error",
+        response.status,
+        json
+      );
+    }
+    return json;
+  }
+  async fetchWithRetry(method, url, init, attempt = 0) {
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: init.headers,
+        body: init.body,
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+      if (response.status >= 500 && attempt < this.retries) {
+        await sleep(retryDelay(attempt));
+        return this.fetchWithRetry(method, url, init, attempt + 1);
+      }
+      return response;
+    } catch (err) {
+      if (attempt < this.retries) {
+        await sleep(retryDelay(attempt));
+        return this.fetchWithRetry(method, url, init, attempt + 1);
+      }
+      const isTimeout = err instanceof DOMException && err.name === "TimeoutError";
+      throw new BioError(
+        isTimeout ? `Request timed out after ${this.timeoutMs}ms` : err instanceof Error ? err.message : "Network error",
+        isTimeout ? "timeout" : "network_error"
+      );
+    }
+  }
+};
+function mapUserInfoResponse(raw) {
+  return {
+    sub: raw.sub,
+    bioId: raw.bio_id ?? raw.sub,
+    email: raw.email,
+    emailVerified: raw.email_verified ?? false,
+    name: raw.name,
+    firstName: raw.given_name,
+    lastName: raw.family_name,
+    userType: raw.user_type ?? "user",
+    roles: raw.roles ?? [],
+    permissions: raw.permissions ?? [],
+    status: raw.status ?? "active",
+    orgId: raw.org_id,
+    orgSlug: raw.org_slug,
+    organizationId: raw.organization_id,
+    organizationName: raw.organization_name,
+    departmentId: raw.department_id,
+    departmentName: raw.department_name,
+    managerId: raw.manager_id,
+    enabledModules: raw.enabled_modules,
+    jobTitle: raw.job_title,
+    phoneHome: raw.phone_home,
+    phoneWork: raw.phone_work,
+    phoneCell: raw.phone_cell,
+    phone: raw.phone_number,
+    addressHome: raw.address_home,
+    addressWork: raw.address_work,
+    messaging: raw.messaging,
+    preferences: raw.preferences,
+    lastLoginAt: raw.last_login_at
+  };
+}
+function mapIntrospectResponse(raw) {
+  return {
+    active: raw.active,
+    user: raw.user,
+    tokenType: raw.token_type,
+    clientId: raw.client_id,
+    scopes: raw.scopes,
+    orgId: raw.org_id ?? raw.orgId,
+    orgSlug: raw.org_slug ?? raw.orgSlug,
+    organizationName: raw.organization_name ?? raw.organizationName
+  };
+}
+
+// src/admin.ts
+var DEFAULT_BASE_URL = "https://bio.tawa.insureco.io";
+var DEFAULT_TIMEOUT_MS2 = 1e4;
+var BioAdmin = class _BioAdmin {
+  baseUrl;
+  internalKey;
+  accessTokenFn;
+  retries;
+  timeoutMs;
+  constructor(config) {
+    if (!config.internalKey && !config.accessTokenFn) {
+      throw new BioError(
+        "Either internalKey or accessTokenFn is required",
+        "config_error"
+      );
+    }
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.internalKey = config.internalKey;
+    this.accessTokenFn = config.accessTokenFn;
+    this.retries = config.retries ?? 2;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
+  }
+  /**
+   * Create a BioAdmin from environment variables.
+   *
+   * Reads: BIO_ID_URL, INTERNAL_API_KEY
+   */
+  static fromEnv() {
+    const internalKey = process.env.INTERNAL_API_KEY;
+    if (!internalKey) {
+      throw new BioError(
+        "INTERNAL_API_KEY environment variable is required",
+        "config_error"
+      );
+    }
+    return new _BioAdmin({
+      baseUrl: process.env.BIO_ID_URL,
+      internalKey
+    });
+  }
+  // ── Users ────────────────────────────────────────────────────────────────
+  /** List users with optional filters */
+  async listUsers(filters) {
+    const params = new URLSearchParams();
+    if (filters?.search) params.set("search", filters.search);
+    if (filters?.status) params.set("status", filters.status);
+    if (filters?.userType) params.set("userType", filters.userType);
+    if (filters?.organizationId) params.set("organizationId", filters.organizationId);
+    if (filters?.page) params.set("page", String(filters.page));
+    if (filters?.limit) params.set("limit", String(filters.limit));
+    const qs = params.toString();
+    const path = qs ? `/api/admin/users?${qs}` : "/api/admin/users";
+    const result = await this.request("GET", path);
+    return result.data ?? [];
+  }
+  /** Get a single user by bioId */
+  async getUser(bioId) {
+    const result = await this.request(
+      "GET",
+      `/api/admin/users/${encodeURIComponent(bioId)}`
+    );
+    if (!result.data) {
+      throw new BioError(`User ${bioId} not found`, "not_found", 404);
+    }
+    return result.data;
+  }
+  /** Update a user's profile, roles, or status */
+  async updateUser(bioId, data) {
+    const result = await this.request(
+      "PATCH",
+      `/api/admin/users/${encodeURIComponent(bioId)}`,
+      data
+    );
+    if (!result.data) {
+      throw new BioError(`Failed to update user ${bioId}`, "update_failed");
+    }
+    return result.data;
+  }
+  // ── Departments ──────────────────────────────────────────────────────────
+  /** List all departments */
+  async listDepartments() {
+    const result = await this.request(
+      "GET",
+      "/api/admin/departments"
+    );
+    return result.data ?? [];
+  }
+  /** Create a new department */
+  async createDepartment(data) {
+    const result = await this.request(
+      "POST",
+      "/api/admin/departments",
+      data
+    );
+    if (!result.data) {
+      throw new BioError("Failed to create department", "create_failed");
+    }
+    return result.data;
+  }
+  // ── Roles ────────────────────────────────────────────────────────────────
+  /** List all roles */
+  async listRoles() {
+    const result = await this.request(
+      "GET",
+      "/api/admin/roles"
+    );
+    return result.data ?? [];
+  }
+  /** Create a new role */
+  async createRole(data) {
+    const result = await this.request(
+      "POST",
+      "/api/admin/roles",
+      data
+    );
+    if (!result.data) {
+      throw new BioError("Failed to create role", "create_failed");
+    }
+    return result.data;
+  }
+  // ── OAuth Clients ────────────────────────────────────────────────────────
+  /** List all OAuth clients */
+  async listClients() {
+    const result = await this.request(
+      "GET",
+      "/api/admin/oauth-clients"
+    );
+    return result.data ?? [];
+  }
+  /** Create a new OAuth client */
+  async createClient(data) {
+    const result = await this.request(
+      "POST",
+      "/api/admin/oauth-clients",
+      data
+    );
+    if (!result.data) {
+      throw new BioError("Failed to create OAuth client", "create_failed");
+    }
+    return result.data;
+  }
+  // ── Private helpers ──────────────────────────────────────────────────────
+  async request(method, path, body, attempt = 0) {
+    const headers = {};
+    if (this.internalKey) {
+      headers["x-internal-key"] = this.internalKey;
+    } else if (this.accessTokenFn) {
+      headers["Authorization"] = `Bearer ${await this.accessTokenFn()}`;
+    }
+    if (body) {
+      headers["Content-Type"] = "application/json";
+    }
+    let response;
+    try {
+      response = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0,
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+    } catch (err) {
+      if (attempt < this.retries) {
+        await sleep(retryDelay(attempt));
+        return this.request(method, path, body, attempt + 1);
+      }
+      const isTimeout = err instanceof DOMException && err.name === "TimeoutError";
+      throw new BioError(
+        isTimeout ? `Request timed out after ${this.timeoutMs}ms` : err instanceof Error ? err.message : "Network error",
+        isTimeout ? "timeout" : "network_error"
+      );
+    }
+    let json;
+    try {
+      json = await response.json();
+    } catch {
+      if (response.status >= 500 && attempt < this.retries) {
+        await sleep(retryDelay(attempt));
+        return this.request(method, path, body, attempt + 1);
+      }
+      throw new BioError(
+        `Bio-ID returned ${response.status} with non-JSON body`,
+        "parse_error",
+        response.status
+      );
+    }
+    if (!response.ok) {
+      if (response.status >= 500 && attempt < this.retries) {
+        await sleep(retryDelay(attempt));
+        return this.request(method, path, body, attempt + 1);
+      }
+      const errorBody = json;
+      throw new BioError(
+        errorBody.error ?? `Bio-ID returned ${response.status}`,
+        errorBody.error ?? "api_error",
+        response.status,
+        errorBody
+      );
+    }
+    return json;
+  }
+};
+
+// src/jwt.ts
+import crypto3 from "crypto";
+var DEFAULT_ISSUERS = [
+  "https://bio.insureco.io",
+  "https://bio.tawa.insureco.io",
+  "http://localhost:6100"
+];
+function base64UrlDecode(str) {
+  return Buffer.from(str, "base64url").toString("utf8");
+}
+function verifyToken(token, secret, 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 !== "HS256") {
+    throw new BioError(`Unsupported algorithm: ${header.alg}`, "unsupported_alg");
+  }
+  const data = `${headerB64}.${payloadB64}`;
+  const expectedBuf = crypto3.createHmac("sha256", secret).update(data).digest();
+  const actualBuf = Buffer.from(signatureB64, "base64url");
+  if (expectedBuf.length !== actualBuf.length || !crypto3.timingSafeEqual(expectedBuf, actualBuf)) {
+    throw new BioError("Invalid JWT signature", "invalid_signature");
+  }
+  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");
+  }
+  if (options?.issuer) {
+    if (payload.iss !== options.issuer) {
+      throw new BioError(`Invalid issuer: ${payload.iss}`, "invalid_issuer");
+    }
+  } else if (!DEFAULT_ISSUERS.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;
+}
+function decodeToken(token) {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) return null;
+    return JSON.parse(base64UrlDecode(parts[1]));
+  } catch {
+    return null;
+  }
+}
+function isTokenExpired(token, bufferSeconds = 30) {
+  const payload = decodeToken(token);
+  if (!payload?.exp) return true;
+  const now = Math.floor(Date.now() / 1e3);
+  return payload.exp < now + bufferSeconds;
+}
+export {
+  BioAdmin,
+  BioAuth,
+  BioError,
+  decodeToken,
+  generatePKCE,
+  isTokenExpired,
+  verifyToken
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@insureco/bio",
+  "version": "0.1.0",
+  "description": "SDK for Bio-ID SSO integration on the Tawa platform",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "insureco",
+    "tawa",
+    "bio-id",
+    "oauth",
+    "oidc",
+    "sso",
+    "authentication"
+  ],
+  "author": "InsurEco",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}