@minca/core 0.1.17 → 0.2.0

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