Oracle Cloud Object Storage

Oracle Cloud Infrastructure Object Storage via the S3 compatibility layer. Auth uses HMAC Customer Secret Keys, not regular API keys.

Installation

@aws-sdk/client-s3, @aws-sdk/s3-presigned-post, and @aws-sdk/s3-request-presigner are optional peer dependencies of files-sdk - install alongside the SDK so the adapter’s imports resolve at runtime.

npm install files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

pnpm add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

yarn add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

bun add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

Usage

import { Files } from "files-sdk";
import { oracleCloud } from "files-sdk/oracle-cloud";

const files = new Files({
  adapter: oracleCloud({
    bucket: "uploads",
    namespace: "axoki12345", // tenancy Object Storage namespace
    region: "us-ashburn-1",
    // accessKeyId / secretAccessKey auto-loaded from
    // OCI_ACCESS_KEY_ID / OCI_SECRET_ACCESS_KEY (Customer Secret Keys)
  }),
});

Oracle Cloud Infrastructure Object Storage via its S3 compatibility layer. A thin wrapper around the S3 adapter - endpoint derived from your tenancy namespace and region (<namespace>.compat.objectstorage.<region>.oraclecloud.com), path-style addressing on (OCI’s TLS cert doesn’t cover bucket subdomains under the namespace prefix), errors relabelled. Auth uses OCI’s HMAC Customer Secret Keys, not regular API signing keys - generate them under Profile -> User Settings -> Customer Secret Keys. Auto-loads from OCI_ACCESS_KEY_ID and OCI_SECRET_ACCESS_KEY.

Options

PropType

bucketstring

OCI bucket name. The adapter scopes all operations to it.

Typestring

namespacestring

OCI tenancy Object Storage namespace — a tenancy-scoped string assigned by Oracle. Find it under the OCI console: Profile → Tenancy → Object Storage Namespace, or via `oci os ns get`. Drives the endpoint host (`<namespace>.compat.objectstorage.<region>.oraclecloud.com`).

Typestring

regionstring

OCI region identifier, e.g. `"us-ashburn-1"`, `"us-phoenix-1"`, `"eu-frankfurt-1"`, `"uk-london-1"`, `"ap-tokyo-1"`. Drives the endpoint host; there's no env-var fallback. Doubles as the SigV4 region.

Typestring

endpoint?string

Override the OCI endpoint. When unset, defaults to `https://${namespace}.compat.objectstorage.${region}.oraclecloud.com`. The namespace prefix is part of the host, not the path — OCI's S3 compatibility layer scopes the bucket lookup to the namespace.

Typestring

accessKeyId?string

Customer secret key access key ID. Generate one in the OCI console under Profile → User Settings → Customer Secret Keys (these are the HMAC keys used for S3-compatible access, distinct from API signing keys). Falls back to `OCI_ACCESS_KEY_ID`; required if that env var isn't set.

Typestring

secretAccessKey?string

Customer Secret Key secret. Falls back to `OCI_SECRET_ACCESS_KEY`; required if that env var isn't set.

Typestring

forcePathStyle?boolean

Use path-style addressing (`/<bucket>/<key>`) rather than virtual-hosted style. Defaults to `true` for OCI — the namespace-prefixed host already scopes lookups, and OCI's wildcard cert does not cover the additional bucket subdomain, so virtual-hosted style typically fails TLS.

Typeboolean

publicBaseUrl?string

Origin used to build URLs from `url()`. When set, `url(key)` returns `${publicBaseUrl}/${key}` and skips signing. For buckets with a pre-authenticated request or a public visibility setting, point this at the corresponding URL prefix; a custom domain via the OCI Web Application Firewall / Load Balancer also works. When unset, `url()` falls back to a presigned GetObject (default expiry: 1 hour).

Typestring

defaultUrlExpiresIn?number

Default expiry, in seconds, for the presigned URLs returned by `url()` when `publicBaseUrl` is not set. Defaults to 3600 (1 hour).

Typenumber

Compatibility

Method	Status	Notes
`upload`	✅
`download`	✅
`delete`	✅
`list`	✅
`search`	✅
`head`	✅
`exists`	✅
`copy`	✅
`url`	✅
`signedUploadUrl`	✅