Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions .github/workflows/sso-image.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,15 @@ name: Build SSO image
# GitHub Container Registry (ghcr.io/<owner>/<repo>) so the cluster can pull it.
#
# Usage: Actions tab -> "Build SSO image" -> Run workflow -> pick the upstream
# app tag that matches the ClickStack chart's appVersion (e.g. @hyperdx/app@2.39.1).
# app tag that matches the ClickStack chart's appVersion (e.g. @hyperdx/app@2.42.0).

on:
workflow_dispatch:
inputs:
upstream_tag:
description: 'Upstream HyperDX app tag to build (must match chart appVersion)'
required: true
default: '@hyperdx/app@2.39.1'
default: '@hyperdx/app@2.42.0'
push:
branches: [main]
paths:
Expand Down Expand Up @@ -44,8 +44,8 @@ jobs:
- name: Resolve tag & version
id: ver
run: |
TAG="${{ github.event.inputs.upstream_tag || '@hyperdx/app@2.39.1' }}"
VERSION="${TAG##*@}" # @hyperdx/app@2.39.1 -> 2.39.1
TAG="${{ github.event.inputs.upstream_tag || '@hyperdx/app@2.42.0' }}"
VERSION="${TAG##*@}" # @hyperdx/app@2.42.0 -> 2.42.0
echo "tag=$TAG" >> "$GITHUB_OUTPUT"
echo "version=$VERSION" >> "$GITHUB_OUTPUT"
echo "Building $TAG (version $VERSION)"
Expand Down Expand Up @@ -102,7 +102,7 @@ jobs:
# stale cached image after a rebuild of the same upstream version.
- name: Create multi-arch manifest
run: |
TAG="${{ github.event.inputs.upstream_tag || '@hyperdx/app@2.39.1' }}"
TAG="${{ github.event.inputs.upstream_tag || '@hyperdx/app@2.42.0' }}"
IMAGE="ghcr.io/$(echo '${{ github.repository }}' | tr '[:upper:]' '[:lower:]')"
SRC="${IMAGE}:${TAG##*@}-sso"
docker buildx imagetools create \
Expand Down
79 changes: 62 additions & 17 deletions sso/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,21 +25,23 @@ header is configurable via `PROXY_AUTH_EMAIL_HEADER`; in k8-mgmt we set it to
`x-forwarded-email`.

Files:
- `overlay/` — new files, mirrored to repo paths (only `proxyAuth.ts`).
- `integrate.mjs` — copies the overlay and applies an idempotent, anchor-based
codemod to `auth.ts`. Fails loudly if upstream changed that file's shape.
- `overlay/` — new files, mirrored to repo paths: `middleware/proxyAuth.ts`
(sign-in), `middleware/proxyAuthRoles.ts` (roles), `models/proxyAuthRole.ts`.
- `integrate.mjs` — copies the overlay and applies idempotent, anchor-based
codemods to `auth.ts`, `api-app.ts` and `mcp/utils/registerTool.ts`. Fails
loudly if upstream changed those files' shape.
- `apply.sh` — checks out an upstream tag into a git worktree and runs the codemod.

## Build locally

```bash
sso/apply.sh '@hyperdx/app@2.28.0' build
sso/apply.sh '@hyperdx/app@2.42.0' build
docker build -f build/docker/hyperdx/Dockerfile --target prod \
--build-context hyperdx=build/docker/hyperdx \
--build-context api=build/packages/api \
--build-context app=build/packages/app \
--build-arg CODE_VERSION=2.28.0-sso \
-t ghcr.io/<owner>/hyperdx:2.28.0-sso build
--build-arg CODE_VERSION=2.42.0-sso \
-t ghcr.io/<owner>/hyperdx:2.42.0-sso build
```

## Build in CI
Expand Down Expand Up @@ -76,27 +78,70 @@ empty in Terraform — `oauth2-proxy.tf` then skips the dockerconfigjson secret
| `PROXY_AUTH_DEFAULT_TEAM_NAME` | `HyperDX` | (default) | Team created on first login. |
| `PROXY_AUTH_GROUPS_HEADER` | `x-forwarded-groups` | (default) | Groups header (oauth2-proxy GitHub: `org`, `org:team`). |
| `PROXY_AUTH_ADMIN_GROUPS` | (empty → roles off) | `topia-io:devops,metaversecloud-com:devops` | Comma-separated groups with full access. |
| `PROXY_AUTH_MEMBER_GROUPS` | (empty) | to add: `topia-io:dev,metaversecloud-com:dev` | Groups that may author dashboards, searches, alerts, webhooks. |
| `PROXY_AUTH_ACCESS_KEY_MAX_IDLE_DAYS` | `30` | (default) | Access keys stop working when their owner hasn't signed in via SSO for this long. `0` disables. |

### Roles

HyperDX OSS has no RBAC; the overlay adds two roles, enforced app-wide by
HyperDX OSS has no RBAC; the overlay adds three roles, enforced app-wide by
`proxyAuthRoleGuard` (mounted before every router):

- **admin** — any user in `PROXY_AUTH_ADMIN_GROUPS`: full access.
- **viewer** — everyone else: all `GET`s plus read-only `POST`s (search/charts via
`/clickhouse-proxy`, `/v1/prometheus/query*`, `/ai/assistant`,
`/me/onboarding/*`). Every other write returns 403. Viewer ClickHouse queries
are forced to `readonly=2`, so raw SQL through the proxy cannot modify data.
| Role | Who | Can |
|------|-----|-----|
| **admin** | in `PROXY_AUTH_ADMIN_GROUPS` | everything |
| **member** | in `PROXY_AUTH_MEMBER_GROUPS` | viewer + create/edit/delete dashboards, saved searches, alerts, webhooks, pinned filters |
| **viewer** | everyone else | read; run searches/charts (`/clickhouse-proxy`, PromQL, AI assistant); own favorites, onboarding, access key |

The UI is unchanged: viewers still see edit buttons, but saving fails. On an
upstream upgrade, re-check new `POST` routes viewers need and run
`yarn ci:unit src/middleware/__tests__/proxyAuth.test.ts` in the integrated tree.
Sources, connections, team settings, IaC and connection tests are admin-only.
Any write route not classified in `proxyAuthRoles.ts` is admin-only, so routes
added upstream fail closed. Non-admin ClickHouse queries are forced to
`readonly=2`, so raw SQL through the proxy cannot modify data.

Write decisions are logged (`Proxy auth: write`, `... write denied`,
`... MCP write`, `... role changed`) and counted in
`hyperdx.proxy_auth.write_decisions{role,outcome}`.

The UI is unchanged: non-admins still see edit buttons, but saving returns 403
naming the required role.

### Access keys, API v2 and MCP

`/api/v2/*` and `/mcp` authenticate by personal access key, not by the proxy,
so group headers are ignored there. The role comes from the key owner's last SSO
sign-in, stored in the `proxyauthroles` collection (refreshed at most hourly
while they use the UI). A key is rejected with 403 if its owner never signed in
through SSO or not within `PROXY_AUTH_ACCESS_KEY_MAX_IDLE_DAYS`.

MCP serves all tools over one `POST /mcp`, so it is gated per tool: tools
annotated `readOnlyHint` are open to viewers, `*_source` tools need admin, every
other write tool needs member. A denied call returns an MCP tool error.

**Revoking someone:** remove them from the GitHub team (blocks new SSO logins;
existing oauth2-proxy cookies last until `cookie_expire`), and delete them in
Team Settings to kill their access key immediately. Otherwise the key dies
after the idle window.

**oauth2-proxy must let bearer requests through** for headless clients (CLI,
MCP, API v2), since they have no GitHub cookie. In `oauth2-proxy.tf`:

```
skip_auth_routes = ["^/api/mcp$", "^/api/api/v2/[^.]*$"]
skip_auth_strip_headers = true # default; must stay on
```

The `[^.]*` keeps `..` out of the bypass. With header stripping on, a skipped
request cannot carry `X-Forwarded-*`, and those routes only trust access keys.

On an upstream upgrade, classify any new write routes in `proxyAuthRoles.ts`
and run `yarn ci:unit src/middleware/__tests__/proxyAuthRoles.test.ts` in the
integrated tree.

> **Security:** only enable when HyperDX is reachable *exclusively* through
> oauth2-proxy, and the proxy strips client-supplied copies of these headers.
> Otherwise the identity header can be spoofed. oauth2-proxy strips inbound
> `X-Forwarded-*` / `X-Auth-Request-*` before setting its own, so this holds as
> long as nothing else can reach the app port directly.
> long as nothing else can reach the app port directly. Enforce that with a
> NetworkPolicy allowing ingress to the HyperDX pod only from oauth2-proxy.

## Deploy via Terraform (k8-mgmt)

Expand Down Expand Up @@ -125,7 +170,7 @@ clickstack_sso = {
github_client_secret = "<from GitHub OAuth App>"
cookie_secret = "<openssl rand -base64 32 | tr -- '+/' '-_'>"
image_repository = "ghcr.io/<owner>/hyperdx"
image_tag = "2.28.0-sso"
image_tag = "2.42.0-sso"
# ghcr_username / ghcr_pull_token omitted → public package
# allowed_github_teams defaults to topia-io/metaversecloud-com :devops/:dev
}
Expand Down
62 changes: 57 additions & 5 deletions sso/integrate.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,11 @@
// if the expected anchors are missing (i.e. upstream changed that file's
// shape) instead of silently producing a broken build.
// 3. Anchor-based codemod of packages/api/src/api-app.ts mounting the
// app-wide role guard (viewer vs admin, from proxy-supplied groups).
// app-wide role guard (viewer/member/admin, from proxy-supplied groups).
// 4. Anchor-based codemod of packages/app/src/HDXMultiSeriesTimeChart.tsx
// so time-chart x-axis ticks show the date on ranges longer than a day.
// 5. Anchor-based codemod of packages/api/src/mcp/utils/registerTool.ts
// gating each MCP write tool by role (MCP multiplexes tools over one POST).
import { cp, readFile, writeFile, stat } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';
import path from 'node:path';
Expand Down Expand Up @@ -94,7 +96,7 @@ if (appSrc.includes('proxyAuthRoleGuard')) {
appSrc = appSrc
.replace(
appImportAnchor,
`${appImportAnchor}\nimport { proxyAuthRoleGuard } from './middleware/proxyAuth';`,
`${appImportAnchor}\nimport { proxyAuthRoleGuard } from './middleware/proxyAuthRoles';`,
)
.replace(corsAnchor, `${corsAnchor}\napp.use(proxyAuthRoleGuard);`);

Expand All @@ -106,15 +108,20 @@ if (appSrc.includes('proxyAuthRoleGuard')) {
// time-of-day only ('time'), whatever the range. Over a 30-day range that is
// a row of identical "9:00:00 AM" labels with no dates. When the range spans
// more than a day, label every tick with its date ('short' = MMM d h:mma).
const chartPath = path.join(target, 'packages/app/src/HDXMultiSeriesTimeChart.tsx');
const chartPath = path.join(
target,
'packages/app/src/HDXMultiSeriesTimeChart.tsx',
);
if (!(await exists(chartPath))) {
throw new Error(`[sso] expected file not found: ${chartPath}`);
}

let chartSrc = await readFile(chartPath, 'utf8');

if (chartSrc.includes('xTickSpansDays')) {
console.log('[sso] HDXMultiSeriesTimeChart.tsx already integrated, skipping codemod');
console.log(
'[sso] HDXMultiSeriesTimeChart.tsx already integrated, skipping codemod',
);
} else {
const tickAnchor =
' const xTickFormatter = useCallback(\n' +
Expand Down Expand Up @@ -145,7 +152,52 @@ if (chartSrc.includes('xTickSpansDays')) {
);

await writeFile(chartPath, chartSrc);
console.log('[sso] patched x-axis tick format in HDXMultiSeriesTimeChart.tsx');
console.log(
'[sso] patched x-axis tick format in HDXMultiSeriesTimeChart.tsx',
);
}

// 5) Gate MCP write tools by role.
const toolPath = path.join(
target,
'packages/api/src/mcp/utils/registerTool.ts',
);
if (!(await exists(toolPath))) {
throw new Error(`[sso] expected file not found: ${toolPath}`);
}

let toolSrc = await readFile(toolPath, 'utf8');

if (toolSrc.includes('guardMcpTool')) {
console.log('[sso] registerTool.ts already integrated, skipping codemod');
} else {
const toolImportAnchor = "import { withToolTracing } from './tracing';";
const registerAnchor =
'server.registerTool<AnyZodObject, AnyZodObject>(name, config, traced);';
if (
!toolSrc.includes(toolImportAnchor) ||
!toolSrc.includes(registerAnchor)
) {
throw new Error(
'[sso] anchors not found in registerTool.ts (layout changed)',
);
}
toolSrc = toolSrc
.replace(
toolImportAnchor,
`import { guardMcpTool } from '@/middleware/proxyAuthRoles';\n\n${toolImportAnchor}`,
)
.replace(
registerAnchor,
'server.registerTool<AnyZodObject, AnyZodObject>(\n' +
' name,\n' +
' config,\n' +
' guardMcpTool(name, config.annotations, traced),\n' +
' );',
);

await writeFile(toolPath, toolSrc);
console.log('[sso] gated MCP tools in registerTool.ts');
}

console.log('[sso] integration complete');

This file was deleted.

Loading
Loading