Module permissions 

Typed permission-card management over the golem:permissions WIT interfaces.

A PermissionCard is an unforgeable capability held by the host. Guest code can only obtain one from the host (wallet, derive_from_wallet, PermissionCard::derive, PolymorphicPermissionCard::derive) or receive one as an agent method argument. A PolymorphicPermissionCard is a template card whose grants may contain slot variables; the agent’s initial card is one. A ScopeCard (derive_scope) lives only in memory for the current invocation and can only be lent to awaited agent calls. This module offers no conversion between the three card types, and nothing in it turns a CardId, a grant list or any other data into a card. A card value that goes through the schema-value codec takes the type that the decoder declares; the host keeps the real kind of the card.

Every operation is checked by the host against the caller’s own cards: deriving requires card:derive, inspecting requires card:inspect, revoking requires card:revoke and installing requires card:install. An expected refusal is returned as a PermissionError.

Typical usage

use golem_rust::permissions::{self, Bounds, Lifespan, PatternGrant};

let grant = PatternGrant::new("card", "*", "*", "inspect", "*");
let card = permissions::derive_from_wallet(
    &Bounds {
        lower_positive: vec![grant.clone()],
        ..Bounds::default()
    },
    None,
)?;
let child = card.derive(
    &Bounds {
        lower_positive: vec![grant],
        ..Bounds::default()
    },
    Some(&Lifespan::iso8601("PT1H")?),
)?;
let revoked = card.revoke()?; // revokes `card` and `child`

Structs

Bounds

The requested grant lists of a derivation.

CardId

An opaque card identifier.

CardView

The four grant lists of a card, as returned by PermissionCard::inspect.

KernelModule

A resource class of the permission kernel, as returned by list_modules.

Lifespan

The lifespan of a derived card, as an ISO-8601 duration of the form PnDTnHnMnS, for example "P1DT2H" or "PT30.5S".

LifespanError

A lifespan that cannot be represented.

PatternGrant

A grant pattern: class(owner) @ recipient : verb : resource-id.

PermissionCard

A permission card held by the calling component.

PolymorphicPermissionCard

A template permission card held by the calling component.

ScopeCard

An invocation-local card derived with derive_scope.

Timestamp

A point in time, in seconds and nanoseconds since the Unix epoch.

WalletVersionToken

A wallet version token, as returned by wallet_version.

Enums

Holder

The holder of a wallet: the target of PermissionCard::install.

PermissionError

An expected refusal of a permission operation by the host.

PersistentCard

An owned persistent card, labelled with the kind returned by the host.

ScopeParent

A parent of derive_scope: a persistent card, a template card or a scope card.

WalletCard

A card in the caller’s wallet, labelled with its kind.

Functions

derive_from_wallet

Derives a card from the caller’s wallet. Requires card:derive.

derive_scope

Derives a scope card from one or more parents. Requires card:derive.

list_modules

Lists the resource classes that the permission kernel knows, with their verbs.

validate_grant

Checks that grant names a known class and verb and uses valid patterns.

wallet

Returns every card in the caller’s wallet, labelled with its kind.

wallet_version

Returns the version token of the caller’s wallet. The token changes whenever a card is installed into or removed from the wallet.