@akanjs/devkit 3.1.1-rc.9 → 3.1.2-rc.0

package/mobile/nativeConfig.test.ts

@@ -2,6 +2,8 @@ import { describe, expect, test } from "bun:test";
 import { generateKeyPairSync } from "node:crypto";
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { buildCsp, cspHash, parseCsp } from "../../native/packages/cli/src/lib/csp";
+import { rewriteDevHtml } from "../../native/packages/cli/src/lib/hmr";
 import type { AkanNativeTarget } from "../akanConfig";
 import { tempDirs } from "../testHelpers";
 import { NativeApi } from "./nativeApi";
@@ -43,6 +45,19 @@ const adminTarget: AkanNativeTarget = {
   },
 };
 
+const cloudEnv = { AKAN_PUBLIC_APP_NAME: "minimal", AKAN_PUBLIC_ENV: "main", AKAN_PUBLIC_SERVE_DOMAIN: "example.com" };
+const policy = (extra: Record<string, string[]> = {}) =>
+  Object.fromEntries(
+    Object.entries(NativeConfig.defaultCsp).map(([directive, sources]) => [
+      directive,
+      [...sources, ...(extra[directive] ?? [])],
+    ]),
+  );
+const permissionOf = (id: string) =>
+  id === "opener"
+    ? { identifier: "opener:default", allow: NativeConfig.defaultOpenUrls.map((url) => ({ url })) }
+    : `${id}:default`;
+
 const ed25519Key = () =>
   generateKeyPairSync("ed25519").publicKey.export({ format: "der", type: "spki" }).subarray(12).toString("base64");
 const updatesKey = ed25519Key();
@@ -102,6 +117,7 @@ describe("NativeConfig.build", () => {
       contributions: [{ permission: "push", plugins: ["push"] }],
       locales: ["en", "ko"],
       platform: "android",
+      publicEnv: cloudEnv,
     });
 
     expect(warnings).toEqual([]);
@@ -113,9 +129,10 @@ describe("NativeConfig.build", () => {
         {
           identifier: "app",
           description: "The plugins minimal ships, each with its default permissions",
-          permissions: [...NativeConfig.basePlugins, "single-instance", "push"].map((plugin) => `${plugin}:default`),
+          permissions: [...NativeConfig.basePlugins, "single-instance", "push"].map(permissionOf),
         },
       ],
+      security: { csp: policy() },
       deepLinks: { schemes: ["minimal"], domains: ["example.com"] },
       android: {
         debugAppIdSuffix: ".debug",
@@ -144,11 +161,10 @@ describe("NativeConfig.build", () => {
         {
           identifier: "app",
           description: "The plugins Portal Admin ships, each with its default permissions",
-          permissions: [...NativeConfig.basePlugins, "camera", "geolocation", "contacts", "iap"].map(
-            (plugin) => `${plugin}:default`,
-          ),
+          permissions: [...NativeConfig.basePlugins, "camera", "geolocation", "contacts", "iap"].map(permissionOf),
         },
       ],
+      security: { csp: policy() },
       usageDescriptions: {
         NSCameraUsageDescription: "Portal Admin requires access to the camera to take photos.",
         NSPhotoLibraryAddUsageDescription: "Portal Admin requires access to the photo library to take photos.",
@@ -172,6 +188,22 @@ describe("NativeConfig.build", () => {
     });
   });
 
+  test('lists a basePath link with no locale segment for the default locale under localePrefix "as-needed"', () => {
+    const { config } = NativeConfig.build({
+      appPath: "/repo/apps/portal",
+      target: adminTarget,
+      webDir: "/web",
+      contributions: [],
+      locales: ["en", "ko"],
+      i18n: { defaultLocale: "en", localePrefix: "as-needed" },
+      platform: "android",
+    });
+
+    expect(config.deepLinks).toEqual({
+      domains: [{ host: "portal.example", pathPrefixes: ["/admin", "/en/admin", "/ko/admin"] }],
+    });
+  });
+
   test("a plugin that claims a permission replaces the builtin one and adds its Android entries", () => {
     const { config } = NativeConfig.build({
       appPath: "/repo/apps/portal",
@@ -362,7 +394,7 @@ describe("NativeConfig.build", () => {
 
     expect(config.plugins).toEqual([...NativeConfig.basePlugins, "./vendor/led-panel", kiosk]);
     expect(config.capabilities?.[0]?.permissions).toEqual(
-      [...NativeConfig.basePlugins, "led-panel", "kiosk"].map((id) => `${id}:default`),
+      [...NativeConfig.basePlugins, "led-panel", "kiosk"].map(permissionOf),
     );
     await mkdir(path.join(root, "web"), { recursive: true });
     await writeFile(path.join(root, "web/index.html"), "<html><head></head><body></body></html>");
@@ -493,6 +525,178 @@ describe("NativeConfig.build", () => {
     expect(build()).toEqual({ ...updates, target });
   });
 
+  describe("the page's content security policy", () => {
+    const build = (
+      target: Partial<AkanNativeTarget> = {},
+      more: Partial<Parameters<typeof NativeConfig.build>[0]> = {},
+    ) =>
+      NativeConfig.build({
+        appPath: "/repo/apps/minimal",
+        target: { ...minimalTarget, ...target },
+        webDir: "/web",
+        contributions: [],
+        locales: ["en"],
+        platform: "ios",
+        publicEnv: cloudEnv,
+        ...more,
+      }).config.security?.csp as Record<string, string[]> | string | undefined;
+
+    test("lets a local build reach the dev server on any port, and a carried server on loopback", () => {
+      const local = build({}, { publicEnv: { AKAN_PUBLIC_ENV: "local" } }) as Record<string, string[]>;
+      expect(local["connect-src"]).toEqual([
+        ...(NativeConfig.defaultCsp["connect-src"] ?? []),
+        "http://localhost:*",
+        "ws://localhost:*",
+      ]);
+      expect(local["script-src"]).toEqual(["'self'", "'wasm-unsafe-eval'"]);
+      const desktopServer = { dir: "/srv", entry: "main.js", env: {} };
+      const carried = build({}, { platform: "macos", desktopServer }) as Record<string, string[]>;
+      expect(carried["connect-src"]).toContain("http://127.0.0.1:*");
+      expect(carried["connect-src"]).toContain("ws://127.0.0.1:*");
+    });
+
+    test("a dev page under the default policy reaches the dev gateway's socket, on this computer or over the LAN", () => {
+      const csp = build({}, { publicEnv: { AKAN_PUBLIC_ENV: "local" } });
+      const devPolicy = (wsOrigin?: string) => {
+        const { html } = rewriteDevHtml(
+          '<!doctype html><html><head><meta charset="utf-8"></head><body><script type="module" src="/_akan/client/main.js"></script></body></html>',
+          {
+            platform: "ios",
+            port: 4321,
+            hmrPath: "/_akan/hmr",
+            wsPaths: ["/ws"],
+            ...(wsOrigin ? { wsOrigin } : {}),
+            csp,
+          },
+        );
+        const content = /http-equiv="Content-Security-Policy" content="([^"]*)"/.exec(html)?.[1] ?? "";
+        return parseCsp(content.replace(/&quot;/g, '"').replace(/&amp;/g, "&"));
+      };
+
+      const loopback = devPolicy();
+      expect(loopback.get("connect-src")).toEqual(
+        expect.arrayContaining(["'self'", "http://localhost:*", "ws://localhost:*", "ws://127.0.0.1:4321"]),
+      );
+      expect(loopback.get("script-src")).toEqual(expect.arrayContaining(["'self'", "blob:"]));
+      const lan = devPolicy("ws://192.168.0.12:4321");
+      expect(lan.get("connect-src")).toEqual(
+        expect.arrayContaining(["'self'", "ws://192.168.0.12:4321", "http://192.168.0.12:4321"]),
+      );
+      expect(lan.get("object-src")).toEqual(["'none'"]);
+    });
+
+    test("reaches any https or wss origin and loads https images, media, fonts and stylesheets, while scripts stay the app's", () => {
+      const csp = build() as Record<string, string[]>;
+      expect(csp["connect-src"]).toEqual(["'self'", "blob:", "data:", "https:", "wss:"]);
+      for (const directive of ["img-src", "media-src", "font-src"]) expect(csp[directive]).toContain("https:");
+      expect(csp["style-src"]).toEqual(["'self'", "'unsafe-inline'", "https:"]);
+      expect(csp["script-src"]).toEqual(["'self'", "'wasm-unsafe-eval'"]);
+    });
+
+    test("names a pinned AKAN_PUBLIC_SERVER_URL only when it is plain http", () => {
+      const connect = (url: string) =>
+        (build({}, { publicEnv: { ...cloudEnv, AKAN_PUBLIC_SERVER_URL: url } }) as Record<string, string[]>)[
+          "connect-src"
+        ];
+      expect(connect("https://api.example.com/x")).toEqual(["'self'", "blob:", "data:", "https:", "wss:"]);
+      expect(connect("http://192.168.0.5:8080/api")).toEqual([
+        "'self'",
+        "blob:",
+        "data:",
+        "https:",
+        "wss:",
+        "http://192.168.0.5:8080",
+        "ws://192.168.0.5:8080",
+      ]);
+    });
+
+    test("a directive map adds to the default, a string replaces it, and false ships none", () => {
+      const added = build({
+        csp: { "script-src": "https://sdk.example.com", "object-src": ["https://embed.example.com"] },
+      }) as Record<string, string[]>;
+      expect(added["script-src"]).toEqual(["'self'", "'wasm-unsafe-eval'", "https://sdk.example.com"]);
+      expect(added["object-src"]).toEqual(["https://embed.example.com"]);
+      expect(build({ csp: "strict" })).toBe("strict");
+      expect(build({ csp: false })).toBeUndefined();
+    });
+
+    test("a directive the default lacks starts from its CSP fallback, so the bundle and init.js still run", () => {
+      const csp = build({
+        csp: {
+          "script-src": "https://sdk.example.com",
+          "script-src-elem": ["https://cdn.example.com"],
+          "style-src-attr": "https://styles.example.com",
+          "manifest-src": ["https://manifest.example.com"],
+          "upgrade-insecure-requests": [],
+        },
+      }) as Record<string, string[]>;
+      expect(csp["script-src-elem"]).toEqual([
+        "'self'",
+        "'wasm-unsafe-eval'",
+        "https://sdk.example.com",
+        "https://cdn.example.com",
+      ]);
+      expect(csp["style-src-attr"]).toEqual(["'self'", "'unsafe-inline'", "https:", "https://styles.example.com"]);
+      expect(csp["manifest-src"]).toEqual(["'self'", "https://manifest.example.com"]);
+      expect(csp["upgrade-insecure-requests"]).toEqual([]);
+
+      const page =
+        '<html><head><meta charset="utf-8"><script src="/__akan_native/init.js"></script></head><body><script type="module">boot()</script></body></html>';
+      expect(parseCsp(buildCsp(csp, page).policy).get("script-src-elem")).toEqual(
+        expect.arrayContaining(["'self'", cspHash("boot()")]),
+      );
+    });
+
+    test("directive names ignore case, and a default-src entry reaches every fetch directive but object-src", () => {
+      const csp = build({
+        csp: { "Connect-Src": ["https://upload.example.com"], "default-src": "https://cdn.example.com" },
+      }) as Record<string, string[]>;
+      expect(Object.keys(csp)).not.toContain("Connect-Src");
+      expect(csp["connect-src"]).toEqual([
+        "'self'",
+        "blob:",
+        "data:",
+        "https:",
+        "wss:",
+        "https://cdn.example.com",
+        "https://upload.example.com",
+      ]);
+      expect(csp["default-src"]).toEqual(["'self'", "https://cdn.example.com"]);
+      for (const directive of ["script-src", "style-src", "img-src", "font-src", "worker-src", "frame-src"])
+        expect(csp[directive]).toContain("https://cdn.example.com");
+      expect(csp["object-src"]).toEqual(["'none'"]);
+      expect(csp["base-uri"]).toEqual(["'self'"]);
+    });
+
+    test("refuses an empty policy string and names csp: false", () => {
+      expect(() => build({ csp: "" })).toThrow("`csp: false`");
+      expect(() => build({ csp: " " })).toThrow("`csp: false`");
+    });
+  });
+
+  test("opener opens https, mailto and tel links unless the app names its own", () => {
+    const opener = (openUrls?: string[]) =>
+      NativeConfig.build({
+        appPath: "/repo/apps/minimal",
+        target: { ...minimalTarget, ...(openUrls ? { openUrls } : {}) },
+        webDir: "/web",
+        contributions: [],
+        locales: ["en"],
+        platform: "android",
+        publicEnv: cloudEnv,
+      }).config.capabilities?.[0]?.permissions.find((permission) => JSON.stringify(permission).includes("opener"));
+
+    expect(opener()).toEqual({
+      identifier: "opener:default",
+      allow: [{ url: "https://*:*" }, { url: "mailto:*" }, { url: "tel:*" }],
+    });
+    expect(opener(["https://*.example.com/*"])).toEqual({
+      identifier: "opener:default",
+      allow: [{ url: "https://*.example.com/*" }],
+    });
+    expect(opener(["*"])).toBe("opener:default");
+  });
+
   test("keeps a file name the runtime accepts", () => {
     expect(NativeConfig.fileNameOf("minimal")).toBe("minimal");
     expect(NativeConfig.fileNameOf("my app!")).toBe("my-app");

package/mobile/nativeConfig.ts

@@ -8,7 +8,7 @@ import type {
   NativeEnv,
   NativePermission,
 } from "akanjs";
-import { trimSlashes } from "akanjs/common";
+import { type AkanI18nConfig, LocalePath, trimSlashes } from "akanjs/common";
 import type { AkanNativeConfig } from "akanjs/native/config";
 import type { DesktopServerBundle } from "./desktopServerStage";
 import { type NativePlatform, resolveAppId } from "./mobileTarget";
@@ -24,6 +24,7 @@ export interface NativeConfigInput {
   /** What the app's and its libs' plugins declare. */
   contributions: AkanPluginNativeConfig[];
   locales: readonly string[];
+  i18n?: Pick<AkanI18nConfig, "defaultLocale" | "localePrefix">;
   /** The backend the binary talks to; an updates channel left unnamed follows it. */
   env?: NativeEnv;
   platform: NativePlatform;
@@ -33,6 +34,8 @@ export interface NativeConfigInput {
   nativePlugins?: NativePluginFolder[];
   /** A desktop build's staged `bin` executables (DesktopBin). */
   desktopBin?: string;
+  /** The `AKAN_PUBLIC_*` the web build inlined, derived keys included. */
+  publicEnv?: Record<string, string>;
 }
 
 export interface NativeConfigResult {
@@ -58,6 +61,42 @@ export class NativeConfig {
     "secure-storage",
     "haptics",
   ] as const;
+  //? Only scripts stay strict ('self', inline ones by hash): injected script must not reach the native bridge.
+  static readonly defaultCsp: Readonly<Record<string, readonly string[]>> = {
+    "default-src": ["'self'"],
+    "script-src": ["'self'", "'wasm-unsafe-eval'"],
+    "style-src": ["'self'", "'unsafe-inline'", "https:"],
+    "img-src": ["'self'", "blob:", "data:", "https:"],
+    "media-src": ["'self'", "blob:", "data:", "https:"],
+    "font-src": ["'self'", "data:", "https:"],
+    "connect-src": ["'self'", "blob:", "data:", "https:", "wss:"],
+    "worker-src": ["'self'", "blob:"],
+    "frame-src": ["'self'", "https:"],
+    "object-src": ["'none'"],
+    "base-uri": ["'self'"],
+    "form-action": ["'self'"],
+  };
+  static readonly #fetchDirectives: readonly string[] = [
+    "child-src",
+    "connect-src",
+    "fenced-frame-src",
+    "font-src",
+    "frame-src",
+    "img-src",
+    "manifest-src",
+    "media-src",
+    "object-src",
+    "prefetch-src",
+    "script-src",
+    "script-src-elem",
+    "script-src-attr",
+    "style-src",
+    "style-src-elem",
+    "style-src-attr",
+    "worker-src",
+  ];
+  //? Also bounds the links the shell hands to the OS; on mobile, openExternalUrl sends http(s) to the browser plugin.
+  static readonly defaultOpenUrls: readonly string[] = ["https://*:*", "mailto:*", "tel:*"];
   //* Used when no plugin of the app or its libs claims the permission; speech has no native plugin yet.
   static readonly builtinContributions: { [permission in NativePermission]: AkanPluginNativeConfig } = {
     camera: {
@@ -95,11 +134,13 @@ export class NativeConfig {
     webDir,
     contributions,
     locales,
+    i18n,
     env,
     platform,
     desktopServer,
     nativePlugins = [],
     desktopBin,
+    publicEnv = {},
   }: NativeConfigInput): NativeConfigResult {
     const warnings: string[] = [];
     const applied = (target.permissions ?? []).flatMap((permission) => {
@@ -189,6 +230,8 @@ export class NativeConfig {
       backgroundColorDark: typeof background === "string" ? undefined : background?.dark,
       devtools: target.devtools ? true : undefined,
     });
+    const csp = NativeConfig.#csp(target, NativeConfig.#plainOrigins(publicEnv, env, !!desktopServer));
+    const openUrls = target.openUrls ?? NativeConfig.defaultOpenUrls;
     const config: AkanNativeConfig = {
       app: {
         id: resolveAppId(target.appId, platform),
@@ -205,12 +248,17 @@ export class NativeConfig {
         {
           identifier: "app",
           description: `The plugins ${target.appName} ships, each with its default permissions`,
-          permissions: pluginIds.map((id) => `${id}:default`),
+          permissions: pluginIds.map((id) =>
+            id === "opener" && !openUrls.includes("*")
+              ? { identifier: "opener:default", allow: openUrls.map((url) => ({ url })) }
+              : `${id}:default`,
+          ),
         },
       ],
+      ...(csp ? { security: { csp } } : {}),
       ...(Object.keys(usageDescriptions).length ? { usageDescriptions } : {}),
       ...(target.deepLinks?.schemes?.length || target.deepLinks?.domains?.length
-        ? { deepLinks: NativeConfig.#deepLinks(target, locales) }
+        ? { deepLinks: NativeConfig.#deepLinks(target, locales, i18n) }
         : {}),
       ...(native ? { native } : {}),
       ...(updates ? { updates } : {}),
@@ -237,6 +285,69 @@ export class NativeConfig {
     return { config, warnings };
   }
 
+  static #csp({ name, csp: setting }: AkanNativeTarget, plainOrigins: string[]) {
+    if (setting === false) return undefined;
+    if (typeof setting === "string") {
+      if (!setting.trim())
+        throw new Error(
+          `Native target '${name}': csp "" is no policy; write \`csp: false\` to ship the page without one.`,
+        );
+      return setting;
+    }
+    const policy: Record<string, string[]> = Object.fromEntries(
+      Object.entries(NativeConfig.defaultCsp).map(([directive, sources]) => [directive, [...sources]]),
+    );
+    const add = (directive: string, sources: readonly string[]) => {
+      const list = policy[directive] ?? [];
+      policy[directive] = [...new Set([...list.filter((source) => source !== "'none'"), ...sources])];
+    };
+    add("connect-src", [...plainOrigins, ...plainOrigins.map((origin) => origin.replace(/^http/, "ws"))]);
+    add("img-src", plainOrigins);
+    add("media-src", plainOrigins);
+    const asked = new Map<string, string[]>();
+    for (const [key, sources] of Object.entries(setting ?? {})) {
+      const directive = key.toLowerCase();
+      const list = typeof sources === "string" ? sources.split(/\s+/).filter(Boolean) : sources;
+      asked.set(directive, [...(asked.get(directive) ?? []), ...list]);
+    }
+    //? Each fetch directive the default names overrides default-src, so a default-src entry has to reach every one.
+    const everywhere = asked.get("default-src") ?? [];
+    asked.delete("default-src");
+    if (everywhere.length)
+      for (const directive of Object.keys(policy))
+        if (
+          directive === "default-src" ||
+          (directive !== "object-src" && NativeConfig.#fetchDirectives.includes(directive))
+        )
+          add(directive, everywhere);
+    const variant = /^(script|style)-src-(elem|attr)$/;
+    //? A directive the default lacks starts from its CSP fallback, else naming it would drop 'self' and the hashes.
+    for (const [directive, sources] of [...asked].sort(
+      ([a], [b]) => Number(variant.test(a)) - Number(variant.test(b)),
+    )) {
+      const from = variant.test(directive)
+        ? directive.replace(/-(elem|attr)$/, "")
+        : NativeConfig.#fetchDirectives.includes(directive)
+          ? "default-src"
+          : null;
+      policy[directive] ??= [...(from ? (policy[from] ?? []) : [])];
+      add(directive, sources);
+    }
+    return policy;
+  }
+
+  //? https: and wss: cover a cloud API, so only plain-http origins are named; a carried server's port comes at launch.
+  static #plainOrigins(publicEnv: Record<string, string | undefined>, env: NativeEnv | undefined, carried: boolean) {
+    const origins = new Set<string>();
+    const pinned = publicEnv.AKAN_PUBLIC_SERVER_URL;
+    if (pinned && URL.canParse(pinned) && new URL(pinned).protocol === "http:") origins.add(new URL(pinned).origin);
+    const environment = publicEnv.AKAN_PUBLIC_ENV ?? env ?? "debug";
+    const mode = publicEnv.AKAN_PUBLIC_OPERATION_MODE ?? (environment === "local" ? "local" : "cloud");
+    if (mode === "local") origins.add("http://localhost:*");
+    if (carried) origins.add("http://127.0.0.1:*");
+    return [...origins];
+  }
+
   static #icon(
     icon: NonNullable<AkanNativeTarget["icon"]>,
     abs: (relative: string) => string,
@@ -310,10 +421,20 @@ export class NativeConfig {
     return Object.assign({}, ...contributed, own);
   }
 
-  //* Every route sits under /:lang, so an app link limited to a basePath lists it once per locale.
-  static #deepLinks(target: AkanNativeTarget, locales: readonly string[]) {
+  //* An app link limited to a basePath lists it per locale, plus the unprefixed URL `"as-needed"` gives the default one.
+  static #deepLinks(
+    target: AkanNativeTarget,
+    locales: readonly string[],
+    i18n: Pick<AkanI18nConfig, "defaultLocale" | "localePrefix"> = { defaultLocale: "" },
+  ) {
     const basePath = target.basePath ? trimSlashes(target.basePath) : "";
-    const pathPrefixes = basePath ? locales.map((locale) => `/${locale}/${basePath}`) : undefined;
+    const pathPrefixes = basePath
+      ? [
+          ...new Set(
+            locales.flatMap((locale) => [LocalePath.join(locale, `/${basePath}`, i18n), `/${locale}/${basePath}`]),
+          ),
+        ]
+      : undefined;
     return {
       ...(target.deepLinks?.schemes?.length ? { schemes: target.deepLinks.schemes } : {}),
       ...(target.deepLinks?.domains?.length

package/mobile/nativePublicEnv.test.ts

@@ -43,12 +43,14 @@ describe("NativePublicEnv", () => {
         AKAN_PUBLIC_MAP_TOKEN: "x",
         AKAN_PUBLIC_PORT: 8282,
         AKAN_PUBLIC_NOTE: "line\nbreak",
+        AKAN_PUBLIC_SIGNER: "-----BEGIN EC PRIVATE KEY-----\\nMHc\\n-----END EC PRIVATE KEY-----",
       }),
     ).toEqual([
       "AKAN_PUBLIC_lower is not an AKAN_PUBLIC_[A-Z0-9_] name",
       "AKAN_PUBLIC_MAP_TOKEN names a token, which a page bundle must not carry",
       "AKAN_PUBLIC_PORT is not a string",
       "AKAN_PUBLIC_NOTE holds a control character",
+      "AKAN_PUBLIC_SIGNER holds a private key",
     ]);
     const many = Object.fromEntries(Array.from({ length: 257 }, (_, idx) => [`AKAN_PUBLIC_K${idx}`, "v"]));
     expect(NativePublicEnv.problems(many)).toEqual(["257 keys, more than 256"]);

package/mobile/nativePublicEnv.ts

@@ -16,6 +16,7 @@ export class NativePublicEnv {
     "AKAN_PUBLIC_RENDER_ENV",
     "AKAN_PUBLIC_DEFAULT_LOCALE",
     "AKAN_PUBLIC_LOCALES",
+    "AKAN_PUBLIC_LOCALE_PREFIX",
   ];
   //? Akan Cloud's own limits on a recorded env: a build it would refuse fails here, before anything is signed.
   static readonly #keyPattern = /^AKAN_PUBLIC_[A-Z0-9_]{1,128}$/;
@@ -46,6 +47,7 @@ export class NativePublicEnv {
       const word = NativePublicEnv.#secretWords.find((secret) => key.includes(secret));
       if (word) return [`${key} names a ${word.toLowerCase()}, which a page bundle must not carry`];
       if (typeof value !== "string") return [`${key} is not a string`];
+      if (/-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/.test(value)) return [`${key} holds a private key`];
       // biome-ignore lint/suspicious/noControlCharactersInRegex: the control characters are what is refused
       if (/[\u0000-\u001f\u007f]/.test(value)) return [`${key} holds a control character`];
       return [];
@@ -71,6 +73,17 @@ export class NativePublicEnv {
     return NativePublicEnv.of((await file.json()) as Record<string, unknown>);
   }
 
+  /** Every `AKAN_PUBLIC_*` the last `akan build` inlined, derived keys included, else the ones this process has. */
+  static async inlined(app: App): Promise<PublicEnv> {
+    const file = Bun.file(CsrArtifactBuilder.publicEnvPath(app));
+    const env = (await file.exists()) ? ((await file.json()) as Record<string, unknown>) : process.env;
+    return Object.fromEntries(
+      Object.entries(env).flatMap(([key, value]) =>
+        key.startsWith("AKAN_PUBLIC_") && typeof value === "string" ? [[key, value]] : [],
+      ),
+    );
+  }
+
   /** A bundle.json's record, or null when it has none (a build from before the record, or no file at all). */
   static async recordedIn(bundleFile: string): Promise<PublicEnv | null> {
     const file = Bun.file(bundleFile);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.1-rc.9",
+  "version": "3.1.2-rc.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -34,12 +34,14 @@
     "./incrementalBuilder": "./incrementalBuilder/index.ts",
     "./mobile": "./mobile/index.ts",
     "./pipeline": "./pipeline/index.ts",
+    "./preview": "./preview/index.ts",
     "./transforms": "./transforms/index.ts",
     "./workflow": "./workflow/index.ts",
     "./*.ts": "./*.ts",
     "./*": "./*.ts"
   },
   "dependencies": {
+    "@akanjs/language": "3.1.2-rc.0",
     "@earendil-works/pi-agent-core": "1.3.0",
     "@earendil-works/pi-ai": "1.3.0",
     "@earendil-works/pi-codemode": "1.3.0",
@@ -48,7 +50,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.1.1-rc.9",
+    "akanjs": "3.1.2-rc.0",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/platformTest/LinuxDockerTarget.ts

@@ -40,6 +40,9 @@ export class LinuxDockerTarget extends PlatformTestTarget {
       "run",
       "-d",
       "--rm",
+      //? An init as PID 1 reaps orphans as a real host does; under `sleep` a killed orphan stays a zombie that still
+      //? answers kill(pid, 0).
+      "--init",
       "--name",
       container,
       "--cpus",

package/{codeAgent/feedback → preview}/PreviewChrome.ts

@@ -2,6 +2,8 @@ import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 
+export type PreviewEngine = "webkit" | "chrome";
+
 // Bun.WebView's `webkit` backend is the macOS system framework and throws on every other platform.
 export class PreviewChrome {
   /** Read by `Bun.WebView` itself; listed so the availability check agrees with what the launcher will do. */
@@ -30,7 +32,7 @@ export class PreviewChrome {
     "Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
   ];
 
-  static get backend(): "webkit" | "chrome" {
+  static get backend(): PreviewEngine {
     const declared = process.env[PreviewChrome.backendEnvKey];
     if (declared === "webkit" || declared === "chrome") return declared;
     return process.platform === "darwin" ? "webkit" : "chrome";
@@ -53,11 +55,15 @@ export class PreviewChrome {
   }
 
   static get available() {
-    return PreviewChrome.backend === "webkit" ? process.platform === "darwin" : !!PreviewChrome.executable();
+    return PreviewChrome.isAvailable();
+  }
+
+  static isAvailable(engine: PreviewEngine = PreviewChrome.backend) {
+    return engine === "webkit" ? process.platform === "darwin" : !!PreviewChrome.executable();
   }
 
-  static backendOption() {
-    if (PreviewChrome.backend === "webkit") return "webkit";
+  static backendOption(engine: PreviewEngine = PreviewChrome.backend) {
+    if (engine === "webkit") return "webkit";
     // Docker's default 64MB /dev/shm is below what Chromium's renderer allocates; the crash looks like a hung load.
     const argv = ["--disable-dev-shm-usage"];
     // Chromium refuses uid 0 with its sandbox on, and uid 0 is the ordinary uid in a container.
@@ -70,9 +76,9 @@ export class PreviewChrome {
     "apt-get update && apt-get install -y --no-install-recommends chromium fonts-liberation fonts-noto-color-emoji fonts-noto-cjk && rm -rf /var/lib/apt/lists/*",
   ];
 
-  static unavailableReason() {
-    if (PreviewChrome.available) return undefined;
-    if (PreviewChrome.backend === "webkit")
+  static unavailableReason(engine: PreviewEngine = PreviewChrome.backend) {
+    if (PreviewChrome.isAvailable(engine)) return undefined;
+    if (engine === "webkit")
       return `The webkit WebView backend exists only on macOS. Set ${PreviewChrome.backendEnvKey}=chrome and install a browser.`;
     return [
       "The page preview needs a browser and this machine has none on PATH.",