@fonderie/config 3.0.0 → 5.0.0

package/README.md

@@ -1,7 +1,9 @@
 # @fonderie/config
 
-DB-backed feature flags and remote config: per-environment overrides and
-TTL-cached snapshots, changeable at runtime without a deploy.
+A Postgres-backed **control plane** for the settings and secrets your app changes
+without a deploy — feature flags, remote config, and secrets — each **versioned,
+with optimistic concurrency, revisions, rollback, and near-instant propagation**.
+Manage it over an admin HTTP surface or the `fonderie` CLI.
 
 ## Install
 
@@ -9,35 +11,102 @@ TTL-cached snapshots, changeable at runtime without a deploy.
 npm install @fonderie/config
 ```
 
-## Use
+## Read config at runtime
+
+Register the module and read live values through `ctx.meta` — a per-environment
+snapshot (with `'all'` as the base, env-specific overrides on top) kept fresh by
+a poll floor and, when a `connectionUrl` is given, **`LISTEN/NOTIFY` push** so a
+change lands in milliseconds.
 
 ```ts
 import { FonderieApp, defineConfig } from '@fonderie/core';
-import { ConfigModule } from '@fonderie/config';
+import { PGAdapter } from '@fonderie/store';
+import { ConfigModule, getConfig } from '@fonderie/config';
 
+const store = new PGAdapter(process.env.DATABASE_URL);
 const app = await new FonderieApp(defineConfig({}))
-  .register(new ConfigModule())
+  .register(new ConfigModule(store, {
+    environment: 'production',
+    connectionUrl: process.env.DATABASE_URL, // opt-in push invalidation
+  }))
   .boot();
+
+// in a handler:
+const on = getConfig(ctx, 'feature.new-onboarding', false);
+```
+
+## Manage it (versioned + optimistic concurrency + rollback)
+
+Every write bumps a monotonic `version`, appends an immutable revision, and
+records the actor. Pass `ifVersion` for a compare-and-swap — the write commits
+only if the version matches, else throws `ConfigConflictError` (reject-and-retry).
+Writes are advisory-locked per `(key, environment)`, so concurrent creators of the
+same key are serialized. `rollbackConfigEntry` rolls *forward* to a past value.
+
+```ts
+import {
+  setConfigEntry, getConfigEntry, rollbackConfigEntry,
+  listConfigRevisions, ConfigConflictError,
+} from '@fonderie/config';
+
+await setConfigEntry({ key: 'rate.limit', value: 100, ifVersion: 3, actor: 'ada' }, store);
+const revs = await listConfigRevisions('rate.limit', 'all', store);
+await rollbackConfigEntry({ key: 'rate.limit', toVersion: 2, actor: 'ada' }, store);
+```
+
+## Secrets (masked, encryptable)
+
+Same lifecycle, a separate `fonderie_secrets` table + read path so config can
+never leak a secret. `getSecret`/`listSecrets` return **metadata only** (never the
+value); values are **encrypted at rest** via a pluggable encryptor; `revealSecret`
+is the single decrypt path.
+
+```ts
+import { setSecret, revealSecret, createAesGcmEncryptor } from '@fonderie/config';
+
+const enc = createAesGcmEncryptor(process.env.SECRET_KEY); // 32-byte hex, or omit for masked-only
+await setSecret({ key: 'stripe.key', value: 'sk_live_…', actor: 'ada' }, store, enc);
+const value = await revealSecret('stripe.key', 'all', store, enc);
 ```
 
+## Admin HTTP surface
+
+Set `adminToken` and the module registers `Bearer`-guarded routes (fail-closed —
+no token, no surface): `GET/PUT/DELETE /admin/config[/:key]`,
+`GET /admin/config/:key/revisions`, `POST /admin/config/:key/rollback`, and the
+same for `/admin/secrets/*` (`PUT` honours `ifVersion` → **409** on conflict;
+secret reads masked; `POST /admin/secrets/:key/reveal` decrypts).
+
 ```ts
-import { configContextMiddleware, getConfig } from '@fonderie/config';
+new ConfigModule(store, { adminToken: process.env.ADMIN_TOKEN, secretEncryptor: enc });
 ```
 
-CRUD services (`listConfigEntries`, `setConfigEntry`, …) are exported for
-building an admin surface on top.
+## CLI
+
+A thin client over that surface (`FONDERIE_ADMIN_URL` + `FONDERIE_ADMIN_TOKEN`):
+
+```sh
+fonderie config set feature.new-onboarding true --if-version 3
+fonderie config history feature.new-onboarding
+fonderie config rollback feature.new-onboarding --to-version 2
+fonderie secret set stripe.key sk_live_… && fonderie secret reveal stripe.key
+```
+
+## Dependencies
+
+Zero runtime dependencies. Peers only: `@fonderie/core`, `@fonderie/store`, and
+`pg` (for the LISTEN client) — all already present in a Fonderie app.
 
 ## Why this exists
 
-You've shipped this plumbing before — auth, teams, billing, messaging —
-and the next project will ask for it again. Fonderie packages it once:
-plain TypeScript modules for
+You've shipped this plumbing before — auth, teams, billing, messaging — and the
+next project will ask for it again. Fonderie packages it once: plain TypeScript
+modules for
 [`@fonderie/core`](https://github.com/fonderie-js/sdk/tree/main/packages/core),
-PostgreSQL-backed, self-hosted, MIT. No external control plane, no
-per-seat anything. Register the modules you need; skip the ones you don't.
+PostgreSQL-backed, self-hosted, MIT. No external control plane, no per-seat
+anything. Register the modules you need; skip the ones you don't.
 
-**This package owns** how behavior changes without a deploy. Feature flags and remote
-config read live by the other bricks.
+**This package owns** how behavior — and secrets — change without a deploy.
 
 Browse the whole set at
 [fonderie-js/sdk](https://github.com/fonderie-js/sdk) · follow

package/brain/outcomes.md

@@ -19,7 +19,66 @@ environment              TEXT NOT NULL DEFAULT 'all'
 description              TEXT
 active                   BOOLEAN NOT NULL DEFAULT true
 updated_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+version                  INT NOT NULL DEFAULT 1
+updated_by               TEXT
+-- UNIQUE (key, environment)
+```
+
+### `fonderie_config_revisions`
+
+```sql
+key                      TEXT NOT NULL
+environment              TEXT NOT NULL DEFAULT 'all'
+value                    TEXT NOT NULL
+version                  INT NOT NULL
+actor                    TEXT
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+-- PRIMARY KEY (key, environment, version)
+```
+
+### `fonderie_secret_revisions`
+
+```sql
+key                      TEXT NOT NULL
+environment              TEXT NOT NULL DEFAULT 'all'
+value                    TEXT NOT NULL
+version                  INT NOT NULL
+actor                    TEXT
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+-- PRIMARY KEY (key, environment, version)
+```
+
+### `fonderie_secrets`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+key                      TEXT NOT NULL
+value                    TEXT NOT NULL
+environment              TEXT NOT NULL DEFAULT 'all'
+description              TEXT
+active                   BOOLEAN NOT NULL DEFAULT true
+version                  INT NOT NULL DEFAULT 1
+updated_by               TEXT
+updated_at               TIMESTAMPTZ NOT NULL DEFAULT now()
 -- UNIQUE (key, environment)
 ```
 
 Raw SQL ships in `node_modules/@fonderie/config/dist/migrations/sql/` — read it there if you must; never download tarballs.
+
+## HTTP routes registered
+
+| Method | Path | Middleware chain (auth / validation / handler) |
+|---|---|---|
+| GET | `/admin/config` | `g(async (ctx) => { const rows = await listConfigEntries(envOf(ctx) ?? null, store); return setApiResponse(HTTP.OK, 'CONFIG_LISTED', 'Config entries', rows); })` |
+| DELETE | `/admin/config/:key` | `g(async (ctx) => { const ok = await deleteConfigEntry(keyOf(ctx), envOf(ctx) ?? 'all', store); return setApiResponse(ok ? HTTP.OK : HTTP.NOT_FOUND, ok ? 'DELETED' : 'NOT_FOUND', ok ? 'Deleted' : 'No such config entry'); })` |
+| GET | `/admin/config/:key` | `g(async (ctx) => { const row = await getConfigEntry(keyOf(ctx), envOf(ctx) ?? 'all', store); return row ? setApiResponse(HTTP.OK, 'CONFIG_ENTRY', 'Config entry', row) : setApiResponse(HTTP.NOT_FOUND, 'NOT_FOUND', 'No such config entry'); })` |
+| PUT | `/admin/config/:key` | `g(async (ctx) => { const b = body(ctx); if (!('value' in b)) { return setApiResponse(HTTP.UNPROCESSABLE, 'INVALID', 'body.value is required'); } try { const row = await setConfigEntry( { key: keyOf(ctx), value: b['value'], ...writeOpts(ctx, b) }, store, ); return setApiResponse(HTTP.OK, 'CONFIG_SET', 'Config entry saved', row); } catch (err) { return conflictOr(err); } })` |
+| GET | `/admin/config/:key/revisions` | `g(async (ctx) => { const revs = await listConfigRevisions(keyOf(ctx), envOf(ctx) ?? 'all', store); return setApiResponse(HTTP.OK, 'REVISIONS', 'Config revisions', revs); })` |
+| POST | `/admin/config/:key/rollback` | `g(async (ctx) => { const b = body(ctx); const toVersion = Number(b['toVersion']); if (!Number.isInteger(toVersion)) { return setApiResponse(HTTP.UNPROCESSABLE, 'INVALID', 'body.toVersion (int) is required'); } const row = await rollbackConfigEntry( rollbackOpts(ctx, b, toVersion), store, ); return setApiResponse(HTTP.OK, 'ROLLED_BACK', `Rolled back to v${toVersion}`, row); })` |
+| GET | `/admin/secrets` | `g(async (ctx) => { const rows = await listSecrets(envOf(ctx) ?? null, store); return setApiResponse(HTTP.OK, 'SECRETS_LISTED', 'Secrets (masked)', rows); })` |
+| DELETE | `/admin/secrets/:key` | `g(async (ctx) => { const ok = await deleteSecret(keyOf(ctx), envOf(ctx) ?? 'all', store); return setApiResponse(ok ? HTTP.OK : HTTP.NOT_FOUND, ok ? 'DELETED' : 'NOT_FOUND', ok ? 'Deleted' : 'No such secret'); })` |
+| GET | `/admin/secrets/:key` | `g(async (ctx) => { const row = await getSecret(keyOf(ctx), envOf(ctx) ?? 'all', store); return row ? setApiResponse(HTTP.OK, 'SECRET', 'Secret (masked)', row) : setApiResponse(HTTP.NOT_FOUND, 'NOT_FOUND', 'No such secret'); })` |
+| PUT | `/admin/secrets/:key` | `g(async (ctx) => { const b = body(ctx); if (typeof b['value'] !== 'string') { return setApiResponse(HTTP.UNPROCESSABLE, 'INVALID', 'body.value (string) is required'); } try { const row = await setSecret( { key: keyOf(ctx), value: b['value'], ...writeOpts(ctx, b) }, store, encryptor, ); return setApiResponse(HTTP.OK, 'SECRET_SET', 'Secret saved (masked)', row); } catch (err) { return conflictOr(err); } })` |
+| POST | `/admin/secrets/:key/reveal` | `g(async (ctx) => { const value = await revealSecret(keyOf(ctx), envOf(ctx) ?? 'all', store, encryptor); return value === null ? setApiResponse(HTTP.NOT_FOUND, 'NOT_FOUND', 'No such secret') : setApiResponse(HTTP.OK, 'SECRET_REVEALED', 'Decrypted secret value', { value }); })` |
+| GET | `/admin/secrets/:key/revisions` | `g(async (ctx) => { const revs = await listSecretRevisions(keyOf(ctx), envOf(ctx) ?? 'all', store); return setApiResponse(HTTP.OK, 'REVISIONS', 'Secret revisions', revs); })` |
+| POST | `/admin/secrets/:key/rollback` | `g(async (ctx) => { const b = body(ctx); const toVersion = Number(b['toVersion']); if (!Number.isInteger(toVersion)) { return setApiResponse(HTTP.UNPROCESSABLE, 'INVALID', 'body.toVersion (int) is required'); } const row = await rollbackSecret( rollbackOpts(ctx, b, toVersion), store, ); return setApiResponse(HTTP.OK, 'ROLLED_BACK', `Rolled back to v${toVersion}`, row); })` |

package/brain/signatures.md

@@ -12,6 +12,8 @@ new ConfigModule(store: IStoreAdapter, options?: IConfigOptions): ConfigModule
   .manager: RemoteConfigManager
   .install(app: IFonderieApp): Promise<void>
 
+function buildAdminRoutes(store: IStoreAdapter, adminToken: string, encryptor?: ISecretEncryptor): [string, string, Middleware][]
+
 new RemoteConfigManager(store: IStoreAdapter, options?: IConfigOptions): RemoteConfigManager
   .boot(): Promise<void>
   .stop(): void
@@ -30,27 +32,96 @@ function listConfigEntries(environment: string | null, store: IStoreAdapter): Pr
 
 function getConfigEntry(key: string, environment: string, store: IStoreAdapter): Promise<IConfigEntry | null>
 
-function setConfigEntry(opts: { key: string; value: unknown; environment?: string; description?: string; active?: boolean; }, store: IStoreAdapter): Promise<IConfigEntry>
+function setConfigEntry(opts: { key: string; value: unknown; environment?: string; description?: string; active?: boolean; ifVersion?: number; actor?: string; }, store: IStoreAdapter): Promise<IConfigEntry>
 
 function deleteConfigEntry(key: string, environment: string, store: IStoreAdapter): Promise<boolean>
 
+function rollbackConfigEntry(opts: { key: string; environment?: string; toVersion: number; actor?: string; }, store: IStoreAdapter): Promise<IConfigEntry>
+
+function listConfigRevisions(key: string, environment: string, store: IStoreAdapter): Promise<IConfigRevision[]>
+
+new ConfigConflictError(key: string, scope: string | null, currentVersion: number | null, expectedVersion: number): VersionConflictError
+  .key: string
+  .scope: string | null
+  .currentVersion: number | null
+  .expectedVersion: number
+  .name: string
+  .message: string
+  .stack: string
+  .cause: unknown
+
 interface IConfigEntry {
     key: string;
     value: unknown;
     environment: string;
     description: string | null;
     active: boolean;
+    version: number;
+    updatedBy: string | null;
     updatedAt: string;
 }
 
+interface IConfigRevision {
+    key: string;
+    environment: string;
+    value: unknown;
+    version: number;
+    actor: string | null;
+    createdAt: string;
+}
+
 interface IConfigSnapshot {
     entries: Record<string, unknown>;
     fetchedAt: Date;
 }
 
+function listSecrets(environment: string | null, store: IStoreAdapter): Promise<ISecretEntry[]>
+
+function getSecret(key: string, environment: string, store: IStoreAdapter): Promise<ISecretEntry | null>
+
+function revealSecret(key: string, environment: string, store: IStoreAdapter, encryptor?: ISecretEncryptor): Promise<string | null>
+
+function setSecret(opts: { key: string; value: string; environment?: string; description?: string; active?: boolean; ifVersion?: number; actor?: string; }, store: IStoreAdapter, encryptor?: ISecretEncryptor): Promise<...>
+
+function rollbackSecret(opts: { key: string; environment?: string; toVersion: number; actor?: string; }, store: IStoreAdapter): Promise<ISecretEntry>
+
+function listSecretRevisions(key: string, environment: string, store: IStoreAdapter): Promise<ISecretRevision[]>
+
+function deleteSecret(key: string, environment: string, store: IStoreAdapter): Promise<boolean>
+
+interface ISecretEntry {
+    key: string;
+    environment: string;
+    description: string | null;
+    active: boolean;
+    version: number;
+    updatedBy: string | null;
+    updatedAt: string;
+}
+
+interface ISecretRevision {
+    key: string;
+    environment: string;
+    version: number;
+    actor: string | null;
+    createdAt: string;
+}
+
+const noopEncryptor: ISecretEncryptor
+
+function createAesGcmEncryptor(keyHex: string): ISecretEncryptor
+
+interface ISecretEncryptor {
+    encrypt(plain: string): string;
+    decrypt(cipher: string): string;
+}
+
 interface IConfigOptions {
     ttl?: number;
     environment?: string;
     table?: string;
+    connectionUrl?: string;
+    adminToken?: string;
+    secretEncryptor?: ISecretEncryptor;
 }
 ```

package/dist/{index-B2jOiL09.d.cts → index-CLaJRR69.d.cts}

@@ -1,21 +1,34 @@
 import { Middleware } from '@fonderie/core';
 import { IStoreAdapter } from '@fonderie/store';
 
+interface ISecretEncryptor {
+    encrypt(plain: string): string;
+    decrypt(cipher: string): string;
+}
+declare const noopEncryptor: ISecretEncryptor;
+declare function createAesGcmEncryptor(keyHex: string): ISecretEncryptor;
+
 interface IConfigOptions {
     ttl?: number;
     environment?: string;
     table?: string;
+    connectionUrl?: string;
+    adminToken?: string;
+    secretEncryptor?: ISecretEncryptor;
 }
 
 declare class RemoteConfigManager {
     private store;
     private snapshot;
     private interval;
+    private listenClient;
     private environment;
     private ttl;
     private table;
+    private connectionUrl;
     constructor(store: IStoreAdapter, options?: IConfigOptions);
     boot(): Promise<void>;
+    private startListening;
     stop(): void;
     get<T>(key: string, fallback: T): T;
     all(): Record<string, unknown>;
@@ -29,4 +42,4 @@ declare function getConfig(ctx: {
     meta: Record<string, unknown>;
 }, key: string, fallback?: unknown): unknown;
 
-export { CONFIG_MANAGER_KEY as C, type IConfigOptions as I, RemoteConfigManager as R, configContextMiddleware as c, getConfig as g };
+export { CONFIG_MANAGER_KEY as C, type IConfigOptions as I, RemoteConfigManager as R, type ISecretEncryptor as a, createAesGcmEncryptor as b, configContextMiddleware as c, getConfig as g, noopEncryptor as n };

package/dist/{index-B2jOiL09.d.ts → index-CLaJRR69.d.ts}

@@ -1,21 +1,34 @@
 import { Middleware } from '@fonderie/core';
 import { IStoreAdapter } from '@fonderie/store';
 
+interface ISecretEncryptor {
+    encrypt(plain: string): string;
+    decrypt(cipher: string): string;
+}
+declare const noopEncryptor: ISecretEncryptor;
+declare function createAesGcmEncryptor(keyHex: string): ISecretEncryptor;
+
 interface IConfigOptions {
     ttl?: number;
     environment?: string;
     table?: string;
+    connectionUrl?: string;
+    adminToken?: string;
+    secretEncryptor?: ISecretEncryptor;
 }
 
 declare class RemoteConfigManager {
     private store;
     private snapshot;
     private interval;
+    private listenClient;
     private environment;
     private ttl;
     private table;
+    private connectionUrl;
     constructor(store: IStoreAdapter, options?: IConfigOptions);
     boot(): Promise<void>;
+    private startListening;
     stop(): void;
     get<T>(key: string, fallback: T): T;
     all(): Record<string, unknown>;
@@ -29,4 +42,4 @@ declare function getConfig(ctx: {
     meta: Record<string, unknown>;
 }, key: string, fallback?: unknown): unknown;
 
-export { CONFIG_MANAGER_KEY as C, type IConfigOptions as I, RemoteConfigManager as R, configContextMiddleware as c, getConfig as g };
+export { CONFIG_MANAGER_KEY as C, type IConfigOptions as I, RemoteConfigManager as R, type ISecretEncryptor as a, createAesGcmEncryptor as b, configContextMiddleware as c, getConfig as g, noopEncryptor as n };