AXP-Resurection/specs/004-microg-phonesky-integration/spec.md

# Feature Specification: microG + GSF Proxy + patched Phonesky

**Feature Branch**: `004-microg-phonesky-integration`  
**Created**: 2026-09-14  
**Status**: Draft  
**Input**: Continue after `003` gate — integrate Google compatibility stack on LAB
vanilla LOS 23.2 / Android 16 (sunfish), without Magisk/KernelSU yet.

## User Scenarios & Testing *(mandatory)*

### User Story 1 - microG Self-Check green on LAB (Priority: P1)

As the developer, after flashing a build that includes microG + GSF Proxy, I can
open microG Settings Self-Check and see the checks required for basic Google
compatibility pass (or document exact remaining gaps owned by `005`).

**Why this priority**: Without a working microG core, Play and banking paths
cannot start.

**Independent Test**: Flash LAB-only build; open microG Self-Check; capture
screenshots/log; no Magisk/KSU installed.

**Acceptance Scenarios**:

1. **Given** LAB on `003` vanilla baseline, **When** a `004` build is flashed,
   **Then** `com.google.android.gms` and `com.google.android.gsf` are present as
   system packages and microG Settings opens.
2. **Given** microG is configured (device registration as required), **When**
   Self-Check runs, **Then** either all P1 checks pass, or each failure is
   explicitly attributed to signature spoofing (`005`) vs packaging error.

---

### User Story 2 - Patched Phonesky as priv-app (Priority: P1)

As the developer, patched Play Store (`com.android.vending`) is installed as a
privileged system app with required permission XMLs, obtained/patched/signed via
a documented host-side procedure (APK never committed to Git).

**Why this priority**: Constitution requires AXP-style patched Phonesky, not
FakeStore→Play as primary.

**Independent Test**: Package present as priv-app; permission XMLs deployed;
Play UI launches; update path documented even if spoofing still incomplete.

**Acceptance Scenarios**:

1. **Given** Phonesky artifacts under a restricted host path, **When** the ROM
   is built, **Then** `com.android.vending` is a privileged system app with the
   required default-permission / privapp-permissions configuration.
2. **Given** the build is flashed to LAB, **When** Play Store is opened,
   **Then** it starts (login/install may still depend on `005` spoofing — mark
   clearly if so).
3. **Given** Git history, **When** inspected, **Then** no Google proprietary
   Phonesky APK bytes are committed.

---

### User Story 3 - No FakeStore conflict (Priority: P2)

As the developer, FakeStore / microG Companion are not installed when they would
conflict with real patched `com.android.vending`.

**Why this priority**: Prevents the wrong Play stub from masking Phonesky.

**Independent Test**: `pm list packages` shows no conflicting FakeStore when
Phonesky is present.

**Acceptance Scenarios**:

1. **Given** Phonesky is included, **When** packages are listed, **Then**
   FakeStore is absent (or explicitly disabled with documented reason).

---

### User Story 4 - Reproducible obtain → patch → sign pipeline (Priority: P2)

As the developer, I can re-run a documented procedure on `rom-dev01` to produce
signed Phonesky + microG packaging inputs without tribal knowledge.

**Why this priority**: Required before any updatable Play Store distribution.

**Independent Test**: Second operator (or clean host path) follows the runbook
and produces matching package names/permissions (signature may differ if keys
differ — keys stay host-only).

**Acceptance Scenarios**:

1. **Given** the `004` runbook, **When** followed on `rom-dev01`, **Then**
   inputs land under `/srv/rom/…` (restricted) and the build consumes them
   without manual one-off hacks.
2. **Given** signing keys, **When** stored, **Then** they live only under
   host secrets (e.g. `/srv/rom/secrets/`), never in Git.

---

### Edge Cases

- LOS 23.2 already ships partial microG spoofing → use it; do not invent a full
  spoofing stack in `004` (that is `005`).
- Self-Check fails only on signature-related items → record as `005` dependency,
  not a `004` packaging failure.
- Play login/install fails while Self-Check packaging is OK → same split.
- Flash/upgrade wipes user data → LAB only; never GOLDEN.
- Wrong device serial → abort flash.

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: Integrate **latest** official microG Services Core as
  `com.google.android.gms` on the LOS 23.2 sunfish LAB build (do not pin to
  GOLDEN’s older version).
- **FR-002**: Integrate GSF Proxy as `com.google.android.gsf` (latest upstream).
- **FR-003**: Integrate patched Phonesky as privileged `com.android.vending`
  with required privapp-permissions / default-permissions XML, produced by
  patching the **latest** official Play Store APK (not an AXP archive binary).
- **FR-004**: Document and implement a reproducible obtain → patch → sign →
  priv-app pipeline for Phonesky on `rom-dev01` using AXP `patch-playstore` /
  apktool; proprietary APKs MUST NOT be committed to Git.
- **FR-005**: Do not install FakeStore (or conflicting Companion) alongside
  patched Phonesky.
- **FR-006**: Record microG Self-Check results on LAB (pass/fail per item) after
  flash; attribute spoofing-related failures to `005`.
- **FR-007**: Keep Magisk and KernelSU out of `004` builds (root arrives in
  `007`; banking baseline rootless in `006`).
- **FR-008**: Flash and validate on LAB serial `11231JEC207477` only; never
  GOLDEN `11071JEC203839`.
- **FR-009**: Prefer AXP golden packaging behaviour as reference (inventory from
  `002`); do not blind-copy Magisk modules or ship AXP-signed Play as product.
- **FR-010**: Phonesky is signed with a **project-owned** stable keystore under
  `/srv/rom/secrets/phonesky-signing/` so later patched Builds can update Play.
- **FR-011**: microG GmsCore/GsfProxy MUST remain **PRESIGNED** with the
  official microG signer so they stay updatable from the microG F-Droid
  repository; document repo setup for LAB Self-Check.

### Key Entities

- **microG Services Core** — `com.google.android.gms`
- **GSF Proxy** — `com.google.android.gsf`
- **Patched Phonesky** — `com.android.vending` (external proprietary input)
- **LAB** — Pixel 4a `11231JEC207477` (Android 16 / LOS 23.2 target)
- **GOLDEN** — AXP Pro Android 15 reference (read-only)

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: LAB build includes microG + GSF + patched Phonesky packages with
  correct package names.
- **SC-002**: microG Self-Check evidence captured; packaging failures = 0; any
  remaining failures mapped to `005` or explicitly accepted.
- **SC-003**: Phonesky opens on LAB; Git contains no proprietary Play APK.
- **SC-004**: Runbook exists such that a clean `rom-dev01` path can rebuild the
  same packaging layout.
- **SC-005**: No Magisk/KSU in the `004` validation build.

## Assumptions

- `003` vanilla baseline remains the parent tree; `004` adds packaging/patches
  on top without unrelated hardening.
- LineageOS 23.2 microG-oriented spoofing hooks may already exist; full
  restricted spoofing policy is `005`.
- `002` / GOLDEN inventory supplies reference behaviour and permission
  patterns only — not version pins for microG or Play.
- Phonesky binary is obtained outside Git via latest Play APK + AXP
  `patch-playstore` (apktool) + project signing keys on `rom-dev01`.
- Official microG release APKs share the signer used by the microG F-Droid
  repo, enabling same-package updates without re-signing.

## Out of Scope

- Signature spoofing implementation beyond using what LOS already provides
  (`005`)
- Insular / banking hard-gates (`006`)
- KernelSU (`007`)
- Release signing / AVB relock (`011`)
- Flashing or modifying GOLDEN