jetforce/CHANGELOG.md

# Jetforce Changelog

### v0.3.0

This release brings some major improvements and necessary refactoring of the
jetforce package. Please read the release notes carefully and exercise caution
when upgrading from previous versions of jetforce.

#### For users of the static file server

If you are running jetforce only as a static file & CGI server (i.e. you
are using the command-line and haven't written any custom python applications),
you should not need to make any changes.

There have been some minor updates to the CGI variables, and new CGI variables
have been added with additional TLS information. Check out the README for the
new list.

This package now has third-party python dependencies. If you installed jetforce
through pip, you should be already fine. If you were running the ``jetforce.py``
script directly from the git repository, you will likely either want to switch
to installing from pip (recommended), or setup a virtual environment and run
``python setup.py install``. This will install the dependencies and stick a
``jetforce`` executable into your system path.

#### jetforce-diagnostics

The ``jetforce-diagnostics`` script is no longer included as part of jetforce.
It has been moved to its own repository at
[gemini-diagnostics](https://github.com/michael-lazar/gemini-diagnostics).

#### Code Structure

The underlying TCP server framework has been switched from asyncio+ssl to
twisted+PyOpenSSL. This change was necessary to allow support for self-signed
client certificates. The new framework provides more access to hook into the
OpenSSL library and implement non-standard TLS behavior.

I tried to isolate the framework changes to the ``GeminiServer`` layer. This
means that if you subclassed from the ``JetforceApplication``, you will likely
not need to change anything in your application code. Launching a jetforce
server from inside of python code has been simplified (no more setting up the
asyncio event loop!).

```
server = GeminiServer(app)
server.run()
```

Check out the updated examples in the *examples/* directory for more details.

#### TLS Client Certificates

Jetforce will now accept self-signed and unvalidated client certificates. The
``capath`` and ``cafile`` arguments can still be provided, and will attempt to
validate the certificate using of the underlying OpenSSL library. The result
of this validation will be saved in the ``TLS_CLIENT_AUTHORISED`` environment
variable so that each application can decide how it wants to accept/reject the
connection.

In order to facilitate TOFU verification schemes, a fingerprint of the client
certificate is now computed and saved in the ``TLS_CLIENT_HASH`` environment
variable.

#### Other Changes

- A client certificate can now have an empty ``commonName`` field.
- ``JetforceApplication.route()`` - named capture groups in regex patterns will
  now be passed as keyword arguments to the wrapped function. See
  examples/pagination.py for an example of how to use this feature.
- ``CompositeApplication`` - A class is now included to support composing
  composing multiple applications behind the same jetforce server. See
  examples/vhost.py for an example of how to use this feature.
- CGI variables - ``SCRIPT_NAME`` and ``PATH_INFO`` have been changed to match
  their intended usage as defined in RFC 3875.
- CGI variables - ``TLS_CIPHER`` and ``TLS_VERSION`` have been added and
  contain information about the established TLS connection.
- Applications can now optionally return ``Deferred`` objects instead of bytes,
  in order to support full-blown asynchronous coroutines.

### v0.2.3 (2020-05-24)

- Fix a security vulnerability that allowed maliciously crafted URLs to break
  out of the root server directory.

### v0.2.2 (2020-03-31)

- Fix a regression in path matching for the static directory application.
  
### v0.2.1 (2020-03-31)

- A hostname can now be specified in the route pattern, to facilitate running
  multiple vhosts on a single jetforce server.
- Route patterns now use ``re.fullmatch()`` and will no longer trigger on
  partial matches.
- Jetforce will no longer raise an exception when attempting to log dropped
  connections or other malformed requests.
- Added the following CGI variables for client certificates:
  TLS_CLIENT_NOT_BEFORE, TLS_CLIENT_NOT_AFTER, TLS_CLIENT_SERIAL_NUMBER

### v0.2.0 (2020-01-21)

#### Features

- Added support for python 3.8. 
- Added a new server diagnostics tool, ``jetforce-diagnostics``.
- Added ability to binding to IPv6 addresses (if supported by your OS):
  - For IPv4        : ``--host "0.0.0.0"``
  - For IPv6        : ``--host "::"``
  - For IPv4 + IPv6 : ``--host ""``
- Various improvements have been made to the project documentation.

#### Bugfixes

- A URL missing a scheme will now be interpreted as "gemini://".
- A request to the root URL without a trailing slash will now return a
  ``31 PERMANENT REDIRECT``.
- Requests containing an invalid or unparsable URL format will now return a
  status of ``59 BAD REQUEST`` instead of ``50 PERMANENT FAILURE``.
- Files starting with ``~`` will now be included in directory listings. 
- Requests containing an incorrect scheme, hostname, or port will now return a
  ``53 PROXY REFUSED`` instead of a ``50 PERMANENT FAILURE``.
- The port number in the URL (if provided) is now validated against the
  server's port number. 
- OS errors when attempting to read a file will return a ``51 NOT FOUND``
  status instead of a ``42 CGI Error``. This is a precaution to prevent leaking
  sensitive information about the server's filesystem.
- For security, unhandled exceptions will now display a generic error message
  instead of the plain exception string.

### v0.1.0 (2019-09-22)

- The server will now return a redirect if a directory is requested but the URL
  does not end in a trailing slash. This is intended to reduce duplicate
  selectors and make it easier for clients to resolve relative links.
- Added a ``-V`` / ``--version`` argument to display the version and exit.
- The server now returns an error code of ``50 PERMENANT FAILURE`` by default
  if the URL does not match the server's scheme or hostname.
- Timestamps in log messages are now displayed in the server's local timezone.
  As before, the UTC offset is included as "+HHMM" to avoid ambiguity.
  
### v0.0.7 (2019-08-30)

- Added support for a primitive version of CGI scripting.
- Added support for TLS client certificate verification.
- The directory index file has been changed from ".gemini" to "index.gmi".
- Files with the ".gemini" extension are now recognized as *text/gemini*.
- Several minor improvements to the internal codebase and API.

### v0.0.6 (2019-08-22)

- Significant refactoring of the base application interface.
- Added built-in support for URL routing based on the request path.
- Added support for accepting input using query strings.
- Files with the ".gmi" extension are now recognized as *text/gemini*.
- Added a new examples/ directory with the following applications
  - A bare bones echo server
  - A guestbook application
  - An HTTP/HTTPS proxy server

### v0.0.5 (2019-08-12)

Updates to conform to the v0.9.1 Gemini specification

- The request line is now expected to be a full URL instead of a PATH.
- Response status codes have been updated to match the new specification.
- The server now requires a "hostname" be specified via a command line argument.
- Request URLs that contain other protocols / hosts are disallowed.
- A simple gemini client, ``jetforce-client``, is now included.