teams_rb 2.0.3 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +39 -1
  3. data/docs/README.md +1 -1
  4. data/docs/essentials/README.md +1 -1
  5. data/docs/essentials/on-event.md +12 -2
  6. data/docs/essentials/sending-messages.md +7 -4
  7. data/docs/in-depth-guides/README.md +2 -0
  8. data/docs/in-depth-guides/agent-365.md +3 -1
  9. data/docs/in-depth-guides/files.md +99 -0
  10. data/docs/in-depth-guides/state.md +59 -0
  11. data/docs/in-depth-guides/streaming.md +6 -5
  12. data/docs/in-depth-guides/user-authentication.md +36 -8
  13. data/lib/teams/activity_context.rb +118 -15
  14. data/lib/teams/api/citation_appearance.rb +10 -2
  15. data/lib/teams/api/file_download_info.rb +34 -0
  16. data/lib/teams/api/message_activity.rb +37 -12
  17. data/lib/teams/api/sensitivity_usage_info.rb +38 -0
  18. data/lib/teams/app.rb +195 -153
  19. data/lib/teams/auth/jwt_validator.rb +17 -2
  20. data/lib/teams/cards/generated.rb +430 -430
  21. data/lib/teams/errors.rb +175 -4
  22. data/lib/teams/files/downloaded_file.rb +35 -0
  23. data/lib/teams/files/downloader.rb +405 -0
  24. data/lib/teams/files/files_accessor.rb +175 -0
  25. data/lib/teams/files/graph_share.rb +44 -0
  26. data/lib/teams/files/incoming_file.rb +128 -0
  27. data/lib/teams/files/inline_image.rb +88 -0
  28. data/lib/teams/files.rb +8 -0
  29. data/lib/teams/http_stream.rb +28 -28
  30. data/lib/teams/oauth/flow.rb +184 -0
  31. data/lib/teams/oauth/handlers.rb +376 -0
  32. data/lib/teams/oauth/pending_sign_ins.rb +300 -0
  33. data/lib/teams/oauth.rb +5 -0
  34. data/lib/teams/state/turn_state.rb +163 -0
  35. data/lib/teams/state/turn_state_container.rb +54 -0
  36. data/lib/teams/state/turn_state_loader.rb +143 -0
  37. data/lib/teams/state.rb +5 -0
  38. data/lib/teams/version.rb +1 -1
  39. data/lib/teams.rb +5 -0
  40. metadata +20 -1
@@ -0,0 +1,184 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Teams
4
+ module OAuth
5
+ DEFAULT_OAUTH_CARD_TEXT = "Please Sign In..."
6
+ DEFAULT_SIGN_IN_BUTTON_TEXT = "Sign In"
7
+
8
+ # A successful sign-in on a connection: the turn's context, the Token
9
+ # Service response, and the connection it completed on.
10
+ SignInEvent = Struct.new(:context, :token_response, :connection_name, keyword_init: true)
11
+
12
+ # A failed sign-in. connection_name is nil when a signin/failure callback
13
+ # cannot be attributed to a connection.
14
+ SignInFailureEvent = Struct.new(:context, :connection_name, :code, :message, keyword_init: true)
15
+
16
+ # The connection name with surrounding whitespace removed; a blank name
17
+ # cannot address anything, so it raises.
18
+ def self.normalize_connection_name(connection_name)
19
+ normalized = connection_name.is_a?(String) ? connection_name.strip : ""
20
+ raise ArgumentError, "OAuth connection name must not be blank." if normalized.empty?
21
+
22
+ normalized
23
+ end
24
+
25
+ # The case-insensitive lookup key for a connection name, or nil for a
26
+ # blank or non-string name (lookups are lenient, registration is strict).
27
+ def self.lookup_key(connection_name)
28
+ return nil unless connection_name.is_a?(String)
29
+
30
+ normalized = connection_name.strip
31
+ normalized.empty? ? nil : normalized.downcase
32
+ end
33
+
34
+ # One named OAuth connection plus the handlers attached to it, created
35
+ # with app.add_oauth_flow. Mirrors the TypeScript, Python, and .NET
36
+ # OAuthFlow.
37
+ class Flow
38
+ attr_reader :connection_name, :oauth_card_text, :sign_in_button_text
39
+
40
+ def initialize(connection_name, oauth_card_text: DEFAULT_OAUTH_CARD_TEXT,
41
+ sign_in_button_text: DEFAULT_SIGN_IN_BUTTON_TEXT, logger: nil)
42
+ @connection_name = OAuth.normalize_connection_name(connection_name)
43
+ @oauth_card_text = oauth_card_text
44
+ @sign_in_button_text = sign_in_button_text
45
+ @logger = logger
46
+ @sign_in_handlers = []
47
+ @sign_in_failure_handlers = []
48
+ end
49
+
50
+ # Called with a SignInEvent after a sign-in completes on this
51
+ # connection. Handlers run in registration order, isolated from one
52
+ # another: one that raises is logged and the rest still run.
53
+ def on_sign_in(&block)
54
+ raise ArgumentError, "handler block is required" unless block
55
+
56
+ @sign_in_handlers << block
57
+ self
58
+ end
59
+
60
+ # Called with a SignInFailureEvent when a sign-in on this connection
61
+ # fails. A signin/failure callback carries no connection name, so it is
62
+ # matched against the pending sign-in recorded when the flow started; if
63
+ # that cannot be resolved (typically another process started it and
64
+ # state is off), every registered flow is notified.
65
+ def on_sign_in_failure(&block)
66
+ raise ArgumentError, "handler block is required" unless block
67
+
68
+ @sign_in_failure_handlers << block
69
+ self
70
+ end
71
+
72
+ # Starts sign-in on this connection: returns the token when the user is
73
+ # already signed in, otherwise sends the OAuth card and returns nil. The
74
+ # card text options override the flow's defaults; the connection is
75
+ # always this flow's.
76
+ def sign_in(context, oauth_card_text: nil, sign_in_button_text: nil)
77
+ context.sign_in(
78
+ connection_name:,
79
+ oauth_card_text: oauth_card_text || self.oauth_card_text,
80
+ sign_in_button_text: sign_in_button_text || self.sign_in_button_text
81
+ )
82
+ end
83
+
84
+ # Signs the user out of this connection.
85
+ def sign_out(context)
86
+ context.api.users.sign_out(
87
+ user_id: context.activity.from.id,
88
+ connection_name:,
89
+ channel_id: context.activity.channel_id
90
+ )
91
+ nil
92
+ end
93
+
94
+ # The user's token for this connection, or nil when not signed in.
95
+ # Token Service failures other than 404 raise.
96
+ def get_token(context)
97
+ context.get_user_token(connection_name:)
98
+ end
99
+
100
+ def signed_in?(context)
101
+ !get_token(context).nil?
102
+ end
103
+
104
+ def sign_in_handlers?
105
+ !@sign_in_handlers.empty?
106
+ end
107
+
108
+ def sign_in_failure_handlers?
109
+ !@sign_in_failure_handlers.empty?
110
+ end
111
+
112
+ def invoke_sign_in_handlers(event)
113
+ dispatch(@sign_in_handlers, event, "on_sign_in")
114
+ end
115
+
116
+ def invoke_sign_in_failure_handlers(event)
117
+ dispatch(@sign_in_failure_handlers, event, "on_sign_in_failure")
118
+ end
119
+
120
+ def inspect
121
+ "#<#{self.class.name} connection_name=#{connection_name.inspect}>"
122
+ end
123
+
124
+ private
125
+
126
+ # A raising handler is a broken listener: it must not hide the rest or
127
+ # turn a successful callback into a failed invoke response.
128
+ def dispatch(handlers, event, kind)
129
+ handlers.dup.each do |handler|
130
+ handler.call(event)
131
+ rescue StandardError => error
132
+ @logger&.error(
133
+ "#{kind} handler failed for connection #{connection_name.inspect}; continuing with later handlers: " \
134
+ "#{error.class}: #{error.message}"
135
+ )
136
+ end
137
+ nil
138
+ end
139
+ end
140
+
141
+ # Case-insensitive, insertion-ordered collection of flows.
142
+ class FlowRegistry
143
+ include Enumerable
144
+
145
+ def initialize
146
+ @flows = {}
147
+ end
148
+
149
+ def add(flow)
150
+ key = OAuth.lookup_key(flow.connection_name)
151
+ if @flows.key?(key)
152
+ raise ArgumentError, "An OAuth flow for connection '#{flow.connection_name}' is already registered. " \
153
+ "Connection names are case-insensitive."
154
+ end
155
+
156
+ @flows[key] = flow
157
+ end
158
+
159
+ # The flow for a connection name (case-insensitive), or nil.
160
+ def [](connection_name)
161
+ @flows[OAuth.lookup_key(connection_name)]
162
+ end
163
+
164
+ def each(&block)
165
+ return enum_for(:each) unless block
166
+
167
+ @flows.values.each(&block)
168
+ self
169
+ end
170
+
171
+ def names
172
+ @flows.values.map(&:connection_name)
173
+ end
174
+
175
+ def size
176
+ @flows.size
177
+ end
178
+
179
+ def empty?
180
+ @flows.empty?
181
+ end
182
+ end
183
+ end
184
+ end
@@ -0,0 +1,376 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "set"
4
+
5
+ module Teams
6
+ module OAuth
7
+ # The default sign-in callback handlers, mirroring the TypeScript and
8
+ # Python OAuth handlers: registered first on the signin routes, they
9
+ # complete the flows, route each callback to its registered flow, fire
10
+ # the sign-in events, and chain to user handlers via next. Their return
11
+ # value is the invoke response; 412 tells the Teams client to fall back to
12
+ # the interactive card.
13
+ class Handlers
14
+ EXPECTED_STATUSES = [400, 404, 412].freeze
15
+ FAILURE_DETAIL = "unable to exchange token..."
16
+ COMPLETED_TTL = ExchangeMarkers::TTL
17
+ MAX_COMPLETED = 1000
18
+
19
+ # How an owned token exchange settled, replayed to duplicates that
20
+ # arrived while it ran.
21
+ Outcome = Struct.new(:response, :error, :token_redeemed, keyword_init: true)
22
+
23
+ class InFlight
24
+ def initialize
25
+ @mutex = Mutex.new
26
+ @settled = ConditionVariable.new
27
+ @outcome = nil
28
+ end
29
+
30
+ def settle(outcome)
31
+ @mutex.synchronize do
32
+ @outcome = outcome
33
+ @settled.broadcast
34
+ end
35
+ end
36
+
37
+ def wait
38
+ @mutex.synchronize do
39
+ @settled.wait(@mutex) until @outcome
40
+ @outcome
41
+ end
42
+ end
43
+ end
44
+
45
+ attr_reader :pending_cache
46
+
47
+ def initialize(app)
48
+ @app = app
49
+ @pending_cache = LocalPendingCache.new
50
+ @mutex = Mutex.new
51
+ @in_flight = {}
52
+ @completed = {}
53
+ end
54
+
55
+ # signin/tokenExchange. Teams fans one exchange out to every endpoint
56
+ # the user is signed in on, so repeats of an exchange id short-circuit:
57
+ # a completed one answers 200 without re-emitting or chaining, and one
58
+ # still running waits and mirrors the owner's result (412 if it raised).
59
+ def token_exchange(ctx, nxt)
60
+ exchange_id = ctx.activity.value.raw["id"]
61
+ return run_token_exchange(ctx, nxt) if exchange_id.to_s.empty?
62
+
63
+ waiting = nil
64
+ owned = nil
65
+ completed = false
66
+ @mutex.synchronize do
67
+ if (waiting = @in_flight[exchange_id])
68
+ nil
69
+ elsif completed_exchange?(ctx, exchange_id)
70
+ completed = true
71
+ else
72
+ owned = @in_flight[exchange_id] = InFlight.new
73
+ end
74
+ end
75
+ return await_exchange(ctx, exchange_id, waiting) if waiting
76
+ return replay_completed_exchange(ctx, exchange_id) if completed
77
+
78
+ run_owned_exchange(ctx, nxt, exchange_id, owned)
79
+ end
80
+
81
+ # signin/verifyState carries only a magic code, so the connections are
82
+ # probed in order: pending sign-ins (newest first), the remaining
83
+ # registered flows, then the default connection. A code a connection
84
+ # rejects (400/404/412) moves on to the next; none accepting is a 404.
85
+ def verify_state(ctx, nxt)
86
+ code = ctx.activity.value.raw["state"]
87
+ if code.to_s.empty?
88
+ logger&.warn(
89
+ "Auth state not present for conversation id '#{ctx.activity.conversation&.id}' " \
90
+ "and user id '#{ctx.activity.from&.id}'."
91
+ )
92
+ return Response.new(status: 404)
93
+ end
94
+
95
+ verify_candidates(ctx).each do |connection_name, flow|
96
+ terminal, response = verify_candidate(ctx, connection_name, flow, code)
97
+ return response if terminal
98
+ end
99
+ Response.new(status: 404)
100
+ ensure
101
+ nxt.call
102
+ end
103
+
104
+ # signin/failure carries no connection name: it is attributed to the
105
+ # newest pending sign-in that offered silent SSO. Without one, the
106
+ # default connection is reported when no flows are registered;
107
+ # otherwise the connection is unknown (nil) and every registered flow's
108
+ # failure handlers are notified so none silently misses it.
109
+ def failure(ctx, nxt)
110
+ value = ctx.activity.value.raw
111
+ target = pending_flows(ctx, sso_only: true).first
112
+ registered = registry.to_a
113
+ connection_name = if target
114
+ target.connection_name
115
+ elsif registered.empty?
116
+ @app.default_connection_name
117
+ end
118
+
119
+ logger&.warn(
120
+ "Sign-in failed: #{value["code"]} - #{value["message"]}. " \
121
+ "If the code is 'resourcematchfailed', verify the Entra app registration's " \
122
+ "Application ID URI matches the OAuth connection's Token Exchange URL."
123
+ )
124
+ callback_flows = target ? [target] : registered
125
+ callback_flows.each { |flow| clear_pending(ctx, flow.connection_name) }
126
+
127
+ @app.emit_error(Error.new("Sign-in failure: #{value["code"]} - #{value["message"]}"), activity: ctx.activity)
128
+ event = SignInFailureEvent.new(context: ctx, connection_name:, code: value["code"], message: value["message"])
129
+ @app.emit_sign_in_failure(event)
130
+ callback_flows.each do |flow|
131
+ flow_event = target ? event : event.dup.tap { |copy| copy.connection_name = flow.connection_name }
132
+ flow.invoke_sign_in_failure_handlers(flow_event)
133
+ end
134
+ nil
135
+ ensure
136
+ nxt.call
137
+ end
138
+
139
+ private
140
+
141
+ def registry
142
+ @app.oauth_registry
143
+ end
144
+
145
+ def logger
146
+ @app.logger
147
+ end
148
+
149
+ def run_owned_exchange(ctx, nxt, exchange_id, owned)
150
+ outcome = nil
151
+ begin
152
+ response = run_token_exchange(ctx, nxt)
153
+ outcome = Outcome.new(response:, token_redeemed: memory_completed?(exchange_id))
154
+ response
155
+ rescue StandardError => error
156
+ outcome = Outcome.new(error:, token_redeemed: memory_completed?(exchange_id))
157
+ raise
158
+ ensure
159
+ outcome ||= Outcome.new(error: Error.new("token exchange interrupted"), token_redeemed: false)
160
+ @mutex.synchronize { @in_flight.delete(exchange_id) }
161
+ owned.settle(outcome)
162
+ end
163
+ end
164
+
165
+ def await_exchange(ctx, exchange_id, waiting)
166
+ outcome = waiting.wait
167
+ stamp_completed_exchange(ctx, exchange_id) if outcome.token_redeemed
168
+ if outcome.error
169
+ return Response.new(
170
+ status: 412,
171
+ body: {
172
+ "id" => exchange_id,
173
+ "connectionName" => resolved_connection_name(ctx.activity.value.raw["connectionName"]),
174
+ "failureDetail" => outcome.error.message.to_s.empty? ? FAILURE_DETAIL : outcome.error.message
175
+ }
176
+ )
177
+ end
178
+
179
+ outcome.response.is_a?(Response) ? outcome.response : Response.new(status: 200)
180
+ end
181
+
182
+ def replay_completed_exchange(ctx, exchange_id)
183
+ logger&.debug("Duplicate signin/tokenExchange with id '#{exchange_id}' - returning 200 no-op.")
184
+ stamp_completed_exchange(ctx, exchange_id)
185
+ Response.new(status: 200)
186
+ end
187
+
188
+ def run_token_exchange(ctx, nxt)
189
+ activity = ctx.activity
190
+ value = activity.value.raw
191
+ connection_name = value["connectionName"]
192
+ flow = registry[connection_name]
193
+ event_connection_name = flow ? flow.connection_name : connection_name
194
+
195
+ if flow.nil? && OAuth.lookup_key(connection_name) != OAuth.lookup_key(@app.default_connection_name)
196
+ logger&.warn(
197
+ "Sign-in token exchange invoked with connection name #{connection_name.inspect}, " \
198
+ "but it is neither the default connection #{@app.default_connection_name.inspect} " \
199
+ "nor a registered OAuth flow. Token verification will likely fail."
200
+ )
201
+ end
202
+
203
+ begin
204
+ token = ctx.api.users.exchange_token(
205
+ user_id: activity.from.id,
206
+ connection_name:,
207
+ channel_id: activity.channel_id,
208
+ exchange_request: { "token" => value["token"] }
209
+ )
210
+ rescue HttpError => error
211
+ unless EXPECTED_STATUSES.include?(error.status)
212
+ clear_pending(ctx, event_connection_name)
213
+ logger&.error("Error exchanging token: #{error.message}")
214
+ @app.emit_error(error, activity:)
215
+ status = error.status || 500
216
+ notify_terminal_failure(ctx, flow, error, status)
217
+ return Response.new(status:)
218
+ end
219
+
220
+ logger&.info("Unable to exchange token: #{error.message}")
221
+ return Response.new(
222
+ status: 412,
223
+ body: {
224
+ "id" => value["id"],
225
+ "connectionName" => connection_name,
226
+ "failureDetail" => error.message.to_s.empty? ? FAILURE_DETAIL : error.message
227
+ }
228
+ )
229
+ end
230
+
231
+ record_completed_exchange(ctx, value["id"])
232
+ clear_pending(ctx, event_connection_name)
233
+ @app.emit_sign_in(ctx, token)
234
+ flow&.invoke_sign_in_handlers(SignInEvent.new(context: ctx, token_response: token, connection_name: event_connection_name))
235
+ nil
236
+ ensure
237
+ nxt.call
238
+ end
239
+
240
+ def verify_candidates(ctx)
241
+ seen = Set.new
242
+ candidates = []
243
+ (pending_flows(ctx) + registry.to_a).each do |flow|
244
+ key = OAuth.lookup_key(flow.connection_name)
245
+ next if key.nil? || seen.include?(key)
246
+
247
+ seen << key
248
+ candidates << [flow.connection_name, flow]
249
+ end
250
+
251
+ default_flow = registry[@app.default_connection_name]
252
+ default_name = default_flow ? default_flow.connection_name : @app.default_connection_name
253
+ candidates << [default_name, default_flow] unless seen.include?(OAuth.lookup_key(default_name))
254
+ candidates
255
+ end
256
+
257
+ # Returns [terminal, response]: a rejected code is not terminal.
258
+ def verify_candidate(ctx, connection_name, flow, code)
259
+ activity = ctx.activity
260
+ token = ctx.api.users.get_token(
261
+ user_id: activity.from.id,
262
+ connection_name:,
263
+ channel_id: activity.channel_id,
264
+ code:
265
+ )
266
+ clear_pending(ctx, connection_name)
267
+ @app.emit_sign_in(ctx, token)
268
+ flow&.invoke_sign_in_handlers(SignInEvent.new(context: ctx, token_response: token, connection_name:))
269
+ [true, nil]
270
+ rescue HttpError => error
271
+ if EXPECTED_STATUSES.include?(error.status)
272
+ logger&.debug(
273
+ "OAuth connection '#{connection_name}' did not accept the verify-state code (HTTP #{error.status})."
274
+ )
275
+ return [false, nil]
276
+ end
277
+
278
+ clear_pending(ctx, connection_name)
279
+ logger&.error("Error verifying sign-in state: #{error.message}")
280
+ @app.emit_error(error, activity:)
281
+ status = error.status || 500
282
+ notify_terminal_failure(ctx, flow, error, status)
283
+ [true, Response.new(status:)]
284
+ end
285
+
286
+ def notify_terminal_failure(ctx, flow, error, status)
287
+ return unless flow
288
+
289
+ flow.invoke_sign_in_failure_handlers(
290
+ SignInFailureEvent.new(
291
+ context: ctx, connection_name: flow.connection_name, code: "tokenservice.http_#{status}", message: error.message
292
+ )
293
+ )
294
+ end
295
+
296
+ def pending_flows(ctx, sso_only: false)
297
+ conversation_id, user_id = pending_scope(ctx)
298
+ PendingSignIns.list(ctx.state, pending_cache, conversation_id:, user_id:).filter_map do |pending|
299
+ next if sso_only && !pending.sso_offered
300
+
301
+ flow = registry[pending.connection_name]
302
+ unless flow
303
+ logger&.debug(
304
+ "Discarding pending OAuth sign-in state for connection '#{pending.connection_name}': no registered OAuth flow."
305
+ )
306
+ PendingSignIns.clear(ctx.state, pending_cache, pending.connection_name, conversation_id:, user_id:)
307
+ next
308
+ end
309
+ flow
310
+ end
311
+ end
312
+
313
+ def clear_pending(ctx, connection_name)
314
+ conversation_id, user_id = pending_scope(ctx)
315
+ PendingSignIns.clear(ctx.state, pending_cache, connection_name, conversation_id:, user_id:)
316
+ end
317
+
318
+ def pending_scope(ctx)
319
+ [ctx.activity.conversation&.id, ctx.activity.from&.id]
320
+ end
321
+
322
+ def resolved_connection_name(connection_name)
323
+ flow = registry[connection_name]
324
+ flow ? flow.connection_name : connection_name
325
+ end
326
+
327
+ # Must be called while holding @mutex.
328
+ def completed_exchange?(ctx, exchange_id)
329
+ prune_completed
330
+ return true if @completed.key?(exchange_id)
331
+
332
+ ExchangeMarkers.completed?(ctx.state, exchange_id)
333
+ rescue StandardError => error
334
+ logger&.error("Unable to read persisted OAuth token exchange state; deduplicating in memory only: #{error.message}")
335
+ false
336
+ end
337
+
338
+ def memory_completed?(exchange_id)
339
+ @mutex.synchronize { @completed.key?(exchange_id) }
340
+ end
341
+
342
+ # The in-memory marker is authoritative on this instance; the state
343
+ # marker (saved right away) lets another instance short-circuit too.
344
+ def record_completed_exchange(ctx, exchange_id)
345
+ return if exchange_id.to_s.empty?
346
+
347
+ @mutex.synchronize do
348
+ prune_completed
349
+ @completed[exchange_id] = Time.now.to_f
350
+ @completed.shift while @completed.size > MAX_COMPLETED
351
+ end
352
+
353
+ begin
354
+ ExchangeMarkers.record(ctx.state, exchange_id)
355
+ ctx.state&.save
356
+ rescue StandardError => error
357
+ logger&.error("Unable to persist completed OAuth token exchange; deduplicating in memory only: #{error.message}")
358
+ end
359
+ end
360
+
361
+ # A duplicate's own turn state may predate the owner's write; saves are
362
+ # last-write-wins, so the marker is copied into it to survive.
363
+ def stamp_completed_exchange(ctx, exchange_id)
364
+ ExchangeMarkers.record(ctx.state, exchange_id) unless ExchangeMarkers.completed?(ctx.state, exchange_id)
365
+ rescue StandardError => error
366
+ logger&.error("Unable to stamp completed OAuth token exchange into turn state: #{error.message}")
367
+ end
368
+
369
+ # Must be called while holding @mutex.
370
+ def prune_completed
371
+ cutoff = Time.now.to_f - COMPLETED_TTL
372
+ @completed.delete_if { |_, completed_at| completed_at < cutoff }
373
+ end
374
+ end
375
+ end
376
+ end