413 lines
18 KiB
TypeScript
413 lines
18 KiB
TypeScript
/**
|
||
* Core.invoke：工具调用的唯一出口（架构设计 4 / 术语表规则 3）。
|
||
*
|
||
* 一次调用经过五道关（A4 控制面）：身份 → 策略 → （需要确认就先开确认卡）→ 凭据 → 执行 → 审计。
|
||
* 三条不变量：
|
||
* 1. 只有一个出口：引擎不论怎么调工具，都落到这里
|
||
* 2. 平台的允许不能覆盖业务系统的拒绝：Provider 回 forbidden 就是 forbidden，不改写成成功、不重试写操作
|
||
* 3. 库里与日志里没有参数与凭据明文：参数只留摘要（确认卡用的参数密文单独存），凭据只在执行期经句柄取用
|
||
*/
|
||
import { randomUUID } from 'node:crypto';
|
||
|
||
import type { ExecutionReceipt } from '@aps/contracts';
|
||
import { isErrorKind, ProviderError, type Capability, type ErrorKind, type ExecutionContext, type ExecutionIdentity, type ImpactPreview, type Provider } from '@aps/provider-sdk';
|
||
import type { ControlPlane } from '../control-plane/control-plane.js';
|
||
import type { AccountBinding } from '../identity/context.js';
|
||
import type { CapabilityRegistry } from '../registry/registry.js';
|
||
import { digestParams, ExecutionStore, type ExecutionRecord } from './store.js';
|
||
|
||
export interface InvokeRequest {
|
||
/** 调用者身份（A4.1 起由身份上下文补齐，现在只需要用户与租户） */
|
||
subject: { userId: string; tenantId: string };
|
||
sessionId: string;
|
||
projectId?: string | null;
|
||
capabilityId: string;
|
||
params: unknown;
|
||
idempotencyKey?: string;
|
||
/** 覆盖默认超时（毫秒） */
|
||
timeoutMs?: number;
|
||
}
|
||
|
||
export interface ApprovalInput {
|
||
decision: 'approve' | 'reject';
|
||
revision: number;
|
||
idempotencyKey: string;
|
||
note?: string;
|
||
}
|
||
|
||
export type ApprovalResult =
|
||
| { kind: 'ok'; approvalId: string; decision: 'approved' | 'rejected' | 'expired'; receipt?: ExecutionReceipt }
|
||
| { kind: 'not-found' }
|
||
| { kind: 'forbidden' };
|
||
|
||
export interface CoreOptions {
|
||
registry: CapabilityRegistry;
|
||
executions?: ExecutionStore;
|
||
defaultTimeoutMs?: number;
|
||
/** A4 控制面：不传则退化为「无策略的直通执行」（只用于老用例与本地试验） */
|
||
controlPlane?: ControlPlane;
|
||
}
|
||
|
||
export interface Core {
|
||
invoke(request: InvokeRequest): Promise<ExecutionReceipt>;
|
||
/** 确认卡响应：校验归属与版本 → 签发一次性授权 → 执行 → 落回执 */
|
||
approve(subject: { userId: string; tenantId: string }, approvalId: string, input: ApprovalInput): Promise<ApprovalResult>;
|
||
executions: ExecutionStore;
|
||
registry: CapabilityRegistry;
|
||
approvals?: ControlPlane['approvals'];
|
||
}
|
||
|
||
const DEFAULT_TIMEOUT_MS = 30_000;
|
||
|
||
function failed(executionId: string, errorKind: ErrorKind, message: string): ExecutionReceipt {
|
||
return { executionId, status: 'failed', errorKind, result: { message } };
|
||
}
|
||
|
||
/** 把任意异常归一化成六分类之一（实施设计 5） */
|
||
function normalizeError(error: unknown): { kind: ErrorKind; message: string } {
|
||
if (error instanceof ProviderError) return { kind: error.kind, message: error.message };
|
||
if (error instanceof Error) return { kind: 'unknown_result', message: error.message };
|
||
return { kind: 'unknown_result', message: 'Provider 抛出未知错误' };
|
||
}
|
||
|
||
interface RunInput {
|
||
executionId: string;
|
||
capability: Capability;
|
||
provider: Provider;
|
||
providerId: string;
|
||
subject: { userId: string; tenantId: string };
|
||
sessionId: string;
|
||
projectId: string | null;
|
||
params: unknown;
|
||
idempotencyKey?: string;
|
||
timeoutMs: number;
|
||
binding?: AccountBinding;
|
||
/** Provider 声明的登录方式；有值才谈得上"登录态失效" */
|
||
authKind?: string;
|
||
}
|
||
|
||
export function createCore(options: CoreOptions): Core {
|
||
const executions = options.executions ?? new ExecutionStore();
|
||
const defaultTimeoutMs = options.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
|
||
const control = options.controlPlane;
|
||
|
||
/** 真正落到 Provider 的那一步：签发一次性授权 → 调用 → 归一化 → 审计 */
|
||
async function run(input: RunInput): Promise<ExecutionReceipt> {
|
||
const paramsDigest = digestParams(input.params);
|
||
const timeoutMs = input.timeoutMs;
|
||
const context: ExecutionContext = {
|
||
executionId: input.executionId,
|
||
sessionId: input.sessionId,
|
||
projectId: input.projectId,
|
||
subject: { userId: input.subject.userId, tenantId: input.subject.tenantId },
|
||
...(input.binding === undefined
|
||
? {}
|
||
: { identity: { accountId: input.binding.accountId, displayName: input.binding.displayName } satisfies ExecutionIdentity }),
|
||
...(input.idempotencyKey === undefined ? {} : { idempotencyKey: input.idempotencyKey }),
|
||
deadlineAt: control ? control.now() + timeoutMs : Date.now() + timeoutMs,
|
||
};
|
||
|
||
// 凭据：只在这一层解开，句柄随上下文传下去；参数里永远没有它
|
||
const grant =
|
||
control && input.binding && control.credentials.has(input.subject, input.providerId)
|
||
? control.credentials.issue({
|
||
subject: input.subject,
|
||
providerId: input.providerId,
|
||
accountId: input.binding.accountId,
|
||
executionId: input.executionId,
|
||
ttlMs: timeoutMs,
|
||
})
|
||
: undefined;
|
||
if (grant) {
|
||
context.credentials = { grantId: grant.grantId, read: async () => grant.read() };
|
||
}
|
||
|
||
executions.create({
|
||
executionId: input.executionId,
|
||
capabilityId: input.capability.id,
|
||
providerId: input.providerId,
|
||
sessionId: input.sessionId,
|
||
projectId: input.projectId,
|
||
subjectUserId: input.subject.userId,
|
||
paramsDigest,
|
||
...(input.idempotencyKey === undefined ? {} : { idempotencyKey: input.idempotencyKey }),
|
||
receipt: { executionId: input.executionId, status: 'accepted' },
|
||
});
|
||
control?.audit.append({
|
||
actorUserId: input.subject.userId,
|
||
tenantId: input.subject.tenantId,
|
||
event: 'execution.started',
|
||
executionId: input.executionId,
|
||
sessionId: input.sessionId,
|
||
capabilityId: input.capability.id,
|
||
providerId: input.providerId,
|
||
paramsDigest,
|
||
...(input.binding === undefined ? {} : { decision: input.binding.accountId }),
|
||
});
|
||
|
||
// 超时判定：超时不等于成功也不等于失败——结果未知（实施设计 5）
|
||
const timeout = new Promise<ExecutionReceipt>((resolve) => {
|
||
setTimeout(() => resolve(failed(input.executionId, 'unknown_result', `调用超过 ${timeoutMs}ms，结果未知`)), timeoutMs).unref();
|
||
});
|
||
|
||
let receipt: ExecutionReceipt;
|
||
try {
|
||
receipt = await Promise.race([input.provider.invoke(context, { capabilityId: input.capability.id, params: input.params }), timeout]);
|
||
} catch (error) {
|
||
const normalized = normalizeError(error);
|
||
receipt = failed(input.executionId, normalized.kind, normalized.message);
|
||
} finally {
|
||
// 一次性授权用完即废：结果未知也不延长
|
||
if (grant) control?.credentials.revoke(grant.grantId);
|
||
}
|
||
|
||
// Provider 返回的分类非法时归一为 unknown_result，避免脏值进记录
|
||
if (receipt.status === 'failed' && receipt.errorKind !== undefined && !isErrorKind(receipt.errorKind)) {
|
||
receipt = failed(input.executionId, 'unknown_result', `Provider 返回了未知错误分类 ${String(receipt.errorKind)}`);
|
||
}
|
||
|
||
executions.complete(input.executionId, receipt);
|
||
// 业务系统说"没登录/没权限"：把绑定标成过期，后续在策略层直接拒（ADR-0012）
|
||
if (receipt.status === 'failed' && receipt.errorKind === 'forbidden' && control && input.authKind !== undefined && input.binding !== undefined) {
|
||
const expired = control.identity.expire(input.subject, input.providerId);
|
||
if (expired !== undefined) {
|
||
control.audit.append({
|
||
actorUserId: input.subject.userId,
|
||
tenantId: input.subject.tenantId,
|
||
event: 'identity.expired',
|
||
executionId: input.executionId,
|
||
sessionId: input.sessionId,
|
||
capabilityId: input.capability.id,
|
||
providerId: input.providerId,
|
||
decision: 'expired',
|
||
detail: { authKind: input.authKind, reason: '业务系统拒绝，需重新绑定' },
|
||
});
|
||
}
|
||
}
|
||
control?.audit.append({
|
||
actorUserId: input.subject.userId,
|
||
tenantId: input.subject.tenantId,
|
||
event: receipt.status === 'failed' && receipt.errorKind === 'forbidden' ? 'provider.denied' : 'execution.finished',
|
||
executionId: input.executionId,
|
||
sessionId: input.sessionId,
|
||
capabilityId: input.capability.id,
|
||
providerId: input.providerId,
|
||
paramsDigest,
|
||
decision: receipt.status === 'failed' ? `failed:${receipt.errorKind ?? 'unknown_result'}` : receipt.status,
|
||
detail:
|
||
receipt.status === 'failed' && receipt.errorKind === 'forbidden'
|
||
? { by: 'provider', message: '业务系统拒绝了这次调用，平台不覆盖该结果' }
|
||
: {},
|
||
});
|
||
return receipt;
|
||
}
|
||
|
||
async function invoke(request: InvokeRequest): Promise<ExecutionReceipt> {
|
||
const capabilityId = request.capabilityId;
|
||
if (typeof capabilityId !== 'string' || capabilityId.trim() === '') {
|
||
return failed(`exec-${randomUUID()}`, 'invalid_argument', 'capabilityId 不能为空');
|
||
}
|
||
|
||
// 幂等：同一键的重试返回原回执，不重复执行
|
||
if (request.idempotencyKey) {
|
||
const existing = executions.findByIdempotencyKey(request.idempotencyKey);
|
||
if (existing) return existing.receipt;
|
||
}
|
||
|
||
const resolved = options.registry.resolve(capabilityId);
|
||
const executionId = `exec-${randomUUID()}`;
|
||
if (!resolved) {
|
||
return failed(executionId, 'invalid_argument', `能力 ${capabilityId} 未注册`);
|
||
}
|
||
|
||
const projectId = request.projectId ?? null;
|
||
const base: RunInput = {
|
||
executionId,
|
||
capability: resolved.capability,
|
||
provider: resolved.provider,
|
||
providerId: resolved.providerId,
|
||
subject: request.subject,
|
||
sessionId: request.sessionId,
|
||
projectId,
|
||
params: request.params,
|
||
...(request.idempotencyKey === undefined ? {} : { idempotencyKey: request.idempotencyKey }),
|
||
timeoutMs: request.timeoutMs ?? defaultTimeoutMs,
|
||
...(resolved.authKind === undefined ? {} : { authKind: resolved.authKind }),
|
||
};
|
||
|
||
if (!control) return run(base);
|
||
|
||
const binding = control.identity.resolve(request.subject, resolved.providerId);
|
||
const decision = control.policy.decide({
|
||
subject: request.subject,
|
||
capability: resolved.capability,
|
||
providerId: resolved.providerId,
|
||
binding,
|
||
visible: control.isVisible(resolved.capability, request.subject),
|
||
requiresIdentity: resolved.requiresIdentity,
|
||
projectId,
|
||
});
|
||
|
||
if (decision.decision === 'deny') {
|
||
control.audit.append({
|
||
actorUserId: request.subject.userId,
|
||
tenantId: request.subject.tenantId,
|
||
event: 'policy.denied',
|
||
executionId,
|
||
sessionId: request.sessionId,
|
||
capabilityId,
|
||
providerId: resolved.providerId,
|
||
paramsDigest: digestParams(request.params),
|
||
decision: decision.code,
|
||
detail: { reason: decision.reason },
|
||
});
|
||
return failed(executionId, 'forbidden', decision.reason);
|
||
}
|
||
|
||
if (decision.decision === 'require-approval') {
|
||
return openApproval(base, binding, decision.code, decision.reason);
|
||
}
|
||
|
||
return run({ ...base, ...(binding === undefined ? {} : { binding }) });
|
||
}
|
||
|
||
/** 写操作：先开确认卡，落一条待确认动作，等用户点头再执行 */
|
||
async function openApproval(input: RunInput, binding: AccountBinding | undefined, code: string, reason: string): Promise<ExecutionReceipt> {
|
||
if (!control) return failed(input.executionId, 'unavailable', '平台未启用控制面，写操作不可用');
|
||
// 同一写请求重试：返回原来那张确认卡，不再开第二张
|
||
if (input.idempotencyKey !== undefined) {
|
||
const existing = control.approvals.findByIdempotencyKey(input.sessionId, input.idempotencyKey);
|
||
if (existing) return existing.receipt;
|
||
}
|
||
const paramsDigest = digestParams(input.params);
|
||
const preview = await previewFor(input);
|
||
const action = control.approvals.create({
|
||
sessionId: input.sessionId,
|
||
projectId: input.projectId,
|
||
ownerUserId: input.subject.userId,
|
||
tenantId: input.subject.tenantId,
|
||
capabilityId: input.capability.id,
|
||
providerId: input.providerId,
|
||
paramsDigest,
|
||
paramsPreview: preview.paramsPreview ?? {},
|
||
paramsSealed: control.credentials.sealText(JSON.stringify(input.params ?? null)),
|
||
impactSummary: preview.impactSummary,
|
||
revision: preview.revision,
|
||
expiresAt: control.now() + control.approvalTtlMs,
|
||
...(input.idempotencyKey === undefined ? {} : { idempotencyKey: input.idempotencyKey }),
|
||
});
|
||
const common = {
|
||
actorUserId: input.subject.userId,
|
||
tenantId: input.subject.tenantId,
|
||
executionId: action.executionId,
|
||
approvalId: action.approvalId,
|
||
sessionId: input.sessionId,
|
||
capabilityId: input.capability.id,
|
||
providerId: input.providerId,
|
||
paramsDigest,
|
||
} as const;
|
||
control.audit.append({ ...common, event: 'policy.requires_confirmation', decision: code, detail: { reason } });
|
||
control.audit.append({ ...common, event: 'approval.requested', decision: 'pending-confirmation', detail: { accountId: binding?.accountId ?? null, revision: action.revision, expiresAt: action.expiresAt } });
|
||
return { executionId: action.executionId, status: 'pending-confirmation', approvalId: action.approvalId };
|
||
}
|
||
|
||
/** 影响预览：Provider 说了算；它没说就退回能力描述（只影响确认卡信息量） */
|
||
async function previewFor(input: RunInput): Promise<ImpactPreview> {
|
||
if (!control) return { impactSummary: input.capability.description, revision: 0 };
|
||
if (input.provider.preview) {
|
||
try {
|
||
const context: ExecutionContext = {
|
||
executionId: input.executionId,
|
||
sessionId: input.sessionId,
|
||
projectId: input.projectId,
|
||
subject: { userId: input.subject.userId, tenantId: input.subject.tenantId },
|
||
deadlineAt: control.now() + input.timeoutMs,
|
||
};
|
||
return await input.provider.preview(context, { capabilityId: input.capability.id, params: input.params });
|
||
} catch {
|
||
/* 预览失败不阻塞确认流程：退回能力描述 */
|
||
}
|
||
}
|
||
return { impactSummary: input.capability.description, revision: 0 };
|
||
}
|
||
|
||
async function approve(subject: { userId: string; tenantId: string }, approvalId: string, input: ApprovalInput): Promise<ApprovalResult> {
|
||
if (!control) return { kind: 'not-found' };
|
||
const action = control.approvals.get(approvalId);
|
||
if (!action) return { kind: 'not-found' };
|
||
// 确认人是会话发起人本人：单用户场景不做委托与转派
|
||
if (action.ownerUserId !== subject.userId || action.tenantId !== subject.tenantId) return { kind: 'forbidden' };
|
||
|
||
const decided = control.approvals.decide(approvalId, {
|
||
decision: input.decision,
|
||
revision: input.revision,
|
||
decidedBy: subject.userId,
|
||
idempotencyKey: input.idempotencyKey,
|
||
});
|
||
if (!decided) return { kind: 'not-found' };
|
||
const { kind, action: current } = decided;
|
||
const common = {
|
||
actorUserId: subject.userId,
|
||
tenantId: subject.tenantId,
|
||
executionId: current.executionId,
|
||
approvalId,
|
||
sessionId: current.sessionId,
|
||
capabilityId: current.capabilityId,
|
||
providerId: current.providerId,
|
||
paramsDigest: current.paramsDigest,
|
||
} as const;
|
||
|
||
// 同一请求重放：返回同一结果，不重复执行
|
||
if (kind === 'replayed') {
|
||
return {
|
||
kind: 'ok',
|
||
approvalId,
|
||
decision: current.decision ?? 'expired',
|
||
...(current.decision === 'approved' ? { receipt: current.receipt } : {}),
|
||
};
|
||
}
|
||
|
||
if (kind === 'expired' || kind === 'revision-mismatch') {
|
||
control.audit.append({ ...common, event: 'approval.expired', decision: kind, detail: { requestedRevision: input.revision, currentRevision: action.revision } });
|
||
return { kind: 'ok', approvalId, decision: 'expired', ...(current.receipt.status === 'pending-confirmation' ? {} : { receipt: current.receipt }) };
|
||
}
|
||
|
||
if (kind === 'rejected') {
|
||
control.audit.append({ ...common, event: 'approval.decided', decision: 'rejected', ...(input.note === undefined ? {} : { detail: { note: input.note } }) });
|
||
return { kind: 'ok', approvalId, decision: 'rejected' };
|
||
}
|
||
|
||
control.audit.append({ ...common, event: 'approval.decided', decision: 'approved', ...(input.note === undefined ? {} : { detail: { note: input.note } }) });
|
||
|
||
const resolved = options.registry.resolve(current.capabilityId);
|
||
if (!resolved) {
|
||
const receipt = failed(current.executionId, 'invalid_argument', `能力 ${current.capabilityId} 已不在能力目录里`);
|
||
control.approvals.complete(current.executionId, receipt);
|
||
return { kind: 'ok', approvalId, decision: 'approved', receipt };
|
||
}
|
||
|
||
const plaintext = control.credentials.openText(current.paramsSealed);
|
||
const params: unknown = plaintext === undefined ? null : (JSON.parse(plaintext) as unknown);
|
||
const binding = control.identity.resolve(subject, current.providerId);
|
||
const receipt = await run({
|
||
executionId: current.executionId,
|
||
capability: resolved.capability,
|
||
provider: resolved.provider,
|
||
providerId: current.providerId,
|
||
subject,
|
||
sessionId: current.sessionId,
|
||
projectId: current.projectId,
|
||
params,
|
||
...(current.idempotencyKey === undefined ? {} : { idempotencyKey: current.idempotencyKey }),
|
||
timeoutMs: defaultTimeoutMs,
|
||
...(binding === undefined ? {} : { binding }),
|
||
...(resolved.authKind === undefined ? {} : { authKind: resolved.authKind }),
|
||
});
|
||
control.approvals.complete(current.executionId, receipt);
|
||
return { kind: 'ok', approvalId, decision: 'approved', receipt };
|
||
}
|
||
|
||
return { invoke, approve, executions, registry: options.registry, ...(control === undefined ? {} : { approvals: control.approvals }) };
|
||
}
|
||
|
||
export type { ExecutionRecord }; |