GSoC 2026: Final Architecture Blueprint - STAC & ODRL Access Flow

[KinshukSS2]

Architecture & Implementation Plan: STAC and ODRL Integration (Week 3 & 4)

Following our recent meetings I have prepared this document that outlines the finalized architecture and coding action plan for integrating STAC/ODRL policies and handling user access workflows in istSOS4.

1. Architectural Workflow

We are implementing a dual-path access pipeline enforced at the FastAPI application layer. This ensures frictionless access to open data while maintaining strict security for restricted requests.

%%{init: {
  "theme": "base",
  "themeVariables": {
    "primaryTextColor": "#000000",
    "textColor": "#000000",
    "primaryBorderColor": "#333333",
    "lineColor": "#333333",
    "fontFamily": "Arial"
  }
}}%%

graph TD

    User((User / STAC Connector))
    Admin((Administrator))

    subgraph FastAPI["Application Layer: FastAPI Engine"]
        PathA["GET /Datastreams<br/>Path A: Public"]
        PathB["POST /register-request<br/>Path B: Restricted"]
        AdminApprove["PATCH /policy-approval<br/>Admin Dual-Action"]
    end

    subgraph PostgreSQL["Storage Layer: PostgreSQL"]
        UserTable[("User Table<br/>id, role, contact JSONB")]
        AuditTable[("AuditLog Table<br/>event_type, payload JSONB")]
        RLS["pg_policies<br/>Row-Level Security"]
    end

    User -->|"1a. Request Public Data"| PathA
    PathA -->|"2a. Log Anonymous Read"| AuditTable
    PathA -->|"3a. Serve Data Immediately"| User

    User -->|"1b. Request Restricted Data"| PathB
    PathB -->|"2b. Create User<br/>status='pending'"| UserTable
    PathB -->|"3b. Store ODRL Request JSON"| AuditTable

    Admin -->|"4. Review & Approve Request"| AdminApprove
    AdminApprove -->|"5a. Update to active"| UserTable
    AdminApprove -->|"5b. Execute Dynamic Policy SQL"| RLS
    AdminApprove -->|"5c. Log Final Approval"| AuditTable

    classDef actor fill:#FFFFFF,stroke:#333333,stroke-width:2px,color:#000000;
    classDef app fill:#E3F2FD,stroke:#1976D2,stroke-width:2px,color:#000000;
    classDef db fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px,color:#000000;

    class User,Admin actor;
    class PathA,PathB,AdminApprove app;
    class UserTable,AuditTable,RLS db;

Loading

2. Implementation Action Plan

The Week 2 RBAC foundations are complete and awaiting merge. The following steps cover the precise deliverables for Weeks 3 and 4.

Step 1: Unblock the STAC Connector

• Action: Create a "Service Account" in the database (e.g., Username: stac_connector_bot, Role: administrator).
• Usage: The external STAC connector will call POST /Login with these credentials to obtain a standard JWT Bearer token for its automated tasks.

Step 2: Build the Audit Log Ledger (migrations/003_audit_log.sql)

• Goal: Create an immutable, append-only ledger for all access events without touching the core User schema.
• Schema Details:
  • id (UUID/Primary Key)
  • actor_id (Nullable for anonymous reads)
  • action_type (Enum/String: PUBLIC_READ, RESTRICTED_REQUEST, ADMIN_APPROVAL)
  • dataset_id (String)
  • odrl_policy_id (String)
  • payload (JSONB) - Crucial for temporarily holding the ODRL JSON documents.
  • created_at (TIMESTAMPTZ)

Step 3: Implement Path A (Frictionless Public Access)

• Goal: Allow users to read non-sensitive open data without logging in.
• Action: Ensure read-only GET endpoints (like GET /Datastreams) bypass authorization checks entirely if the requested dataset policy is public.
• Logging: Triggers an Audit Log insert (action_type = PUBLIC_READ) with a null actor_id.

Step 4: Implement Path B (POST /register-request)

• Goal: Handle credentials and metadata for users requesting restricted data.
• Payload (Pydantic Model):
  • Core: username, password, dataset_id, odrl_policy_id
  • Metadata (Stored in contact JSONB): domain, company, address, telephone, telegram, linkedin
  • Message: explanation (justification for access)
• Logic:
  1. Validate payload.
  2. Create the user with status = 'pending', storing extra details in the contact JSONB column.
  3. Log the event (action_type = RESTRICTED_REQUEST) with the dataset and ODRL IDs.

Step 5: Build Admin Approval Endpoint (PATCH /Users/{id}/policy-approval)

• Goal: Allow admins to activate users, correct mistakes, and enforce security policies.
• Logic:
  1. Admin reviews the pending request. Note: The admin can pass a corrected policy_id here if the user made a mistake during registration.
  2. Dual-Action Transaction (Python-side):
     • Update the user's role to active (and assign the correct role like viewer).
     • Immediately call the dynamic database function (e.g., sensorthings.viewer_policy()) to generate the Row-Level Security rule.
  3. Log the final decision in the Audit Log (action_type = ADMIN_APPROVAL).

[KinshukSS2]

Hi @massimiliano-cannata,

Based on our recent meetings,I have documented the complete architecture and implementation plan .Let me know if this aligns with what we discussed or if you'd like me to make any adjustments before I start coding