fix(resources): resolve CloudFormation-origin API Gateway & Cognito resources

Opening an API Gateway or Cognito resource from a Stack view threw
"Cannot resolve resource type for ARN". The live `list` path and the
CloudFormation path synthesize ARNs differently, and these multi-type
services rely on the engine's "self" describe path, which requires the
synthesized ARN to string-equal the live `id` — but the CFN template
always injects an account segment the live `id` omits.

Fix the 4 types CloudFormation can support by re-encoding the
discriminating token via cfnResourceName and adding a direct describe()
(also removes the per-click re-list for the API Gateway types):
  - cognito userpool, apigateway restapi/apikey/usageplan

Drop the cfn mapping for the 4 it cannot: their PhysicalResourceId is
the leaf id only, without the parent pool/api id every describe API
needs, so CFN-origin resolution is impossible. They are now skipped and
logged in stack views (as the states definition does) rather than
throwing on click; live resources still resolve.
  - cognito userpoolclient/userpoolgroup, apigateway stage/authorizer

Add cfnRoundTrip.test.ts covering synthesize -> resolve -> describe for
the 4 fixed types and asserting the 4 dropped types are unmapped.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: peter-smith-phd

src/platforms/aws/services/definitions/apigateway.ts

@@ -1,9 +1,12 @@
 import {
 	APIGatewayClient,
+	GetApiKeyCommand,
 	GetApiKeysCommand,
 	GetAuthorizersCommand,
+	GetRestApiCommand,
 	GetRestApisCommand,
 	GetStagesCommand,
+	GetUsagePlanCommand,
 	GetUsagePlansCommand,
 } from "@aws-sdk/client-api-gateway";
 import type {
@@ -14,6 +17,7 @@ import type {
 	UsagePlan,
 } from "@aws-sdk/client-api-gateway";
 
+import type ARN from "../../models/arnModel.ts";
 import { defineService } from "../declarative/types.ts";
 import { FieldType } from "../serviceProvider.ts";
 
@@ -39,6 +43,13 @@ export const apiGatewayDefinition = defineService<APIGatewayClient>({
 			plural: "REST APIs",
 			metamodelOp: "getRestApis",
 			cfn: "AWS::ApiGateway::RestApi",
+			/* CloudFormation's PhysicalResourceId is the REST API id; re-encode it as
+			 * the `/restapis/<id>` path the live `id` uses so a stack resource
+			 * resolves to this type and `describe` can read it back. */
+			cfnResourceName: (summary) =>
+				summary.PhysicalResourceId
+					? `/restapis/${summary.PhysicalResourceId}`
+					: undefined,
 			matchArn: (identifier) =>
 				identifier.arn.includes("/restapis/") &&
 				!identifier.arn.includes("/stages/") &&
@@ -55,6 +66,12 @@ export const apiGatewayDefinition = defineService<APIGatewayClient>({
 			},
 			id: (api: RestApi, ctx) =>
 				`arn:aws:apigateway:${ctx.region}::/restapis/${api.id}`,
+			/* Fetch directly by id (works for both live and CloudFormation ARNs)
+			 * rather than re-listing every API. */
+			describe: (client, identifier) =>
+				client.send(
+					new GetRestApiCommand({ restApiId: pathId(identifier, "restapis") }),
+				),
 			detail: [
 				{ label: "Name", path: "name", type: FieldType.NAME },
 				{ label: "ID", path: "id", type: FieldType.NAME },
@@ -72,7 +89,10 @@ export const apiGatewayDefinition = defineService<APIGatewayClient>({
 			singular: "Stage",
 			plural: "Stages",
 			metamodelOp: "getStages",
-			cfn: "AWS::ApiGateway::Stage",
+			/* No `cfn` mapping: CloudFormation's PhysicalResourceId for a stage is the
+			 * stage name alone, without the REST API id needed to fetch it. Live
+			 * stages (whose ARN carries the api id) still resolve; CloudFormation
+			 * stages are skipped in stack views. */
 			matchArn: (identifier) => identifier.arn.includes("/stages/"),
 			list: async (client): Promise<StageWithApi[]> => {
 				const apiIds = await listRestApiIds(client);
@@ -104,6 +124,12 @@ export const apiGatewayDefinition = defineService<APIGatewayClient>({
 			plural: "API Keys",
 			metamodelOp: "getApiKeys",
 			cfn: "AWS::ApiGateway::ApiKey",
+			/* CloudFormation's PhysicalResourceId is the API key id; re-encode it as
+			 * the `/apikeys/<id>` path the live `id` uses. */
+			cfnResourceName: (summary) =>
+				summary.PhysicalResourceId
+					? `/apikeys/${summary.PhysicalResourceId}`
+					: undefined,
 			matchArn: (identifier) => identifier.arn.includes("/apikeys/"),
 			list: async (client): Promise<ApiKey[]> => {
 				const keys: ApiKey[] = [];
@@ -117,6 +143,11 @@ export const apiGatewayDefinition = defineService<APIGatewayClient>({
 			},
 			id: (key: ApiKey, ctx) =>
 				`arn:aws:apigateway:${ctx.region}::/apikeys/${key.id}`,
+			/* Fetch by id (no `includeValue`, so the key secret is never read). */
+			describe: (client, identifier) =>
+				client.send(
+					new GetApiKeyCommand({ apiKey: pathId(identifier, "apikeys") }),
+				),
 			detail: [
 				{ label: "Name", path: "name", type: FieldType.NAME },
 				{ label: "ID", path: "id", type: FieldType.NAME },
@@ -134,6 +165,12 @@ export const apiGatewayDefinition = defineService<APIGatewayClient>({
 			plural: "Usage Plans",
 			metamodelOp: "getUsagePlans",
 			cfn: "AWS::ApiGateway::UsagePlan",
+			/* CloudFormation's PhysicalResourceId is the usage plan id; re-encode it
+			 * as the `/usageplans/<id>` path the live `id` uses. */
+			cfnResourceName: (summary) =>
+				summary.PhysicalResourceId
+					? `/usageplans/${summary.PhysicalResourceId}`
+					: undefined,
 			matchArn: (identifier) => identifier.arn.includes("/usageplans/"),
 			list: async (client): Promise<UsagePlan[]> => {
 				const plans: UsagePlan[] = [];
@@ -147,6 +184,13 @@ export const apiGatewayDefinition = defineService<APIGatewayClient>({
 			},
 			id: (plan: UsagePlan, ctx) =>
 				`arn:aws:apigateway:${ctx.region}::/usageplans/${plan.id}`,
+			/* Fetch directly by id rather than re-listing every usage plan. */
+			describe: (client, identifier) =>
+				client.send(
+					new GetUsagePlanCommand({
+						usagePlanId: pathId(identifier, "usageplans"),
+					}),
+				),
 			detail: [
 				{ label: "Name", path: "name", type: FieldType.NAME },
 				{ label: "ID", path: "id", type: FieldType.NAME },
@@ -162,7 +206,9 @@ export const apiGatewayDefinition = defineService<APIGatewayClient>({
 			singular: "Authorizer",
 			plural: "Authorizers",
 			metamodelOp: "getAuthorizers",
-			cfn: "AWS::ApiGateway::Authorizer",
+			/* No `cfn` mapping: CloudFormation's PhysicalResourceId for an authorizer
+			 * is the authorizer id alone, without the REST API id needed to fetch it.
+			 * Live authorizers still resolve; CloudFormation authorizers are skipped. */
 			matchArn: (identifier) => identifier.arn.includes("/authorizers/"),
 			list: async (client): Promise<AuthorizerWithApi[]> => {
 				const apiIds = await listRestApiIds(client);
@@ -197,6 +243,19 @@ export const apiGatewayDefinition = defineService<APIGatewayClient>({
 	},
 });
 
+/**
+ * Extract the id following a path collection in an API Gateway ARN, e.g. the
+ * `<id>` in `/restapis/<id>` or `/apikeys/<id>`. Works for both the live
+ * (account-less) ARN and the CloudFormation-synthesized one, since both encode
+ * the same `/collection/<id>` path in the resource portion. Returns `""` when
+ * the collection segment is absent.
+ */
+function pathId(identifier: ARN, collection: string): string {
+	const parts = identifier.resourceId.split("/").filter(Boolean);
+	const index = parts.indexOf(collection);
+	return index >= 0 ? (parts[index + 1] ?? "") : "";
+}
+
 /** Enumerate every REST API id (for resource types scoped to an API). */
 async function listRestApiIds(client: APIGatewayClient): Promise<string[]> {
 	const ids: string[] = [];

src/platforms/aws/services/definitions/cognito-idp.ts

@@ -33,6 +33,13 @@ export const cognitoIdpDefinition =
 				singular: "User Pool",
 				plural: "User Pools",
 				cfn: "AWS::Cognito::UserPool",
+				/* CloudFormation's PhysicalResourceId for a user pool is the pool id;
+				 * re-encode it as the `userpool/<id>` token the live `id` uses so a
+				 * stack resource resolves to this type and `describe` can read it. */
+				cfnResourceName: (summary) =>
+					summary.PhysicalResourceId
+						? `userpool/${summary.PhysicalResourceId}`
+						: undefined,
 				matchArn: (identifier) => identifier.arn.includes(":userpool/"),
 				list: async (client): Promise<UserPoolDescriptionType[]> => {
 					const pools: UserPoolDescriptionType[] = [];
@@ -81,7 +88,11 @@ export const cognitoIdpDefinition =
 			userpoolclient: {
 				singular: "User Pool Client",
 				plural: "User Pool Clients",
-				cfn: "AWS::Cognito::UserPoolClient",
+				/* No `cfn` mapping: CloudFormation's PhysicalResourceId for an app
+				 * client is the client id alone, without the user pool id that every
+				 * Cognito API needs to describe it — so a stack-origin client can't be
+				 * resolved. Live resources (which carry the pool id in their ARN) still
+				 * work; CloudFormation app clients are skipped in stack views. */
 				matchArn: (identifier) => identifier.arn.includes(":userpoolclient/"),
 				list: async (client): Promise<UserPoolClientDescription[]> => {
 					const poolIds = await listUserPoolIds(client);
@@ -113,7 +124,9 @@ export const cognitoIdpDefinition =
 			userpoolgroup: {
 				singular: "User Pool Group",
 				plural: "User Pool Groups",
-				cfn: "AWS::Cognito::UserPoolGroup",
+				/* No `cfn` mapping: CloudFormation's PhysicalResourceId for a group is
+				 * the group name alone, without the user pool id needed to describe it.
+				 * Live resources still resolve; CloudFormation groups are skipped. */
 				matchArn: (identifier) => identifier.arn.includes(":userpoolgroup/"),
 				list: async (client): Promise<GroupType[]> => {
 					const poolIds = await listUserPoolIds(client);

src/test/services/cfnRoundTrip.test.ts

@@ -0,0 +1,183 @@
+import assert from "node:assert";
+
+import type { StackResourceSummary } from "@aws-sdk/client-cloudformation";
+
+import ARN from "../../platforms/aws/models/arnModel.ts";
+import { DeclarativeServiceProvider } from "../../platforms/aws/services/declarative/engine.ts";
+import type { ServiceDefinition } from "../../platforms/aws/services/declarative/types.ts";
+import { apiGatewayDefinition } from "../../platforms/aws/services/definitions/apigateway.ts";
+import { cognitoIdpDefinition } from "../../platforms/aws/services/definitions/cognito-idp.ts";
+
+/**
+ * Round-trip tests for CloudFormation-origin resources: synthesize the ARN
+ * exactly as `CfnStackModel` does (`getArnResourceNameForCloudFormationResource`
+ * → `arn:aws:<service>:<region>:<account>:<resourceName>`), then `describeResource`
+ * that ARN and assert it resolves to the right type and fetches by the right id.
+ *
+ * This is the gap that let API Gateway and Cognito resources throw when opened
+ * from a stack view: the live `id` and the CloudFormation ARN are built by two
+ * different code paths, so a type whose `cfnResourceName` doesn't re-encode the
+ * discriminating token is unresolvable. The dropped types assert the honest
+ * fallback — they have no `cfn` mapping (CloudFormation can't supply the parent
+ * id they need), so the stack model skips them rather than showing a broken row.
+ */
+
+type Handlers = Record<string, (input: Record<string, unknown>) => unknown>;
+function fakeClient(handlers: Handlers): { send: (command: unknown) => unknown } {
+	return {
+		send: (command: unknown) => {
+			const name = (command as { constructor: { name: string } }).constructor
+				.name;
+			const handler = handlers[name];
+			if (!handler) {
+				throw new Error(`Unexpected SDK command: ${name}`);
+			}
+			const input = (command as { input?: Record<string, unknown> }).input ?? {};
+			return Promise.resolve(handler(input));
+		},
+	};
+}
+
+function providerWith<TClient>(
+	definition: ServiceDefinition<TClient>,
+	client: unknown,
+) {
+	return new DeclarativeServiceProvider({
+		...definition,
+		client: () => client as TClient,
+	});
+}
+
+function summary(partial: Partial<StackResourceSummary>): StackResourceSummary {
+	return partial as StackResourceSummary;
+}
+
+/** Build the ARN a stack resource would get, mirroring `CfnStackModel`. */
+function cfnArn<TClient>(
+	provider: DeclarativeServiceProvider<TClient>,
+	stackResource: StackResourceSummary,
+): { resourceType: string; arn: ARN } {
+	const { resourceType, resourceName } =
+		provider.getArnResourceNameForCloudFormationResource(stackResource);
+	const arn = `arn:aws:${provider.getId()}:us-east-1:000000000000:${resourceName}`;
+	return { resourceType, arn: new ARN(arn) };
+}
+
+suite("CloudFormation round-trip: API Gateway", () => {
+	let seen: Record<string, string> = {};
+	const client = fakeClient({
+		GetRestApiCommand: (input) => {
+			seen.restApiId = input.restApiId as string;
+			return { id: input.restApiId, name: "My API" };
+		},
+		GetApiKeyCommand: (input) => {
+			seen.apiKey = input.apiKey as string;
+			return { id: input.apiKey, name: "My Key", enabled: true };
+		},
+		GetUsagePlanCommand: (input) => {
+			seen.usagePlanId = input.usagePlanId as string;
+			return { id: input.usagePlanId, name: "My Plan" };
+		},
+	});
+	const provider = providerWith(apiGatewayDefinition, client);
+
+	test("REST API resolves and describes by id", async () => {
+		seen = {};
+		const { resourceType, arn } = cfnArn(
+			provider,
+			summary({
+				ResourceType: "AWS::ApiGateway::RestApi",
+				PhysicalResourceId: "abc123",
+			}),
+		);
+		assert.strictEqual(resourceType, "restapi");
+		const fields = await provider.describeResource("default", arn);
+		assert.strictEqual(seen.restApiId, "abc123");
+		assert.ok(fields.some((f) => f.field === "Name" && f.value === "My API"));
+	});
+
+	test("API Key resolves and describes by id", async () => {
+		seen = {};
+		const { resourceType, arn } = cfnArn(
+			provider,
+			summary({
+				ResourceType: "AWS::ApiGateway::ApiKey",
+				PhysicalResourceId: "key123",
+			}),
+		);
+		assert.strictEqual(resourceType, "apikey");
+		await provider.describeResource("default", arn);
+		assert.strictEqual(seen.apiKey, "key123");
+	});
+
+	test("Usage Plan resolves and describes by id", async () => {
+		seen = {};
+		const { resourceType, arn } = cfnArn(
+			provider,
+			summary({
+				ResourceType: "AWS::ApiGateway::UsagePlan",
+				PhysicalResourceId: "plan123",
+			}),
+		);
+		assert.strictEqual(resourceType, "usageplan");
+		await provider.describeResource("default", arn);
+		assert.strictEqual(seen.usagePlanId, "plan123");
+	});
+
+	test("Stage and Authorizer have no CloudFormation mapping", () => {
+		for (const ResourceType of [
+			"AWS::ApiGateway::Stage",
+			"AWS::ApiGateway::Authorizer",
+		]) {
+			assert.throws(
+				() =>
+					provider.getArnResourceNameForCloudFormationResource(
+						summary({ ResourceType, PhysicalResourceId: "x" }),
+					),
+				/Unsupported resource type/,
+				`expected ${ResourceType} to be unmapped`,
+			);
+		}
+	});
+});
+
+suite("CloudFormation round-trip: Cognito", () => {
+	let seenUserPoolId: string | undefined;
+	const client = fakeClient({
+		DescribeUserPoolCommand: (input) => {
+			seenUserPoolId = input.UserPoolId as string;
+			return { UserPool: { Name: "my-pool", Id: input.UserPoolId } };
+		},
+	});
+	const provider = providerWith(cognitoIdpDefinition, client);
+
+	test("User Pool resolves and describes by id", async () => {
+		const { resourceType, arn } = cfnArn(
+			provider,
+			summary({
+				ResourceType: "AWS::Cognito::UserPool",
+				PhysicalResourceId: "us-east-1_AbC123",
+			}),
+		);
+		assert.strictEqual(resourceType, "userpool");
+		const fields = await provider.describeResource("default", arn);
+		assert.strictEqual(seenUserPoolId, "us-east-1_AbC123");
+		assert.ok(fields.some((f) => f.field === "Name" && f.value === "my-pool"));
+	});
+
+	test("User Pool Client and Group have no CloudFormation mapping", () => {
+		for (const ResourceType of [
+			"AWS::Cognito::UserPoolClient",
+			"AWS::Cognito::UserPoolGroup",
+		]) {
+			assert.throws(
+				() =>
+					provider.getArnResourceNameForCloudFormationResource(
+						summary({ ResourceType, PhysicalResourceId: "x" }),
+					),
+				/Unsupported resource type/,
+				`expected ${ResourceType} to be unmapped`,
+			);
+		}
+	});
+});