{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://heartcortex.ai/schemas/1.0/grant.schema.json",
  "title": "grant",
  "description": "Who may call the system (API Standard 8.2 and 13.2 rule 21; module access). A grant gives one principal a role, and each role is a fixed set of scopes and a clearance. With certificate, the grant is also the principal's row in the mutual-TLS table. PUT /heart/v1/access/grants/{principal} sends role, and may send callerKind, certificate, expiresAt, reason, actionId and presence; scopes and clearance follow from the role.",
  "type": "object",
  "required": [
    "role"
  ],
  "properties": {
    "principal": {
      "description": "Who the grant is for: the sub of their tokens, or the principal a certificate names.",
      "type": "string",
      "pattern": "^[A-Za-z0-9._:@+=~-]{1,256}$",
      "readOnly": true,
      "x-heart-privacy": "private"
    },
    "role": {
      "description": "owner: every scope but heart.propose, clearance private. installer: heart.read, heart.tend, heart.invoke, heart.configure, heart.operate; internal. maintainer: heart.read, heart.tend, heart.invoke, heart.operate; internal. operator: heart.read, heart.ask, heart.subscribe, heart.tend, heart.invoke, heart.approve; internal. viewer: heart.read, heart.ask; internal.",
      "enum": [
        "owner",
        "installer",
        "maintainer",
        "operator",
        "viewer"
      ],
      "x-heart-privacy": "public"
    },
    "scopes": {
      "description": "The scopes the role gives. A caller holds those its credential grants and the role allows.",
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^heart\\.[a-z]+$"
      },
      "readOnly": true,
      "x-heart-privacy": "internal"
    },
    "clearance": {
      "description": "The highest level the role may see.",
      "$ref": "common.schema.json#/$defs/messageLevel",
      "readOnly": true,
      "x-heart-privacy": "internal"
    },
    "callerKind": {
      "description": "The caller kind a certificate of this grant counts as. Default human. An owner is always human, and an ai grant never holds heart.approve.",
      "enum": [
        "human",
        "peer",
        "ai"
      ],
      "default": "human",
      "x-heart-privacy": "internal"
    },
    "certificate": {
      "description": "The client certificate this principal calls with: the URI in its subjectAltName. Missing: tokens only.",
      "type": "object",
      "required": [
        "sanUri"
      ],
      "additionalProperties": false,
      "properties": {
        "sanUri": {
          "type": "string",
          "minLength": 3,
          "maxLength": 512
        }
      },
      "x-heart-privacy": "private"
    },
    "expiresAt": {
      "description": "After this time the grant gives nothing. Missing: until removed.",
      "$ref": "common.schema.json#/$defs/timestamp",
      "x-heart-privacy": "internal"
    },
    "grantedBy": {
      "description": "The person whose request made or last changed it.",
      "type": [
        "string",
        "null"
      ],
      "readOnly": true,
      "x-heart-privacy": "private"
    },
    "createdAt": {
      "$ref": "common.schema.json#/$defs/timestamp",
      "readOnly": true,
      "x-heart-privacy": "internal"
    },
    "updatedAt": {
      "$ref": "common.schema.json#/$defs/timestamp",
      "readOnly": true,
      "x-heart-privacy": "internal"
    },
    "reason": {
      "type": "string",
      "maxLength": 2000,
      "writeOnly": true
    },
    "actionId": {
      "$ref": "common.schema.json#/$defs/actionId",
      "writeOnly": true
    },
    "presence": {
      "$ref": "common.schema.json#/$defs/presence",
      "writeOnly": true
    },
    "ext": {
      "$ref": "common.schema.json#/$defs/ext",
      "x-heart-privacy": "private"
    }
  }
}