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
|
package main
// Token type constants for intent-based authorization.
// Each token type represents a specific workflow/use case, not just API method access.
const (
// TokenInvestigateRecentMail authorizes checking recent mail and reading limited messages.
//
// Typical workflow: "Check if my package arrived" or "See what's new"
//
// Scope fields:
// - mailbox_dir: absolute path to mailbox (REQUIRED)
// - max_age_days: 1-30 days (OPTIONAL, omit for unlimited age access)
// - max_full_reads: 3-10 messages (REQUIRED, typical: 5)
//
// Notes:
// - When max_age_days is omitted, all messages are accessible (subject to output limits)
// - Omitting max_age_days requires explicit user consent ("all messages")
// - Use GetMostRecentMessages to efficiently find newest messages without age filter
//
// Authorized handlers:
// - ListMessages (with time filter applied if max_age_days present)
// - GetMostRecentMessages (ignores max_age_days, always returns newest)
// - ScanMessages
// - GetMessage (enforces max_full_reads limit and age constraint)
// - SearchByDate
//
// Typical duration: 1-5 minutes
//
// Example user prompts:
// With age limit: "Claude wants to check recent mail (last 7 days) and read up to 5 messages"
// Unlimited age: "Claude wants to search all mail and read up to 5 messages"
TokenInvestigateRecentMail = "maildir:investigate-recent-mail"
// TokenSearchAndRead authorizes searching with a frozen query and reading limited results.
//
// Typical workflow: "Find all invoices from Amazon" or "Search for messages about X"
//
// Required scope fields:
// - mailbox_dir: absolute path to mailbox
// - search_query: the exact search expression (frozen - cannot be changed!)
// - max_results: 20-100 (typical: 50)
// - max_full_reads: 5-20 (typical: 10)
//
// Authorized handlers:
// - SearchMessages (enforces query matches token)
// - SearchByHeader (enforces query matches token)
// - ScanMessages
// - GetMessage (enforces max_full_reads limit)
//
// Typical duration: 1-3 minutes
//
// Example user prompt:
// "Claude wants to search for 'from:amazon subject:invoice'
// (up to 50 results) and read up to 10 messages"
//
// Security note: The search query is part of the token scope and frozen at signing time.
// The agent cannot change the query without requesting a new token.
TokenSearchAndRead = "maildir:search-and-read"
// TokenQuickScanOnly authorizes listing and scanning recent messages (NO full body reading).
//
// Typical workflow: "Check if any new mail arrived today" or "When did I last send email?"
//
// Scope fields:
// - mailbox_dir: absolute path to mailbox (REQUIRED)
// - max_age_days: 1-7 days (OPTIONAL, omit for unlimited age access)
//
// Notes:
// - When max_age_days is omitted, all messages are accessible for scanning
// - GetMessage is BLOCKED regardless of max_age_days (summaries only)
// - Use GetMostRecentMessages to find "when was my last email?" efficiently
//
// Authorized handlers:
// - ListMessages (with time filter if max_age_days present)
// - GetMostRecentMessages (ignores max_age_days, always returns newest)
// - ScanMessages
// (GetMessage is explicitly BLOCKED by this token type)
//
// Typical duration: 30 seconds
//
// Example user prompts:
// With age limit: "Claude wants to check if any new mail arrived today (summaries only)"
// Unlimited age: "Claude wants to find when you last sent email (summaries only, all messages)"
TokenQuickScanOnly = "maildir:quick-scan-only"
// TokenEnumerateMailboxes authorizes discovering mailbox folder structure.
//
// Typical workflow: "Show me my email folders" or discovering available mailboxes
//
// Required scope fields:
// - root_dir: absolute path to maildir root
//
// Authorized handlers:
// - ListMailboxes
//
// Typical duration: 10 seconds
//
// Example user prompt:
// "Claude wants to see your mailbox folder structure"
//
// Security note: This reveals organizational structure which might be sensitive.
TokenEnumerateMailboxes = "maildir:enumerate-mailboxes"
)
// Token type documentation for capability service and HATEOAS discovery.
// This can be used to generate ListTokenTypes() responses and help text.
var TokenTypeInfo = map[string]struct {
Description string
RiskLevel string // "routine", "elevated", "administrative"
TypicalDuration string // Human-readable
AuthorizedMethods []string
}{
TokenInvestigateRecentMail: {
Description: "Check recent mail and read limited messages",
RiskLevel: "routine",
TypicalDuration: "1-5 minutes",
AuthorizedMethods: []string{
"de.profpatsch.Maildir.ListMessages",
"de.profpatsch.Maildir.ScanMessages",
"de.profpatsch.Maildir.GetMessage",
"de.profpatsch.Maildir.SearchByDate",
},
},
TokenSearchAndRead: {
Description: "Search with frozen query and read limited results",
RiskLevel: "routine",
TypicalDuration: "1-3 minutes",
AuthorizedMethods: []string{
"de.profpatsch.Maildir.SearchMessages",
"de.profpatsch.Maildir.SearchByHeader",
"de.profpatsch.Maildir.ScanMessages",
"de.profpatsch.Maildir.GetMessage",
},
},
TokenQuickScanOnly: {
Description: "List and scan recent messages (no full body reading)",
RiskLevel: "routine",
TypicalDuration: "30 seconds",
AuthorizedMethods: []string{
"de.profpatsch.Maildir.ListMessages",
"de.profpatsch.Maildir.ScanMessages",
},
},
TokenEnumerateMailboxes: {
Description: "Discover mailbox folder structure",
RiskLevel: "elevated",
TypicalDuration: "10 seconds",
AuthorizedMethods: []string{
"de.profpatsch.Maildir.ListMailboxes",
},
},
}
|