feat(work): stage authenticated remote approvals with scoped execution fencing
This commit is contained in:
@@ -0,0 +1,304 @@
|
||||
"""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
|
||||
|
||||
|
||||
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=''
|
||||
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)''')
|
||||
|
||||
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')]])
|
||||
|
||||
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'])
|
||||
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)
|
||||
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()))
|
||||
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))
|
||||
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))
|
||||
|
||||
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:
|
||||
self.db.execute("UPDATE work_approval_card_outbox_v1 SET state='unknown',updated_at=? WHERE approval_id=? AND state='sending'",
|
||||
(self.clock(),approval_id))
|
||||
|
||||
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._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']))
|
||||
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}
|
||||
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')
|
||||
self.db.execute("UPDATE work_approvals_v3 SET state='cancelled',updated_at=? WHERE approval_id=? AND state IN ('pending','approved')",
|
||||
(self.clock(),approval_id))
|
||||
return self._status(self._row(approval_id))
|
||||
Reference in New Issue
Block a user