AXP-Resurection/specs/007-kernelsu-sunfish/spec.md

Feature Specification: KernelSU-Next on sunfish (LAB)

Feature Branch: 007-kernelsu-sunfish
Created: 2026-09-15
Status: In progress (LAB)
Session handoff: docs/session-20260916-handoff.md (2026-09-16)
Input: After 005 first Google-compat stack works on LAB, skip forcing a rootless Yuh green gate. Prioritize ReSukiSU (not Magisk; KSU-Next only as history) on the LineageOS 23.2 sunfish kernel, verified hide for banking UIDs, then SusFS / TEESimulator-class LAB experiments aimed at Yuh KeyMint/RKP failures already logged in 002. LAB only; never GOLDEN. Personal stock handset for banks remains an optional operator fallback outside this feature.

Spine reminder: product path is our LOS 23.2 (003→004/005 bacon) then 007. Community abu/torukk ROMs and Downloads boots are reference only.

Context / sequencing vs 006

Constitution originally ordered a rootless banking baseline (006) before root (007). Evidence already shows:

Device	Stack	Swissquote	Yuh
GOLDEN	AXP + Magisk DenyList	PASS (owner)	FAIL — HA / “certificate invalid”; KeyMint/HARDWARE_TYPE_UNAVAILABLE
LAB (iodé A16)	No Magisk; BL locked	—	FAIL — same KeyMint/RKP class

So a “rootless Yuh must pass” gate is not a credible start condition. This feature absorbs the banking regression that 006 would have owned: measure owner + Island UIDs on our ROM with root hidden. A separate 006 spec may stay deferred or become a thin historical note — it must not block 007 work.

Explicitly later (do not pull into this feature): call recording (008), FLAG_SECURE (009), AXP UX leftovers (010), project signing/AVB (011), incremental Graphene/AXP/Divest hardening ports (012–013).

User Scenarios & Testing (mandatory)

User Story 1 - Bootable rooted LAB image (Priority: P1)

As the developer, I can flash a LAB build whose kernel includes KernelSU-Next compatible with non-GKI Linux 4.14 / sunfish, boot to the lock screen, and confirm root is available only through the KernelSU manager to apps I approve.

Why this priority: Without a working integrated root path, hide/SusFS/banking experiments cannot run on our ROM.

Independent Test: Flash LAB only; manager shows installed; su works for one approved test app and fails for an unapproved app.

Acceptance Scenarios:

1. Given a 007 LAB flash, When the device boots, Then telephony, Wi‑Fi, and basic UI work at least as well as the last 005 image.
2. Given KernelSU manager, When root is granted to a single debug app, Then that app can obtain root and an unapproved app cannot.
3. Given documentation, When reviewed, Then the exact KernelSU-Next revision (tag/commit) used for the accepted POC is recorded for reproducibility.

---

User Story 2 - Banking apps never get root; mounts hidden (Priority: P1)

As the developer, Yuh and Swissquote (owner and Island/work profile UIDs) are configured so they never receive root, and module/overlay mounts that would expose root or custom ROM fingerprints to those UIDs are removed or hidden — verified by a real check, not only a UI toggle.

Why this priority: Constitution root architecture; Magisk DenyList on GOLDEN is oracle-only, not our production model.

Independent Test: Per-UID checks (process view of mounts / root binaries) for banking packages on user 0 and work profile; screenshots/logs stored under artifacts.

Acceptance Scenarios:

1. Given Yuh and Swissquote installed (Aurora → Island workflow preferred), When root grant lists are reviewed, Then those packages are denied root on every relevant user ID.
2. Given a module or overlay that would be visible to a normal app, When the banking UID is inspected, Then that mount is absent or otherwise hidden per the verified umount/profile mechanism.
3. Given only a manager “hide” toggle without mount evidence, When validation runs, Then the story is not marked pass.

---

User Story 3 - SusFS after profiles work (Priority: P2)

As the developer, once KernelSU profiles and verified hide work, I can enable a SusFS-capable kernel/config on LAB and confirm the device still boots and that selected path-hiding behaviours are measurable for banking UIDs.

Why this priority: Needed for hard banks on community sunfish reports; must not destabilize before basic KSU works. Constitution: SusFS only after KernelSU and application profiles work.

Independent Test: LAB boot + documented SusFS enablement + before/after visibility check for at least one sensitive path from a banking or probe UID.

Acceptance Scenarios:

1. Given US1–US2 green, When SusFS is enabled on LAB, Then the device boots and KernelSU manager still functions.
2. Given SusFS on, When a probe from a denied banking UID runs, Then at least one previously visible root/custom indicator is hidden (evidence logged).
3. Given SusFS causes repeated spontaneous reboot or severe thermal instability, When triage completes, Then SusFS is reverted or pinned to a known-good revision before continuing banking claims.

---

User Story 4 - Attestation / KeyMint experiment track (Priority: P1)

As the developer, I can run a LAB-only attestation-compatibility experiment (TrickyStore-class or equivalent, plus any required microG hardware-attestation toggles) aimed at the Yuh failure mode already captured in 002 (KeyMint / HARDWARE_TYPE_UNAVAILABLE / “certificate invalid”), without modifying GOLDEN.

Why this priority: Root hide alone did not fix Yuh on GOLDEN or iodé LAB; attestation is the open hypothesis. Yuh PASS is mandatory for feature acceptance — otherwise root is not worth carrying vs NeoBackup + native 008/009 and a stock banking phone.

Independent Test: Reproduce Yuh launch with logcat focused on keystore2 / KeyMint / RKP; compare to 002 baselines; diagnostic results required with artifact paths; US5 owns PASS.

Acceptance Scenarios:

1. Given 002 Yuh failure signatures, When the experiment stack is applied on LAB, Then a new log capture exists that either shows the same class of error or a clear change.
2. Given a candidate experiment, When the same attestation probe and bank attempt are repeated, Then record the before/after result, limitations and rollback outcome. US4 owns diagnostic evidence, not banking acceptance.
3. Given persistent KeyMint/RKP messages, When results are interpreted, Then do not infer causality or failure from those messages alone. US5 exclusively owns the end-to-end banking acceptance decision.

---

User Story 5 - Banking regression on our ROM (Priority: P1)

As the project owner, after hide (and any accepted SusFS/attestation experiments) I have a written regression for Swissquote and Yuh inside Island on the 007 LAB image: install path, profile UIDs, biometrics if used, and outcome. Revolut/N26 remain non-blocking.

Why this priority: Compatibility hard-gates; replaces the deferred 006 oracle for “does banking work on our stack”.

Independent Test: End-to-end on LAB only; evidence under /srv/rom/artifacts/007-… (and optional laptop rsync). No GOLDEN flash/wipe.

Acceptance Scenarios:

1. Given Island (or documented equivalent), When Swissquote is used in the work profile with root denied + hide verified, Then Swissquote MUST PASS with a usable authenticated session, date and build id.
2. Given the same setup for Yuh, When login/attestation is attempted, Then the session MUST PASS; an unusable session means 007 is not accepted.
3. Given Magisk, When proposed as production root, Then it is rejected; Magisk A/B diagnostic builds are allowed only as temporary reference per constitution.

---

Edge Cases

• KernelSU-Next revision incompatible with 4.14 → evaluate alternate pin / ReSukiSU only as documented POC fork, not silent default change.
• Work-profile UIDs differ from owner → hide/root denial must be tested on both.
• path_umount missing/broken on 4.14 → story 2 fails until backport/verify.
• Attestation modules break Play/microg → revert experiment; keep iterating until both banks PASS or declare 007 blocked/cancelled.
• Operator chooses a separate stock phone for banks → interim fallback only; does not satisfy the Yuh hard-gate on LAB.

Requirements (mandatory)

Functional Requirements

• FR-001: Project MUST integrate KernelSU-Next into the LineageOS 23.2–compatible sunfish kernel built with the ROM (not Magisk as production root).
• FR-002: Root MUST be grantable only to explicitly approved apps; banking packages (at least Yuh and Swissquote) MUST never receive root on owner or work-profile user IDs used in the regression.
• FR-003: Module/overlay mounts MUST be removable or hidden from selected app processes, with verification beyond manager UI toggles; path_umount (or equivalent) support on this kernel MUST be confirmed or explicitly failed.
• FR-004: The accepted KernelSU-Next revision MUST be pinned and recorded (tag/commit) for reproducible builds.
• FR-005: SusFS MUST only be enabled after FR-001–FR-003 work on LAB; if enabled, boot stability and at least one measurable hide effect MUST be evidenced.
• FR-006: Evaluate an attestation candidate with exact source URL, immutable revision or release plus binary hash, dependencies, auditability, baseline, before/after evidence and rollback. KeyMint/RKP causality remains a hypothesis. Banking acceptance is owned solely by FR-007 / US5.
• FR-007: Both Yuh and Swissquote MUST PASS usable authenticated sessions in the LAB managed profile on the same accepted stack with root denied and hide verified. Failure of either bank leaves 007 incomplete or cancelled. N26/Revolut are non-blocking.
• FR-008: All flashing, kernel experiments, and attestation modules MUST target LAB (11231JEC207477) only; GOLDEN MUST remain read-only oracle.
• FR-009: Zygisk/LSPosed MUST NOT be introduced as the initial architecture unless a later feature proves no native alternative (out of default 007 scope).
• FR-010: Feature docs MUST state that deferred 006 rootless-Yuh-pass is not a prerequisite, and must link 002 Yuh/Swissquote evidence paths.

Key Entities

• LAB device: Experimental sunfish; only flash target for 007.
• KernelSU profile: Per-app (and per-user) root grant / umount policy.
• Banking target apps: Yuh (com.yuh), Swissquote (com.swissquote.android).
• Managed profile: Island (or equivalent) work user hosting banking apps.
• Attestation experiment stack: Optional LAB modules/toggles aimed at hardware attestation / KeyMint behaviour.
• Pinned root revision: Exact KernelSU-Next (and SusFS, if used) identifiers.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: LAB boots a 007 image with working selective root within one flash cycle after the accepted kernel build.
• SC-002: For Yuh and Swissquote on every tested user ID, root grant is denied and mount-hide is evidenced (not toggle-only) for every applicable contract checklist row, for both packages and every tested user ID; no failed or unverified mandatory row is allowed.
• SC-003: Yuh PASS on LAB Island under the 007 stack (root denied + verified hide + accepted SusFS/attestation experiments), with build id and evidence — required to close the feature.
• SC-004: Swissquote MUST PASS a usable authenticated session on the same image/stack as SC-003, with dated evidence; both are required for acceptance.
• SC-005: If SusFS is claimed in the release notes for this phase, LAB completes ≥24h soak without SusFS-driven reboot loops, or SusFS is withdrawn from the claim.
• SC-006: Artifact package contains before/after attestation probe results and correlated banking logs, including unresolved messages and limitations. Absence of a log string alone is not proof of successful attestation.
• SC-007: No Magisk-based production image is published as the project default root path.

Assumptions

• 005 stack (microG + patched Phonesky + restricted spoofing) remains the userspace base on LAB before/while bringing up 007.
• Island (already used on LAB/GOLDEN) remains the managed-profile vehicle unless a documented substitute is chosen during implementation planning.
• If EOL sunfish cannot satisfy Yuh even with SusFS/TrickyStore-class stacks, 007 stays incomplete (or is explicitly cancelled) — not “done with Yuh documented FAIL”. Rationale: without Yuh, root adds little over NeoBackup + native 008/009; a stock handset becomes the banking plan instead.
• Operator may still use a separate stock phone as interim fallback; that does not count as 007 acceptance.
• Full GrapheneOS/AXP/Divest kernel hardening ports remain 013, not this feature — 007 only changes the kernel as needed for KSU/SusFS/umount.
• Community sunfish LOS+KSU+SusFS reports are inspiration, not a drop-in base.

Out of scope

• Flashing or modifying GOLDEN.
• Magisk/Magia as default project root.
• Making Revolut/N26 hard-gates.
• Call recording, FLAG_SECURE, WebView provider work, project AVB lock.
• Purchasing or provisioning a second physical phone (operator choice).