@ouim/logto-authkit 0.3.0

package/dist/utils.d.ts

@@ -0,0 +1,169 @@
+import { type ClassValue } from 'clsx';
+import type { LogtoUser, NavigationOptions } from './types.js';
+import type { LogtoConfig } from '@logto/react';
+/**
+ * Validates Logto configuration for required fields
+ * @param config - The LogtoConfig object to validate
+ * @throws {Error} If required configuration is missing or invalid
+ * @example
+ * try {
+ *   validateLogtoConfig(config);
+ * } catch (error) {
+ *   console.error('Invalid Logto config:', error.message);
+ * }
+ */
+export declare const validateLogtoConfig: (config: LogtoConfig, options?: {
+    warnOnMissingResources?: boolean;
+}) => void;
+/**
+ * Transform Logto User Object
+ *
+ * Converts a Logto JWT claims object into a simplified LogtoUser format.
+ * Maps JWT standard claims (sub, name, email, picture) to user object properties,
+ * and preserves all additional claims from the original object.
+ *
+ * @param {any} logtoUser - Raw Logto user claims object from JWT token
+ * @returns {LogtoUser | null} Simplified user object or null if input is falsy
+ *
+ * @example
+ * const claims = { sub: 'user_123', name: 'John Doe', email: 'john@example.com', picture: 'http://...' };
+ * const user = transformUser(claims);
+ * // { id: 'user_123', name: 'John Doe', email: 'john@example.com', avatar: 'http://...' }
+ *
+ * @internal
+ */
+export declare const transformUser: (logtoUser: any) => LogtoUser | null;
+/**
+ * Navigate to a URL
+ *
+ * Browser fallback navigation function. AuthProvider-scoped custom navigation is handled
+ * via React context in `navigation.tsx`; this utility only performs History API /
+ * window.location navigation when no scoped router override is present.
+ *
+ * Supports:
+ * - Client-side History API for SPAs (pushState/replaceState)
+ * - Direct window.location for absolute URLs and fallback
+ *
+ * @param {string} url - URL to navigate to (relative path like '/dashboard' or absolute URL)
+ * @param {NavigationOptions} [options={}] - Navigation behavior options
+ * @param {boolean} [options.replace=false] - Use replaceState instead of pushState (replaces history entry)
+ * @param {boolean} [options.force=false] - Force navigation even if already on the same page
+ *
+ * @example
+ * // Navigate to a relative path
+ * navigateTo('/dashboard');
+ *
+ * @example
+ * // Replace history entry instead of adding new one
+ * navigateTo('/login', { replace: true });
+ *
+ * @example
+ * // Force navigation even if already on the page
+ * navigateTo('/dashboard', { force: true });
+ */
+export declare const navigateTo: (url: string, options?: NavigationOptions) => void;
+/**
+ * Get initials from name for avatar fallback
+ */
+export declare const getInitials: (name?: string) => string;
+/**
+ * Cookie management utilities
+ */
+export declare const cookieUtils: {
+    /**
+     * Set a cookie with the given name, value, and options
+     */
+    setCookie: (name: string, value: string, options?: {
+        expires?: Date | number;
+        maxAge?: number;
+        domain?: string;
+        path?: string;
+        secure?: boolean;
+        sameSite?: "strict" | "lax" | "none";
+        httpOnly?: boolean;
+    }) => void;
+    /**
+     * Get a cookie value by name
+     */
+    getCookie: (name: string) => string | null;
+    /**
+     * Remove a cookie by name
+     */
+    removeCookie: (name: string, options?: {
+        domain?: string;
+        path?: string;
+    }) => void;
+};
+/**
+ * Specialized functions for JWT token management
+ */
+export declare const jwtCookieUtils: {
+    /**
+     * Save JWT token to cookie.
+     *
+     * ⚠️  SECURITY NOTICE — XSS / non-httpOnly cookie
+     * ─────────────────────────────────────────────────────────────────────────
+     * This cookie is set from JavaScript, which means it cannot carry the
+     * `HttpOnly` flag. Any JavaScript that runs on the same origin — including
+     * injected scripts from an XSS vulnerability — can read the raw JWT value
+     * from `document.cookie` and exfiltrate it.
+     *
+     * The cookie is still protected by `Secure` (HTTPS-only) and
+     * `SameSite=Strict` (blocks cross-site request forgery), but those flags do
+     * NOT prevent access by same-origin JavaScript.
+     *
+     * MITIGATIONS:
+     *   1. Keep a strict Content-Security-Policy to reduce XSS attack surface.
+     *   2. If your deployment includes a Node.js backend that handles the
+     *      callback redirect, use `buildAuthCookieHeader()` from
+     *      `@ouim/logto-authkit/server` to set an `HttpOnly` version of the
+     *      same cookie from the server side. The browser will then send it
+     *      automatically and it will be invisible to JavaScript.
+     *
+     * See: https://owasp.org/www-community/HttpOnly
+     * ─────────────────────────────────────────────────────────────────────────
+     */
+    saveToken: (token: string) => void;
+    /**
+     * Get JWT token from cookie
+     */
+    getToken: () => string | null;
+    /**
+     * Remove JWT token from cookie
+     */
+    removeToken: () => void;
+};
+/**
+ * Client-side guest utilities
+ */
+export declare const guestUtils: {
+    /**
+     * Generate a fingerprint-based guest ID
+     */
+    generateGuestId(): Promise<string>;
+    /**
+     * Get guest ID from cookie
+     */
+    getGuestId(): string | null;
+    /**
+     * Set guest ID cookie
+     *
+     * Uses cookieUtils.setCookie so that the same security flags applied to the
+     * auth token cookie (Secure, SameSite=strict) are also applied here, making
+     * both cookies consistent. The Secure flag is enforced regardless of the
+     * current protocol so that the guest ID is never sent over plain HTTP.
+     */
+    setGuestId(guestId?: string): Promise<string>;
+    /**
+     * Ensure guest ID exists, create if not
+     */
+    ensureGuestId(): Promise<string>;
+    /**
+     * Clear guest ID cookie
+     */
+    clearGuestId(): void;
+};
+/**
+ * Utility function to combine class names (for components)
+ */
+export declare function cn(...inputs: ClassValue[]): string;

package/package.json

@@ -0,0 +1,111 @@
+{
+  "name": "@ouim/logto-authkit",
+  "version": "0.3.0",
+  "description": "A Logto auth kit with prebuilt React UI, hooks, server verification, and bundler helpers",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": "^18.18.0 || ^20.0.0 || ^22.0.0 || ^24.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js",
+      "require": "./dist/server/index.cjs"
+    },
+    "./bundler-config": {
+      "types": "./dist/bundler-config.d.ts",
+      "import": "./dist/bundler-config.js",
+      "require": "./dist/bundler-config.cjs"
+    }
+  },
+  "browser": {
+    "./dist/index.js": "./dist/index.js"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build && tsc --project tsconfig.build.json --emitDeclarationOnly",
+    "build:tsc": "tsc",
+    "dev": "tsc --watch",
+    "dev:example": "npm --prefix example_app run dev",
+    "test": "vitest",
+    "test:package": "node ./scripts/run-package-audit.mjs",
+    "test:size": "node ./scripts/check-bundle-size.mjs",
+    "test:smoke": "node ./scripts/run-packed-smoke-tests.mjs",
+    "test:coverage": "vitest --coverage",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "clean": "rimraf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "publish": "npm publish --access public --provenance"
+  },
+  "peerDependencies": {
+    "@logto/react": "^3.0.0 || ^4.0.0",
+    "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
+    "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@fingerprintjs/fingerprintjs": "^4.6.2",
+    "@radix-ui/react-avatar": "^1.0.4",
+    "@radix-ui/react-dialog": "^1.1.14",
+    "@radix-ui/react-dropdown-menu": "^2.0.6",
+    "@radix-ui/react-tooltip": "^1.2.7",
+    "class-variance-authority": "^0.7.0",
+    "clsx": "^2.1.0",
+    "cookie-parser": "^1.4.7",
+    "jose": "^6.0.11",
+    "lucide-react": "^0.575.0",
+    "tailwind-merge": "^2.2.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^8.56.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/cookie-parser": "^1.4.10",
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.19.15",
+    "@types/react": "^18.0.37",
+    "@types/react-dom": "^18.0.11",
+    "@types/supertest": "^7.2.0",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.21.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/ui": "^4.0.18",
+    "eslint": "^8.56.0",
+    "eslint-plugin-react": "^7.34.0",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "express": "^5.2.1",
+    "happy-dom": "^20.7.0",
+    "rimraf": "^5.0.10",
+    "supertest": "^7.2.2",
+    "typescript": "^5.0.4",
+    "vite": "^6.4.1",
+    "vitest": "^4.0.18"
+  },
+  "keywords": [
+    "logto",
+    "auth",
+    "authentication",
+    "react"
+  ],
+  "author": "thezem",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ouim-me/simple-logto.git"
+  }
+}