diff --git a/ABI-FFI-README.md b/ABI-FFI-README.adoc similarity index 74% rename from ABI-FFI-README.md rename to ABI-FFI-README.adoc index f41a54e..04be86a 100644 --- a/ABI-FFI-README.md +++ b/ABI-FFI-README.adoc @@ -1,19 +1,22 @@ -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -45,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, AffineScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -77,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── affinescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -97,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -111,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -125,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -140,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -215,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -237,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -259,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -282,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -312,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -342,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License MPL-2.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 4cacc1e..4331977 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -1,90 +1,78 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Changelog - -All notable changes to DoubleTrack Browser will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -== [Unreleased] - -=== Added -- Initial project structure with Rust/WASM core and TypeScript shell -- Profile generation system with demographics, interests, and browsing styles -- Activity simulation engine with realistic URL and timing generation -- Browser extension with popup UI and options page -- Background service worker for automated activity simulation -- Storage management for profiles, activities, and statistics -- Configurable noise levels and privacy modes -- Schedule-aware activity generation based on profile occupation -- Activity history tracking and viewing -- Statistics dashboard showing activity metrics -- Content script for future page-level integration -- Comprehensive documentation (README, CLAUDE, DEVELOPMENT, CONTRIBUTING) -- Full test infrastructure for Rust and TypeScript -- Build pipeline with webpack and wasm-pack - -=== Features -- **Profile Generation**: Creates consistent, believable fictional personas - - Demographics: age, gender, location, occupation, education - - 20+ interest categories from technology to hobbies - - 4 browsing styles: Focused, Explorer, Researcher, Casual - - 4 activity levels: Low, Medium, High, VeryHigh - -- **Activity Simulation**: Generates realistic browsing patterns - - 7 activity types: Search, PageVisit, VideoWatch, Shopping, SocialMedia, News, Research - - Interest-correlated URL generation for major sites - - Realistic duration distributions based on activity type - - Schedule-based timing aligned with profile occupation - -- **Privacy Controls**: - - 4 privacy modes: Full, Moderate, Minimal, Disabled - - Adjustable noise level (0-100%) - - Optional schedule adherence - - Separate storage for real vs. simulated data - -- **User Interface**: - - Modern, gradient-based design - - Popup for quick status and controls - - Full options page for detailed configuration - - Activity history viewer with filtering - - Real-time statistics display - - Profile export functionality - -=== Technical -- Rust core compiled to WebAssembly for performance -- TypeScript with strict mode for type safety -- Manifest V3 for modern browser compatibility -- Alarm-based scheduling for efficient background operation -- IndexedDB via chrome.storage for data persistence -- Modular architecture for easy extension - -== [0.1.0] - 2025-11-22 - -=== Initial Release -- First working version of DoubleTrack Browser -- Experimental software for privacy exploration -- Full documentation and contribution guidelines - ---- - -== Version History - -- **0.1.0** - Initial release with core functionality -- **Unreleased** - Active development - -== Migration Guide - -No migrations needed yet. This is the initial release. - -== Deprecation Warnings - -None yet. - -== Security - -If you discover a security vulnerability, please email [security@example.com] rather than using the issue tracker. - ---- - -*For detailed changes, see the [commit history](https://github.com/yourusername/double-track-browser/commits).* +== Changelog + +All notable changes to `+double-track-browser+` will be documented in +this file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat(crg): add crg-grade and crg-badge justfile recipes +* feat: add wokelangiser accessibility+consent manifest +* feat: add stapeln.toml container definition +* feat: deploy UX Manifesto infrastructure +* feat: add CLADE.a2ml — clade taxonomy declaration +* feat: implement data poisoning engine with real tab orchestration +* feat(ci): enable Hypatia scanning + +==== Fixed + +* fix(affine): migrate record literals to #\{ } (affinescript#218) (#28) +* fix(ci): bump a2ml/k9-validate-action pins to canonical (#25) +* fix(ci): sync hypatia-scan.yml to canonical (#24) +* fix(ci): adopt canonical hypatia-scan.yml (#22) +* fix(ci): hypatia-scan workdir ($\{\{ env.HOME }} resolves empty) (#21) +* fix(ci): rsr-antipattern duplicate heredoc + setup-beam ubuntu24 (#17) +* fix(ci): repair YAML block-scalar in workflow-linter Check Permissions +step (#18) +* fix(ci): move secret-scanner Cargo.toml gate from job-level if: to +step-level (#19) +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder +* fix(ci): Resolve workflow-linter self-matching and metadata issues + +==== Changed + +* refactor(rust_core): migrate rand 0.8 -> 0.9 API (44 build errors -> +0) +* refactor(rust_core): close .expect("`TODO: handle error`") +anti-pattern +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) + +==== Documentation + +* docs(governance): CRG v2.0 STRICT audit — C (declared) -> E (honest) +* docs: substantive CRG C annotation (EXPLAINME.adoc) +* docs: add EXPLAINME.adoc — prove-it file backing README claims +* docs: add checkpoint files for state tracking + +==== CI + +* ci: redistribute concurrency-cancel guard to read-only check workflows +(#27) +* ci: bump actions/upload-artifact SHA to current v4 (#16) +* ci(dependabot): restore cargo PR limit so security PRs flow (#15) +* ci(secret-scanner): drop duplicate –fail from trufflehog extra_args +(#14) +* ci: SHA-pin hyperpolymath validate-actions in dogfood-gate + +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 9a28cf8..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,71 +0,0 @@ - - -# Changelog - -All notable changes to `double-track-browser` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat(crg): add crg-grade and crg-badge justfile recipes -- feat: add wokelangiser accessibility+consent manifest -- feat: add stapeln.toml container definition -- feat: deploy UX Manifesto infrastructure -- feat: add CLADE.a2ml — clade taxonomy declaration -- feat: implement data poisoning engine with real tab orchestration -- feat(ci): enable Hypatia scanning - -### Fixed - -- fix(affine): migrate record literals to #{ } (affinescript#218) (#28) -- fix(ci): bump a2ml/k9-validate-action pins to canonical (#25) -- fix(ci): sync hypatia-scan.yml to canonical (#24) -- fix(ci): adopt canonical hypatia-scan.yml (#22) -- fix(ci): hypatia-scan workdir (${{ env.HOME }} resolves empty) (#21) -- fix(ci): rsr-antipattern duplicate heredoc + setup-beam ubuntu24 (#17) -- fix(ci): repair YAML block-scalar in workflow-linter Check Permissions step (#18) -- fix(ci): move secret-scanner Cargo.toml gate from job-level if: to step-level (#19) -- fix(scorecard): enforce granular permissions and add fuzzing placeholder -- fix(ci): Resolve workflow-linter self-matching and metadata issues - -### Changed - -- refactor(rust_core): migrate rand 0.8 -> 0.9 API (44 build errors -> 0) -- refactor(rust_core): close .expect("TODO: handle error") anti-pattern -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs(governance): CRG v2.0 STRICT audit — C (declared) -> E (honest) -- docs: substantive CRG C annotation (EXPLAINME.adoc) -- docs: add EXPLAINME.adoc — prove-it file backing README claims -- docs: add checkpoint files for state tracking - -### CI - -- ci: redistribute concurrency-cancel guard to read-only check workflows (#27) -- ci: bump actions/upload-artifact SHA to current v4 (#16) -- ci(dependabot): restore cargo PR limit so security PRs flow (#15) -- ci(secret-scanner): drop duplicate --fail from trufflehog extra_args (#14) -- ci: SHA-pin hyperpolymath validate-actions in dogfood-gate - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..d041ef1 --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,215 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +our community a harassment-free experience for everyone, regardless of +age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, color, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +=== Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our +mistakes, and learning from the experience +* Focusing on what is best not just for us as individuals, but for the +overall community +* *Supporting reversibility*: Encouraging experimentation and safe +failure +* *Respecting emotional safety*: Being mindful of anxiety and cognitive +load +* *Valuing diverse expertise*: Recognizing contributions from all skill +levels + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or +advances of any kind +* Trolling, insulting or derogatory comments, and personal or political +attacks +* Public or private harassment +* Publishing others’ private information, such as a physical or email +address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a +professional setting +* *Dismissing emotional concerns* as "`just feelings`" or "`being too +sensitive`" +* *Gatekeeping*: Excluding contributors based on experience level +* *Demanding unpaid labor*: Expecting maintainers to fix your issues +immediately + +=== Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our +standards of acceptable behavior and will take appropriate and fair +corrective action in response to any behavior that they deem +inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other +contributions that are not aligned to this Code of Conduct, and will +communicate reasons for moderation decisions when appropriate. + +=== Scope + +This Code of Conduct applies within all community spaces, and also +applies when an individual is officially representing the community in +public spaces. Examples of representing our community include using an +official email address, posting via an official social media account, or +acting as an appointed representative at an online or offline event. + +=== Tri-Perimeter Contribution Framework (TPCF) + +This project uses the *Tri-Perimeter Contribution Framework* to manage +trust and access control. Different perimeters have different behavioral +expectations: + +==== Perimeter 3: Community Sandbox (Current) + +*Access*: Open to all *Expectations*: - Follow this Code of Conduct - +Respect the review process - Accept that PRs may be rejected - +Understand maintainers have final say + +*Enforcement*: Community standards apply, violations result in removal +from Perimeter 3 and potential blocking. + +==== Perimeter 2: Trusted Contributors (Future) + +*Access*: Granted after sustained contributions *Expectations*: - All +Perimeter 3 expectations - Higher quality bar for contributions - Active +participation in discussions - Mentoring newcomers + +*Enforcement*: Higher trust means higher accountability. Violations may +result in demotion to Perimeter 3. + +==== Perimeter 1: Core Stewards (Future) + +*Access*: Invitation-only *Expectations*: - All Perimeter 2 expectations +- Project governance responsibilities - Conflict resolution - Strategic +direction + +*Enforcement*: Stewards hold themselves to the highest standard. + +=== Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported to the community leaders responsible for enforcement at: + +*Email*: conduct@example.com *Response SLA*: 72 hours + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security +of the reporter of any incident. + +=== Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in +determining the consequences for any action they deem in violation of +this Code of Conduct: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behavior +deemed unprofessional or unwelcome in the community. + +*Consequence*: A private, written warning from community leaders, +providing clarity around the nature of the violation and an explanation +of why the behavior was inappropriate. A public apology may be +requested. + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period of +time. This includes avoiding interactions in community spaces as well as +external channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behavior. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No +public or private interaction with the people involved, including +unsolicited interaction with those enforcing the Code of Conduct, is +allowed during this period. Violating these terms may lead to a +permanent ban. + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +=== Emotional Safety + +This project prioritizes *emotional safety* alongside technical +excellence: + +==== Anxiety-Reducing Practices + +* *Reversibility*: All changes can be reverted easily +* *No Blame*: Focus on fixing problems, not finding fault +* *Ask Questions*: "`Stupid questions`" don’t exist +* *Experiment Freely*: Mistakes are learning opportunities +* *Take Breaks*: It’s okay to step away + +==== Burnout Prevention + +* *Sustainable Pace*: No crunch time culture +* *Say No*: Maintainers can decline features +* *Life Happens*: Family/health come first +* *No Guilt*: Disappearing for months is fine + +==== Communication Norms + +* *Assume Good Intent*: Start with charity +* *Request, Don’t Demand*: "`Could you…`" not "`You need to…`" +* *Praise in Public, Critique in Private*: Be generous with recognition +* *Emoji Encouraged*: 🎉 Make interactions warmer + +=== Attribution + +This Code of Conduct is adapted from the +https://www.contributor-covenant.org[Contributor Covenant], version 2.1, +available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. + +Community Impact Guidelines were inspired by +https://github.com/mozilla/diversity[Mozilla’s code of conduct +enforcement ladder]. + +Emotional safety sections inspired by: - +https://www.rust-lang.org/policies/code-of-conduct[Rust Code of Conduct] +- https://ethicalsource.dev/principles/[Ethical Source Principles] - +DoubleTrack’s focus on reversibility and experimentation + +For answers to common questions about this code of conduct, see the FAQ +at https://www.contributor-covenant.org/faq. Translations are available +at https://www.contributor-covenant.org/translations. + +''''' + +*Version*: 2.1 (DoubleTrack Extended) *Last Updated*: 2025-11-22 *Next +Review*: 2026-11-22 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index f8d4491..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,218 +0,0 @@ -# Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, caste, color, religion, or sexual -identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, -diverse, inclusive, and healthy community. - -## Our Standards - -Examples of behavior that contributes to a positive environment for our -community include: - -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience -* Focusing on what is best not just for us as individuals, but for the overall - community -* **Supporting reversibility**: Encouraging experimentation and safe failure -* **Respecting emotional safety**: Being mindful of anxiety and cognitive load -* **Valuing diverse expertise**: Recognizing contributions from all skill levels - -Examples of unacceptable behavior include: - -* The use of sexualized language or imagery, and sexual attention or advances of - any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or email address, - without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting -* **Dismissing emotional concerns** as "just feelings" or "being too sensitive" -* **Gatekeeping**: Excluding contributors based on experience level -* **Demanding unpaid labor**: Expecting maintainers to fix your issues immediately - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of -acceptable behavior and will take appropriate and fair corrective action in -response to any behavior that they deem inappropriate, threatening, offensive, -or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions that are -not aligned to this Code of Conduct, and will communicate reasons for moderation -decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. -Examples of representing our community include using an official email address, -posting via an official social media account, or acting as an appointed -representative at an online or offline event. - -## Tri-Perimeter Contribution Framework (TPCF) - -This project uses the **Tri-Perimeter Contribution Framework** to manage trust -and access control. Different perimeters have different behavioral expectations: - -### Perimeter 3: Community Sandbox (Current) - -**Access**: Open to all -**Expectations**: -- Follow this Code of Conduct -- Respect the review process -- Accept that PRs may be rejected -- Understand maintainers have final say - -**Enforcement**: Community standards apply, violations result in removal from -Perimeter 3 and potential blocking. - -### Perimeter 2: Trusted Contributors (Future) - -**Access**: Granted after sustained contributions -**Expectations**: -- All Perimeter 3 expectations -- Higher quality bar for contributions -- Active participation in discussions -- Mentoring newcomers - -**Enforcement**: Higher trust means higher accountability. Violations may result -in demotion to Perimeter 3. - -### Perimeter 1: Core Stewards (Future) - -**Access**: Invitation-only -**Expectations**: -- All Perimeter 2 expectations -- Project governance responsibilities -- Conflict resolution -- Strategic direction - -**Enforcement**: Stewards hold themselves to the highest standard. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at: - -**Email**: conduct@example.com -**Response SLA**: 72 hours - -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the -reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining -the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing -clarity around the nature of the violation and an explanation of why the -behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of -actions. - -**Consequence**: A warning with consequences for continued behavior. No -interaction with the people involved, including unsolicited interaction with -those enforcing the Code of Conduct, for a specified period of time. This -includes avoiding interactions in community spaces as well as external channels -like social media. Violating these terms may lead to a temporary or permanent -ban. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including -sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period of time. No public or -private interaction with the people involved, including unsolicited interaction -with those enforcing the Code of Conduct, is allowed during this period. -Violating these terms may lead to a permanent ban. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior, harassment of an -individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the -community. - -## Emotional Safety - -This project prioritizes **emotional safety** alongside technical excellence: - -### Anxiety-Reducing Practices - -- **Reversibility**: All changes can be reverted easily -- **No Blame**: Focus on fixing problems, not finding fault -- **Ask Questions**: "Stupid questions" don't exist -- **Experiment Freely**: Mistakes are learning opportunities -- **Take Breaks**: It's okay to step away - -### Burnout Prevention - -- **Sustainable Pace**: No crunch time culture -- **Say No**: Maintainers can decline features -- **Life Happens**: Family/health come first -- **No Guilt**: Disappearing for months is fine - -### Communication Norms - -- **Assume Good Intent**: Start with charity -- **Request, Don't Demand**: "Could you..." not "You need to..." -- **Praise in Public, Critique in Private**: Be generous with recognition -- **Emoji Encouraged**: 🎉 Make interactions warmer - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 2.1, available at -[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. - -Community Impact Guidelines were inspired by -[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. - -Emotional safety sections inspired by: -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Ethical Source Principles](https://ethicalsource.dev/principles/) -- DoubleTrack's focus on reversibility and experimentation - -For answers to common questions about this code of conduct, see the FAQ at -[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at -[https://www.contributor-covenant.org/translations][translations]. - -[homepage]: https://www.contributor-covenant.org -[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html -[Mozilla CoC]: https://github.com/mozilla/diversity -[FAQ]: https://www.contributor-covenant.org/faq -[translations]: https://www.contributor-covenant.org/translations - ---- - -**Version**: 2.1 (DoubleTrack Extended) -**Last Updated**: 2025-11-22 -**Next Review**: 2026-11-22 diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..3759d7f --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/double-track-browser.git cd +double-track-browser + +== Using Guix (recommended for reproducibility) + +guix develop + +== Or using toolbox/distrobox + +toolbox create double-track-browser-dev toolbox enter +double-track-browser-dev # Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +double-track-browser/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ # +Library code (Perimeter 1-2) ├── extensions/ # Extensions (Perimeter 2) +├── plugins/ # Plugins (Perimeter 2) ├── tools/ # Tooling (Perimeter 2) +├── docs/ # Documentation (Perimeter 3) │ ├── architecture/ # ADRs, +specs (Perimeter 2) │ └── proposals/ # RFCs (Perimeter 3) ├── examples/ +# Examples (Perimeter 3) ├── spec/ # Spec tests (Perimeter 3) ├── tests/ +# Test suite (Perimeter 2-3) ├── .well-known/ # Protocol files +(Perimeter 1-3) ├── .github/ # GitHub config (Perimeter 1) │ ├── +ISSUE_TEMPLATE/ │ └── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md +├── CONTRIBUTING.md # This file ├── GOVERNANCE.md ├── LICENSE ├── +MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.guix # Guix +flake (Perimeter 1) └── Justfile # Task runner (Perimeter 1) + +.... + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/double-track-browser/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/double-track-browser/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/double-track-browser/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/double-track-browser/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +.... + +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) + +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 2c007da..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/double-track-browser.git -cd double-track-browser - -# Using Guix (recommended for reproducibility) -guix develop - -# Or using toolbox/distrobox -toolbox create double-track-browser-dev -toolbox enter double-track-browser-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -double-track-browser/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.guix # Guix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/double-track-browser/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/double-track-browser/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/double-track-browser/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/double-track-browser/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/DEVELOPMENT.adoc b/DEVELOPMENT.adoc new file mode 100644 index 0000000..bbc2f08 --- /dev/null +++ b/DEVELOPMENT.adoc @@ -0,0 +1,308 @@ +== Development Guide + +This guide covers setting up and developing DoubleTrack Browser. + +=== Prerequisites + +* *Node.js* (v18 or higher) +* *npm* or *yarn* +* *Rust* (latest stable) +* *wasm-pack* for compiling Rust to WebAssembly + +==== Installing Rust and wasm-pack + +[source,bash] +---- +# Install Rust +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + +# Install wasm-pack +curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh +---- + +=== Project Structure + +.... +double-track-browser/ +├── rust_core/ # Rust/WASM core logic +│ ├── src/ +│ │ ├── lib.rs # Main WASM bindings +│ │ ├── profile.rs # Profile generation +│ │ ├── activity.rs # Activity simulation +│ │ ├── interests.rs # URL generation +│ │ └── schedule.rs # Scheduling logic +│ └── Cargo.toml +├── src/ # TypeScript extension +│ ├── background/ # Service worker +│ ├── popup/ # Popup UI +│ ├── options/ # Options page +│ ├── content/ # Content scripts +│ ├── types/ # Type definitions +│ ├── utils/ # Utility functions +│ └── manifest.json +├── dist/ # Build output (gitignored) +├── icons/ # Extension icons +└── package.json +.... + +=== Initial Setup + +[source,bash] +---- +# 1. Clone the repository +git clone https://github.com/yourusername/double-track-browser.git +cd double-track-browser + +# 2. Install Node dependencies +npm install + +# 3. Build the Rust core +cd rust_core +wasm-pack build --target web +cd .. + +# 4. Build the extension +npm run build +---- + +=== Development Workflow + +==== Building + +[source,bash] +---- +# Full build (Rust + TypeScript) +npm run build + +# Build Rust core only +npm run build:rust + +# Build extension only (assumes Rust already built) +npm run build:extension + +# Development mode with watch +npm run dev +---- + +==== Testing + +[source,bash] +---- +# Run Rust tests +npm run test:rust + +# Run TypeScript tests +npm run test:ts + +# Run all tests +npm test + +# Type checking +npm run type-check + +# Linting +npm run lint +---- + +==== Loading the Extension + +===== Chrome/Chromium + +[arabic] +. Open `+chrome://extensions/+` +. Enable "`Developer mode`" (top right) +. Click "`Load unpacked`" +. Select the `+dist/+` directory + +===== Firefox + +[arabic] +. Open `+about:debugging#/runtime/this-firefox+` +. Click "`Load Temporary Add-on`" +. Select any file in the `+dist/+` directory (e.g., `+manifest.json+`) + +=== Development Tips + +==== Debugging + +*Background Service Worker:* - Chrome: `+chrome://extensions/+` → Click +"`service worker`" link - Firefox: `+about:debugging+` → Inspect +extension + +*Popup:* - Right-click popup → "`Inspect`" + +*Options Page:* - Open options, right-click → "`Inspect`" + +*Content Scripts:* - Use browser DevTools console on any page - Filter +console by "`DoubleTrack`" + +==== Hot Reloading + +The `+npm run dev+` command watches for file changes, but you’ll need +to: 1. Reload the extension in `+chrome://extensions/+` 2. Or use an +auto-reload extension like "`Extension Reloader`" + +==== Rust Development + +When modifying Rust code: + +[source,bash] +---- +cd rust_core + +# Check code without building +cargo check + +# Run tests +cargo test + +# Build and check wasm output +wasm-pack build --target web + +# Optimize for size (production) +wasm-pack build --target web --release +---- + +==== TypeScript Development + +TypeScript files are in `+src/+`. Key files: + +* `+background/index.ts+` - Main service worker logic +* `+utils/storage.ts+` - Data persistence +* `+utils/wasm.ts+` - Rust/WASM interface +* `+types/index.ts+` - Type definitions + +==== Working with WASM + +The Rust core is compiled to WASM and loaded by TypeScript: + +[arabic] +. Rust exports functions via `+#[wasm_bindgen]+` +. TypeScript imports via `+utils/wasm.ts+` +. Data is serialized/deserialized with `+serde-wasm-bindgen+` + +Currently using mock implementations in `+wasm.ts+` - replace with +actual WASM calls once compiled. + +=== Common Issues + +==== WASM Module Not Found + +*Problem:* Extension can’t find WASM files + +*Solution:* - Ensure `+npm run build:rust+` completed successfully - +Check `+dist/+` contains `+.wasm+` files - Verify webpack copied files +correctly + +==== Service Worker Not Updating + +*Problem:* Changes not reflected after reload + +*Solution:* - Chrome: Click "`service worker`" link to open DevTools - +Use "`Update`" button in extensions page - Clear storage: DevTools → +Application → Clear storage + +==== Type Errors + +*Problem:* TypeScript errors in editor + +*Solution:* + +[source,bash] +---- +npm run type-check +npm install # Ensure all types are installed +---- + +==== Build Failures + +*Problem:* Webpack or Rust build fails + +*Solution:* - Check Node.js version: `+node --version+` (should be v18+) +- Check Rust version: `+rustc --version+` - Clear builds: +`+npm run clean && npm run build+` - Delete `+node_modules+` and +reinstall: `+rm -rf node_modules && npm install+` + +=== Performance Optimization + +==== Rust + +* Use `+--release+` flag for production builds +* Profile with `+cargo flamegraph+` (install with +`+cargo install flamegraph+`) +* Minimize allocations in hot paths +* Use `+SmallRng+` instead of full RNG for speed + +==== TypeScript + +* Lazy load WASM module +* Debounce frequent operations +* Use `+chrome.alarms+` instead of `+setInterval+` +* Batch storage operations + +==== Extension Size + +Current optimizations: - Rust compiled with `+opt-level = "z"+` +(optimize for size) - LTO enabled for smaller binaries - Dead code +elimination via tree-shaking + +=== Architecture Decisions + +==== Why Rust + TypeScript? + +* *Rust*: Memory safety, performance, complex logic +* *TypeScript*: Browser API integration, UI, async operations +* *WASM*: Bridge between them + +==== Storage Design + +* Uses `+chrome.storage.local+` for persistence +* Profile data stored separately from activity history +* Statistics updated incrementally +* Activity history capped at 1000 entries + +==== Activity Simulation + +* Poisson distribution for realistic timing +* Profile-based URL generation +* Schedule-aware execution +* Configurable noise levels + +=== Contributing + +See `+CONTRIBUTING.md+` for contribution guidelines. + +==== Code Style + +*Rust:* - Follow Rust standard style (`+rustfmt+`) - Document public +APIs - Write tests for new features + +*TypeScript:* - Use ESLint configuration - Prefer `+async/await+` over +callbacks - Type everything (no `+any+`) + +=== Release Process + +[arabic] +. Update version in `+package.json+` and `+Cargo.toml+` +. Update `+CHANGELOG.md+` +. Run full test suite +. Build production version +. Test loaded extension thoroughly +. Create git tag +. Build distribution package +. Submit to Chrome Web Store / Firefox Add-ons + +=== Resources + +* https://developer.chrome.com/docs/extensions/mv3/[Manifest V3 +Documentation] +* https://rustwasm.github.io/docs/book/[WebAssembly Guide] +* https://rustwasm.github.io/wasm-pack/[wasm-pack Documentation] +* https://github.com/rustwasm/wasm-bindgen[Rust WebExtensions Example] + +=== Getting Help + +* Check existing issues on GitHub +* Read CLAUDE.md for AI assistant context +* Review inline code comments +* Consult browser extension documentation diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md deleted file mode 100644 index 52d374d..0000000 --- a/DEVELOPMENT.md +++ /dev/null @@ -1,305 +0,0 @@ -# Development Guide - -This guide covers setting up and developing DoubleTrack Browser. - -## Prerequisites - -- **Node.js** (v18 or higher) -- **npm** or **yarn** -- **Rust** (latest stable) -- **wasm-pack** for compiling Rust to WebAssembly - -### Installing Rust and wasm-pack - -```bash -# Install Rust -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - -# Install wasm-pack -curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh -``` - -## Project Structure - -``` -double-track-browser/ -├── rust_core/ # Rust/WASM core logic -│ ├── src/ -│ │ ├── lib.rs # Main WASM bindings -│ │ ├── profile.rs # Profile generation -│ │ ├── activity.rs # Activity simulation -│ │ ├── interests.rs # URL generation -│ │ └── schedule.rs # Scheduling logic -│ └── Cargo.toml -├── src/ # TypeScript extension -│ ├── background/ # Service worker -│ ├── popup/ # Popup UI -│ ├── options/ # Options page -│ ├── content/ # Content scripts -│ ├── types/ # Type definitions -│ ├── utils/ # Utility functions -│ └── manifest.json -├── dist/ # Build output (gitignored) -├── icons/ # Extension icons -└── package.json -``` - -## Initial Setup - -```bash -# 1. Clone the repository -git clone https://github.com/yourusername/double-track-browser.git -cd double-track-browser - -# 2. Install Node dependencies -npm install - -# 3. Build the Rust core -cd rust_core -wasm-pack build --target web -cd .. - -# 4. Build the extension -npm run build -``` - -## Development Workflow - -### Building - -```bash -# Full build (Rust + TypeScript) -npm run build - -# Build Rust core only -npm run build:rust - -# Build extension only (assumes Rust already built) -npm run build:extension - -# Development mode with watch -npm run dev -``` - -### Testing - -```bash -# Run Rust tests -npm run test:rust - -# Run TypeScript tests -npm run test:ts - -# Run all tests -npm test - -# Type checking -npm run type-check - -# Linting -npm run lint -``` - -### Loading the Extension - -#### Chrome/Chromium - -1. Open `chrome://extensions/` -2. Enable "Developer mode" (top right) -3. Click "Load unpacked" -4. Select the `dist/` directory - -#### Firefox - -1. Open `about:debugging#/runtime/this-firefox` -2. Click "Load Temporary Add-on" -3. Select any file in the `dist/` directory (e.g., `manifest.json`) - -## Development Tips - -### Debugging - -**Background Service Worker:** -- Chrome: `chrome://extensions/` → Click "service worker" link -- Firefox: `about:debugging` → Inspect extension - -**Popup:** -- Right-click popup → "Inspect" - -**Options Page:** -- Open options, right-click → "Inspect" - -**Content Scripts:** -- Use browser DevTools console on any page -- Filter console by "DoubleTrack" - -### Hot Reloading - -The `npm run dev` command watches for file changes, but you'll need to: -1. Reload the extension in `chrome://extensions/` -2. Or use an auto-reload extension like "Extension Reloader" - -### Rust Development - -When modifying Rust code: - -```bash -cd rust_core - -# Check code without building -cargo check - -# Run tests -cargo test - -# Build and check wasm output -wasm-pack build --target web - -# Optimize for size (production) -wasm-pack build --target web --release -``` - -### TypeScript Development - -TypeScript files are in `src/`. Key files: - -- `background/index.ts` - Main service worker logic -- `utils/storage.ts` - Data persistence -- `utils/wasm.ts` - Rust/WASM interface -- `types/index.ts` - Type definitions - -### Working with WASM - -The Rust core is compiled to WASM and loaded by TypeScript: - -1. Rust exports functions via `#[wasm_bindgen]` -2. TypeScript imports via `utils/wasm.ts` -3. Data is serialized/deserialized with `serde-wasm-bindgen` - -Currently using mock implementations in `wasm.ts` - replace with actual WASM calls once compiled. - -## Common Issues - -### WASM Module Not Found - -**Problem:** Extension can't find WASM files - -**Solution:** -- Ensure `npm run build:rust` completed successfully -- Check `dist/` contains `.wasm` files -- Verify webpack copied files correctly - -### Service Worker Not Updating - -**Problem:** Changes not reflected after reload - -**Solution:** -- Chrome: Click "service worker" link to open DevTools -- Use "Update" button in extensions page -- Clear storage: DevTools → Application → Clear storage - -### Type Errors - -**Problem:** TypeScript errors in editor - -**Solution:** -```bash -npm run type-check -npm install # Ensure all types are installed -``` - -### Build Failures - -**Problem:** Webpack or Rust build fails - -**Solution:** -- Check Node.js version: `node --version` (should be v18+) -- Check Rust version: `rustc --version` -- Clear builds: `npm run clean && npm run build` -- Delete `node_modules` and reinstall: `rm -rf node_modules && npm install` - -## Performance Optimization - -### Rust - -- Use `--release` flag for production builds -- Profile with `cargo flamegraph` (install with `cargo install flamegraph`) -- Minimize allocations in hot paths -- Use `SmallRng` instead of full RNG for speed - -### TypeScript - -- Lazy load WASM module -- Debounce frequent operations -- Use `chrome.alarms` instead of `setInterval` -- Batch storage operations - -### Extension Size - -Current optimizations: -- Rust compiled with `opt-level = "z"` (optimize for size) -- LTO enabled for smaller binaries -- Dead code elimination via tree-shaking - -## Architecture Decisions - -### Why Rust + TypeScript? - -- **Rust**: Memory safety, performance, complex logic -- **TypeScript**: Browser API integration, UI, async operations -- **WASM**: Bridge between them - -### Storage Design - -- Uses `chrome.storage.local` for persistence -- Profile data stored separately from activity history -- Statistics updated incrementally -- Activity history capped at 1000 entries - -### Activity Simulation - -- Poisson distribution for realistic timing -- Profile-based URL generation -- Schedule-aware execution -- Configurable noise levels - -## Contributing - -See `CONTRIBUTING.md` for contribution guidelines. - -### Code Style - -**Rust:** -- Follow Rust standard style (`rustfmt`) -- Document public APIs -- Write tests for new features - -**TypeScript:** -- Use ESLint configuration -- Prefer `async/await` over callbacks -- Type everything (no `any`) - -## Release Process - -1. Update version in `package.json` and `Cargo.toml` -2. Update `CHANGELOG.md` -3. Run full test suite -4. Build production version -5. Test loaded extension thoroughly -6. Create git tag -7. Build distribution package -8. Submit to Chrome Web Store / Firefox Add-ons - -## Resources - -- [Manifest V3 Documentation](https://developer.chrome.com/docs/extensions/mv3/) -- [WebAssembly Guide](https://rustwasm.github.io/docs/book/) -- [wasm-pack Documentation](https://rustwasm.github.io/wasm-pack/) -- [Rust WebExtensions Example](https://github.com/rustwasm/wasm-bindgen) - -## Getting Help - -- Check existing issues on GitHub -- Read CLAUDE.md for AI assistant context -- Review inline code comments -- Consult browser extension documentation diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/LICENSING.adoc b/LICENSING.adoc new file mode 100644 index 0000000..6896254 --- /dev/null +++ b/LICENSING.adoc @@ -0,0 +1,90 @@ +== Licensing Information + +=== Dual License + +DoubleTrack Browser is dual-licensed under: + +[arabic] +. *MIT License* (primary, for maximum compatibility) +. *Palimpsest License v0.8* (alternative, for RSR compliance) + +You may choose either license when using, modifying, or distributing +this software. + +=== Why Dual License? + +* *MIT*: Permissive, widely understood, maximum compatibility with other +projects +* *Palimpsest v0.8*: Supports reversibility principles and RSR Framework +goals + +=== License Texts + +* MIT License: See LICENSE-MIT +* Palimpsest License v0.8: See LICENSE-PALIMPSEST +* Historical GPL-3.0: See LICENSE (retained for historical purposes) + +=== How to Choose + +==== Use MIT if you want: + +* Maximum compatibility +* Simple, well-understood terms +* No additional obligations +* Commercial use without restrictions + +==== Use Palimpsest v0.8 if you want: + +* Support for reversibility principles +* Alignment with RSR Framework values +* Recognition of emotional safety in software development + +=== For Contributors + +By contributing to this project, you agree that your contributions will +be licensed under the same dual license (MIT + Palimpsest v0.8). + +=== For Users + +When using this software: 1. Choose which license you prefer (MIT or +Palimpsest v0.8) 2. Include the appropriate LICENSE file with your +distribution 3. Provide attribution as specified in your chosen license + +=== Clarifications + +*Q: Can I mix and match terms from both licenses?* A: No. Choose one +license and follow its terms entirely. + +*Q: What if I’m unsure which to use?* A: MIT is the simpler, more widely +understood option. Use MIT unless you specifically need Palimpsest v0.8. + +*Q: Can I relicense under just one license?* A: If you redistribute our +code, you must offer the same dual license. Derivative works may choose +stricter terms compatible with your chosen license. + +*Q: What about the GPL-3.0 LICENSE file?* A: That was the original +license. As of v0.1.1, the project has transitioned to MIT + Palimpsest +v0.8 dual licensing. The GPL-3.0 file is retained for historical +reference but is no longer the active license. + +=== SPDX License Identifiers + +When adding headers to source files, use: + +.... +// SPDX-License-Identifier: CC-BY-SA-4.0 +.... + +Or for individual file choice: + +.... +// SPDX-License-Identifier: CC-BY-SA-4.0 +.... + +=== Questions? + +Contact: legal@example.com + +''''' + +*Effective Date*: 2025-11-22 *Version*: 1.0 *Last Updated*: 2025-11-22 diff --git a/LICENSING.md b/LICENSING.md deleted file mode 100644 index 5cebb35..0000000 --- a/LICENSING.md +++ /dev/null @@ -1,83 +0,0 @@ -# Licensing Information - -## Dual License - -DoubleTrack Browser is dual-licensed under: - -1. **MIT License** (primary, for maximum compatibility) -2. **Palimpsest License v0.8** (alternative, for RSR compliance) - -You may choose either license when using, modifying, or distributing this software. - -## Why Dual License? - -- **MIT**: Permissive, widely understood, maximum compatibility with other projects -- **Palimpsest v0.8**: Supports reversibility principles and RSR Framework goals - -## License Texts - -- MIT License: See [LICENSE-MIT](LICENSE-MIT) -- Palimpsest License v0.8: See [LICENSE-PALIMPSEST](LICENSE-PALIMPSEST) -- Historical GPL-3.0: See [LICENSE](LICENSE) (retained for historical purposes) - -## How to Choose - -### Use MIT if you want: -- Maximum compatibility -- Simple, well-understood terms -- No additional obligations -- Commercial use without restrictions - -### Use Palimpsest v0.8 if you want: -- Support for reversibility principles -- Alignment with RSR Framework values -- Recognition of emotional safety in software development - -## For Contributors - -By contributing to this project, you agree that your contributions will be licensed under the same dual license (MIT + Palimpsest v0.8). - -## For Users - -When using this software: -1. Choose which license you prefer (MIT or Palimpsest v0.8) -2. Include the appropriate LICENSE file with your distribution -3. Provide attribution as specified in your chosen license - -## Clarifications - -**Q: Can I mix and match terms from both licenses?** -A: No. Choose one license and follow its terms entirely. - -**Q: What if I'm unsure which to use?** -A: MIT is the simpler, more widely understood option. Use MIT unless you specifically need Palimpsest v0.8. - -**Q: Can I relicense under just one license?** -A: If you redistribute our code, you must offer the same dual license. Derivative works may choose stricter terms compatible with your chosen license. - -**Q: What about the GPL-3.0 LICENSE file?** -A: That was the original license. As of v0.1.1, the project has transitioned to MIT + Palimpsest v0.8 dual licensing. The GPL-3.0 file is retained for historical reference but is no longer the active license. - -## SPDX License Identifiers - -When adding headers to source files, use: - -``` -// SPDX-License-Identifier: CC-BY-SA-4.0 -``` - -Or for individual file choice: - -``` -// SPDX-License-Identifier: CC-BY-SA-4.0 -``` - -## Questions? - -Contact: legal@example.com - ---- - -**Effective Date**: 2025-11-22 -**Version**: 1.0 -**Last Updated**: 2025-11-22 diff --git a/MAINTAINERS.adoc b/MAINTAINERS.adoc index 48d9781..f8f8ae9 100644 --- a/MAINTAINERS.adoc +++ b/MAINTAINERS.adoc @@ -1,47 +1,186 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +This document lists the individuals responsible for the DoubleTrack +Browser project and defines the governance structure. -== Current Maintainers +=== Current Maintainers -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact +==== Core Stewards (Perimeter 1) -| Jonathan D.A. Jewell -| Lead Maintainer -| https://github.com/hyperpolymath[@hyperpolymath] +[width="100%",cols="16%,14%,19%,17%,17%,17%",options="header",] +|=== +|Name |Role |GitHub |Email |Areas |Since +|[Your Name] |Lead Maintainer |@yourusername |you@example.com |All +|2025-11 |=== -== Responsibilities +*Responsibilities*: - Final decision authority on project direction - +Security incident response - Release management - Community moderation - +TPCF perimeter management + +==== Trusted Contributors (Perimeter 2) + +_None currently - perimeter not yet activated_ + +*Path to Perimeter 2*: 1. Sustained contributions over 3+ months 2. 10+ +merged PRs of substance 3. Active participation in discussions 4. +Demonstrated understanding of project goals 5. Nomination by existing P1 +steward 6. Unanimous approval by all P1 stewards + +*Responsibilities* (when activated): - Code review privileges - Triage +issues and PRs - Mentor newcomers - Shape project roadmap + +=== Governance Model + +==== Decision-Making Process + +*Type A: Routine Decisions* (bugs, docs, refactoring) - Any maintainer +can merge after review - 24-hour minimum for review window - LGTM from +one P1 steward required + +*Type B: Feature Decisions* (new capabilities, API changes) - Discussion +in GitHub issue first - 72-hour minimum discussion period - LGTM from +majority of P1 stewards - Lead maintainer has veto power + +*Type C: Governance Decisions* (CoC, license, TPCF changes) - Public RFC +process required - 2-week minimum discussion period - Unanimous approval +by all P1 stewards - Community input strongly considered + +==== Conflict Resolution + +[arabic] +. *Direct Communication*: Parties attempt to resolve privately +. *Mediation*: Neutral P1 steward mediates if needed +. *Lead Decision*: Lead maintainer makes final call if unresolved +. *Fork Option*: Dissenting parties may fork under MIT terms + +==== Succession Planning + +*If Lead Maintainer Steps Down*: 1. 30-day notice preferred (not +required) 2. Existing P1 stewards elect new lead 3. If no P1 stewards +remain, most senior P2 contributor promoted 4. If project abandoned, MIT +license permits forking + +*Adding New Core Stewards*: - Requires unanimous approval of existing P1 +stewards - Minimum 12 months as P2 contributor - Demonstrated commitment +to project values - Invitation-only, not requested + +=== Perimeter Management + +==== Current Status: Perimeter 3 Only + +*Rationale*: Project is in initial development phase. TPCF Perimeters 1 +and 2 are designed but not yet activated. All contributors currently +operate in Perimeter 3 (Community Sandbox). + +==== Activation Criteria + +*Perimeter 2 Activation Triggers*: - Project has 50+ stars on GitHub - +10+ external contributors - 100+ merged PRs - First stable release +(v1.0.0) + +*Perimeter 1 Expansion Triggers*: - Project has 500+ stars on GitHub - +3+ sustained P2 contributors (12+ months) - Security audit completed - +Lead maintainer needs delegation + +=== Time Commitments + +==== Expected Availability + +*P1 Stewards*: - Check GitHub 2-3x per week minimum - Respond to +security issues within 48 hours - Review PRs within 1 week - Participate +in monthly sync (when P2 activated) + +*P2 Contributors* (when activated): - Check GitHub 1x per week - Review +assigned PRs within 2 weeks - Optional participation in discussions + +==== Stepping Down + +Maintainers may step down at any time by: 1. Notifying other maintainers +(private or public) 2. Opening a PR to remove themselves from this file +3. No justification required + +*Emeritus Status*: Former maintainers are honored in CONTRIBUTORS.md +(when created) and retain community respect. + +=== Contact Information + +==== Public Channels + +* *GitHub Issues*: +https://github.com/yourusername/double-track-browser/issues +* *Discussions*: +https://github.com/yourusername/double-track-browser/discussions +* *Email*: maintainers@example.com (public list) + +==== Private Channels + +* *Security*: security@example.com (see SECURITY.md) +* *Code of Conduct*: conduct@example.com (see CODE_OF_CONDUCT.md) +* *Governance*: governance@example.com (for TPCF perimeter requests) + +=== Responsibilities + +==== What Maintainers Do + +✅ *Do*: - Review and merge pull requests - Triage and respond to issues +- Maintain project infrastructure - Coordinate releases - Enforce Code +of Conduct - Protect user privacy - Foster welcoming community + +❌ *Don’t*: - Guarantee response times (best effort only) - Provide free +consulting - Owe anyone explanations for decisions - Sacrifice mental +health for the project + +==== What Contributors Should Expect + +*You Can Expect*: - Respectful, professional communication - Fair review +of contributions - Transparency in decision-making - Adherence to Code +of Conduct - Acknowledgment in release notes + +*You Should Not Expect*: - Immediate responses - Acceptance of all PRs - +Custom features on demand - Detailed justifications for every decision - +Unpaid labor from maintainers + +=== Maintainer Onboarding (Future) -Maintainers are responsible for: +When promoting to P2 or P1: -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +[arabic] +. *Access Grants*: +* GitHub team membership +* NPM publish rights (P1 only) +* Signing keys for releases (P1 only) +* Email list access +. *Knowledge Transfer*: +* Read all documentation +* Shadow current maintainer for 1 month +* Pair on 3+ PR reviews +* Learn release process +. *First Tasks*: +* Update MAINTAINERS.md (this file) +* Introduce yourself in Discussions +* Set up GPG signing key +* Review CONTRIBUTING.md -== Becoming a Maintainer +=== Recognition -Contributors who demonstrate: +Maintainers volunteer their time and expertise. The community thanks +them by: - Being respectful and patient - Following contribution +guidelines - Helping other users - Spreading the word about the project +- Sending encouraging messages - Buying them coffee ☕ (optional): +[TODO: Sponsor link] -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +=== Amendment Process -May be invited to become maintainers at the discretion of existing maintainers. +This document is a living guide and may be updated by: 1. Opening a PR +with proposed changes 2. Discussion period of 1 week minimum 3. Approval +by majority of P1 stewards 4. Merge and announce in release notes -== Decision Making +''''' -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +*Version*: 1.0 *Last Updated*: 2025-11-22 *Next Review*: 2026-05-22 (6 +months) -== Contact +''''' -For questions about project governance, open an issue or contact the maintainers listed above. +Thank you to all current and future maintainers for your stewardship! 🙏 diff --git a/MAINTAINERS.md b/MAINTAINERS.md deleted file mode 100644 index 5c9663f..0000000 --- a/MAINTAINERS.md +++ /dev/null @@ -1,221 +0,0 @@ -# Maintainers - -This document lists the individuals responsible for the DoubleTrack Browser project and defines the governance structure. - -## Current Maintainers - -### Core Stewards (Perimeter 1) - -| Name | Role | GitHub | Email | Areas | Since | -|------|------|--------|-------|-------|-------| -| [Your Name] | Lead Maintainer | @yourusername | you@example.com | All | 2025-11 | - -**Responsibilities**: -- Final decision authority on project direction -- Security incident response -- Release management -- Community moderation -- TPCF perimeter management - -### Trusted Contributors (Perimeter 2) - -*None currently - perimeter not yet activated* - -**Path to Perimeter 2**: -1. Sustained contributions over 3+ months -2. 10+ merged PRs of substance -3. Active participation in discussions -4. Demonstrated understanding of project goals -5. Nomination by existing P1 steward -6. Unanimous approval by all P1 stewards - -**Responsibilities** (when activated): -- Code review privileges -- Triage issues and PRs -- Mentor newcomers -- Shape project roadmap - -## Governance Model - -### Decision-Making Process - -**Type A: Routine Decisions** (bugs, docs, refactoring) -- Any maintainer can merge after review -- 24-hour minimum for review window -- LGTM from one P1 steward required - -**Type B: Feature Decisions** (new capabilities, API changes) -- Discussion in GitHub issue first -- 72-hour minimum discussion period -- LGTM from majority of P1 stewards -- Lead maintainer has veto power - -**Type C: Governance Decisions** (CoC, license, TPCF changes) -- Public RFC process required -- 2-week minimum discussion period -- Unanimous approval by all P1 stewards -- Community input strongly considered - -### Conflict Resolution - -1. **Direct Communication**: Parties attempt to resolve privately -2. **Mediation**: Neutral P1 steward mediates if needed -3. **Lead Decision**: Lead maintainer makes final call if unresolved -4. **Fork Option**: Dissenting parties may fork under MIT terms - -### Succession Planning - -**If Lead Maintainer Steps Down**: -1. 30-day notice preferred (not required) -2. Existing P1 stewards elect new lead -3. If no P1 stewards remain, most senior P2 contributor promoted -4. If project abandoned, MIT license permits forking - -**Adding New Core Stewards**: -- Requires unanimous approval of existing P1 stewards -- Minimum 12 months as P2 contributor -- Demonstrated commitment to project values -- Invitation-only, not requested - -## Perimeter Management - -### Current Status: Perimeter 3 Only - -**Rationale**: Project is in initial development phase. TPCF Perimeters 1 and 2 are designed but not yet activated. All contributors currently operate in Perimeter 3 (Community Sandbox). - -### Activation Criteria - -**Perimeter 2 Activation Triggers**: -- Project has 50+ stars on GitHub -- 10+ external contributors -- 100+ merged PRs -- First stable release (v1.0.0) - -**Perimeter 1 Expansion Triggers**: -- Project has 500+ stars on GitHub -- 3+ sustained P2 contributors (12+ months) -- Security audit completed -- Lead maintainer needs delegation - -## Time Commitments - -### Expected Availability - -**P1 Stewards**: -- Check GitHub 2-3x per week minimum -- Respond to security issues within 48 hours -- Review PRs within 1 week -- Participate in monthly sync (when P2 activated) - -**P2 Contributors** (when activated): -- Check GitHub 1x per week -- Review assigned PRs within 2 weeks -- Optional participation in discussions - -### Stepping Down - -Maintainers may step down at any time by: -1. Notifying other maintainers (private or public) -2. Opening a PR to remove themselves from this file -3. No justification required - -**Emeritus Status**: Former maintainers are honored in CONTRIBUTORS.md (when created) and retain community respect. - -## Contact Information - -### Public Channels - -- **GitHub Issues**: https://github.com/yourusername/double-track-browser/issues -- **Discussions**: https://github.com/yourusername/double-track-browser/discussions -- **Email**: maintainers@example.com (public list) - -### Private Channels - -- **Security**: security@example.com (see SECURITY.md) -- **Code of Conduct**: conduct@example.com (see CODE_OF_CONDUCT.md) -- **Governance**: governance@example.com (for TPCF perimeter requests) - -## Responsibilities - -### What Maintainers Do - -✅ **Do**: -- Review and merge pull requests -- Triage and respond to issues -- Maintain project infrastructure -- Coordinate releases -- Enforce Code of Conduct -- Protect user privacy -- Foster welcoming community - -❌ **Don't**: -- Guarantee response times (best effort only) -- Provide free consulting -- Owe anyone explanations for decisions -- Sacrifice mental health for the project - -### What Contributors Should Expect - -**You Can Expect**: -- Respectful, professional communication -- Fair review of contributions -- Transparency in decision-making -- Adherence to Code of Conduct -- Acknowledgment in release notes - -**You Should Not Expect**: -- Immediate responses -- Acceptance of all PRs -- Custom features on demand -- Detailed justifications for every decision -- Unpaid labor from maintainers - -## Maintainer Onboarding (Future) - -When promoting to P2 or P1: - -1. **Access Grants**: - - GitHub team membership - - NPM publish rights (P1 only) - - Signing keys for releases (P1 only) - - Email list access - -2. **Knowledge Transfer**: - - Read all documentation - - Shadow current maintainer for 1 month - - Pair on 3+ PR reviews - - Learn release process - -3. **First Tasks**: - - Update MAINTAINERS.md (this file) - - Introduce yourself in Discussions - - Set up GPG signing key - - Review CONTRIBUTING.md - -## Recognition - -Maintainers volunteer their time and expertise. The community thanks them by: -- Being respectful and patient -- Following contribution guidelines -- Helping other users -- Spreading the word about the project -- Sending encouraging messages -- Buying them coffee ☕ (optional): [TODO: Sponsor link] - -## Amendment Process - -This document is a living guide and may be updated by: -1. Opening a PR with proposed changes -2. Discussion period of 1 week minimum -3. Approval by majority of P1 stewards -4. Merge and announce in release notes - ---- - -**Version**: 1.0 -**Last Updated**: 2025-11-22 -**Next Review**: 2026-05-22 (6 months) - ---- - -Thank you to all current and future maintainers for your stewardship! 🙏 diff --git a/PROJECT_SUMMARY.adoc b/PROJECT_SUMMARY.adoc new file mode 100644 index 0000000..edea269 --- /dev/null +++ b/PROJECT_SUMMARY.adoc @@ -0,0 +1,362 @@ +== DoubleTrack Browser - Project Summary + +=== Overview + +DoubleTrack Browser is a fully-functional browser extension that +explores unconventional privacy protection through deliberate noise +generation. Instead of hiding user data, it creates believable fictional +browsing patterns to obscure real activity from tracking systems. + +*Status*: Complete, functional prototype ready for testing and further +development + +=== What Was Built + +==== Core Architecture + +===== 1. Rust/WebAssembly Core (`+rust_core/+`) + +*Files*: 6 Rust modules, 1 Cargo configuration *Lines of Code*: ~1,200 +lines + +*Modules*: - `+lib.rs+` - WASM bindings and public API (80 lines) - +`+profile.rs+` - Profile generation with demographics and interests (400 +lines) - `+activity.rs+` - Activity simulation engine (200 lines) - +`+interests.rs+` - URL and content generation (300 lines) - +`+schedule.rs+` - Time-based activity scheduling (150 lines) - +`+tests/integration_tests.rs+` - Comprehensive test suite (450 lines) + +*Features*: - Deterministic profile generation with optional seeding - 9 +occupation categories, 5 education levels - 20+ interest categories - 4 +browsing styles (Focused, Explorer, Researcher, Casual) - 4 activity +levels (Low to VeryHigh) - 7 activity types with realistic URL +generation - Schedule generation based on occupation and lifestyle - +Compiled to WebAssembly for browser integration + +===== 2. TypeScript Browser Extension (`+src/+`) + +*Files*: 15 TypeScript modules, 6 HTML pages, 6 CSS stylesheets *Lines +of Code*: ~3,500 lines + +*Structure*: + +.... +src/ +├── background/ # Service worker for activity simulation +├── popup/ # Quick-access UI +├── options/ # Full settings page +├── dashboard/ # Analytics and visualization +├── content/ # Content script for page integration +├── types/ # TypeScript type definitions +├── utils/ # Storage and WASM utilities +└── manifest.json # Extension configuration +.... + +*Components*: + +[arabic] +. *Background Service Worker* (300 lines) +* Activity simulation orchestration +* Alarm-based scheduling +* Message handling for UI communication +* Profile and statistics management +. *Popup UI* (HTML + CSS + TS: 500 lines) +* Extension enable/disable toggle +* Profile information display +* Quick statistics overview +* Noise level and schedule controls +. *Options Page* (HTML + CSS + TS: 700 lines) +* Comprehensive settings interface +* Profile generation and export +* Activity history viewer +* Privacy mode selection +* Statistics dashboard access +. *Analytics Dashboard* (HTML + CSS + TS: 1,100 lines) +* Canvas-based visualizations (no external charting libraries) +* 7-day activity timeline (bar chart) +* Activity type distribution (pie chart) +* Hourly pattern analysis (line chart) +* Interest category bars +* Weekly heatmap (GitHub-style) +* Recent activities list +* Profile insights generation +. *Utilities* (400 lines) +* `+storage.ts+` - Chrome storage API wrapper +* `+wasm.ts+` - Rust/WASM interface layer +* Type-safe data management +* Activity history trimming (1000-item limit) +. *Content Script* (50 lines) +* Page-level integration stub +* Future privacy safeguards +* Message passing interface + +==== Documentation + +*Total*: 7 comprehensive documents, ~5,000 lines + +[arabic] +. *README.md* - User-facing overview and philosophy +. *CLAUDE.md* - AI assistant development context +. *DEVELOPMENT.md* - Complete development guide with troubleshooting +. *CONTRIBUTING.md* - Contribution guidelines and code standards +. *CHANGELOG.md* - Version history and migration guide +. *QUICKSTART.md* - 5-minute getting started guide +. *PROJECT_SUMMARY.md* - This document + +==== Build System + +*Tools*: Webpack 5, TypeScript 5, wasm-pack, ESLint, Jest + +*Configuration Files*: - `+package.json+` - Dependencies and scripts - +`+tsconfig.json+` - TypeScript strict mode configuration - +`+webpack.config.js+` - Multi-entry build with WASM support - +`+.eslintrc.json+` - Linting rules - `+jest.config.js+` - Test +configuration + +*Scripts*: - `+build+` - Full build (Rust + TypeScript) - `+build:rust+` +- Rust/WASM only - `+build:extension+` - TypeScript only - `+dev+` - +Watch mode for development - `+test+` - Run all tests - `+lint+` - Code +linting - `+type-check+` - TypeScript validation + +==== Testing + +*Coverage*: 27 comprehensive tests + +*Rust Tests* (15 tests): - Profile generation determinism - Activity +simulation correctness - Schedule validation - URL format checking - +Duration reasonableness - Timestamp ordering - Age and occupation +distributions - Browsing style variety + +*TypeScript Tests* (12 tests): - Storage management - Configuration +persistence - Statistics tracking - Activity history management - +Profile age calculation - Daily reset functionality - Mock Chrome API +integration + +==== Resources + +*Icons*: - SVG template with double-track design - Placeholder +instructions - Icon generation script + +*Scripts*: - `+scripts/build.sh+` - Automated build with prerequisite +checking - `+scripts/generate-icons.sh+` - Icon generation helper + +=== Features Implemented + +==== Profile System + +✅ Deterministic profile generation ✅ Demographics (age, gender, +location, occupation, education) ✅ 20+ interest categories ✅ 4 +browsing styles ✅ 4 activity levels ✅ Age-appropriate and +occupation-correlated interests ✅ Profile validation ✅ Profile export +to JSON + +==== Activity Simulation + +✅ 7 activity types (Search, PageVisit, VideoWatch, Shopping, +SocialMedia, News, Research) ✅ Realistic URL generation for major sites +✅ Duration distributions by activity type ✅ Interest-correlated +content ✅ Timestamp ordering and distribution ✅ Poisson-inspired +timing patterns + +==== Scheduling + +✅ Occupation-based activity schedules ✅ Weekday vs. weekend patterns +✅ Hour-based active periods ✅ Activity intensity modulation ✅ +Schedule-aware simulation + +==== User Interface + +✅ Modern gradient design ✅ Responsive layouts ✅ Real-time statistics +✅ Interactive visualizations ✅ Empty state handling ✅ Loading states +✅ Error handling + +==== Data Management + +✅ Local storage persistence ✅ Activity history (1000-item limit) ✅ +Statistics tracking ✅ Daily reset functionality ✅ Profile age +calculation ✅ Data export functionality + +==== Privacy & Security + +✅ All data stored locally ✅ No external API calls ✅ Separate storage +for real vs. simulated data ✅ Configurable privacy modes ✅ Activity +can be disabled instantly + +==== Analytics Dashboard + +✅ Overview statistics cards ✅ 7-day timeline chart ✅ Activity type +pie chart ✅ Hourly pattern line chart ✅ Interest distribution bars ✅ +Weekly activity heatmap ✅ Recent activities list ✅ Profile insights +generation + +=== Technical Achievements + +==== Architecture + +* *Hybrid Rust/TypeScript*: Leverages strengths of both languages +* *WASM Integration*: High-performance core compiled to WebAssembly +* *Type Safety*: Strict TypeScript with comprehensive type definitions +* *Modular Design*: Clean separation of concerns +* *Manifest V3*: Uses latest Chrome extension standard + +==== Performance + +* *Optimized WASM*: Size-optimized Rust compilation +* *Lazy Loading*: WASM module loaded on demand +* *Efficient Storage*: 1000-item activity cap prevents bloat +* *Canvas Rendering*: Custom charts without heavy dependencies +* *Alarm-based Scheduling*: Efficient background operation + +==== Code Quality + +* *27 Tests*: Comprehensive test coverage +* *Linting*: ESLint for TypeScript consistency +* *Type Checking*: Strict TypeScript mode +* *Documentation*: Inline JSDoc and doc comments +* *Error Handling*: Try-catch blocks and user feedback + +=== Project Statistics + +*Total Lines of Code*: ~6,000 lines - Rust: ~1,200 lines - TypeScript: +~3,500 lines - Tests: ~1,000 lines - Documentation: ~5,000 lines + +*Files Created*: ~50 files - Rust: 6 modules - TypeScript: 15 modules - +HTML/CSS: 12 files - Config: 6 files - Documentation: 7 files - Scripts: +2 files - Tests: 2 test files + +*Commits*: 7 meaningful commits with detailed messages + +*Functionality*: - ✅ 100% of planned core features - ✅ Comprehensive +documentation - ✅ Full test coverage - ✅ Analytics dashboard - ✅ +Build automation - ✅ Getting started guide + +=== What Works + +✅ *Profile Generation*: Creates realistic, consistent fictional +personas ✅ *Activity Simulation*: Generates believable browsing +patterns ✅ *Storage System*: Persists all data locally ✅ *Background +Worker*: Schedules and simulates activities ✅ *UI Components*: All +interfaces functional and responsive ✅ *Analytics*: Complete +visualization dashboard ✅ *Build System*: Automated build process ✅ +*Testing*: All tests pass + +=== What Needs Work + +==== To Complete + +[arabic] +. *WASM Integration*: Currently using mock implementations +* Need to properly load compiled WASM module +* Wire up actual Rust function calls +* Test WASM boundary performance +. *Icons*: Using placeholders +* Design professional icons +* Create all required sizes (16, 32, 48, 128) +* Match extension branding +. *Tab Opening*: Currently disabled for safety +* Uncomment tab creation code if desired +* Add user confirmation dialogs +* Implement tab cleanup logic + +==== Nice to Have + +* Profile templates (pre-made personas) +* Multiple profile support +* Import/export settings +* Activity pattern visualization improvements +* Browser history integration (read actual patterns) +* Machine learning for pattern improvement +* Cross-browser synchronization +* Localization/i18n + +=== How to Use + +==== For Users + +[arabic] +. Follow QUICKSTART.md +. Generate a profile +. Enable the extension +. View analytics in dashboard + +==== For Developers + +[arabic] +. Read DEVELOPMENT.md +. Set up prerequisites +. Run `+npm install && npm run build+` +. Load in browser +. Check CONTRIBUTING.md for guidelines + +=== Success Metrics + +✅ *Completeness*: All core features implemented ✅ *Quality*: +Comprehensive testing and documentation ✅ *Usability*: Clean UI with +good UX ✅ *Maintainability*: Well-structured, documented code ✅ +*Extensibility*: Modular architecture for future additions + +=== Value Delivered + +This project provides: 1. *Functional prototype* ready for testing 2. +*Complete codebase* with modern best practices 3. *Comprehensive +documentation* for users and developers 4. *Test suite* ensuring +correctness 5. *Build system* for easy compilation 6. *Clear roadmap* +for future development + +=== Next Steps for Production + +[arabic] +. *Complete WASM Integration* +* Load actual compiled module +* Test performance +* Benchmark vs. mock implementation +. *Design Assets* +* Create professional icons +* Add branding +* Polish UI elements +. *User Testing* +* Beta testing program +* Gather feedback +* Iterate on UX +. *Performance Optimization* +* Profile memory usage +* Optimize background worker +* Reduce bundle size +. *Security Audit* +* Review privacy guarantees +* Test data separation +* Verify no leakage +. *Browser Compatibility* +* Test on Firefox +* Test on Edge +* Handle browser-specific APIs +. *Distribution* +* Prepare for Chrome Web Store +* Create Firefox add-on listing +* Set up update mechanism + +=== Conclusion + +DoubleTrack Browser is a complete, functional browser extension +exploring privacy through noise generation. With ~6,000 lines of code +across Rust and TypeScript, comprehensive documentation, a full test +suite, and modern build tooling, it’s ready for further development and +testing. + +The project demonstrates: - Strong architectural design (Rust + +TypeScript + WASM) - Comprehensive feature implementation - Excellent +documentation practices - Professional code quality - Clear development +roadmap + +*All core functionality is implemented and working.* The main remaining +tasks are WASM integration finalization, icon design, and production +hardening. + +''''' + +*Built with*: Rust, TypeScript, WebAssembly, Chrome Extensions API, +HTML5 Canvas + +*License*: MIT + +*Status*: ✅ Functional Prototype Complete diff --git a/PROJECT_SUMMARY.md b/PROJECT_SUMMARY.md deleted file mode 100644 index ea6a654..0000000 --- a/PROJECT_SUMMARY.md +++ /dev/null @@ -1,401 +0,0 @@ -# DoubleTrack Browser - Project Summary - -## Overview - -DoubleTrack Browser is a fully-functional browser extension that explores unconventional privacy protection through deliberate noise generation. Instead of hiding user data, it creates believable fictional browsing patterns to obscure real activity from tracking systems. - -**Status**: Complete, functional prototype ready for testing and further development - -## What Was Built - -### Core Architecture - -#### 1. Rust/WebAssembly Core (`rust_core/`) - -**Files**: 6 Rust modules, 1 Cargo configuration -**Lines of Code**: ~1,200 lines - -**Modules**: -- `lib.rs` - WASM bindings and public API (80 lines) -- `profile.rs` - Profile generation with demographics and interests (400 lines) -- `activity.rs` - Activity simulation engine (200 lines) -- `interests.rs` - URL and content generation (300 lines) -- `schedule.rs` - Time-based activity scheduling (150 lines) -- `tests/integration_tests.rs` - Comprehensive test suite (450 lines) - -**Features**: -- Deterministic profile generation with optional seeding -- 9 occupation categories, 5 education levels -- 20+ interest categories -- 4 browsing styles (Focused, Explorer, Researcher, Casual) -- 4 activity levels (Low to VeryHigh) -- 7 activity types with realistic URL generation -- Schedule generation based on occupation and lifestyle -- Compiled to WebAssembly for browser integration - -#### 2. TypeScript Browser Extension (`src/`) - -**Files**: 15 TypeScript modules, 6 HTML pages, 6 CSS stylesheets -**Lines of Code**: ~3,500 lines - -**Structure**: -``` -src/ -├── background/ # Service worker for activity simulation -├── popup/ # Quick-access UI -├── options/ # Full settings page -├── dashboard/ # Analytics and visualization -├── content/ # Content script for page integration -├── types/ # TypeScript type definitions -├── utils/ # Storage and WASM utilities -└── manifest.json # Extension configuration -``` - -**Components**: - -1. **Background Service Worker** (300 lines) - - Activity simulation orchestration - - Alarm-based scheduling - - Message handling for UI communication - - Profile and statistics management - -2. **Popup UI** (HTML + CSS + TS: 500 lines) - - Extension enable/disable toggle - - Profile information display - - Quick statistics overview - - Noise level and schedule controls - -3. **Options Page** (HTML + CSS + TS: 700 lines) - - Comprehensive settings interface - - Profile generation and export - - Activity history viewer - - Privacy mode selection - - Statistics dashboard access - -4. **Analytics Dashboard** (HTML + CSS + TS: 1,100 lines) - - Canvas-based visualizations (no external charting libraries) - - 7-day activity timeline (bar chart) - - Activity type distribution (pie chart) - - Hourly pattern analysis (line chart) - - Interest category bars - - Weekly heatmap (GitHub-style) - - Recent activities list - - Profile insights generation - -5. **Utilities** (400 lines) - - `storage.ts` - Chrome storage API wrapper - - `wasm.ts` - Rust/WASM interface layer - - Type-safe data management - - Activity history trimming (1000-item limit) - -6. **Content Script** (50 lines) - - Page-level integration stub - - Future privacy safeguards - - Message passing interface - -### Documentation - -**Total**: 7 comprehensive documents, ~5,000 lines - -1. **README.md** - User-facing overview and philosophy -2. **CLAUDE.md** - AI assistant development context -3. **DEVELOPMENT.md** - Complete development guide with troubleshooting -4. **CONTRIBUTING.md** - Contribution guidelines and code standards -5. **CHANGELOG.md** - Version history and migration guide -6. **QUICKSTART.md** - 5-minute getting started guide -7. **PROJECT_SUMMARY.md** - This document - -### Build System - -**Tools**: Webpack 5, TypeScript 5, wasm-pack, ESLint, Jest - -**Configuration Files**: -- `package.json` - Dependencies and scripts -- `tsconfig.json` - TypeScript strict mode configuration -- `webpack.config.js` - Multi-entry build with WASM support -- `.eslintrc.json` - Linting rules -- `jest.config.js` - Test configuration - -**Scripts**: -- `build` - Full build (Rust + TypeScript) -- `build:rust` - Rust/WASM only -- `build:extension` - TypeScript only -- `dev` - Watch mode for development -- `test` - Run all tests -- `lint` - Code linting -- `type-check` - TypeScript validation - -### Testing - -**Coverage**: 27 comprehensive tests - -**Rust Tests** (15 tests): -- Profile generation determinism -- Activity simulation correctness -- Schedule validation -- URL format checking -- Duration reasonableness -- Timestamp ordering -- Age and occupation distributions -- Browsing style variety - -**TypeScript Tests** (12 tests): -- Storage management -- Configuration persistence -- Statistics tracking -- Activity history management -- Profile age calculation -- Daily reset functionality -- Mock Chrome API integration - -### Resources - -**Icons**: -- SVG template with double-track design -- Placeholder instructions -- Icon generation script - -**Scripts**: -- `scripts/build.sh` - Automated build with prerequisite checking -- `scripts/generate-icons.sh` - Icon generation helper - -## Features Implemented - -### Profile System -✅ Deterministic profile generation -✅ Demographics (age, gender, location, occupation, education) -✅ 20+ interest categories -✅ 4 browsing styles -✅ 4 activity levels -✅ Age-appropriate and occupation-correlated interests -✅ Profile validation -✅ Profile export to JSON - -### Activity Simulation -✅ 7 activity types (Search, PageVisit, VideoWatch, Shopping, SocialMedia, News, Research) -✅ Realistic URL generation for major sites -✅ Duration distributions by activity type -✅ Interest-correlated content -✅ Timestamp ordering and distribution -✅ Poisson-inspired timing patterns - -### Scheduling -✅ Occupation-based activity schedules -✅ Weekday vs. weekend patterns -✅ Hour-based active periods -✅ Activity intensity modulation -✅ Schedule-aware simulation - -### User Interface -✅ Modern gradient design -✅ Responsive layouts -✅ Real-time statistics -✅ Interactive visualizations -✅ Empty state handling -✅ Loading states -✅ Error handling - -### Data Management -✅ Local storage persistence -✅ Activity history (1000-item limit) -✅ Statistics tracking -✅ Daily reset functionality -✅ Profile age calculation -✅ Data export functionality - -### Privacy & Security -✅ All data stored locally -✅ No external API calls -✅ Separate storage for real vs. simulated data -✅ Configurable privacy modes -✅ Activity can be disabled instantly - -### Analytics Dashboard -✅ Overview statistics cards -✅ 7-day timeline chart -✅ Activity type pie chart -✅ Hourly pattern line chart -✅ Interest distribution bars -✅ Weekly activity heatmap -✅ Recent activities list -✅ Profile insights generation - -## Technical Achievements - -### Architecture -- **Hybrid Rust/TypeScript**: Leverages strengths of both languages -- **WASM Integration**: High-performance core compiled to WebAssembly -- **Type Safety**: Strict TypeScript with comprehensive type definitions -- **Modular Design**: Clean separation of concerns -- **Manifest V3**: Uses latest Chrome extension standard - -### Performance -- **Optimized WASM**: Size-optimized Rust compilation -- **Lazy Loading**: WASM module loaded on demand -- **Efficient Storage**: 1000-item activity cap prevents bloat -- **Canvas Rendering**: Custom charts without heavy dependencies -- **Alarm-based Scheduling**: Efficient background operation - -### Code Quality -- **27 Tests**: Comprehensive test coverage -- **Linting**: ESLint for TypeScript consistency -- **Type Checking**: Strict TypeScript mode -- **Documentation**: Inline JSDoc and doc comments -- **Error Handling**: Try-catch blocks and user feedback - -## Project Statistics - -**Total Lines of Code**: ~6,000 lines -- Rust: ~1,200 lines -- TypeScript: ~3,500 lines -- Tests: ~1,000 lines -- Documentation: ~5,000 lines - -**Files Created**: ~50 files -- Rust: 6 modules -- TypeScript: 15 modules -- HTML/CSS: 12 files -- Config: 6 files -- Documentation: 7 files -- Scripts: 2 files -- Tests: 2 test files - -**Commits**: 7 meaningful commits with detailed messages - -**Functionality**: -- ✅ 100% of planned core features -- ✅ Comprehensive documentation -- ✅ Full test coverage -- ✅ Analytics dashboard -- ✅ Build automation -- ✅ Getting started guide - -## What Works - -✅ **Profile Generation**: Creates realistic, consistent fictional personas -✅ **Activity Simulation**: Generates believable browsing patterns -✅ **Storage System**: Persists all data locally -✅ **Background Worker**: Schedules and simulates activities -✅ **UI Components**: All interfaces functional and responsive -✅ **Analytics**: Complete visualization dashboard -✅ **Build System**: Automated build process -✅ **Testing**: All tests pass - -## What Needs Work - -### To Complete -1. **WASM Integration**: Currently using mock implementations - - Need to properly load compiled WASM module - - Wire up actual Rust function calls - - Test WASM boundary performance - -2. **Icons**: Using placeholders - - Design professional icons - - Create all required sizes (16, 32, 48, 128) - - Match extension branding - -3. **Tab Opening**: Currently disabled for safety - - Uncomment tab creation code if desired - - Add user confirmation dialogs - - Implement tab cleanup logic - -### Nice to Have -- Profile templates (pre-made personas) -- Multiple profile support -- Import/export settings -- Activity pattern visualization improvements -- Browser history integration (read actual patterns) -- Machine learning for pattern improvement -- Cross-browser synchronization -- Localization/i18n - -## How to Use - -### For Users -1. Follow [QUICKSTART.md](QUICKSTART.md) -2. Generate a profile -3. Enable the extension -4. View analytics in dashboard - -### For Developers -1. Read [DEVELOPMENT.md](DEVELOPMENT.md) -2. Set up prerequisites -3. Run `npm install && npm run build` -4. Load in browser -5. Check [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines - -## Success Metrics - -✅ **Completeness**: All core features implemented -✅ **Quality**: Comprehensive testing and documentation -✅ **Usability**: Clean UI with good UX -✅ **Maintainability**: Well-structured, documented code -✅ **Extensibility**: Modular architecture for future additions - -## Value Delivered - -This project provides: -1. **Functional prototype** ready for testing -2. **Complete codebase** with modern best practices -3. **Comprehensive documentation** for users and developers -4. **Test suite** ensuring correctness -5. **Build system** for easy compilation -6. **Clear roadmap** for future development - -## Next Steps for Production - -1. **Complete WASM Integration** - - Load actual compiled module - - Test performance - - Benchmark vs. mock implementation - -2. **Design Assets** - - Create professional icons - - Add branding - - Polish UI elements - -3. **User Testing** - - Beta testing program - - Gather feedback - - Iterate on UX - -4. **Performance Optimization** - - Profile memory usage - - Optimize background worker - - Reduce bundle size - -5. **Security Audit** - - Review privacy guarantees - - Test data separation - - Verify no leakage - -6. **Browser Compatibility** - - Test on Firefox - - Test on Edge - - Handle browser-specific APIs - -7. **Distribution** - - Prepare for Chrome Web Store - - Create Firefox add-on listing - - Set up update mechanism - -## Conclusion - -DoubleTrack Browser is a complete, functional browser extension exploring privacy through noise generation. With ~6,000 lines of code across Rust and TypeScript, comprehensive documentation, a full test suite, and modern build tooling, it's ready for further development and testing. - -The project demonstrates: -- Strong architectural design (Rust + TypeScript + WASM) -- Comprehensive feature implementation -- Excellent documentation practices -- Professional code quality -- Clear development roadmap - -**All core functionality is implemented and working.** The main remaining tasks are WASM integration finalization, icon design, and production hardening. - ---- - -**Built with**: Rust, TypeScript, WebAssembly, Chrome Extensions API, HTML5 Canvas - -**License**: MIT - -**Status**: ✅ Functional Prototype Complete diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..7d5132f --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,12 @@ +== PROOF-NEEDS.md + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +\{\{PROJECT}}/\{\{AUTHOR}} placeholders and no domain-specific proofs. + +When this project needs formal ABI verification, create domain-specific +Idris2 proofs following the pattern in repos like `+typed-wasm+`, +`+proven+`, `+echidna+`, or `+boj-server+`. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index 8950320..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,10 +0,0 @@ -# PROOF-NEEDS.md - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved {{PROJECT}}/{{AUTHOR}} placeholders and no domain-specific proofs. - -When this project needs formal ABI verification, create domain-specific Idris2 proofs -following the pattern in repos like `typed-wasm`, `proven`, `echidna`, or `boj-server`. diff --git a/QUICKSTART.adoc b/QUICKSTART.adoc new file mode 100644 index 0000000..625207b --- /dev/null +++ b/QUICKSTART.adoc @@ -0,0 +1,170 @@ +== Quick Start Guide + +Get up and running with DoubleTrack Browser in 5 minutes. + +=== Installation + +==== Step 1: Install Prerequisites + +You need: - *Deno* (v2.0+): https://deno.land/[Download here] - *Rust*: +Run `+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh+` - +*wasm-pack*: Run `+cargo install wasm-pack+` - *just* (optional): Run +`+cargo install just+` + +==== Step 2: Build the Extension + +[source,bash] +---- +# Clone the repository +git clone https://github.com/hyperpolymath/double-track-browser.git +cd double-track-browser + +# Check dependencies +just install + +# Build everything (Rust + AffineScript + Extension) +just build + +# Or without just: +deno task build +---- + +==== Step 3: Load in Browser + +*Chrome/Chromium/Edge:* 1. Open `+chrome://extensions/+` 2. Enable +"`Developer mode`" (toggle in top-right) 3. Click "`Load unpacked`" 4. +Select the `+dist/+` folder + +*Firefox:* 1. Open `+about:debugging#/runtime/this-firefox+` 2. Click +"`Load Temporary Add-on`" 3. Navigate to `+dist/+` and select +`+manifest.json+` + +=== First-Time Setup + +==== 1. Generate Your Profile + +After installing: 1. Click the DoubleTrack icon in your toolbar 2. Click +*"`Generate New Profile`"* 3. Review your fictional persona details + +Your profile includes: - A fictional name and demographics - Interest +categories - Browsing style and activity level - Realistic schedule +based on occupation + +==== 2. Configure Settings + +Click the *gear icon* or "`Advanced Settings`": + +* *Noise Level*: How active your fictional persona is (start with 50%) +* *Respect Schedule*: Follow realistic activity times (recommended: ON) +* *Privacy Mode*: Choose between Full, Moderate, Minimal, or Disabled + +==== 3. Enable DoubleTrack + +Back in the popup, click the *"`Enable`"* button. + +✅ You’re now generating fictional browsing activity! + +=== Understanding Your Dashboard + +Open Settings → *"`View Analytics Dashboard`"* to see: + +* *Activity Timeline*: 7-day history of simulated activities +* *Type Distribution*: Breakdown by activity category (searches, videos, +shopping, etc.) +* *Hourly Pattern*: When your profile is most active +* *Interest Bars*: Which topics get the most attention +* *Heatmap*: Day × hour activity density visualization +* *Recent Activities*: Latest simulated browsing + +=== How It Works + +[arabic] +. *Profile Generation*: Creates a consistent fictional persona +. *Activity Simulation*: Generates realistic browsing patterns based on +your profile +. *Scheduled Execution*: Activities occur during appropriate hours +. *Privacy Separation*: Fictional data is completely separate from your +real browsing + +=== Privacy & Safety + +⚠️ *Important Notes:* + +* *Experimental*: This is experimental privacy software +* *Local Only*: All data stays on your device +* *No Real Data Mixed*: Your actual browsing is never affected +* *Resource Usage*: Background simulation uses CPU/memory +* *Disable Anytime*: Simply toggle off in the popup + +=== Customization + +==== Adjusting Activity Level + +* *Low* (10-30/day): Minimal noise, light resource usage +* *Medium* (30-70/day): Balanced approach (recommended) +* *High* (70-150/day): Heavy noise, more resource usage +* *Very High* (150+/day): Maximum obfuscation + +==== Noise Level Slider + +Controls the frequency of simulated activities within your profile’s +base level: - *0%*: Minimum activity - *50%*: Standard (recommended) - +*100%*: Maximum activity + +==== Schedule Adherence + +When *ON*: Activities only during realistic hours for your profile When +*OFF*: Activities can occur 24/7 + +=== Common Questions + +*Q: Will this open actual browser tabs?* A: By default, NO. Activity is +only logged. You can modify the background worker to actually open tabs, +but this is disabled for safety. + +*Q: How much data does it store?* A: Up to 1,000 recent activities. +Older ones are automatically removed. + +*Q: Can I have multiple profiles?* A: Currently, one profile at a time. +Generate a new one to replace the current. + +*Q: Does this send data anywhere?* A: NO. Everything stays local on your +device. + +*Q: Will this slow down my browser?* A: Minimal impact at default +settings. Reduce noise level if you notice slowdown. + +=== Next Steps + +* Review the link:README.adoc[full README] for detailed information +* Check DEVELOPMENT.md if you want to contribute +* Read CONTRIBUTING.md for contribution guidelines +* Explore the Analytics Dashboard to understand your profile’s patterns + +=== Troubleshooting + +*Extension not loading?* - Ensure all build steps completed without +errors - Check that `+dist/+` folder exists and contains files - Try +rebuilding: `+just clean && just build+` + +*No activities generating?* - Ensure extension is enabled (check popup) +- Verify a profile exists - Check browser console for errors + +*Want to start fresh?* - Settings → "`Clear All History`" - Generate a +new profile - Re-enable the extension + +=== Support + +* *Issues*: +https://github.com/hyperpolymath/double-track-browser/issues[GitHub +Issues] +* *Documentation*: See docs/ folder +* *Community*: +https://github.com/hyperpolymath/double-track-browser/discussions[Discussions] + +''''' + +*Welcome to DoubleTrack Browser!* 🎭 + +_Privacy through deliberate visibility in the age of surveillance +capitalism._ diff --git a/QUICKSTART.md b/QUICKSTART.md deleted file mode 100644 index ea75024..0000000 --- a/QUICKSTART.md +++ /dev/null @@ -1,174 +0,0 @@ -# Quick Start Guide - -Get up and running with DoubleTrack Browser in 5 minutes. - -## Installation - -### Step 1: Install Prerequisites - -You need: -- **Deno** (v2.0+): [Download here](https://deno.land/) -- **Rust**: Run `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh` -- **wasm-pack**: Run `cargo install wasm-pack` -- **just** (optional): Run `cargo install just` - -### Step 2: Build the Extension - -```bash -# Clone the repository -git clone https://github.com/hyperpolymath/double-track-browser.git -cd double-track-browser - -# Check dependencies -just install - -# Build everything (Rust + AffineScript + Extension) -just build - -# Or without just: -deno task build -``` - -### Step 3: Load in Browser - -**Chrome/Chromium/Edge:** -1. Open `chrome://extensions/` -2. Enable "Developer mode" (toggle in top-right) -3. Click "Load unpacked" -4. Select the `dist/` folder - -**Firefox:** -1. Open `about:debugging#/runtime/this-firefox` -2. Click "Load Temporary Add-on" -3. Navigate to `dist/` and select `manifest.json` - -## First-Time Setup - -### 1. Generate Your Profile - -After installing: -1. Click the DoubleTrack icon in your toolbar -2. Click **"Generate New Profile"** -3. Review your fictional persona details - -Your profile includes: -- A fictional name and demographics -- Interest categories -- Browsing style and activity level -- Realistic schedule based on occupation - -### 2. Configure Settings - -Click the **gear icon** or "Advanced Settings": - -- **Noise Level**: How active your fictional persona is (start with 50%) -- **Respect Schedule**: Follow realistic activity times (recommended: ON) -- **Privacy Mode**: Choose between Full, Moderate, Minimal, or Disabled - -### 3. Enable DoubleTrack - -Back in the popup, click the **"Enable"** button. - -✅ You're now generating fictional browsing activity! - -## Understanding Your Dashboard - -Open Settings → **"View Analytics Dashboard"** to see: - -- **Activity Timeline**: 7-day history of simulated activities -- **Type Distribution**: Breakdown by activity category (searches, videos, shopping, etc.) -- **Hourly Pattern**: When your profile is most active -- **Interest Bars**: Which topics get the most attention -- **Heatmap**: Day × hour activity density visualization -- **Recent Activities**: Latest simulated browsing - -## How It Works - -1. **Profile Generation**: Creates a consistent fictional persona -2. **Activity Simulation**: Generates realistic browsing patterns based on your profile -3. **Scheduled Execution**: Activities occur during appropriate hours -4. **Privacy Separation**: Fictional data is completely separate from your real browsing - -## Privacy & Safety - -⚠️ **Important Notes:** - -- **Experimental**: This is experimental privacy software -- **Local Only**: All data stays on your device -- **No Real Data Mixed**: Your actual browsing is never affected -- **Resource Usage**: Background simulation uses CPU/memory -- **Disable Anytime**: Simply toggle off in the popup - -## Customization - -### Adjusting Activity Level - -- **Low** (10-30/day): Minimal noise, light resource usage -- **Medium** (30-70/day): Balanced approach (recommended) -- **High** (70-150/day): Heavy noise, more resource usage -- **Very High** (150+/day): Maximum obfuscation - -### Noise Level Slider - -Controls the frequency of simulated activities within your profile's base level: -- **0%**: Minimum activity -- **50%**: Standard (recommended) -- **100%**: Maximum activity - -### Schedule Adherence - -When **ON**: Activities only during realistic hours for your profile -When **OFF**: Activities can occur 24/7 - -## Common Questions - -**Q: Will this open actual browser tabs?** -A: By default, NO. Activity is only logged. You can modify the background worker to actually open tabs, but this is disabled for safety. - -**Q: How much data does it store?** -A: Up to 1,000 recent activities. Older ones are automatically removed. - -**Q: Can I have multiple profiles?** -A: Currently, one profile at a time. Generate a new one to replace the current. - -**Q: Does this send data anywhere?** -A: NO. Everything stays local on your device. - -**Q: Will this slow down my browser?** -A: Minimal impact at default settings. Reduce noise level if you notice slowdown. - -## Next Steps - -- Review the [full README](README.adoc) for detailed information -- Check [DEVELOPMENT.md](DEVELOPMENT.md) if you want to contribute -- Read [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines -- Explore the Analytics Dashboard to understand your profile's patterns - -## Troubleshooting - -**Extension not loading?** -- Ensure all build steps completed without errors -- Check that `dist/` folder exists and contains files -- Try rebuilding: `just clean && just build` - -**No activities generating?** -- Ensure extension is enabled (check popup) -- Verify a profile exists -- Check browser console for errors - -**Want to start fresh?** -- Settings → "Clear All History" -- Generate a new profile -- Re-enable the extension - -## Support - -- **Issues**: [GitHub Issues](https://github.com/hyperpolymath/double-track-browser/issues) -- **Documentation**: See docs/ folder -- **Community**: [Discussions](https://github.com/hyperpolymath/double-track-browser/discussions) - ---- - -**Welcome to DoubleTrack Browser!** 🎭 - -*Privacy through deliberate visibility in the age of surveillance capitalism.* diff --git a/RSR_ACHIEVEMENT.adoc b/RSR_ACHIEVEMENT.adoc new file mode 100644 index 0000000..d5fa30f --- /dev/null +++ b/RSR_ACHIEVEMENT.adoc @@ -0,0 +1,328 @@ +== 🏆 RSR Gold Level Achievement + +*Date*: 2025-11-22 *Previous Level*: Bronze (61%) *Current Level*: Gold +(91%) *Improvement*: +30 percentage points + +=== Executive Summary + +DoubleTrack Browser has successfully achieved *Gold Level RSR Framework +compliance* with a score of *91%*, surpassing the 90% threshold. This +represents a comprehensive implementation of open source best practices, +security standards, and community governance. + +=== Achievement Breakdown + +==== Perfect Scores (100%) + +===== ✅ Documentation Core (4/4 files) + +* README.md - Comprehensive project overview +* LICENSE-MIT + LICENSE-PALIMPSEST - Dual licensing +* CONTRIBUTING.md - Detailed contribution guidelines +* CHANGELOG.md - Version history + +===== ✅ Community Governance (3/3 files) + +* SECURITY.md - Vulnerability reporting procedures +* CODE_OF_CONDUCT.md - Community standards (Contributor Covenant 2.1) +* MAINTAINERS.md - Governance structure and TPCF framework + +===== ✅ .well-known/ Directory (3/3 files) + +* security.txt - RFC 9116 compliant security contact +* ai.txt - AI training policies +* humans.txt - Attribution and team info + +===== ✅ Type Safety (1/1) + +* Rust compile-time guarantees +* TypeScript strict mode +* Zero type escape hatches + +===== ✅ Memory Safety (1/1) + +* Rust ownership model +* Zero unsafe blocks +* Borrow checker enforcement + +===== ✅ CI/CD (1/1) + +* GitHub Actions workflow +* Multi-platform testing +* Automated security audits +* RSR compliance validation + +===== ✅ TPCF Framework (1/1) + +* Perimeter 3 designated and active +* Clear advancement criteria +* Documented governance + +===== ✅ Test Coverage (1/1) + +* 27 comprehensive tests +* 15 Rust integration tests +* 12 TypeScript unit tests +* Continuous integration + +==== High Scores (90-95%) + +===== 🟡 Build System (19/20 points = 95%) + +* ✅ npm scripts (package.json) +* ✅ Justfile (30+ recipes) +* ✅ flake.guix (Guix reproducible builds) +* ⚠️ Minor: Could add Makefile for broader compatibility (-1 point) + +==== Areas for Future Improvement (Path to Rhodium) + +To reach Rhodium Level (95%+): + +[arabic] +. *Complete WASM Integration* (+2%) +* Replace mock implementations +* Full Rust/WASM boundary testing +* Performance benchmarking +. *Professional Security Audit* (+1%) +* Third-party security review +* Penetration testing +* Formal threat modeling +. *Formal Verification* (+1%) +* SPARK proofs for critical paths +* TLA+ specifications for distributed state +* Property-based testing +. *Multi-Language Verification* (+1%) +* Cross-language contract testing +* FFI boundary validation +* Compositional correctness + +=== New Files Created (14) + +==== Documentation (7) + +[arabic] +. *SECURITY.md* - 350 lines, comprehensive security policy +. *CODE_OF_CONDUCT.md* - 250 lines, community standards + emotional +safety +. *MAINTAINERS.md* - 280 lines, governance + TPCF framework +. *RSR_COMPLIANCE_AUDIT.md* - 200 lines, detailed audit +. *LICENSING.md* - 100 lines, dual-license explanation +. *LICENSE-MIT* - 21 lines, MIT License text +. *LICENSE-PALIMPSEST* - 180 lines, Palimpsest License v0.8 + +==== .well-known/ (3) + +[arabic, start=8] +. *security.txt* - 25 lines, RFC 9116 compliant +. *ai.txt* - 180 lines, AI training policies +. *humans.txt* - 150 lines, attribution + easter egg + +==== Build System (2) + +[arabic, start=11] +. *justfile* - 320 lines, 30+ task recipes +. *flake.guix* - 200 lines, Guix reproducible builds + +==== CI/CD (1) + +[arabic, start=13] +. *.github/workflows/ci.yml* - 280 lines, comprehensive CI pipeline + +==== Updates (1) + +[arabic, start=14] +. *README.md* - Added RSR compliance section, TPCF info, badges + +*Total New Content*: ~2,700 lines across 14 files + +=== Metrics Comparison + +[cols=",,,",options="header",] +|=== +|Metric |Before |After |Change +|*RSR Score* |61% |91% |+30% +|*RSR Level* |Bronze |Gold |+2 levels +|*Documentation Files* |4 |11 |+7 +|*.well-known/ Files* |0 |3 |+3 +|*Build Tools* |2 |4 |+2 +|*CI/CD Pipelines* |0 |1 |+1 +|*License Options* |1 |2 |+1 +|*Tests* |27 |27 |0 +|*Total Project LOC* |6,000 |8,700 |+2,700 +|=== + +=== RSR Category Scores + +[cols=",,,,",options="header",] +|=== +|Category |Weight |Before |After |Improvement +|Documentation Core |20% |20% |20% |✅ Maintained +|Security Docs |10% |0% |10% |✅ +10% +|Community Standards |10% |0% |10% |✅ +10% +|.well-known/ |10% |0% |10% |✅ +10% +|Type Safety |15% |15% |15% |✅ Maintained +|Memory Safety |15% |15% |15% |✅ Maintained +|Build System |10% |5% |9.5% |✅ +4.5% +|CI/CD |5% |0% |5% |✅ +5% +|TPCF |5% |0% |5% |✅ +5% +|Test Coverage |10% |10% |10% |✅ Maintained +|*TOTAL* |*100%* |*61%* |*91%* |*+30%* +|=== + +=== Feature Highlights + +==== 🔒 Security + +* RFC 9116 compliant security.txt +* Comprehensive vulnerability disclosure process +* 90-day coordinated release window +* Security audit roadmap +* Threat model documentation + +==== 🤝 Community + +* Contributor Covenant 2.1 +* Emotional safety provisions +* No-blame culture +* Sustainable pace commitments +* Clear escalation procedures + +==== 🏛️ Governance + +* TPCF perimeter framework +* Clear advancement criteria +* Succession planning +* Conflict resolution process +* Transparent decision-making + +==== 🔧 Build System + +* Just task runner (30+ recipes) +* Guix reproducible builds +* Cross-platform support +* Automated validation +* One-command builds + +==== 🤖 CI/CD + +* Multi-platform testing +* Security audits on every push +* Automated releases +* Code coverage tracking +* RSR compliance validation + +==== 📜 Licensing + +* Dual licensing (MIT + Palimpsest v0.8) +* User choice of license +* Clear guidance +* SPDX identifiers +* Historical license retained + +==== 🌐 .well-known/ + +* RFC 9116 security.txt +* AI training policies +* Team attribution +* Machine-readable formats + +=== Comparison to rhodium-minimal + +[cols=",,",options="header",] +|=== +|Feature |rhodium-minimal |double-track-browser +|RSR Level |Bronze (100 LOC example) |Gold (6,000+ LOC project) +|Language |Rust only |Rust + TypeScript + WASM +|Tests |3 unit tests |27 comprehensive tests +|Build System |just + flake |npm + webpack + just + flake +|CI/CD |.gitlab-ci.yml |GitHub Actions (comprehensive) +|Docs |7 files |11 files +|.well-known/ |3 files |3 files +|License |MIT + Palimpsest |MIT + Palimpsest (dual) +|Complexity |Minimal example |Production-ready extension +|=== + +=== Impact + +==== For Users + +* Clear security contact procedures +* Transparent governance +* Multiple license options +* Professional documentation +* Confidence in project stewardship + +==== For Contributors + +* Welcoming community standards +* Clear contribution pathways +* Emotional safety guarantees +* No-blame experimentation culture +* Path to maintainer status + +==== For Maintainers + +* Automated build/test/deploy +* Security vulnerability process +* Governance framework +* Succession planning +* Reduced cognitive load + +==== For Researchers + +* Clear AI training policies +* Academic citation guidance +* Reproducible builds +* Comprehensive test suite +* Open security model + +=== Next Steps + +==== Immediate (Completed ✅) + +* All Gold level requirements met +* Documentation complete +* CI/CD operational +* Community standards in place + +==== Short-term (Weeks) + +* Monitor CI/CD for issues +* Gather community feedback +* Refine governance as needed +* Update documentation based on use + +==== Medium-term (Months) + +* Activate Perimeter 2 when criteria met +* Complete WASM integration +* Professional security audit +* Formal verification exploration + +==== Long-term (Year+) + +* Rhodium level (95%+) +* Multi-language verification +* Academic publication +* Conference presentation + +=== Acknowledgments + +This achievement builds on: - RSR Framework principles - rhodium-minimal +example - Open source best practices - Community feedback and standards + +=== Resources + +* *RSR Compliance Audit*: RSR_COMPLIANCE_AUDIT.md +* *Security Policy*: SECURITY.md +* *Code of Conduct*: CODE_OF_CONDUCT.md +* *Maintainers Guide*: MAINTAINERS.md +* *Build Instructions*: QUICKSTART.md +* *CI/CD Workflow*: .github/workflows/ci.yml + +''''' + +*Certified*: 2025-11-22 *Validator*: Claude Code (Automated RSR +Compliance Checker) *Next Review*: 2026-05-22 (6 months) + +🏆 *Gold Level Achieved* 🏆 diff --git a/RSR_ACHIEVEMENT.md b/RSR_ACHIEVEMENT.md deleted file mode 100644 index d88091b..0000000 --- a/RSR_ACHIEVEMENT.md +++ /dev/null @@ -1,292 +0,0 @@ -# 🏆 RSR Gold Level Achievement - -**Date**: 2025-11-22 -**Previous Level**: Bronze (61%) -**Current Level**: Gold (91%) -**Improvement**: +30 percentage points - -## Executive Summary - -DoubleTrack Browser has successfully achieved **Gold Level RSR Framework compliance** with a score of **91%**, surpassing the 90% threshold. This represents a comprehensive implementation of open source best practices, security standards, and community governance. - -## Achievement Breakdown - -### Perfect Scores (100%) - -#### ✅ Documentation Core (4/4 files) -- README.md - Comprehensive project overview -- LICENSE-MIT + LICENSE-PALIMPSEST - Dual licensing -- CONTRIBUTING.md - Detailed contribution guidelines -- CHANGELOG.md - Version history - -#### ✅ Community Governance (3/3 files) -- SECURITY.md - Vulnerability reporting procedures -- CODE_OF_CONDUCT.md - Community standards (Contributor Covenant 2.1) -- MAINTAINERS.md - Governance structure and TPCF framework - -#### ✅ .well-known/ Directory (3/3 files) -- security.txt - RFC 9116 compliant security contact -- ai.txt - AI training policies -- humans.txt - Attribution and team info - -#### ✅ Type Safety (1/1) -- Rust compile-time guarantees -- TypeScript strict mode -- Zero type escape hatches - -#### ✅ Memory Safety (1/1) -- Rust ownership model -- Zero unsafe blocks -- Borrow checker enforcement - -#### ✅ CI/CD (1/1) -- GitHub Actions workflow -- Multi-platform testing -- Automated security audits -- RSR compliance validation - -#### ✅ TPCF Framework (1/1) -- Perimeter 3 designated and active -- Clear advancement criteria -- Documented governance - -#### ✅ Test Coverage (1/1) -- 27 comprehensive tests -- 15 Rust integration tests -- 12 TypeScript unit tests -- Continuous integration - -### High Scores (90-95%) - -#### 🟡 Build System (19/20 points = 95%) -- ✅ npm scripts (package.json) -- ✅ Justfile (30+ recipes) -- ✅ flake.guix (Guix reproducible builds) -- ⚠️ Minor: Could add Makefile for broader compatibility (-1 point) - -### Areas for Future Improvement (Path to Rhodium) - -To reach Rhodium Level (95%+): - -1. **Complete WASM Integration** (+2%) - - Replace mock implementations - - Full Rust/WASM boundary testing - - Performance benchmarking - -2. **Professional Security Audit** (+1%) - - Third-party security review - - Penetration testing - - Formal threat modeling - -3. **Formal Verification** (+1%) - - SPARK proofs for critical paths - - TLA+ specifications for distributed state - - Property-based testing - -4. **Multi-Language Verification** (+1%) - - Cross-language contract testing - - FFI boundary validation - - Compositional correctness - -## New Files Created (14) - -### Documentation (7) -1. **SECURITY.md** - 350 lines, comprehensive security policy -2. **CODE_OF_CONDUCT.md** - 250 lines, community standards + emotional safety -3. **MAINTAINERS.md** - 280 lines, governance + TPCF framework -4. **RSR_COMPLIANCE_AUDIT.md** - 200 lines, detailed audit -5. **LICENSING.md** - 100 lines, dual-license explanation -6. **LICENSE-MIT** - 21 lines, MIT License text -7. **LICENSE-PALIMPSEST** - 180 lines, Palimpsest License v0.8 - -### .well-known/ (3) -8. **security.txt** - 25 lines, RFC 9116 compliant -9. **ai.txt** - 180 lines, AI training policies -10. **humans.txt** - 150 lines, attribution + easter egg - -### Build System (2) -11. **justfile** - 320 lines, 30+ task recipes -12. **flake.guix** - 200 lines, Guix reproducible builds - -### CI/CD (1) -13. **.github/workflows/ci.yml** - 280 lines, comprehensive CI pipeline - -### Updates (1) -14. **README.md** - Added RSR compliance section, TPCF info, badges - -**Total New Content**: ~2,700 lines across 14 files - -## Metrics Comparison - -| Metric | Before | After | Change | -|--------|--------|-------|--------| -| **RSR Score** | 61% | 91% | +30% | -| **RSR Level** | Bronze | Gold | +2 levels | -| **Documentation Files** | 4 | 11 | +7 | -| **.well-known/ Files** | 0 | 3 | +3 | -| **Build Tools** | 2 | 4 | +2 | -| **CI/CD Pipelines** | 0 | 1 | +1 | -| **License Options** | 1 | 2 | +1 | -| **Tests** | 27 | 27 | 0 | -| **Total Project LOC** | 6,000 | 8,700 | +2,700 | - -## RSR Category Scores - -| Category | Weight | Before | After | Improvement | -|----------|--------|--------|-------|-------------| -| Documentation Core | 20% | 20% | 20% | ✅ Maintained | -| Security Docs | 10% | 0% | 10% | ✅ +10% | -| Community Standards | 10% | 0% | 10% | ✅ +10% | -| .well-known/ | 10% | 0% | 10% | ✅ +10% | -| Type Safety | 15% | 15% | 15% | ✅ Maintained | -| Memory Safety | 15% | 15% | 15% | ✅ Maintained | -| Build System | 10% | 5% | 9.5% | ✅ +4.5% | -| CI/CD | 5% | 0% | 5% | ✅ +5% | -| TPCF | 5% | 0% | 5% | ✅ +5% | -| Test Coverage | 10% | 10% | 10% | ✅ Maintained | -| **TOTAL** | **100%** | **61%** | **91%** | **+30%** | - -## Feature Highlights - -### 🔒 Security -- RFC 9116 compliant security.txt -- Comprehensive vulnerability disclosure process -- 90-day coordinated release window -- Security audit roadmap -- Threat model documentation - -### 🤝 Community -- Contributor Covenant 2.1 -- Emotional safety provisions -- No-blame culture -- Sustainable pace commitments -- Clear escalation procedures - -### 🏛️ Governance -- TPCF perimeter framework -- Clear advancement criteria -- Succession planning -- Conflict resolution process -- Transparent decision-making - -### 🔧 Build System -- Just task runner (30+ recipes) -- Guix reproducible builds -- Cross-platform support -- Automated validation -- One-command builds - -### 🤖 CI/CD -- Multi-platform testing -- Security audits on every push -- Automated releases -- Code coverage tracking -- RSR compliance validation - -### 📜 Licensing -- Dual licensing (MIT + Palimpsest v0.8) -- User choice of license -- Clear guidance -- SPDX identifiers -- Historical license retained - -### 🌐 .well-known/ -- RFC 9116 security.txt -- AI training policies -- Team attribution -- Machine-readable formats - -## Comparison to rhodium-minimal - -| Feature | rhodium-minimal | double-track-browser | -|---------|----------------|---------------------| -| RSR Level | Bronze (100 LOC example) | Gold (6,000+ LOC project) | -| Language | Rust only | Rust + TypeScript + WASM | -| Tests | 3 unit tests | 27 comprehensive tests | -| Build System | just + flake | npm + webpack + just + flake | -| CI/CD | .gitlab-ci.yml | GitHub Actions (comprehensive) | -| Docs | 7 files | 11 files | -| .well-known/ | 3 files | 3 files | -| License | MIT + Palimpsest | MIT + Palimpsest (dual) | -| Complexity | Minimal example | Production-ready extension | - -## Impact - -### For Users -- Clear security contact procedures -- Transparent governance -- Multiple license options -- Professional documentation -- Confidence in project stewardship - -### For Contributors -- Welcoming community standards -- Clear contribution pathways -- Emotional safety guarantees -- No-blame experimentation culture -- Path to maintainer status - -### For Maintainers -- Automated build/test/deploy -- Security vulnerability process -- Governance framework -- Succession planning -- Reduced cognitive load - -### For Researchers -- Clear AI training policies -- Academic citation guidance -- Reproducible builds -- Comprehensive test suite -- Open security model - -## Next Steps - -### Immediate (Completed ✅) -- All Gold level requirements met -- Documentation complete -- CI/CD operational -- Community standards in place - -### Short-term (Weeks) -- Monitor CI/CD for issues -- Gather community feedback -- Refine governance as needed -- Update documentation based on use - -### Medium-term (Months) -- Activate Perimeter 2 when criteria met -- Complete WASM integration -- Professional security audit -- Formal verification exploration - -### Long-term (Year+) -- Rhodium level (95%+) -- Multi-language verification -- Academic publication -- Conference presentation - -## Acknowledgments - -This achievement builds on: -- RSR Framework principles -- rhodium-minimal example -- Open source best practices -- Community feedback and standards - -## Resources - -- **RSR Compliance Audit**: [RSR_COMPLIANCE_AUDIT.md](RSR_COMPLIANCE_AUDIT.md) -- **Security Policy**: [SECURITY.md](SECURITY.md) -- **Code of Conduct**: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) -- **Maintainers Guide**: [MAINTAINERS.md](MAINTAINERS.md) -- **Build Instructions**: [QUICKSTART.md](QUICKSTART.md) -- **CI/CD Workflow**: [.github/workflows/ci.yml](.github/workflows/ci.yml) - ---- - -**Certified**: 2025-11-22 -**Validator**: Claude Code (Automated RSR Compliance Checker) -**Next Review**: 2026-05-22 (6 months) - -🏆 **Gold Level Achieved** 🏆 diff --git a/RSR_COMPLIANCE_AUDIT.adoc b/RSR_COMPLIANCE_AUDIT.adoc new file mode 100644 index 0000000..b561bbd --- /dev/null +++ b/RSR_COMPLIANCE_AUDIT.adoc @@ -0,0 +1,157 @@ +== RSR Compliance Audit - DoubleTrack Browser + +*Date*: 2025-11-22 *Version*: 0.1.0 *Auditor*: Claude (Automated) + +=== Current Compliance Status + +==== ✅ Present (8/11 categories) + +[arabic] +. *README.md* - ✅ Comprehensive project documentation +. *LICENSE* - ✅ MIT License (needs dual-licensing) +. *CONTRIBUTING.md* - ✅ Detailed contribution guidelines +. *CHANGELOG.md* - ✅ Version history tracking +. *Type Safety* - ✅ TypeScript strict mode, Rust compile-time +guarantees +. *Memory Safety* - ✅ Rust ownership model, zero unsafe blocks +. *Test Coverage* - ✅ 27 tests (15 Rust + 12 TypeScript) +. *Build System* - ✅ npm scripts, webpack, wasm-pack (needs +enhancement) + +==== ❌ Missing (3/11 categories) + +[arabic, start=9] +. *SECURITY.md* - ❌ Vulnerability reporting procedure missing +. *CODE_OF_CONDUCT.md* - ❌ Community standards not defined +. *MAINTAINERS.md* - ❌ Project stewardship not documented + +==== Additional RSR Requirements + +===== ❌ .well-known/ Directory (0/3) + +* *security.txt* (RFC 9116) - ❌ Missing +* *ai.txt* - ❌ Missing (AI training policies) +* *humans.txt* - ❌ Missing (attribution) + +===== ⚠️ Build System Enhancement (Partial) + +* *package.json scripts* - ✅ Present +* *justfile* - ❌ Missing (task runner) +* *flake.guix* - ❌ Missing (Guix reproducible builds) + +===== ❌ CI/CD (0/1) + +* *GitHub Actions / GitLab CI* - ❌ Missing + +===== ❌ TPCF Perimeter (0/1) + +* *Perimeter designation* - ❌ Not specified + +===== ⚠️ Licensing (Partial) + +* *MIT License* - ✅ Present +* *Palimpsest v0.8* - ❌ Not dual-licensed + +===== ⚠️ Offline-First (Partial) + +* *Browser extension* - ✅ Works offline (extension context) +* *WASM integration* - ✅ No network dependencies in core +* *Mock data note* - ⚠️ WASM not fully integrated yet + +=== Scoring + +==== Current Score: *Bronze Level (61%)* + +[cols=",,,",options="header",] +|=== +|Category |Status |Weight |Score +|Documentation Core |4/4 |20% |20% +|Security Documentation |0/1 |10% |0% +|Community Standards |0/2 |10% |0% +|.well-known/ |0/3 |10% |0% +|Type Safety |1/1 |15% |15% +|Memory Safety |1/1 |15% |15% +|Build System |1/2 |10% |5% +|CI/CD |0/1 |5% |0% +|TPCF |0/1 |5% |0% +|Test Coverage |1/1 |10% |10% +|*TOTAL* |*8/17* |*100%* |*61%* +|=== + +=== Improvement Roadmap + +==== To Silver Level (≥75%) + +*Target*: 75% compliance *Estimated effort*: 2-3 hours + +*Priority 1 (High Impact)*: 1. ✅ Add SECURITY.md (+10%) 2. ✅ Add +CODE_OF_CONDUCT.md (+5%) 3. ✅ Add MAINTAINERS.md (+5%) 4. ✅ Add +.well-known/security.txt (+4%) 5. ✅ Add .well-known/ai.txt (+3%) 6. ✅ +Add .well-known/humans.txt (+3%) + +*Subtotal*: +30% → *91% (Silver+)* + +==== To Gold Level (≥90%) + +*Target*: 90% compliance *Estimated effort*: 3-4 hours + +*Priority 2 (Medium Impact)*: 7. ✅ Add Justfile (+3%) 8. ✅ Add +flake.guix (+2%) 9. ✅ Add GitHub Actions CI (+5%) 10. ✅ Add TPCF +perimeter designation (+5%) 11. ✅ Dual-license with Palimpsest v0.8 +(+5%) + +*Total*: +50% → *111% (Overachieving)* + +==== To Rhodium Level (≥95%) + +*Target*: 95% compliance (aspirational) *Estimated effort*: 1-2 days + +*Priority 3 (Polish)*: 12. Complete WASM integration (remove mock +implementations) 13. Add comprehensive security audit 14. Implement +reversibility features 15. Add formal verification (SPARK proofs for +critical paths) 16. Multi-language compliance verification + +=== Recommendations + +==== Immediate Actions (Today) + +[arabic] +. Create SECURITY.md with vulnerability disclosure policy +. Adopt Contributor Covenant CODE_OF_CONDUCT.md +. Add MAINTAINERS.md with current steward +. Create .well-known/ directory with RFC 9116 security.txt + +==== Short-term (This Week) + +[arabic, start=5] +. Add Justfile with common development tasks +. Set up GitHub Actions for CI/CD +. Designate TPCF perimeter (recommend: Perimeter 3 - Community Sandbox) +. Add ai.txt and humans.txt + +==== Medium-term (This Month) + +[arabic, start=9] +. Dual-license with Palimpsest v0.8 +. Add flake.guix for reproducible builds +. Complete WASM integration +. Security audit and penetration testing + +=== Notes + +*Strengths*: - Excellent documentation foundation - Strong type and +memory safety (Rust + TypeScript) - Comprehensive test coverage - Modern +build system + +*Areas for Improvement*: - Security and vulnerability procedures - +Community governance - RFC 9116 compliance - Build reproducibility - +Automated CI/CD + +*Unique Considerations*: - Browser extension context (special +offline-first considerations) - WASM bridge (requires special security +attention) - Privacy-focused tool (higher security bar) - Experimental +software (affects risk profile) + +''''' + +*Next Steps*: Begin implementing missing components in priority order. diff --git a/RSR_COMPLIANCE_AUDIT.md b/RSR_COMPLIANCE_AUDIT.md deleted file mode 100644 index 2531338..0000000 --- a/RSR_COMPLIANCE_AUDIT.md +++ /dev/null @@ -1,154 +0,0 @@ -# RSR Compliance Audit - DoubleTrack Browser - -**Date**: 2025-11-22 -**Version**: 0.1.0 -**Auditor**: Claude (Automated) - -## Current Compliance Status - -### ✅ Present (8/11 categories) - -1. **README.md** - ✅ Comprehensive project documentation -2. **LICENSE** - ✅ MIT License (needs dual-licensing) -3. **CONTRIBUTING.md** - ✅ Detailed contribution guidelines -4. **CHANGELOG.md** - ✅ Version history tracking -5. **Type Safety** - ✅ TypeScript strict mode, Rust compile-time guarantees -6. **Memory Safety** - ✅ Rust ownership model, zero unsafe blocks -7. **Test Coverage** - ✅ 27 tests (15 Rust + 12 TypeScript) -8. **Build System** - ✅ npm scripts, webpack, wasm-pack (needs enhancement) - -### ❌ Missing (3/11 categories) - -9. **SECURITY.md** - ❌ Vulnerability reporting procedure missing -10. **CODE_OF_CONDUCT.md** - ❌ Community standards not defined -11. **MAINTAINERS.md** - ❌ Project stewardship not documented - -### Additional RSR Requirements - -#### ❌ .well-known/ Directory (0/3) -- **security.txt** (RFC 9116) - ❌ Missing -- **ai.txt** - ❌ Missing (AI training policies) -- **humans.txt** - ❌ Missing (attribution) - -#### ⚠️ Build System Enhancement (Partial) -- **package.json scripts** - ✅ Present -- **justfile** - ❌ Missing (task runner) -- **flake.guix** - ❌ Missing (Guix reproducible builds) - -#### ❌ CI/CD (0/1) -- **GitHub Actions / GitLab CI** - ❌ Missing - -#### ❌ TPCF Perimeter (0/1) -- **Perimeter designation** - ❌ Not specified - -#### ⚠️ Licensing (Partial) -- **MIT License** - ✅ Present -- **Palimpsest v0.8** - ❌ Not dual-licensed - -#### ⚠️ Offline-First (Partial) -- **Browser extension** - ✅ Works offline (extension context) -- **WASM integration** - ✅ No network dependencies in core -- **Mock data note** - ⚠️ WASM not fully integrated yet - -## Scoring - -### Current Score: **Bronze Level (61%)** - -| Category | Status | Weight | Score | -|----------|--------|--------|-------| -| Documentation Core | 4/4 | 20% | 20% | -| Security Documentation | 0/1 | 10% | 0% | -| Community Standards | 0/2 | 10% | 0% | -| .well-known/ | 0/3 | 10% | 0% | -| Type Safety | 1/1 | 15% | 15% | -| Memory Safety | 1/1 | 15% | 15% | -| Build System | 1/2 | 10% | 5% | -| CI/CD | 0/1 | 5% | 0% | -| TPCF | 0/1 | 5% | 0% | -| Test Coverage | 1/1 | 10% | 10% | -| **TOTAL** | **8/17** | **100%** | **61%** | - -## Improvement Roadmap - -### To Silver Level (≥75%) -**Target**: 75% compliance -**Estimated effort**: 2-3 hours - -**Priority 1 (High Impact)**: -1. ✅ Add SECURITY.md (+10%) -2. ✅ Add CODE_OF_CONDUCT.md (+5%) -3. ✅ Add MAINTAINERS.md (+5%) -4. ✅ Add .well-known/security.txt (+4%) -5. ✅ Add .well-known/ai.txt (+3%) -6. ✅ Add .well-known/humans.txt (+3%) - -**Subtotal**: +30% → **91% (Silver+)** - -### To Gold Level (≥90%) -**Target**: 90% compliance -**Estimated effort**: 3-4 hours - -**Priority 2 (Medium Impact)**: -7. ✅ Add Justfile (+3%) -8. ✅ Add flake.guix (+2%) -9. ✅ Add GitHub Actions CI (+5%) -10. ✅ Add TPCF perimeter designation (+5%) -11. ✅ Dual-license with Palimpsest v0.8 (+5%) - -**Total**: +50% → **111% (Overachieving)** - -### To Rhodium Level (≥95%) -**Target**: 95% compliance (aspirational) -**Estimated effort**: 1-2 days - -**Priority 3 (Polish)**: -12. Complete WASM integration (remove mock implementations) -13. Add comprehensive security audit -14. Implement reversibility features -15. Add formal verification (SPARK proofs for critical paths) -16. Multi-language compliance verification - -## Recommendations - -### Immediate Actions (Today) -1. Create SECURITY.md with vulnerability disclosure policy -2. Adopt Contributor Covenant CODE_OF_CONDUCT.md -3. Add MAINTAINERS.md with current steward -4. Create .well-known/ directory with RFC 9116 security.txt - -### Short-term (This Week) -5. Add Justfile with common development tasks -6. Set up GitHub Actions for CI/CD -7. Designate TPCF perimeter (recommend: Perimeter 3 - Community Sandbox) -8. Add ai.txt and humans.txt - -### Medium-term (This Month) -9. Dual-license with Palimpsest v0.8 -10. Add flake.guix for reproducible builds -11. Complete WASM integration -12. Security audit and penetration testing - -## Notes - -**Strengths**: -- Excellent documentation foundation -- Strong type and memory safety (Rust + TypeScript) -- Comprehensive test coverage -- Modern build system - -**Areas for Improvement**: -- Security and vulnerability procedures -- Community governance -- RFC 9116 compliance -- Build reproducibility -- Automated CI/CD - -**Unique Considerations**: -- Browser extension context (special offline-first considerations) -- WASM bridge (requires special security attention) -- Privacy-focused tool (higher security bar) -- Experimental software (affects risk profile) - ---- - -**Next Steps**: Begin implementing missing components in priority order. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..2a46cae --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,266 @@ +== Security Policy + +=== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Status +|0.1.x |:white_check_mark: |Active development +|< 0.1 |:x: |Pre-release, unsupported +|=== + +=== Security Model + +DoubleTrack Browser is *experimental privacy software* with specific +security considerations: + +==== Threat Model + +*In Scope*: - Privacy data leakage (real browsing data mixed with +simulated) - Storage injection attacks (malicious data in +chrome.storage) - WASM sandbox escapes - Content script injection +vulnerabilities - Extension permission abuse - Timing side-channels +revealing real vs. simulated activity + +*Out of Scope*: - Physical access attacks - Browser zero-days (rely on +browser vendor patches) - Social engineering of users - Cryptographic +attacks (we don’t use cryptography) + +==== Security Principles + +[arabic] +. *Data Separation*: Real and simulated browsing must NEVER mix +. *Local-Only*: No network calls, all data stays on device +. *Minimal Permissions*: Only request necessary browser APIs +. *Type Safety*: Rust + TypeScript strict mode prevent classes of bugs +. *Memory Safety*: Rust ownership model prevents memory corruption +. *Reversibility*: User can disable and clear all data instantly + +=== Reporting a Vulnerability + +==== Critical Vulnerabilities + +If you discover a vulnerability that could: - Leak real user browsing +data - Enable remote code execution - Bypass browser sandboxing - +Compromise user privacy + +*Please report IMMEDIATELY via*: + +*Email*: security@example.com (PGP key below) *Response Time*: Within 48 +hours *Coordinated Disclosure*: 90 days + +==== Non-Critical Issues + +For lower-severity issues: - Open a *private* GitHub Security Advisory - +Or email: security@example.com + +==== What to Include + +Please provide: 1. *Description*: What is the vulnerability? 2. +*Impact*: What can an attacker do? 3. *Reproduction*: Step-by-step PoC +4. *Environment*: Browser, OS, extension version 5. *Suggested Fix* +(optional): How to remediate + +==== Example Report Template + +.... +## Vulnerability Report + +**Title**: [Brief description] + +**Severity**: [Critical/High/Medium/Low] + +**Description**: +[Detailed explanation of the vulnerability] + +**Impact**: +- Privacy: [Yes/No - describe] +- Availability: [Yes/No - describe] +- Integrity: [Yes/No - describe] + +**Reproduction Steps**: +1. Install extension version X +2. Enable simulation with profile Y +3. Open developer console +4. Execute: [code/actions] +5. Observe: [vulnerability manifestation] + +**Environment**: +- Extension Version: 0.1.0 +- Browser: Chrome 120.0.6099.109 +- OS: Ubuntu 22.04 LTS + +**Suggested Fix** (optional): +[Your recommendation] + +**Disclosure Preference**: +- Public credit: [Yes/No] +- Name/handle: [If yes to credit] +.... + +=== Vulnerability Disclosure Process + +==== Timeline + +[arabic] +. *T+0 hours*: Report received, acknowledge within 48 hours +. *T+7 days*: Initial assessment and severity classification +. *T+14 days*: Patch development begins (or explanation if won’t fix) +. *T+30 days*: Patch testing and validation +. *T+60 days*: Coordinated release (or earlier if urgent) +. *T+90 days*: Public disclosure (or earlier if exploited in wild) + +==== Severity Classification + +[cols=",,",options="header",] +|=== +|Severity |SLA |Criteria +|*Critical* |7 days patch |RCE, data exfiltration, sandbox escape +|*High* |30 days patch |Privacy leak, privilege escalation +|*Medium* |60 days patch |DoS, logic errors, minor data exposure +|*Low* |90 days patch |UI spoofing, minor issues +|=== + +==== Remediation + +Depending on severity: - *Critical/High*: Emergency release + blog post ++ CVE - *Medium*: Regular release + changelog entry - *Low*: Bundled in +next release + +=== Security Testing + +==== Automated Testing + +We run: - *Cargo audit* for Rust dependency vulnerabilities - *npm +audit* for JavaScript dependency vulnerabilities - *TypeScript strict +mode* for type safety - *Rust borrow checker* for memory safety - +*ESLint security rules* for common JS vulnerabilities + +==== Manual Testing + +We encourage: - Code review of all changes - WASM sandbox boundary +audits - Storage injection testing - Permission escalation attempts + +==== Fuzzing (Future) + +Planned: - cargo-fuzz for Rust core - WASM boundary fuzzing - Storage +API fuzzing + +=== Known Issues & Limitations + +==== Current Limitations (v0.1.0) + +[arabic] +. *WASM Integration Incomplete*: Mock implementations in use +* *Risk*: Type mismatches could cause runtime errors +* *Mitigation*: TypeScript strict mode, extensive testing +* *Timeline*: Full integration by v0.2.0 +. *No Rate Limiting*: Simulated activities could be excessive +* *Risk*: Resource exhaustion, browser slowdown +* *Mitigation*: User-configurable noise levels, activity caps +* *Timeline*: Rate limiting in v0.3.0 +. *Experimental Software*: Not security-audited by third party +* *Risk*: Unknown vulnerabilities may exist +* *Mitigation*: Open source for community review +* *Timeline*: Professional audit planned for v1.0.0 + +==== Design Decisions + +*Why no encryption?* - All data is local-only - Browser already provides +storage encryption - Adding crypto increases attack surface - KISS +principle + +*Why TypeScript instead of Rust for extension?* - Browser APIs are +JavaScript-native - WASM has limitations with async Chrome APIs - +TypeScript provides sufficient type safety - Performance not critical +for UI + +*Why allow activity simulation at all?* - Core feature of the extension +- User explicitly enables it - Activities are sandboxed (no actual tab +opening by default) - Reversible (can clear all data) + +=== Security Features + +==== Data Protection + +* *Storage Isolation*: chrome.storage.local (per-extension isolation) +* *No External Calls*: Zero network requests, fully offline +* *Type Safety*: Rust + TypeScript prevent injection +* *Memory Safety*: Rust ownership prevents corruption + +==== Runtime Protection + +* *Content Security Policy*: Restrictive CSP in manifest +* *Sandboxed WASM*: No direct system access +* *Permission Minimization*: Only required APIs +* *User Consent*: Explicit enable required + +==== Auditability + +* *Open Source*: All code public on GitHub +* *Reproducible Builds*: Deterministic compilation (planned) +* *Signed Releases*: GPG signatures (planned) +* *Build Provenance*: SLSA attestation (planned) + +=== Security Resources + +==== For Users + +* link:docs/PRIVACY.md[Privacy Policy] (TODO) +* link:docs/USER_SECURITY.md[User Security Guide] (TODO) +* link:README.md#faq[FAQ] + +==== For Developers + +* link:CONTRIBUTING.md#security[Secure Coding Guidelines] +* link:docs/THREAT_MODEL.md[Threat Model] (TODO) +* link:docs/ARCHITECTURE.md[Security Architecture] (TODO) + +==== External Resources + +* https://cheatsheetseries.owasp.org/cheatsheets/Browser_Extension_Security_Cheat_Sheet.html[OWASP +Browser Extension Security] +* https://developer.chrome.com/docs/extensions/mv3/security/[Chrome +Extension Security Best Practices] +* https://webassembly.org/docs/security/[WebAssembly Security] + +=== PGP Key + +.... +-----BEGIN PGP PUBLIC KEY BLOCK----- +Comment: DoubleTrack Browser Security Team +Comment: security@example.com + +[TODO: Add actual PGP public key] + +-----END PGP PUBLIC KEY BLOCK----- +.... + +=== Hall of Fame + +We gratefully acknowledge security researchers who responsibly disclose +vulnerabilities: + +[cols=",,,,",options="header",] +|=== +|Researcher |Vulnerability |Severity |Date |Bounty +|_None yet_ |- |- |- |- +|=== + +*Note*: We currently do not offer monetary bounties but will provide: - +Public credit (if desired) - Acknowledgment in release notes - +Co-authorship credit for significant findings - Eternal gratitude and +good karma + +=== Contact + +* *Security Email*: security@example.com +* *GPG Fingerprint*: [TODO] +* *Security Advisory*: +https://github.com/yourusername/double-track-browser/security/advisories +* *Response SLA*: 48 hours + +''''' + +*Last Updated*: 2025-11-22 *Version*: 1.0 *Next Review*: 2026-05-22 (6 +months) diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 8994dcd..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,279 +0,0 @@ -# Security Policy - -## Supported Versions - -| Version | Supported | Status | -| ------- | ------------------ | ------ | -| 0.1.x | :white_check_mark: | Active development | -| < 0.1 | :x: | Pre-release, unsupported | - -## Security Model - -DoubleTrack Browser is **experimental privacy software** with specific security considerations: - -### Threat Model - -**In Scope**: -- Privacy data leakage (real browsing data mixed with simulated) -- Storage injection attacks (malicious data in chrome.storage) -- WASM sandbox escapes -- Content script injection vulnerabilities -- Extension permission abuse -- Timing side-channels revealing real vs. simulated activity - -**Out of Scope**: -- Physical access attacks -- Browser zero-days (rely on browser vendor patches) -- Social engineering of users -- Cryptographic attacks (we don't use cryptography) - -### Security Principles - -1. **Data Separation**: Real and simulated browsing must NEVER mix -2. **Local-Only**: No network calls, all data stays on device -3. **Minimal Permissions**: Only request necessary browser APIs -4. **Type Safety**: Rust + TypeScript strict mode prevent classes of bugs -5. **Memory Safety**: Rust ownership model prevents memory corruption -6. **Reversibility**: User can disable and clear all data instantly - -## Reporting a Vulnerability - -### Critical Vulnerabilities - -If you discover a vulnerability that could: -- Leak real user browsing data -- Enable remote code execution -- Bypass browser sandboxing -- Compromise user privacy - -**Please report IMMEDIATELY via**: - -**Email**: security@example.com (PGP key below) -**Response Time**: Within 48 hours -**Coordinated Disclosure**: 90 days - -### Non-Critical Issues - -For lower-severity issues: -- Open a **private** GitHub Security Advisory -- Or email: security@example.com - -### What to Include - -Please provide: -1. **Description**: What is the vulnerability? -2. **Impact**: What can an attacker do? -3. **Reproduction**: Step-by-step PoC -4. **Environment**: Browser, OS, extension version -5. **Suggested Fix** (optional): How to remediate - -### Example Report Template - -``` -## Vulnerability Report - -**Title**: [Brief description] - -**Severity**: [Critical/High/Medium/Low] - -**Description**: -[Detailed explanation of the vulnerability] - -**Impact**: -- Privacy: [Yes/No - describe] -- Availability: [Yes/No - describe] -- Integrity: [Yes/No - describe] - -**Reproduction Steps**: -1. Install extension version X -2. Enable simulation with profile Y -3. Open developer console -4. Execute: [code/actions] -5. Observe: [vulnerability manifestation] - -**Environment**: -- Extension Version: 0.1.0 -- Browser: Chrome 120.0.6099.109 -- OS: Ubuntu 22.04 LTS - -**Suggested Fix** (optional): -[Your recommendation] - -**Disclosure Preference**: -- Public credit: [Yes/No] -- Name/handle: [If yes to credit] -``` - -## Vulnerability Disclosure Process - -### Timeline - -1. **T+0 hours**: Report received, acknowledge within 48 hours -2. **T+7 days**: Initial assessment and severity classification -3. **T+14 days**: Patch development begins (or explanation if won't fix) -4. **T+30 days**: Patch testing and validation -5. **T+60 days**: Coordinated release (or earlier if urgent) -6. **T+90 days**: Public disclosure (or earlier if exploited in wild) - -### Severity Classification - -| Severity | SLA | Criteria | -|----------|-----|----------| -| **Critical** | 7 days patch | RCE, data exfiltration, sandbox escape | -| **High** | 30 days patch | Privacy leak, privilege escalation | -| **Medium** | 60 days patch | DoS, logic errors, minor data exposure | -| **Low** | 90 days patch | UI spoofing, minor issues | - -### Remediation - -Depending on severity: -- **Critical/High**: Emergency release + blog post + CVE -- **Medium**: Regular release + changelog entry -- **Low**: Bundled in next release - -## Security Testing - -### Automated Testing - -We run: -- **Cargo audit** for Rust dependency vulnerabilities -- **npm audit** for JavaScript dependency vulnerabilities -- **TypeScript strict mode** for type safety -- **Rust borrow checker** for memory safety -- **ESLint security rules** for common JS vulnerabilities - -### Manual Testing - -We encourage: -- Code review of all changes -- WASM sandbox boundary audits -- Storage injection testing -- Permission escalation attempts - -### Fuzzing (Future) - -Planned: -- cargo-fuzz for Rust core -- WASM boundary fuzzing -- Storage API fuzzing - -## Known Issues & Limitations - -### Current Limitations (v0.1.0) - -1. **WASM Integration Incomplete**: Mock implementations in use - - **Risk**: Type mismatches could cause runtime errors - - **Mitigation**: TypeScript strict mode, extensive testing - - **Timeline**: Full integration by v0.2.0 - -2. **No Rate Limiting**: Simulated activities could be excessive - - **Risk**: Resource exhaustion, browser slowdown - - **Mitigation**: User-configurable noise levels, activity caps - - **Timeline**: Rate limiting in v0.3.0 - -3. **Experimental Software**: Not security-audited by third party - - **Risk**: Unknown vulnerabilities may exist - - **Mitigation**: Open source for community review - - **Timeline**: Professional audit planned for v1.0.0 - -### Design Decisions - -**Why no encryption?** -- All data is local-only -- Browser already provides storage encryption -- Adding crypto increases attack surface -- KISS principle - -**Why TypeScript instead of Rust for extension?** -- Browser APIs are JavaScript-native -- WASM has limitations with async Chrome APIs -- TypeScript provides sufficient type safety -- Performance not critical for UI - -**Why allow activity simulation at all?** -- Core feature of the extension -- User explicitly enables it -- Activities are sandboxed (no actual tab opening by default) -- Reversible (can clear all data) - -## Security Features - -### Data Protection - -- **Storage Isolation**: chrome.storage.local (per-extension isolation) -- **No External Calls**: Zero network requests, fully offline -- **Type Safety**: Rust + TypeScript prevent injection -- **Memory Safety**: Rust ownership prevents corruption - -### Runtime Protection - -- **Content Security Policy**: Restrictive CSP in manifest -- **Sandboxed WASM**: No direct system access -- **Permission Minimization**: Only required APIs -- **User Consent**: Explicit enable required - -### Auditability - -- **Open Source**: All code public on GitHub -- **Reproducible Builds**: Deterministic compilation (planned) -- **Signed Releases**: GPG signatures (planned) -- **Build Provenance**: SLSA attestation (planned) - -## Security Resources - -### For Users - -- [Privacy Policy](docs/PRIVACY.md) (TODO) -- [User Security Guide](docs/USER_SECURITY.md) (TODO) -- [FAQ](README.md#faq) - -### For Developers - -- [Secure Coding Guidelines](CONTRIBUTING.md#security) -- [Threat Model](docs/THREAT_MODEL.md) (TODO) -- [Security Architecture](docs/ARCHITECTURE.md) (TODO) - -### External Resources - -- [OWASP Browser Extension Security](https://cheatsheetseries.owasp.org/cheatsheets/Browser_Extension_Security_Cheat_Sheet.html) -- [Chrome Extension Security Best Practices](https://developer.chrome.com/docs/extensions/mv3/security/) -- [WebAssembly Security](https://webassembly.org/docs/security/) - -## PGP Key - -``` ------BEGIN PGP PUBLIC KEY BLOCK----- -Comment: DoubleTrack Browser Security Team -Comment: security@example.com - -[TODO: Add actual PGP public key] - ------END PGP PUBLIC KEY BLOCK----- -``` - -## Hall of Fame - -We gratefully acknowledge security researchers who responsibly disclose vulnerabilities: - -| Researcher | Vulnerability | Severity | Date | Bounty | -|------------|---------------|----------|------|--------| -| *None yet* | - | - | - | - | - -**Note**: We currently do not offer monetary bounties but will provide: -- Public credit (if desired) -- Acknowledgment in release notes -- Co-authorship credit for significant findings -- Eternal gratitude and good karma - -## Contact - -- **Security Email**: security@example.com -- **GPG Fingerprint**: [TODO] -- **Security Advisory**: https://github.com/yourusername/double-track-browser/security/advisories -- **Response SLA**: 48 hours - ---- - -**Last Updated**: 2025-11-22 -**Version**: 1.0 -**Next Review**: 2026-05-22 (6 months) diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..29f0f71 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,201 @@ +== CRG C - Comprehensive Test Coverage + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Status: ACHIEVED + +This document tracks the completion of CRG C grade requirements for +`+double-track-browser+`. + +=== CRG C Requirements + +CRG C requires: - Unit tests (12 existing + inline tests) - Smoke tests +(property-based) - Build tests (cargo test) - P2P (property-based) tests +- E2E (end-to-end) tests - Reflexive tests (not applicable for this +project type) - Contract tests (type contracts in TypeScript) - Aspect +tests (security) - Benchmarks with baselines + +=== Test Coverage Summary + +==== Rust Core (rust_core/) + +===== Unit Tests (12 existing) + +* ✅ `+src/lib.rs::tests+` - Profile generation (1 test) +* ✅ `+src/lib.rs::tests+` - Activity generation (1 test) +* ✅ `+src/activity.rs::tests+` - Activity generation (1 test) +* ✅ `+src/activity.rs::tests+` - Duration generation (1 test) +* ✅ `+src/form_data.rs::tests+` - FormData generation (1 test) +* ✅ `+src/form_data.rs::tests+` - Email format (1 test) +* ✅ `+src/form_data.rs::tests+` - Preferences matching (1 test) +* ✅ `+src/schedule.rs::tests+` - Schedule generation (1 test) +* ✅ `+src/schedule.rs::tests+` - Hour in range (1 test) +* ✅ `+src/interests.rs::tests+` - Search query diversity (1 test) +* ✅ `+src/interests.rs::tests+` - URL generation all types (1 test) + +*Pass rate: 11/11 ✅* + +===== Property-Based Tests (proptest) + +File: `+tests/property_test.rs+` (11 tests) - ✅ Profile names never +empty - ✅ Profile ages in valid range [18, 100] - ✅ Interests list +bounds [1, 20] - ✅ Activity log chronologically ordered - ✅ Activity +durations positive and bounded - ✅ FormData emails always valid format +- ✅ FormData display names never empty - ✅ Generated profiles always +valid - ✅ Schedule has exactly 7 days - ✅ No null bytes in FormData +fields - ✅ Profile IDs valid and unique + +*Pass rate: 11/11 ✅* + +===== End-to-End Tests + +File: `+tests/e2e_test.rs+` (8 tests) - ✅ Full profile lifecycle +(create → serialize → deserialize → validate) - ✅ Profile → Activities +→ FormData pipeline - ✅ Profile schedule consistency - ✅ Activity +stream properties (HTTPS, titles, durations, span) - ✅ FormData email +uniqueness across profiles - ✅ FormData serialization round-trip - ✅ +Activity type distribution - ✅ Large activity generation (1 week, 100+ +activities) + +*Pass rate: 8/8 ✅* + +===== Security/Aspect Tests + +File: `+tests/aspect_test.rs+` (12 tests) - ✅ Oversized input handling +(100KB strings) - ✅ Unicode in profile fields (Spanish, Chinese, Greek, +Emoji) - ✅ XSS payload handling in URLs - ✅ SQL injection patterns in +FormData - ✅ Empty input handling - ✅ Timestamp validity (within 1 +minute) - ✅ Activity timestamp validity (within 2 days) - ✅ Integer +overflow protection - ✅ Activity list consistency - ✅ FormData field +lengths < 255 chars - ✅ No unsafe patterns (null bytes, control chars) +- ✅ Boundary values for activity duration + +*Pass rate: 12/12 ✅* + +==== Browser Extension (TypeScript/Deno) + +===== Unit Type Tests + +File: `+tests/unit/types_test.ts+` (4 tests) - ✅ Extension message +types - ✅ Storage schema validation - ✅ Form data contract - ✅ +Activity log schema + +*Pass rate: 4/4 ✅* + +===== Property-Based Tests + +File: `+tests/property/extension_properties_test.ts+` (9 tests) - ✅ +Profiles never have empty names - ✅ Activities always have HTTPS URLs - +✅ Timestamps are monotonic - ✅ Email format is valid - ✅ No null +bytes in strings - ✅ Message type always defined - ✅ Duration is +always positive - ✅ Interests array never empty - ✅ Activity type is +known + +*Pass rate: 9/9 ✅* + +===== End-to-End Extension Lifecycle + +File: `+tests/e2e/extension_lifecycle_test.ts+` (9 tests) - ✅ Extension +initialization - ✅ Profile creation - ✅ Activity generation - ✅ +Activity accumulation - ✅ Pause and resume - ✅ Configuration +persistence - ✅ Cleanup on uninstall - ✅ State serialization - ✅ +Profile switching + +*Pass rate: 9/9 ✅* + +===== Security Aspect Tests + +File: `+tests/aspect/security_test.ts+` (10 tests) - ✅ XSS prevention +in URL display - ✅ Content isolation (sandboxing) - ✅ HTTPS +enforcement - ✅ Message validation - ✅ Origin verification - ✅ No +plain HTTP for sensitive operations - ✅ No sensitive data in logs - ✅ +CSP headers enforcement - ✅ Timestamp validation - ✅ Permission +boundaries + +*Pass rate: 10/10 ✅* + +=== Test Summary + +[width="100%",cols="36%,24%,20%,20%",options="header",] +|=== +|Category |Tests |Pass |File +|Rust Unit |11 |11 |src/**/*.rs +|Rust Property |11 |11 |tests/property_test.rs +|Rust E2E |8 |8 |tests/e2e_test.rs +|Rust Aspect |12 |12 |tests/aspect_test.rs +|TypeScript Unit |4 |4 |tests/unit/types_test.ts +|TypeScript Property |9 |9 |tests/property/extension_properties_test.ts +|TypeScript E2E |9 |9 |tests/e2e/extension_lifecycle_test.ts +|TypeScript Aspect |10 |10 |tests/aspect/security_test.ts +|*TOTAL* |*74* |*74* |— +|=== + +*Overall Pass Rate: 100% (74/74 ✅)* + +=== Benchmarks + +==== Criterion Benchmarks (rust_core/benches/core_bench.rs) + +The following benchmark suites have been configured and are ready to +run: + +* `+profile_generation_with_seed+` - Profile generation performance with +deterministic seed +* `+profile_generation_random+` - Profile generation with random entropy +* `+profile_to_json+` - Serialization throughput +* `+json_to_profile+` - Deserialization throughput +* `+activity_generation+` - Activity generation for 1h, 24h, 72h +durations +* `+activity_scaling+` - Scaling benchmark for 100, 1000, 10000 activity +targets +* `+formdata_generation+` - Form data generation performance +* `+schedule_generation+` - Schedule creation performance +* `+profile_validation+` - Profile validation throughput +* `+activity_type_variety+` - Activity diversity generation (1h, 12h, +24h) +* `+full_pipeline+` - End-to-end pipeline (profile + activities + form + +schedule + serialize) + +*Run with:* `+cargo bench --manifest-path rust_core/Cargo.toml+` + +=== Code Quality + +==== Language Policy Compliance + +* ✅ Rust for core (WASM-compiled) +* ✅ AffineScript for browser (type-safe, compiles to JS) +* ✅ Deno for testing (no npm) +* ✅ MPL-2.0 license headers on all files +* ✅ No TypeScript (uses AffineScript) +* ✅ No Node.js (uses Deno) + +==== Test Characteristics + +* ✅ No panics or unwraps without context +* ✅ Property-based invariant testing +* ✅ End-to-end pipeline validation +* ✅ Security aspect coverage (XSS, SQL injection, overflow, etc.) +* ✅ Type contract enforcement +* ✅ Serialization round-trip validation +* ✅ Deterministic seeding for reproducibility + +=== Smoke Tests Passing + +Run with: `+deno task test+` (TypeScript) + `+cargo test+` (Rust) + +All tests pass without warnings (except one unused variable warning +which is acceptable). + +=== CRG Grade: C + +✅ *All CRG C requirements satisfied:* - Unit tests: 15 (11 existing + 4 +new) - Smoke tests: 24 property-based tests - Build tests: Cargo build +integration - P2P tests: 11 proptest + 9 TypeScript property tests - E2E +tests: 8 Rust + 9 TypeScript (17 total) - Contract tests: 4 TypeScript +unit + 9 property tests - Aspect tests: 12 Rust security + 10 TypeScript +security (22 total) - Benchmarks: 11 criterion benchmarks configured and +ready + +*Next Steps for Higher Grades:* - *CRG B*: Add fuzzing harness +(fuzz/fuzzer.rs), stress tests, mutation testing - *CRG A*: Add formal +proofs (Idris2 ABI verification), adversarial testing, security audit diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 8a103ce..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,216 +0,0 @@ -# CRG C - Comprehensive Test Coverage - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Status: ACHIEVED - -This document tracks the completion of CRG C grade requirements for `double-track-browser`. - -## CRG C Requirements - -CRG C requires: -- Unit tests (12 existing + inline tests) -- Smoke tests (property-based) -- Build tests (cargo test) -- P2P (property-based) tests -- E2E (end-to-end) tests -- Reflexive tests (not applicable for this project type) -- Contract tests (type contracts in TypeScript) -- Aspect tests (security) -- Benchmarks with baselines - -## Test Coverage Summary - -### Rust Core (rust_core/) - -#### Unit Tests (12 existing) -- ✅ `src/lib.rs::tests` - Profile generation (1 test) -- ✅ `src/lib.rs::tests` - Activity generation (1 test) -- ✅ `src/activity.rs::tests` - Activity generation (1 test) -- ✅ `src/activity.rs::tests` - Duration generation (1 test) -- ✅ `src/form_data.rs::tests` - FormData generation (1 test) -- ✅ `src/form_data.rs::tests` - Email format (1 test) -- ✅ `src/form_data.rs::tests` - Preferences matching (1 test) -- ✅ `src/schedule.rs::tests` - Schedule generation (1 test) -- ✅ `src/schedule.rs::tests` - Hour in range (1 test) -- ✅ `src/interests.rs::tests` - Search query diversity (1 test) -- ✅ `src/interests.rs::tests` - URL generation all types (1 test) - -**Pass rate: 11/11 ✅** - -#### Property-Based Tests (proptest) -File: `tests/property_test.rs` (11 tests) -- ✅ Profile names never empty -- ✅ Profile ages in valid range [18, 100] -- ✅ Interests list bounds [1, 20] -- ✅ Activity log chronologically ordered -- ✅ Activity durations positive and bounded -- ✅ FormData emails always valid format -- ✅ FormData display names never empty -- ✅ Generated profiles always valid -- ✅ Schedule has exactly 7 days -- ✅ No null bytes in FormData fields -- ✅ Profile IDs valid and unique - -**Pass rate: 11/11 ✅** - -#### End-to-End Tests -File: `tests/e2e_test.rs` (8 tests) -- ✅ Full profile lifecycle (create → serialize → deserialize → validate) -- ✅ Profile → Activities → FormData pipeline -- ✅ Profile schedule consistency -- ✅ Activity stream properties (HTTPS, titles, durations, span) -- ✅ FormData email uniqueness across profiles -- ✅ FormData serialization round-trip -- ✅ Activity type distribution -- ✅ Large activity generation (1 week, 100+ activities) - -**Pass rate: 8/8 ✅** - -#### Security/Aspect Tests -File: `tests/aspect_test.rs` (12 tests) -- ✅ Oversized input handling (100KB strings) -- ✅ Unicode in profile fields (Spanish, Chinese, Greek, Emoji) -- ✅ XSS payload handling in URLs -- ✅ SQL injection patterns in FormData -- ✅ Empty input handling -- ✅ Timestamp validity (within 1 minute) -- ✅ Activity timestamp validity (within 2 days) -- ✅ Integer overflow protection -- ✅ Activity list consistency -- ✅ FormData field lengths < 255 chars -- ✅ No unsafe patterns (null bytes, control chars) -- ✅ Boundary values for activity duration - -**Pass rate: 12/12 ✅** - -### Browser Extension (TypeScript/Deno) - -#### Unit Type Tests -File: `tests/unit/types_test.ts` (4 tests) -- ✅ Extension message types -- ✅ Storage schema validation -- ✅ Form data contract -- ✅ Activity log schema - -**Pass rate: 4/4 ✅** - -#### Property-Based Tests -File: `tests/property/extension_properties_test.ts` (9 tests) -- ✅ Profiles never have empty names -- ✅ Activities always have HTTPS URLs -- ✅ Timestamps are monotonic -- ✅ Email format is valid -- ✅ No null bytes in strings -- ✅ Message type always defined -- ✅ Duration is always positive -- ✅ Interests array never empty -- ✅ Activity type is known - -**Pass rate: 9/9 ✅** - -#### End-to-End Extension Lifecycle -File: `tests/e2e/extension_lifecycle_test.ts` (9 tests) -- ✅ Extension initialization -- ✅ Profile creation -- ✅ Activity generation -- ✅ Activity accumulation -- ✅ Pause and resume -- ✅ Configuration persistence -- ✅ Cleanup on uninstall -- ✅ State serialization -- ✅ Profile switching - -**Pass rate: 9/9 ✅** - -#### Security Aspect Tests -File: `tests/aspect/security_test.ts` (10 tests) -- ✅ XSS prevention in URL display -- ✅ Content isolation (sandboxing) -- ✅ HTTPS enforcement -- ✅ Message validation -- ✅ Origin verification -- ✅ No plain HTTP for sensitive operations -- ✅ No sensitive data in logs -- ✅ CSP headers enforcement -- ✅ Timestamp validation -- ✅ Permission boundaries - -**Pass rate: 10/10 ✅** - -## Test Summary - -| Category | Tests | Pass | File | -|----------|-------|------|------| -| Rust Unit | 11 | 11 | src/**/*.rs | -| Rust Property | 11 | 11 | tests/property_test.rs | -| Rust E2E | 8 | 8 | tests/e2e_test.rs | -| Rust Aspect | 12 | 12 | tests/aspect_test.rs | -| TypeScript Unit | 4 | 4 | tests/unit/types_test.ts | -| TypeScript Property | 9 | 9 | tests/property/extension_properties_test.ts | -| TypeScript E2E | 9 | 9 | tests/e2e/extension_lifecycle_test.ts | -| TypeScript Aspect | 10 | 10 | tests/aspect/security_test.ts | -| **TOTAL** | **74** | **74** | — | - -**Overall Pass Rate: 100% (74/74 ✅)** - -## Benchmarks - -### Criterion Benchmarks (rust_core/benches/core_bench.rs) - -The following benchmark suites have been configured and are ready to run: - -- `profile_generation_with_seed` - Profile generation performance with deterministic seed -- `profile_generation_random` - Profile generation with random entropy -- `profile_to_json` - Serialization throughput -- `json_to_profile` - Deserialization throughput -- `activity_generation` - Activity generation for 1h, 24h, 72h durations -- `activity_scaling` - Scaling benchmark for 100, 1000, 10000 activity targets -- `formdata_generation` - Form data generation performance -- `schedule_generation` - Schedule creation performance -- `profile_validation` - Profile validation throughput -- `activity_type_variety` - Activity diversity generation (1h, 12h, 24h) -- `full_pipeline` - End-to-end pipeline (profile + activities + form + schedule + serialize) - -**Run with:** `cargo bench --manifest-path rust_core/Cargo.toml` - -## Code Quality - -### Language Policy Compliance -- ✅ Rust for core (WASM-compiled) -- ✅ AffineScript for browser (type-safe, compiles to JS) -- ✅ Deno for testing (no npm) -- ✅ MPL-2.0 license headers on all files -- ✅ No TypeScript (uses AffineScript) -- ✅ No Node.js (uses Deno) - -### Test Characteristics -- ✅ No panics or unwraps without context -- ✅ Property-based invariant testing -- ✅ End-to-end pipeline validation -- ✅ Security aspect coverage (XSS, SQL injection, overflow, etc.) -- ✅ Type contract enforcement -- ✅ Serialization round-trip validation -- ✅ Deterministic seeding for reproducibility - -## Smoke Tests Passing - -Run with: `deno task test` (TypeScript) + `cargo test` (Rust) - -All tests pass without warnings (except one unused variable warning which is acceptable). - -## CRG Grade: C - -✅ **All CRG C requirements satisfied:** -- Unit tests: 15 (11 existing + 4 new) -- Smoke tests: 24 property-based tests -- Build tests: Cargo build integration -- P2P tests: 11 proptest + 9 TypeScript property tests -- E2E tests: 8 Rust + 9 TypeScript (17 total) -- Contract tests: 4 TypeScript unit + 9 property tests -- Aspect tests: 12 Rust security + 10 TypeScript security (22 total) -- Benchmarks: 11 criterion benchmarks configured and ready - -**Next Steps for Higher Grades:** -- **CRG B**: Add fuzzing harness (fuzz/fuzzer.rs), stress tests, mutation testing -- **CRG A**: Add formal proofs (Idris2 ABI verification), adversarial testing, security audit diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 88% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index c7f009c..9140904 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== DoubleTrack Browser — Project Topology -# DoubleTrack Browser — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ USER / BROWSER │ │ (Real & Fictional Personas) │ @@ -42,11 +38,11 @@ │ Deno Tooling .machine_readable/ │ │ wasm-pack RSR Gold (91%) │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── IDENTITY ENGINE (RUST) @@ -66,25 +62,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: █████████░ ~90% v0.1.0 RSR Gold Compliant -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Profile Gen ──────► Simulator ──────► Background Script ──────► Browser API │ │ │ │ ▼ ▼ ▼ ▼ Rust Core ──────► WASM Bridge ──────► AffineScript UI ─────────► User Dashboard -``` +.... -## Update Protocol +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file +[arabic] +. *After completing a component*: Change its bar and percentage +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *Date*: Update the `+Last updated+` comment at the top of this file -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments). diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..a6d1d30 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — double-track-browser — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+MEDIUM+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+NONE+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |233 +|`+docs/+` files |2 +|`+docs/+` LoC |627 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +233 lines has likely grown to do the work of `+docs/+` — split it into a +thin README + `+docs/architecture.md+`, `+docs/usage.md+`, etc. +Heavy-wiki exemplars to copy from: `+affinescript+`, `+boj-server+`, +`+echidna+`, `+hypatia+`. + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index 00ea160..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Tech-Debt Audit — double-track-browser — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `MEDIUM`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `NONE` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 233 | -| `docs/` files | 2 | -| `docs/` LoC | 627 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 233 lines has likely grown to do the work of `docs/` — split it into a thin README + `docs/architecture.md`, `docs/usage.md`, etc. Heavy-wiki exemplars to copy from: `affinescript`, `boj-server`, `echidna`, `hypatia`. - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/icons/README.adoc b/icons/README.adoc new file mode 100644 index 0000000..d131efb --- /dev/null +++ b/icons/README.adoc @@ -0,0 +1,29 @@ +== Extension Icons + +This directory contains the icon assets for DoubleTrack Browser. + +=== Required Sizes + +The extension requires icons in the following sizes: - 16x16 - Toolbar +icon - 32x32 - Toolbar icon (retina) - 48x48 - Extension management page +- 128x128 - Chrome Web Store + +=== Creating Icons + +To create proper icons, use a tool like: - Figma - Adobe Illustrator - +Inkscape (free) + +Design guidelines: - Use a simple, recognizable symbol - Consider a +"`double track`" or "`parallel lines`" motif - Colors should work well +on light and dark backgrounds - Maintain good contrast for visibility + +=== Placeholder Icons + +Currently using placeholder icons. Replace these with proper designed +icons before release. + +=== Icon Theme + +Suggested theme: Two parallel paths or tracks, representing the dual +nature of browsing (real + fictional). Colors could include blues and +purples matching the extension’s UI theme. diff --git a/icons/README.md b/icons/README.md deleted file mode 100644 index 98e57e7..0000000 --- a/icons/README.md +++ /dev/null @@ -1,32 +0,0 @@ -# Extension Icons - -This directory contains the icon assets for DoubleTrack Browser. - -## Required Sizes - -The extension requires icons in the following sizes: -- 16x16 - Toolbar icon -- 32x32 - Toolbar icon (retina) -- 48x48 - Extension management page -- 128x128 - Chrome Web Store - -## Creating Icons - -To create proper icons, use a tool like: -- Figma -- Adobe Illustrator -- Inkscape (free) - -Design guidelines: -- Use a simple, recognizable symbol -- Consider a "double track" or "parallel lines" motif -- Colors should work well on light and dark backgrounds -- Maintain good contrast for visibility - -## Placeholder Icons - -Currently using placeholder icons. Replace these with proper designed icons before release. - -## Icon Theme - -Suggested theme: Two parallel paths or tracks, representing the dual nature of browsing (real + fictional). Colors could include blues and purples matching the extension's UI theme. diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..c875065 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — double-track-browser (Developer) + +=== What is double-track-browser? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index e0084f1..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — double-track-browser (Developer) - -## What is double-track-browser? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..0f87eab --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — double-track-browser (User) + +=== What is double-track-browser? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index fac9ab9..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — double-track-browser (User) - -## What is double-track-browser? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture