@sentropic/auth-hono 0.2.1

package/src/router.ts

@@ -0,0 +1,149 @@
+import { Hono, type Context } from 'hono';
+
+import {
+  AUTH_HONO_ROUTE_MAP,
+  type AuthHonoAuthUiMethod,
+  type AuthHonoRouteContract,
+} from './contracts.js';
+import type { AuthHonoPorts } from './ports.js';
+
+export interface CreateAuthRouterOptions {
+  cookieNames?: AuthHonoCookieNames;
+  emailCode?: AuthHonoEmailCodePolicy;
+  handlers?: AuthHonoRouteHandlers;
+  magicLink?: AuthHonoMagicLinkPolicy;
+  ports?: AuthHonoPorts;
+  responsePolicy?: AuthHonoResponsePolicy;
+  routeOverrides?: Partial<Record<AuthHonoAuthUiMethod, AuthHonoRouteContract>>;
+  routePrefix?: string;
+  rp?: AuthHonoRelyingPartyOptions;
+  session?: AuthHonoSessionPolicy;
+  serviceName?: string;
+}
+
+export interface AuthHonoCookieNames {
+  session: string;
+  refresh: string;
+}
+
+export interface AuthHonoRelyingPartyOptions {
+  id: string;
+  name: string;
+  expectedOrigins: string[];
+}
+
+export interface AuthHonoSessionPolicy {
+  sessionTtlSeconds: number;
+  refreshTtlSeconds: number;
+}
+
+export interface AuthHonoEmailCodePolicy {
+  length: number;
+  ttlSeconds: number;
+  maxRequestsPerWindow: number;
+  windowSeconds: number;
+}
+
+export interface AuthHonoMagicLinkPolicy {
+  ttlSeconds: number;
+  baseUrl?: string;
+}
+
+export interface AuthHonoResponsePolicy {
+  notImplementedCode: string;
+  notImplementedMessage: string;
+}
+
+export interface AuthHonoRouterConfig {
+  cookieNames: AuthHonoCookieNames;
+  emailCode: AuthHonoEmailCodePolicy;
+  magicLink: AuthHonoMagicLinkPolicy;
+  responsePolicy: AuthHonoResponsePolicy;
+  routePrefix: string;
+  routes: Record<AuthHonoAuthUiMethod, AuthHonoRouteContract>;
+  rp?: AuthHonoRelyingPartyOptions;
+  session: AuthHonoSessionPolicy;
+  serviceName: string;
+}
+
+export type AuthHonoRouteHandler = (c: Context) => Response | Promise<Response>;
+
+export type AuthHonoRouteHandlers = Partial<Record<AuthHonoAuthUiMethod, AuthHonoRouteHandler>>;
+
+export const createAuthHonoConfig = (options: CreateAuthRouterOptions = {}): AuthHonoRouterConfig => ({
+  cookieNames: {
+    session: options.cookieNames?.session ?? 'session',
+    refresh: options.cookieNames?.refresh ?? 'refreshToken',
+  },
+  emailCode: {
+    length: options.emailCode?.length ?? 6,
+    ttlSeconds: options.emailCode?.ttlSeconds ?? 10 * 60,
+    maxRequestsPerWindow: options.emailCode?.maxRequestsPerWindow ?? 3,
+    windowSeconds: options.emailCode?.windowSeconds ?? 10 * 60,
+  },
+  magicLink: {
+    ttlSeconds: options.magicLink?.ttlSeconds ?? 10 * 60,
+    baseUrl: options.magicLink?.baseUrl,
+  },
+  responsePolicy: {
+    notImplementedCode: options.responsePolicy?.notImplementedCode ?? 'not_implemented',
+    notImplementedMessage:
+      options.responsePolicy?.notImplementedMessage ?? 'Auth route handler is not implemented yet.',
+  },
+  routePrefix: normalizeRoutePrefix(options.routePrefix),
+  routes: {
+    ...AUTH_HONO_ROUTE_MAP,
+    ...options.routeOverrides,
+  },
+  rp: options.rp,
+  session: {
+    sessionTtlSeconds: options.session?.sessionTtlSeconds ?? 7 * 24 * 60 * 60,
+    refreshTtlSeconds: options.session?.refreshTtlSeconds ?? 30 * 24 * 60 * 60,
+  },
+  serviceName: options.serviceName ?? 'auth',
+});
+
+export const createAuthRouter = (options: CreateAuthRouterOptions = {}): Hono => {
+  const router = new Hono();
+  const config = createAuthHonoConfig(options);
+
+  router.get(joinRoutePath(config.routePrefix, '/health'), (c) =>
+    c.json({ status: 'ok', service: config.serviceName })
+  );
+
+  for (const routeName of Object.keys(config.routes) as AuthHonoAuthUiMethod[]) {
+    const contract = config.routes[routeName];
+    const handler = options.handlers?.[routeName];
+
+    router.on(contract.method, joinRoutePath(config.routePrefix, contract.path), (c) => {
+      if (handler) {
+        return handler(c);
+      }
+
+      return c.json(
+        {
+          error: {
+            code: config.responsePolicy.notImplementedCode,
+            message: config.responsePolicy.notImplementedMessage,
+          },
+        },
+        501
+      );
+    });
+  }
+
+  return router;
+};
+
+const normalizeRoutePrefix = (prefix: string | undefined): string => {
+  if (!prefix || prefix === '/') {
+    return '';
+  }
+
+  return `/${prefix.replace(/^\/+|\/+$/g, '')}`;
+};
+
+const joinRoutePath = (prefix: string, path: string): string => {
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  return `${prefix}${normalizedPath}`;
+};

package/src/session-route-handlers.ts

@@ -0,0 +1,128 @@
+import type { Context } from 'hono';
+import { z } from 'zod';
+
+import type { AuthHonoCookiePort } from './ports.js';
+import type { AuthHonoSessionService } from './session.js';
+import type { AuthHonoRouteHandlers } from './router.js';
+
+export interface CreateAuthSessionRouteHandlersOptions {
+  cookies: AuthHonoCookiePort;
+  service: AuthHonoSessionService;
+}
+
+const refreshSessionSchema = z.object({
+  refreshToken: z.string().min(1),
+});
+
+export const createAuthSessionRouteHandlers = (
+  options: CreateAuthSessionRouteHandlersOptions
+): AuthHonoRouteHandlers => ({
+  async refreshSession(c) {
+    const parsed = await parseJson(c, refreshSessionSchema);
+
+    if (!parsed.ok) {
+      return errorResponse(c, 400, 'invalid_input', 'Invalid request data.', parsed.error.errors);
+    }
+
+    const tokens = await options.service.refreshSession(parsed.value.refreshToken);
+
+    if (!tokens) {
+      return errorResponse(c, 401, 'invalid_session', 'Invalid or expired refresh token.');
+    }
+
+    appendSetCookie(
+      c,
+      options.cookies.serializeSessionCookie({
+        expiresAt: tokens.expiresAt,
+        token: tokens.sessionToken,
+      })
+    );
+    appendSetCookie(
+      c,
+      options.cookies.serializeRefreshCookie({
+        expiresAt: tokens.expiresAt,
+        token: tokens.refreshToken,
+      })
+    );
+
+    return c.json({
+      expiresAt: tokens.expiresAt.toISOString(),
+      refreshToken: tokens.refreshToken,
+      sessionToken: tokens.sessionToken,
+      success: true,
+    });
+  },
+
+  async logout(c) {
+    const sessionToken = readSessionToken(c, options.cookies);
+
+    if (!sessionToken) {
+      return errorResponse(c, 401, 'authentication_required', 'No session token provided.');
+    }
+
+    const session = await options.service.validateSessionToken(sessionToken);
+
+    if (!session) {
+      return errorResponse(c, 401, 'invalid_session', 'Invalid session.');
+    }
+
+    await options.service.revokeSession(session.sessionRecord.id);
+
+    appendSetCookie(c, options.cookies.serializeClearedSessionCookie());
+    appendSetCookie(c, options.cookies.serializeClearedRefreshCookie());
+
+    return c.json({ message: 'Logged out successfully', success: true });
+  },
+});
+
+const parseJson = async <T extends z.ZodTypeAny>(
+  c: Context,
+  schema: T
+): Promise<{ ok: true; value: z.infer<T> } | { error: z.ZodError; ok: false }> => {
+  const body = await c.req.json().catch(() => null);
+  const parsed = schema.safeParse(body);
+
+  if (!parsed.success) {
+    return { error: parsed.error, ok: false };
+  }
+
+  return { ok: true, value: parsed.data };
+};
+
+const readSessionToken = (c: Context, cookies: AuthHonoCookiePort): string | null => {
+  const cookieToken = cookies.readSessionToken(c.req.raw);
+
+  if (cookieToken) {
+    return cookieToken;
+  }
+
+  const authorization = c.req.header('authorization');
+
+  if (!authorization?.startsWith('Bearer ')) {
+    return null;
+  }
+
+  return authorization.slice('Bearer '.length).trim() || null;
+};
+
+const appendSetCookie = (c: Context, value: string): void => {
+  c.header('Set-Cookie', value, { append: true });
+};
+
+const errorResponse = (
+  c: Context,
+  status: 400 | 401,
+  code: string,
+  message: string,
+  details?: z.ZodIssue[]
+): Response =>
+  c.json(
+    {
+      error: {
+        code,
+        ...(details ? { details } : {}),
+        message,
+      },
+    },
+    status
+  );

package/src/session.ts

@@ -0,0 +1,201 @@
+import type {
+  AuthHonoDeviceInfo,
+  AuthHonoPorts,
+  AuthHonoSessionClaims,
+  AuthHonoSessionRecord,
+  AuthHonoUserRecord,
+} from './ports.js';
+
+export interface AuthHonoSessionTokens {
+  expiresAt: Date;
+  refreshToken: string;
+  sessionId: string;
+  sessionToken: string;
+}
+
+export interface AuthHonoValidatedSession {
+  role: string;
+  session: AuthHonoSessionClaims;
+  sessionRecord: AuthHonoSessionRecord;
+  user: AuthHonoUserRecord;
+}
+
+export interface CreateAuthSessionServiceOptions {
+  ports: AuthHonoPorts;
+  refreshTokenBytes?: number;
+  sessionTtlSeconds?: number;
+}
+
+export interface CreateAuthSessionInput {
+  deviceInfo?: AuthHonoDeviceInfo;
+  mfaVerified?: boolean;
+  user: AuthHonoUserRecord;
+}
+
+export interface AuthHonoSessionService {
+  createSession(input: CreateAuthSessionInput): Promise<AuthHonoSessionTokens>;
+  listUserSessions(userId: string): Promise<AuthHonoSessionRecord[]>;
+  refreshSession(refreshToken: string): Promise<AuthHonoSessionTokens | null>;
+  revokeAllSessions(userId: string): Promise<number>;
+  revokeSession(sessionId: string): Promise<boolean>;
+  validateSessionToken(sessionToken: string): Promise<AuthHonoValidatedSession | null>;
+}
+
+export const createAuthSessionService = (
+  options: CreateAuthSessionServiceOptions
+): AuthHonoSessionService => {
+  const sessionTtlSeconds = options.sessionTtlSeconds ?? 7 * 24 * 60 * 60;
+  const refreshTokenBytes = options.refreshTokenBytes ?? 32;
+
+  return {
+    async createSession(input) {
+      const now = options.ports.clock.now();
+      const sessionId = options.ports.random.uuid();
+      const expiresAt = options.ports.clock.addSeconds(now, sessionTtlSeconds);
+      const refreshToken = options.ports.random.token(refreshTokenBytes);
+      const sessionToken = await options.ports.tokens.signSessionToken(
+        {
+          userId: input.user.id,
+          sessionId,
+          role: input.user.role,
+          email: input.user.email,
+          displayName: input.user.displayName,
+        },
+        expiresAt
+      );
+
+      const sessionTokenHash = await options.ports.tokens.hashSecret(sessionToken);
+      const refreshTokenHash = await options.ports.tokens.hashSecret(refreshToken);
+      const sessionRecord = await options.ports.sessions.create({
+        id: sessionId,
+        userId: input.user.id,
+        sessionTokenHash,
+        refreshTokenHash,
+        deviceInfo: input.deviceInfo,
+        mfaVerified: input.mfaVerified ?? false,
+        expiresAt,
+        now,
+      });
+
+      return {
+        expiresAt: sessionRecord.expiresAt,
+        refreshToken,
+        sessionId: sessionRecord.id,
+        sessionToken,
+      };
+    },
+
+    listUserSessions(userId) {
+      return options.ports.sessions.listForUser(userId);
+    },
+
+    async refreshSession(refreshToken) {
+      const now = options.ports.clock.now();
+      const refreshTokenHash = await options.ports.tokens.hashSecret(refreshToken);
+      const sessionRecord = await options.ports.sessions.findByRefreshTokenHash(refreshTokenHash);
+
+      if (!sessionRecord || sessionRecord.revokedAt || sessionRecord.expiresAt <= now) {
+        return null;
+      }
+
+      const user = await options.ports.users.findById(sessionRecord.userId);
+
+      if (!user) {
+        return null;
+      }
+
+      const decision = await options.ports.accountPolicy.canAuthenticate(user, now);
+
+      if (!decision.allowed) {
+        return null;
+      }
+
+      const role = await options.ports.accountPolicy.resolveSessionRole(user, now);
+      const expiresAt = options.ports.clock.addSeconds(now, sessionTtlSeconds);
+      const nextRefreshToken = options.ports.random.token(refreshTokenBytes);
+      const nextSessionToken = await options.ports.tokens.signSessionToken(
+        {
+          userId: user.id,
+          sessionId: sessionRecord.id,
+          role,
+          email: user.email,
+          displayName: user.displayName,
+        },
+        expiresAt
+      );
+      const nextSessionTokenHash = await options.ports.tokens.hashSecret(nextSessionToken);
+      const nextRefreshTokenHash = await options.ports.tokens.hashSecret(nextRefreshToken);
+      const updatedSession = await options.ports.sessions.updateTokens({
+        expiresAt,
+        refreshTokenHash: nextRefreshTokenHash,
+        sessionId: sessionRecord.id,
+        sessionTokenHash: nextSessionTokenHash,
+      });
+
+      if (!updatedSession) {
+        return null;
+      }
+
+      return {
+        expiresAt: updatedSession.expiresAt,
+        refreshToken: nextRefreshToken,
+        sessionId: updatedSession.id,
+        sessionToken: nextSessionToken,
+      };
+    },
+
+    revokeAllSessions(userId) {
+      return options.ports.sessions.revokeAllForUser(userId);
+    },
+
+    revokeSession(sessionId) {
+      return options.ports.sessions.revoke(sessionId);
+    },
+
+    async validateSessionToken(sessionToken) {
+      const claims = await options.ports.tokens.verifySessionToken(sessionToken);
+
+      if (!claims) {
+        return null;
+      }
+
+      const tokenHash = await options.ports.tokens.hashSecret(sessionToken);
+      const sessionRecord = await options.ports.sessions.findByTokenHash(tokenHash);
+      const now = options.ports.clock.now();
+
+      if (
+        !sessionRecord ||
+        sessionRecord.id !== claims.sessionId ||
+        sessionRecord.userId !== claims.userId ||
+        sessionRecord.revokedAt ||
+        sessionRecord.expiresAt <= now
+      ) {
+        return null;
+      }
+
+      const user = await options.ports.users.findById(claims.userId);
+
+      if (!user) {
+        return null;
+      }
+
+      const decision = await options.ports.accountPolicy.canAuthenticate(user, now);
+
+      if (!decision.allowed) {
+        return null;
+      }
+
+      const role = await options.ports.accountPolicy.resolveSessionRole(user, now);
+      const session = { ...claims, role };
+
+      await options.ports.sessions.touch(sessionRecord.id, now);
+
+      return {
+        role,
+        session,
+        sessionRecord,
+        user,
+      };
+    },
+  };
+};

package/src/webauthn-authentication-route-handlers.ts

@@ -0,0 +1,200 @@
+import type { AuthenticationResponseJSON } from '@simplewebauthn/server';
+import type { Context } from 'hono';
+import type { ContentfulStatusCode } from 'hono/utils/http-status';
+import { z } from 'zod';
+
+import type {
+  AuthHonoGenerateAuthenticationOptionsInput,
+  AuthHonoWebAuthnAuthenticationService,
+} from './webauthn-authentication.js';
+import type { AuthHonoRouteHandlers } from './router.js';
+import type { AuthHonoRouteHandlerError } from './webauthn-registration-route-handlers.js';
+
+export interface CreateAuthWebAuthnAuthenticationRouteHandlersOptions {
+  finalizeAuthentication?: AuthHonoFinalizeAuthentication;
+  resolveAuthenticationOptions: AuthHonoResolveAuthenticationOptions;
+  service: AuthHonoWebAuthnAuthenticationService;
+}
+
+export type AuthHonoResolveAuthenticationOptions = (
+  input: AuthHonoAuthenticationOptionsRequest,
+  c: Context
+) =>
+  | Promise<AuthHonoGenerateAuthenticationOptionsInput | AuthHonoRouteHandlerError>
+  | AuthHonoGenerateAuthenticationOptionsInput
+  | AuthHonoRouteHandlerError;
+
+export type AuthHonoFinalizeAuthentication = (
+  result: AuthHonoFinalizeAuthenticationInput,
+  c: Context
+) => Response | Promise<Response>;
+
+export interface AuthHonoFinalizeAuthenticationInput {
+  credentialId: string;
+  request: AuthHonoAuthenticationVerifyRequest;
+  userId: string;
+}
+
+export interface AuthHonoAuthenticationOptionsRequest {
+  email?: string;
+}
+
+export interface AuthHonoAuthenticationVerifyRequest {
+  credential: AuthenticationResponseJSON;
+  deviceName?: string;
+}
+
+const isRouteHandlerError = (value: unknown): value is AuthHonoRouteHandlerError =>
+  Boolean(
+    value &&
+      typeof value === 'object' &&
+      'error' in (value as Record<string, unknown>) &&
+      typeof (value as { error?: unknown }).error === 'object' &&
+      (value as { error?: { code?: unknown } }).error?.code !== undefined
+  );
+
+const authenticationOptionsSchema = z.object({
+  email: z.string().email().optional(),
+});
+
+const authenticationVerifySchema = z.object({
+  credential: z.custom<AuthenticationResponseJSON>(
+    (value) => Boolean(value && typeof value === 'object' && 'response' in value)
+  ),
+  deviceName: z.string().max(100).optional(),
+});
+
+export const createAuthWebAuthnAuthenticationRouteHandlers = (
+  options: CreateAuthWebAuthnAuthenticationRouteHandlersOptions
+): AuthHonoRouteHandlers => ({
+  async createPasskeyAuthenticationOptions(c) {
+    const input = await parseJson(c, authenticationOptionsSchema);
+
+    if (!input.ok) {
+      return invalidRequest(c, input.error);
+    }
+
+    const serviceInput = await options.resolveAuthenticationOptions(input.value, c);
+
+    if (isRouteHandlerError(serviceInput)) {
+      return simpleError(
+        c,
+        serviceInput.error.status,
+        serviceInput.error.code,
+        serviceInput.error.message
+      );
+    }
+
+    const authenticationOptions = await options.service.generateAuthenticationOptions(serviceInput);
+
+    return c.json({ options: authenticationOptions });
+  },
+
+  async verifyPasskeyAuthentication(c) {
+    const input = await parseJson(c, authenticationVerifySchema);
+
+    if (!input.ok) {
+      return invalidRequest(c, input.error);
+    }
+
+    const challenge = extractChallenge(input.value.credential);
+
+    if (!challenge) {
+      return simpleError(c, 400, 'invalid_credential', 'Credential challenge is missing or invalid.');
+    }
+
+    const result = await options.service.verifyAuthentication({
+      credential: input.value.credential,
+      expectedChallenge: challenge,
+    });
+
+    if (!result.verified) {
+      return serviceError(c, result.error);
+    }
+
+    if (options.finalizeAuthentication) {
+      return options.finalizeAuthentication(
+        {
+          credentialId: result.credentialId,
+          request: input.value,
+          userId: result.userId,
+        },
+        c
+      );
+    }
+
+    return c.json({
+      credentialId: result.credentialId,
+      success: true,
+      userId: result.userId,
+    });
+  },
+});
+
+const parseJson = async <T extends z.ZodTypeAny>(
+  c: Context,
+  schema: T
+): Promise<{ ok: true; value: z.infer<T> } | { error: z.ZodError; ok: false }> => {
+  const body = await c.req.json().catch(() => null);
+  const parsed = schema.safeParse(body);
+
+  if (!parsed.success) {
+    return { error: parsed.error, ok: false };
+  }
+
+  return { ok: true, value: parsed.data };
+};
+
+const extractChallenge = (credential: AuthenticationResponseJSON): string | null => {
+  const clientDataJson = credential.response?.clientDataJSON;
+
+  if (!clientDataJson) {
+    return null;
+  }
+
+  try {
+    const json = JSON.parse(decodeBase64Url(clientDataJson)) as { challenge?: unknown };
+    return typeof json.challenge === 'string' && json.challenge.length > 0 ? json.challenge : null;
+  } catch {
+    return null;
+  }
+};
+
+const decodeBase64Url = (value: string): string => {
+  const base64 = value.replace(/-/g, '+').replace(/_/g, '/');
+  const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, '=');
+  return atob(padded);
+};
+
+const invalidRequest = (c: Context, error: z.ZodError): Response =>
+  c.json(
+    {
+      error: {
+        code: 'invalid_input',
+        details: error.errors,
+        message: 'Invalid request data.',
+      },
+    },
+    400
+  );
+
+const serviceError = (
+  c: Context,
+  error: { code: string; message: string; status: number }
+): Response => simpleError(c, error.status as ContentfulStatusCode, error.code, error.message);
+
+const simpleError = (
+  c: Context,
+  status: ContentfulStatusCode,
+  code: string,
+  message: string
+): Response =>
+  c.json(
+    {
+      error: {
+        code,
+        message,
+      },
+    },
+    status
+  );