invocation

package
v0.0.0-...-8bebe15 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 14, 2026 License: Apache-2.0, MIT Imports: 20 Imported by: 0

Documentation

Index

Constants

View Source 
const Validity = 30 * time.Second

Validity is the time an invocation is valid for by default.

Variables

This section is empty.

Functions

func Encode 

func Encode(inv ucan.Invocation) ([]byte, error)

Encode invocation to CBOR.

func VerifySignature 

func VerifySignature(inv ucan.Invocation, verifier ucan.Verifier) (bool, error)

VerifySignature verifies the invocation's signature against the literal signed-payload bytes preserved on decode. No reconstruction of the signing payload from typed fields — verification operates on the exact bytes the issuer signed, per the UCAN spec.

Types

type Invocation 

type Invocation struct {
	// contains filtered or unexported fields
}

UCAN Invocation defines a format for expressing the intention to execute delegated UCAN capabilities, and the attested receipts from an execution.

https://github.com/ucan-wg/invocation/blob/main/README.md

func Decode 

func Decode(b []byte) (*Invocation, error)

Decode invocation from CBOR.

func Invoke 

func Invoke(
	issuer ucan.Signer,
	subject did.DID,
	command ucan.Command,
	args cbg.CBORMarshaler,
	options ...Option,
) (*Invocation, error)

Invoke constructs a signed invocation. The args parameter is any cborgen-marshalable value whose schema matches what the command's executor expects, and which encodes as a CBOR map (per the UCAN spec). Pass nil to encode an empty CBOR map.

func InvokeMap 

func InvokeMap(
	issuer ucan.Signer,
	subject did.DID,
	command ucan.Command,
	args map[string]any,
	options ...Option,
) (*Invocation, error)

InvokeMap is a convenience wrapper around Invoke that accepts an ad-hoc args map. Equivalent to calling Invoke with datamodel.Map(args). Use Invoke directly when the args have a typed cborgen schema; use InvokeMap when you just want to pass a Go map literal.

func (*Invocation) ArgumentsBytes 

func (inv *Invocation) ArgumentsBytes() []byte

ArgumentsBytes returns the raw CBOR bytes of the args field. Decode directly into the typed cborgen struct that corresponds to the invocation's command: 

var args MyArgs
err := args.UnmarshalCBOR(bytes.NewReader(inv.ArgumentsBytes()))

https://github.com/ucan-wg/invocation/blob/main/README.md#arguments

func (*Invocation) Audience 

func (inv *Invocation) Audience() did.DID

The DID of the intended Executor if different from the Subject. Returns did.Undef when no audience is set; check with Defined().

https://github.com/ucan-wg/spec/blob/main/README.md#issuer--audience

func (*Invocation) Bytes 

func (inv *Invocation) Bytes() []byte

Bytes returns the dag-cbor encoded bytes of this invocation.

func (*Invocation) Cause 

func (inv *Invocation) Cause() *cid.Cid

A provenance claim describing which receipt requested it.

https://github.com/ucan-wg/invocation/blob/main/README.md#cause

func (*Invocation) Command 

func (inv *Invocation) Command() ucan.Command

The command to invoke.

https://github.com/ucan-wg/spec/blob/main/README.md#command

func (*Invocation) Envelope 

func (inv *Invocation) Envelope() *edm.EnvelopeModel

Envelope returns the raw envelope (signature + signed-payload bytes).

func (*Invocation) Expiration 

func (inv *Invocation) Expiration() *ucan.UnixTimestamp

The timestamp at which the invocation becomes invalid.

https://github.com/ucan-wg/invocation/blob/main/README.md#expiration

func (*Invocation) IssuedAt 

func (inv *Invocation) IssuedAt() *ucan.UnixTimestamp

An issuance timestamp.

https://github.com/ucan-wg/invocation/blob/main/README.md#issued-at

func (*Invocation) Issuer 

func (inv *Invocation) Issuer() did.DID

Issuer DID (sender).

https://github.com/ucan-wg/spec/blob/main/README.md#issuer--audience 

func (inv *Invocation) Link() cid.Cid

Link returns the IPLD link that corresponds to the encoded bytes of this invocation.

func (*Invocation) MarshalCBOR 

func (inv *Invocation) MarshalCBOR(w io.Writer) error

func (*Invocation) MarshalDagJSON 

func (inv *Invocation) MarshalDagJSON(w io.Writer) error

func (*Invocation) MetadataBytes 

func (inv *Invocation) MetadataBytes() []byte

MetadataBytes returns the raw CBOR bytes of the meta field, or nil if metadata is not set.

https://github.com/ucan-wg/invocation/blob/main/README.md#metadata

func (*Invocation) Nonce 

func (inv *Invocation) Nonce() []byte

A unique, random nonce. It ensures that multiple (non-idempotent) invocations are unique. The nonce SHOULD be empty (0x) for Commands that are idempotent (such as deterministic Wasm modules or standards-abiding HTTP PUT requests).

https://github.com/ucan-wg/invocation/blob/main/README.md#nonce

func (*Invocation) Proofs 

func (inv *Invocation) Proofs() []cid.Cid

The path of authority from the subject to the invoker.

https://github.com/ucan-wg/invocation/blob/main/README.md#proofs

func (*Invocation) SigPayload 

func (inv *Invocation) SigPayload() *idm.SigPayloadModel

SigPayload returns the decoded signature payload (varsig header + token payload).

func (*Invocation) Signature 

func (inv *Invocation) Signature() ucan.Signature

The signature over the payload.

https://github.com/ucan-wg/spec/blob/main/README.md#envelope

func (*Invocation) SignedBytes 

func (inv *Invocation) SignedBytes() []byte

SignedBytes returns the raw CBOR bytes of the SigPayload — i.e. the bytes the issuer signed over. Verification operates on these bytes directly.

func (*Invocation) Subject 

func (inv *Invocation) Subject() did.DID

The Subject being invoked.

https://github.com/ucan-wg/spec/blob/main/README.md#subject

func (*Invocation) Task 

func (inv *Invocation) Task() ucan.Task

Task returns the CID of the fields that comprise the task for the invocation.

https://github.com/ucan-wg/invocation/blob/main/README.md#task

func (*Invocation) UnmarshalCBOR 

func (inv *Invocation) UnmarshalCBOR(r io.Reader) error

func (*Invocation) UnmarshalDagJSON 

func (inv *Invocation) UnmarshalDagJSON(r io.Reader) error

type Option 

type Option func(cfg *invocationConfig)

Option is an option configuring a UCAN invocation.

func WithAudience 

func WithAudience(aud did.DID) Option

WithAudience configures the DID of the intended Executor if different from the Subject.

func WithCause 

func WithCause(cause cid.Cid) Option

WithCause configures the CID of the receipt that enqueued the task.

func WithExpiration 

func WithExpiration(exp ucan.UnixTimestamp) Option

WithExpiration configures the expiration time in seconds since Unix epoch.

func WithIssuedAt 

func WithIssuedAt(iat ucan.UnixTimestamp) Option

WithIssuedAt sets the time at which the invocation was issued at in seconds since Unix epoch.

func WithMetadata 

func WithMetadata(meta ipld.Map) Option

WithMetadata configures the arbitrary metadata for the UCAN.

func WithNoExpiration 

func WithNoExpiration() Option

WithNoExpiration configures the UCAN to never expire.

WARNING: this will cause the delegation to be valid FOREVER, unless revoked.

func WithNoNonce 

func WithNoNonce() Option

WithNoNonce configures an empty nonce value for the UCAN.

func WithNonce 

func WithNonce(nnc []byte) Option

WithNonce configures the nonce value for the UCAN.

func WithProofs 

func WithProofs(prf ...cid.Cid) Option

WithProof configures the proof(s) for the UCAN. If the `issuer` of this `Invocation` is not the resource owner / service provider, for the delegated capabilities, the `proofs` must contain valid `Proof`s containing delegations to the `issuer`.

type Task 

type Task struct {
	// contains filtered or unexported fields
}

func NewTask 

func NewTask(
	subject did.DID,
	command ucan.Command,
	argsBytes []byte,
	nonce []byte,
) (*Task, error)

NewTask constructs a task from its component fields. argsBytes must be the raw CBOR encoding of the args (typically obtained from Invocation.ArgumentsBytes or by marshaling a typed cborgen struct directly).

func (*Task) ArgumentsBytes 

func (t *Task) ArgumentsBytes() []byte

ArgumentsBytes returns the raw CBOR bytes of the args field.

func (*Task) Bytes 

func (t *Task) Bytes() []byte

func (*Task) Command 

func (t *Task) Command() ucan.Command
func (t *Task) Link() cid.Cid

func (*Task) Nonce 

func (t *Task) Nonce() []byte

func (*Task) Subject 

func (t *Task) Subject() did.DID

Source Files

View all Source files

Directories

Path Synopsis
gen command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.