Skip to content

Commit ac92f3f

Browse files
ElMoorishElMoorish
committed
Initial commit: ComLock Production Candidate
1 parent e073ae2 commit ac92f3f

115 files changed

Lines changed: 19238 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/release.yml‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
name: ComLock Release
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*'
7+
8+
jobs:
9+
# ===========================================================================
10+
# WEB BUILD
11+
# ===========================================================================
12+
build-web:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v3
16+
17+
- name: Setup Node
18+
uses: actions/setup-node@v3
19+
with:
20+
node-version: 18
21+
22+
- name: Install Rust
23+
uses: dtolnay/rust-toolchain@stable
24+
25+
- name: Install dependencies
26+
working-directory: ./comlock-app
27+
run: npm ci
28+
29+
- name: Build Web
30+
working-directory: ./comlock-app
31+
run: npm run build
32+
33+
- name: Zip Dist
34+
working-directory: ./comlock-app
35+
run: zip -r comlock-web-${{ github.ref_name }}.zip dist
36+
37+
- name: Upload Web Artifact
38+
uses: actions/upload-artifact@v3
39+
with:
40+
name: web-dist
41+
path: comlock-app/comlock-web-${{ github.ref_name }}.zip
42+
43+
# ===========================================================================
44+
# ANDROID BUILD
45+
# ===========================================================================
46+
build-android:
47+
runs-on: ubuntu-latest
48+
needs: build-web
49+
steps:
50+
- uses: actions/checkout@v3
51+
52+
- name: Setup Node
53+
uses: actions/setup-node@v3
54+
with:
55+
node-version: 18
56+
57+
- name: Install Rust
58+
uses: dtolnay/rust-toolchain@stable
59+
with:
60+
targets: aarch64-linux-android,armv7-linux-androideabi,i686-linux-android,x86_64-linux-android
61+
62+
- name: Install dependencies
63+
working-directory: ./comlock-app
64+
run: npm ci
65+
66+
- name: Build Android APK
67+
uses: tauri-apps/tauri-action@v0
68+
env:
69+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
70+
with:
71+
projectPath: ./comlock-app
72+
tagName: ${{ github.ref_name }}
73+
releaseName: 'ComLock ${{ github.ref_name }}'
74+
releaseBody: 'See the assets to download this version and install.'
75+
modKey: ${{ secrets.ANDROID_KEYSTORE }}
76+
args: android build --apk
77+
78+
# ===========================================================================
79+
# iOS BUILD
80+
# ===========================================================================
81+
build-ios:
82+
runs-on: macos-latest
83+
needs: build-web
84+
steps:
85+
- uses: actions/checkout@v3
86+
87+
- name: Setup Node
88+
uses: actions/setup-node@v3
89+
with:
90+
node-version: 18
91+
92+
- name: Install Rust
93+
uses: dtolnay/rust-toolchain@stable
94+
with:
95+
targets: aarch64-apple-ios,x86_64-apple-ios
96+
97+
- name: Install dependencies
98+
working-directory: ./comlock-app
99+
run: npm ci
100+
101+
- name: Build iOS IPA
102+
uses: tauri-apps/tauri-action@v0
103+
env:
104+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
105+
APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
106+
APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
107+
APPLE_MOBILE_PROVISIONING_PROFILE: ${{ secrets.APPLE_MOBILE_PROVISIONING_PROFILE }}
108+
with:
109+
projectPath: ./comlock-app
110+
tagName: ${{ github.ref_name }}
111+
releaseName: 'ComLock ${{ github.ref_name }}'
112+
releaseBody: 'See the assets to download this version and install.'
113+
args: ios build
114+
115+
# ===========================================================================
116+
# CREATE RELEASE
117+
# ===========================================================================
118+
create-release:
119+
runs-on: ubuntu-latest
120+
needs: [build-web, build-android, build-ios]
121+
steps:
122+
- uses: actions/download-artifact@v3
123+
with:
124+
name: web-dist
125+
126+
- name: Release
127+
uses: softprops/action-gh-release@v1
128+
if: startsWith(github.ref, 'refs/tags/')
129+
with:
130+
files: |
131+
comlock-web-*.zip
132+
comlock-app/src-tauri/gen/android/app/build/outputs/apk/universal/release/app-universal-release.apk
133+
comlock-app/src-tauri/gen/apple/build/Release-iphoneos/comlock_app.ipa

‎.gitignore‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Rust / Cargo
2+
target/
3+
**/*.rs.bk
4+
debug/
5+
release/
6+
7+
# Node / Web
8+
node_modules/
9+
dist/
10+
.DS_Store
11+
Thumbs.db
12+
13+
# Tauri
14+
src-tauri/target/
15+
src-tauri/gen/
16+
**/.tauri/
17+
18+
# Environment / Secrets
19+
.env
20+
*.env
21+
security.enc
22+
security_pentest.enc
23+
*.key
24+
*.pem
25+
26+
# IDEs
27+
.vscode/
28+
.idea/
29+
*.iml
30+
31+
# Logs
32+
npm-debug.log*
33+
yarn-debug.log*
34+
pnpm-debug.log*
35+
36+
# ComLock Specific
37+
brain/
38+
UX Design.md
39+
Implementation-plan.md
40+
Rust Implementation of KEM Braid.md

‎Documentation/PRD.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
1. Vision & ObjectivesProject ComLock aims to establish the "Anonymously Resilient" standard for digital communication. Unlike legacy secure messengers (Signal, WhatsApp) which protect content but leak metadata, and unlike anonymity networks (Tor) which sacrifice latency and usability, ComLock fuses these into a single high-assurance stack.Core Value Proposition:Unlinkability: A Global Network Adversary (GNA) cannot correlate a sender to a receiver.Post-Quantum Confidentiality: All communications are immune to "Harvest Now, Decrypt Later" via hybrid ML-KEM encapsulation.Identity Independence: No phone numbers, emails, or central servers.2. Functional Requirements2.1 The Cryptographic Core: PQ-Triple RatchetThe messaging layer must implement the Triple Ratchet protocol, an evolution of the Double Ratchet that adds a continuous KEM-based re-keying mechanism.Hybrid Handshake: Initial X3DH must be replaced with PQXDH, utilizing X25519 for classical security and ML-KEM-1024 (Kyber) for quantum resistance.The KEM Braid: To mitigate the high bandwidth cost of Kyber keys (~1.5KB), the client must implement a "Sparse Continuous Key Agreement" (SCKA).Mechanism: The KEM ratchet does not advance with every message. Instead, it advances opportunistically (e.g., every 50 messages or 24 hours).Entropy Injection: The output of the KEM encapsulation is mixed into the KDF chain ($CK_{n+1}$) alongside the ECDH output, ensuring that a compromise of the current state is healed against quantum adversaries in the future (Post-Compromise Security).2.2 Transport: Stratified Mixnet (Loopix)Clients do not connect directly. They connect to a Gateway which routes traffic through a Stratified Mixnet.Packet Format: All packets must be indistinguishable 32KB Sphinx packets.Poisson Mixing: Clients must inject dummy traffic (loops) according to a Poisson process ($\lambda_{loop}$). Real messages are delayed by a random variable $t$ drawn from an exponential distribution to decorrelate ingress/egress timing.2.3 Identity: Zero-Knowledge MembershipOnboarding: A user generates a local keypair and presents a "Proof of Humanity" (e.g., a blind signature from a localized trust anchor or a crypto-asset stake) to enter a Rate Limiting Nullifier (RLN) Merkle Tree.Signaling: Every message includes a ZK-Proof proving membership in the tree without revealing the leaf index.Slashing: If a user sends $>1$ message per epoch (e.g., 10s), their secret key is mathematically revealed by the protocol (Shamir's Secret Sharing reconstruction), allowing the network to blacklist them.3. Non-Functional Requirements & ConstraintsLatency: End-to-end latency for text messages must be $\le 2.5$ seconds (95th percentile).Bandwidth: Idle background traffic (Cover Traffic) must not exceed 5KB/s to preserve battery on mobile.Battery: Mobile clients must utilize the device's NPU/DSP for ML-KEM operations where possible to minimize main CPU wake-time.Panic Layer (Duress):Constraint: The app must support a "Duress Password."Behavior: Entering this password at the unlock screen must instantly delete the master keys from the Secure Enclave and populate the database with cryptographically signed "dummy" chat history (pre-generated) to satisfy coercive inspection.4. User StoriesAs a Whistleblower: I need to transfer a 50MB PDF to a journalist. The transfer must be chunked into Sphinx packets and mixed over 10 minutes so that my ISP sees only a constant, low-bandwidth stream indistinguishable from background noise.As a Diplomat: I need to pair with a contact without a server knowing our relationship. We perform a QR-code based Short Authentication String (SAS) verification that exchanges ML-KEM public keys directly over Bluetooth/Camera, bypassing the internet entirely for the initial trust establishment.

‎Features.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
This document outlines the feature set required to deliver "Maximum Security" while managing the inherent friction of Mixnet latency and Zero-Knowledge proofs.1. Identity & Onboarding (The "Ghost" Layer)Objective: Prove humanity without revealing identity.F-ID-01: Zero-Knowledge Account Creation:Generates a locally stored Ed25519/Kyber-1024 keypair.No phone number, email, or cloud account linkage.Mnemonic Backup: standard BIP-39 24-word seed phrase for recovery.F-ID-02: RLN Membership (Spam Shield):Proof-of-Humanity: User must provide a cryptographic "stake" to join the network (e.g., a blind signature from a trusted issuer or a minimal crypto-asset lock).Membership Tree Sync: Background synchronization of the RLN Merkle Tree to generate valid ZK proofs for sending.F-ID-03: Disposable Aliases:Users can generate ephemeral QR codes (Aliases) that link to their master public key but cannot be correlated by the network.One-Time Invite Links: Links that expire after a single handshake to prevent social graph mapping.2. Communication Core (The "Quantum" Shield)Objective: Confidentiality that survives the quantum apocalypse.F-COM-01: Hybrid Post-Quantum Messaging:Triple Ratchet: X25519 + Kyber-1024 + Symmetric Ratchet.Header Splitting: Automatic fragmentation of large Kyber keys into multiple Sphinx packets to prevent packet size correlation.F-COM-02: Asynchronous "Mailbox" Delivery:Since peer-to-peer connections may fail, messages are routed to a "Dead Drop" (SURB - Single Use Reply Block) on a random Service Provider node.Client periodically polls the Dead Drop using anonymous fetch requests.F-COM-03: Media "Shredding":File attachments (Images/PDFs) are padded to uniform block sizes (e.g., 32KB).Blocks are sent via different mix routes and reassembled by the recipient.F-COM-04: Disappearing Messages (Timer-based):Local auto-deletion of message history after $T$ time (e.g., 1 hour, 1 week).3. Network & Transport (The "Noise" Layer)Objective: Hide metadata in a forest of noise.F-NET-01: Tunable Anonymity (The "Slider"):High Latency / High Anonymity: Aggressive Poisson delays (3–10s) and high cover traffic volume.Low Latency / Standard Anonymity: Reduced delays (<2s) for active conversations.F-NET-02: Cover Traffic Generator:App generates dummy traffic ("heartbeats") even when idle.Battery Saver Mode: Reduces cover traffic when battery <20%, with a UI warning that "Metadata protection is degraded."F-NET-03: Censorship Evasion:Pluggable Transports: Option to wrap traffic in WSS (WebSocket Secure) or masquerade as a video stream (WebRTC) to bypass DPI firewalls.4. The "Panic" Layer (Physical Defense)Objective: Protect the user during physical seizure.F-SEC-01: Duress Password (Decoy Mode):Entering a specific "Duress PIN" at the lock screen unlocks a Decoy Vault.Decoy Content: Pre-populated, cryptographically valid but "innocent" chats (e.g., grocery lists, casual banter) generated by a local LLM or pre-scripted.Silent Wipe: While the decoy opens, the real keys in the Secure Enclave are silently destroyed.F-SEC-02: Dead Man's Switch:If the app is not opened for $X$ days, local keys are automatically deleted.

‎Infrastructure.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
1. Node Topology: Stratified MixnetThe network is composed of three distinct layers of nodes to prevent any single node from knowing both the sender and receiver.Layer 1 (Entry/Gateway): Handles client connections, buffers packets, and enforces RLN spam protection. Knows the User IP but not the destination.Layer 2 (Mix): Shuffles packets. Knows only the previous hop and next hop.Layer 3 (Exit/Mailbox): Stores packets for offline users. Knows the Recipient but not the sender.Topology Rule: Traffic must flow $L1 \rightarrow L2 \rightarrow L3$. Loops can flow $L1 \rightarrow L2 \rightarrow L1$.2. Public Parameters & The TreeThe Merkle Tree: Maintained via a decentralized set of Waku Store nodes.Syncing: Clients do not download the whole tree. They use Light Client Proofs to update their witness (the path to the root) only when they need to send.Anonymity Set: Target set size is $2^{20}$ (1M users). Tree depth: 20.3. CI/CD: The "Nix" Trust PipelineTo ensure no backdoors are inserted by the compiler or build server, we use Nix Flakes.flake.nix snippet:Nix{
2+
inputs = {
3+
nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
4+
rust-overlay.url = "github:oxalica/rust-overlay";
5+
};
6+
7+
outputs = { self, nixpkgs, rust-overlay,... }:
8+
let
9+
system = "x86_64-linux";
10+
pkgs = import nixpkgs {
11+
inherit system;
12+
overlays = [ (import rust-overlay) ];
13+
};
14+
in {
15+
# Hermetic build environment
16+
packages.${system}.comlock-core = pkgs.rustPlatform.buildRustPackage {
17+
pname = "comlock-core";
18+
version = "0.1.0";
19+
src =./.;
20+
cargoLock = { lockFile =./Cargo.lock; };
21+
22+
# Enforce reproducibility
23+
postInstall = ''
24+
strip -R.comment $out/bin/comlock-core
25+
# Set deterministic timestamps
26+
find $out -exec touch -h -d @0 {} +
27+
'';
28+
};
29+
}
30+
4. Censorship CircumventionIf the ComLock protocol is identified and blocked by a state firewall (DPI):Pluggable Transports: ComLock packets are wrapped in WebSocket Secure (WSS) to look like HTTPS traffic.Domain Fronting: The initial connection handshake is routed through a major CDN (e.g., Cloudflare/Fastly) so blocking the app requires blocking the entire CDN.Offline Mesh: If the internet is cut, the app switches to P2P Mode using Bluetooth LE and WiFi Direct (via the B.A.T.M.A.N protocol adapted for mobile) to relay packets to a node with uplink connectivity.

‎README.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# ComLock
2+
3+
**ComLock** is a high-assurance, post-quantum secure communication platform designed for extreme threat models. It combines the "Terminal Chic" aesthetic of a hacker dashboard with NSA-grade cryptographic engineering.
4+
5+
## 🛡️ Core Features
6+
7+
- **Post-Quantum Cryptography**: Uses **Kyber-1024 (ML-KEM)** for key encapsulation and **X25519** for ongoing ratchet secrecy.
8+
- **Panic Layer**: "Duress Mode" and "Dead Man's Switch" provide plausible deniability and automated data wiping.
9+
- **Offline-First**: Maximum security through local key management and QR-based offline handshakes.
10+
- **Terminal Chic UI**: A retro-futuristic, high-contrast interface designed for clarity and speed.
11+
12+
## 🚀 Getting Started
13+
14+
### Prerequisites
15+
16+
- **Node.js**: v18+
17+
- **Rust**: Stable toolchain (1.75+)
18+
- **Tauri CLI**: `cargo install tauri-cli`
19+
20+
### Installation
21+
22+
1. Clone the repository:
23+
```bash
24+
git clone https://github.com/your-org/comlock.git
25+
cd comlock/comlock-app
26+
```
27+
28+
2. Install dependencies:
29+
```bash
30+
npm install
31+
# Backend dependencies are handled by Cargo automatically
32+
```
33+
34+
3. Run in Development Mode:
35+
```bash
36+
npm run tauri dev
37+
```
38+
39+
## 🏗️ Build & Release
40+
41+
We use GitHub Actions for automated cross-platform builds.
42+
43+
### Triggering a Release
44+
Push a tag starting with `v` (e.g., `v1.0.0`) to the `main` branch.
45+
```bash
46+
git tag v1.0.0
47+
git push origin v1.0.0
48+
```
49+
50+
### GitHub Secrets Required
51+
For the CI/CD pipeline to work, configure the following repository secrets:
52+
53+
**Android**:
54+
- `ANDROID_KEYSTORE`: Base64 encoded keystore file.
55+
- `ANDROID_KEYSTORE_PASSWORD`: Keystore password.
56+
- `ANDROID_KEY_ALIAS`: Key alias.
57+
- `ANDROID_KEY_PASSWORD`: Key password.
58+
59+
**iOS**:
60+
- `APPLE_CERTIFICATE`: Base64 p12 certificate.
61+
- `APPLE_CERTIFICATE_PASSWORD`: Certificate password.
62+
- `APPLE_MOBILE_PROVISIONING_PROFILE`: Base64 provisioning profile.
63+
64+
## 🔐 Security
65+
66+
ComLock is built with a "paranoia-first" mindset.
67+
68+
- **Audit Status**: Phase 5 Audit Passed (Jan 2026).
69+
- **Memory Safety**: All keys are zeroized on drop.
70+
- **Storage**: AES-256-GCM encrypted local storage PIN-protected.
71+
72+
---
73+
74+
*(c) 2026 ComLock Project*

‎comlock-app/.gitignore‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Logs
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
pnpm-debug.log*
8+
lerna-debug.log*
9+
10+
node_modules
11+
dist
12+
dist-ssr
13+
*.local
14+
15+
# Editor directories and files
16+
.vscode/*
17+
!.vscode/extensions.json
18+
.idea
19+
.DS_Store
20+
*.suo
21+
*.ntvs*
22+
*.njsproj
23+
*.sln
24+
*.sw?

‎comlock-app/README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Tauri + React + Typescript
2+
3+
This template should help get you started developing with Tauri, React and Typescript in Vite.
4+
5+
## Recommended IDE Setup
6+
7+
- [VS Code](https://code.visualstudio.com/) + [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) + [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)

‎comlock-app/index.html‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<link rel="icon" type="image/svg+xml" href="/vite.svg" />
6+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
7+
<title>Tauri + React + Typescript</title>
8+
</head>
9+
10+
<body>
11+
<div id="root"></div>
12+
<script type="module" src="/src/main.tsx"></script>
13+
</body>
14+
</html>

0 commit comments

Comments
 (0)