"""Offline foundation for C2: task-scoped approvals with one-time consumption. No HTTP routes, event subscription, platform message or execution adapter is registered by this module. VerifiedDecision must only be constructed by a platform callback verifier; a browser/button payload alone is not evidence. """ from dataclasses import dataclass import hashlib import hmac import json import re import secrets import time from .crypto import canonical from .approval_audit import ApprovalAudit class ApprovalError(ValueError): pass @dataclass(frozen=True) class VerifiedDecision: environment: str app_id: str actor_open_id: str chat_id: str card_message_id: str approval_id: str nonce: str choice: str event_id: str event_digest: str def _public_text(value,limit): if not isinstance(value,str)or not value.strip()or len(value)>limit or any(ord(c)<32 and c!='\n'for c in value): raise ApprovalError('invalid_approval_text') return value class ApprovalStore: def __init__(self,state,keyring,clock=time.time,enforce_execution_state=False): self.state,self.db,self.keyring,self.clock=state,state.db,keyring,clock self.enforce_execution_state=enforce_execution_state self._sweep_after='' self._retention_after='' with self.db: self.db.execute('''CREATE TABLE IF NOT EXISTS work_approvals_v3( approval_id TEXT PRIMARY KEY,environment TEXT NOT NULL,app_id TEXT NOT NULL, task_id TEXT NOT NULL,owner TEXT NOT NULL,host_id TEXT NOT NULL, binding_generation BIGINT NOT NULL,operation_id TEXT NOT NULL, operation_digest TEXT NOT NULL,nonce_digest TEXT NOT NULL, key_id TEXT NOT NULL,ciphertext TEXT NOT NULL,card_message_id TEXT NOT NULL, state TEXT NOT NULL,expires_at DOUBLE PRECISION NOT NULL, updated_at DOUBLE PRECISION NOT NULL, UNIQUE(environment,app_id,task_id,operation_id))''') self.db.execute('''CREATE TABLE IF NOT EXISTS work_approval_callbacks_v1( environment TEXT NOT NULL,app_id TEXT NOT NULL,event_id TEXT NOT NULL, approval_id TEXT NOT NULL,event_digest TEXT NOT NULL, received_at DOUBLE PRECISION NOT NULL, PRIMARY KEY(environment,app_id,event_id))''') self.db.execute('''CREATE TABLE IF NOT EXISTS work_approval_card_outbox_v1( approval_id TEXT PRIMARY KEY,state TEXT NOT NULL, updated_at DOUBLE PRECISION NOT NULL)''') self.db.execute('''CREATE INDEX IF NOT EXISTS work_approvals_expiry_v3 ON work_approvals_v3(environment,app_id,state,expires_at)''') self.db.execute('''CREATE TABLE IF NOT EXISTS work_approval_retention_v1( approval_id TEXT PRIMARY KEY,purged_at DOUBLE PRECISION NOT NULL)''') self.audit=ApprovalAudit(self.db,self.clock) def _task(self,task_id,owner,host,generation): if type(generation)is not int or generation<1: raise ApprovalError('invalid_binding_generation') task=self.state.task(task_id) if (not self.state.task_current(task)or not task['chat_id']or not task['source_message_id']or (task['owner'],task['host_id'],task['binding_generation'])!=(owner,host,generation)or task['status']!='inflight'or self._execution_closed(task_id)): raise ApprovalError('approval_task_unavailable') return task def _execution_closed(self,task_id): if not self.enforce_execution_state:return False row=self.db.execute('SELECT execution_state FROM work_execution_state_v3 WHERE task_id=?',(task_id,)).fetchone() return bool(row and row['execution_state']in {'completed','failed','cancelled','interrupted','unknown'}) def _aad(self,row): return canonical(['work-approval-v3',*[row[k]for k in ('environment','app_id','task_id', 'owner','host_id','binding_generation','operation_id','operation_digest','approval_id')]]) @staticmethod def _intent(action,owner,operation_id): normalized=json.loads(json.dumps(action,sort_keys=True,ensure_ascii=True,allow_nan=False)) # The calendar key is generated by our PC boundary from owner+op ID; # changing that generated key must not turn a denied action into a new # business intent. No arbitrary caller field is discarded otherwise. if (normalized.get('kind')=='work-api-v1'and normalized.get('method')=='POST' and isinstance(normalized.get('path'),str) and re.fullmatch(r'/open-apis/calendar/v4/calendars/[A-Za-z0-9_.@!:$-]+/events',normalized['path']) and isinstance(normalized.get('params'),dict)): expected=hashlib.sha256(canonical([owner,operation_id])).hexdigest() if normalized['params'].get('idempotency_key')==expected: normalized['params'].pop('idempotency_key') return hashlib.sha256(canonical(normalized)).hexdigest() def _row(self,approval_id): if not isinstance(approval_id,str)or not re.fullmatch(r'apr_[a-f0-9]{64}',approval_id): raise ApprovalError('invalid_approval_reference') row=self.db.execute('SELECT * FROM work_approvals_v3 WHERE approval_id=? AND environment=? AND app_id=?', (approval_id,self.state.environment,self.state.app_id)).fetchone() if not row:raise ApprovalError('approval_not_found') return dict(row) def _expire(self,row): if row['expires_at']<=self.clock()and row['state']in {'pending','approved'}: self.db.execute("UPDATE work_approvals_v3 SET state='expired',updated_at=? WHERE approval_id=? AND state IN ('pending','approved')", (self.clock(),row['approval_id'])) row=self._row(row['approval_id']) self.audit.record(row,'expired') return row @staticmethod def _status(row): return {k:row[k]for k in ('approval_id','state','expires_at','operation_digest')} def create(self,task_id,owner,host,generation,operation_id,action,summary,impact,ttl=120): if not isinstance(operation_id,str)or not re.fullmatch(r'[A-Za-z0-9_-]{8,100}',operation_id): raise ApprovalError('invalid_operation_id') if type(ttl)is not int or not 30<=ttl<=600:raise ApprovalError('invalid_approval_lifetime') if not isinstance(action,dict)or not action:raise ApprovalError('invalid_operation') encoded=json.dumps(action,sort_keys=True,ensure_ascii=True,separators=(',',':'),allow_nan=False).encode() if len(encoded)>32000:raise ApprovalError('operation_budget_exceeded') summary=_public_text(summary,200);impact=_public_text(impact,500) digest=hashlib.sha256(encoded).hexdigest() approval_id='apr_'+hashlib.sha256(canonical([self.state.environment,self.state.app_id,task_id,operation_id])).hexdigest() with self.db: self.state._owner_lock(owner) task=self._task(task_id,owner,host,generation) old=self.db.execute('SELECT * FROM work_approvals_v3 WHERE approval_id=?',(approval_id,)).fetchone() if old: row=self._expire(dict(old)) if (row['owner'],row['host_id'],row['binding_generation'],row['operation_digest'])!=(owner,host,generation,digest): raise ApprovalError('operation_identity_conflict') return self._status(row) # Scope to the SAME authenticated task. Legitimate subsequent user # tasks are independent; changing a model-chosen operation ID inside # this task cannot erase a rejection, expiry or consumed grant. intent=self._intent(action,owner,operation_id) previous=self.db.execute('''SELECT * FROM work_approvals_v3 WHERE environment=? AND app_id=? AND task_id=? LIMIT 51''', (self.state.environment,self.state.app_id,task_id)).fetchall() if len(previous)>=50:raise ApprovalError('approval_task_budget_exceeded') for prior in previous: prior=dict(prior) if not prior['ciphertext']:raise ApprovalError('approval_intent_unavailable') original=json.loads(self.keyring.decrypt(prior['key_id'],prior['ciphertext'],self._aad(prior))) if hmac.compare_digest(intent,self._intent(original['action'],prior['owner'],prior['operation_id'])): raise ApprovalError('approval_intent_already_registered') nonce=secrets.token_urlsafe(32) row={'approval_id':approval_id,'environment':task['environment'],'app_id':task['app_id'], 'task_id':task_id,'owner':owner,'host_id':host,'binding_generation':generation, 'operation_id':operation_id,'operation_digest':digest} key,cipher=self.keyring.encrypt(canonical({'action':action,'summary':summary,'impact':impact,'nonce':nonce}),self._aad(row)) expires=min(self.clock()+ttl,task['deadline']) if expires<=self.clock():raise ApprovalError('approval_task_expired') self.db.execute('INSERT INTO work_approvals_v3 VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)', (approval_id,row['environment'],row['app_id'],task_id,owner,host,generation,operation_id,digest, hashlib.sha256(nonce.encode()).hexdigest(),key,cipher,'','pending',expires,self.clock())) action_class=('work_api_delete'if action.get('method')=='DELETE'else 'work_api_read'if action.get('method')=='GET'else'work_api_write')if action.get('kind')=='work-api-v1'else'unknown' self.audit.record(self._row(approval_id),'created',action_class) return self._status(self._row(approval_id)) def card_material(self,approval_id): """Internal sender only: private task origin + fixed confirmation text.""" with self.db: row=self._row(approval_id);self.state._owner_lock(row['owner']);row=self._expire(self._row(approval_id)) task=self._task(row['task_id'],row['owner'],row['host_id'],row['binding_generation']) if row['state']!='pending':raise ApprovalError('approval_not_pending') material=json.loads(self.keyring.decrypt(row['key_id'],row['ciphertext'],self._aad(row))) return {'source_message_id':task['source_message_id'],'chat_id':task['chat_id'], 'approval_id':approval_id,'summary':material['summary'],'impact':material['impact'], 'nonce':material['nonce'],'expires_at':row['expires_at']} def bind_card(self,approval_id,message_id): if not isinstance(message_id,str)or not re.fullmatch(r'om_[A-Za-z0-9_-]{1,120}',message_id): raise ApprovalError('invalid_card_receipt') with self.db: row=self._row(approval_id);self.state._owner_lock(row['owner']);row=self._expire(self._row(approval_id)) task=self.state.task(row['task_id']) if row['state']in {'pending','approved'}and(not self.state.task_current(task)or task['status']!='inflight'or self._execution_closed(row['task_id'])): self.db.execute("UPDATE work_approvals_v3 SET state='cancelled',updated_at=? WHERE approval_id=?",(self.clock(),approval_id)) self.audit.record(self._row(approval_id),'cancelled') if not self.db.execute('SELECT approval_id FROM work_approval_card_outbox_v1 WHERE approval_id=?',(approval_id,)).fetchone(): raise ApprovalError('approval_send_intent_required') if row['card_message_id']not in ('',message_id):raise ApprovalError('approval_card_conflict') self.db.execute('UPDATE work_approvals_v3 SET card_message_id=?,updated_at=? WHERE approval_id=?', (message_id,self.clock(),approval_id)) self.db.execute("UPDATE work_approval_card_outbox_v1 SET state='sent',updated_at=? WHERE approval_id=?", (self.clock(),approval_id)) self.audit.record(self._row(approval_id),'card_bound') def claim_card(self,approval_id): """Persist send intent before network I/O; lost receipt is not resendable.""" with self.db: row=self._row(approval_id);self.state._owner_lock(row['owner']);row=self._expire(self._row(approval_id)) self._task(row['task_id'],row['owner'],row['host_id'],row['binding_generation']) if row['state']!='pending':raise ApprovalError('approval_not_pending') if row['card_message_id']:return False previous=self.db.execute('SELECT state FROM work_approval_card_outbox_v1 WHERE approval_id=?',(approval_id,)).fetchone() if previous:return False self.db.execute("INSERT INTO work_approval_card_outbox_v1 VALUES(?,'sending',?)",(approval_id,self.clock())) return True def card_send_unknown(self,approval_id): with self.db: changed=self.db.execute("UPDATE work_approval_card_outbox_v1 SET state='unknown',updated_at=? WHERE approval_id=? AND state='sending'", (self.clock(),approval_id)).rowcount if changed:self.audit.record(self._row(approval_id),'card_send_unknown') def close_unavailable(self,limit=100): """Future bounded maintenance: expiry or invalid task never grants consent.""" if type(limit)is not int or not 1<=limit<=100:raise ApprovalError('invalid_approval_budget') rows=self.db.execute("SELECT approval_id FROM work_approvals_v3 WHERE environment=? AND app_id=? AND state IN ('pending','approved') AND approval_id>? ORDER BY approval_id LIMIT ?", (self.state.environment,self.state.app_id,self._sweep_after,limit)).fetchall() if not rows:self._sweep_after='' closed=[];started=time.monotonic() for candidate in rows: if time.monotonic()-started>=.5:break with self.db: row=self._row(candidate['approval_id']);self.state._owner_lock(row['owner']);row=self._row(row['approval_id']) if row['state']not in {'pending','approved'}:continue task=self.state.task(row['task_id']) expired=row['expires_at']<=self.clock()or bool(task and task['deadline']<=self.clock()) invalid=(not self.state.task_current(task)or task['status']!='inflight'or self._execution_closed(row['task_id'])or (task['owner'],task['host_id'],task['binding_generation'])!= (row['owner'],row['host_id'],row['binding_generation'])) if expired or invalid: state='expired'if expired else'cancelled' self.db.execute("UPDATE work_approvals_v3 SET state=?,updated_at=? WHERE approval_id=? AND state IN ('pending','approved')", (state,self.clock(),row['approval_id'])) closed.append({'approval_id':row['approval_id'],'state':state}) self.audit.record(self._row(row['approval_id']),state) self._sweep_after=candidate['approval_id'] return closed def closed_card_receipt(self,approval_id): """Internal renderer only. Never return action/nonce or imply execution success.""" with self.db: row=self._row(approval_id);self.state._owner_lock(row['owner']);row=self._expire(self._row(approval_id)) if row['state']not in {'rejected','expired','cancelled','consumed'}or not row['card_message_id']: return None sent=self.db.execute('SELECT state FROM work_approval_card_outbox_v1 WHERE approval_id=?',(approval_id,)).fetchone() if sent and sent['state']=='closed':return None self.db.execute('UPDATE work_approval_card_outbox_v1 SET updated_at=? WHERE approval_id=?', (self.clock(),approval_id)) return {'message_id':row['card_message_id'],'state':row['state']} def mark_card_closed(self,approval_id,state): with self.db: row=self._row(approval_id);self.state._owner_lock(row['owner']);row=self._row(approval_id) if row['state']!=state or state not in {'rejected','expired','cancelled','consumed'}: raise ApprovalError('approval_state_changed') self.db.execute("UPDATE work_approval_card_outbox_v1 SET state='closed',updated_at=? WHERE approval_id=?", (self.clock(),approval_id)) def cards_to_send(self): rows=self.db.execute("""SELECT a.approval_id FROM work_approvals_v3 a WHERE a.environment=? AND a.app_id=? AND a.state='pending' AND a.expires_at>? AND a.card_message_id='' AND NOT EXISTS(SELECT 1 FROM work_approval_card_outbox_v1 o WHERE o.approval_id=a.approval_id) ORDER BY a.updated_at LIMIT 5""",(self.state.environment,self.state.app_id,self.clock())).fetchall() return [row['approval_id']for row in rows] def cards_to_close(self): rows=self.db.execute("""SELECT a.approval_id FROM work_approvals_v3 a JOIN work_approval_card_outbox_v1 o ON o.approval_id=a.approval_id WHERE a.environment=? AND a.app_id=? AND a.state IN ('rejected','expired','cancelled','consumed') AND a.card_message_id<>'' AND o.state<>'closed' ORDER BY o.updated_at LIMIT 5""", (self.state.environment,self.state.app_id)).fetchall() return [row['approval_id']for row in rows] def decide(self,decision): if not isinstance(decision,VerifiedDecision):raise ApprovalError('verified_callback_required') if decision.choice not in {'allow','deny'}:raise ApprovalError('invalid_approval_choice') if (not isinstance(decision.event_id,str)or not re.fullmatch(r'[A-Za-z0-9_-]{1,128}',decision.event_id) or not isinstance(decision.event_digest,str)or not re.fullmatch(r'[a-f0-9]{64}',decision.event_digest)): raise ApprovalError('invalid_callback_receipt') fields={key:getattr(decision,key)for key in ('environment','app_id','actor_open_id', 'chat_id','card_message_id','approval_id','nonce','choice')} if not hmac.compare_digest(hashlib.sha256(canonical(fields)).hexdigest(),decision.event_digest): raise ApprovalError('callback_receipt_conflict') with self.db: row=self._row(decision.approval_id);self.state._owner_lock(row['owner']);row=self._expire(self._row(decision.approval_id)) task=self._task(row['task_id'],row['owner'],row['host_id'],row['binding_generation']) if (decision.environment,decision.app_id,decision.actor_open_id,decision.chat_id,decision.card_message_id)!=\ (row['environment'],row['app_id'],row['owner'],task['chat_id'],row['card_message_id'])or not row['card_message_id']: raise ApprovalError('callback_identity_conflict') if not isinstance(decision.nonce,str)or len(decision.nonce)>128 or not hmac.compare_digest(hashlib.sha256(decision.nonce.encode()).hexdigest(),row['nonce_digest']): raise ApprovalError('invalid_approval_nonce') # Owner lock serializes duplicate clicks for this approval. Reused # event IDs for a different approval also fail the database PK. receipt=self.db.execute('SELECT approval_id,event_digest FROM work_approval_callbacks_v1 WHERE environment=? AND app_id=? AND event_id=?', (row['environment'],row['app_id'],decision.event_id)).fetchone() if receipt: if (receipt['approval_id'],receipt['event_digest'])!=(row['approval_id'],decision.event_digest): raise ApprovalError('callback_receipt_conflict') return self._status(row) target='approved'if decision.choice=='allow'else'rejected' if row['state']not in {'pending',target}:raise ApprovalError('approval_already_closed') self.db.execute('INSERT INTO work_approval_callbacks_v1 VALUES(?,?,?,?,?,?)', (row['environment'],row['app_id'],decision.event_id,row['approval_id'],decision.event_digest,self.clock())) self.db.execute("UPDATE work_approvals_v3 SET state=?,updated_at=? WHERE approval_id=? AND state='pending'", (target,self.clock(),row['approval_id'])) self.audit.record(self._row(row['approval_id']),target) return self._status(self._row(row['approval_id'])) def status(self,approval_id,task_id,owner,host,generation,operation_digest): """Future device-authenticated polling endpoint; no nonce/action returned.""" with self.db: self.state._owner_lock(owner);row=self._expire(self._row(approval_id)) self._task(task_id,owner,host,generation) if (row['task_id'],row['owner'],row['host_id'],row['binding_generation'],row['operation_digest'])!=\ (task_id,owner,host,generation,operation_digest):raise ApprovalError('operation_identity_conflict') return self._status(row) def consume(self,approval_id,task_id,owner,host,generation,operation_digest): with self.db: self.state._owner_lock(owner) row=self._expire(self._row(approval_id)) self._task(task_id,owner,host,generation) if (row['task_id'],row['owner'],row['host_id'],row['binding_generation'],row['operation_digest'])!=(task_id,owner,host,generation,operation_digest): raise ApprovalError('operation_identity_conflict') if row['state']!='approved':return {**self._status(row),'execute':False} material=json.loads(self.keyring.decrypt(row['key_id'],row['ciphertext'],self._aad(row))) changed=self.db.execute("UPDATE work_approvals_v3 SET state='consumed',updated_at=? WHERE approval_id=? AND state='approved'", (self.clock(),approval_id)).rowcount if changed!=1:return {**self._status(self._row(approval_id)),'execute':False} self.audit.record(self._row(approval_id),'consumed') return {**self._status(self._row(approval_id)),'execute':True,'action':material['action']} def cancel(self,approval_id,task_id,owner,host,generation): with self.db: self.state._owner_lock(owner);row=self._row(approval_id) self._task(task_id,owner,host,generation) if (row['task_id'],row['owner'],row['host_id'],row['binding_generation'])!=(task_id,owner,host,generation):raise ApprovalError('approval_identity_conflict') changed=self.db.execute("UPDATE work_approvals_v3 SET state='cancelled',updated_at=? WHERE approval_id=? AND state IN ('pending','approved')", (self.clock(),approval_id)).rowcount if changed:self.audit.record(self._row(approval_id),'cancelled') return self._status(self._row(approval_id)) def maintain_retention(self,payload_days=30,audit_days=90,limit=10): """Prune CLOSED payloads/audit only. Durable tombstones fence replay.""" if (type(payload_days)is not int or type(audit_days)is not int or not 1<=payload_days<=audit_days<=365 or type(limit)is not int or not 1<=limit<=20): raise ApprovalError('invalid_approval_retention') cutoff=self.clock()-payload_days*86400 rows=self.db.execute('''SELECT approval_id FROM work_approvals_v3 a WHERE environment=? AND app_id=? AND state IN ('rejected','expired','cancelled','consumed') AND updated_at? AND NOT EXISTS(SELECT 1 FROM work_approval_retention_v1 r WHERE r.approval_id=a.approval_id) ORDER BY approval_id LIMIT ?''',(self.state.environment,self.state.app_id,cutoff,self._retention_after,limit)).fetchall() if not rows:self._retention_after='' purged=0;started=time.monotonic() for item in rows: if time.monotonic()-started>.5:break self._retention_after=item['approval_id'] with self.db: row=self._row(item['approval_id']);self.state._owner_lock(row['owner']);row=self._row(row['approval_id']) if row['state']not in {'rejected','expired','cancelled','consumed'}or row['updated_at']>=cutoff:continue if row['state']=='consumed': task=self.state.task(row['task_id']) if not task or task['status']in {'inflight','unknown'}:continue marked=self.db.execute('INSERT INTO work_approval_retention_v1 VALUES(?,?) ON CONFLICT DO NOTHING', (row['approval_id'],self.clock())).rowcount if not marked:continue self.db.execute("UPDATE work_approvals_v3 SET ciphertext='',key_id='',nonce_digest='' WHERE approval_id=?",(row['approval_id'],)) self.audit.record(row,'payload_purged');purged+=1 # Audit removal is bounded too; approval and operation tombstones stay. with self.db: removed=self.db.execute('''DELETE FROM work_approval_audit_v1 WHERE event_key IN ( SELECT x.event_key FROM work_approval_audit_v1 x JOIN work_approval_retention_v1 r ON r.approval_id=x.approval_id WHERE x.environment=? AND x.app_id=? AND x.created_at