feat(auth): restrict API keys to upstreams by group-labels

[selfuryon]

Closes #391

What

Local API keys can restrict which upstreams serve them via settings.upstreams.group-labels. Only upstreams carrying at least one of the listed group-labels are used for the key's requests and subscriptions:

auth:
  key-management:
    - id: partner-a
      type: local
      local:
        key: "..."
        settings:
          upstreams:
            group-labels: [archive, fast]

It is a filter, not a balancer: among the admitted upstreams the chain's strategy (rating / base / label-balancing) still picks as usual, and excluded upstreams are never used — not as a fallback, not on a retry or hedge.

How

• LocalKey.PostCheckSetting adds an internal RequestGroupLabelSelector to every upstream request (new protocol.SelectorAppender, implemented by the JSON-RPC, REST and gRPC holders). A request that cannot carry it is rejected instead of being served unrestricted.
• compileSelector turns it into a GroupLabelMatcher that resolves an upstream's group-labels through the supervisor, so every strategy applies it.
• The selector is part of the subscription aggregation key (keys with different restrictions never share an upstream subscription), but not of the cache key (LabelCacheKey treats it as unconstrained — it chooses which nodes answer, not what they answer).
• Locally-synthesized newHeads / newPendingTransactions merge every upstream of the chain, so — as logs already did — a selector-bearing subscription now takes the node-backed path. drpc_pendingTransactions has no such path and fails with a client error when selectors are present.
• Config validation: labels must be non-empty and unique, and each must be carried by at least one configured upstream (a typo fails at startup instead of leaving the key with no upstream).

Also fixed

The integrity retry (IntegrityRequestProcessor.handleResponse) re-sent stale eth_blockNumber / eth_getBlockByNumber answers to higher upstreams through a strategy without matchers, so it ignored the request's selectors — both a client's own and the new key restriction. It now applies the selector matchers while keeping the height order. Separate commit: fix(flow): honor request selectors on the integrity retry.

Behavior changes

• Emerald NativeSubscribe clients that send effective selectors on newHeads / newPendingTransactions now get them honored via a node-backed subscription; previously the selectors were silently ignored by the local source.
• Requests with selectors that hit the integrity retry are no longer retried on upstreams the selectors exclude.

Not covered

• drpc-managed keys: their settings come from the dRPC platform, which has no such field.
• The emerald gRPC API does not use key-management at all; documented in 03-auth.md.

Testing

• Unit tests for config validation, selector key / cache key, AppendSelectors, GroupLabelMatcher, LocalKey restriction (incl. fail-closed), resolveSource bypass of local sources, subscription key separation.
• createStrategy end-to-end with a real chain supervisor: requests and subscriptions only ever land on the admitted upstream.
• Integrity retry test: fails without the fix (answer comes from the higher full node), passes with it.
• go test -race ./... and golangci-lint v2.14.0 pass locally (except caches/*_e2e, which need Docker).

Docs: docs/nodecore/03-auth.md (new "Upstream restriction" section) and docs/nodecore/13-subscriptions.md.

🤖 Generated with Claude Code

[KirillPamPam]

There is already func (a *AuthConfig) validate, let's reuse it instead of creating a new one

[KirillPamPam]

There is a method func (l *LocalKeyConfig) validate() where we can add a validation of KeySettingsConfig with new Upstreams

[KirillPamPam]

There is already a validation of AuthConfig above, let's reuse it

[KirillPamPam]

I suggest do not fix local subs so far. There should be a more complex fix that we will add as soon as possible. As a workaround local subs can be disabled via LocalSubscriptionsConfig until this fix