Skip to content

Commit

Permalink
Update github repo urls
Browse files Browse the repository at this point in the history
  • Loading branch information
joepio committed May 22, 2022
1 parent dc3a368 commit 126535d
Show file tree
Hide file tree
Showing 10 changed files with 3,814 additions and 549 deletions.
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -297,7 +297,7 @@ Warning: existing databases will _not_ work with this version.

Warning: existing Agents and Commits will no longer work. Be sure to create new ones.

- Change Commit serialization to [match atomic-data-browser](https://github.com/joepio/atomic-data-browser/issues/3) implementation #98.
- Change Commit serialization to [match atomic-data-browser](https://github.com/atomicdata-dev/atomic-data-browser/issues/3) implementation #98.

## [v0.21.1]

Expand Down
4 changes: 2 additions & 2 deletions CONTRIBUTE.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ Clone the repo and run `cargo run` from each folder (e.g. `cli` or `server`).

Since `atomic-server` is developed in conjunction with the typescript / react `atomic-data-browser` project, it might make sense to run both locally whilst developing.

- Clone [`atomic-data-browser`](https://github.com/joepio/atomic-data-browser) and run it (see readme.md, basically: `yarn start`)
- Clone [`atomic-data-browser`](https://github.com/atomicdata-dev/atomic-data-browser) and run it (see readme.md, basically: `yarn start`)
- Visit `https://localhost:8080` (default)
- Visit your `localhost` in your locally running `atomic-data-browser` instance: (e.g. `http://localhost:8080/app/show?subject=http%3A%2F%2Flocalhost`)

Expand Down Expand Up @@ -137,7 +137,7 @@ drill -b benchmark.yml --stats

Before tagging a new version, make sure to update the `app_assets` folder:

1. clone [atomic-data-browser](https://github.com/joepio/atomic-data-browser) in the folder above this one
1. clone [atomic-data-browser](https://github.com/atomicdata-dev/atomic-data-browser) in the folder above this one
2. run `yarn build-server` in `atomic-data-browser`, which should
3. Make sure not to commit all the files, manually check them
4. search and replace `.workbox` with `./app_assets/workbox` in `sw.js`, because we'll host `sw.js` from root.
Expand Down
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

[![Discord chat][discord-badge]][discord-url]
[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
[![github](https://img.shields.io/github/stars/joepio/atomic?style=social)](https://github.com/joepio/atomic)
[![github](https://img.shields.io/github/stars/joepio/atomic?style=social)](https://github.com/atomicdata-dev/atomic-data-browser)

**Create, share, fetch and model [Atomic Data](https://docs.atomicdata.dev)!
This repo consists of three components: A library, a server and a CLI.**
Expand All @@ -21,7 +21,7 @@ Demo on [atomicdata.dev](https://atomicdata.dev)**
- 💻 **Runs everywhere** (linux, windows, mac, arm)
- ⚛️ **Dynamic schema validation** / type checking using [Atomic Schema](https://docs.atomicdata.dev/schema/intro.html).
- 🌐 **Embedded server** with support for HTTP / HTTPS / HTTP2.0 and Built-in LetsEncrypt handshake.
- 🎛️ **Browser GUI included** powered by [atomic-data-browser](https://github.com/joepio/atomic-data-browser). Features dynamic forms, tables, authentication, theming and more.
- 🎛️ **Browser GUI included** powered by [atomic-data-browser](https://github.com/atomicdata-dev/atomic-data-browser). Features dynamic forms, tables, authentication, theming and more.
- 💾 **Event-sourced versioning** / history powered by [Atomic Commits](https://docs.atomicdata.dev/commits/intro.html)
- 🔄 **Synchronization using websockets**: communicates state changes with a client.
- 🧰 **Many serialization options**: to JSON, [JSON-AD](https://docs.atomicdata.dev/core/json-ad.html), and various Linked Data / RDF formats (RDF/XML, N-Triples / Turtle / JSON-LD).
Expand Down Expand Up @@ -58,9 +58,9 @@ Powers both `atomic-cli` and `atomic-server`.

## Also check out

- [Atomic-Data-Browser](https://github.com/joepio/atomic-data-browser), an in-browser app for viewing and editing atomic data. Also contains a typescript / react front-end library. Will replace most of the html templating in this project.
- [Atomic-Data-Browser](https://github.com/atomicdata-dev/atomic-data-browser), an in-browser app for viewing and editing atomic data. Also contains a typescript / react front-end library. Will replace most of the html templating in this project.
- [Atomic-Data-Docs](https://github.com/ontola/atomic-data-docs), a book containing detailed documentation of Atomic Data.
- [RayCast extension](https://www.raycast.com/joepio/atomic) for searching stuff
- [RayCast extension](https://www.raycast.com/atomicdata-dev/atomic-data-browser) for searching stuff
- [Click here to sign up to the Atomic Data Newsletter](http://eepurl.com/hHcRA1)
- [The Atomic Data Docs](https://docs.atomicdata.dev/)

Expand Down
2 changes: 1 addition & 1 deletion desktop/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ cargo tauri build

## Running in development

By default, the dev server points to `localhost:8080`, which is the server for [`atomic-data-browser`](https://github.com/joepio/atomic-data-browser/), which you'll probably want to run.
By default, the dev server points to `localhost:8080`, which is the server for [`atomic-data-browser`](https://github.com/atomicdata-dev/atomic-data-browser/), which you'll probably want to run.
If you only want to work on the _server side_ of things, you can remove `devPath` in `tauri.conf.json`.

## Limitations
Expand Down
2 changes: 1 addition & 1 deletion lib/defaults/default_store.json
Original file line number Diff line number Diff line change
Expand Up @@ -713,7 +713,7 @@
},
{
"@id": "https://atomicdata.dev/classes/Commit",
"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",
"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/atomicdata-dev/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",
"https://atomicdata.dev/properties/isA": [
"https://atomicdata.dev/classes/Class"
],
Expand Down
Loading

0 comments on commit 126535d

Please sign in to comment.