@decaf-ts/integrations 0.10.8 → 0.12.0

package/lib/types/secrets/fs/FsSecretService.d.mts

@@ -0,0 +1,207 @@
+import { ContextualArgs, MaybeContextualArg } from "@decaf-ts/core";
+import { ClientBasedSecretService, DeleteSecretOptions, ExistsSecretOptions, ListSecretsOptions, RetrieveSecretOptions, RotateSecretOptions, SecretMetadata, SecretMetadataOptions, SecretName, SecretPayload, SecretProvider, SecretReference, StoreSecretOptions } from "../core/index.d.mts";
+import { FsSecretServiceConfig } from "./FsSecretServiceConfig.d.mts";
+/**
+ * @description Filesystem-backed encrypted secret service
+ * @summary Stores each secret as an isolated JSON envelope file
+ * (`<normalizedName>.json`) inside a private root directory (default
+ * `.decaf/secrets`, mode `0o700`; envelope files are written with mode
+ * `0o600` through a temp-file-then-rename cycle). The master `keySecret` is
+ * required — boot fails with a {@link ValidationError} when neither the
+ * `secrets.fs.keySecret` Environment slice nor an explicit config supplies
+ * it. Listing and per-secret metadata are intentionally unsupported and
+ * throw a `SECRET_UNSUPPORTED_OPERATION` {@link SecretError}, because the
+ * filesystem store is designed as a minimal bootstrap sink (see
+ * {@link InfraCredentialBootstrap}).
+ *
+ * Configuration is resolved from the `secrets.fs` slice or an explicit boot
+ * config.
+ * @class FsSecretService
+ * @category Secrets
+ * @example
+ * ```ts
+ * import { FsSecretService } from "@decaf-ts/integrations/secrets";
+ *
+ * const fsSecrets = await new FsSecretService().boot({
+ *   keySecret: "master-key",
+ * });
+ * await fsSecrets.store("my-secret", { value: "s3cr3t" });
+ * const payload = await fsSecrets.retrieve<{ value: string }>("my-secret");
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   autonumber
+ *   participant Caller
+ *   participant FS as FsSecretService
+ *   participant Disk as rootPath/*.json
+ *   Caller->>FS: store(name, value)
+ *   activate FS
+ *   FS->>FS: normalize + serialize + encrypt
+ *   FS->>Disk: writeEnvelope (temp + rename, 0o600)
+ *   FS-->>Caller: SecretReference
+ *   Caller->>FS: retrieve(nameOrRef)
+ *   FS->>Disk: readEnvelope
+ *   alt missing file
+ *     FS--xCaller: NotFoundError
+ *   else version mismatch
+ *     FS--xCaller: NotFoundError
+ *   else decrypt/parse failure
+ *     FS--xCaller: SecretError
+ *   else success
+ *     FS-->>Caller: SecretPayload
+ *   end
+ *   deactivate FS
+ */
+export declare class FsSecretService extends ClientBasedSecretService<void, FsSecretServiceConfig> {
+    readonly provider: SecretProvider;
+    private cryptoService?;
+    constructor();
+    /**
+     * @description Builds the filesystem secret configuration from the Environment
+     * @summary Reads the `secrets.fs` Environment slice and returns a
+     * {@link FsSecretServiceConfig} when a `keySecret` is configured, applying the
+     * default root path and key id otherwise; returns `undefined` when the slice
+     * carries no `keySecret`, letting boot fall back to explicit arguments.
+     * @returns {FsSecretServiceConfig | undefined} The Environment-derived configuration, or `undefined`.
+     * @override
+     */
+    protected configFromEnvironment(): FsSecretServiceConfig | undefined;
+    /**
+     * @description Creates the private store directory and the crypto service
+     * @summary Resolves the configuration (Environment slice merged with explicit
+     * args), requires a `keySecret`, resolves and creates `rootPath` with mode
+     * `0o700`, and boots a fresh `CryptoService`. Returns the resolved config with
+     * a `void` client (no external connection is needed).
+     * @param {ContextualArgs} args - Optional decaf `Context`/configuration arguments.
+     * @returns {Promise<{config: FsSecretServiceConfig, client: void}>} The resolved configuration and a `void` client.
+     * @throws {ValidationError} When no `keySecret` is available from Environment or arguments.
+     */
+    initialize(...args: ContextualArgs<any>): Promise<{
+        config: FsSecretServiceConfig;
+        client: void;
+    }>;
+    /**
+     * @description Encrypts and writes a secret envelope to the store
+     * @summary Normalizes the name, serializes the payload, derives the
+     * encryption key from the master `keySecret`, encrypts with the configured
+     * key id, and atomically writes the envelope file. Versioning is expressed
+     * through the envelope's `version` field.
+     * @template T - The secret payload type.
+     * @param {SecretName} name - The secret name (normalized before use).
+     * @param {T} value - The payload to encrypt and store.
+     * @param {StoreSecretOptions} [options] - Optional content type, tags, and version.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context`.
+     * @returns {Promise<SecretReference>} A reference pointing at the envelope file.
+     */
+    store<T extends SecretPayload = SecretPayload>(name: SecretName, value: T, options?: StoreSecretOptions, ...args: MaybeContextualArg<any>): Promise<SecretReference>;
+    /**
+     * @description Reads, decrypts, and deserializes a stored secret
+     * @summary Loads the envelope, validates the requested version when one is
+     * supplied (either via options or the reference), re-derives the key using the
+     * envelope salt, and decrypts the payload. Failures surface as
+     * `SECRET_DECRYPTION_FAILED`/`SECRET_DESERIALIZATION_FAILED`
+     * {@link SecretError}s; a missing envelope throws {@link NotFoundError}.
+     * @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`.
+     * @returns {Promise<T>} The decrypted payload.
+     * @throws {NotFoundError} When the secret (or requested version) does not exist.
+     * @throws {SecretError} On decryption or deserialization failures.
+     */
+    retrieve<T extends SecretPayload = SecretPayload>(nameOrRef: SecretName | SecretReference, options?: RetrieveSecretOptions, ...args: MaybeContextualArg<any>): Promise<T>;
+    /**
+     * @description Removes the envelope file for a secret
+     * @summary Deletes `<name>.json` from the root path (`force: true`, so a
+     * missing file is not an error); a filesystem failure surfaces as a
+     * `SECRET_PROVIDER_UNAVAILABLE` {@link SecretError}.
+     * @param {SecretName | SecretReference} nameOrRef - The secret name or reference.
+     * @param {DeleteSecretOptions} [options] - Unused; accepted for interface parity.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context`.
+     * @returns {Promise<void>} Resolves once the file is removed.
+     * @throws {SecretError} When the file cannot be deleted.
+     */
+    delete(nameOrRef: SecretName | SecretReference, options?: DeleteSecretOptions, ...args: MaybeContextualArg<any>): Promise<void>;
+    /**
+     * @description Checks whether a secret exists (optionally at a specific version)
+     * @summary Reads the envelope and compares the requested version, if any,
+     * against the stored one; a {@link NotFoundError} from the read maps to
+     * `false`.
+     * @param {SecretName | SecretReference} nameOrRef - The secret name or reference.
+     * @param {ExistsSecretOptions} [options] - Optional version filter.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context`.
+     * @returns {Promise<boolean>} `true` when the secret exists and matches the version, if given.
+     */
+    exists(nameOrRef: SecretName | SecretReference, options?: ExistsSecretOptions, ...args: MaybeContextualArg<any>): Promise<boolean>;
+    /**
+     * @description Unsupported: the filesystem store does not expose listings
+     * @summary Always throws to keep the filesystem sink minimal; use
+     * {@link InfraCredentialBootstrap} to track seeded references instead.
+     * @param {ListSecretsOptions} [options] - Unused.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context`.
+     * @returns {Promise<SecretMetadata[]>} Never resolves.
+     * @throws {SecretError} Always, with `SECRET_UNSUPPORTED_OPERATION`.
+     */
+    list(options?: ListSecretsOptions, ...args: MaybeContextualArg<any>): Promise<SecretMetadata[]>;
+    /**
+     * @description Unsupported: the filesystem store does not expose metadata
+     * @summary Always throws; metadata is embedded in the envelope, which callers
+     * are not expected to read directly.
+     * @param {SecretName | SecretReference} nameOrRef - Unused.
+     * @param {SecretMetadataOptions} [options] - Unused.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context`.
+     * @returns {Promise<SecretMetadata | undefined>} Never resolves.
+     * @throws {SecretError} Always, with `SECRET_UNSUPPORTED_OPERATION`.
+     */
+    metadata(nameOrRef: SecretName | SecretReference, options?: SecretMetadataOptions, ...args: MaybeContextualArg<any>): Promise<SecretMetadata | undefined>;
+    /**
+     * @description Overwrites a secret with a new payload and version
+     * @summary Re-stores the secret under the same normalized name, tagging the
+     * new envelope with `options.newVersion` (the old envelope file is replaced).
+     * @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` tag.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context`.
+     * @returns {Promise<SecretReference>} A reference to the rewritten envelope.
+     */
+    rotate<T extends SecretPayload = SecretPayload>(nameOrRef: SecretName | SecretReference, value: T, options?: RotateSecretOptions, ...args: MaybeContextualArg<any>): Promise<SecretReference>;
+    /**
+     * @description Lazily resolves the booted `CryptoService`
+     * @summary Throws an {@link InternalError} when accessed before
+     * `initialize()`/`boot()`, which is the only way the crypto service is
+     * created.
+     * @returns {CryptoService} The booted crypto service.
+     * @throws {InternalError} When the service is not initialized.
+     */
+    private get crypto();
+    /**
+     * @description Resolves the envelope file path for a normalized secret name
+     * @param {string} name - The normalized secret name.
+     * @returns {string} The absolute envelope path inside the configured root.
+     */
+    private fileFor;
+    /**
+     * @description Reads and parses an envelope file
+     * @summary A missing file maps to {@link NotFoundError}; filesystem failures
+     * surface as `SECRET_PROVIDER_UNAVAILABLE` and JSON parse failures as
+     * `SECRET_DESERIALIZATION_FAILED` {@link SecretError}s.
+     * @param {string} name - The normalized secret name.
+     * @returns {Promise<FsSecretEnvelope>} The parsed envelope.
+     * @throws {NotFoundError} When the envelope file does not exist.
+     * @throws {SecretError} On read or parse failures.
+     */
+    private readEnvelope;
+    /**
+     * @description Atomically writes an envelope file with private permissions
+     * @summary Writes to a UUID-suffixed temp file with mode `0o600`, then
+     * renames it over the target and re-applies the mode; on failure the temp
+     * file is removed and a `SECRET_PROVIDER_UNAVAILABLE` {@link SecretError} is
+     * thrown.
+     * @param {string} name - The normalized secret name.
+     * @param {FsSecretEnvelope} envelope - The envelope to persist.
+     * @returns {Promise<void>} Resolves once the envelope is durably written.
+     * @throws {SecretError} When the write/rename cycle fails.
+     */
+    private writeEnvelope;
+}

package/lib/types/secrets/fs/FsSecretServiceConfig.d.cts

@@ -0,0 +1,37 @@
+/**
+ * @module integrations/secrets/fs/config
+ * @summary Configuration contract for the filesystem secret service.
+ * @description Defines {@link FsSecretServiceConfig} — the boot configuration
+ * accepted by `{@link FsSecretService}` and its node counterpart — plus the
+ * `DEFAULT_FS_SECRET_ROOT` and `DEFAULT_FS_SECRET_KEY_ID` fallbacks applied
+ * when the `secrets.fs` Environment slice or explicit arguments omit them.
+ */
+import type { SecretServiceConfig } from "../core/index.d.cts";
+/**
+ * @description Default root directory for the filesystem secret store
+ * @summary Relative paths are resolved against the process working directory
+ * during `FsSecretService.initialize`.
+ */
+export declare const DEFAULT_FS_SECRET_ROOT = ".decaf/secrets";
+/**
+ * @description Default encryption key id for filesystem secret envelopes
+ * @summary Recorded in each envelope's `encryption.keyId` when the
+ * configuration does not name a key explicitly.
+ */
+export declare const DEFAULT_FS_SECRET_KEY_ID = "fs-default-key";
+/**
+ * @description Boot configuration for the filesystem secret service
+ * @summary The `keySecret` is mandatory — it is the master secret from which
+ * per-secret encryption keys are derived; `rootPath` and `keyId` fall back to
+ * {@link DEFAULT_FS_SECRET_ROOT} and {@link DEFAULT_FS_SECRET_KEY_ID}.
+ */
+export interface FsSecretServiceConfig extends SecretServiceConfig {
+    /** @description Fixed provider discriminator for the filesystem backend. */
+    provider: "filesystem";
+    /** @description Directory holding the `<name>.json` secret envelopes (created with mode `0o700`). */
+    rootPath: string;
+    /** @description Master secret used to derive per-secret encryption keys. */
+    keySecret: string;
+    /** @description Optional encryption key id recorded in envelopes; defaults to `fs-default-key`. */
+    keyId?: string;
+}

package/lib/types/secrets/fs/FsSecretServiceConfig.d.mts

@@ -0,0 +1,37 @@
+/**
+ * @module integrations/secrets/fs/config
+ * @summary Configuration contract for the filesystem secret service.
+ * @description Defines {@link FsSecretServiceConfig} — the boot configuration
+ * accepted by `{@link FsSecretService}` and its node counterpart — plus the
+ * `DEFAULT_FS_SECRET_ROOT` and `DEFAULT_FS_SECRET_KEY_ID` fallbacks applied
+ * when the `secrets.fs` Environment slice or explicit arguments omit them.
+ */
+import type { SecretServiceConfig } from "../core/index.d.mts";
+/**
+ * @description Default root directory for the filesystem secret store
+ * @summary Relative paths are resolved against the process working directory
+ * during `FsSecretService.initialize`.
+ */
+export declare const DEFAULT_FS_SECRET_ROOT = ".decaf/secrets";
+/**
+ * @description Default encryption key id for filesystem secret envelopes
+ * @summary Recorded in each envelope's `encryption.keyId` when the
+ * configuration does not name a key explicitly.
+ */
+export declare const DEFAULT_FS_SECRET_KEY_ID = "fs-default-key";
+/**
+ * @description Boot configuration for the filesystem secret service
+ * @summary The `keySecret` is mandatory — it is the master secret from which
+ * per-secret encryption keys are derived; `rootPath` and `keyId` fall back to
+ * {@link DEFAULT_FS_SECRET_ROOT} and {@link DEFAULT_FS_SECRET_KEY_ID}.
+ */
+export interface FsSecretServiceConfig extends SecretServiceConfig {
+    /** @description Fixed provider discriminator for the filesystem backend. */
+    provider: "filesystem";
+    /** @description Directory holding the `<name>.json` secret envelopes (created with mode `0o700`). */
+    rootPath: string;
+    /** @description Master secret used to derive per-secret encryption keys. */
+    keySecret: string;
+    /** @description Optional encryption key id recorded in envelopes; defaults to `fs-default-key`. */
+    keyId?: string;
+}

package/lib/types/secrets/fs/index.d.cts

@@ -0,0 +1,9 @@
+/**
+ * @module integrations/secrets/fs
+ * @summary Filesystem secret service exports.
+ * @description Re-exports the filesystem secret service, its node variant,
+ * configuration contract, and Environment slice.
+ */
+export * from "./FsSecretServiceConfig.d.cts";
+export * from "./FsSecretEnvironment.d.cts";
+export * from "./FsSecretService.d.cts";

package/lib/types/secrets/fs/index.d.mts

@@ -0,0 +1,9 @@
+/**
+ * @module integrations/secrets/fs
+ * @summary Filesystem secret service exports.
+ * @description Re-exports the filesystem secret service, its node variant,
+ * configuration contract, and Environment slice.
+ */
+export * from "./FsSecretServiceConfig.d.mts";
+export * from "./FsSecretEnvironment.d.mts";
+export * from "./FsSecretService.d.mts";

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

@@ -5,3 +5,5 @@
  */
 export * from "./core/index.d.cts";
 export * from "./model/index.d.cts";
+export * from "./fs/index.d.cts";
+export * from "./InfraCredentialBootstrap.d.cts";

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

@@ -5,3 +5,5 @@
  */
 export * from "./core/index.d.mts";
 export * from "./model/index.d.mts";
+export * from "./fs/index.d.mts";
+export * from "./InfraCredentialBootstrap.d.mts";

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;
 }