Upload 236 files

.env.example

@@ -30,3 +30,58 @@ AUTH_DEFAULT_PROCESSING_BYTES_PER_DAY=107374182400
 AUTH_TRUST_PROXY_HEADERS=true
 # Required only when running the standalone stdio MCP transport with auth enabled.
 MCP_STDIO_API_KEY=
+
+# Social Automation Foundation. Apply all SQL files under app/social/migrations/
+# to Supabase/Postgres before enabling social writes in production. The existing
+# DATABASE_URL remains a local-development fallback only.
+SOCIAL_ENABLED=true
+# Example: postgresql+asyncpg://postgres:password@db.example:5432/postgres
+SOCIAL_DATABASE_URL=
+SOCIAL_AUTO_MIGRATE=false
+SOCIAL_WORKER_ENABLED=true
+SOCIAL_SCHEDULER_INTERVAL_SECONDS=30
+SOCIAL_JOB_STALE_AFTER_SECONDS=900
+SOCIAL_PUBLISH_RETRY_LIMIT=5
+SOCIAL_OAUTH_REQUESTS_PER_HOUR=30
+SOCIAL_PUBLISH_REQUESTS_PER_MINUTE=30
+SOCIAL_SCHEDULE_REQUESTS_PER_MINUTE=60
+SOCIAL_ANALYTICS_REQUESTS_PER_MINUTE=120
+# Required for OAuth state/PKCE and encrypted local token fallback. Generate at
+# least 32 random bytes, for example: openssl rand -base64 32
+SOCIAL_OAUTH_ENCRYPTION_KEY=
+SUPABASE_URL=
+SUPABASE_SERVICE_ROLE_KEY=
+SUPABASE_VAULT_ENABLED=false
+SOCIAL_OAUTH_REDIRECT_BASE_URL=
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+# YouTube Data API v3 worker controls. Keep the client secret backend-only.
+# Upload chunks must be a multiple of 262144 bytes (256 KiB).
+YOUTUBE_UPLOAD_CHUNK_BYTES=8388608
+YOUTUBE_MAX_CONCURRENT_UPLOADS=2
+YOUTUBE_REQUEST_TIMEOUT_SECONDS=60
+YOUTUBE_PROCESSING_POLL_SECONDS=30
+META_CLIENT_ID=
+META_CLIENT_SECRET=
+TIKTOK_CLIENT_KEY=
+TIKTOK_CLIENT_SECRET=
+# Exact backend callback registered under TikTok Login Kit. It must be:
+# https://<api-host>/v1/social/accounts/tiktok/callback
+TIKTOK_REDIRECT_URI=
+# Fail closed. Set true only after Content Posting API Direct Post approval and
+# video.publish authorization are confirmed for this TikTok application.
+TIKTOK_DIRECT_POST_ENABLED=false
+# TikTok FILE_UPLOAD chunks: 5,000,000 through 64,000,000 bytes.
+TIKTOK_UPLOAD_CHUNK_BYTES=10000000
+TIKTOK_REQUEST_TIMEOUT_SECONDS=60
+TIKTOK_PROCESSING_POLL_SECONDS=30
+# Test-only opt-in. Normal CI must keep this false; dedicated credentials and
+# explicit publish consent are documented in social-tiktok-production-readiness.md.
+RUN_TIKTOK_INTEGRATION_TESTS=false
+LINKEDIN_CLIENT_ID=
+LINKEDIN_CLIENT_SECRET=
+X_CLIENT_ID=
+X_CLIENT_SECRET=
+TELEGRAM_BOT_TOKEN=
+WHATSAPP_CLIENT_ID=
+WHATSAPP_CLIENT_SECRET=

README.md

@@ -124,6 +124,101 @@ Use one Uvicorn process in a CPU Space. FFmpeg and Whisper concurrency is manage
 
 For durable keys, audit records, and rate aggregates, attach Hugging Face persistent storage and set `DATABASE_URL=sqlite+aiosqlite:////data/mediarouter.db`. The default `./data/mediarouter.db` is appropriate locally but follows the Space filesystem lifecycle. The security layer uses SQLAlchemy so a future external database migration does not change authentication contracts; this release includes and supports the `aiosqlite` driver.
 
+## Connect the Vercel frontend to Hugging Face
+
+The Next.js frontend is an authenticated backend-for-frontend (BFF): browser requests go to its same-origin `/api/backend/*` route, and only that server-side route attaches a backend API key. The browser must never receive an API key. All FFmpeg, Whisper, yt-dlp, uploads, and media processing remain in the Hugging Face Space.
+
+For the current hosted backend, the public origin is:
+
+```text
+https://basyx-mediarouter.hf.space
+```
+
+First verify that the Space has started successfully. This endpoint is public and must return HTTP `200` with `"status": "healthy"` before the frontend can connect:
+
+```bash
+curl -i https://basyx-mediarouter.hf.space/health
+```
+
+### Hugging Face Space secrets
+
+Create the bootstrap administrator locally, save its plaintext `API_KEY` in a password manager, and add **only** the three generated `AUTH_BOOTSTRAP_*` values to **Hugging Face Space → Settings → Secrets**. Enter each value in the value field only: no quotes, no `NAME=`, and no line breaks. Never commit these values.
+
+```text
+AUTH_BOOTSTRAP_KEY_HASH=<64-character lowercase SHA-256 hash>
+AUTH_BOOTSTRAP_KEY_PREFIX=mp_live_<first-eight-secret-characters>
+AUTH_BOOTSTRAP_ENVIRONMENT=live
+```
+
+The bootstrap fields are optional after the first successful start. If a Space fails at startup with `Bootstrap key hash or prefix is malformed`, remove duplicate or stale `AUTH_BOOTSTRAP_*` entries from both the Space **Variables** and **Secrets** panels, restart once, then recreate the three exact values above as Secrets. A blank hash and blank prefix deliberately disable bootstrap creation; a non-empty value must match the format exactly.
+
+Recommended backend deployment settings are:
+
+```env
+BASE_URL=https://basyx-mediarouter.hf.space
+DATABASE_URL=sqlite+aiosqlite:////data/mediarouter.db
+AUTH_ROLE_SCOPES={}
+MCP_STDIO_API_KEY=<a-valid-mp_live-or-mp_test-key-if-stdio-MCP-is-enabled>
+```
+
+`DATABASE_URL` uses `/data` so keys, audit logs, and rate-limit state survive only when Hugging Face persistent storage is attached. `BASE_URL` is the public Hugging Face origin, not the Vercel frontend URL.
+
+### Vercel environment variables
+
+Import this repository with `frontend` as the Vercel root directory. Configure the following values for **Production** and for **Preview** if preview deployments need to connect to the backend. Redeploy after changing an environment variable.
+
+```env
+# Server-only backend connection and credential. Never use NEXT_PUBLIC_ for a key.
+MEDIAROUTER_API_URL=https://basyx-mediarouter.hf.space
+MEDIAROUTER_MCP_URL=https://basyx-mediarouter.hf.space
+MEDIAROUTER_API_TOKEN=mp_live_<saved-bootstrap-admin-key-or-role-key>
+MEDIAROUTER_API_TIMEOUT=120000
+
+# Auth.js / OAuth (server only)
+AUTH_SECRET=<output-of-openssl-rand-base64-32>
+NEXTAUTH_URL=https://<your-vercel-project>.vercel.app
+AUTH_GITHUB_ID=<github-oauth-client-id>
+AUTH_GITHUB_SECRET=<github-oauth-client-secret>
+# Optional: configure both values to enable Google sign-in.
+AUTH_GOOGLE_ID=
+AUTH_GOOGLE_SECRET=
+AUTH_SESSION_MAX_AGE=28800
+
+# Human-role mapping. Put your own OAuth email in the Admin list.
+AUTH_USER_ROLES={}
+AUTH_ADMIN_EMAILS=<your-verified-oauth-email>
+AUTH_DEVELOPER_EMAILS=
+AUTH_OPERATOR_EMAILS=
+AUTH_VIEWER_EMAILS=
+AUTH_DEFAULT_ROLE=Viewer
+
+# Public, non-secret display and capability settings.
+NEXT_PUBLIC_API_URL=https://basyx-mediarouter.hf.space
+NEXT_PUBLIC_MCP_URL=https://basyx-mediarouter.hf.space
+NEXT_PUBLIC_APP_NAME=MediaRouter
+NEXT_PUBLIC_ENABLE_MCP=true
+NEXT_PUBLIC_ENABLE_MARKETPLACE=true
+```
+
+`MEDIAROUTER_API_TOKEN` is the server-only fallback for every human role. In a least-privilege production setup, create dedicated backend role keys after bootstrap and replace it with the appropriate keys instead:
+
+```env
+MEDIAROUTER_ADMIN_API_TOKEN=mp_live_<admin-key>
+MEDIAROUTER_DEVELOPER_API_TOKEN=mp_live_<developer-key>
+MEDIAROUTER_OPERATOR_API_TOKEN=mp_live_<operator-key>
+MEDIAROUTER_VIEWER_API_TOKEN=mp_live_<viewer-key>
+```
+
+GitHub’s production callback URL is `https://<your-vercel-project>.vercel.app/api/auth/callback/github`; Google’s is the equivalent `/api/auth/callback/google`. Generate `AUTH_SECRET` with `openssl rand -base64 32`. Never put API keys, OAuth client secrets, or `AUTH_SECRET` in a `NEXT_PUBLIC_*` variable.
+
+### Verify the complete connection
+
+1. Confirm `https://basyx-mediarouter.hf.space/health` returns `200`.
+2. Redeploy Vercel after its environment variables are set.
+3. Sign in using an OAuth account assigned to `AUTH_ADMIN_EMAILS`.
+4. Visit the frontend `/api/backend/health` while signed in. It should proxy the healthy backend response.
+5. If it returns `Backend authentication unavailable`, set `MEDIAROUTER_API_TOKEN` or the token matching the signed-in user’s role. If it returns `401`, the backend key is expired, disabled, revoked, or not the key represented by the Space bootstrap hash.
+
 ## Authentication and authorization
 
 MediaRouter uses stateless opaque API keys. There are no passwords, login sessions, cookies, or JWTs. Except for the public endpoints below, every REST and MCP request must send:
@@ -1084,6 +1179,53 @@ When the upstream binary property is `data`, use an expression body:
 
 For large files, prefer n8n's multipart binary option or raw binary body; JSON Base64 temporarily expands data by roughly 33%.
 
+## Social Automation: YouTube Phase 2
+
+MediaRouter now publishes YouTube videos through the shared `SocialService → SocialPublisher → YouTubeProvider` pipeline. REST, frontend, MCP, TypeScript/Python SDKs, and the n8n Social node use the same typed post, durable job, OAuth/token, validation, retry, and status-reconciliation implementation; none contains Google publishing logic or receives Google credentials.
+
+YouTube is implemented with the official YouTube Data API v3. It supports OAuth + PKCE, stable channel discovery, encrypted TokenService credentials, registered MediaRouter video outputs, typed YouTube metadata including the required audience declaration, resumable chunked upload, crash-safe external-video reconciliation, status polling, deletion, and supported video statistics. `GET /v1/social/providers` reports YouTube as implemented and reports the other requested providers as registered/unimplemented. Apply all social migrations in numeric order through `0004_youtube_media_assets.sql` before enabling production writes.
+
+Google setup, exact redirect URI, scope, output registration, metadata, scheduling, retries, quotas, analytics limits, and troubleshooting are documented in [docs/social-youtube.md](docs/social-youtube.md). The implementation report and live-test status are in [docs/social-youtube-production-readiness.md](docs/social-youtube-production-readiness.md). No staging credentials were supplied, so live Google verification is **NOT VERIFIED**.
+
+## Social Automation: TikTok Phase 4
+
+TikTok Direct Post video publishing now uses the same SocialService, durable
+SocialJob, TokenService, scheduler, retry, idempotency, and media-variant
+pipeline. It calls only the official TikTok Content Posting API: creator info,
+video initialization, sequential `FILE_UPLOAD` chunks, and publish-status
+reconciliation. TikTok Direct Post is fail-closed behind
+`TIKTOK_DIRECT_POST_ENABLED=false` and requires an explicit OAuth reconnect with
+the approved `video.publish` scope. MediaRouter scheduling is supported;
+TikTok-native scheduling and deletion are not advertised. See
+[docs/social-tiktok-publishing.md](docs/social-tiktok-publishing.md) for
+approval, media requirements, metadata, retries, idempotency, and integration
+usage. Live TikTok verification requires a dedicated approved app and test
+creator and is not part of normal CI.
+
+Phase 4C adds explicit `video.list` authorization and official Display API
+video analytics, tenant/security hardening, credential redaction, optional live
+integration coverage, and a classified readiness audit. See
+[docs/social-tiktok-production-readiness.md](docs/social-tiktok-production-readiness.md).
+Live TikTok, Postgres RLS, and Docker verification remain environment-dependent
+and must not be inferred from configuration alone.
+
+### Social quick discovery
+
+```bash
+curl -H "Authorization: Bearer $MEDIAROUTER_API_KEY" \
+  https://your-space.hf.space/v1/social/providers
+```
+
+Register a completed MediaRouter output, then create a typed YouTube draft with a one-time idempotency key:
+
+```bash
+curl -X POST https://your-space.hf.space/v1/social/posts \
+  -H "Authorization: Bearer $MEDIAROUTER_API_KEY" \
+  -H "Idempotency-Key: $(openssl rand -hex 16)" \
+  -H "Content-Type: application/json" \
+  -d '{"media_asset_id":"<registered_social_asset_id>","publish_mode":"draft","targets":[{"social_account_id":"<youtube_account_id>","youtube":{"title":"Example","description":"YouTube copy","privacy_status":"private","made_for_kids":false}}]}'
+```
+
 ## Configuration
 
 | Variable | Default | Purpose |
@@ -1118,6 +1260,32 @@ For large files, prefer n8n's multipart binary option or raw binary body; JSON B
 | `AUTH_DEFAULT_PROCESSING_BYTES_PER_DAY` | `107374182400` | Default daily uploaded processing bytes |
 | `AUTH_TRUST_PROXY_HEADERS` | `true` | Use first `X-Forwarded-For` address for audits behind HF/Vercel |
 | `MCP_STDIO_API_KEY` | empty | Existing API key required by authenticated standalone stdio MCP |
+| `SOCIAL_ENABLED` | `true` | Enable the additive social domain; existing media APIs remain independent |
+| `SOCIAL_DATABASE_URL` | `DATABASE_URL` | Async SQLAlchemy URL; use Supabase/Postgres in production |
+| `SOCIAL_AUTO_MIGRATE` | `false` | Local/test metadata creation only; never use for production migration management |
+| `SOCIAL_WORKER_ENABLED` | `true` | Run durable scheduler/publisher claim loop when schema is ready |
+| `SOCIAL_SCHEDULER_INTERVAL_SECONDS` | `30` | Scheduler polling interval |
+| `SOCIAL_JOB_STALE_AFTER_SECONDS` | `900` | Recover an interrupted active job after this worker-lease period |
+| `SOCIAL_PUBLISH_RETRY_LIMIT` | `5` | Maximum provider publishing attempts |
+| `SOCIAL_OAUTH_ENCRYPTION_KEY` | empty | Required secret for PKCE state and local encrypted token fallback |
+| `SOCIAL_OAUTH_REDIRECT_BASE_URL` | empty | Public backend origin used to build exact provider callback URLs |
+| `SUPABASE_VAULT_ENABLED` | `false` | Store provider tokens as Supabase Vault secret references |
+| `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` | empty | Backend-only YouTube OAuth application credentials |
+| `YOUTUBE_UPLOAD_CHUNK_BYTES` | `8388608` | Resumable upload chunk size; must be a multiple of 256 KiB |
+| `YOUTUBE_MAX_CONCURRENT_UPLOADS` | `2` | Conservative per-process YouTube upload concurrency |
+| `YOUTUBE_REQUEST_TIMEOUT_SECONDS` | `60` | Per-request YouTube Data API timeout |
+| `YOUTUBE_PROCESSING_POLL_SECONDS` | `30` | Delay between server-side processing reconciliation polls |
+| `META_CLIENT_ID`, `META_CLIENT_SECRET` | empty | Backend-only Facebook/Instagram OAuth application credentials |
+| `TIKTOK_CLIENT_KEY`, `TIKTOK_CLIENT_SECRET` | empty | Backend-only TikTok Login Kit application credentials |
+| `TIKTOK_REDIRECT_URI` | empty | Exact backend-owned TikTok callback registered in Login Kit (`https://<api-host>/v1/social/accounts/tiktok/callback`) |
+| `TIKTOK_DIRECT_POST_ENABLED` | `false` | Fail-closed Direct Post gate; enable only after TikTok Content Posting approval |
+| `TIKTOK_UPLOAD_CHUNK_BYTES` | `10000000` | Sequential FILE_UPLOAD chunk target (5–64 MB; final chunk may be up to 128 MB) |
+| `TIKTOK_REQUEST_TIMEOUT_SECONDS` | `60` | TikTok OAuth, Content Posting, and upload request timeout |
+| `TIKTOK_PROCESSING_POLL_SECONDS` | `30` | Delay between official publish-status reconciliation polls |
+| `LINKEDIN_CLIENT_ID`, `LINKEDIN_CLIENT_SECRET` | empty | Backend-only LinkedIn OAuth credentials |
+| `X_CLIENT_ID`, `X_CLIENT_SECRET` | empty | Backend-only X OAuth credentials |
+| `TELEGRAM_BOT_TOKEN` | empty | Backend-only Telegram bot credential foundation |
+| `WHATSAPP_CLIENT_ID`, `WHATSAPP_CLIENT_SECRET` | empty | Backend-only WhatsApp Business credentials |
 
 ## Logging and safety
 

app/api/social.py

@@ -0,0 +1,298 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Header, Query, Request, Response, status
+
+from app.social.schemas.accounts import (
+    SocialAccountConnectRequest,
+    SocialAccountView,
+    SocialConnectResponse,
+    SocialPublishOptionsView,
+    SocialProviderView,
+)
+from app.social.schemas.assets import (
+    SocialMediaAssetRegister,
+    SocialMediaAssetView,
+)
+from app.social.schemas.jobs import SocialJobView
+from app.social.schemas.posts import SocialPostCreate, SocialPostView
+from app.social.schemas.scheduling import SocialScheduleCreate, SocialScheduleView
+
+router = APIRouter(prefix="/v1/social", tags=["social automation"])
+
+
+def _social(request: Request):
+    service = request.app.state.container.social
+    service.ensure_ready()
+    return service
+
+
+def _identity(request: Request) -> tuple[str, str]:
+    context = request.state.auth
+    # Phase 1 isolation: the authenticated API-key identity is the tenant
+    # boundary until the backend gains a native workspace membership model.
+    return context.api_key_id, context.api_key_id
+
+
+async def _audit(
+    request: Request,
+    event_type: str,
+    *,
+    provider: str | None = None,
+    account_id: str | None = None,
+    post_id: str | None = None,
+    job_id: str | None = None,
+) -> None:
+    workspace_id, user_id = _identity(request)
+    await request.app.state.container.social.audit.record(
+        workspace_id=workspace_id,
+        event_type=event_type,
+        api_key_id=user_id,
+        request_id=request.state.request_id,
+        provider=provider,
+        social_account_id=account_id,
+        social_post_id=post_id,
+        social_job_id=job_id,
+    )
+
+
+@router.get("/providers", response_model=list[SocialProviderView])
+async def list_providers(request: Request) -> list[SocialProviderView]:
+    return request.app.state.container.social.accounts.list_providers()
+
+
+@router.get(
+    "/providers/{provider}/capabilities", response_model=SocialProviderView
+)
+async def provider_capabilities(request: Request, provider: str) -> SocialProviderView:
+    return request.app.state.container.social.accounts.get_provider(provider)
+
+
+@router.get("/assets", response_model=list[SocialMediaAssetView])
+async def list_social_media_assets(
+    request: Request,
+    offset: int = Query(default=0, ge=0),
+    limit: int = Query(default=100, ge=1, le=500),
+) -> list[SocialMediaAssetView]:
+    workspace_id, _ = _identity(request)
+    return await _social(request).media_assets.list(workspace_id, offset=offset, limit=limit)
+
+
+@router.post("/assets", response_model=SocialMediaAssetView, status_code=status.HTTP_201_CREATED)
+async def register_social_media_asset(
+    request: Request, payload: SocialMediaAssetRegister
+) -> SocialMediaAssetView:
+    workspace_id, _ = _identity(request)
+    return await _social(request).media_assets.register(workspace_id, payload)
+
+
+@router.get("/accounts", response_model=list[SocialAccountView])
+async def list_accounts(
+    request: Request,
+    offset: int = Query(default=0, ge=0),
+    limit: int = Query(default=100, ge=1, le=500),
+) -> list[SocialAccountView]:
+    workspace_id, _ = _identity(request)
+    return await _social(request).accounts.list(
+        workspace_id, offset=offset, limit=limit
+    )
+
+
+@router.get("/accounts/{account_id}", response_model=SocialAccountView)
+async def get_account(request: Request, account_id: str) -> SocialAccountView:
+    workspace_id, _ = _identity(request)
+    return await _social(request).accounts.get(workspace_id, account_id)
+
+
+@router.get(
+    "/accounts/{account_id}/publish-options",
+    response_model=SocialPublishOptionsView,
+)
+async def get_account_publish_options(
+    request: Request, account_id: str
+) -> SocialPublishOptionsView:
+    workspace_id, _ = _identity(request)
+    return await _social(request).publishing.publish_options(
+        workspace_id, account_id
+    )
+
+
+@router.post(
+    "/accounts/{provider}/connect", response_model=SocialConnectResponse
+)
+async def connect_account(
+    request: Request, provider: str, payload: SocialAccountConnectRequest
+) -> SocialConnectResponse:
+    workspace_id, user_id = _identity(request)
+    result = await _social(request).oauth.connect(
+        provider=provider,
+        workspace_id=workspace_id,
+        user_id=user_id,
+        payload=payload,
+    )
+    await _audit(request, "SOCIAL_ACCOUNT_CONNECTION_STARTED", provider=provider)
+    return result
+
+
+@router.get(
+    "/accounts/{provider}/callback",
+    response_model=SocialAccountView,
+    include_in_schema=True,
+)
+async def oauth_callback(
+    request: Request,
+    provider: str,
+    state: Annotated[
+        str, Query(min_length=32, max_length=255, pattern=r"^[A-Za-z0-9_-]+$")
+    ],
+    code: Annotated[str | None, Query(min_length=1, max_length=4096)] = None,
+    error: Annotated[str | None, Query(max_length=128)] = None,
+) -> SocialAccountView:
+    # This provider-facing route is authenticated by a short-lived, single-use
+    # state record. Tenant/user identifiers are never accepted from the query.
+    social = request.app.state.container.social
+    social.ensure_ready()
+    if error or not code:
+        await social.oauth.callback_denied(provider=provider, state=state)
+        raise AssertionError("OAuth callback denial should raise a social error")
+    return await social.oauth.callback(provider=provider, state=state, code=code)
+
+
+@router.post("/accounts/{account_id}/refresh", response_model=SocialAccountView)
+async def refresh_account(request: Request, account_id: str) -> SocialAccountView:
+    workspace_id, _ = _identity(request)
+    result = await _social(request).oauth.refresh(
+        workspace_id=workspace_id, account_id=account_id
+    )
+    await _audit(request, "SOCIAL_ACCOUNT_REAUTHORIZED", account_id=account_id)
+    return result
+
+
+@router.delete("/accounts/{account_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def disconnect_account(request: Request, account_id: str) -> Response:
+    workspace_id, _ = _identity(request)
+    account = await _social(request).accounts.get(workspace_id, account_id)
+    await request.app.state.container.social.accounts.disconnect(workspace_id, account_id)
+    await _audit(
+        request,
+        "SOCIAL_ACCOUNT_DISCONNECTED",
+        provider=account.provider.value,
+        account_id=account_id,
+    )
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+@router.post(
+    "/posts", response_model=SocialPostView, status_code=status.HTTP_201_CREATED
+)
+async def create_post(
+    request: Request,
+    payload: SocialPostCreate,
+    idempotency_key: str | None = Header(
+        default=None, alias="Idempotency-Key", min_length=8, max_length=255
+    ),
+) -> SocialPostView:
+    workspace_id, user_id = _identity(request)
+    result = await _social(request).publishing.create(
+        workspace_id=workspace_id,
+        user_id=user_id,
+        payload=payload,
+        idempotency_key=idempotency_key,
+    )
+    await _audit(request, "SOCIAL_POST_CREATED", post_id=result.id)
+    return result
+
+
+@router.get("/posts", response_model=list[SocialPostView])
+async def list_posts(
+    request: Request,
+    offset: int = Query(default=0, ge=0),
+    limit: int = Query(default=100, ge=1, le=500),
+) -> list[SocialPostView]:
+    workspace_id, _ = _identity(request)
+    return await _social(request).publishing.list(
+        workspace_id, offset=offset, limit=limit
+    )
+
+
+@router.get("/posts/{post_id}", response_model=SocialPostView)
+async def get_post(request: Request, post_id: str) -> SocialPostView:
+    workspace_id, _ = _identity(request)
+    return await _social(request).publishing.get(workspace_id, post_id)
+
+
+@router.delete("/posts/{post_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_post(request: Request, post_id: str) -> Response:
+    workspace_id, _ = _identity(request)
+    await _social(request).publishing.delete(workspace_id, post_id)
+    await _audit(request, "SOCIAL_POST_DELETED", post_id=post_id)
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+@router.post(
+    "/posts/{post_id}/publish",
+    response_model=list[SocialJobView],
+    status_code=status.HTTP_202_ACCEPTED,
+)
+async def publish_post(
+    request: Request,
+    post_id: str,
+    idempotency_key: str = Header(alias="Idempotency-Key", min_length=8, max_length=255),
+) -> list[SocialJobView]:
+    workspace_id, _ = _identity(request)
+    jobs = await _social(request).publishing.queue(
+        workspace_id, post_id, idempotency_key=idempotency_key
+    )
+    return jobs
+
+
+@router.post("/posts/{post_id}/schedule", response_model=SocialScheduleView)
+async def schedule_post(
+    request: Request, post_id: str, payload: SocialScheduleCreate
+) -> SocialScheduleView:
+    workspace_id, _ = _identity(request)
+    await _social(request).publishing.validate_post_targets(workspace_id, post_id)
+    schedule = await _social(request).scheduling.schedule(
+        workspace_id, post_id, payload
+    )
+    await _audit(request, "SOCIAL_SCHEDULE_CREATED", post_id=post_id)
+    return schedule
+
+
+@router.post("/posts/{post_id}/cancel", response_model=SocialPostView)
+async def cancel_post(request: Request, post_id: str) -> SocialPostView:
+    workspace_id, _ = _identity(request)
+    result = await _social(request).publishing.cancel(workspace_id, post_id)
+    await _audit(request, "SOCIAL_POST_CANCELLED", post_id=post_id)
+    return result
+
+
+@router.get("/jobs", response_model=list[SocialJobView])
+async def list_jobs(
+    request: Request,
+    offset: int = Query(default=0, ge=0),
+    limit: int = Query(default=100, ge=1, le=500),
+) -> list[SocialJobView]:
+    workspace_id, _ = _identity(request)
+    return await _social(request).jobs.list(
+        workspace_id, offset=offset, limit=limit
+    )
+
+
+@router.get("/jobs/{job_id}", response_model=SocialJobView)
+async def get_job(request: Request, job_id: str) -> SocialJobView:
+    workspace_id, _ = _identity(request)
+    return await _social(request).jobs.get(workspace_id, job_id)
+
+
+@router.get("/accounts/{account_id}/analytics")
+async def account_analytics(request: Request, account_id: str) -> dict[str, object]:
+    workspace_id, _ = _identity(request)
+    return await _social(request).analytics.account(workspace_id, account_id)
+
+
+@router.get("/posts/{post_id}/analytics")
+async def post_analytics(request: Request, post_id: str) -> dict[str, object]:
+    workspace_id, _ = _identity(request)
+    return await _social(request).analytics.post(workspace_id, post_id)

app/container.py

@@ -3,6 +3,10 @@ from __future__ import annotations
 from dataclasses import dataclass
 
 from app.core.config import Settings
+from app.security.audit import AuditService
+from app.security.database import SecurityDatabase
+from app.security.rate_limit import APIKeyRateLimiter
+from app.security.service import APIKeyService
 from app.services.cleanup import CleanupService
 from app.services.downloader import Downloader
 from app.services.ffmpeg_service import FFmpegService
@@ -12,10 +16,25 @@ from app.services.media_service import MediaProcessor
 from app.services.validator import MediaValidator
 from app.services.whisper_service import WhisperService
 from app.services.ytdlp_service import YTDLPService
-from app.security.audit import AuditService
-from app.security.database import SecurityDatabase
-from app.security.rate_limit import APIKeyRateLimiter
-from app.security.service import APIKeyService
+from app.social.database import SocialDatabase
+from app.social.oauth.encryption import TokenCipher
+from app.social.oauth.state import OAuthStateService
+from app.social.providers.registry import build_provider_registry
+from app.social.repositories.accounts import AccountRepository
+from app.social.repositories.assets import SocialMediaAssetRepository
+from app.social.repositories.jobs import JobRepository
+from app.social.repositories.posts import PostRepository
+from app.social.repositories.tokens import TokenRepository
+from app.social.services.account_service import AccountService
+from app.social.services.analytics_service import AnalyticsService
+from app.social.services.audit_service import SocialAuditService
+from app.social.services.job_service import JobService
+from app.social.services.media_asset_service import SocialMediaAssetService
+from app.social.services.oauth_service import OAuthService
+from app.social.services.publishing_service import PublishingService
+from app.social.services.scheduling_service import SchedulingService
+from app.social.services.social_service import SocialService
+from app.social.services.token_service import TokenService
 from app.templates.executor import OperationExecutor, TemplateExecutor
 from app.templates.loader import TemplateLoader
 from app.templates.registry import TemplateRegistry
@@ -40,6 +59,7 @@ class Container:
     api_keys: APIKeyService
     rate_limiter: APIKeyRateLimiter
     audit: AuditService
+    social: SocialService
 
 
 def build_container(settings: Settings) -> Container:
@@ -47,6 +67,8 @@ def build_container(settings: Settings) -> Container:
     api_keys = APIKeyService(security_database, settings)
     rate_limiter = APIKeyRateLimiter(security_database)
     audit = AuditService(security_database)
+    # Social publishing validates the same file-backed outputs as the normal
+    # media pipeline, so build those shared services before wiring Social.
     cleanup = CleanupService(settings)
     validator = MediaValidator(settings)
     downloader = Downloader(settings, validator)
@@ -54,6 +76,48 @@ def build_container(settings: Settings) -> Container:
     ffmpeg = FFmpegService(settings)
     ffprobe = FFprobeService(settings)
     whisper = WhisperService(settings)
+    social_database = SocialDatabase(settings)
+    providers = build_provider_registry(settings)
+    account_repository = AccountRepository(social_database)
+    post_repository = PostRepository(social_database)
+    token_cipher = TokenCipher(
+        settings.social_oauth_encryption_key.get_secret_value()
+        if settings.social_oauth_encryption_key
+        else None
+    )
+    job_repository = JobRepository(social_database, token_cipher)
+    token_service = TokenService(
+        TokenRepository(social_database),
+        settings,
+        token_cipher,
+    )
+    account_service = AccountService(account_repository, token_service, providers)
+    social_audit = SocialAuditService(social_database)
+    oauth_service = OAuthService(
+        settings,
+        providers,
+        OAuthStateService(social_database, token_service.cipher),
+        account_service,
+        social_audit,
+    )
+    social_media_assets = SocialMediaAssetService(
+        SocialMediaAssetRepository(social_database), cleanup, ffprobe, validator
+    )
+    social = SocialService(
+        settings=settings,
+        database=social_database,
+        accounts=account_service,
+        oauth=oauth_service,
+        publishing=PublishingService(
+            settings, post_repository, job_repository, account_repository, providers,
+            social_media_assets, oauth_service,
+        ),
+        scheduling=SchedulingService(post_repository, social_media_assets),
+        jobs=JobService(job_repository),
+        media_assets=social_media_assets,
+        analytics=AnalyticsService(social_database, account_repository, providers, oauth_service),
+        audit=social_audit,
+    )
     resolver = InputResolver(settings, cleanup, downloader, ytdlp, validator)
     processor = MediaProcessor(
         settings, resolver, cleanup, validator, ffmpeg, ffprobe, ytdlp, whisper
@@ -81,4 +145,5 @@ def build_container(settings: Settings) -> Container:
         api_keys=api_keys,
         rate_limiter=rate_limiter,
         audit=audit,
+        social=social,
     )

app/core/config.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
+import re
 from functools import lru_cache
 from pathlib import Path
+from urllib.parse import urlparse
 
 from pydantic import Field, SecretStr, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
@@ -52,6 +54,59 @@ class Settings(BaseSettings):
     )
     auth_trust_proxy_headers: bool = True
     mcp_stdio_api_key: SecretStr | None = None
+    # Social Automation foundation. The existing database remains the default
+    # local store; production Supabase/Postgres deployments should set a
+    # dedicated async SQLAlchemy URL and apply the SQL migration out-of-band.
+    social_enabled: bool = True
+    social_database_url: str = ""
+    social_auto_migrate: bool = False
+    social_worker_enabled: bool = True
+    social_scheduler_interval_seconds: int = Field(default=30, ge=5, le=3600)
+    social_job_stale_after_seconds: int = Field(default=900, ge=60, le=86_400)
+    social_publish_retry_limit: int = Field(default=5, ge=0, le=20)
+    social_oauth_requests_per_hour: int = Field(default=30, ge=1, le=100_000)
+    social_publish_requests_per_minute: int = Field(default=30, ge=1, le=100_000)
+    social_schedule_requests_per_minute: int = Field(default=60, ge=1, le=100_000)
+    social_analytics_requests_per_minute: int = Field(default=120, ge=1, le=100_000)
+    social_oauth_encryption_key: SecretStr | None = None
+    supabase_url: str = ""
+    supabase_service_role_key: SecretStr | None = None
+    supabase_vault_enabled: bool = False
+    google_client_id: str = ""
+    google_client_secret: SecretStr | None = None
+    youtube_upload_chunk_bytes: int = Field(default=8 * 1024 * 1024, ge=256 * 1024)
+    youtube_max_concurrent_uploads: int = Field(default=2, ge=1, le=32)
+    youtube_request_timeout_seconds: float = Field(default=60.0, gt=0, le=600)
+    youtube_processing_poll_seconds: int = Field(default=30, ge=5, le=3600)
+    meta_client_id: str = ""
+    meta_client_secret: SecretStr | None = None
+    # META_APP_* is the public configuration contract. META_CLIENT_* remains
+    # supported for deployments created during the social foundation phase.
+    meta_app_id: str = ""
+    meta_app_secret: SecretStr | None = None
+    meta_graph_api_version: str = "v25.0"
+    tiktok_client_key: str = ""
+    tiktok_client_secret: SecretStr | None = None
+    # Exact, backend-owned OAuth callback registered in TikTok Login Kit.
+    # This is intentionally separate from the secret and is never a frontend
+    # configuration value.
+    tiktok_redirect_uri: str = ""
+    # Direct Post requires TikTok Content Posting approval and an audited app.
+    # Keep it fail-closed until an operator has confirmed that access.
+    tiktok_direct_post_enabled: bool = False
+    tiktok_upload_chunk_bytes: int = Field(
+        default=10_000_000, ge=5_000_000, le=64_000_000
+    )
+    tiktok_request_timeout_seconds: float = Field(default=60.0, gt=0, le=600)
+    tiktok_processing_poll_seconds: int = Field(default=30, ge=5, le=3600)
+    linkedin_client_id: str = ""
+    linkedin_client_secret: SecretStr | None = None
+    x_client_id: str = ""
+    x_client_secret: SecretStr | None = None
+    telegram_bot_token: SecretStr | None = None
+    whatsapp_client_id: str = ""
+    whatsapp_client_secret: SecretStr | None = None
+    social_oauth_redirect_base_url: str = ""
 
     @field_validator("whisper_model")
     @classmethod
@@ -74,14 +129,28 @@ class Settings(BaseSettings):
         self.temp_dir.mkdir(parents=True, exist_ok=True)
         self.output_dir.mkdir(parents=True, exist_ok=True)
         sqlite_prefixes = ("sqlite+aiosqlite:///", "sqlite:///")
-        for prefix in sqlite_prefixes:
-            if self.database_url.startswith(prefix):
-                database_path = self.database_url.removeprefix(prefix)
-                if database_path and database_path != ":memory:":
-                    Path(database_path).expanduser().resolve().parent.mkdir(
-                        parents=True, exist_ok=True
-                    )
-                break
+        for url in {self.database_url, self.resolved_social_database_url}:
+            for prefix in sqlite_prefixes:
+                if url.startswith(prefix):
+                    database_path = url.removeprefix(prefix)
+                    if database_path and database_path != ":memory:":
+                        Path(database_path).expanduser().resolve().parent.mkdir(
+                            parents=True, exist_ok=True
+                        )
+                    break
+
+    @property
+    def resolved_social_database_url(self) -> str:
+        """Use an explicit social database when configured, otherwise local DB."""
+        return self.social_database_url.strip() or self.database_url
+
+    @property
+    def resolved_meta_app_id(self) -> str:
+        return self.meta_app_id.strip() or self.meta_client_id.strip()
+
+    @property
+    def resolved_meta_app_secret(self) -> SecretStr | None:
+        return self.meta_app_secret or self.meta_client_secret
 
     @field_validator("auth_bootstrap_environment")
     @classmethod
@@ -91,6 +160,46 @@ class Settings(BaseSettings):
             raise ValueError("AUTH_BOOTSTRAP_ENVIRONMENT must be live or test")
         return normalized
 
+    @field_validator("youtube_upload_chunk_bytes")
+    @classmethod
+    def validate_youtube_chunk_size(cls, value: int) -> int:
+        # Google resumable uploads require every non-final chunk to be aligned
+        # to 256 KiB. Keeping the constraint at configuration time avoids a
+        # late failure after an upload session was already created.
+        if value % (256 * 1024):
+            raise ValueError("YOUTUBE_UPLOAD_CHUNK_BYTES must be a multiple of 262144")
+        return value
+
+    @field_validator("meta_graph_api_version")
+    @classmethod
+    def validate_meta_graph_api_version(cls, value: str) -> str:
+        normalized = value.strip()
+        if not re.fullmatch(r"v[0-9]+\.[0-9]+", normalized):
+            raise ValueError("META_GRAPH_API_VERSION must use the form vNN.N")
+        return normalized
+
+    @field_validator("tiktok_redirect_uri")
+    @classmethod
+    def validate_tiktok_redirect_uri(cls, value: str) -> str:
+        normalized = value.strip()
+        if not normalized:
+            return ""
+        parsed = urlparse(normalized)
+        local_hosts = {"localhost", "127.0.0.1", "::1"}
+        if (
+            not parsed.netloc
+            or parsed.username
+            or parsed.password
+            or parsed.query
+            or parsed.fragment
+            or parsed.path != "/v1/social/accounts/tiktok/callback"
+            or (parsed.scheme != "https" and parsed.hostname not in local_hosts)
+        ):
+            raise ValueError(
+                "TIKTOK_REDIRECT_URI must be the HTTPS MediaRouter TikTok callback URI"
+            )
+        return normalized
+
 
 @lru_cache
 def get_settings() -> Settings:

app/core/logger.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import contextvars
 import json
 import logging
+import re
 import sys
 from datetime import datetime, timezone
 from typing import Any, TextIO
@@ -16,29 +17,75 @@ class JsonFormatter(logging.Formatter):
     """One-line structured JSON logs suitable for container log collectors."""
 
     _standard = set(logging.makeLogRecord({}).__dict__) | {"message", "asctime"}
+    _sensitive_keys = frozenset(
+        {
+            "access_token",
+            "refresh_token",
+            "id_token",
+            "authorization",
+            "client_secret",
+            "secret",
+            "password",
+            "api_key",
+            "credential",
+            "cookie",
+        }
+    )
+    _bearer = re.compile(r"(?i)\bbearer\s+[A-Za-z0-9._~+/=-]+")
+    _assigned_secret = re.compile(
+        r"(?i)(access[_-]?token|refresh[_-]?token|id[_-]?token|client[_-]?secret|"
+        r"authorization|api[_-]?key|password|secret|credential)"
+        r"([\"']?\s*[:=]\s*[\"']?)([^\"'\s,&}]+)"
+    )
 
     def format(self, record: logging.LogRecord) -> str:
         payload: dict[str, Any] = {
             "timestamp": datetime.now(timezone.utc).isoformat(),
             "level": record.levelname,
             "logger": record.name,
-            "message": record.getMessage(),
+            "message": self._redact_text(record.getMessage()),
             "request_id": getattr(record, "request_id", request_id_context.get()),
         }
         for key, value in record.__dict__.items():
             if key not in self._standard and not key.startswith("_"):
-                payload[key] = self._json_safe(value)
+                payload[key] = self._json_safe(value, key=key)
         if record.exc_info:
-            payload["exception"] = self.formatException(record.exc_info)
+            payload["exception"] = self._redact_text(
+                self.formatException(record.exc_info)
+            )
         return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
 
-    @staticmethod
-    def _json_safe(value: Any) -> Any:
+    @classmethod
+    def _json_safe(cls, value: Any, *, key: str | None = None) -> Any:
+        if key is not None and cls._is_sensitive_key(key):
+            return "[REDACTED]"
+        if isinstance(value, dict):
+            return {
+                str(item_key): cls._json_safe(item, key=str(item_key))
+                for item_key, item in value.items()
+            }
+        if isinstance(value, (list, tuple, set)):
+            return [cls._json_safe(item) for item in value]
+        if isinstance(value, str):
+            return cls._redact_text(value)
         try:
             json.dumps(value)
             return value
         except (TypeError, ValueError):
-            return str(value)
+            return cls._redact_text(str(value))
+
+    @classmethod
+    def _is_sensitive_key(cls, key: str) -> bool:
+        normalized = key.strip().lower().replace("-", "_")
+        return any(part in normalized for part in cls._sensitive_keys)
+
+    @classmethod
+    def _redact_text(cls, value: str) -> str:
+        redacted = cls._bearer.sub("Bearer [REDACTED]", value)
+        return cls._assigned_secret.sub(
+            lambda match: f"{match.group(1)}{match.group(2)}[REDACTED]",
+            redacted,
+        )
 
 
 def configure_logging(stream: TextIO | None = None) -> None:

app/mcp/server.py

@@ -19,6 +19,7 @@ from app.mcp.resources import register_resources
 from app.mcp.tools.audio import register_audio_tools
 from app.mcp.tools.image import register_image_tools
 from app.mcp.tools.probe import register_probe_tools
+from app.mcp.tools.social import register_social_tools
 from app.mcp.tools.system import register_system_tools
 from app.mcp.tools.templates import register_template_tools
 from app.mcp.tools.video import register_video_tools
@@ -56,6 +57,7 @@ def create_mcp_server(container: Container) -> FastMCP[Any]:
     register_probe_tools(server, registry)
     register_system_tools(server, registry)
     register_template_tools(server, registry)
+    register_social_tools(server, registry)
     register_resources(server, registry)
     register_prompts(server)
     return server
@@ -70,6 +72,7 @@ async def run_server(transport: Literal["stdio", "streamable-http"] = "stdio") -
     server = create_mcp_server(container)
     await container.security_database.initialize()
     await container.api_keys.ensure_bootstrap_admin()
+    await container.social.initialize()
     await worker.start()
     try:
         if transport == "stdio":
@@ -116,6 +119,7 @@ async def run_server(transport: Literal["stdio", "streamable-http"] = "stdio") -
                 await uvicorn.Server(config).serve()
     finally:
         await worker.stop()
+        await container.social.close()
         await container.security_database.close()
 
 

app/mcp/tools/social.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from mcp.server.fastmcp import FastMCP
+
+from app.mcp.registry import MCPRegistry
+from app.security.context import auth_context
+from app.social.schemas.posts import SocialPostCreate
+from app.social.schemas.assets import SocialMediaAssetRegister
+from app.social.schemas.scheduling import SocialScheduleCreate
+
+
+def register_social_tools(server: FastMCP[Any], registry: MCPRegistry) -> None:
+    """Register thin MCP transports over the shared SocialService facade."""
+
+    def identity() -> str:
+        context = auth_context.get()
+        if context is None:  # _execute normally rejects this first.
+            return ""
+        return context.api_key_id
+
+    @server.tool(
+        name="social.list_providers",
+        description="List registered social providers and their explicit capabilities.",
+    )
+    async def social_list_providers() -> dict[str, Any]:
+        async def action() -> dict[str, Any]:
+            items = registry.container.social.accounts.list_providers()
+            return {"providers": [item.model_dump(mode="json") for item in items]}
+
+        return await registry.run_metadata_tool(
+            "social.list_providers", action, required_scope="social:accounts:read"
+        )
+
+    @server.tool(
+        name="social.get_capabilities",
+        description="Get capabilities and implementation status for one provider.",
+    )
+    async def social_get_capabilities(provider: str) -> dict[str, Any]:
+        async def action() -> dict[str, Any]:
+            item = registry.container.social.accounts.get_provider(provider)
+            return {"provider": item.model_dump(mode="json")}
+
+        return await registry.run_metadata_tool(
+            "social.get_capabilities", action, required_scope="social:accounts:read"
+        )
+
+    @server.tool(
+        name="social.list_media_assets",
+        description="List workspace-owned MediaRouter outputs registered for social publishing.",
+    )
+    async def social_list_media_assets(offset: int = 0, limit: int = 100) -> dict[str, Any]:
+        async def action() -> dict[str, Any]:
+            social = registry.container.social
+            social.ensure_ready()
+            items = await social.media_assets.list(identity(), offset=offset, limit=limit)
+            return {"assets": [item.model_dump(mode="json") for item in items]}
+
+        return await registry.run_metadata_tool(
+            "social.list_media_assets", action, required_scope="assets:read"
+        )
+
+    @server.tool(
+        name="social.register_media_asset",
+        description="Register an existing MediaRouter output UUID and filename for tenant-scoped social publishing.",
+    )
+    async def social_register_media_asset(request_id: str, filename: str) -> dict[str, Any]:
+        async def action() -> dict[str, Any]:
+            social = registry.container.social
+            social.ensure_ready()
+            item = await social.media_assets.register(
+                identity(),
+                SocialMediaAssetRegister(request_id=request_id, filename=filename),
+            )
+            return {"asset": item.model_dump(mode="json")}
+
+        return await registry.run_metadata_tool(
+            "social.register_media_asset", action, required_scope="assets:write"
+        )
+
+    @server.tool(name="social.list_accounts", description="List connected social accounts.")
+    async def social_list_accounts(offset: int = 0, limit: int = 100) -> dict[str, Any]:
+        async def action() -> dict[str, Any]:
+            social = registry.container.social
+            social.ensure_ready()
+            items = await social.accounts.list(identity(), offset=offset, limit=limit)
+            return {"accounts": [item.model_dump(mode="json") for item in items]}
+
+        return await registry.run_metadata_tool(
+            "social.list_accounts", action, required_scope="social:accounts:read"
+        )
+
+    @server.tool(name="social.get_account", description="Get a tenant-owned social account.")
+    async def social_get_account(account_id: str) -> dict[str, Any]:
+        async def action() -> dict[str, Any]:
+            social = registry.container.social
+            social.ensure_ready()
+            item = await social.accounts.get(identity(), account_id)
+            return {"account": item.model_dump(mode="json")}
+
+        return await registry.run_metadata_tool(
+            "social.get_account", action, required_scope="social:accounts:read"
+        )
+
+    @server.tool(name="social.create_post", description="Create a typed multi-target social post.")
+    async def social_create_post(
+        payload: dict[str, Any], idempotency_key: str | None = None
+    ) -> dict[str, Any]:
+        async def action() -> dict[str, Any]:
+            social = registry.container.social
+            social.ensure_ready()
+            user_id = identity()
+            item = await social.publishing.create(
+                workspace_id=user_id,
+                user_id=user_id,
+                payload=SocialPostCreate.model_validate(payload),
+                idempotency_key=idempotency_key,
+            )
+            await social.audit.record(
+                workspace_id=user_id,
+                api_key_id=user_id,
+                event_type="SOCIAL_POST_CREATED",
+                social_post_id=item.id,
+            )
+            return {"post": item.model_dump(mode="json")}
+
+        return await registry.run_metadata_tool(
+            "social.create_post", action, required_scope="social:posts:write"
+        )
+
+    @server.tool(name="social.publish_post", description="Queue an idempotent social post publication.")
+    async def social_publish_post(post_id: str, idempotency_key: str) -> dict[str, Any]:
+        async def action() -> dict[str, Any]:
+            social = registry.container.social
+            social.ensure_ready()
+            jobs = await social.publishing.queue(
+                identity(), post_id, idempotency_key=idempotency_key
+            )
+            return {"jobs": [job.model_dump(mode="json") for job in jobs]}
+
+        return await registry.run_metadata_tool(
+            "social.publish_post", action, required_scope="social:posts:publish"
+        )
+
+    @server.tool(name="social.schedule_post", description="Schedule a social post using an aware timestamp and IANA timezone.")
+    async def social_schedule_post(
+        post_id: str, scheduled_at: str, timezone: str
+    ) -> dict[str, Any]:
+        async def action() -> dict[str, Any]:
+            social = registry.container.social
+            social.ensure_ready()
+            schedule = await social.scheduling.schedule(
+                identity(),
+                post_id,
+                SocialScheduleCreate(
+                    scheduled_at=scheduled_at,  # type: ignore[arg-type]
+                    timezone=timezone,
+                ),
+            )
+            return {"schedule": schedule.model_dump(mode="json")}
+
+        return await registry.run_metadata_tool(
+            "social.schedule_post", action, required_scope="social:schedules:write"
+        )
+
+    @server.tool(name="social.cancel_post", description="Cancel a scheduled or active social post.")
+    async def social_cancel_post(post_id: str) -> dict[str, Any]:
+        async def action() -> dict[str, Any]:
+            social = registry.container.social
+            social.ensure_ready()
+            item = await social.publishing.cancel(identity(), post_id)
+            return {"post": item.model_dump(mode="json")}
+
+        return await registry.run_metadata_tool(
+            "social.cancel_post", action, required_scope="social:posts:write"
+        )
+
+    @server.tool(name="social.get_post", description="Get a multi-target social post and target states.")
+    async def social_get_post(post_id: str) -> dict[str, Any]:
+        async def action() -> dict[str, Any]:
+            social = registry.container.social
+            social.ensure_ready()
+            item = await social.publishing.get(identity(), post_id)
+            return {"post": item.model_dump(mode="json")}
+
+        return await registry.run_metadata_tool(
+            "social.get_post", action, required_scope="social:posts:read"
+        )
+
+    @server.tool(name="social.get_job", description="Get a durable social publishing job.")
+    async def social_get_job(job_id: str) -> dict[str, Any]:
+        async def action() -> dict[str, Any]:
+            social = registry.container.social
+            social.ensure_ready()
+            item = await social.jobs.get(identity(), job_id)
+            return {"job": item.model_dump(mode="json")}
+
+        return await registry.run_metadata_tool(
+            "social.get_job", action, required_scope="social:posts:read"
+        )
+
+    @server.tool(name="social.get_analytics", description="Get normalized metrics for an account or post.")
+    async def social_get_analytics(
+        resource: Literal["account", "post"], resource_id: str
+    ) -> dict[str, Any]:
+        async def action() -> dict[str, Any]:
+            social = registry.container.social
+            social.ensure_ready()
+            if resource == "account":
+                return await social.analytics.account(identity(), resource_id)
+            return await social.analytics.post(identity(), resource_id)
+
+        return await registry.run_metadata_tool(
+            "social.get_analytics", action, required_scope="social:analytics:read"
+        )

app/security/middleware.py

@@ -68,6 +68,7 @@ class APIKeyAuthenticationMiddleware(BaseHTTPMiddleware):
                 uploaded_bytes=bytes_uploaded,
             )
             self.api_keys.authorize(context, required_scope)
+            await self._apply_social_rate_limit(request, context)
             await self.api_keys.mark_used(context)
             http_auth_token = http_auth_applied.set(True)
             response = await call_next(request)
@@ -120,6 +121,41 @@ class APIKeyAuthenticationMiddleware(BaseHTTPMiddleware):
                     bytes_downloaded,
                 )
 
+    async def _apply_social_rate_limit(
+        self, request: Request, context: AuthContext
+    ) -> None:
+        path = request.url.path
+        if not path.startswith("/v1/social"):
+            return
+        if "/analytics" in path:
+            await self.rate_limiter.acquire_category(
+                context,
+                "social_analytics",
+                limit=self.settings.social_analytics_requests_per_minute,
+                window_seconds=60,
+            )
+        elif path.endswith("/connect") or path.endswith("/callback") or path.endswith("/refresh"):
+            await self.rate_limiter.acquire_category(
+                context,
+                "social_oauth",
+                limit=self.settings.social_oauth_requests_per_hour,
+                window_seconds=3600,
+            )
+        elif path.endswith("/publish"):
+            await self.rate_limiter.acquire_category(
+                context,
+                "social_publish",
+                limit=self.settings.social_publish_requests_per_minute,
+                window_seconds=60,
+            )
+        elif path.endswith("/schedule"):
+            await self.rate_limiter.acquire_category(
+                context,
+                "social_schedule",
+                limit=self.settings.social_schedule_requests_per_minute,
+                window_seconds=60,
+            )
+
     @staticmethod
     def _bearer_token(header: str | None) -> str:
         if not header:

app/security/policy.py

@@ -14,13 +14,26 @@ class ScopePolicy:
 
     @staticmethod
     def is_public(request: Request) -> bool:
-        return request.method == "GET" and request.url.path in PUBLIC_GET_PATHS
+        path = request.url.path
+        callback_segments = tuple(segment for segment in path.split("/") if segment)
+        return request.method == "GET" and (
+            path in PUBLIC_GET_PATHS
+            # OAuth callbacks deliberately rely on a single-use, short-lived
+            # state record instead of an API key that a provider cannot send.
+            # Keep this exemption exact: no nested route may accidentally
+            # inherit callback's public status.
+            or callback_segments[:3] == ("v1", "social", "accounts")
+            and len(callback_segments) == 5
+            and callback_segments[-1] == "callback"
+        )
 
     async def required_scope(self, request: Request) -> str | None:
         path = request.url.path
         method = request.method
         if path == "/v1/auth/context":
             return None
+        if path.startswith("/v1/social"):
+            return self._social_scope(path, method)
         if path.startswith("/mcp"):
             return await self._mcp_scope(request)
         if path.startswith("/v1/api-keys") or path.startswith("/v1/audit-logs"):
@@ -53,6 +66,28 @@ class ScopePolicy:
             return "system:read"
         return "admin"
 
+    @staticmethod
+    def _social_scope(path: str, method: str) -> str:
+        if "/assets" in path:
+            return "assets:read" if method == "GET" else "assets:write"
+        if "/analytics" in path:
+            return "social:analytics:read"
+        if "/jobs" in path:
+            return "social:posts:read"
+        if "/accounts" in path:
+            return "social:accounts:read" if method == "GET" else "social:accounts:write"
+        if "/posts" in path:
+            if method == "GET":
+                return "social:posts:read"
+            if path.endswith("/publish"):
+                return "social:posts:publish"
+            if path.endswith("/schedule"):
+                return "social:schedules:write"
+            if path.endswith("/cancel"):
+                return "social:posts:write"
+            return "social:posts:write"
+        return "social:accounts:read"
+
     @staticmethod
     async def _mcp_scope(request: Request) -> str:
         if request.method != "POST":
@@ -76,6 +111,7 @@ class ScopePolicy:
             "operations:execute",
             "jobs:create",
             "mcp:execute",
+            "social:posts:publish",
         }
 
     @staticmethod

app/security/rate_limit.py

@@ -36,6 +36,7 @@ class APIKeyRateLimiter:
         self._uploads: dict[str, deque[float]] = defaultdict(deque)
         self._concurrent: dict[str, int] = defaultdict(int)
         self._daily_bytes: dict[tuple[str, str], int] = defaultdict(int)
+        self._categories: dict[tuple[str, str], deque[float]] = defaultdict(deque)
 
     async def acquire(
         self,
@@ -96,6 +97,30 @@ class APIKeyRateLimiter:
         async with self._lock:
             self._concurrent[api_key_id] = max(0, self._concurrent[api_key_id] - 1)
 
+    async def acquire_category(
+        self,
+        context: AuthContext,
+        category: str,
+        *,
+        limit: int,
+        window_seconds: int,
+    ) -> None:
+        """Reserve an independent social-operation bucket for a key.
+
+        Generic API limits still apply in middleware. These smaller buckets
+        prevent OAuth, publishing, scheduling, and analytics traffic from
+        starving each other when the social subsystem is enabled.
+        """
+        now = time.time()
+        key = (context.api_key_id, category)
+        async with self._lock:
+            values = self._categories[key]
+            self._prune(values, now - window_seconds)
+            if len(values) >= limit:
+                raise RateLimitError(max(1, math.ceil(values[0] + window_seconds - now)))
+            values.append(now)
+        await self._record(context.api_key_id, category, 1, 0, window_seconds)
+
     @staticmethod
     def _prune(values: deque[float], cutoff: float) -> None:
         while values and values[0] <= cutoff:

app/security/scopes.py

@@ -17,6 +17,14 @@ ALL_SCOPES = frozenset(
         "mcp:read",
         "mcp:execute",
         "system:read",
+        "social:accounts:read",
+        "social:accounts:write",
+        "social:posts:read",
+        "social:posts:write",
+        "social:posts:publish",
+        "social:schedules:read",
+        "social:schedules:write",
+        "social:analytics:read",
         "admin",
     }
 )
@@ -37,6 +45,14 @@ DEFAULT_ROLE_SCOPES: dict[str, frozenset[str]] = {
             "mcp:read",
             "mcp:execute",
             "system:read",
+            "social:accounts:read",
+            "social:accounts:write",
+            "social:posts:read",
+            "social:posts:write",
+            "social:posts:publish",
+            "social:schedules:read",
+            "social:schedules:write",
+            "social:analytics:read",
         }
     ),
     "operator": frozenset(
@@ -52,6 +68,14 @@ DEFAULT_ROLE_SCOPES: dict[str, frozenset[str]] = {
             "mcp:read",
             "mcp:execute",
             "system:read",
+            "social:accounts:read",
+            "social:accounts:write",
+            "social:posts:read",
+            "social:posts:write",
+            "social:posts:publish",
+            "social:schedules:read",
+            "social:schedules:write",
+            "social:analytics:read",
         }
     ),
     "viewer": frozenset(
@@ -62,6 +86,10 @@ DEFAULT_ROLE_SCOPES: dict[str, frozenset[str]] = {
             "assets:read",
             "mcp:read",
             "system:read",
+            "social:accounts:read",
+            "social:posts:read",
+            "social:schedules:read",
+            "social:analytics:read",
         }
     ),
 }

app/social/__init__.py

@@ -0,0 +1,5 @@
+"""MediaRouter Social Automation bounded domain."""
+
+from app.social.services.social_service import SocialService
+
+__all__ = ["SocialService"]

app/social/database.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from sqlalchemy import event, inspect, text
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+
+from app.core.config import Settings
+from app.social.models import SocialBase
+
+REQUIRED_SOCIAL_TABLES = frozenset(
+    {
+        "social_accounts",
+        "social_account_tokens",
+        "social_account_capabilities",
+        "media_variants",
+        "social_media_assets",
+        "social_campaigns",
+        "social_posts",
+        "social_post_targets",
+        "social_post_media",
+        "social_schedules",
+        "social_jobs",
+        "social_job_attempts",
+        "oauth_states",
+        "social_webhook_events",
+        "social_post_metrics",
+        "social_audit_events",
+    }
+)
+
+
+class SocialDatabase:
+    """Social persistence with migration-only production schema changes."""
+
+    def __init__(self, settings: Settings) -> None:
+        self.settings = settings
+        self.database_url = settings.resolved_social_database_url
+        self.engine: AsyncEngine = create_async_engine(self.database_url, pool_pre_ping=True)
+        if self.database_url.startswith("sqlite"):
+            event.listen(self.engine.sync_engine, "connect", self._configure_sqlite)
+        self.session_factory = async_sessionmaker(self.engine, expire_on_commit=False, class_=AsyncSession)
+
+    @staticmethod
+    def _configure_sqlite(dbapi_connection: object, _record: object) -> None:
+        cursor = dbapi_connection.cursor()  # type: ignore[attr-defined]
+        cursor.execute("PRAGMA foreign_keys=ON")
+        cursor.execute("PRAGMA busy_timeout=5000")
+        cursor.close()
+
+    async def initialize(self) -> None:
+        if self.settings.social_auto_migrate:
+            async with self.engine.begin() as connection:
+                await connection.run_sync(SocialBase.metadata.create_all)
+
+    async def schema_ready(self) -> bool:
+        """Check the complete Phase 1 schema without changing the database."""
+        async with self.engine.connect() as connection:
+            tables = await connection.run_sync(
+                lambda sync: set(inspect(sync).get_table_names())
+            )
+        return REQUIRED_SOCIAL_TABLES.issubset(tables)
+
+    async def missing_tables(self) -> list[str]:
+        """Return absent required tables for an actionable startup warning."""
+        async with self.engine.connect() as connection:
+            tables = await connection.run_sync(
+                lambda sync: set(inspect(sync).get_table_names())
+            )
+        return sorted(REQUIRED_SOCIAL_TABLES - tables)
+
+    async def close(self) -> None:
+        await self.engine.dispose()
+
+    @asynccontextmanager
+    async def session(self, workspace_id: str | None = None) -> AsyncIterator[AsyncSession]:
+        async with self.session_factory() as session:
+            if workspace_id and self.database_url.startswith(("postgresql", "postgres")):
+                # RLS policies read this transaction-local tenant identity.
+                await session.execute(
+                    text("select set_config('app.workspace_id', :workspace_id, true)"),
+                    {"workspace_id": workspace_id},
+                )
+            yield session

app/social/domain/__init__.py

@@ -0,0 +1,12 @@
+from app.social.domain.capabilities import ProviderCapabilities
+from app.social.domain.enums import ConnectionStrategy, JobStatus, PostStatus, Provider
+from app.social.domain.errors import SocialError
+
+__all__ = [
+    "ConnectionStrategy",
+    "JobStatus",
+    "PostStatus",
+    "Provider",
+    "ProviderCapabilities",
+    "SocialError",
+]

app/social/domain/capabilities.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from app.social.domain.enums import ConnectionStrategy, Provider
+
+
+class ProviderCapabilities(BaseModel):
+    """Provider metadata consumed by every transport and UI."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    provider: Provider
+    connection_strategy: ConnectionStrategy
+    video: bool = False
+    video_upload: bool = False
+    video_status: bool = False
+    channel_metadata: bool = False
+    image: bool = False
+    carousel: bool = False
+    direct_publish: bool = False
+    draft_upload: bool = False
+    scheduled_publish: bool = False
+    native_scheduling: bool = False
+    analytics: bool = False
+    delete_post: bool = False
+    personal_publishing: bool = False
+    organization_publishing: bool = False
+    implementation_status: str = "foundation"
+    account_types: list[str] = Field(default_factory=list)
+    required_scopes: list[str] = Field(default_factory=list)
+    optional_scopes: list[str] = Field(default_factory=list)
+    # Publishing access is requested only after an explicit user action. This
+    # prevents provider-product approval scopes from being silently added to a
+    # foundation/account-discovery connection.
+    publishing_required_scopes: list[str] = Field(default_factory=list)
+    # Additional authorization is always opt-in. These scopes are never
+    # appended to a normal OAuth connection request.
+    analytics_required_scopes: list[str] = Field(default_factory=list)
+    # Transport-neutral metadata consumed by dynamic clients. Provider-owned
+    # runtime choices are fetched from the account publish-options endpoint.
+    publish_metadata_schema: dict[str, object] = Field(default_factory=dict)
+
+    @property
+    def publish_supported(self) -> bool:
+        return self.direct_publish or self.draft_upload

app/social/domain/enums.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class Provider(StrEnum):
+    YOUTUBE = "youtube"
+    FACEBOOK = "facebook"
+    INSTAGRAM = "instagram"
+    TIKTOK = "tiktok"
+    X = "x"
+    LINKEDIN = "linkedin"
+    TELEGRAM = "telegram"
+    WHATSAPP = "whatsapp"
+
+
+class ConnectionStrategy(StrEnum):
+    OAUTH = "oauth"
+    TOKEN_BOT = "token_bot"
+    BUSINESS_API = "business_api"
+
+
+class AccountStatus(StrEnum):
+    PENDING = "pending"
+    CONNECTED = "connected"
+    REAUTH_REQUIRED = "reauth_required"
+    DISCONNECTED = "disconnected"
+    ERROR = "error"
+
+
+class PostStatus(StrEnum):
+    DRAFT = "draft"
+    SCHEDULED = "scheduled"
+    QUEUED = "queued"
+    PREPARING = "preparing"
+    PROCESSING = "processing"
+    UPLOADING = "uploading"
+    PUBLISHING = "publishing"
+    PUBLISHED = "published"
+    PARTIAL_SUCCESS = "partial_success"
+    RETRYING = "retrying"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class JobStatus(StrEnum):
+    DRAFT = "draft"
+    SCHEDULED = "scheduled"
+    QUEUED = "queued"
+    PREPARING = "preparing"
+    PROCESSING = "processing"
+    UPLOADING = "uploading"
+    PUBLISHING = "publishing"
+    PUBLISHED = "published"
+    RETRYING = "retrying"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class PublishMode(StrEnum):
+    NOW = "now"
+    SCHEDULE = "schedule"
+    DRAFT = "draft"
+
+
+TERMINAL_JOB_STATUSES = frozenset(
+    {JobStatus.PUBLISHED, JobStatus.FAILED, JobStatus.CANCELLED}
+)

app/social/domain/errors.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from app.core.exceptions import MediaAPIError
+
+
+class SocialError(MediaAPIError):
+    code = "SOCIAL_ERROR"
+    status_code = 400
+
+
+class SocialProviderUnavailableError(SocialError):
+    code = "SOCIAL_PROVIDER_UNAVAILABLE"
+    status_code = 503
+
+
+class SocialProviderNotImplementedError(SocialError):
+    code = "SOCIAL_PROVIDER_NOT_IMPLEMENTED"
+    status_code = 501
+
+
+class SocialAccountNotFoundError(SocialError):
+    code = "SOCIAL_ACCOUNT_NOT_FOUND"
+    status_code = 404
+
+
+class SocialAccountDisconnectedError(SocialError):
+    code = "SOCIAL_ACCOUNT_DISCONNECTED"
+    status_code = 409
+
+
+class SocialReauthRequiredError(SocialError):
+    code = "SOCIAL_REAUTH_REQUIRED"
+    status_code = 401
+
+
+class SocialPermissionDeniedError(SocialError):
+    code = "SOCIAL_PERMISSION_DENIED"
+    status_code = 403
+
+
+class SocialCapabilityUnsupportedError(SocialError):
+    code = "SOCIAL_CAPABILITY_UNSUPPORTED"
+    status_code = 422
+
+
+class SocialMediaInvalidError(SocialError):
+    code = "SOCIAL_MEDIA_INVALID"
+    status_code = 422
+
+
+class SocialRateLimitedError(SocialError):
+    code = "SOCIAL_RATE_LIMITED"
+    status_code = 429
+
+
+class SocialProviderQuotaError(SocialError):
+    code = "SOCIAL_PROVIDER_QUOTA_EXCEEDED"
+    status_code = 429
+
+
+class SocialPostNotFoundError(SocialError):
+    code = "SOCIAL_POST_NOT_FOUND"
+    status_code = 404
+
+
+class SocialJobNotFoundError(SocialError):
+    code = "SOCIAL_JOB_NOT_FOUND"
+    status_code = 404
+
+
+class SocialPublishFailedError(SocialError):
+    code = "SOCIAL_PUBLISH_FAILED"
+    status_code = 422
+
+
+class SocialJobFailedError(SocialError):
+    code = "SOCIAL_JOB_FAILED"
+    status_code = 422
+
+
+class SocialIdempotencyConflictError(SocialError):
+    code = "SOCIAL_IDEMPOTENCY_CONFLICT"
+    status_code = 409
+
+
+class SocialOAuthStateError(SocialError):
+    code = "SOCIAL_OAUTH_STATE_INVALID"
+    status_code = 400
+
+
+class SocialTransitionError(SocialError):
+    code = "SOCIAL_INVALID_STATE_TRANSITION"
+    status_code = 409

app/social/domain/models.py

@@ -0,0 +1,24 @@
+from app.social.models import (
+    MediaVariant,
+    SocialMediaAsset,
+    OAuthState,
+    SocialAccount,
+    SocialAccountCapability,
+    SocialAccountToken,
+    SocialCampaign,
+    SocialJob,
+    SocialJobAttempt,
+    SocialPost,
+    SocialPostMedia,
+    SocialPostMetric,
+    SocialPostTarget,
+    SocialSchedule,
+    SocialWebhookEvent,
+)
+
+__all__ = [
+    "MediaVariant", "SocialMediaAsset", "OAuthState", "SocialAccount", "SocialAccountCapability",
+    "SocialAccountToken", "SocialCampaign", "SocialJob", "SocialJobAttempt",
+    "SocialPost", "SocialPostMedia", "SocialPostMetric", "SocialPostTarget",
+    "SocialSchedule", "SocialWebhookEvent",
+]

app/social/domain/retry.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+RETRYABLE_STATUS_CODES = frozenset({429, 500, 502, 503, 504})
+BACKOFF_SECONDS = (0, 10, 30, 120, 600)
+
+
+@dataclass(frozen=True, slots=True)
+class RetryDecision:
+    retryable: bool
+    refresh_token_first: bool = False
+    delay_seconds: int = 0
+
+
+def classify_retry(*, status_code: int | None = None, network_error: bool = False, attempt: int = 1) -> RetryDecision:
+    delay = BACKOFF_SECONDS[min(max(attempt - 1, 0), len(BACKOFF_SECONDS) - 1)]
+    if network_error or status_code in RETRYABLE_STATUS_CODES:
+        return RetryDecision(True, delay_seconds=delay)
+    if status_code == 401:
+        return RetryDecision(attempt <= 1, refresh_token_first=True, delay_seconds=0)
+    return RetryDecision(False)

app/social/domain/state_machine.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from app.social.domain.enums import JobStatus
+from app.social.domain.errors import SocialTransitionError
+
+ALLOWED_TRANSITIONS: dict[JobStatus, frozenset[JobStatus]] = {
+    JobStatus.DRAFT: frozenset({JobStatus.SCHEDULED, JobStatus.QUEUED, JobStatus.CANCELLED}),
+    JobStatus.SCHEDULED: frozenset({JobStatus.QUEUED, JobStatus.CANCELLED}),
+    JobStatus.QUEUED: frozenset({JobStatus.PREPARING, JobStatus.CANCELLED}),
+    JobStatus.PREPARING: frozenset({JobStatus.PROCESSING, JobStatus.UPLOADING, JobStatus.RETRYING, JobStatus.FAILED, JobStatus.CANCELLED}),
+    JobStatus.PROCESSING: frozenset({JobStatus.UPLOADING, JobStatus.RETRYING, JobStatus.FAILED, JobStatus.CANCELLED}),
+    JobStatus.UPLOADING: frozenset({JobStatus.PUBLISHING, JobStatus.RETRYING, JobStatus.FAILED, JobStatus.CANCELLED}),
+    JobStatus.PUBLISHING: frozenset({JobStatus.PUBLISHED, JobStatus.RETRYING, JobStatus.FAILED, JobStatus.CANCELLED}),
+    JobStatus.RETRYING: frozenset({JobStatus.PREPARING, JobStatus.PROCESSING, JobStatus.UPLOADING, JobStatus.PUBLISHING, JobStatus.FAILED, JobStatus.CANCELLED}),
+    JobStatus.PUBLISHED: frozenset(),
+    JobStatus.FAILED: frozenset(),
+    JobStatus.CANCELLED: frozenset(),
+}
+
+
+def validate_transition(current: str | JobStatus, target: str | JobStatus) -> JobStatus:
+    source = JobStatus(current)
+    destination = JobStatus(target)
+    if destination not in ALLOWED_TRANSITIONS[source]:
+        raise SocialTransitionError(f"Cannot transition social job from {source} to {destination}.")
+    return destination

app/social/migrations/0001_social_foundation_postgres.sql

@@ -0,0 +1,257 @@
+-- MediaRouter Social Automation foundation (PostgreSQL / Supabase)
+-- Apply with the normal deployment migration process. Application startup
+-- intentionally does not mutate production schema.
+
+begin;
+create extension if not exists pgcrypto;
+
+create table if not exists social_accounts (
+  id text primary key default gen_random_uuid()::text,
+  workspace_id text not null,
+  provider text not null check (provider in ('youtube','facebook','instagram','tiktok','x','linkedin','telegram','whatsapp')),
+  account_type text not null,
+  external_account_id text not null,
+  username text,
+  display_name text,
+  avatar_url text,
+  status text not null default 'pending',
+  metadata jsonb not null default '{}'::jsonb,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  last_synced_at timestamptz,
+  constraint uq_social_account_workspace_provider_external unique (workspace_id, provider, external_account_id)
+);
+create index if not exists ix_social_accounts_workspace_id on social_accounts(workspace_id);
+create index if not exists ix_social_accounts_provider_status on social_accounts(provider, status);
+
+create table if not exists social_account_tokens (
+  id text primary key default gen_random_uuid()::text,
+  social_account_id text not null references social_accounts(id) on delete cascade,
+  access_token_secret_id text,
+  refresh_token_secret_id text,
+  encrypted_payload text,
+  expires_at timestamptz,
+  scopes jsonb not null default '[]'::jsonb,
+  token_type text,
+  last_refreshed_at timestamptz,
+  revoked_at timestamptz,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  constraint uq_social_account_token unique (social_account_id),
+  constraint ck_social_token_storage check (
+    encrypted_payload is not null or access_token_secret_id is not null or revoked_at is not null
+  )
+);
+create index if not exists ix_social_account_tokens_expires_at on social_account_tokens(expires_at);
+
+create table if not exists social_account_capabilities (
+  id text primary key default gen_random_uuid()::text,
+  social_account_id text not null references social_accounts(id) on delete cascade,
+  capability text not null,
+  enabled boolean not null default false,
+  metadata jsonb not null default '{}'::jsonb,
+  updated_at timestamptz not null default now(),
+  constraint uq_social_account_capability unique (social_account_id, capability)
+);
+create index if not exists ix_social_account_capabilities_account on social_account_capabilities(social_account_id);
+
+create table if not exists media_variants (
+  id text primary key default gen_random_uuid()::text,
+  workspace_id text not null,
+  source_asset_id text not null,
+  asset_reference text,
+  template_id text,
+  platform text,
+  width integer,
+  height integer,
+  duration_seconds double precision,
+  codec text,
+  container text,
+  bitrate bigint,
+  file_size bigint,
+  metadata jsonb not null default '{}'::jsonb,
+  created_at timestamptz not null default now()
+);
+create index if not exists ix_media_variants_workspace_source on media_variants(workspace_id, source_asset_id);
+create index if not exists ix_media_variants_platform on media_variants(platform);
+
+create table if not exists social_campaigns (
+  id text primary key default gen_random_uuid()::text,
+  workspace_id text not null,
+  name text not null,
+  description text,
+  status text not null default 'draft',
+  metadata jsonb not null default '{}'::jsonb,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+create index if not exists ix_social_campaigns_workspace_id on social_campaigns(workspace_id);
+
+create table if not exists social_posts (
+  id text primary key default gen_random_uuid()::text,
+  workspace_id text not null,
+  campaign_id text references social_campaigns(id) on delete set null,
+  media_asset_id text not null,
+  source_variant_id text references media_variants(id) on delete set null,
+  status text not null default 'draft',
+  publish_mode text not null default 'draft' check (publish_mode in ('now','schedule','draft')),
+  idempotency_key text,
+  request_fingerprint char(64),
+  metadata jsonb not null default '{}'::jsonb,
+  created_by text,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  published_at timestamptz,
+  constraint uq_social_posts_workspace_idempotency unique (workspace_id, idempotency_key)
+);
+create index if not exists ix_social_posts_workspace_created on social_posts(workspace_id, created_at desc);
+create index if not exists ix_social_posts_status on social_posts(status);
+
+create table if not exists social_post_targets (
+  id text primary key default gen_random_uuid()::text,
+  social_post_id text not null references social_posts(id) on delete cascade,
+  social_account_id text not null references social_accounts(id) on delete restrict,
+  provider text not null,
+  status text not null default 'draft',
+  caption jsonb not null default '{}'::jsonb,
+  platform_metadata jsonb not null default '{}'::jsonb,
+  external_post_id text,
+  external_url text,
+  error_code text,
+  error_message text,
+  published_at timestamptz,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  constraint uq_social_post_target unique (social_post_id, social_account_id)
+);
+create index if not exists ix_social_post_targets_post on social_post_targets(social_post_id);
+create index if not exists ix_social_post_targets_account on social_post_targets(social_account_id);
+create index if not exists ix_social_post_targets_status on social_post_targets(status);
+
+create table if not exists social_post_media (
+  id text primary key default gen_random_uuid()::text,
+  social_post_id text not null references social_posts(id) on delete cascade,
+  media_variant_id text references media_variants(id) on delete set null,
+  media_asset_id text,
+  position integer not null default 0,
+  kind text not null default 'video',
+  metadata jsonb not null default '{}'::jsonb,
+  created_at timestamptz not null default now()
+);
+create index if not exists ix_social_post_media_post on social_post_media(social_post_id);
+
+create table if not exists social_schedules (
+  id text primary key default gen_random_uuid()::text,
+  social_post_id text not null references social_posts(id) on delete cascade,
+  scheduled_at timestamptz not null,
+  timezone text not null,
+  status text not null default 'scheduled',
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  constraint uq_social_schedule_post unique (social_post_id)
+);
+create index if not exists ix_social_schedules_due on social_schedules(status, scheduled_at);
+
+create table if not exists social_jobs (
+  id text primary key default gen_random_uuid()::text,
+  workspace_id text not null,
+  social_post_id text not null references social_posts(id) on delete cascade,
+  social_post_target_id text references social_post_targets(id) on delete cascade,
+  provider text,
+  status text not null default 'queued',
+  attempt_count integer not null default 0,
+  max_attempts integer not null default 5,
+  next_attempt_at timestamptz,
+  idempotency_key text,
+  error_code text,
+  error_message text,
+  payload jsonb not null default '{}'::jsonb,
+  created_at timestamptz not null default now(),
+  started_at timestamptz,
+  completed_at timestamptz,
+  updated_at timestamptz not null default now(),
+  constraint uq_social_jobs_workspace_idempotency unique (workspace_id, idempotency_key)
+);
+create index if not exists ix_social_jobs_workspace_status on social_jobs(workspace_id, status);
+create index if not exists ix_social_jobs_next_attempt on social_jobs(status, next_attempt_at);
+create index if not exists ix_social_jobs_post on social_jobs(social_post_id);
+
+create table if not exists social_job_attempts (
+  id text primary key default gen_random_uuid()::text,
+  social_job_id text not null references social_jobs(id) on delete cascade,
+  attempt_number integer not null,
+  status text not null,
+  error_code text,
+  error_message text,
+  provider_request_id text,
+  started_at timestamptz not null default now(),
+  completed_at timestamptz,
+  constraint uq_social_job_attempt_number unique (social_job_id, attempt_number)
+);
+create index if not exists ix_social_job_attempts_job on social_job_attempts(social_job_id, attempt_number);
+
+create table if not exists oauth_states (
+  id text primary key default gen_random_uuid()::text,
+  state text not null unique,
+  provider text not null,
+  workspace_id text not null,
+  user_id text,
+  redirect_uri text not null,
+  code_verifier_encrypted text,
+  expires_at timestamptz not null,
+  used_at timestamptz,
+  created_at timestamptz not null default now()
+);
+create index if not exists ix_oauth_states_expires_at on oauth_states(expires_at);
+create index if not exists ix_oauth_states_workspace on oauth_states(workspace_id);
+
+create table if not exists social_webhook_events (
+  id text primary key default gen_random_uuid()::text,
+  provider text not null,
+  event_type text not null,
+  external_event_id text not null,
+  workspace_id text,
+  payload jsonb not null default '{}'::jsonb,
+  received_at timestamptz not null default now(),
+  processed_at timestamptz,
+  status text not null default 'received',
+  error_message text,
+  constraint uq_social_webhook_provider_external unique (provider, external_event_id)
+);
+create index if not exists ix_social_webhook_events_status on social_webhook_events(status);
+create index if not exists ix_social_webhook_events_received on social_webhook_events(received_at);
+
+create table if not exists social_post_metrics (
+  id text primary key default gen_random_uuid()::text,
+  social_post_id text not null references social_posts(id) on delete cascade,
+  social_post_target_id text references social_post_targets(id) on delete cascade,
+  provider text not null,
+  views bigint,
+  impressions bigint,
+  likes bigint,
+  comments bigint,
+  shares bigint,
+  engagement_rate double precision,
+  published_at timestamptz,
+  retrieved_at timestamptz not null default now(),
+  raw_metrics jsonb not null default '{}'::jsonb
+);
+create index if not exists ix_social_post_metrics_target_retrieved on social_post_metrics(social_post_target_id, retrieved_at desc);
+
+create table if not exists social_audit_events (
+  id text primary key default gen_random_uuid()::text,
+  workspace_id text not null,
+  api_key_id text,
+  event_type text not null,
+  provider text,
+  social_account_id text,
+  social_post_id text,
+  social_job_id text,
+  request_id text,
+  metadata jsonb not null default '{}'::jsonb,
+  created_at timestamptz not null default now()
+);
+create index if not exists ix_social_audit_events_workspace_created on social_audit_events(workspace_id, created_at desc);
+create index if not exists ix_social_audit_events_type on social_audit_events(event_type);
+
+commit;

app/social/migrations/0002_social_rls.sql

@@ -0,0 +1,90 @@
+-- Tenant isolation policies for the social bounded domain.
+-- The API starts each Postgres transaction with:
+--   set_config('app.workspace_id', '<authorized workspace>', true)
+-- Supabase service-role workers bypass RLS. Never expose that credential.
+
+begin;
+
+do $$
+declare
+  table_name text;
+begin
+  foreach table_name in array array[
+    'social_accounts', 'media_variants', 'social_campaigns', 'social_posts',
+    'social_jobs', 'social_webhook_events', 'social_audit_events'
+  ] loop
+    execute format('alter table %I enable row level security', table_name);
+    execute format('drop policy if exists social_workspace_isolation on %I', table_name);
+    execute format(
+      'create policy social_workspace_isolation on %I using (workspace_id = current_setting(''app.workspace_id'', true)) with check (workspace_id = current_setting(''app.workspace_id'', true))',
+      table_name
+    );
+  end loop;
+end $$;
+
+-- OAuth states are never a user-facing resource. The provider callback has no
+-- authenticated workspace context, so its random, expiring, single-use state
+-- token is the isolation boundary. Enabling RLS here would reject a valid
+-- callback before it can atomically consume that state.
+alter table oauth_states disable row level security;
+
+alter table social_account_tokens enable row level security;
+drop policy if exists social_token_workspace_isolation on social_account_tokens;
+create policy social_token_workspace_isolation on social_account_tokens
+using (exists (
+  select 1 from social_accounts a
+  where a.id = social_account_tokens.social_account_id
+    and a.workspace_id = current_setting('app.workspace_id', true)
+)) with check (exists (
+  select 1 from social_accounts a
+  where a.id = social_account_tokens.social_account_id
+    and a.workspace_id = current_setting('app.workspace_id', true)
+));
+
+alter table social_account_capabilities enable row level security;
+drop policy if exists social_capability_workspace_isolation on social_account_capabilities;
+create policy social_capability_workspace_isolation on social_account_capabilities
+using (exists (
+  select 1 from social_accounts a
+  where a.id = social_account_capabilities.social_account_id
+    and a.workspace_id = current_setting('app.workspace_id', true)
+)) with check (exists (
+  select 1 from social_accounts a
+  where a.id = social_account_capabilities.social_account_id
+    and a.workspace_id = current_setting('app.workspace_id', true)
+));
+
+do $$
+declare
+  table_name text;
+begin
+  foreach table_name in array array[
+    'social_post_targets', 'social_post_media', 'social_schedules', 'social_post_metrics'
+  ] loop
+    execute format('alter table %I enable row level security', table_name);
+    execute format('drop policy if exists social_post_child_isolation on %I', table_name);
+    execute format(
+      'create policy social_post_child_isolation on %I using (exists (select 1 from social_posts p where p.id = %I.social_post_id and p.workspace_id = current_setting(''app.workspace_id'', true))) with check (exists (select 1 from social_posts p where p.id = %I.social_post_id and p.workspace_id = current_setting(''app.workspace_id'', true)))',
+      table_name, table_name, table_name
+    );
+  end loop;
+end $$;
+
+alter table social_job_attempts enable row level security;
+drop policy if exists social_job_attempt_workspace_isolation on social_job_attempts;
+create policy social_job_attempt_workspace_isolation on social_job_attempts
+using (exists (
+  select 1 from social_jobs j
+  where j.id = social_job_attempts.social_job_id
+    and j.workspace_id = current_setting('app.workspace_id', true)
+)) with check (exists (
+  select 1 from social_jobs j
+  where j.id = social_job_attempts.social_job_id
+    and j.workspace_id = current_setting('app.workspace_id', true)
+));
+
+commit;
+
+-- Reversal (intentionally explicit; execute only during a controlled rollback):
+-- ALTER TABLE <table> DISABLE ROW LEVEL SECURITY; DROP POLICY ...;
+-- This migration never drops customer data.

app/social/migrations/0003_social_integrity_postgres.sql

@@ -0,0 +1,187 @@
+-- Social foundation hardening. Apply after 0001 and 0002.
+-- This migration is additive: it adds database-side timestamp maintenance and
+-- tenant relationship checks without changing or deleting customer data.
+
+begin;
+
+create or replace function mediarouter_social_touch_updated_at()
+returns trigger
+language plpgsql
+as $$
+begin
+  new.updated_at = now();
+  return new;
+end;
+$$;
+
+do $$
+declare
+  table_name text;
+begin
+  foreach table_name in array array[
+    'social_accounts', 'social_account_tokens', 'social_account_capabilities',
+    'social_campaigns', 'social_posts', 'social_post_targets',
+    'social_schedules', 'social_jobs'
+  ] loop
+    execute format(
+      'drop trigger if exists mediarouter_social_touch_updated_at on %I',
+      table_name
+    );
+    execute format(
+      'create trigger mediarouter_social_touch_updated_at before update on %I for each row execute function mediarouter_social_touch_updated_at()',
+      table_name
+    );
+  end loop;
+end;
+$$;
+
+-- SQLAlchemy enums are represented as text for compatibility with the
+-- existing schema. These constraints keep direct SQL writes within the same
+-- state vocabulary enforced by the application state machine.
+do $$
+begin
+  if not exists (select 1 from pg_constraint where conname = 'ck_social_accounts_status') then
+    alter table social_accounts add constraint ck_social_accounts_status
+      check (status in ('pending', 'connected', 'reauth_required', 'disconnected', 'error'));
+  end if;
+  if not exists (select 1 from pg_constraint where conname = 'ck_social_posts_status') then
+    alter table social_posts add constraint ck_social_posts_status
+      check (status in ('draft', 'scheduled', 'queued', 'preparing', 'processing', 'uploading', 'publishing', 'published', 'partial_success', 'retrying', 'failed', 'cancelled'));
+  end if;
+  if not exists (select 1 from pg_constraint where conname = 'ck_social_post_targets_status') then
+    alter table social_post_targets add constraint ck_social_post_targets_status
+      check (status in ('draft', 'scheduled', 'queued', 'preparing', 'processing', 'uploading', 'publishing', 'published', 'partial_success', 'retrying', 'failed', 'cancelled'));
+  end if;
+  if not exists (select 1 from pg_constraint where conname = 'ck_social_schedules_status') then
+    alter table social_schedules add constraint ck_social_schedules_status
+      check (status in ('scheduled', 'queued', 'cancelled'));
+  end if;
+  if not exists (select 1 from pg_constraint where conname = 'ck_social_jobs_status') then
+    alter table social_jobs add constraint ck_social_jobs_status
+      check (status in ('draft', 'scheduled', 'queued', 'preparing', 'processing', 'uploading', 'publishing', 'published', 'retrying', 'failed', 'cancelled'));
+  end if;
+  if not exists (select 1 from pg_constraint where conname = 'ck_social_jobs_attempt_bounds') then
+    alter table social_jobs add constraint ck_social_jobs_attempt_bounds
+      check (attempt_count >= 0 and max_attempts >= 0);
+  end if;
+end;
+$$;
+
+create or replace function mediarouter_social_assert_workspace_integrity()
+returns trigger
+language plpgsql
+as $$
+declare
+  post_workspace text;
+  related_workspace text;
+  related_provider text;
+  related_post_id text;
+begin
+  if tg_op = 'UPDATE' and tg_table_name in ('social_posts', 'social_jobs')
+     and new.workspace_id is distinct from old.workspace_id then
+    raise exception 'social workspace cannot be reassigned'
+      using errcode = '23514';
+  end if;
+
+  if tg_table_name = 'social_posts' then
+    if new.campaign_id is not null then
+      select workspace_id into related_workspace
+      from social_campaigns where id = new.campaign_id;
+      if related_workspace is distinct from new.workspace_id then
+        raise exception 'social post campaign must belong to the same workspace'
+          using errcode = '23503';
+      end if;
+    end if;
+    if new.source_variant_id is not null then
+      select workspace_id into related_workspace
+      from media_variants where id = new.source_variant_id;
+      if related_workspace is distinct from new.workspace_id then
+        raise exception 'social post variant must belong to the same workspace'
+          using errcode = '23503';
+      end if;
+    end if;
+  elsif tg_table_name = 'social_post_targets' then
+    select workspace_id into post_workspace
+    from social_posts where id = new.social_post_id;
+    select workspace_id, provider into related_workspace, related_provider
+    from social_accounts where id = new.social_account_id;
+    if post_workspace is null or related_workspace is distinct from post_workspace then
+      raise exception 'social post target account must belong to the post workspace'
+        using errcode = '23503';
+    end if;
+    if new.provider is distinct from related_provider then
+      raise exception 'social post target provider must match its account'
+        using errcode = '23514';
+    end if;
+  elsif tg_table_name = 'social_post_media' and new.media_variant_id is not null then
+    select workspace_id into post_workspace
+    from social_posts where id = new.social_post_id;
+    select workspace_id into related_workspace
+    from media_variants where id = new.media_variant_id;
+    if post_workspace is null or related_workspace is distinct from post_workspace then
+      raise exception 'social post media variant must belong to the post workspace'
+        using errcode = '23503';
+    end if;
+  elsif tg_table_name = 'social_jobs' then
+    select workspace_id into post_workspace
+    from social_posts where id = new.social_post_id;
+    if post_workspace is distinct from new.workspace_id then
+      raise exception 'social job must belong to the post workspace'
+        using errcode = '23503';
+    end if;
+    if new.social_post_target_id is not null then
+      select social_post_id, provider into related_post_id, related_provider
+      from social_post_targets where id = new.social_post_target_id;
+      if related_post_id is distinct from new.social_post_id then
+        raise exception 'social job target must belong to the social post'
+          using errcode = '23503';
+      end if;
+      if new.provider is not null and new.provider is distinct from related_provider then
+        raise exception 'social job provider must match its target'
+          using errcode = '23514';
+      end if;
+    end if;
+  elsif tg_table_name = 'social_post_metrics' then
+    if new.social_post_target_id is not null then
+      select social_post_id, provider into related_post_id, related_provider
+      from social_post_targets where id = new.social_post_target_id;
+      if related_post_id is distinct from new.social_post_id then
+        raise exception 'social metric target must belong to the social post'
+          using errcode = '23503';
+      end if;
+      if new.provider is distinct from related_provider then
+        raise exception 'social metric provider must match its target'
+          using errcode = '23514';
+      end if;
+    end if;
+  end if;
+  return new;
+end;
+$$;
+
+drop trigger if exists mediarouter_social_post_workspace_integrity on social_posts;
+create trigger mediarouter_social_post_workspace_integrity
+before insert or update of workspace_id, campaign_id, source_variant_id on social_posts
+for each row execute function mediarouter_social_assert_workspace_integrity();
+
+drop trigger if exists mediarouter_social_target_workspace_integrity on social_post_targets;
+create trigger mediarouter_social_target_workspace_integrity
+before insert or update of social_post_id, social_account_id, provider on social_post_targets
+for each row execute function mediarouter_social_assert_workspace_integrity();
+
+drop trigger if exists mediarouter_social_post_media_workspace_integrity on social_post_media;
+create trigger mediarouter_social_post_media_workspace_integrity
+before insert or update of social_post_id, media_variant_id on social_post_media
+for each row execute function mediarouter_social_assert_workspace_integrity();
+
+drop trigger if exists mediarouter_social_job_workspace_integrity on social_jobs;
+create trigger mediarouter_social_job_workspace_integrity
+before insert or update of workspace_id, social_post_id, social_post_target_id, provider on social_jobs
+for each row execute function mediarouter_social_assert_workspace_integrity();
+
+drop trigger if exists mediarouter_social_metric_workspace_integrity on social_post_metrics;
+create trigger mediarouter_social_metric_workspace_integrity
+before insert or update of social_post_id, social_post_target_id, provider on social_post_metrics
+for each row execute function mediarouter_social_assert_workspace_integrity();
+
+commit;

app/social/migrations/0004_youtube_media_assets.sql

@@ -0,0 +1,28 @@
+-- YouTube Phase 2: durable, tenant-scoped references to MediaRouter outputs
+-- plus confidential durable state for resumable Google upload sessions.
+-- This migration is additive and does not rewrite Phase 1 records.
+
+begin;
+
+create table if not exists social_media_assets (
+  id text primary key default gen_random_uuid()::text,
+  workspace_id text not null,
+  request_id text not null,
+  filename text not null,
+  mime_type text not null,
+  file_size bigint not null,
+  metadata jsonb not null default '{}'::jsonb,
+  created_at timestamptz not null default now(),
+  constraint uq_social_media_asset_workspace_output unique (workspace_id, request_id, filename)
+);
+create index if not exists ix_social_media_assets_workspace_id on social_media_assets(workspace_id);
+
+alter table social_media_assets enable row level security;
+drop policy if exists social_workspace_isolation on social_media_assets;
+create policy social_workspace_isolation on social_media_assets
+  using (workspace_id = current_setting('app.workspace_id', true))
+  with check (workspace_id = current_setting('app.workspace_id', true));
+
+alter table social_jobs add column if not exists provider_state_encrypted text;
+
+commit;

app/social/models.py

@@ -0,0 +1,343 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from uuid import uuid4
+
+from sqlalchemy import (
+    JSON,
+    BigInteger,
+    DateTime,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    Text,
+    UniqueConstraint,
+)
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+def utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def new_id() -> str:
+    return str(uuid4())
+
+
+class SocialBase(DeclarativeBase):
+    """Separate metadata keeps production schema changes migration-only."""
+
+
+class SocialAccount(SocialBase):
+    __tablename__ = "social_accounts"
+    __table_args__ = (
+        UniqueConstraint("workspace_id", "provider", "external_account_id", name="uq_social_account_workspace_provider_external"),
+        Index("ix_social_accounts_workspace_id", "workspace_id"),
+        Index("ix_social_accounts_provider_status", "provider", "status"),
+    )
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
+    workspace_id: Mapped[str] = mapped_column(String(120), nullable=False)
+    provider: Mapped[str] = mapped_column(String(32), nullable=False)
+    account_type: Mapped[str] = mapped_column(String(64), nullable=False)
+    external_account_id: Mapped[str] = mapped_column(String(255), nullable=False)
+    username: Mapped[str | None] = mapped_column(String(255))
+    display_name: Mapped[str | None] = mapped_column(String(255))
+    avatar_url: Mapped[str | None] = mapped_column(String(2048))
+    status: Mapped[str] = mapped_column(String(32), nullable=False, default="pending")
+    metadata_json: Mapped[dict[str, object]] = mapped_column("metadata", JSON, nullable=False, default=dict)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow)
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow, onupdate=utcnow)
+    last_synced_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class SocialAccountToken(SocialBase):
+    __tablename__ = "social_account_tokens"
+    __table_args__ = (
+        UniqueConstraint("social_account_id", name="uq_social_account_token"),
+        Index("ix_social_account_tokens_expires_at", "expires_at"),
+    )
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
+    social_account_id: Mapped[str] = mapped_column(String(36), ForeignKey("social_accounts.id", ondelete="CASCADE"), nullable=False)
+    access_token_secret_id: Mapped[str | None] = mapped_column(String(255))
+    refresh_token_secret_id: Mapped[str | None] = mapped_column(String(255))
+    encrypted_payload: Mapped[str | None] = mapped_column(Text)
+    expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    scopes: Mapped[list[str]] = mapped_column(JSON, nullable=False, default=list)
+    token_type: Mapped[str | None] = mapped_column(String(64))
+    last_refreshed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow)
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow, onupdate=utcnow)
+
+
+class SocialAccountCapability(SocialBase):
+    __tablename__ = "social_account_capabilities"
+    __table_args__ = (
+        UniqueConstraint("social_account_id", "capability", name="uq_social_account_capability"),
+        Index("ix_social_account_capabilities_account", "social_account_id"),
+    )
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
+    social_account_id: Mapped[str] = mapped_column(String(36), ForeignKey("social_accounts.id", ondelete="CASCADE"), nullable=False)
+    capability: Mapped[str] = mapped_column(String(100), nullable=False)
+    enabled: Mapped[bool] = mapped_column(nullable=False, default=False)
+    metadata_json: Mapped[dict[str, object]] = mapped_column("metadata", JSON, nullable=False, default=dict)
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow, onupdate=utcnow)
+
+
+class MediaVariant(SocialBase):
+    __tablename__ = "media_variants"
+    __table_args__ = (
+        Index("ix_media_variants_workspace_source", "workspace_id", "source_asset_id"),
+        Index("ix_media_variants_platform", "platform"),
+    )
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
+    workspace_id: Mapped[str] = mapped_column(String(120), nullable=False)
+    source_asset_id: Mapped[str] = mapped_column(String(255), nullable=False)
+    asset_reference: Mapped[str | None] = mapped_column(String(2048))
+    template_id: Mapped[str | None] = mapped_column(String(255))
+    platform: Mapped[str | None] = mapped_column(String(32))
+    width: Mapped[int | None] = mapped_column(Integer)
+    height: Mapped[int | None] = mapped_column(Integer)
+    duration_seconds: Mapped[float | None] = mapped_column()
+    codec: Mapped[str | None] = mapped_column(String(64))
+    container: Mapped[str | None] = mapped_column(String(64))
+    bitrate: Mapped[int | None] = mapped_column(BigInteger)
+    file_size: Mapped[int | None] = mapped_column(BigInteger)
+    metadata_json: Mapped[dict[str, object]] = mapped_column("metadata", JSON, nullable=False, default=dict)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow)
+
+
+class SocialMediaAsset(SocialBase):
+    """A workspace-owned reference to an output published by MediaRouter.
+
+    The media processor remains the source of truth for files.  This table
+    only records a tenant binding and immutable download locator so social
+    workers can validate and stream the exact output without trusting a
+    caller-supplied filesystem path or URL.
+    """
+
+    __tablename__ = "social_media_assets"
+    __table_args__ = (
+        UniqueConstraint("workspace_id", "request_id", "filename", name="uq_social_media_asset_workspace_output"),
+        Index("ix_social_media_assets_workspace_id", "workspace_id"),
+    )
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
+    workspace_id: Mapped[str] = mapped_column(String(120), nullable=False)
+    request_id: Mapped[str] = mapped_column(String(36), nullable=False)
+    filename: Mapped[str] = mapped_column(String(255), nullable=False)
+    mime_type: Mapped[str] = mapped_column(String(255), nullable=False)
+    file_size: Mapped[int] = mapped_column(BigInteger, nullable=False)
+    metadata_json: Mapped[dict[str, object]] = mapped_column("metadata", JSON, nullable=False, default=dict)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow)
+
+
+class SocialCampaign(SocialBase):
+    __tablename__ = "social_campaigns"
+    __table_args__ = (Index("ix_social_campaigns_workspace_id", "workspace_id"),)
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
+    workspace_id: Mapped[str] = mapped_column(String(120), nullable=False)
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    description: Mapped[str | None] = mapped_column(Text)
+    status: Mapped[str] = mapped_column(String(32), nullable=False, default="draft")
+    metadata_json: Mapped[dict[str, object]] = mapped_column("metadata", JSON, nullable=False, default=dict)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow)
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow, onupdate=utcnow)
+
+
+class SocialPost(SocialBase):
+    __tablename__ = "social_posts"
+    __table_args__ = (
+        UniqueConstraint("workspace_id", "idempotency_key", name="uq_social_posts_workspace_idempotency"),
+        Index("ix_social_posts_workspace_created", "workspace_id", "created_at"),
+        Index("ix_social_posts_status", "status"),
+    )
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
+    workspace_id: Mapped[str] = mapped_column(String(120), nullable=False)
+    campaign_id: Mapped[str | None] = mapped_column(String(36), ForeignKey("social_campaigns.id", ondelete="SET NULL"))
+    media_asset_id: Mapped[str] = mapped_column(String(255), nullable=False)
+    source_variant_id: Mapped[str | None] = mapped_column(String(36), ForeignKey("media_variants.id", ondelete="SET NULL"))
+    status: Mapped[str] = mapped_column(String(32), nullable=False, default="draft")
+    publish_mode: Mapped[str] = mapped_column(String(32), nullable=False, default="draft")
+    idempotency_key: Mapped[str | None] = mapped_column(String(255))
+    request_fingerprint: Mapped[str | None] = mapped_column(String(64))
+    metadata_json: Mapped[dict[str, object]] = mapped_column("metadata", JSON, nullable=False, default=dict)
+    created_by: Mapped[str | None] = mapped_column(String(120))
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow)
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow, onupdate=utcnow)
+    published_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class SocialPostTarget(SocialBase):
+    __tablename__ = "social_post_targets"
+    __table_args__ = (
+        UniqueConstraint("social_post_id", "social_account_id", name="uq_social_post_target"),
+        Index("ix_social_post_targets_post", "social_post_id"),
+        Index("ix_social_post_targets_account", "social_account_id"),
+        Index("ix_social_post_targets_status", "status"),
+    )
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
+    social_post_id: Mapped[str] = mapped_column(String(36), ForeignKey("social_posts.id", ondelete="CASCADE"), nullable=False)
+    social_account_id: Mapped[str] = mapped_column(String(36), ForeignKey("social_accounts.id", ondelete="RESTRICT"), nullable=False)
+    provider: Mapped[str] = mapped_column(String(32), nullable=False)
+    status: Mapped[str] = mapped_column(String(32), nullable=False, default="draft")
+    caption_json: Mapped[dict[str, object]] = mapped_column("caption", JSON, nullable=False, default=dict)
+    platform_metadata: Mapped[dict[str, object]] = mapped_column(JSON, nullable=False, default=dict)
+    external_post_id: Mapped[str | None] = mapped_column(String(255))
+    external_url: Mapped[str | None] = mapped_column(String(2048))
+    error_code: Mapped[str | None] = mapped_column(String(100))
+    error_message: Mapped[str | None] = mapped_column(Text)
+    published_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow)
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow, onupdate=utcnow)
+
+
+class SocialPostMedia(SocialBase):
+    __tablename__ = "social_post_media"
+    __table_args__ = (Index("ix_social_post_media_post", "social_post_id"),)
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
+    social_post_id: Mapped[str] = mapped_column(String(36), ForeignKey("social_posts.id", ondelete="CASCADE"), nullable=False)
+    media_variant_id: Mapped[str | None] = mapped_column(String(36), ForeignKey("media_variants.id", ondelete="SET NULL"))
+    media_asset_id: Mapped[str | None] = mapped_column(String(255))
+    position: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    kind: Mapped[str] = mapped_column(String(32), nullable=False, default="video")
+    metadata_json: Mapped[dict[str, object]] = mapped_column("metadata", JSON, nullable=False, default=dict)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow)
+
+
+class SocialSchedule(SocialBase):
+    __tablename__ = "social_schedules"
+    __table_args__ = (
+        UniqueConstraint("social_post_id", name="uq_social_schedule_post"),
+        Index("ix_social_schedules_due", "status", "scheduled_at"),
+    )
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
+    social_post_id: Mapped[str] = mapped_column(String(36), ForeignKey("social_posts.id", ondelete="CASCADE"), nullable=False)
+    scheduled_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    timezone: Mapped[str] = mapped_column(String(100), nullable=False)
+    status: Mapped[str] = mapped_column(String(32), nullable=False, default="scheduled")
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow)
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow, onupdate=utcnow)
+
+
+class SocialJob(SocialBase):
+    __tablename__ = "social_jobs"
+    __table_args__ = (
+        UniqueConstraint("workspace_id", "idempotency_key", name="uq_social_jobs_workspace_idempotency"),
+        Index("ix_social_jobs_workspace_status", "workspace_id", "status"),
+        Index("ix_social_jobs_next_attempt", "status", "next_attempt_at"),
+        Index("ix_social_jobs_post", "social_post_id"),
+    )
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
+    workspace_id: Mapped[str] = mapped_column(String(120), nullable=False)
+    social_post_id: Mapped[str] = mapped_column(String(36), ForeignKey("social_posts.id", ondelete="CASCADE"), nullable=False)
+    social_post_target_id: Mapped[str | None] = mapped_column(String(36), ForeignKey("social_post_targets.id", ondelete="CASCADE"))
+    provider: Mapped[str | None] = mapped_column(String(32))
+    status: Mapped[str] = mapped_column(String(32), nullable=False, default="queued")
+    attempt_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    max_attempts: Mapped[int] = mapped_column(Integer, nullable=False, default=5)
+    next_attempt_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    idempotency_key: Mapped[str | None] = mapped_column(String(255))
+    error_code: Mapped[str | None] = mapped_column(String(100))
+    error_message: Mapped[str | None] = mapped_column(Text)
+    payload_json: Mapped[dict[str, object]] = mapped_column("payload", JSON, nullable=False, default=dict)
+    # Provider resumable-session URLs are bearer-like credentials. They must
+    # survive a worker restart but must never be present in job REST/MCP/SDK
+    # payloads, so they are encrypted separately from payload JSON.
+    provider_state_encrypted: Mapped[str | None] = mapped_column(Text)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow)
+    started_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow, onupdate=utcnow)
+
+
+class SocialJobAttempt(SocialBase):
+    __tablename__ = "social_job_attempts"
+    __table_args__ = (
+        UniqueConstraint("social_job_id", "attempt_number", name="uq_social_job_attempt_number"),
+        Index("ix_social_job_attempts_job", "social_job_id", "attempt_number"),
+    )
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
+    social_job_id: Mapped[str] = mapped_column(String(36), ForeignKey("social_jobs.id", ondelete="CASCADE"), nullable=False)
+    attempt_number: Mapped[int] = mapped_column(Integer, nullable=False)
+    status: Mapped[str] = mapped_column(String(32), nullable=False)
+    error_code: Mapped[str | None] = mapped_column(String(100))
+    error_message: Mapped[str | None] = mapped_column(Text)
+    provider_request_id: Mapped[str | None] = mapped_column(String(255))
+    started_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow)
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class OAuthState(SocialBase):
+    __tablename__ = "oauth_states"
+    __table_args__ = (
+        Index("ix_oauth_states_state", "state", unique=True),
+        Index("ix_oauth_states_expires_at", "expires_at"),
+        Index("ix_oauth_states_workspace", "workspace_id"),
+    )
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
+    state: Mapped[str] = mapped_column(String(255), nullable=False)
+    provider: Mapped[str] = mapped_column(String(32), nullable=False)
+    workspace_id: Mapped[str] = mapped_column(String(120), nullable=False)
+    user_id: Mapped[str | None] = mapped_column(String(120))
+    redirect_uri: Mapped[str] = mapped_column(String(2048), nullable=False)
+    code_verifier_encrypted: Mapped[str | None] = mapped_column(Text)
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    used_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow)
+
+
+class SocialWebhookEvent(SocialBase):
+    __tablename__ = "social_webhook_events"
+    __table_args__ = (
+        UniqueConstraint("provider", "external_event_id", name="uq_social_webhook_provider_external"),
+        Index("ix_social_webhook_events_status", "status"),
+        Index("ix_social_webhook_events_received", "received_at"),
+    )
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
+    provider: Mapped[str] = mapped_column(String(32), nullable=False)
+    event_type: Mapped[str] = mapped_column(String(100), nullable=False)
+    external_event_id: Mapped[str] = mapped_column(String(255), nullable=False)
+    workspace_id: Mapped[str | None] = mapped_column(String(120))
+    payload_json: Mapped[dict[str, object]] = mapped_column("payload", JSON, nullable=False, default=dict)
+    received_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow)
+    processed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    status: Mapped[str] = mapped_column(String(32), nullable=False, default="received")
+    error_message: Mapped[str | None] = mapped_column(Text)
+
+
+class SocialPostMetric(SocialBase):
+    __tablename__ = "social_post_metrics"
+    __table_args__ = (Index("ix_social_post_metrics_target_retrieved", "social_post_target_id", "retrieved_at"),)
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
+    social_post_id: Mapped[str] = mapped_column(String(36), ForeignKey("social_posts.id", ondelete="CASCADE"), nullable=False)
+    social_post_target_id: Mapped[str | None] = mapped_column(String(36), ForeignKey("social_post_targets.id", ondelete="CASCADE"))
+    provider: Mapped[str] = mapped_column(String(32), nullable=False)
+    views: Mapped[int | None] = mapped_column(BigInteger)
+    impressions: Mapped[int | None] = mapped_column(BigInteger)
+    likes: Mapped[int | None] = mapped_column(BigInteger)
+    comments: Mapped[int | None] = mapped_column(BigInteger)
+    shares: Mapped[int | None] = mapped_column(BigInteger)
+    engagement_rate: Mapped[float | None] = mapped_column()
+    published_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    retrieved_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow)
+    raw_metrics: Mapped[dict[str, object]] = mapped_column(JSON, nullable=False, default=dict)
+
+
+class SocialAuditEvent(SocialBase):
+    __tablename__ = "social_audit_events"
+    __table_args__ = (
+        Index("ix_social_audit_events_workspace_created", "workspace_id", "created_at"),
+        Index("ix_social_audit_events_type", "event_type"),
+    )
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
+    workspace_id: Mapped[str] = mapped_column(String(120), nullable=False)
+    api_key_id: Mapped[str | None] = mapped_column(String(36))
+    event_type: Mapped[str] = mapped_column(String(100), nullable=False)
+    provider: Mapped[str | None] = mapped_column(String(32))
+    social_account_id: Mapped[str | None] = mapped_column(String(36))
+    social_post_id: Mapped[str | None] = mapped_column(String(36))
+    social_job_id: Mapped[str | None] = mapped_column(String(36))
+    request_id: Mapped[str | None] = mapped_column(String(64))
+    metadata_json: Mapped[dict[str, object]] = mapped_column("metadata", JSON, nullable=False, default=dict)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow)

app/social/oauth/__init__.py

@@ -0,0 +1,4 @@
+from app.social.oauth.encryption import TokenCipher
+from app.social.oauth.state import OAuthStateService
+
+__all__ = ["OAuthStateService", "TokenCipher"]

app/social/oauth/base.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class OAuthProvider(Protocol):
+    async def get_authorization_url(self, *, state: str, redirect_uri: str) -> str:
+        ...
+
+    async def exchange_code(
+        self, *, code: str, redirect_uri: str
+    ) -> dict[str, object]:
+        ...
+
+    async def refresh_token(self, token: dict[str, object]) -> dict[str, object]:
+        ...
+
+    async def revoke_token(self, token: dict[str, object]) -> None:
+        ...

app/social/oauth/encryption.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from typing import Any
+
+from app.social.domain.errors import SocialProviderUnavailableError
+
+
+class TokenCipher:
+    """Narrow encryption boundary for non-Vault local development.
+
+    Imports cryptography lazily so provider discovery and existing media APIs
+    still start when social token storage is unused. Production should use
+    Supabase Vault references instead of this encrypted database fallback.
+    """
+
+    def __init__(self, key: str | None) -> None:
+        self._key = key
+
+    def _fernet(self):
+        if not self._key:
+            raise SocialProviderUnavailableError(
+                "SOCIAL_OAUTH_ENCRYPTION_KEY is required when Supabase Vault is disabled."
+            )
+        try:
+            from cryptography.fernet import Fernet
+        except ImportError as exc:
+            raise SocialProviderUnavailableError("The cryptography package is required for token storage.") from exc
+        digest = hashlib.sha256(self._key.encode("utf-8")).digest()
+        return Fernet(base64.urlsafe_b64encode(digest))
+
+    def encrypt(self, value: dict[str, Any]) -> str:
+        return self._fernet().encrypt(json.dumps(value, separators=(",", ":")).encode()).decode()
+
+    def decrypt(self, value: str) -> dict[str, Any]:
+        result = json.loads(self._fernet().decrypt(value.encode()).decode())
+        return result if isinstance(result, dict) else {}

app/social/oauth/state.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import secrets
+from datetime import datetime, timedelta, timezone
+
+from sqlalchemy import update
+
+from app.social.database import SocialDatabase
+from app.social.domain.errors import SocialOAuthStateError
+from app.social.models import OAuthState
+from app.social.oauth.encryption import TokenCipher
+
+
+class OAuthStateService:
+    def __init__(self, database: SocialDatabase, cipher: TokenCipher) -> None:
+        self.database = database
+        self.cipher = cipher
+
+    async def create(self, *, provider: str, workspace_id: str, user_id: str, redirect_uri: str, ttl_seconds: int = 600) -> OAuthState:
+        record = OAuthState(
+            state=secrets.token_urlsafe(32), provider=provider, workspace_id=workspace_id,
+            user_id=user_id, redirect_uri=redirect_uri,
+            code_verifier_encrypted=self.cipher.encrypt({"verifier": secrets.token_urlsafe(48)}),
+            expires_at=datetime.now(timezone.utc) + timedelta(seconds=ttl_seconds),
+        )
+        async with self.database.session(workspace_id) as session:
+            session.add(record)
+            await session.commit()
+            await session.refresh(record)
+        return record
+
+    async def consume(self, *, state: str, provider: str) -> OAuthState:
+        now = datetime.now(timezone.utc)
+        async with self.database.session() as session:
+            record = await session.scalar(
+                update(OAuthState)
+                .where(
+                    OAuthState.state == state,
+                    OAuthState.provider == provider,
+                    OAuthState.used_at.is_(None),
+                    OAuthState.expires_at > now,
+                )
+                .values(used_at=now)
+                .returning(OAuthState)
+            )
+            if record is None:
+                raise SocialOAuthStateError("OAuth state is invalid, expired, or already used.")
+            await session.commit()
+            return record
+
+    def code_verifier(self, record: OAuthState) -> str | None:
+        if not record.code_verifier_encrypted:
+            return None
+        value = self.cipher.decrypt(record.code_verifier_encrypted)
+        verifier = value.get("verifier")
+        return str(verifier) if verifier else None

app/social/providers/__init__.py

@@ -0,0 +1,3 @@
+from app.social.providers.registry import ProviderRegistry, build_provider_registry
+
+__all__ = ["ProviderRegistry", "build_provider_registry"]

app/social/providers/base.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from abc import ABC
+from typing import Any
+
+from app.social.domain.capabilities import ProviderCapabilities
+from app.social.domain.errors import (
+    SocialCapabilityUnsupportedError,
+    SocialProviderNotImplementedError,
+    SocialPublishFailedError,
+)
+
+
+class SocialProviderAdapter(ABC):
+    """Common adapter contract; unsupported functions fail explicitly."""
+
+    capabilities: ProviderCapabilities
+    # Adapters opt out only when their official web OAuth contract does not
+    # define PKCE. OAuthService remains the single orchestration layer.
+    pkce_supported: bool = True
+    reconciliation_poll_seconds: int = 30
+
+    @property
+    def provider(self) -> str:
+        return self.capabilities.provider.value
+
+    async def get_authorization_url(
+        self,
+        *,
+        state: str,
+        redirect_uri: str,
+        code_challenge: str | None = None,
+        additional_scopes: list[str] | None = None,
+    ) -> str:
+        raise SocialProviderNotImplementedError(f"{self.provider} account connection is not implemented.")
+
+    async def exchange_code(
+        self, *, code: str, redirect_uri: str, code_verifier: str | None = None
+    ) -> dict[str, Any]:
+        raise SocialProviderNotImplementedError(f"{self.provider} OAuth exchange is not implemented.")
+
+    async def refresh_token(self, token: dict[str, Any]) -> dict[str, Any]:
+        raise SocialProviderNotImplementedError(f"{self.provider} token refresh is not implemented.")
+
+    async def revoke_token(self, token: dict[str, Any]) -> None:
+        raise SocialProviderNotImplementedError(f"{self.provider} token revocation is not implemented.")
+
+    async def get_account(self, token: dict[str, Any]) -> dict[str, Any]:
+        raise SocialProviderNotImplementedError(f"{self.provider} account discovery is not implemented.")
+
+    async def get_capabilities(self) -> ProviderCapabilities:
+        return self.capabilities
+
+    async def get_publish_options(self, token: dict[str, Any]) -> dict[str, Any]:
+        if not self.capabilities.publish_supported:
+            raise SocialCapabilityUnsupportedError(
+                f"{self.provider} publishing is unavailable."
+            )
+        raise SocialProviderNotImplementedError(
+            f"{self.provider} publish options are not implemented."
+        )
+
+    async def validate_media(self, media: dict[str, Any]) -> None:
+        if not self.capabilities.publish_supported:
+            raise SocialProviderNotImplementedError(f"{self.provider} publishing is not implemented.")
+
+    async def upload_media(self, token: dict[str, Any], media: dict[str, Any]) -> dict[str, Any]:
+        raise SocialProviderNotImplementedError(f"{self.provider} media upload is not implemented.")
+
+    async def publish(self, token: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:
+        raise SocialProviderNotImplementedError(f"{self.provider} publishing is not implemented.")
+
+    async def get_publish_status(self, token: dict[str, Any], external_id: str) -> dict[str, Any]:
+        raise SocialProviderNotImplementedError(f"{self.provider} publish status is not implemented.")
+
+    def publish_failure(self, result: dict[str, Any]) -> Exception:
+        """Normalize an unsuccessful provider status without leaking its payload."""
+        del result
+        return SocialPublishFailedError(
+            f"{self.provider} publishing did not complete successfully."
+        )
+
+    async def delete_post(self, token: dict[str, Any], external_id: str) -> None:
+        if not self.capabilities.delete_post:
+            raise SocialCapabilityUnsupportedError(f"{self.provider} does not support post deletion.")
+        raise SocialProviderNotImplementedError(f"{self.provider} post deletion is not implemented.")
+
+    async def get_metrics(self, token: dict[str, Any], external_id: str) -> dict[str, Any]:
+        if not self.capabilities.analytics:
+            raise SocialCapabilityUnsupportedError(f"{self.provider} analytics are unavailable.")
+        raise SocialProviderNotImplementedError(f"{self.provider} analytics are not implemented.")

app/social/providers/facebook.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from app.core.config import Settings
+from app.social.domain.capabilities import ProviderCapabilities
+from app.social.domain.enums import ConnectionStrategy, Provider
+from app.social.providers.meta_graph import MetaGraphClient, insight_values
+from app.social.providers.oauth import OAuthFoundationAdapter
+
+
+class FacebookProvider(OAuthFoundationAdapter):
+
+    def __init__(
+        self, settings: Settings, *, http_client: httpx.AsyncClient | None = None
+    ) -> None:
+        self.client_id = settings.resolved_meta_app_id
+        self.authorization_endpoint = (
+            f"https://www.facebook.com/{settings.meta_graph_api_version}/dialog/oauth"
+        )
+        self._graph = MetaGraphClient(settings, http_client=http_client)
+        self.capabilities = ProviderCapabilities(
+            provider=Provider.FACEBOOK, connection_strategy=ConnectionStrategy.OAUTH,
+            implementation_status="registered",
+            account_types=["facebook_page"],
+            # The Graph endpoint and normalization are implemented, but these
+            # are opt-in scopes. A standard connection is never escalated.
+            analytics=True,
+            analytics_required_scopes=["pages_read_engagement", "read_insights"],
+        )
+
+    async def close(self) -> None:
+        await self._graph.close()
+
+    async def get_metrics(
+        self, token: dict[str, Any], external_id: str
+    ) -> dict[str, Any]:
+        """Read actual Page-post data using the official Graph API.
+
+        The compact fields request avoids deprecated aggregate guessing. A
+        missing field stays absent in the normalized response; zero is never
+        inferred from an empty Meta response.
+        """
+
+        payload = await self._graph.get(
+            external_id,
+            _token_mapping(token),
+            params={
+                "fields": (
+                    "created_time,"
+                    "insights.metric(post_impressions,post_engaged_users,"
+                    "post_clicks,post_video_views),"
+                    "reactions.limit(0).summary(true),"
+                    "comments.limit(0).summary(true),shares"
+                )
+            },
+        )
+        insight_payload = payload.get("insights")
+        insights = insight_values(insight_payload) if isinstance(insight_payload, dict) else {}
+        normalized: dict[str, Any] = {
+            "status": "available",
+            "raw_metrics": {
+                "post_insights": insight_payload if isinstance(insight_payload, dict) else {},
+                "reactions": payload.get("reactions"),
+                "comments": payload.get("comments"),
+                "shares": payload.get("shares"),
+            },
+        }
+        _set_number(normalized, "impressions", insights.get("post_impressions"))
+        _set_number(normalized, "views", insights.get("post_video_views"))
+        _set_number(normalized, "engaged_users", insights.get("post_engaged_users"))
+        _set_number(normalized, "clicks", insights.get("post_clicks"))
+        _set_number(normalized, "likes", _summary_count(payload.get("reactions")))
+        _set_number(normalized, "comments", _summary_count(payload.get("comments")))
+        shares = payload.get("shares")
+        if isinstance(shares, dict):
+            _set_number(normalized, "shares", shares.get("count"))
+        if isinstance(payload.get("created_time"), str):
+            normalized["published_at"] = payload["created_time"]
+        if not any(
+            key in normalized
+            for key in ("impressions", "views", "engaged_users", "clicks", "likes", "comments", "shares")
+        ):
+            return {
+                "status": "unavailable",
+                "reason": "META_METRICS_NOT_AVAILABLE",
+                "raw_metrics": normalized["raw_metrics"],
+            }
+        return normalized
+
+
+def _token_mapping(token: dict[str, Any]) -> Mapping[str, object]:
+    return token
+
+
+def _summary_count(value: object) -> int | float | None:
+    if not isinstance(value, dict):
+        return None
+    summary = value.get("summary")
+    if not isinstance(summary, dict):
+        return None
+    count = summary.get("total_count")
+    return count if isinstance(count, (int, float)) and not isinstance(count, bool) else None
+
+
+def _set_number(target: dict[str, Any], key: str, value: object) -> None:
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        target[key] = value

app/social/providers/instagram.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from app.core.config import Settings
+from app.social.domain.capabilities import ProviderCapabilities
+from app.social.domain.enums import ConnectionStrategy, Provider
+from app.social.providers.meta_graph import MetaGraphClient, insight_values
+from app.social.providers.oauth import OAuthFoundationAdapter
+
+
+class InstagramProvider(OAuthFoundationAdapter):
+
+    def __init__(
+        self, settings: Settings, *, http_client: httpx.AsyncClient | None = None
+    ) -> None:
+        self.client_id = settings.resolved_meta_app_id
+        self.authorization_endpoint = (
+            f"https://www.facebook.com/{settings.meta_graph_api_version}/dialog/oauth"
+        )
+        self._graph = MetaGraphClient(settings, http_client=http_client)
+        self.capabilities = ProviderCapabilities(
+            provider=Provider.INSTAGRAM, connection_strategy=ConnectionStrategy.OAUTH,
+            implementation_status="registered",
+            account_types=["instagram_professional_account"],
+            analytics=True,
+            analytics_required_scopes=["instagram_basic", "instagram_manage_insights"],
+        )
+
+    async def close(self) -> None:
+        await self._graph.close()
+
+    async def get_metrics(
+        self, token: dict[str, Any], external_id: str
+    ) -> dict[str, Any]:
+        """Fetch Instagram professional-media insights by product type.
+
+        Meta does not support one universal metrics set. Querying the media
+        object first prevents an unsupported-metric request for albums and
+        ensures Reels use their documented metric family.
+        """
+
+        media = await self._graph.get(
+            external_id,
+            _token_mapping(token),
+            params={"fields": "media_product_type,media_type,timestamp,permalink"},
+        )
+        product_type = str(media.get("media_product_type", "")).upper()
+        media_type = str(media.get("media_type", "")).upper()
+        metrics = _metrics_for(product_type, media_type)
+        if not metrics:
+            return {
+                "status": "unavailable",
+                "reason": "INSTAGRAM_MEDIA_TYPE_ANALYTICS_UNAVAILABLE",
+                "raw_metrics": {"media": media},
+            }
+        payload = await self._graph.get(
+            f"{external_id}/insights",
+            _token_mapping(token),
+            params={"metric": ",".join(metrics)},
+        )
+        values = insight_values(payload)
+        if not values:
+            # Meta documents an empty data set for unavailable data. It is not
+            # a numeric zero and must not be stored as one.
+            return {
+                "status": "unavailable",
+                "reason": "META_METRICS_NOT_AVAILABLE",
+                "raw_metrics": {"media": media, "insights": payload},
+            }
+        normalized: dict[str, Any] = {
+            "status": "available",
+            "raw_metrics": {"media": media, "insights": payload},
+        }
+        for key in ("views", "reach", "likes", "comments", "shares", "saved"):
+            _set_number(normalized, key, values.get(key))
+        if isinstance(media.get("timestamp"), str):
+            normalized["published_at"] = media["timestamp"]
+        if isinstance(media.get("permalink"), str):
+            normalized["url"] = media["permalink"]
+        return normalized
+
+
+def _metrics_for(product_type: str, media_type: str) -> list[str]:
+    if product_type == "REELS":
+        return ["views", "reach", "likes", "comments", "shares", "saved"]
+    if product_type == "FEED":
+        # `views` is applicable only to playable feed video. Image posts use
+        # the common engagement/reach metrics.
+        metrics = ["reach", "likes", "comments", "shares", "saved"]
+        if media_type == "VIDEO":
+            metrics.insert(0, "views")
+        return metrics
+    # Meta documents no per-item insights for an album. Do not issue a request
+    # that would either fail or tempt callers to fabricate an aggregate.
+    return []
+
+
+def _token_mapping(token: dict[str, Any]) -> Mapping[str, object]:
+    return token
+
+
+def _set_number(target: dict[str, Any], key: str, value: object) -> None:
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        target[key] = value

app/social/providers/linkedin.py

@@ -0,0 +1,15 @@
+from app.core.config import Settings
+from app.social.domain.capabilities import ProviderCapabilities
+from app.social.domain.enums import ConnectionStrategy, Provider
+from app.social.providers.oauth import OAuthFoundationAdapter
+
+
+class LinkedInProvider(OAuthFoundationAdapter):
+    authorization_endpoint = "https://www.linkedin.com/oauth/v2/authorization"
+
+    def __init__(self, settings: Settings) -> None:
+        self.client_id = settings.linkedin_client_id
+        self.capabilities = ProviderCapabilities(
+            provider=Provider.LINKEDIN, connection_strategy=ConnectionStrategy.OAUTH,
+            implementation_status="registered", account_types=["member", "organization"],
+        )

app/social/providers/meta.py

@@ -0,0 +1,3 @@
+"""Shared Meta family marker; Facebook Pages and Instagram accounts stay distinct."""
+
+META_PROVIDER_FAMILY = frozenset({"facebook", "instagram"})

app/social/providers/meta_graph.py

@@ -0,0 +1,115 @@
+"""Official Meta Graph API helpers shared by Meta analytics adapters.
+
+Access tokens are sent as Authorization bearer credentials instead of URL
+parameters. This prevents accidental credential capture by URL logging,
+proxies, exceptions, or observability tooling.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from app.core.config import Settings
+from app.social.domain.errors import (
+    SocialPermissionDeniedError,
+    SocialProviderUnavailableError,
+    SocialRateLimitedError,
+    SocialReauthRequiredError,
+)
+
+_GRAPH_API_ROOT = "https://graph.facebook.com"
+_AUTHENTICATION_ERROR_CODES = frozenset({102, 190})
+_PERMISSION_ERROR_CODES = frozenset({10, 200, 299})
+_RATE_LIMIT_ERROR_CODES = frozenset({4, 17, 32, 613})
+
+
+class MetaGraphClient:
+    """Minimal Graph transport with normalized, non-sensitive errors."""
+
+    def __init__(
+        self, settings: Settings, *, http_client: httpx.AsyncClient | None = None
+    ) -> None:
+        self._version = settings.meta_graph_api_version
+        self._client = http_client or httpx.AsyncClient(
+            timeout=httpx.Timeout(30.0), follow_redirects=False
+        )
+        self._owns_client = http_client is None
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def get(
+        self, object_path: str, token: Mapping[str, object], *, params: Mapping[str, str]
+    ) -> dict[str, Any]:
+        access_token = token.get("access_token")
+        if not isinstance(access_token, str) or not access_token:
+            raise SocialReauthRequiredError("The Meta account requires reauthorization.")
+        try:
+            response = await self._client.get(
+                f"{_GRAPH_API_ROOT}/{self._version}/{object_path.lstrip('/')}",
+                params=dict(params),
+                headers={"Authorization": f"Bearer {access_token}"},
+            )
+        except httpx.TransportError as exc:
+            raise SocialProviderUnavailableError(
+                "Meta analytics is temporarily unavailable."
+            ) from exc
+        if response.is_success:
+            try:
+                payload = response.json()
+            except ValueError as exc:
+                raise SocialProviderUnavailableError(
+                    "Meta returned an invalid analytics response."
+                ) from exc
+            if isinstance(payload, dict):
+                return payload
+            raise SocialProviderUnavailableError("Meta returned an invalid analytics response.")
+        self._raise_graph_error(response)
+        raise AssertionError("Meta graph error mapping must raise")
+
+    @staticmethod
+    def _raise_graph_error(response: httpx.Response) -> None:
+        code: int | None = None
+        try:
+            payload = response.json()
+            error = payload.get("error", {}) if isinstance(payload, dict) else {}
+            raw_code = error.get("code") if isinstance(error, dict) else None
+            code = int(raw_code) if raw_code is not None else None
+        except (TypeError, ValueError):
+            pass
+        if response.status_code == 401 or code in _AUTHENTICATION_ERROR_CODES:
+            raise SocialReauthRequiredError("The Meta account requires reauthorization.")
+        if response.status_code == 403 or code in _PERMISSION_ERROR_CODES:
+            raise SocialPermissionDeniedError("Meta analytics permission was denied.")
+        if response.status_code == 429 or code in _RATE_LIMIT_ERROR_CODES:
+            raise SocialRateLimitedError("Meta analytics rate limit reached.")
+        if response.status_code >= 500 or code == 1:
+            raise SocialProviderUnavailableError("Meta analytics is temporarily unavailable.")
+        raise SocialProviderUnavailableError("Meta analytics request was rejected.")
+
+
+def insight_values(payload: Mapping[str, Any]) -> dict[str, int | float | None]:
+    """Extract only scalar values Meta actually returned for each metric."""
+
+    metrics: dict[str, int | float | None] = {}
+    raw_data = payload.get("data")
+    if not isinstance(raw_data, list):
+        return metrics
+    for item in raw_data:
+        if not isinstance(item, dict) or not isinstance(item.get("name"), str):
+            continue
+        value: Any = None
+        values = item.get("values")
+        if isinstance(values, list) and values and isinstance(values[-1], dict):
+            value = values[-1].get("value")
+        elif isinstance(item.get("total_value"), dict):
+            value = item["total_value"].get("value")
+        if isinstance(value, bool):
+            continue
+        if isinstance(value, (int, float)):
+            metrics[item["name"]] = value
+    return metrics

app/social/providers/oauth.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from urllib.parse import urlencode
+
+from app.social.domain.errors import SocialProviderUnavailableError
+from app.social.providers.base import SocialProviderAdapter
+
+
+class OAuthFoundationAdapter(SocialProviderAdapter):
+    authorization_endpoint: str
+    client_id: str
+
+    async def get_authorization_url(
+        self,
+        *,
+        state: str,
+        redirect_uri: str,
+        code_challenge: str | None = None,
+        additional_scopes: list[str] | None = None,
+    ) -> str:
+        if not self.client_id:
+            raise SocialProviderUnavailableError(
+                f"{self.provider} OAuth credentials are not configured."
+            )
+        params = {
+            "client_id": self.client_id,
+            "redirect_uri": redirect_uri,
+            "response_type": "code",
+            "state": state,
+            "scope": " ".join(
+                dict.fromkeys(
+                    [*self.capabilities.required_scopes, *(additional_scopes or [])]
+                )
+            ),
+        }
+        if code_challenge:
+            params["code_challenge"] = code_challenge
+            params["code_challenge_method"] = "S256"
+        return f"{self.authorization_endpoint}?{urlencode(params)}"

app/social/providers/registry.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from app.core.config import Settings
+from app.social.domain.enums import Provider
+from app.social.domain.errors import SocialProviderUnavailableError
+from app.social.providers.base import SocialProviderAdapter
+from app.social.providers.facebook import FacebookProvider
+from app.social.providers.instagram import InstagramProvider
+from app.social.providers.linkedin import LinkedInProvider
+from app.social.providers.telegram import TelegramProvider
+from app.social.providers.tiktok import TikTokProvider
+from app.social.providers.whatsapp import WhatsAppProvider
+from app.social.providers.x import XProvider
+from app.social.providers.youtube import YouTubeProvider
+
+
+class ProviderRegistry:
+    def __init__(self, providers: list[SocialProviderAdapter]) -> None:
+        self._providers = {provider.provider: provider for provider in providers}
+
+    def list(self) -> list[SocialProviderAdapter]:
+        return [self._providers[key] for key in sorted(self._providers)]
+
+    def get(self, provider: str | Provider) -> SocialProviderAdapter:
+        key = provider.value if isinstance(provider, Provider) else provider.strip().lower()
+        try:
+            return self._providers[key]
+        except KeyError as exc:
+            raise SocialProviderUnavailableError(f"Unknown social provider '{key}'.") from exc
+
+    async def close(self) -> None:
+        for provider in self._providers.values():
+            close = getattr(provider, "close", None)
+            if close is not None:
+                await close()
+
+
+def build_provider_registry(settings: Settings) -> ProviderRegistry:
+    return ProviderRegistry([
+        YouTubeProvider(settings), FacebookProvider(settings), InstagramProvider(settings),
+        TikTokProvider(settings), XProvider(settings), LinkedInProvider(settings),
+        TelegramProvider(settings), WhatsAppProvider(settings),
+    ])

app/social/providers/telegram.py

@@ -0,0 +1,13 @@
+from app.core.config import Settings
+from app.social.domain.capabilities import ProviderCapabilities
+from app.social.domain.enums import ConnectionStrategy, Provider
+from app.social.providers.base import SocialProviderAdapter
+
+
+class TelegramProvider(SocialProviderAdapter):
+    def __init__(self, settings: Settings) -> None:
+        self.capabilities = ProviderCapabilities(
+            provider=Provider.TELEGRAM, connection_strategy=ConnectionStrategy.TOKEN_BOT,
+            account_types=["bot", "channel"],
+            implementation_status="registered",
+        )

app/social/providers/tiktok.py

@@ -0,0 +1,1131 @@
+"""Official TikTok Login Kit and Content Posting Direct Post adapter."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlencode, urlparse
+
+import aiofiles
+import httpx
+
+from app.core.config import Settings
+from app.social.domain.capabilities import ProviderCapabilities
+from app.social.domain.enums import ConnectionStrategy, Provider
+from app.social.domain.errors import (
+    SocialCapabilityUnsupportedError,
+    SocialMediaInvalidError,
+    SocialPermissionDeniedError,
+    SocialProviderUnavailableError,
+    SocialPublishFailedError,
+    SocialRateLimitedError,
+    SocialReauthRequiredError,
+)
+from app.social.providers.oauth import OAuthFoundationAdapter
+from app.social.security import public_provider_data
+
+_TIKTOK_OPEN_API = "https://open.tiktokapis.com"
+_TOKEN_ENDPOINT = f"{_TIKTOK_OPEN_API}/v2/oauth/token/"
+_REVOKE_ENDPOINT = f"{_TIKTOK_OPEN_API}/v2/oauth/revoke/"
+_USER_INFO_ENDPOINT = f"{_TIKTOK_OPEN_API}/v2/user/info/"
+_CREATOR_INFO_ENDPOINT = f"{_TIKTOK_OPEN_API}/v2/post/publish/creator_info/query/"
+_DIRECT_POST_INIT_ENDPOINT = f"{_TIKTOK_OPEN_API}/v2/post/publish/video/init/"
+_PUBLISH_STATUS_ENDPOINT = f"{_TIKTOK_OPEN_API}/v2/post/publish/status/fetch/"
+_VIDEO_QUERY_ENDPOINT = f"{_TIKTOK_OPEN_API}/v2/video/query/"
+_USER_FIELDS = "open_id,union_id,avatar_url,display_name"
+_VIDEO_ANALYTICS_FIELDS = (
+    "id,create_time,share_url,title,video_description,duration,height,width,"
+    "like_count,comment_count,share_count,view_count"
+)
+_RETRYABLE = frozenset({429, 500, 502, 503, 504})
+_MIN_CHUNK = 5_000_000
+_MAX_CHUNK = 64_000_000
+_MAX_FINAL_CHUNK = 128_000_000
+_MAX_VIDEO_SIZE = 4_000_000_000
+_MAX_VIDEO_DURATION = 600.0
+_CONTENT_RANGE = re.compile(r"bytes\s+0-(\d+)/(\d+)", re.IGNORECASE)
+_MEDIA_FAILURES = frozenset(
+    {
+        "file_format_check_failed",
+        "duration_check_failed",
+        "frame_rate_check_failed",
+        "picture_size_check_failed",
+    }
+)
+
+
+class TikTokProvider(OAuthFoundationAdapter):
+    """TikTok Web Login Kit plus audited Direct Post video publishing."""
+
+    authorization_endpoint = "https://www.tiktok.com/v2/auth/authorize/"
+    pkce_supported = False
+
+    def __init__(
+        self, settings: Settings, *, http_client: httpx.AsyncClient | None = None
+    ) -> None:
+        self.settings = settings
+        self.reconciliation_poll_seconds = settings.tiktok_processing_poll_seconds
+        self.client_id = settings.tiktok_client_key
+        self._client_secret = (
+            settings.tiktok_client_secret.get_secret_value()
+            if settings.tiktok_client_secret
+            else ""
+        )
+        self.redirect_uri = settings.tiktok_redirect_uri.strip()
+        self.configuration_ready = bool(
+            self.client_id and self._client_secret and self.redirect_uri
+        )
+        self._client = http_client or httpx.AsyncClient(
+            timeout=httpx.Timeout(settings.tiktok_request_timeout_seconds),
+            follow_redirects=False,
+        )
+        self._owns_client = http_client is None
+        # Capability advertisement is fail-closed until both the operator gate
+        # and complete backend credentials/callback configuration are present.
+        direct_post = settings.tiktok_direct_post_enabled and self.configuration_ready
+        self.capabilities = ProviderCapabilities(
+            provider=Provider.TIKTOK,
+            connection_strategy=ConnectionStrategy.OAUTH,
+            implementation_status="implemented",
+            account_types=["creator"],
+            required_scopes=["user.info.basic"],
+            optional_scopes=["video.publish", "video.list"],
+            publishing_required_scopes=["video.publish"] if direct_post else [],
+            # TikTok Display API video/query is independently authorized. The
+            # normal connection and publishing flows never request video.list.
+            analytics=self.configuration_ready,
+            analytics_required_scopes=["video.list"] if self.configuration_ready else [],
+            video=direct_post,
+            video_upload=direct_post,
+            video_status=direct_post,
+            direct_publish=direct_post,
+            # MediaRouter dispatches scheduled jobs at the canonical UTC time.
+            # TikTok currently exposes no native scheduling parameter.
+            scheduled_publish=direct_post,
+            native_scheduling=False,
+            delete_post=False,
+            publish_metadata_schema=(
+                {
+                    "namespace": "tiktok",
+                    "media_types": ["video"],
+                    "fields": [
+                        {"name": "title", "label": "Caption", "type": "text", "required": False, "max_length": 2200},
+                        {"name": "privacy_level", "label": "Privacy", "type": "select", "required": True, "options_source": "privacy_level_options"},
+                        {"name": "disable_comment", "label": "Disable comments", "type": "boolean", "required": False},
+                        {"name": "disable_duet", "label": "Disable Duet", "type": "boolean", "required": False},
+                        {"name": "disable_stitch", "label": "Disable Stitch", "type": "boolean", "required": False},
+                        {"name": "brand_content_toggle", "label": "Paid partnership", "type": "boolean", "required": True},
+                        {"name": "brand_organic_toggle", "label": "Promotes own brand", "type": "boolean", "required": True},
+                        {"name": "is_aigc", "label": "AI-generated content", "type": "boolean", "required": True},
+                        {"name": "music_usage_confirmed", "label": "I agree to TikTok's Music Usage Confirmation", "type": "confirmation", "required": True},
+                    ],
+                }
+                if direct_post
+                else {}
+            ),
+        )
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def get_authorization_url(
+        self,
+        *,
+        state: str,
+        redirect_uri: str,
+        code_challenge: str | None = None,
+        additional_scopes: list[str] | None = None,
+    ) -> str:
+        if not self.client_id:
+            raise SocialProviderUnavailableError(
+                "TikTok OAuth credentials are not configured."
+            )
+        scopes = list(
+            dict.fromkeys(
+                [*self.capabilities.required_scopes, *(additional_scopes or [])]
+            )
+        )
+        params = {
+            "client_key": self.client_id,
+            "response_type": "code",
+            "redirect_uri": redirect_uri,
+            "scope": ",".join(scopes),
+            "state": state,
+        }
+        # Login Kit Web is a confidential-client flow and its current official
+        # contract does not define the mobile/desktop code_verifier fields.
+        del code_challenge
+        return f"{self.authorization_endpoint}?{urlencode(params)}"
+
+    async def exchange_code(
+        self, *, code: str, redirect_uri: str, code_verifier: str | None = None
+    ) -> dict[str, Any]:
+        if not self.client_id or not self._client_secret:
+            raise SocialProviderUnavailableError(
+                "TikTok OAuth credentials are not configured."
+            )
+        del code_verifier
+        return await self._token_request(
+            {
+                "client_key": self.client_id,
+                "client_secret": self._client_secret,
+                "code": code,
+                "grant_type": "authorization_code",
+                "redirect_uri": redirect_uri,
+            }
+        )
+
+    async def refresh_token(self, token: dict[str, Any]) -> dict[str, Any]:
+        refresh_token = token.get("refresh_token")
+        if not isinstance(refresh_token, str) or not refresh_token:
+            raise SocialReauthRequiredError(
+                "The TikTok account requires reauthorization."
+            )
+        if not self.client_id or not self._client_secret:
+            raise SocialProviderUnavailableError(
+                "TikTok OAuth credentials are not configured."
+            )
+        return await self._token_request(
+            {
+                "client_key": self.client_id,
+                "client_secret": self._client_secret,
+                "refresh_token": refresh_token,
+                "grant_type": "refresh_token",
+            }
+        )
+
+    async def revoke_token(self, token: dict[str, Any]) -> None:
+        access_token = token.get("access_token")
+        if not isinstance(access_token, str) or not access_token:
+            return
+        if not self.client_id or not self._client_secret:
+            raise SocialProviderUnavailableError(
+                "TikTok OAuth credentials are not configured."
+            )
+        try:
+            response = await self._client.post(
+                _REVOKE_ENDPOINT,
+                data={
+                    "client_key": self.client_id,
+                    "client_secret": self._client_secret,
+                    "token": access_token,
+                },
+            )
+        except httpx.TransportError as exc:
+            raise SocialProviderUnavailableError(
+                "TikTok token revocation is temporarily unavailable."
+            ) from exc
+        if response.is_success:
+            return
+        payload = self._response_payload(response, operation="token revocation")
+        self._raise_tiktok_error(response, payload, operation="token revocation")
+
+    async def get_account(self, token: dict[str, Any]) -> dict[str, Any]:
+        payload = await self._authorized_get(
+            _USER_INFO_ENDPOINT,
+            token,
+            params={"fields": _USER_FIELDS},
+            operation="profile discovery",
+        )
+        data = payload.get("data")
+        user = data.get("user") if isinstance(data, dict) else None
+        if (
+            not isinstance(user, dict)
+            or not isinstance(user.get("open_id"), str)
+            or not user["open_id"]
+        ):
+            raise SocialReauthRequiredError(
+                "TikTok did not return an authenticated account identity."
+            )
+        open_id = user["open_id"]
+        metadata = {
+            "tiktok_open_id": open_id,
+            "tiktok_union_id": (
+                user.get("union_id")
+                if isinstance(user.get("union_id"), str)
+                else None
+            ),
+        }
+        return {
+            "external_account_id": open_id,
+            "account_type": "creator",
+            "username": None,
+            "display_name": (
+                user.get("display_name")
+                if isinstance(user.get("display_name"), str)
+                else None
+            ),
+            "avatar_url": (
+                user.get("avatar_url")
+                if isinstance(user.get("avatar_url"), str)
+                else None
+            ),
+            "metadata": {
+                key: value for key, value in metadata.items() if value is not None
+            },
+        }
+
+    async def get_publish_options(self, token: dict[str, Any]) -> dict[str, Any]:
+        self._ensure_direct_post_enabled()
+        payload = await self._authorized_post(
+            _CREATOR_INFO_ENDPOINT,
+            token,
+            json={},
+            operation="creator information",
+        )
+        data = payload.get("data")
+        if not isinstance(data, dict):
+            raise SocialProviderUnavailableError(
+                "TikTok returned invalid creator publishing options."
+            )
+        privacy = data.get("privacy_level_options")
+        duration = data.get("max_video_post_duration_sec")
+        if not isinstance(privacy, list) or not all(
+            isinstance(item, str) and item for item in privacy
+        ):
+            raise SocialProviderUnavailableError(
+                "TikTok returned invalid creator privacy options."
+            )
+        if (
+            not isinstance(duration, (int, float))
+            or isinstance(duration, bool)
+            or duration <= 0
+        ):
+            raise SocialProviderUnavailableError(
+                "TikTok returned an invalid creator duration limit."
+            )
+        disabled_options: dict[str, bool] = {}
+        for name in ("comment_disabled", "duet_disabled", "stitch_disabled"):
+            value = data.get(name)
+            if not isinstance(value, bool):
+                raise SocialProviderUnavailableError(
+                    "TikTok returned invalid creator interaction options."
+                )
+            disabled_options[name] = value
+        return {
+            "privacy_level_options": privacy,
+            **disabled_options,
+            "max_video_post_duration_sec": min(float(duration), _MAX_VIDEO_DURATION),
+            "creator_username": (
+                data.get("creator_username")
+                if isinstance(data.get("creator_username"), str)
+                else None
+            ),
+            "creator_nickname": (
+                data.get("creator_nickname")
+                if isinstance(data.get("creator_nickname"), str)
+                else None
+            ),
+        }
+
+    async def validate_media(self, media: dict[str, Any]) -> None:
+        self._ensure_direct_post_enabled()
+        path = media.get("path")
+        size = media.get("file_size")
+        mime_type = str(media.get("mime_type") or "").lower()
+        probe = media.get("probe") if isinstance(media.get("probe"), dict) else {}
+        if (
+            not isinstance(path, Path)
+            or not path.is_file()
+            or not os.access(path, os.R_OK)
+        ):
+            raise SocialMediaInvalidError("TikTok media asset is not readable.")
+        try:
+            actual_size = path.stat().st_size
+        except OSError as exc:
+            raise SocialMediaInvalidError(
+                "TikTok media asset is not readable."
+            ) from exc
+        if actual_size != size:
+            raise SocialMediaInvalidError(
+                "TikTok media asset size changed after validation."
+            )
+        maximum = min(self.settings.max_upload_size, _MAX_VIDEO_SIZE)
+        if not isinstance(size, int) or size <= 0 or size > maximum:
+            raise SocialMediaInvalidError(
+                "TikTok video size exceeds the configured or official limit."
+            )
+        if mime_type not in {"video/mp4", "video/quicktime", "video/webm"}:
+            raise SocialMediaInvalidError(
+                "TikTok supports registered MP4, MOV, or WebM video variants."
+            )
+        container = str(probe.get("container") or "").lower()
+        if not any(value in container for value in ("mp4", "quicktime", "webm")):
+            raise SocialMediaInvalidError(
+                "TikTok video container is unsupported; create a compatible MediaRouter variant."
+            )
+        streams = probe.get("video_streams")
+        if (
+            not isinstance(streams, list)
+            or not streams
+            or not isinstance(streams[0], dict)
+        ):
+            raise SocialMediaInvalidError("TikTok media must contain a video stream.")
+        codec = str(streams[0].get("codec") or "").lower()
+        if codec not in {"h264", "hevc", "h265", "vp8", "vp9"}:
+            raise SocialMediaInvalidError(
+                "TikTok video codec is unsupported; create a compatible MediaRouter variant."
+            )
+        duration = probe.get("duration")
+        if (
+            not isinstance(duration, (int, float))
+            or isinstance(duration, bool)
+            or duration <= 0
+            or duration > _MAX_VIDEO_DURATION
+        ):
+            raise SocialMediaInvalidError(
+                "TikTok video duration must be positive and no longer than 10 minutes."
+            )
+        fps = probe.get("fps")
+        if (
+            not isinstance(fps, (int, float))
+            or isinstance(fps, bool)
+            or fps < 23
+            or fps > 60
+        ):
+            raise SocialMediaInvalidError(
+                "TikTok video frame rate must be between 23 and 60 FPS."
+            )
+        resolution = (
+            probe.get("resolution")
+            if isinstance(probe.get("resolution"), dict)
+            else {}
+        )
+        width, height = resolution.get("width"), resolution.get("height")
+        if (
+            not isinstance(width, int)
+            or not isinstance(height, int)
+            or not 360 <= width <= 4096
+            or not 360 <= height <= 4096
+        ):
+            raise SocialMediaInvalidError(
+                "TikTok video width and height must each be between 360 and 4096 pixels."
+            )
+        aspect_ratio = width / height
+        if not 0 < aspect_ratio < float("inf"):
+            raise SocialMediaInvalidError("TikTok video aspect ratio is invalid.")
+        audio_streams = probe.get("audio_streams")
+        if audio_streams is not None and not isinstance(audio_streams, list):
+            raise SocialMediaInvalidError("TikTok audio stream metadata is invalid.")
+        # TikTok does not require an audio track. For present audio, accept the
+        # codecs produced by MediaRouter's compatible MP4/WebM templates.
+        for stream in audio_streams or []:
+            if (
+                not isinstance(stream, dict)
+                or str(stream.get("codec") or "").lower()
+                not in {"aac", "mp3", "opus", "vorbis"}
+            ):
+                raise SocialMediaInvalidError(
+                    "TikTok audio codec is unsupported; create a compatible MediaRouter variant."
+                )
+
+    async def upload_media(
+        self, token: dict[str, Any], media: dict[str, Any]
+    ) -> dict[str, Any]:
+        await self.validate_media(media)
+        path = media["path"]
+        assert isinstance(path, Path)
+        total = int(media["file_size"])
+        post_info = media.get("tiktok_post_info")
+        if not isinstance(post_info, dict):
+            raise SocialPublishFailedError(
+                "Typed TikTok Direct Post metadata is required."
+            )
+        creator = await self.get_publish_options(token)
+        self._validate_post_info(post_info, creator, media)
+        persist = media.get("persist_provider_state")
+        if persist is not None and not callable(persist):
+            raise SocialPublishFailedError(
+                "TikTok provider-state persistence is invalid."
+            )
+        heartbeat = media.get("heartbeat")
+        if heartbeat is not None and not callable(heartbeat):
+            raise SocialPublishFailedError("TikTok upload heartbeat is invalid.")
+        state = (
+            dict(media.get("provider_state"))
+            if isinstance(media.get("provider_state"), dict)
+            else {}
+        )
+        publish_id = state.get("tiktok_publish_id")
+        upload_url = state.get("tiktok_upload_url")
+        chunk_size = state.get("tiktok_chunk_size")
+        chunk_count = state.get("tiktok_chunk_count")
+        if not isinstance(publish_id, str) or not publish_id:
+            if state.get("tiktok_init_started"):
+                # TikTok has no client idempotency key or lookup-by-client-key
+                # endpoint. Never repeat an init whose accepted outcome could
+                # not be durably identified.
+                raise SocialPublishFailedError(
+                    "TikTok initialization outcome is unavailable; duplicate publishing was prevented."
+                )
+            if persist:
+                await persist(
+                    {
+                        "tiktok_init_started": True,
+                        "tiktok_video_size": total,
+                    }
+                )
+            chunk_size, chunk_count = self._chunk_plan(total)
+            payload = await self._authorized_post(
+                _DIRECT_POST_INIT_ENDPOINT,
+                token,
+                json={
+                    "post_info": post_info,
+                    "source_info": {
+                        "source": "FILE_UPLOAD",
+                        "video_size": total,
+                        "chunk_size": chunk_size,
+                        "total_chunk_count": chunk_count,
+                    },
+                },
+                operation="Direct Post initialization",
+            )
+            data = payload.get("data")
+            if not isinstance(data, dict):
+                raise SocialProviderUnavailableError(
+                    "TikTok did not return a Direct Post upload session."
+                )
+            publish_id = data.get("publish_id")
+            upload_url = data.get("upload_url")
+            if not isinstance(publish_id, str) or not publish_id:
+                raise SocialProviderUnavailableError(
+                    "TikTok did not return a Direct Post publish ID."
+                )
+            if not isinstance(upload_url, str) or not self._is_upload_url(upload_url):
+                raise SocialProviderUnavailableError(
+                    "TikTok did not return a trusted upload URL."
+                )
+            state = {
+                "tiktok_init_started": True,
+                "tiktok_publish_id": publish_id,
+                "tiktok_upload_url": upload_url,
+                "tiktok_video_size": total,
+                "tiktok_chunk_size": chunk_size,
+                "tiktok_chunk_count": chunk_count,
+                "tiktok_uploaded_bytes": 0,
+            }
+            if persist:
+                await persist(state)
+        else:
+            if state.get("tiktok_video_size") != total:
+                raise SocialMediaInvalidError(
+                    "TikTok retry media does not match the initialized upload."
+                )
+            status = await self.get_publish_status(token, publish_id)
+            if status["status"] == "published":
+                return {"id": publish_id, "metadata": status.get("metadata", {})}
+            if status["status"] == "failed":
+                raise self.publish_failure(status)
+            uploaded = status.get("metadata", {}).get("uploaded_bytes")
+            if isinstance(uploaded, int) and uploaded >= total:
+                return {"id": publish_id}
+            if isinstance(uploaded, int) and uploaded >= 0:
+                state["tiktok_uploaded_bytes"] = uploaded
+
+        if not isinstance(upload_url, str) or not self._is_upload_url(upload_url):
+            raise SocialProviderUnavailableError(
+                "TikTok upload session cannot be safely resumed."
+            )
+        if not isinstance(chunk_size, int) or not isinstance(chunk_count, int):
+            raise SocialProviderUnavailableError(
+                "TikTok upload session has invalid chunk metadata."
+            )
+        position = state.get("tiktok_uploaded_bytes", 0)
+        if not isinstance(position, int) or position < 0 or position > total:
+            raise SocialProviderUnavailableError(
+                "TikTok returned an invalid upload position."
+            )
+        if position < total and position % chunk_size != 0:
+            raise SocialProviderUnavailableError(
+                "TikTok upload position cannot be safely resumed."
+            )
+        try:
+            await self._upload_chunks(
+                token=token,
+                publish_id=publish_id,
+                upload_url=upload_url,
+                path=path,
+                mime_type=str(media["mime_type"]),
+                total=total,
+                chunk_size=chunk_size,
+                chunk_count=chunk_count,
+                position=position,
+                persist=persist,
+                state=state,
+                heartbeat=heartbeat,
+            )
+        except OSError as exc:
+            raise SocialMediaInvalidError(
+                "TikTok media asset could not be read during upload."
+            ) from exc
+        return {"id": publish_id}
+
+    async def publish(
+        self, token: dict[str, Any], payload: dict[str, Any]
+    ) -> dict[str, Any]:
+        del token
+        upload = payload.get("upload")
+        if not isinstance(upload, dict) or not isinstance(upload.get("id"), str):
+            raise SocialPublishFailedError(
+                "TikTok upload did not return a publish ID."
+            )
+        # Direct Post is initiated by /video/init and starts processing after
+        # the final upload chunk. There is no second publish endpoint.
+        return dict(upload)
+
+    async def get_publish_status(
+        self, token: dict[str, Any], external_id: str
+    ) -> dict[str, Any]:
+        self._ensure_direct_post_enabled()
+        response = await self._authorized_request(
+            "POST",
+            _PUBLISH_STATUS_ENDPOINT,
+            token,
+            json={"publish_id": external_id},
+        )
+        payload = self._response_payload(response, operation="publish status")
+        error = payload.get("error")
+        code = str(error.get("code", "")).lower() if isinstance(error, dict) else ""
+        if response.status_code == 400 and code == "invalid_publish_id":
+            return {
+                "id": external_id,
+                "status": "unavailable",
+                "metadata": {"provider_status": "INVALID_PUBLISH_ID"},
+            }
+        self._raise_tiktok_error(response, payload, operation="publish status")
+        data = payload.get("data")
+        if not isinstance(data, dict):
+            raise SocialProviderUnavailableError(
+                "TikTok returned an invalid publish status."
+            )
+        provider_status = str(data.get("status") or "").upper()
+        if provider_status == "PUBLISH_COMPLETE":
+            normalized = "published"
+        elif provider_status in {
+            "PROCESSING_UPLOAD",
+            "PROCESSING_DOWNLOAD",
+            "SEND_TO_USER_INBOX",
+        }:
+            normalized = "processing"
+        elif provider_status == "FAILED":
+            normalized = "failed"
+        else:
+            normalized = "unavailable"
+        public_ids = data.get("publicaly_available_post_id")
+        if not isinstance(public_ids, list):
+            # Accept the corrected spelling defensively if TikTok fixes the
+            # long-standing response-field typo without a version bump.
+            public_ids = data.get("publicly_available_post_id")
+        metadata: dict[str, object] = {
+            "provider_status": provider_status or None,
+            "fail_reason": (
+                data.get("fail_reason")
+                if isinstance(data.get("fail_reason"), str)
+                else None
+            ),
+            "uploaded_bytes": (
+                data.get("uploaded_bytes")
+                if isinstance(data.get("uploaded_bytes"), int)
+                else None
+            ),
+            "public_post_ids": (
+                [str(item) for item in public_ids]
+                if isinstance(public_ids, list)
+                else []
+            ),
+        }
+        return {
+            "id": external_id,
+            "status": normalized,
+            "metadata": {
+                key: value for key, value in metadata.items() if value is not None
+            },
+        }
+
+    async def get_metrics(
+        self, token: dict[str, Any], external_id: str
+    ) -> dict[str, Any]:
+        """Return only TikTok video metrics documented by Display API v2.
+
+        `external_id` must be the publicly available video ID returned by the
+        Content Posting status endpoint, not the private Direct Post
+        `publish_id`. AnalyticsService resolves that identity from safe target
+        metadata before calling this adapter.
+        """
+
+        if not self.configuration_ready:
+            raise SocialCapabilityUnsupportedError(
+                "TikTok analytics are unavailable until the provider is configured."
+            )
+        if not external_id or len(external_id) > 255:
+            raise SocialPublishFailedError("TikTok analytics video ID is invalid.")
+        response = await self._authorized_request(
+            "POST",
+            _VIDEO_QUERY_ENDPOINT,
+            token,
+            params={"fields": _VIDEO_ANALYTICS_FIELDS},
+            json={"filters": {"video_ids": [external_id]}},
+        )
+        payload = self._response_payload(response, operation="video analytics")
+        self._raise_tiktok_error(response, payload, operation="video analytics")
+        data = payload.get("data")
+        videos = data.get("videos") if isinstance(data, dict) else None
+        if not isinstance(videos, list):
+            raise SocialProviderUnavailableError(
+                "TikTok returned an invalid video analytics response."
+            )
+        video = next(
+            (
+                item
+                for item in videos
+                if isinstance(item, dict) and str(item.get("id") or "") == external_id
+            ),
+            None,
+        )
+        if video is None:
+            return {
+                "status": "unavailable",
+                "reason": "TIKTOK_VIDEO_NOT_AVAILABLE_TO_AUTHORIZED_USER",
+            }
+
+        result: dict[str, Any] = {
+            "status": "available",
+            "raw_metrics": public_provider_data(dict(video)),
+        }
+        for provider_name, normalized_name in (
+            ("view_count", "views"),
+            ("like_count", "likes"),
+            ("comment_count", "comments"),
+            ("share_count", "shares"),
+        ):
+            value = video.get(provider_name)
+            if isinstance(value, int) and not isinstance(value, bool) and value >= 0:
+                result[normalized_name] = value
+        created = video.get("create_time")
+        if isinstance(created, int) and not isinstance(created, bool) and created >= 0:
+            result["published_at"] = created
+        if isinstance(video.get("share_url"), str):
+            result["url"] = video["share_url"]
+        return result
+
+    def publish_failure(self, result: dict[str, Any]) -> Exception:
+        metadata = result.get("metadata") if isinstance(result.get("metadata"), dict) else {}
+        reason = str(metadata.get("fail_reason") or "").lower()
+        if reason in _MEDIA_FAILURES:
+            return SocialMediaInvalidError(
+                "TikTok rejected media that does not meet its current restrictions."
+            )
+        if reason == "auth_removed":
+            return SocialReauthRequiredError(
+                "The TikTok account requires reauthorization."
+            )
+        if reason in {"internal", "video_pull_failed", "photo_pull_failed"}:
+            return SocialProviderUnavailableError(
+                "TikTok publishing is temporarily unavailable."
+            )
+        if result.get("status") == "unavailable":
+            return SocialProviderUnavailableError(
+                "TikTok publish status is unavailable."
+            )
+        return SocialPublishFailedError(
+            "TikTok rejected the publishing request."
+        )
+
+    async def _upload_chunks(
+        self,
+        *,
+        token: dict[str, Any],
+        publish_id: str,
+        upload_url: str,
+        path: Path,
+        mime_type: str,
+        total: int,
+        chunk_size: int,
+        chunk_count: int,
+        position: int,
+        persist: Any,
+        state: dict[str, object],
+        heartbeat: Any,
+    ) -> None:
+        async with aiofiles.open(path, "rb") as source:
+            await source.seek(position)
+            while position < total:
+                if heartbeat:
+                    await heartbeat()
+                index = position // chunk_size
+                if index >= chunk_count:
+                    raise SocialProviderUnavailableError(
+                        "TikTok upload exceeded its initialized chunk count."
+                    )
+                length = total - position if index == chunk_count - 1 else chunk_size
+                if length <= 0 or length > _MAX_FINAL_CHUNK:
+                    raise SocialProviderUnavailableError(
+                        "TikTok upload chunk plan is invalid."
+                    )
+                chunk = await source.read(length)
+                if len(chunk) != length:
+                    raise SocialMediaInvalidError(
+                        "TikTok upload file ended before its registered size."
+                    )
+                position = await self._put_chunk(
+                    token=token,
+                    publish_id=publish_id,
+                    upload_url=upload_url,
+                    chunk=chunk,
+                    start=position,
+                    total=total,
+                    mime_type=mime_type,
+                )
+                await source.seek(position)
+                state["tiktok_uploaded_bytes"] = position
+                if persist:
+                    await persist(state)
+
+    async def _put_chunk(
+        self,
+        *,
+        token: dict[str, Any],
+        publish_id: str,
+        upload_url: str,
+        chunk: bytes,
+        start: int,
+        total: int,
+        mime_type: str,
+    ) -> int:
+        end = start + len(chunk) - 1
+        for attempt in range(4):
+            try:
+                response = await self._client.put(
+                    upload_url,
+                    content=chunk,
+                    headers={
+                        "Content-Type": mime_type,
+                        "Content-Length": str(len(chunk)),
+                        "Content-Range": f"bytes {start}-{end}/{total}",
+                    },
+                )
+            except (httpx.TimeoutException, httpx.RequestError) as exc:
+                reconciled = await self._reconcile_uploaded_bytes(
+                    token, publish_id, start
+                )
+                if reconciled > start:
+                    return reconciled
+                if attempt == 3:
+                    raise SocialProviderUnavailableError(
+                        "TikTok upload chunk could not be delivered."
+                    ) from exc
+                await asyncio.sleep(2**attempt)
+                continue
+            if response.status_code == 201:
+                return total
+            if response.status_code == 206:
+                received = self._range_position(response.headers.get("Content-Range"))
+                next_position = received if received is not None else end + 1
+                if next_position != end + 1:
+                    raise SocialProviderUnavailableError(
+                        "TikTok returned an inconsistent upload byte range."
+                    )
+                return next_position
+            if response.status_code in _RETRYABLE:
+                reconciled = await self._reconcile_uploaded_bytes(
+                    token, publish_id, start
+                )
+                if reconciled > start:
+                    return reconciled
+                if attempt < 3:
+                    await asyncio.sleep(2**attempt)
+                    continue
+                raise SocialProviderUnavailableError(
+                    "TikTok upload is temporarily unavailable."
+                )
+            if response.status_code == 401:
+                raise SocialReauthRequiredError(
+                    "The TikTok upload session requires reauthorization."
+                )
+            if response.status_code in {403, 404}:
+                if response.status_code == 403:
+                    raise SocialPermissionDeniedError(
+                        "TikTok denied permission to upload this post."
+                    )
+                raise SocialPublishFailedError(
+                    "TikTok upload session expired before completion."
+                )
+            if response.status_code in {400, 416}:
+                raise SocialMediaInvalidError(
+                    "TikTok rejected the upload byte range or media chunk."
+                )
+            raise SocialPublishFailedError("TikTok upload request failed.")
+        raise SocialProviderUnavailableError(
+            "TikTok upload retry budget was exhausted."
+        )
+
+    async def _reconcile_uploaded_bytes(
+        self, token: dict[str, Any], publish_id: str, fallback: int
+    ) -> int:
+        status = await self.get_publish_status(token, publish_id)
+        metadata = (
+            status.get("metadata")
+            if isinstance(status.get("metadata"), dict)
+            else {}
+        )
+        uploaded = metadata.get("uploaded_bytes")
+        return uploaded if isinstance(uploaded, int) and uploaded >= 0 else fallback
+
+    async def _token_request(self, form: dict[str, str]) -> dict[str, Any]:
+        try:
+            response = await self._client.post(_TOKEN_ENDPOINT, data=form)
+        except httpx.TransportError as exc:
+            raise SocialProviderUnavailableError(
+                "TikTok OAuth is temporarily unavailable."
+            ) from exc
+        payload = self._response_payload(response, operation="OAuth")
+        self._raise_tiktok_error(response, payload, operation="OAuth")
+        if not isinstance(payload.get("access_token"), str) or not payload["access_token"]:
+            raise SocialReauthRequiredError("TikTok did not return an access token.")
+        return payload
+
+    async def _authorized_get(
+        self,
+        url: str,
+        token: dict[str, Any],
+        *,
+        params: dict[str, str],
+        operation: str,
+    ) -> dict[str, Any]:
+        response = await self._authorized_request(
+            "GET", url, token, params=params
+        )
+        payload = self._response_payload(response, operation=operation)
+        self._raise_tiktok_error(response, payload, operation=operation)
+        return payload
+
+    async def _authorized_post(
+        self,
+        url: str,
+        token: dict[str, Any],
+        *,
+        json: dict[str, object],
+        operation: str,
+    ) -> dict[str, Any]:
+        response = await self._authorized_request(
+            "POST", url, token, json=json
+        )
+        payload = self._response_payload(response, operation=operation)
+        self._raise_tiktok_error(response, payload, operation=operation)
+        return payload
+
+    async def _authorized_request(
+        self,
+        method: str,
+        url: str,
+        token: dict[str, Any],
+        **kwargs: Any,
+    ) -> httpx.Response:
+        access_token = self._access_token(token)
+        headers = dict(kwargs.pop("headers", {}))
+        headers["Authorization"] = f"Bearer {access_token}"
+        headers.setdefault("Content-Type", "application/json; charset=UTF-8")
+        try:
+            return await self._client.request(
+                method, url, headers=headers, **kwargs
+            )
+        except httpx.TransportError as exc:
+            raise SocialProviderUnavailableError(
+                "TikTok provider request is temporarily unavailable."
+            ) from exc
+
+    def _validate_post_info(
+        self,
+        post_info: dict[str, object],
+        creator: dict[str, Any],
+        media: dict[str, Any],
+    ) -> None:
+        privacy = post_info.get("privacy_level")
+        options = creator.get("privacy_level_options")
+        if not isinstance(options, list) or privacy not in options:
+            raise SocialPermissionDeniedError(
+                "The selected TikTok privacy level is unavailable for this creator."
+            )
+        for field in ("comment", "duet", "stitch"):
+            if creator.get(f"{field}_disabled") and not post_info.get(
+                f"disable_{field}"
+            ):
+                raise SocialPermissionDeniedError(
+                    f"TikTok requires {field} to remain disabled for this creator."
+                )
+        probe = media.get("probe") if isinstance(media.get("probe"), dict) else {}
+        duration = probe.get("duration")
+        maximum = creator.get("max_video_post_duration_sec")
+        if (
+            isinstance(duration, (int, float))
+            and isinstance(maximum, (int, float))
+            and duration > maximum
+        ):
+            raise SocialMediaInvalidError(
+                "TikTok video exceeds this creator's current duration limit."
+            )
+        cover = post_info.get("video_cover_timestamp_ms")
+        if (
+            isinstance(cover, int)
+            and isinstance(duration, (int, float))
+            and cover >= duration * 1000
+        ):
+            raise SocialMediaInvalidError(
+                "TikTok cover timestamp must fall within the video duration."
+            )
+
+        if (
+            post_info.get("brand_content_toggle")
+            and privacy != "PUBLIC_TO_EVERYONE"
+        ):
+            raise SocialPermissionDeniedError(
+                "TikTok branded content requires public visibility."
+            )
+
+    def _ensure_direct_post_enabled(self) -> None:
+        if (
+            not self.settings.tiktok_direct_post_enabled
+            or not self.configuration_ready
+        ):
+            raise SocialCapabilityUnsupportedError(
+                "TikTok Direct Post is not enabled for this approved application."
+            )
+
+    def _chunk_plan(self, total: int) -> tuple[int, int]:
+        if total <= _MAX_CHUNK:
+            return total, 1
+        chunk_size = min(
+            max(_MIN_CHUNK, self.settings.tiktok_upload_chunk_bytes), _MAX_CHUNK
+        )
+        count = total // chunk_size
+        final_size = total - (count - 1) * chunk_size
+        if count < 1 or count > 1000 or final_size > _MAX_FINAL_CHUNK:
+            raise SocialMediaInvalidError(
+                "TikTok video cannot be represented by a supported upload chunk plan."
+            )
+        return chunk_size, count
+
+    @staticmethod
+    def _range_position(value: str | None) -> int | None:
+        if not value:
+            return None
+        match = _CONTENT_RANGE.search(value)
+        return int(match.group(1)) + 1 if match else None
+
+    @staticmethod
+    def _is_upload_url(value: str) -> bool:
+        parsed = urlparse(value)
+        return (
+            parsed.scheme == "https"
+            and parsed.username is None
+            and parsed.password is None
+            and parsed.hostname is not None
+            and parsed.hostname == "open-upload.tiktokapis.com"
+            and parsed.path.startswith("/video/")
+        )
+
+    @staticmethod
+    def _access_token(token: dict[str, Any]) -> str:
+        access_token = token.get("access_token")
+        if not isinstance(access_token, str) or not access_token:
+            raise SocialReauthRequiredError(
+                "The TikTok account requires reauthorization."
+            )
+        return access_token
+
+    @staticmethod
+    def _response_payload(
+        response: httpx.Response, *, operation: str
+    ) -> dict[str, Any]:
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise SocialProviderUnavailableError(
+                f"TikTok returned an invalid {operation} response."
+            ) from exc
+        if not isinstance(payload, dict):
+            raise SocialProviderUnavailableError(
+                f"TikTok returned an invalid {operation} response."
+            )
+        return payload
+
+    @staticmethod
+    def _raise_tiktok_error(
+        response: httpx.Response, payload: dict[str, Any], *, operation: str
+    ) -> None:
+        error = payload.get("error")
+        if isinstance(error, dict):
+            code = str(error.get("code", "")).lower()
+        elif isinstance(error, str):
+            code = error.lower()
+        else:
+            code = ""
+        if response.is_success and code in {"", "ok"}:
+            return
+        if response.status_code == 401 or code in {
+            "access_token_invalid",
+            "access_token_expired",
+            "authorization_revoked",
+            "auth_removed",
+            "invalid_grant",
+            "invalid_code",
+            "invalid_token",
+        }:
+            raise SocialReauthRequiredError(
+                "The TikTok account requires reauthorization."
+            )
+        if operation == "OAuth" and response.status_code == 400:
+            if code in {"access_denied", "invalid_scope"}:
+                raise SocialPermissionDeniedError(
+                    "TikTok OAuth authorization was denied."
+                )
+            if code in {"invalid_request", "invalid_authorization_code"}:
+                raise SocialReauthRequiredError(
+                    "The TikTok authorization code is invalid or expired."
+                )
+        if response.status_code == 403 or code in {
+            "scope_not_authorized",
+            "permission_denied",
+            "access_not_allowed",
+            "token_not_authorized_for_specified_publish_id",
+        }:
+            raise SocialPermissionDeniedError(
+                f"TikTok {operation} permission was denied."
+            )
+        if response.status_code == 429 or "rate" in code or "quota" in code:
+            raise SocialRateLimitedError(
+                f"TikTok {operation} rate limit reached."
+            )
+        if response.status_code >= 500 or code in {
+            "internal",
+            "internal_error",
+            "server_error",
+        }:
+            raise SocialProviderUnavailableError(
+                f"TikTok {operation} is temporarily unavailable."
+            )
+        if code in _MEDIA_FAILURES or code in {
+            "invalid_file_upload",
+            "video_size_check_failed",
+        }:
+            raise SocialMediaInvalidError(
+                "TikTok rejected media that does not meet its restrictions."
+            )
+        if response.status_code == 400 or code in {
+            "invalid_param",
+            "invalid_request",
+            "spam_risk",
+            "spam_risk_text",
+            "spam_risk_too_many_posts",
+            "spam_risk_user_banned_from_posting",
+        }:
+            raise SocialPublishFailedError(
+                f"TikTok rejected the {operation} request."
+            )
+        raise SocialProviderUnavailableError(
+            f"TikTok {operation} request was rejected."
+        )

app/social/providers/whatsapp.py

@@ -0,0 +1,13 @@
+from app.core.config import Settings
+from app.social.domain.capabilities import ProviderCapabilities
+from app.social.domain.enums import ConnectionStrategy, Provider
+from app.social.providers.base import SocialProviderAdapter
+
+
+class WhatsAppProvider(SocialProviderAdapter):
+    def __init__(self, settings: Settings) -> None:
+        self.capabilities = ProviderCapabilities(
+            provider=Provider.WHATSAPP, connection_strategy=ConnectionStrategy.BUSINESS_API,
+            account_types=["business_account", "phone_number"],
+            implementation_status="registered",
+        )

app/social/providers/x.py

@@ -0,0 +1,15 @@
+from app.core.config import Settings
+from app.social.domain.capabilities import ProviderCapabilities
+from app.social.domain.enums import ConnectionStrategy, Provider
+from app.social.providers.oauth import OAuthFoundationAdapter
+
+
+class XProvider(OAuthFoundationAdapter):
+    authorization_endpoint = "https://twitter.com/i/oauth2/authorize"
+
+    def __init__(self, settings: Settings) -> None:
+        self.client_id = settings.x_client_id
+        self.capabilities = ProviderCapabilities(
+            provider=Provider.X, connection_strategy=ConnectionStrategy.OAUTH,
+            implementation_status="registered", account_types=["user"],
+        )

app/social/providers/youtube.py

@@ -0,0 +1,630 @@
+from __future__ import annotations
+
+import asyncio
+import re
+import time
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlencode, urlparse
+
+import aiofiles
+import httpx
+
+from app.core.config import Settings
+from app.core.logger import get_logger
+from app.social.domain.capabilities import ProviderCapabilities
+from app.social.domain.enums import ConnectionStrategy, Provider
+from app.social.domain.errors import (
+    SocialMediaInvalidError,
+    SocialPermissionDeniedError,
+    SocialProviderQuotaError,
+    SocialProviderUnavailableError,
+    SocialPublishFailedError,
+    SocialRateLimitedError,
+    SocialReauthRequiredError,
+)
+from app.social.providers.oauth import OAuthFoundationAdapter
+
+logger = get_logger(__name__)
+
+_GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token"
+_GOOGLE_REVOKE_URL = "https://oauth2.googleapis.com/revoke"
+_YOUTUBE_API = "https://www.googleapis.com/youtube/v3"
+_YOUTUBE_UPLOAD = "https://www.googleapis.com/upload/youtube/v3/videos"
+_RETRYABLE = frozenset({429, 500, 502, 503, 504})
+_RANGE = re.compile(r"bytes=0-(\d+)")
+
+
+class YouTubeProvider(OAuthFoundationAdapter):
+    """Official YouTube Data API v3 adapter.
+
+    All provider requests use an access token supplied by TokenService through
+    the social worker/service boundary; this class never persists or exposes
+    credentials. Resumable-session URIs enter and leave only encrypted worker
+    state through the callback supplied to ``upload_media``.
+    """
+
+    authorization_endpoint = "https://accounts.google.com/o/oauth2/v2/auth"
+
+    def __init__(
+        self,
+        settings: Settings,
+        *,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.settings = settings
+        self.reconciliation_poll_seconds = settings.youtube_processing_poll_seconds
+        self.client_id = settings.google_client_id
+        self._client_secret = (
+            settings.google_client_secret.get_secret_value()
+            if settings.google_client_secret
+            else ""
+        )
+        self._client = http_client or httpx.AsyncClient(
+            timeout=httpx.Timeout(settings.youtube_request_timeout_seconds),
+            follow_redirects=False,
+        )
+        self._owns_client = http_client is None
+        self._uploads = asyncio.Semaphore(settings.youtube_max_concurrent_uploads)
+        self.capabilities = ProviderCapabilities(
+            provider=Provider.YOUTUBE,
+            connection_strategy=ConnectionStrategy.OAUTH,
+            video=True,
+            video_upload=True,
+            video_status=True,
+            channel_metadata=True,
+            direct_publish=True,
+            # Scheduled posts are dispatched by the existing durable
+            # MediaRouter scheduler. Native YouTube `publishAt` is also typed
+            # and sent when explicitly supplied.
+            scheduled_publish=True,
+            analytics=True,
+            delete_post=True,
+            personal_publishing=True,
+            implementation_status="implemented",
+            account_types=["channel"],
+            required_scopes=["https://www.googleapis.com/auth/youtube.upload"],
+        )
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def get_authorization_url(
+        self,
+        *,
+        state: str,
+        redirect_uri: str,
+        code_challenge: str | None = None,
+        additional_scopes: list[str] | None = None,
+    ) -> str:
+        if not self.client_id:
+            raise SocialProviderUnavailableError("youtube OAuth credentials are not configured.")
+        params = {
+            "client_id": self.client_id,
+            "redirect_uri": redirect_uri,
+            "response_type": "code",
+            "state": state,
+            "scope": " ".join(
+                dict.fromkeys(
+                    [*self.capabilities.required_scopes, *(additional_scopes or [])]
+                )
+            ),
+            # Offline access is necessary for workers to publish after the
+            # browser callback has ended. `prompt=consent` makes reconnecting
+            # an account reliably return a new refresh token.
+            "access_type": "offline",
+            "prompt": "consent",
+            "include_granted_scopes": "false",
+        }
+        if code_challenge:
+            params["code_challenge"] = code_challenge
+            params["code_challenge_method"] = "S256"
+        return f"{self.authorization_endpoint}?{urlencode(params)}"
+
+    async def exchange_code(
+        self, *, code: str, redirect_uri: str, code_verifier: str | None = None
+    ) -> dict[str, Any]:
+        if not self.client_id or not self._client_secret:
+            raise SocialProviderUnavailableError("youtube OAuth credentials are not configured.")
+        if not code_verifier:
+            raise SocialPermissionDeniedError("YouTube OAuth PKCE verification is required.")
+        response = await self._request(
+            "POST",
+            _GOOGLE_TOKEN_URL,
+            data={
+                "code": code,
+                "client_id": self.client_id,
+                "client_secret": self._client_secret,
+                "redirect_uri": redirect_uri,
+                "grant_type": "authorization_code",
+                "code_verifier": code_verifier,
+            },
+            oauth=True,
+        )
+        payload = self._json(response)
+        if not payload.get("access_token"):
+            raise SocialReauthRequiredError("Google did not return an access token.")
+        return payload
+
+    async def refresh_token(self, token: dict[str, Any]) -> dict[str, Any]:
+        refresh_token = token.get("refresh_token")
+        if not isinstance(refresh_token, str) or not refresh_token:
+            raise SocialReauthRequiredError("The YouTube account has no refresh token.")
+        if not self.client_id or not self._client_secret:
+            raise SocialProviderUnavailableError("youtube OAuth credentials are not configured.")
+        response = await self._request(
+            "POST",
+            _GOOGLE_TOKEN_URL,
+            data={
+                "client_id": self.client_id,
+                "client_secret": self._client_secret,
+                "refresh_token": refresh_token,
+                "grant_type": "refresh_token",
+            },
+            oauth=True,
+        )
+        refreshed = self._json(response)
+        if not refreshed.get("access_token"):
+            raise SocialReauthRequiredError("Google did not return a refreshed access token.")
+        # Google normally omits refresh_token on refresh. TokenService merges
+        # it with the existing encrypted credential before persistence.
+        return refreshed
+
+    async def revoke_token(self, token: dict[str, Any]) -> None:
+        value = token.get("refresh_token") or token.get("access_token")
+        if not isinstance(value, str) or not value:
+            return
+        response = await self._client.post(_GOOGLE_REVOKE_URL, data={"token": value})
+        if response.status_code not in {200, 204, 400}:
+            self._raise_provider_error(response)
+
+    async def get_account(self, token: dict[str, Any]) -> dict[str, Any]:
+        response = await self._api_request(
+            "GET",
+            f"{_YOUTUBE_API}/channels",
+            token,
+            params={"part": "snippet", "mine": "true", "maxResults": "1"},
+        )
+        items = self._json(response).get("items")
+        if not isinstance(items, list) or not items or not isinstance(items[0], dict):
+            raise SocialPermissionDeniedError("The authorized Google account has no accessible YouTube channel.")
+        channel = items[0]
+        channel_id = channel.get("id")
+        snippet = channel.get("snippet") if isinstance(channel.get("snippet"), dict) else {}
+        if not isinstance(channel_id, str) or not channel_id:
+            raise SocialPublishFailedError("YouTube returned a channel without a stable channel ID.")
+        thumbnails = snippet.get("thumbnails") if isinstance(snippet.get("thumbnails"), dict) else {}
+        avatar = None
+        for size in ("high", "medium", "default"):
+            candidate = thumbnails.get(size)
+            if isinstance(candidate, dict) and isinstance(candidate.get("url"), str):
+                avatar = candidate["url"]
+                break
+        custom_url = snippet.get("customUrl")
+        return {
+            "external_account_id": channel_id,
+            "account_type": "channel",
+            "display_name": snippet.get("title") if isinstance(snippet.get("title"), str) else channel_id,
+            "username": custom_url if isinstance(custom_url, str) else None,
+            "avatar_url": avatar,
+            "metadata": {
+                "channel_id": channel_id,
+                "published_at": snippet.get("publishedAt"),
+                "country": snippet.get("country"),
+            },
+        }
+
+    async def get_capabilities(self) -> ProviderCapabilities:
+        """Return the exact supported YouTube contract; no inferred features."""
+        return self.capabilities
+
+    async def validate_media(self, media: dict[str, Any]) -> None:
+        path = media.get("path")
+        mime_type = str(media.get("mime_type") or "")
+        size = media.get("file_size")
+        probe = media.get("probe") if isinstance(media.get("probe"), dict) else {}
+        if not isinstance(path, Path) or not path.is_file():
+            raise SocialMediaInvalidError("YouTube media asset is not readable.")
+        if not mime_type.startswith("video/"):
+            raise SocialMediaInvalidError("YouTube accepts video media only.")
+        if not isinstance(size, int) or size <= 0 or size > self.settings.max_upload_size:
+            raise SocialMediaInvalidError("YouTube media file size is invalid or exceeds the configured limit.")
+        container = str(probe.get("container") or "").lower()
+        if not any(value in container for value in ("mp4", "quicktime", "matroska", "webm", "mpeg")):
+            raise SocialMediaInvalidError("YouTube media container is unsupported; create a compatible MediaRouter variant.")
+        video_streams = probe.get("video_streams") if isinstance(probe.get("video_streams"), list) else []
+        if not video_streams:
+            raise SocialMediaInvalidError("YouTube media must contain a video stream.")
+        codec = str(video_streams[0].get("codec") or "").lower() if isinstance(video_streams[0], dict) else ""
+        if codec not in {"h264", "hevc", "vp8", "vp9", "av1", "mpeg4"}:
+            raise SocialMediaInvalidError("YouTube video codec is unsupported; create a compatible MediaRouter variant.")
+        duration = probe.get("duration")
+        if not isinstance(duration, (int, float)) or duration <= 0:
+            raise SocialMediaInvalidError("YouTube media must have a positive duration.")
+        resolution = probe.get("resolution") if isinstance(probe.get("resolution"), dict) else {}
+        width, height = resolution.get("width"), resolution.get("height")
+        if not isinstance(width, int) or not isinstance(height, int) or width < 1 or height < 1:
+            raise SocialMediaInvalidError("YouTube media must have valid dimensions.")
+
+    async def upload_media(self, token: dict[str, Any], media: dict[str, Any]) -> dict[str, Any]:
+        await self.validate_media(media)
+        resource = media.get("youtube_resource")
+        if not isinstance(resource, dict):
+            raise SocialPublishFailedError("Typed YouTube metadata is required to upload a video.")
+        path = media["path"]
+        assert isinstance(path, Path)
+        total = int(media["file_size"])
+        mime_type = str(media["mime_type"])
+        persist_session = media.get("persist_upload_session")
+        if persist_session is not None and not callable(persist_session):
+            raise SocialPublishFailedError("YouTube upload session persistence is invalid.")
+        heartbeat = media.get("heartbeat")
+        if heartbeat is not None and not callable(heartbeat):
+            raise SocialPublishFailedError("YouTube upload heartbeat is invalid.")
+        session_url = media.get("upload_session_url")
+        if session_url is not None and not self._is_google_upload_url(str(session_url)):
+            raise SocialPublishFailedError("Stored YouTube upload session is invalid.")
+
+        async with self._uploads:
+            started = time.monotonic()
+            if isinstance(session_url, str) and session_url:
+                resumed = await self._resume_position(session_url, total, token)
+                if isinstance(resumed, dict):
+                    self._log("youtube_upload_completed", bytes=total, resumed=True, elapsed=time.monotonic() - started)
+                    return self._video_result(resumed)
+                if resumed is None:
+                    session_url = None
+                    if persist_session:
+                        await persist_session(None)
+                else:
+                    position = resumed
+            if not session_url:
+                session_url = await self._initialize_upload(
+                    token,
+                    resource,
+                    total,
+                    mime_type,
+                    bool(media.get("notify_subscribers", True)),
+                )
+                if persist_session:
+                    await persist_session(session_url)
+                position = 0
+            self._log("youtube_upload_started", bytes=total, resumed=position > 0)
+            try:
+                return await self._upload_chunks(
+                    token, session_url, path, total, mime_type, position, heartbeat
+                )
+            except Exception:
+                self._log("youtube_upload_failed", bytes=total, elapsed=time.monotonic() - started)
+                raise
+
+    async def publish(self, token: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:
+        # Video insertion is the publish operation in YouTube Data API v3.
+        # Returning the durable video identifier is deliberately not a claim
+        # that YouTube processing/publication has completed; the worker always
+        # calls get_publish_status before marking a target PUBLISHED.
+        upload = payload.get("upload")
+        if not isinstance(upload, dict) or not isinstance(upload.get("id"), str):
+            raise SocialPublishFailedError("YouTube upload did not return a video ID.")
+        return dict(upload)
+
+    async def get_publish_status(self, token: dict[str, Any], external_id: str) -> dict[str, Any]:
+        response = await self._api_request(
+            "GET",
+            f"{_YOUTUBE_API}/videos",
+            token,
+            params={"part": "snippet,status,processingDetails", "id": external_id},
+        )
+        items = self._json(response).get("items")
+        if not isinstance(items, list) or not items:
+            return {"id": external_id, "status": "deleted", "metadata": {"reason": "not_found"}}
+        video = items[0] if isinstance(items[0], dict) else {}
+        status = video.get("status") if isinstance(video.get("status"), dict) else {}
+        processing = video.get("processingDetails") if isinstance(video.get("processingDetails"), dict) else {}
+        upload_status = str(status.get("uploadStatus") or "")
+        processing_status = str(processing.get("processingStatus") or "")
+        if upload_status in {"failed", "rejected"} or processing_status in {"failed", "terminated"}:
+            normalized = "failed"
+        elif upload_status == "deleted":
+            normalized = "deleted"
+        elif processing_status in {"processing", "uploading"} or upload_status == "uploaded" or upload_status == "processed" and processing_status not in {"succeeded", ""}:
+            normalized = "processing"
+        elif upload_status in {"processed", "uploaded"} or processing_status == "succeeded":
+            normalized = "published"
+        else:
+            normalized = "unavailable"
+        snippet = video.get("snippet") if isinstance(video.get("snippet"), dict) else {}
+        return {
+            "id": str(video.get("id") or external_id),
+            "url": f"https://www.youtube.com/watch?v={video.get('id') or external_id}",
+            "status": normalized,
+            "published_at": snippet.get("publishedAt"),
+            "metadata": {
+                "privacy_status": status.get("privacyStatus"),
+                "upload_status": upload_status or None,
+                "processing_status": processing_status or None,
+                "failure_reason": processing.get("processingFailureReason"),
+                "rejection_reason": status.get("rejectionReason"),
+            },
+        }
+
+    async def delete_post(self, token: dict[str, Any], external_id: str) -> None:
+        try:
+            response = await self._client.request(
+                "DELETE",
+                f"{_YOUTUBE_API}/videos",
+                params={"id": external_id},
+                headers={"Authorization": self._bearer(token)},
+            )
+        except httpx.TimeoutException as exc:
+            raise SocialProviderUnavailableError("YouTube provider request timed out.") from exc
+        except httpx.RequestError as exc:
+            raise SocialProviderUnavailableError("YouTube provider request failed.") from exc
+        # Deletion is idempotent from MediaRouter's perspective. A video that
+        # was already removed must not keep a tenant unable to remove its local
+        # SocialPost record.
+        if response.status_code in {200, 204, 404}:
+            return
+        if response.status_code >= 400:
+            self._raise_provider_error(response)
+
+    async def get_metrics(self, token: dict[str, Any], external_id: str) -> dict[str, Any]:
+        response = await self._api_request(
+            "GET",
+            f"{_YOUTUBE_API}/videos",
+            token,
+            params={"part": "statistics,snippet,status", "id": external_id},
+        )
+        items = self._json(response).get("items")
+        if not isinstance(items, list) or not items:
+            return {"id": external_id, "status": "unavailable", "raw_metrics": {}}
+        video = items[0] if isinstance(items[0], dict) else {}
+        statistics = video.get("statistics") if isinstance(video.get("statistics"), dict) else {}
+        snippet = video.get("snippet") if isinstance(video.get("snippet"), dict) else {}
+        raw = {
+            key: value
+            for key, value in statistics.items()
+            if key in {"viewCount", "likeCount", "commentCount", "favoriteCount"}
+        }
+        return {
+            "id": str(video.get("id") or external_id),
+            "status": "available",
+            "views": self._int(statistics.get("viewCount")),
+            "likes": self._int(statistics.get("likeCount")),
+            "comments": self._int(statistics.get("commentCount")),
+            "published_at": snippet.get("publishedAt"),
+            "raw_metrics": raw,
+        }
+
+    async def _initialize_upload(
+        self,
+        token: dict[str, Any],
+        resource: dict[str, Any],
+        total: int,
+        mime_type: str,
+        notify_subscribers: bool,
+    ) -> str:
+        response = await self._api_request(
+            "POST",
+            _YOUTUBE_UPLOAD,
+            token,
+            params={"uploadType": "resumable", "part": "snippet,status", "notifySubscribers": str(notify_subscribers).lower()},
+            json=resource,
+            headers={
+                "X-Upload-Content-Length": str(total),
+                "X-Upload-Content-Type": mime_type,
+            },
+        )
+        location = response.headers.get("Location")
+        if not location or not self._is_google_upload_url(location):
+            raise SocialPublishFailedError("YouTube did not create a valid resumable upload session.")
+        return location
+
+    async def _resume_position(self, session_url: str, total: int, token: dict[str, Any]) -> int | dict[str, Any] | None:
+        for retry in range(4):
+            try:
+                response = await self._client.put(
+                    session_url,
+                    headers={
+                        "Authorization": self._bearer(token),
+                        "Content-Length": "0",
+                        "Content-Range": f"bytes */{total}",
+                    },
+                )
+            except httpx.TimeoutException as exc:
+                if retry == 3:
+                    raise SocialProviderUnavailableError("YouTube resumable upload status timed out.") from exc
+                await asyncio.sleep(2**retry)
+                continue
+            except httpx.RequestError as exc:
+                if retry == 3:
+                    raise SocialProviderUnavailableError("YouTube resumable upload status could not be reached.") from exc
+                await asyncio.sleep(2**retry)
+                continue
+            if response.status_code in {200, 201}:
+                return self._json(response)
+            if response.status_code == 308:
+                match = _RANGE.fullmatch(response.headers.get("Range", ""))
+                return int(match.group(1)) + 1 if match else 0
+            if response.status_code in {404, 410}:
+                return None
+            if response.status_code in _RETRYABLE and retry < 3:
+                await asyncio.sleep(2**retry)
+                continue
+            self._raise_provider_error(response)
+        raise SocialProviderUnavailableError("YouTube resumable upload status could not be reconciled.")
+
+    async def _upload_chunks(
+        self,
+        token: dict[str, Any],
+        session_url: str,
+        path: Path,
+        total: int,
+        mime_type: str,
+        position: int,
+        heartbeat: Any,
+    ) -> dict[str, Any]:
+        async with aiofiles.open(path, "rb") as media:
+            await media.seek(position)
+            while position < total:
+                if heartbeat is not None:
+                    await heartbeat()
+                chunk = await media.read(min(self.settings.youtube_upload_chunk_bytes, total - position))
+                if not chunk:
+                    raise SocialPublishFailedError("YouTube upload file ended before its registered size.")
+                end = position + len(chunk) - 1
+                response = await self._put_chunk_with_resume(
+                    token, session_url, chunk, position, end, total, mime_type
+                )
+                if isinstance(response, dict):
+                    self._log("youtube_upload_completed", bytes=total)
+                    return self._video_result(response)
+                next_position = response
+                if next_position < position:
+                    raise SocialPublishFailedError("YouTube resumable upload returned an invalid byte range.")
+                position = next_position
+                await media.seek(position)
+        raise SocialPublishFailedError("YouTube upload ended without a video result.")
+
+    async def _put_chunk_with_resume(
+        self, token: dict[str, Any], session_url: str, chunk: bytes, start: int, end: int, total: int, mime_type: str
+    ) -> int | dict[str, Any]:
+        for retry in range(5):
+            try:
+                response = await self._client.put(
+                    session_url,
+                    content=chunk,
+                    headers={
+                        "Authorization": self._bearer(token),
+                        "Content-Type": mime_type,
+                        "Content-Length": str(len(chunk)),
+                        "Content-Range": f"bytes {start}-{end}/{total}",
+                    },
+                )
+            except (httpx.TimeoutException, httpx.RequestError) as exc:
+                if retry == 4:
+                    raise SocialProviderUnavailableError("YouTube upload chunk could not be delivered.") from exc
+                reconciled = await self._resume_position(session_url, total, token)
+                if isinstance(reconciled, dict):
+                    return reconciled
+                if reconciled is None:
+                    raise SocialProviderUnavailableError("YouTube resumable upload session expired.") from exc
+                if reconciled > start:
+                    return reconciled
+                await asyncio.sleep(2**retry)
+                continue
+            if response.status_code in {200, 201}:
+                return self._json(response)
+            if response.status_code == 308:
+                match = _RANGE.fullmatch(response.headers.get("Range", ""))
+                return int(match.group(1)) + 1 if match else 0
+            if response.status_code in _RETRYABLE and retry < 4:
+                reconciled = await self._resume_position(session_url, total, token)
+                if isinstance(reconciled, dict):
+                    return reconciled
+                if reconciled is None:
+                    raise SocialProviderUnavailableError("YouTube resumable upload session expired.")
+                if reconciled > start:
+                    return reconciled
+                await asyncio.sleep(2**retry)
+                continue
+            self._raise_provider_error(response)
+        raise SocialProviderUnavailableError("YouTube upload chunk retry budget was exhausted.")
+
+    async def _api_request(self, method: str, url: str, token: dict[str, Any], **kwargs: Any) -> httpx.Response:
+        headers = dict(kwargs.pop("headers", {}))
+        headers["Authorization"] = self._bearer(token)
+        return await self._request(method, url, headers=headers, **kwargs)
+
+    async def _request(self, method: str, url: str, *, oauth: bool = False, **kwargs: Any) -> httpx.Response:
+        try:
+            response = await self._client.request(method, url, **kwargs)
+        except httpx.TimeoutException as exc:
+            raise SocialProviderUnavailableError("YouTube provider request timed out.") from exc
+        except httpx.RequestError as exc:
+            raise SocialProviderUnavailableError("YouTube provider request failed.") from exc
+        if response.status_code >= 400:
+            self._raise_provider_error(response, oauth=oauth)
+        return response
+
+    @staticmethod
+    def _json(response: httpx.Response) -> dict[str, Any]:
+        try:
+            value = response.json()
+        except ValueError as exc:
+            raise SocialPublishFailedError("YouTube returned an invalid response.") from exc
+        if not isinstance(value, dict):
+            raise SocialPublishFailedError("YouTube returned an invalid response.")
+        return value
+
+    def _raise_provider_error(self, response: httpx.Response, *, oauth: bool = False) -> None:
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = {}
+        error = payload.get("error") if isinstance(payload, dict) else {}
+        detail = error if isinstance(error, dict) else {}
+        reasons = {
+            item.get("reason")
+            for item in detail.get("errors", [])
+            if isinstance(item, dict) and isinstance(item.get("reason"), str)
+        }
+        logger.warning(
+            "youtube_provider_error",
+            extra={
+                "provider": "youtube",
+                "provider_status": response.status_code,
+                "provider_reasons": sorted(reasons),
+                "oauth": oauth,
+            },
+        )
+        # Never pass arbitrary upstream text through. Google messages may
+        # contain user-provided metadata; stable messages remain safe to log.
+        if response.status_code == 401:
+            raise SocialReauthRequiredError("YouTube authorization is no longer valid.")
+        if response.status_code == 403:
+            if reasons & {"quotaExceeded", "dailyLimitExceeded", "userRateLimitExceeded"}:
+                raise SocialProviderQuotaError("YouTube API quota is exhausted.")
+            raise SocialPermissionDeniedError("YouTube denied the requested operation.")
+        if response.status_code == 429:
+            if reasons & {"quotaExceeded", "dailyLimitExceeded"}:
+                raise SocialProviderQuotaError("YouTube API quota is exhausted.")
+            raise SocialRateLimitedError("YouTube rate limit was reached.")
+        if response.status_code in {500, 502, 503, 504}:
+            raise SocialProviderUnavailableError("YouTube is temporarily unavailable.")
+        if oauth and response.status_code == 400:
+            raise SocialReauthRequiredError("Google rejected the OAuth authorization response.")
+        if response.status_code == 400:
+            raise SocialPublishFailedError("YouTube rejected the supplied video metadata or upload request.")
+        raise SocialPublishFailedError("YouTube provider request failed.")
+
+    @staticmethod
+    def _video_result(video: dict[str, Any]) -> dict[str, Any]:
+        video_id = video.get("id")
+        if not isinstance(video_id, str) or not video_id:
+            raise SocialPublishFailedError("YouTube upload completed without a video ID.")
+        return {"id": video_id, "url": f"https://www.youtube.com/watch?v={video_id}"}
+
+    @staticmethod
+    def _bearer(token: dict[str, Any]) -> str:
+        access_token = token.get("access_token")
+        if not isinstance(access_token, str) or not access_token:
+            raise SocialReauthRequiredError("The YouTube account has no access token.")
+        return f"Bearer {access_token}"
+
+    @staticmethod
+    def _is_google_upload_url(value: str) -> bool:
+        parsed = urlparse(value)
+        return parsed.scheme == "https" and parsed.hostname in {"www.googleapis.com", "upload.youtube.com"} and parsed.path.startswith("/upload/youtube/")
+
+    @staticmethod
+    def _int(value: object) -> int | None:
+        try:
+            return int(str(value))
+        except (TypeError, ValueError):
+            return None
+
+    @staticmethod
+    def _log(event: str, **fields: Any) -> None:
+        logger.info(event, extra={"provider": "youtube", **fields})

app/social/repositories/__init__.py

@@ -0,0 +1,6 @@
+from app.social.repositories.accounts import AccountRepository
+from app.social.repositories.jobs import JobRepository
+from app.social.repositories.posts import PostRepository
+from app.social.repositories.tokens import TokenRepository
+
+__all__ = ["AccountRepository", "JobRepository", "PostRepository", "TokenRepository"]

app/social/repositories/accounts.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from sqlalchemy import select
+
+from app.social.database import SocialDatabase
+from app.social.domain.errors import SocialAccountNotFoundError
+from app.social.models import SocialAccount
+
+
+class AccountRepository:
+    def __init__(self, database: SocialDatabase) -> None:
+        self.database = database
+
+    async def list(self, workspace_id: str, *, offset: int = 0, limit: int = 100) -> list[SocialAccount]:
+        async with self.database.session(workspace_id) as session:
+            return list((await session.scalars(select(SocialAccount).where(SocialAccount.workspace_id == workspace_id).order_by(SocialAccount.created_at.desc()).offset(offset).limit(limit))).all())
+
+    async def get(self, workspace_id: str, account_id: str) -> SocialAccount:
+        async with self.database.session(workspace_id) as session:
+            record = await session.scalar(select(SocialAccount).where(SocialAccount.id == account_id, SocialAccount.workspace_id == workspace_id))
+            if record is None:
+                raise SocialAccountNotFoundError("Social account was not found.")
+            return record
+
+    async def create(self, record: SocialAccount) -> SocialAccount:
+        async with self.database.session(record.workspace_id) as session:
+            session.add(record)
+            await session.commit()
+            await session.refresh(record)
+            return record
+
+    async def get_by_external(
+        self, workspace_id: str, provider: str, external_account_id: str
+    ) -> SocialAccount | None:
+        async with self.database.session(workspace_id) as session:
+            return await session.scalar(
+                select(SocialAccount).where(
+                    SocialAccount.workspace_id == workspace_id,
+                    SocialAccount.provider == provider,
+                    SocialAccount.external_account_id == external_account_id,
+                )
+            )
+
+    async def update_connection(
+        self, workspace_id: str, account_id: str, *, account_type: str,
+        username: str | None, display_name: str | None, avatar_url: str | None,
+        metadata: dict[str, object],
+    ) -> SocialAccount:
+        async with self.database.session(workspace_id) as session:
+            record = await session.scalar(
+                select(SocialAccount).where(
+                    SocialAccount.id == account_id,
+                    SocialAccount.workspace_id == workspace_id,
+                )
+            )
+            if record is None:
+                raise SocialAccountNotFoundError("Social account was not found.")
+            record.account_type = account_type
+            record.username = username
+            record.display_name = display_name
+            record.avatar_url = avatar_url
+            record.metadata_json = metadata
+            record.status = "connected"
+            await session.commit()
+            await session.refresh(record)
+            return record
+
+    async def disconnect(self, workspace_id: str, account_id: str) -> SocialAccount:
+        async with self.database.session(workspace_id) as session:
+            record = await session.scalar(select(SocialAccount).where(SocialAccount.id == account_id, SocialAccount.workspace_id == workspace_id))
+            if record is None:
+                raise SocialAccountNotFoundError("Social account was not found.")
+            record.status = "disconnected"
+            await session.commit()
+            return record
+
+    async def set_status(
+        self, workspace_id: str, account_id: str, status: str
+    ) -> SocialAccount:
+        async with self.database.session(workspace_id) as session:
+            record = await session.scalar(
+                select(SocialAccount).where(
+                    SocialAccount.id == account_id,
+                    SocialAccount.workspace_id == workspace_id,
+                )
+            )
+            if record is None:
+                raise SocialAccountNotFoundError("Social account was not found.")
+            record.status = status
+            await session.commit()
+            return record

app/social/repositories/assets.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+
+from app.social.database import SocialDatabase
+from app.social.domain.errors import SocialMediaInvalidError
+from app.social.models import SocialMediaAsset
+
+
+class SocialMediaAssetRepository:
+    def __init__(self, database: SocialDatabase) -> None:
+        self.database = database
+
+    async def get(self, workspace_id: str, asset_id: str) -> SocialMediaAsset:
+        async with self.database.session(workspace_id) as session:
+            record = await session.scalar(
+                select(SocialMediaAsset).where(
+                    SocialMediaAsset.id == asset_id,
+                    SocialMediaAsset.workspace_id == workspace_id,
+                )
+            )
+            if record is None:
+                raise SocialMediaInvalidError("Media asset was not found in this workspace.")
+            return record
+
+    async def list(self, workspace_id: str, *, offset: int = 0, limit: int = 100) -> list[SocialMediaAsset]:
+        async with self.database.session(workspace_id) as session:
+            return list(
+                (
+                    await session.scalars(
+                        select(SocialMediaAsset)
+                        .where(SocialMediaAsset.workspace_id == workspace_id)
+                        .order_by(SocialMediaAsset.created_at.desc())
+                        .offset(offset)
+                        .limit(limit)
+                    )
+                ).all()
+            )
+
+    async def create(self, record: SocialMediaAsset) -> SocialMediaAsset:
+        try:
+            async with self.database.session(record.workspace_id) as session:
+                session.add(record)
+                await session.commit()
+                await session.refresh(record)
+                return record
+        except IntegrityError:
+            async with self.database.session(record.workspace_id) as session:
+                existing = await session.scalar(
+                    select(SocialMediaAsset).where(
+                        SocialMediaAsset.workspace_id == record.workspace_id,
+                        SocialMediaAsset.request_id == record.request_id,
+                        SocialMediaAsset.filename == record.filename,
+                    )
+                )
+                if existing is None:
+                    raise
+                return existing

app/social/repositories/jobs.py

@@ -0,0 +1,287 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+from sqlalchemy import and_, or_, select
+from sqlalchemy.exc import IntegrityError
+
+from app.social.database import SocialDatabase
+from app.social.domain.errors import SocialJobNotFoundError
+from app.social.domain.state_machine import validate_transition
+from app.social.models import SocialJob, SocialJobAttempt
+from app.social.oauth.encryption import TokenCipher
+
+
+class JobRepository:
+    def __init__(self, database: SocialDatabase, cipher: TokenCipher) -> None:
+        self.database = database
+        self.cipher = cipher
+
+    async def list(
+        self, workspace_id: str, *, offset: int = 0, limit: int = 100
+    ) -> list[SocialJob]:
+        async with self.database.session(workspace_id) as session:
+            return list(
+                (
+                    await session.scalars(
+                        select(SocialJob)
+                        .where(SocialJob.workspace_id == workspace_id)
+                        .order_by(SocialJob.created_at.desc())
+                        .offset(offset)
+                        .limit(limit)
+                    )
+                ).all()
+            )
+
+    async def get(self, workspace_id: str, job_id: str) -> SocialJob:
+        async with self.database.session(workspace_id) as session:
+            record = await session.scalar(
+                select(SocialJob).where(
+                    SocialJob.id == job_id, SocialJob.workspace_id == workspace_id
+                )
+            )
+            if record is None:
+                raise SocialJobNotFoundError("Social job was not found.")
+            return record
+
+    async def get_by_idempotency(
+        self, workspace_id: str, idempotency_key: str
+    ) -> SocialJob | None:
+        async with self.database.session(workspace_id) as session:
+            return await session.scalar(
+                select(SocialJob).where(
+                    SocialJob.workspace_id == workspace_id,
+                    SocialJob.idempotency_key == idempotency_key,
+                )
+            )
+
+    async def list_for_post(self, workspace_id: str, post_id: str) -> list[SocialJob]:
+        async with self.database.session(workspace_id) as session:
+            return list(
+                (
+                    await session.scalars(
+                        select(SocialJob).where(
+                            SocialJob.workspace_id == workspace_id,
+                            SocialJob.social_post_id == post_id,
+                        )
+                    )
+                ).all()
+            )
+
+    async def create_many(self, jobs: list[SocialJob]) -> list[SocialJob]:
+        if not jobs:
+            return []
+        try:
+            async with self.database.session(jobs[0].workspace_id) as session:
+                session.add_all(jobs)
+                await session.commit()
+                for record in jobs:
+                    await session.refresh(record)
+                return jobs
+        except IntegrityError:
+            canonical: list[SocialJob] = []
+            for job in jobs:
+                if not job.idempotency_key:
+                    raise
+                record = await self.get_by_idempotency(
+                    job.workspace_id, job.idempotency_key
+                )
+                if record is None:
+                    raise
+                canonical.append(record)
+            return canonical
+
+    async def transition(
+        self,
+        workspace_id: str,
+        job_id: str,
+        status: str,
+        *,
+        error_code: str | None = None,
+        error_message: str | None = None,
+        next_attempt_at: datetime | None = None,
+    ) -> SocialJob:
+        async with self.database.session(workspace_id) as session:
+            record = await session.scalar(
+                select(SocialJob).where(
+                    SocialJob.id == job_id, SocialJob.workspace_id == workspace_id
+                )
+            )
+            if record is None:
+                raise SocialJobNotFoundError("Social job was not found.")
+            destination = validate_transition(record.status, status)
+            record.status = destination.value
+            record.error_code = error_code
+            record.error_message = error_message
+            record.next_attempt_at = next_attempt_at
+            now = datetime.now(timezone.utc)
+            if destination.value == "preparing" and record.started_at is None:
+                record.started_at = now
+            if destination.value in {"published", "failed", "cancelled"}:
+                record.completed_at = now
+            await session.commit()
+            return record
+
+    async def set_provider_state(
+        self, workspace_id: str, job_id: str, state: dict[str, object] | None
+    ) -> None:
+        async with self.database.session(workspace_id) as session:
+            record = await session.scalar(
+                select(SocialJob).where(
+                    SocialJob.id == job_id, SocialJob.workspace_id == workspace_id
+                )
+            )
+            if record is None:
+                raise SocialJobNotFoundError("Social job was not found.")
+            record.provider_state_encrypted = self.cipher.encrypt(state) if state else None
+            await session.commit()
+
+    async def get_provider_state(self, workspace_id: str, job_id: str) -> dict[str, object]:
+        async with self.database.session(workspace_id) as session:
+            record = await session.scalar(
+                select(SocialJob).where(
+                    SocialJob.id == job_id, SocialJob.workspace_id == workspace_id
+                )
+            )
+            if record is None:
+                raise SocialJobNotFoundError("Social job was not found.")
+            value = record.provider_state_encrypted
+        if not value:
+            return {}
+        decoded = self.cipher.decrypt(value)
+        return decoded if isinstance(decoded, dict) else {}
+
+    async def defer_reconciliation(
+        self, workspace_id: str, job_id: str, *, next_attempt_at: datetime
+    ) -> SocialJob:
+        """Keep provider processing in PUBLISHING without counting a retry."""
+        async with self.database.session(workspace_id) as session:
+            record = await session.scalar(
+                select(SocialJob).where(
+                    SocialJob.id == job_id, SocialJob.workspace_id == workspace_id
+                )
+            )
+            if record is None:
+                raise SocialJobNotFoundError("Social job was not found.")
+            if record.status != "publishing":
+                raise SocialJobNotFoundError("Social job is not awaiting provider reconciliation.")
+            record.next_attempt_at = next_attempt_at
+            await session.commit()
+            await session.refresh(record)
+            return record
+
+    async def heartbeat(self, workspace_id: str, job_id: str) -> None:
+        """Renew the active worker lease during a long streaming upload."""
+        async with self.database.session(workspace_id) as session:
+            record = await session.scalar(
+                select(SocialJob).where(
+                    SocialJob.id == job_id, SocialJob.workspace_id == workspace_id
+                )
+            )
+            if record is None:
+                raise SocialJobNotFoundError("Social job was not found.")
+            record.updated_at = datetime.now(timezone.utc)
+            await session.commit()
+
+    async def start_attempt(self, workspace_id: str, job_id: str) -> SocialJobAttempt:
+        async with self.database.session(workspace_id) as session:
+            record = await session.scalar(
+                select(SocialJob).where(
+                    SocialJob.id == job_id, SocialJob.workspace_id == workspace_id
+                )
+            )
+            if record is None:
+                raise SocialJobNotFoundError("Social job was not found.")
+            record.attempt_count += 1
+            attempt = SocialJobAttempt(
+                social_job_id=job_id,
+                attempt_number=record.attempt_count,
+                status="started",
+            )
+            session.add(attempt)
+            await session.commit()
+            await session.refresh(attempt)
+            return attempt
+
+    async def complete_attempt(
+        self,
+        attempt_id: str,
+        *,
+        status: str,
+        error_code: str | None = None,
+        error_message: str | None = None,
+        provider_request_id: str | None = None,
+    ) -> None:
+        async with self.database.session() as session:
+            attempt = await session.get(SocialJobAttempt, attempt_id)
+            if attempt:
+                attempt.status = status
+                attempt.error_code = error_code
+                attempt.error_message = error_message
+                attempt.provider_request_id = provider_request_id
+                attempt.completed_at = datetime.now(timezone.utc)
+                await session.commit()
+
+    async def claim_due(
+        self, *, limit: int = 50, stale_after_seconds: int = 900
+    ) -> list[SocialJob]:
+        now = datetime.now(timezone.utc)
+        stale_before = now - timedelta(seconds=stale_after_seconds)
+        async with self.database.session() as session:
+            active_statuses = ["preparing", "processing", "uploading", "publishing"]
+            statement = (
+                select(SocialJob)
+                .where(
+                    or_(
+                        and_(
+                            SocialJob.status.in_(["queued", "retrying"]),
+                            (
+                                SocialJob.next_attempt_at.is_(None)
+                                | (SocialJob.next_attempt_at <= now)
+                            ),
+                        ),
+                        and_(
+                            SocialJob.status == "publishing",
+                            SocialJob.next_attempt_at.is_not(None),
+                            SocialJob.next_attempt_at <= now,
+                        ),
+                        and_(
+                            SocialJob.status.in_(active_statuses),
+                            SocialJob.updated_at <= stale_before,
+                        ),
+                    )
+                )
+                .order_by(SocialJob.created_at)
+                .limit(limit)
+                .with_for_update(skip_locked=True)
+            )
+            jobs = list((await session.scalars(statement)).all())
+            claimed: list[SocialJob] = []
+            for job in jobs:
+                # A provider-side processing poll is not a failed attempt and
+                # must remain in PUBLISHING. Clear its due timestamp while the
+                # worker owns this reconciliation pass.
+                if job.status == "publishing" and job.next_attempt_at and job.next_attempt_at <= now:
+                    job.next_attempt_at = None
+                    claimed.append(job)
+                    continue
+                if job.status in active_statuses:
+                    if job.attempt_count >= job.max_attempts:
+                        validate_transition(job.status, "failed")
+                        job.status = "failed"
+                        job.error_code = "SOCIAL_WORKER_LEASE_EXPIRED"
+                        job.error_message = "The worker lease expired after the retry limit."
+                        job.completed_at = now
+                        continue
+                    validate_transition(job.status, "retrying")
+                    job.status = "retrying"
+                    job.error_code = "SOCIAL_WORKER_LEASE_EXPIRED"
+                    job.error_message = "The worker lease expired; retrying safely."
+                    job.next_attempt_at = now
+                validate_transition(job.status, "preparing")
+                job.status = "preparing"
+                if job.started_at is None:
+                    job.started_at = now
+                claimed.append(job)
+            await session.commit()
+            return claimed

app/social/repositories/posts.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+
+from app.social.database import SocialDatabase
+from app.social.domain.errors import SocialIdempotencyConflictError, SocialPostNotFoundError
+from app.social.models import (
+    MediaVariant,
+    SocialCampaign,
+    SocialPost,
+    SocialPostTarget,
+    SocialSchedule,
+)
+
+
+class PostRepository:
+    def __init__(self, database: SocialDatabase) -> None:
+        self.database = database
+
+    async def assert_related_resources_owned(
+        self,
+        workspace_id: str,
+        *,
+        campaign_id: str | None,
+        variant_id: str | None,
+    ) -> None:
+        async with self.database.session(workspace_id) as session:
+            if campaign_id:
+                campaign = await session.scalar(
+                    select(SocialCampaign.id).where(
+                        SocialCampaign.id == campaign_id,
+                        SocialCampaign.workspace_id == workspace_id,
+                    )
+                )
+                if campaign is None:
+                    raise SocialPostNotFoundError("Social campaign was not found.")
+            if variant_id:
+                variant = await session.scalar(
+                    select(MediaVariant.id).where(
+                        MediaVariant.id == variant_id,
+                        MediaVariant.workspace_id == workspace_id,
+                    )
+                )
+                if variant is None:
+                    raise SocialPostNotFoundError("Media variant was not found.")
+
+    async def list(
+        self, workspace_id: str, *, offset: int = 0, limit: int = 100
+    ) -> list[tuple[SocialPost, list[SocialPostTarget]]]:
+        async with self.database.session(workspace_id) as session:
+            posts = list(
+                (
+                    await session.scalars(
+                        select(SocialPost)
+                        .where(SocialPost.workspace_id == workspace_id)
+                        .order_by(SocialPost.created_at.desc())
+                        .offset(offset)
+                        .limit(limit)
+                    )
+                ).all()
+            )
+            if not posts:
+                return []
+            targets = list(
+                (
+                    await session.scalars(
+                        select(SocialPostTarget).where(
+                            SocialPostTarget.social_post_id.in_([post.id for post in posts])
+                        )
+                    )
+                ).all()
+            )
+        by_post: dict[str, list[SocialPostTarget]] = {}
+        for target in targets:
+            by_post.setdefault(target.social_post_id, []).append(target)
+        return [(post, by_post.get(post.id, [])) for post in posts]
+
+    async def get(
+        self, workspace_id: str, post_id: str
+    ) -> tuple[SocialPost, list[SocialPostTarget]]:
+        async with self.database.session(workspace_id) as session:
+            post = await session.scalar(
+                select(SocialPost).where(
+                    SocialPost.id == post_id, SocialPost.workspace_id == workspace_id
+                )
+            )
+            if post is None:
+                raise SocialPostNotFoundError("Social post was not found.")
+            targets = list(
+                (
+                    await session.scalars(
+                        select(SocialPostTarget)
+                        .where(SocialPostTarget.social_post_id == post_id)
+                        .order_by(SocialPostTarget.created_at)
+                    )
+                ).all()
+            )
+            return post, targets
+
+    async def get_by_post_id_unscoped(
+        self, post_id: str
+    ) -> tuple[SocialPost, list[SocialPostTarget]]:
+        """Worker-only lookup; API requests must always use the tenant-scoped get."""
+        async with self.database.session() as session:
+            post = await session.get(SocialPost, post_id)
+            if post is None:
+                raise SocialPostNotFoundError("Social post was not found.")
+            targets = list(
+                (
+                    await session.scalars(
+                        select(SocialPostTarget).where(
+                            SocialPostTarget.social_post_id == post_id
+                        )
+                    )
+                ).all()
+            )
+            return post, targets
+
+    async def get_by_idempotency(
+        self, workspace_id: str, idempotency_key: str
+    ) -> tuple[SocialPost, list[SocialPostTarget]] | None:
+        async with self.database.session(workspace_id) as session:
+            post = await session.scalar(
+                select(SocialPost).where(
+                    SocialPost.workspace_id == workspace_id,
+                    SocialPost.idempotency_key == idempotency_key,
+                )
+            )
+        return await self.get(workspace_id, post.id) if post else None
+
+    async def create(
+        self, post: SocialPost, targets: list[SocialPostTarget]
+    ) -> tuple[SocialPost, list[SocialPostTarget]]:
+        try:
+            async with self.database.session(post.workspace_id) as session:
+                session.add(post)
+                await session.flush()
+                for target in targets:
+                    target.social_post_id = post.id
+                    session.add(target)
+                await session.commit()
+                await session.refresh(post)
+                for target in targets:
+                    await session.refresh(target)
+                return post, targets
+        except IntegrityError:
+            if post.idempotency_key:
+                existing = await self.get_by_idempotency(
+                    post.workspace_id, post.idempotency_key
+                )
+                if existing and existing[0].request_fingerprint == post.request_fingerprint:
+                    return existing
+                raise SocialIdempotencyConflictError(
+                    "The idempotency key was already used for a different request."
+                )
+            raise
+
+    async def set_status(
+        self, workspace_id: str, post_id: str, status: str
+    ) -> tuple[SocialPost, list[SocialPostTarget]]:
+        async with self.database.session(workspace_id) as session:
+            post = await session.scalar(
+                select(SocialPost).where(
+                    SocialPost.id == post_id, SocialPost.workspace_id == workspace_id
+                )
+            )
+            if post is None:
+                raise SocialPostNotFoundError("Social post was not found.")
+            post.status = status
+            if status == "published":
+                post.published_at = datetime.now(timezone.utc)
+            await session.commit()
+        return await self.get(workspace_id, post_id)
+
+    async def set_target_status(
+        self,
+        workspace_id: str,
+        target_id: str,
+        status: str,
+        *,
+        error_code: str | None = None,
+        error_message: str | None = None,
+        external_post_id: str | None = None,
+        external_url: str | None = None,
+        provider_metadata: dict[str, object] | None = None,
+    ) -> SocialPostTarget:
+        async with self.database.session(workspace_id) as session:
+            target = await session.scalar(
+                select(SocialPostTarget)
+                .join(SocialPost, SocialPost.id == SocialPostTarget.social_post_id)
+                .where(
+                    SocialPostTarget.id == target_id,
+                    SocialPost.workspace_id == workspace_id,
+                )
+            )
+            if target is None:
+                raise SocialPostNotFoundError("Social post target was not found.")
+            target.status = status
+            target.error_code = error_code
+            target.error_message = error_message
+            target.external_post_id = external_post_id or target.external_post_id
+            target.external_url = external_url or target.external_url
+            if provider_metadata:
+                target.platform_metadata = {
+                    **target.platform_metadata,
+                    "provider": {
+                        **(
+                            target.platform_metadata.get("provider", {})
+                            if isinstance(target.platform_metadata.get("provider"), dict)
+                            else {}
+                        ),
+                        **provider_metadata,
+                    },
+                }
+            if status == "published":
+                target.published_at = datetime.now(timezone.utc)
+            await session.commit()
+            return target
+
+    async def delete(self, workspace_id: str, post_id: str) -> None:
+        post, _ = await self.get(workspace_id, post_id)
+        async with self.database.session(workspace_id) as session:
+            attached = await session.merge(post)
+            await session.delete(attached)
+            await session.commit()
+
+    async def upsert_schedule(
+        self,
+        workspace_id: str,
+        post_id: str,
+        *,
+        scheduled_at: datetime,
+        timezone_name: str,
+    ) -> SocialSchedule:
+        await self.get(workspace_id, post_id)
+        try:
+            return await self._write_schedule(
+                workspace_id, post_id, scheduled_at, timezone_name
+            )
+        except IntegrityError:
+            # Two clients can race to schedule the same post. The unique
+            # constraint remains authoritative; the loser retries as an update.
+            return await self._write_schedule(
+                workspace_id, post_id, scheduled_at, timezone_name
+            )
+
+    async def _write_schedule(
+        self,
+        workspace_id: str,
+        post_id: str,
+        scheduled_at: datetime,
+        timezone_name: str,
+    ) -> SocialSchedule:
+        async with self.database.session(workspace_id) as session:
+            schedule = await session.scalar(
+                select(SocialSchedule)
+                .where(SocialSchedule.social_post_id == post_id)
+                .with_for_update()
+            )
+            if schedule is None:
+                schedule = SocialSchedule(
+                    social_post_id=post_id,
+                    scheduled_at=scheduled_at,
+                    timezone=timezone_name,
+                    status="scheduled",
+                )
+                session.add(schedule)
+            else:
+                schedule.scheduled_at = scheduled_at
+                schedule.timezone = timezone_name
+                schedule.status = "scheduled"
+            post = await session.get(SocialPost, post_id)
+            if post:
+                post.status = "scheduled"
+                post.publish_mode = "schedule"
+            await session.commit()
+            await session.refresh(schedule)
+            return schedule
+
+    async def cancel_schedule(self, workspace_id: str, post_id: str) -> None:
+        await self.get(workspace_id, post_id)
+        async with self.database.session(workspace_id) as session:
+            schedule = await session.scalar(
+                select(SocialSchedule).where(SocialSchedule.social_post_id == post_id)
+            )
+            if schedule:
+                schedule.status = "cancelled"
+            await session.commit()
+
+    async def claim_due_schedules(self, *, limit: int = 100) -> list[SocialSchedule]:
+        now = datetime.now(timezone.utc)
+        async with self.database.session() as session:
+            statement = (
+                select(SocialSchedule)
+                .where(
+                    SocialSchedule.status == "scheduled",
+                    SocialSchedule.scheduled_at <= now,
+                )
+                .order_by(SocialSchedule.scheduled_at)
+                .limit(limit)
+                .with_for_update(skip_locked=True)
+            )
+            records = list((await session.scalars(statement)).all())
+            for record in records:
+                record.status = "queued"
+            await session.commit()
+            return records

app/social/repositories/tokens.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from sqlalchemy import select
+
+from app.social.database import SocialDatabase
+from app.social.domain.errors import SocialAccountNotFoundError
+from app.social.models import SocialAccount, SocialAccountToken
+
+
+class TokenRepository:
+    """Token persistence is intentionally accessible only through TokenService."""
+
+    def __init__(self, database: SocialDatabase) -> None:
+        self.database = database
+
+    async def get(
+        self, workspace_id: str, account_id: str
+    ) -> SocialAccountToken | None:
+        """Return a token record only within its owning tenant context."""
+        async with self.database.session(workspace_id) as session:
+            return await session.scalar(
+                select(SocialAccountToken)
+                .join(
+                    SocialAccount,
+                    SocialAccount.id == SocialAccountToken.social_account_id,
+                )
+                .where(
+                    SocialAccountToken.social_account_id == account_id,
+                    SocialAccount.workspace_id == workspace_id,
+                )
+            )
+
+    async def save(
+        self, workspace_id: str, record: SocialAccountToken
+    ) -> SocialAccountToken:
+        async with self.database.session(workspace_id) as session:
+            owner = await session.scalar(
+                select(SocialAccount.id).where(
+                    SocialAccount.id == record.social_account_id,
+                    SocialAccount.workspace_id == workspace_id,
+                )
+            )
+            if owner is None:
+                raise SocialAccountNotFoundError("Social account was not found.")
+            existing = await session.scalar(
+                select(SocialAccountToken)
+                .join(
+                    SocialAccount,
+                    SocialAccount.id == SocialAccountToken.social_account_id,
+                )
+                .where(
+                    SocialAccountToken.social_account_id == record.social_account_id,
+                    SocialAccount.workspace_id == workspace_id,
+                )
+            )
+            if existing:
+                existing.access_token_secret_id = record.access_token_secret_id
+                existing.refresh_token_secret_id = record.refresh_token_secret_id
+                existing.encrypted_payload = record.encrypted_payload
+                existing.expires_at = record.expires_at
+                existing.scopes = record.scopes
+                existing.token_type = record.token_type
+                existing.last_refreshed_at = datetime.now(timezone.utc)
+                existing.revoked_at = None
+                await session.commit()
+                return existing
+            session.add(record)
+            await session.commit()
+            await session.refresh(record)
+            return record
+
+    async def revoke(self, workspace_id: str, account_id: str) -> None:
+        async with self.database.session(workspace_id) as session:
+            record = await session.scalar(
+                select(SocialAccountToken)
+                .join(
+                    SocialAccount,
+                    SocialAccount.id == SocialAccountToken.social_account_id,
+                )
+                .where(
+                    SocialAccountToken.social_account_id == account_id,
+                    SocialAccount.workspace_id == workspace_id,
+                )
+            )
+            if record:
+                record.revoked_at = datetime.now(timezone.utc)
+                record.encrypted_payload = None
+                await session.commit()