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

main
ts 417 lines 15.7 KB
Raw
1 import * as Neon from "@distilled.cloud/neon";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import * as Effect from "effect/Effect";
7 import {
8 GovernanceRoleSafetyError,
9 governanceRoleTransition,
10 listGovernanceOrganizationMembers,
11 sameOrganizationRole,
12 requireGovernanceBaseline,
13 validateGovernanceActor,
14 validateGovernanceScope,
15 type GovernanceRoleBaseline,
16 } from "./OrganizationMemberRole.ts";
17 import type { Providers } from "./Providers.ts";
18
19 /** Direct project roles supported by Neon. */
20 export type ProjectGovernanceRole = "viewer" | "editor" | "admin";
21
22 export interface ProjectMemberRoleProps {
23 /** Organization owning both the existing membership and project. */
24 orgId: string;
25 /** Existing organization membership ID, never a user ID or email. */
26 memberId: string;
27 /** Already-deployed organization project. Supply its resolved ID on first deployment. */
28 project: { projectId: string };
29 /** Direct project grant to manage; does not replace organization defaults. */
30 role: ProjectGovernanceRole;
31 }
32
33 export interface ProjectMemberRoleAttributes {
34 /** Project containing the direct grant. */
35 projectId: string;
36 /** Organization owning the project and member. */
37 orgId: string;
38 /** Existing membership receiving the direct grant. */
39 memberId: string;
40 /** Observed direct grant; null means no explicit grant, not no effective access. */
41 role: ProjectGovernanceRole | null;
42 /** Original direct grant and ownership evidence. Null originalRole means remove only our grant. */
43 baseline: GovernanceRoleBaseline<ProjectGovernanceRole | null>;
44 }
45
46 export interface ProjectMemberRole extends Resource<
47 "Neon.ProjectMemberRole",
48 ProjectMemberRoleProps,
49 ProjectMemberRoleAttributes,
50 never,
51 Providers
52 > {}
53
54 /**
55 * Own one explicit project grant for an existing organization member.
56 * Inherited/default access is not owned or removed. Adopting an existing direct
57 * grant requires explicit adoption and captures it for exact restoration.
58 * Deletion removes only a newly created direct grant, or restores the adopted one.
59 * Organization-admin overrides and self changes are refused. This resource never
60 * enables confirm_self_demotion or confirm_self_lockout and never invites anyone.
61 *
62 * Requires user credentials with observable ADMIN project permission. A missing
63 * member, ambiguous grant source, or list failure is not evidence of no grant.
64 * The list API's 404 can mean disabled permissions or insufficient access.
65 * Cleanup accepts a removed membership only after a complete organization listing.
66 * A missing project additionally requires an organization-admin scoped project
67 * listing with no unavailable entries; an ambiguous 404 alone never discards state.
68 *
69 * The engine durably saves the initial read snapshot before reconciliation.
70 * Deploy the project first, then supply its resolved ID and resolved settings.
71 * Missing baselines and ambiguous interrupted writes fail closed. Do not discard
72 * state or edit this grant concurrently: Neon has no conditional role-write API.
73 *
74 * ### Grant access to an existing member
75 * **Example:** Manage a direct grant on an already-deployed project
76 * ```typescript
77 * const access = yield* Neon.ProjectMemberRole("ReviewerAccess", {
78 * orgId: "org-example",
79 * memberId: authorizedMemberId,
80 * project: { projectId: deployedProjectId },
81 * role: "viewer",
82 * });
83 * ```
84 *
85 * ### Adopt a direct grant
86 * **Example:** Preserve and restore an existing explicit role
87 * ```typescript
88 * const access = yield* Neon.ProjectMemberRole("ExistingAccess", {
89 * orgId: "org-example",
90 * memberId: authorizedMemberId,
91 * project: { projectId: deployedProjectId },
92 * role: "editor",
93 * }).pipe(Alchemy.adopt(true));
94 * ```
95 *
96 * @resource
97 * @product Project
98 */
99 export const ProjectMemberRole = Resource<ProjectMemberRole>("Neon.ProjectMemberRole");
100
101 /** Validate persisted or desired project grants. @internal */
102 export const validateProjectGovernanceRole = (role: ProjectGovernanceRole | null) =>
103 role === null || role === "viewer" || role === "editor" || role === "admin"
104 ? Effect.void
105 : Effect.fail(
106 new GovernanceRoleSafetyError({
107 message: "Unsupported project grant role",
108 }),
109 );
110
111 /** Distinguish direct access from the effective role and organization defaults. @internal */
112 export const projectMemberDirectRole = (member: Neon.ProjectMember) => {
113 if (member.org_role === "admin" || member.grant_source === "org_admin_override") {
114 return Effect.fail(
115 new GovernanceRoleSafetyError({
116 message: "Organization-admin project overrides cannot be managed as direct grants",
117 }),
118 );
119 }
120 const permission = member.explicit_project_permission;
121 if (member.grant_source === "explicit") {
122 if (permission === "VIEWER") return Effect.succeed("viewer" as const);
123 if (permission === "EDITOR") return Effect.succeed("editor" as const);
124 if (permission === "ADMIN") return Effect.succeed("admin" as const);
125 } else if (
126 (member.grant_source === "org_role_default" || member.grant_source === "unassigned") &&
127 permission === undefined
128 ) {
129 return Effect.succeed(null);
130 }
131 return Effect.fail(
132 new GovernanceRoleSafetyError({
133 message:
134 "Project grant source and explicit permission do not establish a recoverable direct grant",
135 }),
136 );
137 };
138
139 const validateProps = Effect.fn(function* (props: ProjectMemberRoleProps) {
140 yield* validateGovernanceScope(props);
141 if (!props.project?.projectId || typeof props.project.projectId !== "string") {
142 return yield* new GovernanceRoleSafetyError({
143 message: "An explicit resolved existing project ID is required",
144 });
145 }
146 yield* validateProjectGovernanceRole(props.role);
147 if (props.role === null)
148 return yield* new GovernanceRoleSafetyError({
149 message: "A desired direct project role is required",
150 });
151 });
152
153 const request = (scope: { projectId: string; memberId: string }) => ({
154 project_id: scope.projectId,
155 member_id: scope.memberId,
156 });
157
158 const observe = Effect.fn(function* (
159 scope: { orgId: string; memberId: string; projectId: string },
160 listedMembership?: Neon.Member,
161 ) {
162 yield* validateGovernanceScope(scope);
163 const { project } = yield* Neon.getProject({ project_id: scope.projectId });
164 if (project.org_id !== scope.orgId || project.effective_project_permission !== "ADMIN") {
165 return yield* new GovernanceRoleSafetyError({
166 message:
167 "Project organization and caller ADMIN permission must be observable before managing grants",
168 });
169 }
170 const membership =
171 listedMembership ??
172 (yield* Neon.getOrganizationMember({
173 org_id: scope.orgId,
174 member_id: scope.memberId,
175 }));
176 if (membership.org_id !== scope.orgId || membership.id !== scope.memberId) {
177 return yield* new GovernanceRoleSafetyError({
178 message: "Membership identity does not match the project organization",
179 });
180 }
181 let cursor: string | undefined;
182 const seen = new Set<string>();
183 for (let page = 0; page < 10; page++) {
184 const response = yield* Neon.listProjectMembers({
185 project_id: scope.projectId,
186 cursor,
187 limit: 500,
188 });
189 const member = response.project_members.find((member) => member.member_id === scope.memberId);
190 if (member) {
191 if (
192 member.user_id !== membership.user_id ||
193 member.org_role === undefined ||
194 !sameOrganizationRole(member.org_role, membership.role) ||
195 !member.user_id
196 ) {
197 return yield* new GovernanceRoleSafetyError({
198 message: "Project member does not match the observed organization membership",
199 });
200 }
201 return {
202 role: yield* projectMemberDirectRole(member),
203 userId: member.user_id,
204 };
205 }
206 const next = response.pagination?.next;
207 if (!next) break;
208 if (seen.has(next))
209 return yield* new GovernanceRoleSafetyError({
210 message: "Project membership pagination repeated a cursor",
211 });
212 seen.add(next);
213 cursor = next;
214 }
215 return yield* new GovernanceRoleSafetyError({
216 message:
217 "Member is not visible in a complete bounded project-member listing; refusing to infer an absent grant",
218 });
219 });
220
221 const projectAbsenceProven = Effect.fn(function* (
222 scope: { orgId: string; projectId: string },
223 members: readonly Neon.Member[],
224 ) {
225 const actor = yield* Neon.getCurrentUserInfo({});
226 if (!members.some((member) => member.user_id === actor.id && member.role === "admin")) {
227 return yield* new GovernanceRoleSafetyError({
228 message:
229 "Project absence requires an organization-admin listing; restricted project visibility is not proof of deletion",
230 });
231 }
232 const seen = new Set<string>();
233 let cursor: string | undefined;
234 for (let page = 0; page < 10; page++) {
235 const response = yield* Neon.listProjects({
236 org_id: scope.orgId,
237 cursor,
238 limit: 400,
239 });
240 if (response.unavailable_project_ids?.length) {
241 return yield* new GovernanceRoleSafetyError({
242 message: "Project listing contains unavailable projects; absence is unproven",
243 });
244 }
245 if (
246 response.projects.some(
247 (project) => project.org_id !== undefined && project.org_id !== scope.orgId,
248 )
249 ) {
250 return yield* new GovernanceRoleSafetyError({
251 message: "Scoped project listing returned a different organization",
252 });
253 }
254 if (response.projects.some((project) => project.id === scope.projectId)) return false;
255 if (response.projects.length === 0) return true;
256 const next = response.pagination?.cursor;
257 if (next === undefined) return true;
258 if (!next || seen.has(next)) {
259 return yield* new GovernanceRoleSafetyError({
260 message: "Scoped project listing returned an invalid or repeated cursor",
261 });
262 }
263 seen.add(next);
264 cursor = next;
265 }
266 return yield* new GovernanceRoleSafetyError({
267 message: "Scoped project listing exceeded its bounded pagination limit; absence is unproven",
268 });
269 });
270
271 const verifyBaseline = Effect.fn(function* (
272 output: ProjectMemberRoleAttributes | undefined,
273 owner: { fqn: string; instanceId: string },
274 ) {
275 const baseline = yield* requireGovernanceBaseline(output?.baseline, owner);
276 yield* validateProjectGovernanceRole(baseline.originalRole);
277 yield* validateProjectGovernanceRole(baseline.managedRole);
278 return baseline;
279 });
280
281 export const ProjectMemberRoleProvider = () =>
282 Provider.succeed(ProjectMemberRole, {
283 nuke: { skip: true },
284 stables: ["orgId", "memberId", "projectId"],
285 diff: Effect.fn(function* ({ news, olds, output }) {
286 if (!isResolved(news)) return;
287 yield* validateProps(news);
288 if (
289 news.orgId !== (output?.orgId ?? olds.orgId) ||
290 news.memberId !== (output?.memberId ?? olds.memberId) ||
291 news.project.projectId !== (output?.projectId ?? olds.project.projectId)
292 )
293 return yield* new GovernanceRoleSafetyError({
294 message:
295 "Restore and remove the existing grant control before changing its project or membership identity; a new durable grant snapshot is required",
296 });
297 }),
298 read: Effect.fn(function* ({ olds, output, fqn, instanceId }) {
299 if (!output) yield* validateProps(olds);
300 const scope = output ?? {
301 orgId: olds.orgId,
302 memberId: olds.memberId,
303 projectId: olds.project.projectId,
304 };
305 const baseline = output ? yield* verifyBaseline(output, { fqn, instanceId }) : undefined;
306 const observed = yield* observe(scope);
307 if (output && baseline) {
308 if (observed.userId !== baseline.userId)
309 return yield* new GovernanceRoleSafetyError({
310 message: "Membership user changed",
311 });
312 yield* governanceRoleTransition(baseline, observed.role, observed.role);
313 return { ...output, role: observed.role };
314 }
315 const attributes: ProjectMemberRoleAttributes = {
316 orgId: scope.orgId,
317 memberId: scope.memberId,
318 projectId: scope.projectId,
319 role: observed.role,
320 baseline: {
321 fqn,
322 instanceId,
323 userId: observed.userId,
324 originalRole: observed.role,
325 managedRole: observed.role,
326 },
327 };
328 return observed.role === null ? attributes : Unowned(attributes);
329 }),
330 reconcile: Effect.fn(function* ({ news, output, fqn, instanceId }) {
331 yield* validateProps(news);
332 const baseline = yield* verifyBaseline(output, { fqn, instanceId });
333 if (!output)
334 return yield* new GovernanceRoleSafetyError({
335 message: "A persisted initial grant snapshot is required before changing project access",
336 });
337 if (
338 news.orgId !== output.orgId ||
339 news.memberId !== output.memberId ||
340 news.project.projectId !== output.projectId
341 ) {
342 return yield* new GovernanceRoleSafetyError({
343 message: "Project grant identity changed without replacement",
344 });
345 }
346 const observed = yield* observe(output);
347 if (observed.userId !== baseline.userId)
348 return yield* new GovernanceRoleSafetyError({
349 message: "Membership user changed",
350 });
351 if (yield* governanceRoleTransition(baseline, observed.role, news.role)) {
352 yield* validateGovernanceActor(observed.userId, (yield* Neon.getCurrentUserInfo({})).id);
353 yield* Neon.setProjectMemberRole({
354 ...request(output),
355 role: news.role,
356 confirm_self_demotion: false,
357 });
358 }
359 const current = yield* observe(output);
360 if (current.userId !== baseline.userId || current.role !== news.role) {
361 return yield* new GovernanceRoleSafetyError({
362 message: "Direct project grant did not converge",
363 });
364 }
365 return {
366 ...output,
367 role: current.role,
368 baseline: { ...baseline, managedRole: current.role },
369 };
370 }),
371 delete: Effect.fn(function* ({ output, fqn, instanceId }) {
372 const baseline = yield* verifyBaseline(output, { fqn, instanceId });
373 yield* validateGovernanceScope(output);
374 const members = yield* listGovernanceOrganizationMembers(output.orgId);
375 const membership = members.find((member) => member.id === output.memberId);
376 if (!membership) return;
377 if (membership.user_id !== baseline.userId) {
378 return yield* new GovernanceRoleSafetyError({
379 message: "Membership user changed",
380 });
381 }
382 const observed = yield* observe(output, membership).pipe(
383 Effect.catchTag("NotFound", (error) =>
384 Effect.gen(function* () {
385 if (yield* projectAbsenceProven(output, members)) return undefined;
386 return yield* error;
387 }),
388 ),
389 );
390 if (!observed) return;
391 if (observed.userId !== baseline.userId)
392 return yield* new GovernanceRoleSafetyError({
393 message: "Membership user changed",
394 });
395 if (yield* governanceRoleTransition(baseline, observed.role, baseline.originalRole, true)) {
396 yield* validateGovernanceActor(observed.userId, (yield* Neon.getCurrentUserInfo({})).id);
397 if (baseline.originalRole === null) {
398 yield* Neon.removeProjectMemberRole({
399 ...request(output),
400 confirm_self_lockout: false,
401 });
402 } else {
403 yield* Neon.setProjectMemberRole({
404 ...request(output),
405 role: baseline.originalRole,
406 confirm_self_demotion: false,
407 });
408 }
409 const restored = yield* observe(output);
410 if (restored.userId !== baseline.userId || restored.role !== baseline.originalRole) {
411 return yield* new GovernanceRoleSafetyError({
412 message: "Original explicit project grant was not restored",
413 });
414 }
415 }
416 }),
417 });