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

main
ts 1,343 lines 49.7 KB
Raw
1 import * as Context from "effect/Context";
2 import * as Schema from "effect/Schema";
3 import * as HttpApi from "effect/http-api/HttpApi";
4 import * as HttpApiEndpoint from "effect/http-api/HttpApiEndpoint";
5 import * as HttpApiGroup from "effect/http-api/HttpApiGroup";
6 import * as HttpApiMiddleware from "effect/http-api/HttpApiMiddleware";
7 import * as HttpApiSchema from "effect/http-api/HttpApiSchema";
8 import * as HttpApiSecurity from "effect/http-api/HttpApiSecurity";
9 import * as OpenApi from "effect/http-api/OpenApi";
10
11 import {
12 DpopFailureReason,
13 EnvironmentId,
14 ThreadId,
15 TrimmedNonEmptyString,
16 } from "./baseSchemas.ts";
17 import { ExecutionEnvironmentDescriptor } from "./environment.ts";
18
19 export const RelayAgentAwarenessPlatform = Schema.Literals(["ios", "android"]);
20 export type RelayAgentAwarenessPlatform = typeof RelayAgentAwarenessPlatform.Type;
21
22 export const RelayAgentAwarenessPhase = Schema.Literals([
23 "starting",
24 "running",
25 "waiting_for_approval",
26 "waiting_for_input",
27 "completed",
28 "failed",
29 "stale",
30 ]);
31 export type RelayAgentAwarenessPhase = typeof RelayAgentAwarenessPhase.Type;
32
33 export const RelayAgentAwarenessPreferences = Schema.Struct({
34 liveActivitiesEnabled: Schema.Boolean,
35 notificationsEnabled: Schema.Boolean,
36 notifyOnApproval: Schema.Boolean,
37 notifyOnInput: Schema.Boolean,
38 notifyOnCompletion: Schema.Boolean,
39 notifyOnFailure: Schema.Boolean,
40 });
41 export type RelayAgentAwarenessPreferences = typeof RelayAgentAwarenessPreferences.Type;
42
43 export const RelayApnsEnvironment = Schema.Literals(["sandbox", "production"]);
44 export type RelayApnsEnvironment = typeof RelayApnsEnvironment.Type;
45
46 export const RelayDeviceRegistrationRequest = Schema.Struct({
47 deviceId: TrimmedNonEmptyString,
48 label: TrimmedNonEmptyString,
49 platform: RelayAgentAwarenessPlatform,
50 iosMajorVersion: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(18))),
51 androidApiLevel: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(24))),
52 appVersion: Schema.optional(TrimmedNonEmptyString),
53 // APNs topic must match the variant's bundle id; development-signed builds use sandbox tokens.
54 bundleId: Schema.optional(TrimmedNonEmptyString),
55 apsEnvironment: Schema.optional(RelayApnsEnvironment),
56 pushToken: Schema.optional(TrimmedNonEmptyString),
57 pushToStartToken: Schema.optional(TrimmedNonEmptyString),
58 preferences: RelayAgentAwarenessPreferences,
59 }).check(
60 Schema.makeFilter((device) =>
61 device.platform === "ios"
62 ? device.iosMajorVersion !== undefined
63 : device.androidApiLevel !== undefined &&
64 device.iosMajorVersion === undefined &&
65 device.apsEnvironment === undefined &&
66 device.pushToStartToken === undefined,
67 ),
68 );
69 export type RelayDeviceRegistrationRequest = typeof RelayDeviceRegistrationRequest.Type;
70
71 export const RelayClientDeviceRecord = Schema.Struct({
72 deviceId: TrimmedNonEmptyString,
73 label: TrimmedNonEmptyString,
74 platform: RelayAgentAwarenessPlatform,
75 iosMajorVersion: Schema.NullOr(Schema.Int.check(Schema.isGreaterThanOrEqualTo(18))),
76 androidApiLevel: Schema.optional(Schema.NullOr(Schema.Int)),
77 appVersion: Schema.NullOr(TrimmedNonEmptyString),
78 notifications: Schema.Struct({
79 enabled: Schema.Boolean,
80 notifyOnApproval: Schema.Boolean,
81 notifyOnInput: Schema.Boolean,
82 notifyOnCompletion: Schema.Boolean,
83 notifyOnFailure: Schema.Boolean,
84 }),
85 liveActivities: Schema.Struct({
86 enabled: Schema.Boolean,
87 }),
88 updatedAt: TrimmedNonEmptyString,
89 });
90 export type RelayClientDeviceRecord = typeof RelayClientDeviceRecord.Type;
91
92 export const RelayListDevicesResponse = Schema.Struct({
93 devices: Schema.Array(RelayClientDeviceRecord),
94 });
95 export type RelayListDevicesResponse = typeof RelayListDevicesResponse.Type;
96
97 // Installed clients decode v1 as iOS-only. Keep that response contract frozen.
98 export const RelayListDevicesResponseV1 = Schema.Struct({
99 devices: Schema.Array(
100 Schema.Struct({
101 ...RelayClientDeviceRecord.fields,
102 platform: Schema.Literal("ios"),
103 iosMajorVersion: Schema.Int.check(Schema.isGreaterThanOrEqualTo(18)),
104 }),
105 ),
106 });
107
108 export const RelayLiveActivityRegistrationRequest = Schema.Struct({
109 deviceId: TrimmedNonEmptyString,
110 activityPushToken: TrimmedNonEmptyString,
111 });
112 export type RelayLiveActivityRegistrationRequest = typeof RelayLiveActivityRegistrationRequest.Type;
113
114 export const RelayDeviceUnregistrationParams = Schema.Struct({
115 deviceId: TrimmedNonEmptyString,
116 });
117 export type RelayDeviceUnregistrationParams = typeof RelayDeviceUnregistrationParams.Type;
118
119 export const RelayAgentActivityState = Schema.Struct({
120 environmentId: EnvironmentId,
121 threadId: ThreadId,
122 projectTitle: TrimmedNonEmptyString,
123 threadTitle: TrimmedNonEmptyString,
124 phase: RelayAgentAwarenessPhase,
125 headline: TrimmedNonEmptyString,
126 detail: Schema.optional(TrimmedNonEmptyString),
127 modelTitle: TrimmedNonEmptyString,
128 updatedAt: TrimmedNonEmptyString,
129 deepLink: TrimmedNonEmptyString,
130 });
131 export type RelayAgentActivityState = typeof RelayAgentActivityState.Type;
132
133 export const RelayAgentActivityAggregateRow = Schema.Struct({
134 environmentId: EnvironmentId,
135 threadId: ThreadId,
136 projectTitle: TrimmedNonEmptyString,
137 threadTitle: TrimmedNonEmptyString,
138 modelTitle: TrimmedNonEmptyString,
139 phase: RelayAgentAwarenessPhase,
140 status: TrimmedNonEmptyString,
141 updatedAt: TrimmedNonEmptyString,
142 deepLink: TrimmedNonEmptyString,
143 });
144 export type RelayAgentActivityAggregateRow = typeof RelayAgentActivityAggregateRow.Type;
145
146 export const RelayAgentActivityAggregateState = Schema.Struct({
147 title: TrimmedNonEmptyString,
148 subtitle: TrimmedNonEmptyString,
149 activeCount: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
150 updatedAt: TrimmedNonEmptyString,
151 activities: Schema.Array(RelayAgentActivityAggregateRow),
152 });
153 export type RelayAgentActivityAggregateState = typeof RelayAgentActivityAggregateState.Type;
154
155 export const RelayManagedEndpointProviderKind = Schema.Literals([
156 "manual",
157 "cloudflare_tunnel",
158 "t3_relay",
159 ]);
160 export type RelayManagedEndpointProviderKind = typeof RelayManagedEndpointProviderKind.Type;
161
162 export const RelayManagedEndpoint = Schema.Struct({
163 httpBaseUrl: TrimmedNonEmptyString,
164 wsBaseUrl: TrimmedNonEmptyString,
165 providerKind: RelayManagedEndpointProviderKind,
166 });
167 export type RelayManagedEndpoint = typeof RelayManagedEndpoint.Type;
168
169 export const RelayManagedEndpointOrigin = Schema.Struct({
170 localHttpHost: TrimmedNonEmptyString,
171 localHttpPort: Schema.Int.check(
172 Schema.isGreaterThanOrEqualTo(1),
173 Schema.isLessThanOrEqualTo(65_535),
174 ),
175 });
176 export type RelayManagedEndpointOrigin = typeof RelayManagedEndpointOrigin.Type;
177
178 export const RelayManagedEndpointRuntimeConfig = Schema.Struct({
179 providerKind: RelayManagedEndpointProviderKind,
180 connectorToken: TrimmedNonEmptyString,
181 tunnelId: Schema.optional(TrimmedNonEmptyString),
182 tunnelName: Schema.optional(TrimmedNonEmptyString),
183 });
184 export type RelayManagedEndpointRuntimeConfig = typeof RelayManagedEndpointRuntimeConfig.Type;
185
186 export const RelayManagedEndpointRecoveryRequest = Schema.Struct({
187 cloudUserId: TrimmedNonEmptyString,
188 origin: RelayManagedEndpointOrigin,
189 proof: TrimmedNonEmptyString,
190 });
191 export type RelayManagedEndpointRecoveryRequest = typeof RelayManagedEndpointRecoveryRequest.Type;
192
193 export const RelayManagedEndpointRecoveryRegistrationRequest = Schema.Struct({
194 cloudUserId: TrimmedNonEmptyString,
195 tunnelId: TrimmedNonEmptyString,
196 origin: RelayManagedEndpointOrigin,
197 proof: TrimmedNonEmptyString,
198 });
199 export type RelayManagedEndpointRecoveryRegistrationRequest =
200 typeof RelayManagedEndpointRecoveryRegistrationRequest.Type;
201
202 export const RelayManagedEndpointRecoveryRegistrationResponse = Schema.Struct({
203 status: Schema.Literals(["ready", "recovery_required"]),
204 });
205 export type RelayManagedEndpointRecoveryRegistrationResponse =
206 typeof RelayManagedEndpointRecoveryRegistrationResponse.Type;
207
208 export const RelayManagedEndpointRecoveryResponse = Schema.Struct({
209 endpoint: RelayManagedEndpoint,
210 endpointRuntime: RelayManagedEndpointRuntimeConfig,
211 });
212 export type RelayManagedEndpointRecoveryResponse = typeof RelayManagedEndpointRecoveryResponse.Type;
213
214 export const RelayLinkProofRequest = Schema.Struct({
215 challenge: Schema.String,
216 relayIssuer: Schema.String,
217 endpoint: RelayManagedEndpoint,
218 origin: RelayManagedEndpointOrigin,
219 });
220 export type RelayLinkProofRequest = typeof RelayLinkProofRequest.Type;
221
222 export const RelayEnvironmentConfigRequest = Schema.Struct({
223 relayUrl: Schema.String,
224 relayIssuer: Schema.optional(Schema.String),
225 cloudUserId: Schema.String,
226 environmentCredential: Schema.String,
227 cloudMintPublicKey: Schema.String,
228 endpointRuntime: Schema.NullOr(RelayManagedEndpointRuntimeConfig),
229 });
230 export type RelayEnvironmentConfigRequest = typeof RelayEnvironmentConfigRequest.Type;
231
232 const RelaySignedJwtRegisteredClaims = {
233 iss: TrimmedNonEmptyString,
234 aud: TrimmedNonEmptyString,
235 sub: TrimmedNonEmptyString,
236 jti: TrimmedNonEmptyString,
237 iat: Schema.Int,
238 exp: Schema.Int,
239 } as const;
240
241 export const RelayManagedEndpointRecoveryProofPayload = Schema.Union([
242 Schema.Struct({
243 ...RelaySignedJwtRegisteredClaims,
244 action: Schema.Literal("register"),
245 environmentId: EnvironmentId,
246 cloudUserId: TrimmedNonEmptyString,
247 tunnelId: TrimmedNonEmptyString,
248 origin: RelayManagedEndpointOrigin,
249 }),
250 Schema.Struct({
251 ...RelaySignedJwtRegisteredClaims,
252 action: Schema.Literal("recover"),
253 environmentId: EnvironmentId,
254 cloudUserId: TrimmedNonEmptyString,
255 origin: RelayManagedEndpointOrigin,
256 }),
257 ]);
258 export type RelayManagedEndpointRecoveryProofPayload =
259 typeof RelayManagedEndpointRecoveryProofPayload.Type;
260
261 export const RelayAgentActivityPublishProofPayload = Schema.Struct({
262 ...RelaySignedJwtRegisteredClaims,
263 environmentId: EnvironmentId,
264 threadId: ThreadId,
265 state: Schema.NullOr(RelayAgentActivityState),
266 });
267 export type RelayAgentActivityPublishProofPayload =
268 typeof RelayAgentActivityPublishProofPayload.Type;
269
270 export const RelayAgentActivityPublishRequest = Schema.Struct({
271 state: Schema.NullOr(RelayAgentActivityState).annotate({
272 description: "Current agent-awareness state, or null to remove the published state.",
273 }),
274 proof: TrimmedNonEmptyString.annotate({
275 description: "Environment-signed JWT covering this published activity state.",
276 }),
277 }).annotate({ description: "Publishes a signed agent-awareness update from an environment." });
278 export type RelayAgentActivityPublishRequest = typeof RelayAgentActivityPublishRequest.Type;
279
280 export const RelayEnvironmentLinkScope = Schema.Literals([
281 "agent_activity_notifications",
282 "managed_tunnels",
283 ]);
284 export type RelayEnvironmentLinkScope = typeof RelayEnvironmentLinkScope.Type;
285
286 export const RelayEnvironmentLinkProofPayload = Schema.Struct({
287 ...RelaySignedJwtRegisteredClaims,
288 challenge: TrimmedNonEmptyString,
289 descriptor: ExecutionEnvironmentDescriptor,
290 environmentId: EnvironmentId,
291 environmentPublicKey: TrimmedNonEmptyString,
292 endpoint: RelayManagedEndpoint,
293 origin: RelayManagedEndpointOrigin,
294 scopes: Schema.Array(RelayEnvironmentLinkScope),
295 });
296 export type RelayEnvironmentLinkProofPayload = typeof RelayEnvironmentLinkProofPayload.Type;
297
298 export const RelayEnvironmentLinkProof = TrimmedNonEmptyString;
299 export type RelayEnvironmentLinkProof = typeof RelayEnvironmentLinkProof.Type;
300
301 export const RelayEnvironmentLinkChallengeRequest = Schema.Struct({
302 notificationsEnabled: Schema.Boolean.annotate({
303 description: "Whether this link may deliver push notifications.",
304 }),
305 liveActivitiesEnabled: Schema.Boolean.annotate({
306 description: "Whether this link may update Live Activities.",
307 }),
308 managedTunnelsEnabled: Schema.Boolean.annotate({
309 description: "Whether the relay should provision a managed tunnel for this environment.",
310 }),
311 }).annotate({ description: "Requested capabilities for a new environment-link challenge." });
312 export type RelayEnvironmentLinkChallengeRequest = typeof RelayEnvironmentLinkChallengeRequest.Type;
313
314 export const RelayEnvironmentLinkChallengeResponse = Schema.Struct({
315 challenge: TrimmedNonEmptyString,
316 expiresAt: TrimmedNonEmptyString,
317 });
318 export type RelayEnvironmentLinkChallengeResponse =
319 typeof RelayEnvironmentLinkChallengeResponse.Type;
320
321 export const RelayEnvironmentLinkRequest = Schema.Struct({
322 deviceId: Schema.optional(
323 TrimmedNonEmptyString.annotate({
324 description: "Optional client device identifier associated with this link.",
325 }),
326 ),
327 proof: RelayEnvironmentLinkProof.annotate({
328 description: "Environment-signed proof bound to a previously issued link challenge.",
329 }),
330 notificationsEnabled: Schema.Boolean,
331 liveActivitiesEnabled: Schema.Boolean,
332 managedTunnelsEnabled: Schema.Boolean,
333 }).annotate({ description: "Links an authenticated cloud user to a T3 environment." });
334 export type RelayEnvironmentLinkRequest = typeof RelayEnvironmentLinkRequest.Type;
335
336 export const RelayEnvironmentLinkResponse = Schema.Struct({
337 ok: Schema.Boolean,
338 cloudUserId: TrimmedNonEmptyString,
339 environmentId: EnvironmentId,
340 endpoint: RelayManagedEndpoint,
341 endpointRuntime: Schema.NullOr(RelayManagedEndpointRuntimeConfig),
342 relayIssuer: TrimmedNonEmptyString,
343 environmentCredential: TrimmedNonEmptyString,
344 cloudMintPublicKey: TrimmedNonEmptyString,
345 });
346 export type RelayEnvironmentLinkResponse = typeof RelayEnvironmentLinkResponse.Type;
347
348 export const RelayEnvironmentLinkProofInvalidReason = Schema.Literals([
349 "invalid_signature_or_scope",
350 "descriptor_mismatch",
351 "replayed_nonce",
352 "challenge_invalid",
353 "origin_not_allowed",
354 "endpoint_not_secure",
355 "environment_key_mismatch",
356 ]);
357 export type RelayEnvironmentLinkProofInvalidReason =
358 typeof RelayEnvironmentLinkProofInvalidReason.Type;
359
360 export const RelayEnvironmentLinkFailedReason = Schema.Literals([
361 "link_persistence_failed",
362 "credential_persistence_failed",
363 "replay_persistence_failed",
364 "internal_error",
365 ]);
366 export type RelayEnvironmentLinkFailedReason = typeof RelayEnvironmentLinkFailedReason.Type;
367
368 export const RelayEnvironmentLinkUnavailableReason = Schema.Literals([
369 "managed_endpoint_not_configured",
370 "managed_endpoint_provisioning_failed",
371 ]);
372 export type RelayEnvironmentLinkUnavailableReason =
373 typeof RelayEnvironmentLinkUnavailableReason.Type;
374
375 export const RelayEnvironmentEndpointUnavailableReason = Schema.Literals([
376 "endpoint_request_failed",
377 "endpoint_response_invalid",
378 ]);
379 export type RelayEnvironmentEndpointUnavailableReason =
380 typeof RelayEnvironmentEndpointUnavailableReason.Type;
381
382 /**
383 * Which part of the path from the relay to the environment failed. `tunnel_down`
384 * means Cloudflare has no live connector for the tunnel; `origin_unreachable`
385 * means the tunnel answered but T3 Code behind it did not. Optional on the wire
386 * so old relays and old clients keep working.
387 */
388 export const RelayEnvironmentEndpointFailure = Schema.Literals([
389 "tunnel_down",
390 "origin_unreachable",
391 "dns",
392 "tls",
393 "refused",
394 "timeout",
395 "invalid_response",
396 "unknown",
397 ]);
398 export type RelayEnvironmentEndpointFailure = typeof RelayEnvironmentEndpointFailure.Type;
399
400 export const RelayAgentActivityPublishProofInvalidReason = Schema.Literals([
401 "invalid_signature_or_payload",
402 "replayed_nonce",
403 ]);
404 export type RelayAgentActivityPublishProofInvalidReason =
405 typeof RelayAgentActivityPublishProofInvalidReason.Type;
406
407 export const RelayAuthInvalidReason = Schema.Literals([
408 "missing_bearer",
409 "invalid_bearer",
410 "invalid_dpop",
411 "not_authorized",
412 ]);
413 export type RelayAuthInvalidReason = typeof RelayAuthInvalidReason.Type;
414
415 export const RelayDpopFailureReason = DpopFailureReason;
416 export type RelayDpopFailureReason = typeof RelayDpopFailureReason.Type;
417
418 export const RelayInternalErrorReason = Schema.Literals([
419 "database_unavailable",
420 "persistence_failed",
421 "upstream_unavailable",
422 "internal_error",
423 ]);
424 export type RelayInternalErrorReason = typeof RelayInternalErrorReason.Type;
425
426 export class RelayAuthInvalidError extends Schema.TaggedError<RelayAuthInvalidError>()(
427 "RelayAuthInvalidError",
428 {
429 code: Schema.Literal("auth_invalid"),
430 reason: RelayAuthInvalidReason,
431 dpopFailureReason: Schema.optionalKey(RelayDpopFailureReason),
432 traceId: TrimmedNonEmptyString,
433 },
434 { httpApiStatus: 401 },
435 ) {
436 override get message(): string {
437 return `Relay authentication failed: ${this.reason}`;
438 }
439 }
440
441 export class RelayEnvironmentLinkProofExpiredError extends Schema.TaggedError<RelayEnvironmentLinkProofExpiredError>()(
442 "RelayEnvironmentLinkProofExpiredError",
443 {
444 code: Schema.Literal("environment_link_proof_expired"),
445 traceId: TrimmedNonEmptyString,
446 },
447 { httpApiStatus: 401 },
448 ) {
449 override get message(): string {
450 return "Relay environment link proof expired";
451 }
452 }
453
454 export class RelayEnvironmentLinkProofInvalidError extends Schema.TaggedError<RelayEnvironmentLinkProofInvalidError>()(
455 "RelayEnvironmentLinkProofInvalidError",
456 {
457 code: Schema.Literal("environment_link_proof_invalid"),
458 reason: RelayEnvironmentLinkProofInvalidReason,
459 traceId: TrimmedNonEmptyString,
460 },
461 { httpApiStatus: 400 },
462 ) {
463 override get message(): string {
464 return `Relay environment link proof is invalid: ${this.reason}`;
465 }
466 }
467
468 export const RelayEnvironmentConnectNotAuthorizedReason = Schema.Literals([
469 "client_proof_key_thumbprint_missing",
470 "environment_link_not_found",
471 "endpoint_provider_not_managed",
472 "managed_endpoint_allocation_not_found",
473 "managed_endpoint_base_domain_not_configured",
474 "managed_endpoint_allocation_not_ready",
475 "managed_endpoint_hostname_invalid",
476 "managed_endpoint_mismatch",
477 ]);
478 export type RelayEnvironmentConnectNotAuthorizedReason =
479 typeof RelayEnvironmentConnectNotAuthorizedReason.Type;
480
481 export class RelayEnvironmentConnectNotAuthorizedError extends Schema.TaggedError<RelayEnvironmentConnectNotAuthorizedError>()(
482 "RelayEnvironmentConnectNotAuthorizedError",
483 {
484 code: Schema.Literal("environment_connect_not_authorized"),
485 reason: Schema.optional(RelayEnvironmentConnectNotAuthorizedReason),
486 traceId: TrimmedNonEmptyString,
487 },
488 { httpApiStatus: 403 },
489 ) {
490 override get message(): string {
491 return this.reason
492 ? `Relay environment connection is not authorized: ${this.reason}`
493 : "Relay environment connection is not authorized";
494 }
495 }
496
497 export class RelayEnvironmentEndpointUnavailableError extends Schema.TaggedError<RelayEnvironmentEndpointUnavailableError>()(
498 "RelayEnvironmentEndpointUnavailableError",
499 {
500 code: Schema.Literal("environment_endpoint_unavailable"),
501 reason: RelayEnvironmentEndpointUnavailableReason,
502 endpointFailure: Schema.optionalKey(RelayEnvironmentEndpointFailure),
503 endpointStatus: Schema.optionalKey(Schema.Number),
504 traceId: TrimmedNonEmptyString,
505 },
506 { httpApiStatus: 502 },
507 ) {
508 override get message(): string {
509 return `Relay environment endpoint is unavailable: ${this.reason}`;
510 }
511 }
512
513 export class RelayEnvironmentEndpointTimedOutError extends Schema.TaggedError<RelayEnvironmentEndpointTimedOutError>()(
514 "RelayEnvironmentEndpointTimedOutError",
515 {
516 code: Schema.Literal("environment_endpoint_timed_out"),
517 traceId: TrimmedNonEmptyString,
518 },
519 { httpApiStatus: 504 },
520 ) {
521 override get message(): string {
522 return "Relay environment endpoint request timed out";
523 }
524 }
525
526 export class RelayEnvironmentLinkFailedError extends Schema.TaggedError<RelayEnvironmentLinkFailedError>()(
527 "RelayEnvironmentLinkFailedError",
528 {
529 code: Schema.Literal("environment_link_failed"),
530 reason: RelayEnvironmentLinkFailedReason,
531 traceId: TrimmedNonEmptyString,
532 },
533 { httpApiStatus: 500 },
534 ) {
535 override get message(): string {
536 return `Relay environment link failed: ${this.reason}`;
537 }
538 }
539
540 export class RelayEnvironmentLinkUnavailableError extends Schema.TaggedError<RelayEnvironmentLinkUnavailableError>()(
541 "RelayEnvironmentLinkUnavailableError",
542 {
543 code: Schema.Literal("environment_link_unavailable"),
544 reason: RelayEnvironmentLinkUnavailableReason,
545 provisioningStage: Schema.optionalKey(TrimmedNonEmptyString),
546 traceId: TrimmedNonEmptyString,
547 },
548 { httpApiStatus: 503 },
549 ) {
550 override get message(): string {
551 return `Relay environment link is unavailable: ${this.reason}`;
552 }
553 }
554
555 export class RelayEnvironmentLinkLimitExceededError extends Schema.TaggedError<RelayEnvironmentLinkLimitExceededError>()(
556 "RelayEnvironmentLinkLimitExceededError",
557 {
558 code: Schema.Literal("environment_link_limit_exceeded"),
559 maxTunnels: Schema.Number,
560 traceId: TrimmedNonEmptyString,
561 },
562 { httpApiStatus: 403 },
563 ) {
564 override get message(): string {
565 return `Relay managed tunnel limit reached: this account allows at most ${this.maxTunnels} tunnels`;
566 }
567 }
568
569 export class RelayAgentActivityPublishProofExpiredError extends Schema.TaggedError<RelayAgentActivityPublishProofExpiredError>()(
570 "RelayAgentActivityPublishProofExpiredError",
571 {
572 code: Schema.Literal("agent_activity_publish_proof_expired"),
573 traceId: TrimmedNonEmptyString,
574 },
575 { httpApiStatus: 401 },
576 ) {
577 override get message(): string {
578 return "Relay agent activity publish proof expired";
579 }
580 }
581
582 export class RelayAgentActivityPublishProofInvalidError extends Schema.TaggedError<RelayAgentActivityPublishProofInvalidError>()(
583 "RelayAgentActivityPublishProofInvalidError",
584 {
585 code: Schema.Literal("agent_activity_publish_proof_invalid"),
586 reason: RelayAgentActivityPublishProofInvalidReason,
587 traceId: TrimmedNonEmptyString,
588 },
589 { httpApiStatus: 401 },
590 ) {
591 override get message(): string {
592 return `Relay agent activity publish proof is invalid: ${this.reason}`;
593 }
594 }
595
596 export class RelayInternalError extends Schema.TaggedError<RelayInternalError>()(
597 "RelayInternalError",
598 {
599 code: Schema.Literal("internal_error"),
600 reason: RelayInternalErrorReason,
601 traceId: TrimmedNonEmptyString,
602 },
603 { httpApiStatus: 500 },
604 ) {
605 override get message(): string {
606 return `Relay internal error: ${this.reason}`;
607 }
608 }
609
610 export const RelayProtectedError = Schema.Union([
611 RelayAuthInvalidError,
612 RelayEnvironmentLinkProofExpiredError,
613 RelayEnvironmentLinkProofInvalidError,
614 RelayEnvironmentConnectNotAuthorizedError,
615 RelayEnvironmentEndpointUnavailableError,
616 RelayEnvironmentEndpointTimedOutError,
617 RelayEnvironmentLinkFailedError,
618 RelayEnvironmentLinkUnavailableError,
619 RelayEnvironmentLinkLimitExceededError,
620 RelayAgentActivityPublishProofExpiredError,
621 RelayAgentActivityPublishProofInvalidError,
622 RelayInternalError,
623 ]);
624 export type RelayProtectedError = typeof RelayProtectedError.Type;
625
626 const RelayAuthAndInternalErrors = [RelayAuthInvalidError, RelayInternalError] as const;
627
628 const RelayEnvironmentLinkErrors = [
629 RelayAuthInvalidError,
630 RelayEnvironmentLinkProofExpiredError,
631 RelayEnvironmentLinkProofInvalidError,
632 RelayEnvironmentLinkUnavailableError,
633 RelayEnvironmentLinkLimitExceededError,
634 RelayEnvironmentLinkFailedError,
635 RelayInternalError,
636 ] as const;
637
638 const RelayEnvironmentConnectErrors = [
639 RelayAuthInvalidError,
640 RelayEnvironmentConnectNotAuthorizedError,
641 RelayEnvironmentEndpointUnavailableError,
642 RelayEnvironmentEndpointTimedOutError,
643 RelayInternalError,
644 ] as const;
645
646 const RelayAgentActivityPublishErrors = [
647 RelayAuthInvalidError,
648 RelayAgentActivityPublishProofExpiredError,
649 RelayAgentActivityPublishProofInvalidError,
650 RelayInternalError,
651 ] as const;
652
653 export class RelayClientPrincipal extends Context.Service<
654 RelayClientPrincipal,
655 {
656 readonly userId: string;
657 readonly token: string;
658 readonly proofKeyThumbprint?: string;
659 readonly dpopScopes?: ReadonlyArray<RelayDpopAccessTokenScope>;
660 }
661 >()("@t3tools/contracts/relay/RelayClientPrincipal") {}
662
663 export class RelayEnvironmentPrincipal extends Context.Service<
664 RelayEnvironmentPrincipal,
665 {
666 readonly environmentId: string;
667 readonly environmentPublicKey: string;
668 }
669 >()("@t3tools/contracts/relay/RelayEnvironmentPrincipal") {}
670
671 const RelayClientBearerAuthorization = HttpApiSecurity.http({ scheme: "bearer" }).pipe(
672 HttpApiSecurity.annotate(
673 OpenApi.Description,
674 "Clerk session or OAuth bearer token for the signed-in T3 Connect user.",
675 ),
676 );
677
678 export class RelayClientAuth extends HttpApiMiddleware.Service<
679 RelayClientAuth,
680 { provides: RelayClientPrincipal }
681 >()("RelayClientAuth", {
682 error: RelayAuthInvalidError,
683 security: { clientBearer: RelayClientBearerAuthorization },
684 }) {}
685
686 const RelayEnvironmentBearerAuthorization = HttpApiSecurity.http({ scheme: "bearer" }).pipe(
687 HttpApiSecurity.annotate(
688 OpenApi.Description,
689 "Relay-issued environment credential installed when the environment is linked.",
690 ),
691 );
692
693 export class RelayEnvironmentAuth extends HttpApiMiddleware.Service<
694 RelayEnvironmentAuth,
695 { provides: RelayEnvironmentPrincipal }
696 >()("RelayEnvironmentAuth", {
697 error: [RelayAuthInvalidError, RelayInternalError],
698 security: { environmentBearer: RelayEnvironmentBearerAuthorization },
699 }) {}
700
701 const RelayDpopAuthorization = HttpApiSecurity.http({ scheme: "DPoP" }).pipe(
702 HttpApiSecurity.annotate(
703 OpenApi.Description,
704 "DPoP-bound access token. Requests must also include the DPoP proof JWT header.",
705 ),
706 );
707
708 export class RelayDpopClientAuth extends HttpApiMiddleware.Service<
709 RelayDpopClientAuth,
710 { provides: RelayClientPrincipal }
711 >()("RelayDpopClientAuth", {
712 error: RelayAuthInvalidError,
713 security: { relayDpop: RelayDpopAuthorization },
714 }) {}
715
716 export const RelayClientEnvironmentRecord = Schema.Struct({
717 environmentId: EnvironmentId,
718 label: TrimmedNonEmptyString,
719 endpoint: RelayManagedEndpoint,
720 linkedAt: TrimmedNonEmptyString,
721 });
722 export type RelayClientEnvironmentRecord = typeof RelayClientEnvironmentRecord.Type;
723
724 export const RelayListEnvironmentsResponse = Schema.Struct({
725 environments: Schema.Array(RelayClientEnvironmentRecord),
726 });
727 export type RelayListEnvironmentsResponse = typeof RelayListEnvironmentsResponse.Type;
728
729 export const RelayEnvironmentConnectRequest = Schema.Struct({
730 deviceId: Schema.optional(
731 TrimmedNonEmptyString.annotate({
732 description: "Optional client device identifier requesting the connection.",
733 }),
734 ),
735 clientKeyThumbprint: Schema.optional(
736 TrimmedNonEmptyString.annotate({
737 description: "Deprecated alias for clientProofKeyThumbprint.",
738 }),
739 ),
740 clientProofKeyThumbprint: Schema.optional(
741 TrimmedNonEmptyString.annotate({
742 description: "JWK thumbprint that the minted environment credential must be bound to.",
743 }),
744 ),
745 }).annotate({ description: "Requests a short-lived credential for connecting to an environment." });
746 export type RelayEnvironmentConnectRequest = typeof RelayEnvironmentConnectRequest.Type;
747
748 export const RelayEnvironmentConnectScope = "environment:connect" as const;
749 export const RelayEnvironmentStatusScope = "environment:status" as const;
750 export const RelayMobileRegistrationScope = "mobile:registration" as const;
751 export const RelayDpopAccessTokenScope = Schema.Literals([
752 RelayEnvironmentConnectScope,
753 RelayEnvironmentStatusScope,
754 RelayMobileRegistrationScope,
755 ]);
756 export type RelayDpopAccessTokenScope = typeof RelayDpopAccessTokenScope.Type;
757
758 export const RelayDpopTokenExchangeGrantType =
759 "urn:ietf:params:oauth:grant-type:token-exchange" as const;
760 export const RelayJwtSubjectTokenType = "urn:ietf:params:oauth:token-type:jwt" as const;
761 export const RelayAccessTokenType = "urn:ietf:params:oauth:token-type:access_token" as const;
762 export const RelayPublicClientId = Schema.Literals(["t3-mobile", "t3-web"]);
763 export type RelayPublicClientId = typeof RelayPublicClientId.Type;
764 export const RelayMobileClientId = "t3-mobile" as const;
765 export const RelayWebClientId = "t3-web" as const;
766
767 export const RelayDpopAccessTokenRequest = Schema.Struct({
768 grant_type: Schema.Literal(RelayDpopTokenExchangeGrantType),
769 subject_token: TrimmedNonEmptyString.annotate({
770 description: "Clerk bearer token for the signed-in cloud user.",
771 }),
772 subject_token_type: Schema.Literal(RelayJwtSubjectTokenType),
773 requested_token_type: Schema.Literal(RelayAccessTokenType),
774 resource: TrimmedNonEmptyString.annotate({
775 description: "Relay issuer URL that will receive the DPoP-bound access token.",
776 }),
777 scope: TrimmedNonEmptyString.annotate({
778 description: "Space-separated relay scopes requested by the client.",
779 }),
780 client_id: RelayPublicClientId,
781 })
782 .annotate({ description: "OAuth token exchange request for a DPoP-bound relay access token." })
783 .pipe(HttpApiSchema.asFormUrlEncoded());
784 export type RelayDpopAccessTokenRequest = typeof RelayDpopAccessTokenRequest.Type;
785
786 export const RelayDpopAccessTokenResponse = Schema.Struct({
787 access_token: TrimmedNonEmptyString,
788 issued_token_type: Schema.Literal(RelayAccessTokenType),
789 token_type: Schema.Literal("DPoP"),
790 expires_in: Schema.Int.check(Schema.isGreaterThan(0)),
791 scope: TrimmedNonEmptyString,
792 });
793 export type RelayDpopAccessTokenResponse = typeof RelayDpopAccessTokenResponse.Type;
794
795 export const RelayBearerRequestHeaders = Schema.Struct({
796 authorization: TrimmedNonEmptyString,
797 });
798
799 export const RelayDpopProofRequestHeaders = Schema.Struct({
800 dpop: TrimmedNonEmptyString,
801 });
802
803 export const RelayDpopRequestHeaders = Schema.Struct({
804 authorization: TrimmedNonEmptyString,
805 dpop: TrimmedNonEmptyString,
806 });
807
808 export const RelayAuthorizationServerMetadata = Schema.Struct({
809 issuer: TrimmedNonEmptyString,
810 token_endpoint: TrimmedNonEmptyString,
811 grant_types_supported: Schema.Array(Schema.Literal(RelayDpopTokenExchangeGrantType)),
812 token_endpoint_auth_methods_supported: Schema.Array(Schema.Literal("none")),
813 dpop_signing_alg_values_supported: Schema.Array(Schema.Literal("ES256")),
814 scopes_supported: Schema.Array(RelayDpopAccessTokenScope),
815 });
816
817 export const RelayProtectedResourceMetadata = Schema.Struct({
818 resource: TrimmedNonEmptyString,
819 authorization_servers: Schema.Array(TrimmedNonEmptyString),
820 scopes_supported: Schema.Array(RelayDpopAccessTokenScope),
821 dpop_bound_access_tokens_required: Schema.Boolean,
822 dpop_signing_alg_values_supported: Schema.Array(Schema.Literal("ES256")),
823 });
824
825 export const RelayEnvironmentUnlinkParams = Schema.Struct({
826 environmentId: EnvironmentId,
827 });
828 export type RelayEnvironmentUnlinkParams = typeof RelayEnvironmentUnlinkParams.Type;
829
830 export const RelayEnvironmentConnectResponse = Schema.Struct({
831 environmentId: EnvironmentId,
832 endpoint: RelayManagedEndpoint,
833 credential: TrimmedNonEmptyString,
834 expiresAt: TrimmedNonEmptyString,
835 });
836 export type RelayEnvironmentConnectResponse = typeof RelayEnvironmentConnectResponse.Type;
837
838 export const RelayEnvironmentStatusValue = Schema.Literals(["online", "offline"]);
839 export type RelayEnvironmentStatusValue = typeof RelayEnvironmentStatusValue.Type;
840
841 const RelayEnvironmentOfflineReason = Schema.Literals(["tunnel_released"]);
842 type RelayEnvironmentOfflineReason = typeof RelayEnvironmentOfflineReason.Type;
843
844 export const RelayEnvironmentStatusResponse = Schema.Struct({
845 environmentId: EnvironmentId,
846 endpoint: RelayManagedEndpoint,
847 status: RelayEnvironmentStatusValue,
848 checkedAt: TrimmedNonEmptyString,
849 descriptor: Schema.optional(ExecutionEnvironmentDescriptor),
850 error: Schema.optional(TrimmedNonEmptyString),
851 endpointFailure: Schema.optional(RelayEnvironmentEndpointFailure),
852 endpointStatus: Schema.optional(Schema.Number),
853 offlineReason: Schema.optional(RelayEnvironmentOfflineReason),
854 traceId: Schema.optional(TrimmedNonEmptyString),
855 });
856 export type RelayEnvironmentStatusResponse = typeof RelayEnvironmentStatusResponse.Type;
857
858 export const RelayCloudMintCredentialProofPayload = Schema.Struct({
859 ...RelaySignedJwtRegisteredClaims,
860 environmentId: EnvironmentId,
861 clientProofKeyThumbprint: TrimmedNonEmptyString,
862 cnf: Schema.Struct({
863 jkt: TrimmedNonEmptyString,
864 }),
865 deviceId: Schema.optional(TrimmedNonEmptyString),
866 nonce: TrimmedNonEmptyString,
867 scope: Schema.Array(Schema.Literal("environment:connect")),
868 });
869 export type RelayCloudMintCredentialProofPayload = typeof RelayCloudMintCredentialProofPayload.Type;
870
871 export const RelayCloudMintCredentialProof = TrimmedNonEmptyString;
872 export type RelayCloudMintCredentialProof = typeof RelayCloudMintCredentialProof.Type;
873
874 export const RelayCloudMintCredentialRequest = Schema.Struct({
875 proof: RelayCloudMintCredentialProof,
876 });
877 export type RelayCloudMintCredentialRequest = typeof RelayCloudMintCredentialRequest.Type;
878
879 export const RelayCloudEnvironmentHealthProofPayload = Schema.Struct({
880 ...RelaySignedJwtRegisteredClaims,
881 environmentId: EnvironmentId,
882 nonce: TrimmedNonEmptyString,
883 scope: Schema.Array(Schema.Literal("environment:status")),
884 });
885 export type RelayCloudEnvironmentHealthProofPayload =
886 typeof RelayCloudEnvironmentHealthProofPayload.Type;
887
888 /** Verify x-t3-relay-delivery with the relay mint key before trusting delivery id, time, or trace context. */
889 export const RelayHookDeliveryProofPayload = Schema.Struct({
890 ...RelaySignedJwtRegisteredClaims,
891 environmentId: EnvironmentId,
892 deliveryId: TrimmedNonEmptyString,
893 receivedAt: TrimmedNonEmptyString,
894 hookId: TrimmedNonEmptyString,
895 });
896 export type RelayHookDeliveryProofPayload = typeof RelayHookDeliveryProofPayload.Type;
897
898 export const RelayCloudEnvironmentHealthProof = TrimmedNonEmptyString;
899 export type RelayCloudEnvironmentHealthProof = typeof RelayCloudEnvironmentHealthProof.Type;
900
901 export const RelayCloudEnvironmentHealthRequest = Schema.Struct({
902 proof: RelayCloudEnvironmentHealthProof,
903 });
904 export type RelayCloudEnvironmentHealthRequest = typeof RelayCloudEnvironmentHealthRequest.Type;
905
906 export const RelayEnvironmentHealthResponseProofPayload = Schema.Struct({
907 ...RelaySignedJwtRegisteredClaims,
908 environmentId: EnvironmentId,
909 requestNonce: TrimmedNonEmptyString,
910 status: Schema.Literal("online"),
911 descriptor: ExecutionEnvironmentDescriptor,
912 checkedAt: TrimmedNonEmptyString,
913 });
914 export type RelayEnvironmentHealthResponseProofPayload =
915 typeof RelayEnvironmentHealthResponseProofPayload.Type;
916
917 export const RelayEnvironmentHealthResponse = Schema.Struct({
918 environmentId: EnvironmentId,
919 status: Schema.Literal("online"),
920 descriptor: ExecutionEnvironmentDescriptor,
921 checkedAt: TrimmedNonEmptyString,
922 proof: TrimmedNonEmptyString,
923 });
924 export type RelayEnvironmentHealthResponse = typeof RelayEnvironmentHealthResponse.Type;
925
926 export const RelayEnvironmentMintResponseProofPayload = Schema.Struct({
927 ...RelaySignedJwtRegisteredClaims,
928 environmentId: EnvironmentId,
929 clientProofKeyThumbprint: TrimmedNonEmptyString,
930 requestNonce: TrimmedNonEmptyString,
931 credential: TrimmedNonEmptyString,
932 });
933 export type RelayEnvironmentMintResponseProofPayload =
934 typeof RelayEnvironmentMintResponseProofPayload.Type;
935
936 export const RelayEnvironmentMintResponse = Schema.Struct({
937 credential: TrimmedNonEmptyString,
938 expiresAt: TrimmedNonEmptyString,
939 proof: TrimmedNonEmptyString,
940 });
941 export type RelayEnvironmentMintResponse = typeof RelayEnvironmentMintResponse.Type;
942
943 export const RelayDeliveryKind = Schema.Literals([
944 "live_activity_start",
945 "live_activity_update",
946 "live_activity_end",
947 "push_notification",
948 ]);
949 export type RelayDeliveryKind = typeof RelayDeliveryKind.Type;
950
951 export const RelayDeliveryResult = Schema.Struct({
952 deviceId: TrimmedNonEmptyString,
953 kind: RelayDeliveryKind,
954 ok: Schema.Boolean,
955 queued: Schema.optional(Schema.Boolean),
956 apnsStatus: Schema.NullOr(Schema.Number),
957 apnsReason: Schema.NullOr(Schema.String),
958 apnsId: Schema.NullOr(Schema.String),
959 });
960 export type RelayDeliveryResult = typeof RelayDeliveryResult.Type;
961
962 export const RelayOkResponse = Schema.Struct({
963 ok: Schema.Boolean,
964 });
965 export type RelayOkResponse = typeof RelayOkResponse.Type;
966
967 export const RelayT3ChatPlan = Schema.Literals(["free", "pro", "premier"]);
968 export type RelayT3ChatPlan = typeof RelayT3ChatPlan.Type;
969
970 export const DEFAULT_MANAGED_TUNNEL_LIMIT = 3;
971
972 // A linked paid T3 Chat plan raises the default managed tunnel cap.
973 export const T3CHAT_PLAN_TUNNEL_LIMITS = { pro: 10, premier: 100 } as const;
974
975 export const RelayT3ChatLink = Schema.Struct({
976 email: Schema.String,
977 plan: RelayT3ChatPlan,
978 });
979 export type RelayT3ChatLink = typeof RelayT3ChatLink.Type;
980
981 export const RelayT3ChatLinkResponse = Schema.Struct({
982 // False when this relay has no T3 Chat secret, so clients hide the feature.
983 available: Schema.Boolean,
984 link: Schema.NullOr(RelayT3ChatLink),
985 // A manual cap that replaces the plan's; T3 Chat upgrades do not raise it.
986 maxTunnelsOverride: Schema.optionalKey(Schema.Number),
987 });
988 export type RelayT3ChatLinkResponse = typeof RelayT3ChatLinkResponse.Type;
989
990 export const RelayT3ChatLinkRequestResponse = Schema.Struct({
991 url: TrimmedNonEmptyString,
992 });
993 export type RelayT3ChatLinkRequestResponse = typeof RelayT3ChatLinkRequestResponse.Type;
994
995 export const RelayPublishResponse = Schema.Struct({
996 ok: Schema.Boolean,
997 deliveries: Schema.Array(RelayDeliveryResult),
998 });
999 export type RelayPublishResponse = typeof RelayPublishResponse.Type;
1000
1001 export const RelayHealthResponse = Schema.Struct({
1002 ok: Schema.Boolean,
1003 service: Schema.Literal("relay"),
1004 });
1005 export type RelayHealthResponse = typeof RelayHealthResponse.Type;
1006
1007 const RelayHealthGroup = HttpApiGroup.make("health")
1008 .add(
1009 HttpApiEndpoint.get("health", "/health", {
1010 success: RelayHealthResponse,
1011 error: RelayInternalError,
1012 }).annotate(OpenApi.Summary, "Check relay health"),
1013 )
1014 .annotate(OpenApi.Description, "Service health and readiness.");
1015
1016 const RelayMetadataGroup = HttpApiGroup.make("metadata")
1017 .add(
1018 HttpApiEndpoint.get("authorizationServer", "/.well-known/oauth-authorization-server", {
1019 success: RelayAuthorizationServerMetadata,
1020 }).annotate(OpenApi.Summary, "Read OAuth authorization-server metadata"),
1021 HttpApiEndpoint.get("protectedResource", "/.well-known/oauth-protected-resource", {
1022 success: RelayProtectedResourceMetadata,
1023 }).annotate(OpenApi.Summary, "Read OAuth protected-resource metadata"),
1024 )
1025 .annotate(OpenApi.Description, "OAuth and DPoP discovery metadata.");
1026
1027 export const RelayRegisterDeviceEndpoint = HttpApiEndpoint.post(
1028 "registerDevice",
1029 "/v1/mobile/devices",
1030 {
1031 headers: RelayDpopRequestHeaders,
1032 payload: RelayDeviceRegistrationRequest,
1033 success: RelayOkResponse,
1034 error: RelayAuthAndInternalErrors,
1035 },
1036 ).annotate(OpenApi.Summary, "Register or update a mobile device");
1037
1038 export const RelayRegisterLiveActivityEndpoint = HttpApiEndpoint.post(
1039 "registerLiveActivity",
1040 "/v1/mobile/live-activities",
1041 {
1042 headers: RelayDpopRequestHeaders,
1043 payload: RelayLiveActivityRegistrationRequest,
1044 success: RelayOkResponse,
1045 error: RelayAuthAndInternalErrors,
1046 },
1047 ).annotate(OpenApi.Summary, "Register a Live Activity push token");
1048
1049 export const RelayAgentActivitySnapshotResponse = Schema.Struct({
1050 aggregate: Schema.NullOr(RelayAgentActivityAggregateState),
1051 });
1052 export type RelayAgentActivitySnapshotResponse = typeof RelayAgentActivitySnapshotResponse.Type;
1053
1054 export const RelayAgentActivitySnapshotEndpoint = HttpApiEndpoint.get(
1055 "getAgentActivitySnapshot",
1056 "/v1/mobile/agent-activity",
1057 {
1058 headers: RelayDpopRequestHeaders,
1059 success: RelayAgentActivitySnapshotResponse,
1060 error: RelayAuthAndInternalErrors,
1061 },
1062 ).annotate(OpenApi.Summary, "Read the current Live Activity aggregate");
1063
1064 export const RelayUnregisterDeviceEndpoint = HttpApiEndpoint.delete(
1065 "unregisterDevice",
1066 "/v1/mobile/devices/:deviceId",
1067 {
1068 headers: RelayDpopRequestHeaders,
1069 params: RelayDeviceUnregistrationParams,
1070 success: RelayOkResponse,
1071 error: RelayAuthAndInternalErrors,
1072 },
1073 ).annotate(OpenApi.Summary, "Unregister a mobile device");
1074
1075 const RelayMobileGroup = HttpApiGroup.make("mobile")
1076 .add(
1077 RelayRegisterDeviceEndpoint,
1078 RelayRegisterLiveActivityEndpoint,
1079 RelayAgentActivitySnapshotEndpoint,
1080 RelayUnregisterDeviceEndpoint,
1081 )
1082 .annotate(OpenApi.Description, "Mobile push-notification and Live Activity registration.")
1083 .middleware(RelayDpopClientAuth);
1084
1085 const RelayClientGroup = HttpApiGroup.make("client")
1086 .add(
1087 HttpApiEndpoint.get("listEnvironments", "/v1/environments", {
1088 headers: RelayBearerRequestHeaders,
1089 success: RelayListEnvironmentsResponse,
1090 error: RelayAuthAndInternalErrors,
1091 }).annotate(OpenApi.Summary, "List linked environments"),
1092 HttpApiEndpoint.get("listDevices", "/v1/client/devices", {
1093 headers: RelayBearerRequestHeaders,
1094 success: RelayListDevicesResponseV1,
1095 error: RelayAuthAndInternalErrors,
1096 }).annotate(OpenApi.Summary, "List registered iOS devices (legacy clients)"),
1097 HttpApiEndpoint.get("listDevicesV2", "/v2/client/devices", {
1098 headers: RelayBearerRequestHeaders,
1099 success: RelayListDevicesResponse,
1100 error: RelayAuthAndInternalErrors,
1101 }).annotate(OpenApi.Summary, "List registered mobile devices"),
1102 HttpApiEndpoint.post("linkEnvironment", "/v1/client/environment-links", {
1103 headers: RelayBearerRequestHeaders,
1104 payload: RelayEnvironmentLinkRequest,
1105 success: RelayEnvironmentLinkResponse,
1106 error: RelayEnvironmentLinkErrors,
1107 }).annotate(OpenApi.Summary, "Link an environment"),
1108 HttpApiEndpoint.post(
1109 "createEnvironmentLinkChallenge",
1110 "/v1/client/environment-link-challenges",
1111 {
1112 headers: RelayBearerRequestHeaders,
1113 payload: RelayEnvironmentLinkChallengeRequest,
1114 success: RelayEnvironmentLinkChallengeResponse,
1115 error: RelayAuthAndInternalErrors,
1116 },
1117 ).annotate(OpenApi.Summary, "Create an environment-link challenge"),
1118 HttpApiEndpoint.delete("unlinkEnvironment", "/v1/client/environment-links/:environmentId", {
1119 headers: RelayBearerRequestHeaders,
1120 params: RelayEnvironmentUnlinkParams,
1121 success: RelayOkResponse,
1122 error: RelayAuthAndInternalErrors,
1123 }).annotate(OpenApi.Summary, "Unlink an environment"),
1124 HttpApiEndpoint.delete(
1125 "releaseEnvironmentTunnel",
1126 "/v1/client/environment-links/:environmentId/tunnel",
1127 {
1128 headers: RelayBearerRequestHeaders,
1129 params: RelayEnvironmentUnlinkParams,
1130 success: RelayOkResponse,
1131 error: RelayAuthAndInternalErrors,
1132 },
1133 )
1134 .annotate(OpenApi.Summary, "Release an environment's managed tunnel")
1135 .annotate(
1136 OpenApi.Description,
1137 "Deletes the provisioned Cloudflare tunnel while keeping the environment link and its hostname reservation, so a later link re-provisions the tunnel under the same URL. Environments call this when they shut down; Cloudflare bills per provisioned tunnel, so idle tunnels should not outlive their environment.",
1138 ),
1139 HttpApiEndpoint.get("getT3ChatLink", "/v1/client/t3chat-link", {
1140 headers: RelayBearerRequestHeaders,
1141 success: RelayT3ChatLinkResponse,
1142 error: RelayAuthAndInternalErrors,
1143 }).annotate(OpenApi.Summary, "Get the linked T3 Chat account"),
1144 HttpApiEndpoint.post("createT3ChatLinkRequest", "/v1/client/t3chat-link-requests", {
1145 headers: RelayBearerRequestHeaders,
1146 success: RelayT3ChatLinkRequestResponse,
1147 error: RelayAuthAndInternalErrors,
1148 }).annotate(OpenApi.Summary, "Start linking a T3 Chat account"),
1149 HttpApiEndpoint.delete("unlinkT3Chat", "/v1/client/t3chat-link", {
1150 headers: RelayBearerRequestHeaders,
1151 success: RelayOkResponse,
1152 error: RelayAuthAndInternalErrors,
1153 }).annotate(OpenApi.Summary, "Unlink the T3 Chat account"),
1154 )
1155 .annotate(OpenApi.Description, "Cloud-user environment links and registered devices.")
1156 .middleware(RelayClientAuth);
1157
1158 export const RelayExchangeDpopAccessTokenEndpoint = HttpApiEndpoint.post(
1159 "exchangeDpopAccessToken",
1160 "/v1/client/dpop-token",
1161 {
1162 headers: RelayDpopProofRequestHeaders,
1163 payload: RelayDpopAccessTokenRequest,
1164 success: RelayDpopAccessTokenResponse,
1165 error: RelayAuthAndInternalErrors,
1166 },
1167 )
1168 .annotate(OpenApi.Summary, "Exchange a Clerk token for a DPoP access token")
1169 .annotate(
1170 OpenApi.Description,
1171 "Bootstrap endpoint. Send the DPoP proof JWT in the dpop header and the Clerk token in subject_token. The returned access token is bound to the proof key.",
1172 );
1173
1174 const RelayTokenGroup = HttpApiGroup.make("token")
1175 .add(RelayExchangeDpopAccessTokenEndpoint)
1176 .annotate(OpenApi.Description, "OAuth token exchange for DPoP-bound client access.");
1177
1178 export const RelayConnectEnvironmentEndpoint = HttpApiEndpoint.post(
1179 "connectEnvironment",
1180 "/v1/environments/:environmentId/connect",
1181 {
1182 headers: RelayDpopRequestHeaders,
1183 params: Schema.Struct({
1184 environmentId: EnvironmentId,
1185 }),
1186 payload: RelayEnvironmentConnectRequest,
1187 success: RelayEnvironmentConnectResponse,
1188 error: RelayEnvironmentConnectErrors,
1189 },
1190 ).annotate(OpenApi.Summary, "Connect to an environment");
1191
1192 export const RelayGetEnvironmentStatusEndpoint = HttpApiEndpoint.post(
1193 "getEnvironmentStatus",
1194 "/v1/environments/:environmentId/status",
1195 {
1196 headers: RelayDpopRequestHeaders,
1197 params: Schema.Struct({
1198 environmentId: EnvironmentId,
1199 }),
1200 success: RelayEnvironmentStatusResponse,
1201 error: RelayEnvironmentConnectErrors,
1202 },
1203 ).annotate(OpenApi.Summary, "Check environment status");
1204
1205 const RelayDpopClientGroup = HttpApiGroup.make("dpopClient")
1206 .add(RelayConnectEnvironmentEndpoint, RelayGetEnvironmentStatusEndpoint)
1207 .annotate(OpenApi.Description, "DPoP-authenticated client access to linked environments.")
1208 .middleware(RelayDpopClientAuth);
1209
1210 export const RelayEnvironmentLinkPreferencesRequest = Schema.Struct({
1211 holdWebhooksWhileOffline: Schema.Boolean,
1212 });
1213 export type RelayEnvironmentLinkPreferencesRequest =
1214 typeof RelayEnvironmentLinkPreferencesRequest.Type;
1215
1216 export const RelayWakeHeldHooksResponse = Schema.Struct({
1217 pending: Schema.Boolean,
1218 });
1219 export type RelayWakeHeldHooksResponse = typeof RelayWakeHeldHooksResponse.Type;
1220
1221 const RelayServerGroup = HttpApiGroup.make("server")
1222 .add(
1223 HttpApiEndpoint.post(
1224 "registerManagedEndpointRecovery",
1225 "/v1/environments/:environmentId/tunnel/recovery",
1226 {
1227 params: Schema.Struct({
1228 environmentId: EnvironmentId,
1229 }),
1230 payload: RelayManagedEndpointRecoveryRegistrationRequest,
1231 success: RelayManagedEndpointRecoveryRegistrationResponse,
1232 error: RelayAuthAndInternalErrors,
1233 },
1234 ).annotate(OpenApi.Summary, "Register managed tunnel recovery without provisioning"),
1235 HttpApiEndpoint.post("recoverManagedEndpoint", "/v1/environments/:environmentId/tunnel", {
1236 params: Schema.Struct({
1237 environmentId: EnvironmentId,
1238 }),
1239 payload: RelayManagedEndpointRecoveryRequest,
1240 success: RelayManagedEndpointRecoveryResponse,
1241 error: RelayAuthAndInternalErrors,
1242 }).annotate(OpenApi.Summary, "Recover an environment's managed tunnel"),
1243 HttpApiEndpoint.post(
1244 "publishAgentActivity",
1245 "/v1/environments/:environmentId/threads/:threadId/agent-activity",
1246 {
1247 params: Schema.Struct({
1248 environmentId: EnvironmentId,
1249 threadId: ThreadId,
1250 }),
1251 payload: RelayAgentActivityPublishRequest,
1252 success: RelayPublishResponse,
1253 error: RelayAgentActivityPublishErrors,
1254 },
1255 ).annotate(OpenApi.Summary, "Publish agent activity"),
1256 HttpApiEndpoint.post(
1257 "updateLinkPreferences",
1258 "/v1/environments/:environmentId/link-preferences",
1259 {
1260 params: Schema.Struct({ environmentId: EnvironmentId }),
1261 payload: RelayEnvironmentLinkPreferencesRequest,
1262 success: RelayEnvironmentLinkPreferencesRequest,
1263 error: RelayAuthAndInternalErrors,
1264 },
1265 ).annotate(OpenApi.Summary, "Update an environment's link preferences"),
1266 HttpApiEndpoint.post(
1267 "updateLiveActivityPreference",
1268 "/v1/environments/:environmentId/live-activity-preference",
1269 {
1270 params: Schema.Struct({ environmentId: EnvironmentId }),
1271 payload: Schema.Struct({
1272 cloudUserId: Schema.String,
1273 liveActivitiesEnabled: Schema.Boolean,
1274 }),
1275 success: RelayOkResponse,
1276 error: RelayAuthAndInternalErrors,
1277 },
1278 ),
1279 HttpApiEndpoint.post("wakeHeldHooks", "/v1/environments/:environmentId/hooks/wake", {
1280 params: Schema.Struct({ environmentId: EnvironmentId }),
1281 success: RelayWakeHeldHooksResponse,
1282 error: RelayAuthAndInternalErrors,
1283 }).annotate(
1284 OpenApi.Summary,
1285 "Deliver webhook requests held while the environment was offline now",
1286 ),
1287 )
1288 .annotate(OpenApi.Description, "Environment-authenticated activity publication.")
1289 .middleware(RelayEnvironmentAuth);
1290
1291 // Path token authenticates; forward raw bytes for signature verification.
1292 // endpointKey is the managed endpoint hash, not the account-linkable environment id.
1293 const RelayHookParams = Schema.Struct({
1294 endpointKey: Schema.String,
1295 hookId: Schema.String,
1296 token: Schema.String,
1297 });
1298 const RELAY_HOOK_PATH = "/v1/hooks/:endpointKey/:hookId/:token";
1299 const relayHookEndpoint = { params: RelayHookParams } as const;
1300 const RelayHooksGroup = HttpApiGroup.make("hooks")
1301 .add(
1302 HttpApiEndpoint.post("forwardPost", RELAY_HOOK_PATH, relayHookEndpoint),
1303 HttpApiEndpoint.put("forwardPut", RELAY_HOOK_PATH, relayHookEndpoint),
1304 HttpApiEndpoint.patch("forwardPatch", RELAY_HOOK_PATH, relayHookEndpoint),
1305 HttpApiEndpoint.get("forwardGet", RELAY_HOOK_PATH, relayHookEndpoint),
1306 )
1307 .annotate(OpenApi.Description, "Forward webhook requests to an environment.");
1308
1309 export const RelayMobileTelemetrySignal = Schema.Literals(["logs", "metrics", "traces"]);
1310 export type RelayMobileTelemetrySignal = typeof RelayMobileTelemetrySignal.Type;
1311
1312 // expo-observe appends `<easProjectId>/v1/<signal>` to its endpoint URL and cannot send credentials.
1313 const RelayMobileTelemetryParams = Schema.Struct({
1314 projectId: Schema.String.check(Schema.isGUID()),
1315 signal: RelayMobileTelemetrySignal,
1316 });
1317 const RelayMobileTelemetryGroup = HttpApiGroup.make("mobileTelemetry")
1318 .add(
1319 HttpApiEndpoint.post("ingest", "/v1/mobile/observe/:projectId/v1/:signal", {
1320 params: RelayMobileTelemetryParams,
1321 }),
1322 )
1323 .annotate(OpenApi.Description, "Receive mobile app telemetry from expo-observe.");
1324
1325 export const RelayApi = HttpApi.make("RelayApi")
1326 .add(
1327 RelayHealthGroup,
1328 RelayMetadataGroup,
1329 RelayMobileGroup,
1330 RelayClientGroup,
1331 RelayTokenGroup,
1332 RelayDpopClientGroup,
1333 RelayServerGroup,
1334 RelayHooksGroup,
1335 RelayMobileTelemetryGroup,
1336 )
1337 .annotate(OpenApi.Title, "T3 Code Relay API")
1338 .annotate(OpenApi.Version, "1.0.0")
1339 .annotate(
1340 OpenApi.Description,
1341 "Control-plane API for linking T3 environments, connecting authorized clients, and publishing agent activity.",
1342 );
1343 export type RelayApi = typeof RelayApi;