@akanjs/devkit 3.1.1 → 3.1.2-rc.0

package/integration/ssrMemoryProbe.ts

@@ -1,3 +1,4 @@
+import { randomBytes } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -93,6 +94,7 @@ export class SsrMemoryProbe {
   }
 
   readonly #options: SsrMemoryProbeOptions;
+  readonly #statusToken = randomBytes(32).toString("hex");
   #gatewayPid = 0;
 
   constructor(options: SsrMemoryProbeOptions) {
@@ -119,6 +121,8 @@ export class SsrMemoryProbe {
         SERVER_MODE: "federation",
         ...(basePaths ? { AKAN_PUBLIC_BASE_PATHS: basePaths } : {}),
         PORT: String(port),
+        // A built app run outside `akan start` keeps the health detail and metrics behind this token.
+        AKAN_STATUS_TOKEN: this.#statusToken,
         AKAN_MEMORY_LOG: "1",
         AKAN_MEMORY_LOG_INTERVAL_MS: String(this.#options.metricsIntervalMs),
         ...(cacheOff ? { AKAN_HTML_RESULT_CACHE: "0", AKAN_RSC_RESULT_CACHE: "0" } : {}),
@@ -315,6 +319,7 @@ export class SsrMemoryProbe {
   async #fetchChildMetrics(): Promise<Array<Record<string, number>>> {
     try {
       const res = await fetch(`http://localhost:${this.#options.port}/_akan/app/metrics`, {
+        headers: { authorization: `Bearer ${this.#statusToken}` },
         signal: AbortSignal.timeout(5_000),
       });
       if (!res.ok) return [];
@@ -393,6 +398,7 @@ export class SsrMemoryProbe {
     while (Date.now() < deadline) {
       try {
         const res = await fetch(`http://localhost:${this.#options.port}/_akan/app/health`, {
+          headers: { authorization: `Bearer ${this.#statusToken}` },
           signal: AbortSignal.timeout(2_000),
         });
         if (res.ok) {

package/lint/no-unguarded-endpoint.grit

@@ -1,8 +1,8 @@
 engine biome(1.0)
 language js(typescript, jsx)
 
-// `SignalContext` checks `signalOption.guards ?? []`, so an endpoint, a named slice, or a slice's root query declaring
-// none is open to every HTTP and websocket caller. An option the rule cannot read, a variable or a spread, is left alone.
+// `SignalContext` refuses an endpoint, a named slice, or a slice's root query declaring no guards, and outside local
+// operation the server does not boot with one. An option the rule cannot read, a variable or a spread, is left alone.
 or {
   JsCallExpression(callee = $callee, arguments = JsCallArguments(args = $args)) as $call where {
     or {
@@ -32,7 +32,7 @@ or {
     },
     register_diagnostic(
       span = $callee,
-      message = "No `guards`, so every HTTP and websocket caller reaches this endpoint: a missing or empty `guards` fails open, which is also why MCP refuses it. Name the guards it needs, or write `guards: [Public]` when anonymous access is the intent.",
+      message = "No `guards`, so every call to this endpoint is refused with 403, and outside local operation the server does not boot. Name the guards it needs, or write `guards: [Public]` when anonymous access is the intent.",
       severity = "warn"
     )
   },
@@ -47,7 +47,7 @@ or {
         },
         register_diagnostic(
           span = $sliceOption,
-          message = "No `guards` on this slice, so every HTTP and websocket caller reaches its root query and generated reads and writes: a missing guard fails open. Pass { guards: { root: Admin, get: …, cru: … } }, naming `Public` where anonymous access is the intent.",
+          message = "No `guards` on this slice, so it mounts no root list or insight and none of its generated reads and writes. Pass { guards: { root: Admin, get: …, cru: … } }, naming `Public` where anonymous access is the intent.",
           severity = "warn"
         )
       },
@@ -64,7 +64,7 @@ or {
         },
         register_diagnostic(
           span = $guardMap,
-          message = "No `root` guard on this slice, so its root query lists any filter to every HTTP and websocket caller: a missing or empty `root` fails open. Write `root: Admin`.",
+          message = "No `root` guard on this slice. Left out, it mounts no root list or insight; `root: []` refuses every caller with 403, and outside local operation the server does not boot. Write `root: Admin`, or `root: Public` for anonymous access.",
           severity = "warn"
         )
       }

package/maintainabilityReport.ts

@@ -41,7 +41,7 @@ export class MaintainabilityReport {
     "akan.write.placement":
       "A server write leaves the browser through one store action, started by one module component. Move a `fetch.<mutation>` into a store action, and hand `ui/` and `webkit/` code the write as an `onX` prop or hook argument from the module's `Zone` or `Util`: they stay free of any one model, and an agent or another screen reaches the write through the store.",
     "akan.service.call-in-loop":
-      "Load the set once (`load<Model>Many(ids)`, one filter query) or write it once (one batch method), then loop in memory: a call per item is a round trip per item, so the endpoint slows as its input grows.",
+      "Load the set once (`load<Model>Many(ids)`, one filter query) or write it once (`create<Model>Many(rows)`, one batch method), then loop in memory: a call per item is a round trip per item, so the endpoint slows as its input grows.",
     "akan.baseline.growth":
       "Restore the entry from the default branch, then split the file or move the writes instead: `akan lint` lowers an entry as the code shrinks and never raises one.",
   };

package/mobile/desktopServerStage.test.ts

@@ -145,6 +145,7 @@ describe("DesktopServerStage", () => {
     ];
     const imageOnly = [
       "Dockerfile",
+      "akan.env.json",
       "package.json",
       "rscWorker.js",
       "console.js",

package/mobile/desktopServerStage.ts

@@ -2,6 +2,7 @@ import { cp, mkdir, readdir, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { toError } from "akanjs/common";
 import type { ServerPolicy } from "akanjs/native/api";
+import { BUILD_ENV_FILE } from "akanjs/server/lifecycle/buildEnv";
 import type { AkanAppConfig, NativeEnv } from "../akanConfig";
 import type { App } from "../commandDecorators";
 import type { PackageJson } from "../types";
@@ -26,9 +27,10 @@ export interface DesktopServerRun extends ServerPolicy {
 export class DesktopServerStage {
   //? An API-only server starts neither the RSC worker nor the akan console and serves no CSR, public/ or SSR
   //? artifact, and `install` wrote its own package.json and bun.lock. The rest of dist is the server's: its chunks,
-  //? a `.node`, a `.wasm`.
+  //? a `.node`, a `.wasm`. The build's env file would hand it the PORT and AKAN_LOG_TO_FILE its launcher leaves out.
   static readonly uncarried = new Set([
     "Dockerfile",
+    BUILD_ENV_FILE,
     "package.json",
     "bun.lock",
     "rscWorker.js",

package/mobile/nativeApp.test.ts

@@ -313,18 +313,33 @@ describe("NativeApp", () => {
     expect(await injected()).toContain('"indexPath":"/mobile"');
   });
 
-  test("builds its config from the app's locales and the plugins' native contributions", async () => {
+  test("builds its config from the app's locales, the plugins' native contributions and the inlined public env", async () => {
     const push: AkanPlugin = { name: "push-notification", native: { permission: "push", plugins: ["push"] } };
-    const app = new NativeApp(
-      fakeApp([push, { name: "other" }]),
-      target({ basePath: undefined, permissions: ["push"] }),
-    );
+    const root = await makeTempRoot();
+    const portal = { ...fakeApp([push, { name: "other" }]), dist: { cwdPath: path.join(root, "dist/apps/portal") } };
+    await CsrArtifactBuilder.writePublicEnv(portal as unknown as App, {
+      "process.env.AKAN_PUBLIC_APP_NAME": '"portal"',
+      "process.env.AKAN_PUBLIC_ENV": '"main"',
+      "process.env.AKAN_PUBLIC_SERVE_DOMAIN": '"akamir.com"',
+      "process.env.AKAN_PUBLIC_SERVER_URL": '"http://192.168.0.5:8080/api"',
+    });
+    const app = new NativeApp(portal as unknown as App, target({ basePath: undefined, permissions: ["push"] }));
 
     const { config, warnings } = await app.config({ platform: "android" });
 
     expect(warnings).toEqual([]);
     expect(config.plugins).toEqual([...NativeConfig.basePlugins, "push"]);
     expect(config.web.dir).toBe(path.join(nativeDir, "default/web"));
+    const csp = config.security?.csp as Record<string, string[]> | undefined;
+    expect(csp?.["connect-src"]).toEqual([
+      "'self'",
+      "blob:",
+      "data:",
+      "https:",
+      "wss:",
+      "http://192.168.0.5:8080",
+      "ws://192.168.0.5:8080",
+    ]);
   });
 
   test("a config nothing is built from (the update key's) stages no desktop bin", async () => {

package/mobile/nativeApp.ts

@@ -124,10 +124,11 @@ export class NativeApp {
     stageBin?: boolean;
     arch?: DesktopArch;
   }) {
-    const [appConfig, plugins, nativePlugins] = await Promise.all([
+    const [appConfig, plugins, nativePlugins, publicEnv] = await Promise.all([
       this.app.getConfig(),
       this.app.collectPlugins(),
       NativePluginFolders.of(this.app),
+      NativePublicEnv.inlined(this.app),
     ]);
     const desktop = platform === "macos" || platform === "windows" || platform === "linux";
     const carried = desktop && stageBin ? await new DesktopBin(this.app, appConfig).stage(this.binDir, arch) : [];
@@ -137,9 +138,11 @@ export class NativeApp {
       webDir: this.web.dir,
       contributions: plugins.flatMap((plugin) => (plugin.native ? [plugin.native] : [])),
       locales: appConfig.i18n.locales,
+      i18n: appConfig.i18n,
       env: this.env,
       platform,
       nativePlugins,
+      publicEnv,
       ...(server ? { desktopServer: server } : {}),
       ...(carried.length ? { desktopBin: this.binDir } : {}),
     });

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