# 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.