Skip to content

Commit 8ab7331

Browse files
frankpaganfrankpagan
committed
docs: update README to enhance clarity and detail on CoCreate Socket Server features and usage
1 parent 6a6c3e5 commit 8ab7331

3 files changed

Lines changed: 165 additions & 75 deletions

File tree

‎README.md‎

Lines changed: 127 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,91 +1,166 @@
1-
# CoCreate-api
1+
# @cocreate/api
22

3-
A simple api helper component in vanilla javascript used by JavaScript developers to create thirdparty api intergrations. CoCreate-api includes the client component and server side for api processing. Thirdparty apis can be accessible using HTML5 attributes and/or JavaScript API. Take it for a spin in our [playground!](https://cocreate.app/docs/api)
3+
A dynamic, multi-tenant API execution gateway, proxy engine, and webhook orchestration routing layer. It securely manages distributed integration architectures, allowing applications to configure, evaluate, and execute complex third-party API configurations and multi-step macro workflows on the fly. By coupling an Abstract Syntax Tree (AST) evaluation sandbox (`NativeSandbox`) with strict tenant environmental isolation, it transforms declarative configurations into low-latency outbound integrations and secure inbound webhooks without introducing cross-tenant data leaks.
44

5-
![minified](https://img.badgesize.io/https://cdn.cocreate.app/api/latest/CoCreate-api.min.js?style=flat-square&label=minified&color=orange)
6-
![gzip](https://img.badgesize.io/https://cdn.cocreate.app/api/latest/CoCreate-api.min.js?compression=gzip&style=flat-square&label=gzip&color=yellow)
7-
![brotli](https://img.badgesize.io/https://cdn.cocreate.app/api/latest/CoCreate-api.min.js?compression=brotli&style=flat-square&label=brotli)
8-
![GitHub latest release](https://img.shields.io/github/v/release/CoCreate-app/CoCreate-api?style=flat-square)
9-
![License](https://img.shields.io/github/license/CoCreate-app/CoCreate-api?style=flat-square)
10-
![Hiring](https://img.shields.io/static/v1?style=flat-square&label=&message=Hiring&color=blueviolet)
5+
---
116

12-
![CoCreate-api](https://cdn.cocreate.app/docs/CoCreate-api.gif)
7+
## Table of Contents
138

14-
## [Docs & Demo](https://cocreate.app/docs/api)
9+
* [Features](https://www.google.com/search?q=%23features)
10+
* [Dynamic Operations Sandbox](https://www.google.com/search?q=%23dynamic-operations-sandbox)
11+
* [Installation](https://www.google.com/search?q=%23installation)
12+
* [Usage](https://www.google.com/search?q=%23usage)
13+
* [How it Works](https://www.google.com/search?q=%23how-it-works)
14+
* [Architecture and Payload Specs](https://www.google.com/search?q=%23architecture-and-payload-specs)
15+
* [Security Implementations](https://www.google.com/search?q=%23security-implementations)
16+
* [How to Contribute](https://www.google.com/search?q=%23how-to-contribute)
17+
* [License](https://www.google.com/search?q=%23license)
1518

16-
For a complete guide and working demo refer to the [doumentation](https://cocreate.app/docs/api)
19+
---
1720

18-
## CDN
21+
## Features
1922

20-
```html
21-
<script src="https://cdn.cocreate.app/api/latest/CoCreate-api.min.js"></script>
22-
```
23+
* **Abstract Syntax Tree (AST) Micro-Operators:** Evaluates functional configuration contexts inline, supporting expressive syntax tags (like `$data`, `$event`, `$actions`, and `$request`) along with custom business logic operators.
24+
* **Tenant Environmental Isolation Firewall:** Guarantees cryptographic data partitioning by intercepting execution matrices and forcefully injecting bound `organization_id` and verified `host` values into core operations.
25+
* **Real-Time WebSocket Integration Matrix:** Seamlessly hooks into live server networks (`wsManager`), listening for incoming `api` and `endpoint` actions and streaming real-time operational state payloads directly back to the client.
26+
* **Dual Outbound Execution Vectors:** Wire-speeds native, pre-constructed HTTP payloads instantly, or dynamically builds custom multi-step outbound integrations by resolving runtime metadata against persistence layers.
27+
* **Cryptographic Signatures & JWT Orchestration:** Features native, low-latency hooks to generate JSON Web Tokens (`$jwt`) using HMAC-SHA256, alongside timing-attack-safe webhook signature verification (`verifySignature`).
28+
* **Sealed AST Runtime Sandbox:** Features a hardened utility matrix containing sandboxed global objects (`JSON`, `Array`, `Math`) and helper methods (like Base64 encoding/decoding and URL encoders), safely wrapping calculations outside the global scope.
29+
* **Native Edge Stream Inspection:** Inspects active server response buffers automatically, failing back to a clean 200 OK only if macro pipelines didn't forcefully complete or close the stream.
30+
31+
---
32+
33+
## Dynamic Operations Sandbox
34+
35+
The engine evaluates standard properties and custom functional variables using a predefined sandbox layer. This allows configuration profiles to extract fields safely on the fly:
36+
37+
| Core Operator Scope | Extracted Source Value |
38+
| --- | --- |
39+
| **`$data`** | Extracts standard key parameters from the active input execution payload (`data`). |
40+
| **`$event`** | Parses raw, incoming JSON parameters transmitted via active webhook streams. |
41+
| **`$actions`** | Exposes an array of historical execution artifacts from previous macro pipeline links. |
42+
| **`$request` / `$header**` | Exposes underlying HTTP request properties, methods, and incoming network parameters. |
43+
| **`$jwt`** | Triggers an active cryptographic signing loop, building a secure JWT token from properties. |
44+
45+
---
46+
47+
## Installation
48+
49+
```bash
50+
npm install @cocreate/api
2351

24-
```html
25-
<script src="https://cdn.cocreate.app/api/latest/CoCreate-api.min.css"></script>
2652
```
2753

28-
## NPM
54+
---
55+
56+
## Usage
57+
58+
### Module Initialization
59+
60+
Bind the API framework directly during the bootstrapping phase of your core `CoCreateServer` application matrix:
61+
62+
```javascript
63+
import apiGateway from '@cocreate/api';
64+
import { CoCreateServer } from '@cocreate/server';
65+
66+
// Boot the primary application server instance
67+
const serverContext = await CoCreateServer.start();
68+
69+
// Initialize the API engine and register WebSocket listeners
70+
await apiGateway.init(serverContext);
2971

30-
```shell
31-
$ npm i @cocreate/api
3272
```
3373

34-
## yarn
74+
### Direct Programmatic API Execution
75+
76+
Execute complex third-party outbound macro operations using unified integration objects:
77+
78+
```javascript
79+
import apiGateway from '@cocreate/api';
80+
81+
// The method identifies the provider credentials, and the endpoint resolves the data model
82+
const payload = {
83+
organization_id: "64b9a32e18f21bc56789abcd",
84+
method: "stripe",
85+
endpoint: "POST /v1/customers",
86+
stripe: {
87+
email: "$data.userEmail",
88+
metadata: {
89+
workspace: "production"
90+
}
91+
},
92+
userEmail: "developer@cocreate.app"
93+
};
94+
95+
const result = await apiGateway.executeApi(payload);
3596

36-
```shell
37-
$ yarn install @cocreate/api
3897
```
3998

40-
# Table of Contents
99+
---
41100

42-
- [Table of Contents](#table-of-contents)
43-
- [Announcements](#announcements)
44-
- [Roadmap](#roadmap)
45-
- [How to Contribute](#how-to-contribute)
46-
- [About](#about)
47-
- [License](#license)
101+
## How it Works
48102

49-
<a name="announcements"></a>
103+
1. **Bootstrap & Event Binding:** During `init()`, the module hooks directly into the server's WebSocket framework (`wsManager`), capturing incoming `api` and `endpoint` event signals to route them to the execution handler.
104+
2. **Context and Firewall Initialization:** For every outbound execution, the engine evaluates the parameters against a parent context firewall. Security profiles match inbound connections against verified socket bounds, locking `organization_id` and `host` configurations.
105+
3. **Macro Configuration Resolving:** The engine sends queries through the CRUD synchronization layer to match configuration files against stored endpoints or active integration details inside the database collection.
106+
4. **AST Matrix Processing:** The router recursively scans headers, parameters, and bodies via `processOperators()`. Found strings matching active variables (e.g., `$` prefixes) are securely compiled in the isolated `NativeSandbox` environment.
107+
5. **Outbound Network Fetching:** The system builds the options profile, forcefully sets content headers, maps an `AbortController` timeout circuit breaker (15-second cutoff), and runs the task using the system runtime's native `fetch` framework.
108+
6. **Payload Delivery & Webhook Dispatching:** Webhook targets matching inbound edge rules check security values, run validation rules using timing-safe comparisons, execute steps sequentially, and output structural streams.
50109

51-
# Announcements
110+
---
52111

53-
All updates to this library are documented in our [CHANGELOG](https://github.com/CoCreate-app/CoCreate-api/blob/master/CHANGELOG.md) and [releases](https://github.com/CoCreate-app/CoCreate-api/releases). You may also subscribe to email for releases and breaking changes.
112+
## Architecture and Payload Specs
54113

55-
<a name="roadmap"></a>
114+
### Unified Payload Object Schema
56115

57-
# Roadmap
116+
The data engine relies heavily on structural, flat parameter objects passed down into the execution chain:
58117

59-
If you are interested in the future direction of this project, please take a look at our open [issues](https://github.com/CoCreate-app/CoCreate-api/issues) and [pull requests](https://github.com/CoCreate-app/CoCreate-api/pulls). We would love to hear your feedback.
118+
| Field Element | Type | Role |
119+
| --- | --- | --- |
120+
| `organization_id` | `String` | **Required.** Targets the root tenant profile partition mapping to execution databases. |
121+
| `method` | `String` | **Required.** The provider identity string (e.g., `"stripe"`) used to fetch integration credentials. |
122+
| `endpoint` | `String` | **Required.** The operational HTTP verb and route mapping (e.g., `"POST /v1/customers"`) used to match configurations in the endpoints database. |
123+
| `[providerName]` | `Object` | The input context object named after your provider (e.g., `stripe: { ... }`) holding parameters processed by the AST engine. |
60124

61-
<a name="about"></a>
125+
### Context Engine Parameter Schema
62126

63-
# About
127+
The API processing network builds a dedicated execution block on every mutation cycle:
64128

65-
CoCreate-api is guided and supported by the CoCreate Developer Experience Team.
129+
| Field Element | Type | Role |
130+
| --- | --- | --- |
131+
| `data` | `Object` | Input variable parameters sent down from the parent action payload. |
132+
| `event` | `Object` | The compiled incoming request body extracted from active webhook pipelines. |
133+
| `actions` | `Array` | A running chronological memory matrix containing results of completed steps. |
134+
| `organization_id` | `String` | **Required.** Lockout identifier tracking root workspace context. |
135+
| `host` | `String` | The edge routing host domain verifying tenant environment isolation boundaries. |
136+
| `crud` / `wsManager` | `Object` | Bound links to internal database adapters and WebSocket server channels. |
66137

67-
Please Email the Developer Experience Team [here](mailto:develop@cocreate.app) in case of any queries.
138+
---
68139

69-
CoCreate-api is maintained and funded by CoCreate. The names and logos for CoCreate are trademarks of CoCreate, LLC.
140+
## Security Implementations
70141

71-
<a name="contribute"></a>
142+
> [!WARNING]
143+
> To prevent config-driven cross-tenant data leaks or privilege escalations, parent context variables and authenticated socket bounds take absolute priority over raw incoming payload attributes.
72144
73-
# How to Contribute
145+
### Context Sandboxing
74146

75-
We encourage contribution to our libraries (you might even score some nifty swag), please see our [CONTRIBUTING](https://github.com/CoCreate-app/CoCreate-api/blob/master/CONTRIBUTING.md) guide for details.
147+
Local interface methods (such as direct actions on `crud` or `wsManager`) intercept arguments inside the execution layer. Even if a configuration profile passes a malicious tenant parameter inside an AST macro string, the sandbox engine explicitly overwrites the parameters on execution to align with the sealed context of the authenticated user.
76148

77-
We want this library to be community-driven, and CoCreate led. We need your help to realize this goal. To help make sure we are building the right things in the right order, we ask that you create [issues](https://github.com/CoCreate-app/CoCreate-api/issues) and [pull requests](https://github.com/CoCreate-app/CoCreate-api/pulls) or merely upvote or comment on existing issues or pull requests.
149+
### Timing-Safe Signature Verification
78150

79-
We appreciate your continued support, thank you!
151+
Inbound webhook channels configured with `authenticate` properties execute validation algorithms using a cryptographically secure fixed-time comparison script (`crypto.timingSafeEqual`). This completely mitigates timing-attack vectors targeting system endpoints.
80152

81-
<a name="license"></a>
153+
---
82154

83-
# License
155+
## How to Contribute
84156

85-
This software is dual-licensed under the GNU Affero General Public License version 3 (AGPLv3) and a commercial license.
157+
We encourage contribution to our libraries (you might even score some nifty swag), please see our [CONTRIBUTING.md](https://cocreatejs.com/docs/api/contributing) guide for details. We want this library to be community-driven, and CoCreate led. We need your help to realize this goal.
86158

87-
- **Open Source Use**: For open-source projects and non-commercial use, this software is available under the AGPLv3. The AGPLv3 allows you to freely use, modify, and distribute this software, provided that all modifications and derivative works are also licensed under the AGPLv3. For the full license text, see the [LICENSE file](https://github.com/CoCreate-app/CoCreate-api/blob/master/LICENSE).
159+
---
88160

89-
- **Commercial Use**: For-profit companies and individuals intending to use this software for commercial purposes must obtain a commercial license. The commercial license is available when you sign up for an API key on our [website](https://cocreate.app). This license permits proprietary use and modification of the software without the copyleft requirements of the AGPLv3. It is ideal for integrating this software into proprietary commercial products and applications.
161+
## License
162+
163+
This software is dual-licensed under the GNU Affero General Public License version 3 (AGPLv3) and a commercial license.
90164

91-
If you have not purchased a commercial license and intend to use this software for commercial purposes, you are required to sign up for an API key on our website.
165+
* **Open Source Use:** For open-source projects and non-commercial use, this software is available under the AGPLv3. For the full license text, see the LICENSE file.
166+
* **Commercial Use:** For-profit companies and individuals intending to use this software for commercial purposes must obtain a commercial license. The commercial license is available when you sign up for an API key on our website.

‎package.json‎

Lines changed: 14 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,21 @@
11
{
22
"name": "@cocreate/api",
33
"version": "1.23.2",
4-
"description": "A simple api helper component in vanilla javascript used by JavaScript developers to create thirdparty api intergrations. CoCreate-api includes the client component and server side for api processing. Thirdparty apis can be accessible using HTML5 attributes and/or JavaScript API. ",
4+
"description": "A secure, multi-tenant API execution gateway and proxy layer that dynamically resolves endpoint actions, processes AST micro-operators, handles webhooks, and manages third-party integrations with strict tenant environment isolation.",
55
"keywords": [
6-
"thirdparty-api-intergration",
7-
"thirdparty-api-tool",
8-
"cocreate-api",
9-
"cocreate",
10-
"no-code-framework",
11-
"cocreatejs",
12-
"cocreatejs-component",
13-
"cocreate-framework",
14-
"no-code",
15-
"low-code",
16-
"realtime",
17-
"realtime-framework",
18-
"collaboration",
19-
"shared-editing",
20-
"html5-framework",
21-
"javascript-framework"
6+
"api-orchestration",
7+
"webhook-orchestration",
8+
"macro-execution",
9+
"api-gateway",
10+
"api-proxy",
11+
"multi-tenant",
12+
"ast-interpreter",
13+
"sandbox",
14+
"jwt-generator",
15+
"signature-verification",
16+
"websocket",
17+
"serverless-runtime",
18+
"tenant-isolation"
2219
],
2320
"publishConfig": {
2421
"access": "public"

‎src/server.js‎

Lines changed: 24 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -570,18 +570,36 @@ export function generateJWT(config, secret) {
570570
}
571571
}
572572

573+
/**
574+
* Robustly verifies HMAC signatures natively.
575+
* FIXES CRITICAL TIMINGSAFEEQUAL ERROR: Enforces equal buffer lengths to prevent process crashes.
576+
*/
573577
export function verifySignature(payload, signature, secret, algorithm = 'sha256') {
574578
try {
579+
if (!payload || !signature || !secret) return false;
580+
575581
const hmac = crypto.createHmac(algorithm, secret);
576582
hmac.update(payload);
577-
const expectedSignature = hmac.digest('hex');
578583

579-
return crypto.timingSafeEqual(
580-
Buffer.from(expectedSignature),
581-
Buffer.from(signature)
582-
);
584+
// 1. Uniformly resolve inputs to identical encoding formats (e.g., Hex vs Base64 vs Raw buffers)
585+
const expectedSignature = hmac.digest();
586+
let receivedSignature = Buffer.isBuffer(signature) ? signature : Buffer.from(signature, 'hex');
587+
588+
// Fallback: Stripe/Providers can output base64 signatures; handle gracefully
589+
if (receivedSignature.length !== expectedSignature.length) {
590+
receivedSignature = Buffer.from(signature, 'base64');
591+
}
592+
593+
// 2. CRITICAL SECURITY GUARD: Enforce equal length check before passing to timingSafeEqual.
594+
// Node's timingSafeEqual WILL throw an unhandled TypeError (crashing the worker) if byte sizes mismatch.
595+
if (receivedSignature.length !== expectedSignature.length) {
596+
console.warn('[@cocreate/api] Signature verification rejected immediately due to byte-length mismatch.');
597+
return false;
598+
}
599+
600+
return crypto.timingSafeEqual(expectedSignature, receivedSignature);
583601
} catch (err) {
584-
console.error('[@cocreate/api] Failed signature verification:', err);
602+
console.error('[@cocreate/api] Failed signature verification:', err.message);
585603
return false;
586604
}
587605
}

0 commit comments

Comments
 (0)