docs: add introduction to specification

README.md

@@ -16,49 +16,12 @@
 
 ### Why
 
-<!--
-
-Here I think we want to write about how the GDPR or we in the EdTech industry
-place a particulary high value on the data privacy of children.
-Children are of particular importance - they have so much to learn!
-
-Why should EdTech's be interested in this specification?
-... something about the benefits of implementing specs
-... something about lower burden of GDPR compliance
-
--->
-
-#### _Draft 1_
-
-Children have a lot to learn, so we want to offer them digital learning
-experiences in the form of apps.
-
-In order to have a productive learning experience,
-their teachers need to be able to identify the work of their students.
-This is easiest when the teacher can see their students identified by the same
-name they use in all apps and, in particular, the name used in the classroom.
-
-However, as app creators we have a special duty to protect the personal data
-of children. The simplest way to do that is to not receive it.
-
-#### _Draft 2_
-
-Per the [GDPR][GDPR],
-children merit specific protection with regard to their personal.
-The best way to protect that data is not to process it.
-
-We want to have a simple and common way for teachers to recognise their
-students without putting their data at risk.
-
-[GDPR]: https://eur-lex.europa.eu/eli/reg/2016/679/oj
-
-#### _Draft 3_
-
-As app creators we have a special duty to protect the personal data of
-children. The simplest way to do that is to not receive it.
+As app creators, we have a profound responsibility to safeguard the personal
+data of children. The most effective way to protect it is to avoid collecting
+it altogether.
 
-We want to have a simple and common way for teachers to recognise their
-students without putting their data at risk.
+Our goal is to provide a simple and standardized method for teachers to identify
+their students without compromising their data security.
 
 ### What
 
@@ -68,12 +31,10 @@ names without revealing those names to the creator of the app.
 
 We name it client-side depseudonymisation or simply d16n.
 
-D16N refers to the Depseudonymisation process used in integrations, where
+D16N refers to the depseudonymisation process used in integrations, where
 pseudonyms (abstract IDs) are exchanged instead of clear user names. This
 functionality allows a user's browser to communicate directly with IDP
-servers to resolve these IDs into identifiable names. D16N enhances privacy by
-ensuring that user identities remain protected during data exchanges,
-particularly in educational contexts where sensitive information is involved.
+servers to resolve these IDs into identifiable names.
 
 ### For Whom
 

diagrams/connection.puml

@@ -8,8 +8,8 @@ rectangle RelyingParty as "Relying Party" #D9D9D9 {
   rectangle Server #85BCF0
 }
 
-IDP <-[#85BCF0]down-> Server : Authorization
-IDP -[#FAC711]left-> Client : Clear Names
+IDP "Authorization" <-[#85BCF0]down-> Server
+IDP "Clear Names" -[#FAC711]left-> Client
 Client <-[#85BCF0]right- Server : Access Token
 
  legend

spec/d16n-v1_0.adoc

@@ -17,7 +17,19 @@ This is written in the context of offering learning tools to children and their
 
 == Introduction
 
-// TODO: write introduction
+It has become common to develop apps that make use of single sign-on (SSO) in various forms to provide functionality in institutional or educational settings
+
+By using an SSO scheme, such as OpenID Connect, the third-party apps often receive personal data, such as the user's full name, during the authentication. 
+This information is typically used to display that user to other users of the app. However, transferring personal data to the app's server requires an increased level of data privacy safeguards, including proper logging, caching, and storage protocols.
+
+In the education space, when building such apps for the school system this becomes problematic. 
+Through https://eur-lex.europa.eu/eli/reg/2016/679/oj[GDPR] regulations children's data is subject to special protection and needs to be hidden by some means of pseudonymisation. 
+On the other hand, it is essential for a teacher to be able to match students' data to the actual individuals.
+
+D16N approaches this problem by specifying a way for a the client-side component of a third-party app to directly retrieve the users' names directly from the IDP.
+In this way, it should be possible to display recognisable names of students without exposing them beyond the bounds of a teacher's device.
+
+It prescribes an automatic pseudonymisation and the issuance of an access token that enables the a client to look up the pseudonym in the an API implemented by the IDP, the xref:_the_resolve_api[Resolve API].
 
 === Notational Conventions
 
@@ -487,6 +499,10 @@ Clear Names should not be stored long-term on the End-User device.
 It may make sense to cache the Clear Names in the client for a short amount of time to avoid overburdening the IDP.
 We recommend that any caching of the Clear Names is expired when the End-User leaves the application.
 
+=== Content Security Policy (CSP) Headers
+
+The RP should use https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP[CSP] headers to ensure only whitelisted domains can be called. 
+This prevents the client sending sensitive data to any unintended third party.
 
 === On-Site IDPs