@decaf-ts/integrations 0.11.0 → 0.12.0

package/lib/types/namespaces/services/credential.service.d.mts

@@ -0,0 +1,175 @@
+import { Repository } from "@decaf-ts/core";
+import { DeleteSecretOptions, ExistsSecretOptions, RotateSecretOptions, SecretName, SecretPayload, SecretProvider, SecretReference, StoreSecretOptions } from "../../secrets/core/index.d.mts";
+import { CreateCredentialInput, CredentialSummary, RotateCredentialInput } from "../types.d.mts";
+import { BaseModelService } from "../utils.d.mts";
+import { Credential } from "../models/credential.model.d.mts";
+/**
+ * @description Minimal secret-store contract required by the credential service
+ * @summary Structural subset of the secret service API used for credential
+ * values; `rotate` is optional — when absent, rotation falls back to a
+ * re-store under the same secret name.
+ */
+export interface CredentialSecretStore {
+    /** @description Fixed provider discriminator of the backing implementation. */
+    readonly provider: SecretProvider;
+    /** @description Stores (or overwrites) a named secret payload. */
+    store<T extends SecretPayload = SecretPayload>(name: SecretName, value: T, options?: StoreSecretOptions, ...args: any[]): Promise<SecretReference>;
+    /** @description Deletes a stored secret. */
+    delete(nameOrRef: SecretName | SecretReference, options?: DeleteSecretOptions, ...args: any[]): Promise<void>;
+    /** @description Checks whether a secret exists. */
+    exists(nameOrRef: SecretName | SecretReference, options?: ExistsSecretOptions, ...args: any[]): Promise<boolean>;
+    /** @description Optional in-place rotation of a stored secret value. */
+    rotate?(nameOrRef: SecretName | SecretReference, value: SecretPayload, options?: RotateSecretOptions, ...args: any[]): Promise<SecretReference>;
+}
+/**
+ * @description Injection configuration for the credential service
+ * @summary When `secretService` is omitted, the service lazily boots a
+ * `{@link ModelSecretService}` on first use; when `repository` is omitted,
+ * the base `BaseModelService` repository for `{@link Credential}` is used.
+ */
+export interface CredentialServiceConfig {
+    /** @description Secret store for credential values (must have `provider: "model"`). */
+    secretService?: CredentialSecretStore;
+    /** @description Repository backing the `Credential` metadata rows. */
+    repository?: Repository<Credential, any>;
+}
+/**
+ * @description Manages namespaced credentials and their encrypted secret values
+ * @summary Extends `BaseModelService<Credential>` to create, rotate, read,
+ * list, use-mark, and delete credentials. On create, the secret value is
+ * stored under a generated name first and the metadata row second; if the
+ * row insert fails, the stored secret is force-deleted so no orphaned secret
+ * remains. Deletion mirrors that: the row is removed, then the secret value.
+ * The secret store must resolve to `provider: "model"` — user/runtime
+ * credentials always live in the model-backed secret service.
+ * @category Namespaces
+ * @example
+ * ```ts
+ * import { CredentialService } from "@decaf-ts/integrations/namespaces";
+ *
+ * const credentials = new CredentialService();
+ * const credential = await credentials.createCredential({
+ *   tenantId: "tenant-1",
+ *   name: "deploy-token",
+ *   credentialType: "token",
+ *   secret: { value: "s3cr3t" },
+ * });
+ * await credentials.rotateCredential({
+ *   credentialId: credential.id,
+ *   secret: { value: "n3w-s3cr3t" },
+ * });
+ * ```
+ */
+export declare class CredentialService extends BaseModelService<Credential> {
+    private secretServiceInstance?;
+    /**
+     * @description Creates the credential service
+     * @param {CredentialServiceConfig} [config] - Optional secret store and repository overrides.
+     */
+    constructor(config?: CredentialServiceConfig);
+    /**
+     * @description Resolves the model-backed secret store, booting one lazily
+     * @summary Returns the injected secret service or lazily boots a fresh
+     * `{@link ModelSecretService}`; rejects with a {@link ValidationError} when
+     * the resolved store's provider is not `"model"`.
+     * @returns {Promise<CredentialSecretStore>} The model-backed secret store.
+     * @throws {ValidationError} When the injected store is not model-backed.
+     */
+    protected secretService(): Promise<CredentialSecretStore>;
+    /**
+     * @description Creates a credential row and stores its secret value
+     * @summary Validates the name (trimmed, ≤255 chars, `[A-Za-z0-9][A-Za-z0-9._-]*`),
+     * stores the secret under a generated `credential-<uuid>` name scoped to the
+     * supplied tenant/org-unit/owner, then inserts the metadata row. If the row
+     * insert fails, the just-stored secret is force-deleted before rethrowing.
+     * @param {CreateCredentialInput} input - Credential definition (name, type, secret value, scoping, metadata).
+     * @param {any[]} args - Optional trailing decaf `Context` forwarded to the store and repository.
+     * @returns {Promise<Credential>} The persisted credential row.
+     * @throws {ValidationError} When the name is invalid.
+     */
+    createCredential(input: CreateCredentialInput, ...args: any[]): Promise<Credential>;
+    /**
+     * @description Replaces a credential's secret value
+     * @summary Uses the backing store's `rotate` when available; otherwise
+     * re-stores the value under the existing secret name with the supplied
+     * version and the credential's tenant/org-unit/owner scoping. The
+     * credential row's `updatedAt` is refreshed afterwards.
+     * @param {RotateCredentialInput} input - Credential id, new secret value, and optional version.
+     * @param {any[]} args - Optional trailing decaf `Context` forwarded to the store and repository.
+     * @returns {Promise<Credential>} The updated credential row.
+     */
+    rotateCredential(input: RotateCredentialInput, ...args: any[]): Promise<Credential>;
+    /**
+     * @description Reads a credential row by id
+     * @summary Runs the read inside the explicit `withinTransaction` boundary
+     * instead of `@transactional()`: a missing trailing `Context` is synthesized
+     * via `logCtx(args, ..., true)`, then the helper reuses an in-flight
+     * `ContextLock` or opens a new one (`resolveTransactionLock` + `begin`),
+     * rolling back on error and committing when this is the outermost frame. On
+     * a TypeORM-backed repository this binds the context's principal to
+     * `app.principal_id` for the duration of the transaction so namespace RLS
+     * applies to the read.
+     * @param {string} credentialId - The credential id.
+     * @param {any[]} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<Credential>} The credential row.
+     */
+    getCredential(credentialId: string, ...args: any[]): Promise<Credential>;
+    /**
+     * @description Lists all credentials as summaries (no secret material)
+     * @param {any[]} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<CredentialSummary[]>} Summary records for every credential.
+     */
+    listCredentials(...args: any[]): Promise<CredentialSummary[]>;
+    /**
+     * @description Stamps a credential's `lastUsedAt` timestamp
+     * @summary Runs the read and the update inside one explicit
+     * `withinTransaction` boundary instead of `@transactional()`: a missing
+     * trailing `Context` is synthesized via `logCtx(args, ..., true)`, then the
+     * helper reuses an in-flight `ContextLock` or opens a new one
+     * (`resolveTransactionLock` + `begin`), rolling back on error and committing
+     * when this is the outermost frame. On a TypeORM-backed repository this
+     * binds the context's principal to `app.principal_id` for the duration of
+     * the transaction so namespace RLS applies to both statements.
+     * @param {string} credentialId - The credential id.
+     * @param {any[]} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<Credential>} The updated credential row.
+     */
+    markCredentialUsed(credentialId: string, ...args: any[]): Promise<Credential>;
+    /**
+     * @description Deletes a credential row and its stored secret value
+     * @summary Removes the metadata row first, then force-deletes the
+     * referenced secret from the backing store.
+     * @param {string} credentialId - The credential id.
+     * @param {any[]} args - Optional trailing decaf `Context` forwarded to the repository and store.
+     * @returns {Promise<void>} Resolves once the row and secret are removed.
+     */
+    deleteCredential(credentialId: string, ...args: any[]): Promise<void>;
+    /**
+     * @description Runs an operation inside an explicit adapter transaction boundary
+     * @summary Mirrors core's `@transactional()` proxy without the decorator:
+     * reuses the `ContextLock` already cached on the context (`transactionLock`)
+     * when a transaction is in flight, otherwise resolves a fresh lock via
+     * `resolveTransactionLock` and `begin`s it, caching it on the context so
+     * nested frames share it. Depth is tracked so nested calls only decrement;
+     * the outermost frame commits. On error the frame rolls back — unless an
+     * inner frame already ended the transaction — and rethrows the original
+     * error. When the repository exposes no adapter `transactionLock` (e.g.
+     * non-transactional adapters or repository doubles), the operation runs
+     * directly with no transaction. If `ctx` is `undefined`, a standalone
+     * context is synthesized via `this.context`.
+     * @template R - The operation's result type.
+     * @param {Context<any> | undefined} ctx - The caller's decaf `Context`, if one was resolved or synthesized.
+     * @param {() => Promise<R>} operation - The repository work to run inside the transaction.
+     * @returns {Promise<R>} The operation's result, committed when outermost.
+     * @throws {InternalError} When the outermost commit fails.
+     */
+    private withinTransaction;
+    /**
+     * @description Maps a credential row to its API summary shape
+     * @summary Resolves tenant/org-unit/owner relations to their ids and strips
+     * all secret material (the secret value is never exposed).
+     * @param {Credential} credential - The credential row.
+     * @returns {CredentialSummary} The summary record.
+     */
+    private toSummary;
+}

package/lib/types/namespaces/services/index.d.cts

@@ -22,3 +22,4 @@ export * from "./storage-binding.service.d.cts";
 export * from "./bootstrap.service.d.cts";
 export * from "./system-management.service.d.cts";
 export * from "./authz.service.d.cts";
+export * from "./credential.service.d.cts";

package/lib/types/namespaces/services/index.d.mts

@@ -22,3 +22,4 @@ export * from "./storage-binding.service.d.mts";
 export * from "./bootstrap.service.d.mts";
 export * from "./system-management.service.d.mts";
 export * from "./authz.service.d.mts";
+export * from "./credential.service.d.mts";

package/lib/types/namespaces/types.d.cts

@@ -52,6 +52,10 @@ export declare enum StorageBindingKind {
     Shared = "shared",
     Dedicated = "dedicated"
 }
+export declare enum CredentialProvider {
+    Model = "model",
+    Filesystem = "filesystem"
+}
 export declare const IsolationTierOptions: IsolationTier[];
 export declare const MembershipStatusOptions: MembershipStatus[];
 export declare const PrincipalKindOptions: PrincipalKind[];
@@ -60,6 +64,7 @@ export declare const PermissionCategoryOptions: PermissionCategory[];
 export declare const ResourceVisibilityOptions: ResourceVisibility[];
 export declare const StorageKindOptions: StorageKind[];
 export declare const StorageBindingKindOptions: StorageBindingKind[];
+export declare const CredentialProviderOptions: CredentialProvider[];
 export type TxArgs = any[];
 export interface CreateTenantInput {
     slug: string;
@@ -162,6 +167,38 @@ export interface CreateStorageBindingInput {
     region: string;
     config?: Record<string, unknown>;
 }
+export interface CreateCredentialInput {
+    tenantId: string;
+    orgUnitId?: string;
+    ownerPrincipalId?: string;
+    name: string;
+    credentialType: string;
+    secret: string | Record<string, unknown> | Uint8Array;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    expiresAt?: Date;
+}
+export interface RotateCredentialInput {
+    credentialId: string;
+    secret: string | Record<string, unknown> | Uint8Array;
+    version?: string;
+}
+export interface CredentialSummary {
+    id: string;
+    tenantId: string;
+    orgUnitId?: string;
+    ownerPrincipalId?: string;
+    name: string;
+    credentialType: string;
+    provider: CredentialProvider;
+    description?: string;
+    enabled: boolean;
+    metadata?: Record<string, unknown>;
+    expiresAt?: Date;
+    lastUsedAt?: Date;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
 export interface BootstrapPermission {
     key: string;
     category: PermissionCategory;

package/lib/types/namespaces/types.d.mts

@@ -52,6 +52,10 @@ export declare enum StorageBindingKind {
     Shared = "shared",
     Dedicated = "dedicated"
 }
+export declare enum CredentialProvider {
+    Model = "model",
+    Filesystem = "filesystem"
+}
 export declare const IsolationTierOptions: IsolationTier[];
 export declare const MembershipStatusOptions: MembershipStatus[];
 export declare const PrincipalKindOptions: PrincipalKind[];
@@ -60,6 +64,7 @@ export declare const PermissionCategoryOptions: PermissionCategory[];
 export declare const ResourceVisibilityOptions: ResourceVisibility[];
 export declare const StorageKindOptions: StorageKind[];
 export declare const StorageBindingKindOptions: StorageBindingKind[];
+export declare const CredentialProviderOptions: CredentialProvider[];
 export type TxArgs = any[];
 export interface CreateTenantInput {
     slug: string;
@@ -162,6 +167,38 @@ export interface CreateStorageBindingInput {
     region: string;
     config?: Record<string, unknown>;
 }
+export interface CreateCredentialInput {
+    tenantId: string;
+    orgUnitId?: string;
+    ownerPrincipalId?: string;
+    name: string;
+    credentialType: string;
+    secret: string | Record<string, unknown> | Uint8Array;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    expiresAt?: Date;
+}
+export interface RotateCredentialInput {
+    credentialId: string;
+    secret: string | Record<string, unknown> | Uint8Array;
+    version?: string;
+}
+export interface CredentialSummary {
+    id: string;
+    tenantId: string;
+    orgUnitId?: string;
+    ownerPrincipalId?: string;
+    name: string;
+    credentialType: string;
+    provider: CredentialProvider;
+    description?: string;
+    enabled: boolean;
+    metadata?: Record<string, unknown>;
+    expiresAt?: Date;
+    lastUsedAt?: Date;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
 export interface BootstrapPermission {
     key: string;
     category: PermissionCategory;

package/lib/types/redis/adapter.d.cts

@@ -274,6 +274,8 @@ export declare class RedisAdapter extends Adapter<RedisConfig, RedisClientType,
      * through a `for()` configuration-scoped proxy, whose own `_client` slot would
      * otherwise be empty and build a fresh unconnected client). Otherwise builds a
      * node-redis client from the configured URL or discrete host/port/credentials.
+     * When `tls` is set, `tls: true` plus any supplied `tls.connect` options are
+     * merged into the socket options (a `rediss://` URL is passed through as-is).
      * The client is created lazily and connected by {@link initialize}.
      * @return {RedisClientType} The Redis client
      */

package/lib/types/redis/adapter.d.mts

@@ -274,6 +274,8 @@ export declare class RedisAdapter extends Adapter<RedisConfig, RedisClientType,
      * through a `for()` configuration-scoped proxy, whose own `_client` slot would
      * otherwise be empty and build a fresh unconnected client). Otherwise builds a
      * node-redis client from the configured URL or discrete host/port/credentials.
+     * When `tls` is set, `tls: true` plus any supplied `tls.connect` options are
+     * merged into the socket options (a `rediss://` URL is passed through as-is).
      * The client is created lazily and connected by {@link initialize}.
      * @return {RedisClientType} The Redis client
      */

package/lib/types/redis/types.d.cts

@@ -1,13 +1,36 @@
 import { Model } from "@decaf-ts/decorator-validation";
 import { Constructor } from "@decaf-ts/decoration";
 import { AdapterFlags, Context } from "@decaf-ts/core";
+/**
+ * @description TLS settings accepted by {@link RedisAdapter}
+ * @summary `true` enables TLS with Node's default verification (server
+ * certificate checked). An object enables TLS and forwards the standard Node
+ * `tls.connect` options (`rejectUnauthorized`, `ca`, `cert`, `key`,
+ * `servername`); set `rejectUnauthorized: false` only for a known development
+ * server with a self-signed certificate.
+ * @typedef {boolean | object} RedisTlsConfig
+ * @memberOf module:redis
+ */
+export type RedisTlsConfig = boolean | {
+    rejectUnauthorized?: boolean;
+    ca?: string | Buffer;
+    cert?: string | Buffer;
+    key?: string | Buffer;
+    servername?: string;
+    [key: string]: unknown;
+};
 /**
  * @description Connection configuration accepted by {@link RedisAdapter}
  * @summary Supports both a full connection URL and the individual host/port/
  * credential fields. When `url` is provided it takes precedence over the
- * discrete fields.
+ * discrete fields. Set `tls` (or use a `rediss://` URL) to encrypt the
+ * connection.
+ *
+ * Note on `KEYS`: Redis `KEYS` walks the whole keyspace and blocks the server
+ * while it runs. Prefer `SCAN`/`scanIterator` (or a maintained index) in
+ * production; the adapter's key listing is intended for small namespaces.
  * @typedef {object} RedisConfig
- * @property {string} [url] Full redis:// connection string
+ * @property {string} [url] Full redis:// (or rediss://) connection string
  * @property {string} [host] Server host (defaults to localhost)
  * @property {number} [port] Server port (defaults to 6379)
  * @property {string} [username] ACL username
@@ -15,6 +38,7 @@ import { AdapterFlags, Context } from "@decaf-ts/core";
  * @property {number} [database] Logical database index
  * @property {string} [prefix] Key namespace (defaults to decaf:redis)
  * @property {string} [user] Identity reported on created/updated records
+ * @property {RedisTlsConfig} [tls] Enable TLS and optionally supply verification options
  * @memberOf module:redis
  */
 export type RedisConfig = {
@@ -26,6 +50,7 @@ export type RedisConfig = {
     database?: number;
     prefix?: string;
     user?: string;
+    tls?: RedisTlsConfig;
 };
 /**
  * @description Adapter flags enriched with the acting user identity

package/lib/types/redis/types.d.mts

@@ -1,13 +1,36 @@
 import { Model } from "@decaf-ts/decorator-validation";
 import { Constructor } from "@decaf-ts/decoration";
 import { AdapterFlags, Context } from "@decaf-ts/core";
+/**
+ * @description TLS settings accepted by {@link RedisAdapter}
+ * @summary `true` enables TLS with Node's default verification (server
+ * certificate checked). An object enables TLS and forwards the standard Node
+ * `tls.connect` options (`rejectUnauthorized`, `ca`, `cert`, `key`,
+ * `servername`); set `rejectUnauthorized: false` only for a known development
+ * server with a self-signed certificate.
+ * @typedef {boolean | object} RedisTlsConfig
+ * @memberOf module:redis
+ */
+export type RedisTlsConfig = boolean | {
+    rejectUnauthorized?: boolean;
+    ca?: string | Buffer;
+    cert?: string | Buffer;
+    key?: string | Buffer;
+    servername?: string;
+    [key: string]: unknown;
+};
 /**
  * @description Connection configuration accepted by {@link RedisAdapter}
  * @summary Supports both a full connection URL and the individual host/port/
  * credential fields. When `url` is provided it takes precedence over the
- * discrete fields.
+ * discrete fields. Set `tls` (or use a `rediss://` URL) to encrypt the
+ * connection.
+ *
+ * Note on `KEYS`: Redis `KEYS` walks the whole keyspace and blocks the server
+ * while it runs. Prefer `SCAN`/`scanIterator` (or a maintained index) in
+ * production; the adapter's key listing is intended for small namespaces.
  * @typedef {object} RedisConfig
- * @property {string} [url] Full redis:// connection string
+ * @property {string} [url] Full redis:// (or rediss://) connection string
  * @property {string} [host] Server host (defaults to localhost)
  * @property {number} [port] Server port (defaults to 6379)
  * @property {string} [username] ACL username
@@ -15,6 +38,7 @@ import { AdapterFlags, Context } from "@decaf-ts/core";
  * @property {number} [database] Logical database index
  * @property {string} [prefix] Key namespace (defaults to decaf:redis)
  * @property {string} [user] Identity reported on created/updated records
+ * @property {RedisTlsConfig} [tls] Enable TLS and optionally supply verification options
  * @memberOf module:redis
  */
 export type RedisConfig = {
@@ -26,6 +50,7 @@ export type RedisConfig = {
     database?: number;
     prefix?: string;
     user?: string;
+    tls?: RedisTlsConfig;
 };
 /**
  * @description Adapter flags enriched with the acting user identity

package/lib/types/secrets/InfraCredentialBootstrap.d.cts

@@ -0,0 +1,100 @@
+/**
+ * @module integrations/secrets/infra-credential-bootstrap
+ * @summary Idempotent seeding of infrastructure credentials into a secret store.
+ * @description Provides the minimal {@link InfraSecretStore} contract consumed
+ * by {@link InfraCredentialBootstrap}, the {@link InfraCredentialSeed} input
+ * shape, and the `createInfraCredentialBootstrap` factory that wires the
+ * bootstrap to a booted `{@link FsSecretService}`. Intended for startup
+ * routines that must guarantee a known set of credentials (for example the
+ * Mailpit SMTP credentials) exists before services boot against them.
+ */
+import type { DeleteSecretOptions, ExistsSecretOptions, RetrieveSecretOptions, SecretName, SecretPayload, SecretReference, StoreSecretOptions } from "./core/index.d.cts";
+/**
+ * @description Minimal secret-store contract required by the credential bootstrap
+ * @summary Structural subset of the secret service API (`store`, `retrieve`,
+ * `delete`, `exists`) so any backend — including test doubles — can back the
+ * bootstrap without importing the full service hierarchy.
+ */
+export interface InfraSecretStore {
+    /** @description Stores (or overwrites) a named secret payload. */
+    store<T extends SecretPayload = SecretPayload>(name: SecretName, value: T, options?: StoreSecretOptions, ...args: any[]): Promise<SecretReference>;
+    /** @description Reads and decrypts a stored secret payload. */
+    retrieve<T extends SecretPayload = SecretPayload>(nameOrRef: SecretName | SecretReference, options?: RetrieveSecretOptions, ...args: any[]): Promise<T>;
+    /** @description Deletes a stored secret. */
+    delete(nameOrRef: SecretName | SecretReference, options?: DeleteSecretOptions, ...args: any[]): Promise<void>;
+    /** @description Checks whether a secret exists. */
+    exists(nameOrRef: SecretName | SecretReference, options?: ExistsSecretOptions, ...args: any[]): Promise<boolean>;
+}
+/**
+ * @description One credential to guarantee existence of in the secret store
+ * @summary `overwrite: false` (the default) makes `ensure` skip seeds whose
+ * name already exists, keeping stored values stable across restarts.
+ */
+export interface InfraCredentialSeed {
+    /** @description Secret name to seed (normalized by the backing store). */
+    name: SecretName;
+    /** @description Payload to store. */
+    value: SecretPayload;
+    /** @description Optional content type recorded with the secret. */
+    contentType?: string;
+    /** @description Optional tags recorded with the secret. */
+    tags?: Record<string, string>;
+    /** @description When `true`, re-store (overwrite) even if the secret already exists. */
+    overwrite?: boolean;
+}
+/**
+ * @description Idempotent infrastructure credential seeder
+ * @summary Wraps an {@link InfraSecretStore} and guarantees a set of named
+ * credentials exists: `ensure` stores each missing seed (skipping existing
+ * ones unless `overwrite` is set), `retrieve` reads one back. References
+ * returned by `ensure` identify the stored secrets for later cleanup.
+ * @category Secrets
+ * @example
+ * ```ts
+ * import { createInfraCredentialBootstrap } from "@decaf-ts/integrations/secrets";
+ *
+ * const bootstrap = await createInfraCredentialBootstrap({
+ *   keySecret: "master-key",
+ * });
+ * await bootstrap.ensure([
+ *   { name: "smtp-user", value: { value: "mailpit" } },
+ * ]);
+ * ```
+ */
+export declare class InfraCredentialBootstrap {
+    readonly service: InfraSecretStore;
+    /**
+     * @description Creates a bootstrap bound to the given secret store
+     * @param {InfraSecretStore} service - The backing secret store (typically an `FsSecretService`).
+     */
+    constructor(service: InfraSecretStore);
+    /**
+     * @description Ensures every seed exists in the backing store
+     * @summary For each seed, skips when the secret already exists and
+     * `overwrite` is not set; otherwise stores it and collects the returned
+     * references. Existing-but-skipped seeds contribute no reference.
+     * @param {readonly InfraCredentialSeed[]} seeds - The credentials to guarantee.
+     * @param {any[]} args - Optional trailing decaf `Context` forwarded to the store.
+     * @returns {Promise<SecretReference[]>} References for the seeds actually stored during this call.
+     */
+    ensure(seeds: readonly InfraCredentialSeed[], ...args: any[]): Promise<SecretReference[]>;
+    /**
+     * @description Retrieves a previously seeded credential payload
+     * @summary Thin wrapper over the backing store's `retrieve`, resolving
+     * through the bootstrap's store so callers do not need the service instance.
+     * @template T - The expected payload type.
+     * @param {SecretName} name - The secret name to read.
+     * @param {any[]} args - Optional trailing decaf `Context` forwarded to the store.
+     * @returns {Promise<T>} The decrypted payload.
+     */
+    retrieve<T extends SecretPayload = SecretPayload>(name: SecretName, ...args: any[]): Promise<T>;
+}
+/**
+ * @description Creates a bootstrap wired to a freshly booted filesystem secret service
+ * @summary Constructs an `{@link FsSecretService}`, boots it with the supplied
+ * arguments (explicit config or the `secrets.fs` Environment slice), and wraps
+ * it in an {@link InfraCredentialBootstrap}.
+ * @param {any[]} args - `boot()` arguments forwarded to the `FsSecretService` (config and optional `Context`).
+ * @returns {Promise<InfraCredentialBootstrap>} The bootstrap backed by the booted service.
+ */
+export declare function createInfraCredentialBootstrap(...args: any[]): Promise<InfraCredentialBootstrap>;

package/lib/types/secrets/InfraCredentialBootstrap.d.mts

@@ -0,0 +1,100 @@
+/**
+ * @module integrations/secrets/infra-credential-bootstrap
+ * @summary Idempotent seeding of infrastructure credentials into a secret store.
+ * @description Provides the minimal {@link InfraSecretStore} contract consumed
+ * by {@link InfraCredentialBootstrap}, the {@link InfraCredentialSeed} input
+ * shape, and the `createInfraCredentialBootstrap` factory that wires the
+ * bootstrap to a booted `{@link FsSecretService}`. Intended for startup
+ * routines that must guarantee a known set of credentials (for example the
+ * Mailpit SMTP credentials) exists before services boot against them.
+ */
+import type { DeleteSecretOptions, ExistsSecretOptions, RetrieveSecretOptions, SecretName, SecretPayload, SecretReference, StoreSecretOptions } from "./core/index.d.mts";
+/**
+ * @description Minimal secret-store contract required by the credential bootstrap
+ * @summary Structural subset of the secret service API (`store`, `retrieve`,
+ * `delete`, `exists`) so any backend — including test doubles — can back the
+ * bootstrap without importing the full service hierarchy.
+ */
+export interface InfraSecretStore {
+    /** @description Stores (or overwrites) a named secret payload. */
+    store<T extends SecretPayload = SecretPayload>(name: SecretName, value: T, options?: StoreSecretOptions, ...args: any[]): Promise<SecretReference>;
+    /** @description Reads and decrypts a stored secret payload. */
+    retrieve<T extends SecretPayload = SecretPayload>(nameOrRef: SecretName | SecretReference, options?: RetrieveSecretOptions, ...args: any[]): Promise<T>;
+    /** @description Deletes a stored secret. */
+    delete(nameOrRef: SecretName | SecretReference, options?: DeleteSecretOptions, ...args: any[]): Promise<void>;
+    /** @description Checks whether a secret exists. */
+    exists(nameOrRef: SecretName | SecretReference, options?: ExistsSecretOptions, ...args: any[]): Promise<boolean>;
+}
+/**
+ * @description One credential to guarantee existence of in the secret store
+ * @summary `overwrite: false` (the default) makes `ensure` skip seeds whose
+ * name already exists, keeping stored values stable across restarts.
+ */
+export interface InfraCredentialSeed {
+    /** @description Secret name to seed (normalized by the backing store). */
+    name: SecretName;
+    /** @description Payload to store. */
+    value: SecretPayload;
+    /** @description Optional content type recorded with the secret. */
+    contentType?: string;
+    /** @description Optional tags recorded with the secret. */
+    tags?: Record<string, string>;
+    /** @description When `true`, re-store (overwrite) even if the secret already exists. */
+    overwrite?: boolean;
+}
+/**
+ * @description Idempotent infrastructure credential seeder
+ * @summary Wraps an {@link InfraSecretStore} and guarantees a set of named
+ * credentials exists: `ensure` stores each missing seed (skipping existing
+ * ones unless `overwrite` is set), `retrieve` reads one back. References
+ * returned by `ensure` identify the stored secrets for later cleanup.
+ * @category Secrets
+ * @example
+ * ```ts
+ * import { createInfraCredentialBootstrap } from "@decaf-ts/integrations/secrets";
+ *
+ * const bootstrap = await createInfraCredentialBootstrap({
+ *   keySecret: "master-key",
+ * });
+ * await bootstrap.ensure([
+ *   { name: "smtp-user", value: { value: "mailpit" } },
+ * ]);
+ * ```
+ */
+export declare class InfraCredentialBootstrap {
+    readonly service: InfraSecretStore;
+    /**
+     * @description Creates a bootstrap bound to the given secret store
+     * @param {InfraSecretStore} service - The backing secret store (typically an `FsSecretService`).
+     */
+    constructor(service: InfraSecretStore);
+    /**
+     * @description Ensures every seed exists in the backing store
+     * @summary For each seed, skips when the secret already exists and
+     * `overwrite` is not set; otherwise stores it and collects the returned
+     * references. Existing-but-skipped seeds contribute no reference.
+     * @param {readonly InfraCredentialSeed[]} seeds - The credentials to guarantee.
+     * @param {any[]} args - Optional trailing decaf `Context` forwarded to the store.
+     * @returns {Promise<SecretReference[]>} References for the seeds actually stored during this call.
+     */
+    ensure(seeds: readonly InfraCredentialSeed[], ...args: any[]): Promise<SecretReference[]>;
+    /**
+     * @description Retrieves a previously seeded credential payload
+     * @summary Thin wrapper over the backing store's `retrieve`, resolving
+     * through the bootstrap's store so callers do not need the service instance.
+     * @template T - The expected payload type.
+     * @param {SecretName} name - The secret name to read.
+     * @param {any[]} args - Optional trailing decaf `Context` forwarded to the store.
+     * @returns {Promise<T>} The decrypted payload.
+     */
+    retrieve<T extends SecretPayload = SecretPayload>(name: SecretName, ...args: any[]): Promise<T>;
+}
+/**
+ * @description Creates a bootstrap wired to a freshly booted filesystem secret service
+ * @summary Constructs an `{@link FsSecretService}`, boots it with the supplied
+ * arguments (explicit config or the `secrets.fs` Environment slice), and wraps
+ * it in an {@link InfraCredentialBootstrap}.
+ * @param {any[]} args - `boot()` arguments forwarded to the `FsSecretService` (config and optional `Context`).
+ * @returns {Promise<InfraCredentialBootstrap>} The bootstrap backed by the booted service.
+ */
+export declare function createInfraCredentialBootstrap(...args: any[]): Promise<InfraCredentialBootstrap>;

package/lib/types/secrets/core/SecretTypes.d.cts

@@ -3,7 +3,7 @@
  * @summary Secret core types.
  * @description Shared payload, metadata, option, and configuration types for secret service implementations.
  */
-export type SecretProvider = "model" | "memory" | "hashicorp-vault" | "aws-secrets-manager" | "azure-key-vault" | "gcp-secret-manager" | "1password";
+export type SecretProvider = "model" | "memory" | "filesystem" | "hashicorp-vault" | "aws-secrets-manager" | "azure-key-vault" | "gcp-secret-manager" | "1password";
 export type SecretName = string;
 export type SecretPayload = string | Record<string, unknown> | Uint8Array;
 export interface SerializedSecretPayload {
@@ -47,6 +47,20 @@ export interface StoreSecretOptions {
     tags?: Record<string, string>;
     version?: string;
     ttl?: number;
+    /**
+     * @description Namespace tenant that owns the secret.
+     * @summary Stamped onto model-backed secrets so the namespace RLS policies
+     * can scope reads and writes without joining the credential row.
+     */
+    tenantId?: string;
+    /**
+     * @description Organizational unit that owns the secret.
+     */
+    orgUnitId?: string;
+    /**
+     * @description Principal that owns the secret.
+     */
+    ownerPrincipalId?: string;
 }
 export interface RetrieveSecretOptions {
     version?: string;