@decaf-ts/integrations 0.10.8 → 0.12.0

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

@@ -0,0 +1,97 @@
+import { Model } from "@decaf-ts/decorator-validation";
+import { Constructor } from "@decaf-ts/decoration";
+import { AdapterFlags, Context } from "@decaf-ts/core";
+/**
+ * @description TLS settings accepted by {@link RedisAdapter}
+ * @summary `true` enables TLS with Node's default verification (server
+ * certificate checked). An object enables TLS and forwards the standard Node
+ * `tls.connect` options (`rejectUnauthorized`, `ca`, `cert`, `key`,
+ * `servername`); set `rejectUnauthorized: false` only for a known development
+ * server with a self-signed certificate.
+ * @typedef {boolean | object} RedisTlsConfig
+ * @memberOf module:redis
+ */
+export type RedisTlsConfig = boolean | {
+    rejectUnauthorized?: boolean;
+    ca?: string | Buffer;
+    cert?: string | Buffer;
+    key?: string | Buffer;
+    servername?: string;
+    [key: string]: unknown;
+};
+/**
+ * @description Connection configuration accepted by {@link RedisAdapter}
+ * @summary Supports both a full connection URL and the individual host/port/
+ * credential fields. When `url` is provided it takes precedence over the
+ * discrete fields. Set `tls` (or use a `rediss://` URL) to encrypt the
+ * connection.
+ *
+ * Note on `KEYS`: Redis `KEYS` walks the whole keyspace and blocks the server
+ * while it runs. Prefer `SCAN`/`scanIterator` (or a maintained index) in
+ * production; the adapter's key listing is intended for small namespaces.
+ * @typedef {object} RedisConfig
+ * @property {string} [url] Full redis:// (or rediss://) connection string
+ * @property {string} [host] Server host (defaults to localhost)
+ * @property {number} [port] Server port (defaults to 6379)
+ * @property {string} [username] ACL username
+ * @property {string} [password] ACL password
+ * @property {number} [database] Logical database index
+ * @property {string} [prefix] Key namespace (defaults to decaf:redis)
+ * @property {string} [user] Identity reported on created/updated records
+ * @property {RedisTlsConfig} [tls] Enable TLS and optionally supply verification options
+ * @memberOf module:redis
+ */
+export type RedisConfig = {
+    url?: string;
+    host?: string;
+    port?: number;
+    username?: string;
+    password?: string;
+    database?: number;
+    prefix?: string;
+    user?: string;
+    tls?: RedisTlsConfig;
+};
+/**
+ * @description Adapter flags enriched with the acting user identity
+ * @summary Extends the base adapter flags with the `UUID` field used by the
+ * `createdBy`/`updatedBy` decorators.
+ * @interface RedisFlags
+ * @extends AdapterFlags
+ * @property {string} UUID Identity of the user performing the operation
+ * @memberOf module:redis
+ */
+export interface RedisFlags extends AdapterFlags {
+    UUID: string;
+}
+/**
+ * @description Contextual type used by the Redis adapter
+ * @typedef {Context<RedisFlags>} RedisContext
+ * @memberOf module:redis
+ */
+export type RedisContext = Context<RedisFlags>;
+/**
+ * @description Raw query descriptor applied in memory by the Redis adapter
+ * @summary Mirrors the in-memory query shape of the core RAM adapter. The Redis
+ * adapter loads the matching table, reverts records to models and evaluates the
+ * predicate/sort/aggregation functions in JavaScript.
+ * @typedef {object} RawRedisQuery
+ * @template M
+ * @memberOf module:redis
+ */
+export type RawRedisQuery<M extends Model = any> = {
+    select: undefined | (keyof M)[];
+    from: Constructor<M>;
+    where: (el: M) => boolean;
+    sort?: (el: M, el2: M) => number;
+    groupBy?: (keyof M)[];
+    limit?: number;
+    skip?: number;
+    count?: keyof M | null;
+    countDistinct?: keyof M;
+    min?: keyof M;
+    max?: keyof M;
+    sum?: keyof M;
+    avg?: keyof M;
+    distinct?: keyof M;
+};

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

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

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

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

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

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

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