tier2 1.0.0__py3-none-any.whl

tier2/__init__.py

@@ -0,0 +1,3 @@
+from .core import *
+
+__version__ = "1.0.0"

tier2/core.py

@@ -0,0 +1,253 @@
+"""
+## core.py
+Utility functions for:
+  1. Generating random digit-only IDs stored in JWT tokens
+  2. Verifying those IDs
+  3. Sending messages via Telegram, Discord, WhatsApp
+Dependencies:
+  pip install pyjwt requests
+Environment variables required:
+  TELEGRAM_BOT_TOKEN: from @BotFather (e.g. "123456:ABC-DEF...")
+  DISCORD_BOT_TOKEN: from Discord Developer Portal (e.g. "MTA...")
+  WHATSAPP_API_TOKEN: from Meta Cloud API (e.g. "EAAx...")
+  WHATSAPP_PHONE_ID: Meta phone number ID for your WhatsApp sender
+  JWT_SECRET: any strong random string for signing JWT tokens
+"""
+
+import os
+import re
+import random
+import string
+import logging
+from datetime import datetime, timezone
+from typing import Dict, Optional
+
+import jwt
+import requests
+
+logging.basicConfig(level=logging.INFO, format="%(levelname)s | %(message)s")
+log = logging.getLogger(__name__)
+
+JWT_SECRET = os.environ.get("JWT_SECRET", "change-me-to-a-strong-secret")
+TELEGRAM_BOT_TOKEN = os.environ.get("TELEGRAM_BOT_TOKEN", "")
+DISCORD_BOT_TOKEN = os.environ.get("DISCORD_BOT_TOKEN", "")
+WHATSAPP_API_TOKEN = os.environ.get("WHATSAPP_API_TOKEN", "")
+WHATSAPP_PHONE_ID = os.environ.get("WHATSAPP_PHONE_ID", "")
+
+_token_store: Dict[str, str] = {}
+
+def create_random_id(
+  user_name: str,
+  id_length: int = 6,
+  id_timeout: int = 60,
+) -> str:
+  """
+  Generate a random digit-only ID of *id_length* characters, embed it
+  with *user_name* in a JWT that expires after *id_timeout* seconds,
+  store the token in memory, and return the plain ID string.
+  Parameters:
+  user_name : Unique identifier for the user (e.g. email, username).
+  id_length : Number of digits in the ID (default 6).
+  id_timeout : Token lifetime in seconds (default 60).
+  Returns:
+  str: the plain digit ID, e.g. "482931"
+  """
+  if id_length < 1:
+    raise ValueError("id_length must be at least 1")
+  if id_timeout < 1:
+    raise ValueError("id_timeout must be at least 1 second")
+  # Generate a random digit-only string
+  random_id = "".join(random.choices(string.digits, k=id_length))
+  # Build JWT payload
+  now = datetime.now(tz=timezone.utc)
+  payload = {
+    "sub": user_name, # subject
+    "id": random_id, # the OTP-style ID
+    "iat": now, # issued at
+    "exp": now.timestamp() + id_timeout, # expiry (Unix timestamp)
+  }
+  token = jwt.encode(payload, JWT_SECRET, algorithm="HS256")
+  # Store token keyed by user_name (overwrites any previous token)
+  _token_store[user_name] = token
+  log.info("Created ID for '%s' (expires in %ss): %s", user_name, id_timeout, random_id)
+  return random_id
+
+def verify_given_id(user_name: str, id_string: str) -> bool:
+  """
+  Verify that *id_string* matches the active, non-expired token stored for *user_name*.
+  Parameters:
+  user_name : The user whose token to look up.
+  id_string : The digit ID to verify.
+  Returns:
+  True: token found, not expired, and ID matches.
+  False: token missing, expired, or ID mismatch.
+  """
+  token = _token_store.get(user_name)
+  if not token:
+    log.warning("verify_given_id: no token found for user '%s'", user_name)
+    return False
+  try:
+    payload = jwt.decode(
+      token,
+      JWT_SECRET,
+      algorithms=["HS256"],
+      options={"verify_exp": True},
+    )
+  except jwt.ExpiredSignatureError:
+    log.warning("verify_given_id: token expired for user '%s'", user_name)
+    _token_store.pop(user_name, None) # clean up
+    return False
+  except jwt.InvalidTokenError as exc:
+    log.warning("verify_given_id: invalid token for '%s': %s", user_name, exc)
+    return False
+  # Compare IDs (constant-time-ish via == on short strings)
+  if payload.get("id") != id_string:
+    log.warning("verify_given_id: ID mismatch for user '%s'", user_name)
+    return False
+  # Optionally consume token (one-time use): comment out to allow re-use
+  _token_store.pop(user_name, None)
+  log.info("verify_given_id: ID verified successfully for '%s'", user_name)
+  return True
+
+def text_to_telegram(message: str, recipient: str) -> bool:
+  """
+  Send *message* to a Telegram user/chat.
+  Parameters:
+  message : Text to send.
+  recipient : Telegram chat_id (numeric string or @username).
+              Get a user's chat_id by messaging @userinfobot on Telegram.
+  Environment:
+  TELEGRAM_BOT_TOKEN: Bot token from @BotFather.
+  Returns:
+  True: on success
+  False: on failure
+  """
+  if not TELEGRAM_BOT_TOKEN:
+    log.error("text_to_telegram: TELEGRAM_BOT_TOKEN is not set")
+    return False
+  url = f"https://api.telegram.org/bot{TELEGRAM_BOT_TOKEN}/sendMessage"
+  payload = {
+    "chat_id": recipient,
+    "text": message,
+    "parse_mode": "HTML",
+  }
+  try:
+    resp = requests.post(url, json=payload, timeout=10)
+    data = resp.json()
+    if resp.ok and data.get("ok"):
+      log.info("text_to_telegram: message sent to %s", recipient)
+      return True
+    else:
+      log.error("text_to_telegram: API error: %s", data.get("description", resp.text))
+      return False
+  except requests.RequestException as exc:
+    log.error("text_to_telegram: request failed: %s", exc)
+    return False
+
+def text_to_discord(message: str, recipient: str) -> bool:
+  """
+  Send *message* to a Discord user via DM.
+  Parameters:
+  message : Text to send.
+  recipient : Discord user ID (numeric string, e.g. "123456789012345678").
+              Enable Developer Mode in Discord → right-click user → Copy ID.
+  Environment:
+  DISCORD_BOT_TOKEN: Bot token from Discord Developer Portal.
+                     The bot must share a server with the recipient, or the recipient must have DMs open.
+  Returns:
+  True: on success
+  False: on failure
+  """
+  if not DISCORD_BOT_TOKEN:
+    log.error("text_to_discord: DISCORD_BOT_TOKEN is not set")
+    return False
+  headers = {
+    "Authorization": f"Bot {DISCORD_BOT_TOKEN}",
+    "Content-Type": "application/json",
+  }
+  base = "https://discord.com/api/v10"
+  try:
+    # Step 1: open / retrieve DM channel
+    dm_resp = requests.post(
+      f"{base}/users/@me/channels",
+      headers=headers,
+      json={"recipient_id": recipient},
+      timeout=10,
+    )
+    if not dm_resp.ok:
+      log.error("text_to_discord: failed to open DM — %s", dm_resp.text)
+      return False
+    channel_id = dm_resp.json()["id"]
+    # Step 2: send message to DM channel
+    msg_resp = requests.post(
+      f"{base}/channels/{channel_id}/messages",
+      headers=headers,
+      json={"content": message},
+      timeout=10,
+    )
+    if msg_resp.ok:
+      log.info("text_to_discord: message sent to user %s", recipient)
+      return True
+    else:
+      log.error("text_to_discord: send failed — %s", msg_resp.text)
+      return False
+  except requests.RequestException as exc:
+    log.error("text_to_discord: request failed — %s", exc)
+    return False
+
+def text_to_whatsapp(message: str, recipient: str) -> bool:
+  """
+  Send *message* to a WhatsApp number via Meta Cloud API.
+  Parameters:
+  message : Text to send.
+  recipient : Recipient's phone number in E.164 format, e.g. "84901234567" (country code + number, no + or spaces).
+  Environment:
+  WHATSAPP_API_TOKEN: Permanent or temporary token from Meta for Developers.
+  WHATSAPP_PHONE_ID: Phone Number ID of your WhatsApp sender (found in Meta → WhatsApp → API Setup).
+  Returns:
+  True: on success
+  False: on failure
+  Notes:
+  - The recipient must have previously messaged your WhatsApp number within
+    24 hours (session window), OR you must use an approved Message Template.
+  - For OTP use-cases, use a pre-approved "otp" template instead of free text.
+  """
+  if not WHATSAPP_API_TOKEN:
+    log.error("text_to_whatsapp: WHATSAPP_API_TOKEN is not set")
+    return False
+  if not WHATSAPP_PHONE_ID:
+    log.error("text_to_whatsapp: WHATSAPP_PHONE_ID is not set")
+    return False
+  url = f"https://graph.facebook.com/v19.0/{WHATSAPP_PHONE_ID}/messages"
+  headers = {
+    "Authorization": f"Bearer {WHATSAPP_API_TOKEN}",
+    "Content-Type": "application/json",
+  }
+  payload = {
+    "messaging_product": "whatsapp",
+    "to": recipient,
+    "type": "text",
+    "text": {"body": message},
+  }
+  try:
+    resp = requests.post(url, headers=headers, json=payload, timeout=10)
+    data = resp.json()
+    if resp.ok and "messages" in data:
+      log.info("text_to_whatsapp: message sent to %s", recipient)
+      return True
+    else:
+      error = data.get("error", {}).get("message", resp.text)
+      log.error("text_to_whatsapp: API error — %s", error)
+      return False
+  except requests.RequestException as exc:
+    log.error("text_to_whatsapp: request failed — %s", exc)
+    return False
+
+def get_active_token(user_name: str) -> Optional[str]:
+  ## Return the raw JWT for *user_name*, or None if not found
+  return _token_store.get(user_name)
+
+def invalidate_token(user_name: str) -> None:
+  ## Manually invalidate/delete the token for *user_name*
+  _token_store.pop(user_name, None)
+  log.info("Token invalidated for '%s'", user_name)

tier2-1.0.0.dist-info/METADATA

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: tier2
+Version: 1.0.0
+Summary: Literp Tier Two Credential Lib
+Home-page: https://github.com/asinerum/tier2
+Author: Asinerum Conlang Project
+Author-email: asinerum.com@gmail.com
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyjwt>=2.10.1
+Requires-Dist: requests>=2.32.5
+Dynamic: license-file
+
+# LITERP TIER TWO CREDENTIAL LIBRARY
+
+Detailed tips, tricks, and examples, can be found at project's repository
+https://github.com/asinerum/tier2
+
+(C) 2026 Asinerum Conlang Project

tier2-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+tier2/__init__.py,sha256=3lUTe5iXnYlQ4pT510T9Uu3NFzq5rTyiVw-GAC1x13E,46
+tier2/core.py,sha256=Qt1CsZqGlRMJmYIHEDg-g2PzLgK2T6jmlpes_Bq9WDA,8840
+tier2-1.0.0.dist-info/licenses/LICENSE,sha256=4npUbkrpgB6lqMiYYeUxZAP4SOkjVSwK8-7jW60mxvw,1081
+tier2-1.0.0.dist-info/METADATA,sha256=pPk1YX3dnYXKJ81z5l6FqTk83cLHw_EywpFrZkQUP18,737
+tier2-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+tier2-1.0.0.dist-info/top_level.txt,sha256=G8NGyFbIyrhyREYmzDHIs1E1jgDcpp_IGwraRh-6vqg,6
+tier2-1.0.0.dist-info/RECORD,,

tier2-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tier2-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Asinerum Conlang Project
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tier2-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tier2