# Security model

## Trust goal

A user must be able to verify that the official Smart Miners Connector:

1. cannot inspect unrelated user files or processes when packaged as the
   declared Windows AppContainer;
2. does not forward GoMining login details, cookies or bearer tokens;
3. sends only the documented, allowlisted and redacted game records to Smart
   Miners;
4. matches the public source and audited build provenance;
5. can start without an external review while clearly showing that verification
   was not performed;
6. accepts an optional signed verification code only when all four security
   answers are signed and bound to the exact build and installation.

## Data flow

```text
Dedicated GoMining WebView2 profile
        |
        | GoMining page creates its own API requests and websocket
        v
Existing page-hook.js
        |
        | in-page messages may contain raw material
        v
connector-bridge.js strict projection
        |
        | no headers, cookies, bearer, query strings or raw frames
        v
C# JsonRedactor + forbidden-material rejection
        |
        v
Visible local event log in connector-owned storage
        |
        | allowlisted records + installation ID + viewer-code hash
        v
Smart Miners HTTPS ingestion route
        |
        | validation, second redaction, rate limit and private service role
        v
Private Supabase tables
```

The connector uploads only redacted `API_RESPONSE` and `WS_EVENT` records to
`https://gominertools.xyz/push/connector/events`. The client contains no
Supabase service-role key. The VPS validates the endpoint/event allowlist,
redacts the payload again, applies size and rate limits, deduplicates events,
and writes them into a private RLS-enabled Supabase table. Failed uploads stay
in a bounded connector-owned retry queue.

The connector generates a separate high-entropy website viewer code and stores
it only in its own state file. The upload envelope contains its SHA-256 hash,
not the raw code. The website Live route accepts the installation ID and raw
viewer code only in an HTTPS POST, hashes it server-side, compares it in
constant time, rate-limits attempts and returns only that installation's
redacted events. The browser keeps the pair in `sessionStorage`, so closing the
tab removes it.

Every thirty seconds the connector sends a heartbeat containing only the
installation ID, viewer-code hash, app version, source revision, artifact hash
and build channel. It contains no Mining Wars payload and only updates the
private registration's `last_seen_at`. The first hash registered for an
installation is immutable through the public routes: later event uploads and
heartbeats can update the row only when they carry that same hash.

## In-page boundary

The existing hook can observe the GoMining page's API and websocket traffic.
That is necessary to extract live data. `connector-bridge.js` is the only
bridge to the desktop host and does not forward:

- `MW_WS_RECV`
- `MW_WS_SEND`
- raw `MW_API_CALL` request headers
- request bodies
- URL query strings
- cookies or token fields

API responses are accepted only from a small endpoint allowlist. Websocket
events are accepted only for round lifecycle, winner, boost usage and the
already minimized `allUsersStateV2` payload.

## Desktop boundary

The C# host applies a second redaction pass and rejects any event that still
contains a forbidden credential key or bearer-shaped value. It writes only
under `%LocalAppData%\SmartMiners\Connector` in unpackaged development mode.

Password saving and general autofill are enabled through Microsoft Edge
WebView2 for the dedicated GoMining profile. The encrypted profile data is
managed locally by the installed Edge runtime under the connector-owned
WebView2 profile. Connector code does not read, enumerate, log or upload saved
credentials or autofill values. `Delete GoMining session` asks Edge WebView2
to clear all data from that dedicated profile.

When the allowlisted round-state API returns `401` or `403`, the connector
performs one automatic Edge page reload and checks the session again. Duplicate
rejections during that reload cannot start another reload. A second rejection
after navigation stops automatic recovery and shows an interactive-login
message. A later successful round-state response resets the state. The
connector never attempts to recreate, export or persist a JWT itself.

Release-candidate and official packaging run at
`uap10:TrustLevel="appContainer"` with
`uap10:RuntimeBehavior="packagedClassicApp"` and declare only
`internetClient`. They must not declare `runFullTrust`,
`broadFileSystemAccess`, library, device, camera, microphone or location
capabilities.

The `Security & review` tab has explicit copy buttons for the anonymous
installation ID, private SMC viewer code and generated security review request. A
click invokes only `Clipboard.SetText` for that displayed value. The connector
never reads, monitors, enumerates or clears clipboard contents.

## Optional independent verification

Verification-capable release candidates compile with
`SMARTMINERS_AUDIT_ENFORCED`; production builds additionally compile with
`SMARTMINERS_OFFICIAL_BUILD`. The gate validates:

- verdict is `pass`;
- SHA-256 of the complete published app tree;
- app version;
- random installation challenge;
- security policy version;
- issue/expiry timestamps;
- positive credential-safety, 2FA-warning, browser-isolation and official
  source-hash answers;
- ECDSA P-256/SHA-256 signature.

No AI or third-party review is required to run the connector. Without a valid code, the
app visibly reports `OPTIONAL - NOT VERIFIED`. The displayed `SMC1` code is a
base64url representation of the signed
attestation, not a password chosen by a reviewer. The connector decodes and
verifies it locally with the bundled public key before writing the attestation
to connector-owned storage. The signer checks a protected approved-release
registry and refuses to sign an unapproved package. Source confirmation means
the package hash matches the approved release published at
`https://smartminers.xyz`; it does not prove which browser route downloaded it.

The security review flow must visibly warn the user to enable 2FA in GoMining.
No AI, reviewer, audit service or Smart Miners may ask for a password,
cookie, session token or 2FA code.

Development builds remain runnable for open-source development but carry a
prominent unofficial warning and cannot use the official signing identity.

## Current verification status

- The user-facing distribution is one
  `SmartMiners-Connector-*-Install.zip`. It contains the exact MSIX,
  test certificate, release record, unpacked package, review source, test
  evidence and SPDX SBOM.
- The outer ZIP SHA-256 is published separately. `RELEASE-INFO.json` and
  `BUNDLE-INFO.json` bind the installer inside that ZIP to its own SHA-256.
- The ZIP itself is never executed. The user may inspect it with any service
  they choose or simply extract it and run the checked installer.
- A self-contained `1.0.4-rc.1` MSIX is produced with an ephemeral test
  signature.
- The signed package unpacks successfully and preserves AppContainer,
  `packagedClassicApp`, `internetClient` and no `runFullTrust`.
- A temporary package registration launched the actual connector process and
  verified `TokenIsAppContainer = true`.
- C# security tests, bridge tests and source capability policy tests pass.
- The external handoff includes the exact artifact, hashes, source snapshot,
  server ingestion boundary, test evidence and an SPDX SBOM.

## Known limitations

- The candidate is test-signed, not signed by a publicly trusted Smart Miners
  production identity.
- The independent audit verdict and protected production audit signer are not
  implemented in this repository.
- The present source is an `uncommitted-workspace` snapshot; a production build
  deliberately requires a clean committed revision.
- The current runtime test proves AppContainer process isolation and startup.
  Full GoMining login/WebView2 data-flow testing remains part of the
  independent clean-VM audit.
- Static and AI review reduce risk but cannot prove absence of every bug.
- GoMining can change its page, API or websocket implementation.
- Google/wallet login popups are blocked by the strict top-level GoMining
  navigation policy in the MVP; direct GoMining login is the supported path.
- Password saving and autofill depend on the installed Edge WebView2 runtime
  and the user's Windows/Edge policies. They are local convenience features,
  not a Smart Miners credential store.
- The upload endpoint is intentionally network-reachable and must remain
  protected by strict server validation, rate limits and private table grants.
- HTTPS makes the Smart Miners VPS a network trust boundary. The client-side
  allowlist prevents it from sending credentials, but users should audit both
  the connector and the bundled server ingestion source for every release.
- Anyone who obtains both the installation ID and private viewer code can read
  that installation's redacted Live feed until the connector state is reset. Users must
  treat the viewer code as private, although it is not a GoMining credential.

Security reports should include the source commit, complete artifact SHA-256 and exact
connector version.
