@portel/photon 1.28.2 → 1.29.0

package/dist/shared/expose-route-extractor.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Source-level extractor for `@expose` declarations.
+ *
+ * v1.29 Track C. Methods tagged `@expose` are auto-bound to a kebab-cased
+ * `/api/<method>` POST endpoint so a same-origin SPA can call them via
+ * fetch without writing per-method `@post` directives. `@expose public`
+ * widens this from "SameSite-cookie required" to "any caller" — useful
+ * for anonymous public surfaces (iCal feeds, billing portals, etc.).
+ *
+ * Like `http-route-extractor.ts`, this runs against raw source so the
+ * extractor doesn't depend on whatever shape the published photon-core
+ * SchemaExtractor returns. Both the runtime dispatcher and the Cloudflare
+ * deploy code-gen consume the same output.
+ *
+ *   /‍** @expose *‍/        async getCurrentUser() { ... }   → private
+ *   /‍** @expose public *‍/ async billing()        { ... }   → public
+ *   (no @expose tag)         async listUsers()    { ... }   → MCP-only
+ */
+export type ExposeVisibility = 'private' | 'public';
+export interface ExposeDef {
+    /** Method on the photon class. */
+    handler: string;
+    /** SameSite cookie required (`private`) or anonymous OK (`public`). */
+    visibility: ExposeVisibility;
+}
+export declare function extractExposesFromSource(source: string): ExposeDef[];
+/**
+ * Convert a method name to its kebab-cased route segment. Matches the
+ * convention the bridge fetch fallback uses (`fetch('/api/<kebab>', ...)`).
+ *
+ *   getCurrentUser → get-current-user
+ *   listUsers      → list-users
+ *   billing        → billing
+ */
+export declare function methodToKebab(name: string): string;
+//# sourceMappingURL=expose-route-extractor.d.ts.map

package/dist/shared/expose-route-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expose-route-extractor.d.ts","sourceRoot":"","sources":["../../src/shared/expose-route-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEpD,MAAM,WAAW,SAAS;IACxB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,UAAU,EAAE,gBAAgB,CAAC;CAC9B;AAWD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,CAqBpE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKlD"}

package/dist/shared/expose-route-extractor.js

@@ -0,0 +1,64 @@
+/**
+ * Source-level extractor for `@expose` declarations.
+ *
+ * v1.29 Track C. Methods tagged `@expose` are auto-bound to a kebab-cased
+ * `/api/<method>` POST endpoint so a same-origin SPA can call them via
+ * fetch without writing per-method `@post` directives. `@expose public`
+ * widens this from "SameSite-cookie required" to "any caller" — useful
+ * for anonymous public surfaces (iCal feeds, billing portals, etc.).
+ *
+ * Like `http-route-extractor.ts`, this runs against raw source so the
+ * extractor doesn't depend on whatever shape the published photon-core
+ * SchemaExtractor returns. Both the runtime dispatcher and the Cloudflare
+ * deploy code-gen consume the same output.
+ *
+ *   /‍** @expose *‍/        async getCurrentUser() { ... }   → private
+ *   /‍** @expose public *‍/ async billing()        { ... }   → public
+ *   (no @expose tag)         async listUsers()    { ... }   → MCP-only
+ */
+const JSDOC_BLOCK_RE = /\/\*\*([\s\S]*?)\*\//g;
+const METHOD_RE = /^\s*(?:public\s+|private\s+|protected\s+)?(?:async\s+)?(\w+)\s*\(/;
+// Anchor `@expose` to a JSDoc tag position — either the very start of the
+// block body (single-line `/** @expose */`) or a JSDoc line that begins
+// with `*`. Prevents prose mentions like `No @expose — MCP-only` from
+// tripping the matcher. The visibility capture excludes `*` so it stops
+// at the JSDoc terminator on single-line blocks.
+const EXPOSE_TAG_RE = /(?:^\s*|\n\s*\*\s*)@expose\b(?:[ \t]+([^\s*]+))?/im;
+export function extractExposesFromSource(source) {
+    const exposes = [];
+    JSDOC_BLOCK_RE.lastIndex = 0;
+    let block;
+    while ((block = JSDOC_BLOCK_RE.exec(source)) !== null) {
+        const jsdocBody = block[1];
+        const exposeMatch = jsdocBody.match(EXPOSE_TAG_RE);
+        if (!exposeMatch)
+            continue;
+        const after = source.slice(block.index + block[0].length);
+        const methodMatch = after.match(METHOD_RE);
+        if (!methodMatch)
+            continue;
+        // The argument after @expose, if present, is one of: 'public' (widens
+        // exposure to anonymous callers) or anything else (treated as no
+        // visibility hint — defaults to private). This is intentionally loose:
+        // adding new visibility levels later doesn't break existing callers
+        // that already wrote `@expose public`.
+        const visibility = exposeMatch[1]?.trim().toLowerCase() === 'public' ? 'public' : 'private';
+        exposes.push({ handler: methodMatch[1], visibility });
+    }
+    return exposes;
+}
+/**
+ * Convert a method name to its kebab-cased route segment. Matches the
+ * convention the bridge fetch fallback uses (`fetch('/api/<kebab>', ...)`).
+ *
+ *   getCurrentUser → get-current-user
+ *   listUsers      → list-users
+ *   billing        → billing
+ */
+export function methodToKebab(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+        .toLowerCase();
+}
+//# sourceMappingURL=expose-route-extractor.js.map

package/dist/shared/expose-route-extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expose-route-extractor.js","sourceRoot":"","sources":["../../src/shared/expose-route-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAWH,MAAM,cAAc,GAAG,uBAAuB,CAAC;AAC/C,MAAM,SAAS,GAAG,mEAAmE,CAAC;AACtF,0EAA0E;AAC1E,wEAAwE;AACxE,sEAAsE;AACtE,wEAAwE;AACxE,iDAAiD;AACjD,MAAM,aAAa,GAAG,oDAAoD,CAAC;AAE3E,MAAM,UAAU,wBAAwB,CAAC,MAAc;IACrD,MAAM,OAAO,GAAgB,EAAE,CAAC;IAChC,cAAc,CAAC,SAAS,GAAG,CAAC,CAAC;IAC7B,IAAI,KAA6B,CAAC;IAClC,OAAO,CAAC,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACtD,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QAC3B,MAAM,WAAW,GAAG,SAAS,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QACnD,IAAI,CAAC,WAAW;YAAE,SAAS;QAC3B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAC1D,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,CAAC,WAAW;YAAE,SAAS;QAC3B,sEAAsE;QACtE,iEAAiE;QACjE,uEAAuE;QACvE,oEAAoE;QACpE,uCAAuC;QACvC,MAAM,UAAU,GACd,WAAW,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3E,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,IAAI;SACR,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;SACtC,OAAO,CAAC,uBAAuB,EAAE,OAAO,CAAC;SACzC,WAAW,EAAE,CAAC;AACnB,CAAC"}

package/dist/shared/extract-claims.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Extract auth claims from incoming HTTP request headers.
+ *
+ * Used by the standalone HTTP server (Track C closure) to discover which
+ * claim bag the per-claim instance pool should key on. Two sources are
+ * recognized today, matching what `extractInstance` in the Cloudflare
+ * Worker template recognizes — same headers, same precedence:
+ *
+ *   1. `Cf-Access-Authenticated-User-Email` — set by Cloudflare Access at
+ *      the edge after JWT verification. Trusted (origin is behind CF).
+ *   2. `Cf-Access-Jwt-Assertion` — the raw JWT. Decoded payload fields
+ *      (email, sub, ...) are merged into the claim bag. The signature is
+ *      NOT re-verified; CF already validated it before forwarding to the
+ *      origin. If you run the standalone server outside Cloudflare and
+ *      want a different trust boundary, add a verification step here.
+ *
+ * The standalone server is the only consumer right now. The MCP daemon
+ * pulls claims from its CLI / streamable-HTTP authentication path; the
+ * Cloudflare Worker template does its own header read. Keep the three
+ * surfaces in sync when adding a new claim source.
+ */
+import type { IncomingHttpHeaders } from 'node:http';
+/**
+ * Read claims from CF Access headers. Returns undefined when no
+ * recognized auth headers are present so the caller can fall back to the
+ * default instance without a bound claim.
+ *
+ * The returned bag uses lowercased standard claim names (`email`, `sub`,
+ * etc.) so `resolveInstanceFromClaims` finds them by their canonical key
+ * regardless of the JWT's casing.
+ */
+export declare function extractClaimsFromHeaders(headers: IncomingHttpHeaders): Record<string, unknown> | undefined;
+//# sourceMappingURL=extract-claims.d.ts.map

package/dist/shared/extract-claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-claims.d.ts","sourceRoot":"","sources":["../../src/shared/extract-claims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAGrD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,mBAAmB,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CA8BrC"}

package/dist/shared/extract-claims.js

@@ -0,0 +1,60 @@
+/**
+ * Extract auth claims from incoming HTTP request headers.
+ *
+ * Used by the standalone HTTP server (Track C closure) to discover which
+ * claim bag the per-claim instance pool should key on. Two sources are
+ * recognized today, matching what `extractInstance` in the Cloudflare
+ * Worker template recognizes — same headers, same precedence:
+ *
+ *   1. `Cf-Access-Authenticated-User-Email` — set by Cloudflare Access at
+ *      the edge after JWT verification. Trusted (origin is behind CF).
+ *   2. `Cf-Access-Jwt-Assertion` — the raw JWT. Decoded payload fields
+ *      (email, sub, ...) are merged into the claim bag. The signature is
+ *      NOT re-verified; CF already validated it before forwarding to the
+ *      origin. If you run the standalone server outside Cloudflare and
+ *      want a different trust boundary, add a verification step here.
+ *
+ * The standalone server is the only consumer right now. The MCP daemon
+ * pulls claims from its CLI / streamable-HTTP authentication path; the
+ * Cloudflare Worker template does its own header read. Keep the three
+ * surfaces in sync when adding a new claim source.
+ */
+import { Buffer } from 'node:buffer';
+/**
+ * Read claims from CF Access headers. Returns undefined when no
+ * recognized auth headers are present so the caller can fall back to the
+ * default instance without a bound claim.
+ *
+ * The returned bag uses lowercased standard claim names (`email`, `sub`,
+ * etc.) so `resolveInstanceFromClaims` finds them by their canonical key
+ * regardless of the JWT's casing.
+ */
+export function extractClaimsFromHeaders(headers) {
+    const claims = {};
+    const cfEmail = headers['cf-access-authenticated-user-email'];
+    if (typeof cfEmail === 'string' && cfEmail.length > 0) {
+        claims.email = cfEmail;
+    }
+    const cfJwt = headers['cf-access-jwt-assertion'];
+    if (typeof cfJwt === 'string' && cfJwt.includes('.')) {
+        try {
+            const part = cfJwt.split('.')[1];
+            const padded = part + '='.repeat((4 - (part.length % 4)) % 4);
+            const decoded = Buffer.from(padded.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf-8');
+            const payload = JSON.parse(decoded);
+            // Don't overwrite a claim already set from a more specific header.
+            for (const [k, v] of Object.entries(payload)) {
+                if (!(k in claims))
+                    claims[k] = v;
+            }
+        }
+        catch {
+            // Malformed JWT — silently ignore, the email header (if present)
+            // already populated the bag. A misformed JWT shouldn't 500 the
+            // request; the auth gate downstream decides what to do with no
+            // claims.
+        }
+    }
+    return Object.keys(claims).length > 0 ? claims : undefined;
+}
+//# sourceMappingURL=extract-claims.js.map

package/dist/shared/extract-claims.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-claims.js","sourceRoot":"","sources":["../../src/shared/extract-claims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAA4B;IAE5B,MAAM,MAAM,GAA4B,EAAE,CAAC;IAE3C,MAAM,OAAO,GAAG,OAAO,CAAC,oCAAoC,CAAC,CAAC;IAC9D,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtD,MAAM,CAAC,KAAK,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC;IACjD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACrD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YACjC,MAAM,MAAM,GAAG,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC9D,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAC1F,OAAO,CACR,CAAC;YACF,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAA4B,CAAC;YAC/D,mEAAmE;YACnE,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC7C,IAAI,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC;oBAAE,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,iEAAiE;YACjE,+DAA+D;YAC/D,+DAA+D;YAC/D,UAAU;QACZ,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7D,CAAC"}

package/dist/shared/http-route-extractor.d.ts

@@ -18,6 +18,12 @@ export interface HttpRouteDef {
     method: string;
     path: string;
     handler: string;
+    /**
+     * Optional `@format <name>` declared on the same JSDoc block. Used by the
+     * HTTP dispatcher's content-negotiation path (Track A) when the handler
+     * returns a plain value rather than a Response.
+     */
+    format?: string;
 }
 export declare function extractHttpRoutesFromSource(source: string): HttpRouteDef[];
 //# sourceMappingURL=http-route-extractor.d.ts.map

package/dist/shared/http-route-extractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-route-extractor.d.ts","sourceRoot":"","sources":["../../src/shared/http-route-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,EAAE,CAQ1E"}
+{"version":3,"file":"http-route-extractor.d.ts","sourceRoot":"","sources":["../../src/shared/http-route-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAYD,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,EAAE,CAqB1E"}

package/dist/shared/http-route-extractor.js

@@ -1,10 +1,34 @@
-const ROUTE_RE = /\/\*\*[\s\S]*?@(get|post)\s+(\/[^\s*]*)[\s\S]*?\*\/\s*(?:async\s+)?(\w+)\s*\(/gi;
+// Find each JSDoc close `*/` and the method declaration that follows.
+// Crucially we use the JSDoc body BETWEEN the opener and THIS specific close —
+// not greedy back to a far-earlier `/**`. That keeps tag scans (@format, ...)
+// scoped to the SAME block as the route directive, rather than leaking from
+// a class-level docblock that happens to mention `@format` in prose.
+const JSDOC_BLOCK_RE = /\/\*\*([\s\S]*?)\*\//g;
+const METHOD_RE = /^\s*(?:public\s+|private\s+|protected\s+)?(?:async\s+)?(\w+)\s*\(/;
+const ROUTE_TAG_RE = /@(get|post)\s+(\/[^\s*]*)/i;
+const FORMAT_RE = /@format\s+([\w:-]+)/i;
 export function extractHttpRoutesFromSource(source) {
     const routes = [];
-    ROUTE_RE.lastIndex = 0;
-    let m;
-    while ((m = ROUTE_RE.exec(source)) !== null) {
-        routes.push({ method: m[1].toUpperCase(), path: m[2], handler: m[3] });
+    JSDOC_BLOCK_RE.lastIndex = 0;
+    let block;
+    while ((block = JSDOC_BLOCK_RE.exec(source)) !== null) {
+        const jsdocBody = block[1];
+        const routeMatch = jsdocBody.match(ROUTE_TAG_RE);
+        if (!routeMatch)
+            continue;
+        const after = source.slice(block.index + block[0].length);
+        const methodMatch = after.match(METHOD_RE);
+        if (!methodMatch)
+            continue;
+        const route = {
+            method: routeMatch[1].toUpperCase(),
+            path: routeMatch[2],
+            handler: methodMatch[1],
+        };
+        const formatMatch = jsdocBody.match(FORMAT_RE);
+        if (formatMatch)
+            route.format = formatMatch[1];
+        routes.push(route);
     }
     return routes;
 }

package/dist/shared/http-route-extractor.js.map

@@ -1 +1 @@
-{"version":3,"file":"http-route-extractor.js","sourceRoot":"","sources":["../../src/shared/http-route-extractor.ts"],"names":[],"mappings":"AAsBA,MAAM,QAAQ,GAAG,iFAAiF,CAAC;AAEnG,MAAM,UAAU,2BAA2B,CAAC,MAAc;IACxD,MAAM,MAAM,GAAmB,EAAE,CAAC;IAClC,QAAQ,CAAC,SAAS,GAAG,CAAC,CAAC;IACvB,IAAI,CAAyB,CAAC;IAC9B,OAAO,CAAC,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAC5C,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"http-route-extractor.js","sourceRoot":"","sources":["../../src/shared/http-route-extractor.ts"],"names":[],"mappings":"AA4BA,sEAAsE;AACtE,+EAA+E;AAC/E,8EAA8E;AAC9E,4EAA4E;AAC5E,qEAAqE;AACrE,MAAM,cAAc,GAAG,uBAAuB,CAAC;AAC/C,MAAM,SAAS,GAAG,mEAAmE,CAAC;AACtF,MAAM,YAAY,GAAG,4BAA4B,CAAC;AAClD,MAAM,SAAS,GAAG,sBAAsB,CAAC;AAEzC,MAAM,UAAU,2BAA2B,CAAC,MAAc;IACxD,MAAM,MAAM,GAAmB,EAAE,CAAC;IAClC,cAAc,CAAC,SAAS,GAAG,CAAC,CAAC;IAC7B,IAAI,KAA6B,CAAC;IAClC,OAAO,CAAC,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACtD,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QAC3B,MAAM,UAAU,GAAG,SAAS,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QACjD,IAAI,CAAC,UAAU;YAAE,SAAS;QAC1B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAC1D,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,CAAC,WAAW;YAAE,SAAS;QAC3B,MAAM,KAAK,GAAiB;YAC1B,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE;YACnC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;YACnB,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC;SACxB,CAAC;QACF,MAAM,WAAW,GAAG,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC/C,IAAI,WAAW;YAAE,KAAK,CAAC,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;QAC/C,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/shared/instance-binding.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Auth → instance binding registry (Track C).
+ *
+ * For multi-tenant `@stateful` photons: when a caller authenticates, the
+ * loader looks up the photon's `@auth` scheme here to find which JWT/identity
+ * claim should drive the per-user instance name. Photons get one isolated
+ * `this.memory` namespace per claim value without their authors writing
+ * per-call routing.
+ *
+ *   /‍** @auth cf-access *‍/  →  caller.claims.email   →  instance "alice@x.com"
+ *   /‍** @auth oauth     *‍/  →  caller.claims.sub     →  instance "user_42"
+ *
+ * The registry is a pure module (no I/O, no state). The Cloudflare Worker
+ * template runs the equivalent mapping at the outer Worker layer (per-DO
+ * selection); see `extractInstance` in `templates/cloudflare/worker.ts.template`.
+ *
+ * Scope note: this fills `parameters._targetInstance` for downstream
+ * consumers (the daemon at `daemon/server.ts:4408` and the streamable-HTTP
+ * transport at `:1928-1933`). The standalone `photon mcp` server is
+ * single-tenant by design — it loads one photon instance per process — so
+ * the binding has no effect there. Multi-tenant deploys go through the
+ * daemon or Cloudflare.
+ */
+/**
+ * Resolve the instance name a caller should be routed to, based on their
+ * auth scheme + claims. Returns undefined when the scheme is unknown, the
+ * required claim is missing, or claims is empty — the caller should leave
+ * `_targetInstance` unset and fall back to the default singleton.
+ *
+ * @param scheme    Value from `@auth <scheme>` (e.g. `cf-access`, `oauth`)
+ * @param claims    Authenticated caller's claim bag (from `caller.claims`)
+ * @param override  Optional explicit claim name from `@auth <scheme> claim=<name>`
+ *                  — wins over the scheme default. Lets a photon route by
+ *                  org id, tenant slug, etc., without a new scheme entry.
+ */
+export declare function resolveInstanceFromClaims(scheme: string | undefined, claims: Record<string, unknown> | undefined, override?: string): string | undefined;
+/**
+ * Parse the `claim=<name>` modifier from an `@auth` directive value.
+ *
+ *   `cf-access`             → { scheme: 'cf-access', claim: undefined }
+ *   `cf-access claim=email` → { scheme: 'cf-access', claim: 'email' }
+ *   `oauth claim=org_id`    → { scheme: 'oauth',     claim: 'org_id' }
+ *
+ * Loader callers pass the resulting `claim` field to
+ * `resolveInstanceFromClaims` as the override.
+ */
+export declare function parseAuthDirective(value: string | undefined): {
+    scheme: string | undefined;
+    claim: string | undefined;
+};
+/** Exposed for tests so the table stays in sync with the CF worker template. */
+export declare function getSchemeDefaultClaim(scheme: string): string | undefined;
+//# sourceMappingURL=instance-binding.d.ts.map

package/dist/shared/instance-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-binding.d.ts","sourceRoot":"","sources":["../../src/shared/instance-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAYH;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAOpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG;IAC7D,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B,CAaA;AAED,gFAAgF;AAChF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAExE"}

package/dist/shared/instance-binding.js

@@ -0,0 +1,85 @@
+/**
+ * Auth → instance binding registry (Track C).
+ *
+ * For multi-tenant `@stateful` photons: when a caller authenticates, the
+ * loader looks up the photon's `@auth` scheme here to find which JWT/identity
+ * claim should drive the per-user instance name. Photons get one isolated
+ * `this.memory` namespace per claim value without their authors writing
+ * per-call routing.
+ *
+ *   /‍** @auth cf-access *‍/  →  caller.claims.email   →  instance "alice@x.com"
+ *   /‍** @auth oauth     *‍/  →  caller.claims.sub     →  instance "user_42"
+ *
+ * The registry is a pure module (no I/O, no state). The Cloudflare Worker
+ * template runs the equivalent mapping at the outer Worker layer (per-DO
+ * selection); see `extractInstance` in `templates/cloudflare/worker.ts.template`.
+ *
+ * Scope note: this fills `parameters._targetInstance` for downstream
+ * consumers (the daemon at `daemon/server.ts:4408` and the streamable-HTTP
+ * transport at `:1928-1933`). The standalone `photon mcp` server is
+ * single-tenant by design — it loads one photon instance per process — so
+ * the binding has no effect there. Multi-tenant deploys go through the
+ * daemon or Cloudflare.
+ */
+/**
+ * Default claim name for each well-known `@auth` scheme. Matches the
+ * Cloudflare Worker template's `extractInstance` behavior so an auth-bound
+ * photon picks the same instance name on the local daemon and on CF.
+ */
+const SCHEME_DEFAULT_CLAIM = {
+    'cf-access': 'email',
+    oauth: 'sub',
+};
+/**
+ * Resolve the instance name a caller should be routed to, based on their
+ * auth scheme + claims. Returns undefined when the scheme is unknown, the
+ * required claim is missing, or claims is empty — the caller should leave
+ * `_targetInstance` unset and fall back to the default singleton.
+ *
+ * @param scheme    Value from `@auth <scheme>` (e.g. `cf-access`, `oauth`)
+ * @param claims    Authenticated caller's claim bag (from `caller.claims`)
+ * @param override  Optional explicit claim name from `@auth <scheme> claim=<name>`
+ *                  — wins over the scheme default. Lets a photon route by
+ *                  org id, tenant slug, etc., without a new scheme entry.
+ */
+export function resolveInstanceFromClaims(scheme, claims, override) {
+    if (!claims || typeof claims !== 'object')
+        return undefined;
+    const claimName = override ?? (scheme ? SCHEME_DEFAULT_CLAIM[scheme] : undefined);
+    if (!claimName)
+        return undefined;
+    const value = claims[claimName];
+    if (typeof value === 'string' && value.length > 0)
+        return value;
+    return undefined;
+}
+/**
+ * Parse the `claim=<name>` modifier from an `@auth` directive value.
+ *
+ *   `cf-access`             → { scheme: 'cf-access', claim: undefined }
+ *   `cf-access claim=email` → { scheme: 'cf-access', claim: 'email' }
+ *   `oauth claim=org_id`    → { scheme: 'oauth',     claim: 'org_id' }
+ *
+ * Loader callers pass the resulting `claim` field to
+ * `resolveInstanceFromClaims` as the override.
+ */
+export function parseAuthDirective(value) {
+    if (!value)
+        return { scheme: undefined, claim: undefined };
+    const parts = value.trim().split(/\s+/);
+    const scheme = parts[0];
+    let claim;
+    for (const part of parts.slice(1)) {
+        const m = part.match(/^claim=(.+)$/);
+        if (m) {
+            claim = m[1];
+            break;
+        }
+    }
+    return { scheme, claim };
+}
+/** Exposed for tests so the table stays in sync with the CF worker template. */
+export function getSchemeDefaultClaim(scheme) {
+    return SCHEME_DEFAULT_CLAIM[scheme];
+}
+//# sourceMappingURL=instance-binding.js.map

package/dist/shared/instance-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-binding.js","sourceRoot":"","sources":["../../src/shared/instance-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;GAIG;AACH,MAAM,oBAAoB,GAA2B;IACnD,WAAW,EAAE,OAAO;IACpB,KAAK,EAAE,KAAK;CACb,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAA0B,EAC1B,MAA2C,EAC3C,QAAiB;IAEjB,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC5D,MAAM,SAAS,GAAG,QAAQ,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAClF,IAAI,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IACjC,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IAChC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAChE,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAyB;IAI1D,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAC3D,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,KAAyB,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAClC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QACrC,IAAI,CAAC,EAAE,CAAC;YACN,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YACb,MAAM;QACR,CAAC;IACH,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAC3B,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,qBAAqB,CAAC,MAAc;IAClD,OAAO,oBAAoB,CAAC,MAAM,CAAC,CAAC;AACtC,CAAC"}

package/dist/types/server-types.d.ts

@@ -23,6 +23,7 @@ export interface PhotonClassWithMeta extends PhotonClassExtended {
         method: string;
         path: string;
         handler: string;
+        format?: string;
     }>;
 }
 /**

package/dist/types/server-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-types.d.ts","sourceRoot":"","sources":["../../src/types/server-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB;IAC9D,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qEAAqE;IACrE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,uCAAuC;IACvC,WAAW,CAAC,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxE;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,+CAA+C;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB"}
+{"version":3,"file":"server-types.d.ts","sourceRoot":"","sources":["../../src/types/server-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB;IAC9D,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qEAAqE;IACrE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,uCAAuC;IACvC,WAAW,CAAC,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACzF;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,+CAA+C;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portel/photon",
-  "version": "1.28.2",
+  "version": "1.29.0",
   "description": "You focus on the business logic. We'll enable the rest. Build MCP servers and CLI tools in a single TypeScript file.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "prepublishOnly": "node -e \"const p=require('./package.json'); if(JSON.stringify(p.dependencies).includes('file:')) { console.error('ERROR: file: dependency found.'); process.exit(1); }\" && node -e \"const fs=require('fs'),path=require('path'); const p=require('./package.json'); for(const d of Object.keys(p.dependencies||{})){const t=path.join('node_modules',d); if(fs.lstatSync(t).isSymbolicLink()){console.error('ERROR: '+d+' is npm-linked. Run: npm unlink '+d+' && npm install '+d); process.exit(1);}}\" && npm run build && npm run build:beam",
     "test": "bash scripts/run-tests.sh",
     "test:chain": "npm run test:all",
-    "test:all": "npm run build && npm run test:security && npm run test:schema && npm run test:marketplace && npm run test:loader && npm run test:server && npm run test:integration && npm run test:ui-resources && npm run test:client-adaptive && npm run test:zero-config && npm run test:mcp-config && npm run test:cli && npm run test:logger && npm run test:error-handler && npm run test:validation && npm run test:daemon-pubsub && npm run test:daemon-buffer && npm run test:instance-drift && npm run test:daemon-watcher && npm run test:ui-rendering && npm run test:photon-instance-manager && npm run test:viewport-aware-proxy && npm run test:viewport-manager && npm run test:pagination-integration && npm run test:pagination-performance && npm run test:pagination-phase5 && npm run test:pagination-phase5c && npm run test:pagination-phase5d && npm run test:phase6a && npm run test:phase6b && npm run test:phase6c && npm run test:phase6d && npm run test:promises && npm run test:readme",
+    "test:all": "npm run build && npm run test:security && npm run test:schema && npm run test:marketplace && npm run test:loader && npm run test:server && npm run test:integration && npm run test:byte-compat && npm run test:format-registry && npm run test:content-negotiation && npm run test:ui-resources && npm run test:client-adaptive && npm run test:zero-config && npm run test:mcp-config && npm run test:cli && npm run test:logger && npm run test:error-handler && npm run test:validation && npm run test:daemon-pubsub && npm run test:daemon-buffer && npm run test:instance-drift && npm run test:daemon-watcher && npm run test:ui-rendering && npm run test:photon-instance-manager && npm run test:viewport-aware-proxy && npm run test:viewport-manager && npm run test:pagination-integration && npm run test:pagination-performance && npm run test:pagination-phase5 && npm run test:pagination-phase5c && npm run test:pagination-phase5d && npm run test:phase6a && npm run test:phase6b && npm run test:phase6c && npm run test:phase6d && npm run test:promises && npm run test:readme",
     "test:daemon-watcher": "npx tsx tests/daemon-watcher.test.ts",
     "test:instance-drift": "npx tsx tests/instance-drift.test.ts",
     "test:photon-instance-manager": "npx vitest run tests/photon-instance-manager.test.ts",
@@ -63,6 +63,9 @@
     "test:loader": "npx tsx tests/loader.test.ts",
     "test:server": "npx tsx tests/server.test.ts",
     "test:integration": "npx tsx tests/integration.test.ts",
+    "test:byte-compat": "RUN_E2E=1 npx vitest run tests/v128-byte-compat.test.ts",
+    "test:format-registry": "npx vitest run tests/format-registry.test.ts",
+    "test:content-negotiation": "RUN_E2E=1 npx vitest run tests/http-content-negotiation.test.ts",
     "test:ui-resources": "npx tsx tests/ui-resources.test.ts",
     "test:ui-rendering": "npx tsx --test tests/ui/result-rendering.test.ts",
     "test:client-adaptive": "npx tsx tests/client-adaptive.test.ts",
@@ -113,7 +116,7 @@
     "@modelcontextprotocol/ext-apps": "^1.0.1",
     "@modelcontextprotocol/sdk": "^1.25.2",
     "@portel/cli": "^1.1.0",
-    "@portel/photon-core": "^2.25.0",
+    "@portel/photon-core": "^2.26.0",
     "boxen": "^8.0.1",
     "chalk": "^5.4.1",
     "chart.js": "^4.5.1",

package/templates/cloudflare/worker.ts.template

@@ -570,6 +570,19 @@ function matchHttpRoute(
   return null;
 }
 
+/**
+ * camelCase → kebab-case for `/api/<kebab>` route segments.
+ * Mirrors `src/shared/expose-route-extractor.ts#methodToKebab`. Keep both
+ * implementations in lock-step so an `@expose`'d method binds to the
+ * same path on the local server and on Cloudflare.
+ */
+function methodToKebab(name: string): string {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+    .toLowerCase();
+}
+
 function matchPathPattern(
   pattern: string,
   pathname: string
@@ -698,6 +711,14 @@ abstract class BasePhotonDO extends DurableObject<Env> {
   protected abstract readonly photonName: string;
   protected abstract readonly toolDefinitions: any[];
   protected readonly httpRoutes: { method: string; path: string; handler: string }[] = [];
+  /**
+   * Methods declared with `@expose` (Track C). Bound to `POST /api/<kebab>`
+   * with a SameSite-style visibility check. `private` requires a browser-set
+   * `Sec-Fetch-Site: same-origin` (or `same-site`) header — anything else,
+   * or no header, is denied. `public` skips the check (anonymous third-party
+   * callers like RSS readers).
+   */
+  protected readonly exposes: { handler: string; visibility: 'private' | 'public' }[] = [];
   protected abstract createPhoton(): any;
 
   protected photon: any;
@@ -856,6 +877,67 @@ abstract class BasePhotonDO extends DurableObject<Env> {
       }
     }
 
+    // Track C: @expose auto-RPC. POST /api/<kebab> dispatches to an
+    // `@expose`'d method. `@get`/`@post` already won the matchedRoute
+    // check above, so this only fires when no explicit HTTP route
+    // matched. Visibility gate: `private` requires a browser-set
+    // `Sec-Fetch-Site: same-origin` (or `same-site`) header. The Worker
+    // is on the public internet — there is no localhost analog — so an
+    // absent header means deny.
+    if (
+      this.exposes.length > 0 &&
+      request.method === 'POST' &&
+      url.pathname.startsWith('/api/')
+    ) {
+      const segment = url.pathname.slice('/api/'.length);
+      const exposed = this.exposes.find((e) => methodToKebab(e.handler) === segment);
+      if (exposed) {
+        if (exposed.visibility === 'private') {
+          const sfs = request.headers.get('sec-fetch-site')?.toLowerCase() ?? '';
+          if (sfs !== 'same-origin' && sfs !== 'same-site') {
+            return new Response('Forbidden: cross-site @expose call', {
+              status: 403,
+              headers: CORS_HEADERS,
+            });
+          }
+        }
+        const fn = (this.photon as any)[exposed.handler];
+        if (typeof fn !== 'function') {
+          return new Response(`Unknown handler: ${exposed.handler}`, {
+            status: 500,
+            headers: CORS_HEADERS,
+          });
+        }
+        let parsed: unknown = {};
+        try {
+          const text = await request.text();
+          if (text.length > 0) parsed = JSON.parse(text);
+        } catch {
+          return new Response('Invalid JSON body', { status: 400, headers: CORS_HEADERS });
+        }
+        try {
+          const result = await fn.call(this.photon, parsed);
+          if (result instanceof Response) return result;
+          return Response.json(result, { headers: CORS_HEADERS });
+        } catch (error: any) {
+          return new Response(error?.message ?? 'Internal Server Error', {
+            status: 500,
+            headers: CORS_HEADERS,
+          });
+        }
+      }
+    }
+
+    // Fall through to the [assets] binding (Track E). The wrangler.toml
+    // emits this binding only when the host photon has an `assets/`
+    // companion folder, so the typeof guard keeps non-asset deploys
+    // quiet (no extra fetch round-trip when the binding is absent).
+    const assets = (this.env as any).ASSETS as { fetch: (req: Request) => Promise<Response> } | undefined;
+    if (assets && request.method === 'GET') {
+      const assetResponse = await assets.fetch(request);
+      if (assetResponse.status !== 404) return assetResponse;
+    }
+
     return new Response('Not Found', { status: 404, headers: CORS_HEADERS });
   }
 
@@ -1043,13 +1125,18 @@ const CF_ACCESS_ENABLED = __CF_ACCESS_ENABLED__;
  */
 function extractInstance(request: Request): string {
   if (CF_ACCESS_ENABLED) {
+    const headerEmail = request.headers.get('Cf-Access-Authenticated-User-Email');
+    if (headerEmail) return headerEmail;
     const jwt = request.headers.get('Cf-Access-Jwt-Assertion');
     if (jwt) {
       try {
-        const payload = JSON.parse(atob(jwt.split('.')[1]));
+        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;
-      } catch {
-        // malformed JWT — fall through to default resolution
+      } catch (err) {
+        console.warn('extractInstance: JWT parse failed', err);
       }
     }
   }

package/templates/cloudflare/wrangler.toml.template

@@ -27,7 +27,7 @@ __DURABLE_OBJECT_BINDINGS__
 [[migrations]]
 tag = "v1"
 new_sqlite_classes = __SQLITE_CLASSES__
-
+__ASSETS_BLOCK__
 # Uncomment to add environment variables
 # [vars]
 # API_KEY = "your-api-key"