《互联网产品的 AI 架构·多能力编排与任务闭环》9.1 跨能力的权限传播

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

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

/** 身份只分三类：终端用户、编排器、能力节点。节点不能冒充用户。 */
export type PrincipalKind = "user" | "orchestrator" | "node";

export interface Principal {
  id: string;
  kind: PrincipalKind;
  tenantId: string;
}

/** 一条权限 = 资源 + 允许的动作集合。资源与动作都必须是稳定标识。 */
export interface Scope {
  resource: string;
  actions: readonly string[];
}

/**
 * 某一次节点调用看到的安全上下文。
 * subject 是最终用户，actor 是当前节点代理，两者不能混用。
 */
export interface PermissionContext {
  runId: string;
  subject: Principal;
  actor: Principal;
  tenantId: string;
  scopes: readonly Scope[];
  dataLabels: readonly string[];
  expiresAt: number;
  delegation: readonly string[];
}

/** 节点声明自己需要的权限；与父上下文求交集后才成为有效权限。 */
export interface NodeGrant {
  actor: Principal;
  scopes: readonly Scope[];
  dataLabels: readonly string[];
  expiresAt: number;
}

export type PropagationReason =
  | "tenant-mismatch"
  | "principal-kind"
  | "expired"
  | "delegation-depth";

export interface PropagationResult {
  /** 被拒绝时为 null；调用方必须按“没有上下文”处理，而不是复用父上下文。 */
  context: PermissionContext | null;
  effectiveScopes: Scope[];
  droppedScopes: Scope[];
  droppedDataLabels: string[];
  parentActions: number;
  effectiveActions: number;
  amplificationAttempted: boolean;
  narrowed: boolean;
  denied: boolean;
  reason?: PropagationReason;
  delegationDepth: number;
}

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

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

function canonicalActions(actions: readonly string[]): string[] {
  const seen = new Set<string>();
  for (const action of actions) seen.add(nonEmpty(action, "action"));
  return [...seen].sort();
}

/** 同一资源的动作合并去重并排序，保证同一集合每次得到同一表示。 */
export function canonicalScopes(scopes: readonly Scope[]): Scope[] {
  const byResource = new Map<string, Set<string>>();
  for (const scope of scopes) {
    const resource = nonEmpty(scope.resource, "resource");
    const actions = byResource.get(resource) ?? new Set<string>();
    for (const action of canonicalActions(scope.actions)) actions.add(action);
    byResource.set(resource, actions);
  }
  return [...byResource.entries()]
    .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
    .map(([resource, actions]) => ({ resource, actions: [...actions].sort() }));
}

function scopeMap(scopes: readonly Scope[]): Map<string, Set<string>> {
  const map = new Map<string, Set<string>>();
  for (const scope of canonicalScopes(scopes)) map.set(scope.resource, new Set(scope.actions));
  return map;
}

/** 父集合与请求集合的交集；请求中超出父集合的部分进入 dropped。 */
export function intersectScopes(
  parent: readonly Scope[],
  requested: readonly Scope[],
): { effective: Scope[]; dropped: Scope[] } {
  const parentMap = scopeMap(parent);
  const effective: Scope[] = [];
  const dropped: Scope[] = [];
  for (const scope of canonicalScopes(requested)) {
    const allowed = parentMap.get(scope.resource) ?? new Set<string>();
    const kept = scope.actions.filter((action) => allowed.has(action));
    const lost = scope.actions.filter((action) => !allowed.has(action));
    if (kept.length > 0) effective.push({ resource: scope.resource, actions: kept });
    if (lost.length > 0) dropped.push({ resource: scope.resource, actions: lost });
  }
  return { effective: canonicalScopes(effective), dropped: canonicalScopes(dropped) };
}

/** 请求的每个动作都能在父集合里找到，才算真正的子集。 */
export function isScopeSubset(requested: readonly Scope[], granted: readonly Scope[]): boolean {
  return intersectScopes(granted, requested).dropped.length === 0;
}

export function scopeActionCount(scopes: readonly Scope[]): number {
  return canonicalScopes(scopes).reduce((total, scope) => total + scope.actions.length, 0);
}

export function can(
  context: PermissionContext,
  resource: string,
  action: string,
  now = 0,
): boolean {
  if (context.expiresAt <= now) return false;
  const actions = scopeMap(context.scopes).get(resource);
  return actions !== undefined && actions.has(action);
}

function deny(
  parent: PermissionContext,
  reason: PropagationReason,
  grantedScopes: readonly Scope[],
  grantedLabels: readonly string[],
): PropagationResult {
  const dropped = canonicalScopes(grantedScopes);
  return {
    context: null,
    effectiveScopes: [],
    droppedScopes: dropped,
    droppedDataLabels: [...new Set(grantedLabels)].sort(),
    parentActions: scopeActionCount(parent.scopes),
    effectiveActions: 0,
    amplificationAttempted: dropped.length > 0,
    narrowed: true,
    denied: true,
    reason,
    delegationDepth: parent.delegation.length,
  };
}

/**
 * 把一个节点需要的权限收敛进父上下文。
 * 结果只会是父集合的子集；租户、数据标签、过期时间与委派深度都只能收窄。
 */
export function propagatePermission(
  parent: PermissionContext,
  grant: NodeGrant,
  now: number,
  maxDelegationDepth = 4,
): PropagationResult {
  if (parent.tenantId !== parent.subject.tenantId) fail("subject 与上下文租户不一致");
  if (parent.tenantId !== parent.actor.tenantId) fail("actor 与上下文租户不一致");
  if (!Number.isFinite(now)) fail("now 必须是有限数");
  if (!Number.isInteger(maxDelegationDepth) || maxDelegationDepth < 0) {
    fail("maxDelegationDepth 必须是 >= 0 的整数");
  }
  const grantedScopes = canonicalScopes(grant.scopes);
  const grantedLabels = [...new Set(grant.dataLabels.map((label) => nonEmpty(label, "dataLabel")))].sort();

  if (grant.actor.kind === "user") return deny(parent, "principal-kind", grantedScopes, grantedLabels);
  if (grant.actor.tenantId !== parent.tenantId) {
    return deny(parent, "tenant-mismatch", grantedScopes, grantedLabels);
  }
  if (parent.expiresAt <= now || grant.expiresAt <= now) {
    return deny(parent, "expired", grantedScopes, grantedLabels);
  }
  if (parent.delegation.length >= maxDelegationDepth) {
    return deny(parent, "delegation-depth", grantedScopes, grantedLabels);
  }

  const intersection = intersectScopes(parent.scopes, grantedScopes);
  const parentLabels = new Set(parent.dataLabels);
  const effectiveLabels = grantedLabels.filter((label) => parentLabels.has(label));
  const droppedLabels = grantedLabels.filter((label) => !parentLabels.has(label));
  const effective = intersection.effective;
  const effectiveActions = scopeActionCount(effective);
  const parentActions = scopeActionCount(parent.scopes);
  const delegation = [...parent.delegation, `${parent.actor.id}->${grant.actor.id}`];

  return {
    context: {
      runId: parent.runId,
      subject: parent.subject,
      actor: grant.actor,
      tenantId: parent.tenantId,
      scopes: effective,
      dataLabels: effectiveLabels,
      expiresAt: Math.min(parent.expiresAt, grant.expiresAt),
      delegation,
    },
    effectiveScopes: effective,
    droppedScopes: intersection.dropped,
    droppedDataLabels: droppedLabels,
    parentActions,
    effectiveActions,
    amplificationAttempted: intersection.dropped.length > 0 || droppedLabels.length > 0,
    narrowed: effectiveActions < parentActions || effectiveLabels.length < parentLabels.size,
    denied: false,
    delegationDepth: delegation.length,
  };
}