ooss

A lightweight, zero-dependency TypeScript library for S3-compatible signed URL generation and request signing.

只处理签名链接，适用于客户端直传或者一些可用签名链接实现的功能。不想安装依赖可以复制 src/core.ts 文件直接使用。

Features

• 🎯 Focused: Only handles S3 V4 signature generation (GET/PUT).
• 🪶 Lightweight: Zero dependencies. Uses native crypto and fetch.
• 💎 Portable: src/core.ts is a single, self-contained file. Copy it anywhere.
• 🌍 Region Data: Optional built-in region lists for AWS S3, Cloudflare R2, and Aliyun OSS.
• 🚀 Modern: Optimized for Node 22+, Browsers, and Edge Workers.

Installation

npm install ooss

Quick Start

import { signUrl } from 'ooss';

const url = await signUrl({
  accessKeyId: process.env.S3_KEY!,
  accessKeySecret: process.env.S3_SECRET!,
  region: 'us-east-1',
  bucket: 'my-bucket'
}, 'path/to/object.jpg');

console.log(url); // https://my-bucket.s3.us-east-1.amazonaws.com/path/to/object.jpg?X-Amz-Algorithm=...

Examples

AWS S3 (Standard)

import { signUrl } from 'ooss';

const url = await signUrl({
  accessKeyId: 'AKIA...',
  accessKeySecret: 'secret',
  region: 'us-west-2',
  bucket: 'my-app-assets'
}, 'images/logo.png', {
  expires: 3600, // 1 hour
  method: 'GET'
});

Cloudflare R2 (Custom Endpoint)

Cloudflare R2 requires the endpoint field (Account ID based).

import { signUrl } from 'ooss';

const url = await signUrl({
  accessKeyId: 'r2-key',
  accessKeySecret: 'r2-secret',
  region: 'auto',
  bucket: 'my-bucket',
  endpoint: 'https://<ACCOUNT_ID>.r2.cloudflarestorage.com'
}, 'data.json');

Aliyun OSS (With Temporary Credentials)

Supports standard S3-compatible V4 signing for Aliyun OSS.

import { signUrl } from 'ooss';

const url = await signUrl({
  accessKeyId: 'STS.AccessKeyId',
  accessKeySecret: 'STS.AccessKeySecret',
  securityToken: 'STS.SecurityToken', // Required for temporary credentials
  region: 'cn-hangzhou',
  bucket: 'my-oss-bucket',
  endpoint: 'https://my-oss-bucket.oss-cn-hangzhou.aliyuncs.com'
}, 'backup.zip', {
  method: 'PUT',
  contentType: 'application/zip'
});

Built-in Region Data

You can import lists of regions for convenience:

import { S3_REGIONS } from 'ooss/regions/s3';
import { R2_REGIONS } from 'ooss/regions/r2';
import { A1_REGIONS } from 'ooss/regions/a1';

Portable Core (Copy & Paste)

If you don't want to add a dependency to your project, you can simply copy the src/core.ts file. It contains the complete HMAC-SHA256 signature logic and types in a single file.

// After copying src/core.ts to your local project:
import { signatureUrlV4 } from './core';

const url = await signatureUrlV4(config, key, options);

API

signUrl(config, objectKey, options?)

| Parameter | Type | Description | | :--- | :--- | :--- | | config.accessKeyId | string | Required. AccessKey ID. | | config.accessKeySecret | string | Required. AccessKey Secret. | | config.region | string | Required. Region (e.g., us-east-1). | | config.bucket | string | Required. Bucket name. | | config.endpoint | string | Optional. Custom S3 endpoint URL. | | config.securityToken| string | Optional. For temporary credentials. | | objectKey | string | The path to the object in the bucket. | | options.method | string | HTTP method (GET, PUT, etc.). Default GET. | | options.expires | number | Expiration in seconds. Default 3600. | | options.contentType| string | Required for PUT requests if you want to enforce it. |

License

MIT