Skip to content
DocumentationGrant authority and deliver secrets
On this page

Page resources

Open Markdownllms.txtView source

Last updated

Grant authority and deliver secrets

This recipe authorizes one shipment effect and delivers an external credential without putting its value into source, a lock, plan, artifact, or log.

The .one, Rust, and command examples below are illustrative end-product syntax.

1. Declare requirements, not grants

semantic parcelhub.shipping
    domain one.contracts@1
    operation CreateShipment@1
        input ShipmentRequest
        output Shipment
        effect external_create(shipment)
        authority shipment:create
        secret carrier_api_key purpose outbound_authentication

The declaration states what execution requires. It neither identifies the secret value nor authorizes a caller.

2. Bind a protected value locally

$ one setup
requirement carrier_api_key needs a protected local binding
store workstation
binding secret-binding:sha256:42d1…
value protected
scope machine-local

Source and plans retain only the typed requirement and binding reference.

3. Request exact approval

{
  "operation": "parcelhub.shipping#CreateShipment@1",
  "subject": "shipment/request-993",
  "principal": "parcelhub.user#operator-17",
  "effect": "external_create(shipment)",
  "provider": "acme_carrier.provider#AcmeShipmentCreate@1",
  "expires_in": "5m"
}

Changing the subject, effect, provider, arguments, or expiry requires a new authorization decision.

4. Receive an attenuated capability

pub async fn create(ctx: CreateShipment, request: ShipmentRequest) -> Result<Shipment> {
    let carrier = ctx.carrier();
    carrier.create(request).await
}

The runtime delivers the secret only to the selected boundary, redacts it from diagnostics, and enforces the grant independently from UI visibility or client claims.

5. Observe revocation

$ one inspect grant:sha256:91c2…
state revoked
epoch authority:epoch:204
affected binding provider-binding:sha256:cc13…
next action reauthorize exact operation

See authority and trust.