Local Setup & Token Management

Overview

The Packr registry uses a single shared service account (blueforge-ci) for all internal BlueForge projects. This avoids proliferating user accounts and tokens — one token handles both publishing and installing @blueforge-studio packages across all repos.

Prerequisites

• Node.js 22+ with pnpm
• gh CLI authenticated (gh auth login)
• Access to the Packr registry at https://api.packr.blueforge.studio

How It Works

All contexts use the same blueforge-ci JWT token. The token is a standard npm auth token — pnpm, npm, and yarn all read it from .npmrc.

Local Development Setup

1. Global ~/.npmrc

Your ~/.npmrc should contain these lines (alongside any existing config):

# BlueForge Packr Registry
@blueforge-studio:registry=https://api.packr.blueforge.studio
//api.packr.blueforge.studio/:_authToken=<your-token>

This routes all @blueforge-studio/* package installs and publishes to Packr. All other packages continue to resolve from npmjs.org.

2. Per-Repo .npmrc (for CI)

Each repo that publishes or consumes @blueforge-studio packages should have a .npmrc in its root:

@blueforge-studio:registry=https://api.packr.blueforge.studio
//api.packr.blueforge.studio/:_authToken=${PACKR_TOKEN}

The ${PACKR_TOKEN} variable is resolved from the environment — set as a GitHub secret for CI, or from your shell for local use.

3. Store CI Credentials

The blueforge-ci password is stored locally for token rotation:

echo 'your-password-here' > ~/.packr-credentials
chmod 600 ~/.packr-credentials

This file is only read by the rotation script. It is never committed to any repo.

Publishing a Package

From any repo with a @blueforge-studio scoped package:

# Ensure package.json has publishConfig
# "publishConfig": { "registry": "https://api.packr.blueforge.studio" }

pnpm publish --access restricted

The ~/.npmrc token handles authentication automatically.

Publishing from CI (Gitea Actions)

The blueforge-org monorepo uses tag-based publishing. To publish from other repos, add a workflow like:

- uses: actions/setup-node@v4
  with:
    node-version: 22
    registry-url: https://api.packr.blueforge.studio
    scope: '@blueforge-studio'

- run: pnpm publish --access restricted
  env:
    NODE_AUTH_TOKEN: ${{ secrets.PACKR_TOKEN }}

Installing Packages

From any project with the .npmrc config above:

pnpm add @blueforge-studio/core-agent

No additional setup needed — the registry routing in .npmrc handles it.

Token Rotation

The rotation script mints a login JWT via POST /-/v1/login, so its lifetime is the login session's exp — about 30 days. The rotation script does not mint a registry token row, so none of the registry's own token semantics (scopes, roles, revocation via packr-cli token revoke) apply to it. exp is enforced on both auth paths; there is simply no expires_at column, so no API reports the deadline.

Running Rotation

cd /path/to/packr-registry
./scripts/rotate-token.sh

What It Updates

Schedule

token_expiry_days and rotate_before_days are present in .packr.json but the script never reads them (scripts/rotate-token.sh only pulls registry, ci_user, scope, github_org, github_secret_visibility). Editing them changes nothing; the 30/25 numbers above are a convention, not a setting.

Central Configuration: .packr.json

All registry configuration lives in .packr.json at the repo root — the single source of truth for token rotation, repo list, and registry settings:

```json
{
  "registry": "https://api.packr.blueforge.studio",
  "scope": "@blueforge-studio",
  "ci_user": "blueforge-ci",
  "token_expiry_days": 30,
  "rotate_before_days": 25,
  "github_org": "blueforge-studio",
  "github_secret_visibility": "all"
}

There is no repos array, and the script does not iterate one. It sets a single org-level secret (gh secret set PACKR_TOKEN --org "$github_org", scripts/rotate-token.sh:114) that covers every repo in the org — which is why no per-repo list is needed.

Adding Repos to Rotation

Nothing to do. Rotation targets the whole org via github_org; a new repo under blueforge-studio inherits the secret automatically. An earlier revision of this document told you to add the repo to a repos array in .packr.json — that key does not exist in the file and the script never reads it, so following those instructions would have rotated nothing per-repo.

Manual Rotation

If the script is unavailable, rotate manually:

# 1. Get new token
curl -s -X POST https://api.packr.blueforge.studio/-/v1/login \
  -H 'Content-Type: application/json' \
  -d '{"name":"blueforge-ci","password":"<password>"}' | jq -r .token

# 2. Update ~/.npmrc with new token

# 3. Update each GitHub repo
gh secret set PACKR_TOKEN --body "<new-token>" --repo blueforge-studio/<repo>

Troubleshooting

Architecture

Developer Machine                    Gitea Actions (forge-git)
┌─────────────┐                     ┌──────────────────┐
│ ~/.npmrc     │                     │ PACKR_TOKEN      │
│ (auth token) │                     │ (org secret)     │
└──────┬──────┘                     └────────┬─────────┘
       │                                      │
       ▼                                      ▼
┌─────────────────────────────────────────────────────┐
│       Cloudflare → Caddy → https://api.packr...     │
│              (Hetzner app-3, loopback :4873)         │
│                                                      │
│  Auth: JWT Bearer token (blueforge-ci)              │
│  Rate: 30 publish/min, 10 login/min per IP          │
│  Storage: Postgres (app_packr_registry) + S3        │
└─────────────────────────────────────────────────────┘

Fly.io and Vercel are both decommissioned. Fly was destroyed 2026-09-09 (packr-registry.fly.dev no longer answers); the site moved off Vercel and deploys via forge-control. An earlier revision of this document described a packr-site Vercel project and gave a Vercel API recipe for reassigning packr.blueforge.studio — that recipe targets a platform this repo no longer uses, and the DNS record it describes is gone.

Deploys

The Caddy route for packr.blueforge.studio is written by the forge-control deployer; DNS points at the right host already, which is why the deploy path passes --no-dns.

One thing to know about the rate limits above: the per-IP keys are derived from Fly-Client-IP first and then the rightmost X-Forwarded-For entry (internal/ratelimit/ratelimit.go:191). Fly is gone, so the first header is client-settable and the second is the closest proxy's value rather than the client's. The limits are not currently enforced against a trustworthy client IP — see the defect note in SECURITY.md.