@decaf-ts/integrations 0.11.0 → 0.12.0

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

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

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

@@ -0,0 +1,42 @@
+/**
+ * @module integrations/secrets/fs/environment
+ * @summary Environment configuration slice for the filesystem secret service.
+ * @description Accumulates the `secrets.fs` slice into the shared
+ * `SecretEnvironment` so `{@link FsSecretService}` can resolve its
+ * `rootPath`, `keySecret`, and `keyId` from the process Environment without
+ * explicit boot arguments. A missing `keySecret` disables the
+ * Environment-derived configuration path.
+ */
+/**
+ * @description Environment-backed configuration for the filesystem secret service
+ * @summary Mirrors {@link FsSecretServiceConfig} with every field optional:
+ * `rootPath` and `keyId` fall back to their defaults, while an empty
+ * `keySecret` means the slice is not configured.
+ */
+export interface FsSecretEnvironmentConfig {
+    /** @description Directory holding the secret envelopes; defaults to `.decaf/secrets`. */
+    rootPath?: string;
+    /** @description Master secret used to derive per-secret encryption keys. */
+    keySecret?: string;
+    /** @description Encryption key id recorded in envelopes; defaults to `fs-default-key`. */
+    keyId?: string;
+}
+/**
+ * @description Shape of the accumulated Environment containing the `secrets.fs` slice
+ * @summary Used to type the `SecretEnvironment.accumulate` call below so the
+ * `secrets.fs` accessor is fully typed.
+ */
+export interface FsSecretEnvironmentShape {
+    secrets: {
+        fs: FsSecretEnvironmentConfig;
+    };
+}
+/**
+ * @description The accumulated Environment exposing the `secrets.fs` slice
+ * @summary Access it as `FsSecretEnvironment.secrets.fs.{rootPath,keySecret,keyId}`.
+ */
+export declare const FsSecretEnvironment: import("@decaf-ts/logging").AccumulatedEnvironment<{
+    app: string | undefined;
+} & import("@decaf-ts/logging").LoggingConfig<object> & {
+    env: any;
+} & import("..").SecretCommonEnvironmentShape & FsSecretEnvironmentShape>;

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

@@ -0,0 +1,42 @@
+/**
+ * @module integrations/secrets/fs/environment
+ * @summary Environment configuration slice for the filesystem secret service.
+ * @description Accumulates the `secrets.fs` slice into the shared
+ * `SecretEnvironment` so `{@link FsSecretService}` can resolve its
+ * `rootPath`, `keySecret`, and `keyId` from the process Environment without
+ * explicit boot arguments. A missing `keySecret` disables the
+ * Environment-derived configuration path.
+ */
+/**
+ * @description Environment-backed configuration for the filesystem secret service
+ * @summary Mirrors {@link FsSecretServiceConfig} with every field optional:
+ * `rootPath` and `keyId` fall back to their defaults, while an empty
+ * `keySecret` means the slice is not configured.
+ */
+export interface FsSecretEnvironmentConfig {
+    /** @description Directory holding the secret envelopes; defaults to `.decaf/secrets`. */
+    rootPath?: string;
+    /** @description Master secret used to derive per-secret encryption keys. */
+    keySecret?: string;
+    /** @description Encryption key id recorded in envelopes; defaults to `fs-default-key`. */
+    keyId?: string;
+}
+/**
+ * @description Shape of the accumulated Environment containing the `secrets.fs` slice
+ * @summary Used to type the `SecretEnvironment.accumulate` call below so the
+ * `secrets.fs` accessor is fully typed.
+ */
+export interface FsSecretEnvironmentShape {
+    secrets: {
+        fs: FsSecretEnvironmentConfig;
+    };
+}
+/**
+ * @description The accumulated Environment exposing the `secrets.fs` slice
+ * @summary Access it as `FsSecretEnvironment.secrets.fs.{rootPath,keySecret,keyId}`.
+ */
+export declare const FsSecretEnvironment: import("@decaf-ts/logging").AccumulatedEnvironment<{
+    app: string | undefined;
+} & import("@decaf-ts/logging").LoggingConfig<object> & {
+    env: any;
+} & import("..").SecretCommonEnvironmentShape & FsSecretEnvironmentShape>;

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

@@ -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.cts";
+import { FsSecretServiceConfig } from "./FsSecretServiceConfig.d.cts";
+/**
+ * @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/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";