totemlayer 0.1.0

package/LICENSE.md

@@ -0,0 +1,17 @@
+# TotemLayer CLI Use License 1.0
+
+Copyright (c) 2026 TotemLayer. All rights reserved.
+
+Permission is granted, without charge, to any person or organization to download, install, make
+internal copies of, and use unmodified copies of the TotemLayer CLI, including for commercial use,
+solely to connect to and interoperate with TotemLayer-hosted or authorized TotemLayer-compatible
+services.
+
+This permission does not include the right to modify, create derivative works from, publicly
+redistribute, sublicense, or sell the CLI. It does not grant rights to TotemLayer server software,
+services, documentation, or trademarks. Separate terms may govern a hosted TotemLayer service.
+
+THE CLI 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, TITLE, AND
+NONINFRINGEMENT. TO THE MAXIMUM EXTENT PERMITTED BY LAW, TOTEMLAYER WILL NOT BE LIABLE FOR ANY
+CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM OR RELATED TO THE CLI OR ITS USE.

package/README.md

@@ -0,0 +1,159 @@
+# TotemLayer CLI
+
+Install the cross-platform terminal client for TotemLayer agent identity and
+action-level authorization. The package contains only the dependency-free CLI;
+it does not include the TotemLayer web application or server source.
+
+## Install
+
+Node.js 22.14 or newer is required.
+
+```bash
+npm install --global totemlayer
+totem --help
+```
+
+For a one-off run without a global install:
+
+```bash
+npx --yes totemlayer --help
+```
+
+The installed client works on macOS, Linux, and Windows. Applications written
+in any language can instead call the same HTTPS API described by the
+[TotemLayer OpenAPI document](https://totemlayer.com/api/v1/openapi.json).
+
+The package is distributed under the included TotemLayer CLI Use License, which
+permits anyone to install and use unmodified copies with TotemLayer-compatible
+services without exposing or licensing the private server application.
+
+## Before the first production request
+
+Each participating company completes its one-time setup at
+[totemlayer.com](https://totemlayer.com):
+
+1. Verify the organization and establish an accepted company relationship.
+2. Register the presenting and receiving agents.
+3. Issue a live, recipient-bound credential for the permitted action.
+4. In **Developer Settings**, create a `credential.verify` key bound to the
+   receiving agent and a separate `credential.present` key bound to the
+   presenting agent.
+5. Copy each raw key when it is shown and store it in that company's secret
+   manager. TotemLayer does not display the raw key again.
+
+Never place keys, nonces, credentials, or presentation tokens in command-line
+arguments. The CLI reads keys from environment variables and reads proof
+artifacts from files or standard input.
+
+## Production handshake
+
+Assume `request.json` contains the exact business request that the receiving
+company may process.
+
+Receiver — create a five-minute challenge:
+
+```bash
+export TOTEM_URL="https://totemlayer.com"
+export TOTEM_API_KEY="$VERIFIER_KEY"
+
+totem challenge \
+  --presenter-agent "$PRESENTER_AGENT_ID" \
+  --action quote.request \
+  --request-file request.json \
+  --idempotency-key verify-request-001 \
+  --json > challenge.json
+```
+
+Keep `challenge.json` as the receiver-owned original and send a copy to the
+presenting workload over the companies' existing authenticated business
+channel. Do not replace the original with a file returned by the presenter.
+
+Presenter — create a one-minute proof:
+
+```bash
+export TOTEM_AGENT_API_KEY="$PRESENTER_KEY"
+
+totem present \
+  --credential-id "$CREDENTIAL_ID" \
+  --challenge-file challenge.json \
+  --json > presentation.json
+```
+
+Return `presentation.json` to the receiver. Receiver — consume it once:
+
+```bash
+export TOTEM_API_KEY="$VERIFIER_KEY"
+
+totem verify \
+  --challenge-file challenge.json \
+  --presentation-file presentation.json \
+  --request-file request.json \
+  --json
+```
+
+The CLI hashes the receiver-owned request bytes and accepts approval only when
+the result matches `evidence.requestDigest`. Never copy the expected digest from
+the server response—that would defeat the independent check. Act on the same
+immutable bytes, or hash them again immediately before taking the business
+action, because an approval never authorizes different bytes.
+The CLI rejects a local challenge/request mismatch before consuming the proof.
+If returned approval evidence later fails its complete binding check, treat the
+proof as consumed and create a new challenge and presentation.
+
+An application may use `--request-digest <sha256>` instead of
+`--request-file` when it computes that digest from receiver-owned immutable
+bytes. Never take the expected digest from a presenter or from TotemLayer's
+approval response.
+
+### Windows PowerShell
+
+PowerShell uses a backtick for line continuation. `Set-Content -Encoding UTF8`
+also avoids the shell-dependent native redirection encoding used by Windows
+PowerShell 5.1. The CLI accepts both UTF-8 BOM and UTF-16LE BOM artifacts for
+compatibility.
+
+```powershell
+$env:TOTEM_URL = "https://totemlayer.com"
+$env:TOTEM_API_KEY = $env:VERIFIER_KEY
+
+totem challenge `
+  --presenter-agent $env:PRESENTER_AGENT_ID `
+  --action quote.request `
+  --request-file request.json `
+  --idempotency-key verify-request-001 `
+  --json | Set-Content -Encoding UTF8 challenge.json
+
+$env:TOTEM_AGENT_API_KEY = $env:PRESENTER_KEY
+
+totem present `
+  --credential-id $env:CREDENTIAL_ID `
+  --challenge-file challenge.json `
+  --json | Set-Content -Encoding UTF8 presentation.json
+
+$env:TOTEM_API_KEY = $env:VERIFIER_KEY
+
+totem verify `
+  --challenge-file challenge.json `
+  --presentation-file presentation.json `
+  --request-file request.json `
+  --json
+```
+
+## Exit codes
+
+- `0` — approved or the requested operation completed.
+- `2` — server policy rejection, expiration, or replay.
+- `1` — invalid input or local binding, network failure, or protocol/operational error.
+
+## Procurement sandbox
+
+`totem rfq` is a sandbox and self-hosted demonstration command. It is not
+enabled on the production `totemlayer.com` service. Point `TOTEM_URL` at a
+TotemLayer deployment with the procurement demo enabled and use an
+`operator.rfq.execute` key.
+
+## Compatibility
+
+The package also installs the legacy `agenttrust` executable and accepts the
+legacy `AGENTTRUST_*` environment-variable aliases. New integrations should use
+`totem` and `TOTEM_*`.

package/bin/totem.mjs

@@ -0,0 +1,867 @@
+#!/usr/bin/env node
+
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { stripVTControlCharacters } from "node:util";
+
+const RFQ_EXAMPLE =
+  "Request a quote for 50,000 Industrial Sensors (SKU-1001) from SupplyCo using Acme Procurement Agent.";
+const CLI_VERSION = "0.1.0";
+const DEFAULT_BASE_URL = "https://totemlayer.com";
+const API_KEY_PATTERN = /^at_(?:live|test)_[A-Za-z0-9_-]{20,}$/;
+const ACTION_PATTERN = /^[a-z0-9][a-z0-9._:-]*$/;
+const SAFE_IDENTIFIER_PATTERN = /^[A-Za-z0-9._:-]+$/;
+const SHA256_PATTERN = /^[a-fA-F0-9]{64}$/;
+const TERMINAL_UNSAFE_PATTERN =
+  /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
+const MAX_JSON_INPUT_BYTES = 128 * 1_024;
+const MAX_REQUEST_FILE_BYTES = 16 * 1_024 * 1_024;
+const PRESENTATION_REJECTION_CODES = new Set([
+  "CHALLENGE_NOT_FOUND",
+  "CHALLENGE_NOT_PRESENTED",
+  "CHALLENGE_ALREADY_PRESENTED",
+  "CHALLENGE_ALREADY_CONSUMED",
+  "CHALLENGE_EXPIRED",
+  "PRESENTATION_EXPIRED",
+  "PRESENTATION_MISMATCH",
+  "PRESENTER_AGENT_INACTIVE",
+  "AGENT_AUTHORITY_REVOKED",
+  "INVALID_PRESENTATION_SIGNATURE",
+  "PRESENTATION_CLAIMS_MISMATCH",
+]);
+
+function help() {
+  process.stdout.write(`TotemLayer CLI ${CLI_VERSION}
+
+Install:
+  npm install --global totemlayer
+  npx --yes totemlayer --help
+
+Usage:
+  totem challenge --presenter-agent <agent-id> --action <action> \\
+    (--request-digest <sha256> | --request-file <path>) [--amount <number> --currency <ISO-4217>] --json
+  totem present --credential-id <credential-id> [--challenge-file <path>] --json
+  totem verify --challenge-file <receiver-challenge.json> \\
+    (--request-digest <sha256> | --request-file <path>) [--presentation-file <path>] --json
+  totem rfq "${RFQ_EXAMPLE}"  # sandbox/self-hosted demo only
+
+Shared options:
+  --base-url <url>          Totem URL (default: TOTEM_URL or ${DEFAULT_BASE_URL})
+  --json                    Print the complete machine-readable JSON response
+  -h, --help                Show this help
+  -v, --version             Print the CLI version
+
+Challenge options:
+  --presenter-agent <id>    Exact agent expected to present authority
+  --action <action>         Namespaced action, for example inventory.read
+  --request-digest <sha256> SHA-256 of the request being authorized
+  --request-file <path>     Hash this file locally; file contents are never uploaded
+  --amount <number>         Optional transaction amount; requires --currency
+  --currency <code>         Three-letter ISO currency; requires --amount
+  --idempotency-key <key>   Reuse for an exact retry (a random key is used by default)
+
+Verification binding:
+  --challenge-file <path>   Receiver's original challenge; never trust a returned copy
+  --request-digest <sha256> Require approval evidence for this exact request digest
+  --request-file <path>     Hash the exact local request before accepting an approval
+
+Presentation input:
+  present reads challenge JSON from stdin unless --challenge-file is supplied.
+  verify reads presentation JSON from stdin unless --presentation-file is supplied and
+  compares it with the receiver-owned --challenge-file before consuming the proof.
+  Raw keys, nonces, credentials, and presentation tokens are never accepted as arguments.
+
+Authentication:
+  challenge and verify use TOTEM_API_KEY.
+  present uses TOTEM_AGENT_API_KEY bound to the presenting agent.
+  Keys are sent only in the Authorization header and are never printed.
+
+Production supports challenge, present, and verify. The RFQ command requires a
+sandbox or self-hosted Totem deployment with the procurement demo enabled.
+`);
+}
+
+function fail(message) {
+  process.stderr.write(`Totem: ${terminalText(message, "The Totem command failed.")}\n`);
+  process.exitCode = 1;
+}
+
+function failCommand(message, json) {
+  if (json) process.stdout.write(`${JSON.stringify({ error: { message } })}\n`);
+  else fail(message);
+  process.exitCode = 1;
+}
+
+function failUnknownOutcome(message, idempotencyKey, json, machineStdout = false) {
+  if (json) {
+    const serialized = `${JSON.stringify({
+      error: { message, outcome: "unknown", idempotencyKey },
+    })}\n`;
+    (machineStdout ? process.stdout : process.stderr).write(serialized);
+    process.exitCode = 1;
+    return;
+  }
+  fail(`${message} The outcome is unknown; retry with --idempotency-key "${idempotencyKey}".`);
+}
+
+function parseArguments(values) {
+  const options = { json: false, positionals: [] };
+  const valuedOptions = new Set([
+    "--base-url",
+    "--idempotency-key",
+    "--presenter-agent",
+    "--action",
+    "--request-digest",
+    "--request-file",
+    "--amount",
+    "--currency",
+    "--challenge-file",
+    "--credential-id",
+    "--presentation-file",
+  ]);
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+    if (value === "--") continue;
+    if (value === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (value === "-h" || value === "--help") {
+      options.help = true;
+      continue;
+    }
+    if (value === "-v" || value === "--version") {
+      options.version = true;
+      continue;
+    }
+    if (valuedOptions.has(value)) {
+      const next = values[index + 1];
+      if (!next || next.startsWith("--")) throw new Error(`${value} requires a value.`);
+      options[value.slice(2).replaceAll("-", "_")] = next;
+      index += 1;
+      continue;
+    }
+    if (value.startsWith("--")) throw new Error(`Unknown option ${value}.`);
+    options.positionals.push(value);
+  }
+  return options;
+}
+
+function safeBaseUrl(value) {
+  const url = new URL(value);
+  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) {
+    throw new Error("The Totem URL must be an HTTP(S) origin without credentials.");
+  }
+  const local = ["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname);
+  if (url.protocol !== "https:" && !local) {
+    throw new Error("Use HTTPS for a non-local Totem URL.");
+  }
+  url.pathname = url.pathname.replace(/\/$/, "");
+  url.search = "";
+  url.hash = "";
+  return url;
+}
+
+function aliasedEnvironment(primaryName, legacyName) {
+  const primary = process.env[primaryName]?.trim();
+  const legacy = process.env[legacyName]?.trim();
+  if (primary && legacy && primary !== legacy) {
+    throw new Error(
+      `${primaryName} and its legacy alias ${legacyName} must match when both are set.`,
+    );
+  }
+  return primary || legacy;
+}
+
+function apiKey(environmentName, legacyEnvironmentName) {
+  const value = aliasedEnvironment(environmentName, legacyEnvironmentName);
+  if (!value || !API_KEY_PATTERN.test(value)) {
+    throw new Error(`Set ${environmentName} to a valid scoped API key.`);
+  }
+  return value;
+}
+
+function errorFrom(payload, fallback) {
+  if (!payload || typeof payload !== "object") return fallback;
+  const error = payload.error;
+  if (!error || typeof error !== "object") return fallback;
+  const code = typeof error.code === "string" ? error.code : "REQUEST_FAILED";
+  const message = typeof error.message === "string" ? error.message : fallback;
+  return `${code}: ${message}`;
+}
+
+function number(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value.toLocaleString("en-US") : "—";
+}
+
+function terminalText(value, fallback = "unknown") {
+  if (typeof value !== "string" && typeof value !== "number") return fallback;
+  const sanitized = stripVTControlCharacters(String(value))
+    .replace(TERMINAL_UNSAFE_PATTERN, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return sanitized.slice(0, 2_000) || fallback;
+}
+
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+
+function requiredOption(options, key, flag, pattern = SAFE_IDENTIFIER_PATTERN) {
+  const value = options[key]?.trim();
+  if (!value || value.length > 200 || (pattern && !pattern.test(value))) {
+    throw new Error(`${flag} must contain a valid value.`);
+  }
+  return value;
+}
+
+function validateCommandOptions(command, options) {
+  const shared = new Set(["json", "help", "base_url", "positionals"]);
+  const allowed = {
+    rfq: new Set([...shared, "idempotency_key"]),
+    challenge: new Set([
+      ...shared,
+      "idempotency_key",
+      "presenter_agent",
+      "action",
+      "request_digest",
+      "request_file",
+      "amount",
+      "currency",
+    ]),
+    present: new Set([...shared, "challenge_file", "credential_id"]),
+    verify: new Set([
+      ...shared,
+      "challenge_file",
+      "presentation_file",
+      "request_digest",
+      "request_file",
+    ]),
+  }[command];
+  if (!allowed) throw new Error(`Unknown command ${command || "(missing)"}.`);
+  for (const [key, value] of Object.entries(options)) {
+    if (value !== undefined && !allowed.has(key)) {
+      throw new Error(`The --${key.replaceAll("_", "-")} option is not valid for ${command}.`);
+    }
+  }
+}
+
+async function readBounded(stream, maximumBytes, label) {
+  const chunks = [];
+  let size = 0;
+  try {
+    for await (const chunk of stream) {
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      size += bytes.length;
+      if (size > maximumBytes) {
+        stream.destroy?.();
+        throw new Error(`${label} exceeds the ${maximumBytes}-byte limit.`);
+      }
+      chunks.push(bytes);
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("exceeds the")) throw error;
+    throw new Error(`Could not read ${label}.`);
+  }
+  if (size === 0) throw new Error(`${label} is empty.`);
+  return Buffer.concat(chunks);
+}
+
+async function readJson(path, label) {
+  if (!path && process.stdin.isTTY) {
+    throw new Error(`Pipe ${label} to stdin or provide its file option.`);
+  }
+  const source = path ? createReadStream(path) : process.stdin;
+  const bytes = await readBounded(source, MAX_JSON_INPUT_BYTES, label);
+  try {
+    let text;
+    if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+      text = bytes.subarray(3).toString("utf8");
+    } else if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe) {
+      text = bytes.subarray(2).toString("utf16le");
+    } else if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) {
+      const bigEndian = bytes.subarray(2);
+      if (bigEndian.length % 2 !== 0) throw new Error();
+      text = Buffer.from(bigEndian).swap16().toString("utf16le");
+    } else {
+      text = bytes.toString("utf8");
+    }
+    const parsed = JSON.parse(text);
+    if (!record(parsed)) throw new Error();
+    return parsed;
+  } catch {
+    throw new Error(`${label} must be a JSON object.`);
+  }
+}
+
+async function digestFile(path) {
+  const hash = createHash("sha256");
+  let size = 0;
+  const stream = createReadStream(path);
+  try {
+    for await (const chunk of stream) {
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      size += bytes.length;
+      if (size > MAX_REQUEST_FILE_BYTES) {
+        stream.destroy();
+        throw new Error(`Request file exceeds the ${MAX_REQUEST_FILE_BYTES}-byte limit.`);
+      }
+      hash.update(bytes);
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("exceeds the")) throw error;
+    throw new Error("Could not read the request file.");
+  }
+  return hash.digest("hex");
+}
+
+async function resolveRequestDigest(options) {
+  if (Boolean(options.request_digest) === Boolean(options.request_file)) {
+    throw new Error("Provide exactly one of --request-digest or --request-file.");
+  }
+  if (options.request_digest) {
+    if (!SHA256_PATTERN.test(options.request_digest)) {
+      throw new Error("--request-digest must be a 64-character SHA-256 hexadecimal digest.");
+    }
+    return options.request_digest.toLowerCase();
+  }
+  return digestFile(options.request_file);
+}
+
+function validIsoTimestamp(value) {
+  return typeof value === "string" && value.length <= 100 && Number.isFinite(Date.parse(value));
+}
+
+function receiverChallenge(input) {
+  const challenge = record(input.challenge) ?? input;
+  const requiredIdentifiers = [
+    challenge.id,
+    challenge.recipientOrganizationId,
+    challenge.issuerOrganizationId,
+    challenge.verifierAgentId,
+    challenge.presenterAgentId,
+  ];
+  if (
+    requiredIdentifiers.some(
+      (value) =>
+        typeof value !== "string" || value.length > 200 || !SAFE_IDENTIFIER_PATTERN.test(value),
+    ) ||
+    typeof challenge.nonce !== "string" ||
+    challenge.nonce.length < 32 ||
+    challenge.nonce.length > 256 ||
+    !/^[A-Za-z0-9_-]+$/.test(challenge.nonce) ||
+    typeof challenge.requestedAction !== "string" ||
+    !ACTION_PATTERN.test(challenge.requestedAction) ||
+    typeof challenge.requestDigest !== "string" ||
+    !SHA256_PATTERN.test(challenge.requestDigest) ||
+    !validIsoTimestamp(challenge.expiresAt)
+  ) {
+    throw new Error("Receiver challenge JSON is missing required trusted challenge context.");
+  }
+
+  const hasAmount = challenge.transactionAmount !== undefined;
+  const hasCurrency = challenge.currency !== undefined;
+  if (hasAmount !== hasCurrency) {
+    throw new Error("Receiver challenge JSON has incomplete transaction context.");
+  }
+  if (
+    hasAmount &&
+    (typeof challenge.transactionAmount !== "number" ||
+      !Number.isFinite(challenge.transactionAmount) ||
+      challenge.transactionAmount < 0 ||
+      challenge.transactionAmount > 1e12 ||
+      typeof challenge.currency !== "string" ||
+      !/^[A-Z]{3}$/.test(challenge.currency))
+  ) {
+    throw new Error("Receiver challenge JSON has invalid transaction context.");
+  }
+
+  return {
+    id: challenge.id,
+    nonce: challenge.nonce,
+    recipientOrganizationId: challenge.recipientOrganizationId,
+    issuerOrganizationId: challenge.issuerOrganizationId,
+    verifierAgentId: challenge.verifierAgentId,
+    presenterAgentId: challenge.presenterAgentId,
+    requestedAction: challenge.requestedAction,
+    requestDigest: challenge.requestDigest.toLowerCase(),
+    ...(hasAmount
+      ? { transactionAmount: challenge.transactionAmount, currency: challenge.currency }
+      : {}),
+    expiresAt: challenge.expiresAt,
+  };
+}
+
+function decodeJwtObject(segment) {
+  if (
+    typeof segment !== "string" ||
+    segment.length === 0 ||
+    segment.length > MAX_JSON_INPUT_BYTES ||
+    !/^[A-Za-z0-9_-]+$/.test(segment)
+  ) {
+    throw new Error("Presentation token is not a valid compact JWT.");
+  }
+  try {
+    const decoded = JSON.parse(Buffer.from(segment, "base64url").toString("utf8"));
+    if (!record(decoded)) throw new Error();
+    return decoded;
+  } catch {
+    throw new Error("Presentation token is not a valid compact JWT.");
+  }
+}
+
+function boundPresentationClaims(token, challenge, credentialId, expiresAt) {
+  const parts = token.split(".");
+  if (parts.length !== 3 || parts.some((part) => part.length === 0)) {
+    throw new Error("Presentation token is not a valid compact JWT.");
+  }
+  const header = decodeJwtObject(parts[0]);
+  const claims = decodeJwtObject(parts[1]);
+  const expectedAmount = challenge.transactionAmount;
+  const expectedCurrency = challenge.currency;
+  const expectedExpiresAt = Math.floor(Date.parse(expiresAt) / 1_000);
+  if (
+    header.alg !== "ES256" ||
+    header.typ !== "at+agent-proof+jwt" ||
+    header.kid !== challenge.presenterAgentId ||
+    claims.iss !== "urn:agenttrust:organization:" + challenge.issuerOrganizationId ||
+    claims.sub !== "urn:agenttrust:agent:" + challenge.presenterAgentId ||
+    claims.aud !== "urn:agenttrust:organization:" + challenge.recipientOrganizationId ||
+    claims.challengeId !== challenge.id ||
+    claims.nonce !== challenge.nonce ||
+    claims.credentialId !== credentialId ||
+    claims.agentId !== challenge.presenterAgentId ||
+    claims.organizationId !== challenge.issuerOrganizationId ||
+    claims.requestedAction !== challenge.requestedAction ||
+    claims.requestDigest !== challenge.requestDigest ||
+    claims.transactionAmount !== expectedAmount ||
+    claims.currency !== expectedCurrency ||
+    typeof claims.iat !== "number" ||
+    !Number.isInteger(claims.iat) ||
+    typeof claims.exp !== "number" ||
+    !Number.isInteger(claims.exp) ||
+    claims.exp <= claims.iat ||
+    claims.exp !== expectedExpiresAt ||
+    typeof claims.jti !== "string" ||
+    claims.jti.length > 200 ||
+    !SAFE_IDENTIFIER_PATTERN.test(claims.jti)
+  ) {
+    throw new Error("Presentation token claims do not match the receiver-owned challenge context.");
+  }
+  return claims;
+}
+
+async function requestJson({ baseUrl, path, key, body, idempotencyKey, timeout = 30_000 }) {
+  const headers = {
+    authorization: `Bearer ${key}`,
+    "content-type": "application/json",
+  };
+  if (idempotencyKey) headers["idempotency-key"] = idempotencyKey;
+  let response;
+  try {
+    response = await fetch(new URL(path, baseUrl), {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeout),
+    });
+  } catch (error) {
+    const timedOut =
+      error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
+    throw new Error(timedOut ? "The Totem request timed out." : "Could not reach Totem.");
+  }
+  const payload = await response.json().catch(() => null);
+  return { response, payload };
+}
+
+function writeJson(payload) {
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+async function runChallenge(options, baseUrl) {
+  const key = apiKey("TOTEM_API_KEY", "AGENTTRUST_API_KEY");
+  if (options.positionals.length !== 1)
+    throw new Error("challenge does not accept positional values.");
+  const presenterAgentId = requiredOption(options, "presenter_agent", "--presenter-agent");
+  const requestedAction = requiredOption(options, "action", "--action", ACTION_PATTERN);
+  const requestDigest = await resolveRequestDigest(options);
+
+  const hasAmount = options.amount !== undefined;
+  const hasCurrency = options.currency !== undefined;
+  if (hasAmount !== hasCurrency)
+    throw new Error("--amount and --currency must be supplied together.");
+  let transactionAmount;
+  let currency;
+  if (hasAmount) {
+    transactionAmount = Number(options.amount);
+    if (!Number.isFinite(transactionAmount) || transactionAmount < 0 || transactionAmount > 1e12) {
+      throw new Error("--amount must be a finite number from 0 through 1000000000000.");
+    }
+    currency = options.currency.trim().toUpperCase();
+    if (!/^[A-Z]{3}$/.test(currency)) {
+      throw new Error("--currency must be a three-letter ISO currency code.");
+    }
+  }
+
+  const idempotencyKey = options.idempotency_key ?? `cli:${randomUUID()}`;
+  if (
+    typeof idempotencyKey !== "string" ||
+    idempotencyKey.length < 8 ||
+    idempotencyKey.length > 128 ||
+    !SAFE_IDENTIFIER_PATTERN.test(idempotencyKey)
+  ) {
+    throw new Error("--idempotency-key must contain 8 to 128 safe identifier characters.");
+  }
+  if (!options.json) process.stderr.write(`Totem retry key: ${idempotencyKey}\n`);
+
+  let result;
+  try {
+    result = await requestJson({
+      baseUrl,
+      path: "/api/v1/challenges",
+      key,
+      idempotencyKey,
+      body: {
+        presenterAgentId,
+        requestedAction,
+        requestDigest,
+        ...(transactionAmount !== undefined ? { transactionAmount, currency } : {}),
+      },
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Could not create the challenge.";
+    failUnknownOutcome(message, idempotencyKey, options.json, true);
+    return;
+  }
+  const challenge = record(result.payload?.challenge);
+  if (!result.response.ok) {
+    failCommand(
+      errorFrom(result.payload, `Challenge creation returned HTTP ${result.response.status}.`),
+      options.json,
+    );
+    return;
+  }
+  if (!challenge || typeof challenge.id !== "string" || typeof challenge.nonce !== "string") {
+    failUnknownOutcome(
+      "Totem returned an invalid challenge response.",
+      idempotencyKey,
+      options.json,
+      true,
+    );
+    return;
+  }
+  if (options.json) writeJson(result.payload);
+  else {
+    process.stdout.write(`Totem challenge · ${terminalText(challenge.id)}\n`);
+    process.stdout.write(`Action: ${terminalText(challenge.requestedAction ?? requestedAction)}\n`);
+    process.stdout.write(`Expires: ${terminalText(challenge.expiresAt)}\n`);
+    process.stdout.write(
+      "Use --json to emit the nonce-bearing challenge for the presenting agent.\n",
+    );
+  }
+}
+
+async function runPresent(options, baseUrl) {
+  const key = apiKey("TOTEM_AGENT_API_KEY", "AGENTTRUST_AGENT_API_KEY");
+  if (options.positionals.length !== 1)
+    throw new Error("present does not accept positional values.");
+  const credentialId = requiredOption(options, "credential_id", "--credential-id");
+  const input = await readJson(options.challenge_file, "challenge JSON");
+  const challenge = record(input.challenge) ?? input;
+  const challengeId = challenge.id;
+  const nonce = challenge.nonce;
+  if (
+    typeof challengeId !== "string" ||
+    !SAFE_IDENTIFIER_PATTERN.test(challengeId) ||
+    typeof nonce !== "string" ||
+    nonce.length < 32 ||
+    nonce.length > 256 ||
+    !/^[A-Za-z0-9_-]+$/.test(nonce)
+  ) {
+    throw new Error("Challenge JSON is missing a valid challenge id or nonce.");
+  }
+
+  const result = await requestJson({
+    baseUrl,
+    path: "/api/v1/presentations",
+    key,
+    body: { credentialId, challengeId, nonce },
+  });
+  const presentation = record(result.payload?.presentation);
+  if (!result.response.ok) {
+    const apiError = record(result.payload?.error);
+    if (typeof apiError?.code === "string" && PRESENTATION_REJECTION_CODES.has(apiError.code)) {
+      if (options.json) writeJson(result.payload);
+      else {
+        process.stdout.write("Totem presentation · REJECTED\n");
+        process.stdout.write(`Reason: ${apiError.code}\n`);
+      }
+      process.exitCode = 2;
+      return;
+    }
+    failCommand(
+      errorFrom(result.payload, `Presentation creation returned HTTP ${result.response.status}.`),
+      options.json,
+    );
+    return;
+  }
+  if (
+    !presentation ||
+    typeof presentation.challengeId !== "string" ||
+    typeof presentation.credentialId !== "string" ||
+    typeof presentation.token !== "string" ||
+    typeof presentation.expiresAt !== "string"
+  ) {
+    failCommand("Totem returned an invalid presentation response.", options.json);
+    return;
+  }
+  if (options.json) writeJson(result.payload);
+  else {
+    process.stdout.write(`Totem presentation · ${terminalText(presentation.challengeId)}\n`);
+    process.stdout.write(`Credential: ${terminalText(presentation.credentialId)}\n`);
+    process.stdout.write(`Expires: ${terminalText(presentation.expiresAt)}\n`);
+    process.stdout.write("Use --json to emit the token-bearing presentation for the verifier.\n");
+  }
+}
+
+async function runVerify(options, baseUrl) {
+  const key = apiKey("TOTEM_API_KEY", "AGENTTRUST_API_KEY");
+  if (options.positionals.length !== 1)
+    throw new Error("verify does not accept positional values.");
+  const expectedRequestDigest = await resolveRequestDigest(options);
+  if (!options.challenge_file?.trim()) {
+    throw new Error("Provide the receiver's original --challenge-file.");
+  }
+  const challengeInput = await readJson(options.challenge_file, "receiver challenge JSON");
+  const challenge = receiverChallenge(challengeInput);
+  if (challenge.requestDigest !== expectedRequestDigest) {
+    throw new Error(
+      "The local request digest does not match the receiver-owned challenge. Create a new challenge for the exact request.",
+    );
+  }
+  const input = await readJson(options.presentation_file, "presentation JSON");
+  const presentation = record(input.presentation) ?? input;
+  const challengeId = presentation.challengeId;
+  const credentialId = presentation.credentialId;
+  const token = presentation.token;
+  if (
+    typeof challengeId !== "string" ||
+    !SAFE_IDENTIFIER_PATTERN.test(challengeId) ||
+    challengeId !== challenge.id ||
+    typeof credentialId !== "string" ||
+    credentialId.length > 200 ||
+    !SAFE_IDENTIFIER_PATTERN.test(credentialId) ||
+    typeof token !== "string" ||
+    token.length < 20 ||
+    token.length > 100_000 ||
+    !validIsoTimestamp(presentation.expiresAt)
+  ) {
+    throw new Error(
+      "Presentation JSON does not match the receiver-owned challenge or is missing required proof fields.",
+    );
+  }
+  const claims = boundPresentationClaims(token, challenge, credentialId, presentation.expiresAt);
+
+  const result = await requestJson({
+    baseUrl,
+    path: "/api/v1/presentations/verify",
+    key,
+    body: { challengeId: challenge.id, presentation: token },
+  });
+  const payload = record(result.payload);
+  if (!payload || typeof payload.verified !== "boolean" || typeof payload.result !== "string") {
+    const apiError = record(payload?.error);
+    if (typeof apiError?.code === "string" && PRESENTATION_REJECTION_CODES.has(apiError.code)) {
+      if (options.json) writeJson(payload);
+      else {
+        process.stdout.write("Totem verification · REJECTED\n");
+        process.stdout.write(`Reason: ${apiError.code}\n`);
+      }
+      process.exitCode = 2;
+      return;
+    }
+    failCommand(
+      errorFrom(
+        result.payload,
+        `Presentation verification returned HTTP ${result.response.status}.`,
+      ),
+      options.json,
+    );
+    return;
+  }
+
+  const approved = payload.verified && payload.result === "APPROVED";
+  if ((payload.verified || payload.result === "APPROVED") && !approved) {
+    failCommand("Totem returned an internally inconsistent approval response.", options.json);
+    return;
+  }
+  if (approved && result.response.status !== 200) {
+    failCommand("Totem returned an approval without the required HTTP 200 status.", options.json);
+    return;
+  }
+  if (approved) {
+    const evidence = record(payload.evidence);
+    const approvedRequestDigest = evidence?.requestDigest;
+    const agent = record(payload.agent);
+    const organization = record(payload.organization);
+    const authorization = record(payload.authorization);
+    const evidenceMatches =
+      evidence?.challengeId === challenge.id &&
+      evidence.presentationJti === claims.jti &&
+      evidence.credentialId === credentialId &&
+      typeof approvedRequestDigest === "string" &&
+      SHA256_PATTERN.test(approvedRequestDigest) &&
+      approvedRequestDigest.toLowerCase() === expectedRequestDigest &&
+      validIsoTimestamp(evidence.verifiedAt);
+    const identityAndAuthorityMatch =
+      agent?.id === challenge.presenterAgentId &&
+      agent.status === "ACTIVE" &&
+      typeof agent.name === "string" &&
+      typeof agent.purpose === "string" &&
+      organization?.id === challenge.issuerOrganizationId &&
+      typeof organization.name === "string" &&
+      typeof organization.domain === "string" &&
+      organization.verified === true &&
+      authorization?.requestedAction === challenge.requestedAction &&
+      authorization.allowed === true &&
+      validIsoTimestamp(authorization.expiresAt) &&
+      typeof authorization.humanApprovalRequired === "boolean" &&
+      typeof payload.requestId === "string" &&
+      payload.requestId.length > 0 &&
+      payload.requestId.length <= 200;
+    if (!evidenceMatches || !identityAndAuthorityMatch) {
+      failCommand(
+        "Totem approval does not match the receiver-owned challenge and complete approval evidence; do not process the request.",
+        options.json,
+      );
+      return;
+    }
+  }
+
+  if (options.json) writeJson(payload);
+  else {
+    process.stdout.write(`Totem verification · ${terminalText(payload.result)}\n`);
+    if (payload.agent?.name || payload.agent?.id) {
+      process.stdout.write(`Agent: ${terminalText(payload.agent.name ?? payload.agent.id)}\n`);
+    }
+    if (payload.organization?.name || payload.organization?.id) {
+      process.stdout.write(
+        `Organization: ${terminalText(payload.organization.name ?? payload.organization.id)}\n`,
+      );
+    }
+    if (payload.authorization?.requestedAction) {
+      process.stdout.write(`Action: ${terminalText(payload.authorization.requestedAction)}\n`);
+    }
+    if (payload.reasonCode) process.stdout.write(`Reason: ${terminalText(payload.reasonCode)}\n`);
+    if (payload.requestId) process.stdout.write(`Receipt: ${terminalText(payload.requestId)}\n`);
+  }
+  if (payload.verified && payload.result === "APPROVED" && result.response.ok) return;
+  process.exitCode = payload.result === "REJECTED" ? 2 : 1;
+}
+
+async function runRfq(options, baseUrl) {
+  const key = apiKey("TOTEM_API_KEY", "AGENTTRUST_API_KEY");
+  if (baseUrl.origin === DEFAULT_BASE_URL) {
+    throw new Error(
+      "The RFQ command is available only on a sandbox or self-hosted deployment. Set TOTEM_URL to that deployment; production totemlayer.com supports challenge, present, and verify.",
+    );
+  }
+  const requestParts = options.positionals.slice(1);
+  if (requestParts.length === 0) throw new Error('Provide an RFQ request after the "rfq" command.');
+  const idempotencyKey = options.idempotency_key ?? `cli:${randomUUID()}`;
+  const prompt = requestParts.join(" ").trim();
+  process.stderr.write(`Totem retry key: ${idempotencyKey}\n`);
+
+  let result;
+  try {
+    result = await requestJson({
+      baseUrl,
+      path: "/api/v1/operator/rfq",
+      key,
+      idempotencyKey,
+      body: { prompt },
+      timeout: 90_000,
+    });
+  } catch (error) {
+    failUnknownOutcome(
+      error instanceof Error
+        ? error.message.replace("The Totem request", "The RFQ request")
+        : "Could not reach Totem.",
+      idempotencyKey,
+      options.json,
+    );
+    return;
+  }
+  if (!result.response.ok) {
+    const message = errorFrom(
+      result.payload,
+      `The RFQ endpoint returned HTTP ${result.response.status}.`,
+    );
+    if (result.response.status >= 500) failUnknownOutcome(message, idempotencyKey, options.json);
+    else fail(message);
+    return;
+  }
+  const run = record(result.payload?.run);
+  if (!run) {
+    failUnknownOutcome("Totem returned an invalid success response.", idempotencyKey, options.json);
+    return;
+  }
+  if (options.json) {
+    writeJson(result.payload);
+    return;
+  }
+
+  const verification = record(run.verification);
+  const supplier = record(run.supplierRequest);
+  process.stdout.write(`Totem RFQ · ${terminalText(run.id, "unknown run")}\n`);
+  process.stdout.write(`Run: ${terminalText(run.status, "UNKNOWN")}\n`);
+  if (run.summary) process.stdout.write(`${terminalText(run.summary)}\n`);
+  if (verification)
+    process.stdout.write(`Agent authority: ${terminalText(verification.result, "UNKNOWN")}\n`);
+  if (supplier) {
+    process.stdout.write(`Delivery: ${terminalText(supplier.status, "UNKNOWN")}\n`);
+    process.stdout.write(
+      `Supplier response: ${terminalText(supplier.businessStatus, "UNKNOWN")}\n`,
+    );
+    process.stdout.write(
+      `Available now: ${number(supplier.availableQuantity)} ${terminalText(supplier.unit, "units")}\n`,
+    );
+    process.stdout.write(
+      `Backorder: ${number(supplier.backorderQuantity)} ${terminalText(supplier.unit, "units")}\n`,
+    );
+    if (supplier.supplierReference)
+      process.stdout.write(`Reference: ${terminalText(supplier.supplierReference)}\n`);
+  }
+  if (run.status !== "SUCCEEDED") process.exitCode = 1;
+}
+
+async function main() {
+  let options;
+  try {
+    options = parseArguments(process.argv.slice(2));
+    const command = options.positionals[0];
+    if (options.version) {
+      process.stdout.write(`${CLI_VERSION}\n`);
+      return;
+    }
+    if (options.help || command === "help" || !command) {
+      help();
+      return;
+    }
+    validateCommandOptions(command, options);
+    const baseUrl = safeBaseUrl(
+      options.base_url ?? aliasedEnvironment("TOTEM_URL", "AGENTTRUST_URL") ?? DEFAULT_BASE_URL,
+    );
+    if (command === "challenge") await runChallenge(options, baseUrl);
+    else if (command === "present") await runPresent(options, baseUrl);
+    else if (command === "verify") await runVerify(options, baseUrl);
+    else await runRfq(options, baseUrl);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "The Totem command failed.";
+    const command = options?.positionals?.[0];
+    if (command && command !== "rfq") failCommand(message, options?.json);
+    else fail(message);
+  }
+}
+
+await main();

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "totemlayer",
+  "version": "0.1.0",
+  "description": "Cross-platform CLI for TotemLayer agent identity and authorization",
+  "type": "module",
+  "bin": {
+    "totem": "bin/totem.mjs",
+    "totemlayer": "bin/totem.mjs",
+    "agenttrust": "bin/totem.mjs"
+  },
+  "files": [
+    "bin",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "keywords": [
+    "ai-agents",
+    "authorization",
+    "cli",
+    "identity",
+    "totemlayer",
+    "verification"
+  ],
+  "homepage": "https://totemlayer.com",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}