《互联网产品的客户端架构·规模化与架构演进》3.2 沙箱、权限与失败隔离

// file: src/plugin/plugin-sandbox.ts
// tier: L2
// verify: node --test test/plugin/plugin-sandbox.test.ts

export type Permission = "read" | "write" | "network" | "storage";

export type PermissionGrant = {
  permission: Permission;
  scopes: string[];
  quota: number;
};

export type PluginGrant = {
  pluginId: string;
  permissions: PermissionGrant[];
  failureThreshold: number;
};

export type SandboxRequest = {
  pluginId: string;
  permission: Permission;
  resource: string;
  units?: number;
};

export type DenyReason =
  | "plugin-unknown"
  | "permission-not-granted"
  | "resource-out-of-scope"
  | "quota-exceeded"
  | "circuit-open";

export type Decision =
  | { allowed: true; remaining: number }
  | { allowed: false; reason: DenyReason };

export type Job<T> = { pluginId: string; run: () => T };

export type JobResult<T> =
  | { pluginId: string; ok: true; value: T }
  | { pluginId: string; ok: false; error: string };

export type RunReport<T> = { results: Array<JobResult<T>>; failed: string[] };

export type PluginState = {
  failures: number;
  open: boolean;
  usage: Record<Permission, number>;
};

export type Sandbox = {
  authorize(request: SandboxRequest): Decision;
  runIsolated<T>(jobs: Array<Job<T>>): RunReport<T>;
  state(pluginId: string): PluginState | undefined;
};

export function matchScope(scope: string, resource: string): boolean {
  if (scope === "*") return true;
  const scopeParts = scope.split(":");
  const resourceParts = resource.split(":");
  if (scopeParts.length < 2 || resourceParts.length < 2) {
    return scope === resource;
  }
  if (scopeParts[0] !== resourceParts[0]) return false;
  const pattern = scopeParts.slice(1).join(":");
  const target = resourceParts.slice(1).join(":");
  if (pattern === target) return true;
  if (pattern.startsWith("*.")) {
    return (
      target.endsWith(pattern.slice(1)) &&
      target.length > pattern.length - 1
    );
  }
  if (pattern.endsWith("*")) {
    return target.startsWith(pattern.slice(0, -1));
  }
  return false;
}

function emptyUsage(): Record<Permission, number> {
  return { read: 0, write: 0, network: 0, storage: 0 };
}

export function createSandbox(grants: PluginGrant[]): Sandbox {
  const byPlugin = new Map<string, PluginGrant>();
  for (const grant of grants) byPlugin.set(grant.pluginId, grant);
  const states = new Map<string, PluginState>();

  function stateOf(pluginId: string): PluginState {
    let state = states.get(pluginId);
    if (!state) {
      state = { failures: 0, open: false, usage: emptyUsage() };
      states.set(pluginId, state);
    }
    return state;
  }

  function authorize(request: SandboxRequest): Decision {
    const grant = byPlugin.get(request.pluginId);
    if (!grant) return { allowed: false, reason: "plugin-unknown" };
    const state = stateOf(request.pluginId);
    if (state.open) return { allowed: false, reason: "circuit-open" };
    const permission = grant.permissions.find(
      (item) => item.permission === request.permission,
    );
    if (!permission) return { allowed: false, reason: "permission-not-granted" };
    const inScope = permission.scopes.some((scope) =>
      matchScope(scope, request.resource),
    );
    if (!inScope) return { allowed: false, reason: "resource-out-of-scope" };
    const units = request.units ?? 1;
    const used = state.usage[request.permission];
    if (units > permission.quota - used) {
      return { allowed: false, reason: "quota-exceeded" };
    }
    state.usage[request.permission] = used + units;
    return { allowed: true, remaining: permission.quota - used - units };
  }

  function runIsolated<T>(jobs: Array<Job<T>>): RunReport<T> {
    const results: Array<JobResult<T>> = [];
    const failed: string[] = [];
    for (const job of jobs) {
      try {
        results.push({ pluginId: job.pluginId, ok: true, value: job.run() });
      } catch (error) {
        const message = error instanceof Error ? error.message : String(error);
        results.push({ pluginId: job.pluginId, ok: false, error: message });
        failed.push(job.pluginId);
        const grant = byPlugin.get(job.pluginId);
        if (grant) {
          const state = stateOf(job.pluginId);
          state.failures += 1;
          if (state.failures >= grant.failureThreshold) state.open = true;
        }
      }
    }
    return { results, failed };
  }

  return {
    authorize,
    runIsolated,
    state: (pluginId: string) => states.get(pluginId),
  };
}

export type LeastPrivilegeReport = {
  unused: Permission[];
  overreach: SandboxRequest[];
};

export function auditLeastPrivilege(
  grant: PluginGrant,
  requests: SandboxRequest[],
): LeastPrivilegeReport {
  const used = new Set<Permission>();
  const overreach: SandboxRequest[] = [];
  for (const request of requests) {
    if (request.pluginId !== grant.pluginId) continue;
    const permission = grant.permissions.find(
      (item) => item.permission === request.permission,
    );
    const inScope =
      permission !== undefined &&
      permission.scopes.some((scope) => matchScope(scope, request.resource));
    if (!permission || !inScope) {
      overreach.push(request);
      continue;
    }
    used.add(request.permission);
  }
  const unused = grant.permissions
    .map((item) => item.permission)
    .filter((permission) => !used.has(permission));
  return { unused, overreach };
}