Files
ecs-relay-service/deployable/relay/approval_store.py
T

395 lines
26 KiB
Python

"""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,refresh=False):
"""Internal renderer only. Never return action/nonce or imply execution success."""
if type(refresh)is not bool:raise ApprovalError('invalid_card_refresh')
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'and not refresh: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 closed_for_task(self,task_id):
if not isinstance(task_id,str)or not re.fullmatch(r'msg_[a-f0-9]{64}',task_id):
raise ApprovalError('invalid_task_reference')
rows=self.db.execute('''SELECT approval_id FROM work_approvals_v3 WHERE environment=? AND app_id=?
AND task_id=? AND state IN ('rejected','expired','cancelled','consumed') AND card_message_id<>'' LIMIT 10''',
(self.state.environment,self.state.app_id,task_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 approval_id>?
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<?
ORDER BY x.created_at LIMIT ?)''',
(self.state.environment,self.state.app_id,self.clock()-audit_days*86400,limit)).rowcount
return {'payloads_purged':purged,'audit_events_removed':removed,'tombstones_preserved':True}