Decentralized ActivityPub Draft

This document serves as an overview covering a stack of proposals in order to enable portability of identity and object storage within ActivityPub through the use of DIDs and a proposed custom DID method.

The proposed custom DID method, did:fedi is intended to be a self-certifying portable identity that provides the features of:

offer configurability of the base encoding used, allow truncation of DID identifier length for brevity, while still specifying a single canonical representation for a resulting DID
enable key rotation, unlike plain key-based identifiers
allows discovery of associated services, such as media storage and ActivityPub object storage, making use of features from the DID Resolution specification with DID URL dereferencing, but in a reduced profile that's much easier to implement
allows push-based notification of DID updates in-band of ActivityPub, versus inventing an ad-hoc push notification protocol for pushing out notifications of DID updates

This is currently just a set of proposed experimental ideas and is open and subject to change as required. Implementation of the custom DID method is not required and just serves as an opportunity to craft and adjust a custom DID method for use within ActivityPub, if necessary.

did:fedi Specification

The method currently only defines 3 record types: create, update, revoke. These record types and their respective serialization schema is scoped under what 'variant' is used (currently only fedi:0), thus allowing breaking changes to be experimented with under different variant names, during the development process of the DID.

Creation

Genesis Record

Start with an initial skeleton JSON object as follows, which shall serve as our in-memory fediRecord:

{
  "action": "create",
  "variant": "fedi:0",
  "params": null,
  "alsoKnownAs": [],
  "rotationKeys": [],
  "userKeys": [],
  "services": [],
  "when": null,
  "sig": null,
  "last": null
}

Next, define the creation parameters object (creationParams), based on the preferences desired for the DID. The required parameters and their respective options are as defined:

canon: Defines the canonicalization scheme used for record signing and DID generation. The only option currently allowed is "jcs", referring to the JSON Canonicalization Scheme as defined in [[RFC8785]].
hash: Defines the final hash algorithm to be used to generate the did:fedi identifier, after signing. Currently allowed options are: sha256
length: Defines the length of the output hash, in bytes. The value may be less than the hash algorithm's standard output size, which would imply a truncation being applied after hash generation. Hash sizes below 15 bytes (120 bits) are strongly not recommended, and implementations are encouraged to deny weak hash sizes.
encode: Defines the canonical base encoding of the desired resulting DID, for the DID-specific identifier portion. Currently allowed options are: base32, base58btc, base64url

An example of a valid set of parameters are demonstrated below.

{
  "canon": "jcs",
  "hash": "sha256",
  "length": 16,
  "encode": "base58btc"
}

Assign the parameters object as a value of the params property in the fediRecord object.

Rotation Key Generation and Endorsement

Generate two Ed25519 keypairs for the use of certifying the genesis record and any future changes. Encoding and endorsing each public key is handled as follows:

Let rawPublicKey be the public key bytes of the generated Ed25519 key
Let multicodecPubkey be the result of concatenating the bytes 0xed, 0x01, and the bytes of rawPublicKey
Let armoredPubkey be the result of performing Base64url encoding on multicodecPubkey with padding characters omitted.
Let multikey be the result of prepending the character "u" to the armoredPubkey string value.
Let rotationKey be the result of creating a map object, where id has a short random unique string, and key has the value of multikey
Append rotationKey to the list stored in fediRecord.rotationKeys

Demonstration in JavaScript utilizing the WebCrypto API

let keypair = await window.crypto.subtle.generateKey('Ed25519', true, ['sign', 'verify']);
let rawPublicKey = await window.crypto.subtle.exportKey('raw', keypair.publicKey);
let multicodecPubkey = new Uint8Array( [0xed, 0x01, ...rawPublicKey] );
let armoredPubkey = base64url.encode( multicodecPubkey );
let multikey = "u" + armoredPubkey;
let rotationKey = {
  id: "0e8a",
  key: rotationKey
};
fediRecord.rotationKeys.push( rotationKey );

Note that Ed25519 support in WebCrypto is fairly new. Only Firefox 129+ and Safari 17+ have unprefixed support, at the time of writing. Polyfills are needed to support other/older browsers, but polyfills do carry the risk of side-channel attacks due to the non-deterministic performance of JavaScript code execution.

Rotation Keys are only used internally within the DID method for certifying and updating the DID, and are not presented in any DID Document resolution output.

Endorsing User Keys

Public keys to be publicly endorsed within the resolved DID Document (and thus used in any services that consumes the DID), such as for the roles of authentication, proof assertion, key exchange, and capability delegation/invocation—are to be listed in the userKeys list in a fedi record. These may be used and referenced in HTTP Signatures or in Object Integrity Proofs [[FEP-8b32]].

A public key object may be represented as a Multicodec-described value, stored as the value of a multikey property;
- or, as a JSON Web Token, stored as the value of a jwt property.
A public key object MUST have a short unique string identifier, stored as the value of the id property.
A public key object shall list it's authorized uses, under the uses property, containing a list of strings corresponding with the authorized use.

Use Label	Description
assert	Corresponds to `assertionMethod` in a Controller Document
auth	Corresponds to `authentication` in a Controller Document
keyexch	Corresponds to `keyAgreement` in a Controller Document
capdel	Corresponds to `capabilityDelegation` in a Controller Document
capinv	Corresponds to `capabilityInvocation` in a Controller Document

An example of a valid public key object, as to be appended to the userKeys list in the fediRecord is demonstrated as follows:

{
  "id": "df62",
  "multikey": "z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2",
  "uses": ['auth', 'capdel']
}

Services

It is strongly encouraged to delegate storage of ActivityPub objects and media to external services, versus being stored directly "on-chain" within the did:fedi protocol infrastructure. The function of did:fedi is mainly to serve as the "DNS and Certificate Authority of the identity" rather than arbitrary object storage itself. An implementation is allowed to handle identity and storage within the same application and server, it just requires that the responsibilities are cleanly separately (@TODO reword more succinctly). Media and ActivityPub objects are recommended to be listed under separate services, even if they may resolve to the exact same serviceEndpoint. DID URL Resolution and interaction with serviceEndpoints is described further in DID URL Resolution.

The service property in a did:fedi record directly correlates to the service property value presented upon DID resolution. A service can be either ActivityPubService for a server that can handle inbox activity, other dynamic behavior of an ActivityPub implementation, authentication-gated posts, etc; or a MediaStorageService for plain media and object storage. An example of a service value is demonstrated below:

{
  // (...)
  "service": [
    {
      "id": "#ap",
      "type": "ActivityPubService",
      "serviceEndpoint": [
        "https://example.social/user/bob/"
      ]
    },
    {
       "id": "#files",
       "type": "MediaStorageService",
       "serviceEndpoint": [
         "https://example.social/media/bob/",
         "https://backup.example.social/b2ed46e6-6ed7-4bf3-d7db-533aed14ed66/"
       ]
    }
  ],
  // (...)
}

The id of a service entry may be any short URL-safe string, as it is an important component in distinguishing between services in a DID URL. The serviceEndpoint may point to different locations over time, as a user moves between platforms and hosting providers, while transparently facilitating a stable identifier for media and ActivityPub content. Renaming a service to a different id is discouraged, as it will break any links that depend on that id.

Signing

When a did:fedi record is populated with the necessary public keys and information to be published, (... @TODO)

Let fediRecord be the populated map object that is to be signed
Set the sig property of fediRecord to null
If fediRecord is not the first record (a genesis record), and instead an update operation, then:
1. If the action property of fediRecord is set to "create", change the value to "update"
2. Delete the params property from fediRecord, if it exists
3. Delete the did property from fediRecord, if it exists
4. Let lastHashRaw be the result of JCS canonicalization of the previous record, after being SHA-256 hashed
5. Let lastMultihash be the result of concatenating the bytes 0x12, 0x20, and the bytes of lastHashRaw
6. Let lastHash be the result of: base64url encoding lastMultihash, and prepending the character "u"
7. Set the last property of fediRecord to the value of lastHash
Set the when property of fediRecord to the latest datetime in ISO 8601 order, as Zulu time, with a "Z" timezone identifier only, and no sub-second values included
Let canonicalRecord be the result of JCS canonicalization of fediRecord
Let signature be the result of cryptographically signing canonicalRecord, with a private key that corresponds with a public key listed under rotationKeys in the current in-memory did:fedi record
Let sigObj be the value of a map containing a property named sig which holds the value of signature, and a property named id that corresponds to the id value of the public key that corresponds with the private key that was used for creating signature
Set the sig property of the fediRecord to the value of sigObj
If this is the first record; then,
1. Let didHashBytes be the result of performing JCS canonicalization, hashing, and encoding based upon the configuration values specified in params
2. Assign a property named did to fediRecord, with a value of the string "did:fedi:" concatenated with the value of finalDid

async function signRecord(fediRecord, lastRecord = null) {
  fediRecord.sig = null;
  if (null !== lastRecord) {
    if (fediRecord.action == "create") {
      fediRecord.action = "update";
    }
    if (fediRecord.hasOwnProperty('params')) {
      delete fediRecord.params;
    }
    if (fediRecord.hasOwnProperty('did')) {
      delete fediRecord.did;
    }
    let lastHashRaw = await window.crypto.subtle.digest("SHA-256", canonicalize(lastRecord));
    let lastMultihash = new Uint8Array( [0x12, 0x20, ...lastHashRaw] );
    let lastHash = "u" + base64url_encode( lastMultihash );
    fediRecord.last = lastHash;
  }
  fediRecord.when = new Date().toISOString().split('.')[0]+"Z";
  let canonicalRecord = canonicalize( fediRecord );
  let utf = new TextEncoder();
  let signature = await window.crypto.subtle.sign('Ed25519', rotKeypair.privateKey, utf.encode(canonicalRecord));
  let sigObj = { sig: signature, id: rotKeypair.id };
  fediRecord.sig = sigObj;
  if (null === lastRecord) {
    let finalDid = multihash_encode(fediRecord.params.hash, fediRecord.params.length, utf.encode(fediRecord));
    fediRecord.did = "did:fedi:" + finalDid;
  }
  return fediRecord;
}

Verifying

@TODO write descriptive form of procedures

async function verifyRecord(fediRecord, lastRecord = null) {
  if (fediRecord.hasOwnProperty('did')) {
    delete fediRecord.did;
  }
  if (null !== lastRecord) {
    if (!multihash_compare(fediRecord.last, lastRecord)) {
      return false; // Hash of last record does not match calculated hash
    }
  }
  var sigObj = fediRecord.sig;
  fediRecord.sig = null;
  var permittedKeys = (null === lastRecord) ? fediRecord.rotationKeys : lastRecord.rotationKeys;
  var signingKey = permittedKeys.filter(function(item) {
    return item.id == sigObj.id;
  });
  if (signingKey.length === 0) {
    return false; // No matching key id in rotationKeys that corresponds to signature key id
  }
  signingKey = signingKey[0];
  let rawSig = multibase_decode(sigObj.sig);
  let pubkey = await window.crypto.subtle.importKey('raw', multibase_decode(signingKey.key), 'Ed25519', ['verify']);
  return await window.crypto.subtle.verify('Ed25519', pubkey, rawSig, canonicalize(fediRecord) );
}

Submission

The parameters for an HTTP request for submission of a record are as follows:

Request MUST use the POST method
Request path MUST include the DID appended to the endpoint URL being submitted to
Request header Content-Type MUST be set to application/didfedi+json
Request body MUST a UTF-8 encoded string of the JSON-encoded record.

Retrieval

The parameters for requesting the latest record for a DID are as follows:

Request MUST use the GET method
Request path MUST include the DID appended to the endpoint URL being queried from
Request header Accept MUST contain application/didfedi+json

@TODO Filter parameters

Record History

To query the full record history for a did:fedi identity, or to synchronize the full history all-at-once, the same criteria for submission and retrieval apply, EXCEPT that instead of application/didfedi+json, the value application/didfedi+jsonlines is used instead. Whereas the POST body in a submission, or the response body in a query, would instead be multiple records delimited in JSON Lines format (each record terminated by a line break character: 0x0A), in ascending chronological order (genesis record being first).

Update

Any subsequent updates to a DID are identified with an action property set to update. Updates SHOULD NOT contain a params nor did property. Same signing and verifying procedures as outlined in Signing and Verifying section applies. Update records MUST contain a hash of the previous record, stored in the last property before signing. The when property of an update MUST be a later datetime than the previous record.

Updates to the DID are signified simply by the omission, replacement, or addition of values in the record. An update MUST have at least one valid public key listed in rotationKeys.

Revocation

The permanent revocation of an identity is signified by a final signed record where the action property is set to revoke. No subsequent records may be accepted after revocation.

DID URL Resolution

It is strongly encouraged that implementations of the did:fedi method only implement resolution for the base identifier, and not perform object storage using paths identified under the identifier (e.g. NOT did:fedi:z6x5vHr6sWxo4qtYamucHWRuug/post/hello-world).

Instead, it is strongly encouraged to treat DID Resolution essentially as a DNS-like system for referencing different services, that can be used storage providers, that's inferred from the DID Document (as a byproduct of DID Resolution). The justifications to this design decision are:

significantly reduces the load and burden on did:fedi resolution relays and providers to only handling identity-related updates, rather than being involved in hosting arbitrary object or multimedia storage (as well as confusions of which servers allow storage/caching of such content),
makes identity portability easier, as not all providers might offer object storage within the same DID infrastructure
allows use of generic non-DID-aware storage, such as static file hosting providers and cloud bucket storage to be used for hosting content relating to an identity.
allowing arbitrary object storage within the same procedures as DID Resolution may create the risk of type confusion, such as with DID-specific ledger info; while DID URL dereferencing enables a clearer distinction between DID Documents and arbitrary media.

Utilizing the URL dereferencing behavior that's already described in DID Resolution, there are two required URL parameters: service and relativeRef. service corresponds to the id of a service description listed under the service list of a DID Document. relativeRef refers to the remaining path that locates the resource, when appended to a serviceEndpoint URL.

Therefore, given the following resolved DID Document:

{
  "id": "did:fedi:z6x5vHr6sWxo4qtYamucHWRuug",
  // (...)
  "service": [
    {
      "type": "ActivityPubService",
      "id": "#ap",
      "serviceEndpoint": [
        "https://example.social/user/bob/"
      ]
    },
    {
       "type": "MediaStorageService",
       "id": "#files",
       "serviceEndpoint": [
         "https://example.social/media/bob/",
         "https://backup.example.social/b2ed46e6-6ed7-4bf3-d7db-533aed14ed66/"
       ]
    }
  ]
}

along with a DID URL of:

did:fedi:z6x5vHr6sWxo4qtYamucHWRuug?service=ap&relativeRef=outbox

would dereference to a final resolvable URL of

https://example.social/user/bob/outbox

This behavior may closely align to the proposal [[FEP-e3e9]] (Actor-Relative URLs).

Comparison to other DID methods

Other DID methods can absolutely be used within ActivityPub, there's just a few minor preferential motives for constructing a different DID method rather than using the current proposals or standards:

did:key is not intended to be directly used for a standalone identity, has no configurable DID output, and offers no key rotation or revocation mechanisms
did:web is easily resolvable but not portable to a different domain or path
did:plc requires additional libraries and toolings from the DAG-CBOR and IPLD ecosystem in order to canonicalize and verify DIDs
did:plc offers base32 encoding only, uses a short 120-bit identifier; more compact encodings are allowed in did:fedi
did:plc mandates only P-256 and secp256k1, which requires additional BigInteger arithmetic to mathematically compress the public keys for canonical Multikey representation
did:tdw conceptually mixes both did:key and did:web, but carries a heavy identifier length, while did:fedi with Compatibility URLs carries the same benefits, with less overhead

Decentralized ActivityPub Draft

did:fedi Specification

Creation

Genesis Record

Rotation Key Generation and Endorsement

Endorsing User Keys

Services

Signing

Verifying

Submission

Retrieval

Record History

Update

Revocation

DID URL Resolution

Comparison to other DID methods

Compatibility URLs

DID Update Hints

Security

Signature Malleability

Encoding Normalization

Verification Bloat

Definitions

Multibase

Multicodec

Multikey

Varint