socialcli 0.3.0__py3-none-any.whl

socialctl/saas/restore_guard.py

@@ -0,0 +1,229 @@
+"""Prepare an isolated restore; never write over a running or existing database.
+
+Manifest provenance is an explicit operator trust boundary. The operator must
+export from the still-current authoritative service, never regenerate timestamps
+from a backup. JSON labels alone cannot establish that provenance. No command
+contacts a provider or the identity service. Identity cleanup is separately applied
+in the isolated PostgreSQL restore and explicitly attested before release.
+"""
+from __future__ import annotations
+import argparse
+from contextlib import closing
+import json
+import math
+import os
+from pathlib import Path
+import sqlite3
+import tempfile
+import time
+
+from socialctl.saas.backup import snapshot, verify_snapshot, BackupError, _read
+from socialctl.connection_service.store import Store
+from socialctl.saas.store import SaaSStore
+
+
+class RestoreError(ValueError):
+    """Fixed operator diagnostics without credential or identity data."""
+
+
+def checked_manifest(manifest, now):
+    try:
+        if not isinstance(manifest,dict) or manifest['schema']!=1 or manifest['source']!='current-authority':
+            raise ValueError()
+        generated=manifest['generated_at']
+        if type(generated) not in (int,float) or not math.isfinite(generated) or not now-300<=generated<=now+60:
+            raise ValueError()
+        tombstones=manifest['tombstones'];pending=manifest['pending_revocation_ids']
+        if not isinstance(tombstones,list) or not isinstance(pending,list):raise ValueError()
+        if len(tombstones)>1000000 or len(pending)>1000000:raise ValueError()
+        for row in tombstones:
+            if (not isinstance(row,dict) or row['kind'] not in {'user','grant'}
+                    or not isinstance(row['id'],str) or not 1<=len(row['id'])<=512
+                    or any(ord(c)<32 for c in row['id'])
+                    or type(row['requested']) not in (int,float) or not math.isfinite(row['requested'])
+                    or row['requested']>generated+60):raise ValueError()
+        if any(not isinstance(value,str) or not 1<=len(value)<=512 for value in pending):raise ValueError()
+        return manifest
+    except (KeyError,TypeError,ValueError):
+        raise RestoreError('A fresh manifest from the current authority is required; backup-derived or unavailable authority cannot release a restore.') from None
+
+
+def export_manifest(database, *, now):
+    """Read-only; caller attests this path is the current authority, not a backup."""
+    try:
+        with closing(_read(database)) as db:
+            db.row_factory=sqlite3.Row
+            db.execute('BEGIN')
+            if db.execute("SELECT 1 FROM sqlite_master WHERE type='table' AND name='saas_restore_guard'").fetchone():
+                guard=db.execute('SELECT state FROM saas_restore_guard WHERE singleton=1').fetchone()
+                if not guard or guard['state']!='ready':raise RestoreError('A quarantined restore is not an authority.')
+            tombstones=[dict(row) for row in db.execute('SELECT kind,id,requested FROM saas_deletion_tombstones ORDER BY kind,id')]
+            pending=[row[0] for row in db.execute("SELECT id FROM saas_google_revocations WHERE state='pending' ORDER BY id")]
+        return {'schema':1,'source':'current-authority','generated_at':now,'tombstones':tombstones,'pending_revocation_ids':pending}
+    except sqlite3.Error:
+        raise RestoreError('Current deletion authority is unavailable; keep the restore quarantined.') from None
+
+
+def _wipe_access(db, *, quarantine):
+    kinds=['saas-session','saas-login','saas-pair','saas-installation','saas-capability',
+           'saas-candidate','authorization','connection',
+           'saas-meta-webhook-binding','saas-meta-webhook-event']
+    if quarantine:kinds+=['saas-grant','google-revocation']
+    db.execute('DELETE FROM records WHERE kind IN ('+','.join('?' for _ in kinds)+')',kinds)
+    db.execute('UPDATE saas_users SET session_version=session_version+1')
+    if quarantine:
+        db.execute('DELETE FROM saas_slots')
+        db.execute('DELETE FROM saas_google_revocations')
+    if db.execute("SELECT 1 FROM sqlite_master WHERE type='table' AND name='legacy_allowance'").fetchone():
+        db.execute('DELETE FROM legacy_allowance')
+
+
+def _apply(vault,db,manifest):
+    _wipe_access(db,quarantine=manifest is None)
+    if manifest is None:return
+    pending=set(manifest['pending_revocation_ids'])
+    for row in db.execute('SELECT id FROM saas_google_revocations').fetchall():
+        if row['id'] not in pending:
+            vault.delete(db,'google-revocation',row['id'])
+            db.execute('DELETE FROM saas_google_revocations WHERE id=?',(row['id'],))
+        else:
+            db.execute("UPDATE saas_google_revocations SET state='pending',lease=NULL,lease_until=0,next_attempt=0 WHERE id=?",(row['id'],))
+    tables={row[0] for row in db.execute("SELECT name FROM sqlite_master WHERE type='table'")}
+    for item in manifest['tombstones']:
+        kind,record_id=item['kind'],item['id']
+        if kind=='grant':
+            vault.delete(db,'saas-grant',record_id)
+            db.execute('DELETE FROM saas_slots WHERE grant_id=?',(record_id,))
+        else:
+            billing=db.execute('SELECT customer_id FROM saas_billing WHERE user_id=?',(record_id,)).fetchone()
+            if billing and billing['customer_id']:
+                for row in db.execute('SELECT account_id,mode,event_id FROM saas_billing_events WHERE customer_id=?',(billing['customer_id'],)).fetchall():
+                    vault.delete(db,'saas-stripe-event',':'.join(row))
+                db.execute('DELETE FROM saas_billing_events WHERE customer_id=?',(billing['customer_id'],))
+            db.execute('DELETE FROM records WHERE (kind,id) IN (SELECT kind,id FROM saas_record_owners WHERE user_id=?)',(record_id,))
+            vault.delete(db,'saas-user',record_id)
+            for table in ('saas_users','saas_entitlements','saas_billing','saas_slots','saas_brands','saas_reminders','saas_deletions','saas_media_allocations'):
+                if table in tables:
+                    db.execute('DELETE FROM '+table+' WHERE '+('id' if table=='saas_users' else 'user_id')+'=?',(record_id,))
+        db.execute('INSERT OR REPLACE INTO saas_deletion_tombstones VALUES(?,?,?)',(kind,record_id,item['requested']))
+    db.execute('DELETE FROM saas_brands WHERE NOT EXISTS (SELECT 1 FROM saas_slots WHERE saas_slots.user_id=saas_brands.user_id)')
+
+
+def prepare_restore(source,destination,keys,manifest,*,now,snapshot_created):
+    if type(snapshot_created) not in (int,float) or not math.isfinite(snapshot_created) or not now-6*86400<=snapshot_created<=now+60:
+        raise RestoreError('Only an independently dated snapshot no older than six days can enter this restore workflow.')
+    if manifest is not None:checked_manifest(manifest,now)
+    source,destination=Path(source),Path(destination)
+    if destination.exists() or destination.is_symlink() or source.resolve()==destination.resolve():
+        raise RestoreError('Restore destination must be new and isolated; existing databases are never overwritten.')
+    temporary=None
+    try:
+        destination.parent.mkdir(parents=True,exist_ok=True,mode=0o700)
+        if destination.parent.stat().st_mode & 0o077:raise RestoreError('Use a private restore directory with mode 0700.')
+        fd,name=tempfile.mkstemp(prefix='.restore-',dir=destination.parent);os.close(fd)
+        temporary=Path(name);temporary.unlink()
+        snapshot(source,temporary,keys)
+        # Remove the unprepared marker only inside the unpublished offline copy;
+        # re-establish a blocked marker atomically with deletion suppression.
+        with sqlite3.connect(temporary) as db:db.execute('DROP TABLE IF EXISTS saas_restore_guard')
+        vault=Store(temporary,keys);SaaSStore(vault,keys)
+        state='identity_cleanup_required' if manifest is not None else 'authority_unavailable'
+        with vault.transaction() as db:
+            _apply(vault,db,manifest)
+            db.execute('CREATE TABLE saas_restore_guard (singleton INTEGER PRIMARY KEY CHECK(singleton=1),state TEXT NOT NULL,prepared REAL NOT NULL,snapshot_created REAL NOT NULL)')
+            db.execute('INSERT INTO saas_restore_guard VALUES(1,?,?,?)',(state,now,snapshot_created))
+        with sqlite3.connect(temporary) as db:
+            db.execute('PRAGMA wal_checkpoint(TRUNCATE)')
+            db.execute('PRAGMA journal_mode=DELETE')
+        verify_snapshot(temporary,keys)
+        with temporary.open('rb') as stream:os.fsync(stream.fileno())
+        os.link(temporary,destination)
+        return {'status':state,'identity_cleanup_verified':False,'access_credentials_removed':True}
+    except (OSError,sqlite3.Error,BackupError):
+        raise RestoreError('Restore preparation failed; source preserved and no usable restore released.') from None
+    finally:
+        if temporary:
+            temporary.unlink(missing_ok=True)
+            for suffix in ('-wal','-shm','-journal'):Path(str(temporary)+suffix).unlink(missing_ok=True)
+
+
+def release_restore(database,keys,manifest,*,now,identity_cleanup_confirmed=False):
+    checked_manifest(manifest,now)
+    if not identity_cleanup_confirmed:
+        raise RestoreError('Apply the generated cleanup to the isolated Auth restore, then explicitly attest completion.')
+    database=Path(database)
+    if not database.is_file():raise RestoreError('A prepared isolated restore is required.')
+    # Reject a live/unprepared database read-only, before Store can migrate,
+    # change journal mode, or alter its filesystem permissions.
+    try:
+        with closing(_read(database)) as db:
+            row=db.execute('SELECT state FROM saas_restore_guard WHERE singleton=1').fetchone()
+            if row is None or row[0] not in {'identity_cleanup_required','authority_unavailable'}:
+                raise RestoreError('Only a quarantined offline restore can be released.')
+    except sqlite3.Error:
+        raise RestoreError('A prepared isolated restore is required; live databases cannot be released here.') from None
+    verify_snapshot(database,keys)
+    vault=Store(database,keys)
+    try:
+        with vault.transaction() as db:
+            row=db.execute('SELECT * FROM saas_restore_guard WHERE singleton=1').fetchone()
+            if row is None or row['state'] not in {'identity_cleanup_required','authority_unavailable'}:
+                raise RestoreError('Only a quarantined offline restore can be released.')
+            if row['snapshot_created']<now-6*86400:
+                raise RestoreError('The staged snapshot is too old; obtain a current recovery point.')
+            _apply(vault,db,manifest)
+            for record_id in manifest['pending_revocation_ids']:
+                if vault.get(db,'google-revocation',record_id) is None or not db.execute('SELECT id FROM saas_google_revocations WHERE id=?',(record_id,)).fetchone():
+                    raise RestoreError('Current revocation jobs are missing. Recover the authoritative encrypted queue before release.')
+            db.execute("UPDATE saas_restore_guard SET state='ready' WHERE singleton=1")
+    except sqlite3.Error:
+        raise RestoreError('A prepared isolated restore is required; live databases cannot be released here.') from None
+    return {'status':'ready','identity_cleanup_verified':False,'identity_cleanup_operator_attested':True}
+
+
+def auth_cleanup_sql(manifest,*,now):
+    checked_manifest(manifest,now)
+    # All old Auth sessions are invalidated even for owners not deleted. This
+    # script runs only in the isolated restored Auth DB with ON_ERROR_STOP.
+    lines=['BEGIN;','DELETE FROM auth.refresh_tokens;','DELETE FROM auth.sessions;']
+    users=sorted({item['id'] for item in manifest['tombstones'] if item['kind']=='user'})
+    if users:
+        values=','.join("'"+value.replace("'","''")+"'" for value in users)
+        lines.append('DELETE FROM auth.users WHERE id IN ('+values+');')
+    lines.append('COMMIT;')
+    return '\n'.join(lines)+'\n'
+
+
+def _write_private(path,value):
+    fd=os.open(path,os.O_WRONLY|os.O_CREAT|os.O_EXCL,0o600)
+    with os.fdopen(fd,'w') as stream:
+        stream.write(value);stream.flush();os.fsync(stream.fileno())
+
+
+def main():
+    parser=argparse.ArgumentParser(description=__doc__)
+    sub=parser.add_subparsers(dest='operation',required=True)
+    export=sub.add_parser('export');export.add_argument('database',type=Path);export.add_argument('destination',type=Path)
+    export.add_argument('--current-authority-confirmed',action='store_true',required=True)
+    prepare=sub.add_parser('prepare');prepare.add_argument('database',type=Path);prepare.add_argument('destination',type=Path)
+    prepare.add_argument('--manifest',type=Path);prepare.add_argument('--snapshot-created',type=float,required=True)
+    auth=sub.add_parser('auth-sql');auth.add_argument('manifest',type=Path);auth.add_argument('destination',type=Path)
+    release=sub.add_parser('release');release.add_argument('database',type=Path);release.add_argument('--manifest',type=Path,required=True)
+    release.add_argument('--identity-cleanup-confirmed',action='store_true',required=True)
+    args=parser.parse_args();now=time.time()
+    keys=[v.strip().encode() for v in os.environ.get('SOCIALCLI_ENCRYPTION_KEYS','').split(',') if v.strip()]
+    try:
+        manifest=json.loads(args.manifest.read_text()) if getattr(args,'manifest',None) else None
+        if args.operation=='export':
+            _write_private(args.destination,json.dumps(export_manifest(args.database,now=now)))
+            result={'status':'manifest_exported','provenance':'operator_attested_current_authority'}
+        elif args.operation=='prepare':result=prepare_restore(args.database,args.destination,keys,manifest,now=now,snapshot_created=args.snapshot_created)
+        elif args.operation=='auth-sql':
+            _write_private(args.destination,auth_cleanup_sql(manifest,now=now));result={'status':'auth_sql_written','identity_cleanup_verified':False}
+        else:result=release_restore(args.database,keys,manifest,now=now,identity_cleanup_confirmed=args.identity_cleanup_confirmed)
+    except (RestoreError,BackupError,OSError,ValueError,TypeError):
+        parser.exit(1,'Restore guard failed; keep all restored services offline and review authority, freshness, keys and Auth cleanup.\n')
+    print(json.dumps(result,sort_keys=True))
+
+
+if __name__=='__main__':main()

socialctl/saas/revocation.py

@@ -0,0 +1,97 @@
+"""Durable customer Google revocation; credentials are never usable by the broker.
+
+The encrypted queue keeps only the token required to finish revocation, until
+Google confirms completion. All network requests occur outside SQLite locks.
+"""
+import secrets
+from socialctl.saas.budget import using_budget
+
+TOKEN_KIND = 'google-revocation'
+
+
+def tombstone(db, kind, record_id, now):
+    db.execute('INSERT OR REPLACE INTO saas_deletion_tombstones VALUES(?,?,?)',
+               (kind, record_id, now))
+
+
+def reserve(db, job_id, user_id, now):
+    """Fence reconnect while an already-started provider request is unresolved."""
+    tombstone(db, 'grant', job_id, now)
+    db.execute('INSERT OR IGNORE INTO saas_google_revocations(id,user_id,requested) VALUES(?,?,?)',
+               (job_id, user_id, now))
+
+
+def enqueue(metadata, db, grant_id, payload, now):
+    """Called in the same transaction that removes local access."""
+    tombstone(db, 'grant', grant_id, now)
+    if payload.get('platform') != 'youtube':
+        return None
+    grant = payload.get('grant') or {}
+    token = grant.get('refresh_token') or grant.get('access_token')
+    if not token:
+        return None
+    existing=db.execute('SELECT state FROM saas_google_revocations WHERE id=?', (grant_id,)).fetchone()
+    if existing:
+        if existing['state']=='pending' and metadata.vault.get(db,TOKEN_KIND,grant_id) is None:
+            metadata.vault.put(db,TOKEN_KIND,grant_id,{'token':token},expires=253402300799)
+            db.execute('UPDATE saas_google_revocations SET next_attempt=0 WHERE id=?',(grant_id,))
+        return grant_id
+    metadata.vault.put(db, TOKEN_KIND, grant_id, {'token': token}, expires=253402300799)
+    db.execute('INSERT INTO saas_google_revocations(id,user_id,requested) VALUES(?,?,?)',
+               (grant_id, payload['user_id'], now))
+    return grant_id
+
+
+def export_current_deletion_manifest(metadata, clock):
+    """Export from the current authoritative service, NEVER from a restored backup."""
+    with metadata.vault.read_transaction() as db:
+        rows=[dict(row) for row in db.execute('SELECT kind,id,requested FROM saas_deletion_tombstones ORDER BY kind,id')]
+        pending=[row[0] for row in db.execute("SELECT id FROM saas_google_revocations WHERE state='pending' ORDER BY id")]
+    return {'schema': 1, 'source': 'current-authority', 'generated_at': clock(), 'tombstones': rows, 'pending_revocation_ids':pending}
+
+
+def run_revocations(metadata, providers, clock, limit=100, *, user_id=None, job_id=None, budget=None):
+    vault=metadata.vault
+    where="state='pending' AND next_attempt<=? AND lease_until<=?"
+    args=[clock(),clock()]
+    for field,value in (('user_id',user_id),('id',job_id)):
+        if value is not None:
+            where+=' AND '+field+'=?';args.append(value)
+    with vault.read_transaction() as db:
+        jobs=[dict(row) for row in db.execute('SELECT * FROM saas_google_revocations WHERE '+where+' ORDER BY requested LIMIT ?',(*args,limit))]
+    completed=0
+    with using_budget(budget,providers):
+        for job in jobs:
+            if budget and budget.expired():break
+            lease=secrets.token_hex(20)
+            with vault.transaction() as db:
+                claimed=db.execute("UPDATE saas_google_revocations SET lease=?,lease_until=? WHERE id=? AND state='pending' AND lease_until<=? AND next_attempt<=?",(lease,clock()+300,job['id'],clock(),clock())).rowcount
+                if not claimed:continue
+                record=vault.get(db,TOKEN_KIND,job['id'])
+            try:
+                if record is None or providers is None:
+                    raise ValueError('google_revocation_pending')
+                providers.revoke_google(record['payload']['token'])
+            except Exception:
+                with vault.transaction() as db:
+                    db.execute('UPDATE saas_google_revocations SET lease=NULL,lease_until=0,attempts=attempts+1,next_attempt=? WHERE id=? AND lease=?',(clock()+300,job['id'],lease))
+            else:
+                with vault.transaction() as db:
+                    updated=db.execute("UPDATE saas_google_revocations SET state='complete',lease=NULL,lease_until=0,attempts=attempts+1 WHERE id=? AND lease=?",(job['id'],lease)).rowcount
+                    if updated:
+                        vault.delete(db,TOKEN_KIND,job['id']);completed+=1
+    with vault.read_transaction() as db:
+        pending=db.execute("SELECT count(*) FROM saas_google_revocations WHERE state='pending'").fetchone()[0]
+        due=db.execute("SELECT count(*) FROM saas_google_revocations WHERE state='pending' AND next_attempt<=?",(clock(),)).fetchone()[0]
+        overdue=db.execute("SELECT count(*) FROM saas_google_revocations WHERE state='pending' AND requested<=?",(clock()-86400,)).fetchone()[0]
+        awaiting=db.execute("SELECT count(*) FROM saas_google_revocations q WHERE state='pending' AND NOT EXISTS (SELECT 1 FROM records r WHERE r.kind='google-revocation' AND r.id=q.id)").fetchone()[0]
+    return {'completed':completed,'pending':pending,'due':due,'overdue':overdue,
+            'awaiting_credentials':awaiting,'operator_review_required':bool(awaiting),
+            'budget_exhausted':bool(budget and budget.expired())}
+
+
+def status(metadata, job_id):
+    if job_id is None:return 'not_applicable'
+    with metadata.vault.read_transaction() as db:
+        row=db.execute('SELECT state FROM saas_google_revocations WHERE id=?',(job_id,)).fetchone()
+    return row['state'] if row else 'pending'

socialctl/saas/rotation.py

@@ -0,0 +1,114 @@
+"""Two-phase installation/capability rotation; provider grants remain independent."""
+import hmac
+import secrets
+from fastapi import HTTPException,Request
+from pydantic import BaseModel,ConfigDict,Field
+from socialctl.saas.pairing import proof,INSTALLATION_SECONDS
+
+
+class CapabilityRotation(BaseModel):
+    model_config=ConfigDict(extra='forbid')
+    connection_id:str=Field(pattern='^[A-Za-z0-9_-]{16,256}$')
+    challenge:str=Field(pattern='^[0-9a-f]{64}$')
+
+
+class RotationRequest(BaseModel):
+    model_config=ConfigDict(extra='forbid')
+    installation_challenge:str=Field(pattern='^[0-9a-f]{64}$')
+    connections:list[CapabilityRotation]=Field(default_factory=list,max_length=4)
+
+
+def install_rotation_routes(app,metadata,clock):
+    vault=metadata.vault;installations=app.state.saas_installations
+
+    def owned_capability(db,connection_id,installation_id,user_id):
+        record=vault.get(db,'saas-capability',connection_id)
+        if record is None:raise HTTPException(409,'connection_changed: Review the current connection.')
+        data=record['payload']
+        if data['installation_id']!=installation_id or data['user_id']!=user_id:
+            raise HTTPException(403,'This connection belongs to another installation.')
+        slot=db.execute('SELECT grant_id FROM saas_slots WHERE user_id=? AND platform=?',(user_id,data['platform'])).fetchone()
+        grant=vault.get(db,'saas-grant',data['grant_id'])
+        if slot is None or slot['grant_id']!=data['grant_id'] or grant is None or grant['expires']<=clock():
+            raise HTTPException(409,'connection_changed: Review the current connection.')
+        return record
+
+    @app.post('/api/saas/v1/installations/{installation_id}/rotations/{rotation_id}',status_code=201)
+    def prepare(installation_id:str,rotation_id:str,body:RotationRequest,request:Request):
+        import re
+        if not re.fullmatch(r'[A-Za-z0-9_-]{16,64}',rotation_id):raise HTTPException(400,'Invalid rotation identifier.')
+        wanted=body.model_dump()
+        with vault.transaction() as db:
+            old=installations.require(db,installation_id,request);user_id=old['payload']['user_id']
+            pending=vault.get(db,'saas-rotation',rotation_id)
+            if pending:
+                data=pending['payload']
+                if (pending['expires']<=clock() or data.get('status')!='prepared'
+                        or data['installation_id']!=installation_id or data['user_id']!=user_id
+                        or data['request']!=wanted or data['old_hash']!=old['credential_hash']):
+                    raise HTTPException(409,'rotation_changed: Resume the original rotation or review installation access.')
+                return data['result']
+            if not metadata.admit(db,'rotation:'+installation_id,clock(),limit=5):
+                raise HTTPException(429,'Too many rotation attempts. Wait a minute.')
+            if len({c.connection_id for c in body.connections})!=len(body.connections):
+                raise HTTPException(400,'Duplicate connection in rotation.')
+            next_id=secrets.token_urlsafe(24);connections=[];platforms=set()
+            for entry in body.connections:
+                cap=owned_capability(db,entry.connection_id,installation_id,user_id)['payload']
+                if cap['platform'] in platforms:raise HTTPException(400,'Only one connection per platform can be rotated.')
+                platforms.add(cap['platform'])
+                connections.append({'connection_id':secrets.token_urlsafe(24),'previous_id':entry.connection_id,
+                    'platform':cap['platform'],'account':cap['account'],'grant_id':cap['grant_id']})
+            result={'version':1,'status':'prepared','installation_id':next_id,'connections':connections}
+            payload={'status':'prepared','user_id':user_id,'installation_id':installation_id,
+                     'old_hash':old['credential_hash'],'request':wanted,'result':result}
+            vault.put(db,'saas-rotation',rotation_id,payload,expires=min(old['expires'],clock()+600),
+                credential_hash=body.installation_challenge)
+        return result
+
+    @app.post('/api/saas/v1/rotations/{rotation_id}/commit')
+    def commit(rotation_id:str,request:Request):
+        with vault.transaction() as db:
+            record=vault.get(db,'saas-rotation',rotation_id)
+            if record is None or record['expires']<=clock() or not hmac.compare_digest(record['credential_hash'],proof(request)):
+                raise HTTPException(404,'rotation_unavailable: Review pending rotation recovery.')
+            data=record['payload']
+            if data['status']=='committed':
+                installations.require(db,data['installation_id'],request)
+                return {'version':1,'status':'active'}
+            old=vault.get(db,'saas-installation',data['installation_id'])
+            if old is None or old['expires']<=clock() or old['credential_hash']!=data['old_hash']:
+                raise HTTPException(401,'installation_revoked: Sign in to SocialCli again.')
+            user=metadata.user(db,data['user_id'])
+            if user is None or user['deleting']:raise HTTPException(401,'account_unavailable: Sign in to SocialCli again.')
+            next_id=data['result']['installation_id'];expires=clock()+INSTALLATION_SECONDS
+            for item,entry in zip(data['result']['connections'],data['request']['connections'],strict=True):
+                cap=owned_capability(db,entry['connection_id'],data['installation_id'],data['user_id'])
+                if cap['payload']['grant_id']!=item['grant_id'] or cap['payload']['account']!=item['account']:
+                    raise HTTPException(409,'connection_changed: Review the current connection.')
+                vault.put(db,'saas-capability',item['connection_id'],{**cap['payload'],'installation_id':next_id},
+                    expires=expires,credential_hash=entry['challenge'])
+            vault.put(db,'saas-installation',next_id,{**old['payload'],'rotated_at':clock()},
+                expires=expires,credential_hash=record['credential_hash'])
+            vault.delete(db,'saas-installation',data['installation_id'])
+            # Old caps and pending OAuth are unusable because their installation
+            # no longer exists. Remove owned capability records immediately.
+            db.execute("""DELETE FROM records WHERE kind='saas-capability' AND id IN (
+                SELECT link.id FROM saas_record_links link JOIN saas_record_owners owner
+                ON owner.kind=link.kind AND owner.id=link.id
+                WHERE link.kind='saas-capability' AND link.installation_id=? AND owner.user_id=?)""",
+                (data['installation_id'],data['user_id']))
+            vault.put(db,'saas-rotation',rotation_id,{'status':'committed','user_id':data['user_id'],'installation_id':next_id},
+                expires=expires,credential_hash=record['credential_hash'])
+        return {'version':1,'status':'active'}
+
+    @app.delete('/api/saas/v1/installations/{installation_id}/rotations/{rotation_id}')
+    def cancel(installation_id:str,rotation_id:str,request:Request):
+        with vault.transaction() as db:
+            installations.require(db,installation_id,request)
+            record=vault.get(db,'saas-rotation',rotation_id)
+            if record:
+                if record['payload']['installation_id']!=installation_id or record['payload']['status']!='prepared':
+                    raise HTTPException(409,'rotation_changed: Resume the committed rotation.')
+                vault.delete(db,'saas-rotation',rotation_id)
+        return {'version':1,'status':'cancelled'}