{
  "openapi": "3.0.0",
  "info": {
    "title": "MailLock API",
    "description": "Programmatic Email Deliverability, RFC 7208 / RFC 7489 Compliance, and External Attack Surface Remediation Engine. Real-time validation of SPF 10-lookup depth, DMARC quarantine/reject enforcement, 2048-bit DKIM keys, and dangling CNAME subdomain takeovers.",
    "version": "1.0.0",
    "contact": {
      "name": "MailLock Venture Team",
      "url": "https://maillock.agentlabs.workers.dev"
    }
  },
  "servers": [
    {
      "url": "https://maillock.agentlabs.workers.dev",
      "description": "Production Cloudflare Edge Server"
    },
    {
      "url": "http://localhost:3002",
      "description": "Local Development Server"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Enter your Pro ($29) or Agency API Key. For testing and evaluation, use key 'maillock_eval_2026'."
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Bearer token authentication for enterprise subscribers."
      }
    }
  },
  "paths": {
    "/health": {
      "get": {
        "summary": "Service Health Check",
        "description": "Returns operational status and active engine components.",
        "tags": [
          "Tier 1: Free Diagnostic Suite"
        ],
        "responses": {
          "200": {
            "description": "Service is healthy and ready for queries",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ONLINE"
                    },
                    "service": {
                      "type": "string",
                      "example": "MailLock API"
                    },
                    "version": {
                      "type": "string",
                      "example": "1.0.0"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/audit": {
      "get": {
        "summary": "Full Deliverability & Attack Surface Audit (GET)",
        "description": "Runs parallel audits across SPF (recursive depth), DMARC, DKIM, dangling DNS, MTA-STS, and MX routing, returning a 0-100 Deliverability Index and diagnostic breakdown.",
        "tags": [
          "Tier 1: Free Diagnostic Suite"
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "stripe.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Complete Deliverability and Security Audit Dossier"
          }
        }
      },
      "post": {
        "summary": "Full Deliverability & Attack Surface Audit (POST)",
        "description": "JSON payload interface for batch scanning and CI/CD pipelines.",
        "tags": [
          "Tier 1: Free Diagnostic Suite"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domain": {
                    "type": "string",
                    "example": "stripe.com"
                  }
                },
                "required": [
                  "domain"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Complete Deliverability and Security Audit Dossier"
          }
        }
      }
    },
    "/v1/audit/spf": {
      "get": {
        "summary": "SPF Recursive 10-Lookup Depth & RFC 7208 Analyzer",
        "description": "Traverses nested SPF includes, computes exact DNS lookup depth against the RFC 7208 10-lookup limit, void lookups, and flags mechanism risks (+all, ?all, ptr).",
        "tags": [
          "Tier 1: Free Diagnostic Suite"
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "stripe.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SPF Diagnostic Breakdown"
          }
        }
      }
    },
    "/v1/audit/dmarc": {
      "get": {
        "summary": "DMARC 2.0 & RFC 7489 Alignment Auditor",
        "description": "Evaluates policy enforcement (p=reject/quarantine/none), identifier alignment (aspf, adkim), and RFC 7489 Section 7.1 external report authorization.",
        "tags": [
          "Tier 1: Free Diagnostic Suite"
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "stripe.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "DMARC Diagnostic Breakdown"
          }
        }
      }
    },
    "/v1/audit/dkim": {
      "get": {
        "summary": "DKIM Multi-Selector Cryptanalysis",
        "description": "Probes 15+ industry selectors and parses public keys to evaluate RSA modulus bit-length (1024-bit weak vs 2048-bit compliant).",
        "tags": [
          "Tier 1: Free Diagnostic Suite"
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "stripe.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "DKIM Diagnostic Breakdown"
          }
        }
      }
    },
    "/v1/audit/dangling-dns": {
      "get": {
        "summary": "Subdomain Takeover & External Attack Surface Sentry",
        "description": "Probes subdomains against 18 known cloud service fingerprints (AWS S3, GitHub Pages, Zendesk, Heroku, Shopify) to detect orphaned CNAME takeovers.",
        "tags": [
          "Tier 1: Free Diagnostic Suite"
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "stripe.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dangling DNS Security Findings"
          }
        }
      }
    },
    "/v1/audit/transport": {
      "get": {
        "summary": "Transport Security & BIMI Brand Avatar Auditor",
        "description": "Validates MTA-STS (RFC 8461) enforcement mode, TLS-RPT (RFC 8460) reporting, and BIMI brand avatar indicators for Gmail and Apple Mail.",
        "tags": [
          "Tier 2: Pro Remediation Utilities"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "stripe.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transport Security Breakdown"
          },
          "401": {
            "description": "API Key Required — Pro or Agency subscription required"
          }
        }
      }
    },
    "/v1/audit/mx": {
      "get": {
        "summary": "MX Routing & Mail Provider Fingerprinting",
        "description": "Validates mail exchanger priorities, hostname IP resolution, and detects mail providers (Google Workspace, Microsoft 365, ProtonMail, Proofpoint).",
        "tags": [
          "Tier 2: Pro Remediation Utilities"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "stripe.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "MX Routing Breakdown"
          },
          "401": {
            "description": "API Key Required — Pro or Agency subscription required"
          }
        }
      }
    },
    "/v1/generate/spf-flatten": {
      "get": {
        "summary": "Automated SPF Flattener & CIDR Optimizer",
        "description": "Resolves all nested SPF includes into deduplicated IPv4 and IPv6 CIDRs, reducing DNS lookups from >10 down to 1.",
        "tags": [
          "Tier 2: Pro Remediation Utilities"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "stripe.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Flattened SPF Configuration"
          },
          "401": {
            "description": "API Key Required — Pro or Agency subscription required"
          }
        }
      }
    },
    "/v1/generate/dns-fixes": {
      "get": {
        "summary": "1-Click Multi-Registrar DNS Fix Kit",
        "description": "Generates copy-paste DNS record tables tailored for Cloudflare, GoDaddy, Namecheap, AWS Route 53, and RFC-standard BIND zone files.",
        "tags": [
          "Tier 2: Pro Remediation Utilities"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "stripe.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Registrar-specific DNS tables"
          },
          "401": {
            "description": "API Key Required — Pro or Agency subscription required"
          }
        }
      }
    },
    "/v1/agency/score-card": {
      "get": {
        "summary": "Agency Scorecard & Embeddable Badge API",
        "description": "Returns a compact JSON deliverability scorecard with embeddable SVG badge, estimated inbox placement rate, and primary action item.",
        "tags": [
          "Tier 3: Agency & Enterprise Suite"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "stripe.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Agency Scorecard JSON"
          },
          "401": {
            "description": "API Key Required — Agency subscription required"
          }
        }
      }
    },
    "/v1/agency/executive-report": {
      "get": {
        "summary": "White-Label Print-Ready Executive Audit Dossier (HTML)",
        "description": "Returns a branded, print-ready HTML deliverability audit certificate for clients and executive stakeholders with verification hash.",
        "tags": [
          "Tier 3: Agency & Enterprise Suite"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "stripe.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTML Document"
          },
          "401": {
            "description": "API Key Required — Agency subscription required"
          }
        }
      }
    }
  }
}