Implement shared-secret JWT authentication for backend services

[google-labs-jules]

Problem & Context

Currently, backend microservices (admin-service and storage-service) expose highly sensitive administrative routes (e.g., container management, service state controls) and file system operations (e.g., file deletion) directly to the network. Because these endpoints lack authorization verification, they pose a severe security risk of unauthorized destructive actions or arbitrary system manipulation.

Solution Overview

To secure these services without introducing complex IAM infrastructure or modifying the existing Nginx reverse proxy architecture, we have implemented a Shared Secret JWT Authentication model.

By utilizing the existing NEXTAUTH_SECRET on the Next.js server to sign short-lived (5-minute expiration) HMAC-SHA256 tokens, we establish a secure trust relationship between the frontend gateway and backend microservices. The backend services verify these tokens locally using Node's native crypto module, maintaining high routing performance with zero external dependency overhead.

---

Key Decisions & Rationale

• Token Issue via Backend-For-Frontend (BFF): To prevent exposing the raw NEXTAUTH_SECRET to the client browser, we introduced a Next.js API route (/api/auth/token). This route validates the client's current NextAuth session before issuing a signed, short-lived JWT token.
• 5-Minute Expiration Window: To mitigate token leakage or replay attacks, tokens are configured with a strict 5-minute expiration.
• Native Verification: The Express-based backend services verify the HMAC-SHA256 signature using native Node.js crypto functions. This keeps the backend services lightweight and avoids importing heavy external JWT libraries.
• Dual Transmission Channels: Standard API calls utilize the standard Authorization: Bearer <token> header. For scenarios where headers are unsupported (e.g., direct download links or static media sources), the token is securely appended as a short-lived query parameter.

---

Summary of Changes

1. Frontend & Gateway (Next.js)

• Added /api/auth/token: A server-side API endpoint that verifies the NextAuth user session and signs a secure JWT token containing the issuer, subject, and expiration timestamp.
• Created lib/authFetch.ts: A fetch utility wrapper that transparently fetches a valid token, caches it for its lifetime, and appends it to outgoing requests to secured backend endpoints.
• Refactored Views: Integrated authFetch into container administration actions (app/admin/page.tsx) and file management operations (app/cloud/page.tsx).

2. Backend Microservices (admin-service & storage-service)

• Created Verification Middleware: Added Express middleware to parse incoming authorization headers or fallback query parameters.
• Signature & Validity Check: Validates the signature using the shared secret and asserts that the current timestamp is within the valid token lifetime.
• Strict Access Control: Immediately rejects unauthenticated or invalid requests with an HTTP 401 Unauthorized status before running any service business logic.

---

Verification and Acceptance Criteria

• Direct API Access Denied: Direct, unauthenticated requests to the backend container control or file manipulation endpoints fail with an HTTP 401 Unauthorized status.
• Proxy Compatibility: Verified that authorized headers pass transparently through the existing Nginx reverse proxy configurations with zero routing issues.
• Zero Manual Login Interruptions: Authenticated administrative operations and file management perform flawlessly without additional user login prompts.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sparkpage	Ready	Preview, Comment	Jul 22, 2026 10:05am