fix(oauth): crash on startup when OAuth keys are missing (#92)

* fix(oauth): crash on startup when OAuth keys are missing

Instead of silently setting oauthClient to null and serving 503 on all
auth endpoints, throw a clear error during server initialization when
JWKS/private key files are missing or Valkey is unavailable. This
prevents deploying an API that looks healthy but cannot authenticate
users.

Test mode (NODE_ENV=test) still skips OAuth initialization.

Closes #92

* ci(deploy): add post-deploy health gate with OAuth verification

After deploying, poll /api/health/ready for up to 30s and verify the
OAuth endpoint returns a non-503 status. Fails the workflow if the API
doesn't become healthy or OAuth keys are missing.

* style: fix prettier formatting in metadata.ts

.github/workflows/deploy.yml

···
           key: ${{ secrets.VPS_SSH_KEY }}
           script: |
             cd /opt/sifa
-            docker compose pull
-            docker compose up -d --force-recreate --remove-orphans
+            docker compose pull sifa-api
+            docker compose up -d --force-recreate --no-deps sifa-api
+            docker image prune -af
+
+      - name: Verify deployment health
+        uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1
+        with:
+          host: ${{ secrets.VPS_HOST }}
+          username: ${{ secrets.VPS_USER }}
+          key: ${{ secrets.VPS_SSH_KEY }}
+          script: |
+            for i in $(seq 1 10); do
+              status=$(curl -sf -o /dev/null -w '%{http_code}' http://127.0.0.1:3100/api/health/ready 2>/dev/null || echo "000")
+              if [ "$status" = "200" ]; then
+                echo "API healthy after $((i * 3))s"
+                # Verify OAuth is functional (should return 400 not 503)
+                oauth_status=$(curl -sf -o /dev/null -w '%{http_code}' -X POST http://127.0.0.1:3100/oauth/login -H 'Content-Type: application/json' -d '{"handle":"test.invalid"}' 2>/dev/null || echo "000")
+                if [ "$oauth_status" = "503" ]; then
+                  echo "FATAL: OAuth not configured — keys may be missing"
+                  exit 1
+                fi
+                echo "OAuth endpoint responding (status: $oauth_status)"
+                exit 0
+              fi
+              echo "Waiting for API... (attempt $i, status: $status)"
+              sleep 3
+            done
+            echo "FATAL: API did not become healthy within 30s"
+            exit 1

src/oauth/metadata.ts

···
 import type { Env } from '../config.js';
 
 export function registerOAuthMetadata(app: FastifyInstance, config: Env) {
-  if (!existsSync(config.OAUTH_JWKS_PATH)) {
-    app.log.warn(
-      `JWKS file not found at ${config.OAUTH_JWKS_PATH}, skipping OAuth metadata registration`,
+  if (config.NODE_ENV !== 'test' && !existsSync(config.OAUTH_JWKS_PATH)) {
+    throw new Error(
+      `JWKS file not found at ${config.OAUTH_JWKS_PATH} — OAuth metadata cannot be registered`,
     );
+  }
+  if (!existsSync(config.OAUTH_JWKS_PATH)) {
     return;
   }
 

src/server.ts

···
 
   app.get('/api/health', async () => ({ status: 'ok' }));
 
-  // Create OAuth client conditionally (skip in test mode or when JWKS file doesn't exist)
+  // Create OAuth client (required in non-test mode)
   let oauthClient = null;
-  if (config.NODE_ENV !== 'test' && valkey && existsSync(config.OAUTH_JWKS_PATH)) {
+  if (config.NODE_ENV !== 'test') {
+    if (!valkey) {
+      throw new Error('Valkey connection required for OAuth — check VALKEY_URL');
+    }
+    if (!existsSync(config.OAUTH_JWKS_PATH)) {
+      const privateKeyPath = config.OAUTH_JWKS_PATH.replace('jwks', 'private-key');
+      throw new Error(
+        `OAuth keys missing — expected ${config.OAUTH_JWKS_PATH} and ${privateKeyPath}. ` +
+          'Generate with: node -e "..." (see sifa-deploy README)',
+      );
+    }
     oauthClient = await createOAuthClient(config, db, valkey);
   }