Smart backend services

[spicyfalafel]

Summary

Add SMART Backend Services authentication provider for server-to-server OAuth 2.0 authentication per HL7 spec.

Uses oauth4webapi library for OAuth 2.0 implementation.

Features

• SmartBackendServicesAuthProvider - OAuth 2.0 client_credentials grant with JWT bearer assertion
• CryptoKey - accepts Web Crypto API key (not PEM string)
• Discovery via .well-known/smart-configuration endpoint
• Token caching with proactive refresh before expiry (tokenExpirationBuffer)
• Thundering herd prevention — concurrent token requests deduplicated via shared promise
• Retry on 401 with fresh token (handles ReadableStream body via .tee())

Also includes

• validateBaseUrl and mergeHeaders utilities extracted to shared utils.ts
• Integration tests with real Aidbox (no mocks)

Usage

import { AidboxClient, SmartBackendServicesAuthProvider } from "@health-samurai/aidbox-client";

// Import or generate your private key using Web Crypto API
const privateKey = await crypto.subtle.generateKey(
  { name: "RSASSA-PKCS1-v1_5", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-384" },
  true,
  ["sign", "verify"]
).then(kp => kp.privateKey);

const auth = new SmartBackendServicesAuthProvider({
  baseUrl: "https://fhir.example.com",
  clientId: "my-backend-service",
  privateKey: privateKey,      // CryptoKey from Web Crypto API
  keyId: "key-001",            // Must match kid in JWKS registered on server
  scope: "system/*.read",
  // tokenExpirationBuffer: 30,  // Optional: seconds before expiry to refresh (default: 30)
  // allowInsecureRequests: true, // Optional: allow HTTP for testing (default: false)
});

const client = new AidboxClient("https://fhir.example.com", auth);

Test plan

• Integration tests with real Aidbox (no mocks)
• Token acquisition and caching
• FHIR operations via AidboxClient
• 401 retry logic
• Session management (establishSession, revokeSession)
• Lint and typecheck pass

Documentation

• Aidbox docs: https://docs.aidbox.app/modules/security-and-access-control/auth/smart-app/smart-on-fhir-app-launch/smart-backend-services
• spec https://hl7.org/fhir/smart-app-launch/backend-services.html

---

Note

Medium Risk
Introduces new OAuth/token-handling logic (caching, retry, discovery) and changes request header/baseUrl validation behavior in auth providers; functional risk is moderate despite added integration coverage.

Overview
Adds a new SmartBackendServicesAuthProvider to @health-samurai/aidbox-client for SMART Backend Services (OAuth 2.0 client_credentials with private-key JWT), including OAuth discovery, token caching/refresh, concurrent token-request deduplication, and a single 401 retry.

Refactors existing auth providers to share new validateBaseUrl and mergeHeaders helpers, and updates docs/exports/dependencies (oauth4webapi) accordingly.

Expands integration testing: new end-to-end tests for SMART backend services (including on-the-fly keypair/JWKS setup in Aidbox), more deterministic FHIR HTTP tests with DB cleanup, and forces Vitest to run files sequentially; also updates .gitignore for local/dev artifacts.

^{Written by Cursor Bugbot for commit 017a933. This will update automatically on new commits. Configure here.}

[Aitem]

Use real smart app instead mock

[Aitem]

Basically, by code organization, it's ok for me
@rublag-hs need you asist with cryprography part

[spicyfalafel]

@rublag-hs please take a look

[rublag-hs]

Are there any widespread libraries to interact with OAuth2/OIDC? Maybe we can use them instead of reinventing the wheel?

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[Aitem]

LGTM