From fbf92d0414527dcdcde6ce52198d507b7b70e1d4 Mon Sep 17 00:00:00 2001 From: Mehar Khanna Date: Sat, 14 Nov 2026 16:53:06 -0500 Subject: [PATCH] Collector: partner API (a partner's server makes an app per user and reads what it finds) An account GenClass makes a partner by hand (accounts.partner_apps, with the Enterprise grant) gets partner keys on /account and five server-to-server routes under /api/partner/v1: make the app for a user's ref (idempotent), list them, read one app's dashboard data and events, and hand that user a private dashboard link. Keys are gcp_ + 32 bytes, hashed, browser-made, no CORS; a key reaches its own account's apps only and stops when revoked or when the account stops being a partner. Nothing deletes an app. Migration 0023 (partner_apps, projects.partner_ref, partner_keys). Co-Authored-By: Claude Opus 5.5 --- PRIVACY.md | 8 + telemetry-worker/README.md | 43 ++++ telemetry-worker/migrations/0023_partners.sql | 21 ++ telemetry-worker/src/account-pages.ts | 39 ++- telemetry-worker/src/auth.ts | 24 +- telemetry-worker/src/cli.ts | 10 +- telemetry-worker/src/collector.ts | 4 + telemetry-worker/src/dashboard.ts | 15 +- telemetry-worker/src/partner.ts | 229 ++++++++++++++++++ telemetry-worker/test/partner.test.ts | 177 ++++++++++++++ 10 files changed, 561 insertions(+), 9 deletions(-) create mode 100644 telemetry-worker/migrations/0023_partners.sql create mode 100644 telemetry-worker/src/partner.ts create mode 100644 telemetry-worker/test/partner.test.ts diff --git a/PRIVACY.md b/PRIVACY.md index 0a0eadcf..adc32015 100644 --- a/PRIVACY.md +++ b/PRIVACY.md @@ -141,6 +141,14 @@ and nothing else of your account: not its billing, its sign-ins, its export or i a member and a member can leave at any time; deleting an account removes it from every team, and deletes its own team and invite links. +## Partners + +A partner is a product we agreed with that sets GenClass up for its own users. Its server makes a GenClass app for +each of them in the partner's own account, and the partner reads what that app sends and finds, as any account reads +its own apps. If a partner set GenClass up in your app, your app's data goes to that partner's account, and the +partner's own terms say what it does with it; we collect nothing more for it. We store the partner's id for each app +(its own id for you, which we ask partners not to make your email), and its partner keys only as one-way hashes. + ## Paid plans, payments and Stripe Free costs nothing, Pro (named Team until 12 November 2026) is sold on genclass.dev for an account, per developer diff --git a/telemetry-worker/README.md b/telemetry-worker/README.md index 49ea4d66..15bfc485 100644 --- a/telemetry-worker/README.md +++ b/telemetry-worker/README.md @@ -1265,6 +1265,49 @@ CLOUDFLARE_ACCOUNT_ID=144bd5f5270b51dbe7faf46227a154f0 npx --yes wrangler@4 d1 e A worker keeps a key's answer in memory for up to 5 minutes (30 seconds for an unknown key), so a new extra key counts within 30 seconds. +## Partner API + +For a product that builds GenClass in for its own users (a coding-agent tool, a hosting or app-builder platform): its +server makes a GenClass app for each of its users, hands that user's code the app's key, and reads what the app finds. +The partner's account carries the apps and their plan, so its users need no GenClass account and no `genclass` +command (`src/partner.ts`, migration 0023). + +**Making an account a partner** is done by hand with the agreement, as a grant is: GenClass's Enterprise grant so +every app is covered, and `partner_apps`, how many apps the account may hold (NULL: not a partner). The account then +sees a Partner API section in its settings on /account, where it makes, names and revokes up to 10 partner keys +(`gcp_` + 32 random bytes, shown once; only the SHA-256 is stored). + +```bash +CLOUDFLARE_ACCOUNT_ID=144bd5f5270b51dbe7faf46227a154f0 npx --yes wrangler@4 d1 execute genclass-dashboard --remote \ + --command "UPDATE accounts SET comp_plan = 'enterprise', comp_until = '', partner_apps = WHERE lower(email) = lower('')" +``` + +Ending it: `partner_apps = NULL` (every key stops at once; the apps stay in the account) and the grant's end date. + +| route (key: `Authorization: Bearer gcp_...`) | behaviour | +|---|---| +| `POST /api/partner/v1/apps` | `{ ref, name? }`: `ref` is the partner's own id for its user, not an email (1 to 64 of `A-Z a-z 0-9 . _ : @ -`, starting with a letter or digit), unique in the account; `name` defaults to it. 201 `{ created: true, app }` the first time, 200 `{ created: false, app }` for a ref it has made before. `app`: `id, ref, name, key` (the app's public `gc_` key), `created, first_event, last_event, install` (`npx @genclass/runtime@beta init --token `, which needs no sign-in) and `dashboard_url` (the partner's own view). 409 at the account's `partner_apps` (every app of the account counts); 429 under the creation limits every account has | +| `GET /api/partner/v1/apps?ref=&cursor=` | the apps the API made, oldest first, 100 a page: `{ apps, next_cursor, limit: { apps, used } }` | +| `GET /api/partner/v1/apps/?range=24h\|7d\|30d` | the app's dashboard as data, cut by the account's plan: what `/api/cli/app` answers (`src/cli.ts` appView) | +| `GET /api/partner/v1/apps//events?from&to&format&limit&cursor` | its stored events: the export (`exportFor`, same rules and limits) | +| `POST /api/partner/v1/apps//link` | 201 `{ dashboard_url }`: a private dashboard link (`/dashboard/`) to hand that user; the previous link stops working | +| `GET`, `POST /api/account/partner-keys`; `DELETE .../` | browser session on genclass.dev only: list, create (a partner only) and revoke partner keys | + +Rules: a key reaches its own account's apps only (any other id is 404); a cookie, a terminal session or an export key +is never a partner key; the routes send no CORS headers, so a key is used from the partner's server, never a page. +Nothing here deletes an app or changes its key (that stays on the website). Every route counts against the account's +per-minute budget (`EXPORT_LIMIT`, bucket `partner`). An app made here is an ordinary app of the account: its plan, +history, analytics, email reports and dashboard are the account's. + +How a coding agent uses it, per user: `POST /apps` with the user's id, run the `install` line in the user's project +(or set `token` in `GenClass.init` / `data-token` on the script tag), then read `GET /apps/` for what it found, or +give the user the link from `POST /apps//link`. + +```bash +curl -X POST https://genclass.dev/api/partner/v1/apps -H "Authorization: Bearer $GENCLASS_PARTNER_KEY" \ + -H "content-type: application/json" -d '{"ref":"user_42","name":"Ada'"'"'s shop"}' +``` + ## Reports by email A GenClass report about an account's apps goes to the account's email on the schedule it chooses, and an alert goes diff --git a/telemetry-worker/migrations/0023_partners.sql b/telemetry-worker/migrations/0023_partners.sql new file mode 100644 index 00000000..5509c3ef --- /dev/null +++ b/telemetry-worker/migrations/0023_partners.sql @@ -0,0 +1,21 @@ +-- Partners (owner request, 2026-11-14): an account GenClass lets build GenClass into its own product. Its server makes +-- an app for each of its users through the partner API (src/partner.ts) and reads what those apps find. Set by hand +-- with the agreement, like comp_until (telemetry-worker/README.md "Partner API"). Additive only. + +-- How many apps the account may hold when the partner API makes one; NULL: not a partner (every partner route is 403). +ALTER TABLE accounts ADD COLUMN partner_apps INTEGER; + +-- The partner's own id for the user an app is for (unique in its account); NULL for every app not made by the API. +ALTER TABLE projects ADD COLUMN partner_ref TEXT; +CREATE UNIQUE INDEX IF NOT EXISTS projects_partner_ref ON projects (account_id, partner_ref) WHERE partner_ref IS NOT NULL; + +-- Partner keys: `gcp_` + 32 random bytes, stored as a SHA-256 hex. They reach /api/partner/v1/* and nothing else. +CREATE TABLE IF NOT EXISTS partner_keys ( + id TEXT PRIMARY KEY, + hash TEXT NOT NULL UNIQUE, + account_id TEXT NOT NULL, + label TEXT, + created TEXT NOT NULL, + last_used TEXT +); +CREATE INDEX IF NOT EXISTS partner_keys_account ON partner_keys (account_id); diff --git a/telemetry-worker/src/account-pages.ts b/telemetry-worker/src/account-pages.ts index cb31387d..d79ecdaa 100644 --- a/telemetry-worker/src/account-pages.ts +++ b/telemetry-worker/src/account-pages.ts @@ -679,6 +679,8 @@ export interface AccountView { * its first app (the owner's call, 2026-11-13: "our entire goal is for them to put their credit cards in"). */ trial?: { plan: string; price: string; days: number | null; features: string[]; start: string } | null; + /** The partner API (src/partner.ts): how many apps the account may hold, how many it has, its keys. Null: not a partner. */ + partner?: { apps: number; used: number; keys: { id: string; label: string | null; created: string; lastUsed: string | null }[] } | null; } const TRANSPORT_WORDS: Record = { @@ -941,7 +943,7 @@ ${planBlock} ${others ? '
' : ""} -
+${partnerSection(v.partner)}

Delete account

Cannot be undone

Deletes this account. A paid plan is cancelled at once.

@@ -955,7 +957,7 @@ ${planBlock} (function(){ gcDropQuery([]); // views: Projects (the default) and Account settings; the hash names the part, so links and the back button work - var VIEW = { projects: "projects", apps: "projects", claim: "projects", "new-app": "projects", settings: "settings", security: "settings", password: "settings", passkeys: "settings", sessions: "settings", cli: "settings", "delete": "settings" }; + var VIEW = { projects: "projects", apps: "projects", claim: "projects", "new-app": "projects", settings: "settings", security: "settings", password: "settings", passkeys: "settings", sessions: "settings", cli: "settings", partner: "settings", "delete": "settings" }; var parts = [].slice.call(document.querySelectorAll("[data-v]")); function show(id, jump){ if (id === "new-app") { location.replace("/account/new"); return true; } @@ -998,6 +1000,17 @@ ${planBlock} }); } del("[data-revoke]", "data-revoke", function(id){ return "/api/account/sessions/" + encodeURIComponent(id); }, "clierr", null); + del("[data-revokepk]", "data-revokepk", function(id){ return "/api/account/partner-keys/" + encodeURIComponent(id); }, "pterr", "Revoke? Its server stops at once"); + var ptf = document.getElementById("ptf"); + if (ptf) ptf.addEventListener("submit", function(ev){ + ev.preventDefault(); + var b = ptf.querySelector("button"), pe = document.getElementById("pterr"), out = document.getElementById("ptnew"); + pe.textContent = ""; gcBusy(b, true, "Working..."); + gcPost("/api/account/partner-keys", { label: document.getElementById("ptlabel").value }).then(function(j){ + gcBusy(b, false); document.getElementById("ptlabel").value = ""; + document.getElementById("ptkey").textContent = j.key; out.classList.remove("hidden"); + }, function(e){ pe.textContent = gcWhy(e); gcBusy(b, false); }); + }); // removing a passkey asks for a passkey first when this session has not used one in the last few minutes document.querySelectorAll("[data-rmkey]").forEach(function(b){ b.addEventListener("click", function(){ @@ -1079,6 +1092,28 @@ ${planBlock} }); } +/** The Partner API section of /account settings: shown only to an account GenClass made a partner. */ +export function partnerSection(p: AccountView["partner"]): string { + if (!p) return ""; + const keys = p.keys.length + ? `
${p.keys + .map((k) => ``) + .join("")}
Partner keyCreatedLast used
${esc(k.label ?? "Partner key")}${time(k.created)}${time(k.lastUsed, "ago")}
` + : '

No partner keys yet.

'; + return `
+

Partner API

${p.used} of ${p.apps} apps
+

Your server makes an app for each of your users and reads what it finds. Keep keys on your server: a page in a browser cannot use them. How it works

+ ${keys} +
+ + +
+`; +} + +/** Where the partner API is written down (telemetry-worker/README.md "Partner API"). */ +export const PARTNER_DOCS = "https://github.com/genclass-dev/GenClass/blob/main/telemetry-worker/README.md#partner-api"; + export interface NewProjectView { account: AccountView["account"]; /** The account's projects (the header's switcher) and its plan's name (the organization's badge). */ diff --git a/telemetry-worker/src/auth.ts b/telemetry-worker/src/auth.ts index a6ed82ae..a1e6ea1b 100644 --- a/telemetry-worker/src/auth.ts +++ b/telemetry-worker/src/auth.ts @@ -116,7 +116,7 @@ export const FRESH_MS = 5 * MINUTE; /** Where to write about an account whose passkeys are all lost, or whose password is forgotten (no email reset yet). */ export const RECOVERY_CONTACT = "mehar@genclass.dev"; /** Global ceiling on apps created in accounts per minute (anonymous creation has its own, collector.ts). */ -const MAX_ACCOUNT_PROJECTS_PER_MINUTE = 60; +export const MAX_ACCOUNT_PROJECTS_PER_MINUTE = 60; /** The web session cookie: __Host- on HTTPS; the plain name only for plain-HTTP localhost in development. */ export const SESSION_COOKIE = "__Host-gc_session"; @@ -1808,10 +1808,12 @@ async function deleteAccount(c: C): Promise { c.db.prepare(`DELETE FROM integrations WHERE project_id IN (${owned})`).bind(id), c.db.prepare(`DELETE FROM forward_log WHERE project_id IN (${owned})`).bind(id), c.db.prepare("DELETE FROM export_keys WHERE account_id = ?").bind(id), + c.db.prepare("DELETE FROM partner_keys WHERE account_id = ?").bind(id), c.db.prepare("DELETE FROM custom_requests WHERE account_id = ?").bind(id), ...["daily", "hourly", "recent", "sessions", "visits"].map((t) => c.db.prepare(`DELETE FROM ${t} WHERE token IN (${own})`).bind(id)), c.db.prepare("DELETE FROM projects WHERE account_id = ? AND private_link = 0").bind(id), - c.db.prepare("UPDATE projects SET account_id = NULL WHERE account_id = ?").bind(id), + // an app that keeps its private link (one the partner API handed its user, too) leaves without its partner ref + c.db.prepare("UPDATE projects SET account_id = NULL, partner_ref = NULL WHERE account_id = ?").bind(id), c.db.prepare("DELETE FROM credentials WHERE account_id = ?").bind(id), c.db.prepare("DELETE FROM passwords WHERE account_id = ?").bind(id), c.db.prepare("DELETE FROM password_devices WHERE account_id = ?").bind(id), @@ -1883,6 +1885,24 @@ async function accountView(c: C, a: Auth): Promise { pick: { claim: c.url.searchParams.get("claim") === "1", save: c.url.searchParams.get("save") === "1" }, recovery: RECOVERY_CONTACT, githubApp: githubApp(c.env) !== null, + partner: await partnerView(c, a.account.id), + }; +} + +/** The partner API's section of /account (src/partner.ts): only for an account GenClass made a partner. */ +async function partnerView(c: C, accountId: string): Promise { + const acct = await c.db.prepare("SELECT partner_apps FROM accounts WHERE id = ?").bind(accountId).first<{ partner_apps: number | null }>(); + const apps = Number(acct?.partner_apps ?? 0); + if (!(apps > 0)) return null; + const [used, keys] = await c.db.batch([ + c.db.prepare("SELECT COUNT(*) AS n FROM projects WHERE account_id = ?").bind(accountId), + c.db.prepare("SELECT id, label, created, last_used FROM partner_keys WHERE account_id = ? ORDER BY created").bind(accountId), + ]); + const rows = (r: unknown) => ((r as { results?: Record[] })?.results ?? []) as Record[]; + return { + apps, + used: Number(rows(used)[0]?.n ?? 0), + keys: rows(keys).map((k) => ({ id: String(k.id), label: (k.label as string | null) ?? null, created: String(k.created), lastUsed: (k.last_used as string | null) ?? null })), }; } diff --git a/telemetry-worker/src/cli.ts b/telemetry-worker/src/cli.ts index b3b54fed..8ca10b59 100644 --- a/telemetry-worker/src/cli.ts +++ b/telemetry-worker/src/cli.ts @@ -50,7 +50,7 @@ import { answer, appDigest, MAX_ASK_BYTES, readQuestion } from "./ask.js"; import { accountContext, accountJson, accountProjects, authenticate, fail, lockedJson, makeLinkFor, ownedProject, projectJson, readableProject, readJson, upgradeJson, type Auth, type C } from "./auth.js"; import { exportFor, integrationsFor, overBudget, tooMany, trialFor } from "./billing.js"; import type { Env, HandleOptions } from "./collector.js"; -import { putFunnels, stats, stripAnalytics, stripProblems } from "./dashboard.js"; +import { putFunnels, stats, stripAnalytics, stripProblems, type Project } from "./dashboard.js"; import { isKind, KINDS } from "./forward.js"; import { githubApp } from "./github/config.js"; import { repoStatusForAccount } from "./github/http.js"; @@ -228,6 +228,14 @@ async function app(c: C): Promise { } const p = await readableProject(c, a.account.id, c.url.searchParams.get("id") ?? ""); if (!p) return fail(404, "not found"); + return appView(c, p); +} + +/** + * An app's dashboard as data (?range=), cut by its plan: what the browser dashboard reads. Shared by /api/cli/app and + * the partner API (src/partner.ts); the caller has checked that the account may read the app. + */ +export async function appView(c: C, p: Project): Promise { // the same plan rules as the dashboard page's own request (src/auth.ts, /api/account/projects//stats) const access = await projectAccess(c.db, p, c.env, c.now); if (!hasDashboard(access)) return lockedJson(c, access, p.id); diff --git a/telemetry-worker/src/collector.ts b/telemetry-worker/src/collector.ts index de654483..646b9016 100644 --- a/telemetry-worker/src/collector.ts +++ b/telemetry-worker/src/collector.ts @@ -55,6 +55,7 @@ import type { EmailBinding } from "./report.js"; import type { GithubEnv } from "./github/config.js"; import { routeGithub } from "./github/http.js"; import { routeCli } from "./cli.js"; +import { routePartner } from "./partner.js"; import { json, readCapped } from "./http.js"; import { afterBatch } from "./paid.js"; import { dashboardPage, notFoundPage, openSourcePage, ownEndpoint, securityHeaders, setupCommand, setupPage, startPage } from "./pages.js"; @@ -248,6 +249,9 @@ export async function handle(request: Request, env: Env, opts: HandleOptions = { // the `genclass` command's routes (src/cli.ts): /api/cli/* const cli = await routeCli(request, url, path, env, opts); if (cli) return cli; + // the partner API (src/partner.ts): /api/partner/* and /api/account/partner-keys, before the account routes + const partner = await routePartner(request, url, path, env, opts); + if (partner) return partner; const billing = await routeBilling(request, url, path, env, opts); if (billing) return billing; // teams (src/team-routes.ts): /api/team and the invite page /account/join/, before the account routes diff --git a/telemetry-worker/src/dashboard.ts b/telemetry-worker/src/dashboard.ts index 35da0fcc..5ac98144 100644 --- a/telemetry-worker/src/dashboard.ts +++ b/telemetry-worker/src/dashboard.ts @@ -129,13 +129,15 @@ export const PROJECT_COLUMNS = "id, token, name, created, last_event, first_even /** * Create a project. Without an account it is reachable through its private dashboard link (the secret, returned once). * With an account the secret is generated and hashed the same way (the column is required) but the caller does not - * show it and `private_link` is 0: the app is opened from the account only. + * show it and `private_link` is 0: the app is opened from the account only. `partnerRef`: the partner API's id for + * the user the app is for (src/partner.ts), unique in the account, so a second insert for it fails. */ export async function createProject( db: D1Like, name: string, now: Date, accountId: string | null = null, + partnerRef: string | null = null, ): Promise<{ id: string; token: string; secret: string; name: string; created: string }> { for (let attempt = 0; ; attempt++) { const id = newProjectId(); @@ -144,13 +146,18 @@ export async function createProject( const created = now.toISOString(); try { await db - .prepare("INSERT INTO projects (id, token, secret_hash, name, created, account_id, private_link) VALUES (?, ?, ?, ?, ?, ?, ?)") - .bind(id, token, await sha256Hex(secret), name, created, accountId, accountId ? 0 : 1) + .prepare( + partnerRef === null + ? "INSERT INTO projects (id, token, secret_hash, name, created, account_id, private_link) VALUES (?, ?, ?, ?, ?, ?, ?)" + : "INSERT INTO projects (id, token, secret_hash, name, created, account_id, private_link, partner_ref, plan_chosen) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)", + ) + .bind(id, token, await sha256Hex(secret), name, created, accountId, accountId ? 0 : 1, ...(partnerRef === null ? [] : [partnerRef, created])) .run(); tokenCache.set(token, { token, exp: now.getTime() + CACHE_OK_MS }); return { id, token, secret, name, created }; } catch (e) { - if (attempt >= 2) throw e; // a collision is astronomically unlikely; anything else is a real error + // a collision is astronomically unlikely; anything else is a real error (for a partner app: most often its ref is taken) + if (attempt >= 2 || partnerRef !== null) throw e; } } } diff --git a/telemetry-worker/src/partner.ts b/telemetry-worker/src/partner.ts new file mode 100644 index 00000000..9a1ac5aa --- /dev/null +++ b/telemetry-worker/src/partner.ts @@ -0,0 +1,229 @@ +// The partner API: a product that builds GenClass in for its own users (a tools directory, a hosting or app-builder +// platform) makes a GenClass app for each of them from its own server, hands that user the app's key, and reads what +// the app finds. Checked before the account routes (src/collector.ts). +// +// POST /api/partner/v1/apps { ref, name? }: the app for that user (201), or the one made for that ref +// before (200); `ref` is the partner's own id for the user +// GET /api/partner/v1/apps?ref=&cursor= the apps the API made, oldest first, 100 a page (`next_cursor`) +// GET /api/partner/v1/apps/?range=7d one app and its dashboard as data (what `genclass dashboard` reads) +// GET /api/partner/v1/apps//events its stored events: the export's from, to, format, limit and cursor +// POST /api/partner/v1/apps//link a private dashboard link to hand that user; the previous one stops +// GET|POST /api/account/partner-keys, DELETE /api/account/partner-keys/ partner keys (browser session, /account) +// +// Invariants: +// - A partner is an account GenClass set accounts.partner_apps on by hand, with the agreement (README "Partner API"). +// Without it every partner route is 403 and /account shows no partner section; the keys of an account that stops +// being a partner stop working at once, and its apps stay in the account. +// - The /api/partner/ routes take a partner key (Authorization: Bearer gcp_...) and nothing else: no cookie, no +// terminal session, no export key. They send no CORS headers, so no page in a browser can read them: the key stays +// on the partner's server. Keys are made, listed and revoked only by the browser session on genclass.dev; the +// key is shown once and only its SHA-256 is stored. +// - A key reaches its own account's apps only (another account's app is 404). Nothing here deletes an app or +// changes its key: removing an app stays on the website. +// - An app made here is an ordinary app of the partner's account: its plan is the account's (src/plans.ts), so the +// dashboard's lock, history and analytics rules apply unchanged. partner_apps takes the place of the account's +// abuse cap (MAX_APPS_PER_ACCOUNT) for apps made here; the per-account and global creation limits still apply. +// - Every partner route counts against the account's per-minute budget (EXPORT_LIMIT, bucket "partner"); the events +// route also against the export's own (src/billing.ts exportFor). + +import { accountContext, fail, makeLinkFor, MAX_ACCOUNT_PROJECTS_PER_MINUTE, ownedProject, readJson, type C } from "./auth.js"; +import { browserRead, browserWrite, exportFor, overBudget, tooMany } from "./billing.js"; +import { appView } from "./cli.js"; +import type { Env, HandleOptions } from "./collector.js"; +import { createProject, projectsCreatedSince, PROJECT_COLUMNS, randomBase62, sanitizeName, sha256Hex, type Project } from "./dashboard.js"; +import { json } from "./http.js"; +import { RUNTIME_PKG } from "./pages.js"; +import { PLANS_FILE } from "./plans.js"; +import { b64url } from "./webauthn.js"; + +const KEY_RE = /^gcp_[A-Za-z0-9_-]{43}$/; +/** A partner's id for one of its users: what its own database calls them, never shown to anyone else. */ +const REF_RE = /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,63}$/; +export const MAX_PARTNER_KEYS = 10; +const PAGE = 100; +const MINUTE = 60_000; + +const method = (): Response => fail(405, "method not allowed"); + +/** The partner behind a request: its key's account, while it is a partner. */ +async function partnerAuth(c: C): Promise<{ accountId: string; apps: number } | Response> { + const h = c.req.headers.get("authorization"); + const m = h === null ? null : /^Bearer\s+(\S+)$/i.exec(h.trim()); + if (!m || !KEY_RE.test(m[1]!)) return fail(401, "send a partner key: Authorization: Bearer gcp_..."); + const row = await c.db + .prepare("SELECT k.id, k.account_id, k.last_used, a.partner_apps FROM partner_keys k JOIN accounts a ON a.id = k.account_id WHERE k.hash = ?") + .bind(await sha256Hex(m[1]!)) + .first<{ id: string; account_id: string; last_used: string | null; partner_apps: number | null }>(); + if (!row) return fail(401, "this partner key is not valid (revoked, or never created)"); + const apps = Number(row.partner_apps ?? 0); + if (!(apps > 0)) return fail(403, `this account is not a partner; write to ${PLANS_FILE.contact}`); + if (!row.last_used || Date.parse(row.last_used) < c.now.getTime() - 10 * MINUTE) { + await c.db.prepare("UPDATE partner_keys SET last_used = ? WHERE id = ?").bind(c.now.toISOString(), row.id).run(); + } + if (await overBudget(c.env.EXPORT_LIMIT, "partner", row.account_id)) return tooMany(); + return { accountId: row.account_id, apps }; +} + +type PartnerRow = Pick & { partner_ref: string | null }; + +/** One app as the partner API shows it: `key` is the app's public key, the one its runtime sends. */ +function appJson(c: C, p: PartnerRow): Record { + return { + id: p.id, + ref: p.partner_ref, + name: p.name, + key: p.token, + created: p.created, + first_event: p.first_event, + last_event: p.last_event, + install: `npx ${RUNTIME_PKG} init --token ${p.token}`, + dashboard_url: `${c.cfg.origin}/account/apps/${p.id}`, + }; +} + +const COLUMNS = `${PROJECT_COLUMNS}, partner_ref`; + +async function byRef(c: C, accountId: string, ref: string): Promise { + return c.db.prepare(`SELECT ${COLUMNS} FROM projects WHERE account_id = ? AND partner_ref = ?`).bind(accountId, ref).first(); +} + +async function createApp(c: C, who: { accountId: string; apps: number }): Promise { + const body = await readJson(c, 4096); + if (body instanceof Response) return body; + const ref = body.ref; + if (typeof ref !== "string" || !REF_RE.test(ref)) return fail(400, "ref is your id for the user, 1 to 64 letters, digits and . _ : @ - (starting with a letter or digit)"); + if (body.name !== undefined && typeof body.name !== "string") return fail(400, "name is text"); + const had = await byRef(c, who.accountId, ref); + if (had) return json(200, { created: false, app: appJson(c, had) }); + const n = Number((await c.db.prepare("SELECT COUNT(*) AS n FROM projects WHERE account_id = ?").bind(who.accountId).first<{ n: number }>())?.n ?? 0); + if (n >= who.apps) return fail(409, `this account holds ${n} apps, its partner limit of ${who.apps}; write to ${PLANS_FILE.contact} for more`); + if (c.env.CREATE_LIMITER) { + const { success } = await c.env.CREATE_LIMITER.limit({ key: (await sha256Hex(`create:account:${who.accountId}`)).slice(0, 32) }); + if (!success) return fail(429, "too many apps created; try again in a minute", { "retry-after": "60" }); + } + if ((await projectsCreatedSince(c.db, new Date(c.now.getTime() - MINUTE), "account")) >= MAX_ACCOUNT_PROJECTS_PER_MINUTE) { + return fail(429, "too many apps created; try again in a minute", { "retry-after": "60" }); + } + const name = sanitizeName(typeof body.name === "string" && body.name.trim() ? body.name : ref); + try { + await createProject(c.db, name, c.now, who.accountId, ref); + } catch (e) { + // two requests for one ref at once: the unique index lets one in, and the other answers with that app + const won = await byRef(c, who.accountId, ref); + if (won) return json(200, { created: false, app: appJson(c, won) }); + throw e; + } + return json(201, { created: true, app: appJson(c, (await byRef(c, who.accountId, ref))!) }); +} + +export const encodeCursor = (p: { created: string; id: string }): string => b64url(new TextEncoder().encode(`${p.created}|${p.id}`)); +function decodeCursor(v: string | null): { created: string; id: string } | null | "bad" { + if (v === null || v === "") return null; + try { + const s = atob(v.replace(/-/g, "+").replace(/_/g, "/")); + const [created, id] = s.split("|"); + return created && id && !Number.isNaN(Date.parse(created)) ? { created, id } : "bad"; + } catch { + return "bad"; + } +} + +async function listApps(c: C, who: { accountId: string; apps: number }): Promise { + const q = c.url.searchParams; + const ref = q.get("ref"); + if (ref !== null && !REF_RE.test(ref)) return fail(400, "ref is your id for the user, 1 to 64 letters, digits and . _ : @ -"); + const cursor = decodeCursor(q.get("cursor")); + if (cursor === "bad") return fail(400, "this cursor is not valid; send next_cursor from the previous page"); + const where = ["account_id = ?", "partner_ref IS NOT NULL"]; + const args: unknown[] = [who.accountId]; + if (ref !== null) { + where.push("partner_ref = ?"); + args.push(ref); + } + if (cursor) { + where.push("(created > ? OR (created = ? AND id > ?))"); + args.push(cursor.created, cursor.created, cursor.id); + } + const r = await c.db + .prepare(`SELECT ${COLUMNS} FROM projects WHERE ${where.join(" AND ")} ORDER BY created, id LIMIT ${PAGE + 1}`) + .bind(...args) + .all(); + const rows = r.results ?? []; + const more = rows.length > PAGE; + const shown = rows.slice(0, PAGE); + const used = Number((await c.db.prepare("SELECT COUNT(*) AS n FROM projects WHERE account_id = ?").bind(who.accountId).first<{ n: number }>())?.n ?? 0); + return json(200, { + apps: shown.map((p) => appJson(c, p)), + next_cursor: more ? encodeCursor(shown[shown.length - 1]! as { created: string; id: string }) : null, + limit: { apps: who.apps, used }, + }); +} + +async function partnerKeys(c: C, id: string | null): Promise { + const m = c.req.method; + if (id === null && (m === "GET" || m === "HEAD")) { + const a = await browserRead(c); + if (a instanceof Response) return a; + const r = await c.db.prepare("SELECT id, label, created, last_used FROM partner_keys WHERE account_id = ? ORDER BY created").bind(a.account.id).all(); + return json(200, { keys: r.results ?? [] }); + } + if (id === null && m === "POST") { + const a = await browserWrite(c, "partner keys can be created"); + if (a instanceof Response) return a; + const body = await readJson(c, 1024); + if (body instanceof Response) return body; + const acct = await c.db.prepare("SELECT partner_apps FROM accounts WHERE id = ?").bind(a.account.id).first<{ partner_apps: number | null }>(); + if (!(Number(acct?.partner_apps ?? 0) > 0)) return fail(403, `partner keys are for partners; write to ${PLANS_FILE.contact}`); + if (await overBudget(c.env.AUTH_LIMIT, "partner-key", a.account.id)) return tooMany(); + const n = await c.db.prepare("SELECT COUNT(*) AS n FROM partner_keys WHERE account_id = ?").bind(a.account.id).first<{ n: number }>(); + if (Number(n?.n ?? 0) >= MAX_PARTNER_KEYS) return fail(409, `an account can have at most ${MAX_PARTNER_KEYS} partner keys; revoke one first`); + // eslint-disable-next-line no-control-regex + const label = typeof body.label === "string" ? body.label.replace(/[\u0000-\u001f\u007f]/g, " ").trim().slice(0, 60) || null : null; + const key = `gcp_${b64url(crypto.getRandomValues(new Uint8Array(32)))}`; + const keyId = randomBase62(16); + await c.db + .prepare("INSERT INTO partner_keys (id, hash, account_id, label, created) VALUES (?, ?, ?, ?, ?)") + .bind(keyId, await sha256Hex(key), a.account.id, label, c.now.toISOString()) + .run(); + return json(201, { id: keyId, key, label, created: c.now.toISOString() }); + } + if (id !== null && m === "DELETE") { + const a = await browserWrite(c, "partner keys can be revoked"); + if (a instanceof Response) return a; + const r = await c.db.prepare("DELETE FROM partner_keys WHERE id = ? AND account_id = ? RETURNING id").bind(id, a.account.id).first(); + return r ? new Response(null, { status: 204, headers: { "cache-control": "no-store" } }) : fail(404, "no such partner key"); + } + return method(); +} + +/** The partner routes; null for any other path. */ +export async function routePartner(request: Request, url: URL, path: string, env: Env, opts: HandleOptions): Promise { + const keys = /^\/api\/account\/partner-keys(?:\/([^/]+))?$/.exec(path); + if (!keys && !path.startsWith("/api/partner/")) return null; + const c = accountContext(request, url, env, opts); + if (!c) return fail(503, "accounts unavailable"); + if (keys) return partnerKeys(c, keys[1] ?? null); + const m = request.method; + const get = m === "GET" || m === "HEAD"; + const route = /^\/api\/partner\/v1\/apps(?:\/([^/]+)(\/events|\/link)?)?$/.exec(path); + if (!route) return fail(404, "not found"); + const [, id, sub] = route; + if (id === undefined) { + if (!get && m !== "POST") return method(); + const who = await partnerAuth(c); + if (who instanceof Response) return who; + return m === "POST" ? createApp(c, who) : listApps(c, who); + } + if (sub === "/link" ? m !== "POST" : !get) return method(); + const who = await partnerAuth(c); + if (who instanceof Response) return who; + if (sub === "/events") return exportFor(c, who.accountId, id); + if (sub === "/link") { + const r = await makeLinkFor(c, who.accountId, id); + if (r.status !== 201) return r; + return json(201, { dashboard_url: ((await r.json()) as { dashboardUrl: string }).dashboardUrl }); + } + const p = await ownedProject(c, who.accountId, id); + if (!p) return fail(404, "not found"); + return appView(c, p); +} diff --git a/telemetry-worker/test/partner.test.ts b/telemetry-worker/test/partner.test.ts new file mode 100644 index 00000000..c4cbc005 --- /dev/null +++ b/telemetry-worker/test/partner.test.ts @@ -0,0 +1,177 @@ +// The partner API (src/partner.ts): a partner's server makes an app for each of its users and reads what it finds. +// Only for an account GenClass made a partner (accounts.partner_apps); keys made in the browser and shown once; +// a key reaches its own account's apps only, never through a browser (no CORS), and stops at once when revoked or +// when the account stops being a partner. +import { beforeEach, describe, expect, it } from "vitest"; +import { resetTokenCache } from "../src/dashboard.js"; +import { encodeCursor } from "../src/partner.js"; +import { call, cliToken, createApp, detection, now, resetClock, sendBatch, setPlan, setup, signedIn } from "./account-helpers.js"; + +beforeEach(() => { + resetClock(); + resetTokenCache(); +}); + +const FOREVER = "9999-12-31T00:00:00.000Z"; + +/** A partner: GenClass's Enterprise grant and a partner limit, set by hand as in production, with one key. */ +async function partner(apps = 5) { + const t = setup(); + const a = await signedIn(t.env, "partner@example.com"); + setPlan(t.sql, a.account.id, "free", { comp_until: FOREVER, comp_plan: "enterprise", partner_apps: apps }); + const made = await call(t.env, "POST", "/api/account/partner-keys", { body: { label: "server" }, cookie: a.cookie }); + expect(made.status).toBe(201); + const key = ((await made.json()) as any).key as string; + return { ...t, ...a, key }; +} + +const api = (t: { env: any; key: string }, method: string, path: string, body?: unknown) => + call(t.env, method, `/api/partner/v1${path}`, { bearer: t.key, origin: null, ...(body === undefined ? {} : { body }) }); +const lines = async (r: Response) => (await r.text()).split("\n").filter(Boolean); + +describe("partner API (src/partner.ts)", () => { + it("only a partner makes keys; a key is shown once, stored as a hash, listed without it", async () => { + const t = setup(); + const a = await signedIn(t.env); + expect((await call(t.env, "POST", "/api/account/partner-keys", { body: {}, cookie: a.cookie })).status).toBe(403); + setPlan(t.sql, a.account.id, "free", { comp_until: FOREVER, comp_plan: "enterprise", partner_apps: 3 }); + // the browser only, from genclass.dev + expect((await call(t.env, "POST", "/api/account/partner-keys", { body: {}, cookie: a.cookie, origin: "https://evil.example" })).status).toBe(403); + const bearer = await cliToken(t.env, a.cookie); + expect((await call(t.env, "POST", "/api/account/partner-keys", { body: {}, bearer, origin: null })).status).toBe(403); + const made = await call(t.env, "POST", "/api/account/partner-keys", { body: { label: "prod\u0000server" }, cookie: a.cookie }); + expect(made.status).toBe(201); + const { id, key, label } = (await made.json()) as any; + expect(key).toMatch(/^gcp_[A-Za-z0-9_-]{43}$/); + expect(label).toBe("prod server"); + expect(JSON.stringify(t.sql.rows("SELECT * FROM partner_keys"))).not.toContain(key); + const listed = await (await call(t.env, "GET", "/api/account/partner-keys", { cookie: a.cookie })).json(); + expect(JSON.stringify(listed)).not.toContain(key); + expect((listed as any).keys.map((k: any) => k.id)).toEqual([id]); + // /account shows the section to a partner, with its count + const page = await (await call(t.env, "GET", "/account", { cookie: a.cookie })).text(); + expect(page).toContain('id="partner"'); + expect(page).toContain("0 of 3 apps"); + expect(page).not.toContain(key); + }); + + it("an account that is not a partner sees no section, and its requests are refused", async () => { + const t = setup(); + const a = await signedIn(t.env); + expect(await (await call(t.env, "GET", "/account", { cookie: a.cookie })).text()).not.toContain('id="partner"'); + expect((await call(t.env, "GET", "/api/partner/v1/apps", { origin: null })).status).toBe(401); + expect((await call(t.env, "GET", "/api/partner/v1/apps", { cookie: a.cookie })).status).toBe(401); + expect((await call(t.env, "GET", "/api/partner/v1/apps", { bearer: `gcp_${"A".repeat(43)}`, origin: null })).status).toBe(401); + // a terminal's session is not a partner key + expect((await call(t.env, "GET", "/api/partner/v1/apps", { bearer: await cliToken(t.env, a.cookie), origin: null })).status).toBe(401); + }); + + it("makes one app per ref: 201 the first time, the same app after; bad refs are 400", async () => { + const t = await partner(); + const r = await api(t, "POST", "/apps", { ref: "user_42", name: "Ada's shop" }); + expect(r.status).toBe(201); + const { created, app } = (await r.json()) as any; + expect(created).toBe(true); + expect(app).toMatchObject({ ref: "user_42", name: "Ada's shop", first_event: null }); + expect(app.key).toMatch(/^gc_[A-Za-z0-9]{22}$/); + expect(app.install).toBe(`npx @genclass/runtime@beta init --token ${app.key}`); + expect(app.dashboard_url).toBe(`https://genclass.dev/account/apps/${app.id}`); + // the app is the partner's, like any other + expect(t.sql.rows("SELECT account_id, partner_ref, private_link FROM projects WHERE id = ?", app.id)).toEqual([{ account_id: t.account.id, partner_ref: "user_42", private_link: 0 }]); + const again = await api(t, "POST", "/apps", { ref: "user_42", name: "Another name" }); + expect(again.status).toBe(200); + expect(((await again.json()) as any)).toMatchObject({ created: false, app: { id: app.id, name: "Ada's shop", key: app.key } }); + // no name: the ref names it + expect(((await (await api(t, "POST", "/apps", { ref: "u-7" })).json()) as any).app.name).toBe("u-7"); + for (const ref of [undefined, "", " x", "a/b", "x".repeat(65), 42]) expect((await api(t, "POST", "/apps", { ref })).status).toBe(400); + expect((await api(t, "POST", "/apps", { ref: "ok", name: 5 })).status).toBe(400); + }); + + it("stops at the partner limit, counting every app of the account", async () => { + const t = await partner(3); + await createApp(t.env, t.cookie, "Own site"); + expect((await api(t, "POST", "/apps", { ref: "a" })).status).toBe(201); + expect((await api(t, "POST", "/apps", { ref: "b" })).status).toBe(201); + const over = await api(t, "POST", "/apps", { ref: "c" }); + expect(over.status).toBe(409); + expect(((await over.json()) as any).error).toContain("partner limit of 3"); + // an existing ref still answers + expect((await api(t, "POST", "/apps", { ref: "a" })).status).toBe(200); + }); + + it("lists the apps it made, oldest first, by ref and by page, with the limit", async () => { + const t = await partner(); + await createApp(t.env, t.cookie, "Own site"); + const ids: string[] = []; + for (const ref of ["a", "b", "c"]) { + ids.push(((await (await api(t, "POST", "/apps", { ref })).json()) as any).app.id); + t.sql.db.prepare("UPDATE projects SET created = ? WHERE id = ?").run(new Date(now().getTime() + ids.length * 1000).toISOString(), ids.at(-1)!); + } + const all = (await (await api(t, "GET", "/apps")).json()) as any; + expect(all.apps.map((a: any) => a.ref)).toEqual(["a", "b", "c"]); + expect(all).toMatchObject({ next_cursor: null, limit: { apps: 5, used: 4 } }); + expect(((await (await api(t, "GET", "/apps?ref=b")).json()) as any).apps.map((a: any) => a.id)).toEqual([ids[1]]); + const first = all.apps[0]; + const rest = (await (await api(t, "GET", `/apps?cursor=${encodeCursor({ created: first.created, id: first.id })}`)).json()) as any; + expect(rest.apps.map((a: any) => a.ref)).toEqual(["b", "c"]); + expect((await api(t, "GET", "/apps?cursor=!!")).status).toBe(400); + expect((await api(t, "GET", "/apps?ref=a/b")).status).toBe(400); + }); + + it("reads an app's dashboard and events, and hands its user a private link", async () => { + const t = await partner(); + const { app } = (await (await api(t, "POST", "/apps", { ref: "u1" })).json()) as any; + await sendBatch(t.env, app.key, [{ t: "session", seq: 0, host: "shop.example", route: "/" }]); + await sendBatch(t.env, app.key, detection("duplicate", "/checkout"), { sid: "dddddddddddd" }); + const view = await api(t, "GET", `/apps/${app.id}?range=7d`); + expect(view.status).toBe(200); + expect(view.headers.get("access-control-allow-origin")).toBeNull(); + const v = (await view.json()) as any; + expect(v.plan).toMatchObject({ id: "enterprise" }); + expect(JSON.stringify(v)).not.toContain("SECRET PAGE TEXT"); + const ev = await api(t, "GET", `/apps/${app.id}/events`); + expect(ev.status).toBe(200); + expect(await lines(ev)).toHaveLength(3); // one line per event: the session, then the decision and its detection + const link = await api(t, "POST", `/apps/${app.id}/link`); + expect(link.status).toBe(201); + const url = ((await link.json()) as any).dashboard_url as string; + expect(url).toMatch(/^https:\/\/genclass\.dev\/dashboard\/[A-Za-z0-9]{32}$/); + expect((await call(t.env, "GET", new URL(url).pathname, { origin: null })).status).toBe(200); + // a new link replaces the old one + await api(t, "POST", `/apps/${app.id}/link`); + expect((await call(t.env, "GET", new URL(url).pathname, { origin: null })).status).toBe(404); + // methods + expect((await api(t, "GET", `/apps/${app.id}/link`)).status).toBe(405); + expect((await api(t, "DELETE", `/apps/${app.id}`)).status).toBe(405); + expect((await api(t, "GET", "/nothing")).status).toBe(404); + }); + + it("never another account's app; stops at once when revoked or no longer a partner", async () => { + const t = await partner(); + const other = await signedIn(t.env, "bob@example.com"); + setPlan(t.sql, other.account.id, "free", { comp_until: FOREVER, comp_plan: "enterprise" }); + const bobs = await createApp(t.env, other.cookie, "Bob's"); + expect((await api(t, "GET", `/apps/${bobs.id}`)).status).toBe(404); + expect((await api(t, "GET", `/apps/${bobs.id}/events`)).status).toBe(404); + expect((await api(t, "POST", `/apps/${bobs.id}/link`)).status).toBe(404); + expect((await api(t, "GET", "/apps")).status).toBe(200); + t.sql.db.prepare("UPDATE accounts SET partner_apps = NULL WHERE id = ?").run(t.account.id); + expect((await api(t, "GET", "/apps")).status).toBe(403); + t.sql.db.prepare("UPDATE accounts SET partner_apps = 5 WHERE id = ?").run(t.account.id); + const [{ id }] = t.sql.rows("SELECT id FROM partner_keys") as { id: string }[]; + expect((await call(t.env, "DELETE", `/api/account/partner-keys/${id}`, { cookie: t.cookie, origin: "https://evil.example" })).status).toBe(403); + expect((await call(t.env, "DELETE", `/api/account/partner-keys/${id}`, { cookie: t.cookie })).status).toBe(204); + expect((await api(t, "GET", "/apps")).status).toBe(401); + }); + + it("at most 10 keys; deleting the account removes them, and an app with a link leaves without its ref", async () => { + const t = await partner(); + for (let i = 1; i < 10; i++) expect((await call(t.env, "POST", "/api/account/partner-keys", { body: {}, cookie: t.cookie })).status).toBe(201); + expect((await call(t.env, "POST", "/api/account/partner-keys", { body: {}, cookie: t.cookie })).status).toBe(409); + const { app } = (await (await api(t, "POST", "/apps", { ref: "kept" })).json()) as any; + await api(t, "POST", `/apps/${app.id}/link`); + expect((await call(t.env, "DELETE", "/api/account", { body: { confirm: "delete" }, cookie: t.cookie })).status).toBe(204); + expect(t.sql.rows("SELECT COUNT(*) AS n FROM partner_keys")).toEqual([{ n: 0 }]); + expect(t.sql.rows("SELECT account_id, partner_ref FROM projects WHERE id = ?", app.id)).toEqual([{ account_id: null, partner_ref: null }]); + }); +});