feat(token-manager): add structured endpoint acquisition

[Samarth Mukhija (Samearth17)]

Summary

• add typed endpoint acquisition contracts and TokenManagerClient.acquireEndpoint()
• expose POST /api/v1/endpoints/acquire as a typed projection over existing valid azure-ai-foundry keys
• migrate the API's Foundry client acquisition away from consumer-side JSON parsing
• preserve the existing raw key acquisition path for backward compatibility
• document the storage decision and endpoint API

Validation

• vitest focused endpoint/client/consumer tests: 26 passed
• broader affected token-manager and LLM tests: 100 passed
• TypeScript builds: shared, telemetry, token-manager, and api
• git diff --check

The repository's package lint scripts currently invoke eslint, but no ESLint package or configuration is declared in the checked-in workspace, so that command could not start locally (eslint: command not found). CI remains the authoritative lint check.

This contribution was developed with AI assistance and reviewed/tested by the contributor.

Closes #912

[Copilot]

🟡 Changes recommended

Request and response boundary validation can currently produce unintended 500 or TypeError failures.

2 open findings

• Handle missing or null request body during validation · New
• Guard against null response before accessing endpoint · New

What changed in this PR

Adds typed Azure AI Foundry endpoint acquisition while preserving raw key compatibility.

Changes:

• Adds shared endpoint contracts and client support.
• Exposes and tests structured endpoint acquisition.
• Migrates the API consumer and updates architecture documentation.

File	Description
packages/​shared/​src/​token-manager/​types.ts	Defines endpoint contracts.
packages/​shared/​src/​token-manager/​client.ts	Adds acquireEndpoint().
packages/​shared/​src/​token-manager/​client.test.ts	Tests client behavior.
apps/​token-manager/​src/​routes.ts	Adds endpoint acquisition route.
apps/​token-manager/​src/​endpoint-routes.test.ts	Tests route behavior and compatibility.
apps/​api/​src/​llm-token.ts	Consumes structured credentials.
apps/​api/​src/​llm-token.test.ts	Tests Foundry client acquisition.
docs/​architecture/​token-manager.md	Documents endpoint storage and API.

🧠 Review effort: Balanced

---

Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.

[Samarth Mukhija (Samearth17)]

Implemented both Copilot boundary-validation findings and merged current upstream/main normally.

• Added missing/undefined and null request-body regression coverage.
• Validated endpoint JSON as unknown and as a non-null object before property access.
• Added null response coverage.

Validation:

• Vitest: 29 passed across the three affected test files
• Dependency-ordered TypeScript builds: token-manager and API graphs passed
• License headers: 957 files passed
• git diff --check upstream/main...HEAD: passed

The repository currently declares package lint scripts but does not declare/install ESLint, so local lint could not run (eslint: command not found). No force-push was used. Head: fdcea21.

[Samarth Mukhija (Samearth17)]

Merged current upstream/main normally and resolved the single apps/token-manager/src/routes.ts conflict by preserving both upstream key-type validation (KEY_TYPES / isKeyType) and this PR's endpoint parser. The PR diff against current main remains limited to the intended eight endpoint files.

Validation on head 99d916e69dab3ab694ef20ef709d875c9bfbd91a:

• focused Vitest suite: 29 passed across 3 files
• dependency-ordered token-manager... build: passed
• dependency-ordered api... build: passed
• license headers: 961 files passed
• git diff --check: passed

The package lint scripts still cannot run because the repository does not declare/install an eslint binary (eslint: command not found), matching the prior-head limitation. No history was rewritten; this was a normal merge and push.