workspaceaccess

package
v0.7.6 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Index

Constants

View Source
const ConsentAuditTimeout = 5 * time.Second

ConsentAuditTimeout bounds facts lookup and writes after an operator answers a prompt.

View Source
const DenialHint = "access could not be authorized for the caller workspace and profile; " +
	"ask the operator to inspect the session identity and workspace access policy"

DenialHint covers failures without a policy decision. Known denials use DenialMessage.

View Source
const Unrestricted = "unrestricted"
View Source
const UserSelector = "@user"

UserSelector is the reserved workspace selector naming the User scope.

Variables

View Source
var ErrInvalidRequest = errors.New("workspace access: invalid request")

ErrInvalidRequest identifies a structurally invalid workspace-access request.

Functions

func AuthoringCeiling

func AuthoringCeiling(ctx context.Context, operator bool) string

func DenialMessage

func DenialMessage(decision Decision) string

DenialMessage explains which axis refused the decision and what would allow it. It never names the target, so the message is identical whether or not a named target exists.

func NarrowGrant

func NarrowGrant(existing, ceiling string) string

func WithOrigin

func WithOrigin(ctx context.Context, origin Origin) context.Context

Types

type AccessRecord

type AccessRecord struct {
	ActorProfileID string
	Target         TargetRef
	Actor          ActorRef
	TargetID       string
	Allowed        bool
	Source         DecisionSource
	Mode           Mode
	Seam           Seam
	Err            string
}

AccessRecord is the audit representation of one authorization decision.

type ActorKind

type ActorKind string

ActorKind identifies the trusted runtime origin of an access request.

const (
	ActorAgentSession ActorKind = "agent_session"
	ActorHuman        ActorKind = "human"
	ActorExtension    ActorKind = "extension"
	ActorAutomation   ActorKind = "automation"
	ActorDaemon       ActorKind = "daemon"
)
const ActorApp ActorKind = "app"

ActorApp marks work created through an app token. App tokens never carry the unrestricted grant (USW Extensibility, Authority Matrix), so app-originated work gets no ceiling.

type ActorRef

type ActorRef struct {
	Kind        ActorKind
	SessionID   string
	WorkspaceID string
	AgentName   string
	Operator    bool
}

ActorRef carries daemon-validated actor identity into the policy.

type AuditEmitter

type AuditEmitter interface {
	EmitWorkspaceAccess(ctx context.Context, record AccessRecord) error
}

AuditEmitter appends one best-effort record per decision.

type Consent string

Consent is a session-lifetime answer captured from an ACP prompt.

const (
	ConsentAllow  Consent = "allow"
	ConsentReject Consent = "reject"
)

type Decision

type Decision struct {
	Allowed        bool
	Source         DecisionSource
	PromptEligible bool
	// Denial names the axis that refused a denied decision; empty when allowed.
	Denial Denial
	// NeedsGrantAfterConsent marks a prompt-eligible write to another profile or through an
	// aggregate: an operator "allow" grants reach, but the write itself still needs the grant.
	NeedsGrantAfterConsent bool
}

Decision is the fail-closed result of one authorization request.

type DecisionSource

type DecisionSource string

DecisionSource records the policy branch that produced a decision.

const (
	SourceAgentGrant     DecisionSource = "agent_grant"
	SourceOperator       DecisionSource = "operator"
	SourceSameWorkspace  DecisionSource = "same_workspace"
	SourcePermissionMode DecisionSource = "permission_mode"
	SourceSessionConsent DecisionSource = "session_consent"
	SourceToolConsent    DecisionSource = "tool_consent"
	SourceDenied         DecisionSource = "denied"
)

type DefaultPolicy

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

DefaultPolicy applies the fixed workspace-access decision chain.

func New

func New(deps Deps) (*DefaultPolicy, error)

New constructs the fail-closed default policy.

func (*DefaultPolicy) Authorize

func (p *DefaultPolicy) Authorize(ctx context.Context, req Request) (Decision, error)

Authorize evaluates and audits one access request.

func (*DefaultPolicy) RecordToolConsent

func (p *DefaultPolicy) RecordToolConsent(ctx context.Context, req Request)

RecordToolConsent audits a successful native read after its separate operator consent gate.

type Denial

type Denial string

Denial names the decision-chain branch that refused an access request.

const (
	// DenialInvalid covers structural, lookup, and unknown-state failures.
	DenialInvalid Denial = "invalid"
	// DenialNotAgentSession covers non-operator actors that are not agent sessions.
	DenialNotAgentSession Denial = "not_agent_session"
	// DenialModeDenyAll is the deny-all permission mode, which never crosses.
	DenialModeDenyAll Denial = "mode_deny_all"
	// DenialConsentRequired is an approve-reads crossing without a recorded operator answer.
	DenialConsentRequired Denial = "consent_required"
	// DenialConsentRejected is an approve-reads crossing the operator rejected for the session.
	DenialConsentRejected Denial = "consent_rejected"
	// DenialNeedsGrant is a write to another profile or through an aggregate without the grant.
	DenialNeedsGrant Denial = "needs_grant"
)

type Deps

type Deps struct {
	Facts   SessionFactsSource
	Consent SessionConsentCache
	Audit   AuditEmitter
	Log     *slog.Logger
}

Deps contains every dependency required by DefaultPolicy.

type Mode

type Mode string

Mode mirrors the effective permission modes without importing config.

const (
	ModeDenyAll      Mode = "deny-all"
	ModeApproveReads Mode = "approve-reads"
	ModeApproveEdits Mode = "approve-edits"
	ModeAuto         Mode = "auto"
	ModeApproveAll   Mode = "approve-all"
)

type Origin

type Origin struct {
	ID      string
	Kind    ActorKind
	Ceiling string
}

func OriginFromContext

func OriginFromContext(ctx context.Context) Origin

func (Origin) Effective

func (o Origin) Effective(definition string) string

type Policy

type Policy interface {
	Authorize(ctx context.Context, req Request) (Decision, error)
}

Policy is the single decision funnel for cross-workspace access.

type Request

type Request struct {
	Actor    ActorRef
	Target   TargetRef
	ReadOnly bool
	Seam     Seam
}

Request is the complete input to one workspace-access decision.

type Seam

type Seam string

Seam identifies the runtime boundary requesting cross-workspace access.

const (
	SeamIdentity Seam = "identity"
	SeamTask     Seam = "task"
	SeamTool     Seam = "tool"
	SeamSpawn    Seam = "spawn"
	SeamCatalog  Seam = "catalog"
)

type SessionConsentCache

type SessionConsentCache interface {
	ConsentFor(ctx context.Context, sessionID string) (Consent, bool)
	PutConsent(ctx context.Context, sessionID string, consent Consent)
}

SessionConsentCache stores one cross-workspace answer per live session.

type SessionFacts

type SessionFacts struct {
	Mode            Mode
	WorkspaceAccess string
	ProfileID       string
	WorkspaceID     string
}

ModeSource resolves the effective permission mode of a live session.

type SessionFactsSource

type SessionFactsSource interface {
	SessionFacts(ctx context.Context, sessionID string) (SessionFacts, error)
}

type TargetKind

type TargetKind string
const (
	TargetWorkspace TargetKind = "workspace"
	TargetUser      TargetKind = "user"
	TargetAggregate TargetKind = "aggregate"
	// TargetUnresolved is a named target, such as a session id, that resolves to no visible
	// owner. The policy treats it as outside the actor's workspace and profile so a denied
	// caller learns nothing about whether the target exists.
	TargetUnresolved TargetKind = "unresolved"
)

type TargetRef

type TargetRef struct {
	Kind        TargetKind
	WorkspaceID string
	ProfileID   string
	AllProfiles bool
	Surface     string
}

func ScopeTarget

func ScopeTarget(workspaceID, profileID string) TargetRef

ScopeTarget translates an internal owner or an explicit User selector into a policy target.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL