@digital-ai/dot-illustrations 2.0.43 → 2.0.46

package/.github/workflows/publish.yml

@@ -91,7 +91,7 @@ jobs:
           registry-url: 'https://registry.npmjs.org'
 
       - name: Update npm (≥ 11.5.1 required for OIDC)
-        run: npm install -g npm@latest
+        run: npm install -g npm@11
 
       - name: Publish to npm
         run: npm publish --access public

package/README.md

@@ -106,7 +106,11 @@ The demo includes a built-in upload flow that handles everything automatically.
 
 #### Prerequisites
 
-Run the local proxy once so the demo can authenticate as you without entering a token:
+**On the hosted demo** (`digital-ai.github.io/dot-illustrations/demo/`): nothing to run yourself — click **Connect GitHub** and follow the device-code prompt. This works because a maintainer has deployed the `demo/oauth-proxy/` Worker + registered a GitHub OAuth App (one-time setup, see [`demo/oauth-proxy/`](demo/oauth-proxy/)). GitHub's device-flow endpoints don't support CORS, so the browser can't call them directly — the Worker forwards those two calls server-to-server. It holds no secrets; Device Flow for public OAuth Apps only needs the Client ID.
+
+If that isn't configured yet, **Connect GitHub** falls back to a manual Personal Access Token paste-in (scope: `public_repo`).
+
+**Running locally instead:** run the local proxy once so the demo can authenticate as you without entering a token:
 
 ```bash
 # From the repo root (requires gh CLI authenticated: gh auth login)
@@ -123,19 +127,19 @@ node demo/local-proxy.js
 - Enter the **Illustration ID** (lowercase, hyphens only — e.g. `my-new-state`)
 - Select the **Category**: Global or Dashboards
 - Upload the **Light SVG** (☀️) and **Dark SVG** (🌙) — both are required
-- Click **Connect GitHub** then **Create Pull Request**
+- Click **Connect GitHub** (device-code prompt on the hosted demo, local `gh auth` session with the local proxy running, or PAT paste-in fallback) then **Create Pull Request**
 
 **Integration logo**
 - Enter the **Integration ID** (lowercase, hyphens — e.g. `my-tool`)
 - Upload the single **SVG** file (no dark variant needed)
-- Click **Connect GitHub** then **Create Pull Request**
+- Click **Connect GitHub** (device-code prompt on the hosted demo, local `gh auth` session with the local proxy running, or PAT paste-in fallback) then **Create Pull Request**
 
 The PR is created automatically with:
 - SVG file(s) committed to the correct folder
 - CSS rule added to `index.css`
 - ID added to `demo/script.js` in alphabetical order
 
-> The local proxy uses your existing `gh auth` credentials — no token input required.
+> The local proxy uses your existing `gh auth` credentials — no token input required. The hosted demo's Connect GitHub button uses the device-flow proxy instead (see Prerequisites above); if it's not yet configured, it falls back to PAT paste-in.
 
 ---
 

package/demo/device-flow-poll.test.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * Regression test for the device-flow login polling in github-upload.js.
+ *
+ * Guards the fix from #90: ghPollForToken must honor GitHub's `slow_down`
+ * backoff and must not fire a burst of sub-interval polls when the tab is
+ * refocused after the user authorises — otherwise the connect modal stalls
+ * forever on the code screen. Ported from digital-ai/dot-icons, which hit
+ * and fixed the same bug in the same demo pattern (icons #85, #86).
+ *
+ * It runs the ACTUAL ghPollForToken extracted from github-upload.js (not a
+ * copy) against a mocked fetch/document/window, replaying the real failure
+ * scenario: a focus + visibilitychange refocus burst, a `slow_down` from
+ * GitHub, then the token. Zero dependencies — plain Node.
+ *
+ * Run:  node demo/device-flow-poll.test.js   (or: npm test)
+ */
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+// ── Extract ghPollForToken from the source by brace-matching ────────────────
+const src   = fs.readFileSync(path.join(__dirname, 'github-upload.js'), 'utf8');
+const anchor = src.indexOf('function ghPollForToken');
+if (anchor === -1) fail('ghPollForToken not found in github-upload.js');
+let depth = 0, end = -1, started = false;
+for (let i = anchor; i < src.length; i++) {
+  const c = src[i];
+  if (c === '{') { depth++; started = true; }
+  else if (c === '}') { depth--; if (started && depth === 0) { end = i + 1; break; } }
+}
+if (end === -1) fail('could not brace-match ghPollForToken body');
+const fnText = src.slice(anchor, end);
+
+// ── Browser stubs ───────────────────────────────────────────────────────────
+const listeners = { visibilitychange: [], focus: [] };
+const document = {
+  visibilityState: 'visible',
+  addEventListener: (e, cb) => listeners[e] && listeners[e].push(cb),
+  removeEventListener: (e, cb) => { if (listeners[e]) listeners[e] = listeners[e].filter(f => f !== cb); },
+};
+const window = {
+  addEventListener: (e, cb) => listeners[e] && listeners[e].push(cb),
+  removeEventListener: (e, cb) => { if (listeners[e]) listeners[e] = listeners[e].filter(f => f !== cb); },
+};
+
+// Scripted GitHub responses, one per /access_token poll.
+const RESPONSES = [
+  { error: 'authorization_pending' },
+  { error: 'slow_down', interval: 10 }, // GitHub raises the required interval to 10s
+  { access_token: 'gho_REGRESSION_TEST_TOKEN' },
+];
+const pollTimes = [];
+let step = 0;
+const t0 = Date.now();
+global.fetch = async () => {
+  pollTimes.push(Date.now() - t0);
+  const body = RESPONSES[Math.min(step, RESPONSES.length - 1)];
+  step++;
+  return { ok: true, status: 200, json: async () => body };
+};
+
+const GITHUB_UPLOAD_CONFIG = { OAUTH_PROXY_URL: 'https://proxy.test', CLIENT_ID: 'test' };
+
+let ghPollForToken;
+eval(`ghPollForToken = ${fnText}`);
+
+// ── Run the scenario ────────────────────────────────────────────────────────
+function fail(msg) { console.error(`\nFAIL ❌ — ${msg}`); process.exit(1); }
+
+(async () => {
+  const promise = ghPollForToken('device-code', 5, 899);
+
+  // Refocus burst shortly after start: both events fire in the same tick.
+  // The fixed code must throttle these to the current interval.
+  setTimeout(() => {
+    listeners.visibilitychange.forEach(cb => cb());
+    listeners.focus.forEach(cb => cb());
+  }, 1200);
+
+  let token;
+  try {
+    token = await promise;
+  } catch (e) {
+    fail(`polling rejected unexpectedly: ${e.message}`);
+  }
+
+  const gaps = pollTimes.slice(1).map((t, i) => t - pollTimes[i]);
+
+  if (token !== 'gho_REGRESSION_TEST_TOKEN')
+    fail(`expected the token to resolve, got: ${token}`);
+  if (pollTimes.length < 3)
+    fail(`expected at least 3 polls (pending, slow_down, token), got ${pollTimes.length}`);
+  // No self-inflicted burst: no two polls closer than ~the 5s interval, even
+  // though a focus+visibilitychange pair fired mid-flight.
+  const MIN_GAP = 4800;
+  const burst = gaps.find(g => g < MIN_GAP);
+  if (burst !== undefined)
+    fail(`polls fired ${Math.round(burst)}ms apart (< ${MIN_GAP}ms) — refocus burst not throttled`);
+  // Backoff: the interval must widen after slow_down (10s gap > the initial 5s).
+  if (!(gaps[1] > gaps[0] + 3000))
+    fail(`interval did not widen after slow_down (gaps ${gaps.map(Math.round)})`);
+
+  console.log('device-flow polling regression test');
+  console.log(`  poll times (ms): ${pollTimes.map(Math.round).join(', ')}`);
+  console.log(`  gaps (ms):       ${gaps.map(Math.round).join(', ')}`);
+  console.log('\nPASS ✅ — token resolved, no sub-interval burst, slow_down widened the interval');
+  process.exit(0);
+})();

package/demo/github-upload.js

@@ -6,11 +6,18 @@
  * 1. Register a GitHub OAuth App at https://github.com/settings/developers
  *    - Homepage: https://digital-ai.github.io/dot-illustrations/demo/
  *    - Check "Enable Device Flow" — no callback URL needed
- * 2. Set GITHUB_OAUTH_CLIENT_ID to your Client ID
+ * 2. Replace CLIENT_ID below with your app's Client ID
+ * 3. The Client ID is public-safe — only the Client Secret must stay private,
+ *    and Device Flow never requires the secret in the browser.
+ * 4. Deploy demo/oauth-proxy/ (Cloudflare Worker) — GitHub's device-flow
+ *    endpoints don't support CORS, so the browser can't call them directly;
+ *    the Worker forwards those two calls server-to-server. Holds no secrets.
+ * 5. Replace OAUTH_PROXY_URL below with the deployed Worker's *.workers.dev URL.
  */
 
 const GITHUB_UPLOAD_CONFIG = {
-  CLIENT_ID: 'YOUR_GITHUB_OAUTH_CLIENT_ID',
+  CLIENT_ID: 'Ov23liJSaMsvgE5Q51cI',
+  OAUTH_PROXY_URL: 'https://dot-illustrations-oauth-proxy.dot-icons.workers.dev',
   REPO_OWNER: 'digital-ai',
   REPO_NAME: 'dot-illustrations',
   BASE_BRANCH: 'main',
@@ -132,12 +139,20 @@ async function ghCreatePR(head, title, body) {
 }
 
 // ─── Device Flow ─────────────────────────────────────────────────────────────
+// Both calls go through demo/oauth-proxy/ (Cloudflare Worker) — GitHub's
+// device-flow endpoints don't support CORS, so the browser can't call
+// github.com directly.
 
 async function ghStartDeviceFlow() {
-  if (!GITHUB_UPLOAD_CONFIG.CLIENT_ID || GITHUB_UPLOAD_CONFIG.CLIENT_ID === 'YOUR_GITHUB_OAUTH_CLIENT_ID') {
+  if (
+    !GITHUB_UPLOAD_CONFIG.CLIENT_ID ||
+    GITHUB_UPLOAD_CONFIG.CLIENT_ID === 'YOUR_GITHUB_OAUTH_CLIENT_ID' ||
+    !GITHUB_UPLOAD_CONFIG.OAUTH_PROXY_URL ||
+    GITHUB_UPLOAD_CONFIG.OAUTH_PROXY_URL === 'YOUR_OAUTH_PROXY_WORKERS_DEV_URL'
+  ) {
     throw new Error('NO_CLIENT_ID');
   }
-  const resp = await fetch('https://github.com/login/device/code', {
+  const resp = await fetch(`${GITHUB_UPLOAD_CONFIG.OAUTH_PROXY_URL}/device/code`, {
     method: 'POST',
     headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' },
     body: JSON.stringify({ client_id: GITHUB_UPLOAD_CONFIG.CLIENT_ID, scope: GITHUB_UPLOAD_CONFIG.SCOPES }),
@@ -146,11 +161,64 @@ async function ghStartDeviceFlow() {
   return resp.json();
 }
 
-function ghPollForToken(deviceCode, intervalSec) {
+/**
+ * Poll GitHub (via the oauth-proxy Worker) until the user authorises (or times out).
+ * Resolves with the access_token string.
+ *
+ * The intended UX is to approve the code on another tab/device while this tab
+ * waits — which backgrounds this tab, and browsers throttle setInterval in
+ * background tabs (down to ~once/minute or slower). The token is usually ready
+ * within seconds of approval, so also poll immediately on `visibilitychange`
+ * and `focus` to catch up as soon as the user switches back, instead of
+ * waiting on the throttled timer.
+ *
+ * A single failed poll (transient network blip, a fetch aborted because the
+ * tab was backgrounded, etc.) must not kill the whole flow — it just retries
+ * on the next tick. GitHub's own `expired_token` response is the normal stop
+ * condition, but if the proxy itself is unreachable we'd never get that
+ * response from GitHub at all — so `expiresInSec` also bounds retries
+ * client-side to the code's real lifetime, instead of polling forever.
+ *
+ * GitHub's device-flow spec mandates a client-side backoff: when the token
+ * endpoint answers `slow_down`, the client MUST raise its polling interval
+ * (GitHub returns the new minimum in the response, otherwise add 5s) and use
+ * the larger value from then on. Polling faster than the current interval
+ * just gets `slow_down` again — so a client that ignores it never receives
+ * the token and the flow stalls on the code screen even after the user has
+ * authorised. The `focus`/`visibilitychange` wake-ups (which catch up the
+ * throttled background timer as soon as the user switches back) are exactly
+ * what would otherwise fire a burst of sub-interval polls and trip
+ * `slow_down` in the first place, so they are throttled to the current
+ * interval too, and only ever one poll is in flight at a time.
+ */
+function ghPollForToken(deviceCode, intervalSec, expiresInSec) {
   return new Promise((resolve, reject) => {
-    const timer = setInterval(async () => {
+    let settled    = false;
+    let inFlight   = false;
+    let intervalMs = Math.max(intervalSec || 5, 5) * 1000;
+    let lastPollAt = 0;
+    let timer      = null;
+    const deadline = Date.now() + (expiresInSec || 900) * 1000;
+
+    // (Re)arm the next poll `delay` ms from now (clamped to ≥0, so an
+    // already-due wake-up polls immediately). Always supersedes any pending
+    // timer so the interval can grow after a `slow_down`.
+    function schedule(delay) {
+      if (settled) return;
+      clearTimeout(timer);
+      timer = setTimeout(poll, Math.max(delay, 0));
+    }
+
+    async function poll() {
+      if (settled || inFlight) return;
+      if (Date.now() > deadline) {
+        settle(() => reject(new Error('Device code expired — please try again.')));
+        return;
+      }
+      inFlight   = true;
+      lastPollAt = Date.now();
       try {
-        const resp = await fetch('https://github.com/login/oauth/access_token', {
+        const resp = await fetch(`${GITHUB_UPLOAD_CONFIG.OAUTH_PROXY_URL}/access_token`, {
           method: 'POST',
           headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' },
           body: JSON.stringify({
@@ -159,13 +227,52 @@ function ghPollForToken(deviceCode, intervalSec) {
             grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
           }),
         });
-        const d = await resp.json();
-        if (d.access_token) { clearInterval(timer); resolve(d.access_token); }
-        else if (d.error === 'expired_token' || d.error === 'access_denied') {
-          clearInterval(timer); reject(new Error(d.error_description || d.error));
+        const data = await resp.json();
+        if (settled) return;
+        if (data.access_token) {
+          settle(() => resolve(data.access_token));
+          return;
+        }
+        if (data.error === 'expired_token' || data.error === 'access_denied') {
+          settle(() => reject(new Error(data.error_description || data.error)));
+          return;
         }
-      } catch (e) { clearInterval(timer); reject(e); }
-    }, Math.max(intervalSec, 5) * 1000);
+        if (data.error === 'slow_down') {
+          // Honor GitHub's backoff: use the interval it hands back, else +5s.
+          intervalMs = Math.max(data.interval ? data.interval * 1000 : intervalMs + 5000,
+                                intervalMs + 5000);
+        }
+        // 'authorization_pending' or 'slow_down' — keep polling on the interval
+      } catch (err) {
+        // Transient failure (network blip, backgrounded-tab fetch abort) —
+        // keep polling rather than killing the whole flow.
+        console.warn('Device-flow poll failed, retrying:', err);
+      } finally {
+        inFlight = false;
+      }
+      schedule(intervalMs);
+    }
+
+    function settle(fn) {
+      settled = true;
+      clearTimeout(timer);
+      document.removeEventListener('visibilitychange', onVisible);
+      window.removeEventListener('focus', onVisible);
+      fn();
+    }
+
+    // Wake up as soon as the user switches back to this tab, but never poll
+    // sooner than the current interval since the last poll — otherwise the
+    // focus + visibilitychange pair fires two sub-interval polls and trips
+    // GitHub's `slow_down`. If a poll is already due, this fires ~immediately.
+    function onVisible() {
+      if (settled || document.visibilityState !== 'visible') return;
+      schedule(intervalMs - (Date.now() - lastPollAt));
+    }
+
+    document.addEventListener('visibilitychange', onVisible);
+    window.addEventListener('focus', onVisible);
+    poll(); // first poll now; it self-schedules the rest
   });
 }
 

package/demo/oauth-proxy/README.md

@@ -0,0 +1,23 @@
+# OAuth device-flow proxy
+
+Stateless Cloudflare Worker that forwards `POST /device/code` and `POST /access_token`
+to GitHub's device-flow endpoints. Exists only because those endpoints don't support
+CORS, so a static page can't call them directly from the browser. Holds no secrets —
+device flow for public GitHub OAuth Apps only needs the Client ID, which the browser
+already sends.
+
+## Deploy (one-time, per maintainer/environment)
+
+```bash
+cd demo/oauth-proxy
+npx wrangler login
+npx wrangler deploy
+```
+
+This prints a `*.workers.dev` URL. Then:
+
+1. Put that URL into `OAUTH_PROXY_URL` in [`demo/github-upload.js`](../github-upload.js)
+2. Put your GitHub OAuth App's Client ID into `CLIENT_ID` in the same file (see the
+   file's header comment for how to register the OAuth App)
+3. If the demo isn't served from `https://digital-ai.github.io`, update
+   `ALLOWED_ORIGIN` in [`wrangler.toml`](./wrangler.toml) to match

package/demo/oauth-proxy/worker.js

@@ -0,0 +1,62 @@
+/**
+ * OAuth device-flow proxy — Cloudflare Worker
+ *
+ * GitHub's device-flow endpoints (github.com/login/device/code and
+ * github.com/login/oauth/access_token) don't support CORS, so a static
+ * page can't call them directly from browser JS. This Worker forwards
+ * those two calls server-to-server, so the browser only ever talks to
+ * this Worker (which does send CORS headers).
+ *
+ * Holds no secrets: GitHub's device flow for public OAuth Apps only
+ * needs client_id (sent by the browser), never a client secret.
+ *
+ * Deploy: from this directory, `npx wrangler login && npx wrangler deploy`.
+ * Then set ALLOWED_ORIGIN below (or via `wrangler.toml` [vars]) and put the
+ * resulting *.workers.dev URL into demo/github-upload.js's OAUTH_PROXY_URL.
+ */
+
+const GITHUB_ENDPOINTS = {
+  '/device/code':   'https://github.com/login/device/code',
+  '/access_token':  'https://github.com/login/oauth/access_token',
+};
+
+export default {
+  async fetch(request, env) {
+    const allowedOrigin = env.ALLOWED_ORIGIN || 'https://digital-ai.github.io';
+    const corsHeaders = {
+      'Access-Control-Allow-Origin':  allowedOrigin,
+      'Access-Control-Allow-Methods': 'POST, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type',
+    };
+
+    if (request.method === 'OPTIONS') {
+      return new Response(null, { headers: corsHeaders });
+    }
+
+    const url    = new URL(request.url);
+    const target = GITHUB_ENDPOINTS[url.pathname];
+
+    if (!target || request.method !== 'POST') {
+      return new Response(JSON.stringify({ error: 'Not found' }), {
+        status: 404,
+        headers: { 'Content-Type': 'application/json', ...corsHeaders },
+      });
+    }
+
+    const body = await request.text();
+    const upstream = await fetch(target, {
+      method: 'POST',
+      headers: {
+        'Accept':       'application/json',
+        'Content-Type': 'application/json',
+      },
+      body,
+    });
+
+    const data = await upstream.text();
+    return new Response(data, {
+      status: upstream.status,
+      headers: { 'Content-Type': 'application/json', ...corsHeaders },
+    });
+  },
+};

package/demo/oauth-proxy/wrangler.toml

@@ -0,0 +1,6 @@
+name = "dot-illustrations-oauth-proxy"
+main = "worker.js"
+compatibility_date = "2026-01-01"
+
+[vars]
+ALLOWED_ORIGIN = "https://digital-ai.github.io"

package/demo/script.js

@@ -632,7 +632,7 @@ document.addEventListener('DOMContentLoaded', () => {
       document.getElementById('gh-device-code').textContent = user_code;
       document.getElementById('gh-copy-code-btn').onclick = () =>
         navigator.clipboard.writeText(user_code).then(() => showToast('Code copied!'));
-      const token = await window.GitHubUpload.pollForToken(device_code, interval || 5);
+      const token = await window.GitHubUpload.pollForToken(device_code, interval || 5, expires_in);
       window.GitHubUpload.setToken(token);
       const user = await window.GitHubUpload.getUser();
       updateAuthBadge(user);

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@digital-ai/dot-illustrations",
-  "version": "2.0.43",
+  "version": "2.0.46",
   "description": "A central place for the design team to keep illustrations and for dev teams to find them.",
   "main": "./index.css",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node demo/device-flow-poll.test.js"
   },
   "repository": {
     "type": "git",