machina-auth 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3584cdd6299562928d19a2f67d7472a8db478b919c7bf8a18ec9cb36ceefa634
+  data.tar.gz: 1aed243a37779a2758182c91146e6a90fd5d966cc6cb935f4d1e55859b142281
+SHA512:
+  metadata.gz: 979b7056a9721e024d55603d0056fe8fbb327ee69db0276c19c8738506767b26c29bd8312e507b980f7df16a19d3d9618da2a733e76e54ce41e463e8557ec78e
+  data.tar.gz: 5034866ddae72f5aeeb11ac67e2a8b665b9f3e4ef1f5319cd4de9e091c554a5bb59787a2999ce24f3b39ee77aa74a5f06c521440a9f1adba9a00c9fdd8dbd18e

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/README.md

@@ -0,0 +1,54 @@
+# machina-auth
+
+Rails engine that integrates product apps with the Machina Console identity service.
+
+## What It Provides
+
+- **Authentication middleware** — extracts session tokens from cookies, headers, or params and resolves them against the Console
+- **`Machina::Authorized`** — frozen value object with `can?`, `cannot?`, `authorize!`, and permission query methods
+- **`Machina::Current`** — thread-safe current attributes (user, org, workspace, session)
+- **`Machina::ControllerHelpers`** — `require_authorized!` and `authorize!` for controllers
+- **`Machina::WorkspaceScoped`** — concern that filters ActiveRecord queries to the current workspace
+- **Webhook receiver** — verifies HMAC signatures and invalidates cached sessions on permission/membership changes
+- **Permission sync** — pushes a YAML manifest of permissions and policies to the Console on boot
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'machina-auth', path: '../gems/auth'
+```
+
+Run the install generator:
+
+```bash
+bin/rails generate machina:install
+```
+
+## Configuration
+
+```ruby
+Machina.configure do |config|
+  config.identity_service_url = "http://localhost:3100"
+  config.service_token = ENV["MACHINA_SERVICE_TOKEN"]
+  config.product_slug = "my-app"
+  config.manifest = Rails.root.join("config/machina.yml")
+end
+```
+
+## Development
+
+```bash
+cd gems/auth
+bundle install
+bundle exec rspec       # 79 specs
+bundle exec rubocop     # lint
+```
+
+Tests use a dummy Rails app in `spec/dummy/` with an in-memory SQLite database.
+
+## Dependencies
+
+- `rails ~> 8.0.4`
+- `faraday` (HTTP client for Console API calls)

data/app/controllers/machina/webhooks_controller.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Machina
+  # Receives incoming webhook events from the Machina Console and delegates
+  # processing to WebhookReceiver.
+  class WebhooksController < ActionController::API
+    def create
+      receiver = Machina::WebhookReceiver.new(request)
+      return head :unauthorized unless receiver.process!
+
+      head :ok
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+Machina::Engine.routes.draw do
+  post 'webhooks', to: 'webhooks#create'
+end

data/lib/generators/machina/install_generator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Machina
+  # Rails generators for scaffolding Machina configuration files.
+  module Generators
+    # Generates initializer, manifest, and migration files needed to integrate
+    # a Rails application with the Machina auth system.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      def create_initializer
+        template 'machina.rb.tt', 'config/initializers/machina.rb'
+      end
+
+      def create_manifest
+        template 'machina.yml.tt', 'config/machina.yml'
+      end
+
+      def copy_migration
+        template 'create_machina_workspace_refs.rb.tt', "db/migrate/#{timestamp}_create_machina_workspace_refs.rb"
+      end
+
+      private
+
+      def timestamp
+        Time.now.utc.strftime('%Y%m%d%H%M%S')
+      end
+    end
+  end
+end

data/lib/generators/machina/templates/create_machina_workspace_refs.rb.tt

@@ -0,0 +1,13 @@
+class CreateMachinaWorkspaceRefs < ActiveRecord::Migration[8.0]
+  def change
+    create_table :machina_workspace_refs do |t|
+      t.string :tenant_ref, null: false
+      t.string :organization_id
+      t.string :name
+      t.datetime :cached_at
+      t.timestamps
+    end
+
+    add_index :machina_workspace_refs, :tenant_ref, unique: true
+  end
+end

data/lib/generators/machina/templates/machina.rb.tt

@@ -0,0 +1,9 @@
+Machina.configure do |config|
+  config.identity_service_url = ENV.fetch("MACHINA_IDENTITY_URL")
+  config.service_token = ENV.fetch("MACHINA_SERVICE_TOKEN")
+  config.product_id = ENV.fetch("MACHINA_PRODUCT_ID")
+  config.product_slug = "<%= Rails.application.class.module_parent_name.underscore %>"
+  config.cache_store = Rails.cache
+  config.cache_ttl = 5.minutes
+  config.manifest = Rails.root.join("config/machina.yml")
+end

data/lib/generators/machina/templates/machina.yml.tt

@@ -0,0 +1,8 @@
+product_id: # UUID from Console (required for permission sync)
+
+permissions: []
+
+policies:
+  - name: Admin
+    api_name: admin
+    permissions: []

data/lib/machina/authorized.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Machina
+  # Immutable value object representing the currently authenticated user,
+  # their organization/workspace context, and granted permissions.
+  class Authorized
+    attr_reader :user_id, :user_email, :user_name, :avatar_url,
+                :organization_id, :org_name, :org_personal, :org_role,
+                :workspace_id, :workspace_name,
+                :session_id, :expires_at, :type
+
+    def initialize(data = {})
+      assign_user_attrs(data)
+      assign_org_attrs(data)
+      assign_workspace_attrs(data)
+      assign_session_attrs(data)
+      @permissions = Set.new(data['permissions'] || [])
+      freeze
+    end
+
+    def can?(key)
+      @permissions.include?(key)
+    end
+
+    def can_any?(*keys)
+      keys.any? { |key| @permissions.include?(key) }
+    end
+
+    def can_all?(*keys)
+      keys.all? { |key| @permissions.include?(key) }
+    end
+
+    def cannot?(key)
+      !can?(key)
+    end
+
+    def authorize!(key)
+      raise Machina::Unauthorized, key unless can?(key)
+    end
+
+    def authorize_any!(*keys)
+      raise Machina::Unauthorized, keys.join(', ') unless can_any?(*keys)
+    end
+
+    def authorize_all!(*keys)
+      keys.each { |key| authorize!(key) }
+    end
+
+    # Alias matching the product-side column name for consistency.
+    alias tenant_ref workspace_id
+
+    def permissions
+      @permissions.to_a.freeze
+    end
+
+    private
+
+    def assign_user_attrs(data)
+      @user_id    = data.dig('user', 'id')
+      @user_email = data.dig('user', 'email')
+      @user_name  = data.dig('user', 'name')
+      @avatar_url = data.dig('user', 'avatar_url')
+    end
+
+    def assign_org_attrs(data)
+      @organization_id = data.dig('organization', 'id')
+      @org_name        = data.dig('organization', 'name')
+      @org_personal    = data.dig('organization', 'personal')
+      @org_role        = data.dig('membership', 'policy_name') || data.dig('organization', 'role')
+    end
+
+    def assign_workspace_attrs(data)
+      @workspace_id   = data.dig('workspace', 'id')
+      @workspace_name = data.dig('workspace', 'name')
+    end
+
+    def assign_session_attrs(data)
+      @session_id = data.dig('session', 'id') || data['session_id']
+      @type       = data.dig('session', 'type')&.to_sym
+      raw_expires = data.dig('session', 'expires_at') || data['expires_at']
+      @expires_at = raw_expires ? Time.zone.parse(raw_expires) : nil
+    end
+
+    EMPTY = new.freeze # rubocop:disable Lint/UselessConstantScoping
+  end
+end

data/lib/machina/configuration.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Machina
+  # Holds configurable settings for the Machina gem such as service URLs,
+  # tokens, product identifiers, and cache options.
+  class Configuration
+    attr_accessor :identity_service_url,
+                  :service_token,
+                  :product_id,
+                  :product_slug,
+                  :cache_store,
+                  :cache_ttl,
+                  :manifest
+
+    def initialize
+      @cache_ttl = 5.minutes
+    end
+  end
+end

data/lib/machina/controller_helpers.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Machina
+  # Convenience methods mixed into Rails controllers for authentication,
+  # authorization, and session management.
+  module ControllerHelpers
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :authorized, :logged_in? if respond_to?(:helper_method)
+
+      rescue_from Machina::Unauthorized do |error|
+        if request.format.json?
+          render json: { error: 'forbidden', permission: error.message }, status: :forbidden
+        else
+          redirect_to main_app.respond_to?(:root_path) ? main_app.root_path : '/',
+                      alert: "You don't have permission to do that."
+        end
+      end
+    end
+
+    def authorized
+      current = defined?(::Current) ? ::Current : Machina::Current
+      current.authorized || Machina::Authorized::EMPTY
+    end
+
+    def logged_in?
+      authorized.user_id.present?
+    end
+
+    def authenticate!
+      return if logged_in?
+
+      if request.format.json?
+        render json: { error: 'unauthorized' }, status: :unauthorized
+      else
+        redirect_to Machina.authorize_url(redirect_to: request.original_url), allow_other_host: true
+      end
+    end
+
+    # Revokes the current session both locally and in the Console.
+    #
+    # Deletes the local cache entry, calls the Console to revoke server-side,
+    # and removes the session cookie. Errors from the Console call are silently
+    # swallowed so local logout always succeeds.
+    def logout!
+      token = cookies[:machina_session] || extract_bearer_token
+      if token.present?
+        Machina.cache.delete("machina:session:#{token}")
+        begin
+          Machina.identity_client.revoke_session(token)
+        rescue StandardError
+          # Best-effort: local logout succeeds even if Console is unreachable
+        end
+      end
+      cookies.delete(:machina_session)
+    end
+
+    private
+
+    def extract_bearer_token
+      header = request.headers['Authorization'].to_s
+      match = header.match(/\ABearer\s+(.+)\z/)
+      match && match[1]
+    end
+  end
+end

data/lib/machina/current.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Machina
+  # Thread-safe per-request store for the currently authenticated Authorized object.
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :authorized
+  end
+end

data/lib/machina/engine.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Machina
+  # Rails engine that mounts Machina routes, registers controller helpers,
+  # and triggers permission sync on application boot.
+  class Engine < ::Rails::Engine
+    isolate_namespace Machina
+
+    rake_tasks do
+      load File.expand_path('tasks/sync.rake', __dir__)
+    end
+
+    initializer 'machina.controller_helpers' do
+      ActiveSupport.on_load(:action_controller_base) do
+        helper Machina::Engine.helpers if defined?(Machina::Engine.helpers)
+      end
+    end
+
+    # Sync the permission manifest to the Console on boot when configured.
+    # Runs in a background thread so it doesn't block server startup.
+    # Skipped when manifest is not set.
+    config.after_initialize do
+      next if Machina.config.manifest.blank?
+
+      Thread.new do
+        Machina::PermissionSync.call!
+        Rails.logger.info('[machina] Permission manifest synced to Console')
+      rescue StandardError => e
+        Rails.logger.warn("[machina] Permission sync failed on boot: #{e.message}")
+      end
+    end
+  end
+end

data/lib/machina/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Machina
+  # Base error class for all Machina-specific exceptions.
+  class Error < StandardError; end
+
+  # Raised when an action is attempted without the required permission.
+  class Unauthorized < Error; end
+
+  # Raised when a required configuration value is missing or invalid.
+  class ConfigurationError < Error; end
+end

data/lib/machina/identity_client.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Machina
+  # HTTP client for communicating with the Machina Console identity service.
+  # Handles session resolution, revocation, and permission syncing.
+  class IdentityClient
+    Response = Struct.new(:status, :body) do
+      def success?
+        status.between?(200, 299)
+      end
+
+      def parsed
+        body.is_a?(Hash) ? body : JSON.parse(body)
+      end
+    end
+
+    def initialize(config: Machina.config, connection: nil)
+      @config = config
+      @connection = connection
+    end
+
+    def resolve_session(token)
+      post('/internal/v1/sessions/resolve', { token: })
+    end
+
+    def revoke_session(token)
+      post('/internal/v1/sessions/revoke', { token: })
+    end
+
+    def sync_permissions(product_id:, permissions:, policies: [])
+      post("/internal/v1/products/#{product_id}/permissions_sync", {
+        permissions:,
+        policies:
+      })
+    end
+
+    private
+
+    attr_reader :config
+
+    def post(path, payload)
+      ensure_configured!
+
+      response = connection.post(path) do |request|
+        request.headers['Authorization'] = "Bearer #{config.service_token}"
+        request.headers['Content-Type'] = 'application/json'
+        request.headers['Accept'] = 'application/json'
+        request.body = JSON.generate(payload)
+      end
+
+      Response.new(status: response.status, body: response.body.presence || '{}')
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: config.identity_service_url)
+    end
+
+    def ensure_configured!
+      raise ConfigurationError, 'identity_service_url is required' if config.identity_service_url.blank?
+      raise ConfigurationError, 'service_token is required' if config.service_token.blank?
+    end
+  end
+end

data/lib/machina/middleware/authentication.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Machina
+  module Middleware
+    # Rack middleware that extracts authentication tokens from incoming requests,
+    # resolves them against the identity service, and sets Current.authorized.
+    class Authentication
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        request = ActionDispatch::Request.new(env)
+        token = extract_token(request)
+
+        return @app.call(env) if token.blank?
+
+        session_data = resolve_session(token)
+        return unauthorized_response unless session_data
+
+        authorized = Machina::Authorized.new(session_data)
+        Machina::Current.authorized = authorized
+        ::Current.authorized = authorized if defined?(::Current) && ::Current != Machina::Current
+
+        @app.call(env)
+      ensure
+        Machina::Current.reset
+        ::Current.reset if defined?(::Current) && ::Current != Machina::Current
+      end
+
+      private
+
+      def extract_token(request)
+        request.cookies['machina_session'] ||
+          extract_bearer(request) ||
+          request.headers['X-Api-Key'] ||
+          request.params['token']
+      end
+
+      def extract_bearer(request)
+        auth_header = request.headers['Authorization'].to_s
+        match = auth_header.match(/\ABearer\s+(.+)\z/)
+        match && match[1]
+      end
+
+      def resolve_session(token)
+        cached = Machina.cache.read(cache_key(token))
+        return cached if cached.present? && !(cached.is_a?(Hash) && cached[:stale])
+
+        fetch_from_identity_service(token)
+      rescue StandardError
+        nil
+      end
+
+      def fetch_from_identity_service(token)
+        response = Machina.identity_client.resolve_session(token)
+        return nil unless response.success?
+
+        data = unwrap_payload(response.parsed)
+        Machina.cache.write(cache_key(token), data, expires_in: Machina.config.cache_ttl)
+        cache_workspace_ref(data)
+        data
+      end
+
+      def unwrap_payload(payload)
+        payload.fetch('data', payload)
+      end
+
+      def cache_workspace_ref(data)
+        workspace = data['workspace']
+        organization = data['organization']
+        return unless workspace.is_a?(Hash) && organization.is_a?(Hash)
+        return unless defined?(Machina::WorkspaceRef) && Machina::WorkspaceRef.table_exists?
+
+        ref = Machina::WorkspaceRef.find_or_initialize_by(tenant_ref: workspace['id'])
+        ref.organization_id = organization['id']
+        ref.name = workspace['name']
+        ref.cached_at = Time.current
+        ref.save!
+      rescue StandardError
+        nil
+      end
+
+      def cache_key(token)
+        "machina:session:#{token}"
+      end
+
+      def unauthorized_response
+        body = JSON.generate(error: 'unauthorized')
+        [401, { 'Content-Type' => 'application/json', 'Content-Length' => body.bytesize.to_s }, [body]]
+      end
+    end
+  end
+end

data/lib/machina/permission_sync.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Machina
+  # Reads the local permission manifest (machina.yml) and synchronises it
+  # with the Machina Console so the Console knows which permissions exist.
+  class PermissionSync
+    def self.call!
+      new.call!
+    end
+
+    def call!
+      manifest = YAML.load_file(Machina.config.manifest)
+
+      product_id = manifest['product_id'] || Machina.config.product_id
+      if product_id.blank?
+        raise Machina::ConfigurationError,
+              'product_id is required for permission sync (set in machina.yml or Machina.config)'
+      end
+
+      Machina.identity_client.sync_permissions(
+        product_id:,
+        permissions: manifest.fetch('permissions'),
+        policies: manifest.fetch('policies', []),
+      )
+    end
+  end
+end

data/lib/machina/tasks/sync.rake

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+namespace :machina do
+  desc 'Sync permission manifest to Console'
+  task sync_permissions: :environment do
+    Machina::PermissionSync.call!
+    puts 'Permissions synced successfully.'
+  end
+end