Skip to content

Commit d80dc1a

Browse files
nshkiCopilot
andauthored
feat(hub): add local developer sign-in (#229)
<!-- Use a conventional commit-style title, such as "fix(hub): retain prototype history". --> ## Why <!-- Explain the problem and why this change matters in a short, plain-English paragraph. Link the issue when applicable. --> People working on Hub need a quick way to try authenticated pages without registering a GitHub or Entra application first. ## What changes <!-- Describe what becomes different for a first-time reader. Explain necessary terms. Include accurate Mermaid diagrams when they clarify the proposal, using before/after diagrams when helpful. Add screenshots for meaningful UI changes. --> <!-- Omit validation sections, checklists, and routine test/CI summaries such as "CI is green" or "tests passed". Mention only known verification gaps that affect the change, not disclaimers about drafting the description. --> <!-- For UI changes, prune obsolete and duplicate stories in the affected catalogues as part of the change. Explain removed UI or consolidated coverage where needed; see hub/docs/storybook.md#ui-changes-and-pull-request-evidence. --> `npm run dev:api` starts the API with one fixed local developer who has administrator access. Local sign-in uses Hub's normal authorization, admission, session, rate-limit, and audit flow, and refuses non-local databases and remotely reachable listeners or origins. `npm run dev:api:live` disables local sign-in and requires GitHub or Entra settings. After signing in locally, `npm run db:seed:index` can populate the sample repository without a user ID. Real GitHub or Entra sign-in was not exercised because provider credentials were unavailable. ## Storybook screenshots <!-- For Hub or canvas UI changes, follow hub/docs/storybook.md#ui-changes-and-pull-request-evidence. Embed uploaded screenshots of EVERY added or changed story, including stories affected indirectly by shared code, styles, copy, or fixtures. Label each with its full story title/name, theme, and viewport. Keep this section last and refresh images after UI revisions. Name any missing story and its rendering/upload blocker; incomplete evidence is not completion. Remove this section only when no story presentation changes. --> **Hub/Pages/Home / Local Developer — dark — 1440 × 1100** ![Hub/Pages/Home / Local Developer, dark, 1440 by 1100](https://github.com/user-attachments/assets/4ba9dc3d-cee3-41e5-aa20-44232f8ab971) **Hub/Pages/Home / Local Developer — light (system preference) — 1440 × 1100** ![Hub/Pages/Home / Local Developer, light system preference, 1440 by 1100](https://github.com/user-attachments/assets/fac5c230-ceba-4031-bf8c-48d4334c8475) --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 494096eb-fdb5-4c27-b5da-8d4dc060b19d
1 parent 08a01fe commit d80dc1a

39 files changed

Lines changed: 669 additions & 34 deletions

File tree

‎hub/.env.example‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,5 +62,13 @@ TEST_DATABASE_URL=postgresql://replica:replica@127.0.0.1:5432/postgres
6262
# ENTRA_OIDC_CLIENT_AUTHENTICATION=managed-identity
6363
# ENTRA_OIDC_MANAGED_IDENTITY_CLIENT_ID=<managed-identity-client-id>
6464

65+
# Development-only sign-in as one local administrator, without GitHub or Entra.
66+
# `npm run dev:api` defaults NODE_ENV to development and enables local sign-in.
67+
# `npm run dev:api:live` disables local sign-in. These values are for running
68+
# server/index.ts directly. Requires the local DATABASE_URL above.
69+
# See docs/development.md.
70+
# NODE_ENV=development
71+
# HUB_LOCAL_SIGN_IN=true
72+
6573
# Trust forwarded client addresses only behind this exact protected proxy-chain length.
6674
# HUB_TRUSTED_PROXY_HOPS=0

‎hub/AGENTS.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ Hub is being rebuilt in TypeScript. Read the [root instructions](../AGENTS.md),
1212

1313
Run Node commands from `hub/`, locally or inside the devcontainer. PostgreSQL and Prisma support configured GitHub authentication, administrator enrollment, Hub sessions, and a seeded read-only prototype index; see [authentication](docs/authentication.md). Other prototype APIs and repository-specific permissions are not built. Agree on the design before adding more product models, permissions, deployment choices, or product API routes.
1414

15+
Use `npm run dev:api` to run Hub with local developer sign-in; this is the default choice for trying or testing Hub. Use `npm run dev:api:live` only when the task needs real GitHub or Entra sign-in configured in `.env`. [Development](docs/development.md#start-with-the-real-api) explains both modes.
16+
1517
`npm test` does not require PostgreSQL. Use `npm run test:database` for `.db.test.ts` and `.db.test.tsx` cases in Node.js or jsdom. Follow the database isolation and reset rules in [testing](docs/testing-and-operations.md).
1618

1719
Keep the top-level `HubThemeProvider` around Hub and Storybook content. It synchronizes the resolved light/dark mode to `<html data-color-mode>` so portals inherit Brand and `--hub-*` tokens. Do not add a fixed light theme to an overlay.

‎hub/client/application/hub-application/index.test.tsx‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,44 @@ describe("HubApplication()", () => {
173173
expect(screen.queryByRole("button", { name: "Sign in with GitHub" })).toBeNull()
174174
})
175175

176+
it("offers local developer sign-in when the API enables it", async () => {
177+
vi.stubGlobal(
178+
"fetch",
179+
vi.fn((input: RequestInfo | URL) =>
180+
Promise.resolve(
181+
requestUrl(input).endsWith("/api/auth/providers")
182+
? Response.json({ providers: ["local"] })
183+
: new Response(null, { status: 401 }),
184+
),
185+
),
186+
)
187+
188+
renderApplication()
189+
190+
expect(
191+
await screen.findByRole("button", { name: "Sign in as local developer" }),
192+
).toBeInTheDocument()
193+
})
194+
195+
it("leaves local developer sign-in out of administrator enrollment", async () => {
196+
window.history.replaceState({}, "", "/admin-enrollment")
197+
vi.stubGlobal(
198+
"fetch",
199+
vi.fn((input: RequestInfo | URL) =>
200+
Promise.resolve(
201+
requestUrl(input).endsWith("/api/auth/providers")
202+
? Response.json({ providers: ["github", "local"] })
203+
: new Response(null, { status: 401 }),
204+
),
205+
),
206+
)
207+
208+
renderApplication()
209+
210+
expect(await screen.findByRole("button", { name: "Verify with GitHub" })).toBeInTheDocument()
211+
expect(screen.queryByRole("button", { name: /local/i })).toBeNull()
212+
})
213+
176214
it("shows an explicit discovery failure with no fallback actions", async () => {
177215
vi.stubGlobal(
178216
"fetch",

‎hub/client/application/hub-application/index.tsx‎

Lines changed: 28 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -6,20 +6,21 @@ import { useHubTheme } from "@hooks/use-hub-theme"
66
import { CurrentSessionPage } from "@pages/current-session-page"
77
import { HomeIndexPage } from "@pages/home-index-page"
88
import { HubAdminEnrollmentPage } from "@pages/hub-admin-enrollment-page"
9+
import type { HomeSignInAction } from "@pages/home-index-page/types"
910
import { SessionLoadingPage } from "@pages/session-loading-page"
1011

1112
type SessionState =
1213
| { status: "loading" }
1314
| {
1415
status: "signed-out"
1516
providerDiscoveryFailed: boolean
16-
providers: Array<"github" | "entra">
17+
providers: HomeSignInAction["provider"][]
1718
restoreFailed: boolean
1819
}
1920
| {
2021
status: "signed-in"
2122
providerDiscoveryFailed: boolean
22-
providers: Array<"github" | "entra">
23+
providers: HomeSignInAction["provider"][]
2324
membershipId: string
2425
userId: string
2526
provider: string
@@ -30,10 +31,16 @@ type SessionState =
3031

3132
const providersSchema = z
3233
.object({
33-
providers: z.array(z.enum(["github", "entra"])),
34+
providers: z.array(z.enum(["github", "entra", "local"])),
3435
})
3536
.strict()
3637

38+
const signInLabels: Record<HomeSignInAction["provider"], string> = {
39+
entra: "Sign in with Microsoft Entra",
40+
github: "Sign in with GitHub",
41+
local: "Sign in as local developer",
42+
}
43+
3744
export function HubApplication() {
3845
const { resolvedColorMode } = useHubTheme()
3946
const [session, setSession] = useState<SessionState>({ status: "loading" })
@@ -48,7 +55,7 @@ export function HubApplication() {
4855
})
4956
.catch(() => ({
5057
failed: true,
51-
providers: [] as Array<"github" | "entra">,
58+
providers: [] as HomeSignInAction["provider"][],
5259
}))
5360
.then(async (providerResult) => {
5461
try {
@@ -87,7 +94,7 @@ export function HubApplication() {
8794

8895
if (session.status === "loading") return <SessionLoadingPage />
8996
const providerActions = session.providers.map((provider) => ({
90-
label: provider === "github" ? "Sign in with GitHub" : "Sign in with Microsoft Entra",
97+
label: signInLabels[provider],
9198
path: `/api/auth/${provider}/start`,
9299
provider,
93100
}))
@@ -106,12 +113,22 @@ export function HubApplication() {
106113
heading: "Enroll a Hub administrator",
107114
description: "Enter the deployment bootstrap secret, then verify your identity.",
108115
secretLabel: "Bootstrap secret",
109-
providerActions: providerActions.map((action) => ({
110-
...action,
111-
label:
112-
action.provider === "github" ? "Verify with GitHub" : "Verify with Microsoft Entra",
113-
path: `/api/auth/${action.provider}/admin-enrollment/start`,
114-
})),
116+
// The local developer is already an administrator, so it has no enrollment step.
117+
providerActions: providerActions.flatMap((action) =>
118+
action.provider === "local"
119+
? []
120+
: [
121+
{
122+
...action,
123+
provider: action.provider,
124+
label:
125+
action.provider === "github"
126+
? "Verify with GitHub"
127+
: "Verify with Microsoft Entra",
128+
path: `/api/auth/${action.provider}/admin-enrollment/start`,
129+
},
130+
],
131+
),
115132
}}
116133
/>
117134
)

‎hub/client/application/hub/view-models/administrator-provider-label/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,6 @@ export function administratorProviderLabel(provider: string | null) {
22
if (!provider) return "Provider profile unavailable"
33
if (provider === "github") return "GitHub account"
44
if (provider === "entra") return "Microsoft Entra account"
5+
if (provider === "local") return "Local developer account"
56
return `${provider} account`
67
}

‎hub/client/pages/home-index-page/index.tsx‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { MarkGithubIcon, OrganizationIcon } from "@primer/octicons-react"
1+
import { MarkGithubIcon, OrganizationIcon, PersonIcon } from "@primer/octicons-react"
22
import { Button, Hero, Text } from "@primer/react-brand"
33
import { useEffect, useId, useState } from "react"
44

@@ -135,7 +135,11 @@ export function HomeIndexPage({
135135
<Hero.ButtonGroup className="home__actions">
136136
{data.signInActions.map((action) => {
137137
const SignInIcon =
138-
action.provider === "github" ? MarkGithubIcon : OrganizationIcon
138+
action.provider === "github"
139+
? MarkGithubIcon
140+
: action.provider === "local"
141+
? PersonIcon
142+
: OrganizationIcon
139143
return (
140144
<Button
141145
type="submit"

‎hub/client/pages/home-index-page/stories.tsx‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,21 @@ export const GitHubAndMicrosoftEntra: Story = {
101101
},
102102
}
103103

104+
export const LocalDeveloper: Story = {
105+
args: {
106+
data: {
107+
...data,
108+
signInActions: [
109+
{
110+
label: "Sign in as local developer",
111+
path: "/api/auth/local/start",
112+
provider: "local",
113+
},
114+
],
115+
},
116+
},
117+
}
118+
104119
export const AuthorizationFailed: Story = {
105120
args: {
106121
data: {

‎hub/client/pages/home-index-page/types.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
export interface HomeSignInAction {
22
label: string
33
path: string
4-
provider: "github" | "entra"
4+
provider: "github" | "entra" | "local"
55
}
66

77
export interface HomeIndexPageData {

‎hub/docs/architecture.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ Domain operations receive only the transaction-scoped repositories they need. A
3636

3737
The [authentication and session flow](authentication.md) uses this foundation to validate explicit GitHub and [Microsoft Entra OIDC](entra-oidc.md) configuration, complete provider user authentication, resolve the immutable external identity, apply current provider-owned assignment evidence, decide current Hub admission, and issue an opaque browser session. An installation may configure either or both providers, and provider network work remains outside identity transactions.
3838

39-
The administrator-management API and retained frontend list and search existing Hub users, designate one to 50 administrators, and revoke one administrator-managed assignment. Sensitive role changes reuse the current session's GitHub or Entra authorization flow and bind one short-lived, one-use continuation to the live session, external identity, operation, and target memberships. The callback and mutation reread current authority before changing roles. This surface does not invite users or manage general membership lifecycle.
39+
The administrator-management API and retained frontend list and search existing Hub users, designate one to 50 administrators, and revoke one administrator-managed assignment. Sensitive role changes reuse the current session's GitHub, Entra, or local authorization flow and bind one short-lived, one-use continuation to the live session, external identity, operation, and target memberships. The callback and mutation reread current authority before changing roles. This surface does not invite users or manage general membership lifecycle.
4040

4141
The administrator security-audit API and retained frontend list Hub-wide identity and administrator records newest first through bounded opaque-cursor pagination. The API rereads the live administrator session and projects stored records through action-specific presentation allowlists. The frontend keeps the cursor opaque, shows stable membership UUIDs when available, and does not load provisional product workspace contracts. Repository audit, export, retention changes, and deletion remain separate work.
4242

‎hub/docs/authentication.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,12 @@ Administrator-enrollment rate limits write at most one durable denial audit for
9090

9191
Database guards cover invariants that application validation alone cannot protect across concurrent writers or future code paths. They keep membership ownership and history immutable, keep assignment ownership, provenance, and role immutable, allow only one active administrator-managed assignment per membership, prevent reactivation of revoked administrator-managed assignments, require an assignment identity to belong to the membership user, keep external evidence ordering state immutable and monotonic, permit only first session termination, protect the global revocation identity and exact revision increment, and keep an authorization attempt's server-selected purpose, bootstrap-secret generation, nonce, and revocation generation immutable. Ordinary value-shape and time-order checks remain in the application contracts.
9292

93+
## Local developer sign-in
94+
95+
Run `npm run dev:api` to test Hub on your own machine without registering a GitHub or Entra application. This command enables `HUB_LOCAL_SIGN_IN` and adds a `local` provider with the same start, callback, admission, session, sign-out, rate-limit, and audit behavior as the hosted providers. Its start redirects straight back to `/api/auth/local/callback` instead of an outside sign-in page. The callback always proves one fixed `local-developer` identity with provider-assigned administrator access, so the first sign-in creates an active administrator membership without bootstrap enrollment. Administrator management re-authorizes through the same local flow. Use `npm run dev:api:live` to disable local sign-in and test configured GitHub or Entra providers.
96+
97+
Because anyone who can reach the API could sign in this way, startup requires `NODE_ENV=development` and a local development `DATABASE_URL`. It also requires `HOST` to be `127.0.0.1`, `::1`, or `localhost` and `HUB_APPLICATION_ORIGIN` to be a loopback origin. It cannot be combined with GitHub or Entra. Startup chooses the local provider revision itself: it keeps the current revision for an unchanged restart and moves to the next revision after the mode was turned off or the origin changed. When the origin, encryption key, or bootstrap secret is unset, startup uses `http://127.0.0.1:5173` and throwaway secrets. Restarting with a throwaway key only invalidates sign-ins that were in progress.
98+
9399
## Safety boundaries
94100

95101
GitHub and Entra configuration are explicit and independently revisioned. Only the public github.com endpoints and the exact configured single-tenant Entra issuer are accepted. Provider requests have fixed deadlines, reject redirects, and discard provider tokens and client assertions after validation.

0 commit comments

Comments
 (0)