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

main
ts 225 lines 8.41 KB
Raw
1 import * as Neon from "@distilled.cloud/neon";
2 import { isResolved } from "alchemy/Diff";
3 import { createPhysicalName } from "alchemy/PhysicalName";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import * as Data from "effect/Data";
7 import * as Effect from "effect/Effect";
8 import * as Redacted from "effect/Redacted";
9 import type { Providers } from "./Providers.ts";
10
11 export interface OrganizationApiKeyProps {
12 /** Organization that owns the key. Changes replace the key. */
13 orgId: string;
14 /** Restrict access to this project. Omission grants organization-wide access. Changes replace the key. */
15 projectId?: string;
16 /** Immutable key label. Defaults to an instance-qualified physical name. Adding, changing, or removing an explicit label replaces the key. */
17 name?: string;
18 }
19
20 export interface OrganizationApiKeyAttributes {
21 /** Organization that owns the key. */
22 orgId: string;
23 /** Project restriction, or undefined for organization-wide access. */
24 projectId: string | undefined;
25 /** Stable numeric API key identifier, not the secret token. */
26 keyId: number;
27 /** Observed key label. A matching label is never ownership evidence. */
28 name: string;
29 /** Reveal-once secret stored in Alchemy state. Never the deployment API key. */
30 key: Redacted.Redacted<string>;
31 /** Issuance timestamp. */
32 createdAt: string;
33 }
34
35 export interface OrganizationApiKey extends Resource<
36 "Neon.OrganizationApiKey",
37 OrganizationApiKeyProps,
38 OrganizationApiKeyAttributes,
39 never,
40 Providers
41 > {}
42
43 /**
44 * A reveal-once Neon management API key owned by an organization, optionally
45 * restricted to one project. This is not a branch service credential; use
46 * `Neon.Credential` for branch-scoped storage and backend permissions.
47 *
48 * Keep Alchemy state secure and backed up. Neon cannot reveal an existing key.
49 * Missing secrets, revoked keys, and same-name foreign keys fail with
50 * `OrganizationApiKeyRecoveryError` instead of being adopted or silently rotated.
51 * Restore the original state or explicitly revoke the recorded key and replace
52 * the resource. Changing the organization, project restriction, or name replaces
53 * the key. Explicit names may require deleting the recorded old key first.
54 *
55 * ### Project-restricted access
56 * **Example:** Provision a key for a test-owned project
57 * ```typescript
58 * const project = yield* Neon.Project("Application", { orgId: "org-example" });
59 * const key = yield* Neon.OrganizationApiKey("Automation", {
60 * orgId: "org-example",
61 * projectId: project.projectId,
62 * });
63 * ```
64 *
65 * ### Organization-wide access
66 * **Example:** Explicitly choose organization-wide administration
67 * ```typescript
68 * const key = yield* Neon.OrganizationApiKey("OrganizationAdministration", {
69 * orgId: "org-example",
70 * });
71 * ```
72 * Omitting `projectId` grants broad organization access; prefer a project
73 * restriction whenever possible. The secret output is `key.key`, a Redacted value.
74 *
75 * @resource
76 * @product Organization
77 */
78 export const OrganizationApiKey = Resource<OrganizationApiKey>("Neon.OrganizationApiKey");
79
80 export class OrganizationApiKeyRecoveryError extends Data.TaggedError(
81 "OrganizationApiKeyRecoveryError",
82 )<{
83 message: string;
84 }> {}
85
86 type KeyScope = Pick<OrganizationApiKeyProps, "orgId" | "projectId">;
87 type KeyMetadata = Pick<
88 Neon.OrgApiKeysListResponseItem,
89 "id" | "name" | "project_id" | "created_at"
90 >;
91
92 const recoveryError = () =>
93 new OrganizationApiKeyRecoveryError({
94 message:
95 "Organization API key identity or reveal-once secret cannot be recovered. Restore the original Alchemy state, or explicitly revoke the recorded key and replace the resource; names do not authorize adoption or recreation.",
96 });
97
98 const sameScope = (a: KeyScope, b: KeyScope) => a.orgId === b.orgId && a.projectId === b.projectId;
99
100 const validScope = (scope: KeyScope) =>
101 typeof scope.orgId === "string" &&
102 scope.orgId.trim().length > 0 &&
103 (scope.projectId === undefined ||
104 (typeof scope.projectId === "string" && scope.projectId.trim().length > 0));
105
106 const validateScope = (scope: KeyScope) =>
107 validScope(scope) ? Effect.void : Effect.fail(recoveryError());
108
109 /** Preserve a cached secret only when the observed ID and complete scope match. */
110 export const recoverOrganizationApiKey = (
111 scope: KeyScope,
112 observed: KeyMetadata | undefined,
113 cached: OrganizationApiKeyAttributes | undefined,
114 ): Effect.Effect<OrganizationApiKeyAttributes, OrganizationApiKeyRecoveryError> => {
115 if (
116 !validScope(scope) ||
117 !observed ||
118 !cached ||
119 !Number.isSafeInteger(observed.id) ||
120 observed.id <= 0 ||
121 cached.keyId !== observed.id ||
122 !sameScope(scope, cached) ||
123 observed.project_id !== scope.projectId ||
124 !Redacted.isRedacted(cached.key) ||
125 typeof Redacted.value(cached.key) !== "string" ||
126 Redacted.value(cached.key).length === 0
127 ) {
128 return Effect.fail(recoveryError());
129 }
130 return Effect.succeed({
131 ...scope,
132 projectId: observed.project_id,
133 keyId: observed.id,
134 name: observed.name,
135 key: cached.key,
136 createdAt: observed.created_at,
137 });
138 };
139
140 const observeKey = Effect.fn(function* (
141 scope: KeyScope,
142 name: string,
143 cached?: OrganizationApiKeyAttributes,
144 ) {
145 yield* validateScope(scope);
146 // This endpoint returns one complete array, with no pagination or cursor.
147 const keys = yield* Neon.listOrgApiKeys({ org_id: scope.orgId }).pipe(Neon.Retry.none);
148 const matches = keys.filter((key) => (cached ? key.id === cached.keyId : key.name === name));
149 if (matches.length > 1) return yield* recoveryError();
150 return matches[0];
151 });
152
153 export const OrganizationApiKeyProvider = () =>
154 Provider.succeed(OrganizationApiKey, {
155 stables: ["orgId", "projectId", "keyId", "name", "key", "createdAt"],
156 diff: Effect.fn(function* ({ olds, news, output }) {
157 if (!isResolved(news)) return { action: "replace" };
158 if (news.name !== olds.name || (output && !sameScope(news, output))) {
159 return {
160 action: "replace",
161 deleteFirst:
162 output !== undefined && news.orgId === output.orgId && news.name === output.name,
163 };
164 }
165 }),
166 read: Effect.fn(function* ({ id, olds, output }) {
167 if (!output && !olds) return undefined;
168 const scope = output ?? olds!;
169 const name =
170 output?.name ?? olds?.name ?? (yield* createPhysicalName({ id, maxLength: 100 }));
171 const observed = yield* observeKey(scope, name, output);
172 if (!observed && !output) return undefined;
173 return yield* recoverOrganizationApiKey(scope, observed, output);
174 }),
175 reconcile: Effect.fn(function* ({ id, news, olds, output }) {
176 yield* validateScope(news);
177 if (
178 (output &&
179 (!sameScope(news, output) || (news.name !== undefined && news.name !== output.name))) ||
180 (olds && news.name !== olds.name) ||
181 (!output && olds)
182 ) {
183 return yield* recoveryError();
184 }
185 const name = news.name ?? output?.name ?? (yield* createPhysicalName({ id, maxLength: 100 }));
186 if (!name.trim()) return yield* recoveryError();
187 const observed = yield* observeKey(news, name, output);
188 if (observed || output) {
189 const recovered = yield* recoverOrganizationApiKey(news, observed, output);
190 if (recovered.name !== name) return yield* recoveryError();
191 return recovered;
192 }
193 // A retried reveal-once POST could issue an untracked second key.
194 const created = yield* Neon.createOrgApiKey({
195 org_id: news.orgId,
196 project_id: news.projectId,
197 key_name: name,
198 }).pipe(
199 Neon.Retry.none,
200 Effect.catchTag("Conflict", () => Effect.fail(recoveryError())),
201 );
202 return yield* recoverOrganizationApiKey(news, created, {
203 orgId: news.orgId,
204 projectId: news.projectId,
205 keyId: created.id,
206 name: created.name,
207 key: Redacted.isRedacted(created.key) ? created.key : Redacted.make(created.key),
208 createdAt: created.created_at,
209 });
210 }),
211 delete: Effect.fn(function* ({ output }) {
212 const observed = yield* observeKey(output, output.name, output).pipe(
213 Effect.catchTag("NotFound", () => Effect.undefined),
214 );
215 if (!observed) return;
216 if (observed.project_id !== output.projectId) return yield* recoveryError();
217 yield* Neon.revokeOrgApiKey({
218 org_id: output.orgId,
219 key_id: output.keyId,
220 }).pipe(
221 Neon.Retry.none,
222 Effect.catchTag("NotFound", () => Effect.void),
223 );
224 }),
225 });