RobotAutomationDevelopment-Dept/Ubisam-MobileGit
16
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Ubisam-MobileGit/docs/decisions/002-oauth-security.md

2.1 KiB
Raw Blame History

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.