doipjs/docs/serviceproviderdataobject.md

Service provider data object

Overview

The object returned by any service provider has the following layout:

{
  "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 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.