Normalize unscoped Grant responses

.changeset/calm-scopes-normalize.md

@@ -0,0 +1,6 @@
+---
+"@aep-foundation/agent": patch
+"@aep-foundation/core": minor
+---
+
+Accept missing and null Grant response scopes and normalize them to an empty array.

packages/adapters/express/vitest.config.ts

@@ -3,6 +3,8 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   test: {
     environment: "node",
+    reporters: ["basic"],
+    silent: true,
     coverage: {
       provider: "v8",
       reporter: ["text", "json", "html", "lcov"]

packages/adapters/fastify/vitest.config.ts

@@ -3,6 +3,8 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   test: {
     environment: "node",
+    reporters: ["basic"],
+    silent: true,
     coverage: {
       provider: "v8",
       reporter: ["text", "json", "html", "lcov"]

packages/adapters/hono/vitest.config.ts

@@ -3,6 +3,8 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   test: {
     environment: "node",
+    reporters: ["basic"],
+    silent: true,
     coverage: {
       provider: "v8",
       reporter: ["text", "json", "html", "lcov"]

packages/adapters/next/vitest.config.ts

@@ -3,6 +3,8 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   test: {
     environment: "node",
+    reporters: ["basic"],
+    silent: true,
     coverage: {
       provider: "v8",
       reporter: ["text", "json", "html", "lcov"]

packages/agent/test/index.test.ts

@@ -844,6 +844,32 @@ describe("@aep-foundation/agent command clients", () => {
     });
   });
 
+  it("normalizes null API-key Grant scopes", async () => {
+    const result = await withFetch(
+      () =>
+        jsonResponsePromise({
+          api_key: "api-key",
+          credential_id: "cred_123",
+          expires_at: "2026-05-28T12:00:00Z",
+          header: "X-API-Key",
+          scopes: null
+        }),
+      () =>
+        grantService({
+          clientAssertion: "jwt.grant",
+          grantType: "api-key",
+          idempotencyKey: "9f8a4d2e-1c3b-4f5e-8b7a-grant0000001",
+          inspect: inspectResult(),
+          serviceUrl: "https://api.example.com"
+        })
+    );
+
+    expect(result.body).toMatchObject({
+      header: "X-API-Key",
+      scopes: []
+    });
+  });
+
   it("posts Revoke requests using exactly one selector", async () => {
     const calls: Array<{ input: URL | string; init?: RequestInit }> = [];
     const fetch = (input: URL | string, init?: RequestInit) => {

packages/agent/vitest.config.ts

@@ -3,6 +3,8 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   test: {
     environment: "node",
+    reporters: ["basic"],
+    silent: true,
     coverage: {
       provider: "v8",
       reporter: ["text", "json", "html", "lcov"]

packages/conformance/fixtures/aep-specs/schemas/api-key-grant-response.schema.json

@@ -3,7 +3,7 @@
   "$id": "https://www.aep.foundation/schemas/api-key-grant-response.schema.json",
   "title": "AEP API-key Grant Response",
   "type": "object",
-  "required": ["api_key", "credential_id", "expires_at", "header", "scopes"],
+  "required": ["api_key", "credential_id", "expires_at", "header"],
   "additionalProperties": true,
   "properties": {
     "api_key": {
@@ -23,7 +23,7 @@
       "minLength": 1
     },
     "scopes": {
-      "type": "array",
+      "type": ["array", "null"],
       "items": {
         "type": "string"
       }

packages/conformance/fixtures/aep-specs/schemas/basic-grant-response.schema.json

@@ -3,7 +3,7 @@
   "$id": "https://www.aep.foundation/schemas/basic-grant-response.schema.json",
   "title": "AEP Basic Grant Response",
   "type": "object",
-  "required": ["credential_id", "expires_at", "password", "scopes", "username"],
+  "required": ["credential_id", "expires_at", "password", "username"],
   "additionalProperties": true,
   "properties": {
     "credential_id": {
@@ -23,7 +23,7 @@
       "minLength": 1
     },
     "scopes": {
-      "type": "array",
+      "type": ["array", "null"],
       "items": {
         "type": "string"
       }

packages/conformance/fixtures/aep-specs/schemas/oauth-bearer-grant-response.schema.json

@@ -3,7 +3,7 @@
   "$id": "https://www.aep.foundation/schemas/oauth-bearer-grant-response.schema.json",
   "title": "AEP OAuth Bearer Grant Response",
   "type": "object",
-  "required": ["access_token", "credential_id", "expires_at", "scopes", "token_type"],
+  "required": ["access_token", "credential_id", "expires_at", "token_type"],
   "additionalProperties": true,
   "properties": {
     "access_token": {
@@ -19,7 +19,7 @@
       "format": "date-time"
     },
     "scopes": {
-      "type": "array",
+      "type": ["array", "null"],
       "items": {
         "type": "string"
       }

packages/conformance/fixtures/aep-specs/test-vectors/credentials/api-key/grant-response.json

@@ -1,20 +1,19 @@
 {
   "id": "grant-response",
   "title": "API-key Grant response",
-  "description": "A successful API-key session-credential response.",
+  "description": "A successful API-key session-credential response with no scope-limited authorization.",
   "drafts": ["draft-kavian-aep-api-key-session-credential-02"],
   "category": "credentials/api-key",
   "applies_to": ["agent", "service"],
   "profile": "api-key",
   "input": {
-    "grant_type": "api-key",
-    "requested_scopes": ["read"]
+    "grant_type": "api-key"
   },
   "expected": {
     "api_key": "aep_live_7Jm5Example",
     "credential_id": "key_01HZY8W7Q2F8J7D3P9G9Z1N6TT",
     "expires_at": "2026-12-01T00:00:00Z",
     "header": "x-api-key",
-    "scopes": ["read"]
+    "scopes": null
   }
 }

packages/conformance/fixtures/aep-specs/test-vectors/credentials/basic/grant-response.json

@@ -1,21 +1,19 @@
 {
   "id": "grant-response",
   "title": "Basic Grant response",
-  "description": "A successful HTTP Basic session-credential response.",
+  "description": "A successful HTTP Basic session-credential response that omits scope-limited authorization.",
   "drafts": ["draft-kavian-aep-basic-session-credential-02"],
   "category": "credentials/basic",
   "applies_to": ["agent", "service"],
   "profile": "basic",
   "input": {
-    "grant_type": "basic",
-    "requested_scopes": ["read"]
+    "grant_type": "basic"
   },
   "expected": {
     "credential_id": "bas_01HZY8W7Q2F8J7D3P9G9Z1N6TT",
     "expires_at": "2026-12-01T00:00:00Z",
     "password": "s3cr3tExample",
     "realm": "api.example.com",
-    "scopes": ["read"],
     "username": "aep_agent_abc123"
   }
 }

packages/conformance/vitest.config.ts

@@ -3,6 +3,8 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   test: {
     environment: "node",
+    reporters: ["basic"],
+    silent: true,
     coverage: {
       provider: "v8",
       reporter: ["text", "json", "html", "lcov"]

packages/core/src/protocol.ts

@@ -236,9 +236,12 @@ export function validateOAuthBearerGrantResponse(
   requireString(value, "credential_id", issues, { minLength: 1 });
   requireString(value, "expires_at", issues, { minLength: 1 });
   requireDateTime(value["expires_at"], "$.expires_at", issues);
-  requireStringArray(value["scopes"], "$.scopes", issues);
+  optionalNullableStringArray(value["scopes"], "$.scopes", issues);
   requireString(value, "token_type", issues, { allowedValues: new Set(["Bearer"]) });
-  return result(value as OAuthBearerGrantResponse, issues);
+  return result(
+    { ...(value as OAuthBearerGrantResponse), scopes: normalizedScopes(value["scopes"]) },
+    issues
+  );
 }
 
 export function validateApiKeyGrantResponse(value: unknown): ValidationResult<ApiKeyGrantResponse> {
@@ -252,8 +255,11 @@ export function validateApiKeyGrantResponse(value: unknown): ValidationResult<Ap
   requireString(value, "expires_at", issues, { minLength: 1 });
   requireDateTime(value["expires_at"], "$.expires_at", issues);
   requireString(value, "header", issues, { minLength: 1 });
-  requireStringArray(value["scopes"], "$.scopes", issues);
-  return result(value as ApiKeyGrantResponse, issues);
+  optionalNullableStringArray(value["scopes"], "$.scopes", issues);
+  return result(
+    { ...(value as ApiKeyGrantResponse), scopes: normalizedScopes(value["scopes"]) },
+    issues
+  );
 }
 
 export function validateBasicGrantResponse(value: unknown): ValidationResult<BasicGrantResponse> {
@@ -267,9 +273,12 @@ export function validateBasicGrantResponse(value: unknown): ValidationResult<Bas
   requireDateTime(value["expires_at"], "$.expires_at", issues);
   requireString(value, "password", issues, { minLength: 1 });
   optionalString(value["realm"], "$.realm", issues, { minLength: 1 });
-  requireStringArray(value["scopes"], "$.scopes", issues);
+  optionalNullableStringArray(value["scopes"], "$.scopes", issues);
   requireString(value, "username", issues, { minLength: 1 });
-  return result(value as BasicGrantResponse, issues);
+  return result(
+    { ...(value as BasicGrantResponse), scopes: normalizedScopes(value["scopes"]) },
+    issues
+  );
 }
 
 export function validateBuiltInGrantResponse(
@@ -412,6 +421,24 @@ function optionalStringArray(value: unknown, path: string, issues: ValidationIss
   requireStringArray(value, path, issues);
 }
 
+function optionalNullableStringArray(
+  value: unknown,
+  path: string,
+  issues: ValidationIssue[]
+): void {
+  if (value === undefined || value === null) {
+    return;
+  }
+
+  requireStringArray(value, path, issues);
+}
+
+function normalizedScopes(value: unknown): string[] {
+  return Array.isArray(value) && value.every((scope) => typeof scope === "string")
+    ? [...value]
+    : [];
+}
+
 function optionalNonEmptyStringArray(
   value: unknown,
   path: string,

packages/core/test/index.test.ts

@@ -627,24 +627,35 @@ describe("Protocol message validation", () => {
         credential_id: "cred_123",
         expires_at: "2026-05-28T12:00:00Z",
         header: "X-API-Key",
-        scopes: []
+        scopes: null
       })
     ).toMatchObject({
-      header: "X-API-Key"
+      header: "X-API-Key",
+      scopes: []
     });
 
     expect(
       parseBuiltInGrantResponse(AEP_GRANT_TYPE_BASIC, {
         credential_id: "cred_123",
         expires_at: "2026-05-28T12:00:00Z",
         password: "password",
-        scopes: [],
         username: "username"
       })
     ).toMatchObject({
+      scopes: [],
       username: "username"
     });
 
+    expect(() =>
+      parseBuiltInGrantResponse(AEP_GRANT_TYPE_API_KEY, {
+        api_key: "api-key",
+        credential_id: "cred_123",
+        expires_at: "2026-05-28T12:00:00Z",
+        header: "X-API-Key",
+        scopes: [null]
+      })
+    ).toThrow(AepValidationError);
+
     expect(() => parseBuiltInGrantResponse("custom", {})).toThrow(AepValidationError);
   });
 });

packages/core/vitest.config.ts

@@ -3,6 +3,8 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   test: {
     environment: "node",
+    reporters: ["basic"],
+    silent: true,
     coverage: {
       provider: "v8",
       reporter: ["text", "json", "html", "lcov"]

packages/extensions/service-policy/vitest.config.ts

@@ -3,6 +3,8 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   test: {
     environment: "node",
+    reporters: ["basic"],
+    silent: true,
     coverage: {
       provider: "v8",
       reporter: ["text", "json", "html", "lcov"]

packages/platform/vitest.config.ts

@@ -3,6 +3,8 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   test: {
     environment: "node",
+    reporters: ["basic"],
+    silent: true,
     coverage: {
       provider: "v8",
       reporter: ["text", "json", "html", "lcov"]

packages/service/vitest.config.ts

@@ -3,6 +3,8 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   test: {
     environment: "node",
+    reporters: ["basic"],
+    silent: true,
     coverage: {
       provider: "v8",
       reporter: ["text", "json", "html", "lcov"]