liberty-web 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1a3a232c3de7bcab974b91d8e7c9370aa085c93ba3133a0416aa743ddbb0dfc0
+  data.tar.gz: 97f424f9249fc77134937f1829ec376d2ac360c9fa33c7f481627033464956b9
+SHA512:
+  metadata.gz: 3cfd53425ff26efedafac9b24e209e0b36178785192f614d37971a3476a81454c8fd386ecb29362c43960827168da440a2202f7fffbf7da97fac7f8691bf2ffd
+  data.tar.gz: acfc63ed0be078cb61d2cf4af3512f391e734eab28dc12cbf54dee7e8658d25527361ecc935837bbdfb7e7cd674cb26d8bd546106a32f2fc7fd06189165ce562

data/.qlty/.gitignore

@@ -0,0 +1,7 @@
+*
+!configs
+!configs/**
+!hooks
+!hooks/**
+!qlty.toml
+!.gitignore

data/.qlty/qlty.toml

@@ -0,0 +1,81 @@
+# This file was automatically generated by `qlty init`.
+# You can modify it to suit your needs.
+# We recommend you to commit this file to your repository.
+#
+# This configuration is used by both Qlty CLI and Qlty Cloud.
+#
+#     Qlty CLI -- Code quality toolkit for developers
+#     Qlty Cloud -- Fully automated Code Health Platform
+#
+# Try Qlty Cloud: https://qlty.sh
+#
+# For a guide to configuration, visit https://qlty.sh/d/config
+# Or for a full reference, visit https://qlty.sh/d/qlty-toml
+config_version = "0"
+
+exclude_patterns = [
+  "*_min.*",
+  "*-min.*",
+  "*.min.*",
+  "**/.yarn/**",
+  "**/*.d.ts",
+  "**/assets/**",
+  "**/bower_components/**",
+  "**/build/**",
+  "**/cache/**",
+  "**/config/**",
+  "**/db/**",
+  "**/deps/**",
+  "**/dist/**",
+  "**/extern/**",
+  "**/external/**",
+  "**/generated/**",
+  "**/Godeps/**",
+  "**/gradlew/**",
+  "**/mvnw/**",
+  "**/node_modules/**",
+  "**/protos/**",
+  "**/seed/**",
+  "**/target/**",
+  "**/templates/**",
+  "**/testdata/**",
+  "**/vendor/**",
+]
+
+test_patterns = [
+  "**/test/**",
+  "**/spec/**",
+  "**/*.test.*",
+  "**/*.spec.*",
+  "**/*_test.*",
+  "**/*_spec.*",
+  "**/test_*.*",
+  "**/spec_*.*",
+]
+
+[smells]
+mode = "comment"
+
+[[source]]
+name = "default"
+default = true
+
+
+[[plugin]]
+name = "actionlint"
+
+[[plugin]]
+name = "osv-scanner"
+
+[[plugin]]
+name = "ripgrep"
+mode = "comment"
+
+[[plugin]]
+name = "standardrb"
+
+[[plugin]]
+name = "trufflehog"
+
+[[plugin]]
+name = "zizmor"

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+4.0.6

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/testdouble/standard
+ruby_version: 3.1

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+## [0.1.0] - 2026-09-19
+
+The first release. Liberty Web is the browser stack for a Liberty application, kept out of Liberty itself so an API never carries sessions it did not ask for.
+
+### Added
+
+- `Liberty::Web::Config`, a value the application fills in: `session_secrets`, `permitted_hosts`, `secure_cookies`, and optionally `static` and `logger`. Building one never raises; `errors` names what is missing or wrong, one sentence each, and `valid?` says whether there are any.
+- `Liberty::Web.app(config)`, which wraps `Liberty.rack_app` in the browser middleware in the order a browser needs: static files, a request logger, method override, an encrypted cookie session, host authorization, the CSRF token check, the origin check, frame options, and `x-content-type-options: nosniff`. It raises `Liberty::Web::ConfigurationError` for a config with errors, naming every one, and builds nothing.
+- `Liberty::Web::Endpoint`, a `Liberty::Endpoint` with three private helpers: `session`, `csrf_token`, and `location(path)`. Templates are the application's; the gem never sees its renderer.
+- `Liberty::Web::Redirect.to(path, status: 303)`, an endpoint class that only redirects, for an authenticator's `challenge_endpoint_class`. One class per path and status.
+- `Liberty::Web::RequestLogger`, the default logger: INFO on the request's own error stream, so rack-protection's per-request debug output stays out of the log and a spec can read what was warned. An injected logger replaces it.
+- `Liberty::Web::ContentTypeOptions`, the useful half of rack-protection's `XSSHeader`. The obsolete `x-xss-protection` header is not sent.
+- `Liberty::Web::Testing`, required separately, with `lint(app)` for a Rack::Lint-wrapped app and `csrf_token_in(html)` for posting forms back in request specs.
+- `Liberty::Web::Error`, a `Liberty::Error`, and `Liberty::Web::ConfigurationError` beneath it.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant 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, 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
+
+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
+
+## 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 e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at alan@ridlehoover.com. 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.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
+available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+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.

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "flog"
+gem "rack-test", "~> 2.2"
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.13"
+gem "simplecov", "~> 1.0"
+gem "standard", "~> 1.0"

data/Gemfile.lock

@@ -0,0 +1,167 @@
+PATH
+  remote: .
+  specs:
+    liberty-web (0.1.0)
+      liberty (~> 0.5)
+      rack (~> 3.1)
+      rack-protection (~> 4.2)
+      rack-session (~> 2.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    base64 (0.3.0)
+    diff-lcs (1.6.2)
+    flog (4.9.4)
+      path_expander (~> 2.0)
+      prism (~> 1.7)
+      sexp_processor (~> 4.8)
+    hansi (0.2.1)
+    json (2.21.2)
+    language_server-protocol (3.17.0.6)
+    liberty (0.5.0)
+      json (~> 2.3)
+      mustermann (~> 4.0)
+      mustermann-contrib (~> 4.0)
+      rack (~> 3.1)
+      rack-abstract-format (~> 0.9.9)
+      rack-accept-media-types (~> 0.9)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    mustermann (4.0.0)
+    mustermann-contrib (4.0.0)
+      hansi (~> 0.2.0)
+      mustermann (= 4.0.0)
+    parallel (2.2.0)
+    parser (3.3.12.0)
+      ast (~> 2.4.1)
+      racc
+    path_expander (2.0.1)
+    prism (1.9.0)
+    racc (1.8.1)
+    rack (3.2.7)
+    rack-abstract-format (0.9.9)
+    rack-accept-media-types (0.9)
+    rack-protection (4.2.1)
+      base64 (>= 0.1.0)
+      logger (>= 1.6.0)
+      rack (>= 3.0.0, < 4)
+    rack-session (2.1.2)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    regexp_parser (2.12.0)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.88.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    ruby-progressbar (1.13.0)
+    sexp_processor (4.17.5)
+    simplecov (1.3.0)
+    standard (1.56.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.88.0)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.8)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.9.0)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.26.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+
+PLATFORMS
+  arm64-darwin-23
+  ruby
+
+DEPENDENCIES
+  flog
+  liberty-web!
+  rack-test (~> 2.2)
+  rake (~> 13.0)
+  rspec (~> 3.13)
+  simplecov (~> 1.0)
+  standard (~> 1.0)
+
+CHECKSUMS
+  ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
+  base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
+  flog (4.9.4) sha256=12cc054fab7a2cbd2a906514397c4d7788954d530564782d6f14939dc2dfbcbb
+  hansi (0.2.1) sha256=7e27dfd729f1692a3a7690fc0ef3af9d5e3cfc0285bb135cae7e56180e4805db
+  json (2.21.2) sha256=1f1d3b7cf2b3ba1a69beca0bb6db13d5438b80bff3cd54cdaaa620b9b07c1c6a
+  language_server-protocol (3.17.0.6) sha256=5ef2c0c138f8267e1bc631d3328347d354f96724b0af22f2c79516120443b7f0
+  liberty (0.5.0) sha256=98653b326537b3801b27c239749fe01b1a119191af9b945ff34c4e8c497757c0
+  liberty-web (0.1.0)
+  lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  mustermann (4.0.0) sha256=91f67411bb208d1d93c41e6128cb3b0f8ddd9ec7c45966f1007e1c43c08040d7
+  mustermann-contrib (4.0.0) sha256=62f3f9e15f64b36c512faf4582afd78c1ee8d8d80edafe0f4ddfe8a4c0ef12b2
+  parallel (2.2.0) sha256=e1059c5fd7b649558a0aec38a769f06a42942bdb40503d005a59c352fe011cd8
+  parser (3.3.12.0) sha256=21a6d7f755d5a24dfbdc6e6b772e4e879a52e7631a88bc5a3a134606052c9828
+  path_expander (2.0.1) sha256=2de201164bff4719cc4d0b3767286e9977cc832a59c4d70abab571ec86cb41e4
+  prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rack (3.2.7) sha256=93e13e1c24f93556671d85d2d79fa228c3485815c50d7e2f265b5330c6528fb7
+  rack-abstract-format (0.9.9) sha256=376c0897085e99de8d91742c1bb3a7f69a1d377349e6e0f2a56bd462a6448b78
+  rack-accept-media-types (0.9) sha256=2aace41f176858ec711da1b31ff16067859f30551dff22ce2c2a4d38f45ff081
+  rack-protection (4.2.1) sha256=cf6e2842df8c55f5e4d1a4be015e603e19e9bc3a7178bae58949ccbb58558bac
+  rack-session (2.1.2) sha256=595434f8c0c3473ae7d7ac56ecda6cc6dfd9d37c0b2b5255330aa1576967ffe8
+  rack-test (2.2.0) sha256=005a36692c306ac0b4a9350355ee080fd09ddef1148a5f8b2ac636c720f5c463
+  rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
+  rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
+  regexp_parser (2.12.0) sha256=35a916a1d63190ab5c9009457136ae5f3c0c7512d60291d0d1378ba18ce08ebb
+  rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
+  rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
+  rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836
+  rspec-mocks (3.13.8) sha256=086ad3d3d17533f4237643de0b5c42f04b66348c28bf6b9c2d3f4a3b01af1d47
+  rspec-support (3.13.7) sha256=0640e5570872aafefd79867901deeeeb40b0c9875a36b983d85f54fb7381c47c
+  rubocop (1.88.2) sha256=8def251c90cd955feb4daa3edc0ab56893250c4ce90ef81e6c80c03f9a939bbf
+  rubocop-ast (1.50.0) sha256=b9ca88300da0803ee222ad20cdb30494c0a784eed06fdc35d254b06d662788db
+  rubocop-performance (1.26.1) sha256=cd19b936ff196df85829d264b522fd4f98b6c89ad271fa52744a8c11b8f71834
+  ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
+  sexp_processor (4.17.5) sha256=ae2b48ba98353d5d465ce8759836b7a05f2e12c5879fcd14d7815b026de32f0e
+  simplecov (1.3.0) sha256=d9886307863c1ead47657dcbed869bfffd82318808b09014d8f0ff77dcfe7492
+  standard (1.56.0) sha256=ae2af4d9669589162ac69ed5ef59dcf9f346d4afc81f7e62b84339310dfcb787
+  standard-custom (1.0.2) sha256=424adc84179a074f1a2a309bb9cf7cd6bfdb2b6541f20c6bf9436c0ba22a652b
+  standard-performance (1.9.0) sha256=49483d31be448292951d80e5e67cdcb576c2502103c7b40aec6f1b6e9c88e3f2
+  unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
+  unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
+
+BUNDLED WITH
+  4.0.16

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alan Ridlehoover and Fito von Zastrow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,147 @@
+<img src="assets/liberty.png"/>
+
+# Liberty Web
+
+[![Gem Version](https://badge.fury.io/rb/liberty-web.svg)](https://badge.fury.io/rb/liberty-web)
+[![CI](https://github.com/first-try-software/liberty-web/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/first-try-software/liberty-web/actions/workflows/main.yml)
+
+Liberty Web is the browser stack for a [Liberty](https://github.com/first-try-software/liberty) application: sessions, CSRF, host and origin checks, security headers, a redirect challenge, and a seam for the application's renderer.
+
+Liberty itself answers requests and decides who is asking, and it stays free of cookies and templates so an API never carries them. Liberty Web adds what a browser needs, in one explicit call, and no more. It owns the shape of its configuration and the order of its middleware. The application owns every value, its authenticators, its templates, and its data.
+
+Two things Liberty Web does not do, on purpose. It has nothing to say about templates: an endpoint calls whatever renderer the application owns, and the gem never sees it. And it reads no environment: the application reads its own settings and fills in a `Config`.
+
+## Usage
+
+### The stack
+
+Build a `Liberty::Web::Config` with the application's values and hand it to `Liberty::Web.app`:
+
+```ruby
+# config.ru
+require_relative "app/boot"
+
+config = Liberty::Web::Config.new(
+  session_secrets: [ENV.fetch("SESSION_SECRET")],   # one or more strings of at least 64 bytes; more than one rotates
+  permitted_hosts: ENV.fetch("PERMITTED_HOSTS").split(","),
+  secure_cookies: ENV["RACK_ENV"] == "production",  # true needs the proxy to forward the scheme; see below
+  static: "public"                                  # optional: a directory whose top-level entries become urls
+)
+
+run Liberty::Web.app(config)
+```
+
+Building a `Config` never raises, so a task that serves no pages can hold a half-filled one. `config.errors` names each problem in a sentence, and `Liberty::Web.app` raises `Liberty::Web::ConfigurationError` carrying all of them rather than build a stack that is wrong.
+
+The call wraps `Liberty.rack_app` in this middleware, request first:
+
+| Middleware | Why it is there |
+|---|---|
+| `Rack::Static` | Files under `static` answer before anything else runs |
+| `Liberty::Web::RequestLogger` | rack-protection logs through `rack.logger`; without one it builds a DEBUG logger per request and chatters. The default is INFO on the request's own error stream; pass `logger:` to use your own |
+| `Rack::MethodOverride` | Forms can only GET and POST; a hidden `_method` field gives a POST another verb. Only a POST is rewritten |
+| `Rack::Session::Cookie` | Encrypted with `secrets:`, never `secret:`, so the legacy HMAC and Marshal path stays off. `SameSite=Lax`, `HttpOnly`, and `Secure` from `secure_cookies` |
+| `Rack::Protection::HostAuthorization` | Before the CSRF check, so a request for the wrong host is told "Host not permitted" rather than a puzzling 403 |
+| `Rack::Protection::AuthenticityToken` | The token from a form field or the `X-CSRF-Token` header; it needs the session above it |
+| `Rack::Protection::HttpOrigin` | An unsafe request's `Origin` must be the application's own |
+| `Rack::Protection::FrameOptions` | `SAMEORIGIN` on HTML |
+| `Liberty::Web::ContentTypeOptions` | `nosniff` on every response. The obsolete `x-xss-protection` header is not sent |
+
+To add middleware of your own, wrap the result in your own `Rack::Builder`.
+
+### Endpoints
+
+Inherit from `Liberty::Web::Endpoint` instead of `Liberty::Endpoint`. It adds three private helpers and nothing else:
+
+```ruby
+session          # the rack session hash; wrap it in your own class if you want a vocabulary
+csrf_token       # the token the CSRF middleware accepts for this session, for a hidden field or a meta tag
+location(path)   # {"location" => path}; the status stays your own answer
+```
+
+```ruby
+class Journal < Liberty::Web::Endpoint
+  responds_to :get, "/", authenticated_by: Authenticators::Session
+
+  def html
+    MyApp.renderer.render("journal", layout: :application, csrf_token: csrf_token, notes: notes)
+  end
+end
+
+class Logout < Liberty::Web::Endpoint
+  responds_to :delete, "/logout", authenticated_by: Authenticators::Session
+
+  def status
+    session.clear
+    303
+  end
+
+  def headers = location("/login")
+end
+```
+
+The form that posts to a Liberty Web application carries the token in a hidden field, and a page that posts with JavaScript carries it in a `<meta name="csrf-token">` tag and sends it back as `X-CSRF-Token`. Both are the application's markup; the gem only checks them.
+
+### Redirects as challenges
+
+A Liberty authenticator names the endpoint class that answers when there is no principal. For a browser that is a redirect, and `Redirect.to` builds it:
+
+```ruby
+module Authenticators
+  class Session < Liberty::Authenticator
+    def principal = users.find(request.env["rack.session"][:user_id])
+
+    def challenge_endpoint_class = Liberty::Web::Redirect.to("/login")
+  end
+end
+```
+
+`Redirect.to(path, status: 303)` returns one class per path and status, so Liberty sees the same class each time.
+
+### Testing
+
+`require "liberty/web/testing"` where your specs are set up. It is not loaded by `require "liberty/web"`.
+
+```ruby
+APP = Liberty::Web::Testing.lint(Rack::Builder.parse_file("config.ru"))   # every request and response checked against the Rack spec
+
+token = Liberty::Web::Testing.csrf_token_in(last_response.body)          # the hidden field's value, for posting a form back
+```
+
+### Behind a proxy
+
+With `secure_cookies: true`, the session middleware writes no cookie unless the request arrived over TLS, and the origin check compares against the scheme the request arrived with. Puma usually sits behind a proxy that terminates TLS, so Rack learns the scheme from `X-Forwarded-Proto`, or from a `Forwarded` header with `proto=https`. Caddy, Fly, Heroku, and Render add it for you. Nginx does not:
+
+```nginx
+proxy_set_header X-Forwarded-Proto $scheme;
+```
+
+Without it, the first symptom is a 403 on every form post.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add liberty-web
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install liberty-web
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake` to run every gate: the specs, Standard, qlty, and flog. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/first-try-software/liberty-web. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/first-try-software/liberty-web/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Liberty Web project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/first-try-software/liberty-web/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+FLOG_LIMIT = 10.0
+
+def qlty_bin
+  installed = File.expand_path("~/.qlty/bin/qlty")
+  ENV.fetch("QLTY_BIN") { File.exist?(installed) ? installed : "qlty" }
+end
+
+desc "Run qlty lint checks and report code smells"
+task :qlty do
+  sh qlty_bin, "check", "--all", "--no-progress"
+  sh qlty_bin, "smells", "--all", "--quiet"
+end
+
+desc "Fail when the average flog score per method reaches #{FLOG_LIMIT}"
+task :flog do
+  report = `bundle exec flog -m lib`
+  puts report
+  average = report[/^\s*([\d.]+): flog\/method average/, 1].to_f
+  abort("Quality gate failed: average flog #{average} is #{FLOG_LIMIT} or higher") if average >= FLOG_LIMIT
+end
+
+task default: %i[spec standard qlty flog]

data/lib/liberty/web/config.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Liberty
+  module Web
+    # What the stack needs, as a value the application fills in. Building one
+    # never raises, so a task that serves no pages can hold a half-filled one;
+    # `errors` says what is missing or wrong, and Liberty::Web.app refuses to
+    # build while there are any.
+    #
+    #   session_secrets   one or more strings of at least MINIMUM_SECRET_BYTES; more than one rotates
+    #   permitted_hosts   the host names the app answers for; never empty, which would mean anyone
+    #   secure_cookies    true when the site is served over TLS. The session cookie is then written
+    #                     only to a request Rack sees as TLS. Behind a proxy that terminates TLS,
+    #                     Rack learns that from X-Forwarded-Proto, so the proxy must send it
+    #   static            a directory whose top-level entries are served as urls, or nil for none
+    #   logger            a ::Logger that every request gets as rack.logger, which is where
+    #                     rack-protection warns; or nil for a Logger per request on that request's
+    #                     own rack.errors stream at INFO, which keeps rack-protection's debug
+    #                     chatter out of the log and lets a spec read the warnings from a StringIO
+    class Config < Data.define(:session_secrets, :permitted_hosts, :secure_cookies, :static, :logger)
+      MINIMUM_SECRET_BYTES = 64
+
+      def initialize(session_secrets: [], permitted_hosts: [], secure_cookies: nil, static: nil, logger: nil)
+        super(
+          session_secrets: Array(session_secrets),
+          permitted_hosts: Array(permitted_hosts),
+          secure_cookies: secure_cookies,
+          static: static,
+          logger: logger
+        )
+      end
+
+      def errors
+        [secrets_error, hosts_error, cookies_error, static_error].compact
+      end
+
+      def valid?
+        errors.empty?
+      end
+
+      private
+
+      def secrets_error
+        return "session_secrets must hold at least one secret" if session_secrets.empty?
+        return unless session_secrets.any? { |secret| secret.to_s.bytesize < MINIMUM_SECRET_BYTES }
+
+        "session_secrets must each be at least #{MINIMUM_SECRET_BYTES} bytes"
+      end
+
+      def hosts_error
+        "permitted_hosts must name at least one host" if permitted_hosts.empty?
+      end
+
+      def cookies_error
+        "secure_cookies must be true or false" unless [true, false].include?(secure_cookies)
+      end
+
+      def static_error
+        "static must be an existing directory" if static && !File.directory?(static)
+      end
+    end
+  end
+end

data/lib/liberty/web/content_type_options.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Liberty
+  module Web
+    # Tells the browser never to guess a response's type. This is the useful
+    # half of rack-protection's XSSHeader; the other half, x-xss-protection,
+    # is obsolete and is not sent.
+    class ContentTypeOptions
+      attr_reader :app
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        status, headers, body = app.call(env)
+        headers["x-content-type-options"] ||= "nosniff"
+        [status, headers, body]
+      end
+    end
+  end
+end

data/lib/liberty/web/endpoint.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "rack/protection"
+
+module Liberty
+  module Web
+    # A Liberty endpoint with what a browser endpoint reaches for. Three
+    # private helpers and nothing else: no lifecycle, no response object, and
+    # nothing about templates, which are the application's.
+    class Endpoint < Liberty::Endpoint
+      private
+
+      # The rack session hash. An application wraps it with its own class when
+      # it wants a vocabulary for what the cookie carries.
+      def session
+        request.env["rack.session"]
+      end
+
+      # The masked token the CSRF middleware accepts for this session, for a
+      # hidden field or a meta tag.
+      def csrf_token
+        Rack::Protection::AuthenticityToken.token(session)
+      end
+
+      # The headers of a redirect. The status stays the endpoint's own answer.
+      def location(path)
+        {"location" => path}
+      end
+    end
+  end
+end

data/lib/liberty/web/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Liberty
+  module Web
+    # The base for every error Liberty Web raises. A Liberty::Error too, so an
+    # application can rescue the framework as a whole.
+    Error = Class.new(Liberty::Error)
+
+    # Raised by Liberty::Web.app for a Config with errors.
+    ConfigurationError = Class.new(Error)
+  end
+end

data/lib/liberty/web/redirect.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Liberty
+  module Web
+    # Endpoint classes that only redirect, for an authenticator's challenge:
+    #
+    #   def challenge_endpoint_class = Liberty::Web::Redirect.to("/login")
+    #
+    # One class per path and status, so Liberty sees the same class each time.
+    module Redirect
+      class << self
+        def to(path, status: 303)
+          classes[[path, status]] ||= build(path, status)
+        end
+
+        private
+
+        def classes
+          @classes ||= {}
+        end
+
+        def build(path, status)
+          Class.new(Endpoint) do
+            define_method(:status) { status }
+            define_method(:headers) { location(path) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/liberty/web/request_logger.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Liberty
+  module Web
+    # Gives every request a logger on rack.logger. rack-protection logs through
+    # it, and without one builds a DEBUG logger per request that chatters about
+    # every host check. The default is INFO on the request's own error stream,
+    # which is what lets a spec hand in a StringIO and read what was logged.
+    # An injected logger is handed to every request instead.
+    class RequestLogger
+      attr_reader :app, :logger
+
+      def initialize(app, logger = nil)
+        @app = app
+        @logger = logger
+      end
+
+      def call(env)
+        env["rack.logger"] = logger || Logger.new(env["rack.errors"], level: Logger::INFO)
+        app.call(env)
+      end
+    end
+  end
+end

data/lib/liberty/web/stack.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "rack"
+require "rack/builder"
+require "rack/static"
+require "rack/method_override"
+require "rack/session"
+require "rack/protection"
+require_relative "request_logger"
+require_relative "content_type_options"
+
+module Liberty
+  module Web
+    # The middleware around Liberty's application, request first:
+    #
+    #   Rack::Static                 files answer before anything else runs
+    #   RequestLogger                a quiet logger for rack-protection, or the injected one
+    #   Rack::MethodOverride         forms can only GET and POST; _method gives a POST another verb
+    #   Rack::Session::Cookie        encrypted; `secrets:`, never `secret:`, keeps the legacy HMAC path off
+    #   HostAuthorization            before the CSRF check, so a bad host is told so plainly
+    #   AuthenticityToken            the token from a form field or X-CSRF-Token; needs the session above
+    #   HttpOrigin                   an unsafe request's Origin must be the app's own
+    #   FrameOptions                 SAMEORIGIN on HTML
+    #   ContentTypeOptions           nosniff on everything; the obsolete x-xss-protection is not sent
+    class Stack
+      attr_reader :config
+
+      def initialize(config)
+        @config = config
+      end
+
+      def to_app
+        stack = self
+        Rack::Builder.new(Liberty.rack_app) do
+          use Rack::Static, urls: stack.static_urls, root: stack.config.static if stack.config.static
+          use RequestLogger, stack.config.logger
+          use Rack::MethodOverride
+          use Rack::Session::Cookie, **stack.session_options
+          use Rack::Protection::HostAuthorization, permitted_hosts: stack.config.permitted_hosts
+          use Rack::Protection::AuthenticityToken
+          use Rack::Protection::HttpOrigin
+          use Rack::Protection::FrameOptions
+          use ContentTypeOptions
+        end.to_app
+      end
+
+      def static_urls
+        Dir.children(config.static).sort.map { |name| "/#{name}" }
+      end
+
+      def session_options
+        {secrets: config.session_secrets, same_site: :lax, httponly: true, secure: config.secure_cookies}
+      end
+    end
+  end
+end

data/lib/liberty/web/testing.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rack/lint"
+
+module Liberty
+  module Web
+    # For an application's own specs. Not loaded by `require "liberty/web"`;
+    # require "liberty/web/testing" where the tests are set up.
+    module Testing
+      TOKEN_FIELD = /name="authenticity_token" value="([^"]+)"/
+
+      class << self
+        # The app with every request and response checked against the Rack spec.
+        def lint(app)
+          Rack::Lint.new(app)
+        end
+
+        # The value of the hidden field a form carries, for posting it back.
+        def csrf_token_in(html)
+          html[TOKEN_FIELD, 1]
+        end
+      end
+    end
+  end
+end

data/lib/liberty/web/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Liberty
+  module Web
+    VERSION = "0.1.0"
+  end
+end

data/lib/liberty/web.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "liberty"
+require_relative "web/version"
+require_relative "web/errors"
+require_relative "web/config"
+require_relative "web/stack"
+require_relative "web/endpoint"
+require_relative "web/redirect"
+
+module Liberty
+  # The browser stack for a Liberty application: sessions, CSRF, host and
+  # origin checks, security headers, and a redirect challenge. Liberty itself
+  # stays free of all of it, so an API never carries cookies it did not ask
+  # for. Templates are the application's; the gem has no opinion about them.
+  #
+  # The application builds a Config with its values and hands it here:
+  #
+  #   run Liberty::Web.app(config)
+  module Web
+    # Liberty's Rack application wrapped in the browser middleware, in the
+    # order a browser needs. Refuses a config with errors, naming them all.
+    def self.app(config)
+      raise ConfigurationError, "Liberty::Web.app cannot build: #{config.errors.join(". ")}." unless config.valid?
+
+      Stack.new(config).to_app
+    end
+  end
+end

data/liberty-web.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/liberty/web/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "liberty-web"
+  spec.version = Liberty::Web::VERSION
+  spec.authors = ["Alan Ridlehoover", "Fito von Zastrow"]
+  spec.email = ["liberty@firsttry.software"]
+
+  spec.summary = "The browser stack for Liberty applications"
+  spec.description = "Sessions, CSRF, host and origin checks, security headers, redirects, and a renderer seam " \
+    "for Liberty applications that serve browsers. Liberty itself stays free of them."
+  spec.homepage = "https://github.com/first-try-software/liberty-web"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.3.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "https://github.com/first-try-software/liberty-web/CHANGELOG.md"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "liberty", "~> 0.5"
+  spec.add_dependency "rack", "~> 3.1"
+  spec.add_dependency "rack-protection", "~> 4.2"
+  spec.add_dependency "rack-session", "~> 2.1"
+end

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: liberty-web
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alan Ridlehoover
+- Fito von Zastrow
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: liberty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rack-protection
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: rack-session
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+description: Sessions, CSRF, host and origin checks, security headers, redirects,
+  and a renderer seam for Liberty applications that serve browsers. Liberty itself
+  stays free of them.
+email:
+- liberty@firsttry.software
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".qlty/.gitignore"
+- ".qlty/qlty.toml"
+- ".rspec"
+- ".ruby-version"
+- ".standard.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- assets/liberty.png
+- lib/liberty/web.rb
+- lib/liberty/web/config.rb
+- lib/liberty/web/content_type_options.rb
+- lib/liberty/web/endpoint.rb
+- lib/liberty/web/errors.rb
+- lib/liberty/web/redirect.rb
+- lib/liberty/web/request_logger.rb
+- lib/liberty/web/stack.rb
+- lib/liberty/web/testing.rb
+- lib/liberty/web/version.rb
+- liberty-web.gemspec
+homepage: https://github.com/first-try-software/liberty-web
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/first-try-software/liberty-web
+  source_code_uri: https://github.com/first-try-software/liberty-web
+  changelog_uri: https://github.com/first-try-software/liberty-web/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: The browser stack for Liberty applications
+test_files: []