@cortexkit/common-auth 0.38.0 → 0.39.1

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.
@@ -1,3 +1,9 @@
1
+ type LeaseCreationTestHooks = {
2
+ beforeWrite?: (path: string) => void | Promise<void>;
3
+ beforeLink?: (tempPath: string, lockPath: string) => void | Promise<void>;
4
+ };
5
+ /** Test-only creation faults; not re-exported from the public fs entry point. */
6
+ export declare function setLeaseCreationTestHooksForTest(hooks?: LeaseCreationTestHooks): void;
1
7
  export declare function isLostMarkerRaceError(error: unknown): boolean;
2
8
  /** Test-only fault injection between marker mkdir and owner.json write. */
3
9
  export interface EvictionMarkerTestHooks {
@@ -1,8 +1,50 @@
1
1
  import { randomUUID } from 'node:crypto';
2
- import { lstat, mkdir, open, readFile, rename, rm, stat, } from 'node:fs/promises';
2
+ import { link, lstat, mkdir, open, readFile, rename, rm, stat, } from 'node:fs/promises';
3
3
  import { dirname, join } from 'node:path';
4
4
  import { createPrivateBytes, createPrivateDirectoryExclusive, ensurePrivateDirectory, isWindowsSharingViolation, PrivateFileError, privateOperation, readPrivateText, verifyPrivate, windowsPrivateFiles, writePrivateAtomic, } from './private-files.js';
5
5
  import { LockOwnershipError, lockPathFor } from './with-lock.js';
6
+ let leaseCreationTestHooks;
7
+ /** Test-only creation faults; not re-exported from the public fs entry point. */
8
+ export function setLeaseCreationTestHooksForTest(hooks) {
9
+ leaseCreationTestHooks = hooks;
10
+ }
11
+ async function createExclusiveText(path, text) {
12
+ // Publish only a complete owner record. A crash before link leaves at most
13
+ // an orphaned staging file, never an ownerless lease at the lock path.
14
+ const tempPath = `${path}.${randomUUID()}.tmp`;
15
+ let handle;
16
+ try {
17
+ handle = await open(tempPath, 'wx', 0o600);
18
+ try {
19
+ if (leaseCreationTestHooks?.beforeWrite)
20
+ await leaseCreationTestHooks.beforeWrite(tempPath);
21
+ await handle.writeFile(text, 'utf8');
22
+ }
23
+ finally {
24
+ await handle.close();
25
+ }
26
+ try {
27
+ if (leaseCreationTestHooks?.beforeLink)
28
+ await leaseCreationTestHooks.beforeLink(tempPath, path);
29
+ await link(tempPath, path);
30
+ }
31
+ catch (error) {
32
+ const code = error.code;
33
+ if (code !== 'EPERM' &&
34
+ code !== 'ENOTSUP' &&
35
+ code !== 'EOPNOTSUPP' &&
36
+ code !== 'EXDEV')
37
+ throw error;
38
+ // Filesystems without hard links still use exclusive create then write.
39
+ // A crash can leave an incomplete lease there, but locking stays available.
40
+ await writeExclusiveText(path, text);
41
+ }
42
+ }
43
+ finally {
44
+ if (handle)
45
+ await rm(tempPath, { force: true }).catch(() => { });
46
+ }
47
+ }
6
48
  /**
7
49
  * Create a new owner-only file and write `text` into it, failing with EEXIST if
8
50
  * the file already exists. Writing through the handle rather than path-based
@@ -11,7 +53,7 @@ import { LockOwnershipError, lockPathFor } from './with-lock.js';
11
53
  * that redundant ftruncate stalls for hundreds of milliseconds, inside every
12
54
  * lock acquisition.
13
55
  */
14
- async function createExclusiveText(path, text) {
56
+ async function writeExclusiveText(path, text) {
15
57
  const handle = await open(path, 'wx', 0o600);
16
58
  let createdStat;
17
59
  try {
@@ -21,6 +63,8 @@ async function createExclusiveText(path, text) {
21
63
  createdStat = undefined;
22
64
  }
23
65
  try {
66
+ if (leaseCreationTestHooks?.beforeWrite)
67
+ await leaseCreationTestHooks.beforeWrite(path);
24
68
  await handle.writeFile(text, 'utf8');
25
69
  }
26
70
  catch (error) {
@@ -491,7 +535,7 @@ export async function acquireRefreshFileLockWithClock(options) {
491
535
  if (windowsPrivateFiles)
492
536
  await createPrivateBytes(evictOwnerPath, bytes);
493
537
  else
494
- await createExclusiveText(evictOwnerPath, bytes);
538
+ await writeExclusiveText(evictOwnerPath, bytes);
495
539
  }
496
540
  catch (error) {
497
541
  // A competing contender can rename our just-created marker directory
@@ -1,2 +1,8 @@
1
- /** Canonicalize the parent even when the store file has not been created yet. */
1
+ /**
2
+ * Canonicalize a store path even when the store file, or folders above it,
3
+ * have not been created yet. The nearest existing ancestor folder is resolved
4
+ * through symlinks and junctions; the missing folders and the file name are
5
+ * appended unchanged. Two aliases of one folder therefore agree before and
6
+ * after a process creates the store's folder.
7
+ */
2
8
  export declare function canonicalLimitsPath(path: string): string;
@@ -1,14 +1,31 @@
1
1
  import { realpathSync } from 'node:fs';
2
2
  import { basename, dirname, join, resolve } from 'node:path';
3
- /** Canonicalize the parent even when the store file has not been created yet. */
3
+ /**
4
+ * Canonicalize a store path even when the store file, or folders above it,
5
+ * have not been created yet. The nearest existing ancestor folder is resolved
6
+ * through symlinks and junctions; the missing folders and the file name are
7
+ * appended unchanged. Two aliases of one folder therefore agree before and
8
+ * after a process creates the store's folder.
9
+ */
4
10
  export function canonicalLimitsPath(path) {
5
- try {
6
- return join(realpathSync.native(dirname(path)), basename(path));
7
- }
8
- catch (error) {
9
- const code = error.code;
10
- if (code === 'ENOENT' || code === 'ENOTDIR')
11
- return resolve(path);
12
- throw error;
11
+ const absolute = resolve(path);
12
+ const missing = [basename(absolute)];
13
+ let folder = dirname(absolute);
14
+ for (;;) {
15
+ try {
16
+ return join(realpathSync.native(folder), ...missing.reverse());
17
+ }
18
+ catch (error) {
19
+ const code = error.code;
20
+ if (code !== 'ENOENT' && code !== 'ENOTDIR')
21
+ throw error;
22
+ const parent = dirname(folder);
23
+ // Nothing above exists (an unmounted drive or a removed root): keep the
24
+ // plain absolute path, as earlier versions did for a missing parent.
25
+ if (parent === folder)
26
+ return absolute;
27
+ missing.push(basename(folder));
28
+ folder = parent;
29
+ }
13
30
  }
14
31
  }
@@ -1,3 +1,8 @@
1
+ /**
2
+ * Optional THALAMUS routing for vault mode and advisory turn notes for request
3
+ * shaping. Account ids are vault account ids, not local pool rows. Nothing is
4
+ * persisted here; plugins on routes the runner does not serve get no turn notes.
5
+ */
1
6
  /** An eligible vault route, not a local pool row. */
2
7
  export interface RoutingCandidate {
3
8
  /** Vault account id, not the plugin's route id. */
@@ -35,7 +40,7 @@ interface RoutingReportIdentity {
35
40
  accountId: string;
36
41
  credentialId?: string;
37
42
  }
38
- export type ReportRoutingInput = RoutingReportIdentity & ({
43
+ export type ReportRoutingInput = (RoutingReportIdentity & ({
39
44
  outcome: 'served';
40
45
  /**
41
46
  * Pass only rate-limit headers, never the whole response headers.
@@ -56,7 +61,26 @@ export type ReportRoutingInput = RoutingReportIdentity & ({
56
61
  pool?: string;
57
62
  /** Optional reset time in epoch milliseconds. */
58
63
  resetsAt?: number;
59
- });
64
+ })) | {
65
+ sessionId: string;
66
+ kind: 'turn_notes_supported';
67
+ model: string;
68
+ supported: boolean;
69
+ } | {
70
+ sessionId: string;
71
+ kind: 'turn_note_skipped';
72
+ after_tool_use_id: string;
73
+ reason: 'anchor_missing' | 'before_user_message' | 'unsupported_model' | 'not_oauth';
74
+ };
75
+ /**
76
+ * Read advisory input for request shaping, in landing order, without persisting
77
+ * it. If no routing handle is available or the runner does not serve the route,
78
+ * returns [].
79
+ */
80
+ export declare function turnNotes(sessionId: string): readonly {
81
+ afterToolUseId: string;
82
+ text: string;
83
+ }[];
60
84
  /**
61
85
  * Ask routing for an eligible vault route. Any failure or unfamiliar answer
62
86
  * yields undefined so the plugin can keep its own choice. This does not admit
@@ -64,9 +88,10 @@ export type ReportRoutingInput = RoutingReportIdentity & ({
64
88
  */
65
89
  export declare function askRouting<Candidate extends RoutingCandidate>(input: AskRoutingInput<Candidate>): Promise<RoutingSelection<Candidate> | undefined>;
66
90
  /**
67
- * Report a vault request without waiting for routing. Only contract fields are
68
- * sent, and all accessor failures are ignored. Headers must already be limited
69
- * to rate-limit headers by the caller; values are not filtered or redacted here.
91
+ * Report a vault request or turn-note event without waiting for routing. Only
92
+ * contract fields are sent, and all accessor failures are ignored. Headers must
93
+ * already be limited to rate-limit headers by the caller; values are not filtered
94
+ * or redacted here.
70
95
  */
71
96
  export declare function reportRouting(input: ReportRoutingInput): void;
72
97
  export {};
@@ -1,9 +1,60 @@
1
- // Optional THALAMUS routing for vault mode only. Account ids here are vault
2
- // account ids; local pool rows are not known to the routing engine.
1
+ /**
2
+ * Optional THALAMUS routing for vault mode and advisory turn notes for request
3
+ * shaping. Account ids are vault account ids, not local pool rows. Nothing is
4
+ * persisted here; plugins on routes the runner does not serve get no turn notes.
5
+ */
3
6
  import { routingHandle } from './handle.js';
4
7
  function isObject(value) {
5
8
  return typeof value === 'object' && value !== null;
6
9
  }
10
+ /**
11
+ * Read advisory input for request shaping, in landing order, without persisting
12
+ * it. If no routing handle is available or the runner does not serve the route,
13
+ * returns [].
14
+ */
15
+ export function turnNotes(sessionId) {
16
+ try {
17
+ const handle = routingHandle(sessionId);
18
+ if (!handle)
19
+ return [];
20
+ const read = handle.turn_notes;
21
+ if (typeof read !== 'function')
22
+ return [];
23
+ const answer = read.call(handle);
24
+ if (isObject(answer) && typeof answer.then === 'function') {
25
+ void Promise.resolve(answer).catch(() => { });
26
+ return [];
27
+ }
28
+ if (!Array.isArray(answer))
29
+ return [];
30
+ const notes = [];
31
+ const encoder = new TextEncoder();
32
+ for (const entry of answer) {
33
+ try {
34
+ if (!isObject(entry) || Array.isArray(entry))
35
+ continue;
36
+ const afterToolUseId = entry.after_tool_use_id;
37
+ const text = entry.text;
38
+ if (typeof afterToolUseId !== 'string' ||
39
+ afterToolUseId.length === 0 ||
40
+ typeof text !== 'string' ||
41
+ // A whitespace-only note says nothing and a provider may refuse it.
42
+ text.trim().length === 0 ||
43
+ encoder.encode(text).byteLength > 16_384)
44
+ continue;
45
+ notes.push({ afterToolUseId, text });
46
+ }
47
+ catch {
48
+ // One unreadable note entry must not hide its valid neighbours.
49
+ }
50
+ }
51
+ return notes;
52
+ }
53
+ catch {
54
+ // Turn notes are optional and must not break request shaping.
55
+ return [];
56
+ }
57
+ }
7
58
  function selectionFor(answer, candidates) {
8
59
  if (!isObject(answer))
9
60
  return undefined;
@@ -72,9 +123,10 @@ export async function askRouting(input) {
72
123
  }
73
124
  }
74
125
  /**
75
- * Report a vault request without waiting for routing. Only contract fields are
76
- * sent, and all accessor failures are ignored. Headers must already be limited
77
- * to rate-limit headers by the caller; values are not filtered or redacted here.
126
+ * Report a vault request or turn-note event without waiting for routing. Only
127
+ * contract fields are sent, and all accessor failures are ignored. Headers must
128
+ * already be limited to rate-limit headers by the caller; values are not filtered
129
+ * or redacted here.
78
130
  */
79
131
  export function reportRouting(input) {
80
132
  try {
@@ -84,38 +136,75 @@ export function reportRouting(input) {
84
136
  const report = handle.report;
85
137
  if (typeof report !== 'function')
86
138
  return;
87
- const identity = {
88
- account_id: input.accountId,
89
- ...(input.credentialId !== undefined
90
- ? { credential_id: input.credentialId }
91
- : {}),
92
- };
93
139
  let payload;
94
- switch (input.outcome) {
95
- case 'served':
96
- payload = { ...identity, outcome: 'served', headers: input.headers };
97
- break;
98
- case 'exhausted': {
99
- const { window, pool } = input;
100
- if (window !== '5h' && window !== '7d')
140
+ if ('kind' in input) {
141
+ switch (input.kind) {
142
+ case 'turn_notes_supported': {
143
+ const { model, supported } = input;
144
+ if (typeof model !== 'string' ||
145
+ model.length === 0 ||
146
+ typeof supported !== 'boolean')
147
+ return;
148
+ payload = {
149
+ kind: 'turn_notes_supported',
150
+ model,
151
+ supported,
152
+ };
153
+ break;
154
+ }
155
+ case 'turn_note_skipped': {
156
+ const { after_tool_use_id, reason } = input;
157
+ if (typeof after_tool_use_id !== 'string' ||
158
+ after_tool_use_id.length === 0 ||
159
+ (reason !== 'anchor_missing' &&
160
+ reason !== 'before_user_message' &&
161
+ reason !== 'unsupported_model' &&
162
+ reason !== 'not_oauth'))
163
+ return;
164
+ payload = {
165
+ kind: 'turn_note_skipped',
166
+ after_tool_use_id,
167
+ reason,
168
+ };
169
+ break;
170
+ }
171
+ default:
101
172
  return;
102
- // An undefined pool means the whole account, as an omitted one does.
103
- if (pool !== undefined &&
104
- (typeof pool !== 'string' || !/^[a-z0-9._-]{1,64}$/.test(pool)))
173
+ }
174
+ }
175
+ else {
176
+ const identity = {
177
+ account_id: input.accountId,
178
+ ...(input.credentialId !== undefined
179
+ ? { credential_id: input.credentialId }
180
+ : {}),
181
+ };
182
+ switch (input.outcome) {
183
+ case 'served':
184
+ payload = { ...identity, outcome: 'served', headers: input.headers };
185
+ break;
186
+ case 'exhausted': {
187
+ const { window, pool } = input;
188
+ if (window !== '5h' && window !== '7d')
189
+ return;
190
+ // An undefined pool means the whole account, as an omitted one does.
191
+ if (pool !== undefined &&
192
+ (typeof pool !== 'string' || !/^[a-z0-9._-]{1,64}$/.test(pool)))
193
+ return;
194
+ payload = {
195
+ ...identity,
196
+ outcome: 'exhausted',
197
+ window,
198
+ ...(pool ? { pool } : {}),
199
+ ...(input.resetsAt !== undefined
200
+ ? { resets_at: input.resetsAt }
201
+ : {}),
202
+ };
203
+ break;
204
+ }
205
+ default:
105
206
  return;
106
- payload = {
107
- ...identity,
108
- outcome: 'exhausted',
109
- window,
110
- ...(pool ? { pool } : {}),
111
- ...(input.resetsAt !== undefined
112
- ? { resets_at: input.resetsAt }
113
- : {}),
114
- };
115
- break;
116
207
  }
117
- default:
118
- return;
119
208
  }
120
209
  // A broken bridge may return a rejected promise despite its void contract.
121
210
  const pending = report.call(handle, payload);
@@ -1,2 +1,8 @@
1
+ /**
2
+ * The package records `npm pack --json` printed. Up to npm 11 it prints an
3
+ * array of records; from npm 12 an object keyed by package name. The records
4
+ * themselves (`filename`, `files[].path`) have the same fields in both.
5
+ */
6
+ export declare function packedRecords<T>(parsed: unknown): T[];
1
7
  /** Compare the files npm actually publishes, not the manifest's glob patterns. */
2
8
  export declare function assertEmittedPublishList(packageRoot: string, destinationDir: string, emitted: readonly string[]): Promise<void>;
@@ -1,10 +1,22 @@
1
1
  import { execFile } from 'node:child_process';
2
2
  import { relative, resolve } from 'node:path';
3
3
  import { promisify } from 'node:util';
4
+ /**
5
+ * The package records `npm pack --json` printed. Up to npm 11 it prints an
6
+ * array of records; from npm 12 an object keyed by package name. The records
7
+ * themselves (`filename`, `files[].path`) have the same fields in both.
8
+ */
9
+ export function packedRecords(parsed) {
10
+ if (Array.isArray(parsed))
11
+ return parsed;
12
+ if (parsed !== null && typeof parsed === 'object')
13
+ return Object.values(parsed);
14
+ return [];
15
+ }
4
16
  /** Compare the files npm actually publishes, not the manifest's glob patterns. */
5
17
  export async function assertEmittedPublishList(packageRoot, destinationDir, emitted) {
6
18
  const { stdout } = await promisify(execFile)('npm', ['pack', '--json', '--dry-run', '--ignore-scripts'], { cwd: packageRoot });
7
- const packed = JSON.parse(stdout);
19
+ const packed = packedRecords(JSON.parse(stdout));
8
20
  const prefix = `${relative(resolve(packageRoot), resolve(destinationDir)).split('\\').join('/')}/`;
9
21
  const packageInfo = packed[0];
10
22
  if (!packageInfo)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cortexkit/common-auth",
3
- "version": "0.38.0",
3
+ "version": "0.39.1",
4
4
  "description": "Shared code for the CortexKit auth plugins: account pool, quota and routing, commands and auth menu, OpenCode 2 hooks, Claustrum custody, and plumbing (loopback RPC, file locks, logger, sidebar state, TUI preferences and build).",
5
5
  "license": "MIT",
6
6
  "repository": {