[Opulencechuks]

Here is the PR description formatted with your security template:

## Security Changes

Closes #1733 

### Type of Security Change
- [ ] SAST rule update
- [ ] Dependency vulnerability fix
- [ ] Exemption addition/renewal
- [ ] Security workflow modification
- [ ] Container image update
- [x] Other: Stream deletion authorization, lifecycle status guards, soft deletion, and audit logging

### Vulnerability Details (if applicable)

**CVE/Advisory ID:** 
- CVE-ID: N/A
- GHSA-ID: N/A

**Affected Package:**
- Name: `streampay-frontend` (`DELETE /api/streams/:id`, `DELETE /api/v2/streams/:id`)
- Version: `0.1.0`
- Severity: [ ] Critical [ ] High [x] Medium [ ] Low

**Fix Applied:**
- [ ] Package version bump
- [x] Code change to mitigate
- [ ] Configuration update
- [ ] Exemption granted (see below)

### Exemption Request (if applicable)

**Exemption ID:** N/A

**Justification:**
N/A — Direct code fix applied.

**Mitigation Applied:**
- Added a shared `deleteStream(id, actor, tenant, request)` helper in `app/lib/stream-delete.ts` used by both v1 and v2 `DELETE` routes.
- Blocked deletion of `ended` streams with `409 FUNDS_PENDING_WITHDRAWAL` and `withdrawn` streams unless `withdrawal.state === "succeeded"`.
- Enforced sender or organization owner authorization (`403 FORBIDDEN` otherwise) and tenant isolation (`404 STREAM_NOT_FOUND` on mismatch).
- Replaced hard physical removal with soft deletion (`deletedAt`), invalidated `streamCache`, and recorded a tamper-evident `stream.delete` audit entry with a `before` snapshot.

**Expiry Date:** N/A

**Review Plan:**
Verified via automated Jest test suites (`app/api/streams/[id]/route.test.ts`, `app/api/v2/streams/[id]/route.test.ts`, `app/lib/stream-delete.test.ts`) and OpenAPI schema checks (`npm run openapi:check`).

### Testing

- [x] Ran `npm audit` locally - output attached or no new vulnerabilities
- [x] Security workflow passes on this branch
- [x] Test suite passes: `npm test`
- [x] Build succeeds: `npm run build`

### Security Impact Analysis

**Affected Components:**
- [x] Authentication/Authorization
- [x] Payment processing
- [ ] Data encryption
- [x] API endpoints
- [ ] Dependencies
- [ ] Container images
- [ ] CI/CD pipeline
- [x] Other: Audit logging & cache invalidation

**Risk Assessment:**
Previously, both `DELETE /api/streams/:id` and `DELETE /api/v2/streams/:id` only blocked `active` and `paused` streams, allowing an `ended` stream with unclaimed funds or a `pending` withdrawal finality check to be permanently deleted, causing recipients to lose the record needed to claim funds. Additionally, v2 lacked ownership checks and neither endpoint recorded an audit trail.

This change mitigates these risks by:
1. Restricting deletion strictly to `draft`, `cancelled`, and `withdrawn` (with `withdrawal.state === "succeeded"`).
2. Enforcing ownership checks requiring the verified actor to be the `senderAddress` or an organization owner (`403 FORBIDDEN` otherwise), and enforcing tenant isolation (`404 STREAM_NOT_FOUND`).
3. Soft-deleting streams (`deletedAt`) and excluding them from `GET` and list endpoints prior to pagination while preserving records for reconciliation and audit.
4. Invalidating `streamCache` on soft delete so subsequent `GET` requests with stale `If-None-Match` headers return `404` instead of `304`.
5. Recording `stream.delete` with a `before` snapshot via `recordPrivilegedStreamAuditEvent`.

#### Deletability Matrix

| Stream Status | `withdrawal.state` | Deletable? | HTTP Status / Error Code |
| :--- | :--- | :---: | :--- |
| `draft` | N/A | Yes | `204 No Content` |
| `cancelled` | N/A | Yes | `204 No Content` |
| `withdrawn` | `"succeeded"` | Yes | `204 No Content` |
| `withdrawn` | `"pending"` / `"failed"` / unset | No | `409 Conflict` (`STREAM_INACTIVE_STATE`) |
| `ended` | Any (`"pending"`, etc.) | No | `409 Conflict` (`FUNDS_PENDING_WITHDRAWAL`) |
| `active` | N/A | No | `409 Conflict` (`STREAM_INACTIVE_STATE`) |
| `paused` | N/A | No | `409 Conflict` (`STREAM_INACTIVE_STATE`) |
| Already deleted (`deletedAt` set) | Any | Yes (Idempotent) | `204 No Content` |

### Documentation Updates

- [ ] Updated README.md (if workflow changed)
- [ ] Updated SECURITY-CI-SETUP.md (if process changed)
- [ ] Updated security-exemptions.json (if applicable)
- [x] Added security notes to code comments (and updated `openapi.json` + `app/types/openapi.generated.ts`)

### Accessibility (a11y)

- [ ] All interactive elements (buttons, links, form controls, custom
      widgets) are reachable and operable via keyboard alone, with a visible
      focus indicator.
- [ ] Screen-reader support verified: no unlabelled regions, icon-only
      controls have accessible names, and dynamic content updates use an
      `aria-live` region where appropriate.
- [ ] Animations/transitions respect the `prefers-reduced-motion` user
      preference (or the change introduces no motion).
- [ ] Status/state is never conveyed by color alone (icon, text, or pattern
      is paired with any color-coded indicator).
- [x] N/A — this change has no user-facing UI impact.

### Checklist

- [x] No secrets or keys committed
- [x] No PII or sensitive data in logs
- [x] All security scans pass (or exemptions documented)
- [x] Branch protection requirements met
- [x] Code review from security team (for critical changes)

### Additional Notes

- **Test Plan Coverage**:
  - [x] 1. Delete an `ended` stream with `withdrawal.state: "pending"` → `409 FUNDS_PENDING_WITHDRAWAL`
  - [x] 2. Delete `draft` as the sender → `204`; `GET` → `404`; excluded from list before pagination
  - [x] 3. Delete `draft` as a non-sender → `403 FORBIDDEN`
  - [x] 4. Delete `withdrawn` with a `succeeded` withdrawal → `204`
  - [x] 5. Delete twice → `204` then `204`
  - [x] 6. Delete an unknown id → `404`
  - [x] 7. Audit → One `stream.delete` record with a `before` snapshot
  - [x] 8. `GET` with a stale `If-None-Match` after delete → `404`, not `304`
  - [x] 9. v1 and v2 parity → Same status codes for the same inputs

### Test Output

```text
PASS app/api/streams/[id]/route.test.ts
PASS app/api/v2/streams/[id]/route.test.ts
PASS app/lib/stream-delete.test.ts

Generated OpenAPI types are up to date.

CI Run Link

Workflow Run: https://github.com/Opulencechuks/StreamPay-Frontend/actions

---

Security Review Required: @security-team
Compliance Impact: Yes - Enhances financial record retention and tamper-evident audit logging by preventing premature deletion of streams with pending withdrawals and recording stream.delete audit events with before state snapshots.