《互联网产品的 AI 架构·多能力编排与任务闭环》9.2 外部动作的授权边界

// file: src/orch/action-authz.ts
// tier: L1
// verify: node --test test/orch/permission.test.ts

import { AiError } from "../core/errors.ts";

/** 外部动作只列出有副作用的三类；读操作不走这套授权。 */
export type ActionKind = "order.create" | "message.send" | "refund.issue";

export interface ActionRequest {
  requestId: string;
  tenantId: string;
  subjectId: string;
  action: ActionKind;
  resourceId: string;
  amountMicros: number;
  irreversible: boolean;
  idempotencyKey: string;
  payloadFingerprint: string;
  requestedAt: number;
}

/** 主体策略：某人在某租户内能做哪些动作、金额上限与资源前缀。 */
export interface ActionPolicy {
  tenantId: string;
  subjectId: string;
  actions: readonly ActionKind[];
  maxAmountMicros: number;
  resourcePrefixes: readonly string[];
}

/** 一次性令牌绑定主体、动作与资源，不能跨动作复用。 */
export interface OneTimeToken {
  tokenId: string;
  tenantId: string;
  subjectId: string;
  action: ActionKind;
  resourceId: string;
  expiresAt: number;
  used: boolean;
}

export interface Confirmation {
  approverId: string;
  approvedAt: number;
  requestFingerprint: string;
  channel: "human" | "policy";
}

export interface IdempotencyRecord {
  key: string;
  fingerprint: string;
  action: ActionKind;
  status: "executed" | "rejected";
  decisionId: string;
}

export interface AuthorizationState {
  tokens: Map<string, OneTimeToken>;
  idempotency: Map<string, IdempotencyRecord>;
}

export type AuthzReason =
  | "ok"
  | "unknown-subject"
  | "action-not-granted"
  | "resource-out-of-scope"
  | "amount-exceeded"
  | "token-missing"
  | "token-mismatch"
  | "token-used"
  | "token-expired"
  | "idempotency-required"
  | "idempotent-replay"
  | "idempotency-conflict"
  | "confirmation-required"
  | "self-approval"
  | "confirmation-fingerprint"
  | "confirmation-future"
  | "confirmation-stale";

export interface AuthorizationDecision {
  allowed: boolean;
  reason: AuthzReason;
  requiresConfirmation: boolean;
  replay: boolean;
  tokenConsumed: boolean;
  decisionId: string;
}

/** 达到或超过这个金额的动作必须人工确认；不可逆动作无条件确认。 */
export const CONFIRMATION_THRESHOLD_MICROS = 100_000;
export const CONFIRMATION_WINDOW_MS = 10 * 60_000;

export function createAuthorizationState(): AuthorizationState {
  return { tokens: new Map(), idempotency: new Map() };
}

function fail(message: string): never {
  throw new AiError("invalid-request", `action-authz: ${message}`);
}

function nonEmpty(value: string, field: string): string {
  const trimmed = value.trim();
  if (trimmed === "") fail(`${field} 不能为空`);
  return trimmed;
}

function decision(
  request: ActionRequest,
  allowed: boolean,
  reason: AuthzReason,
  extras: Partial<Pick<AuthorizationDecision, "requiresConfirmation" | "replay" | "tokenConsumed">> = {},
): AuthorizationDecision {
  return {
    allowed,
    reason,
    requiresConfirmation: extras.requiresConfirmation ?? false,
    replay: extras.replay ?? false,
    tokenConsumed: extras.tokenConsumed ?? false,
    decisionId: `authz:${request.requestId}:${request.idempotencyKey}`,
  };
}

/**
 * 外部动作的授权判定。顺序是：主体策略、令牌绑定、幂等重放、人工确认、一次性消费。
 * 任何一步失败都返回拒绝，不抛异常；抛异常只留给结构错误。
 */
export function authorizeAction(
  request: ActionRequest,
  token: OneTimeToken | null,
  policy: ActionPolicy,
  state: AuthorizationState,
  confirmation: Confirmation | null = null,
  now: number = request.requestedAt,
  confirmationWindowMs = CONFIRMATION_WINDOW_MS,
): AuthorizationDecision {
  nonEmpty(request.requestId, "requestId");
  nonEmpty(request.subjectId, "subjectId");
  nonEmpty(request.payloadFingerprint, "payloadFingerprint");
  if (!Number.isFinite(request.amountMicros) || request.amountMicros < 0) {
    fail("amountMicros 必须是 >= 0 的有限数");
  }
  if (!Number.isFinite(now) || !Number.isFinite(confirmationWindowMs) || confirmationWindowMs < 0) {
    fail("时间参数非法");
  }

  if (request.idempotencyKey.trim() === "") {
    return decision(request, false, "idempotency-required");
  }
  if (policy.tenantId !== request.tenantId || policy.subjectId !== request.subjectId) {
    return decision(request, false, "unknown-subject");
  }
  if (!policy.actions.includes(request.action)) {
    return decision(request, false, "action-not-granted");
  }
  if (!policy.resourcePrefixes.some((prefix) => request.resourceId.startsWith(prefix))) {
    return decision(request, false, "resource-out-of-scope");
  }
  if (request.amountMicros > policy.maxAmountMicros) {
    return decision(request, false, "amount-exceeded");
  }
  if (token === null) return decision(request, false, "token-missing");
  if (
    token.tenantId !== request.tenantId ||
    token.subjectId !== request.subjectId ||
    token.action !== request.action ||
    token.resourceId !== request.resourceId
  ) {
    return decision(request, false, "token-mismatch");
  }
  if (token.expiresAt <= now) return decision(request, false, "token-expired");

  const existing = state.idempotency.get(request.idempotencyKey);
  if (existing !== undefined) {
    if (existing.fingerprint === request.payloadFingerprint && existing.action === request.action) {
      return {
        allowed: true,
        reason: "idempotent-replay",
        requiresConfirmation: false,
        replay: true,
        tokenConsumed: false,
        decisionId: existing.decisionId,
      };
    }
    return decision(request, false, "idempotency-conflict");
  }

  if (token.used) return decision(request, false, "token-used");

  const needsConfirmation =
    request.irreversible || request.amountMicros >= CONFIRMATION_THRESHOLD_MICROS;
  if (needsConfirmation) {
    if (confirmation === null) {
      return decision(request, false, "confirmation-required", { requiresConfirmation: true });
    }
    if (confirmation.approverId === request.subjectId) {
      return decision(request, false, "self-approval");
    }
    if (confirmation.requestFingerprint !== request.payloadFingerprint) {
      return decision(request, false, "confirmation-fingerprint");
    }
    if (confirmation.approvedAt > now) {
      return decision(request, false, "confirmation-future");
    }
    if (now - confirmation.approvedAt > confirmationWindowMs) {
      return decision(request, false, "confirmation-stale");
    }
  }

  token.used = true;
  state.idempotency.set(request.idempotencyKey, {
    key: request.idempotencyKey,
    fingerprint: request.payloadFingerprint,
    action: request.action,
    status: "executed",
    decisionId: `authz:${request.requestId}:${request.idempotencyKey}`,
  });
  return decision(request, true, "ok", { tokenConsumed: true });
}