Softanza
StartFrançais
Softanza
StartFrançais
Reference · I/O, formats, extensibility, media

Security & governance

59 functions in 39 classes, grouped by what they do, each with the explanation the library gives of itself.

The story of this area, for a general reader: what a crafter does with it, an example run and its rated lanes, is on its Platform page.

The functions, by what they do

Testing and checking

  • HasTotp A user may add an authenticator-app second factor. Enrollment is TWO steps so a mis-scanned secret can never lock the user out: EnableTotp issues a secret stored UNCONFIRMED (not yet enforced -- plain Login still works); ConfirmTotp proves the app is in sync, enforces the factor, and hands back one-time recovery codes. From then on a plain Login is refused for that user and LoginTwoFactor is the only door. The factor is stzTotp; per-user state (secret + recovery-code hashes) lives in the store. whether a user has a CONFIRMED (enforced) second factor. in stzAuth
  • IsLockedOut lockout queries in stzAuth
  • IsRefusal "granted" and "observed" are not refusals; "refused" and "failed" are. Written as an explicit list rather than `!= "granted"` because a fourth outcome arrived later (see Observed) and the negative form would have silently swept it in -- an expired session would have counted as a refusal in every pivot. in stzSecurityEvent
  • CheckAgainst judging ----------------------------------------------------- Judge a ledger. Returns findings in the unified rule shape -- hand them to stzRuleReport.Ingest(). in stzDetection
  • Check watching ----------------------------------------------------- One pass: judge, then fire only what CHANGED. Returns the number of NEW firings. in stzSecuritySentinel
  • Has safe reads (never leak a value) in stzSecretStore
  • IsRevealableBy may this actor reveal this secret? (no side effect, no audit entry.) in stzSecretStore
  • IsResolvableBy does the secret resolve to a non-empty value? Governed. A vault-sourced secret needs a resolver, so it is not resolvable this way. in stzSecret
  • IsWellFormed a JWS is exactly three dot-separated parts. in stzJwt
  • IsClean clean = nothing flagged at all. in stzSecurityPosture
  • IsSound sound = no ERROR findings (warnings are advisory, not blocking). in stzSecurityPosture
  • IsExpiredAt expired at a given "now" (epoch seconds)? A 0 expiry never expires. The caller passes the clock -- the class holds no wall-clock of its own. in stzToken

Finding

  • LastCut the graph edges the last revocation removed, as [ from, label, to ] in stzCapabilityResponder
  • LastStatus the HTTP status of the last request (0 = no answer) -- for diagnostics in stzVaultHttpResolver

Counting and measuring

  • Size Events still retained in the window. in stzSecurityLedger
  • Count Events ever recorded (keeps counting past capacity). in stzSecurityLedger
  • NumberOfPendingCodes housekeeping + introspection in stzOidcProvider

Replacing and setting

  • SetStore Persist through a chosen store (e.g. StzAuthDbStoreQ("auth.db")). The default is in-memory. Pass a DB store for durability -- its sqlite is an engine handle, so the held copy still writes the same database. in stzAuth
  • SetIdleTTL idle timeout: a session dies if untouched for this many seconds (0 = off). Every successful validation slides the window (touches last-seen). in stzAuth
  • SetMailPort passwordless config (mail port + magic-link) -------------------- bind the mail PORT passwordless flows send through -- a stzMailSandbox in dev (captured + assertable), your SMTP adapter at deploy. Any object with Send(to, subject, body) works. in stzAuth
  • SetOidcClient "Sign in with Google / Okta / Entra". The provider proves who the user is and hands back an id-token; stzAuth VERIFIES it locally (signature against the provider's published key, then issuer / audience / expiry / nonce -- see stzOidcClient) and, only then, opens a normal Softanza session. From that point the user is indistinguishable from any other: the same session, the same roles, the same governance ACTOR (phase 5). An external identity is a way IN, not a separate kind of citizen. in stzAuth
  • SetSessionTTL how long a new session lives, in seconds (0 = no expiry). Existing sessions keep the TTL they were issued with. in stzAuth
  • ChangePassword change a password (the current one must be presented). TRUE on success. in stzAuth
  • SetMaxAttempts brute-force lockout config in stzAuth
  • SetPasswordlessTTL how long a magic link / email-OTP stays valid (seconds). in stzAuth
  • SetMagicLinkBaseUrl the app URL a magic link points at; the token is appended as ?token=... (or &token=... if the URL already has a query). "" -> a softanza:// URI. in stzAuth
  • SetPasswordResetTTL The recovery path is where accounts are taken over, so it holds the same line as every other door: - ENUMERATION-SAFE: the request answers the same whether or not the email has an account; a link is minted and mailed only for a real one; - the token is 256 random bits, stored ONLY as its sha256, ONE-TIME and short-lived (30 min); a newer request cancels the older link; - a reset stores an Argon2id hash and ENDS EVERY SESSION -- an attacker holding one is signed out with the rest; - it does NOT sign anybody in: the next login still asks for the second factor when 2FA is on; - it cannot undo CONTAINMENT: an account a responder or an operator locked (LockAccount) is refused; a lockout from failed attempts, which is what a forgotten password produces, is cleared. in stzAuth
  • SetOidcAutoProvision create a local account the first time an external identity signs in (the usual want). Turn it off to admit only pre-provisioned users. in stzAuth
  • SetPasskeyRelyingParty A passkey replaces the password with a key pair the user's DEVICE holds: the private half never leaves the authenticator, so there is nothing to phish, reuse, or steal in a breach. Registration stores the public key; login is a signature over a fresh challenge. The relying-party judgement (origin, challenge, user presence, the cloned-authenticator counter) lives in stzPasskeyServer; the credentials live in the store, one row per DEVICE. bind the relying party: the domain credentials are bound to, and the exact origin the browser reports. The origin check is what makes a passkey unphishable, so both are required. in stzAuth

and 4 more in the reference

Removing

  • RemovePasskey un-enroll one device (losing a key should not cost the account). in stzAuth

Adding

  • AppendCanonical Append a canonical line directly -- the acquisition path (I8), used when rebuilding a ledger from verified evidence. The chain is recomputed here; it does not carry the original file's. in stzSecurityLedger
  • AddActor nodes ----------------------------------------------------------- posture: trusted | external | sandboxed in stzSecurityGraph
  • AddCapability capabilities are auto-created by Holds/Grants, but may be declared too in stzSecurityGraph
  • AddKey the provider's signing keys (its JWKS) -------------------------- add one key: [ :kid, :kty, :x, :y ] (EC) or [ :kid, :kty, :n, :e ] (RSA). in stzOidcClient
  • AddLiveActor a live actor whose capability kinds this responder may revoke in stzCapabilityResponder
  • Add add one responder BY REFERENCE (see StzResponderSet) in stzResponderSet

Ordering and moving

  • RotateSession ROTATE a session's token (session-fixation defense): after a privilege change -- 2FA, password change, elevation -- issue a NEW token for the same user + device, void the OLD one, and return the new token ("" if invalid). The pre-elevation token can no longer be replayed. in stzAuth
  • RotateKey Start signing with a NEW key. The previous public key stays in the JWKS, so tokens already issued keep verifying until they expire -- rotation without an outage. A 32-byte hex seed makes it deterministic ("" = random). in stzOidcProvider
  • Rotate rotate a secret: replace whatever is registered under poNewSecret's name. in stzSecretStore
  • RotateToFresh ROTATE IN PLACE, to a fresh random value -- containment's :RotateSecret. Only a secret whose value THIS store holds (a :literal) can be regenerated here: a key it issues, a token it signs with. A secret that lives in an environment variable, a file or a vault is not this store's to change -- that REFUSES loudly, naming where to rotate it, rather than pretending. Creating a credential is an effect, so poActor passes the same gate as a reveal. The new value is 32 random bytes as 64 hex characters; kind and name are kept (a token's expiry is cleared -- a new value is a new credential). Returns This. in stzSecretStore
  • RotateSecret Not this responder's to perform: authentication owns accounts and sessions, nothing else. A plan that proposes these needs another responder -- refused loudly, never pretended. in stzAuthResponder

Converting

  • AsInfo severity (the catalog's default, overridable) in stzSecurityEvent
  • AsLine legibility ------------------------------------------------- One line, human first: who did what to which, how it ended, why. in stzSecurityEvent
  • ToOcsfJson OCSF as one JSON array (the batch form). in stzSecurityLedger
  • ToOcsfNdJson OCSF, newline-delimited: what a collector ingests as a stream. in stzSecurityLedger
  • ToOtelLogsJson The OTLP logs envelope -- the same shape stzLog ships (perf P9), so security events and log lines arrive at one collector looking like what they are: records of the same run, sharing trace ids. in stzSecurityLedger
  • FromCase building ----------------------------------------------------- Build from a sentinel case (I4) plus the ledger it fired on. in stzIncident
  • FromFinding Build from a bare finding (a detection judged outside a sentinel). in stzIncident
  • ToOcsfFindingJson interop: the incident as an OCSF finding (I7) ---------------- OCSF class 2001, Security Finding -- the class a SIEM expects for "something was concluded", as opposed to the raw events (which the ledger exports separately). The attack path, blast radius and trace ids ride in `unmapped`, which is what that field is for. in stzIncident
  • FromLiteral source setters (Q-fluent: return the object AFTER acting) -------- dev/test only: the value inline. Still redacted in every output; only Reveal(effectfulActor) returns it. in stzSecret

Reading and writing

  • OpenVictimSession containment: the loop closes ---------------------------------- Log the victim in for real BEFORE the attack, so containment has a live session to end and the drill can prove it ended. in stzSecurityDrill
  • SaveSealedTo Write the whole store to pcPath as ONE authenticated-encryption blob (XChaCha20-Poly1305), keyed by poKeySecret -- itself a stzSecret, whose 64-hex value comes from wherever secrets come from (an environment variable, a file, a vault). Literal values are sealed; env / file / vault secrets are saved as their POINTER only -- the plaintext never leaves its source. The store's name is bound as the aad, so one store's file cannot be passed off as another's. Sealing reads every literal value, so poActor passes the same gate as a reveal. in stzSecretStore
  • SaveSealedToVia As SaveSealedTo, with the KEY fetched through a vault resolver (R4). in stzSecretStore
  • WriteTo Seal the ledger to a file, attested by this actor. Returns TRUE when written; FALSE (with the refusal recorded) when the actor may not. in stzSecurityAttestation

Walking and applying

  • ExecuteOn the crossing (admission is governed) -------------------------- Apply the plan to a responder. Returns the number of actions committed; 0 with a full refusal audit when the actor may not. in stzResponsePlan

The explanations are the ones the library gives of itself, read from its documentation comments on 2026-10-01 04:14, from the library at commit 0e72e2e2c, by the library's own stzSelfDoc over 635 class sources.

The classes of this area

Narrations about this area