socialcli 0.3.0__py3-none-any.whl

socialctl/saas/billing_reconcile.py

@@ -0,0 +1,127 @@
+"""Canonical Stripe reconciliation: event timestamps never decide access."""
+from socialctl.saas.billing import fixed_price, unavailable, stripe_id
+from socialctl.saas.budget import using_budget
+
+
+def paid_until(billing,customer,subscription,invoices):
+    end=0
+    for invoice in invoices:
+        parent=invoice.get('parent') or {}
+        details=parent.get('subscription_details') or {}
+        if (invoice.get('livemode') is not billing.settings.expected_livemode or invoice.get('customer')!=customer
+                or invoice.get('status')!='paid' or invoice.get('paid_out_of_band')
+                or invoice.get('currency')!='usd'
+                or details.get('subscription')!=subscription['id']):
+            continue
+        lines=invoice.get('lines') or {}
+        data=lines.get('data',[])
+        if lines.get('has_more') is not False:continue
+        matches=[line for line in data if ((line.get('pricing') or {}).get('price_details') or {}).get('price')==billing.settings.price_id]
+        if len(matches)!=1:continue
+        line=matches[0];price=(line.get('pricing') or {}).get('price_details') or {}
+        if line.get('currency')!='usd' or line.get('amount')!=1000 or line.get('quantity')!=1 or price.get('price')!=billing.settings.price_id:continue
+        period=line.get('period') or {}
+        start,finish=period.get('start'),period.get('end')
+        if type(start) not in (int,float) or type(finish) not in (int,float) or not 0<finish-start<=32*86400:continue
+        if start<=billing.clock():end=max(end,finish)
+    return end
+
+
+def reconcile(billing,user_id):
+    with billing.lease(user_id) as (row,token):
+        if not row['customer_id']:return
+        if billing.api('GET','/account').get('id')!=billing.settings.account_id:raise unavailable()
+        customer=billing.customer(user_id,row,token)
+        subscriptions=billing.listing('/subscriptions',{'customer':customer,'status':'all'})
+        ongoing=[s for s in subscriptions if s.get('status') not in {'canceled','incomplete_expired'}]
+        candidates=ongoing or [s for s in subscriptions if s.get('status')=='canceled']
+        status='';end=0;selected=None;cancel=False;review=''
+        if len(ongoing)>1:
+            review='multiple_subscriptions'
+        else:
+            invoices=billing.listing('/invoices',{'customer':customer,'status':'paid'}) if candidates else []
+            for sub in candidates:
+                items=sub.get('items') or {};data=items.get('data',[])
+                valid=(billing.owned(sub,user_id) and sub.get('customer')==customer and items.get('has_more') is False
+                       and len(data)==1 and data[0].get('quantity')==1 and fixed_price(data[0].get('price',{}),billing.settings.price_id,expected_livemode=billing.settings.expected_livemode))
+                if not valid:
+                    review='subscription_mismatch';continue
+                until=paid_until(billing,customer,sub,invoices)
+                if selected is None or until>end:
+                    selected=stripe_id(sub.get('id'),'sub_');status=sub.get('status','')
+                    end=until
+                    # Clover Portal can schedule an explicit cancel_at timestamp
+                    # while cancel_at_period_end remains false. Both mean no renewal.
+                    cancel=(sub.get('cancel_at_period_end') is True
+                            or type(sub.get('cancel_at')) is int and sub['cancel_at']>0)
+                    if sub.get('pause_collection'):status='paused'
+                    if status=='trialing':review='unexpected_stripe_trial'
+        if review and review!='unexpected_stripe_trial':status='';end=0
+        with billing.vault.transaction() as db:
+            current=db.execute('SELECT * FROM saas_billing WHERE user_id=?',(user_id,)).fetchone()
+            user=billing.metadata.user(db,user_id)
+            if not current or current['lease']!=token or current['lease_until']<=billing.clock() or not user or user['deleting']:
+                raise unavailable()
+            db.execute('INSERT OR IGNORE INTO saas_entitlements(user_id) VALUES(?)',(user_id,))
+            db.execute('UPDATE saas_entitlements SET subscription_status=?,paid_until=? WHERE user_id=?',(status,end,user_id))
+            db.execute('UPDATE saas_billing SET subscription_id=?,cancel_at_period_end=?,review=?,sync_due=? WHERE user_id=?',
+                       (selected,int(cancel),review,billing.clock()+300,user_id))
+        return {'status':status,'paid_until':end,'review':review}
+
+
+def run_pending(billing,limit=100,*,budget=None):
+    with using_budget(budget,billing):
+        return _run_pending(billing,limit,budget)
+
+
+def _run_pending(billing,limit,budget):
+    """Run on the isolated five-minute maintenance timer; safe to retry on crash."""
+    from fastapi import HTTPException
+    with billing.vault.transaction() as db:
+        events=[dict(r) for r in db.execute("SELECT * FROM saas_billing_events WHERE state='pending' AND next_attempt<=? ORDER BY next_attempt,received,event_id LIMIT ?",(billing.clock(),limit))]
+        due=[r[0] for r in db.execute('SELECT b.user_id FROM saas_billing b JOIN saas_users u ON u.id=b.user_id WHERE b.customer_id IS NOT NULL AND b.sync_due<=? AND u.deleting=0 ORDER BY b.sync_due,b.user_id LIMIT ?',(billing.clock(),limit))]
+    processed=0;failed=0;visited=set()
+    # Reserve half the phase for periodic reconciliation, even under event load.
+    event_budget=budget.portion(0.5) if budget else None
+    if event_budget:billing.budget=event_budget
+    for event in events:
+        if event_budget and event_budget.expired():break
+        key=(event['account_id'],event['mode'],event['event_id'])
+        with billing.vault.transaction() as db:
+            row=db.execute('SELECT user_id FROM saas_billing WHERE customer_id=?',(event['customer_id'],)).fetchone()
+        if not row:
+            # A customer write may still be in flight. Preserve the event until
+            # that write finishes; unrelated deliveries eventually need review.
+            state='ignored' if billing.clock()-event['received']>86400 else 'pending'
+            if state=='ignored':
+                with billing.vault.read_transaction() as db:
+                    saved=billing.vault.get(db,'saas-stripe-event',':'.join(key))
+                if saved and (saved['payload']['data']['object'].get('metadata') or {}).get('app')=='socialcli':
+                    state='review'
+        else:
+            user_id=row['user_id']
+            try:
+                billing.reconcile(user_id)
+                state='done';processed+=1;visited.add(user_id)
+            except HTTPException:
+                state='pending';failed+=1
+        with billing.vault.transaction() as db:
+            db.execute("UPDATE saas_billing_events SET state=?,next_attempt=? WHERE account_id=? AND mode=? AND event_id=? AND state='pending'",(state,billing.clock()+300,*key))
+            if state in {'done','ignored'}:
+                billing.vault.delete(db,'saas-stripe-event',':'.join(key))
+    if budget:billing.budget=budget
+    for user_id in due:
+        if budget and budget.expired():break
+        if user_id in visited:continue
+        try:
+            billing.reconcile(user_id)
+        except HTTPException:
+            failed+=1
+            with billing.vault.transaction() as db:
+                db.execute('UPDATE saas_billing SET sync_due=? WHERE user_id=? AND lease_until<=?',
+                           (billing.clock()+300,user_id,billing.clock()))
+    with billing.vault.transaction() as db:
+        event_due=db.execute("SELECT count(*) FROM saas_billing_events WHERE state='pending' AND next_attempt<=?",(billing.clock(),)).fetchone()[0]
+        customer_due=db.execute("SELECT count(*) FROM saas_billing b JOIN saas_users u ON u.id=b.user_id WHERE b.customer_id IS NOT NULL AND b.sync_due<=? AND u.deleting=0",(billing.clock(),)).fetchone()[0]
+    return {'processed':processed,'retry_pending':failed,'due':event_due+customer_due,
+            'budget_exhausted':bool(budget and budget.expired())}

socialctl/saas/billing_routes.py

@@ -0,0 +1,27 @@
+"""Account billing actions use the verified browser identity, never body IDs."""
+import asyncio
+from fastapi import Request
+from fastapi.responses import RedirectResponse
+from socialctl.saas.routes import read_form
+
+
+def install_billing_routes(app,billing):
+    app.state.saas_billing=billing
+
+    async def action(request,method):
+        data=await read_form(request,billing.origin)
+        app.state.saas_valid_form(request,data,'saas-account')
+        user=await asyncio.to_thread(app.state.saas_sessions.require_user,request)
+        url=await asyncio.to_thread(method,user.id)
+        response=RedirectResponse(url,status_code=303)
+        # These POSTs only redirect to validated Stripe HTTPS destinations.
+        response.headers['Content-Security-Policy']="default-src 'none'; form-action 'self' https://checkout.stripe.com https://billing.stripe.com; frame-ancestors 'none'; base-uri 'none'"
+        return response
+
+    @app.post('/account/billing/checkout')
+    async def checkout(request:Request):
+        return await action(request,billing.checkout)
+
+    @app.post('/account/billing/portal')
+    async def portal(request:Request):
+        return await action(request,billing.portal)

socialctl/saas/budget.py

@@ -0,0 +1,66 @@
+"""Cooperative maintenance deadlines; the process manager is the hard guard."""
+from contextlib import contextmanager
+import math
+import time
+
+
+class BudgetExpired(Exception):
+    pass
+
+
+class WorkBudget:
+    def __init__(self, seconds, *, clock=time.monotonic):
+        if not math.isfinite(seconds) or seconds < 0:
+            raise ValueError('Invalid maintenance budget.')
+        self.clock = clock
+        self.deadline = clock() + seconds
+
+    def remaining(self):
+        return max(0.0, self.deadline - self.clock())
+
+    def expired(self):
+        return self.remaining() <= 0
+
+    def timeout(self, maximum):
+        remaining = self.remaining()
+        if remaining <= 0:
+            raise BudgetExpired()
+        return min(maximum, remaining)
+
+    def portion(self, fraction):
+        return WorkBudget(self.remaining() * fraction, clock=self.clock)
+
+
+@contextmanager
+def using_budget(budget, *adapters):
+    """Only maintenance-owned synchronous adapters are temporarily constrained."""
+    previous = []
+    try:
+        if budget is not None:
+            for adapter in adapters:
+                if adapter is not None:
+                    previous.append((adapter, getattr(adapter, 'budget', None)))
+                    adapter.budget = budget
+        yield
+    finally:
+        for adapter, original in reversed(previous):
+            adapter.budget = original
+
+
+@contextmanager
+def hard_deadline(seconds=230):
+    """One-shot worker only: end the actual container process, not docker exec.
+
+    Crash-safe durable leases recover on the next run. An SMTP DATA operation
+    interrupted here stays uncertain and must never be replayed automatically.
+    """
+    import os
+    import threading
+    timer=threading.Timer(seconds,lambda:os._exit(124))
+    timer.daemon=True
+    timer.start()
+    try:
+        yield
+    finally:
+        timer.cancel()
+        timer.join()

socialctl/saas/connections.py

@@ -0,0 +1,374 @@
+"""Owner-bound OAuth, browser account selection and recoverable local activation."""
+import asyncio
+import hmac
+import json
+import secrets
+from html import escape
+from fastapi import HTTPException,Request
+from fastapi.responses import HTMLResponse,RedirectResponse
+from pydantic import BaseModel,ConfigDict,Field
+from socialctl.saas import pages
+from socialctl.saas.auth import digest
+from socialctl.saas.pairing import proof,INSTALLATION_SECONDS
+from socialctl.saas.routes import read_form
+from socialctl.saas.access import AccessControl
+from socialctl.saas import renewal, permissions
+from socialctl.connection_service.providers import RefreshFailure
+
+OAUTH_SECONDS=600
+INACTIVITY_SECONDS=90*86400
+
+
+class AttachRequest(BaseModel):
+    model_config=ConfigDict(extra='forbid')
+    platform:str=Field(pattern='^(youtube|facebook|instagram|tiktok)$')
+    brand:str=Field(min_length=1,max_length=80)
+
+
+class OAuthRequest(AttachRequest):
+    poll_challenge:str=Field(pattern='^[0-9a-f]{64}$')
+    management:bool=False
+    analytics:bool=False
+
+
+def safe_account(account):
+    return {k:account[k] for k in ('id','name','page_id') if k in account}
+
+
+class Connections:
+    def __init__(self,metadata,installations,providers,clock):
+        self.metadata,self.vault,self.installations,self.providers,self.clock=metadata,metadata.vault,installations,providers,clock
+        self.access=AccessControl(metadata)
+
+    def owner(self,db,installation_id):
+        installation=self.vault.get(db,'saas-installation',installation_id)
+        if installation is None or installation['expires']<=self.clock():
+            raise HTTPException(401,'installation_revoked: Sign in to SocialCli again.')
+        user_id=installation['payload']['user_id']
+        user=self.metadata.user(db,user_id)
+        if user is None or user['deleting']:
+            raise HTTPException(401,'account_unavailable: Sign in to SocialCli again.')
+        return user_id
+
+    def require_platform(self,db,installation_id,platform):
+        user_id=self.owner(db,installation_id)
+        installation=self.vault.get(db,'saas-installation',installation_id)
+        from socialctl.saas import consent
+        consent.require_privacy(self.metadata,db,user_id)
+        consent.require_assistant(installation['payload'])
+        permissions.require(installation['payload'],platform)
+        if platform=='youtube' and db.execute("SELECT 1 FROM saas_google_revocations WHERE user_id=? AND state='pending' LIMIT 1",(installation['payload']['user_id'],)).fetchone():
+            raise HTTPException(409,'google_revocation_pending: Google disconnect is still finishing. Try connecting again after cleanup completes.')
+
+    def allowed(self,db,user_id,*,new=False):
+        decision=self.access.decision(db,user_id,self.clock())
+        if not decision.allowed and not (new and decision.reason=='trial_not_started'):
+            raise HTTPException(402,'subscription_required: Open your SocialCli account to manage access.')
+        return decision
+
+    def brand(self,db,user_id,label):
+        brand=db.execute('SELECT * FROM saas_brands WHERE user_id=?',(user_id,)).fetchone()
+        if brand and brand['label']!=label:
+            raise HTTPException(409,'brand_limit: This subscription already has a brand. Use its existing name.')
+        return brand
+
+    def authorization(self,db,auth_id,request=None,user=None):
+        record=self.vault.get(db,'authorization',auth_id)
+        if record is None or record['expires']<=self.clock() or 'saas' not in record['payload']:
+            raise HTTPException(404,'authorization_expired: Request a new connection link.')
+        if request is not None and not hmac.compare_digest(record['credential_hash'],proof(request)):
+            raise HTTPException(404,'Authorization unavailable.')
+        owner=self.owner(db,record['payload']['saas']['installation_id'])
+        self.require_platform(db,record['payload']['saas']['installation_id'],record['payload']['platform'])
+        if owner!=record['payload']['saas']['user_id'] or user is not None and owner!=user.id:
+            raise HTTPException(403,'This connection belongs to another account.')
+        return record
+
+    def candidate(self,db,installation_id,user_id,platform,label,account,*,grant=None,existing=None,expected=None):
+        self.require_platform(db,installation_id,platform)
+        connection_id,secret=secrets.token_urlsafe(24),secrets.token_urlsafe(32)
+        data={'installation_id':installation_id,'user_id':user_id,'platform':platform,'brand':label,
+              'account':safe_account(account),'expected_grant':expected,'existing_grant':existing}
+        if grant is not None: data['grant']=grant
+        self.vault.put(db,'saas-candidate',connection_id,data,expires=self.clock()+OAUTH_SECONDS,credential_hash=digest(secret))
+        return {'version':1,'connection_id':connection_id,'connection_secret':secret,'platform':platform,
+                'account':data['account'],'granted_scopes':grant['granted_scopes'] if grant else [],'status':'selected'}
+
+    def capability(self,db,connection_id,request,*,require_slot=True,require_access=True):
+        record=self.vault.get(db,'saas-capability',connection_id)
+        if record is None:
+            candidate=self.vault.get(db,'saas-candidate',connection_id)
+            if candidate and candidate['expires']>self.clock() and hmac.compare_digest(candidate['credential_hash'],proof(request)):
+                raise HTTPException(409,'activation_required: Finish installing this connection.')
+            raise HTTPException(404,'connection_unavailable: Check your SocialCli account.')
+        if record['expires']<=self.clock() or not hmac.compare_digest(record['credential_hash'],proof(request)):
+            raise HTTPException(404,'connection_unavailable: Check your SocialCli account.')
+        data=record['payload']
+        if self.owner(db,data['installation_id'])!=data['user_id']:
+            raise HTTPException(403,'Connection ownership mismatch.')
+        if request.method!='DELETE':
+            from socialctl.saas import consent
+            consent.require_privacy(self.metadata,db,data['user_id'])
+            installation=self.vault.get(db,'saas-installation',data['installation_id'])
+            consent.require_assistant(installation['payload'])
+        if require_access:self.require_platform(db,data['installation_id'],data['platform'])
+        slot=db.execute('SELECT * FROM saas_slots WHERE user_id=? AND platform=?',(data['user_id'],data['platform'])).fetchone()
+        if require_slot and (slot is None or slot['grant_id']!=data['grant_id']):
+            raise HTTPException(409,'connection_replaced: Select the current connection in your SocialCli account.')
+        return record
+
+    def activate(self,connection_id,request):
+        with self.vault.transaction() as db:
+            active=self.vault.get(db,'saas-capability',connection_id)
+            if active:
+                self.capability(db,connection_id,request)
+                return {'version':1,'status':'active'}
+            candidate=self.vault.get(db,'saas-candidate',connection_id)
+            if candidate is None or candidate['expires']<=self.clock() or not hmac.compare_digest(candidate['credential_hash'],proof(request)):
+                raise HTTPException(404,'Connection activation expired.')
+            data=candidate['payload'];user_id=self.owner(db,data['installation_id'])
+            self.require_platform(db,data['installation_id'],data['platform'])
+            if user_id!=data['user_id']: raise HTTPException(403,'Connection ownership mismatch.')
+            self.allowed(db,user_id,new=True)
+            brand=self.brand(db,user_id,data['brand'])
+            current=db.execute('SELECT * FROM saas_slots WHERE user_id=? AND platform=?',(user_id,data['platform'])).fetchone()
+            current_id=current['grant_id'] if current else None
+            if current_id!=data['expected_grant']:
+                raise HTTPException(409,'connection_changed: Another connection changed. Review the current account before retrying.')
+            if data['platform'] in {'facebook','instagram'}:
+                other='instagram' if data['platform']=='facebook' else 'facebook'
+                linked=db.execute('SELECT grant_id FROM saas_slots WHERE user_id=? AND platform=?',(user_id,other)).fetchone()
+                if linked:
+                    other_grant=self.vault.get(db,'saas-grant',linked['grant_id'])
+                    if other_grant is None or other_grant['expires']<=self.clock():
+                        db.execute('DELETE FROM saas_slots WHERE user_id=? AND platform=?',(user_id,other))
+                    else:
+                        wanted=data['account'].get('page_id') if data['platform']=='instagram' else data['account']['id']
+                        have=other_grant['payload']['account'].get('page_id') if other=='instagram' else other_grant['payload']['account']['id']
+                        if wanted!=have: raise HTTPException(409,'page_mismatch: Facebook and Instagram must share the same Page.')
+            if data.get('legacy_id'):
+                from socialctl.saas.migration import legacy_record
+                old=legacy_record(self,db,data['legacy_id'],data['legacy_hash'],data['platform'])
+                if old['payload']['account']!=data['account']:
+                    raise HTTPException(409,'connection_changed: Review the current connection.')
+                data['grant']=old['payload']['grant']
+            if data['existing_grant']:
+                grant_id=data['existing_grant']
+                existing=self.vault.get(db,'saas-grant',grant_id)
+                if existing is None or existing['expires']<=self.clock():
+                    raise HTTPException(409,'connection_inactive: This SocialCli connection expired after inactivity.')
+            else:
+                grant_id=secrets.token_urlsafe(24)
+                self.vault.put(db,'saas-grant',grant_id,{'user_id':user_id,'platform':data['platform'],
+                    'account':data['account'],'grant':data['grant']},expires=self.clock()+INACTIVITY_SECONDS)
+            if brand is None:
+                db.execute('INSERT INTO saas_brands VALUES(?,?,?)',(user_id,secrets.token_urlsafe(24),data['brand']))
+            self.access.activate_trial(db,user_id,self.clock())
+            self.allowed(db,user_id)
+            db.execute('INSERT OR REPLACE INTO saas_slots VALUES(?,?,?)',(user_id,data['platform'],grant_id))
+            self.vault.put(db,'saas-capability',connection_id,{'user_id':user_id,'installation_id':data['installation_id'],
+                'platform':data['platform'],'grant_id':grant_id,'account':data['account']},
+                expires=self.clock()+INSTALLATION_SECONDS,credential_hash=candidate['credential_hash'])
+            self.vault.delete(db,'saas-candidate',connection_id)
+            if data.get('legacy_id'):
+                self.vault.delete(db,'connection',data['legacy_id'])
+                db.execute("DELETE FROM legacy_allowance WHERE kind='connection' AND id=?",(data['legacy_id'],))
+            if current_id and current_id!=grant_id:
+                self.vault.delete(db,'saas-grant',current_id)
+        return {'version':1,'status':'active'}
+
+
+def install_connection_routes(app,settings,metadata,sessions,providers,clock):
+    vault=metadata.vault
+    connections=Connections(metadata,app.state.saas_installations,providers,clock)
+    app.state.saas_connections=connections
+    from socialctl.saas.meta_user import install_meta_user_route
+    install_meta_user_route(app, connections, clock)
+    csrf,valid_form=app.state.saas_csrf,app.state.saas_valid_form
+
+    @app.post('/api/saas/v1/installations/{installation_id}/authorizations',status_code=201)
+    def start(installation_id:str,body:OAuthRequest,request:Request):
+        if body.platform not in settings.providers:
+            raise HTTPException(503,'platform_unavailable: This platform is not configured.')
+        try:
+            providers.scopes(body.platform,management=body.management,analytics=body.analytics)
+        except ValueError:
+            raise HTTPException(400,'These permissions are not available for this platform.') from None
+        auth_id=secrets.token_urlsafe(24)
+        with vault.transaction() as db:
+            installation=connections.installations.require(db,installation_id,request)
+            connections.require_platform(db,installation_id,body.platform)
+            user_id=installation['payload']['user_id']
+            connections.allowed(db,user_id,new=True);connections.brand(db,user_id,body.brand)
+            if not metadata.admit(db,'oauth-installation:'+installation_id,clock(),limit=5):
+                raise HTTPException(429,'Too many connection attempts. Wait a minute.')
+            current=db.execute('SELECT grant_id FROM saas_slots WHERE user_id=? AND platform=?',(user_id,body.platform)).fetchone()
+            data={'platform':body.platform,'status':'pending','management':body.management,'analytics':body.analytics,
+                  'saas':{'user_id':user_id,'installation_id':installation_id,'brand':body.brand,'expected_grant':current['grant_id'] if current else None}}
+            vault.put(db,'authorization',auth_id,data,expires=clock()+OAUTH_SECONDS,credential_hash=body.poll_challenge)
+        return {'version':1,'authorization_id':auth_id,'browser_url':settings.public_url+'/connect/'+auth_id,
+                'expires_in':OAUTH_SECONDS,'poll_interval':2}
+
+    @app.post('/api/saas/v1/installations/{installation_id}/attach',status_code=201)
+    def attach(installation_id:str,body:AttachRequest,request:Request):
+        with vault.transaction() as db:
+            installation=connections.installations.require(db,installation_id,request)
+            connections.require_platform(db,installation_id,body.platform)
+            user_id=installation['payload']['user_id'];connections.allowed(db,user_id);connections.brand(db,user_id,body.brand)
+            slot=db.execute('SELECT grant_id FROM saas_slots WHERE user_id=? AND platform=?',(user_id,body.platform)).fetchone()
+            grant=vault.get(db,'saas-grant',slot['grant_id']) if slot else None
+            if grant is None or grant['expires']<=clock():
+                raise HTTPException(404,'No current connection is available for this platform.')
+            result=connections.candidate(db,installation_id,user_id,body.platform,body.brand,
+                grant['payload']['account'],existing=slot['grant_id'],expected=slot['grant_id'])
+            result['granted_scopes']=grant['payload']['grant']['granted_scopes']
+            return result
+
+    @app.get('/account/connect/{auth_id}',response_class=HTMLResponse)
+    def choose(auth_id:str,request:Request):
+        user=sessions.require_user(request)
+        with vault.transaction() as db:
+            record=connections.authorization(db,auth_id,user=user);data=record['payload']
+            if data['status']!='ready':
+                raise HTTPException(409,'This account selection is unavailable. Return to your assistant.')
+        choices=''
+        for index,account in enumerate(data['result']['accounts']):
+            choices+=f'<label for="choice-{index}"><input id="choice-{index}" name="account_id" type="radio" value="{escape(account["id"],quote=True)}" required> {escape(account.get("name",account["id"]))} <small>({escape(account["id"])})</small></label>'
+        replacement='<p class="status-notice">The existing connection stays active until your assistant finishes installing this replacement.</p>' if data['saas']['expected_grant'] else ''
+        from socialctl.connection_service.landing import PROVIDERS
+        name = PROVIDERS[data['platform']][0]
+        return HTMLResponse(pages.page('Choose your account · ' + name,f'''<p class="eyebrow">REVIEW YOUR CONNECTION</p><h1 id="page-title">Choose your {name} account</h1>
+<p class="description">Connect one {name} account to {escape(data['saas']['brand'])}. Only choose an account you own or manage.</p>{replacement}
+<form method="post" action="/account/connect/{escape(auth_id,quote=True)}" class="form-stack">{pages.hidden('csrf',csrf(request,'select:'+auth_id))}{choices}<button class="primary-button" type="submit">Confirm this account</button></form><p class="expiry-note">Confirming does not publish content.</p>''',platform=data['platform']))
+
+    @app.post('/account/connect/{auth_id}',response_class=HTMLResponse)
+    async def select(auth_id:str,request:Request):
+        form=await read_form(request,settings.public_url);valid_form(request,form,'select:'+auth_id)
+        user=await asyncio.to_thread(sessions.require_user,request)
+        def commit():
+            with vault.transaction() as db:
+                record=connections.authorization(db,auth_id,user=user);data=record['payload']
+                if data['status']!='ready': raise HTTPException(409,'This account selection has already been used.')
+                connections.allowed(db,user.id,new=True)
+                account=next((a for a in data['result']['accounts'] if a['id']==form.get('account_id')),None)
+                if account is None: raise HTTPException(400,'Choose an account authorized by the provider.')
+                grant=json.loads(json.dumps(data['result']['grant']))
+                if data['platform']=='instagram' and account.get('access_token'):
+                    # Broader User credentials remain encrypted server-side.
+                    # Ordinary publishing still receives the selected Page token.
+                    grant['meta_user_grant']=json.loads(json.dumps(data['result']['grant']))
+                if account.get('access_token'): grant['access_token']=account['access_token']
+                owner=data['saas']
+                result=connections.candidate(db,owner['installation_id'],user.id,data['platform'],owner['brand'],account,
+                    grant=grant,expected=owner['expected_grant'])
+                data.pop('result',None);data['selection']=result;data['status']='selected'
+                vault.put(db,'authorization',auth_id,data,expires=record['expires'],credential_hash=record['credential_hash'])
+                return data['platform']
+        platform = await asyncio.to_thread(commit)
+        from socialctl.connection_service.landing import PROVIDERS
+        name = PROVIDERS[platform][0]
+        return HTMLResponse(pages.page('Account confirmed · ' + name,f'<p class="eyebrow">{name.upper()} ACCOUNT CONFIRMED</p><h1 id="page-title">Return to your assistant</h1><p class="description">You can close this page and continue with your assistant.</p><p class="button-note">Keep the SocialCli command running while it finishes connecting your {name} account. No content was published.</p><a class="secondary-button" href="/account/">My Account</a>',platform=platform))
+
+    @app.post('/api/saas/v1/authorizations/{auth_id}/poll')
+    def poll(auth_id:str,request:Request):
+        with vault.read_transaction() as db:
+            data=connections.authorization(db,auth_id,request)['payload']
+            return data['selection'] if data['status']=='selected' else {'version':1,'status':data['status']}
+
+    @app.delete('/api/saas/v1/authorizations/{auth_id}')
+    def cancel(auth_id:str,request:Request):
+        with vault.transaction() as db:
+            data=connections.authorization(db,auth_id,request)['payload']
+            if data.get('selection'): vault.delete(db,'saas-candidate',data['selection']['connection_id'])
+            vault.delete(db,'authorization',auth_id)
+        return {'version':1,'status':'cancelled'}
+
+    @app.post('/api/saas/v1/connections/{connection_id}/activate')
+    def activate(connection_id:str,request:Request):
+        return connections.activate(connection_id,request)
+
+    @app.get('/api/saas/v1/connections/{connection_id}')
+    def status(connection_id:str,request:Request):
+        with vault.read_transaction() as db:
+            cap=connections.capability(db,connection_id,request,require_access=False);data=cap['payload']
+            grant=vault.get(db,'saas-grant',data['grant_id'])
+            if grant is None or grant['expires']<=clock():
+                raise HTTPException(409,'connection_inactive: This SocialCli connection expired after inactivity.')
+            decision=connections.access.decision(db,data['user_id'],clock())
+            renewal_state=renewal.state(grant['payload'],clock())
+            return {'version':1,'platform':data['platform'],'account':data['account'],
+                'expires_at':grant['payload']['grant']['expires_at'],'granted_scopes':grant['payload']['grant']['granted_scopes'],
+                'connection_expires_at':cap['expires'],'needs_reconnect':renewal_state=='reconnect_required',
+                'renewal_status':renewal_state,
+                'data_cleanup_required':renewal_state=='reconnect_required',
+                'access':{'allowed':decision.allowed,'reason':decision.reason,'access_until':decision.access_until}}
+
+    @app.delete('/api/saas/v1/connections/{connection_id}')
+    def disconnect(connection_id:str,request:Request):
+        with vault.transaction() as db:
+            record=connections.capability(db,connection_id,request,require_slot=False,require_access=False);data=record['payload']
+            job=app.state.saas_lifecycle.disconnect_grant(db,data['user_id'],data['platform'],data['grant_id'])
+        from socialctl.saas import revocation
+        if job:
+            from socialctl.saas.budget import WorkBudget
+            revocation.run_revocations(metadata,providers,clock,user_id=data['user_id'],budget=WorkBudget(20))
+        state=revocation.status(metadata,job)
+        return {'version':1,'status':'disconnected','provider_authorization_revoked':state=='complete',
+                'provider_revocation_status':state}
+
+    @app.post('/api/saas/v1/connections/{connection_id}/token')
+    def token(connection_id:str,request:Request,refresh:bool=True):
+        lease=None
+        with vault.transaction() as db:
+            cap=connections.capability(db,connection_id,request);data=cap['payload']
+            connections.allowed(db,data['user_id'])
+            record=vault.get(db,'saas-grant',data['grant_id'])
+            if record is None or record['expires']<=clock():
+                raise HTTPException(409,'connection_inactive: This SocialCli connection expired after inactivity.')
+            if data['platform'] not in settings.providers: raise HTTPException(503,'platform_unavailable: Try again later.')
+            grant=record['payload']['grant']
+            renewal.check(record['payload'],clock(),refresh)
+            if grant['expires_at']<=clock()+60:
+                lease=secrets.token_urlsafe(24)
+                renewal.clear(record['payload'])
+                record['payload']['refresh_lease']=lease
+                record['payload']['refresh_started_at']=clock()
+                vault.put(db,'saas-grant',data['grant_id'],record['payload'],expires=record['expires'])
+        if lease:
+            try:
+                renewed=providers.refresh(data['platform'],grant)
+            except Exception as error:
+                code=error.code if isinstance(error,RefreshFailure) else 'renewal_uncertain'
+                with vault.transaction() as db:
+                    current=vault.get(db,'saas-grant',data['grant_id'])
+                    if current is None or current['payload'].get('refresh_lease')!=lease:
+                        raise HTTPException(409,'connection_changed: Review the current connection.') from None
+                    renewal.record_failure(current['payload'],code,clock())
+                    vault.put(db,'saas-grant',data['grant_id'],current['payload'],expires=current['expires'])
+                renewal.reject(code)
+            with vault.transaction() as db:
+                current=vault.get(db,'saas-grant',data['grant_id'])
+                changed=current is None or current['payload'].get('refresh_lease')!=lease
+                if changed:
+                    # The old queued token may already be revoked or invalidated
+                    # by rotation. Preserve a late token under a separate job.
+                    revoked=data['platform']=='youtube' and db.execute(
+                        "SELECT 1 FROM saas_deletion_tombstones WHERE (kind='user' AND id=?) OR (kind='grant' AND id=?)",
+                        (data['user_id'],data['grant_id'])).fetchone()
+                    if revoked:
+                        from socialctl.saas import revocation
+                        revocation.enqueue(metadata,db,data['grant_id']+':refresh:'+lease,
+                            {'user_id':data['user_id'],'platform':'youtube','grant':renewed},clock())
+                else:
+                    renewal.clear(current['payload']);current['payload']['grant']=renewed
+                    vault.put(db,'saas-grant',data['grant_id'],current['payload'],expires=current['expires'])
+                    grant=renewed
+            if changed:
+                raise HTTPException(409,'connection_changed: Review the current connection.')
+        with vault.transaction() as db:
+            connections.capability(db,connection_id,request);connections.allowed(db,data['user_id'])
+            current=vault.get(db,'saas-grant',data['grant_id'])
+            if current is None: raise HTTPException(409,'connection_changed: Review the current connection.')
+            vault.put(db,'saas-grant',data['grant_id'],current['payload'],expires=clock()+INACTIVITY_SECONDS)
+        return {'version':1,'platform':data['platform'],'account':data['account'],'access_token':grant['access_token'],
+                'expires_at':grant['expires_at'],'granted_scopes':grant['granted_scopes']}