auth README

The project's README from github.com/yielded-dev/auth. As one markdown file: README.md.

Yielded Auth

npm CI MIT license

Documentation · Getting started · yielded.dev

Composable authentication, sessions, and identity workflows for Effect.

Define your contract with Schema, supply infrastructure with Layers, and call auth alongside your other Effects. The same contract connects your server to an Effect HttpClient service and Effect Atom queries and mutations.

Your application owns its accounts, identifiers, and authorization policy. Use managed auth tables, map an existing SQL schema, or implement storage services against another backend. The auth API stays the same when you change storage. Core has only Effect as a runtime peer; companion packages supply database, cryptography, and protocol adapters.

Start with Auth in an Effect application or compare database and backend choices. The four account apps show managed Drizzle, custom Drizzle, Effect SQL, and non-SQL persistence.

Install the beta release with Effect:

bun add @yielded/auth@beta effect

Prefer named namespace imports from @yielded/auth. Direct module paths such as @yielded/auth/AuthContract remain available; see the import guide.

One API, server and client

Define the shared contract in packages/domain/auth-contract.ts:

import { Schema } from "effect";
import { AuthContract } from "@yielded/auth";

export const AuthApi = AuthContract.make("app/Auth", {
  claims: Schema.Struct({ displayName: Schema.String }),
  actions: (sessions) => ({ signIn: AuthContract.passwordSignIn(sessions) }),
});

Bind the server implementation and mount its HTTP routes:

import { Auth, Http, Password, Sessions } from "@yielded/auth";

import { AuthApi } from "@app/domain/auth-contract";

export const AppAuth = Auth.make(AuthApi, {
  sessions: Sessions.stateful(),
  strategies: { password: Password.make() },
  defaultStrategy: "password",
});

export const AuthRoutes = Http.layer(AppAuth, { origin: "https://app.example.com" });

Supply your persistence and account Layers to AuthRoutes, then merge it with your router. For application routes that call auth, use the middleware shown in the router composition. Inside an existing Effect handler, call the service directly:

const auth = yield* AppAuth;
const result = yield* auth.signIn({ email, password });

The request context supplies credentials and cookie delivery. auth.getSession(), auth.requireSession(), and auth.signOut() use the same boundary. An Authenticated sign-in result contains a session with typed claims.displayName.

Create the client and its atoms from the same contract:

import { Atom as AuthAtom, Client } from "@yielded/auth";

import { AuthApi } from "@app/domain/auth-contract";

export const AppClient = Client.make(AuthApi, { baseUrl: "https://app.example.com" });
export const auth = AuthAtom.make(AppClient);

Use auth.session, auth.signIn, and auth.signOut with ordinary @effect/atom-react hooks. Auth mutations refresh auth queries automatically; React renders and dispatches. Compose your own queries through the same client:

import { Effect } from "effect";

import { AppClient, auth } from "./auth-client";

export const memberName = auth.runtime.atom(
  Effect.gen(function* () {
    const client = yield* AppClient;
    const session = yield* client.auth.getSession();

    return session?.claims.displayName ?? null;
  }),
);

Fetch is configured by default. To customize transport, compose AppClient.layer with your HttpClient Layer and pass { layer: ClientLive } to AuthAtom.make. See the client guide for React, shared invalidation, and standalone Effect calls.

Add passwords, passkeys, email or phone codes, two-factor authentication, and OAuth through strategies and their required Layers. OAuth can also retain encrypted provider grants for calling APIs after sign-in.

Start with the documentation and consumer examples. The public library lives in packages/auth; examples are leaf workspaces.

Development

Install Bun and Vite+, then run:

vp install
vp run patch:tsgo
vp run ready

The toolchain guide covers release setup and contributor rules. Shared versions live in the root catalog. Formatting, linting, strict TypeScript, package exports, dependency purity, tests, and builds use Vite+.

License

MIT

auth (yielded-dev/auth)

Searching Database…

233 ·GitHub
Auth
这是什么？一个专为 Effect 生态构建的可组合认证、会话与身份工作流库。你用 Schema 定义认证契约，并通过 Effect Layers 接入基础设施。
它是一个独立框架，还是一个可以接入现有 Effect 应用的库？它是一个库，不是框架：公开包位于 packages/auth，你可以像调用自己的其他 Effect 一样调用它的服务，示例应用则作为独立的叶子工作区保留。
怎么把它加进我的 Effect 项目？在安装 Effect 的同时安装 beta 版本，从 @yielded/auth 使用具名命名空间导入，定义一份共享契约（例如 packages/domain/auth-contract.ts），绑定服务端实现并挂载其 HTTP 路由，然后用同一份契约创建客户端及其 atoms。
除了 Effect 本身，它还需要什么？核心包在运行时只把 Effect 作为对等依赖（peer dependency）；独立的配套包按你选择的存储后端和认证策略提供数据库、密码学和协议适配器。参与贡献/开发需要 Bun 和 Vite+。
它准备好用于生产环境了吗？它目前以 beta 版本发布，因此在稳定版出来之前，API 表面预计仍会有变动。
用了它，我会被锁定在某个特定数据库上吗？不会。你可以使用托管的认证表，也可以把它映射到现有的 SQL 模式上，或者针对完全不同的后端实现存储服务，无论哪种方式认证 API 都保持不变。
开箱即用支持哪些认证策略？密码、通行密钥（passkey）、邮箱或手机验证码、双因素认证和 OAuth，每种都通过策略及其所需的 Layers 添加。OAuth 还能保留加密的提供方授权凭据，以便在登录后调用 API。
能在 React 中使用吗？可以。客户端暴露的 atoms 可配合普通的 @effect/atom-react hooks 使用（auth.session、auth.signIn、auth.signOut），认证变更会自动刷新相关的查询。
那些示例应用是干什么用的？自带的四个账户应用演示了不同的持久化选项：托管 Drizzle、自定义 Drizzle、Effect SQL 和非 SQL 存储。
HTTP 传输是如何工作的？默认配置的是 Fetch；要自定义的话，你可以用自己的 HttpClient Layer 与 AppClient.layer 组合，并在创建认证客户端时把它作为客户端 Layer 传入。
What are similar projects?react-starter-kit, zitadel, mongoose, better-auth, rankme.fast, hackathon-starter, kratos, cloudflare_temp_email
Which topics is it in?beta, identity, passkeys, drizzle-orm, schema, authorization, 2fa, functional-programming, orm, cryptography, oauth2, npm-package
Creator
yielded-dev
Size
5.9 MB
Stars
233
Updated
CommitOct 18
Age
1mo
Commits · 90 Days