feat(auth)!: 6-digit OTP pairing code and crypto-secure tokens

Separate the two roles the auth flow previously conflated. The persistent
client bearer token and remote-dock tokens become high-entropy, CSPRNG
credentials, while the human-typed pairing code becomes an easy-to-enter
6-digit one-time code guarded by a short TTL and an attempt cap.

The pairing code is single-use, expires after five minutes, is compared in
constant time, and rotates after five failed attempts, so its shorter length
stays brute-force resistant. Bearer and dock tokens move off the vendored
word-list generator (which relied on Math.random) to WebCrypto-backed
randomness.

The vendored human-id helper is removed in favour of a new
`devframe/utils/crypto-token` util exposing `randomToken`, `randomDigits`,
and `timingSafeEqual`.

BREAKING CHANGE: the `devframe/utils/human-id` export is removed. Use
`randomToken` from `devframe/utils/crypto-token` for random identifiers.

Author: antfubot

alias.ts

@@ -18,9 +18,9 @@ export const alias = {
   'devframe/node': r('devframe/src/node/index.ts'),
   'devframe/constants': r('devframe/src/constants.ts'),
   'devframe/utils/colors': r('devframe/src/utils/colors.ts'),
+  'devframe/utils/crypto-token': r('devframe/src/utils/crypto-token.ts'),
   'devframe/utils/events': r('devframe/src/utils/events.ts'),
   'devframe/utils/hash': r('devframe/src/utils/hash.ts'),
-  'devframe/utils/human-id': r('devframe/src/utils/human-id.ts'),
   'devframe/utils/launch-editor': r('devframe/src/utils/launch-editor.ts'),
   'devframe/utils/nanoid': r('devframe/src/utils/nanoid.ts'),
   'devframe/utils/open': r('devframe/src/utils/open.ts'),

docs/helpers/utilities.md

@@ -74,25 +74,27 @@ const wire = structuredCloneStringify(new Map([['a', 1]]))
 const value = structuredCloneParse<Map<string, number>>(wire)
 ```
 
-### `devframe/utils/human-id`
+### `devframe/utils/nanoid`
 
-Generate a human-readable, lowercase, dash-separated random ID.
+Tiny URL-safe random ID generator (vendored, no runtime dependency).
 
 ```ts
-import { humanId } from 'devframe/utils/human-id'
+import { nanoid } from 'devframe/utils/nanoid'
 
-humanId() // 'bright-orange-tiger'
+nanoid() // 21 chars
+nanoid(10) // 10 chars
 ```
 
-### `devframe/utils/nanoid`
+### `devframe/utils/crypto-token`
 
-Tiny URL-safe random ID generator (vendored, no runtime dependency).
+Cryptographically-secure token helpers built on the WebCrypto global, so they run in browsers and Node alike. Use these for bearer credentials and human-typed one-time codes.
 
 ```ts
-import { nanoid } from 'devframe/utils/nanoid'
+import { randomDigits, randomToken, timingSafeEqual } from 'devframe/utils/crypto-token'
 
-nanoid() // 21 chars
-nanoid(10) // 10 chars
+randomToken() // 32-char hex, 128 bits of entropy — use as a bearer token
+randomDigits(6) // '047204' — uniform, leading zeros preserved
+timingSafeEqual(input, secret) // constant-time string comparison
 ```
 
 ### `devframe/utils/promise`

packages/devframe/package.json

@@ -40,9 +40,9 @@
     "./rpc/transports/ws-server": "./dist/rpc/transports/ws-server.mjs",
     "./types": "./dist/types/index.mjs",
     "./utils/colors": "./dist/utils/colors.mjs",
+    "./utils/crypto-token": "./dist/utils/crypto-token.mjs",
     "./utils/events": "./dist/utils/events.mjs",
     "./utils/hash": "./dist/utils/hash.mjs",
-    "./utils/human-id": "./dist/utils/human-id.mjs",
     "./utils/launch-editor": "./dist/utils/launch-editor.mjs",
     "./utils/nanoid": "./dist/utils/nanoid.mjs",
     "./utils/open": "./dist/utils/open.mjs",

packages/devframe/src/client/rpc.ts

@@ -7,8 +7,8 @@ import {
   DEVFRAME_CONNECTION_META_FILENAME,
 } from 'devframe/constants'
 import { RpcCacheManager, RpcFunctionsCollectorBase } from 'devframe/rpc'
+import { randomToken } from 'devframe/utils/crypto-token'
 import { createEventEmitter } from 'devframe/utils/events'
-import { humanId } from 'devframe/utils/human-id'
 import { createRpcSharedStateClientHost } from './rpc-shared-state'
 import { createStaticRpcClientMode } from './rpc-static'
 import { createRpcStreamingClientHost } from './rpc-streaming'
@@ -144,7 +144,7 @@ function getConnectionAuthTokenFromWindows(userAuthToken?: string): string {
   }
 
   if (!value)
-    value = humanId()
+    value = randomToken()
 
   localStorage.setItem(CONNECTION_AUTH_TOKEN_KEY, value)
   ;(globalThis as any)[CONNECTION_AUTH_TOKEN_KEY] = value

packages/devframe/src/node/auth/state.ts

@@ -1,7 +1,18 @@
 import type { DevframeNodeRpcSession } from 'devframe/types'
 import type { SharedState } from 'devframe/utils/shared-state'
 import type { InternalAnonymousAuthStorage } from '../hub-internals/context'
-import { humanId } from 'devframe/utils/human-id'
+import { randomDigits, timingSafeEqual } from 'devframe/utils/crypto-token'
+
+/** Number of decimal digits in a human-typed one-time pairing code. */
+const TEMP_AUTH_TOKEN_LENGTH = 6
+/**
+ * How long a pairing code stays valid after it is (re)generated. A 6-digit
+ * code only has ~20 bits of entropy, so a short lifetime plus the attempt cap
+ * below are what keep it brute-force resistant.
+ */
+const TEMP_AUTH_TOKEN_TTL = 5 * 60_000
+/** Failed attempts allowed against a single code before it is rotated. */
+const TEMP_AUTH_MAX_ATTEMPTS = 5
 
 export interface PendingAuthRequest {
   clientAuthToken: string
@@ -15,17 +26,26 @@ export interface PendingAuthRequest {
 
 let pendingAuth: PendingAuthRequest | null = null
 let tempAuthToken: string = generateTempId()
+let tempAuthExpiresAt: number = Date.now() + TEMP_AUTH_TOKEN_TTL
+let tempAuthFailedAttempts = 0
 
 function generateTempId(): string {
-  return humanId()
+  return randomDigits(TEMP_AUTH_TOKEN_LENGTH)
 }
 
 export function getTempAuthToken(): string {
   return tempAuthToken
 }
 
+/**
+ * Rotate the pairing code, resetting its expiry window and failed-attempt
+ * counter. Adapters call this when a new pairing flow begins so the displayed
+ * code is freshly valid.
+ */
 export function refreshTempAuthToken(): string {
   tempAuthToken = generateTempId()
+  tempAuthExpiresAt = Date.now() + TEMP_AUTH_TOKEN_TTL
+  tempAuthFailedAttempts = 0
   return tempAuthToken
 }
 
@@ -49,14 +69,34 @@ export function abortPendingAuth(): void {
 }
 
 /**
- * Consume the temp auth ID: verify it matches, trust the pending client, and clean up.
- * Returns the client's authToken if successful, null otherwise.
+ * Consume the temp auth code: verify it matches an active, unexpired pairing
+ * code, trust the pending client, and clean up. Returns the client's authToken
+ * on success, `null` otherwise.
+ *
+ * Because the code is short and human-typed, verification is hardened against
+ * brute force: it requires a live pending request, enforces a time-to-live,
+ * compares in constant time, and rotates the code after
+ * {@link TEMP_AUTH_MAX_ATTEMPTS} failed attempts so an attacker cannot keep
+ * guessing against the same code.
  */
 export function consumeTempAuthToken(
   id: string,
   storage: SharedState<InternalAnonymousAuthStorage>,
 ): string | null {
-  if (id !== tempAuthToken || !pendingAuth) {
+  if (!pendingAuth)
+    return null
+
+  // Expired code: rotate so a stale code can never be redeemed.
+  if (Date.now() > tempAuthExpiresAt) {
+    refreshTempAuthToken()
+    return null
+  }
+
+  if (!timingSafeEqual(id, tempAuthToken)) {
+    tempAuthFailedAttempts += 1
+    // Too many wrong guesses — invalidate this code entirely.
+    if (tempAuthFailedAttempts >= TEMP_AUTH_MAX_ATTEMPTS)
+      refreshTempAuthToken()
     return null
   }
 

packages/devframe/src/node/hub-internals/context.ts

@@ -1,6 +1,6 @@
 import type { DevframeNodeContext } from 'devframe/types'
 import type { SharedState } from 'devframe/utils/shared-state'
-import { humanId } from 'devframe/utils/human-id'
+import { randomToken } from 'devframe/utils/crypto-token'
 import { join } from 'pathe'
 import { revokeActiveConnectionsForToken, revokeAuthToken } from '../auth/revoke'
 import { createStorage } from '../storage'
@@ -80,7 +80,7 @@ export function getInternalContext(context: DevframeNodeContext): DevframeIntern
       revokeAuthToken: (token: string) => revokeAuthToken(context, storage, token),
       remoteTokens,
       allocateRemoteToken(dockId, origin, originLock) {
-        const token = humanId()
+        const token = randomToken()
         remoteTokens.set(token, { dockId, origin, originLock })
         return token
       },

packages/devframe/src/utils/crypto-token.ts

@@ -0,0 +1,60 @@
+// Cryptographically-secure token helpers built on the WebCrypto global
+// (`globalThis.crypto`), which is present in browsers and Node 19+. Kept free
+// of node builtins so it stays runtime-agnostic (see `test/runtime-agnostic.test.ts`)
+// and can be shared by browser-side client code and node-side auth code alike.
+//
+// `getRandomValues` is available in both secure and insecure contexts, unlike
+// `crypto.randomUUID`, so it works even when a devtool is reached over plain
+// HTTP on a LAN address.
+
+const HEX = '0123456789abcdef'
+
+/**
+ * Generate a high-entropy, URL-safe (hex) random token suitable for use as a
+ * bearer credential — e.g. the persistent client auth token or an ephemeral
+ * remote-dock token. Defaults to 16 bytes (128 bits) of entropy.
+ */
+export function randomToken(byteLength = 16): string {
+  const bytes = new Uint8Array(byteLength)
+  globalThis.crypto.getRandomValues(bytes)
+  let out = ''
+  for (let i = 0; i < bytes.length; i++)
+    out += HEX[bytes[i] >> 4] + HEX[bytes[i] & 0x0F]
+  return out
+}
+
+/**
+ * Generate a uniformly-distributed string of decimal digits using rejection
+ * sampling to avoid modulo bias. Intended for short, human-typed one-time
+ * codes (e.g. a 6-digit pairing code). Leading zeros are preserved.
+ */
+export function randomDigits(length: number): string {
+  // Largest multiple of 10 that fits in a byte; reject values at/above it so
+  // every digit is equally likely.
+  const limit = 250
+  const buf = new Uint8Array(1)
+  let out = ''
+  while (out.length < length) {
+    globalThis.crypto.getRandomValues(buf)
+    if (buf[0] < limit)
+      out += String(buf[0] % 10)
+  }
+  return out
+}
+
+/**
+ * Constant-time string equality. Compares every character so the comparison
+ * time does not depend on the position of the first mismatch, mitigating
+ * timing side-channels when verifying secrets.
+ *
+ * Length is treated as public (it short-circuits on differing lengths), which
+ * is appropriate for fixed-length codes and tokens.
+ */
+export function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length)
+    return false
+  let mismatch = 0
+  for (let i = 0; i < a.length; i++)
+    mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i)
+  return mismatch === 0
+}

packages/devframe/src/utils/human-id.ts

@@ -10,9 +10,9 @@ import { describe, expect, it } from 'vitest'
 const AGNOSTIC_ENTRIES = [
   'client/index.mjs',
   'utils/colors.mjs',
+  'utils/crypto-token.mjs',
   'utils/events.mjs',
   'utils/hash.mjs',
-  'utils/human-id.mjs',
   'utils/nanoid.mjs',
   'utils/promise.mjs',
   'utils/shared-state.mjs',

packages/devframe/test/runtime-agnostic.test.ts

@@ -59,9 +59,9 @@ const deps = {
 const clientEntries = {
   'client/index': 'src/client/index.ts',
   'utils/colors': 'src/utils/colors.ts',
+  'utils/crypto-token': 'src/utils/crypto-token.ts',
   'utils/events': 'src/utils/events.ts',
   'utils/hash': 'src/utils/hash.ts',
-  'utils/human-id': 'src/utils/human-id.ts',
   'utils/nanoid': 'src/utils/nanoid.ts',
   'utils/promise': 'src/utils/promise.ts',
   'utils/shared-state': 'src/utils/shared-state.ts',
@@ -128,9 +128,9 @@ export default defineConfig([
           entries: [
             resolve(distDir, 'client/index.mjs'),
             resolve(distDir, 'utils/colors.mjs'),
+            resolve(distDir, 'utils/crypto-token.mjs'),
             resolve(distDir, 'utils/events.mjs'),
             resolve(distDir, 'utils/hash.mjs'),
-            resolve(distDir, 'utils/human-id.mjs'),
             resolve(distDir, 'utils/nanoid.mjs'),
             resolve(distDir, 'utils/promise.mjs'),
             resolve(distDir, 'utils/shared-state.mjs'),