OAuth
15 symbols from @neontechspace/fluxerly/effect
Variables#
oauth#
Create a server-side OAuth client, or generate an S256 PKCE challenge for an authorization request
The create method returns an Effect that requires Scope. Invalid configuration is misuse and dies with ConfigurationError. The application owns consent, callback correlation, state validation, token storage, installation policy and coordinated refresh
const oauth: Readonly<{ … }>import { Effect } from "effect"
import { oauth, OAuthScopes } from "@neontechspace/fluxerly/effect"
export const oauthEffectExample = Effect.scoped(
Effect.gen(function* () {
const client = yield* oauth.create({ clientId: "123", clientSecret: "server-held-secret" })
const pkce = oauth.createPkce()
const url = yield* client.authorizationUrl({
redirectUri: "https://app.example.test/oauth/callback",
scopes: [OAuthScopes.Identify, OAuthScopes.Bot],
state: "caller-correlated-state",
codeChallenge: pkce.challenge,
guildId: "456",
permissions: 0n,
})
// Store the verifier with the matching state in a one-use server record before redirecting the browser.
// Use it to exchange the callback code, and keep it out of browser responses and logs
return { url, codeVerifier: pkce.verifier }
}),
)create#-
Create the OAuth client when this Effect executes, without making a request
Invalid client credentials or instance settings are misuse and die with
ConfigurationError. Unexpected failures remain defects in the Cause. Scope closure calls shutdown(config: OAuthConfig) => Effect.Effect<OAuthClient, never, Scope.Scope>(config: OAuthConfig) => Effect.Effect< OAuthClient, never, Scope.Scope > create#Pkce -
Generate a private verifier and matching S256 challenge for one authorization-code flow
Send challenge to
authorizationUrland keep verifier privately forexchangeCode. This synchronous helper returns the values immediately, without a request or token storage. It does not generate or verify the callback's state value() => OAuthPkce
Interfaces#
OAuthClient #
Use OAuth to access a user's Fluxer account with their consent and a server-held client secret
The scope that creates this client shuts it down
interface OAuthClientThe application handles consent, browser callbacks, state checks, token storage and refresh coordination
The fetchGuilds and fetchConnections methods read the user's communities and connections. Reading one delegated
community, its roles or the fuller current-user profile needs a server-side request with the access token.
The client.rest.request method always sends the bot token. The Webhooks & OAuth guide's section Reading with a user token shows the request
The client keeps a copy of the secret until shutdown and runs at most eight operations at once. While eight are running, another operation fails at once with OAuthOperationError reason busy instead of waiting. Response bodies are capped at 1 MiB. Requests never retry automatically
The timeoutMs option defaults to 30,000 for discovery and the operation, with request cleanup awaited afterward. Malformed options fail with a local input error before discovery. Discovery throttling fails with OAuthOperationError reason rateLimit, outcome notDispatched, status 429 and the server's retryAfterMs when available
Expected failures use Effect's error channel. Interruption and cleanup defects remain in Cause.
Response and discovery cleanup faults keep their original values as Cause defects, and describeError masks credential patterns in them
Operation input properties are read during execution, with throwing accessors retained as defects
authorizationUrl #
Build an authorization URL for the selected instance using its discovered web application URL, including its path
Supply the redirect URI, scopes, caller-generated state and S256 PKCE challenge, which binds the callback code to the private verifier. The application must retain state correlation and the PKCE verifier. Bot community and permission parameters are consent hints, not proof of installation or authorization. This returns the URL without opening it. Fluxer's prompt parameter is not supported, so the URL always shows the consent page. Network failures retain only sanitized transport facts in cause
authorizationUrl(
input: OAuthAuthorizationInput,
options?: RequestOptions
): Effect<string, OAuthOperationFailure>authorizationUrl(
input: OAuthAuthorizationInput,
options?: RequestOptions
): Effect<
string,
OAuthOperationFailure
>Parameters
input-
OAuthAuthorizationInput optionsoptional-
RequestOptions
- Returns
Effect<string, OAuthOperationFailure>- Fails with
exchangeCode #
Exchange the code from an authorization callback for access and refresh tokens
Supply the matching redirect URI and PKCE verifier. The application must store the returned tokens. After dispatch, cancellation or a lost response cannot tell whether Fluxer consumed the one-use code. Do not retry that exchange when its outcome is unknown. Network failures retain only sanitized transport facts in cause
exchangeCode(
input: OAuthCodeExchangeInput,
options?: RequestOptions
): Effect<OAuthTokens, OAuthOperationFailure>exchangeCode(
input: OAuthCodeExchangeInput,
options?: RequestOptions
): Effect<
OAuthTokens,
OAuthOperationFailure
>Parameters
input-
OAuthCodeExchangeInput optionsoptional-
RequestOptions
- Fails with
fetchAuthorization #
Fetch what the delegated user authorized with an access token: The application, the granted scopes, when the token expires and, with the identify scope, the user
Any valid access token works, so this checks a stored token without the client secret that introspect needs. Fluxer answers a rejected, expired or revoked token with reason rejected and HTTP 401. Failures identify a read in details.read for errors.isRetryable. Requests are not retried automatically, and network causes retain only sanitized transport facts
fetchAuthorization(
accessToken: string,
options?: RequestOptions
): Effect<OAuthAuthorization, OAuthOperationFailure>fetchAuthorization(
accessToken: string,
options?: RequestOptions
): Effect<
OAuthAuthorization,
OAuthOperationFailure
>Parameters
accessToken -
string optionsoptional-
RequestOptions
fetchConnections #
Fetch the delegated user's full connections list with a connections-scoped access token
The client neither creates, verifies, reorders nor retains those connections. Failures identify a read in details.read for errors.isRetryable. Requests are not retried automatically, and network causes retain only sanitized transport facts
fetchConnections(
accessToken: string,
options?: RequestOptions
): Effect<readonly OAuthConnection[], OAuthOperationFailure>fetchConnections(
accessToken: string,
options?: RequestOptions
): Effect<
readonly OAuthConnection[],
OAuthOperationFailure
>Parameters
accessToken -
string optionsoptional-
RequestOptions
- Returns
Effect<readonly OAuthConnection[], OAuthOperationFailure>Effect< readonly OAuthConnection[], OAuthOperationFailure >- Fails with
fetchGuilds #
Fetch one bounded page of the delegated user's community memberships
Use an access token with Fluxer's guilds scope. Optionally supply pagination settings in GuildListQuery, where limit defaults to 200 and accepts 1–200, and before and after are mutually exclusive cursors. This uses bearer authentication with the supplied access token, never the bot token. Failures identify a read in details.read for errors.isRetryable. Requests are not retried automatically, and network causes retain only sanitized transport facts
fetchGuilds(
accessToken: string,
query?: GuildListQuery,
options?: RequestOptions
): Effect<readonly GuildListSummary[], OAuthOperationFailure>fetchGuilds(
accessToken: string,
query?: GuildListQuery,
options?: RequestOptions
): Effect<
readonly GuildListSummary[],
OAuthOperationFailure
>Parameters
accessToken -
string queryoptional-
GuildListQuery optionsoptional-
RequestOptions
- Returns
Effect<readonly GuildListSummary[], OAuthOperationFailure>Effect< readonly GuildListSummary[], OAuthOperationFailure >- Fails with
fetchIdentity #
Fetch the delegated user's identity with an access token granted the identify scope
Additional identity fields depend on the token's scopes. The access token is not retained by this client. Failures identify a read in details.read, so errors.isRetryable can classify transient failures without implying a token change. Requests are not retried automatically, and network causes retain only sanitized transport facts
fetchIdentity(
accessToken: string,
options?: RequestOptions
): Effect<OAuthIdentity, OAuthOperationFailure>fetchIdentity(
accessToken: string,
options?: RequestOptions
): Effect<
OAuthIdentity,
OAuthOperationFailure
>Parameters
accessToken -
string optionsoptional-
RequestOptions
- Fails with
introspect#
Inspect an access or refresh token using this client's ID and secret through HTTP Basic authentication
An inactive result does not explain expiry or revocation, prove token ownership or establish whether it ever existed. Failures identify a read in details.read for errors.isRetryable. Requests are not retried automatically, and network causes retain only sanitized transport facts
introspect(
token: string,
options?: RequestOptions
): Effect<OAuthIntrospection, OAuthOperationFailure>introspect(
token: string,
options?: RequestOptions
): Effect<
OAuthIntrospection,
OAuthOperationFailure
>Parameters
token-
string optionsoptional-
RequestOptions
refresh#
Exchange a refresh token for a new access and refresh token pair
Form tokens must contain 1–256 well-formed UTF-16 units without surrounding whitespace, U+000C or U+202E. Invalid values fail locally rather than being normalized, and this also applies to revoke and introspect tokens. Fluxer rotates refresh tokens. The application must coordinate refreshes and atomically replace both stored tokens after success, so it never stores a mixed pair
A refresh with an unknown outcome must not be retried, because it may have rotated the token. Network failures retain only sanitized transport facts in cause
refresh(
refreshToken: string,
options?: RequestOptions
): Effect<OAuthTokens, OAuthOperationFailure>refresh(
refreshToken: string,
options?: RequestOptions
): Effect<
OAuthTokens,
OAuthOperationFailure
>Parameters
refreshToken -
string optionsoptional-
RequestOptions
- Fails with
revoke#
Revoke the supplied token and every access and refresh token for the same user and application
Other sessions for that user and application stop working too. The token and hint are captured once when execution starts, then validated and transmitted from that snapshot. A lost response can still mean the tokens were revoked. Network failures retain only sanitized transport facts in cause
revoke(
input: {
readonly token: string
readonly tokenTypeHint?: "refresh_token" | "access_token"
},
options?: RequestOptions
): Effect<void, OAuthOperationFailure>revoke(
input: {
readonly token: string
readonly tokenTypeHint?:
| "refresh_token"
| "access_token"
},
options?: RequestOptions
): Effect<
void,
OAuthOperationFailure
>Parameters
input-
token-
Access or refresh token to invalidate
Keep this secret out of logs
string tokenoptionalType Hint -
Identify the token as an access token or a refresh token when the kind is known
When omitted, the request asks Fluxer to check refresh tokens first, then access tokens. Fluxer does not find a refresh token sent with the access_token hint
"refresh_token" | "access_token"
optionsoptional-
RequestOptions
- Returns
Effect<void, OAuthOperationFailure>- Fails with
shutdown#
Permanently stop OAuth work, reject new work, release the client's copied secret and abort active requests
Shutdown waits for fetch and response-reader cleanup. A response-cleanup failure in an active operation fails that operation, while shutdown waits for it and may itself succeed. A failure in shutdown's own discovery cleanup fails shutdown
shutdown(): Effect<void>- Returns
Effect<void>
Those cleanup defects remain in the affected Effect's Cause
Re-Exports#
Declared in JavaScript & TypeScript and documented there. Import them from @neontechspace/fluxerly/effect as well
OAuth#Scopes - Choose which account data the user may share, or request bot installation, in
authorizationUrl OAuth#Active Introspection - Token-check result when Fluxer reports this application's access or refresh token as active
OAuth#Authorization - Frozen description of the authorization behind a delegated access token, returned by
fetchAuthorization OAuth#Authorization Input - Build the consent URL for an authorization-code request with PKCE
OAuth#Code Exchange Input - Values received or retained by the application for
exchangeCodeafter a consent callback OAuth#Config - Create a server-side OAuth client for exchanging authorization codes with an application secret
OAuth#Connection - One connection returned by
fetchConnectionswith the connections scope, as an immutable value OAuth#Identity - Frozen basic account identity returned by
fetchIdentityusing a delegated access token OAuth#Inactive Introspection - Token-check result when Fluxer does not report the credential as active for this application
OAuth#Pkce - A PKCE secret and its public hash challenge, used to prove that the code exchange belongs to the authorization request
OAuth#Tokens - Credentials returned by a successful
exchangeCodeor refresh call OAuth#Introspection - Result of introspect, which explicitly asks Fluxer whether a token is active for this application
OAuth#Scope - One supported authorization scope from
OAuthScopes