Sign in
InOrbit

← All schemas

Schema · approvals/runner-enrollment

draft

Runner enrollment

What a person approves to enrol a runner's run key: the key itself, the label the runner gave it and the key's fingerprint, so the phone shows the same fingerprint the terminal printed. It travels as the payload of an approval of kind runner_enrollment; the approval pins the SHA-256 of its canonical JSON (keys sorted, no whitespace), and the person's device-key signature over that approval is the enrolment proof. The runner then proves it holds the key and is enrolled once. Strings only, so the canonical JSON is the same in every language. Closed object.

https://schemas.inorbit.hr/approvals/runner-enrollment/v0.json
01Versions

Each version is a file at its own address and has a page of its own. The raw file is plain JSON, served without a sign-in.

What changed

One version so far. When a second is published, this is where it is compared with v0, field by field.

02Fields

Fields of v0, the newest version, by path. A name ending in [] is each item of a list. Every field not listed is refused.

  • public_keystringrequired

    The run key: a P-256 public key as its 65-byte uncompressed point (0x04, X, Y), base64url without padding.

    pattern ^B[A-Za-z0-9_-]{86}$

  • labelstringrequired

    The name the runner gave this key, for example: runner on build host. One line, no control, bidirectional, zero-width, blank, combining-joiner, variation-selector or private-use characters; the service also refuses any character that is not a letter, a digit or printable ASCII.

    pattern ^[^\u0000-\u001f\u007f-\u009f\u00ad\u061c\u180e\u200b-\u200f\u2028-\u202e\u2060-\u206f\ufeff\u00a0\u034f\u115f\u1160\u1680\u17b4\u17b5\u2000-\u200a\u2800\u3000\u3164\ue000-\uf8ff\ufe00-\ufe0f\uffa0\ufff0-\uffff]+$at least 1 charactersat most 100 characters

  • fingerprintstringrequired

    SHA-256 of the 65-byte point, lower-case hex. Apps show its first 24 characters in groups of four, the same the runner prints.

    pattern ^[0-9a-f]{64}$

03Examples

Documents with made-up values, the same ones our tests check against the schema: the ones it accepts and the ones it must refuse.

1 valid documentshow
{
  "public_key": "BNPx7_nAKwNo0cXeKOhW5OWUcpoxIaNINbzkPIZpo880U-2FrrUIkBv3Zr_izrA7Ksek8pUsGV0JDAqos9gyrKU",
  "label": "runner on build host",
  "fingerprint": "e7fda60e9a0b4ff223c257694d8cf1a050684200341d44fbee26dac041bd0774"
}
8 documents the schema must refuseshow

Each file name says what is wrong with it. Paste one into the check below to see the schema refuse it.

{
  "public_key": "BNPx7_nAKwNo0cXeKOhW5OWUcpoxIaNINbzkPIZpo880U-2FrrUIkBv3Zr_izrA7Ksek8pUsGV0JDAqos9gyr",
  "label": "runner on build host",
  "fingerprint": "e7fda60e9a0b4ff223c257694d8cf1a050684200341d44fbee26dac041bd0774"
}
04Check a file against it

Paste a document to check it against v0 here, or use the address in your editor or CI.

Checked in your browser. The document is not sent anywhere.
VS Code, JetBrains: settings
"json.schemas": [
  { "fileMatch": ["my-file.json"], "url": "https://schemas.inorbit.hr/approvals/runner-enrollment/v0.json" }
]
check-jsonschema
check-jsonschema --schemafile https://schemas.inorbit.hr/approvals/runner-enrollment/v0.json my-file.json
ajv-cli
ajv validate --spec=draft2020 -s <(curl -s https://schemas.inorbit.hr/approvals/runner-enrollment/v0.json) -d my-file.json
curl
curl -s https://schemas.inorbit.hr/approvals/runner-enrollment/v0.json
05The schema itself

The raw file of v0, as published.

schemas.inorbit.hr/approvals/runner-enrollment/v0.json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://schemas.inorbit.hr/approvals/runner-enrollment/v0.json",
  "title": "Runner enrollment",
  "description": "What a person approves to enrol a runner's run key: the key itself, the label the runner gave it and the key's fingerprint, so the phone shows the same fingerprint the terminal printed. It travels as the payload of an approval of kind runner_enrollment; the approval pins the SHA-256 of its canonical JSON (keys sorted, no whitespace), and the person's device-key signature over that approval is the enrolment proof. The runner then proves it holds the key and is enrolled once. Strings only, so the canonical JSON is the same in every language. Closed object. Draft line: it may still be corrected.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "public_key",
    "label",
    "fingerprint"
  ],
  "properties": {
    "public_key": {
      "description": "The run key: a P-256 public key as its 65-byte uncompressed point (0x04, X, Y), base64url without padding.",
      "type": "string",
      "pattern": "^B[A-Za-z0-9_-]{86}$"
    },
    "label": {
      "description": "The name the runner gave this key, for example: runner on build host. One line, no control, bidirectional, zero-width, blank, combining-joiner, variation-selector or private-use characters; the service also refuses any character that is not a letter, a digit or printable ASCII.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f\\u00ad\\u061c\\u180e\\u200b-\\u200f\\u2028-\\u202e\\u2060-\\u206f\\ufeff\\u00a0\\u034f\\u115f\\u1160\\u1680\\u17b4\\u17b5\\u2000-\\u200a\\u2800\\u3000\\u3164\\ue000-\\uf8ff\\ufe00-\\ufe0f\\uffa0\\ufff0-\\uffff]+$"
    },
    "fingerprint": {
      "description": "SHA-256 of the 65-byte point, lower-case hex. Apps show its first 24 characters in groups of four, the same the runner prints.",
      "type": "string",
      "pattern": "^[0-9a-f]{64}$"
    }
  }
}