Implement API Key Authentication Guard with Scoped Permissions

[Cjay-Cyber-2]

Description — what to implement and the why/impact.

Implement an API key authentication guard and decorator supporting granular scope-based permissions for developer and agent API access.

Context & Requirements — background, constraints, design references, edge cases;

Autonomous agents and developers interact with Astroid API using long-lived API keys. The authentication guard must validate hashed keys against the database, attach tenant and agent context to the request, and enforce required permission scopes (e.g., transactions:write, policies:read).

Acceptance Criteria — a checklist of specific, testable conditions that define "done".

• API key schema and repository methods implemented in database layer.
• NestJS Guard ApiKeyGuard and decorator @RequireScopes(...) created.
• Proper HTTP 401 (Unauthorized) and 403 (Forbidden) responses for invalid keys or missing scopes.
• Unit tests covering valid keys, expired keys, and scope checks.

Implementation Guidance — likely files/modules to touch and a suggested approach.

• Likely files: src/modules/auth/, src/common/guards/api-key.guard.ts, prisma/schema.prisma.
• Store API keys hashed using SHA-256 rather than in plaintext.

Testing & Validation — how the contributor should prove it works.

• Run npm test ensuring all auth guard tests pass successfully.
• Verify type safety with npm run typecheck.

Submission Guidelines — must open a PR that includes "Closes #"; assignment is required before starting.

---

Wave complexity: Medium

[johnmic0132]

@johnmic0132 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi Maintainer! I’d love to take on this issue and get it done efficiently. Kindly assign it to me.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @johnmic0132 to this issue.

[Netty-kun]

@Netty-kun has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi maintainer, I have read and understood the issue requirements and checked the necessary documentation. I’m confident I can work on this task effectively and deliver a proper solution.
Happy to discuss the approach first if that's useful before I start.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Netty-kun to this issue.

[LiegeFx]

@LiegeFx has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I can fix it, kindly assign it to me. This is where my skill set lies.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @LiegeFx to this issue.

[akinerin]

@akinerin has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I would love to work on this issue, please assign it to me

ℹ️ Repo Maintainers: To accept this application, review their application or assign @akinerin to this issue.

[drips-wave]

Congratulations, @akinerin! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @akinerin: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊