Secrets Engine
Notation keeps plaintext credential values strictly in process memory while storing opaque markers in SQLite state and workflow journals. Registered secret strings are stripped from error messages before any failure is recorded or emitted.
Credential Markers
A CredentialMarker (packages/resource/src/credential.ts) stands in for a secret value inside persisted params, output, and step results:
export type CredentialMarker = {
$credential: { resource: string; name: string; version: string | null };
};Each marker identifies the producing resource, the credential property name, and an opaque version. When a producer creates, rotates, or receives --credential, its marker gets a new version so consumer params diffs trigger updates.
When a takeover or read lacks a marker, addCredentialMarkers inserts a null version. This signals that Notation holds no value and must mint or load one before a consumer can use it.
omitCredentials strips a resource's own credential fields, and getOperationState replaces taken credential markers with undefined before update, delete, or rotate. assertNoHiddenCredential rejects any hidden: true param referencing a CredentialRef because hidden params are omitted from state and would trigger rotation on every deploy.
In-Memory Credential Tracking
packages/reconciler/src/credentials.ts maintains three process-local structures that never leave memory:
| Structure | Role |
|---|---|
held | Maps each credential version to its plaintext value |
given | Records credential versions injected into consumer operations |
unobtainable | Stores deferred UnobtainableCredentialError instances per consumer and credential |
held is a Map<string, unknown> populated via holdCredential(value, version = randomUUID()), so resumed deploys start with an empty held map. given is a WeakMap<BaseResource, Set<string>> populated by revealCredentials and left empty for journal-replayed operations. unobtainable is a WeakMap<BaseResource, Map<string, Error>> keyed by taker and ${resource}.${name} via deferUnobtainable.
When a resource operation runs, revealCredentials(value, taker, recorded) walks value with mapChangedCredentials.
If a marker matches recorded at the exact same object path, it substitutes undefined because the consumer already holds that version. Otherwise, it resolves the secret from held and records the version in given, or throws from unobtainable.
Because deferred errors throw only inside revealCredentials, a resumed deploy whose consumer operation replays from the journal succeeds without failing on unheld non-rotatable secrets.
On create, holdCreated(resource, result) extracts each schema credential property, validates it under "create", registers it in held, and returns { key, credentials, invalid }.
After applying an action, findCredentialsNotReceived inspects given (excluding credential sources and non-rotatable credentials). If a resumed consumer replayed an operation whose credential later rotated, reconcileResource re-reconciles it with staleCredentials passed to markCredentialsStale, resetting those marker versions to null in recorded params so the consumer updates.
Credential Minting
mintNeededCredentials (packages/reconciler/src/durable/credentials.ts) runs on kept, non-"creating" producers before reconciliation reaches their consumers:
- Passed credentials – For each matching
--credentialtarget,applyPassedCredentialcallsholdPassedCredential. It readsprocess.env[target.variable], registers secret strings, validates under"deploy", and checkpoints onlyversionin"passed"; on replay withoutheld, it reloads the variable under the savedversionbeforerecordCredentialpersists the marker. - Consumer needs – Step
"credentials:needed"runsgetCredentialsToMintacross all consumers. It detects"no-version","consumer-added","consumer-create-unfinished", and"consumer-behind"viagetChangedCredentials. - Eager rotation – For unpassed needed credentials with
resource.rotate?.[name],rotateStepcallsrotatein"rotate", holds the returned value, and immediately persists the new marker withrecordCredentialbecause rotation revokes the prior secret. Non-rotatable credentials throwUnobtainableCredentialError.
Credential Acquisition
obtainCredentials (packages/reconciler/src/durable/credentials.ts) runs immediately before a non-noop consumer operation whenever findUnheldCredentials(received) finds markers missing from held:
- Credential sources – Calls
loadSourceCredential, which invokessource.loadCredential, validates under"load", callsrecordSecretStrings, and stores the value inheldunder the source's deterministicversion. - Non-rotatable credentials – Calls
deferUnobtainablewithreason: "not-held"so the error surfaces only ifrevealCredentialsruns. - Rotatable credentials – Loops
attempt = 0, 1, ...callingrotateStepuntilholdsCredential(version)is true, skipping journaled attempts without an in-memory value. Once held, it updates the producer record, refreshes sibling consumers (refresh:<id>,driftDetection: false), and updates markers inparams,unnamedParams, andaction.patchviarefreshCredentialMarkers.
Source Versioning
readAndDecideSource (packages/reconciler/src/sources.ts) runs source.readSource inside step.run("read", ...). It scrubs errors with scrubError, emits reconciler.source.warning for each warn() message, and passes the validated result to decideSource.
For every declared credential on the source, decideSource constructs a marker using computeSourceCredentialVersion (packages/reconciler/src/credentials.ts):
export function computeSourceCredentialVersion(
source: BaseResource,
name: string,
params: Record<string, unknown>,
revision: unknown,
): string {
return createHash("sha256")
.update(
sortedJson.encode([
source.id,
name,
toComparableParams(source.schema, params),
revision,
]),
)
.digest("hex");
}Because the version hashes only source.id, name, toComparableParams, and revision, identical source state yields the exact same version across deploys without rotating downstream consumers.
decideSource returns "create" when no non-"creating" record exists, "update" when diffParams or isDeepStrictEqual detects output or marker differences, and "noop" otherwise.
Value Fingerprinting
Credential sources such as sources.Env, sources.Dotenv, and InfisicalSecret use trackRevision (packages/std/src/track.ts) to hash secret values into deterministic revision strings without storing plaintext. Every digest is salted with JSON.stringify([scope.app, scope.stage, scope.id]) so identical secrets across apps, stages, or resource IDs yield distinct revisions:
"scrypt"– Runscrypto.scrypt(value, salt, 32, { N: 2 ** 17, r: 8, p: 1, maxmem: 256 * 1024 * 1024 })and returnsscrypt:<hex>.maxmemis 256 MiB becauseN = 2^17withr = 8requires 128 MiB, exceeding Node's 32 MiB default."hmac"– Requiresprocess.env.NOTATION_TRACK_KEY(assertTrackKey) and computesHMAC-SHA256(key)oversalt + "\0" + value, returninghmac:<hex>.
trackRevision memoizes pending and resolved promises in a process-level Map keyed by SHA-256(JSON.stringify([track, key, salt, value])). Rejected entries are deleted, and neither plaintext values nor track keys sit in the cache key.
Redacted Wrapper
Redacted<T> (packages/core/src/secrets/redacted.ts) wraps secret strings in a private #value field to prevent accidental serialization or logging:
| Member | Behavior |
|---|---|
unwrap() | Returns the underlying #value at the final provider boundary |
[Symbol.toPrimitive]() | Throws RedactedValueError |
toString() | Throws RedactedValueError |
toJSON() | Throws RedactedValueError |
[Symbol.for("nodejs.util.inspect.custom")]() | Returns REDACTED_PLACEHOLDER |
Coercion methods throw RedactedValueError instead of returning a placeholder that could be sent to a provider API. REDACTED_PLACEHOLDER evaluates to "Redacted(<hidden>)" for safe console.log and util.inspect output.
Secret Scrubbing
packages/utils/src/secret-values.ts maintains a singleton registry on globalThis[Symbol.for("@notation/utils/secret-values")] so separate bundles in the same process scrub the same secret set. recordSecretValue(value) ignores empty strings and registers three representations per secret because provider SDKs may echo any of them in HTTP error payloads:
| Form | Encoding |
|---|---|
| Raw | Exact value string |
| Base64 | Buffer.from(value, "utf8").toString("base64") |
| JSON-escaped | JSON.stringify(value).slice(1, -1) |
scrubSecretValues(text) lazily sorts registered patterns longest-first so shorter substrings cannot leave fragments of longer secrets behind, replacing matches with SCRUBBED ("<hidden>").
scrubError(error) rewrites message and stack in place while preserving the error class. It walks cause and errors recursively with a seen Set to guard against reference cycles.