feat: local auth testing with Docker (localauth0 + OpenResty proxy) (STIT-338)

.env.example

@@ -0,0 +1,45 @@
+LOG_LEVEL=info
+
+POSTGRES_DB=stitch
+POSTGRES_HOST=db
+POSTGRES_PORT=5432
+
+STITCH_MIGRATOR_PASSWORD=CHANGE_ME_migrator123!
+STITCH_APP_PASSWORD=CHANGE_ME_app123!
+
+STITCH_DB_SCHEMA_MODE="if-empty"
+STITCH_DB_SEED_MODE="if-needed"
+STITCH_DB_SEED_PROFILE="dev"
+
+FRONTEND_ORIGIN_URL=http://localhost:3000
+
+# --- Auth (API) ---
+# AUTH_DISABLED=true bypasses JWT validation for local dev (default).
+# When false, the API validates Bearer tokens using the issuer/audience/JWKS below.
+AUTH_DISABLED=true
+
+# For local auth testing with mock OIDC (docker compose --profile auth-test):
+# AUTH_DISABLED=false
+# AUTH_ISSUER=http://localhost:3100/
+# AUTH_AUDIENCE=stitch-api-local
+# AUTH_JWKS_URI=http://localauth0:3000/.well-known/jwks.json
+#
+# For real Auth0:
+# AUTH_ISSUER=https://<tenant>.auth0.com/
+# AUTH_AUDIENCE=<your-api-identifier>
+# AUTH_JWKS_URI=https://<tenant>.auth0.com/.well-known/jwks.json
+
+# --- Auth (Frontend) ---
+#
+# For local auth testing (localauth0 via CORS proxy on port 3100):
+# VITE_AUTH0_DOMAIN=http://localhost:3100
+# localauth0 hardcodes expected client_id as the literal string "client_id"
+# VITE_AUTH0_CLIENT_ID=client_id
+# VITE_AUTH0_AUDIENCE=stitch-api-local
+# VITE_API_URL=http://localhost:8000/api/v1
+#
+# For real Auth0:
+# VITE_AUTH0_DOMAIN=<tenant>.auth0.com
+# VITE_AUTH0_CLIENT_ID=<spa-client-id>
+# VITE_AUTH0_AUDIENCE=<api-identifier>
+# VITE_API_URL=http://localhost:8000/api/v1

.github/workflows/docker-compose-build.yml

@@ -10,6 +10,6 @@ jobs:
         uses: actions/checkout@v5
 
       - name: Set up example Env file
-        run: cp env.example .env
+        run: cp .env.example .env
 
       - run: docker compose build

.github/workflows/docker-compose-config.yml

@@ -10,6 +10,6 @@ jobs:
         uses: actions/checkout@v5
 
       - name: Set up example Env file
-        run: cp env.example .env
+        run: cp .env.example .env
 
       - run: docker compose config

README.md

@@ -54,6 +54,45 @@ Note: The `db-init` service runs automatically (via `depends_on`) to apply schem
 - `STITCH_DB_SEED_MODE`
 - `STITCH_DB_SEED_PROFILE`
 
+### Auth Testing (optional)
+
+By default, auth is disabled (`AUTH_DISABLED=true`) — all requests get a hardcoded dev user with no token required. To test real JWT auth flows locally with a mock OIDC server:
+
+1. Update `.env`:
+   ```
+   AUTH_DISABLED=false
+   AUTH_ISSUER=http://localauth0:3000/
+   AUTH_AUDIENCE=stitch-api-local
+   AUTH_JWKS_URI=http://localauth0:3000/.well-known/jwks.json
+   ```
+
+2. Start with the `auth-test` profile:
+   ```bash
+   docker compose -f docker-compose.yml -f docker-compose.local.yml --profile auth-test up --build
+   ```
+
+3. Get a token and make requests:
+   ```bash
+   # Health check (always open)
+   curl localhost:8000/api/v1/health
+
+   # No token → 401
+   curl localhost:8000/api/v1/resources/
+
+   # Get a valid token
+   TOKEN=$(curl -s -X POST localhost:3100/oauth/token \
+     -H "Content-Type: application/json" \
+     -d '{"client_id":"client_id","client_secret":"client_secret","audience":"stitch-api-local","grant_type":"client_credentials"}' \
+     | jq -r '.access_token')
+
+   # Authenticated request → 200
+   curl -H "Authorization: Bearer $TOKEN" localhost:8000/api/v1/resources/
+   ```
+
+Swagger UI (`/docs`) also supports the "Authorize" button for token entry.
+
+See [docs/auth-testing.md](docs/auth-testing.md) for the full scenario guide.
+
 ## Reset (wipe DB volumes safely)
 
 Stop containers and delete the Postgres volume (this removes all local DB data):

deployments/stitch-frontend/Dockerfile

@@ -10,6 +10,10 @@ COPY index.html vite.config.js ./
 COPY public/ ./public/
 COPY src/ ./src/
 
+ARG VITE_AUTH0_DOMAIN
+ARG VITE_AUTH0_CLIENT_ID
+ARG VITE_AUTH0_AUDIENCE
+ARG VITE_API_URL
 RUN npm run build
 
 ########################

deployments/stitch-frontend/package.json

@@ -16,6 +16,7 @@
     "test:coverage": "vitest --coverage"
   },
   "dependencies": {
+    "@auth0/auth0-react": "^2.15.0",
     "@tailwindcss/vite": "^4.1.18",
     "@tanstack/react-query": "^5.90.16",
     "react": "^19.2.0",

deployments/stitch-frontend/src/App.jsx

@@ -1,9 +1,13 @@
 import ResourcesView from "./components/ResourcesView";
 import ResourceView from "./components/ResourceView";
+import { LogoutButton } from "./components/LogoutButton";
 
 function App() {
   return (
     <div className="min-h-screen w-screen bg-gray-100 p-8">
+      <div className="max-w-4xl mx-auto flex justify-end mb-4">
+        <LogoutButton />
+      </div>
       <ResourcesView endpoint="/api/v1/resources" />
       <ResourceView className="mt-24" endpoint="/api/v1/resources/{id}" />
     </div>

deployments/stitch-frontend/src/auth/AuthGate.jsx

@@ -0,0 +1,30 @@
+import { useAuth0 } from "@auth0/auth0-react";
+import LoginPage from "../components/LoginPage";
+
+export default function AuthGate({ children }) {
+  const { isLoading, isAuthenticated, error } = useAuth0();
+
+  if (isLoading) {
+    return (
+      <div className="min-h-screen flex items-center justify-center">
+        <p className="text-gray-500 text-lg">Loading...</p>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="min-h-screen flex items-center justify-center">
+        <p className="text-red-600 text-lg">
+          Authentication error: {error.message}
+        </p>
+      </div>
+    );
+  }
+
+  if (!isAuthenticated) {
+    return <LoginPage />;
+  }
+
+  return children;
+}

deployments/stitch-frontend/src/auth/AuthGate.test.jsx

@@ -0,0 +1,62 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { useAuth0 } from "@auth0/auth0-react";
+import { auth0TestDefaults } from "../test/utils";
+import AuthGate from "./AuthGate";
+
+describe("AuthGate", () => {
+  it("shows loading indicator while auth is loading", () => {
+    vi.mocked(useAuth0).mockReturnValue({
+      ...auth0TestDefaults,
+      isLoading: true,
+      isAuthenticated: false,
+    });
+
+    render(
+      <AuthGate>
+        <div>App Content</div>
+      </AuthGate>,
+    );
+
+    expect(screen.getByText("Loading...")).toBeInTheDocument();
+    expect(screen.queryByText("App Content")).not.toBeInTheDocument();
+  });
+
+  it("shows error message when auth fails", () => {
+    vi.mocked(useAuth0).mockReturnValue({
+      ...auth0TestDefaults,
+      isAuthenticated: false,
+      error: new Error("Something went wrong"),
+    });
+
+    render(
+      <AuthGate>
+        <div>App Content</div>
+      </AuthGate>,
+    );
+
+    expect(
+      screen.getByText("Authentication error: Something went wrong"),
+    ).toBeInTheDocument();
+    expect(screen.queryByText("App Content")).not.toBeInTheDocument();
+  });
+
+  it("renders LoginPage when unauthenticated", () => {
+    vi.mocked(useAuth0).mockReturnValue({
+      ...auth0TestDefaults,
+      isAuthenticated: false,
+    });
+
+    render(
+      <AuthGate>
+        <div>App Content</div>
+      </AuthGate>,
+    );
+
+    expect(screen.getByText("Stitch")).toBeInTheDocument();
+    expect(
+      screen.getByRole("button", { name: /log in to continue/i }),
+    ).toBeInTheDocument();
+    expect(screen.queryByText("App Content")).not.toBeInTheDocument();
+  });
+});