webdaemon 0.0.0-241205172853

package/src/js/ParentHelper.js

@@ -0,0 +1,302 @@
+import { Token } from './Token.js'
+import { KeyPair } from './KeyPair.js'
+
+/**
+ * This helper provides the parent capability for a website to
+ * check and activate a daemon, and to create a device offer for
+ * subsequent claim by consumer devices or browsers.
+ *
+ * The helper can operate either browser- or server-side.
+ *
+ * Usage
+ * =====
+ *
+ * // Create the helper for a child daemon.
+ * const helper = new ParentHelper()
+ *
+ * // User-supplied callback function receives public JWK and returns URL path.
+ * const callback = ({role, publicJwk}) => {daemon, source, iss}
+ * await helper.init(callback)
+ *
+ * // Succeeds if the child daemon is activated.
+ * await helper.checkActivate()
+ *
+ * // Returns the claim code and check state of a new device offer.
+ * await helper.fetchOffer()
+ *
+ */
+
+/*
+ * @typedef {Object} JsonWebKey
+ * @typedef {'parent'} Role
+ *
+ * @typedef {Object} CallbackArg
+ * @property {JsonWebKey} publicJwk
+ * @property {Role} role
+ *
+ * @typedef {Object} CallbackReturn
+ * @typedef {string} daemon the host name of the daemon.
+ * @typedef {string | undefined} source the URL of the source HTML page if request made from browser.
+ * @property {URL} signatory URL used in the iss field of the token.
+ *
+ * @typedef {Object} Signatory the object to be served on the iss URL.
+ * @property {string} role which is 'parent'.
+ * @property {JsonWebKey} publicJwk
+
+ * @callback SignatoryCallback
+ * @param {Signatory} signatory which is what the user should serve.
+ * @returns {Promise<CallbackReturn>} user provides daemon name and public URL of the signatory.
+ *
+ * @typedef {string} TokenBase64
+ *
+ * @typedef {Object} OfferOptions
+ * @property {'TRANSIENT' | 'PERMANENT'} type the type of the device.
+ * @property {number} ttl the time-to-live of device (transient only), in seconds.
+ * @property {number} expiry the number of seconds before the offer expires.
+ */
+
+export class ParentHelper {
+  #privateJwk // Signs the token used for activate and offer.
+  #publicJwk  // Verifies the signed token, must be made publicly visible.
+  #daemon     // The host name of the daemon being parented.
+  #issUrl     // Callback-supplied URL for the pubicly visible issuer object.
+  #source     // The HTML source URL, which must match origin: header iff present in daemon request.
+  #token      // The token used for check activate and offer calls to the daemon.
+  #claimCode  // The claim code returned by fetchOffer.
+
+  /**
+   * Generates the keypair for this instance and invokes callback for daemon
+   * name and signatory path.
+   *
+   * The callback should:
+   * 1. Save the generated public key such that it is publically visible.
+   * 2. Return the externally addressable signatory path.
+   *
+   * @param {SignatoryCallback} signatoryCallback
+   * @return {Promise<TokenBase64>}
+   */
+  async init(signatoryCallback) {
+    await this.#generateKeyPair()
+
+    const {
+      daemon,
+      source, // Only needed if offer request is made from a browser.
+      issUrl
+    } = await signatoryCallback({
+      role: 'parent',
+      publicJwk: this.#publicJwk
+    })
+
+    this.#daemon = daemon
+    this.#source = source
+    this.#issUrl = issUrl
+
+    await this.#buildToken()
+  }
+
+  /**
+   * Uses the token to check activate the daemon. An already
+   * activated daemon with this parent is retained, or a new
+   * daemon is created so long as the sub of the pre-generated
+   * token matches a parent record in the provider.
+   *
+   * @throws {string} exception if daemon cannot be activated.
+   */
+  async checkActivate() {
+    const url = new URL(`${this.#token.getAud()}/activate`)
+    const token = await this.#token.asSignedBase64()
+    const body = {}
+    let response
+    try {
+      response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'x-tabserver-token': token,
+          'content-type': 'application/json'
+        },
+        body: JSON.stringify(body)
+      })
+    }
+    catch (e) {
+      console.error(e)
+      throw `Cannot activate ${this.#token.getParty()}`
+    }
+    const json = await response.json()
+    if ('error' in json) {
+      throw json.error
+    }
+  }
+
+  /**
+   * Uses the token to create a device offer on the daemon with default
+   * type 'TRANSIENT' and ttl of 300s.
+   *
+   * @param {'NO_CHECK' | 'DO_CHECK'} flow to use. For QR offers, use checked flow.
+   * @param {OfferOptions} options to use when making the offer, if any.
+   * @return {Promise<Offer>} offer claimCode and checkState ('NO_CHECK' or 'AWAIT_CHECK').
+   */
+  async makeOffer(flow, options = {}) {
+    const {
+      type = 'TRANSIENT',
+      ttl = 300,
+      expiry = 30
+    } = options
+
+    const url = new URL(`${this.#token.getAud()}/offer`)
+    const token = await this.#token.asSignedBase64()
+    const body = {
+      role: 'party',
+      type,
+      ttl,
+      description: `Offered by ${this.#token.getCounterparty()}`,
+      expiry: new Date(Date.now() + 1000 * expiry),
+      flow
+    }
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'x-tabserver-token': token,
+        'content-type': 'application/json'
+      },
+      body: JSON.stringify(body)
+    })
+    const json = await response.json()
+    if ('error' in json) {
+      throw json.error
+    }
+
+    const {
+      claimCode,
+      _checkState
+    } = json.ok
+
+    this.#claimCode = claimCode
+
+    return json.ok
+  }
+
+  /**
+   * Returns the check state for the offer. This is used when
+   * awaiting claim.
+   *
+   * @return {Promise<void>}
+   */
+  async checkState() {
+    const url = new URL(`${this.#token.getAud()}/offer/check`)
+    url.searchParams.append('claimCode', this.#claimCode)
+    const token = await this.#token.asSignedBase64()
+    const response = await fetch(url, {
+      headers: {
+        'x-tabserver-token': token
+      }
+    })
+    const json = await response.json()
+    if ('error' in json) {
+      throw json.error
+    }
+
+    /**
+     * Result has `claimCode` and `checkState`.
+     */
+    return json.ok.checkState
+  }
+
+    /**
+   * Posts the check code that confirms the offering device has
+   * got the expected claiming device, and returns the resulting check state.
+   *
+   * @param {string} checkCode the check code obtained from the claiming device.
+   * @return {Promise<ConfirmResult>} the check state following confirmation.
+   */
+    async confirmClaim(checkCode) {
+      const url = new URL(`${this.#token.getAud()}/offer/confirm`)
+      const token = await this.#token.asSignedBase64()
+      const body = {
+        claimCode: this.#claimCode,
+        checkCode
+      }
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'x-tabserver-token': token,
+          'content-type': 'application/json'
+        },
+        body: JSON.stringify(body)
+      })
+      const json = await response.json()
+      if ('error' in json) {
+        throw json.error
+      }
+      return json.ok
+    }
+
+  /**
+   * Returns the daemon name.
+   *
+   * @return {string} daemon name, e.g. 'daemon.once.id'.
+   */
+  getDaemon() {
+    return this.#daemon
+  }
+
+  /**
+   * Returns the daemon origin, suitable for redirection or claiming
+   * a code.
+   *
+   * @return {URL} daemon origin e.g. 'https://daemon.once.id'.
+   */
+  getDaemonUrl() {
+    return new URL(`${this.#issUrl.protocol}//${this.#daemon}`)
+  }
+
+  /**
+   * Generates the public and private keypair used for the check
+   * activate and offer calls to the daemon.
+   *
+   * @return {Promise<void>}
+   */
+  async #generateKeyPair() {
+    const keyPair = new KeyPair()
+    await keyPair.generate()
+    this.#privateJwk = await keyPair.privateJwk()
+    this.#publicJwk = await keyPair.publicJwk()
+  }
+
+  /**
+   * Builds the token used in the check activate and offer calls toh
+   * the daemon.
+   *
+   * @return {Promise<void>}
+   */
+  async #buildToken() {
+    const iss = this.#issUrl.toString()
+    const aud = `${this.#issUrl.protocol}//${this.#daemon}`
+    const sub = this.#issUrl.origin
+
+    // The `src` attribute is origin and pathname only.
+    let src
+    if (this.#source) {
+      const srcUrl = new URL(this.#source)
+      src = `${srcUrl.origin}${srcUrl.pathname}`
+    }
+    else {
+      src = 'party:control'
+    }
+
+    const payload = {
+      iss,
+      aud,
+      sub,
+      src,
+      scope: {
+        'party:control': 'offer'
+      },
+      iat: Date.now(),
+      exp: Date.now() + 1000 * 60 * 3
+    }
+
+    const token = new Token(payload)
+    await token.signWith(Promise.resolve(this.#privateJwk))
+    this.#token = token
+  }
+}

package/src/js/QrCode.js

@@ -0,0 +1,37 @@
+/**
+ * Utility class to generate a QR code img element which is placed
+ * under a parent element.
+ */
+const BASE_URL = 'https://qrcode.tec-it.com/API/QRCode'
+export const IMG_CLASS = 'qrcode'
+
+export class QrCode {
+  #img
+  #content
+
+  /**
+   * Constructor takes img element and
+   * the string to show in the QR code.
+   * @param {HTMLImageElement} img the image element to use.
+   * @param {string} content the content of the qr code.
+   */
+  constructor(img, content) {
+    this.#img = img
+    this.#content = content
+  }
+
+  /**
+   * Returns a promise that is resolved when the image loads
+   * successfully, or rejected if the image load fails.
+   */
+  generate() {
+    const url = new URL(BASE_URL)
+    url.searchParams.append('data', this.#content)
+    this.#img.classList.add(IMG_CLASS)
+    this.#img.src = url.toString()
+    return new Promise((resolve, reject) => {
+      this.#img.onload = resolve
+      this.#img.onerror = reject
+    })
+  }
+}

package/src/js/README.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+    <title>Readme</title>
+  </head>
+  <body>
+<h1 id="javascript-library">Javascript library</h1>
+<p>This directory holds Javascript source files designed to be used in
+either the browser or a daemon runner, served from a public site such as
+https://webdaemon.online.</p>
+  </body>
+</html>

package/src/js/README.md

@@ -0,0 +1,4 @@
+# Javascript library
+This directory holds Javascript source files designed to be
+used in either the browser or a daemon runner, served from
+a public site such as https://webdaemon.online.

package/src/js/Storage.js

@@ -0,0 +1,182 @@
+/**
+ * Storage keys are 1 or more slash-separated components
+ * using the characters a-z, A-Z, 0-9, hyphen and period.
+ *
+ * Examples:
+ * - acmeSetting
+ * - acme.com/applicant/22fc01-b0d3084870b-fcae49ac2-892668
+ * - address/line1
+ * - url/acme.com
+ *
+ * The key needs to work as part of a REST/HTTP pathname.
+ */
+const KEY_PATTERN = /^[\w\-.]+(?:\/[\w\-.]+)*$/
+
+/**
+ * As above, but % and _ are both allowed as a wildcards.
+ */
+const KEYLIKE_PATTERN = /^[\w\-.%_]+(?:\/[\w\-.%_]+)*$/
+
+/**
+ * @typedef {Object} Ok
+ * @property {Plain} ok
+ *
+ * @typedef {Object} Error
+ * @property {string} error
+ */
+
+/**
+ * An instance of this class is normally obtained from BrowserApp, which constructs
+ * the instance using the party token.
+ */
+export class Storage {
+  #token    // Party token which must include getitem and setitem capabilities on party:control.
+
+  constructor(token) {
+    this.#token = token
+  }
+
+  getItem(key) {
+    return getItem(this.#token, key)
+  }
+
+  getItemsLike(keylike) {
+    return getItemsLike(this.#token, keylike)
+  }
+
+  setItem(key, value) {
+    return setItem(this.#token, key, value)
+  }
+
+  removeItem(key) {
+    return removeItem(this.#token, key)
+  }
+}
+
+/**
+ * Throws an exception if the key being used is not
+ * in a valid format.
+ */
+function assertValid(key) {
+  if (key.match(KEY_PATTERN) == null) {
+    throw `DaemonStorage: Invalid key: '${key}`
+  }
+}
+
+/**
+ * Throws an exception if the key like pattern being used
+ * is not in a valid format.
+ */
+function assertValidLike(keylike) {
+  if (keylike.match(KEYLIKE_PATTERN) == null) {
+    throw `DaemonStorage: Invalid like key: ${keylike}`
+  }
+}
+
+/**
+ * Returns the value as a JSON string
+ *
+ * @return {string} JSON string.
+ * @throws {string} exception if the value is not JSON.
+ */
+function serialise(value) {
+  try {
+    return JSON.stringify(value)
+  }
+  catch (_e) {
+    throw `DaemonStorage: Invalid value`
+  }
+}
+
+/**
+ * Sets an item in daemon storage.
+ *
+ * The value must be an object or primitive
+ * which is serialised before saving.
+ *
+ * @param {Token} token to use.
+ * @param {string} key the item key.
+ * @param {any} value the serialisable value for the item.
+ * @return {Promise<Ok | Error>} ok or error object.
+ */
+export async function setItem(token, key, value) {
+  assertValid(key)
+  const body = serialise(value)
+  const url = `${token.getAud()}/storage/${key}`
+  const response = await fetch(url, {
+    method: 'PUT',
+    headers: {
+      'X-Tabserver-Token': token.asSignedBase64(),
+      'Content-Type': 'application/json'
+    },
+    body
+  })
+  return response.json()
+}
+
+/**
+ * Gets an item from daemon storage.
+ *
+ * Returns an 'ok' object with the value if present, otherwise
+ * returns an 'error' object.
+ *
+ * @param {Token} token to use.
+ * @param {string} key the item key to retrieve.
+ * @return {Promise<Ok | Error>} ok object with value, or error.
+ */
+export async function getItem(token, key) {
+  assertValid(key)
+  const url = `${token.getAud()}/storage/${key}`
+  const response = await fetch(url, {
+    method: 'GET',
+    headers: {
+      'X-Tabserver-Token': token.asSignedBase64()
+    }
+  })
+  return response.json()
+}
+
+/**
+ * Gets zero or more items from daemon storage, whose
+ * keys match the keyLike pattern. This is normally
+ * something like 'my/prefix/%' which gets all values
+ * with that prefix.
+ *
+ * You can use both '%' and '_' as wildcards for string
+ * of any length and single character respectively.
+ *
+ * @param {Token} token to use.
+ * @param {string} the item keylike pattern to match.
+ * @return {Promise<Ok>} ok object with list, or error.
+ */
+export async function getItemsLike(token, keylike) {
+  assertValidLike(keylike)
+  const url = new URL(`${token.getAud()}/storage`)
+  url.searchParams.append('like', keylike)
+  const response = await fetch(url, {
+    method: 'GET',
+    headers: {
+      'X-Tabserver-Token': token.asSignedBase64()
+    }
+  })
+  return await response.json()
+}
+
+/**
+ * Removes an item from daemon storage.
+ *
+ * @param {Token} token to use.
+ * @param {string} key the item key to remove.
+ * @return {Promise<Ok | Error>} ok or error object.
+ */
+export async function removeItem(token, key) {
+  assertValid(key)
+  const url =`${token.getAud()}/storage/${key}`
+  const response = await fetch(url, {
+    method: 'DELETE',
+    headers: {
+      'X-Tabserver-Token': token.asSignedBase64()
+    }
+  })
+  return response.json()
+}