@consentera/cli 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+`@consentera/cli` follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] — 2026-09-22
+
+Versioned in step with `@consentera/consent-sdk` 2.0.0: both speak the U58 wire
+and the refusal of `data_principal_ref`, and a mismatched pair is the thing
+these version numbers exist to prevent.
+
+### Breaking
+
+- **`--secret <value>` is removed** from `trigger`. It is refused with an error
+  rather than ignored, because a caller who typed it believes the event was
+  signed. Use `CONSENTERA_WEBHOOK_SECRET`, `consentera login --webhook`, or
+  `--secret-file <path>`. 1.x documented the flag **in its own usage block**, so
+  the tool taught every user to put a webhook secret in their shell history.
+- **Unknown flags are refused** (exit 2) instead of silently ignored.
+  `--guardian_email` used to be dropped, creating a child's session with no
+  guardian.
+- **`CONSENTERA_API_URL` is required; there is no default target.** 1.x fell
+  back to `http://localhost:9090` — plain HTTP, carrying the secret key as a
+  Bearer header to whatever listened on a port many other tools also use. A
+  command that sends the key now exits 2 naming `CONSENTERA_API_URL` when it is
+  unset or not an absolute http(s) URL (after the key check, which stays exit 4).
+- **Exit codes are differentiated**: 1 API refusal, 2 usage, 3 network, 4 auth.
+  Everything used to be 1, so a script could not tell a typo from an outage.
+- `engines.node` is `>=20` (Node 18 reached end of life on 2025-04-30).
+- The lifecycle roads take identifiers, not `data_principal_ref` (landed in
+  `459a3967`).
+
+### Added
+
+- **`consentera login`** — reads a secret from **stdin** and stores it in the OS
+  keychain (`security` / `secret-tool`), falling back to
+  `~/.config/consentera/credentials.json` created at mode `0600`.
+- **`--json`**: one JSON document on stdout and nothing else, so the output can
+  be piped. The envelope carries `ok`, `status`, `request_id` and `data`.
+- **`--version`**. `consentera --version` used to print the whole help text and
+  exit 0.
+- **`X-Consentera-SDK: cli/<version>`** on every request.
+- **The platform's `X-Request-ID` is surfaced** on failures.
+- A test suite (`node --test`), where there was none.
+
+[2.0.0]: https://github.com/consentera-platform/consentera-sdks/releases/tag/v2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Consentera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS 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 NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# @consentera/cli
+
+The fastest way to exercise the [Consentera](https://docs.consentera.in) consent
+API and webhooks from a terminal. Zero dependencies, Node ≥ 20.
+
+```
+npm install -g @consentera/cli
+consentera --help
+```
+
+## Quickstart (5 minutes)
+
+```bash
+# 1. point it at YOUR tenant's API (required — there is no default server)
+#    and store a key — from stdin, never from a flag
+export CONSENTERA_API_URL=https://<your Consentera API host>
+consentera login              # paste a tiq_test_… key, stored in your OS keychain
+
+# 2. check the key and what mode it is in
+consentera keys check
+# { "ok": true, "mode": "test", "api": "https://<your Consentera API host>" }
+
+# 3. mint a consent session and open the hosted page it prints
+consentera sessions create \
+  --data-principal email=always.allow@test.consentera.in \
+  --notice bnb_consent_v2 \
+  --dob 1998-04-12
+
+# 4. ask the authoritative question
+consentera validate --data-principal email=always.allow@test.consentera.in \
+                    --purpose product_analytics
+
+# 5. send your local webhook endpoint a correctly-signed synthetic event
+consentera trigger consent.granted --forward-to http://localhost:4242/hooks
+```
+
+## Credentials
+
+**A secret is never a command-line argument.** There is no `--api-key` and no
+`--secret`: a value in `argv` is visible in `ps` for the life of the process,
+and lives forever in shell history and in CI logs.
+
+`consentera login` reads the secret from **stdin** and stores it in the OS
+keychain — `security` on macOS, `secret-tool` on Linux — falling back to
+`~/.config/consentera/credentials.json` at mode `0600` when no keyring tool is
+present. `consentera login --webhook` stores the webhook signing secret.
+
+Resolution order, first hit wins:
+
+1. `CONSENTERA_API_KEY` / `CONSENTERA_WEBHOOK_SECRET`
+2. the OS keychain
+3. `~/.config/consentera/credentials.json`
+
+A public site key (`tiq_pub_…`) is refused: the CLI is a server-side tool and
+the roads it calls need a secret key.
+
+## `--json`
+
+With `--json`, **stdout carries exactly one JSON document and nothing else** —
+every human note is suppressed rather than merely redirected — so it is safe to
+pipe:
+
+```bash
+consentera keys check --json | jq -r .mode
+consentera validate --json --data-principal email=x@y.in --purpose analytics | jq -r .data.decision
+```
+
+The envelope is `{ ok, status, request_id, data }`. `request_id` is the
+platform's `X-Request-ID` — quote it in a support ticket.
+
+## Exit codes
+
+| code | meaning |
+|---|---|
+| 0 | success |
+| 1 | the platform answered, and said no (4xx/5xx other than auth) |
+| 2 | the command line was wrong — unknown flag, missing argument |
+| 3 | the platform could not be reached |
+| 4 | no usable credential, or it was refused (401/403) |
+
+Unknown flags are **refused**, not ignored: `--guardian_email` (underscore) used
+to be dropped in silence, so a child's session was created with no guardian and
+the failure surfaced as a `412 GUARDIAN_REQUIRED` naming a condition rather than
+the typo. It now exits 2 and suggests `--guardian-email`.
+
+## Naming a Data Principal
+
+**One vocabulary, both roads.** `--data-principal <field>=<value>` is
+repeatable, and the field names are **your organisation's locked integration
+key** — an open, per-tenant set, so the type comes from the field name and the
+CLI does not allow-list. It sends what you give it and the SERVER answers
+`UNKNOWN_IDENTIFIER_FIELD`, naming the field and listing your key's actual
+fields, when you get one wrong. (It used to carry a hard-coded five-field set
+that rejected a legal key before the server ever saw it.)
+
+The mobile atom is **`mobile`** on `sessions create` *and* on the lifecycle
+roads (`validate`, `withdraw`). It used to be `phone` on the lifecycle roads,
+folded server-side; F015 removed the fold, so **`phone` is refused by name**.
+There is no `pan` key: it is evidence-class and can never be a scheme field.
+
+Only the wire key differs — create spells the object `data_principal` and may
+mint a person; the lifecycle roads spell it `data_principal_identifiers` and
+only resolve.
+
+`data_principal_ref` is refused outright by the API
+(`DATA_PRINCIPAL_REF_REFUSED`) with no transition period. The other refusals are
+`UNKNOWN_IDENTIFIER_FIELD`, `IDENTIFIER_REQUIRED`, `INVALID_IDENTIFIER_FORMAT`
+(a raw 12-digit Aadhaar lives here — send the linked token) and
+`SCHEME_NOT_CONFIGURED`.
+
+## Sandbox
+
+Use a `tiq_test_…` key and the magic Data Principals for deterministic runs:
+`always.allow@test.consentera.in`, `always.withdrawn@…`, `always.none@…`,
+`always.expired@…`.
+
+## Licence
+
+MIT — see [LICENSE](./LICENSE).

package/consentera.js

@@ -0,0 +1,766 @@
+#!/usr/bin/env node
+/**
+ * consentera — the Consentera developer CLI.
+ *
+ * The fastest way to exercise the consent API and webhooks from a terminal:
+ *
+ *   consentera sessions create --data-principal email=riya@example.in --notice bnb_consent_v2
+ *   consentera validate --data-principal riya@example.in --purpose product_analytics
+ *   consentera withdraw --data-principal riya@example.in --purposes product_analytics
+ *   consentera portal   --data-principal riya@example.in
+ *   consentera trigger  consent.granted --forward-to http://localhost:4242/hooks
+ *   consentera keys check
+ *
+ * Auth + target, and a secret is NEVER a command-line argument:
+ *   CONSENTERA_API_URL   your tenant's Consentera API origin — REQUIRED, no default
+ *   CONSENTERA_API_KEY   a tiq_test_* (sandbox) or tiq_live_* secret key — server-side only
+ *   or `consentera login`, which reads it from stdin into the OS keychain
+ *
+ * Zero dependencies; Node 18+.
+ */
+'use strict';
+
+const crypto = require('node:crypto');
+const http = require('node:http');
+const https = require('node:https');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { URL } = require('node:url');
+
+const SDK_VERSION = require('./package.json').version;
+
+// ─── EXIT CODES ────────────────────────────────────────────────────────────
+//
+// One code for everything was the 1.x behaviour: `die()` used 1 and
+// `printResult` used 1, so a typo in a flag, an expired key, a dropped
+// connection and a 409 from the API were indistinguishable to a caller — which
+// matters because the caller is usually a script.
+const EXIT = {
+  OK: 0,
+  API: 1,      // the platform answered, and said no
+  USAGE: 2,    // the command line was wrong
+  NETWORK: 3,  // the platform could not be reached
+  AUTH: 4,     // no usable credential, or it was refused
+};
+
+// NO DEFAULT TARGET. 1.x fell back to http://localhost:9090 — plain HTTP, to
+// whatever happens to listen on a port many other tools also use, carrying the
+// secret key as a Bearer header. The SDKs in this repository shipped built-in
+// hosts too, one of them on a domain the company does not own. A CLI holding a
+// tiq_live_ key must be told where to send it; see requireApiUrl().
+const API_URL = (process.env.CONSENTERA_API_URL || '').trim().replace(/\/+$/, '');
+
+// ─── CREDENTIALS ───────────────────────────────────────────────────────────
+//
+// NEVER FROM argv. 1.x documented `--secret whsec_xxx` in its own usage block,
+// which puts the value in `ps`, in shell history, and in any CI log that echoes
+// the command. There is no `--api-key` flag and there is no `--secret` flag.
+//
+// Resolution order, first hit wins:
+//   1. the environment            CONSENTERA_API_KEY / CONSENTERA_WEBHOOK_SECRET
+//   2. the OS keychain            `security` (macOS) or `secret-tool` (Linux),
+//                                 used only if the binary is present
+//   3. ~/.config/consentera/credentials.json, which `consentera login` writes
+//      with mode 0600
+//
+// Zero dependencies is a deliberate property of this CLI, so the keychain is
+// reached by shelling out to the tool the OS already ships rather than by
+// adding a native module.
+const CONFIG_DIR = path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'consentera');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'credentials.json');
+
+function keychainGet(account) {
+  try {
+    if (process.platform === 'darwin') {
+      return execFileSync('security', ['find-generic-password', '-s', 'consentera', '-a', account, '-w'], {
+        encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+    }
+    if (process.platform === 'linux') {
+      return execFileSync('secret-tool', ['lookup', 'service', 'consentera', 'account', account], {
+        encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+    }
+  } catch { /* no tool, no entry, or no keyring daemon — fall through */ }
+  return '';
+}
+
+function keychainSet(account, secret) {
+  try {
+    if (process.platform === 'darwin') {
+      execFileSync('security', ['add-generic-password', '-U', '-s', 'consentera', '-a', account, '-w', secret], {
+        stdio: 'ignore',
+      });
+      return true;
+    }
+    if (process.platform === 'linux') {
+      execFileSync('secret-tool', ['store', '--label=consentera', 'service', 'consentera', 'account', account], {
+        input: secret, stdio: ['pipe', 'ignore', 'ignore'],
+      });
+      return true;
+    }
+  } catch { /* fall back to the file */ }
+  return false;
+}
+
+function fileCreds() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function resolveCredential(account, envName) {
+  const fromEnv = process.env[envName];
+  if (fromEnv) return fromEnv.trim();
+  const fromKeychain = keychainGet(account);
+  if (fromKeychain) return fromKeychain;
+  const v = fileCreds()[account];
+  return typeof v === 'string' ? v.trim() : '';
+}
+
+const API_KEY = resolveCredential('api_key', 'CONSENTERA_API_KEY');
+
+// ---------- tiny arg parser ----------
+//
+// A REPEATED FLAG COLLECTS INTO AN ARRAY rather than overwriting. U58 needs it:
+// `--data-principal customer_id=C1 --data-principal mobile=+91…` is ONE
+// identifier object with two fields, and last-one-wins would have sent half of
+// it — a request the API then refuses for not meeting the key's floor, naming a
+// condition rather than the flag that was dropped. Single use is unchanged: a
+// flag given once is still a plain string, so every other command reads exactly
+// what it read before.
+function parseArgs(argv) {
+  const args = { _: [] };
+  const put = (key, value) => {
+    if (!(key in args)) { args[key] = value; return; }
+    if (Array.isArray(args[key])) { args[key].push(value); return; }
+    args[key] = [args[key], value];
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) { put(key, true); }
+      else { put(key, next); i++; }
+    } else args._.push(a);
+  }
+  return args;
+}
+
+// Set from --json. In JSON mode stdout carries exactly one JSON document and
+// nothing else, so `consentera … --json | jq` is safe; the human commentary
+// that normally goes to stderr is suppressed entirely.
+let JSON_MODE = false;
+
+function note(msg) { if (!JSON_MODE) console.error(msg); }
+
+function die(msg, code = EXIT.USAGE) {
+  if (JSON_MODE) console.log(JSON.stringify({ ok: false, error: String(msg), exit_code: code }, null, 2));
+  else console.error(`error: ${msg}`);
+  process.exit(code);
+}
+
+/** Every command that sends the key also needs a target; refused by name. */
+function requireApiUrl() {
+  if (!API_URL) {
+    die(
+      'CONSENTERA_API_URL is not set. There is no default server: set it to your Consentera API ' +
+      'origin, e.g. `export CONSENTERA_API_URL=https://<your Consentera API host>`.',
+      EXIT.USAGE
+    );
+  }
+  if (!/^https?:\/\/[^\s/?#]+/i.test(API_URL)) {
+    die('CONSENTERA_API_URL must be an absolute http(s) URL (it is the origin the key is sent to).', EXIT.USAGE);
+  }
+}
+
+function requireKey() {
+  if (!API_KEY) {
+    die(
+      'no API key. Set CONSENTERA_API_KEY, or run `consentera login` (which reads the key from ' +
+      'stdin and stores it in your OS keychain, or in ~/.config/consentera/credentials.json at ' +
+      'mode 0600). There is deliberately no --api-key flag: a secret on the command line is in ' +
+      'ps, in shell history and in CI logs.',
+      EXIT.AUTH
+    );
+  }
+  if (API_KEY.startsWith('tiq_pub_')) {
+    die('that is a public site key; the CLI needs a secret key (tiq_test_* or tiq_live_*).', EXIT.AUTH);
+  }
+  // The key is checked first (exit 4), then where it would go (exit 2).
+  requireApiUrl();
+}
+
+function modeBanner() {
+  if (API_KEY.startsWith('tiq_test_')) return 'sandbox (tiq_test_)';
+  if (API_KEY.startsWith('tiq_live_')) return 'LIVE (tiq_live_)';
+  return 'unknown key type';
+}
+
+// ---------- HTTP ----------
+function request(method, path, body, extraHeaders = {}, rawUrl = null) {
+  const url = new URL(rawUrl || API_URL + path);
+  const payload = body === undefined ? null : Buffer.from(JSON.stringify(body));
+  const lib = url.protocol === 'https:' ? https : http;
+  // THE PAIR, agreed across all six surfaces (coordinator ruling 2026-09-22):
+  //   User-Agent:       ConsenteraSDK/<version> (<platform>; <runtime>)
+  //   X-Consentera-SDK: <surface>/<version>
+  // `ConsenteraSDK/<version>` is the form the platform's audit pipeline already
+  // parses (core/audit/user_agent_coarsening_test.go:39-40). The CLI sends BOTH
+  // because User-Agent is ours to set here; the browser SDK sends only the
+  // second, because User-Agent is a forbidden fetch header in a browser.
+  const headers = {
+    Accept: 'application/json',
+    'User-Agent': `ConsenteraSDK/${SDK_VERSION} (cli; node ${process.versions.node})`,
+    'X-Consentera-SDK': `cli/${SDK_VERSION}`,
+    ...extraHeaders,
+  };
+  if (payload) { headers['Content-Type'] = 'application/json'; headers['Content-Length'] = payload.length; }
+  if (!rawUrl && API_KEY) headers.Authorization = `Bearer ${API_KEY}`;
+  return new Promise((resolve, reject) => {
+    const req = lib.request(url, { method, headers, timeout: 30000 }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        const text = Buffer.concat(chunks).toString('utf8');
+        let json = null;
+        try { json = JSON.parse(text); } catch { /* leave as text */ }
+        // The platform sets X-Request-ID and exposes it; it is the first thing
+        // support asks for, and 1.x read no response header at all.
+        resolve({ status: res.statusCode, json, text, requestId: res.headers['x-request-id'] });
+      });
+    });
+    req.on('timeout', () => { req.destroy(new Error('request timed out after 30s')); });
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+function printResult(res) {
+  const ok = res.status >= 200 && res.status < 300;
+  if (JSON_MODE) {
+    console.log(JSON.stringify({
+      ok,
+      status: res.status,
+      request_id: res.requestId || null,
+      data: res.json !== null ? res.json : res.text,
+    }, null, 2));
+  } else {
+    console.log(res.json !== null ? JSON.stringify(res.json, null, 2) : res.text);
+    if (!ok && res.requestId) note(`# request id: ${res.requestId}`);
+  }
+  if (!ok) process.exit(res.status === 401 || res.status === 403 ? EXIT.AUTH : EXIT.API);
+}
+
+/** A value that must never be echoed. */
+function maskSecret(v) {
+  if (!v) return '';
+  return v.length <= 12 ? '***' : `${v.slice(0, 9)}…${v.slice(-2)}`;
+}
+
+// ---------- commands ----------
+/**
+ * POST /api/v1/public/consent/sessions.
+ *
+ * EVERY KEY BUILT HERE IS ONE THE API DECODES. The handler decodes with a plain
+ * JSON decoder and no DisallowUnknownFields, so a key it does not know is
+ * dropped in silence and the call still returns 200 — an invented field never
+ * happens and never says so. Check a name against the server's request struct
+ * before adding it here.
+ *
+ * ─── THIS IS THE U58 WIRE, AND THERE IS NO OVERLAP WINDOW ──────────────────
+ *
+ * `--data-principal <field>=<value>` (repeatable) replaces
+ * `--data-principal <ref>` + `--data-principal-type <type>`: the identifiers
+ * are keyed BY THE FIELD NAMES OF THE ORGANISATION'S LOCKED INTEGRATION KEY,
+ * and THE TYPE COMES FROM THE FIELD NAME. A field outside the key is refused
+ * 400 UNKNOWN_IDENTIFIER_FIELD and the message LISTS the allowed fields — this
+ * CLI does not know the key and deliberately does not guess at it, because a
+ * guess could only turn that message into silence.
+ *
+ * The bare form `--data-principal riya@example.in` is still accepted and is
+ * REFUSED HERE, with the reason, rather than sent: it has no field name, so the
+ * API would drop the identifier in silence and then refuse the request for
+ * carrying none — a 400 naming a condition instead of the mistake.
+ */
+
+/**
+ * Parse repeatable `--data-principal field=value` into the U58 `data_principal`
+ * object. A bare value (no `=`) is a wire error we can catch here, so we do.
+ */
+function parseDataPrincipal(raw) {
+  if (raw === undefined) return undefined;
+  const items = Array.isArray(raw) ? raw : [raw];
+  const out = {};
+  for (const item of items) {
+    if (typeof item !== 'string' || !item.includes('=')) {
+      die(`--data-principal takes field=value (U58), not a bare identifier: got '${item}'.\n` +
+          `  The field name IS the type, and it must be one of YOUR organisation's locked\n` +
+          `  integration-key fields — for example --data-principal email=riya@example.in\n` +
+          `  or --data-principal customer_id=CUST-90210 --data-principal mobile=+919876500000.`);
+    }
+    const i = item.indexOf('=');
+    const field = item.slice(0, i).trim();
+    const value = item.slice(i + 1);
+    if (!field) die(`--data-principal: empty field name in '${item}'`);
+    out[field] = value;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+async function cmdSessionsCreate(args) {
+  requireKey();
+  const notice = args.notice || die('--notice <internal_name> is required');
+  const principalId = args['data-principal-id'];
+  const dataPrincipal = parseDataPrincipal(args['data-principal']);
+  if (!dataPrincipal && !principalId) {
+    die('send --data-principal <field>=<value> (repeatable), or --data-principal-id <uuid>; ' +
+        "the API refuses a session that names neither");
+  }
+  if (args['data-principal-type']) {
+    die('--data-principal-type is gone (U58): the type comes from the field name.\n' +
+        `  Send --data-principal ${args['data-principal-type']}=<value> instead.`);
+  }
+  const body = {
+    notice_internal_name: notice,
+    ui_mode: args['ui-mode'] || 'redirect',
+    callback_url: args.callback || 'https://example.invalid/consent/done',
+    session_ref: args['session-ref'] || `cli-${Date.now()}`,
+  };
+  if (dataPrincipal) body.data_principal = dataPrincipal;
+  if (principalId) body.data_principal_id = principalId;
+  // THE ONE AGE SIGNAL, AND IT IS A DATE. Age is server-authoritative: the date
+  // is re-read every time it is used, so a person graduates at eighteen without
+  // anyone updating a flag. Omit it and the person's age is UNKNOWN — the
+  // session is still created, and purposes restricted for children are then
+  // refused. If the date IS a child's, send --guardian-email or --guardian-phone
+  // as well, or the call is refused 412 GUARDIAN_REQUIRED.
+  if (args.dob) body.age = { date_of_birth: args.dob };
+  // ONE language field, replacing locale_pref / notice_language /
+  // template_language together. Goes AHEAD of the tenant's own default in the
+  // server's fallback chain, so send it only when one was actually asked for.
+  if (args.language || args.locale) body.language = args.language || args.locale;
+  if (args['notice-version']) body.notice_version_number = Number(args['notice-version']);
+  // The guardian channel — top level, never inside data_principal, which holds
+  // the identifiers of the person the consent is ABOUT. Either, not both.
+  if (args['guardian-email'] && args['guardian-phone']) {
+    die('send --guardian-email OR --guardian-phone, not both: one invitation goes to one ' +
+        'address, and two addresses name two people with nothing saying which is the guardian');
+  }
+  if (args['guardian-email']) body.guardian_email = args['guardian-email'];
+  if (args['guardian-phone']) body.guardian_phone = args['guardian-phone'];
+  if (args['guardian-relationship']) body.guardian_relationship = args['guardian-relationship'];
+  note(`# mode: ${modeBanner()} → POST ${API_URL}/api/v1/public/consent/sessions`);
+  const res = await request('POST', '/api/v1/public/consent/sessions', body);
+  printResult(res);
+  if (res.json && res.json.consent_url) {
+    note(`\n# open this in a browser to complete consent:\n# ${res.json.consent_url}`);
+  }
+}
+
+/**
+ * ONE FLAG, ONE VOCABULARY — the identifier fields are the tenant's own locked
+ * integration key, on every road (F015).
+ *
+ *   session create   data_principal: {<field>: <value>, …}
+ *                    an OPEN map keyed by the tenant's LOCKED integration key
+ *   lifecycle roads  data_principal_identifiers: {<field>: <value>, …}
+ *                    THE SAME open scheme-keyed map — only the wire KEY differs,
+ *                    because create MAY MINT a person and this one resolves only
+ *   portal-sessions  data_principal_ref + data_principal_ref_type — a DIFFERENT
+ *                    module (rights/principal), untouched by the consent
+ *                    ruling, and it still requires the pair
+ *
+ * `--data-principal field=value` is uniform across all three.
+ *
+ * THE CLI DOES NOT ALLOW-LIST. The admissible fields are a PER-TENANT fact this
+ * CLI cannot know (F015 deleted the closed five-field vocabulary — `phone` and
+ * `pan` among them; the mobile atom is `mobile` and `pan` can never be a key
+ * field). Whatever field=value you type is sent as-is, and the SERVER answers
+ * UNKNOWN_IDENTIFIER_FIELD — naming the field and listing the key's actual
+ * fields — when it is wrong. Guessing here would only hide that refusal.
+ */
+function lifecycleIdentifiers(raw) {
+  return parseDataPrincipal(raw);
+}
+
+/** The person-naming half of a lifecycle body: the id, or the identifiers. */
+function lifecyclePrincipalBody(args, road) {
+  const id = args['data-principal-id'];
+  const ids = lifecycleIdentifiers(args['data-principal']);
+  if (id && ids) {
+    die('send --data-principal-id OR --data-principal field=value, not both: the API refuses a ' +
+        'request whose fields could name two different people');
+  }
+  if (id) return { data_principal_id: id };
+  if (ids) return { data_principal_identifiers: ids };
+  die(`${road} needs --data-principal-id <uuid>, or --data-principal field=value ` +
+      `where field is one of your organisation's locked integration-key fields.\n` +
+      `  data_principal_ref is REFUSED by the API outright (DATA_PRINCIPAL_REF_REFUSED) — ` +
+      `owner ruling 2026-09-21, no transition period.`);
+}
+
+async function cmdValidate(args) {
+  requireKey();
+  const purpose = args.purpose || die('--purpose <code> is required');
+  const who = lifecyclePrincipalBody(args, 'validate');
+  note(`# mode: ${modeBanner()}`);
+  const res = await request('POST', '/api/v1/public/consent/validate', {
+    ...who, purpose_code: purpose,
+  });
+  printResult(res);
+}
+
+async function cmdWithdraw(args) {
+  requireKey();
+  const purposes = (args.purposes || die('--purposes <code,code> is required')).split(',').map(s => s.trim()).filter(Boolean);
+  const who = lifecyclePrincipalBody(args, 'withdraw');
+  note(`# mode: ${modeBanner()}`);
+  const res = await request('POST', '/api/v1/public/consent/withdraw', {
+    ...who, purposes,
+  });
+  printResult(res);
+}
+
+async function cmdPortal(args) {
+  requireKey();
+  // THE PORTAL ROAD IS NOT A CONSENT LIFECYCLE ROAD. It lives in
+  // rights/principal (portal_session_handlers.go), the 2026-09-21 ruling does
+  // not reach it, and it still REQUIRES data_principal_ref plus its declared
+  // type — so this is the one command that must keep sending the old pair.
+  // A sweep that "fixed" it would have broken a working endpoint.
+  const dp = parseDataPrincipal(args['data-principal']);
+  if (!dp) die('portal needs --data-principal field=value, e.g. --data-principal email=riya@example.in');
+  const fields = Object.keys(dp);
+  if (fields.length !== 1) {
+    die('portal takes exactly ONE identifier: it mints an SSO link for one person, ' +
+        `and ${fields.length} were given (${fields.join(', ')})`);
+  }
+  const refType = fields[0];
+  note(`# mode: ${modeBanner()}`);
+  const res = await request('POST', '/api/v1/public/consent/portal-sessions', {
+    data_principal_ref: dp[refType], data_principal_ref_type: refType,
+  });
+  printResult(res);
+  if (res.json && res.json.portal_url) {
+    note(`\n# single-use portal SSO link (expires in ${res.json.expires_in_seconds}s) — open it now:\n# ${res.json.portal_url}`);
+  }
+}
+
+async function cmdKeysCheck() {
+  requireKey();
+  note(`# mode: ${modeBanner()} → GET ${API_URL}/api/v1/public/df/purposes`);
+  const res = await request('GET', '/api/v1/public/df/purposes?limit=1');
+  if (res.status === 200) {
+    console.log(JSON.stringify({ ok: true, mode: API_KEY.startsWith('tiq_test_') ? 'test' : 'live', api: API_URL }, null, 2));
+  } else printResult(res);
+}
+
+// Sample payloads mirror the real delivery worker's envelope for each event.
+//
+// TRANSCRIBED FROM THE DISPATCH SITES, because they had drifted from all three
+// and this command exists so a receiver can be built against it:
+//
+//   consent.granted   consent/submit_evidence.go:1741-1745
+//                     session_id, consent_artifact_id, data_principal_id
+//   consent.withdrawn consent/engine.go:963-971
+//   consent.expired   (same site; the event name is the only difference)
+//                     data_principal_id, artifact_id, purpose_ids[], source
+//
+// WHAT WAS WRONG, and why it mattered: every sample named the person with
+// `data_principal_ref` and carried `purpose_code` / `decision` / `reason` /
+// `expired_at`. The platform emits NONE of those. A receiver written against
+// this command keyed on fields that never arrive, and — because a webhook
+// receiver has no schema to refuse them — it would have read `undefined` in
+// production and blamed the delivery.
+//
+// NOTE THE ARTIFACT KEY IS NOT THE SAME ON BOTH EVENTS: granted sends
+// `consent_artifact_id`, withdrawn/expired send `artifact_id`. That asymmetry
+// is the platform's, faithfully reproduced here rather than smoothed over —
+// smoothing it would hide it from the one place an integrator would notice.
+const TRIGGER_SAMPLES = {
+  'consent.granted': {
+    session_id: '00000000-0000-4000-8000-000000000010',
+    consent_artifact_id: '00000000-0000-4000-8000-000000000001',
+    data_principal_id: '00000000-0000-4000-8000-000000000002',
+  },
+  'consent.withdrawn': {
+    data_principal_id: '00000000-0000-4000-8000-000000000002',
+    artifact_id: '00000000-0000-4000-8000-000000000001',
+    purpose_ids: ['00000000-0000-4000-8000-000000000003'],
+    source: 'principal_withdrawal',
+  },
+  'consent.expired': {
+    data_principal_id: '00000000-0000-4000-8000-000000000002',
+    artifact_id: '00000000-0000-4000-8000-000000000001',
+    purpose_ids: ['00000000-0000-4000-8000-000000000003'],
+    source: 'expiry_sweep',
+  },
+};
+
+async function cmdTrigger(args) {
+  const event = args._[1] || die(`trigger needs an event: ${Object.keys(TRIGGER_SAMPLES).join(' | ')}`);
+  if (!TRIGGER_SAMPLES[event]) die(`unknown event "${event}". Available: ${Object.keys(TRIGGER_SAMPLES).join(', ')}`);
+  const forwardTo = args['forward-to'] || die('--forward-to <url> is required (your local webhook endpoint)');
+  // `--secret` is refused in checkFlags(), which every command passes through —
+  // ONE implementation of that refusal, so the message cannot drift between
+  // here and there.
+  let secret = resolveCredential('webhook_secret', 'CONSENTERA_WEBHOOK_SECRET');
+  if (args['secret-file']) {
+    try {
+      secret = fs.readFileSync(String(args['secret-file']), 'utf8').trim();
+    } catch (e) {
+      die(`--secret-file: ${e.message}`, EXIT.USAGE);
+    }
+  }
+
+  const notificationId = crypto.randomUUID();
+  const body = Buffer.from(JSON.stringify({
+    event,
+    notification_id: notificationId,
+    occurred_at: new Date().toISOString(),
+    data: TRIGGER_SAMPLES[event],
+    livemode: false, // trigger always sends synthetic sandbox-shaped events
+  }));
+
+  // Sign exactly the way the server does: hex(HMAC_SHA256(secret, ts + "." + rawBody))
+  const ts = String(Math.floor(Date.now() / 1000));
+  const headers = {
+    'Content-Type': 'application/json',
+    'X-ConsentEra-Event': event,
+    'X-ConsentEra-Timestamp': ts,
+    'X-ConsentEra-Notification-ID': notificationId,
+  };
+  if (secret) {
+    headers['X-ConsentEra-Signature'] =
+      crypto.createHmac('sha256', secret).update(ts + '.').update(body).digest('hex');
+  } else {
+    note('# note: no webhook secret configured — sending UNSIGNED. Set CONSENTERA_WEBHOOK_SECRET ' +
+         'or run \'consentera login --webhook\', so what you test is what production sends.');
+  }
+
+  note(`# trigger ${event} → ${forwardTo} (signed: ${Boolean(secret)})`);
+  const res = await new Promise((resolve, reject) => {
+    const url = new URL(forwardTo);
+    const lib = url.protocol === 'https:' ? https : http;
+    const req = lib.request(url, { method: 'POST', headers: { ...headers, 'Content-Length': body.length }, timeout: 15000 }, (r) => {
+      const chunks = [];
+      r.on('data', (c) => chunks.push(c));
+      r.on('end', () => resolve({ status: r.statusCode, text: Buffer.concat(chunks).toString('utf8') }));
+    });
+    req.on('timeout', () => req.destroy(new Error('endpoint timed out after 15s')));
+    req.on('error', reject);
+    req.write(body); req.end();
+  });
+  console.log(JSON.stringify({ delivered: true, endpoint_status: res.status, notification_id: notificationId, signed: Boolean(secret) }, null, 2));
+  if (res.status < 200 || res.status >= 300) {
+    note(`# endpoint answered ${res.status} — a production delivery would be retried`);
+    process.exit(EXIT.API);
+  }
+}
+
+/**
+ * `consentera login [--webhook]` — read a secret from STDIN and store it.
+ *
+ * From stdin and nowhere else. A flag value is visible in `ps` for the life of
+ * the process and lives forever in shell history; an environment variable is
+ * inherited by every child. Stdin is read once and not retained.
+ */
+async function cmdLogin(args) {
+  const isWebhook = Boolean(args.webhook);
+  const account = isWebhook ? 'webhook_secret' : 'api_key';
+  const label = isWebhook ? 'webhook signing secret (whsec_…)' : 'secret API key (tiq_test_… or tiq_live_…)';
+
+  note(`# paste your ${label} and press enter (input is not echoed to the terminal by this CLI)`);
+  const secret = await new Promise((resolve) => {
+    let buf = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (c) => { buf += c; });
+    process.stdin.on('end', () => resolve(buf.trim()));
+  });
+  if (!secret) die('nothing was read from stdin', EXIT.USAGE);
+  if (!isWebhook && secret.startsWith('tiq_pub_')) {
+    die('that is a public site key; the CLI needs a secret key (tiq_test_* or tiq_live_*).', EXIT.AUTH);
+  }
+
+  let where;
+  if (keychainSet(account, secret)) {
+    where = process.platform === 'darwin' ? 'macOS keychain' : 'the OS keyring';
+  } else {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    const creds = fileCreds();
+    creds[account] = secret;
+    // 0600 BEFORE the write, not after: a file created 0644 and chmod'ed
+    // afterwards is world-readable for the interval in between.
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(creds, null, 2) + '\n', { mode: 0o600 });
+    fs.chmodSync(CONFIG_FILE, 0o600);
+    where = CONFIG_FILE;
+  }
+
+  const payload = { ok: true, stored: account, location: where, value: maskSecret(secret) };
+  if (JSON_MODE) console.log(JSON.stringify(payload, null, 2));
+  else console.log(`stored ${account} in ${where} (${maskSecret(secret)})`);
+}
+
+const HELP = `consentera — Consentera developer CLI
+
+USAGE
+  consentera <command> [flags]
+
+GLOBAL FLAGS
+  --json                                 one JSON document on stdout and nothing else; the
+                                         human commentary that normally goes to stderr is
+                                         suppressed. Safe to pipe into jq.
+  --version                              print the CLI version
+  --help                                 this text
+
+EXIT CODES
+  0 success · 1 the platform answered and said no · 2 the command line was wrong
+  3 the platform could not be reached · 4 no usable credential, or it was refused
+
+COMMANDS
+  login [--webhook]                      read a secret from STDIN and store it in your OS
+                                         keychain (macOS 'security', Linux 'secret-tool') or,
+                                         failing that, ~/.config/consentera/credentials.json at
+                                         mode 0600. --webhook stores the webhook signing secret
+                                         instead of the API key. There is deliberately NO
+                                         --api-key and NO --secret flag: a secret on the command
+                                         line is in ps, in shell history and in CI logs.
+  keys check                             verify the resolved API key and report its mode
+  sessions create --data-principal <field>=<value> --notice <name>
+                  [--data-principal <field>=<value> ...] [--data-principal-id <uuid>]
+                  [--dob YYYY-MM-DD] [--language <code>]
+                  [--guardian-email <addr> | --guardian-phone <num>]
+                  [--guardian-relationship <what>]
+                  [--notice-version <n>] [--callback <url>] [--ui-mode redirect]
+                                         mint a consent session; prints the hosted consent_url.
+                                         --data-principal is FIELD=VALUE and repeatable: the
+                                         field names are YOUR organisation's locked
+                                         integration-key fields, and THE TYPE COMES FROM THE
+                                         FIELD NAME (U58). A field outside the key is refused
+                                         400 UNKNOWN_IDENTIFIER_FIELD and the message lists
+                                         the allowed fields; too few is 400
+                                         IDENTIFIER_REQUIRED. --data-principal-type is GONE.
+                                         --data-principal-id may be sent instead of, or
+                                         alongside, --data-principal; sent together they must
+                                         agree (409 IDENTITY_MISMATCH), and a session naming
+                                         neither is refused. --language goes AHEAD of the
+                                         tenant's default language, so send it only when one
+                                         was asked for; it replaces --locale, notice_language
+                                         and template_language together. --dob is YYYY-MM-DD
+                                         and is the one age signal; without it the person's
+                                         age is unknown and purposes restricted for children
+                                         are refused. If --dob is a CHILD's, send
+                                         --guardian-email or --guardian-phone (either, not
+                                         both) or the call is refused 412 GUARDIAN_REQUIRED.
+  validate  --data-principal <field>=<value> --purpose <code>
+            | --data-principal-id <uuid> --purpose <code>
+                                         authoritative ALLOW/DENY decision check.
+                                         field is one of your organisation's locked
+                                         integration-key fields (the same vocabulary
+                                         'sessions create' uses; the mobile atom is
+                                         'mobile', and a field outside the key is
+                                         answered UNKNOWN_IDENTIFIER_FIELD by the
+                                         server). data_principal_ref is refused
+                                         outright (DATA_PRINCIPAL_REF_REFUSED).
+  withdraw  --data-principal <field>=<value> --purposes <code,code>
+            | --data-principal-id <uuid> --purposes <code,code>
+                                         withdraw consent for that person
+  portal    --data-principal <field>=<value>    mint a single-use DP-portal SSO link.
+                                         Exactly ONE identifier; this road is
+                                         rights/principal's and still sends the
+                                         data_principal_ref pair, deliberately.
+  trigger <event> --forward-to <url> [--secret-file <path>]
+                                         POST a synthetic, correctly-signed webhook to your
+                                         local endpoint (events: consent.granted |
+                                         consent.withdrawn | consent.expired)
+
+ENVIRONMENT
+  CONSENTERA_API_URL      your Consentera API origin — REQUIRED, there is no default
+  CONSENTERA_API_KEY      tiq_test_* (sandbox) or tiq_live_* secret key
+  CONSENTERA_WEBHOOK_SECRET  the webhook signing secret for 'trigger'
+
+  Credentials resolve environment -> OS keychain -> ~/.config/consentera/credentials.json,
+  first hit wins.
+
+SANDBOX
+  Use a tiq_test_* key and the magic data principals (always.allow@test.consentera.in,
+  always.withdrawn@…, always.none@…, always.expired@…) for deterministic runs, e.g.
+  --data-principal email=always.allow@test.consentera.in
+`;
+
+// Every flag the CLI understands. A flag outside this set is REFUSED, not
+// ignored: `--guardian_email` (underscore) used to be dropped in silence, so a
+// child's session was created with no guardian and the failure surfaced as a
+// 412 GUARDIAN_REQUIRED naming a condition rather than the typo.
+const KNOWN_FLAGS = new Set([
+  'help', 'version', 'json',
+  'notice', 'notice-version', 'data-principal', 'data-principal-id', 'data-principal-type',
+  'dob', 'language', 'locale', 'callback', 'ui-mode', 'session-ref',
+  'guardian-email', 'guardian-phone', 'guardian-relationship',
+  'purpose', 'purposes', 'reason',
+  'forward-to', 'secret-file', 'webhook',
+]);
+
+function checkFlags(args) {
+  // `--secret` is REMOVED, not unknown, and the difference matters to whoever
+  // typed it: an "unknown flag" reads as a typo, and they would try again with
+  // a different spelling of the same mistake.
+  if ('secret' in args) {
+    die(
+      '--secret <value> is gone: a webhook secret on the command line lands in ps, in shell ' +
+      'history and in CI logs. Use CONSENTERA_WEBHOOK_SECRET, `consentera login --webhook` ' +
+      '(reads it from stdin), or --secret-file <path>.',
+      EXIT.USAGE
+    );
+  }
+  const unknown = Object.keys(args).filter((k) => k !== '_' && !KNOWN_FLAGS.has(k));
+  if (unknown.length) {
+    const near = (bad) => {
+      const alt = bad.replace(/_/g, '-');
+      return KNOWN_FLAGS.has(alt) ? ` (did you mean --${alt}?)` : '';
+    };
+    die(`unknown flag${unknown.length > 1 ? 's' : ''}: ${unknown.map((u) => `--${u}${near(u)}`).join(', ')}`, EXIT.USAGE);
+  }
+}
+
+(async () => {
+  const args = parseArgs(process.argv.slice(2));
+  JSON_MODE = Boolean(args.json);
+  const cmd = args._[0];
+
+  if (args.version) {
+    if (JSON_MODE) console.log(JSON.stringify({ name: '@consentera/cli', version: SDK_VERSION }, null, 2));
+    else console.log(SDK_VERSION);
+    process.exit(EXIT.OK);
+  }
+
+  try {
+    if (!cmd || cmd === 'help' || args.help) { console.log(HELP); process.exit(EXIT.OK); }
+    checkFlags(args);
+    if (cmd === 'login') await cmdLogin(args);
+    else if (cmd === 'keys' && args._[1] === 'check') await cmdKeysCheck();
+    else if (cmd === 'sessions' && args._[1] === 'create') await cmdSessionsCreate(args);
+    else if (cmd === 'validate') await cmdValidate(args);
+    else if (cmd === 'withdraw') await cmdWithdraw(args);
+    else if (cmd === 'portal') await cmdPortal(args);
+    else if (cmd === 'trigger') await cmdTrigger(args);
+    else {
+      note(`unknown command "${cmd}"`);
+      if (!JSON_MODE) console.log(HELP);
+      die(`unknown command "${cmd}"`, EXIT.USAGE);
+    }
+  } catch (e) {
+    // A connection that never reached the platform is not the same failure as
+    // one the platform refused, and a script needs to tell them apart.
+    const transport = e && (e.code === 'ECONNREFUSED' || e.code === 'ENOTFOUND' || e.code === 'ETIMEDOUT' ||
+      e.code === 'ECONNRESET' || /timed out/.test(String(e.message)));
+    die(e.message || String(e), transport ? EXIT.NETWORK : EXIT.API);
+  }
+})();

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@consentera/cli",
+  "version": "2.0.0",
+  "description": "Consentera developer CLI \u2014 exercise the consent API, mint sessions/portal links, and test webhooks with correctly-signed synthetic events.",
+  "bin": {
+    "consentera": "consentera.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/consentera-platform/consentera-sdks.git",
+    "directory": "cli"
+  },
+  "keywords": [
+    "consentera",
+    "consent",
+    "dpdp",
+    "cli",
+    "webhooks"
+  ],
+  "files": [
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "consentera.js"
+  ],
+  "homepage": "https://docs.consentera.in",
+  "bugs": {
+    "url": "https://github.com/consentera-platform/consentera-sdks/issues"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "lint": "node --check consentera.js",
+    "typecheck": "node --check consentera.js",
+    "verify:pack": "bash ../scripts/verify-pack.sh cli",
+    "prepublishOnly": "npm test && npm run verify:pack"
+  }
+}