Haketilo

*Note: this is derived from the project plan prepared in relation to NLnet grant received by Haketilo/Hydrilla*

# Project plan Haketilo/Hydrilla

At the time of this writing the browser extension Haketilo and its repository, Hydrilla, have already

seen their initial 0.1 demo releases. Below is a plan for their further development that will use the

experience gained during initial prototyping to increase stability and supply functionalities that have

been missing or provisional only, as well as make the tools available to a wider audience, more

secure and easier to use.

{{toc}}

## 1. ~~Haketilo and Hydrilla 1.0 pre-release~~ (#103)

Some big code changes to land in Haketilo and Hydrilla 1.0 will be available in a pre-release. The

pre-release will be made before delivery of several other side artifacts planned for 1.0.

##### Milestones

* ~~project plan~~[^1_prplan]

* ~~tentative software bill of materials~~[^1_bom_haketilo][^1_bom_hydrilla]

* ~~use of registerContentScript API in Firefox Haketilo port~~ (#92)[^1_haketilo_buildable_again]

* ~~move to the new Hydrilla JSON API prototyped at [https://hydrillabugs.koszko.org/projects/hydrilla/wiki/Repository_API

](/projects/hydrilla/wiki/Repository_API)~~[^1_haketilo_buildable_again]

* ~~most WebExtension storage.local uses replaced with IndexedDB~~ (#98)[^1_haketilo_buildable_again]

* ~~Python implementation of Hydrilla~~[^1_python_hydrilla]

[^1_prplan]: [[Roadmap|this very document]]

[^1_bom_haketilo]: [[Haketilo Software Bill of Materials]]

[^1_bom_hydrilla]: [[hydrilla:Hydrilla Software Bill of Materials]]

[^1_haketilo_buildable_again]: [commit 4c6a2323d90e9321ec2b78e226167b3013ea69ab](/projects/haketilo/repository/haketilo/revisions/4c6a2323d90e9321ec2b78e226167b3013ea69ab)

[^1_python_hydrilla]: [Hydrilla](/projects/hydrilla/repository/hydrilla) and [Hydrilla builder](/projects/hydrilla/repository/hydrilla-builder) repositories

## ~~2. Haketilo and Hydrilla 1.0 release (#104)~~

This will be the first release since receiving the NLnet grant and the first non-demo

release, hence it includes many improvements in various fields.

##### Milestones

* ~~basic automated Haketilo tests using Selenium and a Firefox-based web browser~~ (#66)

* ~~JSON schemas describing Hydrilla on-disk resource format, Hydrilla HTTP API and other JSON interfaces in use~~[^2_schemas_repo]

* ~~validation of all external JSON data in Haketilo and Hydrilla using included JSON schemas~~ (#105)[^2_schemas_used_haketilo]

* ~~sample Apache2 configuration file for use with Hydrilla~~ (#55)[^2_apache2_configs_added]

* ~~detailed documentation for installation and running of Hydrilla~~ (#55)[^2_hydrilla_user_manual]

* ~~manpage for Hydrilla~~ (#55)[^2_manpages]

[^2_schemas_repo]: [JSON schemas](/projects/hydrilla/repository/hydrilla-json-schemas) repository

[^2_schemas_used_haketilo]: [commit 57ce414ca81682a71288018a4d9001604002ec23 ](/projects/haketilo/repository/haketilo/revisions/57ce414ca81682a71288018a4d9001604002ec23)

[^2_apache2_configs_added]: [commit ea6afb92048c835752fe1c72ad52f424e2df88a8](/projects/hydrilla/repository/hydrilla/revisions/ea6afb92048c835752fe1c72ad52f424e2df88a8)

[^2_hydrilla_user_manual]: [[hydrilla:User manual]]

[^2_manpages]: [commit 1cb6aaae2055283d04aa0aa581e82addb8049ce4](/projects/hydrilla/repository/hydrilla/revisions/1cb6aaae2055283d04aa0aa581e82addb8049ce4) and [commit 363cbbb6a9fac49a377d8fa13ffede1483feabd5](/projects/hydrilla/repository/hydrilla-builder/revisions/363cbbb6a9fac49a377d8fa13ffede1483feabd5)

##### Estimated time

1.5 weeks

## 3. Distribution of Hydrilla and (when applicable) Haketilo in package managers (#106)

It is beneficial to have tools available in a format specific to various operating system distributions.

While the process of inclusion in official repositories is often a complex and lengthy one, preparing

the actual packages, as is the goal of this task, is a good first step to making that happen.

##### Milestones

* .deb packaging of Haketilo and Hydrilla[^3_debian_packaging]

* Nix packaging of Hydrilla

* Pacman PKGBUILDs for Haketilo and Hydrilla

* Guix packaging of Haketilo and Hydrilla

* RPM packaging of Haketilo and Hydrilla

[^3_debian_packaging]: [APT repository](http://hydrillarepos.koszko.org/apt/) and debian package git branches ([Hydrilla](/projects/hydrilla/repository/hydrilla?rev=debian-debian) and [Hydrilla builder](/projects/hydrilla/repository/hydrilla-builder?rev=debian-debian))

##### Estimated time

2 weeks

## 4. Development of Hydrilla website part (#35)

A project's website makes its first impression, and therefore deserves special care. In our case the

website will be part of our software Hydrilla.

##### Milestones

* planning a site structure

* designing a landing page

* cross-reference with Hydrilla to ensure uniformity of design and compatibility with the on-disk format

* crafting of text, graphics, and any other media

* assembly of website

##### Estimated time

2 weeks

## 5. ~~Development of a user-controlled captcha client~~ (#107)

Haketilo's goal is to give internet users control over their browsing. Replacing proprietary,

privacy-hostile client-side programs is part of that. A tool similar to the librecaptcha Python program

is needed, but in the form of a JavaScript library.

##### Milestones

* ~~facility for Haketilo-supplied scripts to bypass CORS~~[^5_bypass_cors]

* ~~free/libre JavaScript library for solving reCAPTCHA challenges~~[^5_recaptcha_client]

* ~~sample Haketilo resource making use of the library on a chosen website~~[^5_recaptcha_client_sample_script]

[^5_bypass_cors]: [Haketilo release v2.0-beta1](/news/13)

[^5_recaptcha_client]: [Hacktcha release 2022.6.21](https://git.koszko.org/haketilo-packages/hacktcha/tag/?h=v2022.6.21)

[^5_recaptcha_client_sample_script]: [Hacktcha demo script](https://git.koszko.org/haketilo-packages/hacktcha/tree/captcha-demo.js?h=v2022.6.21)

##### Estimated time

3 weeks

## 6. Permissions system for Haketilo-supplied resources (#73)

Custom, user-supplied resources Haketilo may deploy on viewed pages might require looser

restrictions than those normally employed on pages. Or, they might allow for tighter security

mechanisms to be employed.

##### Milestones

* specification of a new revision of Hydrilla API and on-disk format with permissions support[^6_hydrilla_api]

* facility to limit domains for which a Haketilo-supplied script is allowed to bypass CORS

* facility to specify what custom Content Security Policy should be used on a given pages (#88)

[^6_hydrilla_api]: [commit 7206db45f277c10c34d1b7ed9bd35343ac742d30](/projects/hydrilla/repository/hydrilla-json-schemas/revisions/7206db45f277c10c34d1b7ed9bd35343ac742d30)

##### Estimated time

2 weeks

## 7. Further means of user-controlled customization of sites (#108)

Besides the initial function of replacing sites' JavaScript it is also desired to facilitate supplying

additional data (e.g. images) and replacing other site components.

##### Milestones

* facility to make arbitrary bundled data files accessible to Haketilo-supplied scripts (#69)

* facility to replace the entire interface of a web page with user-supplied HTML (#70)

* facility to add user-supplied CSS to a web page

* facility to add user-supplied fonts to a web page

##### Estimated time

3 weeks

## 8. 50 sample site resources for Haketilo (#109)

To build the community its purpose depends on, Hydrilla must be clearly ready for use. This

requires a representative, well-stocked library of packages.

##### Milestones

* guide describing how to make and contribute custom site resources to Hydrilla

* at least 5 alternative site interfaces

* JavaScript of at least 10 free/libre web tools (like Etherpad, Ethercalc) repackaged to be run in a user-controlled way from Haketilo

* at least 50 different custom site resources in total

##### Estimated time

2 weeks

## 9. ~~Haketilo LibrePlanet presentation~~ (#110)

LibrePlanet is a conference organized by the Free Software Foundation (FSF). It is "an opportunity

to meet and interact with other people with both a technical and non technical background" and to

share experience.

##### Milestones

* ~~applied to LibrePlanet 2022~~

* ~~prepared presentation about giving users back the control over web browsing~~

* ~~made the presentation at LibrePlanet 2022 (if accepted there) or posted a video presentation on Haketilo website (as a fallback case)~~[^lp2022]

[^lp2022]: https://libreplanet.org/2022/speakers/#5790

## 10. Localization of Haketilo and Hydrilla

To truly empower to web users all over the world, Haketilo, Hydrilla, and all associated materials

must be able to support languages from across the world.

##### Milestones

* automatic content language negotiation on Hydrilla pages and the website

* language selection option on Hydrilla pages and the website

* internationalization of Haketilo (#51)

* language selection option in Haketilo

* Polish translation

##### Estimated time

3 weeks

## 11. Security vetting of Haketilo and Hydrilla

As NLNet-funded projects, Haketilo and Hydrilla have the privilege of a security review from

Radically Open Security. To make use of this opportunity, we will ensure any findings provided are

properly addressed.

##### Milestones

* action on any recommendations or other findings

* report of how each finding from the vetting was addressed, and why

* note of any key issues in the developer documentation, in order to avoid repetition in the future

##### Estimated time

2 weeks

## 12. Accessibility vetting of Haketilo and Hydrilla

To empower every web user, Haketilo and Hydrilla must support the interfaces they need.

##### Milestones

* action on any recommendations or other findings

* report of how each finding from the vetting was addressed, and why

* note of any key issues in the developer documentation, in order to avoid repetition in the future

* certified WCAG accessible

##### Estimated time

2 weeks

## 13. Manifest V3 Haketilo port

Although highly controversial, the Manifest V3 extension format seems unavoidable.

##### Milestones

* background page replaced with Service Workers

* blocking webRequest operations replaced with declarativeNetRequest

* Haketilo working under a Chromium-based browser as a Manifest V3 extension

##### Estimated time

4 weeks

## 14. Tighter testing of Haketilo

Testing in multiple browser environments is important to ensure stability of the extension.

##### Milestones

* automated tests under each supported extension platform with at least 1 Firefox-based and Chromium-based platform

* integration tests of communication between Haketilo and a Hydrilla instance

##### Estimated time

2 weeks

## 15. More thorough documentation of Haketilo and Hydrilla internals

With codebase refactored and stabilized, a worthy thing is to have it properly described for others

to hack on.

##### Milestones

* graphical diagram(s) describing execution contexts in Haketilo and the way scripts running in various context communicate

* graphical diagram(s) describing the algorithm for querying by Haketilo URL patterns

* comprehensive description of strategies employed and APIs used for replacing scripts and CSP in Haketilo

* graphical diagram describing how entities (resources, mappings, licenses) depend on each another

* docstring documentation of every Python function

* HTML documentation generated from Python source code

* JSDoc description of every Haketilo JavaScript function exported from file

* HTML documentation generated from JavaScript source code

##### Estimated time

2 weeks

## 16. Tooling for building of site resources

Simple scripts don't require building before distribution. Wasm modules and bigger libraries do. For

users to control the resources they use in Haketilo, there needs to be some well-defined way of

accessing the sources and repeating the build process.

##### Milestones

* specification of Haketilo source package format

* ability to specify other programs the build process depends on

* software to automatically build a Haketilo source package

##### Estimated time

2 weeks

## 17. Package signing in Haketilo and Hydrilla

Haketilo uses encrypted HTTPS connections to query Hydrilla API. However, to boost the security

and enable use of mirrors, we plan to also use PGP signatures on site resources served.

##### Milestones

* specification of a new revision of Hydrilla API and on-disk format with PGP signatures support

* tool for batch signing of site resources

* Hydrilla support for serving PGP signatures

* Haketilo support for downloading and verifying PGP signatures

* facility to manage trusted public keys within Haketilo

##### Estimated time

3 weeks

## 18. Support for custom meta-sites in Haketilo/Hydrilla

Allowing users to modify pages loaded by their browsers is our goal. Allowing them to aggregate

content from many sites on one page is a natural extension of it. Just as is allowing them to run

static web apps without having to trust some website serving them.

##### Milestones

* specification of a new revision of Hydrilla API and on-disk format with meta-sites support

* support for meta-sites in Hydrilla and Haketilo (#72)

##### Estimated time

3 weeks

## 19. Easier content management and editing within Haketilo (I)

Easy configuring and editing of site resource bundles is Haketilo's raison d'être. To definitively

meet this expectation, any shortcomings must be identified and rethought.

##### Milestones

* testing with untrained users/consultation with "UX experts"

* identified annoying quirks/problems

* comparison with UIs of similar extensions

* designed alternatives to identified problems

* user interface mock

* a compiled plan for UI changes

##### Estimated time

2 weeks

## 20. Easier content management and editing within Haketilo (II)

The previously compiled plan and carefully-prepared user interface mocks will direct the

implementation efforts.

##### Milestones

* new Haketilo settings page interface implementation following the plan

* new Haketilo popup page implementation following the plan

* automated Haketilo GUI tests

##### Estimated time

2 weeks

## 21. REUSE specification compliance

License terms of software projects' files should be unambiguous and easy to analyze by humans

and computers alike. Compliance with the REUSE specification helps ensure that.

##### Milestones

* REUSE compliance in Hydrilla repository

* REUSE compliance in project website repository

* REUSE compliance in Haketilo repository

* REUSE compliance in custom site resources repository(ies)

##### Estimated time

1 week

## 22. Integrity constraints in Haketilo **(optional)**

One Haketilo custom site resource may depend on another, but initial versions of Haketilo did not

verify that dependencies are present. This and other sanity checks can be employed.

##### Milestones

* dependency checks when "installing" or upgrading a custom resource in Haketilo

* dependency checks when removing a custom resource from Haketilo

* facility for cascade removal

* validation of Haketilo URL patterns and other values typed in by the user

##### Estimated time

1 week

## 23. Sample meta-sites for Haketilo/Hydrilla **(optional)**

Running a static webapp like litewrite by visiting its website relies on the security of TLS and

network connectivity. Having it packaged as a separate browser extension requires giving it

excessive permissions. Running it from an HTML file is inconvenient.

##### Milestones

* at least 5 existing webapps packaged as meta-sites

* at least 5 meta-sites aggregating content from various client websites

##### Estimated time

3 weeks

## 24. Haketilo build system runnable from the browser **(optional)**

For portability of Haketilo's POSIX shell-based build system we avoided depending on Node.js,

NPM and similar tools. However, an even more portable alternative exists - to contain the build

system inside a standalone HTML page.

##### Milestones

* JavaScript-based build system in an HTML page (#47)

* facility to run the JavaScript-based build system from the command line

##### Estimated time

2 weeks

## 25. User upload of content to Hydrilla website **(optional)**

To be able to easier gather and share custom site resources within the community, we need a

user-friendly platform.

##### Milestones

* registrations on a Hydrilla instance

* upload of custom site resources to a Hydrilla instance

* facility to easily and efficiently moderate the content uploaded by users

##### Estimated time

3 weeks

## 26. Further development of Hydrilla platform **(optional)**

Users should be able to share not only custom site resources but also their opinions about them.

##### Milestones

* support for user comments

* support for user ratings

* support for flagging site resources that are broken or have other issues

* development of comment quality control systems and policies

##### Estimated time

2 weeks

## 27. Facility for setting up Hydrilla repository mirrors **(optional)**

While allowing users to set up independent instances of Hydrilla gives them greater control over

site content they use, it does not by itself increase the robustness and maximum throughput of

Hydrilla platform. Enabling the use of mirrors does.

##### Milestones

* support for setting up and automatically synchronizing Hydrilla mirrors

* support for announcing available mirrors in Hydrilla

* support for fetching repository mirrors list in Haketilo

* support for distributing requests over multiple repository mirrors in Haketilo

* documentation

##### Estimated time

2 weeks

## 28. 150 sample site resources for Haketilo **(optional)**

To maintain community growth and participation, Hydrilla's collection must be visibly alive and

evolve with Haketilo's feature set.

##### Milestones

* at least 20 alternative site interfaces

* at least 20 existing webapps packaged as meta-sites

* at least 150 custom site resources in total

##### Estimated time

2 weeks

## 29. 200 sample site resources for Haketilo **(optional)**

To maintain community growth and participation, Hydrilla's collection must be visibly alive and

evolve with Haketilo's feature set.

##### Milestones

* at least 20 accessibility-improving site changes

* at least 10 meta-sites aggregating content from various client websites

* at least 200 custom site resources in total

##### Estimated time

2 weeks

## 30. Automated building of Haketilo source packages uploaded to Hydrilla **(optional)**

Requiring packagers to upload compiled code places an extra burden on them, and complicates

reproducibility. Hydrilla should be able to build from source packages.

##### Milestones

* Hydrilla automated resource builds feature

* security consultation of the feature

##### Estimated time

2 weeks

## 31. Self-documented Haketilo **(optional)**

Now matter how user-friendly the graphical interface is, an explanation of some of the concepts

might be needed. The next step, after having the documentation available on the project website,

is bundling it with the extension itself.

##### Milestones

* Haketilo popup self-documented inline

* Haketilo settings page self-documented inline

* documentation included as extension-bundled HTML pages

##### Estimated time

2 weeks

## 32. Displaying Hypothesis annotations for given site **(optional)**

Haketilo makes site resources for websites you visit available in only a few clicks. It would be

useful to have the same capacity for comments. The established, libre https://hypothes.is/ provides

a framework for this.

##### Milestones

* support for displaying current site's Hypothesis annotations in the popup

* support for adding adding Hypothesis annotations in Haketilo

##### Estimated time

2 weeks

## 33. Automatic generation of independent browser extensions from Haketilo site resources **(optional)**

Haketilo's rich feature set might also be an inconvenience. It may be overwhelming or irritating to

some users and has a higher risk of breaking with newer browser versions than a simple extension

would have. Thus, an option to install just a single Haketilo resource in the browser would be

useful.

##### Milestones

* automatic generation of Firefox WebExtensions from Haketilo site resources

* automatic generation of Chromium ManifestV3 WebExtensions from Haketilo site resources

##### Estimated time

2 weeks

## 34. Facility to automatically convert page's "native" scripts to a Haketilo resource **(optional)** (#6)

Haketilo gives users control over scripts being executed on a given web page. The scripts to be

used need to be defined in Haketilo as a resource. Doing this manually might be time-consuming

for a user who aims to use mostly the same JavaScript a website normally serves, but served from

within Haketilo.

##### Milestones

* automatic conversion of page's inline scripts in a Haketilo resource

* inclusion of page's external scripts in generated resource

* inclusion of page's intrinsic JavaScript events in generated resource (#7)

* displaying warnings when a site's JavaScript is known to use mechanisms that might stop

  such automatic package from working properly

##### Estimated time

3 weeks

## 35. Use of a standalone JavaScript engine to perform unit tests in Haketilo **(optional)**

A Selenium-driven web browser is currently used to test parts of Haketilo. Those tests that don't

rely on browser APIs could as well be run outside of browser which would save time during tests.

##### Milestones

* selected the JavaScript engine to use for testing

* facilitated writing Haketilo tests against the chosen engine

* applicable existing tests modified to be run without a web browser

##### Estimated time

2 weeks

## 36. Supplemental anti-bot measures in Hydrilla **(optional)**

Limiting the number of allowed registrations and content uploads is our planned basic way to

prevent Hydrilla instances from being harmed by automated requests. Another measures can be

added to further improve platform's resilience.

##### Milestones

* email-verified registrations

* selected an ethical, privacy-friendly captcha solution

* implementation of the chosen captcha solution

##### Estimated time

2 weeks

## 37. Support for external user authentication mechanisms in Hydrilla **(optional)**

It should be possible to run Hydrilla as part of a bigger web service. Users should be able to use

the same set of credentials for logging in in various parts of such service.

##### Milestones

* selected an authentication mechanism to support

* implementation of the feature

##### Estimated time

1 week

## 38. Support for building Hydrilla and Haketilo using Autotools **(optional)**

The specificity of Haketilo and Hydrilla means a complex build system like Autotools is not

necessary. It could, however, be added as optional to supplement their simple build mechanisms.

##### Milestones

* Hydrilla buildable with Autotools

* Hydrilla out-of-source builds possible

* Hydrilla tarball producible with a make rule

* Haketilo buildable with Autotools

* Haketilo out-of-source builds possible

* Haketilo tarball producible with a make rule

##### Estimated time

1 week

## 39. Evaluation of non-WebExtension platforms for the purpose of porting Haketilo **(optional)**

WebExtensions are really a convenient platform for developing software that empowers users. But

this platform is also tightly controlled by big organizations and has some serious limitations and

shortcomings.

##### Milestones

* evaluation of existing Webkit-based browsers

* evaluation of XUL extensions platform still used in some Firefox forks

* prepared evaluation report

##### Estimated time

1 week

## 40. Development of the first non-WebExtension Haketilo port **(optional)**

Users suffer a vendor lock-in with few mainstream web browsers. Lack of their favorite extensions

is what stops them from switching to more user-controlled alternatives. Haketilo should not

contribute to that problem.

##### Milestones

* selection of a target platform based on previous evaluation

* specification of tasks

* development roadmap

* prototype

* automated tests

* developer documentation

* user documentation

##### Estimated time

7.5 weeks