Dev.to Security 🔐 Cybersecurity Wed, 23 Sep 2026 01:26:07 +0000 👁 0 📖 9 min read

Auditable Node.js Remaining API Headroom for Property Managers (Budget Metrics)

The least complex useful design is a small scheduled exporter that reads the authoritative quota snapshot for a Node.js workload, publishes remaining headroom as a gauge, and records only the evidence needed to explain an alert. For a property-management platform running a leaked-key drill, that means the on-call engineer can answer three separate questions: how much capacity remains, which credential consumed it, and whether revocation actually stopped further use.

TL;DR: alert on both absolute headroom and depletion rate, attach credential and workload identity to an audit record rather than to a high-cardinality metric, and expire raw access events after the investigation window. A single low-watermark alarm is late when consumption accelerates, while an indefinitely retained request log creates a larger security and compliance surface than the drill requires.

The bill is usually made of two different terms: a bounded series such as api_budget_remaining{workload="resident-portal"}, and a potentially unbounded event stream containing every access decision. Suppose the exporter runs every 60 seconds for 30 workloads. That creates 43,200 gauge samples per day before replication, whereas 2 million daily API calls can create 2 million audit events. The event stream is the dominant retention term in that example, by roughly 46 to 1. Changing the polling interval will not rescue a policy that stores every raw event forever.

How should we turn remaining API budget headroom into metrics?

The drill begins when a credential used by the resident portal is presumed exposed. The operational goal is not merely to rotate a string. The team must detect abnormal consumption, identify the affected credential without putting the secret itself into telemetry, revoke it, verify that subsequent uses are denied, reconcile quota accounting, and preserve a reviewable chronology.

That chronology needs stable identifiers and explicit times: a pseudonymous credential ID, workload, property-management function, decision, reason, observed quota, source timestamp, collection timestamp, and correlation ID. Never place the credential value in a label, log field, trace attribute, or alert annotation. OWASP's secrets-management guidance recommends attribution, expiration, revocation, and audit logging around secret use; it also warns that logs must not disclose the secrets they are meant to protect.

The metric and the audit trail have different jobs. Metrics answer “is intervention needed now?” with bounded dimensions. Audit events answer “what happened?” with richer records and stricter access controls. Combining them into a label set, perhaps by adding tenant, building, user, credential, and request ID to every sample, turns an operational gauge into an uncontrolled cardinality index. For the metric, keep labels to a reviewed allowlist such as workload and quota class. For the audit record, hash or otherwise pseudonymize the credential identifier under a separately managed key, include a schema version, and make writes append-only from the exporter's point of view. The audit sink should reject malformed records rather than silently dropping fields. This is the same discipline used for ledger entries: an observation is immutable, and a correction is another observation. It also gives the drill reviewer a finite reconciliation set: accepted observations, rejected observations, alert transitions, and the final revocation decision must balance without relying on whatever happens to remain in an operator's terminal history.

Keep those paths separate.

Build the scheduled boundary, not a second accounting system

The quota authority remains authoritative. The exporter does not infer remaining capacity by counting local requests, because retries, traffic from another workload, delayed events, and administrative adjustments can all make that reconstruction diverge. It polls a single internal adapter whose response includes limit, used amount, reset time, and the source's observation time; the adapter is where a Node.js account service normalizes its upstream quota response.

Here is the core of a separate Go exporter. It uses only the standard library, rejects incoherent snapshots, exposes a small Prometheus-compatible text response, and writes a compact JSON audit event. The one-minute interval is an illustrative operating choice, not a universal threshold; choose it from the shortest depletion time your response process must catch and the load the quota authority permits.

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "os"
    "sync"
    "time"
)

type Snapshot struct {
    Limit      int64     `json:"limit"`
    Used       int64     `json:"used"`
    ObservedAt time.Time `json:"observed_at"`
    ResetAt    time.Time `json:"reset_at"`
}

type Exporter struct {
    mu        sync.RWMutex
    remaining int64
    observed  time.Time
    valid     bool
}

func (e *Exporter) collect(ctx context.Context, client *http.Client, url string) error {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return err
    }
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    if resp.StatusCode != http.StatusOK {
        return fmt.Errorf("quota source returned status %d", resp.StatusCode)
    }

    var s Snapshot
    if err := json.NewDecoder(resp.Body).Decode(&s); err != nil {
        return err
    }
    if s.Limit < 0 || s.Used < 0 || s.Used > s.Limit || s.ObservedAt.IsZero() {
        return fmt.Errorf("incoherent quota snapshot")
    }

    e.mu.Lock()
    e.remaining, e.observed, e.valid = s.Limit-s.Used, s.ObservedAt, true
    e.mu.Unlock()

    event := map[string]any{
        "schema_version": 1,
        "event_type":     "quota_snapshot_collected",
        "workload":       "resident-portal",
        "remaining":      s.Limit - s.Used,
        "source_time":    s.ObservedAt.UTC(),
        "collected_at":   time.Now().UTC(),
    }
    return json.NewEncoder(os.Stdout).Encode(event)
}

func (e *Exporter) metrics(w http.ResponseWriter, _ *http.Request) {
    e.mu.RLock()
    defer e.mu.RUnlock()
    w.Header().Set("Content-Type", "text/plain; version=0.0.4")
    if !e.valid {
        fmt.Fprintln(w, "quota_snapshot_valid 0")
        return
    }
    fmt.Fprintln(w, "quota_snapshot_valid 1")
    fmt.Fprintf(w, "api_budget_remaining{workload=%q} %d\n", "resident-portal", e.remaining)
    fmt.Fprintf(w, "api_budget_observed_timestamp_seconds{workload=%q} %d\n", "resident-portal", e.observed.Unix())
}

func main() {
    e := &Exporter{}
    client := &http.Client{Timeout: 10 * time.Second}
    source := os.Getenv("QUOTA_SOURCE_URL")
    if source == "" {
        log.Fatal("QUOTA_SOURCE_URL is required")
    }

    go func() {
        ticker := time.NewTicker(time.Minute)
        defer ticker.Stop()
        for {
            ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
            if err := e.collect(ctx, client, source); err != nil {
                log.Printf("quota collection failed: %v", err)
            }
            cancel()
            <-ticker.C
        }
    }()

    http.HandleFunc("/metrics", e.metrics)
    log.Fatal(http.ListenAndServe(":9464", nil))
}

Production authentication belongs in the HTTP transport, using a short-lived workload identity or an injected credential rather than a literal token in source. The source endpoint should also return a versioned schema and reject callers outside the exporter's identity. Those controls keep the example's trust boundary honest without pretending that a metrics process should own account authorization.

This pattern has a clear limitation. A scheduled exporter is inappropriate when the available headroom can disappear inside one polling interval, when the quota authority cannot provide source timestamps, or when a safety-critical request must be rejected synchronously. In those cases, enforce admission at the request path and use the exporter only for observation. The trade-off is added latency and a harder dependency in exchange for a decision made from current state.

There is one subtle scheduling error worth calling out: time.Ticker does not guarantee that every scheduled instant becomes a successful observation. Collection can fail, a process can pause, or the source can return old data. Silence must therefore be measurable. Alert on quota_snapshot_valid == 0 and on the age derived from api_budget_observed_timestamp_seconds; do not reuse the last good remaining value as if it were current.

Silence is data.

Alert on exhaustion risk and data freshness

Two alert conditions cover different failure shapes. An absolute threshold protects workloads that are near exhaustion even if consumption is slow. A rate-based condition estimates whether headroom will survive the response window when usage suddenly accelerates. Both require a freshness guard, because arithmetic over stale observations produces confident nonsense.

For example, an organization might define a response window from its actual on-call and credential-revocation procedure, then page when projected depletion is inside that window. The projection should use a documented lookback, suppress negative rates caused by quota resets, and carry the reset timestamp as context. Avoid presenting the estimate as an exact forecast. Quota use can be bursty.

Very bursty.

An alert state should have an idempotency key such as (policy, workload, quota-period, severity). Re-evaluating the same state updates the existing incident rather than producing another page every minute. A transition from firing to resolved is also recorded, including the policy version and the observation that caused it. This produces exactly-once effects at the notification boundary even though collection and delivery remain at-least-once operations.

The leaked-key drill adds a security correlation: consumption attributed to the suspected credential after its revocation time is a separate high-severity event. A falling headroom gauge alone cannot prove that revocation worked, because legitimate traffic may continue spending the same shared quota. The access-decision trail supplies that proof.

Retention is part of the control design

Keep the low-cardinality gauge long enough to compare normal cycles and investigate gradual changes. Keep summarized alert transitions and drill records according to the organization's audit and legal requirements. Raw per-request access events deserve a shorter, explicitly approved window unless a regulation, litigation hold, or active investigation requires otherwise.

The exact duration cannot be universal: property jurisdictions, lease operations, payment functions, and organizational policies differ. NIST SP 800-92 frames log management as an organization-wide process involving infrastructure, policies, and operational procedures, while OWASP recommends defined retention periods and protection against tampering and unauthorized access. Those are constraints for a policy owner, not permission for an exporter author to invent a compliance number.

Policy owns the number.

This is the deliberate deletion point. After the raw-event window closes, retain aggregated consumption, alert transitions, revocation evidence, schema and policy versions, and the signed drill report; delete request bodies, secret material, and unnecessary subject-level detail. The cost is real: a later investigator may be unable to reconstruct an individual request path. The benefit is also real: fewer sensitive records remain available to an attacker, an over-privileged operator, or an accidental disclosure.

Test deletion as seriously as collection. A retention job should emit a count and cutoff time, support legal holds through an auditable policy decision, and be reconciled against the storage system. “TTL configured” is not evidence that every replica, export, and backup followed the rule.

Ship the drill as a repeatable control

Before deployment, feed the adapter snapshots with monotonic use, a reset, stale timestamps, used > limit, timeouts, and duplicate observations. Verify that malformed input never overwrites the last valid sample, but also that freshness alarms still fire. Then run the leaked-key exercise in a non-production quota scope: create controlled consumption, observe the two alert paths, revoke the test credential, attempt a denied use, and reconcile the audit sequence by correlation ID.

Roll out the exporter with a single workload first. Watch source latency, collection failures, observation age, notification deduplication, audit-sink rejection, and metric cardinality. None of these is decorative telemetry; each one guards a point where the evidence chain can break.

Start narrow.

The final review should be answerable without privileged access to raw secrets: who initiated the drill, which policy version evaluated the signal, what observation opened the incident, when revocation took effect, whether post-revocation access was denied, and which records will expire on what authority. A quota alert is complete only when its operational effect and its audit evidence reconcile.