@araminix/platform 0.0.0-stage → 1.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amin Abbasi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,283 @@
-# Temporary Holding Version
+# @araminix/platform
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Enterprise-grade actor runtime, WebSocket endpoint platform, and multi-threaded agent execution engine.**
+
+[![npm version](https://img.shields.io/badge/version-1.2.0-blue.svg)](https://www.npmjs.com/package/@araminix/platform)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20.0.0-green.svg)](https://nodejs.org/)
+
+**Araminix Platform** (`@araminix/platform`) is a high-performance backend orchestration engine designed for complex real-time applications. Built on top of [`@araminix/lib`](../araminix-lib), it integrates an enterprise WebSocket & HTTP server, worker-thread agent execution, dynamic component/UI assembly, authentication (with 2FA and Google OAuth), and S3/MinIO cloud storage.
+
+---
+
+## 🌟 Key Features
+
+- ⚡ **Unified WebSocket & HTTP Endpoint**: Built on Express & `express-ws`, providing automatic WebSocket route dispatching, session cookies, Google OAuth, and two-factor authentication (2FA).
+- 🧵 **Multi-Threaded Agent Runtime**: Spawns isolated worker processes (`worker_threads`) with type-safe `MessageChannel` IPC, protecting the main thread from CPU-heavy tasks and crashes.
+- 🧩 **Dynamic UI Builder & Actor Engine**: Assemble complex interactive interfaces on the fly using `Panel`, `Fragment`, and `Actor` lifecycles.
+- 🗄️ **Integrated MinIO / S3 Storage**: Built-in presigned URL generation, file uploads (`multer`), MIME type mapping, and bucket management.
+- 🌐 **First-Class Internationalization**: Integrated `I18nService` with type-safe generic dictionary translations and automatic language fallbacks.
+- 🛡️ **Zero-Crash Functional Core**: Powered by `@araminix/lib`'s `Result<T, E>` monads and multiplexed streaming channels.
+
+---
+
+## 📐 Architecture
+
+```
+                                  +------------------------------------+
+                                  |            Platform                |
+                                  +-----------------+------------------+
+                                                    |
+                      +-----------------------------+-----------------------------+
+                      |                                                           |
+                      v                                                           v
+        +----------------------------+                             +----------------------------+
+        |         Endpoint           |                             |      AgentController       |
+        |  (Express WS + HTTP + 2FA) |                             |     (worker_threads)       |
+        +--------------+-------------+                             +--------------+-------------+
+                       |                                                          |
+        +--------------+-------------+                             +--------------+-------------+
+        |    MinIO S3 / Storage      |                             |   WorkerSocket / IPC Port  |
+        +----------------------------+                             +----------------------------+
+```
+
+---
+
+## 📦 Installation
+
+```bash
+# npm
+npm install @araminix/platform @araminix/lib
+
+# pnpm
+pnpm add @araminix/platform @araminix/lib
+
+# yarn
+yarn add @araminix/platform @araminix/lib
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Initializing the Platform and Endpoint
+
+```typescript
+import { AuthProvider, ClientInfo, Ok, Platform, Result } from '@araminix/platform';
+
+// 1. Define custom authentication logic
+class CustomAuthProvider extends AuthProvider {
+    async getInfo(token: string): Promise<Result<ClientInfo, unknown>> {
+        // Retrieve and return client information
+        return new Ok({
+            id: 'user-100',
+            clientType: 'User',
+            runtimeId: 'rt-100',
+        } as ClientInfo);
+    }
+
+    async auth(data: any) {
+        /* verify credentials */ return new Ok('token-xyz');
+    }
+    async googleAuth(data: any) {
+        /* Google OAuth */ return new Ok('token-xyz');
+    }
+    async destroy(token: string) {
+        /* session cleanup */
+    }
+    async refreshToken(token: string) {
+        return new Ok('new-token');
+    }
+    async request2FA(userId: string) {
+        return new Ok('otpauth://...');
+    }
+    async enable2FA(userId: string, secret: string, code: string) {
+        return new Ok(true);
+    }
+    async verify2FA(account: string, code: string, uuid: string) {
+        return new Ok(true);
+    }
+    async disable2FA(userId: string) {
+        return new Ok(true);
+    }
+    async requestUploadUrl(id: string, name: string, mime: string) {
+        return new Ok('https://...');
+    }
+    async requestDownloadUrl(id: string, name: string) {
+        return new Ok('https://...');
+    }
+    async mobileRequests(data: any) {
+        return { status: 200, result: 'OK' };
+    }
+}
+
+// 2. Configure and launch the Platform
+const platform = new Platform({
+    appIndexPath: new URL('file:///path/to/apps/index.js'),
+    agentIndexPath: new URL('file:///path/to/agents/index.js'),
+    authProvider: new CustomAuthProvider(),
+    instanceUserLimit: 10,
+    port: 3000,
+    mount: '/api',
+});
+
+// Start listening for HTTP & WebSocket connections
+await platform.start();
+console.log('Araminix Platform running on http://localhost:3000/api');
+```
+
+---
+
+### 2. Spawning Multi-Threaded Agents
+
+```typescript
+import { AgentController } from '@araminix/platform';
+
+const controller = new AgentController(new URL('file:///path/to/agentWorker.js'));
+
+// Acquire or send tasks to background worker threads
+const taskResult = await controller.task('worker-1', {
+    action: 'computeAnalytics',
+    payload: { range: '30d' },
+});
+
+if (taskResult.isOk()) {
+    console.log('Agent Response:', taskResult.unwrap());
+}
+```
+
+---
+
+### 3. Dynamic UI Building with Fragments & Panels
+
+```typescript
+import { Fragment, panel } from '@araminix/platform';
+
+class UserProfileFragment extends Fragment {
+    build() {
+        return {
+            type: 'card',
+            props: { title: 'User Information' },
+        };
+    }
+}
+
+// Assemble nested reactive panels
+const dashboard = panel({ header: 'System Overview' })
+    .panel(panel({ header: 'Metrics' }))
+    .fragment(new UserProfileFragment())
+    .build();
+```
+
+---
+
+### 4. Session Security & Cookie Configuration
+
+`Endpoint` issues signed, hardened session cookies by default:
+
+- Default Flags: `HttpOnly: true`, `Secure: true`, `SameSite: 'lax'`, `Path: '/'`, and TTL-based `Max-Age`.
+- Customizable via optional `cookieOptions` in `EndpointOptions`:
+
+```typescript
+const endpoint = new Endpoint({
+    authProvider: new CustomAuthProvider(),
+    cookieOptions: {
+        secure: process.env.NODE_ENV === 'production',
+        sameSite: 'lax',
+    },
+});
+```
+
+#### WebSocket Authentication Routes
+
+- **`/ws/:endpoint` (Recommended):**
+    - **Browsers:** Cookie-authenticated via `httpOnly` session cookie automatically attached on WebSocket upgrade.
+    - **Node Clients / Agents:** Header-authenticated by passing `x-token: <token>` in the HTTP upgrade request headers.
+- **`/ws-token/:token/:endpoint` (`@deprecated`):**
+    - Maintained for backward compatibility with legacy clients. Tokens in URL paths are automatically redacted in server access logs.
+
+#### Google OAuth Hardening (`/gauth`)
+
+`Endpoint` verifies Google access tokens against Google's `tokeninfo` endpoint prior to retrieving user profile data:
+
+- **Client ID Verification:** `EndpointOptions.googleClientIds` defines allowed OAuth client IDs. Replayed tokens issued to other Google OAuth applications are rejected with HTTP 401 (`Unauthorized`).
+- **Verified Email Enforcement:** Rejects tokens unless Google confirms `email_verified === 'true'`.
+- **Header-Only Authorization:** Access tokens are passed to `userinfo` strictly via the HTTP `Authorization: Bearer <token>` header rather than query strings.
+- **Fail-Closed Protection:** If `googleClientIds` is not configured, `/gauth` requests are refused with HTTP 503 (`Service Unavailable`).
+- **HTTP Timeouts:** All external Google API calls enforce an explicit 10-second timeout.
+
+```typescript
+const endpoint = new Endpoint({
+    authProvider: new CustomAuthProvider(),
+    googleClientIds: [
+        '1234567890-example.apps.googleusercontent.com',
+    ],
+});
+```
+
+---
+
+### 5. File Upload Security & Stored XSS Mitigation
+
+`Endpoint` and `Platform` provide hardened file upload and static download controls:
+
+- **Upload Size Limits:** Configured via `maxUploadBytes` (default: 20 MB). Oversized files are rejected with HTTP 413 (`Payload Too Large`). Only single-file uploads (`files: 1`) are permitted per request.
+- **Allowlist Filtering:** Optional `uploadAllowlist` restricts uploads to specific extensions and/or MIME types. Unauthorized uploads are rejected with HTTP 415 (`Unsupported Media Type`):
+    ```typescript
+    const platform = new Platform({
+        uploadDir: '/var/data/uploads',
+        maxUploadBytes: 10 * 1024 * 1024, // 10 MB
+        uploadAllowlist: {
+            extensions: ['png', 'jpg', 'pdf'],
+            mimetypes: ['image/png', 'image/jpeg', 'application/pdf'],
+        },
+        // ...
+    });
+    ```
+- **Filename Sanitization:** Uploaded filenames are stripped of path traversal sequences (`..`, `/`, `\`), null bytes, and non-printable control characters, with length capped at 255 characters.
+- **Stored XSS Defenses:** Static file downloads (`/file/:fileId/:safeName`) enforce defense-in-depth security headers:
+    - `X-Content-Type-Options: nosniff`
+    - `Content-Disposition: attachment` (forces browser download instead of inline execution)
+    - `Content-Security-Policy: default-src 'none'; sandbox` (strips script execution privileges and isolates origin)
+    - `dotfiles: 'deny'` and `index: false`
+
+---
+
+## 🛠️ Module Exports
+
+| Submodule            | Purpose                                                                                        |
+| -------------------- | ---------------------------------------------------------------------------------------------- |
+| `Platform`           | Primary orchestrator managing endpoints, apps, and user session lifecycles.                    |
+| `Endpoint`           | Express + `express-ws` HTTP/WebSocket server handling auth, sessions, 2FA, and upload streams. |
+| `AgentController`    | Spawns and supervises isolated worker threads with `MessageChannel` IPC.                       |
+| `Panel` / `Fragment` | Fluent builder API for dynamic UI layout structures.                                           |
+| `MinioService`       | Object storage client for S3/MinIO presigned URLs and file lifecycle operations.               |
+| `I18nService`        | Type-safe multi-language translation and fallback engine.                                      |
+
+---
+
+## 🧪 Testing
+
+```bash
+# Run unit tests
+npm test
+
+# Run tests with built-in code coverage report
+npm run test:coverage
+```
+
+---
+
+## 👤 Author
+
+**Amin Abbasi**
+
+- Organization: [araminix](https://github.com/araminix)
+- GitHub: [@abbasi](https://github.com)
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import Fragment from './src/builder/Fragment.js';
+import panel from './src/builder/Panel.js';
+import Platform, { UserInstance } from './src/Platform.js';
+import { ConnectRequest } from './src/server/ConnectRequest.js';
+import Endpoint from './src/server/Endpoint.js';
+export * from '@araminix/lib';
+export * from './src/server/index.js';
+export * from './src/utils/index.js';
+export * from './src/lib/d.js';
+export * from './src/lib/actors.js';
+export * from './src/lib/worker_socket.js';
+export * from './src/agent/d.js';
+export * from './src/executor/index.js';
+export { Platform, Endpoint, ConnectRequest, Fragment, panel, UserInstance };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,2BAA2B,CAAC;AACjD,OAAO,KAAK,MAAM,wBAAwB,CAAC;AAC3C,OAAO,QAAQ,EAAE,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,QAAQ,MAAM,0BAA0B,CAAC;AAEhD,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AAExC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+import Fragment from './src/builder/Fragment.js';
+import panel from './src/builder/Panel.js';
+import Platform from './src/Platform.js';
+import { ConnectRequest } from './src/server/ConnectRequest.js';
+import Endpoint from './src/server/Endpoint.js';
+export * from '@araminix/lib';
+export * from './src/server/index.js';
+export * from './src/utils/index.js';
+export * from './src/lib/d.js';
+export * from './src/lib/actors.js';
+export * from './src/lib/worker_socket.js';
+export * from './src/agent/d.js';
+export * from './src/executor/index.js';
+export { Platform, Endpoint, ConnectRequest, Fragment, panel };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,2BAA2B,CAAC;AACjD,OAAO,KAAK,MAAM,wBAAwB,CAAC;AAC3C,OAAO,QAA0B,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,QAAQ,MAAM,0BAA0B,CAAC;AAEhD,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AAExC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,QAAQ,EAAE,KAAK,EAAgB,CAAC"}

package/dist/src/Platform.d.ts

@@ -0,0 +1,59 @@
+import { Result, Socket, Stream } from '@araminix/lib';
+import { ResourceLimits } from 'worker_threads';
+import Instance from './executor/Instance.js';
+import { AppListing } from './lib/d.js';
+import { AuthProvider, ClientInfo } from './server/AuthProvider.js';
+import Endpoint, { MinioOptions, RateLimitConfig, UploadAllowlist } from './server/Endpoint.js';
+export interface PlatformConfig {
+    appIndexPath: URL;
+    agentIndexPath: URL;
+    authProvider: AuthProvider;
+    instanceUserLimit: number;
+    maxInstances?: number;
+    resourceLimits?: ResourceLimits;
+    port?: number;
+    mount?: string;
+    cookieSecret?: string;
+    tabLimit?: number;
+    uploadDir?: string;
+    maxUploadBytes?: number;
+    uploadAllowlist?: UploadAllowlist;
+    googleClientIds?: string[];
+    allowedOrigins?: string[];
+    authRateLimit?: RateLimitConfig | boolean;
+    minio?: MinioOptions;
+    onCustomStream?: {
+        [key: string]: (client: ClientInfo, stream: Stream) => Promise<void>;
+    };
+}
+export type UserInstance = {
+    id: string;
+    appName: string;
+    appTitle: string;
+    activityTitle?: string;
+    profile: string | null;
+    touched: number;
+};
+export default class Platform {
+    private readonly config;
+    readonly endpoint: Endpoint;
+    private appIndex;
+    private agentController;
+    readonly instances: Map<string, Map<string, Instance>>;
+    get totalInstances(): number;
+    constructor(config: PlatformConfig);
+    private serve;
+    private processInstanceCloseStream;
+    processCustomStreams(clientInfo: ClientInfo, endpointSocket: Socket): void;
+    private sanitizeClientInfo;
+    processUserInfo(clientInfo: ClientInfo, endpointSocket: Socket): void;
+    listUserInstances(runtimeId: string): Promise<Array<UserInstance>>;
+    listUserApps(userId: string): Promise<Result<Array<AppListing>, void>>;
+    private processInstanceListStream;
+    private processInstanceStream;
+    private processAppsListStream;
+    private serveInstance;
+    start(): Promise<void>;
+    stop(): void;
+}
+//# sourceMappingURL=Platform.d.ts.map

package/dist/src/Platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Platform.d.ts","sourceRoot":"","sources":["../../src/Platform.ts"],"names":[],"mappings":"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"}