space.highport.manage.setCertificateMode

{
  "type": "procedure",
  "input": {
    "schema": {
      "type": "object",
      "required": [
        "domain",
        "mode"
      ],
      "properties": {
        "mode": {
          "type": "string",
          "description": "per-name: one certificate per name, ending any wildcard grant. wildcard: grant this service a wildcard certificate for the base. A new grant after an earlier one ended gets a new challenge target.",
          "knownValues": [
            "per-name",
            "wildcard"
          ]
        },
        "domain": {
          "type": "string",
          "maxLength": 253,
          "description": "The base: a domain registered to the caller."
        },
        "acknowledgeCertificateGrant": {
          "type": "boolean",
          "description": "Must be true for wildcard. While the base's _acme-challenge record points at the challenge target, this service can get a publicly trusted certificate for the base and every name in its zone. Removing that record ends the grant."
        }
      }
    },
    "encoding": "application/json"
  },
  "errors": [
    {
      "name": "InvalidDomain",
      "description": "Not a syntactically valid domain."
    },
    {
      "name": "NotBaseOwner",
      "description": "No verified or active registration of that domain belongs to the caller."
    },
    {
      "name": "CertificateGrantNotAcknowledged",
      "description": "mode is wildcard and acknowledgeCertificateGrant is not true."
    },
    {
      "name": "WildcardNotOffered",
      "description": "No wildcard certificate is offered for this domain: it is a name delegated under another base, it is under a base offered to anyone without DNS proof, or the deployment has no challenge zone. The error message says which."
    },
    {
      "name": "CaaForbidsIssuance",
      "description": "The base's CAA records block this mode. For wildcard, issuewild (or issue, if there is no issuewild) must allow this deployment's issuer, account and DNS-01. For either mode, issue records must not limit this issuer to DNS-01, because the probe and per-name certificates cannot use it. The error message names the blocking record."
    },
    {
      "name": "RateLimitExceeded",
      "description": "A new wildcard grant was requested during the deployment's cooldown after the base's last grant or ending, or while its previous wildcard is still being retired. Ending a grant is never limited."
    }
  ],
  "output": {
    "schema": {
      "type": "object",
      "required": [
        "domain",
        "mode",
        "records",
        "verified"
      ],
      "properties": {
        "mode": {
          "type": "string",
          "knownValues": [
            "per-name",
            "wildcard"
          ]
        },
        "domain": {
          "type": "string"
        },
        "records": {
          "type": "array",
          "items": {
            "ref": "space.highport.defs#dnsInstruction",
            "type": "ref"
          },
          "description": "For wildcard, one record: the base's _acme-challenge CNAME pointing at its challenge target, with purpose certificate. Empty for per-name."
        },
        "verified": {
          "type": "boolean",
          "description": "Whether the record this mode needs is in place. For wildcard, false until the base's _acme-challenge record is found pointing at its challenge target. Always true for per-name, which needs no record."
        }
      }
    },
    "encoding": "application/json"
  },
  "description": "Choose how names under a proven base get certificates. wildcard lets this service get one wildcard certificate for the base over DNS-01, through the base's own challenge target, and returns the record that delegates it. per-name ends that grant. The caller must own the base, which must be verified or active. Delegation does not need to be enabled."
}