Skip to main content

Publish an adapter

You need an owner or admin account in your organisation on Adapter Studio, and either the zaitrack command (the quick path below) or openssl and jq (the manual path, steps 1 to 5).

One set of files, two ways to send them

The zaitrack adapter command and Adapter Studio use the same files and the same registry: adapter.json (the manifest), manifest.canonical.json (the bytes that are signed) and signature.b64 (ECDSA P-256 over their SHA-256). Make them with the command and send them with zaitrack adapter submit or paste them into the studio; or make them by hand as below. The older --legacy-ed25519 signature (signature.json) is for adapters ZAITRACK builds inside its own monorepo and is not accepted.

Quick path: the zaitrack command​

zaitrack adapter scaffold connector --name acme-fleet-export --display-name "Acme fleet export" \
--licence MIT --publisher acme --out ./work # ./work/acme-fleet-export/manifest.yaml and the skeleton
zaitrack adapter test ./work/acme-fleet-export # conformance pack: golden vectors, fuzz, scenarios
zaitrack adapter pack ./work/acme-fleet-export # adapter.json and manifest.canonical.json
zaitrack adapter keygen --out ./keys # key.pem (private, 0600), key.pub.pem, the fingerprint
zaitrack adapter sign ./work/acme-fleet-export --key ./keys/key.pem # signature.b64
zaitrack adapter verify ./work/acme-fleet-export --public-key ./keys/key.pub.pem
zaitrack adapter submit ./work/acme-fleet-export --registry https://<registry> \
--token ZAITRACK_REGISTRY_TOKEN --key ./keys/key.pem --create-project
  • The directory name is the project's slug and the manifest's id (3 to 64 characters, lowercase letters, digits and hyphens). The licence, summary and description belong to the project, not the manifest: they come from manifest.yaml when --create-project creates it (--visibility public|tenant-only, default tenant-only).
  • pack refuses what the registry would refuse, with the field named: slug, version, display name, availability, family, config keys and types, notices, a codec's device classes. A codec's built module goes in with --module, which pins its SHA-256 in the manifest.
  • ZAITRACK_REGISTRY_TOKEN is the name of the environment variable holding an owner's or admin's Bearer token; the token is never a flag and is never printed. --registry is the registry's address behind the gateway, as your ZAITRACK contact gives it; the command calls its /adapters/v1 routes over https.
  • submit registers key.pub.pem first when the registry does not know its fingerprint, then submits the version with the artifact's address, SHA-256 and size when you give --artifact-url, --artifact-sha256, --artifact-size (or --module). The version waits as pending-review; steps 6 and 7 follow.
  • The studio alternative: Signing keys → Register a key with key.pub.pem, then Projects → your project → Submit a version with the content of adapter.json and signature.b64. A codec's module is uploaded there too.

1. Make a signing key​

ZAITRACK accepts one algorithm: ECDSA on the P-256 curve over SHA-256, the signature in ASN.1 DER, base64.

openssl ecparam -name prime256v1 -genkey -noout -out key.pem
openssl ec -in key.pem -pubout -out key.pub.pem

Keep key.pem secret: anyone holding it can sign versions as you. In Adapter Studio, Signing keys → Register a key, give it a name (2 to 80 characters) and paste key.pub.pem. The studio shows the key's fingerprint, SHA256: and the base64 SHA-256 of the DER public key.

2. Create the project​

Projects → New project: a slug (lowercase letters, digits and hyphens), the family (codec, connector, datasource, action or ai), a display name, a summary and description, an SPDX licence (LicenseRef-… for your own) and the visibility: public (any organisation can see and install its approved versions) or tenant-only (your organisation only).

3. Write the manifest​

adapter.json says who the adapter is, what it can do, the permissions it asks for and the settings an installation must give:

{
"id": "acme-fleet-export",
"family": "connector",
"version": "1.0.0",
"displayName": "Acme fleet export",
"capabilities": ["export"],
"permissions": ["trips:read"],
"config": [
{"key": "sftpHost", "type": "url", "required": true, "label": "SFTP host"},
{"key": "password", "type": "secret", "required": true, "label": "Password"}
]
}
  • id: 3 to 64 characters, lowercase letters, digits and hyphens, starting with a letter and not ending with a hyphen. The version must be new for the project.
  • version: semantic versioning (1.0.0, 1.1.0-rc.1).
  • displayName: at least 3 characters.
  • config[].key: a letter, then letters, digits or _ (48 at most), each key once.
  • config[].type: text, number, url, secret or port. A secret setting is never shown back once given.

4. Sign the canonical manifest​

The registry signs and checks the canonical manifest: keys sorted, no insignificant whitespace, no trailing newline. Make it with jq, then sign it:

jq -cSj . adapter.json > manifest.canonical.json
openssl dgst -sha256 -sign key.pem manifest.canonical.json | base64 -w0 > signature.b64

Keep the characters &, < and > out of the manifest's strings: the registry writes them as \u0026, \u003c and \u003e and jq does not, so the signature would not match. On macOS, use base64 without -w0 (it does not wrap).

5. Submit the version​

Projects → your project → Submit a version: paste adapter.json, the content of signature.b64 and choose the key. Optionally give the artifact's address (https:// or oci://). The registry makes the manifest canonical, hashes it with SHA-256 and checks the signature against your key. A wrong signature or a revoked key is refused. The version waits as pending-review.

6. Review​

ZAITRACK staff run the conformance suite and record its result: coverage and how many checks passed and failed. A version is approved only with a run of at least 85 % coverage and no failures; staff approve with a note, or reject with a reason.

7. Installations​

Organisations install an approved version and fill in the settings your manifest declares. They can upgrade to another approved version, change settings, suspend, resume and uninstall. You see one installation per organisation, with its version and status.

An active installation is a registry state, not proof of a connected device or a prepared runtime. Before deployment, follow Codec readiness; keep approval, installation and device evidence separate.

Revoking a key​

Signing keys → Revoke, with a reason. In one step it revokes every version that key signed and suspends their installations; the key goes on the revocation list with when and why. An installation resumes once it is upgraded to a version that is not revoked: sign the next version with a new key.