Skip to content

Commit 13f9161

Browse files
matas-bitbybit-devmatas-bitbybit-dev
committed
new docs for security policy and hosting of assets on users cdn
1 parent adfeb3d commit 13f9161

3 files changed

Lines changed: 270 additions & 1 deletion

File tree

‎docs/learn/hosting-and-cdn.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
---
2+
sidebar_position: 10
3+
title: Hosting Bitbybit Assets on Your Own CDN
4+
sidebar_label: Self-Hosting Assets
5+
description: Learn how to host Bitbybit assets on your own CDN infrastructure for improved reliability, performance, and control.
6+
tags: [cdn, hosting, infrastructure, deployment, performance, assets]
7+
---
8+
9+
import Admonition from '@theme/Admonition';
10+
11+
# Hosting Bitbybit Assets on Your Own CDN
12+
13+
To simplify the setup process for new users and customers, our runners and various assets are hosted on a generally available CDN called **jsDelivr**. Our online editors and runners that you set up on your website all load critical assets from the jsDelivr CDN. While convenient, this dependency introduces a potential point of failure: what if your website suddenly stops working because jsDelivr went down? This is a realistic scenario that happens more often than we'd like to admit.
14+
15+
The solution? Host Bitbybit assets on your own infrastructure using a CDN provider you trust.
16+
17+
## Understanding CDNs
18+
19+
### What is a CDN?
20+
21+
A **Content Delivery Network (CDN)** is a geographically distributed network of servers designed to deliver web content efficiently to users based on their physical location. Instead of serving all content from a single origin server, CDNs replicate and cache your static assets (JavaScript files, images, fonts, etc.) across multiple data centers worldwide.
22+
23+
### How CDNs Function
24+
25+
When a user requests content from a CDN-enabled website:
26+
27+
1. The CDN receives the request and determines the user's geographic location
28+
2. The request is routed to the nearest edge server (Point of Presence)
29+
3. If the content is cached on that edge server, it's delivered immediately
30+
4. If not cached, the edge server retrieves it from the origin, caches it, and serves it to the user
31+
5. Subsequent requests from nearby users receive the cached version
32+
33+
### Performance Benefits of CDNs
34+
35+
CDNs significantly improve website performance through:
36+
37+
- **Reduced Latency**: Content is served from geographically closer servers, minimizing the physical distance data travels
38+
- **Faster Load Times**: Cached static assets load instantly without hitting the origin server
39+
- **Bandwidth Optimization**: CDNs compress and optimize content delivery
40+
- **Load Distribution**: Traffic is distributed across multiple servers, preventing bottlenecks
41+
- **High Availability**: If one server fails, requests automatically route to another
42+
43+
### Why Consider Self-Hosting Bitbybit Assets?
44+
45+
While we provide jsDelivr hosting for convenience, there are compelling reasons to host assets on your own infrastructure:
46+
47+
1. **Reliability & Control**: You're not dependent on third-party uptime. If jsDelivr experiences an outage, your application continues functioning
48+
2. **Performance Optimization**: Choose a CDN provider optimized for your specific user base and geographic regions
49+
3. **Version Stability**: Pin specific versions without worrying about external changes or deprecations
50+
4. **Compliance & Security**: Meet enterprise requirements for asset hosting and security policies
51+
5. **Custom Caching Strategies**: Implement caching rules tailored to your application's needs
52+
6. **Cost Management**: For high-traffic applications, your own CDN plan might be more cost-effective
53+
54+
## Downloading Bitbybit Assets
55+
56+
All assets used by the Bitbybit platform are available for download from our GitHub repository:
57+
58+
**[Bitbybit Assets Releases](https://github.com/bitbybit-dev/bitbybit-assets/releases)**
59+
60+
Each release contains a complete set of assets packaged as a `.zip` file. Download the version that matches your Bitbybit implementation.
61+
62+
## Identifying Required Assets
63+
64+
### You Don't Need Everything
65+
66+
An important consideration: **you probably don't need to host all assets**, only the ones your specific implementation requires.
67+
68+
**Examples:**
69+
- If you use `bitbybit-runner-babylonjs.js`, you won't need `bitbybit-runner-threejs.js` or the lite runners
70+
- If you only use the OCCT kernel, you'll only need to host `bitbybit-occt-webworker.js`
71+
- If you never load GLTF files with Draco compression, you don't need the Draco decompressor
72+
73+
### Determining Your Asset Dependencies
74+
75+
Identifying exactly which assets you need depends on the features you're implementing. Some assets are loaded dynamically only when specific features are activated.
76+
77+
<Admonition type="tip" title="Recommended Approach for Identifying Assets">
78+
79+
1. **Use Browser DevTools**: Open your application and access the Network tab
80+
2. **Exercise All Features**: Navigate through your application, activating all features and workflows
81+
3. **Filter CDN Requests**: Look for requests matching the pattern:
82+
```
83+
https://cdn.jsdelivr.net/gh/bitbybit-dev/bitbybit-assets@<version-number-of-bitbybit>
84+
```
85+
4. **Document Assets**: Note every asset loaded from this domain—these are the files you should migrate to your own hosting
86+
87+
</Admonition>
88+
89+
### Alternative Approach: Host Everything
90+
91+
While potentially inefficient, you can simply host the complete assets folder on your infrastructure. This ensures all potential dependencies are available, though it may consume more storage and bandwidth than necessary.
92+
93+
## Configuring the Runner to Use Your CDN
94+
95+
### Using the Runner with `cdnUrl` Option
96+
97+
When initializing the Bitbybit Runner, you pass an options object containing properties like `canvasId`, `enableOCCT`, etc. This same object supports a property called **`cdnUrl`**, which tells the runner where to load assets from.
98+
99+
**Example Configuration:**
100+
101+
```javascript
102+
const runnerOptions = {
103+
canvasId: 'myCanvas',
104+
enableOCCT: true,
105+
enableJSCAD: false,
106+
enableManifold: false,
107+
cdnUrl: 'https://cdn.yourownhosting.com/bitbybit/', // Your custom CDN URL
108+
loadFonts: [],
109+
};
110+
111+
const runner = window.bitbybitRunner.getRunnerInstance();
112+
const { bitbybit, Bit } = await runner.run(runnerOptions);
113+
```
114+
115+
### Using NPM Packages with `GlobalCDNProvider`
116+
117+
If you're using Bitbybit's NPM packages directly in your project (rather than the standalone runner), you need to configure the CDN URL differently. Import the `GlobalCDNProvider` from `@bitbybit-dev/base` and set the CDN URL before initializing any Bitbybit services.
118+
119+
**Example Configuration:**
120+
121+
```javascript
122+
import { GlobalCDNProvider } from "@bitbybit-dev/base";
123+
124+
// Set your custom CDN URL before initializing Bitbybit
125+
GlobalCDNProvider.BITBYBIT_CDN_URL = "https://cdn.yourownhosting.com/bitbybit/";
126+
127+
// Now initialize your Bitbybit services as usual
128+
// All asset requests will use your custom CDN URL
129+
```
130+
131+
<Admonition type="info" title="NPM Package Users">
132+
<p>If you're using NPM packages like <code>@bitbybit-dev/occt</code>, <code>@bitbybit-dev/babylonjs</code>, or <code>@bitbybit-dev/threejs</code>, you must use the <code>GlobalCDNProvider</code> approach. The <code>cdnUrl</code> option in the runner configuration only applies when using the standalone runner files.</p>
133+
</Admonition>
134+
135+
### Important Considerations
136+
137+
**Public Access:** All hosted assets must be completely public and accessible without authentication.
138+
139+
**Recommended Hosting Strategy:**
140+
- Use global CDN providers (e.g., AWS CloudFront, Cloudflare, Azure CDN, Google Cloud CDN)
141+
- Enable automatic deployment of static assets across regions
142+
- Implement proper caching headers and strategies
143+
- Configure cache invalidation when updating versions
144+
145+
**Geographic Distribution:** Quality CDN providers automatically distribute assets to edge locations closest to your users, minimizing latency and maximizing performance.
146+
147+
**Path Structure:** Ensure your CDN URL maintains the same folder structure as the Bitbybit assets repository. The runner expects assets to be organized in specific paths relative to the `cdnUrl`.
148+
149+
<Admonition type="warning" title="Maintain Correct Folder Structure">
150+
<p>The runner expects assets to follow the exact same folder structure as found in the Bitbybit assets repository. If the structure doesn't match, assets will fail to load.</p>
151+
</Admonition>
152+
153+
## Testing Your Configuration
154+
155+
After setting up your custom CDN:
156+
157+
1. Clear your browser cache
158+
2. Load your application
159+
3. Open DevTools Network tab
160+
4. Verify all assets load from your CDN domain
161+
5. Test all features to ensure no assets are missing
162+
6. Monitor for any 404 errors indicating missing files
163+
164+
## Popular CDN Providers
165+
166+
Here are some popular CDN providers you might consider for hosting Bitbybit assets:
167+
168+
- **Cloudflare**: Offers a generous free tier with global edge locations
169+
- **AWS CloudFront**: Integrates seamlessly with S3 storage and offers fine-grained control
170+
- **Azure CDN**: Excellent for enterprises already using Microsoft Azure
171+
- **Google Cloud CDN**: Fast global network, ideal for Google Cloud users
172+
- **Fastly**: Premium CDN with real-time configuration and edge computing capabilities
173+
- **BunnyCDN**: Cost-effective option with good performance and simple pricing
174+
175+
Choose a provider based on your budget, geographic user base, existing infrastructure, and specific feature requirements.
176+
177+
## Conclusion
178+
179+
While jsDelivr hosting provides convenience for getting started, self-hosting Bitbybit assets gives you greater control, reliability, and performance optimization opportunities. By carefully selecting the assets you need and configuring a robust CDN solution, you can ensure your Bitbybit-powered applications remain fast, reliable, and independent of third-party infrastructure.
180+
181+
For more information about using the Bitbybit Runner, see [Introducing Bitbybit Runner](/learn/runners/intro).

‎docs/learn/security-policy.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
sidebar_position: 10
3+
title: Security Policy
4+
sidebar_label: Security Policy
5+
description: Guidelines for reporting security vulnerabilities to the Bitbybit team.
6+
tags: [security]
7+
---
8+
9+
## Security Policy
10+
11+
At Bitbybit, we take the security of our platform and our users' data seriously. We welcome contributions from the security community and appreciate responsible disclosure. Please note that this document may change at any time, and you are responsible for checking for updates without prior notice from us.
12+
13+
## Safe Harbor & Rules of Engagement
14+
15+
We consider security research to be a helpful activity, not a crime. If you act in good faith and follow this policy, **we will not take legal action against you** regarding your research.
16+
17+
However, we must protect our users. This pledge **does not apply** if you act maliciously - for example, by intentionally stealing data, disrupting our services, share user information with third parties, breach our [Terms and Conditions](https://bitbybit.dev/terms-and-conditions) or do not agree to our [Privacy Policy](https://bitbybit.dev/privacy-policy). In those cases, we reserve the right to take necessary legal steps.
18+
19+
**To stay safe and helpful, please:**
20+
* **Test only on accounts you own** or have explicit permission to test on.
21+
* **Do not** exfiltrate, download, or modify data residing in any other account (verify the vulnerability exists and stop there).
22+
* **Do not** execute attacks that degrade the performance of our services (e.g., DoS, spamming).
23+
* **Refrain** from publicly disclosing the vulnerability until we have had reasonable time to fix it.
24+
25+
## Reporting a Vulnerability
26+
27+
If you believe you have found a security vulnerability in our platform, please report it to us via email.
28+
29+
:::info How to Report
30+
**Email:** [info@bitbybit.dev](mailto:info@bitbybit.dev)
31+
**Subject:** Security Vulnerability Report
32+
:::
33+
34+
### What to Include
35+
To help us triage the issue efficiently, please include:
36+
1. **Type:** The class of vulnerability (e.g., XSS, SQLi, IDOR).
37+
2. **Location:** The specific URL, endpoint, or package affected.
38+
3. **Proof of Concept (PoC):** Step-by-step instructions to reproduce the issue (screenshots or video are highly encouraged).
39+
4. **Impact:** A brief summary of the potential risk.
40+
41+
*Note: Please redact sensitive information (e.g., real API keys or PII) from your report unless necessary to prove the vulnerability.*
42+
43+
## Our Process
44+
45+
We value your time and aim to be transparent about our triage process.
46+
47+
1. **Acknowledgment:** We aim to respond to valid reports within **5 business days**.
48+
2. **Assessment:** We will review the report to verify the vulnerability and assess its severity.
49+
3. **Resolution:** If the issue is confirmed, we will work on a fix. We will keep you updated on the progress.
50+
4. **Closure:** We will notify you once the issue is resolved.
51+
52+
:::note No Bug Bounty
53+
We **do not** currently offer a bug bounty program or financial compensation. Please do not submit reports expecting payment. However, we are very thankful for your efforts to keep our community safe.
54+
:::
55+
56+
### Acknowledgments
57+
58+
We value the time you invest in security research. For valid, responsibly disclosed vulnerabilities, we are happy to acknowledge your contribution in our release notes or security credits.
59+
60+
**Please Note:**
61+
* **Identification:** When reporting, please let us know how you would like to be identified (e.g., **Real Name** or **Handle/Pseudonym**). If you prefer to remain anonymous, we will respect that.
62+
* **Disclosure Details:** To protect our users and infrastructure, we reserve the right to limit the technical details shared in public acknowledgments. We generally describe the issue category (e.g., "Discovered and helped mitigate XSS vulnerability") rather than providing specific exploit steps.
63+
64+
## Scope
65+
66+
### In Scope
67+
* [bitbybit.dev](https://bitbybit.dev) website and platform
68+
* Bitbybit open-source repositories and NPM packages
69+
70+
### Out of Scope
71+
The following are generally considered out of scope and will not be acknowledged unless they present a severe risk:
72+
* Social engineering (phishing) of Bitbybit staff or contractors.
73+
* Denial of Service (DoS) attacks.
74+
* **Automated scanner reports** without a reproducible PoC.
75+
* Missing security headers (e.g., HSTS, CSP) without a clear exploitation scenario.
76+
* Self-XSS (manually entered by the user).
77+
* Vulnerabilities in third-party dependencies (unless directly caused by our implementation).
78+
* Login/Logout CSRF.

‎docs/learn/tags.yml‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -796,4 +796,14 @@ simple-matching:
796796
product-options:
797797
label: Product Options
798798
permalink: /product-options
799-
description: Product options and configurations.
799+
description: Product options and configurations.
800+
801+
cdn:
802+
label: CDN
803+
permalink: /cdn
804+
description: Content Delivery Network and caching.
805+
806+
hosting:
807+
label: Hosting
808+
permalink: /hosting
809+
description: Web hosting and server management.

0 commit comments

Comments
 (0)