@portel/photon 1.29.0 → 1.31.1

package/templates/cloudflare/worker.ts.template

@@ -298,6 +298,54 @@ function createCallProvider(env: Env, callerName: string) {
   };
 }
 
+/**
+ * Build a `Cloudflare` adapter for the deployed Worker. Each scoped
+ * category resolves to `env[bindingNameFor(photon, category, qualifier)]`
+ * — the same auto-naming convention the local miniflare sandbox seeds,
+ * so photon source is unchanged across runtimes. Shared categories
+ * (ai/images/browser) read fixed canonical env keys.
+ *
+ * Mirrors photon-core's `createCloudflareFromEnv` line-for-line. We
+ * inline it rather than import to keep the template self-contained
+ * (the bundled Worker shouldn't depend on `@portel/photon-core` at
+ * runtime — too much surface for what's needed here).
+ */
+function bindingNameFor(photon: string, category: string, qualifier?: string): string {
+  const safePhoton = photon.toLowerCase().replace(/-/g, '_');
+  if (qualifier && qualifier.length > 0) {
+    const safeQualifier = qualifier.toLowerCase().replace(/-/g, '_');
+    return `${safePhoton}_${safeQualifier}_${category}`;
+  }
+  return `${safePhoton}_${category}`;
+}
+
+function createCloudflareFromEnv(env: Env, photonName: string): any {
+  const scoped = (category: string) => (qualifier?: string) => {
+    const name = bindingNameFor(photonName, category, qualifier);
+    const binding = (env as any)[name];
+    if (!binding) {
+      throw new Error(
+        `cf.${category}(${qualifier ? JSON.stringify(qualifier) : ''}) requires ` +
+          `binding "${name}" on the Worker env, but it is not defined. Add it to ` +
+          `wrangler.toml (or run \`photon host deploy cloudflare\` to regenerate ` +
+          `bindings from the photon's source).`
+      );
+    }
+    return binding;
+  };
+  return {
+    kv: scoped('kv'),
+    r2: scoped('r2'),
+    d1: scoped('d1'),
+    queue: scoped('queue'),
+    vectorize: scoped('vectorize'),
+    ai: (env as any).AI,
+    images: (env as any).IMAGES,
+    browser: (env as any).BROWSER,
+    fetch: (input: any, init?: any) => fetch(input, init),
+  };
+}
+
 // ════════════════════════════════════════════════════════════════════════════
 // Capability shim — wires this.* on the photon instance
 // ════════════════════════════════════════════════════════════════════════════
@@ -316,15 +364,76 @@ function withCfCapabilities(
   });
 
   Object.defineProperty(instance, 'emit', {
-    value: (event: { channel?: string; [k: string]: unknown }) => {
-      const channel = (event && typeof event === 'object' && event.channel) || 'default';
-      const payload = JSON.stringify(event);
-      for (const ws of ctx.getWebSockets(channel)) {
-        try {
-          ws.send(payload);
-        } catch {
-          // Socket closing; webSocketClose hook will reap.
-        }
+    value: (event: { emit?: string; [k: string]: unknown }) => {
+      // SSE forwarding for in-flight tool calls. When an SSE
+      // request context is active (i.e. the caller used
+      // `Accept: text/event-stream`), `this.emit({ emit: 'progress' })`,
+      // `this.emit({ emit: 'status' })`, etc. become real
+      // `notifications/progress` / `notifications/message` JSON-RPC
+      // notifications written to the open stream — the client sees
+      // them arrive as the tool runs, not in a single batch at the
+      // end. Mirrors `src/server.ts:1340-1397` for runtime parity
+      // between local and deployed transports.
+      const reqCtx = requestContext.getStore();
+      if (!reqCtx) return;
+      const kind = (event && typeof event === 'object' ? event.emit : undefined) as string | undefined;
+      if (!kind) return;
+      const progressToken = reqCtx.progressToken;
+      if (kind === 'progress') {
+        const rawValue = typeof event.value === 'number' ? (event.value as number) : 0;
+        const progress = rawValue <= 1 ? rawValue * 100 : rawValue;
+        void reqCtx.send({
+          jsonrpc: '2.0',
+          method: 'notifications/progress',
+          params: {
+            ...(progressToken !== undefined ? { progressToken } : {}),
+            progress,
+            total: 100,
+            ...(typeof event.message === 'string' ? { message: event.message } : {}),
+          },
+        });
+      } else if (kind === 'status') {
+        void reqCtx.send({
+          jsonrpc: '2.0',
+          method: 'notifications/progress',
+          params: {
+            ...(progressToken !== undefined ? { progressToken } : {}),
+            progress: 0,
+            total: 100,
+            message: typeof event.message === 'string' ? event.message : '',
+          },
+        });
+      } else if (kind === 'log') {
+        void reqCtx.send({
+          jsonrpc: '2.0',
+          method: 'notifications/message',
+          params: {
+            level: typeof event.level === 'string' ? event.level : 'info',
+            data: typeof event.message === 'string' ? event.message : '',
+          },
+        });
+      } else if (kind === 'render') {
+        void reqCtx.send({
+          jsonrpc: '2.0',
+          method: 'notifications/message',
+          params: {
+            level: 'info',
+            data: JSON.stringify({
+              _render: true,
+              format: event.format,
+              value: event.value,
+            }),
+          },
+        });
+      } else if (kind === 'render:clear') {
+        void reqCtx.send({
+          jsonrpc: '2.0',
+          method: 'notifications/message',
+          params: {
+            level: 'info',
+            data: JSON.stringify({ _render: true, clear: true }),
+          },
+        });
       }
     },
     writable: false,
@@ -332,6 +441,80 @@ function withCfCapabilities(
     configurable: false,
   });
 
+  // Emit-based convenience helpers — `this.status(...)`, `this.log(...)`,
+  // `this.progress(...)`, `this.toast(...)`, `this.thinking(...)`,
+  // `this.render(...)`. The classic loader injects these on every
+  // plain-class instance (`src/loader.ts:injectEmitHelpers`); the
+  // deployed Worker must do the same so a photon written against the
+  // local runtime behaves identically when served from CF. Without
+  // these, calls like `this.status?.('one')` short-circuit silently
+  // on the Worker and the whole chain of progress notifications is
+  // lost — which is exactly the symptom that prompted this wiring.
+  // Each helper guards on `in instance` so user-declared methods on
+  // the photon class always win.
+  const emitFn = (data: { [k: string]: unknown }) =>
+    (instance as { emit: (d: unknown) => void }).emit(data);
+  if (!('render' in instance)) {
+    (instance as { render?: (format?: string, value?: unknown) => void }).render = (
+      format?: string,
+      value?: unknown,
+    ) => {
+      if (format === undefined) return emitFn({ emit: 'render:clear' });
+      if (format === 'status') {
+        return emitFn(
+          typeof value === 'string'
+            ? { emit: 'status', message: value }
+            : { emit: 'status', ...(value as object) }
+        );
+      }
+      if (format === 'progress') {
+        return emitFn(
+          typeof value === 'number'
+            ? { emit: 'progress', value }
+            : { emit: 'progress', ...(value as object) }
+        );
+      }
+      if (format === 'toast') {
+        return emitFn(
+          typeof value === 'string'
+            ? { emit: 'toast', message: value }
+            : { emit: 'toast', ...(value as object) }
+        );
+      }
+      emitFn({ emit: 'render', format, value });
+    };
+  }
+  if (!('toast' in instance)) {
+    (instance as { toast?: (m: string, o?: { type?: string; duration?: number }) => void }).toast = (
+      message: string,
+      opts: { type?: string; duration?: number } = {},
+    ) => emitFn({ emit: 'toast', message, ...opts });
+  }
+  if (!('log' in instance)) {
+    (instance as { log?: (m: string, o?: { level?: string; data?: unknown }) => void }).log = (
+      message: string,
+      opts: { level?: string; data?: unknown } = {},
+    ) => emitFn({ emit: 'log', message, level: opts.level ?? 'info', data: opts.data });
+  }
+  if (!('status' in instance)) {
+    // Signature mirrors `src/loader.ts:288` exactly. Photons that pass a
+    // second arg (e.g. `this.status('one', { n: 1 })`) keep working —
+    // the extra arg is dropped on both transports for parity. If we
+    // ever decide to surface it, change both call sites at once.
+    (instance as { status?: (m: string) => void }).status = (message: string) =>
+      emitFn({ emit: 'status', message });
+  }
+  if (!('progress' in instance)) {
+    (instance as { progress?: (v: number, m?: string) => void }).progress = (
+      value: number,
+      message?: string,
+    ) => emitFn({ emit: 'progress', value, message });
+  }
+  if (!('thinking' in instance)) {
+    (instance as { thinking?: (a?: boolean) => void }).thinking = (active = true) =>
+      emitFn({ emit: 'thinking', active });
+  }
+
   Object.defineProperty(instance, 'schedule', {
     value: createScheduleProvider(ctx, photonName),
     writable: false,
@@ -366,6 +549,33 @@ function withCfCapabilities(
     configurable: false,
   });
 
+  // `this.mcpAuthed` — true when the active /mcp request passed the
+  // PHOTON_MCP_BEARER check, false when no secret is configured or the
+  // request hit a path outside MCP dispatch (e.g. /api/* or /__call).
+  // User code can guard sensitive methods with:
+  //   if (!this.mcpAuthed) throw new Error('unauthorized');
+  // The flag is per-tool-call (AsyncLocalStorage scoped); it doesn't
+  // persist across awaits that escape the dispatch context.
+  Object.defineProperty(instance, 'mcpAuthed', {
+    get() {
+      return mcpAuthContext.getStore()?.authed === true;
+    },
+    enumerable: false,
+    configurable: false,
+  });
+
+  // `this.cf` — the wrapped Cloudflare surface. Auto-naming
+  // (`bindingNameFor`) resolves `cf.kv()` to `<photon>_kv`,
+  // `cf.kv('cache')` to `<photon>_cache_kv`, etc. The deploy
+  // pipeline emits matching wrangler.toml entries from the same
+  // convention, so bindings always line up across runtimes.
+  Object.defineProperty(instance, 'cf', {
+    value: createCloudflareFromEnv(env, photonName),
+    writable: false,
+    enumerable: false,
+    configurable: false,
+  });
+
   // Human/LLM-in-the-loop primitives. Each one wraps an MCP server-initiated
   // request (sampling/createMessage, elicitation/create), pushed over the
   // active tool call's SSE response stream and awaited on a Promise keyed by
@@ -407,6 +617,14 @@ interface RequestContext {
   send: (msg: unknown) => Promise<void>;
   /** Shared pending map; the DO's POST /mcp handler resolves entries here. */
   pendingRequests: Map<string, PendingRequest>;
+  /**
+   * Client-supplied progress token from the originating request's
+   * `_meta.progressToken`. Echoed back in every `notifications/progress`
+   * event we send during the call so the client can correlate progress
+   * with its outstanding request. Falls back to a synthesized token if
+   * the client didn't supply one.
+   */
+  progressToken?: string | number;
 }
 
 /**
@@ -418,6 +636,73 @@ interface RequestContext {
  */
 const requestContext = new AsyncLocalStorage<RequestContext>();
 
+/**
+ * Per-tool-call MCP auth context. Set when the bearer check on `/mcp`
+ * has passed (or skipped because no `PHOTON_MCP_BEARER` secret is
+ * configured) so user code reading `this.mcpAuthed` sees the right
+ * 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 }>();
+
+/**
+ * Constant-time string comparison to avoid leaking the bearer through
+ * timing differences. Falls back to a manual byte loop because Workers
+ * doesn't always expose `crypto.timingSafeEqual`.
+ */
+function timingSafeEqualString(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let mismatch = 0;
+  for (let i = 0; i < a.length; i++) {
+    mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return mismatch === 0;
+}
+
+/**
+ * Validate the Authorization header against `env.PHOTON_MCP_BEARER`.
+ * Returns:
+ *  - `{ enforced: false }` when no secret is configured (back-compat).
+ *  - `{ enforced: true, ok: true }` when the bearer matches.
+ *  - `{ enforced: true, ok: false, reason }` when missing or wrong.
+ *
+ * Methods that don't dispatch user code (`tools/list`, `initialize`,
+ * `notifications/*`, `ping`) bypass this check at the call site.
+ */
+function checkMcpBearer(
+  request: Request,
+  env: Env
+): { enforced: false } | { enforced: true; ok: boolean; reason?: string } {
+  const expected = (env as Record<string, unknown>).PHOTON_MCP_BEARER;
+  if (typeof expected !== 'string' || expected.length === 0) {
+    return { enforced: false };
+  }
+  const header = request.headers.get('Authorization') ?? '';
+  const match = header.match(/^Bearer\s+(.+)$/i);
+  if (!match) {
+    return { enforced: true, ok: false, reason: 'Authorization: Bearer <token> header missing' };
+  }
+  const presented = match[1].trim();
+  if (!timingSafeEqualString(presented, expected)) {
+    return { enforced: true, ok: false, reason: 'bearer token does not match PHOTON_MCP_BEARER' };
+  }
+  return { enforced: true, ok: true };
+}
+
+/**
+ * Methods that may pass through `/mcp` without a bearer because they
+ * don't dispatch into user code. `tools/list` advertises the catalog,
+ * which is generally safe to expose; if a deployment wants to gate it
+ * the photon owner can set CF Access on the route.
+ */
+const MCP_METHODS_BYPASSING_BEARER = new Set([
+  'initialize',
+  'notifications/initialized',
+  'notifications/cancelled',
+  'ping',
+  'tools/list',
+]);
+
 function requireRequestContext(which: string): RequestContext {
   const ctx = requestContext.getStore();
   if (!ctx) {
@@ -983,6 +1268,40 @@ 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) {
+      return new Response(
+        JSON.stringify({
+          jsonrpc: '2.0',
+          id: body?.id ?? null,
+          error: {
+            code: -32001,
+            message: 'Unauthorized',
+            data: { reason: (authResult as { reason: string }).reason },
+          },
+        }),
+        {
+          status: 401,
+          headers: {
+            'Content-Type': 'application/json',
+            'WWW-Authenticate': 'Bearer realm="photon"',
+            ...CORS_HEADERS,
+          },
+        }
+      );
+    }
+    const authed = authResult.enforced ? authResult.ok === true : false;
+
     // Tool calls from clients that signal SSE support get a streamed
     // response so this.sample / this.confirm / this.elicit can push
     // server-initiated requests inline. All other JSON-RPC methods (and
@@ -990,10 +1309,12 @@ 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 this._streamToolCall(body);
+      return mcpAuthContext.run({ authed }, () => this._streamToolCall(body));
     }
 
-    const result = await handleMCPRequest(body, this.photon, this.photonName, this.toolDefinitions);
+    const result = await mcpAuthContext.run({ authed }, () =>
+      handleMCPRequest(body, this.photon, this.photonName, this.toolDefinitions)
+    );
     return Response.json(result, { headers: CORS_HEADERS });
   }
 
@@ -1011,9 +1332,15 @@ abstract class BasePhotonDO extends DurableObject<Env> {
       await writer.write(encoder.encode(`data: ${JSON.stringify(msg)}\n\n`));
     };
 
+    // Per MCP spec, echo the client-supplied progressToken so any
+    // streamed progress notifications correlate with this request.
+    const clientProgressToken = (rpcRequest?.params as { _meta?: { progressToken?: string | number } })
+      ?._meta?.progressToken;
+    const toolName = (rpcRequest?.params as { name?: string })?.name ?? 'tool';
     const ctx: RequestContext = {
       send,
       pendingRequests: this.pendingRequests,
+      progressToken: clientProgressToken ?? `progress_${toolName}`,
     };
 
     // Fire-and-forget: the response stream stays open as long as the writer

package/templates/cloudflare/wrangler.toml.template

@@ -7,12 +7,7 @@ main = "src/worker.ts"
 compatibility_date = "2024-09-23"
 compatibility_flags = ["nodejs_compat"]
 __OBSERVABILITY__
-# Workers AI binding — gives every photon access to CF's edge inference
-# (embeddings, classification, small LLMs) via `(this as any).env.AI.run(...)`.
-# Free tier covers thousands of calls/day; charges only kick in at scale.
-# Photons that don't use it pay nothing for having the binding declared.
-[ai]
-binding = "AI"
+__CF_BINDINGS__
 
 # Durable Objects backing every photon class bundled into this Worker. The
 # host photon is always bound to `PHOTON`; each `@photons` sibling gets

package/templates/photon.template.ts

@@ -7,6 +7,19 @@
  */
 
 export default class TemplateName {
+  // User-configurable knobs. Photon auto-generates a `settings` MCP tool
+  // from this object and persists changes to
+  // ~/.photon/state/<photon>/<instance>-settings.json.
+  //
+  // Reach for this whenever a value should be runtime-configurable. Use a
+  // constructor parameter only for primitive secrets (API keys, tokens)
+  // that should live in .env. Uncomment and edit:
+  //
+  //   protected settings = {
+  //     /** Friendly description shown in the settings tool */
+  //     greeting: 'Hello',
+  //   };
+
   /**
    * Optional initialization hook
    * Called once when the MCP is loaded