API 인터페이스 명세서

클래스 시그니처, 파라미터 타입, 반환값 규격 및 메모리 수명주기 (amv-sentinel)

Release: v2.3.0 NPM Version PyPI Version Security Guard License
핵심 가치 제안 (Why It Matters)

보안 감도와 차단 기준을 손쉽게 설정하여 내 서비스의 안전을 완벽하게 통제하는 가이드입니다.

Documentation Correction Notice

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

MemberSignatureReturnsDescription
createSentinel(options)(options: SentinelOptions) → SentinelSentinelFactory 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}) → AnalyticsobjectAggregates 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 | nullstring | nullMasks the host portion of an IPv4/IPv6 address. Same implementation as lib/privacy/network-identifiers.js.

2. SentinelOptions (constructor / createSentinel config)

OptionTypeDefaultDescription
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.
policyPolicydefaultPolicyScoring rule set. Build a custom one with createPolicy().
eventStoreRiskEventStorenullWhere evaluated reports are persisted. Built-in: MemoryRiskEventStore, LocalStorageRiskEventStore. The live site additionally batches to Postgres directly in api/sentinel.js, outside this interface.
counterStoreCounterStoreMemoryFixedWindowCounterStoreBacking store for the burst-rate counter. MemoryCounterStore is also available.
rateKeyProvider(req) => string | nullsession/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 / expectedAudienceKeyResolver / stringunsetRequired 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)

ValueTypical HTTP mappingMeaning
ALLOW200No action; request proceeds normally.
OBSERVE200Logged for visibility; not enforced. Always the result in shadow mode for anything other than ALLOW.
RATE_LIMIT429Burst threshold exceeded for the derived rate key.
REQUIRE_APP_VERIFICATION403 or a verification challengePolicy requires a verified collector token that was not presented or failed verification.
TEMPORARY_DENY403Score crossed the deny threshold with sufficient non-passive evidence (see canTemporarilyDeny guard rail in risk-core.js).
REDIRECT302/307Routes 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

ExportDescription
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 / LocalStorageRiskEventStoreBuilt-in eventStore implementations (in-process memory / browser localStorage).
MemoryCounterStore / MemoryFixedWindowCounterStoreBuilt-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.