The registry API

How larva hive talks to a registry - the files a registry serves, the HTTP routes of www.antril.org/hive-api, publishing with a token, and the status codes.

A Hive registry is, first of all, files: for each package an index, Author/Name/index.json, and the package files beside it. larva hive reads them from a folder or over HTTPS. A registry on the web adds one request to publish. The public registry's root is https://www.antril.org/hive-api/.

A registry made of files

registry/
  Ana/
    Greetings/
      index.json
      1.0/Greetings-1.0.hive
      1.1/Greetings-1.1.hive
      2.0/Greetings-2.0.hive

larva hive publish to a folder writes exactly this (see Publishing packages). Any static web server that serves the folder over HTTPS is a registry too: larva hive only needs GET for installing. To publish to such a registry, publish to the folder, then upload it.

index.json

json

{
  "package": "Ana/Greetings",
  "keys": {
    "a59d969b683ba7f96e9fece9d1bcf78180354d077be31daeb5b9f2ebdc7ddb2d": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEt2nz5PDcKGyCEddkuAPfBauYEJVK4G3bfrFHnPyxn3r4UkfuUNsWCkhPMgBcQ3LBxGvu5O297PxsXhRrYvQ1UQ=="
  },
  "versions": [
    {
      "version": "1.0",
      "file": "1.0/Greetings-1.0.hive",
      "sha256": "2c3213cf4a1f227af46ee55d81acf9f9e455b444360d1ebd4cf99f86b5f7748b",
      "key": "a59d969b683ba7f96e9fece9d1bcf78180354d077be31daeb5b9f2ebdc7ddb2d",
      "dependencies": [],
      "yanked": false
    }
  ]
}

Field	Meaning
`package`	`Author/Name`. It must be the package asked for, or `larva hive` refuses the index.
`keys`	The public keys that sign the package: fingerprint (SHA-256 of the key, hex) to the key (base64 SubjectPublicKeyInfo).
`versions`	Every published version, oldest first.
`version`	The version, written canonically (`1.0`, `3.5.0`).
`file`	The package file, relative to the package's folder. It must be a plain relative path.
`sha256`	The SHA-256 of the package file, hex.
`key`	The fingerprint of the key that signed it; absent when it is unsigned.
`dependencies`	The packages it needs: `{ "package": "Ana/Greetings", "version": "^1.0" }` (an empty `version`: any).
`yanked`	`true`: withdrawn; Hive chooses it only when `hive.lock` already pins it.

The index is not signed: each package file is. What the index can change is checked when installing: the file must match sha256, its manifest must name the same package and version, its signature must be the key the index gives, and that key must be one the user trusts for the package (see What installing checks).

The HTTP API

Root: /hive-api/. Names in addresses are matched regardless of case.

Request	Answers
`GET /hive-api/`	`200` `{ "registry": "Hive", "index": "{Author}/{Name}/index.json" }`
`GET /hive-api/{Author}/{Name}/index.json`	`200` the index; `404` unknown package
`GET /hive-api/{Author}/{Name}/{version}/{file}`	`200` the package file; `404` unknown version or file
`PUT /hive-api/{Author}/{Name}/{version}`	`201` published; errors below. Needs a token.

Read an index

GET /hive-api/Ana/Greetings/index.json

200 OK
Content-Type: application/json
Cache-Control: no-cache

{ "package": "Ana/Greetings", "keys": { ... }, "versions": [ ... ] }

An unknown package answers 404 with the text no package Ana/Nothing. larva hive then tries the next registry.

Download a package file

GET /hive-api/Ana/Greetings/1.0/Greetings-1.0.hive

200 OK
Content-Type: application/octet-stream
Cache-Control: public, max-age=31536000, immutable
ETag: "2c3213cf4a1f227af46ee55d81acf9f9e455b444360d1ebd4cf99f86b5f7748b"

The address is the index's file under the package's folder. A published file never changes, so it may be cached for good; its entity tag is its SHA-256. A version that is not written canonically, or a file that is not the version's, answers 404.

Publish a version

larva hive publish sends:

PUT /hive-api/Ana/Greetings/1.0
Authorization: Bearer hive_...
Hive-Sha256: 2c3213cf4a1f227af46ee55d81acf9f9e455b444360d1ebd4cf99f86b5f7748b
Hive-Public-Key: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
Content-Length: 2976

<the .hive file>

Header	Required	Meaning
`Authorization`	yes	`Bearer` and an API token (`hive_...`), from `HIVE_TOKEN`.
`Hive-Sha256`	yes	The SHA-256 of the body, 64 hex digits.
`Hive-Public-Key`	for a signed package	The public key that signed it: base64 SubjectPublicKeyInfo, as `larva hive` sends it, or PEM.

On success:

201 Created
Content-Type: application/json

{
  "package": "Ana/Greetings",
  "version": "1.0",
  "file": "1.0/Greetings-1.0.hive",
  "sha256": "2c3213cf4a1f227af46ee55d81acf9f9e455b444360d1ebd4cf99f86b5f7748b",
  "key": "a59d969b683ba7f96e9fece9d1bcf78180354d077be31daeb5b9f2ebdc7ddb2d"
}

Who may publish

The token must be valid: known, not revoked, not expired. The author (the first part of the name) must exist and be owned by the token's user. You get your own author when you sign up and can claim others on your account page: see Accounts, tokens and authors. A package's first publish creates it under that author.

The registry applies the same signing rules as larva hive does for a folder:

a version is published once, and never replaced;
a package's first version brings its key; later versions must be signed by a key the package already has;
once a package is signed, an unsigned version is refused.

Errors

An error's body is plain text, and the same message is the HTTP/1.1 reason phrase, so larva hive publish shows it:

larva hive: https://www.antril.org/hive-api/Ana/Greetings/1.0: 403 you cannot publish as `Ana`

Status	When
`400`	The name in the address is not a package name; the version is not one, or not written canonically (`1.0`, not `v1.0` nor `01.0`); the body is empty; the author or package is written with other capitals than the registry's (the author is written `Ana` ); `Hive-Sha256` is missing, is not 64 hex digits, or does not match the body; `Hive-Public-Key` is not a public key.
`401`	No token, or one that is unknown, revoked or expired. The answer has no body and `WWW-Authenticate: Bearer realm="hive"`; `larva hive publish` shows `401 Unauthorized`.
`403`	The author does not exist (claim it first); you do not own it; the signing rules refuse the version (another key than the package's, or an unsigned version of a signed package).
`409`	The version is already published.
`413`	The package is larger than the registry accepts (128 MB on www.antril.org).
`422`	The package itself: not a valid Hive package, a file that does not match its hash, a signature that is not the given key's, a signed package sent without `Hive-Public-Key` (or the other way round), or a manifest whose package or version is not the one in the address.

Messages as the registry writes them:

Status	Message
`400`	`not a package name: Author/Name uses letters, digits, '-', '_' and '.'`
`400`	`v1.0` is not a version (write it as 1.2.3)
`400`	`the request has no package`
`400`	`the Hive-Sha256 header must be the package's SHA-256 (64 hex digits)`
`400`	`the package does not match its Hive-Sha256: it was damaged on the way`
`400`	`the Hive-Public-Key header is not a public key`
`403`	the author `Ana` does not exist: claim it on your account page first
`403`	you cannot publish as `Ana`
`403`	`Ana/Greetings is signed with other keys (a59d969b683ba7f9): sign it with one of them`
`403`	Ana/Greetings is signed: an unsigned version cannot be added (set `sign` in HIVE)
`409`	`Ana/Greetings 1.0 is already published: publish a new version`
`413`	`a package may be at most 134217728 bytes`
`422`	`the package is Ana/Other, not Ana/Greetings`
`422`	`the package is version 1.1, not 1.0`
`422`	`the package is signed: send its public key in Hive-Public-Key`

Running your own

Any folder or static HTTPS server works as a read-only registry, as above. The www.antril.org site, with accounts and publishing, can also run on your machine for testing; point larva at it with plain http, which is accepted only for localhost:

Terminal

$ larva config hive.provider http://localhost:5080/hive-api
hive.provider: http://localhost:5080/hive-api

or, for one project, provider: http://localhost:5080/hive-api in its HIVE chunk.