doc: add documentation for app shares

doc/api/share.md

@@ -14,6 +14,36 @@ different from calling `/grant-user-user` with a permission.
 When users are **specified by email** they will receive
 a [share link](./concepts/share-link.md).
 
+Each item specified in the `shares` property is a tag-typed
+object of type `fs-share` or `app-share`.
+
+#### File Shares (`fs-share`)
+
+File shares grant permission to a file or directory. By default
+this is read permission. If `access` is specified as `"write"`,
+then write permission will be granted.
+
+#### App Shares (`app-share`)
+
+App shares grant permission to read a protected app.
+
+##### subdomain permission
+If there is a subdomain associated with the app, and the owner
+of the subdomain is the same as the owner of the app, then
+permission to access the subdomain will be granted.
+Note that the subdomain is only associated if the subdomain
+entry has `associated_app_id` set according to the app's id,
+and will not be considered "associated" if only the index_url
+happens to match the subdomain url.
+
+##### appdata permission
+If the app has `shared_appdata` set to `true` in its metadata
+object, the recipient of the share will also get write permission
+to the app owner's corresponding appdata directory. The appdata
+directory must exist for this to work as expected
+(otherwise the permission rewrite rule fails since the uuid
+can't be determined).
+
 ### Example
 
 ```json

packages/backend/doc/lists-of-things/list-of-tto-types.md

@@ -0,0 +1,29 @@
+# Types for Type-Tagged Objects
+
+## Internal Use
+
+### `{ $: 'share-intent' }`
+
+- Used in the `/share` endpoint
+- Permissions get applied to existing users
+- For email shares, is trasnformed into a `token:share`
+  which is stored in the `share` database table.
+
+- **variants:**
+  - `share-intent:file`
+  - `share-intent:app`
+- **properties:**
+  - `permissions` - a list of permissions to grant
+  
+### `{ $: 'internal:share' }`
+- Stored in the `share` database table
+- **properties:**
+  - `permissions` - a list of permissions to grant
+
+### `{ $: 'token:share }`
+
+- Stored in a JWT called the "share token"
+- Contains only the share UUID
+
+- **properties:**
+  - `uid` - UUID of a share