# Smart Miners Connector

Open-source Windows connector for keeping the authenticated GoMining Mining
Wars page active in the background and exposing a strictly redacted local view
of selected API responses and websocket events.

The source is released under the permissive [MIT License](LICENSE).

## Current MVP

- Runs the official GoMining page inside a dedicated WebView2 profile.
- Lets Microsoft Edge WebView2 manage password saving and general autofill
  inside that dedicated local profile. Connector code does not read or upload
  those values.
- Continues in the Windows notification area when the window is minimized or
  closed. Windows decides whether the icon appears directly or under hidden
  icons; double-clicking the icon restores the connector.
- Reuses the proven Smart Miners websocket/worker hook.
- `Reload GoMining` first re-runs each safely observed allowlisted API endpoint
  once inside the authenticated WebView session and then reloads the page.
- On a `401/403` from the round-state API, tries one automatic Edge session
  reload. A second rejection stops automatic recovery and asks the user to
  sign in; a successful response resets the recovery state.
- Forwards only allowlisted round, league, clan, score and boost data.
- Never forwards request headers, cookies, bearer tokens, raw websocket frames
  or URL query strings.
- Stores only a redacted event log under the connector-owned local app folder.
- Uploads redacted `API_RESPONSE` and `WS_EVENT` data through the private
  `https://gominertools.xyz/push/connector/events` ingestion route.
- Keeps a bounded connector-owned retry queue when the server is unavailable.
- Limits high-frequency state/API snapshots to one upload per source every
  thirty seconds; round, winner and boost events remain immediate.
- Creates a random private viewer code for
  `https://gominertools.xyz/connector-live/`; only its SHA-256 hash is uploaded
  and stored.
- Sends a metadata-only heartbeat every thirty seconds so the website can
  distinguish an online connector from an old game event.
- Implements optional signed schema-v2 AI verification, accepting
  either a full `.smcaudit` file or its installation-bound `SMC1` activation
  code representation.
- Contains no Supabase service-role key or GoMining credential export path.

## Honest security status

Two channels now exist:

- the unpackaged development build remains visibly marked
  `UNOFFICIAL DEVELOPMENT BUILD` and is intended only for functional testing;
- version `1.0.11-rc.1` can be built as a self-contained, test-signed MSIX with
  `packagedClassicApp`, AppContainer trust and only `internetClient`.

The release-candidate process token has been tested with
`TokenIsAppContainer = true`. This is not yet a production release: its
certificate is test-only, the current source snapshot is not a clean public
commit and the external independent audit verdict is still pending.

An official build can run without external verification and shows that state as
`OPTIONAL - NOT VERIFIED`. Users may inspect the ZIP with any AI, scanner or
reviewer they choose and can enter a valid, unexpired signed attestation bound to the SHA-256 of the
complete published app tree, app version and installation challenge. The
Security tab then shows the four verified answers. Changing the DLL, bridge,
hook or another shipped file invalidates the code. The repository contains only
a public verification key. A production audit signer and independently
protected private key are deliberately not included.

## Guided installation ZIP

The download page offers one
`SmartMiners-Connector-*-Install.zip`. Extract it and run `INSTALL.cmd`.
Independent inspection is optional and the user decides which AI, scanner or
reviewer to use.

The ZIP contains the exact MSIX, release evidence, audit prompt, complete
review source, test evidence, unpacked package and SPDX SBOM. A valid `SMC1`
code adds a verified status but is not required to use the connector.

Create it from the verified external audit handoff:

```powershell
./scripts/New-InstallerBundle.ps1 `
  -ExternalAuditBundlePath ./artifacts/SmartMiners-Connector-1.0.11.0-External-Audit.zip `
  -DisplayVersion 1.0.11-rc.1
```

The release candidate still includes its test certificate inside the one ZIP.
For this test-signed candidate, extract the ZIP and run `INSTALL.cmd`. Its
open PowerShell source verifies the exact MSIX and certificate SHA-256 values,
the certificate thumbprint and the package signature before requesting
elevation. Elevation is used only to import the public certificate into
`Local Computer > Trusted People`; the script then installs the verified MSIX
for the current user. The manual MSIX route requires the same certificate step
before App Installer enables its Install button.

The final publicly signed production MSIX will not require that test-certificate
step.

## Build

Build requirements:

- Windows 10/11
- .NET 10 SDK
- Microsoft Edge WebView2 Runtime

The AppContainer release candidate is self-contained and therefore does not
require a separate .NET Desktop Runtime on the user's computer. WebView2
Runtime remains required.

```powershell
dotnet restore SmartMinersConnector.sln --locked-mode
dotnet build SmartMinersConnector.sln -c Debug --no-restore
dotnet run --project tests/SmartMiners.Connector.SecurityTests -c Debug --no-build
node tests/bridge-security.test.js
node tests/source-policy.test.js
dotnet run --project src/SmartMiners.Connector -c Debug --no-build
```

Create both the runnable development ZIP and the version-specific package a
user can upload to an AI:

```powershell
./scripts/New-AiAuditBundle.ps1
```

The AI bundle also includes the exact VPS ingestion validator, its tests and
the Supabase migrations, so the complete client-to-database boundary can be
reviewed.

## Optional official-build verification

```powershell
dotnet publish src/SmartMiners.Connector/SmartMiners.Connector.csproj `
  -c Release -p:OfficialBuild=true `
  -p:SourceRevisionId=<clean-git-commit>
```

The app can run without an attestation. If the user chooses external
verification, the returned signed attestation must match the challenge
displayed by the connector. The app verifies the `SMC1` signature locally and
only then changes its status to verified.

The example signing service is intentionally unapproved, so it cannot issue a
production code until the exact release has passed the independent audit and
the protected signer is configured.

## AppContainer release candidate

Build a test-signed candidate:

```powershell
./scripts/New-AppContainerRelease.ps1
```

The script uses the pinned Microsoft Windows SDK Build Tools, executes all
security tests, publishes a self-contained `win-x64` app, packages it as MSIX,
applies an ephemeral test signature, checks the signature-to-certificate
binding, unpacks the package and verifies the final manifest.

Verify the actual process token:

```powershell
./scripts/Test-AppContainerRuntime.ps1 `
  -PackagePath ./artifacts/SmartMiners-Connector-1.0.11.0-TestSigned-AppContainer-RC.msix
```

Generate the exact independent-review handoff, including an SPDX SBOM:

```powershell
./scripts/New-ExternalAuditBundle.ps1 `
  -PackagePath <candidate.msix> `
  -CertificatePath <candidate.cer> `
  -ReleaseEvidencePath <candidate.release.json>
```

For `-Production`, `New-AppContainerRelease.ps1` requires a real signing PFX
and a clean committed source revision. It intentionally refuses to fall back to
the test certificate.

## Project boundaries

The connector does not perform wallet actions, boost actions, payments,
clipboard reads, screen capture, filesystem scanning, process inspection or
credential export. See [SECURITY.md](SECURITY.md) and
[AI-AUDIT-PROMPT.md](AI-AUDIT-PROMPT.md).

## Supabase upload

The Windows client never connects to Supabase directly. It sends only the
already-redacted allowlisted event types to the Smart Miners VPS endpoint. That
endpoint validates and redacts the batch again, rate-limits it, and writes it
with the server-side Supabase service role into the private
`smart_miners_connector_events` table. Anonymous and authenticated Supabase
clients have no table privileges.

Supabase keeps only the current round state for each connector installation.
Every allowlisted API path or websocket event name has one current slot; a new
value updates that slot instead of appending another database row. A reliable
`roundOpened` event or successful round-state API response rotates the
installation to a new round and removes the previous round slots. Failed API
responses never replace the last valid current value. This bounds event
storage to at most 18 current rows per installation while leaving the separate
metadata-only heartbeat intact.

## Private website Live view

The connector shows an anonymous installation ID and a 20-hex-character
private viewer code under `Security & AI audit`. A user enters both at
`https://gominertools.xyz/connector-live/`. The website sends them only in a
same-origin HTTPS POST body and keeps them in the browser tab's
`sessionStorage`; neither value is placed in the URL.

Each value has its own `Copy` button. The connector only writes the selected
value to the Windows clipboard after that explicit click; it never reads or
monitors clipboard contents.

The Windows connector uploads only `viewerCodeHash`, never the raw viewer
code. The VPS hashes the code supplied by the website and uses a constant-time
comparison against the private `smart_miners_connector_installations` row.
Only then does it return the latest redacted records for that installation.
The separate heartbeat contains no Mining Wars payload and keeps the online
indicator accurate during quiet periods between game events.
