퀵스타트 및 실행 레시피
프라이버시 우선 보안 평가 및 듀얼 런타임 미들웨어 연동 표준 코드 (amv-sentinel)
An earlier version of this page showed fabricated code samples (sentinel.middleware(), a non-existent Python amv_sentinel.SentinelMiddleware FastAPI integration, and a non-existent window.SentinelClient.generateAttestationToken() browser global). The recipes below call the real exported API — see the API Reference for full signatures.
1. Serverless API Handler (Node.js / Vercel-style, as actually used in production)
This mirrors the real integration in this site's own api/sentinel.js:
import { createSentinel, MemoryRiskEventStore, MemoryCounterStore } from 'amv-sentinel';
const eventStore = new MemoryRiskEventStore({ maxItems: 1000 });
const counterStore = new MemoryCounterStore();
// IP fallback is required: without a rateKeyProvider, requests with no
// session identifier never get burst-counted (see API Reference §4).
function deriveRateKey(req) {
if (req.sessionId) return `sess_${req.sessionId}`;
const ip = String(req.headers['x-forwarded-for'] || req.headers['x-real-ip'] || '').split(',')[0].trim();
return ip ? `ip_${ip}` : null;
}
const sentinel = createSentinel({
mode: 'enforce', // 'shadow' computes but never blocks
eventStore,
counterStore,
rateKeyProvider: deriveRateKey
});
export default async function handler(req, res) {
const report = await sentinel.score(req);
if (report.action === 'TEMPORARY_DENY') return res.status(403).json({ status: 'denied', traceId: report.traceId });
if (report.action === 'RATE_LIMIT') return res.status(429).json({ status: 'rate_limited', traceId: report.traceId });
return res.status(200).json({ status: 'ok', report });
}
2. Edge Middleware (per-request gate before your handler runs)
The SDK's score() call does I/O (counter increment, optional DB write) and is not meant to run on every static asset request. On this site, cheap pattern-based checks (bot UA, SQLi/XSS/probe signatures, IP-keyed rate limiting) run first in middleware.js at the edge; the full SDK scoring in api/sentinel.js runs only for requests that explicitly report telemetry. If your integration needs the SDK's score to gate page requests directly, call sentinel.score(req) from your own edge/middleware layer rather than assuming the two are automatically wired together — they are separate call sites.
// Minimal illustrative pattern — adapt to your framework's middleware API
import { createSentinel } from 'amv-sentinel';
const sentinel = createSentinel({ mode: 'enforce', rateKeyProvider: (req) => req.ip });
export async function middleware(req) {
const report = await sentinel.score(req);
if (report.action === 'TEMPORARY_DENY' || report.action === 'RATE_LIMIT') {
return new Response('Blocked', { status: report.action === 'RATE_LIMIT' ? 429 : 403 });
}
// allow through
}
3. Verified Collector Tokens (optional, cryptographic client attestation)
If you want a client to cryptographically attest telemetry (rather than sending plain, spoofable signal booleans), sign a token server-side or in a trusted context and verify it on ingest:
import { signCollectorToken, verifyCollectorToken, StaticKeyResolver } from 'amv-sentinel';
const keyResolver = new StaticKeyResolver({ keyId: 'k1', secret: process.env.SENTINEL_HMAC_SECRET });
// Issue (trusted context only — never expose the secret to the browser):
const token = await signCollectorToken({ aud: 'my-app', purpose: 'telemetry-collect' }, keyResolver.getSigningKey());
// On the collecting endpoint, createSentinel({ keyResolver, expectedAudience: 'my-app', ... })
// will verify any token presented via the Authorization: Bearer header automatically inside score().
4. SentinelAction Reference (what report.action can be)
| Action | Meaning | Typical response |
|---|---|---|
ALLOW | Clean request | 200, proceed |
OBSERVE | Logged only — always the result of anything non-ALLOW while mode: 'shadow' | 200, proceed, but record for review |
RATE_LIMIT | Burst threshold exceeded for the rate key | 429 with Retry-After |
REQUIRE_APP_VERIFICATION | Policy requires a verified collector token that is missing/invalid | 403 or a verification challenge flow |
TEMPORARY_DENY | Score crossed the deny threshold with non-passive evidence | 403 |
REDIRECT | Routed to a configured destination instead of blocked | 302/307 |