# Configuration Contract: mautrix-slack Bridge

# This contract defines the expected NixOS configuration structure for the
# Slack↔Matrix bridge deployment. It serves as a specification for how the
# bridge should be configured in hosts/ops-jrz1.nix.

# =============================================================================
# NixOS Module Configuration (hosts/ops-jrz1.nix)
# =============================================================================

services:
  mautrix-slack:
    enable: true  # Enable the bridge service

    # Matrix Homeserver Configuration
    # --------------------------------
    # Connects the bridge to the local Matrix homeserver (conduwuit)
    matrix:
      homeserverUrl: "http://127.0.0.1:8008"
      # Type: URL
      # Description: Matrix homeserver client-server API endpoint
      # Default: "http://127.0.0.1:8008"
      # Notes: Use localhost since bridge and homeserver are on same host

      serverName: "clarun.xyz"
      # Type: domain
      # Description: Matrix server domain for user IDs and room aliases
      # Default: null (required)
      # Notes: Must match homeserver configuration

    # Database Configuration
    # ----------------------
    # PostgreSQL connection for bridge state storage
    database:
      type: "postgres"
      # Type: enum ["postgres", "sqlite"]
      # Description: Database backend type
      # Default: "postgres"
      # Notes: PostgreSQL recommended for production

      uri: "postgresql:///mautrix_slack?host=/run/postgresql"
      # Type: URI
      # Description: Database connection string
      # Default: "postgresql:///mautrix_slack?host=/run/postgresql"
      # Format: postgresql://[user[:password]@][host][:port]/dbname[?params]
      # Notes:
      #   - Empty user/password uses peer authentication
      #   - Unix socket via /run/postgresql (no network exposure)
      #   - Database created by dev-services.nix

      maxOpenConnections: 32
      # Type: integer
      # Description: Maximum concurrent database connections
      # Default: 32

      maxIdleConnections: 4
      # Type: integer
      # Description: Maximum idle connections in pool
      # Default: 4

    # Appservice Configuration
    # ------------------------
    # Matrix application service protocol settings
    appservice:
      hostname: "127.0.0.1"
      # Type: string
      # Description: Bind address for appservice HTTP server
      # Default: "127.0.0.1"
      # Notes: Localhost-only (homeserver is local)

      port: 29319
      # Type: integer (1024-65535)
      # Description: Port for appservice HTTP server
      # Default: 29319
      # Notes: Must be unique per bridge instance

      id: "slack"
      # Type: string
      # Description: Appservice identifier in registration file
      # Default: "slack"
      # Notes: Must match registration.yaml

      senderLocalpart: "slackbot"
      # Type: string
      # Description: Localpart for bridge bot user
      # Default: "slackbot"
      # Results in: @slackbot:clarun.xyz

      userPrefix: "slack_"
      # Type: string
      # Description: Prefix for ghost user IDs
      # Default: "slack_"
      # Results in: @slack_U123ABC:clarun.xyz

      botDisplayName: "Slack Bridge Bot"
      # Type: string
      # Description: Display name for bridge bot
      # Default: "Slack Bridge Bot"
      # Optional: Can be customized for branding

      botAvatar: ""
      # Type: mxc:// URL or empty string
      # Description: Avatar for bridge bot
      # Default: ""
      # Optional: Set after deployment via Matrix client

    # Bridge Behavior Configuration
    # ------------------------------
    # Controls bridge-specific functionality
    bridge:
      commandPrefix: "!slack"
      # Type: string
      # Description: Prefix for bridge bot commands
      # Default: "!slack"
      # Usage: "!slack help", "!slack status"

      permissions:
        "clarun.xyz": "user"
        # Type: map[domain]permission_level
        # Description: Access control by homeserver domain
        # Levels: "relay", "user", "admin"
        # Notes:
        #   - "relay": Can use relay mode (bot posts on behalf)
        #   - "user": Can login and bridge their own chats
        #   - "admin": Can manage bridge, access all portals
        # Example for multiple domains:
        #   "clarun.xyz": "user"
        #   "example.com": "relay"
        #   "admin.clarun.xyz": "admin"

    # Encryption Configuration
    # ------------------------
    # End-to-end encryption support in Matrix rooms
    encryption:
      enable: true
      # Type: boolean
      # Description: Allow bridge to participate in encrypted rooms
      # Default: true
      # Notes: Requires crypto dependencies (already in package)

      default: false
      # Type: boolean
      # Description: Enable encryption by default for new portals
      # Default: false
      # Notes: Can cause issues with search/backfill

      require: false
      # Type: boolean
      # Description: Require encryption for all portals
      # Default: false
      # Notes: Set true for high-security deployments

    # Logging Configuration
    # ---------------------
    # Service logging settings
    logging:
      level: "info"
      # Type: enum ["debug", "info", "warn", "error"]
      # Description: Minimum log level to output
      # Default: "info"
      # Notes:
      #   - Use "debug" for initial deployment troubleshooting
      #   - Use "info" for production
      #   - Logs viewable via: journalctl -u mautrix-slack -f

# =============================================================================
# Generated config.yaml Structure (for reference)
# =============================================================================
# The following represents the actual config.yaml generated by the NixOS
# module. This is NOT directly edited; it's created from the NixOS options above.

# homeserver:
#   address: "http://127.0.0.1:8008"
#   domain: "clarun.xyz"
#   software: "standard"  # Auto-detected
#   status_endpoint: null
#   message_send_checkpoint_endpoint: null
#   async_media: false
#   websocket: false
#   ping_interval_seconds: 0

# appservice:
#   address: "http://127.0.0.1:29319"
#   hostname: "127.0.0.1"
#   port: 29319
#   id: "slack"
#   bot:
#     username: "slackbot"
#     displayname: "Slack Bridge Bot"
#     avatar: ""
#   ephemeral_events: true
#   async_transactions: false
#   as_token: "generated-from-registration"
#   hs_token: "generated-from-registration"

# database:
#   type: "postgres"
#   uri: "postgresql:///mautrix_slack?host=/run/postgresql"
#   max_open_conns: 32
#   max_idle_conns: 4
#   max_conn_idle_time: null
#   max_conn_lifetime: null

# bridge:
#   username_template: "slack_{{.}}"
#   displayname_template: "{{.RealName}} (S)"
#   bot_messages_as_notices: true
#   bridge_matrix_leave: true
#   sync_with_custom_puppets: true
#   sync_direct_chat_list: false
#   double_puppet_server_map: {}
#   double_puppet_allow_discovery: false
#   login_shared_secret_map: {}
#   command_prefix: "!slack"
#   management_room_text:
#     welcome: "Hello, I'm a Slack bridge bot."
#     connected: "Successfully logged into Slack."
#     not_connected: "This bridge is not logged in. Use `login` to log in."
#   encryption:
#     allow: true
#     default: false
#     require: false
#     appservice: false
#     allow_key_sharing: false
#   permissions:
#     "clarun.xyz": "user"
#   relay:
#     enabled: false
#     admin_only: true
#   message_handling_timeout:
#     error_after: 0s
#     deadline: 120s

# slack:
#   # Credentials NOT in config file
#   # Provided via `login app` command interactively
#   # Stored in database after authentication
#   conversation_count: 10  # Number of recent chats to sync on login

# logging:
#   min_level: "info"
#   writers:
#     - type: "stdout"
#       format: "pretty-colored"
#       time_format: " "
#   print_level: "debug"
#   file_name_format: ""
#   file_date_format: "2006-01-02"
#   file_mode: 384
#   timestamp_format: "Jan _2, 2006 15:04:05"
#   print_json: false

# =============================================================================
# Configuration Validation Checklist
# =============================================================================

# Before deployment, verify:
# [ ] services.mautrix-slack.enable = true
# [ ] matrix.serverName matches homeserver configuration
# [ ] database.uri points to existing PostgreSQL database
# [ ] appservice.port is unique (not used by other services)
# [ ] bridge.permissions includes homeserver domain
# [ ] Secrets NOT in config (tokens provided via interactive login)
# [ ] logging.level set appropriately (debug for initial deploy, info for production)

# After deployment, verify:
# [ ] Service started: systemctl status mautrix-slack
# [ ] Logs show no errors: journalctl -u mautrix-slack -n 50
# [ ] Registration file created: ls -l /var/lib/matrix-appservices/mautrix_slack_registration.yaml
# [ ] Database has tables: sudo -u mautrix_slack psql mautrix_slack -c '\dt'
# [ ] Bot user registered in Matrix: DM with @slackbot:clarun.xyz works

# =============================================================================
# Related Files
# =============================================================================

# NixOS Module: /home/dan/proj/ops-jrz1/modules/mautrix-slack.nix
# Host Config: /home/dan/proj/ops-jrz1/hosts/ops-jrz1.nix
# Service Config: /home/dan/proj/ops-jrz1/modules/dev-services.nix (database provisioning)
# Secrets: /home/dan/proj/ops-jrz1/secrets/secrets.yaml (sops-encrypted)
# Registration: /var/lib/matrix-appservices/mautrix_slack_registration.yaml (runtime)
# Generated Config: /var/lib/mautrix_slack/config/config.yaml (runtime)

# =============================================================================
# Version Information
# =============================================================================

# Contract Version: 1.0
# Created: 2025-10-22
# mautrix-slack Version: Latest from nixpkgs-unstable
# NixOS Version: 24.05+
# Last Updated: 2025-10-22