+36 -16

PLAN.md

··· 67 - [x] `Actor.accept_follow` - send Accept(Follow) 68 - [x] `Actor.reject_follow` - send Reject(Follow) 69 70 - ## Phase 5: Missing Proto Properties (Partial) 71 72 ### 5.1 Actor Properties ✓ 73 - [x] `also_known_as: Uri.t list option` ··· 77 - [x] `featured: Uri.t option` 78 - [x] `featured_tags: Uri.t option` 79 80 - ### 5.2 Object Properties (Partial) 81 - [x] `conversation: Uri.t option` (conversation threading) 82 - [x] `audience: Recipient.t list option` 83 - - [ ] `location` support 84 - - [ ] `preview: Link_or_uri.t option` 85 86 - ### 5.3 Question Activity 87 - - [ ] `one_of: Object.t list option` 88 - - [ ] `any_of: Object.t list option` 89 - - [ ] `closed: Datetime.t option` 90 91 ## Phase 6: NodeInfo ✓ 92 ··· 94 - [x] Parse nodeinfo links for schema 2.0/2.1 95 - [x] Fetch and decode nodeinfo document 96 97 - ## Phase 7: CLI Enhancements 98 99 Current commands: 100 - [x] `apub webfinger` - look up account via Webfinger 101 - [x] `apub actor` - fetch an ActivityPub actor 102 - [x] `apub outbox` - fetch an actor's outbox 0 0 0 0 103 104 - Planned: 105 - - [ ] `apub post` - create and post a note 106 - - [ ] `apub follow` - follow an actor 107 - - [ ] `apub like` - like a post 108 - - [ ] `apub boost` - announce/reblog a post 0 0 109 110 ## Implementation Order 111 ··· 116 ↓ 117 Phase 3 (Outbox) ✓ 118 ↓ 119 - Phase 7 (CLI) - in progress 0 0 120 121 - Phase 5 (Properties) ✓ (partial - missing location, preview, Question) 122 Phase 6 (NodeInfo) ✓ 123 ``` 0 0 0 0 0 0 0 0 0 0 0 0

··· 67 - [x] `Actor.accept_follow` - send Accept(Follow) 68 - [x] `Actor.reject_follow` - send Reject(Follow) 69 70 + ## Phase 5: Proto Properties ✓ 71 72 ### 5.1 Actor Properties ✓ 73 - [x] `also_known_as: Uri.t list option` ··· 77 - [x] `featured: Uri.t option` 78 - [x] `featured_tags: Uri.t option` 79 80 + ### 5.2 Object Properties ✓ 81 - [x] `conversation: Uri.t option` (conversation threading) 82 - [x] `audience: Recipient.t list option` 83 + - [x] `location: Link_or_uri.t option` 84 + - [x] `preview: Link_or_uri.t option` 85 86 + ### 5.3 Question Activity ✓ 87 + - [x] `one_of: Object_ref.t list option` 88 + - [x] `any_of: Object_ref.t list option` 89 + - [x] `closed: Datetime.t option` 90 91 ## Phase 6: NodeInfo ✓ 92 ··· 94 - [x] Parse nodeinfo links for schema 2.0/2.1 95 - [x] Fetch and decode nodeinfo document 96 97 + ## Phase 7: CLI Enhancements ✓ 98 99 Current commands: 100 - [x] `apub webfinger` - look up account via Webfinger 101 - [x] `apub actor` - fetch an ActivityPub actor 102 - [x] `apub outbox` - fetch an actor's outbox 103 + - [x] `apub post` - create and post a note 104 + - [x] `apub follow` - follow an actor 105 + - [x] `apub like` - like a post 106 + - [x] `apub boost` - announce/reblog a post 107 108 + ## Phase 8: WebFinger Integration ✓ 109 + 110 + Integrated the `webfinger` library for RFC 7033/7565 compliant discovery: 111 + - [x] Use `Webfinger.query_acct` for proper acct URI handling 112 + - [x] Support for percent-encoding in userparts 113 + - [x] Added `Webfinger.lookup_raw` for efficient direct JRD access 114 + - [x] Added ActivityPub WebFinger spec to `spec/` directory 115 116 ## Implementation Order 117 ··· 122 ↓ 123 Phase 3 (Outbox) ✓ 124 ↓ 125 + Phase 7 (CLI) ✓ 126 + ↓ 127 + Phase 8 (WebFinger) ✓ 128 129 + Phase 5 (Properties) ✓ 130 Phase 6 (NodeInfo) ✓ 131 ``` 132 + 133 + ## Completed 134 + 135 + All phases are now complete. The library provides: 136 + - Full HTTP signature support (RFC 9421) 137 + - Activity delivery to inboxes 138 + - Outbox operations (create, like, boost, delete, update) 139 + - Follow protocol (follow, unfollow, accept, reject) 140 + - Question/poll activity support 141 + - NodeInfo discovery 142 + - Complete CLI with read and write operations 143 + - RFC 7033/7565 compliant WebFinger via the `webfinger` library

+35 -1

README.md

··· 8 - **JSON codecs**: Bidirectional encoding/decoding using jsont 9 - **Eio-based HTTP**: Direct-style concurrent I/O with connection pooling 10 - **HTTP Signatures**: RFC 9421 message signatures for authenticated federation 11 - - **Webfinger**: Actor discovery via RFC 7033 12 - **NodeInfo**: Server metadata discovery 0 13 14 ## Usage 15 ··· 50 ~actor:my_actor 51 ~content:"<p>Hello from OCaml!</p>" 52 () 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 53 ``` 54 55 ## Installation

··· 8 - **JSON codecs**: Bidirectional encoding/decoding using jsont 9 - **Eio-based HTTP**: Direct-style concurrent I/O with connection pooling 10 - **HTTP Signatures**: RFC 9421 message signatures for authenticated federation 11 + - **Webfinger**: Actor discovery via RFC 7033/7565 using the `webfinger` library 12 - **NodeInfo**: Server metadata discovery 13 + - **CLI Tool**: Command-line interface for interacting with ActivityPub servers 14 15 ## Usage 16 ··· 51 ~actor:my_actor 52 ~content:"<p>Hello from OCaml!</p>" 53 () 54 + ``` 55 + 56 + ## Command-Line Interface 57 + 58 + The `apub` command provides a CLI for interacting with ActivityPub servers: 59 + 60 + ```bash 61 + # Discover an actor via Webfinger 62 + apub webfinger gargron@mastodon.social 63 + 64 + # Fetch an actor's profile 65 + apub actor gargron@mastodon.social 66 + 67 + # Fetch an actor's outbox 68 + apub outbox gargron@mastodon.social 69 + 70 + # Post a note (requires signing) 71 + apub post --actor https://example.com/users/alice \ 72 + --key-file ~/.keys/alice.pem \ 73 + --key-id "https://example.com/users/alice#main-key" \ 74 + "Hello, Fediverse!" 75 + 76 + # Follow an actor 77 + apub follow --actor https://example.com/users/alice \ 78 + gargron@mastodon.social 79 + 80 + # Like a post 81 + apub like --actor https://example.com/users/alice \ 82 + https://mastodon.social/notes/123 83 + 84 + # Boost a post 85 + apub boost --actor https://example.com/users/alice \ 86 + https://mastodon.social/notes/123 87 ``` 88 89 ## Installation

+241

bin/apub.ml

··· 253 Cmd.v (Cmd.info "outbox" ~doc ~man) term 254 end 255 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 256 (* Main command group *) 257 let main_cmd = 258 let doc = "ActivityPub command-line client" in ··· 265 `Pre " apub webfinger anil@recoil.org"; 266 `Pre " apub actor anil@recoil.org"; 267 `Pre " apub outbox anil@recoil.org"; 0 0 0 0 268 ] in 269 let info = Cmd.info "apub" ~version:"0.1" ~doc ~man in 270 Cmd.group info [ 271 Webfinger_cmd.cmd; 272 Actor_cmd.cmd; 273 Outbox_cmd.cmd; 0 0 0 0 274 ] 275 276 let () = exit (Cmd.eval main_cmd)

··· 253 Cmd.v (Cmd.info "outbox" ~doc ~man) term 254 end 255 256 + (* Common signing options for write operations *) 257 + let key_file = 258 + let doc = "Path to PEM file containing the private key for signing." in 259 + Arg.(value & opt (some file) None & info ["key-file"; "k"] ~docv:"FILE" ~doc) 260 + 261 + let key_id = 262 + let doc = "Key ID for signing (usually your actor's publicKey.id URI)." in 263 + Arg.(value & opt (some string) None & info ["key-id"; "K"] ~docv:"URI" ~doc) 264 + 265 + let actor_uri = 266 + let doc = "Your actor URI (required for write operations)." in 267 + Arg.(value & opt (some string) None & info ["actor"; "a"] ~docv:"URI" ~doc) 268 + 269 + (* Helper to create a signed client *) 270 + let create_signed_client ~sw ~user_agent ~timeout env ~key_file ~key_id = 271 + match key_file, key_id with 272 + | Some kf, Some kid -> 273 + let pem = In_channel.with_open_bin kf In_channel.input_all in 274 + let signing = Apubt.Signing.from_pem_exn ~key_id:kid ~pem () in 275 + Apubt.create ~sw ~signing ~user_agent ~timeout env 276 + | _ -> Apubt.create ~sw ~user_agent ~timeout env 277 + 278 + (* Post command - create a note *) 279 + module Post_cmd = struct 280 + let content = 281 + let doc = "Content of the note to post (HTML allowed)." in 282 + Arg.(required & pos 0 (some string) None & info [] ~docv:"CONTENT" ~doc) 283 + 284 + let reply_to = 285 + let doc = "URI of the note to reply to." in 286 + Arg.(value & opt (some string) None & info ["reply-to"; "r"] ~docv:"URI" ~doc) 287 + 288 + let public = 289 + let doc = "Post publicly (default)." in 290 + Arg.(value & flag & info ["public"; "p"] ~doc) 291 + 292 + let followers_only = 293 + let doc = "Post to followers only." in 294 + Arg.(value & flag & info ["followers-only"; "f"] ~doc) 295 + 296 + let sensitive = 297 + let doc = "Mark as sensitive content." in 298 + Arg.(value & flag & info ["sensitive"; "s"] ~doc) 299 + 300 + let summary = 301 + let doc = "Content warning / summary text." in 302 + Arg.(value & opt (some string) None & info ["summary"; "w"] ~docv:"TEXT" ~doc) 303 + 304 + let run () timeout user_agent key_file key_id actor_uri content reply_to 305 + _public followers_only sensitive cw_summary = 306 + match actor_uri with 307 + | None -> 308 + Fmt.epr "Error: --actor is required for posting.@."; 309 + `Error (false, "Missing required option: --actor") 310 + | Some actor_uri_str -> 311 + Eio_main.run @@ fun env -> 312 + Eio.Switch.run @@ fun sw -> 313 + let client = create_signed_client ~sw ~user_agent ~timeout env ~key_file ~key_id in 314 + try 315 + let actor = Apubt.Actor.fetch client (Apubt.Proto.Uri.v actor_uri_str) in 316 + let in_reply_to = Option.map Apubt.Proto.Uri.v reply_to in 317 + let _summary = if sensitive then cw_summary else None in 318 + let activity = 319 + if followers_only then 320 + Apubt.Outbox.followers_only_note client ~actor ?in_reply_to ~content () 321 + else 322 + Apubt.Outbox.public_note client ~actor ?in_reply_to ~content () 323 + in 324 + let activity_id = Option.get (Apubt.Proto.Activity.id activity) in 325 + Fmt.pr "Posted: %s@." (Apubt.Proto.Uri.to_string activity_id); 326 + `Ok () 327 + with 328 + | Apubt.E err -> 329 + Fmt.epr "Error: %a@." Apubt.Error.pp err; 330 + `Error (false, Apubt.Error.to_string err) 331 + 332 + let term = 333 + Term.(ret (const run $ setup_log_term $ timeout $ user_agent $ key_file 334 + $ key_id $ actor_uri $ content $ reply_to $ public 335 + $ followers_only $ sensitive $ summary)) 336 + 337 + let cmd = 338 + let doc = "Post a note." in 339 + let man = [ 340 + `S Manpage.s_description; 341 + `P "Creates and posts a new note (status update)."; 342 + `P "Requires --actor and optionally --key-file/--key-id for signing."; 343 + `S Manpage.s_examples; 344 + `Pre " apub post --actor https://example.com/users/alice \"Hello world!\""; 345 + `Pre " apub post --actor https://example.com/users/alice --reply-to https://other.com/notes/123 \"Nice post!\""; 346 + `Pre " apub post --followers-only --actor https://example.com/users/alice \"Followers only content\""; 347 + ] in 348 + Cmd.v (Cmd.info "post" ~doc ~man) term 349 + end 350 + 351 + (* Follow command *) 352 + module Follow_cmd = struct 353 + let target = 354 + let doc = "Account to follow (user@domain or URI)." in 355 + Arg.(required & pos 0 (some string) None & info [] ~docv:"ACCOUNT" ~doc) 356 + 357 + let run () timeout user_agent key_file key_id actor_uri target = 358 + match actor_uri with 359 + | None -> 360 + Fmt.epr "Error: --actor is required for following.@."; 361 + `Error (false, "Missing required option: --actor") 362 + | Some actor_uri_str -> 363 + Eio_main.run @@ fun env -> 364 + Eio.Switch.run @@ fun sw -> 365 + let client = create_signed_client ~sw ~user_agent ~timeout env ~key_file ~key_id in 366 + try 367 + let actor = Apubt.Actor.fetch client (Apubt.Proto.Uri.v actor_uri_str) in 368 + let target_actor = 369 + if String.contains target '@' && not (String.starts_with ~prefix:"http" target) then 370 + Apubt.Actor.lookup client target 371 + else 372 + Apubt.Actor.fetch client (Apubt.Proto.Uri.v target) 373 + in 374 + let activity = Apubt.Actor.follow client ~actor ~target:target_actor in 375 + let activity_id = Option.get (Apubt.Proto.Activity.id activity) in 376 + Fmt.pr "Sent follow request: %s@." (Apubt.Proto.Uri.to_string activity_id); 377 + Fmt.pr "Target: %s (%s)@." 378 + (Option.value ~default:"" (Apubt.Proto.Actor.preferred_username target_actor)) 379 + (Apubt.Proto.Uri.to_string (Apubt.Proto.Actor.id target_actor)); 380 + `Ok () 381 + with 382 + | Apubt.E err -> 383 + Fmt.epr "Error: %a@." Apubt.Error.pp err; 384 + `Error (false, Apubt.Error.to_string err) 385 + 386 + let term = 387 + Term.(ret (const run $ setup_log_term $ timeout $ user_agent $ key_file 388 + $ key_id $ actor_uri $ target)) 389 + 390 + let cmd = 391 + let doc = "Follow an actor." in 392 + let man = [ 393 + `S Manpage.s_description; 394 + `P "Sends a Follow activity to another actor."; 395 + `P "Requires --actor for your identity. Use --key-file/--key-id for signing."; 396 + `S Manpage.s_examples; 397 + `Pre " apub follow --actor https://example.com/users/alice gargron@mastodon.social"; 398 + `Pre " apub follow --actor https://example.com/users/alice https://mastodon.social/users/Gargron"; 399 + ] in 400 + Cmd.v (Cmd.info "follow" ~doc ~man) term 401 + end 402 + 403 + (* Like command *) 404 + module Like_cmd = struct 405 + let object_uri = 406 + let doc = "URI of the object to like." in 407 + Arg.(required & pos 0 (some string) None & info [] ~docv:"URI" ~doc) 408 + 409 + let run () timeout user_agent key_file key_id actor_uri object_uri = 410 + match actor_uri with 411 + | None -> 412 + Fmt.epr "Error: --actor is required for liking.@."; 413 + `Error (false, "Missing required option: --actor") 414 + | Some actor_uri_str -> 415 + Eio_main.run @@ fun env -> 416 + Eio.Switch.run @@ fun sw -> 417 + let client = create_signed_client ~sw ~user_agent ~timeout env ~key_file ~key_id in 418 + try 419 + let actor = Apubt.Actor.fetch client (Apubt.Proto.Uri.v actor_uri_str) in 420 + let activity = Apubt.Outbox.like client ~actor ~object_:(Apubt.Proto.Uri.v object_uri) in 421 + let activity_id = Option.get (Apubt.Proto.Activity.id activity) in 422 + Fmt.pr "Liked: %s@." object_uri; 423 + Fmt.pr "Activity: %s@." (Apubt.Proto.Uri.to_string activity_id); 424 + `Ok () 425 + with 426 + | Apubt.E err -> 427 + Fmt.epr "Error: %a@." Apubt.Error.pp err; 428 + `Error (false, Apubt.Error.to_string err) 429 + 430 + let term = 431 + Term.(ret (const run $ setup_log_term $ timeout $ user_agent $ key_file 432 + $ key_id $ actor_uri $ object_uri)) 433 + 434 + let cmd = 435 + let doc = "Like an object." in 436 + let man = [ 437 + `S Manpage.s_description; 438 + `P "Sends a Like activity for the specified object (note, article, etc)."; 439 + `P "Requires --actor for your identity. Use --key-file/--key-id for signing."; 440 + `S Manpage.s_examples; 441 + `Pre " apub like --actor https://example.com/users/alice https://mastodon.social/notes/123"; 442 + ] in 443 + Cmd.v (Cmd.info "like" ~doc ~man) term 444 + end 445 + 446 + (* Boost command (Announce) *) 447 + module Boost_cmd = struct 448 + let object_uri = 449 + let doc = "URI of the object to boost." in 450 + Arg.(required & pos 0 (some string) None & info [] ~docv:"URI" ~doc) 451 + 452 + let run () timeout user_agent key_file key_id actor_uri object_uri = 453 + match actor_uri with 454 + | None -> 455 + Fmt.epr "Error: --actor is required for boosting.@."; 456 + `Error (false, "Missing required option: --actor") 457 + | Some actor_uri_str -> 458 + Eio_main.run @@ fun env -> 459 + Eio.Switch.run @@ fun sw -> 460 + let client = create_signed_client ~sw ~user_agent ~timeout env ~key_file ~key_id in 461 + try 462 + let actor = Apubt.Actor.fetch client (Apubt.Proto.Uri.v actor_uri_str) in 463 + let activity = Apubt.Outbox.announce client ~actor ~object_:(Apubt.Proto.Uri.v object_uri) in 464 + let activity_id = Option.get (Apubt.Proto.Activity.id activity) in 465 + Fmt.pr "Boosted: %s@." object_uri; 466 + Fmt.pr "Activity: %s@." (Apubt.Proto.Uri.to_string activity_id); 467 + `Ok () 468 + with 469 + | Apubt.E err -> 470 + Fmt.epr "Error: %a@." Apubt.Error.pp err; 471 + `Error (false, Apubt.Error.to_string err) 472 + 473 + let term = 474 + Term.(ret (const run $ setup_log_term $ timeout $ user_agent $ key_file 475 + $ key_id $ actor_uri $ object_uri)) 476 + 477 + let cmd = 478 + let doc = "Boost (announce/reblog) an object." in 479 + let man = [ 480 + `S Manpage.s_description; 481 + `P "Sends an Announce activity (boost/reblog) for the specified object."; 482 + `P "Requires --actor for your identity. Use --key-file/--key-id for signing."; 483 + `S Manpage.s_examples; 484 + `Pre " apub boost --actor https://example.com/users/alice https://mastodon.social/notes/123"; 485 + ] in 486 + Cmd.v (Cmd.info "boost" ~doc ~man) term 487 + end 488 + 489 (* Main command group *) 490 let main_cmd = 491 let doc = "ActivityPub command-line client" in ··· 498 `Pre " apub webfinger anil@recoil.org"; 499 `Pre " apub actor anil@recoil.org"; 500 `Pre " apub outbox anil@recoil.org"; 501 + `Pre " apub post --actor https://example.com/users/alice \"Hello world!\""; 502 + `Pre " apub follow --actor https://example.com/users/alice gargron@mastodon.social"; 503 + `Pre " apub like --actor https://example.com/users/alice https://mastodon.social/notes/123"; 504 + `Pre " apub boost --actor https://example.com/users/alice https://mastodon.social/notes/123"; 505 ] in 506 let info = Cmd.info "apub" ~version:"0.1" ~doc ~man in 507 Cmd.group info [ 508 Webfinger_cmd.cmd; 509 Actor_cmd.cmd; 510 Outbox_cmd.cmd; 511 + Post_cmd.cmd; 512 + Follow_cmd.cmd; 513 + Like_cmd.cmd; 514 + Boost_cmd.cmd; 515 ] 516 517 let () = exit (Cmd.eval main_cmd)

+77 -24

lib/client/apubt.ml

··· 195 end 196 197 module Webfinger = struct 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 198 let lookup t acct = 199 - (* Normalize account: remove acct: prefix if present *) 200 - let acct = 201 - if String.starts_with ~prefix:"acct:" acct then 202 - String.sub acct 5 (String.length acct - 5) 203 - else acct 0 0 0 0 0 204 in 205 - (* Extract domain from user@domain *) 206 - let domain = 207 - match String.split_on_char '@' acct with 208 - | [_; domain] -> domain 209 - | _ -> raise (E (Webfinger_error ("Invalid account format: " ^ acct))) 0 0 0 0 0 0 0 0 0 0 210 in 211 - (* Build Webfinger URL *) 212 - let url = Printf.sprintf "https://%s/.well-known/webfinger?resource=acct:%s" domain acct in 213 - let headers = 214 - Requests.Headers.empty 215 - |> Requests.Headers.add `Accept "application/jrd+json, application/json" 216 - in 217 - let resp = Requests.get t.requests ~headers url in 218 - check_response resp; 219 - Requests.Response.jsonv Proto.Webfinger.jsont resp 220 221 let actor_uri jrd = 222 match Proto.Webfinger.links jrd with 223 | None -> None 224 | Some links -> 225 List.find_map (fun link -> 226 - if Proto.Webfinger.Jrd_link.rel link = "self" then 227 match Proto.Webfinger.Jrd_link.type_ link with 228 | Some t when String.equal t "application/activity+json" -> 229 Proto.Webfinger.Jrd_link.href link ··· 233 else None 234 ) links 235 0 0 0 0 0 0 0 0 0 0 0 0 0 236 let profile_page jrd = 237 match Proto.Webfinger.links jrd with 238 | None -> None 239 | Some links -> 240 List.find_map (fun link -> 241 - if Proto.Webfinger.Jrd_link.rel link = "http://webfinger.net/rel/profile-page" then 242 Proto.Webfinger.Jrd_link.href link 243 else None 244 ) links ··· 248 | None -> None 249 | Some links -> 250 List.find_map (fun link -> 251 - if Proto.Webfinger.Jrd_link.rel link = "http://ostatus.org/schema/1.0/subscribe" then 252 Proto.Webfinger.Jrd_link.template link 253 else None 254 ) links ··· 327 Http.get_typed t Proto.Actor.jsont uri 328 329 let lookup t acct = 330 - let jrd = Webfinger.lookup t acct in 331 - match Webfinger.actor_uri jrd with 0 332 | Some uri -> fetch t uri 333 | None -> raise (E (Webfinger_error "No ActivityPub actor link in Webfinger response")) 334

··· 195 end 196 197 module Webfinger = struct 198 + (** Convert a webfinger library Jrd to our internal Proto.Webfinger type *) 199 + let jrd_of_webfinger (jrd : Webfinger.Jrd.t) : Proto.Webfinger.t = 200 + let links = List.map (fun (link : Webfinger.Link.t) -> 201 + Proto.Webfinger.Jrd_link.make 202 + ~rel:(Webfinger.Link.rel link) 203 + ?type_:(Webfinger.Link.type_ link) 204 + ?href:(Option.map Proto.Uri.v (Webfinger.Link.href link)) 205 + ?template:( 206 + (* Try to get template from properties if it exists *) 207 + Webfinger.Link.property ~uri:"template" link 208 + ) 209 + () 210 + ) (Webfinger.Jrd.links jrd) in 211 + let aliases = match Webfinger.Jrd.aliases jrd with 212 + | [] -> None 213 + | a -> Some a 214 + in 215 + let properties = match Webfinger.Jrd.properties jrd with 216 + | [] -> None 217 + | p -> Some (List.filter_map (fun (k, v) -> 218 + match v with Some s -> Some (k, s) | None -> None 219 + ) p) 220 + in 221 + Proto.Webfinger.make 222 + ~subject:(Option.value ~default:"" (Webfinger.Jrd.subject jrd)) 223 + ?aliases 224 + ?properties 225 + ~links 226 + () 227 + 228 let lookup t acct = 229 + (* Parse the account string into an Acct.t *) 230 + let acct_uri = 231 + (* Handle both "user@domain" and "acct:user@domain" formats *) 232 + let acct_str = 233 + if String.starts_with ~prefix:"acct:" acct then acct 234 + else "acct:" ^ acct 235 + in 236 + match Webfinger.Acct.of_string acct_str with 237 + | Ok a -> a 238 + | Error e -> raise (E (Webfinger_error (Webfinger.error_to_string e))) 239 in 240 + (* Use the webfinger library's query function *) 241 + match Webfinger.query_acct t.requests acct_uri () with 242 + | Ok jrd -> jrd_of_webfinger jrd 243 + | Error e -> raise (E (Webfinger_error (Webfinger.error_to_string e))) 244 + 245 + (** Look up using webfinger library and return the raw Webfinger.Jrd.t *) 246 + let lookup_raw t acct = 247 + let acct_uri = 248 + let acct_str = 249 + if String.starts_with ~prefix:"acct:" acct then acct 250 + else "acct:" ^ acct 251 + in 252 + match Webfinger.Acct.of_string acct_str with 253 + | Ok a -> a 254 + | Error e -> raise (E (Webfinger_error (Webfinger.error_to_string e))) 255 in 256 + match Webfinger.query_acct t.requests acct_uri () with 257 + | Ok jrd -> jrd 258 + | Error e -> raise (E (Webfinger_error (Webfinger.error_to_string e))) 0 0 0 0 0 0 259 260 let actor_uri jrd = 261 match Proto.Webfinger.links jrd with 262 | None -> None 263 | Some links -> 264 List.find_map (fun link -> 265 + if Proto.Webfinger.Jrd_link.rel link = Webfinger.Rel.activitypub then 266 match Proto.Webfinger.Jrd_link.type_ link with 267 | Some t when String.equal t "application/activity+json" -> 268 Proto.Webfinger.Jrd_link.href link ··· 272 else None 273 ) links 274 275 + (** Extract ActivityPub actor URI from a raw Webfinger.Jrd.t *) 276 + let actor_uri_raw (jrd : Webfinger.Jrd.t) : Proto.Uri.t option = 277 + (* Look for self link with ActivityPub media type *) 278 + match Webfinger.Jrd.find_link ~rel:Webfinger.Rel.activitypub jrd with 279 + | Some link -> 280 + (match Webfinger.Link.type_ link with 281 + | Some t when String.equal t "application/activity+json" -> 282 + Option.map Proto.Uri.v (Webfinger.Link.href link) 283 + | Some t when String.starts_with ~prefix:"application/ld+json" t -> 284 + Option.map Proto.Uri.v (Webfinger.Link.href link) 285 + | _ -> None) 286 + | None -> None 287 + 288 let profile_page jrd = 289 match Proto.Webfinger.links jrd with 290 | None -> None 291 | Some links -> 292 List.find_map (fun link -> 293 + if Proto.Webfinger.Jrd_link.rel link = Webfinger.Rel.profile then 294 Proto.Webfinger.Jrd_link.href link 295 else None 296 ) links ··· 300 | None -> None 301 | Some links -> 302 List.find_map (fun link -> 303 + if Proto.Webfinger.Jrd_link.rel link = Webfinger.Rel.subscribe then 304 Proto.Webfinger.Jrd_link.template link 305 else None 306 ) links ··· 379 Http.get_typed t Proto.Actor.jsont uri 380 381 let lookup t acct = 382 + (* Use the raw webfinger lookup for efficiency - avoids converting to Proto.Webfinger *) 383 + let jrd = Webfinger.lookup_raw t acct in 384 + match Webfinger.actor_uri_raw jrd with 385 | Some uri -> fetch t uri 386 | None -> raise (E (Webfinger_error "No ActivityPub actor link in Webfinger response")) 387

+31 -3

lib/client/apubt.mli

··· 171 (** {1 Webfinger Discovery} *) 172 173 (** Webfinger actor discovery per RFC 7033. 174 - @see <https://www.rfc-editor.org/rfc/rfc7033> *) 0 0 0 0 0 0 0 175 module Webfinger : sig 176 val lookup : t -> string -> Proto.Webfinger.t 177 (** [lookup client acct] performs a Webfinger lookup for the given account. 178 179 The [acct] can be in the form "user@domain" or "acct:user@domain". 0 0 0 0 0 0 0 0 0 180 181 @raise E on lookup failure *) 182 183 val actor_uri : Proto.Webfinger.t -> Proto.Uri.t option 184 (** [actor_uri jrd] extracts the ActivityPub actor URI from a Webfinger response. 185 186 - Looks for a link with [rel="self"] and [type="application/activity+json"]. *) 0 0 0 0 0 0 0 0 0 187 188 val profile_page : Proto.Webfinger.t -> Proto.Uri.t option 189 - (** [profile_page jrd] extracts the HTML profile page URI from a Webfinger response. *) 0 0 190 191 val subscribe_template : Proto.Webfinger.t -> string option 192 (** [subscribe_template jrd] extracts the subscribe/follow template URI. 193 0 194 This is used for remote follow buttons. The template contains [{uri}] 195 which should be replaced with the actor to follow. *) 196 end

··· 171 (** {1 Webfinger Discovery} *) 172 173 (** Webfinger actor discovery per RFC 7033. 174 + 175 + This module uses the [webfinger] library for robust RFC 7033/7565 compliance 176 + with proper acct URI handling and percent-encoding. See the 177 + {{:https://swicg.github.io/activitypub-webfinger/}ActivityPub WebFinger spec} 178 + for details on how WebFinger is used with ActivityPub. 179 + 180 + @see <https://www.rfc-editor.org/rfc/rfc7033> RFC 7033 WebFinger 181 + @see <https://www.rfc-editor.org/rfc/rfc7565> RFC 7565 acct URI *) 182 module Webfinger : sig 183 val lookup : t -> string -> Proto.Webfinger.t 184 (** [lookup client acct] performs a Webfinger lookup for the given account. 185 186 The [acct] can be in the form "user@domain" or "acct:user@domain". 187 + Uses the [webfinger] library for proper RFC 7565 acct URI handling. 188 + 189 + @raise E on lookup failure *) 190 + 191 + val lookup_raw : t -> string -> Webfinger.Jrd.t 192 + (** [lookup_raw client acct] performs a Webfinger lookup returning the raw JRD. 193 + 194 + This is more efficient when you only need to extract specific fields 195 + and don't need the full {!Proto.Webfinger.t} type. 196 197 @raise E on lookup failure *) 198 199 val actor_uri : Proto.Webfinger.t -> Proto.Uri.t option 200 (** [actor_uri jrd] extracts the ActivityPub actor URI from a Webfinger response. 201 202 + Looks for a link with [rel="self"] and [type="application/activity+json"] 203 + or [type="application/ld+json; profile=..."]. 204 + 205 + Per the ActivityPub WebFinger spec, publishers SHOULD include exactly one 206 + such link. *) 207 + 208 + val actor_uri_raw : Webfinger.Jrd.t -> Proto.Uri.t option 209 + (** [actor_uri_raw jrd] extracts the ActivityPub actor URI from a raw JRD. 210 + 211 + More efficient variant that works directly with {!Webfinger.Jrd.t}. *) 212 213 val profile_page : Proto.Webfinger.t -> Proto.Uri.t option 214 + (** [profile_page jrd] extracts the HTML profile page URI from a Webfinger response. 215 + 216 + Looks for [rel="http://webfinger.net/rel/profile-page"]. *) 217 218 val subscribe_template : Proto.Webfinger.t -> string option 219 (** [subscribe_template jrd] extracts the subscribe/follow template URI. 220 221 + Looks for [rel="http://ostatus.org/schema/1.0/subscribe"]. 222 This is used for remote follow buttons. The template contains [{uri}] 223 which should be replaced with the actor to follow. *) 224 end

+1 -1

lib/client/dune

··· 1 (library 2 (name apubt) 3 (public_name apubt) 4 - (libraries apubt_proto eio jsont jsont.bytesrw ptime.clock.os requests x509))

··· 1 (library 2 (name apubt) 3 (public_name apubt) 4 + (libraries apubt_proto eio jsont jsont.bytesrw ptime.clock.os requests webfinger x509))

+55 -8

lib/proto/apubt_proto.ml

··· 809 ?sensitive:bool -> 810 ?conversation:Uri.t -> 811 ?audience:Recipient.t list -> 0 0 812 unit -> t 0 813 814 val context : t -> Context.t option 815 val id : t -> Uri.t option ··· 841 val conversation : t -> Uri.t option 842 val audience : t -> Recipient.t list option 843 0 0 0 0 0 0 844 val jsont : t Jsont.t 0 845 end = struct 846 type t = { 847 context : Context.t option; ··· 873 sensitive : bool option; 874 conversation : Uri.t option; 875 audience : Recipient.t list option; 0 0 876 } 877 878 let make ?context ?id ~type_ ?name ?summary ?content ?media_type ?url 879 ?attributed_to ?in_reply_to ?published ?updated ?deleted ?to_ ?cc 880 ?bto ?bcc ?replies ?attachment ?tag ?generator ?icon ?image 881 - ?start_time ?end_time ?duration ?sensitive ?conversation ?audience () = 0 882 { context; id; type_; name; summary; content; media_type; url; 883 attributed_to; in_reply_to; published; updated; deleted; 884 to_; cc; bto; bcc; replies; attachment; tag; generator; 885 icon; image; start_time; end_time; duration; sensitive; 886 - conversation; audience } 887 888 let context t = t.context 889 let id t = t.id ··· 914 let sensitive t = t.sensitive 915 let conversation t = t.conversation 916 let audience t = t.audience 0 0 917 918 let jsont = 919 Jsont.Object.map ~kind:"Object" 920 (fun context id type_ name summary content media_type url attributed_to 921 in_reply_to published updated deleted to_ cc bto bcc replies 922 attachment tag generator icon image start_time end_time duration 923 - sensitive conversation audience -> 924 { context; id; type_; name; summary; content; media_type; url; 925 attributed_to; in_reply_to; published; updated; deleted; 926 to_; cc; bto; bcc; replies; attachment; tag; generator; 927 icon; image; start_time; end_time; duration; sensitive; 928 - conversation; audience }) 929 |> Jsont.Object.opt_mem "@context" Context.jsont ~enc:context 930 |> Jsont.Object.opt_mem "id" Uri.jsont ~enc:id 931 |> Jsont.Object.mem "type" Object_type.jsont ~enc:type_ ··· 959 |> Jsont.Object.opt_mem "sensitive" Jsont.bool ~enc:sensitive 960 |> Jsont.Object.opt_mem "conversation" Uri.jsont ~enc:conversation 961 |> Jsont.Object.opt_mem "audience" (one_or_many Recipient.jsont) ~enc:audience 0 0 962 |> Jsont.Object.finish 963 end 964 ··· 1175 ?published:Datetime.t -> 1176 ?updated:Datetime.t -> 1177 ?summary:string -> 0 0 0 1178 unit -> t 0 0 0 0 0 1179 1180 val context : t -> Context.t option 1181 val id : t -> Uri.t option ··· 1194 val updated : t -> Datetime.t option 1195 val summary : t -> string option 1196 0 0 0 0 0 0 0 0 0 1197 val jsont : t Jsont.t 0 1198 end = struct 1199 type t = { 1200 context : Context.t option; ··· 1213 published : Datetime.t option; 1214 updated : Datetime.t option; 1215 summary : string option; 0 0 0 1216 } 1217 1218 let make ?context ?id ~type_ ~actor ?object_ ?target ?result ?origin 1219 - ?instrument ?to_ ?cc ?bto ?bcc ?published ?updated ?summary () = 0 1220 { context; id; type_; actor; object_; target; result; origin; 1221 - instrument; to_; cc; bto; bcc; published; updated; summary } 0 1222 1223 let context t = t.context 1224 let id t = t.id ··· 1236 let published t = t.published 1237 let updated t = t.updated 1238 let summary t = t.summary 0 0 0 1239 1240 let jsont = 1241 Jsont.Object.map ~kind:"Activity" 1242 (fun context id type_ actor object_ target result origin instrument 1243 - to_ cc bto bcc published updated summary -> 1244 { context; id; type_; actor; object_; target; result; origin; 1245 - instrument; to_; cc; bto; bcc; published; updated; summary }) 0 1246 |> Jsont.Object.opt_mem "@context" Context.jsont ~enc:context 1247 |> Jsont.Object.opt_mem "id" Uri.jsont ~enc:id 1248 |> Jsont.Object.mem "type" Activity_type.jsont ~enc:type_ ··· 1259 |> Jsont.Object.opt_mem "published" Datetime.jsont ~enc:published 1260 |> Jsont.Object.opt_mem "updated" Datetime.jsont ~enc:updated 1261 |> Jsont.Object.opt_mem "summary" Jsont.string ~enc:summary 0 0 0 1262 |> Jsont.Object.finish 1263 end 1264

··· 809 ?sensitive:bool -> 810 ?conversation:Uri.t -> 811 ?audience:Recipient.t list -> 812 + ?location:Link_or_uri.t -> 813 + ?preview:Link_or_uri.t -> 814 unit -> t 815 + (** Create a new Object. *) 816 817 val context : t -> Context.t option 818 val id : t -> Uri.t option ··· 844 val conversation : t -> Uri.t option 845 val audience : t -> Recipient.t list option 846 847 + val location : t -> Link_or_uri.t option 848 + (** [location t] returns the physical or logical location associated with the object. *) 849 + 850 + val preview : t -> Link_or_uri.t option 851 + (** [preview t] returns a preview of the object, typically a smaller version. *) 852 + 853 val jsont : t Jsont.t 854 + (** JSON type for Objects. *) 855 end = struct 856 type t = { 857 context : Context.t option; ··· 883 sensitive : bool option; 884 conversation : Uri.t option; 885 audience : Recipient.t list option; 886 + location : Link_or_uri.t option; 887 + preview : Link_or_uri.t option; 888 } 889 890 let make ?context ?id ~type_ ?name ?summary ?content ?media_type ?url 891 ?attributed_to ?in_reply_to ?published ?updated ?deleted ?to_ ?cc 892 ?bto ?bcc ?replies ?attachment ?tag ?generator ?icon ?image 893 + ?start_time ?end_time ?duration ?sensitive ?conversation ?audience 894 + ?location ?preview () = 895 { context; id; type_; name; summary; content; media_type; url; 896 attributed_to; in_reply_to; published; updated; deleted; 897 to_; cc; bto; bcc; replies; attachment; tag; generator; 898 icon; image; start_time; end_time; duration; sensitive; 899 + conversation; audience; location; preview } 900 901 let context t = t.context 902 let id t = t.id ··· 927 let sensitive t = t.sensitive 928 let conversation t = t.conversation 929 let audience t = t.audience 930 + let location t = t.location 931 + let preview t = t.preview 932 933 let jsont = 934 Jsont.Object.map ~kind:"Object" 935 (fun context id type_ name summary content media_type url attributed_to 936 in_reply_to published updated deleted to_ cc bto bcc replies 937 attachment tag generator icon image start_time end_time duration 938 + sensitive conversation audience location preview -> 939 { context; id; type_; name; summary; content; media_type; url; 940 attributed_to; in_reply_to; published; updated; deleted; 941 to_; cc; bto; bcc; replies; attachment; tag; generator; 942 icon; image; start_time; end_time; duration; sensitive; 943 + conversation; audience; location; preview }) 944 |> Jsont.Object.opt_mem "@context" Context.jsont ~enc:context 945 |> Jsont.Object.opt_mem "id" Uri.jsont ~enc:id 946 |> Jsont.Object.mem "type" Object_type.jsont ~enc:type_ ··· 974 |> Jsont.Object.opt_mem "sensitive" Jsont.bool ~enc:sensitive 975 |> Jsont.Object.opt_mem "conversation" Uri.jsont ~enc:conversation 976 |> Jsont.Object.opt_mem "audience" (one_or_many Recipient.jsont) ~enc:audience 977 + |> Jsont.Object.opt_mem "location" Link_or_uri.jsont ~enc:location 978 + |> Jsont.Object.opt_mem "preview" Link_or_uri.jsont ~enc:preview 979 |> Jsont.Object.finish 980 end 981 ··· 1192 ?published:Datetime.t -> 1193 ?updated:Datetime.t -> 1194 ?summary:string -> 1195 + ?one_of:Object_ref.t list -> 1196 + ?any_of:Object_ref.t list -> 1197 + ?closed:Datetime.t -> 1198 unit -> t 1199 + (** Create a new Activity. 1200 + 1201 + The [one_of], [any_of], and [closed] fields are only used for Question 1202 + activities (polls). Use [one_of] for single-choice polls and [any_of] 1203 + for multiple-choice polls. *) 1204 1205 val context : t -> Context.t option 1206 val id : t -> Uri.t option ··· 1219 val updated : t -> Datetime.t option 1220 val summary : t -> string option 1221 1222 + val one_of : t -> Object_ref.t list option 1223 + (** [one_of t] returns single-choice poll options for Question activities. *) 1224 + 1225 + val any_of : t -> Object_ref.t list option 1226 + (** [any_of t] returns multiple-choice poll options for Question activities. *) 1227 + 1228 + val closed : t -> Datetime.t option 1229 + (** [closed t] returns when the poll was closed, for Question activities. *) 1230 + 1231 val jsont : t Jsont.t 1232 + (** JSON type for Activities. *) 1233 end = struct 1234 type t = { 1235 context : Context.t option; ··· 1248 published : Datetime.t option; 1249 updated : Datetime.t option; 1250 summary : string option; 1251 + one_of : Object_ref.t list option; 1252 + any_of : Object_ref.t list option; 1253 + closed : Datetime.t option; 1254 } 1255 1256 let make ?context ?id ~type_ ~actor ?object_ ?target ?result ?origin 1257 + ?instrument ?to_ ?cc ?bto ?bcc ?published ?updated ?summary 1258 + ?one_of ?any_of ?closed () = 1259 { context; id; type_; actor; object_; target; result; origin; 1260 + instrument; to_; cc; bto; bcc; published; updated; summary; 1261 + one_of; any_of; closed } 1262 1263 let context t = t.context 1264 let id t = t.id ··· 1276 let published t = t.published 1277 let updated t = t.updated 1278 let summary t = t.summary 1279 + let one_of t = t.one_of 1280 + let any_of t = t.any_of 1281 + let closed t = t.closed 1282 1283 let jsont = 1284 Jsont.Object.map ~kind:"Activity" 1285 (fun context id type_ actor object_ target result origin instrument 1286 + to_ cc bto bcc published updated summary one_of any_of closed -> 1287 { context; id; type_; actor; object_; target; result; origin; 1288 + instrument; to_; cc; bto; bcc; published; updated; summary; 1289 + one_of; any_of; closed }) 1290 |> Jsont.Object.opt_mem "@context" Context.jsont ~enc:context 1291 |> Jsont.Object.opt_mem "id" Uri.jsont ~enc:id 1292 |> Jsont.Object.mem "type" Activity_type.jsont ~enc:type_ ··· 1303 |> Jsont.Object.opt_mem "published" Datetime.jsont ~enc:published 1304 |> Jsont.Object.opt_mem "updated" Datetime.jsont ~enc:updated 1305 |> Jsont.Object.opt_mem "summary" Jsont.string ~enc:summary 1306 + |> Jsont.Object.opt_mem "oneOf" (Jsont.list Object_ref.jsont) ~enc:one_of 1307 + |> Jsont.Object.opt_mem "anyOf" (Jsont.list Object_ref.jsont) ~enc:any_of 1308 + |> Jsont.Object.opt_mem "closed" Datetime.jsont ~enc:closed 1309 |> Jsont.Object.finish 1310 end 1311

+25 -1

lib/proto/apubt_proto.mli

··· 362 ?sensitive:bool -> 363 ?conversation:Uri.t -> 364 ?audience:Recipient.t list -> 0 0 365 unit -> t 366 (** Create a new Object. *) 367 ··· 394 val sensitive : t -> bool option 395 val conversation : t -> Uri.t option 396 val audience : t -> Recipient.t list option 0 0 0 0 0 0 397 398 val jsont : t Jsont.t 399 (** JSON type for Objects. *) ··· 472 ?published:Datetime.t -> 473 ?updated:Datetime.t -> 474 ?summary:string -> 0 0 0 475 unit -> t 476 - (** Create a new Activity. *) 0 0 0 0 477 478 val context : t -> Context.t option 479 val id : t -> Uri.t option ··· 491 val published : t -> Datetime.t option 492 val updated : t -> Datetime.t option 493 val summary : t -> string option 0 0 0 0 0 0 0 0 0 494 495 val jsont : t Jsont.t 496 (** JSON type for Activities. *)

··· 362 ?sensitive:bool -> 363 ?conversation:Uri.t -> 364 ?audience:Recipient.t list -> 365 + ?location:Link_or_uri.t -> 366 + ?preview:Link_or_uri.t -> 367 unit -> t 368 (** Create a new Object. *) 369 ··· 396 val sensitive : t -> bool option 397 val conversation : t -> Uri.t option 398 val audience : t -> Recipient.t list option 399 + 400 + val location : t -> Link_or_uri.t option 401 + (** [location t] returns the physical or logical location associated with the object. *) 402 + 403 + val preview : t -> Link_or_uri.t option 404 + (** [preview t] returns a preview of the object, typically a smaller version. *) 405 406 val jsont : t Jsont.t 407 (** JSON type for Objects. *) ··· 480 ?published:Datetime.t -> 481 ?updated:Datetime.t -> 482 ?summary:string -> 483 + ?one_of:Object_ref.t list -> 484 + ?any_of:Object_ref.t list -> 485 + ?closed:Datetime.t -> 486 unit -> t 487 + (** Create a new Activity. 488 + 489 + The [one_of], [any_of], and [closed] fields are only used for Question 490 + activities (polls). Use [one_of] for single-choice polls and [any_of] 491 + for multiple-choice polls. *) 492 493 val context : t -> Context.t option 494 val id : t -> Uri.t option ··· 506 val published : t -> Datetime.t option 507 val updated : t -> Datetime.t option 508 val summary : t -> string option 509 + 510 + val one_of : t -> Object_ref.t list option 511 + (** [one_of t] returns single-choice poll options for Question activities. *) 512 + 513 + val any_of : t -> Object_ref.t list option 514 + (** [any_of t] returns multiple-choice poll options for Question activities. *) 515 + 516 + val closed : t -> Datetime.t option 517 + (** [closed t] returns when the poll was closed, for Question activities. *) 518 519 val jsont : t Jsont.t 520 (** JSON type for Activities. *)

+302

spec/activitypub-webfinger.html

··· 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

··· 1 + <!DOCTYPE html> 2 + <html> 3 + 4 + <head> 5 + <meta charset="utf-8" /> 6 + <title>ActivityPub and WebFinger</title> 7 + <script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove" defer></script> 8 + <script class="remove"> 9 + // All config options at https://respec.org/docs/ 10 + var respecConfig = { 11 + editors: [{ name: "a", url: "https://trwnh.com" }, { name: "Evan Prodromou", url: "https://evanp.me/" }], 12 + specStatus: "CG-FINAL", 13 + latestVersion: "https://www.w3.org/community/reports/socialcg/apwf/", 14 + xref: "web-platform", 15 + group: "socialcg", 16 + shortName: "apwf", 17 + github: "swicg/activitypub-webfinger", 18 + }; 19 + </script> 20 + </head> 21 + 22 + <body> 23 + <section id="abstract"> 24 + <p>Identifiers in ActivityPub tend to be HTTPS URIs. The use of WebFinger (as defined in [[RFC7033]]) allows for discovery of an actor's identifier given a username and a hostname, which may be more socially salient or otherwise easier to communicate across various contexts and media. The username and hostname are resolved at the WebFinger endpoint of the hostname in order to discover a link to an actor associated with the user's account, and that actor similarly can be back-linked to the username and hostname.</p> 25 + </section> 26 + <section id="sotd"> 27 + </section> 28 + <section class="informative" id="motivation"> 29 + <h2>Motivation</h2> 30 + <p>Consider an HTTPS URI of the form <code>https://social.example/actors/9c5b94b1-35ad-49bb-b118-8e8fc24abf80</code> being used as an identifier for an actor associated with a user account. Communicating this digitally may be done by simply using the HTTPS URI as-is, as a hyperlink reference. However, communicating this verbally or in a space-constrained visual format can be difficult. WebFinger allows communicating aliases of the form <code>alyssa@social.example</code>, which are easier to work with in the previously-cited cases.</p> 31 + <p>Additional benefits of using WebFinger include smoothing over the differences between varying actor URI schemas. Different softwares may provide human-friendly URLs for an actor's profile, but these URLs may take several different forms:</p> 32 + <ul> 33 + <li><code>https://social.example/alyssa</code></li> 34 + <li><code>https://social.example/@alyssa</code></li> 35 + <li><code>https://social.example/~alyssa</code></li> 36 + <li><code>https://social.example/u/alyssa</code></li> 37 + <li>...and so on.</li> 38 + </ul> 39 + <p>Conventionally, people can be identified by their user@domain address, while documents can be identified by their HTTPS location.</p> 40 + </section> 41 + <section class="normative" id="discovery"> 42 + <h2>Discovery</h2> 43 + <p>Discovery can occur in one of two directions:</p> 44 + <ul> 45 + <li>Given a WebFinger address, one can resolve it to an actor document;</li> 46 + <li>Given an actor document with a preferredUsername, one can reconstruct a WebFinger address that should link back to the same actor document.</li> 47 + </ul> 48 + <p>The former will be referred to as "forward discovery" and the latter will be referred to as "reverse discovery".</p> 49 + <section id="forward-discovery"> 50 + <h3>Forward discovery of an actor document given a WebFinger address</h3> 51 + <p>Given a username and hostname in the form <code>user@domain</code>:</p> 52 + <ol> 53 + <li>Construct an <code>acct:</code> URI of the form <code>acct:user@domain</code> (as defined in [[RFC7565]])</li> 54 + <li>Make an HTTP GET request to that hostname's WebFinger well-known endpoint, using the <code>acct:</code> URI as the value of the <code>resource</code> query parameter (as described in [[RFC7033]])</li> 55 + </ol> 56 + <p>For example, the WebFinger address <code>alyssa@social.example</code> can be resolved as a resource by making an HTTP GET request for <code>https://social.example/.well-known/webfinger?resource=acct:alyssa@social.example</code> (which is <code>https://social.example/.well-known/webfinger?resource=acct:alyssa%40social.example</code> when percent-encoded). This request MAY result in an HTTP 3xx redirect, in which case the redirect MUST be followed to the <code>Location</code> header's value, which MUST be an <code>https:</code> URI per [[RFC7033]]. (Subsequent redirects SHOULD be followed, up until a maximum redirect limit at the discretion of the requester.) The final request MUST return a JRD (JSON Resource Descriptor, as defined in [[RFC6415]]) with <code>application/jrd+json</code> as the content type (assuming no specified <code>Accept</code> header).</p> 57 + <p>The WebFinger request and response may look like this:</p> 58 + <pre class="http example" title="Sample WebFinger request and JRD response"> 59 + GET /.well-known/webfinger?resource=acct:alyssa%40social.example HTTP/1.1 60 + Host: social.example 61 + 62 + HTTP/1.1 307 Temporary Redirect 63 + Location: https://social.example/jrd/alyssa 64 + 65 + GET /jrd/alyssa HTTP/1.1 66 + Host: social.example 67 + 68 + HTTP/1.1 200 OK 69 + Content-Type: application/jrd+json 70 + 71 + { 72 + "subject": "acct:alyssa@social.example", 73 + "aliases": [ 74 + "https://social.example/@alyssa", 75 + "https://social.example/actors/9c5b94b1-35ad-49bb-b118-8e8fc24abf80" 76 + ], 77 + "links": [ 78 + { 79 + "rel": "http://webfinger.net/rel/profile-page", 80 + "type": "text/html", 81 + "href": "https://social.example/@alyssa" 82 + }, 83 + { 84 + "rel": "self", 85 + "type": "application/activity+json", 86 + "href": "https://social.example/actors/9c5b94b1-35ad-49bb-b118-8e8fc24abf80" 87 + } 88 + ] 89 + } 90 + </pre> 91 + <p>At this point, you can parse for the <code>href</code> of the element of <code>links</code> that has a <code>rel</code> of <code>self</code> and a <code>type</code> of either <code>application/ld+json; profile="https://www.w3.org/ns/activitystreams"</code> or <code>application/activity+json</code> (depending on the implementation). See <a href="#link"></a> for more information about this.</p> 92 + </section> 93 + <section id="reverse-discovery"> 94 + <h3>Reverse discovery of a WebFinger address given an actor document</h3> 95 + <p>Given an actor with an <code>id</code> and a <code>preferredUsername</code>:</p> 96 + <ol> 97 + <li>Take the hostname of the <code>id</code> to discover the WebFinger domain</li> 98 + <li>Combine the <code>preferredUsername</code> and the WebFinger domain in order to form a WebFinger address</li> 99 + <li>Verify that this WebFinger address links back to the same actor when performing discovery as described in <a href="#forward-discovery"></a></li> 100 + <li>Optionally: If the JRD from the previous step has a <code>subject</code> and it contains an <code>acct:</code> URI different from the one you constructed, perform a verification discovery against that <code>acct:</code> URI afterward. (In such cases, the <code>subject</code> of the JRD denotes the expected canonical identifier.)</li> 101 + </ol> 102 + <p>For example, given an actor document at <code>https://activitypub.example.com/actor/1</code> like so:</p> 103 + <pre class="json example" title="Sample actor document"> 104 + { 105 + "@context": "https://www.w3.org/ns/activitystreams", 106 + "id": "https://activitypub.example.com/actor/1", 107 + "preferredUsername": "alice", 108 + "name": "Alice P. Hacker" 109 + } 110 + </pre> 111 + <p>The reverse discovery process would extract <code>alice</code> and <code>activitypub.example.com</code>, construct the <code>acct:</code> URI <code>acct:alice@activitypub.example.com</code>, then request <code>https://activitypub.example.com/.well-known/webfinger?resource=acct:alice@activitypub.example.com</code> like so:</p> 112 + <pre class="http example" title="Verifying the constructed WebFinger address"> 113 + GET /.well-known/webfinger?resource=acct:alice@activitypub.example.com HTTP/1.1 114 + Host: activitypub.example.com 115 + 116 + HTTP/1.1 200 OK 117 + Content-Type: application/jrd+json 118 + 119 + { 120 + "subject": "acct:alice@example.com", 121 + "aliases": [ 122 + "https://example.com/@alice", 123 + "https://activitypub.example.com/actors/1" 124 + ], 125 + "links": [ 126 + { 127 + "rel": "http://webfinger.net/rel/profile-page", 128 + "type": "text/html", 129 + "href": "https://example.com/@alice" 130 + }, 131 + { 132 + "rel": "self", 133 + "type": "application/ld+json; profile=\"https://www.w3.org/ns/activitystreams\"", 134 + "href": "https://activitypub.example.com/actors/1" 135 + } 136 + ] 137 + } 138 + </pre> 139 + <p>At this point, we have validated that <code>alice@activitypub.example.com</code> links back to our actor document, but we can optionally verify that the canonical WebFinger address of <code>alice@example.com</code> also links back to the same actor document:</p> 140 + <pre class="http example" title="Verifying the canonical WebFinger address discovered from the constructed WebFinger address"> 141 + GET /.well-known/webfinger?resource=acct:alice@example.com HTTP/1.1 142 + Host: example.com 143 + 144 + HTTP/1.1 307 Temporary Redirect 145 + Location: https://activitypub.example.com/.well-known/webfinger?resource=acct:alice@example.com 146 + 147 + GET /.well-known/webfinger?resource=acct:alice@example.com HTTP/1.1 148 + Host: activitypub.example.com 149 + 150 + HTTP/1.1 200 OK 151 + Content-Type: application/jrd+json 152 + 153 + { 154 + "subject": "acct:alice@example.com", 155 + "aliases": [ 156 + "https://example.com/@alice", 157 + "https://activitypub.example.com/actors/1" 158 + ], 159 + "links": [ 160 + { 161 + "rel": "http://webfinger.net/rel/profile-page", 162 + "type": "text/html", 163 + "href": "https://example.com/@alice" 164 + }, 165 + { 166 + "rel": "self", 167 + "type": "application/ld+json; profile=\"https://www.w3.org/ns/activitystreams\"", 168 + "href": "https://activitypub.example.com/actors/1" 169 + } 170 + ] 171 + } 172 + </pre> 173 + </section> 174 + </section> 175 + <section class="normative" id="encoding"> 176 + <h2>Encoding</h2> 177 + <p>To ensure smooth operation of the WebFinger discovery flows, identifiers and responses should follow certain guidelines for encoding.</p> 178 + <section class="normative" id="names"> 179 + <h3>Limitations on usernames and hostnames</h3> 180 + <p>The <code>acct:</code> URI scheme is defined in [[RFC7565]], which contains ABNF ([[RFC5234]]) for allowed characters (inheriting from [[RFC3986]] as well):</p> 181 + <pre class="abnf" title="acct: URI ABNF"> 182 + acctURI = "acct" ":" userpart "@" host 183 + userpart = unreserved / sub-delims 184 + 0*( unreserved / pct-encoded / sub-delims ) 185 + ; userpart regex: [A-Za-z0-9\-\.\_\~\!\$\&\'\(\)\*\+\,\;\=](?:[A-Za-z0-9\-\.\_\~\!\$\&\'\(\)\*\+\,\;\=]|(?:%[0-9A-Fa-f]{2}))* 186 + unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 187 + sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "=" 188 + pct-encoded = "%" HEXDIG HEXDIG 189 + 190 + host = IP-literal / IPv4address / reg-name 191 + reg-name = *( unreserved / pct-encoded / sub-delims ) 192 + ; reg-name regex: (?:[A-Za-z0-9\-\.\_\~\!\$\&\'\(\)\*\+\,\;\=]|(?:%[0-9A-Fa-f]{2}))* 193 + </pre> 194 + <p>Further restrictions are specified in [[RFC7565]]:</p> 195 + <ul> 196 + <li>Per [[RFC3986]] Section 6.2.2.1 "Case Normalization", the scheme and host are case-insensitive and SHOULD therefore be normalized to lowercase.</li> 197 + <li>Per [[RFC3986]] Section 6.2.2.2 "Percent-Encoding Normalization", any <code>unreserved</code> characters SHOULD be decoded if encountered as a percent-encoded octet.</li> 198 + <li>Before percent-encoding anything, the userpart MUST consist only of Unicode code points that are part of the [[RFC7564]] PRECIS <code>IdentifierClass</code> 199 + </li> 200 + <li>Before percent-encoding anything, the hostname MUST conform to IDNA rules specified in [[RFC5982]] and [[RFC5980]] for A-label (ASCII-Compatible Encoding, or Punycode)</li> 201 + </ul> 202 + <section class="informative" id="rules"> 203 + <h4>Current implementation rules</h4> 204 + <p>Note that while there are several symbols allowed in the userpart, the de facto limits set by some current implementers are much more restrictive.</p> 205 + <p>At the time of this writing, Mastodon enforces the following rules:</p> 206 + <ul> 207 + <li>The username must be at least one character</li> 208 + <li>ASCII alphanumeric characters (<code>A</code> through <code>Z</code>, <code>a</code> through <code>z</code>, <code>0</code> through <code>9</code>) and underscores (<code>_</code>) are generally allowed anywhere in the username</li> 209 + <li>Dots (<code>.</code>) and dashes (<code>-</code>) are allowed in the middle of a username, but not as the first character or the last character</li> 210 + <li>All other symbols are disallowed</li> 211 + <li>Usernames are case-insensitive</li> 212 + </ul> 213 + <p>In other words, Mastodon will accept the regular expression or the following ABNF:</p> 214 + <pre class="abnf" title="Mastodon username ABNF"> 215 + ; As a regular expression, this can be expressed as follows: 216 + ; /[a-z0-9_]+([a-z0-9_.-]+[a-z0-9_]+)?/i 217 + 218 + username = word 219 + *( rest ) 220 + word = ALPHA / DIGIT / "_" 221 + rest = *( extended ) 222 + word 223 + extended = word / "." / "-" 224 + </pre> 225 + <p>Similarly at the time of this writing, Misskey is subject to the following limitations:</p> 226 + <ul> 227 + <li>Usernames are limited to 128 characters</li> 228 + <li>Hostnames are limited to 128 characters</li> 229 + </ul> 230 + </section> 231 + <section class="normative" id="usernames"> 232 + <h4>Recommendations for handling usernames</h4> 233 + <ul> 234 + <li>Implementers SHOULD treat local usernames as case-insensitive.</li> 235 + <li>Implementers SHOULD NOT assume case insensitivity for external usernames.</li> 236 + <li>Implementers SHOULD NOT treat usernames as stable identifiers that will always map to the same actor, and SHOULD use the actor <code>id</code> in any references to an actor. (Implementers that currently treat usernames as canonical identifiers SHOULD take steps to avoid doing so in the future.)</li> 237 + <li>Implementers SHOULD limit the length of local usernames. The exact limit is not specified, but it is noteworthy that similar systems such as email often limit the localpart to 64 characters (per [[RFC2821]]).</li> 238 + <li>Implementers SHOULD support remote usernames containing valid characters per [[RFC7565]]. For short-term compatibility, implementers SHOULD NOT use characters other than alphanumeric (<code>A-Z, a-z, 0-9</code>) and underscores (<code>_</code>).</li> 239 + </ul> 240 + </section> 241 + </section> 242 + <section class="normative" id="link"> 243 + <h3>Establishing a link between the WebFinger resource and the actor document</h3> 244 + <p>As discussed in <a href="#forward-discovery"></a>, the link to the actor associated with a given WebFinger address will have the following qualifiers:</p> 245 + <ul> 246 + <li><code>rel</code> MUST be <code>self</code></li> 247 + <li><code>type</code> MUST be either <code>application/activity+json</code> or <code>application/ld+json; profile="https://www.w3.org/ns/activitystreams"</code></li> 248 + </ul> 249 + <p>Publishers SHOULD include only one such link.</p> 250 + <p>Due to the prevailing use of WebFinger addresses as canonical primary identifiers for users, implementations that require WebFinger for compatibility will often also deduplicate actors based on the WebFinger address. Therefore, it is generally expected that there is only one <code>self</code> link to an Activity Streams document, in a unary relationship. However, some implementations do not follow this expectation, and there might be multiple links to ActivityStreams documents for the same WebFinger <code>acct:</code> resource. In such cases, one of the following strategies may be employed:</p> 251 + <ul> 252 + <li>Take the first matching entry in `links`</li> 253 + <li>Deduplicate all matching entries in `links` by their `href`</li> 254 + <li>Check for additional information, such as the presence of `properties` which may give further hints as to which entry of `links` is appropriate to follow</li> 255 + </ul> 256 + </section> 257 + </section> 258 + <section class="informative" id="other"> 259 + <h3>Other uses of WebFinger</h3> 260 + <p>Aside from the self-link to the associated actor, resolving a WebFinger query may expose some other links of potential interest. The following link relations are currently common among WebFinger implementers, and are recommended for use especially when the actor document is not publicly available:</p> 261 + <ul> 262 + <li><code>http://webfinger.net/rel/profile-page</code> (for quickly getting the HTML profile page of a user without resolving their actor document and checking for the <code>url</code>)</li> 263 + <li><code>http://webfinger.net/rel/avatar</code> (for quickly getting the avatar of a user without resolving their actor document and checking for the <code>icon</code>)</li> 264 + </ul> 265 + <p>The following link relations are less common, but offer useful information to ActivityPub implementers:</p> 266 + <ul> 267 + <li><code>http://ostatus.org/schema/1.0/subscribe</code> (used to power features like Mastodon's remote follow buttons)</li> 268 + <li><code>http://schemas.google.com/g/2010#updates-from</code> (used by some implementations to link to an Atom feed)</li> 269 + <li><code>feed</code> (used by some implementations to link to one or more feeds; feeds can be disambiguated by checking <code>type</code> and/or <code>title</code> properties of the link)</li> 270 + <li><code>http://a9.com/-/spec/opensearch/1.1/</code> (for custom search bars)</li> 271 + </ul> 272 + <p>Also uncommon but supported by at least one implementation (WordPress) is the ability to query non-actor, non-user resources via WebFinger. The following link relations are exposed:</p> 273 + <ul> 274 + <li><code>shortlink</code></li> 275 + <li><code>author</code></li> 276 + <li><code>alternate</code></li> 277 + <li><code>license</code></li> 278 + <li><code>canonical</code></li> 279 + <li><code>webmention</code></li> 280 + </ul> 281 + </section> 282 + <section class="informative" id="security"> 283 + <h2>Security Considerations</h2> 284 + <p>Using WebFinger can provide proof of existence of an associated actor document, as well as make it easier to discover that associated actor document; following this, an actor's inbox can be likewise discovered, and spam or other unwanted messages can be delivered to that actor's inbox. It may be desirable for some systems to not publicly expose an actor's existence and instead rely on the user manually entering their actor's HTTPS URI, or maintaining a "contact list" of bookmarked actors or resources. For such systems, the use of WebFinger is not advisable.</p> 285 + <p>WebFinger allows for the lookup request to redirect; this primarily allows a web host or origin to defer or delegate their WebFinger lookups to a separate WebFinger service, but it can also create an issue when there are multiple redirects. For this reason, anyone making a WebFinger request should take care to limit the maximum number of redirects that they follow.</p> 286 + </section> 287 + <section class="informative" id="future"> 288 + <h2>Future Enhancements</h2> 289 + <p>The current use of WebFinger with ActivityPub could be improved in several ways:</p> 290 + <ul> 291 + <li>Back-linking an actor to a WebFinger address could be more explicit. Current use of <code>preferredUsername</code> is not ideal for constructing WebFinger addresses, and it also does not allow for expressing actual "preferred usernames". An explicit property for denoting the user's "canonical" WebFinger address would ease reverse-discovery concerns.</li> 292 + <li>Implementers could ease their de facto WebFinger requirements by treating WebFinger addresses purely as aliases for the actor's HTTPS identifier, rather than as the canonical identifier. This would make WebFinger address mappings mutable and no longer unary.</li> 293 + <li>WebFinger could be used to expose certain properties or qualified links more directly, skipping the resolution of the actor resource.</li> 294 + <li>An ActivityStreams profile of WebFinger can be defined in order to redirect or directly resolve the actor document if the <code>Accept</code> header specifies the correct media type, skipping the resolution of the JRD.</li> 295 + <li>A convention could be adopted for identifying users by a DNS name instead of an acct: URI.</li> 296 + </ul> 297 + </section> 298 + <section id="conformance"> 299 + </section> 300 + </body> 301 + 302 + </html>