The best way to control Claude Code, Codex and more from any computer or phone

main
ts 450 lines 19.5 KB
Raw
1 // Answers stay in the secret store behind one-use refs; orchestration records only request status.
2 // Consuming tools keep values out of transcripts, projections, clients and model context.
3 // A `file` request instead moves its value to an owner-only file for the agent's own shell.
4 // A secret the user pasted in chat goes straight to such a file, with no card.
5 import {
6 CommandId,
7 SecretRef,
8 SecretRequestError,
9 type OrchestrationV2TurnItem,
10 type ProjectId,
11 type SecretReference,
12 type SecretRequestAnswerInput,
13 type ThreadId,
14 } from "@t3tools/contracts";
15 import * as SecretResolver from "@t3tools/secret-provider-core/server/SecretResolver";
16
17 import * as Clock from "effect/Clock";
18 import * as Context from "effect/Context";
19 import * as Mac from "effect/crypto/Mac";
20 import * as Effect from "effect/Effect";
21 import * as Hex from "effect/encoding/Hex";
22 import * as FileSystem from "effect/FileSystem";
23 import * as Layer from "effect/Layer";
24 import * as Option from "effect/Option";
25 import * as Path from "effect/Path";
26 import * as Schedule from "effect/Schedule";
27 import * as Schema from "effect/Schema";
28 import * as Semaphore from "effect/Semaphore";
29
30 import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
31 import * as Metrics from "../observability/Metrics.ts";
32 import * as ThreadManagementService from "../orchestration-v2/ThreadManagementService.ts";
33
34 const SECRET_REF_PREFIX = "secret-ref:";
35 const storeName = (ref: SecretRef) => `secret-request-${ref.slice(SECRET_REF_PREFIX.length)}`;
36 const REF_PATTERN = /^secret-ref:[0-9a-f]{32}$/;
37 const SECRET_REF_TTL_MS = 24 * 60 * 60 * 1000;
38 const STORE_NAME_PATTERN = /^(secret-request-[0-9a-f]{32})\.bin$/;
39 const FILE_NAME_PATTERN = /^[0-9a-f]{32}(\.partial)?$/;
40
41 const StoredSecret = Schema.fromJsonString(
42 Schema.Struct({ projectId: Schema.String, value: Schema.String, savedAt: Schema.Number }),
43 );
44 const encodeStored = Schema.encodeEffect(StoredSecret);
45 const decodeStored = Schema.decodeUnknownOption(StoredSecret);
46
47 type SecretRequestItem = Extract<OrchestrationV2TurnItem, { readonly type: "secret_request" }>;
48 /** `undefined` names the value of a request without fields. */
49 type FieldName = string | undefined;
50 const fieldNames = (item: SecretRequestItem): ReadonlyArray<FieldName> =>
51 item.fields?.map((field) => field.name) ?? [undefined];
52
53 /** The answer's value per field, or undefined when it does not answer exactly those fields. */
54 function answerValues(
55 item: SecretRequestItem,
56 answer: Exclude<SecretRequestAnswerInput["answer"], { readonly type: "decline" }>,
57 ): ReadonlyArray<readonly [FieldName, string]> | undefined {
58 if (item.fields === undefined)
59 return "secret" in answer ? [[undefined, answer.secret]] : undefined;
60 if (!("values" in answer)) return undefined;
61 const { values } = answer;
62 if (Object.keys(values).length !== item.fields.length) return undefined;
63 const entries: Array<readonly [string, string]> = [];
64 for (const field of item.fields) {
65 const value = Object.hasOwn(values, field.name) ? values[field.name] : undefined;
66 if (value === undefined) return undefined;
67 entries.push([field.name, value]);
68 }
69 return entries;
70 }
71
72 export class SecretRequests extends Context.Service<
73 SecretRequests,
74 {
75 readonly answer: (input: SecretRequestAnswerInput) => Effect.Effect<void, SecretRequestError>;
76 readonly savedRef: (input: {
77 readonly threadId: ThreadId;
78 readonly turnItemId: string;
79 }) => Effect.Effect<Option.Option<SecretRef>>;
80 readonly consume: (input: {
81 readonly ref: SecretRef;
82 readonly projectId: ProjectId;
83 }) => Effect.Effect<string, SecretRequestError>;
84 /** Moves a saved `file` request's values to owner-only files, one per field. */
85 readonly saveToFile: (input: {
86 readonly threadId: ThreadId;
87 readonly turnItemId: string;
88 }) => Effect.Effect<
89 { readonly file: string } | { readonly files: { readonly [name: string]: string } },
90 SecretRequestError
91 >;
92 /** Writes a secret the user pasted in chat to an owner-only file and returns its path. */
93 readonly savePasted: (input: {
94 readonly threadId: ThreadId;
95 /** The provider session's namespace, so two sessions' keys never share a file. */
96 readonly requestNamespace: string;
97 readonly requestKey: string;
98 readonly value: string;
99 }) => Effect.Effect<string, SecretRequestError>;
100 }
101 >()("t3/secrets/SecretRequests") {}
102
103 const make = Effect.gen(function* () {
104 const store = yield* ServerSecretStore.ServerSecretStore;
105 const fileSystem = yield* FileSystem.FileSystem;
106 const path = yield* Path.Path;
107 const threadManagement = yield* ThreadManagementService.ThreadManagementService;
108 const resolver = yield* SecretResolver.SecretResolver;
109 // Beside the store's own files so the same owner-only directory and cleanup rules apply.
110 const filesDir = store.directory === undefined ? undefined : path.join(store.directory, "files");
111
112 const mac = yield* Mac.Mac;
113 // Keyed by the salt's hex text, as refs saved by earlier versions were.
114 const refKey = yield* Mac.key(
115 Mac.hmacSha256,
116 new TextEncoder().encode(
117 Hex.encode(yield* store.getOrCreateRandom("secret-request-salt", 32).pipe(Effect.orDie)),
118 ),
119 ).pipe(Effect.orDie);
120 const refFor = (threadId: ThreadId, turnItemId: string, field?: string) =>
121 mac
122 .sign(
123 refKey,
124 new TextEncoder().encode(
125 field === undefined
126 ? `${threadId}\u0000${turnItemId}`
127 : `${threadId}\u0000${turnItemId}\u0000${field}`,
128 ),
129 )
130 .pipe(
131 Effect.orDie,
132 Effect.map((tag) => SecretRef.make(`${SECRET_REF_PREFIX}${Hex.encode(tag).slice(0, 32)}`)),
133 );
134 const removeAnswered = (threadId: ThreadId, item: SecretRequestItem) =>
135 Effect.forEach(fieldNames(item), (field) =>
136 refFor(threadId, item.id, field).pipe(Effect.flatMap((ref) => removeLogged(storeName(ref)))),
137 );
138
139 const readReference = Effect.fn("SecretRequests.readReference")(function* (
140 reference: SecretReference,
141 ) {
142 // The resolver keeps failed reads for the server's life; a retry after unlocking must re-read.
143 yield* resolver.invalidate([reference]);
144 const [value] = yield* resolver.read([reference]);
145 if (value === undefined || value.trim() === "") {
146 return yield* new SecretRequestError({
147 reason: "reference_unreadable",
148 provider: yield* resolver.label(reference.provider),
149 });
150 }
151 return value;
152 });
153
154 // One answer at a time: fields are stored one by one, so two racing answers could otherwise
155 // each keep some of their values on one card.
156 const answerLock = yield* Semaphore.make(1);
157 const answer: SecretRequests["Service"]["answer"] = Effect.fn("SecretRequests.answer")(function* (
158 input,
159 ) {
160 yield* Effect.annotateCurrentSpan({
161 "orchestration_v2.thread_id": input.threadId,
162 "secret_request.answer": input.answer.type,
163 });
164 const records = yield* threadManagement
165 .getThreadRecords(input.threadId, ["runs", "turnItems"], {
166 turnItemTypes: ["secret_request"],
167 messageRoles: [],
168 })
169 .pipe(Effect.mapError((cause) => new SecretRequestError({ reason: "load_failed", cause })));
170 const item = records.turnItems.find((candidate) => candidate.id === input.turnItemId);
171 if (item?.type !== "secret_request" || item.runId === null || item.nodeId === null) {
172 return yield* new SecretRequestError({ reason: "not_found" });
173 }
174 if (item.secretStatus !== "pending") {
175 return yield* new SecretRequestError({ reason: "already_answered" });
176 }
177 const run = records.runs.find((candidate) => candidate.id === item.runId);
178 if (run === undefined || ThreadManagementService.isTerminalRunStatus(run.status)) {
179 return yield* new SecretRequestError({ reason: "agent_stopped" });
180 }
181 // Create before recording so racing answers cannot overwrite values or show saved before storage.
182 // Existing values on pending cards finish earlier saves whose recording failed.
183 const values =
184 input.answer.type === "decline"
185 ? undefined
186 : input.answer.type === "reference" && item.fields === undefined
187 ? [[undefined, yield* readReference(input.answer.reference)] as const]
188 : (answerValues(item, input.answer) ??
189 (yield* new SecretRequestError({ reason: "fields_mismatch" })));
190 if (values !== undefined) {
191 const savedAt = yield* Clock.currentTimeMillis;
192 // Cleared when interrupted too, or a retry would keep these values beside its own.
193 yield* Effect.forEach(values, ([field, value]) =>
194 Effect.gen(function* () {
195 const encoded = yield* encodeStored({
196 projectId: records.thread.projectId,
197 value,
198 savedAt,
199 }).pipe(Effect.orDie);
200 yield* store
201 .create(
202 storeName(yield* refFor(input.threadId, item.id, field)),
203 new TextEncoder().encode(encoded),
204 )
205 .pipe(
206 Effect.catchIf(ServerSecretStore.isSecretAlreadyExistsError, () => Effect.void),
207 Effect.mapError(
208 (error) => new SecretRequestError({ reason: "store_failed", cause: error }),
209 ),
210 );
211 }),
212 ).pipe(Effect.onError(() => removeAnswered(input.threadId, item)));
213 }
214 const secretStatus = values === undefined ? "declined" : "saved";
215 yield* threadManagement
216 .dispatch({
217 type: "secret_request.record",
218 commandId: CommandId.make(`secret-request:${item.id}:${secretStatus}`),
219 threadId: input.threadId,
220 runId: item.runId,
221 nodeId: item.nodeId,
222 turnItemId: item.id,
223 label: item.label,
224 reason: item.reason,
225 ...(item.url === undefined ? {} : { url: item.url }),
226 ...(item.placeholder === undefined ? {} : { placeholder: item.placeholder }),
227 ...(item.delivery === undefined ? {} : { delivery: item.delivery }),
228 ...(item.fields === undefined ? {} : { fields: item.fields }),
229 secretStatus,
230 })
231 .pipe(
232 Effect.mapError((cause) => new SecretRequestError({ reason: "record_failed", cause })),
233 // Clear failed saves so the pending card can be answered again.
234 Effect.tapError(() =>
235 values !== undefined ? removeAnswered(input.threadId, item) : Effect.void,
236 ),
237 );
238 if (values === undefined) return;
239 // The wait may have closed the card; delete unrecorded answers because no one receives their refs.
240 const recorded = yield* threadManagement
241 .getThreadRecords(input.threadId, ["turnItems"], {
242 turnItemTypes: ["secret_request"],
243 messageRoles: [],
244 })
245 .pipe(Effect.mapError((cause) => new SecretRequestError({ reason: "record_failed", cause })));
246 const card = recorded.turnItems.find((candidate) => candidate.id === item.id);
247 if (card?.type === "secret_request" && card.secretStatus !== "saved") {
248 yield* removeAnswered(input.threadId, item);
249 return yield* new SecretRequestError({ reason: "agent_stopped" });
250 }
251 }, answerLock.withPermits(1));
252
253 const savedRef: SecretRequests["Service"]["savedRef"] = Effect.fn("SecretRequests.savedRef")(
254 function* (input) {
255 const ref = yield* refFor(input.threadId, input.turnItemId);
256 const stored = yield* store.get(storeName(ref)).pipe(Effect.orElseSucceed(Option.none));
257 return Option.map(stored, () => ref);
258 },
259 );
260
261 const removeLogged = (name: string) =>
262 store.remove(name).pipe(
263 Effect.as(true),
264 Effect.catch((error) =>
265 Effect.logWarning("Could not delete a secret request value", {
266 errorTag: error._tag,
267 }).pipe(Effect.as(false)),
268 ),
269 );
270
271 // Serialize get/remove so concurrent consumers cannot read the same one-use ref.
272 const consumeLock = yield* Semaphore.make(1);
273 const consume: SecretRequests["Service"]["consume"] = (input) =>
274 consumeRef(input).pipe(
275 consumeLock.withPermits(1),
276 Effect.tap(() => Metrics.increment(Metrics.secretRefsConsumedTotal, { result: "used" })),
277 Effect.tapError(() =>
278 Metrics.increment(Metrics.secretRefsConsumedTotal, { result: "rejected" }),
279 ),
280 Effect.withSpan("SecretRequests.consume"),
281 );
282
283 /** A live ref's value, left in the store. */
284 const readRef = Effect.fn("SecretRequests.readRef")(function* (input: {
285 readonly ref: SecretRef;
286 readonly projectId: ProjectId;
287 }) {
288 if (!REF_PATTERN.test(input.ref))
289 return yield* new SecretRequestError({ reason: "invalid_ref" });
290 const stored = yield* store
291 .get(storeName(input.ref))
292 .pipe(Effect.mapError((cause) => new SecretRequestError({ reason: "read_failed", cause })));
293 const decoded = Option.flatMap(stored, (bytes) =>
294 decodeStored(new TextDecoder().decode(bytes)),
295 );
296 if (Option.isNone(decoded) || decoded.value.projectId !== input.projectId) {
297 return yield* new SecretRequestError({ reason: "ref_unavailable" });
298 }
299 if ((yield* Clock.currentTimeMillis) - decoded.value.savedAt > SECRET_REF_TTL_MS) {
300 yield* removeLogged(storeName(input.ref));
301 return yield* new SecretRequestError({ reason: "ref_expired" });
302 }
303 return decoded.value.value;
304 });
305
306 const consumeRef = Effect.fn("SecretRequests.consumeRef")(function* (input: {
307 readonly ref: SecretRef;
308 readonly projectId: ProjectId;
309 }) {
310 const value = yield* readRef(input);
311 // One use: the value moves into whatever consumed it. If it cannot be
312 // deleted, it is not handed out, so a ref is never used twice.
313 if (!(yield* removeLogged(storeName(input.ref)))) {
314 return yield* new SecretRequestError({ reason: "consume_failed" });
315 }
316 return value;
317 });
318
319 const writeSecretFile = (dir: string, file: string, value: string) => {
320 const partial = `${file}.partial`;
321 return fileSystem.makeDirectory(dir, { recursive: true, mode: 0o700 }).pipe(
322 Effect.andThen(fileSystem.chmod(dir, 0o700)),
323 Effect.andThen(fileSystem.remove(partial, { force: true })),
324 // `wx` never follows or replaces an existing path.
325 Effect.andThen(
326 fileSystem.writeFile(partial, new TextEncoder().encode(value), {
327 flag: "wx",
328 mode: 0o600,
329 }),
330 ),
331 Effect.andThen(fileSystem.rename(partial, file)),
332 Effect.mapError((cause) => new SecretRequestError({ reason: "store_failed", cause })),
333 );
334 };
335
336 const saveToFile: SecretRequests["Service"]["saveToFile"] = Effect.fn(
337 "SecretRequests.saveToFile",
338 )(function* (input) {
339 const records = yield* threadManagement
340 .getThreadRecords(input.threadId, ["turnItems"], {
341 turnItemTypes: ["secret_request"],
342 messageRoles: [],
343 })
344 .pipe(Effect.mapError((cause) => new SecretRequestError({ reason: "load_failed", cause })));
345 const item = records.turnItems.find((candidate) => candidate.id === input.turnItemId);
346 // Only a card that told the user the agent's commands can read the value may write it out.
347 if (
348 item?.type !== "secret_request" ||
349 item.secretStatus !== "saved" ||
350 item.delivery !== "file"
351 ) {
352 return yield* new SecretRequestError({ reason: "not_a_file_request" });
353 }
354 if (filesDir === undefined) return yield* new SecretRequestError({ reason: "store_failed" });
355 const projectId = records.thread.projectId;
356 const deliver = Effect.fn("SecretRequests.deliverFile")(function* (field: FieldName) {
357 const ref = yield* refFor(input.threadId, item.id, field);
358 const file = path.join(filesDir, ref.slice(SECRET_REF_PREFIX.length));
359 // One use: the file counts as delivered only once the stored copy is gone. A retry with the
360 // same clientRequestId gets the file the first call wrote and finishes that removal.
361 const removeStored = removeLogged(storeName(ref)).pipe(
362 Effect.flatMap((removed) =>
363 removed ? Effect.succeed(file) : new SecretRequestError({ reason: "consume_failed" }),
364 ),
365 );
366 if (yield* fileSystem.exists(file).pipe(Effect.orElseSucceed(() => false))) {
367 return yield* removeStored;
368 }
369 // The stored value goes only after the file is complete, so a failed write can retry.
370 const value = yield* readRef({ ref, projectId });
371 yield* writeSecretFile(filesDir, file, value);
372 return yield* removeStored;
373 });
374 const { fields } = item;
375 return yield* Effect.gen(function* () {
376 if (fields === undefined) return { file: yield* deliver(undefined) };
377 const files: Record<string, string> = {};
378 for (const field of fields) files[field.name] = yield* deliver(field.name);
379 return { files };
380 }).pipe(consumeLock.withPermits(1));
381 });
382
383 const savePasted: SecretRequests["Service"]["savePasted"] = Effect.fn(
384 "SecretRequests.savePasted",
385 )(function* (input) {
386 if (filesDir === undefined) return yield* new SecretRequestError({ reason: "store_failed" });
387 const ref = yield* refFor(
388 input.threadId,
389 `pasted\u0000${input.requestNamespace}\u0000${input.requestKey}`,
390 );
391 const file = path.join(filesDir, ref.slice(SECRET_REF_PREFIX.length));
392 // A retry with the same clientRequestId gets the file the first call wrote, unchanged, so a
393 // command already holding that path never reads another value.
394 return yield* Effect.gen(function* () {
395 if (yield* fileSystem.exists(file).pipe(Effect.orElseSucceed(() => false))) return file;
396 yield* writeSecretFile(filesDir, file, input.value);
397 return file;
398 }).pipe(consumeLock.withPermits(1));
399 });
400
401 const sweepExpired = Effect.gen(function* () {
402 if (store.directory === undefined) return;
403 const now = yield* Clock.currentTimeMillis;
404 const names = (yield* fileSystem.readDirectory(store.directory)).flatMap((file) => {
405 const match = STORE_NAME_PATTERN.exec(file);
406 return match?.[1] === undefined ? [] : [match[1]];
407 });
408 let removed = 0;
409 for (const name of names) {
410 const stored = yield* store.get(name).pipe(Effect.orElseSucceed(Option.none));
411 const decoded = Option.flatMap(stored, (bytes) =>
412 decodeStored(new TextDecoder().decode(bytes)),
413 );
414 if (Option.isSome(decoded) && now - decoded.value.savedAt <= SECRET_REF_TTL_MS) continue;
415 if (yield* removeLogged(name)) removed += 1;
416 }
417 yield* Effect.annotateCurrentSpan({ "secret_request.expired_removed": removed });
418 }).pipe(
419 Effect.catchCause((cause) => Effect.logWarning("Could not sweep expired secret refs", cause)),
420 Effect.withSpan("SecretRequests.sweepExpired"),
421 );
422 const sweepExpiredFiles = Effect.gen(function* () {
423 if (filesDir === undefined || !(yield* fileSystem.exists(filesDir))) return;
424 const now = yield* Clock.currentTimeMillis;
425 let removed = 0;
426 for (const name of yield* fileSystem.readDirectory(filesDir)) {
427 if (!FILE_NAME_PATTERN.test(name)) continue;
428 const file = path.join(filesDir, name);
429 const { mtime } = yield* fileSystem.stat(file);
430 if (Option.exists(mtime, (time) => now - time.getTime() <= SECRET_REF_TTL_MS)) continue;
431 yield* fileSystem.remove(file);
432 removed += 1;
433 }
434 yield* Effect.annotateCurrentSpan({ "secret_request.expired_files_removed": removed });
435 }).pipe(
436 Effect.catchCause((cause) => Effect.logWarning("Could not sweep expired secret files", cause)),
437 Effect.withSpan("SecretRequests.sweepExpiredFiles"),
438 );
439 const sweep = Effect.andThen(sweepExpired, sweepExpiredFiles);
440 yield* sweep;
441 yield* sweep.pipe(
442 Effect.delay("1 hour"),
443 Effect.repeat(Schedule.spaced("1 hour")),
444 Effect.forkScoped,
445 );
446
447 return SecretRequests.of({ answer, savedRef, consume, saveToFile, savePasted });
448 });
449
450 export const layer = Layer.effect(SecretRequests, make);