@agentforge-io/core 2.0.23 → 2.1.0

package/dist/services/plan.service.d.ts

@@ -1,54 +0,0 @@
-import type { PlanRepository } from '../repositories';
-import type { Plan, NewPlan, PlanPatch } from '../domain/plan';
-import type { PlanDefinition } from '../types/config.types';
-export interface PlanServiceOptions {
-    /**
-     * Plans to seed the DB with on first boot (i.e. when `af_plans` is empty).
-     * After the table has at least one row, this seed is ignored — the DB is
-     * the source of truth. Pass your `config.billing.plans` here so existing
-     * deployments migrate transparently.
-     */
-    seedPlans?: PlanDefinition[];
-}
-/**
- * Reads and writes plan rows from the DB, with an in-process cache invalidated
- * on every mutation. Hot-path reads (`getPlan(id)`) are O(n) over a tiny set,
- * which is fine for the few plans most apps need.
- *
- * Single-instance assumption: when running multiple API instances, mutations
- * via admin endpoints invalidate only the local cache. The next read on other
- * instances still serves stale data until their own TTL expires. For most B2B
- * scenarios (plan edits are rare, eventually-consistent is OK) this is fine;
- * if you need strict consistency, set `cacheTtlMs: 0`.
- */
-export declare class PlanService {
-    private readonly repo;
-    private readonly opts;
-    private cache;
-    private cacheLoadedAt;
-    /** Default TTL: 60 seconds. */
-    private readonly cacheTtlMs;
-    constructor(repo: PlanRepository, opts?: PlanServiceOptions);
-    /**
-     * Call once at boot. Seeds the table from `opts.seedPlans` if empty, then
-     * warms the cache. Safe to call multiple times.
-     */
-    initialize(): Promise<void>;
-    list(): Promise<Plan[]>;
-    listAll(): Promise<Plan[]>;
-    getPlan(id: string): Promise<Plan | undefined>;
-    getDefault(): Promise<Plan | undefined>;
-    getDefaultId(): Promise<string>;
-    create(plan: NewPlan): Promise<Plan>;
-    update(id: string, patch: PlanPatch): Promise<Plan>;
-    deactivate(id: string): Promise<void>;
-    /** Force the next read to bypass the cache. Useful in tests. */
-    invalidate(): void;
-    private refresh;
-    private isCacheFresh;
-}
-export declare class PlanServiceError extends Error {
-    status: number;
-    code: 'plan_exists' | 'plan_not_found' | 'plan_is_default';
-    constructor(code: 'plan_exists' | 'plan_not_found' | 'plan_is_default', message: string);
-}

package/dist/services/plan.service.js

@@ -1,120 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PlanServiceError = exports.PlanService = void 0;
-/**
- * Reads and writes plan rows from the DB, with an in-process cache invalidated
- * on every mutation. Hot-path reads (`getPlan(id)`) are O(n) over a tiny set,
- * which is fine for the few plans most apps need.
- *
- * Single-instance assumption: when running multiple API instances, mutations
- * via admin endpoints invalidate only the local cache. The next read on other
- * instances still serves stale data until their own TTL expires. For most B2B
- * scenarios (plan edits are rare, eventually-consistent is OK) this is fine;
- * if you need strict consistency, set `cacheTtlMs: 0`.
- */
-class PlanService {
-    constructor(repo, opts = {}) {
-        this.repo = repo;
-        this.opts = opts;
-        this.cache = null;
-        this.cacheLoadedAt = 0;
-        /** Default TTL: 60 seconds. */
-        this.cacheTtlMs = 60_000;
-    }
-    /**
-     * Call once at boot. Seeds the table from `opts.seedPlans` if empty, then
-     * warms the cache. Safe to call multiple times.
-     */
-    async initialize() {
-        const all = await this.repo.list({ includeInactive: true });
-        if (all.length === 0 && this.opts.seedPlans?.length) {
-            for (const p of this.opts.seedPlans) {
-                await this.repo.create({ ...p, isActive: true });
-            }
-        }
-        await this.refresh();
-    }
-    async list() {
-        if (!this.isCacheFresh())
-            await this.refresh();
-        return this.cache;
-    }
-    async listAll() {
-        return this.repo.list({ includeInactive: true });
-    }
-    async getPlan(id) {
-        if (!this.isCacheFresh())
-            await this.refresh();
-        // The cache only holds active plans (hot-path callers like UsageService
-        // never want inactive ones). For admin lookups by id we fall through to
-        // the repo so soft-deleted plans are still reachable for re-activation.
-        const cached = this.cache.find((p) => p.id === id);
-        if (cached)
-            return cached;
-        return (await this.repo.findById(id)) ?? undefined;
-    }
-    async getDefault() {
-        const plans = await this.list();
-        return plans.find((p) => p.isDefault) ?? plans[0];
-    }
-    async getDefaultId() {
-        return (await this.getDefault())?.id ?? 'free';
-    }
-    // ─── Admin operations ───────────────────────────────────────────────────
-    async create(plan) {
-        const existing = await this.repo.findById(plan.id);
-        if (existing) {
-            throw new PlanServiceError('plan_exists', `Plan "${plan.id}" already exists`);
-        }
-        const created = await this.repo.create(plan);
-        this.invalidate();
-        return created;
-    }
-    async update(id, patch) {
-        const existing = await this.repo.findById(id);
-        if (!existing) {
-            throw new PlanServiceError('plan_not_found', `Plan "${id}" not found`);
-        }
-        await this.repo.update(id, patch);
-        this.invalidate();
-        const updated = await this.repo.findById(id);
-        return updated;
-    }
-    async deactivate(id) {
-        const existing = await this.repo.findById(id);
-        if (!existing) {
-            throw new PlanServiceError('plan_not_found', `Plan "${id}" not found`);
-        }
-        if (existing.isDefault) {
-            throw new PlanServiceError('plan_is_default', 'Cannot deactivate the default plan');
-        }
-        await this.repo.deactivate(id);
-        this.invalidate();
-    }
-    /** Force the next read to bypass the cache. Useful in tests. */
-    invalidate() {
-        this.cache = null;
-        this.cacheLoadedAt = 0;
-    }
-    async refresh() {
-        this.cache = await this.repo.list();
-        this.cacheLoadedAt = Date.now();
-    }
-    isCacheFresh() {
-        if (!this.cache)
-            return false;
-        if (this.cacheTtlMs <= 0)
-            return false;
-        return Date.now() - this.cacheLoadedAt < this.cacheTtlMs;
-    }
-}
-exports.PlanService = PlanService;
-class PlanServiceError extends Error {
-    constructor(code, message) {
-        super(message);
-        this.code = code;
-        this.status =
-            code === 'plan_not_found' ? 404 : code === 'plan_exists' ? 409 : 400;
-    }
-}
-exports.PlanServiceError = PlanServiceError;

package/dist/services/refresh-token.service.d.ts

@@ -1,38 +0,0 @@
-import type { RefreshTokenRepository } from '../repositories';
-import type { RefreshToken } from '../domain/refresh-token';
-export interface MintedRefreshToken {
-    /** Plain token to send to the client. Only available at mint time. */
-    token: string;
-    entity: RefreshToken;
-}
-export interface IssueOptions {
-    family?: string;
-    userAgent?: string;
-    ip?: string;
-}
-export declare class RefreshTokenError extends Error {
-    readonly code: 'invalid' | 'expired' | 'revoked';
-    constructor(message: string, code: 'invalid' | 'expired' | 'revoked');
-}
-export interface RefreshTokenServiceOptions {
-    /** Refresh token TTL in days. Default: 30. */
-    ttlDays?: number;
-    /** Hook called when reuse is detected — log/alert from your app. */
-    onReuseDetected?: (info: {
-        userId: string;
-        family: string;
-    }) => void;
-}
-export declare class RefreshTokenService {
-    private readonly repo;
-    private readonly opts;
-    constructor(repo: RefreshTokenRepository, opts?: RefreshTokenServiceOptions);
-    issue(userId: string, opts?: IssueOptions): Promise<MintedRefreshToken>;
-    rotate(rawToken: string, opts?: IssueOptions): Promise<MintedRefreshToken & {
-        userId: string;
-    }>;
-    revoke(rawToken: string): Promise<void>;
-    revokeFamily(family: string): Promise<void>;
-    revokeAllForUser(userId: string): Promise<void>;
-    private hash;
-}

package/dist/services/refresh-token.service.js

@@ -1,73 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RefreshTokenService = exports.RefreshTokenError = void 0;
-const crypto_1 = require("crypto");
-class RefreshTokenError extends Error {
-    constructor(message, code) {
-        super(message);
-        this.code = code;
-    }
-}
-exports.RefreshTokenError = RefreshTokenError;
-class RefreshTokenService {
-    constructor(repo, opts = {}) {
-        this.repo = repo;
-        this.opts = opts;
-    }
-    async issue(userId, opts = {}) {
-        const token = (0, crypto_1.randomBytes)(32).toString('hex');
-        const tokenHash = this.hash(token);
-        const ttlDays = this.opts.ttlDays ?? 30;
-        const entity = await this.repo.create({
-            userId,
-            tokenHash,
-            family: opts.family ?? (0, crypto_1.randomUUID)(),
-            expiresAt: new Date(Date.now() + ttlDays * 24 * 60 * 60 * 1000),
-            userAgent: opts.userAgent,
-            ip: opts.ip,
-        });
-        return { token, entity };
-    }
-    async rotate(rawToken, opts = {}) {
-        const tokenHash = this.hash(rawToken);
-        const existing = await this.repo.findByHash(tokenHash);
-        if (!existing)
-            throw new RefreshTokenError('Invalid refresh token', 'invalid');
-        if (existing.expiresAt <= new Date()) {
-            throw new RefreshTokenError('Refresh token expired', 'expired');
-        }
-        if (existing.revokedAt) {
-            this.opts.onReuseDetected?.({ userId: existing.userId, family: existing.family });
-            await this.repo.revokeFamily(existing.family);
-            throw new RefreshTokenError('Refresh token has been revoked', 'revoked');
-        }
-        const minted = await this.issue(existing.userId, {
-            family: existing.family,
-            userAgent: opts.userAgent,
-            ip: opts.ip,
-        });
-        await this.repo.update(existing.id, {
-            revokedAt: new Date(),
-            replacedById: minted.entity.id,
-            lastUsedAt: new Date(),
-        });
-        return { ...minted, userId: existing.userId };
-    }
-    async revoke(rawToken) {
-        const tokenHash = this.hash(rawToken);
-        const existing = await this.repo.findByHash(tokenHash);
-        if (!existing || existing.revokedAt)
-            return;
-        await this.repo.update(existing.id, { revokedAt: new Date() });
-    }
-    async revokeFamily(family) {
-        await this.repo.revokeFamily(family);
-    }
-    async revokeAllForUser(userId) {
-        await this.repo.revokeAllForUser(userId);
-    }
-    hash(token) {
-        return (0, crypto_1.createHash)('sha256').update(token).digest('hex');
-    }
-}
-exports.RefreshTokenService = RefreshTokenService;

package/dist/services/secrets/crypto.d.ts

@@ -1,37 +0,0 @@
-export declare class SecretCryptoError extends Error {
-    readonly code: SecretCryptoErrorCode;
-    constructor(code: SecretCryptoErrorCode, message: string);
-}
-export type SecretCryptoErrorCode = 'invalid_master_key' | 'invalid_ciphertext' | 'decryption_failed';
-/**
- * Encrypt a UTF-8 string with the given 32-byte master key. Returns a
- * single Buffer that can be persisted as a bytea column.
- *
- * Throws `SecretCryptoError('invalid_master_key', ...)` if `masterKey`
- * isn't exactly 32 bytes — fail loudly at insert time rather than
- * silently corrupt data with a short/long key.
- */
-export declare function encrypt(plaintext: string, masterKey: Buffer): Buffer;
-/**
- * Reverse of `encrypt`. Throws `SecretCryptoError('decryption_failed', ...)`
- * when the ciphertext was produced with a different key, has been
- * tampered with, or the tag doesn't validate — there's no way to tell
- * these apart with GCM, and we shouldn't reveal which one anyway.
- */
-export declare function decrypt(blob: Buffer, masterKey: Buffer): string;
-/**
- * Parse a master key from its env-var representation. Accepts:
- *  - 64-char hex string (output of `openssl rand -hex 32`)
- *  - base64 string that decodes to exactly 32 bytes
- *
- * Throws with a clear message if neither — operators set this once and
- * we don't want them silently running with a 16-byte key.
- */
-export declare function parseMasterKey(raw: string): Buffer;
-/**
- * Compute a stable hint from the plaintext for the UI. Returns the last
- * 4 chars prefixed with "..." (e.g. "...xZ12"). For values shorter than
- * 4 chars, returns a generic placeholder so we never echo the whole
- * secret back.
- */
-export declare function valueHint(plaintext: string): string;

package/dist/services/secrets/crypto.js

@@ -1,110 +0,0 @@
-"use strict";
-// AES-256-GCM utilities for encrypting platform secrets at rest.
-//
-// Storage layout: a single buffer `iv (12B) | ciphertext (var) | tag (16B)`.
-// Keeping the IV inline (rather than in a separate column) means the row
-// is self-contained — if you ever export/import the table, you only carry
-// one blob per secret instead of juggling related fields.
-//
-// AES-GCM provides authenticated encryption: any tampering with the
-// ciphertext (or wrong key) fails decryption explicitly rather than
-// returning garbage. That's why decrypt() throws on mismatch — callers
-// must treat any error as "this secret is unrecoverable, fall back to
-// env var or ask the operator to re-enter".
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SecretCryptoError = void 0;
-exports.encrypt = encrypt;
-exports.decrypt = decrypt;
-exports.parseMasterKey = parseMasterKey;
-exports.valueHint = valueHint;
-const crypto_1 = require("crypto");
-const ALGO = 'aes-256-gcm';
-const IV_LEN = 12;
-const TAG_LEN = 16;
-const KEY_LEN = 32;
-class SecretCryptoError extends Error {
-    constructor(code, message) {
-        super(message);
-        this.code = code;
-        this.name = 'SecretCryptoError';
-    }
-}
-exports.SecretCryptoError = SecretCryptoError;
-/**
- * Encrypt a UTF-8 string with the given 32-byte master key. Returns a
- * single Buffer that can be persisted as a bytea column.
- *
- * Throws `SecretCryptoError('invalid_master_key', ...)` if `masterKey`
- * isn't exactly 32 bytes — fail loudly at insert time rather than
- * silently corrupt data with a short/long key.
- */
-function encrypt(plaintext, masterKey) {
-    assertMasterKey(masterKey);
-    const iv = (0, crypto_1.randomBytes)(IV_LEN);
-    const cipher = (0, crypto_1.createCipheriv)(ALGO, masterKey, iv);
-    const ct = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
-    const tag = cipher.getAuthTag();
-    return Buffer.concat([iv, ct, tag]);
-}
-/**
- * Reverse of `encrypt`. Throws `SecretCryptoError('decryption_failed', ...)`
- * when the ciphertext was produced with a different key, has been
- * tampered with, or the tag doesn't validate — there's no way to tell
- * these apart with GCM, and we shouldn't reveal which one anyway.
- */
-function decrypt(blob, masterKey) {
-    assertMasterKey(masterKey);
-    if (blob.length < IV_LEN + TAG_LEN) {
-        throw new SecretCryptoError('invalid_ciphertext', `ciphertext too short: ${blob.length} bytes (need ≥ ${IV_LEN + TAG_LEN})`);
-    }
-    const iv = blob.subarray(0, IV_LEN);
-    const tag = blob.subarray(blob.length - TAG_LEN);
-    const ct = blob.subarray(IV_LEN, blob.length - TAG_LEN);
-    const decipher = (0, crypto_1.createDecipheriv)(ALGO, masterKey, iv);
-    decipher.setAuthTag(tag);
-    try {
-        return Buffer.concat([decipher.update(ct), decipher.final()]).toString('utf8');
-    }
-    catch {
-        throw new SecretCryptoError('decryption_failed', 'decryption failed (wrong key or tampered ciphertext)');
-    }
-}
-/**
- * Parse a master key from its env-var representation. Accepts:
- *  - 64-char hex string (output of `openssl rand -hex 32`)
- *  - base64 string that decodes to exactly 32 bytes
- *
- * Throws with a clear message if neither — operators set this once and
- * we don't want them silently running with a 16-byte key.
- */
-function parseMasterKey(raw) {
-    const trimmed = raw.trim();
-    if (/^[0-9a-fA-F]{64}$/.test(trimmed)) {
-        return Buffer.from(trimmed, 'hex');
-    }
-    try {
-        const decoded = Buffer.from(trimmed, 'base64');
-        if (decoded.length === KEY_LEN)
-            return decoded;
-    }
-    catch {
-        // fall through to the throw below
-    }
-    throw new SecretCryptoError('invalid_master_key', `MASTER_KEY must be 32 bytes (64 hex chars or base64-encoded). Generate one with: openssl rand -hex 32`);
-}
-/**
- * Compute a stable hint from the plaintext for the UI. Returns the last
- * 4 chars prefixed with "..." (e.g. "...xZ12"). For values shorter than
- * 4 chars, returns a generic placeholder so we never echo the whole
- * secret back.
- */
-function valueHint(plaintext) {
-    if (plaintext.length <= 4)
-        return '••••';
-    return '...' + plaintext.slice(-4);
-}
-function assertMasterKey(key) {
-    if (!Buffer.isBuffer(key) || key.length !== KEY_LEN) {
-        throw new SecretCryptoError('invalid_master_key', `master key must be a 32-byte Buffer (got ${Buffer.isBuffer(key) ? `${key.length} bytes` : typeof key})`);
-    }
-}

package/dist/services/secrets/known-keys.d.ts

@@ -1,38 +0,0 @@
-export type SecretSensitivity = 'critical' | 'high' | 'medium' | 'low';
-export interface KnownSecretDefinition {
-    /** Stable identifier, matches the env-var name. */
-    key: string;
-    /** One-line explanation shown next to the field in the admin UI. */
-    description: string;
-    sensitivity: SecretSensitivity;
-}
-export declare const KNOWN_SECRETS: {
-    readonly ANTHROPIC_API_KEY: {
-        readonly key: "ANTHROPIC_API_KEY";
-        readonly description: "LLM provider key. Required — without it the chat endpoints stop working.";
-        readonly sensitivity: "critical";
-    };
-    readonly STRIPE_SECRET_KEY: {
-        readonly key: "STRIPE_SECRET_KEY";
-        readonly description: "Stripe secret for B2B + B2C billing. Pair with STRIPE_WEBHOOK_SECRET.";
-        readonly sensitivity: "high";
-    };
-    readonly STRIPE_WEBHOOK_SECRET: {
-        readonly key: "STRIPE_WEBHOOK_SECRET";
-        readonly description: "Signs incoming Stripe webhooks. Rotate together with STRIPE_SECRET_KEY.";
-        readonly sensitivity: "high";
-    };
-    readonly TAVILY_API_KEY: {
-        readonly key: "TAVILY_API_KEY";
-        readonly description: "Web search via Tavily. Optional — when missing, web_search falls back to Brave or is omitted.";
-        readonly sensitivity: "medium";
-    };
-    readonly BRAVE_API_KEY: {
-        readonly key: "BRAVE_API_KEY";
-        readonly description: "Web search via Brave Search. Used only when TAVILY_API_KEY is empty.";
-        readonly sensitivity: "medium";
-    };
-};
-export type KnownSecretKey = keyof typeof KNOWN_SECRETS;
-export declare function isKnownSecretKey(key: string): key is KnownSecretKey;
-export declare function listKnownSecrets(): KnownSecretDefinition[];

package/dist/services/secrets/known-keys.js

@@ -1,50 +0,0 @@
-"use strict";
-// The whitelist of platform secrets the operator can manage.
-//
-// Keeping this hardcoded (rather than letting the admin invent new keys
-// from the UI) is deliberate: every secret has to be CONSUMED by code
-// somewhere in the codebase — adding a row that nothing reads is just
-// data clutter and a foot-gun ("why isn't TAVLY_KEY working?"). Adding
-// a new secret is a code change anyway, so the catalog lives in code.
-//
-// `sensitivity` exists so the UI can ask for an extra confirmation step
-// when editing a critical key. Rotating ANTHROPIC_API_KEY mid-conversation
-// breaks every in-flight request; rotating TAVILY_API_KEY just affects
-// the next web search. The UI shouldn't treat them the same.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.KNOWN_SECRETS = void 0;
-exports.isKnownSecretKey = isKnownSecretKey;
-exports.listKnownSecrets = listKnownSecrets;
-exports.KNOWN_SECRETS = {
-    ANTHROPIC_API_KEY: {
-        key: 'ANTHROPIC_API_KEY',
-        description: 'LLM provider key. Required — without it the chat endpoints stop working.',
-        sensitivity: 'critical',
-    },
-    STRIPE_SECRET_KEY: {
-        key: 'STRIPE_SECRET_KEY',
-        description: 'Stripe secret for B2B + B2C billing. Pair with STRIPE_WEBHOOK_SECRET.',
-        sensitivity: 'high',
-    },
-    STRIPE_WEBHOOK_SECRET: {
-        key: 'STRIPE_WEBHOOK_SECRET',
-        description: 'Signs incoming Stripe webhooks. Rotate together with STRIPE_SECRET_KEY.',
-        sensitivity: 'high',
-    },
-    TAVILY_API_KEY: {
-        key: 'TAVILY_API_KEY',
-        description: 'Web search via Tavily. Optional — when missing, web_search falls back to Brave or is omitted.',
-        sensitivity: 'medium',
-    },
-    BRAVE_API_KEY: {
-        key: 'BRAVE_API_KEY',
-        description: 'Web search via Brave Search. Used only when TAVILY_API_KEY is empty.',
-        sensitivity: 'medium',
-    },
-};
-function isKnownSecretKey(key) {
-    return Object.prototype.hasOwnProperty.call(exports.KNOWN_SECRETS, key);
-}
-function listKnownSecrets() {
-    return Object.values(exports.KNOWN_SECRETS);
-}

package/dist/services/secrets.service.d.ts

@@ -1,91 +0,0 @@
-import type { Logger } from './tool-registry.service';
-import type { PlatformSecretRepository } from '../repositories';
-import type { PlatformSecret } from '../domain/platform-secret';
-import { type KnownSecretKey, type KnownSecretDefinition } from './secrets/known-keys';
-export type SecretsErrorCode = 'unknown_key' | 'env_override_active' | 'master_key_missing';
-export declare class SecretsError extends Error {
-    readonly code: SecretsErrorCode;
-    readonly status: number;
-    constructor(code: SecretsErrorCode, message: string);
-}
-/** What admin endpoints / UI receive about a single known secret. Never
- *  carries plaintext or ciphertext — only metadata + hint. */
-export interface PlatformSecretEntry {
-    key: KnownSecretKey;
-    description: string;
-    sensitivity: KnownSecretDefinition['sensitivity'];
-    /** `true` when the value can actually be resolved at boot. */
-    configured: boolean;
-    /** Where the value would come from. `none` when not configured anywhere. */
-    source: 'env' | 'db' | 'none';
-    /** Last 4 chars of the plaintext, or undefined when source !== 'db'. */
-    valueHint?: string;
-    /** Set by the UI; undefined for env-sourced entries. */
-    updatedAt?: Date;
-    updatedByUserId?: string;
-}
-export interface SecretsServiceOptions {
-    /** When omitted, the service starts but every DB-path call returns
-     *  `master_key_missing`. Lets the rest of AgentForge boot when an
-     *  operator forgot to set MASTER_KEY — they can still log in and fix it
-     *  from the UI rather than the server refusing to start. */
-    masterKey?: Buffer;
-    logger?: Logger;
-    /** Override for tests. Defaults to `process.env`. */
-    env?: NodeJS.ProcessEnv;
-}
-export declare class SecretsService {
-    private readonly repo;
-    private readonly cache;
-    private readonly logger;
-    private readonly env;
-    private readonly masterKey?;
-    constructor(repo: PlatformSecretRepository, opts?: SecretsServiceOptions);
-    /**
-     * Resolve a known key. Returns the plaintext or `undefined` when neither
-     * env nor DB has it set. Callers decide whether undefined is fatal (it
-     * is for ANTHROPIC_API_KEY; it's not for TAVILY_API_KEY).
-     *
-     * Cached in memory after first read. Cache survives until the next
-     * upsert/delete on the same key.
-     */
-    resolve(key: KnownSecretKey | (string & {})): Promise<string | undefined>;
-    /**
-     * Bulk variant — resolve every known key at once. Useful at boot when
-     * the server wants to decide which adapters to wire up (Stripe on/off,
-     * which search provider, etc.). Skips logging on individual misses to
-     * keep the boot log readable.
-     */
-    resolveAll(): Promise<Partial<Record<KnownSecretKey, string>>>;
-    /**
-     * Admin-facing catalog. Returns one entry per known key — including
-     * the ones that aren't configured anywhere — so the UI can render the
-     * whole table in one shot.
-     *
-     * Never returns plaintext or ciphertext: only hint + metadata.
-     */
-    listForAdmin(): Promise<PlatformSecretEntry[]>;
-    /**
-     * Upsert a known secret. The new ciphertext + hint hit the DB; the
-     * cache entry is evicted so the next `resolve` re-reads (and decrypts)
-     * fresh data. Returns the row metadata so the UI can echo the hint.
-     *
-     * Throws `unknown_key` for keys outside the catalog (no free-form
-     * inserts), `master_key_missing` when MASTER_KEY isn't configured.
-     */
-    upsert(input: {
-        key: string;
-        value: string;
-        description?: string;
-        updatedByUserId?: string;
-    }): Promise<PlatformSecret>;
-    /**
-     * Hard-delete a known secret. Refuses while the matching env var is
-     * set — otherwise the operator would see "still configured" in the UI
-     * after deleting, which is confusing.
-     */
-    delete(key: string): Promise<void>;
-    /** For tests + admin tools: drop everything from cache so the next
-     *  resolve goes back to env/DB. */
-    clearCache(): void;
-}