@exvio/os-backend-core 0.4.0

package/src/auth/passkey.ts

@@ -0,0 +1,760 @@
+import { AuthError } from './errors.ts'
+
+export const PASSKEY_CHALLENGE_TTL_SECONDS = 5 * 60
+export const PASSKEY_RECENT_AUTH_MAX_AGE_MS = 10 * 60 * 1_000
+
+const MAX_RECORD_BYTES = 64 * 1024
+const AUTH_TOKEN_PATTERN = /^pca_v1_[A-Za-z0-9_-]{43}$/
+const CHALLENGE_PATTERN = /^[A-Za-z0-9_-]{16,2048}$/
+const CREDENTIAL_ID_PATTERN = /^[A-Za-z0-9_-]{1,500}$/
+const SHA256_BASE64URL_PATTERN = /^[A-Za-z0-9_-]{43}$/
+const KEY_PREFIX_PATTERN = /^[A-Za-z0-9:_-]{1,96}$/
+const encoder = new TextEncoder()
+
+export type PasskeyChallengePurpose = 'register' | 'authenticate'
+
+export interface PasskeyChallengeStore {
+  put(key: string, value: string, ttlSeconds: number): Promise<void>
+  putIfAbsent(key: string, value: string, ttlSeconds: number): Promise<boolean>
+  /** Must atomically return and remove the stored value. */
+  take(key: string): Promise<string | null>
+}
+
+interface PasskeyChallengeBase {
+  readonly version: 1
+  readonly purpose: PasskeyChallengePurpose
+  readonly challenge: string
+  readonly tenantId: number
+  readonly rpID: string
+  readonly origin: string
+  readonly issuedAt: number
+  readonly expiresAt: number
+}
+
+export interface RegistrationPasskeyChallenge extends PasskeyChallengeBase {
+  readonly purpose: 'register'
+  readonly userId: number
+  readonly initiatingSessionHash: string
+  readonly authenticatedAt: number
+  readonly excludedCredentialIds: readonly string[]
+}
+
+export interface AuthenticationPasskeyChallenge extends PasskeyChallengeBase {
+  readonly purpose: 'authenticate'
+  readonly userId: number | null
+  readonly allowedCredentialIds: readonly string[]
+}
+
+export class PasskeyAuthError extends AuthError {
+  constructor() {
+    super({ code: 'invalid_passkey_challenge', status: 400 })
+    this.name = 'PasskeyAuthError'
+  }
+}
+
+export interface PasskeyChallengeManager {
+  issueRegistration(input: {
+    readonly challenge: string
+    readonly tenantId: number
+    readonly userId: number
+    readonly initiatingSessionId: string
+    readonly authenticatedAt: number
+    readonly rpID: string
+    readonly origin: string
+    readonly excludedCredentialIds: readonly string[]
+  }): Promise<void>
+  takeRegistration(expected: {
+    readonly tenantId: number
+    readonly userId: number
+    readonly initiatingSessionId: string
+    readonly authenticatedAt: number
+    readonly rpID: string
+    readonly origin: string
+  }): Promise<RegistrationPasskeyChallenge>
+  issueAuthentication(input: {
+    readonly challenge: string
+    readonly tenantId: number
+    readonly userId: number | null
+    readonly rpID: string
+    readonly origin: string
+    readonly allowedCredentialIds: readonly string[]
+  }): Promise<string>
+  takeAuthentication(expected: {
+    readonly token: string
+    readonly tenantId: number
+    readonly rpID: string
+    readonly origin: string
+    readonly credentialId: string
+  }): Promise<AuthenticationPasskeyChallenge>
+}
+
+export interface CreatePasskeyChallengeManagerOptions {
+  readonly store: PasskeyChallengeStore
+  readonly now?: () => number
+  readonly generateToken?: () => string
+  readonly ttlSeconds?: number
+  readonly recentAuthMaxAgeMs?: number
+  readonly registrationKeyPrefix?: string
+  readonly authenticationKeyPrefix?: string
+  readonly maxSerializedBytes?: number
+}
+
+export function createPasskeyChallengeManager(
+  options: CreatePasskeyChallengeManagerOptions,
+): PasskeyChallengeManager {
+  if (
+    !isObject(options)
+    || !isObject(options.store)
+    || typeof options.store.put !== 'function'
+    || typeof options.store.putIfAbsent !== 'function'
+    || typeof options.store.take !== 'function'
+  ) invalidInput()
+
+  const ttlSeconds = options.ttlSeconds ?? PASSKEY_CHALLENGE_TTL_SECONDS
+  const recentAuthMaxAgeMs = options.recentAuthMaxAgeMs ?? PASSKEY_RECENT_AUTH_MAX_AGE_MS
+  const maxSerializedBytes = options.maxSerializedBytes ?? MAX_RECORD_BYTES
+  const registrationKeyPrefix = options.registrationKeyPrefix ?? 'passkey:reg:v1:'
+  const authenticationKeyPrefix = options.authenticationKeyPrefix ?? 'passkey:auth:v1:'
+  const now = options.now ?? Date.now
+  const generateToken = options.generateToken ?? createAuthenticationToken
+
+  if (
+    !Number.isSafeInteger(ttlSeconds)
+    || ttlSeconds < 30
+    || ttlSeconds > 600
+    || !Number.isSafeInteger(recentAuthMaxAgeMs)
+    || recentAuthMaxAgeMs < 60_000
+    || recentAuthMaxAgeMs > 3_600_000
+    || !Number.isSafeInteger(maxSerializedBytes)
+    || maxSerializedBytes < 1_024
+    || maxSerializedBytes > 131_072
+    || typeof now !== 'function'
+    || typeof generateToken !== 'function'
+    || !KEY_PREFIX_PATTERN.test(registrationKeyPrefix)
+    || !KEY_PREFIX_PATTERN.test(authenticationKeyPrefix)
+  ) invalidInput()
+
+  const ttlMs = ttlSeconds * 1_000
+  if (!Number.isSafeInteger(ttlMs)) invalidInput()
+
+  const snapshot = Object.freeze({
+    put: options.store.put.bind(options.store),
+    putIfAbsent: options.store.putIfAbsent.bind(options.store),
+    take: options.store.take.bind(options.store),
+    ttlSeconds,
+    ttlMs,
+    recentAuthMaxAgeMs,
+    maxSerializedBytes,
+    registrationKeyPrefix,
+    authenticationKeyPrefix,
+    now,
+    generateToken,
+  })
+
+  const registrationKey = async (
+    tenantId: number,
+    userId: number,
+    sessionHash: string,
+  ): Promise<string> => `${snapshot.registrationKeyPrefix}${tenantId}:${userId}:${sessionHash}`
+
+  const authenticationKey = async (token: string): Promise<string> => (
+    `${snapshot.authenticationKeyPrefix}${await sha256Base64Url(token)}`
+  )
+
+  const manager: PasskeyChallengeManager = {
+    async issueRegistration(input): Promise<void> {
+      assertIssueRegistration(input)
+      const issuedAt = checkedNow(snapshot.now)
+      assertAuthenticationTime(input.authenticatedAt, issuedAt, snapshot.recentAuthMaxAgeMs)
+      const expiresAt = checkedExpiry(issuedAt, snapshot.ttlMs)
+      const initiatingSessionHash = await sha256Base64Url(input.initiatingSessionId)
+      const record: RegistrationPasskeyChallenge = Object.freeze({
+        version: 1,
+        purpose: 'register',
+        challenge: input.challenge,
+        tenantId: input.tenantId,
+        userId: input.userId,
+        initiatingSessionHash,
+        authenticatedAt: input.authenticatedAt,
+        rpID: input.rpID,
+        origin: input.origin,
+        excludedCredentialIds: Object.freeze(validateCredentialIds(input.excludedCredentialIds)),
+        issuedAt,
+        expiresAt,
+      })
+      try {
+        await snapshot.put(
+          await registrationKey(input.tenantId, input.userId, initiatingSessionHash),
+          encodeRecord(record, snapshot.maxSerializedBytes),
+          snapshot.ttlSeconds,
+        )
+      } catch (error) {
+        if (error instanceof AuthError) throw error
+        storeUnavailable()
+      }
+    },
+
+    async takeRegistration(expected): Promise<RegistrationPasskeyChallenge> {
+      let currentTime: number
+      let initiatingSessionHash: string
+      try {
+        assertConsumeRegistration(expected)
+        currentTime = checkedNow(snapshot.now)
+        initiatingSessionHash = await sha256Base64Url(expected.initiatingSessionId)
+      } catch {
+        throw new PasskeyAuthError()
+      }
+
+      let raw: string | null
+      try {
+        raw = await snapshot.take(await registrationKey(
+          expected.tenantId,
+          expected.userId,
+          initiatingSessionHash,
+        ))
+      } catch {
+        storeUnavailable()
+      }
+      const record = parseRecord(raw, currentTime, snapshot.ttlMs, snapshot.maxSerializedBytes)
+      if (
+        record.purpose !== 'register'
+        || record.tenantId !== expected.tenantId
+        || record.userId !== expected.userId
+        || record.initiatingSessionHash !== initiatingSessionHash
+        || record.authenticatedAt !== expected.authenticatedAt
+        || currentTime - record.authenticatedAt > snapshot.recentAuthMaxAgeMs
+        || record.rpID !== expected.rpID
+        || record.origin !== expected.origin
+      ) throw new PasskeyAuthError()
+      return record
+    },
+
+    async issueAuthentication(input): Promise<string> {
+      assertIssueAuthentication(input)
+      const issuedAt = checkedNow(snapshot.now)
+      const record: AuthenticationPasskeyChallenge = Object.freeze({
+        version: 1,
+        purpose: 'authenticate',
+        challenge: input.challenge,
+        tenantId: input.tenantId,
+        userId: input.userId,
+        rpID: input.rpID,
+        origin: input.origin,
+        allowedCredentialIds: Object.freeze(validateCredentialIds(input.allowedCredentialIds)),
+        issuedAt,
+        expiresAt: checkedExpiry(issuedAt, snapshot.ttlMs),
+      })
+      const encoded = encodeRecord(record, snapshot.maxSerializedBytes)
+      for (let attempt = 0; attempt < 3; attempt += 1) {
+        let token: string
+        try {
+          token = snapshot.generateToken()
+        } catch {
+          invalidInput(500)
+        }
+        if (!AUTH_TOKEN_PATTERN.test(token)) invalidInput(500)
+        try {
+          const reserved = await snapshot.putIfAbsent(
+            await authenticationKey(token),
+            encoded,
+            snapshot.ttlSeconds,
+          )
+          if (typeof reserved !== 'boolean') storeUnavailable()
+          if (reserved) return token
+        } catch {
+          storeUnavailable()
+        }
+      }
+      throw new AuthError({ code: 'auth_store_unavailable', status: 503, retryable: true })
+    },
+
+    async takeAuthentication(expected): Promise<AuthenticationPasskeyChallenge> {
+      if (!isObject(expected) || typeof expected.token !== 'string' || !AUTH_TOKEN_PATTERN.test(expected.token)) {
+        throw new PasskeyAuthError()
+      }
+
+      let raw: string | null
+      try {
+        raw = await snapshot.take(await authenticationKey(expected.token))
+      } catch {
+        storeUnavailable()
+      }
+      const record = parseRecord(raw, checkedNow(snapshot.now), snapshot.ttlMs, snapshot.maxSerializedBytes)
+      try {
+        assertPositiveTenantId(expected.tenantId)
+        assertRpBinding(expected.rpID, expected.origin)
+        assertCredentialId(expected.credentialId)
+      } catch {
+        throw new PasskeyAuthError()
+      }
+      if (
+        record.purpose !== 'authenticate'
+        || record.tenantId !== expected.tenantId
+        || record.rpID !== expected.rpID
+        || record.origin !== expected.origin
+        || (record.allowedCredentialIds.length > 0
+          && !record.allowedCredentialIds.includes(expected.credentialId))
+      ) throw new PasskeyAuthError()
+      return record
+    },
+  }
+  return Object.freeze(manager)
+}
+
+export interface PasskeyRateLimitStoreInput {
+  readonly key: string
+  readonly cutoff: number
+  readonly now: number
+  readonly member: string
+  readonly limit: number
+  readonly ttlSeconds: number
+}
+
+export interface PasskeyRateLimitStoreResult {
+  readonly allowed: boolean
+  readonly remaining: number
+  readonly oldestTimestamp: number
+}
+
+export interface PasskeyRateLimitStore {
+  take(input: PasskeyRateLimitStoreInput): Promise<PasskeyRateLimitStoreResult>
+}
+
+export interface PasskeyRateLimitResult {
+  readonly allowed: boolean
+  readonly remaining: number
+  readonly retryAfterSeconds: number
+}
+
+export interface PasskeyRateLimiter {
+  take(input: {
+    readonly tenantId: number
+    readonly purpose: 'start' | 'finish'
+    readonly scope: 'client' | 'tenant'
+    readonly subject: string
+    readonly limit: number
+    readonly windowSeconds: number
+  }): Promise<PasskeyRateLimitResult>
+}
+
+export function createPasskeyRateLimiter(options: {
+  readonly store: PasskeyRateLimitStore
+  readonly now?: () => number
+  readonly generateMember?: () => string
+  readonly keyPrefix?: string
+}): PasskeyRateLimiter {
+  if (!isObject(options) || !isObject(options.store) || typeof options.store.take !== 'function') {
+    invalidInput()
+  }
+  const now = options.now ?? Date.now
+  const generateMember = options.generateMember ?? (() => crypto.randomUUID())
+  const keyPrefix = options.keyPrefix ?? 'passkey:auth:rate:v1:'
+  if (typeof now !== 'function' || typeof generateMember !== 'function' || !KEY_PREFIX_PATTERN.test(keyPrefix)) {
+    invalidInput()
+  }
+  const take = options.store.take.bind(options.store)
+
+  const limiter: PasskeyRateLimiter = {
+    async take(input): Promise<PasskeyRateLimitResult> {
+      if (!isObject(input)) invalidInput()
+      assertPositiveTenantId(input.tenantId)
+      if (input.purpose !== 'start' && input.purpose !== 'finish') invalidInput()
+      if (input.scope !== 'client' && input.scope !== 'tenant') invalidInput()
+      if (typeof input.subject !== 'string' || input.subject.length === 0 || input.subject.length > 512) invalidInput()
+      if (!Number.isSafeInteger(input.limit) || input.limit <= 0) invalidInput()
+      if (!Number.isSafeInteger(input.windowSeconds) || input.windowSeconds <= 0) invalidInput()
+
+      const currentTime = checkedNow(now)
+      const windowMs = input.windowSeconds * 1_000
+      if (!Number.isSafeInteger(windowMs)) invalidInput()
+      let member: string
+      try {
+        member = generateMember()
+      } catch {
+        invalidInput(500)
+      }
+      if (typeof member !== 'string' || member.length === 0 || member.length > 256) invalidInput(500)
+
+      const subjectHash = await sha256Base64Url(`${input.scope}:${input.subject}`)
+      let result: PasskeyRateLimitStoreResult
+      try {
+        result = await take({
+          key: `${keyPrefix}${input.purpose}:${input.tenantId}:${subjectHash}`,
+          cutoff: currentTime - windowMs,
+          now: currentTime,
+          member,
+          limit: input.limit,
+          ttlSeconds: input.windowSeconds + 1,
+        })
+      } catch {
+        storeUnavailable()
+      }
+      if (
+        !isObject(result)
+        || typeof result.allowed !== 'boolean'
+        || !Number.isSafeInteger(result.remaining)
+        || result.remaining < 0
+        || !Number.isSafeInteger(result.oldestTimestamp)
+        || result.oldestTimestamp < 0
+      ) storeUnavailable()
+
+      return Object.freeze({
+        allowed: result.allowed,
+        remaining: result.remaining,
+        retryAfterSeconds: result.allowed
+          ? 0
+          : Math.max(1, Math.ceil((result.oldestTimestamp + windowMs - currentTime) / 1_000)),
+      })
+    },
+  }
+  return Object.freeze(limiter)
+}
+
+export function recentPasskeyAuthenticationAt(
+  loginHistory: readonly { readonly userId: number; readonly loginAt: string; readonly logoutAt: string | null }[],
+  userId: number,
+  options: { readonly now?: number; readonly maxAgeMs?: number } = {},
+): number | null {
+  if (!Array.isArray(loginHistory)) invalidInput()
+  assertPositiveId(userId)
+  const currentTime = options.now ?? Date.now()
+  const maxAgeMs = options.maxAgeMs ?? PASSKEY_RECENT_AUTH_MAX_AGE_MS
+  if (!Number.isSafeInteger(currentTime) || currentTime < 0) invalidInput()
+  if (!Number.isSafeInteger(maxAgeMs) || maxAgeMs <= 0) invalidInput()
+
+  for (let index = loginHistory.length - 1; index >= 0; index -= 1) {
+    const entry = loginHistory[index]
+    if (!entry || entry.userId !== userId || entry.logoutAt !== null) continue
+    const authenticatedAt = Date.parse(entry.loginAt)
+    const age = currentTime - authenticatedAt
+    return Number.isSafeInteger(authenticatedAt) && age >= 0 && age <= maxAgeMs
+      ? authenticatedAt
+      : null
+  }
+  return null
+}
+
+export async function createPasskeyUserHandle(
+  tenantId: number,
+  userId: number,
+  secret: string | Uint8Array,
+): Promise<Uint8Array<ArrayBuffer>> {
+  assertPositiveTenantId(tenantId)
+  assertPositiveId(userId)
+  const secretBytes = typeof secret === 'string'
+    ? encoder.encode(secret)
+    : secret instanceof Uint8Array
+      ? new Uint8Array(secret)
+      : invalidInput()
+  if (secretBytes.byteLength < 32) invalidInput()
+  try {
+    const key = await crypto.subtle.importKey(
+      'raw',
+      secretBytes,
+      { name: 'HMAC', hash: 'SHA-256' },
+      false,
+      ['sign'],
+    )
+    const message = encoder.encode(`wellous-passkey-user:v1:${tenantId}:${userId}`)
+    return new Uint8Array(await crypto.subtle.sign('HMAC', key, message))
+  } catch {
+    invalidInput()
+  }
+}
+
+export interface PasskeyCounterStore {
+  compareAndSwap(input: {
+    readonly credentialRowId: number
+    readonly expectedCounter: number
+    readonly newCounter: number
+    readonly usedAt: Date
+  }): Promise<boolean>
+  readCounter(credentialRowId: number): Promise<number | null>
+}
+
+export async function commitPasskeyCounter(
+  store: PasskeyCounterStore,
+  input: {
+    readonly credentialRowId: number
+    readonly expectedCounter: number
+    readonly newCounter: number
+    readonly usedAt?: Date
+  },
+): Promise<boolean> {
+  if (!isObject(store) || typeof store.compareAndSwap !== 'function' || typeof store.readCounter !== 'function') {
+    invalidInput()
+  }
+  if (!isObject(input)) invalidInput()
+  assertPositiveId(input.credentialRowId)
+  assertCounter(input.expectedCounter)
+  assertCounter(input.newCounter)
+  const usedAtMs = input.usedAt === undefined
+    ? Date.now()
+    : input.usedAt instanceof Date
+      ? input.usedAt.getTime()
+      : invalidInput()
+  if (!Number.isSafeInteger(usedAtMs) || usedAtMs < 0 || usedAtMs > 8_640_000_000_000_000) invalidInput()
+
+  const counterless = input.expectedCounter === 0 && input.newCounter === 0
+  if (!counterless && input.newCounter <= input.expectedCounter) return false
+
+  let swapped: boolean
+  try {
+    swapped = await store.compareAndSwap({
+      credentialRowId: input.credentialRowId,
+      expectedCounter: input.expectedCounter,
+      newCounter: input.newCounter,
+      usedAt: new Date(usedAtMs),
+    })
+  } catch {
+    storeUnavailable()
+  }
+  if (typeof swapped !== 'boolean') storeUnavailable()
+  if (swapped) return true
+
+  if (!counterless) return false
+  try {
+    return await store.readCounter(input.credentialRowId) === 0
+  } catch {
+    storeUnavailable()
+  }
+}
+
+function assertIssueRegistration(input: unknown): asserts input is Parameters<PasskeyChallengeManager['issueRegistration']>[0] {
+  if (!isObject(input)) invalidInput()
+  assertCommonInput(input)
+  assertPositiveId(input.userId)
+  assertSessionBinding(input.initiatingSessionId)
+  validateCredentialIds(input.excludedCredentialIds)
+}
+
+function assertConsumeRegistration(input: unknown): asserts input is Parameters<PasskeyChallengeManager['takeRegistration']>[0] {
+  if (!isObject(input)) invalidInput()
+  assertPositiveTenantId(input.tenantId)
+  assertPositiveId(input.userId)
+  assertSessionBinding(input.initiatingSessionId)
+  if (!Number.isSafeInteger(input.authenticatedAt) || input.authenticatedAt < 0) invalidInput()
+  assertRpBinding(input.rpID, input.origin)
+}
+
+function assertIssueAuthentication(input: unknown): asserts input is Parameters<PasskeyChallengeManager['issueAuthentication']>[0] {
+  if (!isObject(input)) invalidInput()
+  assertCommonInput(input)
+  if (input.userId !== null) assertPositiveId(input.userId)
+  validateCredentialIds(input.allowedCredentialIds)
+}
+
+function assertCommonInput(input: Record<string, unknown>): void {
+  if (typeof input.challenge !== 'string' || !CHALLENGE_PATTERN.test(input.challenge)) invalidInput()
+  assertPositiveTenantId(input.tenantId)
+  assertRpBinding(input.rpID, input.origin)
+}
+
+function parseRecord(
+  raw: string | null,
+  currentTime: number,
+  expectedTtlMs: number,
+  maxSerializedBytes: number,
+): RegistrationPasskeyChallenge | AuthenticationPasskeyChallenge {
+  if (typeof raw !== 'string' || raw.length === 0 || encoder.encode(raw).byteLength > maxSerializedBytes) {
+    throw new PasskeyAuthError()
+  }
+  let value: unknown
+  try {
+    value = JSON.parse(raw)
+  } catch {
+    throw new PasskeyAuthError()
+  }
+  if (!isObject(value) || value.version !== 1) throw new PasskeyAuthError()
+
+  try {
+    assertPositiveTenantId(value.tenantId)
+    if (typeof value.challenge !== 'string' || !CHALLENGE_PATTERN.test(value.challenge)) invalidInput()
+    assertRpBinding(value.rpID, value.origin)
+    if (
+      !Number.isSafeInteger(value.issuedAt)
+      || value.issuedAt < 0
+      || value.issuedAt > currentTime
+      || !Number.isSafeInteger(value.expiresAt)
+      || value.expiresAt <= currentTime
+      || value.expiresAt <= value.issuedAt
+      || value.expiresAt - value.issuedAt !== expectedTtlMs
+    ) invalidInput()
+
+    if (value.purpose === 'register') {
+      assertExactKeys(value, [
+        'version', 'purpose', 'challenge', 'tenantId', 'userId', 'initiatingSessionHash',
+        'authenticatedAt', 'rpID', 'origin', 'excludedCredentialIds', 'issuedAt', 'expiresAt',
+      ])
+      assertPositiveId(value.userId)
+      if (typeof value.initiatingSessionHash !== 'string' || !SHA256_BASE64URL_PATTERN.test(value.initiatingSessionHash)) {
+        invalidInput()
+      }
+      assertAuthenticationTime(value.authenticatedAt, currentTime)
+      if (value.authenticatedAt > value.issuedAt) invalidInput()
+      return Object.freeze({
+        version: 1,
+        purpose: 'register',
+        challenge: value.challenge,
+        tenantId: value.tenantId,
+        userId: value.userId,
+        initiatingSessionHash: value.initiatingSessionHash,
+        authenticatedAt: value.authenticatedAt,
+        rpID: value.rpID,
+        origin: value.origin,
+        excludedCredentialIds: Object.freeze(validateCredentialIds(value.excludedCredentialIds)),
+        issuedAt: value.issuedAt,
+        expiresAt: value.expiresAt,
+      })
+    }
+    if (value.purpose === 'authenticate') {
+      assertExactKeys(value, [
+        'version', 'purpose', 'challenge', 'tenantId', 'userId', 'rpID', 'origin',
+        'allowedCredentialIds', 'issuedAt', 'expiresAt',
+      ])
+      if (value.userId !== null) assertPositiveId(value.userId)
+      return Object.freeze({
+        version: 1,
+        purpose: 'authenticate',
+        challenge: value.challenge,
+        tenantId: value.tenantId,
+        userId: value.userId,
+        rpID: value.rpID,
+        origin: value.origin,
+        allowedCredentialIds: Object.freeze(validateCredentialIds(value.allowedCredentialIds)),
+        issuedAt: value.issuedAt,
+        expiresAt: value.expiresAt,
+      })
+    }
+    invalidInput()
+  } catch {
+    throw new PasskeyAuthError()
+  }
+}
+
+function encodeRecord(
+  record: RegistrationPasskeyChallenge | AuthenticationPasskeyChallenge,
+  maxSerializedBytes: number,
+): string {
+  const encoded = JSON.stringify(record)
+  if (encoder.encode(encoded).byteLength > maxSerializedBytes) invalidInput()
+  return encoded
+}
+
+function validateCredentialIds(value: unknown): string[] {
+  if (!Array.isArray(value) || value.length > 128) invalidInput()
+  const result: string[] = []
+  const seen = new Set<string>()
+  for (const item of value) {
+    if (typeof item !== 'string' || !CREDENTIAL_ID_PATTERN.test(item)) invalidInput()
+    if (!seen.has(item)) {
+      seen.add(item)
+      result.push(item)
+    }
+  }
+  return result
+}
+
+function assertPositiveTenantId(value: unknown): asserts value is number {
+  if (!Number.isSafeInteger(value) || (value as number) <= 0) invalidInput()
+}
+
+function assertPositiveId(value: unknown): asserts value is number {
+  if (!Number.isSafeInteger(value) || (value as number) <= 0) invalidInput()
+}
+
+function assertCounter(value: unknown): asserts value is number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0) invalidInput()
+}
+
+function assertCredentialId(value: unknown): asserts value is string {
+  if (typeof value !== 'string' || !CREDENTIAL_ID_PATTERN.test(value)) invalidInput()
+}
+
+function assertSessionBinding(value: unknown): asserts value is string {
+  if (typeof value !== 'string' || value.length < 16 || value.length > 512) invalidInput()
+}
+
+function assertAuthenticationTime(value: unknown, currentTime: number, maxAgeMs = Number.MAX_SAFE_INTEGER): asserts value is number {
+  if (
+    !Number.isSafeInteger(value)
+    || (value as number) < 0
+    || (value as number) > currentTime
+    || currentTime - (value as number) > maxAgeMs
+  ) invalidInput()
+}
+
+function assertRpBinding(rpID: unknown, origin: unknown): asserts rpID is string {
+  if (typeof rpID !== 'string' || rpID.length === 0 || rpID.length > 253 || typeof origin !== 'string') {
+    invalidInput()
+  }
+  let parsed: URL
+  try {
+    parsed = new URL(origin)
+  } catch {
+    invalidInput()
+  }
+  if (
+    parsed.origin !== origin
+    || parsed.hostname !== rpID
+    || (parsed.protocol !== 'https:' && !isLoopbackRp(parsed.hostname))
+    || parsed.username !== ''
+    || parsed.password !== ''
+  ) invalidInput()
+}
+
+function assertExactKeys(value: Record<string, unknown>, keys: readonly string[]): void {
+  const allowed = new Set(keys)
+  if (Object.keys(value).some(key => !allowed.has(key))) invalidInput()
+}
+
+function isLoopbackRp(hostname: string): boolean {
+  return hostname === 'localhost'
+    || hostname.endsWith('.localhost')
+    || hostname === '[::1]'
+    || /^127(?:\.\d{1,3}){3}$/u.test(hostname)
+}
+
+function checkedNow(now: () => number): number {
+  let value: number
+  try {
+    value = now()
+  } catch {
+    invalidInput(500)
+  }
+  if (!Number.isSafeInteger(value) || value < 0) invalidInput()
+  return value
+}
+
+function checkedExpiry(issuedAt: number, ttlMs: number): number {
+  const expiresAt = issuedAt + ttlMs
+  if (!Number.isSafeInteger(expiresAt)) invalidInput()
+  return expiresAt
+}
+
+async function sha256Base64Url(value: string): Promise<string> {
+  const hash = await crypto.subtle.digest('SHA-256', encoder.encode(value))
+  return base64Url(new Uint8Array(hash))
+}
+
+function createAuthenticationToken(): string {
+  return `pca_v1_${base64Url(crypto.getRandomValues(new Uint8Array(32)))}`
+}
+
+function base64Url(bytes: Uint8Array): string {
+  let binary = ''
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary).replace(/\+/gu, '-').replace(/\//gu, '_').replace(/=+$/u, '')
+}
+
+function invalidInput(status = 400): never {
+  throw new AuthError({ code: 'invalid_input', status })
+}
+
+function storeUnavailable(): never {
+  throw new AuthError({ code: 'auth_store_unavailable', status: 503, retryable: true })
+}
+
+function isObject(value: unknown): value is Record<string, any> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}