Zero-dependency S3-compatible signed URL generator and region data
npm install oossA lightweight, zero-dependency TypeScript library for S3-compatible signed URL generation and request signing.
只处理签名链接，适用于客户端直传或者一些可用签名链接实现的功能。不想安装依赖可以复制 src/core.ts 文件直接使用。
- 🎯 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.
``bash`
npm install ooss
`typescript
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=...
`
typescript
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'
});
`$3
Cloudflare R2 requires the field (Account ID based).
`typescript
import { signUrl } from 'ooss';const url = await signUrl({
accessKeyId: 'r2-key',
accessKeySecret: 'r2-secret',
region: 'auto',
bucket: 'my-bucket',
endpoint: 'https://.r2.cloudflarestorage.com'
}, 'data.json');
`$3
Supports standard S3-compatible V4 signing for Aliyun OSS.
typescript
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'
});
`$3
You can import lists of regions for convenience:
typescript
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
file. It contains the complete HMAC-SHA256 signature logic and types in a single file.`typescript
// After copying src/core.ts to your local project:
import { signatureUrlV4 } from './core';const url = await signatureUrlV4(config, key, options);
`API
$3
| Parameter | Type | Description |
| :--- | :--- | :--- |
|
| 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. |MIT