@sentropic/auth-hono 0.2.1

package/src/middleware.ts

@@ -0,0 +1,178 @@
+import type { Context, MiddlewareHandler, Next } from 'hono';
+
+import type {
+  AuthHonoPorts,
+  AuthHonoSessionClaims,
+  AuthHonoSessionRecord,
+  AuthHonoUserRecord,
+} from './ports.js';
+
+export interface AuthHonoAuthContext {
+  role: string;
+  session: AuthHonoSessionClaims;
+  sessionRecord: AuthHonoSessionRecord;
+  token: string;
+  user: AuthHonoUserRecord;
+}
+
+export interface AuthHonoMiddlewareVariables {
+  auth: AuthHonoAuthContext;
+  session: AuthHonoSessionClaims;
+  user: AuthHonoUserRecord;
+}
+
+export interface AuthHonoMiddlewareEnv {
+  Variables: AuthHonoMiddlewareVariables;
+}
+
+export interface CreateAuthMiddlewareOptions {
+  ports: AuthHonoPorts;
+  unauthorizedCode?: string;
+  unauthorizedMessage?: string;
+}
+
+type AuthResult =
+  | { kind: 'authenticated'; auth: AuthHonoAuthContext }
+  | { kind: 'missing' }
+  | { kind: 'rejected'; code: string; message: string; status: 401 | 403 };
+
+export const createRequireAuth = (options: CreateAuthMiddlewareOptions): MiddlewareHandler => {
+  return async (c, next) => {
+    const result = await authenticateRequest(c, options);
+
+    if (result.kind === 'missing') {
+      return authError(c, {
+        code: options.unauthorizedCode ?? 'unauthorized',
+        message: options.unauthorizedMessage ?? 'Authentication required.',
+        status: 401,
+      });
+    }
+
+    if (result.kind === 'rejected') {
+      return authError(c, result);
+    }
+
+    setAuthContext(c, result.auth);
+    await next();
+  };
+};
+
+export const createOptionalAuth = (options: CreateAuthMiddlewareOptions): MiddlewareHandler => {
+  return async (c, next) => {
+    const result = await authenticateRequest(c, options);
+
+    if (result.kind === 'rejected') {
+      return authError(c, result);
+    }
+
+    if (result.kind === 'authenticated') {
+      setAuthContext(c, result.auth);
+    }
+
+    await next();
+  };
+};
+
+const authenticateRequest = async (
+  c: Context,
+  options: CreateAuthMiddlewareOptions
+): Promise<AuthResult> => {
+  const token = readBearerToken(c.req.raw) ?? options.ports.cookies.readSessionToken(c.req.raw);
+
+  if (!token) {
+    return { kind: 'missing' };
+  }
+
+  const now = options.ports.clock.now();
+  const claims = await options.ports.tokens.verifySessionToken(token);
+
+  if (!claims) {
+    return invalidSession();
+  }
+
+  const tokenHash = await options.ports.tokens.hashSecret(token);
+  const sessionRecord = await options.ports.sessions.findByTokenHash(tokenHash);
+
+  if (
+    !sessionRecord ||
+    sessionRecord.id !== claims.sessionId ||
+    sessionRecord.userId !== claims.userId ||
+    sessionRecord.revokedAt ||
+    sessionRecord.expiresAt <= now
+  ) {
+    return invalidSession();
+  }
+
+  const user = await options.ports.users.findById(claims.userId);
+
+  if (!user) {
+    return invalidSession();
+  }
+
+  const decision = await options.ports.accountPolicy.canAuthenticate(user, now);
+
+  if (!decision.allowed) {
+    return {
+      kind: 'rejected',
+      code: decision.code ?? 'forbidden',
+      message: decision.message ?? 'Authentication is not allowed for this account.',
+      status: decision.status === 401 ? 401 : 403,
+    };
+  }
+
+  const role = await options.ports.accountPolicy.resolveSessionRole(user, now);
+  const session = { ...claims, role };
+
+  await options.ports.sessions.touch(sessionRecord.id, now);
+
+  return {
+    kind: 'authenticated',
+    auth: {
+      role,
+      session,
+      sessionRecord,
+      token,
+      user,
+    },
+  };
+};
+
+const invalidSession = (): AuthResult => ({
+  kind: 'rejected',
+  code: 'invalid_session',
+  message: 'Session is invalid or expired.',
+  status: 401,
+});
+
+const readBearerToken = (request: Request): string | null => {
+  const header = request.headers.get('Authorization');
+
+  if (!header) {
+    return null;
+  }
+
+  const match = /^Bearer\s+(.+)$/i.exec(header);
+  return match?.[1]?.trim() || null;
+};
+
+const setAuthContext = (c: Context, auth: AuthHonoAuthContext): void => {
+  const typedContext = c as Context<AuthHonoMiddlewareEnv>;
+  typedContext.set('auth', auth);
+  typedContext.set('session', auth.session);
+  typedContext.set('user', auth.user);
+};
+
+const authError = (
+  c: Context,
+  error: { code: string; message: string; status: 401 | 403 }
+): Response => {
+  return c.json(
+    {
+      error: {
+        code: error.code,
+        message: error.message,
+      },
+    },
+    error.status
+  );
+};

package/src/ports.ts

@@ -0,0 +1,289 @@
+export type AuthHonoAccountStatus =
+  | 'active'
+  | 'pending_admin_approval'
+  | 'approval_expired_readonly'
+  | 'disabled_by_user'
+  | 'disabled_by_admin'
+  | (string & {});
+
+export type AuthHonoChallengeType = 'registration' | 'authentication';
+
+export interface AuthHonoDeviceInfo {
+  name?: string;
+  ipAddress?: string;
+  userAgent?: string;
+}
+
+export interface AuthHonoUserRecord {
+  id: string;
+  email: string | null;
+  displayName: string | null;
+  role: string;
+  emailVerified: boolean;
+  accountStatus: AuthHonoAccountStatus;
+  approvalDueAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface AuthHonoCreateUserInput {
+  email: string;
+  displayName?: string | null;
+  role: string;
+  emailVerified?: boolean;
+  accountStatus?: AuthHonoAccountStatus;
+  approvalDueAt?: Date | null;
+}
+
+export interface AuthHonoUpdateUserInput {
+  email?: string | null;
+  displayName?: string | null;
+  role?: string;
+  emailVerified?: boolean;
+  accountStatus?: AuthHonoAccountStatus;
+  approvalDueAt?: Date | null;
+  updatedAt?: Date;
+}
+
+export interface AuthHonoUserPort {
+  findById(userId: string): Promise<AuthHonoUserRecord | null>;
+  findByEmail(email: string): Promise<AuthHonoUserRecord | null>;
+  create(input: AuthHonoCreateUserInput): Promise<AuthHonoUserRecord>;
+  update(userId: string, input: AuthHonoUpdateUserInput): Promise<AuthHonoUserRecord | null>;
+  count(): Promise<number>;
+}
+
+export interface AuthHonoCredentialRecord {
+  id: string;
+  userId: string;
+  credentialId: string;
+  publicKey: Uint8Array | ArrayBuffer | string;
+  counter: number;
+  transports: string[] | null;
+  name: string | null;
+  deviceType: string | null;
+  backedUp: boolean | null;
+  lastUsedAt: Date | null;
+  createdAt: Date;
+  revokedAt: Date | null;
+}
+
+export interface AuthHonoCreateCredentialInput {
+  userId: string;
+  credentialId: string;
+  publicKey: Uint8Array | ArrayBuffer | string;
+  counter: number;
+  transports?: string[] | null;
+  name?: string | null;
+  deviceType?: string | null;
+  backedUp?: boolean | null;
+}
+
+export interface AuthHonoCredentialPort {
+  findById(credentialRecordId: string): Promise<AuthHonoCredentialRecord | null>;
+  findByCredentialId(credentialId: string): Promise<AuthHonoCredentialRecord | null>;
+  listForUser(userId: string): Promise<AuthHonoCredentialRecord[]>;
+  create(input: AuthHonoCreateCredentialInput): Promise<AuthHonoCredentialRecord>;
+  updateCounter(credentialId: string, counter: number, lastUsedAt?: Date): Promise<void>;
+  rename(credentialRecordId: string, userId: string, name: string): Promise<AuthHonoCredentialRecord | null>;
+  revoke(credentialRecordId: string, userId: string): Promise<boolean>;
+}
+
+export interface AuthHonoChallengeRecord {
+  id: string;
+  challenge: string;
+  userId: string | null;
+  type: AuthHonoChallengeType;
+  expiresAt: Date;
+  used: boolean;
+  createdAt: Date;
+}
+
+export interface AuthHonoCreateChallengeInput {
+  challenge: string;
+  userId?: string | null;
+  type: AuthHonoChallengeType;
+  expiresAt: Date;
+}
+
+export interface AuthHonoChallengePort {
+  create(input: AuthHonoCreateChallengeInput): Promise<AuthHonoChallengeRecord>;
+  findValid(challenge: string, type: AuthHonoChallengeType): Promise<AuthHonoChallengeRecord | null>;
+  markUsed(challenge: string): Promise<void>;
+  purgeExpired(now: Date): Promise<number>;
+}
+
+export interface AuthHonoSessionRecord {
+  id: string;
+  userId: string;
+  sessionTokenHash: string;
+  refreshTokenHash: string | null;
+  deviceName: string | null;
+  ipAddress: string | null;
+  userAgent: string | null;
+  mfaVerified: boolean;
+  expiresAt: Date;
+  createdAt: Date;
+  lastActivityAt: Date;
+  revokedAt: Date | null;
+}
+
+export interface AuthHonoCreateSessionInput {
+  id: string;
+  userId: string;
+  sessionTokenHash: string;
+  refreshTokenHash?: string | null;
+  deviceInfo?: AuthHonoDeviceInfo;
+  mfaVerified?: boolean;
+  expiresAt: Date;
+  now: Date;
+}
+
+export interface AuthHonoSessionPort {
+  create(input: AuthHonoCreateSessionInput): Promise<AuthHonoSessionRecord>;
+  findById(sessionId: string): Promise<AuthHonoSessionRecord | null>;
+  findByTokenHash(sessionTokenHash: string): Promise<AuthHonoSessionRecord | null>;
+  findByRefreshTokenHash(refreshTokenHash: string): Promise<AuthHonoSessionRecord | null>;
+  touch(sessionId: string, now: Date): Promise<void>;
+  updateTokens(input: {
+    expiresAt: Date;
+    refreshTokenHash: string;
+    sessionId: string;
+    sessionTokenHash: string;
+  }): Promise<AuthHonoSessionRecord | null>;
+  revoke(sessionId: string): Promise<boolean>;
+  revokeAllForUser(userId: string): Promise<number>;
+  listForUser(userId: string): Promise<AuthHonoSessionRecord[]>;
+}
+
+export interface AuthHonoEmailVerificationRecord {
+  id: string;
+  email: string;
+  codeHash: string;
+  verificationToken: string | null;
+  expiresAt: Date;
+  used: boolean;
+  createdAt: Date;
+}
+
+export interface AuthHonoEmailVerificationPort {
+  countRecent(email: string, since: Date): Promise<number>;
+  createCode(input: {
+    email: string;
+    codeHash: string;
+    expiresAt: Date;
+    now: Date;
+  }): Promise<AuthHonoEmailVerificationRecord>;
+  findLatestValidCode(email: string, codeHash: string, now: Date): Promise<AuthHonoEmailVerificationRecord | null>;
+  markUsedWithVerificationToken(id: string, verificationToken: string): Promise<void>;
+  verifyToken(email: string, verificationToken: string, now: Date): Promise<boolean>;
+}
+
+export interface AuthHonoMagicLinkRecord {
+  id: string;
+  tokenHash: string;
+  email: string;
+  userId: string | null;
+  expiresAt: Date;
+  used: boolean;
+  createdAt: Date;
+}
+
+export interface AuthHonoMagicLinkPort {
+  create(input: {
+    email: string;
+    tokenHash: string;
+    userId?: string | null;
+    expiresAt: Date;
+    now: Date;
+  }): Promise<AuthHonoMagicLinkRecord>;
+  findValidByTokenHash(tokenHash: string, now: Date): Promise<AuthHonoMagicLinkRecord | null>;
+  markUsed(id: string, userId?: string | null): Promise<void>;
+}
+
+export interface AuthHonoEmailDeliveryPort {
+  sendVerificationCode(input: { email: string; code: string; expiresAt: Date }): Promise<void>;
+  sendMagicLink(input: { email: string; token: string; expiresAt: Date; url: string }): Promise<void>;
+}
+
+export interface AuthHonoCookiePort {
+  readSessionToken(request: Request): string | null;
+  readRefreshToken(request: Request): string | null;
+  serializeSessionCookie(input: { token: string; expiresAt: Date }): string;
+  serializeRefreshCookie(input: { token: string; expiresAt: Date }): string;
+  serializeClearedSessionCookie(): string;
+  serializeClearedRefreshCookie(): string;
+}
+
+export interface AuthHonoSessionClaims {
+  userId: string;
+  sessionId: string;
+  role: string;
+  email?: string | null;
+  displayName?: string | null;
+}
+
+export interface AuthHonoTokenPort {
+  hashSecret(secret: string): Promise<string> | string;
+  signSessionToken(claims: AuthHonoSessionClaims, expiresAt: Date): Promise<string>;
+  verifySessionToken(token: string): Promise<AuthHonoSessionClaims | null>;
+  signVerificationToken(input: { email: string; expiresAt: Date }): Promise<string>;
+}
+
+export type AuthHonoAuditLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface AuthHonoAuditLogPort {
+  record(level: AuthHonoAuditLevel, event: string, fields?: Record<string, unknown>): Promise<void> | void;
+}
+
+export interface AuthHonoClockPort {
+  now(): Date;
+  addSeconds(date: Date, seconds: number): Date;
+}
+
+export interface AuthHonoRandomPort {
+  uuid(): string;
+  bytes(length: number): Uint8Array;
+  numericCode(length: number): string;
+  token(bytes: number): string;
+}
+
+export interface AuthHonoAccountPolicyDecision {
+  allowed: boolean;
+  status?: number;
+  code?: string;
+  message?: string;
+}
+
+export interface AuthHonoAccountPolicyPort {
+  normalizeEmail(email: string): string;
+  deriveDisplayName(email: string): string;
+  resolveUserVerification?(user: AuthHonoUserRecord): 'discouraged' | 'preferred' | 'required';
+  roleForNewUser(input: { email: string; isFirstUser: boolean }): Promise<string> | string;
+  statusForNewUser(input: { email: string; isFirstUser: boolean; now: Date }): Promise<{
+    accountStatus: AuthHonoAccountStatus;
+    approvalDueAt: Date | null;
+  }> | {
+    accountStatus: AuthHonoAccountStatus;
+    approvalDueAt: Date | null;
+  };
+  canAuthenticate(user: AuthHonoUserRecord, now: Date): Promise<AuthHonoAccountPolicyDecision> | AuthHonoAccountPolicyDecision;
+  resolveSessionRole(user: AuthHonoUserRecord, now: Date): Promise<string> | string;
+  afterUserCreated?(user: AuthHonoUserRecord): Promise<void> | void;
+}
+
+export interface AuthHonoPorts {
+  users: AuthHonoUserPort;
+  credentials: AuthHonoCredentialPort;
+  challenges: AuthHonoChallengePort;
+  sessions: AuthHonoSessionPort;
+  emailVerification: AuthHonoEmailVerificationPort;
+  magicLinks: AuthHonoMagicLinkPort;
+  emailDelivery: AuthHonoEmailDeliveryPort;
+  cookies: AuthHonoCookiePort;
+  tokens: AuthHonoTokenPort;
+  auditLog: AuthHonoAuditLogPort;
+  clock: AuthHonoClockPort;
+  random: AuthHonoRandomPort;
+  accountPolicy: AuthHonoAccountPolicyPort;
+}

package/src/route-handlers.ts

@@ -0,0 +1,182 @@
+import type { Context } from 'hono';
+import type { ContentfulStatusCode } from 'hono/utils/http-status';
+import { z } from 'zod';
+
+import type { AuthHonoEmailVerificationService } from './email-verification.js';
+import type { AuthHonoMagicLinkService, AuthHonoRequestMagicLinkResult } from './magic-link.js';
+import type { AuthHonoRouteHandlers } from './router.js';
+
+export interface CreateAuthEmailRouteHandlersOptions {
+  service: AuthHonoEmailVerificationService;
+}
+
+export interface CreateAuthMagicLinkRouteHandlersOptions {
+  formatRequestMagicLinkSuccess?: (
+    result: Extract<AuthHonoRequestMagicLinkResult, { success: true }>
+  ) => AuthHonoMagicLinkRequestSuccessResponse;
+  service: AuthHonoMagicLinkService;
+}
+
+export interface AuthHonoMagicLinkRequestSuccessResponse {
+  success: true;
+  [key: string]: unknown;
+}
+
+interface AuthHonoHttpServiceError {
+  code: string;
+  message: string;
+  status: number;
+}
+
+const requestEmailCodeSchema = z.object({
+  email: z.string().email(),
+});
+
+const verifyEmailCodeSchema = z.object({
+  code: z.string().regex(/^\d{6}$/),
+  email: z.string().email(),
+});
+
+const requestMagicLinkSchema = z.object({
+  email: z.string().email(),
+});
+
+const verifyMagicLinkSchema = z.object({
+  token: z.string().min(1),
+});
+
+export const createAuthEmailRouteHandlers = (
+  options: CreateAuthEmailRouteHandlersOptions
+): AuthHonoRouteHandlers => ({
+  async requestEmailCode(c) {
+    const input = await parseJson(c, requestEmailCodeSchema);
+
+    if (!input.ok) {
+      return invalidRequest(c, input.error);
+    }
+
+    const result = await options.service.requestEmailCode(input.value);
+
+    if (!result.success) {
+      return serviceError(c, result.error);
+    }
+
+    return c.json({
+      delivery: 'email',
+      expiresAt: result.expiresAt.toISOString(),
+      success: true,
+    });
+  },
+
+  async verifyEmailCode(c) {
+    const input = await parseJson(c, verifyEmailCodeSchema);
+
+    if (!input.ok) {
+      return invalidRequest(c, input.error);
+    }
+
+    const result = await options.service.verifyEmailCode(input.value);
+
+    if (!result.valid) {
+      return serviceError(c, result.error);
+    }
+
+    return c.json({
+      success: true,
+      verificationToken: result.verificationToken,
+    });
+  },
+});
+
+export const createAuthMagicLinkRouteHandlers = (
+  options: CreateAuthMagicLinkRouteHandlersOptions
+): AuthHonoRouteHandlers => ({
+  async requestMagicLink(c) {
+    const input = await parseJson(c, requestMagicLinkSchema);
+
+    if (!input.ok) {
+      return invalidRequest(c, input.error);
+    }
+
+    const result = await options.service.requestMagicLink(input.value);
+
+    if (!result.success) {
+      return serviceError(c, result.error);
+    }
+
+    return c.json(formatRequestMagicLinkSuccess(options, result));
+  },
+
+  async verifyMagicLink(c) {
+    const input = await parseJson(c, verifyMagicLinkSchema);
+
+    if (!input.ok) {
+      return invalidRequest(c, input.error);
+    }
+
+    const result = await options.service.verifyMagicLink(input.value);
+
+    if (!result.valid) {
+      return serviceError(c, result.error);
+    }
+
+    return c.json({
+      success: true,
+      user: {
+        displayName: result.user.displayName,
+        email: result.email,
+        id: result.user.id,
+        role: result.user.role,
+      },
+    });
+  },
+});
+
+const formatRequestMagicLinkSuccess = (
+  options: CreateAuthMagicLinkRouteHandlersOptions,
+  result: Extract<AuthHonoRequestMagicLinkResult, { success: true }>
+): AuthHonoMagicLinkRequestSuccessResponse =>
+  options.formatRequestMagicLinkSuccess
+    ? options.formatRequestMagicLinkSuccess(result)
+    : {
+        delivery: 'magic_link',
+        expiresAt: result.expiresAt.toISOString(),
+        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 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: AuthHonoHttpServiceError): Response =>
+  c.json(
+    {
+      error: {
+        code: error.code,
+        message: error.message,
+      },
+    },
+    error.status as ContentfulStatusCode
+  );