thoughtleaders-cli 0.5.0__py3-none-any.whl

tl_cli/_plugin/skills/tl/references/postgres-schema.md

@@ -0,0 +1,269 @@
+# ThoughtLeaders PostgreSQL Schema Reference
+
+## How to query
+
+```bash
+tl db pg "SELECT id, weighted_price FROM thoughtleaders_adlink
+          WHERE publish_status = 2
+          LIMIT 50 OFFSET 0"
+```
+
+`tl schema pg` prints the live table/column listing visible to your user.
+
+Accepted SQL:
+- **SELECT only**, single statement. No DDL/DML/transactions/SET/COPY/MERGE.
+- Functions accepted from an explicit list (aggregates, window, string, JSON, math, date-time, array). Catalog-resolving casts (`::regclass`, `::regprocedure`, …) are not accepted.
+- `LIMIT` and `OFFSET` are optional. Omit them and the server fills in `LIMIT 50 OFFSET 0`. Explicit `LIMIT` must be an integer literal ≤ 500. Explicit `OFFSET` ≥ 10,000 is rejected with HTTP 403 (`OFFSET_TOO_DEEP`); paginate with the response's `next_offset`/breadcrumbs instead of jumping deep.
+- SQL ≤ 50,000 chars; AST depth ≤ 64; node count ≤ 5,000.
+
+## Core Tables
+
+### `thoughtleaders_adlink` (Deals/Sponsorships)
+
+The main deals table. Each row = one sponsorship deal between a brand and a YouTube channel. Also called "AdLink" in code, exposed as **sponsorship** in the CLI.
+
+> 🚨 **Columns that DO NOT exist on `thoughtleaders_adlink` — common hallucinations:**
+> - ❌ `brand_id` — there is NO direct brand FK. Brand is reached via `creator_profile_id → profile → profile_brands → brand`.
+> - ❌ `organization_id` — there is NO direct org FK. Org is reached via `creator_profile_id → profile.organization_id → organization`.
+> - ❌ `channel_id` — channel is reached via `ad_spot_id → adspot.channel_id → channel`.
+> - ❌ `youtube_id` (on channel) — use `external_channel_id`.
+
+#### Key Columns
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | int | Primary key |
+| `created_at` | timestamptz | When the deal was created |
+| `updated_at` | timestamptz | Last modification |
+| `publish_status` | int | Deal status (see constants below) |
+| `price` | numeric | Deal price (USD) |
+| `price_currency` | varchar | Always USD |
+| `weighted_price` | numeric | `price * (status_weight/100)`, pre-calculated on save |
+| `weighted_price_currency` | varchar | Always USD |
+| `cost` | numeric | Cost to TL |
+| `ad_spot_id` | int FK | → `thoughtleaders_adspot.id` |
+| `creator_profile_id` | int FK | → brand/advertiser profile |
+| `owner_advertiser_id` | int FK | → `auth_user.id` (brand-side owner) |
+| `owner_publisher_id` | int FK | → `auth_user.id` (channel-side owner) |
+| `owner_sales_id` | int FK | → `auth_user.id` (sales rep) |
+| `send_date` | timestamptz | Scheduled send/publish date |
+| `publish_date` | timestamptz | Actual publish date |
+| `outreach_date` | timestamptz | When outreach was sent |
+| `purchase_date` | timestamptz | When deal was purchased/sold |
+| `presented_date` | timestamptz | When presented to brand |
+| `rejected_date` | timestamptz | When rejected |
+| `proposal_approved_date` | timestamptz | When proposal was approved |
+| `draft_expected_date` | date | Expected draft delivery |
+| `actual_end_date` | timestamptz | Actual end date |
+| `scheduled_end_date` | timestamptz | Scheduled end date |
+| `rejection_reason` | int | Rejection reason code |
+| `rejection_reason_details` | text | Free-text rejection details |
+| `payment_status` | int | 0=Unpaid, 1=Paid |
+| `performance_grade` | int | Performance rating (see business-glossary) |
+| `article_id` | varchar | Compound `<channel_id>:<youtube_id>` — links to ES `_id` and ES `id` field |
+| `dashboard_campaign_id` | int FK | Campaign grouping |
+| `created_where` | varchar | Where the deal originated |
+| `tx_data` | jsonb | Transaction metadata |
+
+#### `publish_status` Constants
+
+| Value | Constant | Label | Pipeline Weight |
+|-------|----------|-------|----------------|
+| 0 | PREVIEW | Proposed | 10% |
+| 1 | UNAVAILABLE | Unavailable | — |
+| 2 | PENDING | Pending | 70% |
+| 3 | SOLD | Sold | — |
+| 4 | DENY | Rejected by Advertiser | 0% |
+| 5 | REJECT | Rejected by Publisher | 0% |
+| 6 | PROPOSAL_APPROVED | Proposal Approved | 25% |
+| 7 | MATCHED | Matched (default) | 1% |
+| 8 | OUTREACH | Reached Out | 5% |
+| 9 | REJECTED_AGENCY | Rejected by Agency | 0% |
+| -1 | CLIENT_SIDE_AVAILABLE | Client Side Available | — |
+| -2 | CLIENT_SIDE_TAKEN | Client Side Taken | — |
+
+#### Pipeline Stages
+
+- **Active pipeline** = statuses with weight > 0: 0, 2, 6, 7, 8.
+- **Won** = 3 (Sold).
+- **Lost** = 4, 5, 9.
+
+### `thoughtleaders_brand`
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | int | Primary key |
+| `name` | varchar | Brand name |
+| `description` | text | Brand description |
+| `creator_id` | int FK | User who created it |
+
+#### Junction Tables
+
+| Table | Columns | Purpose |
+|-------|---------|---------|
+| `thoughtleaders_profile_brands` | `profile_id`, `brand_id` | Profile↔Brand M2M (Django field `profile.brands`). In practice each profile has one brand attached. |
+| `thoughtleaders_brand_brands` | `from_brand_id`, `to_brand_id` | Self-referential: related brands. |
+
+### `thoughtleaders_adspot` (Ad Catalogue)
+
+Buyable ad placements. Each adspot links a channel to a seller. Price/cost here are **list prices** — actual deal values live on the adlink.
+
+A channel can have multiple adspots (different sellers: talent manager, direct, multiple agencies).
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | int | Primary key |
+| `channel_id` | int FK | → `thoughtleaders_channel.id` |
+| `price` | numeric | List/catalogue price |
+| `cost` | numeric | List/catalogue cost |
+| `integration` | int | 1=YouTube Mentions (live reads). Only one active mention-type adspot per channel. |
+| `is_active` | boolean | Active flag |
+| `publisher_id` | int FK | → `auth_user.id` (NOT `thoughtleaders_profile.id` — see gotcha below) |
+
+### `thoughtleaders_channel` (YouTube Channels)
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | int | Primary key |
+| `channel_name` | varchar | Display name |
+| `external_channel_id` | varchar | YouTube channel ID (`UCxxxxxx`). ⚠️ There is NO `youtube_id` column. |
+| `url` | varchar | Channel URL |
+| `media_selling_network_join_date` | date/timestamptz | When channel joined MSN |
+| `is_tl_channel` | boolean | True = TPP/VIP channel |
+| `evergreenness` | float | Cached evergreen score |
+
+### `auth_user` (Django Users)
+
+Standard Django user table. Used for owner lookups.
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | int | Primary key |
+| `first_name` | varchar | First name |
+| `last_name` | varchar | Last name |
+| `email` | varchar | Email |
+
+## Top Tables by Row Count
+
+| Rows | Table | Purpose |
+|------|-------|---------|
+| 1.3M | `thoughtleaders_channel` | YouTube channels |
+| 1.2M | `thoughtleaders_historicaladlink` | Audit trail for adlink changes |
+| 150K | `thoughtleaders_adlink` | Deals/sponsorships |
+| 43K | `thoughtleaders_adspot` | Ad placements |
+| 20K | `auth_user` | Users (team + external) |
+| 20K | `thoughtleaders_profile` | User profiles |
+| 19K | `thoughtleaders_organization` | Organizations |
+| 19K | `dashboard_campaign` | Campaign groupings |
+| 13K | `thoughtleaders_dailymetric` | Daily performance metrics |
+| 12K | `thoughtleaders_leads` | Sales leads |
+
+## Key Relationships
+
+```
+thoughtleaders_adlink
+  ├── ad_spot_id → thoughtleaders_adspot.id
+  │                  └── channel_id → thoughtleaders_channel.id
+  ├── owner_advertiser_id → auth_user.id
+  ├── owner_publisher_id → auth_user.id
+  ├── owner_sales_id → auth_user.id
+  └── creator_profile_id → thoughtleaders_profile.id
+                              ├── organization_id → thoughtleaders_organization.id
+                              └── profile_brands.profile_id → brand.id
+
+⚠️ thoughtleaders_adlink has NO direct brand_id, organization_id, or channel_id column.
+⚠️ thoughtleaders_brand has NO organization_id column — org lives on profile.
+```
+
+### Common Join Paths
+
+**Adlink → Channel name:**
+```sql
+JOIN thoughtleaders_adspot s ON a.ad_spot_id = s.id
+JOIN thoughtleaders_channel ch ON s.channel_id = ch.id
+```
+
+**Adlink → Brand name:**
+```sql
+JOIN thoughtleaders_profile p ON a.creator_profile_id = p.id
+JOIN thoughtleaders_profile_brands pb ON p.id = pb.profile_id
+JOIN thoughtleaders_brand b ON pb.brand_id = b.id
+-- NEVER: JOIN brand b ON b.id = a.creator_profile_id (different ID spaces, returns wrong data)
+```
+
+**Adlink → Organization:**
+```sql
+JOIN thoughtleaders_profile p ON a.creator_profile_id = p.id
+JOIN thoughtleaders_organization o ON p.organization_id = o.id
+```
+
+🚨 **`adspot.publisher_id` is a FK to `auth_user`, not `profile`.** To get the publisher's profile, join through user:
+```sql
+JOIN auth_user au ON au.id = adspot.publisher_id
+JOIN thoughtleaders_profile p ON p.user_id = adspot.publisher_id
+```
+Joining `adspot.publisher_id → profile.id` directly mixes ID spaces and returns garbage.
+
+## `thoughtleaders_profile` persona constants
+
+| Value | Label |
+|-------|-------|
+| 1 | Direct Brand |
+| 2 | Creator |
+| 3 | Talent Manager |
+| 4 | Media Agency |
+| 5 | Creator Service |
+
+## `thoughtleaders_profile_channels` (Profile ↔ Channel M2M)
+
+| Column | Type |
+|--------|------|
+| `id` | int PK |
+| `profile_id` | int FK |
+| `channel_id` | int FK |
+
+Note: separate from the adspot publisher relationship. Not always in sync.
+
+## Example queries
+
+**Total weighted pipeline by sales rep:**
+```sql
+SELECT owner_sales_id, SUM(weighted_price) AS pipeline
+FROM thoughtleaders_adlink
+WHERE publish_status IN (0, 2, 6, 7, 8)
+GROUP BY owner_sales_id
+ORDER BY pipeline DESC
+LIMIT 100 OFFSET 0
+```
+
+**Sold deals this month:**
+```sql
+SELECT id, price, purchase_date, ad_spot_id, creator_profile_id
+FROM thoughtleaders_adlink
+WHERE publish_status = 3
+  AND purchase_date >= date_trunc('month', CURRENT_DATE)
+ORDER BY purchase_date DESC
+LIMIT 500 OFFSET 0
+```
+
+**MSN channel joins this month:**
+```sql
+SELECT id, channel_name, media_selling_network_join_date
+FROM thoughtleaders_channel
+WHERE media_selling_network_join_date >= date_trunc('month', CURRENT_DATE)
+ORDER BY media_selling_network_join_date DESC
+LIMIT 500 OFFSET 0
+```
+
+**Deal with brand and channel name:**
+```sql
+SELECT a.id, a.price, a.publish_status, b.name AS brand, ch.channel_name
+FROM thoughtleaders_adlink a
+JOIN thoughtleaders_adspot s ON a.ad_spot_id = s.id
+JOIN thoughtleaders_channel ch ON s.channel_id = ch.id
+JOIN thoughtleaders_profile p ON a.creator_profile_id = p.id
+JOIN thoughtleaders_profile_brands pb ON p.id = pb.profile_id
+JOIN thoughtleaders_brand b ON pb.brand_id = b.id
+WHERE a.id = 12345
+LIMIT 1 OFFSET 0
+```

tl_cli/auth/commands.py

@@ -0,0 +1,49 @@
+"""Auth CLI commands: tl auth login/logout/status."""
+
+import typer
+from rich.console import Console
+from rich.prompt import Prompt
+
+from tl_cli.auth.login import login_browser, login_device_code
+from tl_cli.auth.token_store import clear_tokens, load_tokens
+
+app = typer.Typer(help="Authentication commands")
+console = Console(stderr=True)
+
+
+@app.command("login", help="Log in to ThoughtLeaders.")
+def login_cmd() -> None:
+    """Log in to ThoughtLeaders."""
+    console.print("[bold]How would you like to authenticate?[/bold]")
+    console.print("  [cyan]1[/cyan] — Browser on this machine (default)")
+    console.print("  [cyan]2[/cyan] — Device code (use a browser on another device)")
+    console.print()
+    choice = Prompt.ask("Choose", choices=["1", "2"], default="1", console=console)
+
+    if choice == "2":
+        login_device_code()
+    else:
+        login_browser()
+
+
+@app.command("logout")
+def logout_cmd() -> None:
+    """Clear stored authentication tokens."""
+    clear_tokens()
+    console.print("[green]Logged out successfully.[/green]")
+
+
+@app.command("status")
+def status_cmd() -> None:
+    """Show current authentication status."""
+    tokens = load_tokens()
+    if not tokens:
+        console.print("[yellow]Not logged in.[/yellow] Run: tl auth login")
+        raise SystemExit(2)
+
+    if tokens.is_expired:
+        console.print(f"[yellow]Token expired.[/yellow] Logged in as: {tokens.email or 'unknown'}")
+        console.print("Run: tl auth login")
+        raise SystemExit(2)
+
+    console.print(f"[green]Authenticated[/green] as: {tokens.email or 'unknown'}")

tl_cli/auth/login.py

@@ -0,0 +1,328 @@
+"""Auth0 login flows: browser-based PKCE and headless device code."""
+
+import http.server
+import secrets
+import threading
+import time
+import urllib.parse
+import webbrowser
+from dataclasses import dataclass
+
+import httpx
+from rich.console import Console
+
+from tl_cli.auth.pkce import generate_pkce_pair
+from tl_cli.auth.token_store import StoredTokens, save_tokens
+from tl_cli.config import get_config
+
+console = Console(stderr=True)
+
+
+@dataclass
+class _CallbackResult:
+    """Captured from the OAuth callback."""
+
+    code: str | None = None
+    error: str | None = None
+    state: str | None = None
+
+
+def login_browser() -> StoredTokens:
+    """Run the Auth0 PKCE login flow with a local browser.
+
+    1. Generate PKCE pair + state
+    2. Start localhost callback server
+    3. Open browser to Auth0 /authorize
+    4. Wait for callback with authorization code
+    5. Exchange code for tokens
+    6. Store tokens
+    """
+    config = get_config()
+    code_verifier, code_challenge = generate_pkce_pair()
+    state = secrets.token_urlsafe(32)
+    result = _CallbackResult()
+
+    # Start callback server on the fixed port (must match Auth0 allowed callback URLs)
+    from tl_cli.config import DEFAULT_AUTH0_CALLBACK_PORT
+    server, port = _start_callback_server(result, state, DEFAULT_AUTH0_CALLBACK_PORT)
+
+    redirect_uri = f"http://localhost:{port}/callback"
+
+    # Build authorization URL
+    params = {
+        "response_type": "code",
+        "client_id": config.auth0_client_id,
+        "redirect_uri": redirect_uri,
+        "audience": config.auth0_audience,
+        "scope": "openid profile email offline_access",
+        "code_challenge": code_challenge,
+        "code_challenge_method": "S256",
+        "state": state,
+    }
+    auth_url = f"https://{config.auth0_domain}/authorize?{urllib.parse.urlencode(params)}"
+
+    console.print("[bold]Opening browser for login...[/bold]")
+    console.print(f"[dim]If the browser doesn't open, visit:[/dim]\n{auth_url}\n")
+    webbrowser.open(auth_url)
+
+    # Wait for callback (timeout after 120 seconds)
+    deadline = time.time() + 120
+    while result.code is None and result.error is None:
+        if time.time() > deadline:
+            server.shutdown()
+            console.print("[red]Login timed out. Please try again.[/red]")
+            raise SystemExit(1)
+        time.sleep(0.1)
+
+    server.shutdown()
+
+    if result.error:
+        console.print(f"[red]Login failed: {result.error}[/red]")
+        raise SystemExit(1)
+
+    # Exchange code for tokens
+    console.print("[dim]Exchanging authorization code...[/dim]")
+    tokens = _exchange_code(
+        code=result.code,
+        code_verifier=code_verifier,
+        redirect_uri=redirect_uri,
+        config=config,
+    )
+
+    save_tokens(tokens)
+    console.print(f"[green]Logged in as {tokens.email or 'unknown'}[/green]")
+    return tokens
+
+
+def login_device_code() -> StoredTokens:
+    """Run the Auth0 Device Authorization Flow (RFC 8628).
+
+    Works on headless machines — the user authenticates via any browser on any device.
+    """
+    config = get_config()
+
+    # Request a device code
+    response = httpx.post(
+        f"https://{config.auth0_domain}/oauth/device/code",
+        data={
+            "client_id": config.auth0_client_id,
+            "scope": "openid profile email offline_access",
+            "audience": config.auth0_audience,
+        },
+    )
+
+    if response.status_code != 200:
+        console.print(f"[red]Failed to start device login: {response.text}[/red]")
+        raise SystemExit(1)
+
+    data = response.json()
+    device_code = data["device_code"]
+    user_code = data["user_code"]
+    verification_uri = data["verification_uri"]
+    verification_uri_complete = data.get("verification_uri_complete", verification_uri)
+    interval = data.get("interval", 5)
+    expires_in = data.get("expires_in", 900)
+
+    console.print()
+    console.print("[bold]To log in, open this URL on any device:[/bold]")
+    console.print(f"  {verification_uri_complete}")
+    console.print()
+    console.print(f"[bold]And enter the code:[/bold]  [cyan bold]{user_code}[/cyan bold]")
+    console.print()
+    console.print(f"[dim]The code expires in {expires_in // 60} minutes.[/dim]")
+
+    # Poll for token
+    deadline = time.time() + expires_in
+    while time.time() < deadline:
+        time.sleep(interval)
+
+        token_response = httpx.post(
+            f"https://{config.auth0_domain}/oauth/token",
+            data={
+                "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                "device_code": device_code,
+                "client_id": config.auth0_client_id,
+            },
+        )
+
+        token_data = token_response.json()
+
+        if token_response.status_code == 200:
+            # Extract email from ID token if present
+            email = None
+            id_token = token_data.get("id_token")
+            if id_token:
+                email = _extract_email_from_jwt(id_token)
+
+            tokens = StoredTokens(
+                access_token=token_data["access_token"],
+                refresh_token=token_data.get("refresh_token"),
+                expires_at=time.time() + token_data.get("expires_in", 3600),
+                email=email,
+            )
+            save_tokens(tokens)
+            console.print(f"\n[green]Logged in as {tokens.email or 'unknown'}[/green]")
+            return tokens
+
+        error = token_data.get("error")
+        if error == "authorization_pending":
+            continue
+        elif error == "slow_down":
+            interval += 5
+            continue
+        elif error == "expired_token":
+            console.print("[red]Device code expired. Please try again.[/red]")
+            raise SystemExit(1)
+        elif error == "access_denied":
+            console.print("[red]Login was denied.[/red]")
+            raise SystemExit(1)
+        else:
+            console.print(f"[red]Login failed: {token_data.get('error_description', error)}[/red]")
+            raise SystemExit(1)
+
+    console.print("[red]Login timed out. Please try again.[/red]")
+    raise SystemExit(1)
+
+
+def refresh_access_token(refresh_token: str) -> StoredTokens:
+    """Use a refresh token to get a new access token."""
+    config = get_config()
+
+    response = httpx.post(
+        f"https://{config.auth0_domain}/oauth/token",
+        json={
+            "grant_type": "refresh_token",
+            "client_id": config.auth0_client_id,
+            "refresh_token": refresh_token,
+        },
+    )
+
+    if response.status_code != 200:
+        console.print("[red]Token refresh failed. Please run: tl auth login[/red]")
+        raise SystemExit(2)
+
+    data = response.json()
+    tokens = StoredTokens(
+        access_token=data["access_token"],
+        refresh_token=data.get("refresh_token", refresh_token),
+        expires_at=time.time() + data.get("expires_in", 3600),
+        email=None,  # Not returned on refresh
+    )
+    save_tokens(tokens)
+    return tokens
+
+
+def _exchange_code(
+    code: str,
+    code_verifier: str,
+    redirect_uri: str,
+    config,
+) -> StoredTokens:
+    """Exchange authorization code for tokens."""
+    response = httpx.post(
+        f"https://{config.auth0_domain}/oauth/token",
+        json={
+            "grant_type": "authorization_code",
+            "client_id": config.auth0_client_id,
+            "code": code,
+            "code_verifier": code_verifier,
+            "redirect_uri": redirect_uri,
+        },
+    )
+
+    if response.status_code != 200:
+        console.print(f"[red]Token exchange failed: {response.text}[/red]")
+        raise SystemExit(1)
+
+    data = response.json()
+
+    # Decode email from ID token if present
+    email = None
+    id_token = data.get("id_token")
+    if id_token:
+        email = _extract_email_from_jwt(id_token)
+
+    return StoredTokens(
+        access_token=data["access_token"],
+        refresh_token=data.get("refresh_token"),
+        expires_at=time.time() + data.get("expires_in", 3600),
+        email=email,
+    )
+
+
+def _extract_email_from_jwt(token: str) -> str | None:
+    """Extract email from JWT payload without full verification (already trusted from Auth0)."""
+    import base64
+    import json
+
+    try:
+        payload_part = token.split(".")[1]
+        # Add padding
+        padding = 4 - len(payload_part) % 4
+        payload_part += "=" * padding
+        payload = json.loads(base64.urlsafe_b64decode(payload_part))
+        return payload.get("email")
+    except Exception:
+        return None
+
+
+def _start_callback_server(
+    result: _CallbackResult, expected_state: str, port: int = 0
+) -> tuple[http.server.HTTPServer, int]:
+    """Start a temporary HTTP server to receive the OAuth callback."""
+
+    class CallbackHandler(http.server.BaseHTTPRequestHandler):
+        def do_GET(self):
+            parsed = urllib.parse.urlparse(self.path)
+            params = urllib.parse.parse_qs(parsed.query)
+
+            if parsed.path != "/callback":
+                self.send_response(404)
+                self.end_headers()
+                return
+
+            # Check state
+            received_state = params.get("state", [None])[0]
+            if received_state != expected_state:
+                result.error = "State mismatch — possible CSRF attack"
+                self._respond("Login failed: state mismatch.")
+                return
+
+            if "error" in params:
+                result.error = params["error"][0]
+                desc = params.get("error_description", [""])[0]
+                self._respond(f"Login failed: {desc or result.error}")
+                return
+
+            code = params.get("code", [None])[0]
+            if not code:
+                result.error = "No authorization code received"
+                self._respond("Login failed: no code received.")
+                return
+
+            result.code = code
+            self._respond(
+                "Login successful! You can close this tab and return to the terminal."
+            )
+
+        def _respond(self, message: str):
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html")
+            self.end_headers()
+            html = f"""<!DOCTYPE html>
+<html><head><title>TL CLI Login</title></head>
+<body style="font-family: system-ui; text-align: center; padding: 60px;">
+<h2>{message}</h2>
+</body></html>"""
+            self.wfile.write(html.encode())
+
+        def log_message(self, format, *args):
+            pass  # Suppress HTTP logs
+
+    server = http.server.HTTPServer(("127.0.0.1", port), CallbackHandler)
+    port = server.server_address[1]
+
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+
+    return server, port

tl_cli/auth/pkce.py

@@ -0,0 +1,21 @@
+"""PKCE (Proof Key for Code Exchange) utilities for OAuth 2.1."""
+
+import base64
+import hashlib
+import secrets
+
+
+def generate_pkce_pair() -> tuple[str, str]:
+    """Generate a PKCE code_verifier and code_challenge (S256).
+
+    Returns:
+        (code_verifier, code_challenge) tuple.
+    """
+    # code_verifier: 43-128 characters, URL-safe
+    code_verifier = secrets.token_urlsafe(64)
+
+    # code_challenge: SHA256 hash of verifier, base64url-encoded (no padding)
+    digest = hashlib.sha256(code_verifier.encode("ascii")).digest()
+    code_challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+
+    return code_verifier, code_challenge