@decaf-ts/integrations 0.11.0 → 0.12.0

package/lib/types/secrets/model/ModelSecretService.d.cts

@@ -1,22 +1,211 @@
+/**
+ * @module integrations/secrets/model/service
+ * @summary Model-backed encrypted secret service.
+ * @description Implements the `{@link ModelSecretService}`, an undecorated
+ * `ClientBasedSecretService` that
+ * persists AES-encrypted payloads as `{@link Secret}` rows through a
+ * decaf `Repository` (tenant/org-unit/owner scoping included). Encryption
+ * keys derive from a master `keySecret` via `CryptoService`; configuration
+ * comes from the `secrets.model` Environment slice or an explicit boot
+ * config (see `ModelSecretServiceConfig`).
+ */
 import { ClientBasedSecretService, SecretError, SecretProvider } from "../core/index.d.cts";
 import { SecretName, SecretPayload, SecretReference, SecretMetadata } from "../core/index.d.cts";
-import { StoreSecretOptions, RetrieveSecretOptions, DeleteSecretOptions, ExistsSecretOptions, ListSecretsOptions, SecretMetadataOptions } from "../core/index.d.cts";
+import { StoreSecretOptions, RetrieveSecretOptions, DeleteSecretOptions, ExistsSecretOptions, ListSecretsOptions, SecretMetadataOptions, RotateSecretOptions } from "../core/index.d.cts";
 import { Secret } from "./Secret.d.cts";
 import { ContextualArgs, MaybeContextualArg, Repository } from "@decaf-ts/core";
 import { ModelSecretServiceConfig } from "./ModelSecretServiceConfig.d.cts";
+/**
+ * @description Model-backed encrypted secret service
+ * @summary Stores each secret as a `{@link Secret}` row (encrypted payload,
+ * key id/iv/salt metadata, version, enablement flag, and optional
+ * tenant/org-unit/owner scope) through the repository booted as the service
+ * client. Names are validated and normalized before persistence;
+ * `(name, version)` is unique (enforced by a `SECRET_ALREADY_EXISTS`
+ * conflict in `store`/`rotate` and backed by the `uq_secrets_name_version`
+ * database index); retrieval only considers enabled rows, supports version
+ * pinning, and resolves multiple matches deterministically by `updatedAt
+ * DESC`. Delete is soft by default (sets `enabled: false`) unless
+ * `options.force` is set. Errors from the repository are translated into
+ * typed {@link SecretError}s by `parseError`.
+ *
+ * Undecorated and Environment-configurable
+ * through the `secrets.model` slice; the credential service
+ * (`CredentialService`) delegates user/runtime credential storage to this
+ * service.
+ * @class ModelSecretService
+ * @category Secrets
+ * @example
+ * ```ts
+ * import { ModelSecretService } from "@decaf-ts/integrations/secrets";
+ *
+ * const modelSecrets = await new ModelSecretService().boot({
+ *   keySecret: "model-master-key",
+ * });
+ * await modelSecrets.store("my-secret", { value: "s3cr3t" });
+ * const payload = await modelSecrets.retrieve<{ value: string }>("my-secret");
+ * ```
+ */
 export declare class ModelSecretService extends ClientBasedSecretService<Repository<Secret, any>, ModelSecretServiceConfig> {
     readonly provider: SecretProvider;
     private cryptoService;
+    constructor();
+    /**
+     * @description Builds the model secret configuration from the Environment
+     * @summary Reads the `secrets.model` Environment slice and returns a
+     * `ModelSecretServiceConfig` when a `keySecret` is configured; returns
+     * `undefined` otherwise, letting boot fall back to explicit arguments.
+     * @returns {ModelSecretServiceConfig | undefined} The Environment-derived configuration, or `undefined`.
+     * @override
+     */
     protected configFromEnvironment(): ModelSecretServiceConfig | undefined;
+    /**
+     * @description Boots the crypto service and resolves the backing repository
+     * @summary Accepts the configuration (explicit args, merged with the
+     * Environment slice by the base) and an optional `Repository<Secret>` as the
+     * second argument; when absent, creates one via `Repository.forModel(Secret)`.
+     * Returns the config and repository as the service client.
+     * @param {ContextualArgs} args - Configuration and optional `Repository`/`Context` arguments.
+     * @returns {Promise<{config: ModelSecretServiceConfig, client: Repository<Secret, any>}>} The resolved config and repository client.
+     */
     initialize(...args: ContextualArgs<any>): Promise<{
         config: ModelSecretServiceConfig;
         client: Repository<Secret, any>;
     }>;
+    /**
+     * @description Encrypts and persists a secret row
+     * @summary Validates and normalizes the name, serializes the payload, and
+     * encrypts it with a key derived from the master `keySecret`, embedding the
+     * key id/iv/salt in the row's `encryption` metadata. The row carries the
+     * optional tenant/org-unit/owner scoping and version. `(name, version)` is
+     * unique: an application-level pre-check rejects a duplicate combination
+     * with a `SECRET_ALREADY_EXISTS` {@link SecretError} before the insert, and
+     * the `uq_secrets_name_version` database index (which treats `NULL`
+     * versions as `''`) backstops the same rule against concurrent writers.
+     * @template T - The secret payload type.
+     * @param {SecretName} name - The secret name (validated and normalized).
+     * @param {T} value - The payload to encrypt and store.
+     * @param {StoreSecretOptions} [options] - Optional content type, tags, version, and tenant/org/owner scoping.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<SecretReference>} A reference to the persisted secret.
+     * @throws {SecretError} `SECRET_ALREADY_EXISTS` when a row with the same normalized name and version already exists, or `SECRET_NOT_FOUND`/`SECRET_PROVIDER_CONFLICT` when the name is invalid or the repository insert fails.
+     */
     store<T extends SecretPayload = SecretPayload>(name: SecretName, value: T, options?: StoreSecretOptions, ...args: MaybeContextualArg<any>): Promise<SecretReference>;
+    /**
+     * @description Reads, decrypts, and deserializes an enabled secret row
+     * @summary Queries the newest matching enabled row (by normalized name and,
+     * optionally, version), re-derives the key using the row's salt, and decrypts
+     * the payload. Rows are ordered by `updatedAt DESC`, so when several rows
+     * share a name the most recently updated enabled row is resolved
+     * deterministically. The repository SELECT runs inside a principal-bound
+     * transaction (see {@link ModelSecretService.withinPrincipalTransaction}):
+     * it joins an in-flight `transactionLock` on the context or begins one,
+     * binding the context's principal to `app.principal_id` on TypeORM adapters
+     * so namespace RLS applies to the read. Missing rows throw
+     * {@link NotFoundError}; decryption and JSON parse failures throw
+     * `InternalError`.
+     * @template T - The secret payload type.
+     * @param {SecretName | SecretReference} nameOrRef - The secret name or reference.
+     * @param {RetrieveSecretOptions} [options] - Optional version filter.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<T>} The decrypted payload.
+     * @throws {NotFoundError} When no enabled secret matches the name/version.
+     */
     retrieve<T extends SecretPayload = SecretPayload>(nameOrRef: SecretName | SecretReference, options?: RetrieveSecretOptions, ...args: MaybeContextualArg<any>): Promise<T>;
+    /**
+     * @description Runs a repository operation inside a principal-bound transaction
+     * @summary Mirrors core's `@transactional()` proxy for single reads: reuses
+     * the `transactionLock` already cached on the context (nested call), or
+     * resolves a fresh lock for the service client via `resolveTransactionLock`
+     * and calls `begin(context)` - which, on a TypeORM adapter, binds the
+     * context's principal to `app.principal_id` for the new transaction.
+     * Increments the lock depth for the duration of the operation; on failure,
+     * rolls back and zeroes the depth (skipping a redundant rollback when an
+     * inner frame already ended the transaction) and rethrows the original
+     * error; on success, commits when the outermost frame completes.
+     * @template R - The operation result type.
+     * @param {Context} context - The request context, carrying any in-flight transaction lock.
+     * @param {function(ContextLock): Promise<R>} operation - The repository operation to run, receiving the active lock.
+     * @returns {Promise<R>} The operation result.
+     * @throws {InternalError} When the final commit fails; operation errors are rethrown after rollback.
+     */
+    private withinPrincipalTransaction;
+    /**
+     * @description Deletes (or disables) a secret row
+     * @summary Soft-deletes by default: the row is disabled and stamped with a
+     * new `updatedAt`. With `options.force`, the row is hard-deleted from the
+     * repository. Rows are ordered by `updatedAt DESC`, so the most recently
+     * updated matching row is resolved deterministically. A missing secret
+     * resolves silently.
+     * @param {SecretName | SecretReference} nameOrRef - The secret name or reference.
+     * @param {DeleteSecretOptions} [options] - Optional version filter and `force` hard-delete flag.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<void>} Resolves once the row is deleted or disabled.
+     */
     delete(nameOrRef: SecretName | SecretReference, options?: DeleteSecretOptions, ...args: MaybeContextualArg<any>): Promise<void>;
+    /**
+     * @description Checks whether an enabled secret exists (optionally at a version)
+     * @summary Counts enabled rows matching the normalized name (plus any
+     * requested version) and returns whether the count is positive.
+     * @param {SecretName | SecretReference} nameOrRef - The secret name or reference.
+     * @param {ExistsSecretOptions} [options] - Optional version filter.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<boolean>} `true` when at least one enabled row matches.
+     */
     exists(nameOrRef: SecretName | SecretReference, options?: ExistsSecretOptions, ...args: MaybeContextualArg<any>): Promise<boolean>;
+    /**
+     * @description Lists secret metadata across stored rows
+     * @summary Selects rows filtered by the `enabled` flag (when supplied) and
+     * maps them to `SecretMetadata` records (no payloads).
+     * @param {ListSecretsOptions} [options] - Optional `enabled` filter.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<SecretMetadata[]>} Metadata for every matching secret.
+     */
     list(options?: ListSecretsOptions, ...args: MaybeContextualArg<any>): Promise<SecretMetadata[]>;
+    /**
+     * @description Reads one secret's metadata without its payload
+     * @summary Selects the row matching the normalized name (and optional
+     * version) and maps it to `SecretMetadata`; tags are included only when
+     * `options.includeTags` is set. Rows are ordered by `updatedAt DESC`, so
+     * the most recently updated matching row is resolved deterministically.
+     * Returns `undefined` when no row matches.
+     * @param {SecretName | SecretReference} nameOrRef - The secret name or reference.
+     * @param {SecretMetadataOptions} [options] - Optional version filter and `includeTags` flag.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<SecretMetadata | undefined>} The metadata, or `undefined` when absent.
+     */
     metadata(nameOrRef: SecretName | SecretReference, options?: SecretMetadataOptions, ...args: MaybeContextualArg<any>): Promise<SecretMetadata | undefined>;
+    /**
+     * @description Re-encrypts an enabled secret row with a new payload
+     * @summary Locates the enabled row (optionally pinned to
+     * `options.oldVersion`), encrypts the new payload with a freshly derived
+     * key (optionally tagged with `options.keyId`), and updates the row's
+     * payload, encryption metadata, version (`options.newVersion`), and
+     * `updatedAt`. When `options.newVersion` differs from the row's current
+     * version, a `(name, version)` duplicate check rejects the rotation with a
+     * `SECRET_ALREADY_EXISTS` {@link SecretError}; otherwise the target version
+     * is reused and the row is updated in place. Matching rows are ordered by
+     * `updatedAt DESC`, so the most recently updated enabled row is resolved
+     * deterministically.
+     * @template T - The secret payload type.
+     * @param {SecretName | SecretReference} nameOrRef - The secret name or reference.
+     * @param {T} value - The new payload.
+     * @param {RotateSecretOptions} [options] - Optional `newVersion`, `oldVersion`, and `keyId`.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<SecretReference>} A reference reflecting the updated row.
+     * @throws {NotFoundError} When no enabled secret matches the name/version.
+     * @throws {SecretError} `SECRET_ALREADY_EXISTS` when the target `newVersion` is already held by another row with the same normalized name, or `SECRET_PROVIDER_CONFLICT` when the repository update fails.
+     */
+    rotate<T extends SecretPayload = SecretPayload>(nameOrRef: SecretName | SecretReference, value: T, options?: RotateSecretOptions, ...args: MaybeContextualArg<any>): Promise<SecretReference>;
+    /**
+     * @description Translates repository errors into typed secret errors
+     * @summary Inspects the error message for "not found"/404, "already
+     * exists"/conflict/409, and decryption-related markers and maps them to
+     * `SECRET_NOT_FOUND`, `SECRET_ALREADY_EXISTS`,
+     * `SECRET_DECRYPTION_FAILED`, or a generic `SECRET_PROVIDER_CONFLICT`
+     * {@link SecretError}.
+     * @param {unknown} error - The raw error thrown by the repository.
+     * @returns {SecretError} The typed secret error.
+     */
     protected parseError(error: unknown): SecretError;
 }

package/lib/types/secrets/model/ModelSecretService.d.mts

@@ -1,22 +1,211 @@
+/**
+ * @module integrations/secrets/model/service
+ * @summary Model-backed encrypted secret service.
+ * @description Implements the `{@link ModelSecretService}`, an undecorated
+ * `ClientBasedSecretService` that
+ * persists AES-encrypted payloads as `{@link Secret}` rows through a
+ * decaf `Repository` (tenant/org-unit/owner scoping included). Encryption
+ * keys derive from a master `keySecret` via `CryptoService`; configuration
+ * comes from the `secrets.model` Environment slice or an explicit boot
+ * config (see `ModelSecretServiceConfig`).
+ */
 import { ClientBasedSecretService, SecretError, SecretProvider } from "../core/index.d.mts";
 import { SecretName, SecretPayload, SecretReference, SecretMetadata } from "../core/index.d.mts";
-import { StoreSecretOptions, RetrieveSecretOptions, DeleteSecretOptions, ExistsSecretOptions, ListSecretsOptions, SecretMetadataOptions } from "../core/index.d.mts";
+import { StoreSecretOptions, RetrieveSecretOptions, DeleteSecretOptions, ExistsSecretOptions, ListSecretsOptions, SecretMetadataOptions, RotateSecretOptions } from "../core/index.d.mts";
 import { Secret } from "./Secret.d.mts";
 import { ContextualArgs, MaybeContextualArg, Repository } from "@decaf-ts/core";
 import { ModelSecretServiceConfig } from "./ModelSecretServiceConfig.d.mts";
+/**
+ * @description Model-backed encrypted secret service
+ * @summary Stores each secret as a `{@link Secret}` row (encrypted payload,
+ * key id/iv/salt metadata, version, enablement flag, and optional
+ * tenant/org-unit/owner scope) through the repository booted as the service
+ * client. Names are validated and normalized before persistence;
+ * `(name, version)` is unique (enforced by a `SECRET_ALREADY_EXISTS`
+ * conflict in `store`/`rotate` and backed by the `uq_secrets_name_version`
+ * database index); retrieval only considers enabled rows, supports version
+ * pinning, and resolves multiple matches deterministically by `updatedAt
+ * DESC`. Delete is soft by default (sets `enabled: false`) unless
+ * `options.force` is set. Errors from the repository are translated into
+ * typed {@link SecretError}s by `parseError`.
+ *
+ * Undecorated and Environment-configurable
+ * through the `secrets.model` slice; the credential service
+ * (`CredentialService`) delegates user/runtime credential storage to this
+ * service.
+ * @class ModelSecretService
+ * @category Secrets
+ * @example
+ * ```ts
+ * import { ModelSecretService } from "@decaf-ts/integrations/secrets";
+ *
+ * const modelSecrets = await new ModelSecretService().boot({
+ *   keySecret: "model-master-key",
+ * });
+ * await modelSecrets.store("my-secret", { value: "s3cr3t" });
+ * const payload = await modelSecrets.retrieve<{ value: string }>("my-secret");
+ * ```
+ */
 export declare class ModelSecretService extends ClientBasedSecretService<Repository<Secret, any>, ModelSecretServiceConfig> {
     readonly provider: SecretProvider;
     private cryptoService;
+    constructor();
+    /**
+     * @description Builds the model secret configuration from the Environment
+     * @summary Reads the `secrets.model` Environment slice and returns a
+     * `ModelSecretServiceConfig` when a `keySecret` is configured; returns
+     * `undefined` otherwise, letting boot fall back to explicit arguments.
+     * @returns {ModelSecretServiceConfig | undefined} The Environment-derived configuration, or `undefined`.
+     * @override
+     */
     protected configFromEnvironment(): ModelSecretServiceConfig | undefined;
+    /**
+     * @description Boots the crypto service and resolves the backing repository
+     * @summary Accepts the configuration (explicit args, merged with the
+     * Environment slice by the base) and an optional `Repository<Secret>` as the
+     * second argument; when absent, creates one via `Repository.forModel(Secret)`.
+     * Returns the config and repository as the service client.
+     * @param {ContextualArgs} args - Configuration and optional `Repository`/`Context` arguments.
+     * @returns {Promise<{config: ModelSecretServiceConfig, client: Repository<Secret, any>}>} The resolved config and repository client.
+     */
     initialize(...args: ContextualArgs<any>): Promise<{
         config: ModelSecretServiceConfig;
         client: Repository<Secret, any>;
     }>;
+    /**
+     * @description Encrypts and persists a secret row
+     * @summary Validates and normalizes the name, serializes the payload, and
+     * encrypts it with a key derived from the master `keySecret`, embedding the
+     * key id/iv/salt in the row's `encryption` metadata. The row carries the
+     * optional tenant/org-unit/owner scoping and version. `(name, version)` is
+     * unique: an application-level pre-check rejects a duplicate combination
+     * with a `SECRET_ALREADY_EXISTS` {@link SecretError} before the insert, and
+     * the `uq_secrets_name_version` database index (which treats `NULL`
+     * versions as `''`) backstops the same rule against concurrent writers.
+     * @template T - The secret payload type.
+     * @param {SecretName} name - The secret name (validated and normalized).
+     * @param {T} value - The payload to encrypt and store.
+     * @param {StoreSecretOptions} [options] - Optional content type, tags, version, and tenant/org/owner scoping.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<SecretReference>} A reference to the persisted secret.
+     * @throws {SecretError} `SECRET_ALREADY_EXISTS` when a row with the same normalized name and version already exists, or `SECRET_NOT_FOUND`/`SECRET_PROVIDER_CONFLICT` when the name is invalid or the repository insert fails.
+     */
     store<T extends SecretPayload = SecretPayload>(name: SecretName, value: T, options?: StoreSecretOptions, ...args: MaybeContextualArg<any>): Promise<SecretReference>;
+    /**
+     * @description Reads, decrypts, and deserializes an enabled secret row
+     * @summary Queries the newest matching enabled row (by normalized name and,
+     * optionally, version), re-derives the key using the row's salt, and decrypts
+     * the payload. Rows are ordered by `updatedAt DESC`, so when several rows
+     * share a name the most recently updated enabled row is resolved
+     * deterministically. The repository SELECT runs inside a principal-bound
+     * transaction (see {@link ModelSecretService.withinPrincipalTransaction}):
+     * it joins an in-flight `transactionLock` on the context or begins one,
+     * binding the context's principal to `app.principal_id` on TypeORM adapters
+     * so namespace RLS applies to the read. Missing rows throw
+     * {@link NotFoundError}; decryption and JSON parse failures throw
+     * `InternalError`.
+     * @template T - The secret payload type.
+     * @param {SecretName | SecretReference} nameOrRef - The secret name or reference.
+     * @param {RetrieveSecretOptions} [options] - Optional version filter.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<T>} The decrypted payload.
+     * @throws {NotFoundError} When no enabled secret matches the name/version.
+     */
     retrieve<T extends SecretPayload = SecretPayload>(nameOrRef: SecretName | SecretReference, options?: RetrieveSecretOptions, ...args: MaybeContextualArg<any>): Promise<T>;
+    /**
+     * @description Runs a repository operation inside a principal-bound transaction
+     * @summary Mirrors core's `@transactional()` proxy for single reads: reuses
+     * the `transactionLock` already cached on the context (nested call), or
+     * resolves a fresh lock for the service client via `resolveTransactionLock`
+     * and calls `begin(context)` - which, on a TypeORM adapter, binds the
+     * context's principal to `app.principal_id` for the new transaction.
+     * Increments the lock depth for the duration of the operation; on failure,
+     * rolls back and zeroes the depth (skipping a redundant rollback when an
+     * inner frame already ended the transaction) and rethrows the original
+     * error; on success, commits when the outermost frame completes.
+     * @template R - The operation result type.
+     * @param {Context} context - The request context, carrying any in-flight transaction lock.
+     * @param {function(ContextLock): Promise<R>} operation - The repository operation to run, receiving the active lock.
+     * @returns {Promise<R>} The operation result.
+     * @throws {InternalError} When the final commit fails; operation errors are rethrown after rollback.
+     */
+    private withinPrincipalTransaction;
+    /**
+     * @description Deletes (or disables) a secret row
+     * @summary Soft-deletes by default: the row is disabled and stamped with a
+     * new `updatedAt`. With `options.force`, the row is hard-deleted from the
+     * repository. Rows are ordered by `updatedAt DESC`, so the most recently
+     * updated matching row is resolved deterministically. A missing secret
+     * resolves silently.
+     * @param {SecretName | SecretReference} nameOrRef - The secret name or reference.
+     * @param {DeleteSecretOptions} [options] - Optional version filter and `force` hard-delete flag.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<void>} Resolves once the row is deleted or disabled.
+     */
     delete(nameOrRef: SecretName | SecretReference, options?: DeleteSecretOptions, ...args: MaybeContextualArg<any>): Promise<void>;
+    /**
+     * @description Checks whether an enabled secret exists (optionally at a version)
+     * @summary Counts enabled rows matching the normalized name (plus any
+     * requested version) and returns whether the count is positive.
+     * @param {SecretName | SecretReference} nameOrRef - The secret name or reference.
+     * @param {ExistsSecretOptions} [options] - Optional version filter.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<boolean>} `true` when at least one enabled row matches.
+     */
     exists(nameOrRef: SecretName | SecretReference, options?: ExistsSecretOptions, ...args: MaybeContextualArg<any>): Promise<boolean>;
+    /**
+     * @description Lists secret metadata across stored rows
+     * @summary Selects rows filtered by the `enabled` flag (when supplied) and
+     * maps them to `SecretMetadata` records (no payloads).
+     * @param {ListSecretsOptions} [options] - Optional `enabled` filter.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<SecretMetadata[]>} Metadata for every matching secret.
+     */
     list(options?: ListSecretsOptions, ...args: MaybeContextualArg<any>): Promise<SecretMetadata[]>;
+    /**
+     * @description Reads one secret's metadata without its payload
+     * @summary Selects the row matching the normalized name (and optional
+     * version) and maps it to `SecretMetadata`; tags are included only when
+     * `options.includeTags` is set. Rows are ordered by `updatedAt DESC`, so
+     * the most recently updated matching row is resolved deterministically.
+     * Returns `undefined` when no row matches.
+     * @param {SecretName | SecretReference} nameOrRef - The secret name or reference.
+     * @param {SecretMetadataOptions} [options] - Optional version filter and `includeTags` flag.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<SecretMetadata | undefined>} The metadata, or `undefined` when absent.
+     */
     metadata(nameOrRef: SecretName | SecretReference, options?: SecretMetadataOptions, ...args: MaybeContextualArg<any>): Promise<SecretMetadata | undefined>;
+    /**
+     * @description Re-encrypts an enabled secret row with a new payload
+     * @summary Locates the enabled row (optionally pinned to
+     * `options.oldVersion`), encrypts the new payload with a freshly derived
+     * key (optionally tagged with `options.keyId`), and updates the row's
+     * payload, encryption metadata, version (`options.newVersion`), and
+     * `updatedAt`. When `options.newVersion` differs from the row's current
+     * version, a `(name, version)` duplicate check rejects the rotation with a
+     * `SECRET_ALREADY_EXISTS` {@link SecretError}; otherwise the target version
+     * is reused and the row is updated in place. Matching rows are ordered by
+     * `updatedAt DESC`, so the most recently updated enabled row is resolved
+     * deterministically.
+     * @template T - The secret payload type.
+     * @param {SecretName | SecretReference} nameOrRef - The secret name or reference.
+     * @param {T} value - The new payload.
+     * @param {RotateSecretOptions} [options] - Optional `newVersion`, `oldVersion`, and `keyId`.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<SecretReference>} A reference reflecting the updated row.
+     * @throws {NotFoundError} When no enabled secret matches the name/version.
+     * @throws {SecretError} `SECRET_ALREADY_EXISTS` when the target `newVersion` is already held by another row with the same normalized name, or `SECRET_PROVIDER_CONFLICT` when the repository update fails.
+     */
+    rotate<T extends SecretPayload = SecretPayload>(nameOrRef: SecretName | SecretReference, value: T, options?: RotateSecretOptions, ...args: MaybeContextualArg<any>): Promise<SecretReference>;
+    /**
+     * @description Translates repository errors into typed secret errors
+     * @summary Inspects the error message for "not found"/404, "already
+     * exists"/conflict/409, and decryption-related markers and maps them to
+     * `SECRET_NOT_FOUND`, `SECRET_ALREADY_EXISTS`,
+     * `SECRET_DECRYPTION_FAILED`, or a generic `SECRET_PROVIDER_CONFLICT`
+     * {@link SecretError}.
+     * @param {unknown} error - The raw error thrown by the repository.
+     * @returns {SecretError} The typed secret error.
+     */
     protected parseError(error: unknown): SecretError;
 }

package/lib/types/secrets/model/Secret.d.cts

@@ -1,24 +1,65 @@
 /**
- * @module integrations/secrets/model/secret
- * @summary Encrypted secret model types.
- * @description Model payload and metadata types used by the encrypted-at-rest secret service.
+ * @module integrations/secrets/model/model
+ * @summary Encrypted-at-rest secret persistence model.
+ * @description Defines the `{@link Secret}` model (`secrets` table) persisted
+ * by the `{@link ModelSecretService}`: one row per secret, holding the
+ * encrypted payload, `keyId`/`iv`/`salt` encryption metadata, versioning and
+ * enablement fields, and optional tenant/org-unit/owner scoping columns.
  */
 import { BaseModel } from "@decaf-ts/core";
+/**
+ * @description Encryption metadata embedded in a secret row
+ * @summary `keyId` identifies the key used to encrypt the payload; `iv` and
+ * the optional `aad`/`salt` carry the cipher parameters needed to re-derive
+ * the key and decrypt the payload.
+ */
 export interface SecretEncryptionMetadata {
+    /** @description Identifier of the encryption key used for the payload. */
     keyId: string;
+    /** @description Initialization vector used for the payload encryption. */
     iv: string;
+    /** @description Optional additional authenticated data bound to the cipher. */
     aad?: string;
+    /** @description Optional salt used when deriving the key from the master secret. */
+    salt?: string;
 }
+/**
+ * @description Encrypted secret record stored through the model-backed secret service
+ * @summary Persisted in the `secrets` table. The `encryptedPayload` column is
+ * written only by `{@link ModelSecretService}` (which also fills
+ * `encryption`, `version`, and the optional `tenantId`/`orgUnitId`/
+ * `ownerPrincipalId` scoping columns); `enabled: false` marks soft-deleted
+ * secrets that retrieval filters out.
+ * @category Secrets
+ */
 export declare class Secret extends BaseModel {
+    /** @description Primary key (UUID). */
+    id: string;
+    /** @description Normalized secret name. */
     name: string;
+    /** @description Secret provider discriminator that wrote the row. */
     provider: string;
+    /** @description Encrypted, serialized payload. */
     encryptedPayload: string;
+    /** @description Cipher parameters required to decrypt the payload. */
     encryption: SecretEncryptionMetadata;
+    /** @description Optional content type describing the payload. */
     contentType?: string;
+    /** @description Optional free-form tags. */
     tags?: Record<string, string>;
+    /** @description When `false`, the secret is soft-deleted and filtered from retrieval. */
     enabled: boolean;
+    /** @description Optional version label. */
     version?: string;
+    /** @description Optional external identifier linking the secret to a provider record. */
     externalId?: string;
+    /** @description Optional provider URI for externally stored secrets. */
     uri?: string;
+    /** @description Optional tenant scope id. */
+    tenantId?: string;
+    /** @description Optional organizational unit scope id. */
+    orgUnitId?: string;
+    /** @description Optional owning principal id. */
+    ownerPrincipalId?: string;
     constructor(data?: Partial<Secret>);
 }

package/lib/types/secrets/model/Secret.d.mts

@@ -1,24 +1,65 @@
 /**
- * @module integrations/secrets/model/secret
- * @summary Encrypted secret model types.
- * @description Model payload and metadata types used by the encrypted-at-rest secret service.
+ * @module integrations/secrets/model/model
+ * @summary Encrypted-at-rest secret persistence model.
+ * @description Defines the `{@link Secret}` model (`secrets` table) persisted
+ * by the `{@link ModelSecretService}`: one row per secret, holding the
+ * encrypted payload, `keyId`/`iv`/`salt` encryption metadata, versioning and
+ * enablement fields, and optional tenant/org-unit/owner scoping columns.
  */
 import { BaseModel } from "@decaf-ts/core";
+/**
+ * @description Encryption metadata embedded in a secret row
+ * @summary `keyId` identifies the key used to encrypt the payload; `iv` and
+ * the optional `aad`/`salt` carry the cipher parameters needed to re-derive
+ * the key and decrypt the payload.
+ */
 export interface SecretEncryptionMetadata {
+    /** @description Identifier of the encryption key used for the payload. */
     keyId: string;
+    /** @description Initialization vector used for the payload encryption. */
     iv: string;
+    /** @description Optional additional authenticated data bound to the cipher. */
     aad?: string;
+    /** @description Optional salt used when deriving the key from the master secret. */
+    salt?: string;
 }
+/**
+ * @description Encrypted secret record stored through the model-backed secret service
+ * @summary Persisted in the `secrets` table. The `encryptedPayload` column is
+ * written only by `{@link ModelSecretService}` (which also fills
+ * `encryption`, `version`, and the optional `tenantId`/`orgUnitId`/
+ * `ownerPrincipalId` scoping columns); `enabled: false` marks soft-deleted
+ * secrets that retrieval filters out.
+ * @category Secrets
+ */
 export declare class Secret extends BaseModel {
+    /** @description Primary key (UUID). */
+    id: string;
+    /** @description Normalized secret name. */
     name: string;
+    /** @description Secret provider discriminator that wrote the row. */
     provider: string;
+    /** @description Encrypted, serialized payload. */
     encryptedPayload: string;
+    /** @description Cipher parameters required to decrypt the payload. */
     encryption: SecretEncryptionMetadata;
+    /** @description Optional content type describing the payload. */
     contentType?: string;
+    /** @description Optional free-form tags. */
     tags?: Record<string, string>;
+    /** @description When `false`, the secret is soft-deleted and filtered from retrieval. */
     enabled: boolean;
+    /** @description Optional version label. */
     version?: string;
+    /** @description Optional external identifier linking the secret to a provider record. */
     externalId?: string;
+    /** @description Optional provider URI for externally stored secrets. */
     uri?: string;
+    /** @description Optional tenant scope id. */
+    tenantId?: string;
+    /** @description Optional organizational unit scope id. */
+    orgUnitId?: string;
+    /** @description Optional owning principal id. */
+    ownerPrincipalId?: string;
     constructor(data?: Partial<Secret>);
 }

package/lib/types/shared/environmentValue.d.cts

@@ -11,6 +11,30 @@
  * must use these helpers instead of a raw truthiness check, both to decide whether a
  * field was really configured and to build the config object it returns.
  */
+/**
+ * @description Returns a non-empty string when the value is a usable string
+ * @summary Guards against `LoggedEnvironment` unset-leaf proxies: a value is
+ * accepted only when it is actually a `string` with positive length, so proxy
+ * placeholders and empty strings yield `undefined` instead of leaking into
+ * config objects.
+ * @param {unknown} value - The raw environment value to test.
+ * @returns {string | undefined} The string value, or `undefined` when the value is not a non-empty string.
+ */
 export declare function envString(value: unknown): string | undefined;
+/**
+ * @description Returns a finite number when the value is a usable number
+ * @summary Accepts only real finite numbers, rejecting proxy placeholders,
+ * `NaN`, and `Infinity` so numeric environment leaves produce `undefined`
+ * rather than invalid config values.
+ * @param {unknown} value - The raw environment value to test.
+ * @returns {number | undefined} The numeric value, or `undefined` when the value is not a finite number.
+ */
 export declare function envNumber(value: unknown): number | undefined;
+/**
+ * @description Returns a boolean when the value is actually a boolean
+ * @summary Accepts only `true`/`false`; any other value (including proxy
+ * placeholders and string-encoded flags) yields `undefined`.
+ * @param {unknown} value - The raw environment value to test.
+ * @returns {boolean | undefined} The boolean value, or `undefined` when the value is not a boolean.
+ */
 export declare function envBoolean(value: unknown): boolean | undefined;

package/lib/types/shared/environmentValue.d.mts

@@ -11,6 +11,30 @@
  * must use these helpers instead of a raw truthiness check, both to decide whether a
  * field was really configured and to build the config object it returns.
  */
+/**
+ * @description Returns a non-empty string when the value is a usable string
+ * @summary Guards against `LoggedEnvironment` unset-leaf proxies: a value is
+ * accepted only when it is actually a `string` with positive length, so proxy
+ * placeholders and empty strings yield `undefined` instead of leaking into
+ * config objects.
+ * @param {unknown} value - The raw environment value to test.
+ * @returns {string | undefined} The string value, or `undefined` when the value is not a non-empty string.
+ */
 export declare function envString(value: unknown): string | undefined;
+/**
+ * @description Returns a finite number when the value is a usable number
+ * @summary Accepts only real finite numbers, rejecting proxy placeholders,
+ * `NaN`, and `Infinity` so numeric environment leaves produce `undefined`
+ * rather than invalid config values.
+ * @param {unknown} value - The raw environment value to test.
+ * @returns {number | undefined} The numeric value, or `undefined` when the value is not a finite number.
+ */
 export declare function envNumber(value: unknown): number | undefined;
+/**
+ * @description Returns a boolean when the value is actually a boolean
+ * @summary Accepts only `true`/`false`; any other value (including proxy
+ * placeholders and string-encoded flags) yields `undefined`.
+ * @param {unknown} value - The raw environment value to test.
+ * @returns {boolean | undefined} The boolean value, or `undefined` when the value is not a boolean.
+ */
 export declare function envBoolean(value: unknown): boolean | undefined;