slauthjs 0.0.0-stage → 1.0.0

package/src/index.d.ts

@@ -0,0 +1,149 @@
+/** A key-value store: the only thing slauth needs from your database. */
+export interface Store {
+  get(key: string): Promise<any>
+  /** ttl is in seconds. */
+  put(key: string, value: unknown, options?: { ttl?: number }): Promise<void>
+  delete(key: string): Promise<void>
+}
+
+/** Sends the sign-in email. `subject`, `text` and `html` are ready to use. */
+export interface EmailSender {
+  send(message: { to: string; code: string; appName: string; subject: string; text: string; html: string }): Promise<void>
+}
+
+export interface SlauthUser {
+  id: string
+  email: string
+  createdAt: number
+}
+
+export interface SlauthConfig {
+  /** A random string of 16+ characters. Make one with: openssl rand -base64 32 */
+  secret: string
+  /** Where users, sessions and passkeys live: memory(), d1(env.DB), kv(env.KV), sqlite(db), or your own. */
+  store: Store
+  /** How codes are emailed. Defaults to printing them to the console. */
+  email?: EmailSender
+  /** Shown in emails and as the passkey's site name. */
+  appName?: string
+  /** Who may sign in: a list of emails ("@family.com" for a whole domain) or a function. Everyone, if left out. */
+  allow?: string[] | ((email: string) => boolean | Promise<boolean>)
+  /** Where the routes live. Default "/auth". */
+  basePath?: string
+  /** Session cookie name. Default "slauth_session". */
+  cookie?: string
+  /** Sessions last this many days after the last visit. Default 30. */
+  sessionDays?: number
+  /** Origins allowed to post to the routes (and to use passkeys). Default: the request's own origin. */
+  origins?: string | string[]
+  /** Passkey settings, or false to turn passkeys off. */
+  passkeys?:
+    | false
+    | {
+        /** The site passkeys belong to, e.g. "myapp.dev" (works for every subdomain). Default: the request's hostname. */
+        rpId?: string
+        rpName?: string
+        origin?: string | string[]
+        userVerification?: 'required' | 'preferred' | 'discouraged'
+      }
+  /** Also accept people signed in by Cloudflare Access. */
+  access?: { team: string; aud: string | string[]; devUser?: string; fetch?: typeof fetch }
+  /** Turn on the PIN app lock. true = off by default for each person; or set their default. */
+  lock?: true | { default?: Policy; cookie?: string }
+}
+
+export interface Slauth {
+  /** Answers every request under basePath (404 for anything else). */
+  handle(request: Request): Promise<Response>
+  /** The signed-in person, or null. Ignores the app lock. */
+  user(request: Request): Promise<SlauthUser | null>
+  /** The signed-in, unlocked person, or a 401 Response to return as it is. */
+  requireUser(request: Request): Promise<SlauthUser | Response>
+  store: Store
+}
+
+export function slauth(config: SlauthConfig): Slauth
+export function memory(): Store
+export function consoleEmail(): EmailSender
+
+/** What createAccess and createLock work with. */
+export interface User {
+  /** Lower-cased email from the Access sign-in. */
+  email: string
+  /** Stable, opaque id: the same in every app for the same email. */
+  userId: string
+}
+
+export interface AccessOptions {
+  /** "yourteam" or "yourteam.cloudflareaccess.com". */
+  teamDomain: string
+  /** The Application Audience (AUD) tag of the Access application(s). */
+  audience: string | string[]
+  /** Optional second check after the Access policy. */
+  allowedEmails?: string[]
+  /** email -> userId, to keep someone's data when their email changes. */
+  aliases?: Record<string, string>
+  /** Local development only: treat every request as this email. Never set in production. */
+  devUser?: string
+  fetch?: typeof fetch
+}
+
+export function createAccess(options: AccessOptions): {
+  /** The signed-in person, or null when the request did not come through Access. */
+  getUser(request: Request): Promise<User | null>
+}
+
+export function userIdFor(email: string): Promise<string>
+
+export type Policy = 'always' | 'daily' | 'weekly' | 'never'
+export const POLICIES: readonly Policy[]
+
+export interface LockDoc {
+  pinHash?: string
+  salt?: string
+  sessionKey: string
+  failures: number
+  lockedUntil: number
+  policy?: Policy
+}
+
+export interface LockStore {
+  get(userId: string): Promise<LockDoc | null>
+  put(userId: string, doc: LockDoc): Promise<void>
+}
+
+export interface LockReply {
+  status: number
+  body: Record<string, unknown>
+  /** A Set-Cookie header value, when the reply changes the unlock. */
+  cookie?: string
+}
+
+export interface LockOptions {
+  /** Cookie name; keep an app's old one so nobody is signed out twice. Default "slauth_lock". */
+  cookie?: string
+  /** For people who haven't chosen yet. Default "weekly". */
+  defaultPolicy?: Policy
+}
+
+export function createLock(
+  store: LockStore,
+  options?: LockOptions,
+): {
+  /**
+   * Routes: GET session, POST login | setup | logout | pin | policy.
+   * Returns null for any other route.
+   */
+  handle(
+    route: string,
+    method: string,
+    readBody: () => Promise<any>,
+    user: User,
+    cookieHeader: string | null | undefined,
+    secure: boolean,
+  ): Promise<LockReply | null>
+  isUnlocked(user: User, cookieHeader: string | null | undefined): Promise<boolean>
+}
+
+export function validPin(pin: unknown): pin is string
+export function validPolicy(policy: unknown): policy is Policy

package/src/index.js

@@ -0,0 +1,6 @@
+export { slauth } from './core.js'
+export { memory } from './stores/memory.js'
+export { consoleEmail } from './email/console.js'
+// The Cloudflare Access check and the PIN lock, usable on their own too.
+export { createAccess, userIdFor } from './access.js'
+export { createLock, validPin, validPolicy, POLICIES } from './lock.js'

package/src/lock.js

@@ -0,0 +1,225 @@
+/**
+ * The app lock: a 4-digit PIN that each person can ask an app to check again now and
+ * then, on top of the Access sign-in. Access says *who* you are; the lock guards an
+ * unlocked phone or iPad from whoever picks it up.
+ *
+ * Each person picks how often, per app:
+ *   always   every visit (the unlock ends when the browser closes, at most 12 hours)
+ *   daily    once a day
+ *   weekly   once a week
+ *   never    no PIN; the Access sign-in is enough
+ *
+ * Grown out of the Planda / LedgerFox PIN pad, and compatible with its stored hashes:
+ * a salted PBKDF2 hash, 5 free tries then a lock of 5 minutes doubling to an hour, and a
+ * signed HttpOnly cookie. The signing key is random and per person; changing the PIN
+ * replaces it, which locks that person's other devices.
+ */
+
+import { base64Url, randomToken, readCookie, safeEqual } from './util.js'
+
+const DAY = 24 * 60 * 60
+export const POLICIES = /** @type {const} */ (['always', 'daily', 'weekly', 'never'])
+const TTL_SECONDS = { always: DAY / 2, daily: DAY, weekly: 7 * DAY }
+const FREE_ATTEMPTS = 5
+const PBKDF2_ITERATIONS = 100_000
+
+export function validPin(pin) {
+  return typeof pin === 'string' && /^\d{4}$/.test(pin)
+}
+
+export function validPolicy(policy) {
+  return POLICIES.includes(policy)
+}
+
+/**
+ * @typedef {'always' | 'daily' | 'weekly' | 'never'} Policy
+ * @typedef {{ pinHash?: string, salt?: string, sessionKey: string, failures: number, lockedUntil: number, policy?: Policy }} LockDoc
+ * @typedef {{ get(userId: string): Promise<LockDoc | null>, put(userId: string, doc: LockDoc): Promise<void> }} LockStore
+ * @typedef {{ email: string, userId: string }} User
+ * @typedef {{ status: number, body: object, cookie?: string }} LockReply
+ */
+
+/**
+ * @param {LockStore} store  where each person's lock document lives
+ * @param {{ cookie?: string, defaultPolicy?: Policy }} [options]
+ *   cookie         the cookie name (keep an app's old one so nobody is signed out twice)
+ *   defaultPolicy  for people who haven't chosen yet; "weekly" unless set
+ */
+export function createLock(store, { cookie: cookieName = 'slauth_lock', defaultPolicy = 'weekly' } = {}) {
+  if (!validPolicy(defaultPolicy)) throw new Error(`slauth: unknown policy "${defaultPolicy}".`)
+
+  async function load(userId) {
+    const doc = await store.get(userId)
+    if (doc && typeof doc.sessionKey === 'string') return doc
+    const fresh = { sessionKey: randomToken(), failures: 0, lockedUntil: 0 }
+    await store.put(userId, fresh)
+    return fresh
+  }
+
+  const policyOf = (doc) => (validPolicy(doc.policy) ? doc.policy : defaultPolicy)
+  const pinIsSet = (doc) => Boolean(doc.pinHash && doc.salt)
+  const matches = async (doc, pin) => pinIsSet(doc) && safeEqual(await hashPin(pin, doc.salt), doc.pinHash)
+
+  async function unlockCookie(userId, doc, secure) {
+    const issued = String(Math.floor(Date.now() / 1000))
+    const value = `${issued}.${await sign(`${userId}.${issued}`, doc.sessionKey)}`
+    // "always" is a browser-session cookie; the others last as long as the longest policy,
+    // and the policy in force decides on each request whether the unlock still counts.
+    return cookie(cookieName, value, policyOf(doc) === 'always' ? null : TTL_SECONDS.weekly, secure)
+  }
+
+  /**
+   * True when this person may use the app right now: they chose "never", or they
+   * unlocked recently enough for their policy.
+   * @param {User} user
+   * @param {string | null | undefined} cookieHeader
+   */
+  async function isUnlocked(user, cookieHeader) {
+    const doc = await load(user.userId)
+    const policy = policyOf(doc)
+    if (policy === 'never') return true
+    if (!pinIsSet(doc)) return false
+
+    const [issued, signature] = (readCookie(cookieHeader, cookieName) ?? '').split('.')
+    const issuedAt = Number(issued)
+    if (!signature || !Number.isFinite(issuedAt)) return false
+    const age = Date.now() / 1000 - issuedAt
+    if (age < -60 || age > TTL_SECONDS[policy]) return false
+    // The user id is part of what's signed, so one person's cookie never unlocks another's.
+    return safeEqual(signature, await sign(`${user.userId}.${issued}`, doc.sessionKey))
+  }
+
+  async function savePin(userId, doc, pin, policy, secure) {
+    const salt = randomToken()
+    const next = { ...doc, pinHash: await hashPin(pin, salt), salt, sessionKey: randomToken(), failures: 0, lockedUntil: 0, policy }
+    await store.put(userId, next)
+    return unlockCookie(userId, next, secure)
+  }
+
+  /** @returns {Promise<LockReply>} */
+  async function login(user, guess, secure) {
+    if (!validPin(guess)) return { status: 400, body: { error: 'The PIN is 4 digits.' } }
+    const doc = await load(user.userId)
+    const now = Date.now()
+    if (!pinIsSet(doc)) return { status: 409, body: { error: 'No PIN has been created yet.', reason: 'no-pin' } }
+    if (doc.lockedUntil > now) {
+      return { status: 429, body: { error: 'Too many tries.', reason: 'locked', retryAt: doc.lockedUntil } }
+    }
+
+    if (await matches(doc, guess)) {
+      if (doc.failures !== 0 || doc.lockedUntil !== 0) await store.put(user.userId, { ...doc, failures: 0, lockedUntil: 0 })
+      return { status: 200, body: { ok: true }, cookie: await unlockCookie(user.userId, doc, secure) }
+    }
+
+    const failures = doc.failures + 1
+    const over = failures - FREE_ATTEMPTS
+    const lockedUntil = over >= 0 ? now + Math.min(60, 5 * 2 ** over) * 60_000 : 0
+    await store.put(user.userId, { ...doc, failures, lockedUntil })
+    return lockedUntil
+      ? { status: 429, body: { error: 'Too many tries.', reason: 'locked', retryAt: lockedUntil } }
+      : { status: 401, body: { error: 'Wrong PIN.', reason: 'wrong', attemptsLeft: FREE_ATTEMPTS - failures } }
+  }
+
+  /** First time in this app: choose a PIN (and optionally how often to ask for it). */
+  async function setup(user, pin, policy, secure) {
+    if (!validPin(pin)) return { status: 400, body: { error: 'The PIN is 4 digits.' } }
+    if (policy !== undefined && !validPolicy(policy)) return { status: 400, body: { error: 'Unknown lock setting.' } }
+    const doc = await load(user.userId)
+    if (pinIsSet(doc)) return { status: 409, body: { error: 'A PIN already exists.' } }
+    return { status: 200, body: { ok: true }, cookie: await savePin(user.userId, doc, pin, policy ?? policyOf(doc), secure) }
+  }
+
+  /** Change PIN from Settings. Not counted toward the lockout; locks this person's other devices. */
+  async function change(user, current, next, secure) {
+    if (!validPin(current) || !validPin(next)) return { status: 400, body: { error: 'PINs are 4 digits.' } }
+    const doc = await load(user.userId)
+    if (!(await matches(doc, current))) return { status: 403, body: { error: 'The current PIN is wrong.' } }
+    return { status: 200, body: { ok: true }, cookie: await savePin(user.userId, doc, next, policyOf(doc), secure) }
+  }
+
+  /**
+   * Change how often the PIN is asked for. With a PIN set, the current PIN is needed,
+   * so a borrowed unlocked device can't switch the lock off.
+   */
+  async function setPolicy(user, policy, pin, secure) {
+    if (!validPolicy(policy)) return { status: 400, body: { error: 'Unknown lock setting.' } }
+    const doc = await load(user.userId)
+    if (pinIsSet(doc)) {
+      if (!validPin(pin) || !(await matches(doc, pin))) return { status: 403, body: { error: 'The current PIN is wrong.' } }
+    } else if (policy !== 'never') {
+      return { status: 409, body: { error: 'Create a PIN first.', reason: 'no-pin' } }
+    }
+    const next = { ...doc, policy }
+    await store.put(user.userId, next)
+    const reply = { status: 200, body: { ok: true, policy } }
+    return pinIsSet(next) ? { ...reply, cookie: await unlockCookie(user.userId, next, secure) } : reply
+  }
+
+  /**
+   * The lock routes. `route` is the part after the app's prefix (e.g. "session" for
+   * /api/lock/session). Returns null for any other route.
+   * @param {string} route
+   * @param {string} method
+   * @param {() => Promise<any>} readBody
+   * @param {User} user  from Access
+   * @param {string | null | undefined} cookieHeader
+   * @param {boolean} secure  https, so the cookie gets the Secure flag
+   * @returns {Promise<LockReply | null>}
+   */
+  async function handle(route, method, readBody, user, cookieHeader, secure) {
+    if (route === 'session' && method === 'GET') {
+      const doc = await load(user.userId)
+      const policy = policyOf(doc)
+      return {
+        status: 200,
+        body: { email: user.email, policy, required: policy !== 'never', pinSet: pinIsSet(doc), unlocked: await isUnlocked(user, cookieHeader) },
+      }
+    }
+    if (route === 'login' && method === 'POST') return login(user, (await readBody())?.pin, secure)
+    if (route === 'setup' && method === 'POST') {
+      const body = await readBody()
+      if (body?.policy === 'never' && body?.pin === undefined) return setPolicy(user, 'never', undefined, secure)
+      return setup(user, body?.pin, body?.policy, secure)
+    }
+    if (route === 'logout' && method === 'POST') return { status: 200, body: { ok: true }, cookie: cookie(cookieName, '', 0, secure) }
+    if (route === 'pin' && method === 'POST') {
+      if (!(await isUnlocked(user, cookieHeader))) return { status: 401, body: { error: 'Please enter your PIN.' } }
+      const body = await readBody()
+      return change(user, body?.current, body?.next, secure)
+    }
+    if (route === 'policy' && method === 'POST') {
+      if (!(await isUnlocked(user, cookieHeader))) return { status: 401, body: { error: 'Please enter your PIN.' } }
+      const body = await readBody()
+      return setPolicy(user, body?.policy, body?.pin, secure)
+    }
+    return null
+  }
+
+  return { handle, isUnlocked }
+}
+
+function cookie(name, value, maxAge, secure) {
+  const age = maxAge === null ? '' : `; Max-Age=${maxAge}`
+  return `${name}=${value}; Path=/; HttpOnly; SameSite=Strict${age}${secure ? '; Secure' : ''}`
+}
+
+
+async function hashPin(pin, salt) {
+  const encoder = new TextEncoder()
+  const key = await crypto.subtle.importKey('raw', encoder.encode(pin), 'PBKDF2', false, ['deriveBits'])
+  const bits = await crypto.subtle.deriveBits(
+    { name: 'PBKDF2', hash: 'SHA-256', salt: encoder.encode(salt), iterations: PBKDF2_ITERATIONS },
+    key,
+    256,
+  )
+  return base64Url(bits)
+}
+
+async function sign(payload, secret) {
+  const encoder = new TextEncoder()
+  const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'])
+  return base64Url(await crypto.subtle.sign('HMAC', key, encoder.encode(payload)))
+}
+
+
+

package/src/node.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+export function toNodeHandler(auth: { handle(request: Request): Promise<Response> }): (req: IncomingMessage, res: ServerResponse, next?: (error?: unknown) => void) => Promise<void>
+export function toRequest(req: IncomingMessage): Promise<Request>

package/src/node.js

@@ -0,0 +1,67 @@
+/**
+ * Plain Node (node:http, Express, Connect): turns `auth.handle` into `(req, res, next)`.
+ *
+ *   import { toNodeHandler } from 'slauthjs/node'
+ *   app.use('/auth', toNodeHandler(auth))            // Express
+ *   const user = await auth.user(toRequest(req))     // in your own routes
+ *
+ * Everything else (Workers, Bun, Deno, Next.js, Astro, Hono) speaks Request/Response
+ * already and can call auth.handle(request) directly.
+ */
+
+/** @param {{ handle(request: Request): Promise<Response> }} auth */
+export function toNodeHandler(auth) {
+  return async (req, res, next) => {
+    try {
+      const response = await auth.handle(await toRequest(req))
+      res.statusCode = response.status
+      for (const [key, value] of response.headers) {
+        if (key.toLowerCase() === 'set-cookie') continue
+        res.setHeader(key, value)
+      }
+      const cookies = response.headers.getSetCookie?.() ?? []
+      if (cookies.length) res.setHeader('Set-Cookie', cookies)
+      res.end(Buffer.from(await response.arrayBuffer()))
+    } catch (error) {
+      if (next) next(error)
+      else {
+        res.statusCode = 500
+        res.end()
+      }
+    }
+  }
+}
+
+/**
+ * A Web Request from a Node IncomingMessage (body included).
+ * @param {import('node:http').IncomingMessage & { originalUrl?: string, body?: unknown }} req
+ */
+export async function toRequest(req) {
+  const proto = req.headers['x-forwarded-proto']?.toString().split(',')[0] ?? (req.socket?.encrypted ? 'https' : 'http')
+  const host = req.headers['x-forwarded-host']?.toString() ?? req.headers.host ?? 'localhost'
+  // Under app.use('/auth', ...) Express strips the prefix from req.url; originalUrl keeps it.
+  const url = new URL(req.originalUrl ?? req.url ?? '/', `${proto}://${host}`)
+
+  const headers = new Headers()
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value === undefined) continue
+    for (const v of [value].flat()) headers.append(key, v)
+  }
+
+  let body
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    // Express's json() may already have read the body.
+    if (req.body !== undefined && typeof req.body === 'object' && !Buffer.isBuffer(req.body)) body = JSON.stringify(req.body)
+    else {
+      const chunks = []
+      let size = 0
+      for await (const chunk of req) {
+        size += chunk.length
+        if (size > 1_000_000) throw new Error('slauth: request body too large.')
+        chunks.push(chunk)
+      }
+      body = Buffer.concat(chunks)
+    }
+  }
+  return new Request(url, { method: req.method, headers, body })
+}

package/src/passkey/cbor.js

@@ -0,0 +1,99 @@
+/**
+ * Just enough CBOR (RFC 8949) to read what authenticators send: integers, byte and
+ * text strings, arrays, maps, booleans, null and floats. Definite lengths only, which
+ * is all WebAuthn uses.
+ */
+
+/**
+ * Decodes one item from `bytes` starting at `offset`.
+ * @param {Uint8Array} bytes
+ * @returns {{ value: any, offset: number }}  the item and where the next one starts
+ */
+export function decodeCbor(bytes, offset = 0) {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  let at = offset
+
+  const need = (n) => {
+    if (at + n > bytes.length) throw new Error('CBOR: ran out of bytes.')
+  }
+
+  const length = (info) => {
+    if (info < 24) return info
+    if (info === 24) return need(1), view.getUint8(at++)
+    if (info === 25) return need(2), (at += 2), view.getUint16(at - 2)
+    if (info === 26) return need(4), (at += 4), view.getUint32(at - 4)
+    if (info === 27) {
+      need(8)
+      const big = view.getBigUint64(at)
+      at += 8
+      if (big > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error('CBOR: number too large.')
+      return Number(big)
+    }
+    throw new Error('CBOR: indefinite lengths are not supported.')
+  }
+
+  const item = (depth) => {
+    if (depth > 16) throw new Error('CBOR: nested too deeply.')
+    need(1)
+    const first = view.getUint8(at++)
+    const major = first >> 5
+    const info = first & 31
+    switch (major) {
+      case 0:
+        return length(info)
+      case 1:
+        return -1 - length(info)
+      case 2: {
+        const n = length(info)
+        need(n)
+        at += n
+        return bytes.slice(at - n, at)
+      }
+      case 3: {
+        const n = length(info)
+        need(n)
+        at += n
+        return new TextDecoder().decode(bytes.subarray(at - n, at))
+      }
+      case 4: {
+        const n = length(info)
+        const out = []
+        for (let i = 0; i < n; i++) out.push(item(depth + 1))
+        return out
+      }
+      case 5: {
+        const n = length(info)
+        const out = new Map()
+        for (let i = 0; i < n; i++) {
+          const key = item(depth + 1)
+          out.set(key, item(depth + 1))
+        }
+        return out
+      }
+      case 6:
+        // A tag: skip it and read what it wraps.
+        length(info)
+        return item(depth + 1)
+      case 7:
+        if (info === 20) return false
+        if (info === 21) return true
+        if (info === 22 || info === 23) return null
+        if (info === 25) return need(2), (at += 2), halfFloat(view.getUint16(at - 2))
+        if (info === 26) return need(4), (at += 4), view.getFloat32(at - 4)
+        if (info === 27) return need(8), (at += 8), view.getFloat64(at - 8)
+        throw new Error('CBOR: unsupported simple value.')
+    }
+  }
+
+  const value = item(0)
+  return { value, offset: at }
+}
+
+function halfFloat(bits) {
+  const exp = (bits >> 10) & 0x1f
+  const frac = bits & 0x3ff
+  const sign = bits & 0x8000 ? -1 : 1
+  if (exp === 0) return sign * 2 ** -14 * (frac / 1024)
+  if (exp === 31) return frac ? NaN : sign * Infinity
+  return sign * 2 ** (exp - 15) * (1 + frac / 1024)
+}