- "https://atomicdata.dev/properties/description": "A Commit is a Resource that describes how a Resource must be updated.\nIt can be used for auditing, versioning and feeds.\nIt is cryptographically signed by an [Agent](https://atomicdata.dev/classes/Agent).\n\nThe **required fields** are:\n\n- `subject` - The thing being changed. A Resource Subject URL (HTTP identifier) that the Commit is changing about. A Commit Subject must not contain query parameters, as these are reserved for dynamic resources.\n- `signer` - Who's making the change. The Atomic URL of the Author's profile - which in turn must contain a `publicKey`.\n- `signature` - Cryptographic proof of the change. A hash of the JSON-AD serialized Commit (without the `signature` field), signed by the Agent's `private-key`. This proves that the author is indeed the one who created this exact commit. The signature of the Commit is also used as the identifier of the commit.\n- `created-at` - When the change was made. A UNIX timestamp number of when the commit was created.\n\nThe **optional method fields** describe how the data must be changed:\n\n- `destroy` - If true, the existing Resource will be removed.\n- `remove` - an array of Properties that need to be removed (including their values).\n- `set` - a Nested Resource which contains all the new or edited fields.\n\nThese commands are executed in the order above.\nThis means that you can set `destroy` to `true` and include `set`, which empties the existing resource and sets new values.\n\n### Posting commits using HTTP\n\nSince Commits contains cryptographic proof of authorship, they can be accepted at a public endpoint.\nThere is no need for authentication.\n\nA commit should be sent (using an HTTPS POST request) to a `/commmit` endpoint of an Atomic Server.\nThe server then checks the signature and the author rights, and responds with a `2xx` status code if it succeeded, or an `5xx` error if something went wrong.\nThe error will be a JSON object.\n\n### Serialization with JSON-AD\n\nLet's look at an example Commit:\n\n```json\n{\n \"@id\": \"https://atomicdata.dev/commits/3n+U/3OvymF86Ha6S9MQZtRVIQAAL0rv9ZQpjViht4emjnqKxj4wByiO9RhfL+qwoxTg0FMwKQsNg6d0QU7pAw==\",\n \"https://atomicdata.dev/properties/createdAt\": 1611489929370,\n \"https://atomicdata.dev/properties/isA\": [\n \"https://atomicdata.dev/classes/Commit\"\n ],\n \"https://atomicdata.dev/properties/set\": {\n \"https://atomicdata.dev/properties/shortname\": \"1611489928\"\n },\n \"https://atomicdata.dev/properties/signature\": \"3n+U/3OvymF86Ha6S9MQZtRVIQAAL0rv9ZQpjViht4emjnqKxj4wByiO9RhfL+qwoxTg0FMwKQsNg6d0QU7pAw==\",\n \"https://atomicdata.dev/properties/signer\": \"https://surfy.ddns.net/agents/9YCs7htDdF4yBAiA4HuHgjsafg+xZIrtZNELz4msCmc=\",\n \"https://atomicdata.dev/properties/subject\": \"https://atomicdata.dev/test\"\n}\n```\n\nThis Commit can be sent to any Atomic Server.\nThis server, in turn, should verify the signature and the author's rights before the server applies the Commit.\n\n### Calculating the signature\n\nThe signature is a base64 encoded Ed25519 signature of the deterministically serialized Commit.\nCalculating the signature is a delicate process that should be followed to the letter - even a single character in the wrong place will result in an incorrect signature, which makes the Commit invalid.\n\nThe first step is **serializing the commit deterministically**.\nThis means that the process will always end in the exact same string.\n\n- Serialize the Commit as JSON-AD.\n- Do not serialize the signature field.\n- Do not include empty objects or arrays.\n- If `destroy` is false, do not include it.\n- All keys are sorted alphabetically - both in the root object, as in any nested objects.\n- The JSON-AD is minified: no newlines, no spaces.\n\nThis will result in a string.\nThe next step is to sign this string using the Ed25519 private key from the Author.\nThis signature is a byte array, which should be encoded in base64 for serialization.\nMake sure that the Author's URL resolves to a Resource that contains the linked public key.\n\nCongratulations, you've just created a valid Commit!\n\nHere are currently working implementations of this process, including serialization and signing (links are permalinks).\n\n- [in Rust (atomic-lib)](https://github.com/joepio/atomic/blob/ceb88c1ae58811f2a9e6bacb7eaa39a2a7aa1513/lib/src/commit.rs#L81).\n- [in Typescript / Javascript (atomic-data-browser)](https://github.com/joepio/atomic-data-browser/blob/fc899bb2cf54bdff593ee6b4debf52e20a85619e/src/atomic-lib/commit.ts#L51).\n\nIf you want validate your implementation, check out the tests for these two projects.\n\n### Applying the Commit\n\nIf you're on the receiving end of a Commit (e.g. if you're writing a server or a client who has to parse Commits), you will _apply_ the Commit to your Store.\nIf you have to _persist_ the Commit, you must perform all of the checks.\nIf you're writing a client, and you trust the source of the Commit, you can probably skip the validation steps.\n\nHere's how you apply a Commit:\n\n1. Check if the Subject URL is valid\n2. Validate the signature. This means serialize the Commit deterministically (see above), check the Agent's publickey (you might need to fetch this one), verify if the signature matches.\n3. Check if the timestamp matches is OK. I think an acceptable window is 10 seconds.\n4. If the Commit is for an existing resource, get it.\n5. Validate the Rights of the one making the Commit.\n6. Check if the `previousCommit` of the Commit matches with the `previousCommit` of the Resource.\n7. Iterate over the `set` fields. Overwrite existing, or add the new Values. Make sure the Datatypes match with the respective Properties.\n8. Iterate over the `remove` fields. Remove existing properties.\n9. If the Resource has one or more classes, check if the required Properties are there.\n10. You might want to perform some custom validations now (e.g. if you accept an Invite, you should make sure that the one creating the Invite has the correct rights to actually make it!)\n11. Store the created Commit as a Resource, and store the modified Resource!\n\n## Limitations\n\n- Commits adjust **only one Resource at a time**, which means that you cannot change multiple in one commit.\n- The one creating the Commit will **need to sign it**, which may make clients that write data more complicated than you'd like. You can also let Servers write Commits, but this makes them less verifiable / decentralized.\n- Commits require signatures, which means **key management**. Doing this securely is no trivial matter.\n- The signatures **require JSON-AD** serialization\n- If your implementation persists all Commits, you might need to **store a lot of data**.\n",
0 commit comments