@insureco/bio 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,385 @@
+/** Configuration for BioAuth (OAuth flow client) */
+interface BioAuthConfig {
+    /** OAuth client ID (env: BIO_CLIENT_ID) */
+    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) */
+    issuer?: string;
+    /** Number of retry attempts on transient failures (default: 2) */
+    retries?: number;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeoutMs?: number;
+}
+/** Configuration for BioAdmin (admin API client) */
+interface BioAdminConfig {
+    /** Bio-ID base URL (env: BIO_ID_URL, default: https://bio.tawa.insureco.io) */
+    baseUrl?: string;
+    /** Internal API key for service-to-service auth (env: INTERNAL_API_KEY) */
+    internalKey?: string;
+    /** Async function returning a Bearer token (alternative to internalKey) */
+    accessTokenFn?: () => Promise<string>;
+    /** Number of retry attempts on transient failures (default: 2) */
+    retries?: number;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeoutMs?: number;
+}
+/** Options for building an authorization URL */
+interface AuthorizeOptions {
+    /** Callback URL where Bio-ID redirects after authorization */
+    redirectUri: string;
+    /** OAuth scopes to request (default: ['openid', 'profile', 'email']) */
+    scopes?: string[];
+    /** CSRF state parameter (auto-generated if not provided) */
+    state?: string;
+}
+/** Result from getAuthorizationUrl() */
+interface AuthorizeResult {
+    /** Full authorization URL to redirect the user to */
+    url: string;
+    /** State parameter (for CSRF validation on callback) */
+    state: string;
+    /** PKCE code verifier (store securely, send during token exchange) */
+    codeVerifier: string;
+    /** PKCE code challenge (included in the URL) */
+    codeChallenge: string;
+}
+/** Response from the /api/oauth/token endpoint */
+interface TokenResponse {
+    access_token: string;
+    token_type: 'Bearer';
+    expires_in: number;
+    refresh_token?: string;
+    scope: string;
+    id_token?: string;
+}
+/** Response from the /api/auth/introspect endpoint */
+interface IntrospectResult {
+    active: boolean;
+    user?: {
+        id: string;
+        email: string;
+        name: string;
+        org: string;
+        roles: string[];
+    };
+    tokenType?: 'client_credentials';
+    clientId?: string;
+    scopes?: string[];
+    orgId?: string;
+    orgSlug?: string;
+    organizationName?: string;
+}
+/** Decoded access token payload (user auth) */
+interface BioTokenPayload {
+    iss: string;
+    sub: string;
+    aud: string;
+    exp: number;
+    iat: number;
+    bioId: string;
+    email: string;
+    name: string;
+    userType: string;
+    roles: string[];
+    permissions: string[];
+    orgId?: string;
+    orgSlug?: string;
+    client_id: string;
+    scope: string;
+    enabled_modules?: string[];
+    onboarding?: {
+        platform: boolean;
+        modules: Record<string, {
+            completed: string[];
+            due: string[];
+        }>;
+    };
+}
+/** Decoded client credentials token payload (service-to-service) */
+interface BioClientTokenPayload {
+    iss: string;
+    exp: number;
+    iat: number;
+    client_id: string;
+    scope: string;
+    token_type: 'client_credentials';
+    orgId?: string;
+    orgSlug?: string;
+}
+/** Options for local JWT verification */
+interface VerifyOptions {
+    /** Expected issuer (default: config issuer) */
+    issuer?: string;
+    /** Expected audience (client_id) */
+    audience?: string;
+}
+/** User profile from /api/oauth/userinfo or admin API */
+interface BioUser {
+    sub: string;
+    bioId: string;
+    email: string;
+    emailVerified: boolean;
+    name: string;
+    firstName?: string;
+    lastName?: string;
+    userType: string;
+    roles: string[];
+    permissions: string[];
+    status: string;
+    orgId?: string;
+    orgSlug?: string;
+    organizationId?: string;
+    organizationName?: string;
+    departmentId?: string;
+    departmentName?: string;
+    managerId?: string;
+    enabledModules?: string[];
+    jobTitle?: string;
+    phoneHome?: string;
+    phoneWork?: string;
+    phoneCell?: string;
+    phone?: string;
+    addressHome?: BioAddress;
+    addressWork?: BioAddress;
+    messaging?: BioMessaging;
+    preferences?: Record<string, unknown>;
+    lastLoginAt?: number;
+}
+interface BioAddress {
+    street?: string;
+    city?: string;
+    state?: string;
+    zip?: string;
+    country?: string;
+}
+interface BioMessaging {
+    slack?: string;
+    teams?: string;
+    skype?: string;
+    whatsapp?: string;
+}
+/** Filters for listing users */
+interface UserFilters {
+    search?: string;
+    status?: string;
+    userType?: string;
+    organizationId?: string;
+    page?: number;
+    limit?: number;
+}
+/** Data for updating a user */
+interface UpdateUserData {
+    firstName?: string;
+    lastName?: string;
+    displayName?: string;
+    roles?: string[];
+    status?: string;
+    userType?: string;
+    departmentId?: string;
+    jobTitle?: string;
+    permissions?: string[];
+    enabled_modules?: string[];
+}
+/** Department from admin API */
+interface BioDepartment {
+    id: string;
+    name: string;
+    description?: string;
+    organizationId: string;
+    headId?: string;
+    parentId?: string;
+    memberCount?: number;
+}
+/** Data for creating a department */
+interface CreateDepartmentData {
+    name: string;
+    description?: string;
+    headId?: string;
+    parentId?: string;
+}
+/** Role from admin API */
+interface BioRole {
+    id: string;
+    name: string;
+    description?: string;
+    permissions: string[];
+    isSystem?: boolean;
+}
+/** Data for creating a role */
+interface CreateRoleData {
+    name: string;
+    description?: string;
+    permissions: string[];
+}
+/** OAuth client from admin API */
+interface BioOAuthClient {
+    clientId: string;
+    name: string;
+    description?: string;
+    redirectUris: string[];
+    allowedScopes: string[];
+    allowedGrantTypes: string[];
+    isActive: boolean;
+    orgId?: string;
+    orgSlug?: string;
+    accessTokenTtl?: number;
+    refreshTokenTtl?: number;
+}
+/** Data for creating an OAuth client */
+interface CreateClientData {
+    name: string;
+    description?: string;
+    redirectUris: string[];
+    allowedScopes?: string[];
+    allowedGrantTypes?: string[];
+}
+/** Admin API response wrapper */
+interface AdminResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    meta?: {
+        total: number;
+        page: number;
+        limit: number;
+    };
+}
+
+/**
+ * OAuth flow client for Bio-ID SSO.
+ *
+ * Handles authorization URL generation, token exchange, refresh,
+ * userinfo fetching, revocation, and introspection.
+ */
+declare class BioAuth {
+    private readonly clientId;
+    private readonly clientSecret;
+    private readonly issuer;
+    private readonly retries;
+    private readonly timeoutMs;
+    constructor(config: BioAuthConfig);
+    /**
+     * Create a BioAuth from environment variables.
+     *
+     * Reads: BIO_CLIENT_ID, BIO_CLIENT_SECRET, BIO_ID_URL
+     */
+    static fromEnv(): BioAuth;
+    /**
+     * 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: AuthorizeOptions): AuthorizeResult;
+    /**
+     * Exchange an authorization code for tokens.
+     *
+     * Called in your OAuth callback handler after the user authorizes.
+     */
+    exchangeCode(code: string, codeVerifier: string, redirectUri: string): Promise<TokenResponse>;
+    /**
+     * Refresh an expired access token using a refresh token.
+     *
+     * Returns new access_token and a rotated refresh_token.
+     */
+    refreshToken(refreshToken: string): Promise<TokenResponse>;
+    /**
+     * Get a client credentials token for service-to-service auth.
+     *
+     * No user context — the token identifies your OAuth client only.
+     */
+    getClientCredentialsToken(scopes?: string[]): Promise<TokenResponse>;
+    /**
+     * Fetch the authenticated user's profile from the userinfo endpoint.
+     */
+    getUserInfo(accessToken: string): Promise<BioUser>;
+    /**
+     * Revoke a token (typically the refresh token on logout).
+     */
+    revokeToken(token: string, hint?: 'refresh_token' | 'access_token'): Promise<void>;
+    /**
+     * Introspect a token to check if it's active and get user/client context.
+     *
+     * Does not require JWT_SECRET — validates against Bio-ID server.
+     */
+    introspect(token: string): Promise<IntrospectResult>;
+    private tokenRequest;
+    private request;
+    private fetchWithRetry;
+}
+
+/**
+ * Admin API client for Bio-ID.
+ *
+ * Manages users, departments, roles, and OAuth clients.
+ * Authenticates via X-Internal-Key header or Bearer token.
+ */
+declare class BioAdmin {
+    private readonly baseUrl;
+    private readonly internalKey?;
+    private readonly accessTokenFn?;
+    private readonly retries;
+    private readonly timeoutMs;
+    constructor(config: BioAdminConfig);
+    /**
+     * Create a BioAdmin from environment variables.
+     *
+     * Reads: BIO_ID_URL, INTERNAL_API_KEY
+     */
+    static fromEnv(): BioAdmin;
+    /** List users with optional filters */
+    listUsers(filters?: UserFilters): Promise<BioUser[]>;
+    /** Get a single user by bioId */
+    getUser(bioId: string): Promise<BioUser>;
+    /** Update a user's profile, roles, or status */
+    updateUser(bioId: string, data: UpdateUserData): Promise<BioUser>;
+    /** List all departments */
+    listDepartments(): Promise<BioDepartment[]>;
+    /** Create a new department */
+    createDepartment(data: CreateDepartmentData): Promise<BioDepartment>;
+    /** List all roles */
+    listRoles(): Promise<BioRole[]>;
+    /** Create a new role */
+    createRole(data: CreateRoleData): Promise<BioRole>;
+    /** List all OAuth clients */
+    listClients(): Promise<BioOAuthClient[]>;
+    /** Create a new OAuth client */
+    createClient(data: CreateClientData): Promise<BioOAuthClient>;
+    private request;
+}
+
+/** Error thrown by Bio SDK operations */
+declare class BioError extends Error {
+    /** HTTP status code (if from an API response) */
+    readonly statusCode?: number;
+    /** Machine-readable error code (e.g. 'invalid_grant', 'token_expired') */
+    readonly code: string;
+    /** Additional error details from the API */
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code: string, statusCode?: number, details?: Record<string, unknown>);
+}
+
+/** Generate a PKCE code verifier and S256 code challenge */
+declare function generatePKCE(): {
+    codeVerifier: string;
+    codeChallenge: string;
+};
+
+/**
+ * Verify a Bio-ID JWT access token using HS256.
+ * Checks algorithm, signature (constant-time), expiration, issuer, and audience.
+ */
+declare function verifyToken(token: string, secret: string, options?: VerifyOptions): BioTokenPayload;
+/**
+ * Decode a JWT without verifying its signature.
+ * Useful for reading claims from tokens you trust (e.g. from your own cookie).
+ */
+declare function decodeToken(token: string): BioTokenPayload | null;
+/**
+ * Check if a JWT is expired (with optional buffer in seconds).
+ * Returns true if expired or unparseable.
+ */
+declare function isTokenExpired(token: string, bufferSeconds?: number): boolean;
+
+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 };