Papyr Write together in Markdown. The server can't read it. Try it GitHub

Hosting Papyr in your own app

Three calls put the relay into an ASP.NET Core app of your own, beside its routes and behind its sign-in. There is no NuGet package: reference the project src/Papyr.AspNetCore. Its only public type is PapyrHostingExtensions, in the namespace Papyr.AspNetCore. A complete, tested app of about 100 lines is samples/PapyrSample.

src/Papyr.AspNetCore is under the FSL-1.1-ALv2 (the repository’s LICENSE): any app may host the relay, but not one that is a commercial product or service offering what Papyr offers. The sample’s own code is MIT.

builder.Services.AddPapyr(builder.Configuration);    // reads the Papyr:* settings, adds the rooms
var app = builder.Build();
app.MapPapyrRelay().RequireAuthorization();           // GET /relay, behind your sign-in
app.MapPapyrAdmin();                                  // the admin API under /api, off without a token

What each call does

  • AddPapyr(services, configuration), once, before the app is built. Reads Papyr:DataDirectory, FlushIntervalSeconds, RoomExpiryDays, Relay:*, Blobs:*, Admin:* and Backup:* from configuration (configuration.md) and throws InvalidOperationException naming the setting and the fix when one is invalid. There is no options object: set a key in the configuration, in code too (builder.Configuration["Papyr:DataDirectory"] = ...). A TimeProvider or ArrayPool<byte> registered before is used. The host locks the data directory when it starts: one another server holds, or that cannot be created, stops the start. When the app begins to stop, the rooms close their connections (1001) and flush.
  • MapPapyrRelay(endpoints): GET /relay, relative to what you call it on (app.MapGroup("/collab") serves /collab/relay; the pages of Papyr.Server connect to /relay). There is no room in the path: a client names its room in its hello, the first message inside the WebSocket (relay-protocol.md). It returns the endpoint’s builder: add RequireAuthorization(), RequireHost(...) or a CORS policy. The endpoint runs its own WebSockets middleware (ping every 15 s); one your app has does no harm. It is mapped for GET (HTTP/1.1) and CONNECT (a WebSocket over HTTP/2, which browsers open on Kestrel’s HTTPS endpoints by default), and also maps /relay/{one segment}, where a page of version 1 still connects and is told to reload (4009, reason version1 in telemetry.md). What you add to the builder applies to all of them. With Papyr:Blobs:Enabled (off by default) it also maps the blob routes under /blob beside the relay (relative to the same endpoints: /collab/blob): the upload and download of a room’s encrypted files and HEAD /blob, with the limits of relay-protocol.md, “Blobs”. What you add to the builder applies to them as well. Off, nothing is mapped and every path under /blob is yours. The routes take the room’s access key in the request header Papyr-Room, so a gate of yours decides who may reach the server, not which room; they answer 403 to a foreign Origin as the relay does and send no CORS header. Never log or forward that header.
  • MapPapyrAdmin(app): the admin API (admin-api.md) under /api, which cannot be moved (the admin page and the OpenAPI document name it). Its token check is inside every route and cannot be replaced or switched off; conditions on the returned builder (RequireHost("localhost:*")) run in front of it. Without a token it maps nothing.

What your app must do

  • Sign-in in front of the relay. The relay takes whoever reaches it. A gate on its builder applies to the relay as a whole: the room is known only from the hello, after the upgrade, so no gate can admit a visitor to one room and not another (the room’s access key does that). It is checked at the upgrade only: a session that ends later does not close an open socket.
  • The Origin. A browser sends your visitor’s cookies with a WebSocket request that another site’s page opens, so a cookie gate alone would let that page in. The relay answers 403, before the upgrade, to a request whose Origin names neither the request’s own host (its Host, same port) nor an origin in Papyr:Relay:AllowedOrigins (configuration.md; the exact rule: relay-protocol.md, “The Origin”). Pages your app serves need no entry; list pages elsewhere (another host or port, an installed client’s app://...) as a browser writes them, without a default port. A request without Origin (no browser, so no cookie) passes. SameSite=Strict on the cookie is the first defence, the Origin check the second.
  • Behind a proxy: Host and the scheme. The own host is the Host header as the app sees it, so the proxy must pass the one the browser sent, port included (nginx: proxy_set_header Host $http_host; Caddy and Traefik pass it; YARP only with RequestHeaderOriginalHost). A proxy that rewrites it has every page refused, with event 33 once per start. If your app applies X-Forwarded-Host (UseForwardedHeaders, from the proxy only), the forwarded host is the own host. “Over TLS” is HttpRequest.IsHttps: true when Kestrel terminates TLS, and behind a TLS proxy only when the app applies X-Forwarded-Proto; then an http:// origin is refused. Without it the scheme is not compared. Papyr.Server applies X-Forwarded-For only.
  • A private network: AllowedHosts. DNS rebinding points an attacker’s name at your server; the browser then sends that name in Host and Origin alike, so the Origin rule passes it. Such a page gets no cookie of yours, but a server on a private network should still answer its own names only: set ASP.NET Core’s AllowedHosts (AllowedHosts=notes.internal, ;-separated; Papyr.Server takes it too), which answers 400 to any other Host.
  • Forwarded headers. Behind a proxy, apply its X-Forwarded-For (UseForwardedHeaders with KnownProxies or KnownIPNetworks set to that proxy, ForwardLimit 1) before the endpoints: the relay counts its limits per client address, and without it every client is one source (event 19 once). Never trust every peer (ASPNETCORE_FORWARDEDHEADERS_ENABLED=true).
  • Request bodies. An upload sets MaxRequestBodySize of its own request to Papyr:Blobs:BlobBytes as its first statement, before anything reads the body, so a limit of your app or of Kestrel cannot lower it: set BlobBytes to what you want to take. An upload that declares more is refused with 413 and the app reads none of its body (Kestrel drains an unread body for up to 5 seconds after the answer, so that such a request still costs its bandwidth until then). The body is streamed to a file through Kestrel’s input buffer, within 10 seconds and one more per 256 KiB of its length, else the connection is ended. Blobs are stored in blobs/ of the data directory, beside rooms/ and under the same lock; they count in the disk you give it (configuration.md).
  • Kestrel. The façade changes none of its options. Papyr.Server sets Limits.MaxRequestBufferSize and the socket transport’s MaxReadBufferSize to 64 KiB (they default to 1 MiB, which every relay connection could hold), MaxConcurrentUpgradedConnections to Papyr:Relay:ServerConnections, and a 15 s keep-alive timeout: do the same where memory matters (configuration.md, “Memory”).
  • Order of the middleware. Call MapPapyrAdmin after UseForwardedHeaders and before your static files or any fallback that would answer a path under /api; if you call UseRouting() yourself, call it before MapPapyrAdmin.
  • Telemetry and logs. An ActivitySource and a Meter named Papyr (telemetry.md); events go through your ILogger under the categories Papyr.AspNetCore.*.

What it changes in your app

AddPapyr with an admin token puts the admin types’ JSON context first in the resolver chain of your HTTP JSON options (the OpenAPI package reads them). It resolves those types and no others, so nothing else your app serializes changes. No other global setting is touched.