foundation-license — IMP FORGE

Capability-based license enforcement

Tier	foundation
Role	unclassified (baselined)
Path	`crates/foundation/license`
Edition	2021
Targets	foundation_license
Public items	125 across 12 modules
Tests	43

What it is for

# foundation-license

Capability-based license enforcement library crate for Rust applications.

This crate provides a server-side license enforcement system that:

Validates signed license artifacts (Ed25519)
Exposes a read-only interface to license capabilities
Enforces capabilities at service and API boundaries
Supports multiple license tiers with different modules/features
Integrates with audit logging

Architecture

License enforcement follows a layered approach:

1. Service Layer (Primary) - Every privileged operation calls enforce_capability() 2. API Layer (Secondary) - Axum middleware gates entire route trees 3. Admin UI (Tertiary) - UI reflects license state but does not enforce

The server is always authoritative. UI gating is convenience only.

Quick Start

use foundation_license::{initialize_license, enforce_capability, LICENSE_PUBLIC_KEY};

// Initialize at startup (once)
initialize_license("license.json", &LICENSE_PUBLIC_KEY, None);

// Enforce in service methods
pub async fn create_document(input: Input) -> Result<Document, Error> {
enforce_capability("module:documents", Some(&user_id))?;
// ... proceed with operation
}

License File Format

Licenses are JSON files containing a base64-encoded payload and signature:

{
"payload": "base64-encoded-json-payload",
"signature": "base64-encoded-ed25519-signature",
"version": 1
}

Capabilities

Capabilities follow a namespace:name pattern:

module:content - Access to the content module
feature:sso - Access to SSO feature
limit:max_users - A numeric limit (value stored separately)

Error Handling

All errors include:

Stable error code (e.g., LICENSE_FORBIDDEN)
Human-readable message (neutral, professional)
Required capability (if applicable)
Current license status

Security Notes

The public key is compiled into the binary
License state cannot be mutated after initialization
All enforcement is server-side
Audit events are emitted for all enforcement decisions

Capabilities

`CapabilityCheckResponse`

License status API

Item
`pub struct CapabilityCheckResponse`
`CapabilityCheckResponse :: fn check(capability : & str) -> Self`

`LicenseStatusResponse`

License status API

Item
`pub struct LicenseStatusResponse`
`LicenseStatusResponse :: fn from_current_state() -> Self`

`LimitSummary`

License status API

Item
`pub struct LimitSummary`

`api::handlers (other)`

Axum handlers for license API endpoints.

Item
`async fn get_license_status() -> Json <LicenseStatusResponse>`
`async fn check_capability(Path(capability) : Path <String>,) ->(StatusCode, Json <CapabilityCheckResponse>)`

`audit (other)`

License audit event types

Item
`fn audit_license_loaded(status : LicenseStatus)`
`fn audit_capability_denied(capability : & str, status : LicenseStatus, actor : Option <& str>)`
`fn audit_capability_granted(capability : & str, status : LicenseStatus, actor : Option <& str>)`
`fn audit_limit_exceeded(limit_name : & str, current : u64, maximum : u64, status : LicenseStatus, actor : Option <& str>,)`

`AuditOutcome`

License audit event types

Item
`pub enum AuditOutcome`

`LicenseAuditEntry`

License audit event types

Item
`pub struct LicenseAuditEntry`
`LicenseAuditEntry :: fn new(event : LicenseAuditEvent, status : LicenseStatus, outcome : AuditOutcome) -> Self`
`LicenseAuditEntry :: fn with_actor(mut self, actor : impl Into <String>) -> Self`
`LicenseAuditEntry :: fn with_capability(mut self, capability : impl Into <String>) -> Self`
`LicenseAuditEntry :: fn with_context(mut self, context : serde_json::Value) -> Self`
`LicenseAuditEntry :: fn emit(self)`

`LicenseAuditEvent`

License audit event types

Item
`pub enum LicenseAuditEvent`

`enforcement (other)`

License enforcement mechanisms

Item
`fn enforce_capability(capability : & str, actor : Option <& str>) -> LicenseResult <()>`
`fn enforce_limit(limit_name : & str, current_value : u64, actor : Option <& str>,) -> LicenseResult <()>`
`fn has_capability(capability : & str) -> bool`
`fn license_status() -> LicenseStatus`
`fn is_licensed() -> bool`

`CapabilityGuard`

License enforcement mechanisms

Item
`pub struct CapabilityGuard`
`CapabilityGuard :: fn acquire(capability : & str, actor : Option <& str>) -> LicenseResult <Self>`
`CapabilityGuard :: fn capability(& self) -> & str`

`EnforcementDenial`

License enforcement mechanisms

Item
`pub struct EnforcementDenial`
`EnforcementDenial :: fn from(error : & LicenseError) -> Self`

`LicenseError`

License error types

Item
`pub enum LicenseError`
`LicenseError :: fn error_code(& self) -> & 'static str`
`LicenseError :: fn required_capability(& self) -> Option <& str>`
`LicenseError :: fn license_status(& self) -> LicenseStatus`
`LicenseError :: fn user_message(& self) -> & str`

`LicenseResult`

License error types

Item
`pub type LicenseResult<T>: Result <T, LicenseError>`

`hardware (other)`

Hardware node-locking + grace-then-fail entitlement (ADR 0018).

Item
`pub const ACCEPT_THRESHOLD: u32`
`fn match_hardware(licensed : & HardwareBinding, observed : & BTreeMap <String, String>,) -> HardwareMatch`

`AccessMode`

Hardware node-locking + grace-then-fail entitlement (ADR 0018).

Item
`pub enum AccessMode`

`Entitlement`

Hardware node-locking + grace-then-fail entitlement (ADR 0018).

Item
`pub struct Entitlement`
`Entitlement :: fn emergency(reason : impl Into <String>) -> Self`
`fn evaluate(payload : & LicensePayload, signature_valid : bool, observed : Option <& BTreeMap <String, String>>, now : DateTime <Utc>, hardware_grace_until : Option <DateTime <Utc>>,) -> Entitlement`

`HardwareBinding`

Hardware node-locking + grace-then-fail entitlement (ADR 0018).

Item
`pub struct HardwareBinding`

`HardwareMatch`

Hardware node-locking + grace-then-fail entitlement (ADR 0018).

Item
`pub struct HardwareMatch`

`middleware (other)`

Axum middleware for license enforcement

Item
`async fn require_valid_license(request : Request, next : Next) -> Response`
`fn require_capability_middleware(capability : & 'static str,) -> impl Fn(Request, Next) -> std::pin::Pin <Box <dyn std::future::Future <Output = Response> + Send>> + Clone + Send + 'static`

`LicenseErrorResponse`

Axum middleware for license enforcement

Item
`pub struct LicenseErrorResponse`
`LicenseErrorResponse :: fn into_response(self) -> Response`
`LicenseErrorResponse :: fn from(error : LicenseError) -> Self`

`LicenseRouterExt`

Axum middleware for license enforcement

Item
`pub trait LicenseRouterExt`

`RequireCapability`

Axum middleware for license enforcement

Item
`pub struct RequireCapability`
`RequireCapability :: async fn from_request_parts(_parts : & mut axum::http::request::Parts, _state : & S,) -> Result <Self, Self::Rejection>`

`axum::Router<S>`

Axum middleware for license enforcement

Item
`axum::Router<S> :: fn require_license(self) -> Self`
`axum::Router<S> :: fn require_capability(self, capability : & 'static str) -> Self`

`LicenseState:LicenseState`

License state management

Item
`pub struct LicenseState`

`LicenseState:check`

License state management

Item
`LicenseState :: fn check_limit(& self, name : & str, current : u64) -> LicenseResult <()>`

`LicenseState:create`

License state management

Item
`fn create_test_state(payload : LicensePayload) -> LicenseState`

`LicenseState:customer`

License state management

Item
`LicenseState :: fn customer_id(& self) -> Option <& str>`

`LicenseState:enabled`

License state management

Item
`LicenseState :: fn enabled_modules(& self) -> Vec <& str>`
`LicenseState :: fn enabled_features(& self) -> Vec <& str>`

`LicenseState:expires`

License state management

Item
`LicenseState :: fn expires_at(& self) -> Option <DateTime <Utc>>`

`LicenseState:get`

License state management

Item
`fn get_license() -> & 'static LicenseState`

`LicenseState:has`

License state management

Item
`LicenseState :: fn has_capability(& self, cap : & str) -> bool`

`LicenseState:initialize`

License state management

Item
`fn initialize_license(path : impl AsRef <Path>, public_key : & u8; 32, environment : Option <& str>,) -> & 'static LicenseState`

`LicenseState:is`

License state management

Item
`LicenseState :: fn is_valid(& self) -> bool`

`LicenseState:license`

License state management

Item
`LicenseState :: fn license_id(& self) -> Option <uuid::Uuid>`

`LicenseState:limit`

License state management

Item
`LicenseState :: fn limit(& self, name : & str) -> Option <u64>`

`LicenseState:limits`

License state management

Item
`LicenseState :: fn limits(& self) -> std::collections::HashMap <String, u64>`

`LicenseState:loaded`

License state management

Item
`LicenseState :: fn loaded_at(& self) -> DateTime <Utc>`

`LicenseState:require`

License state management

Item
`LicenseState :: fn require(& self, cap : & str) -> LicenseResult <()>`

`LicenseState:status`

License state management

Item
`LicenseState :: fn status(& self) -> LicenseStatus`

`LicenseState:try`

License state management

Item
`fn try_get_license() -> Option <& 'static LicenseState>`