akanjs 3.0.0-beta.9 → 3.0.1

package/server/memoryLimit.ts

@@ -1,13 +1,5 @@
 import fs from "node:fs";
 
-/**
- * Where a process's RSS ceiling comes from, shared by every host that recycles a child to bound it.
- *
- * A budget can be declared explicitly, discovered from the container, or absent altogether, so each
- * host asks for a fraction of whatever limit it can find and supplies its own fallback for the last
- * case. Kept as its own module rather than living on a host class because both `akanjs/server` and
- * the dev host in `@akanjs/devkit` need it, and neither should import the other's stack to get it.
- */
 export class MemoryLimit {
   static readonly #cgroupLimitFiles = ["/sys/fs/cgroup/memory.max", "/sys/fs/cgroup/memory/memory.limit_in_bytes"];
   /** Host-level cgroup files report effectively-unlimited sentinels; anything this large means "no limit". */
@@ -47,11 +39,7 @@ export class MemoryLimit {
     return null;
   }
 
-  /**
-   * Resolves a ceiling from, in order: an explicit MiB env, an explicit byte env, a fraction of the
-   * container's memory limit, and finally the caller's fallback (`null` to leave the process
-   * unbounded).
-   */
+  /** Order: MiB env, byte env, `limitFraction` of the container limit, then `fallbackBytes` (`null` = unbounded). */
   static resolveMaxRssBytes({
     megabytesEnv,
     bytesEnv,

package/server/nativeFile.ts

@@ -0,0 +1,107 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { lstatSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { getEnv } from "akanjs/base";
+import type { AkanIpcMessage } from "akanjs/service";
+
+export type NativeFileMode = "read" | "write" | "folder";
+
+type Resolved = Extract<AkanIpcMessage, { type: "file.resolved" }>;
+
+export class NativeFile {
+  static timeoutMs = 5_000;
+  static operationMode: () => string = () => getEnv().operationMode;
+  static readonly #waiting = new Map<string, (answer: Resolved) => void>();
+  static #listener: ((message: unknown) => void) | null = null;
+
+  /** The path behind `grant`, which the user must have given for `mode`. */
+  static async resolve(grant: string, mode: NativeFileMode): Promise<string> {
+    const found = grant.startsWith("dev:") ? NativeFile.#devGrant(grant) : await NativeFile.#ask(grant);
+    if (found.mode !== mode) throw new Error(`The file was granted to ${found.mode}, not to ${mode}.`);
+    return found.path;
+  }
+
+  /** A path inside a folder grant; one that climbs out of the folder is refused. */
+  static async resolveIn(grant: string, relative: string): Promise<string> {
+    const folder = await NativeFile.resolve(grant, "folder");
+    const target = path.resolve(folder, relative);
+    NativeFile.#assertInside(folder, target, relative);
+
+    NativeFile.#assertInside(NativeFile.#realPath(folder), NativeFile.#realPath(target), relative);
+    return target;
+  }
+
+  static #assertInside(folder: string, target: string, relative: string) {
+    const inside = path.relative(folder, target);
+    if (inside === ".." || inside.startsWith(`..${path.sep}`) || path.isAbsolute(inside))
+      throw new Error(`${relative} is outside the folder the user granted.`);
+  }
+
+  static #realPath(target: string): string {
+    const rest: string[] = [];
+    for (let current = target; ; current = path.dirname(current)) {
+      try {
+        return path.join(realpathSync.native(current), ...rest);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT" || path.dirname(current) === current) throw error;
+        if (NativeFile.#exists(current)) throw new Error(`${target} is a link to nothing.`);
+        rest.unshift(path.basename(current));
+      }
+    }
+  }
+
+  static #exists(entry: string) {
+    try {
+      lstatSync(entry);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  static #ask(grant: string): Promise<{ path: string; mode: NativeFileMode }> {
+    const send = process.send?.bind(process);
+    if (!send) return Promise.reject(new Error("A file grant resolves only inside the desktop app that gave it."));
+    NativeFile.#listen();
+    const id = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        NativeFile.#waiting.delete(id);
+        reject(new Error("The desktop app did not answer for the file grant."));
+      }, NativeFile.timeoutMs);
+      NativeFile.#waiting.set(id, (answer) => {
+        clearTimeout(timer);
+        NativeFile.#waiting.delete(id);
+        if (answer.path && answer.mode) resolve({ path: answer.path, mode: answer.mode });
+        else reject(new Error(answer.error ?? "The desktop app refused the file grant."));
+      });
+      send({ type: "file.resolve", id, grant } satisfies AkanIpcMessage);
+    });
+  }
+
+  static #listen() {
+    if (NativeFile.#listener) return;
+    NativeFile.#listener = (message) => {
+      const answer = message as AkanIpcMessage | null;
+      if (answer?.type === "file.resolved") NativeFile.#waiting.get(answer.id)?.(answer);
+    };
+    process.on("message", NativeFile.#listener);
+  }
+
+  static #devGrant(grant: string): { path: string; mode: NativeFileMode } {
+    
+    if (NativeFile.operationMode() !== "local")
+      throw new Error("A dev build's file grant resolves only on akan start, in operationMode local.");
+    const [, mode, encoded = "", signature = ""] = grant.split(":");
+    if (mode !== "read" && mode !== "write" && mode !== "folder") throw new Error("The file grant is malformed.");
+    const key = readFileSync(
+      process.env.AKAN_NATIVE_DEV_GRANT_KEY || path.join(homedir(), ".akan", "native", "dev-file-grant.key"),
+    );
+    const expected = createHmac("sha256", key).update(`${mode}:${encoded}`).digest();
+    const given = Buffer.from(signature, "base64url");
+    if (given.length !== expected.length || !timingSafeEqual(given, expected))
+      throw new Error("The file grant was not signed by this computer's dev build.");
+    return { path: Buffer.from(encoded, "base64url").toString(), mode };
+  }
+}

package/server/oauth/OAuthAuthorize.ts

@@ -4,7 +4,7 @@ import { OAuthRedirect } from "./OAuthRedirect";
 import type { OAuthAuthorizeErrorCode, OAuthAuthorizeParams, OAuthClientRecord } from "./oauthTypes";
 
 export interface OAuthAuthorizeContext {
-  /** The client the request's `client_id` resolved to, however it was registered; `null` when it resolved to nothing. */
+  /** `null` when the request's `client_id` resolved to no client. */
   client: OAuthClientRecord | null;
   issuer: string;
   /** The one resource this server issues tokens for — the MCP endpoint's canonical URL. */
@@ -14,11 +14,7 @@ export interface OAuthAuthorizeContext {
 export type OAuthAuthorizeResult = { ok: true; params: OAuthAuthorizeParams } | { ok: false; response: Response };
 
 export class OAuthAuthorize {
-  /**
-   * Validates in the order RFC 6749 §4.1.2.1 prescribes: the client and its redirect URI first, answered with a page
-   * because nothing may be redirected to an unverified destination; everything after that is answered through the
-   * redirect URI the client registered, with `state` and `iss` so the client can match and trust the answer.
-   */
+
   static parse(url: URL, { client, issuer, resource }: OAuthAuthorizeContext): OAuthAuthorizeResult {
     const param = (name: string) => url.searchParams.get(name) ?? undefined;
     const clientId = param("client_id");
@@ -48,7 +44,7 @@ export class OAuthAuthorize {
       return fail("unauthorized_client", "This client is not registered for the authorization_code grant.");
     const codeChallenge = param("code_challenge");
     const method = param("code_challenge_method");
-
+    
     if (method !== undefined && method !== OAuthPkce.method)
       return fail("invalid_request", `code_challenge_method "${method}" is not supported; use ${OAuthPkce.method}.`);
     if (!OAuthPkce.isChallenge(codeChallenge)) return fail("invalid_request", "A PKCE code_challenge is required.");

package/server/oauth/OAuthClientIdMetadata.ts

@@ -5,7 +5,7 @@ import type { OAuthClientRecord, OAuthRedirectPolicy } from "./oauthTypes";
 
 export interface OAuthClientIdMetadataResult {
   client: OAuthClientRecord;
-  /** How long the document may be reused, from its `Cache-Control`, clamped to something a server can live with. */
+  /** From `Cache-Control` max-age (else `defaultTtlMs`), clamped to `minTtlMs`..`maxTtlMs`. */
   ttlMs: number;
 }
 
@@ -15,18 +15,10 @@ export type OAuthDocumentFetch = (input: string | URL | Request, init?: RequestI
 
 export interface OAuthClientIdMetadataFetchOptions extends OAuthRedirectPolicy {
   fetchImpl?: OAuthDocumentFetch;
-  /**
-   * Resolves the document's host before it is fetched and refuses one whose addresses are not all public. On by
-   * default with the system resolver; `false` trusts the name alone, for a deployment whose egress policy already
-   * closes the private range.
-   */
+  /** SSRF check: every resolved address must be public. Default: system resolver; `false` trusts the name alone. */
   resolve?: OAuthAddressLookup | false;
 }
 
-/**
- * OAuth Client ID Metadata Documents (draft-ietf-oauth-client-id-metadata-document): a client whose `client_id`
- * is an HTTPS URL hosts its own registration there, and the server reads it instead of holding a registry.
- */
 export class OAuthClientIdMetadata {
   static readonly maxBytes = 64 * 1024;
   static readonly timeoutMs = 5_000;
@@ -40,13 +32,6 @@ export class OAuthClientIdMetadata {
     return !!url && url.protocol === "https:" && url.pathname !== "/" && !url.username && !url.password;
   }
 
-  /**
-   * Whether a document URL may be fetched on the client's say-so. The fetch API never shows the address a name
-   * resolved to, so this judges the name: no address literals (a client hosts its document under a name), no
-   * single-label or reserved-suffix names, no explicit port. A public name that resolves into the private range is
-   * `resolvesPublicly`'s to catch; the rebinding window between that lookup and the fetch is the residual the
-   * deployment's egress policy owns — the SSRF section of the draft says as much.
-   */
   static isFetchable(url: URL): boolean {
     const host = url.hostname.toLowerCase();
     if (url.port) return false;
@@ -55,11 +40,6 @@ export class OAuthClientIdMetadata {
     return !/\.(?:localhost|local|internal|lan|home|arpa)$/.test(host);
   }
 
-  /**
-   * Whether every address the name resolves to is public. The resolver is asked separately from the fetch, so a
-   * name that flips between the two (DNS rebinding) is the residual; what this closes is the ordinary case of a
-   * public name parked on a private address, which `isFetchable` cannot see.
-   */
   static async resolvesPublicly(hostname: string, resolve: OAuthAddressLookup = OAuthClientIdMetadata.#lookup) {
     try {
       const addresses = await resolve(hostname);
@@ -96,10 +76,6 @@ export class OAuthClientIdMetadata {
     return client ? { client, ttlMs: OAuthClientIdMetadata.#ttl(res.headers.get("cache-control")) } : null;
   }
 
-  /**
-   * §4: `client_id` MUST equal the URL the document was fetched from, `client_name` and `redirect_uris` MUST be
-   * present. Only public clients are accepted — `private_key_jwt` needs a JWKS the token endpoint does not read.
-   */
   static validate(clientId: string, json: unknown, policy: OAuthRedirectPolicy = {}): OAuthClientRecord | null {
     if (!json || typeof json !== "object" || Array.isArray(json)) return null;
     const doc = json as Record<string, unknown>;
@@ -122,7 +98,6 @@ export class OAuthClientIdMetadata {
     };
   }
 
-  /** The system resolver, under the same deadline as the fetch: a resolver that hangs is a fetch that hangs. */
   static readonly #lookup: OAuthAddressLookup = async (hostname) =>
     await Promise.race([
       lookup(hostname, { all: true }),

package/server/oauth/OAuthErrors.ts

@@ -15,10 +15,6 @@ export class OAuthErrors {
   
   static readonly noStore = { "cache-control": "no-store", pragma: "no-cache" } as const;
 
-  /**
-   * RFC 6749 §5.2. `invalid_client` is 401, and when the client authenticated with the `Authorization` header the
-   * answer names that scheme back — the one case the RFC requires a `WWW-Authenticate` on a token response.
-   */
   static token(
     error: OAuthTokenErrorCode,
     description: string,
@@ -37,11 +33,6 @@ export class OAuthErrors {
     return Response.json({ error, error_description: description }, { status: 400, headers: OAuthErrors.noStore });
   }
 
-  /**
-   * An authorization error that travels back through the redirect URI (RFC 6749 §4.1.2.1) — legal only once that
-   * URI has been matched against the client's registration, which is why `OAuthAuthorize` answers the client and
-   * redirect checks with a page instead.
-   */
   static redirect(
     redirectUri: string,
     { error, description, state, iss }: OAuthRedirectParams & { error: OAuthAuthorizeErrorCode; description?: string },
@@ -53,10 +44,6 @@ export class OAuthErrors {
     return OAuthErrors.#located(redirectUri, { code, state, iss });
   }
 
-  /**
-   * The answer when nothing may be redirected to: an unknown client or an unregistered redirect URI, where the
-   * destination the request named is the one thing that cannot be trusted with the user (RFC 6749 §4.1.2.1).
-   */
   static page(status: number, title: string, detail: string) {
     const body = `<!doctype html><meta charset="utf-8"><title>${OAuthErrors.#escape(title)}</title><main style="font:16px system-ui;max-width:32rem;margin:4rem auto"><h1>${OAuthErrors.#escape(title)}</h1><p>${OAuthErrors.#escape(detail)}</p></main>`;
     return new Response(body, {

package/server/oauth/OAuthMetadata.ts

@@ -5,19 +5,13 @@ export interface OAuthMetadataProps {
   registrationEndpoint?: string;
   revocationEndpoint?: string;
   scopesSupported?: string[];
-  /** Whether a `client_id` that is an HTTPS URL is read as a metadata document. Advertised as true unless a deployment turned it off. */
+  /** Whether an HTTPS `client_id` is read as a metadata document; defaults to `true`. */
   clientIdMetadataDocumentSupported?: boolean;
 }
 
 export class OAuthMetadata {
   static readonly wellKnownSuffix = "/.well-known/oauth-authorization-server";
 
-  /**
-   * The RFC 8414 document. Three fixed fields are load-bearing for MCP clients: `code_challenge_methods_supported`
-   * (a client MUST refuse to proceed without it), `client_id_metadata_document_supported` (the registration path the
-   * spec prefers), and `authorization_response_iss_parameter_supported` (which is what obliges the client to check
-   * `iss` on the way back).
-   */
   static document({
     issuer,
     authorizationEndpoint,

package/server/oauth/OAuthPkce.ts

@@ -1,9 +1,7 @@
 import { createHash, timingSafeEqual } from "node:crypto";
 
-/** RFC 7636 with `S256` only: OAuth 2.1 drops `plain`, and an MCP client refuses a server whose metadata offers nothing else. */
 export class OAuthPkce {
   static readonly method = "S256";
-  
   static readonly #verifier = /^[A-Za-z0-9\-._~]{43,128}$/;
   
   static readonly #challenge = /^[A-Za-z0-9\-_]{43}$/;

package/server/oauth/OAuthRedirect.ts

@@ -18,11 +18,6 @@ export class OAuthRedirect {
     return url.protocol === "http:" && OAuthRedirect.loopbackHosts.has(url.hostname);
   }
 
-  /**
-   * What may be registered: HTTPS, loopback HTTP, or a private-use scheme the deployment named. The MCP spec allows
-   * only the first two; the third exists because Cursor's desktop client registers `cursor://…/oauth/callback`, and
-   * a server that refuses it cannot be used from Cursor at all.
-   */
   static isRegistrable(uri: string, { allowedSchemes = [] }: OAuthRedirectPolicy = {}): boolean {
     const url = OAuthRedirect.parse(uri);
     if (!url) return false;
@@ -30,10 +25,6 @@ export class OAuthRedirect {
     return allowedSchemes.includes(url.protocol.slice(0, -1));
   }
 
-  /**
-   * Exact match against what was registered, except that a loopback redirect may vary its port: a native client
-   * binds whichever port is free at the time (RFC 8252 §7.3), and Claude Code picks one at random per session.
-   */
   static matches(registered: readonly string[], presented: string): boolean {
     if (registered.includes(presented)) return true;
     const url = OAuthRedirect.parse(presented);

package/server/oauth/OAuthRegistration.ts

@@ -4,7 +4,6 @@ import type { OAuthClientAuthMethod, OAuthClientMetadata, OAuthClientRecord, OAu
 
 export type OAuthRegistrationResult = { ok: true; client: OAuthClientMetadata } | { ok: false; response: Response };
 
-/** RFC 7591 Dynamic Client Registration — the request's validation and the response's shape; the identifier is the caller's. */
 export class OAuthRegistration {
   static readonly authMethods: readonly OAuthClientAuthMethod[] = ["none", "client_secret_post", "client_secret_basic"];
   static readonly grantTypes: readonly string[] = ["authorization_code", "refresh_token"];
@@ -70,7 +69,6 @@ export class OAuthRegistration {
     return Array.isArray(value) && value.every((entry) => typeof entry === "string");
   }
 
-  /** The list as sent when every entry is allowed, the default when absent, `null` when something else was named. */
   static #subset(value: unknown, allowed: readonly string[], fallback: string[]): string[] | null {
     if (value === undefined) return fallback;
     if (!OAuthRegistration.#strings(value) || !value.length) return null;

package/server/oauth/OAuthRevocation.ts

@@ -6,7 +6,7 @@ export type OAuthTokenTypeHint = "access_token" | "refresh_token";
 
 export interface OAuthRevocationParams {
   token: string;
-  /** The client's guess at what it is handing over; a server may ignore it, and an unknown hint reads as none. */
+  /** Advisory only; an unknown hint reads as none. */
   tokenTypeHint?: OAuthTokenTypeHint;
   client: OAuthClientCredential;
 }
@@ -15,14 +15,9 @@ export type OAuthRevocationParseResult =
   | { ok: true; params: OAuthRevocationParams }
   | { ok: false; response: Response };
 
-/**
- * RFC 7009 Token Revocation — the request's shape and the two answers it allows. What a token *is* and whose it
- * is are the issuer's to decide, so the parse hands back the credential and the token and nothing more.
- */
 export class OAuthRevocation {
   static readonly hints: readonly OAuthTokenTypeHint[] = ["access_token", "refresh_token"];
 
-  /** §2.1: form-encoded like the token endpoint, with the same client authentication and `token` required. */
   static async parse(req: Request): Promise<OAuthRevocationParseResult> {
     const type = req.headers.get("content-type")?.toLowerCase() ?? "";
     if (!type.startsWith("application/x-www-form-urlencoded"))
@@ -45,11 +40,6 @@ export class OAuthRevocation {
     };
   }
 
-  /**
-   * §2.2: a revoked token and a token the server never knew get the same empty 200, so the endpoint cannot be used
-   * to test whether a token exists. The only refusals are a malformed request and a client that failed to
-   * authenticate, both answered as the token endpoint would.
-   */
   static success() {
     return new Response(null, { status: 200, headers: OAuthErrors.noStore });
   }

package/server/oauth/OAuthToken.ts

@@ -12,10 +12,7 @@ export interface OAuthTokenSuccess {
 }
 
 export class OAuthToken {
-  /**
-   * RFC 6749 §4.1.3 and §6: the token endpoint speaks form encoding only, and a client authenticates through the
-   * `Authorization` header or the body, never both — two credentials on one request is a request nobody can audit.
-   */
+  
   static async parse(req: Request): Promise<OAuthTokenParseResult> {
     const type = req.headers.get("content-type")?.toLowerCase() ?? "";
     if (!type.startsWith("application/x-www-form-urlencoded"))
@@ -51,11 +48,6 @@ export class OAuthToken {
     return OAuthToken.#fail("unsupported_grant_type", "Only authorization_code and refresh_token are supported.");
   }
 
-  /**
-   * Whether the credential presented is this client's. A public client has none to present, and a secret it sends
-   * anyway is ignored rather than refused — OAuth 2.1 §2.3 lets a public client keep naming itself. A confidential
-   * client must present its secret, compared as hashes in constant time.
-   */
   static authenticate(
     client: OAuthClientRecord,
     credential: OAuthClientCredential,
@@ -82,14 +74,11 @@ export class OAuthToken {
     );
   }
 
-  /**
-   * `null` when both channels carried a credential. RFC 6749 §2.3.1 form-encodes the two halves of the Basic pair.
-   * Shared with the revocation endpoint, which RFC 7009 §2.1 authenticates the same way.
-   */
+  /** `null` when both channels carried a credential. Basic halves are form-encoded (RFC 6749 §2.3.1). */
   static credentialOf(req: Request, form: URLSearchParams): OAuthClientCredential | null {
     const header = req.headers.get("authorization");
     const bodySecret = form.get("client_secret") ?? undefined;
-    if (header?.startsWith("Basic ")) {
+    if (header && /^Basic /i.test(header)) {
       if (bodySecret !== undefined) return null;
       const decoded = Buffer.from(header.slice("Basic ".length).trim(), "base64").toString("utf8");
       const separator = decoded.indexOf(":");

package/server/oauth/oauthTypes.ts

@@ -1,6 +1,6 @@
 export type OAuthClientAuthMethod = "none" | "client_secret_post" | "client_secret_basic";
 
-/** How a client came to be known: declared in the app's option, registered over RFC 7591, or read off its `client_id` URL. */
+/** Declared in the app's option, registered over RFC 7591, or read off its `client_id` URL. */
 export type OAuthClientSource = "static" | "dynamic" | "metadataDocument";
 
 export interface OAuthClientRecord {
@@ -13,7 +13,6 @@ export interface OAuthClientRecord {
   source: OAuthClientSource;
 }
 
-/** The metadata a registration request carries, before the server assigns an identifier to it. */
 export type OAuthClientMetadata = Pick<
   OAuthClientRecord,
   "clientName" | "redirectUris" | "grantTypes" | "tokenEndpointAuthMethod"