+36 -16

PLAN.md

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

+35 -1

README.md

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

+241

bin/apub.ml

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

+77 -24

lib/client/apubt.ml

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

+31 -3

lib/client/apubt.mli

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

+1 -1

lib/client/dune

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

+55 -8

lib/proto/apubt_proto.ml

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

+25 -1

lib/proto/apubt_proto.mli

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

+302

spec/activitypub-webfinger.html

··· 1 1 + <!DOCTYPE html> 2 2 + <html> 3 3 + 4 4 + <head> 5 5 + <meta charset="utf-8" /> 6 6 + <title>ActivityPub and WebFinger</title> 7 7 + <script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove" defer></script> 8 8 + <script class="remove"> 9 9 + // All config options at https://respec.org/docs/ 10 10 + var respecConfig = { 11 11 + editors: [{ name: "a", url: "https://trwnh.com" }, { name: "Evan Prodromou", url: "https://evanp.me/" }], 12 12 + specStatus: "CG-FINAL", 13 13 + latestVersion: "https://www.w3.org/community/reports/socialcg/apwf/", 14 14 + xref: "web-platform", 15 15 + group: "socialcg", 16 16 + shortName: "apwf", 17 17 + github: "swicg/activitypub-webfinger", 18 18 + }; 19 19 + </script> 20 20 + </head> 21 21 + 22 22 + <body> 23 23 + <section id="abstract"> 24 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 25 + </section> 26 26 + <section id="sotd"> 27 27 + </section> 28 28 + <section class="informative" id="motivation"> 29 29 + <h2>Motivation</h2> 30 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 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 32 + <ul> 33 33 + <li><code>https://social.example/alyssa</code></li> 34 34 + <li><code>https://social.example/@alyssa</code></li> 35 35 + <li><code>https://social.example/~alyssa</code></li> 36 36 + <li><code>https://social.example/u/alyssa</code></li> 37 37 + <li>...and so on.</li> 38 38 + </ul> 39 39 + <p>Conventionally, people can be identified by their user@domain address, while documents can be identified by their HTTPS location.</p> 40 40 + </section> 41 41 + <section class="normative" id="discovery"> 42 42 + <h2>Discovery</h2> 43 43 + <p>Discovery can occur in one of two directions:</p> 44 44 + <ul> 45 45 + <li>Given a WebFinger address, one can resolve it to an actor document;</li> 46 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 47 + </ul> 48 48 + <p>The former will be referred to as "forward discovery" and the latter will be referred to as "reverse discovery".</p> 49 49 + <section id="forward-discovery"> 50 50 + <h3>Forward discovery of an actor document given a WebFinger address</h3> 51 51 + <p>Given a username and hostname in the form <code>user@domain</code>:</p> 52 52 + <ol> 53 53 + <li>Construct an <code>acct:</code> URI of the form <code>acct:user@domain</code> (as defined in [[RFC7565]])</li> 54 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 55 + </ol> 56 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 57 + <p>The WebFinger request and response may look like this:</p> 58 58 + <pre class="http example" title="Sample WebFinger request and JRD response"> 59 59 + GET /.well-known/webfinger?resource=acct:alyssa%40social.example HTTP/1.1 60 60 + Host: social.example 61 61 + 62 62 + HTTP/1.1 307 Temporary Redirect 63 63 + Location: https://social.example/jrd/alyssa 64 64 + 65 65 + GET /jrd/alyssa HTTP/1.1 66 66 + Host: social.example 67 67 + 68 68 + HTTP/1.1 200 OK 69 69 + Content-Type: application/jrd+json 70 70 + 71 71 + { 72 72 + "subject": "acct:alyssa@social.example", 73 73 + "aliases": [ 74 74 + "https://social.example/@alyssa", 75 75 + "https://social.example/actors/9c5b94b1-35ad-49bb-b118-8e8fc24abf80" 76 76 + ], 77 77 + "links": [ 78 78 + { 79 79 + "rel": "http://webfinger.net/rel/profile-page", 80 80 + "type": "text/html", 81 81 + "href": "https://social.example/@alyssa" 82 82 + }, 83 83 + { 84 84 + "rel": "self", 85 85 + "type": "application/activity+json", 86 86 + "href": "https://social.example/actors/9c5b94b1-35ad-49bb-b118-8e8fc24abf80" 87 87 + } 88 88 + ] 89 89 + } 90 90 + </pre> 91 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 92 + </section> 93 93 + <section id="reverse-discovery"> 94 94 + <h3>Reverse discovery of a WebFinger address given an actor document</h3> 95 95 + <p>Given an actor with an <code>id</code> and a <code>preferredUsername</code>:</p> 96 96 + <ol> 97 97 + <li>Take the hostname of the <code>id</code> to discover the WebFinger domain</li> 98 98 + <li>Combine the <code>preferredUsername</code> and the WebFinger domain in order to form a WebFinger address</li> 99 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 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 101 + </ol> 102 102 + <p>For example, given an actor document at <code>https://activitypub.example.com/actor/1</code> like so:</p> 103 103 + <pre class="json example" title="Sample actor document"> 104 104 + { 105 105 + "@context": "https://www.w3.org/ns/activitystreams", 106 106 + "id": "https://activitypub.example.com/actor/1", 107 107 + "preferredUsername": "alice", 108 108 + "name": "Alice P. Hacker" 109 109 + } 110 110 + </pre> 111 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 112 + <pre class="http example" title="Verifying the constructed WebFinger address"> 113 113 + GET /.well-known/webfinger?resource=acct:alice@activitypub.example.com HTTP/1.1 114 114 + Host: activitypub.example.com 115 115 + 116 116 + HTTP/1.1 200 OK 117 117 + Content-Type: application/jrd+json 118 118 + 119 119 + { 120 120 + "subject": "acct:alice@example.com", 121 121 + "aliases": [ 122 122 + "https://example.com/@alice", 123 123 + "https://activitypub.example.com/actors/1" 124 124 + ], 125 125 + "links": [ 126 126 + { 127 127 + "rel": "http://webfinger.net/rel/profile-page", 128 128 + "type": "text/html", 129 129 + "href": "https://example.com/@alice" 130 130 + }, 131 131 + { 132 132 + "rel": "self", 133 133 + "type": "application/ld+json; profile=\"https://www.w3.org/ns/activitystreams\"", 134 134 + "href": "https://activitypub.example.com/actors/1" 135 135 + } 136 136 + ] 137 137 + } 138 138 + </pre> 139 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 140 + <pre class="http example" title="Verifying the canonical WebFinger address discovered from the constructed WebFinger address"> 141 141 + GET /.well-known/webfinger?resource=acct:alice@example.com HTTP/1.1 142 142 + Host: example.com 143 143 + 144 144 + HTTP/1.1 307 Temporary Redirect 145 145 + Location: https://activitypub.example.com/.well-known/webfinger?resource=acct:alice@example.com 146 146 + 147 147 + GET /.well-known/webfinger?resource=acct:alice@example.com HTTP/1.1 148 148 + Host: activitypub.example.com 149 149 + 150 150 + HTTP/1.1 200 OK 151 151 + Content-Type: application/jrd+json 152 152 + 153 153 + { 154 154 + "subject": "acct:alice@example.com", 155 155 + "aliases": [ 156 156 + "https://example.com/@alice", 157 157 + "https://activitypub.example.com/actors/1" 158 158 + ], 159 159 + "links": [ 160 160 + { 161 161 + "rel": "http://webfinger.net/rel/profile-page", 162 162 + "type": "text/html", 163 163 + "href": "https://example.com/@alice" 164 164 + }, 165 165 + { 166 166 + "rel": "self", 167 167 + "type": "application/ld+json; profile=\"https://www.w3.org/ns/activitystreams\"", 168 168 + "href": "https://activitypub.example.com/actors/1" 169 169 + } 170 170 + ] 171 171 + } 172 172 + </pre> 173 173 + </section> 174 174 + </section> 175 175 + <section class="normative" id="encoding"> 176 176 + <h2>Encoding</h2> 177 177 + <p>To ensure smooth operation of the WebFinger discovery flows, identifiers and responses should follow certain guidelines for encoding.</p> 178 178 + <section class="normative" id="names"> 179 179 + <h3>Limitations on usernames and hostnames</h3> 180 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 181 + <pre class="abnf" title="acct: URI ABNF"> 182 182 + acctURI = "acct" ":" userpart "@" host 183 183 + userpart = unreserved / sub-delims 184 184 + 0*( unreserved / pct-encoded / sub-delims ) 185 185 + ; userpart regex: [A-Za-z0-9\-\.\_\~\!\$\&\'\(\)\*\+\,\;\=](?:[A-Za-z0-9\-\.\_\~\!\$\&\'\(\)\*\+\,\;\=]|(?:%[0-9A-Fa-f]{2}))* 186 186 + unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 187 187 + sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "=" 188 188 + pct-encoded = "%" HEXDIG HEXDIG 189 189 + 190 190 + host = IP-literal / IPv4address / reg-name 191 191 + reg-name = *( unreserved / pct-encoded / sub-delims ) 192 192 + ; reg-name regex: (?:[A-Za-z0-9\-\.\_\~\!\$\&\'\(\)\*\+\,\;\=]|(?:%[0-9A-Fa-f]{2}))* 193 193 + </pre> 194 194 + <p>Further restrictions are specified in [[RFC7565]]:</p> 195 195 + <ul> 196 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 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 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 199 + </li> 200 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 201 + </ul> 202 202 + <section class="informative" id="rules"> 203 203 + <h4>Current implementation rules</h4> 204 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 205 + <p>At the time of this writing, Mastodon enforces the following rules:</p> 206 206 + <ul> 207 207 + <li>The username must be at least one character</li> 208 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 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 210 + <li>All other symbols are disallowed</li> 211 211 + <li>Usernames are case-insensitive</li> 212 212 + </ul> 213 213 + <p>In other words, Mastodon will accept the regular expression or the following ABNF:</p> 214 214 + <pre class="abnf" title="Mastodon username ABNF"> 215 215 + ; As a regular expression, this can be expressed as follows: 216 216 + ; /[a-z0-9_]+([a-z0-9_.-]+[a-z0-9_]+)?/i 217 217 + 218 218 + username = word 219 219 + *( rest ) 220 220 + word = ALPHA / DIGIT / "_" 221 221 + rest = *( extended ) 222 222 + word 223 223 + extended = word / "." / "-" 224 224 + </pre> 225 225 + <p>Similarly at the time of this writing, Misskey is subject to the following limitations:</p> 226 226 + <ul> 227 227 + <li>Usernames are limited to 128 characters</li> 228 228 + <li>Hostnames are limited to 128 characters</li> 229 229 + </ul> 230 230 + </section> 231 231 + <section class="normative" id="usernames"> 232 232 + <h4>Recommendations for handling usernames</h4> 233 233 + <ul> 234 234 + <li>Implementers SHOULD treat local usernames as case-insensitive.</li> 235 235 + <li>Implementers SHOULD NOT assume case insensitivity for external usernames.</li> 236 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 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 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 239 + </ul> 240 240 + </section> 241 241 + </section> 242 242 + <section class="normative" id="link"> 243 243 + <h3>Establishing a link between the WebFinger resource and the actor document</h3> 244 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 245 + <ul> 246 246 + <li><code>rel</code> MUST be <code>self</code></li> 247 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 248 + </ul> 249 249 + <p>Publishers SHOULD include only one such link.</p> 250 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 251 + <ul> 252 252 + <li>Take the first matching entry in `links`</li> 253 253 + <li>Deduplicate all matching entries in `links` by their `href`</li> 254 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 255 + </ul> 256 256 + </section> 257 257 + </section> 258 258 + <section class="informative" id="other"> 259 259 + <h3>Other uses of WebFinger</h3> 260 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 261 + <ul> 262 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 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 264 + </ul> 265 265 + <p>The following link relations are less common, but offer useful information to ActivityPub implementers:</p> 266 266 + <ul> 267 267 + <li><code>http://ostatus.org/schema/1.0/subscribe</code> (used to power features like Mastodon's remote follow buttons)</li> 268 268 + <li><code>http://schemas.google.com/g/2010#updates-from</code> (used by some implementations to link to an Atom feed)</li> 269 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 270 + <li><code>http://a9.com/-/spec/opensearch/1.1/</code> (for custom search bars)</li> 271 271 + </ul> 272 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 273 + <ul> 274 274 + <li><code>shortlink</code></li> 275 275 + <li><code>author</code></li> 276 276 + <li><code>alternate</code></li> 277 277 + <li><code>license</code></li> 278 278 + <li><code>canonical</code></li> 279 279 + <li><code>webmention</code></li> 280 280 + </ul> 281 281 + </section> 282 282 + <section class="informative" id="security"> 283 283 + <h2>Security Considerations</h2> 284 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 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 286 + </section> 287 287 + <section class="informative" id="future"> 288 288 + <h2>Future Enhancements</h2> 289 289 + <p>The current use of WebFinger with ActivityPub could be improved in several ways:</p> 290 290 + <ul> 291 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 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 293 + <li>WebFinger could be used to expose certain properties or qualified links more directly, skipping the resolution of the actor resource.</li> 294 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 295 + <li>A convention could be adopted for identifying users by a DNS name instead of an acct: URI.</li> 296 296 + </ul> 297 297 + </section> 298 298 + <section id="conformance"> 299 299 + </section> 300 300 + </body> 301 301 + 302 302 + </html>