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

main
ts 242 lines 8.24 KB
Raw
1 import * as zeroTrust from "@distilled.cloud/cloudflare/zero-trust";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import * as Provider from "alchemy/Provider";
4 import { Resource } from "alchemy/Resource";
5 import * as Effect from "effect/Effect";
6 import * as Predicate from "effect/Predicate";
7 import * as Stream from "effect/Stream";
8 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
9 import type { Providers } from "../Providers.ts";
10
11 const TypeId = "Cloudflare.RiskScoring.Integration" as const;
12 type TypeId = typeof TypeId;
13
14 export interface IntegrationProps {
15 /**
16 * The third-party SOAR/SSF consumer of risk-score changes. Only
17 * `Okta` is supported by the API today.
18 * @default "Okta"
19 */
20 integrationType?: "Okta";
21 /**
22 * The base URL of the tenant that receives risk-score changes, e.g.
23 * `https://tenant.okta.com`. Mutable — updated in place via PUT.
24 */
25 tenantUrl: string;
26 /**
27 * A reference id supplied by the client. Cloudflare recommends setting
28 * it to the Access-Okta identity provider ID (a UUIDv4) so the
29 * integration can be recalled by that secondary asset.
30 */
31 referenceId?: string;
32 /**
33 * Whether the integration exports risk-score changes to the
34 * third-party. Only togglable after create (the create API always
35 * provisions an active integration).
36 * @default true
37 */
38 active?: boolean;
39 }
40
41 export type IntegrationAttributes = {
42 /** API UUID of the integration. */
43 integrationId: string;
44 /** Account that owns the integration. */
45 accountId: string;
46 /** The third-party consumer of risk-score changes. */
47 integrationType: "Okta" | (string & {});
48 /** Observed tenant base URL. */
49 tenantUrl: string;
50 /** Observed client-supplied reference id. */
51 referenceId: string;
52 /** Whether risk-score changes are exported. */
53 active: boolean;
54 /** The Shared Signals Framework configuration URL. */
55 wellKnownUrl: string;
56 /** RFC 3339 timestamp of when the integration was created. */
57 createdAt: string;
58 };
59
60 export type Integration = Resource<
61 TypeId,
62 IntegrationProps,
63 IntegrationAttributes,
64 never,
65 Providers
66 >;
67
68 /**
69 * A Cloudflare Zero Trust **risk scoring integration** — a Shared
70 * Signals Framework (SSF) push integration that exports user risk-score
71 * changes to a third-party tenant (currently Okta) so the IdP can react
72 * to risky behavior detected by Zero Trust.
73 *
74 * Requires the Zero Trust risk-scoring entitlement (an Enterprise
75 * feature); accounts without it receive the typed `Forbidden` error on
76 * all writes.
77 * ### Creating a risk scoring integration
78 * **Example:** Push risk scores to an Okta tenant
79 * ```typescript
80 * const okta = yield* Cloudflare.RiskScoring.Integration("OktaSsf", {
81 * tenantUrl: "https://tenant.okta.com",
82 * referenceId: oktaIdp.identityProviderId,
83 * });
84 * ```
85 *
86 * **Example:** Pause exporting without deleting
87 * ```typescript
88 * const okta = yield* Cloudflare.RiskScoring.Integration("OktaSsf", {
89 * tenantUrl: "https://tenant.okta.com",
90 * active: false,
91 * });
92 * ```
93 *
94 * @see https://developers.cloudflare.com/cloudflare-one/insights/risk-score/
95 *
96 * @resource
97 * @product Risk Scoring
98 * @category Cloudflare One (Zero Trust)
99 */
100 export const Integration = Resource<Integration>(TypeId);
101
102 /**
103 * Returns true if the given value is a Integration resource.
104 */
105 export const isIntegration = (value: unknown): value is Integration =>
106 Predicate.hasProperty(value, "Type") && value.Type === TypeId;
107
108 export const IntegrationProvider = () =>
109 Provider.succeed(Integration, {
110 stables: ["integrationId", "accountId", "integrationType", "createdAt"],
111
112 read: Effect.fn(function* ({ output, olds }) {
113 const { accountId } = yield* yield* CloudflareEnvironment;
114 const acct = output?.accountId ?? accountId;
115
116 if (output?.integrationId) {
117 const observed = yield* observeIntegration(acct, output.integrationId);
118 return observed ? toAttributes(observed, acct) : undefined;
119 }
120
121 // Cold lookup by tenant URL. Integrations carry no ownership
122 // markers — brand the match `Unowned`.
123 const tenantUrl = olds?.tenantUrl;
124 if (tenantUrl === undefined) return undefined;
125 const match = yield* findByTenantUrl(acct, tenantUrl);
126 if (match) return Unowned(toAttributes(match, acct));
127 return undefined;
128 }),
129
130 reconcile: Effect.fn(function* ({ news, output }) {
131 const { accountId } = yield* yield* CloudflareEnvironment;
132
133 // 1. Observe — cached id is a hint; fall back to a tenant-URL scan
134 // so a crashed prior run converges.
135 let observed = output?.integrationId
136 ? yield* observeIntegration(accountId, output.integrationId)
137 : undefined;
138 if (!observed) {
139 observed = yield* findByTenantUrl(accountId, news.tenantUrl);
140 }
141
142 // 2. Ensure — create when missing. Create always provisions an
143 // active integration; the sync step below applies `active: false`.
144 if (!observed) {
145 observed = yield* zeroTrust.createRiskScoringIntegration({
146 accountId,
147 integrationType: news.integrationType ?? "Okta",
148 tenantUrl: news.tenantUrl,
149 ...(news.referenceId !== undefined ? { referenceId: news.referenceId } : {}),
150 });
151 }
152
153 // 3. Sync — PUT the full desired state when the observed state
154 // differs; skip the call on a no-op.
155 const desiredActive = news.active ?? true;
156 const dirty =
157 observed.tenantUrl !== news.tenantUrl ||
158 observed.active !== desiredActive ||
159 (news.referenceId !== undefined && observed.referenceId !== news.referenceId);
160 if (!dirty) {
161 return toAttributes(observed, accountId);
162 }
163 const updated = yield* zeroTrust.updateRiskScoringIntegration({
164 accountId,
165 integrationId: observed.id,
166 active: desiredActive,
167 tenantUrl: news.tenantUrl,
168 ...(news.referenceId !== undefined ? { referenceId: news.referenceId } : {}),
169 });
170 return toAttributes(updated, accountId);
171 }),
172
173 delete: Effect.fn(function* ({ output }) {
174 yield* zeroTrust
175 .deleteRiskScoringIntegration({
176 accountId: output.accountId,
177 integrationId: output.integrationId,
178 })
179 .pipe(Effect.catchTag("RiskScoringIntegrationNotFound", () => Effect.void));
180 }),
181
182 // Account collection (pattern b). Enumerate every risk-scoring
183 // integration in the ambient account, exhaustively paginating the
184 // distilled list op. Accounts lacking the Zero Trust risk-scoring
185 // entitlement reject the route with a typed `Forbidden` — treat that
186 // as "nothing to list" and return [].
187 list: Effect.fn(function* () {
188 const { accountId } = yield* yield* CloudflareEnvironment;
189 return yield* zeroTrust.listRiskScoringIntegrations.pages({ accountId }).pipe(
190 Stream.runCollect,
191 Effect.map((chunk) =>
192 Array.from(chunk).flatMap((page) =>
193 (page.result ?? []).map((integration) => toAttributes(integration, accountId)),
194 ),
195 ),
196 Effect.catchTag("Forbidden", () => Effect.succeed([])),
197 );
198 }),
199 });
200
201 /**
202 * Structural shape shared by get/list/create/update responses.
203 */
204 type ObservedIntegration = {
205 id: string;
206 active: boolean;
207 createdAt: string;
208 integrationType: string;
209 referenceId: string;
210 tenantUrl: string;
211 wellKnownUrl: string;
212 };
213
214 /**
215 * Read an integration by id, mapping "gone" to `undefined`.
216 */
217 const observeIntegration = (accountId: string, integrationId: string) =>
218 zeroTrust
219 .getRiskScoringIntegration({ accountId, integrationId })
220 .pipe(Effect.catchTag("RiskScoringIntegrationNotFound", () => Effect.undefined));
221
222 /**
223 * Find an integration by exact tenant URL.
224 */
225 const findByTenantUrl = (accountId: string, tenantUrl: string) =>
226 zeroTrust
227 .listRiskScoringIntegrations({ accountId })
228 .pipe(Effect.map((list) => list.result.find((i) => i.tenantUrl === tenantUrl)));
229
230 const toAttributes = (
231 integration: ObservedIntegration,
232 accountId: string,
233 ): IntegrationAttributes => ({
234 integrationId: integration.id,
235 accountId,
236 integrationType: integration.integrationType,
237 tenantUrl: integration.tenantUrl,
238 referenceId: integration.referenceId,
239 active: integration.active,
240 wellKnownUrl: integration.wellKnownUrl,
241 createdAt: integration.createdAt,
242 });