Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

fix(assetlinks): list every certificate that can sign the app, so a Play install keeps full screen

nirholas87e93cc0527c
diff --git a/solana-mobile/scripts/assetlinks.mjs b/solana-mobile/scripts/assetlinks.mjs
new file mode 100644
index 000000000..c3753eaf3
--- /dev/null
+++ b/solana-mobile/scripts/assetlinks.mjs
@@ -0,0 +1,118 @@
+// Build the Digital Asset Links statement list for the three.ws TWA.
+//
+// Why this is not a one-liner inside build-apk.sh: the same app is distributed
+// through more than one channel, and each channel can sign it with a DIFFERENT
+// certificate.
+//
+// Solana dApp Store + direct download -> signed with our own release key
+// (solana-mobile/android.keystore).
+// Google Play -> Play App Signing is mandatory for
+// new apps, so Google re-signs the
+// upload with ITS key. The installed
+// app then presents Google's
+// certificate, not ours.
+//
+// Digital Asset Links verifies the certificate of the app that is actually
+// installed. A statement file carrying only our key means every Play install
+// fails verification and opens three.ws with the Chrome address bar visible
+// instead of full screen, while the dApp Store build stays correct. That is a
+// channel-specific failure nobody sees in local QA.
+//
+// So the file has to list every certificate the app can legitimately be signed
+// with. The extra ones are declared in twa/extra-fingerprints.json, checked
+// into git and reviewed there, rather than merged out of whatever the last run
+// happened to leave on disk. Merging from disk is how the orphaned key from
+// the lost 2026-08-10 keystore survived a rotation it was supposed to die in.
+
+const HEX_PAIR = /^[0-9A-F]{2}(:[0-9A-F]{2}){31}$/;
+
+/** Normalize a keytool/Play Console fingerprint to upper-case colon-separated hex. */
+export function normalizeFingerprint(raw) {
+ const cleaned = String(raw ?? '').trim().replace(/\s+/g, '').toUpperCase();
+ if (!cleaned) return null;
+ const hex = cleaned.replace(/:/g, '');
+ if (!/^[0-9A-F]{64}$/.test(hex)) return null;
+ return hex.match(/.{2}/g).join(':');
+}
+
+/**
+ * @param {{ packageId: string, fingerprints: string[] }} input
+ * @returns {Array<object>} the assetlinks.json statement list
+ */
+export function buildAssetLinks({ packageId, fingerprints }) {
+ if (!packageId) throw new Error('packageId is required');
+
+ const seen = new Set();
+ const normalized = [];
+ for (const raw of fingerprints ?? []) {
+ const fp = normalizeFingerprint(raw);
+ if (!fp) throw new Error(`not a SHA-256 certificate fingerprint: ${JSON.stringify(raw)}`);
+ if (seen.has(fp)) continue;
+ seen.add(fp);
+ normalized.push(fp);
+ }
+ if (!normalized.length) throw new Error('at least one certificate fingerprint is required');
+ if (!normalized.every((fp) => HEX_PAIR.test(fp))) throw new Error('fingerprint normalization failed');
+
+ return [
+ {
+ relation: ['delegate_permission/common.handle_all_urls', 'delegate_permission/common.use_as_origin'],
+ target: {
+ namespace: 'android_app',
+ package_name: packageId,
+ sha256_cert_fingerprints: normalized,
+ },
+ },
+ ];
+}
+
+/** Read the checked-in extra certificates (Play App Signing and any future channel). */
+export function extraFingerprintsFrom(config) {
+ if (!config) return [];
+ const list = Array.isArray(config) ? config : config.fingerprints;
+ if (!Array.isArray(list)) return [];
+ return list
+ .map((e) => (typeof e === 'string' ? e : e?.sha256))
+ .filter((v) => typeof v === 'string' && v.trim().length > 0);
+}
+
+// --- CLI ---------------------------------------------------------------------
+// node scripts/assetlinks.mjs --package ws.three.app --fingerprint <SHA256> \
+// [--extra <file>] [--out <path>]
+// Prints the statement list to stdout, or writes it to --out.
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+ const { readFileSync, writeFileSync, mkdirSync } = await import('node:fs');
+ const { dirname, resolve } = await import('node:path');
+
+ const argv = process.argv.slice(2);
+ const flag = (name) => {
+ const i = argv.indexOf(`--${name}`);
+ return i === -1 ? undefined : argv[i + 1];
+ };
+
+ const here = dirname(new URL(import.meta.url).pathname);
+ const extraFile = resolve(flag('extra') ?? `${here}/../twa/extra-fingerprints.json`);
+ const packageId = flag('package') ?? JSON.parse(readFileSync(resolve(`${here}/../twa/twa-manifest.json`), 'utf8')).packageId;
+
+ let extraConfig = null;
+ try {
+ extraConfig = JSON.parse(readFileSync(extraFile, 'utf8'));
+ } catch (err) {
+ if (err.code !== 'ENOENT') throw err;
+ }
+ const extras = extraFingerprintsFrom(extraConfig);
+
+ const links = buildAssetLinks({ packageId, fingerprints: [flag('fingerprint'), ...extras].filter(Boolean) });
+ const body = JSON.stringify(links, null, 2) + '\n';
+
+ const out = flag('out');
+ if (out) {
+ mkdirSync(dirname(resolve(out)), { recursive: true });
+ writeFileSync(resolve(out), body);
+ const count = links[0].target.sha256_cert_fingerprints.length;
+ process.stderr.write(`[assetlinks] wrote ${out} with ${count} certificate fingerprint(s)\n`);
+ } else {
+ process.stdout.write(body);
+ }
+}
diff --git a/solana-mobile/scripts/build-apk.sh b/solana-mobile/scripts/build-apk.sh
index bfe93f7b3..08bdc0619 100755
--- a/solana-mobile/scripts/build-apk.sh
+++ b/solana-mobile/scripts/build-apk.sh
@@ -88,22 +88,11 @@ fi
echo "[build-apk] SHA-256: $FINGERPRINT"
-mkdir -p "$(dirname "$ASSETLINKS_OUT")"
-PACKAGE_ID=$(node -e "console.log(require('./twa/twa-manifest.json').packageId)")
-node <<NODE > "$ASSETLINKS_OUT"
-const links = [{
- relation: [
- 'delegate_permission/common.handle_all_urls',
- 'delegate_permission/common.use_as_origin',
- ],
- target: {
- namespace: 'android_app',
- package_name: '${PACKAGE_ID}',
- sha256_cert_fingerprints: ['${FINGERPRINT}'],
- },
-}];
-process.stdout.write(JSON.stringify(links, null, 2) + '\n');
-NODE
+# Every certificate the app can legitimately be signed with goes in the file,
+# not just this keystore: Play App Signing re-signs the upload with Google's
+# key, and a Play install presenting an unlisted certificate loses full-screen
+# mode. Extra certificates are declared in twa/extra-fingerprints.json.
+node scripts/assetlinks.mjs --fingerprint "$FINGERPRINT" --out "$ASSETLINKS_OUT"
echo "[build-apk] wrote assetlinks.json → $ASSETLINKS_OUT"
diff --git a/solana-mobile/scripts/update-assetlinks.sh b/solana-mobile/scripts/update-assetlinks.sh
index 4082d052b..8f12dc074 100755
--- a/solana-mobile/scripts/update-assetlinks.sh
+++ b/solana-mobile/scripts/update-assetlinks.sh
@@ -32,21 +32,10 @@ if [[ -z "$FINGERPRINT" ]]; then
echo "[update-assetlinks] failed to extract SHA-256" >&2; exit 1
fi
-mkdir -p "$(dirname "$ASSETLINKS_OUT")"
-node <<NODE > "$ASSETLINKS_OUT"
-const links = [{
- relation: [
- 'delegate_permission/common.handle_all_urls',
- 'delegate_permission/common.use_as_origin',
- ],
- target: {
- namespace: 'android_app',
- package_name: '${PACKAGE_ID}',
- sha256_cert_fingerprints: ['${FINGERPRINT}'],
- },
-}];
-process.stdout.write(JSON.stringify(links, null, 2) + '\n');
-NODE
+# Includes every certificate from twa/extra-fingerprints.json (Play App
+# Signing) alongside this keystore's, so refreshing one channel's key never
+# silently un-verifies another channel's installs.
+node scripts/assetlinks.mjs --package "$PACKAGE_ID" --fingerprint "$FINGERPRINT" --out "$ASSETLINKS_OUT"
echo "[update-assetlinks] wrote $ASSETLINKS_OUT (SHA-256: $FINGERPRINT)"
echo "[update-assetlinks] deploy three.ws and verify https://three.ws/.well-known/assetlinks.json"
diff --git a/solana-mobile/twa/extra-fingerprints.json b/solana-mobile/twa/extra-fingerprints.json
new file mode 100644
index 000000000..06793f152
--- /dev/null
+++ b/solana-mobile/twa/extra-fingerprints.json
@@ -0,0 +1,4 @@
+{
+ "$comment": "Additional SHA-256 signing certificates that are allowed to act as ws.three.app, merged into public/.well-known/assetlinks.json alongside the release keystore's own fingerprint by solana-mobile/scripts/assetlinks.mjs. Google Play re-signs every new app with its own Play App Signing key, so a Play release presents a certificate that is NOT ours; without its fingerprint here, every Play install loses full-screen mode and shows the Chrome address bar. Copy the value from Play Console > Test and release > Setup > App integrity > App signing key certificate (SHA-256). Keep the list minimal: an entry here is a key that is trusted to be three.ws, and a rotated-out key must be DELETED, not left behind.",
+ "fingerprints": []
+}
diff --git a/tests/solana-mobile-assetlinks.test.js b/tests/solana-mobile-assetlinks.test.js
new file mode 100644
index 000000000..1adebb68c
--- /dev/null
+++ b/tests/solana-mobile-assetlinks.test.js
@@ -0,0 +1,88 @@
+// Coverage for solana-mobile/scripts/assetlinks.mjs, the Digital Asset Links
+// statement builder shared by build-apk.sh and update-assetlinks.sh.
+//
+// The load-bearing property: the file lists EVERY certificate the app can be
+// signed with. three.ws ships through channels that sign differently (our own
+// release key for the Solana dApp Store and direct download, Google's Play App
+// Signing key for Play), and a statement file missing one of them costs that
+// channel full-screen mode with no local symptom.
+
+import { describe, it, expect } from 'vitest';
+import { buildAssetLinks, normalizeFingerprint, extraFingerprintsFrom } from '../solana-mobile/scripts/assetlinks.mjs';
+
+const RELEASE = '98:0A:1A:AB:A3:ED:28:D6:3D:06:69:86:7F:9A:C1:4D:EC:05:F7:78:6D:3A:30:0F:84:00:4D:E8:55:11:13:D7';
+const PLAY = 'AB:CD:' + '11:'.repeat(29) + '22';
+
+describe('normalizeFingerprint', () => {
+ it('accepts keytool output as-is', () => {
+ expect(normalizeFingerprint(RELEASE)).toBe(RELEASE);
+ });
+
+ it('upper-cases and re-inserts colons, so a Play Console paste round-trips', () => {
+ expect(normalizeFingerprint(RELEASE.replace(/:/g, '').toLowerCase())).toBe(RELEASE);
+ });
+
+ it('tolerates surrounding whitespace from a copy/paste', () => {
+ expect(normalizeFingerprint(` ${RELEASE}\n`)).toBe(RELEASE);
+ });
+
+ it('rejects anything that is not 32 hex bytes', () => {
+ expect(normalizeFingerprint('')).toBeNull();
+ expect(normalizeFingerprint(null)).toBeNull();
+ expect(normalizeFingerprint('DE:AD:BE:EF')).toBeNull();
+ expect(normalizeFingerprint(RELEASE + ':00')).toBeNull();
+ expect(normalizeFingerprint('ZZ'.repeat(32))).toBeNull();
+ });
+});
+
+describe('buildAssetLinks', () => {
+ it('emits both relations Chrome needs for a TWA', () => {
+ const [stmt] = buildAssetLinks({ packageId: 'ws.three.app', fingerprints: [RELEASE] });
+ expect(stmt.relation).toEqual([
+ 'delegate_permission/common.handle_all_urls',
+ 'delegate_permission/common.use_as_origin',
+ ]);
+ expect(stmt.target).toMatchObject({ namespace: 'android_app', package_name: 'ws.three.app' });
+ });
+
+ it('carries every channel certificate, not just the first', () => {
+ const [stmt] = buildAssetLinks({ packageId: 'ws.three.app', fingerprints: [RELEASE, PLAY] });
+ expect(stmt.target.sha256_cert_fingerprints).toEqual([RELEASE, PLAY]);
+ });
+
+ it('de-duplicates a certificate declared twice in different casing', () => {
+ const [stmt] = buildAssetLinks({
+ packageId: 'ws.three.app',
+ fingerprints: [RELEASE, RELEASE.toLowerCase(), RELEASE.replace(/:/g, '')],
+ });
+ expect(stmt.target.sha256_cert_fingerprints).toEqual([RELEASE]);
+ });
+
+ it('refuses to write a statement file with no certificate', () => {
+ expect(() => buildAssetLinks({ packageId: 'ws.three.app', fingerprints: [] })).toThrow(/at least one/);
+ });
+
+ it('refuses a malformed fingerprint rather than emitting one Google will not match', () => {
+ expect(() => buildAssetLinks({ packageId: 'ws.three.app', fingerprints: ['nope'] })).toThrow(/not a SHA-256/);
+ });
+
+ it('requires a package id', () => {
+ expect(() => buildAssetLinks({ packageId: '', fingerprints: [RELEASE] })).toThrow(/packageId/);
+ });
+});
+
+describe('extraFingerprintsFrom', () => {
+ it('reads the checked-in config shape', () => {
+ expect(extraFingerprintsFrom({ $comment: 'x', fingerprints: [PLAY] })).toEqual([PLAY]);
+ });
+
+ it('accepts annotated entries so a key can carry its channel note', () => {
+ expect(extraFingerprintsFrom({ fingerprints: [{ channel: 'play', sha256: PLAY }] })).toEqual([PLAY]);
+ });
+
+ it('treats a missing or empty config as no extra certificates', () => {
+ expect(extraFingerprintsFrom(null)).toEqual([]);
+ expect(extraFingerprintsFrom({})).toEqual([]);
+ expect(extraFingerprintsFrom({ fingerprints: [] })).toEqual([]);
+ });
+});