@alneas/eaos-server 0.0.0-stage → 0.2.0

package/dist/storage/s3-compatible.d.ts

@@ -0,0 +1,139 @@
+import { R2StorageConfig, S3StorageConfig, StorageAdapter } from '@alneas/appkit-core/storage';
+
+/**
+ * Server-held signing credentials; never expose these through browser configuration.
+ * @see createS3CompatibleStorage for host setup.
+ */
+interface StorageCredentials {
+    /** Nonempty access key identifier for the selected provider. */
+    accessKeyId: string;
+    /** Nonempty secret used for request signing. */
+    secretAccessKey: string;
+}
+type Credentials = StorageCredentials | (() => StorageCredentials | Promise<StorageCredentials>);
+type Common = {
+    /** Server-held credentials or a callback invoked once when constructing the adapter; callback errors reject creation. */
+    credentials: Credentials;
+    /** Signed URL lifetime ceiling in whole seconds, from 1 to 604800. @defaultValue 300 */
+    maxUrlLifetimeSeconds?: number;
+};
+/**
+ * Selects R2 or S3 transport settings with host-held credentials and a signed URL ceiling.
+ * @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 createS3CompatibleStorage for a complete setup example.
+ */
+type S3CompatibleStorageConfig = Common & (({
+    /**
+     * Select Cloudflare R2 transport; accountId must be 32 hexadecimal characters and bucket/credentials must be configured.
+     */
+    provider: 'r2';
+} & Omit<R2StorageConfig, 'accessKeyId' | 'secretAccessKey' | 'publicUrl' | 'defaultExpiresIn'>) | ({
+    /**
+     * Select S3-compatible transport; a nonempty region and valid bucket/credentials are required, with optional HTTPS endpoint.
+     */
+    provider: 's3';
+} & Omit<S3StorageConfig, 'accessKeyId' | 'secretAccessKey' | 'defaultExpiresIn'>));
+/**
+ * Creates an unscoped private-upload, signed-URL storage adapter for R2 or S3.
+ * @param config - Provider configuration, credentials, and URL ceiling; see {@link S3CompatibleStorageConfig}.
+ * @returns A frozen app-core adapter whose uploads reject public=true and whose URLs always use signatures within the configured ceiling.
+ * @throws Rejects invalid provider, lifetime, bucket, account/region, endpoint, or empty credentials, and propagates credential callback/import/adapter construction errors. Subsequent operations propagate transport errors.
+ * @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.
+ * @example
+ * ```typescript
+ * 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.
+ * ```
+ */
+declare function createS3CompatibleStorage(config: S3CompatibleStorageConfig): Promise<StorageAdapter>;
+/**
+ * Creates provider-backed storage isolated to a verified tenant/plugin scope.
+ * @param config - Host provider configuration and credentials.
+ * @param options - Trusted scope and live authorization; an omitted scope URL ceiling inherits config.maxUrlLifetimeSeconds, then 300.
+ * @returns A frozen scoped adapter; see {@link createTenantStorage} for relative key and operation policy.
+ * @throws Rejects provider construction failures and invalid scope settings; operations propagate authorization, policy, and transport errors.
+ * @remarks The provider ceiling also applies, so a larger scope ceiling cannot increase it. The host owns bucket provisioning and verified identity resolution.
+ * @example
+ * ```typescript
+ * 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);
+ * }
+ * ```
+ */
+declare function createTenantS3CompatibleStorage(config: S3CompatibleStorageConfig, options: TenantStorageOptions): Promise<StorageAdapter>;
+/**
+ * Reads trimmed S3 or R2 configuration from a host environment map.
+ * @param env - 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 Configuration, or null when the provider is absent/blank. This read does not fully validate values; creation validates provider settings.
+ * @throws If a selected provider lacks required nonblank values, or the provider is unsupported.
+ * @remarks Returned configuration contains secrets and belongs exclusively in trusted server code.
+ * @example
+ * ```typescript
+ * import { readS3CompatibleStorageConfig } from "@alneas/eaos-server/storage/s3-compatible";
+ * const config = readS3CompatibleStorageConfig();
+ * console.log(config ? "Storage configured" : "Storage disabled");
+ * ```
+ */
+declare function readS3CompatibleStorageConfig(env?: Record<string, string | undefined>): S3CompatibleStorageConfig | null;
+
+/**
+ * Operation names passed to the host authorization callback before scoped storage access.
+ * @see createTenantStorage for a complete usage example.
+ */
+type StorageOperation = 'upload' | 'download' | 'delete' | 'exists' | 'head' | 'list' | 'getUrl' | 'copy' | 'move';
+/**
+ * Trusted tenant/plugin scope and per-operation authorization for {@link createTenantStorage}.
+ */
+interface TenantStorageOptions {
+    /** 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. */
+    tenantId: string;
+    /** Trusted plugin ID: 1–128 ASCII letters, digits, underscores, or hyphens, starting with a letter or digit. */
+    pluginId: string;
+    /** 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: {
+        /**
+         * Trusted tenant scope captured at adapter construction, independent of caller object keys.
+         */
+        tenantId: string;
+        /**
+         * Trusted plugin scope captured at adapter construction.
+         */
+        pluginId: string;
+        /**
+         * Storage operation about to be delegated to the provider.
+         */
+        operation: StorageOperation;
+        /**
+         * Frozen relative-key array; copy/move supplies source then destination, and list supplies its requested prefix.
+         */
+        keys: readonly string[];
+    }) => boolean | Promise<boolean>;
+    /** Signed URLs remain usable until expiry; default ceiling 300 seconds. */
+    maxUrlLifetimeSeconds?: number;
+}
+/**
+ * Wraps a storage adapter with tenant/plugin key isolation and per-operation authorization.
+ * @param adapter - Host-owned transport/signing adapter; optional copy and move are exposed only when supported.
+ * @param options - Trusted scope, authorization callback, and signed URL ceiling; see {@link TenantStorageOptions}.
+ * @returns A frozen adapter using relative keys while storing under tenants/{tenantId}/plugins/{pluginId}/; returned object keys and list cursors are scope-relative.
+ * @throws 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.
+ * @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.
+ * @example
+ * ```typescript
+ * 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);
+ * }
+ * ```
+ */
+declare function createTenantStorage(adapter: StorageAdapter, options: TenantStorageOptions): StorageAdapter;
+
+export { createTenantStorage as c, createS3CompatibleStorage, createTenantS3CompatibleStorage, readS3CompatibleStorageConfig };
+export type { StorageOperation as S, S3CompatibleStorageConfig, StorageCredentials, TenantStorageOptions as T };

package/dist/storage/s3-compatible.js

@@ -0,0 +1,11 @@
+import {
+  createS3CompatibleStorage,
+  createTenantS3CompatibleStorage,
+  readS3CompatibleStorageConfig
+} from "../chunk-NNCCN7JP.js";
+export {
+  createS3CompatibleStorage,
+  createTenantS3CompatibleStorage,
+  readS3CompatibleStorageConfig
+};
+//# sourceMappingURL=s3-compatible.js.map

package/dist/storage/s3-compatible.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/tenant.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Routing hints used by {@link TenantResolver}; they do not authenticate a tenant.
+ * @see TenantResolver for a complete usage example.
+ */
+interface TenantResolverOptions {
+    /** Fallback when no explicit ID or host mapping matches. @defaultValue "default" */
+    defaultTenantId?: string;
+    /** Routing-only email domain mappings. Never use email-derived results as an authenticated tenant claim. */
+    domainTenantMap?: Record<string, string>;
+    /** Trusted, exact hostname mappings (e.g. { "demo.example.com": "tenant-demo" }). */
+    hostTenantMap?: Record<string, string>;
+}
+/**
+ * Selects a tenant routing ID from an explicit trusted ID, configured host, or fallback.
+ * @remarks This resolver performs no authentication or membership check. Host headers and explicit IDs must be validated by the host before being used for authorization. Email mappings are exposed only by resolveFromEmail.
+ * @example
+ * ```typescript
+ * import { TenantResolver } from "@alneas/eaos-server/tenant";
+ * const resolver = new TenantResolver({ hostTenantMap: { "workspace.example.com": "workspace" } });
+ * const tenantId = resolver.resolve({ host: "workspace.example.com:443" });
+ * console.log(tenantId); // "workspace"
+ * ```
+ */
+declare class TenantResolver {
+    private defaultTenantId;
+    private domainTenantMap;
+    private hostTenantMap;
+    /**
+     * Copies routing mappings, normalizing their keys to lower case.
+     * @param options - Routing mappings and fallback; omitted options use empty mappings and "default".
+     */
+    constructor(options?: TenantResolverOptions);
+    /**
+     * Looks up the lower-case domain following the first @ in an email routing hint.
+     * @param email - Email hint; missing, empty, or missing @ returns null. No address validation is performed.
+     * @returns The configured routing ID, or null when no domain matches.
+     * @example
+     * ```typescript
+     * import { TenantResolver } from "@alneas/eaos-server/tenant";
+     * const resolver = new TenantResolver({ domainTenantMap: { "example.com": "workspace" } });
+     * console.log(resolver.resolveFromEmail("person@example.com"));
+     * ```
+     */
+    resolveFromEmail(email: string | null | undefined): string | null;
+    /**
+     * Looks up a configured hostname after removing text following the first colon and lower-casing.
+     * @param host - Host routing hint, optionally including a port; missing or empty values return null. IPv6 host parsing is not provided.
+     * @returns The exact configured host mapping, or null.
+     * @example
+     * ```typescript
+     * import { TenantResolver } from "@alneas/eaos-server/tenant";
+     * const resolver = new TenantResolver({ hostTenantMap: { "workspace.example.com": "workspace" } });
+     * console.log(resolver.resolveFromHost("workspace.example.com:443"));
+     * ```
+     */
+    resolveFromHost(host: string | null | undefined): string | null;
+    /**
+     * Selects a truthy explicit ID, then a host mapping, then the configured fallback.
+     * @param input - Routing hints: explicitTenantId takes precedence over host; email is intentionally ignored. The host must establish whether an explicit ID is trusted.
+     * @returns The selected routing ID, without validating tenant existence or membership.
+     * @see TenantResolver for a complete usage example.
+     * @example
+     * ```typescript
+     * import { TenantResolver } from "@alneas/eaos-server/tenant";
+     * const resolver = new TenantResolver();
+     * console.log(resolver.resolve({ explicitTenantId: "workspace" }));
+     * ```
+     */
+    resolve(input: {
+        /**
+         * Optional host routing hint, including a possible port; checked only after a falsy/absent explicitTenantId against configured exact host mappings.
+         */
+        host?: string | null;
+        /**
+         * Optional compatibility routing hint intentionally ignored by resolve; an email domain is not an authenticated tenant claim.
+         */
+        email?: string | null;
+        /**
+         * Optional trusted tenant routing selection; any truthy value takes precedence without tenant-existence or membership validation.
+         */
+        explicitTenantId?: string | null;
+    }): string;
+    /**
+     * Reads the fallback ID captured at construction.
+     * @returns The configured fallback, or "default" when none was supplied.
+     * @example
+     * ```typescript
+     * import { TenantResolver } from "@alneas/eaos-server/tenant";
+     * console.log(new TenantResolver().getDefaultTenantId());
+     * ```
+     */
+    getDefaultTenantId(): string;
+}
+/**
+ * Creates a resolver for host-owned tenant routing hints.
+ * @param options - Routing mappings and fallback; see {@link TenantResolverOptions}.
+ * @returns A new independent resolver with copied mappings.
+ * @example
+ * ```typescript
+ * import { createTenantResolver } from "@alneas/eaos-server/tenant";
+ * const resolver = createTenantResolver({ defaultTenantId: "workspace" });
+ * console.log(resolver.resolve({}));
+ * ```
+ */
+declare function createTenantResolver(options?: TenantResolverOptions): TenantResolver;
+
+export { TenantResolver, createTenantResolver };
+export type { TenantResolverOptions };

package/dist/tenant.js

@@ -0,0 +1,9 @@
+import {
+  TenantResolver,
+  createTenantResolver
+} from "./chunk-BKAHUEIT.js";
+export {
+  TenantResolver,
+  createTenantResolver
+};
+//# sourceMappingURL=tenant.js.map

package/dist/tenant.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/workspace-context.d.ts

@@ -0,0 +1,119 @@
+/** Identity is supplied exclusively by the host's verified authentication middleware.
+ * @see createWorkspaceContextResolver for host setup and usage.
+ */
+interface WorkspaceIdentity {
+    /** User ID established by verified host authentication. */
+    userId: string;
+    /** Verified optional email; resolved contexts normalize absence to null. */
+    email?: string | null;
+    /** Trusted platform authority; tenant roles cannot grant this privilege. Defaults to false. */
+    isSuperAdmin?: boolean;
+}
+/**
+ * Host reads used by {@link createWorkspaceContextResolver}; filter inactive rows and apply schema policy in the adapter.
+ */
+interface WorkspaceContextStore {
+    /**
+     * Loads the selected active tenant.
+     * @param tenantId - Selected tenant ID from trusted routing.
+     * @returns Active tenant display data, or undefined if unavailable.
+     * @throws Persistence failures are wrapped as WorkspaceContextError with status 503.
+     
+     * @example
+     * ```typescript
+     * import type { WorkspaceContextStore } from "@alneas/eaos-server";
+     * export async function readSelectedTenant(store: WorkspaceContextStore, trustedTenantId: string) {
+     *   // Host storage filters inactive tenants and enforces its schema/access policy.
+     *   const tenant = await store.readTenant(trustedTenantId);
+     *   return tenant?.tenantName;
+     * }
+     * ```
+     */
+    readTenant(tenantId: string): Promise<{
+        /** Display name of the selected active tenant; the context resolver falls back to tenantId when this value is empty. */
+        tenantName: string;
+        /** Optional tenant industry classification; the context resolver substitutes generic when absent or empty. */
+        industryType?: string;
+    } | undefined>;
+    /**
+     * Loads the active membership for this tenant/user pair.
+     * @param tenantId - Selected active tenant ID.
+     * @param userId - Authenticated user ID.
+     * @returns Membership role, or undefined if absent; tenant roles never establish platform authority.
+     * @throws Persistence failures are wrapped as WorkspaceContextError with status 503.
+     
+     * @example
+     * ```typescript
+     * import type { WorkspaceContextStore } from "@alneas/eaos-server";
+     * export async function readVerifiedMembership(
+     *   store: WorkspaceContextStore, trustedTenantId: string, authenticatedUserId: string,
+     * ) {
+     *   const membership = await store.readMembership(trustedTenantId, authenticatedUserId);
+     *   return membership?.role; // Absence must not grant tenant access.
+     * }
+     * ```
+     */
+    readMembership(tenantId: string, userId: string): Promise<{
+        /** Role from the active tenant/user membership; the resolver trims it and normalizes blank or super_admin/superadmin values to member rather than granting platform authority. */
+        role: string;
+    } | undefined>;
+}
+/**
+ * Resolved user identity and authorized tenant context returned by {@link createWorkspaceContextResolver}.
+ */
+interface WorkspaceContext {
+    /** Authenticated user ID. */
+    userId: string;
+    /** Authorized selected tenant ID. */
+    tenantId: string;
+    /** Verified email, or null when absent. */
+    email: string | null;
+    /** Tenant display name, falling back to tenantId for an empty stored name. */
+    tenantName: string;
+    /** Tenant industry, falling back to "generic" for an empty stored value. */
+    industryType: string;
+    /** Trimmed membership role, member for unsafe/blank roles, or admin for a platform administrator without membership. */
+    role: string;
+    /** Platform administrators receive SUPER_ADMIN, super_admin, admin; other users receive USER and their normalized role. */
+    roles: string[];
+    /** True only when the verified identity explicitly has platform authority. */
+    isSuperAdmin: boolean;
+}
+/**
+ * Reports an authentication, membership, or host-store failure using an HTTP-compatible status.
+ * @see createWorkspaceContextResolver for the resolver that rejects with this error.
+ * @example
+ * ```typescript
+ * import { WorkspaceContextError } from "@alneas/eaos-server/workspace-context";
+ * const error = new WorkspaceContextError(403, "Tenant membership required");
+ * console.log(error.status); // 403
+ * ```
+ */
+declare class WorkspaceContextError extends Error {
+    readonly status: 401 | 403 | 503;
+    /**
+     * Creates an error with a stable status and caller-supplied message.
+     * @param status - 401 for missing identity, 403 for denied tenant access, or 503 for unavailable context data. This public readonly property is available for HTTP error mapping.
+     * @param message - Human-readable failure description.
+     */
+    constructor(status: 401 | 403 | 503, message: string);
+}
+/**
+ * Builds a resolver that requires an existing tenant and membership or verified platform authority.
+ * @param store - Host-owned active tenant and membership reads; see {@link WorkspaceContextStore}.
+ * @returns An async resolver accepting verified identity and a selected tenant ID, resolving a fresh context. Missing email becomes null, tenantName falls back to tenant ID, and industryType falls back to "generic".
+ * @throws The returned resolver rejects with WorkspaceContextError: 401 for empty userId, 403 for missing/unavailable tenant or denied membership, and 503 for other store failures.
+ * @remarks The host supplies verified identity, schema, active-row filtering, and credentials. Reads are sequential and not wrapped in a transaction here. Platform administrators may select existing tenants without membership; membership role strings cannot grant platform authority. Blank or super_admin/superadmin membership roles normalize to member. This function writes no persistent data.
+ * @example
+ * ```typescript
+ * import { createWorkspaceContextResolver, type WorkspaceContextStore, type WorkspaceIdentity } from "@alneas/eaos-server/workspace-context";
+ * export async function selectedWorkspace(store: WorkspaceContextStore, identity: WorkspaceIdentity, tenantId: string) {
+ *   // The host implements active-row reads and authenticates identity before this call.
+ *   return createWorkspaceContextResolver(store)(identity, tenantId);
+ * }
+ * ```
+ */
+declare function createWorkspaceContextResolver(store: WorkspaceContextStore): (identity: WorkspaceIdentity, tenantId: string | undefined) => Promise<WorkspaceContext>;
+
+export { WorkspaceContextError, createWorkspaceContextResolver };
+export type { WorkspaceContext, WorkspaceContextStore, WorkspaceIdentity };

package/dist/workspace-context.js

@@ -0,0 +1,9 @@
+import {
+  WorkspaceContextError,
+  createWorkspaceContextResolver
+} from "./chunk-WFEAKJLR.js";
+export {
+  WorkspaceContextError,
+  createWorkspaceContextResolver
+};
+//# sourceMappingURL=workspace-context.js.map

package/dist/workspace-context.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}