@ahmedbaset/adminjs-hono 0.1.0

package/.eslintrc.cjs

@@ -0,0 +1,20 @@
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+  ],
+  plugins: ['@typescript-eslint'],
+  env: {
+    node: true,
+    es2022: true,
+  },
+  parserOptions: {
+    ecmaVersion: 2022,
+    sourceType: 'module',
+  },
+  rules: {
+    '@typescript-eslint/no-explicit-any': 'warn',
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+  },
+}

package/README.md

@@ -0,0 +1,239 @@
+# @ahmedbaset/adminjs-hono
+
+AdminJS adapter for [Hono](https://hono.dev/) web framework. This adapter allows you to integrate AdminJS admin panels into Hono applications with support for all JavaScript runtimes (Node.js, Deno, Bun, Cloudflare Workers, etc.).
+
+## Installation
+
+```bash
+npm install @ahmedbaset/adminjs-hono adminjs hono
+```
+
+## Features
+
+- 🚀 Works with all Hono-supported runtimes (Node.js, Deno, Bun, Cloudflare Workers, etc.)
+- 🔒 Built-in session-based authentication
+- 📦 File upload support using Web Standards
+- 🎨 Same API design as the Express adapter for easy migration
+- 📝 Full TypeScript support
+- ⚡ Lightweight and fast
+
+## Usage
+
+### Basic Usage (No Authentication)
+
+```typescript
+import { Hono } from 'hono'
+import AdminJS from 'adminjs'
+import { buildRouter } from '@ahmedbaset/adminjs-hono'
+
+const admin = new AdminJS({
+  databases: [],
+  rootPath: '/admin',
+})
+
+const app = new Hono()
+const adminRouter = buildRouter(admin)
+
+app.route('/admin', adminRouter)
+
+export default app
+```
+
+### With Authentication
+
+```typescript
+import { Hono } from 'hono'
+import AdminJS from 'adminjs'
+import { buildAuthenticatedRouter } from '@ahmedbaset/adminjs-hono'
+
+const admin = new AdminJS({
+  databases: [],
+  rootPath: '/admin',
+})
+
+const app = new Hono()
+
+const adminRouter = buildAuthenticatedRouter(
+  admin,
+  {
+    authenticate: async (email, password) => {
+      // Verify credentials against your database
+      if (email === 'admin@example.com' && password === 'password') {
+        return { email, name: 'Admin' }
+      }
+      return null
+    },
+    cookiePassword: 'some-secret-password-at-least-32-characters-long',
+    cookieName: 'adminjs',
+  },
+  undefined, // predefined app (optional)
+  {
+    // Session options
+    maxAge: 86400, // 24 hours
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+  }
+)
+
+app.route('/admin', adminRouter)
+
+export default app
+```
+
+### Using an Existing Hono App
+
+You can pass an existing Hono app instance to add custom middleware:
+
+```typescript
+import { Hono } from 'hono'
+import { logger } from 'hono/logger'
+import AdminJS from 'adminjs'
+import { buildRouter } from '@ahmedbaset/adminjs-hono'
+
+const admin = new AdminJS({
+  databases: [],
+  rootPath: '/admin',
+})
+
+// Create a Hono app with custom middleware
+const adminApp = new Hono()
+adminApp.use('*', logger())
+
+// Pass it to buildRouter
+const adminRouter = buildRouter(admin, adminApp)
+
+const app = new Hono()
+app.route('/admin', adminRouter)
+
+export default app
+```
+
+## API
+
+### `buildRouter(admin, predefinedApp?, uploadOptions?)`
+
+Creates a Hono app with AdminJS routes (no authentication).
+
+**Parameters:**
+- `admin` (AdminJS): AdminJS instance
+- `predefinedApp` (Hono, optional): Existing Hono app to use
+- `uploadOptions` (UploadOptions, optional): File upload configuration
+
+**Returns:** Hono app with AdminJS routes
+
+### `buildAuthenticatedRouter(admin, auth, predefinedApp?, sessionOptions?, uploadOptions?)`
+
+Creates a Hono app with AdminJS routes protected by session authentication.
+
+**Parameters:**
+- `admin` (AdminJS): AdminJS instance
+- `auth` (AuthenticationOptions): Authentication configuration
+- `predefinedApp` (Hono, optional): Existing Hono app to use
+- `sessionOptions` (SessionOptions, optional): Session cookie configuration
+- `uploadOptions` (UploadOptions, optional): File upload configuration
+
+**Returns:** Hono app with authenticated AdminJS routes
+
+## Configuration Options
+
+### AuthenticationOptions
+
+```typescript
+{
+  cookiePassword: string          // Required: Secret for session cookies
+  cookieName?: string             // Optional: Cookie name (default: 'adminjs')
+  authenticate?: (email, password, context?) => Promise<CurrentAdmin | null>
+  maxRetries?: number | { count: number, duration: number }
+  provider?: BaseAuthProvider     // Alternative to authenticate function
+}
+```
+
+### SessionOptions
+
+```typescript
+{
+  maxAge?: number        // Session duration in seconds (default: 86400)
+  httpOnly?: boolean     // HttpOnly flag (default: true)
+  secure?: boolean       // Secure flag (default: false)
+  sameSite?: 'Strict' | 'Lax' | 'None'  // SameSite policy (default: 'Lax')
+  domain?: string        // Cookie domain
+  path?: string          // Cookie path (default: '/')
+}
+```
+
+### UploadOptions
+
+```typescript
+{
+  uploadDir?: string         // Upload directory path
+  maxFileSize?: number       // Maximum file size in bytes
+  maxFieldsSize?: number     // Maximum total fields size in bytes
+  maxFields?: number         // Maximum number of fields
+  keepExtensions?: boolean   // Keep file extensions
+}
+```
+
+## Authentication Providers
+
+You can use AdminJS authentication providers instead of the `authenticate` function:
+
+```typescript
+import { buildAuthenticatedRouter } from '@ahmedbaset/adminjs-hono'
+import { MyAuthProvider } from './my-auth-provider'
+
+const adminRouter = buildAuthenticatedRouter(
+  admin,
+  {
+    provider: new MyAuthProvider(),
+    cookiePassword: 'secret',
+  }
+)
+```
+
+## Differences from Express Adapter
+
+The Hono adapter maintains API compatibility with the Express adapter, but there are some differences:
+
+1. **Runtime Support**: Works on all JavaScript runtimes, not just Node.js
+2. **File Uploads**: Uses Web Standards FormData API instead of express-formidable
+3. **Session Storage**: Uses in-memory storage by default (suitable for single-instance deployments)
+4. **Middleware**: Uses Hono middleware instead of Express middleware
+
+## Debugging
+
+Set the `ADMINJS_HONO_DEBUG` environment variable to enable debug logging:
+
+```bash
+ADMINJS_HONO_DEBUG=true node server.js
+```
+
+## Examples
+
+See the [examples](./examples) directory for complete working examples:
+
+- [simple.ts](./examples/simple.ts) - Basic usage without authentication
+- [auth.ts](./examples/auth.ts) - Usage with authentication
+
+## Troubleshooting
+
+### Session not persisting
+
+Make sure you're using the same `cookieName` across requests and that cookies are enabled in your browser. In production, set `secure: true` in session options when using HTTPS.
+
+### File uploads not working
+
+Ensure the `uploadDir` exists and is writable. The adapter uses Web Standards FormData API, which may have different behavior across runtimes.
+
+### Assets not loading
+
+Check that the AdminJS `rootPath` matches the path where you mount the router. For example, if `rootPath: '/admin'`, mount with `app.route('/admin', adminRouter)`.
+
+## License
+
+MIT
+
+## Links
+
+- [AdminJS Documentation](https://docs.adminjs.co/)
+- [Hono Documentation](https://hono.dev/)
+- [GitHub Repository](https://github.com/SoftwareBrothers/adminjs-hono)

package/examples/auth.ts

@@ -0,0 +1,76 @@
+/**
+ * Example of AdminJS with Hono and authentication
+ * 
+ * This example shows how to integrate AdminJS into a Hono application
+ * with session-based authentication.
+ */
+
+import { Hono } from 'hono'
+import { serve } from '@hono/node-server'
+import AdminJS from 'adminjs'
+import { buildAuthenticatedRouter } from '../src/index.js'
+
+// Mock admin user for demonstration
+const ADMIN = {
+  email: 'admin@example.com',
+  password: 'password',
+  name: 'Admin User',
+}
+
+// Create AdminJS instance
+const admin = new AdminJS({
+  databases: [],
+  rootPath: '/admin',
+  resources: [],
+})
+
+// Build authenticated AdminJS router
+const adminRouter = buildAuthenticatedRouter(
+  admin,
+  {
+    // Authentication function
+    authenticate: async (email, password) => {
+      // In production, verify against database with hashed passwords
+      if (email === ADMIN.email && password === ADMIN.password) {
+        return {
+          email: ADMIN.email,
+          name: ADMIN.name,
+        }
+      }
+      return null
+    },
+    // Session cookie configuration
+    cookiePassword: 'some-secret-password-at-least-32-characters-long',
+    cookieName: 'adminjs',
+  },
+  undefined, // No predefined app
+  {
+    // Session options
+    maxAge: 86400, // 24 hours
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'Lax',
+  }
+)
+
+// Create main Hono app
+const app = new Hono()
+
+// Mount AdminJS router
+app.route('/admin', adminRouter)
+
+// Add a simple home route
+app.get('/', (c) => {
+  return c.text('AdminJS is running at /admin (login required)')
+})
+
+// Start server
+const port = 3000
+console.log(`Server is running on http://localhost:${port}`)
+console.log(`AdminJS is available at http://localhost:${port}/admin`)
+console.log(`Login with: ${ADMIN.email} / ${ADMIN.password}`)
+
+serve({
+  fetch: app.fetch,
+  port,
+})

package/examples/simple.ts

@@ -0,0 +1,42 @@
+/**
+ * Simple example of AdminJS with Hono (no authentication)
+ * 
+ * This example shows how to integrate AdminJS into a Hono application
+ * without authentication. Suitable for development environments.
+ */
+
+import { Hono } from 'hono'
+import { serve } from '@hono/node-server'
+import AdminJS from 'adminjs'
+import { buildRouter } from '../src/index.js'
+
+// Create AdminJS instance
+const admin = new AdminJS({
+  databases: [],
+  rootPath: '/admin',
+  resources: [],
+})
+
+// Build AdminJS router
+const adminRouter = buildRouter(admin)
+
+// Create main Hono app
+const app = new Hono()
+
+// Mount AdminJS router
+app.route('/admin', adminRouter)
+
+// Add a simple home route
+app.get('/', (c) => {
+  return c.text('AdminJS is running at /admin')
+})
+
+// Start server
+const port = 3000
+console.log(`Server is running on http://localhost:${port}`)
+console.log(`AdminJS is available at http://localhost:${port}/admin`)
+
+serve({
+  fetch: app.fetch,
+  port,
+})

package/lib/authentication/login.handler.d.ts

@@ -0,0 +1,11 @@
+import type AdminJS from 'adminjs';
+import type { Hono } from 'hono';
+import type { AuthenticationOptions } from '../types.js';
+/**
+ * Registers login routes with the Hono app
+ * @param app - Hono app instance
+ * @param admin - AdminJS instance
+ * @param auth - Authentication options
+ */
+export declare function withLogin(app: Hono, admin: AdminJS, auth: AuthenticationOptions): void;
+//# sourceMappingURL=login.handler.d.ts.map

package/lib/authentication/login.handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"login.handler.d.ts","sourceRoot":"","sources":["../../src/authentication/login.handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,SAAS,CAAA;AAClC,OAAO,KAAK,EAAE,IAAI,EAAW,MAAM,MAAM,CAAA;AACzC,OAAO,KAAK,EAGV,qBAAqB,EAEtB,MAAM,aAAa,CAAA;AA8EpB;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,qBAAqB,GAC1B,IAAI,CAiGN"}

package/lib/authentication/login.handler.js

@@ -0,0 +1,155 @@
+import { INVALID_AUTH_CONFIG_ERROR, WrongArgumentError } from '../errors.js';
+/**
+ * Normalizes the login path by removing the root path
+ * @param admin - AdminJS instance
+ * @returns Normalized login path
+ */
+function getLoginPath(admin) {
+    const { loginPath, rootPath } = admin.options;
+    const normalizedLoginPath = loginPath.replace(rootPath, '');
+    return normalizedLoginPath.startsWith('/')
+        ? normalizedLoginPath
+        : `/${normalizedLoginPath}`;
+}
+/**
+ * Manages login retry attempts per IP address
+ */
+class Retry {
+    static retriesContainer = new Map();
+    lastRetry;
+    retriesCount = 0;
+    constructor(ip) {
+        const existing = Retry.retriesContainer.get(ip);
+        if (existing) {
+            return existing;
+        }
+        Retry.retriesContainer.set(ip, this);
+    }
+    /**
+     * Checks if a login attempt is allowed based on retry limits
+     * @param maxRetries - Maximum retry configuration
+     * @returns true if login is allowed, false otherwise
+     */
+    canLogin(maxRetries) {
+        if (maxRetries === undefined) {
+            return true;
+        }
+        // Convert number to AuthenticationMaxRetriesOptions
+        let retryConfig;
+        if (typeof maxRetries === 'number') {
+            retryConfig = {
+                count: maxRetries,
+                duration: 60, // per minute
+            };
+        }
+        else {
+            retryConfig = maxRetries;
+        }
+        if (retryConfig.count <= 0) {
+            return true;
+        }
+        // Check if duration has passed since last retry
+        if (!this.lastRetry ||
+            new Date().getTime() - this.lastRetry.getTime() >
+                retryConfig.duration * 1000) {
+            // Reset counter
+            this.lastRetry = new Date();
+            this.retriesCount = 1;
+            return true;
+        }
+        else {
+            // Increment counter
+            this.lastRetry = new Date();
+            this.retriesCount++;
+            return this.retriesCount <= retryConfig.count;
+        }
+    }
+}
+/**
+ * Registers login routes with the Hono app
+ * @param app - Hono app instance
+ * @param admin - AdminJS instance
+ * @param auth - Authentication options
+ */
+export function withLogin(app, admin, auth) {
+    const { rootPath } = admin.options;
+    const loginPath = getLoginPath(admin);
+    const { provider } = auth;
+    const providerProps = provider?.getUiProps?.() ?? {};
+    // GET /login - Render login page
+    app.get(loginPath, async (c) => {
+        const baseProps = {
+            action: admin.options.loginPath,
+            errorMessage: null,
+        };
+        const login = await admin.renderLogin({
+            ...baseProps,
+            ...providerProps,
+        });
+        return c.html(login);
+    });
+    // POST /login - Handle login submission
+    app.post(loginPath, async (c) => {
+        // Get client IP for retry tracking
+        const ip = c.req.header('x-forwarded-for') || c.req.header('x-real-ip') || 'unknown';
+        // Check retry limits
+        if (!new Retry(ip).canLogin(auth.maxRetries)) {
+            const login = await admin.renderLogin({
+                action: admin.options.loginPath,
+                errorMessage: 'tooManyRequests',
+                ...providerProps,
+            });
+            return c.html(login);
+        }
+        const context = { req: c, res: c };
+        let adminUser;
+        try {
+            if (provider) {
+                // Use authentication provider
+                const fields = c.get('fields') || {};
+                adminUser = await provider.handleLogin({
+                    headers: Object.fromEntries(c.req.raw.headers.entries()),
+                    query: c.req.query(),
+                    params: c.req.param(),
+                    data: fields,
+                }, context);
+            }
+            else if (auth.authenticate) {
+                // Use authenticate function
+                const fields = c.get('fields') || {};
+                const { email, password } = fields;
+                adminUser = await auth.authenticate(email, password, context);
+            }
+            else {
+                throw new WrongArgumentError(INVALID_AUTH_CONFIG_ERROR);
+            }
+        }
+        catch (error) {
+            const errorMessage = error.message || error.error || 'invalidCredentials';
+            const loginPage = await admin.renderLogin({
+                action: admin.options.loginPath,
+                errorMessage,
+                ...providerProps,
+            });
+            return c.html(loginPage, 400);
+        }
+        if (adminUser) {
+            // Store user in session
+            const session = c.get('session');
+            session.adminUser = adminUser;
+            // Redirect to original path or root
+            const redirectTo = session.redirectTo || rootPath;
+            delete session.redirectTo;
+            return c.redirect(redirectTo, 302);
+        }
+        else {
+            // Invalid credentials
+            const login = await admin.renderLogin({
+                action: admin.options.loginPath,
+                errorMessage: 'invalidCredentials',
+                ...providerProps,
+            });
+            return c.html(login);
+        }
+    });
+}

package/lib/authentication/logout.handler.d.ts

@@ -0,0 +1,11 @@
+import type AdminJS from 'adminjs';
+import type { Hono } from 'hono';
+import type { AuthenticationOptions } from '../types.js';
+/**
+ * Registers logout route with the Hono app
+ * @param app - Hono app instance
+ * @param admin - AdminJS instance
+ * @param auth - Authentication options
+ */
+export declare function withLogout(app: Hono, admin: AdminJS, auth: AuthenticationOptions): void;
+//# sourceMappingURL=logout.handler.d.ts.map

package/lib/authentication/logout.handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logout.handler.d.ts","sourceRoot":"","sources":["../../src/authentication/logout.handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,SAAS,CAAA;AAClC,OAAO,KAAK,EAAE,IAAI,EAAW,MAAM,MAAM,CAAA;AAEzC,OAAO,KAAK,EAAE,qBAAqB,EAAiB,MAAM,aAAa,CAAA;AAgBvE;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,qBAAqB,GAC1B,IAAI,CAgCN"}

package/lib/authentication/logout.handler.js

@@ -0,0 +1,50 @@
+import { getCookie } from 'hono/cookie';
+import { destroySession } from '../session.js';
+/**
+ * Normalizes the logout path by removing the root path
+ * @param admin - AdminJS instance
+ * @returns Normalized logout path
+ */
+function getLogoutPath(admin) {
+    const { logoutPath, rootPath } = admin.options;
+    const normalizedLogoutPath = logoutPath.replace(rootPath, '');
+    return normalizedLogoutPath.startsWith('/')
+        ? normalizedLogoutPath
+        : `/${normalizedLogoutPath}`;
+}
+/**
+ * Registers logout route with the Hono app
+ * @param app - Hono app instance
+ * @param admin - AdminJS instance
+ * @param auth - Authentication options
+ */
+export function withLogout(app, admin, auth) {
+    const logoutPath = getLogoutPath(admin);
+    const { provider } = auth;
+    app.get(logoutPath, async (c) => {
+        // Call provider's handleLogout if available
+        if (provider) {
+            try {
+                await provider.handleLogout({ req: c, res: c });
+            }
+            catch (error) {
+                // Fail silently and continue with logout
+                console.error('Provider logout error:', error);
+            }
+        }
+        // Get session ID and destroy session
+        const cookieName = auth.cookieName || 'adminjs';
+        const sessionId = getCookie(c, cookieName);
+        if (sessionId) {
+            destroySession(sessionId);
+        }
+        // Clear session from context
+        const session = c.get('session');
+        if (session) {
+            delete session.adminUser;
+            delete session.redirectTo;
+        }
+        // Redirect to login page
+        return c.redirect(admin.options.loginPath);
+    });
+}

package/lib/authentication/protected-routes.handler.d.ts

@@ -0,0 +1,11 @@
+import type AdminJS from 'adminjs';
+import type { Hono } from 'hono';
+/**
+ * Registers middleware to protect routes that require authentication
+ * Redirects unauthenticated requests to the login page
+ *
+ * @param app - Hono app instance
+ * @param admin - AdminJS instance
+ */
+export declare function withProtectedRoutesHandler(app: Hono, admin: AdminJS): void;
+//# sourceMappingURL=protected-routes.handler.d.ts.map

package/lib/authentication/protected-routes.handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protected-routes.handler.d.ts","sourceRoot":"","sources":["../../src/authentication/protected-routes.handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,SAAS,CAAA;AAClC,OAAO,KAAK,EAAE,IAAI,EAA8B,MAAM,MAAM,CAAA;AAG5D;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,OAAO,GACb,IAAI,CAuBN"}

package/lib/authentication/protected-routes.handler.js

@@ -0,0 +1,26 @@
+/**
+ * Registers middleware to protect routes that require authentication
+ * Redirects unauthenticated requests to the login page
+ *
+ * @param app - Hono app instance
+ * @param admin - AdminJS instance
+ */
+export function withProtectedRoutesHandler(app, admin) {
+    const { loginPath } = admin.options;
+    const authorizedRoutesMiddleware = async (c, next) => {
+        const session = c.get('session');
+        // Check if user is authenticated
+        if (!session || !session.adminUser) {
+            // Store the original path for redirect after login
+            session.redirectTo = c.req.path;
+            // Redirect to login page
+            return c.redirect(loginPath);
+        }
+        // User is authenticated, proceed
+        return next();
+    };
+    // Apply middleware to all routes
+    // Note: This should be registered after login/logout routes
+    // so they remain accessible without authentication
+    app.use('*', authorizedRoutesMiddleware);
+}

package/lib/authentication/refresh.handler.d.ts

@@ -0,0 +1,13 @@
+import type AdminJS from 'adminjs';
+import type { Hono } from 'hono';
+import type { AuthenticationOptions } from '../types.js';
+/**
+ * Registers token refresh route with the Hono app
+ * Delegates to authentication provider's refresh method if available
+ *
+ * @param app - Hono app instance
+ * @param admin - AdminJS instance
+ * @param auth - Authentication options
+ */
+export declare function withRefresh(app: Hono, admin: AdminJS, auth: AuthenticationOptions): void;
+//# sourceMappingURL=refresh.handler.d.ts.map

package/lib/authentication/refresh.handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh.handler.d.ts","sourceRoot":"","sources":["../../src/authentication/refresh.handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,SAAS,CAAA;AAClC,OAAO,KAAK,EAAE,IAAI,EAAW,MAAM,MAAM,CAAA;AACzC,OAAO,KAAK,EAAE,qBAAqB,EAAiB,MAAM,aAAa,CAAA;AAEvE;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,qBAAqB,GAC1B,IAAI,CA0CN"}