Authentication and account identity service for the OCode.js ecosystem.
- Auth.js v5 with Google OAuth, GitHub OAuth, and email/password credentials.
- bcryptjs password hashing; plaintext passwords are never stored.
- Prisma + PostgreSQL persistence for users, provider accounts, sessions, and profiles.
- Automatic profile creation for email registration and OAuth sign-up.
- Public profiles at
/u/[username]. - Profile editing, GitHub username linking, follower/following graph, stars, and public activity.
- Readiness endpoint at
GET /api/health.
See .env.example. Configure secrets only in the intended environment; never commit credentials.
DATABASE_URL: dedicated PostgreSQL connection string (pooled Neon URL recommended for serverless runtime).AUTH_SECRET: cryptographically random Auth.js secret.AUTH_URL: canonical application URL.AUTH_GOOGLE_ID/AUTH_GOOGLE_SECRET.AUTH_GITHUB_ID/AUTH_GITHUB_SECRET.
OAuth callback URLs:
https://YOUR-DOMAIN/api/auth/callback/googlehttps://YOUR-DOMAIN/api/auth/callback/github
The account area includes a server-mediated API key manager at /account/keys.
Users can paste a provider key or import a supported .env / JSON file. File parsing
happens locally in the browser; only the selected key value is sent over HTTPS to the
server. The browser receives metadata only and cannot reveal a stored key.
The Next.js server signs a short-lived (60-second) HS256 assertion using
TOKEN_VAULT_ASSERTION_SECRET. The Cloudflare Token Vault verifies that assertion,
scopes every operation to the immutable Auth.js user ID, and stores the credential
using AES-GCM encryption in the dedicated Staging D1 database. The assertion secret
must exist only in server-side Preview environment variables and the Staging Worker
secret store. Do not add it to NEXT_PUBLIC_*, source control, client bundles, or logs.
Required Preview-only settings:
TOKEN_VAULT_URL: the dedicated OCode.js Token Vault Staging Worker URL.TOKEN_VAULT_ASSERTION_SECRET: shared HMAC key, configured as a Vercel encrypted Preview variable and a Cloudflare Worker secret.
The service API never returns plaintext keys to the browser. The admin Vault view is kept separate from user-owned credentials. Do not enable Production until security tests, provider proxy integration, and secret-redaction checks pass.
- Install dependencies:
npm install. - Configure an untracked
.envwith a dedicated development database and auth credentials. - Generate Prisma Client:
npx prisma generate. - Apply reviewed migrations to the development database:
npx prisma migrate deploy. - Start the app:
npm run dev.
Do not use prisma db push against a shared or production database.
| Endpoint | Method | Purpose |
|---|---|---|
/api/register |
POST | Register account and create profile transactionally |
/api/auth/[...nextauth] |
GET, POST | Auth.js sign-in, callbacks, and session |
/api/health |
GET | Configuration and PostgreSQL readiness |
/api/vault/tokens |
GET, POST | Manage per-user encrypted BYOK credentials |
/api/vault/tokens/[id] |
DELETE | Delete an owned credential |
/api/vault/chat |
POST | Server-side OpenAI, Anthropic, and Gemini gateway using an owned key |
/api/profile/me |
GET, PATCH | Read/update authenticated profile |
/api/profile/github |
PATCH | Set public GitHub username |
/api/profile/stars |
GET, POST, DELETE | Manage authenticated user's stars |
/api/profiles/[username] |
GET | Public profile and social counts |
/api/profiles/[username]/follow |
POST, DELETE | Follow/unfollow a public profile |
/api/profiles/[username]/followers |
GET | List followers |
/api/profiles/[username]/following |
GET | List followed profiles |
/api/profiles/[username]/stars |
GET | Public stars |
/api/profiles/[username]/activity |
GET | Public activity feed |
/api/profiles/[username]/github |
GET | Public GitHub profile/repository summary |
200 ready: required environment variables exist and a read-only PostgreSQLSELECT 1succeeds.503 not_configured: required settings are absent.503 unavailable: settings exist but database connectivity failed.
Health readiness does not prove OAuth callbacks or end-to-end registration work. Those require Preview tests.
This repository is linked to Vercel. Work on this branch is Preview-only. Before enabling end-to-end sign-up:
- Provision a dedicated OCode.js Preview PostgreSQL database. Do not reuse any Velclaw database or another application's database.
- Add the database URL and OAuth settings to Vercel Preview only, scoped to this branch where supported.
- Apply committed Prisma migrations to that Preview database.
- Verify health, email registration, duplicate-email handling, invalid credentials, Google/GitHub callbacks, session persistence, profile creation/editing, follow/unfollow, stars, activity, and logout.
- Confirm the deployment target is Preview, not Production.
Do not merge this branch or deploy Production without explicit authorization.
- Add a managed rate limiter to registration and credential login.
- Add email verification and password reset.
- Add end-to-end OAuth/session tests.
- Review dependency audit findings and update vulnerable packages in a separate tested change.
- Add abuse controls and pagination/retention policies for public activity.