android-skills 1.0.0 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +55 -58
- package/android-ui/SKILL.md +187 -0
- package/android-ui/references/anti-slop-checklist.md +61 -0
- package/android-ui/references/checklist.md +95 -0
- package/android-ui/references/clarifying-questions.md +55 -0
- package/android-ui/references/color-and-contrast.md +104 -0
- package/android-ui/references/components-intents.md +74 -0
- package/android-ui/references/compose-patterns.md +120 -0
- package/android-ui/references/compose-risks.md +86 -0
- package/android-ui/references/input-and-state.md +77 -0
- package/android-ui/references/network-storage.md +87 -0
- package/android-ui/references/reconstruction-workflow.md +74 -0
- package/android-ui/references/report-template.md +71 -0
- package/android-ui/references/sensitive-data-ui.md +73 -0
- package/android-ui/references/typography-spacing.md +93 -0
- package/android-ui/references/webview.md +105 -0
- package/{android-ui-minimal → android-ui}/scripts/contrast.py +8 -8
- package/{android-ui-minimal → android-ui}/scripts/gen_tokens.py +11 -11
- package/{android-ui-minimal → android-ui}/scripts/lint_ui.py +29 -29
- package/{android-ui-security-review → android-ui}/scripts/scan.py +146 -146
- package/bin/android-skills.js +10 -10
- package/install.py +79 -65
- package/opencode/commands/ui.md +13 -0
- package/package.json +3 -4
- package/android-ui-minimal/SKILL.md +0 -98
- package/android-ui-minimal/references/anti-slop-checklist.md +0 -61
- package/android-ui-minimal/references/clarifying-questions.md +0 -55
- package/android-ui-minimal/references/color-and-contrast.md +0 -104
- package/android-ui-minimal/references/compose-patterns.md +0 -120
- package/android-ui-minimal/references/reconstruction-workflow.md +0 -74
- package/android-ui-minimal/references/typography-spacing.md +0 -93
- package/android-ui-security-review/SKILL.md +0 -93
- package/android-ui-security-review/references/checklist.md +0 -95
- package/android-ui-security-review/references/components-intents.md +0 -74
- package/android-ui-security-review/references/compose-risks.md +0 -86
- package/android-ui-security-review/references/input-and-state.md +0 -77
- package/android-ui-security-review/references/network-storage.md +0 -87
- package/android-ui-security-review/references/report-template.md +0 -71
- package/android-ui-security-review/references/sensitive-data-ui.md +0 -73
- package/android-ui-security-review/references/webview.md +0 -105
- package/opencode/commands/ui-minimal.md +0 -9
- package/opencode/commands/ui-security.md +0 -9
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# Color and contrast
|
|
2
|
+
|
|
3
|
+
Goal: the UI looks calm and clear without looking "lacking" (washed out, flat, boundary-less). The trick is not more colors, but enough neutral depth plus one consistent accent.
|
|
4
|
+
|
|
5
|
+
## Palette structure
|
|
6
|
+
|
|
7
|
+
A screen only needs these roles:
|
|
8
|
+
|
|
9
|
+
| Role | Function | Material 3 |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| Background | Screen base | `background` |
|
|
12
|
+
| Surface | Content areas, bars | `surface` |
|
|
13
|
+
| Surface variant (tonal) | Subtle separation, fields, chips | `surfaceVariant`, `surfaceContainer*` |
|
|
14
|
+
| Outline | Thin lines | `outlineVariant` |
|
|
15
|
+
| Text primary | Headings, body | `onSurface` |
|
|
16
|
+
| Text secondary | Descriptions | `onSurfaceVariant` |
|
|
17
|
+
| Accent | Primary actions, active state | `primary` / `onPrimary` |
|
|
18
|
+
| Error | Errors | `error` |
|
|
19
|
+
|
|
20
|
+
If all roles above are filled, the UI rarely looks lacking. The problem usually appears when only two levels exist (white and light gray), so there is no hierarchy.
|
|
21
|
+
|
|
22
|
+
## Rules so it does not look lacking
|
|
23
|
+
|
|
24
|
+
1. **At least 3 neutral depth levels** per theme: background, surface, and a higher surface or variant. Luminance difference between levels around 3–6 percent.
|
|
25
|
+
2. **Use the accent sparingly but consistently**: primary buttons, selected state, focus indicators, links. Do not use it as a large-area background.
|
|
26
|
+
3. **Secondary text stays readable.** Never lower text opacity below 4.5:1. Avoid `alpha = 0.38` for text that must be read.
|
|
27
|
+
4. **Separators exist**, but are subtle: space first, then tonal shift, then a 1dp `outlineVariant` line.
|
|
28
|
+
5. **Status colors** (error, success, warning) may sit outside the single accent, but always paired with text or an icon, not color alone.
|
|
29
|
+
6. **Dark mode is designed**, not inverted. Dark: background around `#0F1114` to `#141619`, surfaces stepping up. The accent is softened (lower chroma, lighter) so it does not vibrate.
|
|
30
|
+
7. **Grayscale test.** Convert the screenshot to black and white. The hierarchy must still read.
|
|
31
|
+
|
|
32
|
+
## Choosing an accent
|
|
33
|
+
|
|
34
|
+
- If the user has a brand color, use it. Derive its tonal steps, do not change the hue.
|
|
35
|
+
- If not, pick one hue with medium chroma. Avoid neon purple-blue and gradients. Safe picks: steel blue, dark teal green, terracotta, olive green, dark indigo.
|
|
36
|
+
- Do not use more than one accent hue. If categories need differentiation, differentiate with shape, labels, or icons.
|
|
37
|
+
- Generate tokens automatically: `python3 scripts/gen_tokens.py "#3B5BA9"`.
|
|
38
|
+
|
|
39
|
+
## Example palettes (neutral, ready to use)
|
|
40
|
+
|
|
41
|
+
Light:
|
|
42
|
+
|
|
43
|
+
| Token | Hex |
|
|
44
|
+
|---|---|
|
|
45
|
+
| background | `#F7F7F5` |
|
|
46
|
+
| surface | `#FFFFFF` |
|
|
47
|
+
| surfaceVariant | `#EFEFEC` |
|
|
48
|
+
| outlineVariant | `#DADAD5` |
|
|
49
|
+
| onSurface | `#1B1C1A` |
|
|
50
|
+
| onSurfaceVariant | `#5B5D58` |
|
|
51
|
+
| primary | `#3B5BA9` |
|
|
52
|
+
| onPrimary | `#FFFFFF` |
|
|
53
|
+
| error | `#B3261E` |
|
|
54
|
+
|
|
55
|
+
Dark:
|
|
56
|
+
|
|
57
|
+
| Token | Hex |
|
|
58
|
+
|---|---|
|
|
59
|
+
| background | `#121312` |
|
|
60
|
+
| surface | `#1A1B1A` |
|
|
61
|
+
| surfaceVariant | `#252624` |
|
|
62
|
+
| outlineVariant | `#3A3B38` |
|
|
63
|
+
| onSurface | `#E6E6E2` |
|
|
64
|
+
| onSurfaceVariant | `#A9AAA4` |
|
|
65
|
+
| primary | `#9DB4F0` |
|
|
66
|
+
| onPrimary | `#14224A` |
|
|
67
|
+
| error | `#F2B8B5` |
|
|
68
|
+
|
|
69
|
+
Verify before using: `python3 scripts/contrast.py "#5B5D58" "#F7F7F5"`.
|
|
70
|
+
|
|
71
|
+
## Contrast (WCAG 2.2)
|
|
72
|
+
|
|
73
|
+
- Normal text: at least 4.5:1.
|
|
74
|
+
- Large text (18sp or 14sp bold) and UI components (field borders, action icons): at least 3:1.
|
|
75
|
+
- Disabled state may be lower, but never use it for important information.
|
|
76
|
+
- Text over images: use a solid scrim, do not rely on the image.
|
|
77
|
+
|
|
78
|
+
## Compose implementation
|
|
79
|
+
|
|
80
|
+
```kotlin
|
|
81
|
+
private val LightColors = lightColorScheme(
|
|
82
|
+
primary = Color(0xFF3B5BA9),
|
|
83
|
+
onPrimary = Color(0xFFFFFFFF),
|
|
84
|
+
background = Color(0xFFF7F7F5),
|
|
85
|
+
surface = Color(0xFFFFFFFF),
|
|
86
|
+
surfaceVariant = Color(0xFFEFEFEC),
|
|
87
|
+
outlineVariant = Color(0xFFDADAD5),
|
|
88
|
+
onSurface = Color(0xFF1B1C1A),
|
|
89
|
+
onSurfaceVariant = Color(0xFF5B5D58),
|
|
90
|
+
error = Color(0xFFB3261E),
|
|
91
|
+
)
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Hex values may only appear in this theme file. In screens, use `MaterialTheme.colorScheme.primary` and so on.
|
|
95
|
+
|
|
96
|
+
Dynamic color (Material You): do not enable by default when the user has a brand color. Make it an option and ask.
|
|
97
|
+
|
|
98
|
+
## Anti-patterns
|
|
99
|
+
|
|
100
|
+
- Pure white `#FFFFFF` as the main background everywhere, plus pure black text.
|
|
101
|
+
- Pure black `#000000` + pure white text (halos, tiring), except OLED-first.
|
|
102
|
+
- Gray via opacity over other colors (unpredictable results). Use solid colors from tokens.
|
|
103
|
+
- Random color per component for "variety".
|
|
104
|
+
- Accent gradients on buttons, headers, and backgrounds.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Components, intents, deep links
|
|
2
|
+
|
|
3
|
+
## Exported
|
|
4
|
+
|
|
5
|
+
Since target SDK 31, components with an `intent-filter` require an explicit `android:exported`. Rules:
|
|
6
|
+
- Default `false`. Change to `true` only when other apps must call it.
|
|
7
|
+
- A launcher activity must be exported. Other activities usually are not.
|
|
8
|
+
- Exported services, receivers, and providers must be protected with `android:permission` (signature) unless intentionally public.
|
|
9
|
+
- Check the merged manifest, because libraries can add exported components.
|
|
10
|
+
|
|
11
|
+
## Activities receiving data from outside
|
|
12
|
+
|
|
13
|
+
Treat `intent.extras`, `intent.data`, and `intent.action` as untrusted input.
|
|
14
|
+
|
|
15
|
+
```kotlin
|
|
16
|
+
val id = intent.getStringExtra("id")?.takeIf { it.matches(Regex("[A-Za-z0-9_-]{1,64}")) }
|
|
17
|
+
?: return finish()
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Do not:
|
|
21
|
+
- Pass an extra directly into a query, file path, WebView URL, or `startActivity`.
|
|
22
|
+
- Assume the extra type is correct. Use the typed API version (`getParcelableExtra(key, Clazz::class.java)`) and handle null.
|
|
23
|
+
- Trust `callingPackage` as authentication.
|
|
24
|
+
|
|
25
|
+
## Intent redirection
|
|
26
|
+
|
|
27
|
+
Dangerous pattern:
|
|
28
|
+
|
|
29
|
+
```kotlin
|
|
30
|
+
val forward = intent.getParcelableExtra<Intent>("next")
|
|
31
|
+
startActivity(forward) // attacker picks the destination, including private components
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Fix: do not accept an Intent in extras. If unavoidable, resolve it and restrict the destination to an allowlist of components, strip `FLAG_GRANT_*_URI_PERMISSION`, and do not launch with elevated rights.
|
|
35
|
+
|
|
36
|
+
## Deep links
|
|
37
|
+
|
|
38
|
+
- Validate scheme, host, path, and every parameter.
|
|
39
|
+
- Use verified App Links (`autoVerify="true"`, `assetlinks.json`) for https.
|
|
40
|
+
- Custom schemes can be hijacked by other apps. Never send tokens over a custom scheme.
|
|
41
|
+
- Do not skip authentication just because the entry came from a deep link. Check the session before showing a sensitive screen.
|
|
42
|
+
- Be careful with `redirect`, `url`, `next` parameters. Allowlist destinations to prevent open redirects.
|
|
43
|
+
- Navigation Compose arguments from deep links are still untrusted input.
|
|
44
|
+
|
|
45
|
+
## PendingIntent
|
|
46
|
+
|
|
47
|
+
- Always set `FLAG_IMMUTABLE` unless it truly must be filled in later (`FLAG_MUTABLE`).
|
|
48
|
+
- The intent inside is explicit (component or package set). No empty Intent.
|
|
49
|
+
- For notifications, do not embed sensitive data in extras.
|
|
50
|
+
|
|
51
|
+
## Broadcasts
|
|
52
|
+
|
|
53
|
+
- `registerReceiver` on Android 13+ requires `RECEIVER_NOT_EXPORTED` for internal broadcasts.
|
|
54
|
+
- `sendBroadcast` with sensitive data: restrict to your own package (`setPackage`) or use a permission.
|
|
55
|
+
- Consider in-process alternatives (Flow, SharedFlow) instead of broadcasts.
|
|
56
|
+
|
|
57
|
+
## FileProvider and file sharing
|
|
58
|
+
|
|
59
|
+
- Define paths as narrow as possible, never `root-path` or `.`
|
|
60
|
+
- Use `FileProvider.getUriForFile`, not `Uri.fromFile`.
|
|
61
|
+
- Grant `FLAG_GRANT_READ_URI_PERMISSION` only to a specific receiver on the Intent being sent; do not make the provider exported.
|
|
62
|
+
- Validate user-supplied file names (strip `..`, path separators) before writing.
|
|
63
|
+
|
|
64
|
+
## Sharing and receiving content
|
|
65
|
+
|
|
66
|
+
- `ACTION_SEND` activities receive text or Uris from any app. Validate size, MIME type, and Uri scheme (`content` only, not `file`).
|
|
67
|
+
- Copy into private storage before processing. Do not open `content://` with a path from input.
|
|
68
|
+
|
|
69
|
+
## Tapjacking
|
|
70
|
+
|
|
71
|
+
Screens that trigger sensitive actions with a single tap can be overlaid.
|
|
72
|
+
- Views: `filterTouchesWhenObscured = true`.
|
|
73
|
+
- Compose: read `LocalView.current` and set the same property on the root view, or check `MotionEvent.FLAG_WINDOW_IS_OBSCURED` and refuse the action.
|
|
74
|
+
- For critical confirmations, add an explicit step (a dialog with clear text).
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# Compose patterns (and XML equivalents)
|
|
2
|
+
|
|
3
|
+
## File structure
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
ui/
|
|
7
|
+
theme/Color.kt Type.kt Theme.kt Spacing.kt
|
|
8
|
+
components/ (small reusable components)
|
|
9
|
+
screen/<name>/ <Name>Screen.kt <Name>ViewModel.kt <Name>UiState.kt
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
Rule: one screen composable receives `state` and `onEvent` (state hoisting). No repository or network access inside composables.
|
|
13
|
+
|
|
14
|
+
## Screen skeleton
|
|
15
|
+
|
|
16
|
+
```kotlin
|
|
17
|
+
@Composable
|
|
18
|
+
fun NotesScreen(
|
|
19
|
+
state: NotesUiState,
|
|
20
|
+
onEvent: (NotesEvent) -> Unit,
|
|
21
|
+
modifier: Modifier = Modifier,
|
|
22
|
+
) {
|
|
23
|
+
Scaffold(
|
|
24
|
+
modifier = modifier,
|
|
25
|
+
topBar = { NotesTopBar(onSearch = { onEvent(NotesEvent.OpenSearch) }) },
|
|
26
|
+
containerColor = MaterialTheme.colorScheme.background,
|
|
27
|
+
) { inner ->
|
|
28
|
+
when (state) {
|
|
29
|
+
NotesUiState.Loading -> LoadingBox(Modifier.padding(inner))
|
|
30
|
+
is NotesUiState.Error -> ErrorBox(state.message, { onEvent(NotesEvent.Retry) }, Modifier.padding(inner))
|
|
31
|
+
is NotesUiState.Content ->
|
|
32
|
+
if (state.items.isEmpty()) EmptyBox("No notes yet", Modifier.padding(inner))
|
|
33
|
+
else NotesList(state.items, { onEvent(NotesEvent.Open(it)) }, Modifier.padding(inner))
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Plain list rows (no cards)
|
|
40
|
+
|
|
41
|
+
```kotlin
|
|
42
|
+
@Composable
|
|
43
|
+
fun NoteRow(title: String, subtitle: String, onClick: () -> Unit) {
|
|
44
|
+
Column(
|
|
45
|
+
Modifier
|
|
46
|
+
.fillMaxWidth()
|
|
47
|
+
.clickable(onClick = onClick)
|
|
48
|
+
.heightIn(min = 56.dp)
|
|
49
|
+
.padding(horizontal = Space.lg, vertical = Space.md),
|
|
50
|
+
verticalArrangement = Arrangement.spacedBy(Space.xs),
|
|
51
|
+
) {
|
|
52
|
+
Text(title, style = MaterialTheme.typography.titleMedium, maxLines = 1, overflow = TextOverflow.Ellipsis)
|
|
53
|
+
Text(subtitle, style = MaterialTheme.typography.bodyMedium,
|
|
54
|
+
color = MaterialTheme.colorScheme.onSurfaceVariant, maxLines = 2, overflow = TextOverflow.Ellipsis)
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Divider: `HorizontalDivider(color = MaterialTheme.colorScheme.outlineVariant)` with a 16dp inset.
|
|
60
|
+
|
|
61
|
+
## Buttons
|
|
62
|
+
|
|
63
|
+
- Primary action: `Button` (one per screen).
|
|
64
|
+
- Secondary: `OutlinedButton` or `TextButton`.
|
|
65
|
+
- Minimum height 48dp. Full width only for the primary action in a form or bottom bar.
|
|
66
|
+
|
|
67
|
+
## Edge-to-edge and insets
|
|
68
|
+
|
|
69
|
+
```kotlin
|
|
70
|
+
// Activity
|
|
71
|
+
enableEdgeToEdge()
|
|
72
|
+
// Scaffold already applies inner padding. For manual content:
|
|
73
|
+
Modifier.windowInsetsPadding(WindowInsets.safeDrawing)
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Use `imePadding()` for screens with fields.
|
|
77
|
+
|
|
78
|
+
## Required previews
|
|
79
|
+
|
|
80
|
+
```kotlin
|
|
81
|
+
@Preview(name = "Light") @Composable private fun P1() = AppTheme(darkTheme = false) { NotesScreen(sampleState, {}) }
|
|
82
|
+
@Preview(name = "Dark", uiMode = UI_MODE_NIGHT_YES) @Composable private fun P2() = AppTheme(darkTheme = true) { NotesScreen(sampleState, {}) }
|
|
83
|
+
@Preview(name = "Large font", fontScale = 1.5f) @Composable private fun P3() = AppTheme { NotesScreen(sampleState, {}) }
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## Accessibility
|
|
87
|
+
|
|
88
|
+
```kotlin
|
|
89
|
+
Icon(Icons.Outlined.Delete, contentDescription = "Delete note")
|
|
90
|
+
Modifier.semantics { heading() } // section heading
|
|
91
|
+
Modifier.clearAndSetSemantics { } // decorative
|
|
92
|
+
Modifier.minimumInteractiveComponentSize() // 48dp target
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Basic performance
|
|
96
|
+
|
|
97
|
+
- `remember` for expensive objects, `derivedStateOf` for derived state.
|
|
98
|
+
- Stable lambda parameters. Avoid creating new objects on every recomposition inside a list.
|
|
99
|
+
- `LazyColumn(key = { it.id }, contentType = { ... })`.
|
|
100
|
+
- Images: Coil with fixed sizes so they do not jump.
|
|
101
|
+
|
|
102
|
+
## XML Views equivalents
|
|
103
|
+
|
|
104
|
+
| Compose | XML |
|
|
105
|
+
|---|---|
|
|
106
|
+
| `MaterialTheme.colorScheme.*` | Theme attributes `?attr/colorSurface`, `?attr/colorOnSurface` |
|
|
107
|
+
| `Space.lg` | `@dimen/space_lg` (in `dimens.xml`) |
|
|
108
|
+
| `typography.titleMedium` | `?attr/textAppearanceTitleMedium` |
|
|
109
|
+
| `Scaffold` | `CoordinatorLayout` + `MaterialToolbar` |
|
|
110
|
+
| `LazyColumn` | `RecyclerView` + `ListAdapter` + `DiffUtil` |
|
|
111
|
+
|
|
112
|
+
No hex colors in XML layouts. Define them in `colors.xml` and `values-night/colors.xml`, reference them via theme attributes.
|
|
113
|
+
|
|
114
|
+
## Do not
|
|
115
|
+
|
|
116
|
+
- `Color(0xFF...)` inside screens.
|
|
117
|
+
- Ad-hoc `fontSize = 15.sp`.
|
|
118
|
+
- `Modifier.padding(13.dp)` off-scale numbers.
|
|
119
|
+
- Calling `viewModel()` inside a small reusable component.
|
|
120
|
+
- Hiding important content behind gestures without an alternative.
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# Jetpack Compose-specific risks
|
|
2
|
+
|
|
3
|
+
## Persisted state
|
|
4
|
+
|
|
5
|
+
- `rememberSaveable` stores values in the Bundle (restorable after process death, visible in debug tools). Do not use it for passwords, PINs, tokens.
|
|
6
|
+
- `SavedStateHandle` in a ViewModel carries the same risk.
|
|
7
|
+
- Use `remember` for secrets and clear it when the screen leaves composition (`DisposableEffect`).
|
|
8
|
+
|
|
9
|
+
```kotlin
|
|
10
|
+
var pin by remember { mutableStateOf("") }
|
|
11
|
+
DisposableEffect(Unit) { onDispose { pin = "" } }
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
JVM strings cannot be wiped from memory with certainty. Do not claim "safely deleted"; you only shortened the reference's lifetime.
|
|
15
|
+
|
|
16
|
+
## Text fields
|
|
17
|
+
|
|
18
|
+
```kotlin
|
|
19
|
+
OutlinedTextField(
|
|
20
|
+
value = password,
|
|
21
|
+
onValueChange = { password = it },
|
|
22
|
+
visualTransformation = if (visible) VisualTransformation.None else PasswordVisualTransformation(),
|
|
23
|
+
keyboardOptions = KeyboardOptions(
|
|
24
|
+
keyboardType = KeyboardType.Password,
|
|
25
|
+
autoCorrectEnabled = false,
|
|
26
|
+
imeAction = ImeAction.Done,
|
|
27
|
+
),
|
|
28
|
+
singleLine = true,
|
|
29
|
+
)
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
- The show-password toggle is temporary. Hide it again when the screen loses focus or the app goes to background.
|
|
33
|
+
- Use `Modifier.semantics { password() }` so accessibility services and autofill treat it as a password.
|
|
34
|
+
- Limit input length (`onValueChange = { if (it.length <= 64) ... }`).
|
|
35
|
+
|
|
36
|
+
## Semantics and accessibility
|
|
37
|
+
|
|
38
|
+
- `contentDescription` and `stateDescription` are read by accessibility services. Do not put secret data in them.
|
|
39
|
+
- For content that must not be read by accessibility services, use `Modifier.clearAndSetSemantics { }` or `invisibleToUser()` carefully, while still providing an alternative for users who need it.
|
|
40
|
+
- A malicious accessibility service can read the screen. For the most sensitive screens, consider FLAG_SECURE and checking for active accessibility services.
|
|
41
|
+
|
|
42
|
+
## AndroidView and interop
|
|
43
|
+
|
|
44
|
+
- `AndroidView { WebView(it) }` inherits all WebView risks (see `webview.md`).
|
|
45
|
+
- Release resources in `onRelease`. Do not hold an Activity Context in long-lived objects.
|
|
46
|
+
|
|
47
|
+
## Navigation
|
|
48
|
+
|
|
49
|
+
- Route arguments are strings on the back stack and in deep links. Do not pass sensitive objects as arguments. Pass an ID, fetch data from the repository.
|
|
50
|
+
- `navDeepLink` exposes the route externally. Check authentication at the destination, not only on the first screen.
|
|
51
|
+
- Make sure `popUpTo` after login/logout clears the back stack so the user cannot return to a sensitive screen.
|
|
52
|
+
|
|
53
|
+
## Previews and sample data
|
|
54
|
+
|
|
55
|
+
- No real data, tokens, or internal URLs in `@Preview` or sample data. It ends up in the repo.
|
|
56
|
+
- Preview code ships in the APK unless wrapped in the debug source set. Use `debugImplementation` for preview tooling.
|
|
57
|
+
|
|
58
|
+
## Sensitive screens
|
|
59
|
+
|
|
60
|
+
- Set FLAG_SECURE on the host Activity. Compose single-activity means the flag applies to every screen. Set it dynamically per route:
|
|
61
|
+
|
|
62
|
+
```kotlin
|
|
63
|
+
@Composable
|
|
64
|
+
fun SecureScreen(content: @Composable () -> Unit) {
|
|
65
|
+
val window = (LocalContext.current as Activity).window
|
|
66
|
+
DisposableEffect(Unit) {
|
|
67
|
+
window.addFlags(WindowManager.LayoutParams.FLAG_SECURE)
|
|
68
|
+
onDispose { window.clearFlags(WindowManager.LayoutParams.FLAG_SECURE) }
|
|
69
|
+
}
|
|
70
|
+
content()
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Dialogs and overlays
|
|
75
|
+
|
|
76
|
+
- Compose dialogs create their own window. `DialogProperties(securePolicy = SecureFlagPolicy.SecureOn)` sets FLAG_SECURE for sensitive dialogs.
|
|
77
|
+
- Triggers for destructive or financial actions in dialogs are still vulnerable to tapjacking. See `components-intents.md`.
|
|
78
|
+
|
|
79
|
+
## Side effects
|
|
80
|
+
|
|
81
|
+
- A `LaunchedEffect` that sends data over the network based on user input can fire repeatedly on recomposition or configuration changes. Make effect keys correct so a sensitive action is not sent twice.
|
|
82
|
+
|
|
83
|
+
## Third-party UI libraries
|
|
84
|
+
|
|
85
|
+
- Review the permissions and components they add via manifest merge.
|
|
86
|
+
- Pin versions and track security updates. Avoid unmaintained libraries for sensitive tasks (WebView wrappers, QR scanners, card input).
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# Inputs and state from outside
|
|
2
|
+
|
|
3
|
+
Any value not produced directly by your code is untrusted: user input, intent extras, deep links, network responses, file contents, clipboard, `ContentResolver` results, navigation arguments, QR contents.
|
|
4
|
+
|
|
5
|
+
## Validation
|
|
6
|
+
|
|
7
|
+
- Validate at the entry boundary (ViewModel or use case), not scattered across composables.
|
|
8
|
+
- Use allowlists, not blocklists: length, characters, ranges, enums.
|
|
9
|
+
- Parse into strong types as early as possible (`UUID`, `Int`, `enum`), handle failures.
|
|
10
|
+
- Client validation is for UX only. The server still re-validates.
|
|
11
|
+
|
|
12
|
+
```kotlin
|
|
13
|
+
fun parseAmount(raw: String): Long? =
|
|
14
|
+
raw.takeIf { it.length <= 12 && it.all(Char::isDigit) }?.toLongOrNull()
|
|
15
|
+
?.takeIf { it in 1..100_000_000 }
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Injection
|
|
19
|
+
|
|
20
|
+
| Context | Risk | Prevent |
|
|
21
|
+
|---|---|---|
|
|
22
|
+
| SQLite | SQL injection | Parameter binding, Room |
|
|
23
|
+
| WebView | XSS, JS injection | Do not build HTML/JS, escaped JSON |
|
|
24
|
+
| Intent / URI | Redirection, open redirect | Allowlist schemes and hosts |
|
|
25
|
+
| File | Path traversal | `canonicalPath` + base directory |
|
|
26
|
+
| Regex | ReDoS | Avoid nested-iteration patterns on user input, limit length |
|
|
27
|
+
| String format | Leaks | Never use user input as the format |
|
|
28
|
+
|
|
29
|
+
Path traversal:
|
|
30
|
+
|
|
31
|
+
```kotlin
|
|
32
|
+
val base = File(context.filesDir, "uploads").canonicalFile
|
|
33
|
+
val target = File(base, name).canonicalFile
|
|
34
|
+
require(target.path.startsWith(base.path + File.separator)) { "invalid path" }
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Deep links and navigation arguments
|
|
38
|
+
|
|
39
|
+
```kotlin
|
|
40
|
+
composable("detail/{id}") { entry ->
|
|
41
|
+
val id = entry.arguments?.getString("id")?.toLongOrNull() ?: return@composable
|
|
42
|
+
// check authorization: may this user see this id?
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
An ID in a URL is not authorization. Check access rights on the server (IDOR).
|
|
47
|
+
|
|
48
|
+
## QR and camera content
|
|
49
|
+
|
|
50
|
+
- Treat as untrusted URLs. Show the destination to the user before opening.
|
|
51
|
+
- Restrict schemes (`https`). Do not open `intent://` or `javascript:`.
|
|
52
|
+
|
|
53
|
+
## Network responses
|
|
54
|
+
|
|
55
|
+
- Use typed data models, ignore unknown fields, handle missing fields.
|
|
56
|
+
- Limit response sizes and the number of items rendered.
|
|
57
|
+
- Do not render HTML from responses unless sanitized.
|
|
58
|
+
- Server-provided image URLs: allow https only, limit decode size (`size(...)` in Coil).
|
|
59
|
+
|
|
60
|
+
## Displayed text
|
|
61
|
+
|
|
62
|
+
- User text shown in `Text` is safe from HTML injection. Risk appears when using `Html.fromHtml`, `AnnotatedString` from markup, or WebView.
|
|
63
|
+
- Limit text length and lines (`maxLines`, `overflow`) so the layout does not break.
|
|
64
|
+
- Watch for bidirectional control characters in file names or usernames shown in confirmation UIs.
|
|
65
|
+
|
|
66
|
+
## Races and state
|
|
67
|
+
|
|
68
|
+
- Prevent double submission on sensitive actions: disable the button while in flight, use an idempotency key on the server.
|
|
69
|
+
- Do not decide security from UI state (`isAdmin` in the ViewModel). The server decides.
|
|
70
|
+
- After process death, UI state can be restored with stale values. Re-verify the session before sensitive actions.
|
|
71
|
+
|
|
72
|
+
## Client-side validation that is often wrong
|
|
73
|
+
|
|
74
|
+
- Hiding a button is not access control.
|
|
75
|
+
- Obfuscation (R8) is not encryption.
|
|
76
|
+
- Root or emulator detection is not a security boundary.
|
|
77
|
+
- Client-only PIN attempt limiting can be bypassed.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Network and storage (UI perspective)
|
|
2
|
+
|
|
3
|
+
## Cleartext
|
|
4
|
+
|
|
5
|
+
- Manifest: do not set `usesCleartextTraffic="true"`.
|
|
6
|
+
- Target SDK 28+ blocks cleartext by default. Exceptions must go through `network_security_config` and stay narrow.
|
|
7
|
+
- All API, image, and WebView URLs use `https://`.
|
|
8
|
+
|
|
9
|
+
## network_security_config
|
|
10
|
+
|
|
11
|
+
Safe example for release:
|
|
12
|
+
|
|
13
|
+
```xml
|
|
14
|
+
<network-security-config>
|
|
15
|
+
<base-config cleartextTrafficPermitted="false">
|
|
16
|
+
<trust-anchors>
|
|
17
|
+
<certificates src="system" />
|
|
18
|
+
</trust-anchors>
|
|
19
|
+
</base-config>
|
|
20
|
+
<debug-overrides>
|
|
21
|
+
<trust-anchors>
|
|
22
|
+
<certificates src="user" />
|
|
23
|
+
</trust-anchors>
|
|
24
|
+
</debug-overrides>
|
|
25
|
+
</network-security-config>
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Do not trust user CAs (`src="user"`) in release.
|
|
29
|
+
|
|
30
|
+
## Certificate pinning
|
|
31
|
+
|
|
32
|
+
For high-risk apps (finance, health), pinning reduces fake-CA risk. But:
|
|
33
|
+
- Pin to the public key (SPKI), include at least one backup.
|
|
34
|
+
- Have a rotation and expiry plan. A wrong pin makes the app unable to connect.
|
|
35
|
+
- Pinning is not a replacement for server validation.
|
|
36
|
+
|
|
37
|
+
```kotlin
|
|
38
|
+
val pinner = CertificatePinner.Builder()
|
|
39
|
+
.add("api.example.com", "sha256/AAAA...=", "sha256/BBBB...=")
|
|
40
|
+
.build()
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Custom TrustManager and HostnameVerifier
|
|
44
|
+
|
|
45
|
+
Never implement one that accepts all certificates or all hosts, including "temporarily for dev". For dev servers with self-signed certs, register the dev CA in `debug-overrides`.
|
|
46
|
+
|
|
47
|
+
## Storage
|
|
48
|
+
|
|
49
|
+
| Data type | Where |
|
|
50
|
+
|---|---|
|
|
51
|
+
| Session tokens | Encrypted private storage with an Android Keystore key |
|
|
52
|
+
| Non-sensitive preferences | DataStore or SharedPreferences |
|
|
53
|
+
| Image cache | Private cache, clear on logout |
|
|
54
|
+
| User files | `filesDir` (private) or SAF/MediaStore at the user's choice |
|
|
55
|
+
|
|
56
|
+
Note: `EncryptedSharedPreferences` from `androidx.security:security-crypto` is marked deprecated in recent releases. Check the version you use and consider Keystore directly, or Tink with an encrypted DataStore.
|
|
57
|
+
|
|
58
|
+
Rules:
|
|
59
|
+
- Store the minimum. Short-lived tokens + revocable refresh tokens.
|
|
60
|
+
- Encryption keys never in source or in assets.
|
|
61
|
+
- Use `setUserAuthenticationRequired(true)` for keys guarding the most sensitive data.
|
|
62
|
+
- Do not store passwords. Store tokens.
|
|
63
|
+
|
|
64
|
+
## Backups
|
|
65
|
+
|
|
66
|
+
- `android:allowBackup="false"`, or define `dataExtractionRules` (Android 12+) and `fullBackupContent` excluding databases, tokens, and sensitive preferences.
|
|
67
|
+
|
|
68
|
+
## Files and shared storage
|
|
69
|
+
|
|
70
|
+
- Avoid writing sensitive data to external storage or MediaStore.
|
|
71
|
+
- Delete temporary files after use.
|
|
72
|
+
- Be careful with file names from the server or from users.
|
|
73
|
+
|
|
74
|
+
## Secrets in the app
|
|
75
|
+
|
|
76
|
+
- Anything in the APK can be extracted: strings, resources, BuildConfig, assets, native libraries.
|
|
77
|
+
- API keys that must live on the client (maps, analytics) must be restricted provider-side (package name + SHA-1, API allowlist, quotas).
|
|
78
|
+
- Full-access secrets (server keys, cloud service keys) do not belong on the client. Move them to the backend or a proxy.
|
|
79
|
+
- If one was committed: revoke and rotate first, then clean git history.
|
|
80
|
+
- For BYOK apps (the user enters their own API key): store encrypted in Keystore, do not log, do not put in crash reports, do not send anywhere except the intended provider, mask when displayed.
|
|
81
|
+
|
|
82
|
+
## Release
|
|
83
|
+
|
|
84
|
+
- Enable R8 (`isMinifyEnabled = true`) and `isShrinkResources` for release.
|
|
85
|
+
- Sign with a key stored securely, not in the repo.
|
|
86
|
+
- Ensure `debuggable` is false, logging off, WebView debugging off.
|
|
87
|
+
- Use the Play Integrity API where needed, with server-side verification.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# UI reconstruction workflow
|
|
2
|
+
|
|
3
|
+
Used when the user provides a screenshot, an old screen, or a description and asks for a cleaner rebuild.
|
|
4
|
+
|
|
5
|
+
## 1. Inventory
|
|
6
|
+
|
|
7
|
+
Write down what is on the screen, without judging:
|
|
8
|
+
- Elements (headings, lists, fields, buttons, navigation)
|
|
9
|
+
- Data displayed
|
|
10
|
+
- Actions available
|
|
11
|
+
- Visible states (empty, loading, error, selected)
|
|
12
|
+
|
|
13
|
+
If from a screenshot, name what cannot be confirmed (font, original sizes, exact colors) and ask if it matters.
|
|
14
|
+
|
|
15
|
+
## 2. Set the hierarchy
|
|
16
|
+
|
|
17
|
+
Answer three things:
|
|
18
|
+
1. What is this screen's one primary purpose?
|
|
19
|
+
2. What is the one primary action?
|
|
20
|
+
3. What can be dropped or moved to another screen?
|
|
21
|
+
|
|
22
|
+
Elements that do not answer those three questions are candidates for removal or demotion.
|
|
23
|
+
|
|
24
|
+
## 3. Map to tokens
|
|
25
|
+
|
|
26
|
+
Replace every ad-hoc value with a token:
|
|
27
|
+
- Color: pick the closest role (`surface`, `onSurfaceVariant`, `primary`).
|
|
28
|
+
- Spacing: round to the 4dp scale.
|
|
29
|
+
- Typography: pick the closest style from the scale.
|
|
30
|
+
- Radius: pick from the three levels.
|
|
31
|
+
|
|
32
|
+
Note mappings that change the appearance meaningfully, for the report.
|
|
33
|
+
|
|
34
|
+
## 4. Simplify
|
|
35
|
+
|
|
36
|
+
Pruning order:
|
|
37
|
+
1. Remove decoration without function (gradients, stacked shadows, ornamental icons).
|
|
38
|
+
2. Merge nested containers (card inside card).
|
|
39
|
+
3. Align everything to one left edge.
|
|
40
|
+
4. Reduce the number of text styles.
|
|
41
|
+
5. Reduce colors to one accent + neutrals.
|
|
42
|
+
|
|
43
|
+
## 5. Build
|
|
44
|
+
|
|
45
|
+
Follow `compose-patterns.md`. Start from state and events, then composition, then previews.
|
|
46
|
+
|
|
47
|
+
## 6. Verify
|
|
48
|
+
|
|
49
|
+
- Previews: light, dark, font scale 1.5, width 360dp.
|
|
50
|
+
- `python3 scripts/lint_ui.py <path>`.
|
|
51
|
+
- Contrast of the main color pairs.
|
|
52
|
+
- The checklist in `anti-slop-checklist.md`.
|
|
53
|
+
|
|
54
|
+
## 7. Report
|
|
55
|
+
|
|
56
|
+
Short format:
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
Done: <screen>
|
|
60
|
+
Decisions: <accent, list structure, etc.>
|
|
61
|
+
Changed: <files>
|
|
62
|
+
Deliberately not done: <things left unchanged and why>
|
|
63
|
+
Needs confirmation: <if any>
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Preserving behavior
|
|
67
|
+
|
|
68
|
+
Reconstruction must not change behavior. Preserve:
|
|
69
|
+
- Public function names and signatures called from outside the screen
|
|
70
|
+
- Navigation and route arguments
|
|
71
|
+
- Test IDs (`testTag`, `android:id`) already in use
|
|
72
|
+
- Text referenced by tests or localization (change via `strings.xml`, never hardcode)
|
|
73
|
+
|
|
74
|
+
If you must change any of them, state it explicitly in the report.
|