slauthjs 0.0.0-stage → 2.0.0

package/src/oauth/flow.js

@@ -0,0 +1,81 @@
+import { base64Url, randomToken, readCookie, serializeCookie, sha256 } from '../util.js'
+
+const STATE_SECONDS = 10 * 60
+const COOKIE = 'slauth_oauth'
+
+/**
+ * The OAuth 2.0 authorization-code flow with PKCE (RFC 7636) and a `state` that's tied
+ * to this browser by a short-lived cookie, so nobody can finish a sign-in someone else
+ * started (login CSRF).
+ *
+ *   oauth:<state>  { provider, verifier, redirect, returnTo, linkUserId }   (lives 10 minutes)
+ *
+ * @param {{ store: import('../index.js').Store, fetch?: typeof fetch }} options
+ */
+export function createOAuthFlow({ store, fetch: doFetch = (...args) => fetch(...args) }) {
+  async function endpoints(provider) {
+    if (!provider.discover) return { authorization: provider.authorization, token: provider.token }
+    const config = await provider.discover(doFetch)
+    return { authorization: config.authorization_endpoint, token: config.token_endpoint }
+  }
+
+  return {
+    fetch: doFetch,
+
+    /** Where to send the browser, and the cookie that ties the flow to it. */
+    async start(provider, { callbackUrl, redirect, returnTo, linkUserId = null, secure }) {
+      const state = randomToken()
+      const verifier = randomToken()
+      await store.put(`oauth:${state}`, { provider: provider.id, verifier, redirect, returnTo, linkUserId }, { ttl: STATE_SECONDS })
+      const url = new URL((await endpoints(provider)).authorization)
+      url.searchParams.set('response_type', 'code')
+      url.searchParams.set('client_id', provider.clientId)
+      url.searchParams.set('redirect_uri', callbackUrl)
+      url.searchParams.set('state', state)
+      if (provider.scope) url.searchParams.set('scope', provider.scope)
+      if (provider.pkce) {
+        url.searchParams.set('code_challenge', base64Url(await sha256(verifier)))
+        url.searchParams.set('code_challenge_method', 'S256')
+      }
+      for (const [key, value] of Object.entries(provider.params ?? {})) url.searchParams.set(key, value)
+      return { location: url.toString(), cookie: serializeCookie(COOKIE, state, { maxAge: STATE_SECONDS, secure }) }
+    },
+
+    /**
+     * Finishes the flow: checks state, swaps the code for tokens, reads the profile.
+     * @returns {Promise<{ ok: true, profile: object, tokens: object, state: object } | { ok: false, code: string, state?: object }>}
+     */
+    async finish(provider, request, { callbackUrl }) {
+      const url = new URL(request.url)
+      const state = url.searchParams.get('state')
+      const fromCookie = readCookie(request.headers.get('cookie'), COOKIE)
+      const saved = state ? await store.get(`oauth:${state}`) : null
+      if (state) await store.delete(`oauth:${state}`)
+      if (!saved || saved.provider !== provider.id || !fromCookie || fromCookie !== state) return { ok: false, code: 'oauth-state' }
+      if (url.searchParams.get('error')) return { ok: false, code: url.searchParams.get('error') === 'access_denied' ? 'oauth-cancelled' : 'oauth-failed', state: saved }
+      const code = url.searchParams.get('code')
+      if (!code) return { ok: false, code: 'oauth-failed', state: saved }
+
+      const body = new URLSearchParams({ grant_type: 'authorization_code', code, redirect_uri: callbackUrl })
+      if (provider.pkce) body.set('code_verifier', saved.verifier)
+      const headers = { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' }
+      if (provider.tokenAuth === 'basic') headers.Authorization = `Basic ${btoa(`${encodeURIComponent(provider.clientId)}:${encodeURIComponent(provider.clientSecret ?? '')}`)}`
+      else {
+        body.set('client_id', provider.clientId)
+        if (provider.clientSecret) body.set('client_secret', provider.clientSecret)
+      }
+      const res = await doFetch((await endpoints(provider)).token, { method: 'POST', headers, body })
+      const tokens = await res.json().catch(() => ({}))
+      if (!res.ok || !tokens.access_token) {
+        console.error(`slauth: ${provider.id} wouldn't swap the code for a token:`, res.status, tokens.error ?? '')
+        return { ok: false, code: 'oauth-failed', state: saved }
+      }
+      const profile = await provider.profile(tokens, doFetch)
+      if (!profile?.id) return { ok: false, code: 'oauth-failed', state: saved }
+      if (provider.trustEmail && profile.email) profile.emailVerified = true
+      return { ok: true, profile, tokens, state: saved }
+    },
+
+    clearCookie: (secure) => serializeCookie(COOKIE, '', { maxAge: 0, secure }),
+  }
+}

package/src/oauth/providers.js

@@ -0,0 +1,171 @@
+/**
+ * "Sign in with …" providers. Each is a plain object, so adding your own is just
+ * oauth2({ ... }) or oidc({ ... }):
+ *
+ *   import { github, google } from 'slauthjs/providers'
+ *   slauth({ ..., providers: [github({ clientId, clientSecret }), google({ clientId, clientSecret })] })
+ *
+ * The callback URL to register with each provider is <your site>/auth/oauth/<id>/callback.
+ *
+ * A provider's `profile(tokens, fetch)` returns { id, email, emailVerified, name, image }.
+ * slauth only signs someone in by email when the provider says the email is verified,
+ * so nobody can claim your account by making a provider account with your address.
+ */
+
+/**
+ * Any OAuth 2.0 provider.
+ *
+ * @param {{
+ *   id: string, name: string, clientId: string, clientSecret?: string,
+ *   authorization: string, token: string, scope?: string, params?: Record<string, string>,
+ *   pkce?: boolean, tokenAuth?: 'post' | 'basic',
+ *   profile(tokens: Record<string, any>, fetch: typeof fetch): Promise<{ id: string, email?: string | null, emailVerified?: boolean, name?: string | null, image?: string | null }>,
+ *   trustEmail?: boolean, keepTokens?: boolean,
+ * }} options
+ */
+export function oauth2(options) {
+  for (const key of ['id', 'clientId', 'authorization', 'token', 'profile']) {
+    if (!options?.[key]) throw new Error(`slauth: the ${options?.id ?? 'OAuth'} provider needs \`${key}\`.`)
+  }
+  if (!/^[a-z0-9-]+$/.test(options.id)) throw new Error(`slauth: provider ids are lower-case letters, digits and dashes, not "${options.id}".`)
+  return { type: 'oauth2', name: options.id, pkce: true, tokenAuth: 'post', scope: '', params: {}, ...options }
+}
+
+/**
+ * Any OpenID Connect provider, found from its issuer's discovery document. The profile
+ * comes from the userinfo endpoint, using the access token we just got over TLS.
+ *
+ * @param {{ id: string, name: string, issuer: string, clientId: string, clientSecret?: string, scope?: string, params?: Record<string, string>, trustEmail?: boolean, keepTokens?: boolean, tokenAuth?: 'post' | 'basic' }} options
+ */
+export function oidc({ issuer, scope = 'openid email profile', ...options }) {
+  if (!issuer) throw new Error(`slauth: the ${options.id ?? 'OIDC'} provider needs \`issuer\`.`)
+  let discovered = null
+  const discover = (doFetch) =>
+    (discovered ??= doFetch(`${issuer.replace(/\/+$/, '')}/.well-known/openid-configuration`)
+      .then((res) => {
+        if (!res.ok) throw new Error(`slauth: couldn't read ${issuer}'s OpenID configuration (${res.status}).`)
+        return res.json()
+      })
+      .catch((error) => {
+        discovered = null
+        throw error
+      }))
+  return oauth2({
+    // Filled in from discovery when the flow starts (see flow.js).
+    authorization: 'discover',
+    token: 'discover',
+    discover,
+    scope,
+    async profile(tokens, doFetch) {
+      const config = await discover(doFetch)
+      const info = await getJson(doFetch, config.userinfo_endpoint, tokens.access_token)
+      return { id: String(info.sub), email: info.email ?? null, emailVerified: info.email_verified === true || info.email_verified === 'true', name: info.name ?? null, image: info.picture ?? null }
+    },
+    ...options,
+  })
+}
+
+/** GitHub. Make an OAuth app at github.com/settings/developers. */
+export function github({ clientId, clientSecret, scope = 'read:user user:email', ...rest }) {
+  return oauth2({
+    id: 'github',
+    name: 'GitHub',
+    clientId,
+    clientSecret,
+    scope,
+    authorization: 'https://github.com/login/oauth/authorize',
+    token: 'https://github.com/login/oauth/access_token',
+    async profile(tokens, doFetch) {
+      const me = await getJson(doFetch, 'https://api.github.com/user', tokens.access_token)
+      // The profile email can be hidden or unverified; /user/emails says which is which.
+      const emails = await getJson(doFetch, 'https://api.github.com/user/emails', tokens.access_token).catch(() => [])
+      const primary = emails.find((e) => e.primary && e.verified) ?? emails.find((e) => e.verified)
+      return { id: String(me.id), email: primary?.email ?? null, emailVerified: Boolean(primary), name: me.name || me.login, image: me.avatar_url ?? null }
+    },
+    ...rest,
+  })
+}
+
+/** Google. Make an OAuth client at console.cloud.google.com/apis/credentials. */
+export function google({ clientId, clientSecret, scope = 'openid email profile', ...rest }) {
+  return oauth2({
+    id: 'google',
+    name: 'Google',
+    clientId,
+    clientSecret,
+    scope,
+    authorization: 'https://accounts.google.com/o/oauth2/v2/auth',
+    token: 'https://oauth2.googleapis.com/token',
+    params: { prompt: 'select_account' },
+    async profile(tokens, doFetch) {
+      const info = await getJson(doFetch, 'https://openidconnect.googleapis.com/v1/userinfo', tokens.access_token)
+      return { id: String(info.sub), email: info.email ?? null, emailVerified: info.email_verified === true, name: info.name ?? null, image: info.picture ?? null }
+    },
+    ...rest,
+  })
+}
+
+/** Discord. Make an application at discord.com/developers/applications. */
+export function discord({ clientId, clientSecret, scope = 'identify email', ...rest }) {
+  return oauth2({
+    id: 'discord',
+    name: 'Discord',
+    clientId,
+    clientSecret,
+    scope,
+    authorization: 'https://discord.com/oauth2/authorize',
+    token: 'https://discord.com/api/oauth2/token',
+    async profile(tokens, doFetch) {
+      const me = await getJson(doFetch, 'https://discord.com/api/users/@me', tokens.access_token)
+      const image = me.avatar ? `https://cdn.discordapp.com/avatars/${me.id}/${me.avatar}.png` : null
+      return { id: String(me.id), email: me.email ?? null, emailVerified: me.verified === true, name: me.global_name ?? me.username, image }
+    },
+    ...rest,
+  })
+}
+
+/** GitLab (gitlab.com, or your own with `baseUrl`). */
+export function gitlab({ clientId, clientSecret, baseUrl = 'https://gitlab.com', ...rest }) {
+  return oidc({ id: 'gitlab', name: 'GitLab', issuer: baseUrl, clientId, clientSecret, scope: 'openid email profile', ...rest })
+}
+
+/**
+ * Microsoft (personal accounts, and work or school accounts with `tenant`). Microsoft
+ * doesn't promise a work account's email belongs to the person, so by default only
+ * personal accounts' emails count as verified. With a single `tenant` you control,
+ * set trustEmail: true.
+ */
+export function microsoft({ clientId, clientSecret, tenant = 'common', ...rest }) {
+  const CONSUMERS = '9188040d-6c67-4c5b-b112-36a304b66dad'
+  return oauth2({
+    id: 'microsoft',
+    name: 'Microsoft',
+    clientId,
+    clientSecret,
+    scope: 'openid email profile User.Read',
+    authorization: `https://login.microsoftonline.com/${tenant}/oauth2/v2.0/authorize`,
+    token: `https://login.microsoftonline.com/${tenant}/oauth2/v2.0/token`,
+    async profile(tokens, doFetch) {
+      const info = await getJson(doFetch, 'https://graph.microsoft.com/oidc/userinfo', tokens.access_token)
+      const claims = decodeJwtPayload(tokens.id_token)
+      return { id: String(info.sub), email: info.email ?? null, emailVerified: claims?.tid === CONSUMERS, name: info.name ?? null, image: null }
+    },
+    ...rest,
+  })
+}
+
+async function getJson(doFetch, url, accessToken) {
+  const res = await doFetch(url, { headers: { Authorization: `Bearer ${accessToken}`, Accept: 'application/json', 'User-Agent': 'slauth' } })
+  if (!res.ok) throw new Error(`slauth: ${new URL(url).host} said ${res.status} when asked for the profile.`)
+  return res.json()
+}
+
+/** Reads (doesn't check) a JWT's claims; only for tokens we got straight from the provider. */
+function decodeJwtPayload(token) {
+  try {
+    const part = String(token).split('.')[1].replace(/-/g, '+').replace(/_/g, '/')
+    return JSON.parse(atob(part + '='.repeat((4 - (part.length % 4)) % 4)))
+  } catch {
+    return null
+  }
+}

package/src/orgs.js

@@ -0,0 +1,184 @@
+import { randomId } from './util.js'
+import { normalizeEmail } from './users.js'
+
+const INVITE_DAYS = 7
+/** Roles that can manage an organization. Any other role string is just a label for your app. */
+const MANAGERS = new Set(['owner', 'admin'])
+
+/**
+ * Organizations (teams, workspaces, families: whatever your app calls them).
+ *
+ *   org:<orgId>         { id, name, metadata, createdAt, createdBy }
+ *   members:<orgId>     [{ userId, role, joinedAt }]
+ *   orgs:<userId>       [orgId, ...]
+ *   invite:<inviteId>   { id, orgId, email, role, invitedBy, createdAt, expiresAt }
+ *   invites:<email>     [inviteId, ...]
+ *   org-invites:<orgId> [inviteId, ...]
+ *
+ * Roles: "owner" (everything, including deleting the org), "admin" (members and
+ * invitations), and anything else you like ("member", "billing", "viewer").
+ *
+ * @param {import('./index.js').Store} store
+ */
+export function createOrgs(store) {
+  const list = async (key) => (await store.get(key)) ?? []
+  const save = async (key, items) => (items.length ? store.put(key, items) : store.delete(key))
+
+  async function get(orgId) {
+    return typeof orgId === 'string' ? store.get(`org:${orgId}`) : null
+  }
+
+  async function members(orgId) {
+    return list(`members:${orgId}`)
+  }
+
+  async function role(orgId, userId) {
+    return (await members(orgId)).find((m) => m.userId === userId)?.role ?? null
+  }
+
+  async function addMember(orgId, userId, memberRole = 'member') {
+    const current = await members(orgId)
+    if (current.some((m) => m.userId === userId)) return setRole(orgId, userId, memberRole)
+    await store.put(`members:${orgId}`, [...current, { userId, role: memberRole, joinedAt: Date.now() }])
+    const mine = await list(`orgs:${userId}`)
+    if (!mine.includes(orgId)) await store.put(`orgs:${userId}`, [...mine, orgId])
+    return true
+  }
+
+  async function setRole(orgId, userId, memberRole) {
+    const current = await members(orgId)
+    const member = current.find((m) => m.userId === userId)
+    if (!member) return false
+    if (member.role === 'owner' && memberRole !== 'owner' && current.filter((m) => m.role === 'owner').length === 1) {
+      throw new OrgError('An organization needs at least one owner.', 'last-owner')
+    }
+    await store.put(`members:${orgId}`, current.map((m) => (m.userId === userId ? { ...m, role: memberRole } : m)))
+    return true
+  }
+
+  async function removeMember(orgId, userId) {
+    const current = await members(orgId)
+    const member = current.find((m) => m.userId === userId)
+    if (!member) return false
+    if (member.role === 'owner' && current.filter((m) => m.role === 'owner').length === 1 && current.length > 1) {
+      throw new OrgError('Make someone else an owner first.', 'last-owner')
+    }
+    await save(`members:${orgId}`, current.filter((m) => m.userId !== userId))
+    await save(`orgs:${userId}`, (await list(`orgs:${userId}`)).filter((id) => id !== orgId))
+    // The last person out turns off the lights.
+    if (current.length === 1) await remove(orgId)
+    return true
+  }
+
+  async function remove(orgId) {
+    for (const m of await members(orgId)) await save(`orgs:${m.userId}`, (await list(`orgs:${m.userId}`)).filter((id) => id !== orgId))
+    for (const id of await list(`org-invites:${orgId}`)) await revokeInvite(id)
+    await store.delete(`members:${orgId}`)
+    await store.delete(`org-invites:${orgId}`)
+    await store.delete(`org:${orgId}`)
+  }
+
+  async function invite(orgId, email, memberRole = 'member', invitedBy = null) {
+    const to = normalizeEmail(email)
+    const id = randomId('inv')
+    const now = Date.now()
+    const doc = { id, orgId, email: to, role: memberRole, invitedBy, createdAt: now, expiresAt: now + INVITE_DAYS * 86_400_000 }
+    await store.put(`invite:${id}`, doc, { ttl: INVITE_DAYS * 86_400 })
+    await store.put(`invites:${to}`, [...(await list(`invites:${to}`)), id])
+    await store.put(`org-invites:${orgId}`, [...(await list(`org-invites:${orgId}`)), id])
+    return doc
+  }
+
+  async function revokeInvite(inviteId) {
+    const doc = typeof inviteId === 'string' ? await store.get(`invite:${inviteId}`) : null
+    if (!doc) return false
+    await store.delete(`invite:${inviteId}`)
+    await save(`invites:${doc.email}`, (await list(`invites:${doc.email}`)).filter((id) => id !== inviteId))
+    await save(`org-invites:${doc.orgId}`, (await list(`org-invites:${doc.orgId}`)).filter((id) => id !== inviteId))
+    return true
+  }
+
+  async function live(ids) {
+    const out = []
+    for (const id of ids) {
+      const doc = await store.get(`invite:${id}`)
+      if (doc && doc.expiresAt > Date.now()) out.push(doc)
+    }
+    return out
+  }
+
+  return {
+    get,
+    members,
+    role,
+    addMember,
+    setRole,
+    removeMember,
+    remove,
+    invite,
+    revokeInvite,
+
+    async create({ name, metadata = {} }, ownerId) {
+      const org = { id: randomId('org'), name: String(name).trim().slice(0, 100), metadata, createdAt: Date.now(), createdBy: ownerId ?? null }
+      await store.put(`org:${org.id}`, org)
+      if (ownerId) await addMember(org.id, ownerId, 'owner')
+      return org
+    },
+
+    async update(orgId, patch) {
+      const org = await get(orgId)
+      if (!org) return null
+      const next = { ...org }
+      if (typeof patch.name === 'string' && patch.name.trim()) next.name = patch.name.trim().slice(0, 100)
+      if (patch.metadata !== undefined) next.metadata = patch.metadata
+      await store.put(`org:${orgId}`, next)
+      return next
+    },
+
+    /** The organizations someone belongs to, each with their role. */
+    async forUser(userId) {
+      const out = []
+      for (const id of await list(`orgs:${userId}`)) {
+        const org = await get(id)
+        const r = org && (await role(id, userId))
+        if (r) out.push({ ...org, role: r })
+      }
+      return out
+    },
+
+    invitesFor: async (email) => live(await list(`invites:${normalizeEmail(email)}`)),
+    invitesOf: async (orgId) => live(await list(`org-invites:${orgId}`)),
+    getInvite: async (inviteId) => (typeof inviteId === 'string' ? store.get(`invite:${inviteId}`) : null),
+
+    /** Accepts an invitation addressed to this user's email. */
+    async accept(inviteId, user) {
+      const doc = typeof inviteId === 'string' ? await store.get(`invite:${inviteId}`) : null
+      if (!doc || doc.email !== user.email || doc.expiresAt <= Date.now() || !(await get(doc.orgId))) return null
+      await addMember(doc.orgId, user.id, doc.role)
+      await revokeInvite(inviteId)
+      return doc
+    },
+
+    /** Called when a user is deleted. */
+    async forget(userId) {
+      for (const id of await list(`orgs:${userId}`)) {
+        const current = await members(id)
+        const rest = current.filter((m) => m.userId !== userId)
+        // Hand ownership on to the longest-standing member rather than leave it ownerless.
+        if (rest.length && !rest.some((m) => m.role === 'owner')) rest[0] = { ...rest[0], role: 'owner' }
+        if (rest.length) await store.put(`members:${id}`, rest)
+        else await remove(id)
+      }
+      await store.delete(`orgs:${userId}`)
+    },
+
+    canManage: (memberRole) => MANAGERS.has(memberRole),
+  }
+}
+
+export class OrgError extends Error {
+  constructor(message, code) {
+    super(message)
+    this.code = code
+  }
+}

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)
+}