@portel/photon 1.33.0 → 1.33.2

package/templates/cloudflare/worker.ts.template

@@ -20,6 +20,11 @@ interface Env {
 
 const DEV_MODE = __DEV_MODE__;
 const HOST_PHOTON_NAME = '__HOST_PHOTON_NAME__';
+const MCP_AUTH_MODE = __MCP_AUTH_MODE__;
+const MCP_JWT_ISSUER = __MCP_JWT_ISSUER__;
+const MCP_JWT_AUDIENCE = __MCP_JWT_AUDIENCE__;
+const MCP_JWT_JWKS = __MCP_JWT_JWKS__;
+const DEPLOY_INSTANCE_ALIASES: Record<string, string> = __INSTANCE_ALIASES__;
 
 /**
  * Photon name → Worker env binding name. Generated at deploy time from the
@@ -31,7 +36,7 @@ const PHOTON_BINDINGS: Record<string, string> = __PHOTON_BINDINGS_MAP__;
 const CORS_HEADERS = {
   'Access-Control-Allow-Origin': '*',
   'Access-Control-Allow-Methods': 'POST, GET, OPTIONS',
-  'Access-Control-Allow-Headers': 'Content-Type, Mcp-Session-Id, X-Photon-Instance',
+  'Access-Control-Allow-Headers': 'Content-Type, Authorization, Mcp-Session-Id, X-Photon-Instance',
 };
 
 /**
@@ -43,6 +48,13 @@ const CORS_HEADERS = {
 const UI_ASSET_MANIFEST: Record<string, { base: string; js: string; hash: string }> =
   __UI_ASSET_MANIFEST__;
 
+/**
+ * Photon companion-folder assets embedded at deploy time for synchronous
+ * `this.assets(subpath, { load })` parity with the local runtime. Files are
+ * keyed by photon name and normalized relative path.
+ */
+const PHOTON_ASSET_CONTENTS: Record<string, Record<string, string>> = __PHOTON_ASSET_CONTENTS__;
+
 // ════════════════════════════════════════════════════════════════════════════
 // Memory proxy — ctx.storage backing for this.memory
 // ════════════════════════════════════════════════════════════════════════════
@@ -231,6 +243,14 @@ function createScheduleProvider(ctx: DurableObjectState, photonId: string) {
       if (ok) await rescheduleAlarm(ctx);
       return ok;
     },
+    async cancelByName(name: string): Promise<boolean> {
+      const task = await this.getByName(name);
+      if (!task) return false;
+      return this.cancel(task.id);
+    },
+    async has(name: string): Promise<boolean> {
+      return (await this.getByName(name)) !== null;
+    },
     async update(
       id: string,
       updates: Partial<
@@ -248,6 +268,28 @@ function createScheduleProvider(ctx: DurableObjectState, photonId: string) {
       await rescheduleAlarm(ctx);
       return next;
     },
+    async pause(id: string): Promise<ScheduledTask> {
+      const cur = await ctx.storage.get<ScheduledTask>(SCHEDULE_PREFIX + id);
+      if (!cur) throw new Error(`Schedule ${id} not found`);
+      if (cur.status !== 'active') {
+        throw new Error(`Cannot pause task with status '${cur.status}'. Only active tasks can be paused.`);
+      }
+      const next: ScheduledTask = { ...cur, status: 'paused' };
+      await ctx.storage.put(SCHEDULE_PREFIX + id, next);
+      await rescheduleAlarm(ctx);
+      return next;
+    },
+    async resume(id: string): Promise<ScheduledTask> {
+      const cur = await ctx.storage.get<ScheduledTask>(SCHEDULE_PREFIX + id);
+      if (!cur) throw new Error(`Schedule ${id} not found`);
+      if (cur.status !== 'paused') {
+        throw new Error(`Cannot resume task with status '${cur.status}'. Only paused tasks can be resumed.`);
+      }
+      const next: ScheduledTask = { ...cur, status: 'active' };
+      await ctx.storage.put(SCHEDULE_PREFIX + id, next);
+      await rescheduleAlarm(ctx);
+      return next;
+    },
   };
 }
 
@@ -538,6 +580,13 @@ function withCfCapabilities(
     configurable: false,
   });
 
+  Object.defineProperty(instance, 'assets', {
+    value: createAssetsProvider(photonName),
+    writable: false,
+    enumerable: false,
+    configurable: false,
+  });
+
   Object.defineProperty(instance, 'callerCwd', {
     get() {
       return undefined;
@@ -546,6 +595,22 @@ function withCfCapabilities(
     configurable: false,
   });
 
+  Object.defineProperty(instance, 'caller', {
+    get() {
+      return (
+        mcpAuthContext.getStore()?.caller ?? {
+          id: 'anonymous',
+          name: undefined,
+          anonymous: true,
+          scope: undefined,
+          claims: {},
+        }
+      );
+    },
+    enumerable: false,
+    configurable: false,
+  });
+
   // Worker env exposed to the photon for direct binding access — Workers AI
   // (`env.AI.run('@cf/...', ...)`), KV, R2, queues, secrets. Photons that
   // want to stay CF-portable should branch on `(this as any).env?.AI` and
@@ -612,6 +677,43 @@ function withCfCapabilities(
   return instance;
 }
 
+function createAssetsProvider(photonName: string) {
+  return (subpath: string, options?: boolean | { load?: boolean; encoding?: string | null }) => {
+    const normalized = typeof options === 'boolean' ? { load: options } : (options ?? {});
+    const assetPath = normalizeAssetPath(subpath);
+    if (!normalized.load) return `/${photonName}/${assetPath}`;
+
+    const encoded = PHOTON_ASSET_CONTENTS[photonName]?.[assetPath];
+    if (encoded === undefined) {
+      throw new Error(`Asset not found: ${assetPath}`);
+    }
+
+    const bytes = base64ToBytes(encoded);
+    if (normalized.encoding === null) return bytes;
+    const encoding = !normalized.encoding || normalized.encoding === 'utf8' ? 'utf-8' : normalized.encoding;
+    return new TextDecoder(encoding).decode(bytes);
+  };
+}
+
+function normalizeAssetPath(subpath: string): string {
+  const clean = String(subpath)
+    .replace(/\\/g, '/')
+    .replace(/^\/+/, '')
+    .split('/')
+    .filter((part) => part && part !== '.');
+  if (clean.some((part) => part === '..')) {
+    throw new Error(`Invalid asset path: ${subpath}`);
+  }
+  return clean.join('/');
+}
+
+function base64ToBytes(value: string): Uint8Array {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
 // ════════════════════════════════════════════════════════════════════════════
 // Server-initiated MCP requests — sample / confirm / elicit
 // ════════════════════════════════════════════════════════════════════════════
@@ -652,7 +754,7 @@ const requestContext = new AsyncLocalStorage<RequestContext>();
  * value for the dispatched method. The flag is scoped to the single
  * `tools/call` invocation, not the DO lifetime.
  */
-const mcpAuthContext = new AsyncLocalStorage<{ authed: boolean }>();
+const mcpAuthContext = new AsyncLocalStorage<{ authed: boolean; caller?: any }>();
 
 /**
  * Constant-time string comparison to avoid leaking the bearer through
@@ -698,6 +800,153 @@ function checkMcpBearer(
   return { enforced: true, ok: true };
 }
 
+type McpAuthResult =
+  | { enforced: false; ok: true; authed: false }
+  | { enforced: true; ok: true; authed: true; caller?: any }
+  | { enforced: true; ok: false; status: number; code: number; message: string; reason: string; wwwAuthenticate: string };
+
+function bearerTokenFromRequest(request: Request): string | null {
+  const header = request.headers.get('Authorization') ?? '';
+  const match = header.match(/^Bearer\s+(.+)$/i);
+  return match ? match[1].trim() : null;
+}
+
+function base64UrlDecode(input: string): string {
+  const normalized = input.replace(/-/g, '+').replace(/_/g, '/');
+  const padded = normalized + '='.repeat((4 - (normalized.length % 4)) % 4);
+  return atob(padded);
+}
+
+function base64UrlBytes(input: string): Uint8Array {
+  const binary = base64UrlDecode(input);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+
+function parseJwtPart(part: string): any | null {
+  try {
+    return JSON.parse(base64UrlDecode(part));
+  } catch {
+    return null;
+  }
+}
+
+async function verifyMcpJwt(
+  request: Request,
+  requiredScopes: string[] = []
+): Promise<McpAuthResult> {
+  if (MCP_AUTH_MODE !== 'jwt') {
+    return { enforced: false, ok: true, authed: false };
+  }
+  if (!MCP_JWT_ISSUER || !MCP_JWT_AUDIENCE || !MCP_JWT_JWKS?.keys?.length) {
+    return jwtReject('missing_token');
+  }
+  const token = bearerTokenFromRequest(request);
+  if (!token) return jwtReject('missing_token');
+  const parts = token.split('.');
+  if (parts.length !== 3) return jwtReject('malformed_token');
+  const header = parseJwtPart(parts[0]);
+  const claims = parseJwtPart(parts[1]);
+  if (!header || !claims) return jwtReject('malformed_token');
+  if (header.alg !== 'ES256') return jwtReject('unsupported_alg');
+  const kid = typeof header.kid === 'string' ? header.kid : '';
+  const jwk = MCP_JWT_JWKS.keys.find((key: any) => key?.kid === kid);
+  if (!kid || !jwk) return jwtReject('unknown_kid');
+
+  let verified = false;
+  try {
+    const key = await crypto.subtle.importKey(
+      'jwk',
+      jwk,
+      { name: 'ECDSA', namedCurve: 'P-256' },
+      false,
+      ['verify']
+    );
+    verified = await crypto.subtle.verify(
+      { name: 'ECDSA', hash: 'SHA-256' },
+      key,
+      base64UrlBytes(parts[2]),
+      new TextEncoder().encode(`${parts[0]}.${parts[1]}`)
+    );
+  } catch {
+    verified = false;
+  }
+  if (!verified) return jwtReject('bad_signature');
+  if (claims.iss !== MCP_JWT_ISSUER) return jwtReject('wrong_issuer');
+  const audMatches = Array.isArray(claims.aud)
+    ? claims.aud.includes(MCP_JWT_AUDIENCE)
+    : claims.aud === MCP_JWT_AUDIENCE;
+  if (!audMatches) return jwtReject('wrong_audience');
+  const now = Math.floor(Date.now() / 1000);
+  const skew = 60;
+  if (typeof claims.exp !== 'number' || claims.exp < now - skew) return jwtReject('expired_token');
+  if (typeof claims.nbf === 'number' && claims.nbf > now + skew) {
+    return jwtReject('token_not_yet_valid');
+  }
+  if (typeof claims.iat === 'number' && claims.iat > now + skew) {
+    return jwtReject('token_not_yet_valid');
+  }
+  const granted = new Set(String(claims.scope ?? '').split(/\s+/).filter(Boolean));
+  const missing = requiredScopes.find((scope) => !granted.has(scope));
+  if (missing) return jwtReject('insufficient_scope', requiredScopes);
+  return {
+    enforced: true,
+    ok: true,
+    authed: true,
+    caller: {
+      id: String(claims.sub ?? 'unknown'),
+      name: typeof claims.name === 'string' ? claims.name : undefined,
+      anonymous: false,
+      scope: typeof claims.scope === 'string' ? claims.scope : undefined,
+      claims,
+    },
+  };
+}
+
+function jwtReject(reason: string, scopes: string[] = []): McpAuthResult {
+  const insufficient = reason === 'insufficient_scope';
+  const scopePart = insufficient && scopes.length > 0 ? `, scope="${scopes.join(' ')}"` : '';
+  return {
+    enforced: true,
+    ok: false,
+    status: insufficient ? 403 : 401,
+    code: insufficient ? -32003 : -32001,
+    message: insufficient ? 'Forbidden' : 'Unauthorized',
+    reason,
+    wwwAuthenticate: `Bearer realm="photon", error="${insufficient ? 'insufficient_scope' : 'invalid_token'}"${scopePart}`,
+  };
+}
+
+async function checkMcpAuth(
+  request: Request,
+  env: Env,
+  method: string,
+  toolDefinitions: any[],
+  body: any
+): Promise<McpAuthResult> {
+  const requiresAuth = method !== '' && !MCP_METHODS_BYPASSING_BEARER.has(method);
+  if (!requiresAuth) return { enforced: false, ok: true, authed: false };
+  if (MCP_AUTH_MODE === 'jwt') {
+    const toolName = body?.method === 'tools/call' ? body?.params?.name : undefined;
+    const tool = toolDefinitions.find((t: any) => t.name === toolName);
+    return verifyMcpJwt(request, Array.isArray(tool?.scopes) ? tool.scopes : []);
+  }
+  if (MCP_AUTH_MODE === 'open') return { enforced: false, ok: true, authed: false };
+  const bearer = checkMcpBearer(request, env);
+  if (!bearer.enforced) return { enforced: false, ok: true, authed: false };
+  if (bearer.ok) return { enforced: true, ok: true, authed: true };
+  return {
+    enforced: true,
+    ok: false,
+    status: 401,
+    code: -32001,
+    message: 'Unauthorized',
+    reason: bearer.reason ?? 'Authorization: Bearer <token> header missing',
+    wwwAuthenticate: 'Bearer realm="photon"',
+  };
+}
+
 /**
  * Methods that may pass through `/mcp` without a bearer because they
  * don't dispatch into user code. `tools/list` advertises the catalog,
@@ -1030,10 +1279,17 @@ abstract class BasePhotonDO extends DurableObject<Env> {
   constructor(ctx: DurableObjectState, env: Env) {
     super(ctx, env);
     this.instanceName = ctx.id.name ?? 'default';
-    this.photon = withCfCapabilities(this.createPhoton(), ctx, env, this.photonName);
+  }
+
+  protected getPhoton(): any {
+    if (!this.photon) {
+      this.photon = withCfCapabilities(this.createPhoton(), this.ctx, this.env, this.photonName);
+    }
+    return this.photon;
   }
 
   async fetch(request: Request): Promise<Response> {
+    this.getPhoton();
     const url = new URL(request.url);
 
     // Internal cross-photon call — invoked by sibling DOs via this.call.
@@ -1130,27 +1386,6 @@ abstract class BasePhotonDO extends DurableObject<Env> {
           headers: { 'Content-Type': 'text/html' },
         });
       }
-      if (url.pathname === '/api/tools') {
-        return Response.json({ tools: this.toolDefinitions }, { headers: CORS_HEADERS });
-      }
-      if (url.pathname === '/api/call' && request.method === 'POST') {
-        const { tool, args } = (await request.json()) as { tool: string; args: any };
-        try {
-          const fn = (this.photon as any)[tool];
-          if (typeof fn !== 'function') {
-            throw new Error(`Unknown tool: ${tool}`);
-          }
-          const toolDef = this.toolDefinitions.find((t: any) => t.name === tool);
-          const callArgs = spreadArgs(toolDef, args || {});
-          const result = await fn.call(this.photon, ...callArgs);
-          return Response.json({ success: true, data: result }, { headers: CORS_HEADERS });
-        } catch (error: any) {
-          return Response.json(
-            { success: false, error: error.message },
-            { status: 500, headers: CORS_HEADERS }
-          );
-        }
-      }
     }
 
     // @get / @post HTTP routes — dispatch to photon method, bypass MCP.
@@ -1328,39 +1563,36 @@ abstract class BasePhotonDO extends DurableObject<Env> {
       return new Response(null, { status: 204, headers: CORS_HEADERS });
     }
 
-    // Bearer auth gate. When `PHOTON_MCP_BEARER` is set on the deployed
-    // Worker (e.g. via `wrangler secret put PHOTON_MCP_BEARER`), every
-    // method that dispatches into user code requires a matching
-    // `Authorization: Bearer <token>` header. Discovery + handshake
-    // methods (tools/list, initialize, ping, notifications/*) pass
-    // through unauthed so MCP clients can complete capability
-    // negotiation before authenticating. When the secret is unset the
-    // gate is a no-op so existing deployments keep working.
     const method = typeof body?.method === 'string' ? body.method : '';
-    const authResult = checkMcpBearer(request, (this as any).env);
-    const requiresAuth = method !== '' && !MCP_METHODS_BYPASSING_BEARER.has(method);
-    if (authResult.enforced && requiresAuth && !authResult.ok) {
+    const authResult = await checkMcpAuth(
+      request,
+      (this as any).env,
+      method,
+      this.toolDefinitions,
+      body
+    );
+    if (authResult.enforced && !authResult.ok) {
       return new Response(
         JSON.stringify({
           jsonrpc: '2.0',
           id: body?.id ?? null,
           error: {
-            code: -32001,
-            message: 'Unauthorized',
-            data: { reason: (authResult as { reason: string }).reason },
+            code: authResult.code,
+            message: authResult.message,
+            data: { reason: authResult.reason },
           },
         }),
         {
-          status: 401,
+          status: authResult.status,
           headers: {
             'Content-Type': 'application/json',
-            'WWW-Authenticate': 'Bearer realm="photon"',
+            'WWW-Authenticate': authResult.wwwAuthenticate,
             ...CORS_HEADERS,
           },
         }
       );
     }
-    const authed = authResult.enforced ? authResult.ok === true : false;
+    const authContext = { authed: authResult.authed === true, caller: authResult.caller };
 
     // Tool calls from clients that signal SSE support get a streamed
     // response so this.sample / this.confirm / this.elicit can push
@@ -1369,10 +1601,10 @@ abstract class BasePhotonDO extends DurableObject<Env> {
     const accept = request.headers.get('Accept') ?? '';
     const wantsSse = accept.includes('text/event-stream');
     if (body?.method === 'tools/call' && wantsSse) {
-      return mcpAuthContext.run({ authed }, () => this._streamToolCall(body));
+      return mcpAuthContext.run(authContext, () => this._streamToolCall(body));
     }
 
-    const result = await mcpAuthContext.run({ authed }, () =>
+    const result = await mcpAuthContext.run(authContext, () =>
       handleMCPRequest(body, this.photon, this.photonName, this.toolDefinitions)
     );
     return Response.json(result, { headers: CORS_HEADERS });
@@ -1385,6 +1617,7 @@ abstract class BasePhotonDO extends DurableObject<Env> {
    * (which arrive as separate POST /mcp requests routed by `_handleMcpPost`).
    */
   private _streamToolCall(rpcRequest: any): Response {
+    this.getPhoton();
     const { readable, writable } = new TransformStream();
     const writer = writable.getWriter();
     const encoder = new TextEncoder();
@@ -1453,6 +1686,7 @@ abstract class BasePhotonDO extends DurableObject<Env> {
    * Per-task errors move that task to status='error' without blocking others.
    */
   async alarm(): Promise<void> {
+    this.getPhoton();
     const tasks = await listSchedules(this.ctx);
     const now = Date.now();
     for (const task of tasks) {
@@ -1510,27 +1744,44 @@ const CF_ACCESS_ENABLED = __CF_ACCESS_ENABLED__;
  * CF Access verifies the JWT at the edge before the request reaches this
  * Worker, so we trust the claim without re-verifying the signature here.
  */
-function extractInstance(request: Request): string {
+function canonicalizeInstance(instance: string, env: Env): string {
+  const key = instance.trim().toLowerCase();
+  const aliases: Record<string, string> = { ...DEPLOY_INSTANCE_ALIASES };
+  const runtimeAliases = env.PHOTON_INSTANCE_ALIASES;
+  if (typeof runtimeAliases === 'string' && runtimeAliases.trim()) {
+    try {
+      const parsed = JSON.parse(runtimeAliases) as Record<string, unknown>;
+      for (const [from, to] of Object.entries(parsed)) {
+        if (typeof to === 'string' && to.trim()) aliases[from.toLowerCase()] = to;
+      }
+    } catch (err) {
+      console.warn('canonicalizeInstance: PHOTON_INSTANCE_ALIASES parse failed', err);
+    }
+  }
+  return aliases[key] || instance;
+}
+
+function extractInstance(request: Request, env: Env): string {
+  let instance: string | null = null;
   if (CF_ACCESS_ENABLED) {
     const headerEmail = request.headers.get('Cf-Access-Authenticated-User-Email');
-    if (headerEmail) return headerEmail;
+    if (headerEmail) instance = headerEmail;
     const jwt = request.headers.get('Cf-Access-Jwt-Assertion');
-    if (jwt) {
+    if (!instance && jwt) {
       try {
         const part = jwt.split('.')[1];
         const b64 = part.replace(/-/g, '+').replace(/_/g, '/');
         const padded = b64 + '==='.slice((b64.length + 3) % 4);
         const payload = JSON.parse(atob(padded));
-        if (payload?.email) return payload.email as string;
+        if (payload?.email) instance = payload.email as string;
       } catch (err) {
         console.warn('extractInstance: JWT parse failed', err);
       }
     }
   }
   const url = new URL(request.url);
-  return (
-    url.searchParams.get('instance') ?? request.headers.get('X-Photon-Instance') ?? 'default'
-  );
+  instance ??= url.searchParams.get('instance') ?? request.headers.get('X-Photon-Instance') ?? 'default';
+  return canonicalizeInstance(instance, env);
 }
 
 export default {
@@ -1541,11 +1792,11 @@ export default {
           'Access-Control-Allow-Origin': '*',
           'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
           'Access-Control-Allow-Headers':
-            'Content-Type, Mcp-Session-Id, X-Photon-Instance, Upgrade',
+            'Content-Type, Authorization, Mcp-Session-Id, X-Photon-Instance, Upgrade',
         },
       });
     }
-    const instance = extractInstance(request);
+    const instance = extractInstance(request, env);
     const id = env.__HOST_BINDING__.idFromName(instance);
     return env.__HOST_BINDING__.get(id).fetch(request);
   },
@@ -1605,6 +1856,12 @@ function getPlaygroundHTML(photonName: string, toolDefinitions: any[]): string {
         <h3>Parameters</h3>
         <div id="params"></div>
         <button class="btn" id="call" disabled>Call Tool</button>
+        <div style="margin-top: 10px; font-size: 12px; color: var(--muted);">
+          <a href="#" id="set-token" style="color: var(--muted); text-decoration: underline;">Set token</a>
+          &middot;
+          <a href="#" id="clear-token" style="color: var(--muted); text-decoration: underline;">Clear token</a>
+          <span id="token-status" style="margin-left: 8px;"></span>
+        </div>
       </div>
       <div class="panel">
         <h3>Response</h3>
@@ -1680,11 +1937,23 @@ function getPlaygroundHTML(photonName: string, toolDefinitions: any[]): string {
       document.getElementById('response').textContent = 'Calling...';
 
       try {
-        const res = await fetch('/api/call', {
+        const headers = { 'Content-Type': 'application/json' };
+        const token = localStorage.getItem('photon_mcp_token');
+        if (token) headers['Authorization'] = 'Bearer ' + token;
+        const res = await fetch('/mcp', {
           method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ tool: selectedTool.name, args })
+          headers,
+          body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: Date.now(),
+            method: 'tools/call',
+            params: { name: selectedTool.name, arguments: args }
+          })
         });
+        if (res.status === 401 || res.status === 403) {
+          document.getElementById('response').textContent = "Auth required. Click 'Set token' to paste an MCP token.";
+          return;
+        }
         const data = await res.json();
         document.getElementById('response').textContent = JSON.stringify(data, null, 2);
       } catch (e) {
@@ -1692,6 +1961,22 @@ function getPlaygroundHTML(photonName: string, toolDefinitions: any[]): string {
       }
     };
 
+    function updateTokenStatus() {
+      const el = document.getElementById('token-status');
+      el.textContent = localStorage.getItem('photon_mcp_token') ? '(token set)' : '(no token)';
+    }
+    document.getElementById('set-token').onclick = (e) => {
+      e.preventDefault();
+      const t = prompt('Paste MCP bearer/JWT token (stored in this browser only):');
+      if (t) { localStorage.setItem('photon_mcp_token', t.trim()); updateTokenStatus(); }
+    };
+    document.getElementById('clear-token').onclick = (e) => {
+      e.preventDefault();
+      localStorage.removeItem('photon_mcp_token');
+      updateTokenStatus();
+    };
+    updateTokenStatus();
+
     renderTools();
   </script>
 </body>