Security Documentation

1. Security Overview

The Packr registry has been hardened against the OWASP Top 10 and common npm registry attack vectors, including tarball path traversal, package hijacking, brute-force credential attacks, webhook SSRF, and denial-of-service via large uploads or high request volume. This document describes the security controls in place.

2. Authentication & Authorization

3. Rate Limiting

IP extraction uses the Fly-Client-IP header, which is unforgeable behind the Fly.io proxy. If that header is absent, the implementation falls back to the last IP in X-Forwarded-For.

4. Resource Limits

5. Password Requirements

Passwords are validated on registration and password reset. Requirements:

• Minimum 10 characters
• Maximum 128 characters
• At least one uppercase letter
• At least one lowercase letter
• At least one digit
• At least one special character (!@#$%^&* etc.)

6. Input Validation

7. Package Ownership

• First publish: any authenticated user with a valid token can publish a new package.
• Subsequent publishes: only package owners can publish new versions.
• Ownership is enforced on: publish, deprecate, unpublish, and dist-tag changes.
• Package owners are set automatically on first publish.

8. Session Security

• Sessions are HMAC-SHA256 signed tokens.
• Session cookies are set with HttpOnly, Secure, and SameSite=strict attributes.
• Sessions expire after 7 days.
• Session creation requires the INTERNAL_API_SECRET shared between the Next.js dashboard and the Go backend.

9. CORS Policy

10. Webhook Security

• Payloads are signed with HMAC-SHA256 and delivered with the header X-Packr-Signature: sha256=....
• SSRF protection is applied at both DNS resolution and TCP connect time, blocking private IP ranges.
• Webhooks targeting unresolvable hostnames are blocked.
• Webhook secrets are redacted in list API responses and are only shown at creation time.
• Webhook delivery has a 10-second timeout.

11. Infrastructure Security

• The Docker container runs as a non-root user (packr).
• HTTP server timeouts: ReadTimeout 30s, WriteTimeout 120s, IdleTimeout 60s.
• ReadHeaderTimeout is set to 10s; MaxHeaderBytes is limited to 1 MB.
• Token hashing uses full SHA-256 with no truncation.
• Secrets (JWT_SECRET, SESSION_SECRET) are generated randomly at startup if not configured, with a warning logged. Random secrets are ephemeral and do not persist across restarts.

12. Environment Variables

13. OAuth Device Flow Security

The OAuth device flow (RFC 8628) is implemented with the following security controls:

14. Keychain Credential Storage

The CLI can store tokens in the system keychain rather than a plain file:

• macOS: macOS Keychain (encrypted, locked to user session)
• Windows: Windows Credential Manager
• Linux: libsecret (GNOME Keyring, KWallet)

Keychain storage is recommended for developer workstations. The file-based store (~/.packr/credentials.json) is created with mode 0600 and is acceptable for CI environments where keychain access is unavailable.

15. Scope-Based Access Control

Tokens carry optional scope restrictions in their JWT claims. When scope restrictions are present:

• The token can only be used for packages within the listed scopes.
• Attempts to publish to, unpublish from, or deprecate packages outside the listed scopes are rejected with 403 Forbidden.
• Read operations (install, metadata fetch) respect scope restrictions for private scopes.

Empty scope list means the token applies to all packages (backward compatible with tokens created before the permission system).

16. Token Permission Enforcement

The RequirePermission middleware enforces permissions on every protected route. Permission checks happen after JWT validation:

Request → JWT validation → Permission check → Scope check → Handler

• Missing JWT: 401 Unauthorized
• Valid JWT, wrong permission: 403 Forbidden
• Valid JWT, scope mismatch: 403 Forbidden
• Valid JWT, no permissions claim (legacy): 200 OK (backward compatible)

Permission types: read, publish, unpublish, admin.

17. Account Linking Security

When a user logs in via OAuth, the registry links the OAuth identity to a Packr account by verified email address:

• Only provider-verified emails are used for linking (GitHub: only primary verified email; Google: always verified; GitLab: only verified primary email).
• If no existing Packr account has the email, a new account is created automatically.
• If a Packr account exists with that email, the OAuth identity is linked to it. The user can then log in via password or OAuth interchangeably.
• A single Packr account can have multiple linked OAuth identities (e.g., GitHub + Google with the same email).
• Admins can unlink OAuth identities via the dashboard.

18. Security Audit History

The April 2026 audit covered authentication flows, authorization enforcement, input validation, rate limiting, webhook security, session management, CORS configuration, resource limits, infrastructure hardening, OAuth device flow, and token permission enforcement. All findings have been addressed and verified.