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
11 changes: 1 addition & 10 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,7 @@ N2API_ADMIN_USERNAME=admin
N2API_ADMIN_PASSWORD=change-me
N2API_ADMIN_PASSWORD_FILE=

# Secret material used for encrypting OAuth tokens at rest.
# Secret material used for encrypting stored credentials at rest.
# Use a long random value in real deployments.
N2API_ENCRYPTION_SECRET=change-me-to-a-long-random-secret
N2API_ENCRYPTION_SECRET_FILE=
Expand All @@ -151,15 +151,6 @@ N2API_ENCRYPTION_KEY_ID=default
N2API_ENCRYPTION_PREVIOUS_KEYS=[]
N2API_ENCRYPTION_PREVIOUS_KEYS_FILE=

# OpenAI/Codex OAuth.
# The default flow uses the Codex-compatible OpenAI OAuth client with PKCE.
# Leave these OAuth values blank unless you intentionally need endpoint/client overrides.
OPENAI_OAUTH_CLIENT_ID=
OPENAI_OAUTH_CLIENT_SECRET=
OPENAI_OAUTH_CLIENT_SECRET_FILE=
OPENAI_OAUTH_REDIRECT_URL=http://localhost:1455/auth/callback
OPENAI_OAUTH_AUTH_URL=
OPENAI_OAUTH_TOKEN_URL=
OPENAI_API_BASE_URL=https://api.openai.com

# Host paths consumed only by the release secret-file Compose overrides.
Expand Down
15 changes: 7 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,7 @@
</div>

N2API is a personal AI API/account gateway for self-hosted use. It provides a
single OpenAI-compatible entry point for Codex/OpenAI OAuth accounts and
API-key-compatible upstreams, with a compact administration interface for
single OpenAI-compatible entry point for API-key-compatible upstreams, with a compact administration interface for
accounts, routing, client keys, and request logs.

N2API is inspired by sub2api's practical workflow, but it is a new
Expand All @@ -15,7 +14,7 @@ operations.

## Features

- Codex/OpenAI OAuth and API-key upstream accounts.
- API-key upstream accounts.
- OpenAI-compatible `/v1/models`, `/v1/responses`, and
`/v1/chat/completions` routes.
- Routing pools, model policies, fallback chains, and sticky sessions.
Expand Down Expand Up @@ -66,17 +65,17 @@ Compose details for diagnosis and owner-controlled fallback.

## Basic Setup

1. Add a Codex/OpenAI OAuth account or API-key upstream on **Provider
accounts**.
1. Add an API-key upstream on **Provider accounts**.
2. Test the account and enable the models it can serve.
3. Create a routing pool and add the provider account to it.
4. Create a client key on **API Keys** and bind it to the routing pool.
5. Use `http://localhost:3000/v1` as the OpenAI-compatible base URL and the
client key as the bearer token.

The OAuth flow returns an authorization link. Complete the provider login in
your browser, then paste the resulting callback URL into N2API to finish the
connection.
OAuth upstreams and fingerprint simulation have been removed. Existing OAuth
accounts remain archived in the database and must be replaced with API-key
upstreams in routing pools. Downstream Codex CLI clients remain supported via
API keys. See the [upgrade scope](docs/specs/2026-11-09-api-key-only-upstreams.md).

## Documentation

Expand Down
11 changes: 11 additions & 0 deletions backend/cmd/mock-openai/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,17 @@ func newDiagnosticState() *diagnosticState {
}

func (h *mockHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
// Scenario paths let API-only fixtures choose failures without header profiles.
if tail, ok := strings.CutPrefix(r.URL.Path, "/__scenario/"); ok {
scenario, path, found := strings.Cut(tail, "/")
if !found {
http.NotFound(w, r)
return
}
r = r.Clone(r.Context())
r.URL.Path = "/" + path
r.Header.Set(scenarioHeader, scenario)
}
if h.serveControl(w, r) {
return
}
Expand Down
8 changes: 8 additions & 0 deletions backend/cmd/mock-openai/main_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -482,3 +482,11 @@ func (w *flushRecorder) Flush() {
w.flushes++
w.ResponseRecorder.Flush()
}

func TestScenarioPath(t *testing.T) {
handler := newMockHandler()
response := performRequest(t, handler, http.MethodPost, "/__scenario/status-503/v1/chat/completions", `{"model":"mock","messages":[]}`, "")
if response.Code != http.StatusServiceUnavailable {
t.Fatalf("scenario status = %d: %s", response.Code, response.Body.String())
}
}
13 changes: 0 additions & 13 deletions backend/cmd/n2api/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -94,16 +94,12 @@ func selectedGatewayAccount(selected provider.SelectedAccount, err error) (gatew
AuthorizationToken: selected.AuthorizationToken,
BaseURL: selected.BaseURL,
ProxyURL: selected.ProxyURL,
ChatGPTAccountID: selected.ChatGPTAccountID,
MaxConcurrentRequests: selected.MaxConcurrentRequests,
RoutingPoolID: selected.RoutingPoolID,
RoutingPoolName: selected.RoutingPoolName,
RoutingPoolFallbackDepth: selected.RoutingPoolFallbackDepth,
RoutingPoolFallbackChain: selected.RoutingPoolFallbackChain,
RoutingPoolError: selected.RoutingPoolError,
FingerprintUA: selected.FingerprintUA,
FingerprintTLS: selected.FingerprintTLS,
FingerprintHeaders: selected.FingerprintHeaders,
}
if err != nil {
return mapped, err
Expand All @@ -115,10 +111,6 @@ func (p gatewayAccountProvider) RecordAccountFailure(ctx context.Context, accoun
return p.service.RecordAccountFailure(ctx, accountID, statusCode, retryAfter, message)
}

func (p gatewayAccountProvider) RefreshAccountAuthorization(ctx context.Context, accountID int64, rejectedAccessToken string, statusCode int, message string) (string, bool, bool, error) {
return p.service.RefreshAccountAuthorization(ctx, accountID, rejectedAccessToken, statusCode, message)
}

func (p gatewayAccountProvider) RecordAccountUsed(ctx context.Context, accountID int64) error {
return p.service.RecordAccountUsed(ctx, accountID)
}
Expand Down Expand Up @@ -437,11 +429,6 @@ func runServer() int {
responseAffinityRepo := store.NewResponseAffinityRepository(pool, cfg.EncryptionSecret)
providerService := provider.NewService(providerRepo, provider.NewHTTPClient(http.DefaultClient), provider.Config{
Provider: "openai",
ClientID: cfg.OpenAIOAuthClientID,
ClientSecret: cfg.OpenAIOAuthSecret,
RedirectURL: cfg.OpenAIOAuthRedirectURL,
AuthURL: cfg.OpenAIOAuthAuthURL,
TokenURL: cfg.OpenAIOAuthTokenURL,
APIBaseURL: cfg.OpenAIAPIBaseURL,
Secret: cfg.EncryptionSecret,
EncryptionKeyring: cfg.EncryptionKeyring,
Expand Down
1 change: 0 additions & 1 deletion backend/cmd/n2api/main_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -305,7 +305,6 @@ func TestProviderAccountMetricsPreserveLastSnapshotAfterRefreshFailure(t *testin

func TestGatewayAccountProviderReportsAccountFailures(t *testing.T) {
var _ gateway.AccountFailureReporter = gatewayAccountProvider{}
var _ gateway.AccountAuthorizationRefresher = gatewayAccountProvider{}
var _ gateway.AccountUsageRecorder = gatewayAccountProvider{}
var _ gateway.AccountRecoveryRecorder = gatewayAccountProvider{}
}
Expand Down
4 changes: 0 additions & 4 deletions backend/e2e/helpers_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,6 @@ type e2eResources struct {
poolName string
clientKeyID int64
clientSecret string
fingerprintIDs []int64
accountIDs []int64
poolIDs []int64
clientKeyIDs []int64
Expand Down Expand Up @@ -281,9 +280,6 @@ func registerCleanup(t *testing.T, client *http.Client, env e2eEnvironment, reso
for _, id := range uniquePositiveIDs(resources.accountID, resources.accountIDs) {
_, _ = performJSON(ctx, client, http.MethodDelete, env.baseURL+"/api/admin/provider-accounts/"+int64String(id), nil, nil, nil)
}
for _, id := range uniquePositiveIDs(0, resources.fingerprintIDs) {
_, _ = performJSON(ctx, client, http.MethodDelete, env.baseURL+"/api/admin/fingerprint-profiles/"+int64String(id), nil, nil, nil)
}
if resources.pricingUpdated {
_, _ = performJSON(ctx, client, http.MethodPut, env.baseURL+"/api/admin/usage-pricing", nil, resources.pricingBefore, nil)
}
Expand Down
26 changes: 13 additions & 13 deletions backend/e2e/protocol_e2e_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ func TestGatewayNormalizesRetryableUpstreamStatusLogs(t *testing.T) {
for _, test := range tests {
t.Run(test.scenario, func(t *testing.T) {
fixture := newProtocolFixture(t)
profileID := fixture.createFingerprintProfile(test.scenario, test.scenario)
profileID := test.scenario
accountIDs := make([]int64, 0, 5)
for index := 0; index < 5; index++ {
accountIDs = append(accountIDs, fixture.createAccount(test.scenario+"-account-"+int64String(int64(index)), index, profileID))
Expand Down Expand Up @@ -76,7 +76,7 @@ func TestGatewayHandlesUpstreamContentTypeAndUsageVariants(t *testing.T) {
for _, test := range tests {
t.Run(test.scenario, func(t *testing.T) {
fixture := newProtocolFixture(t)
profileID := fixture.createFingerprintProfile(test.scenario, test.scenario)
profileID := test.scenario
accountID := fixture.createAccount(test.scenario+"-account", 0, profileID)
_, keyID, secret := fixture.createPoolAndKey(test.scenario, []int64{accountID})
sessionID := "e2e-" + test.scenario + "-" + fixture.suffix
Expand Down Expand Up @@ -126,7 +126,7 @@ func TestGatewayHandlesResponsesStreamUsageVariants(t *testing.T) {
for _, test := range tests {
t.Run(test.scenario, func(t *testing.T) {
fixture := newProtocolFixture(t)
profileID := fixture.createFingerprintProfile("responses "+test.scenario, test.scenario)
profileID := test.scenario
accountID := fixture.createAccount("responses-"+test.scenario+"-account", 0, profileID)
_, keyID, secret := fixture.createPoolAndKey("responses-"+test.scenario, []int64{accountID})
sessionID := "e2e-responses-" + test.scenario + "-" + fixture.suffix
Expand Down Expand Up @@ -155,9 +155,9 @@ func TestGatewayHandlesResponsesStreamUsageVariants(t *testing.T) {

func TestGatewayFallsBackWhenUpstreamDisconnectsBeforeHeaders(t *testing.T) {
fixture := newProtocolFixture(t)
disconnectProfileID := fixture.createFingerprintProfile("disconnect before headers", "disconnect-before-headers")
disconnectProfileID := "disconnect-before-headers"
failedAccountID := fixture.createAccount("disconnect-before-account", 0, disconnectProfileID)
happyAccountID := fixture.createAccount("disconnect-fallback-account", 1, 0)
happyAccountID := fixture.createAccount("disconnect-fallback-account", 1, "")
_, keyID, secret := fixture.createPoolAndKey("disconnect-before", []int64{failedAccountID, happyAccountID})
fixture.resetMock()
sessionID := "e2e-disconnect-before-" + fixture.suffix
Expand All @@ -183,7 +183,7 @@ func TestGatewayFallsBackWhenUpstreamDisconnectsBeforeHeaders(t *testing.T) {

func TestGatewayFallsBackAfterOnePreStreamServiceUnavailable(t *testing.T) {
fixture := newProtocolFixture(t)
retryProfileID := fixture.createFingerprintProfile("service unavailable once", "status-503-once")
retryProfileID := "status-503-once"
failedAccountID := fixture.createAccount("status-once-account", 0, retryProfileID)
happyAccountID := fixture.createAccount("status-once-fallback-account", 1, retryProfileID)
_, keyID, secret := fixture.createPoolAndKey("status-once", []int64{failedAccountID, happyAccountID})
Expand Down Expand Up @@ -211,9 +211,9 @@ func TestGatewayFallsBackAfterOnePreStreamServiceUnavailable(t *testing.T) {

func TestGatewayDoesNotRetryAfterFirstStreamEvent(t *testing.T) {
fixture := newProtocolFixture(t)
disconnectProfileID := fixture.createFingerprintProfile("disconnect after event", "disconnect-after-first-event")
disconnectProfileID := "disconnect-after-first-event"
failedAccountID := fixture.createAccount("disconnect-after-account", 0, disconnectProfileID)
happyAccountID := fixture.createAccount("disconnect-unused-account", 1, 0)
happyAccountID := fixture.createAccount("disconnect-unused-account", 1, "")
_, keyID, secret := fixture.createPoolAndKey("disconnect-after", []int64{failedAccountID, happyAccountID})
fixture.resetMock()
sessionID := "e2e-disconnect-after-" + fixture.suffix
Expand All @@ -239,7 +239,7 @@ func TestGatewayDoesNotRetryAfterFirstStreamEvent(t *testing.T) {

func TestGatewayDoesNotRetryWhenStreamEndsWithoutCompletion(t *testing.T) {
fixture := newProtocolFixture(t)
missingProfileID := fixture.createFingerprintProfile("missing completion", "missing-completion")
missingProfileID := "missing-completion"
accountID := fixture.createAccount("missing-completion-account", 0, missingProfileID)
_, keyID, secret := fixture.createPoolAndKey("missing-completion", []int64{accountID})
fixture.resetMock()
Expand Down Expand Up @@ -269,8 +269,8 @@ func TestGatewayDoesNotRetryWhenStreamEndsWithoutCompletion(t *testing.T) {

func TestGatewayStickySessionUsesSameAccountTwice(t *testing.T) {
fixture := newProtocolFixture(t)
firstAccountID := fixture.createAccount("sticky-first-account", 0, 0)
secondAccountID := fixture.createAccount("sticky-second-account", 0, 0)
firstAccountID := fixture.createAccount("sticky-first-account", 0, "")
secondAccountID := fixture.createAccount("sticky-second-account", 0, "")
poolID, keyID, secret := fixture.createPoolAndKey("sticky", []int64{firstAccountID, secondAccountID})
sessionID := "e2e-sticky-" + fixture.suffix
request := map[string]any{
Expand Down Expand Up @@ -308,7 +308,7 @@ func TestGatewayStickySessionUsesSameAccountTwice(t *testing.T) {

func TestGatewayEnforcesPerKeyRequestLimitBeforeUpstream(t *testing.T) {
fixture := newProtocolFixture(t)
accountID := fixture.createAccount("rate-limit-account", 0, 0)
accountID := fixture.createAccount("rate-limit-account", 0, "")
_, keyID, secret := fixture.createPoolAndKey("rate-limit", []int64{accountID})
mustJSON(t, fixture.client, http.MethodPut, fixture.env.baseURL, "/api/admin/keys/"+int64String(keyID)+"/limits", "key_limits", nil, map[string]int{
"requestsPerMinute": 1,
Expand Down Expand Up @@ -348,7 +348,7 @@ func TestGatewayEnforcesPerKeyRequestLimitBeforeUpstream(t *testing.T) {

func TestGatewayPropagatesCancellationWhileUpstreamWaitsForHeaders(t *testing.T) {
fixture := newProtocolFixture(t)
timeoutProfileID := fixture.createFingerprintProfile("timeout before headers", "timeout-before-headers")
timeoutProfileID := "timeout-before-headers"
accountID := fixture.createAccount("timeout-account", 0, timeoutProfileID)
_, keyID, secret := fixture.createPoolAndKey("timeout-cancel", []int64{accountID})
fixture.resetMock()
Expand Down
29 changes: 4 additions & 25 deletions backend/e2e/protocol_helpers_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -56,29 +56,7 @@ func newProtocolFixture(t *testing.T) *protocolFixture {
}
}

func (fixture *protocolFixture) createFingerprintProfile(name, scenario string) int64 {
fixture.t.Helper()
var response struct {
Profile struct {
ID int64 `json:"id"`
} `json:"profile"`
}
mustJSON(fixture.t, fixture.client, http.MethodPost, fixture.env.baseURL, "/api/admin/fingerprint-profiles", "fingerprint_create", nil, map[string]any{
"name": name + " " + fixture.suffix,
"description": "gateway protocol e2e fixture",
"headers": map[string]string{
"X-N2API-E2E-Scenario": scenario,
},
"enabled": true,
}, &response, http.StatusCreated)
if response.Profile.ID <= 0 {
fixture.t.Fatal("stage=fingerprint_create field=id")
}
fixture.resources.fingerprintIDs = append(fixture.resources.fingerprintIDs, response.Profile.ID)
return response.Profile.ID
}

func (fixture *protocolFixture) createAccount(name string, priority int, fingerprintProfileID int64) int64 {
func (fixture *protocolFixture) createAccount(name string, priority int, scenario string) int64 {
fixture.t.Helper()
input := map[string]any{
"name": name + " " + fixture.suffix,
Expand All @@ -89,9 +67,10 @@ func (fixture *protocolFixture) createAccount(name string, priority int, fingerp
"loadFactor": 1,
"models": []string{e2eModel},
}
if fingerprintProfileID > 0 {
input["fingerprintProfileId"] = fingerprintProfileID
if scenario != "" {
input["baseUrl"] = strings.TrimRight(fixture.env.mockBaseURL, "/") + "/__scenario/" + scenario
}

var response struct {
Account struct {
ID int64 `json:"id"`
Expand Down
14 changes: 7 additions & 7 deletions backend/e2e/resource_boundaries_e2e_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ func TestGatewayRejectsKnownLengthAndChunkedOversizedBodies(t *testing.T) {
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
fixture := newProtocolFixture(t)
accountID := fixture.createAccount("oversized-request-account", 0, 0)
accountID := fixture.createAccount("oversized-request-account", 0, "")
_, keyID, secret := fixture.createPoolAndKey("oversized-request", []int64{accountID})
fixture.resetMock()

Expand All @@ -56,7 +56,7 @@ func TestGatewayRejectsKnownLengthAndChunkedOversizedBodies(t *testing.T) {

func TestGatewayDoesNotReplayAcceptedBodyAboveReplayLimit(t *testing.T) {
fixture := newProtocolFixture(t)
profileID := fixture.createFingerprintProfile("large body service unavailable", "status-503-once")
profileID := "status-503-once"
firstAccountID := fixture.createAccount("large-body-first", 0, profileID)
secondAccountID := fixture.createAccount("large-body-second", 1, profileID)
_, keyID, secret := fixture.createPoolAndKey("large-body", []int64{firstAccountID, secondAccountID})
Expand Down Expand Up @@ -84,7 +84,7 @@ func TestGatewayDoesNotReplayAcceptedBodyAboveReplayLimit(t *testing.T) {

func TestGatewayTimesOutSlowUploadAndReleasesAdmissionSlots(t *testing.T) {
fixture := newProtocolFixture(t)
accountID := fixture.createAccount("slow-upload-account", 0, 0)
accountID := fixture.createAccount("slow-upload-account", 0, "")
_, keyID, secret := fixture.createPoolAndKey("slow-upload", []int64{accountID})
fixture.resetMock()

Expand Down Expand Up @@ -131,7 +131,7 @@ func TestGatewayTimesOutSlowUploadAndReleasesAdmissionSlots(t *testing.T) {
func TestGatewayBoundsUpstreamHeadersBodiesAndStreams(t *testing.T) {
t.Run("response header timeout", func(t *testing.T) {
fixture := newProtocolFixture(t)
profileID := fixture.createFingerprintProfile("response header timeout", "timeout-before-headers")
profileID := "timeout-before-headers"
accountID := fixture.createAccount("response-header-timeout", 0, profileID)
_, keyID, secret := fixture.createPoolAndKey("response-header-timeout", []int64{accountID})
fixture.resetMock()
Expand All @@ -155,7 +155,7 @@ func TestGatewayBoundsUpstreamHeadersBodiesAndStreams(t *testing.T) {

t.Run("oversized JSON response", func(t *testing.T) {
fixture := newProtocolFixture(t)
profileID := fixture.createFingerprintProfile("oversized JSON response", "oversized-json-response")
profileID := "oversized-json-response"
accountID := fixture.createAccount("oversized-json-response", 0, profileID)
_, keyID, secret := fixture.createPoolAndKey("oversized-json-response", []int64{accountID})
fixture.resetMock()
Expand All @@ -175,7 +175,7 @@ func TestGatewayBoundsUpstreamHeadersBodiesAndStreams(t *testing.T) {

t.Run("stalled SSE", func(t *testing.T) {
fixture := newProtocolFixture(t)
profileID := fixture.createFingerprintProfile("stalled SSE", "stalled-sse")
profileID := "stalled-sse"
accountID := fixture.createAccount("stalled-sse", 0, profileID)
_, keyID, secret := fixture.createPoolAndKey("stalled-sse", []int64{accountID})
fixture.resetMock()
Expand All @@ -195,7 +195,7 @@ func TestGatewayBoundsUpstreamHeadersBodiesAndStreams(t *testing.T) {

t.Run("periodic SSE", func(t *testing.T) {
fixture := newProtocolFixture(t)
profileID := fixture.createFingerprintProfile("periodic SSE", "periodic-sse")
profileID := "periodic-sse"
accountID := fixture.createAccount("periodic-sse", 0, profileID)
_, keyID, secret := fixture.createPoolAndKey("periodic-sse", []int64{accountID})
fixture.resetMock()
Expand Down
3 changes: 0 additions & 3 deletions backend/e2e/response_affinity_e2e_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -233,9 +233,6 @@ func responseAffinitySelectedAccount(selected provider.SelectedAccount, err erro
RoutingPoolFallbackDepth: selected.RoutingPoolFallbackDepth,
RoutingPoolFallbackChain: selected.RoutingPoolFallbackChain,
RoutingPoolError: selected.RoutingPoolError,
FingerprintUA: selected.FingerprintUA,
FingerprintTLS: selected.FingerprintTLS,
FingerprintHeaders: selected.FingerprintHeaders,
}
return mapped, err
}
Expand Down
2 changes: 0 additions & 2 deletions backend/go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,11 @@ require (
github.com/prometheus/client_golang v1.25.0
github.com/prometheus/client_model v0.6.3
github.com/prometheus/common v0.73.1
github.com/refraction-networking/utls v1.8.2
go.yaml.in/yaml/v3 v3.0.6
golang.org/x/crypto v0.58.0
)

require (
github.com/andybalholm/brotli v1.2.7 // indirect
github.com/beorn7/perks v1.0.1 // indirect
github.com/cespare/xxhash/v2 v2.3.0 // indirect
github.com/jackc/pgpassfile v1.0.0 // indirect
Expand Down
Loading
Loading