# Packr Registry

> A CI-friendly, self-hosted private npm registry. JWT auth, OAuth device flow, fine-grained scoped tokens, AI-optimized package discovery, and zero configuration for CI.

Packr is a private npm registry written in Go with a Next.js dashboard. It replaces Verdaccio and GitHub Packages for teams that want a registry designed for CI-first workflows: non-interactive token auth, structured error responses, OAuth device flow for CLI login, and per-scope token permissions.

## Key features

- **CI-first auth** — JWT tokens from `POST /-/v1/login` or OAuth device flow. No cookies, no TTY required.
- **Fine-grained permissions** — tokens have a role (`ci-readonly`, `ci-publish`, `maintainer`, `admin`) and optional scope restriction (e.g. `@blueforge-studio` only).
- **OAuth device flow** — `packr-cli login --provider github` (also google, gitlab, generic OIDC, forge-auth). Follows RFC 8628.
- **AI agent endpoints** — `/agent/:pkg` returns quality score, capabilities, dependencies, and AI-generated documentation.
- **Two-tier storage** — metadata in SQLite or PostgreSQL, tarballs in local FS, S3, Supabase Storage, or Backblaze B2.
- **Webhooks** — package events with HMAC-SHA256 signed payloads and exponential-backoff retry (1m, 5m, 30m, 2h, 24h).
- **Kubernetes ready** — official Helm chart at `helm/packr/`.

## Documentation

- [Home](https://packr.blueforge.studio/): overview and feature highlights
- [Pricing](https://packr.blueforge.studio/pricing): self-hosted free, cloud plans from $10/year
- [Documentation index](https://packr.blueforge.studio/docs): quick start, CLI, API, SDK/MCP

### Core docs (GitHub)

- [API Reference](https://github.com/kristianmandrup/packr-registry/blob/main/docs/API.md): all HTTP endpoints with request/response examples
- [OAuth & Providers](https://github.com/kristianmandrup/packr-registry/blob/main/docs/06-oauth.md): device flow, providers, forge-auth SSO, custom OIDC
- [Token Permissions](https://github.com/kristianmandrup/packr-registry/blob/main/docs/07-tokens.md): roles, scopes, rotation strategy
- [CLI Authentication](https://github.com/kristianmandrup/packr-registry/blob/main/docs/08-cli-auth.md): `packr-cli login`, credential storage, multi-repo setup
- [Operations Guide](https://github.com/kristianmandrup/packr-registry/blob/main/docs/09-operations-guide.md): step-by-step deploy, token setup, troubleshooting
- [Multi-Region](https://github.com/kristianmandrup/packr-registry/blob/main/docs/10-multi-region.md): Fly.io + PostgreSQL read replicas
- [Deployment](https://github.com/kristianmandrup/packr-registry/blob/main/docs/deployment.md): Docker, Fly.io, Vercel, environment variables
- [Security](https://github.com/kristianmandrup/packr-registry/blob/main/docs/SECURITY.md): auth model, rate limiting, CORS, hardening
- [Architecture overview](https://github.com/kristianmandrup/packr-registry/blob/main/docs/00-overview.md): system design
- [Roadmap](https://github.com/kristianmandrup/packr-registry/blob/main/docs/roadmap.md): shipped features and future ideas

## Public API endpoints (no auth)

- `GET https://api.packr.blueforge.studio/health` — health check with region
- `GET https://api.packr.blueforge.studio/openapi.json` — OpenAPI 3.0 spec
- `GET https://api.packr.blueforge.studio/@:scope/:pkg` — package metadata
- `GET https://api.packr.blueforge.studio/@:scope/:pkg/:version` — specific version metadata
- `GET https://api.packr.blueforge.studio/@:scope/:pkg/-/package/:version.tgz` — tarball download (redirects to presigned S3 URL)
- `GET https://api.packr.blueforge.studio/-/search/:scope?q=:query` — search packages
- `GET https://api.packr.blueforge.studio/agent/:pkg` — AI-optimized info with quality score
- `GET https://api.packr.blueforge.studio/agent/search?q=:capability` — capability-based search
- `GET https://api.packr.blueforge.studio/agent/compare?packages=a,b` — side-by-side comparison
- `GET https://api.packr.blueforge.studio/agent/:pkg/deps` — dependency graph
- `GET https://api.packr.blueforge.studio/agent/:pkg/recommendations` — commonly co-used packages
- `GET https://api.packr.blueforge.studio/agent/:pkg/docs` — AI-generated API documentation
- `GET https://api.packr.blueforge.studio/api/v1/orgs/:slug/packages` — public org package listing
- `GET https://api.packr.blueforge.studio/api/v1/users/:username/profile` — public user profile

## Source

- GitHub: [kristianmandrup/packr-registry](https://github.com/kristianmandrup/packr-registry)
- License: source-available, free to self-host
- Live registry: https://api.packr.blueforge.studio
- Live dashboard: https://packr.blueforge.studio