Initial content import

Author: Dan Costello

app/docs/layout.tsx

@@ -4,8 +4,36 @@ import { baseOptions } from '@/app/layout.config';
 import { source } from '@/lib/source';
 
 export default function Layout({ children }: { children: ReactNode }) {
+  const options = {
+    ...baseOptions,
+    tree: source.pageTree,
+    links: [
+      {
+        text: 'Welcome to the UserCloud docs!',
+        url: '/docs',
+      },
+    ],
+    sidebar: {
+      tabs: [
+        {
+          title: 'Documentation',
+          icon: '🚀',
+          url: '/docs',
+          description: 'Guides and definitions',
+        },
+        {
+          title: 'Reference',
+          text: 'Reference',
+          icon: '🔍',
+          url: '/docs/reference',
+          description: 'API reference',
+        },
+      ],
+    },
+  };
+  console.log(options);
   return (
-    <DocsLayout tree={source.pageTree} {...baseOptions}>
+    <DocsLayout {...options}>
       {children}
     </DocsLayout>
   );

content/_dangling-articles/key-concepts.md

@@ -0,0 +1,25 @@
+---
+title: "Key Concepts"
+slug: "key-concepts"
+excerpt: ""
+hidden: true
+createdAt: "Fri Apr 05 2024 21:34:13 GMT+0000 (Coordinated Universal Time)"
+updatedAt: "Tue Sep 10 2024 18:33:44 GMT+0000 (Coordinated Universal Time)"
+---
+UserClouds’s is a safety layer for data protection. The layer mediates access to sensitive data, enforcing best practices in security, privacy and governance. It can be deployed in several distinct areas of your stack, depending on your use case.
+
+The Safety Layer allows you to define custom access paths, called **accessors** (for reading data) and **mutators** (for writing data) - see below for more detail. **Access policies** (like `IsRoleEngineer` and `IsIPTrusted`) describe a set of rules around reading and writing data. Policies control the circumstances in which data can be retrieved from and written to the store. **Data transformers** (like `BirthdayToAge` or `PhoneToAreaCode`) obscure, minimize or tokenize outbound data for a given use case.
+
+# Reading Data
+
+Data can be retrieved from the store using **accessors** (custom read paths that you define). Accessors are intended to be use-case specific, e.g.`GetEmailForMarketing` or `GetNameAndPhoneForSupport`. They enforce data usage policies and minimize outbound data from the store for their given use case. Each accessor is associated with a **user record selector**, a set of **columns**, a set of **data transformers**, a **purpose**, an **access policy** and an **optional token resolution policy** (see below). The user record selector is a SQL-like clause that specifies which records the accessor should return data for, based on an array of values that are passed at execution time. The columns indicate which data fields the accessor will pull. Each column is associated with a transformer, which transforms, minimizes or obscures the outbound data from that column. The purpose indicates what the accessor will be used for, e.g. marketing. The accessor will filter out user records where the user has not consented to the specified purpose. The access policy determines the circumstances in which the data can be retrieved. 
+
+# Writing Data
+
+New data can be written to the store using **mutators** (custom write paths that you define). Examples of mutators are `SetProfile` and `SetEmailAndPhoneNumber`. Each mutator is associated with a **user record selector**, a set of **columns**, a set of **validators** and an **access policy**. The record selector is a SQL-like clause that specifies which records the mutator should edit data for, based on an array of values that are passed at execution time. The columns indicate which data fields the mutator will edit. Each column is associated with a validator, which is a special data transformer that validates the incoming data and may transform it before saving it to the columns in the store. The access policy determines the circumstances in which the write is allowed. 
+
+# Tokenizing Data
+
+When using an accessor to retrieve data from the store, it is possible to **tokenize** the data. When you tokenize a piece of sensitive data, you replace it with a secure (but resolvable) reference token. Tokenization differs from other forms of data transformation: it allows an employee or service with sufficient permissions to **resolve** the token back into the raw data.
+
+The token is generated from the accessor's **transformer** code. It is common to generate tokens randomly and/or to match the format of the raw data so that the token can be used in place of the data without causing validation errors. For example, you might transform an email address like `john@beatles.com` to `550e8400e@a59d15b1.com`. The token is associated with a separate **token resolution policy** which controls the circumstances in which the token can be exchanged for the original raw data. When an application or employee needs the original data, it can request to exchange the raw data from the tokenization service. If the resolution access policy is met, the raw data is returned. Once the purpose for which the data was retrieved is achieved, the raw data should be discarded.

content/_dangling-articles/principles-for-use.md

@@ -0,0 +1,33 @@
+---
+title: "Principles for use"
+slug: "principles-for-use"
+excerpt: ""
+hidden: true
+createdAt: "Thu Aug 03 2023 18:41:15 GMT+0000 (Coordinated Universal Time)"
+updatedAt: "Tue Sep 10 2024 18:33:44 GMT+0000 (Coordinated Universal Time)"
+---
+Following a few key principles will help you get the most out of User Store.
+
+### 1. Avoid storing raw PII outside of the Safety Layer, unless necessary
+
+The key benefits of Safety Layer come from the ability to draw a protective boundary around your data. This boundary governs access control and minimizes or <<glossary:tokenize>>s outbound data. If data is stored outside the store, it does not receive these protective benefits. When applications or employees need raw data to complete a task, they should hold the data for the minimum time frame required to complete the task.
+
+### 2. When PII must be stored outside of the Safety Layer, tokenize or mask it wherever possible
+
+Of course, sometimes, data does need to be stored outside of the Safety Layer, e.g. for offline data analysis. In these cases, use a <<glossary:data transformer>> to obscure the data as much as possible. For example, use a tokenizing function that replaces the data with a random UUID. Attach this <<glossary:token>> to an access policy that only allows the token to be resolved in specific circumstances, such as by an authenticated employee, with the role of engineer, on the company VPN.
+
+### 3. Use transformers to minimize the information carried by a piece of data for a given task
+
+When you are passing data out of the store for a specified use case, minimize the information as much as possible for the specified task. For example, if you want to conduct analysis assessing the differences in behavior between children and adults, do not pull raw Dates of Birth from the store. Instead, use a <<glossary:data transformer>> to pass a string indicating `child` or `adult`. By minimizing outbound data, you reduce your surface area from attack, enable better enforcement of least privilege and better align with the GDPR principle of data minimization. 
+
+### 4. Create different accessors and mutators for different use cases
+
+User Store makes creating a new <<glossary:accessor>> (read API) as simple as writing a database query. This is because accessors are intended to be use-case specific. For example, you should configure one accessor `GetPhoneAndNameForMarketing`, and another `GetPhoneForMFA`. Configuring one accessor per use case makes accidental misuse of the system less likely. It lets you enforce different purpose-based access policies for different use cases, automatically create an audit log of data access and turn off individual data streams in case of emergency. It is essential for automatically generating DPIAs and other documentation about data use practices.
+
+### 5. Re-use access policies, transformers and validators to keep your code [DRY](https://en.wikipedia.org/wiki/Don't_repeat_yourself)
+
+Unlike accessors, each <<glossary:access policy>>, <<glossary:data transformer>> and validator can be re-used to maximize auditability, reduce update costs and prevent errors. Access policies can be easily built from parametrizable <<glossary:access policy template>>s. This allows you to update a set of access policies with parallel logic just by updating the template. Similarly, complex access policies can be composed of other policies to maximize re-use.
+
+### 6. Adopt a naming practice for accessors and mutators that describes what they do and why
+
+Accessor and mutator names are used in your codebase (to call the API), in code review (to identify accidental misuse) and in your audit log (to understand whether data usage aligns with user consents). Use the names to describe what the API does and why it exists. A good approach to naming describes the transformed data and the purpose, e.g. `GetAgeGroupForDataScience`, `SetPhoneNumberForMarketing` or `GetLastFourOfPhoneForCustomerService`.