akanjs 3.0.0-alpha.2 → 3.0.0-alpha.21

package/server/devtools/signalSerializer.ts

@@ -204,7 +204,7 @@ export class SignalSerializer {
     return Object.entries(nodes).flatMap(([key, node]) => {
       const info = meta[key];
       if (!info) return [];
-      const transport = node.type === "query" || node.type === "mutation" ? "http" : "ws";
+      const transport = node.type === "pubsub" || node.type === "message" ? "ws" : "http";
       return [
         {
           signal,
@@ -212,7 +212,7 @@ export class SignalSerializer {
           source: typeof source === "function" ? source(key) : source,
           type: node.type,
           transport,
-          method: node.type === "query" ? "GET" : node.type === "mutation" ? "POST" : null,
+          method: node.type === "mutation" ? "POST" : transport === "http" ? "GET" : null,
           path:
             transport === "ws"
               ? SignalSerializer.#joinPath(prefix, websocketPrefix)

package/server/devtools/types.ts

@@ -134,7 +134,7 @@ export interface ConstantData {
 export type { ArgType, SerializedArg, SerializedReturns };
 
 export interface EndpointNode {
-  type: "query" | "mutation" | "pubsub" | "message";
+  type: "query" | "mutation" | "pubsub" | "message" | "prompt";
   args: SerializedArg[];
   returns: SerializedReturns;
   path?: string;
@@ -192,7 +192,7 @@ export interface RouteRow {
   signal: string;
   key: string;
   source: "declared" | "crud" | "slice";
-  type: "query" | "mutation" | "message" | "pubsub";
+  type: "query" | "mutation" | "message" | "pubsub" | "prompt";
   transport: "http" | "ws";
   method: "GET" | "POST" | null;
   /** Fully prefixed, `:param` placeholders intact — e.g. `/api/user/:userId`. */

package/server/di/diLifecycle.ts

@@ -12,6 +12,8 @@ import {
   srv,
   type WebsocketAdaptor,
 } from "akanjs/service";
+import { agent as agentSignal } from "../../signal/agent.signal";
+import { agentTurnConstant, agentTurnDocument } from "../../signal/agentTurn";
 import { Base, BaseEndpoint, BaseInternal } from "../../signal/base.signal";
 import type { Endpoint } from "../../signal/endpoint";
 import type { Internal } from "../../signal/internal";
@@ -82,14 +84,24 @@ export class DiLifecycle {
     };
   }
 
+  static #envOn(...names: string[]) {
+    return !names.some((name) => process.env[name] === "false" || process.env[name] === "0");
+  }
+
   constructor(env: BaseEnv, serverMode: "federation" | "batch" | "all", ...libs: AkanLib[]) {
     this.#env = env;
-    this.#predefinedAdaptor = getPredefinedAdaptor(env.databaseMode ?? "single");
+    
+    this.#predefinedAdaptor = { ...getPredefinedAdaptor(env.databaseMode ?? "single") };
     this.#libs = libs;
     this.#service.set("base", {
       service: srv.base,
       signal: SignalRegistry.registerService("base" as const, BaseInternal, BaseEndpoint, Base),
     });
+
+    const frameworkAgent: ServiceModule | null = DiLifecycle.#envOn("AKAN_AGENT", "AKAN_PUBLIC_AGENT")
+      ? { service: srv.agent, signal: agentSignal }
+      : null;
+    if (frameworkAgent) this.#service.set("agent", frameworkAgent);
     this.#middleware.set(Logging.refName, Logging);
     const defaultOption = createDefaultAkanOption();
     defaultOption.getMiddlewares().forEach((middleware) => {
@@ -102,6 +114,14 @@ export class DiLifecycle {
       lib.option.getMiddlewares().forEach((middleware) => {
         this.#middleware.set(middleware.refName, middleware);
       });
+      lib.option.getAdaptorOverrides().forEach(({ role, adaptor }) => {
+        const roleKey = Object.entries(this.#predefinedAdaptorRole).find(([, roleCls]) => roleCls === role)?.[0];
+        if (!roleKey) {
+          this.logger.warn(`applyAdaptor got an unknown role "${role.refName}" — override ignored`);
+          return;
+        }
+        (this.#predefinedAdaptor as Record<string, AdaptorCls>)[roleKey] = adaptor;
+      });
       this.webProxies.push(...lib.option.getWebProxies());
       lib.database.forEach((mod) => {
         databaseCandidates.set(mod.constant.refName, { refName: mod.constant.refName, module: mod });
@@ -122,6 +142,10 @@ export class DiLifecycle {
       if (disabledModules.has(refName)) return;
       this.#service.set(refName, module as ServiceModule);
     });
+    if (frameworkAgent && this.#service.get("agent") !== frameworkAgent)
+      this.logger.info("agent relay is provided by a lib module — the framework's is skipped");
+    if (!this.#scalar.has("agentTurn"))
+      this.#scalar.set("agentTurn", { constant: agentTurnConstant, database: agentTurnDocument });
     this.#database.forEach((mod) => {
       const { adaptor, schema } = DatabaseResolver.resolveDatabase(mod.constant, mod.database);
       this.#adaptor.set(adaptor.refName, adaptor);
@@ -365,7 +389,11 @@ export class DiLifecycle {
   }
 
   async #initializeUses() {
-    const uses = Object.assign({}, ...this.#libs.map((lib) => lib.option.getUses(this.#env)));
+    
+    const uses = Object.assign(
+      { llmOption: Object.assign({}, ...this.#libs.map((lib) => lib.option.getLlm(this.#env))) },
+      ...this.#libs.map((lib) => lib.option.getUses(this.#env)),
+    );
     const entries = Object.entries(uses);
     await runStage(
       "uses",
@@ -473,7 +501,7 @@ export class DiLifecycle {
       );
     }
 
-    this.#cascade.seal((refName) => this.getService(refName));
+    this.#cascade.seal((refName: string) => this.getService(refName));
   }
 
   async #initializeInternal() {

package/server/di/predefinedAdaptor.ts

@@ -10,8 +10,11 @@ import {
   ConsoleLogger,
   type DatabaseAdaptor,
   DatabaseAdaptorRole,
+  DeepseekLlm,
   JsonCompressor,
   LibsqlDatabase,
+  type LlmAdaptor,
+  LlmAdaptorRole,
   type LoggingAdaptor,
   LoggingAdaptorRole,
   PostgresDatabase,
@@ -41,6 +44,7 @@ export interface PredefinedAdaptor {
   logging: AdaptorCls<LoggingAdaptor>;
   websocket: AdaptorCls<WebsocketAdaptor>;
   compress: AdaptorCls<CompressAdaptor>;
+  llm: AdaptorCls<LlmAdaptor>;
 }
 
 export const predefinedAdaptorRole = {
@@ -52,6 +56,7 @@ export const predefinedAdaptorRole = {
   logging: LoggingAdaptorRole,
   websocket: WebsocketAdaptorRole,
   compress: CompressAdaptorRole,
+  llm: LlmAdaptorRole,
 } satisfies PredefinedAdaptor;
 
 export const predefinedAdaptor = {
@@ -63,6 +68,7 @@ export const predefinedAdaptor = {
   logging: ConsoleLogger,
   websocket: SolidPubSub,
   compress: JsonCompressor,
+  llm: DeepseekLlm,
 };
 
 export const getPredefinedAdaptor = (mode: DatabaseMode = "single"): PredefinedAdaptor => {

package/server/imageOptimizer.ts

@@ -1,6 +1,8 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { Logger } from "akanjs/common";
+import { isAnimatedImage } from "./animatedImage";
 import { ImageOptimizerError } from "./imageOptimizerError";
 import {
   type AkanImageConfig,
@@ -10,18 +12,6 @@ import {
   mergeAkanImageConfig,
 } from "./types";
 
-type SharpFactory = typeof import("sharp");
-
-let sharpLoad: Promise<SharpFactory> | null = null;
-
-function loadSharp(): Promise<SharpFactory> {
-  sharpLoad ??= import("sharp").then((mod) => {
-    const loaded = mod as unknown as { default?: SharpFactory } & SharpFactory;
-    return loaded.default ?? loaded;
-  });
-  return sharpLoad;
-}
-
 export interface ImageOptimizerOptions {
   publicDir: string;
   cacheDir: string;
@@ -59,18 +49,37 @@ export class ImageOptimizer {
   static readonly #webp = "image/webp";
   static readonly #gif = "image/gif";
   static readonly #avif = "image/avif";
+  static readonly #heic = "image/heic";
   static readonly #bypassTypes = new Set(["image/x-icon", "image/x-icns", "image/bmp", "image/jxl", "image/heic"]);
 
   #publicDir: string;
   #cacheDir: string;
   #prodMode: boolean;
   #config: AkanImageConfig;
+  #logger = new Logger("ImageOptimizer");
 
   constructor({ publicDir, cacheDir, prodMode, config }: ImageOptimizerOptions) {
     this.#publicDir = publicDir;
     this.#cacheDir = cacheDir;
     this.#prodMode = prodMode;
-    this.#config = mergeAkanImageConfig(config);
+    const merged = mergeAkanImageConfig(config);
+    const formats = merged.formats.filter((format) => ImageOptimizer.#isCodecAvailable(format));
+    if (formats.length !== merged.formats.length) {
+      const dropped = merged.formats.filter((format) => !formats.includes(format));
+      this.#logger.warn(`${dropped.join(", ")} needs an OS codec this platform does not have; serving webp instead`);
+    }
+    this.#config = { ...merged, formats: formats.length ? formats : ["image/webp"] };
+  }
+
+  /**
+   * AVIF, HEIC and TIFF ride the OS codec, which only the `system` backend has — macOS and Windows.
+   * A Linux container runs the `bun` backend, where both encode and decode raise
+   * `ERR_IMAGE_FORMAT_UNSUPPORTED`, so those types are decided up front rather than thrown at.
+   */
+  static #isCodecAvailable(contentType: string): boolean {
+    if (contentType !== ImageOptimizer.#avif && contentType !== ImageOptimizer.#heic && contentType !== "image/tiff")
+      return true;
+    return Bun.Image.backend === "system";
   }
 
   async handle(req: Request): Promise<Response> {
@@ -217,7 +226,8 @@ export class ImageOptimizer {
     const shouldBypass =
       inputType === ImageOptimizer.#svg ||
       ImageOptimizer.#bypassTypes.has(inputType) ||
-      (await ImageOptimizer.#isAnimated(source.buffer, inputType));
+      !ImageOptimizer.#isCodecAvailable(inputType) ||
+      isAnimatedImage(source.buffer, inputType);
     const outputType =
       shouldBypass || !params.outputType || inputType === ImageOptimizer.#webp || inputType === ImageOptimizer.#avif
         ? inputType
@@ -240,7 +250,7 @@ export class ImageOptimizer {
     let cacheable = true;
     if (!shouldBypass) {
       try {
-        buffer = await ImageOptimizer.#optimizeWithSharp(source.buffer, {
+        buffer = await ImageOptimizer.#optimize(source.buffer, {
           width: params.width,
           quality: params.quality,
           contentType: outputType,
@@ -281,24 +291,17 @@ export class ImageOptimizer {
     return new Response(ImageOptimizer.#toArrayBuffer(image.buffer), { headers });
   }
 
-  static async #optimizeWithSharp(
+  static async #optimize(
     buffer: Buffer,
     options: { width: number; quality: number; contentType: string },
   ): Promise<Buffer> {
-    const sharp = await loadSharp();
-    if (sharp.concurrency() > 1) sharp.concurrency(Math.max(Math.floor(sharp.concurrency() / 2), 1));
-    const transformer = sharp(buffer, {
-      limitInputPixels: 268_402_689,
-      sequentialRead: true,
-    }).resize(options.width, undefined, { withoutEnlargement: true });
-
-    if (options.contentType === ImageOptimizer.#avif)
-      return await transformer.avif({ quality: options.quality }).toBuffer();
-    if (options.contentType === ImageOptimizer.#webp)
-      return await transformer.webp({ quality: options.quality }).toBuffer();
-    if (options.contentType === ImageOptimizer.#png)
-      return await transformer.png({ quality: options.quality }).toBuffer();
-    return await transformer.jpeg({ quality: options.quality }).toBuffer();
+    const image = new Bun.Image(buffer).resize(options.width, undefined, { withoutEnlargement: true });
+
+    if (options.contentType === ImageOptimizer.#avif) return await image.avif({ quality: options.quality }).toBuffer();
+    if (options.contentType === ImageOptimizer.#webp) return await image.webp({ quality: options.quality }).toBuffer();
+    
+    if (options.contentType === ImageOptimizer.#png) return await image.png().toBuffer();
+    return await image.jpeg({ quality: options.quality }).toBuffer();
   }
 
   static #getPreferredOutputType(accept: string, formats: AkanImageFormat[]): AkanImageFormat | "" {
@@ -375,22 +378,6 @@ export class ImageOptimizer {
     return Buffer.concat(chunks);
   }
 
-  static async #isAnimated(buffer: Buffer, contentType: string): Promise<boolean> {
-    if (
-      contentType !== ImageOptimizer.#gif &&
-      contentType !== ImageOptimizer.#webp &&
-      contentType !== ImageOptimizer.#png
-    )
-      return false;
-    try {
-      const sharp = await loadSharp();
-      const metadata = await sharp(buffer, { animated: true }).metadata();
-      return Boolean(metadata.pages && metadata.pages > 1);
-    } catch {
-      return false;
-    }
-  }
-
   static #detectContentType(buffer: Buffer): string | null {
     if (buffer.length < 12) return null;
     if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) return ImageOptimizer.#jpeg;

package/server/index.ts

@@ -9,8 +9,7 @@ export * from "./devtools";
 export type { ChangeBatch, ChangeKind } from "./hmr/changeBatch";
 export * from "./processMetricsCollector";
 export * from "./proxy";
-export * from "./routeElementComposer";
-export * from "./routeTreeBuilder";
+
 export * from "./sitemap";
 export type { SsrManifest, SsrManifestEntry } from "./ssrTypes";
 export * from "./types";

package/server/mcp/McpAuth.ts

@@ -0,0 +1,177 @@
+import type { HttpRoutes } from "../types";
+
+export interface McpAuthOption {
+  /** Where a client may obtain a token, published in the metadata document for it to discover. */
+  authorizationServers?: string[];
+  /** Scopes every call must carry. Declaring any turns `insufficient_scope` enforcement on. */
+  scopes?: string[];
+  /** Overrides the resource identifier when the public URL differs from what the request reports. */
+  resource?: string;
+}
+
+export interface McpAuthProps extends McpAuthOption {
+  /** Path the MCP endpoint is mounted at. Its absolute URL is this server's OAuth resource identifier. */
+  path: string;
+}
+
+interface McpAuthFailure {
+  status: 401 | 403;
+  error: "invalid_token" | "insufficient_scope";
+  description: string;
+}
+
+/**
+ * The OAuth 2.1 protected-resource half of the MCP authorization spec: the RFC 9728 metadata document, the
+ * `WWW-Authenticate` challenge that points at it, and the token checks that can be made without an issuer.
+ *
+ * The authorization server itself is a separate project. What lives here is what a resource server owes a
+ * client regardless of who mints the tokens, so wiring one up later needs no change on this side.
+ */
+export class McpAuth {
+  static readonly wellKnownPath = "/.well-known/oauth-protected-resource";
+
+  readonly #props: McpAuthProps;
+
+  constructor(props: McpAuthProps) {
+    this.#props = props;
+  }
+
+  /**
+   * Both spellings of the metadata path. RFC 9728 inserts the resource's path into the well-known URL, and MCP
+   * clients try that form first and the bare one second; serving only one leaves half the clients at a 404.
+   */
+  createRoutes(): HttpRoutes {
+    const handler = { GET: (req: Request) => this.#metadata(req) };
+    return {
+      [McpAuth.wellKnownPath]: handler,
+      [`${McpAuth.wellKnownPath}${this.#props.path}`]: handler,
+    };
+  }
+
+  unauthorized(req: Request, failure?: McpAuthFailure) {
+    const { status, error, description } = failure ?? {
+      status: 401 as const,
+      error: "invalid_token" as const,
+      description: "Authentication is required to use this MCP server.",
+    };
+    return Response.json(
+      { error, error_description: description },
+      { status, headers: { "WWW-Authenticate": this.#challenge(req, error, description) } },
+    );
+  }
+
+  /**
+   * Refuses a bearer token that is already provably unusable, before the signal pipeline sees it.
+   *
+   * The claims are read **without verifying the signature**, which is sound only because every branch below can
+   * deny and none can grant: a forged token still has to pass the app's own middleware afterwards, so the worst
+   * a crafted payload achieves is refusing itself. What this buys is the failure mode it removes — an expired or
+   * foreign token otherwise degrades to an anonymous caller, and the agent is told a tool does not exist rather
+   * than that it needs to authenticate.
+   */
+  reject(req: Request): Response | null {
+    const claims = McpAuth.#claims(req);
+    if (!claims) return null;
+    const failure = this.#failureOf(claims, req);
+    return failure ? this.unauthorized(req, failure) : null;
+  }
+
+  #failureOf(claims: Record<string, unknown>, req: Request): McpAuthFailure | null {
+    const { exp, aud } = claims;
+    if (typeof exp === "number" && exp * 1000 <= Date.now())
+      return { status: 401, error: "invalid_token", description: "The access token has expired." };
+    const audience = (Array.isArray(aud) ? aud : typeof aud === "string" ? [aud] : []).filter(
+      (value): value is string => typeof value === "string",
+    );
+
+    if (this.#props.authorizationServers?.length && !audience.length)
+      return { status: 401, error: "invalid_token", description: "The access token names no resource." };
+    if (audience.length && !audience.includes(this.#resource(req)))
+      return { status: 401, error: "invalid_token", description: "The access token was issued for another resource." };
+    const missing = this.#missingScopes(claims);
+    
+    if (missing.length)
+      return { status: 403, error: "insufficient_scope", description: `Missing required scope: ${missing.join(" ")}.` };
+    return null;
+  }
+
+  /**
+   * Enforced only when `scopes` is configured, because this server's own tokens carry no scope claim at all —
+   * declaring one is how a deployment says its issuer mints them.
+   */
+  #missingScopes(claims: Record<string, unknown>) {
+    const required = this.#props.scopes ?? [];
+    if (!required.length) return [];
+    const raw = claims.scope ?? claims.scp;
+    const granted = new Set(Array.isArray(raw) ? raw.map(String) : String(raw ?? "").split(/\s+/));
+    return required.filter((scope) => !granted.has(scope));
+  }
+
+  #metadata(req: Request) {
+    const { authorizationServers, scopes } = this.#props;
+    return Response.json(
+      {
+        resource: this.#resource(req),
+        ...(authorizationServers?.length ? { authorization_servers: authorizationServers } : {}),
+        bearer_methods_supported: ["header"],
+        ...(scopes?.length ? { scopes_supported: scopes } : {}),
+      },
+      {
+        
+        headers: { "access-control-allow-origin": "*", "cache-control": "public, max-age=3600" },
+      },
+    );
+  }
+
+  #challenge(req: Request, error: string, description: string) {
+    const scopes = this.#props.scopes ?? [];
+    return [
+      "Bearer",
+      [
+        `resource_metadata="${new URL(McpAuth.wellKnownPath + this.#props.path, McpAuth.origin(req)).href}"`,
+        `error="${error}"`,
+        `error_description="${description}"`,
+        ...(scopes.length ? [`scope="${scopes.join(" ")}"`] : []),
+      ].join(", "),
+    ].join(" ");
+  }
+
+  #resource(req: Request) {
+    return this.#props.resource ?? new URL(this.#props.path, McpAuth.origin(req)).href;
+  }
+
+  /**
+   * The public origin, not the one the request arrived on. Behind a proxy `req.url` names the internal host the
+   * proxy dialed, and publishing that as the resource identifier is not cosmetic: an authorization server issues
+   * `aud` for the URL the *client* used, so every correctly-issued token would then fail the audience check.
+   *
+   * `McpRouter` compares an `Origin` header against this too — the same proxy that makes `req.url` wrong for the
+   * metadata document makes it wrong for a same-origin check, and there the cost is a flat 403.
+   *
+   * `x-forwarded-host` is a request header, so this is exactly as trustworthy as the edge that overwrites it, and
+   * a deployment whose edge merely appends leaves both the same-origin comparison and the audience a token is
+   * checked against to the caller. A browser cannot reach it — a custom header is not on a preflight, and the
+   * `OPTIONS` is judged on the real host — but a direct caller can. `AKAN_MCP_RESOURCE` pins the identifier for a
+   * deployment that cannot make the guarantee.
+   */
+  static origin(req: Request) {
+    const url = new URL(req.url);
+    const forwarded = (header: string) => req.headers.get(header)?.split(",")[0]?.trim();
+    const host = forwarded("x-forwarded-host") ?? req.headers.get("host") ?? url.host;
+    return `${forwarded("x-forwarded-proto") ?? url.protocol.replace(":", "")}://${host}`;
+  }
+
+  static #claims(req: Request): Record<string, unknown> | null {
+    const [scheme, token] = (req.headers.get("authorization") ?? "").split(" ");
+    if (scheme !== "Bearer" || !token) return null;
+    const segments = token.split(".");
+
+    if (segments.length !== 3) return null;
+    try {
+      const claims: unknown = JSON.parse(Buffer.from(segments[1], "base64url").toString("utf8"));
+      return claims && typeof claims === "object" ? (claims as Record<string, unknown>) : null;
+    } catch {
+      return null;
+    }
+  }
+}