fix(trust-graph): validate capability invocation identity

docs/api/trust-graph.yaml

@@ -170,6 +170,8 @@ paths:
       summary: Record a capability invocation
       description: |
         Increments the invocation counter for capability-scoring purposes.
+        Resolves the DID through discovery before writing invocation state.
+        Unknown identities return `404`; discovery outages return `503`.
         Requires API key authentication with the `X-API-Key` header. When
         `TRUST_GRAPH_API_KEYS` is configured, the key must include
         `trust:capability:invoke` or `*`.
@@ -193,6 +195,10 @@ paths:
                   ok:
                     type: boolean
                     example: true
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
         "500":
           $ref: "#/components/responses/InternalError"
 

services/trust-graph/src/routes/trust.ts

@@ -30,7 +30,7 @@ export function createTrustRoutes(db: DbClient, discoveryUrl?: string) {
       c.header('Cache-Control', 'public, max-age=300')
       return c.json(score)
     } catch (error) {
-      const mapped = mapScoreLookupError(error)
+      const mapped = mapTrustLookupError(error)
       return c.json({ error: mapped.message }, mapped.status)
     }
   })
@@ -57,7 +57,7 @@ export function createTrustRoutes(db: DbClient, discoveryUrl?: string) {
       c.header('Cache-Control', 'public, max-age=300')
       return c.json(score)
     } catch (error) {
-      const mapped = mapScoreLookupError(error)
+      const mapped = mapTrustLookupError(error)
       return c.json({ error: mapped.message }, mapped.status)
     }
   })
@@ -70,7 +70,8 @@ export function createTrustRoutes(db: DbClient, discoveryUrl?: string) {
       await trustService.recordCapabilityInvocation(db, did, decodeURIComponent(capabilityId))
       return c.json({ ok: true }, 201)
     } catch (error) {
-      return c.json({ error: 'Internal server error' }, 500)
+      const mapped = mapTrustLookupError(error)
+      return c.json({ error: mapped.message }, mapped.status)
     }
   })
 
@@ -127,7 +128,7 @@ export function createTrustRoutes(db: DbClient, discoveryUrl?: string) {
   return app
 }
 
-function mapScoreLookupError(error: unknown): { status: 404 | 500 | 503; message: string } {
+function mapTrustLookupError(error: unknown): { status: 404 | 500 | 503; message: string } {
   if (error instanceof TrustError) {
     if (error.message.startsWith('Discovery service unavailable')) {
       return { status: 503, message: error.message }

services/trust-graph/src/services/trust-service.ts

@@ -359,6 +359,7 @@ export class TrustService {
    * Record a capability invocation.
    */
   async recordCapabilityInvocation(db: DbClient, did: string, capabilityId: string): Promise<void> {
+    await this.ensureIdentity(db, did)
     return recordCapabilityInvocation(db, did, capabilityId)
   }
 

services/trust-graph/test/routes.test.ts

@@ -189,6 +189,7 @@ describe('HTTP Routes', () => {
       process.env.TRUST_GRAPH_API_KEYS = JSON.stringify([
         { key: 'invoke-key', scopes: ['trust:capability:invoke'] },
       ])
+      mockIdentity(new Uint8Array(32).fill(1))
 
       const app = createTrustRoutes(mockDb)
       const res = await app.request('/v1/trust/did:fides:agent/capability/payments.execute/invoke', {
@@ -200,6 +201,54 @@ describe('HTTP Routes', () => {
       expect(await res.json()).toEqual({ ok: true })
     })
 
+    it('returns 404 for capability invocation when identity is absent from discovery', async () => {
+      process.env.TRUST_GRAPH_API_KEYS = JSON.stringify([
+        { key: 'invoke-key', scopes: ['trust:capability:invoke'] },
+      ])
+      vi.stubGlobal('fetch', vi.fn(() => Promise.resolve(new Response('not found', { status: 404 }))))
+
+      mockDb.select = vi.fn(() => ({
+        from: vi.fn(() => ({
+          where: vi.fn(() => ({
+            limit: vi.fn(() => Promise.resolve([])),
+          })),
+        })),
+      }))
+
+      const app = createTrustRoutes(mockDb, 'http://discovery.test')
+      const res = await app.request('/v1/trust/did:fides:missing/capability/payments.execute/invoke', {
+        method: 'POST',
+        headers: { 'X-API-Key': 'invoke-key' },
+      })
+
+      expect(res.status).toBe(404)
+      expect((await res.json()).error).toContain('Identity not found: did:fides:missing')
+    })
+
+    it('returns 503 for capability invocation when discovery is unavailable', async () => {
+      process.env.TRUST_GRAPH_API_KEYS = JSON.stringify([
+        { key: 'invoke-key', scopes: ['trust:capability:invoke'] },
+      ])
+      vi.stubGlobal('fetch', vi.fn(() => Promise.resolve(new Response('unavailable', { status: 503 }))))
+
+      mockDb.select = vi.fn(() => ({
+        from: vi.fn(() => ({
+          where: vi.fn(() => ({
+            limit: vi.fn(() => Promise.resolve([])),
+          })),
+        })),
+      }))
+
+      const app = createTrustRoutes(mockDb, 'http://discovery.test')
+      const res = await app.request('/v1/trust/did:fides:missing/capability/payments.execute/invoke', {
+        method: 'POST',
+        headers: { 'X-API-Key': 'invoke-key' },
+      })
+
+      expect(res.status).toBe(503)
+      expect((await res.json()).error).toContain('Discovery service unavailable')
+    })
+
     it('allows revocation writes with the revocations write scope', async () => {
       process.env.TRUST_GRAPH_API_KEYS = JSON.stringify([
         { key: 'revocation-key', scopes: ['trust:revocations:write'] },