Device Authentication & Trust API

This section documents all device-related APIs for trust, fingerprinting, and authorization within the OTA Wallet ecosystem.

POST `/device/auth`

Authenticate a device using public key, signal fingerprint, and signed nonce.

Request Body

{
  "device_id": "ota-device-001",
  "wallet": "osmo1abc...",
  "public_key": "BASE64_ENCODED_PUBLIC_KEY",
  "signed_nonce": "SIGNATURE",
  "signal_fingerprint": "sha256:...",
  "firmware_version": "1.0.5"
}

POST `/device/challenge`

Request a signed challenge from server for attestation.

Response

{
  "nonce": "challenge-123456",
  "timestamp": "2025-05-14T16:00:00Z"
}

GET `/device/trust-status/{device_id}`

Returns trust state, OTA linkage, last seen status.

POST `/device/signal-fingerprint`

GET `/device/fingerprint-log/{device_id}`

Returns audit log of registered fingerprints.

Example – Python (SDR or CLI Device)

import requests
import base64
import hashlib
from nacl.signing import SigningKey

key = SigningKey.generate()
public_key = key.verify_key.encode()
nonce = requests.post("https://api.otawallet.com/v1/device/challenge").json()["nonce"]
signature = key.sign(nonce.encode()).signature

payload = {
  "device_id": "ota-sdr-001",
  "wallet": "osmo1abc...",
  "public_key": base64.b64encode(public_key).decode(),
  "signed_nonce": base64.b64encode(signature).decode(),
  "signal_fingerprint": hashlib.sha256(b"my-fingerprint").hexdigest()
}

res = requests.post("https://api.otawallet.com/v1/device/auth", json=payload)
print(res.json())

📱 Example – Android (Kotlin)

val wallet = "osmo1abc..."
val deviceId = "android-01"
val fingerprint = sha256("bluetooth-mac|imei|build")

val json = JSONObject().apply {
  put("device_id", deviceId)
  put("wallet", wallet)
  put("public_key", encodedPubKey)
  put("signed_nonce", signedNonce)
  put("signal_fingerprint", fingerprint)
}

val req = Request.Builder()
  .url("https://api.otawallet.com/v1/device/auth")
  .post(json.toString().toRequestBody())
  .build()

Trust Levels

Level	Meaning
0	Unknown
1	Signal-only (radio/MAC)
3	Wallet-bound, partial
5	Fully trusted validator

These APIs secure OTA-compatible devices and are enforced by CID relay gates, wallet actions, and offline payout eligibility.

POST /device/auth