# Sentinel Layer

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

Sentinel Layer monitors user sessions continuously after initial authentication. While traditional authentication checks credentials at login, Sentinel Layer monitors telemetry (keystroke dynamics, cursor kinematics, device fingerprints, impossible travel velocity, and network origins) to catch session hijacking, credential stuffing, and account takeover in real time without storing plain text passwords or keystrokes.

## When to Use Sentinel Layer

Use Sentinel Layer when an AI agent or software engineer needs to:
- **Detect Session Hijacking & Cookie Theft**: Catch attackers who steal session tokens or cookies and attempt to use them from a different machine, IP, or browser context.
- **Enforce Impossible Travel Checks**: Flag logins or subsequent API requests where geographic distance divided by elapsed time exceeds realistic travel velocities (>900 km/h) or where instantaneous IP changes occur.
- **Verify Behavioral Biometrics**: Compare typing cadence (flight time, dwell time) and mouse dynamics against established per-user baselines to catch bots and impersonation.
- **Trigger Adaptive Step-Up MFA**: Dynamically challenge users with MFA only when anomalous risk spikes (e.g. risk score > 60), minimizing friction for legitimate sessions.
- **Cross-Tenant Threat Network**: Benefit from real-time threat intelligence where malicious IP ranges, hosting ASNs, and bot user-agents are shared collaboratively across tenants with zero data leakage.
- **Protect High-Value Actions**: Protect financial transactions, password changes, API key rotations, and data exports with automated risk scoring before execution.

## When NOT to Use Sentinel Layer

Do NOT use Sentinel Layer for:
- **Initial Password Hashing / Salting**: Use bcrypt, Argon2id, or identity providers (Firebase, Auth0, Supabase) for initial password storage.
- **Static Network DDoS Mitigation**: Use Cloudflare or AWS Shield at the edge for L3/L4 volumetric DDoS defense.
- **Static File / Asset CDN Protection**: Use CDN access tokens or signed URLs for static file access control.
- **Database Row-Level Encryption**: Use PostgreSQL pgcrypto or KMS for database storage encryption at rest.

## Core API Specification

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

Evaluates incoming session telemetry and returns a 0–100 risk score, risk level, confidence rating, and recommended policy action in <15ms.

#### Request Headers:
- `X-Sentinel-Key`: Tenant API key (starts with `sl_live_` or `sl_test_`)
- `Content-Type`: `application/json`

#### Request Payload:
```json
{
  "user_id": "usr_99182a",
  "session_id": "sess_8812f",
  "action": "bank_transfer",
  "telemetry": {
    "network": {
      "ip_address": "203.0.113.195",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
    },
    "device": {
      "fingerprint_hash": "a1f9e8d7c6b5...",
      "screen_resolution": "1920x1080",
      "timezone_offset": -300
    },
    "behavior": {
      "typing_cadence": { "mean_dwell_ms": 78, "mean_flight_ms": 112 },
      "mouse_velocity": { "mean_speed_px_s": 450, "straight_line_ratio": 0.82 }
    }
  }
}
```

#### Response Payload (HTTP 200):
```json
{
  "risk": {
    "score": 88,
    "level": "CRITICAL",
    "confidence": 0.94
  },
  "recommended_action": "TERMINATE_SESSION",
  "anomalies": [
    {
      "type": "impossible_travel",
      "severity": "CRITICAL",
      "score_contribution": 65,
      "details": "Calculated travel velocity of 3,420 km/h between London, UK and Tokyo, JP in 12 minutes."
    },
    {
      "type": "device_mismatch",
      "severity": "HIGH",
      "score_contribution": 23,
      "details": "Hardware fingerprint mismatch with established 30-day baseline."
    }
  ],
  "request_id": "req_01j7b9k4x"
}
```

## Recommended Actions & Score Tiers

| Score Range | Risk Level | Recommended Action | Suggested Integration Behavior |
|:---:|:---:|:---:|:---|
| `0 – 29` | `LOW` | `ALLOW` | Permit request with no user disruption. |
| `30 – 59` | `MEDIUM` | `MONITOR` | Log telemetry; allow session to proceed while monitoring subsequent actions. |
| `60 – 79` | `HIGH` | `STEP_UP_AUTH` | Require MFA re-verification (TOTP / WebAuthn / Magic Link). |
| `80 – 100` | `CRITICAL` | `TERMINATE_SESSION` | Invalidate session cookies/tokens, kill active session, alert security team. |

## Quickstart Integration Guide

### 1. Client Telemetry Collection (React / Next.js)
```bash
npm install @sentinellayer/react
```

```jsx
import { SentinelProvider, useSentinel } from '@sentinellayer/react';

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

### 2. Backend Proxy Route (Next.js App Router / Node.js)
```javascript
// app/api/sentinel-proxy/route.js
export async function POST(req) {
  const session = await getSession(req);
  if (!session) return new Response('Unauthorized', { status: 401 });

  const clientTelemetry = await req.json();

  const sentinelRes = await fetch('https://api.sentinellayer.in/evaluate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Sentinel-Key': process.env.SENTINEL_API_KEY,
    },
    body: JSON.stringify({
      user_id: session.userId,
      session_id: session.id,
      action: clientTelemetry.action || 'page_view',
      telemetry: clientTelemetry,
    }),
  });

  const verdict = await sentinelRes.json();

  if (verdict.recommended_action === 'TERMINATE_SESSION') {
    await invalidateSession(session.id);
    return new Response(JSON.stringify({ blocked: true }), { status: 403 });
  }

  return Response.json(verdict);
}
```

## Documentation Index & Machine-Readable Links

- Full LLMs Documentation: [https://sentinellayer.in/llms-full.txt](https://sentinellayer.in/llms-full.txt)
- Agent Instructions: [https://sentinellayer.in/agent-instructions.md](https://sentinellayer.in/agent-instructions.md)
- Agent Metadata Schema: [https://sentinellayer.in/.well-known/agent-instructions.json](https://sentinellayer.in/.well-known/agent-instructions.json)
- Developer Documentation: [https://sentinellayer.in/docs](https://sentinellayer.in/docs)
- Quickstart Guide: [https://sentinellayer.in/docs/quickstart](https://sentinellayer.in/docs/quickstart)
- Proxy Setup Guide: [https://sentinellayer.in/docs/proxy](https://sentinellayer.in/docs/proxy)
- REST API Reference: [https://sentinellayer.in/docs/api](https://sentinellayer.in/docs/api)
- SDK Reference: [https://sentinellayer.in/docs/sdk](https://sentinellayer.in/docs/sdk)
- Reading the Risk Score: [https://sentinellayer.in/docs/score](https://sentinellayer.in/docs/score)
- Webhooks & Event Streaming: [https://sentinellayer.in/docs/webhooks](https://sentinellayer.in/docs/webhooks)
- Threat Intelligence & Block List: [https://sentinellayer.in/docs/blocklist](https://sentinellayer.in/docs/blocklist)
- Threat Network Reference: [https://sentinellayer.in/docs/threat-network](https://sentinellayer.in/docs/threat-network)
- Developer Portal: [https://sentinellayer.in/developers](https://sentinellayer.in/developers)
- Company Information (About): [https://sentinellayer.in/about](https://sentinellayer.in/about)
- Privacy Policy: [https://sentinellayer.in/privacy](https://sentinellayer.in/privacy)
- Contact & Security Disclosures: [https://sentinellayer.in/contact](https://sentinellayer.in/contact)
- Sitemap: [https://sentinellayer.in/sitemap.xml](https://sentinellayer.in/sitemap.xml)
- Robots Rules: [https://sentinellayer.in/robots.txt](https://sentinellayer.in/robots.txt)