Skip to content

ArchivePub

ArchivePub is the federation wire protocol behind Artist Alley, defined by the Artist Alley project. It is designed to let two independently-operated Digital Asset Management (DAM) instances share assets, posts, comments, reviews, brand kits, and workflow state directly, with no middle vendor.

Today Artist Alley implements the studio-to-studio connection. Pairing two instances opens a channel between them but exchanges nothing by itself: likes and comments about a post reach a peer only once the post has been explicitly shared with that peer. Sending assets and posts to a peer, review actions, and workflow events are planned; see What works today.

Where ActivityPub solves federated social messaging, ArchivePub is aimed at federated archival and creative collaboration. Studios reviewing each other’s work come first; the vocabulary also leaves room for museums sharing condition reports, brand teams distributing kits to partner agencies, and archives loaning collections without centralising authority. None of those workflows is built yet.

ArchivePub borrows the ActivityPub model (Actor / Activity / Object / Collection) and much of the ActivityStreams vocabulary that ActivityPub uses, so the mental model is familiar. It is not ActivityPub: Artist Alley does not interoperate with ActivityPub servers such as Mastodon, and a public-fediverse bridge would be separate future work. It departs from ActivityPub deliberately in three ways that matter for the DAM domain:

  • Plain JSON, versioned: no JSON-LD. The @context is a version marker, not a Linked Data context to resolve, and by design no JSON-LD context document is published for it. No context resolver, no LD-signature pitfalls.
  • Custom activity + object types from day one. Every peer is a DAM, so aa:Approve and aa:Asset are first-class: no degrading to Note / Image for compatibility.
  • Content-addressed URIs (planned). The design references asset bytes by cas://<sha256>, so identical bytes are stored once. Cross-instance asset transfer is not implemented yet.

Federation is walled-garden: peers are explicitly paired, not openly discoverable, and every shared object is a separate opt-in.

Standard activity types in the vocabulary: Create, Update, Delete, Follow, Accept, Reject, Undo, Like, Announce, Block.

DAM-shaped extension types (the aa: namespace):

TypePurpose
aa:Share / aa:UnshareGrant / revoke access to one object for a paired peer. The sending instance delivers activities about an object only to peers it has shared the object with.
aa:AssetExtends Document with technical metadata (color profile, EXIF, content hash, source DCC tool).
aa:Approve / aa:RequestChanges / aa:MarkReviewedFederated review actions.
aa:AnnotationA brush stroke / highlight / region comment anchored to an asset, video timecode, or PDF page.
aa:WorkflowTransitionFederated workflow state changes.
aa:AssetVersionVersion bumps without resending bytes.
aa:Subscribe / aa:MentionSubscribe to a collection/workspace output; cross-instance mentions.

Custom object types: aa:Asset, aa:Post, aa:Workspace, aa:BrandKit, aa:Collection.

These types are the wire vocabulary, not a list of working features. Today a receiving instance applies Like and comment Create activities; it accepts and records the other types without acting on them.

Every federation activity is a JSON envelope with an embedded signature block, delivered to the peer’s inbox in a request that carries the sending instance’s HTTP Signature. The pairing handshake that comes first is separate: it sends its own envelope, signed with the key the instance is offering, in a request without an HTTP Signature. That signature shows the envelope wasn’t altered, not that the key belongs to the claimed instance. The @context field carries the canonical protocol version string, nothing more:

{
"@context": "https://artist-alley.org/protocol/v1",
"type": "aa:Approve",
"id": "https://studio-a.example/activities/3f6c2a8e-9b1d-4e7a-8c5f-2d9e0b7a6c41",
"actor": "https://studio-a.example/users/alice",
"published": "2026-06-04T10:00:00Z",
"object": "https://studio-a.example/assets/b2e8d5f1-6a3c-4f09-9e27-71c4a0d3e85b",
"to": ["https://studio-b.example/users/bob"],
"cc": [],
"aa:comment": "Approved with minor lighting note.",
"aa:reviewedAt": "2026-06-04T10:00:00Z",
"signature": {
"type": "Ed25519",
"publicKey": "https://studio-a.example/users/alice#main-key",
"value": "ILLUSTRATIVE-PLACEHOLDER-not-a-computed-signature"
}
}

The example shows the envelope as the specification defines it. Its identifiers are illustrative and its signature value is a placeholder, not a computed signature, so it is not a cryptographically valid envelope. Artist Alley doesn’t act on a received aa:Approve yet, and the signature block it sends today is a placeholder, as the rules below explain.

Rules of the wire (per ADR 0043 and the specification), with what Artist Alley does today:

  • Instance authentication (enforced). Every inbox POST carries an HTTP Signature from the sending instance, and the receiver verifies it against the paired peer’s key before accepting the request.
  • Per-actor signature (not implemented yet). The specification requires an embedded Ed25519 signature by the sending actor over the envelope with the signature field omitted, canonicalised with RFC 8785 (JSON Canonicalization Scheme), and requires the receiver to verify it against the actor’s published key before processing the inner activity. Artist Alley does not do this yet: it sends a placeholder signature block, and the receiver checks only that the block is present and names Ed25519. Until it lands, activities are authenticated per instance, not per actor, and the embedded signature gives no relay, storage, or audit-replay guarantee.
  • Strict parsing (partly implemented). The specification requires unknown fields to be rejected, not silently ignored. Artist Alley’s parser rejects unknown fields inside the signature and encryption blocks, but currently keeps unknown top-level fields instead of rejecting them.
  • Delivery. Envelopes are POSTed to a recipient inbox (POST /federation/inbox), with a batched variant (POST /federation/inbox/batch) for queues with more than one pending activity per peer.

This is the load-bearing security property. Pairing a peer establishes a trusted channel, nothing more. It shares no posts, collections, workspaces, brand kits, or comments. After pairing, both instances simply know about each other and can authenticate each other’s signed requests.

Every shared object is an explicit, separate opt-in. To share an object with a paired peer (or a specific user on it), the object’s owner or an administrator grants a share, which emits an aa:Share activity with a scope (such as view, comment or annotate) and an optional expiry. The sending instance then delivers activities about that object only to the peers it has been shared with; today that delivery covers posts only. A grant does not send the object itself yet: the receiving instance records the aa:Share without acting on it, and sending assets and posts is planned. The specification also requires the receiving instance to reject activities about objects the sending peer holds no grant for; Artist Alley does not enforce that inbound check yet. The model is a private channel between two paired studios, not the open fediverse.

Trust tiers describe what the channel can carry: connected (the standard tier), directory-listed (opts into an optional discovery directory), and auto-sync (opt-in policy-driven auto-share within a single trust domain). Today the tier is a label: the pairing handshake sets connected, an administrator can set any of the three, and Artist Alley behaves the same whichever is set. Directory discovery works separately from the tier: an instance can subscribe to discovery directories, and can ask to be listed in one after proving its domain with a DNS record. Auto-sync policies are not implemented.

In the protocol design, every reference to asset bytes uses a content-addressed URI:

cas://<sha256>?content-type=image/png&size=12345

In that design the receiving peer checks local storage first (if the SHA-256 is already present, no transfer happens), and otherwise fetches the bytes from the origin with a signed request and caches them, so identical bytes are stored once per instance. Artist Alley does not transfer asset bytes between instances yet; this is planned work (#72).

Encryption tier is orthogonal to trust tier. Under the specification’s sender policy, an activity’s payload goes inside a NaCl-box encryption block, addressed to the recipient actor’s published key, whenever the sender can encrypt: the peer has negotiated encryption support and the recipient’s encryption key is available. Activities about restricted- and embargo-tier content are sent only that way; if the sender can’t encrypt for a recipient, it sends nothing to that recipient rather than falling back to plaintext. Activities about public- and team-tier content are sent as plaintext in that case.

Artist Alley applies the encrypt-when-possible rule to everything it sends. Today it sends only activities about posts, and treats them as public-tier, so the refusal for restricted and embargoed content is not reached yet. On the receiving side, it rejects a plaintext activity about a local asset whose tier requires encryption. One current limit: the receiver decrypts with the sender’s currently known key, so an envelope sealed with an older sender key doesn’t decrypt. See ADR 0049 for the encrypted-federation design and dogfood validation.

  • Implemented: peer pairing; HTTP-signed inbox requests, verified on receipt; share grants, which decide which peers receive activities about a post; likes and comments applied on the receiving instance; payload encryption when the peer and recipient support it; single and batched inbox delivery; subscribing to discovery directories and asking to be listed in one.
  • In the vocabulary, not acted on yet: the receiving instance accepts and records review actions (aa:Approve, aa:RequestChanges, aa:MarkReviewed), annotations, workflow transitions, asset versions, subscriptions, mentions, aa:Share / aa:Unshare, and the other standard types, without applying them.
  • Not implemented yet: per-actor envelope signing and verification; rejection of unknown top-level fields; the inbound share-grant check; sending shared assets and posts, including content-addressed asset transfer between instances; looking up the tier of outgoing activities, so the refusal for restricted and embargoed content isn’t in effect; auto-sync policies; decrypting envelopes sealed with an older sender key.
  • Not supported: interoperability with ActivityPub servers such as Mastodon. No implementation other than Artist Alley has demonstrated ArchivePub interoperability.

The specification’s Implementation status section describes the signature, parsing, share-grant, CAS and encryption-key gaps in more detail.