@m1a0rz/agent-identity 0.4.6 → 0.5.0

package/dist/src/local-server/handlers.js

@@ -0,0 +1,207 @@
+/*
+ * Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { getOrRefreshTIPToken } from "../services/tip-with-refresh.js";
+import { getSessionWithRefresh } from "../services/session-refresh.js";
+import { getAllTIPTokens } from "../store/tip-store.js";
+import { isPersonalSessionModeEnabled, PERSONAL_SESSION_STORAGE_KEY, } from "../store/sender-session-store.js";
+const MAIN_SESSION_KEY = "agent:main:main";
+function resolveMainSessionKey() {
+    if (isPersonalSessionModeEnabled())
+        return PERSONAL_SESSION_STORAGE_KEY;
+    return MAIN_SESSION_KEY;
+}
+function json(res, status, body) {
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(body));
+}
+function parseSessionKeyFromUrl(url) {
+    if (!url)
+        return null;
+    try {
+        const u = new URL(url, "http://localhost");
+        return u.searchParams.get("session");
+    }
+    catch {
+        return null;
+    }
+}
+export function createRequestHandler(deps) {
+    const { storeDir, identityService, configWorkloadName, getOidcConfigForRefresh, logger } = deps;
+    const toolFactories = deps.toolFactories ?? new Map();
+    const tipRefreshOptions = {
+        identityService,
+        getOidcConfigForRefresh,
+        configWorkloadName,
+        logger,
+    };
+    const TOOL_PREFIX = "/tool/";
+    let cachedToolList = null;
+    return async (req, res) => {
+        const pathname = req.url?.split("?")[0];
+        try {
+            if (req.method === "GET" && pathname === "/token") {
+                await handleGetToken(req, res);
+            }
+            else if (req.method === "GET" && pathname === "/session") {
+                await handleGetSession(req, res);
+            }
+            else if (req.method === "GET" && pathname === "/status") {
+                handleGetStatus(res);
+            }
+            else if (req.method === "GET" && pathname === "/tools") {
+                handleListTools(res);
+            }
+            else if (req.method === "POST" && pathname?.startsWith(TOOL_PREFIX)) {
+                const toolName = decodeURIComponent(pathname.slice(TOOL_PREFIX.length));
+                await handleToolCall(req, res, toolName);
+            }
+            else {
+                json(res, 404, { error: "not_found", message: `Unknown route: ${req.method} ${pathname}` });
+            }
+        }
+        catch (err) {
+            logger.warn?.(`local-server: handler error: ${String(err)}`);
+            json(res, 500, { error: "internal_error", message: String(err) });
+        }
+    };
+    async function handleGetToken(req, res) {
+        const explicitSession = parseSessionKeyFromUrl(req.url);
+        const sessionKey = explicitSession ?? resolveMainSessionKey();
+        logger.debug?.(`local-server: GET /token sessionKey=${sessionKey.slice(0, 24)}...`);
+        const tip = await getOrRefreshTIPToken(storeDir, sessionKey, tipRefreshOptions);
+        if (!tip) {
+            json(res, 401, {
+                error: "no_token",
+                message: "No TIP token available for this session. Login required.",
+                sessionKey,
+            });
+            return;
+        }
+        json(res, 200, {
+            tipToken: tip.token,
+            sub: tip.sub,
+            issuedAt: tip.issuedAt,
+            expiresAt: tip.expiresAt,
+            sessionKey,
+        });
+    }
+    async function handleGetSession(req, res) {
+        const explicitSession = parseSessionKeyFromUrl(req.url);
+        const sessionKey = explicitSession ?? resolveMainSessionKey();
+        logger.debug?.(`local-server: GET /session sessionKey=${sessionKey.slice(0, 24)}...`);
+        const session = await getSessionWithRefresh(storeDir, sessionKey, getOidcConfigForRefresh);
+        if (!session?.userToken) {
+            json(res, 401, {
+                error: "no_session",
+                message: "No OIDC session found. Login required.",
+                sessionKey,
+            });
+            return;
+        }
+        json(res, 200, {
+            sessionIdToken: session.userToken,
+            sub: session.sub,
+            loginAt: session.loginAt,
+            expiresAt: session.expiresAt ?? null,
+            sessionKey,
+        });
+    }
+    function handleGetStatus(res) {
+        const allTips = getAllTIPTokens();
+        const now = Date.now();
+        const sessions = Object.entries(allTips).map(([key, entry]) => ({
+            sessionKey: key,
+            sub: entry.sub,
+            expiresAt: entry.expiresAt,
+            ttlSec: Math.max(0, Math.floor((entry.expiresAt - now) / 1000)),
+        }));
+        json(res, 200, {
+            ok: true,
+            personalSessionMode: isPersonalSessionModeEnabled(),
+            mainSessionKey: resolveMainSessionKey(),
+            activeSessions: sessions.length,
+            sessions,
+        });
+    }
+    function handleListTools(res) {
+        if (!cachedToolList) {
+            cachedToolList = [];
+            for (const [, factory] of toolFactories) {
+                const tool = factory({});
+                cachedToolList.push({
+                    name: tool.name,
+                    description: tool.description,
+                    parameters: tool.parameters,
+                });
+            }
+            cachedToolList.sort((a, b) => a.name.localeCompare(b.name));
+        }
+        json(res, 200, { tools: cachedToolList });
+    }
+    async function handleToolCall(req, res, toolName) {
+        const factory = toolFactories.get(toolName);
+        if (!factory) {
+            json(res, 404, { error: "unknown_tool", message: `Tool "${toolName}" not found`, available: Array.from(toolFactories.keys()).sort() });
+            return;
+        }
+        const body = await readBody(req);
+        if (body === null) {
+            json(res, 400, { error: "bad_request", message: "Invalid JSON body. Expected { params?: {}, session?: string }" });
+            return;
+        }
+        const params = body.params ?? {};
+        const sessionKey = typeof body.session === "string" && body.session ? body.session : resolveMainSessionKey();
+        const ctx = { sessionKey };
+        const tool = factory(ctx);
+        const toolCallId = `uds-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        logger.debug?.(`local-server: POST /tool/${toolName} session=${sessionKey.slice(0, 24)}...`);
+        try {
+            const result = await tool.execute(toolCallId, params);
+            json(res, 200, { tool: toolName, result: result.details ?? null, sessionKey });
+        }
+        catch (err) {
+            logger.warn?.(`local-server: tool ${toolName} error: ${String(err)}`);
+            json(res, 500, { error: "tool_error", tool: toolName, message: String(err) });
+        }
+    }
+}
+/** Read and parse JSON body from an IncomingMessage. Returns null on failure. */
+function readBody(req) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => {
+            try {
+                const raw = Buffer.concat(chunks).toString("utf-8");
+                if (!raw.trim()) {
+                    resolve({});
+                    return;
+                }
+                const parsed = JSON.parse(raw);
+                if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+                    resolve(parsed);
+                }
+                else {
+                    resolve(null);
+                }
+            }
+            catch {
+                resolve(null);
+            }
+        });
+        req.on("error", () => resolve(null));
+    });
+}

package/dist/src/local-server/identity-socket.d.ts

@@ -0,0 +1,18 @@
+import { type LocalServerDeps } from "./handlers.js";
+export type IdentitySocketOptions = LocalServerDeps & {
+    /** Override socket directory (defaults to storeDir). */
+    socketDir?: string;
+    /** Additional process names/paths allowed to connect (beyond defaults). */
+    allowlist?: readonly string[];
+    /**
+     * When peer resolution fails (lsof unavailable, timing race, etc.),
+     * allow the request through with a warning log. Default: true.
+     */
+    failOpen?: boolean;
+};
+export declare function startIdentitySocket(opts: IdentitySocketOptions): Promise<string>;
+export declare function stopIdentitySocket(logger?: {
+    info?: (msg: string) => void;
+}): Promise<void>;
+export declare function getSocketPath(): string | null;
+//# sourceMappingURL=identity-socket.d.ts.map

package/dist/src/local-server/identity-socket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-socket.d.ts","sourceRoot":"","sources":["../../../src/local-server/identity-socket.ts"],"names":[],"mappings":"AAqCA,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAM3E,MAAM,MAAM,qBAAqB,GAAG,eAAe,GAAG;IACpD,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AA2EF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CAkGhF;AAED,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB3F;AAED,wBAAgB,aAAa,IAAI,MAAM,GAAG,IAAI,CAE7C"}

package/dist/src/local-server/identity-socket.js

@@ -0,0 +1,198 @@
+/*
+ * Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * HTTP-over-UDS server for local identity token access.
+ *
+ * Other processes on the same machine can connect to the Unix domain socket
+ * to retrieve TIP tokens and session info without network exposure.
+ *
+ * Security layers:
+ *   1. Socket file mode 0600 — only the same OS user can connect.
+ *   2. Peer process check — uses `lsof` to identify the connecting process
+ *      and validates it against an allowlist (default: curl, wget, python, etc.).
+ *
+ * Lifecycle:
+ *   - startIdentitySocket() creates the server and listens on the socket path.
+ *   - stopIdentitySocket() gracefully shuts down and removes the socket file.
+ *   - Stale socket files from crashed processes are cleaned up on start.
+ */
+import { createServer } from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import { createRequestHandler } from "./handlers.js";
+import { checkPeer, registerPeerCredProvider, hasPeerCredProvider, setPeerCheckLogger } from "./peer-check.js";
+import { tryBuildPeerCredProvider } from "./peercred-linux.js";
+const SOCKET_FILENAME = "identity.sock";
+let server = null;
+let currentSocketPath = null;
+function resolveSocketPath(opts) {
+    const dir = opts.socketDir ?? opts.storeDir;
+    return path.join(dir, SOCKET_FILENAME);
+}
+function cleanupStaleSocket(socketPath) {
+    try {
+        const stat = fs.statSync(socketPath);
+        if (stat.isSocket()) {
+            fs.unlinkSync(socketPath);
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw err;
+        }
+    }
+}
+function ensureDirectory(dir) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+// ─── Per-connection peer info cache ──────────────────────────────────
+const peerCache = new WeakMap();
+/** Extract the raw fd from a Node.js Socket for SO_PEERCRED. */
+function getSocketFd(socket) {
+    // Node.js internal: _handle is a Pipe (libuv) wrapping the fd.
+    // Safe to access — returns -1 if unavailable so checkPeer falls back.
+    const handle = socket._handle;
+    return typeof handle?.fd === "number" ? handle.fd : -1;
+}
+function resolvePeerForSocket(socket, allowlist, failOpen, logger) {
+    const cached = peerCache.get(socket);
+    if (cached?.checked) {
+        return { allowed: true, peer: cached.info };
+    }
+    const fd = getSocketFd(socket);
+    const result = checkPeer(allowlist, failOpen, fd);
+    peerCache.set(socket, { info: result.peer ?? null, checked: true });
+    if (!result.allowed) {
+        logger.warn?.(`local-server: REJECTED connection: ${result.reason}`);
+        return { allowed: false, peer: result.peer ?? null };
+    }
+    if (result.peer) {
+        logger.debug?.(`local-server: accepted connection from ${result.peer.processName} ` +
+            `(pid=${result.peer.pid}, path=${result.peer.processPath})`);
+    }
+    else {
+        logger.debug?.("local-server: accepted connection (peer unresolvable, fail-open)");
+    }
+    return { allowed: true, peer: result.peer ?? null };
+}
+// ─── Server lifecycle ────────────────────────────────────────────────
+export function startIdentitySocket(opts) {
+    if (server) {
+        opts.logger.warn?.("local-server: already running, skipping duplicate start");
+        return Promise.resolve(currentSocketPath);
+    }
+    const socketPath = resolveSocketPath(opts);
+    const socketDir = path.dirname(socketPath);
+    const allowlist = opts.allowlist ?? [];
+    const failOpen = opts.failOpen ?? true;
+    ensureDirectory(socketDir);
+    cleanupStaleSocket(socketPath);
+    const handler = createRequestHandler(opts);
+    // Wire peer-check debug/warn to the plugin logger
+    setPeerCheckLogger({
+        debug: (msg) => opts.logger.debug?.(msg),
+        warn: (msg) => opts.logger.warn?.(msg),
+    });
+    // Auto-register SO_PEERCRED provider via koffi (Linux only, optional)
+    if (!hasPeerCredProvider()) {
+        const provider = tryBuildPeerCredProvider(opts.logger);
+        if (provider) {
+            registerPeerCredProvider(provider);
+            opts.logger.info?.("local-server: SO_PEERCRED provider registered via koffi");
+        }
+        else {
+            opts.logger.debug?.("local-server: SO_PEERCRED provider not available, using fail-open policy");
+        }
+    }
+    server = createServer((req, res) => {
+        const method = req.method ?? "?";
+        const url = req.url ?? "/";
+        // ── Peer process check ────────────────────────────────────────
+        const { allowed, peer } = resolvePeerForSocket(req.socket, allowlist, failOpen, opts.logger);
+        if (!allowed) {
+            const peerDesc = peer
+                ? `${peer.processName} (pid=${peer.pid}, uid=${peer.uid}, path=${peer.processPath})`
+                : "unknown";
+            opts.logger.warn?.(`local-server: REJECTED ${method} ${url} from ${peerDesc}`);
+            res.writeHead(403, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                error: "forbidden",
+                message: "Process not in allowlist. Configure identity.localServerAllowlist to grant access.",
+                process: peer ? {
+                    pid: peer.pid,
+                    name: peer.processName,
+                    path: peer.processPath,
+                } : null,
+            }));
+            return;
+        }
+        const peerDesc = peer
+            ? `${peer.processName}(pid=${peer.pid})`
+            : "unknown-peer";
+        opts.logger.debug?.(`local-server: ${method} ${url} from ${peerDesc}`);
+        handler(req, res).catch((err) => {
+            opts.logger.warn?.(`local-server: unhandled error on ${method} ${url}: ${String(err)}`);
+            if (!res.headersSent) {
+                res.writeHead(500, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "internal_error" }));
+            }
+        });
+    });
+    server.unref();
+    return new Promise((resolve, reject) => {
+        server.on("error", (err) => {
+            opts.logger.warn?.(`local-server: server error: ${String(err)}`);
+            reject(err);
+        });
+        server.listen(socketPath, () => {
+            try {
+                fs.chmodSync(socketPath, 0o600);
+            }
+            catch (err) {
+                opts.logger.warn?.(`local-server: failed to chmod socket: ${String(err)}`);
+            }
+            currentSocketPath = socketPath;
+            opts.logger.info?.(`local-server: listening on ${socketPath} (peer check enabled, fail-open=${failOpen})`);
+            resolve(socketPath);
+        });
+    });
+}
+export function stopIdentitySocket(logger) {
+    return new Promise((resolve) => {
+        if (!server) {
+            resolve();
+            return;
+        }
+        const sock = currentSocketPath;
+        server.close(() => {
+            if (sock) {
+                try {
+                    fs.unlinkSync(sock);
+                }
+                catch {
+                    // already removed
+                }
+            }
+            logger?.info?.(`local-server: stopped (socket ${sock ?? "unknown"})`);
+            server = null;
+            currentSocketPath = null;
+            resolve();
+        });
+    });
+}
+export function getSocketPath() {
+    return currentSocketPath;
+}

package/dist/src/local-server/peer-check.d.ts

@@ -0,0 +1,58 @@
+export type PeerCheckLogger = {
+    debug?: (msg: string) => void;
+    warn?: (msg: string) => void;
+};
+export declare function setPeerCheckLogger(logger: PeerCheckLogger): void;
+export type PeerInfo = {
+    pid: number;
+    uid: number;
+    gid: number;
+    processName: string;
+    processPath: string;
+};
+export type PeerCredentials = {
+    pid: number;
+    uid: number;
+    gid: number;
+};
+export type GetPeerCredFn = (fd: number) => PeerCredentials | null;
+/**
+ * Register a native SO_PEERCRED provider. Call this at startup if a native
+ * binding (N-API addon, koffi FFI, etc.) is available.
+ *
+ * Example with a hypothetical native addon:
+ *   import { getPeerCred } from "./peercred.node";
+ *   registerPeerCredProvider(getPeerCred);
+ *
+ * The provider receives the connected socket fd and must return
+ * { pid, uid, gid } or null on failure.
+ */
+export declare function registerPeerCredProvider(fn: GetPeerCredFn): void;
+/** True when a native SO_PEERCRED provider is registered. */
+export declare function hasPeerCredProvider(): boolean;
+/**
+ * Check whether a peer process is in the allowlist.
+ *
+ * Matching rules (any match = allowed):
+ *   1. Exact basename match: "curl" matches /usr/bin/curl
+ *   2. Full path match: "/usr/bin/curl" matches exactly
+ *   3. Glob suffix: "python*" matches python3, python3.11
+ */
+export declare function isProcessAllowed(peer: PeerInfo, customAllowlist?: readonly string[]): boolean;
+/**
+ * Resolve and validate the peer process for a UDS connection.
+ *
+ * @param customAllowlist  Extra process names/paths to allow.
+ * @param failOpen    If true, allow when SO_PEERCRED is unavailable
+ *                    (socket 0600 still provides UID-level protection).
+ * @param socketFd    The accepted connection socket's fd (for SO_PEERCRED).
+ */
+export declare function checkPeer(customAllowlist: readonly string[], failOpen: boolean, socketFd?: number): {
+    allowed: true;
+    peer: PeerInfo | null;
+} | {
+    allowed: false;
+    reason: string;
+    peer?: PeerInfo;
+};
+//# sourceMappingURL=peer-check.d.ts.map

package/dist/src/local-server/peer-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-check.d.ts","sourceRoot":"","sources":["../../../src/local-server/peer-check.ts"],"names":[],"mappings":"AA+CA,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B,CAAC;AAIF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAEhE;AAED,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AACxE,MAAM,MAAM,aAAa,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,eAAe,GAAG,IAAI,CAAC;AAoBnE;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,aAAa,GAAG,IAAI,CAEhE;AAED,6DAA6D;AAC7D,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAoED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,QAAQ,EACd,eAAe,GAAE,SAAS,MAAM,EAAO,GACtC,OAAO,CAUT;AAID;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,eAAe,EAAE,SAAS,MAAM,EAAE,EAClC,QAAQ,EAAE,OAAO,EACjB,QAAQ,GAAE,MAAW,GACpB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,QAAQ,CAAA;CAAE,CAiChG"}