rails-console 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2f2321f67a6a9c31742bf4402542b064b058b092c06b8faf1d780ddd13481f90
+  data.tar.gz: e1eeed831c25b3d78c442c1ba1f08bc79d1e4e3a6fbc91606c76f6bba28c0caa
+SHA512:
+  metadata.gz: e56e7f980a78c1b3fc40a352ff95dc012641e453b8de608d7f29aafc8d6e6848c90508844020620549edd79bb3dcd3df779f90f911475b925ea1f96e9e2c6a31
+  data.tar.gz: 5edec40ae0354c4ed4ec1d8fbfd7321bb126ed7b721aca3bd45ef6d76d46524f36857cb2fb9bae879113afc7038254883b57a7f61f9c243e4f4f2a8b6db3c9c4

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+- Browser console over ActionCable with xterm.js frontend bundle.
+- Broker process (`bundle exec rails_console`) with PTY, sandbox-by-default, and `unsafe!` / `safe!` to toggle write mode.
+- Audit models (`rails_console_sessions`, `rails_console_log_lines`); mode toggles are recorded as `transition` log lines.
+- Install generator for migrations and `config/initializers/rails_console.rb`.
+- `authorize` and `current_user` receive the resolved user (HTTP and WebSocket).
+- Default `user_class` is `User`; default socket is `tmp/sockets/rails_console.sock`.

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Washington Botelho
+
+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,118 @@
+# Rails Console
+
+[![Tests](https://github.com/wbotelhos/rails-console/workflows/Tests/badge.svg)](https://github.com/wbotelhos/rails-console/actions/workflows/tests.yml)
+[![RuboCop](https://github.com/wbotelhos/rails-console/workflows/RuboCop/badge.svg)](https://github.com/wbotelhos/rails-console/actions/workflows/rubocop.yml)
+[![Gem Version](https://badge.fury.io/rb/rails-console.svg)](https://badge.fury.io/rb/rails-console)
+[![Maintainability](https://qlty.sh/gh/wbotelhos/projects/rails-console/maintainability.svg)](https://qlty.sh/gh/wbotelhos/projects/rails-console)
+[![Coverage](https://codecov.io/gh/wbotelhos/rails-console/branch/main/graph/badge.svg)](https://codecov.io/gh/wbotelhos/rails-console)
+[![Sponsor](https://img.shields.io/badge/sponsor-%3C3-green)](https://github.com/sponsors/wbotelhos)
+
+A safe, browser-based Rails console you mount on your app.
+
+## Installation
+
+```ruby
+gem 'rails-console'
+```
+
+```sh
+bundle install
+bin/rails generate rails_console:install
+bin/rails db:migrate
+```
+
+## Mounting
+
+Mount the engine behind your own authentication **and** authorization:
+
+```ruby
+# config/routes.rb
+authenticate :user, ->(user) { user.devops? } do
+  mount RailsConsole::Engine, at: :console
+end
+```
+
+The route constraint protects the HTML page. The gem's `authorize` config (below) also protects the ActionCable channel — required because `/cable` is outside the mount.
+
+## Configuration
+
+Created by `bin/rails generate rails_console:install`. Example:
+
+```ruby
+# config/initializers/rails_console.rb
+RailsConsole.configure do |config|
+  config.audit = true
+
+  config.authorize = ->(user) { user&.devops? }
+
+  config.command = 'bundle exec rails console'
+
+  config.current_user = ->(user) { { id: user&.id, label: user.try(:email) || 'unknown' } }
+
+  config.idle_timeout = 10.minutes
+  config.sandbox_command = 'bundle exec rails console --sandbox'
+end
+```
+
+`authorize` and `current_user` receive the resolved user from HTTP (`request`) and WebSocket (`connection`) contexts.
+
+| Option | Purpose |
+| --- | --- |
+| `audit` | Persist sessions and I/O log lines (default: `true`) |
+| `authorize` | Proc `(user) -> bool` — may the user use the console (HTTP **and** WebSocket) |
+| `command` | Command after `unsafe!` |
+| `current_user` | Proc `(user) -> { id:, label: }` for audit records |
+| `idle_timeout` | Kill idle PTY sessions after this duration |
+| `sandbox_command` | Default command (safe-by-default sandbox) |
+| `socket_path` | Unix socket between Puma workers and the broker (default: `tmp/sockets/rails_console.sock`) |
+| `user_class` | ActiveRecord model class name for session `user` lookup (default: `User`) |
+
+## Security layers
+
+1. **Route constraint** — `authenticate` / custom constraint on the mount (HTTP only).
+2. **Controller** — `authorize` runs again before rendering the page.
+3. **Channel** — `authorize` on `subscribed` is the **only** protection for `/cable`; the mount does not cover WebSockets.
+
+Additional safeguards:
+
+- **Sandbox by default** — sessions start with `rails console --sandbox`.
+- **`unsafe!` / `safe!`** — explicit toggle between write and sandbox mode; each swap starts a fresh PTY and is audited.
+- **Broker isolation** — one PTY per container, shared via Unix socket across Puma workers.
+- **Audit trail** — `RailsConsole::Session` and `RailsConsole::LogLine` when `audit` is enabled.
+
+Do not rely on command filtering inside Ruby; use authorization + sandbox + auditing.
+
+## Usage
+
+Open `/console` (the path you mounted the engine at) to get a real `rails console` in the browser.
+
+Sessions start in **safe mode** — changes are rolled back and never persisted:
+
+```rb
+User.last.destroy # runs, but nothing is saved
+```
+
+Type `unsafe!` to switch to **write mode**, where changes persist:
+
+```rb
+unsafe!
+User.last.destroy # now really deletes the record
+```
+
+Type `safe!` to go back to sandbox mode. Each toggle starts a fresh session and is recorded in the audit trail.
+
+## Broker process
+
+The broker boots on demand when someone opens `/console`, or run it manually:
+
+```sh
+bundle exec rails_console
+```
+
+## Development (gem)
+
+```sh
+npm install
+bundle exec rake assets:build # rebuild xterm bundle into app/assets/rails_console/
+bundle exec rake spec
+```

data/app/assets/rails_console/rails_console.css

@@ -0,0 +1,230 @@
+/**
+ * Copyright (c) 2014 The xterm.js authors. All rights reserved.
+ * Copyright (c) 2012-2013, Christopher Jeffrey (MIT License)
+ * https://github.com/chjj/term.js
+ * @license MIT
+ *
+ * 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.
+ *
+ * Originally forked from (with the author's permission):
+ *   Fabrice Bellard's javascript vt100 for jslinux:
+ *   http://bellard.org/jslinux/
+ *   Copyright (c) 2011 Fabrice Bellard
+ *   The original design remains. The terminal itself
+ *   has been extended to include xterm CSI codes, among
+ *   other features.
+ */
+
+/**
+ *  Default styles for xterm.js
+ */
+
+.xterm {
+    cursor: text;
+    position: relative;
+    user-select: none;
+    -ms-user-select: none;
+    -webkit-user-select: none;
+}
+
+.xterm.focus,
+.xterm:focus {
+    outline: none;
+}
+
+.xterm .xterm-helpers {
+    position: absolute;
+    top: 0;
+    /**
+     * The z-index of the helpers must be higher than the canvases in order for
+     * IMEs to appear on top.
+     */
+    z-index: 5;
+}
+
+.xterm .xterm-helper-textarea {
+    padding: 0;
+    border: 0;
+    margin: 0;
+    /* Move textarea out of the screen to the far left, so that the cursor is not visible */
+    position: absolute;
+    opacity: 0;
+    left: -9999em;
+    top: 0;
+    width: 0;
+    height: 0;
+    z-index: -5;
+    /** Prevent wrapping so the IME appears against the textarea at the correct position */
+    white-space: nowrap;
+    overflow: hidden;
+    resize: none;
+}
+
+.xterm .composition-view {
+    /* TODO: Composition position got messed up somewhere */
+    background: #000;
+    color: #FFF;
+    display: none;
+    position: absolute;
+    white-space: nowrap;
+    z-index: 1;
+}
+
+.xterm .composition-view.active {
+    display: block;
+}
+
+.xterm .xterm-viewport {
+    /* On OS X this is required in order for the scroll bar to appear fully opaque */
+    background-color: #000;
+    overflow-y: scroll;
+    cursor: default;
+    position: absolute;
+    right: 0;
+    left: 0;
+    top: 0;
+    bottom: 0;
+}
+
+.xterm .xterm-screen {
+    position: relative;
+}
+
+.xterm .xterm-screen canvas {
+    position: absolute;
+    left: 0;
+    top: 0;
+}
+
+.xterm .xterm-scroll-area {
+    visibility: hidden;
+}
+
+.xterm-char-measure-element {
+    display: inline-block;
+    visibility: hidden;
+    position: absolute;
+    top: 0;
+    left: -9999em;
+    line-height: normal;
+}
+
+.xterm.enable-mouse-events {
+    /* When mouse events are enabled (eg. tmux), revert to the standard pointer cursor */
+    cursor: default;
+}
+
+.xterm.xterm-cursor-pointer,
+.xterm .xterm-cursor-pointer {
+    cursor: pointer;
+}
+
+.xterm.column-select.focus {
+    /* Column selection mode */
+    cursor: crosshair;
+}
+
+.xterm .xterm-accessibility:not(.debug),
+.xterm .xterm-message {
+    position: absolute;
+    left: 0;
+    top: 0;
+    bottom: 0;
+    right: 0;
+    z-index: 10;
+    color: transparent;
+    pointer-events: none;
+}
+
+.xterm .xterm-accessibility-tree:not(.debug) *::selection {
+  color: transparent;
+}
+
+.xterm .xterm-accessibility-tree {
+  user-select: text;
+  white-space: pre;
+}
+
+.xterm .live-region {
+    position: absolute;
+    left: -9999px;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+}
+
+.xterm-dim {
+    /* Dim should not apply to background, so the opacity of the foreground color is applied
+     * explicitly in the generated class and reset to 1 here */
+    opacity: 1 !important;
+}
+
+.xterm-underline-1 { text-decoration: underline; }
+.xterm-underline-2 { text-decoration: double underline; }
+.xterm-underline-3 { text-decoration: wavy underline; }
+.xterm-underline-4 { text-decoration: dotted underline; }
+.xterm-underline-5 { text-decoration: dashed underline; }
+
+.xterm-overline {
+    text-decoration: overline;
+}
+
+.xterm-overline.xterm-underline-1 { text-decoration: overline underline; }
+.xterm-overline.xterm-underline-2 { text-decoration: overline double underline; }
+.xterm-overline.xterm-underline-3 { text-decoration: overline wavy underline; }
+.xterm-overline.xterm-underline-4 { text-decoration: overline dotted underline; }
+.xterm-overline.xterm-underline-5 { text-decoration: overline dashed underline; }
+
+.xterm-strikethrough {
+    text-decoration: line-through;
+}
+
+.xterm-screen .xterm-decoration-container .xterm-decoration {
+	z-index: 6;
+	position: absolute;
+}
+
+.xterm-screen .xterm-decoration-container .xterm-decoration.xterm-decoration-top-layer {
+	z-index: 7;
+}
+
+.xterm-decoration-overview-ruler {
+    z-index: 8;
+    position: absolute;
+    top: 0;
+    right: 0;
+    pointer-events: none;
+}
+
+.xterm-decoration-top {
+    z-index: 2;
+    position: relative;
+}
+html,
+body {
+  background: #000;
+  height: 100%;
+  margin: 0;
+  padding: 0;
+}
+
+#rails-console {
+  height: 100vh;
+  width: 100vw;
+}