A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.
docs: drop hosted donation, refund, appeal and Visionary details
Hampuse8a2011cfe0b
diff --git a/fluxer_docs/src/content/docs/admin-api/bulk-jobs.mdx b/fluxer_docs/src/content/docs/admin-api/bulk-jobs.mdxindex 2a3ac9017..6d1006725 100644--- a/fluxer_docs/src/content/docs/admin-api/bulk-jobs.mdx+++ b/fluxer_docs/src/content/docs/admin-api/bulk-jobs.mdx@@ -14,8 +14,6 @@ Every target is a list of IDs. There is no search, role, tag, email, or IP selec## Bulk job creation object-A bulk job creation has the identifier of the queued job.-### Structure| Field | Type | Description |@@ -75,8 +73,6 @@ Body validation runs ahead of authentication and ACL evaluation, so a malformed### JSON body-The `task` discriminator selects one of these structures. Every ID array has an upper bound and no lower bound, so an empty array queues a job that processes nothing and finishes with the status `succeeded`.-#### Update user flags structure| Field | Type | Description |@@ -116,7 +112,7 @@ The `task` discriminator selects one of these structures. Every ID array has an| days_until_deletion<sup>1</sup> | integer | The delay before deletion in whole days (1-365) || basis<sup>2</sup> | [basis](/admin-api/enforcement/#basis) object | Why the accounts are closed |-<sup>1</sup> Fluxer raises the value to the minimum of the basis, 74 days for a broken rule and 14 days otherwise. A self-hosted instance has no appeal route and raises every basis to 14 days+<sup>1</sup> Fluxer raises the value to 14 days, the minimum of every basis<sup>2</sup> The `enforcement` basis takes a bulk decision with `reason_code`, `source` (always `own_review`), `automation` and a required `statement`. Reports, evidence messages and any other field are refused, because per-account facts cannot be given in bulk. The `X-Audit-Log-Reason` header is required with this basis, or the request fails with `ENFORCEMENT_INTERNAL_NOTE_REQUIRED`, and becomes the first note on every decisiondiff --git a/fluxer_docs/src/content/docs/http-api/donations.mdx b/fluxer_docs/src/content/docs/http-api/donations.mdxdeleted file mode 100644index f147af6a5..000000000--- a/fluxer_docs/src/content/docs/http-api/donations.mdx+++ /dev/null@@ -1,217 +0,0 @@-----# SPDX-License-Identifier: AGPL-3.0-or-later-title: Donations-description: Donation currencies and intervals, checkout sessions, and the donor management link.------import RouteHeader from '@/components/RouteHeader.astro';--A donation is a one-off or recurring payment, taken on an externally hosted checkout page. Fluxer tracks it by email address, and it grants no [premium](/http-api/premium/). [Billing](/http-api/billing/) defines the payment provider webhook that completes one.--None of the routes here takes a credential, and all are hosted-only, as [deployment availability](/http-api/deployment-availability/) describes. When a request presents a valid credential anyway, Fluxer counts the request against that account's rate limit.--Fluxer removes the surrounding whitespace from a submitted address and lowercases it before it matches a donor, so `[email protected]` and `[email protected]` address the same donor.--:::note[Donation management requires a completed donation]-Fluxer stores a donor only when the payment provider confirms a donation checkout. [Request donation management link](#request-donation-management-link) sends a link only to an address stored as a donor.-:::--## Donation currencies--Amounts are expressed in the minor unit of the selected currency. Each currency has its own inclusive bounds.--| Value | Description |-| --- | --- |-| usd | The United States dollar (300-99999999 minor units) |-| eur | The euro (300-99999999 minor units) |-| brl | The Brazilian real (1000-99999999 minor units) |-| inr | The Indian rupee (20000-99999999 minor units) |-| pln | The Polish zloty (800-99999999 minor units) |-| try | The Turkish lira (10000-99999999 minor units) |-| sek | The Swedish krona (3000-99999999 minor units) |-| dkk | The Danish krone (2000-99999999 minor units) |-| nok | The Norwegian krone (3000-99999999 minor units) |--## Donation intervals--| Value | Description |-| --- | --- |-| month | The donation repeats every month |-| year | The donation repeats every year |-| null | The donation is taken once |--## Donation checkout object--A donation checkout is one absolute URL.--### Structure--| Field | Type | Description |-| --- | --- | --- |-| url<sup>1</sup> | string | The absolute URL to send the donor to |--<sup>1</sup> The externally hosted checkout session URL. A recurring donation for an address that already holds an active recurring donation returns the public donation management page--### Example--```json-{- "url": "https://checkout.example.com/c/pay/cs_test_a1b2c3d4e5f6"-}-```--## Request donation management link--<RouteHeader method="POST" path="/v1/donations/request-link" unauthenticated />--Accepts a request for a single-use donation management link. Returns 204 with an empty body.--### Limitations--- The submitted address must be syntactically valid.-- The address must not exceed 254 characters.-- Its domain must publish usable mail or address records.--A failure of any of those returns 400 `INVALID_FORM_BODY` with an `errors` entry on `email`.--:::caution[Every address answers the same 204]-An address that resolves to no donor receives no email.-:::--### JSON body--| Field | Type | Description |-| --- | --- | --- |-| email<sup>1</sup> <sup>2</sup> <sup>3</sup> | string | The donor email address (max 254 characters) |--<sup>1</sup> An empty string is reported as a missing address--<sup>2</sup> A padded address has its surrounding whitespace removed before validation--<sup>3</sup> The domain must publish an MX, A or AAAA record--### Response--| Status | Body | Condition |-| --- | --- | --- |-| 204 | empty | The request was accepted, whether or not an email was sent |-| 400 | [error response](/http-api/#error-response) | The address domain publishes no usable mail or address records |--### Side effects--An address that resolves to a donor receives an email with the management link. The 204 response does not guarantee delivery.--Fluxer creates a single-use token of 64 lowercase hexadecimal characters, valid for 15 minutes, only when the address resolves to a donor. Issuing a new link deletes every earlier token for the same address, and a replaced link returns 400 `DONATION_MAGIC_LINK_INVALID`.--### Rate limit--3 requests per hour for each client IP address or authenticated user, on the `donation:request_link` bucket.--10 requests per hour for each address, on the shared `donation:request_link:email` bucket.--## Manage donation--<RouteHeader method="GET" path="/v1/donations/manage" unauthenticated />--Checks a donation management token and leaves it unspent. Answers 302 with `Location` set to the donation management confirmation page on the public site. The token is the credential.--An unknown token redirects with `link_invalid` in `alert`, an expired token with `link_expired`, and a used token with `link_used`. An expired and used token reports `link_expired`. A token whose address no longer resolves to a donor holding a payment provider customer redirects with `no_customer`.--### Query parameters--| Field | Type | Description |-| --- | --- | --- |-| token<sup>1</sup> | string | The management token, exactly 64 characters |--<sup>1</sup> A token whose case was changed in transit redirects with `link_invalid`--### Response--| Status | Body | Condition |-| --- | --- | --- |-| 302 | empty | `Location` is the confirmation page, or the management page with an `alert` value |-| 400 | [error response](/http-api/#error-response) | The token is not exactly 64 characters |--### Side effects--None. The token stays spendable, so a mail scanner that opens the link first does not spend it.--### Rate limit--10 requests per minute for each client IP address or authenticated user, on the `donation:manage` bucket.--## Redeem donation management link--<RouteHeader method="POST" path="/v1/donations/manage" unauthenticated />--Creates the billing portal session and then consumes the token. Answers 302 with `Location` set to the externally hosted billing portal. The token is consumed only after the portal session exists, so a payment provider failure leaves it spendable.--Every other outcome redirects to the public donation management page with `alert` set to `link_invalid`, `link_expired`, `link_used`, `no_customer` or `portal_error`. A deployment with no configured payment provider redirects with `portal_error`, and so does a provider that rejects the portal creation.--### Query parameters--| Field | Type | Description |-| --- | --- | --- |-| token | string | The management token, exactly 64 characters |--### Response--| Status | Body | Condition |-| --- | --- | --- |-| 302 | empty | `Location` is the billing portal session, or the management page with an `alert` value |-| 400 | [error response](/http-api/#error-response) | The token is not exactly 64 characters |--### Side effects--The token is consumed. Closing the portal session returns the donor to the public donation page.--### Rate limit--10 requests per minute for each client IP address or authenticated user, on the `donation:manage` bucket.--## Create donation checkout--<RouteHeader method="POST" path="/v1/donations/checkout" unauthenticated />--Creates a one-off or recurring donation checkout session. Returns a [donation checkout](#donation-checkout-object) object on success.--An amount outside the selected currency's bounds fails validation with 400 `INVALID_FORM_BODY` and an `errors` entry on `amount_cents`. Where the deployment has no configured payment provider, the route returns 400 `STRIPE_PAYMENT_NOT_AVAILABLE` before it resolves the address. A provider failure while creating the session returns 400 `STRIPE_ERROR`.--A recurring donation for an address with an active recurring donation returns the public donation management page, with the percent-encoded address in `email` and `active_subscription` in `alert`. A donation scheduled for cancellation does not block a new checkout.--The session is bound to the address by email alone, never to a payment provider customer the address already has. Addresses are trimmed and lowercased before every lookup and before they are stored.--### JSON body--| Field | Type | Description |-| --- | --- | --- |-| email<sup>1</sup> | string | The donor email address (max 254 characters) |-| amount_cents<sup>2</sup> | integer | Amount in the minor unit of `currency`, within that currency's [bounds](#donation-currencies) |-| currency | string | Lowercase [donation currency](#donation-currencies) |-| interval | ?string | [Donation interval](#donation-intervals), or null for a one-off donation |-| is_business?<sup>3</sup> | boolean | Whether to require a billing address for tax invoicing |--<sup>1</sup> Subject to the same syntax, length and domain record checks that [request donation management link](#request-donation-management-link) applies. The domain check runs after the amount bounds check, so an amount error is reported first--<sup>2</sup> The field name states cents, but the value is the minor unit of the selected currency. A fractional value is rejected--<sup>3</sup> Only `true` requires a billing address. `false` and an omitted key both leave billing address collection to the payment provider--### Response--| Status | Body | Condition |-| --- | --- | --- |-| 200 | [donation checkout](#donation-checkout-object) object | The checkout session was created, or the donor was redirected to donation management |-| 400 | [error response](/http-api/#error-response) | The amount is outside the currency's bounds, the address domain publishes no usable records, the payment provider is not configured and returns `STRIPE_PAYMENT_NOT_AVAILABLE`, or the provider rejected the request and returns `STRIPE_ERROR` |--### Side effects--Checkout opens on the provider's pages for the submitted amount, currency and interval. Completion returns the donor to the public donation success page, while cancellation returns to the public donation page.--When the payment provider confirms the payment, Fluxer stores the address as a donor and sends a donation confirmation email to it. From then on, [Request donation management link](#request-donation-management-link) sends a link to that address.--### Rate limit--5 requests per minute for each client IP address or authenticated user, on the `donation:checkout` bucket.--10 requests per hour for each address, on the shared `donation:checkout:email` bucket.diff --git a/fluxer_docs/src/content/docs/http-api/gifts.mdx b/fluxer_docs/src/content/docs/http-api/gifts.mdxindex 05e4ef811..984c13817 100644--- a/fluxer_docs/src/content/docs/http-api/gifts.mdx+++ b/fluxer_docs/src/content/docs/http-api/gifts.mdx@@ -32,7 +32,7 @@ Both creation paths record a creator. A completed gift checkout records the purc<sup>1</sup> Exactly 32 case-sensitive letters and digits-<sup>2</sup> Non-negative, and positive on every gift the current code paths create. The exact value `0` means lifetime Visionary entitlement and appears only on a record that predates that constraint+<sup>2</sup> Non-negative. The exact value `0` means lifetime premium<sup>3</sup> Neither the redemption time nor the redeeming account appears in this object@@ -109,7 +109,7 @@ Redeems a gift for the authenticated account and returns 204 with an empty body.- The redeeming account must be claimed, and an unclaimed account returns 400 `UNCLAIMED_ACCOUNT_CANNOT_MAKE_PURCHASES`.- The account must have a verified email address, and an unverified address returns 403 `PURCHASE_EMAIL_VERIFICATION_REQUIRED`.- The account must not have the purchase-disabled premium flag, and the flag returns 403 `PREMIUM_PURCHASE_BLOCKED` with a top-level `reason` member set to `purchase_disabled`.-- An account already holding lifetime Visionary entitlement receives 400 `CANNOT_REDEEM_PLUTONIUM_WITH_VISIONARY`.+- An account already holding lifetime premium receives 400 `CANNOT_REDEEM_PLUTONIUM_WITH_VISIONARY`.A consumed code receives 400 `GIFT_CODE_ALREADY_REDEEMED`. A code another request is redeeming receives 400 `STRIPE_GIFT_REDEMPTION_IN_PROGRESS`. A code that does not exist or has been revoked receives 404 `UNKNOWN_GIFT_CODE`.@@ -140,9 +140,9 @@ One redemption can be in flight for a code across the whole deployment, and a se| Status | Body | Condition || --- | --- | --- || 204 | empty | The gift was redeemed and the entitlement was applied |-| 400 | [error response](/http-api/#error-response) | CAPTCHA failed, the code is redeemed or a redemption is in flight, the account is unclaimed or holds lifetime entitlement, the payment provider rejected the change to the active subscription, or the Visionary guild join for a lifetime gift failed |+| 400 | [error response](/http-api/#error-response) | CAPTCHA failed, the code is redeemed or a redemption is in flight, the account is unclaimed or holds lifetime entitlement, or the payment provider rejected the change to the active subscription || 403 | [error response](/http-api/#error-response) | The email address is unverified, or purchases are disabled for the account |-| 404 | [error response](/http-api/#error-response) | No gift exists for the code, the gift was revoked, the authenticated account record no longer exists, or the configured Visionary guild does not exist |+| 404 | [error response](/http-api/#error-response) | No gift exists for the code, the gift was revoked, or the authenticated account record no longer exists |### Side effects@@ -150,9 +150,7 @@ The gift becomes redeemed, so [Get gift](#get-gift) reports `redeemed` as true aA positive quantity extends premium from the latest of the current time, the current premium end and the existing gift extension end. When the account has a subscription with the payment provider and its subscription premium has not ended, Fluxer also extends that subscription's trial or billing period without proration. A provider failure can return 400 `STRIPE_ERROR` and leave the code unredeemed.-A quantity of `0` grants lifetime Visionary premium and immediately cancels an active subscription without proration or a final invoice. When the gift record has a Visionary sequence number, the redeemer receives that number as their lifetime Visionary sequence and joins the [Visionary guild](/http-api/premium/#rejoin-visionary-guild).--A failed Visionary guild join leaves the gift unredeemed. Guild limits return 400 `MAX_GUILDS` or `MAX_GUILD_MEMBERS`. Any subscription cancellation already completed is not reversed.+A quantity of `0` grants lifetime premium and immediately cancels an active subscription without proration or a final invoice.Entitlement changes send [User Update](/gateway/events/#user-update) to the redeemer's sessions.diff --git a/fluxer_docs/src/content/docs/http-api/webhooks.mdx b/fluxer_docs/src/content/docs/http-api/webhooks.mdxindex 17c8b86e3..b0260753a 100644--- a/fluxer_docs/src/content/docs/http-api/webhooks.mdx+++ b/fluxer_docs/src/content/docs/http-api/webhooks.mdx@@ -36,7 +36,7 @@ The [global HTTP limit](/topics/rate-limits/) applies to every management route.## Origin refusal-Fluxer refuses a call from a first-party web client on [Execute webhook](#execute-webhook), [Get webhook message](#get-webhook-message), [Edit webhook message](#edit-webhook-message), and [Delete webhook message](#delete-webhook-message). A request whose `Origin` header is exactly `https://web.fluxer.app`, `https://web.canary.fluxer.app`, or one of the instance's own web app origins returns 403 `INVALID_API_ORIGIN`. Those are the origin of `FLUXER_APP_ENDPOINT` and every `FLUXER_APP_ORIGIN_ALIASES` entry.+Fluxer refuses a call from a first-party web client on [Execute webhook](#execute-webhook), [Get webhook message](#get-webhook-message), [Edit webhook message](#edit-webhook-message), and [Delete webhook message](#delete-webhook-message). A request whose `Origin` header is one of the instance's own web app origins returns 403 `INVALID_API_ORIGIN`. Those are the origin of `FLUXER_APP_ENDPOINT` and every `FLUXER_APP_ORIGIN_ALIASES` entry.A request that sends no `Origin`, or any other `Origin` value, passes the check. It runs after the route rate limit and before path validation.diff --git a/fluxer_docs/src/content/docs/topics/rate-limits.md b/fluxer_docs/src/content/docs/topics/rate-limits.mdindex deb10b241..c57656b59 100644--- a/fluxer_docs/src/content/docs/topics/rate-limits.md+++ b/fluxer_docs/src/content/docs/topics/rate-limits.md@@ -28,22 +28,6 @@ Some operations enforce a further limit inside the handler. `RATE_LIMIT_BYPASS`Every bucket is a leaky bucket. It admits at most the declared limit at once and refills continuously at that limit for each declared window, so a client that exhausts an allowance can send again as soon as enough of it has drained.:::-:::note[The headers and the body report different instants]-`X-RateLimit-Reset` and `X-RateLimit-Reset-After` report when the bucket has drained completely. `retry_after` in the response body reports the shorter delay after which one further request is admitted.-:::--:::note[A 429 can hide a 401 or 403]-A rate-limited request can return 429 even if its credentials would otherwise be rejected with 401 or 403.-:::--Some routes declare a second route bucket, including group direct message creation, adding group recipients, and deleting guild emoji or stickers. Each operation lists its limits. Fluxer counts a request against its route buckets before the handler runs, so a request the handler rejects still uses up allowance.--:::caution[A global denial revokes a user session]-When the global bucket denies a request authenticated by a non-bot account's user session token, Fluxer revokes that token before writing the 429. The client must authenticate again. A bot token, an OAuth2 access token, and an Admin API key are never revoked this way, and a route bucket denial never revokes a credential.-:::--A deployment can disable both buckets through instance configuration. While they are disabled, no response has an `X-RateLimit-*` header and no request is refused with 429 `RATE_LIMITED`. That switch also turns off the login allowances. Every other [limit enforced inside a handler](#limits-enforced-inside-a-handler) stays in force.-## Rate limit response objectThe denial body has the members of the ordinary [error response](/http-api/#error-response) and two further members.@@ -78,20 +62,6 @@ A [slowmode](#slowmode) denial answers 400 `SLOWMODE_RATE_LIMITED`.}```-## Rate limit scopes--The `X-RateLimit-Scope` header is the scope that produced a denial.--| Value | Description |-| --- | --- |-| user | The denial came from an allowance keyed by the caller alone |-| global | The denial came from the global bucket |-| shared<sup>1</sup> | The denial came from an allowance that several accounts can exhaust for each other |--<sup>1</sup> No route bucket declares a scope of its own, so every route bucket denial reports `user`. The announcement channel allowances are the live sources of `shared`--[Crosspost message](/http-api/messages/#crosspost-message) reports `shared` for its channel publish allowance, and an edit of a published message reports it for the per-message edit allowance. Every member who publishes or edits draws on the same allowance.-## Rate limit headersThese headers describe a rate limit decision. An operation that answers 429 returns this set.@@ -188,20 +158,18 @@ Each is a leaky bucket like the route buckets. It admits a burst of its full siz| [Modify current guild member](/http-api/guild-members/#modify-current-guild-member) | 25 per 30 minutes on the guild pronouns, when the submitted value differs | `PRONOUNS_CHANGED_TOO_MANY_TIMES` || [Modify current guild member](/http-api/guild-members/#modify-current-guild-member) | 25 per 30 minutes on the guild accent colour, when the submitted value differs | `ACCENT_COLOR_CHANGED_TOO_MANY_TIMES` || [Modify voice activity sharing](/http-api/users/settings/#modify-voice-activity-sharing) | 1 per 24 hours on the sharing default | `VOICE_ACTIVITY_SHARING_ON_COOLDOWN` |-| [Complete login with TOTP](/http-api/authentication/#complete-login-with-totp), [Complete login with WebAuthn MFA](/http-api/authentication/#complete-login-with-webauthn-mfa), and [Complete passkey bridge](/http-api/authentication/#complete-passkey-bridge) for `login_mfa` | 10 multi-factor attempts per 15 minutes | `INVALID_CODE` |-| [Complete login with TOTP](/http-api/authentication/#complete-login-with-totp), [Complete login with WebAuthn MFA](/http-api/authentication/#complete-login-with-webauthn-mfa), and [Complete passkey bridge](/http-api/authentication/#complete-passkey-bridge) for `login_mfa` | 5 multi-factor attempts per 5 minutes on one MFA ticket | `INVALID_CODE` |-| [Sudo mode](/http-api/users/mfa/#sudo-mode) with the `totp` method, and [Complete passkey bridge](/http-api/authentication/#complete-passkey-bridge) for `sudo` | 10 multi-factor attempts per 15 minutes | `INVALID_MFA_CODE` |+| [Complete login with TOTP](/http-api/authentication/#complete-login-with-totp), and [Complete login with WebAuthn MFA](/http-api/authentication/#complete-login-with-webauthn-mfa) | 10 multi-factor attempts per 15 minutes | `INVALID_CODE` |+| [Complete login with TOTP](/http-api/authentication/#complete-login-with-totp), and [Complete login with WebAuthn MFA](/http-api/authentication/#complete-login-with-webauthn-mfa) | 5 multi-factor attempts per 5 minutes on one MFA ticket | `INVALID_CODE` |+| [Sudo mode](/http-api/users/mfa/#sudo-mode) with the `totp` method | 10 multi-factor attempts per 15 minutes | `INVALID_MFA_CODE` |Every Modify current user allowance is keyed by the authenticated account, and the bot tag allowance by the bot account, so an owner changing a bot's tag draws on the bot's allowance. The guild member allowances are keyed by the guild and the member together, and one account holds a separate allowance in each guild. The login allowances are keyed by the account and by the MFA ticket respectively, and the sudo allowance by the account.-Fluxer consumes every multi-factor allowance before it checks the code, so a correct code drawn against an exhausted allowance is reported exactly like a wrong one. A correct code clears the counter. A completed passkey bridge ceremony clears nothing, and redeeming a `login_mfa` ceremony clears the login counters. The ticket allowance also destroys the MFA ticket as it denies, and the client restarts from [Log in with a password](/http-api/authentication/#log-in-with-a-password).+Fluxer consumes every multi-factor allowance before it checks the code, so a correct code drawn against an exhausted allowance is reported exactly like a wrong one. A correct code clears the counter. The ticket allowance also destroys the MFA ticket as it denies, and the client restarts from [Log in with a password](/http-api/authentication/#log-in-with-a-password).### Allowances answering neither shape[Get desktop handoff information](/http-api/authentication/#get-desktop-handoff-information) and [Complete desktop handoff](/http-api/authentication/#complete-desktop-handoff) share one failed-attempt counter keyed by the client IP address. Five failures block both operations for 15 minutes from the most recent failure, and a blocked request returns 400 `INVALID_HANDOFF_CODE` as a top-level code with no validation entry. Get desktop handoff information separately permits three successful lookups for each handoff code and reports a fourth with the same top-level code.-[Refund latest purchase](/http-api/billing/#refund-latest-purchase) permits one self-serve refund every 30 days for each account and reports a request inside that window as 403 `STRIPE_REFUND_COOLDOWN_ACTIVE`.-[Slowmode](#slowmode) is enforced inside the handler as well.## Slowmode