In-app /install configurator and /admin/diagnostics for Azure/Entra deployments

Altien adds a backend-side install wizard that walks an operator through Azure Key Vault secrets, Entra app registration, and readiness checks - all served from the running container. The manifest in `lib/install/manifest.ts` doubles as a live inventory of every config item the app expects.

infrastructuremulti-tenant

Maintained by

Allen Morgan · verified on MikeWatch

Commit c94bf9f1 is the backend half of an operator setup UI. It's structured around a config manifest - a TypeScript file listing every expected secret (KV secret names, env-only items, readiness probes) with human-readable labels and check logic. The manifest serves as both the wizard's data model and the source for /admin/diagnostics, which runs those same checks on demand.

Auth for /install is a two-phase flow. A bootstrap token (set at deploy time) gates the first sign-in; on successful Entra admin login the token burns. After that, the session is maintained with HMAC-signed short-lived cookies issued by lib/install/sessionTokens.ts. The bootstrap-burn mechanism means the install surface can't be re-entered by anyone who only knows the original deploy token.

lib/install/checks/ holds individual readiness probes. installerAccess.ts makes a real ARM call - it lists role assignments on the Key Vault scope filtered to the installer's principal ID, then reports pass when the Key Vault Secrets Officer assignment is gone. Three things gate that check: SUBSCRIPTION_ID in env, installer-principal-id in Key Vault, and UAMI Reader permission on the KV scope. Each missing prerequisite fails soft to status: "info" with a remediation hint rather than a misleading green tick.

The whole thing is tightly coupled to Azure/Entra/Key Vault. Routes under /install and /admin/diagnostics don't exist in the upstream codebase.

So what Skip unless you're building for the Azure Marketplace or want an operator-facing setup wizard for multi-tenant Entra deployments. The manifest pattern - a single file declaring all config items plus their readiness probes - is reusable if you want something similar for a different stack, but everything else here is Altien-specific.

Spotted something wrong? Or know the PR text has fresher detail than the writeup above?

Commits in this thread

1 commit from Altien/mikeOssAzure, oldest first. Source extracted verbatim from the harvested git log.

SHA	Subject	Author	Date
`c94bf9f1`	feat(install): /install configurator + /admin/diagnostics routes	Allen Morgan	2026-05-08	↗ GitHub
commit body Backend half of the in-app install/configuration UI. * lib/install/manifest.ts - declarative manifest of every config item the app expects (KV secret names, env-only items, readiness checks). Functional documentation: anyone with this code can rebuild the configurator, no proprietary IP. * lib/install/installAuth.ts - bootstrap-token + Entra OIDC auth for /install. The bootstrap token burns on first successful Entra- admin sign-in. * lib/install/sessionTokens.ts - short-lived HMAC-signed cookies keyed off the bootstrap or OIDC identity. * lib/install/types.ts - manifest model types. * lib/install/checks/* - manifest readiness probes for installer access and Entra redirect-uri registration. * routes/install.ts - server-rendered HTML configurator UI. Reads/writes Key Vault via getConfig/setConfig. GET /install/ scripts/:name returns 404 when scripts/install/ is absent - that directory ships with the separate deploy package, not the application image, so the application-only deployment degrades cleanly. * routes/diagnostics.ts - /admin/diagnostics health page. Operator-grade utility that runs every manifest probe and reports status; useful in any deployment. Adds cookie-parser + @types/cookie-parser to support the configurator's short-lived session cookies. The routers themselves are not yet mounted on the Express app - that wiring lands in the bundled-frontend commit so this one stays focused on the configurator surface.

SHA

Subject

Author

Date

c94bf9f1

feat(install): /install configurator + /admin/diagnostics routes

Allen Morgan

2026-05-08

↗ GitHub

commit body

Backend half of the in-app install/configuration UI.

  * lib/install/manifest.ts        - declarative manifest of every
                                     config item the app expects (KV
                                     secret names, env-only items,
                                     readiness checks).  Functional
                                     documentation: anyone with this
                                     code can rebuild the configurator,
                                     no proprietary IP.

  * lib/install/installAuth.ts     - bootstrap-token + Entra OIDC auth
                                     for /install.  The bootstrap token
                                     burns on first successful Entra-
                                     admin sign-in.

  * lib/install/sessionTokens.ts   - short-lived HMAC-signed cookies
                                     keyed off the bootstrap or OIDC
                                     identity.

  * lib/install/types.ts           - manifest model types.

  * lib/install/checks/*           - manifest readiness probes for
                                     installer access and Entra
                                     redirect-uri registration.

  * routes/install.ts              - server-rendered HTML configurator
                                     UI.  Reads/writes Key Vault via
                                     getConfig/setConfig.  GET /install/
                                     scripts/:name returns 404 when
                                     scripts/install/ is absent - that
                                     directory ships with the separate
                                     deploy package, not the application
                                     image, so the application-only
                                     deployment degrades cleanly.

  * routes/diagnostics.ts          - /admin/diagnostics health page.
                                     Operator-grade utility that runs
                                     every manifest probe and reports
                                     status; useful in any deployment.

Adds cookie-parser + @types/cookie-parser to support the configurator's
short-lived session cookies.  The routers themselves are not yet
mounted on the Express app - that wiring lands in the bundled-frontend
commit so this one stays focused on the configurator surface.

Capture this thread into my fork

Download a single Markdown prompt that tells Claude how to port every commit above into your working tree — adapting paths and structure to match your repo. Run it via claude -p < capture-thread-195.md from inside the repo you want the changes in.