feat: initial commit of trustlab-docs

2026-01-25 21:18:46 +07:00 · 2026-01-08 15:03:32 +07:00
commit 6c5b0c53ae
31 changed files with 8109 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,29 @@
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+pnpm-debug.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
--- a/components/CertificateDownload.tsx
+++ b/components/CertificateDownload.tsx
@@ -0,0 +1,89 @@
+import { Cards, Card } from 'nextra/components'
+import useSWR from 'swr'
+import axios from 'axios'
+import { ShieldCheck, Shield, Smartphone, Monitor } from 'lucide-react'
+import { useEffect, useState } from 'react'
+
+interface CaCertificate {
+    name: string;
+    type: string;
+    serial: string;
+    family_id?: string | null;
+    expires_at: string;
+    cdn_url?: string | null;
+    linux_cdn_url?: string | null;
+    der_cdn_url?: string | null;
+    bat_cdn_url?: string | null;
+    mac_cdn_url?: string | null;
+}
+
+const fetcher = (url: string) => axios.get(url).then(res => res.data.data)
+
+export function CertificateDownload() {
+    const { data: certificates, error } = useSWR<CaCertificate[]>('https://api.trustlab.dyzulk.com/api/public/ca-certificates', fetcher)
+    const [os, setOs] = useState<'windows' | 'mac' | 'linux' | 'android' | 'ios' | 'unknown'>('unknown')
+
+    useEffect(() => {
+        const ua = navigator.userAgent.toLowerCase()
+        if (ua.includes('win')) setOs('windows')
+        else if (ua.includes('mac')) setOs('mac')
+        else if (ua.includes('linux')) setOs('linux')
+        else if (ua.includes('android')) setOs('android')
+        else if (ua.includes('iphone') || ua.includes('ipad')) setOs('ios')
+    }, [])
+
+    if (error) return <div className="p-4 border border-red-200 bg-red-50 text-red-600 rounded-lg">Failed to load certificates. Please check your connection.</div>
+    if (!certificates) return <div className="p-4 text-gray-500 animate-pulse">Loading certificates...</div>
+
+    const rootCerts = certificates.filter(c => c.type === 'root')
+    const interCerts = certificates.filter(c => c.type !== 'root')
+
+    const getDownloadLink = (cert: CaCertificate) => {
+        if (os === 'windows' && cert.bat_cdn_url) return cert.bat_cdn_url
+        if (os === 'mac' && cert.mac_cdn_url) return cert.mac_cdn_url
+        if (os === 'android' && cert.der_cdn_url) return cert.der_cdn_url
+        if (os === 'ios' && cert.mac_cdn_url) return cert.mac_cdn_url
+        return cert.cdn_url // Default PEM
+    }
+
+    const getIcon = (type: string) => {
+        return type === 'root' ? <ShieldCheck className="w-6 h-6 text-purple-500" /> : <Shield className="w-6 h-6 text-blue-500" />
+    }
+
+    return (
+        <div className="mt-6 space-y-8">
+            <div>
+                <h3 className="text-xl font-bold mb-4 flex items-center gap-2">
+                    Root Authorities
+                    <span className="text-xs font-normal px-2 py-0.5 rounded-full bg-purple-100 text-purple-700 dark:bg-purple-900/30 dark:text-purple-300">Auto-Detected: {os.toUpperCase()}</span>
+                </h3>
+                <Cards>
+                    {rootCerts.map(cert => (
+                        <Card 
+                            key={cert.serial}
+                            icon={getIcon('root')}
+                            title={cert.name}
+                            href={getDownloadLink(cert) || '#'}
+                            target="_blank"
+                        />
+                    ))}
+                </Cards>
+            </div>
+
+            <div>
+                 <h3 className="text-xl font-bold mb-4 text-gray-600 dark:text-gray-400">Intermediate Authorities</h3>
+                 <Cards>
+                    {interCerts.map(cert => (
+                        <Card 
+                            key={cert.serial}
+                            icon={getIcon('intermediate')}
+                            title={cert.name}
+                            href={getDownloadLink(cert) || '#'}
+                            target="_blank"
+                        />
+                    ))}
+                </Cards>
+            </div>
+        </div>
+    )
+}
--- a/next-env.d.ts
+++ b/next-env.d.ts
@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/pages/building-your-application/configuring/typescript for more information.
--- a/next.config.js
+++ b/next.config.js
@@ -0,0 +1,6 @@
+const withNextra = require('nextra')({
+  theme: 'nextra-theme-docs',
+  themeConfig: './theme.config.tsx',
+})
+
+module.exports = withNextra()
--- a/package-lock.json
+++ b/package-lock.json
--- a/package.json
+++ b/package.json
@@ -0,0 +1,26 @@
+{
+  "name": "trustlab-docs",
+  "version": "0.0.1",
+  "description": "Documentation for TrustLab",
+  "scripts": {
+    "dev": "next dev -p 3001",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "axios": "^1.13.2",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.562.0",
+    "next": "^14.0.0",
+    "nextra": "2.13.4",
+    "nextra-theme-docs": "2.13.4",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "swr": "^2.3.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.2.0",
+    "typescript": "^5.0.0"
+  }
+}
--- a/pages/_meta.json
+++ b/pages/_meta.json
@@ -0,0 +1,18 @@
+{
+    "index": {
+        "title": "Introduction",
+        "type": "page"
+    },
+    "guide": {
+        "title": "User Guide",
+        "type": "page"
+    },
+    "knowledge": {
+        "title": "Knowledge Base",
+        "type": "page"
+    },
+    "policies": {
+        "title": "Policies",
+        "type": "page"
+    }
+}
--- a/pages/guide/_meta.json
+++ b/pages/guide/_meta.json
@@ -0,0 +1,6 @@
+{
+    "index": "Overview",
+    "getting-started": "Getting Started",
+    "certificates": "Certificate Operations",
+    "integrations": "Integrations"
+}
--- a/pages/guide/certificates/_meta.json
+++ b/pages/guide/certificates/_meta.json
@@ -0,0 +1,6 @@
+{
+    "request-new": "Requesting a Certificate",
+    "download-install": "Download & Formats",
+    "renewal": "Renewal Process",
+    "revocation": "Revocation"
+}
--- a/pages/guide/certificates/download-install.mdx
+++ b/pages/guide/certificates/download-install.mdx
@@ -0,0 +1,39 @@
+# Download & Formats (PEM, PFX, JKS)
+
+Once your certificate is issued, you can download it in various formats suitable for different servers and applications.
+
+## Available Formats
+
+| Format | Extension | Used For |
+| :--- | :--- | :--- |
+| **PEM (Nginx/Apache)** | `.crt`, `.key` | Standard Linux web servers. You get separate Certificate and Private Key files. |
+| **PFX / PKCS#12** | `.pfx`, `.p12` | IIS (Windows), Microsoft Exchange, Client Certificates (S/MIME). Contains both key and cert. |
+| **JKS (Java)** | `.jks` | Java applications (Tomcat, Spring Boot). |
+
+## How to Download
+
+1. Go to **"My Certificates"** in the dashboard.
+2. Click on the certificate ID or the **"View"** button.
+3. Scroll to the **"Downloads"** section.
+4. Select the format you need and click **Download**.
+
+> [!WARNING]
+> The **Private Key** is generated securely. If you lose it, you cannot recover it. You must revoke and re-issue the certificate.
+
+## Installation Examples
+
+### Nginx (PEM)
+```nginx
+server {
+    listen 443 ssl;
+    server_name internal.app;
+
+    ssl_certificate     /etc/nginx/ssl/internal.app.crt;
+    ssl_certificate_key /etc/nginx/ssl/internal.app.key;
+}
+```
+
+### Windows (PFX)
+1. Double-click the downloaded `.pfx` file.
+2. Follow the "Certificate Import Wizard".
+3. When prompted for a password, enter the password you set during download (or the default export password provided in the UI).
--- a/pages/guide/certificates/renewal.mdx
+++ b/pages/guide/certificates/renewal.mdx
@@ -0,0 +1,26 @@
+# Renewal Process
+
+Certificates expire to ensure security rotation. TrustLab simplifies the renewal process so you don't experience downtime.
+
+## When to Renew
+You will receive an email notification:
+- **30 days** before expiration.
+- **7 days** before expiration.
+- **1 day** before expiration.
+
+## How to Renew
+
+1. Log in to TrustLab.
+2. Navigate to **"My Certificates"**.
+3. Identify certificates marked with the **"Expiring Soon"** badge.
+4. Click the **"Renew"** button next to the certificate.
+5. Review the details (CN, SANs). You can add or remove SANs at this stage.
+6. Click **Confirm Renewal**.
+
+## What Happens Next?
+- A **new certificate** is generated with a new validity period.
+- The **Private Key** remains the same (if "Reuse Key" was selected) OR a new key is generated (recommended).
+- The old certificate remains valid until its original expiration date (unless revoked).
+
+> [!IMPORTANT]
+> You must **download and install the new certificate** on your server. Renewal **does not** happen automatically on the server side unless you use our ACME integration.
--- a/pages/guide/certificates/request-new.mdx
+++ b/pages/guide/certificates/request-new.mdx
@@ -0,0 +1,31 @@
+# Requesting a New Certificate
+
+TrustLab allows you to request private SSL/TLS certificates for various internal uses.
+
+## Prerequisites
+- You must have an active TrustLab account.
+- You must have the **Root CA** installed on your machine.
+
+## Step-by-Step Guide
+
+1. **Log in to Dashboard**
+   Navigate to the TrustLab Dashboard and login with your credentials.
+
+2. **Navigate to "New Certificate"**
+   Click on the **"New Request"** button in the top navigation bar or the main dashboard card.
+
+3. **Select Certificate Profile**
+   Choose the profile that matches your need:
+   - **Internal Web Server**: For HTTPS on internal tools (e.g., specific IP or `.local` domains).
+   - **User / S/MIME**: For email signing and encryption.
+   - **Code Signing**: For signing scripts and executables.
+
+4. **Fill in Details**
+   - **Common Name (CN)**: The primary domain name or IP address (e.g., `internal.app` or `192.168.1.50`).
+   - **Subject Alternative Names (SANs)**: Additional domains or IPs (optional).
+   - **Validity Period**: Choose between 90 days, 1 year, or custom (if allowed).
+
+5. **Submit Request**
+   Click **"Submit"**. The system will process your request. 
+   - If **Auto-Approval** is enabled for your role, the certificate is issued immediately.
+   - If **Manual Approval** is required, the status will be `PENDING` until a Manager approves it.
--- a/pages/guide/certificates/revocation.mdx
+++ b/pages/guide/certificates/revocation.mdx
@@ -0,0 +1,23 @@
+# Revocation (Cabut Sertifikat)
+
+Revocation invalidates a certificate before its expiration date. This is critical if a Private Key is compromised.
+
+## When to Revoke?
+- **Key Compromise**: You suspect someone stole your Private Key.
+- **Service Change**: The domain name effectively no longer belongs to the service.
+- **Mistake**: The certificate was issued with incorrect details.
+
+## How to Revoke
+
+1. Open the Certificate Detail page.
+2. Click the **"Revoke"** button (Danger Zone).
+3. Select a **Reason Code**:
+   - `unspecified` (0)
+   - `keyCompromise` (1)
+   - `cACompromise` (2)
+   - `superseded` (4)
+   - `cessationOfOperation` (5)
+4. Confirm the action.
+
+## CRL (Certificate Revocation List)
+Once revoked, the certificate serial number is added to the TrustLab CRL. All clients checking the CRL will immediately reject the certificate.
--- a/pages/guide/getting-started/_meta.json
+++ b/pages/guide/getting-started/_meta.json
@@ -0,0 +1,4 @@
+{
+    "install-root-ca": "Install Root CA",
+    "access-dashboard": "Access Dashboard"
+}
--- a/pages/guide/getting-started/access-dashboard.mdx
+++ b/pages/guide/getting-started/access-dashboard.mdx
@@ -0,0 +1,5 @@
+# Accessing Dashboard
+
+1. Navigate to [https://trustlab.dyzulk.com](https://trustlab.dyzulk.com).
+2. Click "Login".
+3. Use your SSO credentials or Magic Link.
--- a/pages/guide/getting-started/install-root-ca.mdx
+++ b/pages/guide/getting-started/install-root-ca.mdx
@@ -0,0 +1,36 @@
+import { CertificateDownload } from '../../../components/CertificateDownload'
+
+# Installing Root CA
+
+To ensure your browser trusts certificates issued by TrustLab, you must install our Root CA.
+
+<div className="my-8">
+  <CertificateDownload />
+</div>
+
+## Manual Installation Guide
+
+### Windows
+1. Download the Root CA (`.crt`) or use the auto-installer above.
+2. Double-click to open.
+3. Click "Install Certificate".
+4. Select "Local Machine" (Requires Admin).
+5. Choose "Place all certificates in the following store" -> **Trusted Root Certification Authorities**.
+
+### macOS
+1. Download the Root CA.
+2. Open in Keychain Access.
+3. Double-click the certificate.
+4. Expand "Trust" and select "Always Trust".
+
+### Linux (Debian/Ubuntu)
+```bash
+sudo cp trustlab-root.crt /usr/local/share/ca-certificates/
+sudo update-ca-certificates
+```
+
+### Android
+1. Settings > Security > Encryption & Credentials.
+2. Install a certificate > CA Certificate.
+3. Select the downloaded `.crt` or `.der` file.
+
--- a/pages/guide/index.mdx
+++ b/pages/guide/index.mdx
@@ -0,0 +1,8 @@
+# User Guide
+
+Welcome to the TrustLab User Guide. Here you will find step-by-step instructions on how to use our services.
+
+## Getting Started
+
+- [Install Root CA](/guide/getting-started/install-root-ca)
+- [Access Dashboard](/guide/getting-started/access-dashboard)
--- a/pages/guide/integrations/_meta.json
+++ b/pages/guide/integrations/_meta.json
@@ -0,0 +1,5 @@
+{
+    "smime": "S/MIME for Email",
+    "web-servers": "Web Servers (Nginx/IIS)",
+    "code-signing": "Code Signing"
+}
--- a/pages/guide/integrations/code-signing.mdx
+++ b/pages/guide/integrations/code-signing.mdx
@@ -0,0 +1,23 @@
+# Code Signing
+
+Code signing ensures that scripts and executables have not been tampered with and originate from a trusted source (Internal Developer).
+
+## Supported Formats
+- **Microsoft Authenticode** (Executables, PowerShell scripts)
+- **Java Archive** (JAR files)
+
+## Signing with SignTool (Windows)
+
+1. **Install SignTool**: Included in the Windows SDK.
+2. **Download PFX**: Get your Code Signing certificate in `.pfx` format.
+3. **Run Command**:
+
+```powershell
+signtool sign /f "MyCert.pfx" /p "password" /tr http://timestamp.digicert.com /td sha256 /fd sha256 .\MyApp.exe
+```
+
+- `/tr`: Timestamp Server (Recommended so the signature is valid even after cert expiry).
+- `/fd`: File Digest algorithm (Use SHA256).
+
+## Verifying Signature
+Right-click the `.exe` file -> **Properties** -> **Digital Signatures** tab. You should see "TrustLab Internal CA" in the certificate path.
--- a/pages/guide/integrations/smime.mdx
+++ b/pages/guide/integrations/smime.mdx
@@ -0,0 +1,28 @@
+# S/MIME Email Security
+
+Secure/Multipurpose Internet Mail Extensions (S/MIME) allows you to **sign** and **encrypt** internal emails.
+
+- **Signing**: Proves the email actually came from you (prevents spoofing).
+- **Encryption**: Ensures only the intended recipient can read the message.
+
+## Prerequisites
+- A TrustLab certificate with the **S/MIME** profile.
+- Downloaded in **PFX (.p12)** format.
+
+## Outlook (Windows) Setup
+1. Open Outlook. Go to **File > Options > Trust Center**.
+2. Click **Trust Center Settings > Email Security**.
+3. Under "Encrypted Email", click **Settings**.
+4. Click **Choose** for Signing Certificate and select your TrustLab ID.
+5. Click **OK**.
+
+## Thunderbird Setup
+1. Go to **Settings > Privacy & Security**.
+2. Scroll to **Certificates** and click **Manage Certificates**.
+3. Under **"Your Certificates"**, click **Import**.
+4. Select your `.p12` file.
+5. Go back to Account Settings > Security.
+6. Select the certificate for **Digital Signing** and **Encryption**.
+
+> [!TIP]
+> To send encrypted email to a colleague, you must first possess their Public Key (usually by receiving a signed email from them first).
--- a/pages/guide/integrations/web-servers.mdx
+++ b/pages/guide/integrations/web-servers.mdx
@@ -0,0 +1,52 @@
+# Web Server Configuration
+
+Configuring SSL/TLS on internal web servers is the most common use case for TrustLab.
+
+## Nginx Configuration
+
+Ensure you have downloaded the **PEM** format bundle (contains `.crt` and `.key`).
+
+```nginx
+server {
+    listen 80;
+    server_name internal.app;
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name internal.app;
+
+    # SSL Configuration
+    ssl_certificate     /path/to/internal.app.crt;
+    ssl_certificate_key /path/to/internal.app.key;
+
+    # Recommended Security Settings
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    ssl_prefer_server_ciphers on;
+}
+```
+
+## Apache (httpd)
+
+```apache
+<VirtualHost *:443>
+    ServerName internal.app
+    SSLEngine on
+    SSLCertificateFile "/path/to/internal.app.crt"
+    SSLCertificateKeyFile "/path/to/internal.app.key"
+</VirtualHost>
+```
+
+## IIS (Windows Server)
+
+For IIS, you must use the **PFX** format.
+
+1. Open **IIS Manager**.
+2. Select the server node.
+3. Open **Server Certificates**.
+4. Click **Import** in the actions pane.
+5. Select your `.pfx` file and enter the password.
+6. Go to your Site -> **Bindings**.
+7. Add **https** binding and select the imported certificate.
--- a/pages/index.mdx
+++ b/pages/index.mdx
@@ -0,0 +1,7 @@
+# Welcome to TrustLab Docs
+
+Welcome to the official documentation for **TrustLab**, a private SSL/TLS certificate management system.
+
+## Getting Started
+
+TrustLab helps you manage your internal PKI infrastructure with ease.
--- a/pages/knowledge/_meta.json
+++ b/pages/knowledge/_meta.json
@@ -0,0 +1,5 @@
+{
+    "index": "Overview",
+    "fundamentals": "Fundamentals",
+    "troubleshooting": "Troubleshooting"
+}
--- a/pages/knowledge/fundamentals/_meta.json
+++ b/pages/knowledge/fundamentals/_meta.json
@@ -0,0 +1,4 @@
+{
+    "pki-intro": "What is PKI?",
+    "cert-types": "Certificate Types"
+}
--- a/pages/knowledge/fundamentals/pki-intro.mdx
+++ b/pages/knowledge/fundamentals/pki-intro.mdx
@@ -0,0 +1,26 @@
+# What is PKI?
+
+**Public Key Infrastructure (PKI)** is a set of roles, policies, hardware, software, and procedures needed to create, manage, distribute, store, and revoke digital certificates.
+
+## Core Concepts
+
+### 1. Asymmetric Encryption
+PKI relies on a pair of keys:
+- **Public Key**: Shared with everyone. Used to encrypt data.
+- **Private Key**: Kept secret. Used to decrypt data and *sign* digital assets.
+
+### 2. The Chain of Trust
+A certificate is only trusted if it is signed by a trusted issuer.
+- **Root CA**: The anchor of trust. It signs itself (Self-Signed). You explicitly trust this on your device.
+- **Intermediate CA**: Signed by Root CA. Used to sign End-Entity certificates for security.
+- **End-Entity (Leaf)**: The certificate used on your Web Server or Email.
+
+TrustLab manages this entire chain for your internal organization.
+
+### 3. Why Internal PKI?
+Using Public CAs (like Let's Encrypt) is great for public websites, but incompatible with:
+- **Intranet IPs** (e.g., `10.0.0.1`).
+- **Internal Domains** (e.g., `.local`, `.corp`).
+- **VPN Services**.
+
+TrustLab fills this gap by acting as your private authority.
--- a/pages/knowledge/index.mdx
+++ b/pages/knowledge/index.mdx
@@ -0,0 +1,7 @@
+# Knowledge Base
+
+Understand the concepts behind Public Key Infrastructure (PKI) and find solutions to common problems.
+
+## Fundamentals
+
+- [What is PKI?](/knowledge/fundamentals/what-is-pki)
--- a/pages/knowledge/troubleshooting/_meta.json
+++ b/pages/knowledge/troubleshooting/_meta.json
@@ -0,0 +1,4 @@
+{
+    "browser-errors": "NET::ERR_CERT Errors",
+    "missing-root": "System Doesn't Trust CA"
+}
--- a/pages/knowledge/troubleshooting/browser-errors.mdx
+++ b/pages/knowledge/troubleshooting/browser-errors.mdx
@@ -0,0 +1,32 @@
+# Common Browser Errors
+
+When using internal certificates, browsers are very strict. Here are common error codes and what they mean.
+
+## NET::ERR_CERT_AUTHORITY_INVALID hiding
+
+**Cause:**
+The browser does not recognize the Root CA that issued the certificate.
+
+**Solution:**
+You have not installed the TrustLab Root CA on your device.
+-> [Go to Installation Guide](/guide/getting-started/install-root-ca)
+
+## NET::ERR_CERT_COMMON_NAME_INVALID
+
+**Cause:**
+The domain name you are visiting (e.g., `app.local`) does not match the names listed in the certificate.
+
+**Solution:**
+Check the **SANs (Subject Alternative Names)** of the certificate.
+1. Click the "Not Secure" icon in the address bar.
+2. View Certificate.
+3. Check "DNS Names". If the domain is missing, you must **Re-issue** the certificate.
+
+## NET::ERR_CERT_DATE_INVALID
+
+**Cause:**
+The certificate has expired or the system clock is wrong.
+
+**Solution:**
+1. Check your computer's date and time.
+2. If time is correct, the certificate is expired. [Renew the certificate](/guide/certificates/renewal).
--- a/pages/policies/index.mdx
+++ b/pages/policies/index.mdx
@@ -0,0 +1,6 @@
+# Policies
+
+Official documents governing the operations and usage of TrustLab PKI.
+
+- [Certificate Policy (CP)](/policies/cp)
+- [Certification Practice Statement (CPS)](/policies/cps)
--- a/theme.config.tsx
+++ b/theme.config.tsx
@@ -0,0 +1,15 @@
+import React from 'react'
+import { DocsThemeConfig } from 'nextra-theme-docs'
+
+const config: DocsThemeConfig = {
+  logo: <span>TrustLab Docs</span>,
+  project: {
+    link: 'https://github.com/dyzulk/trustlab-docs',
+  },
+  docsRepositoryBase: 'https://github.com/dyzulk/trustlab-docs/tree/main',
+  footer: {
+    text: 'TrustLab Documentation',
+  },
+}
+
+export default config
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "es5",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules"]
+}