Repository navigation
Expand file tree
/
Copy pathplugin.go
More file actions
258 lines (235 loc) · 9.28 KB
/
Copy pathplugin.go
File metadata and controls
258 lines (235 loc) · 9.28 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
package agentauth
import (
"context"
"net/http"
"time"
log "github.com/xraph/go-utils/log"
"github.com/xraph/forge"
"github.com/xraph/authsome/bridge"
"github.com/xraph/authsome/hook"
"github.com/xraph/authsome/middleware"
"github.com/xraph/authsome/plugin"
"github.com/xraph/authsome/plugins/oauth2provider"
"github.com/xraph/grove/migrate"
)
// defaultGrantTTL caps how long a delegation lives before the user has to
// consent again.
const defaultGrantTTL = 90 * 24 * time.Hour
// Compile-time interface checks.
var (
_ plugin.Plugin = (*Plugin)(nil)
_ plugin.OnInit = (*Plugin)(nil)
_ plugin.RouteProvider = (*Plugin)(nil)
_ plugin.MigrationProvider = (*Plugin)(nil)
)
// Plugin is the delegated agent identity plugin.
type Plugin struct {
engine plugin.Engine
store Store
scopes *ScopeRegistry
hooks *hook.Bus
chronicle bridge.Chronicle
logger log.Logger
permChecker plugin.PermissionChecker
grantTTL time.Duration
basePath string
cache *grantCache
}
// Option configures the plugin at construction.
type Option func(*Plugin)
// WithScope maps a delegation scope onto a Warden permission. A scope with no
// mapping is rejected at consent time.
func WithScope(scope string, p Permission) Option {
return func(pl *Plugin) { pl.scopes.Register(scope, p) }
}
// WithStore injects a persistent store. Without it the plugin uses an
// in-memory store. A nil s is a no-op rather than installing a nil store:
// Store is an interface, so pl.store = nil would leave every store call in
// the plugin (Authorize's grant read included, at the very first thing an
// agent request does) calling a method on a nil interface value, which
// panics rather than erroring. New() already sets a working default before
// any Option runs, so there is nothing useful a nil argument here could mean
// other than "leave it alone".
func WithStore(s Store) Option {
return func(pl *Plugin) {
if s == nil {
return
}
pl.store = s
}
}
// WithDefaultGrantTTL sets the fallback cap on grant lifetime. An org policy
// with a shorter MaxGrantTTL still wins.
func WithDefaultGrantTTL(d time.Duration) Option {
return func(pl *Plugin) { pl.grantTTL = d }
}
// New creates the agentauth plugin.
func New(opts ...Option) *Plugin {
p := &Plugin{
store: NewMemoryStore(),
scopes: NewScopeRegistry(),
grantTTL: defaultGrantTTL,
cache: newGrantCache(grantCacheTTL),
}
for _, opt := range opts {
opt(p)
}
return p
}
// Name returns the plugin name.
func (p *Plugin) Name() string { return "agentauth" }
// MigrationGroups returns the agentauth migration groups for the given driver.
func (p *Plugin) MigrationGroups(driverName string) []*migrate.Group {
switch driverName {
case "pg", "postgres":
return []*migrate.Group{PostgresMigrations}
case "sqlite", "sqlite3":
return []*migrate.Group{SqliteMigrations}
case "mongo", "mongodb":
return []*migrate.Group{MongoMigrations}
default:
return nil
}
}
// Scopes returns the delegation scope registry.
func (p *Plugin) Scopes() *ScopeRegistry { return p.scopes }
// Store returns the plugin's store.
func (p *Plugin) Store() Store { return p.store }
// DefaultGrantTTL returns the fallback cap on grant lifetime.
func (p *Plugin) DefaultGrantTTL() time.Duration { return p.grantTTL }
// OnInit captures engine capabilities.
func (p *Plugin) OnInit(_ context.Context, engine plugin.Engine) error {
p.engine = engine
p.hooks = engine.Hooks()
p.chronicle = bridge.NewBusChronicle(engine.Hooks())
p.logger = engine.Logger()
// The router plugins register on is already grouped at the app's base
// path (extension/extension.go groups it before handing plugins the
// router), so p.basePath must carry only the version segment, not the
// base path again. engine.BasePath() defaults to "/authsome", and using
// it here would have doubled up to "/authsome/authsome/me/agents".
// plugins/consent/plugin.go hardcodes "/v1" for the same reason; this
// matches it.
p.basePath = "/v1"
if pc, ok := engine.(plugin.PermissionChecker); ok {
p.permChecker = pc
}
p.registerConsentGate(engine)
return nil
}
// consentGateSetter is implemented by oauth2provider.Plugin. Asserting
// against this interface rather than the concrete type keeps agentauth from
// importing more of that package's surface than this one call needs, and
// keeps the wiring resilient to a test double or future re-implementation
// that satisfies the same shape without being oauth2provider.Plugin itself.
type consentGateSetter interface {
SetConsentGate(oauth2provider.ConsentGate)
}
// registerConsentGate wires agentauth as oauth2provider's ConsentGate when
// an "oauth2provider" plugin is registered on the same engine, per the
// design spec ("agentauth registers itself as the gate during OnInit") and
// per oauth2provider's own consent_gate.go doc comment, which already
// asserts this happens.
//
// Without this call the plugin enforces nothing at the point that matters
// most: a host that follows the RegisterRoutes/RouteProvider wiring alone,
// with no code of its own naming ConsentGate, would see an agent run the
// ordinary OAuth2 flow and receive a plain human session — no PrincipalKind,
// no grant, that user's full role set — because nothing ever told
// oauth2provider a gate exists to consult.
//
// A missing oauth2provider plugin, or one that doesn't expose
// SetConsentGate, is a no-op rather than an error: agentauth must remain
// usable in a host that has not installed oauth2provider yet, or that wires
// the gate some other way (see doc.go's host integration contract, point 1).
func (p *Plugin) registerConsentGate(engine plugin.Engine) {
op := engine.Plugins().Plugin("oauth2provider")
if op == nil {
p.logger.Debug("agentauth: no oauth2provider plugin registered; consent gate not wired")
return
}
setter, ok := op.(consentGateSetter)
if !ok {
p.logger.Debug("agentauth: registered oauth2provider plugin does not expose SetConsentGate; consent gate not wired")
return
}
setter.SetConsentGate(p)
}
// RegisterRoutes registers the user and admin surfaces: a place for a user
// to see and revoke which agents are acting for them, and an admin surface
// for registering and blocking agents org-wide.
func (p *Plugin) RegisterRoutes(router forge.Router) error {
// Neither surface is open to an agent or delegated session, so an agent
// cannot manage its own delegation. SessionGuard and AdminGuard check
// permissions against sess.UserID, which for an agent session is the
// delegating user: without the deny, an agent acting for an org admin
// could open its own org's policy, unblock itself or revoke a competing
// grant. On /me the deny goes after the guard, which is what resolves the
// session (see middleware.DenyDelegatedSession); AdminGuard ends with it.
me := router.Group(p.basePath+"/me/agents",
forge.WithGroupTags("agentauth"),
forge.WithGroupAuth("session"),
forge.WithGroupMiddleware(append(plugin.SessionGuard(p.engine), middleware.DenyDelegatedSession())...),
)
if err := me.GET("", p.handleListMyGrants,
forge.WithSummary("List agents acting on my behalf"),
forge.WithResponseSchema(http.StatusOK, "Active delegations", ListGrantsResponse{}),
forge.WithErrorResponses(),
); err != nil {
return err
}
if err := me.DELETE("/:id", p.handleRevokeMyGrant,
forge.WithSummary("Revoke an agent's delegation"),
forge.WithResponseSchema(http.StatusOK, "Grant revoked", StatusResponse{}),
forge.WithErrorResponses(),
); err != nil {
return err
}
admin := router.Group(p.basePath+"/admin/agents",
forge.WithGroupTags("agentauth-admin"),
forge.WithGroupAuth("session"),
forge.WithGroupMiddleware(plugin.AdminGuard(p.engine, "read", "agent")...),
)
if err := admin.GET("", p.handleListAgents,
forge.WithSummary("List registered agents"),
forge.WithResponseSchema(http.StatusOK, "Registered agents", ListAgentsResponse{}),
forge.WithErrorResponses(),
); err != nil {
return err
}
if err := admin.POST("", p.handleRegisterAgent,
append([]forge.RouteOption{
forge.WithSummary("Register an agent"),
forge.WithRequestSchema(RegisterAgentRequest{}),
forge.WithResponseSchema(http.StatusCreated, "Agent registered", Agent{}),
forge.WithErrorResponses(),
}, plugin.PermissionRouteOptions(p.engine, "write", "agent")...)...,
); err != nil {
return err
}
if err := admin.PATCH("/:id/status", p.handleSetAgentStatus,
append([]forge.RouteOption{
forge.WithSummary("Approve or block an agent"),
forge.WithRequestSchema(SetAgentStatusRequest{}),
forge.WithResponseSchema(http.StatusOK, "Status updated", StatusResponse{}),
forge.WithErrorResponses(),
}, plugin.PermissionRouteOptions(p.engine, "write", "agent")...)...,
); err != nil {
return err
}
if err := admin.GET("/policy", p.handleGetOrgPolicy,
forge.WithSummary("Read the org's agent delegation policy"),
forge.WithResponseSchema(http.StatusOK, "Current policy", OrgAgentPolicy{}),
forge.WithErrorResponses(),
); err != nil {
return err
}
return admin.PUT("/policy", p.handlePutOrgPolicy,
append([]forge.RouteOption{
forge.WithSummary("Set the org's agent delegation policy"),
forge.WithRequestSchema(PutOrgPolicyRequest{}),
forge.WithResponseSchema(http.StatusOK, "Policy set", OrgAgentPolicy{}),
forge.WithErrorResponses(),
}, plugin.PermissionRouteOptions(p.engine, "write", "agent")...)...,
)
}