@datacules/agent-identity-otel 0.10.0 → 0.11.1

package/LICENSE

@@ -0,0 +1,109 @@
+Datacules Agent Identity License — Version 1.0
+Copyright (c) 2026 Datacules LLC. All rights reserved.
+
+─────────────────────────────────────────────────────────────────────────────
+PREAMBLE
+─────────────────────────────────────────────────────────────────────────────
+
+This software — Agent Identity & Auth Patterns — is developed and owned by
+Datacules LLC. It is made available to the public as open-source software
+under the permissive terms below.
+
+Datacules LLC retains ownership and authorship of this software while
+granting broad, royalty-free rights for anyone to use, copy, modify, and
+distribute it — in commercial or non-commercial contexts — without requiring
+that derivative works also become open source.
+
+─────────────────────────────────────────────────────────────────────────────
+TERMS AND CONDITIONS
+─────────────────────────────────────────────────────────────────────────────
+
+1. PERMISSION TO USE
+
+   Permission is hereby granted, free of charge, to any person or
+   organization obtaining a copy of this software and associated
+   documentation files (the "Software"), 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 conditions below.
+
+2. ATTRIBUTION
+
+   a. Redistributions of source code must retain this copyright notice,
+      this list of conditions, and the disclaimer below.
+
+   b. Redistributions in binary form or as a product must reproduce this
+      copyright notice, this list of conditions, and the disclaimer in the
+      documentation and/or other materials provided with the distribution.
+
+   c. Neither the name "Datacules LLC" nor the names of its contributors
+      may be used to endorse or promote products derived from this Software
+      without prior written permission from Datacules LLC.
+
+3. COMMERCIAL USE
+
+   Use of this Software in commercial products, SaaS platforms, internal
+   enterprise tools, or any revenue-generating context is explicitly
+   permitted without royalty, fee, or additional licensing agreement,
+   provided that the conditions in Section 2 (Attribution) are met.
+
+4. NO COPYLEFT / NO VIRAL REQUIREMENT
+
+   This license does NOT require that derivative works, modifications,
+   or software that uses or embeds this Software be made open source.
+   You may incorporate this Software into proprietary or closed-source
+   products under your own license terms.
+
+5. MODIFICATIONS
+
+   Modified versions of the Software may be distributed under the same
+   terms as this license or under any other permissive open-source
+   license (e.g. MIT, Apache 2.0, BSD), provided that:
+
+   a. The original copyright notice of Datacules LLC is preserved.
+   b. Modifications are clearly documented and distinguished from the
+      original work.
+
+6. COMPATIBILITY
+
+   This license is compatible with other permissive open-source licenses
+   such as MIT, BSD 2-Clause, BSD 3-Clause, and Apache License 2.0. It
+   is also GPL-compatible — this Software may coexist with GPL-licensed
+   code, though this Software itself is not distributed under the GPL.
+
+─────────────────────────────────────────────────────────────────────────────
+DISCLAIMER
+─────────────────────────────────────────────────────────────────────────────
+
+THIS SOFTWARE IS PROVIDED BY DATACULES LLC AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+AND NON-INFRINGEMENT ARE DISCLAIMED.
+
+IN NO EVENT SHALL DATACULES LLC OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+─────────────────────────────────────────────────────────────────────────────
+SUMMARY (non-binding)
+─────────────────────────────────────────────────────────────────────────────
+
+  ✔  Use freely — commercial, proprietary, or open-source projects
+  ✔  Modify and distribute with or without changes
+  ✔  Sell products built on this Software
+  ✔  No royalties or fees
+  ✔  No requirement to open-source your own code
+  ✔  Attribution to Datacules LLC required in source and binary distributions
+  ✗  Do not use "Datacules LLC" to endorse derived products without permission
+
+─────────────────────────────────────────────────────────────────────────────
+CONTACT
+─────────────────────────────────────────────────────────────────────────────
+
+Datacules LLC
+For licensing enquiries: legal@datacules.com
+Product: https://github.com/hvrcharon1/agent-identity

package/dist/esm/index.js

@@ -0,0 +1,118 @@
+/**
+ * Wrap any CredentialRouter with automatic OTEL span instrumentation.
+ *
+ * Span schema:
+ *   agent_identity.resolve           — sync resolve
+ *   agent_identity.resolve_async     — async resolve (includes approval + budget)
+ *   agent_identity.resolve_pair      — migration pair resolve (sync)
+ *   agent_identity.resolve_pair_async — migration pair resolve (async)
+ *
+ * Attributes on every span:
+ *   agent.user_id, agent.provider, agent.model, agent.action,
+ *   credential.resource_id, credential.resource_kind,
+ *   routing.canary (boolean), routing.resolved (boolean)
+ *
+ * Migration spans also set:
+ *   migration.id, migration.phase, migration.dry_run
+ */
+export function withOtel(router, options) {
+    const { tracer, serviceName = 'agent-identity', includeUserId = true } = options;
+    function startSpan(name, ctx) {
+        const span = tracer.startSpan(`${serviceName}.${name}`);
+        span.setAttribute('agent.provider', ctx.provider);
+        span.setAttribute('agent.model', ctx.model);
+        span.setAttribute('agent.action', ctx.action);
+        span.setAttribute('credential.resource_id', ctx.resourceId);
+        span.setAttribute('credential.resource_kind', ctx.resourceKind);
+        if (includeUserId)
+            span.setAttribute('agent.user_id', ctx.userId);
+        if (ctx.traceId)
+            span.setAttribute('trace.id', ctx.traceId);
+        if (ctx.parentTraceId)
+            span.setAttribute('trace.parent_id', ctx.parentTraceId);
+        return span;
+    }
+    function annotateResult(span, resolved) {
+        span.setAttribute('routing.resolved', resolved !== null);
+        if (resolved) {
+            span.setAttribute('credential.id', resolved.credentialId);
+            span.setAttribute('credential.kind', resolved.kind);
+            span.setAttribute('routing.canary', resolved.isCanary ?? false);
+            span.setAttribute('routing.resolved_for', resolved.resolvedFor);
+        }
+    }
+    function annotateMigrationCtx(span, ctx) {
+        span.setAttribute('migration.id', ctx.migrationId);
+        span.setAttribute('migration.phase', ctx.phase);
+        span.setAttribute('migration.dry_run', ctx.dryRun);
+    }
+    return {
+        resolve(ctx) {
+            const span = startSpan('resolve', ctx);
+            try {
+                const result = router.resolve(ctx);
+                annotateResult(span, result);
+                return result;
+            }
+            catch (err) {
+                span.recordException(err);
+                span.setStatus({ code: 2 }); // ERROR
+                throw err;
+            }
+            finally {
+                span.end();
+            }
+        },
+        async resolveAsync(ctx) {
+            const span = startSpan('resolve_async', ctx);
+            try {
+                const result = await router.resolveAsync(ctx);
+                annotateResult(span, result);
+                return result;
+            }
+            catch (err) {
+                span.recordException(err);
+                span.setStatus({ code: 2 });
+                throw err;
+            }
+            finally {
+                span.end();
+            }
+        },
+        resolvePair(ctx) {
+            const span = startSpan('resolve_pair', ctx);
+            annotateMigrationCtx(span, ctx);
+            try {
+                const result = router.resolvePair(ctx);
+                span.setAttribute('routing.resolved', result !== null);
+                return result;
+            }
+            catch (err) {
+                span.recordException(err);
+                span.setStatus({ code: 2 });
+                throw err;
+            }
+            finally {
+                span.end();
+            }
+        },
+        async resolvePairAsync(ctx) {
+            const span = startSpan('resolve_pair_async', ctx);
+            annotateMigrationCtx(span, ctx);
+            try {
+                const result = await router.resolvePairAsync(ctx);
+                span.setAttribute('routing.resolved', result !== null);
+                return result;
+            }
+            catch (err) {
+                span.recordException(err);
+                span.setStatus({ code: 2 });
+                throw err;
+            }
+            finally {
+                span.end();
+            }
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @datacules/agent-identity-otel
+ *
+ * Zero-config OpenTelemetry wrapper for @datacules/agent-identity.
+ * Wraps CredentialRouter to emit spans on every resolve, store lookup,
+ * and audit emission — without touching your existing code.
+ *
+ * Usage:
+ *   import { withOtel } from '@datacules/agent-identity-otel';
+ *   import { trace } from '@opentelemetry/api';
+ *
+ *   const router = withOtel(createRouter(credentials, rules, logger), {
+ *     tracer: trace.getTracer('agent-identity'),
+ *   });
+ */
+import type { Tracer } from '@opentelemetry/api';
+import type { AgentRequestContext, ResolvedCredential, MigrationContext, ResolvedCredentialPair } from '@datacules/agent-identity';
+export interface OtelWrapperOptions {
+    tracer: Tracer;
+    /** Service name prefix on every span (default: 'agent-identity') */
+    serviceName?: string;
+    /** If true, include userId in span attributes (default: true) */
+    includeUserId?: boolean;
+}
+/**
+ * Structural interface that CredentialRouter satisfies.
+ * withOtel() accepts any object that matches this shape — not just
+ * CredentialRouter — so it works with any custom router implementation.
+ */
+export interface TracedRouter {
+    resolve(ctx: AgentRequestContext): ResolvedCredential | null;
+    resolveAsync(ctx: AgentRequestContext): Promise<ResolvedCredential | null>;
+    resolvePair(ctx: MigrationContext): ResolvedCredentialPair | null;
+    /**
+     * Async counterpart of resolvePair() — benefits from budget enforcement,
+     * attestation, and approval gates on migration workflows.
+     * Added to TracedRouter to match the method added to CredentialRouter in
+     * the v0.3.0 hardening pass (PR #19).
+     */
+    resolvePairAsync(ctx: MigrationContext): Promise<ResolvedCredentialPair | null>;
+}
+/**
+ * Wrap any CredentialRouter with automatic OTEL span instrumentation.
+ *
+ * Span schema:
+ *   agent_identity.resolve           — sync resolve
+ *   agent_identity.resolve_async     — async resolve (includes approval + budget)
+ *   agent_identity.resolve_pair      — migration pair resolve (sync)
+ *   agent_identity.resolve_pair_async — migration pair resolve (async)
+ *
+ * Attributes on every span:
+ *   agent.user_id, agent.provider, agent.model, agent.action,
+ *   credential.resource_id, credential.resource_kind,
+ *   routing.canary (boolean), routing.resolved (boolean)
+ *
+ * Migration spans also set:
+ *   migration.id, migration.phase, migration.dry_run
+ */
+export declare function withOtel(router: TracedRouter, options: OtelWrapperOptions): TracedRouter;
+export type { OtelWrapperOptions as WithOtelOptions };
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,MAAM,EAAwB,MAAM,oBAAoB,CAAC;AACvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAEnI,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,GAAG,EAAE,mBAAmB,GAAG,kBAAkB,GAAG,IAAI,CAAC;IAC7D,YAAY,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IAC3E,WAAW,CAAC,GAAG,EAAE,gBAAgB,GAAG,sBAAsB,GAAG,IAAI,CAAC;IAClE;;;;;OAKG;IACH,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAC;CACjF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,kBAAkB,GAAG,YAAY,CA+FxF;AAGD,YAAY,EAAE,kBAAkB,IAAI,eAAe,EAAE,CAAC"}

package/package.json

@@ -1,10 +1,24 @@
 {
   "name": "@datacules/agent-identity-otel",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "private": false,
   "description": "Zero-config OpenTelemetry tracing wrapper for @datacules/agent-identity",
   "author": "Datacules LLC",
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hvrcharon1/agent-identity.git",
+    "directory": "packages/integrations/otel"
+  },
+  "keywords": [
+    "agent-identity",
+    "opentelemetry",
+    "otel",
+    "tracing",
+    "observability",
+    "ai-agents",
+    "datacules"
+  ],
   "module": "./dist/esm/index.js",
   "types": "./dist/types/index.d.ts",
   "exports": {
@@ -15,20 +29,22 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "type-check": "tsc --noEmit",
     "lint": "eslint src --ext .ts"
   },
-  "dependencies": {
-    "@datacules/agent-identity": "^0.8.0"
-  },
   "peerDependencies": {
+    "@datacules/agent-identity": "^0.11.1",
     "@opentelemetry/api": ">=1.0.0"
   },
   "peerDependenciesMeta": {
+    "@datacules/agent-identity": {
+      "optional": false
+    },
     "@opentelemetry/api": {
       "optional": false
     }