omen 0.3.1 → 0.5.0

data/lib/omen/grants.rb

@@ -3,6 +3,12 @@ module Omen
   # may read, and what it may not. Kept apart from the task that runs them, which is about a
   # database it has to find and a refusal it has to survive rather than about privileges.
   module Grants
+    # Membership without inheritance, so a role that enters a narrowed one with SET LOCAL ROLE
+    # is not itself held back by its policies. Postgres 16 and later; below that the grant is
+    # refused and the task says so, which leaves a reading misconfigured rather than narrowing
+    # somebody nobody meant to narrow.
+    APART = 'GRANT %{role} TO %{member} WITH INHERIT FALSE'
+
     # DDL, which Active Record has no expression for, and not a query.
     # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
     # @param members [Array<String>] the roles that may SET LOCAL ROLE to this one. The owner
@@ -12,20 +18,66 @@ module Omen
     def self.statements(connection, members)
       role = connection.quote_table_name Omen.config.narrow_role
       [
-        'DO $$ BEGIN IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = ' \
-          "#{connection.quote Omen.config.narrow_role}) THEN CREATE ROLE #{role} NOLOGIN; " \
-          'END IF; END $$',
-        "ALTER ROLE #{role} WITH #{Attributes::SETTABLE}",
+        *made(connection, Omen.config.narrow_role),
+        *members.map { |member| "GRANT #{role} TO #{connection.quote_table_name member}" },
         "GRANT USAGE ON SCHEMA public TO #{role}",
         "GRANT SELECT ON ALL TABLES IN SCHEMA public TO #{role}",
         "ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO #{role}",
-        *members.map { |member| "GRANT #{role} TO #{connection.quote_table_name member}" },
         *revoked(connection, role),
-        *Omen::Eastern.statements(connection),
+        *Omen::Renamed.statements,
+        *Omen::TimeZone.statements(connection),
         *Omen::Distance.statements(connection),
       ]
     end
 
+    # The same role, made for one audience rather than for every table: it is granted nothing
+    # here, since a narrowing names the tables and the columns of each itself.
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @param name [String] the role to make.
+    # @param members [Array<String>] the roles that may enter it, none of them inheriting it.
+    # @return [Array<String>] the statements to run, in order.
+    def self.narrowed(connection, name, members)
+      role = connection.quote_table_name name
+      [
+        *made(connection, name),
+        *members.map { |member| apart role, connection.quote_table_name(member) },
+        "GRANT USAGE ON SCHEMA public TO #{role}",
+      ]
+    end
+
+    # @param role [String] the role, quoted.
+    # @param member [String] the role that may enter it, quoted.
+    # @return [String] the statement that lets it in without handing it what the role holds.
+    def self.apart(role, member) = APART % { role: role, member: member }
+
+    # Named one by one rather than granted whole: a column added to hold a secret, or to count
+    # what belongs to everybody, is one a role has to be given before it can read it. Taken away
+    # first, since a grant only ever adds: without the revoke, a column dropped from the list
+    # stays readable by whoever was granted it the last time this ran.
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @param name [String] the role to grant them to.
+    # @param table [String] the table whose columns are being granted.
+    # @param refused [Regexp] the columns of it that role may not read.
+    # @return [Array<String>] what it may read of that table, said over again.
+    def self.granted(connection, name, table, refused)
+      role = connection.quote_table_name name
+      quoted = connection.quote_table_name table
+      columns = connection.columns(table).map(&:name).grep_v(refused)
+        .map { |column| connection.quote_column_name column }
+      [ "REVOKE ALL ON #{quoted} FROM #{role}",
+        "GRANT SELECT (#{columns.join ', '}) ON #{quoted} TO #{role}", ]
+    end
+
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @param name [String] the role to make, where the database has not got it.
+    # @return [Array<String>] the statements that make it and say what it may be.
+    def self.made(connection, name)
+      role = connection.quote_table_name name
+      [ 'DO $$ BEGIN IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = ' \
+          "#{connection.quote name}) THEN CREATE ROLE #{role} NOLOGIN; END IF; END $$",
+        "ALTER ROLE #{role} WITH #{Attributes::SETTABLE}", ]
+    end
+
     # Intersected, so a bare db:create with no table yet to revoke on is not a failure.
     # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
     # @param role [String] the role to hide this feature's own tables from.

data/lib/omen/inquirer.rb

@@ -14,30 +14,30 @@ module Omen
     UNMADE = 'Could not make %{role}, so every reading will say this app is misconfigured. Ask ' \
              'for that role, NOLOGIN, granted SELECT on every table but %{tables}.'
 
-    # Said per statement, since the grants, the revocations and the functions need nothing from
-    # one another and one refusal should not discard the rest.
+    # Said per group, since the grants, the revocations and the functions need nothing from one
+    # another and one refusal should not discard the rest.
     REFUSED = 'Skipped, refused by the database: %{statement} (%{error})'
 
     # Said where a role that already existed is one a reading should not be able to reach through.
     DANGEROUS = '%{role} holds %{held}. This gem cannot take that away without being a superuser ' \
                 'itself, so ask for it to be taken away.'
 
-    # Creates the role and the function, on every database this environment prepares.
+    # Creates the role and the functions, and writes every narrowing a host declared, on every
+    # database this environment prepares.
     # @return [void]
-    def self.grant
-      environments.each do |environment|
-        config = ActiveRecord::Base.configurations.configs_for env_name: environment,
-          name: 'primary'
-        next unless config
-        ActiveRecord::Tasks::DatabaseTasks.with_temporary_connection config do |connection|
-          grant_on connection
+    def self.grant = Omen.each_database { |connection| grant_on connection }
+
+    # Takes every narrowing back off, leaving each table read the way it was read before one.
+    # @return [void]
+    def self.widen
+      Omen.each_database do |connection|
+        Omen::Reading.narrowings.each do |narrowing|
+          narrowing.widening(connection).each { |group| attempted connection, *group }
+          puts "Widened #{connection.current_database} back out of #{narrowing.role}"
         end
       end
     end
 
-    # @return [Array<String>] the environments whose databases this run should cover.
-    def self.environments = Rails.env.development? ? %w[ development test ] : [Rails.env.to_s]
-
     # Warns rather than raises: a managed database never grants CREATEROLE, and a deploy that
     # cannot make the role must still finish, having said what has to be made by hand.
     # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
@@ -54,18 +54,34 @@ module Omen
       held = Attributes.dangerous connection
       warn DANGEROUS % { role: role, held: held.to_sentence } if held.any?
       puts "Granted SELECT on #{connection.current_database} to #{role}"
+      narrow connection, members
     end
 
-    # One statement at a time, so a database that refuses one still runs the others -- and each
-    # inside a savepoint of its own, since a refusal inside a transaction refuses everything
-    # after it too, and this task is as likely to be run from a console as from a deploy.
+    # Every audience a host declared, written into the database its readings are answered from.
     # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
-    # @param statement [String] one of the statements Omen::Grants builds.
+    # @param members [Array<String>] the roles that may enter a narrowed one.
     # @return [void]
-    def self.attempted(connection, statement)
-      connection.transaction(requires_new: true) { connection.execute statement }
+    def self.narrow(connection, members)
+      Omen::Reading.narrowings.each do |narrowing|
+        narrowing.statements(connection, members).each { |group| attempted connection, *group }
+        puts "Narrowed #{narrowing.role} to the rows #{narrowing.setting} names"
+      end
+    end
+
+    # A group at a time, so a database that refuses one still runs the others -- and each inside
+    # a savepoint of its own, since a refusal inside a transaction refuses everything after it
+    # too, and this task is as likely to be run from a console as from a deploy. What arrives
+    # together is applied together: a table is never left with row level security on and no
+    # policy under it.
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @param statements [Array<String>] what Omen::Grants or a narrowing built.
+    # @return [void]
+    def self.attempted(connection, *statements)
+      connection.transaction(requires_new: true) do
+        statements.each { |statement| connection.execute statement }
+      end
     rescue ActiveRecord::StatementInvalid => error
-      warn REFUSED % { statement: statement.squish, error: error.message.lines.first.strip }
+      warn REFUSED % { statement: statements.first.squish, error: error.message.lines.first.strip }
     end
 
     # Discovered rather than named: SET LOCAL ROLE needs the connecting role to be a member of

data/lib/omen/narrowing.rb

@@ -0,0 +1,87 @@
+module Omen
+  # What one audience of a reading may read: the role its statement runs as, the rows each
+  # table admits it, and the tables it reads whole because nothing in them is anybody's.
+  class Narrowing
+    # The policy every role holds, so that turning row level security on takes nothing away
+    # from whoever could already read -- a role made after this ran included. The narrowed role
+    # is held back by the restrictive policy beside it, which is ANDed with this one and
+    # applies to nobody else.
+    EVERYBODY = 'omen_everybody'
+
+    # @return [String] the Postgres role a reading of this audience runs as.
+    attr_reader :role
+
+    # @return [Symbol] the column of the reading that says whose rows these are.
+    attr_reader :by
+
+    # @param role [String] the Postgres role a reading of this audience runs as.
+    # @param by [Symbol] the column of the reading that says whose rows these are.
+    # @param own [Hash] every table it reads rows of, to what makes a row its own. A table is
+    #   named either way, since a host writing one of these writes symbols or strings by habit.
+    # @param whole [Array<String>] the tables it reads whole, nobody's in particular.
+    # @param except [Regexp, nil] the columns of those it may not read, a counter over everybody
+    #   being the case this exists for: it counts every owner rather than this one.
+    def initialize(role:, by:, own:, whole: [], except: nil)
+      @role = role
+      @by = by
+      @own = own.transform_keys(&:to_s)
+      @whole = whole.map(&:to_s)
+      @except = except
+    end
+
+    # @return [String] the setting a policy reads to know whose rows it is looking at.
+    def setting = "omen.#{@by}"
+
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @param members [Array<String>] the roles that may enter this one.
+    # @return [Array<Array<String>>] the statements, grouped: what arrives together is applied
+    #   together, so no table is left with row level security on and no policy under it.
+    def statements(connection, members)
+      [ Grants.narrowed(connection, @role, members),
+        *@whole.map { |table| granted connection, table },
+        *@own.map { |table, own| narrowed connection, table, own }, ]
+    end
+
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @return [Array<Array<String>>] the statements that take it back off, table by table.
+    def widening(connection)
+      @own.keys.map { |table| widened connection, table }
+    end
+
+  private
+
+    # The permissive policy first and the table turned on last, so a group that stops short
+    # leaves a table nobody has been narrowed on rather than one nobody can read.
+    def narrowed(connection, table, own)
+      quoted = connection.quote_table_name table
+      [ *granted(connection, table),
+        *policy(connection, quoted, EVERYBODY, 'FOR ALL TO PUBLIC USING (true) WITH CHECK (true)'),
+        *policy(connection, quoted, "#{table}_#{@role}",
+          "AS RESTRICTIVE FOR SELECT TO #{connection.quote_table_name @role} " \
+          "USING (#{format own, owner: owner, setting: setting})"),
+        "ALTER TABLE #{quoted} ENABLE ROW LEVEL SECURITY", ]
+    end
+
+    # Dropped first, so that running this again says what it said the first time.
+    def policy(connection, quoted, name, rule)
+      named = connection.quote_table_name name
+      [ "DROP POLICY IF EXISTS #{named} ON #{quoted}",
+        "CREATE POLICY #{named} ON #{quoted} #{rule}", ]
+    end
+
+    def widened(connection, table)
+      quoted = connection.quote_table_name table
+      [ "DROP POLICY IF EXISTS #{connection.quote_table_name "#{table}_#{@role}"} ON #{quoted}",
+        "DROP POLICY IF EXISTS #{connection.quote_table_name EVERYBODY} ON #{quoted}",
+        "ALTER TABLE #{quoted} DISABLE ROW LEVEL SECURITY", ]
+    end
+
+    # Empty where the reading names nobody, and no row is nobody's, so nobody reads nothing.
+    def owner = "NULLIF(current_setting('#{setting}', true), '')::bigint"
+
+    def granted(connection, table)
+      refused = [ Omen::Column::CREDENTIALS, (@except if @whole.include? table) ].compact
+      Grants.granted connection, @role, table, Regexp.union(refused)
+    end
+  end
+end

data/lib/omen/renamed.rb

@@ -0,0 +1,17 @@
+module Omen
+  # The names these functions had before 1.0, dropped so a database matches the gem installed in
+  # it. A statement stored before the rename names them, and dropping them makes re-running one
+  # fail where leaving them would have it quietly answer -- from a function nothing maintains any
+  # more. An answer already drawn is unaffected: its rows are stored, not recomputed.
+  #
+  # Delete this file once no database still has them.
+  module Renamed
+    # Signatures rather than names, since a function is dropped by the arguments it takes.
+    BEFORE = [ 'eastern(timestamp)', 'eastern(timestamptz)',
+               'miles_between(double precision, double precision, double precision, ' \
+               'double precision)', ]
+
+    # @return [Array<String>] one DROP per function this gem used to create.
+    def self.statements = BEFORE.map { |signature| "DROP FUNCTION IF EXISTS #{signature}" }
+  end
+end

data/lib/omen/time_zone.rb

@@ -0,0 +1,57 @@
+module Omen
+  # The zone the company works in, and the two questions a reading asks about it: what a stored
+  # timestamp says here, and what day it is here. Created by the rake task rather than by a
+  # migration, because Rails' :ruby schema format dumps no functions, so db:schema:load would
+  # drop one a migration had made -- and the format cannot become :sql, since db/schema.rb is
+  # what Claude is shown.
+  module TimeZone
+    # The zone as Postgres names one: Time.zone.name is not a name it takes.
+    ZONE = 'America/New_York'
+
+    # DDL, which Active Record has no expression for, and not a query.
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @return [Array<String>] the statements to run, in order.
+    def self.statements(connection) = [ stored(connection), instant(connection), today(connection) ]
+
+    # A stored timestamp says nothing about its own zone, so it is named UTC and then rendered.
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @return [String] the statement declaring the function over a naked timestamp.
+    def self.stored(connection)
+      "CREATE OR REPLACE FUNCTION #{name connection}(ts timestamp) RETURNS timestamp AS " \
+        "$$ SELECT ts AT TIME ZONE 'UTC' AT TIME ZONE #{connection.quote ZONE} $$ " \
+        'LANGUAGE sql IMMUTABLE'
+    end
+
+    # One conversion and not two: an instant already knows which moment it is, so naming it UTC
+    # first would convert it twice and answer hours out. Overloaded because Postgres will not
+    # cast an instant to a timestamp to resolve a call, so now() reaches neither without it.
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @return [String] the statement declaring the function over an instant.
+    def self.instant(connection)
+      "CREATE OR REPLACE FUNCTION #{name connection}(ts timestamptz) RETURNS timestamp AS " \
+        "$$ SELECT ts AT TIME ZONE #{connection.quote ZONE} $$ LANGUAGE sql IMMUTABLE"
+    end
+
+    # What makes a window slide: a statement saying `date_trunc('month', omen_today())` answers
+    # for whichever month it is run in, where a literal answers for the month it was written in.
+    #
+    # STABLE and not IMMUTABLE, unlike its neighbours, which are pure functions of what they are
+    # given. This one reads the clock: marked immutable, Postgres is entitled to fold it to a
+    # constant, and a window would stop moving in the way this function exists to prevent. Stable
+    # is also what has it evaluated once per statement, so a query naming it five times cannot
+    # straddle midnight.
+    #
+    # A date and not a timestamp, so a window cannot silently mean "up to the current hour".
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @return [String] the statement declaring the function.
+    def self.today(connection)
+      "CREATE OR REPLACE FUNCTION #{connection.quote_table_name Omen::Instructions::TODAY}() " \
+        "RETURNS date AS $$ SELECT (now() AT TIME ZONE #{connection.quote ZONE})::date $$ " \
+        'LANGUAGE sql STABLE'
+    end
+
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @return [String] the function's name, quoted.
+    def self.name(connection) = connection.quote_table_name Omen::Instructions::TIME_ZONE
+  end
+end

data/lib/omen/version.rb

@@ -1,4 +1,4 @@
 module Omen
   # The version of this gem, as RubyGems knows it.
-  VERSION = '0.3.1'
+  VERSION = '0.5.0'
 end

data/lib/omen.rb

@@ -4,8 +4,11 @@ require 'anthropic'
 require 'omen/attributes'
 require 'omen/config'
 require 'omen/distance'
-require 'omen/eastern'
 require 'omen/grants'
+require 'omen/renamed'
+require 'omen/time_zone'
+require 'omen/bound'
+require 'omen/narrowing'
 require 'omen/inquirer'
 require 'omen/requirements'
 require 'omen/version'
@@ -23,4 +26,19 @@ module Omen
   # Yields the configuration, so a host states its own facts in one initializer.
   # @return [void]
   def self.configure = yield config
+
+  # @return [Array<String>] the environments whose databases a grant should cover.
+  def self.environments = Rails.env.development? ? %w[ development test ] : [Rails.env.to_s]
+
+  # @yield [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing connection to each
+  #   database this environment prepares.
+  # @return [void]
+  def self.each_database
+    environments.each do |environment|
+      config = ActiveRecord::Base.configurations.configs_for env_name: environment,
+        name: 'primary'
+      next unless config
+      ActiveRecord::Tasks::DatabaseTasks.with_temporary_connection(config) { |it| yield it }
+    end
+  end
 end

data/lib/tasks/omen.rake

@@ -1,9 +1,23 @@
 namespace :db do
   namespace :omen do
-    desc 'Create the role a reading runs its statement as, and the function it reads a ' \
-         'timestamp through'
+    desc 'Create the role a reading runs its statement as, the function it reads a ' \
+         'timestamp through, and the policies every narrowing a host declared asks for'
     task grant: :environment do
       Omen::Inquirer.grant
     end
+
+    desc 'Take every narrowing back off, leaving each table read the way it was read before'
+    task widen: :environment do
+      Omen::Inquirer.widen
+    end
+
+    desc 'Say which roles the policies of a narrowing hold back, membership included'
+    task narrowed: :environment do
+      Omen.config.record.with_connection do |connection|
+        Omen::Bound.roles(connection).each { |row| puts row.join ' ' }
+        surprises = Omen::Bound.surprises connection
+        abort "Narrowed without being asked for: #{surprises.inspect}" if surprises.any?
+      end
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omen
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -73,6 +73,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
+- INSTRUCTIONS.md
 - LICENSE.txt
 - README.md
 - app/models/omen/answer.rb
@@ -83,9 +84,12 @@ files:
 - app/models/omen/executed.rb
 - app/models/omen/instructions.md
 - app/models/omen/instructions.rb
+- app/models/omen/narrowed.rb
 - app/models/omen/query.rb
 - app/models/omen/question.rb
 - app/models/omen/reading.rb
+- app/models/omen/refusal.rb
+- app/models/omen/reply.rb
 - app/models/omen/revealed.rb
 - app/models/omen/role.rb
 - app/models/omen/schema.rb
@@ -94,18 +98,29 @@ files:
 - db/migrate/20260821120000_create_omen_readings.rb
 - db/migrate/20260821120001_create_omen_questions.rb
 - db/migrate/20260821120002_create_omen_answers.rb
+- db/migrate/20260912000000_add_type_to_omen_readings.rb
 - lib/generators/omen/install/install_generator.rb
 - lib/generators/omen/install/templates/omen.rb
+- lib/generators/omen/pages/USAGE
+- lib/generators/omen/pages/pages_generator.rb
+- lib/generators/omen/pages/templates/_form.html.erb.tt
+- lib/generators/omen/pages/templates/controller.rb.tt
+- lib/generators/omen/pages/templates/index.html.erb.tt
+- lib/generators/omen/pages/templates/model.rb.tt
+- lib/generators/omen/pages/templates/show.html.erb.tt
 - lib/omen.rb
 - lib/omen/attributes.rb
+- lib/omen/bound.rb
 - lib/omen/config.rb
 - lib/omen/distance.rb
-- lib/omen/eastern.rb
 - lib/omen/engine.rb
 - lib/omen/grants.rb
 - lib/omen/inquirer.rb
+- lib/omen/narrowing.rb
+- lib/omen/renamed.rb
 - lib/omen/requirements.rb
 - lib/omen/stubs.rb
+- lib/omen/time_zone.rb
 - lib/omen/version.rb
 - lib/tasks/omen.rake
 homepage: https://github.com/claudiob/omen

data/lib/omen/eastern.rb

@@ -1,40 +0,0 @@
-module Omen
-  # The database function a reading's SQL reads every timestamp through. Created by the rake
-  # task rather than by a migration, because Rails' :ruby schema format dumps no functions, so
-  # db:schema:load would drop one a migration had made -- and the format cannot become :sql,
-  # since db/schema.rb is what Claude is shown.
-  module Eastern
-    # The zone the company works in, as Postgres names one: Time.zone.name is not one it takes.
-    ZONE = 'America/New_York'
-
-    # DDL, which Active Record has no expression for, and not a query.
-    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
-    # @return [Array<String>] the statements to run, in order.
-    def self.statements(connection)
-      [ stored(connection), instant(connection) ]
-    end
-
-    # A stored timestamp says nothing about its own zone, so it is named UTC and then rendered.
-    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
-    # @return [String] the statement declaring the function over a naked timestamp.
-    def self.stored(connection)
-      "CREATE OR REPLACE FUNCTION #{name connection}(ts timestamp) RETURNS timestamp AS " \
-        "$$ SELECT ts AT TIME ZONE 'UTC' AT TIME ZONE #{connection.quote ZONE} $$ " \
-        'LANGUAGE sql IMMUTABLE'
-    end
-
-    # One conversion and not two: an instant already knows which moment it is, so naming it UTC
-    # first would convert it twice and answer hours out. Overloaded because Postgres will not
-    # cast an instant to a timestamp to resolve a call, so now() reaches neither without it.
-    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
-    # @return [String] the statement declaring the function over an instant.
-    def self.instant(connection)
-      "CREATE OR REPLACE FUNCTION #{name connection}(ts timestamptz) RETURNS timestamp AS " \
-        "$$ SELECT ts AT TIME ZONE #{connection.quote ZONE} $$ LANGUAGE sql IMMUTABLE"
-    end
-
-    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
-    # @return [String] the function's name, quoted.
-    def self.name(connection) = connection.quote_table_name Omen::Instructions::EASTERN
-  end
-end