fix: add AWS tag character restrictions and improve error messages

- Add Unicode character validation to TagKeySchema and TagValueSchema
  per AWS tag restrictions (letters, digits, whitespace, _ . : / = + - @)
- Improve removeTag error when key is inherited from project defaults:
  now hints to use "tag remove-defaults" instead
- Add tests for character restrictions and updated error messages

Author: tejaskash

src/cli/commands/tag/__tests__/action.test.ts

@@ -134,6 +134,14 @@ describe('addTag', () => {
   it('rejects tag value exceeding 256 chars', async () => {
     await expect(addTag('agent:myAgent', 'key', 'v'.repeat(257))).rejects.toThrow('Invalid tag value');
   });
+
+  it('rejects tag key with invalid characters', async () => {
+    await expect(addTag('agent:myAgent', 'key\x00bad', 'value')).rejects.toThrow('Invalid tag key');
+  });
+
+  it('rejects tag value with invalid characters', async () => {
+    await expect(addTag('agent:myAgent', 'key', 'value\x00bad')).rejects.toThrow('Invalid tag value');
+  });
 });
 
 describe('removeTag', () => {
@@ -148,8 +156,8 @@ describe('removeTag', () => {
     expect(written.agents[0].tags).toEqual({ team: 'a' });
   });
 
-  it('throws when key not found', async () => {
-    await expect(removeTag('agent:myAgent', 'nonexistent')).rejects.toThrow('Tag key');
+  it('throws when key not found with hint about defaults', async () => {
+    await expect(removeTag('agent:myAgent', 'nonexistent')).rejects.toThrow('remove-defaults');
   });
 });
 

src/cli/commands/tag/action.ts

@@ -127,7 +127,10 @@ export async function removeTag(resourceRefStr: string, key: string): Promise<{
       throw new Error(`${ref.type} "${ref.name}" not found in project.`);
     }
     if (!resource.tags || !(key in resource.tags)) {
-      throw new Error(`Tag key "${key}" not found on ${ref.type} "${ref.name}".`);
+      throw new Error(
+        `Tag key "${key}" not found on ${ref.type} "${ref.name}". ` +
+          `If this is an inherited project default, use "tag remove-defaults --key ${key}" instead.`
+      );
     }
     delete resource.tags[key];
     if (Object.keys(resource.tags).length === 0) {
@@ -141,7 +144,10 @@ export async function removeTag(resourceRefStr: string, key: string): Promise<{
       throw new Error(`gateway "${ref.name}" not found in MCP spec.`);
     }
     if (!gateway.tags || !(key in gateway.tags)) {
-      throw new Error(`Tag key "${key}" not found on gateway "${ref.name}".`);
+      throw new Error(
+        `Tag key "${key}" not found on gateway "${ref.name}". ` +
+          `If this is an inherited project default, use "tag remove-defaults --key ${key}" instead.`
+      );
     }
     delete gateway.tags[key];
     if (Object.keys(gateway.tags).length === 0) {

src/schema/schemas/__tests__/tags.test.ts

@@ -7,6 +7,7 @@ describe('TagKeySchema', () => {
     expect(TagKeySchema.parse('environment')).toBe('environment');
     expect(TagKeySchema.parse('agentcore:created-by')).toBe('agentcore:created-by');
     expect(TagKeySchema.parse('a'.repeat(128))).toHaveLength(128);
+    expect(TagKeySchema.parse('cost-center_v2')).toBe('cost-center_v2');
   });
 
   it('rejects empty string', () => {
@@ -16,6 +17,20 @@ describe('TagKeySchema', () => {
   it('rejects keys longer than 128 characters', () => {
     expect(() => TagKeySchema.parse('a'.repeat(129))).toThrow();
   });
+
+  it('rejects whitespace-only keys', () => {
+    expect(() => TagKeySchema.parse(' ')).toThrow();
+    expect(() => TagKeySchema.parse('  \t  ')).toThrow();
+  });
+
+  it('rejects aws: prefixed keys', () => {
+    expect(() => TagKeySchema.parse('aws:internal')).toThrow();
+  });
+
+  it('rejects keys with invalid characters', () => {
+    expect(() => TagKeySchema.parse('key\x00null')).toThrow();
+    expect(() => TagKeySchema.parse('key{bracket}')).toThrow();
+  });
 });
 
 describe('TagValueSchema', () => {
@@ -28,6 +43,10 @@ describe('TagValueSchema', () => {
   it('rejects values longer than 256 characters', () => {
     expect(() => TagValueSchema.parse('a'.repeat(257))).toThrow();
   });
+
+  it('rejects values with invalid characters', () => {
+    expect(() => TagValueSchema.parse('val\x00ue')).toThrow();
+  });
 });
 
 describe('TagsSchema', () => {
@@ -43,6 +62,18 @@ describe('TagsSchema', () => {
   it('accepts empty object', () => {
     expect(TagsSchema.parse({})).toEqual({});
   });
+
+  it('rejects more than 50 tags', () => {
+    const tags: Record<string, string> = {};
+    for (let i = 0; i < 51; i++) tags[`key${i}`] = `value${i}`;
+    expect(() => TagsSchema.parse(tags)).toThrow();
+  });
+
+  it('accepts 50 tags', () => {
+    const tags: Record<string, string> = {};
+    for (let i = 0; i < 50; i++) tags[`key${i}`] = `value${i}`;
+    expect(TagsSchema.parse(tags)).toEqual(tags);
+  });
 });
 
 describe('AgentCoreProjectSpecSchema with tags', () => {

src/schema/schemas/primitives/tags.ts

@@ -1,6 +1,26 @@
 import { z } from 'zod';
 
-export const TagKeySchema = z.string().min(1).max(128);
-export const TagValueSchema = z.string().max(256);
-export const TagsSchema = z.record(TagKeySchema, TagValueSchema).optional();
+const TAG_CHAR_PATTERN = /^[\p{L}\p{N}\s_.:/=+\-@]+$/u;
+const TAG_CHAR_MESSAGE = 'can only contain Unicode letters, digits, whitespace, and _ . : / = + - @';
+
+export const TagKeySchema = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/\S/, 'Tag key must contain at least one non-whitespace character')
+  .regex(TAG_CHAR_PATTERN, `Tag key ${TAG_CHAR_MESSAGE}`)
+  .refine(key => !key.startsWith('aws:'), 'Tag keys starting with "aws:" are reserved');
+
+const TAG_VALUE_CHAR_PATTERN = /^[\p{L}\p{N}\s_.:/=+\-@]*$/u;
+
+export const TagValueSchema = z
+  .string()
+  .max(256)
+  .regex(TAG_VALUE_CHAR_PATTERN, `Tag value ${TAG_CHAR_MESSAGE}`);
+
+export const TagsSchema = z
+  .record(TagKeySchema, TagValueSchema)
+  .refine(tags => Object.keys(tags).length <= 50, 'A resource can have at most 50 tags')
+  .optional();
+
 export type Tags = z.infer<typeof TagsSchema>;