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 (internal/ratelimit/ratelimit.go:191) reads Fly-Client-IP first, then X-Forwarded-For, then RemoteAddr.

⚠️ These headers are not trustworthy here

An earlier revision of this document called Fly-Client-IP "unforgeable behind the Fly.io proxy". Fly was decommissioned on 2026-09-09; the registry runs on Hetzner app-3 behind Caddy + Cloudflare. Nothing strips or overwrites a client-supplied Fly-Client-IP, so a direct caller can set it and receive a fresh rate-limit bucket per request — the limits in the table above are bypassable by one header.

The X-Forwarded-For fallback does not rescue it: it takes parts[len(parts)-1], the rightmost entry, which is the value appended by the closest proxy rather than the originating client. Behind a Caddy + Cloudflare chain that is Caddy's own view, so every request through the proxy can share a single key.

This is a code defect, not a documentation one. It is recorded here so the doc stops asserting a protection the registry does not have; the fix is a separate change and needs care — trusting the wrong end of X-Forwarded-For would collapse every client into one bucket and break rate limiting fleet-wide.

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 and a 7-day MaxAge. The other two flags are not uniform, and an earlier revision of this document said they were:

  Cookie	sameSite	secure
  api/auth/token/route.ts:13	lax	NODE_ENV === 'production'
  api/auth/callback/forgeauth/route.ts:35	lax	always true
  api/auth/callback/route.ts:66	strict	NODE_ENV === 'production'
  api/auth/device/callback/route.ts:54	strict	NODE_ENV === 'production'

  The two lax cookies are the ones a cross-site redirect lands on, so they are the deliberate ones; the other two sit behind a same-site POST callback. Note that in a non-production build secure is off on three of the four — the site is only safe on HTTPS because production sets NODE_ENV.

• 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

There is no RequirePermission middleware on any route. The function exists at internal/auth/permissions.go:125 and has unit tests, but nothing mounts it. Each handler calls auth.HasPermission directly, so the checks are per-handler and the pipeline below is a description of the npm publish path only — other ecosystems order these differently or omit some.

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, AUTH_SESSION_READS_REGISTRY=true: 200 OK
• Valid JWT, no permissions claim, AUTH_SESSION_READS_REGISTRY=false (default): 403 Forbidden

The second row was the finding, not the first. POST /-/v1/login mints with neither Permissions nor Scopes, and HasPermission treats an absent permission list as grant-everything. So a dashboard sign-in satisfied publish, unpublish and read while failing only admin — the inverse of what #244 intended when it moved the admin gates onto an explicit check and left these three behind. The old line called this "backward compatible with legacy tokens"; the only credential that reaches that branch in practice is a login session, so it was the gap, described as a feature.

Unpublish and publish-over-existing were already contained by checkPackageOwnership. First publish was not — there is no scope-ownership model to check against, so any authenticated user could create a package in a scope they did not own and take ownership of it. Issue #330; fixed in auth.HasSessionAwarePermission, with auth.IsSession as the single place the distinction is made.

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.