feat: implement API key extraction helper and authorization scope man…

[muhsar27]

Summary

Implements secure cryptographic API key authentication and fine-grained permission scope authorization with @RequiredScopes for programmatic developer and autonomous AI agent access to the Astroid API.

Type of change

• Bug fix
• New feature
• Refactor / cleanup
• Documentation
• CI / tooling

Related issue

Closes #121

Why this change is needed

Autonomous AI agents and external developer integrations require programmatic, non-interactive authentication without relying on browser sessions or temporary user tokens. Storing plain secrets in the database presents security vulnerabilities, while lacking granular permission scopes prevents principle-of-least-privilege access.

This implementation addresses these requirements by:

1. Validating and securely looking up API keys using SHA-256 cryptographic hashes against PostgreSQL via Prisma.
2. Checking expiration and revocation status while updating key usage timestamps (lastUsedAt).
3. Parsing keys seamlessly across multiple header schemes including x-api-key, Authorization: ApiKey <key>, and Authorization: Bearer ast_... / Bearer ak_....
4. Enforcing fine-grained permission scopes via ScopesGuard with the @RequiredScopes decorator, supporting exact matches (transactions:write), resource wildcards (transactions:*), and global privileges (*, admin).

Checklist

• npm run build passes
• npm test passes
• npm run lint passes
• npm run typecheck passes
• No secrets added to tracked files
• PR description explains the why, not just the what

[drips-wave]

@muhsar27 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[mergekeeper]

MergeKeeper review

Scope: in scope for linked issue #121.
Verdict: clean

The pull request correctly implements the requested API key authentication helper updates, required scope aliases, and corresponding unit tests matching issue #121.

Reviewed commit: 0d90ad46457b5ed2907e4bc0271b3a2c858bf418.
CI and merge eligibility are checked separately.

[mergekeeper]

Approved

The pull request correctly implements the requested API key authentication helper updates, required scope aliases, and corresponding unit tests matching issue #121.

[mergekeeper]

Merged

Merged with squash.