Skip to content

Commit 4ec1505

Browse files
authored
[Android] Add breaking change page for hardened entrypoint and cached engine Intent arguments (#13645)
_Description of what this PR is changing or adding, and why:_ Adds breaking change/migration guide for security improvements made to entrypoint and cached engine `Intent` arguments for the Flutter Android embedding. _Issues fixed by this PR (if any):_ flutter/flutter#190452 and flutter/flutter#190450 _PRs or commits this PR depends on (if any):_ flutter/flutter#190249 (merged) ## Presubmit checklist - [x] If you are unwilling, or unable, to sign the CLA, even for a _tiny_, one-word PR, please file an issue instead of a PR. - [x] If this PR is not meant to land until a future stable release, mark it as draft with an explanation. - [x] This PR follows the [Google Developer Documentation Style Guidelines](https://developers.google.com/style)—for example, it doesn't use _i.e._ or _e.g._, and it avoids _I_ and _we_ (first-person pronouns). - [x] This PR uses [semantic line breaks](https://github.com/dart-lang/site-shared/blob/main/doc/writing-for-dart-and-flutter-websites.md#semantic-line-breaks) of 80 characters or fewer.
1 parent 9fa5960 commit 4ec1505

2 files changed

Lines changed: 223 additions & 0 deletions

File tree

‎sites/docs/src/content/release/breaking-changes/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,10 +38,12 @@ They're sorted by release and listed in alphabetical order:
3838

3939
* [Added enabled property and made onChanged optional for DropdownButton][]
4040
* [Migrate to standalone `material_ui` and `cupertino_ui` packages][]
41+
* [Stricter Android `Intent` verification for app entrypoints][]
4142
* [Restrict Android engine flags in release mode][]
4243
* [Removal of `useInheritedMediaQuery`][]
4344

4445
[Added enabled property and made onChanged optional for DropdownButton]: /release/breaking-changes/dropdownbutton-enabled-property
46+
[Stricter Android `Intent` verification for app entrypoints]: /release/breaking-changes/stricter-android-entrypoint-intent-verification
4547
[Migrate to standalone `material_ui` and `cupertino_ui` packages]: /release/breaking-changes/material-ui-and-cupertino-ui
4648
[Restrict Android engine flags in release mode]: /release/breaking-changes/restrict-android-engine-flags-release-mode
4749
[Removal of `useInheritedMediaQuery`]: /release/breaking-changes/remove-useInheritedMediaQuery
Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
---
2+
title: Stricter Android `Intent` Verification for App Entrypoints
3+
description: >-
4+
Android `Intent` extras for routing, entrypoints, and cached engines
5+
are now strictly verified.
6+
---
7+
8+
{% render "docs/breaking-changes.md" %}
9+
10+
## Summary
11+
12+
To prevent [`Intent`][]-based vulnerability exploits,
13+
the Flutter Android embedder
14+
(`FlutterActivity` and `FlutterFragmentActivity`)
15+
now verifies the sender of `Intent` objects
16+
before processing `EXTRA_INITIAL_ROUTE`, `EXTRA_DART_ENTRYPOINT`,
17+
`EXTRA_DART_ENTRYPOINT_ARGS`, `EXTRA_CACHED_ENGINE_ID`,
18+
and `EXTRA_CACHED_ENGINE_GROUP_ID`.
19+
20+
In release mode, external `Intent` objects cannot set these extras
21+
unless verified as originating from the app itself.
22+
If verification fails, the embedder ignores the extras
23+
and falls back to manifest metadata or default values for initial routes
24+
and Dart entrypoints.
25+
26+
## Context
27+
28+
Previously, the Flutter Android embedder accepted routing, entrypoint,
29+
and engine configuration directly from `Intent` extras.
30+
This allowed external apps or malicious actors to:
31+
32+
1. Hijack app navigation to sensitive internal routes
33+
(`EXTRA_INITIAL_ROUTE`).
34+
1. Execute arbitrary Dart entrypoints or pass unsafe arguments
35+
(`EXTRA_DART_ENTRYPOINT` and `EXTRA_DART_ENTRYPOINT_ARGS`).
36+
1. Reuse active, pre-authenticated in-memory engine instances
37+
(`EXTRA_CACHED_ENGINE_ID` and `EXTRA_CACHED_ENGINE_GROUP_ID`).
38+
39+
To fix these vulnerabilities, Flutter now validates the `Intent` sender.
40+
Deep links remain supported,
41+
but they must match the `<intent-filter>` declarations
42+
in your `AndroidManifest.xml`.
43+
44+
## Description of change
45+
46+
In release builds, the Android embedder strictly validates `Intent` extras:
47+
`"route"`, `"dart_entrypoint"`, `"dart_entrypoint_args"`,
48+
`"cached_engine_id"`, and `"cached_engine_group_id"`.
49+
50+
### Intent verification rules
51+
52+
An `Intent` is verified as safe if:
53+
54+
* **The activity is not exported:**
55+
Activities with `android:exported="false"` are automatically trusted.
56+
* **On Android 14 and later (API 34+):**
57+
The launching UID matches the application's UID (`getLaunchedFromUid()`).
58+
* **On Android 13 and earlier (API 33 and lower):**
59+
The calling package matches the app package (`getCallingPackage()`).
60+
This requires launching with `startActivityForResult()`
61+
or `startActivityIfNeeded()`.
62+
63+
For deep links (`Intent.ACTION_VIEW`),
64+
the link URI must match an `<intent-filter>`
65+
declared in the application manifest,
66+
unless the `Intent` is verified as self-sent.
67+
68+
### Fallback behavior
69+
70+
If verification fails in release builds, the extras are ignored:
71+
72+
* **Initial route (`EXTRA_INITIAL_ROUTE`):**
73+
Falls back to command-line arguments or `io.flutter.InitialRoute` metadata
74+
in `AndroidManifest.xml`.
75+
If neither is specified, it defaults to `"/"`.
76+
* **Dart entrypoint (`EXTRA_DART_ENTRYPOINT`):**
77+
Falls back to `io.flutter.Entrypoint` metadata in `AndroidManifest.xml`.
78+
If not specified, it defaults to `"main"`.
79+
* **Entrypoint arguments (`EXTRA_DART_ENTRYPOINT_ARGS`):**
80+
Ignored; returns `null`.
81+
* **Cached engine IDs (`EXTRA_CACHED_ENGINE_ID` and
82+
`EXTRA_CACHED_ENGINE_GROUP_ID`):**
83+
Ignored; returns `null`.
84+
85+
### Behavior in debug and profile modes
86+
87+
In debug and profile builds,
88+
the embedder bypasses verification to preserve developer tooling
89+
(such as `adb shell am start`) and automated tests.
90+
However, if an `Intent` fails verification,
91+
the embedder logs a warning with the target component,
92+
intent extras, and migration instructions.
93+
94+
## Migration guide
95+
96+
You do not need to migrate if:
97+
98+
* You do not pass `route`, `dart_entrypoint`, `dart_entrypoint_args`,
99+
`cached_engine_id`, or `cached_engine_group_id` extras in `Intent`s.
100+
* Your target `FlutterActivity` or `FlutterFragmentActivity`
101+
is not exported (`android:exported="false"`).
102+
103+
If you pass these extras to an exported activity,
104+
choose one of the following migration strategies:
105+
106+
### Set host activities to non-exported
107+
108+
If external apps do not need to open your activity directly,
109+
set `android:exported="false"` in `AndroidManifest.xml`:
110+
111+
```xml title="AndroidManifest.xml"
112+
<activity
113+
android:name=".MyFlutterActivity"
114+
android:exported="false">
115+
</activity>
116+
```
117+
118+
:::note
119+
Your app's main launcher activity (with `ACTION_MAIN`
120+
and `CATEGORY_LAUNCHER`) must remain exported so that the system launcher
121+
can launch your app.
122+
:::
123+
124+
### Migrate to deep links for external routing
125+
126+
To route to specific screens from external sources,
127+
shortcuts, or notifications,
128+
use standard [deep links][] instead of `EXTRA_INITIAL_ROUTE`:
129+
130+
```java
131+
Intent intent = new Intent(context, MainActivity.class);
132+
intent.setAction(Intent.ACTION_VIEW);
133+
intent.setData(Uri.parse("myapp://product_details"));
134+
```
135+
136+
Declare matching `<intent-filter>` entries in `AndroidManifest.xml`
137+
so the embedder can validate the incoming URL.
138+
139+
### Declare entrypoints and routes in AndroidManifest.xml
140+
141+
For static entrypoints or initial routes,
142+
declare them as `<meta-data>` in `AndroidManifest.xml`:
143+
144+
```xml title="AndroidManifest.xml"
145+
<activity
146+
android:name=".MyFlutterActivity"
147+
android:exported="true">
148+
<meta-data
149+
android:name="io.flutter.Entrypoint"
150+
android:value="myCustomEntrypoint" />
151+
<meta-data
152+
android:name="io.flutter.InitialRoute"
153+
android:value="/customRoute" />
154+
</activity>
155+
```
156+
157+
### Use startActivityForResult on Android 13 and earlier
158+
159+
For internal app launches to an exported activity on Android 13 and earlier,
160+
call `startActivityForResult()` instead of `startActivity()`:
161+
162+
```diff
163+
- startActivity(intent);
164+
+ startActivityForResult(intent, REQUEST_CODE);
165+
```
166+
167+
This populates `getCallingPackage()`, allowing the embedder to verify
168+
that the `Intent` originated from your app.
169+
You do not need to handle the result in `onActivityResult()`.
170+
171+
### Override configuration methods in an activity subclass
172+
173+
To provide dynamic entrypoints or arguments without relying on `Intent` extras,
174+
subclass `FlutterActivity` or `FlutterFragmentActivity`
175+
and override the configuration methods:
176+
177+
```java
178+
public class MyFlutterActivity extends FlutterActivity {
179+
@NonNull
180+
@Override
181+
public String getDartEntrypointFunctionName() {
182+
return ConfigManager.getEntrypoint();
183+
}
184+
185+
@Nullable
186+
@Override
187+
public List<String> getDartEntrypointArgs() {
188+
return ConfigManager.getArgs();
189+
}
190+
}
191+
```
192+
193+
## Timeline
194+
195+
Landed in version: TBD<br>
196+
In stable release: TBD
197+
198+
## References
199+
200+
* [Android `Intent` filters][]
201+
* [Set up Flutter Android deep links][]
202+
203+
Relevant issues:
204+
205+
* [Issue 190450][]
206+
* [Issue 190452][]
207+
208+
Relevant PR:
209+
210+
* [PR 190249][]
211+
212+
[`Intent`]: https://developer.android.com/reference/android/content/Intent
213+
[deep links]: /cookbook/navigation/set-up-app-links
214+
[intent filters]: https://developer.android.com/guide/components/intents-filters
215+
[Android `Intent` filters]:
216+
https://developer.android.com/guide/components/intents-filters
217+
[Set up Flutter Android deep links]: /cookbook/navigation/set-up-app-links
218+
[Issue 190450]: https://github.com/flutter/flutter/issues/190450
219+
[Issue 190452]: https://github.com/flutter/flutter/issues/190452
220+
[PR 190249]: https://github.com/flutter/flutter/pull/190249
221+

0 commit comments

Comments
 (0)