Skip to content

Module Spec: FintraOS Guard

1. Overview

FintraOS Guard is designed to be the security and governance sentinel. It will ensure that no sensitive data is ever exposed to unauthorised services or users.

Core Responsibilities: - Key Management: Managing Tenant and User encryption keys (Crypto-Shredding). - Consent Registry: Tracking what data a user has agreed to share and for how long. - Access Control: Enforcing Row-Level Security (RLS) and Scope-based access.

2. Core Entities

2.1. ConsentGrant

Will record the legal basis for processing. 

{
  "consent_id": "cst_777",
  "profile_id": "usr_123",
  "tenant_id": "org_neobank",
  "scope": ["READ_ACCOUNTS", "READ_TRANSACTIONS", "READ_FORECAST"],
  "valid_from": "2023-10-01T00:00:00Z",
  "expires_at": "2024-01-01T00:00:00Z",
  "status": "ACTIVE",
  "metadata": {
    "ip_address": "192.168.1.1",
    "user_agent": "iOS/16.0"
  }
}

2.2. KeyMetadata

Internal record of encryption keys (keys themselves are in KMS/HSM). 

{
  "key_id": "key_usr_123_v1",
  "entity_type": "PROFILE",
  "entity_id": "usr_123",
  "algorithm": "AES-256-GCM",
  "status": "ACTIVE", // or DESTROYED
  "created_at": "2023-10-01"
}

2.3. IdentityRecord

The "Master Patient Index" that will map physical humans to digital profiles. 

{
  "identity_id": "id_global_999",
  "hash_keys": {
    "national_id": "sha256(AB123456C)", 
    "passport": "sha256(P12345678)"
  },
  "linked_profiles": [
    { "tenant": "org_neobank", "profile_id": "usr_123" },
    { "tenant": "org_lender", "profile_id": "usr_456" }
  ],
  "confidence_level": "HIGH"
}

3. Architecture

3.1. Identity Resolution Logic

When a new user signs up, Guard will attempt to match them against the IdentityRecord database. 1. Level 1 (Strong Match): Exact match on National ID + Country. -> Auto-Merge. 2. Level 2 (Medium Match): Exact match on Full Name + DOB + Email. -> Prompt User ("Is this you?"). 3. Level 3 (Weak Match): Same Phone Number only. -> Do nothing (could be a family plan).

3.2. The "Guard Sidecar"

Every FintraOS microservice (Core, Brain, Pulse) will run with a Guard Sidecar. - Incoming: Intercepts API requests -> Validates JWT -> Checks Consent -> Decrypts payload (if authorised). - Outgoing: Encrypts sensitive fields before writing to DB/Event Log. - Benefit: Developers don't handle keys directly; infrastructure handles encryption transparently.

3.4. AI Context Scoping (The "Ringfence")

Guard will govern the Context Window for GenAI features. It will ensure the AI only "sees" what the tenant is allowed to see.

  • Scenario: Tenant A (NeoBank) asks the AI: "How is this user's financial health?"
  • Policy Check:
    • Does Tenant A have READ_GLOBAL_PROFILE scope?
      • YES: Guard injects data from all linked accounts (Credit Cards, Loans from other banks).
      • NO: Guard filters the Context Window to only show data originating from Tenant A.
  • Mechanism: The Guard Sidecar will intercept the RAG retrieval and apply a hard filter: WHERE tenant_id = 'org_neobank'.

3.5. Agent Skill Governance

When the AI Agent attempts to invoke a Skill (e.g., transfer_money), Guard will intercept the request.

  • Check 1: Skill Authorization: Does the Tenant have this Skill enabled?
  • Check 2: User Consent: Has the user explicitly granted the EXECUTE_TRANSACTIONS scope?
  • Check 3: Policy Limits: Are the parameters within safe limits? (e.g., "Max Transfer < £500").
  • Check 4: Risk Analysis: Calls [Brain](<./Module-Brain.md>) to assess if this transaction fits the user's normal pattern.

4. Events

3.6. Deletion Workflow (GDPR)

  1. API Call: When a tenant calls DELETE /v1/profiles/{id}.
  2. Guard:
  3. Marks ConsentGrant as REVOKED.
  4. Calls KMS to delete the KeyMetadata for that user.
  5. Flushes any cached keys from memory.
  6. Result: Data in Vault is now permanent ciphertext.

4. Interfaces

4.1. Access Policy

Will be defined using OPA (Open Policy Agent) or similar. 

allow {
  input.method == "GET"
  input.path == ["v1", "forecast"]
  input.user.scopes[_] == "READ_FORECAST"
  input.user.tenant_id == input.resource.tenant_id
}