330 lines
12 KiB
TypeScript
330 lines
12 KiB
TypeScript
|
/**
|
|||
|
|
* 待确认动作（任务 A4.4）：确认卡与一次性执行授权的持久层。
|
|||
|
|
*
|
|||
|
|
* 一张表同时承担「待确认动作」与「执行记录」两件事（A4 备注：不设单独的凭据表与审批事件表）：
|
|||
|
|
* 参数摘要、状态、回执、幂等键、有效期都在一行里，审批与执行的状态迁移是同一行的状态迁移。
|
|||
|
|
*
|
|||
|
|
* 三条不变量：
|
|||
|
|
* 1. 确认卡绑定动作、参数摘要、目标版本与有效期——版本变了确认即失效
|
|||
|
|
* 2. 确认人必须是会话发起人本人（单用户场景不做委托与转派）
|
|||
|
|
* 3. 待确认状态落库，进程重启后仍在；同一写请求重试不重复生效
|
|||
|
|
*/
|
|||
|
|
import { randomUUID } from 'node:crypto';
|
|||
|
|
|
|||
|
|
import type { ExecutionReceipt } from '@aps/contracts';
|
|||
|
|
|
|||
|
|
import type { SealedSecret } from '../credentials/broker.js';
|
|||
|
|
import type { Database } from '../storage/db.js';
|
|||
|
|
|
|||
|
|
export type PendingStatus = 'pending-confirmation' | 'succeeded' | 'failed' | 'rejected' | 'expired';
|
|||
|
|
export type ApprovalDecision = 'approved' | 'rejected' | 'expired';
|
|||
|
|
|
|||
|
|
export interface PendingAction {
|
|||
|
|
executionId: string;
|
|||
|
|
approvalId: string;
|
|||
|
|
sessionId: string;
|
|||
|
|
projectId: string | null;
|
|||
|
|
ownerUserId: string;
|
|||
|
|
tenantId: string;
|
|||
|
|
capabilityId: string;
|
|||
|
|
providerId: string;
|
|||
|
|
paramsDigest: string;
|
|||
|
|
/** 脱敏后的关键参数：给确认卡看的，不是完整参数 */
|
|||
|
|
paramsPreview: Record<string, unknown>;
|
|||
|
|
/** 原始参数的密文：确认后要照原样执行，但库里不留明文 */
|
|||
|
|
paramsSealed: SealedSecret;
|
|||
|
|
impactSummary: string;
|
|||
|
|
/** 目标数据版本；版本变了确认就失效 */
|
|||
|
|
revision: number;
|
|||
|
|
status: PendingStatus;
|
|||
|
|
decision?: ApprovalDecision;
|
|||
|
|
decidedBy?: string;
|
|||
|
|
decidedAt?: number;
|
|||
|
|
/** 执行幂等键：同一写请求重试不重复生效 */
|
|||
|
|
idempotencyKey?: string;
|
|||
|
|
/** 确认请求的幂等键 */
|
|||
|
|
decisionIdempotencyKey?: string;
|
|||
|
|
grantId?: string;
|
|||
|
|
receipt: ExecutionReceipt;
|
|||
|
|
expiresAt: number;
|
|||
|
|
createdAt: number;
|
|||
|
|
updatedAt: number;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
export interface CreatePendingInput {
|
|||
|
|
sessionId: string;
|
|||
|
|
projectId: string | null;
|
|||
|
|
ownerUserId: string;
|
|||
|
|
tenantId: string;
|
|||
|
|
capabilityId: string;
|
|||
|
|
providerId: string;
|
|||
|
|
paramsDigest: string;
|
|||
|
|
paramsPreview: Record<string, unknown>;
|
|||
|
|
/** 原始参数的密文：确认后要照原样执行，但库里不留明文 */
|
|||
|
|
paramsSealed: SealedSecret;
|
|||
|
|
impactSummary: string;
|
|||
|
|
revision: number;
|
|||
|
|
expiresAt: number;
|
|||
|
|
idempotencyKey?: string;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
export type DecideKind = 'approved' | 'rejected' | 'expired' | 'replayed' | 'not-found' | 'revision-mismatch';
|
|||
|
|
|
|||
|
|
export interface DecideResult {
|
|||
|
|
kind: DecideKind;
|
|||
|
|
action: PendingAction;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
interface PendingRow {
|
|||
|
|
execution_id: string;
|
|||
|
|
approval_id: string;
|
|||
|
|
session_id: string;
|
|||
|
|
project_id: string | null;
|
|||
|
|
owner_user_id: string;
|
|||
|
|
tenant_id: string;
|
|||
|
|
capability_id: string;
|
|||
|
|
provider_id: string;
|
|||
|
|
params_digest: string;
|
|||
|
|
params_preview: string;
|
|||
|
|
params_iv: string | null;
|
|||
|
|
params_ciphertext: string | null;
|
|||
|
|
params_tag: string | null;
|
|||
|
|
impact_summary: string;
|
|||
|
|
revision: number;
|
|||
|
|
status: string;
|
|||
|
|
decision: string | null;
|
|||
|
|
decided_by: string | null;
|
|||
|
|
decided_at: number | null;
|
|||
|
|
idempotency_key: string | null;
|
|||
|
|
decision_idempotency_key: string | null;
|
|||
|
|
grant_id: string | null;
|
|||
|
|
receipt: string;
|
|||
|
|
expires_at: number;
|
|||
|
|
created_at: number;
|
|||
|
|
updated_at: number;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function sealedFromRow(row: PendingRow): SealedSecret {
|
|||
|
|
return { iv: row.params_iv ?? '', ciphertext: row.params_ciphertext ?? '', tag: row.params_tag ?? '' };
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function fromRow(row: PendingRow): PendingAction {
|
|||
|
|
return {
|
|||
|
|
executionId: row.execution_id,
|
|||
|
|
approvalId: row.approval_id,
|
|||
|
|
sessionId: row.session_id,
|
|||
|
|
projectId: row.project_id,
|
|||
|
|
ownerUserId: row.owner_user_id,
|
|||
|
|
tenantId: row.tenant_id,
|
|||
|
|
capabilityId: row.capability_id,
|
|||
|
|
providerId: row.provider_id,
|
|||
|
|
paramsDigest: row.params_digest,
|
|||
|
|
paramsPreview: JSON.parse(row.params_preview) as Record<string, unknown>,
|
|||
|
|
paramsSealed: sealedFromRow(row),
|
|||
|
|
impactSummary: row.impact_summary,
|
|||
|
|
revision: row.revision,
|
|||
|
|
status: row.status as PendingStatus,
|
|||
|
|
...(row.decision === null ? {} : { decision: row.decision as ApprovalDecision }),
|
|||
|
|
...(row.decided_by === null ? {} : { decidedBy: row.decided_by }),
|
|||
|
|
...(row.decided_at === null ? {} : { decidedAt: row.decided_at }),
|
|||
|
|
...(row.idempotency_key === null ? {} : { idempotencyKey: row.idempotency_key }),
|
|||
|
|
...(row.decision_idempotency_key === null ? {} : { decisionIdempotencyKey: row.decision_idempotency_key }),
|
|||
|
|
...(row.grant_id === null ? {} : { grantId: row.grant_id }),
|
|||
|
|
receipt: JSON.parse(row.receipt) as ExecutionReceipt,
|
|||
|
|
expiresAt: row.expires_at,
|
|||
|
|
createdAt: row.created_at,
|
|||
|
|
updatedAt: row.updated_at,
|
|||
|
|
};
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
export class PendingActionStore {
|
|||
|
|
private readonly memory = new Map<string, PendingAction>();
|
|||
|
|
|
|||
|
|
constructor(
|
|||
|
|
private readonly db?: Database,
|
|||
|
|
private readonly now: () => number = Date.now,
|
|||
|
|
) {}
|
|||
|
|
|
|||
|
|
create(input: CreatePendingInput): PendingAction {
|
|||
|
|
const at = this.now();
|
|||
|
|
const action: PendingAction = {
|
|||
|
|
executionId: `exec-${randomUUID()}`,
|
|||
|
|
approvalId: `apr-${randomUUID()}`,
|
|||
|
|
sessionId: input.sessionId,
|
|||
|
|
projectId: input.projectId,
|
|||
|
|
ownerUserId: input.ownerUserId,
|
|||
|
|
tenantId: input.tenantId,
|
|||
|
|
capabilityId: input.capabilityId,
|
|||
|
|
providerId: input.providerId,
|
|||
|
|
paramsDigest: input.paramsDigest,
|
|||
|
|
paramsPreview: input.paramsPreview,
|
|||
|
|
paramsSealed: input.paramsSealed,
|
|||
|
|
impactSummary: input.impactSummary,
|
|||
|
|
revision: input.revision,
|
|||
|
|
status: 'pending-confirmation',
|
|||
|
|
...(input.idempotencyKey === undefined ? {} : { idempotencyKey: input.idempotencyKey }),
|
|||
|
|
receipt: { executionId: '', status: 'pending-confirmation' },
|
|||
|
|
expiresAt: input.expiresAt,
|
|||
|
|
createdAt: at,
|
|||
|
|
updatedAt: at,
|
|||
|
|
};
|
|||
|
|
action.receipt = { executionId: action.executionId, status: 'pending-confirmation', approvalId: action.approvalId };
|
|||
|
|
this.save(action);
|
|||
|
|
return action;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
get(approvalId: string): PendingAction | undefined {
|
|||
|
|
if (this.db) {
|
|||
|
|
const row = this.db.prepare('select * from pending_actions where approval_id = ?').get(approvalId) as PendingRow | undefined;
|
|||
|
|
return row ? fromRow(row) : undefined;
|
|||
|
|
}
|
|||
|
|
return this.memory.get(approvalId);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
byExecution(executionId: string): PendingAction | undefined {
|
|||
|
|
if (this.db) {
|
|||
|
|
const row = this.db.prepare('select * from pending_actions where execution_id = ?').get(executionId) as PendingRow | undefined;
|
|||
|
|
return row ? fromRow(row) : undefined;
|
|||
|
|
}
|
|||
|
|
return [...this.memory.values()].find((action) => action.executionId === executionId);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/** 同一写请求的重试：找到原待确认动作，不新建第二张确认卡 */
|
|||
|
|
findByIdempotencyKey(sessionId: string, idempotencyKey: string): PendingAction | undefined {
|
|||
|
|
if (this.db) {
|
|||
|
|
const row = this.db
|
|||
|
|
.prepare('select * from pending_actions where session_id = ? and idempotency_key = ? limit 1')
|
|||
|
|
.get(sessionId, idempotencyKey) as PendingRow | undefined;
|
|||
|
|
return row ? fromRow(row) : undefined;
|
|||
|
|
}
|
|||
|
|
return [...this.memory.values()].find((action) => action.sessionId === sessionId && action.idempotencyKey === idempotencyKey);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
listBySession(sessionId: string): PendingAction[] {
|
|||
|
|
if (this.db) {
|
|||
|
|
const rows = this.db
|
|||
|
|
.prepare('select * from pending_actions where session_id = ? order by created_at')
|
|||
|
|
.all(sessionId) as unknown as PendingRow[];
|
|||
|
|
return rows.map(fromRow);
|
|||
|
|
}
|
|||
|
|
return [...this.memory.values()].filter((action) => action.sessionId === sessionId).sort((a, b) => a.createdAt - b.createdAt);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/** 确认或拒绝。返回 kind 描述这次调用发生了什么；已决策过的再次调用返回 replayed（幂等） */
|
|||
|
|
decide(
|
|||
|
|
approvalId: string,
|
|||
|
|
input: { decision: 'approve' | 'reject'; revision: number; decidedBy: string; idempotencyKey: string },
|
|||
|
|
): DecideResult | undefined {
|
|||
|
|
const action = this.get(approvalId);
|
|||
|
|
if (!action) return undefined;
|
|||
|
|
|
|||
|
|
// 已经决策过：同一请求重放返回同一结果；不重复执行
|
|||
|
|
if (action.decision !== undefined && action.decision !== 'expired') return { kind: 'replayed', action };
|
|||
|
|
|
|||
|
|
const at = this.now();
|
|||
|
|
if (at > action.expiresAt) {
|
|||
|
|
const expired: PendingAction = { ...action, status: 'expired', decision: 'expired', decidedBy: input.decidedBy, decidedAt: at, decisionIdempotencyKey: input.idempotencyKey, updatedAt: at };
|
|||
|
|
this.save(expired);
|
|||
|
|
return { kind: 'expired', action: expired };
|
|||
|
|
}
|
|||
|
|
if (input.revision !== action.revision) {
|
|||
|
|
// 目标数据在等待确认期间变了：这次确认作废，必须重新发起（协议第 7 节）
|
|||
|
|
const expired: PendingAction = { ...action, status: 'expired', decision: 'expired', decidedBy: input.decidedBy, decidedAt: at, decisionIdempotencyKey: input.idempotencyKey, updatedAt: at };
|
|||
|
|
this.save(expired);
|
|||
|
|
return { kind: 'revision-mismatch', action: expired };
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
if (input.decision === 'reject') {
|
|||
|
|
const rejected: PendingAction = {
|
|||
|
|
...action,
|
|||
|
|
status: 'rejected',
|
|||
|
|
decision: 'rejected',
|
|||
|
|
decidedBy: input.decidedBy,
|
|||
|
|
decidedAt: at,
|
|||
|
|
decisionIdempotencyKey: input.idempotencyKey,
|
|||
|
|
updatedAt: at,
|
|||
|
|
};
|
|||
|
|
this.save(rejected);
|
|||
|
|
return { kind: 'rejected', action: rejected };
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const approved: PendingAction = {
|
|||
|
|
...action,
|
|||
|
|
decision: 'approved',
|
|||
|
|
decidedBy: input.decidedBy,
|
|||
|
|
decidedAt: at,
|
|||
|
|
decisionIdempotencyKey: input.idempotencyKey,
|
|||
|
|
updatedAt: at,
|
|||
|
|
};
|
|||
|
|
this.save(approved);
|
|||
|
|
return { kind: 'approved', action: approved };
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/** 签发一次性授权后记账 */
|
|||
|
|
attachGrant(approvalId: string, grantId: string): PendingAction | undefined {
|
|||
|
|
const action = this.get(approvalId);
|
|||
|
|
if (!action) return undefined;
|
|||
|
|
const updated: PendingAction = { ...action, grantId, updatedAt: this.now() };
|
|||
|
|
this.save(updated);
|
|||
|
|
return updated;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/** 执行结束：回执与状态落到同一行 */
|
|||
|
|
complete(executionId: string, receipt: ExecutionReceipt): PendingAction | undefined {
|
|||
|
|
const action = this.byExecution(executionId);
|
|||
|
|
if (!action) return undefined;
|
|||
|
|
const status: PendingStatus = receipt.status === 'succeeded' ? 'succeeded' : receipt.status === 'failed' ? 'failed' : 'pending-confirmation';
|
|||
|
|
const updated: PendingAction = { ...action, status, receipt, updatedAt: this.now() };
|
|||
|
|
this.save(updated);
|
|||
|
|
return updated;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
private save(action: PendingAction): void {
|
|||
|
|
if (this.db) {
|
|||
|
|
this.db
|
|||
|
|
.prepare(
|
|||
|
|
`insert into pending_actions (execution_id, approval_id, session_id, project_id, owner_user_id, tenant_id, capability_id, provider_id, params_digest, params_preview, params_iv, params_ciphertext, params_tag, impact_summary, revision, status, decision, decided_by, decided_at, idempotency_key, decision_idempotency_key, grant_id, receipt, expires_at, created_at, updated_at)
|
|||
|
|
values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
|
|||
|
|
on conflict(execution_id) do update set
|
|||
|
|
status = excluded.status,
|
|||
|
|
decision = excluded.decision,
|
|||
|
|
decided_by = excluded.decided_by,
|
|||
|
|
decided_at = excluded.decided_at,
|
|||
|
|
decision_idempotency_key = excluded.decision_idempotency_key,
|
|||
|
|
grant_id = excluded.grant_id,
|
|||
|
|
receipt = excluded.receipt,
|
|||
|
|
updated_at = excluded.updated_at`,
|
|||
|
|
)
|
|||
|
|
.run(
|
|||
|
|
action.executionId,
|
|||
|
|
action.approvalId,
|
|||
|
|
action.sessionId,
|
|||
|
|
action.projectId,
|
|||
|
|
action.ownerUserId,
|
|||
|
|
action.tenantId,
|
|||
|
|
action.capabilityId,
|
|||
|
|
action.providerId,
|
|||
|
|
action.paramsDigest,
|
|||
|
|
JSON.stringify(action.paramsPreview),
|
|||
|
|
action.paramsSealed.iv,
|
|||
|
|
action.paramsSealed.ciphertext,
|
|||
|
|
action.paramsSealed.tag,
|
|||
|
|
action.impactSummary,
|
|||
|
|
action.revision,
|
|||
|
|
action.status,
|
|||
|
|
action.decision ?? null,
|
|||
|
|
action.decidedBy ?? null,
|
|||
|
|
action.decidedAt ?? null,
|
|||
|
|
action.idempotencyKey ?? null,
|
|||
|
|
action.decisionIdempotencyKey ?? null,
|
|||
|
|
action.grantId ?? null,
|
|||
|
|
JSON.stringify(action.receipt),
|
|||
|
|
action.expiresAt,
|
|||
|
|
action.createdAt,
|
|||
|
|
action.updatedAt,
|
|||
|
|
);
|
|||
|
|
return;
|
|||
|
|
}
|
|||
|
|
this.memory.set(action.approvalId, action);
|
|||
|
|
}
|
|||
|
|
}
|