Social Poster — Direct OAuth Posting

Overview

User Interaction Flow

1. "What networks can you post to?"

The agent should:

1. Run python3 ~/.social-poster/social-poster.py vault:status to check which platforms have stored tokens
2. Report the full list of 14 platforms, marking connected ones with ✅ and the rest as ⬜
3. Offer: "Want me to guide you through setting up any of them?"

Example response:

14 platforms supported. Currently connected:
  ✅ X, LinkedIn, Bluesky
  ⬜ Instagram, Mastodon, Twitch, Reddit, Discord, Slack, Telegram, GitHub, Threads, Facebook, YouTube
Say 'connect [platform]' and I'll walk you through it."

2. "Connect [platform]" or "How do I set up [platform]?"

The agent should:

1. Load the platform's setup guide from references/platform-setup-guides.md
2. Walk the user through the numbered steps, one at a time
3. For OAuth platforms: ask for credentials, save to config.json, generate auth URL, exchange code
4. For webhook/token platforms: ask for the URL/token, save to config.json, verify it works

3. "Post this to [platforms]: [content]"

The agent should:

1. Check the vault that the requested platforms have tokens
2. Use the platform-specific API to post
3. Report success/failure per platform
4. Respect per-platform character limits (see Platform Character Limits below)

4. "Schedule this for [time]"

The agent should:

1. Create a Hermes cron job that calls the posting function at the specified time
2. Use cronjob action='create' with the posting instructions

Architecture

{{SOCIAL_POSTER_DIR}}/
├── config.json              — API credentials (key/secret per platform)
├── vault.json               — User access/refresh tokens
├── social-poster.py         — Unified CLI (vault status, auth URL gen, token exchange)
├── webhook-poster.py        — Webhook/Token poster (Discord, Slack, Telegram, GitHub)
├── auth-x-step1.py          — X OAuth step 1 (request token + auth URL)
├── auth-x-step2.py          — X OAuth step 2 (exchange PIN for access token)
├── oauth-callback-server.py — Callback HTTP server (Tailscale Serve)
└── last_code.txt            — Latest OAuth code captured (auto-generated)

Platform Setup Guides

For step-by-step instructions on creating developer apps and getting credentials, load references/platform-setup-guides.md. Each platform has:

• Exact URLs to visit
• Buttons to click and fields to fill
• Where to find credentials
• How the auth flow works

Quick Reference: Auth Method Summary

Environment Variables

All platforms support environment variable fallback when config.json is absent. This is useful for CI/CD or ephemeral environments:

Cross-Machine OAuth (Reverse Proxy Required)

When the agent is on a remote machine and the user is on a different machine (e.g., their desktop "Kratos"), OAuth redirect URLs need to point somewhere the user's browser can reach.

You need a reverse proxy that makes a local port accessible via HTTPS at a URL you can reach from your browser. Options include:

• Tailscale Serve — HTTPS on your tailnet, no public internet needed
• Cloudflare Tunnel (cloudflared) — public or private tunnels
• Nginx Proxy Manager — if you have a domain pointing to your VPS
• ngrok — quick public URL for testing
• Your VPS hostname — if it already has HTTPS

The URL does NOT need to be public on the internet — it just needs to be reachable by YOUR browser.

Setup (one-time)

# 1. Start the callback server (persistent, port 19876)
python3 ~/.social-poster/oauth-callback-server.py 19876 &

# 2. Use your reverse proxy to route paths to 127.0.0.1:19876
#    Example with Tailscale: tailscale serve --bg --set-path /oauth-callback 19876
#    Example with Cloudflare: cloudflared tunnel --url http://localhost:19876
#    Example with nginx: proxy_pass http://127.0.0.1:19876 in your site config

# The paths you need depend on which platforms you use:
# - /oauth-callback                          # For Mastodon, Twitch, Reddit, etc.
# - /integrations/social/linkedin            # If using LinkedIn
# - /integrations/social/instagram            # If using Instagram

How the Callback Server Works

The Python HTTP server (oauth-callback-server.py) listens on 127.0.0.1:19876. Your reverse proxy forwards HTTPS requests to it. When an OAuth redirect arrives with ?code=..., the server saves the code to {{SOCIAL_POSTER_DIR}}/last_code.txt.

The agent then reads the code and exchanges it for tokens. The server stays alive between sessions and handles any number of callbacks.

Platform Character Limits

When posting, respect per-platform limits:

Pitfalls

• Never use os.path.expanduser("~") directly in Hermes sessions — it resolves to the sandbox home. Scripts auto-detect and use pwd.getpwuid().
• config.json and vault.json must be chmod 600 — NEVER committed to git.
• LinkedIn scopes must NOT include org scopes unless the app has Community Management API.
• LinkedIn MUST NOT use prompt=none for first-time authorization.
• X/Twitter callback must be oob for PIN-based flow.
• Instagram app MUST be Live (not Development) for OAuth.
• Bluesky uses app passwords (format: xxxx-xxxx-xxxx-xxxx), not regular passwords.
• Redirect URI MUST match exactly between auth URL and token exchange POST.
• state parameter is REQUIRED for all OAuth 2.0 flows — built into all generators.
• post.py is text-only — any post carrying a picture needs scripts/post_with_image.py (same vault/config, per-platform copy from <dir>/<platform>.md). Verified upload recipes for X, LinkedIn, Bluesky, Mastodon and Discord are in references/image-posts.md.
• LinkedIn /rest/posts returns 500 for every active version on this app (202601-202608, 2026-09-15); post images via /v2/assets?action=registerUpload + /v2/ugcPosts with shareMediaCategory: IMAGE. A urn:li:image: URN from /rest/images in a ugcPost fails as "not owned by the author".
• X returns 402 credits depleted regardless of code correctness once the Pay-Per-Use balance hits zero. Auth and media upload still succeed, so diagnose in that order before touching the code.
• Platform setup guides may drift as developer portals update their UIs. If a user reports a step doesn't match, verify at the official developer portal URL and update the guide.
• Discord's edge returns 403 to urllib's default User-Agent (Python-urllib/3.x) while accepting any explicit one. A health probe that sends no User-Agent therefore reports a perfectly live webhook as "deleted/invalid" and sends you off to recreate something that was never broken. post.py sends User-Agent: SocialPoster/1.0 and works fine. Set an explicit agent on every Discord-touching request, and before acting on a discord FAIL, confirm with an explicit-agent GET or a real POST rather than trusting the 403.
• Store a Discord webhook URL without ?wait=true. post_discord treats any non-empty response body as failure, so ?wait=true (which makes Discord return the created message object instead of an empty 204) turns every successful post into a reported failure. If a Discord result looks like a failure, read the channel back before believing it.
• A token can expire with no refresh path. An OAuth app may return an access token with a long lifetime and an empty refresh_token if programmatic refresh is not enabled on it. Record the expiry timestamp when you store the token and watch it, or the platform dies silently on a known date. A daily platform-state watchdog that alerts on change (including days-remaining) turns that into an advance warning.

References

• references/platform-setup-guides.md — Step-by-step setup guides for all 15 platforms
• references/platform-expansion.md — Full roadmap and implementation notes
• references/oauth-flows.md — OAuth implementation details and token exchange reference