@helyx/module-account-gate 1.0.1

package/migrations/0001_account_gate_foundation.sql

@@ -0,0 +1,303 @@
+CREATE TABLE IF NOT EXISTS account_gate_gate_panels (
+  panel_id text PRIMARY KEY,
+  guild_id text NOT NULL UNIQUE,
+  channel_id text NOT NULL,
+  message_id text NOT NULL,
+  revision integer NOT NULL CHECK (revision > 0),
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  CHECK (updated_at >= created_at)
+);
+
+CREATE TABLE IF NOT EXISTS account_gate_public_channels (
+  guild_id text NOT NULL,
+  channel_id text NOT NULL,
+  created_at timestamptz NOT NULL,
+  PRIMARY KEY (guild_id, channel_id)
+);
+
+CREATE TABLE IF NOT EXISTS account_gate_questions (
+  question_id text PRIMARY KEY,
+  guild_id text NOT NULL,
+  question_text text NOT NULL CHECK (char_length(question_text) BETWEEN 1 AND 200),
+  answers_json text NOT NULL,
+  correct_option_index integer NOT NULL CHECK (correct_option_index BETWEEN 0 AND 4),
+  enabled boolean NOT NULL,
+  sort_order integer NOT NULL CHECK (sort_order BETWEEN 0 AND 1000),
+  revision integer NOT NULL CHECK (revision > 0),
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  UNIQUE (guild_id, question_id),
+  CHECK (updated_at >= created_at)
+);
+
+CREATE INDEX IF NOT EXISTS account_gate_questions_guild_order_idx
+  ON account_gate_questions (guild_id, sort_order, question_id);
+CREATE TABLE IF NOT EXISTS account_gate_question_creators (
+  attribution_id text PRIMARY KEY,
+  question_id text NOT NULL UNIQUE,
+  guild_id text NOT NULL,
+  creator_user_id text NOT NULL,
+  created_at timestamptz NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS account_gate_question_creator_privacy_idx
+  ON account_gate_question_creators (
+    creator_user_id,
+    created_at,
+    attribution_id
+  );
+
+CREATE TABLE IF NOT EXISTS account_gate_password_secrets (
+  guild_id text PRIMARY KEY,
+  encoded_hash text NOT NULL,
+  ignore_case boolean NOT NULL,
+  trim_whitespace boolean NOT NULL,
+  revision integer NOT NULL CHECK (revision > 0),
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  CHECK (updated_at >= created_at)
+);
+
+CREATE TABLE IF NOT EXISTS account_gate_attempts (
+  attempt_id text PRIMARY KEY,
+  guild_id text NOT NULL,
+  member_user_id text NOT NULL,
+  session_id text NOT NULL,
+  challenge_type text NOT NULL CHECK (
+    challenge_type IN (
+      'quick_sum', 'button_sequence', 'number_order', 'symbol_match',
+      'modal_recall', 'server_question', 'password_entry', 'emoji_entry'
+    )
+  ),
+  outcome text NOT NULL CHECK (outcome IN ('passed', 'failed', 'expired')),
+  reason_code text NOT NULL,
+  duration_ms bigint NOT NULL CHECK (duration_ms >= 0),
+  retention_until timestamptz NOT NULL,
+  created_at timestamptz NOT NULL,
+  UNIQUE (guild_id, attempt_id),
+  UNIQUE (guild_id, session_id, challenge_type)
+);
+
+CREATE INDEX IF NOT EXISTS account_gate_attempts_member_privacy_idx
+  ON account_gate_attempts (member_user_id, created_at, attempt_id);
+CREATE INDEX IF NOT EXISTS account_gate_attempts_retention_idx
+  ON account_gate_attempts (retention_until, attempt_id);
+
+CREATE TABLE IF NOT EXISTS account_gate_member_summaries (
+  summary_id text NOT NULL UNIQUE,
+  guild_id text NOT NULL,
+  member_user_id text NOT NULL,
+  previous_success_at timestamptz,
+  failure_count integer NOT NULL CHECK (failure_count >= 0),
+  lockout_until timestamptz,
+  rejoin_count integer NOT NULL CHECK (rejoin_count >= 0),
+  join_generation integer NOT NULL CHECK (join_generation > 0),
+  account_created_at timestamptz NOT NULL,
+  joined_at timestamptz NOT NULL,
+  deadline_at timestamptz NOT NULL,
+  pending_reason text NOT NULL CHECK (
+    pending_reason IN ('none', 'account_too_new')
+  ),
+  last_failure_terminal_id text,
+  left_at timestamptz,
+  last_decision text NOT NULL CHECK (
+    last_decision IN (
+      'pending', 'finalizing', 'passed', 'failed', 'review', 'kick_pending',
+      'kicked', 'dismissed'
+    )
+  ),
+  revision integer NOT NULL CHECK (revision > 0),
+  retention_until timestamptz NOT NULL,
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  PRIMARY KEY (guild_id, member_user_id),
+  CHECK (updated_at >= created_at)
+);
+
+CREATE INDEX IF NOT EXISTS account_gate_member_summary_privacy_idx
+  ON account_gate_member_summaries (member_user_id, created_at, guild_id);
+CREATE INDEX IF NOT EXISTS account_gate_member_summary_retention_idx
+  ON account_gate_member_summaries (retention_until, guild_id, member_user_id);
+
+CREATE TABLE IF NOT EXISTS account_gate_reviews (
+  review_id text PRIMARY KEY,
+  pending_key text NOT NULL UNIQUE,
+  guild_id text NOT NULL,
+  member_user_id text NOT NULL,
+  join_generation integer NOT NULL CHECK (join_generation > 0),
+  status text NOT NULL CHECK (
+    status IN (
+      'pending', 'claim_approve', 'claim_retry', 'claim_kick',
+      'claim_dismiss', 'approved', 'retry', 'kicked', 'dismissed'
+    )
+  ),
+  delivery_status text NOT NULL CHECK (
+    delivery_status IN ('pending', 'sent', 'failed')
+  ),
+  claim_action text,
+  claim_expires_at timestamptz,
+  reason_code text NOT NULL,
+  challenge_types_json text NOT NULL,
+  failed_attempts integer NOT NULL CHECK (failed_attempts >= 0),
+  expired_attempts integer NOT NULL CHECK (expired_attempts >= 0),
+  review_channel_id text,
+  review_message_id text,
+  decided_by_user_id text,
+  decided_at timestamptz,
+  revision integer NOT NULL CHECK (revision > 0),
+  retention_until timestamptz NOT NULL,
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  UNIQUE (guild_id, review_id),
+  UNIQUE (guild_id, review_message_id),
+  CHECK (updated_at >= created_at)
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS account_gate_one_pending_review_idx
+  ON account_gate_reviews (guild_id, member_user_id)
+  WHERE status = 'pending';
+
+CREATE TABLE IF NOT EXISTS account_gate_terminal_finalizations (
+  finalization_id text PRIMARY KEY,
+  guild_id text NOT NULL,
+  member_user_id text NOT NULL,
+  session_id text NOT NULL,
+  join_generation integer NOT NULL CHECK (join_generation > 0),
+  outcome text NOT NULL CHECK (outcome IN ('passed', 'failed')),
+  challenge_type text NOT NULL,
+  challenge_types_json text NOT NULL,
+  work_created_at timestamptz NOT NULL,
+  status text NOT NULL CHECK (
+    status IN ('pending', 'failure_recorded', 'completed', 'cancelled')
+  ),
+  revision integer NOT NULL CHECK (revision > 0),
+  retention_until timestamptz NOT NULL,
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  UNIQUE (guild_id, session_id),
+  CHECK (updated_at >= created_at)
+);
+
+CREATE INDEX IF NOT EXISTS account_gate_terminal_finalization_status_idx
+  ON account_gate_terminal_finalizations (status, created_at, finalization_id);
+
+CREATE INDEX IF NOT EXISTS account_gate_reviews_member_privacy_idx
+  ON account_gate_reviews (member_user_id, created_at, review_id);
+CREATE INDEX IF NOT EXISTS account_gate_reviews_actor_privacy_idx
+  ON account_gate_reviews (decided_by_user_id, created_at, review_id)
+  WHERE decided_by_user_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS account_gate_reviews_retention_idx
+  ON account_gate_reviews (retention_until, review_id);
+
+CREATE TABLE IF NOT EXISTS account_gate_role_transitions (
+  transition_id text PRIMARY KEY,
+  guild_id text NOT NULL,
+  member_user_id text NOT NULL,
+  verified_role_id text NOT NULL,
+  pending_remove_role_ids_json text NOT NULL,
+  status text NOT NULL CHECK (status IN ('pending', 'partial', 'completed', 'review')),
+  revision integer NOT NULL CHECK (revision > 0),
+  next_retry_at timestamptz,
+  completed_at timestamptz,
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  UNIQUE (guild_id, transition_id),
+  UNIQUE (guild_id, member_user_id),
+  CHECK (updated_at >= created_at)
+);
+
+CREATE INDEX IF NOT EXISTS account_gate_role_transition_privacy_idx
+  ON account_gate_role_transitions (member_user_id, created_at, transition_id);
+CREATE INDEX IF NOT EXISTS account_gate_role_transition_retry_idx
+  ON account_gate_role_transitions (status, next_retry_at, transition_id)
+  WHERE status IN ('pending', 'partial');
+
+CREATE TABLE IF NOT EXISTS account_gate_strict_modes (
+  guild_id text PRIMARY KEY,
+  status text NOT NULL CHECK (status IN ('active', 'expired', 'disabled')),
+  ends_at timestamptz NOT NULL,
+  generation integer NOT NULL CHECK (generation > 0),
+  activated_by_user_id text,
+  revision integer NOT NULL CHECK (revision > 0),
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  CHECK (updated_at >= created_at)
+);
+
+CREATE INDEX IF NOT EXISTS account_gate_strict_mode_expiry_idx
+  ON account_gate_strict_modes (status, ends_at, guild_id)
+  WHERE status = 'active';
+CREATE INDEX IF NOT EXISTS account_gate_strict_mode_actor_privacy_idx
+  ON account_gate_strict_modes (activated_by_user_id, created_at, guild_id)
+  WHERE activated_by_user_id IS NOT NULL;
+
+CREATE TABLE IF NOT EXISTS account_gate_privacy_suppressions (
+  suppression_id text NOT NULL UNIQUE,
+  guild_id text NOT NULL,
+  member_user_id text NOT NULL,
+  suppressed_at timestamptz NOT NULL,
+  created_at timestamptz NOT NULL,
+  PRIMARY KEY (guild_id, member_user_id)
+);
+
+CREATE INDEX IF NOT EXISTS account_gate_privacy_suppression_subject_idx
+  ON account_gate_privacy_suppressions (member_user_id, created_at, guild_id);
+
+CREATE OR REPLACE FUNCTION account_gate_install_privacy_suppression()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+BEGIN
+  INSERT INTO account_gate_privacy_suppressions (
+    suppression_id,
+    guild_id,
+    member_user_id,
+    suppressed_at,
+    created_at
+  )
+  VALUES (
+    OLD.guild_id || ':' || OLD.member_user_id,
+    OLD.guild_id,
+    OLD.member_user_id,
+    clock_timestamp(),
+    clock_timestamp()
+  )
+  ON CONFLICT (guild_id, member_user_id)
+  DO UPDATE SET suppressed_at = GREATEST(
+    account_gate_privacy_suppressions.suppressed_at,
+    EXCLUDED.suppressed_at
+  );
+  RETURN OLD;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS account_gate_attempt_privacy_suppressed
+  ON account_gate_attempts;
+CREATE TRIGGER account_gate_attempt_privacy_suppressed
+AFTER DELETE ON account_gate_attempts
+FOR EACH ROW EXECUTE FUNCTION account_gate_install_privacy_suppression();
+
+DROP TRIGGER IF EXISTS account_gate_summary_privacy_suppressed
+  ON account_gate_member_summaries;
+CREATE TRIGGER account_gate_summary_privacy_suppressed
+AFTER DELETE ON account_gate_member_summaries
+FOR EACH ROW EXECUTE FUNCTION account_gate_install_privacy_suppression();
+
+DROP TRIGGER IF EXISTS account_gate_review_privacy_suppressed
+  ON account_gate_reviews;
+CREATE TRIGGER account_gate_review_privacy_suppressed
+AFTER DELETE ON account_gate_reviews
+FOR EACH ROW EXECUTE FUNCTION account_gate_install_privacy_suppression();
+
+DROP TRIGGER IF EXISTS account_gate_transition_privacy_suppressed
+  ON account_gate_role_transitions;
+CREATE TRIGGER account_gate_transition_privacy_suppressed
+AFTER DELETE ON account_gate_role_transitions
+FOR EACH ROW EXECUTE FUNCTION account_gate_install_privacy_suppression();
+
+DROP TRIGGER IF EXISTS account_gate_terminal_privacy_suppressed
+  ON account_gate_terminal_finalizations;
+CREATE TRIGGER account_gate_terminal_privacy_suppressed
+AFTER DELETE ON account_gate_terminal_finalizations
+FOR EACH ROW EXECUTE FUNCTION account_gate_install_privacy_suppression();

package/migrations/0002_account_gate_panel_message.sql

@@ -0,0 +1,27 @@
+ALTER TABLE account_gate_gate_panels
+  ADD COLUMN IF NOT EXISTS message_body text;
+
+UPDATE account_gate_gate_panels
+SET message_body =
+  'Complete a short human-interaction check to access the server. Press the button below when you are ready.'
+WHERE message_body IS NULL;
+
+ALTER TABLE account_gate_gate_panels
+  ALTER COLUMN message_body SET DEFAULT
+    'Complete a short human-interaction check to access the server. Press the button below when you are ready.',
+  ALTER COLUMN message_body SET NOT NULL;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+    FROM pg_constraint
+    WHERE conname = 'account_gate_gate_panels_message_body_length'
+      AND conrelid = 'account_gate_gate_panels'::regclass
+  ) THEN
+    ALTER TABLE account_gate_gate_panels
+      ADD CONSTRAINT account_gate_gate_panels_message_body_length
+      CHECK (char_length(message_body) BETWEEN 1 AND 1000);
+  END IF;
+END
+$$;

package/migrations/0003_account_gate_revoked_member_status.sql

@@ -0,0 +1,17 @@
+DO $$
+BEGIN
+  IF to_regclass('account_gate_member_summaries') IS NOT NULL THEN
+    ALTER TABLE account_gate_member_summaries
+      DROP CONSTRAINT IF EXISTS account_gate_member_summaries_last_decision_check;
+
+    ALTER TABLE account_gate_member_summaries
+      ADD CONSTRAINT account_gate_member_summaries_last_decision_check
+      CHECK (
+        last_decision IN (
+          'pending', 'finalizing', 'passed', 'failed', 'review', 'kick_pending',
+          'kicked', 'dismissed', 'revoked'
+        )
+      );
+  END IF;
+END
+$$;

package/migrations/0004_account_gate_multiple_panels.sql

@@ -0,0 +1,23 @@
+ALTER TABLE account_gate_gate_panels
+  ADD COLUMN IF NOT EXISTS access_type text NOT NULL DEFAULT 'challenges';
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+    FROM pg_constraint
+    WHERE conname = 'account_gate_gate_panels_access_type'
+      AND conrelid = 'account_gate_gate_panels'::regclass
+  ) THEN
+    ALTER TABLE account_gate_gate_panels
+      ADD CONSTRAINT account_gate_gate_panels_access_type
+      CHECK (access_type IN ('challenges', 'password', 'emoji'));
+  END IF;
+END
+$$;
+
+ALTER TABLE account_gate_gate_panels
+  DROP CONSTRAINT IF EXISTS account_gate_gate_panels_guild_id_key;
+
+CREATE INDEX IF NOT EXISTS account_gate_gate_panels_guild_idx
+  ON account_gate_gate_panels (guild_id, created_at, panel_id);

package/migrations/0005_account_gate_panel_passwords.sql

@@ -0,0 +1,45 @@
+ALTER TABLE account_gate_gate_panels
+  ADD COLUMN IF NOT EXISTS password_hash text,
+  ADD COLUMN IF NOT EXISTS password_ignore_case boolean NOT NULL DEFAULT true,
+  ADD COLUMN IF NOT EXISTS password_trim_whitespace boolean NOT NULL DEFAULT true;
+
+UPDATE account_gate_gate_panels AS panel
+SET
+  password_hash = secret.encoded_hash,
+  password_ignore_case = secret.ignore_case,
+  password_trim_whitespace = secret.trim_whitespace
+FROM account_gate_password_secrets AS secret
+WHERE panel.guild_id = secret.guild_id
+  AND panel.access_type = 'password'
+  AND panel.password_hash IS NULL;
+
+CREATE OR REPLACE FUNCTION account_gate_enforce_panel_limit()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+BEGIN
+  PERFORM pg_advisory_xact_lock(
+    hashtextextended(NEW.guild_id, 4815162342)
+  );
+
+  IF (
+    SELECT count(*)
+    FROM account_gate_gate_panels
+    WHERE guild_id = NEW.guild_id
+  ) >= 10 THEN
+    RAISE EXCEPTION USING
+      ERRCODE = 'check_violation',
+      MESSAGE = 'Account Gate panel limit reached';
+  END IF;
+
+  RETURN NEW;
+END
+$$;
+
+DROP TRIGGER IF EXISTS account_gate_gate_panels_limit
+  ON account_gate_gate_panels;
+
+CREATE TRIGGER account_gate_gate_panels_limit
+BEFORE INSERT ON account_gate_gate_panels
+FOR EACH ROW
+EXECUTE FUNCTION account_gate_enforce_panel_limit();

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@helyx/module-account-gate",
+  "version": "1.0.1",
+  "description": "Require configurable Discord interaction checks before new members gain access.",
+  "keywords": [
+    "helyx",
+    "discord",
+    "account-gate"
+  ],
+  "private": false,
+  "license": "HSAL 1.0",
+  "homepage": "https://helyx.gg/modules/",
+  "bugs": {
+    "url": "https://github.com/ZyC0R3/Helyx/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZyC0R3/Helyx.git",
+    "directory": "modules/account-gate"
+  },
+  "engines": {
+    "node": ">=24 <27",
+    "npm": ">=11"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "!dist/*.tsbuildinfo",
+    "!dist/**/*.map",
+    "migrations",
+    "manifest.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "@helyx/module-manifest": "0.5.0",
+    "@helyx/sdk": "0.4.0"
+  }
+}