HTTP Operations

HTTP Operations are the reusable boundary between effect-auth's domain services and an application's HTTP contract. Use them when you want different routes, groups, or public schemas without reimplementing authentication behavior. Each *HttpOperations service contains endpoint-shaped functions: they accept the built-in endpoint request shape and return its typed success and error channels. See Architecture for the surrounding layers.

request -> your HttpApi endpoint + middleware -> *HttpOperations method
        -> AuthRateLimit (when required) -> domain services -> public result
        <- response + Set-Cookie effects <- mapped public error/success

The ownership line

This is more than calling a primitive. For example, password sign-in preserves credential-enumeration resistance, continuation handling, internal-error hiding, session commitment, and configured trusted-device behavior. A custom endpoint may adapt its own request before calling the operation, but its contract must declare compatible output and error schemas. For a worked comparison, see Password and Custom Auth API.

Bind one method

const CoreAuthPasswordGroupLive = HttpApiBuilder.group(
  AppAuthApi,
  "password",
  Effect.gen(function* (handlers) {
    const password = yield* PasswordHttpOperations;
    return handlers.handle("signIn", password.signIn);
  })
).pipe(Layer.provide(PasswordHttpOperationsLive));

Layers are feature-sized, binding is endpoint-sized. PasswordHttpOperationsLive constructs the complete password service (signIn, signUp, reset, set, and change), so its layer must have the dependencies needed by that feature. Your API can expose only signIn, combine password sign-in with session logout and passkey registration, or call a primitive in another handler. The choice is per endpoint; feature-level layers do not force feature-level routing.

Provide the configured AuthRateLimit while constructing operation layers. Methods with standard operation security capture it and execute the applicable policy themselves. Run that policy exactly once: do not wrap the operation with the same AuthRateLimit check, or rate-limit budget and other effects can be consumed twice. Endpoint middleware and genuinely additional application rules remain yours.

Optional capabilities are also captured when the layer is created. Examples include email-verification flow, trusted-device cookies, login-risk enrichment, strong-factor removal policy, optional OAuth grants, token introspection/revocation, and login-approval services. Adding one later to the request's context does not change an already-built operations service; rebuild/provide the operations layer with that capability present.

Cookie behavior belongs to the operation when it is part of the standard workflow: authenticated sessions are committed, refreshed, or cleared through AuthHttp and SessionCookie, and related cookies are applied where configured. Likewise, domain failures are converted to the endpoint's stable public errors while unexpected storage, hashing, or cryptographic failures are hidden as internal errors. Your endpoint still owns schema-error middleware and must advertise the errors it can encode.

Catalog

• Primary authentication: Password, EmailAuth, EmailOtp, MagicLink, Passkey, EmailVerification.
• Sessions and assurance: Session, Mfa, StepUp, Totp, RecoveryCodes, LoginApproval.
• Account security: TrustedDevice, Security, SecurityTimeline, plus AdminSession, AdminTrustedDevice, and AdminSecurityTimeline.
• Tokens and federation: OAuth, OAuthProviderAuthorization, OAuthToken, ApiKey, RefreshToken, Jwt, JwtDiscovery, and OidcDiscovery.

Each name above represents NameHttpOperations, its service interface and operation types, plus a corresponding NameHttpOperationsLive export. Consult Reference: HTTP Operations for the method-level inventory.