Skip to content

index.md

Latest commit

 

History

History
106 lines (77 loc) · 5.16 KB

index.md

File metadata and controls

106 lines (77 loc) · 5.16 KB

UMS SDK — Portal

Language: English | Español

The UMS SDK is the official client integration surface for the User Management System. It packages everything a client system needs to authenticate against UMS, consume the AuthorizationGraph, and enforce authorization decisions locally — across three runtimes that share a single canonical contract.

Status: Documentation phase (Phase A) — implementation begins after documentation is reviewed and merged.

What the SDK gives you

After a client system authenticates with UMS, it receives an AuthorizationGraph (see ADR-0071 and auth-graph.md). The SDK provides:

  • Typed deserialization of the graph in your runtime's idiomatic types.
  • A pure validator that applies the deny-wins / override-takes-precedence rules and validUntil expiry check — the same rules implemented identically across runtimes.
  • Declarative authorization via attributes (.NET) or decorators (TypeScript / NestJS) for the four canonical primitives:
    • RequiresScope("RESOURCE.ACTION")
    • RequiresMenuOption("OPTION_CODE")
    • RequiresDomainAccess("RESOURCE", "ACTION")
    • RequiresFeatureFlag("FLAG_CODE")
  • Testing utilities to build fake graphs for unit tests of consumer code without spinning up UMS.

Layout

docs/sdk/                        ← documentation (English)
├── index.md                     ← this file
├── contracts/                   ← canonical contract (language-neutral)
│   ├── schema-overview.md
│   ├── error-codes.md
│   ├── versioning.md
│   ├── fixtures.md
│   └── compatibility-matrix.md
├── dotnet/                      ← .NET SDK guide
│   ├── README.md
│   └── quickstart.md
├── typescript/                  ← TypeScript SDK guide
│   ├── README.md
│   └── quickstart.md
└── nestjs/                      ← NestJS SDK guide
    ├── README.md
    └── quickstart.md

Spanish mirror lives under docs/sdk-es/. Source code lives at src/libs/sdk/ (separate from documentation — see ADR-0073).

Distributions

Distribution Registry Packages Status
.NET NuGet Ums.Sdk.Contracts, Ums.Sdk.Authorization, Ums.Sdk.Authorization.Aop, Ums.Sdk.Authorization.Testing Documentation
TypeScript npm @ums/sdk-contracts, @ums/sdk-authorization, @ums/sdk-testing Documentation
NestJS npm @ums/sdk-nestjs (extends @ums/sdk-authorization) Documentation

JavaScript consumers (no TypeScript) use the @ums/* packages directly — they ship both .js and .d.ts, so JS works with full functionality, only losing compile-time typing.

Quick Links

For integrators

For SDK contributors

Conceptual Model

All three runtimes implement the same four authorization primitives, mapped one-to-one to the four authorization-bearing sections of the graph:

Primitive Graph section Decision rule
RequiresScope scopes[] Scope present AND not in denies
RequiresMenuOption menuAccess[].…options[] Option resolves to effect = "Allow"
RequiresDomainAccess domainPermissions[] Resource+action resolves to effect = "Allow"
RequiresFeatureFlag featureFlags[] Flag found with isEnabled = true

Universal pre-check: if graph.validUntil < now, decision is Expired regardless of content. Deny always wins over Allow (Axiom A3).

References