@crombolo/auth 0.14.1 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/auth",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "OAuth2 authorization server, password hashing, cookies and member tickets for crombolo.",
   "license": "MIT",
   "author": "Crombolo",
@@ -28,8 +28,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@crombolo/core": "0.14.1",
-    "@crombolo/data": "0.14.1",
+    "@crombolo/core": "0.15.0",
+    "@crombolo/data": "0.15.0",
     "jose": "^6.2.12",
     "uqr": "^0.1.3"
   }

package/src/device.ts

@@ -0,0 +1,183 @@
+/**
+ * The OAuth 2.0 device authorization grant (RFC 8628), for the `crombolo` CLI
+ * signing in to a remote (story 107): the CLI shows a short code, the person
+ * approves it in a browser where they are already signed in, and the CLI
+ * receives tokens for that person, with that person's permissions.
+ *
+ * The device code is a bearer credential and is stored hashed; the user code is
+ * what a person types, short and unambiguous, and is single-use. An approved
+ * authorization becomes a session of its own, so "signed-in devices" is the
+ * list of those sessions and revoking one ends it.
+ */
+import { randomInt } from 'node:crypto'
+import { type Db, DbDate } from '@crombolo/data'
+import { generateToken, hashToken } from './pkce.ts'
+
+/** The client id the CLI signs in as. */
+export const REMOTE_CLIENT_ID = 'crombolo-cli'
+export const DEVICE_CODE_SECONDS = 10 * 60
+export const DEVICE_POLL_SECONDS = 5
+
+/** No vowels or look-alikes, so a code never spells a word or reads two ways. */
+const USER_CODE_ALPHABET = 'BCDFGHJKLMNPQRSTVWXZ'
+
+export type DeviceStatus = 'pending' | 'approved' | 'denied' | 'issued'
+
+export interface DeviceAuthorizationRow {
+  id: number
+  userCode: string
+  clientId: string
+  clientName: string | null
+  scope: string
+  status: DeviceStatus
+  userId: number | null
+  sessionId: string | null
+  intervalSeconds: number
+  lastPolledAt: Date | undefined
+  expiresAt: Date
+  decidedAt: Date | undefined
+  createdAt: Date
+}
+
+export interface SignedInDevice {
+  id: number
+  clientName: string | null
+  signedInAt: Date
+  lastUsedAt: Date | undefined
+}
+
+function userCode(): string {
+  const pick = () => USER_CODE_ALPHABET[randomInt(USER_CODE_ALPHABET.length)] as string
+  return `${Array.from({ length: 4 }, pick).join('')}-${Array.from({ length: 4 }, pick).join('')}`
+}
+
+/** A code as typed: case, spaces and the dash do not matter. */
+export const normaliseUserCode = (code: string): string => {
+  const plain = code.toUpperCase().replace(/[^A-Z]/g, '')
+  return plain.length === 8 ? `${plain.slice(0, 4)}-${plain.slice(4)}` : plain
+}
+
+function mapRow(row: Record<string, unknown>): DeviceAuthorizationRow {
+  return {
+    id: Number(row.id),
+    userCode: String(row.user_code),
+    clientId: String(row.client_id),
+    clientName:
+      row.client_name === null || row.client_name === undefined ? null : String(row.client_name),
+    scope: String(row.scope),
+    status: String(row.status) as DeviceStatus,
+    userId: row.user_id === null || row.user_id === undefined ? null : Number(row.user_id),
+    sessionId:
+      row.session_id === null || row.session_id === undefined ? null : String(row.session_id),
+    intervalSeconds: Number(row.interval_seconds),
+    lastPolledAt: DbDate.fromDb(row.last_polled_at),
+    expiresAt: DbDate.fromDb(row.expires_at) ?? new Date(0),
+    decidedAt: DbDate.fromDb(row.decided_at),
+    createdAt: DbDate.fromDb(row.create_date) ?? new Date(0),
+  }
+}
+
+export class DeviceStore {
+  #db: Db
+
+  constructor(db: Db) {
+    this.#db = db
+  }
+
+  async create(init: {
+    clientId: string
+    clientName: string | null
+    scope: string
+  }): Promise<{ deviceCode: string; userCode: string; expiresAt: Date }> {
+    const deviceCode = generateToken()
+    const expiresAt = new Date(Date.now() + DEVICE_CODE_SECONDS * 1000)
+    // A clash with a live code is vanishingly rare; another draw settles it.
+    for (let attempt = 0; ; attempt++) {
+      const code = userCode()
+      try {
+        await this.#db.exec(
+          `INSERT INTO device_authorization
+             (device_code_hash, user_code, client_id, client_name, scope, status, interval_seconds, expires_at, create_date)
+           VALUES (?, ?, ?, ?, ?, 'pending', ?, ?, ?)`,
+          [
+            hashToken(deviceCode),
+            code,
+            init.clientId,
+            init.clientName,
+            init.scope,
+            DEVICE_POLL_SECONDS,
+            DbDate.toDb(expiresAt),
+            DbDate.toDb(new Date()),
+          ],
+        )
+        return { deviceCode, userCode: code, expiresAt }
+      } catch (error) {
+        if (attempt >= 4) throw error
+      }
+    }
+  }
+
+  async byDeviceCode(deviceCode: string): Promise<DeviceAuthorizationRow | undefined> {
+    const rows = await this.#db.query(
+      'SELECT * FROM device_authorization WHERE device_code_hash = ?',
+      [hashToken(deviceCode)],
+    )
+    return rows[0] ? mapRow(rows[0]) : undefined
+  }
+
+  async byUserCode(code: string): Promise<DeviceAuthorizationRow | undefined> {
+    const rows = await this.#db.query('SELECT * FROM device_authorization WHERE user_code = ?', [
+      normaliseUserCode(code),
+    ])
+    return rows[0] ? mapRow(rows[0]) : undefined
+  }
+
+  async polled(id: number, intervalSeconds: number): Promise<void> {
+    await this.#db.exec(
+      'UPDATE device_authorization SET last_polled_at = ?, interval_seconds = ? WHERE id = ?',
+      [DbDate.toDb(new Date()), intervalSeconds, id],
+    )
+  }
+
+  /** Approves or denies a pending one; false when it was no longer pending. */
+  async decide(id: number, userId: number, approve: boolean): Promise<boolean> {
+    const rows = await this.#db.query<{ id: number }>(
+      `UPDATE device_authorization SET status = ?, user_id = ?, decided_at = ?
+       WHERE id = ? AND status = 'pending' RETURNING id`,
+      [approve ? 'approved' : 'denied', userId, DbDate.toDb(new Date()), id],
+    )
+    return rows.length > 0
+  }
+
+  /** Marks an approved one as having had its tokens issued, once; false if it already had. */
+  async issued(id: number, sessionId: string): Promise<boolean> {
+    const rows = await this.#db.query<{ id: number }>(
+      `UPDATE device_authorization SET status = 'issued', session_id = ?
+       WHERE id = ? AND status = 'approved' RETURNING id`,
+      [sessionId, id],
+    )
+    return rows.length > 0
+  }
+
+  /** The devices signed in as this user, whose sessions are still open. */
+  async signedIn(userId: number): Promise<SignedInDevice[]> {
+    const rows = await this.#db.query<Record<string, unknown>>(
+      `SELECT d.id, d.client_name, s.logged_in_utc, s.last_validated_utc
+       FROM device_authorization d JOIN user_login_session s ON s.session_id = d.session_id
+       WHERE d.user_id = ? AND d.status = 'issued' AND s.logged_out_utc IS NULL
+       ORDER BY s.logged_in_utc DESC`,
+      [userId],
+    )
+    return rows.map((row) => ({
+      id: Number(row.id),
+      clientName: row.client_name === null ? null : String(row.client_name),
+      signedInAt: DbDate.fromDb(row.logged_in_utc) ?? new Date(0),
+      lastUsedAt: DbDate.fromDb(row.last_validated_utc),
+    }))
+  }
+
+  async byId(id: number): Promise<DeviceAuthorizationRow | undefined> {
+    const rows = await this.#db.query('SELECT * FROM device_authorization WHERE id = ?', [id])
+    return rows[0] ? mapRow(rows[0]) : undefined
+  }
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './admin.ts'
 export * from './cookies.ts'
+export * from './device.ts'
 export * from './member-session.ts'
 export * from './oidc.ts'
 export * from './password.ts'

package/src/routes.ts

@@ -15,6 +15,7 @@ import {
   resolveRedacted,
   serializeCookie,
 } from './cookies.ts'
+import { REMOTE_CLIENT_ID } from './device.ts'
 import type { AuthService } from './service.ts'
 import { BACKOFFICE_CLIENT_ID, DEFAULT_SCOPE } from './service.ts'
 import { readShortLived, signShortLived } from './short-lived.ts'
@@ -25,6 +26,9 @@ const TWO_FACTOR_PENDING_SECONDS = 5 * 60
 
 export const SECURITY_PREFIX = `${MANAGEMENT_API_PATH}/security/back-office`
 
+/** RFC 8628's grant type. */
+export const DEVICE_CODE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code'
+
 export interface AuthRouteOptions {
   backOfficePath: string
   service: AuthService
@@ -186,6 +190,32 @@ export function createAuthRoutes(options: AuthRouteOptions): AuthRoutes {
       })
     }
 
+    // The CLI (story 107): tokens in the body, as a client with no cookie jar needs.
+    if (clientId === REMOTE_CLIENT_ID) {
+      const result =
+        grantType === DEVICE_CODE_GRANT
+          ? await service.pollDevice(form.get('device_code') ?? '', clientId)
+          : grantType === 'refresh_token'
+            ? await service.refresh(form.get('refresh_token') ?? '', clientId)
+            : {
+                ok: false as const,
+                error: 'unsupported_grant_type' as const,
+                description: `Unsupported grant_type '${grantType}'.`,
+              }
+      if (!result.ok) return oauthError(result.error, result.description, 400)
+      const signedIn = (result as { user?: UserRow }).user
+      if (grantType === DEVICE_CODE_GRANT && signedIn)
+        await audit({ action: 'SignIn', user: signedIn, detail: 'Device sign-in' }, request)
+      return Response.json({
+        access_token: result.grant.accessToken,
+        refresh_token: result.grant.refreshToken,
+        token_type: 'Bearer',
+        expires_in: result.grant.expiresIn,
+        issued_at: result.grant.issuedAt,
+        scope: DEFAULT_SCOPE,
+      })
+    }
+
     if (clientId !== BACKOFFICE_CLIENT_ID) {
       return oauthError('invalid_client', `Unknown client '${clientId}'.`)
     }
@@ -447,6 +477,101 @@ export function createAuthRoutes(options: AuthRouteOptions): AuthRoutes {
     return response
   }
 
+  /** RFC 8628's device authorization endpoint: the codes the CLI shows and polls with. */
+  async function handleDeviceAuthorization(request: Request, url: URL): Promise<Response> {
+    const form = new URLSearchParams(await request.text())
+    if ((form.get('client_id') ?? '') !== REMOTE_CLIENT_ID)
+      return oauthError('invalid_client', `Unknown client '${form.get('client_id') ?? ''}'.`, 401)
+    const name = form.get('client_name')?.slice(0, 200) || null
+    const started = await service.startDeviceAuthorization(REMOTE_CLIENT_ID, name)
+    const verification = `${url.origin}${options.backOfficePath}/device`
+    return Response.json({
+      device_code: started.deviceCode,
+      user_code: started.userCode,
+      verification_uri: verification,
+      verification_uri_complete: `${verification}?user_code=${encodeURIComponent(started.userCode)}`,
+      expires_in: started.expiresIn,
+      interval: started.interval,
+    })
+  }
+
+  /** The signed-in back-office person, from the session cookie, or undefined. */
+  async function sessionUser(request: Request): Promise<number | undefined> {
+    const sessionId = readCookie(request, names.session)
+    return sessionId ? (await service.resolveSession(sessionId))?.userId : undefined
+  }
+
+  /** A cookie-authenticated write must come from this site, not a form elsewhere. */
+  const sameSite = (request: Request) => {
+    const site = request.headers.get('sec-fetch-site')
+    if (site) return site === 'same-origin'
+    const origin = request.headers.get('origin')
+    return !origin || origin === new URL(request.url).origin
+  }
+
+  const signInFirst = () => problemResponse(problemDetails({ title: 'Sign in first', status: 401 }))
+
+  /** What the approval page shows for a code, and its decision. */
+  async function handleDevicePage(
+    request: Request,
+    url: URL,
+    action: string,
+  ): Promise<Response | undefined> {
+    const userId = await sessionUser(request)
+    if (!userId) return signInFirst()
+    if (action === 'device/pending' && request.method === 'GET') {
+      const pending = await service.pendingDevice(url.searchParams.get('user_code') ?? '')
+      if (!pending)
+        return problemResponse(
+          problemDetails({
+            title: 'That code is not waiting',
+            status: 404,
+            detail:
+              'It may have expired or been used. Start the sign-in again from the command line.',
+          }),
+        )
+      return Response.json({
+        userCode: pending.userCode,
+        clientName: pending.clientName,
+        expiresAt: pending.expiresAt.toISOString(),
+      })
+    }
+    if (action === 'device/decide' && request.method === 'POST') {
+      if (!sameSite(request)) return new Response('Forbidden', { status: 403 })
+      const body = (await request.json().catch(() => ({}))) as {
+        userCode?: unknown
+        approve?: unknown
+      }
+      const decided = await service.decideDevice(
+        typeof body.userCode === 'string' ? body.userCode : '',
+        userId,
+        body.approve === true,
+      )
+      return decided
+        ? new Response(null, { status: 204 })
+        : problemResponse(problemDetails({ title: 'That code is not waiting', status: 404 }))
+    }
+    if (action === 'devices' && request.method === 'GET') {
+      const devices = await service.signedInDevices(userId)
+      return Response.json(
+        devices.map((device) => ({
+          id: device.id,
+          name: device.clientName,
+          signedInAt: device.signedInAt.toISOString(),
+          lastUsedAt: device.lastUsedAt?.toISOString() ?? null,
+        })),
+      )
+    }
+    const revoking = /^devices\/(\d+)$/.exec(action)
+    if (revoking && request.method === 'DELETE') {
+      if (!sameSite(request)) return new Response('Forbidden', { status: 403 })
+      return (await service.revokeDevice(Number(revoking[1]), userId))
+        ? new Response(null, { status: 204 })
+        : problemResponse(problemDetails({ title: 'No such device', status: 404 }))
+    }
+    return undefined
+  }
+
   return {
     async handle(request, pathname) {
       if (!pathname.startsWith(`${prefix}/`)) return undefined
@@ -460,6 +585,10 @@ export function createAuthRoutes(options: AuthRouteOptions): AuthRoutes {
       if (action === 'signout') return handleSignOut(request, url)
       if (action === 'verify-2fa' && request.method === 'POST')
         return handleVerifyTwoFactor(request)
+      if (action === 'device' && request.method === 'POST')
+        return handleDeviceAuthorization(request, url)
+      if (action.startsWith('device/') || action === 'devices' || action.startsWith('devices/'))
+        return handleDevicePage(request, url, action)
       return undefined
     },
   }

package/src/service.ts

@@ -3,6 +3,12 @@
  * actually sends. See docs/backoffice-hosting.md for the wire contract.
  */
 import { type ExtensionSectionAlias, type SectionAlias, toSectionAliases } from '@crombolo/core'
+import {
+  DEVICE_CODE_SECONDS,
+  DEVICE_POLL_SECONDS,
+  type DeviceAuthorizationRow,
+  type SignedInDevice,
+} from './device.ts'
 import { hashPassword, isNativeHash, passwordConfigJson, verifyPassword } from './password.ts'
 import { type CodeChallengeMethod, generateToken, verifyChallenge } from './pkce.ts'
 import type { AuthStore, UserRow } from './store.ts'
@@ -71,6 +77,11 @@ export type TokenError =
   | 'invalid_request'
   | 'invalid_client'
   | 'unauthorized_client'
+  // RFC 8628's answers while a device sign-in waits.
+  | 'authorization_pending'
+  | 'slow_down'
+  | 'expired_token'
+  | 'access_denied'
 
 export type TokenResult =
   | { ok: true; grant: TokenGrant }
@@ -377,6 +388,83 @@ export class AuthService {
     return this.signOut(token.sessionId)
   }
 
+  /** Starts a device sign-in (RFC 8628): the codes, and how often the client may poll. */
+  async startDeviceAuthorization(
+    clientId: string,
+    clientName: string | null,
+  ): Promise<{ deviceCode: string; userCode: string; expiresIn: number; interval: number }> {
+    const created = await this.#store.devices.create({ clientId, clientName, scope: DEFAULT_SCOPE })
+    return {
+      deviceCode: created.deviceCode,
+      userCode: created.userCode,
+      expiresIn: DEVICE_CODE_SECONDS,
+      interval: DEVICE_POLL_SECONDS,
+    }
+  }
+
+  /** A device sign-in waiting for a person, by the code they typed; undefined once it is not. */
+  async pendingDevice(userCode: string): Promise<DeviceAuthorizationRow | undefined> {
+    const row = await this.#store.devices.byUserCode(userCode)
+    if (row?.status !== 'pending' || row.expiresAt.getTime() < Date.now()) return undefined
+    return row
+  }
+
+  /** Approves or denies a waiting device sign-in for the signed-in person. */
+  async decideDevice(userCode: string, userId: number, approve: boolean): Promise<boolean> {
+    const row = await this.pendingDevice(userCode)
+    return row ? this.#store.devices.decide(row.id, userId, approve) : false
+  }
+
+  /**
+   * The device's poll: pending until a person decides, then the tokens, once.
+   * Polling faster than the interval answers `slow_down` and lengthens it, as
+   * RFC 8628 says.
+   */
+  async pollDevice(
+    deviceCode: string,
+    clientId: string,
+  ): Promise<TokenResult & { user?: UserRow }> {
+    const row = await this.#store.devices.byDeviceCode(deviceCode)
+    if (!row || row.clientId !== clientId)
+      return { ok: false, error: 'invalid_grant', description: 'Unknown device code.' }
+    if (row.status === 'denied')
+      return { ok: false, error: 'access_denied', description: 'The sign-in was declined.' }
+    if (row.status === 'issued')
+      return { ok: false, error: 'invalid_grant', description: 'This device code has been used.' }
+    if (row.expiresAt.getTime() < Date.now())
+      return { ok: false, error: 'expired_token', description: 'The device code has expired.' }
+    if (row.status === 'pending') {
+      const tooSoon =
+        row.lastPolledAt !== undefined &&
+        Date.now() - row.lastPolledAt.getTime() < row.intervalSeconds * 1000
+      await this.#store.devices.polled(row.id, row.intervalSeconds + (tooSoon ? 5 : 0))
+      return tooSoon
+        ? { ok: false, error: 'slow_down', description: 'Poll less often.' }
+        : { ok: false, error: 'authorization_pending', description: 'Waiting for approval.' }
+    }
+    const user = row.userId === null ? undefined : await this.#store.findUserById(row.userId)
+    if (!user || user.isLockedOut || !user.isApproved)
+      return { ok: false, error: 'access_denied', description: 'This account cannot sign in.' }
+    const sessionId = crypto.randomUUID()
+    if (!(await this.#store.devices.issued(row.id, sessionId)))
+      return { ok: false, error: 'invalid_grant', description: 'This device code has been used.' }
+    await this.#store.recordLoginSuccess(user.id, sessionId)
+    return { ok: true, grant: await this.#issue(user.id, sessionId, clientId, row.scope), user }
+  }
+
+  /** The devices signed in as this user. */
+  signedInDevices(userId: number): Promise<SignedInDevice[]> {
+    return this.#store.devices.signedIn(userId)
+  }
+
+  /** Signs a device out, ending its session; false when it is not this user's. */
+  async revokeDevice(id: number, userId: number): Promise<boolean> {
+    const row = await this.#store.devices.byId(id)
+    if (!row || row.userId !== userId || !row.sessionId) return false
+    await this.#store.endSession(row.sessionId)
+    return true
+  }
+
   async #issue(
     userId: number,
     sessionId: string,

package/src/store.ts

@@ -5,6 +5,7 @@
  * usable credential.
  */
 import { type Db, DbDate, fromDbBool, Locks } from '@crombolo/data'
+import { DeviceStore } from './device.ts'
 import { hashToken } from './pkce.ts'
 
 export interface UserRow {
@@ -88,9 +89,12 @@ const USER_COLUMNS =
 
 export class AuthStore {
   #db: Db
+  /** Device sign-ins (story 107), beside the sessions they become. */
+  readonly devices: DeviceStore
 
   constructor(db: Db) {
     this.#db = db
+    this.devices = new DeviceStore(db)
   }
 
   async findUserByLogin(login: string): Promise<UserRow | undefined> {