componentized

package componentized:secrets@0.1.1-dev

pre-release

A collection of utility components for sensitive values.

Secrets for components, sensitive values looked up by key.

Interfaces

  • types since 0.1.1-dev
  • latch since 0.1.1-dev — Access control for componentized:secrets.
  • store since 0.1.0 — A store of secrets, sensitive values looked up by key, e.g. passwords, tokens and keys.

Worlds

  • provider since 0.1.0 — A component that provides secrets, e.g. from a vault or another source of secrets.
  • imports since 0.1.0 — The interfaces to import to use secrets.

WIT

/// Secrets for components, sensitive values looked up by key.
package componentized:secrets@0.1.1-dev;

@since(version = 0.1.1-dev)
interface types {
  /// The value of a secret.
  @since(version = 0.1.1-dev)
  variant secret {
    /// A secret that is text.
    %string(string),
    /// A secret that is binary.
    ///
    /// Encoded text is discouraged, favor a string.
    bytes(list<u8>),
  }

  /// An error getting a secret.
  @since(version = 0.1.1-dev)
  variant error-code {
    /// The store is not initialized, call `init()` first.
    not-initialized,
    /// The store has no secret for the key.
    not-found,
    /// Any other error, e.g. the store is unavailable or access to the secret is denied, with
    /// a message describing the error, when there is one.
    other(option<string>),
  }
}

/// Access control for componentized:secrets.
///
/// A gate consults a latch before each operation on the store. The latch either defers, raising
/// no objection, or denies the operation. A latch never grants an operation, an operation
/// proceeds when the latch defers. Several latches can be aggregated into one, the operation is
/// denied when any of them denies it.
///
/// Deciding and acting on a decision are separate steps. `authorize` decides without side
/// effects, then the gate reports the final decision to `observe-decision`, where a latch updates
/// any state it keeps. A latch aggregated with others may not be asked to authorize an operation
/// another latch already denied, but it always observes the final decision.
@since(version = 0.1.1-dev)
interface latch {
  @since(version = 0.1.1-dev)
  use types.{error-code as store-error-code};

  /// Arguments to componentized:secrets/store#get.
  @since(version = 0.1.1-dev)
  record get-args {
    /// The key of the secret to get.
    key: string,
  }

  /// Operations of the componentized:secrets/store interface.
  ///
  /// `init` is not authorized, it gets no secret.
  @since(version = 0.1.1-dev)
  variant store-operation {
    /// Get a secret, componentized:secrets/store#get.
    get(get-args),
  }

  /// Operations of the componentized:secrets package a gate asks a latch to authorize.
  @since(version = 0.1.1-dev)
  variant operation {
    /// An operation on componentized:secrets/store.
    store(store-operation),
  }

  /// Whether the operation is allowed to proceed.
  @since(version = 0.1.1-dev)
  variant decision {
    /// The latch raises no objection, the operation proceeds unless another latch denies it.
    deferred,
    /// The operation must not proceed. The gate fails it with the error code, without
    /// calling the store, e.g. `not-found` to hide that the secret exists.
    denied(store-error-code),
  }

  /// The name of a latch component, identifying which latch reported an error.
  @since(version = 0.1.1-dev)
  type latch-name = string;

  /// A latch was unable to decide or observe. The gate fails the operation.
  @since(version = 0.1.1-dev)
  variant error-code {
    /// The latch's configuration is invalid, the cause is logged by the latch.
    invalid-config(latch-name),
    /// The latch was unable to act on the final decision.
    observation-failed(latch-name),
    /// Any other error.
    other(option<string>),
  }

  /// Decide whether the operation may proceed.
  ///
  /// Must not have side effects. When latches are aggregated, a latch is not asked about an
  /// operation another latch already denied, so state changed here could disagree with what
  /// actually happened. Act on decisions in `observe-decision` instead.
  @since(version = 0.1.1-dev)
  authorize: func(operation: operation) -> result<decision, error-code>;

  /// Observe the final decision for an operation, after `authorize` returned a decision.
  ///
  /// Called for both deferred and denied operations, including operations this latch was not
  /// asked to authorize because an aggregated latch denied them first. The final decision is
  /// what the gate enforces, so this is where a latch updates any state it keeps. Not called
  /// when `authorize` returned an error.
  ///
  /// An error fails the operation, since the latch could not act on the decision.
  @since(version = 0.1.1-dev)
  observe-decision: func(final-decision: decision, operation: operation) -> result<_, error-code>;
}

/// A store of secrets, sensitive values looked up by key, e.g. passwords, tokens and keys.
@since(version = 0.1.0)
interface store {
  @since(version = 0.1.0)
  use types.{secret, error-code};

  /// Initialize the store.
  ///
  /// The store must be initialized before use. Secrets are immutable after
  /// initialization completes. Subsequent calls to initialize are no-ops.
  @since(version = 0.1.0)
  init: async func() -> result<_, error-code>;

  /// Gets the secret for the key.
  ///
  /// Returns `error-code::not-found` when the store has no secret for the
  /// key. Returns `error-code::not-initialized` when the store is not
  /// initialized, call `init()` first.
  @since(version = 0.1.0)
  get: func(key: string) -> result<secret, error-code>;
}

/// A component that provides secrets, e.g. from a vault or another source of secrets.
@since(version = 0.1.0)
world provider {
  @since(version = 0.1.0)
  import types;

  @since(version = 0.1.0)
  export store;
}
/// The interfaces to import to use secrets.
@since(version = 0.1.0)
world imports {
  @since(version = 0.1.1-dev)
  import types;
  @since(version = 0.1.0)
  import store;
  @since(version = 0.1.1-dev)
  import latch;
}