@byline/admin 6.7.2 → 6.8.0

package/src/modules/auth/passkey-rate-limiter.test.node.ts

@@ -0,0 +1,83 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { createPasskeyRequestLimiter } from './passkey-rate-limiter.js'
+import { createPasswordSignInLimiter, type SignInRateLimitStore } from './sign-in-rate-limiter.js'
+
+const secret = 'passkey-counter-secret-at-least-thirty-two-bytes'
+function fixture() {
+  const counts = new Map<string, number>()
+  const store: SignInRateLimitStore = {
+    consume: vi.fn(async (key, limit) => {
+      const n = (counts.get(key) ?? 0) + 1
+      counts.set(key, n)
+      return n <= limit
+    }),
+    purgeExpired: vi.fn(async () => 0),
+  }
+  return { store, limiter: createPasskeyRequestLimiter(store, secret, () => 0) }
+}
+afterEach(() => vi.useRealTimers())
+describe('passkey request limiter', () => {
+  it('uses four slots without queueing and retains each slot for 100ms including quick denials', async () => {
+    vi.useFakeTimers()
+    const { limiter } = fixture()
+    const leases = await Promise.all(Array.from({ length: 4 }, () => limiter.acquire()))
+    expect(leases.every(Boolean)).toBe(true)
+    expect(await limiter.acquire()).toBeNull()
+    leases[0]?.()
+    leases[0]?.()
+    await vi.advanceTimersByTimeAsync(99)
+    expect(await limiter.acquire()).toBeNull()
+    await vi.advanceTimersByTimeAsync(1)
+    expect(await limiter.acquire()).toBeTypeOf('function')
+    expect(await limiter.acquire()).toBeNull()
+  })
+  it('shares a 60/minute network bucket across instances with IPv4-mapped equivalence', async () => {
+    const { store, limiter } = fixture()
+    const another = createPasskeyRequestLimiter(store, secret, () => 0)
+    for (let i = 0; i < 60; i++)
+      expect((await limiter.consume({ ip: '192.0.2.1' })).allowed).toBe(true)
+    expect(await another.consume({ ip: '::ffff:192.0.2.1' })).toEqual({
+      allowed: false,
+      retryAfterSeconds: 60,
+    })
+    expect((await another.consume({ ip: '192.0.2.2' })).allowed).toBe(true)
+    const key = vi.mocked(store.consume).mock.calls[0]?.[0]
+    expect(key).toMatch(/^[a-f0-9]{64}$/)
+    expect(key).not.toContain('192.0.2.1')
+  })
+  it('separates the passkey counter domain and capacity from password sign-in', async () => {
+    const { store, limiter } = fixture()
+    for (let i = 0; i < 4; i++) await limiter.acquire()
+    const password = createPasswordSignInLimiter(store, secret, undefined, () => 0, {
+      onEvent: () => {},
+    })
+    const releasePassword = await password.acquire()
+    expect(releasePassword).toBeTypeOf('function')
+    await limiter.consume({ ip: '192.0.2.1' })
+    const passkeyKey = vi.mocked(store.consume).mock.calls.at(-1)?.[0]
+    await password.consume({ email: 'admin@example.test', ip: '192.0.2.1' })
+    expect(
+      vi
+        .mocked(store.consume)
+        .mock.calls.slice(1)
+        .every(([key]) => key !== passkeyKey)
+    ).toBe(true)
+    releasePassword?.()
+    password.dispose()
+  })
+  it('fails closed on storage errors and rejects invalid addresses', async () => {
+    const { store, limiter } = fixture()
+    vi.mocked(store.consume).mockRejectedValue(new Error('offline'))
+    await expect(limiter.consume({ ip: '192.0.2.1' })).rejects.toThrow('offline')
+    await expect(limiter.consume({ ip: 'untrusted' })).rejects.toThrow('Invalid client address')
+  })
+})

package/src/modules/auth/passkey-rate-limiter.ts

@@ -0,0 +1,76 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { createHmac } from 'node:crypto'
+
+import type { PasskeyRequestLimiter } from '@byline/auth'
+import type { RecurringTaskDefinition } from '@byline/core'
+
+import { type SignInRateLimitStore, signInNetwork } from './sign-in-rate-limiter.js'
+
+/** Separate WebAuthn capacity and key domain; counter storage and cleanup are shared. */
+export function createPasskeyRequestLimiter(
+  store: SignInRateLimitStore,
+  secret: string | Uint8Array,
+  now: () => number = Date.now
+): PasskeyRequestLimiter & { cleanupTask: RecurringTaskDefinition } {
+  const bytes = typeof secret === 'string' ? new TextEncoder().encode(secret) : secret
+  if (bytes.byteLength < 32) throw new Error('Passkey HMAC secret must contain at least 32 bytes')
+  const key = createHmac('sha256', bytes).update('byline:passkey-requests:v1').digest()
+  let active = 0
+  const cleanupTask: RecurringTaskDefinition = {
+    // Both limiters use the same counter table; register this task only once.
+    name: 'auth.sign-in-counters.cleanup',
+    intervalMs: 60_000,
+    leaseMs: 60_000,
+    async run(context) {
+      const started = performance.now()
+      for (let n = 0; n < 32 && performance.now() - started < 30_000; n++) {
+        context.signal.throwIfAborted()
+        await context.heartbeat()
+        if ((await store.purgeExpired(new Date(now() - 300_000))) < 100)
+          return { workRemaining: false }
+      }
+      return { workRemaining: true }
+    },
+  }
+  return {
+    requiredCleanupTask: cleanupTask.name,
+    cleanupTask,
+    async acquire() {
+      if (active >= 4) return null
+      active++
+      const started = performance.now()
+      let released = false
+      return () => {
+        if (released) return
+        released = true
+        setTimeout(
+          () => {
+            active--
+          },
+          Math.max(0, 100 - (performance.now() - started))
+        ).unref()
+      }
+    },
+    async consume({ ip }) {
+      const network = signInNetwork(ip)
+      const time = now()
+      const end = (Math.floor(time / 60_000) + 1) * 60_000
+      const digest = createHmac('sha256', key)
+        .update(JSON.stringify(['network', network, end]))
+        .digest('hex')
+      await store.purgeExpired(new Date(time - 300_000))
+      const allowed = await store.consume(digest, 60, new Date(end))
+      return {
+        allowed,
+        retryAfterSeconds: allowed ? 0 : Math.max(1, Math.ceil((end - time) / 1000)),
+      }
+    },
+  }
+}

package/src/modules/auth/passkey-storage-validation.ts

@@ -0,0 +1,108 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type { PasskeyAttemptRow, PasskeyClaimInput } from './passkeys-repository.js'
+
+/** Canonical encoding makes string identity exactly equivalent to WebAuthn byte identity. */
+export function assertPasskeyBytes(value: string, maxBytes: number, exactBytes?: number): void {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9_-]+$/.test(value)) {
+    throw new Error('Invalid passkey byte encoding')
+  }
+  const bytes = Buffer.from(value, 'base64url')
+  if (
+    bytes.length > maxBytes ||
+    (exactBytes !== undefined && bytes.length !== exactBytes) ||
+    bytes.toString('base64url') !== value
+  )
+    throw new Error('Invalid passkey byte encoding')
+}
+
+export function assertPasskeyTokenHash(value: string): void {
+  if (!/^[a-f0-9]{64}$/.test(value)) throw new Error('Invalid passkey token hash')
+}
+
+export function assertPasskeyAttempt(input: Omit<PasskeyAttemptRow, 'consumed_at'>): void {
+  assertPasskeyTokenHash(input.token_hash)
+  const lifetime = input.expires_at.getTime() - input.created_at.getTime()
+  if (!Number.isFinite(lifetime) || lifetime <= 0 || lifetime > 300_000) {
+    throw new Error('Invalid passkey attempt lifetime')
+  }
+  if (!['sign-in', 'fresh-authentication', 'enrollment', 'grant'].includes(input.purpose)) {
+    throw new Error('Invalid passkey attempt purpose')
+  }
+  if (input.purpose === 'grant') {
+    if (input.challenge !== null) throw new Error('Grants cannot contain challenges')
+  } else {
+    assertPasskeyBytes(input.challenge ?? '', 32, 32)
+  }
+  if (input.purpose === 'sign-in') {
+    if (
+      [
+        input.actor_user_id,
+        input.actor_login_id,
+        input.actor_generation,
+        input.action,
+        input.target_user_id,
+        input.credential_record_id,
+        input.proof_credential_id,
+      ].some((value) => value !== null)
+    ) {
+      throw new Error('Sign-in attempts cannot carry management authority')
+    }
+  } else {
+    if (
+      !input.actor_user_id ||
+      !input.actor_login_id ||
+      !Number.isSafeInteger(input.actor_generation) ||
+      (input.actor_generation ?? -1) < 0
+    ) {
+      throw new Error('Management attempts require an acting login and generation')
+    }
+    if (input.action === 'enroll') {
+      if (input.target_user_id !== input.actor_user_id || input.credential_record_id !== null) {
+        throw new Error('Enrollment must target the actor')
+      }
+    } else if (input.action === 'remove') {
+      if (!input.target_user_id || !input.credential_record_id || input.purpose === 'enrollment') {
+        throw new Error('Removal must bind its target account and credential')
+      }
+    } else throw new Error('Management attempts require an action')
+  }
+}
+
+/** Runtime callers must obey the same purpose/action boundary as typed callers. */
+export function assertPasskeyClaim(input: PasskeyClaimInput): void {
+  assertPasskeyTokenHash(input.tokenHash)
+  if (input.purpose === 'sign-in') {
+    if (
+      input.action !== undefined ||
+      [
+        input.binding.actor_user_id,
+        input.binding.actor_login_id,
+        input.binding.actor_generation,
+      ].some((value) => value !== null)
+    ) {
+      throw new Error('Sign-in claims require anonymous binding and no action')
+    }
+  } else {
+    if (!['fresh-authentication', 'enrollment', 'grant'].includes(input.purpose)) {
+      throw new Error('Invalid passkey claim purpose')
+    }
+    if (input.action !== 'enroll' && input.action !== 'remove') {
+      throw new Error('Authenticated claims require an action')
+    }
+    if (
+      !input.binding.actor_user_id ||
+      !input.binding.actor_login_id ||
+      !Number.isSafeInteger(input.binding.actor_generation) ||
+      input.binding.actor_generation < 0
+    ) {
+      throw new Error('Authenticated claims require an acting login binding')
+    }
+  }
+}

package/src/modules/auth/passkeys-repository.ts

@@ -0,0 +1,97 @@
+/**
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/** Internal persistence records. Never return these through account/editor DTOs. */
+export interface PasskeyCredentialRow {
+  id: string
+  /** Null after account deletion; the credential identity remains reserved. */
+  admin_user_id: string | null
+  /** Canonical unpadded base64url; byte-exact uniqueness includes revoked records. */
+  credential_id: string
+  public_key: string
+  counter: number
+  transports: string[]
+  backup_eligible: boolean
+  backed_up: boolean
+  name: string
+  created_at: Date
+  last_used_at: Date | null
+  revoked_at: Date | null
+}
+
+export interface PasskeyAttemptRow {
+  /** SHA-256 hex of the independent bearer identifier; never the identifier itself. */
+  token_hash: string
+  purpose: 'sign-in' | 'fresh-authentication' | 'enrollment' | 'grant'
+  challenge: string | null
+  actor_user_id: string | null
+  actor_login_id: string | null
+  actor_generation: number | null
+  action: 'enroll' | 'remove' | null
+  target_user_id: string | null
+  credential_record_id: string | null
+  /** Credential used for fresh proof, if any; revalidated at grant use. */
+  proof_credential_id: string | null
+  created_at: Date
+  expires_at: Date
+  consumed_at: Date | null
+}
+
+export type PasskeyClaimInput = { tokenHash: string; now: Date } & (
+  | {
+      purpose: 'sign-in'
+      binding: { actor_user_id: null; actor_login_id: null; actor_generation: null }
+      action?: never
+    }
+  | {
+      purpose: 'fresh-authentication' | 'enrollment' | 'grant'
+      binding: { actor_user_id: string; actor_login_id: string; actor_generation: number }
+      action: 'enroll' | 'remove'
+    }
+)
+
+export interface PasskeysRepository {
+  /** Target lock required; generation and native-login revocation commit together. */
+  invalidateAccountLogins(adminUserId: string, at: Date): Promise<void>
+  /** Success requires both account locks; denial/failure records may be written separately. */
+  appendRemovalAudit(input: {
+    actorId: string
+    targetId: string
+    credentialId: string
+    outcome: 'success' | 'denied' | 'failed'
+  }): Promise<void>
+  getUserHandle(adminUserId: string): Promise<string | null>
+  /** Requires the owning account lock. Allocates once; never resets on credential removal. */
+  ensureUserHandle(adminUserId: string, candidate: string): Promise<string>
+  /** Includes tombstones: authentication must reject revoked or ownerless records. */
+  findCredential(id: string): Promise<PasskeyCredentialRow | null>
+  /** Includes tombstones: authentication must reject revoked or ownerless records. */
+  findCredentialByCredentialId(credentialId: string): Promise<PasskeyCredentialRow | null>
+  listCredentials(adminUserId: string): Promise<PasskeyCredentialRow[]>
+  /** All credential writes require the owning account lock and share its transaction. */
+  createCredential(
+    input: Omit<PasskeyCredentialRow, 'admin_user_id' | 'revoked_at'> & {
+      admin_user_id: string
+    }
+  ): Promise<void>
+  updateCredential(
+    id: string,
+    patch: Partial<Pick<PasskeyCredentialRow, 'counter' | 'backed_up' | 'name' | 'last_used_at'>>
+  ): Promise<void>
+  revokeCredential(id: string, at: Date): Promise<void>
+  /** Authenticated attempts require the actor lock; sign-in has no account yet. */
+  createAttempt(input: Omit<PasskeyAttemptRow, 'consumed_at'>): Promise<void>
+  findAttempt(tokenHash: string): Promise<PasskeyAttemptRow | null>
+  countPendingForLogin(loginId: string, now: Date): Promise<number>
+  /**
+   * Root store only: commits consumption in its own short transaction BEFORE returning.
+   * Calling through an account-transaction store must throw, never create a savepoint.
+   * Exact purpose/binding, unconsumed state and expiry gate the sole winning claim.
+   * No automatic retries, even if commit acknowledgement is uncertain.
+   */
+  claimAttempt(input: PasskeyClaimInput): Promise<PasskeyAttemptRow | null>
+}

package/src/modules/auth/refresh-tokens-repository.ts

@@ -66,7 +66,7 @@ export interface RefreshTokensRepository {
   revokeChain(startId: string, at?: Date): Promise<number>
   /** Revoke every non-revoked token for a user. Used on password change / sign-out everywhere. */
   revokeAllForUser(adminUserId: string, at?: Date): Promise<number>
-  /** Remove rows whose `expires_at` is in the past. Housekeeping. */
+  /** Legacy housekeeping: at most 100 null-sid rows expired for 30 days. Native login members are retained. */
   purgeExpired(now?: Date): Promise<number>
   /** All non-revoked tokens for a user. Primarily for tests. */
   listActiveForUser(adminUserId: string): Promise<RefreshTokenRow[]>

package/src/modules/auth/sign-in-rate-limiter.ts

@@ -48,7 +48,7 @@ const DEFAULT_POLICY: SignInRateLimitPolicy = {
 const CLEANUP_TASK_NAME = 'auth.sign-in-counters.cleanup'
 
 /** IPv4 uses one address; IPv6 uses its /64. Mapped IPv4 shares its native IPv4 bucket. */
-function signInNetwork(ip: string): string {
+export function signInNetwork(ip: string): string {
   const version = isIP(ip)
   if (version === 4) return ip
   if (version !== 6 || ip.includes('%')) throw new Error('Invalid client address')

package/src/services/admin-services-context.tsx

@@ -16,6 +16,8 @@ export type {
   ChangeAccountPasswordInput,
   CreateAdminRoleInput,
   CreateAdminUserInput,
+  PasskeyAdminServices,
+  PasskeyPageBinding,
   SetAdminUserPasswordInput,
   SetRoleAbilitiesInput,
   SetUserRolesInput,

package/src/services/admin-services-types.ts

@@ -25,6 +25,15 @@
  * in Phase 3 along with the route factories.
  */
 
+import type {
+  PasskeyAuthenticationOptions,
+  PasskeyCeremony,
+  PasskeyCredentialSummary,
+  PasskeyManagementAction,
+  PasskeyManagementGrant,
+  PasskeyRegistrationOptions,
+} from '@byline/auth'
+
 import type {
   AccountResponse,
   ChangeAccountPasswordRequest,
@@ -59,6 +68,56 @@ export interface SignInInput {
  */
 export type SignInResult = unknown
 
+/** Captured before any prompt; the host checks it again before submission. */
+export interface PasskeyPageBinding {
+  expectedSessionId: string | null
+  assertCurrent(): void
+}
+interface PasskeyBoundInput {
+  expectedSessionId: string
+}
+export interface PasskeyAdminServices {
+  capability(): Promise<{ enabled: boolean }>
+  captureLogin(signIn?: boolean): PasskeyPageBinding
+  managementContext(
+    binding: PasskeyPageBinding
+  ): Promise<{ id: string; isSuperAdmin: boolean; canManagePasskeys: boolean }>
+  signInOptions: AdminServiceCall<
+    Record<string, never>,
+    PasskeyCeremony<PasskeyAuthenticationOptions>
+  >
+  signIn(
+    args: { data: { ceremonyId: string; response: unknown } },
+    binding: PasskeyPageBinding
+  ): Promise<unknown>
+  passwordProof: AdminServiceCall<
+    PasskeyBoundInput & { password: string; action: PasskeyManagementAction },
+    PasskeyManagementGrant
+  >
+  proofOptions: AdminServiceCall<
+    PasskeyBoundInput & { action: PasskeyManagementAction },
+    PasskeyCeremony<PasskeyAuthenticationOptions>
+  >
+  proof: AdminServiceCall<
+    PasskeyBoundInput & { ceremonyId: string; response: unknown },
+    PasskeyManagementGrant
+  >
+  enrollmentOptions: AdminServiceCall<
+    PasskeyBoundInput & { grantId: string },
+    PasskeyCeremony<PasskeyRegistrationOptions>
+  >
+  enrollment: AdminServiceCall<
+    PasskeyBoundInput & { ceremonyId: string; response: unknown; name: string },
+    PasskeyCredentialSummary
+  >
+  list: AdminServiceCall<PasskeyBoundInput & { targetUserId?: string }, PasskeyCredentialSummary[]>
+  rename: AdminServiceCall<
+    PasskeyBoundInput & { credentialRecordId: string; name: string },
+    PasskeyCredentialSummary
+  >
+  remove: AdminServiceCall<PasskeyBoundInput & { grantId: string }, { signedOut: boolean }>
+}
+
 // --- Account self-service -------------------------------------------------
 
 /** Same shape as `UpdateAccountRequest` from `@byline/admin/admin-account`. */
@@ -155,6 +214,7 @@ export interface WhoHasAbilityInput {
 export interface BylineAdminServices {
   // Auth
   adminSignIn: AdminServiceCall<SignInInput, SignInResult>
+  passkeys?: PasskeyAdminServices
 
   // Account self-service
   updateAccount: AdminServiceCall<UpdateAccountInput, AccountResponse>

package/src/store.ts

@@ -13,7 +13,9 @@ import type {
   AdminUsersRepository,
   AdminUserWithPasswordRow,
 } from './modules/admin-users/repository.js'
+import type { AuthMaintenanceRepository } from './modules/auth/auth-maintenance-repository.js'
 import type { LoginSessionsRepository } from './modules/auth/login-sessions-repository.js'
+import type { PasskeysRepository } from './modules/auth/passkeys-repository.js'
 import type { RefreshTokensRepository } from './modules/auth/refresh-tokens-repository.js'
 import type { SignInRateLimitStore } from './modules/auth/sign-in-rate-limiter.js'
 
@@ -44,6 +46,8 @@ export interface AdminStore {
   ): Promise<T>
   /** Lock distinct account IDs in sorted order in one transaction for account-switch sign-in. */
   withSessionLocks<T>(adminUserIds: string[], work: (store: AdminStore) => Promise<T>): Promise<T>
+  authMaintenance: AuthMaintenanceRepository
+  passkeys: PasskeysRepository
   loginSessions: LoginSessionsRepository
   signInRateLimits: SignInRateLimitStore
   adminUsers: AdminUsersRepository