> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synheart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Synheart Auth Overview

> Hardware-backed device identity and request signing for Synheart mobile SDKs

`synheart-auth` is the mobile-side device-identity SDK. It generates an ECDSA P-256 key pair in hardware (Secure Enclave on iOS, Android Keystore on Android), registers the device with the Synheart auth service, and signs every outbound request from the cloud paths in your app.

The SDK is normatively defined by RFC-AUTH-MOBILE-0001. Mode A (hardware ECDSA) only — backend HMAC API-key flow is out of scope.

<Note>
  If you're using **Synheart Core**, you get `synheart-auth` automatically — Core wires its crypto callbacks into the runtime during `Synheart.initialize`. You only deal with this SDK directly if you're integrating without Core.
</Note>

## What it owns

* Key pair generation in hardware (non-exportable).
* Device registration via challenge + attestation (App Attest on iOS, Play Integrity on Android).
* Request signing per RFC-AUTH-MOBILE-0001 §8.
* Key invalidation detection and recovery.
* Key rotation.
* Clock-skew correction.
* Per-`app_id` scoped identity (a single device can carry independent identities for multiple apps).

## What it does not own

* Crypto primitives — uses Apple `CryptoKit` and Android `KeyStore`.
* Attestation providers — uses App Attest / Play Integrity native APIs.
* Capability and consent tokens — those live in `synheart-core` / runtime.
* Cloud HTTP transport beyond the Synheart Auth endpoints. The SDK returns signed-headers; consumers attach them to their own requests.

## Packages

<CardGroup cols={3}>
  <Card title="Flutter / Dart" icon="flutter">
    `synheart_auth` 0.1.0 — MethodChannel wrapper around the native plugins. No crypto in Dart.
  </Card>

  <Card title="iOS / Swift" icon="apple">
    `SynheartAuth` (SwiftPM + CocoaPods). Crypto runs in Secure Enclave.
  </Card>

  <Card title="Android / Kotlin" icon="android">
    `ai.synheart:synheart-auth`. Crypto runs in Android Keystore.
  </Card>
</CardGroup>

The Dart package is **orchestration-only** — all crypto and attestation lives in the native plugins. Calls flow through `MethodChannel`s into Swift/Kotlin code.

## Public API

The SDK exposes the same surface across all three platforms:

| Method                                         | Purpose                                                                             |
| ---------------------------------------------- | ----------------------------------------------------------------------------------- |
| `configure(baseUrl)`                           | Sets the Synheart Auth base URL. Must be called before any other method.            |
| `isRegistered(appId)`                          | Returns whether a device identity exists locally for this app.                      |
| `registerDevice(appId)`                        | One-time registration. Generates key, attests, calls `/auth/v1/device/register`.    |
| `signRequest(appId, method, path, bodyBytes?)` | Returns six signed headers (see [Signing](/synheart-auth/signing)).                 |
| `getDeviceId(appId)`                           | Returns the server-issued `device_id`, or null when unregistered.                   |
| `rotateKey(appId)`                             | Rotates the signing key while preserving `device_id`.                               |
| `resetDeviceIdentity(appId)`                   | **Destructive.** Wipes local key + device\_id; forces full re-registration.         |
| `correctClockSkew(serverTimestamp)`            | Stores the offset learned from a server-supplied timestamp on a `CLOCK_SKEW` error. |

Dart `SynheartAuth.instance` is a singleton; Kotlin uses `class SynheartAuth` constructed once per app context; Swift uses `class SynheartAuth` with the same shape. All operations that touch the network or hardware return `async`/`Future`/`suspend` per platform.

## Multi-app-id model

A device may hold independent key pairs for multiple `app_id`s. Storage, registration, and signing are scoped per `app_id`; key alias is `synheart_auth_{app_id}` (deterministic). This lets a single device run several Synheart-backed apps without identity collision.

## How Synheart Core consumes it

`synheart-core` does **not** call `SynheartAuth` HTTP-shaped methods directly. Per the runtime-only networking policy:

* The Core SDK constructs a `DeviceAuthProvider` that wraps `SynheartAuth`.
* The Core SDK registers the auth provider's crypto callbacks (`generate_key`, `sign_bytes`, `get_attestation`, `key_exists`, `delete_key`) with the Synheart runtime.
* The runtime owns the network calls to the auth service (challenge → attestation → register).

The Dart-side `registerDevice` / `rotateKey` are flagged in source as "performed by the runtime" — they exist for direct consumers (CLIs, custom integrations) that don't use Core.

## Security invariants (from RFC §6)

1. Private key MUST be hardware-backed and **non-exportable**.
2. Every external request MUST be signed; there is no unsigned path.
3. Signature covers `method + path + timestamp + raw_body_bytes` exactly (not parsed JSON).
4. Server-side timestamp freshness window: **300 seconds**.
5. Nonce replay protection enforced for write endpoints (POST/PUT/PATCH/DELETE); recommended for GET.
6. Key rotation MUST be authenticated by the current key.

## Synheart Auth endpoints used

| Endpoint                          | When                    |
| --------------------------------- | ----------------------- |
| `POST /auth/v1/device/challenge`  | Step 1 of registration. |
| `POST /auth/v1/device/register`   | Step 5 of registration. |
| `POST /auth/v1/device/rotate-key` | Key rotation flow.      |

## Reading order

<CardGroup cols={2}>
  <Card title="Registration" icon="key" href="/synheart-auth/registration">
    Challenge → keygen → attestation → register.
  </Card>

  <Card title="Request Signing" icon="signature" href="/synheart-auth/signing">
    Message construction, the six headers, server-side verification.
  </Card>

  <Card title="State Machine" icon="diagram-project" href="/synheart-auth/state-machine">
    `unregistered → challengeReceived → keyReady → registering → registered`.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/synheart-auth/errors">
    Error taxonomy, key invalidation, clock skew recovery.
  </Card>
</CardGroup>