feat(hub): add Microsoft Entra OIDC authentication

.github/workflows/hub-ci.yml

@@ -20,7 +20,17 @@ jobs:
       fail-fast: false
       matrix:
         node: [24, 26]
-        command: [lint, typecheck, test, build, storybook:build, "db:validate", "test:database"]
+        command:
+          [
+            lint,
+            typecheck,
+            test,
+            "test:entra-setup",
+            build,
+            storybook:build,
+            "db:validate",
+            "test:database",
+          ]
     services:
       postgres:
         image: ${{ matrix.command == 'test:database' && 'postgres:18.6-bookworm' || '' }}

CONTRIBUTING.md

@@ -103,6 +103,7 @@ npm run lint
 npm run db:validate
 npm run typecheck
 npm test
+npm run test:entra-setup
 npm run build
 npm run storybook:build
 ```

docs/testing-and-review.md

@@ -44,7 +44,7 @@ When a command gains a dependency or build prerequisite, update its local setup
 
 All CI workflows run on every pull request and push to `main`. Do not skip checks based on changed paths or add jobs that only combine other jobs' results. Configure branch protection to require the individual checks.
 
-Hub reports lint, types, unit tests, database tests, the frontend/API build, Storybook, and Controls/extension checks separately. Only the database test command starts PostgreSQL. The new Hub has no production-image or release jobs.
+Hub reports lint, types, unit tests, Entra setup-script tests, database tests, the frontend/API build, Storybook, and Controls/extension checks separately. Only the database test command starts PostgreSQL. The new Hub has no production-image or release jobs.
 
 Maintainers must update branch rules when required checks change. Editing a workflow does not update those rules.
 

hub/.devcontainer/compose.yaml

@@ -8,6 +8,10 @@ services:
     working_dir: /workspaces/replica/hub
     volumes:
       - ../..:/workspaces/replica:cached
+    env_file:
+      - path: default.env
+      - path: ../.env
+        required: false
     environment:
       DATABASE_URL: postgresql://replica:replica@db:5432/replica
       TEST_DATABASE_URL: postgresql://replica:replica@db:5432/postgres

hub/.devcontainer/default.env

@@ -0,0 +1 @@
+HUB_AUTH_PROVIDER=github

hub/.env.example

@@ -4,8 +4,65 @@ PORT=3001
 # API logging threshold: trace, debug, info, warn, error, fatal, or silent.
 LOG_LEVEL=info
 
+# Public browser origin. Production requires HTTPS; local HTTP must use loopback.
+HUB_ORIGIN=http://127.0.0.1:5173
+
+# Select exactly one user sign-in provider. Hub fails closed when this is absent.
+HUB_AUTH_PROVIDER=github
+
+# Standards-based OIDC. The first documented profile is single-tenant Microsoft Entra ID.
+# The credential reference names another environment variable; Hub never stores the secret.
+# HUB_OIDC_ENABLED=true
+# HUB_OIDC_ISSUER=https://login.microsoftonline.com/<tenant-id>/v2.0
+# HUB_OIDC_CLIENT_ID=
+# HUB_OIDC_CALLBACK_URL=https://hub.example.com/api/auth/oidc/callback
+# HUB_OIDC_CLIENT_CREDENTIAL_REFERENCE=HUB_OIDC_CLIENT_SECRET
+# HUB_OIDC_CLIENT_SECRET=
+# HUB_OIDC_MEMBER_ROLE=Hub.User
+# HUB_OIDC_ADMINISTRATOR_ROLE=Hub.Administrator
+# HUB_OIDC_SCOPES=openid profile email
+# HUB_OIDC_MEMBERSHIP_POLICY=jit-assignment
+# HUB_OIDC_PROVIDER_REVISION=1
+
+# Keep 0 unless the API is reachable only through this exact number of trusted proxies.
+HUB_TRUSTED_PROXY_HOPS=0
+
 # Local development only. The devcontainer supplies its own database hostname.
 DATABASE_URL=postgresql://replica:replica@127.0.0.1:5432/replica
 
 # Only database-enabled tests require this URL and CREATEDB permission.
 TEST_DATABASE_URL=postgresql://replica:replica@127.0.0.1:5432/postgres
+
+# Local reference artifact storage. The default is ~/.replica/artifacts, outside the checkout.
+# Production deployments should mount durable storage here.
+# HUB_ARTIFACT_STORAGE_PATH=/var/lib/replica/artifacts
+
+# GitHub user authorization is optional until both values are configured.
+# These credentials establish user identity and are separate from source integration.
+# HUB_GITHUB_AUTH_CLIENT_ID=
+# HUB_GITHUB_AUTH_CLIENT_SECRET=
+
+# GitHub proves identity by default. github-synchronized admits users through explicitly
+# linked repository sources. legacy-repository preserves the earlier compatibility behavior.
+HUB_ADMISSION_POLICY=hub-managed
+
+# Generate separate host-held values. Bootstrap can enroll the first administrator once.
+# Recovery works only when no active administrator remains and never reopens bootstrap.
+# HUB_BOOTSTRAP_SECRET=<openssl rand -hex 32>
+# HUB_ADMIN_RECOVERY_SECRET=<openssl rand -hex 32>
+
+# Select the GitHub source-integration credential provider. See docs/identity.md.
+HUB_GITHUB_CREDENTIAL_PROVIDER=database
+
+# Generate separate values outside the database. See docs/identity.md.
+# HUB_GITHUB_CREDENTIAL_KEY=<openssl rand -hex 32>
+
+# The environment provider is read-only and requires every source-integration setting below.
+# GITHUB_APP_ID=
+# GITHUB_INSTALLATION_ID=
+# GITHUB_CLIENT_ID=
+# GITHUB_CLIENT_SECRET=
+# GITHUB_PRIVATE_KEY=
+
+# Required only for /api/github/webhooks. Keep it separate from user-auth credentials.
+# HUB_GITHUB_WEBHOOK_SECRET=<GitHub App webhook secret>

hub/.prettierignore

@@ -1,6 +1,7 @@
 /log
 .local
 .npm
+.devcontainer/default.env
 .storybook/instances
 .storybook/settings.json
 node_modules

hub/README.md

@@ -2,9 +2,9 @@
 
 Hub is being rebuilt on `build/hub/new` using TypeScript, Express, React, Vite, and Vitest. This branch lets contributors start the new app locally. It is not ready to replace the existing Hub.
 
-The API has one route: `GET /api/health`. The frontend displays the existing Replica logo and supports light and dark themes. Existing components, features, and pages are kept in Storybook, but they are not connected to the new API.
+The API exposes its health check, GitHub or production OIDC authentication, sessions, installation membership administration, prototype authorization, opt-in GitHub-synchronized admission and prototype baselines, and provider-neutral artifact publishing. The frontend provides configured-provider sign-in, one-use administrator enrollment and recovery, and a minimal membership administration surface. Existing prototype components, features, and pages remain in Storybook, but they are not connected to the new product APIs.
 
-Contributors can use PostgreSQL and Prisma locally or in the devcontainer. The database has no product models yet. Sign-in, saved data, live updates, background jobs, and deployment are not implemented.
+Contributors can use PostgreSQL and Prisma locally or in the devcontainer. One configured GitHub or OIDC provider proves user identity. Hub-owned admission, optional GitHub-synchronized authorization with Hub overrides, invitations, membership roles and lifecycle, administrator recovery, session revocation, prototype metadata, and artifact ingestion are implemented. Previews, reviews, SCIM, live updates, general background-job infrastructure, and deployment are not implemented.
 
 Use [Development](docs/development.md) to start the API and frontend. Review [Architecture](docs/architecture.md), [code architecture conventions](docs/backend-architecture.md), and [coding conventions](docs/coding-conventions.md) before adding behavior.
 

hub/app/javascript/application/authentication/index.test.tsx

@@ -0,0 +1,175 @@
+import { ThemeProvider } from "@primer/react-brand"
+import { fireEvent, render, screen, waitFor } from "@testing-library/react"
+import { describe, expect, it, vi } from "vitest"
+
+import { AuthenticationApplication } from "."
+
+describe("AuthenticationApplication()", () => {
+  it("offers provider-role recovery through the configured sign-in flow", async () => {
+    window.history.replaceState({}, "", "/?authentication=failed&reason=provider_role_changed")
+    const authorizationUrl = "#provider-role-recovery"
+    const session = {
+      authenticated: true,
+      configured: true,
+      provider: "oidc",
+      providerLabel: "Company SSO",
+      csrfToken: "session-csrf-token",
+      user: { id: "administrator", displayName: "Hub administrator" },
+      membership: { id: "administrator-membership", role: "administrator", status: "active" },
+    }
+    const administration = { memberships: [], invitations: [] }
+    const fetch = vi.fn((input: RequestInfo | URL, init?: RequestInit) => {
+      if (input === "/api/session" && init?.method === undefined) {
+        return Promise.resolve(Response.json(session))
+      }
+      if (input === "/api/administration" && init?.method === undefined) {
+        return Promise.resolve(Response.json(administration))
+      }
+      if (input === "/api/auth/oidc") {
+        return Promise.resolve(Response.json({ authorizationUrl }))
+      }
+      return Promise.reject(new Error("Unexpected request"))
+    })
+    vi.stubGlobal("fetch", fetch)
+    render(
+      <ThemeProvider>
+        <AuthenticationApplication />
+      </ThemeProvider>,
+    )
+
+    expect(await screen.findByRole("alert")).toHaveTextContent(
+      "Your provider role changed. Sign in again to update your Hub access.",
+    )
+    fireEvent.click(screen.getByRole("button", { name: "Sign in again" }))
+
+    await waitFor(() => expect(window.location.hash).toBe(authorizationUrl))
+    expect(fetch).toHaveBeenCalledWith("/api/auth/oidc", {
+      method: "POST",
+      credentials: "same-origin",
+      headers: { "X-CSRF-Token": "session-csrf-token" },
+    })
+  })
+
+  it("starts fresh verification instead of presenting a failed administration mutation as success", async () => {
+    const authorizationUrl = "#provider-authorization"
+    const session = {
+      authenticated: true,
+      configured: true,
+      provider: "github",
+      providerLabel: "GitHub",
+      csrfToken: "session-csrf-token",
+      user: { id: "administrator", displayName: "Hub administrator" },
+      membership: { id: "administrator-membership", role: "administrator", status: "active" },
+    }
+    const administration = {
+      memberships: [
+        {
+          id: "member-membership",
+          status: "active",
+          role: "member",
+          user: {
+            id: "member",
+            displayName: "Hub member",
+            externalIdentities: [],
+          },
+        },
+      ],
+      invitations: [],
+    }
+    const fetch = vi.fn((input: RequestInfo | URL, init?: RequestInit) => {
+      if (input === "/api/session" && init?.method === undefined) {
+        return Promise.resolve(Response.json(session))
+      }
+      if (input === "/api/administration" && init?.method === undefined) {
+        return Promise.resolve(Response.json(administration))
+      }
+      if (input === "/api/administration/memberships/member-membership") {
+        return Promise.resolve(
+          Response.json(
+            { error: "fresh_authorization_required", message: "Verify before continuing." },
+            { status: 403 },
+          ),
+        )
+      }
+      if (input === "/api/session/verify") {
+        return Promise.resolve(Response.json({ authorizationUrl }))
+      }
+      return Promise.reject(new Error("Unexpected request"))
+    })
+    vi.stubGlobal("fetch", fetch)
+    render(
+      <ThemeProvider>
+        <AuthenticationApplication />
+      </ThemeProvider>,
+    )
+    const member = (await screen.findByText("Hub member")).closest("li")!
+
+    fireEvent.click(screen.getByRole("button", { name: "Suspend" }))
+
+    await waitFor(() => expect(window.location.hash).toBe(authorizationUrl))
+    expect(fetch).toHaveBeenCalledWith("/api/session/verify", {
+      method: "POST",
+      credentials: "same-origin",
+      headers: { "X-CSRF-Token": "session-csrf-token" },
+    })
+    expect(member).toHaveTextContent("member · active")
+    expect(fetch.mock.calls.filter(([input]) => input === "/api/session")).toHaveLength(1)
+  })
+
+  it("shows a useful error when fresh verification cannot start", async () => {
+    const session = {
+      authenticated: true,
+      configured: true,
+      provider: "github",
+      providerLabel: "GitHub",
+      csrfToken: "session-csrf-token",
+      user: { id: "administrator", displayName: "Hub administrator" },
+      membership: { id: "administrator-membership", role: "administrator", status: "active" },
+    }
+    const administration = {
+      memberships: [
+        {
+          id: "member-membership",
+          status: "active",
+          role: "member",
+          user: {
+            id: "member",
+            displayName: "Hub member",
+            externalIdentities: [],
+          },
+        },
+      ],
+      invitations: [],
+    }
+    const fetch = vi.fn((input: RequestInfo | URL, init?: RequestInit) => {
+      if (input === "/api/session" && init?.method === undefined) {
+        return Promise.resolve(Response.json(session))
+      }
+      if (input === "/api/administration" && init?.method === undefined) {
+        return Promise.resolve(Response.json(administration))
+      }
+      if (input === "/api/administration/memberships/member-membership") {
+        return Promise.resolve(
+          Response.json({ error: "fresh_authorization_required" }, { status: 403 }),
+        )
+      }
+      if (input === "/api/session/verify") {
+        return Promise.resolve(Response.json({ error: "provider_unavailable" }, { status: 503 }))
+      }
+      return Promise.reject(new Error("Unexpected request"))
+    })
+    vi.stubGlobal("fetch", fetch)
+    render(
+      <ThemeProvider>
+        <AuthenticationApplication />
+      </ThemeProvider>,
+    )
+    await screen.findByText("Hub member")
+    const currentUrl = window.location.href
+
+    fireEvent.click(screen.getByRole("button", { name: "Suspend" }))
+
+    expect(await screen.findByRole("alert")).toHaveTextContent("Hub could not start verification.")
+    expect(window.location.href).toBe(currentUrl)
+  })
+})