slauthjs 0.0.0-stage → 1.0.0

package/src/passkey/webauthn.js

@@ -0,0 +1,183 @@
+import { decodeCbor } from './cbor.js'
+import { base64Url, concat, fromBase64Url, sha256 } from '../util.js'
+
+/**
+ * WebAuthn (passkeys), the parts a server needs, with Web Crypto only:
+ *
+ * - registration: check the browser's answer to navigator.credentials.create() and pull
+ *   out the new public key;
+ * - sign-in: check a signature from navigator.credentials.get() with that key.
+ *
+ * Attestation is not checked ("none"): for a personal project what matters is that the
+ * same passkey signs in later, not which company made the authenticator.
+ *
+ * Supports ES256 (every platform passkey) and RS256 (some Windows Hello keys).
+ */
+
+export const ES256 = -7
+export const RS256 = -257
+
+const FLAG_UP = 0x01
+const FLAG_UV = 0x04
+const FLAG_AT = 0x40
+
+/**
+ * @typedef {{ origin: string | string[], rpId: string, challenge: string, requireUserVerification?: boolean }} Expect
+ * @typedef {{ id: string, publicKey: JsonWebKey, alg: number, counter: number, transports?: string[] }} Credential
+ */
+
+/**
+ * Checks a registration response.
+ * @param {{ id: string, rawId?: string, type: string, response: { clientDataJSON: string, attestationObject: string, transports?: string[] } }} credential
+ * @param {Expect} expect
+ * @returns {Promise<Credential>}
+ */
+export async function verifyRegistration(credential, expect) {
+  if (credential?.type !== 'public-key' || typeof credential.id !== 'string') throw new PasskeyError('Not a passkey.')
+  await checkClientData(credential.response?.clientDataJSON, 'webauthn.create', expect)
+
+  const attestation = decodeCbor(fromBase64Url(credential.response.attestationObject)).value
+  if (!(attestation instanceof Map) || !(attestation.get('authData') instanceof Uint8Array)) {
+    throw new PasskeyError('The attestation is malformed.')
+  }
+  const auth = await parseAuthData(attestation.get('authData'), expect)
+  if (!auth.credentialId || !auth.coseKey) throw new PasskeyError('No new credential in the response.')
+  if (base64Url(auth.credentialId) !== credential.id) throw new PasskeyError('Credential id mismatch.')
+
+  const { jwk, alg } = coseToJwk(auth.coseKey)
+  // Make sure Web Crypto accepts the key now, rather than at the first sign-in.
+  await importKey(jwk, alg)
+  const transports = Array.isArray(credential.response.transports) ? credential.response.transports.filter((t) => typeof t === 'string') : undefined
+  return { id: credential.id, publicKey: jwk, alg, counter: auth.signCount, transports }
+}
+
+/**
+ * Checks a sign-in (assertion) response against a stored credential.
+ * @param {{ id: string, type: string, response: { clientDataJSON: string, authenticatorData: string, signature: string, userHandle?: string | null } }} assertion
+ * @param {Credential} stored
+ * @param {Expect} expect
+ * @returns {Promise<{ counter: number }>}  the new signature counter to store
+ */
+export async function verifyAuthentication(assertion, stored, expect) {
+  if (assertion?.type !== 'public-key' || assertion.id !== stored.id) throw new PasskeyError('Not the expected passkey.')
+  const clientDataBytes = fromBase64Url(assertion.response?.clientDataJSON ?? '')
+  await checkClientData(assertion.response.clientDataJSON, 'webauthn.get', expect)
+
+  const authData = fromBase64Url(assertion.response.authenticatorData)
+  const auth = await parseAuthData(authData, expect)
+
+  const signed = concat(authData, await sha256(clientDataBytes))
+  let signature = fromBase64Url(assertion.response.signature)
+  const key = await importKey(stored.publicKey, stored.alg)
+  if (stored.alg === ES256) signature = derToRaw(signature)
+  const algorithm = stored.alg === ES256 ? { name: 'ECDSA', hash: 'SHA-256' } : { name: 'RSASSA-PKCS1-v1_5' }
+  if (!(await crypto.subtle.verify(algorithm, key, signature, signed))) throw new PasskeyError('The signature is wrong.')
+
+  // A counter that goes backwards means the passkey was copied. Many passkeys always
+  // send 0, which means "no counter" and is fine.
+  if ((auth.signCount !== 0 || stored.counter !== 0) && auth.signCount <= stored.counter) {
+    throw new PasskeyError('This passkey may have been cloned (its counter went backwards).')
+  }
+  return { counter: auth.signCount }
+}
+
+export class PasskeyError extends Error {}
+
+/** The challenge a response answers, so the server can look up what it sent. */
+export function readChallenge(clientDataJSON) {
+  try {
+    const challenge = JSON.parse(new TextDecoder().decode(fromBase64Url(clientDataJSON))).challenge
+    return typeof challenge === 'string' ? challenge : null
+  } catch {
+    return null
+  }
+}
+
+async function checkClientData(encoded, type, expect) {
+  let data
+  try {
+    data = JSON.parse(new TextDecoder().decode(fromBase64Url(encoded)))
+  } catch {
+    throw new PasskeyError('clientDataJSON is malformed.')
+  }
+  if (data.type !== type) throw new PasskeyError(`Expected a ${type} response.`)
+  if (data.challenge !== expect.challenge) throw new PasskeyError('The challenge does not match.')
+  const origins = [expect.origin].flat()
+  if (!origins.includes(data.origin)) throw new PasskeyError(`Unexpected origin ${data.origin}.`)
+  if (data.crossOrigin === true) throw new PasskeyError('Cross-origin passkey requests are not allowed.')
+  return data
+}
+
+async function parseAuthData(bytes, expect) {
+  if (bytes.length < 37) throw new PasskeyError('authenticatorData is too short.')
+  const rpIdHash = bytes.subarray(0, 32)
+  const flags = bytes[32]
+  const signCount = new DataView(bytes.buffer, bytes.byteOffset + 33, 4).getUint32(0)
+
+  const expected = await sha256(expect.rpId)
+  if (base64Url(rpIdHash) !== base64Url(expected)) throw new PasskeyError('The passkey is for a different site (rpId).')
+  if (!(flags & FLAG_UP)) throw new PasskeyError('The user was not present.')
+  if (expect.requireUserVerification && !(flags & FLAG_UV)) throw new PasskeyError('The user was not verified.')
+
+  const out = { flags, signCount, credentialId: null, coseKey: null }
+  if (flags & FLAG_AT) {
+    let at = 37 + 16 // skip the AAGUID
+    if (bytes.length < at + 2) throw new PasskeyError('authenticatorData is truncated.')
+    const idLength = (bytes[at] << 8) | bytes[at + 1]
+    at += 2
+    if (bytes.length < at + idLength) throw new PasskeyError('authenticatorData is truncated.')
+    out.credentialId = bytes.slice(at, at + idLength)
+    at += idLength
+    out.coseKey = decodeCbor(bytes, at).value
+  }
+  return out
+}
+
+/** COSE_Key (RFC 9053) -> JWK. */
+function coseToJwk(cose) {
+  if (!(cose instanceof Map)) throw new PasskeyError('The public key is malformed.')
+  const kty = cose.get(1)
+  const alg = cose.get(3)
+  if (kty === 2 && alg === ES256 && cose.get(-1) === 1) {
+    const x = cose.get(-2)
+    const y = cose.get(-3)
+    if (!(x instanceof Uint8Array) || !(y instanceof Uint8Array) || x.length !== 32 || y.length !== 32) {
+      throw new PasskeyError('The P-256 key is malformed.')
+    }
+    return { alg, jwk: { kty: 'EC', crv: 'P-256', x: base64Url(x), y: base64Url(y) } }
+  }
+  if (kty === 3 && alg === RS256) {
+    const n = cose.get(-1)
+    const e = cose.get(-2)
+    if (!(n instanceof Uint8Array) || !(e instanceof Uint8Array)) throw new PasskeyError('The RSA key is malformed.')
+    return { alg, jwk: { kty: 'RSA', n: base64Url(n), e: base64Url(e), alg: 'RS256' } }
+  }
+  throw new PasskeyError(`Unsupported passkey algorithm (${alg}).`)
+}
+
+function importKey(jwk, alg) {
+  const algorithm = alg === ES256 ? { name: 'ECDSA', namedCurve: 'P-256' } : { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }
+  return crypto.subtle.importKey('jwk', jwk, algorithm, false, ['verify'])
+}
+
+/** ECDSA signatures arrive DER-encoded; Web Crypto wants r || s, 32 bytes each. */
+function derToRaw(der) {
+  const fail = () => {
+    throw new PasskeyError('The signature is malformed.')
+  }
+  if (der[0] !== 0x30) fail()
+  let at = 2
+  if (der[1] & 0x80) at = 2 + (der[1] & 0x7f)
+  const int = () => {
+    if (der[at] !== 0x02) fail()
+    const len = der[at + 1]
+    let value = der.subarray(at + 2, at + 2 + len)
+    at += 2 + len
+    while (value.length > 32 && value[0] === 0) value = value.subarray(1)
+    if (value.length > 32) fail()
+    const out = new Uint8Array(32)
+    out.set(value, 32 - value.length)
+    return out
+  }
+  return concat(int(), int())
+}

package/src/session.js

@@ -0,0 +1,49 @@
+import { base64Url, randomToken, readCookie, serializeCookie, sha256 } from './util.js'
+
+const DAY = 24 * 60 * 60
+
+/**
+ * Sessions: a random token in an HttpOnly cookie. Only a SHA-256 of the token is
+ * stored, so a leaked database can't be used to sign in. Sessions slide: each day
+ * someone uses the app, the 30 days start again.
+ *
+ * @param {{ store: import('./index.js').Store, cookie: string, days: number }} options
+ */
+export function createSessions({ store, cookie, days }) {
+  const ttl = days * DAY
+  const keyFor = async (token) => `session:${base64Url(await sha256(token))}`
+  const secure = (request) => new URL(request.url).protocol === 'https:'
+
+  return {
+    /** Starts a session; returns the Set-Cookie value. */
+    async create(userId, request) {
+      const token = randomToken()
+      const now = Date.now()
+      await store.put(await keyFor(token), { userId, createdAt: now, refreshedAt: now }, { ttl })
+      return serializeCookie(cookie, token, { maxAge: ttl, secure: secure(request) })
+    },
+
+    /** The session behind this request, or null. */
+    async read(request) {
+      const token = readCookie(request.headers.get('cookie'), cookie)
+      if (!token || token.length > 128) return null
+      const session = await store.get(await keyFor(token))
+      return session ? { ...session, token } : null
+    },
+
+    /** Restarts the 30 days at most once a day; returns a Set-Cookie value when it did. */
+    async refresh(session, request) {
+      if (Date.now() - session.refreshedAt < DAY * 1000) return null
+      const { token, ...value } = session
+      await store.put(await keyFor(token), { ...value, refreshedAt: Date.now() }, { ttl })
+      return serializeCookie(cookie, token, { maxAge: ttl, secure: secure(request) })
+    },
+
+    /** Ends this request's session; returns the Set-Cookie value that clears it. */
+    async destroy(request) {
+      const token = readCookie(request.headers.get('cookie'), cookie)
+      if (token && token.length <= 128) await store.delete(await keyFor(token))
+      return serializeCookie(cookie, '', { maxAge: 0, secure: secure(request) })
+    },
+  }
+}

package/src/stores/d1.d.ts

@@ -0,0 +1 @@
+export { d1 } from './index.js'

package/src/stores/d1.js

@@ -0,0 +1,44 @@
+/**
+ * Cloudflare D1. Creates its own table (`slauth_kv`) on first use, so there are no
+ * migrations to run; it sits happily next to your app's own tables.
+ *
+ * @param {D1Database} db  the D1 binding, e.g. env.DB
+ * @param {{ table?: string }} [options]
+ * @returns {import('../index.js').Store}
+ */
+export function d1(db, { table = 'slauth_kv' } = {}) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) throw new Error(`slauth: "${table}" isn't a valid table name.`)
+  let ready = null
+  const init = () =>
+    (ready ??= db
+      .prepare(`CREATE TABLE IF NOT EXISTS ${table} (key TEXT PRIMARY KEY, value TEXT NOT NULL, expires_at INTEGER)`)
+      .run()
+      .catch((err) => {
+        ready = null
+        throw err
+      }))
+
+  return {
+    async get(key) {
+      await init()
+      const row = await db.prepare(`SELECT value, expires_at FROM ${table} WHERE key = ?`).bind(key).first()
+      if (!row) return null
+      if (row.expires_at !== null && row.expires_at <= Date.now()) {
+        await db.prepare(`DELETE FROM ${table} WHERE key = ?`).bind(key).run()
+        return null
+      }
+      return JSON.parse(row.value)
+    },
+    async put(key, value, { ttl } = {}) {
+      await init()
+      await db
+        .prepare(`INSERT INTO ${table} (key, value, expires_at) VALUES (?, ?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value, expires_at = excluded.expires_at`)
+        .bind(key, JSON.stringify(value), ttl ? Date.now() + ttl * 1000 : null)
+        .run()
+    },
+    async delete(key) {
+      await init()
+      await db.prepare(`DELETE FROM ${table} WHERE key = ?`).bind(key).run()
+    },
+  }
+}

package/src/stores/index.d.ts

@@ -0,0 +1,5 @@
+import type { Store } from '../index.js'
+export function memory(): Store
+export function d1(db: { prepare(sql: string): any }, options?: { table?: string }): Store
+export function kv(namespace: { get(key: string, type: 'json'): Promise<any>; put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>; delete(key: string): Promise<void> }, options?: { prefix?: string }): Store
+export function sqlite(db: { prepare(sql: string): { get(...args: unknown[]): any; run(...args: unknown[]): unknown } }, options?: { table?: string }): Store

package/src/stores/kv.d.ts

@@ -0,0 +1 @@
+export { kv } from './index.js'

package/src/stores/kv.js

@@ -0,0 +1,18 @@
+/**
+ * Cloudflare Workers KV. Fine for small projects; note KV is eventually consistent
+ * (a sign-in can take a moment to be seen in other regions) and its free tier allows
+ * 1,000 writes a day. D1 is the better default on Workers.
+ *
+ * @param {KVNamespace} namespace  the KV binding, e.g. env.AUTH
+ * @param {{ prefix?: string }} [options]
+ * @returns {import('../index.js').Store}
+ */
+export function kv(namespace, { prefix = 'slauth:' } = {}) {
+  return {
+    get: (key) => namespace.get(prefix + key, 'json'),
+    // KV can't expire anything sooner than 60 seconds.
+    put: (key, value, { ttl } = {}) =>
+      namespace.put(prefix + key, JSON.stringify(value), ttl ? { expirationTtl: Math.max(60, Math.ceil(ttl)) } : undefined),
+    delete: (key) => namespace.delete(prefix + key),
+  }
+}

package/src/stores/memory.d.ts

@@ -0,0 +1 @@
+export { memory } from './index.js'

package/src/stores/memory.js

@@ -0,0 +1,30 @@
+/**
+ * Keeps everything in memory. Lovely for tests and trying things out; everything is
+ * forgotten when the process restarts, so use a real store before you ship.
+ *
+ * @returns {import('../index.js').Store}
+ */
+export function memory() {
+  const rows = new Map()
+  const live = (key) => {
+    const row = rows.get(key)
+    if (!row) return null
+    if (row.expiresAt !== null && row.expiresAt <= Date.now()) {
+      rows.delete(key)
+      return null
+    }
+    return row
+  }
+  return {
+    async get(key) {
+      const row = live(key)
+      return row ? structuredClone(row.value) : null
+    },
+    async put(key, value, { ttl } = {}) {
+      rows.set(key, { value: structuredClone(value), expiresAt: ttl ? Date.now() + ttl * 1000 : null })
+    },
+    async delete(key) {
+      rows.delete(key)
+    },
+  }
+}

package/src/stores/sqlite.d.ts

@@ -0,0 +1 @@
+export { sqlite } from './index.js'

package/src/stores/sqlite.js

@@ -0,0 +1,35 @@
+/**
+ * Any synchronous SQLite handle with `prepare(sql).get(...)` / `.run(...)`: bun:sqlite,
+ * better-sqlite3 and node:sqlite all fit. Creates its own table on first use.
+ *
+ * @param {{ prepare(sql: string): { get(...args: unknown[]): any, run(...args: unknown[]): unknown } }} db
+ * @param {{ table?: string }} [options]
+ * @returns {import('../index.js').Store}
+ */
+export function sqlite(db, { table = 'slauth_kv' } = {}) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) throw new Error(`slauth: "${table}" isn't a valid table name.`)
+  db.prepare(`CREATE TABLE IF NOT EXISTS ${table} (key TEXT PRIMARY KEY, value TEXT NOT NULL, expires_at INTEGER)`).run()
+  const select = db.prepare(`SELECT value, expires_at FROM ${table} WHERE key = ?`)
+  const upsert = db.prepare(
+    `INSERT INTO ${table} (key, value, expires_at) VALUES (?, ?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value, expires_at = excluded.expires_at`,
+  )
+  const remove = db.prepare(`DELETE FROM ${table} WHERE key = ?`)
+
+  return {
+    async get(key) {
+      const row = select.get(key)
+      if (!row) return null
+      if (row.expires_at !== null && row.expires_at <= Date.now()) {
+        remove.run(key)
+        return null
+      }
+      return JSON.parse(row.value)
+    },
+    async put(key, value, { ttl } = {}) {
+      upsert.run(key, JSON.stringify(value), ttl ? Date.now() + ttl * 1000 : null)
+    },
+    async delete(key) {
+      remove.run(key)
+    },
+  }
+}

package/src/users.js

@@ -0,0 +1,56 @@
+import { base64Url } from './util.js'
+
+/**
+ * People. A user is just `{ id, email, createdAt }`; keep anything else about them in
+ * your own tables, keyed by `user.id`.
+ *
+ *   user:<id>      the user
+ *   email:<email>  -> id
+ *
+ * @param {import('./index.js').Store} store
+ * @param {undefined | string[] | ((email: string) => boolean | Promise<boolean>)} allow
+ */
+export function createUsers(store, allow) {
+  const list = Array.isArray(allow) ? allow.map((e) => e.trim().toLowerCase()) : null
+
+  async function allowed(email) {
+    if (typeof allow === 'function') return Boolean(await allow(email))
+    if (!list) return true
+    // "@family.com" lets in anyone at that domain.
+    return list.includes(email) || list.some((entry) => entry.startsWith('@') && email.endsWith(entry))
+  }
+
+  return {
+    allowed,
+
+    async byId(id) {
+      return store.get(`user:${id}`)
+    },
+
+    async byEmail(email) {
+      const id = await store.get(`email:${normalizeEmail(email)}`)
+      return id ? store.get(`user:${id}`) : null
+    },
+
+    /** The user with this email, created on first sign-in. Null when they aren't allowed in. */
+    async signIn(rawEmail) {
+      const email = normalizeEmail(rawEmail)
+      if (!(await allowed(email))) return null
+      const existing = await this.byEmail(email)
+      if (existing) return existing
+      const user = { id: `usr_${base64Url(crypto.getRandomValues(new Uint8Array(15)))}`, email, createdAt: Date.now() }
+      await store.put(`user:${user.id}`, user)
+      await store.put(`email:${email}`, user.id)
+      return user
+    },
+  }
+}
+
+export function normalizeEmail(email) {
+  return String(email ?? '').trim().toLowerCase()
+}
+
+/** Deliberately loose: one @, something either side, a dot in the domain, no spaces. */
+export function validEmail(email) {
+  return typeof email === 'string' && email.length <= 254 && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
+}

package/src/util.js

@@ -0,0 +1,69 @@
+/** Small helpers shared across slauth. Web Crypto only, so they run anywhere. */
+
+export function readCookie(header, name) {
+  for (const part of (header ?? '').split(';')) {
+    const [key, ...rest] = part.trim().split('=')
+    if (key === name) return rest.join('=')
+  }
+  return null
+}
+
+export function randomToken() {
+  return base64Url(crypto.getRandomValues(new Uint8Array(32)).buffer)
+}
+
+export function base64Url(buffer) {
+  let binary = ''
+  for (const byte of new Uint8Array(buffer)) binary += String.fromCharCode(byte)
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+/** Compares without stopping at the first difference, so timing gives nothing away. */
+export function safeEqual(a, b) {
+  if (a.length !== b.length) return false
+  let diff = 0
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i)
+  return diff === 0
+}
+
+export function fromBase64Url(text) {
+  const base64 = String(text).replace(/-/g, '+').replace(/_/g, '/')
+  const binary = atob(base64 + '='.repeat((4 - (base64.length % 4)) % 4))
+  return Uint8Array.from(binary, (c) => c.charCodeAt(0))
+}
+
+const encoder = new TextEncoder()
+
+export async function sha256(data) {
+  return new Uint8Array(await crypto.subtle.digest('SHA-256', typeof data === 'string' ? encoder.encode(data) : data))
+}
+
+export async function hmac(secret, message) {
+  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(message)))
+}
+
+/** A Set-Cookie value. maxAge null makes a browser-session cookie; 0 deletes it. */
+export function serializeCookie(name, value, { maxAge = null, secure = true, sameSite = 'Lax', path = '/' } = {}) {
+  const parts = [`${name}=${value}`, `Path=${path}`, 'HttpOnly', `SameSite=${sameSite}`]
+  if (maxAge !== null) parts.push(`Max-Age=${maxAge}`)
+  if (secure) parts.push('Secure')
+  return parts.join('; ')
+}
+
+export function json(body, status = 200, headers = {}) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', ...headers },
+  })
+}
+
+export function concat(...parts) {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0))
+  let at = 0
+  for (const part of parts) {
+    out.set(part, at)
+    at += part.length
+  }
+  return out
+}