docs(android): spec Android App Links (assetlinks.json + build-time host)

Promote APP_LINKS.md from a deferred design note into an implementation spec
matching the website `feat/mobile-app-links` and android `feat/app-links`
branches: the server-side `/.well-known/assetlinks.json` route + `mobile_app_links_enabled`
toggle + additive redirect-allowlist entry, and the app-side `autoVerify`
intent-filter driven by a build-time `appLinkHost` (a single multi-tenant APK
cannot autoVerify open-ended shard domains, so App Links are a white-label /
first-party build opt-in; the custom scheme stays the permanent fallback).

Update PLAN.md §9 (M9 follow-up) and the §14 open item, and the redirect-URI
allowlist section of website/BACKEND_DESIGN.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
This commit is contained in:
2026-07-20 18:37:04 -05:00
parent 44544dc3bc
commit 752793f6c3
3 changed files with 183 additions and 70 deletions

View File

@@ -794,8 +794,14 @@ push, and Play (M6M8) follow the designed app.
`code_verifier`/`code_challenge` + `state`; open the Custom Tab at `/auth/mobile/sso/start`;
verify `state` on the callback; `POST …/exchange`; store the returned pair in the existing
`TokenStore` (M3). No new token-storage or refresh code — it feeds the M3 session machinery.
- **Deferred:** App Links / per-shard `assetlinks.json` / pairing — custom scheme only for now
([`APP_LINKS.md`](./APP_LINKS.md)).
- **Follow-up — App Links (opt-in hardening on top of Part 2):** a website `GET
/.well-known/assetlinks.json` route behind the `mobile_app_links_enabled` admin toggle, a
self-origin HTTPS entry added to the redirect-URI allowlist when enabled, and an app-side
`autoVerify` intent-filter for `https://<host>/mobile/callback` driven by a **build-time**
`appLinkHost` (a single multi-tenant APK cannot autoVerify open-ended shard domains, so the
generic build stays custom-scheme; white-label/first-party builds bake one host). The custom
scheme remains the permanent fallback on every build. Full spec + rollout in
[`APP_LINKS.md`](./APP_LINKS.md).
---
@@ -915,7 +921,12 @@ it is a UX convenience, not a v1 requirement — deferred at M3, descoped at M6;
`runicgateway.app` domain (needed for a verified app-link host and a matching package namespace). Also
the fixed launcher name (baked at build even though in-app branding is per-shard — one APK, any shard).
Since SSO/invite/reset are website-handled, the app mostly *opens* website URLs rather than needing its
own verified app links — confirm whether any deep-link-back is wanted at all for v1.
own verified app links. **App Links resolved (M9 follow-up):** the SSO callback is the one place a
verified deep-link-back helps; the server side (`assetlinks.json` + toggle) ships for any shard, but
the app-side `autoVerify` needs a **literal build-time host**, so it is a white-label/first-party build
opt-in (`-PappLinkHost=<host>`) — the generic multi-tenant build stays custom-scheme. A canonical
`runicgateway.app` relay host, if secured, would let the generic build autoVerify one central domain.
See [`APP_LINKS.md`](./APP_LINKS.md).
- ntfy: exact upstream image + pinned tag (Part-1 landed the compose service — confirm the tag), and
its reverse-proxy hostname/path. The hostname must land in `NTFY_ALLOWED_ORIGINS` before M7 Part 2 is
end-to-end testable (the app registers an endpoint on that origin; the SSRF guard rejects others). No