Newer
Older
gnexus-book / 30-runbooks / local-auth-testing.md

owner: gmikcon status: active last_reviewed: 2026-11-19 review_interval: 90d confidence: high

source_of_truth: local-auth-setup

Local gnexus-auth testing

How the local Gnexus Book instance is connected to the local gnexus-auth, which runs the same code as production.

Components

  • gnexus-auth: http://gnexus-auth.local (nginx, MariaDB gnexus_auth).
  • Gnexus Book backend: http://127.0.0.1:3005.
  • Gnexus Book UI (Vite): http://127.0.0.1:3006.
  • Gnexus Book MCP: http://127.0.0.1:8001/mcp-protocol/.

Configuration

Runtime configuration lives in server/.env (chmod 600, gitignored). The systemd units load it through EnvironmentFile; the local scripts source it before starting the service. Do not commit it.

Required variables:

GNEXUS_BOOK_STORAGE_BACKEND=db
GNEXUS_BOOK_DATABASE_URL=...
GNEXUS_BOOK_AUTH_CLIENT_ID=...
GNEXUS_BOOK_AUTH_CLIENT_SECRET=...
GNEXUS_BOOK_AUTH_BASE_URL=http://gnexus-auth.local
GNEXUS_BOOK_AUTH_REDIRECT_URI=http://127.0.0.1:3006/auth/callback
GNEXUS_BOOK_AUTH_WEBHOOK_SECRET=...
GNEXUS_BOOK_AUTH_COOKIE_SECURE=false
GNEXUS_BOOK_INTERNAL_KEY_SECRET=...

Store the same secrets in gnexus-creds for any shared or production deployment.

Local OAuth client

  • Slug: gnexus-book-local (owner-provided local client); access mode: all_active_users.
  • Default role: user; the test user is explicitly assigned the editor client role.
  • The client currently defines roles editor, user, docs.write and inventory.write, but no client permissions. Gnexus Book mirrors the roles snapshot and does not depend on client permissions for authorization yet.
  • Redirect URIs: http://127.0.0.1:3006/auth/callback and http://localhost:3006/auth/callback.
  • Local redirect URIs are enabled for this client.
  • Webhook URL: http://127.0.0.1:3005/webhooks/gnexus-auth; insecure HTTP and private network access are explicitly enabled for local testing.

The earlier gnexus-book test client is disabled and its secrets are revoked. The active local client is the owner-provided gnexus-book-local. Production must use an owner-registered client, HTTPS redirect/webhook URLs, a narrower access mode and properly defined permissions.

Test user

A dedicated local user exists for end-to-end tests:

  • Login: gnexus-book-test@local.test.
  • Credentials: ~/.config/gnexus-book/local-auth-test-user.txt (chmod 600, outside the repository).
  • Role: editor on the gnexus-book-local client; client permissions are currently empty, so /me reports roles: ["editor"] and permissions: [].

No real user account is used for automated checks.

Running locally

# Backend with database storage and SSO (loads server/.env)
./scripts/dev-server.sh

# MCP streamable HTTP (loads server/.env)
./scripts/dev-mcp.sh

# UI
cd ui && npm run dev

Open http://127.0.0.1:3006/ and use Sign in. The browser goes through gnexus-auth and returns to /auth/callback; Vite proxies /auth and /webhooks to the backend.

Verification

  • GET /health reports storage: db and checks.db.status: ok.
  • Before sign-in, GET /me returns auth_enabled: true and user: null.
  • After sign-in, GET /me returns the test user with roles: ["editor"] and the client's current permissions (empty until permissions are defined).
  • Protected routes return 401 without a session.
  • /mcp-keys is available with a session.
  • A gnexus-auth webhook.test delivery reaches POST /webhooks/gnexus-auth with 200 OK and appears in webhook_events.
  • POST /auth/logout clears the session and /me returns user: null.

Production differences

  • Register the client in production gnexus-auth and use HTTPS redirect and webhook URLs.
  • Use specific_users or groups instead of all_active_users.
  • Store client and webhook secrets in gnexus-creds; keep only runtime values in .env.
  • Configure the webhook endpoint without insecure HTTP/private-network overrides.
  • Set GNEXUS_BOOK_MCP_ALLOWED_HOSTS to the public MCP hostname and GNEXUS_BOOK_MCP_ALLOWED_ORIGINS to its HTTPS origin, otherwise FastMCP rejects public requests with 421 Invalid Host header.