@alneas/eaos-server API

@alneas/eaos-server API

Public entrypoints

Import	Contract
@alneas/eaos-server/storage	Typed public export
@alneas/eaos-server/storage/s3-compatible	Typed public export

[FUNCTION] createS3CompatibleStorage

Creates an unscoped private-upload, signed-URL storage adapter for R2 or S3.

Imports: @alneas/eaos-server/storage, @alneas/eaos-server/storage/s3-compatible.

Signature

declare function createS3CompatibleStorage(config: S3CompatibleStorageConfig): Promise<StorageAdapter>;

Parameters

Name	Type	Required	Description
config	S3CompatibleStorageConfig	Yes	Provider configuration, credentials, and URL ceiling; see {@link S3CompatibleStorageConfig}.

Returns

Promise<StorageAdapter>

A frozen app-core adapter whose uploads reject public=true and whose URLs always use signatures within the configured ceiling.

Remarks

Server-only: transport/signing stay in app-core and the host supplies secrets. Credentials are resolved once at construction. Signed access also works during a public-bucket migration but cannot close existing public URLs. Keep this unscoped adapter host-owned; give plugins createTenantS3CompatibleStorage. Constructing an adapter does not verify remote credentials or create a bucket.

Errors and rejections

Rejects invalid provider, lifetime, bucket, account/region, endpoint, or empty credentials, and propagates credential callback/import/adapter construction errors. Subsequent operations propagate transport errors.

Example

import { createS3CompatibleStorage, readS3CompatibleStorageConfig } from "@alneas/eaos-server/storage/s3-compatible";
// The host provisions a private bucket and supplies the documented storage environment.
const config = readS3CompatibleStorageConfig();
if (!config) throw new Error("Storage is not configured");
const storage = await createS3CompatibleStorage(config);
// Retain storage in trusted server code; authorize requests before performing operations.

[FUNCTION] createTenantS3CompatibleStorage

Creates provider-backed storage isolated to a verified tenant/plugin scope.

Imports: @alneas/eaos-server/storage, @alneas/eaos-server/storage/s3-compatible.

Signature

declare function createTenantS3CompatibleStorage(config: S3CompatibleStorageConfig, options: TenantStorageOptions): Promise<StorageAdapter>;

Parameters

Name	Type	Required	Description
config	S3CompatibleStorageConfig	Yes	Host provider configuration and credentials.
options	TenantStorageOptions	Yes	Trusted scope and live authorization; an omitted scope URL ceiling inherits config.maxUrlLifetimeSeconds, then 300.

Returns

Promise<StorageAdapter>

A frozen scoped adapter; see {@link createTenantStorage} for relative key and operation policy.

Remarks

The provider ceiling also applies, so a larger scope ceiling cannot increase it. The host owns bucket provisioning and verified identity resolution.

Errors and rejections

Rejects provider construction failures and invalid scope settings; operations propagate authorization, policy, and transport errors.

Example

import { createTenantS3CompatibleStorage, type S3CompatibleStorageConfig } from "@alneas/eaos-server/storage/s3-compatible";
import type { TenantStorageOptions } from "@alneas/eaos-server/storage";
export async function scopedStorage(config: S3CompatibleStorageConfig, trustedOptions: TenantStorageOptions) {
  return createTenantS3CompatibleStorage(config, trustedOptions);
}

[FUNCTION] createTenantStorage

Wraps a storage adapter with tenant/plugin key isolation and per-operation authorization.

Imports: @alneas/eaos-server/storage.

Signature

declare function createTenantStorage(adapter: StorageAdapter, options: TenantStorageOptions): StorageAdapter;

Parameters

Name	Type	Required	Description
adapter	StorageAdapter	Yes	Host-owned transport/signing adapter; optional copy and move are exposed only when supported.
options	TenantStorageOptions	Yes	Trusted scope, authorization callback, and signed URL ceiling; see {@link TenantStorageOptions}.

Returns

StorageAdapter

A frozen adapter using relative keys while storing under tenants/{tenantId}/plugins/{pluginId}/; returned object keys and list cursors are scope-relative.

Remarks

Keys cannot be absolute or contain traversal, empty segments, backslashes, percent escapes, control characters, query strings, or fragments. List permits an empty prefix and slash delimiter only. URLs default to a 300-second ceiling and remain usable until expiry after authorization changes. This wrapper supplies no persistence, locking, revocation, or transaction mechanism beyond the underlying adapter. The host must retain ownership of the unscoped adapter.

Errors and rejections

Throws synchronously for invalid scope IDs or URL lifetime. Operations reject for invalid relative keys, denied access, public uploads, unsigned or overlong URLs, invalid cursors/delimiters, out-of-scope provider results, or propagated adapter/authorization errors.

Example

import { createTenantStorage, type StorageAdapter, type TenantStorageOptions } from "@alneas/eaos-server/storage";
export function pluginStorage(adapter: StorageAdapter, trustedOptions: TenantStorageOptions) {
  // Resolve scope and authorization from verified host identity, never request body IDs.
  return createTenantStorage(adapter, trustedOptions);
}

[FUNCTION] readS3CompatibleStorageConfig

Reads trimmed S3 or R2 configuration from a host environment map.

Imports: @alneas/eaos-server/storage, @alneas/eaos-server/storage/s3-compatible.

Signature

declare function readS3CompatibleStorageConfig(env?: Record<string, string | undefined>): S3CompatibleStorageConfig | null;

Parameters

Name	Type	Required	Description
env	Record<string, string | undefined>	No	Environment values; defaults to process.env. EAOS_STORAGE_PROVIDER selects s3/r2 case-insensitively. R2 uses R2_ACCOUNT_ID, R2_BUCKET, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, and optional R2_ENDPOINT. S3 uses S3_BUCKET, S3_REGION, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, optional S3_ENDPOINT, and S3_FORCE_PATH_STYLE (true or 1). EAOS_STORAGE_MAX_URL_SECONDS is converted with Number.

Returns

S3CompatibleStorageConfig \| null

Configuration, or null when the provider is absent/blank. This read does not fully validate values; creation validates provider settings.

Remarks

Returned configuration contains secrets and belongs exclusively in trusted server code.

Errors and rejections

If a selected provider lacks required nonblank values, or the provider is unsupported.

Example

import { readS3CompatibleStorageConfig } from "@alneas/eaos-server/storage/s3-compatible";
const config = readS3CompatibleStorageConfig();
console.log(config ? "Storage configured" : "Storage disabled");

[TYPE] S3CompatibleStorageConfig

Selects R2 or S3 transport settings with host-held credentials and a signed URL ceiling.

Imports: @alneas/eaos-server/storage, @alneas/eaos-server/storage/s3-compatible.

Signature

type S3CompatibleStorageConfig = Common & (({
    provider: 'r2';
} & Omit<R2StorageConfig, 'accessKeyId' | 'secretAccessKey' | 'publicUrl' | 'defaultExpiresIn'>) | ({
    provider: 's3';
} & Omit<S3StorageConfig, 'accessKeyId' | 'secretAccessKey' | 'defaultExpiresIn'>));

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Remarks

R2 requires a 32-hex-character accountId; S3 requires region. Both require a valid bucket name. Optional endpoints must be HTTPS URLs without credentials, query, or fragment. Provider-specific fields follow app-core storage configuration; public URLs are not configured by this factory.

See also

createS3CompatibleStorage for a complete setup example.

Public members

provider

Select Cloudflare R2 transport; accountId must be 32 hexadecimal characters and bucket/credentials must be configured.

provider

Select S3-compatible transport; a nonempty region and valid bucket/credentials are required, with optional HTTPS endpoint.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] StorageAdapter

Compatibility re-export; its implementation and documentation are owned by the owning package @dataarthub/app-core.

Imports: @alneas/eaos-server/storage.

Signature

export interface StorageAdapter {
    upload(key: string, data: Buffer | Blob | ReadableStream | string, options?: StorageUploadOptions): Promise<StorageObject>;
    download(key: string): Promise<Buffer | null>;
    getUrl(key: string, options?: StorageURLOptions): Promise<string>;
    delete(key: string): Promise<boolean>;
    exists(key: string): Promise<boolean>;
    head(key: string): Promise<StorageObject | null>;
    list(options?: StorageListOptions): Promise<StorageListResult>;
    copy?(sourceKey: string, destinationKey: string): Promise<StorageObject>;
    move?(sourceKey: string, destinationKey: string): Promise<StorageObject>;
}

Parameters

Name	Type	Required	Description
upload	Promise<StorageObject>	Yes	See the upstream owning declaration.
download	Promise<Buffer | null>	Yes	See the upstream owning declaration.
getUrl	Promise<string>	Yes	See the upstream owning declaration.
delete	Promise<boolean>	Yes	See the upstream owning declaration.
exists	Promise<boolean>	Yes	See the upstream owning declaration.
head	Promise<StorageObject | null>	Yes	See the upstream owning declaration.
list	Promise<StorageListResult>	Yes	See the upstream owning declaration.
copy	Promise<StorageObject>	No	See the upstream owning declaration.
move	Promise<StorageObject>	No	See the upstream owning declaration.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] StorageCredentials

Server-held signing credentials; never expose these through browser configuration.

Imports: @alneas/eaos-server/storage, @alneas/eaos-server/storage/s3-compatible.

Signature

interface StorageCredentials {
    accessKeyId: string;
    secretAccessKey: string;
}

Parameters

Name	Type	Required	Description
accessKeyId	string	Yes	Nonempty access key identifier for the selected provider.
secretAccessKey	string	Yes	Nonempty secret used for request signing.

Returns

Type declaration; no runtime value.

See also

createS3CompatibleStorage for host setup.

Public members

accessKeyId

Nonempty access key identifier for the selected provider.

secretAccessKey

Nonempty secret used for request signing.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] StorageOperation

Operation names passed to the host authorization callback before scoped storage access.

Imports: @alneas/eaos-server/storage.

Signature

type StorageOperation = 'upload' | 'download' | 'delete' | 'exists' | 'head' | 'list' | 'getUrl' | 'copy' | 'move';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

See also

createTenantStorage for a complete usage example.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] TenantStorageOptions

Trusted tenant/plugin scope and per-operation authorization for createTenantStorage.

Imports: @alneas/eaos-server/storage.

Signature

interface TenantStorageOptions {
    tenantId: string;
    pluginId: string;
    authorize: (request: {
        tenantId: string;
        pluginId: string;
        operation: StorageOperation;
        keys: readonly string[];
    }) => boolean | Promise<boolean>;
    maxUrlLifetimeSeconds?: number;
}

Parameters

Name	Type	Required	Description
tenantId	string	Yes	Trusted tenant ID: 1–128 ASCII letters, digits, underscores, or hyphens, starting alphanumeric. It must come from verified server identity/configuration, never request body keys.
pluginId	string	Yes	Trusted plugin ID: 1–128 ASCII letters, digits, underscores, or hyphens, starting with a letter or digit.
authorize	(request: { tenantId: string; pluginId: string; operation: StorageOperation; keys: readonly string[]; }) => boolean | Promise<boolean>	Yes	Invoked before each operation with trusted scope, operation, and frozen relative keys (list receives its prefix); only exactly true allows access. Errors propagate.
maxUrlLifetimeSeconds	number	No	Signed URLs remain usable until expiry; default ceiling 300 seconds.

Returns

Type declaration; no runtime value.

Public members

tenantId

Trusted tenant ID: 1–128 ASCII letters, digits, underscores, or hyphens, starting alphanumeric. It must come from verified server identity/configuration, never request body keys.

pluginId

Trusted plugin ID: 1–128 ASCII letters, digits, underscores, or hyphens, starting with a letter or digit.

authorize

Invoked before each operation with trusted scope, operation, and frozen relative keys (list receives its prefix); only exactly true allows access. Errors propagate.

authorize.request.tenantId

Trusted tenant scope captured at adapter construction, independent of caller object keys.

authorize.request.pluginId

Trusted plugin scope captured at adapter construction.

authorize.request.operation

Storage operation about to be delegated to the provider.

authorize.request.keys

Frozen relative-key array; copy/move supplies source then destination, and list supplies its requested prefix.

maxUrlLifetimeSeconds

Signed URLs remain usable until expiry; default ceiling 300 seconds.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.