feat: support request-level proxy sessions

[alexferrari88]

Summary

Adds optional request-level proxy support to POST /tabs while preserving Camofox's one-BrowserContext-per-user session model.

• Accepts a validated proxy object with server and optional literal username / password values.
• Makes a user's proxy immutable for the life of the session; conflicting requests return a structured, non-retryable 409 proxy_conflict.
• Rejects request proxies when the global proxy pool is active with 409 proxy_mode_conflict.
• Preserves the request proxy through dead contexts, browser disconnects/restarts, navigation/new-page recovery, idle expiry, memory pressure, and tab reaping using a bounded TTL cache.
• Clears recovery state on explicit session deletion and other intentional teardown.
• Returns a credential-free proxied boolean from POST /tabs.
• Keeps request credentials out of logs and API responses; unsupported field names are not reflected in validation errors.

Tests

• Real HTTP endpoint tests with a local forwarding proxy prove traffic routing, literal Basic-auth credentials, session reuse, conflicts, cookie import, page-lease release, pressure recovery, and recovery after killing the browser process.
• Unit/contract tests cover validation, redaction, proxy equality, immutable/coalesced session guards, bounded cache TTL/eviction, all automatic teardown reasons, OpenAPI generation, and both CI workflows.
• Local verification on the locked Jest 30 dependency set:
  • 60 unit/plugin suites, 834 tests
  • 4 browser-dependent suites under Xvfb, 48 tests
  • 15 E2E suites, 72 tests
  • MCP smoke/package tests
  • TypeScript compiler API check
  • production dependency audits: 0 vulnerabilities

Documentation

Updates README, contributor guidance, generated OpenAPI, CI, and npm publish workflow routing.

[skyfallsin]

Thanks for the request-level proxy work. Per-request or per-task proxy selection can be useful, but this branch needs a current-architecture rebase before it is safe to merge.

The reworked design must preserve the chosen proxy through every session and page recovery path. Current recovery calls create a replacement session without carrying a request-proxy argument, so a recovered context could silently lose the requested proxy identity.

Please also:

• preserve the current viewport: null Camoufox behavior instead of restoring a fixed viewport;
• retain the current session fields and page-lease lifecycle;
• define behavior with the global rotating proxy pool;
• add endpoint-level tests for creation, same-proxy reuse, conflicting proxy requests, recovery, and page leases;
• update OpenAPI and regenerate the spec.

A fresh rebase is preferable to resolving the existing conflicts in place.

[alexferrari88]

@LostOnTheLine Rebuilt this from current master and force-replaced the old implementation rather than trying to patch the stale session model.

The concerns from your review are now covered directly:

• requestProxy is added to the current session object without dropping viewport: null, tracing, tab groups, leases, downloads, or other current fields.
• POST /tabs releases its page lease on every path; the real endpoint test proves pressure cleanup can close the tab and session afterward.
• Global proxy-pool mode and request-level proxy mode fail closed with a structured 409 proxy_mode_conflict.
• The tests call the real HTTP endpoint through a local forwarding proxy. They cover actual routing, literal proxy-auth credentials, reuse, conflicting proxies, cookie import, pressure cleanup, and browser-process death/recovery.
• Automatic teardown now retains the same request proxy in a bounded TTL cache, so a later request without another proxy cannot silently fall back to direct routing. Explicit session deletion clears it.
• CI and the npm publish workflow both run the browser-dependent request-proxy suite under Xvfb.

I also added generated OpenAPI/README documentation and a credential-free proxied response field. Proxy credentials are compared through the request-proxy helpers and are never emitted in logs or API responses.