Add API spec for VC-issuer

docs/vc-spec.md

@@ -1,6 +1,163 @@
-# II Verifiable Credential Spec
+# II Verifiable Credential Spec (MVP)
+
+
+## Issuer API
+
+This section describes the (Candid) interface to be implemented by an issuer of verifiable credentials on the IC.
+This interface is used by the II-canister during attribute sharing flow (cf. [flow description](https://github.com/dfinity/wg-identity-authentication/blob/main/topics/attribute-sharing.md))
+An example implementation of the interface is given in [demos/vc_issuer](../demos/vc_issuer).
+
+The Candid interface is as follows, and the subsequent sections describe the
+services and the corresponding messages in more detail.
+
+```candid
+type CredentialSpec = record { info : text };
+type GetCredentialRequest = record {
+    signed_id_alias : SignedIdAlias;
+    prepared_context : opt blob;
+    credential_spec : CredentialSpec;
+};
+type GetCredentialResponse = variant {
+    Ok : IssuedCredentialData;
+    Err : IssueCredentialError
+};
+type Icrc21ConsentInfo = record { consent_message : text; language : text };
+type Icrc21ConsentMessageRequest = record {
+    arg : vec nat8;
+    method : text;
+    preferences : Icrc21ConsentPreferences;
+};
+type Icrc21ConsentMessageResponse = variant {
+    Ok : Icrc21ConsentInfo;
+    Err : Icrc21Error;
+};
+type Icrc21ConsentPreferences = record { language : text };
+type Icrc21Error = variant {
+    GenericError : Icrc21ErrorInfo;
+    MalformedCall : Icrc21ErrorInfo;
+    NotSupported : Icrc21ErrorInfo;
+    Forbidden : Icrc21ErrorInfo;
+};
+type Icrc21ErrorInfo = record { description : text; error_code : nat64 };
+type IssueCredentialError = variant {
+    Internal : text;
+    SignatureNotFound : text;
+    InvalidIdAlias : text;
+    UnauthorizedSubject : text;
+    UnknownSubject : text;
+};
+type IssuedCredentialData = record { vc_jws : text };
+type PrepareCredentialRequest = record {
+    signed_id_alias : SignedIdAlias;
+    credential_spec : CredentialSpec;
+};
+type PrepareCredentialResponse = variant {
+    Ok : PreparedCredentialData;
+    Err : IssueCredentialError;
+};
+type PreparedCredentialData = record { prepared_context : opt blob };
+type SignedIdAlias = record {
+    credential_jws : text;
+    id_alias : principal;
+    id_dapp : principal;
+};
+service : {
+    consent_message : (Icrc21ConsentMessageRequest) -> (Icrc21ConsentMessageResponse);
+    get_credential : (GetCredentialRequest) -> (GetCredentialResponse) query;
+    prepare_credential : (PrepareCredentialRequest) -> (PrepareCredentialResponse);
+}
+```
+
+### 1: Consent Message
+
+In the attribute sharing flow a user must approve the issuance of a verifiable
+credential by an issuer, and this happens by approving a human-readable consent message from the issuer.
+See [ICRC-21](https://github.com/dfinity/wg-identity-authentication/blob/main/topics/icrc_21_consent_msg.md) for more detail.
+
+Identity provider requests the consent message via `Icrc21ConsentMessageRequest`,
+and upon successful response displays the consent message from `Icrc21ConsentInfo` to the user.
+
+### 2: Prepare Credential
+
+Preparation of a credential involves checking the validity of the request,
+and upon success, preparation of the actual credential requested by the user.
+
+```candid
+service : {
+  prepare_credential : (PrepareCredentialRequest) -> (PrepareCredentialResponse);
+};
+
+type PrepareCredentialRequest = record {
+    signed_id_alias : SignedIdAlias;
+    credential_spec : CredentialSpec;
+};
+
+type SignedIdAlias = record {
+    credential_jws : text;
+    id_alias : principal;
+    id_dapp : principal;
+};
+
+type PrepareCredentialRequest = record {
+    signed_id_alias : SignedIdAlias;
+    credential_spec : CredentialSpec;
+};
+
+type PrepareCredentialResponse = variant {
+    Ok : PreparedCredentialData;
+    Err : IssueCredentialError;
+};
+
+type PreparedCredentialData = record { prepared_context : opt blob };
+```
+
+Specifically, the issuer checks via `prepared_id_alias.credential_jws` that user identified via `id_dapp` on the issuer
+side can be identified using `id_alias` for the purpose of attribute sharing, and that the credential
+described by `credential_spec` does apply to the user.  When these checks are successful, the issuer
+prepares and returns a context in `PreparedCredentialData.prepared_context` (if any).  The returned prepared context is then 
+passed back to the issuer in a subsequent `get_credential`-call (see below).
+
+**NOTE:** 
+The value of `prepared_context` is basically used to transfer information between `prepare_credential`
+and `get_credential` steps, and it is totally up to the issuer to decide on the content of 
+that field.  That is, the issuer creates `prepared_context`, and is the only entity that
+consumes it.
+
+
+### 3: Get Credential
+
+`get_credential`-service issues the actual credential requested by the user.
+
+```candid
+service : {
+  get_credential : (GetCredentialRequest) -> (GetCredentialResponse) query;
+};
+
+type GetCredentialRequest = record {
+    signed_id_alias : SignedIdAlias;
+    prepared_context : opt blob;
+    credential_spec : CredentialSpec;
+};
+type GetCredentialResponse = variant {
+    Ok : IssuedCredentialData;
+    Err : IssueCredentialError;
+};
+type IssuedCredentialData = record { vc_jws : text };
+
+```
+
+`GetCredentialRequest` should contain the same parameters as `PrepareCredentialRequest`, plus the
+`prepared_context`-value  returned by `prepare_credential`, if any.
+The issuer performs the same checks as during the `prepare_credential`-call,
+plus verify that `prepared_context` is consistent with the other parameters.
+
+Upon successful checks, issuer returns the signed credential in JWS-format.
+
+
+##  Identity Provider API 
 
-## Window Post Message Interface
+This section describes the _Window Post Message_-interface implemented by the identity provider (Internet Idenity).
+This interface is used by a Relying Party during attribute sharing flow (cf. [flow description](https://github.com/dfinity/wg-identity-authentication/blob/main/topics/attribute-sharing.md))
 
 ### 1: Load II in a new window