mesh-contracts/seats/mesh-enrolment/seat.json

{
  "format": 1,
  "seat": "mesh-enrolment",
  "scope": "mesh",
  "grain": "seat-list",
  "decision": "novox/hq ADR 0587",
  "verbs": [
    {
      "name": "issue",
      "description": "Issue a one-time token for a new machine, on the operator's Approve: refused at once, naming every finding, for a name that is not a node name or that a node record, a placement key or an open enrolment holds, and for every call before the controller's lease is handed away. Otherwise reserves the lowest free private-network address, asks the operator under the seat's own name and, on the warrant, adds the node to placement with its tunnel key, asks the vault for the token and says enrolment-issued. The token itself is read only through tokens.",
      "input": {
        "properties": {
          "expires": {
            "description": "how long the token lasts, a duration such as 1h or 24h: one hour when not given, at most 24 hours",
            "type": "string"
          },
          "node": {
            "description": "the new machine's name in the mesh",
            "type": "string"
          },
          "overlay_key": {
            "description": "the new machine's private network (tunnel) public key, as `nox-mesh-host key` prints it",
            "type": "string"
          },
          "why": {
            "description": "why it joins, shown to the operator with the ask",
            "type": "string"
          }
        },
        "required": [
          "node",
          "why",
          "overlay_key"
        ],
        "type": "object"
      }
    },
    {
      "name": "redeem",
      "description": "Spend a token: asked by a joining node-engine dialled as enrol.\u003cnode\u003e alone, with the public halves of its keys and its identity key's proof over them. Spends the token, asks the vault for the node's account and certificate, writes the node into placement, and answers the account sealed to the node, its certificate and the vault's public half, signed by the vault. Asked again with the same keys it finishes what is not done and answers the same; with other keys it is refused.",
      "input": {
        "additionalProperties": false,
        "properties": {
          "node": {
            "description": "the node the token was issued for",
            "type": "string"
          },
          "overlay_key": {
            "description": "the private network key's public half",
            "type": "string"
          },
          "profile": {
            "description": "what the machine is, as its record says it",
            "type": "object"
          },
          "proof": {
            "description": "the identity key's signature over the redeem's proof bytes (delivery.RedeemProof), base64",
            "type": "string"
          },
          "public_key": {
            "description": "the identity key's public half, base64",
            "type": "string"
          },
          "sealing_key": {
            "description": "the sealing key's public half, which the account is sealed to",
            "type": "string"
          },
          "serving_key": {
            "description": "the serving key's public half, which the certificate binds",
            "type": "string"
          },
          "tunnel": {
            "description": "a tunnel found on the machine: everything but its private key",
            "type": "object"
          }
        },
        "required": [
          "node",
          "public_key",
          "sealing_key",
          "proof"
        ],
        "type": "object"
      }
    },
    {
      "name": "confirm",
      "description": "Confirm an enrolment: asked by the node-engine dialled as its own node login alone, the runtime's proof of that caller being the confirmation. Says node-enrolled and ends the enrolment.",
      "input": {
        "properties": {},
        "type": "object"
      }
    },
    {
      "name": "revoke",
      "description": "End an enrolment at any stage, with why, without an Approve: withdraws an open ask, deletes the node's key and its address, has the vault retire an account it already minted for it, records the act as a hand act and says enrolment-revoked.",
      "input": {
        "properties": {
          "node": {
            "description": "the node",
            "type": "string"
          },
          "why": {
            "description": "why, recorded with the hand act",
            "type": "string"
          }
        },
        "required": [
          "node",
          "why"
        ],
        "type": "object"
      }
    },
    {
      "name": "tokens",
      "description": "Read every open enrolment, or one: its stage, expiry, ask and revision, the bucket's fill against its cap. For a node at live, its token sealed to the operator key, asked of the vault at that moment and relayed as the vault sealed it. With history, the ended enrolments from the seat's events, as far back as the events are kept.",
      "input": {
        "properties": {
          "history": {
            "description": "\"true\": the ended enrolments too",
            "enum": [
              "true",
              "false"
            ],
            "type": "string"
          },
          "node": {
            "description": "one node",
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    {
      "name": "again",
      "description": "Raise an issue's ask again when the operator's channel does not hold it, and nothing more.",
      "input": {
        "properties": {
          "node": {
            "description": "the node whose ask is raised again",
            "type": "string"
          }
        },
        "required": [
          "node"
        ],
        "type": "object"
      }
    }
  ],
  "events": [
    {
      "name": "enrolment-issued"
    },
    {
      "name": "node-enrolled"
    },
    {
      "name": "enrolment-refused"
    },
    {
      "name": "enrolment-revoked"
    },
    {
      "name": "enrolment-expired"
    }
  ]
}