auth

type Action ¶

type Action int

Action enumerates the authorization decisions the multi-session attach layer makes. The matrix is intentionally small in α.1; finer scoping (per-tool, per-MCP-server, per-session-sub-area) is deferred per docs/multi-session-design.md §"Out of scope".

Handlers don't enforce these in α.1 — enforcement wiring is α.2. The function is here so the type surface is settled before the handlers wrap on top.

const (
	// ActionSessionList is the GET /sessions endpoint. Always
	// permitted; the handler filters results to sessions the Caller
	// can actually read.
	ActionSessionList Action = iota
	// ActionSessionRead covers reading session state — events
	// stream, status, tools, memory, permissions, etc.
	ActionSessionRead
	// ActionSessionWrite covers mutating endpoints — inject,
	// wake, interrupt, slash commands.
	ActionSessionWrite
	// ActionSessionAdmin covers ACL / metadata mutations on the
	// session — modifying SessionACL, deleting the session.
	ActionSessionAdmin
	// ActionDaemonAdmin covers daemon-scoped read/write — peer
	// registry, global metrics, anything not bound to a single
	// session. Admin-only.
	ActionDaemonAdmin
)

func (a Action) String() string

type AnonymousAuth ¶

type AnonymousAuth struct {
	Caller Caller
}

AnonymousAuth resolves every request to the same Caller. It is the default Authenticator wired into pkg/attach when multi-session is disabled — every request is "anon" (or whatever default identity the operator configured) and downstream code sees a Caller-on-context just like in multi-session deployments.

Zero value resolves to the package-level Anonymous Caller. Set Caller explicitly to override the identity (the operator-facing knob is attach.multi_session.default_identity).

func (a AnonymousAuth) Authenticate(_ *http.Request) (Caller, error)

type Authenticator ¶

type Authenticator interface {
	Authenticate(r *http.Request) (Caller, error)
}

Authenticator extracts a Caller from an inbound HTTP request, or returns ErrUnauthenticated when no valid credential is present.

Implementations shipped in α.1:

• AnonymousAuth — single fixed Caller; the default for single-user deployments and any deployment with multi-session disabled.
• BearerTokenAuth — token → Caller lookup against a static table loaded from users.json (see LoadUsersFile).

Future implementations (designed but not in α.1): OIDC/JWT, mTLS (subject DN → Caller), K8s ServiceAccount (TokenReview).

type AuthenticatorWithProxy ¶

type AuthenticatorWithProxy interface {
	Authenticator
	CanProxyAs(c Caller) bool
}

AuthenticatorWithProxy is the optional extension implemented by authenticators that support the proxy pattern (a Caller authorized to assert other Callers via the X-Asserted-Caller header).

The bot integration use case: a Slack/GChat bot authenticates as itself, then asserts the human user's identity per request so audit logs and per-caller MCP credentials attribute to the human, not the bot. CanProxyAs reports whether the resolved Caller is on the configured proxy allowlist.

Authenticators that don't implement this interface implicitly deny all proxy assertions.

type BearerTokenAuth ¶

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

BearerTokenAuth validates the request's bearer token against a static table loaded from users.json. Returns the matched Caller, or ErrUnauthenticated when no token is presented or the token is unknown.

Token comparison is constant-time (subtle.ConstantTimeCompare) to avoid leaking match prefixes through response timing. The table is indexed by token for O(1) lookup; identities are not exposed by the lookup path.

Accepted headers, in order:

1. X-Attach-Token (matches the existing daemon-level side-channel header used when an identity gateway owns Authorization)
2. Authorization: Bearer <token>

Proxy semantics: a Caller resolved here is permitted to assert other identities via X-Asserted-Caller only if it appears in the ProxyIdentities allowlist. See CanProxyAs.

func NewBearerTokenAuth(users []User, adminIdentities, proxyIdentities []string) *BearerTokenAuth

func (b *BearerTokenAuth) Authenticate(r *http.Request) (Caller, error)

func (b *BearerTokenAuth) CanProxyAs(c Caller) bool

func (b *BearerTokenAuth) HasIdentity(identity string) bool

func (b *BearerTokenAuth) LookupIdentity(identity string) (Caller, bool)

type Caller ¶

type Caller struct {
	Identity string
	Labels   map[string]string
	Admin    bool
}

Caller is the opaque identity attached to every authenticated request entering the daemon. Subsequent code uses it for authorization (see Authorize) and audit (see eventlog metadata, layered in α.2).

Identity is a stable opaque ID — typically an email ("alice@example.com"), a service-account marker ("sa:platform-agent"), or "anon" for unauthenticated requests when anonymous access is allowed.

Labels carry free-form metadata from the auth source (e.g., {"team": "platform", "issuer": "https://oidc.example.com"}). Available to authorization logic and audit consumers; not part of the Identity equality check.

Admin grants the see-everything role; set per configuration (attach.multi_session.admin_identities). Admin Callers pass every Authorize check.

func CallerFromContext(ctx context.Context) (c Caller, ok bool)

type SessionACL ¶

type SessionACL struct {
	Owner        string
	Viewers      []string
	Contributors []string
}

SessionACL captures who can do what to a session. Owner is the creator (full access). Viewers can read; Contributors can read + write but not modify the ACL itself.

Owner may be a synthetic identity like "channel:#incident-response" for shared-session deployments where the session belongs to a group rather than a single user.

Zero value (empty Owner, nil slices) grants nothing to any non-Admin Caller — this is the safe default when a session was created before multi-session was enabled (legacy sessions become admin-only-accessible until the operator assigns an Owner).

type User ¶

type User struct {
	Identity string            `json:"identity"`
	Token    string            `json:"token"`
	Labels   map[string]string `json:"labels,omitempty"`
}

User is one row in users.json. Identity is the stable opaque ID the daemon stamps onto audit log entries; Token is the bearer credential clients present. Labels are free-form metadata available to downstream authorization / observability.

Identity and Token are both required; rows missing either are rejected at load time (silently skipping them would hide misconfiguration from the operator).

type UsersFile ¶

type UsersFile struct {
	Version int    `json:"version"`
	Users   []User `json:"users"`
}

UsersFile is the on-disk shape of attach.multi_session.auth.table_file. Operators populate this directly today; an OIDC / IDP-backed loader is layered in later (see docs/multi-session-design.md §"Migration story").

func LoadUsersFile(path string) (*UsersFile, error)