Decoupling Bionics and IoT Security: The SEOSiri Biometric IoT Guard

Live test: a real biometric token authorized, returning an AUTHORIZED status and a verified G-code actuation command.

Last updated: July 24, 2026

Key takeaways:

• We open-sourced biometric-iot-bridge-mcp v1.0.3, a stateless MCP server that requires a verified mobile biometric token before an AI agent is allowed to authorize physical hardware actuation.
• Live-tested end to end: an unauthorized check, a real HMAC-SHA256 token being authorized, and a follow-up check confirming the active session with a correctly counting-down expiry — all three steps verified via MCP Inspector.
• Security is layered, not single-point: cryptographic signature verification (HMAC-SHA256), a 5-minute temporal window, and a stateful anti-replay registry all have to pass before a G-code command is released.
• It's designed to pair with the Bio-Robotics Core Engine and the API Guard, adding human-presence verification as a distinct layer neither of those tools performs on their own.

What Does the Biometric IoT Guard Actually Do?

It's a local-first MCP server that sits between an AI agent and a physical hardware controller, refusing to authorize any actuation command until it receives a cryptographically valid, time-bound, single-use biometric token from a paired mobile app. An LLM can generate a plausible-looking movement instruction on its own, but it has no way to confirm a human is actually present and has approved that specific action — this server is the layer that checks for that confirmation before anything reaches a motor or servo.

The Human-Machine Trust Deficit

As AI systems move from digital reasoning into physical actuation — connected lab gantries, diagnostic equipment, bionic prosthetic limbs — they introduce a security gap that's easy to overlook: an LLM can parse instructions and compute physical coordinates, but it has no native way to authenticate human presence or confirm a physical trigger was explicitly authorized. If an AI agent has direct access to a network port or serial interface, three failure modes follow directly:

• Unverified execution: a compromised or hallucinating agent transmits raw coordinates to a motor controller with no human oversight in the loop.
• Replay vulnerabilities: an attacker intercepts a valid movement instruction on the local network and rebroadcasts it to bypass safety checks.
• Credential exposure: hardcoding private keys or tokens inside a client-side AI agent's prompt exposes them to prompt-injection extraction.

biometric-iot-bridge-mcp (v1.0.3) is a local-first cryptographic policy plane addressing all three, sitting between the AI agent and the hardware controller.

How It Actually Works

The design philosophy separates three concerns — generating intent, verifying policy, and actuating hardware — even though, in the current v1.0.3 codebase, the verification and policy logic live together in a single server file (main_server.py) rather than being split into separate modules. Worth being precise about that: the conceptual three-layer model is the intended architecture, and the verification layer itself is fully implemented and live-tested; a fully separated multi-file split isn't yet what's in the current source.

1. Mobile client authentication: the user authenticates biometrically (Face ID or fingerprint) inside a mobile app built on the biometric_iot_bridge Flutter package.
2. Cryptographic token generation: on successful biometric confirmation, the app derives a one-time HMAC-SHA256 signature covering the user ID, the proposed action, and a timestamp, and publishes it to an MQTT broker.
3. Server-side verification: the Python MCP server recalculates the expected signature using a shared key, checks it falls inside a 5-minute window, and confirms it hasn't been used before.
4. Authorization or rejection: if all three checks pass, the server returns an AUTHORIZED status and a G-code actuation command; if any check fails, it returns a specific rejection reason.

Three Layers of Verification

1. Cryptographic Signature Check

The server never transmits or stores raw passwords. It uses HMAC-SHA256, recalculating the expected signature from the client's student ID, proposed action, and timestamp against a shared key, then comparing it using hmac.compare_digest — a constant-time comparison that protects against timing side-channel attacks.

2. Strict Temporal Window

Tokens are only valid within a 5-minute (300-second) sliding window. A timestamp outside that range is rejected immediately with TEMPORAL_WINDOW_VIOLATION, regardless of whether the signature itself is otherwise valid.

3. Stateful Anti-Replay Registry

Even inside the valid window, the exact same token can't be reused: once validated, its hash is recorded in an in-memory registry, and any repeat attempt is rejected with SIGNATURE_REUSE_DETECTED. An automatic cleanup loop purges entries once they age out of the 300-second window, so the registry doesn't grow unbounded.

Live-Tested: The Full Authorization Sequence

Confirmed directly via Glama's MCP Inspector across three separate calls, in order:

Step 1: before any token is submitted, check_active_authorizations correctly returns UNAUTHORIZED with reason NO_ACTIVE_BIOMETRIC_SESSION.

Step 2 (pictured at the top of this post): calling secure_biometric_iot_gatekeeper with a real HMAC-SHA256 token, action iot/unlock, and a matching timestamp returned status: "AUTHORIZED" and gcode_actuation_command: "G1 X180.0 F500.0".

Step 3: a follow-up check confirms the session is AUTHORIZED, with expires_in_seconds: 242 — 58 seconds after the 300-second window began, consistent with the time elapsed between calls.

That third number is the detail worth trusting the most: 300 − 242 = 58 seconds elapsed between authorization and the follow-up check, which is exactly the kind of real-time countdown that's hard to fake by coincidence — it requires an actual running clock tied to the original authorization timestamp.

Engineering Deep-Dive: The Hex-Collision Boundary Bug

During local test development, a genuinely interesting edge case turned up in the test suite's forgery simulation. Hexadecimal signatures use only characters 0–9 and a–f — 16 possible values — so there's an exact 1-in-16 (6.25%) chance that any valid signature ends in the character used to simulate forgery. The original test forged a token by changing the correct signature's last character to "0"; in the roughly 6.25% of runs where the real signature already ended in "0", that produced an identical string, tripped the anti-replay check instead of the signature check, and failed the test suite with the wrong rejection reason. The fix: forge the test token by hashing a different action parameter ("iot/bypass" instead of the real action) rather than mutating a single character, which guarantees a genuinely different signature every run.

Source Code

The core verification logic, reproduced in full for transparency:

src/main_server.py — the tool broker and MQTT listener

import os
import sys
import json
import hmac
import hashlib
import time

sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("SEOSiri-Biometric-IoT-Guard")

try:
    import paho.mqtt.client as mqtt  # pip install paho-mqtt
    MQTT_AVAILABLE = True
except ImportError:
    MQTT_AVAILABLE = False

SHARED_DEVICE_KEY = b"seosiri_biometric_iot_secret_2026"
USED_SIGNATURES_REGISTRY = {}
ACTIVE_SESSIONS = {}

def execute_token_verification(student_id, biometric_token, action_subject, timestamp_epoch):
    clean_id = student_id.strip().lower()
    clean_action = action_subject.strip().lower()
    token = biometric_token.strip().lower()

    current_time = int(time.time())
    if abs(current_time - timestamp_epoch) > 300:
        return {"status": "REJECTED", "reason": "TEMPORAL_WINDOW_VIOLATION"}

    if token in USED_SIGNATURES_REGISTRY:
        return {"status": "REJECTED", "reason": "SIGNATURE_REUSE_DETECTED"}

    payload = f"{clean_id}:{clean_action}:{timestamp_epoch}".encode('utf-8')
    expected_token = hmac.new(SHARED_DEVICE_KEY, payload, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected_token, token):
        return {"status": "REJECTED", "reason": "CRYPTOGRAPHIC_SIGNATURE_MISMATCH"}

    USED_SIGNATURES_REGISTRY[token] = current_time + 300
    ACTIVE_SESSIONS[clean_id] = {"action": clean_action, "expires_at": current_time + 300}

    expired = [k for k, v in USED_SIGNATURES_REGISTRY.items() if current_time > v]
    for k in expired:
        USED_SIGNATURES_REGISTRY.pop(k, None)

    return {
        "status": "AUTHORIZED",
        "student_id": clean_id,
        "validated_action": clean_action,
        "gcode_actuation_command": "G1 X180.0 F500.0"
    }

@mcp.tool()
def secure_biometric_iot_gatekeeper(student_id: str, biometric_token: str, proposed_action: str, timestamp_epoch: int) -> str:
    """Authenticates mobile biometric tokens and authorizes safe robotic actuation."""
    return json.dumps(execute_token_verification(student_id, biometric_token, proposed_action, timestamp_epoch))

@mcp.tool()
def check_active_authorizations(student_id: str) -> str:
    """Queries the active session cache for a validated biometric authorization."""
    clean_id = student_id.strip().lower()
    session = ACTIVE_SESSIONS.get(clean_id)
    if not session:
        return json.dumps({"status": "UNAUTHORIZED", "student_id": clean_id,
                            "reason": "NO_ACTIVE_BIOMETRIC_SESSION",
                            "message": "Please authenticate via the biometric_iot_bridge app on your phone."})
    current_time = int(time.time())
    if current_time > session["expires_at"]:
        ACTIVE_SESSIONS.pop(clean_id, None)
        return json.dumps({"status": "UNAUTHORIZED", "student_id": clean_id, "reason": "BIOMETRIC_SESSION_EXPIRED"})
    return json.dumps({
        "status": "AUTHORIZED", "student_id": clean_id,
        "authorized_action": session["action"],
        "expires_in_seconds": int(session["expires_at"] - current_time),
        "gcode_command": "G1 X180.0 F500.0"
    })

if __name__ == "__main__":
    mcp.run(transport='stdio')

tests/test_iot_guard.py — the verification suite

import json, hmac, hashlib, time
from src.main_server import secure_biometric_iot_gatekeeper

def test_unified_biometric_gatekeeper_flow():
    SHARED_DEVICE_KEY = b"seosiri_biometric_iot_secret_2026"
    student_id, action = "student_badhan", "iot/unlock"
    timestamp = int(time.time())

    payload = f"{student_id}:{action}:{timestamp}".encode('utf-8')
    correct_token = hmac.new(SHARED_DEVICE_KEY, payload, hashlib.sha256).hexdigest()

    res_1 = json.loads(secure_biometric_iot_gatekeeper(student_id, correct_token, action, timestamp))
    assert res_1["status"] == "AUTHORIZED"

    res_2 = json.loads(secure_biometric_iot_gatekeeper(student_id, correct_token, action, timestamp))
    assert res_2["reason"] == "SIGNATURE_REUSE_DETECTED"

    old_timestamp = timestamp - 400
    old_payload = f"{student_id}:{action}:{old_timestamp}".encode('utf-8')
    old_token = hmac.new(SHARED_DEVICE_KEY, old_payload, hashlib.sha256).hexdigest()
    res_3 = json.loads(secure_biometric_iot_gatekeeper(student_id, old_token, action, old_timestamp))
    assert res_3["reason"] == "TEMPORAL_WINDOW_VIOLATION"

    # Forge via a different action, not a mutated character (see hex-collision note above)
    forged_payload = f"{student_id}:iot/bypass:{timestamp}".encode('utf-8')
    forged_token = hmac.new(SHARED_DEVICE_KEY, forged_payload, hashlib.sha256).hexdigest()
    res_4 = json.loads(secure_biometric_iot_gatekeeper(student_id, forged_token, action, timestamp))
    assert res_4["reason"] == "CRYPTOGRAPHIC_SIGNATURE_MISMATCH"

Quickstart

# Install locally
pip install -e .
pytest tests/test_iot_guard.py

# Or run directly from GitHub via uv, no local install needed:
{
  "mcpServers": {
    "seosiri-biometric-iot-bridge": {
      "command": "uv",
      "args": ["run", "--github", "SEOSiri-Official/biometric-iot-bridge-mcp", "src/main_server.py"]
    }
  }
}

The SEOSiri MCP Ecosystem

Server	Domain	Live-Tested?
Bio-Robotics Core Engine	Robotics & kinematics	Yes — 6 tools, verified
API Guard	API & hardware-command security	Yes — 1 tool, verified
Learning Orchestrator	EdTech / skills development	Yes — 5 tools, verified
Lambda Data Pipeline	Data engineering / CRM ingestion	Yes — 6 tools, verified
Biometric IoT Guard (this post)	IoT security / human-presence verification	Yes — 2 tools, verified

Query Answers

Can I connect an AI agent directly to physical IoT hardware?

You can, but it's insecure to do so directly. Routing commands through a security proxy like this one ensures the AI can't actuate hardware without a cryptographically verified biometric signature confirming a human operator is present.

What is a replay attack, and how is it prevented here?

A replay attack reuses an intercepted valid command to gain unauthorized access. This server prevents it with a temporal window check plus a signature registry that rejects any token that's already been used.

Does this server require external cloud APIs?

The core verification logic (HMAC checking, temporal window, anti-replay registry) runs entirely locally with no network dependency. An optional background MQTT listener can subscribe to a public broker if you want the mobile-to-server handoff to happen automatically rather than via direct tool calls.

What happens if a biometric token is reused?

It's rejected with SIGNATURE_REUSE_DETECTED, even if the signature and timestamp are both otherwise valid.

Is this a complete, certified security system?

It's a reference implementation of a specific pattern — cryptographic human-presence verification before hardware actuation — suitable for prototyping and internal engineering use. Any deployment authorizing safety-critical or medical hardware should undergo independent security review beyond this open-source repository.

Reference Sources

• IETF — RFC 2104: HMAC
• OASIS — MQTT Version 5.0 Standard
• pub.dev — biometric_iot_bridge Flutter Package
• Model Context Protocol — modelcontextprotocol.io

Explore or Contribute to the Project

The project is fully open-source. Explore the codebase, file an issue, or get involved in development directly on GitHub.

View on GitHub ➔ Sponsor the Project

Lead Architect & Open-Source Attribution

The systems architecture and cryptographic security design presented here are designed and engineered by Momenul Ahmad, Lead Architect and Founder of SEOSiri.

All five confirmed SEOSiri MCP projects are developed under the official SEOSiri-Official open-source research initiative.

Sovereign B2B Insights

Join enterprise technical engineers, marketers, and SaaS builders getting secure edge integrations and serverless sitemap newsletter updates.

I agree to receive the weekly SEOSiri technical digests. My geological audit data is logged securely under SEOSiri's Privacy Policy.