angarium 0.1.0

data/Rakefile

@@ -0,0 +1,13 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"
+
+# `rake standard` / `rake standard:fix` when the linter is in the bundle (dev).
+# `bin/rails test` loads this Rakefile too, and the test-matrix bundles omit
+# standard, so only require it when present. Release tasks live in rakelib/.
+require "standard/rake" if Gem.loaded_specs.key?("standard")

data/SECURITY.md

@@ -0,0 +1,51 @@
+# Security Policy
+
+## Supported versions
+
+Angarium is pre-release. Security fixes are provided for the `0.1.x` series
+during this phase. Once a stable line is released, this policy will be updated to
+list the versions that receive security updates.
+
+| Version | Supported |
+| ------- | --------- |
+| 0.1.x   | ✅        |
+
+## Reporting a vulnerability
+
+Please report security vulnerabilities **privately**. Do **not** open a public
+issue, pull request, or discussion for a suspected vulnerability.
+
+Use GitHub's private vulnerability reporting for the
+[`radioactive-labs/angarium`](https://github.com/radioactive-labs/angarium)
+repository: go to the **Security** tab and choose **Report a vulnerability**
+(this opens a private draft advisory visible only to the maintainers).
+
+We aim to acknowledge new reports within a few business days, and we'll keep you
+informed as we investigate and prepare a fix. Please give us a reasonable window
+to release a patch before any public disclosure.
+
+## Security surfaces Angarium hardens
+
+Angarium is designed to send user-configured webhooks safely. The intended
+security guarantees, and the surfaces you can hold us to, are:
+
+- **SSRF protection.** Endpoint URLs are user-supplied, so delivery is guarded by
+  an address policy that blocks private/loopback/link-local addresses by default,
+  requires an explicit per-endpoint opt-in for private networks, and **fails
+  closed** on hosts it can't resolve.
+- **Connect-time IP pinning.** Deliveries pin the connection to the validated
+  resolved address, closing the DNS-rebinding window between resolution and
+  connect (TLS SNI and certificate verification still use the original hostname).
+- **Encrypted secrets at rest.** Endpoint signing secrets (current and
+  in-rotation previous) and `custom_headers` (which commonly carries a receiver
+  credential such as an Authorization bearer token) are encrypted at rest with
+  Active Record Encryption.
+- **Standard Webhooks HMAC signing.** Requests are signed per the
+  [Standard Webhooks](https://www.standardwebhooks.com) spec (HMAC-SHA256 over
+  `{id}.{timestamp}.{body}`) with a timestamp tolerance enforced on verification
+  to resist replay.
+- **Custom-header denylist.** Per-endpoint custom headers cannot override the
+  signature headers or dangerous transport headers (request-smuggling and
+  receiver-confusion surface).
+
+If you find a gap in any of these guarantees, we especially want to hear about it.

data/app/assets/config/angarium_manifest.js

@@ -0,0 +1 @@
+//= link_directory ../stylesheets/angarium .css

data/app/assets/stylesheets/angarium/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/angarium/api/attempts_controller.rb

@@ -0,0 +1,12 @@
+module Angarium
+  module Api
+    class AttemptsController < BaseController
+      # GET /deliveries/:delivery_id/attempts
+      def index
+        delivery = scoped_delivery(params[:delivery_id])
+        authorize!(delivery)
+        render_collection(:attempts, delivery.delivery_attempts.order(created_at: :desc)) { |a| attempt_json(a) }
+      end
+    end
+  end
+end

data/app/controllers/angarium/api/base_controller.rb

@@ -0,0 +1,133 @@
+module Angarium
+  module Api
+    # Base controller for the headless JSON API. Inherits from your app's
+    # controller (config.parent_controller, default "ApplicationController"), so
+    # your existing authentication applies here too.
+    class BaseController < Angarium.config.parent_controller.constantize
+      # These endpoints authenticate via your current-user convention (a session
+      # or token), not a form CSRF token. If we inherited a forgery-protecting
+      # base (ActionController::Base), don't reject API POSTs for a missing token.
+      protect_from_forgery with: :null_session if respond_to?(:protect_from_forgery)
+
+      before_action :authenticate_angarium_user!
+
+      rescue_from ActiveRecord::RecordNotFound, with: :angarium_render_not_found
+      rescue_from ActiveRecord::RecordInvalid, with: :angarium_render_invalid
+      rescue_from Angarium::Api::NotAuthorized, with: :angarium_render_forbidden
+      rescue_from Angarium::Api::UnpermittedParameter, with: :angarium_render_unpermitted
+
+      # Resolved current user (via config.current_user). Public so policies can
+      # read it as `controller.angarium_current_user`.
+      def angarium_current_user
+        return @angarium_current_user if defined?(@angarium_current_user)
+
+        @angarium_current_user = Angarium.config.current_user.call(self)
+      end
+
+      private
+
+      def authenticate_angarium_user!
+        angarium_render_unauthorized unless angarium_current_user
+      end
+
+      # The policy for this request (config.policy_class), holding scope,
+      # create-owner, and per-action permissions.
+      def angarium_policy(record = nil)
+        Angarium.config.policy_class.to_s.constantize.new(self, record)
+      end
+
+      # The endpoints this user may see/act on: the policy narrows the base relation.
+      def endpoint_scope
+        angarium_policy.scope(Angarium::Endpoint.all)
+      end
+
+      # A delivery whose endpoint is within the caller's scope, or 404.
+      def scoped_delivery(id)
+        Angarium::Delivery.where(endpoint_id: endpoint_scope.select(:id)).find(id)
+      end
+
+      # Guard the current action with the policy's `<action>?` predicate.
+      def authorize!(record = nil)
+        raise Angarium::Api::NotAuthorized unless angarium_policy(record).public_send("#{action_name}?")
+      end
+
+      # Render a paginated list. Applies ?limit (default 50, max 200) and ?offset,
+      # and advertises the window with a `pagination` object so clients can page
+      # (there's more when offset + count < total).
+      def render_collection(key, relation, &serializer)
+        limit = params.fetch(:limit, 50).to_i.clamp(1, 200)
+        offset = [params.fetch(:offset, 0).to_i, 0].max
+        records = relation.limit(limit).offset(offset).to_a
+        render json: {
+          key => records.map(&serializer),
+          :pagination => {limit: limit, offset: offset, count: records.size, total: relation.count}
+        }
+      end
+
+      def render_error(status, message, **extra)
+        render json: {error: message, **extra}, status: status
+      end
+
+      def angarium_render_unauthorized = render_error(:unauthorized, "authentication required")
+      def angarium_render_forbidden = render_error(:forbidden, "not authorized")
+      def angarium_render_not_found = render_error(:not_found, "not found")
+
+      def angarium_render_invalid(error)
+        render_error(:unprocessable_entity, "validation failed", details: error.record.errors.full_messages)
+      end
+
+      def angarium_render_unpermitted(error)
+        render_error(:unprocessable_entity, "unpermitted parameter", details: [error.message])
+      end
+
+      # --- serializers ----------------------------------------------------------
+      # signing_secret and custom_headers are never echoed in responses (they're
+      # encrypted at rest and may carry credentials); the secret is revealed only
+      # on create and rotate_secret.
+
+      def endpoint_json(endpoint, include_secret: false)
+        json = {
+          id: endpoint.id,
+          name: endpoint.name,
+          url: endpoint.url,
+          status: endpoint.status,
+          subscribed_events: endpoint.subscribed_events,
+          allow_private_network: endpoint.allow_private_network,
+          allowed_networks: endpoint.allowed_networks,
+          consecutive_failures: endpoint.consecutive_failures,
+          status_changed_at: endpoint.status_changed_at&.iso8601,
+          created_at: endpoint.created_at.iso8601,
+          updated_at: endpoint.updated_at.iso8601
+        }
+        json[:signing_secret] = endpoint.signing_secret if include_secret
+        json
+      end
+
+      def delivery_json(delivery)
+        {
+          id: delivery.id,
+          endpoint_id: delivery.endpoint_id,
+          event: delivery.event.name,
+          state: delivery.state,
+          attempt_count: delivery.attempt_count,
+          next_attempt_at: delivery.next_attempt_at&.iso8601,
+          last_attempt_at: delivery.last_attempt_at&.iso8601,
+          created_at: delivery.created_at.iso8601,
+          updated_at: delivery.updated_at.iso8601
+        }
+      end
+
+      def attempt_json(attempt)
+        {
+          id: attempt.id,
+          delivery_id: attempt.delivery_id,
+          response_code: attempt.response_code,
+          response_body: attempt.response_body,
+          error: attempt.error,
+          duration: attempt.duration,
+          created_at: attempt.created_at.iso8601
+        }
+      end
+    end
+  end
+end

data/app/controllers/angarium/api/deliveries_controller.rb

@@ -0,0 +1,29 @@
+module Angarium
+  module Api
+    class DeliveriesController < BaseController
+      # GET /endpoints/:endpoint_id/deliveries
+      def index
+        endpoint = endpoint_scope.find(params[:endpoint_id])
+        authorize!(endpoint)
+        render_collection(:deliveries, endpoint.deliveries.includes(:event).order(created_at: :desc)) { |d| delivery_json(d) }
+      end
+
+      # GET /deliveries/:id
+      # Attempts are fetched separately (and paginated) via
+      # GET /deliveries/:id/attempts.
+      def show
+        delivery = scoped_delivery(params[:id])
+        authorize!(delivery)
+        render json: {delivery: delivery_json(delivery)}
+      end
+
+      # POST /deliveries/:id/redeliver
+      def redeliver
+        delivery = scoped_delivery(params[:id])
+        authorize!(delivery)
+        delivery.redeliver!
+        render json: {delivery: delivery_json(delivery)}, status: :accepted
+      end
+    end
+  end
+end

data/app/controllers/angarium/api/endpoints_controller.rb

@@ -0,0 +1,117 @@
+module Angarium
+  module Api
+    class EndpointsController < BaseController
+      before_action :set_endpoint, only: %i[show update destroy rotate_secret pause enable verify ping]
+
+      def index
+        authorize!
+        render_collection(:endpoints, endpoint_scope.order(created_at: :desc)) { |e| endpoint_json(e) }
+      end
+
+      def show
+        authorize!(@endpoint)
+        render json: {endpoint: endpoint_json(@endpoint)}
+      end
+
+      def create
+        # The owner comes from the policy's #owner (default: current_user), set
+        # before authorize! so policy #create? can gate the target owner.
+        endpoint = Angarium::Endpoint.new(endpoint_params)
+        endpoint.owner = angarium_policy.owner
+        endpoint.status = :unverified if angarium_policy.create_unverified?
+        authorize!(endpoint)
+        endpoint.save!
+        # The signing secret is revealed once, on creation.
+        render json: {endpoint: endpoint_json(endpoint, include_secret: true)}, status: :created
+      end
+
+      def update
+        authorize!(@endpoint)
+        @endpoint.update!(endpoint_params)
+        render json: {endpoint: endpoint_json(@endpoint)}
+      end
+
+      def destroy
+        authorize!(@endpoint)
+        @endpoint.destroy!
+        head :no_content
+      end
+
+      def rotate_secret
+        authorize!(@endpoint)
+        secret = @endpoint.rotate_secret!
+        render json: {endpoint: endpoint_json(@endpoint), signing_secret: secret}
+      end
+
+      def pause
+        authorize!(@endpoint)
+        @endpoint.pause!
+        render json: {endpoint: endpoint_json(@endpoint)}
+      end
+
+      def enable
+        authorize!(@endpoint)
+        @endpoint.enable!
+        render json: {endpoint: endpoint_json(@endpoint)}
+      end
+
+      def verify
+        authorize!(@endpoint)
+        @endpoint.verify!
+        render json: {endpoint: endpoint_json(@endpoint)}
+      end
+
+      def ping
+        authorize!(@endpoint)
+        delivery = @endpoint.ping!
+        render json: {delivery: delivery_json(delivery)}, status: :accepted
+      end
+
+      private
+
+      def set_endpoint
+        @endpoint = endpoint_scope.find(params[:id])
+      end
+
+      # SSRF-relevant controls, each gated by its own policy predicate. They are
+      # independent: allow_private_network relaxes the private-IP denylist
+      # (dangerous), while allowed_networks only restricts delivery to a CIDR
+      # allowlist. permit shape per attribute (scalar vs array).
+      NETWORK_CONTROLS = {
+        allow_private_network: :permit_allow_private_network?,
+        allowed_networks: :permit_allowed_networks?
+      }.freeze
+
+      def endpoint_params
+        policy = angarium_policy
+        permitted = [:name, :url, {subscribed_events: [], custom_headers: {}}]
+
+        NETWORK_CONTROLS.each do |attr, predicate|
+          if policy.public_send(predicate)
+            permitted << ((attr == :allowed_networks) ? {allowed_networks: []} : attr)
+          else
+            reject_network_control_change!(attr)
+          end
+        end
+
+        params.require(:endpoint).permit(*permitted)
+      end
+
+      # A request may not change a network control the policy doesn't permit.
+      # Attempting to (a submitted value that differs from the record's current
+      # value) is a 422 naming the attribute, so an escalation attempt fails
+      # loudly rather than being silently ignored. Echoing the current value is a
+      # no-op and allowed, so a client can round-trip the serialized endpoint.
+      def reject_network_control_change!(attr)
+        body = params.fetch(:endpoint, ActionController::Parameters.new)
+        return unless body.key?(attr)
+
+        current = (@endpoint || Angarium::Endpoint.new).public_send(attr)
+        submitted = body[attr]
+        submitted = Array(submitted).map(&:to_s) if attr == :allowed_networks
+
+        raise Angarium::Api::UnpermittedParameter, attr unless submitted == current
+      end
+    end
+  end
+end

data/app/controllers/angarium/api/not_authorized.rb

@@ -0,0 +1,7 @@
+module Angarium
+  module Api
+    # Raised by a controller when the configured policy denies an action.
+    # Rendered as 403 by Angarium::Api::BaseController.
+    class NotAuthorized < StandardError; end
+  end
+end

data/app/controllers/angarium/api/unpermitted_parameter.rb

@@ -0,0 +1,15 @@
+module Angarium
+  module Api
+    # Raised when a request tries to change an attribute the policy doesn't permit
+    # (e.g. a privileged SSRF control), so the caller fails loudly with a 422
+    # naming the attribute instead of the change being silently dropped.
+    class UnpermittedParameter < StandardError
+      attr_reader :attribute
+
+      def initialize(attribute)
+        @attribute = attribute
+        super("#{attribute} is not permitted")
+      end
+    end
+  end
+end

data/app/helpers/angarium/application_helper.rb

@@ -0,0 +1,4 @@
+module Angarium
+  module ApplicationHelper
+  end
+end

data/app/jobs/angarium/application_job.rb

@@ -0,0 +1,5 @@
+module Angarium
+  class ApplicationJob < ActiveJob::Base
+    queue_as { Angarium.config.job_queue }
+  end
+end

data/app/jobs/angarium/deliver_job.rb

@@ -0,0 +1,11 @@
+module Angarium
+  class DeliverJob < ApplicationJob
+    def perform(delivery_id, force = false)
+      delivery = Delivery.find_by(id: delivery_id)
+      return unless delivery
+      return unless delivery.pending?
+
+      delivery.deliver!(force: force)
+    end
+  end
+end

data/app/models/angarium/application_record.rb

@@ -0,0 +1,17 @@
+module Angarium
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+
+    # Multi-database support: point every Angarium table at a separate database
+    # instead of the app's primary connection. The host sets either config.database
+    # (a database name; the common case) or config.connects_to (a raw hash for
+    # custom roles/shards, which wins if both are set). Read once here at class
+    # load: config/initializers run before the models are first used or
+    # eager-loaded, so the setting is in place by then.
+    if Angarium.config.connects_to
+      connects_to(**Angarium.config.connects_to)
+    elsif (db = Angarium.config.database)
+      connects_to database: {writing: db, reading: db}
+    end
+  end
+end