@sentropic/auth-hono 0.2.1

package/src/webauthn-authentication.ts

@@ -0,0 +1,211 @@
+import {
+  generateAuthenticationOptions,
+  verifyAuthenticationResponse,
+  type VerifiedAuthenticationResponse,
+  type WebAuthnCredential,
+} from '@simplewebauthn/server';
+import type {
+  AuthenticationResponseJSON,
+  AuthenticatorTransportFuture,
+  PublicKeyCredentialRequestOptionsJSON,
+  UserVerificationRequirement,
+} from '@simplewebauthn/server';
+
+import type { AuthHonoCredentialRecord, AuthHonoPorts } from './ports.js';
+import type { AuthHonoRelyingPartyConfig } from './webauthn-registration.js';
+
+export interface CreateAuthWebAuthnAuthenticationServiceOptions {
+  challengeBytes?: number;
+  challengeTtlSeconds?: number;
+  ports: AuthHonoPorts;
+  rp: AuthHonoRelyingPartyConfig;
+  timeoutMs?: number;
+  verifyAuthenticationResponse?: typeof verifyAuthenticationResponse;
+}
+
+export interface AuthHonoGenerateAuthenticationOptionsInput {
+  userId?: string;
+}
+
+export interface AuthHonoVerifyAuthenticationInput {
+  credential: AuthenticationResponseJSON;
+  expectedChallenge: string;
+}
+
+export type AuthHonoVerifyAuthenticationResult =
+  | {
+      credentialId: string;
+      userId: string;
+      verified: true;
+    }
+  | {
+      error: AuthHonoWebAuthnAuthenticationError;
+      verified: false;
+    };
+
+export interface AuthHonoWebAuthnAuthenticationError {
+  code: string;
+  message: string;
+  status: number;
+}
+
+export interface AuthHonoWebAuthnAuthenticationService {
+  generateAuthenticationOptions(
+    input: AuthHonoGenerateAuthenticationOptionsInput
+  ): Promise<PublicKeyCredentialRequestOptionsJSON>;
+  verifyAuthentication(input: AuthHonoVerifyAuthenticationInput): Promise<AuthHonoVerifyAuthenticationResult>;
+}
+
+export const createAuthWebAuthnAuthenticationService = (
+  options: CreateAuthWebAuthnAuthenticationServiceOptions
+): AuthHonoWebAuthnAuthenticationService => {
+  const challengeBytes = options.challengeBytes ?? 32;
+  const challengeTtlSeconds = options.challengeTtlSeconds ?? 5 * 60;
+  const timeoutMs = options.timeoutMs ?? 5 * 60_000;
+  const verifyResponse = options.verifyAuthenticationResponse ?? verifyAuthenticationResponse;
+
+  return {
+    async generateAuthenticationOptions(input) {
+      const user = input.userId ? await options.ports.users.findById(input.userId) : null;
+      const credentials = input.userId ? await options.ports.credentials.listForUser(input.userId) : [];
+      const challenge = options.ports.random.token(challengeBytes);
+      const challengeRecord = await options.ports.challenges.create({
+        challenge,
+        expiresAt: options.ports.clock.addSeconds(options.ports.clock.now(), challengeTtlSeconds),
+        type: 'authentication',
+        userId: input.userId ?? null,
+      });
+
+      const generatedOptions = await generateAuthenticationOptions({
+        allowCredentials:
+          credentials.length > 0
+            ? credentials.map((credential) => ({
+                id: credential.credentialId,
+                transports: toAuthenticatorTransports(credential.transports),
+              }))
+            : undefined,
+        challenge: challengeRecord.challenge,
+        rpID: options.rp.id,
+        timeout: timeoutMs,
+        userVerification: resolveUserVerification(options.ports, user),
+      });
+
+      generatedOptions.challenge = challengeRecord.challenge;
+      return generatedOptions;
+    },
+
+    async verifyAuthentication(input) {
+      const storedCredential = await options.ports.credentials.findByCredentialId(input.credential.id);
+
+      if (!storedCredential || storedCredential.revokedAt) {
+        return invalidAuthentication('credential_not_found', 'Credential was not found.', 401);
+      }
+
+      const challenge = await options.ports.challenges.findValid(
+        input.expectedChallenge,
+        'authentication'
+      );
+
+      if (!challenge || challenge.used || challenge.expiresAt <= options.ports.clock.now()) {
+        return invalidAuthentication('invalid_or_expired_challenge', 'Authentication challenge is invalid or expired.');
+      }
+
+      if (challenge.userId && challenge.userId !== storedCredential.userId) {
+        return invalidAuthentication('challenge_user_mismatch', 'Authentication challenge does not belong to this user.');
+      }
+
+      const user = await options.ports.users.findById(storedCredential.userId);
+
+      if (!user) {
+        return invalidAuthentication('user_not_found', 'Credential user was not found.', 404);
+      }
+
+      const requireUserVerification = resolveUserVerification(options.ports, user) === 'required';
+      const verification = await verifyResponse({
+        credential: toWebAuthnCredential(storedCredential),
+        expectedChallenge: input.expectedChallenge,
+        expectedOrigin: options.rp.expectedOrigins,
+        expectedRPID: options.rp.id,
+        requireUserVerification,
+        response: input.credential,
+      });
+
+      if (!verification.verified) {
+        return invalidAuthentication('authentication_verification_failed', 'Authentication verification failed.', 401);
+      }
+
+      if (requireUserVerification && !verification.authenticationInfo.userVerified) {
+        return invalidAuthentication('user_verification_required', 'User verification is required.', 403);
+      }
+
+      const now = options.ports.clock.now();
+      await options.ports.credentials.updateCounter(
+        storedCredential.credentialId,
+        verification.authenticationInfo.newCounter,
+        now
+      );
+      await options.ports.challenges.markUsed(input.expectedChallenge);
+
+      return {
+        credentialId: storedCredential.credentialId,
+        userId: storedCredential.userId,
+        verified: true,
+      };
+    },
+  };
+};
+
+const toWebAuthnCredential = (credential: AuthHonoCredentialRecord): WebAuthnCredential => ({
+  counter: credential.counter,
+  id: credential.credentialId,
+  publicKey: toUint8Array(credential.publicKey),
+  transports: toAuthenticatorTransports(credential.transports),
+});
+
+const toAuthenticatorTransports = (
+  transports: string[] | null
+): AuthenticatorTransportFuture[] | undefined => {
+  if (!transports || transports.length === 0) {
+    return undefined;
+  }
+
+  return transports as AuthenticatorTransportFuture[];
+};
+
+const toUint8Array = (value: Uint8Array | ArrayBuffer | string): Uint8Array => {
+  if (value instanceof Uint8Array) {
+    return value;
+  }
+
+  if (value instanceof ArrayBuffer) {
+    return new Uint8Array(value);
+  }
+
+  return new TextEncoder().encode(value);
+};
+
+const resolveUserVerification = (
+  ports: AuthHonoPorts,
+  user: Awaited<ReturnType<AuthHonoPorts['users']['findById']>>
+): UserVerificationRequirement => {
+  if (!user) {
+    return 'preferred';
+  }
+
+  return ports.accountPolicy.resolveUserVerification?.(user) ?? 'preferred';
+};
+
+const invalidAuthentication = (
+  code: string,
+  message: string,
+  status = 400
+): AuthHonoVerifyAuthenticationResult => ({
+  error: {
+    code,
+    message,
+    status,
+  },
+  verified: false,
+});
+
+export type AuthHonoVerifiedAuthenticationResponse = VerifiedAuthenticationResponse;

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

@@ -0,0 +1,248 @@
+import type { RegistrationResponseJSON } from '@simplewebauthn/server';
+import type { Context } from 'hono';
+import type { ContentfulStatusCode } from 'hono/utils/http-status';
+import { z } from 'zod';
+
+import type {
+  AuthHonoGenerateRegistrationOptionsInput,
+  AuthHonoWebAuthnRegistrationService,
+} from './webauthn-registration.js';
+import type { AuthHonoRouteHandlers } from './router.js';
+
+export interface CreateAuthWebAuthnRegistrationRouteHandlersOptions {
+  finalizeRegistration?: AuthHonoFinalizeRegistration;
+  prepareRegistrationOptions: AuthHonoPrepareRegistrationOptions;
+  resolveRegistrationUser: AuthHonoResolveRegistrationUser;
+  service: AuthHonoWebAuthnRegistrationService;
+}
+
+export type AuthHonoPrepareRegistrationOptions = (
+  input: AuthHonoRegistrationOptionsRequest,
+  c: Context
+) =>
+  | Promise<AuthHonoPreparedRegistrationOptions | AuthHonoRouteHandlerError>
+  | AuthHonoPreparedRegistrationOptions
+  | AuthHonoRouteHandlerError;
+
+export type AuthHonoResolveRegistrationUser = (
+  input: AuthHonoRegistrationVerifyRequest,
+  c: Context
+) =>
+  | Promise<AuthHonoResolvedRegistrationUser | AuthHonoRouteHandlerError>
+  | AuthHonoResolvedRegistrationUser
+  | AuthHonoRouteHandlerError;
+
+export type AuthHonoFinalizeRegistration = (
+  result: AuthHonoFinalizeRegistrationInput,
+  c: Context
+) => Response | Promise<Response>;
+
+export interface AuthHonoFinalizeRegistrationInput {
+  credentialId: string;
+  request: AuthHonoRegistrationVerifyRequest;
+  userId: string;
+}
+
+export interface AuthHonoRegistrationOptionsRequest {
+  deviceName?: string;
+  email: string;
+  verificationToken?: string;
+}
+
+export interface AuthHonoRegistrationVerifyRequest {
+  credential: RegistrationResponseJSON;
+  deviceName?: string;
+  email: string;
+  userId: string;
+  verificationToken: string;
+}
+
+export interface AuthHonoPreparedRegistrationOptions {
+  serviceInput: AuthHonoGenerateRegistrationOptionsInput;
+  userId: string;
+}
+
+export interface AuthHonoResolvedRegistrationUser {
+  userId: string;
+}
+
+export interface AuthHonoRouteHandlerError {
+  error: {
+    code: string;
+    message: string;
+    status: ContentfulStatusCode;
+  };
+}
+
+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 registrationOptionsSchema = z.object({
+  deviceName: z.string().max(100).optional(),
+  email: z.string().email(),
+  verificationToken: z.string().optional(),
+});
+
+const registrationVerifySchema = z.object({
+  credential: z.custom<RegistrationResponseJSON>(
+    (value) => Boolean(value && typeof value === 'object' && 'response' in value)
+  ),
+  deviceName: z.string().max(100).optional(),
+  email: z.string().email(),
+  userId: z.string().min(1),
+  verificationToken: z.string().min(1),
+});
+
+export const createAuthWebAuthnRegistrationRouteHandlers = (
+  options: CreateAuthWebAuthnRegistrationRouteHandlersOptions
+): AuthHonoRouteHandlers => ({
+  async createPasskeyRegistrationOptions(c) {
+    const input = await parseJson(c, registrationOptionsSchema);
+
+    if (!input.ok) {
+      return invalidRequest(c, input.error);
+    }
+
+    const prepared = await options.prepareRegistrationOptions(input.value, c);
+
+    if (isRouteHandlerError(prepared)) {
+      return simpleError(c, prepared.error.status, prepared.error.code, prepared.error.message);
+    }
+
+    const registrationOptions = await options.service.generateRegistrationOptions(
+      prepared.serviceInput
+    );
+
+    return c.json({
+      options: registrationOptions,
+      userId: prepared.userId,
+    });
+  },
+
+  async verifyPasskeyRegistration(c) {
+    const input = await parseJson(c, registrationVerifySchema);
+
+    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 registrationUser = await options.resolveRegistrationUser(input.value, c);
+
+    if (isRouteHandlerError(registrationUser)) {
+      return simpleError(
+        c,
+        registrationUser.error.status,
+        registrationUser.error.code,
+        registrationUser.error.message
+      );
+    }
+
+    const result = await options.service.verifyRegistration({
+      credential: input.value.credential,
+      deviceName: input.value.deviceName,
+      expectedChallenge: challenge,
+      userId: registrationUser.userId,
+    });
+
+    if (!result.verified) {
+      return serviceError(c, result.error);
+    }
+
+    if (options.finalizeRegistration) {
+      return options.finalizeRegistration(
+        {
+          credentialId: result.credentialId,
+          request: input.value,
+          userId: registrationUser.userId,
+        },
+        c
+      );
+    }
+
+    return c.json({
+      credentialId: result.credentialId,
+      success: true,
+      userId: registrationUser.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: RegistrationResponseJSON): 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
+  );

package/src/webauthn-registration.ts

@@ -0,0 +1,204 @@
+import {
+  generateRegistrationOptions,
+  verifyRegistrationResponse,
+  type VerifiedRegistrationResponse,
+} from '@simplewebauthn/server';
+import type {
+  AttestationConveyancePreference,
+  AuthenticatorTransportFuture,
+  PublicKeyCredentialCreationOptionsJSON,
+  RegistrationResponseJSON,
+  UserVerificationRequirement,
+} from '@simplewebauthn/server';
+
+import type { AuthHonoPorts } from './ports.js';
+
+export interface AuthHonoRelyingPartyConfig {
+  expectedOrigins: string[];
+  id: string;
+  name: string;
+}
+
+export interface CreateAuthWebAuthnRegistrationServiceOptions {
+  attestation?: AttestationConveyancePreference;
+  challengeBytes?: number;
+  challengeTtlSeconds?: number;
+  ports: AuthHonoPorts;
+  rp: AuthHonoRelyingPartyConfig;
+  timeoutMs?: number;
+  verifyRegistrationResponse?: typeof verifyRegistrationResponse;
+}
+
+export interface AuthHonoGenerateRegistrationOptionsInput {
+  userDisplayName: string;
+  userId?: string;
+  userName: string;
+}
+
+export interface AuthHonoVerifyRegistrationInput {
+  credential: RegistrationResponseJSON;
+  deviceName?: string;
+  expectedChallenge: string;
+  userId: string;
+}
+
+export type AuthHonoVerifyRegistrationResult =
+  | {
+      credentialId: string;
+      verified: true;
+    }
+  | {
+      error: AuthHonoWebAuthnRegistrationError;
+      verified: false;
+    };
+
+export interface AuthHonoWebAuthnRegistrationError {
+  code: string;
+  message: string;
+  status: number;
+}
+
+export interface AuthHonoWebAuthnRegistrationService {
+  generateRegistrationOptions(
+    input: AuthHonoGenerateRegistrationOptionsInput
+  ): Promise<PublicKeyCredentialCreationOptionsJSON>;
+  verifyRegistration(input: AuthHonoVerifyRegistrationInput): Promise<AuthHonoVerifyRegistrationResult>;
+}
+
+export const createAuthWebAuthnRegistrationService = (
+  options: CreateAuthWebAuthnRegistrationServiceOptions
+): AuthHonoWebAuthnRegistrationService => {
+  const challengeBytes = options.challengeBytes ?? 32;
+  const challengeTtlSeconds = options.challengeTtlSeconds ?? 5 * 60;
+  const timeoutMs = options.timeoutMs ?? 60_000;
+  const verifyResponse = options.verifyRegistrationResponse ?? verifyRegistrationResponse;
+
+  return {
+    async generateRegistrationOptions(input) {
+      const user = input.userId ? await options.ports.users.findById(input.userId) : null;
+      const existingCredentials = input.userId
+        ? await options.ports.credentials.listForUser(input.userId)
+        : [];
+      const challenge = options.ports.random.token(challengeBytes);
+      const challengeRecord = await options.ports.challenges.create({
+        challenge,
+        expiresAt: options.ports.clock.addSeconds(options.ports.clock.now(), challengeTtlSeconds),
+        type: 'registration',
+        userId: input.userId ?? null,
+      });
+
+      const generatedOptions = await generateRegistrationOptions({
+        attestationType: normalizeAttestation(options.attestation),
+        authenticatorSelection: {
+          residentKey: 'preferred',
+          userVerification: resolveUserVerification(options.ports, user),
+        },
+        challenge: challengeRecord.challenge,
+        excludeCredentials: existingCredentials.map((credential) => ({
+          id: credential.credentialId,
+          transports: toAuthenticatorTransports(credential.transports),
+        })),
+        rpID: options.rp.id,
+        rpName: options.rp.name,
+        timeout: timeoutMs,
+        userDisplayName: input.userDisplayName,
+        userName: input.userName,
+      });
+
+      generatedOptions.challenge = challengeRecord.challenge;
+      return generatedOptions;
+    },
+
+    async verifyRegistration(input) {
+      const challenge = await options.ports.challenges.findValid(
+        input.expectedChallenge,
+        'registration'
+      );
+
+      if (!challenge || challenge.used || challenge.expiresAt <= options.ports.clock.now()) {
+        return invalidRegistration('invalid_or_expired_challenge', 'Registration challenge is invalid or expired.');
+      }
+
+      if (challenge.userId && challenge.userId !== input.userId) {
+        return invalidRegistration('challenge_user_mismatch', 'Registration challenge does not belong to this user.');
+      }
+
+      const verification = await verifyResponse({
+        expectedChallenge: input.expectedChallenge,
+        expectedOrigin: options.rp.expectedOrigins,
+        expectedRPID: options.rp.id,
+        requireUserVerification: false,
+        response: input.credential,
+      });
+
+      if (!verification.verified || !verification.registrationInfo?.credential) {
+        return invalidRegistration('registration_verification_failed', 'Registration verification failed.');
+      }
+
+      const credential = verification.registrationInfo.credential;
+      const credentialId = credential.id;
+      const existing = await options.ports.credentials.findByCredentialId(credentialId);
+
+      if (existing && !existing.revokedAt) {
+        return invalidRegistration('duplicate_credential', 'Credential is already registered.', 409);
+      }
+
+      await options.ports.credentials.create({
+        backedUp: verification.registrationInfo.credentialBackedUp,
+        counter: credential.counter,
+        credentialId,
+        deviceType: verification.registrationInfo.credentialDeviceType,
+        name: input.deviceName ?? verification.registrationInfo.credentialDeviceType ?? 'Unknown Device',
+        publicKey: credential.publicKey,
+        transports: input.credential.response.transports ?? [],
+        userId: input.userId,
+      });
+      await options.ports.challenges.markUsed(input.expectedChallenge);
+
+      return {
+        credentialId,
+        verified: true,
+      };
+    },
+  };
+};
+
+const toAuthenticatorTransports = (
+  transports: string[] | null
+): AuthenticatorTransportFuture[] => (transports ?? []) as AuthenticatorTransportFuture[];
+
+const normalizeAttestation = (
+  attestation: AttestationConveyancePreference | undefined
+): 'none' | 'direct' | 'enterprise' | undefined => {
+  if (attestation === 'indirect') {
+    return 'none';
+  }
+
+  return attestation as 'none' | 'direct' | 'enterprise' | undefined;
+};
+
+const resolveUserVerification = (
+  ports: AuthHonoPorts,
+  user: Awaited<ReturnType<AuthHonoPorts['users']['findById']>>
+): UserVerificationRequirement => {
+  if (!user) {
+    return 'preferred';
+  }
+
+  return ports.accountPolicy.resolveUserVerification?.(user) ?? 'preferred';
+};
+
+const invalidRegistration = (
+  code: string,
+  message: string,
+  status = 400
+): AuthHonoVerifyRegistrationResult => ({
+  error: {
+    code,
+    message,
+    status,
+  },
+  verified: false,
+});
+
+export type AuthHonoVerifiedRegistrationResponse = VerifiedRegistrationResponse;