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

# Capability Token Service
# Stateless signing service that prompts users and signs authorization tokens.
# Tokens are validated by resource services (e.g., maildir-varlink).

interface de.profpatsch.CapabilityTokens

# HATEOAS Action type for discoverable APIs
type Action (
  name: string,
  href: string,
  method: string,
  description: string
)

# Request a capability token (prompts user for approval)
# Parameters:
#   token_id: Token type identifier (e.g., "maildir:open-mailbox")
#   scope: Token scope fields (e.g., {"mailbox_dir": "/home/user/Mail"})
#   session: Session UUID from resource service (e.g., maildir.NewSession())
#   reason: Optional explanation shown to user in approval dialog
#   token_description: Optional human-readable description of what token allows
#   field_descriptions: Optional descriptions for scope fields (maps field name to description)
# Returns:
#   token: Complete signed token (includes _sig field)
method RequestToken(
  token_id: string,
  scope: object,
  session: string,
  reason: ?string,
  token_description: ?string,
  field_descriptions: ?object
) -> (
  token: object,
  available_actions: []Action
)

# Get the public key for token verification
# Resource services use this key to verify token signatures.
# Returns:
#   public_key_base64: ED25519 public key encoded as base64
method GetPublicKey() -> (
  public_key_base64: string,
  available_actions: []Action
)

# Dialog callback - called by dialog subprocess to report user's decision
# Parameters:
#   dialog_uuid: UUID identifying this dialog request
#   approved: true if user clicked Allow, false if Deny
method DialogReply(
  dialog_uuid: string,
  approved: bool
) -> ()

# Error codes
error TokenDenied (reason: string)
error SigningFailed (message: string)