@ahmedbaset/adminjs-hono 0.1.0

package/lib/session.js

@@ -0,0 +1,56 @@
+import { getCookie, setCookie } from 'hono/cookie';
+// In-memory session store (not suitable for production with multiple instances)
+const sessions = new Map();
+/**
+ * Generates a unique session ID using Web Crypto API
+ * @returns A unique session identifier
+ */
+function generateSessionId() {
+    return crypto.randomUUID();
+}
+/**
+ * Creates session middleware for Hono
+ * Manages cookie-based sessions with in-memory storage
+ *
+ * @param secret - Secret key for session (currently unused, for future HMAC signing)
+ * @param cookieName - Name of the session cookie
+ * @param options - Session cookie options
+ * @returns Hono middleware handler
+ */
+export function createSessionMiddleware(secret, cookieName, options) {
+    return async (c, next) => {
+        let sessionId = getCookie(c, cookieName);
+        // Create new session if none exists or session not found
+        if (!sessionId || !sessions.has(sessionId)) {
+            sessionId = generateSessionId();
+            sessions.set(sessionId, {});
+        }
+        // Get session data and store in context
+        const session = sessions.get(sessionId);
+        c.set('session', session);
+        await next();
+        // Save session cookie after request processing
+        setCookie(c, cookieName, sessionId, {
+            httpOnly: options?.httpOnly ?? true,
+            secure: options?.secure ?? false,
+            sameSite: options?.sameSite ?? 'Lax',
+            maxAge: options?.maxAge ?? 86400, // 24 hours default
+            path: options?.path ?? '/',
+            domain: options?.domain,
+        });
+    };
+}
+/**
+ * Destroys a session by removing it from the store
+ * @param sessionId - The session ID to destroy
+ */
+export function destroySession(sessionId) {
+    sessions.delete(sessionId);
+}
+/**
+ * Gets the session store (for testing purposes)
+ * @returns The session store Map
+ */
+export function getSessionStore() {
+    return sessions;
+}

package/lib/types.d.ts

@@ -0,0 +1,46 @@
+import type { BaseAuthProvider, CurrentAdmin } from 'adminjs';
+import type { Context } from 'hono';
+export type UploadOptions = {
+    uploadDir?: string;
+    maxFileSize?: number;
+    maxFieldsSize?: number;
+    maxFields?: number;
+    keepExtensions?: boolean;
+};
+export type HonoVariables = {
+    session: SessionData;
+    fields: Record<string, any>;
+    files: Record<string, File>;
+};
+export type AuthenticationContext = {
+    req: Context<{
+        Variables: HonoVariables;
+    }>;
+    res: Context<{
+        Variables: HonoVariables;
+    }>;
+};
+export type AuthenticationMaxRetriesOptions = {
+    count: number;
+    duration: number;
+};
+export type AuthenticationOptions = {
+    cookiePassword: string;
+    cookieName?: string;
+    authenticate?: (email: string, password: string, context?: AuthenticationContext) => Promise<CurrentAdmin | null> | CurrentAdmin | null;
+    maxRetries?: number | AuthenticationMaxRetriesOptions;
+    provider?: BaseAuthProvider;
+};
+export type SessionOptions = {
+    maxAge?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    domain?: string;
+    path?: string;
+};
+export type SessionData = {
+    adminUser?: CurrentAdmin;
+    redirectTo?: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAC7D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,MAAM,MAAM,aAAa,GAAG;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB,CAAA;AAGD,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,WAAW,CAAA;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;CAC5B,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,GAAG,EAAE,OAAO,CAAC;QAAE,SAAS,EAAE,aAAa,CAAA;KAAE,CAAC,CAAA;IAC1C,GAAG,EAAE,OAAO,CAAC;QAAE,SAAS,EAAE,aAAa,CAAA;KAAE,CAAC,CAAA;CAC3C,CAAA;AAED,MAAM,MAAM,+BAA+B,GAAG;IAC5C,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,cAAc,EAAE,MAAM,CAAA;IACtB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,YAAY,CAAC,EAAE,CACb,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,qBAAqB,KAC5B,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,YAAY,GAAG,IAAI,CAAA;IACvD,UAAU,CAAC,EAAE,MAAM,GAAG,+BAA+B,CAAA;IACrD,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CAC5B,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAA;IACpC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,SAAS,CAAC,EAAE,YAAY,CAAA;IACxB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA"}

package/lib/types.js

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

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@ahmedbaset/adminjs-hono",
+  "version": "0.1.0",
+  "description": "AdminJS adapter for Hono web framework",
+  "main": "lib/index.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./lib/index.js",
+      "types": "./lib/index.d.ts"
+    }
+  },
+  "keywords": [
+    "hono",
+    "admin",
+    "adminjs",
+    "admin-panel"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "adminjs": "^7.4.0",
+    "hono": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "adminjs": "^7.4.0",
+    "eslint": "^8.0.0",
+    "fast-check": "^3.15.0",
+    "hono": "^4.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.2.0"
+  },
+  "scripts": {
+    "dev": "rm -rf lib && tsc --watch",
+    "build": "rm -rf lib && tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint './**/*.ts'",
+    "check:all": "npm run lint && npm run build && npm run test"
+  }
+}

package/src/authentication/login.handler.ts

@@ -0,0 +1,193 @@
+import type AdminJS from 'adminjs'
+import type { Hono, Context } from 'hono'
+import type {
+  AuthenticationContext,
+  AuthenticationMaxRetriesOptions,
+  AuthenticationOptions,
+  HonoVariables,
+} from '../types.js'
+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: AdminJS): string {
+  const { loginPath, rootPath } = admin.options
+  const normalizedLoginPath = loginPath.replace(rootPath, '')
+  return normalizedLoginPath.startsWith('/')
+    ? normalizedLoginPath
+    : `/${normalizedLoginPath}`
+}
+
+/**
+ * Manages login retry attempts per IP address
+ */
+class Retry {
+  private static retriesContainer: Map<string, Retry> = new Map()
+  private lastRetry: Date | undefined
+  private retriesCount = 0
+
+  constructor(ip: string) {
+    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
+   */
+  public canLogin(
+    maxRetries: number | AuthenticationMaxRetriesOptions | undefined
+  ): boolean {
+    if (maxRetries === undefined) {
+      return true
+    }
+    
+    // Convert number to AuthenticationMaxRetriesOptions
+    let retryConfig: AuthenticationMaxRetriesOptions
+    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: Hono,
+  admin: AdminJS,
+  auth: AuthenticationOptions
+): void {
+  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: Context<{ Variables: HonoVariables }>) => {
+    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: Context<{ Variables: HonoVariables }>) => {
+    // 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: AuthenticationContext = { 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 as {
+          email: string
+          password: string
+        }
+        adminUser = await auth.authenticate(email, password, context)
+      } else {
+        throw new WrongArgumentError(INVALID_AUTH_CONFIG_ERROR)
+      }
+    } catch (error: any) {
+      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/src/authentication/logout.handler.ts

@@ -0,0 +1,62 @@
+import type AdminJS from 'adminjs'
+import type { Hono, Context } from 'hono'
+import { getCookie } from 'hono/cookie'
+import type { AuthenticationOptions, HonoVariables } from '../types.js'
+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: AdminJS): string {
+  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: Hono,
+  admin: AdminJS,
+  auth: AuthenticationOptions
+): void {
+  const logoutPath = getLogoutPath(admin)
+  const { provider } = auth
+  
+  app.get(logoutPath, async (c: Context<{ Variables: HonoVariables }>) => {
+    // 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/src/authentication/protected-routes.handler.ts

@@ -0,0 +1,38 @@
+import type AdminJS from 'adminjs'
+import type { Hono, MiddlewareHandler, Context } from 'hono'
+import type { HonoVariables } from '../types.js'
+
+/**
+ * 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: Hono,
+  admin: AdminJS
+): void {
+  const { loginPath } = admin.options
+  
+  const authorizedRoutesMiddleware: MiddlewareHandler<{ Variables: HonoVariables }> = async (c: Context<{ Variables: HonoVariables }>, 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/src/authentication/refresh.handler.ts

@@ -0,0 +1,59 @@
+import type AdminJS from 'adminjs'
+import type { Hono, Context } from 'hono'
+import type { AuthenticationOptions, HonoVariables } 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 function withRefresh(
+  app: Hono,
+  admin: AdminJS,
+  auth: AuthenticationOptions
+): void {
+  const { provider } = auth
+  
+  // Only register refresh route if provider supports it
+  if (!provider || !(provider as any).handleRefresh) {
+    return
+  }
+  
+  // Typically refresh is at /refresh, but this depends on the provider
+  const refreshPath = '/refresh'
+  
+  app.post(refreshPath, async (c: Context<{ Variables: HonoVariables }>) => {
+    try {
+      const fields = c.get('fields') || {}
+      const session = c.get('session')
+      
+      // Call provider's refresh method
+      const refreshedUser = await (provider as any).handleRefresh(
+        {
+          headers: Object.fromEntries(c.req.raw.headers.entries()),
+          query: c.req.query(),
+          params: c.req.param(),
+          data: fields,
+        },
+        { req: c, res: c }
+      )
+      
+      if (refreshedUser) {
+        // Update session with new credentials
+        session.adminUser = refreshedUser
+        return c.json({ success: true })
+      } else {
+        return c.json({ success: false, error: 'Refresh failed' }, 401)
+      }
+    } catch (error: any) {
+      console.error('Token refresh error:', error)
+      return c.json(
+        { success: false, error: error.message || 'Refresh failed' },
+        401
+      )
+    }
+  })
+}

package/src/buildAuthenticatedRouter.ts

@@ -0,0 +1,92 @@
+import AdminJS, { Router as AdminRouter } from 'adminjs'
+import type { Hono } from 'hono'
+import { withLogin } from './authentication/login.handler.js'
+import { withLogout } from './authentication/logout.handler.js'
+import { withProtectedRoutesHandler } from './authentication/protected-routes.handler.js'
+import { withRefresh } from './authentication/refresh.handler.js'
+import { buildAssets, buildRoutes, initializeAdmin } from './buildRouter.js'
+import {
+  INVALID_AUTH_CONFIG_ERROR,
+  MISSING_AUTH_CONFIG_ERROR,
+  WrongArgumentError,
+} from './errors.js'
+import type { AuthenticationOptions, SessionOptions, UploadOptions } from './types.js'
+import { createFormParserMiddleware } from './formParser.js'
+import { createSessionMiddleware } from './session.js'
+
+/**
+ * Builds a Hono app with AdminJS routes protected by session-based authentication
+ * 
+ * @param admin - The AdminJS instance
+ * @param auth - Authentication configuration
+ * @param predefinedApp - Optional existing Hono app to use
+ * @param sessionOptions - Optional session configuration
+ * @param uploadOptions - Optional upload configuration
+ * @returns Configured Hono app with authentication
+ */
+export function buildAuthenticatedRouter(
+  admin: AdminJS,
+  auth: AuthenticationOptions,
+  predefinedApp?: Hono,
+  sessionOptions?: SessionOptions,
+  uploadOptions?: UploadOptions
+): Hono {
+  // Initialize AdminJS
+  initializeAdmin(admin)
+  
+  // Validate authentication configuration
+  if (!auth.authenticate && !auth.provider) {
+    throw new WrongArgumentError(MISSING_AUTH_CONFIG_ERROR)
+  }
+  
+  if (auth.authenticate && auth.provider) {
+    throw new WrongArgumentError(INVALID_AUTH_CONFIG_ERROR)
+  }
+  
+  // Use provided app or create new Hono instance
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const { Hono: HonoClass } = require('hono')
+  const app = predefinedApp ?? new HonoClass()
+  
+  // Get routes and assets from AdminJS
+  const { routes, assets } = AdminRouter
+  
+  // If provider is configured, add its UI props to AdminJS env
+  if (auth.provider) {
+    admin.options.env = {
+      ...admin.options.env,
+      ...auth.provider.getUiProps(),
+    }
+  }
+  
+  // Configure session middleware
+  const cookieName = auth.cookieName || 'adminjs'
+  app.use('*', createSessionMiddleware(
+    auth.cookiePassword,
+    cookieName,
+    sessionOptions
+  ))
+  
+  // Register form parsing middleware
+  app.use('*', createFormParserMiddleware(uploadOptions))
+  
+  // Register login handler (must be before protected routes middleware)
+  withLogin(app, admin, auth)
+  
+  // Register logout handler (must be before protected routes middleware)
+  withLogout(app, admin, auth)
+  
+  // Build assets (must be before protected routes middleware)
+  buildAssets(assets, routes, app, admin)
+  
+  // Register protected routes middleware (applies to all subsequent routes)
+  withProtectedRoutesHandler(app, admin)
+  
+  // Register refresh handler (after protected routes middleware)
+  withRefresh(app, admin, auth)
+  
+  // Build routes (after protected routes middleware)
+  buildRoutes(routes, app, admin)
+  
+  return app
+}