akanjs 3.0.0-beta.26 → 3.0.0-beta.28

package/index.ts

@@ -1,3 +1,4 @@
+import type { AkanNativeConfig } from "./vendor/@akanjs/native/packages/cli/src/config.ts";
 import type { AkanI18nConfig } from "akanjs/common";
 import type { AkanImageConfig } from "akanjs/server";
 
@@ -27,6 +28,41 @@ export interface LibDockerConfig {
   postRuns: DockerRun[];
 }
 
+/** `${process.platform}-${process.arch}` of the computer a desktop app is built on, which is the one it runs on. */
+export const binPlatforms = [
+  "darwin-arm64",
+  "darwin-x64",
+  "linux-arm64",
+  "linux-x64",
+  "win32-arm64",
+  "win32-x64",
+] as const;
+export type BinPlatform = (typeof binPlatforms)[number];
+
+/** Downloaded when the desktop app is built; the file must hash to `sha256`, so plain http is as safe as https. */
+export interface AkanBinUrlSource {
+  url: string;
+  sha256: string;
+  /** The executable inside the archive `url` names (.zip, .tar.gz, .tgz, .tar.xz, .tar.bz2, .tar). */
+  file?: string;
+}
+
+/** A file on the building computer, relative to the `akan.config.ts` that declares it. */
+export interface AkanBinPathSource {
+  path: string;
+  /** The executable inside the archive `path` names. */
+  file?: string;
+}
+
+export type AkanBinSource = AkanBinUrlSource | AkanBinPathSource;
+
+/**
+ * Executables a desktop app carries, by the name its code spawns and then by platform. Their folder comes first on
+ * the app's PATH, so the carried server's `spawn("ffmpeg")` runs the carried file; a native plugin finds it in
+ * `ctx.binDir`.
+ */
+export type AkanBinConfig = Record<string, { [platform in BinPlatform]?: AkanBinSource }>;
+
 export interface AkanRouteDomains {
   main?: string[];
   develop?: string[];
@@ -67,8 +103,10 @@ export type MobileEnv = "local" | "debug" | "develop" | "main";
 export type MobilePermission = "camera" | "contacts" | "location" | "push" | "speech";
 
 export interface AkanMobileTargetAssets {
-  icon?: string;
-  splash?: string;
+  /** A square PNG, relative to the app folder, or it with the color behind its transparent areas. */
+  icon?: string | { image: string; backgroundColor?: string };
+  /** A PNG shown centered at launch, or the launch screen's color, image and when it hides. */
+  splash?: string | NonNullable<AkanNativeConfig["splash"]>;
 }
 
 export interface AkanMobileTargetDeepLinks {
@@ -106,15 +144,72 @@ export interface AkanMobileNativeConfig {
     activity?: string[];
     /** The Firebase project's google-services.json, relative to the app folder, for FCM push on Android. */
     googleServices?: string;
+    /** Media plays with sound without a tap first, as it does on iOS and the desktop: a signage screen. */
+    autoplay?: boolean;
+  };
+  /** Android's notification channel, status bar icon (relative to the app folder) and accent color. */
+  push?: AkanNativeConfig["push"];
+  /** The app's part of the iOS privacy manifest (PrivacyInfo.xcprivacy), which an App Store upload requires. */
+  privacy?: AkanNativeConfig["privacy"];
+  desktop?: {
+    /**
+     * The desktop app carries the app's server (API only, database mode single, on loopback) and its pages call
+     * nothing else. `build-desktop`, `start-desktop` and `publish-update` all read it, and an installed app refuses
+     * a release that carries a server when it has none, or none when it has one.
+     */
+    server?: boolean;
+    /**
+     * `"reload"`: a window whose page's process ends (a crash, a hang) loads it again every time, waiting
+     * longer after each end in a row, and the app relaunches when the webview's browser process ends — for an
+     * app nobody attends. `"errorPage"` (default): one reload, then an error page, and a quit for the browser.
+     */
+    recovery?: "errorPage" | "reload";
+    /** The main window from its first frame: borderless fullscreen, and no taskbar button (Windows, Linux). */
+    window?: { fullscreen?: boolean; skipTaskbar?: boolean };
+    /**
+     * Windows: `"auto"` answers getDisplayMedia() with the first screen at once, no picker or gesture — remote
+     * support on an unattended screen; it covers every media request, so not for an app that asks for a camera.
+     */
+    screenCapture?: "picker" | "auto";
   };
 }
 
+/**
+ * Where an installed app looks for newer releases of itself (the native runtime's updates plugin): the whole app on a
+ * desktop, the web bundle on a phone. `akan publish-update` writes and signs a release with a key on this machine;
+ * `akan pack-update` writes an unsigned phone bundle for whoever holds the key to sign.
+ */
+export interface AkanMobileUpdatesConfig {
+  /**
+   * A static base URL, https in a release build: `<url>/<os>-<arch>/<channel>.json` (desktop) or `<url>/<platform>/…`
+   * (a phone's web bundle).
+   */
+  url: string;
+  /** The update key's public half, the raw 32-byte Ed25519 key in base64 (`akan update-keygen` prints it). */
+  publicKey: string;
+  /**
+   * The manifest the app follows, e.g. a "pilot" target's "pilot". Default: the backend env the app is built for
+   * (`main`, `develop`, `debug`, `local`).
+   */
+  channel?: string;
+  /** How long a newly applied release has to call notifyReady() before it is rolled back, ms. Default 10000. */
+  readyTimeout?: number;
+}
+
+/**
+ * One bundle id, or one per platform, for an app whose store listings already carry different ids. A platform without
+ * its own takes `default`.
+ */
+export type AkanMobileAppId =
+  | string
+  | { default?: string; ios?: string; android?: string; macos?: string; windows?: string; linux?: string };
+
 export interface AkanMobileTargetConfig {
   name: string;
   basePath?: string;
   indexPath?: string;
   appName: string;
-  appId: string;
+  appId: AkanMobileAppId;
   /** Executables, archives and the Swift module; letters, digits, `.`, `_` and `-`. Default: the app's folder name. */
   fileName?: string;
   version: string;
@@ -124,16 +219,19 @@ export interface AkanMobileTargetConfig {
   deepLinks?: AkanMobileTargetDeepLinks;
   files?: AkanMobileTargetFiles;
   native?: AkanMobileNativeConfig;
+  /** Over mobile.updates, field by field: a pilot target names its own channel. */
+  updates?: Partial<AkanMobileUpdatesConfig>;
 }
 
 export interface AkanMobileConfig {
   appName: string;
-  appId: string;
+  appId: AkanMobileAppId;
   fileName?: string;
   version: string;
   buildNum: number;
   files?: AkanMobileTargetFiles;
   native?: AkanMobileNativeConfig;
+  updates?: AkanMobileUpdatesConfig;
   targets: Record<string, AkanMobileTargetConfig>;
 }
 
@@ -228,6 +326,10 @@ export interface AppConfigResult {
    */
   syncPageLibs?: string[] | boolean;
   externalLibs: string[];
+  /** Dependencies whose install scripts `bun install --production` runs, in the image and in a desktop app's server. */
+  trustedDependencies: string[];
+  /** Every desktop build, run and dev session carries these, server or not; the image installs through `docker`. */
+  bin: AkanBinConfig;
   barrelImports: string[];
   optimizeImports: string[];
   images: AkanImageConfig;
@@ -240,6 +342,9 @@ export interface AppConfigResult {
 
 export interface LibConfigResult {
   externalLibs: string[];
+  trustedDependencies: string[];
+  /** Carried by the desktop app of every app that depends on this lib; an app's own entry of the same name wins. */
+  bin: AkanBinConfig;
   /** Image steps every app that mounts this lib inherits, unless that app declares a whole Dockerfile. */
   docker: LibDockerConfig;
   /** Which of this lib's own public fonts every app that mounts it must keep. */
@@ -260,12 +365,16 @@ export interface LibConfigContext {
   readonly type: "lib";
 }
 
-export type AppConfigInput = Omit<DeepPartial<AppConfigResult>, "docker" | "web"> & {
+export type AppConfigInput = Omit<DeepPartial<AppConfigResult>, "docker" | "web" | "bin"> & {
   docker?: DockerOption;
   web?: AkanWebOption;
+  bin?: AkanBinConfig;
+  plugins?: AkanPlugin[];
+};
+export type LibConfigInput = Omit<DeepPartial<LibConfigResult>, "bin"> & {
+  bin?: AkanBinConfig;
   plugins?: AkanPlugin[];
 };
-export type LibConfigInput = DeepPartial<LibConfigResult> & { plugins?: AkanPlugin[] };
 export interface SubspaceDeclaration {
   /** Short name used on the command line and as the git remote suffix. */
   name: string;

package/native/desktop.ts

@@ -0,0 +1,5 @@
+
+
+export { AkanNativeError, mimeFor } from "../vendor/@akanjs/native/packages/core/src/index.ts";
+export type { DesktopContext, DesktopPlugin, NativeEvent } from "../vendor/@akanjs/native/packages/desktop/src/plugin.ts";
+export { createPageVeto, defineDesktopPlugin, externalOpenAllowed } from "../vendor/@akanjs/native/packages/desktop/src/plugin.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-beta.26",
+  "version": "3.0.0-beta.28",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -95,6 +95,16 @@
       "import": "./client/native.ts",
       "default": "./client/native.ts"
     },
+    "./client/native/*": {
+      "types": "./types/client/native/*.d.ts",
+      "import": "./client/native/*.ts",
+      "default": "./client/native/*.ts"
+    },
+    "./native/desktop": {
+      "types": "./types/native/desktop.d.ts",
+      "import": "./native/desktop.ts",
+      "default": "./native/desktop.ts"
+    },
     "./webkit": {
       "types": "./types/webkit/index.d.ts",
       "import": "./webkit/index.ts",

package/server/akanApp.ts

@@ -4,8 +4,9 @@ import path from "node:path";
 import { Logger } from "akanjs/common";
 import type { AkanChildRole, AkanChildStatus, AkanIpcMessage, AkanMetricsReport, AkanUpstream } from "akanjs/service";
 import { getApiPrefix, getWsPrefix, normalizeRoutePrefix, resetEnvCache } from "../base/baseEnv";
+import { CrossSiteGuard } from "../signal/CrossSiteGuard";
 import { isTraceEnabled } from "../signal/trace";
-import { makeAkanChildProxyHeaders } from "./akanAppHeaders";
+import { AKAN_CHILD_HOST, makeAkanChildProxyHeaders } from "./akanAppHeaders";
 import type { BuilderCsrReq, BuilderCsrRes, BuilderMessage, BuilderReq, BuilderRes } from "./artifact";
 import { compressResponse, encodedFileResponse } from "./contentEncoding";
 import { isPortInUseError } from "./lifecycle/portInUse";
@@ -19,6 +20,8 @@ import { RotatingLogWriter } from "./logging/rotatingLogWriter";
 import { AppInfo } from "./ops/appInfo";
 import type { OpsRoute } from "./ops/opsRoute";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
+import { HostAllowlist } from "./routing/hostAllowlist";
+import { SelfExec } from "./selfExec";
 import { resolveStaticPath } from "./staticPath";
 import { getWebConfigFromEnv } from "./types";
 
@@ -139,6 +142,7 @@ export class AkanApp {
   #logControl: LogControlSocket | null = null;
   #logStream: LogStreamRoute | null = null;
   #ops: OpsRoute | null = null;
+  #hostAllowlist = HostAllowlist.fromEnv();
   static readonly #ansiPattern = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, "g");
   #gatewayMetrics: AkanMetricsReport = {};
   #proxyHopCount = 0;
@@ -149,6 +153,7 @@ export class AkanApp {
   #stopping = false;
 
   constructor(serverPathOrOptions: string | AkanAppOptions = "./server", options: AkanAppOptions = {}) {
+    SelfExec.adopt();
     const resolvedOptions = typeof serverPathOrOptions === "string" ? options : serverPathOrOptions;
     const serverPath = typeof serverPathOrOptions === "string" ? serverPathOrOptions : "./server";
     this.#serverPath = AkanApp.#resolveServerPath(resolvedOptions.serverPath ?? serverPath);
@@ -235,6 +240,10 @@ export class AkanApp {
       process.exit(await OpsCommand.run(process.argv.slice(3)));
     }
     if (this.#solo) return await this.#startSolo();
+    if (SelfExec.carried)
+      throw new Error(
+        "A desktop app's server runs in one process, and this main.ts asks for replicas (replica, solo: false or AKAN_SOLO=false), which would start with the `bun` on the user's PATH. Leave them out of the app the desktop build carries.",
+      );
     Logger.role = "gateway";
     await this.#prepareRuntimeDir();
     await this.#startLogHub();
@@ -579,6 +588,7 @@ export class AkanApp {
     this.#server = Bun.serve({
       idleTimeout: 0,
       port: this.#port,
+      hostname: process.env.AKAN_LISTEN_HOST || undefined,
       fetch: (req, server) => this.#handleFetch(req, server),
       websocket: {
         idleTimeout: 0,
@@ -595,6 +605,7 @@ export class AkanApp {
   }
 
   async #handleFetch(req: Request, server: Bun.Server<GatewayWsData>): Promise<Response | undefined> {
+    if (this.#hostAllowlist && !this.#hostAllowlist.allows(req)) return this.#hostAllowlist.refuse();
     const url = new URL(req.url);
     if (url.pathname === "/_akan/app/health") return Response.json(this.#getHealthStatus());
     if (url.pathname === "/_akan/app/metrics") return Response.json(this.#getMetricsStatus());
@@ -638,6 +649,12 @@ export class AkanApp {
     const upstream = child?.upstream ? (child.wsUpstream ?? this.#getChildUpstream(child.idx, child.role).ws) : null;
     if (!child || !upstream) return new Response("No websocket upstream is ready", { status: 503 });
     const url = new URL(req.url);
+    
+    try {
+      CrossSiteGuard.assertOrigin(req, url, url.pathname === "/_akan/hmr" ? "hmr" : "websocket");
+    } catch {
+      return new Response("Forbidden", { status: 403 });
+    }
     const upstreamWs = new WebSocket(`ws://${upstream.host}:${upstream.port}${url.pathname}${url.search}`, {
       headers: makeAkanChildProxyHeaders(req, child.idx, server.requestIP(req)),
     } as unknown as string[]);
@@ -947,7 +964,8 @@ export class AkanApp {
     if (!location) return;
     try {
       const parsed = new URL(location);
-      if (parsed.hostname === "akan-child") headers.set("location", `${parsed.pathname}${parsed.search}${parsed.hash}`);
+      if (parsed.hostname === AKAN_CHILD_HOST)
+        headers.set("location", `${parsed.pathname}${parsed.search}${parsed.hash}`);
     } catch {
     }
   }
@@ -1074,6 +1092,7 @@ export class AkanApp {
     child.upstream = message.upstream;
     child.wsUpstream = message.wsUpstream;
     child.healthPath = message.healthPath;
+    if (message.crossSite) CrossSiteGuard.configure(message.crossSite);
     child.lastPongAtMono = performance.now();
     child.restartAttempts = 0;
     
@@ -1084,7 +1103,8 @@ export class AkanApp {
     this.#federationChildCache = null;
     
     const trafficChildren = [...this.#children.values()].filter((item) => item.role !== "batch");
-    if (child.role !== "batch" && trafficChildren.every((item) => item.ready)) {
+    
+    if (!this.#stopping && child.role !== "batch" && trafficChildren.every((item) => item.ready)) {
       process.send?.({ type: "backend-ready", pid: process.pid } satisfies AkanIpcMessage);
     }
     if ([...this.#children.values()].every((item) => item.ready)) {

package/server/akanAppHeaders.ts

@@ -11,6 +11,9 @@ const HOP_BY_HOP_HEADERS = new Set([
   "upgrade",
 ]);
 
+/** The Host every request the gateway hands a replica carries; a browser never sends it to a replica's port. */
+export const AKAN_CHILD_HOST = "akan-child";
+
 export interface ProxyClientPeer {
   address: string;
   port: number;
@@ -44,6 +47,6 @@ export function makeAkanChildProxyHeaders(req: Request, childIdx: number, peer?:
   if (!headers.has("x-request-id") && process.env.AKAN_BENCH_SKIP_REQUEST_ID !== "1") {
     headers.set("x-request-id", crypto.randomUUID());
   }
-  headers.set("host", "akan-child");
+  headers.set("host", AKAN_CHILD_HOST);
   return headers;
 }

package/server/akanServer.ts

@@ -19,11 +19,13 @@ import { AgentRelayAccess } from "../signal/guards";
 import { createOpenApiDocument } from "../signal/openapi";
 import { FetchSerializer } from "../signal/serializer";
 import { SignalContext } from "../signal/signalContext";
+import { AKAN_CHILD_HOST } from "./akanAppHeaders";
 import type { AkanLib, AkanLibProps } from "./akanLib";
 import { BinaryPubsub } from "./binaryPubsub";
 import { DevtoolsRouter } from "./devtools";
 import { DiLifecycle } from "./di/diLifecycle";
 import type { HmrWsData, HmrWsHub } from "./hmr/wsHub";
+import { OrphanGroup } from "./lifecycle/orphanGroup";
 import { isPortInUseError } from "./lifecycle/portInUse";
 import { resolveRuntimeDir } from "./lifecycle/runtimeDir";
 import { ShutdownManager } from "./lifecycle/shutdownManager";
@@ -42,6 +44,7 @@ import { WebProxyRunner } from "./proxy";
 import { SignalResolver } from "./resolver";
 import { type ApiRouteInputs, ApiRouter } from "./routing/apiRouter";
 import type { AppWsData } from "./routing/appWsData";
+import { HostAllowlist } from "./routing/hostAllowlist";
 import { createSoloAppRoutes } from "./routing/soloAppRoutes";
 import {
   getWebConfigFromEnv,
@@ -167,6 +170,7 @@ export class AkanServer {
   #ops: OpsRoute | null | undefined;
   #lastMetrics: AkanMetricsReport = {};
   #stopping: Promise<void> | null = null;
+  #orphanExiting = false;
   constructor(
     name = "AkanServer",
     env: BackendEnv = {},
@@ -392,7 +396,10 @@ export class AkanServer {
       }),
       data: {},
     } as Bun.WebSocketHandler<AppWsData | HmrWsData>;
-    const buildRoutes = (upgradeAppWs: ApiRouteInputs["upgradeAppWs"]) =>
+    
+    const hostAllowlist = unix ? null : HostAllowlist.fromEnv();
+    const hostname = process.env.AKAN_LISTEN_HOST || undefined;
+    const buildRoutes = (upgradeAppWs: ApiRouteInputs["upgradeAppWs"], allowlist: HostAllowlist | null) =>
       ApiRouter.buildRoutes({
         prefix: this.prefix,
         websocketPrefix: this.websocketPrefix,
@@ -402,19 +409,25 @@ export class AkanServer {
         renderEnvRoutes,
         upgradeAppWs,
         webProxyRunner,
+        hostAllowlist: allowlist,
       });
     this.#server = Bun.serve({
       idleTimeout: 0,
-      ...(unix ? { unix } : { port }),
-      routes: buildRoutes((req, data) => this.#server?.upgrade(req, { data }) ?? false),
+      ...(unix ? { unix } : { port, hostname }),
+      routes: buildRoutes((req, data) => this.#server?.upgrade(req, { data }) ?? false, hostAllowlist),
       websocket: websocketHandlers,
     } as Parameters<typeof Bun.serve>[0]);
     if (unix && process.env.AKAN_CHILD_WS_PORT) {
       const preferredWsPort = Number(process.env.AKAN_CHILD_WS_PORT);
+
       const wsServeOptions = (port: number) => ({
         idleTimeout: 0,
         port,
-        routes: buildRoutes((req, data) => this.#wsServer?.upgrade(req, { data }) ?? false),
+        hostname: "127.0.0.1",
+        routes: buildRoutes(
+          (req, data) => this.#wsServer?.upgrade(req, { data }) ?? false,
+          new HostAllowlist([AKAN_CHILD_HOST]),
+        ),
         websocket: websocketHandlers,
       });
       try {
@@ -467,6 +480,7 @@ export class AkanServer {
       upstream: unix ? { type: "unix", socketPath: unix } : { type: "tcp", host: "127.0.0.1", port: Number(port) },
       wsUpstream: typeof wsPort === "number" ? { type: "tcp", host: "127.0.0.1", port: wsPort } : undefined,
       healthPath: "/_akan/app/child-health",
+      crossSite: CrossSiteGuard.option(),
     } satisfies AkanIpcMessage);
     await this.#di.runSchedulerInit();
     ShutdownManager.register(this.logger, () => this.stop());
@@ -550,10 +564,16 @@ export class AkanServer {
 
   #handleParentDisconnect() {
     this.logger.warn("Parent IPC channel closed; shutting down to avoid an orphaned replica");
-    setTimeout(() => process.exit(1), this.shutdownTimeoutMs + 1_000);
+    setTimeout(() => this.#exitOrphaned(1), this.shutdownTimeoutMs + 1_000);
     void this.stop()
-      .then(() => process.exit(0))
-      .catch(() => process.exit(1));
+      .then(() => this.#exitOrphaned(0))
+      .catch(() => this.#exitOrphaned(1));
+  }
+
+  #exitOrphaned(code: number) {
+    if (this.#orphanExiting) return;
+    this.#orphanExiting = true;
+    OrphanGroup.exit(code);
   }
 
   #handleIpcMessage(message: AkanIpcMessage) {

package/server/index.ts

@@ -7,6 +7,7 @@ export * from "./console";
 export * from "./decorators";
 export * from "./devtools";
 export type { ChangeBatch, ChangeKind } from "./hmr/wsHub";
+export * from "./nativeFile";
 export * from "./oauth";
 export * from "./processMetricsCollector";
 export * from "./proxy";

package/server/lifecycle/orphanGroup.ts

@@ -0,0 +1,21 @@
+import { SelfExec } from "../selfExec";
+
+export class OrphanGroup {
+  static exit(code: number, { leads = SelfExec.carried && process.platform !== "win32", graceMs = 1_000 } = {}) {
+    if (!leads) process.exit(code);
+    process.removeAllListeners("SIGTERM");
+    process.on("SIGTERM", () => undefined);
+    OrphanGroup.#signal("SIGTERM");
+    setTimeout(() => {
+      OrphanGroup.#signal("SIGKILL");
+      process.exit(code);
+    }, graceMs);
+  }
+
+  static #signal(signal: NodeJS.Signals) {
+    try {
+      process.kill(-process.pid, signal);
+    } catch {
+    }
+  }
+}

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/ops/opsRoute.ts

@@ -1,5 +1,6 @@
 import { Logger } from "akanjs/common";
 import { getEnv } from "../../base/baseEnv";
+import { SelfExec } from "../selfExec";
 import type { AppDetailInfo } from "./appInfo";
 import { OpsTokenVerifier } from "./opsToken";
 import { type SnapshotJobRequest, SnapshotJobs } from "./snapshotJobs";
@@ -65,8 +66,8 @@ export class OpsRoute {
     const args = ["ops", "snapshot", "--id", request.id, "--out", dir, "--db", sources.main, "--json"];
     if (sources.solid) args.push("--solid-db", sources.solid);
     if (request.includeSolid) args.push("--include-solid");
-    const proc = Bun.spawn([process.execPath, Bun.main, ...args], {
-      env: process.env,
+    const proc = Bun.spawn(SelfExec.command(Bun.main, ...args), {
+      env: SelfExec.env(),
       stdout: "pipe",
       stderr: "pipe",
     });