import * as location from "@distilled.cloud/aws/location";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags, type Tags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as EffectStream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { toTagRecord } from "./internal.ts";
export class LocationApiKeyUnexpectedResponse extends Data.TaggedError(
"LocationApiKeyUnexpectedResponse",
)<{
readonly message: string;
readonly cause?: unknown;
}> {}
/**
* What a Location API key is allowed to call. Keys authorize *unsigned*
* requests, so restrictions should be as narrow as possible.
*/
export interface ApiKeyRestrictions {
/**
* Allowed API actions, e.g. `["geo:GetMap*"]` or
* `["geo:SearchPlaceIndexForText"]`. Wildcards are allowed at the end of
* an action name.
*/
allowActions: string[];
/**
* Allowed resource ARNs, e.g. a specific map's ARN or a wildcard like
* `arn:aws:geo:*:*:map/*`.
*/
allowResources: string[];
/**
* Optional HTTP referer patterns the key may be used from, e.g.
* `["https://example.com/*"]`.
*/
allowReferers?: string[];
}
export interface ApiKeyProps {
/**
* Name of the API key. Immutable — changing it replaces the key.
* @default ${app}-${stage}-${id}
*/
keyName?: string;
/**
* The actions, resources, and referers the key is allowed to be used
* with. Updatable in place.
*/
restrictions: ApiKeyRestrictions;
/**
* Optional description of the API key.
*/
description?: string;
/**
* Expiry as an ISO-8601 timestamp, e.g. `"2027-01-01T00:00:00Z"`.
* Mutually exclusive with `noExpiry`.
*/
expireTime?: string;
/**
* Create the key without an expiry.
* @default true when `expireTime` is omitted
*/
noExpiry?: boolean;
/**
* Tags to associate with the API key.
*/
tags?: Record<string, string>;
}
export interface ApiKey extends Resource<
"AWS.Location.ApiKey",
ApiKeyProps,
{
/** Physical name of the API key. */
keyName: string;
/** ARN of the API key resource. */
keyArn: string;
/**
* The key value clients send (`v1.public.…`). Wrapped in `Redacted` —
* unwrap with `Redacted.value(apiKey.key)` where the raw value is
* needed.
*/
key: Redacted.Redacted<string>;
/** Restrictions currently applied to the key. */
restrictions: ApiKeyRestrictions;
/** Expiry timestamp (ISO-8601), if any. */
expireTime: string | undefined;
/** Description of the API key. */
description: string | undefined;
/** Tags currently associated with the key. */
tags: Record<string, string>;
},
never,
Providers
> {}
/**
* An Amazon Location Service API key. API keys authorize **unsigned**
* requests (e.g. map tiles rendered directly in a browser) to a restricted
* set of Location actions and resources. The key name is immutable;
* restrictions, description, and expiry can be updated in place.
*
* The `key` attribute is the secret key value (`v1.public.…`) clients pass
* as the `key` query parameter; it is wrapped in `Redacted`.
*
* Availability: Amazon Location classic (V1) is closed to newer AWS
* accounts — `geo:CreateKey` is rejected service-side with an
* `AccessDeniedException` regardless of IAM policy. Accounts onboarded to
* Location before the V2 split can create keys normally.
*
* ### Creating API Keys
* **Example:** Map-Rendering Key for Browsers
* ```typescript
* import * as Location from "@alchemy.run/aws/Location";
*
* const map = yield* Location.Map("SiteMap", {
* configuration: { style: "VectorEsriStreets" },
* });
*
* const key = yield* Location.ApiKey("SiteMapKey", {
* restrictions: {
* allowActions: ["geo:GetMap*"],
* allowResources: [map.mapArn],
* },
* });
* // Redacted.value(key.key) → "v1.public.…" — append as ?key=… to tile URLs
* ```
*
* **Example:** Key with Referer Restrictions and Expiry
* ```typescript
* const key = yield* Location.ApiKey("WebKey", {
* restrictions: {
* allowActions: ["geo:GetMap*"],
* allowResources: ["arn:aws:geo:*:*:map/*"],
* allowReferers: ["https://example.com/*"],
* },
* expireTime: "2027-01-01T00:00:00Z",
* });
* ```
*
* @resource
*/
export const ApiKey = Resource<ApiKey>("AWS.Location.ApiKey");
const createKeyName = (id: string, props: { keyName?: string | undefined }) =>
Effect.gen(function* () {
if (props.keyName) return props.keyName;
return yield* createPhysicalName({ id, maxLength: 100 });
});
const unredact = (value: string | Redacted.Redacted<string>): string =>
Redacted.isRedacted(value) ? Redacted.value(value) : value;
const toRestrictions = (restrictions: location.ApiKeyRestrictions): ApiKeyRestrictions => ({
allowActions: [...restrictions.AllowActions],
allowResources: [...restrictions.AllowResources],
allowReferers:
restrictions.AllowReferers === undefined
? undefined
: (restrictions.AllowReferers as (string | Redacted.Redacted<string>)[]).map(unredact),
});
/** Order-insensitive structural comparison of key restrictions. */
const sameRestrictions = (a: ApiKeyRestrictions, b: ApiKeyRestrictions) => {
const norm = (r: ApiKeyRestrictions) =>
JSON.stringify({
actions: [...r.allowActions].sort(),
resources: [...r.allowResources].sort(),
referers: [...(r.allowReferers ?? [])].sort(),
});
return norm(a) === norm(b);
};
const readKey = Effect.fn(function* (keyName: string) {
const found = yield* location
.describeKey({ KeyName: keyName })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
if (!found) return undefined;
return {
keyName: found.KeyName,
keyArn: found.KeyArn,
key: Redacted.make(unredact(found.Key)),
restrictions: toRestrictions(found.Restrictions),
expireTime: found.ExpireTime ? found.ExpireTime.toISOString() : undefined,
description: found.Description ? found.Description : undefined,
tags: toTagRecord(found.Tags),
} satisfies ApiKey["Attributes"];
});
export const ApiKeyProvider = () =>
Provider.effect(
ApiKey,
Effect.gen(function* () {
return {
stables: ["keyName", "keyArn", "key"],
list: () =>
Effect.gen(function* () {
const names = yield* location.listKeys.pages({}).pipe(
EffectStream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.Entries ?? []).map((entry) => entry.KeyName),
),
),
);
const hydrated = yield* Effect.forEach(names, (name) => readKey(name), {
concurrency: 10,
});
return hydrated.filter((attrs): attrs is ApiKey["Attributes"] => attrs !== undefined);
}),
read: Effect.fn(function* ({ id, olds, output }) {
const keyName = output?.keyName ?? (yield* createKeyName(id, olds ?? {}));
const state = yield* readKey(keyName);
if (!state) return undefined;
return (yield* hasAlchemyTags(id, state.tags as Tags)) ? state : Unowned(state);
}),
diff: Effect.fn(function* ({ id, news, olds }) {
if (!isResolved(news)) return;
const oldName = yield* createKeyName(id, olds);
const newName = yield* createKeyName(id, news);
if (oldName !== newName) {
return { action: "replace" } as const;
}
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const keyName = output?.keyName ?? (yield* createKeyName(id, news));
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...internalTags, ...news.tags };
const desiredRestrictions: location.ApiKeyRestrictions = {
AllowActions: news.restrictions.allowActions,
AllowResources: news.restrictions.allowResources,
AllowReferers: news.restrictions.allowReferers,
};
let state = yield* readKey(keyName);
if (state === undefined) {
yield* location
.createKey({
KeyName: keyName,
Restrictions: desiredRestrictions,
Description: news.description,
ExpireTime: news.expireTime ? new Date(news.expireTime) : undefined,
NoExpiry: news.expireTime ? undefined : (news.noExpiry ?? true),
Tags: desiredTags,
})
.pipe(Effect.catchTag("ConflictException", () => Effect.void));
state = yield* readKey(keyName);
if (state === undefined) {
return yield* new LocationApiKeyUnexpectedResponse({
message: `failed to read created API key ${keyName}`,
});
}
}
const desiredExpireTime = news.expireTime
? new Date(news.expireTime).toISOString()
: undefined;
if (
state.description !== (news.description ?? undefined) ||
!sameRestrictions(state.restrictions, news.restrictions) ||
(desiredExpireTime !== undefined && state.expireTime !== desiredExpireTime)
) {
yield* location.updateKey({
KeyName: keyName,
Description: news.description,
Restrictions: desiredRestrictions,
ExpireTime: desiredExpireTime ? new Date(desiredExpireTime) : undefined,
NoExpiry: desiredExpireTime ? undefined : true,
// Required to update a key that has been used recently.
ForceUpdate: true,
});
}
const { removed, upsert } = diffTags(state.tags, desiredTags);
if (removed.length > 0) {
yield* location.untagResource({
ResourceArn: state.keyArn,
TagKeys: removed,
});
}
if (upsert.length > 0) {
yield* location.tagResource({
ResourceArn: state.keyArn,
Tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
});
}
yield* session.note(state.keyArn);
const final = yield* readKey(keyName);
if (!final) {
return yield* new LocationApiKeyUnexpectedResponse({
message: `failed to read reconciled API key ${keyName}`,
});
}
return final;
}),
delete: Effect.fn(function* ({ output }) {
yield* location
.deleteKey({ KeyName: output.keyName, ForceDelete: true })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
}),
};
}),
);