API 인터페이스 명세서
클래스 시그니처, 파라미터 타입, 반환값 규격 및 메모리 수명주기 (amv-sentinel)
보안 감도와 차단 기준을 손쉽게 설정하여 내 서비스의 안전을 완벽하게 통제하는 가이드입니다.
An earlier version of this page described a fictional API (Sentinel.init(), .middleware(), .verifyToken(), .tarpit(), custom exception classes) that did not exist in the shipped package. This page has been rewritten to match the actual exports of amv-sentinel (lib/sentinel/index.js → sentinel.js + risk-core.js + providers/ + policy/edge-policy.js).
1. createSentinel() & the Sentinel class
| Member | Signature | Returns | Description |
|---|---|---|---|
createSentinel(options) | (options: SentinelOptions) → Sentinel | Sentinel | Factory function. Equivalent to new Sentinel(options). |
sentinel.score(req) | (req) → Promise<RiskReport> | Promise<RiskReport> | Full pipeline: collects signals, derives the rate key, increments the burst counter, verifies any presented token, and evaluates the risk policy. This is the primary entry point. |
sentinel.collect(req) | (req) → Promise<{signals, token}> | Promise<object> | Extracts raw telemetry signals and an optional collector token from headers/body without running the policy evaluation. |
sentinel.verify(token) | (token: string | null) → Promise<VerificationOutcome> | Promise<object> | Cryptographically verifies an HMAC collector token via the configured keyResolver. Returns {state: 'NONE'|'VALID'|'FAILED', context, error?}. |
sentinel.synthesizeFootprint(report, req) | (report, req) → Footprint | {visitorId, triageCategory, vendorGroup, webglRenderer, country, city, ...} | Derives a non-PII visitor footprint and triage classification from a risk report. |
sentinel.resolveGeoPayload(req) | (req) → GeoResult | {shouldDeliver, payload, botName, botVendor, contentType, servedBytes, ...} | Decides whether to serve an alternate GEO/markdown payload for an identified AI agent, and returns that payload. |
sentinel.getForensicAnalytics({events, geoLogs}) | ({events, geoLogs}) → Analytics | object | Aggregates stored risk events and GEO delivery logs into dashboard-ready analytics (used by admin.html and api/stats.js). |
sentinel.maskIpAddress(ip) | (ip: string) → string | null | string | null | Masks the host portion of an IPv4/IPv6 address. Same implementation as lib/privacy/network-identifiers.js. |
2. SentinelOptions (constructor / createSentinel config)
| Option | Type | Default | Description |
|---|---|---|---|
mode | 'shadow' | 'enforce' | 'shadow' | 'shadow' computes the risk score but downgrades any TEMPORARY_DENY/RATE_LIMIT decision to OBSERVE — nothing is blocked. 'enforce' preserves the real decision in report.action; the calling application is still responsible for reading report.action and returning the corresponding HTTP status. |
policy | Policy | defaultPolicy | Scoring rule set. Build a custom one with createPolicy(). |
eventStore | RiskEventStore | null | Where evaluated reports are persisted. Built-in: MemoryRiskEventStore, LocalStorageRiskEventStore. The live site additionally batches to Postgres directly in api/sentinel.js, outside this interface. |
counterStore | CounterStore | MemoryFixedWindowCounterStore | Backing store for the burst-rate counter. MemoryCounterStore is also available. |
rateKeyProvider | (req) => string | null | session/IP fallback (see §4) | Function that derives the key used to bucket burst-rate counting. If this returns null for a given request, that request's burst count is never incremented — see the rate-limiting note below. |
keyResolver / expectedAudience | KeyResolver / string | unset | Required for cryptographic token verification (sentinel.verify()). Without these, any presented token fails verification with VERIFIER_CONFIGURATION_MISSING. |
stateFailureMode | 'OBSERVE_ONLY' | 'FAIL_CLOSED' | 'OBSERVE_ONLY' | Behaviour when the event/counter store throws. 'OBSERVE_ONLY' swallows the error and continues (fail-open); 'FAIL_CLOSED' re-throws. |
3. SentinelAction (report.action values)
| Value | Typical HTTP mapping | Meaning |
|---|---|---|
ALLOW | 200 | No action; request proceeds normally. |
OBSERVE | 200 | Logged for visibility; not enforced. Always the result in shadow mode for anything other than ALLOW. |
RATE_LIMIT | 429 | Burst threshold exceeded for the derived rate key. |
REQUIRE_APP_VERIFICATION | 403 or a verification challenge | Policy requires a verified collector token that was not presented or failed verification. |
TEMPORARY_DENY | 403 | Score crossed the deny threshold with sufficient non-passive evidence (see canTemporarilyDeny guard rail in risk-core.js). |
REDIRECT | 302/307 | Routes the request to a configured redirectRegistry destination (e.g. a GEO feed or decoy path) instead of blocking outright. |
4. Rate-Limiting Mechanics — Read Before Relying On This
deriveRateKey(req) (used internally by score()) checks, in order: a custom rateKeyProvider, then req.sessionId, then req.testClientId, then browser sessionStorage. None of these are present on an anonymous server-to-server or scripted request by default — if you do not supply a rateKeyProvider, burst counting silently never engages for that traffic. The deployed api/sentinel.js on this site supplies an IP-based rateKeyProvider fallback for this reason; if you integrate the SDK yourself, you should do the same.
5. Standalone Functions & Stores
| Export | Description |
|---|---|
evaluate(signals, options) | Pure scoring function — no I/O, no token verification. Returns a RiskReport synchronously. |
evaluateVerified(signals, verifiedContext, options) | Like evaluate, but incorporates a verified collector-token context into the score. |
classifyBot(userAgent) | Matches a User-Agent string against the built-in BOT_SIGNATURES table (37 entries) and returns a classification. |
createPolicy(overrides) | Builds a custom policy object from defaultPolicy plus overrides (thresholds, bot policy, redirect registry). |
verifyCollectorToken(token, keyResolver, nonceStore, options) | Low-level HMAC token verification used internally by sentinel.verify(). |
signCollectorToken(payload, key, options) | Signs a collector token — used by a trusted client-side or partner integration to produce the token verify() checks. |
MemoryRiskEventStore / LocalStorageRiskEventStore | Built-in eventStore implementations (in-process memory / browser localStorage). |
MemoryCounterStore / MemoryFixedWindowCounterStore | Built-in counterStore implementations for burst-rate tracking. |
resolveProviderAdapter(req) (from providers/index.js) | Picks the correct IP/geo header extraction logic for the hosting edge (Vercel, Cloudflare, Fastly) based on request headers present. |
evaluateEdgePolicy(clientInfo, assessment, options) (from policy/edge-policy.js) | Secondary policy pass applied at the edge layer using resolved client info (IP/geo/ASN) in addition to the core risk assessment. |