backd-js 0.1.14 → 0.2.0

package/src/auth.js

@@ -0,0 +1,374 @@
+import { AuthenticationError, VerificationRequiredError } from './errors.js'
+
+/**
+ * @typedef {import('./client.js').Client} Client
+ * @typedef {import('./client.js').RequestOptions} RequestOptions
+ */
+
+/**
+ * A realm user as the user sees themselves.
+ * @typedef {object} User
+ * @property {string} id
+ * @property {string} email
+ * @property {boolean} email_verified
+ * @property {string[]} roles
+ * @property {string} locale       The user's language, one the realm lists (used for their emails).
+ * @property {string} created_at   RFC3339 timestamp.
+ */
+
+/**
+ * A new session.
+ * @typedef {object} Session
+ * @property {string} token       Session token (`bds_…`); already stored by the client.
+ * @property {'Bearer'} token_type
+ * @property {string} session_id
+ * @property {string} expires_at  RFC3339; pushed forward as the session is used.
+ * @property {User} user
+ */
+
+/**
+ * @typedef {object} SessionInfo
+ * @property {string} id
+ * @property {string} created_at
+ * @property {string} last_used_at
+ * @property {string} expires_at
+ * @property {boolean} current  The session making this request.
+ */
+
+/**
+ * What changed: a sign-in (signup or login), a sign-out (logout, logout
+ * everywhere, account deleted), or the server refusing the stored token
+ * (expired, revoked, or the user disabled).
+ * @typedef {'SIGNED_IN' | 'SIGNED_OUT' | 'SESSION_EXPIRED'} AuthEvent
+ */
+
+/**
+ * @callback AuthListener
+ * @param {AuthEvent} event
+ * @param {Session | null} session  The new session for SIGNED_IN, otherwise null.
+ * @returns {void}
+ */
+
+/** A body without the fields that were not given. @param {Record<string, unknown>} fields */
+function compact(fields) {
+  return Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined))
+}
+
+/** Sign-up, login and session management: `client.auth`. */
+export class Auth {
+  /** @param {Client} client */
+  constructor(client) {
+    /** @internal */
+    this.client = client
+    /** @internal */
+    this.listeners = new Set()
+  }
+
+  /**
+   * Creates an account and signs in. Realms with `signup: invite` need an
+   * invitation token. `locale` (such as `es` or `es-MX`) is the language to
+   * use for the user; the server maps it silently to one the realm lists. A
+   * browser also sends its `Accept-Language`, which is used when no `locale`
+   * is given. `redirectTo` is where the page after the verification link may
+   * send the user (it must be within the realm's `email.allowed_redirects`).
+   *
+   * A realm that requires verified addresses (`account.require_verified_email`)
+   * creates the account but starts no session: this rejects with a
+   * {@link VerificationRequiredError}, nothing is stored, and the user signs
+   * in after following the link in the email they were sent.
+   * @param {{ email: string, password: string, invitation?: string, locale?: string, redirectTo?: string }} input
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<Session>}
+   */
+  async signup({ email, password, invitation, locale, redirectTo }, opts) {
+    /** @type {Record<string, string>} */
+    const body = { email, password }
+    if (invitation) body.invitation = invitation
+    if (locale) body.locale = locale
+    if (redirectTo) body.redirect_to = redirectTo
+    const { status, data } = await this.client.request({ method: 'POST', path: ['_auth', 'signup'], body, auth: false, ...opts })
+    if (status === 202) {
+      throw new VerificationRequiredError({ status, code: 'verification_required', message: 'the account was created: verify the email address, then sign in' })
+    }
+    return this.signedIn(data)
+  }
+
+  /**
+   * Signs in with email and password.
+   * @param {{ email: string, password: string }} input
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<Session>}
+   */
+  async login({ email, password }, opts) {
+    const { data } = await this.client.request({ method: 'POST', path: ['_auth', 'login'], body: { email, password }, auth: false, ...opts })
+    return this.signedIn(data)
+  }
+
+  /**
+   * Asks for the verification email again. Always resolves, whatever the
+   * address is (unknown, disabled, already verified), so it can't be used to
+   * find out who is registered. `redirectTo` is where the page after the link
+   * may send the user (within the realm's `email.allowed_redirects`).
+   * @param {{ email: string, redirectTo?: string }} input
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<void>}
+   */
+  async resendVerification({ email, redirectTo }, opts) {
+    await this.accepted(['_auth', 'verify-email', 'resend'], { email, redirect_to: redirectTo }, opts)
+  }
+
+  /**
+   * Verifies an address with the token of the link in the email: for apps
+   * that host their own page (`email.links` in `realm.yaml`). Starts no
+   * session. An expired, used or unknown token rejects with a
+   * `ValidationError` whose `code` is `invalid_token`.
+   * @param {string} token
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<void>}
+   */
+  async verifyEmail(token, opts) {
+    await this.accepted(['_auth', 'verify-email'], { token }, opts)
+  }
+
+  /**
+   * Asks for a password reset email. Always resolves, whatever the address is.
+   * Rejects with a `RetryableError` once the realm's limits for reset
+   * requests (per address and per client) are reached.
+   * @param {{ email: string, redirectTo?: string }} input
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<void>}
+   */
+  async requestPasswordReset({ email, redirectTo }, opts) {
+    await this.accepted(['_auth', 'reset-password', 'request'], { email, redirect_to: redirectTo }, opts)
+  }
+
+  /**
+   * Sets a new password with the token of a reset link. Ends every session of
+   * the user, verifies their address and starts no session: log in afterwards.
+   * A password the policy refuses rejects with a `ValidationError` and leaves
+   * the token usable; a bad token has the `invalid_token` code.
+   * @param {{ token: string, password: string }} input
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<void>}
+   */
+  async resetPassword({ token, password }, opts) {
+    await this.accepted(['_auth', 'reset-password'], { token, password }, opts)
+  }
+
+  /**
+   * Asks to change the signed-in user's email address (realms with
+   * `account.allow_email_change`). Needs the current password. Resolves
+   * whether or not the new address is free; nothing changes until the link
+   * sent to the new address is used (see {@link Auth#confirmEmailChange}).
+   * @param {{ newEmail: string, password: string, redirectTo?: string }} input
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<void>}
+   */
+  async requestEmailChange({ newEmail, password, redirectTo }, opts) {
+    await this.client.request({ method: 'POST', path: ['_auth', 'email'], body: compact({ new_email: newEmail, password, redirect_to: redirectTo }), ...opts })
+  }
+
+  /**
+   * Confirms an email change with the token sent to the new address: the
+   * address changes and every session of the user ends.
+   * @param {string} token
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<void>}
+   */
+  async confirmEmailChange(token, opts) {
+    await this.accepted(['_auth', 'confirm-email-change'], { token }, opts)
+  }
+
+  /**
+   * Undoes an email change with the token sent to the old address: restores
+   * it, ends every session and makes the password unusable until it is reset
+   * (a reset email is sent to the restored address).
+   * @param {string} token
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<void>}
+   */
+  async revertEmailChange(token, opts) {
+    await this.accepted(['_auth', 'revert-email-change'], { token }, opts)
+  }
+
+  /**
+   * Accepts an invitation that was emailed (admin `invitations.send`), with
+   * the token of its link: creates the account for the invited address,
+   * already verified, and starts no session. `locale` is the user's language.
+   * @param {{ token: string, password: string, locale?: string }} input
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<void>}
+   */
+  async acceptInvitation({ token, password, locale }, opts) {
+    await this.accepted(['_auth', 'accept-invitation'], { token, password, locale }, opts)
+  }
+
+  /**
+   * A call that needs no session and answers with no body.
+   * @internal
+   * @param {string[]} path
+   * @param {Record<string, unknown>} body
+   * @param {RequestOptions} [opts]
+   */
+  async accepted(path, body, opts) {
+    await this.client.request({ method: 'POST', path, body: compact(body), auth: false, ...opts })
+  }
+
+  /**
+   * Ends the current session. The stored token is removed even if the
+   * server can't be reached.
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<void>}
+   */
+  async logout(opts) {
+    try {
+      await this.client.request({ method: 'POST', path: ['_auth', 'logout'], expire: false, ...opts })
+    } catch (err) {
+      // A session the server no longer knows is logged out already.
+      if (!(err instanceof AuthenticationError)) throw err
+    } finally {
+      await this.signedOut('SIGNED_OUT')
+    }
+  }
+
+  /**
+   * Ends every session of the user, on every device.
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<void>}
+   */
+  async logoutAll(opts) {
+    await this.client.request({ method: 'POST', path: ['_auth', 'logout-all'], ...opts })
+    await this.signedOut('SIGNED_OUT')
+  }
+
+  /**
+   * The signed-in user.
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<User>}
+   */
+  async me(opts) {
+    return (await this.client.request({ method: 'GET', path: ['_auth', 'me'], ...opts })).data
+  }
+
+  /**
+   * Changes the signed-in user's own settings: today their language, which
+   * must be one the realm lists (case is ignored). Anything else is a
+   * `ValidationError` with code `invalid_locale` and the allowed languages in
+   * `details`.
+   * @param {{ locale?: string }} changes
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<User>}
+   */
+  async updateMe(changes, opts) {
+    return (await this.client.request({ method: 'PATCH', path: ['_auth', 'me'], body: changes, ...opts })).data
+  }
+
+  /**
+   * Deletes the signed-in user's account: it is **deactivated** (disabled, its
+   * sessions end) and all data is kept. Erasing a user's data is an
+   * administrator's action (`admin.users.delete`).
+   * @param {{ password: string }} input
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<void>}
+   */
+  async deleteAccount({ password }, opts) {
+    await this.client.request({ method: 'DELETE', path: ['_auth', 'me'], body: { password }, ...opts })
+    await this.signedOut('SIGNED_OUT')
+  }
+
+  /**
+   * Changes the password. This session stays valid; all others end.
+   * @param {{ currentPassword: string, newPassword: string }} input
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<void>}
+   */
+  async changePassword({ currentPassword, newPassword }, opts) {
+    await this.client.request({
+      method: 'POST',
+      path: ['_auth', 'password'],
+      body: { current_password: currentPassword, new_password: newPassword },
+      ...opts,
+    })
+  }
+
+  /**
+   * The user's active sessions, newest first.
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<SessionInfo[]>}
+   */
+  async sessions(opts) {
+    return (await this.client.request({ method: 'GET', path: ['_auth', 'sessions'], ...opts })).data.items
+  }
+
+  /**
+   * Ends one of the user's sessions, for example a lost device.
+   * @param {string} id
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<void>}
+   */
+  async revokeSession(id, opts) {
+    await this.client.request({ method: 'DELETE', path: ['_auth', 'sessions', id], ...opts })
+  }
+
+  /**
+   * The stored session token, if any.
+   * @returns {Promise<string | null>}
+   */
+  async token() {
+    return (await this.client.storage.get()) ?? null
+  }
+
+  /**
+   * Calls listener on sign-in, sign-out and session expiry.
+   * @param {AuthListener} listener
+   * @returns {() => void} Stops listening.
+   */
+  onAuthChange(listener) {
+    this.listeners.add(listener)
+    return () => this.listeners.delete(listener)
+  }
+
+  /**
+   * @internal
+   * @param {Session} session
+   * @returns {Promise<Session>}
+   */
+  async signedIn(session) {
+    await this.client.storage.set(session.token)
+    this.emit('SIGNED_IN', session)
+    return session
+  }
+
+  /**
+   * @internal
+   * @param {AuthEvent} event
+   */
+  async signedOut(event) {
+    await this.client.storage.remove()
+    this.emit(event, null)
+  }
+
+  /**
+   * Called by the client when the server refuses the stored token.
+   * @internal
+   */
+  async _expired() {
+    await this.signedOut('SESSION_EXPIRED')
+  }
+
+  /**
+   * @internal
+   * @param {AuthEvent} event
+   * @param {Session | null} session
+   */
+  emit(event, session) {
+    for (const l of this.listeners) {
+      try {
+        l(event, session)
+      } catch (err) {
+        // A failing listener must not break the client or other listeners.
+        console.error('backd: an onAuthChange listener failed:', err)
+      }
+    }
+  }
+}

package/src/client.js

@@ -0,0 +1,214 @@
+import { Admin } from './admin.js'
+import { Auth } from './auth.js'
+import { Database } from './data.js'
+import { NetworkError, RetryableError, errorFromResponse } from './errors.js'
+import { memoryStorage } from './storage.js'
+
+/**
+ * @typedef {import('./storage.js').TokenStorage} TokenStorage
+ */
+
+/**
+ * Retry settings. Only 429 and 503 answers are retried, and only for safe
+ * requests: GET, or writes with If-Match.
+ * @typedef {object} RetryOptions
+ * @property {number} attempts       Extra attempts after the first (0 disables).
+ * @property {number} [maxDelayMs]   Longest wait between attempts; default 30000.
+ */
+
+/**
+ * @typedef {object} ClientOptions
+ * @property {string} url                 Base URL of backd, e.g. "https://api.example.com".
+ * @property {string} realm               The realm to talk to.
+ * @property {string} [apiKey]            Server-side only: an API key (`bdk_…`). Full access to the realm.
+ * @property {boolean} [dangerouslyAllowBrowser] Allow `apiKey` in a browser. Anyone who loads the page gets the key.
+ * @property {TokenStorage} [storage]     Where the session token lives; memory by default.
+ * @property {RetryOptions} [retry]       Retries for 429/503; off by default.
+ * @property {typeof fetch} [fetch]       A fetch implementation; the global one by default.
+ * @property {Record<string, string>} [headers] Extra headers for every request.
+ */
+
+/**
+ * Per-request options.
+ * @typedef {object} RequestOptions
+ * @property {AbortSignal} [signal]
+ * @property {RetryOptions} [retry]
+ * @property {Record<string, string>} [headers]
+ */
+
+/**
+ * @typedef {object} RequestInit
+ * @property {string} method
+ * @property {string[]} path             Path segments after /v1/{realm}, encoded here.
+ * @property {Record<string, string | number | boolean | undefined>} [query]
+ * @property {unknown} [body]            Sent as JSON.
+ * @property {string} [contentType]      Defaults to application/json when there's a body.
+ * @property {Record<string, string>} [headers]
+ * @property {boolean} [auth]            Send credentials; default true.
+ * @property {boolean} [expire]          Treat a refused session token as expired; default true.
+ * @property {AbortSignal} [signal]
+ * @property {RetryOptions} [retry]
+ */
+
+/**
+ * The raw answer of a successful request.
+ * @typedef {object} RawResponse
+ * @property {number} status
+ * @property {Headers} headers
+ * @property {any} data   Parsed JSON, or undefined for empty bodies.
+ */
+
+const isBrowser = () => typeof window !== 'undefined' && typeof window.document !== 'undefined'
+
+/**
+ * Creates a client for one realm.
+ * @param {ClientOptions} options
+ * @returns {Client}
+ */
+export function createClient(options) {
+  return new Client(options)
+}
+
+export class Client {
+  /** @param {ClientOptions} options */
+  constructor(options) {
+    if (!options?.url) throw new TypeError('createClient: `url` is required')
+    if (!options.realm) throw new TypeError('createClient: `realm` is required')
+    if (options.apiKey && isBrowser() && !options.dangerouslyAllowBrowser) {
+      throw new Error(
+        'createClient: API keys give full access to the realm and must not be used in browsers, ' +
+          'where every visitor can read them. Use sessions (client.auth) instead, or pass ' +
+          '`dangerouslyAllowBrowser: true` if you really mean it.',
+      )
+    }
+    /** @readonly */
+    this.url = options.url.replace(/\/+$/, '')
+    /** @readonly */
+    this.realm = options.realm
+    /** @internal */
+    this.apiKey = options.apiKey
+    /** @internal */
+    this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis)
+    /** @internal */
+    this.retry = options.retry ?? { attempts: 0 }
+    /** @internal */
+    this.headers = options.headers ?? {}
+    /** @readonly */
+    this.storage = options.storage ?? memoryStorage()
+    /** Sign-up, login and sessions. */
+    this.auth = new Auth(this)
+    /** Users, roles, invitations and API keys; needs an admin `apiKey` or an admin user's session. */
+    this.admin = new Admin(this)
+  }
+
+  /** Whether the client was created with an API key. */
+  get hasApiKey() {
+    return Boolean(this.apiKey)
+  }
+
+  /**
+   * A database of the realm, to reach its collections:
+   * `client.db('main').collection('posts')`.
+   * @param {string} name
+   * @returns {Database}
+   */
+  db(name) {
+    return new Database(this, name)
+  }
+
+  /**
+   * Sends a request to /v1/{realm}/…, adding credentials, and returns the
+   * parsed answer. Non-2xx answers throw a BackdError.
+   * @param {RequestInit} req
+   * @returns {Promise<RawResponse>}
+   */
+  async request(req) {
+    const url = new URL(this.url + '/v1/' + [this.realm, ...req.path].map(encodeURIComponent).join('/'))
+    for (const [k, v] of Object.entries(req.query ?? {})) {
+      if (v !== undefined) url.searchParams.set(k, String(v))
+    }
+    /** @type {Record<string, string>} */
+    const headers = { Accept: 'application/json', ...this.headers, ...req.headers }
+    if (req.body !== undefined) headers['Content-Type'] = req.contentType ?? 'application/json'
+
+    let sentSession = false
+    if (req.auth !== false) {
+      if (this.apiKey) {
+        headers.Authorization = 'Bearer ' + this.apiKey
+      } else {
+        const token = await this.storage.get()
+        if (token) {
+          headers.Authorization = 'Bearer ' + token
+          sentSession = true
+        }
+      }
+    }
+
+    const retry = req.retry ?? this.retry
+    const safe = req.method === 'GET' || Object.keys(headers).some((h) => h.toLowerCase() === 'if-match')
+    const attempts = safe ? Math.max(0, retry.attempts) : 0
+    for (let attempt = 0; ; attempt++) {
+      /** @type {Response} */
+      let res
+      try {
+        res = await this.fetchImpl(url, {
+          method: req.method,
+          headers,
+          body: req.body === undefined ? undefined : JSON.stringify(req.body),
+          signal: req.signal,
+        })
+      } catch (cause) {
+        throw new NetworkError({
+          status: 0,
+          code: req.signal?.aborted ? 'aborted' : 'network_error',
+          message: req.signal?.aborted ? 'request aborted' : 'network error: ' + String(cause),
+          cause,
+        })
+      }
+      if (res.ok) {
+        const text = await res.text()
+        return { status: res.status, headers: res.headers, data: text ? JSON.parse(text) : undefined }
+      }
+      const err = await errorFromResponse(res)
+      if (err.code === 'unauthenticated' && sentSession && req.expire !== false) {
+        await this.auth._expired()
+      }
+      if (err instanceof RetryableError && attempt < attempts) {
+        await sleep(backoff(attempt, err.retryAfter, retry.maxDelayMs ?? 30000), req.signal)
+        continue
+      }
+      throw err
+    }
+  }
+}
+
+/**
+ * Wait before the next attempt: what the server asked, else exponential
+ * backoff from 500 ms; never more than max.
+ * @param {number} attempt
+ * @param {number | undefined} retryAfter
+ * @param {number} max
+ */
+function backoff(attempt, retryAfter, max) {
+  return Math.min(retryAfter ?? 500 * 2 ** attempt, max)
+}
+
+/**
+ * @param {number} ms
+ * @param {AbortSignal} [signal]
+ * @returns {Promise<void>}
+ */
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(signal.reason)
+    const t = setTimeout(resolve, ms)
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(t)
+        reject(signal.reason)
+      },
+      { once: true },
+    )
+  })
+}