[SEC] Field-Level Auth + Resource Ownership + RBAC

[oomokaro1]

[SEC] Field-Level Authorization + Resource Ownership Guard

Priority: High

Difficulty: Hard
Estimated Effort: 3-4 days
Relevant Packages: OrbitStream_backend/, orbitstream_docs/
Labels: security, enhancement, priority:high

Requirements

1. Public vs Authenticated Response Filtering

• Create a PublicSessionDto that strips sensitive fields: only returns id, url, amount, asset, status, expiresAt
• The public GET /v1/checkout/sessions/:id returns PublicSessionDto
• The authenticated merchant endpoint returns the full CheckoutSession object
• Use class-transformer @Exclude() and @Expose() decorators, or manual field selection

2. ResourceOwnershipGuard

Create a reusable guard that verifies the authenticated merchant owns the resource:

// src/auth/resource-ownership.guard.ts
@Injectable()
export class ResourceOwnershipGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    const merchantId = request.merchantId; // from JWT or API key
    const resourceId = request.params.id;

    // Look up resource and verify ownership
    // Return true if owned, throw ForbiddenException if not
  }
}

Apply to:

• DELETE /merchants/me/api-keys/:id — verify key belongs to merchant
• POST /v1/checkout/sessions/:id/cancel — verify session belongs to merchant
• All future merchant-scoped endpoints

3. Role-Based Access Control

• Add a role column to the merchants table: admin | merchant | viewer (default: merchant)
• Create a RolesGuard that checks @Roles('admin') decorator
• admin can access all merchants' data (platform operators)
• merchant can access only their own data (default)
• viewer can read but not write (for team members)
• Create a @Roles() decorator

4. Audit Logging

• Log all authorization failures: who tried to access what, from which IP
• Create an audit_logs table: id, merchant_id, action, resource_type, resource_id, ip_address, user_agent, created_at
• Log: failed auth attempts, successful logins, resource access denials, sensitive operations (API key generation, webhook changes)

5. Input Sanitization

• Validate walletAddress format: must start with G, be exactly 56 characters, base32-encoded
• Validate email format with RFC 5322 compliant regex
• Validate webhookUrl format: must be HTTPS in production
• Validate amount is positive and within reasonable bounds (0 < amount < 1,000,000)

6. Testing

• Unit test: ResourceOwnershipGuard allows owner, denies non-owner
• Unit test: RolesGuard allows admin, denies viewer on write endpoints
• Unit test: PublicSessionDto excludes sensitive fields
• Integration test: merchant A cannot cancel merchant B's session
• Integration test: viewer role cannot generate API keys
• Integration test: admin can access any merchant's data

[AbelOsaretin]

I'd like to work on this issue.
The current backend lacks field-level authorization and resource ownership verification, meaning authenticated merchants can potentially access or manipulate resources belonging to other merchants. For example, the DELETE /merchants/me/api-keys/:id endpoint and POST /v1/checkout/sessions/:id/cancel endpoint do not verify that the requesting merchant owns the target resource, and the public checkout endpoint returns full CheckoutSession objects including sensitive fields. These gaps could allow cross-tenant data exposure and unauthorized resource manipulation.
My approach
I will implement a layered security model: a ResourceOwnershipGuard to verify merchant ownership of resources at the route level, a RolesGuard with @roles() decorator for role-based access control, and a PublicSessionDto with class-transformer decorators to enforce field-level filtering. Input sanitization will be added at the DTO validation layer, and an audit logging system will record all authorization failures and sensitive operations.
Implementation plan

1. Create PublicSessionDto with field-level filtering
   • Create src/dto/public-session.dto.ts extending or mirroring CheckoutSession
   • Apply @exclude() on sensitive fields (merchantId, metadata, webhookUrl) and @expose() on safe fields (id, url, amount, asset, status, expiresAt)
   • Update GET /v1/checkout/sessions/:id public endpoint to return PublicSessionDto using instanceToPlain() or plainToInstance()
   • Ensure the authenticated merchant endpoint continues returning the full CheckoutSession
2. Implement ResourceOwnershipGuard
   • Create src/auth/resource-ownership.guard.ts implementing CanActivate
   • Extract merchantId from the JWT payload or API key context (request.merchantId)
   • Look up the resource by request.params.id from the database (API key or checkout session)
   • Compare resource's merchantId to the authenticated merchant; throw ForbiddenException if mismatch
   • Apply the guard to DELETE /merchants/me/api-keys/:id, POST /v1/checkout/sessions/:id/cancel, and any future merchant-scoped endpoints
3. Implement Role-Based Access Control
   • Add a role column to the merchants table via a new migration: type enum('admin','merchant','viewer'), default 'merchant'
   • Create src/auth/roles.decorator.ts with a @roles() decorator that attaches role metadata to route handlers
   • Create src/auth/roles.guard.ts implementing CanActivate, reading the required roles from the decorator metadata and comparing against request.merchant.role
   • Configure: admin can access all merchants' data, merchant can access only their own, viewer can read but not write
4. Implement audit logging
   • Create an audit_logs migration with columns: id, merchant_id, action, resource_type, resource_id, ip_address, user_agent, created_at
   • Create src/audit/audit.service.ts with methods to log authorization failures, successful logins, resource access denials, and sensitive operations (API key generation, webhook changes)
   • Integrate AuditService into ResourceOwnershipGuard, RolesGuard, and relevant controllers
   • Log the requesting merchant ID, action, resource type/ID, IP address, and user agent
5. Add input sanitization
   • Validate walletAddress: must start with G, exactly 56 characters, base32-encoded (add custom @ValidatorDecorator or use class-validator @matches)
   • Validate email: RFC 5322 compliant regex pattern
   • Validate webhookUrl: must be HTTPS in production environments
   • Validate amount: positive integer, bounded 0 < amount < 1,000,000
   • Apply validations to all relevant DTOs using class-validator decorators
6. Write comprehensive tests
   • Unit test ResourceOwnershipGuard: allows owner, denies non-owner with ForbiddenException
   • Unit test RolesGuard: allows admin on all routes, denies viewer on write endpoints
   • Unit test PublicSessionDto: confirms sensitive fields are excluded from serialization
   • Integration test: merchant A cannot cancel merchant B's checkout session
   • Integration test: viewer role cannot generate API keys
   • Integration test: admin can access any merchant's data
   • Integration test: authorization failures are logged to audit_logs
     Impact

• Eliminates cross-tenant resource access vulnerabilities by enforcing ownership checks at the guard level before any business logic executes.
• Enforces defense-in-depth: field-level DTO filtering prevents accidental data leakage, while ownership and role guards prevent deliberate misuse.
• Establishes a reusable, decorator-based RBAC pattern (@roles()) that scales cleanly to future endpoints without requiring per-route guard configuration.
• Audit logging provides a forensic trail for all authorization decisions, enabling incident response and compliance reporting.
• Input sanitization at the DTO layer prevents injection and malformed data from reaching business logic or the database.
  I'm ready to start immediately and can have a PR up within a reasonable timeline. Happy to adjust the plan if you have preferences on any of the details.

[grantfox-oss]

🦊 GrantFox — @AbelOsaretin has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

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

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign campaign!

@AbelOsaretin's PR #25 was approved and merged by @oomokaro1.

🏆 @AbelOsaretin: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (153 total points). Track your full progress on GrantFox.

👏 Great work, @AbelOsaretin! Keep contributing to OrbitStream.