@cemiar/auth-sdk 1.0.0

package/README.md

@@ -0,0 +1,122 @@
+# @cemiar/auth-sdk
+
+Reusable helpers for integrating Cemiar Auth in web front-ends and Node.js APIs.
+
+This package bundles:
+
+- A browser-friendly Cemiar Auth client with email codes, Microsoft login support, token storage, refresh and logout helpers
+- Axios utilities to attach automatic Authorization headers and refresh tokens on 401 responses
+- A Hapi JWT strategy helper that fetches Cemiar Auth signing keys from JWKS and validates incoming requests
+
+## Installation
+
+```bash
+npm install @cemiar/auth-sdk
+```
+
+When working inside this monorepo, you can add it via a file reference:
+
+```bash
+npm install @cemiar/auth-sdk@file:../packages/cemiar-auth-sdk
+```
+
+Make sure the host project also has the required peer dependencies installed (`@hapi/hapi`, `hapi-auth-jwt2`).
+
+## Usage
+
+### Front-end (Vue/React/etc.)
+
+```ts
+import { createCemiarAuthClient } from "@cemiar/auth-sdk";
+
+const authClient = createCemiarAuthClient({
+    baseUrl: import.meta.env.VITE_CEMIAR_AUTH_URL!,
+    tenantId: import.meta.env.VITE_CEMIAR_TENANT_ID!,
+    auds: (import.meta.env.VITE_CEMIAR_AUDS || "").split(","),
+    redirectUrl: `${window.location.origin}/auth/microsoft/callback`,
+    logoutRedirectUrl: `${window.location.origin}/login`
+});
+
+// Trigger Microsoft login
+window.location.href = authClient.getMicrosoftLoginUrl();
+
+// Email code flow
+await authClient.sendEmailCode("user@example.com");
+const { accessToken } = await authClient.verifyEmailCode("user@example.com", "123456");
+
+// Axios client with automatic Authorization header and refresh-on-401
+const api = authClient.createApiClient({ baseURL: import.meta.env.VITE_API_BASE });
+const jobs = await api.get("/api/jobs");
+
+// Manual interceptor attachment if you already have an axios instance
+authClient.attachInterceptors(existingAxiosInstance);
+```
+
+#### Token storage hooks
+
+By default the client stores tokens in `localStorage`. Override storage to customize behaviour:
+
+```ts
+import { createCemiarAuthClient, TokenStorage } from "@cemiar/auth-sdk";
+
+const storage: TokenStorage = {
+    getToken: () => cookies.get("cemiar-access"),
+    setToken: token => {
+        token ? cookies.set("cemiar-access", token) : cookies.remove("cemiar-access");
+    }
+};
+
+const authClient = createCemiarAuthClient({
+    baseUrl: import.meta.env.VITE_CEMIAR_AUTH_URL!,
+    tenantId: import.meta.env.VITE_CEMIAR_TENANT_ID!,
+    auds: ["cemiar-jobs"],
+    storage
+});
+```
+
+### Backend (Hapi)
+
+```ts
+import { registerCemiarAuthHapi } from "@cemiar/auth-sdk";
+
+await registerCemiarAuthHapi(server, {
+    authUrl: process.env.CEMIAR_AUTH_URL!,
+    strategyName: "jwt",
+    validate: async decoded => ({
+        isValid: true,
+        credentials: decoded.payload
+    })
+});
+```
+
+The helper automatically fetches signing keys from Cemiar Auth JWKS endpoint and keeps them cached.
+
+To customise the cache and algorithms:
+
+```ts
+await registerCemiarAuthHapi(server, {
+    authUrl: process.env.CEMIAR_AUTH_URL!,
+    algorithms: ["RS256"],
+    cacheMaxAgeMs: 12 * 60 * 60 * 1000
+});
+```
+
+### Environment Variables
+
+| Variable                   | Description                                                        |
+| -------------------------- | ------------------------------------------------------------------ |
+| `VITE_CEMIAR_AUTH_URL`     | Base Cemiar Auth URL (e.g. `https://cemiar-auth.example.com/auth`) |
+| `VITE_CEMIAR_TENANT_ID`    | Tenant identifier provided by Cemiar Auth                          |
+| `VITE_CEMIAR_AUDS`         | Comma separated list of audiences                                  |
+| `VITE_CEMIAR_REDIRECT_URL` | Optional override for Microsoft redirect                           |
+| `CEMIAR_AUTH_URL`          | Backend URL for Cemiar Auth (no Vite prefix)                       |
+
+### Building
+
+```bash
+cd packages/cemiar-auth-sdk
+npm install
+npm run build
+```
+
+Output will be generated under `dist/`.

package/dist/browser/CemiarAuthClient.d.ts

@@ -0,0 +1,30 @@
+import { AxiosInstance } from "axios";
+import type { AuthTokens, CemiarAuthClientConfig, CemiarAuthClientInstance, CreateApiClientOptions, EmailCodeResponse, LogoutOptions, VerifyEmailResult } from "../shared/Types.js";
+export declare class CemiarAuthClient implements CemiarAuthClientInstance {
+    private readonly baseUrl;
+    private readonly tenantId;
+    private readonly auds;
+    private readonly redirectUrl?;
+    private storage;
+    private readonly onTokenChange?;
+    private readonly onAuthFailure?;
+    private readonly logoutRedirectUrl?;
+    private refreshPromise;
+    constructor(config: CemiarAuthClientConfig);
+    getAccessToken(): string | null;
+    setAccessToken(token: string | null): void;
+    private authPost;
+    sendEmailCode(email: string): Promise<EmailCodeResponse>;
+    verifyEmailCode(email: string, code: string): Promise<VerifyEmailResult>;
+    getMicrosoftLoginUrl(extraParams?: Record<string, string>): string;
+    exchangeMicrosoftCode(code: string): Promise<AuthTokens>;
+    refreshToken(): Promise<AuthTokens>;
+    logout(options?: LogoutOptions): Promise<void>;
+    createApiClient(options: CreateApiClientOptions): AxiosInstance;
+    attachInterceptors(instance: AxiosInstance): AxiosInstance;
+    private addAuthHeader;
+    private handleResponseError;
+    private queueTokenRefresh;
+    private handleAuthFailure;
+}
+export declare function createCemiarAuthClient(config: CemiarAuthClientConfig): CemiarAuthClientInstance;

package/dist/browser/CemiarAuthClient.js

@@ -0,0 +1,171 @@
+import axios from "axios";
+import { createDefaultTokenStorage } from "./Storage.js";
+import { normalizeBaseUrl, isBrowser } from "../shared/Utils.js";
+function parseAuds(auds) {
+    return auds.map(a => a.trim()).filter(Boolean);
+}
+function extractAccessToken(data) {
+    var _a;
+    const token = (_a = data.accessToken) !== null && _a !== void 0 ? _a : data.token;
+    if (typeof token === "string" && token.length > 0) {
+        return token;
+    }
+    throw new Error("Cemiar Auth response missing access token");
+}
+export class CemiarAuthClient {
+    constructor(config) {
+        var _a, _b, _c;
+        this.storage = createDefaultTokenStorage();
+        this.refreshPromise = null;
+        this.baseUrl = normalizeBaseUrl(config.baseUrl || "http://localhost:3000/auth");
+        this.tenantId = config.tenantId;
+        this.auds = parseAuds(config.auds);
+        this.redirectUrl =
+            (_a = config.redirectUrl) !== null && _a !== void 0 ? _a : (isBrowser ? `${window.location.origin}/auth/microsoft/callback` : undefined);
+        this.onTokenChange = config.onTokenChange;
+        this.onAuthFailure = config.onAuthFailure;
+        this.logoutRedirectUrl =
+            (_b = config.logoutRedirectUrl) !== null && _b !== void 0 ? _b : (isBrowser ? `${window.location.origin}/login` : undefined);
+        this.storage = (_c = config.storage) !== null && _c !== void 0 ? _c : createDefaultTokenStorage();
+    }
+    getAccessToken() {
+        return this.storage.getToken();
+    }
+    setAccessToken(token) {
+        var _a;
+        this.storage.setToken(token);
+        (_a = this.onTokenChange) === null || _a === void 0 ? void 0 : _a.call(this, token);
+    }
+    async authPost(path, body, withCredentials = true) {
+        const url = `${this.baseUrl}${path}`;
+        const response = await axios.post(url, body, {
+            withCredentials
+        });
+        return response.data;
+    }
+    async sendEmailCode(email) {
+        return this.authPost("/emailCodes/generate", { email });
+    }
+    async verifyEmailCode(email, code) {
+        const payload = {
+            email,
+            code,
+            tenantId: this.tenantId,
+            auds: this.auds
+        };
+        const data = await this.authPost("/emailCodes/validate", payload);
+        const accessToken = extractAccessToken(data);
+        this.setAccessToken(accessToken);
+        return {
+            accessToken,
+            authenticated: Boolean(data.authenticated),
+            blacklisted: Boolean(data.blacklisted),
+            raw: data
+        };
+    }
+    getMicrosoftLoginUrl(extraParams = {}) {
+        const params = new URLSearchParams({
+            tenantId: this.tenantId,
+            auds: this.auds.join(","),
+            ...(this.redirectUrl ? { redirectUrl: this.redirectUrl } : {})
+        });
+        for (const [key, value] of Object.entries(extraParams)) {
+            params.set(key, value);
+        }
+        return `${this.baseUrl}/microsoft?${params.toString()}`;
+    }
+    async exchangeMicrosoftCode(code) {
+        const payload = {
+            code,
+            ...(this.redirectUrl ? { redirectUrl: this.redirectUrl } : {})
+        };
+        const data = await this.authPost("/microsoft/callback", payload);
+        const accessToken = extractAccessToken(data);
+        this.setAccessToken(accessToken);
+        return { accessToken };
+    }
+    async refreshToken() {
+        const data = await this.authPost("/refresh", {}, true);
+        const accessToken = extractAccessToken(data);
+        this.setAccessToken(accessToken);
+        return { accessToken };
+    }
+    async logout(options = {}) {
+        if (options.clearToken !== false) {
+            this.setAccessToken(null);
+        }
+        const redirectUrl = options.redirectUrl || this.logoutRedirectUrl;
+        const logoutUrl = redirectUrl
+            ? `${this.baseUrl}/microsoft/logout?redirectUrl=${encodeURIComponent(redirectUrl)}`
+            : `${this.baseUrl}/logout`;
+        try {
+            if (options.performRedirect === false || !isBrowser) {
+                await axios.post(`${this.baseUrl}/logout`, {}, { withCredentials: true });
+                return;
+            }
+            window.location.href = logoutUrl;
+        }
+        catch {
+            // ignore network errors during logout
+        }
+    }
+    createApiClient(options) {
+        var _a;
+        const instance = axios.create({
+            baseURL: options.baseURL,
+            withCredentials: true,
+            ...((_a = options.axiosConfig) !== null && _a !== void 0 ? _a : {})
+        });
+        return this.attachInterceptors(instance);
+    }
+    attachInterceptors(instance) {
+        instance.interceptors.request.use(config => this.addAuthHeader(config));
+        instance.interceptors.response.use(response => response, error => this.handleResponseError(error, instance));
+        return instance;
+    }
+    addAuthHeader(config) {
+        const token = this.getAccessToken();
+        if (token && config.headers) {
+            config.headers.Authorization = `Bearer ${token}`;
+        }
+        return config;
+    }
+    async handleResponseError(error, instance) {
+        var _a;
+        const status = (_a = error.response) === null || _a === void 0 ? void 0 : _a.status;
+        const originalRequest = error.config;
+        if (status !== 401 || !originalRequest || originalRequest._retry) {
+            return Promise.reject(error);
+        }
+        originalRequest._retry = true;
+        try {
+            const newToken = await this.queueTokenRefresh();
+            if (originalRequest.headers) {
+                originalRequest.headers.Authorization = `Bearer ${newToken}`;
+            }
+            return instance(originalRequest);
+        }
+        catch (refreshError) {
+            this.handleAuthFailure();
+            return Promise.reject(refreshError);
+        }
+    }
+    async queueTokenRefresh() {
+        if (!this.refreshPromise) {
+            this.refreshPromise = this.refreshToken()
+                .then(tokens => tokens.accessToken)
+                .finally(() => {
+                this.refreshPromise = null;
+            });
+        }
+        return this.refreshPromise;
+    }
+    handleAuthFailure() {
+        var _a;
+        this.setAccessToken(null);
+        (_a = this.onAuthFailure) === null || _a === void 0 ? void 0 : _a.call(this);
+    }
+}
+export function createCemiarAuthClient(config) {
+    return new CemiarAuthClient(config);
+}

package/dist/browser/Storage.d.ts

@@ -0,0 +1,4 @@
+import type { TokenStorage } from "../shared/Types.js";
+export declare function createMemoryStorage(initialValue?: string | null): TokenStorage;
+export declare function createLocalStorageWrapper(key?: string): TokenStorage;
+export declare function createDefaultTokenStorage(): TokenStorage;

package/dist/browser/Storage.js

@@ -0,0 +1,42 @@
+import { isBrowser } from "../shared/Utils.js";
+export function createMemoryStorage(initialValue = null) {
+    let token = initialValue;
+    return {
+        getToken: () => token,
+        setToken: value => {
+            token = value;
+        }
+    };
+}
+export function createLocalStorageWrapper(key = "accessToken") {
+    if (!isBrowser || !("localStorage" in globalThis)) {
+        return createMemoryStorage(null);
+    }
+    return {
+        getToken: () => {
+            try {
+                return window.localStorage.getItem(key);
+            }
+            catch (error) {
+                console.warn("Failed to read token from localStorage", error);
+                return null;
+            }
+        },
+        setToken: value => {
+            try {
+                if (value) {
+                    window.localStorage.setItem(key, value);
+                }
+                else {
+                    window.localStorage.removeItem(key);
+                }
+            }
+            catch (error) {
+                console.warn("Failed to write token to localStorage", error);
+            }
+        }
+    };
+}
+export function createDefaultTokenStorage() {
+    return createLocalStorageWrapper();
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { CemiarAuthClient, createCemiarAuthClient } from "./browser/CemiarAuthClient.js";
+export * from "./shared/Types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { CemiarAuthClient, createCemiarAuthClient } from "./browser/CemiarAuthClient.js";
+export * from "./shared/Types.js";

package/dist/server/ServerHandler.d.ts

@@ -0,0 +1,8 @@
+import type { HapiJwtStrategyOptions, JwtParts } from "../shared/Types.js";
+import type { Server } from "@hapi/hapi";
+declare function createSigningKeyResolver(jwksUri: string, cacheMaxAgeMs: number): {
+    getKey: (decoded: JwtParts) => Promise<string>;
+};
+export declare function registerCemiarAuthHapi(server: Server, options: HapiJwtStrategyOptions): Promise<void>;
+export { createSigningKeyResolver };
+export type { JwtValidateFn, JwtValidateResult, JwtParts } from "../shared/Types.js";

package/dist/server/ServerHandler.js

@@ -0,0 +1,59 @@
+import jwksClient from "jwks-rsa";
+import { normalizeBaseUrl } from "../shared/Utils.js";
+const DEFAULT_ALGORITHMS = ["RS256"];
+const DEFAULT_CACHE_MAX_AGE = 24 * 60 * 60 * 1000; // 24 hours
+const defaultValidate = async (decoded) => ({
+    isValid: true,
+    credentials: decoded.payload
+});
+function createSigningKeyResolver(jwksUri, cacheMaxAgeMs) {
+    const client = jwksClient({
+        jwksUri,
+        cache: true,
+        cacheMaxEntries: 5,
+        cacheMaxAge: cacheMaxAgeMs
+    });
+    const getKey = async (decoded) => {
+        var _a;
+        const kid = (_a = decoded.header) === null || _a === void 0 ? void 0 : _a.kid;
+        if (!kid) {
+            throw new Error("JWT header is missing 'kid' claim");
+        }
+        return new Promise((resolve, reject) => {
+            client.getSigningKey(kid, (error, key) => {
+                if (error) {
+                    return reject(error);
+                }
+                if (!key) {
+                    return reject(new Error(`Unable to resolve signing key for kid ${kid}`));
+                }
+                resolve(key.getPublicKey());
+            });
+        });
+    };
+    return { getKey };
+}
+export async function registerCemiarAuthHapi(server, options) {
+    var _a;
+    const { authUrl, strategyName = "cemiar-jwt", algorithms = DEFAULT_ALGORITHMS, cacheMaxAgeMs = DEFAULT_CACHE_MAX_AGE, validate = defaultValidate } = options;
+    const jwksUri = `${normalizeBaseUrl(authUrl)}/.well-known/jwks.json`;
+    const { getKey } = createSigningKeyResolver(jwksUri, cacheMaxAgeMs);
+    const pluginModule = await import("hapi-auth-jwt2");
+    const plugin = ((_a = pluginModule.default) !== null && _a !== void 0 ? _a : pluginModule);
+    await server.register(plugin);
+    server.auth.strategy(strategyName, "jwt", {
+        key: async (decoded) => {
+            const key = await getKey(decoded);
+            return { key };
+        },
+        validate: async (decoded, request, h) => {
+            return validate(decoded, request, h);
+        },
+        verifyOptions: {
+            algorithms
+        },
+        complete: true
+    });
+    server.auth.default(strategyName);
+}
+export { createSigningKeyResolver };

package/dist/server/index.d.ts

@@ -0,0 +1,2 @@
+export { registerCemiarAuthHapi, createSigningKeyResolver } from "./ServerHandler.js";
+export type { JwtValidateFn, JwtValidateResult, JwtParts, HapiJwtStrategyOptions } from "../shared/Types.js";

package/dist/server/index.js

@@ -0,0 +1 @@
+export { registerCemiarAuthHapi, createSigningKeyResolver } from "./ServerHandler.js";

package/dist/shared/Types.d.ts

@@ -0,0 +1,81 @@
+import type { AxiosInstance, AxiosRequestConfig } from "axios";
+import type { Request, ResponseToolkit } from "@hapi/hapi";
+export interface TokenStorage {
+    getToken(): string | null;
+    setToken(token: string | null): void;
+}
+export interface CemiarAuthClientConfig {
+    baseUrl: string;
+    tenantId: string;
+    auds: string[];
+    redirectUrl?: string;
+    storage?: TokenStorage;
+    onTokenChange?: (token: string | null) => void;
+    onAuthFailure?: () => void;
+    logoutRedirectUrl?: string;
+}
+export interface AuthTokens {
+    accessToken: string;
+}
+export interface EmailCodeResponse {
+    success: boolean;
+    [key: string]: unknown;
+}
+export interface EmailVerifyResponse {
+    token: string;
+    authenticated: boolean;
+    blacklisted: boolean;
+    [key: string]: unknown;
+}
+export interface VerifyEmailResult extends AuthTokens {
+    authenticated: boolean;
+    blacklisted: boolean;
+    raw: EmailVerifyResponse;
+}
+export interface RefreshResponse {
+    accessToken?: string;
+    token?: string;
+    [key: string]: unknown;
+}
+export interface CreateApiClientOptions {
+    baseURL: string;
+    axiosConfig?: AxiosRequestConfig;
+}
+export interface LogoutOptions {
+    redirectUrl?: string;
+    performRedirect?: boolean;
+    clearToken?: boolean;
+}
+export interface JwtHeader {
+    kid: string;
+    alg: string;
+}
+export interface JwtParts {
+    header: JwtHeader;
+    payload: unknown;
+    signature?: string;
+}
+export interface JwtValidateResult {
+    isValid: boolean;
+    credentials?: unknown;
+}
+export type JwtValidateFn = (decoded: JwtParts, request: Request, h: ResponseToolkit) => Promise<JwtValidateResult> | JwtValidateResult;
+export interface HapiJwtStrategyOptions {
+    authUrl: string;
+    strategyName?: string;
+    algorithms?: string[];
+    cacheMaxAgeMs?: number;
+    validate?: JwtValidateFn;
+}
+export interface CemiarAuthClientInstance {
+    getAccessToken(): string | null;
+    setAccessToken(token: string | null): void;
+    getMicrosoftLoginUrl(params?: Record<string, string>): string;
+    sendEmailCode(email: string): Promise<EmailCodeResponse>;
+    verifyEmailCode(email: string, code: string): Promise<VerifyEmailResult>;
+    exchangeMicrosoftCode(code: string): Promise<AuthTokens>;
+    refreshToken(): Promise<AuthTokens>;
+    logout(options?: LogoutOptions): Promise<void>;
+    createApiClient(options: CreateApiClientOptions): AxiosInstance;
+    attachInterceptors(instance: AxiosInstance): AxiosInstance;
+}

package/dist/shared/Types.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/Utils.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeBaseUrl(url: string): string;
+export declare const isBrowser: boolean;

package/dist/shared/Utils.js

@@ -0,0 +1,7 @@
+export function normalizeBaseUrl(url) {
+    if (!url) {
+        return "";
+    }
+    return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+export const isBrowser = typeof window !== "undefined" && typeof window.document !== "undefined";

package/package.json

@@ -0,0 +1,53 @@
+{
+    "name": "@cemiar/auth-sdk",
+    "version": "1.0.0",
+    "description": "Cemiar Auth integration helpers for web apps and APIs.",
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        },
+        "./server": {
+            "import": "./dist/server/index.js",
+            "types": "./dist/server/index.d.ts"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.json",
+        "clean": "rimraf dist"
+    },
+    "keywords": [
+        "cemiar",
+        "auth",
+        "jwt",
+        "hapi",
+        "axios"
+    ],
+    "author": "Cemiar",
+    "license": "MIT",
+    "dependencies": {
+        "axios": "^1.7.0",
+        "jwks-rsa": "^3.1.0"
+    },
+    "peerDependencies": {
+        "@hapi/hapi": "^21.3.0",
+        "hapi-auth-jwt2": "^10.5.0"
+    },
+    "devDependencies": {
+        "@hapi/hapi": "^21.3.0",
+        "@types/node": "^20.11.30",
+        "hapi-auth-jwt2": "^10.5.0",
+        "rimraf": "^5.0.5",
+        "typescript": "^5.3.3"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}