$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://cfse.ai/schemas/grammar.schema.yaml"
title: "CFSE Grammar Schema"
description: "Reusable type definitions for CFSE artifact validation"

$defs:
  # ============================================================================
  # IDENTIFIER TYPES
  # ============================================================================

  ConceptID:
    title: "Concept Identifier"
    description: "Identifier for a security concept artifact"
    type: string
    pattern: "^C-[A-Z0-9]{2,8}-[A-Z0-9-]{1,32}$"
    examples:
      - "C-AWS-IAM-ROLE"
      - "C-K8S-POD"
      - "C-OAUTH2-ACCESS-TOKEN"

  InteractionID:
    title: "Interaction Identifier"
    description: "Identifier for an interaction artifact"
    type: string
    pattern: "^I-[A-Z0-9]{2,8}-[A-Z]{1,16}-[A-Z]{1,16}-[0-9]{3}$"
    examples:
      - "I-AWS-ASSUME-ROLE-001"
      - "I-K8S-CREATE-POD-042"
      - "I-OAUTH2-REFRESH-TOKEN-003"

  FlowID:
    title: "Flow Identifier"
    description: "Identifier for a flow artifact"
    type: string
    pattern: "^F-[A-Z0-9]{2,8}-[A-Z0-9-]{1,32}$"
    examples:
      - "F-AWS-CROSS-ACCOUNT-ACCESS"
      - "F-K8S-POD-SCHEDULING"
      - "F-OAUTH2-AUTHORIZATION-CODE"

  ScenarioID:
    title: "Scenario Identifier"
    description: "Identifier for a scenario artifact"
    type: string
    pattern: "^S-[A-Z0-9]{2,8}-[A-Z0-9-]{1,24}-[0-9]{3}$"
    examples:
      - "S-AWS-PRIVILEGE-ESCALATION-001"
      - "S-K8S-CONTAINER-ESCAPE-003"
      - "S-OAUTH2-TOKEN-THEFT-010"

  ExplorationID:
    title: "Exploration Identifier"
    description: "Identifier for an exploration artifact"
    type: string
    pattern: "^E-[A-Z0-9]{2,8}-[A-Z0-9-]{1,24}-[0-9]{3}-[0-9]{2}$"
    examples:
      - "E-AWS-PRIVILEGE-ESCALATION-001-01"
      - "E-K8S-CONTAINER-ESCAPE-003-05"
      - "E-OAUTH2-TOKEN-THEFT-010-12"

  TraceID:
    title: "Trace Identifier"
    description: "Identifier for a trace artifact"
    type: string
    pattern: "^T-[A-Z0-9]{2,8}-[A-Z0-9-]{1,24}-[0-9]{3}-[0-9]{2}-[0-9]{2}$"
    examples:
      - "T-AWS-PRIVILEGE-ESCALATION-001-01-01"
      - "T-K8S-CONTAINER-ESCAPE-003-05-02"
      - "T-OAUTH2-TOKEN-THEFT-010-12-01"

  FindingID:
    title: "Finding Identifier"
    description: "Identifier for a finding artifact"
    type: string
    pattern: "^FD-[A-Z0-9]{2,8}-[A-Z]{1,16}-[0-9]{3}$"
    examples:
      - "FD-AWS-AUTHZ-001"
      - "FD-K8S-CONFIG-023"
      - "FD-OAUTH2-CRYPTO-005"

  PredicateID:
    title: "Predicate Identifier"
    description: "Identifier for a predicate artifact"
    type: string
    pattern: "^P-[A-Z0-9]{2,8}-[A-Z0-9-]{1,32}$"
    examples:
      - "P-AWS-HAS-MFA"
      - "P-K8S-IS-PRIVILEGED"
      - "P-OAUTH2-TOKEN-VALID"

  InvariantID:
    title: "Invariant Identifier"
    description: "Identifier for an invariant artifact"
    type: string
    pattern: "^INV-[A-Z0-9]{2,8}-[A-Z0-9-]{1,32}$"
    examples:
      - "INV-AWS-NO-PUBLIC-S3"
      - "INV-K8S-POD-SECURITY"
      - "INV-OAUTH2-TOKEN-EXPIRY"

  EntryPointID:
    title: "Entry Point Identifier"
    description: "Identifier for an entry point artifact (EP-*)"
    type: string
    pattern: "^EP-[A-Z0-9-]{1,128}$"
    examples:
      - "EP-SHOP-USER-API-CREATE"
      - "EP-SHOP-ITEM-API-DELETE"
      - "EP-GL-FEED-API-READ"

  ProjectionID:
    title: "Projection Identifier"
    description: "Identifier for a projection artifact"
    type: string
    pattern: "^PRJ-[A-Z0-9-]{1,128}$"
    examples:
      - "PRJ-SHOP-PUBLIC-VIEWER"
      - "PRJ-GL-ANON-RSS"

  GeneratorID:
    title: "Generator Identifier"
    description: "Identifier for a generator artifact"
    type: string
    pattern: "^GEN-[A-Z0-9-]{1,24}-[0-9]{3}$"
    examples:
      - "GEN-BOUNDARY-001"
      - "GEN-MUTATION-FUZZ-042"
      - "GEN-PRIVILEGE-ESCALATION-003"

  PatchID:
    title: "Patch Identifier"
    description: "Identifier for a patch artifact"
    type: string
    pattern: "^PATCH-[A-Z0-9]{2,8}-[0-9]{3}$"
    examples:
      - "PATCH-AWS-001"
      - "PATCH-K8S-042"
      - "PATCH-OAUTH2-003"

  ArtifactID:
    title: "Any Artifact Identifier"
    description: "Union type for any valid artifact identifier"
    oneOf:
      - $ref: "#/$defs/ConceptID"
      - $ref: "#/$defs/InteractionID"
      - $ref: "#/$defs/FlowID"
      - $ref: "#/$defs/ScenarioID"
      - $ref: "#/$defs/ExplorationID"
      - $ref: "#/$defs/TraceID"
      - $ref: "#/$defs/FindingID"
      - $ref: "#/$defs/PredicateID"
      - $ref: "#/$defs/InvariantID"
      - $ref: "#/$defs/EntryPointID"
      - $ref: "#/$defs/ProjectionID"
      - $ref: "#/$defs/GeneratorID"
      - $ref: "#/$defs/PatchID"

  # ============================================================================
  # ENUMERATION TYPES
  # ============================================================================

  Criticality:
    title: "Criticality Level"
    description: "Priority level for security artifacts"
    type: string
    enum:
      - P0
      - P1
      - P2
      - P3
    x-enum-descriptions:
      P0: "Critical - Immediate action required (< 24 hours)"
      P1: "High - Urgent attention needed (< 1 week)"
      P2: "Medium - Plan remediation (< 1 month)"
      P3: "Low - Address when convenient"

  Verdict:
    title: "Test Verdict"
    description: "Outcome of exploration or test execution"
    type: string
    enum:
      - PASS
      - FAIL
      - INCONCLUSIVE
      - BLOCKED
      - SKIPPED
    x-enum-descriptions:
      PASS: "Test passed, no security issues found"
      FAIL: "Test failed, security issue confirmed"
      INCONCLUSIVE: "Unable to determine outcome"
      BLOCKED: "Test could not be executed"
      SKIPPED: "Test intentionally skipped"

  InvariantState:
    title: "Invariant State"
    description: "Current state of an invariant"
    type: string
    enum:
      - HOLDS
      - VIOLATED
      - UNKNOWN
      - NOT_APPLICABLE
    x-enum-descriptions:
      HOLDS: "Invariant is satisfied"
      VIOLATED: "Invariant is not satisfied"
      UNKNOWN: "State cannot be determined"
      NOT_APPLICABLE: "Invariant does not apply in context"

  ArtifactStatus:
    title: "Artifact Status"
    description: "Lifecycle status of an artifact"
    type: string
    enum:
      - DRAFT
      - REVIEW
      - PLANNED
      - ACTIVE
      - DEPRECATED
      - ARCHIVED
    x-enum-descriptions:
      DRAFT: "Initial creation, not reviewed"
      REVIEW: "Under review"
      PLANNED: "Approved future state (not yet current reality)"
      ACTIVE: "Approved and in use"
      DEPRECATED: "Being phased out"
      ARCHIVED: "No longer in use"

  Extensions:
    title: "Extensions"
    description: "Extension-specific fields, keyed by extension name"
    type: object
    additionalProperties: true

  # ============================================================================
  # TANGIBLE LOCATIONS
  # ============================================================================

  TangibleLocationKind:
    title: "Tangible Location Kind"
    description: "How a surface is concretely accessed/observed by a tester"
    type: string
    enum:
      - web_url
      - api_url
      - graphql
      - cli
      - email
      - file
      - event
    x-enum-descriptions:
      web_url: "Browser-fetchable URL (often no auth headers)"
      api_url: "API URL (often requires auth headers/tokens)"
      graphql: "GraphQL operation surface"
      cli: "Concrete CLI invocation"
      email: "Email-rendering surface"
      file: "File path or template path"
      event: "Event name surface (e.g., queue/topic name)"

  TangibleLocation:
    title: "Tangible Location"
    description: |
      A concrete access locator for an entry point or surface, intended for scoping,
      test planning, and audit checklists. This is declarative metadata (no logic).
    type: object
    required:
      - kind
    properties:
      kind:
        $ref: "#/$defs/TangibleLocationKind"
      web_url_template:
        type: string
        description: "Templated fully-qualified URL (use placeholders like {host})"
      example_urls:
        type: array
        items:
          type: string
        minItems: 1
        description: "Concrete URLs a tester can paste into a browser/curl"
      notes:
        type: string
        description: "Short scoping notes (auth preconditions, flags, settings, etc.)"
    additionalProperties: false

  Severity:
    title: "Finding Severity"
    description: "Severity level for findings"
    type: string
    enum:
      - CRITICAL
      - HIGH
      - MEDIUM
      - LOW
      - INFO
    x-enum-descriptions:
      CRITICAL: "CVSS 9.0-10.0 - Immediate exploitation risk"
      HIGH: "CVSS 7.0-8.9 - Significant security impact"
      MEDIUM: "CVSS 4.0-6.9 - Moderate security impact"
      LOW: "CVSS 0.1-3.9 - Minor security impact"
      INFO: "CVSS 0.0 - Informational only"

  FindingCategory:
    title: "Finding Category"
    description: "Category classification for findings"
    type: string
    enum:
      - AUTHZ
      - AUTHN
      - CRYPTO
      - CONFIG
      - INJECT
      - LEAK
      - LOGIC
      - RACE
      - SSRF
      - IDOR
    x-enum-descriptions:
      AUTHZ: "Authorization and access control"
      AUTHN: "Authentication"
      CRYPTO: "Cryptographic issues"
      CONFIG: "Configuration vulnerabilities"
      INJECT: "Injection vulnerabilities"
      LEAK: "Information disclosure"
      LOGIC: "Business logic flaws"
      RACE: "Race conditions"
      SSRF: "Server-side request forgery"
      IDOR: "Insecure direct object reference"

  ConceptType:
    title: "Concept Type"
    description: "Type classification for concepts"
    type: string
    enum:
      - IDENTITY
      - RESOURCE
      - POLICY
      - CREDENTIAL
      - TOKEN
      - KEY
      - CONFIGURATION
    x-enum-descriptions:
      IDENTITY: "Principal or identity entity"
      RESOURCE: "Protected resource"
      POLICY: "Policy or permission document"
      CREDENTIAL: "Authentication credential"
      TOKEN: "Session or access token"
      KEY: "Cryptographic key"
      CONFIGURATION: "System configuration"

  ActionType:
    title: "Action Type"
    description: "Type classification for actions"
    type: string
    enum:
      - CREATE
      - READ
      - UPDATE
      - DELETE
      - ACCESS
      - EXECUTE
      - ASSUME
      - GRANT
      - REVOKE
    x-enum-descriptions:
      CREATE: "Create new resource"
      READ: "Read resource data"
      UPDATE: "Modify existing resource"
      DELETE: "Remove resource"
      ACCESS: "Generic access"
      EXECUTE: "Execute code or command"
      ASSUME: "Assume identity"
      GRANT: "Grant permission"
      REVOKE: "Revoke permission"

  ConstraintType:
    title: "Constraint Type"
    description: "Type of validation constraint"
    type: string
    enum:
      - pattern
      - range
      - enum
      - length
      - custom

  EvidenceType:
    title: "Evidence Type"
    description: "Type of supporting evidence"
    type: string
    enum:
      - log
      - screenshot
      - request
      - response
      - code
      - configuration

  ParameterType:
    title: "Parameter Data Type"
    description: "Data type for parameters"
    type: string
    enum:
      - string
      - integer
      - boolean
      - array
      - object

  # ============================================================================
  # COMPOSITE TYPES
  # ============================================================================

  InvariantRef:
    title: "Invariant Reference"
    description: "Reference to an invariant with optional state tracking"
    type: object
    required:
      - id
    properties:
      id:
        $ref: "#/$defs/InvariantID"
      state:
        $ref: "#/$defs/InvariantState"
      notes:
        type: string
        description: "Additional context about the invariant state"
    additionalProperties: false

  Parameter:
    title: "Parameter Definition"
    description: "Typed parameter for interactions or generators"
    type: object
    required:
      - name
      - type
    properties:
      name:
        type: string
        pattern: "^[a-z][a-z0-9_]*$"
        description: "Parameter name in snake_case"
      type:
        $ref: "#/$defs/ParameterType"
      required:
        type: boolean
        default: true
        description: "Whether the parameter is required"
      default:
        description: "Default value for the parameter"
      description:
        type: string
        description: "Human-readable parameter description"
      constraints:
        type: array
        items:
          $ref: "#/$defs/Constraint"
        description: "Validation constraints for the parameter"
    additionalProperties: false

  Constraint:
    title: "Validation Constraint"
    description: "Constraint for parameter validation"
    type: object
    required:
      - type
    properties:
      type:
        $ref: "#/$defs/ConstraintType"
      value:
        description: "Constraint value (interpretation depends on type)"
      min:
        type: number
        description: "Minimum value for range constraints"
      max:
        type: number
        description: "Maximum value for range constraints"
      message:
        type: string
        description: "Custom error message for constraint violation"
    additionalProperties: false

  EntryPoint:
    title: "Entry Point Definition"
    description: "Entry point for scenario or exploration"
    type: object
    required:
      - interaction
    properties:
      interaction:
        $ref: "#/$defs/InteractionID"
      parameters:
        type: array
        items:
          $ref: "#/$defs/Parameter"
        description: "Input parameters for the entry point"
      preconditions:
        type: array
        items:
          type: string
        description: "Required preconditions for entry"
    additionalProperties: false

  FlowStep:
    title: "Flow Step Definition"
    description: "A step within a flow"
    type: object
    required:
      - order
      - interaction
    properties:
      order:
        type: integer
        minimum: 1
        description: "Step sequence number"
      interaction:
        $ref: "#/$defs/InteractionID"
      description:
        type: string
        description: "Human-readable step description"
      conditional:
        type: string
        description: "Condition expression for step execution"
      on_success:
        type: integer
        description: "Next step order on success"
      on_failure:
        type: integer
        description: "Next step order on failure"
    additionalProperties: false

  Evidence:
    title: "Evidence"
    description: "Supporting evidence for a finding"
    type: object
    required:
      - type
      - description
    properties:
      type:
        $ref: "#/$defs/EvidenceType"
      description:
        type: string
        description: "Description of the evidence"
      data:
        type: string
        description: "Evidence content (may be encoded)"
      url:
        type: string
        format: uri
        description: "Reference URL for the evidence"
    additionalProperties: false

  Finding:
    title: "Finding Document"
    description: "Complete finding document structure"
    type: object
    required:
      - id
      - title
      - severity
      - category
      - exploration
      - description
      - impact
      - remediation
    properties:
      id:
        $ref: "#/$defs/FindingID"
      title:
        type: string
        maxLength: 100
        description: "Brief finding title"
      severity:
        $ref: "#/$defs/Severity"
      category:
        $ref: "#/$defs/FindingCategory"
      exploration:
        $ref: "#/$defs/ExplorationID"
      invariant:
        $ref: "#/$defs/InvariantID"
      description:
        type: string
        description: "Detailed finding description"
      impact:
        type: string
        description: "Security impact assessment"
      remediation:
        type: string
        description: "Recommended remediation steps"
      evidence:
        type: array
        items:
          $ref: "#/$defs/Evidence"
        description: "Supporting evidence"
      status:
        $ref: "#/$defs/ArtifactStatus"
    additionalProperties: false

  # ============================================================================
  # REFERENCE COLLECTIONS
  # ============================================================================

  ConceptList:
    title: "Concept Reference List"
    description: "List of concept references"
    type: array
    items:
      $ref: "#/$defs/ConceptID"
    uniqueItems: true

  InteractionList:
    title: "Interaction Reference List"
    description: "List of interaction references"
    type: array
    items:
      $ref: "#/$defs/InteractionID"
    uniqueItems: true

  FlowList:
    title: "Flow Reference List"
    description: "List of flow references"
    type: array
    items:
      $ref: "#/$defs/FlowID"
    uniqueItems: true

  ScenarioList:
    title: "Scenario Reference List"
    description: "List of scenario references"
    type: array
    items:
      $ref: "#/$defs/ScenarioID"
    uniqueItems: true

  ExplorationList:
    title: "Exploration Reference List"
    description: "List of exploration references"
    type: array
    items:
      $ref: "#/$defs/ExplorationID"
    uniqueItems: true

  FindingList:
    title: "Finding Reference List"
    description: "List of finding references"
    type: array
    items:
      $ref: "#/$defs/FindingID"
    uniqueItems: true

  PredicateList:
    title: "Predicate Reference List"
    description: "List of predicate references"
    type: array
    items:
      $ref: "#/$defs/PredicateID"
    uniqueItems: true

  InvariantList:
    title: "Invariant Reference List"
    description: "List of invariant references (simple IDs or with state)"
    type: array
    items:
      oneOf:
        - $ref: "#/$defs/InvariantID"
        - $ref: "#/$defs/InvariantRef"
    uniqueItems: true

  GeneratorList:
    title: "Generator Reference List"
    description: "List of generator references"
    type: array
    items:
      $ref: "#/$defs/GeneratorID"
    uniqueItems: true

  PatchList:
    title: "Patch Reference List"
    description: "List of patch references"
    type: array
    items:
      $ref: "#/$defs/PatchID"
    uniqueItems: true

  FlowStepList:
    title: "Flow Step List"
    description: "Ordered list of flow steps"
    type: array
    items:
      $ref: "#/$defs/FlowStep"
    minItems: 1

  ParameterList:
    title: "Parameter List"
    description: "List of parameter definitions"
    type: array
    items:
      $ref: "#/$defs/Parameter"

  EvidenceList:
    title: "Evidence List"
    description: "List of evidence items"
    type: array
    items:
      $ref: "#/$defs/Evidence"

# Root schema (used for validation testing)
type: object
properties:
  $schema:
    type: string
  test_concept_id:
    $ref: "#/$defs/ConceptID"
  test_interaction_id:
    $ref: "#/$defs/InteractionID"
  test_flow_id:
    $ref: "#/$defs/FlowID"
  test_scenario_id:
    $ref: "#/$defs/ScenarioID"
  test_exploration_id:
    $ref: "#/$defs/ExplorationID"
  test_finding_id:
    $ref: "#/$defs/FindingID"
  test_predicate_id:
    $ref: "#/$defs/PredicateID"
  test_invariant_id:
    $ref: "#/$defs/InvariantID"
  test_generator_id:
    $ref: "#/$defs/GeneratorID"
  test_patch_id:
    $ref: "#/$defs/PatchID"
  test_criticality:
    $ref: "#/$defs/Criticality"
  test_verdict:
    $ref: "#/$defs/Verdict"
  test_invariant_state:
    $ref: "#/$defs/InvariantState"
  test_artifact_status:
    $ref: "#/$defs/ArtifactStatus"
  test_severity:
    $ref: "#/$defs/Severity"
  test_finding_category:
    $ref: "#/$defs/FindingCategory"
  test_invariant_ref:
    $ref: "#/$defs/InvariantRef"
  test_parameter:
    $ref: "#/$defs/Parameter"
  test_entry_point:
    $ref: "#/$defs/EntryPoint"
  test_flow_step:
    $ref: "#/$defs/FlowStep"
  test_evidence:
    $ref: "#/$defs/Evidence"
  test_finding:
    $ref: "#/$defs/Finding"
  test_concept_list:
    $ref: "#/$defs/ConceptList"
  test_interaction_list:
    $ref: "#/$defs/InteractionList"
  test_invariant_list:
    $ref: "#/$defs/InvariantList"
  test_flow_step_list:
    $ref: "#/$defs/FlowStepList"
additionalProperties: true