본문으로 건너뛰기

Policy 스펙 스키마

이 페이지는 Fascia의 Policy(정책) 스펙에 대한 전체 JSON Schema를 정의합니다. Policy는 안전하지 않은 연산을 방지하기 위해 설계 시(런타임이 아닌) 적용되는 규칙입니다. Policy는 Tool을 배포하기 전에 Risk Engine에 의해 평가됩니다.

JSON Schema​

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["name", "version", "description", "type", "condition", "action"],
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-zA-Z0-9]*$",
      "description": "camelCase policy name (e.g., maxRowLimit, budgetCheck)"
    },
    "version": {
      "type": "integer",
      "minimum": 1
    },
    "description": {
      "type": "string"
    },
    "type": {
      "enum": ["rowLimit", "budgetCheck", "rateLimit", "custom"],
      "description": "Policy category"
    },
    "condition": {
      "type": "string",
      "description": "Value DSL boolean expression. Policy triggers when this is TRUE."
    },
    "action": {
      "enum": ["block", "warn", "escalate"],
      "description": "What happens when the condition is met"
    },
    "message": {
      "type": "string",
      "description": "Human-readable message shown when policy triggers"
    },
    "parameters": {
      "type": "object",
      "description": "Type-specific parameters",
      "properties": {
        "maxRows": { "type": "integer", "description": "For rowLimit type" },
        "maxAmount": { "type": "number", "description": "For budgetCheck type" },
        "maxRequestsPerMinute": { "type": "integer", "description": "For rateLimit type" }
      }
    }
  }
}

최상위 속성​

속성타입필수설명
namestring예camelCase Policy 이름입니다 (예: maxRowLimit, budgetCheck). ^[a-z][a-zA-Z0-9]*$ 패턴을 따라야 합니다.
versioninteger예불변 버전 번호. 1부터 시작합니다.
descriptionstring예Policy의 목적에 대한 사람이 읽을 수 있는 설명입니다.
typeenum예Policy 유형: rowLimit, budgetCheck, rateLimit, custom 중 하나입니다.
conditionstring예Value DSL 불리언 표현식입니다. 이 표현식이 true로 평가되면 Policy가 발동합니다.
actionenum예조건이 충족되었을 때의 대응: block, warn, escalate 중 하나입니다.
messagestring아니오Policy가 발동될 때 사용자에게 표시되는 사람이 읽을 수 있는 메시지입니다.
parametersobject아니오구체적인 임계값을 제공하는 유형별 파라미터입니다.

액션​

액션동작
block작업의 진행을 차단합니다. 조건이 해결될 때까지 Tool을 배포하거나 실행할 수 없습니다.
warn사용자에게 message 텍스트와 함께 경고를 표시합니다. 사용자가 경고를 명시적으로 확인하면 작업을 진행할 수 있습니다. 확인 내역은 감사 로그에 기록됩니다.
escalate관리자의 수동 검토를 위해 이슈를 플래그합니다. 승인이 허가될 때까지 작업이 일시 중지됩니다.

Policy 유형​

rowLimit​

단일 작업이 영향을 미칠 수 있는 행 수를 제한합니다. 의도치 않은 대량 업데이트나 삭제를 방지합니다.

파라미터:

파라미터타입설명
maxRowsinteger단일 작업이 영향을 미칠 수 있는 최대 행 수입니다.

예시:

{
  "name": "maxRowLimit",
  "version": 1,
  "description": "Prevent operations affecting more than 100 rows",
  "type": "rowLimit",
  "condition": "affectedRowCount > 100",
  "action": "block",
  "message": "This operation would affect more than 100 rows. Please add a filter.",
  "parameters": {
    "maxRows": 100
  }
}

이 Policy는 단일 실행에서 100개 이상의 행을 수정하는 쓰기 작업을 차단합니다. Tool 설계자는 작업을 진행하기 위해 WHERE 필터를 추가하거나 배치 처리해야 합니다.

budgetCheck​

외부 서비스 호출에 대한 지출 한도를 적용합니다. 결제 처리, 이메일 발송, 서드파티 API 사용의 비용을 제어하는 데 유용합니다.

파라미터:

파라미터타입설명
maxAmountnumber예산 기간 내 허용되는 최대 금액입니다.

예시:

{
  "name": "monthlyBudgetCheck",
  "version": 1,
  "description": "Warn when monthly spend exceeds budget",
  "type": "budgetCheck",
  "condition": "workspace.monthlySpend > workspace.budgetLimit",
  "action": "warn",
  "message": "Monthly budget exceeded. Current spend: {workspace.monthlySpend}",
  "parameters": {
    "maxAmount": 1000
  }
}

이 Policy는 워크스페이스의 월간 누적 지출이 설정된 예산 한도를 초과할 때 경고를 발행합니다. 작업을 진행하기 전에 워크스페이스 소유자가 경고를 확인해야 합니다.

rateLimit​

사용자, 이메일, IP 주소별 요청 빈도를 제한합니다. 인증 엔드포인트에 대한 무차별 대입 공격을 방지하는 데 일반적으로 사용됩니다.

파라미터:

파라미터타입설명
maxRequestsPerMinuteinteger1분 내 허용되는 최대 요청 수입니다.

예시:

{
  "name": "loginRateLimit",
  "version": 1,
  "description": "Rate limit login attempts",
  "type": "rateLimit",
  "condition": "requestCount(user.email, '1m') > 5",
  "action": "block",
  "message": "Too many login attempts. Please wait and try again.",
  "parameters": {
    "maxRequestsPerMinute": 5
  }
}

이 Policy는 특정 이메일 주소에서 1분 내 5회를 초과하는 로그인 시도를 차단합니다. 사용자는 제한 시간이 만료될 때까지 기다린 후 재시도해야 합니다.

custom​

미리 정의된 유형에 해당하지 않는 Policy를 위한 범용 유형입니다. Custom Policy는 임의의 Value DSL 조건을 사용하여 모든 비즈니스 규칙을 적용할 수 있습니다.

예시:

{
  "name": "requireConfirmationForHighValue",
  "version": 1,
  "description": "Escalate operations involving amounts over $10,000",
  "type": "custom",
  "condition": "input.amount > 10000",
  "action": "escalate",
  "message": "Operations over $10,000 require administrator approval."
}

Tool에서 Policy 참조​

Policy는 Tool 스펙의 policies 배열에서 이름으로 참조됩니다. Tool이 호출되면, 트랜잭션이 시작되기 전 Execution Contract의 3단계에서 참조된 모든 Policy가 평가됩니다.

{
  "name": "createReservation",
  "policies": ["maxRowLimit", "monthlyBudgetCheck"],
  "...": "..."
}

action: "block"인 Policy가 발동되면 실행이 즉시 중단되고 에러가 반환됩니다. action: "warn"인 Policy는 진행하기 전에 확인이 필요합니다.

설계 시 vs 런타임​

Fascia의 Policy는 주로 설계 시에 작동합니다. Risk Engine은 스펙 검증 및 배포 과정에서 Policy를 평가합니다:

  • 설계 시 적용: Tool 스펙이 생성되거나 업데이트될 때, Risk Engine은 Flow 패턴이 참조된 모든 Policy를 준수하는지 확인합니다. block Policy를 구조적으로 위반하는 Tool은 배포할 수 없습니다.
  • 런타임 평가: 일부 Policy (예: rateLimit, budgetCheck)는 실행 시점에만 평가할 수 있는 동적 데이터를 포함합니다. 이러한 Policy는 Execution Contract의 3단계에서 검사됩니다.

이러한 구분을 통해 구조적으로 안전하지 않은 Tool은 실행되기 전에 감지되며, 동적 임계값은 호출 시점에 적용됩니다.

관련 문서​