[PR #4203] docs(android): define safe TLS capture composition #6122

Open
opened 2026-10-31 01:12:02 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/4203
Author: @arslanbasharat-o-o
Created: 10/15/2026
Status: 🔄 Open

Base: main ← Head: docs/android-tls-capture-composition


📝 Commits (2)

  • 03186e6 docs(android): define safe TLS capture composition
  • 83819fc fix(docs): separate Android capture guidance

📊 Changes

4 files changed (+83 additions, -0 deletions)

View changed files

📝 docs/adb-device-analysis.md (+8 -0)
📝 docs/frida-instrumentation.md (+10 -0)
📝 docs/web-network-captures.md (+27 -0)
📝 src/browser/history/HarCapture.test.ts (+38 -0)

📄 Description

Summary

Addresses #4194.

This PR records and documents the safe, docs-only composition of existing REA
lanes for caller-authorized Android TLS capture, and adds regression coverage
for HTTP Toolkit-style TLS failure metadata in HAR exports.

It intentionally does not add SSL-unpinning, CA installation, Android trust
mutation, HTTP Toolkit orchestration, or a built-in Frida bypass script.

Problem and expected behavior

Issue #4194 is a scope decision rather than a demonstrated implementation bug.
REA already has separate lanes for ADB device work, caller-authored Frida
instrumentation, and offline HAR inspection, but no documented end-to-end
workflow or explicit boundary around SSL-unpinning.

The safe supported result is:

  1. The caller uses a separately authorized HTTP Toolkit setup with a
    caller-owned/debug Android app.
  2. The caller exports HAR 1.2 and preserves the original file.
  3. REA inspects that local file offline.

HTTP Toolkit-style log._tlsErrors data, including cert-rejected, remains
historical container evidence. It is not treated as an HTTP record, proof that
pinning was bypassed, runtime attribution, or authorization evidence.

Change and scope

  • Document the manual composition in the historical capture, ADB, and Frida
    guides.
  • State explicitly that REA does not control HTTP Toolkit, install trust
    anchors, alter Android trust settings, or ship/select an unpinning script.
  • Add a HAR regression using a synthetic HTTP Toolkit-like _tlsErrors
    extension. It verifies container retention, entry-based record counts, and
    explicit redaction of a TLS-error message.

This stays within the existing offline capture and general-purpose provider
boundaries. Options 2 (assisted orchestration) and 3 (built-in unpinning) remain
pending separate maintainer scope decisions and are not included here.

Contract and boundary impact

  • Semantic owner and earliest changed stage: HAR capture projection owns
    producer-specific extension retention; docs own the composition boundary.
  • Contribution scope fit and linked maintainer decision: option 1/docs-only
    composition for #4194; no new runtime authority is introduced.
  • CLI and MCP/tool-catalog contract: none.
  • Provider, bridge, target-format, or platform compatibility: none; no live
    Android or HTTP Toolkit provider was added.
  • Evidence, artifact, provenance, or reconstruction contract: unknown HAR
    extensions remain container evidence; no runtime claim is inferred.
  • Target selection, authority, upstream behavior, and cleanup details: no new
    target interaction. Existing ADB/Frida effects and cleanup rules remain in
    their owning lanes.
  • Generated metadata, package, or installation impact: none.

Expected effects:

  • Read existing files or captured data.
  • Launch or attach to a process.
  • Inject instrumentation or run scripts/code.
  • Change process memory, registers, files, or configuration.
  • Contact network services.
  • Recover protected code or work around protections.
  • Documentation or usability only; no target interaction.
  • Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

  • Tests added or updated: src/browser/history/HarCapture.test.ts covers a
    log._tlsErrors array with cause: "cert-rejected", preservation under the
    container projection, non-projection into records, and redaction.
  • Base reproduction or other evidence: source inspection showed that generic
    HAR unknown extensions are already retained, while the issue provided no
    live HTTP Toolkit export or target fixture. The new test pins the relevant
    producer-shaped behavior without claiming a live HTTP Toolkit run.
  • User-visible CLI/MCP output: not run against a live Android device or HTTP
    Toolkit installation; the documented flow is intentionally offline at the
    REA inspection step.
  • Remaining proof gaps: no live HTTP Toolkit export, Android device, Frida
    server, or end-to-end capture was available. Options 2 and 3 remain
    intentionally unresolved pending maintainer scope decisions.

Validation performed

  • npm run test:local -- src/browser/history/HarCapture.test.ts — 62 passed.
  • npm run test:fast — 540 test files passed; 8,292 tests passed and 13
    skipped.
  • npm run check:fast — typecheck and lint passed.
  • npm run format:check — passed.
  • npm run docs:check — generated-document checks and readme consistency passed.
  • npm run verify:test-discovery — all 1,352 test files discovered exactly
    once.
  • git diff --check — passed.

Compatibility, safety, and release

  • Breaking changes or migration steps: none.
  • Real Hopper/Ghidra, browser, or OS coverage: no live provider was needed or
    run; the regression uses a synthetic HAR boundary fixture.
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: no bypass capability or
    target mutation was added. Documentation requires caller ownership or
    explicit authorization and does not treat device/APK/endpoint possession as
    proof of authorization.

Author readiness

Human owner: @arslanbasharat-o-o

  • I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
  • I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
  • I declare this PR ready for initial maintainer review.

Before merge

  • This PR addresses a concrete problem or an agreed enhancement.
  • Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related issue is linked.
  • Tests cover changed observable behavior and meaningful failure paths.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/4203 **Author:** [@arslanbasharat-o-o](https://github.com/arslanbasharat-o-o) **Created:** 10/15/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `docs/android-tls-capture-composition` --- ### 📝 Commits (2) - [`03186e6`](https://github.com/morluto/rea/commit/03186e63229873ccf606102c51f95312bfe58339) docs(android): define safe TLS capture composition - [`83819fc`](https://github.com/morluto/rea/commit/83819fcbd45dbeaa3417be0b1a747e0b1561d262) fix(docs): separate Android capture guidance ### 📊 Changes **4 files changed** (+83 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `docs/adb-device-analysis.md` (+8 -0) 📝 `docs/frida-instrumentation.md` (+10 -0) 📝 `docs/web-network-captures.md` (+27 -0) 📝 `src/browser/history/HarCapture.test.ts` (+38 -0) </details> ### 📄 Description ## Summary Addresses #4194. This PR records and documents the safe, docs-only composition of existing REA lanes for caller-authorized Android TLS capture, and adds regression coverage for HTTP Toolkit-style TLS failure metadata in HAR exports. It intentionally does **not** add SSL-unpinning, CA installation, Android trust mutation, HTTP Toolkit orchestration, or a built-in Frida bypass script. ## Problem and expected behavior Issue #4194 is a scope decision rather than a demonstrated implementation bug. REA already has separate lanes for ADB device work, caller-authored Frida instrumentation, and offline HAR inspection, but no documented end-to-end workflow or explicit boundary around SSL-unpinning. The safe supported result is: 1. The caller uses a separately authorized HTTP Toolkit setup with a caller-owned/debug Android app. 2. The caller exports HAR 1.2 and preserves the original file. 3. REA inspects that local file offline. HTTP Toolkit-style `log._tlsErrors` data, including `cert-rejected`, remains historical container evidence. It is not treated as an HTTP record, proof that pinning was bypassed, runtime attribution, or authorization evidence. ## Change and scope - Document the manual composition in the historical capture, ADB, and Frida guides. - State explicitly that REA does not control HTTP Toolkit, install trust anchors, alter Android trust settings, or ship/select an unpinning script. - Add a HAR regression using a synthetic HTTP Toolkit-like `_tlsErrors` extension. It verifies container retention, entry-based record counts, and explicit redaction of a TLS-error message. This stays within the existing offline capture and general-purpose provider boundaries. Options 2 (assisted orchestration) and 3 (built-in unpinning) remain pending separate maintainer scope decisions and are not included here. ## Contract and boundary impact - Semantic owner and earliest changed stage: HAR capture projection owns producer-specific extension retention; docs own the composition boundary. - Contribution scope fit and linked maintainer decision: option 1/docs-only composition for #4194; no new runtime authority is introduced. - CLI and MCP/tool-catalog contract: none. - Provider, bridge, target-format, or platform compatibility: none; no live Android or HTTP Toolkit provider was added. - Evidence, artifact, provenance, or reconstruction contract: unknown HAR extensions remain container evidence; no runtime claim is inferred. - Target selection, authority, upstream behavior, and cleanup details: no new target interaction. Existing ADB/Frida effects and cleanup rules remain in their owning lanes. - Generated metadata, package, or installation impact: none. Expected effects: - [x] Read existing files or captured data. - [x] Launch or attach to a process. - [x] Inject instrumentation or run scripts/code. - [x] Change process memory, registers, files, or configuration. - [x] Contact network services. - [x] Recover protected code or work around protections. - [x] Documentation or usability only; no target interaction. - [x] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: `src/browser/history/HarCapture.test.ts` covers a `log._tlsErrors` array with `cause: "cert-rejected"`, preservation under the container projection, non-projection into records, and redaction. - Base reproduction or other evidence: source inspection showed that generic HAR unknown extensions are already retained, while the issue provided no live HTTP Toolkit export or target fixture. The new test pins the relevant producer-shaped behavior without claiming a live HTTP Toolkit run. - User-visible CLI/MCP output: not run against a live Android device or HTTP Toolkit installation; the documented flow is intentionally offline at the REA inspection step. - Remaining proof gaps: no live HTTP Toolkit export, Android device, Frida server, or end-to-end capture was available. Options 2 and 3 remain intentionally unresolved pending maintainer scope decisions. ## Validation performed - `npm run test:local -- src/browser/history/HarCapture.test.ts` — 62 passed. - `npm run test:fast` — 540 test files passed; 8,292 tests passed and 13 skipped. - `npm run check:fast` — typecheck and lint passed. - `npm run format:check` — passed. - `npm run docs:check` — generated-document checks and readme consistency passed. - `npm run verify:test-discovery` — all 1,352 test files discovered exactly once. - `git diff --check` — passed. ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: no live provider was needed or run; the regression uses a synthetic HAR boundary fixture. - Package or release metadata impact: none. - Security, privacy, process, or containment review: no bypass capability or target mutation was added. Documentation requires caller ownership or explicit authorization and does not treat device/APK/endpoint possession as proof of authorization. ## Author readiness Human owner: @arslanbasharat-o-o - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## Before merge - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#6122
No description provided.