App Package Token

Overview

The APKG (App Package) token publishes an app package: a signed token carrying the app’s metadata plus the package itself as an attachment. It is the unit of app distribution on Cloudillo — a publisher signs one APKG per release, and other instances retrieve it to install or update the app.

Unlike most action types, APKG is not pushed to recipients. It is marked local_only, so it is stored on the publishing instance and never enters the delivery fan-out or the federated history sync; peers fetch it through the app store instead. Like every action token it is content-addressed — see Content Addressing.

Token Structure

Field	Type	Required	Description
`iss`	identity	Yes	The publishing identity
`iat`	timestamp	Yes	Issue time
`k`	string	Yes	Signing key ID
`t`	string	Yes	Type with optional subtype: `APKG`, `APKG:DEL`
`c`	object	Yes	App package metadata (see below)
`a`	array	Yes	Attachments — the package payload

aud (audience), p (parent) and sub (subject) are forbidden on this type: an APKG is published, not addressed.

Subtypes

Type String	Description
`APKG`	Publish an app package
`APKG:DEL`	Unpublish a previously published package

Content Schema

Field	Type	Required	Max length	Description
`name`	string	Yes	100	App name — also the identity of the app across releases
`version`	string	Yes	50	Release version
`description`	string	No	1000	What the app does
`changelog`	string	No	5000	What changed in this release
`minPlatformVersion`	string	No	50	Minimum Cloudillo version required
`tags`	string[]	No	50 per item	Categorisation tags
`capabilities`	string[]	No	50 per item	Capabilities the app requests

Permissions

Rule	Value
Who may create	Authenticated users
Who may receive	Any identity
Requires connection	No
Requires following	No
Unknown senders	Accepted
Approvable	Yes

Database Key

The database key pattern is {type}:{content.name} — keyed on the app name rather than the issuer, so publishing a new version supersedes the previous release of the same app instead of accumulating one entry per version — see Database Keys.

Processing

APKG has no native hooks — no on_create, on_receive, on_accept or on_reject. It is stored and served like any other local action; see Action Lifecycle.

Example

Publisher @apps.cloudillo.net releases version 1.2.0 of an app:

Field	Value
iss	apps.cloudillo.net
iat	2024-04-13T00:01:10.000Z
k	20240101
t	APKG
c.name	quillo
c.version	1.2.0
c.description	Collaborative document editor
c.changelog	Added table support.
c.minPlatformVersion	0.9.0
c.tags	[“editor”, “collaboration”]
c.capabilities	[“crdt”, “files”]
a	[package attachment]