@threadcrumbs/common 0.1.9 → 0.1.10

package/README.md

@@ -18,7 +18,7 @@ need it.
 | `@threadcrumbs/common/orgs` | Which organization each repo belongs to, so the apps can group repos the same way. `organizationReader()` returns `withOrganizations(threads)`, which tags each thread with `org` by its `projectPath` and reads each folder at most once a minute. `signalsOf(dir)` reads one folder's package name and git origin owner, and `organizationsFor(signals)` combines them. The rules are in [DECISIONS.md](DECISIONS.md#a-repos-organization-comes-from-its-package-name). Node only, and it only reads |
 | `@threadcrumbs/common/launch` | `present(result, via)`: carries out a harness adapter's answer to "open this thread" by fronting the window of a session already running, handing a deep link to the OS, or running the harness's CLI in a new terminal. When nothing on the machine answers the link, it tries the adapter's `fallback` links, such as Claude Code's thread in VS Code, and failing those returns `{ ok: false, error, missing: { name, download, scheme, also }, terminal }`: the app to install, where to get it, other apps that would do, and whether `via: 'terminal'` would work instead. Also `launch(target)` and `resolveFolder(dir)`. Threadgauge uses it, and Threadnauts still has its own copy |
 | `@threadcrumbs/common/license` | The Threadcrumbs license both apps check offline and the key service signs: `createLicenseKeys`, `publicKeyOf`, `licenseClaims`, `signLicense`, `verifyLicense`, and the unlock rule, `paidThrough` and `unlocks`, plus `renewalDue`. Web APIs only, so the same file runs in a Cloudflare Worker. The format and rules are in [DECISIONS.md](DECISIONS.md#licenses-are-signed-by-threadcrumbs-and-checked-offline). `LICENSE_PUBLIC_KEYS` holds the production keys every app trusts, and never a sandbox key |
-| `@threadcrumbs/common/license/store` | Where the license lives on this machine, shared by every app: `licenseStore()` returns `device()`, `current()`, `save(token)`, and `clear()`, over `license.json` in `threadcrumbsDataDir()`. `current().at` is the time to test unlocks at, and `current()` writes nothing on a machine where no one has entered a key. `trustedKeys({ development })` adds a sandbox key in a development build, and `cloudUrl({ development })` is the key service's address: `https://threadcrumbs.io/api`, or the local Worker at `http://localhost:8787/api` in a development build. Node only, so the Worker never loads it |
+| `@threadcrumbs/common/license/store` | Where the license lives on this machine, shared by every app: `licenseStore()` returns `device()`, `current()`, `save(token)`, and `clear()`, over `license.json` in `threadcrumbsDataDir()`. `current().at` is the time to test unlocks at, and `current()` writes nothing on a machine where no one has entered a key. `trustedKeys({ development })` adds a sandbox key in a development build, and `cloudUrl({ development })` is the key service's address: `https://threadcrumbs.io/api`, or the local Worker at `http://localhost:8787/api` in a development build. `portalUrl({ license, device, fetch, cloud })` asks the key service for Polar's customer portal, signed in, where a subscriber changes plan; it resolves to `{ url }` or `{ error, why }`, with `why` ready to show ([DECISIONS.md](DECISIONS.md#changing-plan-happens-in-polars-portal-opened-with-the-license)). Node only, so the Worker never loads it |
 | `@threadcrumbs/common/ui/theme.css` | The Threadcrumbs look as CSS variables: the Quieter backgrounds, lines, and text levels, Threadcrumbs orange, the six status colors and their plates, `--warn`, added and removed, the chart and gauge colors, focus, type sizes, spacing, radii, and the default `--sans`, `--cond`, and `--mono` stacks. Every element keeps one x-height (`font-size-adjust: 0.51`) |
 | `@threadcrumbs/common/ui/fonts.css` | `@font-face` rules for Inter, Inter Tight, and JetBrains Mono, Latin and Latin Extended, upright, with their `.woff2` files in `ui/fonts/`. A bundler copies the files into the app, so they load from its own origin. `tools/ui-fonts.mjs` writes both from the `@fontsource` packages |
 | `@threadcrumbs/common/ui/status` | `STATUSES` (each status's key, name, color, and plate, in the order both apps pin), `STATUS_KEYS`, `URGENCY_ORDER` (for the status row and the waffle), `LIVE_STATUSES`, `statusOf`, the status icons as SVG in `LAMP_ICONS`, and `lampHTML(status)`. `ui/status.css` colors each `[data-st]` and animates the lamps, and reduced motion stops them |
@@ -140,7 +140,7 @@ give its sessions the same ids, which Threadgauge's Open depends on.
 or imports `launch/` or the license store. `test/launch.test.mjs` covers how `present()` refuses and names a missing app,
 starting nothing but a registry query on Windows. `test/license.test.mjs` covers signing and the unlock rule, and
 `test/license-store.test.mjs` covers the shared file, including two apps starting at once on a
-fresh machine and a clock set back.
+fresh machine and a clock set back, and `portalUrl()` against a fake key service.
 
 GitHub Actions runs the suite on Windows, macOS, and Linux for every push to `master` and every
 pull request (`.github/workflows/test.yml`). The tests that only run on one OS, like the real

package/license/store.mjs

@@ -1,155 +1,192 @@
-import { randomBytes } from 'node:crypto'
-import fsp from 'node:fs/promises'
-import os from 'node:os'
-import path from 'node:path'
-import { LICENSE_PUBLIC_KEYS, verifyLicense } from './index.mjs'
-
-const FILE = 'license.json'
-const DEVICE = /^[A-Za-z0-9_-]{8,100}$/
-const SEEN_STEP = 3600
-const READ_TRIES = 5
-const RENAME_TRIES = 10
-const PAUSE_MS = 20
-const CLOUD_URL = 'https://threadcrumbs.io/api'
-const LOCAL_CLOUD_URL = 'http://localhost:8787/api'
-
-const pause = () => new Promise((resolve) => setTimeout(resolve, PAUSE_MS))
-const isDevice = (value) => typeof value === 'string' && DEVICE.test(value)
-const finite = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0)
-
-export function threadcrumbsDataDir({ platform = process.platform, env = process.env, home = os.homedir() } = {}) {
-  if (env.THREADCRUMBS_DATA_DIR) return env.THREADCRUMBS_DATA_DIR
-  if (platform === 'win32') {
-    return path.win32.join(env.APPDATA || path.win32.join(home, 'AppData', 'Roaming'), 'Threadcrumbs')
-  }
-  if (platform === 'darwin') return path.posix.join(home, 'Library', 'Application Support', 'Threadcrumbs')
-  const xdg = env.XDG_DATA_HOME && path.posix.isAbsolute(env.XDG_DATA_HOME) ? env.XDG_DATA_HOME : ''
-  return path.posix.join(xdg || path.posix.join(home, '.local', 'share'), 'threadcrumbs')
-}
-
-export function trustedKeys({ env = process.env, development = false } = {}) {
-  const extra = development ? env.THREADCRUMBS_LICENSE_KEYS : ''
-  if (!extra) return { ...LICENSE_PUBLIC_KEYS }
-  let parsed
-  try {
-    parsed = JSON.parse(extra)
-  } catch {
-    throw new Error('THREADCRUMBS_LICENSE_KEYS must be JSON: { "<kid>": "<public key>" }')
-  }
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || !Object.values(parsed).every((k) => typeof k === 'string')) {
-    throw new Error('THREADCRUMBS_LICENSE_KEYS must map each key ID to a public key')
-  }
-  return { ...LICENSE_PUBLIC_KEYS, ...parsed }
-}
-
-export function cloudUrl({ env = process.env, development = false } = {}) {
-  return (env.THREADCRUMBS_CLOUD_URL || (development ? LOCAL_CLOUD_URL : CLOUD_URL)).replace(/\/+$/, '')
-}
-
-async function check(token, keys, device) {
-  try {
-    return await verifyLicense(token, { keys, device })
-  } catch {
-    return { ok: false, reason: 'malformed' }
-  }
-}
-
-export function licenseStore({ dir = threadcrumbsDataDir(), keys = LICENSE_PUBLIC_KEYS, now = () => Date.now() / 1000 } = {}) {
-  const file = path.join(dir, FILE)
-
-  async function read() {
-    let text
-    try {
-      text = await fsp.readFile(file, 'utf8')
-    } catch (err) {
-      if (err.code === 'ENOENT') return null
-      throw err
-    }
-    try {
-      const data = JSON.parse(text)
-      return data && typeof data === 'object' && !Array.isArray(data) ? data : {}
-    } catch {
-      return {}
-    }
-  }
-
-  const serialize = (data) => `${JSON.stringify(data, null, 2)}\n`
-
-  async function replace(data) {
-    await fsp.mkdir(dir, { recursive: true })
-    const temp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`
-    try {
-      await fsp.writeFile(temp, serialize(data), { mode: 0o600 })
-      for (let attempt = 1; ; attempt++) {
-        try {
-          return await fsp.rename(temp, file)
-        } catch (err) {
-          if (attempt >= RENAME_TRIES || !['EPERM', 'EACCES', 'EBUSY'].includes(err.code)) throw err
-          await pause()
-        }
-      }
-    } catch (err) {
-      await fsp.rm(temp, { force: true })
-      throw err
-    }
-  }
-
-  async function device() {
-    for (let attempt = 0; attempt < READ_TRIES; attempt++) {
-      const data = await read()
-      if (isDevice(data?.device)) return data.device
-      if (data === null) {
-        await fsp.mkdir(dir, { recursive: true })
-        try {
-          await fsp.writeFile(file, serialize({ device: randomBytes(18).toString('base64url'), license: null, seen: 0 }), { flag: 'wx', mode: 0o600 })
-        } catch (err) {
-          if (err.code !== 'EEXIST') throw err
-        }
-        continue
-      }
-      await pause()
-    }
-    await replace({ device: randomBytes(18).toString('base64url'), license: null, seen: 0 })
-    const data = await read()
-    if (!isDevice(data?.device)) throw new Error(`Can't read or replace ${file}`)
-    return data.device
-  }
-
-  async function update(change) {
-    const data = (await read()) ?? {}
-    await replace({ ...data, ...change, device: data.device })
-  }
-
-  async function current() {
-    const clock = now()
-    if ((await read()) === null) return { device: null, token: null, license: null, at: clock }
-    const dev = await device()
-    const data = (await read()) ?? {}
-    const seen = finite(data.seen)
-    if (typeof data.license !== 'string') return { device: dev, token: null, license: null, at: Math.max(clock, seen) }
-    const checked = await check(data.license, keys, dev)
-    if (!checked.ok) return { device: dev, token: null, license: null, reason: checked.reason, at: Math.max(clock, seen) }
-    if (clock > seen + SEEN_STEP) await update({ seen: clock }).catch(() => {})
-    return { device: dev, token: data.license, license: checked.license, at: Math.max(clock, seen, checked.license.iat) }
-  }
-
-  async function save(token) {
-    const dev = await device()
-    const checked = await check(token, keys, dev)
-    if (!checked.ok) return checked
-    const data = (await read()) ?? {}
-    const stored = typeof data.license === 'string' ? await check(data.license, keys, dev) : null
-    if (stored?.ok && stored.license.iat > checked.license.iat) {
-      return { ok: true, license: stored.license, at: Math.max(now(), finite(data.seen), stored.license.iat) }
-    }
-    await update({ license: token, seen: checked.license.iat })
-    return { ok: true, license: checked.license, at: Math.max(now(), checked.license.iat) }
-  }
-
-  async function clear() {
-    await device()
-    await update({ license: null })
-  }
-
-  return { file, device, current, save, clear }
-}
+import { randomBytes } from 'node:crypto'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { LICENSE_PUBLIC_KEYS, verifyLicense } from './index.mjs'
+
+const FILE = 'license.json'
+const DEVICE = /^[A-Za-z0-9_-]{8,100}$/
+const SEEN_STEP = 3600
+const READ_TRIES = 5
+const RENAME_TRIES = 10
+const PAUSE_MS = 20
+const CLOUD_URL = 'https://threadcrumbs.io/api'
+const LOCAL_CLOUD_URL = 'http://localhost:8787/api'
+const CLOUD_TIMEOUT_MS = 15000
+
+const pause = () => new Promise((resolve) => setTimeout(resolve, PAUSE_MS))
+const isDevice = (value) => typeof value === 'string' && DEVICE.test(value)
+const finite = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0)
+
+export function threadcrumbsDataDir({ platform = process.platform, env = process.env, home = os.homedir() } = {}) {
+  if (env.THREADCRUMBS_DATA_DIR) return env.THREADCRUMBS_DATA_DIR
+  if (platform === 'win32') {
+    return path.win32.join(env.APPDATA || path.win32.join(home, 'AppData', 'Roaming'), 'Threadcrumbs')
+  }
+  if (platform === 'darwin') return path.posix.join(home, 'Library', 'Application Support', 'Threadcrumbs')
+  const xdg = env.XDG_DATA_HOME && path.posix.isAbsolute(env.XDG_DATA_HOME) ? env.XDG_DATA_HOME : ''
+  return path.posix.join(xdg || path.posix.join(home, '.local', 'share'), 'threadcrumbs')
+}
+
+export function trustedKeys({ env = process.env, development = false } = {}) {
+  const extra = development ? env.THREADCRUMBS_LICENSE_KEYS : ''
+  if (!extra) return { ...LICENSE_PUBLIC_KEYS }
+  let parsed
+  try {
+    parsed = JSON.parse(extra)
+  } catch {
+    throw new Error('THREADCRUMBS_LICENSE_KEYS must be JSON: { "<kid>": "<public key>" }')
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || !Object.values(parsed).every((k) => typeof k === 'string')) {
+    throw new Error('THREADCRUMBS_LICENSE_KEYS must map each key ID to a public key')
+  }
+  return { ...LICENSE_PUBLIC_KEYS, ...parsed }
+}
+
+export function cloudUrl({ env = process.env, development = false } = {}) {
+  return (env.THREADCRUMBS_CLOUD_URL || (development ? LOCAL_CLOUD_URL : CLOUD_URL)).replace(/\/+$/, '')
+}
+
+const PORTAL_REFUSALS = {
+  not_activated: 'Enter your license key on this computer first.',
+  offline: "Couldn't reach the license service. Check your connection, then try again.",
+  unavailable: "The license service didn't answer as expected. Try again in a minute.",
+}
+
+const refusal = (error) => ({ error, why: PORTAL_REFUSALS[error] })
+
+function isHttps(url) {
+  try {
+    return new URL(url).protocol === 'https:'
+  } catch {
+    return false
+  }
+}
+
+export async function portalUrl({ license, device, fetch = globalThis.fetch, cloud = cloudUrl() } = {}) {
+  if (typeof license !== 'string' || !license || !isDevice(device)) return refusal('not_activated')
+  if (!cloud) return refusal('unavailable')
+  let response
+  try {
+    response = await fetch(`${cloud}/v1/portal`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ license, device }),
+      signal: AbortSignal.timeout(CLOUD_TIMEOUT_MS),
+    })
+  } catch {
+    return refusal('offline')
+  }
+  const data = await response.json().catch(() => null)
+  if (response.ok && typeof data?.url === 'string' && isHttps(data.url)) return { url: data.url }
+  if (!response.ok && typeof data?.error === 'string' && typeof data.why === 'string' && data.why) return { error: data.error, why: data.why }
+  return refusal('unavailable')
+}
+
+async function check(token, keys, device) {
+  try {
+    return await verifyLicense(token, { keys, device })
+  } catch {
+    return { ok: false, reason: 'malformed' }
+  }
+}
+
+export function licenseStore({ dir = threadcrumbsDataDir(), keys = LICENSE_PUBLIC_KEYS, now = () => Date.now() / 1000 } = {}) {
+  const file = path.join(dir, FILE)
+
+  async function read() {
+    let text
+    try {
+      text = await fsp.readFile(file, 'utf8')
+    } catch (err) {
+      if (err.code === 'ENOENT') return null
+      throw err
+    }
+    try {
+      const data = JSON.parse(text)
+      return data && typeof data === 'object' && !Array.isArray(data) ? data : {}
+    } catch {
+      return {}
+    }
+  }
+
+  const serialize = (data) => `${JSON.stringify(data, null, 2)}\n`
+
+  async function replace(data) {
+    await fsp.mkdir(dir, { recursive: true })
+    const temp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`
+    try {
+      await fsp.writeFile(temp, serialize(data), { mode: 0o600 })
+      for (let attempt = 1; ; attempt++) {
+        try {
+          return await fsp.rename(temp, file)
+        } catch (err) {
+          if (attempt >= RENAME_TRIES || !['EPERM', 'EACCES', 'EBUSY'].includes(err.code)) throw err
+          await pause()
+        }
+      }
+    } catch (err) {
+      await fsp.rm(temp, { force: true })
+      throw err
+    }
+  }
+
+  async function device() {
+    for (let attempt = 0; attempt < READ_TRIES; attempt++) {
+      const data = await read()
+      if (isDevice(data?.device)) return data.device
+      if (data === null) {
+        await fsp.mkdir(dir, { recursive: true })
+        try {
+          await fsp.writeFile(file, serialize({ device: randomBytes(18).toString('base64url'), license: null, seen: 0 }), { flag: 'wx', mode: 0o600 })
+        } catch (err) {
+          if (err.code !== 'EEXIST') throw err
+        }
+        continue
+      }
+      await pause()
+    }
+    await replace({ device: randomBytes(18).toString('base64url'), license: null, seen: 0 })
+    const data = await read()
+    if (!isDevice(data?.device)) throw new Error(`Can't read or replace ${file}`)
+    return data.device
+  }
+
+  async function update(change) {
+    const data = (await read()) ?? {}
+    await replace({ ...data, ...change, device: data.device })
+  }
+
+  async function current() {
+    const clock = now()
+    if ((await read()) === null) return { device: null, token: null, license: null, at: clock }
+    const dev = await device()
+    const data = (await read()) ?? {}
+    const seen = finite(data.seen)
+    if (typeof data.license !== 'string') return { device: dev, token: null, license: null, at: Math.max(clock, seen) }
+    const checked = await check(data.license, keys, dev)
+    if (!checked.ok) return { device: dev, token: null, license: null, reason: checked.reason, at: Math.max(clock, seen) }
+    if (clock > seen + SEEN_STEP) await update({ seen: clock }).catch(() => {})
+    return { device: dev, token: data.license, license: checked.license, at: Math.max(clock, seen, checked.license.iat) }
+  }
+
+  async function save(token) {
+    const dev = await device()
+    const checked = await check(token, keys, dev)
+    if (!checked.ok) return checked
+    const data = (await read()) ?? {}
+    const stored = typeof data.license === 'string' ? await check(data.license, keys, dev) : null
+    if (stored?.ok && stored.license.iat > checked.license.iat) {
+      return { ok: true, license: stored.license, at: Math.max(now(), finite(data.seen), stored.license.iat) }
+    }
+    await update({ license: token, seen: checked.license.iat })
+    return { ok: true, license: checked.license, at: Math.max(now(), checked.license.iat) }
+  }
+
+  async function clear() {
+    await device()
+    await update({ license: null })
+  }
+
+  return { file, device, current, save, clear }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@threadcrumbs/common",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "type": "module",
   "description": "Code the Threadcrumbs apps share, starting with the readers for each coding-agent harness.",
   "license": "SEE LICENSE IN LICENSE.md",