@minca/core 0.1.7 → 0.1.9

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 (154) hide show
  1. package/dist/elements/auth-styles.d.ts +1 -1
  2. package/dist/elements/auth-styles.d.ts.map +1 -1
  3. package/dist/elements/auth-styles.js +16 -8
  4. package/dist/elements/auth-styles.js.map +1 -1
  5. package/dist/elements/minca-auth.d.ts +7 -0
  6. package/dist/elements/minca-auth.d.ts.map +1 -1
  7. package/dist/elements/minca-auth.js +107 -49
  8. package/dist/elements/minca-auth.js.map +1 -1
  9. package/dist/files/file-id.d.ts +51 -0
  10. package/dist/files/file-id.d.ts.map +1 -0
  11. package/dist/files/file-id.js +97 -0
  12. package/dist/files/file-id.js.map +1 -0
  13. package/dist/files/seal.d.ts +20 -0
  14. package/dist/files/seal.d.ts.map +1 -0
  15. package/dist/files/seal.js +77 -0
  16. package/dist/files/seal.js.map +1 -0
  17. package/dist/files/space-files.d.ts +51 -0
  18. package/dist/files/space-files.d.ts.map +1 -0
  19. package/dist/files/space-files.js +476 -0
  20. package/dist/files/space-files.js.map +1 -0
  21. package/dist/index.d.ts +5 -4
  22. package/dist/index.d.ts.map +1 -1
  23. package/dist/index.js +3 -2
  24. package/dist/index.js.map +1 -1
  25. package/dist/node/api.d.ts +6 -1
  26. package/dist/node/api.d.ts.map +1 -1
  27. package/dist/node/api.js +17 -3
  28. package/dist/node/api.js.map +1 -1
  29. package/dist/node/carrier.d.ts +17 -2
  30. package/dist/node/carrier.d.ts.map +1 -1
  31. package/dist/node/carrier.js +26 -4
  32. package/dist/node/carrier.js.map +1 -1
  33. package/dist/node/copy.d.ts +0 -4
  34. package/dist/node/copy.d.ts.map +1 -1
  35. package/dist/node/copy.js +26 -0
  36. package/dist/node/copy.js.map +1 -1
  37. package/dist/node/host.d.ts +66 -1
  38. package/dist/node/host.d.ts.map +1 -1
  39. package/dist/node/host.js +571 -5
  40. package/dist/node/host.js.map +1 -1
  41. package/dist/node/index.d.ts +2 -2
  42. package/dist/node/index.d.ts.map +1 -1
  43. package/dist/node/index.js +1 -1
  44. package/dist/node/index.js.map +1 -1
  45. package/dist/node/node.d.ts.map +1 -1
  46. package/dist/node/node.js +235 -75
  47. package/dist/node/node.js.map +1 -1
  48. package/dist/node/space-runtime.d.ts +9 -0
  49. package/dist/node/space-runtime.d.ts.map +1 -1
  50. package/dist/node/space-runtime.js +125 -16
  51. package/dist/node/space-runtime.js.map +1 -1
  52. package/dist/node/stores.d.ts +44 -8
  53. package/dist/node/stores.d.ts.map +1 -1
  54. package/dist/node/stores.js +44 -7
  55. package/dist/node/stores.js.map +1 -1
  56. package/dist/node/types.d.ts +73 -6
  57. package/dist/node/types.d.ts.map +1 -1
  58. package/dist/node/usage.d.ts +54 -0
  59. package/dist/node/usage.d.ts.map +1 -0
  60. package/dist/node/usage.js +201 -0
  61. package/dist/node/usage.js.map +1 -0
  62. package/dist/node/writer-keys.d.ts +4 -1
  63. package/dist/node/writer-keys.d.ts.map +1 -1
  64. package/dist/node/writer-keys.js +25 -6
  65. package/dist/node/writer-keys.js.map +1 -1
  66. package/dist/node/writers.d.ts.map +1 -1
  67. package/dist/node/writers.js +10 -3
  68. package/dist/node/writers.js.map +1 -1
  69. package/dist/react/minca-auth.d.ts +3 -1
  70. package/dist/react/minca-auth.d.ts.map +1 -1
  71. package/dist/react/minca-auth.js +5 -3
  72. package/dist/react/minca-auth.js.map +1 -1
  73. package/dist/schema/version.d.ts +5 -0
  74. package/dist/schema/version.d.ts.map +1 -1
  75. package/dist/schema/version.js +1 -0
  76. package/dist/schema/version.js.map +1 -1
  77. package/dist/schemas/fragments.d.ts +23 -2
  78. package/dist/schemas/fragments.d.ts.map +1 -1
  79. package/dist/schemas/fragments.js +5 -2
  80. package/dist/schemas/fragments.js.map +1 -1
  81. package/dist/schemas/library/annotations.d.ts +24 -0
  82. package/dist/schemas/library/annotations.d.ts.map +1 -1
  83. package/dist/schemas/library/community.d.ts +24 -0
  84. package/dist/schemas/library/community.d.ts.map +1 -1
  85. package/dist/schemas/library/life.d.ts +72 -0
  86. package/dist/schemas/library/life.d.ts.map +1 -1
  87. package/dist/schemas/library/media.d.ts +144 -0
  88. package/dist/schemas/library/media.d.ts.map +1 -1
  89. package/dist/schemas/library/money.d.ts +24 -0
  90. package/dist/schemas/library/money.d.ts.map +1 -1
  91. package/dist/schemas/library/publishing.d.ts +96 -0
  92. package/dist/schemas/library/publishing.d.ts.map +1 -1
  93. package/dist/schemas/library/social.d.ts +72 -0
  94. package/dist/schemas/library/social.d.ts.map +1 -1
  95. package/dist/session/account-hint.d.ts +13 -0
  96. package/dist/session/account-hint.d.ts.map +1 -0
  97. package/dist/session/account-hint.js +51 -0
  98. package/dist/session/account-hint.js.map +1 -0
  99. package/dist/session/auth.d.ts +51 -3
  100. package/dist/session/auth.d.ts.map +1 -1
  101. package/dist/session/auth.js +262 -36
  102. package/dist/session/auth.js.map +1 -1
  103. package/dist/session/connect.d.ts.map +1 -1
  104. package/dist/session/connect.js +6 -2
  105. package/dist/session/connect.js.map +1 -1
  106. package/dist/session/hosting.d.ts +73 -28
  107. package/dist/session/hosting.d.ts.map +1 -1
  108. package/dist/session/hosting.js +85 -5
  109. package/dist/session/hosting.js.map +1 -1
  110. package/dist/session/index.d.ts +1 -0
  111. package/dist/session/index.d.ts.map +1 -1
  112. package/dist/session/index.js +1 -0
  113. package/dist/session/index.js.map +1 -1
  114. package/dist/session/pairing.d.ts +2 -0
  115. package/dist/session/pairing.d.ts.map +1 -1
  116. package/dist/session/pairing.js +8 -0
  117. package/dist/session/pairing.js.map +1 -1
  118. package/dist/session/places.d.ts +7 -0
  119. package/dist/session/places.d.ts.map +1 -1
  120. package/dist/session/places.js +20 -2
  121. package/dist/session/places.js.map +1 -1
  122. package/dist/space/account-registry.d.ts +13 -0
  123. package/dist/space/account-registry.d.ts.map +1 -1
  124. package/dist/space/account-registry.js +13 -0
  125. package/dist/space/account-registry.js.map +1 -1
  126. package/dist/storage/blob/directory.d.ts +14 -0
  127. package/dist/storage/blob/directory.d.ts.map +1 -0
  128. package/dist/storage/blob/directory.js +80 -0
  129. package/dist/storage/blob/directory.js.map +1 -0
  130. package/dist/storage/folder-adapter.d.ts +22 -0
  131. package/dist/storage/folder-adapter.d.ts.map +1 -1
  132. package/dist/storage/folder-adapter.js +5 -5
  133. package/dist/storage/folder-adapter.js.map +1 -1
  134. package/dist/storage/mirror.d.ts +9 -2
  135. package/dist/storage/mirror.d.ts.map +1 -1
  136. package/dist/storage/mirror.js +60 -35
  137. package/dist/storage/mirror.js.map +1 -1
  138. package/dist/storage/segment.d.ts +7 -2
  139. package/dist/storage/segment.d.ts.map +1 -1
  140. package/dist/storage/segment.js +25 -3
  141. package/dist/storage/segment.js.map +1 -1
  142. package/dist/sync/sync-engine.d.ts +2 -0
  143. package/dist/sync/sync-engine.d.ts.map +1 -1
  144. package/dist/sync/sync-engine.js +5 -0
  145. package/dist/sync/sync-engine.js.map +1 -1
  146. package/dist/sync/sync-messages.d.ts +24 -0
  147. package/dist/sync/sync-messages.d.ts.map +1 -1
  148. package/dist/sync/sync-messages.js.map +1 -1
  149. package/docs/node.md +63 -24
  150. package/docs/sign-in.md +123 -24
  151. package/docs/spaces.md +18 -10
  152. package/docs/standard-library.md +16 -20
  153. package/docs/storage.md +120 -15
  154. package/package.json +1 -1
@@ -73,6 +73,30 @@ export type SyncMessage = V &
73
73
  | {
74
74
  readonly type: 'stored';
75
75
  readonly ids: ReadonlyArray<string>;
76
+ }
77
+ /** "Send me these chunks of a file, or its chunk list" (spec 05 §16.6) */
78
+ | {
79
+ readonly type: 'want-file';
80
+ readonly id: number;
81
+ readonly hash: string;
82
+ readonly chunks?: readonly [number, number];
83
+ readonly list?: true;
84
+ }
85
+ /** Part of a chunk, or of the chunk list: `bytes` base64url, from `at` */
86
+ | {
87
+ readonly type: 'file';
88
+ readonly id: number;
89
+ readonly hash: string;
90
+ readonly chunk: number | 'list';
91
+ readonly at: number;
92
+ readonly bytes: string;
93
+ }
94
+ /** The last answer to a `want-file`: what was asked and not sent */
95
+ | {
96
+ readonly type: 'file-done';
97
+ readonly id: number;
98
+ readonly hash: string;
99
+ readonly missing: ReadonlyArray<number | 'list'>;
76
100
  });
77
101
  /** A message before the version is stamped on — what callers construct. */
78
102
  export type SyncMessageBody = SyncMessage extends infer M ? (M extends V ? Omit<M, 'v'> : never) : never;
@@ -1 +1 @@
1
- {"version":3,"file":"sync-messages.d.ts","sourceRoot":"","sources":["../../src/sync/sync-messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAG3C,4FAA4F;AAC5F,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,KAAK,CAAC,GAAG;IAAE,QAAQ,CAAC,CAAC,EAAE,OAAO,qBAAqB,CAAA;CAAE,CAAC;AAEtD,MAAM,MAAM,WAAW,GAAG,CAAC;AACzB;;;;;;GAMG;AACH,CACI;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AACH;;;GAGG;GACD;IACE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AACH,uGAAuG;GACrG;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE;AACvG,6DAA6D;GAC3D;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAAE;AACrF;;;GAGG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;CAAE;AAChG,4EAA4E;GAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE;AAC7D;;;;GAIG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAAE,CACnE,CAAC;AAEJ,2EAA2E;AAC3E,MAAM,MAAM,eAAe,GAAG,WAAW,SAAS,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC;AAEzG,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAEnE"}
1
+ {"version":3,"file":"sync-messages.d.ts","sourceRoot":"","sources":["../../src/sync/sync-messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAG3C,4FAA4F;AAC5F,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,KAAK,CAAC,GAAG;IAAE,QAAQ,CAAC,CAAC,EAAE,OAAO,qBAAqB,CAAA;CAAE,CAAC;AAEtD,MAAM,MAAM,WAAW,GAAG,CAAC;AACzB;;;;;;GAMG;AACH,CACI;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AACH;;;GAGG;GACD;IACE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AACH,uGAAuG;GACrG;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE;AACvG,6DAA6D;GAC3D;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAAE;AACrF;;;GAGG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;CAAE;AAChG,4EAA4E;GAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE;AAC7D;;;;GAIG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAAE;AAClE,0EAA0E;GACxE;IACE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;CACtB;AACH,0EAA0E;GACxE;IACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AACH,oEAAoE;GAClE;IACE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;CAClD,CACJ,CAAC;AAEJ,2EAA2E;AAC3E,MAAM,MAAM,eAAe,GAAG,WAAW,SAAS,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC;AAEzG,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAEnE"}
@@ -1 +1 @@
1
- {"version":3,"file":"sync-messages.js","sourceRoot":"","sources":["../../src/sync/sync-messages.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,4FAA4F;AAC5F,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAmDvC,4EAA4E;AAC5E,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7C,CAAC;AAED,8FAA8F;AAC9F,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,KAAK,qBAAqB,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC;AAChG,CAAC"}
1
+ {"version":3,"file":"sync-messages.js","sourceRoot":"","sources":["../../src/sync/sync-messages.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,4FAA4F;AAC5F,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AA2EvC,4EAA4E;AAC5E,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7C,CAAC;AAED,8FAA8F;AAC9F,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,KAAK,qBAAqB,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC;AAChG,CAAC"}
package/docs/node.md CHANGED
@@ -27,7 +27,7 @@ conveniences.
27
27
  | `sessionTtlSeconds` | number, optional | Lifetime of each session note. Default `3600`. |
28
28
  | `sessionKey` | `CryptoKeyPair`, optional | Sign with this key instead of a fresh one. Used when the signer's note names a specific key (an app's key, an agent's key, [spec 06 §2](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md), [spec 06 §3](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)). |
29
29
  | `writerKey` | `WriterKeySource`, optional | Keep a signing key across runs, so this device keeps one log in each space ([writer keys](#writer-keys)). Ignored with `sessionKey`. |
30
- | `watchIntervalMs` | number, optional | How often to look for writes another process made to a folder store. `0` disables. Default `2000`. _Implementation detail._ |
30
+ | `watchIntervalMs` | number, optional | How often to look for writes another app, device or process made: a data folder's segments, a store file another process shares. `0` disables. Default `2000`. _Implementation detail._ |
31
31
  | `cache` | `CacheConfig`, optional | Hold only the collections used, in spaces that name a keeper ([holding part of a space](#holding-part-of-a-space)). |
32
32
  | `mailbox` | `MailboxClient`, optional | How doors reach relays' mailboxes ([07](https://github.com/leifriksheim/minca/blob/main/spec/07-doors.md)). Default: a WebSocket to each relay. |
33
33
 
@@ -165,9 +165,13 @@ What a path means is the factory's choice:
165
165
  - `indexedDBStores(prefix)` — one IndexedDB database per path, named
166
166
  `<prefix>:<path with / replaced by :>`. Never sealed: the browser profile
167
167
  already guards it.
168
- - `folderStores(directory, { basePath?, localKey? })` — a directory tree under
169
- `basePath`; the `registry` is sealed under `localKey` (`deriveLocalKey(seed)`)
170
- when one is given.
168
+ - `folderStores(directory, { basePath?, localKey?, local? })` — a data folder
169
+ ([sync and storage](storage.md#data-folders)): the `registry` in the folder
170
+ under `basePath`, sealed under `localKey` (`deriveLocalKey(seed)`) when one
171
+ is given; every other path in `local`; and each space mirrored to the
172
+ folder's segments, which the factory names as `folder`.
173
+ - `directoryStores(directory, { localKey? })` — a directory on this device,
174
+ one file per entry and per version; the `registry` sealed as above.
171
175
 
172
176
  Every version a node signs in a space takes the next place in its key's line
173
177
  for that collection there ([spec 02 §4.10](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)).
@@ -210,7 +214,21 @@ node makes a key for this run as it would without a source.
210
214
  whether its stores are in IndexedDB or a data folder, so signing out
211
215
  (`deleteBrowserData`) deletes the keys too. The key never goes in the data
212
216
  folder, which other apps and devices share.
213
- - The CLI keeps them in `~/.minca/writers/<account id>/slot-<n>/`: the key as
217
+ - `forget()` drops the key but keeps its places, which still count while it
218
+ signs this run; the slot's next claim makes a new key and clears them.
219
+ `revokeSelf` forgets the claimed key before it writes a single revoke, so a
220
+ page closed while the revokes wait leaves no revoked key to claim again.
221
+ With a peer connected in any open space, each revoke waits up to
222
+ `waitMs` for one to take it in; with none, none wait. A node that claims a
223
+ key the account registry has revoked anyway (one forgotten by an older
224
+ version, say) forgets it and starts again on a key for this run alone; the
225
+ next start claims a new lasting one.
226
+ - A node never signs at a place behind one it took itself this run: if the
227
+ slot has lost them (site data cleared while the page was open), every
228
+ write fails until the page reloads, since signing on would fork the line
229
+ and withdraw what the key wrote. A slot whose connection the browser
230
+ closed opens again only while it still holds the key.
231
+ - The CLI keeps them outside its home, in `<local>/writers/slot-<n>/` (`localPath` in `packages/cli/src/home.ts`, [sync and storage](storage.md#data-folders)): the key as
214
232
  JWK in an envelope (spec 01 §9.1) under the account's local key, with label
215
233
  `minca/writer-key/v1` and bound `{ did: <account DID>, slot: <n> }`
216
234
  (`key.sealed`, mode 600), so a copy of the files can't sign, and a key file
@@ -218,7 +236,7 @@ node makes a key for this run as it would without a source.
218
236
  `heads/`; and a `lock` file naming the process that holds it, taken over
219
237
  once that process is gone.
220
238
 
221
- _Source: `packages/core/src/node/writer-keys.ts` (`browserWriterKeys`), `packages/core/src/node/stores.ts` (`writerKeysFor`), `packages/core/src/node/worker.ts` (`withWriterKey`), `packages/cli/src/writer-keys.ts` (`fileWriterKeys`), `packages/cli/src/home.ts` (`unlock`, `nodeFor`). Tests: `packages/core/tests/writer-logs.test.ts` ("a writer key that outlives the node"), `packages/cli/tests/writer-keys.test.ts` ("a key file moved to another slot, or to another account, does not open")._
239
+ _Source: `packages/core/src/node/writer-keys.ts` (`browserWriterKeys`), `packages/core/src/node/writers.ts` (`createWriters`), `packages/core/src/node/node.ts` (`createNode`, `revokeSelf`), `packages/core/src/node/stores.ts` (`writerKeysFor`), `packages/core/src/node/worker.ts` (`withWriterKey`), `packages/cli/src/writer-keys.ts` (`fileWriterKeys`), `packages/cli/src/home.ts` (`unlock`, `nodeFor`). Tests: `packages/core/tests/writer-logs.test.ts` ("a writer key that outlives the node"), `packages/cli/tests/writer-keys.test.ts` ("a key file moved to another slot, or to another account, does not open")._
222
240
 
223
241
  Sign-in ([sign-in](sign-in.md)) uses `storesFor(account)`: IndexedDB with prefix
224
242
  `minca:<dataPath with : for />` in the browser, or `folderStores(pod,
@@ -228,7 +246,8 @@ by default. These names are _implementation details_ ([sync and storage](storage
228
246
  a pod's layout is in
229
247
  [05](https://github.com/leifriksheim/minca/blob/main/spec/05-sync-and-storage.md).
230
248
  A node also opens `mirrors/<spaceId>/<n>` for a mirror's writer state
231
- ([mirrors](storage.md#mirrors)), and a host `host` for its subscriptions.
249
+ ([mirrors](storage.md#mirrors)), `folder/<spaceId>` for a data folder's, and
250
+ a host `host` for its subscriptions.
232
251
 
233
252
  `copyAccountData({ from, to, did, accountKey? })` copies every space an
234
253
  account holds, with its key and records, from one set of stores to another —
@@ -572,7 +591,8 @@ successors, mine, heads, key, relays, keepers, copies, forks, flagged }`
572
591
  with at most one more queued.
573
592
  - `node.account` — `profile()`, `setName(name)` (writes `sys.profile`, key
574
593
  `profile`, in the account registry, then republishes the profile in every
575
- open space), `revoke(key, { waitMs? })` (one of the account's keys, by DID, in the account registry). All need the account
594
+ open space), `setAvatar({ bytes, mime } | null, { name? })` and `picture()`
595
+ (the account's picture, likewise; see [spaces](spaces.md)), `revoke(key, { waitMs? })` (one of the account's keys, by DID, in the account registry). All need the account
576
596
  key.
577
597
  - `spaces.revoke(space, key, { waitMs? })` and `account.revoke` resolve once the revoke is written; with
578
598
  `waitMs`, once a peer says it has taken it in, or that long has passed (`true` when one did). A node
@@ -805,7 +825,15 @@ are protocol ([spec 06 §4](https://github.com/leifriksheim/minca/blob/main/spec
805
825
  the carry space, named `Carried by <name>` (name trimmed to 80, default
806
826
  `Carrier`), writes the `sys.carrier` record, fills the carry space, and returns
807
827
  `{ space, invite }` for the carrier to join with; for a carrier it already
808
- has, by `did`, it returns that one's. `node.carriers.reached(carrySpace, waitMs)`
828
+ has, by `did`, it returns that one's. If the record can't be written, it
829
+ takes the carry space back out before failing, so a restart never lists it as
830
+ a space the account uses. A node that starts, or hears the registry change,
831
+ refills every carrier's carry space in the background: it opens every space
832
+ the account holds, which from a data folder is slow, and signing in doesn't
833
+ wait for it. Adding an automation doesn't either (adding a carrier writes that
834
+ carrier's passes before it returns):
835
+ `node.carriers.settled(waitMs)` waits up to `waitMs` for the refill under way
836
+ and says whether it finished, for a window about to close. `node.carriers.reached(carrySpace, waitMs)`
809
837
  waits up to `waitMs` for the node to be level with the carrier in the carry
810
838
  space and then the account registry, and says whether it was: a node about to
811
839
  close (the home's window, once it has answered) waits on it, so what it wrote
@@ -827,18 +855,18 @@ holds. Nothing shows these yet, the browser extension included.
827
855
 
828
856
  **Hosting.** `node.hosting`:
829
857
 
830
- | Call | Does |
831
- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
832
- | `use(url)` | Reads the host's description, makes the subscription key and writes the `sys.hosting` record. |
833
- | `list()` | Asks each host for its status and hands over the carry space when paid and not carrying, making the carrier first if needed (named after the host's address). At most once a minute per host; a second look waits for a handover in flight. |
834
- | `pay(url, plan)` | Asks the host to start one of its plans (`HostingView.plans`): a pay answer, `checkout` (a page to open in a new tab with no opener) or `request` (a payment for a wallet, shown by the app). Call `list()` until the status moves. |
835
- | `manage(url)` | The payment provider's page to change a card or cancel it, as a `checkout` answer. |
836
- | `remind(url, email)` | Asks the host to email a reminder before paid time runs out; it mails a link to confirm first. |
837
- | `stop(url)` | Sends `DELETE …/carry` (ignoring failure), removes the carrier and deletes the `sys.hosting` record. |
838
- | `space(id)` | The hosts a space names in `std.host`, each asked how the space's own subscription stands, with its plans for spaces (below). |
839
- | `payForSpace(id, url, { amount, method, monthly? })`, `remindForSpace(id, url, email)` | Adds to a space's fund at a host it names (dollars, by `checkout` or `request`, monthly by card), and asks for reminders before it runs out. Anyone in it may. `space(id)` gives each host's `fund` offer, and in its status the `balance`, `daily` spend and `bots`. |
840
- | `startBot(id, url, { name, role? })` | Asks a host the space names to run a bot there ([spec 08 §3](https://github.com/leifriksheim/minca/blob/main/spec/08-hosting.md)): makes an invite for `role` (by default as `spaces.invite` picks one) and hands it over. The host holds the bot's keys, so an app says so first. |
841
- | `stopForSpace(id, url)` | Stops a space using a host it names: deletes its `std.host` record, removes the host's bots and changes the key (below). |
858
+ | Call | Does |
859
+ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
860
+ | `use(url)` | Reads the host's description, makes the subscription key and writes the `sys.hosting` record. |
861
+ | `list()` | Asks each host for its status and hands over the carry space when paid and not carrying, making the carrier first if needed (named after the host's address). At most once a minute per host; a second look waits for a handover in flight. |
862
+ | `pay(url, { amount, method, monthly? })` | Adds to the account's balance at the host (dollars, by `checkout` or `request`, monthly by card, as its `HostingView.fund` says): a pay answer, `checkout` (a page to open in a new tab with no opener) or `request` (a payment for a wallet, shown by the app). Call `list()` until the balance moves. |
863
+ | `remind(url, email)` | Asks the host to email a reminder before paid time runs out; it mails a link to confirm first. |
864
+ | `stop(url)` | Sends `DELETE …/carry` (ignoring failure), removes the carrier and deletes the `sys.hosting` record. |
865
+ | `space(id)` | The hosts a space names in `std.host`, each asked how the space's own subscription stands, with how its fund is paid into (below). |
866
+ | `over(id)` | The account's hosts whose last status says the space is over their free line, each `{ url, name, over }` (`over.until`, `over.reasons`), from the receipts in `sys.hosting`: asks no host. An agent may call it for a space it was given. |
867
+ | `payForSpace(id, url, { amount, method, monthly? })`, `remindForSpace(id, url, email)` | Adds to a space's fund at a host it names (dollars, by `checkout` or `request`, monthly by card), and asks for reminders before it runs out. Anyone in it may. `space(id)` gives each host's `fund` offer, and in its status the `balance`, `daily` spend and `bots`. |
868
+ | `startBot(id, url, { name, role? })` | Asks a host the space names to run a bot there ([spec 08 §3](https://github.com/leifriksheim/minca/blob/main/spec/08-hosting.md)): makes an invite for `role` (by default as `spaces.invite` picks one) and hands it over. The host holds the bot's keys, so an app says so first. |
869
+ | `stopForSpace(id, url)` | Stops a space using a host it names: deletes its `std.host` record, removes the host's bots and changes the key (below). |
842
870
 
843
871
  Every device runs `list()` after each reconciliation ([following the account](#following-the-account)).
844
872
  A device reaches a host at the socket its description names (`peer`,
@@ -860,13 +888,24 @@ The reference host (`minca host`, `packages/cli/src/host.ts`) keeps a lapsed
860
888
  subscription for `graceDays` (default 30) after `paidUntil`, and drops lapsed
861
889
  ones in a sweep every hour (`sweepMs`). It measures each carried space's
862
890
  folder at most every ten minutes, and each status gives the sum as `bytes`,
863
- with `quotaBytes` as `quota` (`MINCA_HOST_QUOTA_GB`: 10 on a paying host, none
864
- on a free one). At its quota, an account's carry space takes no new space
891
+ with `quotaBytes` as `quota` (`MINCA_HOST_QUOTA_GB`, none unless set, at a
892
+ host without limits). At its quota, an account's carry space takes no new space
865
893
  (`full`, in `createCarryCore`): what it carries stays and keeps syncing, and a
866
894
  space that waited is taken once a later measure finds room. All of this is the
867
895
  host's own policy.
868
896
 
869
- _Source: `packages/core/src/node/node.ts` (`carriers`, `notifications`, `hosting`), `packages/core/src/node/carrier.ts` (`arrived`), `packages/core/src/session/hosting.ts`, `packages/cli/src/host.ts`. Tests: `packages/core/tests/carrier.test.ts`, `packages/cli/tests/host.test.ts`._
897
+ With `limits` ([spec 08 §1.1](https://github.com/leifriksheim/minca/blob/main/spec/08-hosting.md),
898
+ `MINCA_HOST_FREE_GB`), an account's subscription is active with nothing paid,
899
+ its `plan` `free` until it pays, and its quota by plan; a device hands such a
900
+ host its carry space as it would a free one. A space its own fund pays for
901
+ takes none of its members' room. The host counts each carried space's writers
902
+ as versions arrive (`onArrived`, in `createCarryCore`) and its readers as
903
+ sockets prove themselves (`onPeer`, `packages/cli/src/serve.ts`), and once an
904
+ hour (`evaluate`) holds each to the free line. Past a space's `until`, every
905
+ account's carry space stops carrying it (`skip`, in `createCarryCore`), while
906
+ its own subscription still may. Each change is a line in the host's log.
907
+
908
+ _Source: `packages/core/src/node/node.ts` (`carriers`, `notifications`, `hosting`), `packages/core/src/node/carrier.ts` (`arrived`, `skip`, `onArrived`), `packages/core/src/node/host.ts` (`evaluate`), `packages/core/src/session/hosting.ts`, `packages/cli/src/host.ts`. Tests: `packages/core/tests/carrier.test.ts`, `packages/core/tests/host-limits.test.ts`, `packages/cli/tests/host.test.ts`._
870
909
 
871
910
  ### A space paying for itself
872
911
 
package/docs/sign-in.md CHANGED
@@ -60,26 +60,36 @@ _Source: `packages/core/src/identity/account-store.ts`. Tests: `packages/core/te
60
60
 
61
61
  Transitions:
62
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` |
66
- | `starting` | `start()`, 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
- | `existing`, `signIn` | `choosePod()` / `useBrowser()` while signed out | `signIn` or `welcome` |
71
- | `ready` | `choosePod()` while signed in | `ready`, with `podChoice` set; `confirmPod('combine' \| 'switch')` restarts the session in the pod |
72
- | `pod` | `choosePod()` | `ready`: the new account moves into the pod without asking, and its browser copy is removed |
73
- | `pod` | `finishSetup()` | `ready` |
74
- | `welcome`, `existing`, `signIn` | `startCreating()` | `create` |
75
- | `signIn` | `signInWithPassword` / `signInWithPasskey` succeeds | `ready` |
76
- | `signIn`, `restore` | `signInWithCode` (or a recovery code given to `signInWithPassword`) succeeds | `ready` if the account has a usable passkey or a password here; else `recovery` with `setup: 'restored'` |
77
- | `create` | `createAccount(name)` | `recovery`, with `session`, `freshCode` and `setup: 'new'` set |
78
- | `recovery` | `codeSaved()` | `unlock` |
79
- | `unlock` | `addPasskey()` / `setPassword(p)` succeeds | `pod` for a new account in a browser that can open folders, unless `offerPod` is false; else `ready` |
80
- | `pair` | `acceptPairing()` | once the computer confirms the code, `unlock` with `setup: 'paired'` if the account has no way in here, else `ready` |
81
- | `pair` | `dismissPairing()` | `ready` if signed in, else `signIn` / `welcome` |
82
- | `ready` | `signOut()` | `starting`, then `signIn` / `welcome` |
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)` | `recovery`, with `session`, `freshCode` and `setup: 'new'` set |
79
+ | `recovery` | `codeSaved()` | `unlock` |
80
+ | `unlock` | `addPasskey()` / `setPassword(p)` succeeds | `pod` for a new account 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.
83
93
 
84
94
  A failed action sets `error` (`{ message, hint?, code? }`) and leaves the stage
85
95
  as it was. A dismissed passkey or folder prompt sets no error.
@@ -89,7 +99,7 @@ while it runs, or a carrier given the folder. A page that closes once signed
89
99
  in, such as an account home's connect page, passes `offerPod: false`, and
90
100
  offers the pod where the person comes back instead.
91
101
 
92
- _Source: `packages/core/src/session/auth.ts`. Tests: `packages/core/tests/auth.test.ts`._
102
+ _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")._
93
103
 
94
104
  ## Ways in
95
105
 
@@ -130,6 +140,39 @@ waits for `ready` does not see the session during `recovery`, `unlock` or
130
140
 
131
141
  _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`._
132
142
 
143
+ ## Proving it is you
144
+
145
+ Being signed in is no proof anyone is there: a page may be left open, and a
146
+ sign-in kept for days. So whatever hands out the whole account, or changes how
147
+ it signs in, asks again. `auth.recoveryCode()` returns the code,
148
+ `auth.offerToPhone()` starts, `setPassword`, `addPasskey` and
149
+ `removeShortcut` work (outside the first setup of an account just made,
150
+ restored or paired, which only landing a session opens), only within five
151
+ minutes of `auth.confirm(proof)` succeeding for the account signed in now
152
+ (`isConfirmed()` says whether it has), where `proof` is
153
+ `{ password }`, `{ passkey: true }` (the passkey's own check that someone is
154
+ there: a fingerprint, a face or a PIN) or `{ code }`, the recovery code itself.
155
+ `confirm` resolves false and sets `error` for a wrong answer, and a passkey
156
+ with no credential behind it is no proof. A new sign-in, or signing out, asks
157
+ again. The recovery code shown once when an account is made needs no confirm.
158
+
159
+ Giving an app or a carrier anything (`auth.grant`, `auth.grantCarry`) takes
160
+ the same proof, or a sign-in with `signInWithPassword`, `signInWithPasskey`
161
+ or `signInWithCode` in the last five minutes: the person just gave it.
162
+ Making the account counts too: whoever made it is there. A passkey sign-in
163
+ counts only when the passkey's own check ran, not for a wrap with no
164
+ credential behind it. `mayGrant()` says whether any of these holds. A
165
+ sign-in kept from an earlier visit is none of them. So the reference home's connect page
166
+ goes as signing in with Google does: choose the account, prove it is you
167
+ (signing in to it, or confirming if it is the one signed in), then allow.
168
+ A suggestion from an app already connected (`auth.propose`) gives nothing
169
+ new, and needs only the sign-in.
170
+ This keeps the seed from someone who only has the open page, not from a
171
+ compromised one: the seed is in the page's memory while it is signed in
172
+ ([threat model §4](https://github.com/leifriksheim/minca/blob/main/spec/threat-model.md)).
173
+
174
+ _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")._
175
+
133
176
  ## Device keys and passkeys
134
177
 
135
178
  A device key ([spec 01 §12](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md))
@@ -227,6 +270,11 @@ into the pod, copies every space into it (`copyAccountData`, [stores](node.md#st
227
270
  restarts the session there. `forgetBrowserCopy()` then deletes the browser's
228
271
  copy. Other accounts in the pod are never touched.
229
272
 
273
+ The page writes to the pod only while it is open. A carrier given the same
274
+ folder, such as the Chrome extension, keeps it up to date while the page is
275
+ closed: it learns of the pod from its grant (`CarryGrant.pod`), so one that
276
+ connected before the move learns of it only by connecting again.
277
+
230
278
  _Source: `packages/core/src/session/auth.ts` (`confirmPod`), `packages/core/src/session/places.ts`. Tests: `packages/core/tests/account.test.ts`._
231
279
 
232
280
  ## Pairing a phone
@@ -256,6 +304,32 @@ the person to confirm. Where accounts are already kept here, `<minca-auth>`
256
304
  warns before going on: a link someone else sent would put the phone in their
257
305
  account.
258
306
 
307
+ A phone that stays signed in still gets the `pair` stage, with the kept
308
+ account's session open, and `<minca-auth>` names it; `dismissPairing()` goes
309
+ back to it. Signed in, `acceptPairing()` stops once the account arrives,
310
+ before taking it, and sets `pairingArrival` to `{ did, account }`: `account`
311
+ is the summary when this place already keeps that account, else null. The
312
+ same account as the one signed in is taken without asking, and only its
313
+ spaces are joined. `answerPairing(true)` adds the account (or, already here,
314
+ switches to it) and the one signed in stays filed, to switch back to;
315
+ `answerPairing(false)` lets it go and goes back to the account signed in.
316
+ `<minca-auth>` asks "Add this account?" or "Switch to <name>?", with the
317
+ account's avatar. Only the tab's session when the account arrives counts: a
318
+ tab that opens with no kept sign-in, or a caller that accepts before
319
+ `start()` has finished, pairs as a signed-out one does. Switching this way
320
+ starts the arriving account's session without signing the other out: its
321
+ session key is left unrevoked, as when a tab closes. `dismissPairing()` stops
322
+ a pairing at any point before the account is taken: the phone leaves the
323
+ exchange, and tells the computer nothing.
324
+
325
+ `pairingTransport` in `createMincaAuth`'s config sets how the two sides of a
326
+ pairing reach each other (default: the relay in the ticket), for tests or a
327
+ host with its own.
328
+
329
+ An account home ignores a pairing link on its connect page, so a popup an app
330
+ opened never shows a pairing screen. It is no defence: any page can open the
331
+ account page with the link instead.
332
+
259
333
  The camera opens the link in a new tab, so an app that sent the person to
260
334
  sign in is still waiting in another. A flow that is signed out picks up a
261
335
  sign-in another tab keeps (`storage` events on the remembered session), as a
@@ -269,7 +343,30 @@ tab. It keeps the remembered key as it is, and gives up if the kept sign-in
269
343
  changed meanwhile. When the kept sign-in goes, because the person signed out
270
344
  in another tab, a tab that took it up signs out too, revoking its own key.
271
345
 
272
- _Source: `packages/core/src/session/pairing.ts` (`offerToPhone`, `receiveFromDesktop`), `packages/core/src/session/auth.ts` (`offerToPhone`, `acceptPairing`), `packages/core/src/elements/minca-auth.ts`. Tests: `packages/core/tests/pairing.test.ts`, `packages/core/tests/take-up.test.ts`._
346
+ _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")._
347
+
348
+ ## Linking to the account home
349
+
350
+ An app that links to the person's account home (for its settings, say) says
351
+ which account it acts for: `accountHomeLink(home, did, section?)` gives the
352
+ account page beside the home's connect page, with `#account=<did>` in the
353
+ fragment, after the section if there is one (`#notifications&account=…`). The
354
+ fragment never reaches the server that serves the home.
355
+
356
+ The home may be signed in to another account in that browser, or signed out.
357
+ `readAccountHint()` on the home gives the DID, or null when there is none or it
358
+ is not a P-256 `did:key`; `clearAccountHint()` takes it out of the address and
359
+ leaves the section. Any page can open the home with any DID, so a home must
360
+ treat it as a hint: say which account the app uses, pick it on the sign-in
361
+ screen, offer to switch, and never sign out or switch on the hint alone. For
362
+ an account the home doesn't keep, it must not suggest bringing it in: a
363
+ stranger could name their own account, then send a pairing link "to add this
364
+ browser" ([threat model §3.1](https://github.com/leifriksheim/minca/blob/main/spec/threat-model.md)). An
365
+ account the home keeps is named by the name it filed, never one from the
366
+ link; its avatar helps recognise it, but is no proof, since a look-alike
367
+ takes seconds to find.
368
+
369
+ _Source: `packages/core/src/session/account-hint.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`._
273
370
 
274
371
  ## The account home's side
275
372
 
@@ -324,11 +421,13 @@ disconnects them first, and the programs connected through them, with the
324
421
  automations they proposed; carriers stay. The node sends nothing once it has
325
422
  stopped, so it waits, up to 5 s for them all (`signOutGraceMs` in
326
423
  `createMincaAuth`'s config), for a peer to take in each revoke (`spaces.revoke`
327
- with `waitMs`), its own session key's among them. A node with no network
424
+ with `waitMs`). Its own session key's revokes wait only when a peer is connected in some
425
+ open space as signing out starts, so signing out with nobody else online is
426
+ quick; `state.signingOut` is true meanwhile. A node with no network
328
427
  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
329
428
  access when its time runs out. The account home asks each time, with
330
429
  disconnecting ticked, and is not ready to grant anything from the moment
331
- signing out starts. "Use another account" on the connect page signs out
430
+ signing out starts. Choosing another account on the connect page signs out
332
431
  without disconnecting: switching accounts disconnects nothing.
333
432
 
334
433
  **Proposals.** `auth.propose({ origin, request, kept? })` adds the
package/docs/spaces.md CHANGED
@@ -196,17 +196,29 @@ whose root's `hex40` is not the record key:
196
196
  empty means no profile), `did` (its root) and `updatedAt` (its `createdAt`);
197
197
  - `contactKey` comes from the newest remaining version that carries a valid
198
198
  P-256 point, so a newer version written without one does not hide it.
199
+ - `avatar` comes from the newest version only (one without it has taken it
200
+ away): a file reference (`records.addFile`) whose `mime` is an image.
199
201
 
200
202
  **Writing.** Profiles are written with `retain`, so older versions stay. A
201
203
  writer that does not hold the contact key must carry forward the
202
204
  `contactKey` of its current profile.
203
205
 
204
- **The account's name.** The account keeps its name in the account registry,
205
- as `sys.profile` at key `profile` with body `{ name }`; the newest version
206
- wins. `node.account.setName` writes it. The node publishes that name into
207
- every space it opens, and again on a rename, except the registry, the
208
- contacts space and nodes whose note lacks `/account/write` (an agent's); a
209
- non-member publishes nothing
206
+ **The account's name and picture.** The account keeps its name in the
207
+ account registry, as `sys.profile` at key `profile` with body
208
+ `{ name, avatar? }`; the newest version wins. `node.account.setName` writes
209
+ the name, `setAvatar({ bytes, mime })` the picture (a file in the registry;
210
+ the app resizes it first), and `picture()` reads it back. The node publishes
211
+ both into every space it opens, and again on a change. A space's members
212
+ can't read the registry, so the picture is copied into each space once, as a
213
+ file of that space, and its reference names the registry file it copies
214
+ (`source`), so opening the space again makes no second copy. A picture that
215
+ can't be copied now (its bytes on a device that is away) leaves the space's
216
+ copy as it was, and never holds back the name. Profiles are retained, so a
217
+ picture once shared stays with the members who hold it: taking it away
218
+ shows none from then on, and withdraws nothing. It publishes
219
+ in every space but the registry and the contacts space, and not at all from
220
+ a node whose note lacks `/account/write` (an agent's); a non-member
221
+ publishes nothing
210
222
  ([spec 06 §1.3](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
211
223
 
212
224
  > **Planned:** profiles, round two.
@@ -215,10 +227,6 @@ non-member publishes nothing
215
227
  > per space; what is missing is a way to say the name was chosen for this
216
228
  > space, so publishing the account name on the next rename does not
217
229
  > overwrite it.
218
- > - **An avatar**, as a reference to an image on the profile. Depends on a
219
- > way for a record to carry a file, which is not specified yet (the blob
220
- > stores of [spec 05](https://github.com/leifriksheim/minca/blob/main/spec/05-sync-and-storage.md) hold mirrors, not files records
221
- > point to).
222
230
  > - **Private nicknames for others**: a name you give someone, seen only by
223
231
  > you. It belongs in the account's own spaces, not in the shared one;
224
232
  > `std.contact`'s `name` already does this for contacts.
@@ -57,23 +57,24 @@ _Source: `packages/core/src/schemas/blueprints.ts` (`standardCollections`), `pac
57
57
  out in each definition, built by the library's `fragments` so they are
58
58
  identical everywhere:
59
59
 
60
- | Fragment | Shape |
61
- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
62
- | `when` | string 10–64: RFC 3339 date-time (`2026-03-01T18:30:00+01:00`), or `YYYY-MM-DD` for a whole day |
63
- | `day` | string of 10: `YYYY-MM-DD` |
64
- | `timeZone` | string 1–64: an IANA zone, `Europe/Oslo` |
65
- | DID | string 1–256: an account DID (built by `person`) |
66
- | `money` | `{ amount, currency }`, both required: `amount` a decimal string 1–32 (`"12.50"`), never a number; `currency` ISO 4217, 3 characters |
67
- | `address` | `{ street, locality, region, postcode, country }`, each optional; `country` ISO 3166-1 alpha-2 |
68
- | `place` | `{ name, address, lat, lon, cells }` (built by `placeRef`), each optional; `lat` −90–90, `lon` −180–180, WGS 84; `cells` string 1–12[] (≤ 8), the geohash cells of `lat` and `lon` (see Places and areas) |
69
- | `blob` | `{ hash, size, mime, name? }`: `hash` the lower-case hex SHA-256 of the bytes as stored (64 characters), `size` bytes, `mime` required |
70
- | `image` | `{ blob, alt? }`: `alt` ≤ 2000, what it shows |
71
- | `position` | string 1–200 that sorts where a record goes (Positions, below) |
60
+ | Fragment | Shape |
61
+ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
62
+ | `when` | string 10–64: RFC 3339 date-time (`2026-03-01T18:30:00+01:00`), or `YYYY-MM-DD` for a whole day |
63
+ | `day` | string of 10: `YYYY-MM-DD` |
64
+ | `timeZone` | string 1–64: an IANA zone, `Europe/Oslo` |
65
+ | DID | string 1–256: an account DID (built by `person`) |
66
+ | `money` | `{ amount, currency }`, both required: `amount` a decimal string 1–32 (`"12.50"`), never a number; `currency` ISO 4217, 3 characters |
67
+ | `address` | `{ street, locality, region, postcode, country }`, each optional; `country` ISO 3166-1 alpha-2 |
68
+ | `place` | `{ name, address, lat, lon, cells }` (built by `placeRef`), each optional; `lat` −90–90, `lon` −180–180, WGS 84; `cells` string 1–12[] (≤ 8), the geohash cells of `lat` and `lon` (see Places and areas) |
69
+ | `blob` | `{ hash, size, mime, name?, key?, salt? }`: what `records.addFile` gives: `hash` the file's id (64 hex characters), `size` bytes as stored, `mime` required; `key` and `salt` open it (22 base64url characters each) |
70
+ | `image` | `{ blob, alt? }`: `alt` ≤ 2000, what it shows |
71
+ | `position` | string 1–200 that sorts where a record goes (Positions, below) |
72
72
 
73
73
  Until the dialect has `format` ([spec 02 §6.2](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)), `when` and `day` are checked only for
74
- length. How a `blob`'s bytes are stored and fetched is planned
75
- ([Planned: what the library still waits on](#planned-what-the-library-still-waits-on));
76
- the reference to them is not.
74
+ length. A `blob` is what `records.addFile` gives
75
+ ([storage](storage.md#files)): its `hash` is the file's id, and it carries
76
+ the `key` and `salt` that open it
77
+ ([spec 05 §16.6](https://github.com/leifriksheim/minca/blob/main/spec/05-sync-and-storage.md)).
77
78
 
78
79
  ## The definitions
79
80
 
@@ -485,11 +486,6 @@ _Source: `packages/core/src/schemas/geo.ts` (`geohash`, `cellsOf`, `cellsAround`
485
486
 
486
487
  > **Planned.** Not normative. Each item names its own issue.
487
488
  >
488
- > - **File bytes** ([spec 05 §16.6](https://github.com/leifriksheim/minca/blob/main/spec/05-sync-and-storage.md),
489
- > [#37](https://github.com/leifriksheim/minca/issues/37)). The `blob`
490
- > fragment names bytes by hash, but a space cannot yet store or send them,
491
- > so `std.file`, `std.photo`, `std.video` and the images elsewhere point at
492
- > bytes a reader may not be able to fetch.
493
489
  > - **References to other spaces** ([spec 02 §5.3](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md),
494
490
  > [#38](https://github.com/leifriksheim/minca/issues/38)). `std.follow`'s
495
491
  > `space` is a plain space id, and a repost or a list item can point only