API Authentication and Security
Relevant source files
The following files were used as context for generating this wiki page:
- packages/registry/src/middleware/auth.ts
- packages/registry/src/middleware/csrf.ts
- packages/registry/src/middleware/rate-limit.ts
- packages/registry/src/middleware/session-security.ts
- packages/registry/src/routes/auth.ts
- packages/webapp/public/legal/SECURITY.md
- packages/webapp/public/legal/ACCEPTABLE_USE_POLICY.md
The PRPM registry employs a multi-layered security strategy to protect its API, user data, and packages. This system is built on industry-standard practices, including GitHub OAuth 2.0 for authentication, JSON Web Tokens (JWT) for authorization, and a robust stack of security middleware to mitigate common web vulnerabilities. The primary goals are to ensure data integrity, control access, and prevent abuse.
The security architecture is primarily implemented through a series of Fastify middleware components that handle authentication, authorization, rate limiting, CSRF protection, and secure session management. This ensures that security checks are applied consistently across all relevant API endpoints before any business logic is executed.
Authentication
Authentication is the process of verifying a user's identity. The PRPM registry uses GitHub as its sole OAuth 2.0 provider, meaning it does not store user passwords. Instead, it relies on GitHub to authenticate users and then issues its own JWT to manage sessions.
GitHub OAuth 2.0 Flow
The authentication process is initiated by the client application, which redirects the user to GitHub. After the user authorizes the application, GitHub redirects them back to the PRPM API's callback endpoint with an authorization code. The API then exchanges this code for a GitHub access token, fetches the user's profile, and creates or updates the user in its own database. Finally, it generates a JWT for the user and sends it back to the client.
The following sequence diagram illustrates the complete GitHub OAuth 2.0 authentication flow.
Authentication Endpoints
The authentication flow is managed by a set of dedicated API endpoints.
| Method | Endpoint | Description |
|---|---|---|
GET | /auth/github | Initiates the GitHub OAuth flow by redirecting the user to GitHub's authorization page. |
GET | /auth/github/callback | Handles the callback from GitHub, exchanges the code for a token, and creates a user session. |
POST | /auth/logout | Clears the session cookie, effectively logging the user out. |
GET | /auth/status | Checks if the user has a valid session and returns their authentication status and user data. |
POST | /auth/token | Allows a user to generate a scoped API key (token) for programmatic access. |
Sources: packages/registry/src/routes/auth.ts:25-135
Authorization and Access Control
Once a user is authenticated, authorization determines what actions they are permitted to perform. This is handled by the authMiddleware.
JWT-Based Authorization
For programmatic access and subsequent API requests from the web client, the PRPM registry uses JWTs. The client must include the JWT in the Authorization header as a Bearer token.
The authMiddleware intercepts incoming requests, extracts the token, and verifies its signature and expiration. If the token is valid, the user's information is decoded from the token payload and attached to the Fastify request object as request.user, making it available to all downstream route handlers.
The diagram below shows the logic of the authentication middleware.
API Key Scopes
The system supports scoped API keys, allowing users to generate tokens with limited permissions, such as read-only or publish-only access. This follows the principle of least privilege for programmatic interactions.
Sources: packages/webapp/public/legal/SECURITY.md:100-104
Security Middleware
The PRPM registry uses a suite of security-focused middleware to protect against common threats.
Rate Limiting
To prevent abuse and ensure service availability, the API enforces rate limiting on incoming requests. It uses @fastify/rate-limit with Redis as a distributed store, ensuring limits are applied consistently across all server instances.
Different rate limits are applied based on the user's subscription tier.
| Tier | Rate Limit |
|---|---|
| Free | 10 requests/minute |
| Starter | 100 requests/minute |
| Pro | 500 requests/minute |
| Enterprise | Custom limits |
Sources: packages/registry/src/middleware/rate-limit.ts:9-24, packages/webapp/public/legal/ACCEPTABLE_USE_POLICY.md:175-179
CSRF Protection
To protect against Cross-Site Request Forgery (CSRF) attacks, the application uses @fastify/csrf-protection. This middleware generates a unique token for each user session, which must be included in a request header (e.g., x-csrf-token) for any state-changing operations (like POST, PUT, DELETE). This ensures that requests originate from the legitimate client application and not a malicious third-party site.
Sources: packages/registry/src/middleware/csrf.ts:9-14
Session and Cookie Security
Secure session management is configured via @fastify/session and @fastify/cookie. Cookies are configured with security best practices to prevent session hijacking and other cookie-based attacks.
| Cookie Attribute | Setting | Purpose |
|---|---|---|
secret | string | A long, random string used to sign session IDs, preventing tampering. |
httpOnly | true | Prevents client-side JavaScript from accessing the cookie, mitigating XSS attacks. |
secure | true | Ensures the cookie is only sent over HTTPS connections. |
sameSite | lax | Provides a balance of security and usability, protecting against most CSRF attacks. |
maxAge | number | Defines the session's lifetime, after which it expires automatically. |
Sources: packages/registry/src/middleware/session-security.ts:11-26
Additionally, fastify-helmet is used to set various HTTP security headers (like Content-Security-Policy, X-Content-Type-Options, etc.) to further harden the application against common attacks.
Sources: packages/webapp/public/legal/SECURITY.md:73-74
Conclusion
The PRPM registry's security model is a comprehensive system that combines standard authentication protocols like OAuth 2.0 with a robust middleware stack. By leveraging JWTs for authorization, enforcing rate limits, and implementing CSRF and session protection, the API ensures a secure environment for developers to manage and share AI development artifacts. This layered approach provides defense-in-depth, protecting against a wide range of potential security threats.