isphere-ai-bridge/docs/n12r-return-package-validation-checklist.md

N12R Return Package Validation Checklist

Use this checklist in the outer-network coordination environment after an internal-network operator returns a live capture package.

N12R packages are expected under:

runs/internal-sandbox-live-capture/<capture-id>/

This checklist validates package completeness and boundary compliance. It does not execute copied client binaries and does not mark original current-environment N12 as passed.

1. Required files

A package is structurally complete only if these files exist:

metadata/source-notes.txt
helper/version.json
helper/self-check.json
windows/scan-windows.json
windows/selected-window.json
uia/dump-uia-main.json
uia/dump-uia-main-redacted.json
notes/operator-notes.txt

Recommended metadata files:

metadata/os-version.txt
metadata/process-list.txt
metadata/repo-status.txt
metadata/verification-summary.txt

2. Read-only validation commands

Set package path:

$captureRoot = "runs\internal-sandbox-live-capture\<capture-id>"

Preferred one-command validation:

$reportRoot = "runs\internal-sandbox-live-capture-reports"
New-Item -ItemType Directory -Force -Path $reportRoot | Out-Null
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\validate-n12r-return-package.ps1 `
  -PackageRoot $captureRoot `
  -ReportPath (Join-Path $reportRoot "<capture-id>-validation.md")

The report path must stay outside the returned package root so validation does not modify the returned evidence package.

Check required files:

$required = @(
  "metadata\source-notes.txt",
  "helper\version.json",
  "helper\self-check.json",
  "windows\scan-windows.json",
  "windows\selected-window.json",
  "uia\dump-uia-main.json",
  "uia\dump-uia-main-redacted.json",
  "notes\operator-notes.txt"
)
foreach ($rel in $required) {
  $path = Join-Path $captureRoot $rel
  if (-not (Test-Path -LiteralPath $path)) { throw "missing required file: $rel" }
}

Check JSON parseability:

$jsonFiles = @(
  "helper\version.json",
  "helper\self-check.json",
  "windows\scan-windows.json",
  "windows\selected-window.json",
  "uia\dump-uia-main.json",
  "uia\dump-uia-main-redacted.json"
)
foreach ($rel in $jsonFiles) {
  Get-Content -LiteralPath (Join-Path $captureRoot $rel) -Encoding UTF8 | ConvertFrom-Json | Out-Null
}

3. Metadata acceptance checks

metadata/source-notes.txt must state:

source_environment: internal-network test sandbox
iSphere manually logged in: yes
client opened before capture: yes
main window visible: yes
operations used: version, self_check, scan_windows, dump_uia
forbidden actions performed: no
this package is N12R live evidence, not current-environment N12 pass

notes/operator-notes.txt must state:

How login was performed: manual normal company process
Forbidden actions performed: no

If either note file says automatic login, sending, receiving, injection, hook, memory reading, or bypass occurred, reject the package.

4. Helper JSON checks

helper/version.json should parse to an object where:

ok == true
data.helper_name == ISphereWinHelper

helper/self-check.json should parse to an object where:

ok == true
data.uia_available is a boolean

5. Window scan checks

windows/scan-windows.json should include at least one candidate where one or more of these fields indicates iSphere / IMPlatformClient / IMPP:

process_name
title
class_name
score

windows/selected-window.json should be one selected object from scan-windows.json and should include:

hwnd
pid
process_name
title
class_name
visible
bounds
score

6. UIA dump checks

uia/dump-uia-main.json should parse to a helper response where:

ok == true
data.root exists

The UIA root tree should include selector-useful fields such as:

name
control_type
automation_id
class_name
framework_id
bounds
children

The redacted copy uia/dump-uia-main-redacted.json must exist before broad sharing.

7. Boundary rejection checks

Reject the package for N12R evidence use if any of these are true:

source notes do not confirm manual login
main window was not visible
scan result has no iSphere / IMPlatformClient candidate
UIA dump is missing or empty
redacted UIA copy is missing
package includes raw passwords, tokens, cookies, private keys, or copied credential material
operator notes indicate automatic login, search, opening conversations, sending, receiving, injection, hook, memory reading, or endpoint-security bypass
package was produced by running copied executables from an offline evidence package

8. Validation result template

After validation, write a short report under:

runs/internal-sandbox-live-capture/<capture-id>/metadata/outer-validation-summary.txt

Template:

capture_id: <capture-id>
validated_at: <local time>
validated_by: outer-network coordination environment
required_files_present: yes/no
json_parse_ok: yes/no
manual_login_confirmed: yes/no
main_window_visible_confirmed: yes/no
candidate_window_found: yes/no
uia_dump_ok: yes/no
redacted_copy_present: yes/no
forbidden_actions_indicated: yes/no
validation_result: accepted/rejected
notes: <short notes>

9. Next decision after acceptance

If accepted, N12R evidence can be used for a selector-design review gate.

Do not implement selectors or action tools directly from this checklist. Selector design requires a separate written plan and explicit approval.