@dreamforgestudiollc/emet 0.3.1 → 0.3.3

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 (72) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/README.md +29 -6
  3. package/docs/BOOTSTRAP.md +2 -0
  4. package/docs/BOTS.md +8 -7
  5. package/docs/DEPLOY.md +6 -0
  6. package/docs/ERROR-CODES-SPEC.md +2 -2
  7. package/docs/ERROR-CODES.md +29 -0
  8. package/docs/GUIDED-SETUP.md +1 -1
  9. package/docs/PERMISSIONS.md +5 -5
  10. package/docs/SETUP.md +10 -4
  11. package/docs/SUBKEYS.md +4 -4
  12. package/package.json +2 -2
  13. package/server.json +8 -4
  14. package/src/aleph.js +34 -13
  15. package/src/annotations.js +6 -2
  16. package/src/approve-throttle.js +3 -0
  17. package/src/atlas-role.js +1 -1
  18. package/src/attribution.js +76 -28
  19. package/src/bound-door.js +170 -0
  20. package/src/break-glass.js +531 -0
  21. package/src/carry-forward-close.js +386 -0
  22. package/src/checkpoint.js +241 -0
  23. package/src/chooser.js +543 -0
  24. package/src/claimed-tag.js +140 -0
  25. package/src/conformance.js +269 -5
  26. package/src/deep-links.js +267 -0
  27. package/src/dispatch.js +112 -18
  28. package/src/error-codes.js +29 -0
  29. package/src/error-log.js +138 -26
  30. package/src/error-report.js +17 -5
  31. package/src/gaps.js +1 -1
  32. package/src/grants.js +230 -0
  33. package/src/http-remote.js +80 -26
  34. package/src/index.js +18 -2
  35. package/src/invites.js +47 -1
  36. package/src/layers.js +1 -1
  37. package/src/lessons-to-checks.js +1 -1
  38. package/src/logger.js +3 -1
  39. package/src/oauth-provider.js +89 -5
  40. package/src/owl.js +232 -0
  41. package/src/owner-approvals.js +24 -267
  42. package/src/owner-session.js +235 -0
  43. package/src/pages.js +1 -1
  44. package/src/persons.js +39 -6
  45. package/src/proof-run.js +70 -0
  46. package/src/redact.js +4 -0
  47. package/src/request-log.js +2 -2
  48. package/src/rotate.js +554 -0
  49. package/src/rune-dispatch.js +1 -1
  50. package/src/session-graph.js +44 -25
  51. package/src/session.js +52 -9
  52. package/src/setup.js +21 -12
  53. package/src/staged-write.js +522 -0
  54. package/src/startup-pages.js +2 -2
  55. package/src/startup-payload.js +3 -3
  56. package/src/subkeys.js +61 -0
  57. package/src/tools.js +290 -79
  58. package/src/transcript-session.js +23 -4
  59. package/src/validation.js +1 -1
  60. package/src/version.js +1 -1
  61. package/src/writer-approval.js +394 -0
  62. package/templates/AREA.md +1 -1
  63. package/templates/BOTHANDOFF.md +2 -2
  64. package/templates/GRANT.md +48 -0
  65. package/templates/INDEX.md +9 -7
  66. package/templates/PROCEDURE.md +1 -1
  67. package/templates/ROSTER.md +2 -2
  68. package/templates/SEED.md +2 -2
  69. package/templates/SESSIONDISPOSITION.md +59 -0
  70. package/templates/STAGING.md +1 -1
  71. package/templates/STANDARD.md +1 -1
  72. package/templates/THREAD.md +1 -1
@@ -0,0 +1,70 @@
1
+ /**
2
+ * Last R7 proof-run status.
3
+ *
4
+ * Operational metric for this process, in the same family as the owl
5
+ * retirement and rotate-all lines. The controlled record is the proof pack
6
+ * under docs/proof/R7/ in the EMET-private repo. This module does not write
7
+ * the memory store, does not mint a grant, and does not rotate credentials.
8
+ * A fresh process reports not_run. Railway EMET therefore reports not_run
9
+ * until a harness run is recorded in that process.
10
+ *
11
+ * ISO 9001 7.5.3 / ISO 13485 4.2.5: a later run does not delete an earlier
12
+ * one. The in-process history keeps every record. The proof pack is the
13
+ * retained copy that survives a restart.
14
+ */
15
+
16
+ const history = [];
17
+
18
+ export function _resetProofRunForTests() {
19
+ history.length = 0;
20
+ }
21
+
22
+ export function proofRunHistory() {
23
+ return history.map((row) => ({ ...row }));
24
+ }
25
+
26
+ export function proofRunMetric() {
27
+ const last = history.length ? history[history.length - 1] : null;
28
+ return {
29
+ rung: 'R7',
30
+ status: last ? last.status : 'not_run',
31
+ last_at: last ? last.at : null,
32
+ last_correlation_id: last ? last.correlation_id : null,
33
+ passed: last ? last.passed : 0,
34
+ failed: last ? last.failed : 0,
35
+ retained: history.length,
36
+ deleted: false,
37
+ since_process_start: true
38
+ };
39
+ }
40
+
41
+ export function proofStartupLine() {
42
+ const metric = proofRunMetric();
43
+ if (metric.status === 'fail') {
44
+ return `[emet] PROOF RUN FAILED status=fail rung=R7 failed=${metric.failed} retained=${metric.retained}`;
45
+ }
46
+ if (metric.status === 'pass') {
47
+ return `[emet] proof-run status=pass rung=R7 failed=0 retained=${metric.retained}`;
48
+ }
49
+ return '[emet] proof-run status=not_run rung=R7';
50
+ }
51
+
52
+ /**
53
+ * Record one matrix run. `correlation_id` is kept only when it is 16 hex
54
+ * characters. Anything else is dropped, so a token cannot land in the metric.
55
+ */
56
+ export function recordProofRun({ pass, passed, failed, correlation_id } = {}) {
57
+ const status = pass === true && !(Number(failed) > 0) ? 'pass' : 'fail';
58
+ const correlation = typeof correlation_id === 'string' && /^[0-9a-f]{16}$/.test(correlation_id)
59
+ ? correlation_id
60
+ : null;
61
+ history.push({
62
+ at: new Date().toISOString(),
63
+ status,
64
+ passed: Number(passed) || 0,
65
+ failed: Number(failed) || 0,
66
+ correlation_id: correlation
67
+ });
68
+ if (status === 'fail') console.error(proofStartupLine());
69
+ return proofRunMetric();
70
+ }
package/src/redact.js CHANGED
@@ -121,6 +121,10 @@ const RULES = [
121
121
  // JWT
122
122
  { name: 'jwt', pre: (t) => t.includes('eyJ'),
123
123
  re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, sub: () => MASK },
124
+ // R4 chooser link. The raw token is the capability. Mask it if a log line
125
+ // ever contains the URL. The path stays so the line still says which page.
126
+ { name: 'chooser-link', pre: (t) => t.includes('/owner/chooser?d='),
127
+ re: /(\/owner\/chooser\?d=)[A-Za-z0-9_-]{16,}/g, sub: (_m, prefix) => `${prefix}${MASK}` },
124
128
  // Delegated client sub-keys (EMET-0001). The full key, the session handle
125
129
  // and the claim nonce. A bare key_id (32 hex, no prefix) is an index and
126
130
  // stays visible. Lengths are exact so a shorter hex id is not masked.
@@ -29,7 +29,7 @@
29
29
  import { redactText } from './redact.js';
30
30
 
31
31
  // Paths always logged, whatever the status.
32
- export const LOGGED_PATH = /^\/(?:authorize|token|register|revoke|oauth\/approve|mcp|\.well-known\/[^\s]*)$/;
32
+ export const LOGGED_PATH = /^\/(?:authorize|token|register|revoke|oauth\/approve|mcp|owner\/(?:chooser|break-glass|approvals)(?:\/[a-z]+(?:-[a-z]+)*)?|owner\/login|\.well-known\/[^\s]*)$/;
33
33
 
34
34
  const CLIP = 160;
35
35
  const clip = (v) => String(v).slice(0, CLIP);
@@ -68,7 +68,7 @@ export function requestLogEntry({ method, path, statusCode, ms, ip, query = {},
68
68
  entry.rpc = clip(b.method);
69
69
  if (b.method === 'tools/call' && b.params && b.params.name) {
70
70
  entry.tool = clip(b.params.name);
71
- // Parameter NAMES only (Alex, 2026-09-27, code audit 1.6) - values never.
71
+ // Parameter NAMES only (the owner, 2026-09-27, code audit 1.6) - values never.
72
72
  const a = b.params.arguments;
73
73
  if (a && typeof a === 'object' && !Array.isArray(a)) entry.params = Object.keys(a).sort().map(clip);
74
74
  }
package/src/rotate.js ADDED
@@ -0,0 +1,554 @@
1
+ /**
2
+ * Household rotate-all (R5a) and per-member revoke (R5b).
3
+ *
4
+ * The owner passphrase session is the only trigger. An AI or MCP grant is
5
+ * not a session. Confirm is a second step: a review post does not revoke.
6
+ *
7
+ * Revocation is a household generation plus a superseded_by pointer. Rows
8
+ * stay. The 60-second refresh grace is not consulted once a credential is
9
+ * inside this generation or marked superseded. Fresh invites are new rows.
10
+ * An old grant is never made live again.
11
+ *
12
+ * Railway EMET checks the generation on the next token request. This module
13
+ * does not call a deploy target.
14
+ */
15
+
16
+ import { COLLECTION_PREFIX } from './database.js';
17
+ import { setting } from './env.js';
18
+ import { assignCode, newCorrelationId } from './error-codes.js';
19
+ import { InvalidGrantError, InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
20
+ import { doorFromIssuedVia, grantIdFromFamily, logClientId, logDoor, logGrantId } from './grants.js';
21
+ import { isOwlIdentity } from './owl.js';
22
+ import { isBotTag } from './session-graph.js';
23
+ import { currentInstanceId, retireUnusedDeepLinks } from './deep-links.js';
24
+ import { esc } from './owner-session.js';
25
+
26
+ export const HOUSEHOLD_EPOCH_ID = 'household-epoch';
27
+ const ROTATIONS = 'rotations';
28
+ const LIVE_SUBKEY = new Set(['pending', 'approved', 'active', 'grace']);
29
+
30
+ const metric = {
31
+ events: 0,
32
+ last_at: null,
33
+ last_correlation_id: null,
34
+ last_decider: null,
35
+ last_revoked: null,
36
+ last_invites: null,
37
+ last_scope: null
38
+ };
39
+
40
+ export function _resetRotationForTests() {
41
+ metric.events = 0;
42
+ metric.last_at = null;
43
+ metric.last_correlation_id = null;
44
+ metric.last_decider = null;
45
+ metric.last_revoked = null;
46
+ metric.last_invites = null;
47
+ metric.last_scope = null;
48
+ }
49
+
50
+ export function rotateMetric() {
51
+ return {
52
+ rung: 'R5',
53
+ path: '/owner/break-glass',
54
+ grace_window_seconds: null,
55
+ events: metric.events,
56
+ last_at: metric.last_at,
57
+ last_correlation_id: metric.last_correlation_id,
58
+ last_decider: metric.last_decider,
59
+ last_revoked: metric.last_revoked,
60
+ last_invites: metric.last_invites,
61
+ last_scope: metric.last_scope,
62
+ since_process_start: true
63
+ };
64
+ }
65
+
66
+ export function rotateStartupLine() {
67
+ return `[emet] rotate-all path=/owner/break-glass rung=R5 events=${metric.events} grace_window_seconds=null`;
68
+ }
69
+
70
+ export function rotationTriggerAllowed({ session, authorization, door } = {}) {
71
+ if (door === 'member' || door === 'guest' || door === 'owner') return false;
72
+ if (typeof authorization === 'string' && /^bearer\s+\S+/i.test(authorization.trim())) return false;
73
+ return !!(session && session.csrf);
74
+ }
75
+
76
+ function safeDecider(id) {
77
+ const text = typeof id === 'string' && id.trim() ? id.trim() : 'owner';
78
+ return text.replace(/[\r\n\s]+/g, '_').slice(0, 80);
79
+ }
80
+
81
+ function cleanName(value) {
82
+ if (typeof value !== 'string') return null;
83
+ const text = value.trim();
84
+ if (!text || text.length > 80 || /[\r\n]/.test(text)) return null;
85
+ return text;
86
+ }
87
+
88
+ /**
89
+ * Member scope names one tag or one person. `*`, `all`, and the owner person
90
+ * are not a member. Household scope ignores both fields.
91
+ */
92
+ export function normalizeRotationRequest({ scope, tag, personId } = {}) {
93
+ if (scope !== 'member') return { ok: true, scope: 'household', tag: null, personId: null };
94
+ if (tag === '*' || tag === 'all' || personId === '*' || personId === 'all') {
95
+ return { ok: false, reason: 'one_subject' };
96
+ }
97
+ const tagOk = cleanName(tag);
98
+ const personOk = cleanName(personId);
99
+ if ((typeof tag === 'string' && tag.trim() && !tagOk) || (typeof personId === 'string' && personId.trim() && !personOk)) {
100
+ return { ok: false, reason: 'one_subject' };
101
+ }
102
+ if (!tagOk && !personOk) return { ok: false, reason: 'one_subject' };
103
+ return { ok: true, scope: 'member', tag: tagOk, personId: personOk };
104
+ }
105
+
106
+ export async function currentHouseholdGeneration(db, prefix = COLLECTION_PREFIX) {
107
+ if (!db || typeof db.collection !== 'function') return 0;
108
+ const row = await db.collection(`${prefix}${ROTATIONS}`).findOne({ _id: HOUSEHOLD_EPOCH_ID });
109
+ const n = row && row.generation;
110
+ return Number.isInteger(n) && n > 0 ? n : 0;
111
+ }
112
+
113
+ /**
114
+ * True when this stored credential must be refused. Reads the epoch every time.
115
+ * The stamp and the generation are both load-bearing. A row the stamp missed
116
+ * is still behind the epoch. A row at the current generation is still dead
117
+ * when it carries superseded_by or retired. tests/rotate-r5.test.js fails if
118
+ * the generation compare is removed or always false.
119
+ */
120
+ export async function credentialBlocked(db, prefix, doc) {
121
+ if (!doc || typeof doc !== 'object') return false;
122
+ if (doc.superseded_by || doc.retired === true) return true;
123
+ const generation = await currentHouseholdGeneration(db, prefix);
124
+ if (!generation) return false;
125
+ const tokenGen = Number.isInteger(doc.rotation_generation) ? doc.rotation_generation : 0;
126
+ return tokenGen < generation;
127
+ }
128
+
129
+ const ROTATED_INTRO = 'this credential was revoked by rotation. Re-onboard: keyed link, owner sign-in, assign the tag, initialize via /owner/chooser. No grace window.';
130
+
131
+ /** Log grant_id and correlation_id, then refuse. The invite code is not logged. */
132
+ export async function refuseRotatedCredential(doc, kind = 'access') {
133
+ const correlation_id = newCorrelationId();
134
+ const grant_id = logGrantId(grantIdFromFamily(doc && doc.family));
135
+ const door = doorFromIssuedVia(doc && doc.issued_via) || 'unknown';
136
+ console.error(`[emet] credential-revoked grant_id=${grant_id} correlation_id=${correlation_id} reonboard=/owner/chooser`);
137
+ try {
138
+ const { insertErrorLog } = await import('./error-log.js');
139
+ await insertErrorLog({
140
+ emet_code: 'EMET-AUTH-041',
141
+ class_code: 'INTERNAL_ERROR',
142
+ tool: kind === 'refresh' ? 'oauth_refresh' : (kind === 'code' ? 'oauth_code' : 'oauth_access'),
143
+ transport: 'http',
144
+ caller: 'unregistered',
145
+ role: 'guest',
146
+ client_id: logClientId(doc && doc.client_id),
147
+ grant_id,
148
+ door: logDoor(door),
149
+ correlation_id
150
+ });
151
+ } catch {
152
+ console.error('[emet] credential-revoked error-log write failed');
153
+ }
154
+ const message = `${ROTATED_INTRO} grant_id: ${grant_id}. correlation_id: ${correlation_id}`;
155
+ const err = assignCode(kind === 'access' ? new InvalidTokenError(message) : new InvalidGrantError(message), 'EMET-AUTH-041');
156
+ err.correlation_id = correlation_id;
157
+ err.grant_id = grant_id;
158
+ throw err;
159
+ }
160
+
161
+ function noteCommitted(record) {
162
+ metric.events += 1;
163
+ metric.last_at = record.at;
164
+ metric.last_correlation_id = record.correlation_id;
165
+ metric.last_decider = record.decider;
166
+ metric.last_revoked = record.revoked;
167
+ metric.last_invites = record.invites_issued;
168
+ metric.last_scope = record.scope;
169
+ console.error(`[emet] rotate-all scope=${record.scope} decider=${record.decider} correlation_id=${record.correlation_id} revoked=${record.revoked} invites=${record.invites_issued}`);
170
+ }
171
+
172
+ export function noteRotationRefused(reason, decider) {
173
+ const why = String(reason || 'refused').replace(/[^a-z_]/g, '').slice(0, 40) || 'refused';
174
+ console.error(`[emet] rotate-all refused reason=${why} decider=${safeDecider(decider)}`);
175
+ }
176
+
177
+ function blankSubject() {
178
+ return { tag: null, person_id: null, display_name: null, door: 'guest', writer: false };
179
+ }
180
+
181
+ function mergeSubject(subjects, key, fields) {
182
+ const prev = subjects.get(key) || blankSubject();
183
+ const writer = prev.writer || fields.writer || fields.door === 'member';
184
+ subjects.set(key, {
185
+ tag: fields.tag || prev.tag,
186
+ person_id: fields.person_id || prev.person_id,
187
+ display_name: fields.display_name || prev.display_name || fields.tag || fields.person_id || 'member',
188
+ door: writer ? 'member' : 'guest',
189
+ writer
190
+ });
191
+ }
192
+
193
+ function consider(subjects, item) {
194
+ const tag = cleanName(item.tag);
195
+ const person_id = cleanName(item.person_id);
196
+ const door = item.door === 'member' || item.door === 'guest' ? item.door : null;
197
+ const bot = !!(tag && isBotTag(tag));
198
+ const subkey = item.kind === 'subkey';
199
+ const memberDoor = door === 'member' || door === 'guest';
200
+ const personRow = item.kind === 'person';
201
+ if (personRow && item.role === 'owner') return;
202
+ if (!bot && !subkey && !memberDoor && !personRow) return;
203
+ // An owner-door grant's subject is the owner, shared by every bot on that
204
+ // login. The bot's identity is the tag. Only a member or guest door, or a
205
+ // person row, binds person_id.
206
+ const identityPerson = (memberDoor || personRow) ? person_id : null;
207
+ let key = null;
208
+ if (tag && (bot || subkey || memberDoor)) key = `tag:${tag}`;
209
+ else if (identityPerson) key = `person:${identityPerson}`;
210
+ if (!key) return;
211
+ if (identityPerson) {
212
+ for (const [existingKey, prev] of subjects) {
213
+ if (prev.person_id === identityPerson && existingKey !== key) {
214
+ const fields = {
215
+ tag: tag || prev.tag,
216
+ person_id: identityPerson,
217
+ display_name: item.display_name || prev.display_name,
218
+ door: door || prev.door,
219
+ writer: bot || subkey || door === 'member' || prev.writer
220
+ };
221
+ subjects.delete(existingKey);
222
+ if (existingKey.startsWith('tag:') && key.startsWith('person:')) key = existingKey;
223
+ mergeSubject(subjects, key, fields);
224
+ return;
225
+ }
226
+ }
227
+ }
228
+ mergeSubject(subjects, key, {
229
+ tag,
230
+ person_id: identityPerson,
231
+ display_name: item.display_name || tag || identityPerson,
232
+ door,
233
+ writer: bot || subkey || door === 'member'
234
+ });
235
+ }
236
+
237
+ function tokenInScope(row, spec) {
238
+ if (spec.scope === 'household') return true;
239
+ if (spec.tag && row.source_tag === spec.tag) return true;
240
+ if (spec.personId && row.subject === spec.personId) return true;
241
+ return false;
242
+ }
243
+
244
+ function inviteInScope(row, spec) {
245
+ if (spec.scope === 'household') return true;
246
+ if (spec.tag && row.source_tag === spec.tag) return true;
247
+ if (spec.personId && row.person_id === spec.personId) return true;
248
+ return false;
249
+ }
250
+
251
+ async function readAll(db, name) {
252
+ const col = db.collection(name);
253
+ if (!col || typeof col.find !== 'function') return [];
254
+ const cursor = col.find({});
255
+ if (!cursor || typeof cursor.toArray !== 'function') return [];
256
+ return cursor.toArray();
257
+ }
258
+
259
+ async function subkeyPicture(deps) {
260
+ if (setting('SUBKEYS') !== '1') return { keys: {}, sessions: [], skipped: true };
261
+ try {
262
+ const { loadSubkeyRecords } = await import('./subkeys.js');
263
+ const snap = await loadSubkeyRecords(deps || {});
264
+ return { keys: (snap && snap.keys) || {}, sessions: (snap && snap.sessions) || [], skipped: false };
265
+ } catch {
266
+ return { keys: {}, sessions: [], skipped: false, unavailable: true };
267
+ }
268
+ }
269
+
270
+ async function loadPicture(db, prefix, spec, deps) {
271
+ const tokens = await readAll(db, `${prefix}oauth_tokens`);
272
+ const codes = await readAll(db, `${prefix}oauth_codes`);
273
+ const invites = await readAll(db, 'invites');
274
+ const persons = await readAll(db, 'persons');
275
+ const subkeys = await subkeyPicture(deps);
276
+ const scopedTokens = tokens.filter((row) => row && tokenInScope(row, spec) && !row.superseded_by);
277
+ const scopedCodes = codes.filter((row) => row && tokenInScope(row, spec) && !row.superseded_by);
278
+ const grantIds = [...new Set(scopedTokens.map((row) => row.family).filter(Boolean))];
279
+ const subjects = new Map();
280
+ for (const row of scopedTokens) {
281
+ consider(subjects, {
282
+ kind: 'grant',
283
+ tag: row.source_tag,
284
+ person_id: row.subject,
285
+ door: doorFromIssuedVia(row.issued_via),
286
+ display_name: row.source_tag || row.subject
287
+ });
288
+ }
289
+ for (const row of invites) {
290
+ if (!row || row.used_at || row.retired_at || row.superseded_by) continue;
291
+ if (!inviteInScope(row, spec)) continue;
292
+ consider(subjects, {
293
+ kind: 'grant',
294
+ tag: row.source_tag,
295
+ person_id: row.person_id,
296
+ door: row.door === 'member' ? 'member' : 'guest',
297
+ display_name: row.display_name || row.source_tag
298
+ });
299
+ }
300
+ const tags = new Set();
301
+ if (spec.scope === 'member' && spec.tag) tags.add(spec.tag);
302
+ for (const row of scopedTokens) if (row.source_tag) tags.add(row.source_tag);
303
+ for (const row of invites) {
304
+ if (row && inviteInScope(row, spec) && row.source_tag) tags.add(row.source_tag);
305
+ }
306
+ const keyRows = Object.values(subkeys.keys || {});
307
+ for (const row of keyRows) {
308
+ if (!row || !row.tag) continue;
309
+ if (spec.scope === 'member' && !tags.has(row.tag)) continue;
310
+ if (!LIVE_SUBKEY.has(row.status)) continue;
311
+ consider(subjects, { kind: 'subkey', tag: row.tag, door: 'member', display_name: row.tag });
312
+ }
313
+ for (const person of persons) {
314
+ if (!person || person.role !== 'member') continue;
315
+ if (spec.scope === 'member' && spec.personId && person.person_id !== spec.personId) continue;
316
+ if (spec.scope === 'member' && !spec.personId) continue;
317
+ consider(subjects, {
318
+ kind: 'person',
319
+ role: person.role,
320
+ person_id: person.person_id,
321
+ door: person.door === 'member' ? 'member' : 'guest',
322
+ display_name: person.display_name || person.person_id
323
+ });
324
+ }
325
+ let sessions = 0;
326
+ for (const row of subkeys.sessions || []) {
327
+ if (!row || (row.state !== 'live' && row.state !== 'opening')) continue;
328
+ if (spec.scope === 'member') {
329
+ const key = keyRows.find((item) => item && item.key_id === row.key_id);
330
+ if (!key || !tags.has(key.tag)) continue;
331
+ }
332
+ sessions += 1;
333
+ }
334
+ const liveSubkeys = keyRows.filter((row) => {
335
+ if (!row || !LIVE_SUBKEY.has(row.status)) return false;
336
+ if (spec.scope === 'member' && !tags.has(row.tag)) return false;
337
+ return true;
338
+ }).length;
339
+ return {
340
+ tokenIds: scopedTokens.map((row) => row._id).filter((id) => id != null),
341
+ codeIds: scopedCodes.map((row) => row._id).filter((id) => id != null),
342
+ grantIds,
343
+ subjects: [...subjects.values()],
344
+ subkeys: liveSubkeys,
345
+ sessions,
346
+ subkeysUnavailable: subkeys.unavailable === true,
347
+ tagSet: spec.scope === 'household' ? null : tags
348
+ };
349
+ }
350
+
351
+ async function ownerPersonRefused(db, spec) {
352
+ if (spec.scope !== 'member' || !spec.personId) return false;
353
+ const person = await db.collection('persons').findOne({ person_id: spec.personId });
354
+ return !!(person && person.role === 'owner');
355
+ }
356
+
357
+ export async function describeRotation({ db, prefix = COLLECTION_PREFIX, deps = null, scope, tag, personId } = {}) {
358
+ if (!db) return { ok: false, reason: 'unavailable' };
359
+ const spec = normalizeRotationRequest({ scope, tag, personId });
360
+ if (!spec.ok) return spec;
361
+ if (await ownerPersonRefused(db, spec)) return { ok: false, reason: 'owner_is_not_a_member' };
362
+ const picture = await loadPicture(db, prefix, spec, deps);
363
+ return {
364
+ ok: true,
365
+ scope: spec.scope,
366
+ grants: picture.grantIds.length,
367
+ subkeys: picture.subkeys,
368
+ sessions: picture.sessions,
369
+ subjects: picture.subjects.map((row) => ({
370
+ tag: row.tag,
371
+ person_id: row.person_id,
372
+ door: row.door,
373
+ display_name: row.display_name
374
+ })),
375
+ subkeys_unavailable: picture.subkeysUnavailable
376
+ };
377
+ }
378
+
379
+ export async function commitRotation({
380
+ db,
381
+ prefix = COLLECTION_PREFIX,
382
+ deps = null,
383
+ scope,
384
+ tag,
385
+ personId,
386
+ issueInvite = true,
387
+ decider,
388
+ correlationId,
389
+ now = new Date()
390
+ } = {}) {
391
+ if (!db) return { ok: false, reason: 'unavailable' };
392
+ const spec = normalizeRotationRequest({ scope, tag, personId });
393
+ if (!spec.ok) return spec;
394
+ if (await ownerPersonRefused(db, spec)) return { ok: false, reason: 'owner_is_not_a_member' };
395
+ const picture = await loadPicture(db, prefix, spec, deps);
396
+ const at = now instanceof Date ? now : new Date(now);
397
+ const atIso = at.toISOString();
398
+ const eventId = newCorrelationId();
399
+ const correlation_id = typeof correlationId === 'string' && /^[0-9a-f]{16}$/.test(correlationId) ? correlationId : newCorrelationId();
400
+ const who = safeDecider(decider);
401
+ const event = {
402
+ _id: eventId,
403
+ kind: 'rotation_event',
404
+ scope: spec.scope,
405
+ status: 'committed',
406
+ at: atIso,
407
+ at_ms: at.getTime(),
408
+ decider: who,
409
+ correlation_id,
410
+ tag: spec.tag,
411
+ person_id: spec.personId,
412
+ grant_ids: picture.grantIds,
413
+ superseded_pointer: eventId,
414
+ retained: true,
415
+ deleted: false,
416
+ grace_window_seconds: null
417
+ };
418
+ const { openRotationEvent, finishRotationEvent } = await import('./oauth-provider.js');
419
+ await openRotationEvent(db, prefix, {
420
+ event,
421
+ epochId: HOUSEHOLD_EPOCH_ID,
422
+ household: spec.scope === 'household',
423
+ epochSet: {
424
+ kind: 'household_epoch',
425
+ status: 'committed',
426
+ at: atIso,
427
+ at_ms: at.getTime(),
428
+ event_id: eventId,
429
+ decider: who,
430
+ correlation_id
431
+ },
432
+ tokenIds: picture.tokenIds,
433
+ codeIds: picture.codeIds,
434
+ at: atIso
435
+ });
436
+ let subkeys = { revoked: 0, sessions: 0, unavailable: picture.subkeysUnavailable };
437
+ try {
438
+ const { retireSubkeysForRotation } = await import('./subkeys.js');
439
+ subkeys = await retireSubkeysForRotation(deps, {
440
+ eventId,
441
+ tags: spec.scope === 'household' ? null : picture.tagSet,
442
+ now: at
443
+ });
444
+ } catch {
445
+ subkeys = { revoked: 0, sessions: 0, unavailable: true };
446
+ }
447
+ const deepLinks = retireUnusedDeepLinks(eventId, spec.scope === 'household'
448
+ ? { all: true }
449
+ : { tag: spec.tag, grantIds: picture.grantIds }, at.getTime());
450
+ const { retireUnusedInvites, createRotationInvite } = await import('./invites.js');
451
+ const retiredInvites = await retireUnusedInvites(db, {
452
+ eventId,
453
+ at: atIso,
454
+ household: spec.scope === 'household',
455
+ tag: spec.tag,
456
+ personId: spec.personId
457
+ });
458
+ const invites = [];
459
+ let inviteFailures = 0;
460
+ if (issueInvite !== false) {
461
+ for (const subject of picture.subjects) {
462
+ if (isOwlIdentity({ source_tag: subject.tag, tag: subject.tag })) continue;
463
+ try {
464
+ const made = await createRotationInvite(db, {
465
+ created_by: who,
466
+ display_name: subject.display_name,
467
+ door: subject.door === 'member' ? 'member' : 'guest',
468
+ source_tag: subject.tag,
469
+ instance_id: currentInstanceId(),
470
+ rotation_event_id: eventId
471
+ });
472
+ invites.push({
473
+ tag: subject.tag,
474
+ person_id: subject.person_id,
475
+ door: made.door,
476
+ display_name: made.display_name,
477
+ code: made.code
478
+ });
479
+ } catch {
480
+ inviteFailures += 1;
481
+ }
482
+ }
483
+ }
484
+ const revoked = picture.grantIds.length + (subkeys.revoked || 0) + (subkeys.sessions || 0) + deepLinks + retiredInvites;
485
+ const record = {
486
+ at: atIso,
487
+ scope: spec.scope,
488
+ decider: who,
489
+ correlation_id,
490
+ revoked,
491
+ invites_issued: invites.length
492
+ };
493
+ await finishRotationEvent(db, prefix, eventId, {
494
+ revoked_grants: picture.grantIds.length,
495
+ revoked_subkeys: subkeys.revoked || 0,
496
+ revoked_sessions: subkeys.sessions || 0,
497
+ revoked_deep_links: deepLinks,
498
+ retired_invites: retiredInvites,
499
+ invites_issued: invites.length,
500
+ invite_failures: inviteFailures,
501
+ invite_subjects: picture.subjects.map((row) => row.tag || row.person_id),
502
+ subkeys_unavailable: subkeys.unavailable === true,
503
+ revoked
504
+ });
505
+ noteCommitted(record);
506
+ return {
507
+ ok: true,
508
+ event_id: eventId,
509
+ correlation_id,
510
+ decider: who,
511
+ scope: spec.scope,
512
+ revoked,
513
+ revoked_grants: picture.grantIds.length,
514
+ revoked_subkeys: subkeys.revoked || 0,
515
+ revoked_sessions: subkeys.sessions || 0,
516
+ revoked_deep_links: deepLinks,
517
+ retired_invites: retiredInvites,
518
+ invites_issued: invites.length,
519
+ invite_failures: inviteFailures,
520
+ grant_ids: picture.grantIds,
521
+ subjects: picture.subjects.map((row) => ({ tag: row.tag, person_id: row.person_id, door: row.door })),
522
+ invites
523
+ };
524
+ }
525
+
526
+ export function rotationForms(csrf) {
527
+ const token = esc(csrf);
528
+ return `<h2>Rotate every credential</h2>
529
+ <p>Owner session only. An AI client, a member grant, and a guest grant cannot run this. Review does not revoke. Confirming revokes every grant, sub-key, sub-key session, and unused deep link immediately. There is no grace window. Each known bot or member receives one new invite. Old grants stay retired.</p>
530
+ <form method="post" action="/owner/break-glass/rotate-all">
531
+ <input type="hidden" name="csrf" value="${token}">
532
+ <button type="submit" name="stage" value="review">Review rotate-all</button>
533
+ </form>
534
+ <h2>Revoke one member or bot</h2>
535
+ <form method="post" action="/owner/break-glass/revoke-member">
536
+ <input type="hidden" name="csrf" value="${token}">
537
+ <label>Tag <input type="text" name="tag" maxlength="80" autocomplete="off"></label>
538
+ <label>Person <input type="text" name="person_id" maxlength="80" autocomplete="off"></label>
539
+ <label><input type="checkbox" name="issue_invite" value="1"> Issue one fresh invite for that member</label>
540
+ <button type="submit" name="stage" value="review">Review revoke</button>
541
+ </form>`;
542
+ }
543
+
544
+ export function rotationConfirmForm({ csrf, action, confirm, fields = {} }) {
545
+ const hidden = Object.entries(fields)
546
+ .filter(([, value]) => value != null && value !== '')
547
+ .map(([key, value]) => `<input type="hidden" name="${esc(key)}" value="${esc(value)}">`)
548
+ .join('');
549
+ return `<form method="post" action="${esc(action)}">
550
+ <input type="hidden" name="csrf" value="${esc(csrf)}">
551
+ ${hidden}
552
+ <button type="submit" name="confirm" value="${esc(confirm)}">Confirm</button>
553
+ </form>`;
554
+ }
@@ -8,7 +8,7 @@
8
8
  * from authentication, the served hash is the pin, and the attestation
9
9
  * fields do not change on a later write. The file keeps SERVE_CAP rows per
10
10
  * principal. This release creates SERVE_COLLECTION (`<prefix>gem_serves`).
11
- * Alex approved it as an append-only write site on the write-path allow-list.
11
+ * the owner approved it as an append-only write site on the write-path allow-list.
12
12
  * The collection keeps every row. Nothing is deleted.
13
13
  */
14
14
  import crypto from 'node:crypto';