@tangle-network/agent-core 0.2.0

package/dist/auth/index.js

@@ -0,0 +1,841 @@
+import { a as ReadTokenPayloadSchema, c as CallbackAuth, d as RefreshableTokenAuth, f as StaticTokenAuth, i as ProjectScopedTokenPayloadSchema, l as NoAuth, n as CreateSessionRequestSchema, o as SendMessageRequestSchema, r as ProductSchema, s as SessionScopedTokenPayloadSchema, t as BatchScopedTokenPayloadSchema, u as ReadTokenAuth } from "../types-DC6OJ1um.js";
+import { createHmac, generateKeyPairSync, randomBytes, sign, timingSafeEqual, verify } from "node:crypto";
+//#region src/auth/tokens.ts
+/**
+* JWT Token Utilities
+*
+* Token generation and verification for multi-tenant auth.
+* - Read/product tokens: HMAC-SHA256 (symmetric, fast)
+* - Sidecar tokens: Ed25519 (asymmetric — sidecar cannot forge tokens)
+*/
+/**
+* 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)
+*/
+function generateSecureToken(prefix, bytes = 32) {
+	return `${prefix}${randomBytes(bytes).toString("base64url")}`;
+}
+/**
+* Generate a product API key.
+*/
+function generateApiKey() {
+	return generateSecureToken("orch_prod_");
+}
+/**
+* Generate a signing secret.
+*/
+function generateSigningSecret() {
+	return generateSecureToken("orch_sign_");
+}
+/**
+* Base64URL encode (RFC 7515).
+*/
+function base64UrlEncode(data) {
+	return (typeof data === "string" ? Buffer.from(data) : data).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/**
+* Base64URL decode.
+*/
+function base64UrlDecode(data) {
+	const padded = data + "=".repeat((4 - data.length % 4) % 4);
+	return Buffer.from(padded.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString();
+}
+/**
+* Create HMAC-SHA256 signature.
+*/
+function createSignature(data, secret) {
+	return base64UrlEncode(createHmac("sha256", secret).update(data).digest());
+}
+/**
+* Verify signature using timing-safe comparison on raw HMAC bytes.
+*
+* Decoding both sides to raw bytes before the compare strips the
+* length-of-base64url-string oracle: every legitimate signature
+* decodes to exactly 32 bytes (HMAC-SHA256 digest size), so a
+* length mismatch on the decoded buffer means malformed input,
+* not a partial match. Equivalent to the pattern used in
+* `products/sandbox/sdk/src/auth/tokens.ts`.
+*/
+function verifySignature(data, signature, secret) {
+	const expectedBuf = createHmac("sha256", secret).update(data).digest();
+	let providedBuf;
+	try {
+		providedBuf = Buffer.from(signature, "base64url");
+	} catch {
+		return false;
+	}
+	if (providedBuf.length !== expectedBuf.length) return false;
+	try {
+		return timingSafeEqual(providedBuf, expectedBuf);
+	} catch {
+		return false;
+	}
+}
+/**
+* JWT header (always the same for our use case).
+*/
+const JWT_HEADER = base64UrlEncode(JSON.stringify({
+	alg: "HS256",
+	typ: "JWT"
+}));
+/**
+* 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
+*/
+function issueReadToken(signingSecret, payload, ttlMinutes) {
+	const now = Math.floor(Date.now() / 1e3);
+	const fullPayload = {
+		...payload,
+		typ: "read",
+		iat: now,
+		exp: now + ttlMinutes * 60
+	};
+	const data = `${JWT_HEADER}.${base64UrlEncode(JSON.stringify(fullPayload))}`;
+	return `${data}.${createSignature(data, signingSecret)}`;
+}
+/**
+* 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
+*/
+function issueSessionScopedToken(signingSecret, payload, ttlMinutes) {
+	return issueReadToken(signingSecret, payload, ttlMinutes);
+}
+/**
+* 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
+*/
+function issueProjectScopedToken(signingSecret, payload, ttlMinutes) {
+	return issueReadToken(signingSecret, payload, ttlMinutes);
+}
+/**
+* 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
+*/
+function issueBatchScopedToken(signingSecret, payload, ttlMinutes) {
+	return issueReadToken(signingSecret, payload, ttlMinutes);
+}
+const JWT_HEADER_EDDSA = base64UrlEncode(JSON.stringify({
+	alg: "EdDSA",
+	typ: "JWT"
+}));
+/**
+* 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 `/`.
+*/
+const SIDECAR_CAPABILITY_ROUTES = [
+	{
+		prefix: "/mcp",
+		capability: "computer_use"
+	},
+	{
+		prefix: "/computer-use",
+		capability: "computer_use"
+	},
+	{
+		prefix: "/a11y",
+		capability: "computer_use"
+	},
+	{
+		prefix: "/debug",
+		capability: "debug"
+	}
+];
+/**
+* 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.
+*/
+const SIDECAR_CAPABILITY_ROUTE_PATTERNS = [{
+	pattern: /^\/terminals\/[^/]+\/ws$/,
+	capability: "terminal"
+}, {
+	pattern: /^\/ssh\/?$/,
+	capability: "terminal"
+}];
+/**
+* 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.
+*/
+const READ_CAPABILITY_ROUTES = [
+	{
+		prefix: "/agents/sessions",
+		methods: ["GET"]
+	},
+	{
+		prefix: "/agents/events",
+		methods: ["GET"]
+	},
+	{
+		prefix: "/health",
+		methods: ["GET"]
+	},
+	{
+		prefix: "/privacy",
+		methods: ["GET"]
+	},
+	{
+		prefix: "/computer-use/screenshot",
+		methods: ["GET"]
+	}
+];
+function isReadCapAllowed(path, method) {
+	if (!method) return false;
+	const m = method.toUpperCase();
+	for (const entry of READ_CAPABILITY_ROUTES) if (path === entry.prefix || path.startsWith(`${entry.prefix}/`)) return entry.methods.includes(m);
+	return false;
+}
+/**
+* Returns the capability required to access `path`, or `null` if the
+* route requires full scope (no `cap` claim).
+*/
+function requiredCapabilityForPath(path) {
+	for (const { pattern, capability } of SIDECAR_CAPABILITY_ROUTE_PATTERNS) if (pattern.test(path)) return capability;
+	for (const { prefix, capability } of SIDECAR_CAPABILITY_ROUTES) if (path === prefix || path.startsWith(`${prefix}/`)) return capability;
+	return 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).
+*/
+function authorizeSidecarToken(payload, path, method) {
+	const required = requiredCapabilityForPath(path);
+	if (payload.cap !== void 0) {
+		if (payload.cap.includes("read") && isReadCapAllowed(path, method)) return true;
+		return required !== null && payload.cap.includes(required);
+	}
+	return required === null;
+}
+/**
+* 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
+*/
+function generateSidecarKeyPair() {
+	const { privateKey, publicKey } = generateKeyPairSync("ed25519", {
+		publicKeyEncoding: {
+			type: "spki",
+			format: "pem"
+		},
+		privateKeyEncoding: {
+			type: "pkcs8",
+			format: "pem"
+		}
+	});
+	return {
+		privateKey,
+		publicKey
+	};
+}
+/**
+* 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
+*/
+function issueSidecarAccessToken(privateKey, payload, ttlMinutes) {
+	if (!privateKey.includes("PRIVATE KEY")) throw new Error("issueSidecarAccessToken requires an Ed25519 private key (PEM). HMAC fallback has been removed — generate a key pair with generateSidecarKeyPair().");
+	const now = Math.floor(Date.now() / 1e3);
+	const jti = `${payload.cid}:${now}:${randomBytes(8).toString("hex")}`;
+	const fullPayload = {
+		...payload,
+		typ: "sidecar",
+		jti,
+		iat: now,
+		exp: now + ttlMinutes * 60
+	};
+	const data = `${JWT_HEADER_EDDSA}.${base64UrlEncode(JSON.stringify(fullPayload))}`;
+	return `${data}.${base64UrlEncode(sign(null, Buffer.from(data), privateKey))}`;
+}
+/**
+* Verify a sidecar JWT using Ed25519 public key. Rejects non-EdDSA tokens.
+* Returns decoded payload on success, null on failure.
+*/
+function verifySidecarToken(token, publicKey, containerId) {
+	try {
+		const parts = token.split(".");
+		if (parts.length !== 3) return null;
+		const headerJson = Buffer.from(parts[0], "base64url").toString("utf-8");
+		if (JSON.parse(headerJson).alg !== "EdDSA") return null;
+		const data = `${parts[0]}.${parts[1]}`;
+		const signatureBuffer = Buffer.from(parts[2], "base64url");
+		if (!verify(null, Buffer.from(data), publicKey, signatureBuffer)) return null;
+		const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf-8"));
+		if (payload.typ !== "sidecar") return null;
+		if (typeof payload.jti !== "string" || payload.jti.length === 0) return null;
+		const exactContainerMatch = payload.cid === containerId;
+		const shortDockerIdMatch = isDockerShortIdMatch(payload.cid, containerId);
+		if (!exactContainerMatch && !shortDockerIdMatch) return null;
+		const now = Math.floor(Date.now() / 1e3);
+		if (typeof payload.exp !== "number" || payload.exp < now) return null;
+		if (typeof payload.sub !== "string" || payload.sub.length === 0) return null;
+		return payload;
+	} catch {
+		return null;
+	}
+}
+function isDockerShortIdMatch(payloadCid, containerId) {
+	if (typeof payloadCid !== "string" || typeof containerId !== "string") return false;
+	if (!/^[a-f0-9]{64}$/i.test(payloadCid)) return false;
+	if (!/^[a-f0-9]{12}$/i.test(containerId)) return false;
+	return payloadCid.startsWith(containerId);
+}
+/**
+* Check if a token payload is session-scoped.
+* Session-scoped tokens have a sid claim and no projectId/projectIds.
+*/
+function isSessionScopedToken(payload) {
+	return "sid" in payload && typeof payload.sid === "string" && payload.sid.length > 0 && !("projectId" in payload && payload.projectId) && !("projectIds" in payload && payload.projectIds);
+}
+/**
+* Check if a token payload is project-scoped.
+* Project-scoped tokens have a projectId claim and no sid/projectIds.
+*/
+function isProjectScopedToken(payload) {
+	return "projectId" in payload && typeof payload.projectId === "string" && payload.projectId.length > 0 && !("sid" in payload && payload.sid) && !("projectIds" in payload && payload.projectIds);
+}
+/**
+* Check if a token payload is batch-scoped.
+* Batch-scoped tokens have a projectIds claim and no sid/projectId.
+*/
+function isBatchScopedToken(payload) {
+	return "projectIds" in payload && Array.isArray(payload.projectIds) && payload.projectIds.length > 0 && !("sid" in payload && payload.sid) && !("projectId" in payload && payload.projectId);
+}
+/**
+* Get the scope of a token payload.
+* Returns null if the token has an invalid/ambiguous scope.
+*/
+function getTokenScope(payload) {
+	if (isSessionScopedToken(payload)) return "session";
+	if (isProjectScopedToken(payload)) return "project";
+	if (isBatchScopedToken(payload)) return "batch";
+	return null;
+}
+/**
+* Validate that a token payload has exactly one valid scope.
+* Returns an error message if invalid, null if valid.
+*/
+function validateTokenScope(payload) {
+	const scopeCount = [
+		"sid" in payload && payload.sid,
+		"projectId" in payload && payload.projectId,
+		"projectIds" in payload && Array.isArray(payload.projectIds) && payload.projectIds.length > 0
+	].filter(Boolean).length;
+	if (scopeCount === 0) return "Token must have one of: sid (session), projectId (project), or projectIds (batch)";
+	if (scopeCount > 1) return "Token cannot have multiple scope claims (sid, projectId, projectIds are mutually exclusive)";
+	return null;
+}
+/**
+* Decode a JWT without verification (to extract claims for lookup).
+* Returns null if the token is malformed.
+*/
+function decodeToken(token) {
+	try {
+		const parts = token.split(".");
+		if (parts.length !== 3) return null;
+		return JSON.parse(base64UrlDecode(parts[1]));
+	} catch {
+		return 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
+*/
+function verifyReadToken(token, product) {
+	if (product.status !== "active") return {
+		valid: false,
+		error: "Product is suspended",
+		errorCode: "PRODUCT_SUSPENDED"
+	};
+	const parts = token.split(".");
+	if (parts.length !== 3) return {
+		valid: false,
+		error: "Invalid token format",
+		errorCode: "TOKEN_INVALID"
+	};
+	const [header, encodedPayload, signature] = parts;
+	const data = `${header}.${encodedPayload}`;
+	if (header !== JWT_HEADER) {
+		let parsedAlg = null;
+		try {
+			const decoded = JSON.parse(base64UrlDecode(header));
+			if (typeof decoded.alg === "string") parsedAlg = decoded.alg;
+		} catch {}
+		if (parsedAlg !== "HS256") return {
+			valid: false,
+			error: "Unsupported token algorithm",
+			errorCode: "TOKEN_INVALID"
+		};
+	}
+	let signatureValid = verifySignature(data, signature, product.secrets.current.secret);
+	if (!signatureValid && product.secrets.previous) {
+		if (Date.now() < product.secrets.previous.expires_at) signatureValid = verifySignature(data, signature, product.secrets.previous.secret);
+	}
+	if (!signatureValid) return {
+		valid: false,
+		error: "Invalid signature",
+		errorCode: "SIGNATURE_INVALID"
+	};
+	let payload;
+	try {
+		payload = JSON.parse(base64UrlDecode(encodedPayload));
+	} catch {
+		return {
+			valid: false,
+			error: "Invalid token payload",
+			errorCode: "TOKEN_INVALID"
+		};
+	}
+	if (payload.typ !== "read") return {
+		valid: false,
+		error: "Not a read token",
+		errorCode: "TOKEN_WRONG_TYPE"
+	};
+	const now = Math.floor(Date.now() / 1e3);
+	if (payload.exp < now) return {
+		valid: false,
+		error: "Token expired",
+		errorCode: "TOKEN_EXPIRED"
+	};
+	if (payload.pid !== product.product_id) return {
+		valid: false,
+		error: "Product ID mismatch",
+		errorCode: "TOKEN_INVALID"
+	};
+	const scopeError = validateTokenScope(payload);
+	if (scopeError) return {
+		valid: false,
+		error: scopeError,
+		errorCode: "TOKEN_INVALID"
+	};
+	return {
+		valid: true,
+		payload,
+		scope: getTokenScope(payload) ?? void 0
+	};
+}
+/**
+* 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;
+}
+/**
+* Default salt for API key hashing (development only).
+* Production MUST set API_KEY_HASH_SALT environment variable.
+* WARNING: Changing the salt will invalidate all existing API key hashes.
+*/
+const DEFAULT_API_KEY_SALT = "api_key_hash_salt";
+let _saltWarned = false;
+/**
+* Get the API key hash salt from environment.
+* Logs a warning if falling back to the weak default (development only).
+*/
+function getApiKeyHashSalt() {
+	if (typeof process !== "undefined" && process.env?.API_KEY_HASH_SALT) return process.env.API_KEY_HASH_SALT;
+	if (!_saltWarned && typeof process !== "undefined" && process.env?.NODE_ENV === "production") {
+		_saltWarned = true;
+		console.error("[SECURITY] API_KEY_HASH_SALT not set in production. Using weak default salt. Set API_KEY_HASH_SALT to a cryptographically random value.");
+	}
+	return DEFAULT_API_KEY_SALT;
+}
+/**
+* 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.
+*/
+function hashApiKey(apiKey) {
+	return createHmac("sha256", getApiKeyHashSalt()).update(apiKey).digest("hex");
+}
+/**
+* Hash an API key with an explicit salt.
+* Use this when you need to verify against a specific salt.
+*/
+function hashApiKeyWithSalt(apiKey, salt) {
+	return createHmac("sha256", salt).update(apiKey).digest("hex");
+}
+/**
+* Verify an API key using timing-safe comparison.
+*/
+function verifyApiKey(provided, stored) {
+	if (provided.length !== stored.length) return false;
+	try {
+		return timingSafeEqual(Buffer.from(provided), Buffer.from(stored));
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/auth/channel-access.ts
+/**
+* Channel Access Control
+*
+* Determines what channels a token can access based on its scope.
+* Used by SessionGateway to validate subscriptions and event delivery.
+*
+* Channel patterns:
+* - session:{sessionId} - Events for a specific session
+* - agent:{sessionId} - Agent events for a specific session
+* - project:{projectId} - All events for a project
+* - system - System-wide events (heartbeat, etc.)
+*/
+/**
+* Extract session ID from a session channel pattern.
+* Returns null if not a session channel.
+*/
+function extractSessionFromChannel(channel) {
+	if (channel.startsWith("session:")) return channel.slice(8);
+	if (channel.startsWith("agent:")) return channel.slice(6);
+	return null;
+}
+/**
+* Extract project ID from a project channel pattern.
+* Returns null if not a project channel.
+*/
+function extractProjectFromChannel(channel) {
+	if (channel.startsWith("project:")) return channel.slice(8);
+	return 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
+*/
+function canSessionTokenAccessChannel(payload, channel) {
+	if (channel === "system" || channel.startsWith("system.")) return { allowed: true };
+	if (channel === "*") return {
+		allowed: false,
+		reason: "Session-scoped tokens cannot subscribe to all channels"
+	};
+	const sessionId = extractSessionFromChannel(channel);
+	if (sessionId !== null) {
+		if (sessionId === payload.sid) return { allowed: true };
+		if (sessionId === "*") return {
+			allowed: false,
+			reason: "Session-scoped tokens cannot subscribe to all sessions"
+		};
+		return {
+			allowed: false,
+			reason: `Token only has access to session ${payload.sid}`
+		};
+	}
+	if (channel.startsWith("project:")) return {
+		allowed: false,
+		reason: "Session-scoped tokens cannot access project channels"
+	};
+	return { allowed: true };
+}
+/**
+* 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)
+*/
+function canProjectTokenAccessChannel(payload, channel) {
+	if (channel === "system" || channel.startsWith("system.")) return { allowed: true };
+	if (channel === "*") return {
+		allowed: false,
+		reason: "Project-scoped tokens cannot subscribe to all channels across projects"
+	};
+	const projectId = extractProjectFromChannel(channel);
+	if (projectId !== null) {
+		if (projectId === payload.projectId) return { allowed: true };
+		return {
+			allowed: false,
+			reason: `Token only has access to project ${payload.projectId}`
+		};
+	}
+	if (channel.startsWith("session:") || channel.startsWith("agent:")) {
+		if (extractSessionFromChannel(channel) === "*") return { allowed: true };
+		return { allowed: true };
+	}
+	return { allowed: true };
+}
+/**
+* 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)
+*/
+function canBatchTokenAccessChannel(payload, channel) {
+	if (channel === "system" || channel.startsWith("system.")) return { allowed: true };
+	if (channel === "*") return { allowed: true };
+	const projectId = extractProjectFromChannel(channel);
+	if (projectId !== null) {
+		if (projectId === "*") return { allowed: true };
+		if (payload.projectIds.includes(projectId)) return { allowed: true };
+		return {
+			allowed: false,
+			reason: `Token does not have access to project ${projectId}`
+		};
+	}
+	if (channel.startsWith("session:") || channel.startsWith("agent:")) return { allowed: true };
+	return { allowed: true };
+}
+/**
+* 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
+*/
+function canTokenAccessChannel(payload, channel) {
+	if (isSessionScopedToken(payload)) return canSessionTokenAccessChannel(payload, channel);
+	if (isProjectScopedToken(payload)) return canProjectTokenAccessChannel(payload, channel);
+	if (isBatchScopedToken(payload)) return canBatchTokenAccessChannel(payload, channel);
+	return {
+		allowed: false,
+		reason: "Token has no valid scope (missing sid, projectId, or projectIds)"
+	};
+}
+/**
+* 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
+*/
+function getAllowedChannelPatterns(payload) {
+	const patterns = ["system", "system.*"];
+	if (isSessionScopedToken(payload)) {
+		patterns.push(`session:${payload.sid}`, `agent:${payload.sid}`);
+		return patterns;
+	}
+	if (isProjectScopedToken(payload)) {
+		patterns.push(`project:${payload.projectId}`, "session:*", "agent:*");
+		return patterns;
+	}
+	if (isBatchScopedToken(payload)) {
+		patterns.push("*", "project:*", ...payload.projectIds.map((id) => `project:${id}`), "session:*", "agent:*");
+		return patterns;
+	}
+	return patterns;
+}
+/**
+* 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
+*/
+function validateChannelSubscription(payload, channels) {
+	const allowed = [];
+	const denied = [];
+	for (const channel of channels) {
+		const result = canTokenAccessChannel(payload, channel);
+		if (result.allowed) allowed.push(channel);
+		else denied.push({
+			channel,
+			reason: result.reason ?? "Access denied"
+		});
+	}
+	return {
+		allowed,
+		denied
+	};
+}
+//#endregion
+//#region src/auth/index.ts
+/**
+* Authentication Configuration
+*
+* Token management with refresh hooks and expiration handling.
+*/
+/**
+* Environment-based auth that reads from env vars.
+* Matches the server-side patterns used in sidecar/orchestrator.
+*/
+var EnvTokenAuth = class {
+	envVar;
+	fallback;
+	constructor(options) {
+		this.envVar = options.envVar;
+		this.fallback = options.fallback;
+	}
+	async getToken() {
+		if (typeof process !== "undefined" && process.env) return process.env[this.envVar] ?? this.fallback ?? null;
+		return this.fallback ?? null;
+	}
+};
+/**
+* Pre-configured auth for sidecar connections.
+* Uses SIDECAR_AUTH_TOKEN env var (matches server expectation).
+*/
+var SidecarAuth = class extends EnvTokenAuth {
+	constructor(token) {
+		super({
+			envVar: "SIDECAR_AUTH_TOKEN",
+			fallback: token
+		});
+	}
+};
+/**
+* Product-based auth for multi-tenant orchestrator connections.
+* Uses ORCHESTRATOR_API_SECRET_KEY env var.
+*/
+var ProductAuth = class extends EnvTokenAuth {
+	constructor(apiKey) {
+		super({
+			envVar: "ORCHESTRATOR_API_SECRET_KEY",
+			fallback: apiKey
+		});
+	}
+};
+/**
+* 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}`,
+* });
+* ```
+*/
+var ProductTokenIssuer = class {
+	productId;
+	signingSecret;
+	ttlMinutes;
+	constructor(config) {
+		this.productId = config.productId;
+		this.signingSecret = config.signingSecret;
+		this.ttlMinutes = {
+			free: config.ttlMinutes?.free ?? 15,
+			pro: config.ttlMinutes?.pro ?? 240,
+			enterprise: config.ttlMinutes?.enterprise ?? 480
+		};
+	}
+	/**
+	* Issue a read token for a user session.
+	*/
+	issue(params) {
+		const tier = params.tier ?? "free";
+		const ttl = this.ttlMinutes[tier] ?? this.ttlMinutes.free;
+		return {
+			token: issueReadToken(this.signingSecret, {
+				sub: params.userId,
+				sid: params.sessionId,
+				pid: this.productId,
+				cid: params.sidecarId
+			}, ttl),
+			expiresAt: Math.floor(Date.now() / 1e3) + ttl * 60
+		};
+	}
+	/**
+	* Get the TTL in minutes for a tier.
+	*/
+	getTtlMinutes(tier = "free") {
+		return this.ttlMinutes[tier] ?? this.ttlMinutes.free;
+	}
+};
+//#endregion
+export { BatchScopedTokenPayloadSchema, CallbackAuth, CreateSessionRequestSchema, EnvTokenAuth, NoAuth, ProductAuth, ProductSchema, ProductTokenIssuer, ProjectScopedTokenPayloadSchema, READ_CAPABILITY_ROUTES, ReadTokenAuth, ReadTokenPayloadSchema, RefreshableTokenAuth, SIDECAR_CAPABILITY_ROUTES, SIDECAR_CAPABILITY_ROUTE_PATTERNS, SendMessageRequestSchema, SessionScopedTokenPayloadSchema, SidecarAuth, StaticTokenAuth, 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.js.map