oci-common

oci-common is the foundational package underlying every one of the many service SDKs published from Oracle’s oci-typescript-sdk monorepo (identity, object storage, key management, vault, secrets, and so on). Rather than each service package reimplementing HTTP signing, credential handling, and retry logic, they all depend on oci-common for that shared plumbing — most developers get it transitively and only install it directly when building a lower-level integration or wrapping an OCI endpoint that doesn’t yet have a dedicated service package.

The package implements OCI’s request-signing protocol (an RSA-SHA256 signature over a fixed header set) and every authentication mode Oracle documents: local config-file/API-key auth, instance principals, resource principals, session-token (browser-based) auth, delegation tokens, and OKE Workload Identity for Kubernetes-hosted workloads. It also owns the cross-cutting concerns every generated client needs — configurable retry with exponential backoff and jitter, a circuit breaker for failing endpoints, waiters for polling long-running operations to a terminal state, and pagination helpers for list APIs.

What You Get

• Six authentication provider implementations — config-file/API-key, instance principal, resource principal, session-token, delegation-token, and OKE Workload Identity
• An RSA-SHA256 request signer implementing OCI’s HTTP signature scheme, including automatic content-SHA256 and content-length header population for POST/PUT/PATCH
• A configurable GenericRetrier with exponential backoff plus jitter, and a circuit breaker to stop hammering a failing endpoint
• Generic waiter utilities (genericWaiter, MaxAttemptsTerminationStrategy, and related delay/termination strategies) for polling long-running resources to a terminal state
• Pagination helpers (paginateRecords, paginateResponses, and their generic variants) for iterating OCI list APIs page-by-page

Common Use Cases

• Config-file authentication - a Node.js script reads the local OCI config file and signs requests with an API key for local development or CI
• Instance/resource principal auth in production - a service running on an OCI Compute instance or inside another OCI resource authenticates without embedding a private key
• Kubernetes workload identity - an app running in Oracle Container Engine for Kubernetes authenticates to OCI services via OkeWorkloadIdentityAuthenticationDetailsProvider instead of static credentials
• Building a custom OCI integration - a team wraps an OCI REST endpoint not yet covered by a generated service package, reusing oci-common’s signer and retrier directly

Under The Hood

Architecture oci-common separates concerns cleanly across single-purpose modules under lib/ — auth/ hosts one class per authentication strategy (ConfigFileAuthenticationDetailsProvider, InstancePrincipalsAuthenticationDetailsProviderBuilder, ResourcePrincipalAuthenticationDetailsProvider, SessionAuthDetailProvider, OkeWorkloadIdentityAuthenticationDetailsProvider) behind a common AuthenticationDetailsProvider interface, while signer.ts, retrier.ts, circuit-breaker.ts, and waiter.ts each own one cross-cutting concern that every generated service client composes together at call time. DefaultRequestSigner takes an AuthenticationDetailsProvider in its constructor and lazily resolves delegated/session-based providers via delegateAuthProvider on each signHttpRequest call, so credentials can rotate mid-session without the caller re-instantiating the signer. GenericRetrier is built from injectable delay/termination strategy pairs shared with waiter.ts, and a DefaultRetryCondition class centralizes which HTTP statuses and OCI service error codes are retryable — a decision every generated service package needs to make identically. The main coupling risk is structural rather than technical: this package is consumed by a very large number of downstream service packages in the same monorepo, so a change to any exported interface ripples through the entire SDK surface.

Tech Stack The package targets an older ECMAScript/CommonJS output via tsc with TypeScript strict mode enabled, running across several supported Node.js versions. Signing and hashing rely on jssha for SHA-256 digests, sshpk for private-key parsing, and the http-signature package for constructing the OCI signature header; jsonwebtoken and uuid support token-based auth flows. HTTP execution is abstracted behind an HttpClient interface with a fetch-based default implementation, which is what lets the same source also target browser builds via webpack for the handful of scenarios that need it. Resilience is handled by the opossum library for circuit-breaking rather than a hand-rolled implementation. The monorepo builds every service package with a file-based workspace dependency on this one, so consumers always get a version matched to the exact SDK release.

Code Quality Tests exist under a dedicated tests/ directory using Mocha and Chai, covering the signer, request/response generation, circuit breaker, config file reader, realm/region resolution, object serialization, and a sensitive-data sanitizer, with karma configured for browser-target test runs — but the public CI workflow only exercises install-and-build on pull requests, so test execution isn’t visibly gated from what’s in this repo alone. TypeScript strict mode is enabled and the codebase favors typed interfaces over loose objects, though the signer and retrier modules include a handful of explicit any casts and non-null assertions that trade type safety for pragmatism around optional interface methods. A Prettier config is present; no ESLint config is present in this clone despite typescript-eslint being a devDependency, so lint enforcement isn’t verifiable from the repo alone. Naming is consistent and descriptive throughout.

API Design As a ‘common’ package underpinning a large generated SDK, oci-common isn’t attempting novel abstractions so much as comprehensive coverage of every authentication pattern Oracle documents for OCI — including newer entries like OKE Workload Identity for Kubernetes-native auth and built-in delegation-token (on-behalf-of) support, which go beyond what a typical cloud SDK’s shared auth layer covers. The public surface is intentionally narrow and composable: consumers construct one AuthenticationDetailsProvider, pass it to a generated service client, and the signer/retrier/waiter machinery is wired in automatically by that client’s constructor, so day-to-day developers rarely touch this package’s internals directly. Getting started requires understanding OCI’s config-file conventions or which principal type applies to your runtime environment — a real, if standard-for-cloud-SDKs, conceptual prerequisite rather than boilerplate.