@sentropic/auth-hono 0.2.1

package/src/contracts.ts

@@ -0,0 +1,99 @@
+import type { AuthHonoPorts } from './ports.js';
+
+export const AUTH_HONO_AUTH_UI_METHODS = [
+  'requestEmailCode',
+  'verifyEmailCode',
+  'requestMagicLink',
+  'verifyMagicLink',
+  'createPasskeyRegistrationOptions',
+  'verifyPasskeyRegistration',
+  'createPasskeyAuthenticationOptions',
+  'verifyPasskeyAuthentication',
+  'refreshSession',
+  'logout',
+  'listCredentials',
+  'renameCredential',
+  'revokeCredential',
+] as const;
+
+export type AuthHonoAuthUiMethod = (typeof AUTH_HONO_AUTH_UI_METHODS)[number];
+
+export type AuthHonoHttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+
+export interface AuthHonoRouteContract {
+  method: AuthHonoHttpMethod;
+  path: string;
+}
+
+export const AUTH_HONO_ROUTE_MAP = {
+  requestEmailCode: {
+    method: 'POST',
+    path: '/email/verify-request',
+  },
+  verifyEmailCode: {
+    method: 'POST',
+    path: '/email/verify-code',
+  },
+  requestMagicLink: {
+    method: 'POST',
+    path: '/magic-link/request',
+  },
+  verifyMagicLink: {
+    method: 'POST',
+    path: '/magic-link/verify',
+  },
+  createPasskeyRegistrationOptions: {
+    method: 'POST',
+    path: '/register/options',
+  },
+  verifyPasskeyRegistration: {
+    method: 'POST',
+    path: '/register/verify',
+  },
+  createPasskeyAuthenticationOptions: {
+    method: 'POST',
+    path: '/login/options',
+  },
+  verifyPasskeyAuthentication: {
+    method: 'POST',
+    path: '/login/verify',
+  },
+  refreshSession: {
+    method: 'POST',
+    path: '/session/refresh',
+  },
+  logout: {
+    method: 'DELETE',
+    path: '/session',
+  },
+  listCredentials: {
+    method: 'GET',
+    path: '/credentials',
+  },
+  renameCredential: {
+    method: 'PUT',
+    path: '/credentials/:id',
+  },
+  revokeCredential: {
+    method: 'DELETE',
+    path: '/credentials/:id',
+  },
+} as const satisfies Record<AuthHonoAuthUiMethod, AuthHonoRouteContract>;
+
+export const AUTH_HONO_REQUIRED_PORTS = [
+  'users',
+  'credentials',
+  'challenges',
+  'sessions',
+  'emailVerification',
+  'magicLinks',
+  'emailDelivery',
+  'cookies',
+  'tokens',
+  'auditLog',
+  'clock',
+  'random',
+  'accountPolicy',
+] as const satisfies readonly (keyof AuthHonoPorts)[];
+
+export type AuthHonoRequiredPort = (typeof AUTH_HONO_REQUIRED_PORTS)[number];

package/src/credential-route-handlers.ts

@@ -0,0 +1,178 @@
+import type { Context } from 'hono';
+import { z } from 'zod';
+
+import type { AuthHonoCredentialPort, AuthHonoCredentialRecord } from './ports.js';
+import type { AuthHonoRouteHandlers } from './router.js';
+
+export interface AuthHonoCredentialRouteSession {
+  userId: string;
+}
+
+export type AuthHonoCredentialSessionResolver = (
+  c: Context
+) => Promise<AuthHonoCredentialRouteSession | null>;
+
+export interface CreateAuthCredentialRouteHandlersOptions {
+  credentials: AuthHonoCredentialPort;
+  resolveSession: AuthHonoCredentialSessionResolver;
+}
+
+const renameCredentialSchema = z.object({
+  deviceName: z.string().min(1).max(100),
+});
+
+export const createAuthCredentialRouteHandlers = (
+  options: CreateAuthCredentialRouteHandlersOptions
+): AuthHonoRouteHandlers => ({
+  async listCredentials(c) {
+    const session = await options.resolveSession(c);
+
+    if (!session) {
+      return authenticationRequired(c);
+    }
+
+    const credentials = await options.credentials.listForUser(session.userId);
+    return c.json({ credentials: credentials.map(toCredentialResponse) });
+  },
+
+  async renameCredential(c) {
+    const session = await options.resolveSession(c);
+
+    if (!session) {
+      return authenticationRequired(c);
+    }
+
+    const parsed = await parseJson(c, renameCredentialSchema);
+
+    if (!parsed.ok) {
+      return invalidInput(c, parsed.error);
+    }
+
+    const checked = await requireOwnedCredential(c, options, session.userId);
+
+    if (!checked.ok) {
+      return checked.response;
+    }
+
+    const renamed = await options.credentials.rename(
+      checked.credential.id,
+      session.userId,
+      parsed.value.deviceName
+    );
+
+    if (!renamed) {
+      return credentialNotFound(c);
+    }
+
+    return c.json({ credential: toCredentialResponse(renamed), success: true });
+  },
+
+  async revokeCredential(c) {
+    const session = await options.resolveSession(c);
+
+    if (!session) {
+      return authenticationRequired(c);
+    }
+
+    const checked = await requireOwnedCredential(c, options, session.userId);
+
+    if (!checked.ok) {
+      return checked.response;
+    }
+
+    const revoked = await options.credentials.revoke(checked.credential.id, session.userId);
+
+    if (!revoked) {
+      return credentialNotFound(c);
+    }
+
+    return c.json({ success: true });
+  },
+});
+
+const toCredentialResponse = (credential: AuthHonoCredentialRecord) => ({
+  backedUp: credential.backedUp,
+  counter: credential.counter,
+  createdAt: credential.createdAt.toISOString(),
+  credentialId: credential.credentialId,
+  deviceName: credential.name ?? 'Unnamed credential',
+  deviceType: credential.deviceType,
+  id: credential.id,
+  lastUsedAt: credential.lastUsedAt ? credential.lastUsedAt.toISOString() : null,
+  transports: credential.transports,
+});
+
+const requireOwnedCredential = async (
+  c: Context,
+  options: CreateAuthCredentialRouteHandlersOptions,
+  userId: string
+): Promise<{ credential: AuthHonoCredentialRecord; ok: true } | { ok: false; response: Response }> => {
+  const credentialId = c.req.param('id');
+
+  if (!credentialId) {
+    return { ok: false, response: credentialNotFound(c) };
+  }
+
+  const credential = await options.credentials.findById(credentialId);
+
+  if (!credential) {
+    return { ok: false, response: credentialNotFound(c) };
+  }
+
+  if (credential.userId !== userId) {
+    return { ok: false, response: forbidden(c) };
+  }
+
+  return { credential, ok: 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 authenticationRequired = (c: Context): Response =>
+  c.json(
+    {
+      error: {
+        code: 'authentication_required',
+        message: 'Authentication is required to access credentials.',
+      },
+    },
+    401
+  );
+
+const invalidInput = (c: Context, error: z.ZodError): Response =>
+  c.json(
+    {
+      error: {
+        code: 'invalid_input',
+        details: error.errors,
+        message: 'Invalid request data.',
+      },
+    },
+    400
+  );
+
+const credentialNotFound = (c: Context): Response =>
+  c.json({ error: { code: 'credential_not_found', message: 'Credential not found.' } }, 404);
+
+const forbidden = (c: Context): Response =>
+  c.json(
+    {
+      error: {
+        code: 'forbidden',
+        message: 'Credential does not belong to the authenticated user.',
+      },
+    },
+    403
+  );

package/src/email-verification.ts

@@ -0,0 +1,127 @@
+import type { AuthHonoPorts } from './ports.js';
+
+export interface CreateAuthEmailVerificationServiceOptions {
+  codeLength?: number;
+  codeTtlSeconds?: number;
+  maxRequestsPerWindow?: number;
+  ports: AuthHonoPorts;
+  verificationTokenTtlSeconds?: number;
+  windowSeconds?: number;
+}
+
+export interface AuthHonoRequestEmailCodeInput {
+  email: string;
+}
+
+export interface AuthHonoVerifyEmailCodeInput {
+  code: string;
+  email: string;
+}
+
+export type AuthHonoRequestEmailCodeResult =
+  | {
+      expiresAt: Date;
+      success: true;
+    }
+  | {
+      error: AuthHonoServiceError;
+      success: false;
+    };
+
+export type AuthHonoVerifyEmailCodeResult =
+  | {
+      valid: true;
+      verificationToken: string;
+    }
+  | {
+      error: AuthHonoServiceError;
+      valid: false;
+    };
+
+export interface AuthHonoServiceError {
+  code: string;
+  message: string;
+  status: number;
+}
+
+export interface AuthHonoEmailVerificationService {
+  requestEmailCode(input: AuthHonoRequestEmailCodeInput): Promise<AuthHonoRequestEmailCodeResult>;
+  verifyEmailCode(input: AuthHonoVerifyEmailCodeInput): Promise<AuthHonoVerifyEmailCodeResult>;
+}
+
+export const createAuthEmailVerificationService = (
+  options: CreateAuthEmailVerificationServiceOptions
+): AuthHonoEmailVerificationService => {
+  const codeLength = options.codeLength ?? 6;
+  const codeTtlSeconds = options.codeTtlSeconds ?? 10 * 60;
+  const maxRequestsPerWindow = options.maxRequestsPerWindow ?? 3;
+  const verificationTokenTtlSeconds = options.verificationTokenTtlSeconds ?? 15 * 60;
+  const windowSeconds = options.windowSeconds ?? 10 * 60;
+
+  return {
+    async requestEmailCode(input) {
+      const email = options.ports.accountPolicy.normalizeEmail(input.email);
+      const now = options.ports.clock.now();
+      const windowStart = options.ports.clock.addSeconds(now, -windowSeconds);
+      const recentCount = await options.ports.emailVerification.countRecent(email, windowStart);
+
+      if (recentCount >= maxRequestsPerWindow) {
+        return {
+          error: {
+            code: 'rate_limited',
+            message: 'Too many verification code requests.',
+            status: 429,
+          },
+          success: false,
+        };
+      }
+
+      const code = options.ports.random.numericCode(codeLength);
+      const codeHash = await options.ports.tokens.hashSecret(code);
+      const expiresAt = options.ports.clock.addSeconds(now, codeTtlSeconds);
+
+      await options.ports.emailVerification.createCode({
+        email,
+        codeHash,
+        expiresAt,
+        now,
+      });
+      await options.ports.emailDelivery.sendVerificationCode({ email, code, expiresAt });
+
+      return {
+        expiresAt,
+        success: true,
+      };
+    },
+
+    async verifyEmailCode(input) {
+      const email = options.ports.accountPolicy.normalizeEmail(input.email);
+      const codeHash = await options.ports.tokens.hashSecret(input.code);
+      const now = options.ports.clock.now();
+      const record = await options.ports.emailVerification.findLatestValidCode(email, codeHash, now);
+
+      if (!record || record.used || record.expiresAt <= now) {
+        return {
+          error: {
+            code: 'invalid_or_expired_code',
+            message: 'Verification code is invalid or expired.',
+            status: 400,
+          },
+          valid: false,
+        };
+      }
+
+      const verificationToken = await options.ports.tokens.signVerificationToken({
+        email,
+        expiresAt: options.ports.clock.addSeconds(now, verificationTokenTtlSeconds),
+      });
+
+      await options.ports.emailVerification.markUsedWithVerificationToken(record.id, verificationToken);
+
+      return {
+        valid: true,
+        verificationToken,
+      };
+    },
+  };
+};

package/src/index.ts

@@ -0,0 +1,14 @@
+export * from './contracts.js';
+export * from './credential-route-handlers.js';
+export * from './email-verification.js';
+export * from './magic-link.js';
+export * from './middleware.js';
+export * from './ports.js';
+export * from './route-handlers.js';
+export * from './router.js';
+export * from './session.js';
+export * from './session-route-handlers.js';
+export * from './webauthn-authentication.js';
+export * from './webauthn-authentication-route-handlers.js';
+export * from './webauthn-registration.js';
+export * from './webauthn-registration-route-handlers.js';

package/src/magic-link.ts

@@ -0,0 +1,167 @@
+import type { AuthHonoPorts, AuthHonoUserRecord } from './ports.js';
+
+export interface CreateAuthMagicLinkServiceOptions {
+  baseUrl: string;
+  ports: AuthHonoPorts;
+  tokenBytes?: number;
+  ttlSeconds?: number;
+}
+
+export interface AuthHonoRequestMagicLinkInput {
+  email: string;
+  userId?: string | null;
+}
+
+export interface AuthHonoVerifyMagicLinkInput {
+  token: string;
+}
+
+export type AuthHonoRequestMagicLinkResult =
+  | {
+      expiresAt: Date;
+      success: true;
+    }
+  | {
+      error: AuthHonoMagicLinkError;
+      success: false;
+    };
+
+export type AuthHonoVerifyMagicLinkResult =
+  | {
+      email: string;
+      user: AuthHonoUserRecord;
+      valid: true;
+    }
+  | {
+      error: AuthHonoMagicLinkError;
+      valid: false;
+    };
+
+export interface AuthHonoMagicLinkError {
+  code: string;
+  message: string;
+  status: number;
+}
+
+export interface AuthHonoMagicLinkService {
+  requestMagicLink(input: AuthHonoRequestMagicLinkInput): Promise<AuthHonoRequestMagicLinkResult>;
+  verifyMagicLink(input: AuthHonoVerifyMagicLinkInput): Promise<AuthHonoVerifyMagicLinkResult>;
+}
+
+export const createAuthMagicLinkService = (
+  options: CreateAuthMagicLinkServiceOptions
+): AuthHonoMagicLinkService => {
+  const tokenBytes = options.tokenBytes ?? 32;
+  const ttlSeconds = options.ttlSeconds ?? 10 * 60;
+
+  return {
+    async requestMagicLink(input) {
+      const email = options.ports.accountPolicy.normalizeEmail(input.email);
+      const now = options.ports.clock.now();
+      const token = options.ports.random.token(tokenBytes);
+      const tokenHash = await options.ports.tokens.hashSecret(token);
+      const expiresAt = options.ports.clock.addSeconds(now, ttlSeconds);
+      const url = buildMagicLinkUrl(options.baseUrl, token);
+
+      await options.ports.magicLinks.create({
+        email,
+        expiresAt,
+        now,
+        tokenHash,
+        userId: input.userId ?? null,
+      });
+      await options.ports.emailDelivery.sendMagicLink({ email, expiresAt, token, url });
+
+      return {
+        expiresAt,
+        success: true,
+      };
+    },
+
+    async verifyMagicLink(input) {
+      const tokenHash = await options.ports.tokens.hashSecret(input.token);
+      const now = options.ports.clock.now();
+      const link = await options.ports.magicLinks.findValidByTokenHash(tokenHash, now);
+
+      if (!link || link.used || link.expiresAt <= now) {
+        return invalidMagicLink();
+      }
+
+      const email = options.ports.accountPolicy.normalizeEmail(link.email);
+      const user = await resolveMagicLinkUser(options.ports, {
+        email,
+        now,
+        userId: link.userId,
+      });
+
+      if (!user) {
+        return invalidMagicLink();
+      }
+
+      await options.ports.magicLinks.markUsed(link.id, user.id);
+
+      return {
+        email,
+        user,
+        valid: true,
+      };
+    },
+  };
+};
+
+const resolveMagicLinkUser = async (
+  ports: AuthHonoPorts,
+  input: { email: string; now: Date; userId: string | null }
+): Promise<AuthHonoUserRecord | null> => {
+  const existingUser = input.userId
+    ? await ports.users.findById(input.userId)
+    : await ports.users.findByEmail(input.email);
+
+  if (existingUser) {
+    if (!existingUser.emailVerified || existingUser.email !== input.email || !existingUser.displayName) {
+      return (
+        (await ports.users.update(existingUser.id, {
+          displayName: existingUser.displayName ?? ports.accountPolicy.deriveDisplayName(input.email),
+          email: existingUser.email ?? input.email,
+          emailVerified: true,
+          updatedAt: input.now,
+        })) ?? existingUser
+      );
+    }
+
+    return existingUser;
+  }
+
+  const isFirstUser = (await ports.users.count()) === 0;
+  const status = await ports.accountPolicy.statusForNewUser({
+    email: input.email,
+    isFirstUser,
+    now: input.now,
+  });
+  const user = await ports.users.create({
+    accountStatus: status.accountStatus,
+    approvalDueAt: status.approvalDueAt,
+    displayName: ports.accountPolicy.deriveDisplayName(input.email),
+    email: input.email,
+    emailVerified: true,
+    role: await ports.accountPolicy.roleForNewUser({ email: input.email, isFirstUser }),
+  });
+
+  await ports.accountPolicy.afterUserCreated?.(user);
+
+  return user;
+};
+
+const invalidMagicLink = (): AuthHonoVerifyMagicLinkResult => ({
+  error: {
+    code: 'invalid_or_expired_magic_link',
+    message: 'Magic link is invalid or expired.',
+    status: 400,
+  },
+  valid: false,
+});
+
+const buildMagicLinkUrl = (baseUrl: string, token: string): string => {
+  const normalizedBaseUrl = baseUrl.replace(/\/+$/g, '');
+  return `${normalizedBaseUrl}/auth/magic-link/verify?token=${encodeURIComponent(token)}`;
+};