Mirrors/doipjs
1
0
Fork 1
mirror of https://codeberg.org/keyoxide/doipjs.git synced 2024-12-22 14:39:28 -07:00
Code Issues Projects Releases Packages Wiki Activity

Remove docs

Browse source
This commit is contained in:
Yarmo Mackenbach 2021-04-20 16:35:28 +02:00
parent 205c978980
commit a1b03c3350
No known key found for this signature in database
GPG key ID: 37367F4AF4087AD1
33 changed files with 0 additions and 2032 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

37
docs/README.md
View file

@ -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/).

10
docs/_coverpage.md
View file

@ -1,10 +0,0 @@
# doip.js <small>0.12.0</small>
<img src="doip.png" width="120">
Decentralized OpenPGP Identity Proofs library in Node.js
[Source code](https://codeberg.org/keyoxide/doipjs)
[Getting started](#doipjs)
![color](#c9beff)

39
docs/_sidebar.md
View file

@ -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)

295
docs/changelog.md
View file

@ -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

147
docs/claims.md
View file

@ -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"
]
}
}
```

102
docs/doip.md
View file

@ -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&mdash;in a way&mdash;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&mdash;and their data!&mdash;with them.
> Yeah, but&hellip; 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**.

BIN
docs/doip.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 12 KiB

129
docs/doipjs/class_claim.md
View file

@ -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<Object>}`
## 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)).

239
docs/doipjs/module_keys.md
View file

@ -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` &rArr; `keys.fetch.hkp(FINGERPRINT)`
`hkp:FINGERPRINT:KEYSERVER` &rArr; `keys.fetch.hkp(FINGERPRINT, KEYSERVER)`
`hkp:EMAIL` &rArr; `keys.fetch.hkp(EMAIL)`
`hkp:EMAIL:KEYSERVER` &rArr; `keys.fetch.hkp(EMAIL, KEYSERVER)`
`wkd:EMAIL` &rArr; `keys.fetch.wkd(EMAIL)`
`kb:USERNAME:FINGERPRINT` &rArr; `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": { ... }
}
```

257
docs/doipjs/old.md
View file

@ -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` &rArr; `keys.fetch.hkp(FINGERPRINT)`
`hkp:FINGERPRINT:KEYSERVER` &rArr; `keys.fetch.hkp(FINGERPRINT, KEYSERVER)`
`hkp:EMAIL` &rArr; `keys.fetch.hkp(EMAIL)`
`hkp:EMAIL:KEYSERVER` &rArr; `keys.fetch.hkp(EMAIL, KEYSERVER)`
`wkd:EMAIL` &rArr; `keys.fetch.wkd(EMAIL)`
`kb:USERNAME:FINGERPRINT` &rArr; `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": { ... }
}
```

38
docs/index.html
View file

@ -1,38 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>doip.js</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta
name="description"
content="doip.js documentation, Node.js library for Decentralized OpenPGP Identity Proofs"
/>
<meta
name="viewport"
content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"
/>
<link
rel="stylesheet"
href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css"
/>
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
name: 'doip.js',
themeColor: '#8C76F2',
coverpage: true,
loadSidebar: true,
maxLevel: 4,
subMaxLevel: 2,
}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/external-script.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify-copy-code"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1.22.0/components/prism-bash.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1.22.0/components/prism-json.min.js"></script>
</body>
</html>

21
docs/installation.md
View file

@ -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
<script src="https://cdn.jsdelivr.net/npm/doipjs@0.12.0/dist/doip.min.js"></script>
```
Next step: [quick start (Node.js)](quickstart-nodejs.md) and [quick start (browser)](quickstart-browser.md)

25
docs/proofs.md
View file

@ -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.

32
docs/quickstart-browser.md
View file

@ -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
<script src="https://cdn.jsdelivr.net/npm/openpgp/dist/openpgp.min.js"></script>
```
## 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).

27
docs/quickstart-nodejs.md
View file

@ -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).

169
docs/serviceproviderdataobject.md
View file

@ -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`.

19
docs/serviceproviders.md
View file

@ -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/))

21
docs/serviceproviders/devto.md
View file

@ -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`.

21
docs/serviceproviders/discourse.md
View file

@ -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`.

19
docs/serviceproviders/dns.md
View file

@ -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`.

22
docs/serviceproviders/fediverse.md
View file

@ -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`.

20
docs/serviceproviders/gitea.md
View file

@ -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`.

22
docs/serviceproviders/github.md
View file

@ -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`.

20
docs/serviceproviders/gitlab.md
View file

@ -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`.

21
docs/serviceproviders/hackernews.md
View file

@ -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`.

19
docs/serviceproviders/liberapay.md
View file

@ -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`.

21
docs/serviceproviders/lobsters.md
View file

@ -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`.

14
docs/serviceproviders/mastodon.md
View file

@ -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`.

27
docs/serviceproviders/owncast.md
View file

@ -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`.

21
docs/serviceproviders/reddit.md
View file

@ -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`.

21
docs/serviceproviders/twitter.md
View file

@ -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`.

29
docs/serviceproviders/xmpp.md
View file

@ -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`.

128
docs/terminology.md
View file

@ -1,128 +0,0 @@
# Terminology
## Claim
A piece of data that is expected to be contained with the [proof](#proof). When
found, the claim&mdash;and the identity associated with the claim&mdash;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](<https://en.wikipedia.org/wiki/Key_(cryptography)>):
> [...] 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).