@quran-lab/tajweedformer 0.0.0-stage → 2.0.0

package/web/platform/client.js

@@ -0,0 +1,366 @@
+// The Quran Lab platform client for the web product: the
+// developer key, an unattested app token, register, the signed config (Ed25519 over the exact bytes,
+// pinned key ids, ETag, 60 s refresh while in use), the tajweed block into the model's settings,
+// telemetry v2 (on by default, anonymous), issues, and the learner's sharing routes. Nothing here sits
+// in the recognition path: a failing network never stops recognition.
+//
+//   import { QuranLab } from '@quran-lab/tajweedformer/platform';
+//   const ql = await QuranLab.configure({ key: 'qlk_v1_...', appVersion: '1.4.0' });
+//   const tf = await TajweedFormer.load({ platform: ql });   // the recommended model, settings, telemetry
+
+import { Telemetry, deviceInfo, utcDay } from './telemetry.js';
+import { localState } from './storage.js';
+import { QURANLAB_PUBLIC_KEY_HEX, hexToBytes, bytesToHex } from '../tajweed/manifest.js';
+import { decode } from '../tajweed/decode.js';
+
+export const SDK_VERSION = '2.0.0';
+export const API_URL = 'https://api.quranlab.ai';
+export const CDN_URL = 'https://cdn.quranlab.ai';
+/** Where model files are served: {base}/{owner}/{repo}/{revision}/{path}. The signed config's `base`
+ * replaces it when present; a cdnUrl given without modelsUrl keeps the old {cdn}/hf/ path. */
+export const MODELS_URL = 'https://cdn.quranlab.ai/models';
+const SAFE_BASE = /^(https:\/\/[A-Za-z0-9.-]+(:\d+)?|http:\/\/(localhost|127\.0\.0\.1)(:\d+)?)(\/[A-Za-z0-9._~\/-]*)?$/;
+const REGIONAL_CDN = /^https:\/\/((weur|eeur|enam|wnam|apac|oc)\.)?cdn\.quranlab\.ai$/;
+const ISSUE_KINDS = ['engine_failed', 'model_load', 'checksum_mismatch', 'signature_invalid', 'update_failed', 'fallback',
+  'self_test_failed', 'audio_input', 'other'];
+/** Codes after which the client stops all network calls until the next launch (error table). */
+const STOP_CODES = new Set(['invalid_key', 'unauthorized', 'developer_not_approved', 'not_a_member', 'key_type_mismatch',
+  'origin_not_allowed', 'app_not_allowed', 'app_blocked', 'environment_mismatch', 'sdk_too_old']);
+
+/** A platform failure: { status, code } from the API's {"error","message"} body. */
+export class PlatformError extends Error {
+  constructor(status, code, message) { super(`${status} ${code}${message ? ': ' + message : ''}`); this.name = 'PlatformError'; this.status = status; this.code = code; }
+}
+
+const subtle = () => globalThis.crypto.subtle;
+const b64uToBytes = (s) => {
+  const t = s.replace(/-/g, '+').replace(/_/g, '/');
+  const bin = atob(t + '='.repeat((4 - (t.length % 4)) % 4));
+  return Uint8Array.from(bin, (c) => c.charCodeAt(0));
+};
+
+/** The key id of a raw 32-byte Ed25519 public key: the first 8 bytes of its SHA-256, hex. */
+export async function keyId(raw) {
+  const b = typeof raw === 'string' ? hexToBytes(raw) : raw;
+  return bytesToHex(new Uint8Array(await subtle().digest('SHA-256', b)).subarray(0, 8));
+}
+
+/**
+ * Verify a signed config response (PLATFORM_CLIENT.md section 3): the key id pinned, Ed25519 over
+ * the exact body bytes, v 1, not expired. Returns the parsed config, or throws PlatformError
+ * 'signature_invalid' / 'config_expired'.
+ * @param {Uint8Array} body  the body bytes as received
+ * @param {string|null} sigHeader  x-qlab-signature ("ed25519=<base64url>")
+ * @param {string|null} kid  x-qlab-key-id
+ * @param {Array<string|Uint8Array>} trustedKeys  raw public keys (hex or bytes)
+ */
+export async function verifySignedConfig(body, sigHeader, kid, trustedKeys, now = Date.now()) {
+  if (!sigHeader || !sigHeader.startsWith('ed25519=') || !kid) throw new PlatformError(0, 'signature_invalid', 'no signature');
+  let sig;
+  try { sig = b64uToBytes(sigHeader.slice(8)); } catch (_) { throw new PlatformError(0, 'signature_invalid', 'bad signature encoding'); }
+  let ok = false;
+  for (const k of trustedKeys) {
+    if ((await keyId(k)) !== kid) continue;
+    const key = await subtle().importKey('raw', typeof k === 'string' ? hexToBytes(k) : k, { name: 'Ed25519' }, false, ['verify']);
+    if (await subtle().verify({ name: 'Ed25519' }, key, sig, body)) { ok = true; break; }
+  }
+  if (!ok) throw new PlatformError(0, 'signature_invalid', `the config does not verify with a pinned key (kid ${kid})`);
+  const cfg = JSON.parse(new TextDecoder().decode(body));
+  if (cfg.v !== 1) throw new PlatformError(0, 'signature_invalid', `config v ${cfg.v}`);
+  if (!(typeof cfg.expires_at === 'number' && cfg.expires_at * 1000 > now)) throw new PlatformError(0, 'config_expired', 'the config has expired');
+  return cfg;
+}
+
+/**
+ * One configured client. Use QuranLab.configure(...).
+ */
+export class QuranLab {
+  /**
+   * @param {object} o
+   * @param {string} o.key  the developer key qlk_v1_... (a web key in browsers; a desktop key in Node)
+   * @param {string} [o.appVersion]
+   * @param {string} [o.appName]
+   * @param {string} [o.platform]  'web' (browsers, default), or 'linux' / 'windows' / 'web' in Node
+   * @param {string} [o.bundleId]  web: the page's origin (default location.origin); desktop: the app id
+   * @param {string} [o.origin]  Node with a web key: the Origin header to send
+   * @param {'on'|'off'} [o.analytics='on']  the one developer opt-out; never a prompt
+   * @param {boolean} [o.issues=true]
+   * @param {boolean} [o.contributions=false]  recitation sharing (asks the learner first)
+   * @param {'general'|'children'} [o.audience]
+   * @param {number} [o.sharingBitrate]  Opus bit/s for shared sessions (default 192000, SHARING_BITRATE_DEFAULT)
+   * @param {object} [o.state]  persistence (default localStorage; Node: dirState(dir))
+   * @param {Array<string|Uint8Array>} [o.trustedKeys]  pinned config keys (default Quran Lab's)
+   * @param {string} [o.apiUrl] [o.modelsUrl] [o.cdnUrl] [o.fetch] [o.clock]  o.modelsUrl: model files (default the
+   *   signed config's base, else cdn.quranlab.ai/models); o.cdnUrl alone: the old {cdn}/hf/ path
+   */
+  constructor(o) {
+    if (!o || typeof o.key !== 'string' || !/^qlk_v1_/.test(o.key)) throw new TypeError('QuranLab: a developer key qlk_v1_... is needed');
+    const inBrowser = typeof globalThis.window !== 'undefined' && !!globalThis.location;
+    this.key = o.key;
+    this.apiUrl = (o.apiUrl || API_URL).replace(/\/$/, '');
+    this.cdnUrl = (o.cdnUrl || CDN_URL).replace(/\/$/, '');
+    this.modelsUrl = o.modelsUrl ? o.modelsUrl.replace(/\/+$/, '') : null;
+    this.legacyCdn = !!o.cdnUrl && !o.modelsUrl;
+    this.platform = o.platform || 'web';
+    this.bundleId = o.bundleId || (inBrowser ? globalThis.location.origin : null);
+    if (!this.bundleId) throw new TypeError('QuranLab: bundleId is needed outside a browser (the origin for a web key, the app id for a desktop key)');
+    this.origin = o.origin || null; // Node only: browsers set Origin themselves
+    this.appVersion = o.appVersion || '0';
+    this.appName = o.appName || null;
+    this.fetch = o.fetch || globalThis.fetch.bind(globalThis);
+    this.clock = o.clock || Date.now;
+    this.state = o.state || localState();
+    this.trustedKeys = o.trustedKeys || [QURANLAB_PUBLIC_KEY_HEX];
+    this.analyticsOn = o.analytics !== 'off';
+    this.issuesOn = o.issues !== false;
+    this.contributions = !!o.contributions;
+    this.audience = o.audience || 'general';
+    this.sharingBitrate = o.sharingBitrate || null;
+    this.stopped = null; // the code that stopped the network this launch
+    this.config = null;
+    this._token = null;
+    this._timer = null;
+    this.telemetry = new Telemetry({ state: this.state, product: 'web', platform: this.platform, sdkVersion: SDK_VERSION,
+      appVersion: this.appVersion, device: deviceInfo(), clock: this.clock, enabled: this.analyticsOn });
+    // the stored signed config, if still valid, until the network answers
+    const saved = this.state.get('config');
+    if (saved && saved.cfg && saved.cfg.expires_at * 1000 > this.clock()) this.config = saved.cfg;
+    if (this.state.get('bucket') === null) this.state.set('bucket', Math.floor(Math.random() * 100));
+  }
+
+  /** Configure and run the launch sequence (token, register, config, pending telemetry and issues).
+   * Never throws for network trouble; check `ql.stopped` and `ql.lastError`. */
+  static async configure(o) {
+    const ql = new QuranLab(o);
+    await ql.launch();
+    return ql;
+  }
+
+  get flags() { return (this.config && this.config.flags) || { analytics: true, issues: true, contributions: false }; }
+
+  // ---- HTTP ----
+  async _call(method, path, { body = null, auth = 'token', headers = {}, raw = false } = {}) {
+    if (this.stopped) throw new PlatformError(0, this.stopped, 'stopped for this launch');
+    const h = { ...headers };
+    if (this.origin) h.origin = this.origin;
+    if (auth === 'key') h['x-qlab-key'] = this.key;
+    else if (auth === 'token') h.authorization = `Bearer ${await this.token()}`;
+    if (body !== null) h['content-type'] = 'application/json';
+    const r = await this.fetch(this.apiUrl + path, { method, headers: h, body: body === null ? undefined : JSON.stringify(body) });
+    if (raw) return r;
+    if (r.status >= 400) {
+      let e = {};
+      try { e = await r.json(); } catch (_) { /* no body */ }
+      const err = new PlatformError(r.status, e.error || 'http_' + r.status, e.message || '');
+      if (STOP_CODES.has(err.code)) this.stopped = err.code;
+      if (err.code === 'invalid_token' && auth === 'token' && !headers['x-retried']) {
+        this._token = null; this.state.set('token', null);
+        return this._call(method, path, { body, auth, headers: { ...headers, 'x-retried': '1' } }).catch((e2) => { throw e2; });
+      }
+      throw err;
+    }
+    return r.status === 204 || r.status === 304 ? null : r.json();
+  }
+
+  /** An unattested app token (24 h), renewed when under 1 h is left. */
+  async token() {
+    const now = this.clock() / 1000;
+    const t = this._token || this.state.get('token');
+    if (t && t.exp - now > 3600) { this._token = t; return t.token; }
+    const r = await this._call('POST', '/v1/attest', { auth: 'key', body: { platform: this.platform, bundle_id: this.bundleId } });
+    this._token = { token: r.token, exp: now + (r.expires_in || 86400), attested: !!r.attested };
+    this.state.set('token', this._token);
+    return r.token;
+  }
+
+  // ---- launch ----
+  async launch() {
+    const steps = [() => this.register(), () => this.refreshConfig(), () => this.flush()];
+    for (const s of steps) {
+      try { await s(); } catch (e) { this.lastError = e; if (this.stopped) break; }
+    }
+  }
+
+  /** POST /v1/register, once per launch. */
+  async register() {
+    if (this._registered) return this._registered;
+    const first = this.state.get('installed') === null;
+    if (first) this.state.set('installed', true);
+    const pendingNew = this.state.get('register.pending_new') === true;
+    const newInstall = first || pendingNew;
+    this.state.set('register.pending_new', newInstall);
+    const body = { platform: this.platform, bundle_id: this.bundleId, app_version: this.appVersion, sdk_version: SDK_VERSION, new_install: newInstall };
+    if (this.appName) body.app_name = this.appName;
+    if (this.modelRevision) body.model_revision = this.modelRevision;
+    this._registered = await this._call('POST', '/v1/register', { body });
+    this.state.set('register.pending_new', null);
+    return this._registered;
+  }
+
+  /**
+   * GET /v1/config with If-None-Match; verifies and stores it. A failure keeps the last good config.
+   * Returns the config in force (or null).
+   */
+  async refreshConfig() {
+    const saved = this.state.get('config');
+    const nearExpiry = saved && saved.cfg && saved.cfg.expires_at * 1000 - this.clock() < 3600_000;
+    const q = new URLSearchParams({ bucket: String(this.state.get('bucket')), sdk: SDK_VERSION });
+    const headers = {};
+    if (saved && saved.etag && !nearExpiry) headers['if-none-match'] = saved.etag;
+    const r = await this._call('GET', `/v1/config?${q}`, { headers, raw: true });
+    if (r.status === 304 && saved) { this.config = saved.cfg; return this.config; }
+    if (r.status >= 400) {
+      let e = {};
+      try { e = await r.json(); } catch (_) { /* none */ }
+      const err = new PlatformError(r.status, e.error || 'http_' + r.status, e.message);
+      if (STOP_CODES.has(err.code)) this.stopped = err.code;
+      throw err;
+    }
+    const body = new Uint8Array(await r.arrayBuffer());
+    let cfg;
+    try {
+      cfg = await verifySignedConfig(body, r.headers.get('x-qlab-signature'), r.headers.get('x-qlab-key-id'), this.trustedKeys, this.clock());
+    } catch (e) {
+      this.reportIssue('signature_invalid', 'config:' + e.code);
+      throw e;
+    }
+    this.config = cfg;
+    this.state.set('config', { cfg, etag: r.headers.get('etag'), sig: r.headers.get('x-qlab-signature'), kid: r.headers.get('x-qlab-key-id') });
+    if (cfg.flags && cfg.flags.analytics === false) this.telemetry.clear();
+    this.telemetry.enabled = this.analyticsOn && !(cfg.flags && cfg.flags.analytics === false);
+    for (const tf of this._models || []) tf.setRemoteConfig(cfg);
+    return cfg;
+  }
+
+  /** Refresh the config every `ms` (60 s) while the app is in use; call stop() when it is not. */
+  startRefresh(ms = 60_000) {
+    this.stopRefresh();
+    this._timer = setInterval(() => { this.refreshConfig().catch(() => {}); }, ms);
+    if (this._timer && typeof this._timer.unref === 'function') this._timer.unref();
+  }
+  stopRefresh() { if (this._timer) clearInterval(this._timer); this._timer = null; }
+
+  /** Where the recommended model lives on the CDN: { url, headers } for TajweedFormer.load. */
+  async modelSource() {
+    const cfg = this.config || (await this.refreshConfig().catch(() => null));
+    const rec = cfg && cfg.recommended;
+    if (!rec || !rec.revision) throw new PlatformError(0, 'no_model', 'the config recommends no model for this app and SDK');
+    const enc = (p) => p.split('/').map(encodeURIComponent).join('/');
+    this.modelRevision = `${rec.model_id || 'v4.0'}+${rec.revision}`.slice(0, 64);
+    // the base: the app's modelsUrl, else the signed config's base, else the app's cdnUrl (old /hf/ path), else
+    // cdn.quranlab.ai/models. A bare cdn.quranlab.ai base always means the /hf/ path.
+    const signed = typeof cfg.base === 'string' && SAFE_BASE.test(cfg.base) ? cfg.base.replace(/\/+$/, '') : null;
+    let base = this.modelsUrl || signed || (this.legacyCdn ? this.cdnUrl + '/hf' : MODELS_URL);
+    if (REGIONAL_CDN.test(base)) base += '/hf';
+    return { url: `${base}/${enc(rec.model)}/${enc(rec.revision)}/${enc(rec.folder || 'sdk/' + rec.model_id)}/`,
+      headers: { 'x-qlab-key': this.key, ...(this.origin ? { origin: this.origin } : {}) } };
+  }
+
+  /** Called by TajweedFormer.load({ platform }): the portal's settings and the telemetry hooks. */
+  attach(tf) {
+    this._models = (this._models || []).filter((x) => x._eng);
+    this._models.push(tf);
+    if (this.config) tf.setRemoteConfig(this.config);
+    tf._telemetry = this;
+    this.telemetry.modelLoaded(tf, tf.loadMs || 0);
+    if (tf.delivery) {
+      this.telemetry.download({ revision: this.modelRevision || 'unknown', profile: 'web-cpu', bytes: tf.delivery.bytesDownloaded,
+        success: true, resumed: tf.delivery.rangesResumed > 0 });
+    }
+  }
+
+  // hooks the model calls (tajweedformer.js)
+  streamStarted(tf, s) {
+    const self = this;
+    const timings = [];
+    let samples = 0, firstAt = null;
+    const t0 = this.clock();
+    const push = s.pushAudio.bind(s), finish = s.finish.bind(s), reset = s.reset.bind(s), free = s.free.bind(s);
+    const timed = (fn, n) => { const a = performance.now(); const k = fn(); const ms = performance.now() - a; if (k > 0) for (let i = 0; i < k; i++) timings.push(ms / k); return k; };
+    const end = (aborted) => {
+      if (!samples) return;
+      self.telemetry.session(tf, { seconds: samples / tf.sampleRate, chunkMs: timings.splice(0), aborted, firstMs: firstAt });
+      try { self.telemetry.decoded(tf, decode(s.heads(), {})); } catch (_) { /* freed */ }
+      samples = 0;
+    };
+    s.pushAudio = (pcm) => { if (firstAt === null) firstAt = self.clock() - t0; samples += pcm.length; return timed(() => push(pcm)); };
+    s.finish = () => { const k = timed(finish); end(false); return k; };
+    s.reset = () => { end(true); return reset(); };
+    s.free = () => { end(true); return free(); };
+    if (this.sharing && typeof this.sharing.streamStarted === 'function') this.sharing.streamStarted(tf, s);
+  }
+  scored(tf, result) { this.telemetry.scored(tf, result); }
+
+  // ---- telemetry and issues ----
+  /** Send every completed day (202 drop, 400 drop, 401 renew once, else keep) and queued issues. */
+  async flush() {
+    let sent = 0;
+    if (this.telemetry.enabled && this.flags.analytics !== false) {
+      for (const p of this.telemetry.pending()) {
+        try { await this._call('POST', '/v1/events', { body: p }); this.telemetry.drop(p.day); sent++; } catch (e) {
+          if (e.status === 400 || e.status === 413) this.telemetry.drop(p.day); else break;
+        }
+      }
+    } else if (this.flags.analytics === false) this.telemetry.clear();
+    const issues = this.state.get('issues.queue') || [];
+    const keep = [];
+    for (const i of issues) {
+      if (!this.issuesOn || this.flags.issues === false) break;
+      try { await this._call('POST', '/v1/issues', { body: i }); } catch (e) { if (!(e.status === 400)) keep.push(i); }
+    }
+    this.state.set('issues.queue', this.flags.issues === false ? [] : keep);
+    return sent;
+  }
+
+  /** Queue an issue report (no free text, no paths); one per kind+code per day. */
+  reportIssue(kind, code, frames = []) {
+    if (!this.issuesOn) return false;
+    const k = ISSUE_KINDS.includes(kind) ? kind : 'other';
+    const c = String(code).replace(/[^A-Za-z0-9_.:-]/g, '_').slice(0, 64) || 'unknown';
+    const day = utcDay(this.clock());
+    const seen = this.state.get('issues.seen') || {};
+    const sig = `${day}|${k}|${c}`;
+    if (seen[sig]) return false;
+    for (const s of Object.keys(seen)) if (!s.startsWith(day)) delete seen[s];
+    seen[sig] = 1;
+    this.state.set('issues.seen', seen);
+    const ua = (globalThis.navigator && globalThis.navigator.userAgent) || '';
+    const q = this.state.get('issues.queue') || [];
+    q.push({ day, platform: this.platform, sdk_version: SDK_VERSION, app_version: this.appVersion,
+      os_version: String(this.telemetry.device.os_major), device_class: this.telemetry.device.class, backend: 'exact',
+      ...(this.modelRevision ? { revision: this.modelRevision } : {}), kind: k, code: c,
+      ...(frames.length ? { frames: frames.slice(0, 16).map((f) => String(f).slice(0, 80)) } : {}) });
+    this.state.set('issues.queue', q.slice(-20));
+    void ua;
+    return true;
+  }
+
+  // ---- the learner's sharing routes (section 9) ----
+  /** The contribution code (32 hex), created on first use, stored per origin. */
+  contributor() {
+    let c = this.state.get('contributor');
+    if (!c) {
+      const b = new Uint8Array(16);
+      globalThis.crypto.getRandomValues(b);
+      c = bytesToHex(b);
+      this.state.set('contributor', c);
+    }
+    return c;
+  }
+  resetContributor() { this.state.set('contributor', null); }
+
+  /** GET /v1/contributions/summary (real numbers only; null when it fails). */
+  async contributionSummary() {
+    try { return await this._call('GET', '/v1/contributions/summary', { headers: { 'x-qlab-contributor': this.contributor() } }); } catch (_) { return null; }
+  }
+
+  /** Whether this install may upload under the signed config (flags.contributions and upload_trust). */
+  sharingAllowed() {
+    const f = this.flags;
+    if (!this.contributions || f.contributions !== true) return false;
+    // owner decision (11-07): web and desktop upload at the lower trust tier (`capped`, attested=false);
+    // an absent upload_trust entry means that tier; `off` or `attested` (which they cannot meet) mean no
+    const trust = (f.upload_trust && f.upload_trust[this.platform]) || 'capped';
+    return trust === 'capped';
+  }
+}

package/web/platform/contributor-key.js

@@ -0,0 +1,112 @@
+// The learner's sharing key: a per-contributor P-256 key pair made with WebCrypto as
+// NON-EXTRACTABLE (the private half can sign but can never be read by script, including the app's),
+// stored in IndexedDB (CryptoKey objects are structured-cloneable), bound to the contributor id on the
+// first upload. Deletion of what the learner shared is a challenge-response signed with it.
+//
+// The app gets: the public key (to send on the first upload), sign(bytes) for the SDK's own deletion
+// request, and nothing else. There is no export of the private key and no call that deletes for anyone
+// but this install's contributor.
+
+const DB = 'quranlab-sharing-keys-v1';
+const ALG = { name: 'ECDSA', namedCurve: 'P-256' };
+const SIGN = { name: 'ECDSA', hash: 'SHA-256' };
+
+function idb() {
+  if (!globalThis.indexedDB) return null;
+  return new Promise((res, rej) => {
+    const q = globalThis.indexedDB.open(DB, 1);
+    q.onupgradeneeded = () => q.result.createObjectStore('keys');
+    q.onsuccess = () => res(q.result);
+    q.onerror = () => rej(q.error);
+  });
+}
+async function idbOp(mode, fn) {
+  const d = await idb();
+  if (!d) return undefined;
+  return new Promise((res, rej) => {
+    const t = d.transaction('keys', mode);
+    const r = fn(t.objectStore('keys'));
+    t.oncomplete = () => res(r && 'result' in r ? r.result : undefined);
+    t.onerror = () => rej(t.error);
+  });
+}
+
+/** In-memory fallback (Node, or no IndexedDB): the key lives as long as the process. */
+const memory = new Map();
+
+/**
+ * The key pair of a contributor id, created on first use. Returns { contributor, publicKeyRaw
+ * (65-byte uncompressed P-256 point), publicKeySpki (DER), sign(bytes) -> 64-byte r||s }.
+ */
+export async function contributorKey(contributor, { create = true } = {}) {
+  let pair = memory.get(contributor) || (await idbOp('readonly', (s) => s.get(contributor)).catch(() => undefined));
+  if (!pair) {
+    if (!create) return null;
+    pair = await globalThis.crypto.subtle.generateKey(ALG, false, ['sign', 'verify']);
+    memory.set(contributor, pair);
+    await idbOp('readwrite', (s) => s.put(pair, contributor)).catch(() => {});
+  }
+  const subtle = globalThis.crypto.subtle;
+  const raw = new Uint8Array(await subtle.exportKey('raw', pair.publicKey));
+  const spki = new Uint8Array(await subtle.exportKey('spki', pair.publicKey));
+  return {
+    contributor,
+    extractable: pair.privateKey.extractable, // always false
+    publicKeyRaw: raw,
+    publicKeySpki: spki,
+    async sign(bytes) { return new Uint8Array(await subtle.sign(SIGN, pair.privateKey, bytes)); },
+  };
+}
+
+/** Forget a contributor's key (after a deletion, or when sharing is turned off for good). */
+export async function forgetContributorKey(contributor) {
+  memory.delete(contributor);
+  await idbOp('readwrite', (s) => s.delete(contributor)).catch(() => {});
+}
+
+// ---- the recovery code (PLATFORM_CLIENT.md section 9.1) ----
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+
+/** 16 bytes as 26 Crockford base32 characters, most significant bit first (the last character carries
+ * 3 bits and two zero bits), shown in groups of 4 separated by "-". */
+export function recoveryCodeFromBytes(bytes) {
+  if (bytes.length !== 16) throw new RangeError('a recovery code is 16 bytes');
+  let bits = 0, acc = 0, out = '';
+  for (const b of bytes) {
+    acc = (acc << 8) | b; bits += 8;
+    while (bits >= 5) { bits -= 5; out += CROCKFORD[(acc >> bits) & 31]; }
+    acc &= (1 << bits) - 1;
+  }
+  if (bits) out += CROCKFORD[(acc << (5 - bits)) & 31];
+  return out.match(/.{1,4}/g).join('-');
+}
+
+/** The normalised form the hash is taken of: upper case, spaces and "-" removed, O as 0, I and L as 1. */
+export function normaliseRecoveryCode(code) {
+  return String(code).toUpperCase().replace(/[\s-]/g, '').replace(/O/g, '0').replace(/[IL]/g, '1');
+}
+
+/** recovery_hash: lower-case hex SHA-256 of the normalised code. */
+export async function recoveryHash(code) {
+  const d = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(normaliseRecoveryCode(code)));
+  return Array.from(new Uint8Array(d), (x) => x.toString(16).padStart(2, '0')).join('');
+}
+
+/** A fresh recovery code (16 random bytes). */
+export function newRecoveryCode() {
+  const b = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(b);
+  return recoveryCodeFromBytes(b);
+}
+
+/** The exact bytes a deletion signs (LF line ends, final LF). */
+export function deletionMessage({ app, contributor, nonce, timestamp }) {
+  return new TextEncoder().encode(`quranlab-contribution-delete 1\napp ${app}\ncontributor ${contributor}\nnonce ${nonce}\ntimestamp ${timestamp}\naction delete-all\n`);
+}
+
+/** base64url without padding. */
+export function b64url(bytes) {
+  let s = '';
+  for (const x of bytes) s += String.fromCharCode(x);
+  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}

package/web/platform/index.d.ts

@@ -0,0 +1,114 @@
+// Types for @quran-lab/tajweedformer/platform: the Quran Lab platform client.
+
+export declare const SDK_VERSION: '2.0.0';
+export declare const API_URL: string;
+export declare const CDN_URL: string;
+
+/** Persistence for small JSON state. */
+export interface StateStore { kind: string; get(key: string): any; set(key: string, value: unknown): void }
+export declare function memoryState(): StateStore;
+/** localStorage (per origin), falling back to memory. */
+export declare function localState(prefix?: string): StateStore;
+/** Node: a directory of JSON files (0600). */
+export declare function dirState(dir: string): Promise<StateStore>;
+
+export declare class PlatformError extends Error { readonly status: number; readonly code: string }
+
+export interface SignedConfig {
+  v: 1; app: string; channel: string; issued_at: number; expires_at: number;
+  models: Record<string, { revision: string; source: string; model_id?: string; folder?: string }>;
+  recommended: { model: string; model_id: string; folder: string; revision: string; source: string } | null;
+  denylist: Record<string, string>[];
+  flags: { analytics?: boolean; issues?: boolean; contributions?: boolean; upload_trust?: Record<string, 'off' | 'capped' | 'attested'>; [k: string]: unknown };
+  tajweed?: unknown;
+  /** where model files are served (qlab-api signs it): {base}/{model}/{revision}/{folder}/ */
+  base?: string;
+}
+
+export interface QuranLabOptions {
+  /** the developer key qlk_v1_... (a web key in browsers, origin-locked; a desktop key from Node) */
+  key: string;
+  appVersion?: string;
+  appName?: string;
+  /** 'web' in browsers; in Node 'web' (with origin), 'linux' or 'windows' */
+  platform?: 'web' | 'linux' | 'windows';
+  /** web: the page's origin (default location.origin); desktop: the reverse-DNS or package id */
+  bundleId?: string;
+  /** Node with a web key: the Origin header to send */
+  origin?: string;
+  /** telemetry: on by default, anonymous; 'off' is the one developer opt-out (never a prompt) */
+  analytics?: 'on' | 'off';
+  issues?: boolean;
+  /** recitation sharing (the SDK asks the learner first; see @quran-lab/tajweedformer/consent) */
+  contributions?: boolean;
+  audience?: 'general' | 'children';
+  state?: StateStore;
+  /** pinned Ed25519 config keys (default: Quran Lab's) */
+  trustedKeys?: (string | Uint8Array)[];
+  apiUrl?: string;
+  /** model files: default the signed config's base, else https://cdn.quranlab.ai/models */
+  modelsUrl?: string;
+  /** given alone (no modelsUrl): model files from the old {cdnUrl}/hf/ path */
+  cdnUrl?: string;
+  fetch?: typeof fetch;
+  clock?: () => number;
+}
+
+export declare class QuranLab {
+  constructor(o: QuranLabOptions);
+  /** configure and run the launch sequence (token, register, config, pending telemetry and issues);
+   * never throws for network trouble */
+  static configure(o: QuranLabOptions): Promise<QuranLab>;
+  readonly config: SignedConfig | null;
+  readonly flags: SignedConfig['flags'];
+  /** the error-table code that stopped the network for this launch, or null */
+  readonly stopped: string | null;
+  readonly lastError?: Error;
+  readonly telemetry: Telemetry;
+  token(): Promise<string>;
+  launch(): Promise<void>;
+  register(): Promise<{ ok: boolean; app_id: string; store_status: string }>;
+  refreshConfig(): Promise<SignedConfig | null>;
+  /** refresh every ms (60 s) while the app is in use */
+  startRefresh(ms?: number): void;
+  stopRefresh(): void;
+  modelSource(): Promise<{ url: string; headers: Record<string, string> }>;
+  flush(): Promise<number>;
+  reportIssue(kind: string, code: string, frames?: string[]): boolean;
+  contributor(): string;
+  resetContributor(): void;
+  contributionSummary(): Promise<{ you: { sessions: number; minutes: number }; app: { contributors: number; minutes: number } | null;
+    all: { contributors: number; minutes: number } } | null>;
+  sharingAllowed(): boolean;
+}
+
+export declare function verifySignedConfig(body: Uint8Array, signatureHeader: string | null, keyId: string | null,
+  trustedKeys: (string | Uint8Array)[], now?: number): Promise<SignedConfig>;
+export declare function keyId(rawPublicKey: string | Uint8Array): Promise<string>;
+
+export declare class Telemetry {
+  enabled: boolean;
+  /** completed days as wire payloads (v2) */
+  pending(): object[];
+  clear(): void;
+}
+export declare function bucket(kind: string, value: number): string;
+export declare function utcDay(t?: number): string;
+export declare function deviceInfo(): { class: string; soc?: string; os_major: number; ram_tier?: string };
+
+export interface ContributorKey {
+  contributor: string;
+  /** always false: the private half never leaves WebCrypto */
+  extractable: false;
+  publicKeyRaw: Uint8Array;
+  publicKeySpki: Uint8Array;
+  sign(bytes: Uint8Array): Promise<Uint8Array>;
+}
+export declare function contributorKey(contributor: string, opts?: { create?: boolean }): Promise<ContributorKey | null>;
+export declare function forgetContributorKey(contributor: string): Promise<void>;
+export declare function recoveryCodeFromBytes(bytes: Uint8Array): string;
+export declare function normaliseRecoveryCode(code: string): string;
+export declare function recoveryHash(code: string): Promise<string>;
+export declare function newRecoveryCode(): string;
+export declare function deletionMessage(m: { app: string; contributor: string; nonce: string; timestamp: number }): Uint8Array;
+export declare function b64url(bytes: Uint8Array): string;

package/web/platform/index.js

@@ -0,0 +1,7 @@
+// @quran-lab/tajweedformer/platform: the Quran Lab platform client:
+// key, token, register, the signed config, telemetry v2 (on by default, anonymous), issues.
+//   import { QuranLab } from '@quran-lab/tajweedformer/platform';
+export { QuranLab, PlatformError, verifySignedConfig, keyId, SDK_VERSION, API_URL, CDN_URL } from './client.js';
+export { Telemetry, bucket, utcDay, deviceInfo } from './telemetry.js';
+export { memoryState, localState, dirState } from './storage.js';
+export { contributorKey, forgetContributorKey, recoveryCodeFromBytes, normaliseRecoveryCode, recoveryHash, newRecoveryCode, deletionMessage, b64url } from './contributor-key.js';

package/web/platform/storage.js

@@ -0,0 +1,50 @@
+// Small persistent state for the platform client (tokens, the signed config, telemetry days, the
+// sharing state, the bucket, the first-launch flag): JSON values by key.
+//   browsers: localStorage (per origin), wrapped in try/catch (private modes can throw)
+//   Node:     a JSON file per key in a directory (nodeStateStore in ../tajweed/node.js style, here)
+//   tests:    memoryState()
+
+/** In memory. */
+export function memoryState() {
+  const m = new Map();
+  return {
+    kind: 'memory',
+    get(k) { return m.has(k) ? JSON.parse(m.get(k)) : null; },
+    set(k, v) { if (v === null || v === undefined) m.delete(k); else m.set(k, JSON.stringify(v)); },
+  };
+}
+
+/** localStorage, prefixed "quranlab.". Falls back to memory when storage throws. */
+export function localState(prefix = 'quranlab.') {
+  const mem = memoryState();
+  const ls = (() => { try { return globalThis.localStorage || null; } catch (_) { return null; } })();
+  return {
+    kind: ls ? 'localStorage' : 'memory',
+    get(k) {
+      try { const v = ls ? ls.getItem(prefix + k) : null; return v === null ? mem.get(k) : JSON.parse(v); } catch (_) { return mem.get(k); }
+    },
+    set(k, v) {
+      mem.set(k, v);
+      try { if (ls) { if (v === null || v === undefined) ls.removeItem(prefix + k); else ls.setItem(prefix + k, JSON.stringify(v)); } } catch (_) { /* kept in memory */ }
+    },
+  };
+}
+
+/** A directory of JSON files (Node). Synchronous on purpose: tiny files, called rarely. */
+export async function dirState(dir) {
+  const fs = await import('node:fs');
+  const path = await import('node:path');
+  fs.mkdirSync(dir, { recursive: true });
+  const file = (k) => path.join(dir, encodeURIComponent(k) + '.json');
+  return {
+    kind: 'directory',
+    get(k) { try { return JSON.parse(fs.readFileSync(file(k), 'utf8')); } catch (_) { return null; } },
+    set(k, v) {
+      const f = file(k);
+      if (v === null || v === undefined) { fs.rmSync(f, { force: true }); return; }
+      const tmp = `${f}.${process.pid}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(v), { mode: 0o600 });
+      fs.renameSync(tmp, f);
+    },
+  };
+}