cookiecrumbs 0.2.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,190 @@
+# cookiecrumbs — the CookieCrumbs CLI
+
+Push and pull your banner configuration as code, publish versions, run hosted scans in CI, manage
+the site itself (name, retention, scan schedule, services, issues, domains, install checks,
+templates), and export consent logs, declarations and audit bundles. Talks only to the REST API v1
+(`{api}/v1/...`) with a `cc_*` token.
+
+```bash
+npm i -D cookiecrumbs          # or: npx cookiecrumbs <command>
+npx cookiecrumbs login         # device flow: approve in the dashboard
+npx cookiecrumbs init          # pick/create a site, write cookiecrumbs.config.ts + texts, print the install snippet
+npx cookiecrumbs push --note "first version"
+```
+
+Requires Node 22+.
+
+## Configuration
+
+| What | Where |
+|---|---|
+| API base | `--api <url>` or `COOKIECRUMBS_API` (default `https://api.cookiecrumbs.eu`; paths are `{base}/v1/...`) |
+| Token | `COOKIECRUMBS_TOKEN` (CI/MCP) wins, else the credentials file |
+| Credentials file | `~/.config/cookiecrumbs/credentials.json` (mode 0600) — on Windows `%APPDATA%\cookiecrumbs\credentials.json`; `{api, token, org, name, …}` |
+| Project state | `.cookiecrumbs/state.json` `{site_id, env, last_pulled_hash, last_pulled_updated_at}` plus `.cookiecrumbs/last-pulled.json` (the last synced config, used for diffs) |
+| Config file | `cookiecrumbs.config.ts` (`export default defineConfig({...})` from `@cookiecrumbs/config`) or `cookiecrumbs.config.json` |
+| Texts | `cookiecrumbs/texts/<lang>.json` — `{texts, category_texts}` per language, merged into the config on push (the config file may keep `texts: {}`) |
+| Dashboard URL | `COOKIECRUMBS_APP` (default `https://app.cookiecrumbs.eu`), used by `open` and the install snippet (`COOKIECRUMBS_RUNTIME_URL` overrides the `cc.js` location) |
+
+Every command accepts `--json` (prints exactly one JSON object to stdout, nothing else; errors become
+`{ok:false, error:{code, detail, exit, …}}`) and `--api <url>`. Exit codes: `0` ok, `1` failure,
+`2` usage, conflict or "needs a prompt". When stdin is not a terminal the CLI never prompts: it exits 2
+and names the flag to pass instead. Every request carries `X-CookieCrumbs-Client: cli/<version>`, so the
+audit trail reads "via CLI · <token name>".
+
+## Commands
+
+### Account
+
+| Command | What it does |
+|---|---|
+| `login [--token [cc_…]] [--scopes a,b] [--no-open]` | Device flow (RFC 8628): prints the URL and code, opens the browser, polls until approved; `--token` stores an existing token after checking it with `/v1/me` (reads stdin when no value is given: `echo $TOK \| cookiecrumbs login --token`). |
+| `logout` | Deletes the credentials file. |
+| `whoami` | Token name, kind, scopes, restrictions, expiry, workspace, source (env or file). |
+
+### Project
+
+| Command | What it does |
+|---|---|
+| `init [--site <id> \| --name <n> --domain <d>] [--env preview] [--format ts\|json] [--publish] [--yes]` | Detects Next.js / React / Astro / Nuxt / SvelteKit / plain from `package.json` and file hints, links or creates the site, writes the config + texts from the current draft (or the defaults), prints the install snippet with the environment's public key. `--publish` pushes straight away. Non-interactive runs need `--site` (or `--name` + `--domain`) and `--yes` to overwrite. |
+| `link [--site <id>] [--env <env>]` | Re-point the folder without touching the config. |
+| `push [--env] [--note] [--material] [--dry-run]` | Lints locally with `@cookiecrumbs/config`, prints the diff vs the last pulled config, `PUT` the draft (with `If-Match` from the last pull → exit 2 `draft_conflict` when someone else edited it), then `POST /versions`. Server lint errors (422) are printed; plan gates (402) fail with the feature name. |
+| `pull [--env] [--force]` | Three-way on hashes of the canonical JSON: local unchanged since the last pull → overwrite; remote unchanged → keep; both changed → writes `cookiecrumbs.config.remote.json` and exits 2 (`--force` takes the remote version). |
+| `diff [--env]` | Flat path diff local vs remote draft (`~ changed`, `+ added locally`, `- missing locally`). |
+| `status` | Site, environment, framework, sync state, latest versions. |
+| `open [overview\|banner\|versions\|services\|inbox\|declaration\|scans\|logs\|exports\|settings\|developers] [--no-open]` | Opens the dashboard page for the linked site. |
+
+### Versions
+
+```
+cookiecrumbs versions list [--env]
+cookiecrumbs versions show <n>
+cookiecrumbs versions rollback <n> [--env]     # publishes a new version copied from n
+cookiecrumbs versions promote <n>              # existing preview version → production
+```
+
+### Scans
+
+```
+cookiecrumbs scan [--env] [--states no_interaction,reject_all,accept_all] [--pages <n>]
+                  [--wait] [--timeout <min>] [--fail-on-unknown] [--fail-on-preconsent]
+                  [--sarif <file>] [--scan-id <id>] [--json]
+```
+
+Without `--wait` the scan is queued and its id printed (exit 0). With `--wait` (implied by `--sarif` and the
+`--fail-on-*` flags) the CLI polls `GET /v1/scans/:id` every 5 s and prints the summary; `--fail-on-unknown`
+exits 1 when `summary.unclassified > 0`, `--fail-on-preconsent` when `summary.preconsent_violations > 0`;
+`--sarif` downloads `findings?format=sarif` (SARIF 2.1.0). `--scan-id <id>` re-attaches to an existing scan
+instead of starting one (extension). `--local` prints "not yet available" and exits 2.
+
+### Logs, declaration, full export
+
+```
+cookiecrumbs logs export [--from YYYY-MM-DD] [--to …] [--env] [--format jsonl|csv] [--out <file>] [--job <id>] [--timeout <s>]
+cookiecrumbs declaration export [--format html|md|json] [--lang <lang>] [--out <file>]
+cookiecrumbs export --all [--out ./cookiecrumbs-export] [--env] [--from] [--to] [--skip-logs]
+```
+
+`logs export` creates an export job (`consent_jsonl` / `consent_csv`), waits for a **running cc-worker**
+to finish it (polling every 3 s, 10 min by default), downloads the signed file and checks the
+`X-Content-SHA256` header against the bytes. One export job per site runs at a time; `--job <id>`
+re-attaches to a queued job (extension).
+
+`export --all` writes `config.json`, `texts/<lang>.json`, `declaration.<lang>.{html,md,json}`,
+`versions.json`, `consents.jsonl`, `audit-bundle.zip` and a `README.txt` that explains the files and how to
+verify hashes, signatures and the consent hash chain (`node bundle/verify.mjs`). Files that could not be
+produced (e.g. no worker running) are listed under "Missing" and the command exits 1.
+
+### The site itself
+
+Everything the dashboard's Settings, Scans → Schedule, Services, Issues, Domains and Install pages
+can change. Every command takes `--site <id>`; without it the linked site is used.
+
+```
+cookiecrumbs sites list
+cookiecrumbs sites show [id]
+cookiecrumbs sites create --name <n> --domain <host> [--languages en,de]
+cookiecrumbs sites update [id] [--name <n>] [--retention <months>] [--public-versions-feed on|off]
+                          [--consent-cookie-name <name>|none] [--reask-months <n>|none]
+
+cookiecrumbs schedule [--site <id>]                       # the scan schedule
+cookiecrumbs schedule set [--cadence monthly|weekly|daily] [--pages <n>] [--states a,b]
+                          [--start-urls <list>|none] [--include <list>|none] [--exclude <list>|none]
+                          [--robots on|off] [--pause | --resume]
+
+cookiecrumbs services list [--status discovered|managed|ignored]
+cookiecrumbs services add <name> --category <key> [--provider] [--domain] [--hosts] [--scripts]
+                          [--cookies] [--storage] [--iframes] [--basis] [--justification]
+                          [--privacy-url] [--first-party on|off] [--status] [--description]
+cookiecrumbs services update <id> [same options] [--name]
+cookiecrumbs services remove <id> [--yes]
+
+cookiecrumbs issues list [--status open|resolved|suppressed|all]
+cookiecrumbs issues suppress <id> --reason "<why>"
+cookiecrumbs issues unsuppress <id>
+
+cookiecrumbs install status [--limit <n>]
+cookiecrumbs install check [--url <page>] [--wait] [--timeout <s>]   # --wait exits 1 when cc.js is missing
+
+cookiecrumbs domains list
+cookiecrumbs domains verify <id> [--method dns_txt|meta]              # prints the record / tag to publish
+
+cookiecrumbs templates show <id> [--config-only]
+cookiecrumbs templates save <name> [--from-site <id>] [--env production|preview] [--config <file.json>] [--id <template>]
+cookiecrumbs templates delete <id> [--yes]
+```
+
+`schedule set` and `services update` send only the options you pass. A cadence or page cap the plan
+does not allow is clamped by the server and **reported** (`clamped` in `--json`), never hidden.
+`issues suppress` requires a reason: it is kept with the issue and shown in the audit trail.
+`install check --wait` polls `GET /sites/:id/install-checks` for a result newer than the request
+(a worker must be running) and is meant as a post-deploy gate.
+
+### Tokens
+
+```
+cookiecrumbs tokens list [--all]
+cookiecrumbs tokens revoke <id> [--note <text>]
+cookiecrumbs tokens create [--scopes a,b] [--use] [--no-open]
+```
+
+There is no `POST /v1/tokens` route: `tokens create` runs the device flow and prints the new token once
+(the approver picks workspace, optional site/environment and scopes in the dashboard); `--use` also stores it
+as this machine's credentials.
+
+## CI
+
+Set `COOKIECRUMBS_TOKEN` (a machine token with the scopes you need) and commit `.cookiecrumbs/state.json`,
+or `link --site` first. Everything works without a TTY; add `--json` to parse results.
+
+```bash
+# fail the pipeline on unclassified trackers, upload SARIF
+npx cookiecrumbs scan --wait --fail-on-unknown --fail-on-preconsent --sarif results.sarif
+
+# publish the config from the repository
+npx cookiecrumbs push --env production --note "release $GITHUB_SHA"
+```
+
+GitHub Actions example: `docs/platform/ci/cookiecrumbs-scan.yml` (scheduled + after deployments, uploads the
+SARIF to Code scanning).
+
+```yaml
+- uses: actions/setup-node@v4
+  with: { node-version: 22 }
+- run: npx --yes cookiecrumbs scan --wait --fail-on-unknown --sarif results.sarif
+  env: { COOKIECRUMBS_TOKEN: ${{ secrets.COOKIECRUMBS_TOKEN }} }
+- uses: github/codeql-action/upload-sarif@v3
+  if: always()
+  with: { sarif_file: results.sarif }
+```
+
+## Development
+
+```bash
+npm run build -w cookiecrumbs     # tsc → dist/ (the config package is compiled in, dist/config/)
+npm test -w cookiecrumbs          # unit tests + end-to-end against a fake API server (test/fake-api.ts)
+node packages/cli/dist/cli/src/index.js --help
+```
+
+`COOKIECRUMBS_POLL_MS` shortens the scan/export/device polling interval (tests), `COOKIECRUMBS_CREDENTIALS`
+overrides the credentials path, `DEBUG=1` prints stack traces.

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);
+}