@minca/core 0.1.17 → 0.1.18
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -1
- package/dist/files/space-files.d.ts +2 -2
- package/dist/files/space-files.d.ts.map +1 -1
- package/dist/files/space-files.js +7 -5
- package/dist/files/space-files.js.map +1 -1
- package/dist/inbox/names.d.ts +1 -1
- package/dist/inbox/names.js +1 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- package/dist/node/actions.d.ts +3 -0
- package/dist/node/actions.d.ts.map +1 -1
- package/dist/node/actions.js.map +1 -1
- package/dist/node/api.d.ts +1 -0
- package/dist/node/api.d.ts.map +1 -1
- package/dist/node/api.js +1 -0
- package/dist/node/api.js.map +1 -1
- package/dist/node/carrier.js +1 -1
- package/dist/node/carrier.js.map +1 -1
- package/dist/node/node-contacts.d.ts.map +1 -1
- package/dist/node/node-contacts.js +1 -0
- package/dist/node/node-contacts.js.map +1 -1
- package/dist/node/node-records.d.ts.map +1 -1
- package/dist/node/node-records.js +6 -1
- package/dist/node/node-records.js.map +1 -1
- package/dist/node/node.d.ts.map +1 -1
- package/dist/node/node.js +13 -1
- package/dist/node/node.js.map +1 -1
- package/dist/node/remote.d.ts.map +1 -1
- package/dist/node/remote.js +7 -1
- package/dist/node/remote.js.map +1 -1
- package/dist/node/space-runtime.d.ts +5 -3
- package/dist/node/space-runtime.d.ts.map +1 -1
- package/dist/node/space-runtime.js +3 -1
- package/dist/node/space-runtime.js.map +1 -1
- package/dist/node/types.d.ts +112 -36
- package/dist/node/types.d.ts.map +1 -1
- package/dist/query/types.d.ts +1 -0
- package/dist/query/types.d.ts.map +1 -1
- package/dist/query/types.js.map +1 -1
- package/dist/records/contract-builder.d.ts +22 -6
- package/dist/records/contract-builder.d.ts.map +1 -1
- package/dist/records/contract-builder.js.map +1 -1
- package/dist/schemas/automations.d.ts +6 -2
- package/dist/schemas/automations.d.ts.map +1 -1
- package/dist/schemas/automations.js.map +1 -1
- package/dist/schemas/connectors.d.ts +4 -3
- package/dist/schemas/connectors.d.ts.map +1 -1
- package/dist/schemas/connectors.js +4 -3
- package/dist/schemas/connectors.js.map +1 -1
- package/dist/schemas/library/media.js +1 -1
- package/dist/schemas/library/media.js.map +1 -1
- package/dist/session/auth.d.ts +7 -3
- package/dist/session/auth.d.ts.map +1 -1
- package/dist/session/auth.js.map +1 -1
- package/dist/storage/blob-store.d.ts +3 -0
- package/dist/storage/blob-store.d.ts.map +1 -1
- package/dist/types.d.ts +11 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js.map +1 -1
- package/docs/README.md +86 -93
- package/docs/actions.md +213 -152
- package/docs/agents.md +198 -167
- package/docs/automations.md +296 -204
- package/docs/blueprints-and-guides.md +405 -311
- package/docs/bots.md +208 -134
- package/docs/building-an-app.md +74 -163
- package/docs/collections.md +248 -328
- package/docs/computed.md +112 -89
- package/docs/contacts.md +151 -112
- package/docs/contracts.md +299 -120
- package/docs/direct-messages.md +80 -65
- package/docs/inbox.md +138 -93
- package/docs/node.md +1072 -996
- package/docs/permissions.md +142 -0
- package/docs/proposing-collections.md +74 -55
- package/docs/query-format.md +150 -126
- package/docs/records-and-queries.md +205 -126
- package/docs/sign-in.md +496 -418
- package/docs/spaces.md +261 -246
- package/docs/standard-library.md +473 -526
- package/docs/storage.md +325 -348
- package/docs/usernames.md +164 -97
- package/docs/warrants.md +100 -67
- package/package.json +1 -1
package/docs/sign-in.md
CHANGED
|
@@ -1,260 +1,208 @@
|
|
|
1
1
|
# Signing in
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
3
|
+
Most apps connect to the person's account home
|
|
4
|
+
([Building an app](building-an-app.md)). This page is for a page that keeps
|
|
5
|
+
the account itself: an account home, or an app that signs people in on its
|
|
6
|
+
own. `createMincaAuth` is the whole flow, from creating an account to
|
|
7
|
+
pairing a phone.
|
|
8
|
+
|
|
9
|
+
## The sign-in screen
|
|
10
|
+
|
|
11
|
+
The quickest way in is the `<minca-auth>` element. It draws every screen of
|
|
12
|
+
the flow, and fires `minca-session` when someone signs in or out:
|
|
13
|
+
|
|
14
|
+
```html
|
|
15
|
+
<minca-auth app-name="Todo" relays="wss://relay.minca.social"></minca-auth>
|
|
16
|
+
<script type="module">
|
|
17
|
+
import '@minca/core/elements';
|
|
18
|
+
document.querySelector('minca-auth').addEventListener('minca-session', (event) => {
|
|
19
|
+
const session = event.detail.session; // { account, did, sessionDid, node }, or null
|
|
20
|
+
if (session) start(session.node);
|
|
21
|
+
});
|
|
22
|
+
</script>
|
|
23
|
+
```
|
|
12
24
|
|
|
13
|
-
|
|
25
|
+
In React, make the flow with `createMincaAuth`, hand it to `MincaProvider`,
|
|
26
|
+
and show `<MincaAuth>` until the person is signed in:
|
|
14
27
|
|
|
15
|
-
|
|
28
|
+
```tsx
|
|
29
|
+
import { createRoot } from 'react-dom/client';
|
|
30
|
+
import { createMincaAuth } from '@minca/core/session';
|
|
31
|
+
import { MincaProvider, MincaAuth, useMinca } from '@minca/react';
|
|
16
32
|
|
|
17
|
-
|
|
18
|
-
| ------------------ | ------------------------------------- | ------------------------------------------------------------ |
|
|
19
|
-
| `browser` | the browser account store (IndexedDB) | IndexedDB, per account ([stores](node.md#stores)) |
|
|
20
|
-
| `folder` (a _pod_) | the folder's account store | the folder, per account, registry sealed under the local key |
|
|
33
|
+
const auth = createMincaAuth({ appName: 'Todo', network: { relays: ['wss://relay.minca.social'] } });
|
|
21
34
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
35
|
+
function App() {
|
|
36
|
+
const { state } = useMinca();
|
|
37
|
+
if (state?.stage !== 'ready') return <MincaAuth />;
|
|
38
|
+
return <p>Signed in.</p>;
|
|
39
|
+
}
|
|
26
40
|
|
|
27
|
-
|
|
41
|
+
createRoot(root).render(
|
|
42
|
+
<MincaProvider auth={auth}>
|
|
43
|
+
<App />
|
|
44
|
+
</MincaProvider>,
|
|
45
|
+
);
|
|
46
|
+
```
|
|
28
47
|
|
|
29
|
-
|
|
48
|
+
Everything below the provider works as it does for a connected app. The
|
|
49
|
+
rest of this page is for when you want to know what the flow does, or draw
|
|
50
|
+
your own screens on it.
|
|
30
51
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
`createdAt`), and writes each file as JSON with a 2-space indent and a trailing
|
|
35
|
-
newline.
|
|
52
|
+
## Places
|
|
53
|
+
|
|
54
|
+
A place is where accounts and their data are kept. There are two kinds:
|
|
36
55
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
56
|
+
| `kind` | Accounts and data are kept in |
|
|
57
|
+
| --------- | ---------------------------------------------------------------- |
|
|
58
|
+
| `browser` | IndexedDB, per account ([stores](node.md#stores)) |
|
|
59
|
+
| `folder` | A folder the person picks, called a pod. The registry is sealed. |
|
|
40
60
|
|
|
41
|
-
|
|
61
|
+
A pod is a folder picked through the File System Access API. The last one
|
|
62
|
+
picked is remembered, and opened again without a prompt while the browser
|
|
63
|
+
still grants it. A place holds any number of accounts. `listAccounts` returns
|
|
64
|
+
them most recently used first.
|
|
42
65
|
|
|
43
66
|
## Stages
|
|
44
67
|
|
|
45
|
-
`
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
|
64
|
-
|
|
|
65
|
-
|
|
|
66
|
-
| `
|
|
67
|
-
| `
|
|
68
|
-
| `
|
|
69
|
-
|
|
|
70
|
-
| `
|
|
71
|
-
| `welcome
|
|
72
|
-
| `
|
|
73
|
-
| `
|
|
74
|
-
| `
|
|
75
|
-
| `
|
|
76
|
-
| `
|
|
77
|
-
| `
|
|
78
|
-
| `
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
With `usernames: '
|
|
103
|
-
the account's name
|
|
104
|
-
background ([usernames
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
68
|
+
The flow is a state to read and actions to call. `auth.getState().stage`
|
|
69
|
+
says which screen it is on. It goes from `starting` through the screens of signing in or setting up,
|
|
70
|
+
to `ready`. What each stage means is in
|
|
71
|
+
[`AuthStage`](https://minca.dev/api/session/type-aliases/AuthStage/).
|
|
72
|
+
|
|
73
|
+
Where data lives is asked at `existing`, not up front. A page that waits for
|
|
74
|
+
`ready` doesn't see the session during `recovery`, `unlock` or `pod`.
|
|
75
|
+
|
|
76
|
+
A failed action sets `error`, an
|
|
77
|
+
[`AuthError`](https://minca.dev/api/session/interfaces/AuthError/), and stays
|
|
78
|
+
on the same stage. A dismissed passkey or folder prompt sets no error.
|
|
79
|
+
|
|
80
|
+
### Moving between stages
|
|
81
|
+
|
|
82
|
+
| From | Action | To |
|
|
83
|
+
| ------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
84
|
+
| `starting` | `start()` with a kept sign-in here | `ready`, or `pair` (signed in) with a pairing ticket in the URL |
|
|
85
|
+
| `starting` | `start()` with no kept sign-in and a pairing ticket in the URL | `pair` |
|
|
86
|
+
| `starting` | `start()`, otherwise | `signIn` if the place has accounts, else `welcome` |
|
|
87
|
+
| `starting` | `start()` fails | `welcome`, with `error` |
|
|
88
|
+
| any | `showWelcome()`, `showExisting()`, `showRestore()`, `showSignIn()` | that stage |
|
|
89
|
+
| `welcome`, `existing`, `signIn` | `choosePod()` or `useBrowser()`, signed out | `signIn` or `welcome` |
|
|
90
|
+
| `welcome` | `reopenPod()` from a click, with `podToReopen` set | `ready` with a kept sign-in there, else `signIn` or `welcome` |
|
|
91
|
+
| `ready` | `choosePod()` | `ready`, with `podChoice` set ([moving into a pod](#moving-into-a-pod)) |
|
|
92
|
+
| `pod` | `choosePod()` | `ready`. The new account moves into the pod, and its browser copy is removed |
|
|
93
|
+
| `pod` | `finishSetup()` | `ready` |
|
|
94
|
+
| `welcome`, `existing`, `signIn` | `startCreating()` | `create` |
|
|
95
|
+
| `signIn` | `signInWithPassword` or `signInWithPasskey` succeeds | `ready` |
|
|
96
|
+
| `signIn`, `restore` | `signInWithCode` succeeds, or a recovery code given to `signInWithPassword` | `ready` if the account has a passkey or password here, else `unlock` with `setup: 'restored'` |
|
|
97
|
+
| `create` | `createAccount(name, { username? })` | `recovery`, with `session`, `freshCode` and `setup: 'new'` |
|
|
98
|
+
| `recovery` | `codeSaved()` | `unlock` |
|
|
99
|
+
| `unlock` | `addPasskey()` or `setPassword(p)` succeeds | `ready` for a new account with a host. Else `pod` where folders can be opened, unless `offerPod` is false. Else `ready` |
|
|
100
|
+
| `pair` | `acceptPairing()` | See [pairing a phone](#pairing-a-phone) |
|
|
101
|
+
| `pair` | `answerPairing(true)` or `answerPairing(false)` | As `acceptPairing()` signed out, or `ready` keeping the account signed in |
|
|
102
|
+
| `pair` | `dismissPairing()` | `ready` if signed in, else `signIn` or `welcome` |
|
|
103
|
+
| `ready` | `signOut()` | `starting`, then `signIn` or `welcome` |
|
|
104
|
+
|
|
105
|
+
### A pod that needs a click
|
|
106
|
+
|
|
107
|
+
Chrome keeps a pod's folder between visits, but not the permission to use
|
|
108
|
+
it, unless the person chose "Allow on every visit". Then `start()` sets
|
|
109
|
+
`podToReopen` to the folder's name and goes on as if there were no pod.
|
|
110
|
+
`<minca-auth>` offers it first on the welcome screen. `reopenPod()`, called
|
|
111
|
+
from that click, asks for the permission and carries on as `start()` would
|
|
112
|
+
have.
|
|
113
|
+
|
|
114
|
+
## Creating an account
|
|
115
|
+
|
|
116
|
+
`createAccount(name)` makes a new account with a random seed. It writes the
|
|
117
|
+
account's vault, asks the browser to keep its storage, starts its session,
|
|
118
|
+
writes its name to `sys.profile` and shows the recovery code (`freshCode`).
|
|
119
|
+
|
|
120
|
+
The person must then set up a passkey or a password before `ready`.
|
|
121
|
+
Otherwise they would open the account with the recovery code every time.
|
|
122
|
+
|
|
123
|
+
### Usernames
|
|
124
|
+
|
|
125
|
+
With `usernames: 'minca.social'` in the config, the create screen asks for a
|
|
126
|
+
username alone, and takes the account's name from it. `createAccount` claims
|
|
127
|
+
it in the background ([usernames](usernames.md#on-the-node)).
|
|
128
|
+
|
|
129
|
+
### Hosts
|
|
130
|
+
|
|
131
|
+
With `network.hosts`, a new account is kept online with the first host as it
|
|
132
|
+
is made. Nothing to choose: `hosting.use` runs in the background, tried once
|
|
133
|
+
more if the host doesn't answer. It does this only when the host keeps
|
|
134
|
+
accounts for free (`free`, or `limits`). Failing that, the account stays in
|
|
135
|
+
this browser, and the person can keep it online from the account page later.
|
|
136
|
+
|
|
137
|
+
`settled()` resolves once the host and any username claim are done.
|
|
138
|
+
|
|
139
|
+
### Pods
|
|
140
|
+
|
|
141
|
+
A pod is kept up to date only while a node has it open: this page, or a
|
|
142
|
+
carrier given the folder. So a page that closes once signed in, such as an
|
|
143
|
+
account home's connect page, passes `offerPod: false`. It offers the pod
|
|
144
|
+
where the person comes back instead.
|
|
114
145
|
|
|
115
146
|
## Ways in
|
|
116
147
|
|
|
117
|
-
|
|
118
|
-
([01](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md)). It works on any site without anything stored there,
|
|
119
|
-
and is for restoring, not for every day. If an account is selected and the
|
|
120
|
-
code opens a different one, sign-in fails with a reason. If the code's
|
|
121
|
-
account is new to this place, it is filed there with an empty vault (no
|
|
122
|
-
wraps) under the selected account's name or `My account`.
|
|
123
|
-
- **A password** unwraps the seed from the vault's `passphrase` wrap. It
|
|
124
|
-
works wherever that vault is: this browser, or a pod on any origin. The flow
|
|
125
|
-
keeps one passphrase wrap as the account's password: setting one replaces
|
|
126
|
-
any other, except the CLI's (label `CLI passphrase`, `CLI_PASSPHRASE_LABEL`),
|
|
127
|
-
which is for unattended unlocking and is kept; the CLI account home
|
|
128
|
-
(`packages/cli/src/home.ts`) makes those. Signing in by password tries every
|
|
129
|
-
passphrase wrap. Any password but an empty one is taken: a copied vault can
|
|
130
|
-
be guessed at offline, so the forms show how strong it is as it is typed
|
|
131
|
-
(`passwordStrength`, weak under 40 bits, strong from 60) and warn, but leave
|
|
132
|
-
the choice to the person. `signInWithPassword` also accepts a
|
|
133
|
-
recovery code, which password managers may hold as this site's login from
|
|
134
|
-
before passwords existed.
|
|
135
|
-
- **A passkey** is a gate, not a key: the WebAuthn ceremony proves presence,
|
|
136
|
-
and the seed is unwrapped with a non-extractable device key kept in this
|
|
137
|
-
site's storage, named by the vault's `device` wrap for this `rpId`
|
|
138
|
-
([device keys and passkeys](#device-keys-and-passkeys)). Only device wraps
|
|
139
|
-
whose `rpId` is this site's are offered, since another origin's device key
|
|
140
|
-
is unreachable from here, and only one whose device key is present in this
|
|
141
|
-
browser.
|
|
142
|
-
|
|
143
|
-
A new account's seed is random. Creating one writes its vault with no wraps,
|
|
144
|
-
asks the browser to persist its storage (when kept in the browser), starts its
|
|
145
|
-
session, writes its name to `sys.profile` in the account registry, and shows
|
|
146
|
-
the recovery code (`freshCode`). Setting up a passkey or a password is
|
|
147
|
-
required before `ready`: an account with no everyday way in would be opened
|
|
148
|
-
with its recovery code every time, which is the habit this avoids. A page that
|
|
149
|
-
waits for `ready` does not see the session during `recovery`, `unlock` or
|
|
150
|
-
`pod`.
|
|
151
|
-
|
|
152
|
-
_Source: `packages/core/src/session/auth.ts`, `packages/core/src/session/credentials.ts`, `packages/core/src/identity/account-vault.ts` (`CLI_PASSPHRASE_LABEL`). Tests: `packages/core/tests/auth.test.ts`, `packages/core/tests/account-vault.test.ts`._
|
|
153
|
-
|
|
154
|
-
## Proving it is you
|
|
155
|
-
|
|
156
|
-
Being signed in is no proof anyone is there: a page may be left open, and a
|
|
157
|
-
sign-in kept for days. So whatever hands out the whole account, or changes how
|
|
158
|
-
it signs in, asks again. `auth.recoveryCode()` returns the code,
|
|
159
|
-
`auth.offerToPhone()` starts, `setPassword`, `addPasskey`,
|
|
160
|
-
`removeShortcut` and `removeAccount` work (outside the first setup of an account just made,
|
|
161
|
-
restored or paired, which only landing a session opens), only within five
|
|
162
|
-
minutes of `auth.confirm(proof)` succeeding for the account signed in now
|
|
163
|
-
(`isConfirmed()` says whether it has), where `proof` is
|
|
164
|
-
`{ password }`, `{ passkey: true }` (the passkey's own check that someone is
|
|
165
|
-
there: a fingerprint, a face or a PIN) or `{ code }`, the recovery code itself.
|
|
166
|
-
`confirm` resolves false and sets `error` for a wrong answer, and a passkey
|
|
167
|
-
with no credential behind it is no proof. A new sign-in, or signing out, asks
|
|
168
|
-
again. The recovery code shown once when an account is made needs no confirm.
|
|
148
|
+
There are three ways into an account.
|
|
169
149
|
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
credential behind it. `mayGrant()` says whether any of these holds. A
|
|
176
|
-
sign-in kept from an earlier visit is none of them. So the reference home's connect page
|
|
177
|
-
goes as signing in with Google does: choose the account, prove it is you
|
|
178
|
-
(signing in to it, or confirming if it is the one signed in), then allow.
|
|
179
|
-
A suggestion from an app already connected (`auth.propose`) gives nothing
|
|
180
|
-
new, and needs only the sign-in.
|
|
181
|
-
This keeps the seed from someone who only has the open page, not from a
|
|
182
|
-
compromised one: the seed is in the page's memory while it is signed in
|
|
183
|
-
([threat model §4](https://github.com/leifriksheim/minca/blob/main/spec/threat-model.md)).
|
|
184
|
-
|
|
185
|
-
_Source: `packages/core/src/session/auth.ts` (`confirm`, `mayGrant`, `recoveryCode`, `offerToPhone`), `apps/home/src/components/ConfirmItsYou.tsx`, `apps/home/src/components/ConnectPage.tsx` (`ChooseAccount`). Tests: `packages/core/tests/auth.test.ts` ("reading the recovery code or offering the account to a phone takes proof it is you", "changing how the account signs in takes proof it is you, once it is set up", "no call steps back into setup to skip the proof", "proof is for one account, and does not carry over to another"), `packages/core/tests/connect.test.ts` ("an app or a carrier is given access only just after proof it is you")._
|
|
186
|
-
|
|
187
|
-
## Device keys and passkeys
|
|
150
|
+
**The recovery code** is the seed written out, 26 characters. It works on any
|
|
151
|
+
site with nothing stored there. It is for restoring, not for every day. If an
|
|
152
|
+
account is selected and the code opens a different one, sign-in fails with a
|
|
153
|
+
reason. If the code's account is new here, it is filed under the selected
|
|
154
|
+
account's name, or `My account`.
|
|
188
155
|
|
|
189
|
-
A
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
What that protects: someone holding a copy of the folder or the vault gets
|
|
195
|
-
ciphertext and no key, and because the key is non-extractable it cannot be
|
|
196
|
-
carried off and used elsewhere. What it does not: anything that can run script
|
|
197
|
-
in the origin can use the key in place without the passkey. The passkey in
|
|
198
|
-
front of it is enforced by this code, not by cryptography.
|
|
199
|
-
|
|
200
|
-
**Passkeys are a gate.** A passkey yields no key material here. A WebAuthn
|
|
201
|
-
ceremony is required before the flow reaches for a device key, and the seed
|
|
202
|
-
comes from the device wrap. A passkey can return a secret only through the PRF
|
|
203
|
-
extension, which several major credential providers do not implement or report
|
|
204
|
-
inconsistently, and a passkey is bound to one relying party, so an identity
|
|
205
|
-
derived from it would differ per origin. There is no server, so nobody verifies
|
|
206
|
-
the assertion's challenge or signature; the gate is that the browser completed
|
|
207
|
-
a user-verified ceremony for the recorded credential.
|
|
156
|
+
**A password** unlocks the vault. It works wherever that vault is: this
|
|
157
|
+
browser, or a pod on any site. An account has one password. Setting a new one
|
|
158
|
+
replaces the old one, but keeps the CLI's (`CLI_PASSPHRASE_LABEL`), which is
|
|
159
|
+
for unlocking unattended. Signing in tries every password the vault holds.
|
|
208
160
|
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
| `user.id` | 32 random bytes (kept, base64url, as the wrap's `userHandle`) |
|
|
215
|
-
| `user.name`, `user.displayName` | The account's name |
|
|
216
|
-
| `challenge` | 32 random bytes |
|
|
217
|
-
| `pubKeyCredParams` | ES256 (−7), RS256 (−257) |
|
|
218
|
-
| `authenticatorSelection` | `residentKey: "required"`, `requireResidentKey: true`, `userVerification: "required"`; `authenticatorAttachment: "platform"` when a platform authenticator exists |
|
|
219
|
-
| `hints` | `["client-device"]` when preferring the platform authenticator |
|
|
161
|
+
Any password but an empty one is taken. A copied vault can be guessed at
|
|
162
|
+
offline, so the forms show how strong a password is as it is typed
|
|
163
|
+
(`passwordStrength`: weak under 40 bits, strong from 60) and leave the
|
|
164
|
+
choice to the person. `signInWithPassword` also takes a recovery code, which
|
|
165
|
+
a password manager may hold from before passwords existed.
|
|
220
166
|
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
167
|
+
**A passkey** is a gate, not a key. The passkey proves someone is there, then
|
|
168
|
+
a device key kept in this browser unlocks the seed
|
|
169
|
+
([device keys and passkeys](#device-keys-and-passkeys)). Only passkeys made
|
|
170
|
+
on this site, whose device key is in this browser, are offered.
|
|
224
171
|
|
|
225
|
-
|
|
226
|
-
WebAuthn Signal API (`PublicKeyCredential.signalCurrentUserDetails` with the
|
|
227
|
-
`userHandle`); best effort.
|
|
172
|
+
## Staying signed in
|
|
228
173
|
|
|
229
|
-
|
|
174
|
+
After an unlock, the account can stay signed in on this device, so a reload
|
|
175
|
+
doesn't ask again. The choices are `never`, `1d`, `7d` and `30d`. The default
|
|
176
|
+
is `7d`, and each use pushes the expiry forward.
|
|
230
177
|
|
|
231
|
-
|
|
178
|
+
```ts
|
|
179
|
+
import { createMincaAuth } from '@minca/core/session';
|
|
232
180
|
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
registry, as a non-extractable `CryptoKey`, and never hands it out. The
|
|
238
|
-
session (`MincaSession`) is `{ account, did, sessionDid, node }`. The seed stays
|
|
239
|
-
inside the auth object; `recoveryCode()` returns it as a recovery code.
|
|
181
|
+
const auth = createMincaAuth();
|
|
182
|
+
await auth.staySignedIn.setChoice('30d');
|
|
183
|
+
auth.staySignedIn.until(); // a Date, or null
|
|
184
|
+
```
|
|
240
185
|
|
|
241
|
-
The
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
186
|
+
The seed is kept wrapped with a fresh device key that can't leave the
|
|
187
|
+
browser. A kept sign-in resumes only in the same kind of place it was made
|
|
188
|
+
in. Signing out, choosing `never`, or finding it expired deletes the device
|
|
189
|
+
key.
|
|
245
190
|
|
|
246
|
-
|
|
191
|
+
A signed-out tab picks up a sign-in another tab keeps, as a reload would. It
|
|
192
|
+
does this only once `start()` has finished, and only at `welcome`,
|
|
193
|
+
`existing` or `signIn` with no account picked, or the same one picked. When
|
|
194
|
+
the person signs out in another tab, a tab that picked it up signs out too.
|
|
247
195
|
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
labelled `stay signed in` that is kept outside any vault, and stored with an
|
|
251
|
-
expiry that is pushed forward each time it is used. Choices: `never`, `1d`,
|
|
252
|
-
`7d` (default), `30d`. A kept sign-in resumes only for the same kind of place
|
|
253
|
-
it was made in (`browser` or `folder`). Signing out, choosing `never`, or
|
|
254
|
-
finding it expired deletes the device key.
|
|
196
|
+
The flow keeps these in `localStorage`, where `<prefix>` is `storageKey` in
|
|
197
|
+
the config, default `minca`:
|
|
255
198
|
|
|
256
|
-
|
|
257
|
-
|
|
199
|
+
| Key | Holds |
|
|
200
|
+
| ---------------------------------- | ----------------------------------------------------------- |
|
|
201
|
+
| `<prefix>.stay-signed-in` | The choice |
|
|
202
|
+
| `<prefix>.remembered-session` | The kept sign-in (below) |
|
|
203
|
+
| `<prefix>.last-account` | The account used last |
|
|
204
|
+
| `<prefix>.storage-choice` | Where data lives |
|
|
205
|
+
| `<prefix>.connections:<accountId>` | At an account home, its connections ([below](#connections)) |
|
|
258
206
|
|
|
259
207
|
```json
|
|
260
208
|
{
|
|
@@ -265,213 +213,343 @@ _Implementation detail:_ kept in `localStorage` as `<prefix>.stay-signed-in`
|
|
|
265
213
|
}
|
|
266
214
|
```
|
|
267
215
|
|
|
268
|
-
|
|
269
|
-
and at an account home `<prefix>.connections:<accountId>` ([the account home's side](#the-account-homes-side)). `prefix`
|
|
270
|
-
defaults to `minca`.
|
|
216
|
+
These are implementation details. Don't read them from your app.
|
|
271
217
|
|
|
272
|
-
|
|
218
|
+
## Proving it is you
|
|
273
219
|
|
|
274
|
-
|
|
220
|
+
Being signed in is no proof anyone is there. A page may be left open, and a
|
|
221
|
+
sign-in kept for days. So anything that hands out the whole account, or
|
|
222
|
+
changes how it signs in, asks again first:
|
|
275
223
|
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
`confirmPod('switch')` uses the pod's own copy and brings nothing.
|
|
279
|
-
`confirmPod('combine')` writes the account and a union of both vaults' wraps
|
|
280
|
-
into the pod, copies every space into it (`copyAccountData`, [stores](node.md#stores)), and
|
|
281
|
-
restarts the session there. `forgetBrowserCopy()` then deletes the browser's
|
|
282
|
-
copy. Other accounts in the pod are never touched.
|
|
283
|
-
|
|
284
|
-
`removeAccount()` takes an account out of the browser altogether, as clearing
|
|
285
|
-
its site data would. It refuses while an app is connected from here: only this
|
|
286
|
-
home can disconnect an app, so the apps go first, from the list where
|
|
287
|
-
`disconnect` says whether each has heard. Then it signs out and deletes the
|
|
288
|
-
account's vault, its spaces' data and what the home remembered of it. A
|
|
289
|
-
revoke no peer but the app has taken in goes with them, as after a disconnect
|
|
290
|
-
nobody heard. Its passkey keys stay, since a pod's vault may name the same
|
|
291
|
-
one; with the vault gone they open nothing.
|
|
292
|
-
Copies on other devices, carriers and hosts stay; with none, its private
|
|
293
|
-
spaces are gone, and so is whatever reached no other copy. An account kept in a pod is not removed this way: the pod is
|
|
294
|
-
its copy.
|
|
224
|
+
```ts
|
|
225
|
+
import { createMincaAuth } from '@minca/core/session';
|
|
295
226
|
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
227
|
+
const auth = createMincaAuth();
|
|
228
|
+
const ok = await auth.confirm({ password: 'correct horse battery staple' });
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
The proof is the password, the passkey's own check (a fingerprint, a face or
|
|
232
|
+
a PIN), or the recovery code itself
|
|
233
|
+
([`MincaAuth.confirm`](https://minca.dev/api/session/interfaces/MincaAuth/)).
|
|
234
|
+
A wrong answer resolves false and sets `error`. A passkey with nothing behind
|
|
235
|
+
it is no proof.
|
|
236
|
+
|
|
237
|
+
For five minutes after, these work: `recoveryCode()`, `offerToPhone()`,
|
|
238
|
+
`setPassword`, `addPasskey`, `removeShortcut` and `removeAccount`.
|
|
239
|
+
`isConfirmed()` says whether you're in that window. A new sign-in, or
|
|
240
|
+
signing out, asks again. The first setup of an account just made, restored
|
|
241
|
+
or paired needs no proof, nor does the recovery code shown when an account
|
|
242
|
+
is made.
|
|
243
|
+
|
|
244
|
+
### Giving apps access
|
|
245
|
+
|
|
246
|
+
Giving an app or a carrier anything (`auth.grant`, `auth.grantCarry`) takes
|
|
247
|
+
the same proof, or a sign-in in the last five minutes. Making the account
|
|
248
|
+
counts too. A passkey sign-in counts only when the passkey's own check ran. A
|
|
249
|
+
sign-in kept from an earlier visit doesn't count. `mayGrant()` says whether
|
|
250
|
+
any of these holds.
|
|
251
|
+
|
|
252
|
+
So the reference home's connect page works like signing in with Google:
|
|
253
|
+
choose the account, prove it is you, then allow. A suggestion from an app
|
|
254
|
+
already connected (`auth.propose`) gives nothing new, and needs only the
|
|
255
|
+
sign-in.
|
|
300
256
|
|
|
301
|
-
|
|
257
|
+
This keeps the seed from someone who only has the open page. It can't keep
|
|
258
|
+
it from a compromised page, since the seed is in the page's memory while
|
|
259
|
+
signed in. [Threat model §4](https://github.com/leifriksheim/minca/blob/main/spec/threat-model.md)
|
|
302
260
|
|
|
303
261
|
## Pairing a phone
|
|
304
262
|
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
263
|
+
Pairing moves an account from a computer to a phone with a QR code.
|
|
264
|
+
|
|
265
|
+
### On the computer
|
|
266
|
+
|
|
267
|
+
`offerToPhone(onStage)` starts an offer on the first relay, and returns
|
|
268
|
+
`{ url, stop }`: the link to show as a QR code, and a way to stop. The link
|
|
309
269
|
holds a one-time secret, not the account. The offer answers the first phone
|
|
310
|
-
that turns up and nobody after it
|
|
311
|
-
|
|
270
|
+
that turns up and nobody after it. It stops after two minutes if no phone
|
|
271
|
+
has come.
|
|
312
272
|
|
|
313
273
|
When the phone is there, `onStage` gets `{ kind: 'compare', code, same,
|
|
314
|
-
different }`. Show the six digits and ask whether the phone shows the same
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
Each space goes
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
`
|
|
326
|
-
|
|
327
|
-
|
|
274
|
+
different }`. Show the six digits and ask whether the phone shows the same.
|
|
275
|
+
Call `same()` to send the account, or `different()` to end it having sent
|
|
276
|
+
nothing. Then come `sending`, and `sent` once the phone says it arrived.
|
|
277
|
+
Each space goes along as `node.spaces.invite(id)`.
|
|
278
|
+
|
|
279
|
+
### On the phone
|
|
280
|
+
|
|
281
|
+
The phone opens the link at the `pair` stage, and waits for a tap.
|
|
282
|
+
`acceptPairing()` meets the computer and shows the same code
|
|
283
|
+
(`pairingStage` is `{ kind: 'confirm', code }`). The seed arrives only once
|
|
284
|
+
the person confirms on the computer. The phone then signs in, joins each
|
|
285
|
+
space (`{ kind: 'joining', joined, total }`), and ends on `received`.
|
|
286
|
+
|
|
287
|
+
It waits 60 seconds for the computer to answer, and 10 minutes for the
|
|
288
|
+
person to confirm. Where accounts are already kept, `<minca-auth>` warns
|
|
289
|
+
before going on: a link someone else sent would put the phone in their
|
|
328
290
|
account.
|
|
329
291
|
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
292
|
+
After that, the account goes to `unlock` with `setup: 'paired'` if it has no
|
|
293
|
+
way in on this phone yet, else to `ready`.
|
|
294
|
+
|
|
295
|
+
### A phone already signed in
|
|
296
|
+
|
|
297
|
+
A phone that is signed in still gets the `pair` stage. `acceptPairing()`
|
|
298
|
+
stops once the account arrives, before taking it, and sets `pairingArrival`
|
|
299
|
+
to `{ did, account }`. `account` is the summary if this place already keeps
|
|
300
|
+
it, else null. The same account as the one signed in is taken without
|
|
301
|
+
asking, and only its spaces are joined.
|
|
302
|
+
|
|
303
|
+
`answerPairing(true)` adds the account, or switches to it, and keeps the
|
|
304
|
+
other one filed to switch back to. `answerPairing(false)` lets it go.
|
|
305
|
+
`<minca-auth>` asks "Add this account?" or "Switch to <name>?".
|
|
306
|
+
|
|
307
|
+
Switching doesn't sign the other account out: its session key is left as it
|
|
308
|
+
is, as when a tab closes. Only the session open when the account arrives
|
|
309
|
+
counts, so a caller that accepts before `start()` has finished pairs as a
|
|
310
|
+
signed-out phone.
|
|
311
|
+
|
|
312
|
+
`dismissPairing()` stops a pairing at any point before the account is taken.
|
|
313
|
+
The phone leaves, and tells the computer nothing.
|
|
314
|
+
|
|
315
|
+
### Pairing details
|
|
316
|
+
|
|
317
|
+
- The camera opens the link in a new tab. The tab the person started in picks
|
|
318
|
+
up the new sign-in ([staying signed in](#staying-signed-in)).
|
|
319
|
+
- An account home ignores a pairing link on its connect page, so a popup an
|
|
320
|
+
app opened never shows a pairing screen. This is no defence: any page can
|
|
321
|
+
open the account page with the link.
|
|
322
|
+
- `pairingTransport` in the config sets how the two sides reach each other.
|
|
323
|
+
The default is the relay in the ticket. It is for tests, or a host with its
|
|
324
|
+
own.
|
|
325
|
+
|
|
326
|
+
The ticket and the exchange are in
|
|
327
|
+
[spec 01 §15](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md).
|
|
328
|
+
|
|
329
|
+
## Moving into a pod
|
|
330
|
+
|
|
331
|
+
Picking a pod while signed in sets `podChoice` with what the pod holds:
|
|
332
|
+
this account's copy, other accounts, and whether it is the pod in use. Then
|
|
333
|
+
the person chooses:
|
|
334
|
+
|
|
335
|
+
- `confirmPod('switch')` uses the pod's own copy and brings nothing.
|
|
336
|
+
- `confirmPod('combine')` copies the account and every space into the pod,
|
|
337
|
+
keeps the ways in from both, and restarts the session there.
|
|
338
|
+
|
|
339
|
+
`forgetBrowserCopy()` then deletes the browser's copy. Other accounts in the
|
|
340
|
+
pod are never touched.
|
|
341
|
+
|
|
342
|
+
The page writes to the pod only while it is open. A carrier given the same
|
|
343
|
+
folder, such as the Chrome extension, keeps it up to date while the page is
|
|
344
|
+
closed. It learns of the pod when it connects, so one that connected before
|
|
345
|
+
the move must connect again.
|
|
346
|
+
|
|
347
|
+
## Removing an account
|
|
348
|
+
|
|
349
|
+
`removeAccount()` takes an account out of the browser, as clearing its site
|
|
350
|
+
data would. It signs out, then deletes the account's vault, its spaces' data
|
|
351
|
+
and what the home remembered of it.
|
|
352
|
+
|
|
353
|
+
It refuses while an app is connected from here. Only this home can disconnect
|
|
354
|
+
an app, so the apps go first. A revoke that only the app had taken in goes
|
|
355
|
+
with the account, as after a disconnect nobody heard.
|
|
356
|
+
|
|
357
|
+
Copies on other devices, carriers and hosts stay. With none, the account's
|
|
358
|
+
private spaces are gone, and so is anything that reached no other copy. Its
|
|
359
|
+
passkeys stay too, but with the vault gone they open nothing. An account kept
|
|
360
|
+
in a pod is not removed this way: the pod is its copy.
|
|
370
361
|
|
|
371
362
|
## Linking to the account home
|
|
372
363
|
|
|
373
|
-
An app
|
|
374
|
-
|
|
375
|
-
account
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
364
|
+
An app can link to the person's account home, for its settings say.
|
|
365
|
+
`accountHomeLink(home, did, section?)` gives the account page, with the
|
|
366
|
+
account in the fragment, so it never reaches the home's server:
|
|
367
|
+
|
|
368
|
+
```ts
|
|
369
|
+
import { accountHomeLink, popupFeatures } from '@minca/core/session';
|
|
370
|
+
|
|
371
|
+
const home = 'https://home.minca.social/connect';
|
|
372
|
+
window.open(accountHomeLink(home, did, 'notifications'), 'minca', popupFeatures(480, 640));
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
That opens `…#notifications&account=<did>`. `popupFeatures(width, height)`
|
|
376
|
+
centres the popup on the window it opens from. Given only a size, a browser
|
|
377
|
+
puts it where it likes, often the top left of the screen.
|
|
378
|
+
|
|
379
|
+
On the home, `readAccountHint()` gives the DID, or null when there is none or
|
|
380
|
+
it isn't a P-256 `did:key`. `clearAccountHint()` takes it out of the address
|
|
381
|
+
and leaves the section.
|
|
382
|
+
|
|
383
|
+
Any page can open the home with any DID, so the home must treat it as a hint.
|
|
384
|
+
Say which account the app uses, pick it on the sign-in screen, and offer to
|
|
385
|
+
switch. Never sign out or switch on the hint alone. For an account the home
|
|
386
|
+
doesn't keep, never suggest bringing it in: a stranger could name their own
|
|
387
|
+
account, then send a pairing link "to add this browser". Name a kept account
|
|
388
|
+
by the name the home filed, never one from the link. Its avatar helps, but is
|
|
389
|
+
no proof. [Threat model §3.1](https://github.com/leifriksheim/minca/blob/main/spec/threat-model.md)
|
|
390
|
+
|
|
391
|
+
## Options
|
|
392
|
+
|
|
393
|
+
`createMincaAuth(config)` takes the options in
|
|
394
|
+
[`MincaAuthConfig`](https://minca.dev/api/session/interfaces/MincaAuthConfig/).
|
|
395
|
+
Every one has a default, so `createMincaAuth()` alone signs in offline, in
|
|
396
|
+
this browser.
|
|
397
|
+
|
|
398
|
+
## Account stores
|
|
399
|
+
|
|
400
|
+
A folder keeps `accounts.json` and one vault file per account. The library
|
|
401
|
+
lists accounts most recently used first (`lastUsedAt`, else `createdAt`). It
|
|
402
|
+
writes each file as JSON with a 2-space indent and a trailing newline.
|
|
403
|
+
|
|
404
|
+
In the browser, the same shape lives in IndexedDB database
|
|
405
|
+
`minca-accounts`, object store `accounts`. Key `__list` holds the list of
|
|
406
|
+
accounts, and key `<id>` that account's vault. No other site can edit it.
|
|
407
|
+
|
|
408
|
+
The file formats are in
|
|
409
|
+
[spec 01 §14.1](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md).
|
|
410
|
+
|
|
411
|
+
## Device keys and passkeys
|
|
412
|
+
|
|
413
|
+
A device key is made non-extractable, for `encrypt` and `decrypt`. It is
|
|
414
|
+
kept in IndexedDB database `minca-device-keys`, object store `keys`, under
|
|
415
|
+
its id.
|
|
416
|
+
|
|
417
|
+
Someone with a copy of the folder or the vault gets ciphertext and no key.
|
|
418
|
+
The key can't be carried off and used elsewhere. But anything that can run
|
|
419
|
+
script on the site can use the key in place, without the passkey. The passkey
|
|
420
|
+
in front of it is enforced by this code, not by cryptography.
|
|
421
|
+
|
|
422
|
+
**Why passkeys are a gate.** A passkey gives no key material here. The flow
|
|
423
|
+
runs a passkey check before it reaches for a device key, and the seed comes
|
|
424
|
+
from the device key. A passkey could return a secret only through the PRF
|
|
425
|
+
extension, which several major providers don't support or report
|
|
426
|
+
inconsistently. And a passkey belongs to one site, so an identity made from
|
|
427
|
+
it would differ per site. There is no server, so nobody checks the
|
|
428
|
+
assertion's signature. The gate is that the browser finished a verified
|
|
429
|
+
passkey check for the recorded credential.
|
|
430
|
+
|
|
431
|
+
Registration (`navigator.credentials.create`):
|
|
432
|
+
|
|
433
|
+
| Option | Value |
|
|
434
|
+
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
435
|
+
| `rp` | `{ id: rpId, name: appName }` |
|
|
436
|
+
| `user.id` | 32 random bytes, kept as the wrap's `userHandle` (base64url) |
|
|
437
|
+
| `user.name`, `user.displayName` | The account's name |
|
|
438
|
+
| `challenge` | 32 random bytes |
|
|
439
|
+
| `pubKeyCredParams` | ES256 (−7), RS256 (−257) |
|
|
440
|
+
| `authenticatorSelection` | `residentKey: "required"`, `requireResidentKey: true`, `userVerification: "required"`; `authenticatorAttachment: "platform"` when there is one |
|
|
441
|
+
| `hints` | `["client-device"]` when preferring the platform authenticator |
|
|
442
|
+
|
|
443
|
+
Assertion (`navigator.credentials.get`): a random 32-byte challenge,
|
|
444
|
+
`userVerification: "required"`, and `allowCredentials` set to the wrap's
|
|
445
|
+
`credentialId` when known. Neither asks for PRF.
|
|
446
|
+
|
|
447
|
+
Renaming an account asks the passkey provider to rename the passkey too,
|
|
448
|
+
through `PublicKeyCredential.signalCurrentUserDetails`. Not every provider
|
|
449
|
+
does.
|
|
450
|
+
|
|
451
|
+
Device keys in the vault are in
|
|
452
|
+
[spec 01 §12](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md).
|
|
453
|
+
|
|
454
|
+
## The session a sign-in starts
|
|
455
|
+
|
|
456
|
+
A sign-in starts a node with the account's keys, the place's stores for that
|
|
457
|
+
account ([stores](node.md#stores)) and the configured network. The session is a
|
|
458
|
+
[`MincaSession`](https://minca.dev/api/session/interfaces/MincaSession/).
|
|
459
|
+
|
|
460
|
+
The seed stays inside the auth object. `recoveryCode()` returns it as a
|
|
461
|
+
recovery code. The page also holds the local key, which seals a pod's
|
|
462
|
+
registry, as a non-extractable `CryptoKey`, and never hands it out.
|
|
463
|
+
|
|
464
|
+
The account's name follows the account. When another device renames it, this
|
|
465
|
+
one takes the new name for its vault and passkeys. The name is written to the
|
|
466
|
+
account only when it is made and on `rename`.
|
|
398
467
|
|
|
399
468
|
## The account home's side
|
|
400
469
|
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
`
|
|
416
|
-
`
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
470
|
+
An account home built on `createMincaAuth` answers apps with these. What it
|
|
471
|
+
receives, checks and answers is protocol, in
|
|
472
|
+
[spec 06 §2](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md).
|
|
473
|
+
|
|
474
|
+
### Receiving a request
|
|
475
|
+
|
|
476
|
+
`receiveConnectRequest(timeoutMs)` resolves with the first request from the
|
|
477
|
+
window that opened this one, and the origin the browser reports for it. It
|
|
478
|
+
resolves `null` once the opener is closed, or after the timeout, 10 minutes
|
|
479
|
+
by default. Without `window.opener` it does nothing. Answering closes the
|
|
480
|
+
window 100 ms later.
|
|
481
|
+
|
|
482
|
+
### Granting
|
|
483
|
+
|
|
484
|
+
`auth.grant({ origin, request, spaceIds, days? })` makes the grant.
|
|
485
|
+
`spaceIds` are the spaces the person picked. `days` is the lifetime they
|
|
486
|
+
chose, from 1/24 to 365.
|
|
487
|
+
|
|
488
|
+
### Connections
|
|
489
|
+
|
|
490
|
+
`auth.connections()` lists what the home has connected, each a
|
|
491
|
+
[`Connection`](https://minca.dev/api/session/interfaces/Connection/). They are kept
|
|
492
|
+
per account in `localStorage` under `<prefix>.connections:<accountId>`. A kept
|
|
493
|
+
connection in any other shape is dropped when read, and its app connects
|
|
422
494
|
again.
|
|
423
|
-
|
|
424
|
-
the
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
program connected by code
|
|
429
|
-
so each such program is its own (`connectionKey`). A
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
the app
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
(
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
495
|
+
|
|
496
|
+
Connecting the same origin again replaces its connection and revokes nothing.
|
|
497
|
+
The keys it replaced go in `retired`, for disconnecting to revoke. Nothing
|
|
498
|
+
revokes an app just because its time has passed.
|
|
499
|
+
|
|
500
|
+
A program connected by code at the home's own origin (`via: 'code'`) is kept
|
|
501
|
+
by its key instead, so each such program is its own (`connectionKey`). A
|
|
502
|
+
carrier is kept apart from the app at its origin, and connecting one never
|
|
503
|
+
replaces the other.
|
|
504
|
+
|
|
505
|
+
### Disconnecting
|
|
506
|
+
|
|
507
|
+
`auth.disconnect(origin, { audience?, waitMs? })` removes the connections
|
|
508
|
+
from that origin, or only the one with that key. It revokes the keys of
|
|
509
|
+
those with `write` access and every key in their `retired`, and removes the
|
|
510
|
+
automations the app proposed. A carrier at that origin stays.
|
|
511
|
+
|
|
512
|
+
The app hears of it when the revokes reach it. `waitMs` waits up to that
|
|
513
|
+
long for a peer to take them in, and `disconnect` resolves whether one did.
|
|
514
|
+
False means the revokes are still only here: the app keeps working until
|
|
515
|
+
this home is next online with another of the account's devices or apps.
|
|
516
|
+
Without `waitMs`, true only means written. A read-only app or a carrier has
|
|
517
|
+
no key to revoke, so it is true there too. The reference home waits 5 s, and
|
|
518
|
+
says so when nobody took them in.
|
|
519
|
+
|
|
520
|
+
### Signing out
|
|
521
|
+
|
|
522
|
+
`auth.signOut()` forgets the account on this device and revokes the home's
|
|
523
|
+
own session key. Nothing it wrote is lost.
|
|
524
|
+
|
|
525
|
+
The apps connected from here keep working, since they don't need the home
|
|
526
|
+
signed in. Their live use stops when their time runs out, and what they
|
|
527
|
+
write counts until they are disconnected. `signOut({ disconnect: true })`
|
|
528
|
+
disconnects them first, with the programs connected through them and the
|
|
529
|
+
automations they proposed. Carriers stay.
|
|
530
|
+
|
|
531
|
+
Signing out waits up to 5 s (`signOutGraceMs`) for a peer to take in each
|
|
532
|
+
revoke, and `state.signingOut` is true meanwhile. For the home's own key it
|
|
533
|
+
waits only when a peer is connected as signing out starts, so signing out
|
|
534
|
+
alone is quick. With no network, it doesn't wait. With nobody reachable, the
|
|
535
|
+
revokes go out the next time the account signs in here. A read-only app has
|
|
536
|
+
no key to revoke, and loses access when its time runs out.
|
|
537
|
+
|
|
538
|
+
The reference home asks each time, with disconnecting unticked, since
|
|
539
|
+
revoking is for when something is wrong. It grants nothing once signing out
|
|
540
|
+
starts. Choosing another account on the connect page signs out without
|
|
541
|
+
disconnecting.
|
|
542
|
+
|
|
543
|
+
### Proposals
|
|
544
|
+
|
|
545
|
+
`auth.propose({ origin, request, kept? })` adds the automations the person
|
|
546
|
+
kept as the account's own. `kept` is the indices kept, all by default. The
|
|
547
|
+
home lists them by app, where the person can pause or remove them.
|
|
548
|
+
|
|
549
|
+
### Carriers
|
|
550
|
+
|
|
551
|
+
`auth.grantCarry({ origin, request })` adds a carrier with
|
|
552
|
+
`node.carriers.add` ([carriers](node.md#carriers-hosting-and-notifications))
|
|
553
|
+
and returns its `CarryGrant`. It replaces any earlier carrier from that
|
|
554
|
+
origin, never the app there. A carrier's connection never expires, so it is
|
|
555
|
+
kept with `expiresAt: 0`.
|