@hashspan/core 0.1.0 → 0.2.0

package/README.md

@@ -17,7 +17,9 @@ The core is library-agnostic and read-only: it never signs, sends or fetches any
 npm install @hashspan/core @opentelemetry/api
 ```
 
-`@opentelemetry/api` is the only peer dependency. Bring your own OpenTelemetry SDK and exporter.
+`@opentelemetry/api` is the only peer dependency. Bring your own OpenTelemetry SDK and exporter. Requires Node.js 22.3
+or later; in other runtimes, `hashed` address mode needs a custom `hash` function and otherwise records no addresses,
+with a `diag` warning.
 
 ## Usage
 
@@ -66,9 +68,10 @@ the instrumentation are reported through `diag` and never thrown into your code.
 |---|---|---|
 | `tracerProvider` | global provider | Tracer provider to use |
 | `address` | `'raw'` | `'raw'`, `'hashed'`, `'off'`, or `{ mode: 'hashed', hash: (address) => string }` |
-| `errorMessages` | `'off'` | What failed spans record about the error: `'off'` (type only), `'sanitized'` (first line, addresses per `address` mode, calldata removed; in `hashed` and `off` mode any hex longer than an address) or `'raw'` (full message and stack trace) |
+| `errorMessages` | `'off'` | What failed spans record about the error: `'off'` (type only), `'sanitized'` (first line, addresses per `address` mode, calldata removed; in `hashed` and `off` mode any hex longer than an address) or `'raw'` (full message and stack trace). `'raw'` can record RPC URLs that include API keys, as some libraries put the request URL in the message; `'sanitized'` keeps only the first line (viem puts the URL on a later line), which is best effort. See [ADR 0006](https://github.com/selimaytac/hashspan/blob/main/docs/adr/0006-error-privacy.md) |
 | `recordFunctionArguments` | `false` | Record `functionArguments` as a JSON array in `blockchain.contract.function.arguments`: bigints as decimal strings, addresses per `address` mode (longer hex values become `<hex>` in `hashed` and `off` mode), at most 4096 characters. Reads only own enumerable data properties: `toJSON()` and getters are never called, so a `Date` records as `{}`; a Proxy's traps still run |
-| `agent` | none | Fallback `{ id, name }`; Baggage entries `gen_ai.agent.id` / `gen_ai.agent.name` take precedence |
+| `agent` | none | Agent `{ id, name }`; a field set here always wins, unset fields come from the Baggage entries `gen_ai.agent.id` / `gen_ai.agent.name` |
+| `agentFromBaggage` | `true` | Read agent identity fields that `agent` leaves unset from Baggage; set to `false` in services that accept requests from outside their trust boundary |
 | `redact` | none | `(attributes) => attributes`, runs last on every attribute set, including exception event attributes; if it throws, only non-sensitive identifiers are kept |
 | `linkTtlMs` | `600000` | How long a sent transaction can be linked from its confirmation |
 | `maxTrackedTransactions` | `10000` | Upper bound on transactions kept for linking |
@@ -92,6 +95,9 @@ Attribute definitions:
   party APIs. Put only identifiers there that may leave your system, such as an opaque agent id. For identifiers
   that must stay internal, use the tracker's static `agent` option instead, which is recorded on spans but never
   propagated, or strip the entries before outbound calls.
+- **Inbound Baggage can claim an identity.** A caller can send Baggage entries with any agent id. A field set in the
+  `agent` option cannot be overridden that way; to ignore identity from Baggage entirely, set `agentFromBaggage: false`
+  ([ADR 0011](https://github.com/selimaytac/hashspan/blob/main/docs/adr/0011-agent-identity-precedence.md)).
 - The redaction hook (`redact`) runs last on every attribute set and on exception attributes; use it for anything
   else your policy forbids.
 

package/dist/index.cjs

@@ -3,11 +3,14 @@ let _opentelemetry_api = require("@opentelemetry/api");
 //#region src/agent.ts
 const ATTR_GEN_AI_AGENT_ID = "gen_ai.agent.id";
 const ATTR_GEN_AI_AGENT_NAME = "gen_ai.agent.name";
-/** Agent identity from baggage (preferred) or the static fallback, as GenAI attributes. */
-function agentAttributes(ctx, fallback) {
-	const baggage = _opentelemetry_api.propagation.getBaggage(ctx);
-	const id = baggage?.getEntry("gen_ai.agent.id")?.value ?? fallback?.id;
-	const name = baggage?.getEntry("gen_ai.agent.name")?.value ?? fallback?.name;
+/**
+* Agent identity as GenAI attributes. A field set in the static identity always wins; Baggage, which a remote caller
+* can set, only fills fields it leaves unset, and is not read at all with `fromBaggage` false (docs/adr/0011).
+*/
+function agentAttributes(ctx, identity, fromBaggage = true) {
+	const baggage = fromBaggage ? _opentelemetry_api.propagation.getBaggage(ctx) : void 0;
+	const id = identity?.id ?? baggage?.getEntry("gen_ai.agent.id")?.value;
+	const name = identity?.name ?? baggage?.getEntry("gen_ai.agent.name")?.value;
 	const attributes = {};
 	if (id !== void 0) attributes[ATTR_GEN_AI_AGENT_ID] = id;
 	if (name !== void 0) attributes[ATTR_GEN_AI_AGENT_NAME] = name;
@@ -299,7 +302,7 @@ function resolveErrorMessageMode(mode) {
 }
 //#endregion
 //#region src/version.ts
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 //#endregion
 //#region src/tracker.ts
 const INSTRUMENTATION_NAME = "@hashspan/core";
@@ -443,7 +446,7 @@ function createTxTracker(options = {}) {
 		[ATTR_BLOCKCHAIN_SYSTEM]: "evm",
 		[ATTR_BLOCKCHAIN_CHAIN_ID]: chainId,
 		[ATTR_BLOCKCHAIN_OPERATION_NAME]: operation,
-		...agentAttributes(ctx, options.agent)
+		...agentAttributes(ctx, options.agent, options.agentFromBaggage !== false)
 	});
 	const startSend = (input, parentCtx) => {
 		const parent = parentCtx ?? _opentelemetry_api.context.active();

package/dist/index.d.cts

@@ -38,8 +38,17 @@ interface TxTrackerOptions {
    * text; addresses in them follow the address mode and the redaction hook runs on them.
    */
   recordFunctionArguments?: boolean | undefined;
-  /** Fallback agent identity. Baggage entries `gen_ai.agent.id` / `gen_ai.agent.name` take precedence. */
+  /**
+   * Agent identity. A field set here always wins; fields left unset are taken from the Baggage entries
+   * `gen_ai.agent.id` / `gen_ai.agent.name` unless `agentFromBaggage` is false (docs/adr/0011).
+   */
   agent?: AgentIdentity | undefined;
+  /**
+   * Read agent identity fields that `agent` leaves unset from Baggage. Default: true. Baggage travels with requests
+   * between services, so a remote caller can set it; services that accept requests from outside their trust boundary
+   * should set this to false.
+   */
+  agentFromBaggage?: boolean | undefined;
   /**
    * Runs last on every attribute set and returns the attributes to record.
    * If it throws, only non-sensitive identifiers (system, chain id, operation, hash) are recorded.

package/dist/index.d.mts

@@ -38,8 +38,17 @@ interface TxTrackerOptions {
    * text; addresses in them follow the address mode and the redaction hook runs on them.
    */
   recordFunctionArguments?: boolean | undefined;
-  /** Fallback agent identity. Baggage entries `gen_ai.agent.id` / `gen_ai.agent.name` take precedence. */
+  /**
+   * Agent identity. A field set here always wins; fields left unset are taken from the Baggage entries
+   * `gen_ai.agent.id` / `gen_ai.agent.name` unless `agentFromBaggage` is false (docs/adr/0011).
+   */
   agent?: AgentIdentity | undefined;
+  /**
+   * Read agent identity fields that `agent` leaves unset from Baggage. Default: true. Baggage travels with requests
+   * between services, so a remote caller can set it; services that accept requests from outside their trust boundary
+   * should set this to false.
+   */
+  agentFromBaggage?: boolean | undefined;
   /**
    * Runs last on every attribute set and returns the attributes to record.
    * If it throws, only non-sensitive identifiers (system, chain id, operation, hash) are recorded.

package/dist/index.mjs

@@ -2,11 +2,14 @@ import { SpanKind, SpanStatusCode, context, diag, propagation, trace } from "@op
 //#region src/agent.ts
 const ATTR_GEN_AI_AGENT_ID = "gen_ai.agent.id";
 const ATTR_GEN_AI_AGENT_NAME = "gen_ai.agent.name";
-/** Agent identity from baggage (preferred) or the static fallback, as GenAI attributes. */
-function agentAttributes(ctx, fallback) {
-	const baggage = propagation.getBaggage(ctx);
-	const id = baggage?.getEntry("gen_ai.agent.id")?.value ?? fallback?.id;
-	const name = baggage?.getEntry("gen_ai.agent.name")?.value ?? fallback?.name;
+/**
+* Agent identity as GenAI attributes. A field set in the static identity always wins; Baggage, which a remote caller
+* can set, only fills fields it leaves unset, and is not read at all with `fromBaggage` false (docs/adr/0011).
+*/
+function agentAttributes(ctx, identity, fromBaggage = true) {
+	const baggage = fromBaggage ? propagation.getBaggage(ctx) : void 0;
+	const id = identity?.id ?? baggage?.getEntry("gen_ai.agent.id")?.value;
+	const name = identity?.name ?? baggage?.getEntry("gen_ai.agent.name")?.value;
 	const attributes = {};
 	if (id !== void 0) attributes[ATTR_GEN_AI_AGENT_ID] = id;
 	if (name !== void 0) attributes[ATTR_GEN_AI_AGENT_NAME] = name;
@@ -298,7 +301,7 @@ function resolveErrorMessageMode(mode) {
 }
 //#endregion
 //#region src/version.ts
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 //#endregion
 //#region src/tracker.ts
 const INSTRUMENTATION_NAME = "@hashspan/core";
@@ -442,7 +445,7 @@ function createTxTracker(options = {}) {
 		[ATTR_BLOCKCHAIN_SYSTEM]: "evm",
 		[ATTR_BLOCKCHAIN_CHAIN_ID]: chainId,
 		[ATTR_BLOCKCHAIN_OPERATION_NAME]: operation,
-		...agentAttributes(ctx, options.agent)
+		...agentAttributes(ctx, options.agent, options.agentFromBaggage !== false)
 	});
 	const startSend = (input, parentCtx) => {
 		const parent = parentCtx ?? context.active();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hashspan/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Transaction lifecycle tracing for on-chain actions of AI agents, built on OpenTelemetry.",
   "license": "Apache-2.0",
   "author": "Selim Aytac",
@@ -57,7 +57,7 @@
     "@opentelemetry/sdk-trace-node": "^2.11.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22.3.0"
   },
   "scripts": {
     "build": "tsdown",