From inai-auth-skills
Integrate InAI Auth SDK into Hono applications. Use this skill whenever the user wants to add authentication, login, signup, middleware protection, role-based access control (RBAC), MFA, or session management to a Hono app using @inai-dev/hono. Also trigger when the user mentions InAI auth with Hono, asks about protecting routes in Hono, needs auth middleware for Hono or Cloudflare Workers, wants to set up auth API routes in Hono, or is building an edge-first API with Hono that needs authentication. Covers middleware setup, route protection, cookie management, and both app and platform auth modes.
How this skill is triggered — by the user, by Claude, or both
Slash command
/inai-auth-skills:inai-hono-sdkThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill guides you through integrating InAI Auth into Hono 4+ applications using the `@inai-dev/hono` package. Works with Cloudflare Workers, Deno, Bun, and Node.js.
This skill guides you through integrating InAI Auth into Hono 4+ applications using the @inai-dev/hono package. Works with Cloudflare Workers, Deno, Bun, and Node.js.
https://apiauth.inai.dev — hardcoded in the SDK, never configurableINAI_PUBLISHABLE_KEY=pk_live_...@inai-dev/hono (depends on @inai-dev/backend and @inai-dev/shared)"app" (end users) and "platform" (admin/developer panels)hono >= 4.0.0npm install @inai-dev/hono
inaiAuthMiddleware() as global middlewarecreateAuthRoutes() mounted as a sub-apprequireAuth() for per-route authorizationimport { Hono } from "hono";
import { inaiAuthMiddleware } from "@inai-dev/hono/middleware";
const app = new Hono();
app.use(
"*",
inaiAuthMiddleware({
publicRoutes: ["/", "/health", "/login", "/register"],
})
);
publicRoutes — if so, sets inaiAuth context to null and proceedsAuthorization: Bearer <token> header or auth_token cookierefresh_token cookie exists → auto-refreshAuthObject and stores in Hono context as inaiAuthonUnauthorized handler (default: 401 JSON response)inaiAuthMiddleware({
authMode: "app", // "app" (default) or "platform"
publicRoutes: ["/", "/health"], // string[] or (path: string) => boolean
onUnauthorized: (c) => {
return c.json({ error: "Unauthorized" }, 401);
},
// jwksUrl: "https://apiauth.inai.dev/.well-known/jwks.json", // optional override
})
// String array
publicRoutes: ["/", "/health", "/api/public/*"]
// Function
publicRoutes: (path) => path.startsWith("/public/")
import { createAuthRoutes } from "@inai-dev/hono/api-routes";
const authRoutes = createAuthRoutes();
app.route("/api/auth", authRoutes);
Creates these endpoints automatically:
POST /api/auth/login — Login, sets httpOnly cookies. Returns { user } or { mfa_required, mfa_token }POST /api/auth/register — Registration. Returns { user } or { needs_email_verification, user }POST /api/auth/mfa-challenge — TOTP MFA verificationPOST /api/auth/refresh — Token rotation (also called by middleware automatically)POST /api/auth/logout — Invalidate session, clear cookiesFor admin/developer panels, use platform auth mode:
app.use(
"*",
inaiAuthMiddleware({
authMode: "platform",
publicRoutes: ["/login"],
})
);
Platform mode uses /api/platform/auth/* endpoints internally. No publishable key needed.
import { requireAuth } from "@inai-dev/hono/middleware";
// Require any authenticated user
app.get("/api/profile", requireAuth(), (c) => {
const auth = getAuth(c);
return c.json({ userId: auth?.userId });
});
// Require specific role
app.get("/api/admin", requireAuth({ role: "admin" }), (c) => {
return c.json({ message: "Admin access granted" });
});
// Require specific permission
app.put("/api/posts/:id", requireAuth({ permission: "posts:write" }), (c) => {
// Update post...
});
import { getAuth } from "@inai-dev/hono";
app.get("/api/data", (c) => {
const auth = getAuth(c);
if (!auth?.userId) {
return c.json({ error: "Not authenticated" }, 401);
}
if (auth.has({ role: "admin" })) {
// Return admin data
}
return c.json({ userId: auth.userId });
});
The middleware extends Hono's context:
// c.get("inaiAuth") is available after middleware runs
const auth = c.get("inaiAuth");
auth?.userId // string | null
auth?.tenantId // string | null
auth?.orgId // string | null
auth?.orgRole // string | null
auth?.sessionId // string | null
auth?.roles // string[]
auth?.permissions // string[]
auth?.has({ role: "admin" }) // boolean
auth?.has({ permission: "posts:write" }) // boolean
auth?.getToken() // Promise<string | null>
Hono's ContextVariableMap is augmented:
declare module "hono" {
interface ContextVariableMap {
inaiAuth: AuthObject | null;
}
}
| Cookie | Purpose | httpOnly | Path | MaxAge |
|---|---|---|---|---|
auth_token | Access JWT | Yes | / | Token expiry |
refresh_token | Refresh JWT | Yes | / | 7 days |
auth_session | User data (readable by JS) | No | / | Token expiry |
NODE_ENV=production): secure: true on all cookiessecure: false for http://localhostFor custom auth flows or manual token management:
import { setAuthCookies, clearAuthCookies } from "@inai-dev/hono";
// After manual authentication
setAuthCookies(c, tokens, user);
// Manual logout
clearAuthCookies(c);
import { getTokenFromContext, getRefreshTokenFromContext } from "@inai-dev/hono";
// Gets token from Authorization header or auth_token cookie
const token = getTokenFromContext(c);
// Gets refresh token from cookie only
const refreshToken = getRefreshTokenFromContext(c);
{
userId: string | null
tenantId: string | null
appId: string | null
envId: string | null
orgId: string | null
orgRole: string | null
sessionId: string | null
roles: string[]
permissions: string[]
getToken(): Promise<string | null>
has(params: { role?: string; permission?: string }): boolean
}
import { Hono } from "hono";
import {
inaiAuthMiddleware,
requireAuth,
createAuthRoutes,
getAuth,
} from "@inai-dev/hono";
const app = new Hono();
// Global auth middleware
app.use(
"*",
inaiAuthMiddleware({
publicRoutes: ["/", "/health", "/login", "/register"],
})
);
// Auth routes
app.route("/api/auth", createAuthRoutes());
// Public route
app.get("/health", (c) => c.json({ status: "ok" }));
// Protected route
app.get("/api/me", requireAuth(), (c) => {
const auth = getAuth(c);
return c.json({ userId: auth?.userId });
});
// Admin-only route
app.delete("/api/users/:id", requireAuth({ role: "admin" }), (c) => {
// Delete user...
return c.json({ deleted: true });
});
export default app;
// src/index.ts
import { Hono } from "hono";
import { inaiAuthMiddleware, createAuthRoutes } from "@inai-dev/hono";
type Bindings = {
INAI_PUBLISHABLE_KEY: string;
};
const app = new Hono<{ Bindings: Bindings }>();
app.use("*", (c, next) => {
return inaiAuthMiddleware({
publicRoutes: ["/"],
publishableKey: c.env.INAI_PUBLISHABLE_KEY,
})(c, next);
});
app.route("/api/auth", createAuthRoutes());
export default app;
const res = await fetch("/api/auth/login", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ email, password }),
});
const data = await res.json();
if (data.mfa_required) {
await fetch("/api/auth/mfa-challenge", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ mfa_token: data.mfa_token, code: totpCode }),
});
}
When you need to check implementation details, the source files are at:
packages/hono/src/middleware.ts — inaiAuthMiddleware(), requireAuth()packages/hono/src/api-routes.ts — createAuthRoutes()packages/hono/src/helpers.ts — Cookie & token context utilitiespackages/hono/src/types.ts — TypeScript interfaces & Hono type augmentationpackages/backend/src/client.ts — InAIAuthClient (core API client)packages/shared/src/constants.ts — Cookie names, URLs, headerspackages/shared/src/jwks.ts — JWKSClient (JWKS key fetching, caching, error throttling)packages/shared/src/jwt.ts — ES256 verification, JWT decodingnpx claudepluginhub inai-team/inai-auth-skills --plugin inai-auth-skillsGuides Hono app creation, API building, middleware/auth/validation addition, routing, context usage, streaming, WebSocket, CORS, testing, SSG, and multi-runtime deployment including Cloudflare Workers.
Scaffold signin and signup authentication endpoints for a project. Use when the user wants to add authentication, create login/register flows, or set up auth from scratch.
Builds ultra-fast web APIs and full-stack apps with Hono on Cloudflare Workers, Deno, Bun, Node.js. Covers routing, middleware, JSX support, RPC client for edge and BFFs.