Source: keys.js

import { calculateJwkThumbprint, exportJWK, generateKeyPair, importJWK } from 'jose';

/** Client key algorithms this library can sign HTTP messages with, in preference order. */
export const CLIENT_KEY_ALGS = Object.freeze(['ES256', 'ES384', 'PS256', 'RS256']);

/** WebCrypto parameters for signing with each JWS algorithm (RFC 9421 section 3.3.7). */
const SIGN_PARAMS = {
  ES256: { name: 'ECDSA', hash: 'SHA-256' },
  ES384: { name: 'ECDSA', hash: 'SHA-384' },
  PS256: { name: 'RSA-PSS', saltLength: 32 },
  RS256: { name: 'RSASSA-PKCS1-v1_5' },
};

/**
 * Where the client key pair is kept between page loads. `extractable: true` says the store can only hold
 * an extractable key (Web Storage holds strings), so `ClientKey.loadOrCreate` generates one.
 * @typedef {object} KeyStore
 * @property {() => Promise<StoredKey|undefined>} get
 * @property {(value: StoredKey) => Promise<void>} set
 * @property {() => Promise<void>} delete
 * @property {boolean} [extractable]
 */

/**
 * @typedef {object} StoredKey
 * @property {string} alg
 * @property {CryptoKeyPair} keyPair
 */

/**
 * The client instance's key (RFC 9635 section 7.1). In GNAP the key IS the client: it is presented by
 * value in the first request, and every request after is signed with it, so each token the AS issues is
 * bound to it. This library proves it with HTTP message signatures (`httpsig`, RFC 9421).
 *
 * The private key is generated NON-EXTRACTABLE: script running in the page (including injected script)
 * can ask it to sign while the page is open, but can never read it out, so a stolen access token or
 * continuation token is useless anywhere else. `IndexedDBKeyStore` keeps that non-extractable key across
 * page loads. `WebStorageKeyStore` keeps an extractable copy in sessionStorage for this tab, which is what
 * Web Storage can hold.
 *
 * The JWK's `kid` is its RFC 7638 thumbprint, and is the `keyid` of every signature.
 */
export class ClientKey {
  #privateKey;
  /** The public JWK, with `alg` and `kid`. @type {Record<string, any>} */
  publicJwk;
  /** @type {string} */
  alg;
  /** RFC 7638 SHA-256 thumbprint of the public key; also its `kid`. @type {string} */
  thumbprint;
  /** @type {CryptoKeyPair|undefined} */
  keyPair;

  /**
   * Use `ClientKey.create()` or `ClientKey.loadOrCreate()` rather than this.
   * @param {string} alg
   * @param {CryptoKey} privateKey
   * @param {Record<string, any>} publicJwk
   * @param {string} thumbprint
   */
  constructor(alg, privateKey, publicJwk, thumbprint) {
    if (!SIGN_PARAMS[alg]) throw new TypeError(`Unsupported client key alg ${alg} (supported: ${CLIENT_KEY_ALGS.join(', ')})`);
    this.alg = alg;
    this.#privateKey = privateKey;
    this.publicJwk = publicJwk;
    this.thumbprint = thumbprint;
  }

  /**
   * Builds a key from a CryptoKeyPair, generating a new pair if none is given.
   * Generated keys are non-extractable unless `extractable` is set, which sessionStorage requires.
   * @param {{ alg?: string, keyPair?: CryptoKeyPair, extractable?: boolean }} [opts]
   * @returns {Promise<ClientKey>}
   */
  static async create({ alg = 'ES256', keyPair, extractable = false } = {}) {
    if (!SIGN_PARAMS[alg]) throw new TypeError(`Unsupported client key alg ${alg} (supported: ${CLIENT_KEY_ALGS.join(', ')})`);
    const pair = keyPair ?? await generateKeyPair(alg, { extractable });
    const { kty, crv, x, y, n, e } = await exportJWK(pair.publicKey);
    const bare = Object.fromEntries(Object.entries({ kty, crv, x, y, n, e }).filter(([, v]) => v !== undefined));
    const thumbprint = await calculateJwkThumbprint(bare, 'sha256');
    const key = new ClientKey(alg, pair.privateKey, { ...bare, alg, kid: thumbprint }, thumbprint);
    key.keyPair = pair;
    return key;
  }

  /**
   * Loads the key held in `store`, or creates one and stores it.
   * @param {KeyStore} store
   * @param {{ alg?: string }} [opts]
   * @returns {Promise<ClientKey>}
   */
  static async loadOrCreate(store, { alg = 'ES256' } = {}) {
    const held = await store.get();
    if (held?.keyPair && held.alg === alg) return ClientKey.create({ alg, keyPair: held.keyPair });
    const key = await ClientKey.create({ alg, extractable: store.extractable === true });
    await store.set({ alg, keyPair: /** @type {CryptoKeyPair} */ (key.keyPair) });
    return key;
  }

  /**
   * The key object a grant request carries by value (RFC 9635 section 7.1): the proof method and the
   * public JWK. Register exactly this on the AS (iya-sts: the application's `gnapKey`).
   * @returns {{ proof: string, jwk: Record<string, any> }}
   */
  keyObject() {
    return { proof: 'httpsig', jwk: { ...this.publicJwk } };
  }

  /**
   * Signs bytes with the private key, as RFC 9421 section 3.3.7 does for a JWS algorithm: ECDSA
   * signatures are the raw `r || s` concatenation, which is what WebCrypto produces.
   * @param {Uint8Array} data
   * @returns {Promise<Uint8Array>}
   */
  async sign(data) {
    return new Uint8Array(await crypto.subtle.sign(SIGN_PARAMS[this.alg], this.#privateKey, data));
  }
}

/**
 * Keeps one client key pair in IndexedDB. CryptoKeys are stored as-is (structured clone), so a
 * non-extractable private key survives page loads without ever being exported.
 */
export class IndexedDBKeyStore {
  #name;
  #key;

  /** @param {{ database?: string, key?: string }} [opts] */
  constructor({ database = 'gnap-caep-client', key = 'client-key' } = {}) {
    this.#name = database;
    this.#key = key;
  }

  #open() {
    return new Promise((resolve, reject) => {
      const req = indexedDB.open(this.#name, 1);
      req.onupgradeneeded = () => req.result.createObjectStore('keys');
      req.onsuccess = () => resolve(req.result);
      req.onerror = () => reject(req.error);
    });
  }

  async #tx(mode, fn) {
    const db = await this.#open();
    try {
      return await new Promise((resolve, reject) => {
        const tx = db.transaction('keys', mode);
        const req = fn(tx.objectStore('keys'));
        tx.oncomplete = () => resolve(req.result);
        tx.onerror = () => reject(tx.error);
      });
    } finally {
      db.close();
    }
  }

  /** @returns {Promise<StoredKey|undefined>} */
  get() { return this.#tx('readonly', (s) => s.get(this.#key)); }
  /** @param {StoredKey} value @returns {Promise<void>} */
  set(value) { return this.#tx('readwrite', (s) => s.put(value, this.#key)); }
  /** @returns {Promise<void>} */
  delete() { return this.#tx('readwrite', (s) => s.delete(this.#key)); }
}

/**
 * Keeps one client key pair in Web Storage, sessionStorage by default. Storage holds strings, so the
 * private key is a JWK and therefore extractable. It survives a reload and the round trip to the
 * authorization server, and it is cleared when the tab closes.
 */
export class WebStorageKeyStore {
  #storage;
  #key;

  /** @param {{ storage?: Storage, key?: string }} [opts] */
  constructor({ storage = globalThis.sessionStorage, key = 'gnap-caep-client:client-key' } = {}) {
    if (!storage) throw new TypeError('Web Storage is not available here');
    this.extractable = true;
    this.#storage = storage;
    this.#key = key;
  }

  /** @returns {Promise<StoredKey|undefined>} */
  async get() {
    const raw = this.#storage.getItem(this.#key);
    if (!raw) return undefined;
    const saved = JSON.parse(raw);
    if (!saved?.alg || !saved.privateJwk || !saved.publicJwk) return undefined;
    const [privateKey, publicKey] = await Promise.all([
      importJWK(saved.privateJwk, saved.alg, { extractable: true }),
      importJWK(saved.publicJwk, saved.alg),
    ]);
    return { alg: saved.alg, keyPair: { privateKey: /** @type {CryptoKey} */ (privateKey), publicKey: /** @type {CryptoKey} */ (publicKey) } };
  }

  /** @param {StoredKey} value @returns {Promise<void>} */
  async set(value) {
    const privateKey = value?.keyPair?.privateKey;
    if (!privateKey?.extractable) throw new TypeError('WebStorageKeyStore can only store an extractable private key');
    const [privateJwk, publicJwk] = await Promise.all([exportJWK(privateKey), exportJWK(value.keyPair.publicKey)]);
    this.#storage.setItem(this.#key, JSON.stringify({ alg: value.alg, privateJwk, publicJwk }));
  }

  async delete() {
    this.#storage.removeItem(this.#key);
  }
}

/** Keeps a client key in memory only (a new key, so a new client instance, after every page load). */
export class MemoryKeyStore {
  #value;
  /** @returns {Promise<StoredKey|undefined>} */
  async get() { return this.#value; }
  /** @param {StoredKey} value */
  async set(value) { this.#value = value; }
  async delete() { this.#value = undefined; }
}