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