@cookiecrumbs-eu/mcp 0.7.0

package/LICENSE

@@ -0,0 +1,134 @@
+CookieCrumbs Source-Available Licence
+Version 1.0, 2 September 2026
+
+Copyright (c) 2026 CookieCrumbs (cookiecrumbs.eu). All rights reserved.
+
+This licence covers the CookieCrumbs software published by CookieCrumbs under it
+(the "Software"): the `cookiecrumbs` command line, the `@cookiecrumbs/*` packages
+(MCP server, framework bindings, configuration schema), the `cc.js` banner runtime
+and the source files that accompany them. It also covers the CookieCrumbs brand
+assets in the `brand/` directory (the "Brand Assets"), with the additional rules in
+section 5.
+
+The Software exists to be used with the CookieCrumbs service at https://cookiecrumbs.eu
+(the "Service"). That is what this licence lets you do, including in commercial
+projects, without letting anyone take the project and turn it into something else.
+
+1. Definitions
+
+  "You" means the person or organisation exercising rights under this licence.
+  "Service Terms" means the terms of service, privacy policy and marketing
+  guidelines published at https://cookiecrumbs.eu, as amended from time to time.
+  "Modification" means any change to the Software or any work derived from it.
+  "Competing Service" means any product or service that offers consent management,
+  cookie banners, tracker scanning or consent-record keeping to third parties,
+  whether hosted, on-premise or embedded, other than the Service itself.
+
+2. Permitted use
+
+  Subject to the conditions in section 3, CookieCrumbs grants You a worldwide,
+  royalty-free, non-exclusive, non-transferable licence to:
+
+  a) install, run and use the Software, including for commercial purposes, on any
+     number of sites and machines, in order to use, configure, automate, integrate
+     with or extend the Service;
+  b) copy the Software into Your own repositories, build pipelines, containers and
+     developer tooling for the purpose in (a);
+  c) make Modifications for Your own use with the Service, and contribute them back
+     to CookieCrumbs;
+  d) redistribute unmodified copies of the Software, and of Your Modifications under
+     (c), provided this licence and all copyright, licence and attribution notices
+     stay attached and unaltered.
+
+3. Conditions
+
+  a) The Software may only be used together with the Service under an active
+     CookieCrumbs account, in accordance with the Service Terms.
+  b) You may not use the Software, any part of it or any Modification to build,
+     offer, host or operate a Competing Service, nor to help anyone else do so.
+  c) You may not remove, hide, alter or circumvent any licence notice, copyright
+     notice, attribution, plan entitlement check, telemetry the Service Terms
+     disclose, or the "Made & Hosted in Europe by CookieCrumbs" line where the
+     Service Terms require it.
+  d) You may not use the Software in a way that circumvents the limits of Your plan
+     or gains access to data that Your account is not entitled to.
+  e) You may not sublicense, sell, rent or lease the Software, or represent that
+     You own it or that CookieCrumbs endorses Your product.
+  f) You may not register, or attempt to register, any trademark, domain name or
+     package name that contains "CookieCrumbs" or is confusingly similar to it.
+
+  Any use outside these conditions requires a separate written agreement with
+  CookieCrumbs (hello@cookiecrumbs.eu).
+
+4. Contributions
+
+  If You send a Modification to CookieCrumbs (for example as a pull request), You
+  grant CookieCrumbs a perpetual, worldwide, irrevocable, royalty-free licence to
+  use, modify, sublicense and distribute that Modification as part of the Software
+  and the Service under any terms. You confirm that You have the right to grant
+  this licence.
+
+5. Brand Assets
+
+  The CookieCrumbs name, the cookie-and-crumbs mark, the wordmark and the logo
+  lockups are trademarks of CookieCrumbs and are not licensed under sections 2 to
+  4. You may use the Brand Assets, unaltered and as provided in the `brand/`
+  directory, only:
+
+  a) to state truthfully that a site, product or integration uses or works with
+     CookieCrumbs (for example "Made with CookieCrumbs", "Consent by CookieCrumbs"
+     or the attribution line the banner renders);
+  b) in articles, talks, documentation and comparisons that refer to CookieCrumbs;
+  c) in the ways the marketing guidelines at https://cookiecrumbs.eu expressly
+     allow.
+
+  You may not change the colours, proportions or shapes of the Brand Assets, put
+  them inside other marks, use them as or in Your own logo or app icon, or use them
+  in a way that suggests that CookieCrumbs made, endorses or is responsible for
+  Your product. The Brand Assets must always be recognisable as belonging to
+  CookieCrumbs.
+
+6. Third-party components
+
+  The Software depends on open-source packages that keep their own licences (see
+  each package's `node_modules` and `package-lock.json`). The wordmark is set in
+  Space Grotesk, which is licensed under the SIL Open Font License 1.1. Nothing in
+  this licence restricts those components beyond their own terms.
+
+7. No warranty
+
+  THE SOFTWARE AND THE BRAND ASSETS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. The
+  Software helps You operate a consent banner; it does not make Your site
+  compliant by itself and nothing it outputs is legal advice.
+
+8. Limitation of liability
+
+  TO THE EXTENT PERMITTED BY LAW, COOKIECRUMBS IS NOT LIABLE FOR ANY INDIRECT,
+  INCIDENTAL, SPECIAL, CONSEQUENTIAL OR PUNITIVE DAMAGES, OR FOR LOSS OF PROFITS,
+  DATA OR GOODWILL, ARISING FROM THE SOFTWARE OR THIS LICENCE, EVEN IF ADVISED OF
+  THE POSSIBILITY. Liability for intent, gross negligence, injury to life, body or
+  health, and under mandatory product-liability law is not limited.
+
+9. Termination
+
+  This licence ends automatically if You breach section 3 or section 5 and do not
+  cure the breach within 30 days of being notified, or immediately on a breach of
+  section 3(b) or 3(f). It also ends when Your CookieCrumbs account is closed. On
+  termination You must stop using the Software and the Brand Assets and delete
+  Your copies, except that copies of the consent records and configurations that
+  belong to You remain Yours. Sections 4, 7, 8 and 10 survive termination.
+
+10. General
+
+  This licence is governed by the laws of the Federal Republic of Germany,
+  excluding its conflict-of-law rules and the UN Convention on Contracts for the
+  International Sale of Goods. If any provision is unenforceable, the rest remains
+  in force. CookieCrumbs may publish new versions of this licence; new versions
+  apply to releases published under them, never retroactively. This is the whole
+  agreement about the Software and the Brand Assets, together with the Service
+  Terms for Your use of the Service.
+
+Questions about this licence, or a request for rights it does not grant:
+hello@cookiecrumbs.eu

package/README.md

@@ -0,0 +1,186 @@
+# @cookiecrumbs-eu/mcp
+
+The CookieCrumbs [Model Context Protocol](https://modelcontextprotocol.io) server. It gives a coding
+agent read access to your consent banner, your hosted scans and your compliance issues — and, when the
+token carries a write scope, **two-step** writes that land in the audit trail as *via MCP*.
+
+stdio only. Node 22+.
+
+```bash
+claude mcp add cookiecrumbs -- npx -y @cookiecrumbs-eu/mcp
+```
+
+```jsonc
+// .cursor/mcp.json
+{
+  "mcpServers": {
+    "cookiecrumbs": {
+      "command": "npx",
+      "args": ["-y", "@cookiecrumbs-eu/mcp"],
+      "env": { "COOKIECRUMBS_TOKEN": "cc_live_…" }
+    }
+  }
+}
+```
+
+## The token
+
+The server reads the token from, in order:
+
+1. `COOKIECRUMBS_TOKEN`;
+2. the credentials file the CLI writes (`%APPDATA%\cookiecrumbs\credentials.json` on Windows,
+   `~/.config/cookiecrumbs/credentials.json` elsewhere) — one credential store, shared with
+   `npx cookiecrumbs`.
+
+If neither exists the server still starts, and the first tool call answers with the two ways to fix it.
+It does **not** run a device flow: a stdio server has no terminal to print a user code on and no browser
+to open. Run `npx cookiecrumbs login` once, or create a machine token in the dashboard under
+**Developers → MCP**, then restart the server.
+
+Machine tokens can be restricted to one site and one environment. The server picks that up from
+`GET /v1/me` and every tool then defaults to that site.
+
+| Variable | Meaning |
+|---|---|
+| `COOKIECRUMBS_TOKEN` | `cc_live_…` bearer token |
+| `COOKIECRUMBS_API` | gateway base (default: the hosted gateway) |
+| `MCP_CLIENT` | overrides the client name in `X-CookieCrumbs-Client: mcp/<client>` |
+| `COOKIECRUMBS_CREDENTIALS` | path to the CLI credentials file |
+
+## Tools, and the scopes they need
+
+A tool is **advertised only when the token carries one of its scopes**. Hand an agent a read-only
+token and the write tools are not in its tool list at all — there is nothing for it to be tempted by.
+
+| Tool | Kind | Scope |
+|---|---|---|
+| `list_sites` | read | `sites:read` |
+| `get_site` | read | `sites:read` |
+| `get_banner` | read | `banner:read` |
+| `get_compliance_status` | read | `banner:read` |
+| `scan_site` | read | `scans:run` |
+| `get_scan` | read | `scans:read` |
+| `list_findings` | read | `scans:read` |
+| `explain_classification` | read | `scans:read` |
+| `check_first_layer` | read | `banner:read` |
+| `rules_reference` | read | — |
+| `get_declaration` | read | `banner:read` |
+| `list_versions` | read | `banner:read` |
+| `logs_summary` | read | `analytics:read` |
+| `logs_export` | read | `logs:export` |
+| `classify_tracker` | **write, two-step** | `banner:write` |
+| `update_banner` | **write, two-step** | `banner:write` |
+| `push_config` | **write, two-step** | `banner:publish` or `banner:write` |
+| `rollback_version` | **write, two-step** | `banner:publish` |
+
+### The whole site (`src/tools-config.ts`)
+
+Everything the dashboard can change, an agent can change too — and nothing more (team, billing and
+tokens stay in the dashboard). Same rules: scope-gated, two-step, audited.
+
+| Tool | Kind | Scope |
+|---|---|---|
+| `create_site` | **write, two-step** | `sites:write` |
+| `update_site` — name, retention, settings | **write, two-step** | `sites:write` |
+| `list_domains` | read | `sites:read` |
+| `verify_domain` — re-issues the DNS TXT / meta token | **write, two-step** | `sites:write` |
+| `list_scans` · `get_scan_diff` · `get_scan_schedule` · `get_install_status` | read | `scans:read` |
+| `set_scan_schedule` — cadence, pages, states, URLs, patterns, robots, pause | **write, two-step** | `scans:run` |
+| `check_install` — queue an install check, optionally wait | read | `scans:run` |
+| `list_alerts` | read | `scans:read` |
+| `acknowledge_alert` · `resolve_alert` | **write, two-step** | `scans:run` |
+| `list_services` | read | `banner:read` |
+| `add_service` · `update_service` · `delete_service` (destructive) | **write, two-step** | `banner:write` |
+| `suppress_issue` (reason required) · `unsuppress_issue` | **write, two-step** | `banner:write` |
+| `promote_version` — preview → production, diff first | **write, two-step** | `banner:publish` |
+| `list_templates` · `get_template` | read | `banner:read` |
+| `apply_template` · `save_template` · `delete_template` (destructive) | **write, two-step** | `banner:write` |
+| `list_webhooks` · `list_alert_channels` · `get_usage` · `list_export_destinations` | read | `sites:read` |
+| `create_webhook` (secret shown once) · `update_webhook` · `delete_webhook` (destructive) | **write, two-step** | `sites:write` |
+| `create_alert_channel` · `update_alert_channel` · `delete_alert_channel` (destructive) | **write, two-step** | `sites:write` |
+| `list_export_schedules` | read | `logs:export` |
+| `create_export_schedule` · `update_export_schedule` · `delete_export_schedule` (destructive) | **write, two-step** | `logs:export` |
+
+Site, service, template, webhook and channel arguments accept an id **or a name** (a domain for
+sites, a URL for webhooks); the tool says what it matched. Deletes carry `destructiveHint` so an
+agent host can ask first.
+
+The table lives in [`src/matrix.ts`](src/matrix.ts). `src/tools.ts` and `src/tools-config.ts` build
+their tool definitions from it and the dashboard renders it, so the three can never disagree.
+
+## Resources
+
+* `cookiecrumbs://sites/<id>/config` — the draft configuration with its legal lint
+* `cookiecrumbs://sites/<id>/declaration` — the current cookie declaration as Markdown
+* `cookiecrumbs://sites/<id>/issues` — open compliance issues with their rules
+
+`<id>` accepts a site id, a primary domain or a site name.
+
+## The rules the server keeps
+
+**Every write is two-step.** The first call — `confirm: false`, which is the default — returns a
+unified diff of what would change (plus the legal lint where a banner config is involved), and
+changes nothing. Only `confirm: true` writes. A confirmed `push_config` also requires a `note`, which
+goes into the version and into the audit trail. Plan limits answer with the feature they need (402),
+and a value the plan clamped (a daily scan cadence on a monthly plan) is reported in the answer,
+never silently applied.
+
+**Nothing subject-level leaves the API.** `logs_export` returns an export id and the signed download
+URL. It never streams consent records into a conversation. `logs_summary` reads daily roll-ups only.
+
+**Classifications are quoted, not guessed.** `explain_classification` answers with the
+`tracker_patterns` row that matched, the `tracker_db` entry behind it — including its **source** and
+its **licence** — and the regime rule that follows from the category. If the finding is unclassified it
+says exactly that, and offers nothing else.
+
+**Citations are real or absent.** The rules reference (`@cookiecrumbs/config/rules`) carries verbatim
+wording only where it was verified against the primary source; everything else carries a summary in our
+own words and `quote: null`. Nothing the server returns is a legal assessment, and every citation block
+says so.
+
+**Every request is attributable.** `X-CookieCrumbs-Client: mcp/<client>` goes out on every call — the
+client name comes from `MCP_CLIENT` or from the MCP `initialize` params — so the gateway records
+`channel = 'mcp'` and the audit row reads *via MCP · &lt;token name&gt;*.
+
+## Example
+
+```
+> why is _fbp classified as Marketing on e2e.cookiecrumbs.test?
+
+# http_cookie `_fbp` on e2e.cookiecrumbs.test (first party)
+## Category: marketing
+Decided by: service (classification_source `service`, confidence 1)
+## The tracker database row this came from
+  provider:        Meta Pixel (facebook.com)
+  source:          cookiecrumbs
+  licence:         CC0
+  Consent Mode:    ad_storage, ad_user_data, ad_personalization
+## The pattern that matched
+  tracker_patterns row …: kind=cookie_name, pattern=`_fbp`, match_type=exact
+## The regime rule applied
+  Under an opt-in regime … nothing in category "marketing" may be stored or read before
+  the visitor gives consent …
+
+Citations:
+  • Directive 2002/58/EC (ePrivacy Directive), Article 5(3) — “Member States shall ensure that …”
+  • EDPB, Cookie Banner Taskforce report (para. 24) — “… the legal basis for the placement/reading
+    of cookies pursuant to Article 5 (3) cannot be the legitimate interests of the controller.”
+
+This is not a legal assessment.
+```
+
+## Known gaps
+
+* `classify_tracker` with `confirm: true` calls `PATCH /v1/services/:id`. Where a gateway does not
+  expose that route yet, the dry run still works and the confirmed call answers with what to do
+  instead of a raw error.
+* `logs_summary` calls `GET /v1/sites/:id/analytics/daily` and needs the `analytics:read` scope. Where
+  the route or the scope is not deployed, the tool is simply not advertised, or answers that nothing
+  was read.
+
+## Development
+
+```bash
+npm run build -w @cookiecrumbs-eu/mcp     # tsc → dist/mcp/src/index.js (the bin)
+npm test -w @cookiecrumbs-eu/mcp          # tool registration by scope, diff rendering, error mapping
+```

package/dist/cli/src/api.js

@@ -0,0 +1,192 @@
+import { randomUUID } from 'node:crypto';
+import { CliError } from "./errors.js";
+import { normaliseApi } from "./util.js";
+const exitFor = (status) => (status === 409 || status === 412 || status === 400 ? 2 : 1);
+function codeFromProblem(problem, status) {
+    if (typeof problem.code === 'string' && problem.code)
+        return problem.code;
+    if (typeof problem.type === 'string' && problem.type && problem.type !== 'about:blank') {
+        const tail = problem.type.split(/[/#:]/).filter(Boolean).pop();
+        if (tail)
+            return tail;
+    }
+    if (typeof problem.title === 'string' && problem.title)
+        return problem.title.toLowerCase().replace(/[^a-z0-9]+/g, '_');
+    return `http_${status}`;
+}
+/** Map a non-2xx response (RFC 9457 problem+json when available) to a CliError. */
+export function problemToError(status, body, fallbackText = '') {
+    const problem = (typeof body === 'object' && body !== null ? body : {});
+    const code = codeFromProblem(problem, status);
+    const detail = typeof problem.detail === 'string' && problem.detail ? problem.detail : typeof problem.title === 'string' && problem.title ? problem.title : fallbackText || `HTTP ${status}`;
+    const extra = {};
+    for (const k of ['errors', 'lint', 'issues', 'instance', 'type', 'title'])
+        if (problem[k] !== undefined)
+            extra[k] = problem[k];
+    let exit = exitFor(status);
+    if (status === 401)
+        exit = 1;
+    if (status === 403)
+        exit = 1;
+    return new CliError(code, detail, exit, { status, extra });
+}
+export class Api {
+    base;
+    token;
+    client;
+    constructor(base, token, version) {
+        this.base = normaliseApi(base);
+        this.token = token;
+        this.client = `cli/${version}`;
+    }
+    url(path, query) {
+        const u = new URL(`${this.base}/v1${path.startsWith('/') ? path : '/' + path}`);
+        if (query)
+            for (const [k, v] of Object.entries(query))
+                if (v !== undefined && v !== '')
+                    u.searchParams.set(k, String(v));
+        return u.toString();
+    }
+    headers(opts, hasBody) {
+        const h = {
+            'X-CookieCrumbs-Client': this.client,
+            'X-Request-Id': randomUUID(),
+            Accept: 'application/json, application/problem+json;q=0.9, */*;q=0.1',
+            ...(opts.headers ?? {}),
+        };
+        if (hasBody)
+            h['Content-Type'] = 'application/json';
+        if (!opts.anonymous) {
+            if (!this.token)
+                throw new CliError('not_logged_in', 'No API token. Run `cookiecrumbs login` or set COOKIECRUMBS_TOKEN.', 2);
+            h.Authorization = `Bearer ${this.token}`;
+        }
+        return h;
+    }
+    async send(method, path, opts) {
+        const hasBody = opts.body !== undefined;
+        const url = this.url(path, opts.query);
+        let res;
+        try {
+            res = await fetch(url, { method, headers: this.headers(opts, hasBody), body: hasBody ? JSON.stringify(opts.body) : undefined });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? (e.cause instanceof Error ? `${e.message}: ${e.cause.message}` : e.message) : String(e);
+            throw new CliError('network', `Could not reach ${url}: ${msg}`, 1);
+        }
+        if (res.ok || opts.allowStatus?.includes(res.status))
+            return res;
+        const text = await res.text();
+        let body = null;
+        try {
+            body = text ? JSON.parse(text) : null;
+        }
+        catch {
+            body = null;
+        }
+        throw problemToError(res.status, body, text.slice(0, 300));
+    }
+    async request(method, path, opts = {}) {
+        const res = await this.send(method, path, opts);
+        if (res.status === 204)
+            return undefined;
+        const text = await res.text();
+        if (!text)
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new CliError('bad_response', `Expected JSON from ${method} ${path}, got: ${text.slice(0, 120)}`, 1);
+        }
+    }
+    async requestText(method, path, opts = {}) {
+        const res = await this.send(method, path, opts);
+        return res.text();
+    }
+    async download(path, opts = {}) {
+        const res = await this.send('GET', path, { ...opts, headers: { Accept: '*/*', ...(opts.headers ?? {}) } });
+        const headers = {};
+        res.headers.forEach((v, k) => (headers[k.toLowerCase()] = v));
+        const cd = headers['content-disposition'] ?? '';
+        const m = /filename\*?=(?:UTF-8'')?"?([^";]+)"?/i.exec(cd);
+        return { bytes: Buffer.from(await res.arrayBuffer()), headers, filename: m ? decodeURIComponent(m[1]) : null };
+    }
+    // ---- typed routes ------------------------------------------------------
+    health = () => this.request('GET', '/health', { anonymous: true });
+    me = () => this.request('GET', '/me');
+    sites = () => this.request('GET', '/sites').then(unwrapList('sites'));
+    site = (id) => this.request('GET', `/sites/${id}`);
+    createSite = (body) => this.request('POST', '/sites', { body });
+    updateSite = (id, body) => this.request('PATCH', `/sites/${id}`, { body });
+    // ---- site configuration (0063) -----------------------------------------
+    scanSchedule = (site) => this.request('GET', `/sites/${site}/scan-schedule`);
+    updateScanSchedule = (site, body) => this.request('PATCH', `/sites/${site}/scan-schedule`, { body });
+    installChecks = (site, limit) => this.request('GET', `/sites/${site}/install-checks`, { query: { limit } }).then((r) => r.items ?? []);
+    requestInstallCheck = (site, url) => this.request('POST', `/sites/${site}/install-checks`, { body: url ? { url } : {} });
+    domains = (site) => this.request('GET', `/sites/${site}/domains`).then((r) => r.items ?? []);
+    verifyDomain = (id, method) => this.request('POST', `/domains/${id}/verify`, { body: { method } });
+    createService = (site, body) => this.request('POST', `/sites/${site}/services`, { body });
+    updateService = (id, body) => this.request('PATCH', `/services/${id}`, { body });
+    deleteService = (id) => this.request('DELETE', `/services/${id}`);
+    issuesOf = (site, status = 'open') => this.request('GET', `/sites/${site}/issues`, { query: { status } }).then((r) => r.items ?? []);
+    suppressIssue = (id, reason) => this.request('POST', `/issues/${id}/suppress`, { body: { reason } });
+    unsuppressIssue = (id) => this.request('POST', `/issues/${id}/unsuppress`, { body: {} });
+    template = (id) => this.request('GET', `/templates/${id}`);
+    createTemplate = (body) => this.request('POST', '/templates', { body });
+    updateTemplate = (id, body) => this.request('PUT', `/templates/${id}`, { body });
+    deleteTemplate = (id) => this.request('DELETE', `/templates/${id}`);
+    getDraft = (site, env) => this.request('GET', `/sites/${site}/config/draft`, { query: { env } });
+    putDraft = (site, env, config, ifMatch) => this.request('PUT', `/sites/${site}/config/draft`, { query: { env }, body: config, headers: ifMatch ? { 'If-Match': ifMatch } : undefined });
+    validate = (site, config) => this.request('POST', `/sites/${site}/config/validate`, { body: config });
+    publish = (site, body) => this.request('POST', `/sites/${site}/versions`, { body });
+    versions = (site) => this.request('GET', `/sites/${site}/versions`).then(unwrapList('versions'));
+    version = (id) => this.request('GET', `/versions/${id}`);
+    rollback = (id, env) => this.request('POST', `/versions/${id}/rollback`, { body: { env } });
+    promote = (id) => this.request('POST', `/versions/${id}/promote`, { body: {} });
+    services = (site, status) => this.request('GET', `/sites/${site}/services`, { query: { status } }).then(unwrapList('items'));
+    issues = (site) => this.request('GET', `/sites/${site}/issues`);
+    createScan = (site, body) => this.request('POST', `/sites/${site}/scans`, { body });
+    scan = (id) => this.request('GET', `/scans/${id}`);
+    findings = (id, format, tab = 'all') => this.requestText('GET', `/scans/${id}/findings`, { query: { format, tab }, headers: { Accept: '*/*' } });
+    scanDiff = (id) => this.request('GET', `/scans/${id}/diff`);
+    declaration = (site, format, lang) => this.requestText('GET', `/sites/${site}/declaration.${format}`, { query: { lang }, headers: { Accept: '*/*' } });
+    consents = (site, q) => this.request('GET', `/sites/${site}/consents`, { query: q });
+    createExport = (site, body) => this.request('POST', `/sites/${site}/exports`, { body });
+    exportJob = (id) => this.request('GET', `/exports/${id}`);
+    exportDownload = (id) => this.download(`/exports/${id}/download`);
+    tokens = () => this.request('GET', '/tokens').then(unwrapList('tokens'));
+    revokeToken = (id, note) => this.request('DELETE', `/tokens/${id}`, { body: note ? { note } : undefined });
+    // ---- phase 5 ----------------------------------------------------------
+    alerts = (q) => this.request('GET', '/alerts', { query: q }).then((v) => Array.isArray(v) ? { items: v } : { items: v.items ?? [], counts: v.counts });
+    acknowledgeAlert = (id) => this.request('POST', `/alerts/${id}/acknowledge`, { body: {} });
+    resolveAlert = (id) => this.request('POST', `/alerts/${id}/resolve`, { body: {} });
+    webhooks = (siteId) => this.request('GET', '/webhooks', { query: { site_id: siteId } }).then(unwrapList('items'));
+    createWebhook = (body) => this.request('POST', '/webhooks', { body });
+    rotateWebhook = (id) => this.request('POST', `/webhooks/${id}/rotate`, { body: {} });
+    deleteWebhook = (id) => this.request('DELETE', `/webhooks/${id}`);
+    webhookDeliveries = (id, limit) => this.request('GET', `/webhooks/${id}/deliveries`, { query: { limit } }).then(unwrapList('items'));
+    redeliverWebhook = (id, delivery) => this.request('POST', `/webhooks/${id}/deliveries/${delivery}/redeliver`, { body: {} });
+    usage = (period) => this.request('GET', '/usage', { query: { period } });
+    templates = () => this.request('GET', '/templates').then(unwrapList('items'));
+    applyTemplate = (id, body) => this.request('POST', `/templates/${id}/apply`, { body }).then(unwrapList('results'));
+    deviceCode = (body) => this.request('POST', '/device/code', { body, anonymous: true });
+    deviceToken = (device_code) => this.request('POST', '/device/token', { body: { device_code }, anonymous: true, allowStatus: [400, 401, 403, 428] });
+}
+/** Some list routes may wrap rows (`{sites:[…]}`); accept both. */
+function unwrapList(key) {
+    return (v) => {
+        if (Array.isArray(v))
+            return v;
+        if (v && typeof v === 'object') {
+            const o = v;
+            for (const k of [key, 'rows', 'data', 'items'])
+                if (Array.isArray(o[k]))
+                    return o[k];
+        }
+        return [];
+    };
+}
+export function isDeviceTokenOk(r) {
+    return typeof r.token === 'string' && r.token.length > 0;
+}

package/dist/cli/src/auth.js

@@ -0,0 +1,106 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { isDeviceTokenOk } from "./api.js";
+import { CliError } from "./errors.js";
+import { human, spinner } from "./output.js";
+import { openBrowser, sleep, pollMs } from "./util.js";
+/** `%APPDATA%/cookiecrumbs/credentials.json` on Windows, `~/.config/cookiecrumbs/credentials.json` elsewhere. */
+export function credentialsPath() {
+    if (process.env.COOKIECRUMBS_CREDENTIALS)
+        return process.env.COOKIECRUMBS_CREDENTIALS;
+    if (process.platform === 'win32') {
+        const base = process.env.APPDATA ?? join(homedir(), 'AppData', 'Roaming');
+        return join(base, 'cookiecrumbs', 'credentials.json');
+    }
+    const base = process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config');
+    return join(base, 'cookiecrumbs', 'credentials.json');
+}
+export function readCredentials() {
+    const file = credentialsPath();
+    if (!existsSync(file))
+        return null;
+    try {
+        const c = JSON.parse(readFileSync(file, 'utf8'));
+        return c && typeof c.token === 'string' ? c : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeCredentials(c) {
+    const file = credentialsPath();
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    writeFileSync(file, JSON.stringify({ ...c, saved_at: new Date().toISOString() }, null, 2) + '\n', { mode: 0o600 });
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        /* Windows ignores POSIX modes; the file sits under the user's profile */
+    }
+    return file;
+}
+export function clearCredentials() {
+    const file = credentialsPath();
+    if (!existsSync(file))
+        return false;
+    rmSync(file);
+    return true;
+}
+/** COOKIECRUMBS_TOKEN wins over the credentials file. */
+export function resolveToken() {
+    const env = process.env.COOKIECRUMBS_TOKEN?.trim();
+    if (env)
+        return { token: env, source: 'env', creds: null };
+    const creds = readCredentials();
+    if (creds)
+        return { token: creds.token, source: 'file', creds };
+    return { token: null, source: null, creds: null };
+}
+export const DEFAULT_SCOPES = ['banner:read', 'banner:write', 'banner:publish', 'scans:read', 'scans:run', 'logs:read', 'logs:export', 'sites:read', 'sites:write'];
+/** RFC 8628 device flow: print the URL + code, open the browser unless told not to, poll until a token arrives. */
+export async function deviceFlow(api, opts = {}) {
+    const code = await api.deviceCode({ scopes: opts.scopes ?? DEFAULT_SCOPES, client: api.client });
+    if (!code?.device_code || !code.user_code)
+        throw new CliError('bad_response', 'The device code response is missing device_code/user_code.', 1);
+    opts.onCode?.(code);
+    const url = code.verification_uri_complete || code.verification_uri;
+    human.note(`Open ${url}\nand confirm the code ${code.user_code}`, 'Approve this device');
+    if (opts.open !== false) {
+        if (openBrowser(url))
+            human.info('Opening your browser… (pass --no-open to skip)');
+    }
+    let interval = Math.max(1, Number(code.interval) || 5);
+    const deadline = Date.now() + Math.max(30, Number(code.expires_in) || 900) * 1000;
+    const s = spinner('Waiting for approval in the dashboard');
+    while (Date.now() < deadline) {
+        await sleep(pollMs(interval * 1000));
+        const r = await api.deviceToken(code.device_code);
+        if (isDeviceTokenOk(r)) {
+            s.stop('Approved');
+            return { token: r, code };
+        }
+        const err = r?.error ?? 'authorization_pending';
+        if (err === 'authorization_pending')
+            continue;
+        if (err === 'slow_down') {
+            interval += 5;
+            continue;
+        }
+        s.fail(err === 'access_denied' ? 'Denied in the dashboard' : `Device code ${err}`);
+        if (err === 'access_denied')
+            throw new CliError('access_denied', 'The request was denied in the dashboard.', 1);
+        if (err === 'expired_token')
+            throw new CliError('expired_token', 'The device code expired before it was approved. Run `cookiecrumbs login` again.', 1);
+        throw new CliError(err, r.error_description ?? `Device flow failed: ${err}`, 1);
+    }
+    s.fail('Timed out');
+    throw new CliError('expired_token', 'Timed out waiting for approval. Run `cookiecrumbs login` again.', 1);
+}
+export function orgLabel(org) {
+    if (!org)
+        return '—';
+    if (typeof org === 'string')
+        return org;
+    return org.slug ? `${org.name ?? org.slug} (${org.slug})` : (org.name ?? org.id);
+}