Files

Forgotten 80a8ec26f1 Add secrets documentation and inline env migration script

Document secret storage in DATABASE.md and DEVELOPING.md. Update
SPEC-implementation with company_secrets schema and indexes. Add
migrate-inline-env-secrets script for converting existing plain
env values to managed secrets (dry-run by default, --apply to commit).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-19 15:44:11 -06:00

2.3 KiB

Raw Blame History

Developing

This project can run fully in local dev without setting up PostgreSQL manually.

Prerequisites

Node.js 20+
pnpm 9+

Start Dev

From repo root:

pnpm install
pnpm dev

This starts:

API server: http://localhost:3100
UI: served by the API server in dev middleware mode (same origin as API)

Database in Dev (Auto-Handled)

For local development, leave DATABASE_URL unset. The server will automatically use embedded PostgreSQL and persist data at:

./data/embedded-postgres

No Docker or external database is required for this mode.

Quick Health Checks

In another terminal:

curl http://localhost:3100/api/health
curl http://localhost:3100/api/companies

Expected:

/api/health returns {"status":"ok"}
/api/companies returns a JSON array

Reset Local Dev Database

To wipe local dev data and start fresh:

rm -rf server/data/embedded-postgres
pnpm dev

Optional: Use External Postgres

If you set DATABASE_URL, the server will use that instead of embedded PostgreSQL.

Secrets in Dev

Agent env vars now support secret references. By default, secret values are stored with local encryption and only secret refs are persisted in agent config.

Default local key path: ./data/secrets/master.key
Override key material directly: PAPERCLIP_SECRETS_MASTER_KEY
Override key file path: PAPERCLIP_SECRETS_MASTER_KEY_FILE

Strict mode (recommended outside local trusted machines):

PAPERCLIP_SECRETS_STRICT_MODE=true

When strict mode is enabled, sensitive env keys (for example *_API_KEY, *_TOKEN, *_SECRET) must use secret references instead of inline plain values.

CLI configuration support:

pnpm paperclip onboard writes a default secrets config section (local_encrypted, strict mode off, key file path set) and creates a local key file when needed.
pnpm paperclip configure --section secrets lets you update provider/strict mode/key path and creates the local key file when needed.
pnpm paperclip doctor validates secrets adapter configuration and can create a missing local key file with --repair.

Migration helper for existing inline env secrets:

pnpm secrets:migrate-inline-env         # dry run
pnpm secrets:migrate-inline-env --apply # apply migration

2.3 KiB Raw Blame History