credentials

type AuditSink ¶

type AuditSink interface {
	Emit(ctx context.Context, event string, fields map[string]any)
}

AuditSink is the narrow interface Injector uses to emit credential_issued / credential_revoked / credential_failed events. Kept minimal (map-based fields) so the credentials package doesn't depend on the runtime package (avoiding an import cycle — forge-core/runtime/audit.go already imports agentspec which imports this package).

Runner startup wires a small adapter that implements this against the real *runtime.AuditLogger.

type Credential ¶

type Credential interface {
	// Materialize mints one JIT credential for the given tool call.
	// `args` is the raw JSON the LLM is about to pass to the tool —
	// providers may inspect it to further scope down (e.g. read the
	// S3 key path and constrain the STS session policy). Providers
	// that don't care about args should ignore it.
	Materialize(ctx context.Context, tool string, args json.RawMessage) (Materialization, error)

	// Kind returns the provider name (e.g. "sts_assume_role"). Used
	// on audit events so operators can filter by credential source.
	Kind() string
}

Credential is what a provider hands back from NewCredential — a reusable factory the runner calls once per tool invocation.

Implementations MUST be safe for concurrent Materialize calls when the same skill's tool is invoked from multiple goroutines. Each Materialize call SHOULD produce a distinct credential; providers that support caching (STS creds valid for 15m) MAY reuse a materialization within its TTL but MUST NOT return one past expiration.

type CredentialSpec ¶

type CredentialSpec struct {
	Tool     string          `json:"tool,omitempty" yaml:"tool,omitempty"`
	Binary   string          `json:"binary,omitempty" yaml:"binary,omitempty"`
	Provider string          `json:"provider" yaml:"provider"`
	Spec     json.RawMessage `json:"spec,omitempty" yaml:"spec,omitempty"`
}

CredentialSpec is the declarative shape a skill's config uses to describe one JIT credential.

Tool + Binary route the credential to a specific tool call:

• Tool empty → credential applies to every tool.
• Tool set → credential applies only to that tool.
• Binary set → additionally scoped to cli_execute invocations of that binary (ignored for non-cli_execute tools).

Provider names the plugin (e.g. "sts_assume_role", "static"). Spec is opaque JSON the provider decodes into its own config struct.

func (spec CredentialSpec) MatchesTool(tool, binary string) bool

func (c *CredentialSpec) UnmarshalYAML(node *yaml.Node) error

type Duration ¶

type Duration string

Duration is a JSON-friendly time.Duration wrapper. Values marshal as strings like "15m" / "1h" so config files stay readable and audit events stay grep-friendly. We deliberately do not export a full time.Duration to avoid tying the audit schema to Go's nanosecond string form ("15m0s").

type Handle ¶

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

Handle is the per-invocation grip on a materialized credential. The caller invokes Close() when the tool has finished so the injector can revoke (if applicable) and emit the credential_revoked audit event.

func (h *Handle) Close(ctx context.Context) error

func (h *Handle) Env() map[string]string

func (h *Handle) Headers() map[string]string

func (h *Handle) Kind() string

type Injector ¶

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

Injector materializes JIT credentials at tool-exec time. Tools that need credentials (currently cli_execute) call Materialize(...) and merge the resulting env into their subprocess env; the returned Handle is used to schedule revocation after the tool completes.

Injector is a thin coordinator over a set of Credential instances resolved at startup — the resolution → mint → audit path lives here so individual tools don't each duplicate provider lookup + logging.

func NewInjector(ctx context.Context, reg *Registry, specs []CredentialSpec, audit AuditSink) (*Injector, error)

func (i *Injector) Empty() bool

func (i *Injector) Materialize(ctx context.Context, tool, binary string, args json.RawMessage) (*Handle, error)

type Materialization ¶

type Materialization struct {
	Env     map[string]string
	Headers map[string]string
	TTL     Duration
	Revoke  func(context.Context) error
}

Materialization is what a Credential produces at tool-call time.

Env holds environment variables to inject into a subprocess (for cli_execute) or otherwise pass to the tool. Headers is for HTTP tool calls that sign or authenticate outbound requests. TTL is the operator-facing lifetime of the underlying secret — used for audit and to schedule revocation. Revoke, when non-nil, is called by the runner after the tool completes.

type Provider ¶

type Provider interface {
	// Name returns the plugin name matched against CredentialSpec.Provider.
	Name() string

	// NewCredential decodes spec (the plugin-specific JSON payload)
	// and returns a reusable Credential. Called once per matching
	// CredentialSpec at runner startup.
	NewCredential(ctx context.Context, spec CredentialSpec) (Credential, error)
}

Provider is the plugin that mints Credentials. One provider instance per registered plugin name — the runner looks it up once at startup and reuses it for every skill.

type Registry ¶

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

Registry holds Provider instances by name. A single Registry per runtime; providers register themselves at init time by calling Register() on the package-level default, or a fresh Registry can be constructed for tests.

func NewRegistry() *Registry

func (r *Registry) Get(name string) Provider

func (r *Registry) Names() []string

func (r *Registry) Register(p Provider)

func (r *Registry) ResolveSpec(ctx context.Context, spec CredentialSpec) (Credential, error)