# Sentinel Layer — Complete Technical & API Documentation

> Continuous post-login session security and AI-powered behavioral anomaly detection platform for web applications.

---

## 1. Executive & Architectural Overview

Sentinel Layer is a real-time cybersecurity platform designed to protect authenticated sessions from token theft, session hijacking, credential replay, and account takeover. 

### Why Sentinel Layer Exists (The Post-Login Gap)
Traditional identity solutions (passwords, MFA, Passkeys, OAuth) only verify the user at the login moment. Once authentication succeeds and a session cookie or JWT is issued, the host application assumes the bearer remains legitimate for hours or days. If an adversary steals that session token via info-stealer malware, cross-site scripting (XSS), or network interception, they can impersonate the victim completely without triggering password prompts.

Sentinel Layer closes this gap by gathering continuous, low-overhead browser and backend telemetry to verify that the active session's physical kinematics, device hardware signatures, and network routing remain consistent with the legitimate user.

---

## 2. Core Security Safeguards

1. **Impossible Travel Velocity**: Haversine distance divided by elapsed seconds between consecutive requests. Velocities exceeding realistic commercial airliner speeds (>900 km/h) or zero-second IP jumps across continents immediately trigger high-severity alerts.
2. **Behavioral Biometrics (Keystroke Dynamics)**: Analyzes flight times (interval between releasing key N and pressing key N+1) and dwell times (duration key is depressed) without ever recording the characters typed.
3. **Cursor Kinematics**: Analyzes mouse trajectory curvature, acceleration curves, and straight-line ratio to differentiate organic human hand movement from Puppeteer / Selenium automation scripts.
4. **Device Fingerprint Drift**: Cryptographic hashing of canvas rendering, WebGL context attributes, hardware concurrency, and audio buffer characteristics.
5. **Network Intelligence & Proxy Detection**: Real-time identification of datacenter hosting ranges (AWS, DigitalOcean, Hetzner), Tor exit nodes, and commercial VPN proxies.
6. **Adaptive Step-Up MFA**: Calculates probabilistic Bayesian risk scores from 0 to 100. Rather than annoying users on every action, step-up challenges trigger only when anomalous risk spikes into the HIGH band (60–79).
7. **Cross-Tenant Threat Network**: Collaborative threat intelligence where malicious IP addresses, user agents, and ASN patterns identified on one tenant are propagated across the network using anonymized hashes with automatic decay.
8. **Shadow Mode**: Allows security teams to evaluate Sentinel Layer in staging or production without enforcing blocks, logging what *would have happened* for safe baseline calibration.

---

## 3. Evaluation API Reference

### `POST https://api.sentinellayer.in/evaluate`

The primary telemetry ingestion and evaluation endpoint.

#### Headers
- `X-Sentinel-Key`: Required string. Your Sentinel API key (`sl_live_...` or `sl_test_...`).
- `Content-Type`: `application/json`

#### Request Body
```json
{
  "user_id": "usr_102847",
  "session_id": "sess_991823",
  "action": "user.transfer_funds",
  "telemetry": {
    "network": {
      "ip_address": "198.51.100.24",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)..."
    },
    "device": {
      "fingerprint_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "screen_resolution": "2560x1440",
      "timezone_offset": -330
    },
    "behavior": {
      "typing_cadence": {
        "mean_dwell_ms": 82,
        "mean_flight_ms": 124,
        "sample_count": 48
      },
      "mouse_velocity": {
        "mean_speed_px_s": 520,
        "straight_line_ratio": 0.74
      }
    }
  }
}
```

#### Response Body (HTTP 200 OK)
```json
{
  "risk": {
    "score": 85,
    "level": "CRITICAL",
    "confidence": 0.96
  },
  "recommended_action": "TERMINATE_SESSION",
  "anomalies": [
    {
      "type": "impossible_travel",
      "severity": "CRITICAL",
      "score_contribution": 65,
      "details": "Calculated travel velocity of 4,120 km/h between Berlin, DE and Singapore, SG in 25 minutes."
    },
    {
      "type": "automation_detected",
      "severity": "HIGH",
      "score_contribution": 20,
      "details": "Straight-line mouse kinematics indicating automated webdriver execution."
    }
  ],
  "evaluated_at": "2026-08-24T11:40:00Z",
  "request_id": "req_998124a"
}
```

---

## 4. Risk Levels & Recommended Policy Actions

- **`0 – 29` | LOW (`ALLOW`)**: Normal organic behavior consistent with established baselines.
- **`30 – 59` | MEDIUM (`MONITOR`)**: Minor anomaly detected (e.g. slight IP subnet change, new browser minor version). Allow with increased logging.
- **`60 – 79` | HIGH (`STEP_UP_AUTH`)**: Significant behavioral or location deviation. Require the user to complete secondary authentication (TOTP, WebAuthn, Magic Link).
- **`80 – 100` | CRITICAL (`TERMINATE_SESSION`)**: High confidence session hijacking or active automation attack. Invalidate session cookies, terminate active session, and alert security operations.

---

## 5. Official SDK Packages

### React / Next.js Client SDK: `@sentinellayer/react`
```jsx
import { SentinelProvider } from '@sentinellayer/react';

export default function RootLayout({ children }) {
  return (
    <SentinelProvider endpoint="/api/sentinel-proxy">
      {children}
    </SentinelProvider>
  );
}
```

### Official CLI Tool: `@sentinellayer/cli`
```bash
npm install -g @sentinellayer/cli
sentinel health
sentinel evaluate --event test_payload.json
```

---

## 6. Trust & Privacy Principles

- **Zero-Knowledge Input**: No passwords, PINs, card numbers, or form inputs are ever inspected or stored.
- **Cryptographic Hashing**: Device and behavioral signals are irreversibly transformed into numerical vectors.
- **Configurable Data Retention**: 7 days (Free Trial), 30 days (Starter), 90 days (Pro), Custom (Enterprise).
- **Compliance Alignment**: GDPR, CCPA, and SOC 2 Type II architectural controls.