@dreamforgestudiollc/emet 0.3.5 → 0.3.7

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 (103) hide show
  1. package/.env.example +29 -0
  2. package/CHANGELOG.md +49 -11
  3. package/CHARTER.md +1 -1
  4. package/CONTRIBUTING.md +21 -0
  5. package/README.md +25 -10
  6. package/RELEASE_NOTES-0.2.6.md +43 -0
  7. package/RELEASE_NOTES-0.3.6.md +29 -0
  8. package/RELEASE_NOTES-0.3.7.md +19 -0
  9. package/SECURITY.md +13 -0
  10. package/docs/BOTS.md +4 -4
  11. package/docs/DEPLOY.md +23 -4
  12. package/docs/ERROR-CODES-SPEC.md +4 -0
  13. package/docs/ERROR-CODES.md +7 -0
  14. package/docs/GUIDED-SETUP.md +1 -1
  15. package/docs/ROADMAP.md +62 -49
  16. package/docs/SETUP.md +11 -1
  17. package/docs/SUBKEYS.md +3 -1
  18. package/docs/continuity-currency-statechart.md +34 -0
  19. package/docs/features/README.md +21 -0
  20. package/docs/features/access.md +28 -0
  21. package/docs/features/documents.md +35 -0
  22. package/docs/features/errors.md +32 -0
  23. package/docs/features/gems.md +31 -0
  24. package/docs/features/memory.md +29 -0
  25. package/docs/features/pages.md +28 -0
  26. package/docs/features/record.md +27 -0
  27. package/docs/features/search.md +27 -0
  28. package/docs/features/startup.md +29 -0
  29. package/docs/features/subkeys.md +30 -0
  30. package/docs/features/transcripts.md +33 -0
  31. package/docs/per-tag-handoff-statechart.md +147 -0
  32. package/docs/subkey-session-statechart.md +57 -0
  33. package/package.json +6 -2
  34. package/server.json +27 -2
  35. package/src/annotations.js +5 -3
  36. package/src/attribution.js +2 -2
  37. package/src/carry-forward-close.js +1 -1
  38. package/src/chooser.js +74 -3
  39. package/src/conformance.js +2 -0
  40. package/src/continuity-currency-statechart.js +139 -0
  41. package/src/continuity-currency.js +869 -0
  42. package/src/database.js +1 -1
  43. package/src/dispatch.js +1 -1
  44. package/src/error-codes.js +7 -0
  45. package/src/gem-check.js +4 -1
  46. package/src/grants.js +28 -5
  47. package/src/host-reach.js +1 -1
  48. package/src/http-remote.js +29 -5
  49. package/src/index.js +3 -2
  50. package/src/invites.js +2 -2
  51. package/src/owl.js +12 -11
  52. package/src/pages.js +15 -0
  53. package/src/per-tag-handoff-statechart.js +264 -0
  54. package/src/per-tag-handoff.js +988 -0
  55. package/src/persons.js +16 -0
  56. package/src/session-graph.js +123 -12
  57. package/src/session.js +56 -12
  58. package/src/setup.js +32 -11
  59. package/src/startup-pages.js +13 -2
  60. package/src/subkey-lifecycle.js +105 -0
  61. package/src/subkey-session-statechart.js +253 -0
  62. package/src/subkeys.js +648 -89
  63. package/src/tools.js +171 -51
  64. package/src/transcript-session.js +2 -2
  65. package/src/version.js +1 -1
  66. package/templates/INDEX.md +1 -0
  67. package/templates/SESSIONDISPOSITION.md +2 -2
  68. package/templates/TAGHANDOFF.md +45 -0
  69. package/verification/continuity-currency/ContinuityCurrency.cfg +12 -0
  70. package/verification/continuity-currency/ContinuityCurrency.tla +239 -0
  71. package/verification/continuity-currency/tlc-output.txt +32 -0
  72. package/verification/continuity-currency/view.mjs +54 -0
  73. package/verification/load-gate/load-gate.mjs +1 -1
  74. package/verification/per-tag-handoff/PerTagHandoff.cfg +10 -0
  75. package/verification/per-tag-handoff/PerTagHandoff.tla +191 -0
  76. package/verification/per-tag-handoff/StampCounter.cfg +10 -0
  77. package/verification/per-tag-handoff/out/report.md +6 -0
  78. package/verification/per-tag-handoff/out-counter/chart.mmd +30 -0
  79. package/verification/per-tag-handoff/out-counter/report.md +15 -0
  80. package/verification/per-tag-handoff/out-counter/tlc.out +130 -0
  81. package/verification/per-tag-handoff/split/PerTagConflict.cfg +6 -0
  82. package/verification/per-tag-handoff/split/PerTagConflict.tla +104 -0
  83. package/verification/per-tag-handoff/split/PerTagTime.cfg +8 -0
  84. package/verification/per-tag-handoff/split/PerTagTime.tla +100 -0
  85. package/verification/per-tag-handoff/split/conflict-chart.mmd +47 -0
  86. package/verification/per-tag-handoff/split/conflict-report.md +8 -0
  87. package/verification/per-tag-handoff/split/conflict-tlc.txt +19 -0
  88. package/verification/per-tag-handoff/split/conflict-view.mjs +34 -0
  89. package/verification/per-tag-handoff/split/time-chart.mmd +44 -0
  90. package/verification/per-tag-handoff/split/time-report.md +8 -0
  91. package/verification/per-tag-handoff/split/time-tlc.txt +19 -0
  92. package/verification/per-tag-handoff/split/time-view.mjs +33 -0
  93. package/verification/per-tag-handoff/tlc-output.txt +19 -0
  94. package/verification/per-tag-handoff/v1-draft/PerTagHandoff.cfg +5 -0
  95. package/verification/per-tag-handoff/v1-draft/PerTagHandoff.tla +94 -0
  96. package/verification/per-tag-handoff/v1-draft/out/chart.mmd +37 -0
  97. package/verification/per-tag-handoff/v1-draft/out/report.md +7 -0
  98. package/verification/per-tag-handoff/v1-draft/out/tlc.out +19 -0
  99. package/verification/per-tag-handoff/v1-draft/view.mjs +20 -0
  100. package/verification/per-tag-handoff/view.mjs +31 -0
  101. package/verification/subkey-session/SubkeySession.cfg +11 -0
  102. package/verification/subkey-session/SubkeySession.tla +254 -0
  103. package/verification/subkey-session/tlc-output.txt +13 -0
@@ -0,0 +1,105 @@
1
+ /**
2
+ * Sub-key session lifetime (handle renewal, grace, and the backstop).
3
+ *
4
+ * A handle lasts 12 hours. The last hour is the renewal window. After
5
+ * expiry, the same length is a grace window. Past that, the session is
6
+ * stranded and the sweep can close it. This module is the clock and the
7
+ * words. The store writes live in src/subkeys.js.
8
+ *
9
+ * A client_kind on the call is not a kind. The kind is the value the owner
10
+ * stored on the key.
11
+ */
12
+
13
+ import { setting } from './env.js';
14
+
15
+ export const HANDLE_TTL_MS = 12 * 60 * 60 * 1000;
16
+
17
+ export const UNWRAPPED_NOTICE =
18
+ 'The previous chat was not wrapped up. Go back to that chat and wrap it up to save it.';
19
+
20
+ export const RENEW_MESSAGE =
21
+ 'Wrap up and call emet_session_open with your sub-key and this session_handle. The server cannot push a new handle to an idle client.';
22
+
23
+ const TERMINAL = new Set(['closed', 'auto_closed', 'revoked']);
24
+
25
+ export function isTerminalState(state) {
26
+ return TERMINAL.has(state);
27
+ }
28
+
29
+ /** 'chat', 'bot', or null when the value is absent or not one of those two. */
30
+ export function clientKindValue(value) {
31
+ if (value === undefined || value === null) return null;
32
+ const text = String(value).trim();
33
+ if (!text) return null;
34
+ if (text === 'chat' || text === 'bot') return text;
35
+ return null;
36
+ }
37
+
38
+ /** The kind stored on the key. A missing value is a bot: the collision rule stays. */
39
+ export function clientKindOf(row) {
40
+ return row && row.client_kind === 'chat' ? 'chat' : 'bot';
41
+ }
42
+
43
+ export function renewalWindowMs() {
44
+ const raw = setting('SUBKEY_RENEWAL_MINUTES');
45
+ const cap = Math.floor(HANDLE_TTL_MS / 60000) - 1;
46
+ if (raw === undefined || raw === null || String(raw).trim() === '') return 60 * 60 * 1000;
47
+ const n = Number(raw);
48
+ if (!Number.isFinite(n) || n < 1) return 60 * 60 * 1000;
49
+ return Math.min(Math.floor(n), cap) * 60 * 1000;
50
+ }
51
+
52
+ export function handleGraceMs() {
53
+ const raw = setting('SUBKEY_HANDLE_GRACE_MINUTES');
54
+ if (raw === undefined || raw === null || String(raw).trim() === '') return 60 * 60 * 1000;
55
+ const n = Number(raw);
56
+ if (!Number.isFinite(n) || n < 0) return 60 * 60 * 1000;
57
+ return Math.floor(n) * 60 * 1000;
58
+ }
59
+
60
+ export function sweepIntervalMs() {
61
+ const raw = setting('SUBKEY_SWEEP_MINUTES');
62
+ if (raw === undefined || raw === null || String(raw).trim() === '') return 15 * 60 * 1000;
63
+ const n = Number(raw);
64
+ if (!Number.isFinite(n) || n < 1) return 15 * 60 * 1000;
65
+ return Math.floor(n) * 60 * 1000;
66
+ }
67
+
68
+ /**
69
+ * Where a handle sits against its expiry.
70
+ * fresh: more than the renewal window remains.
71
+ * window: inside the last stretch, the handle still verifies.
72
+ * grace: expired, and a renewal that presents the key is still open.
73
+ * beyond: the grace window is over.
74
+ */
75
+ export function phaseOf(expiresAt, now, windowMs = renewalWindowMs(), graceMs = handleGraceMs()) {
76
+ const exp = expiresAt ? new Date(expiresAt).getTime() : NaN;
77
+ if (!Number.isFinite(exp)) return 'fresh';
78
+ const t = now instanceof Date ? now.getTime() : new Date(now).getTime();
79
+ if (!Number.isFinite(t)) return 'fresh';
80
+ if (t >= exp + graceMs) return 'beyond';
81
+ if (t >= exp) return 'grace';
82
+ if (t >= exp - windowMs) return 'window';
83
+ return 'fresh';
84
+ }
85
+
86
+ export function renewalRequest(session) {
87
+ return {
88
+ action: 'reinitialize',
89
+ session_id: session && session.session_id || null,
90
+ open_id: session && session.open_id || null,
91
+ expires_at: session && session.expires_at || null,
92
+ message: RENEW_MESSAGE
93
+ };
94
+ }
95
+
96
+ /**
97
+ * The code http-remote puts on a preflight failure.
98
+ * A stranded session is EMET-SESS-014. It is not EMET-AUTH-039.
99
+ */
100
+ export function preflightHttpCode(err) {
101
+ if (!err) return null;
102
+ if (err.subkeyHold) return 'EMET-SESS-014';
103
+ if (err.attributionRefusal) return err.emetCode === 'EMET-AUTH-044' ? 'EMET-AUTH-044' : 'EMET-AUTH-039';
104
+ return null;
105
+ }
@@ -0,0 +1,253 @@
1
+ /**
2
+ * Sub-key session statechart.
3
+ *
4
+ * One key, one session slot. Renewal and reclaim replace that slot.
5
+ * A handle with no key does not mint the next session.
6
+ * The picture is docs/subkey-session-statechart.md.
7
+ * The model is verification/subkey-session/SubkeySession.tla.
8
+ */
9
+
10
+ export const SUBKEY_SESSION_MERMAID = `stateDiagram-v2
11
+ [*] --> opening
12
+ opening --> live: open commits
13
+ opening --> ended: open lost
14
+ live --> renewal_offered: last hour, handle still valid
15
+ renewal_offered --> live: renew with the key and the handle
16
+ live --> live: renew with the key and the handle
17
+ live --> expired: handle expires
18
+ renewal_offered --> expired: handle expires
19
+ expired --> live: renew with the key and the handle, inside grace
20
+ expired --> unwrapped: chat, no wrap-up, key still required to open
21
+ unwrapped --> live: same key opens the next session
22
+ live --> closed: owner, or same key reclaim, or a clean close
23
+ ended --> auto_closed: sweep
24
+ expired --> auto_closed: past grace, sweep
25
+ unwrapped --> auto_closed: past grace, sweep
26
+ opening --> auto_closed: past grace, sweep
27
+ live --> revoked: revoke
28
+ renewal_offered --> revoked: revoke
29
+ closed --> [*]
30
+ auto_closed --> [*]
31
+ revoked --> [*]`;
32
+
33
+ export const SUBKEY_SESSION_STEPS = Object.freeze([
34
+ 'A session opens into one live slot for its key. A second open while that slot is still in its 12 hours is a collision for a bot key.',
35
+ 'Inside the last hour the server asks the caller to wrap up and open again with the sub-key and the current handle. The handle still works. The server does not mint a handle from that call.',
36
+ 'A renewal presents the sub-key and the current handle. The old session closes into the new one in the same write. One live session remains. The new row records the previous open.',
37
+ 'After expiry, the grace window still accepts that pair. The handle alone does not mint a session.',
38
+ 'A chat key is the kind the owner stored. A chat whose handle expired with no wrap-up record is marked unwrapped, and the next open with the key is still allowed. The reply tells the user to go back and wrap that chat up.',
39
+ 'A wrap-up record for that tag, written between the handle and now, lets the old session close into the new one.',
40
+ 'The owner, or a new open with the same key, carry-forward closes a stranded session of that key. Another key does not.',
41
+ 'Past the grace window, or when the link is already ended, the sweep records auto_closed. The row and the transcript stay. A status read is not refused and does not write handle_expired.'
42
+ ]);
43
+
44
+ const SESS = new Set([
45
+ 'opening', 'live', 'renewal_offered', 'ended', 'expired', 'unwrapped', 'closed', 'auto_closed', 'revoked'
46
+ ]);
47
+ const PHASE = new Set(['fresh', 'window', 'grace', 'beyond']);
48
+ const CLOSED = new Set(['closed', 'auto_closed', 'revoked']);
49
+ const ORDER = ['fresh', 'window', 'grace', 'beyond'];
50
+
51
+ function same(state, extra) {
52
+ return { ...state, ...extra };
53
+ }
54
+
55
+ /** A step that changes the session record. `store` counts those writes. */
56
+ function wrote(state, extra) {
57
+ const store = state.store || 0;
58
+ return { ...state, ...extra, store: store + 1, prevStore: store, act: 'write' };
59
+ }
60
+
61
+ /** A read. The session record and the store counter stay where they are. */
62
+ function read(state, act) {
63
+ const store = state.store || 0;
64
+ return { ...state, store, prevStore: store, act };
65
+ }
66
+
67
+ /**
68
+ * One step. An event that cannot happen returns null.
69
+ * `credential` is `key` for renew and reclaim, `handle` for a bare handle, `foreign` for another tag.
70
+ */
71
+ export function subkeySessionStep(state, event, credential = 'key') {
72
+ if (!state || !SESS.has(state.sess) || !PHASE.has(state.phase)) return null;
73
+ if (state.kind !== 'bot' && state.kind !== 'chat') return null;
74
+ const next = { ...state };
75
+
76
+ if (event === 'rest') {
77
+ if (!CLOSED.has(state.sess)) return null;
78
+ return same(state, {});
79
+ }
80
+ if (event === 'status') return read(state, 'status');
81
+ if (CLOSED.has(state.sess)) return null;
82
+
83
+ if (event === 'commit') {
84
+ if (state.sess !== 'opening' || (state.phase !== 'fresh' && state.phase !== 'window')) return null;
85
+ return wrote(state, { sess: 'live', live: 1 });
86
+ }
87
+ if (event === 'lose') {
88
+ if (state.sess !== 'opening') return null;
89
+ return wrote(state, { sess: 'ended', live: 0 });
90
+ }
91
+ if (event === 'offer') {
92
+ if (state.sess !== 'live' || state.phase !== 'window' || state.live !== 1) return null;
93
+ return wrote(state, { sess: 'renewal_offered' });
94
+ }
95
+ if (event === 'advance') {
96
+ const i = ORDER.indexOf(state.phase);
97
+ if (i < 0 || i === ORDER.length - 1) return null;
98
+ const phase = ORDER[i + 1];
99
+ if ((state.sess === 'live' || state.sess === 'renewal_offered') && (phase === 'grace' || phase === 'beyond')) {
100
+ return wrote(state, { phase, sess: 'expired', live: 0 });
101
+ }
102
+ return wrote(state, { phase });
103
+ }
104
+ if (event === 'renew') {
105
+ if (credential !== 'key') return null;
106
+ if (state.gen >= 1) return null;
107
+ if (state.phase !== 'window' && state.phase !== 'grace') return null;
108
+ if (!['live', 'renewal_offered', 'expired'].includes(state.sess)) return null;
109
+ return wrote(state, {
110
+ sess: 'live', phase: 'fresh', gen: state.gen + 1, live: 1,
111
+ prevClosed: true, closedBy: 'same', bareMint: false
112
+ });
113
+ }
114
+ if (event === 'reclaim') {
115
+ if (credential !== 'key') return null;
116
+ if (state.reclaims >= 1) return null;
117
+ if (state.sess === 'opening') return null;
118
+ const stranded = ['ended', 'expired', 'unwrapped'].includes(state.sess) || state.phase === 'grace' || state.phase === 'beyond';
119
+ if (state.kind !== 'chat' && !stranded) return null;
120
+ const chatClean = state.kind === 'chat' && state.wrap && state.sess !== 'ended';
121
+ return wrote(state, {
122
+ sess: 'live', phase: 'fresh', live: 1, reclaims: state.reclaims + 1,
123
+ prevClosed: chatClean || state.kind !== 'chat' || state.wrap || state.sess === 'ended' || state.phase === 'beyond',
124
+ closedBy: 'same', bareMint: false
125
+ });
126
+ }
127
+ if (event === 'unwrap') {
128
+ if (state.kind !== 'chat' || state.wrap || state.phase !== 'grace' || state.sess !== 'expired') return null;
129
+ return wrote(state, { sess: 'unwrapped', live: 0, bareMint: false });
130
+ }
131
+ if (event === 'owner_close') {
132
+ return wrote(state, { sess: 'closed', live: 0, closedBy: 'owner', prevClosed: true });
133
+ }
134
+ if (event === 'sweep') {
135
+ if (state.phase !== 'beyond' && state.sess !== 'ended') return null;
136
+ if (state.sess === 'ended' || state.phase === 'beyond') {
137
+ return wrote(state, { sess: 'auto_closed', live: 0, closedBy: 'sweep', prevClosed: true });
138
+ }
139
+ return null;
140
+ }
141
+ if (event === 'revoke') {
142
+ return wrote(state, { sess: 'revoked', live: 0, closedBy: 'owner' });
143
+ }
144
+ if (event === 'bare_handle') {
145
+ if (credential !== 'handle') return null;
146
+ return read(state, 'bare');
147
+ }
148
+ if (event === 'foreign_close') {
149
+ if (credential !== 'foreign') return null;
150
+ return same(next, {});
151
+ }
152
+ if (event === 'collision') {
153
+ if (state.kind !== 'bot' || !['live', 'renewal_offered'].includes(state.sess)) return null;
154
+ if (state.phase !== 'fresh' && state.phase !== 'window') return null;
155
+ return same(next, {});
156
+ }
157
+ return null;
158
+ }
159
+
160
+ export function initialSubkeySessions() {
161
+ const rows = [];
162
+ for (const kind of ['bot', 'chat']) {
163
+ for (const wrap of [false, true]) {
164
+ rows.push({
165
+ sess: 'opening', phase: 'fresh', kind, wrap, gen: 0, live: 0,
166
+ reclaims: 0, bareMint: false, closedBy: 'none', prevClosed: false,
167
+ store: 0, prevStore: 0, act: 'init'
168
+ });
169
+ }
170
+ }
171
+ return rows;
172
+ }
173
+
174
+ const EVENTS = [
175
+ 'commit', 'lose', 'offer', 'advance', 'renew', 'reclaim', 'unwrap',
176
+ 'owner_close', 'sweep', 'revoke', 'bare_handle', 'status', 'foreign_close', 'collision', 'rest'
177
+ ];
178
+
179
+ function credFor(event) {
180
+ if (event === 'bare_handle') return 'handle';
181
+ if (event === 'foreign_close') return 'foreign';
182
+ return 'key';
183
+ }
184
+
185
+ function keyOf(state) {
186
+ return [state.sess, state.phase, state.kind, state.wrap, state.gen, state.live, state.reclaims, state.bareMint, state.closedBy, state.prevClosed].join('|');
187
+ }
188
+
189
+ /**
190
+ * Every reachable slot. `stranded` is a non-closed state from which
191
+ * commit, lose, advance, and sweep cannot reach a closed state.
192
+ */
193
+ export function auditSubkeySessions() {
194
+ const start = initialSubkeySessions();
195
+ const seen = new Map();
196
+ const queue = [];
197
+ for (const row of start) {
198
+ seen.set(keyOf(row), row);
199
+ queue.push(row);
200
+ }
201
+ while (queue.length) {
202
+ const row = queue.shift();
203
+ for (const event of EVENTS) {
204
+ const step = subkeySessionStep(row, event, credFor(event));
205
+ if (!step) continue;
206
+ const id = keyOf(step);
207
+ if (seen.has(id)) continue;
208
+ seen.set(id, step);
209
+ queue.push(step);
210
+ }
211
+ }
212
+ const rows = [...seen.values()];
213
+ const problems = [];
214
+ for (const row of rows) {
215
+ if (row.live > 1) problems.push({ rule: 'live', row });
216
+ if (row.bareMint) problems.push({ rule: 'bare', row });
217
+ if (row.closedBy === 'foreign') problems.push({ rule: 'foreign', row });
218
+ if ((row.sess === 'closed' || row.sess === 'auto_closed') && !['same', 'owner', 'sweep'].includes(row.closedBy)) {
219
+ problems.push({ rule: 'closer', row });
220
+ }
221
+ if (row.sess === 'unwrapped' && row.live !== 0) problems.push({ rule: 'unwrapped', row });
222
+ const status = subkeySessionStep(row, 'status', 'key');
223
+ if (!status || status.act !== 'status' || status.store !== row.store || status.sess !== row.sess || status.prevStore !== status.store) {
224
+ problems.push({ rule: 'status-write', row });
225
+ }
226
+ const bare = subkeySessionStep(row, 'bare_handle', 'handle');
227
+ if (bare && (bare.act !== 'bare' || bare.store !== row.store || bare.sess !== row.sess || bare.live !== row.live)) {
228
+ problems.push({ rule: 'bare-write', row });
229
+ }
230
+ }
231
+ const progress = new Set(['commit', 'lose', 'advance', 'sweep']);
232
+ const stranded = [];
233
+ for (const row of rows) {
234
+ if (['closed', 'auto_closed', 'revoked'].includes(row.sess)) continue;
235
+ const reach = new Map([[keyOf(row), row]]);
236
+ const q = [row];
237
+ let settled = false;
238
+ while (q.length) {
239
+ const cur = q.shift();
240
+ if (['closed', 'auto_closed', 'revoked'].includes(cur.sess)) { settled = true; break; }
241
+ for (const event of progress) {
242
+ const step = subkeySessionStep(cur, event, 'key');
243
+ if (!step) continue;
244
+ const id = keyOf(step);
245
+ if (reach.has(id)) continue;
246
+ reach.set(id, step);
247
+ q.push(step);
248
+ }
249
+ }
250
+ if (!settled) stranded.push(row);
251
+ }
252
+ return { count: rows.length, problems, stranded };
253
+ }