securedgram 0.1.0

data/exe/sg-clean

@@ -0,0 +1,337 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# sg-clean -- SecureDGram CLI tool to purge old messages from the database
+#
+# Deletes terminal-state messages older than the specified age.
+# By default purges:
+#   - Outbound: acknowledged, send_failed
+#   - Inbound:  ack_sent, ack_failed (only where read_count > 0)
+#
+# Usage:
+#   sg-clean <age>                      # e.g., 7d, 24h, 4w
+#   sg-clean --before <datetime>        # ISO 8601: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS
+#   sg-clean --dry-run 30d              # preview what would be deleted
+#
+# Age suffixes (GNU sleep / systemd convention):
+#   s = seconds, m = minutes, h = hours, d = days, w = weeks
+
+require 'securedgram/version'
+require 'securedgram/env_loader'
+
+## Load .env:
+SecureDGram::EnvLoader.load_dotenv
+
+require 'optparse'
+require 'json'
+require 'sqlite3'
+require 'time'
+
+## Duration suffix multipliers (GNU sleep / systemd convention):
+DURATION_MULTIPLIERS = {
+  's' => 1,
+  'm' => 60,
+  'h' => 3600,
+  'd' => 86400,
+  'w' => 604800,
+}.freeze
+
+##
+## Parse a duration string like "7d", "24h", "30m", "3600s", "4w"
+## Returns seconds as an integer, or nil if invalid.
+##
+def parse_duration(str)
+  str = str.strip
+  if m = /\A(\d+)([smhdw])\z/.match(str)
+    return m[1].to_i * DURATION_MULTIPLIERS[m[2]]
+  end
+  nil
+end
+
+##
+## Parse an age argument: either a duration suffix or an ISO 8601 datetime.
+## Returns a Time object representing the cutoff.
+##
+def parse_cutoff(str)
+  ## Try duration first:
+  seconds = parse_duration(str)
+  if seconds
+    return Time.now - seconds
+  end
+
+  ## Try ISO 8601 datetime (Time.parse handles YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, etc.):
+  begin
+    return Time.parse(str)
+  rescue ArgumentError
+    nil
+  end
+end
+
+## Defaults:
+db_path        = ENV.fetch('SECUREDGRAM_DB', 'securedgram.db')
+dry_run        = false
+auto_yes       = false
+no_vacuum      = false
+outbound_only  = false
+inbound_only   = false
+include_unread = false
+all_states     = false
+target_state   = nil
+before_str     = nil
+
+optparser = OptionParser.new do |opts|
+  opts.banner = "Usage: #{File.basename($0)} [options] <age>"
+  opts.separator ""
+  opts.separator "SecureDGram v#{SecureDGram::VERSION} -- Purge old messages from the database."
+  opts.separator ""
+  opts.separator "Age format: <number><suffix> where suffix is:"
+  opts.separator "  s = seconds, m = minutes, h = hours, d = days, w = weeks"
+  opts.separator "  Examples: 7d (7 days), 24h (24 hours), 4w (4 weeks), 3600s (1 hour)"
+  opts.separator ""
+  opts.separator "Options:"
+
+  opts.on("--db PATH", "SQLite3 database path (default: from .env)") do |path|
+    db_path = path
+  end
+
+  opts.on("--before DATETIME", "Purge messages before this date (ISO 8601: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS)") do |dt|
+    before_str = dt
+  end
+
+  opts.on("--dry-run", "Show what would be deleted without actually deleting") do
+    dry_run = true
+  end
+
+  opts.on("-y", "--yes", "Skip confirmation prompt (for scripting)") do
+    auto_yes = true
+  end
+
+  opts.on("--no-vacuum", "Skip VACUUM after deletion") do
+    no_vacuum = true
+  end
+
+  opts.on("--outbound-only", "Only purge outbound messages") do
+    outbound_only = true
+  end
+
+  opts.on("--inbound-only", "Only purge inbound messages") do
+    inbound_only = true
+  end
+
+  opts.on("--include-unread", "Also purge inbound messages with read_count = 0") do
+    include_unread = true
+  end
+
+  opts.on("--all-states", "Purge ALL matching rows regardless of state (DANGEROUS)") do
+    all_states = true
+  end
+
+  opts.on("-s", "--state STATE", "Target a specific state only (e.g., send_failed, acknowledged)") do |s|
+    target_state = s
+  end
+
+  opts.on("-V", "--version", "Show version and exit") do
+    puts "sg-clean (SecureDGram) #{SecureDGram::VERSION}"
+    exit
+  end
+
+  opts.on("-h", "--help", "Show this help") do
+    puts opts
+    exit
+  end
+end
+
+begin
+  optparser.parse!(ARGV)
+rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
+  STDERR.puts "ERROR: #{e.message}"
+  STDERR.puts optparser
+  exit 1
+end
+
+## Conflicting flags:
+if outbound_only && inbound_only
+  STDERR.puts "ERROR: --outbound-only and --inbound-only are mutually exclusive."
+  exit 1
+end
+
+## Parse cutoff time:
+cutoff = nil
+
+if before_str
+  cutoff = parse_cutoff(before_str)
+  unless cutoff
+    STDERR.puts "ERROR: Cannot parse --before value: #{before_str.inspect}"
+    STDERR.puts "Expected ISO 8601 format: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS"
+    exit 1
+  end
+elsif ARGV.size >= 1
+  cutoff = parse_cutoff(ARGV[0])
+  unless cutoff
+    STDERR.puts "ERROR: Cannot parse age: #{ARGV[0].inspect}"
+    STDERR.puts "Expected format: <number><suffix> where suffix is s/m/h/d/w"
+    STDERR.puts "  Examples: 7d, 24h, 30m, 3600s, 4w"
+    STDERR.puts "Or ISO 8601: YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS"
+    exit 1
+  end
+else
+  STDERR.puts "ERROR: Missing required age argument."
+  STDERR.puts optparser
+  exit 1
+end
+
+cutoff_str = cutoff.strftime('%Y-%m-%dT%H:%M:%S.%6N')
+
+## Verify database exists:
+unless File.file?(db_path)
+  STDERR.puts "ERROR: Database not found at #{db_path}"
+  exit 1
+end
+
+## Terminal states for each table:
+OUTBOUND_TERMINAL = ['acknowledged', 'send_failed'].freeze
+INBOUND_TERMINAL  = ['ack_sent', 'ack_failed'].freeze
+
+##
+## Build DELETE conditions for a table.
+## Returns [where_clause, params] or nil if this table should be skipped.
+##
+def build_conditions(table, cutoff_str, target_state, all_states, include_unread)
+  conditions = []
+  params = []
+
+  conditions << "updated_at < ?"
+  params << cutoff_str
+
+  ## State filter:
+  if target_state
+    conditions << "state = ?"
+    params << target_state
+  elsif !all_states
+    if table == 'outbound_messages'
+      placeholders = OUTBOUND_TERMINAL.map { '?' }.join(', ')
+      conditions << "state IN (#{placeholders})"
+      params.concat(OUTBOUND_TERMINAL)
+    else
+      placeholders = INBOUND_TERMINAL.map { '?' }.join(', ')
+      conditions << "state IN (#{placeholders})"
+      params.concat(INBOUND_TERMINAL)
+    end
+  end
+
+  ## For inbound: skip unread unless --include-unread:
+  if table == 'inbound_messages' && !include_unread && !all_states
+    conditions << "read_count > 0"
+  end
+
+  where = conditions.join(" AND ")
+  return where, params
+end
+
+begin
+  db = SQLite3::Database.new(db_path)
+  db.results_as_hash = true
+  db.execute("PRAGMA journal_mode = WAL")
+  db.busy_timeout = 5000
+
+  tables = []
+  tables << 'outbound_messages' unless inbound_only
+  tables << 'inbound_messages'  unless outbound_only
+
+  total_to_delete = 0
+  table_counts = {}
+
+  ## Count phase:
+  tables.each do |table|
+    where, params = build_conditions(table, cutoff_str, target_state, all_states, include_unread)
+    count_query = "SELECT COUNT(*) as cnt FROM #{table} WHERE #{where}"
+    row = db.get_first_row(count_query, params)
+    count = row ? row['cnt'] : 0
+    table_counts[table] = { count: count, where: where, params: params }
+    total_to_delete += count
+  end
+
+  ## Report:
+  puts "Cutoff: #{cutoff.strftime('%Y-%m-%d %H:%M:%S')} (messages last updated before this time)"
+  puts ""
+
+  tables.each do |table|
+    info = table_counts[table]
+    label = table == 'outbound_messages' ? 'Outbound' : 'Inbound'
+
+    if info[:count] > 0
+      ## Show state breakdown:
+      where = info[:where]
+      params = info[:params]
+      breakdown_query = "SELECT state, COUNT(*) as cnt FROM #{table} WHERE #{where} GROUP BY state ORDER BY cnt DESC"
+      breakdown = db.execute(breakdown_query, params)
+      puts "  #{label}: #{info[:count]} rows to delete"
+      breakdown.each do |brow|
+        puts "    #{brow['state']}: #{brow['cnt']}"
+      end
+    else
+      puts "  #{label}: 0 rows to delete"
+    end
+  end
+
+  puts ""
+
+  if total_to_delete == 0
+    puts "Nothing to delete."
+    db.close
+    exit 0
+  end
+
+  if dry_run
+    puts "(dry run — no rows were deleted)"
+    db.close
+    exit 0
+  end
+
+  ## Confirmation:
+  unless auto_yes
+    STDERR.print "Delete #{total_to_delete} rows? [y/N] "
+    STDERR.flush
+    answer = STDIN.gets
+    unless answer && answer.strip.downcase == 'y'
+      puts "Cancelled."
+      db.close
+      exit 0
+    end
+  end
+
+  ## Delete phase:
+  total_deleted = 0
+  tables.each do |table|
+    info = table_counts[table]
+    next if info[:count] == 0
+
+    delete_query = "DELETE FROM #{table} WHERE #{info[:where]}"
+    db.execute(delete_query, info[:params])
+    deleted = db.changes
+    total_deleted += deleted
+
+    label = table == 'outbound_messages' ? 'Outbound' : 'Inbound'
+    puts "  #{label}: #{deleted} rows deleted"
+  end
+
+  puts ""
+  puts "Total: #{total_deleted} rows deleted."
+
+  ## VACUUM (default unless --no-vacuum):
+  unless no_vacuum
+    puts "Running VACUUM to reclaim disk space..."
+    db.execute("VACUUM")
+    puts "VACUUM complete."
+  end
+
+  db.close
+
+rescue SQLite3::BusyException => e
+  STDERR.puts "ERROR: Database is busy: #{e.message}"
+  STDERR.puts "The daemon or another process is holding the lock. Try again."
+  exit 1
+rescue SQLite3::Exception => e
+  STDERR.puts "ERROR: Database error: #{e.class}: #{e.message}"
+  exit 1
+end

data/exe/sg-recv

@@ -0,0 +1,287 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# sg-recv -- SecureDGram CLI tool to read received (inbound) messages
+#
+# Queries the inbound_messages table and outputs results as JSON.
+# Can also query outbound message status.
+#
+# Usage:
+#   sg-recv [options]              # show recent inbound messages
+#   sg-recv --outbound [options]   # show outbound message status
+#   sg-recv --follow               # poll for new messages continuously
+
+require 'securedgram/version'
+require 'securedgram/env_loader'
+
+## Load .env:
+SecureDGram::EnvLoader.load_dotenv
+
+require 'optparse'
+require 'json'
+require 'sqlite3'
+
+## Defaults:
+db_path      = ENV.fetch('SECUREDGRAM_DB', 'securedgram.db')
+limit        = 20
+outbound     = false
+state        = nil
+from_addr    = nil
+msg_id       = nil
+follow       = false
+interval     = 1.0
+since_id     = nil
+compact      = false
+payload_only = false
+read_included = false
+no_mark      = false
+
+optparser = OptionParser.new do |opts|
+  opts.banner = "Usage: #{File.basename($0)} [options]"
+  opts.separator ""
+  opts.separator "SecureDGram v#{SecureDGram::VERSION} -- Read messages from the database."
+  opts.separator ""
+  opts.separator "Options:"
+
+  opts.on("--db PATH", "SQLite3 database path (default: from .env)") do |path|
+    db_path = path
+  end
+
+  opts.on("-n", "--limit N", Integer, "Number of messages to return (default: 20, 0 = all)") do |n|
+    limit = n
+  end
+
+  opts.on("-o", "--outbound", "Query outbound messages instead of inbound") do
+    outbound = true
+  end
+
+  opts.on("-s", "--state STATE", "Filter by message state (e.g., ack_sent, received, pending, sent, acknowledged)") do |s|
+    state = s
+  end
+
+  opts.on("--from ADDR", "Filter inbound by sender IP address") do |addr|
+    from_addr = addr
+  end
+
+  opts.on("--to ADDR", "Filter outbound by destination IP address") do |addr|
+    from_addr = addr  ## Reuse same variable; context changes meaning
+  end
+
+  opts.on("-i", "--id MESSAGE_ID", "Look up a specific message by message_id") do |mid|
+    msg_id = mid.strip.downcase
+  end
+
+  opts.on("-f", "--follow", "Continuously poll for new messages (Ctrl+C to stop)") do
+    follow = true
+  end
+
+  opts.on("--interval SECS", Float, "Poll interval in seconds for --follow mode (default: 1.0)") do |secs|
+    interval = secs
+  end
+
+  opts.on("--since-id ID", Integer, "Only show messages with row id > ID") do |id|
+    since_id = id
+  end
+
+  opts.on("-c", "--compact", "Output one JSON object per line (JSONL) instead of pretty-printed") do
+    compact = true
+  end
+
+  opts.on("-p", "--payload-only", "Output only the payload field of each message") do
+    payload_only = true
+  end
+
+  opts.on("-r", "--read-included", "Include already-read messages (default: unread only for inbound)") do
+    read_included = true
+  end
+
+  opts.on("--no-mark", "Don't increment read_count (peek without marking as read)") do
+    no_mark = true
+  end
+
+  opts.on("-V", "--version", "Show version and exit") do
+    puts "sg-recv (SecureDGram) #{SecureDGram::VERSION}"
+    exit
+  end
+
+  opts.on("-h", "--help", "Show this help") do
+    puts opts
+    exit
+  end
+end
+
+begin
+  optparser.parse!(ARGV)
+rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
+  STDERR.puts "ERROR: #{e.message}"
+  STDERR.puts optparser
+  exit 1
+end
+
+## Verify database exists:
+unless File.file?(db_path)
+  STDERR.puts "ERROR: Database not found at #{db_path}"
+  STDERR.puts "Has the daemon been started at least once? (It creates the DB on first run.)"
+  exit 1
+end
+
+## Build query:
+def build_query(outbound, msg_id, state, from_addr, since_id, limit, read_included)
+  table = outbound ? "outbound_messages" : "inbound_messages"
+  conditions = []
+  params = []
+
+  if msg_id
+    conditions << "message_id = ?"
+    params << msg_id
+  end
+
+  if state
+    conditions << "state = ?"
+    params << state
+  end
+
+  if from_addr
+    if outbound
+      conditions << "dst_addr = ?"
+    else
+      conditions << "src_addr = ?"
+    end
+    params << from_addr
+  end
+
+  if since_id
+    conditions << "id > ?"
+    params << since_id
+  end
+
+  ## For inbound queries, default to unread only (read_count = 0):
+  if !outbound && !read_included && !msg_id
+    conditions << "read_count = 0"
+  end
+
+  where = conditions.empty? ? "" : " WHERE " + conditions.join(" AND ")
+  limit_clause = (limit > 0) ? " LIMIT #{limit}" : ""
+
+  query = "SELECT * FROM #{table}#{where} ORDER BY id DESC#{limit_clause}"
+  return query, params
+end
+
+## Format a row for output:
+def format_row(row, payload_only)
+  if payload_only
+    begin
+      return JSON.parse(row['payload'])
+    rescue
+      return row['payload']
+    end
+  end
+  ## Convert the Hash to a clean structure:
+  result = {}
+  row.each do |key, value|
+    next if key.is_a?(Integer)  ## Skip numeric index keys from results_as_hash
+    result[key] = value
+  end
+  ## Parse payload JSON for nested output:
+  if result['payload']
+    begin
+      result['payload'] = JSON.parse(result['payload'])
+    rescue
+      ## Leave as string if not valid JSON
+    end
+  end
+  result
+end
+
+begin
+  db = SQLite3::Database.new(db_path)
+  db.results_as_hash = true
+  db.execute("PRAGMA journal_mode = WAL")
+  db.busy_timeout = 5000
+
+  if follow
+    ## Follow mode: continuously poll for new messages
+    last_id = since_id || 0
+
+    ## Get the current max id as starting point if no since_id given:
+    if last_id == 0
+      table = outbound ? "outbound_messages" : "inbound_messages"
+      max_row = db.get_first_row("SELECT MAX(id) as max_id FROM #{table}")
+      last_id = (max_row && max_row['max_id']) ? max_row['max_id'] : 0
+      STDERR.puts "Following new messages (since id #{last_id}). Press Ctrl+C to stop."
+    end
+
+    begin
+      loop do
+        query, params = build_query(outbound, msg_id, state, from_addr, last_id, 0, read_included)
+        ## Override ORDER to ASC for follow mode:
+        query = query.sub("ORDER BY id DESC", "ORDER BY id ASC")
+        rows = db.execute(query, params)
+
+        rows.each do |row|
+          formatted = format_row(row, payload_only)
+          if compact
+            puts JSON.generate(formatted)
+          else
+            puts JSON.pretty_generate(formatted)
+          end
+          STDOUT.flush
+          last_id = row['id'] if row['id'] > last_id
+
+          ## Mark as read (increment read_count) for inbound messages:
+          if !outbound && !no_mark
+            db.execute(
+              "UPDATE inbound_messages SET read_count = read_count + 1, updated_at = strftime('%Y-%m-%dT%H:%M:%f', 'now') WHERE id = ?",
+              [row['id']]
+            )
+          end
+        end
+
+        sleep interval
+      end
+    rescue Interrupt
+      STDERR.puts "\nStopped."
+    end
+
+  else
+    ## One-shot query:
+    query, params = build_query(outbound, msg_id, state, from_addr, since_id, limit, read_included)
+    rows = db.execute(query, params)
+
+    results = rows.map { |row| format_row(row, payload_only) }
+
+    ## Mark as read (increment read_count) for inbound messages:
+    if !outbound && !no_mark
+      rows.each do |row|
+        db.execute(
+          "UPDATE inbound_messages SET read_count = read_count + 1, updated_at = strftime('%Y-%m-%dT%H:%M:%f', 'now') WHERE id = ?",
+          [row['id']]
+        )
+      end
+    end
+
+    if msg_id && results.size == 1
+      ## Single lookup: output the object directly:
+      if compact
+        puts JSON.generate(results.first)
+      else
+        puts JSON.pretty_generate(results.first)
+      end
+    else
+      if compact
+        results.each { |r| puts JSON.generate(r) }
+      else
+        puts JSON.pretty_generate(results)
+      end
+    end
+  end
+
+  db.close
+
+rescue SQLite3::BusyException => e
+  STDERR.puts "ERROR: Database is busy: #{e.message}"
+  exit 1
+rescue SQLite3::Exception => e
+  STDERR.puts "ERROR: Database error: #{e.class}: #{e.message}"
+  exit 1
+end