DBConnectionAPI composes database connection strings for authorized callers from templates and secure credentials held in the SAIF Environment API, validates Oracle and SQL Server strings with a connectivity probe, caches validated strings in memory, and exposes an Admin surface that returns the raw credential parts. The 25 rules below cover caching, key construction, template and credential handling, probe and retry behavior, error-to-status mapping, audit logging, Admin disclosure and authorization. Rules are numbered BR-DBC-001 to BR-DBC-025. Each rule heading combines the rule identifier and its title.
BR-DBC-001 Serve from the cache when the key is present¶
Field
Value
Title
Serve from the cache when the key is present
Statement
On every retrieval request the Environment API template is read and formatted first. A connection string is then served from the in-memory cache when its key is already present. Secure-credential retrieval, credential validation, the connectivity probe and cache insertion run only on a cache miss
Trigger
Every retrieval request, in the service layer after the template lookup and before the secure-credential retrieval
Cache hit: the template lookup still occurs, but secure-credential retrieval, credential validation, the connectivity probe and cache insertion are skipped; the stored string is returned with status 200
Cache keys are ORA.<instance>.<user>, SQL.<server>.<instance>.<user> and POSTGRES.<server>.<instance>.<user>. They are case-sensitive and not normalized
Trigger
Key generation at the start of each retrieval request
BR-DBC-007 Templates come from the Environment API group¶
Field
Value
Title
Templates come from the Environment API group
Statement
Connection-string templates are read from Environment API group dbconnectionapi (keys sqlconnectiontemplate, postgresqlconnectiontemplate, oraconnectiontemplate). {SERVER} and {INSTANCE} are replaced; the Oracle template replaces only {INSTANCE}
Trigger
Template retrieval for every operation
Enforcement
ConnectionManager.GetSqlTemplate, GetPostgreSqlTemplate, GetOracleTemplate; key names in EnvironmentKeys
A template with placeholders substituted. There is no null guard, so a missing template fails with an unhandled null reference (status not visible in source**)
A missing pipe raises ArgumentOutOfRangeException outside the retry try; it is not a ConnectionManagerException, so the status depends on the package middleware (presumably 500**)
Other final failures map to HTTP 500: ORA-01034 (database unavailable), ORA-01000 (cursors), ORA-01017 or Login failed (invalid credentials; the message names the secure-setting key and track), ORA-12570, ORA-12571 and ORA-03135 (network interrupted; includes the raw message), and a generic fallback (Something went wrong, then See: and the raw message {msg})
ConnectionManagerException(500) rendered by the package middleware (DynamicErrorHandler†); the body can disclose key names, the track and raw provider messages
BR-DBC-019 Legacy token decoded for the probe only¶
Field
Value
Title
Legacy token decoded for the probe only
Statement
Before probing, the legacy token ZSPECIALCHAR is replaced with the BEL control character (char 7). This applies only to the string under test; the cached and returned string keeps the token
Every retrieval request is logged at Info level with the key components, the caller's UserId and AuthenticationScheme, and the timestamp. Admin requests are not logged
Trigger
Each Connections request
Enforcement
ConnectionsController actions through ISaifLogService and IIdentityServiceAccessor
BR-DBC-023 Admin inspection discloses raw credentials¶
Field
Value
Title
Admin inspection discloses raw credentials
Statement
Admin inspection reads the secure setting directly. It skips the HasSetting check, the probe and the cache, and returns the raw credentials, user, pw and connectionString
Plaintext credential disclosure with status 200. A missing secure setting is not handled locally, so the failure is raised by the package client and its status is not visible in source**
BR-DBC-024 Admin split failure reported with status 200¶
Field
Value
Title
Admin split failure reported with status 200
Statement
If the Admin credential split fails, the response adds an Error entry (pipe delimiter expected), returns an empty user and password, and keeps HTTP 200
Trigger
Exception while splitting the credential
Enforcement
Bare try/catch in AdminController.GetConnectionInfo
BR-DBC-025 Resource authorization on every endpoint¶
Field
Value
Title
Resource authorization on every endpoint
Statement
All endpoints require resource DBConnAPIRetrieveResource. The caller identity name must be non-blank, the domain prefix is stripped, and the security service authorization check is called†
Trigger
Every request, before the action runs
Enforcement
[SecurityApiAuthorize("DBConnAPIRetrieveResource")] on both controllers; handler behavior from SAIF.NetCore.ServiceExtensions†
Denied requests receive a status the package documentation does not state** (401 or 403 by ASP.NET Core convention*). The same resource guards the Admin and the retrieval endpoints, and no data-level check ties the caller to the requested instance or user
Note: Statements marked with † are derived from dependency library
documentation via the Legends CLI. Statements marked with * were inferred
from code structure or contextual evidence. Statements marked with ** could
not be confirmed; treat as unknown until verified.