@tangle-network/agent-core 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tangle Network
+
+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,35 @@
+# @tangle-network/agent-core
+
+Runtime primitives for talking to Tangle agents:
+
+- **Auth** — issue and verify scoped access tokens for sidecar/session access.
+- **SSE** — parse agent event streams (`SSEChunkParser`, `parseSSEStream`, `parseSSEData`).
+- **Transport** — connection-manager and transport interfaces.
+- **Resilience** — retries, timeouts, and circuit breakers.
+- **Telemetry** — GenAI attribute and token-usage helpers.
+
+Depends on [`@tangle-network/agent-interface`](../agent-interface) for the shared
+type/schema contract.
+
+## Install
+
+```bash
+pnpm add @tangle-network/agent-core @tangle-network/agent-interface
+```
+
+Requires Node.js >= 18 — the auth module uses `node:crypto` for token signing and
+verification.
+
+## Subpath exports
+
+```ts
+import { } from "@tangle-network/agent-core";            // top-level
+import { } from "@tangle-network/agent-core/auth";       // token issue/verify
+import { } from "@tangle-network/agent-core/sse";        // SSE parsing
+import { } from "@tangle-network/agent-core/transport";  // transport interfaces
+import { } from "@tangle-network/agent-core/resilience"; // retries / breakers
+```
+
+## License
+
+MIT

package/dist/auth/browser.d.ts

@@ -0,0 +1,22 @@
+import { C as ReadTokenAuth, S as NoAuth, T as StaticTokenAuth, a as CreateSessionResponse, b as AuthProvider, c as ProductSchema, f as ReadTokenPayload, h as SendMessageRequestSchema, i as CreateSessionRequestSchema, l as ProductSecrets, m as SendMessageRequest, o as Product, p as ReadTokenPayloadSchema, r as CreateSessionRequest, s as ProductAuthInfo, w as RefreshableTokenAuth, x as CallbackAuth, y as TokenValidationResult } from "../types-DiDSGM8K.js";
+
+//#region src/auth/tokens-browser.d.ts
+/**
+ * Decode a JWT without verification (to extract claims for lookup).
+ * Returns null if the token is malformed.
+ *
+ * This is safe to use in browsers - it only parses the token, doesn't verify.
+ */
+declare function decodeToken(token: string): ReadTokenPayload | null;
+/**
+ * Get time until token expires (in seconds).
+ * Returns negative if expired.
+ */
+declare function getTokenTTL(payload: ReadTokenPayload): number;
+/**
+ * Check if token is expiring soon (within buffer seconds).
+ */
+declare function isTokenExpiringSoon(payload: ReadTokenPayload, bufferSeconds?: number): boolean;
+//#endregion
+export { type AuthProvider, CallbackAuth, type CreateSessionRequest, CreateSessionRequestSchema, type CreateSessionResponse, NoAuth, type Product, type ProductAuthInfo, ProductSchema, type ProductSecrets, ReadTokenAuth, type ReadTokenPayload, ReadTokenPayloadSchema, RefreshableTokenAuth, type SendMessageRequest, SendMessageRequestSchema, StaticTokenAuth, type TokenValidationResult, decodeToken, getTokenTTL, isTokenExpiringSoon };
+//# sourceMappingURL=browser.d.ts.map

package/dist/auth/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","names":[],"sources":["../../src/auth/tokens-browser.ts"],"mappings":";;;;AAkDA;;;;;iBAlBgB,WAAA,CAAY,KAAA,WAAgB,gBAAA;;;;;iBAkB5B,WAAA,CAAY,OAAA,EAAS,gBAAA;;;;iBAQrB,mBAAA,CACd,OAAA,EAAS,gBAAA,EACT,aAAA"}

package/dist/auth/browser.js

@@ -0,0 +1,43 @@
+import { a as ReadTokenPayloadSchema, c as CallbackAuth, d as RefreshableTokenAuth, f as StaticTokenAuth, l as NoAuth, n as CreateSessionRequestSchema, o as SendMessageRequestSchema, r as ProductSchema, u as ReadTokenAuth } from "../types-DC6OJ1um.js";
+//#region src/auth/tokens-browser.ts
+/**
+* Base64URL decode (browser-safe).
+*/
+function base64UrlDecode(data) {
+	const base64 = (data + "=".repeat((4 - data.length % 4) % 4)).replace(/-/g, "+").replace(/_/g, "/");
+	if (typeof atob === "function") return atob(base64);
+	return Buffer.from(base64, "base64").toString();
+}
+/**
+* Decode a JWT without verification (to extract claims for lookup).
+* Returns null if the token is malformed.
+*
+* This is safe to use in browsers - it only parses the token, doesn't verify.
+*/
+function decodeToken(token) {
+	try {
+		const parts = token.split(".");
+		if (parts.length !== 3) return null;
+		return JSON.parse(base64UrlDecode(parts[1]));
+	} catch {
+		return null;
+	}
+}
+/**
+* Get time until token expires (in seconds).
+* Returns negative if expired.
+*/
+function getTokenTTL(payload) {
+	const now = Math.floor(Date.now() / 1e3);
+	return payload.exp - now;
+}
+/**
+* Check if token is expiring soon (within buffer seconds).
+*/
+function isTokenExpiringSoon(payload, bufferSeconds = 60) {
+	return getTokenTTL(payload) <= bufferSeconds;
+}
+//#endregion
+export { CallbackAuth, CreateSessionRequestSchema, NoAuth, ProductSchema, ReadTokenAuth, ReadTokenPayloadSchema, RefreshableTokenAuth, SendMessageRequestSchema, StaticTokenAuth, decodeToken, getTokenTTL, isTokenExpiringSoon };
+
+//# sourceMappingURL=browser.js.map

package/dist/auth/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","names":[],"sources":["../../src/auth/tokens-browser.ts"],"sourcesContent":["/**\n * Browser-safe Token Utilities\n *\n * Token decoding and inspection that works in both browser and Node.js.\n * Uses only standard APIs (atob/btoa or TextEncoder/TextDecoder).\n */\n\nimport type { ReadTokenPayload } from \"./types.js\";\n\n/**\n * Base64URL decode (browser-safe).\n */\nfunction base64UrlDecode(data: string): string {\n  // Add padding if needed\n  const padded = data + \"=\".repeat((4 - (data.length % 4)) % 4);\n  // Convert base64url to base64\n  const base64 = padded.replace(/-/g, \"+\").replace(/_/g, \"/\");\n\n  // Use atob in browser, Buffer in Node\n  if (typeof atob === \"function\") {\n    return atob(base64);\n  }\n  // Node.js fallback\n  return Buffer.from(base64, \"base64\").toString();\n}\n\n/**\n * Decode a JWT without verification (to extract claims for lookup).\n * Returns null if the token is malformed.\n *\n * This is safe to use in browsers - it only parses the token, doesn't verify.\n */\nexport function decodeToken(token: string): ReadTokenPayload | null {\n  try {\n    const parts = token.split(\".\");\n    if (parts.length !== 3) {\n      return null;\n    }\n\n    const payload = JSON.parse(base64UrlDecode(parts[1]));\n    return payload as ReadTokenPayload;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Get time until token expires (in seconds).\n * Returns negative if expired.\n */\nexport function getTokenTTL(payload: ReadTokenPayload): number {\n  const now = Math.floor(Date.now() / 1000);\n  return payload.exp - now;\n}\n\n/**\n * Check if token is expiring soon (within buffer seconds).\n */\nexport function isTokenExpiringSoon(\n  payload: ReadTokenPayload,\n  bufferSeconds = 60,\n): boolean {\n  return getTokenTTL(payload) <= bufferSeconds;\n}\n"],"mappings":";;;;;AAYA,SAAS,gBAAgB,MAAsB;CAI7C,MAAM,UAFS,OAAO,IAAI,QAAQ,IAAK,KAAK,SAAS,KAAM,EAAE,EAEvC,QAAQ,MAAM,IAAI,CAAC,QAAQ,MAAM,IAAI;AAG3D,KAAI,OAAO,SAAS,WAClB,QAAO,KAAK,OAAO;AAGrB,QAAO,OAAO,KAAK,QAAQ,SAAS,CAAC,UAAU;;;;;;;;AASjD,SAAgB,YAAY,OAAwC;AAClE,KAAI;EACF,MAAM,QAAQ,MAAM,MAAM,IAAI;AAC9B,MAAI,MAAM,WAAW,EACnB,QAAO;AAIT,SADgB,KAAK,MAAM,gBAAgB,MAAM,GAAG,CACtC;SACR;AACN,SAAO;;;;;;;AAQX,SAAgB,YAAY,SAAmC;CAC7D,MAAM,MAAM,KAAK,MAAM,KAAK,KAAK,GAAG,IAAK;AACzC,QAAO,QAAQ,MAAM;;;;;AAMvB,SAAgB,oBACd,SACA,gBAAgB,IACP;AACT,QAAO,YAAY,QAAQ,IAAI"}

package/dist/auth/index.d.ts

@@ -0,0 +1,430 @@
+import { C as ReadTokenAuth, S as NoAuth, T as StaticTokenAuth, _ as SessionScopedTokenPayloadSchema, a as CreateSessionResponse, b as AuthProvider, c as ProductSchema, d as ProjectScopedTokenPayloadSchema, f as ReadTokenPayload, g as SessionScopedTokenPayload, h as SendMessageRequestSchema, i as CreateSessionRequestSchema, l as ProductSecrets, m as SendMessageRequest, n as BatchScopedTokenPayloadSchema, o as Product, p as ReadTokenPayloadSchema, r as CreateSessionRequest, s as ProductAuthInfo, t as BatchScopedTokenPayload, u as ProjectScopedTokenPayload, v as TokenScope, w as RefreshableTokenAuth, x as CallbackAuth, y as TokenValidationResult } from "../types-DiDSGM8K.js";
+
+//#region src/auth/channel-access.d.ts
+/**
+ * Result of channel access check.
+ */
+interface ChannelAccessResult {
+  /** Whether access is allowed */
+  allowed: boolean;
+  /** Reason for denial (if not allowed) */
+  reason?: string;
+}
+/**
+ * Extract session ID from a session channel pattern.
+ * Returns null if not a session channel.
+ */
+declare function extractSessionFromChannel(channel: string): string | null;
+/**
+ * Extract project ID from a project channel pattern.
+ * Returns null if not a project channel.
+ */
+declare function extractProjectFromChannel(channel: string): string | null;
+/**
+ * Check if a session-scoped token can access a channel.
+ *
+ * Session tokens can access:
+ * - session:{their-sid}
+ * - agent:{their-sid}
+ * - system (always allowed)
+ * - Wildcard patterns matching their session
+ */
+declare function canSessionTokenAccessChannel(payload: SessionScopedTokenPayload, channel: string): ChannelAccessResult;
+/**
+ * Check if a project-scoped token can access a channel.
+ *
+ * Project tokens can access:
+ * - project:{their-projectId}
+ * - session:* (all sessions within project - requires validation by caller)
+ * - agent:* (all agent events within project)
+ * - system (always allowed)
+ */
+declare function canProjectTokenAccessChannel(payload: ProjectScopedTokenPayload, channel: string): ChannelAccessResult;
+/**
+ * Check if a batch-scoped token can access a channel.
+ *
+ * Batch tokens can access:
+ * - project:{any of their projectIds}
+ * - session:* (all sessions within their projects)
+ * - agent:* (all agent events within their projects)
+ * - system (always allowed)
+ * - * (global wildcard - for organization-wide subscriptions)
+ */
+declare function canBatchTokenAccessChannel(payload: BatchScopedTokenPayload, channel: string): ChannelAccessResult;
+/**
+ * Check if a token can access a channel.
+ * Dispatches to scope-specific functions based on token type.
+ *
+ * @param payload - The token payload
+ * @param channel - The channel to check access for
+ * @returns Access result with allowed boolean and optional reason
+ */
+declare function canTokenAccessChannel(payload: ReadTokenPayload, channel: string): ChannelAccessResult;
+/**
+ * Get the list of allowed channel patterns for a token.
+ * Useful for informing clients what they can subscribe to.
+ *
+ * @param payload - The token payload
+ * @returns Array of allowed channel patterns
+ */
+declare function getAllowedChannelPatterns(payload: ReadTokenPayload): string[];
+/**
+ * Validate channel subscription request.
+ * Checks multiple channels and returns aggregated result.
+ *
+ * @param payload - The token payload
+ * @param channels - Channels to validate
+ * @returns Object with allowed channels and denied channels with reasons
+ */
+declare function validateChannelSubscription(payload: ReadTokenPayload, channels: string[]): {
+  allowed: string[];
+  denied: Array<{
+    channel: string;
+    reason: string;
+  }>;
+};
+//#endregion
+//#region src/auth/tokens.d.ts
+/**
+ * Generate a cryptographically secure random string.
+ * @param prefix - Prefix for the generated string (e.g., "orch_prod_")
+ * @param bytes - Number of random bytes (default: 32 = 256 bits)
+ */
+declare function generateSecureToken(prefix: string, bytes?: number): string;
+/**
+ * Generate a product API key.
+ */
+declare function generateApiKey(): string;
+/**
+ * Generate a signing secret.
+ */
+declare function generateSigningSecret(): string;
+/**
+ * Issue a read token (JWT) for WebSocket authentication.
+ *
+ * @param signingSecret - The product's signing secret
+ * @param payload - Token payload (without iat/exp, those are added)
+ * @param ttlMinutes - Token TTL in minutes
+ */
+declare function issueReadToken(signingSecret: string, payload: Omit<ReadTokenPayload, "iat" | "exp" | "typ">, ttlMinutes: number): string;
+/**
+ * Issue a session-scoped token (JWT) for WebSocket authentication.
+ * Grants access to a single session's events.
+ *
+ * @param signingSecret - The product's signing secret
+ * @param payload - Token payload with session ID
+ * @param ttlMinutes - Token TTL in minutes
+ */
+declare function issueSessionScopedToken(signingSecret: string, payload: Omit<SessionScopedTokenPayload, "iat" | "exp" | "typ">, ttlMinutes: number): string;
+/**
+ * Issue a project-scoped token (JWT) for WebSocket authentication.
+ * Grants access to all sessions within a single project.
+ *
+ * @param signingSecret - The product's signing secret
+ * @param payload - Token payload with project ID
+ * @param ttlMinutes - Token TTL in minutes
+ */
+declare function issueProjectScopedToken(signingSecret: string, payload: Omit<ProjectScopedTokenPayload, "iat" | "exp" | "typ">, ttlMinutes: number): string;
+/**
+ * Issue a batch-scoped token (JWT) for WebSocket authentication.
+ * Grants access to multiple projects (organization-level access).
+ *
+ * @param signingSecret - The product's signing secret
+ * @param payload - Token payload with project IDs array
+ * @param ttlMinutes - Token TTL in minutes
+ */
+declare function issueBatchScopedToken(signingSecret: string, payload: Omit<BatchScopedTokenPayload, "iat" | "exp" | "typ">, ttlMinutes: number): string;
+/**
+ * Capability strings carried in a sidecar token's `cap` claim. The
+ * sidecar route allowlist (SIDECAR_CAPABILITY_ROUTES) maps each path
+ * prefix to the capability required to access it. Tokens with a `cap`
+ * claim are strictly limited to those capabilities; tokens without a
+ * `cap` claim are full-scope (legacy orchestrator-internal use).
+ *
+ * Adding a new capability:
+ *   1. Extend this union.
+ *   2. Add the path prefix → capability mapping in SIDECAR_CAPABILITY_ROUTES.
+ *   3. Mint tokens with the new capability via `issueSidecarAccessToken`.
+ */
+type SidecarCapability = "computer_use" | "read" | "debug" | "terminal";
+/**
+ * Public ↔ capability binding. The sidecar's auth middleware uses this
+ * to enforce: a token with a `cap` claim can only call routes whose
+ * required capability is in the token's `cap` list. Routes not listed
+ * here implicitly require full scope (no `cap` claim, i.e. legacy
+ * orchestrator-internal tokens).
+ *
+ * Order matters — longest prefix wins so `/mcp/x` matches before `/`.
+ */
+declare const SIDECAR_CAPABILITY_ROUTES: ReadonlyArray<{
+  prefix: string;
+  capability: SidecarCapability;
+}>;
+/**
+ * Pattern-gated routes, for capabilities that must bind to a SPECIFIC path
+ * shape rather than a whole prefix. The terminal/ssh WebSocket upgrade paths
+ * are the raw-input interactive surface (keystrokes straight to a PTY / SSH
+ * tunnel) — the highest-trust action in the box — so they require a `terminal`
+ * capability, while the sibling REST route `/terminals/commands` (one-shot
+ * command exec, called by the public SDK + artifact queue) deliberately stays
+ * OUT of the gate so a prefix match does not break those callers.
+ *
+ * Adding a pattern: anchor it (`^…$`) so it cannot over-match a sibling path.
+ */
+declare const SIDECAR_CAPABILITY_ROUTE_PATTERNS: ReadonlyArray<{
+  pattern: RegExp;
+  capability: SidecarCapability;
+}>;
+/**
+ * Routes a token with `cap: ["read"]` is allowed to call, with the HTTP
+ * methods permitted on each. Used by `box.mintScopedToken({scope:
+ * "read-only" | "project" | "session"})` (Issue #913 Gap 1).
+ *
+ * The "read" capability is intentionally NOT in
+ * `SIDECAR_CAPABILITY_ROUTES` — that table maps gated routes that ONLY
+ * the matching cap can access. "read" is *additive*: it grants a token
+ * access to a narrow allow-list of read routes WITHOUT also denying
+ * those same routes to master tokens. Master tokens (cap=undefined)
+ * keep reaching every non-gated route as before.
+ *
+ * Adding a route here: keep it GET-only by default. Mutating methods
+ * on a read-token would defeat the "read-only" promise customers rely
+ * on when handing the token to browser code.
+ */
+declare const READ_CAPABILITY_ROUTES: ReadonlyArray<{
+  prefix: string;
+  methods: ReadonlyArray<string>;
+}>;
+/**
+ * Returns the capability required to access `path`, or `null` if the
+ * route requires full scope (no `cap` claim).
+ */
+declare function requiredCapabilityForPath(path: string): SidecarCapability | null;
+/**
+ * Authorize a verified sidecar token for `path` (and optionally
+ * `method`). Returns true iff one of:
+ *   - the token has NO `cap` claim (legacy full-scope master) AND the
+ *     path is not capability-gated;
+ *   - the path is capability-gated and the token's `cap` claim
+ *     includes the required capability;
+ *   - the token has `cap: ["read"]` (Issue #913 Gap 1 consumer
+ *     scoped tokens) AND the path is in `READ_CAPABILITY_ROUTES`
+ *     with the request method on the allow-list.
+ *
+ * Fail-closed semantics:
+ *   - An explicit `cap` claim is a scope assertion. Even an empty
+ *     array (`cap: []`) means "scoped to no capability" → reject every
+ *     request, including admin routes (see harden report 2026-04-26).
+ *   - A capability-scoped token CANNOT access non-capability-gated
+ *     routes outside its explicit allow-list.
+ *
+ * `method` defaults to undefined for backwards compatibility — callers
+ * that don't pass it will fail-closed for the read-cap allow-list,
+ * which matches the old behavior (read-cap didn't exist).
+ */
+declare function authorizeSidecarToken(payload: {
+  cap?: readonly SidecarCapability[];
+}, path: string, method?: string): boolean;
+/**
+ * Generate an Ed25519 key pair for per-session JWT signing.
+ * Private key stays in orchestrator memory. Public key is injected into
+ * the sidecar container. Even if the sidecar is fully compromised,
+ * the attacker cannot forge JWTs for any container.
+ *
+ * @returns { privateKey, publicKey } as PEM strings
+ */
+declare function generateSidecarKeyPair(): {
+  privateKey: string;
+  publicKey: string;
+};
+/**
+ * Issue a sidecar access token (JWT) using Ed25519 signing.
+ * Scoped to a specific container via the required `cid` claim.
+ *
+ * @param privateKey - Ed25519 private key (PEM). If not provided, falls back to HMAC.
+ * @param hmacFallbackSecret - HMAC secret for backward compat (used when no Ed25519 key)
+ * @param payload - Token payload with container ID
+ * @param ttlMinutes - Token TTL in minutes
+ */
+declare function issueSidecarAccessToken(privateKey: string, payload: {
+  sub: string;
+  pid: string;
+  cid: string;
+  sid?: string;
+  /**
+   * Capability allowlist. When present, the token is restricted to
+   * routes whose required capability is in this list (see
+   * SIDECAR_CAPABILITY_ROUTES). Absent = full scope (legacy
+   * orchestrator-internal tokens).
+   */
+  cap?: SidecarCapability[];
+}, ttlMinutes: number): string;
+/**
+ * Verify a sidecar JWT using Ed25519 public key. Rejects non-EdDSA tokens.
+ * Returns decoded payload on success, null on failure.
+ */
+declare function verifySidecarToken(token: string, publicKey: string, containerId: string): {
+  sub: string;
+  pid: string;
+  cid: string;
+  sid?: string;
+  typ: string;
+  jti?: string;
+  exp: number;
+  cap?: SidecarCapability[];
+} | null;
+/**
+ * Check if a token payload is session-scoped.
+ * Session-scoped tokens have a sid claim and no projectId/projectIds.
+ */
+declare function isSessionScopedToken(payload: ReadTokenPayload): payload is SessionScopedTokenPayload;
+/**
+ * Check if a token payload is project-scoped.
+ * Project-scoped tokens have a projectId claim and no sid/projectIds.
+ */
+declare function isProjectScopedToken(payload: ReadTokenPayload): payload is ProjectScopedTokenPayload;
+/**
+ * Check if a token payload is batch-scoped.
+ * Batch-scoped tokens have a projectIds claim and no sid/projectId.
+ */
+declare function isBatchScopedToken(payload: ReadTokenPayload): payload is BatchScopedTokenPayload;
+/**
+ * Get the scope of a token payload.
+ * Returns null if the token has an invalid/ambiguous scope.
+ */
+declare function getTokenScope(payload: ReadTokenPayload): TokenScope | null;
+/**
+ * Validate that a token payload has exactly one valid scope.
+ * Returns an error message if invalid, null if valid.
+ */
+declare function validateTokenScope(payload: ReadTokenPayload): string | null;
+/**
+ * Decode a JWT without verification (to extract claims for lookup).
+ * Returns null if the token is malformed.
+ */
+declare function decodeToken(token: string): ReadTokenPayload | null;
+/**
+ * Verify a read token against a product's signing secrets.
+ *
+ * @param token - The JWT token to verify
+ * @param product - Product auth info containing secrets
+ */
+declare function verifyReadToken(token: string, product: ProductAuthInfo): TokenValidationResult;
+/**
+ * Get time until token expires (in seconds).
+ * Returns negative if expired.
+ */
+declare function getTokenTTL(payload: ReadTokenPayload): number;
+/**
+ * Check if token is expiring soon (within buffer seconds).
+ */
+declare function isTokenExpiringSoon(payload: ReadTokenPayload, bufferSeconds?: number): boolean;
+/**
+ * Hash an API key for storage/lookup.
+ * Uses HMAC-SHA256 for consistent, fast hashing.
+ *
+ * The salt can be configured via API_KEY_HASH_SALT environment variable.
+ * WARNING: Changing the salt will invalidate all existing API key hashes.
+ */
+declare function hashApiKey(apiKey: string): string;
+/**
+ * Hash an API key with an explicit salt.
+ * Use this when you need to verify against a specific salt.
+ */
+declare function hashApiKeyWithSalt(apiKey: string, salt: string): string;
+/**
+ * Verify an API key using timing-safe comparison.
+ */
+declare function verifyApiKey(provided: string, stored: string): boolean;
+//#endregion
+//#region src/auth/index.d.ts
+/**
+ * Environment-based auth that reads from env vars.
+ * Matches the server-side patterns used in sidecar/orchestrator.
+ */
+declare class EnvTokenAuth {
+  private envVar;
+  private fallback?;
+  constructor(options: {
+    envVar: string;
+    fallback?: string;
+  });
+  getToken(): Promise<string | null>;
+}
+/**
+ * Pre-configured auth for sidecar connections.
+ * Uses SIDECAR_AUTH_TOKEN env var (matches server expectation).
+ */
+declare class SidecarAuth extends EnvTokenAuth {
+  constructor(token?: string);
+}
+/**
+ * Product-based auth for multi-tenant orchestrator connections.
+ * Uses ORCHESTRATOR_API_SECRET_KEY env var.
+ */
+declare class ProductAuth extends EnvTokenAuth {
+  constructor(apiKey?: string);
+}
+/**
+ * Product token issuer for backend services.
+ *
+ * Use this in product backends to issue read tokens for WebSocket connections.
+ *
+ * @example
+ * ```typescript
+ * import { ProductTokenIssuer } from "@tangle-network/agent-core";
+ *
+ * const issuer = new ProductTokenIssuer({
+ *   productId: "vibecode",
+ *   signingSecret: process.env.ORCHESTRATOR_SIGNING_SECRET!,
+ *   ttlMinutes: { free: 15, pro: 240 },
+ * });
+ *
+ * // Issue a token for a user session
+ * const token = issuer.issue({
+ *   userId: "user_123",
+ *   sessionId: "sess_abc",
+ *   tier: "pro",
+ * });
+ *
+ * // Return token to frontend for WebSocket connection
+ * res.json({
+ *   readToken: token.token,
+ *   expiresAt: token.expiresAt,
+ *   websocketUrl: `wss://orchestrator.example.com/session?token=${token.token}`,
+ * });
+ * ```
+ */
+declare class ProductTokenIssuer {
+  private readonly productId;
+  private readonly signingSecret;
+  private readonly ttlMinutes;
+  constructor(config: {
+    productId: string;
+    signingSecret: string; /** TTL in minutes for each tier (default: { free: 15, pro: 240 }) */
+    ttlMinutes?: {
+      free?: number;
+      pro?: number;
+      enterprise?: number;
+    };
+  });
+  /**
+   * Issue a read token for a user session.
+   */
+  issue(params: {
+    userId: string;
+    sessionId: string;
+    tier?: "free" | "pro" | "enterprise";
+    sidecarId?: string;
+  }): {
+    token: string;
+    expiresAt: number;
+  };
+  /**
+   * Get the TTL in minutes for a tier.
+   */
+  getTtlMinutes(tier?: "free" | "pro" | "enterprise"): number;
+}
+//#endregion
+export { type AuthProvider, BatchScopedTokenPayload, BatchScopedTokenPayloadSchema, CallbackAuth, ChannelAccessResult, CreateSessionRequest, CreateSessionRequestSchema, CreateSessionResponse, EnvTokenAuth, NoAuth, Product, ProductAuth, ProductAuthInfo, ProductSchema, ProductSecrets, ProductTokenIssuer, ProjectScopedTokenPayload, ProjectScopedTokenPayloadSchema, READ_CAPABILITY_ROUTES, ReadTokenAuth, ReadTokenPayload, ReadTokenPayloadSchema, RefreshableTokenAuth, SIDECAR_CAPABILITY_ROUTES, SIDECAR_CAPABILITY_ROUTE_PATTERNS, SendMessageRequest, SendMessageRequestSchema, SessionScopedTokenPayload, SessionScopedTokenPayloadSchema, SidecarAuth, SidecarCapability, StaticTokenAuth, TokenScope, TokenValidationResult, authorizeSidecarToken, canBatchTokenAccessChannel, canProjectTokenAccessChannel, canSessionTokenAccessChannel, canTokenAccessChannel, decodeToken, extractProjectFromChannel, extractSessionFromChannel, generateApiKey, generateSecureToken, generateSidecarKeyPair, generateSigningSecret, getAllowedChannelPatterns, getTokenScope, getTokenTTL, hashApiKey, hashApiKeyWithSalt, isBatchScopedToken, isProjectScopedToken, isSessionScopedToken, isTokenExpiringSoon, issueBatchScopedToken, issueProjectScopedToken, issueReadToken, issueSessionScopedToken, issueSidecarAccessToken, requiredCapabilityForPath, validateChannelSubscription, validateTokenScope, verifyApiKey, verifyReadToken, verifySidecarToken };
+//# sourceMappingURL=index.d.ts.map

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

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