SDK, modules

The SDK has eight source modules, totaling 41 exports. Each module has a tightly scoped responsibility.

src/index.ts

Barrel file. Re-exports everything from the other modules. Consumers import only from here:

import { encrypt, getSetting, recordLoginAttempt } from "@olympusoss/sdk";

src/settings.ts

Settings vault CRUD. The most-imported module.

Exports:

• getSetting(domain, key), read.
• setSetting(domain, key, value, opts), write, optionally encrypted.
• batchSetSettings(domain, entries), atomic multi-key write.
• deleteSetting(domain, key), remove.
• listSettings(domain, prefix?), enumerate.

Uses the TTL cache (cache.ts) for hot reads. Decrypts on read if the value has the v2: prefix.

src/crypto.ts

Encryption primitives.

Exports:

• encrypt(plaintext, record_id), AES-256-GCM with HKDF-derived key.
• decrypt(ciphertext, record_id), inverse.
• Internal helpers for HKDF, nonce generation, format version handling.

See Internals, SDK encryption format for the on-disk format.

src/cache.ts

In-memory TTL cache for settings.

Exports:

• SettingsCache class, get, set, invalidate.
• Default 60-second TTL.

Per-process. Multiple containers don't share, a cache invalidation in one container doesn't propagate. For settings that must be coherent across containers, lower the TTL or skip the cache.

src/db.ts

postgres-js connection pool, auto-migration, table helpers.

Exports:

• db, the pool.
• Internal: migrate() runs on first import; ensures all SDK-owned tables exist.

Five tables managed:

• <domain>_settings (ciam_settings, iam_settings)
• locations
• login_attempts
• lockouts
• security_audit

src/brute-force.ts

Login attempt tracking + lockout logic.

Exports:

• recordLoginAttempt(domain, identifier, success), write to login_attempts.
• isLockedOut(domain, identifier), check current lockout.
• applyLockout(domain, identifier, reason), explicitly lock.
• releaseLockout(domain, identifier), explicitly unlock.

Hera calls recordLoginAttempt on every login flow submission, then isLockedOut before calling Kratos.

src/locations.ts

Session location tracking.

Exports:

• recordLocation(session_id, ip, geo), write to locations.
• getRecentLocations(identity_id), read recent.

Athena's identity detail page shows "Recent logins from" via this.

src/blocklist.ts

The ENCRYPTION_KEY blocklist (see Security, Encryption key blocklist).

Exports:

• BLOCKLIST, the set of forbidden values.
• validateEncryptionKey(key), called at startup.

src/migrate-encryption-key.ts

Standalone script for rotating ENCRYPTION_KEY. See Operate, Encryption key rotation for the runbook.

Not exported in index.ts, it's a CLI tool, not a library function.

Type definitions

src/types.ts defines the cross-module types: Setting, LoginAttempt, Lockout, Location, AuditEvent. Importing apps get these via @olympusoss/sdk exports.

Module dependencies

index ──┬─→ settings ─→ db, cache, crypto
        ├─→ crypto ─→ blocklist
        ├─→ cache
        ├─→ db
        ├─→ brute-force ─→ db
        ├─→ locations ─→ db
        └─→ blocklist

db is the only module with side effects at import (running migrations). All others are pure imports.

Where to add code

Related

• Reference, SDK API
• Internals, SDK, Encryption format
• Internals, SDK, Connection pool
• Develop, Working with SDK