Feature: Add Custodial Wallet Persistence and KMS References

[3m1n3nc3]

Description

Add wallet and managed-key-reference models without storing plaintext Stellar secrets.

File Location

learnault-api/prisma/schema.prisma, wallet migration/types, KMS interface, and tests

Design Reference

API Roadmap Phase 1: Add Custodial Wallet Persistence and KMS References.

Dependencies

• Status: Blocked
• Blocked by: Feature: Replace Floating-Point Monetary Storage #123 (Replace Floating-Point Monetary Storage) — done; Feature: Introduce Typed Status Enums and Transition Guards #65 (Introduce Typed Status Enums and Transition Guards) — done; Feature: Add Auditable Data Lifecycle and Archive Policy #124 (Add Auditable Data Lifecycle and Archive Policy) — done
• Blocks: Feature: Implement Idempotent Stellar Wallet Provisioning #90 (Implement Idempotent Stellar Wallet Provisioning) — done; Feature: Add Wallet Status Balance and History API #151 (Add Wallet Status Balance and History API)

Tasks

• Add wallet user, network, custody, public key, status, and timestamps
• Add opaque managed-key/envelope metadata only
• Enforce intended wallet and public-key uniqueness
• Define provisioning, active, failed, export, migrated, and disabled transitions
• Add KMS interface and fake
• Test migration, uniqueness, transitions, redaction, and lifecycle

Acceptance Criteria

• Schema/DTO cannot store plaintext secret
• Uniqueness and transitions are enforced
• KMS references never enter ordinary responses
• Tests pass

Verification Evidence

• Attach schema threat review, migration, and secret-redaction tests

Difficulty

Advanced

[DhruvC-2938]

I’d like to work on this issue by implementing secure wallet persistence and managed-key references without ever storing plaintext Stellar secrets. I’ll update the Prisma schema and migration to support wallet users, networks, custody metadata, public keys, statuses, and lifecycle timestamps, while enforcing wallet and public-key uniqueness.

I’ll also add opaque managed-key/envelope metadata and a KMS interface with a fake implementation for testing. The implementation will enforce valid wallet lifecycle transitions such as provisioning, active, failed, exported, migrated, and disabled, while ensuring KMS references never appear in normal API responses.

Finally, I’ll add tests covering migrations, uniqueness constraints, lifecycle transitions, secret redaction, and the managed-key flow to verify that sensitive key material is never persisted or exposed.

[grantfox-oss]

🦊 GrantFox — @DhruvC-2938 has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #135)
2. Your PR will be reviewed by the learnault maintainers

Good luck! Track your progress on GrantFox.