Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -378,7 +378,7 @@ stateDiagram-v2
- `/api/health` for health checks
- `/api/metrics` for JSON snapshot
- `/api/metrics?format=prometheus` for scrape-compatible format
- Ops UI consumes these APIs for dashboarding
- Ops UI renders the same in-process snapshot: `src/app/settings/page.tsx` (Ops tab, also reached via `/ops`) reads `getMetricsSnapshot()` on the server and hands it to `src/components/ops-dashboard.tsx`, so screen and scrape cannot disagree

## 9) 🚨 Failure Modes and Current Behavior

Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -525,6 +525,7 @@ or `signedXdr` strings.
- Health endpoint: `GET /api/health` — returns `blocklist` object with `configured`, `lastRefreshAt`, `domainCount`, `lastError`, plus `ready`, `checks`, and `failingChecks` (`production_config`, `storage`, `horizon`). The dashboard shows its pay, fund, and policy actions only while `ready` is `true`.
- Metrics endpoint: `GET /api/metrics` + Prometheus format
- `/ops` dashboard shows:
- allow / deny / rate-limit / submit-failure counters, read from the same in-process metrics snapshot that `GET /api/metrics` exports (zeroes when nothing has been recorded yet)
- service health
- total requests
- error rate
Expand Down
75 changes: 38 additions & 37 deletions docs/REVIEWER_EVIDENCE_MATRIX.md
Original file line number Diff line number Diff line change
@@ -1,37 +1,38 @@
# Reviewer Evidence Matrix

This document maps Fortexa's core security and payment claims directly to the codebase, tests, and API routes. It is designed to allow an SCF or investor reviewer to verify all claims in under 15 minutes.

## 15-Minute Reviewer Checklist

- [ ] **Wallet-bound login**: Verify in `src/lib/auth/wallet-challenge.ts` and `src/lib/auth/freighter.ts`.
- [ ] **Role-based access control**: Verify `requireAuth` usage in `src/app/api/stellar/submit-signed/route.ts` and `src/lib/auth/require-auth.ts`.
- [ ] **Policy decision outcomes**: Verify logic in `src/lib/policy/engine.ts` and `src/lib/decision/engine.ts`.
- [ ] **Human approval gate**: Verify UI block in `src/components/decision-console.tsx` and logic in `src/lib/decision/simulate.ts`.
- [ ] **Signed-XDR only payment path**: Verify API only accepts signed XDR in `src/app/api/stellar/submit-signed/route.ts` and client builds unsigned in `src/lib/stellar/client.ts`.
- [ ] **Audit hash-chain integrity**: Verify hashing mechanism in `src/lib/audit/hash-chain.ts`.
- [ ] **Metrics and ops visibility**: Verify structured logging and metrics in `src/lib/observability/metrics.ts` and `src/lib/observability/logger.ts`.
- [ ] **Idempotent submit behavior**: Verify the key claim / canonical body hash / stored-result replay logic in `src/lib/storage/submit-idempotency-store.ts` and `src/app/api/stellar/submit-signed/route.ts`.
- [ ] **No server-side private-key custody**: Verify absence of backend signing (`Keypair.fromSecret()`) in `src/lib/stellar/client.ts`.

## Detailed Evidence Mapping

| Claim | Source File(s) / API Routes | Tests / Documentation |
| :--- | :--- | :--- |
| **Wallet-bound login** | [`src/lib/auth/wallet-challenge.ts`](../src/lib/auth/wallet-challenge.ts)<br>[`src/lib/auth/freighter.ts`](../src/lib/auth/freighter.ts) | `src/lib/auth/freighter.test.ts`<br>`src/lib/auth/wallet-challenge.test.ts` |
| **Role-based access control** | [`src/lib/auth/require-auth.ts`](../src/lib/auth/require-auth.ts)<br>[`src/lib/auth/wallet-role.ts`](../src/lib/auth/wallet-role.ts) | `src/lib/auth/login-lockout.test.ts` |
| **Policy decision outcomes** | [`src/lib/policy/engine.ts`](../src/lib/policy/engine.ts)<br>[`src/lib/decision/engine.ts`](../src/lib/decision/engine.ts) | `src/lib/policy/engine.test.ts`<br>`src/lib/decision/engine.test.ts` |
| **Human approval gate** | [`src/components/decision-console.tsx`](../src/components/decision-console.tsx)<br>[`src/lib/decision/simulate.ts`](../src/lib/decision/simulate.ts) | `src/lib/decision/simulate.test.ts` |
| **Signed-XDR only payment path** | [`src/app/api/stellar/submit-signed/route.ts`](../src/app/api/stellar/submit-signed/route.ts)<br>[`src/lib/stellar/client.ts`](../src/lib/stellar/client.ts) | `src/lib/stellar/verify-payment-quote.test.ts` |
| **Audit hash-chain integrity** | [`src/lib/audit/hash-chain.ts`](../src/lib/audit/hash-chain.ts) | `src/lib/audit/hash-chain.test.ts` |
| **Metrics and ops visibility** | [`src/lib/observability/metrics.ts`](../src/lib/observability/metrics.ts)<br>[`src/lib/observability/logger.ts`](../src/lib/observability/logger.ts) | `src/lib/observability/metrics.test.ts` |
| **Idempotent submit behavior** | [`src/app/api/stellar/submit-signed/route.ts`](../src/app/api/stellar/submit-signed/route.ts)<br>[`src/lib/storage/submit-idempotency-store.ts`](../src/lib/storage/submit-idempotency-store.ts) | `src/app/api/stellar/submit-signed-idempotency.test.ts`<br>`src/lib/storage/submit-idempotency-store.test.ts`<br>`src/lib/storage/submit-idempotency-cleanup.test.ts` |
| **No server-side private-key custody** | [`src/lib/stellar/client.ts`](../src/lib/stellar/client.ts) | |

## Honest Limitations

To maintain transparency for SCF reviewers and investors, we note the following current architectural constraints:

1. **Audit Hash-Chain Storage**: The hash-chain is currently persisted in a standard database (Postgres) rather than being anchored to a decentralized public ledger or immutable storage network.
2. **Idempotency State**: Idempotency records live in Postgres (`fortexa_submit_idempotency`) with a local JSON-file fallback, so a record can be lost if the process restarts before the file store is written, and claims are per-instance unless all instances share the database.
3. **Hardware Wallet Integration**: The current wallet-bound login relies on browser extension wallets (like Freighter) and does not yet have direct native integrations with hardware signing devices.
# Reviewer Evidence Matrix

This document maps Fortexa's core security and payment claims directly to the codebase, tests, and API routes. It is designed to allow an SCF or investor reviewer to verify all claims in under 15 minutes.

## 15-Minute Reviewer Checklist

- [ ] **Wallet-bound login**: Verify in `src/lib/auth/wallet-challenge.ts` and `src/lib/auth/freighter.ts`.
- [ ] **Role-based access control**: Verify `requireAuth` usage in `src/app/api/stellar/submit-signed/route.ts` and `src/lib/auth/require-auth.ts`.
- [ ] **Policy decision outcomes**: Verify logic in `src/lib/policy/engine.ts` and `src/lib/decision/engine.ts`.
- [ ] **Human approval gate**: Verify UI block in `src/components/decision-console.tsx` and logic in `src/lib/decision/simulate.ts`.
- [ ] **Signed-XDR only payment path**: Verify API only accepts signed XDR in `src/app/api/stellar/submit-signed/route.ts` and client builds unsigned in `src/lib/stellar/client.ts`.
- [ ] **Audit hash-chain integrity**: Verify hashing mechanism in `src/lib/audit/hash-chain.ts`.
- [ ] **Metrics and ops visibility**: Verify structured logging and metrics in `src/lib/observability/metrics.ts` and `src/lib/observability/logger.ts`.
- [ ] **Dashboard and scrape agree**: Verify the Ops tab loader (`src/app/settings/page.tsx`) passes `getMetricsSnapshot()` to `src/components/ops-dashboard.tsx`, the same object `GET /api/metrics` serialises.
- [ ] **Idempotent submit behavior**: Verify deduplication logic via `xdrHash` in `src/app/api/stellar/submit-signed/route.ts`.
- [ ] **No server-side private-key custody**: Verify absence of backend signing (`Keypair.fromSecret()`) in `src/lib/stellar/client.ts`.

## Detailed Evidence Mapping

| Claim | Source File(s) / API Routes | Tests / Documentation |
| :--- | :--- | :--- |
| **Wallet-bound login** | [`src/lib/auth/wallet-challenge.ts`](../src/lib/auth/wallet-challenge.ts)<br>[`src/lib/auth/freighter.ts`](../src/lib/auth/freighter.ts) | `src/lib/auth/freighter.test.ts`<br>`src/lib/auth/wallet-challenge.test.ts` |
| **Role-based access control** | [`src/lib/auth/require-auth.ts`](../src/lib/auth/require-auth.ts)<br>[`src/lib/auth/wallet-role.ts`](../src/lib/auth/wallet-role.ts) | `src/lib/auth/login-lockout.test.ts` |
| **Policy decision outcomes** | [`src/lib/policy/engine.ts`](../src/lib/policy/engine.ts)<br>[`src/lib/decision/engine.ts`](../src/lib/decision/engine.ts) | `src/lib/policy/engine.test.ts`<br>`src/lib/decision/engine.test.ts` |
| **Human approval gate** | [`src/components/decision-console.tsx`](../src/components/decision-console.tsx)<br>[`src/lib/decision/simulate.ts`](../src/lib/decision/simulate.ts) | `src/lib/decision/simulate.test.ts` |
| **Signed-XDR only payment path** | [`src/app/api/stellar/submit-signed/route.ts`](../src/app/api/stellar/submit-signed/route.ts)<br>[`src/lib/stellar/client.ts`](../src/lib/stellar/client.ts) | `src/lib/stellar/verify-payment-quote.test.ts` |
| **Audit hash-chain integrity** | [`src/lib/audit/hash-chain.ts`](../src/lib/audit/hash-chain.ts) | `src/lib/audit/hash-chain.test.ts` |
| **Metrics and ops visibility** | [`src/lib/observability/metrics.ts`](../src/lib/observability/metrics.ts)<br>[`src/lib/observability/logger.ts`](../src/lib/observability/logger.ts)<br>[`src/app/api/metrics/route.ts`](../src/app/api/metrics/route.ts)<br>[`src/components/ops-dashboard.tsx`](../src/components/ops-dashboard.tsx) | `src/lib/observability/metrics.test.ts`<br>`src/app/api/metrics/route.test.ts`<br>`src/components/ops-dashboard.snapshot.test.tsx` |
| **Idempotent submit behavior** | [`src/app/api/stellar/submit-signed/route.ts`](../src/app/api/stellar/submit-signed/route.ts) | |
| **No server-side private-key custody** | [`src/lib/stellar/client.ts`](../src/lib/stellar/client.ts) | |

## Honest Limitations

To maintain transparency for SCF reviewers and investors, we note the following current architectural constraints:

1. **Audit Hash-Chain Storage**: The hash-chain is currently persisted in a standard database (Postgres) rather than being anchored to a decentralized public ledger or immutable storage network.
2. **Idempotency State**: Idempotency keys rely on local storage/Redis, which may be volatile depending on the infrastructure configuration.
3. **Hardware Wallet Integration**: The current wallet-bound login relies on browser extension wallets (like Freighter) and does not yet have direct native integrations with hardware signing devices.
Loading
Loading