Skip to content

feat(cli): reach a remote local server behind Cloudflare Access - #466

Open
alan-roe wants to merge 1 commit into
MapleTechLabs:mainfrom
alan-roe:feat/cli-cloudflare-access
Open

feat(cli): reach a remote local server behind Cloudflare Access#466
alan-roe wants to merge 1 commit into
MapleTechLabs:mainfrom
alan-roe:feat/cli-cloudflare-access

Conversation

@alan-roe

@alan-roe alan-roe commented Aug 14, 2026

Copy link
Copy Markdown

Problem

MAPLE_LOCAL_URL can already point the CLI at a remote maple start instance, but the local-mode HTTP client sends only content-type — there is no way to attach an auth header. Any self-hosted instance behind an authenticating reverse proxy (e.g. a Cloudflare Access tunnel, the natural way to expose a single-binary maple on a homelab box) is unreachable from the CLI.

Changes

  • packages/query-engine/src/local.ts: the local query client accepts optional extra headers (generic Record<string,string>; default unchanged, bundled UI unaffected)
  • MAPLE_LOCAL_HEADERS: comma-separated Key=Value pairs (same format as OTEL_EXPORTER_OTLP_HEADERS), attached to every local-mode request — e.g. a CF Access service token for machines
  • cloudflared identity flow: when the resolved local URL is non-loopback https and no Access credential is already configured, the CLI best-effort acquires a user JWT via cloudflared access token -app=<origin> and sends it as cf-access-token. One-time setup is the standard cloudflared access login <origin>; missing binary/token degrades silently
  • Typed error UX: a 401/403 or a redirect to *.cloudflareaccess.com / /cdn-cgi/access/ fails with a Schema.TaggedError explaining both options instead of a JSON parse error
  • Docs: new section in local-mode/cli-reference.md

Verification

  • Targeted unit tests (header parsing, redirect/401 detection, executor wiring): 8 pass; tsc --noEmit clean in apps/cli and packages/query-engine
  • Exercised against a real self-hosted v0.0.18 instance behind Cloudflare Access (service-token and identity-token paths)

View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.

@Makisuo

Makisuo commented Aug 15, 2026

Copy link
Copy Markdown
Collaborator

Hey @alan-roe, this looks really good but I have some small points we should address before merging this in!

  • maple sql still broken behind Access — executeRawLocalQuery (operations.ts:327) has no headers, no Access detection. Only the executor path got wired.
  • isCloudflareAccessResponse treats any 401/403 as Access. serve.ts:589 "browser origin not allowed" covers /local/query, so a local CORS 403 tells you to run cloudflared access login http://127.0.0.1:4318. Gate it on non-loopback https.
  • probeLocal sends a bare /health, so auto-detect never picks a protected origin --local always required.
  • no timeout on the cloudflared spawn, hangs the CLI with nothing on screen.
  • redirect: "manual" hits apps/local-ui too. Make it a param, default follow.
  • unguarded new URL in cloudflareAccessError; headers spread after content-type so they can clobber it; tryPromise catch + orElseSucceed is doubled; const process = shadows the global.

Also I'm curious to what your main use case is of using cloudflare access with it?

The local-mode HTTP client only ever sent content-type, so a
self-hosted 'maple start' instance behind an authenticating reverse
proxy (Cloudflare Access tunnel) was unreachable from the CLI even
though MAPLE_LOCAL_URL can already point at it.

- packages/query-engine local client accepts optional extra headers
  (default unchanged; the bundled UI is unaffected)
- MAPLE_LOCAL_HEADERS env: comma-separated Key=Value pairs (same
  format as OTEL_EXPORTER_OTLP_HEADERS) attached to every local-mode
  request, e.g. a CF Access service token
- when the local URL is non-loopback https and no Access credential
  is configured, best-effort acquire a user-identity JWT via
  'cloudflared access token' and send it as cf-access-token
  (one-time 'cloudflared access login <origin>' required)
- 401/403 or a redirect to the Access login page fails with a typed
  error explaining both options

Verified against a self-hosted instance behind Cloudflare Access.
@alan-roe
alan-roe force-pushed the feat/cli-cloudflare-access branch from 42e7d36 to 0cc922d Compare August 15, 2026 11:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants