Skip to content

feat(auth): forwardedClientId strategy and opt-in apikey/path secret locations - #3

Draft
snowkide wants to merge 3 commits into
mainfrom
feat/forwarded-client-id-auth
Draft

snowkide wants to merge 3 commits into
mainfrom
feat/forwarded-client-id-auth

Conversation

@snowkide

@snowkide snowkide commented Oct 15, 2026 •

Copy link
Copy Markdown

Two opt-in auth additions for deployments where eRPC sits behind an API gateway or is used by clients that only take a single RPC URL, plus a tracing fix. Nothing changes for existing configurations.

Commits (can be split into three PRs; 3 depends on 1):

  1. fix(tracing): redact credential query parameters from http.url. Http.ReceivedRequest recorded r.URL.String() verbatim, so ?secret=, ?token=, ?jwt= and SIWE ?signature= values were exported to the tracing backend. They are now replaced with REDACTED; other parameters and the path are unchanged.
  2. feat(auth): forwardedClientId strategy. When a gateway already authenticates callers and forwards the client id in a header, eRPC uses that header as the user id, so per-client rate-limit budgets, method scoping and the user label work. Inactive unless configured.
    • header (default X-Client-Id), allowedIds, rateLimitBudget.
    • allowedProxies: checked against the direct TCP peer, not X-Forwarded-For (separate from server.trustedIPForwarders, which only resolves the client IP). A startup warning is logged when it is empty.
    • Multiple header values are rejected, as are empty ids, ids over 256 bytes, or ids with whitespace, commas or non-ASCII.
    • Works over HTTP and WebSocket upgrades; gRPC is not supported.
  3. feat(auth): opt-in secret locations for the secret and database strategies via additionalLocations (empty by default), consulted only when no standard location supplied a secret:
    • apikeyQuery (?apikey=), apikeyHeader (X-Api-Key / apikey), path (https://host/<secret>, only on a domain alias that fixes project, architecture and chain).
    • These never change the credential type, so network strategies behave as before. Unknown location names fail validation.
    • A path is only read as a secret, and redacted from http.url and the CORS metric label, when the auth config serving the request lists path (healthCheck.auth for GET requests). ?apikey= is redacted like ?secret=.
auth:
  strategies:
    - type: forwardedClientId
      forwardedClientId:
        header: X-Client-Id
        allowedProxies: ["10.0.0.0/8"]
        rateLimitBudget: per-client
    - type: secret
      secret:
        id: wallet-app
        value: ${WALLET_APP_SECRET}
        additionalLocations: [apikeyHeader]

Security note: forwardedClientId trusts a header. Enable it only behind a proxy that strips or overwrites that header from clients, and restrict allowedProxies to that proxy.

Notes for review:

  • forwardedClientId authenticates (budgets, method scoping and allowClientDirectives apply), unlike trustUserIdHeader, which only labels.
  • Not addressed here (pre-existing): the database strategy logs apiKey at debug/warn/error level, and the secret strategy's comparison is not constant-time.

Docs: config/auth, operation/tracing.

Verification

Based on fork main @ f97c9f6 (erpc/erpc 0.5.0 @ 204f98c). Build, vet and auth tests pass at each commit.

  • go build ./... and go vet ./auth ./common ./erpc are clean; gofmt -l on touched files is clean.
  • go test ./auth ./telemetry ./common: ok; go test -race ./auth: ok.
  • go test ./erpc -run 'Auth|PathSecret|ForwardedClientId|HealthCheck|Healthcheck|CORS|WebSocket|Alias|HttpServer|Tracing': ok.
  • New tests include TestRedactedRequestURL, TestPathSecretAuth_NotOptedIn, TestAuthRegistry_ForwardedClientId*, TestAuthRegistry_SecondarySecretLocations, AcceptsSecretLocation and Supports tests for the secret and database strategies.
  • TypeScript: src types updated (lib/ not rebuilt; it is already behind src on this base); pnpm test: ok.

AI assistance

  • Model: anthropic/claude-opus-5.5
  • Harness / skills: Claude Code
  • Human-reviewed: no, pending

🤖 Generated with Claude Code

@snowkide
snowkide force-pushed the feat/forwarded-client-id-auth branch from 3cb7068 to 3599b4b Compare November 3, 2026 10:57
@snowkide
snowkide changed the base branch from main to upstream-main November 3, 2026 11:07
@snowkide
snowkide force-pushed the feat/forwarded-client-id-auth branch from 3599b4b to b59945a Compare November 3, 2026 11:23
@snowkide
snowkide changed the base branch from upstream-main to main November 3, 2026 11:23
@snowkide
snowkide force-pushed the feat/forwarded-client-id-auth branch from b59945a to cd967de Compare November 4, 2026 14:31
snowkide and others added 3 commits November 5, 2026 14:46
The Http.ReceivedRequest span recorded r.URL.String() verbatim, so a
secret, token, JWT or SIWE signature passed as ?secret=, ?token=, ?jwt=
or ?signature= was exported to the tracing backend. Replace those values
with REDACTED; other query parameters and the path are kept as is.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…callers

When eRPC runs behind an API gateway or reverse proxy that already
authenticates callers, the gateway typically forwards the authenticated
client's id in a request header. The new forwardedClientId strategy
trusts that header as the user id, so per-client rate-limit budgets,
method scoping and the user metric label work without duplicating the
gateway's key store in eRPC.

The strategy is only active when configured and is offered every HTTP or
WebSocket request that carries its header, in declaration order:

- header: header name, default X-Client-Id
- allowedProxies: only trust the header from these direct TCP peers
  (the socket address, not the X-Forwarded-For client IP); a startup
  warning is logged when it is empty
- allowedIds: optional allowlist, also bounds user label cardinality
- rateLimitBudget: budget attached to the authenticated user

A header with several values (a proxy that appends instead of
overwriting) is rejected, as are ids that are empty, longer than 256
bytes, or contain whitespace, commas or non-ASCII characters.

AuthPayload now carries the request headers and remote address so that
strategies can read their own transport inputs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Many clients and gateways send an API key as ?apikey=, an X-Api-Key or
apikey header, or (wallets and SDKs that only accept a single RPC URL)
as the URL path itself. The secret and database strategies gain
additionalLocations, empty by default, to also accept the secret from:

- apikeyQuery: the ?apikey= query parameter
- apikeyHeader: the X-Api-Key or apikey header
- path: the URL path as a single segment (https://host/<secret>), only
  on a domain alias that preselects project, architecture and chain so
  the path is not used for routing; /admin, /healthcheck and /metrics
  are never treated as secrets

These locations are consulted only when none of the standard ones
supplied a secret, and never change the extracted credential type, so a
request carrying only one of them still reaches a network strategy as
before. A strategy ignores a secret from a location it does not list;
unknown location names fail validation.

A path is only read as a secret when the auth config serving the request
(the project's, or healthCheck.auth for GET healthchecks) lists path.
Such a path is replaced with /REDACTED in the http.url span attribute
and the CORS metrics' path label, and ?apikey= values are redacted from
http.url like ?secret=.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@snowkide
snowkide force-pushed the feat/forwarded-client-id-auth branch from cd967de to 5291495 Compare November 5, 2026 13:52

This branch has not been deployed

No deployments
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.

1 participant