langsmith 0.10.5 → 0.10.6

package/dist/sandbox/verify.cjs

@@ -0,0 +1,300 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SandboxTokenVerifier = exports.CALLBACK_SIGNATURE_HEADER = exports.USER_TOKEN_HEADER = void 0;
+const env_js_1 = require("../utils/env.cjs");
+const errors_js_1 = require("./errors.cjs");
+/** Header carrying the signed identity of a LangSmith-login service URL request. */
+exports.USER_TOKEN_HEADER = "X-Langsmith-User-Token";
+/** Header carrying the signature of a proxy callback request. */
+exports.CALLBACK_SIGNATURE_HEADER = "X-LangSmith-Signature-JWT";
+const CALLBACK_SUBJECT = "langsmith-sandbox-callback";
+const JWKS_PATH = "/.well-known/jwks.json";
+const JWKS_TTL_MS = 300_000;
+// Bounds refetches when a token names a kid the cached set lacks.
+const JWKS_MIN_REFRESH_MS = 30_000;
+const LEEWAY_SECONDS = 30;
+function fail(message) {
+    throw new errors_js_1.LangSmithSandboxTokenVerificationError(message);
+}
+function subtle() {
+    const s = globalThis.crypto?.subtle;
+    if (!s)
+        fail("Web Crypto is not available in this runtime");
+    return s;
+}
+function base64UrlDecode(value) {
+    const b64 = value.replace(/-/g, "+").replace(/_/g, "/");
+    const bin = atob(b64 + "=".repeat((4 - (b64.length % 4)) % 4));
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function decodeJson(segment) {
+    const value = JSON.parse(new TextDecoder().decode(base64UrlDecode(segment)));
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("not a JSON object");
+    }
+    return value;
+}
+function isLoopback(hostname) {
+    return (hostname === "localhost" ||
+        hostname === "[::1]" ||
+        /^127(\.\d{1,3}){3}$/.test(hostname));
+}
+function checkJwksUrl(url, allowInsecure) {
+    const { protocol, hostname } = new URL(url);
+    if (protocol === "https:" || allowInsecure)
+        return;
+    if (protocol === "http:" && isLoopback(hostname))
+        return;
+    throw new Error(`JWKS URL must use https, got ${JSON.stringify(url)}; pass ` +
+        "allowInsecureJwks: true only if the network path to LangSmith is trusted");
+}
+function jwksUrlFrom(apiUrl) {
+    return new URL(JWKS_PATH, new URL(apiUrl).origin).toString();
+}
+function serviceHost(audience) {
+    return audience.includes("://") ? new URL(audience).host : audience;
+}
+function toBytes(body) {
+    if (typeof body === "string")
+        return new TextEncoder().encode(body);
+    if (body instanceof ArrayBuffer)
+        return new Uint8Array(body);
+    return new Uint8Array(body);
+}
+function hex(buf) {
+    return Array.from(new Uint8Array(buf), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/**
+ * Verifies tokens LangSmith signs for code running in or behind a sandbox.
+ *
+ * Keys are fetched from LangSmith's JWKS endpoint and cached. Requires Web
+ * Crypto Ed25519 support (Node.js 20+, Deno, Bun, Cloudflare Workers).
+ *
+ * @example
+ * ```typescript
+ * const verifier = new SandboxTokenVerifier();
+ *
+ * // In an app served from a LangSmith-login service URL:
+ * const user = await verifier.verifyUserToken(
+ *   req.headers.get(USER_TOKEN_HEADER)!,
+ *   { audience: req.headers.get("host")! }
+ * );
+ *
+ * // In a proxy callback endpoint:
+ * const callback = await verifier.verifyCallback({
+ *   body: await req.text(),
+ *   signature: req.headers.get(CALLBACK_SIGNATURE_HEADER)!,
+ *   aud: "https://example.com/sandbox-callback",
+ * });
+ * ```
+ */
+class SandboxTokenVerifier {
+    constructor(config = {}) {
+        Object.defineProperty(this, "jwksUrl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "timeoutMs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "keys", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "fetchedAt", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "inflight", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.jwksUrl =
+            config.jwksUrl ??
+                jwksUrlFrom(config.apiUrl ??
+                    (0, env_js_1.getLangSmithEnvironmentVariable)("ENDPOINT") ??
+                    "https://api.smith.langchain.com");
+        checkJwksUrl(this.jwksUrl, config.allowInsecureJwks ?? false);
+        this.timeoutMs = config.timeoutMs ?? 10_000;
+    }
+    /**
+     * Verify the `X-Langsmith-User-Token` header of a service URL request.
+     *
+     * LangSmith sets this header only for service URLs that use LangSmith login.
+     * Code that knows it is running in a sandbox can instead trust the unsigned
+     * `X-Langsmith-User-Id` and `X-Langsmith-User-Email` headers, which the
+     * sandbox runtime strips from inbound requests and sets itself; verify this
+     * token when that is not guaranteed.
+     */
+    async verifyUserToken(token, options) {
+        const claims = await this.verify(token, serviceHost(options.audience), options.issuer);
+        const sub = claims.sub;
+        if (typeof sub !== "string" || !sub || sub === CALLBACK_SUBJECT) {
+            fail("token is not a user token");
+        }
+        return {
+            subject: sub,
+            email: typeof claims.email === "string" && claims.email
+                ? claims.email
+                : undefined,
+            name: typeof claims.name === "string" && claims.name
+                ? claims.name
+                : undefined,
+            expiresAt: new Date(claims.exp * 1000),
+        };
+    }
+    /** Verify a proxy callback request and return its parsed payload. */
+    async verifyCallback(options) {
+        const claims = await this.verify(options.signature, options.aud, options.issuer);
+        if (claims.sub !== CALLBACK_SUBJECT) {
+            fail("signature is not a callback signature");
+        }
+        const expected = claims.body_sha256;
+        if (typeof expected !== "string")
+            fail("signature has no body hash");
+        const raw = toBytes(options.body);
+        const digest = hex(await subtle().digest("SHA-256", raw));
+        if (!timingSafeEqual(expected, digest))
+            fail("body does not match signature");
+        let payload;
+        try {
+            payload = JSON.parse(new TextDecoder().decode(raw));
+        }
+        catch (e) {
+            fail(`malformed callback body: ${e.message}`);
+        }
+        const id = payload?.identity;
+        if (typeof payload?.host !== "string" ||
+            typeof payload.port !== "number" ||
+            typeof id?.tenant_id !== "string" ||
+            typeof id.sandbox_id !== "string") {
+            fail("malformed callback body");
+        }
+        return payload;
+    }
+    async verify(token, audience, issuer) {
+        const parts = token ? token.split(".") : [];
+        if (parts.length !== 3)
+            fail("malformed token");
+        let header;
+        let claims;
+        let signature;
+        try {
+            header = decodeJson(parts[0]);
+            claims = decodeJson(parts[1]);
+            signature = base64UrlDecode(parts[2]);
+        }
+        catch (e) {
+            fail(`malformed token: ${e.message}`);
+        }
+        if (header.alg !== "EdDSA") {
+            fail(`unexpected signing algorithm: ${JSON.stringify(header.alg)}`);
+        }
+        if (typeof header.kid !== "string" || !header.kid)
+            fail("token has no kid");
+        const key = await this.key(header.kid);
+        const signed = new TextEncoder().encode(`${parts[0]}.${parts[1]}`);
+        if (!(await subtle().verify({ name: "Ed25519" }, key, signature, signed))) {
+            fail("invalid signature");
+        }
+        const now = Date.now() / 1000;
+        const { exp, iat, nbf, iss, aud } = claims;
+        if (typeof exp !== "number")
+            fail("token has no exp");
+        if (now > exp + LEEWAY_SECONDS)
+            fail("token is expired");
+        if (typeof iat !== "number")
+            fail("token has no iat");
+        if (iat > now + LEEWAY_SECONDS)
+            fail("token is not yet valid");
+        if (nbf !== undefined &&
+            (typeof nbf !== "number" || nbf > now + LEEWAY_SECONDS)) {
+            fail("token is not yet valid");
+        }
+        if (typeof iss !== "string")
+            fail("token has no iss");
+        if (issuer !== undefined && iss !== issuer.replace(/\/+$/, "")) {
+            fail("token has the wrong issuer");
+        }
+        const audiences = typeof aud === "string" ? [aud] : Array.isArray(aud) ? aud : [];
+        const matches = typeof audience === "function"
+            ? audiences.some((a) => typeof a === "string" && audience(a))
+            : audiences.includes(audience);
+        if (audience !== undefined && !matches) {
+            fail("token has the wrong audience");
+        }
+        return claims;
+    }
+    async key(kid) {
+        const age = Date.now() - this.fetchedAt;
+        const fresh = this.keys.has(kid) && age < JWKS_TTL_MS;
+        if (!fresh && (this.fetchedAt === 0 || age >= JWKS_MIN_REFRESH_MS)) {
+            this.inflight ??= this.refresh().finally(() => {
+                this.inflight = undefined;
+            });
+            await this.inflight;
+        }
+        const key = this.keys.get(kid);
+        if (!key)
+            fail(`unknown signing key: ${kid}`);
+        try {
+            return await key;
+        }
+        catch (e) {
+            fail(`signing key ${kid} is not a usable Ed25519 key: ${e.message}`);
+        }
+    }
+    async refresh() {
+        let body;
+        try {
+            const resp = await fetch(this.jwksUrl, {
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+            if (!resp.ok)
+                throw new Error(`HTTP ${resp.status}`);
+            body = await resp.json();
+        }
+        catch (e) {
+            fail(`failed to fetch JWKS from ${this.jwksUrl}: ${e.message}`);
+        }
+        const entries = body?.keys;
+        if (!Array.isArray(entries)) {
+            fail("invalid JWKS: expected an object with a keys array");
+        }
+        const keys = new Map();
+        for (const jwk of entries) {
+            if (typeof jwk !== "object" || jwk === null)
+                continue;
+            if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || !jwk.kid || !jwk.x)
+                continue;
+            const imported = subtle().importKey("jwk", { kty: "OKP", crv: "Ed25519", x: jwk.x }, { name: "Ed25519" }, false, ["verify"]);
+            imported.catch(() => undefined);
+            keys.set(jwk.kid, imported);
+        }
+        this.keys = keys;
+        this.fetchedAt = Date.now();
+    }
+}
+exports.SandboxTokenVerifier = SandboxTokenVerifier;

package/dist/sandbox/verify.d.ts

@@ -0,0 +1,122 @@
+/** Header carrying the signed identity of a LangSmith-login service URL request. */
+export declare const USER_TOKEN_HEADER = "X-Langsmith-User-Token";
+/** Header carrying the signature of a proxy callback request. */
+export declare const CALLBACK_SIGNATURE_HEADER = "X-LangSmith-Signature-JWT";
+/** The LangSmith user a service URL request was made by. */
+export interface SandboxUser {
+    subject: string;
+    email?: string;
+    name?: string;
+    expiresAt: Date;
+}
+/** The sandbox whose outbound request triggered a proxy callback. */
+export interface SandboxCallbackIdentity {
+    tenant_id: string;
+    sandbox_id: string;
+    organization_id?: string;
+    ls_user_id?: string;
+}
+/** Snapshot of the outbound request, sent for `full_request` callbacks. */
+export interface SandboxCallbackRequest {
+    method: string;
+    url: string;
+    scheme: string;
+    host: string;
+    path: string;
+    query?: string;
+    headers: Record<string, string[]>;
+    body_base64: string;
+    body_truncated: boolean;
+}
+/** A verified proxy callback payload. */
+export interface SandboxCallback {
+    host: string;
+    port: number;
+    identity: SandboxCallbackIdentity;
+    request?: SandboxCallbackRequest;
+}
+export interface SandboxTokenVerifierConfig {
+    /** LangSmith API URL whose origin serves the JWKS. Defaults to LANGSMITH_ENDPOINT. */
+    apiUrl?: string;
+    /** Full JWKS URL; overrides `apiUrl`. */
+    jwksUrl?: string;
+    /** Timeout in milliseconds for fetching the JWKS. */
+    timeoutMs?: number;
+    /**
+     * Allow fetching the JWKS over plain HTTP from a non-loopback host. Anyone
+     * who can tamper with that traffic can forge tokens this verifier accepts.
+     */
+    allowInsecureJwks?: boolean;
+}
+export interface VerifyUserTokenOptions {
+    /**
+     * The service URL host the request was sent to, such as the request's
+     * `Host` header. A full service URL is also accepted.
+     */
+    audience: string;
+    /** If set, the LangSmith app URL the token must be issued by. */
+    issuer?: string;
+}
+export interface VerifyCallbackOptions {
+    /** The raw request body, exactly as received. */
+    body: string | Uint8Array | ArrayBuffer;
+    /** The `X-LangSmith-Signature-JWT` header value. */
+    signature: string;
+    /**
+     * If set, checks the signature's audience, which is the callback URL as
+     * configured in the proxy config. A string must match exactly; a predicate
+     * is called with each audience and must return true for at least one.
+     */
+    aud?: AudienceMatcher;
+    /** If set, the LangSmith OAuth issuer the signature must be issued by. */
+    issuer?: string;
+}
+/** An exact audience, or a predicate called with each audience in the token. */
+export type AudienceMatcher = string | ((aud: string) => boolean);
+/**
+ * Verifies tokens LangSmith signs for code running in or behind a sandbox.
+ *
+ * Keys are fetched from LangSmith's JWKS endpoint and cached. Requires Web
+ * Crypto Ed25519 support (Node.js 20+, Deno, Bun, Cloudflare Workers).
+ *
+ * @example
+ * ```typescript
+ * const verifier = new SandboxTokenVerifier();
+ *
+ * // In an app served from a LangSmith-login service URL:
+ * const user = await verifier.verifyUserToken(
+ *   req.headers.get(USER_TOKEN_HEADER)!,
+ *   { audience: req.headers.get("host")! }
+ * );
+ *
+ * // In a proxy callback endpoint:
+ * const callback = await verifier.verifyCallback({
+ *   body: await req.text(),
+ *   signature: req.headers.get(CALLBACK_SIGNATURE_HEADER)!,
+ *   aud: "https://example.com/sandbox-callback",
+ * });
+ * ```
+ */
+export declare class SandboxTokenVerifier {
+    private readonly jwksUrl;
+    private readonly timeoutMs;
+    private keys;
+    private fetchedAt;
+    private inflight?;
+    constructor(config?: SandboxTokenVerifierConfig);
+    /**
+     * Verify the `X-Langsmith-User-Token` header of a service URL request.
+     *
+     * LangSmith sets this header only for service URLs that use LangSmith login.
+     * Code that knows it is running in a sandbox can instead trust the unsigned
+     * `X-Langsmith-User-Id` and `X-Langsmith-User-Email` headers, which the
+     * sandbox runtime strips from inbound requests and sets itself; verify this
+     * token when that is not guaranteed.
+     */
+    verifyUserToken(token: string, options: VerifyUserTokenOptions): Promise<SandboxUser>;
+    /** Verify a proxy callback request and return its parsed payload. */
+    verifyCallback(options: VerifyCallbackOptions): Promise<SandboxCallback>;
+    private verify;
+    private key;
+    private refresh;
+}