documentationUrl: https://spec.openlint.org/
rules:
  openapi-agentic-access-contract-declared:
    description: Every operation exposed to AI agents should declare an x-agentic-access execution contract so an agent knows
      what it may attempt, and what must be denied, constrained, or escalated.
    message: Operation has no x-agentic-access contract — an agent cannot know what it may attempt.
    severity: info
    given: $.paths[*][get,post,put,patch,delete,options,head,trace]
    then:
      field: x-agentic-access
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-agentic-access-contract-declared
  openapi-agentic-access-core-fields:
    description: An x-agentic-access contract must declare action-class, consequence, subject, and a non-empty scope so the
      runtime decision layer has the token and policy context it needs.
    message: x-agentic-access must declare action-class, consequence, subject, and a non-empty scope.
    severity: info
    given: $.paths[*][get,post,put,patch,delete,options,head,trace].x-agentic-access
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required:
          - action-class
          - consequence
          - subject
          - scope
          properties:
            action-class:
              enum:
              - connected
              - delegated
              - acting
            consequence:
              enum:
              - read
              - write
              - physical
              - safety-critical
            subject:
              enum:
              - required
              - optional
              - none
            scope:
              type: array
              minItems: 1
              items:
                type: string
            audience:
              type: string
            audit:
              enum:
              - required
              - none
            token:
              type: object
              properties:
                max-ttl:
                  type: integer
                  minimum: 1
                exchange:
                  type: boolean
                proof-of-possession:
                  type: boolean
                purpose-required:
                  type: boolean
            escalation:
              type: object
              properties:
                human-in-the-loop:
                  enum:
                  - required
                  - conditional
                  - none
                triggers:
                  type: array
                  items:
                    enum:
                    - abnormal
                    - high-value
                    - safety
                approver:
                  type: string
    documentationUrl: https://apicommons.org/rules/#openapi-agentic-access-core-fields
  openapi-agentic-access-consequence-requirements:
    description: Higher-consequence actions must bind an audience, require a subject, cap token lifetime, and be audited —
      just-enough privilege, just-in-time access, and an auditable production loop.
    message: Higher-consequence action must bind audience, require a subject, cap token TTL, and be audited.
    severity: info
    given: $.paths[*][get,post,put,patch,delete,options,head,trace].x-agentic-access
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          allOf:
          - if:
              properties:
                consequence:
                  const: write
            then:
              required:
              - audience
              - audit
              - token
              properties:
                audit:
                  const: required
                token:
                  required:
                  - max-ttl
                  properties:
                    max-ttl:
                      maximum: 900
          - if:
              properties:
                consequence:
                  const: physical
            then:
              required:
              - audience
              - audit
              - subject
              - token
              properties:
                subject:
                  const: required
                audit:
                  const: required
                token:
                  required:
                  - max-ttl
                  properties:
                    max-ttl:
                      maximum: 300
          - if:
              properties:
                consequence:
                  const: safety-critical
            then:
              required:
              - audience
              - audit
              - subject
              - token
              properties:
                subject:
                  const: required
                audit:
                  const: required
                token:
                  required:
                  - max-ttl
                  properties:
                    max-ttl:
                      maximum: 120
    documentationUrl: https://apicommons.org/rules/#openapi-agentic-access-consequence-requirements
  openapi-agentic-access-safety-critical-human:
    description: Safety-critical actions must require human-in-the-loop approval — step-up review for high-impact operations.
    message: Safety-critical action must set escalation.human-in-the-loop = required.
    severity: info
    given: $.paths[*][get,post,put,patch,delete,options,head,trace].x-agentic-access
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          if:
            properties:
              consequence:
                const: safety-critical
            required:
            - consequence
          then:
            required:
            - escalation
            properties:
              escalation:
                type: object
                required:
                - human-in-the-loop
                properties:
                  human-in-the-loop:
                    const: required
    documentationUrl: https://apicommons.org/rules/#openapi-agentic-access-safety-critical-human
  openapi-agentic-access-acting-escalation:
    description: Any acting operation should declare an escalation policy — even 'none' by explicit decision — so runtime
      approval behavior is never left implicit.
    message: Acting operation should declare escalation.human-in-the-loop (may be 'none' by decision).
    severity: info
    given: $.paths[*][get,post,put,patch,delete,options,head,trace].x-agentic-access
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          if:
            properties:
              action-class:
                const: acting
            required:
            - action-class
          then:
            required:
            - escalation
            properties:
              escalation:
                type: object
                required:
                - human-in-the-loop
    documentationUrl: https://apicommons.org/rules/#openapi-agentic-access-acting-escalation
  openapi-agentic-access-delegation-token-exchange:
    description: Actions that act on behalf of a subject should require token exchange so delegation is scoped per action
      rather than relying on a broad standing token.
    message: Action acts on behalf of a subject but does not require token.exchange = true.
    severity: info
    given: $.paths[*][get,post,put,patch,delete,options,head,trace].x-agentic-access
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          if:
            properties:
              subject:
                const: required
            required:
            - subject
          then:
            required:
            - token
            properties:
              token:
                type: object
                required:
                - exchange
                properties:
                  exchange:
                    const: true
    documentationUrl: https://apicommons.org/rules/#openapi-agentic-access-delegation-token-exchange
  openapi-agentic-access-oauth-protected:
    description: Delegated or acting operations must carry a security requirement so agent actions are actually authorized
      at runtime, not merely described.
    message: Delegated/acting operation for an agent declares no security requirement.
    severity: info
    given: $.paths[*][get,post,put,patch,delete,options,head,trace]
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          if:
            required:
            - x-agentic-access
            properties:
              x-agentic-access:
                required:
                - action-class
                properties:
                  action-class:
                    enum:
                    - acting
                    - delegated
          then:
            required:
            - security
            properties:
              security:
                type: array
                minItems: 1
    documentationUrl: https://apicommons.org/rules/#openapi-agentic-access-oauth-protected