Here is an example module requesting two secrets through the secret contract.

{ config, ... }:
let
  inherit (lib) mkOption;
  inherit (lib.types) submodule;
in
{
  options = {
    myservice = mkOption {
      type = submodule {
        options = {
          adminPassword = contracts.secret.mkRequester {
            owner = "myservice";
            group = "myservice";
            mode = "0440";
            restartUnits = [ "myservice.service" ];
          };
          databasePassword = contracts.secret.mkRequester {
            owner = "myservice";
            # group defaults to "root"
            # mode defaults to "0400"
            restartUnits = [ "myservice.service" "mysql.service" ];
          };
        };
      };
    };
  };

  config = {
    // Do something with the secrets, available at:
    // config.myservice.adminPassword.result.path
    // config.myservice.databasePassword.result.path
  };
};

Now, on the other side, we have a module that uses those options and provides a secret. Let’s assume such a module is available under the secretservice option and that one can create multiple instances.

{ config, ... }:
let
  inherit (lib) mkOption;
  inherit (lib.types) attrsOf submodule;

  contracts = pkgs.callPackage ./contracts {};
in
{
  options.secretservice.secret = mkOption {
    description = "Secret following the secret contract.";
    default = {};
    type = attrsOf (submodule ({ name, options, ... }: {
      options = contracts.secret.mkProvider {
        settings = mkOption {
          description = ''
            Settings specific to the secrets provider.
          '';

          type = submodule {
            options = {
              secretFile = lib.mkOption {
                description = "File containing the encrypted secret.";
                type = lib.types.path;
              };
            };
          };
        };

        resultCfg = {
          path = "/run/secrets/${name}";
          pathText = "/run/secrets/<name>";
        };
      };
    }));
  };

  config = {
    // ...
  };
}

The end user’s responsibility is now to do some plumbing.

They will setup the provider module - here secretservice - with the options set by the requester module, while also setting other necessary options to satisfy the provider service. And then they will give back the result to the requester module myservice.

secretservice.secret."adminPassword" = {
  request = myservice.adminPasswor".request;
  settings.secretFile = ./secret.yaml;
};
myservice.adminPassword.result = secretservice.secret."adminPassword".result;

secretservice.secret."databasePassword" = {
  request = myservice.databasePassword.request;
  settings.secretFile = ./secret.yaml;
};
myservice.databasePassword.result = secretservice.service."databasePassword".result;

Assuming the secretservice module accepts default options, the above snippet could be reduced to:

secretservice.default.secretFile = ./secret.yaml;

secretservice.secret."adminPassword".request = myservice.adminPasswor".request;
myservice.adminPassword.result = secretservice.secret."adminPassword".result;

secretservice.secret."databasePassword".request = myservice.databasePassword.request;
myservice.databasePassword.result = secretservice.service."databasePassword".result;

The plumbing of request from the requester to the provider and then the result from the provider back to the requester is quite explicit in this snippet.