@oras-project/oci-client 0.18.0-alpha.0

package/LICENSE

@@ -0,0 +1,201 @@
+                              Apache License
+                        Version 2.0, January 2004
+                    http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+  "License" shall mean the terms and conditions for use, reproduction,
+  and distribution as defined by Sections 1 through 9 of this document.
+
+  "Licensor" shall mean the copyright owner or entity authorized by
+  the copyright owner that is granting the License.
+
+  "Legal Entity" shall mean the union of the acting entity and all
+  other entities that control, are controlled by, or are under common
+  control with that entity. For the purposes of this definition,
+  "control" means (i) the power, direct or indirect, to cause the
+  direction or management of such entity, whether by contract or
+  otherwise, or (ii) ownership of fifty percent (50%) or more of the
+  outstanding shares, or (iii) beneficial ownership of such entity.
+
+  "You" (or "Your") shall mean an individual or Legal Entity
+  exercising permissions granted by this License.
+
+  "Source" form shall mean the preferred form for making modifications,
+  including but not limited to software source code, documentation
+  source, and configuration files.
+
+  "Object" form shall mean any form resulting from mechanical
+  transformation or translation of a Source form, including but
+  not limited to compiled object code, generated documentation,
+  and conversions to other media types.
+
+  "Work" shall mean the work of authorship, whether in Source or
+  Object form, made available under the License, as indicated by a
+  copyright notice that is included in or attached to the work
+  (an example is provided in the Appendix below).
+
+  "Derivative Works" shall mean any work, whether in Source or Object
+  form, that is based on (or derived from) the Work and for which the
+  editorial revisions, annotations, elaborations, or other modifications
+  represent, as a whole, an original work of authorship. For the purposes
+  of this License, Derivative Works shall not include works that remain
+  separable from, or merely link (or bind by name) to the interfaces of,
+  the Work and Derivative Works thereof.
+
+  "Contribution" shall mean any work of authorship, including
+  the original version of the Work and any modifications or additions
+  to that Work or Derivative Works thereof, that is intentionally
+  submitted to Licensor for inclusion in the Work by the copyright owner
+  or by an individual or Legal Entity authorized to submit on behalf of
+  the copyright owner. For the purposes of this definition, "submitted"
+  means any form of electronic, verbal, or written communication sent
+  to the Licensor or its representatives, including but not limited to
+  communication on electronic mailing lists, source code control systems,
+  and issue tracking systems that are managed by, or on behalf of, the
+  Licensor for the purpose of discussing and improving the Work, but
+  excluding communication that is conspicuously marked or otherwise
+  designated in writing by the copyright owner as "Not a Contribution."
+
+  "Contributor" shall mean Licensor and any individual or Legal Entity
+  on behalf of whom a Contribution has been received by Licensor and
+  subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+  this License, each Contributor hereby grants to You a perpetual,
+  worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+  copyright license to reproduce, prepare Derivative Works of,
+  publicly display, publicly perform, sublicense, and distribute the
+  Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+  this License, each Contributor hereby grants to You a perpetual,
+  worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+  (except as stated in this section) patent license to make, have made,
+  use, offer to sell, sell, import, and otherwise transfer the Work,
+  where such license applies only to those patent claims licensable
+  by such Contributor that are necessarily infringed by their
+  Contribution(s) alone or by combination of their Contribution(s)
+  with the Work to which such Contribution(s) was submitted. If You
+  institute patent litigation against any entity (including a
+  cross-claim or counterclaim in a lawsuit) alleging that the Work
+  or a Contribution incorporated within the Work constitutes direct
+  or contributory patent infringement, then any patent licenses
+  granted to You under this License for that Work shall terminate
+  as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+  Work or Derivative Works thereof in any medium, with or without
+  modifications, and in Source or Object form, provided that You
+  meet the following conditions:
+
+  (a) You must give any other recipients of the Work or
+      Derivative Works a copy of this License; and
+
+  (b) You must cause any modified files to carry prominent notices
+      stating that You changed the files; and
+
+  (c) You must retain, in the Source form of any Derivative Works
+      that You distribute, all copyright, patent, trademark, and
+      attribution notices from the Source form of the Work,
+      excluding those notices that do not pertain to any part of
+      the Derivative Works; and
+
+  (d) If the Work includes a "NOTICE" text file as part of its
+      distribution, then any Derivative Works that You distribute must
+      include a readable copy of the attribution notices contained
+      within such NOTICE file, excluding those notices that do not
+      pertain to any part of the Derivative Works, in at least one
+      of the following places: within a NOTICE text file distributed
+      as part of the Derivative Works; within the Source form or
+      documentation, if provided along with the Derivative Works; or,
+      within a display generated by the Derivative Works, if and
+      wherever such third-party notices normally appear. The contents
+      of the NOTICE file are for informational purposes only and
+      do not modify the License. You may add Your own attribution
+      notices within Derivative Works that You distribute, alongside
+      or as an addendum to the NOTICE text from the Work, provided
+      that such additional attribution notices cannot be construed
+      as modifying the License.
+
+  You may add Your own copyright statement to Your modifications and
+  may provide additional or different license terms and conditions
+  for use, reproduction, or distribution of Your modifications, or
+  for any such Derivative Works as a whole, provided Your use,
+  reproduction, and distribution of the Work otherwise complies with
+  the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+  any Contribution intentionally submitted for inclusion in the Work
+  by You to the Licensor shall be under the terms and conditions of
+  this License, without any additional terms or conditions.
+  Notwithstanding the above, nothing herein shall supersede or modify
+  the terms of any separate license agreement you may have executed
+  with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+  names, trademarks, service marks, or product names of the Licensor,
+  except as required for reasonable and customary use in describing the
+  origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+  agreed to in writing, Licensor provides the Work (and each
+  Contributor provides its Contributions) on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+  implied, including, without limitation, any warranties or conditions
+  of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+  PARTICULAR PURPOSE. You are solely responsible for determining the
+  appropriateness of using or redistributing the Work and assume any
+  risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+  whether in tort (including negligence), contract, or otherwise,
+  unless required by applicable law (such as deliberate and grossly
+  negligent acts) or agreed to in writing, shall any Contributor be
+  liable to You for damages, including any direct, indirect, special,
+  incidental, or consequential damages of any character arising as a
+  result of this License or out of the use or inability to use the
+  Work (including but not limited to damages for loss of goodwill,
+  work stoppage, computer failure or malfunction, or any and all
+  other commercial damages or losses), even if such Contributor
+  has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+  the Work or Derivative Works thereof, You may choose to offer,
+  and charge a fee for, acceptance of support, warranty, indemnity,
+  or other liability obligations and/or rights consistent with this
+  License. However, in accepting such obligations, You may act only
+  on Your own behalf and on Your sole responsibility, not on behalf
+  of any other Contributor, and only if You agree to indemnify,
+  defend, and hold each Contributor harmless for any liability
+  incurred by, or claims asserted against, such Contributor by reason
+  of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+  To apply the Apache License to your work, attach the following
+  boilerplate notice, with the fields enclosed by brackets "[]"
+  replaced with your own identifying information. (Don't include
+  the brackets!)  The text should be enclosed in the appropriate
+  comment syntax for the file format. We also recommend that a
+  file or class name and description of purpose be included on the
+  same "printed page" as the copyright notice for easier
+  identification within third-party archives.
+
+Copyright (c) The ORAS Authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,313 @@
+# Node.js Bindings for rust-oci-client
+
+Node.js bindings for the [rust-oci-client](https://github.com/oras-project/rust-oci-client) library, providing high-performance OCI Distribution client functionality.
+
+**Version**: These bindings are versioned in sync with the parent `oci-client` crate.
+
+## Features
+
+- **High Performance**: Native Rust via NAPI-RS; binary data uses Node.js `Buffer`
+- **Full Auth Support**: Anonymous, Basic (username/password), and Bearer token authentication
+- **Complete ClientConfig**: All native configuration options exposed
+- **Multi-Platform Images**: Built-in platform resolution for Image Index manifests
+- **TypeScript Support**: Full type definitions included (see [index.d.ts](./index.d.ts))
+
+## Installation
+
+```bash
+npm install @oras-project/oci-client
+# or
+yarn add @oras-project/oci-client
+```
+
+## Usage
+
+```typescript
+import { OciClient, ClientProtocol, anonymousAuth, basicAuth } from '@oras-project/oci-client';
+
+// Create a client with default configuration
+const client = new OciClient();
+
+// Or with custom configuration
+const clientWithConfig = OciClient.withConfig({
+  protocol: ClientProtocol.Https,
+  acceptInvalidCertificates: false,
+  maxConcurrentDownload: 8,
+  maxConcurrentUpload: 8,
+});
+
+// Create a client targeting a specific platform (for multi-arch images)
+const armClient = OciClient.withConfig({
+  platform: {
+    os: 'linux',
+    architecture: 'arm64',
+    variant: 'v8', // optional
+  },
+});
+
+// Pull an image
+const imageData = await client.pull('ghcr.io/example/image:latest', anonymousAuth(), [
+  'application/vnd.oci.image.layer.v1.tar+gzip',
+]);
+
+console.log(`Pulled ${imageData.layers.length} layers`);
+console.log(`Digest: ${imageData.digest}`);
+
+// Push an image
+const response = await client.push(
+  'registry.example.com/myimage:v1',
+  layers,
+  config,
+  basicAuth('username', 'password'),
+  undefined, // Let the client generate the manifest
+);
+
+console.log(`Manifest URL: ${response.manifestUrl}`);
+
+// Pull image manifest
+const { manifest, digest } = await client.pullImageManifest(
+  'ghcr.io/example/image:latest',
+  anonymousAuth(),
+);
+
+// Push a manifest list (multi-platform image)
+const manifestUrl = await client.pushManifestList(
+  'registry.example.com/myimage:v1',
+  basicAuth('username', 'password'),
+  imageIndex,
+);
+
+// Pull referrers (OCI 1.1)
+const referrers = await client.pullReferrers(
+  'ghcr.io/example/image@sha256:abc123...',
+  'application/vnd.example.sbom',
+);
+```
+
+## API Reference
+
+### Client
+
+#### `new OciClient()`
+
+Create a client with default configuration.
+
+#### `OciClient.withConfig(config: ClientConfig)`
+
+Create a client with custom configuration.
+
+### Platform Selection
+
+For multi-platform images (Image Index/Manifest List), you can specify the target platform:
+
+```typescript
+const client = OciClient.withConfig({
+  platform: {
+    os: 'linux', // Required: linux, windows, darwin, etc.
+    architecture: 'arm64', // Required: amd64, arm64, arm, etc.
+    variant: 'v8', // Optional: v7, v8, etc. for ARM
+  },
+});
+```
+
+When pulling an image that references an Image Index, the client will automatically select the manifest matching the specified platform.
+
+### Authentication
+
+#### `anonymousAuth()`
+
+Create anonymous authentication.
+
+#### `basicAuth(username: string, password: string)`
+
+Create HTTP Basic authentication.
+
+#### `bearerAuth(token: string)`
+
+Create Bearer token authentication.
+
+#### `storeAuth(registry, auth)`
+
+Pre-authenticate with a registry. Useful for storing credentials before performing multiple operations.
+
+#### How authentication works
+
+Some methods accept an `auth` parameter directly:
+
+- **Explicit auth:** `pull`, `push`, `pullImageManifest`, `pullManifest`, `pullManifestRaw`, `pushManifestList`, `listTags`, `fetchManifestDigest`, `catalog`, `pullImageManifestAndListDigest`, `pullManifestAndConfigAndListDigest`
+
+These methods call the native `store_auth_if_needed` internally, which stores the credentials for the registry if not already stored, then uses them for the request.
+
+Other methods do **not** accept an `auth` parameter and rely on credentials previously stored by one of the methods above (or by an explicit `storeAuth` call):
+
+- **Stored auth:** `pullBlob`, `pullBlobToFile`, `pushBlob`, `pushBlobFromFile`, `pushManifest`, `blobExists`, `mountBlob`, `pullReferrers`
+
+A typical workflow authenticates once, then performs multiple operations:
+
+```typescript
+// Authenticate — credentials are stored for this registry
+await client.storeAuth('registry.example.com', basicAuth('user', 'token'));
+
+// These all use the stored credentials
+await client.pushBlob('registry.example.com/repo:v1', layerData, layerDigest);
+await client.pushManifest('registry.example.com/repo:v1', manifest);
+const exists = await client.blobExists('registry.example.com/repo:v1', layerDigest);
+```
+
+Alternatively, the first call with explicit `auth` stores credentials automatically:
+
+```typescript
+// pullManifest stores auth for registry.example.com as a side effect
+const { manifest } = await client.pullManifest(
+  'registry.example.com/repo:v1',
+  basicAuth('user', 'token'),
+);
+
+// Subsequent calls to the same registry reuse the stored credentials
+const blob = await client.pullBlob('registry.example.com/repo:v1', layerDigest);
+```
+
+For anonymous registries, call `storeAuth` with `anonymousAuth()` or use any explicit-auth method first.
+
+### Main Functions
+
+#### `pull(image, auth, acceptedMediaTypes)`
+
+Pull an image from the registry. Returns `ImageData` with layers as Buffers.
+
+#### `push(imageRef, layers, config, auth, manifest?)`
+
+Push an image to the registry. Returns `PushResponse`. Do not mutate layer or config `Buffer`s until the Promise settles (same contract as `fs.write` / `socket.write`).
+
+#### `pullImageManifest(image, auth)`
+
+Pull an image manifest. Returns `{ manifest, digest }`. If a multi-platform Image Index is encountered, automatically selects the platform-specific manifest.
+
+#### `pullManifest(image, auth)`
+
+Pull a manifest (either image or image index) from the registry. Returns `{ manifest, digest }`.
+
+#### `pullManifestRaw(image, auth, acceptedMediaTypes)`
+
+Pull a manifest as raw bytes. Returns a `Buffer`.
+
+#### `pushManifest(image, manifest)`
+
+Push a manifest (image or image index) to the registry. Returns the manifest URL.
+
+#### `pushManifestList(reference, auth, manifest)`
+
+Push a manifest list (image index). Returns manifest URL.
+
+#### `pullReferrers(image, artifactType?)`
+
+Pull referrers for an artifact (OCI 1.1 Referrers API). Returns `ImageIndex`.
+
+#### `pullBlob(image, digest)`
+
+Pull a blob from the registry. Returns a `Buffer`.
+
+#### `pullBlobToFile(image, digest, path)`
+
+Pull a blob from the registry and write it to `path` (created or truncated). Bytes go from the registry socket to disk and never enter a JavaScript `Buffer`. The digest is verified when the write completes.
+
+#### `pushBlob(image, data, digest)`
+
+Push a blob to the registry. Returns the blob digest. Do not mutate `data` until the Promise settles (same contract as `fs.write` / `socket.write`).
+
+#### `pushBlobFromFile(image, path, digest)`
+
+Push a blob from a file at `path`. The file is streamed to the registry. `digest` must be `sha256:` followed by the hex SHA-256 of the file contents.
+
+To pull or push a full image without buffering layers in V8, compose these with the manifest APIs: `pullManifest` then `pullBlobToFile` for the config and each layer; or `pushBlobFromFile` for large layers, `pushBlob` for small configs, then `pushManifest`. There is no image-level `pullToDir` / `pushFromDir`. Sources that are not already files should write a temp file first, then call `pushBlobFromFile`.
+
+#### `blobExists(image, digest)`
+
+Check if a blob exists in the registry. Returns `boolean`.
+
+#### `mountBlob(target, source, digest)`
+
+Mount a blob from one repository to another (cross-repository blob mounting).
+
+#### `listTags(image, auth, n?, last?)`
+
+List tags for a repository. Supports pagination via `n` (page size) and `last` (last tag from previous page). Returns `string[]`.
+
+#### `fetchManifestDigest(image, auth)`
+
+Fetch a manifest's digest without downloading the full manifest content. Returns the digest string.
+
+#### `catalog(image, auth, n?, last?)`
+
+List available repositories in the registry (OCI Distribution Spec `/v2/_catalog`). Supports pagination via `n` (page size) and `last` (last repo from previous page). Returns `string[]`.
+
+#### `pullImageManifestAndListDigest(image, auth)`
+
+Like `pullImageManifest`, but also returns the digest of the parent manifest list/image index when the resolved manifest came from one. Returns `{ manifest, digest, listDigest }`.
+
+#### `pullManifestAndConfigAndListDigest(image, auth)`
+
+Pull a manifest, its config JSON, and the parent manifest list digest. Returns `{ manifest, digest, config, listDigest }`.
+
+#### `close()`
+
+Explicitly release the underlying connection pool. Idempotent — returns `true` on first call, `false` on subsequent calls. After `close()`, all method calls will throw `"Client is closed"`.
+
+### Types
+
+See the TypeScript definitions for complete type information.
+
+## Building from Source
+
+```bash
+# Install dependencies
+yarn install
+
+# Build native module (release)
+yarn build
+
+# Build debug version
+yarn build:debug
+
+# Run tests
+yarn test
+
+# Lint
+yarn lint
+```
+
+## TLS
+
+These bindings default to the **`native-tls`** backend (OpenSSL on Linux, Secure Transport on macOS,
+SChannel on Windows), unlike the parent `oci-client` crate which defaults to `rustls-tls`. The
+reason is cross-compilation: the prebuilt binaries cover nine target triples including musl and
+s390x, and `native-tls` with vendored OpenSSL (`native-tls-vendored` feature) produces
+self-contained binaries on all of them without requiring a system Rust toolchain or OpenSSL headers
+at runtime.
+
+If you build from source and prefer a pure-Rust TLS stack, you can enable the `rustls-tls` feature
+instead:
+
+```bash
+yarn napi build --platform --release --no-default-features --features rustls-tls
+```
+
+## Supported Platforms
+
+- Windows x64 (MSVC)
+- macOS x64 (Intel)
+- macOS ARM64 (Apple Silicon)
+- Linux x64 (glibc)
+- Linux ARM64 (glibc)
+- Linux x64 (musl/Alpine)
+- Linux ARM64 (musl/Alpine)
+- Linux s390x (glibc)
+- Linux ppc64le (glibc)
+
+## Contributing
+
+See the [CONTRIBUTING.md](./CONTRIBUTING.md) file for contribution guidelines.
+
+## License
+
+Apache-2.0