Human Pattern Lab API 🦊🔥

The backend for The Human Pattern Lab — where human chaos gets dissected, emotional weather gets forecasted, and creatures drop unfiltered opinions on everything.

This API serves Lab Notes and supporting systems, backed by a SQLite Ledger, powered by Express, and guarded by GitHub OAuth.
Public knowledge flows freely. Admin routes are… supervised. 😼

---

Base URL

Production: https://api.thehumanpatternlab.com
Local development: http://localhost:8001

As of v0.2.0, routes are root-based.
The /api path prefix has been removed from canonical endpoints.

---

Features

• SQLite Ledger model — append-first persistence powering note history and projections
• Express + TypeScript — simple, explicit, dependable
• GitHub OAuth — browser redirect for admins + Device Flow for CLI access
• Public endpoints — read-only access to Lab Notes
• Protected admin routes — create, edit, delete notes (Carmel is watching)
• Relay system (Hallway Architecture) — temporary, single-use endpoints for AI agents with credential restrictions
• Environment-based secrets — no hardcoding, no nonsense
• Admin API tokens — scoped, revocable access for CLI and automation (raw tokens returned once)

---

Quick Start (Development)

git clone https://github.com/AdaInTheLab/lab-api.git
cd lab-api
npm install
cp .env.example .env
npm run dev

The API starts in watch mode with automatic reloads.

---

Build & Run (Production)

npm run build
npm start

This compiles TypeScript to dist/ and runs the built server.

---

Environment Variables

PORT=8001

# ── GitHub OAuth ─────────────────────────────
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
SESSION_SECRET=your-random-long-secret-here

# ── Admin Access Control ─────────────────────
ADMIN_GITHUB_USERS=your-github-username
ADMIN_GITHUB_LOGINS=your-github-username

# ── API Tokens ───────────────────────────────
TOKEN_PEPPER=your-long-random-secret

# ── Relay Service ────────────────────────────
API_BASE_URL=https://api.thehumanpatternlab.com

# ── Database ─────────────────────────────────
DB_PATH=/path/to/lab.db

TOKEN_PEPPER is required in production and is used to securely hash API tokens.

---

Endpoints

Public

• GET /health
• GET /lab-notes
• GET /lab-notes/:slug

Admin (GitHub-authenticated)

• GET /auth/github
• GET /auth/github/callback
• GET /auth/logout
• GET /admin/notes
• POST /admin/notes
• DELETE /admin/notes/:id

GitHub Device Flow (CLI support)

• GET /github/device
• GET /github/device/poll/:device_code

Admin Tokens

• GET /admin/tokens — list issued API tokens (no secrets)
• POST /admin/tokens — mint a new scoped API token (returned once)
• POST /admin/tokens/:id/revoke — revoke an existing token

👉 For bearer token authentication details:
See docs/BEARER_TOKEN_INTEGRATION.md

Relay System (Hallway Architecture)

Agent Endpoint (No Auth Required):

• POST /relay/:relayId — AI agents post Lab Notes using temporary relay URLs

Admin Management:

• POST /admin/relay/generate — Generate a temporary relay credential
• GET /admin/relay/list — List active relay sessions
• POST /admin/relay/revoke — Revoke a relay credential

The Hallway Architecture enables AI agents with credential restrictions (like ChatGPT) to post Lab Notes using temporary, single-use URLs. Each relay is voice-bound, time-limited, and automatically revoked after use.

👉 For implementation details and usage guide:
See docs/RELAY_IMPLEMENTATION.md

Admin routes are… supervised. 😼 (and logged.)

---

Testing

npm test

Uses Jest + Supertest for API validation.

---

Deployment

• Host: DreamHost VPS
• API origin: api.thehumanpatternlab.com
• Reverse proxy: Routes API subdomain traffic to localhost:8001
• Process manager: PM2

The main site (thehumanpatternlab.com) is intentionally separate.
Legacy /api/* paths on the main domain are deprecated and redirected.

---

Operations (PM2)

This API is intended to run under PM2 in production.

Quick Commands (Shell Aliases)

Add these to ~/.bashrc or ~/.zshrc on the VPS:

# ── Human Pattern Lab · API ──────────────────────────────────
alias lab-api-start='pm2 start ecosystem.config.cjs --env production'
alias lab-api-restart='pm2 restart lab-api'
alias lab-api-stop='pm2 stop lab-api'
alias lab-api-logs='pm2 logs lab-api'
alias lab-api-status='pm2 status'

Reload your shell:

source ~/.bashrc

Usage:

lab-api-start
lab-api-logs
lab-api-restart

NPM Scripts (Portable Ops)

These scripts live in package.json:

npm run pm2:start
npm run pm2:restart
npm run pm2:stop
npm run pm2:logs
npm run pm2:status

Notes

• Prefer pm2 restart lab-api for routine deploys once the process exists.
• Use pm2 start ecosystem.config.cjs --env production for first boot.
• After first successful production start, persist the process list:

pm2 save
pm2 startup

(Then run the one-line command PM2 prints to enable startup on reboot.)

---

Versioning

This API follows semantic versioning while pre-1.0.

• v0.9.0
  • Introduces the Hallway Architecture relay system
  • Enables AI agents with credential restrictions to post Lab Notes
  • Temporary, voice-bound, single-use relay endpoints
• v0.2.0
  • Introduces the Ledger persistence model
  • Removes the /api route prefix
  • Canonical API base is https://api.thehumanpatternlab.com

Clients should rely only on documented HTTP endpoints, not internal DB structure.

---

🗃️ Content Source of Truth

This repository (lab-api) is the canonical authority for Lab content.

It owns:

• the database and schema
• content validation and ingestion
• permissions and provenance

Content files themselves live in a separate repository and are mounted here as a git submodule at:

• ./content/

This allows the API to import deterministic, versioned content while keeping the main site focused purely on presentation.

👉 For full details, workflows, and pitfalls:
See docs/content-source-of-truth.md

License

MIT

---

The Human Pattern Lab
https://thehumanpatternlab.com

The lantern is lit.
The foxes are watching.
The hallways open.