stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity

up

Browse Source
This commit is contained in:
master
2025-10-12 20:37:18 +03:00
parent 016c5a3fe7
commit d3a98326d1
306 changed files with 21409 additions and 4449 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/assets/authority/authority-plugin-lifecycle.mmd Normal file
View File

@@ -0,0 +1,17 @@
%% Authority plug-in lifecycle sequence diagram (Mermaid)
flowchart LR
manifest[[Plugin Manifest<br/>etc/authority.plugins/*.yaml]]
loader[AuthorityPluginConfigurationLoader<br/>binds and validates options]
scanner[PluginHost Assembly Scan<br/>StellaOps.Authority.Plugin.*]
registrar[IAuthorityPluginRegistrar<br/>registers services & health checks]
runtime[Identity Provider Plugin<br/>IIdentityProviderPlugin surface]
capabilities{Capability Metadata<br/>password/mfa/bootstrap/clientProvisioning}
storage[(Credential Store<br/>Mongo collections or custom backend)]
telemetry[[Structured Logs & Metrics<br/>authority.*]]
manifest --> loader --> scanner --> registrar --> runtime --> storage
scanner --> capabilities
capabilities --> runtime
runtime --> telemetry
loader -. emits deterministic config hashes .-> telemetry
storage -. readiness probes .-> runtime

91
docs/assets/authority/authority-plugin-lifecycle.svg Normal file
View File

@@ -0,0 +1,91 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 320" role="img">
<title>Authority plug-in lifecycle: manifest to runtime</title>
<defs>
<style>
.node { fill: #0f172a; stroke: #1e293b; stroke-width: 2; rx: 14; ry: 14; }
.node text { fill: #f1f5f9; font: 16px/1.4 "Segoe UI", sans-serif; }
.accent { fill: #1e3a8a; stroke: #1d4ed8; }
.accent text { fill: #e2e8f0; }
.note { fill: #0f766e; stroke: #134e4a; }
.note text { fill: #ecfeff; }
.caption { fill: #111827; font: bold 18px "Segoe UI", sans-serif; }
.annotation { fill: #475569; font: 14px "Segoe UI", sans-serif; }
</style>
<marker id="arrow" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto">
<path d="M0,0 L12,6 L0,12 z" fill="#1d4ed8" />
</marker>
</defs>
<text class="caption" x="40" y="36">Authority plug-in lifecycle</text>
<!-- Nodes -->
<g transform="translate(40,70)">
<rect class="node" width="200" height="110" />
<text x="20" y="32">Manifest YAML</text>
<text x="20" y="58">etc/authority.plugins/*.yaml</text>
<text x="20" y="84">Deterministic hashes</text>
</g>
<g transform="translate(280,70)">
<rect class="node accent" width="220" height="110" />
<text x="20" y="32">AuthorityPluginConfigurationLoader</text>
<text x="20" y="58">binds + validates options</text>
<text x="20" y="84">logs config fingerprints</text>
</g>
<g transform="translate(540,70)">
<rect class="node" width="220" height="110" />
<text x="20" y="32">PluginHost assembly scan</text>
<text x="20" y="58">StellaOps.Authority.Plugin.*</text>
<text x="20" y="84">loads IAuthorityPluginRegistrar</text>
</g>
<g transform="translate(800,70)">
<rect class="node accent" width="220" height="110" />
<text x="20" y="32">IAuthorityPluginRegistrar</text>
<text x="20" y="58">register services &amp; health checks</text>
<text x="20" y="84">publish capability metadata</text>
</g>
<g transform="translate(1060,70)">
<rect class="node" width="220" height="110" />
<text x="20" y="32">Identity Provider plug-in</text>
<text x="20" y="58">IIdentityProviderPlugin</text>
<text x="20" y="84">ready/readiness probes</text>
</g>
<!-- Supporting nodes -->
<g transform="translate(420,210)">
<rect class="node note" width="240" height="96" />
<text x="20" y="32">Capability metadata broadcast</text>
<text x="20" y="58">password / mfa / bootstrap / clientProvisioning</text>
</g>
<g transform="translate(760,210)">
<rect class="node note" width="240" height="96" />
<text x="20" y="32">Credential &amp; audit storage</text>
<text x="20" y="58">Mongo collections or custom backend</text>
<text x="20" y="84">queried in readiness probes</text>
</g>
<g transform="translate(1040,210)">
<rect class="node note" width="180" height="96" />
<text x="20" y="32">Telemetry output</text>
<text x="20" y="58">logs + metrics with correlation IDs</text>
</g>
<!-- Arrows -->
<path d="M240,125 H280" stroke="#1d4ed8" stroke-width="3" fill="none" marker-end="url(#arrow)" />
<path d="M500,125 H540" stroke="#1d4ed8" stroke-width="3" fill="none" marker-end="url(#arrow)" />
<path d="M760,125 H800" stroke="#1d4ed8" stroke-width="3" fill="none" marker-end="url(#arrow)" />
<path d="M1020,125 H1060" stroke="#1d4ed8" stroke-width="3" fill="none" marker-end="url(#arrow)" />
<path d="M650,180 V210" stroke="#22d3ee" stroke-width="3" fill="none" marker-end="url(#arrow)" />
<path d="M920,180 V210" stroke="#22d3ee" stroke-width="3" fill="none" marker-end="url(#arrow)" />
<path d="M1180,180 V210" stroke="#22d3ee" stroke-width="3" fill="none" marker-end="url(#arrow)" />
<text class="annotation" x="320" y="56">1. Configuration</text>
<text class="annotation" x="600" y="56">2. Assembly discovery</text>
<text class="annotation" x="860" y="56">3. Registrar execution</text>
<text class="annotation" x="1120" y="56">4. Runtime surface</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 4.0 KiB

27
docs/assets/authority/authority-rate-limit-flow.mmd Normal file
View File

@@ -0,0 +1,27 @@
%% Rate limit and lockout interplay for Standard plug-in (Mermaid)
sequenceDiagram
autonumber
participant Client as Client/App
participant Host as Authority Host
participant Limiter as Rate Limiter Middleware
participant Plugin as Standard Plugin
participant Store as Credential Store / Lockout State
Client->>Host: POST /token (client_id, credentials)
Host->>Limiter: Check quota (client_id + remote_ip)
alt quota exceeded
Limiter-->>Host: Reject (429, retryAfter)
Host-->>Client: 429 Too Many Requests\nRetry-After header with limiter tags
else quota ok
Limiter-->>Host: Allow (remaining tokens)
Host->>Plugin: VerifyCredentials(subject)
Plugin->>Store: Load hashed password + lockout counters
Store-->>Plugin: Credential result + deterministic counter
alt lockout threshold reached
Plugin-->>Host: Locked (retryAfter=lockoutWindow)
Host-->>Client: 423 Locked\nRetry-After header + `authority.lockout` tag
else valid credentials
Plugin-->>Host: Success (issue tokens)
Host-->>Client: 200 OK + tokens + limiter metadata
end
end

105
docs/assets/authority/authority-rate-limit-flow.svg Normal file
View File

@@ -0,0 +1,105 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1180 400" role="img">
<title>Authority rate limit and lockout flow</title>
<defs>
<style>
.lane { fill: #0f172a; }
.lane text { fill: #e2e8f0; font: bold 18px "Segoe UI", sans-serif; }
.step { fill: #1f2937; stroke: #1e3a8a; stroke-width: 2; rx: 12; ry: 12; }
.step text { fill: #f8fafc; font: 15px "Segoe UI", sans-serif; }
.decision { fill: #0f766e; stroke: #0d9488; stroke-width: 2; rx: 12; ry: 12; }
.decision text { fill: #ecfeff; font: 15px "Segoe UI", sans-serif; }
.note { fill: #1e293b; font: italic 14px "Segoe UI", sans-serif; }
</style>
<marker id="arrow-blue" markerWidth="11" markerHeight="11" refX="10" refY="6" orient="auto">
<path d="M0,0 L11,6 L0,12 z" fill="#2563eb" />
</marker>
<marker id="arrow-green" markerWidth="11" markerHeight="11" refX="10" refY="6" orient="auto">
<path d="M0,0 L11,6 L0,12 z" fill="#0d9488" />
</marker>
<marker id="arrow-red" markerWidth="11" markerHeight="11" refX="10" refY="6" orient="auto">
<path d="M0,0 L11,6 L0,12 z" fill="#dc2626" />
</marker>
</defs>
<rect class="lane" x="40" y="20" width="160" height="40" rx="8" />
<text x="60" y="48">Client / App</text>
<rect class="lane" x="300" y="20" width="200" height="40" rx="8" />
<text x="320" y="48">Authority Host</text>
<rect class="lane" x="560" y="20" width="210" height="40" rx="8" />
<text x="580" y="48">Rate Limiter</text>
<rect class="lane" x="840" y="20" width="150" height="40" rx="8" />
<text x="860" y="48">Standard Plug-in</text>
<rect class="lane" x="1040" y="20" width="120" height="40" rx="8" />
<text x="1060" y="48">Credential Store</text>
<!-- Flow steps -->
<g transform="translate(40,90)">
<rect class="step" width="220" height="90" />
<text x="20" y="36">POST /token request</text>
<text x="20" y="64">client_id + subject creds</text>
</g>
<g transform="translate(300,90)">
<rect class="step" width="220" height="90" />
<text x="20" y="36">Authority middleware</text>
<text x="20" y="64">enriches context tags</text>
</g>
<g transform="translate(580,90)">
<rect class="step" width="220" height="90" />
<text x="20" y="36">Rate limiter window</text>
<text x="20" y="64">client_id + IP keyed</text>
</g>
<g transform="translate(580,210)">
<rect class="decision" width="220" height="90" />
<text x="20" y="36">Quota exceeded?</text>
<text x="20" y="64">emit Retry-After &amp; tags</text>
</g>
<g transform="translate(580,330)">
<rect class="step" width="220" height="90" />
<text x="20" y="36">Quota OK</text>
<text x="20" y="64">pass remaining tokens</text>
</g>
<g transform="translate(840,210)">
<rect class="step" width="220" height="90" />
<text x="20" y="36">Verify credentials</text>
<text x="20" y="64">hash compare + audit tags</text>
</g>
<g transform="translate(1040,210)">
<rect class="step" width="220" height="90" />
<text x="20" y="36">Load lockout state</text>
<text x="20" y="64">deterministic counters</text>
</g>
<g transform="translate(840,330)">
<rect class="decision" width="220" height="90" />
<text x="20" y="36">Lockout threshold hit?</text>
<text x="20" y="64">follow dedup precedence</text>
</g>
<g transform="translate(300,330)">
<rect class="step" width="220" height="90" />
<text x="20" y="36">Issue tokens or errors</text>
<text x="20" y="64">include limiter metadata</text>
</g>
<!-- Arrows -->
<path d="M260,135 H300" stroke="#2563eb" stroke-width="3" fill="none" marker-end="url(#arrow-blue)" />
<path d="M520,135 H580" stroke="#2563eb" stroke-width="3" fill="none" marker-end="url(#arrow-blue)" />
<path d="M670,180 V210" stroke="#2563eb" stroke-width="3" fill="none" marker-end="url(#arrow-blue)" />
<path d="M670,300 V330" stroke="#2563eb" stroke-width="3" fill="none" marker-end="url(#arrow-blue)" />
<path d="M800,375 H840" stroke="#2563eb" stroke-width="3" fill="none" marker-end="url(#arrow-blue)" />
<path d="M960,255 H1040" stroke="#2563eb" stroke-width="3" fill="none" marker-end="url(#arrow-blue)" />
<path d="M960,375 H840" stroke="#0d9488" stroke-width="3" fill="none" marker-end="url(#arrow-green)" />
<path d="M670,255 H520" stroke="#dc2626" stroke-width="3" fill="none" marker-end="url(#arrow-red)" />
<path d="M520,375 H300" stroke="#2563eb" stroke-width="3" fill="none" marker-end="url(#arrow-blue)" />
<path d="M260,375 H40" stroke="#2563eb" stroke-width="3" fill="none" marker-end="url(#arrow-blue)" />
<!-- Notes -->
<text class="note" x="40" y="210">429 path → add `authority.client_id`, `authority.remote_ip` tags for dashboards.</text>
<text class="note" x="40" y="240">Lockout path → reuse precedence strategy from Feedser dedup (see DEDUP_CONFLICTS_RESOLUTION_ALGO.md).</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 4.8 KiB