fix(auth): make AuthManager.verifyToken usable from custom Hono routes (#814) (#819)

AuthManager.verifyToken(token) silently fell back to a dev-only placeholder
secret when called without the JWT_SECRET argument. Custom routes mounted
alongside SonicJS that copy-pasted the docs hit this and rejected every
request as "Invalid token".

- Add AuthManager.verifyAuthRequest(c) helper that pulls the token from the
  Authorization header / auth_token cookie and JWT_SECRET from c.env, so
  custom Hono routes have a one-call equivalent of requireAuth().
- Strengthen verifyToken JSDoc to spell out the secret requirement and point
  to verifyAuthRequest / requireAuth() as the recommended paths.
- Update docs/authentication.md with a "Custom Routes Alongside SonicJS"
  section walking through the three supported patterns; fix verifyToken
  examples in routing-middleware.md, architecture.md, and the AI API
  reference to pass c.env.JWT_SECRET.
- Drive-by: rename destructured `is_active` to `_isActive` in the otp-login
  plugin to clear a pre-existing eslint naming-convention error that was
  blocking the pre-commit hook.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: lane711

docs/ai/core-package-api-reference.md

@@ -242,11 +242,14 @@ const hash = await AuthManager.hashPassword('password123')
 // Verify password
 const valid = await AuthManager.verifyPassword('password123', hash)
 
-// Generate JWT
-const token = await AuthManager.generateToken({ userId, email, role })
+// Generate JWT (pass JWT_SECRET from c.env)
+const token = await AuthManager.generateToken(userId, email, role, c.env.JWT_SECRET)
 
-// Verify JWT
-const payload = await AuthManager.verifyToken(token)
+// Verify JWT — pass the secret, otherwise the dev fallback is used
+const payload = await AuthManager.verifyToken(token, c.env.JWT_SECRET)
+
+// Or, from a Hono handler, do header/cookie/secret extraction in one call:
+const payload = await AuthManager.verifyAuthRequest(c)
 ```
 
 ### Logging Middleware

docs/architecture.md

@@ -390,9 +390,9 @@ export const requireAuth = () => {
       }
     }
 
-    // Verify token if not cached
+    // Verify token if not cached (pass JWT_SECRET from the env binding)
     if (!payload) {
-      payload = await AuthManager.verifyToken(token)
+      payload = await AuthManager.verifyToken(token, c.env?.JWT_SECRET)
 
       // Cache for 5 minutes
       if (payload && kv) {

docs/authentication.md

@@ -177,39 +177,35 @@ fresh one via `POST /auth/refresh`.
 
 ### Token Verification
 
+The `JWT_SECRET` lives on the Cloudflare Workers binding (`c.env.JWT_SECRET`), so
+you must thread the secret through when verifying tokens. The easiest way from a
+Hono handler is `AuthManager.verifyAuthRequest(c)`, which extracts the token
+from the `Authorization` header (or `auth_token` cookie) and pulls the secret
+from `c.env` for you:
+
 ```typescript
-// Verify and decode token
-const payload = await AuthManager.verifyToken(token)
+// Inside a custom Hono route handler
+const payload = await AuthManager.verifyAuthRequest(c)
 
 if (!payload) {
-  // Token invalid or expired
   return c.json({ error: 'Invalid or expired token' }, 401)
 }
 
-// Token is valid, payload contains user info
 console.log(payload.userId, payload.email, payload.role)
 ```
 
-**Implementation:**
+If you already have the raw token, call `verifyToken` directly and pass the
+secret yourself:
 
 ```typescript
-static async verifyToken(token: string): Promise<JWTPayload | null> {
-  try {
-    const payload = await verify(token, JWT_SECRET, 'HS256') as JWTPayload
-
-    // Check if token is expired
-    if (payload.exp < Math.floor(Date.now() / 1000)) {
-      return null
-    }
-
-    return payload
-  } catch (error) {
-    console.error('Token verification failed:', error)
-    return null
-  }
-}
+const payload = await AuthManager.verifyToken(token, c.env.JWT_SECRET)
 ```
 
+> **Heads up:** `AuthManager.verifyToken(token)` (no secret argument) falls
+> back to a development-only placeholder secret. In production this will
+> silently fail to verify any real token. Always pass `c.env.JWT_SECRET`, or
+> use `verifyAuthRequest(c)` / the `requireAuth()` middleware.
+
 ### Token Configuration
 
 ```typescript
@@ -256,9 +252,9 @@ export const requireAuth = () => {
       }
     }
 
-    // If not cached, verify token
+    // If not cached, verify token (passing the JWT_SECRET binding)
     if (!payload) {
-      payload = await AuthManager.verifyToken(token)
+      payload = await AuthManager.verifyToken(token, c.env?.JWT_SECRET)
 
       // Cache the verified payload for 5 minutes
       if (payload && kv) {
@@ -1094,6 +1090,59 @@ app.get('/content/:id',
 )
 ```
 
+### Custom Routes Alongside SonicJS
+
+When you mount your own Hono routes next to a SonicJS app, you can authenticate
+requests with the same JWT that SonicJS issues. Three options, ordered by
+preference:
+
+**1. Use `requireAuth()` middleware** (recommended — matches what SonicJS uses
+internally, including the KV verification cache):
+
+```typescript
+import { Hono } from 'hono'
+import { requireAuth, createSonicJSApp } from '@sonicjs-cms/core'
+
+const app = new Hono()
+const adminRoutes = new Hono()
+
+adminRoutes.use('*', requireAuth())
+adminRoutes.get('/stats', (c) => {
+  const user = c.get('user') // { userId, email, role, ... }
+  return c.json({ user })
+})
+
+app.route('/api/admin', adminRoutes)
+app.route('/', createSonicJSApp(config))
+```
+
+**2. Use `AuthManager.verifyAuthRequest(c)`** when you need custom error
+handling but still want the helper to extract the token + secret for you:
+
+```typescript
+import { AuthManager } from '@sonicjs-cms/core'
+
+adminRoutes.use('*', async (c, next) => {
+  const payload = await AuthManager.verifyAuthRequest(c)
+  if (!payload) return c.json({ error: 'Invalid token' }, 401)
+  if (payload.role !== 'admin') return c.json({ error: 'Forbidden' }, 403)
+  c.set('user', payload)
+  await next()
+})
+```
+
+**3. Call `AuthManager.verifyToken(token, secret)` directly** when you've
+already extracted the token yourself. Always pass `c.env.JWT_SECRET`:
+
+```typescript
+const token = c.req.header('Authorization')?.replace('Bearer ', '')
+const payload = await AuthManager.verifyToken(token, c.env.JWT_SECRET)
+```
+
+> **Don't call `AuthManager.verifyToken(token)` without a secret.** It falls
+> back to a development-only placeholder, so any token signed with your real
+> `JWT_SECRET` will silently fail verification.
+
 ### Custom Authorization Logic
 
 ```typescript

docs/routing-middleware.md

@@ -87,17 +87,22 @@ The authentication system uses JWT tokens stored in HTTP-only cookies.
 ```typescript
 import { AuthManager } from '../middleware/auth'
 
-// Generate JWT token
+// Generate JWT token (pass JWT_SECRET from c.env)
 const token = await AuthManager.generateToken(
   userId,
   email,
-  role
+  role,
+  c.env.JWT_SECRET
 )
 
-// Verify JWT token
-const payload = await AuthManager.verifyToken(token)
+// Verify JWT token — always pass the secret from c.env
+const payload = await AuthManager.verifyToken(token, c.env.JWT_SECRET)
 // Returns: { userId, email, role, exp, iat } or null
 
+// Or, from inside a Hono handler, let the helper extract the token
+// (Authorization header / auth_token cookie) and secret for you:
+const payload = await AuthManager.verifyAuthRequest(c)
+
 // Hash password
 const hash = await AuthManager.hashPassword(password)
 

packages/core/src/__tests__/middleware/auth.test.ts

@@ -132,6 +132,70 @@ describe('AuthManager', () => {
     })
   })
 
+  describe('verifyAuthRequest', () => {
+    const buildContext = (opts: {
+      authHeader?: string
+      cookieHeader?: string
+      env?: Record<string, any>
+    }) => {
+      const headers = new Headers()
+      if (opts.authHeader) headers.set('Authorization', opts.authHeader)
+      if (opts.cookieHeader) headers.set('Cookie', opts.cookieHeader)
+      return {
+        req: {
+          header: (name: string) => headers.get(name) ?? undefined,
+          raw: { headers }
+        },
+        env: opts.env ?? {}
+      } as unknown as Context
+    }
+
+    it('verifies a token from the Authorization header', async () => {
+      const secret = 'request-helper-secret'
+      const token = await AuthManager.generateToken('u-1', 'a@b.c', 'admin', secret, 60)
+
+      const c = buildContext({
+        authHeader: `Bearer ${token}`,
+        env: { JWT_SECRET: secret }
+      })
+
+      const payload = await AuthManager.verifyAuthRequest(c)
+      expect(payload?.userId).toBe('u-1')
+      expect(payload?.email).toBe('a@b.c')
+      expect(payload?.role).toBe('admin')
+    })
+
+    it('falls back to the auth_token cookie when no Authorization header is present', async () => {
+      const secret = 'request-helper-secret'
+      const token = await AuthManager.generateToken('u-2', 'c@d.e', 'editor', secret, 60)
+
+      const c = buildContext({
+        cookieHeader: `auth_token=${token}`,
+        env: { JWT_SECRET: secret }
+      })
+
+      const payload = await AuthManager.verifyAuthRequest(c)
+      expect(payload?.userId).toBe('u-2')
+    })
+
+    it('returns null when no token is provided', async () => {
+      const c = buildContext({ env: { JWT_SECRET: 'whatever' } })
+      const payload = await AuthManager.verifyAuthRequest(c)
+      expect(payload).toBeNull()
+    })
+
+    it('returns null when token is signed with a different secret than c.env.JWT_SECRET', async () => {
+      const token = await AuthManager.generateToken('u-3', 'e@f.g', 'admin', 'real-secret', 60)
+      const c = buildContext({
+        authHeader: `Bearer ${token}`,
+        env: { JWT_SECRET: 'wrong-secret' }
+      })
+
+      const payload = await AuthManager.verifyAuthRequest(c)
+      expect(payload).toBeNull()
+    })
+  })
+
   describe('getJwtExpirySeconds', () => {
     it('defaults to 30 days when env is empty', () => {
       expect(getJwtExpirySeconds({})).toBe(60 * 60 * 24 * 30)

packages/core/src/middleware/auth.ts

@@ -196,6 +196,13 @@ export class AuthManager {
   /**
    * Verify a token's signature and expiration.
    *
+   * IMPORTANT: pass the `JWT_SECRET` binding (e.g. `c.env.JWT_SECRET`) as the
+   * `secret` argument. If omitted, this falls back to a development-only
+   * placeholder secret — tokens signed with the real `JWT_SECRET` will then
+   * silently fail verification. From inside a Hono handler prefer
+   * `AuthManager.verifyAuthRequest(c)`, which handles header/cookie extraction
+   * and pulls the secret from `c.env` for you.
+   *
    * If `graceSeconds` > 0, tokens whose `exp` is within the grace window
    * (i.e. expired by no more than `graceSeconds`) are still returned. This
    * supports a sliding-session refresh endpoint that accepts recently-expired
@@ -243,6 +250,27 @@ export class AuthManager {
     }
   }
 
+  /**
+   * Verify the JWT on an incoming Hono request using the `JWT_SECRET`
+   * binding from `c.env`. Reads the token from the `Authorization: Bearer …`
+   * header first, then falls back to the `auth_token` cookie. Returns the
+   * decoded payload, or null when the token is missing, malformed, expired,
+   * or signed with a different secret.
+   *
+   * Use this from custom Hono routes mounted alongside SonicJS — it
+   * resolves the secret the same way `requireAuth()` does, without forcing
+   * the caller to plumb it through manually.
+   */
+  static async verifyAuthRequest(c: Context): Promise<JWTPayload | null> {
+    let token = c.req.header('Authorization')?.replace('Bearer ', '')
+    if (!token) {
+      token = getCookie(c, 'auth_token')
+    }
+    if (!token) return null
+    const secret = (c.env as any)?.JWT_SECRET
+    return await AuthManager.verifyToken(token, secret)
+  }
+
   static async hashPassword(password: string): Promise<string> {
     const iterations = 100000
     const salt = new Uint8Array(16)

packages/core/src/plugins/core-plugins/otp-login-plugin/index.ts

@@ -333,7 +333,7 @@ export function createOTPLoginPlugin(): Plugin {
       })
 
       const customData = await getCustomData(db, user.id)
-      const { is_active, ...publicUser } = user
+      const { is_active: _isActive, ...publicUser } = user
 
       return c.json({
         success: true,