Authentication & Rate Limiting

Relevant source files

The following files were used as context for generating this wiki page:

• packages/api/src/middleware/auth.ts
• packages/api/src/tests/api.integration.test.ts
• SECURITY_SUMMARY.md
• SYSTEM_EVALUATION.md
• README.md
• PHASE1_IMPLEMENTATION.md

The Authentication & Rate Limiting system in SecretForge AI provides a multi-layered security framework designed to protect sensitive API endpoints and manage resource consumption. It supports dual authentication methods—JSON Web Tokens (JWT) for user sessions and scoped API Keys for programmatic access—while enforcing tier-based access controls and request quotas to ensure system stability and compliance.

Sources: packages/api/src/middleware/auth.ts, packages/api/src/tests/api.integration.test.ts:182-198

Authentication Architecture

SecretForge AI utilizes a flexible middleware architecture that allows for varying levels of strictness, ranging from mandatory JWT/API Key validation to optional authentication for public endpoints.

Authentication Methods

The system supports two primary authentication mechanisms:

1. JWT Authentication: Primarily used for web-based user sessions. It validates Bearer tokens provided in the Authorization header.
2. API Key Authentication: Used for CLI and automated integrations. It validates custom keys provided via the X-API-Key header. Keys are stored as SHA-256 hashes in the database.

Sources: packages/api/src/middleware/auth.ts:19-71, packages/api/src/middleware/auth.ts:149-174

Data Flow for Authentication

The following diagram illustrates how the auth middleware handles incoming requests by attempting JWT verification before falling back to API Key validation.

This flow ensures that the most secure and context-rich authentication method is attempted first while providing a fallback for CLI-based access.
Sources: packages/api/src/middleware/auth.ts:77-108

Tier-Based Access Control

The system implements Role-Based Access Control (RBAC) based on subscription tiers. User information extracted during authentication includes a tier attribute which is used to restrict access to high-value features such as AI-powered secret rotation or compliance reporting.

Subscription Tiers

Tier	Description	AI Features Access
Free	Basic secret management for individuals	No
Pro	Advanced management for power users	Yes
Team	Collaboration features for small teams	Yes
Enterprise	Full compliance and SSO for organizations	Yes

Sources: packages/api/src/middleware/auth.ts:5-10, packages/api/src/tests/api.integration.test.ts:200-234

Tier Enforcement Logic

The requireTier middleware intercepts requests and compares the user's tier against a whitelist of allowed tiers. If the tier is insufficient, a 403 Forbidden error is returned.

Rate Limiting and Quotas

Rate limiting is enforced based on user tiers to prevent abuse and ensure fair resource distribution. The system monitors request counts over specific time windows using a KV store.

Request Quotas by Tier

Metric	Free Tier	Pro/Enterprise Tier
Request Limit	200 per window	Higher/Unlimited
Concurrent Sessions	Limited	High/Configurable

Sources: packages/api/src/tests/api.integration.test.ts:182-198

Rate Limit Enforcement

The rate limiting mechanism triggers a 429 Too Many Requests status code once the threshold is exceeded. In integration tests, this is verified by simulating high-volume bursts of requests.

Sources: packages/api/src/tests/api.integration.test.ts:194-197

Security Implementation Details

API Key Security

API keys are generated with a sf_ prefix followed by a 32-character random string. To prevent leakage, the API never stores the raw key. Instead, keys are hashed using SHA-256 before being queried against the api_keys table in the D1 database.

Sources: packages/api/src/middleware/auth.ts:149-174, packages/api/src/middleware/auth.ts:251-258

JWT Verification

JWTs are verified using a crypto.subtle HMAC with SHA-256. The verification process includes:

• Signature Validation: Ensures the token was not tampered with.
• Expiration Check: Rejects tokens where the exp claim is in the past.
• Payload Extraction: Sets userId, email, and tier into the application context.

Sources: packages/api/src/middleware/auth.ts:179-219, packages/api/src/middleware/auth.ts:224-249

Summary

The Authentication and Rate Limiting module provides the critical security gateway for SecretForge AI. By supporting both JWT and hashed API keys, it accommodates both user-facing and programmatic interfaces. Tier-based enforcement and request throttling further ensure that system resources are protected and that high-tier features (such as AI Agents) are accessible only to authorized users, maintaining the overall security posture and stability of the platform.

Sources: SYSTEM_EVALUATION.md:81-98, SECURITY_SUMMARY.md:39-55