The best way to control Claude Code, Codex and more from any computer or phone
| 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 | }); |