Object Storage

Object Storage Protocol

Unified storage protocol that combines:

Object storage systems (S3, Azure Blob, GCS, MinIO)
Scoped storage configuration (temp, cache, data, logs, config, public)
Multi-cloud storage providers
Bucket/container configuration
Access control and permissions
Lifecycle policies for data retention
Presigned URLs for secure direct access
Multipart uploads for large files

Source: packages/spec/src/system/object-storage.zod.ts

TypeScript Usage

import { AccessControlConfigSchema, BucketConfigSchema, FileMetadataSchema, LifecycleActionSchema, LifecyclePolicyConfigSchema, LifecyclePolicyRuleSchema, MultipartUploadConfigSchema, ObjectMetadataSchema, ObjectStorageConfigSchema, PresignedUrlConfigSchema, StorageAclSchema, StorageClassSchema, StorageConnectionSchema, StorageProviderSchema, StorageScopeSchema } from '@objectstack/spec/system';
import type { AccessControlConfig, BucketConfig, FileMetadata, LifecycleAction, LifecyclePolicyConfig, LifecyclePolicyRule, MultipartUploadConfig, ObjectMetadata, ObjectStorageConfig, PresignedUrlConfig, StorageAcl, StorageClass, StorageConnection, StorageProvider, StorageScope } from '@objectstack/spec/system';

// Validate data
const result = AccessControlConfigSchema.parse(data);

AccessControlConfig

Properties

Property	Type	Required	Description
acl	`Enum<'private' \| 'public_read' \| 'public_read_write' \| 'authenticated_read' \| 'bucket_owner_read' \| 'bucket_owner_full_control'>`	✅	Default access control level
allowedOrigins	`string[]`	optional	CORS allowed origins
allowedMethods	`Enum<'GET' \| 'PUT' \| 'POST' \| 'DELETE' \| 'HEAD'>[]`	optional	CORS allowed HTTP methods
allowedHeaders	`string[]`	optional	CORS allowed headers
exposeHeaders	`string[]`	optional	CORS exposed headers
maxAge	`number`	optional	CORS preflight cache duration in seconds
corsEnabled	`boolean`	✅	Enable CORS configuration
publicAccess	`{ allowPublicRead: boolean; allowPublicWrite: boolean; allowPublicList: boolean }`	optional	Public access control
allowedIps	`string[]`	optional	Allowed IP addresses/CIDR blocks
blockedIps	`string[]`	optional	Blocked IP addresses/CIDR blocks

BucketConfig

Properties

Property	Type	Required	Description
name	`string`	✅	Bucket identifier in ObjectStack (snake_case)
label	`string`	✅	Display label
bucketName	`string`	✅	Actual bucket/container name in storage provider
region	`string`	optional	Storage region (e.g., us-east-1, westus)
provider	`Enum<'s3' \| 'azure_blob' \| 'gcs' \| 'minio' \| 'r2' \| 'spaces' \| 'wasabi' \| 'backblaze' \| 'local'>`	✅	Storage provider
endpoint	`string`	optional	Custom endpoint URL (for S3-compatible providers)
pathStyle	`boolean`	✅	Use path-style URLs (for S3-compatible providers)
versioning	`boolean`	✅	Enable object versioning
encryption	`{ enabled: boolean; algorithm: Enum<'AES256' \| 'aws:kms' \| 'azure:kms' \| 'gcp:kms'>; kmsKeyId?: string }`	optional	Server-side encryption configuration
accessControl	`{ acl: Enum<'private' \| 'public_read' \| 'public_read_write' \| 'authenticated_read' \| … +2 more>; allowedOrigins?: string[]; allowedMethods?: Enum<'GET' \| 'PUT' \| 'POST' \| 'DELETE' \| 'HEAD'>[]; allowedHeaders?: string[]; … }`	optional	Access control configuration
lifecyclePolicy	`{ enabled: boolean; rules: object[] }`	optional	Lifecycle policy configuration
multipartConfig	`{ enabled: boolean; partSize: number; maxParts: number; threshold: number; … }`	optional	Multipart upload configuration
tags	`Record<string, string>`	optional	Bucket tags for organization
description	`string`	optional	Bucket description
enabled	`boolean`	✅	Enable this bucket

FileMetadata

Properties

Property	Type	Required	Description
path	`string`	✅	File path
name	`string`	✅	File name
size	`integer`	✅	File size in bytes
mimeType	`string`	✅	MIME type
lastModified	`string`	✅	Last modified timestamp
created	`string`	✅	Creation timestamp
etag	`string`	optional	Entity tag
fileId	`string`	optional	Opaque sys_file id (ADR-0104 D3 file-as-reference)

LifecycleAction

Lifecycle policy action type

Allowed Values

transition
delete
abort

LifecyclePolicyConfig

Properties

Property	Type	Required	Description
enabled	`boolean`	✅	Enable lifecycle policies
rules	`{ id: string; enabled: boolean; action: Enum<'transition' \| 'delete' \| 'abort'>; prefix?: string; … }[]`	✅	Lifecycle rules

LifecyclePolicyRule

Properties

Property	Type	Required	Description
id	`string`	✅	Rule identifier
enabled	`boolean`	✅	Enable this rule
action	`Enum<'transition' \| 'delete' \| 'abort'>`	✅	Action to perform
prefix	`string`	optional	Object key prefix filter (e.g., "uploads/")
tags	`Record<string, string>`	optional	Object tag filters
daysAfterCreation	`number`	optional	Days after object creation
daysAfterModification	`number`	optional	Days after last modification
targetStorageClass	`Enum<'standard' \| 'intelligent' \| 'infrequent_access' \| 'glacier' \| 'deep_archive'>`	optional	Target storage class for transition action

MultipartUploadConfig

Properties

Property	Type	Required	Description
enabled	`boolean`	✅	Enable multipart uploads
partSize	`number`	✅	Part size in bytes (min 5MB, max 5GB)
maxParts	`number`	✅	Maximum number of parts (max 10,000)
threshold	`number`	✅	File size threshold to trigger multipart upload (bytes)
maxConcurrent	`number`	✅	Maximum concurrent part uploads
abortIncompleteAfterDays	`number`	optional	Auto-abort incomplete uploads after N days

ObjectMetadata

Properties

Property	Type	Required	Description
contentType	`string`	✅	MIME type (e.g., image/jpeg, application/pdf)
contentLength	`number`	✅	File size in bytes
contentEncoding	`string`	optional	Content encoding (e.g., gzip)
contentDisposition	`string`	optional	Content disposition header
contentLanguage	`string`	optional	Content language
cacheControl	`string`	optional	Cache control directives
etag	`string`	optional	Entity tag for versioning/caching
lastModified	`string`	optional	Last modification timestamp
versionId	`string`	optional	Object version identifier
storageClass	`Enum<'standard' \| 'intelligent' \| 'infrequent_access' \| 'glacier' \| 'deep_archive'>`	optional	Storage class/tier
encryption	`{ algorithm: string; keyId?: string }`	optional	Server-side encryption configuration
custom	`Record<string, string>`	optional	Custom user-defined metadata

ObjectStorageConfig

Properties

Property	Type	Required	Description
name	`string`	✅	Storage configuration identifier
label	`string`	✅	Display label
provider	`Enum<'s3' \| 'azure_blob' \| 'gcs' \| 'minio' \| 'r2' \| 'spaces' \| 'wasabi' \| 'backblaze' \| 'local'>`	✅	Primary storage provider
scope	`Enum<'global' \| 'tenant' \| 'user' \| 'session' \| 'temp' \| 'cache' \| 'data' \| 'logs' \| 'config' \| 'public'>`	✅	Storage scope
connection	`{ accessKeyId?: string; secretAccessKey?: string; sessionToken?: string; accountName?: string; … }`	✅	Connection credentials
buckets	`{ name: string; label: string; bucketName: string; region?: string; … }[]`	✅	Configured buckets
defaultBucket	`string`	optional	Default bucket name for operations
location	`string`	optional	Root path (local) or base location
quota	`integer`	optional	Max size in bytes
options	`Record<string, any>`	optional	Provider-specific configuration options
enabled	`boolean`	✅	Enable this storage configuration
description	`string`	optional	Configuration description

PresignedUrlConfig

Properties

Property	Type	Required	Description
operation	`Enum<'get' \| 'put' \| 'delete' \| 'head'>`	✅	Allowed operation
expiresIn	`number`	✅	Expiration time in seconds (max 7 days)
contentType	`string`	optional	Required content type for PUT operations
maxSize	`number`	optional	Maximum file size in bytes for PUT operations
responseContentType	`string`	optional	Override content-type for GET operations
responseContentDisposition	`string`	optional	Override content-disposition for GET operations

StorageAcl

Storage access control level

Allowed Values

private
public_read
public_read_write
authenticated_read
bucket_owner_read
bucket_owner_full_control

StorageClass

Storage class/tier for cost optimization

Allowed Values

standard
intelligent
infrequent_access
glacier
deep_archive

StorageConnection

Properties

Property	Type	Required	Description
accessKeyId	`string`	optional	AWS access key ID or MinIO access key
secretAccessKey	`string`	optional	AWS secret access key or MinIO secret key
sessionToken	`string`	optional	AWS session token for temporary credentials
accountName	`string`	optional	Azure storage account name
accountKey	`string`	optional	Azure storage account key
sasToken	`string`	optional	Azure SAS token
environmentId	`string`	optional	GCP project ID
credentials	`string`	optional	GCP service account credentials JSON
endpoint	`string`	optional	Custom endpoint URL
region	`string`	optional	Default region
useSSL	`boolean`	✅	Use SSL/TLS for connections
timeout	`number`	optional	Connection timeout in milliseconds

StorageProvider

Storage provider type

Allowed Values

s3
azure_blob
gcs
minio
r2
spaces
wasabi
backblaze
local

StorageScope

Storage scope classification

Allowed Values

global
tenant
user
session
temp
cache
data
logs
config
public

On this page