Hardware Verification
The Invariant SDK allows you to verify that a client device is a physical Android handset with a secure hardware keystore. It detects emulators, server farms, and rooted environments using the Secure Enclave (TEE).
Quickstart
The SDK handles the cryptographic handshake. You receive a structured `InvariantResult` containing a definitive Decision and a granular Risk Score.
1. INSTALLATION
dependencies: invariant_sdk: ^0.1.0
2. USAGE
import 'package:invariant_sdk/invariant_sdk.dart';
void main() {
// Initialize with your Publishable Key
Invariant.initialize(
apiKey: "pk_live_...",
mode: InvariantMode.shadow // Use 'enforce' to block bots
);
runApp(MyApp());
}
Future<void> onLogin() async {
// 1. Run Hardware Attestation
final result = await Invariant.verifyDevice();
// 2. Handle Decision
switch (result.decision) {
case InvariantDecision.allow:
// ✅ Device Verified (Hardware TEE Confirmed)
completeLogin();
break;
case InvariantDecision.allowShadow:
// ⚠️ Risk Detected but Allowed (Shadow Mode)
// Log this event to your analytics
logRisk(result.riskScore, result.reason);
completeLogin();
break;
case InvariantDecision.deny:
// ⛔ Blocked (Emulator / Rooted / Clone)
showBlockScreen(reason: result.reason);
break;
}
}Simulation & Testing
You don't need a physical device farm to test your UI. The SDK includes a simulation mode for development.
Simulated Scenarios
The Example App allows you to toggle between network modes to verify your UI's reaction to different threat levels.
- Real Network: Actual TEE Handshake.
- Force Allow: Simulates a clean Pixel 8.
- Force Shadow: Simulates a risk event in audit mode.
- Force Deny: Simulates an emulator block.
Fail-Open Design
If the Invariant Cloud is unreachable, the SDK defaults to allow with the tier UNVERIFIED_TRANSIENT.
This ensures legitimate users are never blocked due to network outages or server maintenance.
Architecture
Hybrid Trust Model
Invariant prioritizes Security first, then User Experience. Some devices (e.g., budget Samsungs) have a secure TEE but refuse to sign metadata like "Model Name".
Hardware Handshake
The TEE generates a key pair and signs a nonce. If this fails (Emulator), we block.
Metadata Enrichment
If the TEE signature includes the Model Name, we use it. If not, we fallback to the OS-reported name.
Policy Decision
The server validates the chain against the Google Root CA and issues a decision (Allow/Deny).
API Reference
The `InvariantResult` object.
| Field | Type | Description |
|---|---|---|
| decision | enum | allow, allowShadow, or deny. Use this for control flow. |
| score | double | Risk Score (0.0 = Safe, 100.0 = Bot). |
| tier | string | The hardware classification (see below). |
| reason | string? | Diagnostic reason for denial or shadow flag. |