componentized

interface componentized:secrets/latch@0.1.1-dev

since 0.1.1-dev pre-release

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.

Types

use variant store-error-codesince 0.1.1-dev

from componentized:secrets/types@0.1.1-dev

An error getting a secret.

  • not-initialized

    The store is not initialized, call init() first.

  • not-found

    The store has no secret for the key.

  • other: option<string>

    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.

record get-argssince 0.1.1-dev

Arguments to componentized:secrets/store#get.

  • key: string

    The key of the secret to get.

variant store-operationsince 0.1.1-dev

Operations of the componentized:secrets/store interface.

init is not authorized, it gets no secret.

  • get: get-args

    Get a secret, componentized:secrets/store#get.

variant operationsince 0.1.1-dev

Operations of the componentized:secrets package a gate asks a latch to authorize.

variant decisionsince 0.1.1-dev

Whether the operation is allowed to proceed.

  • deferred

    The latch raises no objection, the operation proceeds unless another latch denies it.

  • denied: store-error-code

    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.

type latch-namesince 0.1.1-dev

The name of a latch component, identifying which latch reported an error.

  • string

variant error-codesince 0.1.1-dev

A latch was unable to decide or observe. The gate fails the operation.

  • invalid-config: latch-name

    The latch's configuration is invalid, the cause is logged by the latch.

  • observation-failed: latch-name

    The latch was unable to act on the final decision.

  • other: option<string>

    Any other error.

Functions

functionauthorize: func(operation: operation) -> result<decision, error-code>since 0.1.1-dev

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.

functionobserve-decision: func( final-decision: decision, operation: operation, ) -> result<_, error-code>since 0.1.1-dev

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.

WIT

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