Skip to content

Commit dce035b

Browse files
author
Chris Chinchilla
committed
Draft
Signed-off-by: Chris Chinchilla <[email protected]>
1 parent 56bba3c commit dce035b

File tree

1 file changed

+173
-60
lines changed

1 file changed

+173
-60
lines changed

‎docs/develop/01_sdk/04_integrate/04_extension_api.md‎

Lines changed: 173 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -3,93 +3,202 @@ id: kilt-extension-api
33
title: KILT Extension API
44
---
55

6-
KILT Extension API is a JavaScript/TypeScript library that provides helper functions for interacting with KILT enabled extensions.
7-
It facilitates seamless communication between your application and KILT extensions.
6+
import TsJsBlock from '@site/src/components/TsJsBlock';
7+
import Tabs from '@theme/Tabs';
8+
import TabItem from '@theme/TabItem';
89

9-
## Getting Started
10+
The KILT Extension API is a JavaScript and TypeScript library that provides helper functions for interacting with KILT extensions.
11+
It facilitates communication between your application and KILT extensions.
1012

11-
Before you can communicate with KILT extensions, you must call the `initializeKiltExtensionAPI()` function to signal the API versions supported by your application.
12-
This is crucial for the extension to inject the appropriate scripts into the website.
13+
<!-- TODO: Possible to test code as it's browser-based? -->
1314

14-
```ts
15-
import { initializeKiltExtensionAPI } from 'kilt-extension-api'
15+
## Installation
1616

17-
initializeKiltExtensionAPI()
18-
```
17+
Add the package:
18+
19+
<Tabs groupId="ts-js-choice">
20+
<TabItem value='ts' label='Typescript' default>
21+
22+
```bash
23+
yarn add @kiltprotocol/kilt-extension-api
24+
```
25+
26+
</TabItem>
27+
<TabItem value='js' label='Javascript'>
28+
29+
```bash
30+
npm install --save @kiltprotocol/kilt-extension-api
31+
```
32+
33+
</TabItem>
34+
</Tabs>
35+
36+
## Initialize Extension API
37+
38+
Before your application can communicate with KILT extensions, call the `initializeKiltExtensionAPI()` method to signal the API versions supported by your application so the extension can inject the appropriate scripts.
39+
40+
<Tabs groupId="ts-js-choice">
41+
<TabItem value='ts' label='Typescript' default>
42+
43+
```ts
44+
import { initializeKiltExtensionAPI } from 'kilt-extension-api'
45+
46+
initializeKiltExtensionAPI()
47+
```
48+
49+
</TabItem>
50+
<TabItem value='js' label='Javascript'>
51+
52+
```js
53+
import { initializeKiltExtensionAPI } from 'kilt-extension-api'
54+
55+
initializeKiltExtensionAPI()
56+
```
57+
58+
</TabItem>
59+
</Tabs>
1960

2061
## Get Extensions
2162

22-
The `getExtensions()` function returns a list of extensions currently injected into the website.
63+
The `getExtensions()` method returns a list of extensions injected into the browser.
2364

24-
```ts
25-
import { getExtensions } from 'kilt-extension-api'
65+
<Tabs groupId="ts-js-choice">
66+
<TabItem value='ts' label='Typescript' default>
2667

27-
const extensions = getExtensions()
28-
```
68+
```ts
69+
import { getExtensions } from 'kilt-extension-api'
2970

30-
## Watch Extensions
71+
const extensions = getExtensions()
72+
console.log(extensions)
73+
```
3174

32-
Extensions may take longer to load than the website.
33-
Therefore, the first call to `getExtensions()` might not return all available extensions.
34-
To receive updates on additional extensions as they load, you can use `watchExtensions`.
75+
</TabItem>
76+
<TabItem value='js' label='Javascript'>
3577

36-
Here's an example of how you can use this function in a React application:
78+
```js
79+
import { getExtensions } from 'kilt-extension-api'
3780

38-
```ts
39-
import { watchExtensions, Types } from 'kilt-extension-api'
40-
41-
export default function Home(): JSX.Element {
42-
const [extensions, setExtensions] = useState<
43-
Types.InjectedWindowProvider<Types.PubSubSessionV1 | Types.PubSubSessionV2>[]
44-
>([])
45-
46-
useEffect(() => {
47-
watchExtensions((extensions) => {
48-
setExtensions(extensions)
49-
})
50-
}, [])
51-
52-
return (
53-
<>
54-
<h2>Extensions</h2>
55-
<ul>
56-
{extensions.map((ext, i) => (
57-
<li key={i}>{ext.name}</li>
58-
))}
59-
</ul>
60-
</>
61-
)
62-
}
63-
```
81+
const extensions = getExtensions()
82+
console.log(extensions)
83+
```
84+
85+
</TabItem>
86+
</Tabs>
87+
88+
## Watch Extensions
89+
90+
Extensions can take longer to load than the host application, so the first call to `getExtensions()` might not return all available extensions.
91+
To receive updates on extensions as they load, use the `watchExtensions` method.
92+
93+
The following is an example of how you can use this method in a React application:
94+
95+
<Tabs groupId="ts-js-choice">
96+
<TabItem value='ts' label='Typescript' default>
97+
98+
```ts
99+
import { watchExtensions, Types } from 'kilt-extension-api'
100+
101+
export default function Home(): JSX.Element {
102+
const [extensions, setExtensions] = useState<
103+
Types.InjectedWindowProvider<Types.PubSubSessionV1 | Types.PubSubSessionV2>[]
104+
>([])
105+
106+
useEffect(() => {
107+
watchExtensions((extensions) => {
108+
setExtensions(extensions)
109+
})
110+
}, [])
111+
112+
return (
113+
<>
114+
<h2>Extensions</h2>
115+
<ul>
116+
{extensions.map((ext, i) => (
117+
<li key={i}>{ext.name}</li>
118+
))}
119+
</ul>
120+
</>
121+
)
122+
}
123+
```
124+
125+
</TabItem>
126+
<TabItem value='js' label='Javascript'>
127+
128+
```js
129+
import { watchExtensions } from "kilt-extension-api"
130+
131+
function App() {
132+
const [extensions, setExtensions] = useState([])
133+
134+
useEffect(() => {
135+
watchExtensions(extensions => {
136+
setExtensions(extensions)
137+
})
138+
}, [])
139+
140+
return (
141+
<>
142+
<h2>Extensions</h2>
143+
<ul>
144+
{extensions.map((ext, i) => (
145+
<li key={i}>{ext.name}</li>
146+
))}
147+
</ul>
148+
</>
149+
)
150+
}
151+
```
152+
153+
</TabItem>
154+
</Tabs>
155+
156+
<!-- TODO: Unable to test -->
64157

65158
## Well-Known DID Configuration
66159

67-
This library also aids in setting up the [Well-Known DID Configuration](https://identity.foundation/.well-known/resources/did-configuration/) as required by the [KILT Credential API specification](https://github.com/KILTprotocol/spec-ext-credential-api).
160+
This library helps set up the [Well-Known DID Configuration](https://identity.foundation/.well-known/resources/did-configuration/) as required by the [KILT Credential API specification](https://github.com/KILTprotocol/spec-ext-credential-api).
68161

69162
### Using the CLI Tool
70163

71-
A CLI tool is included in this library to create a [DID Configuration Resource](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource) as specified in the above documentation. This resource is necessary to establish a secure, end-to-end encrypted communication channel between a conforming browser extension and the application backend.
164+
This library includes a CLI tool to create a [DID Configuration Resource](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource). This resource is necessary to establish a secure, end-to-end encrypted communication channel between a conforming browser extension and the application backend.
72165

73-
To start using this tool, you can add this package to your application using `yarn add --dev kilt-extension-api` or install it globally if needed (`yarn global add kilt-extension-api`).
166+
:::warning KILT Account
74167

75-
You can run the CLI tool using Yarn as follows:
168+
The `createDidConfig` CLI tool **only** works if you installed the package with Yarn.
169+
170+
:::
171+
172+
Run the CLI tool using Yarn as follows:
76173

77174
```bash
78-
yarn createDidConfig --did <your DID> --origin <your domain> --assertionMethod <id of your DID's assertionMethod key> --seed <seed or mnemonic of the assertionMethod key>
175+
yarn createDidConfig --did <your DID> \
176+
--origin <your domain> \
177+
--assertionMethod <id of your DID's assertionMethod key> \
178+
--seed <seed or mnemonic of the assertionMethod key>
79179
```
80180
81-
For additional commands and configuration options, refer to the CLI tool's helper:
181+
:::info
182+
183+
- `did`: DID of the issuer (and subject) of the Domain Linkage Credential. If omitted, the tool attempts to infer this from the `assertionMethod`.
184+
- `seed`: Mnemonic or seed for the `assertionMethod` key used for issuing a new credential.
185+
- `origin`: The domain for which you are creating the credential. See [https://developer.mozilla.org/en-US/docs/Glossary/Origin] for details.
186+
- `assertionMethod`: ID of the `assertionMethod` key used for issuing a new credential.
187+
-
188+
:::
189+
190+
Use the tool's `--help` flag to see all available options:
82191

83192
```bash
84193
yarn createDidConfig --help
85194
```
86195

87-
### Integration into Your App
196+
### Integration into an App
88197

89-
Similar functionality to the CLI tool is available for import into your Node.js scripts using the subpath `kilt-extension-api/wellKnownDidConfiguration`:
198+
Similar functionality to the CLI tool is available for use in application code using the `@kiltprotocol/extension-api/wellKnownDidConfiguration` subpath:
90199

91200
```ts
92-
import { createCredential, didConfigResourceFromCredential } from './wellKnownDidConfiguration/index.js'
201+
import { createCredential, didConfigResourceFromCredential } from '@kiltprotocol/extension-api/wellKnownDidConfiguration'
93202
94203
const credential = await createCredential(
95204
({ data }) => {
@@ -102,20 +211,24 @@ const credential = await createCredential(
102211
const didConfigResource = didConfigResourceFromCredential(credential)
103212
```
104213
105-
This module also assists in verifying a DID configuration resource within an extension context:
214+
You can also verify a DID configuration resource within an extension context. From either a 3rd party DID resource:
106215
107216
```ts
108-
import { verifyDidConfigResource } from './wellKnownDidConfiguration/index.js'
217+
import { verifyDidConfigResource } from '@kiltprotocol/extension-api/wellKnownDidConfiguration'
109218
110-
// load didConfigResource from https://example.com/.well-known/did-configuration.json
219+
let didConfigResource = … // Load from https://socialkyc.io/.well-known/did-configuration.json or some other source
111220
112-
const didLinkedToOrigin = await verifyDidConfigResource(didConfigResource, 'https://example.com')
221+
const didLinkedToOrigin = await verifyDidConfigResource(didConfigResource, 'https://socialkyc.io')
222+
```
223+
224+
Or, if you expect a specific DID:
113225
114-
// or, if a specific DID is expected:
226+
```ts
227+
import { verifyDidConfigResource } from '@kiltprotocol/extension-api/wellKnownDidConfiguration'
115228
116229
await verifyDidConfigResource(
117230
didConfigResource,
118231
'https://example.com',
119232
'did:kilt:4pnfkRn5UurBJTW92d9TaVLR2CqJdY4z5HPjrEbpGyBykare'
120233
)
121-
```
234+
```

0 commit comments

Comments
 (0)