Free-Tier Quota — {{quota_anon}} / {{quota_token}} Scans per UTC Day

Audience: individual developers and small teams running Stella Ops on the free tier, and operators who need to understand the daily scan limits.

Stella Ops is free for individual developers and small teams. To prevent registry abuse, the scanner enforces a two-tier daily quota that works fully offline. For the request-time enforcement path, see the Quota Enforcement flow diagram.

Mode	Daily ceiling	How to obtain
Anonymous	{{quota_anon}} scans	No registration. Works online or air-gapped.
Free JWT token	{{quota_token}} scans	Email `token@stella-ops.org` (blank body). The bot replies with a signed JWT.

A soft reminder banner appears at 200 scans. Exceeding the limit never blocks you — the CLI/UI introduce a delay instead, detailed below.

1 · Token structure

{
  "iss": "stella-ops.org",
  "sub": "free-tier",
  "tid": "7d2285…",          // 32-byte random token-ID
  "tier": {{ quota_token }}, // daily scans allowed
  "exp": 1767139199          // POSIX seconds — token expiry
}

The token-ID (tid) — not the email — is hashed (SHA-256 + salt) and stored for counter lookup.
Verification uses the bundled public key (keys/cosign.pub), so offline hosts validate tokens locally. An optional exp claim may be present; if absent, the default is a far-future timestamp used solely for schema compatibility.

2 · Enforcement algorithm

Step	Operation	Typical latency
1	`key = sha256(ip)` or `sha256(tid)`	< 0.1 ms
2	`count = INCR quota:<key>` in Valkey (24 h TTL)	0.2 ms (Lua)
3	If `count > limit` → `WAIT delay_ms`	first 30 × 5 000 ms, then 60 000 ms
4	Return `HTTP 429` only if `delay > 60 s` (should never fire under the free tier)	—

Counters reset at 00:00 UTC. For the full request flow, key layout, and metrics, see the Quota Enforcement flow diagram.

3 · CLI / API integration

# Example invocation
docker run --rm \
  -e DOCKER_HOST="$DOCKER_HOST" \                  # remote-daemon pointer
  -v "$WORKSPACE/${SBOM_FILE}:/${SBOM_FILE}:ro" \  # mount SBOM under the same name at container root
  -e STELLA_OPS_URL="https://${STELLA_URL}" \      # where the CLI posts findings
  "$STELLA_URL/registry/stella-cli:latest" \
    scan --sbom "/${SBOM_FILE}" "$IMAGE"

No JWT? The scanner defaults to the anonymous quota.

4 · Data retention & privacy

Data	Retention	Purpose
IP hash (`quota:ip:*`)	7 days, then salted hash only	Abuse rate-limit
Token-ID hash	Until revoked	Counter lookup
Email (token request)	≤ 7 days unless newsletters opted-in	Deliver the JWT

No personal data leaves your infrastructure when running offline.

5 · Common questions

What happens at exactly 200 scans?

The UI/CLI shows a yellow “fair-use reminder”. No throttling is applied yet. Once you cross the full limit, the first 30 over-quota scans incur a 5-second delay; further excess scans delay 60 s each.

Does the quota differ offline?

No. Counters are evaluated locally in Valkey, so the same limits apply even without Internet access.

Can I reset counters manually?

Yes — delete the quota:* keys in Valkey. We recommend letting them expire at midnight to keep statistics meaningful.

6 · Revision history

Version	Date	Notes
2.1	2025-07-16	Consolidated into a single source; delays re-tuned (30 × 5 s → 60 s).
2.0	2025-04-07	Switched quota counters from MongoDB (removed in Sprint 4400) to Valkey (Redis-compatible).
1.0	2024-12-20	Initial free-tier design.

Authoritative source — any doc or website section that references quotas must link to this file instead of duplicating the text.