webdaemon 11.4.1 → 11.4.3

package/src/js/Token.js

@@ -1,529 +0,0 @@
-/**
- * Encapsulates the functionality associated with a bearer token normally
- * passed in a request `x-tabserver-token` header as a base64-encoded
- * JSON object.
- *
- * Note the type definition annotations which are helpful when using this
- * Javascript class in Typescript.
- *
- * Example token:
- *
- * {
- *  "iss": "http://foo.daemon/some/public.jwk",
- *  "aud": "https://bar.daemon",
- *  "sub": "https://foo.daemon",
- *  "src": "https://some.com",
- *  "scope": {
- *    "http://localhost:9000/helloWorld1.html": "read write",
- *    "party:control": "grant revoke"
- *  }
- *  "iat": 1698576567000,
- *  "exp": 1698576344000,
- *  "sig": "long base64 string"
- * }
- *
- * Generally:
- *  iss - the issuer URL references the public JWK used to verify the sig.
- *  aud - the party handling the request, expressed as an origin.
- *  sub - the counterparty making the request, expressed as an origin.
- *  src - the source HTML file making the request, protocol://host/path only.
- *  scope - a map of requested source -> scope pairs.
- *          A scope is a space-separated list of capabilities.
- *  iat - issued at time in absolute millis.
- *  exp - expiry time, ditto.
- *  sig - the base64 signature, verified by the JWK pointed to by iss.
- *
- * Normally the sub field must match the host portion of the iss URL. But
- * the possiblity remains open for an intermediary trusted by the party to
- * hold the public keys of counterparties.
- */
-
-/**
- * @typedef {object.<string, string>} Scope
- */
-
-/**
- * @typedef TokenPayload
- * @type {object<string, Token>}
- * @property {string} iss   // URL of public key of counterparty making request.
- * @property {string} aud   // Party origin handling the request.
- * @property {string} sub   // Counterparty origin making the request.
- * @property {string} src   // Source HTML document context of the request excluding fragment and query.
- * @property {Scope} scope  // Map of scope (space-separated capabilities) keyed by source URL.
- * @property {number} iat   // Issued at time.
- * @property {number} exp   // Expiry time.
- *
- * @typedef SignedTokenPayload
- * @type {TokenPayload}
- * @property {string} sig      // Counterparty signs, `iss` used to verify.
- */
-
-/**
- * @typedef Signatory
- * @type {object}
- * @property {string} role     // Role label of this signatory.
- * @property {JSONWebKey} jwk  // Public JWK of this signatory.
- */
-
-/**
- * @typedef TokenSet
- * @type {object<string, Token>}
- */
-
-/** Must match algorithm in Keypair.js */
-const ALGORITHM = {
-  name: 'RSASSA-PKCS1-v1_5',
-  hash: 'SHA-256'
-}
-
-/** Matches an origin with protocol and no path. */
-const MATCH_ORIGIN = /https?:\/\/[^\/]+$/
-
-/**
- * Allow a 30s leeway to allow for clock difference when checking
- * token issued at time. We allow our clock to be up to 30s behind
- * the system that generated a token.
- */
-const TOKEN_IAT_LEEWAY_MILLIS = 1000 * 30
-
-export class Token {
-
-  // Standard sources.
-  static Source = {
-    PARTY_CONTROL: 'party:control' // Party control subject, a pseudo-source with scope granted to counterparties.
-  }
-
-  // Standard counterparty pattern.
-  static Counterparty = {
-    PUBLIC: 'public'              // Public counterparty, matching requests with no host specified in sub.
-  }
-
-  // Standard signatory roles.
-  static SignatoryRole = {
-    PARTY: 'party',
-    PARENT: 'parent'
-  }
-
-  // Standard scope labels.
-  static Capability = {
-    OPEN: 'open',         // Capability to open source files and start tab runners.
-    CLOSE: 'close',       // Capability to close source files and stop tab runners.
-    GRANT: 'grant',       // Capability to create relation records.
-    REVOKE: 'revoke',     // Capability to delete relation records.
-    OFFER: 'offer',       // Capability to create a party offer for a device to claim.
-    RETRACT: 'retract',   // Capability to delete a party offer before it is claimed.
-    DELETE: 'delete',     // Capability to delete devices.
-    CATALOG: 'catalog',   // Capability to get sources, devices, alerts etc.
-    ALIAS: 'alias',       // Capability to set the alias for a counterparty host.
-    UNALIAS: 'unalias',   // Capability to unset the alias for a counterparty host.
-    GET_ITEM: 'getitem',  // Capability to get a storage item.
-    SET_ITEM: 'setitem',  // Capability to set (and remove) a storage item.
-    ALERT: 'alert',       // Capability to post and delete alerts.
-    LOG: 'log',           // Capability to view logs.
-    READ: 'read',         // Capability to read from drive.
-    WRITE: 'write'        // Capability to write to drive.
-  }
-
-  static DEFAULT_EXPIRY_MILLIS = 1000 * 60 * 60 * 24
-  static TOKEN_HEADER = 'x-tabserver-token'
-  static SCOPE_SEPARATOR = /[\s,;\|]+/ // Specification per String.split() function.
-
-  /** @type{Token} */
-  #payload = null
-
-  /** @type{string} */
-  #signatureBase64 = null
-
-  /** @type{URL} */
-  #audUrl
-
-  /** @type{URL} */
-  #subUrl
-
-  /** @type{URL} */
-  #srcUrl
-
-  /** @type {Signatory} */
-  #signatory    // Set upon successful verification of signature.
-
-
-  /**
-   * Constructor takes either a signed base64 token, or a payload object.
-   *
-   * If successful, the payload and optionally the signature fields are
-   * populated.
-   *
-   * @param {object | string} source a payload, or a base64 token
-   */
-  constructor(source) {
-    let payload = null
-
-    if (typeof source == 'object') {
-      payload = source
-    }
-    else if (typeof source == 'string') {
-      try {
-        payload = JSON.parse(atob(source))
-      }
-      catch (_e) {
-        throw 'Invalid token format'
-      }
-    }
-    else {
-      throw `Cannot construct token from ${typeof source}`
-    }
-
-    // Separate out the signature from the payload.
-    this.#signatureBase64 = payload.sig
-    delete payload.sig
-    this.#payload = payload
-
-    const {
-      iss,
-      aud,
-      sub,
-      src,
-      scope,
-      iat,
-      exp
-    } = payload
-
-    // Check payload is complete.
-    if ((!iss || !aud || !sub || !src || !scope || !iat || !exp)) {
-      throw 'Token must include iss, aud, sub, src, scope, iat and exp'
-    }
-
-    // Check aud, sub and src fields are origins (i.e. proto://host.name)
-    if (
-      !aud.match(MATCH_ORIGIN) ||
-      !sub.match(MATCH_ORIGIN)
-    ) {
-      throw 'The aud and sub attributes must be origins'
-    }
-
-    this.#audUrl = new URL(aud)
-    this.#subUrl = new URL(sub)
-
-    // The `src` attribute must not have query or fragment.
-    if (
-      src.includes('?') ||
-      src.includes('#')
-    ) {
-      throw 'The src attribute must have no query or fragment component.'
-    }
-
-    this.#srcUrl = new URL(src)
-
-    this.#payload = payload
-  }
-
-  /**
-   * Generates the signature for the object using the private key provided by the
-   * supplied callback and stores the result.
-   *
-   * @param {Promise<JsonWebKey>} privateJwkPromise the private key used for signing.
-   * @return {Promise<string>} resolved with the base64 signature if signed successfully.
-   */
-  async signWith(privateJwkPromise) {
-    if (this.#payload == null) {
-      throw 'No payload to sign'
-    }
-
-    const privateJwk = await privateJwkPromise
-    const privateKey = await crypto.subtle.importKey('jwk', privateJwk, ALGORITHM, true, ['sign'])
-    const toSign = JSON.stringify(this.#payload)
-    const messageBuffer = new TextEncoder().encode(toSign).buffer
-    const signature = await crypto.subtle.sign(ALGORITHM, privateKey, messageBuffer)
-    const signatureBase64 = Token.bytesToBase64(new Uint8Array(signature))
-    this.#signatureBase64 = signatureBase64
-    return signatureBase64
-  }
-
-  /**
-   * Retrieves the signatory using the `iss` field, checks the signature
-   * and if valid sets the signatory property in this instance.
-   *
-   * @throws {string} if signatory cannot be retrieved or signature doesn't match.
-   */
-  async verifySignatory() {
-    await this.fetchSignatory()
-    await this.checkSignature(Promise.resolve(this.#signatory.jwk))
-  }
-
-  /**
-   * Fetches the signatory from the `iss` URL, setting the instance
-   * property.
-   *
-   * The signatory comprises the `role` label and  the public `jwk`.
-   *
-   * Caching may be introduced to reduce latency and bandwidth use.
-   *
-   * @throws {string} error if fetch fails or returns an error response.
-   */
-  async fetchSignatory() {
-    const issuer = this.getIssuer()
-    try {
-      const response = await fetch(issuer, {
-        headers: {
-          'content-type': 'application/json'
-        }
-      })
-
-      const json = await response.json()
-      if ('error' in json) {
-        throw json.error
-      }
-      this.#signatory = json.ok
-    }
-    catch (_e) {
-      throw `Failed to read signatory at ${issuer}`
-    }
-  }
-
-  /**
-   * Checks the signature using the public key provided by the supplied callback,
-   * and stores the result.
-   *
-   * @param {Promise<JsonWebKey>} publicJwkPromise the public key used to verify the signature.
-   * @throws {string} exception if signature cannot be verified or the public key is null or error.
-   */
-  async checkSignature(publicJwkPromise) {
-    const publicJwk = await publicJwkPromise
-    if (!publicJwk || 'error' in publicJwk) {
-      throw publicJwk.error
-    }
-    const publicKey = await crypto.subtle.importKey('jwk', publicJwk, ALGORITHM, true, ['verify'])
-    const toCheck = JSON.stringify(this.#payload)
-    const messageBuffer = new TextEncoder().encode(toCheck).buffer
-    const sigBuffer = Token.base64ToBytes(this.#signatureBase64).buffer
-    const isVerified = await crypto.subtle.verify(ALGORITHM, publicKey, sigBuffer, messageBuffer)
-    if (!isVerified) {
-      throw 'Signature cannot be verified'
-    }
-  }
-
-  /**
-   * Returns the payload with the `sig` property added.
-   *
-   * @return {SignedTokenPayload} the payload with additional `sig` property.
-   */
-  getSignedPayload() {
-    if (this.#signatureBase64 === null) {
-      throw 'Not yet signed'
-    }
-
-    return {
-      ...this.#payload,
-      sig: this.#signatureBase64
-    }
-  }
-
-  /**
-   * Returns the payload whether signed or not.
-   *
-   * @return {TokenPayload} the payload object without signature.
-   */
-  getPayload() {
-    return this.#payload
-  }
-
-  /**
-   * Returns the `aud` field as a string.
-   *
-   * @return {string} the `aud` field value.
-   */
-  getAud() {
-    return this.#audUrl.origin
-  }
-
-
-  /**
-   * Returns the `aud` host which is the party name handling the request.
-   *
-   * @return {string} the party name.
-   */
-  getParty() {
-    return this.#audUrl.host
-  }
-
-  /**
-   * Returns the `sub` field as a string.
-   *
-   * @return {string} the `sub` field value.
-   */
-  getSub() {
-    return this.#subUrl.origin
-  }
-
-  /**
-   * Returns the `sub` host, which is the counterparty name making the
-   * request.
-   *
-   * @return {string} the counterparty name.
-   */
-  getCounterparty() {
-    return this.#subUrl.host
-  }
-
-  /**
-   * Returns the role of the signatory who signed on behalf of the
-   * counterparty.
-   *
-   * @returns {string} role of the verified signatory.
-   */
-  getSignatoryRole() {
-    return this.#signatory.role
-  }
-
-  /**
-   * Returns the `src` URL.
-   *
-   * @return {URL} the source URL.
-   */
-  getSourceUrl() {
-    return this.#srcUrl
-  }
-
-  /**
-   * Returns the `issuer` field as a URL. The counterparty is inferred from
-   * the host name which generally matches the sub field.
-   *
-   * @return {URL} the issuer URL.
-   */
-  getIssuer() {
-    return new URL(this.getPayload().iss)
-  }
-
-  /**
-   * Returns the list of zero or more sources for which scope is requested.
-   *
-   * @return {string[]} a list of source URL strings.
-   */
-  getSources() {
-    const sources = []
-    for (const source in this.#payload.scope) {
-      sources.push(source)
-    }
-    return sources
-  }
-
-  /**
-   * Returns the scope for the source as an array of capability tokens.
-   *
-   * These can be separated by any mix of space, comma, semicolon
-   * or vertical bar.
-   *
-   * @param {string} source whose capabilities are returned.
-   * @return {string[]} zero or more scope tokens.
-   */
-  getCapabilities(source) {
-    const scope = this.#payload.scope
-    if (! (source in scope)) {
-      throw `Source '${source}' not in scope`
-    }
-
-    return scope[source].split(Token.SCOPE_SEPARATOR)
-  }
-
-  /**
-   * Returns true if the supplied capability is present in the token
-   * scope under the specified source, otherwise false.
-   *
-   * @param {string} source the source under which the capability is expected.
-   * @param {string} capability the capability being tested.
-   * @return {boolean} true if capability is present in the scope, otherwise false.
-   */
-  hasCapability(source, capability) {
-    return this.getCapabilities(source).includes(capability)
-  }
-
-  /**
-   * Checks the token is within the period defined by the `iat` and `exp`
-   * date fields.
-   *
-   * @throws {string} exception if not within valid period.
-   */
-  checkPeriod() {
-    const {
-      iat,
-      exp
-    } = this.#payload
-
-    const now = Date.now()
-    if (now < iat - TOKEN_IAT_LEEWAY_MILLIS) {
-      throw 'Token is not yet valid'
-    }
-
-    if (now > exp) {
-      throw 'Token has expired'
-    }
-  }
-
-  /**
-   * Returns the signed object including the `sig` property as a base64 string.
-   *
-   * @return {string} the signed object as a base64 string.
-   */
-  asSignedBase64() {
-    return btoa(JSON.stringify(this.getSignedPayload()))
-  }
-
-  /**
-   * Returns a base64 JSON string corresponding to the provided byte array.
-   *
-   * @param {Uint8Array} bytes to be encoded as a base64 string.
-   * @returns {string} the encoded bytes.
-   */
-  static bytesToBase64(bytes) {
-    const binString = Array.from(bytes, (x) => String.fromCodePoint(x)).join('');
-    return btoa(binString);
-  }
-
-  /**
-   * Returns the byte array decoded from the base64 string.
-   *
-   * @param {string} base64
-   * @returns {Uint8Array} the decoded bytes.
-   */
-  static base64ToBytes(base64) {
-    const binString = atob(base64);
-    return Uint8Array.from(binString, (m) => m.codePointAt(0));
-  }
-
-  /**
-   * Returns a new token using the x-tabserver-token header on the
-   * request.
-   *
-   * @param {Request} the request.
-   * @return {Token | null} the token, or null if no header is present.
-   * @throws {string} exception if token cannot be constructed.
-   */
-  static from(request) {
-    if (request.headers.has(Token.TOKEN_HEADER)) {
-      return new Token(request.headers.get(Token.TOKEN_HEADER))
-    }
-    return null
-  }
-
-  /**
-   * Converts an object whose string keys map to token objects
-   * into  URL-friendly search params suitable for use in a
-   * query string or fragment.
-   *
-   * The string keys are normally the audience hostname, or the
-   * special key 'party' which holds the identity token whose
-   * `aud` and `sub` are the same.
-   *
-   * @param {TokenSet} tokenSet the set of tokens keyed by string.
-   * @returns {string}
-   */
-  static toSearchString(tokenSet) {
-    const searchParams = new URLSearchParams()
-    for (const key in tokenSet) {
-      const token = tokenSet[key]
-      const tokenBase64 = token.asSignedBase64()
-      searchParams.append(key, tokenBase64)
-    }
-    return searchParams.toString()
-  }
-}

package/src/ts/Assertions.ts

@@ -1,41 +0,0 @@
-/**
- * Use this type to reference a plain object with
- * random string keys.
- */
-export interface Plain {
-  // deno-lint-ignore no-explicit-any
-  [key: string]: any
-}
-
-/**
- * Any JSON-serialisable type.
- */
-export type JSONPrimitive = string | number | boolean | null
-export type JSONArray = JSONValue[]
-export interface JSONObject {
-  [key: string]: JSONValue
-}
-export type JSONValue = JSONPrimitive | JSONObject | JSONArray
-
-
-/**
- * Type predicates to be used in type-narrowing assertions, e.g.
- *
- *   assert(notNull(someValue))
- *   ... now the type of someValue does not include null ...
- *
- * or
- *  if (isOk(returnValue)) {
- *     ...in this block we know returnValue.ok is present and of the correct type.
- *  }
- *
- * @param value the value to be tested.
- * @returns true if not null, otherwise false.
- */
-export function notNull<T>(value: T | null): value is T {
-  return value !== null
-}
-
-export function isDefined<T>(value: T | undefined): value is T {
-  return value !== undefined
-}