Passport metadata: arbitrary JSON key-value store on passport, updatable by holder

[leocagli]

Context

Passport issuance creates a minimal record (agentId, status, expiresAt). External integrations often need to store additional structured data on the passport — e.g. which service issued it, what roles the agent has, custom attributes. A metadata field provides this without schema changes.

What to implement

Schema addition

Add metadata: Record<string, unknown> to the passport type. Default: {}.

Route: PATCH /api/protocol/passport/[id]/metadata

Body: { metadata: Record<string, unknown> }

• Merge behavior: deep-merge the provided keys into existing metadata
• To delete a key: set its value to null
• Max keys: 50; max key length: 64 chars; max value size: 1 KB per key

Response

Returns full passport with updated metadata.

Validation

• Reject if total serialized metadata exceeds 32 KB → 413
• Reject keys containing . or $ (reserved for future query operators) → 400

Acceptance criteria

• PATCH with { k: 'v' } → passport.metadata.k === 'v'
• Second PATCH with { k2: 'v2' } merges: both keys present
• PATCH with { k: null } removes key k
• 51 keys → 400 with 'too_many_keys'
• Unit tests: set, merge, delete, limit enforcement

🎁 Evidencia visual = reward extra

• Si tu PR incluye video demo o capturas de pantalla mostrando la funcionalidad pedida funcionando end-to-end, va a ser considerado para rewards de GrantFox en esta issue. No es obligatorio, pero suma mucho para la evaluación.

[retkatmun]

Hi,

I’m a full-stack software engineer with experience building scalable web apps, backend systems,

I’d love to work on this issue. I’ve reviewed the requirements and have a clear implementation plan to deliver a clean, well-tested solution that meets all acceptance criteria and aligns with the project’s standards.

I can start immediately and provide timely updates throughout the implementation.

[Stella112]

Hi, I’d like to work on #113: Passport metadata — arbitrary JSON key-value store on passport, updatable by holder.

I can inspect the existing passport data model and update flow, add a focused metadata storage/update mechanism for holder-controlled key-value data, and include tests or examples for setting and reading metadata.

I’ll keep the PR scoped to passport metadata behavior and avoid unrelated changes.