webdaemon 11.4.3 → 11.5.0

package/index.js

@@ -0,0 +1,17 @@
+/** Common libs */
+export * from './js/Digest.js'
+export * from './js/KeyPair.js'
+export * from './js/Token.js'
+
+/** Browser libs */
+export * from './js/Alert.js'
+export * from './js/BrowserApp.js'
+export * from './js/ParentHelper.js'
+export * from './js/QrCode.js'
+export * from './js/Storage.js'
+
+/** Backend libs */
+export * from './ts/Assertions.ts'
+export * from './ts/Lifecycle.ts'
+export * from './ts/Requests.ts'
+export * from './ts/Responses.ts'

package/js/Alert.js

@@ -0,0 +1,33 @@
+import { BrowserApp } from './BrowserApp.js'
+
+/**
+ * Returns the currently raised launch alert for this app,
+ * or null if none.
+ *
+ * @return { Promise<AlertType | null> } raised launch alert, or null if none.
+ * @throws {string} exception if alert catalog cannot be retrieved.
+ */
+export async function getLaunchAlert() {
+  const app = await BrowserApp.getInstance()
+  const origin = app.getPartyOrigin()
+  const url = new URL(`${origin}/catalog`)
+  url.searchParams.append('alert', '')
+  const response = await fetch(url, {
+    headers: {
+      'X-Tabserver-Token': this.getTokenBase64(),
+      'Accept': 'application/json'
+    }
+  })
+  const json = await response.json()
+  if ('error' in json) {
+    throw json.error
+  }
+
+  const alert = json.ok.alert.find(
+    alert => (
+      alert.type == 'LAUNCH' &&
+      alert.sourceUrl == app.getAppUrl()
+    )
+  )
+  return alert || null
+}

package/js/BrowserApp.js

@@ -0,0 +1,334 @@
+import { Token } from './Token.js'
+
+/**
+ * @module
+ * Provides convenience support for WebDaemon apps delivered
+ * through browsers.
+ *
+ * Use the singleton pattern, providing app name on first call
+ * to getInstance.
+ */
+
+const PARTY_PARAM = 'party'
+
+export class BrowserApp {
+  static #instance
+
+  #appName
+  #appUrlKey
+  #partyKey
+  #tokensKey
+
+  /**
+   * Gets the singleton instance of BrowserApp. On invocations
+   * after the first, the app name must be omitted or match
+   * the first-used app name.
+   *
+   * @param {string=} appName
+   * @return {Promise<BrowserApp>} instance of browser app.
+   */
+  static async getInstance(appName = null) {
+    if (
+      !appName &&
+      !BrowserApp.#instance
+    ) {
+      throw `Must provide app name`
+    }
+
+    if (
+      appName &&
+      BrowserApp.#instance &&
+      appName !== BrowserApp.#instance.#appName
+    ) {
+      throw `Cannot change app name to ${appName}`
+    }
+
+    if (!BrowserApp.#instance) {
+      BrowserApp.#instance = new BrowserApp(appName)
+      await BrowserApp.#instance.init()
+    }
+
+    return BrowserApp.#instance
+  }
+
+  /**
+   * Constructs a BrowserApp instance with the app name. This should be
+   * unique per origin. Spaces are _NOT_ allowed in this name.
+   *
+   * @param {string} appName a unique name for this app per origin.
+   */
+  constructor(appName) {
+    this.#appName = appName
+    this.#partyKey = `${appName}Party`
+    this.#tokensKey = `${appName}Tokens`
+    this.#appUrlKey = `${appName}Url`
+  }
+
+  /**
+   * Initialises the instance with the party name and tokens passed
+   * in the #fragment and ?query string search parameters.
+   *
+   *   - party is passed in the special parameter 'party'.
+   *   - tokens are passed in the remaining parameters keyed by host name.
+   *
+   * The entire #fragment is parsed into search params, if present.
+   * Query params whose name starts with the special character 'æ' are
+   * extracted, if present.
+   *
+   * The window location is replaced with the 'clean' version that
+   * no longer includes tokens.
+   *
+   * @return {Promise<BrowserApp>} instance promise.
+   * @throws {string} error if party token `src` does not match our window location.
+   */
+  async init() {
+    const ourUrl = new URL(globalThis.location)
+
+    // Extract and clear the fragment component before storing the url.
+    const tokenParams = new URLSearchParams(ourUrl.hash.substring(1))
+    ourUrl.hash = ''
+
+    // Extract matching query parameters, add them to the token params
+    // and clear them from the url.
+    for (const [key, value] of ourUrl.searchParams) {
+      if (key.startsWith('æ')) {
+        tokenParams.set(key.substring(1), value)
+        ourUrl.searchParams.delete(key)
+      }
+    }
+
+    sessionStorage[this.#appUrlKey] = ourUrl.toString()
+
+    if (tokenParams.has(PARTY_PARAM)) {
+      sessionStorage[this.#tokensKey] = tokenParams.toString()
+      const identityToken = this.getToken()
+      await identityToken.verifySignatory()
+      sessionStorage[this.#partyKey] = identityToken.getParty()
+
+      const srcUrl = identityToken.getSourceUrl()
+      if (srcUrl.origin !== ourUrl.origin || srcUrl.pathname !== ourUrl.pathname) {
+        throw `Party token is for different app: ${srcUrl}`
+      }
+    }
+
+    globalThis.history.replaceState(null, '', ourUrl.toString())
+    return this
+  }
+
+  /**
+   * Returns true if this app is an orphan, i.e. has not been launched from
+   * a Dæmon shell.
+   *
+   * Otherwise returns false.
+   *
+   * @return {boolean} true if an orphan without Dæmon, otherwise false.
+    */
+  isOrphan() {
+    return (
+      sessionStorage[this.#partyKey] == undefined ||
+      sessionStorage[this.#tokensKey] == undefined
+    )
+  }
+
+  /**
+   * Returns the app name. This is normally used to disambiguate properties
+   * of this app from others, such as those sharing a web origin and therefore
+   * sharing localStorage or sessionStorage.
+   *
+   * Note that this is a client-side name not known to the tabserver.
+   *
+   * @return {string} the app name.
+   */
+  getAppName() {
+    return this.#appName
+  }
+
+  /**
+   * Returns the app url, obtained from window.location at time of app init,
+   * or the empty string if not initialised.
+   *
+   * @return {string} the app url, or the empty string.
+   */
+  getAppUrl() {
+    return sessionStorage[this.#appUrlKey] || ''
+  }
+
+  /**
+   * Returns the party hostname, being the Dæmon that launched this app.
+   *
+   * @return {string} the party (Dæmon) hostname.
+   */
+  getParty() {
+    return sessionStorage[this.#partyKey]
+  }
+
+  /**
+   * Returns the party origin, being the protocol (http: or https:)
+   * and the party hostname.
+   *
+   * @return {string} the party origin.
+   */
+  getPartyOrigin() {
+    return `${globalThis.location.protocol}//${this.getParty()}`
+  }
+
+  /**
+   * Returns the base64-encoded token for the supplied party. If no
+   * party is specified, returns the token for the launching party.
+   *
+   * @param {string} party the party, or the launching party if not specified.
+   * @return {string} the base64-encoded token for the party.
+   */
+  getTokenBase64(party = PARTY_PARAM) {
+    const tokens = sessionStorage[this.#tokensKey]
+    const searchParams = new URLSearchParams(tokens)
+    const tokenBase64 = searchParams.get(party)
+    if (!tokenBase64) {
+      throw `No token for ${party}, check 'audience' in YML`
+    }
+    return tokenBase64
+  }
+
+
+  /**
+   * Gets the token for a party either as a base64-encoded string, or as a
+   * Token object depending on the asBase64 argument.
+   *
+   * If the party is not passed or is null, the default is the launching party.
+   * If the asBase64 is not passed, the default is true.
+   *
+   * @param {string=} party the audience for the token. Defaults to the identity token 'party'.
+   * @return {Token} the pre-generated token for the given party.
+   */
+  getToken(party = PARTY_PARAM) {
+    const tokenBase64 = this.getTokenBase64(party)
+    return new Token(tokenBase64)
+  }
+
+  /**
+   * Gets the value of the named parameter, or null if no value is supplied.
+   *
+   * The parameter name is case insensitive.
+   *
+   * The parameter is specified as:
+   *   - an attribute on the webdaemon meta tag, or
+   *   - a search parameter in the query string of the URL
+   *
+   * where the query string parameter takes priority if present.
+   *
+   * @param {string} name
+   * @return {string | null} parameter value or null if not present.
+   */
+  getParam(name) {
+
+    // Return a matching search parameter if present.
+    const searchParams = new URL(globalThis.location).searchParams
+    for (const [paramName, value] of searchParams) {
+      if (name.toLowerCase() == paramName.toLowerCase()) {
+        return value
+      }
+    }
+
+    // Return meta element attribute if present, or null.
+    const metaElement = document.querySelector('link[rel=webdaemon]')
+    return metaElement.getAttribute(name)
+  }
+
+  /**
+   * Returns true if the named parameter is present, even if with empty
+   * or null value.
+   *
+   * @param {string} name
+   * @return {boolean} true if the parameter exists, otherwise false.
+   */
+  hasParam(name) {
+    const searchParams = new URL(globalThis.location).searchParams
+    if (searchParams.has(name)) {
+      return true
+    }
+
+    const metaElement = document.querySelector('link[rel=webdaemon]')
+    return metaElement.hasAttribute(name)
+  }
+
+  /**
+   * Returns the currently raised launch alert for this app,
+   * or null if none.
+   *
+   * @return { Promise<AlertType | null> } raised launch alert, or null if none.
+   * @throws {string} exception if alert catalog cannot be retrieved.
+   */
+  async getLaunchAlert() {
+    const origin = this.getPartyOrigin()
+    const url = new URL(`${origin}/catalog`)
+    url.searchParams.append('alert', '')
+    const response = await fetch(url, {
+      headers: {
+        'X-Tabserver-Token': this.getTokenBase64(),
+        'Accept': 'application/json'
+      }
+    })
+    const json = await response.json()
+    if ('error' in json) {
+      throw json.error
+    }
+
+    const alert = json.ok.alert.find(
+      alert => (
+        alert.type == 'LAUNCH' &&
+        alert.sourceUrl == this.getAppUrl()
+      )
+    )
+    return alert || null
+  }
+
+  /**
+   * Resolves the currently raised launch alert for this app, if any.
+   *
+   * @throws {string} exception if alert cannot be resolved.
+   */
+  async resolveLaunchAlert() {
+    const origin = this.getPartyOrigin()
+    const url = new URL(`${origin}/resolve`)
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'X-Tabserver-Token': this.getTokenBase64(),
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        type: 'LAUNCH',
+        source: this.getAppUrl()
+      })
+    })
+    const json = await response.json()
+    if ('error' in json) {
+      throw json.error
+    }
+  }
+
+  /**
+   * Resolves the currently raised launch alert for this app, if any.
+   *
+   * @throws {string} exception if alert cannot be resolved.
+   */
+  async rejectLaunchAlert() {
+    const origin = this.getPartyOrigin()
+    const url = new URL(`${origin}/reject`)
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'X-Tabserver-Token': this.getTokenBase64(),
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        type: 'LAUNCH',
+        source: this.getAppUrl()
+      })
+    })
+    const json = await response.json()
+    if ('error' in json) {
+      throw json.error
+    }
+  }
+}

package/js/Digest.js

@@ -0,0 +1,45 @@
+/**
+ * Generates a SHA-1 digest of the supplied string, and returns
+ * it as a base64 string optionally truncated to the first 'length'
+ * characters.
+ *
+ * @param {string} message to digest.
+ * @return {Promise<string>} base64-encoded digest.
+ */
+export async function shortSafeDigest(message, length = 0) {
+  const msgUint8 = new TextEncoder().encode(message)
+  if (!crypto.subtle) {
+    throw 'Requires secure origin (localhost or https:)'
+  }
+  const hashBuffer = await crypto.subtle.digest("SHA-1", msgUint8)
+  const hashArray = new Uint8Array(hashBuffer)
+  const byteString = String.fromCodePoint(...hashArray)
+  const base64 = btoa(byteString)
+  const base64Safe = base64
+    .replaceAll('+','-')
+    .replaceAll('/','_')
+    .replaceAll('=','')
+  return length ? base64Safe.substring(0, length) : base64Safe
+}
+
+/**
+ * Generates a SHA-1 digest of the supplied string, and returns
+ * it as a hex string optionally truncated to the first 'length'
+ * characters.
+ *
+ * @param {string} message to digest.
+ * @return {Promise<string>} hex-encoded digest.
+ */
+export async function shortHexDigest(message, length = 0) {
+  const msgUint8 = new TextEncoder().encode(message)
+  if (!crypto.subtle) {
+    throw 'Requires secure origin (localhost or https:)'
+  }
+  const hashBuffer = await crypto.subtle.digest("SHA-1", msgUint8)
+  const hashArray = Array.from(new Uint8Array(hashBuffer))
+  const hashHex = hashArray
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('')
+
+  return length ? hashHex.substring(0, length) : hashHex
+}

package/js/KeyPair.js

@@ -0,0 +1,38 @@
+const DEFAULT_ALGORITHM = {
+  name: 'RSASSA-PKCS1-v1_5',
+  modulusLength: 2048,
+  publicExponent: new Uint8Array([0x01, 0x00, 0x01]),
+  hash: 'SHA-256'
+}
+
+export class KeyPair {
+  #algorithm
+  #keypair
+
+  constructor(algorithm = DEFAULT_ALGORITHM) {
+    this.#algorithm = algorithm
+    if (!crypto.subtle) {
+      throw 'Crypto.subtle requires secure environment'
+    }
+  }
+
+  async generate() {
+    this.#keypair = await crypto.subtle.generateKey(
+      this.#algorithm,
+      true,
+      ['sign', 'verify']
+    )
+  }
+
+  async publicJwk() {
+    const publicKey = this.#keypair.publicKey
+    const publicJwk = await crypto.subtle.exportKey('jwk', publicKey)
+    return publicJwk
+  }
+
+  async privateJwk() {
+    const privateKey = this.#keypair.privateKey
+    const privateJwk = await crypto.subtle.exportKey('jwk', privateKey)
+    return privateJwk
+  }
+}