Merge branch 'main' into feat/Payment

Author: memplethee-lab

.env.example

@@ -48,6 +48,14 @@ RATE_LIMIT_ENTERPRISE_PER_MINUTE=10000
 RATE_LIMIT_WINDOW_MS=60000
 RATE_LIMIT_BURST_MULTIPLIER=1.2
 
+# Distributed rate limiting (Redis-backed) — complements the per-tier limits above
+# Default strategy: "token-bucket" or "sliding-window"
+RATE_LIMIT_DEFAULT_STRATEGY=token-bucket
+# Redis key prefix for rate-limit entries
+RATE_LIMIT_REDIS_KEY_PREFIX=alian:rl:
+# When false, requests are rejected (not in-memory fallback) if Redis is down
+RATE_LIMIT_FALLBACK_TO_MEMORY=true
+
 # ── Logging ────────────────────────────────────────────────────────────────
 # Minimum log level emitted to all transports.
 # Values: verbose | debug | info | warn | error | fatal

.env.production.example

@@ -69,6 +69,11 @@ RATE_LIMIT_ENTERPRISE_PER_MINUTE=10000
 RATE_LIMIT_WINDOW_MS=60000
 RATE_LIMIT_BURST_MULTIPLIER=1.2
 
+# Distributed rate limiting (Redis-backed)
+RATE_LIMIT_DEFAULT_STRATEGY=token-bucket
+RATE_LIMIT_REDIS_KEY_PREFIX=alian:rl:
+RATE_LIMIT_FALLBACK_TO_MEMORY=false
+
 # Security Headers
 HSTS_MAX_AGE=31536000
 

.eslintrc.js

@@ -14,6 +14,17 @@ module.exports = {
     node: true,
     jest: true,
   },
+  overrides: [
+    {
+      files: [
+        'test/modules/**/*.ts',
+        'test/alerts/alert-preferences.e2e-spec.ts',
+      ],
+      parserOptions: {
+        project: 'test/tsconfig.json',
+      },
+    },
+  ],
   ignorePatterns: ['.eslintrc.js'],
   rules: {
     '@typescript-eslint/interface-name-prefix': 'off',
@@ -23,4 +34,4 @@ module.exports = {
     "@typescript-eslint/no-namespace": "off",
     "import/no-relative-parent-imports": "error",
   },
-};
+};

.vscode/settings.json

@@ -1,3 +1,5 @@
 {
-    "snyk.advanced.autoSelectOrganization": true
-}
+  "snyk.advanced.autoSelectOrganization": true,
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "typescript.enablePromptUseWorkspaceTsdk": true
+}

Dockerfile

@@ -43,6 +43,8 @@ RUN addgroup -S app && adduser -S app -G app
 # Copy only what's needed for runtime
 COPY --from=builder /app/dist ./dist
 COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/modules ./modules
+COPY --from=builder /app/package.json ./package.json
 
 ENV NODE_ENV=${NODE_ENV}
 ENV PORT=3000

MODULE_REVIEW_CHECKLIST.md

@@ -0,0 +1,40 @@
+# Module review checklist
+
+Use this checklist when GrantFox, Stella, or a SourceXXL maintainer reviews a new
+module pull request.
+
+## Manifest and compatibility
+
+- [ ] `module.manifest.json` is present and passes registry validation.
+- [ ] `name` is stable and unique, and `version` is valid semver.
+- [ ] The declared core compatibility range is accurate and tested.
+- [ ] Every lifecycle hook marked `true` is implemented by the entry point.
+- [ ] The published/runtime entry point is compiled JavaScript and loads without
+      development-only TypeScript hooks.
+
+## Scope and architecture
+
+- [ ] The module does not directly modify or couple itself to core files.
+- [ ] Public behavior is exposed through documented module boundaries.
+- [ ] Database changes include safe, reversible migration hooks.
+- [ ] Lifecycle hooks are idempotent and fail without leaving partial state.
+
+## Quality and isolation
+
+- [ ] Unit and integration tests are included and passing.
+- [ ] Per-tenant enablement, disablement, and configuration isolation are tested.
+- [ ] Global-default behavior is documented and does not overwrite tenant states.
+- [ ] Effective-state tests cover tenant override, global fallback, and implicit
+      disabled behavior.
+- [ ] Logs and errors provide enough context without exposing sensitive data.
+- [ ] No API keys, credentials, private URLs, or other secrets are hardcoded.
+- [ ] Registry installation and upgrade operations remain restricted to
+      administrators.
+
+## Governance and documentation
+
+- [ ] Dependency and source licenses are compatible with Apache-2.0.
+- [ ] The module's purpose, setup, configuration, and operational limits are documented.
+- [ ] Upgrade, rollback, and uninstall expectations are documented.
+- [ ] User-facing API or configuration changes include examples.
+- [ ] The PR is limited to the module and necessary registry integration.

docs/module-registry.md

@@ -0,0 +1,143 @@
+# Module registry and versioning
+
+The module registry installs pluggable packages without adding them to the core
+application module graph. It validates manifests, checks compatibility with the
+running API version, stores one current version per module name, and isolates
+enablement and configuration by tenant.
+
+## Author a module
+
+Create a `module.manifest.json` next to the module entry point:
+
+```json
+{
+  "name": "portfolio-exporter",
+  "version": "1.0.0",
+  "core": ">=0.1.0 <1.0.0",
+  "hooks": {
+    "onInstall": true,
+    "onUpgrade": true,
+    "onUninstall": false
+  },
+  "entryPoint": "@organization/portfolio-exporter"
+}
+```
+
+The schema requires:
+
+- `name`: lowercase module identifier.
+- `version`: valid semantic version.
+- `core`: semantic-version range supported by the module.
+- `hooks`: booleans declaring `onInstall`, `onUpgrade`, and `onUninstall`.
+- `entryPoint`: installed package reference or a runtime JavaScript entry point
+  inside the root `modules/` directory. Local entry points outside that directory
+  are rejected so manifests cannot load core source files.
+
+The machine-readable schema is in
+`src/modules/registry/module-manifest.schema.json`. Runtime validation uses the
+equivalent class-validator DTO plus `semver`, so invalid versions and ranges are
+rejected even when a client does not use the JSON Schema.
+
+Local modules must expose JavaScript that Node can load without `ts-node`.
+TypeScript authors should compile their package before registration and ship
+declarations that implement `ModuleLifecycle`. Published npm package entry points
+are resolved normally from `node_modules`.
+
+The entry point must default-export a lifecycle class or object implementing:
+
+```ts
+interface ModuleLifecycle {
+  onInstall?(): Promise<void>;
+  onUpgrade?(fromVersion: string, toVersion: string): Promise<void>;
+  onUninstall?(): Promise<void>;
+}
+```
+
+A hook marked `true` must be implemented. Hooks execute inside the registry's
+database transaction where possible. A thrown error rolls back the registry
+version and status. Because external services cannot participate in the database
+transaction, hooks must be idempotent and compensate for external side effects.
+
+## Register and upgrade
+
+Registry endpoints require an authenticated administrator. Registry management
+bypasses the general user KYC guard because it is an administrative control-plane
+operation; the global authentication and role guards still apply.
+
+POST the manifest and its metadata to `POST /api/v1/modules`:
+
+```json
+{
+  "manifest": {
+    "name": "portfolio-exporter",
+    "version": "1.0.0",
+    "core": ">=0.1.0 <1.0.0",
+    "hooks": {
+      "onInstall": true,
+      "onUpgrade": true,
+      "onUninstall": false
+    },
+    "entryPoint": "@organization/portfolio-exporter"
+  },
+  "description": "Exports tenant portfolios",
+  "author": "Organization"
+}
+```
+
+The API reads the core version from the root `package.json`. Registration and
+enablement fail with a message containing the required range and actual version
+when the module is incompatible.
+
+Posting a new name runs `onInstall`. Posting the same name with a strictly newer
+version runs `onUpgrade` and updates the existing registry row. Equal versions and
+downgrades are rejected.
+
+## Tenant and global enablement
+
+Enable a module with `POST /api/v1/modules/:id/enable` and disable it with
+`POST /api/v1/modules/:id/disable`:
+
+```json
+{
+  "tenantId": "tenant-123",
+  "config": { "format": "csv" }
+}
+```
+
+Each operation changes only that tenant's `TenantModuleState`. The project has no
+canonical tenant entity, so `tenantId` is an opaque identifier supplied by the
+caller. Omitting `tenantId` creates or updates the nullable global-default state;
+it does not alter any explicit tenant row. An explicit tenant state therefore
+remains isolated from the default.
+
+Resolve the effective state for a tenant with:
+
+```text
+GET /api/v1/modules/:id/state?tenantId=tenant-123
+```
+
+Resolution uses the explicit tenant row first, then the global-default row. When
+neither exists the result is an implicit disabled state. A disabled explicit row
+therefore overrides an enabled global default.
+
+A module can be removed with `DELETE /api/v1/modules/:id` only when every tenant
+and global-default state is disabled. Deregistration runs `onUninstall` when it is
+declared.
+
+## Run the example locally
+
+The working example is in `modules/example-grant-module`. Its CommonJS entry
+point is loadable by the development server, the bundled application, and the
+production Docker image; `index.d.ts` declares the lifecycle TypeScript contract.
+
+```bash
+npm install
+npm run migration:run
+npm run start:dev
+MODULE_REGISTRY_TOKEN=<admin-token> npm run module:example:register
+```
+
+`MODULE_REGISTRY_TOKEN` must contain an administrator bearer token. Set
+`MODULE_REGISTRY_URL` to use a non-default API URL. Inspect the registered module
+with `GET /api/v1/modules`, then use its returned UUID in the enable, disable, and
+state-resolution endpoints.

docs/stellar-reconciliation.md

@@ -0,0 +1,31 @@
+# Stellar reconciliation
+
+The reconciliation module records confirmed Stellar payments, matches them to internal invoices, and preserves every decision in an audit trail.
+
+## Testnet polling
+
+Set `STELLAR_RECONCILIATION_ACCOUNT` to the Stellar destination account monitored by the service. The service polls `STELLAR_HORIZON_URL` every 60 seconds and defaults to `https://horizon-testnet.stellar.org`. Horizon paging tokens provide idempotent continuation. Duplicate transaction hashes are ignored and recorded as retry-safe audit entries.
+
+For webhook or queue consumers, send a confirmed payment to `POST /reconcile/stellar/transactions` with its transaction hash, destination account, amount, asset, and memo. The endpoint accepts the same payload shape as the Horizon adapter.
+
+## Invoice lifecycle
+
+Register an invoice with `POST /reconcile/stellar/invoice`.
+
+```json
+{
+  "invoiceId": "INV-2026-0001",
+  "expectedAmount": "125.5000000",
+  "destinationAccount": "GABC...DEST",
+  "paymentReference": "order-0001",
+  "assetCode": "XLM"
+}
+```
+
+Matching requires destination account and asset equality. When an invoice has a payment reference, the incoming memo must match it. The invoice moves from `open` to `partial` or `paid`. Transactions without a matching invoice remain `unmatched`.
+
+## Lookup and operations
+
+`GET /reconcile/stellar/tx/:txid` returns the transaction and its decisions. `GET /reconcile/stellar/invoice/:invoiceId` returns the invoice and its decisions. `POST /reconcile/stellar/invoice/:invoiceId/reconcile` retries matching for accounting staff. Administrators can inspect unmatched transactions with `GET /reconcile/stellar/admin/unmatched` and audit records with `GET /reconcile/stellar/admin/audit`.
+
+The admin endpoints require an authenticated administrator with verified two-factor authentication. All decision records include the invoice, transaction, decision, reason, attempt, and relevant matching metadata.

modules/example-grant-module/README.md

@@ -0,0 +1,22 @@
+# Example grant module
+
+This package is a minimal runtime-safe module that demonstrates the registry's
+install and upgrade lifecycle. It lives outside `src/`, does not modify core
+files, and exports a CommonJS entry point that works in development, the bundled
+Nest build, and the production Docker image.
+
+`index.d.ts` declares that the runtime class implements `ModuleLifecycle`.
+`index.cjs` records lifecycle calls in memory so the e2e test can verify them.
+
+Start the API, provide an admin bearer token, and register the module:
+
+```bash
+npm run start:dev
+MODULE_REGISTRY_TOKEN=<admin-token> npm run module:example:register
+```
+
+Override the endpoint with `MODULE_REGISTRY_URL` when the API is not available at
+`http://localhost:3001/api/v1/modules`.
+
+Submitting the same manifest with a version newer than `0.1.0` calls
+`onUpgrade(fromVersion, toVersion)`.

modules/example-grant-module/index.cjs

@@ -0,0 +1,23 @@
+"use strict";
+
+/** @type {string[]} */
+const exampleGrantModuleEvents = [];
+
+/**
+ * Runtime implementation of the registry's ModuleLifecycle contract.
+ * The adjacent index.d.ts provides the compile-time TypeScript contract.
+ */
+class ExampleGrantModuleLifecycle {
+  async onInstall() {
+    exampleGrantModuleEvents.push("installed");
+  }
+
+  async onUpgrade(fromVersion, toVersion) {
+    exampleGrantModuleEvents.push(`upgraded:${fromVersion}->${toVersion}`);
+  }
+}
+
+module.exports = {
+  default: ExampleGrantModuleLifecycle,
+  exampleGrantModuleEvents,
+};