@eqxjs/file-namagement

File management library for NestJS microservices, providing signed (SigV4) S3 file get/put operations over a configurable HTTPS proxy.

Installation

npm install @eqxjs/file-namagement

Usage

import { s3Getfile, s3Putfile } from "@eqxjs/file-namagement";

// Download a file from S3
const response = await s3Getfile(
  "my-bucket",
  "path/to/object.txt",
  "us-east-1",
  process.env.AWS_ACCESS_KEY_ID!,
  process.env.AWS_SECRET_ACCESS_KEY!,
  "my-bucket.s3.us-east-1.amazonaws.com",
  "s3-proxy.internal.example.com"
);

// Upload a file to S3
await s3Putfile(
  "my-bucket",
  "path/to/object.txt",
  "us-east-1",
  process.env.AWS_ACCESS_KEY_ID!,
  process.env.AWS_SECRET_ACCESS_KEY!,
  "my-bucket.s3.us-east-1.amazonaws.com",
  "s3-proxy.internal.example.com",
  Buffer.from("hello world"),
  "text/plain"
);

API

s3Getfile(bucket, key, region, accessKeyId, secretAccessKey, s3HostName, s3ProxyHostName, httpsAgent?, timeout?)

Signs a GET request with AWS SigV4 and fetches the object through the given proxy host.

| Parameter | Type | Description | | --- | --- | --- | | bucket | string | S3 bucket name | | key | string | Object key | | region | string | AWS region | | accessKeyId | string | AWS access key ID | | secretAccessKey | string | AWS secret access key | | s3HostName | string | Host name used for SigV4 signing (actual S3 endpoint) | | s3ProxyHostName | string | Host name the request is actually sent to (proxy) | | httpsAgent | https.Agent (optional) | Custom HTTPS agent | | timeout | number (optional, default 5000) | Request timeout in ms |

Returns a Promise<AxiosResponse> with responseType: "arraybuffer".

s3Putfile(bucket, key, region, accessKeyId, secretAccessKey, s3HostName, s3ProxyHostName, data, contentType, httpsAgent?, timeout?)

Signs a PUT request with AWS SigV4 and uploads the given buffer through the proxy host.

| Parameter | Type | Description | | --- | --- | --- | | bucket | string | S3 bucket name | | key | string | Object key | | region | string | AWS region | | accessKeyId | string | AWS access key ID | | secretAccessKey | string | AWS secret access key | | s3HostName | string | Host name used for SigV4 signing (actual S3 endpoint) | | s3ProxyHostName | string | Host name the request is actually sent to (proxy) | | data | Buffer | File content to upload | | contentType | string | MIME type of the uploaded content | | httpsAgent | https.Agent (optional) | Custom HTTPS agent | | timeout | number (optional, default 5000) | Request timeout in ms |

Returns a Promise<AxiosResponse>.

Security Notes

• Never hardcode accessKeyId / secretAccessKey; load credentials from environment variables or a secrets manager.
• Keep the axios dependency up to date — run npm audit regularly and apply npm audit fix to pick up security patches.

Development

npm run build    # Compile TypeScript to dist/
npm test         # Run Jest tests
npm run format   # Format source with Prettier

License

ISC