starred/finmars-core

Fork 0

mirror of https://github.com/finmars-platform/finmars-core.git synced 2026-04-26 06:35:59 +03:00

[GH-ISSUE #80] Finmars Marketplace Licensing System: Software Requirements Specification #29

New issue

Open

opened 2026-03-03 11:58:29 +03:00 by kerem · 2 comments

kerem commented

2026-03-03 11:58:29 +03:00

Owner

Originally created by @olegprivate on GitHub (Aug 7, 2025).
Original GitHub issue: https://github.com/finmars-platform/finmars-core/issues/80

Originally assigned to: @falendary, @sergeiosipov on GitHub.

1. Introduction

1.1. Purpose

This document provides the detailed software requirements for the Finmars Marketplace Licensing System. It is intended for project managers, developers, and QA teams to understand the features, functions, and constraints of the system.

1.2. Scope

The scope of this document covers the full lifecycle of a module license, from purchase and activation to renewal and expiration. This includes the user interfaces on the main Finmars marketplace and the necessary API endpoints for validation by consumer Workspaces (both SaaS and on-premises).

1.3. Definitions, Acronyms, and Abbreviations

• Finmars ID: The master user account responsible for owning and managing licenses.
• Workspace: An isolated instance of a Finmars application which consumes a license.
• Module: A software product on the marketplace sold via subscription.
• Subscription: The time-based financial agreement for the use of a Module.
• License Entitlement: An abstract record representing the user's right to use a Module, defined by the active Subscription.
• License Key: A unique string generated for the "Push" activation model.
• OAuth 2.0: Open Authorization standard used for secure, delegated access.
• API: Application Programming Interface.

2. General System Requirements

2.1. Core Licensing Principles

• 2.1.1. The system shall implement a floating license model where a license can be moved between different Workspaces.
• 2.1.2. License ownership shall be immutably tied to the user's Finmars ID.
• 2.1.3. License consumption shall be tied to a specific Workspace upon activation.

3. Functional Requirements

3.1. License Ownership & Management (Marketplace View)

• 3.1.1. All users shall have access to a "My Licenses" dashboard on the finmars.com website.
• 3.1.2. The dashboard shall list all License Entitlements associated with the logged-in user's Finmars ID.
• 3.1.3. Each license entry shall display the following information:
o Associated Module name.
o Subscription expiration date.
o Current status: Active or Unassigned, Expired.
• 3.1.4. For licenses with an Active status, the dashboard shall also display the name or ID of the Workspace to which it is assigned.
• 3.1.5. Users shall have the ability to deactivate an Active license from the dashboard, which will change its status to Unassigned.

3.2. Activation Flow 1: Marketplace-Initiated ("Push" Model)

• 3.2.1. The system shall provide a mechanism for a user to assign an Unassigned license to one of their registered Workspaces from the "My Licenses" dashboard.
• 3.2.2. Upon successful assignment, the system shall generate a unique, cryptographically secure, and non-sequential License Key.
• 3.2.3. The system shall display this License Key to the user and provide an easy mechanism (e.g., a "copy" button) to copy it to their clipboard.

3.3. Activation Flow 2: Workspace-Initiated ("Pull" Model)

• 3.3.1. The system shall support a license activation flow that is initiated from within the Workspace user interface.
• 3.3.2. This user authorization flow shall be implemented using the OAuth 2.0 protocol to ensure secure delegated access.
• 3.3.3. After a user provides consent, the Workspace shall be able to make a secure API call to Finmars to retrieve a list of the user's Unassigned licenses relevant to the Module requiring activation.
• 3.3.4. The Workspace UI shall present this list of available licenses to the user for selection.
• 3.3.5. Upon user selection, the Workspace shall send an API request to Finmars to activate the chosen License Entitlement for that Workspace.
• 3.3.6. This activation flow shall not require the user to manually see, copy, or paste any License Key.

3.4. License Validation

• 3.4.1. Any Workspace with an activated Module shall validate the license status with a central Finmars API endpoint.
• 3.4.2. The validation API endpoint shall verify the following conditions for a license to be considered valid:
o The license exists and is Active.
o The associated Subscription has not been canceled or expired (past its grace period).
o The license is assigned to the Workspace_ID making the validation request.

3.5. License Lifecycle Management

• 3.5.1. The successful renewal of a Subscription shall automatically extend the Expiry_Date on the corresponding License Entitlement without requiring any change or reactivation in the Workspace.
• 3.5.2. Upon Subscription expiration, the system should provide a configurable grace period (e.g., 7-14 days) during which the license continues to validate successfully.
• 3.5.3. After the grace period ends, the license shall become invalid, and the validation API shall return a "valid: false" response.

4. Non-Functional Requirements

4.1. Security

• 4.1.1. All API communication between a Workspace and the Finmars Licensing System shall use Transport Layer Security (TLS 1.2 or higher).
• 4.1.2. The License Key string shall not contain any sensitive data (e.g., expiration date, user ID). It must act only as a pointer to the record in the Finmars database.
• 4.1.3. The OAuth 2.0 implementation shall follow industry best practices, including the use of short-lived access tokens and secure storage of client secrets.

4.2. Usability

• 4.2.1. Error messages returned by the API or displayed in the UI for invalid, expired, or incorrect licenses shall be clear, concise, and provide actionable guidance to the user.

4.3. Reliability & Availability

• 4.3.1. The central license validation API shall be designed for high availability.
• 4.3.2. For on-premises Workspaces, the consuming application should cache the license validation status for a configurable duration (e.g., 24-72 hours). This ensures continuous operation during periods of intermittent network connectivity to the Finmars API.

5. System Integration Requirements

5.1. API Specifications

• 5.1.1. Finmars shall provide and maintain clear, versioned, and publicly accessible documentation for its licensing API.
• 5.1.2. The API documentation shall include detailed specifications, request/response examples, and error codes for all public endpoints, including license validation and the OAuth 2.0 authorization flow.

Originally created by @olegprivate on GitHub (Aug 7, 2025). Original GitHub issue: https://github.com/finmars-platform/finmars-core/issues/80 Originally assigned to: @falendary, @sergeiosipov on GitHub. ### 1. Introduction ### 1.1. Purpose This document provides the detailed software requirements for the Finmars Marketplace Licensing System. It is intended for project managers, developers, and QA teams to understand the features, functions, and constraints of the system. ### 1.2. Scope The scope of this document covers the full lifecycle of a module license, from purchase and activation to renewal and expiration. This includes the user interfaces on the main Finmars marketplace and the necessary API endpoints for validation by consumer Workspaces (both SaaS and on-premises). ### 1.3. Definitions, Acronyms, and Abbreviations • Finmars ID: The master user account responsible for owning and managing licenses. • Workspace: An isolated instance of a Finmars application which consumes a license. • Module: A software product on the marketplace sold via subscription. • Subscription: The time-based financial agreement for the use of a Module. • License Entitlement: An abstract record representing the user's right to use a Module, defined by the active Subscription. • License Key: A unique string generated for the "Push" activation model. • OAuth 2.0: Open Authorization standard used for secure, delegated access. • API: Application Programming Interface. ### 2. General System Requirements ### 2.1. Core Licensing Principles • 2.1.1. The system shall implement a floating license model where a license can be moved between different Workspaces. • 2.1.2. License ownership shall be immutably tied to the user's Finmars ID. • 2.1.3. License consumption shall be tied to a specific Workspace upon activation. ### 3. Functional Requirements ### 3.1. License Ownership & Management (Marketplace View) • 3.1.1. All users shall have access to a "My Licenses" dashboard on the finmars.com website. • 3.1.2. The dashboard shall list all License Entitlements associated with the logged-in user's Finmars ID. • 3.1.3. Each license entry shall display the following information: o Associated Module name. o Subscription expiration date. o Current status: Active or Unassigned, Expired. • 3.1.4. For licenses with an Active status, the dashboard shall also display the name or ID of the Workspace to which it is assigned. • 3.1.5. Users shall have the ability to deactivate an Active license from the dashboard, which will change its status to Unassigned. ### 3.2. Activation Flow 1: Marketplace-Initiated ("Push" Model) • 3.2.1. The system shall provide a mechanism for a user to assign an Unassigned license to one of their registered Workspaces from the "My Licenses" dashboard. • 3.2.2. Upon successful assignment, the system shall generate a unique, cryptographically secure, and non-sequential License Key. • 3.2.3. The system shall display this License Key to the user and provide an easy mechanism (e.g., a "copy" button) to copy it to their clipboard. ### 3.3. Activation Flow 2: Workspace-Initiated ("Pull" Model) • 3.3.1. The system shall support a license activation flow that is initiated from within the Workspace user interface. • 3.3.2. This user authorization flow shall be implemented using the OAuth 2.0 protocol to ensure secure delegated access. • 3.3.3. After a user provides consent, the Workspace shall be able to make a secure API call to Finmars to retrieve a list of the user's Unassigned licenses relevant to the Module requiring activation. • 3.3.4. The Workspace UI shall present this list of available licenses to the user for selection. • 3.3.5. Upon user selection, the Workspace shall send an API request to Finmars to activate the chosen License Entitlement for that Workspace. • 3.3.6. This activation flow shall not require the user to manually see, copy, or paste any License Key. ### 3.4. License Validation • 3.4.1. Any Workspace with an activated Module shall validate the license status with a central Finmars API endpoint. • 3.4.2. The validation API endpoint shall verify the following conditions for a license to be considered valid: o The license exists and is Active. o The associated Subscription has not been canceled or expired (past its grace period). o The license is assigned to the Workspace_ID making the validation request. ### 3.5. License Lifecycle Management • 3.5.1. The successful renewal of a Subscription shall automatically extend the Expiry_Date on the corresponding License Entitlement without requiring any change or reactivation in the Workspace. • 3.5.2. Upon Subscription expiration, the system should provide a configurable grace period (e.g., 7-14 days) during which the license continues to validate successfully. • 3.5.3. After the grace period ends, the license shall become invalid, and the validation API shall return a "valid: false" response. ### 4. Non-Functional Requirements ### 4.1. Security • 4.1.1. All API communication between a Workspace and the Finmars Licensing System shall use Transport Layer Security (TLS 1.2 or higher). • 4.1.2. The License Key string shall not contain any sensitive data (e.g., expiration date, user ID). It must act only as a pointer to the record in the Finmars database. • 4.1.3. The OAuth 2.0 implementation shall follow industry best practices, including the use of short-lived access tokens and secure storage of client secrets. ### 4.2. Usability • 4.2.1. Error messages returned by the API or displayed in the UI for invalid, expired, or incorrect licenses shall be clear, concise, and provide actionable guidance to the user. ### 4.3. Reliability & Availability • 4.3.1. The central license validation API shall be designed for high availability. • 4.3.2. For on-premises Workspaces, the consuming application should cache the license validation status for a configurable duration (e.g., 24-72 hours). This ensures continuous operation during periods of intermittent network connectivity to the Finmars API. ### 5. System Integration Requirements ### 5.1. API Specifications • 5.1.1. Finmars shall provide and maintain clear, versioned, and publicly accessible documentation for its licensing API. • 5.1.2. The API documentation shall include detailed specifications, request/response examples, and error codes for all public endpoints, including license validation and the OAuth 2.0 authorization flow.

kerem added the

enhancement

label

2026-03-03 11:58:29 +03:00

kerem commented

2026-03-03 11:58:30 +03:00

Author

Owner

@sergeiosipov commented on GitHub (Aug 9, 2025):

@olegprivate @falendary

Terminology:
1. Workspace -> Space: as of now in the system we have Space not a Workspace. We either need to change it all to Workspace or call them Space.
2. Module -> Add-on: as of now we call them Add-ons.
All operations for cancel, deactivation, refund or tenant migration of the assigned Space are only possible if we can restrict access to the expired add-on. As of now - no such mechanism exists and it's not clear what should happen when the validation API returns a "valid: false" response.
License dashboard should group licenses by add-ons because one user may have several licenses for one add-on.
Space license dashboard should be the same as in finmars.com
For described approach we need to implement Space register mechanism to assign license keys, and it's unclear how to determine UID for Spaces for self-hosted deployments with no Internet or we need to clearly say that we do not support add-ons for them.

@sergeiosipov commented on GitHub (Aug 9, 2025): @olegprivate @falendary 1. Terminology: 1. Workspace -> **Space**: as of now in the system we have Space not a Workspace. We either need to change it all to Workspace or call them Space. 2. Module -> **Add-on**: as of now we call them Add-ons. 3. All operations for cancel, deactivation, refund or tenant migration of the assigned Space are **only possible if we can restrict access to the expired add-on**. As of now - no such mechanism exists and it's not clear what should happen when the validation API returns a "valid: false" response. 4. License dashboard should **group licenses by add-ons** because one user may have several licenses for one add-on. 5. Space license dashboard should be the same as in finmars.com 6. For described approach we need to implement **Space register mechanism** to assign license keys, and it's unclear how to determine UID for Spaces for self-hosted deployments with no Internet or we need to clearly say that we do not support add-ons for them.

kerem commented

2026-03-03 11:58:30 +03:00

Author

Owner

@olegprivate commented on GitHub (Aug 11, 2025):

Agree to all.
p.5 - we can generate a unique UUID of Space during the deploy. And use it when we assign license key. It can be subject to abuse, but given that we log all interactions with the license server: Finmars ID, License key, Space ID, IP address - I ythink we will be able to prevent the abuse.

And yes - we need a tool to restrict the module usage with expired keys somehow. I think that we can implement some simple check inside the finmars. It can be "hacked" - but I won't consider it a serious threat for now

@olegprivate commented on GitHub (Aug 11, 2025): Agree to all. p.5 - we can generate a unique UUID of Space during the deploy. And use it when we assign license key. It can be subject to abuse, but given that we log all interactions with the license server: Finmars ID, License key, Space ID, IP address - I ythink we will be able to prevent the abuse. And yes - we need a tool to restrict the module usage with expired keys somehow. I think that we can implement some simple check inside the finmars. It can be "hacked" - but I won't consider it a serious threat for now

kerem referenced this issue

2026-03-03 11:59:01 +03:00

[PR #29] [MERGED] Update dockerfile #128