Eve library

OSHUN Entitlement Schema

Spec

Revision 1

On this page

Status: Active
Owner: OSHUN Platform Engineering
Last Updated: February 16, 2026
Related: libs/oshun/auth/src/entitlements.ts, OSHUN_APP_TODOS.md

Purpose#

Define one shared entitlement schema for OSHUN shell and adapters:

  • tier definitions (free, pro, premium)
  • per-domain minimum access tiers
  • per-feature tier gates and optional usage limits
  • deterministic evaluation helpers for domain/feature access

Tier Model#

Tier Order Intended Access
free 0 baseline access across all domains
pro 1 advanced features and higher usage limits
premium 2 full access and unlimited premium features

Domain Policies#

The schema currently defines policies for:

  • tara
  • veritas
  • nyx
  • arete

Each policy includes:

  • minimumTier for domain-level entry
  • features[] where each feature has:
    • featureKey
    • minimumTier
    • limit (number | null)
    • period (daily | monthly | lifetime)

Evaluation Contracts#

libs/oshun/auth/src/entitlements.ts exposes:

  • evaluateDomainAccess(...)
  • evaluateFeatureAccess(...)
  • getEffectiveTierForDomain(...)
  • hasTierAccess(...)
  • getDomainEntitlementPolicy(...)
  • listDomainEntitlementPolicies(...)

Evaluation reasons are normalized to:

  • allowed
  • insufficient_tier
  • domain_suspended
  • feature_not_found
  • limit_exceeded

Notes#

  • This schema is the canonical source for shell-side entitlement checks.
  • Server-side authorization remains authoritative; client checks are UX gates.
  • Future tiers (for example student/family) should be added by extending:
    • tier order
    • tier definitions
    • domain feature policy mappings