39 lines
2.1 KiB
Markdown
39 lines
2.1 KiB
Markdown
# ADR-002: OAuth security and read-only scopes
|
|
|
|
## Status
|
|
|
|
Accepted — 2026-08-25
|
|
|
|
## Context
|
|
|
|
UBGitea is a public Android client for the company Gitea instance. The instance reports Gitea version 1.23.5, which supports granular OAuth scopes. The application must browse private resources visible to the signed-in account without receiving write access.
|
|
|
|
## Decision
|
|
|
|
- Use OAuth 2.0 Authorization Code with a fresh PKCE S256 verifier and random state per attempt.
|
|
- Do not use, request, store, transmit, or log a client secret.
|
|
- Request only `read:user`, `read:repository`, `read:organization`, `read:issue`, and `read:notification`.
|
|
- Submit access tokens only as an HTTP Bearer authorization header.
|
|
- Use the system browser and the registered verified HTTPS App Link.
|
|
- Require exact callback origin and path, matching state, a valid unexpired transaction, and a single authorization code.
|
|
- Store tokens only through an Android Keystore-backed vault and exclude authentication data from Android backup.
|
|
- Treat 401 as expired authentication and 403 as insufficient permission; never broaden scopes automatically.
|
|
|
|
## Alternatives considered
|
|
|
|
- A broad or write scope was rejected because the current product is read-only.
|
|
- A client secret was rejected because an installed Android application cannot keep one confidential and the registered flow uses PKCE.
|
|
- A WebView was rejected because credentials must remain in the system browser security context.
|
|
- A custom URI scheme was rejected in favor of the registered verified HTTPS App Link.
|
|
|
|
## Consequences
|
|
|
|
- Adding a future feature that requires a new scope needs product approval, ADR revision, and explicit reauthorization UX.
|
|
- End-to-end verification remains blocked until signing fingerprints and `assetlinks.json` are configured.
|
|
- Private repository data must not be persisted until a separate retention and cache decision is approved.
|
|
|
|
## Evidence
|
|
|
|
- `GET /api/v1/version` on 2026-08-25 returned `1.23.5` without authentication.
|
|
- Gitea's OAuth provider documentation states that v1.23 and later support granular read/write resource scopes and PKCE.
|