slauthjs 0.0.0-stage → 2.0.0

package/src/users.js

@@ -0,0 +1,126 @@
+import { randomId } from './util.js'
+
+/**
+ * People.
+ *
+ *   user:<id>      { id, email, name, image, roles, metadata, privateMetadata, createdAt, updatedAt, bannedAt }
+ *   email:<email>  -> id
+ *
+ * `metadata` is yours to fill and is sent to the browser; `privateMetadata` never leaves
+ * the server. Anything bigger belongs in your own tables, keyed by `user.id`.
+ *
+ * @param {import('./index.js').Store} store
+ * @param {undefined | string[] | ((email: string, context: object) => 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, context = {}) {
+    if (typeof allow === 'function') return Boolean(await allow(email, context))
+    if (!list) return true
+    // "@family.com" lets in anyone at that domain.
+    return list.includes(email) || list.some((entry) => entry.startsWith('@') && email.endsWith(entry))
+  }
+
+  async function byId(id) {
+    if (typeof id !== 'string') return null
+    const user = await store.get(`user:${id}`)
+    return user ? withDefaults(user) : null
+  }
+
+  async function byEmail(email) {
+    const id = await store.get(`email:${normalizeEmail(email)}`)
+    return id ? byId(id) : null
+  }
+
+  /** Makes a user; no allow-list check, so it's for sign-in flows that already did one, and for admins. */
+  async function create({ email: rawEmail, name = null, image = null, roles = [], metadata = {}, privateMetadata = {} }) {
+    const email = normalizeEmail(rawEmail)
+    if (!validEmail(email)) throw new Error(`slauth: "${rawEmail}" isn't an email address.`)
+    if (await store.get(`email:${email}`)) throw new Error(`slauth: there's already a user with ${email}.`)
+    const now = Date.now()
+    const user = { id: randomId('usr'), email, name, image, roles, metadata, privateMetadata, createdAt: now, updatedAt: now, bannedAt: null }
+    await store.put(`user:${user.id}`, user)
+    await store.put(`email:${email}`, user.id)
+    return user
+  }
+
+  /** Changes what's given; `email` moves the email index too. Returns the new user, or null. */
+  async function update(id, patch) {
+    const user = await byId(id)
+    if (!user) return null
+    const next = { ...user, updatedAt: Date.now() }
+    for (const key of ['name', 'image', 'roles', 'metadata', 'privateMetadata', 'bannedAt']) if (patch[key] !== undefined) next[key] = patch[key]
+    if (patch.email !== undefined) {
+      const email = normalizeEmail(patch.email)
+      if (!validEmail(email)) throw new Error(`slauth: "${patch.email}" isn't an email address.`)
+      if (email !== user.email) {
+        const owner = await store.get(`email:${email}`)
+        if (owner && owner !== id) throw new Error(`slauth: there's already a user with ${email}.`)
+        await store.put(`email:${email}`, id)
+        await store.delete(`email:${user.email}`)
+        next.email = email
+      }
+    }
+    await store.put(`user:${id}`, next)
+    return next
+  }
+
+  return {
+    allowed,
+    byId,
+    byEmail,
+    create,
+    update,
+
+    /**
+     * The user with this email, made on first sign-in. Null when they aren't allowed in.
+     * `profile` fills in a name and picture the first time (e.g. from GitHub).
+     */
+    async signIn(rawEmail, context = {}, profile = {}) {
+      const email = normalizeEmail(rawEmail)
+      if (!(await allowed(email, context))) return null
+      const existing = await byEmail(email)
+      if (existing) {
+        const fill = {}
+        if (!existing.name && profile.name) fill.name = profile.name
+        if (!existing.image && profile.image) fill.image = profile.image
+        return Object.keys(fill).length ? update(existing.id, fill) : existing
+      }
+      const user = await create({ email, name: profile.name ?? null, image: profile.image ?? null })
+      return { ...user, isNew: true }
+    },
+
+    /** Forgets the user record and email; core.js removes everything hanging off it. */
+    async remove(user) {
+      await store.delete(`email:${user.email}`)
+      await store.delete(`user:${user.id}`)
+    },
+
+    /** Every user, a page at a time. Needs a store with list() (all the built-in ones). */
+    async list({ limit = 100, cursor } = {}) {
+      if (typeof store.list !== 'function') throw new Error("slauth: listing users needs a store with list(); the built-in stores all have one.")
+      const page = await store.list('user:', { limit, cursor })
+      return { users: page.items.map((item) => withDefaults(item.value)), cursor: page.cursor }
+    },
+  }
+}
+
+/** Users saved by slauth 1.0 only had { id, email, createdAt }. */
+function withDefaults(user) {
+  return { name: null, image: null, roles: [], metadata: {}, privateMetadata: {}, updatedAt: user.createdAt, bannedAt: null, ...user }
+}
+
+/** What the browser (and your app, via auth.user) sees. */
+export function publicUser(user) {
+  return { id: user.id, email: user.email, name: user.name ?? null, image: user.image ?? null, roles: user.roles ?? [], metadata: user.metadata ?? {}, createdAt: user.createdAt }
+}
+
+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,106 @@
+/** 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
+}
+
+/** A random, URL-safe id with a readable prefix, e.g. id('usr') → "usr_k3J…". */
+export function randomId(prefix, bytes = 15) {
+  return `${prefix}_${base64Url(crypto.getRandomValues(new Uint8Array(bytes)))}`
+}
+
+/** A 302 to `location`, with any Set-Cookie values. */
+export function redirect(location, cookies = []) {
+  const headers = new Headers({ Location: location, 'Cache-Control': 'no-store' })
+  for (const c of cookies) headers.append('Set-Cookie', c)
+  return new Response(null, { status: 302, headers })
+}
+
+/**
+ * Only paths on this site ("/dashboard?tab=1"), never "//evil.example" or
+ * "https://evil.example", so a sign-in link can't send someone elsewhere.
+ */
+export function safeRedirect(path, fallback = '/') {
+  if (typeof path !== 'string' || !path.startsWith('/') || path.startsWith('//') || path.startsWith('/\\') || /[\r\n]/.test(path)) return fallback
+  return path
+}
+
+/** Adds query parameters to a same-site path. */
+export function withParams(path, params) {
+  const url = new URL(path, 'http://x')
+  for (const [key, value] of Object.entries(params)) if (value != null) url.searchParams.set(key, value)
+  return url.pathname + url.search + url.hash
+}
+
+/** The visitor's IP from the headers hosts set for it, or null when there's none we can trust. */
+export function clientIp(request) {
+  return request.headers.get('cf-connecting-ip') ?? request.headers.get('fly-client-ip') ?? request.headers.get('x-real-ip') ?? null
+}
+
+export function escapeHtml(text) {
+  return String(text).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c])
+}