@alsania-io/api-client-kit

Auth engine, OpenAPI loader, HTTP executor, and response shaper for Alsania services that talk to authenticated external APIs.

Extracted from: openapi-dynamic-mcp (MIT, Andrey Starostin).

Why this exists

The auth/ module here is the single most reusable piece we found across six reviewed projects. It handles API key, bearer, basic, and four OAuth2 flows (client credentials, password, device code, authorization code + PKCE) behind one resolver, with a persistent token store and agent-relayable interactive responses.

Modules

auth/

| File | Responsibility | |---|---| | resolveAuth.ts | Dispatch by security scheme type | | schemeAuth.ts | API key / bearer / basic | | oauthClient.ts | Shared OAuth engine (oauth4webapi) | | deviceCodeFlow.ts | Device code flow | | authCodeFlow.ts | Authorization code + PKCE | | authStore.ts | Token persistence | | env.ts | Env-var derivation (<API>_<SCHEME>_ACCESS_TOKEN, etc.) |

openapi/

| File | Responsibility | |---|---| | loadSpec.ts | Load OpenAPI 3.x / Swagger 2.0 from file or URL | | endpointIndex.ts | Index endpoints for lookup | | jsonPointer.ts | JSON Pointer resolution |

http/

| File | Responsibility | |---|---| | requestExecutor.ts | Build request, dry-run mode, retry 429 |

output/

| File | Responsibility | |---|---| | jsonPath.ts | JSONPath response filtering + size warnings |

config/

| File | Responsibility | |---|---| | loadConfig.ts | YAML config validation |

Interactive OAuth2 pattern

When a flow needs the user, return a structured object an agent can relay:

{
  "status": "authorization_required",
  "method": "device_code",
  "verificationUri": "https://auth.example.com/device",
  "userCode": "ABCD-1234",
  "instruction": "After the user confirms, call this endpoint again."
}

This is the pattern to standardize across all Alsania MCP servers.

Security notes

• Tokens are never logged.
• Env vars are the source of truth; the store is a fallback.
• Add a URL allowlist before wiring to production credentials (see TODO in the security plan).

Setup

make install
make build

License

MIT. See LICENSE. Original copyright (c) 2026 Andrey Starostin.