@minca/core 0.1.16 → 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.
Files changed (125) hide show
  1. package/README.md +10 -9
  2. package/dist/elements/auth-styles.d.ts +1 -1
  3. package/dist/elements/auth-styles.d.ts.map +1 -1
  4. package/dist/elements/auth-styles.js +14 -5
  5. package/dist/elements/auth-styles.js.map +1 -1
  6. package/dist/elements/minca-auth.d.ts.map +1 -1
  7. package/dist/elements/minca-auth.js +18 -15
  8. package/dist/elements/minca-auth.js.map +1 -1
  9. package/dist/files/space-files.d.ts +2 -2
  10. package/dist/files/space-files.d.ts.map +1 -1
  11. package/dist/files/space-files.js +7 -5
  12. package/dist/files/space-files.js.map +1 -1
  13. package/dist/inbox/names.d.ts +1 -1
  14. package/dist/inbox/names.js +1 -1
  15. package/dist/index.d.ts +2 -0
  16. package/dist/index.d.ts.map +1 -1
  17. package/dist/index.js +2 -0
  18. package/dist/index.js.map +1 -1
  19. package/dist/network/ws-transport.d.ts.map +1 -1
  20. package/dist/network/ws-transport.js +3 -0
  21. package/dist/network/ws-transport.js.map +1 -1
  22. package/dist/node/actions.d.ts +5 -0
  23. package/dist/node/actions.d.ts.map +1 -1
  24. package/dist/node/actions.js +39 -20
  25. package/dist/node/actions.js.map +1 -1
  26. package/dist/node/api.d.ts +2 -0
  27. package/dist/node/api.d.ts.map +1 -1
  28. package/dist/node/api.js +2 -0
  29. package/dist/node/api.js.map +1 -1
  30. package/dist/node/carrier.js +1 -1
  31. package/dist/node/carrier.js.map +1 -1
  32. package/dist/node/node-carriers.d.ts.map +1 -1
  33. package/dist/node/node-carriers.js +6 -1
  34. package/dist/node/node-carriers.js.map +1 -1
  35. package/dist/node/node-contacts.d.ts.map +1 -1
  36. package/dist/node/node-contacts.js +1 -0
  37. package/dist/node/node-contacts.js.map +1 -1
  38. package/dist/node/node-hosting.d.ts.map +1 -1
  39. package/dist/node/node-hosting.js +11 -4
  40. package/dist/node/node-hosting.js.map +1 -1
  41. package/dist/node/node-records.d.ts.map +1 -1
  42. package/dist/node/node-records.js +6 -1
  43. package/dist/node/node-records.js.map +1 -1
  44. package/dist/node/node.d.ts.map +1 -1
  45. package/dist/node/node.js +14 -1
  46. package/dist/node/node.js.map +1 -1
  47. package/dist/node/remote.d.ts.map +1 -1
  48. package/dist/node/remote.js +7 -1
  49. package/dist/node/remote.js.map +1 -1
  50. package/dist/node/space-holding.d.ts +7 -3
  51. package/dist/node/space-holding.d.ts.map +1 -1
  52. package/dist/node/space-holding.js +90 -18
  53. package/dist/node/space-holding.js.map +1 -1
  54. package/dist/node/space-peers.d.ts.map +1 -1
  55. package/dist/node/space-peers.js +58 -24
  56. package/dist/node/space-peers.js.map +1 -1
  57. package/dist/node/space-runtime.d.ts +11 -3
  58. package/dist/node/space-runtime.d.ts.map +1 -1
  59. package/dist/node/space-runtime.js +22 -1
  60. package/dist/node/space-runtime.js.map +1 -1
  61. package/dist/node/space-writing.d.ts +2 -0
  62. package/dist/node/space-writing.d.ts.map +1 -1
  63. package/dist/node/space-writing.js +2 -0
  64. package/dist/node/space-writing.js.map +1 -1
  65. package/dist/node/types.d.ts +130 -36
  66. package/dist/node/types.d.ts.map +1 -1
  67. package/dist/query/types.d.ts +1 -0
  68. package/dist/query/types.d.ts.map +1 -1
  69. package/dist/query/types.js.map +1 -1
  70. package/dist/records/contract-builder.d.ts +22 -6
  71. package/dist/records/contract-builder.d.ts.map +1 -1
  72. package/dist/records/contract-builder.js.map +1 -1
  73. package/dist/schemas/automations.d.ts +6 -2
  74. package/dist/schemas/automations.d.ts.map +1 -1
  75. package/dist/schemas/automations.js.map +1 -1
  76. package/dist/schemas/connectors.d.ts +4 -3
  77. package/dist/schemas/connectors.d.ts.map +1 -1
  78. package/dist/schemas/connectors.js +4 -3
  79. package/dist/schemas/connectors.js.map +1 -1
  80. package/dist/schemas/library/media.js +1 -1
  81. package/dist/schemas/library/media.js.map +1 -1
  82. package/dist/schemas/library/social.d.ts +258 -0
  83. package/dist/schemas/library/social.d.ts.map +1 -1
  84. package/dist/schemas/library/social.js +28 -1
  85. package/dist/schemas/library/social.js.map +1 -1
  86. package/dist/session/auth.d.ts +7 -3
  87. package/dist/session/auth.d.ts.map +1 -1
  88. package/dist/session/auth.js.map +1 -1
  89. package/dist/session/hosting.d.ts.map +1 -1
  90. package/dist/session/hosting.js +8 -2
  91. package/dist/session/hosting.js.map +1 -1
  92. package/dist/space/presets.d.ts +2 -2
  93. package/dist/space/presets.d.ts.map +1 -1
  94. package/dist/space/presets.js +3 -2
  95. package/dist/space/presets.js.map +1 -1
  96. package/dist/storage/blob-store.d.ts +3 -0
  97. package/dist/storage/blob-store.d.ts.map +1 -1
  98. package/dist/types.d.ts +11 -2
  99. package/dist/types.d.ts.map +1 -1
  100. package/dist/types.js.map +1 -1
  101. package/docs/README.md +86 -93
  102. package/docs/actions.md +212 -144
  103. package/docs/agents.md +198 -155
  104. package/docs/automations.md +296 -204
  105. package/docs/blueprints-and-guides.md +405 -295
  106. package/docs/bots.md +208 -134
  107. package/docs/building-an-app.md +74 -163
  108. package/docs/collections.md +248 -328
  109. package/docs/computed.md +112 -89
  110. package/docs/contacts.md +151 -112
  111. package/docs/contracts.md +299 -120
  112. package/docs/direct-messages.md +80 -61
  113. package/docs/inbox.md +138 -93
  114. package/docs/node.md +1072 -972
  115. package/docs/permissions.md +142 -0
  116. package/docs/proposing-collections.md +74 -55
  117. package/docs/query-format.md +150 -126
  118. package/docs/records-and-queries.md +205 -126
  119. package/docs/sign-in.md +496 -418
  120. package/docs/spaces.md +261 -245
  121. package/docs/standard-library.md +473 -504
  122. package/docs/storage.md +325 -348
  123. package/docs/usernames.md +164 -97
  124. package/docs/warrants.md +100 -67
  125. package/package.json +1 -2
package/docs/sign-in.md CHANGED
@@ -1,260 +1,208 @@
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.
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
- ## Places
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
- A **place** is where accounts and their data are kept (`Place`):
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
- | `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 |
33
+ const auth = createMincaAuth({ appName: 'Todo', network: { relays: ['wss://relay.minca.social'] } });
21
34
 
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).
35
+ function App() {
36
+ const { state } = useMinca();
37
+ if (state?.stage !== 'ready') return <MincaAuth />;
38
+ return <p>Signed in.</p>;
39
+ }
26
40
 
27
- _Source: `packages/core/src/session/places.ts`. Tests: `packages/core/tests/account-store.test.ts`._
41
+ createRoot(root).render(
42
+ <MincaProvider auth={auth}>
43
+ <App />
44
+ </MincaProvider>,
45
+ );
46
+ ```
28
47
 
29
- ## Account stores
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
- 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.
52
+ ## Places
53
+
54
+ A place is where accounts and their data are kept. There are two kinds:
36
55
 
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.
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
- _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")._
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
- `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")._
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
- - **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`._
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
- 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")._
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 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.
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
- Registration (`navigator.credentials.create`):
210
-
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 |
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
- 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.
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
- Renaming an account asks the provider to relabel the passkey through the
226
- WebAuthn Signal API (`PublicKeyCredential.signalCurrentUserDetails` with the
227
- `userHandle`); best effort.
172
+ ## Staying signed in
228
173
 
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._
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
- ## The session a sign-in starts
178
+ ```ts
179
+ import { createMincaAuth } from '@minca/core/session';
232
180
 
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.
181
+ const auth = createMincaAuth();
182
+ await auth.staySignedIn.setChoice('30d');
183
+ auth.staySignedIn.until(); // a Date, or null
184
+ ```
240
185
 
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.
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
- ## Staying signed in
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
- 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.
196
+ The flow keeps these in `localStorage`, where `<prefix>` is `storageKey` in
197
+ the config, default `minca`:
255
198
 
256
- _Implementation detail:_ kept in `localStorage` as `<prefix>.stay-signed-in`
257
- (the choice) and `<prefix>.remembered-session`:
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
- 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`.
216
+ These are implementation details. Don't read them from your app.
271
217
 
272
- _Source: `packages/core/src/session/stay-signed-in.ts`, `packages/core/src/session/auth.ts`. Tests: none._
218
+ ## Proving it is you
273
219
 
274
- ## Moving into a pod
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
- 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.
224
+ ```ts
225
+ import { createMincaAuth } from '@minca/core/session';
295
226
 
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.
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
- _Source: `packages/core/src/session/auth.ts` (`confirmPod`), `packages/core/src/session/places.ts`. Tests: `packages/core/tests/account.test.ts`._
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
- 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
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, and stops working after two minutes if no
311
- phone has.
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
- 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
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
- 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")._
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 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`._
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
- 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
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
- 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")._
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`.