diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index a934e7c..0000000 --- a/docs/README.md +++ /dev/null @@ -1,37 +0,0 @@ -# doip.js - -doip.js allows websites and Node.js projects to verify decentralized online -identities based on OpenPGP. - -## Features - -- Verify online identities using profile URLs -- Regex-based service provider detection -- [Mocha](https://mochajs.org/) tests - -## About Keyoxide - -[Keyoxide](https://keyoxide.org/), made by Yarmo Mackenbach, is a modern, secure -and privacy-friendly platform to establish decentralized online identities using -a novel concept know as [DOIP](doip.md). In an effort to make this technology -accessible for other projects and stimulate the emergence of both complementary -and competing projects, this project-agnostic library is -[published on codeberg.org](https://codeberg.org/keyoxide/doipjs) and open -sourced under the -[Apache-2.0](https://codeberg.org/keyoxide/doipjs/src/branch/main/LICENSE) -license. - -## Community - -There's a [Keyoxide Matrix room](https://matrix.to/#/#keyoxide:matrix.org) where -we discuss everything DOIP and Keyoxide. - -## Donate - -Please consider [donating](https://liberapay.com/Keyoxide/) if you think this -project is a step in the right direction for the internet. - -## Funding - -This library was realized with funding from -[NLnet](https://nlnet.nl/project/Keyoxide/). diff --git a/docs/_coverpage.md b/docs/_coverpage.md deleted file mode 100644 index d06b626..0000000 --- a/docs/_coverpage.md +++ /dev/null @@ -1,10 +0,0 @@ -# doip.js 0.12.0 - - - -Decentralized OpenPGP Identity Proofs library in Node.js - -[Source code](https://codeberg.org/keyoxide/doipjs) -[Getting started](#doipjs) - -![color](#c9beff) diff --git a/docs/_sidebar.md b/docs/_sidebar.md deleted file mode 100644 index c70fb45..0000000 --- a/docs/_sidebar.md +++ /dev/null @@ -1,39 +0,0 @@ -- Getting started - - - [Installation](installation.md) - - [Quick start (Node.js)](quickstart-nodejs.md) - - [Quick start (browser)](quickstart-browser.md) - - [Terminology](terminology.md) - -- Concepts - - - [DOIP](doip.md) - - [Proofs](proofs.md) - - [Claims](claims.md) - - [Service providers](serviceproviders.md) - -- Reference doip.js - - - [Claim (class)](doipjs/class_claim.md) - - [keys (module)](doipjs/module_keys.md) - -- Service providers - - - [dev.to](serviceproviders/devto.md) - - [discourse](serviceproviders/discourse.md) - - [dns](serviceproviders/dns.md) - - [fediverse](serviceproviders/fediverse.md) - - [gitea](serviceproviders/gitea.md) - - [github](serviceproviders/github.md) - - [gitlab](serviceproviders/gitlab.md) - - [hackernews](serviceproviders/hackernews.md) - - [liberapay](serviceproviders/liberapay.md) - - [lobste.rs](serviceproviders/lobsters.md) - - [mastodon](serviceproviders/mastodon.md) - - [owncast](serviceproviders/owncast.md) - - [reddit](serviceproviders/reddit.md) - - [twitter](serviceproviders/twitter.md) - - [xmpp](serviceproviders/xmpp.md) - -- More - - [Changelog](changelog.md) diff --git a/docs/changelog.md b/docs/changelog.md deleted file mode 100644 index 6f93a7f..0000000 --- a/docs/changelog.md +++ /dev/null @@ -1,295 +0,0 @@ -# Changelog - -## [0.11.2] - -[2021-03-06](https://codeberg.org/keyoxide/doipjs/releases/tag/0.11.2) - -## Fixed -- Matrix.to URLs - -## [0.11.1] - -[2021-03-06](https://codeberg.org/keyoxide/doipjs/releases/tag/0.11.1) - -## Fixed -- Proxy URL encoding - -## [0.11.0] - -[2021-03-05](https://codeberg.org/keyoxide/doipjs/releases/tag/0.11.0) - -## Added -- IRC service provider -- Matrix service provider -## Fixed -- Handling of requests without URI - -## [0.10.5] - -[2021-03-02](https://codeberg.org/keyoxide/doipjs/releases/tag/0.10.5) - -## Fixed -- Logic error - -## [0.10.4] - -[2021-03-02](https://codeberg.org/keyoxide/doipjs/releases/tag/0.10.4) - -## Changed -- Add Twitter proxy verification - -## [0.10.3] - -[2021-03-02](https://codeberg.org/keyoxide/doipjs/releases/tag/0.10.3) - -## Changed -- Remove twitter dependency - -## [0.10.2] - -[2021-03-01](https://codeberg.org/keyoxide/doipjs/releases/tag/0.10.2) - -## Changed -- Make Twitter verification configurable - -## [0.10.1] - -[2021-01-13](https://codeberg.org/keyoxide/doipjs/releases/tag/0.10.1) - -## Fixed -- Polyfill for promise.allSettled - -## [0.10.0] - -[2021-01-13](https://codeberg.org/keyoxide/doipjs/releases/tag/0.10.0) - -## Added -- Owncast service provider - -## [0.9.4] - -[2021-01-10](https://codeberg.org/keyoxide/doipjs/releases/tag/0.9.4) - -## Fixed -- Fix typo in keyserver url - -## [0.9.3] - -[2021-01-10](https://codeberg.org/keyoxide/doipjs/releases/tag/0.9.3) - -## Fixed -- Fix regex skipping some claims - -## [0.9.2] - -[2021-01-09](https://codeberg.org/keyoxide/doipjs/releases/tag/0.9.2) - -## Fixed -- Network errors blocking code execution - -## [0.9.1] - -[2021-01-09](https://codeberg.org/keyoxide/doipjs/releases/tag/0.9.1) - -## Changed -- Use signature data to find key location - -## [0.9.0] - -[2021-01-07](https://codeberg.org/keyoxide/doipjs/releases/tag/0.9.0) - -## Added -- Signature claims verification - -## [0.8.5] - -[2021-01-03](https://codeberg.org/keyoxide/doipjs/releases/tag/0.8.5) - -### Fixed -- Remove trailing slash from HKP server URL - -## [0.8.4] - -[2021-01-02](https://codeberg.org/keyoxide/doipjs/releases/tag/0.8.4) - -### Fixed -- Fetch Twitter proofs from Nitter - -## [0.8.3] - -[2020-12-26](https://codeberg.org/keyoxide/doipjs/releases/tag/0.8.3) - -### Fixed -- Handling of users without userId - -## [0.8.2] - -[2020-12-26](https://codeberg.org/keyoxide/doipjs/releases/tag/0.8.2) - -### Fixed -- Handling of users without selfCertifications - -## [0.8.1] - -[2020-12-20](https://codeberg.org/keyoxide/doipjs/releases/tag/0.8.1) - -### Fixed -- Timeout for claim verification promises - -## [0.8.0] - -[2020-12-11](https://codeberg.org/keyoxide/doipjs/releases/tag/0.8.0) - -### Added -- Add fallback proxy policy - -### Fixed -- Handling of failed network requests -- Handling of rejected promises -- DNS proxy URL generation -- Twitter & Dev.to service provider - -## [0.7.5] - -[2020-12-10](https://codeberg.org/keyoxide/doipjs/releases/tag/0.7.5) - -### Fixed -- Browser bundling - -## [0.7.4] - -[2020-12-08](https://codeberg.org/keyoxide/doipjs/releases/tag/0.7.4) - -### Fixed -- Handling HKP URI - -## [0.7.3] - -[2020-12-08](https://codeberg.org/keyoxide/doipjs/releases/tag/0.7.3) - -### Fixed -- Bundled library for release - -## [0.7.2] - -[2020-12-08](https://codeberg.org/keyoxide/doipjs/releases/tag/0.7.2) - -### Fixed -- Support for specifying keyservers - -## [0.7.1] - -[2020-12-08](https://codeberg.org/keyoxide/doipjs/releases/tag/0.7.1) - -### Changed -- Update openpgpjs dependency - -## [0.7.0] - -[2020-12-05](https://codeberg.org/keyoxide/doipjs/releases/tag/0.7.0) - -### Changed -- Properly reject promises - -## [0.6.0] - -[2020-11-20](https://codeberg.org/keyoxide/doipjs/releases/tag/0.6.0) - -### Changed -- Handle multiple users in key - -## 0.5.2 - -[2020-11-20](https://codeberg.org/keyoxide/doipjs/releases/tag/0.5.2) - -### Fixed - -- Claim verification regex - -## 0.5.1 - -[2020-11-20](https://codeberg.org/keyoxide/doipjs/releases/tag/0.5.1) - -### Fixed -- Link to bundled openpgp - -## 0.5.0 - -[2020-11-18](https://codeberg.org/keyoxide/doipjs/releases/tag/0.5.0) - -### Added -- Keys fetching using openpgp.js -- Claims extraction from keys using openpgp.js - -### Changed -- Support xmpp via doip-proxy -- Module structure -- Docs - -### Fixed -- Bad verification value return for text proofs -- Missing User-Agent request header - -## 0.4.2 - -[2020-11-06](https://codeberg.org/keyoxide/doipjs/releases/tag/0.4.2) - -### Changed - -- URLs in package.json - -## 0.4.1 - -[2020-11-06](https://codeberg.org/keyoxide/doipjs/releases/tag/0.4.1) - -### Changed - -- Update README -- Add image to coverpage - -## 0.4.0 - -[2020-11-06](https://codeberg.org/keyoxide/doipjs/releases/tag/0.4.0) - -### Added - -- Custom request handler for DNS service provider -- Docs - -### Changed - -- Service provider data structure -- More consistent handling of options - -### Removed - -- dotenv dependency - -### Fixed - -- Crash for unexpected JSON data structure -- Body in http requests - -## 0.3.0 - -[2020-11-04](https://codeberg.org/keyoxide/doipjs/releases/tag/0.3.0) - -### Added - -- Liberapay service provider -- Proxy request handler - -### Changed - -- Improve handling of arrays in JSON -- Customizable proxy hostname - -### Fixed - -- Dots in URL regex - -## 0.2.0 - -[2020-11-03](https://codeberg.org/keyoxide/doipjs/releases/tag/0.2.0) - -Initial release diff --git a/docs/claims.md b/docs/claims.md deleted file mode 100644 index cb1efc9..0000000 --- a/docs/claims.md +++ /dev/null @@ -1,147 +0,0 @@ -# Claims - -## Definition - -A **claim** is one of the two pieces of data needed to verify an online -identity, the other being a [proof](proofs.md). - -A claim is always a phrase, string or URI that is expected to be found inside -the proof. **The presence of a claim inside a proof verifies that claim.** - -## Claims in OpenPGP keys - -DOIP assumes claims are stored in OpenPGP keys as so-called notations. The -format for all claims is the same: - -``` -proof@metacode.biz=... -``` - -## Relation with proof - -The relation between proof and claim is defined by three variables: `format`, -`path` and `relation`. - -In the following examples, we'll assume we are dealing with a key that has the -fingerprint `13ec664f5e0c3e4ebad8b7441adbf09217175f75`. - -### format - -This variable describes how the proof is integrated in the data returned by the -service provider. - -If `format` is set to `uri`, the claim expects the proof to be or contain: - -``` -openpgp4fpr:13ec664f5e0c3e4ebad8b7441adbf09217175f75 -``` - -If `format` is set to `message`, the claim expects the proof to be or contain: - -``` -[Verifying my OpenPGP key: openpgp4fpr:13ec664f5e0c3e4ebad8b7441adbf09217175f75] -``` - -If `format` is set to `fingerprint`, the claim expects the proof to be or -contain: - -``` -13ec664f5e0c3e4ebad8b7441adbf09217175f75 -``` - -### path - -This variables describes how to get to the important proof-containing field -inside the JSON data. It is an array of strings, each string equal to the next -field inside the JSON data. - -If the proof data is text, the `path` value is ignored. - -Assuming the following JSON data: - -```json -"firstField": { - "secondField": { - "finalField": "openpgp4fpr:13ec664f5e0c3e4ebad8b7441adbf09217175f75", - "yetAnotherField": "yetAnotherValue" - }, - "otherField": "someValue" -} -``` - -To verify any claim, the `path` should be set to: - -```javascript -claim.path = ['firstField', 'secondField', 'finalField'] -``` - -**JSON data containing arrays** - -In cases there are arrays in the JSON data, these should **not** be entered in -`path`. They will always be iterated over. - -Assuming the following JSON data: - -```json -"firstField": { - "fieldContainingArray": [ - { - "finalField": "https://domain.org", - "yetAnotherField": "yetAnotherValue1" - }, - { - "finalField": "openpgp4fpr:13ec664f5e0c3e4ebad8b7441adbf09217175f75", - "yetAnotherField": "yetAnotherValue2" - } - ], - "otherField": "someValue" -} -``` - -To verify any claim, the `path` should be set to: - -```javascript -claim.path = ['firstField', 'fieldContainingArray', 'finalField'] -``` - -Every `finalField` field for every item in the `fieldContainingArray` array will -be tested for the claim. - -### relation - -This variable simply states whether after following the `path` inside the JSON -data, the obtained value `contains` the claim, `equals` the claim or if the -obtained value is an array, the claim is `oneOf` the values of the array. - -The `relation` should be `contains` for the following proof data: - -```json -"firstField": { - "secondField": { - "finalField": "Long text. openpgp4fpr:13ec664f5e0c3e4ebad8b7441adbf09217175f75. Perhaps more text." - } -} -``` - -The `relation` should be `equals` for the following proof data: - -```json -"firstField": { - "secondField": { - "finalField": "openpgp4fpr:13ec664f5e0c3e4ebad8b7441adbf09217175f75" - } -} -``` - -The `relation` should be `oneOf` for the following proof data: - -```json -"firstField": { - "secondField": { - "finalField": [ - "cats", - "openpgp4fpr:13ec664f5e0c3e4ebad8b7441adbf09217175f75" - ] - } -} -``` diff --git a/docs/doip.md b/docs/doip.md deleted file mode 100644 index c51b24b..0000000 --- a/docs/doip.md +++ /dev/null @@ -1,102 +0,0 @@ -# Decentralized OpenPGP Identity Proofs - -Decentralized OpenPGP Identity Proofs, or DOIPs, are a way of identifying -and linking profiles and accounts on the internet. Take ten different websites -and make an account on each of them. How could outsiders tell they were created -by the same person? They can't directly. You could be **Alice** on website A but -**Alice123** on website B. - -What if a bad actor creates an account **Alice** on a brand new website and -starts contacting people you know from website A? How could they verify this new -accounts is in fact you? - -With the digital realm becoming more and more a second home in our lives, we -need tools to identify ourselves and stay safe. - -## Why decentralized? - -Say you have a Facebook or Google account. You can use that to create accounts -on different websites. Problem solved! That is, until the day you get an email -that your account was flagged by AI, you just lost access to all those websites -and there's no way to contact them to restore it. - -This [happens way too often](https://www.businessinsider.com/google-users-locked-out-after-years-2020-10?international=true&r=US&IR=T). - -Why does it happen? You are a number to them. Losing you as a user doesn't cost -them anything. - -Therefore, it is imperative that new solutions give the people **sovereignty** -over their identity. How do we do this? By making new solutions -**decentralized**. - -**Decentralized** simply means that there is no central authority. In the -classic model, you give your data to Facebook or Google and the truth is what -they say it is: if they say you no longer exist, then, well, you no longer -exist. In the **decentralized** model, you hold your own data and no one can -take that away from you. This also means that service providers should fight for -you to keep you as a user since **you allow them to use your data**. Any misstep -on their behalf and you can take it away. - -## Why OpenPGP? - -To achieve user sovereignty, DOIP relies on **OpenPGP** cryptographic keys. Read -more about those keys [here](cryptographickeys.md) but in short: they are like -documents that the whole world can read but only you can edit. In that way, you -can publish a list of profiles on websites that you have created but no one can -do that for you in an attempt to impersonate you. - -## Bidirectional linking - -There's a catch: simply adding a link to a profile inside your OpenPGP document -is not sufficient. If it were, you could claim any profile anywhere simply by -linking to them! - -This is why DOIP uses two-way or bidirectional linking. Your key must link to a -profile and your profile must link back to the key. That is the only way to make -sure you hold both the key and the profile. - -This also solves the imposter problem. A bad actor could you link to your -profile but since your profile doesn't link back to their key, DOIP will not -verify their claim. Unless they hacked your profile, in which case you have more -urgent problems. - -How does a profile link to a cryptographic key? Every key can be uniquely -identified using what we call their **fingerprint**. All a profile page needs to -do is contain that fingerprint somehow. Usually, this can be added as the last -line to a biography. - -Note that the service provider itself needs to do a few things to support the -verification of DOIPs. Please refer to the [list of supported service providers](serviceproviders.md) - -## Adding more than one proof - -The endgame of using DOIP is to add at least two profile. Proving that you own -a single profile—in a way—doesn't prove anything. The issue is that -we cannot prove that **you**, the physical being **you**, holds that key. DOIP -can only verify that "_whoever holds that key also holds that profile_". - -By adding at least two profiles, you can create meaningful links between those -profiles. If someone knows **you**, the physical being **you**, is **Alice** on -website A, they will also now know that you are **Alice123** on website B, -simply because "_whoever holds that key also holds both of those profiles_". - -## Why the snail logo? - -> Aren't snails associated with slowness? - -Well, they are also animals that take their homes with them wherever they go. In -a sense, they are a nice metaphor for DOIP. Snails are the ultimate -"decentralized life" species of the animal kingdom. They don't have to rely on -centralized (social) structures, they are self-sufficient by always having their -home and their identity—and their data!—with them. - -> Yeah, but… Snails are slow, though! - -You know what, let's embrace the Big Slow. DOIP is slow. Not computationally -slow. DOIP is just a slow technology. It doesn't provide a social network, it -doesn't send notifications or reminders, it doesn't want your attention. DOIP is -more set-and-forget. Set your identities and the technology handles the rest. As -long as your public keys are live, they'll just continue to work without your -intervention. - -So yes, it's a **Slow Technology**. diff --git a/docs/doip.png b/docs/doip.png deleted file mode 100644 index 18be005..0000000 Binary files a/docs/doip.png and /dev/null differ diff --git a/docs/doipjs/class_claim.md b/docs/doipjs/class_claim.md deleted file mode 100644 index a980767..0000000 --- a/docs/doipjs/class_claim.md +++ /dev/null @@ -1,129 +0,0 @@ -# Claim (class) - -## Constructor - -new Claim([uri], [fingerprint]) - -**Parameters** - -| Name | Type | Mandatory | Description | -| ----------- | ------ | --------- | --------------------------------- | -| uri | string | false | The URI to an identity to verify | -| fingerprint | string | false | The fingerprint to verify against | - -## Properties - -### uri - -The `uri` to an identity to verify. It can be modified until the claim is in a -`matched` state. - -**Returns** `{String|null}` - -### fingerprint - -The `fingerprint` to verify against. It can be modified until the claim is in a -`verified` state. - -**Returns** `{String|null}` - -### state - -The current `state` of the Claim object. It can not be set. - -**Values** - -| Value | Description | -| -------- | ----------------------------------------------------------------- | -| init | The claim has just been initialized | -| matched | The claim has been matched to candidate claim definitions | -| verified | The claim has attempted to verify all candidate claim definitions | - -**Returns** `{String}` The current state - -### matches - -The `matches` (or "candidate claim definitions") that have been matched against -the `uri`. - -Will throw an error if the claim has not yet run `match()`. - -**Returns** `{Array}` - -## Methods - -### match() - -claimInstance.match() - -Verifies the identity behind the provided **uri** using the **fingerprint**. - -**Parameters** - -| Name | Type | Mandatory | Description | -| ----------- | ------ | --------- | -------------------------------- | -| uri | string | true | the URI to an identity to verify | -| fingerprint | string | false | the fingerprint of the claim | -| opts | object | false | options (see below) | - -**Options** - -| Name | Type | Default value | Description | -| ------------------ | ------- | -------------------- | ---------------------------------------------------------------------- | -| returnMatchesOnly | boolean | false | only return matching service providers, do not attempt verification | -| proxyPolicy | string | 'adaptive' | when to use a proxy ['adaptive', 'fallback', 'always', 'never'] | -| doipProxyHostname | string | 'proxy.keyoxide.org' | the hostname of the proxy server | -| twitterBearerToken | string | '' | the Twitter API bearer token used for Twitter verification | -| nitterInstance | string | '' | the domain name of the nitter instance to use for Twitter verification | - -When the `proxyPolicy` option is to `adaptive`, the chosen strategy is -the one suggested by the service provider. - -By default, Twitter accounts are not verified. Either provide a -[Twitter bearer token](https://developer.twitter.com/en/docs/authentication/oauth-2-0/bearer-tokens) -(as `twitterBearerToken`) or the domain name of a Nitter instance (as -`nitterInstance`) to enable Twitter account verification. If both values are -provided, only the Twitter bearer token is used. - -Note that Nitter instances are subject to rate limiting which would instantly -break Twitter account verification. - -**Returns** - -An object with the results of the identity claim verification containing a -boolean named `isVerified` and a -[serviceproviderData](serviceproviderdataobject.md#service-provider-data-object) -object. - -```json -{ - "isVerified": true, - "serviceproviderData": { ... } -} -``` - -If `opts.returnMatchesOnly` is `true`, this function instead returns a list of -service providers matched to the provided `uri`. - -### verify([opts]) - -_(async)_ `claimInstance.verify([opts])` - -Verifies the identity behind the provided **array of uris** using the **fingerprint**. - -**Parameters** - -| Name | Type | Mandatory | Description | -| ----------- | ------ | --------- | ---------------------------- | -| uriArray | array | true | array of uris | -| fingerprint | string | false | the fingerprint of the claim | -| opts | object | false | options (see below) | - -**Options** - -See [claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts). - -**Returns** - -An array of objects with claim verification results (see -[claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts)). diff --git a/docs/doipjs/module_keys.md b/docs/doipjs/module_keys.md deleted file mode 100644 index e521000..0000000 --- a/docs/doipjs/module_keys.md +++ /dev/null @@ -1,239 +0,0 @@ -# keys (module) - -## Constructor - -new Claim([uri], [fingerprint]) - -**Parameters** - -| Name | Type | Mandatory | Description | -| ----------- | ------ | --------- | -------------------------------- | -| uri | string | false | the URI to an identity to verify | -| fingerprint | string | false | the fingerprint of the claim | - -## Properties - -## Methods - -Verifies the identity behind the provided **uri** using the **fingerprint**. - -**Parameters** - -| Name | Type | Mandatory | Description | -| ----------- | ------ | --------- | -------------------------------- | -| uri | string | true | the URI to an identity to verify | -| fingerprint | string | false | the fingerprint of the claim | -| opts | object | false | options (see below) | - -**Options** - -| Name | Type | Default value | Description | -| ------------------ | ------- | -------------------- | ---------------------------------------------------------------------- | -| returnMatchesOnly | boolean | false | only return matching service providers, do not attempt verification | -| proxyPolicy | string | 'adaptive' | when to use a proxy ['adaptive', 'fallback', 'always', 'never'] | -| doipProxyHostname | string | 'proxy.keyoxide.org' | the hostname of the proxy server | -| twitterBearerToken | string | '' | the Twitter API bearer token used for Twitter verification | -| nitterInstance | string | '' | the domain name of the nitter instance to use for Twitter verification | - -When the `proxyPolicy` option is to `adaptive`, the chosen strategy is -the one suggested by the service provider. - -By default, Twitter accounts are not verified. Either provide a -[Twitter bearer token](https://developer.twitter.com/en/docs/authentication/oauth-2-0/bearer-tokens) -(as `twitterBearerToken`) or the domain name of a Nitter instance (as -`nitterInstance`) to enable Twitter account verification. If both values are -provided, only the Twitter bearer token is used. - -Note that Nitter instances are subject to rate limiting which would instantly -break Twitter account verification. - -**Returns** - -An object with the results of the identity claim verification containing a -boolean named `isVerified` and a -[serviceproviderData](serviceproviderdataobject.md#service-provider-data-object) -object. - -```json -{ - "isVerified": true, - "serviceproviderData": { ... } -} -``` - -If `opts.returnMatchesOnly` is `true`, this function instead returns a list of -service providers matched to the provided `uri`. - -### claims.verify(uriArray, [fingerprint], [opts]) - -_(async)_ doip.claims.verify(array, [fingerprint], [opts]) - -Verifies the identity behind the provided **array of uris** using the **fingerprint**. - -**Parameters** - -| Name | Type | Mandatory | Description | -| ----------- | ------ | --------- | ---------------------------- | -| uriArray | array | true | array of uris | -| fingerprint | string | false | the fingerprint of the claim | -| opts | object | false | options (see below) | - -**Options** - -See [claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts). - -**Returns** - -An array of objects with claim verification results (see -[claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts)). - -### claims.verify(key, [fingerprint], [opts]) - -_(async)_ doip.claims.verify(key, [fingerprint], [opts]) - -Verifies the identity behind the claims contained within the provided -**key** using the **fingerprint**. This key is outputted by the -[keys.fetch.\*()](#keysfetchuriuri) commands. - -**Parameters** - -| Name | Type | Mandatory | Description | -| ----------- | ------ | --------- | ---------------------------- | -| key | object | true | a public key | -| fingerprint | string | false | the fingerprint of the claim | -| opts | object | false | options (see below) | - -**Options** - -See [claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts). - -**Returns** - -An array of objects with claim verification results (see -[claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts)). - -### keys.fetch.uri(uri) - -_(async)_ keys.fetch.uri(uri) - -Fetches a key based on the provided `uri`. This simply serves as a shortcut to -other `keys.fetch.*` commands. - -**Parameters** - -| Name | Type | Mandatory | Description | -| ---- | ------ | --------- | --------------------- | -| uri | string | true | public key identifier | - -Possible formats for `uri`: - -`hkp:FINGERPRINT` ⇒ `keys.fetch.hkp(FINGERPRINT)` -`hkp:FINGERPRINT:KEYSERVER` ⇒ `keys.fetch.hkp(FINGERPRINT, KEYSERVER)` -`hkp:EMAIL` ⇒ `keys.fetch.hkp(EMAIL)` -`hkp:EMAIL:KEYSERVER` ⇒ `keys.fetch.hkp(EMAIL, KEYSERVER)` -`wkd:EMAIL` ⇒ `keys.fetch.wkd(EMAIL)` -`kb:USERNAME:FINGERPRINT` ⇒ `keys.fetch.keybase(USERNAME, FINGERPRINT)` - -**Returns** - -A public key object. - -### keys.fetch.hkp(fingerprint, [keyserverBaseUrl]) - -_(async)_ keys.fetch.hkp(fingerprint, [keyserverBaseUrl]) - -Fetches a key using HKP-compatible key servers. - -**Parameters** - -| Name | Type | Mandatory | Description | -| ---------------- | ------ | --------- | --------------------- | -| fingerprint | string | true | public key identifier | -| keyserverBaseUrl | string | false | base URL of keyserver | - -`keyserverBaseUrl` defaults to `https://keys.openpgp.org/`. - -**Returns** - -A public key object. - -### keys.fetch.hkp(email, [keyserverBaseUrl]) - -_(async)_ keys.fetch.hkp(email, [keyserverBaseUrl]) - -Fetches a key using HKP-compatible key servers. - -**Parameters** - -| Name | Type | Mandatory | Description | -| ---------------- | ------ | --------- | --------------------- | -| email | string | true | public key identifier | -| keyserverBaseUrl | string | false | base URL of keyserver | - -`keyserverBaseUrl` defaults to `https://keys.openpgp.org/`. - -**Returns** - -A public key object. - -### keys.fetch.wkd(wkdId) - -_(async)_ keys.fetch.wkd(wkdId) - -Fetches a key using the WKD protocol. - -**Parameters** - -| Name | Type | Mandatory | Description | -| ----- | ------ | --------- | -------------- | -| wkdId | string | true | WKD identifier | - -`wkdId` looks like an email address and is formatted as `username@domain.org`. - -**Returns** - -A public key object. - -### keys.fetch.plaintext(keyPlaintext) - -_(async)_ keys.fetch.plaintext(keyPlaintext) - -Parses the `keyPlaintext`. - -**Parameters** - -| Name | Type | Mandatory | Description | -| ------------ | ------ | --------- | ----------------- | -| keyPlaintext | string | true | ASCII key content | - -**Returns** - -A public key object. - -### signatures.verify(uri, [fingerprint], [opts]) - -_(async)_ doip.signatures.verify(signature, [opts]) - -Verifies the identity behind the claims in the provided clear-signed **signature**. - -**Parameters** - -| Name | Type | Mandatory | Description | -| --------- | ------ | --------- | ------------------------- | -| signature | string | true | the clear-sgned signature | -| opts | object | false | options (see below) | - -**Options** - -See [claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts). - -**Returns** - -```json -{ - "errors": [ ... ], - "publicKey": { ... }, - "fingerprint": "...", - "serviceproviderData": { ... } -} -``` diff --git a/docs/doipjs/old.md b/docs/doipjs/old.md deleted file mode 100644 index d3bb3ff..0000000 --- a/docs/doipjs/old.md +++ /dev/null @@ -1,257 +0,0 @@ -# Claim (class) - -## Constructor - -new Claim([uri], [fingerprint]) - -**Parameters** - -| Name | Type | Mandatory | Description | -| ----------- | ------ | --------- | -------------------------------- | -| uri | string | false | the URI to an identity to verify | -| fingerprint | string | false | the fingerprint of the claim | - -## Properties - -### state - -The current state of the Claim object. - -**Values:** - -| Name | Description | -| -------- | ----------------------------------------------------------------- | -| init | The claim has just been initialized | -| matched | The claim has been matched to candidate claim definitions | -| verified | The claim has attempted to verify all candidate claim definitions | - -### matches - -Returns the matches - -## Methods - -### match() - -Verifies the identity behind the provided **uri** using the **fingerprint**. - -**Parameters** - -| Name | Type | Mandatory | Description | -| ----------- | ------ | --------- | -------------------------------- | -| uri | string | true | the URI to an identity to verify | -| fingerprint | string | false | the fingerprint of the claim | -| opts | object | false | options (see below) | - -**Options** - -| Name | Type | Default value | Description | -| ------------------ | ------- | -------------------- | ---------------------------------------------------------------------- | -| returnMatchesOnly | boolean | false | only return matching service providers, do not attempt verification | -| proxyPolicy | string | 'adaptive' | when to use a proxy ['adaptive', 'fallback', 'always', 'never'] | -| doipProxyHostname | string | 'proxy.keyoxide.org' | the hostname of the proxy server | -| twitterBearerToken | string | '' | the Twitter API bearer token used for Twitter verification | -| nitterInstance | string | '' | the domain name of the nitter instance to use for Twitter verification | - -When the `proxyPolicy` option is to `adaptive`, the chosen strategy is -the one suggested by the service provider. - -By default, Twitter accounts are not verified. Either provide a -[Twitter bearer token](https://developer.twitter.com/en/docs/authentication/oauth-2-0/bearer-tokens) -(as `twitterBearerToken`) or the domain name of a Nitter instance (as -`nitterInstance`) to enable Twitter account verification. If both values are -provided, only the Twitter bearer token is used. - -Note that Nitter instances are subject to rate limiting which would instantly -break Twitter account verification. - -**Returns** - -An object with the results of the identity claim verification containing a -boolean named `isVerified` and a -[serviceproviderData](serviceproviderdataobject.md#service-provider-data-object) -object. - -```json -{ - "isVerified": true, - "serviceproviderData": { ... } -} -``` - -If `opts.returnMatchesOnly` is `true`, this function instead returns a list of -service providers matched to the provided `uri`. - -### claims.verify(uriArray, [fingerprint], [opts]) - -_(async)_ doip.claims.verify(array, [fingerprint], [opts]) - -Verifies the identity behind the provided **array of uris** using the **fingerprint**. - -**Parameters** - -| Name | Type | Mandatory | Description | -| ----------- | ------ | --------- | ---------------------------- | -| uriArray | array | true | array of uris | -| fingerprint | string | false | the fingerprint of the claim | -| opts | object | false | options (see below) | - -**Options** - -See [claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts). - -**Returns** - -An array of objects with claim verification results (see -[claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts)). - -### claims.verify(key, [fingerprint], [opts]) - -_(async)_ doip.claims.verify(key, [fingerprint], [opts]) - -Verifies the identity behind the claims contained within the provided -**key** using the **fingerprint**. This key is outputted by the -[keys.fetch.\*()](#keysfetchuriuri) commands. - -**Parameters** - -| Name | Type | Mandatory | Description | -| ----------- | ------ | --------- | ---------------------------- | -| key | object | true | a public key | -| fingerprint | string | false | the fingerprint of the claim | -| opts | object | false | options (see below) | - -**Options** - -See [claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts). - -**Returns** - -An array of objects with claim verification results (see -[claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts)). - -### keys.fetch.uri(uri) - -_(async)_ keys.fetch.uri(uri) - -Fetches a key based on the provided `uri`. This simply serves as a shortcut to -other `keys.fetch.*` commands. - -**Parameters** - -| Name | Type | Mandatory | Description | -| ---- | ------ | --------- | --------------------- | -| uri | string | true | public key identifier | - -Possible formats for `uri`: - -`hkp:FINGERPRINT` ⇒ `keys.fetch.hkp(FINGERPRINT)` -`hkp:FINGERPRINT:KEYSERVER` ⇒ `keys.fetch.hkp(FINGERPRINT, KEYSERVER)` -`hkp:EMAIL` ⇒ `keys.fetch.hkp(EMAIL)` -`hkp:EMAIL:KEYSERVER` ⇒ `keys.fetch.hkp(EMAIL, KEYSERVER)` -`wkd:EMAIL` ⇒ `keys.fetch.wkd(EMAIL)` -`kb:USERNAME:FINGERPRINT` ⇒ `keys.fetch.keybase(USERNAME, FINGERPRINT)` - -**Returns** - -A public key object. - -### keys.fetch.hkp(fingerprint, [keyserverBaseUrl]) - -_(async)_ keys.fetch.hkp(fingerprint, [keyserverBaseUrl]) - -Fetches a key using HKP-compatible key servers. - -**Parameters** - -| Name | Type | Mandatory | Description | -| ---------------- | ------ | --------- | --------------------- | -| fingerprint | string | true | public key identifier | -| keyserverBaseUrl | string | false | base URL of keyserver | - -`keyserverBaseUrl` defaults to `https://keys.openpgp.org/`. - -**Returns** - -A public key object. - -### keys.fetch.hkp(email, [keyserverBaseUrl]) - -_(async)_ keys.fetch.hkp(email, [keyserverBaseUrl]) - -Fetches a key using HKP-compatible key servers. - -**Parameters** - -| Name | Type | Mandatory | Description | -| ---------------- | ------ | --------- | --------------------- | -| email | string | true | public key identifier | -| keyserverBaseUrl | string | false | base URL of keyserver | - -`keyserverBaseUrl` defaults to `https://keys.openpgp.org/`. - -**Returns** - -A public key object. - -### keys.fetch.wkd(wkdId) - -_(async)_ keys.fetch.wkd(wkdId) - -Fetches a key using the WKD protocol. - -**Parameters** - -| Name | Type | Mandatory | Description | -| ----- | ------ | --------- | -------------- | -| wkdId | string | true | WKD identifier | - -`wkdId` looks like an email address and is formatted as `username@domain.org`. - -**Returns** - -A public key object. - -### keys.fetch.plaintext(keyPlaintext) - -_(async)_ keys.fetch.plaintext(keyPlaintext) - -Parses the `keyPlaintext`. - -**Parameters** - -| Name | Type | Mandatory | Description | -| ------------ | ------ | --------- | ----------------- | -| keyPlaintext | string | true | ASCII key content | - -**Returns** - -A public key object. - -### signatures.verify(uri, [fingerprint], [opts]) - -_(async)_ doip.signatures.verify(signature, [opts]) - -Verifies the identity behind the claims in the provided clear-signed **signature**. - -**Parameters** - -| Name | Type | Mandatory | Description | -| --------- | ------ | --------- | ------------------------- | -| signature | string | true | the clear-sgned signature | -| opts | object | false | options (see below) | - -**Options** - -See [claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts). - -**Returns** - -```json -{ - "errors": [ ... ], - "publicKey": { ... }, - "fingerprint": "...", - "serviceproviderData": { ... } -} -``` diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index 056401e..0000000 --- a/docs/index.html +++ /dev/null @@ -1,38 +0,0 @@ - - - - - doip.js - - - - - - -
- - - - - - - - diff --git a/docs/installation.md b/docs/installation.md deleted file mode 100644 index b3a93b8..0000000 --- a/docs/installation.md +++ /dev/null @@ -1,21 +0,0 @@ -# Installation - -Install using **yarn**: - -```bash -yarn add doipjs -``` - -Install using **NPM**: - -```bash -npm install --save doipjs -``` - -Install on website by including the following HTML snippet: - -```html - -``` - -Next step: [quick start (Node.js)](quickstart-nodejs.md) and [quick start (browser)](quickstart-browser.md) diff --git a/docs/proofs.md b/docs/proofs.md deleted file mode 100644 index d851fed..0000000 --- a/docs/proofs.md +++ /dev/null @@ -1,25 +0,0 @@ -# Proofs - -## Definition - -A **proof** is one of the two pieces of data needed to verify an online -identity, the other being a [claim](claims.md). - -Usually, the proof is a JSON document provided by the service provider -containing publicly-available data of the user. This data may contain the -username and a biography. Currently, a lot of service providers are supported -because of the ability to write a proof statement inside a biography or -something similar. Other service providers are supported by entering the proof -statement in a post, in which case said service provider must provide JSON data -for each post. - -With regards to identity verification, **the presence of a claim inside a proof -verifies that claim.** - -See [claims](claims.md) for details on how proofs and claims are -(programmatically) related to each other. - -A proof can also be a text of any length. This changes nothing about the -definition above. It only means the search for the claim is simpler: no -traversing a JSON document, just find the claim inside the text and the claim is -verified. diff --git a/docs/quickstart-browser.md b/docs/quickstart-browser.md deleted file mode 100644 index d94423a..0000000 --- a/docs/quickstart-browser.md +++ /dev/null @@ -1,32 +0,0 @@ -# Quick start (browser) - -Basic example: - -```javascript -const verifyIdentity = async (url, fp) => { - const claim = new doip.Claim(url, fp) - claim.match() - await claim.verify() - console.log(claim.result) -} -verifyIdentity('dns:doip.rocks', '9f0048ac0b23301e1f77e994909f6bd6f80f485d') -``` - -This snippet works en will verify the [doip.rocks](https://doip.rocks) domain as -linked to Yarmo's cryptographic key using the [dns](serviceproviders/dns.md) -service provider. - -Please note you need to include the -[openpgpjs](https://github.com/openpgpjs/openpgpjs) library: - -```html - -``` - -## Twitter account verification - -By default, Twitter accounts verification has to be enabled by either having a -Twitter developer account or providing a Nitter instance domain. - -Please refer to the -[API documentation](/#/api?id=claimsverifyuri-fingerprint-opts). diff --git a/docs/quickstart-nodejs.md b/docs/quickstart-nodejs.md deleted file mode 100644 index 00b993f..0000000 --- a/docs/quickstart-nodejs.md +++ /dev/null @@ -1,27 +0,0 @@ -# Quick start (Node.js) - -Basic example: - -```javascript -const doip = require('doip') - -const verifyIdentity = async (url, fp) => { - const claim = new doip.Claim(url, fp) - claim.match() - await claim.verify() - console.log(claim.result) -} -verifyIdentity('dns:doip.rocks', '9f0048ac0b23301e1f77e994909f6bd6f80f485d') -``` - -This snippet works en will verify the [doip.rocks](https://doip.rocks) domain as -linked to Yarmo's cryptographic key using the [dns](serviceproviders/dns.md) -service provider. - -## Twitter account verification - -By default, Twitter accounts verification has to be enabled by either having a -Twitter developer account or providing a Nitter instance domain. - -Please refer to the -[API documentation](/#/api?id=claimsverifyuri-fingerprint-opts). diff --git a/docs/serviceproviderdataobject.md b/docs/serviceproviderdataobject.md deleted file mode 100644 index 9c06a05..0000000 --- a/docs/serviceproviderdataobject.md +++ /dev/null @@ -1,169 +0,0 @@ -# Service provider data object - -## Overview - -The object returned by any service provider has the following layout: - -```json -{ - "serviceprovider": { - "type": "web", - "name": "awesome-service" - }, - "profile": { - "display": "Alice", - "uri": "https://domain.org/users/Alice", - "qr": null - }, - "proof": { - "uri": "https://domain.org/users/Alice.json", - "fetch": null, - "useProxy": false, - "format": "json" - }, - "claim": { - "fingerprint": "13ec664f5e0c3e4ebad8b7441adbf09217175f75", - "format": "uri", - "path": ["user", "cryptographicKeys"], - "relation": "oneOf" - }, - "customRequestHandler": null -} -``` - -## serviceprovider.type - -``` -Type: string -Values: web, communication -Mandatory: true -``` - -Currently, only two types of service providers are supported: - -- `web`: traditional website platforms -- `communication`: platforms for interpersonal communication - -## serviceprovider.name - -``` -Type: string -Values: * -Mandatory: true -``` - -The name of the service provider (or protocol): `dns`, `xmpp`, `gitea`, `fediverse`, etc. - -## profile.display - -``` -Type: string -Values: * -Mandatory: true -``` - -The account's name to display. - -## profile.uri - -``` -Type: string -Values: * -Mandatory: true -``` - -The URI/URL to the profile page of the account. - -## profile.qr - -``` -Type: string | null -Values: * -Mandatory: true -``` - -A QR link related to the profile to be displayed **if and only if** the identity proof is verified. - -## proof.uri - -``` -Type: string -Values: * -Mandatory: true -``` - -The URI to the JSON/text data that holds the proof verifying the claim. - -## proof.fetch - -``` -Type: string | null -Values: * -Mandatory: true -``` - -If not `null`, the URI to the JSON/text data that holds the proof verifying the claim to be fetched solely by a machine. - -In some cases, we need to consider two separate URIs for proof verification. It could be that an identity proof is stored in a post. In such a case, `proof.uri` should be the URL to that post that can be verified by a human and `proof.fetch` should be the URL to the JSON data associated to that post. - -## claim.fingerprint - -``` -Type: string | null -Values: * -Mandatory: true -``` - -The fingerprint of the claim to verify against the proof. If `null`, the verification itself is skipped. - -## claim.format - -``` -Type: string -Values: uri, message, fingerprint -Mandatory: true -``` - -The format in which the claim's fingerprint is expected to be found in the proof. There are three supported claim formats: - -- `uri`: the claim is formulated as `openpgp4fpr:FINGERPRINT` -- `message`: the claim is formulated as `[Verifying my OpenPGP key: openpgp4fpr:FINGERPRINT]` -- `fingerprint`: the claim is formulated as `FINGERPRINT` - -## claim.path - -``` -Type: array | null -Values: * -Mandatory: true -``` - -The path inside the JSON proof data that leads to the field where the claim's fingerprint is expected to be found. Each field is inputted as a string appended to the array. When a certain field in the JSON data contains an array, this level will not get an input in `claim.path`: arrays are to be automatically iterated over. - -If the proof data is text based, this field is ignored and its value should be set to `null`. - -See [Claims](claims.md) for examples on how this works. - -## claim.relation - -``` -Type: string -Values: contains, equals, oneOf -Mandatory: true -``` - -How the claim relates to the proof. There are three supported claim relations: - -- `contains`: the proof is a long text containing the claim -- `equals`: the proof is equal to the claim -- `oneOf`: the proof is an array of string, one of which is the claim - -## customRequestHandler - -``` -Type: function | null -Values: * -Mandatory: false -``` - -A function that will be called to handle the actual request to obtain the proof data. Most service providers will not need this and will use the default internal request handler to fetch the JSON/text data containing the proof. Service providers that need more than a single simple HTTP GET request must provide their own `customRequestHandler`. diff --git a/docs/serviceproviders.md b/docs/serviceproviders.md deleted file mode 100644 index 7aaabb2..0000000 --- a/docs/serviceproviders.md +++ /dev/null @@ -1,19 +0,0 @@ -# Service providers - -Currently, the following service providers are supported: - -- dev.to ([documentation](serviceproviders/devto.md) - [official website](https://dev.to/)) -- discourse ([documentation](serviceproviders/discourse.md) - [official website](https://www.discourse.org/)) -- dns ([documentation](serviceproviders/dns.md)) -- fediverse ([documentation](serviceproviders/fediverse.md)) -- gitea ([documentation](serviceproviders/gitea.md) - [official website](https://gitea.io/)) -- github ([documentation](serviceproviders/github.md) - [official website](https://github.com/)) -- gitlab ([documentation](serviceproviders/gitlab.md) - [official website](https://about.gitlab.com/)) -- hackernews ([documentation](serviceproviders/hackernews.md) - [official website](https://news.ycombinator.com/)) -- liberapay ([documentation](serviceproviders/liberapay.md) - [official website](https://liberapay.com/)) -- lobste.rs ([documentation](serviceproviders/lobsters.md) - [official website](https://lobste.rs/)) -- mastodon ([documentation](serviceproviders/mastodon.md) - [official website](https://joinmastodon.org/)) -- owncast ([documentation](serviceproviders/owncast.md) - [official website](https://owncast.online/)) -- reddit ([documentation](serviceproviders/reddit.md) - [official website](https://www.reddit.com/)) -- twitter ([documentation](serviceproviders/twitter.md) - [official website](https://twitter.com/home)) -- xmpp ([documentation](serviceproviders/xmpp.md) - [official website](https://xmpp.org/)) diff --git a/docs/serviceproviders/devto.md b/docs/serviceproviders/devto.md deleted file mode 100644 index fcbd21b..0000000 --- a/docs/serviceproviders/devto.md +++ /dev/null @@ -1,21 +0,0 @@ -# dev.to - -## Proof - -Proofs are defined as posts and should contain the following information: - -``` -This is an OpenPGP proof that connects [my OpenPGP key](https://keyoxide.org/FINGERPRINT) to [this dev.to account](https://dev.to/USERNAME). For details check out https://keyoxide.org/guides/openpgp-proofs - -[Verifying my OpenPGP key: openpgp4fpr:FINGERPRINT] -``` - -Make sure to replace `FINGERPRINT` and `USERNAME`. - -## Claim - -``` -https://dev.to/USERNAME/POST_TITLE -``` - -Make sure to replace `USERNAME` and `POST_TITLE`. diff --git a/docs/serviceproviders/discourse.md b/docs/serviceproviders/discourse.md deleted file mode 100644 index ef4bef8..0000000 --- a/docs/serviceproviders/discourse.md +++ /dev/null @@ -1,21 +0,0 @@ -# discourse - -## Proof - -Proofs are defined by including the following information in the **About me**: - -``` -This is an OpenPGP proof that connects my OpenPGP key to this Discourse account. For details check out https://keyoxide.org/guides/openpgp-proofs - -[Verifying my OpenPGP key: openpgp4fpr:FINGERPRINT] -``` - -Make sure to replace `FINGERPRINT`. - -## Claim - -``` -https://DOMAIN/u/USERNAME -``` - -Make sure to replace `DOMAIN` and `USERNAME`. diff --git a/docs/serviceproviders/dns.md b/docs/serviceproviders/dns.md deleted file mode 100644 index a8f12f6..0000000 --- a/docs/serviceproviders/dns.md +++ /dev/null @@ -1,19 +0,0 @@ -# dns - -## Proof - -Proofs are defined by adding a **TXT** record to the DNS records: - -``` -openpgp4fpr:FINGERPRINT -``` - -Make sure to replace `FINGERPRINT`. - -## Claim - -``` -dns:DOMAIN -``` - -Make sure to replace `DOMAIN`. diff --git a/docs/serviceproviders/fediverse.md b/docs/serviceproviders/fediverse.md deleted file mode 100644 index c6fea54..0000000 --- a/docs/serviceproviders/fediverse.md +++ /dev/null @@ -1,22 +0,0 @@ -# fediverse - -Fediverse refers to the network of ActivityPub-compatible servers. - -## Proof - -Proofs are defined by adding the following information to the **Bio** or -similar field: - -``` -[Verifying my OpenPGP key: openpgp4fpr:FINGERPRINT] -``` - -Make sure to replace `FINGERPRINT`. - -## Claim - -``` -https://DOMAIN/users/USERNAME -``` - -Make sure to replace `DOMAIN` and `USERNAME`. diff --git a/docs/serviceproviders/gitea.md b/docs/serviceproviders/gitea.md deleted file mode 100644 index 0af021c..0000000 --- a/docs/serviceproviders/gitea.md +++ /dev/null @@ -1,20 +0,0 @@ -# gitea - -## Proof - -Proofs are defined by creating a public repository `gitea_proof` and setting the -description to: - -``` -[Verifying my OpenPGP key: openpgp4fpr:FINGERPRINT] -``` - -Make sure to replace `FINGERPRINT`. - -## Claim - -``` -https://DOMAIN/USERNAME/gitea_proof -``` - -Make sure to replace `DOMAIN` and `USERNAME`. diff --git a/docs/serviceproviders/github.md b/docs/serviceproviders/github.md deleted file mode 100644 index d0dc6ff..0000000 --- a/docs/serviceproviders/github.md +++ /dev/null @@ -1,22 +0,0 @@ -# github - -## Proof - -Proofs are defined by creating a public gist and a file `openpgp.md` with the -following information: - -``` -This is an OpenPGP proof that connects [my OpenPGP key](https://keyoxide.org/FINGERPRINT) to [this Github account](https://github.com/USERNAME). For details check out https://keyoxide.org/guides/openpgp-proofs - -[Verifying my OpenPGP key: openpgp4fpr:FINGERPRINT] -``` - -Make sure to replace `FINGERPRINT` and `USERNAME`. - -## Claim - -``` -https://gist.github.com/USERNAME/GIST_ID -``` - -Make sure to replace `USERNAME` and `GIST_ID`. diff --git a/docs/serviceproviders/gitlab.md b/docs/serviceproviders/gitlab.md deleted file mode 100644 index 3e9bfe8..0000000 --- a/docs/serviceproviders/gitlab.md +++ /dev/null @@ -1,20 +0,0 @@ -# gitlab - -## Proof - -Proofs are defined by creating a public project with slug `gitea_proof` and -setting the description to: - -``` -[Verifying my OpenPGP key: openpgp4fpr:FINGERPRINT] -``` - -Make sure to replace `FINGERPRINT`. - -## Claim - -``` -https://DOMAIN/USERNAME/gitlab_proof -``` - -Make sure to replace `DOMAIN` and `USERNAME`. diff --git a/docs/serviceproviders/hackernews.md b/docs/serviceproviders/hackernews.md deleted file mode 100644 index 8d62b96..0000000 --- a/docs/serviceproviders/hackernews.md +++ /dev/null @@ -1,21 +0,0 @@ -# hackernews - -## Proof - -Proofs are defined by adding the following information to the **about**: - -``` -This is an OpenPGP proof that connects my OpenPGP key to this Hackernews account. For details check out https://keyoxide.org/guides/openpgp-proofs - -[Verifying my OpenPGP key: openpgp4fpr:FINGERPRINT] -``` - -Make sure to replace `FINGERPRINT`. - -## Claim - -``` -https://news.ycombinator.com/user?id=USERNAME -``` - -Make sure to replace `USERNAME`. diff --git a/docs/serviceproviders/liberapay.md b/docs/serviceproviders/liberapay.md deleted file mode 100644 index bc25e19..0000000 --- a/docs/serviceproviders/liberapay.md +++ /dev/null @@ -1,19 +0,0 @@ -# liberapay - -## Proof - -Proofs are defined by adding the following information to a **Statement**: - -``` -[Verifying my OpenPGP key: openpgp4fpr:FINGERPRINT] -``` - -Make sure to replace `FINGERPRINT`. - -## Claim - -``` -https://liberapay.com/USERNAME -``` - -Make sure to replace `USERNAME`. diff --git a/docs/serviceproviders/lobsters.md b/docs/serviceproviders/lobsters.md deleted file mode 100644 index 6b70550..0000000 --- a/docs/serviceproviders/lobsters.md +++ /dev/null @@ -1,21 +0,0 @@ -# lobste.rs - -## Proof - -Proofs are defined by adding the following information to the **About**: - -``` -This is an OpenPGP proof that connects my OpenPGP key to this Lobste.rs account. For details check out https://keyoxide.org/guides/openpgp-proofs - -[Verifying my OpenPGP key: openpgp4fpr:FINGERPRINT] -``` - -Make sure to replace `FINGERPRINT`. - -## Claim - -``` -https://lobste.rs/u/USERNAME -``` - -Make sure to replace `USERNAME`. diff --git a/docs/serviceproviders/mastodon.md b/docs/serviceproviders/mastodon.md deleted file mode 100644 index 35001e6..0000000 --- a/docs/serviceproviders/mastodon.md +++ /dev/null @@ -1,14 +0,0 @@ -# mastodon - -## Proof - -Proofs are defined by adding an item under `Profile metadata` with `OpenPGP` as -label and the fingerprint as value. - -## Claim - -``` -https://DOMAIN/@USERNAME -``` - -Make sure to replace `DOMAIN` and `USERNAME`. diff --git a/docs/serviceproviders/owncast.md b/docs/serviceproviders/owncast.md deleted file mode 100644 index a980da3..0000000 --- a/docs/serviceproviders/owncast.md +++ /dev/null @@ -1,27 +0,0 @@ -# owncast - -## Proof - -Proofs are defined by adding the following information to the **config.yaml**: - -``` - - platform: keyoxide - url: https://keyoxide.org/FINGERPRINT -``` - -If you use WKD, you could instead add: - -``` - - platform: keyoxide - url: https://keyoxide.org/wkd/EMAIL?openpgp4fpr=FINGERPRINT -``` - -Make sure to replace `FINGERPRINT`. - -## Claim - -``` -https://DOMAIN -``` - -Make sure to replace `DOMAIN`. diff --git a/docs/serviceproviders/reddit.md b/docs/serviceproviders/reddit.md deleted file mode 100644 index 4665e8b..0000000 --- a/docs/serviceproviders/reddit.md +++ /dev/null @@ -1,21 +0,0 @@ -# reddit - -## Proof - -Proofs are defined as posts and should contain the following information: - -``` -This is an OpenPGP proof that connects my OpenPGP key to this Reddit account. For details check out https://keyoxide.org/guides/openpgp-proofs - -[Verifying my OpenPGP key: openpgp4fpr:FINGERPRINT] -``` - -Make sure to replace `FINGERPRINT`. - -## Claim - -``` -https://reddit.com/user/USERNAME/comments/POST_ID/POST_TITLE -``` - -Make sure to replace `USERNAME`, `POST_ID` and `POST_TITLE`. diff --git a/docs/serviceproviders/twitter.md b/docs/serviceproviders/twitter.md deleted file mode 100644 index 7a46065..0000000 --- a/docs/serviceproviders/twitter.md +++ /dev/null @@ -1,21 +0,0 @@ -# twitter - -## Proof - -Proofs are defined as tweets and should contain the following information: - -``` -This is an OpenPGP proof that connects my OpenPGP key to this Twitter account. For details check out https://keyoxide.org/guides/openpgp-proofs - -[Verifying my OpenPGP key: openpgp4fpr:FINGERPRINT] -``` - -Make sure to replace `FINGERPRINT`. - -## Claim - -``` -https://twitter.com/USERNAME/status/TWEET_ID -``` - -Make sure to replace `USERNAME` and `TWEET_ID`. diff --git a/docs/serviceproviders/xmpp.md b/docs/serviceproviders/xmpp.md deleted file mode 100644 index a011ff4..0000000 --- a/docs/serviceproviders/xmpp.md +++ /dev/null @@ -1,29 +0,0 @@ -# xmpp - -## Proof - -Proofs are defined by adding the following information to the **About** section -of the profile's vCard information using a client that support editing that -information: - -``` -This is an OpenPGP proof that connects my OpenPGP key to this XMPP account. For details check out https://keyoxide.org/guides/openpgp-proofs - -[Verifying my OpenPGP key: openpgp4fpr:FINGERPRINT] -``` - -Make sure to replace `FINGERPRINT`. - -## Claim - -``` -xmpp:XMPP_ID -``` - -or with OMEMO: - -``` -xmpp:XMPP_ID?omemo-sid-OMEMO_DEVICE_ID=OMEMO_FINGERPRINT&... -``` - -Make sure to replace `XMPP_ID`, `OMEMO_DEVICE_ID` and `OMEMO_FINGERPRINT`. diff --git a/docs/terminology.md b/docs/terminology.md deleted file mode 100644 index e2f0d3d..0000000 --- a/docs/terminology.md +++ /dev/null @@ -1,128 +0,0 @@ -# Terminology - -## Claim - -A piece of data that is expected to be contained with the [proof](#proof). When -found, the claim—and the identity associated with the claim—is -verified. Within the context of this project, a claim is always the fingerprint -of an [OpenPGP](#openpgp) [cryptographic key](#cryptographic-key), but formatted -in different ways depending on the [service provider](#service-provider). - -For more detailed information, please refer to [Claims](claims.md). - -## Cryptographic key - -According to [Wikipedia](): - -> [...] a piece of information (a parameter) that determines the functional -> output of a cryptographic algorithm. - -Cryptographic keys can be used to encrypt/decrypt data and verify digital -signatures. - -Within the context of this project, we can view cryptographic keys as documents -that everyone can read but only one person can edit. This makes it the perfect -candidate to serve as vessel for [decentralized](#decentralized) -[identity](#identity) [claims](#claim). - -## Decentralized - -A model for interaction between computers or nodes in a network. Its -distinguishing feature is that this model does not rely on a central authority, -unlike traditional centralized models that are used by Facebook, Google and all -other privacy-invading corporations. - -A core outcome of choosing a decentralized model is that it gives the user -**sovereignty** over their data, instead of giving all the power to the central -node. This means that [service providers](#service-provider) are **allowed** to -access a user's data, courtesy of that user. It also implies that that user can -choose to block access of any [service provider](#service-provider) at any -point in time and move to a different [service provider](#service-provider). In -this new model, [service providers](#service-provider) need to fight for access -to that user data and any user-compromising service can simply be left behind. - -Within the context of this project, you store your identity claims inside a -[cryptographic key](#cryptographic-key). You can then use any compatible client -software or website to verify these claims. And if you don't like that -particular client software or website, you just choose to use a different one. - -## DOIP - -A protocol that describes how interactions between -[cryptographic keys](#cryptographic-key) and -[service providers](#service-provider) can be used to the advantage of the -people on the internet and allow them to publicly verify their online -[identity](#identity) in a secure manner that is resistant to impersonation. - -Currently, this documentation is the most elaborate description of the inner -workings of the DOIP protocol. Drafting a standard is planned. - -## Fingerprint - -A string of hexadecimal characters that uniquely identifies a -[cryptographic key](#cryptographic-key). - -Within the context of this project, they are used to link a [profile](#profile) -page back to a single [cryptographic key](#cryptographic-key) by mentioning this -fingerprint anywhere on the [profile](#profile) page, like inside a biography. - -## Identity - -Within the context of this project, identity refers to a person's -**digital online identity**, the collection of [profiles](#profile) that a -person holds and that partially accounts for a person's online activity. A -physical person can have multiple online identities, for example a private -identity and a work-related identity. - -That collection of [profiles](#profile) can be stored inside -[cryptographic key](#cryptographic-key). - -## OpenPGP - -A standard for [cryptographic keys](#cryptographic-key) defined by -[RFC 4880](https://tools.ietf.org/html/rfc4880). - -## Profile - -A piece of data that is created by a physical person but stored and managed on -the servers of a [service provider](#service-provider). While a person does not -own that data, it does define them as part of their online -[identity](#identity). - -Usually, a [service provider](#service-provider) generates a profile page based -on that user data that displays basic information like a username, an avatar and -a biography. - -## Proof - -A piece of data provided a [service provider](#service-provider) that contains -at least some of the data that it stores on a specific user. That piece of data -also is publicly available to all, usually as a JSON document. - -A [claim](#claim) expects the proof to contain a certain statement. For -[DOIP](#doip), this statement is a [fingerprint](#fingerprint). - -For more detailed information, please refer to [Proofs](proofs.md). - -## Proxy - -A piece of software that handles the request for proof instead of the original -piece of software that called the proxy. This is useful when doip.js is used in -browsers. Some [service providers](#service-provider) do not allow their public -data to be accessed by other websites (so called CORS restrictions, -[Wikipedia](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)) but -requests from non-browser origin are accepted and fulfilled. Doip.js when used -in a browser will let proxy servers handle their requests for them to eliminate -this friction. - -Doip.js requires a proxy server to run the open source -[doip-proxy software](https://codeberg.org/keyoxide/doip-proxy). - -## Service provider - -A company, organization or protocol that stores [profiles](#profile) submitted -by their users. The data associated to those [profiles](#profile) should at -least be partially made publicly available to allow identity verification using -[DOIP](#doip). - -For more information, please refer to [Service providers](serviceproviders.md).