@portel/photon 1.33.0 → 1.33.2

package/dist/server.js

@@ -26,11 +26,27 @@ import { pingDaemon } from './daemon/client.js';
 import { ensureDaemon } from './daemon/manager.js';
 import { ChannelManager, } from './channel-manager.js';
 import { PhotonDocExtractor } from './photon-doc-extractor.js';
-import { isLocalRequest, readBody, setSecurityHeaders, getCorsOrigin } from './shared/security.js';
+import { isLocalRequest, setSecurityHeaders, getCorsOrigin } from './shared/security.js';
 import { audit } from './shared/audit.js';
 import { TaskExecutor } from './task-executor.js';
 import { CapabilityNegotiator } from './capability-negotiator.js';
 import { ResourceServer, SubscriptionRegistry, } from './resource-server.js';
+import { verifyPhotonAuthToken } from './auth/mcp-jwt.js';
+import { loadPhotonAuth } from './cli/commands/auth.js';
+let cachedJwtProfile = null;
+async function loadJwtProfile(name) {
+    if (cachedJwtProfile && cachedJwtProfile.name === name) {
+        return { issuer: cachedJwtProfile.issuer, jwks: cachedJwtProfile.jwks };
+    }
+    try {
+        const loaded = await loadPhotonAuth(name);
+        cachedJwtProfile = { name, issuer: loaded.issuer.issuer, jwks: loaded.jwks };
+        return { issuer: loaded.issuer.issuer, jwks: loaded.jwks };
+    }
+    catch {
+        return null;
+    }
+}
 export class HotReloadDisabledError extends Error {
     constructor(message) {
         super(message);
@@ -209,6 +225,38 @@ function findFreePort(preferred = 0) {
         srv.on('error', reject);
     });
 }
+function localMcpAuthMode() {
+    return process.env.PHOTON_MCP_AUTH_MODE || (process.env.PHOTON_MCP_BEARER ? 'bearer' : 'legacy');
+}
+function authHeaderToken(req) {
+    const header = req.headers.authorization ?? '';
+    const match = Array.isArray(header)
+        ? header[0]?.match(/^Bearer\s+(.+)$/i)
+        : header.match(/^Bearer\s+(.+)$/i);
+    return match ? match[1].trim() : null;
+}
+function unauthorizedJson(res, id, status, code, message, reason, wwwAuthenticate, corsOrigin) {
+    const headers = {
+        'Content-Type': 'application/json',
+        'WWW-Authenticate': wwwAuthenticate,
+    };
+    if (corsOrigin)
+        headers['Access-Control-Allow-Origin'] = corsOrigin;
+    res.writeHead(status, headers);
+    res.end(JSON.stringify({
+        jsonrpc: '2.0',
+        id: id ?? null,
+        error: { code, message, data: { reason } },
+    }));
+}
+function mcpTokenMatches(actual, expected) {
+    if (!actual || !expected)
+        return false;
+    const actualBytes = Buffer.from(actual);
+    const expectedBytes = Buffer.from(expected);
+    return (actualBytes.length === expectedBytes.length &&
+        crypto.timingSafeEqual(actualBytes, expectedBytes));
+}
 class BeamCompatTransport {
     photonName;
     photonMeta;
@@ -220,6 +268,8 @@ class BeamCompatTransport {
     pendingResponse = null;
     /** Sub-photons whose tools are injected into tools/list alongside the main photon. */
     subPhotons = [];
+    /** Main photon tools, mirrored so auth can enforce scopes before dispatch. */
+    mainTools = [];
     /** Callback to execute a tool on a sub-photon by name. */
     subPhotonExecutor;
     constructor(photonName, photonMeta) {
@@ -237,12 +287,14 @@ class BeamCompatTransport {
         this.onclose?.();
     }
     async send(message) {
-        // Transform outgoing tools/list responses: prefix names + add x-photon-* metadata
+        // Transform outgoing tools/list responses with Photon metadata. Main photon
+        // tools stay slashless for broad client compatibility; aggregated tools use
+        // dot names (`photon.method`) while tools/call still accepts legacy slashes.
         if (message?.result?.tools && Array.isArray(message.result.tools)) {
             // Main photon tools
             message.result.tools = message.result.tools.map((tool) => ({
                 ...tool,
-                name: `${this.photonName}/${tool.name}`,
+                name: tool.name,
                 'x-photon-id': this.photonName,
                 'x-photon-description': this.photonMeta.description || '',
                 'x-photon-icon': this.photonMeta.icon || '⚡',
@@ -260,7 +312,7 @@ class BeamCompatTransport {
                 const subTools = sub.tools.map((tool) => {
                     const def = {
                         ...tool,
-                        name: `${sub.name}/${tool.name}`,
+                        name: `${sub.name}.${tool.name}`,
                         'x-photon-id': sub.name,
                         'x-photon-description': sub.description,
                         'x-photon-icon': sub.icon,
@@ -300,6 +352,20 @@ class BeamCompatTransport {
             this.sseResponse.write(`event: message\nid: ${id}\ndata: ${JSON.stringify(message)}\n\n`);
         }
     }
+    requiredScopesForTool(fullToolName) {
+        const dotIdx = fullToolName.indexOf('.');
+        const slashIdx = fullToolName.indexOf('/');
+        const separatorIdx = dotIdx !== -1 ? dotIdx : slashIdx;
+        const targetPhoton = separatorIdx === -1 ? this.photonName : fullToolName.slice(0, separatorIdx);
+        const methodName = separatorIdx === -1 ? fullToolName : fullToolName.slice(separatorIdx + 1);
+        const tools = targetPhoton === this.photonName
+            ? this.mainTools
+            : this.subPhotons.find((sub) => sub.name === targetPhoton)?.tools;
+        const scopes = tools?.find((tool) => tool.name === methodName)?.scopes;
+        return Array.isArray(scopes)
+            ? scopes.filter((scope) => typeof scope === 'string')
+            : [];
+    }
     async handleHTTP(req, res, url) {
         const corsOrigin = getCorsOrigin(req);
         // GET — open SSE stream for server-to-client notifications
@@ -357,13 +423,75 @@ class BeamCompatTransport {
                 res.end(JSON.stringify({ error: 'Invalid JSON' }));
                 return;
             }
-            // Transform incoming tools/call: strip photonName/ prefix from tool name
+            const authMode = localMcpAuthMode();
+            const dispatchesUserCode = parsed?.method === 'tools/call';
+            const requiredScopes = dispatchesUserCode && typeof parsed?.params?.name === 'string'
+                ? this.requiredScopesForTool(parsed.params.name)
+                : [];
+            let jwtClaims;
+            if (dispatchesUserCode && authMode === 'jwt') {
+                let jwks = null;
+                let issuer;
+                const profileName = process.env.PHOTON_MCP_JWT_PROFILE;
+                if (profileName) {
+                    const profile = await loadJwtProfile(profileName);
+                    if (profile) {
+                        issuer = profile.issuer;
+                        jwks = profile.jwks;
+                    }
+                }
+                else {
+                    try {
+                        jwks = process.env.PHOTON_MCP_JWT_JWKS
+                            ? JSON.parse(process.env.PHOTON_MCP_JWT_JWKS)
+                            : null;
+                    }
+                    catch {
+                        jwks = null;
+                    }
+                    issuer = process.env.PHOTON_MCP_JWT_ISSUER;
+                }
+                const audience = process.env.PHOTON_MCP_JWT_AUDIENCE;
+                if (!issuer || !audience || !jwks) {
+                    unauthorizedJson(res, parsed.id, 401, -32001, 'Unauthorized', 'missing_token', 'Bearer realm="photon", error="invalid_token"', corsOrigin);
+                    return;
+                }
+                const result = verifyPhotonAuthToken(authHeaderToken(req), {
+                    issuer,
+                    audience,
+                    jwks,
+                    requiredScopes,
+                });
+                if (!result.ok) {
+                    const insufficientScope = result.reason === 'insufficient_scope';
+                    unauthorizedJson(res, parsed.id, insufficientScope ? 403 : 401, insufficientScope ? -32003 : -32001, insufficientScope ? 'Forbidden' : 'Unauthorized', result.reason, insufficientScope
+                        ? `Bearer realm="photon", error="insufficient_scope", scope="${requiredScopes.join(' ')}"`
+                        : 'Bearer realm="photon", error="invalid_token"', corsOrigin);
+                    return;
+                }
+                jwtClaims = result.claims;
+            }
+            else if (dispatchesUserCode && authMode === 'bearer') {
+                const expected = process.env.PHOTON_MCP_BEARER;
+                const token = authHeaderToken(req);
+                if (!mcpTokenMatches(token, expected)) {
+                    unauthorizedJson(res, parsed.id, 401, -32001, 'Unauthorized', !expected
+                        ? 'Authorization: Bearer <token> header missing'
+                        : token
+                            ? 'bearer token does not match PHOTON_MCP_BEARER'
+                            : 'Authorization: Bearer <token> header missing', 'Bearer realm="photon"', corsOrigin);
+                    return;
+                }
+            }
+            // Transform incoming tools/call: strip photonName.method prefix from tool name
             // and route sub-photon calls directly
             if (parsed.method === 'tools/call' && parsed.params?.name) {
+                const dotIdx = parsed.params.name.indexOf('.');
                 const slashIdx = parsed.params.name.indexOf('/');
-                if (slashIdx !== -1) {
-                    const targetPhoton = parsed.params.name.slice(0, slashIdx);
-                    const methodName = parsed.params.name.slice(slashIdx + 1);
+                const separatorIdx = dotIdx !== -1 ? dotIdx : slashIdx;
+                if (separatorIdx !== -1) {
+                    const targetPhoton = parsed.params.name.slice(0, separatorIdx);
+                    const methodName = parsed.params.name.slice(separatorIdx + 1);
                     // Check if this is a sub-photon call
                     if (targetPhoton !== this.photonName && this.subPhotonExecutor) {
                         const sub = this.subPhotons.find((s) => s.name === targetPhoton);
@@ -411,11 +539,16 @@ class BeamCompatTransport {
             // claims ride on the SDK's MessageExtraInfo.authInfo.extra, which
             // the protocol layer propagates to setRequestHandler's `extra` arg.
             const { extractClaimsFromHeaders } = await import('./shared/extract-claims.js');
-            const claims = extractClaimsFromHeaders(req.headers);
+            const claims = jwtClaims ?? extractClaimsFromHeaders(req.headers);
             const messageExtra = claims
                 ? {
                     sessionId: this.sessionId,
-                    authInfo: { token: '', clientId: '', scopes: [], extra: claims },
+                    authInfo: {
+                        token: '',
+                        clientId: typeof claims.client_id === 'string' ? claims.client_id : '',
+                        scopes: typeof claims.scope === 'string' ? claims.scope.split(/\s+/) : [],
+                        extra: claims,
+                    },
                 }
                 : { sessionId: this.sessionId };
             // Notifications have no id — fire-and-forget
@@ -1011,8 +1144,12 @@ export class PhotonServer {
                 const notice = typeof deprecated === 'string' ? deprecated : 'This tool is deprecated.';
                 description = `[DEPRECATED: ${notice}] ${description}`;
             }
+            const slashlessName = tool.name.includes('/') ? tool.name.split('/').pop() : tool.name;
+            const toolName = slashlessName.includes('.')
+                ? slashlessName.split('.').pop()
+                : slashlessName;
             const toolDef = {
-                name: tool.name,
+                name: toolName,
                 description,
                 inputSchema: JSON.parse(JSON.stringify(tool.inputSchema)),
             };
@@ -1045,6 +1182,8 @@ export class PhotonServer {
                 toolDef['x-output-format'] = schema.outputFormat;
             if (schema.layoutHints)
                 toolDef['x-layout-hints'] = schema.layoutHints;
+            if (schema.scopes)
+                toolDef.scopes = schema.scopes;
             if (schema.buttonLabel)
                 toolDef['x-button-label'] = schema.buttonLabel;
             if (schema.icon)
@@ -1307,11 +1446,22 @@ export class PhotonServer {
         const tool = targetMcp.tools.find((t) => t.name === toolName);
         const outputFormat = tool?.outputFormat;
         const startTime = Date.now();
+        const claims = extra?.authInfo?.extra;
+        const caller = claims && typeof claims.sub === 'string'
+            ? {
+                id: claims.sub,
+                name: typeof claims.name === 'string' ? claims.name : undefined,
+                anonymous: false,
+                scope: typeof claims.scope === 'string' ? claims.scope : undefined,
+                claims,
+            }
+            : undefined;
         const result = await this.loader.executeTool(targetMcp, toolName, args || {}, {
             inputProvider,
             outputHandler,
             samplingProvider,
             roots: this.rootsByServer.get(ctx.server),
+            caller,
         });
         const durationMs = Date.now() - startTime;
         const transport = this.options.transport || 'stdio';
@@ -2313,6 +2463,12 @@ export class PhotonServer {
             });
             this.capabilityNegotiator.interceptTransportForRawCapabilities(beamTransport, this.server, (msg) => this.channelManager.interceptPermissionRequest(msg));
             await this.server.connect(beamTransport);
+            beamTransport.mainTools = (this.mcp?.tools || [])
+                .filter((t) => !t.internal)
+                .map((t) => ({
+                name: t.name,
+                scopes: Array.isArray(t.scopes) ? t.scopes : [],
+            }));
             // Wire sub-photons: collect all loaded photons except the main one
             const mainName = this.mcp?.name || 'photon';
             const allLoaded = this.loader.getLoadedPhotons();
@@ -2336,6 +2492,7 @@ export class PhotonServer {
                         name: t.name,
                         description: t.description || '',
                         inputSchema: t.inputSchema,
+                        ...(Array.isArray(t.scopes) ? { scopes: t.scopes } : {}),
                         ...(linkedUI ? { linkedUi: linkedUI.id } : {}),
                     };
                 });
@@ -2465,30 +2622,6 @@ export class PhotonServer {
                         }
                         return;
                     }
-                    // API: List tools (for compatibility, now returns current photon)
-                    if (req.method === 'GET' && url.pathname === '/api/tools') {
-                        const toolHeaders = { 'Content-Type': 'application/json' };
-                        if (corsOrigin)
-                            toolHeaders['Access-Control-Allow-Origin'] = corsOrigin;
-                        res.writeHead(200, toolHeaders);
-                        const tools = this.mcp?.tools.map((tool) => {
-                            const linkedUI = this.mcp?.assets?.ui.find((u) => u.linkedTool === tool.name || u.linkedTools?.includes(tool.name));
-                            return {
-                                name: tool.name,
-                                description: tool.description,
-                                inputSchema: JSON.parse(JSON.stringify(tool.inputSchema)),
-                                ui: linkedUI
-                                    ? { id: linkedUI.id, uri: `ui://${this.mcp.name}/${linkedUI.id}` }
-                                    : null,
-                            };
-                        }) || [];
-                        // Resolve @choice-from fields
-                        for (const tool of tools) {
-                            await this.resolveChoiceFromFields(tool);
-                        }
-                        res.end(JSON.stringify({ tools }));
-                        return;
-                    }
                     if (req.method === 'GET' && url.pathname === '/api/status') {
                         const statusHeaders = { 'Content-Type': 'application/json' };
                         if (corsOrigin)
@@ -2502,147 +2635,6 @@ export class PhotonServer {
                         return;
                     }
                 }
-                // API: Call tool
-                if (req.method === 'POST' && url.pathname === '/api/call') {
-                    // Security: restrict CORS to localhost and require local request
-                    if (corsOrigin)
-                        res.setHeader('Access-Control-Allow-Origin', corsOrigin);
-                    res.setHeader('Content-Type', 'application/json');
-                    if (!isLocalRequest(req)) {
-                        res.writeHead(403);
-                        res.end(JSON.stringify({ success: false, error: 'Forbidden: non-local request' }));
-                        return;
-                    }
-                    if (!this.mcp) {
-                        res.writeHead(503);
-                        res.end(JSON.stringify({ success: false, error: 'Photon not loaded' }));
-                        return;
-                    }
-                    try {
-                        const body = await readBody(req);
-                        const { tool, args } = JSON.parse(body);
-                        const result = await this.loader.executeTool(this.mcp, tool, args || {});
-                        const isStateful = result && typeof result === 'object' && result._stateful === true;
-                        res.writeHead(200);
-                        res.end(JSON.stringify({
-                            success: true,
-                            data: isStateful ? result.result : result,
-                        }));
-                    }
-                    catch (error) {
-                        const status = error.message?.includes('too large') ? 413 : 500;
-                        res.writeHead(status);
-                        res.end(JSON.stringify({ success: false, error: getErrorMessage(error) }));
-                    }
-                    return;
-                }
-                // API: Call tool with streaming progress (SSE)
-                if (req.method === 'POST' && url.pathname === '/api/call-stream') {
-                    if (corsOrigin)
-                        res.setHeader('Access-Control-Allow-Origin', corsOrigin);
-                    res.setHeader('Content-Type', 'text/event-stream');
-                    res.setHeader('Cache-Control', 'no-cache');
-                    res.setHeader('Connection', 'keep-alive');
-                    if (!this.mcp) {
-                        res.writeHead(503, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ success: false, error: 'Photon not loaded' }));
-                        return;
-                    }
-                    let body = '';
-                    req.on('data', (chunk) => (body += chunk));
-                    req.on('end', () => {
-                        void (async () => {
-                            let requestId = `run_${Date.now()}`;
-                            const sendMessage = (message) => {
-                                res.write(`event: message\ndata: ${JSON.stringify(message)}\n\n`);
-                            };
-                            try {
-                                const payload = JSON.parse(body || '{}');
-                                const tool = payload.tool;
-                                if (!tool) {
-                                    throw new Error('Tool name is required');
-                                }
-                                const args = payload.args || {};
-                                const progressToken = payload.progressToken ?? `progress_${Date.now()}`;
-                                requestId = payload.requestId || requestId;
-                                const sendNotification = (method, params) => {
-                                    sendMessage({ jsonrpc: '2.0', method, params });
-                                };
-                                const reportProgress = (emit) => {
-                                    const rawValue = typeof emit?.value === 'number' ? emit.value : 0;
-                                    const percent = rawValue <= 1 ? rawValue * 100 : rawValue;
-                                    const payload = emit?.value ?? emit?.data;
-                                    sendNotification('notifications/progress', {
-                                        progressToken,
-                                        progress: percent,
-                                        total: 100,
-                                        message: emit?.message || null,
-                                        ...(payload !== undefined && typeof payload !== 'number'
-                                            ? { data: payload }
-                                            : {}),
-                                    });
-                                };
-                                const outputHandler = (emit) => {
-                                    if (!emit)
-                                        return;
-                                    if (emit.emit === 'progress') {
-                                        reportProgress(emit);
-                                    }
-                                    else if (emit.emit === 'status') {
-                                        sendNotification('notifications/status', {
-                                            type: emit.type || 'info',
-                                            message: emit.message || '',
-                                        });
-                                    }
-                                    else if (emit.emit === 'render') {
-                                        sendNotification('notifications/render', {
-                                            format: emit.format,
-                                            value: emit.value,
-                                        });
-                                    }
-                                    else if (emit.emit === 'render:clear') {
-                                        sendNotification('notifications/render', { clear: true });
-                                    }
-                                    else {
-                                        sendNotification('notifications/emit', { event: emit });
-                                    }
-                                    // Forward channel events to daemon for cross-process pub/sub
-                                    this.channelManager.publishIfChannel(emit);
-                                };
-                                sendNotification('notifications/status', {
-                                    type: 'info',
-                                    message: `Starting ${tool}`,
-                                });
-                                const result = await this.loader.executeTool(this.mcp, tool, args, {
-                                    outputHandler,
-                                });
-                                const isStateful = result && typeof result === 'object' && result._stateful === true;
-                                sendMessage({
-                                    jsonrpc: '2.0',
-                                    id: requestId,
-                                    result: {
-                                        success: true,
-                                        data: isStateful ? result.result : result,
-                                    },
-                                });
-                                res.end();
-                            }
-                            catch (error) {
-                                const message = getErrorMessage(error);
-                                const errorPayload = {
-                                    jsonrpc: '2.0',
-                                    error: { code: -32000, message },
-                                };
-                                if (requestId) {
-                                    errorPayload.id = requestId;
-                                }
-                                sendMessage(errorPayload);
-                                res.end();
-                            }
-                        })();
-                    });
-                    return;
-                }
                 // API: Get UI template (and directory-style siblings for SPA bundles).
                 //
                 // Two shapes: