@driftengine/package 3.61.2 → 3.62.0

package/README.md

@@ -58,7 +58,8 @@ Beside your `package.json`, in the project that produces the web build:
   "features": { "clipExport": false, "gamepad": true },
   "splash": { "show": true, "minMs": 1400 },
   "targets": ["linux-x64", "win-x64", "mac-arm64"],
-  "steam": { "appId": null }
+  "steam": { "appId": null },
+  "android": { "permissions": [], "cleartextTraffic": false }
 }
 ```
 
@@ -243,6 +244,40 @@ bridge is injected before the game's own scripts through `addDocumentStartJavaSc
 mobile equivalent of the desktop preload, so `createHost` finds the same `__driftHost` it finds on
 the desktop.
 
+### An APK asks for nothing until a game says so
+
+The manifest template declares one activity and **no permissions**, which is the right default: a
+permission is visible in the store listing, and a packager that granted the network to every game
+it ever built would be asking on behalf of games that never use it. A game that needs the network
+says so:
+
+```json
+"android": { "permissions": ["INTERNET"], "cleartextTraffic": false }
+```
+
+`"INTERNET"` and `"android.permission.INTERNET"` are both accepted, and the elements are written
+into the copied Gradle project before Gradle runs — the same copy the icon is written into, so
+nothing in this repository is touched by a consumer's build. `drift-package doctor` prints what was
+asked for, and `aapt2 dump permissions <apk>` is how to confirm it landed.
+
+**Without it every connection fails and nothing says why.** The process is not permitted to open a
+socket, so the game reports that it could not connect and the server logs nothing at all, because
+no packet leaves the phone. That is the same silence on both ends, and it is indistinguishable from
+a wrong address.
+
+### Reaching a relay that has no certificate
+
+`cleartextTraffic` is the second half, and it is false by default. The game is served from an https
+origin, so a WebView will not open `ws://` from it: a WebView defaults to `MIXED_CONTENT_NEVER_ALLOW`,
+which is stricter than a browser tab, where the same connection succeeds with a deprecation warning
+(measured on Chrome 151 against a LAN address). Setting it true writes
+`android:usesCleartextTraffic="true"` **and** is what `MainActivity` reads back at runtime, through
+`NetworkSecurityPolicy`, to allow mixed content in the WebView. One switch, so the platform and the
+renderer cannot disagree — which they would if only the manifest moved.
+
+Set it only for the case it exists for: a relay on a LAN, which cannot hold a certificate for an
+address that is not a name. A public relay should be `wss://` and this should stay false.
+
 **Signing is not optional here and there is no unsigned option to offer**: Android refuses to
 install an unsigned APK at all. Without a keystore the packager generates one and says so on every
 build. That APK installs on a device with developer mode on; it cannot go to the Play Store.

package/android/app/src/main/java/dev/driftengine/host/MainActivity.java

@@ -12,9 +12,11 @@ import android.view.WindowInsetsController;
 import android.view.WindowManager;
 import android.widget.Toast;
 import android.os.Message;
+import android.security.NetworkSecurityPolicy;
 import android.webkit.WebChromeClient;
 import android.webkit.WebResourceRequest;
 import android.webkit.WebResourceResponse;
+import android.webkit.WebSettings;
 import android.webkit.WebView;
 import android.webkit.WebViewClient;
 import android.webkit.URLUtil;
@@ -91,6 +93,28 @@ public final class MainActivity extends Activity {
        error — which is indistinguishable from a broken link. With it, the request arrives at
        onCreateWindow below and is sent to the person's browser. */
     web.getSettings().setSupportMultipleWindows(true);
+    /*
+     * **Mixed content follows the manifest's cleartext policy, read back from the platform.**
+     *
+     * The game is served from an https origin (see the class comment), so it is a secure context,
+     * and a WebView defaults to MIXED_CONTENT_NEVER_ALLOW — stricter than a browser tab, which
+     * permits an insecure WebSocket from a secure page with a deprecation warning. A relay on a
+     * LAN cannot hold a certificate, so a game that wants one asks for
+     * `"android": { "cleartextTraffic": true }` and gets `usesCleartextTraffic="true"` in its
+     * manifest. Without this line that flag would be half a permission: Android would allow the
+     * socket and the renderer would still refuse it, which is the kind of disagreement nobody can
+     * debug from either side.
+     *
+     * **Read from NetworkSecurityPolicy rather than passed in as a build property**, so there is
+     * one source of truth. The policy reflects `usesCleartextTraffic` and any network security
+     * config a consumer adds later, so the two cannot drift apart and a scoped config keeps
+     * working without this file learning about it.
+     *
+     * A build that asks for nothing keeps NEVER_ALLOW, which is exactly what it had before.
+     */
+    if (NetworkSecurityPolicy.getInstance().isCleartextTrafficPermitted()) {
+      web.getSettings().setMixedContentMode(WebSettings.MIXED_CONTENT_ALWAYS_ALLOW);
+    }
     web.setWebViewClient(new LocalContentClient(loader, this));
     web.setWebChromeClient(new ExternalWindowClient(this));
     /*

package/dist/android.js

@@ -5,6 +5,7 @@ import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resourceDir } from './resources.js';
 import { missingReferences } from './mobile/assetCheck.js';
+import { withAndroidManifest } from './mobile/androidManifest.js';
 import { versionCodeFor } from './mobile/versionCode.js';
 import { androidToolchain, toolchainHome } from './toolchain.js';
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -61,6 +62,29 @@ export async function buildAndroid(manifest, projectDir, outDir, options = {}) {
         target: 'es2022',
         logLevel: 'warning',
     });
+    /*
+     * **The manifest is rewritten in the copy, before Gradle reads it.** The same place and the same
+     * reason as the icon below: the template is staged into `out/`, so a consumer's permissions never
+     * touch this repository's tree. See `mobile/androidManifest.ts` for what an empty request does,
+     * which is nothing at all.
+     */
+    const manifestPath = join(projectRoot, 'app', 'src', 'main', 'AndroidManifest.xml');
+    const templateXml = await readFile(manifestPath, 'utf8');
+    const withPermissions = withAndroidManifest(templateXml, manifest.android);
+    if (withPermissions !== templateXml) {
+        await writeFile(manifestPath, withPermissions, 'utf8');
+    }
+    if (manifest.android.permissions.length > 0) {
+        console.log(`[drift-package] android: permissions ${manifest.android.permissions.join(', ')}`);
+    }
+    if (manifest.android.cleartextTraffic) {
+        /*
+         * Said out loud because it is a security posture rather than a setting: the build now permits
+         * `http://` and `ws://`, and `MainActivity` reads the same flag to allow mixed content in the
+         * WebView. A consumer who did not mean it should see it in the build log.
+         */
+        console.log('[drift-package] android: cleartext traffic permitted (http:// and ws:// allowed)');
+    }
     if (manifest.icon !== null) {
         /* One PNG at one density: Android scales it for the rest, and a game that wants a full set
            supplies its own `res/` through its own build rather than through this. */

package/dist/cli.js

@@ -102,6 +102,19 @@ async function doctor(cwd, options = {}) {
         console.log(`  ${target}: signing ${signing.mode} — ${signing.reason}`);
     }
     console.log(`  splash: ${manifest.splash.show ? `the engine badge, held ${manifest.splash.minMs} ms` : 'off'}`);
+    /*
+     * **Printed the way the signing mode is, and for the same reason.** An APK's permissions are the
+     * difference between a game that can reach a relay and one whose every connection fails with
+     * nothing logged at either end, and they are invisible until somebody runs `aapt2` on the built
+     * artifact. Saying it here puts it in front of whoever is about to build.
+     */
+    if (manifest.targets.includes('android')) {
+        const asked = manifest.android.permissions;
+        console.log(`  android: permissions ${asked.length > 0 ? asked.join(', ') : 'none — the APK cannot open a socket'}`);
+        console.log(`  android: cleartext ${manifest.android.cleartextTraffic
+            ? 'permitted — http:// and ws:// are allowed, and mixed content with them'
+            : 'refused — a relay must be wss://'}`);
+    }
     /*
      * **What each target still needs, and the command that fetches it.** A `doctor` that only
      * validated a manifest would pass on a machine with no Java and no SDK, and the failure would

package/dist/manifest.d.ts

@@ -1,15 +1,3 @@
-/**
- * `drift.package.json`, parsed once and trusted afterwards.
- *
- * **Every rejection names its field.** A packaging manifest is written by hand, usually once, and
- * a wrong value surfaces at signing or at first launch on a machine the author does not have. The
- * cost of validating here is a few dozen lines; the cost of not validating is a build.
- *
- * **What is defaulted and what is not** is the only interesting decision in this file. Window size
- * and features default, because a short manifest is easier to read and a wrong window is visible
- * immediately. The id, the entry, the targets and the backend policy do not, because each of them
- * is silent when wrong: the wrong id writes saves to a directory nobody looks in.
- */
 export type WebGpuPolicy = 'prefer' | 'require' | 'off';
 export type Target = 'win-x64' | 'mac-arm64' | 'mac-x64' | 'linux-x64' | 'android' | 'ios';
 /** The two that are a phone rather than a desktop, and differ in almost every way that matters. */
@@ -40,6 +28,25 @@ export interface PackageManifest {
         readonly show: boolean;
         readonly minMs: number;
     };
+    /**
+     * What the Android build asks the platform for. Nothing, unless a game says otherwise.
+     *
+     * **`permissions` is empty by default and that default is the feature**: the manifest template
+     * declares none, so a game asks for what it needs and the asking is visible in the store listing
+     * rather than granted to every game the packager ever builds. `"INTERNET"` and
+     * `"android.permission.INTERNET"` are both accepted.
+     *
+     * **`cleartextTraffic` is false by default and is the other half of reaching a relay.** The game
+     * is served from `https://appassets.androidplatform.net`, which is a secure context, so Blink
+     * refuses `ws://` from it as mixed content whatever Android's own policy says. Setting this true
+     * sets `android:usesCleartextTraffic` *and* is what `MainActivity` reads at runtime to allow
+     * mixed content in the WebView, so the platform and the renderer cannot disagree about it. A
+     * relay on a LAN cannot hold a certificate, which is the case it exists for.
+     */
+    readonly android: {
+        readonly permissions: readonly string[];
+        readonly cleartextTraffic: boolean;
+    };
     /**
      * Who an installer says this is from.
      *

package/dist/manifest.js

@@ -1,3 +1,16 @@
+/**
+ * `drift.package.json`, parsed once and trusted afterwards.
+ *
+ * **Every rejection names its field.** A packaging manifest is written by hand, usually once, and
+ * a wrong value surfaces at signing or at first launch on a machine the author does not have. The
+ * cost of validating here is a few dozen lines; the cost of not validating is a build.
+ *
+ * **What is defaulted and what is not** is the only interesting decision in this file. Window size
+ * and features default, because a short manifest is easier to read and a wrong window is visible
+ * immediately. The id, the entry, the targets and the backend policy do not, because each of them
+ * is silent when wrong: the wrong id writes saves to a directory nobody looks in.
+ */
+import { checkPermission, fullPermissionName } from './mobile/androidManifest.js';
 /** The two that are a phone rather than a desktop, and differ in almost every way that matters. */
 export const MOBILE_TARGETS = ['android', 'ios'];
 const POLICIES = ['prefer', 'require', 'off'];
@@ -54,6 +67,18 @@ export function parseManifest(raw) {
     const featuresRaw = (source.features ?? {});
     const steamRaw = (source.steam ?? {});
     const splashRaw = (source.splash ?? {});
+    const androidRaw = (source.android ?? {});
+    const permissionsRaw = androidRaw.permissions ?? [];
+    if (!Array.isArray(permissionsRaw)) {
+        throw new Error('drift.package.json: "android.permissions" must be an array of strings');
+    }
+    const permissions = permissionsRaw.map((entry) => {
+        if (typeof entry !== 'string') {
+            throw new Error(`drift.package.json: "android.permissions" holds ${typeof entry}, expected strings`);
+        }
+        checkPermission(entry);
+        return fullPermissionName(entry);
+    });
     const appId = steamRaw.appId;
     return {
         id,
@@ -81,6 +106,10 @@ export function parseManifest(raw) {
             ? source.publisher
             : (id.split('.')[1] ?? id),
         icon: typeof source.icon === 'string' && source.icon.length > 0 ? source.icon : null,
+        android: {
+            permissions,
+            cleartextTraffic: androidRaw.cleartextTraffic === true,
+        },
         splash: {
             show: splashRaw.show !== false,
             minMs: typeof splashRaw.minMs === 'number'

package/dist/mobile/androidManifest.d.ts

@@ -0,0 +1,41 @@
+/** What a game asks the Android manifest for, written into the copied template before Gradle runs. */
+/** The `android` block of `drift.package.json`, already parsed. See `manifest.ts`. */
+export interface AndroidOptions {
+    /** Fully-qualified permission names, in the order they were asked for. */
+    readonly permissions: readonly string[];
+    /** Whether the app may open `http://` and `ws://` at all. */
+    readonly cleartextTraffic: boolean;
+}
+/** Nothing asked for: what every build got before this existed, and still gets. */
+export declare const NO_ANDROID_OPTIONS: AndroidOptions;
+/**
+ * `INTERNET` and `android.permission.INTERNET` are the same thing, written two ways.
+ *
+ * A consumer writes the short name because that is what the permission is called everywhere except
+ * in the XML, and the long one because that is what the XML says. Both are accepted and the long
+ * form is what is written, since a short name in the manifest is a permission Android does not
+ * recognise and silently does not grant — the same silence this whole field exists to end.
+ */
+export declare function fullPermissionName(name: string): string;
+/** Refuse a name that cannot go into the XML, at parse time where a consumer can fix it. */
+export declare function checkPermission(name: string): void;
+/**
+ * The template manifest with a game's permissions in it, and its cleartext policy set.
+ *
+ * **Written into the copy, not into the template**, the way the icon already is: `buildAndroid`
+ * stages `packages/package/android/` into `out/android/project` and edits it there, so this
+ * repository's own tree is never the thing a consumer's build modifies.
+ *
+ * **Why this exists at all.** The template declares one activity and no permissions, deliberately:
+ * a game that needs the network should ask for it, and the asking should be visible in the store
+ * listing rather than granted to everybody by default. That default was right and there was no way
+ * to depart from it — the template is copied wholesale, none of the eight `-Pdrift*` properties
+ * reaches the manifest, and the only door was `--resources`, which moves the desktop shell and the
+ * iOS spec along with the Gradle project. So an online game shipped an APK whose process is not
+ * permitted to open a socket: every connection fails, the relay logs nothing because no packet
+ * leaves, and neither end can say why. Reported from outside exactly that way.
+ *
+ * Returns the source unchanged when nothing is asked for, which is what keeps a game that has never
+ * heard of this byte-identical to the build before it.
+ */
+export declare function withAndroidManifest(xml: string, options: AndroidOptions): string;

package/dist/mobile/androidManifest.js

@@ -0,0 +1,92 @@
+/** What a game asks the Android manifest for, written into the copied template before Gradle runs. */
+/** Nothing asked for: what every build got before this existed, and still gets. */
+export const NO_ANDROID_OPTIONS = Object.freeze({
+    permissions: Object.freeze([]),
+    cleartextTraffic: false,
+});
+/**
+ * `INTERNET` and `android.permission.INTERNET` are the same thing, written two ways.
+ *
+ * A consumer writes the short name because that is what the permission is called everywhere except
+ * in the XML, and the long one because that is what the XML says. Both are accepted and the long
+ * form is what is written, since a short name in the manifest is a permission Android does not
+ * recognise and silently does not grant — the same silence this whole field exists to end.
+ */
+export function fullPermissionName(name) {
+    return name.includes('.') ? name : `android.permission.${name}`;
+}
+/**
+ * What a permission name may contain.
+ *
+ * Checked because the name is interpolated into an XML attribute: a quote or a bracket in it ends
+ * the attribute and produces a manifest that either fails to parse or parses into something nobody
+ * wrote. Android's own names are dotted upper snake case, and a custom one from a library follows
+ * the same shape.
+ */
+const PERMISSION = /^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)*$/;
+/** Refuse a name that cannot go into the XML, at parse time where a consumer can fix it. */
+export function checkPermission(name) {
+    if (!PERMISSION.test(name)) {
+        throw new Error(`drift.package.json: "${name}" is not a permission name — expected something like ` +
+            `"INTERNET" or "android.permission.INTERNET", letters, digits, underscores and dots only.`);
+    }
+}
+/**
+ * The template manifest with a game's permissions in it, and its cleartext policy set.
+ *
+ * **Written into the copy, not into the template**, the way the icon already is: `buildAndroid`
+ * stages `packages/package/android/` into `out/android/project` and edits it there, so this
+ * repository's own tree is never the thing a consumer's build modifies.
+ *
+ * **Why this exists at all.** The template declares one activity and no permissions, deliberately:
+ * a game that needs the network should ask for it, and the asking should be visible in the store
+ * listing rather than granted to everybody by default. That default was right and there was no way
+ * to depart from it — the template is copied wholesale, none of the eight `-Pdrift*` properties
+ * reaches the manifest, and the only door was `--resources`, which moves the desktop shell and the
+ * iOS spec along with the Gradle project. So an online game shipped an APK whose process is not
+ * permitted to open a socket: every connection fails, the relay logs nothing because no packet
+ * leaves, and neither end can say why. Reported from outside exactly that way.
+ *
+ * Returns the source unchanged when nothing is asked for, which is what keeps a game that has never
+ * heard of this byte-identical to the build before it.
+ */
+export function withAndroidManifest(xml, options) {
+    const permissions = options.permissions.map(fullPermissionName);
+    let out = xml;
+    if (permissions.length > 0) {
+        /* The element, not any tag that starts with its name: `[\s>]` is what separates
+           `<application` from an `<applicationInfo` somebody adds later. */
+        const at = out.search(/<application[\s>]/);
+        if (at === -1) {
+            throw new Error('the Android manifest template has no <application> element to precede');
+        }
+        /*
+         * Before `<application>` and at its indentation. The schema requires `uses-permission` to be a
+         * child of `manifest` rather than of `application`, and Android's own tooling orders them
+         * first; `aapt2` accepts either order, and a reader of the built manifest should not have to
+         * hunt for them.
+         */
+        const indent = indentOf(out, at);
+        const block = permissions
+            .map((name) => `${indent}<uses-permission android:name="${name}" />`)
+            .join('\n');
+        out = `${out.slice(0, at - indent.length)}${block}\n\n${indent}${out.slice(at)}`;
+    }
+    /*
+     * The attribute is rewritten rather than appended, because the template already carries it with
+     * `false`. Two of them is a build error, and a second one appended after the first is the shape
+     * that produces it.
+     */
+    const cleartext = options.cleartextTraffic ? 'true' : 'false';
+    const replaced = out.replace(/android:usesCleartextTraffic="(?:true|false)"/, `android:usesCleartextTraffic="${cleartext}"`);
+    if (replaced === out && options.cleartextTraffic) {
+        throw new Error('the Android manifest template no longer declares android:usesCleartextTraffic, so asking ' +
+            'for cleartext traffic would do nothing');
+    }
+    return replaced;
+}
+/** The whitespace at the start of the line `at` falls on, so an inserted element lines up. */
+function indentOf(xml, at) {
+    const lineStart = xml.lastIndexOf('\n', at) + 1;
+    return xml.slice(lineStart, at);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/package",
-  "version": "3.61.2",
+  "version": "3.62.0",
   "description": "Builds an installable application from a game built on the engine",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,7 +35,7 @@
     "drift-package": "bin/drift-package.mjs"
   },
   "peerDependencies": {
-    "@driftengine/core": "3.61.2",
+    "@driftengine/core": "3.62.0",
     "steamworks.js": ">=0.4.0"
   },
   "dependencies": {
@@ -74,5 +74,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "prepack": "node ../../scripts/build.mjs @driftengine/package"
   }
 }

package/src/android.ts

@@ -8,6 +8,7 @@ import type { PackageManifest } from './manifest.ts';
 import { resourceDir } from './resources.ts';
 import type { ResourceOptions } from './resources.ts';
 import { missingReferences } from './mobile/assetCheck.ts';
+import { withAndroidManifest } from './mobile/androidManifest.ts';
 import { versionCodeFor } from './mobile/versionCode.ts';
 import { androidToolchain, toolchainHome } from './toolchain.ts';
 
@@ -77,6 +78,30 @@ export async function buildAndroid(
     logLevel: 'warning',
   });
 
+  /*
+   * **The manifest is rewritten in the copy, before Gradle reads it.** The same place and the same
+   * reason as the icon below: the template is staged into `out/`, so a consumer's permissions never
+   * touch this repository's tree. See `mobile/androidManifest.ts` for what an empty request does,
+   * which is nothing at all.
+   */
+  const manifestPath = join(projectRoot, 'app', 'src', 'main', 'AndroidManifest.xml');
+  const templateXml = await readFile(manifestPath, 'utf8');
+  const withPermissions = withAndroidManifest(templateXml, manifest.android);
+  if (withPermissions !== templateXml) {
+    await writeFile(manifestPath, withPermissions, 'utf8');
+  }
+  if (manifest.android.permissions.length > 0) {
+    console.log(`[drift-package] android: permissions ${manifest.android.permissions.join(', ')}`);
+  }
+  if (manifest.android.cleartextTraffic) {
+    /*
+     * Said out loud because it is a security posture rather than a setting: the build now permits
+     * `http://` and `ws://`, and `MainActivity` reads the same flag to allow mixed content in the
+     * WebView. A consumer who did not mean it should see it in the build log.
+     */
+    console.log('[drift-package] android: cleartext traffic permitted (http:// and ws:// allowed)');
+  }
+
   if (manifest.icon !== null) {
     /* One PNG at one density: Android scales it for the rest, and a game that wants a full set
        supplies its own `res/` through its own build rather than through this. */

package/src/cli.ts

@@ -106,6 +106,25 @@ async function doctor(cwd: string, options: ResourceOptions = {}): Promise<Packa
   console.log(
     `  splash: ${manifest.splash.show ? `the engine badge, held ${manifest.splash.minMs} ms` : 'off'}`,
   );
+  /*
+   * **Printed the way the signing mode is, and for the same reason.** An APK's permissions are the
+   * difference between a game that can reach a relay and one whose every connection fails with
+   * nothing logged at either end, and they are invisible until somebody runs `aapt2` on the built
+   * artifact. Saying it here puts it in front of whoever is about to build.
+   */
+  if (manifest.targets.includes('android')) {
+    const asked = manifest.android.permissions;
+    console.log(
+      `  android: permissions ${asked.length > 0 ? asked.join(', ') : 'none — the APK cannot open a socket'}`,
+    );
+    console.log(
+      `  android: cleartext ${
+        manifest.android.cleartextTraffic
+          ? 'permitted — http:// and ws:// are allowed, and mixed content with them'
+          : 'refused — a relay must be wss://'
+      }`,
+    );
+  }
 
   /*
    * **What each target still needs, and the command that fetches it.** A `doctor` that only

package/src/manifest.ts

@@ -10,6 +10,8 @@
  * immediately. The id, the entry, the targets and the backend policy do not, because each of them
  * is silent when wrong: the wrong id writes saves to a directory nobody looks in.
  */
+import { checkPermission, fullPermissionName } from './mobile/androidManifest.ts';
+
 export type WebGpuPolicy = 'prefer' | 'require' | 'off';
 export type Target = 'win-x64' | 'mac-arm64' | 'mac-x64' | 'linux-x64' | 'android' | 'ios';
 
@@ -54,6 +56,25 @@ export interface PackageManifest {
   readonly targets: readonly Target[];
   readonly steam: { readonly appId: number | null };
   readonly splash: { readonly show: boolean; readonly minMs: number };
+  /**
+   * What the Android build asks the platform for. Nothing, unless a game says otherwise.
+   *
+   * **`permissions` is empty by default and that default is the feature**: the manifest template
+   * declares none, so a game asks for what it needs and the asking is visible in the store listing
+   * rather than granted to every game the packager ever builds. `"INTERNET"` and
+   * `"android.permission.INTERNET"` are both accepted.
+   *
+   * **`cleartextTraffic` is false by default and is the other half of reaching a relay.** The game
+   * is served from `https://appassets.androidplatform.net`, which is a secure context, so Blink
+   * refuses `ws://` from it as mixed content whatever Android's own policy says. Setting this true
+   * sets `android:usesCleartextTraffic` *and* is what `MainActivity` reads at runtime to allow
+   * mixed content in the WebView, so the platform and the renderer cannot disagree about it. A
+   * relay on a LAN cannot hold a certificate, which is the case it exists for.
+   */
+  readonly android: {
+    readonly permissions: readonly string[];
+    readonly cleartextTraffic: boolean;
+  };
   /**
    * Who an installer says this is from.
    *
@@ -116,6 +137,20 @@ export function parseManifest(raw: unknown): PackageManifest {
   const featuresRaw = (source.features ?? {}) as Record<string, unknown>;
   const steamRaw = (source.steam ?? {}) as Record<string, unknown>;
   const splashRaw = (source.splash ?? {}) as Record<string, unknown>;
+  const androidRaw = (source.android ?? {}) as Record<string, unknown>;
+  const permissionsRaw = androidRaw.permissions ?? [];
+  if (!Array.isArray(permissionsRaw)) {
+    throw new Error('drift.package.json: "android.permissions" must be an array of strings');
+  }
+  const permissions = permissionsRaw.map((entry) => {
+    if (typeof entry !== 'string') {
+      throw new Error(
+        `drift.package.json: "android.permissions" holds ${typeof entry}, expected strings`,
+      );
+    }
+    checkPermission(entry);
+    return fullPermissionName(entry);
+  });
   const appId = steamRaw.appId;
 
   return {
@@ -146,6 +181,10 @@ export function parseManifest(raw: unknown): PackageManifest {
         ? source.publisher
         : (id.split('.')[1] ?? id),
     icon: typeof source.icon === 'string' && source.icon.length > 0 ? source.icon : null,
+    android: {
+      permissions,
+      cleartextTraffic: androidRaw.cleartextTraffic === true,
+    },
     splash: {
       show: splashRaw.show !== false,
       minMs:

package/src/mobile/androidManifest.ts

@@ -0,0 +1,115 @@
+/** What a game asks the Android manifest for, written into the copied template before Gradle runs. */
+
+/** The `android` block of `drift.package.json`, already parsed. See `manifest.ts`. */
+export interface AndroidOptions {
+  /** Fully-qualified permission names, in the order they were asked for. */
+  readonly permissions: readonly string[];
+  /** Whether the app may open `http://` and `ws://` at all. */
+  readonly cleartextTraffic: boolean;
+}
+
+/** Nothing asked for: what every build got before this existed, and still gets. */
+export const NO_ANDROID_OPTIONS: AndroidOptions = Object.freeze({
+  permissions: Object.freeze([]) as readonly string[],
+  cleartextTraffic: false,
+});
+
+/**
+ * `INTERNET` and `android.permission.INTERNET` are the same thing, written two ways.
+ *
+ * A consumer writes the short name because that is what the permission is called everywhere except
+ * in the XML, and the long one because that is what the XML says. Both are accepted and the long
+ * form is what is written, since a short name in the manifest is a permission Android does not
+ * recognise and silently does not grant — the same silence this whole field exists to end.
+ */
+export function fullPermissionName(name: string): string {
+  return name.includes('.') ? name : `android.permission.${name}`;
+}
+
+/**
+ * What a permission name may contain.
+ *
+ * Checked because the name is interpolated into an XML attribute: a quote or a bracket in it ends
+ * the attribute and produces a manifest that either fails to parse or parses into something nobody
+ * wrote. Android's own names are dotted upper snake case, and a custom one from a library follows
+ * the same shape.
+ */
+const PERMISSION = /^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)*$/;
+
+/** Refuse a name that cannot go into the XML, at parse time where a consumer can fix it. */
+export function checkPermission(name: string): void {
+  if (!PERMISSION.test(name)) {
+    throw new Error(
+      `drift.package.json: "${name}" is not a permission name — expected something like ` +
+        `"INTERNET" or "android.permission.INTERNET", letters, digits, underscores and dots only.`,
+    );
+  }
+}
+
+/**
+ * The template manifest with a game's permissions in it, and its cleartext policy set.
+ *
+ * **Written into the copy, not into the template**, the way the icon already is: `buildAndroid`
+ * stages `packages/package/android/` into `out/android/project` and edits it there, so this
+ * repository's own tree is never the thing a consumer's build modifies.
+ *
+ * **Why this exists at all.** The template declares one activity and no permissions, deliberately:
+ * a game that needs the network should ask for it, and the asking should be visible in the store
+ * listing rather than granted to everybody by default. That default was right and there was no way
+ * to depart from it — the template is copied wholesale, none of the eight `-Pdrift*` properties
+ * reaches the manifest, and the only door was `--resources`, which moves the desktop shell and the
+ * iOS spec along with the Gradle project. So an online game shipped an APK whose process is not
+ * permitted to open a socket: every connection fails, the relay logs nothing because no packet
+ * leaves, and neither end can say why. Reported from outside exactly that way.
+ *
+ * Returns the source unchanged when nothing is asked for, which is what keeps a game that has never
+ * heard of this byte-identical to the build before it.
+ */
+export function withAndroidManifest(xml: string, options: AndroidOptions): string {
+  const permissions = options.permissions.map(fullPermissionName);
+  let out = xml;
+
+  if (permissions.length > 0) {
+    /* The element, not any tag that starts with its name: `[\s>]` is what separates
+       `<application` from an `<applicationInfo` somebody adds later. */
+    const at = out.search(/<application[\s>]/);
+    if (at === -1) {
+      throw new Error('the Android manifest template has no <application> element to precede');
+    }
+    /*
+     * Before `<application>` and at its indentation. The schema requires `uses-permission` to be a
+     * child of `manifest` rather than of `application`, and Android's own tooling orders them
+     * first; `aapt2` accepts either order, and a reader of the built manifest should not have to
+     * hunt for them.
+     */
+    const indent = indentOf(out, at);
+    const block = permissions
+      .map((name) => `${indent}<uses-permission android:name="${name}" />`)
+      .join('\n');
+    out = `${out.slice(0, at - indent.length)}${block}\n\n${indent}${out.slice(at)}`;
+  }
+
+  /*
+   * The attribute is rewritten rather than appended, because the template already carries it with
+   * `false`. Two of them is a build error, and a second one appended after the first is the shape
+   * that produces it.
+   */
+  const cleartext = options.cleartextTraffic ? 'true' : 'false';
+  const replaced = out.replace(
+    /android:usesCleartextTraffic="(?:true|false)"/,
+    `android:usesCleartextTraffic="${cleartext}"`,
+  );
+  if (replaced === out && options.cleartextTraffic) {
+    throw new Error(
+      'the Android manifest template no longer declares android:usesCleartextTraffic, so asking ' +
+        'for cleartext traffic would do nothing',
+    );
+  }
+  return replaced;
+}
+
+/** The whitespace at the start of the line `at` falls on, so an inserted element lines up. */
+function indentOf(xml: string, at: number): string {
+  const lineStart = xml.lastIndexOf('\n', at) + 1;
+  return xml.slice(lineStart, at);
+}