@shivaedev/identity 0.3.0 → 0.3.1

package/README.md

@@ -15,11 +15,11 @@ import { Authenticated } from "@shivaedev/identity/middleware.ts";
 export const Account = RpcGroup.make(Rpc.make("WhoAmI", { success: Schema.String })).middleware(Authenticated);
 
 export const Handlers = Account.toLayer({
-  WhoAmI: () =>
-    Effect.gen(function* () {
-      const identity = yield* Identity;
-      return identity.id;
-    }),
+	WhoAmI: () =>
+		Effect.gen(function* () {
+			const identity = yield* Identity;
+			return identity.id;
+		}),
 });
 ```
 
@@ -30,7 +30,6 @@ The browser imports `Account` as it is; the server supplies the session middlewa
 ### How to think about it
 
 There are three parts to an authenticated RPC boundary:
-
 1. **The shared contract** names the middleware tags (`Authenticated`, `MaybeAuthenticated`, `AuthenticatedUser`, permission middleware) and the request-local services they provide. These modules are browser-safe, because the client imports the contract.
 2. **The server composition** implements the tags with Layers from `server/`. A session provider resolves a session; an Origin policy decides whether its request may reach that provider; request tracing supplies a request id and diagnostic context.
 3. **The feature handler** reads `Identity`, `OptionalIdentity`, `SessionUser` or `RequestId` and runs application code. Authentication supplies a user id. Authorization still decides whether that user may perform this operation.
@@ -49,22 +48,22 @@ import { Identity } from "@shivaedev/identity/identity.ts";
 import { Authenticated } from "@shivaedev/identity/middleware.ts";
 
 export const Account = RpcGroup.make(
-  Rpc.make("ReadOwn", {
-    error: Forbidden,
-    payload: { userId: Schema.String },
-    success: Schema.String,
-  }),
+	Rpc.make("ReadOwn", {
+		error: Forbidden,
+		payload: { userId: Schema.String },
+		success: Schema.String,
+	}),
 ).middleware(Authenticated);
 
 export const Handlers = Account.toLayer({
-  ReadOwn: ({ userId }) =>
-    Effect.gen(function* () {
-      const identity = yield* Identity;
-      if (identity.id !== userId) {
-        return yield* new Forbidden({ message: "Not your account" });
-      }
-      return identity.id;
-    }),
+	ReadOwn: ({ userId }) =>
+		Effect.gen(function* () {
+			const identity = yield* Identity;
+			if (identity.id !== userId) {
+				return yield* new Forbidden({ message: "Not your account" });
+			}
+			return identity.id;
+		}),
 });
 ```
 
@@ -78,8 +77,8 @@ import { trustedOrigins } from "@shivaedev/identity/server/origin.ts";
 import { auth } from "./auth.ts";
 
 export const sessions = {
-  origin: trustedOrigins({ allow: ["http://localhost:3000"], missing: "allow" }),
-  provider: betterAuthSessions((headers) => auth.api.getSession({ headers })),
+	origin: trustedOrigins({ allow: ["http://localhost:3000"], missing: "allow" }),
+	provider: betterAuthSessions((headers) => auth.api.getSession({ headers })),
 };
 ```
 
@@ -96,12 +95,12 @@ import { Config, Effect } from "effect";
 import { authDatabase, betterAuthMount } from "@shivaedev/identity/server/better-auth/mount.ts";
 
 const authentication = Effect.gen(function* () {
-  const database = yield* authDatabase(yield* Config.Redacted("DATABASE_URL"));
-  return yield* betterAuthMount({
-    database,
-    emailAndPassword: { enabled: true },
-    session: { cookieCache: { enabled: false } },
-  });
+	const database = yield* authDatabase(yield* Config.Redacted("DATABASE_URL"));
+	return yield* betterAuthMount({
+		database,
+		emailAndPassword: { enabled: true },
+		session: { cookieCache: { enabled: false } },
+	});
 });
 ```
 
@@ -145,7 +144,7 @@ A native client signs in through `/api/auth/sign-in/email` with `credentials: "o
 
 Native sign-out revokes the stored session. Signing in again while sending the current bearer replaces it and revokes the old session after successful sign-in. Streams keep their original request headers, so the old session ends with `Unauthorized` on the next revalidation; it never adopts the replacement. Keep cookie caching disabled for database-backed revocation and choose `streamRevalidationInterval` for the required delivery window.
 
-`appHost`'s `nativeOrigins` option admits those exact origins through the RPC transport guard and the auth routes. Wildcards, patterns and URLs with paths are rejected at startup. Keep the list aligned with `bearerSessions.origins`, Better Auth's `trustedOrigins` and the RPC session origin policy: the later origin policies alone cannot open the transport guard. Omit the option to keep the existing same-origin transport policy.
+`appHost`'s `nativeOrigins` option admits those exact origins through the RPC transport guard and the auth routes. Wildcards, patterns and URLs with paths are rejected at startup. Keep the list aligned with `bearerSessions.origins`, Better Auth's `trustedOrigins` and the RPC session origin policy: the later origin policies alone cannot open the transport guard. Without the option, the transport guard keeps its same-origin policy.
 
 The host answers native preflights with POST for RPC, GET and POST for auth, and only `Authorization` and `Content-Type` headers. Native responses echo the allowed origin exactly with `Vary: Origin`; auth responses expose `set-auth-token`. The host never enables CORS credentials. It strips cookies from admitted native requests before auth or RPC session resolution, so only the signed bearer session can authenticate them. This prevents native access from opening a cookie CSRF path, even if a caller sends a cookie. Resource authorization remains app-owned.
 
@@ -163,17 +162,17 @@ import { betterAuthSessions } from "@shivaedev/identity/server/adapters/betterAu
 import { trustedOrigins } from "@shivaedev/identity/server/origin.ts";
 
 const authentication = Effect.gen(function* () {
-  const database = yield* authDatabase(yield* Config.Redacted("DATABASE_URL"));
-  const mounted = yield* betterAuthMount(
-    { database, session: { cookieCache: { enabled: false } }, socialProviders: { github } },
-    { signIn: { accounts: allowedAccounts, recheckInterval: "5 minutes", rule: inOrganization } },
-  );
-  yield* mounted.revokeUnadmitted;
-  const sessions = {
-    origin: trustedOrigins({ allow: ["https://app.example"], missing: "reject" }),
-    provider: betterAuthSessions(mounted.admittedSessions((headers) => mounted.auth.api.getSession({ headers }))),
-  };
-  return { ...mounted, sessions };
+	const database = yield* authDatabase(yield* Config.Redacted("DATABASE_URL"));
+	const mounted = yield* betterAuthMount(
+		{ database, session: { cookieCache: { enabled: false } }, socialProviders: { github } },
+		{ signIn: { accounts: allowedAccounts, recheckInterval: "5 minutes", rule: inOrganization } },
+	);
+	yield* mounted.revokeUnadmitted;
+	const sessions = {
+		origin: trustedOrigins({ allow: ["https://app.example"], missing: "reject" }),
+		provider: betterAuthSessions(mounted.admittedSessions((headers) => mounted.auth.api.getSession({ headers }))),
+	};
+	return { ...mounted, sessions };
 });
 ```
 
@@ -199,18 +198,16 @@ import { Rpc, RpcGroup } from "effect/rpc";
 import { OptionalIdentity } from "@shivaedev/identity/identity.ts";
 import { MaybeAuthenticated } from "@shivaedev/identity/middleware.ts";
 
-export const Greetings = RpcGroup.make(
-  Rpc.make("Greeting", { success: Schema.String }),
-).middleware(MaybeAuthenticated);
+export const Greetings = RpcGroup.make(Rpc.make("Greeting", { success: Schema.String })).middleware(MaybeAuthenticated);
 
 export const GreetingHandlers = Greetings.toLayer({
-  Greeting: () =>
-    Effect.map(OptionalIdentity, (identity) =>
-      Option.match(identity, {
-        onNone: () => "hello anonymous",
-        onSome: ({ id }) => `hello ${id}`,
-      }),
-    ),
+	Greeting: () =>
+		Effect.map(OptionalIdentity, (identity) =>
+			Option.match(identity, {
+				onNone: () => "hello anonymous",
+				onSome: ({ id }) => `hello ${id}`,
+			}),
+		),
 });
 ```
 
@@ -230,7 +227,7 @@ Declare expected refusals with the shared tagged error schemas from [`@shivaedev
 
 ### Reading the signed-in user
 
-When a handler needs the current user's name and email, declare `AuthenticatedUser` and read `SessionUser`. `Identity` keeps its `{ id }` shape; the new middleware supplies both services for that invocation. Its provider must return `user: { id, name, email }`, described by `UserSessionShape`.
+When a handler needs the current user's name and email, declare `AuthenticatedUser` and read `SessionUser`. `Identity` keeps its `{ id }` shape; `AuthenticatedUser` supplies both services for that invocation. Its provider must return `user: { id, name, email }`, described by `UserSessionShape`.
 
 ```ts
 import { Effect, Layer, Schema } from "effect";
@@ -240,13 +237,13 @@ import { AuthenticatedUser } from "@shivaedev/identity/middleware.ts";
 import { authenticatedUserLayer } from "@shivaedev/identity/server/session.ts";
 
 export const Account = RpcGroup.make(
-  Rpc.make("Whoami", {
-    success: Schema.Struct({ id: Schema.String, name: Schema.String, email: Schema.String }),
-  }),
+	Rpc.make("Whoami", {
+		success: Schema.Struct({ id: Schema.String, name: Schema.String, email: Schema.String }),
+	}),
 ).middleware(AuthenticatedUser);
 
 export const AccountHandlers = Account.toLayer({
-  Whoami: () => Effect.map(SessionUser, (user) => user),
+	Whoami: () => Effect.map(SessionUser, (user) => user),
 });
 
 export const AccountServer = Layer.merge(AccountHandlers, authenticatedUserLayer(sessions));
@@ -265,21 +262,21 @@ import { AuthUnavailable, Unauthorized } from "@shivaedev/errors/taxonomy.ts";
 import { authenticatedUserWithProviderAccountsLayer } from "@shivaedev/identity/server/session.ts";
 
 const sessions = {
-  origin: trustedOrigins({ allow: ["https://app.example"], missing: "reject" }),
-  provider: betterAuthSessions(
-    (headers) => auth.api.getSession({ headers }),
-    (headers) => auth.api.listUserAccounts({ headers }),
-  ),
+	origin: trustedOrigins({ allow: ["https://app.example"], missing: "reject" }),
+	provider: betterAuthSessions(
+		(headers) => auth.api.getSession({ headers }),
+		(headers) => auth.api.listUserAccounts({ headers }),
+	),
 };
 
 const githubAccount = Effect.gen(function* () {
-  const user = yield* SessionUserWithProviderAccounts;
-  const accounts = yield* user.providerAccounts;
-  return accounts.find((account) => account.providerId === "github");
+	const user = yield* SessionUserWithProviderAccounts;
+	const accounts = yield* user.providerAccounts;
+	return accounts.find((account) => account.providerId === "github");
 });
 ```
 
-Declare `Schema.Union([AuthUnavailable, Unauthorized])` in the account-reading RPC's `error` schema: lookup failures now come from the handler's Effect. An outage fails with `AuthUnavailable`; a session that expires before the lookup fails with `Unauthorized`. Neither failure exposes provider exception details.
+Declare `Schema.Union([AuthUnavailable, Unauthorized])` in the account-reading RPC's `error` schema: lookup failures come from the handler's Effect. An outage fails with `AuthUnavailable`; a session that expires before the lookup fails with `Unauthorized`. Neither failure exposes provider exception details.
 
 The lookup uses the same transport headers and runs only when the handler evaluates `user.providerAccounts`. The boundary memoizes a successful result in that invocation's Effect context, including concurrent reads, without sharing it across requests or users. A failed lookup is not retained: the next read tries again. Identity-only handlers never run the accounts lookup. `SessionUserWithProviderAccountsValue.providerAccounts` is a required `Effect<readonly ProviderAccountValue[], AuthUnavailable | Unauthorized>`. Each result contains only `{ providerId: string, accountId: string }`; for example, GitHub's numeric user ID is the string `"123"`, not Better Auth's account-row id. `SessionUser` and `SessionUserValue` contain the base profile without accounts.
 
@@ -327,7 +324,7 @@ import { permissionLayer } from "@shivaedev/identity/server/permissions.ts";
 class ToolsPermission extends permissionMiddleware<ToolsPermission>()("app/ToolsPermission", UseTools) {}
 const Tools = RpcGroup.make(Rpc.make("tools", { success: Schema.String }).middleware(ToolsPermission));
 const handlers = Tools.toLayer({ tools: () => Effect.map(SessionUser, (user) => user.email) }).pipe(
-  Layer.provideMerge(permissionLayer(ToolsPermission, sessions)),
+	Layer.provideMerge(permissionLayer(ToolsPermission, sessions)),
 );
 ```
 
@@ -340,13 +337,15 @@ import { HttpRouter, HttpServerResponse } from "effect/http";
 import { permissionRoute } from "@shivaedev/identity/server/permissions.ts";
 
 const routes = HttpRouter.use((router) =>
-  router.add("GET", "/tools", permissionRoute(sessions, UseTools)(() =>
-    Effect.map(SessionUser, (user) => HttpServerResponse.text(user.email)),
-  )),
+	router.add(
+		"GET",
+		"/tools",
+		permissionRoute(sessions, UseTools)(() => Effect.map(SessionUser, (user) => HttpServerResponse.text(user.email))),
+	),
 );
 ```
 
-An operation on one record reads that record's owner and uses the application's access policy. With a request-local user, `const { role } = yield* Access.resolve(user.role)` recovers the application's closed role type; `yield* Access.requireAccess({ id: user.id, role }, UseTools, record.ownerId)` then permits an explicit `any` grant or an `own` grant for that owner. Keep these resource decisions in the handler or domain service. Browser interfaces can use `hasPermission(user, permission)` from `rpc/permission.ts` over the client session's grants; the server always resolves its own grants.
+An operation on one record reads that record's owner and uses the application's access policy. With a request-local user, `const { role } = yield* Access.resolve(user.role)` recovers the application's closed role type; `yield* Access.requireAccess({ id: user.id, role }, UseTools, record.ownerId)` then permits an explicit `any` grant or an `own` grant for that owner. Keep these resource decisions in the handler or domain service. Browser interfaces can use `hasPermission(user, permission)` from `@shivaedev/identity/permission.ts` over the client session's grants; the server always resolves its own grants.
 
 ### Session-scoped contract keys
 
@@ -356,7 +355,7 @@ The host's generated `$changes` handler accepts `{ queries: [{ query: "get", pay
 
 `authenticatedLayer`, `authenticatedUserLayer`, `authenticatedUserWithProviderAccountsLayer` and `permissionLayer` run scoped command invalidation inside the authenticated invocation. Successful commands publish their scoped keys after commit and omit keys the handler's transactions already published. A rejected transaction publishes no keys.
 
-Hosted applications use `Api.application.toLayer(...)` and let `appHost` own `$changes`. When migrating a custom change handler, accept query references and resolve them inside `Stream.unwrap`, after authentication has provided `Identity`:
+Hosted applications use `Api.application.toLayer(...)` and let `appHost` own `$changes`. A custom change handler accepts query references and resolves them inside `Stream.unwrap`, after authentication has provided `Identity`:
 
 ```ts
 import { Effect, Stream } from "effect";
@@ -364,13 +363,10 @@ import { resolveChanges } from "@shivaedev/identity/server/sessionKeys.ts";
 
 const changesRpc = Api.requests.get("preferences.$changes")!;
 const handlers = Api.toLayer({
-  "preferences.$changes": ({ queries }) => Stream.unwrap(
-    Effect.map(resolveChanges(changesRpc, queries), ({ subscription, context }) =>
-      changes.subscribe(subscription, context)
-    )
-  ),
-  "preferences.get": getPreference,
-  "preferences.save": savePreference,
+	"preferences.$changes": ({ queries }) =>
+		Stream.unwrap(Effect.map(resolveChanges(changesRpc, queries), ({ subscription, context }) => changes.subscribe(subscription, context))),
+	"preferences.get": getPreference,
+	"preferences.save": savePreference,
 });
 ```
 
@@ -385,12 +381,12 @@ import { Identity } from "@shivaedev/identity/identity.ts";
 import { commandChanges } from "@shivaedev/identity/server/commandChanges.ts";
 
 const authentication = Layer.succeed(MyAuthentication, (effect, { headers, rpc, payload }) =>
-  Effect.gen(function* () {
-    const session = yield* requireTransportSession(headers, rpc);
-    return yield* authorizeReads(commandChanges(effect, rpc, payload), { rpc, payload }, Option.some({ id: session.user.id })).pipe(
-      Effect.provideService(Identity, { id: session.user.id })
-    );
-  })
+	Effect.gen(function* () {
+		const session = yield* requireTransportSession(headers, rpc);
+		return yield* authorizeReads(commandChanges(effect, rpc, payload), { rpc, payload }, Option.some({ id: session.user.id })).pipe(
+			Effect.provideService(Identity, { id: session.user.id }),
+		);
+	}),
 );
 ```
 
@@ -404,9 +400,9 @@ Set `SessionPolicy.streamRevalidationInterval` to an Effect `Duration.Input` to
 
 ```ts
 const sessions = {
-  origin: trustedOrigins({ allow: ["https://app.example.com"], missing: "reject" }),
-  provider: betterAuthSessions((headers) => auth.api.getSession({ headers })),
-  streamRevalidationInterval: "5 seconds",
+	origin: trustedOrigins({ allow: ["https://app.example.com"], missing: "reject" }),
+	provider: betterAuthSessions((headers) => auth.api.getSession({ headers })),
+	streamRevalidationInterval: "5 seconds",
 };
 ```
 
@@ -416,14 +412,12 @@ An `AuthUnavailable` failure during revalidation leaves the stream running and t
 
 Session resolution reads `HttpServerRequest`: the HTTP POST or WebSocket upgrade request. Credentials and Origin supplied inside an RPC message cannot replace those transport headers. An application-owned middleware can use `transportHeaders(rpcHeaders)` for the same source of headers.
 
-react’s `actionTrace` groups an action’s RPC Effects under one browser trace; editor saves and create submissions group their save Effects automatically. Native `RpcClient.layerProtocolHttp` with `FetchHttpClient.layer` sends W3C `traceparent` on each request. appHost continues that HTTP trace for RPC handling, including without an installed tracer or exporter. Each RPC span records `request.id` and `rpc.method`; native SQL spans executed by the handler inherit that trace.
-
-When a handler enqueues through jobs, the job stores the current span context. Wrap enqueueing in an application-named producer span with `Effect.withSpan("Receipt.enqueue", { kind: "producer" })` to show the enqueue operation in the action trace. Worker attempts run in their own trace, linked back to the captured sender span. A trace viewer can follow that link between the action and its job.
-
 Tracing uses the RPC headers for correlation. `requestTracingLayer()` accepts `x-request-id`; `{ header: "x-correlation-id" }` changes the name. Missing, malformed or oversized values receive generated 32-character lowercase hexadecimal ids. A request id reaches the `RequestId` service, log annotations as `requestId`, and the server span as `request.id`; the RPC method reaches both as `rpc.method`.
 
 Caller-chosen request ids are correlation data. Keep authorization tied to the authenticated identity.
 
+The app host of `@shivaedev/server` adds this tracing to its RPC group and continues the caller's W3C trace; react's [action tracing](https://github.com/ShivaeDev/platform/blob/main/packages/react/README.md#trace-an-action-across-rpcs) follows one browser action through RPC, SQL and a queued job.
+
 ### Signed-in story preconditions
 
 Use `testUtils()` from `better-auth/plugins` in a test-only Better Auth instance with the host's database, secret and cookie policy. Keep the plugin out of production auth options.
@@ -436,14 +430,14 @@ import { testUtils } from "better-auth/plugins";
 import { signedInUser } from "@shivaedev/identity/server/better-auth/testing.ts";
 
 const testAuth = betterAuth({
-  ...options,
-  plugins: [...(options.plugins ?? []), testUtils()],
+	...options,
+	plugins: [...(options.plugins ?? []), testUtils()],
 });
 const { user, headers, cookies } = await signedInUser(testAuth, {
-  email: "member@example.test",
-  name: "Member",
-  providerAccounts: [{ providerId: "github", accountId: "123" }],
-  role: "user,admin",
+	email: "member@example.test",
+	name: "Member",
+	providerAccounts: [{ providerId: "github", accountId: "123" }],
+	role: "user,admin",
 });
 ```
 
@@ -458,25 +452,29 @@ import { seedCookies } from "@shivaedev/test-story/server/seedCookies.ts";
 import { signedInUser, storedProviderAccounts } from "@shivaedev/identity/server/better-auth/testing.ts";
 
 const member = app.trait("account", "a member starts signed in with GitHub", function* ({ auth }) {
-  const { cookies } = yield* Effect.promise(() => signedInUser(auth, {
-    email: "member@example.test",
-    name: "Member",
-    providerAccounts: [{ providerId: "github", accountId: "123" }],
-  }));
-  yield* seedCookies(cookies);
+	const { cookies } = yield* Effect.promise(() =>
+		signedInUser(auth, {
+			email: "member@example.test",
+			name: "Member",
+			providerAccounts: [{ providerId: "github", accountId: "123" }],
+		}),
+	);
+	yield* seedCookies(cookies);
 });
 
 app.it("the member's provider account stores no credentials", [member], function* ({ session, story }) {
-  const { user } = yield* session();
-  const accounts = yield* Effect.promise(() => storedProviderAccounts(story.engine.auth, user.id));
-  expect(accounts).toEqual([{
-    providerId: "github",
-    accountId: "123",
-    hasAccessToken: false,
-    hasRefreshToken: false,
-    hasIdToken: false,
-    hasPassword: false,
-  }]);
+	const { user } = yield* session();
+	const accounts = yield* Effect.promise(() => storedProviderAccounts(story.engine.auth, user.id));
+	expect(accounts).toEqual([
+		{
+			providerId: "github",
+			accountId: "123",
+			hasAccessToken: false,
+			hasRefreshToken: false,
+			hasIdToken: false,
+			hasPassword: false,
+		},
+	]);
 });
 ```
 
@@ -492,32 +490,32 @@ Register the Effect with a worker schedule, as the starter does at midnight UTC.
 
 Import the module that defines the name; there is no package-root entry. Paths below follow `@shivaedev/identity/`.
 
-| Module | Names and purpose |
-| --- | --- |
-| `identity.ts` | `RequestId`, `Identity`, `OptionalIdentity`, `SessionUser`, `SessionUserWithProviderAccounts`: request-local services. |
-| `middleware.ts` | `RequestTracing`, `Authenticated`, `AuthenticatedUser`, `AuthenticatedUserWithProviderAccounts`, `MaybeAuthenticated`: native RPC middleware declarations. |
-| `permission.ts` | Native permission middleware declarations and predicates over resolved grants. |
-| `server/permissions.ts` | Permission middleware Layers and HTTP route guards. |
-| `server/session.ts` | `authenticatedLayer`, `maybeAuthenticatedLayer`, `authenticatedUserLayer`, `authenticatedUserWithProviderAccountsLayer`, `withSessionUser`, `resolveSession`: session middleware implementations and the identity boundary. |
-| `server/adapters/betterAuthSessions.ts` | `betterAuthSessions(getSession, getProviderAccounts?)`: a session provider from Better Auth lookups. |
-| `server/origin.ts` | `trustedOrigins({ allow, missing })`: an exact Origin allowlist. |
-| `server/local.ts` | `localRpcGuard`, `loopbackOnly`, `sameOrigin`, `trustedProxyPeer`, `trustedProxyRanges`: loopback and proxy guards. |
-| `server/transportHeaders.ts` | `transportHeaders(rpcHeaders)`: the headers used for a transport-level decision. |
-| `server/tracing.ts` | `requestTracingLayer({ header?, sensitive? })`: the `RequestTracing` implementation. |
-| `server/sessionKeys.ts` | `resolveChanges`: session-scoped change subscriptions for custom change handlers. |
-| `server/better-auth/mount.ts` | `betterAuthMount(options, { signIn?, bearerSessions? })`, returning `{ auth, routes, admittedSessions, revokeUnadmitted }`, and `authDatabase(url, { max?, application_name? }?)`: native auth routes, the sign-in policy and a scoped PostgreSQL pool. |
-| `server/better-auth/allowedAccounts.ts` | `AllowedAccounts`, `allowedAccounts`: the provider-account list Schema and its `AUTH_ALLOWED_ACCOUNTS` Config. |
-| `server/better-auth/signInGate.ts` | `SignInPolicy`: the `accounts`, `rule` and `recheckInterval` of a sign-in policy. |
-| `server/better-auth/revokeUnadmitted.ts` | `RevokedSessions`: the `{ users, sessions }` counts of a revocation. |
-| `server/better-auth/userProfiles.ts` | Public profile lookups for other users. |
-| `server/better-auth/sweepExpiredSessions.ts` | `sweepExpiredSessions`: delete expired sessions through the application's SQL client and return the number removed. |
-| `server/better-auth/testDatabase.ts` | `authTestDatabase(pool)`: test-only identity/session readouts and faults for the default PostgreSQL auth schema. |
-| `server/better-auth/testing.ts` | `signedInUser(auth, fields)`, `storedProviderAccounts(auth, userId)`: test-only minted user sessions and credential storage observations. |
+| Module                                       | Names and purpose                                                                                                                                                                                                                                                         |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `identity.ts`                                | `RequestId`, `Identity`, `OptionalIdentity`, `SessionUser`, `SessionUserWithProviderAccounts`: request-local services.                                                                                                                                                    |
+| `middleware.ts`                              | `RequestTracing`, `Authenticated`, `AuthenticatedUser`, `AuthenticatedUserWithProviderAccounts`, `MaybeAuthenticated`: native RPC middleware declarations.                                                                                                                |
+| `permission.ts`                              | `permissionMiddleware`, `hasPermission`, `requirePermission`: native permission middleware declarations and predicates over resolved grants.                                                                                                                              |
+| `server/permissions.ts`                      | `permissionLayer`, `permissionRoute`: permission middleware Layers and HTTP route guards.                                                                                                                                                                                 |
+| `server/session.ts`                          | `authenticatedLayer`, `maybeAuthenticatedLayer`, `authenticatedUserLayer`, `authenticatedUserWithProviderAccountsLayer`, `withSessionUser`, `resolveSession`: session middleware implementations and the identity boundary.                                               |
+| `server/adapters/betterAuthSessions.ts`      | `betterAuthSessions(getSession, getProviderAccounts?)`: a session provider from Better Auth lookups.                                                                                                                                                                      |
+| `server/origin.ts`                           | `trustedOrigins({ allow, missing })`: an exact Origin allowlist.                                                                                                                                                                                                          |
+| `server/local.ts`                            | `localRpcGuard`, `loopbackOnly`, `sameOrigin`, `trustedProxyPeer`, `trustedProxyRanges`: loopback and proxy guards.                                                                                                                                                       |
+| `server/transportHeaders.ts`                 | `transportHeaders(rpcHeaders)`: the headers used for a transport-level decision.                                                                                                                                                                                          |
+| `server/tracing.ts`                          | `requestTracingLayer({ header?, sensitive? })`: the `RequestTracing` implementation.                                                                                                                                                                                      |
+| `server/sessionKeys.ts`                      | `resolveChanges`: session-scoped change subscriptions for custom change handlers.                                                                                                                                                                                         |
+| `server/commandChanges.ts`                   | `commandChanges(effect, rpc, payload)`: scoped command invalidation for custom authentication middleware.                                                                                                                                                                 |
+| `server/better-auth/mount.ts`                | `betterAuthMount(options, { signIn?, bearerSessions?, roles? })`, returning `{ auth, routes, sessions, admittedSessions, revokeUnadmitted }`, and `authDatabase(url, { max?, application_name? }?)`: native auth routes, the sign-in policy and a scoped PostgreSQL pool. |
+| `server/better-auth/allowedAccounts.ts`      | `AllowedAccounts`, `allowedAccounts`: the provider-account list Schema and its `AUTH_ALLOWED_ACCOUNTS` Config.                                                                                                                                                            |
+| `server/better-auth/signInGate.ts`           | `SignInPolicy`: the `accounts`, `rule` and `recheckInterval` of a sign-in policy.                                                                                                                                                                                         |
+| `server/better-auth/revokeUnadmitted.ts`     | `RevokedSessions`: the `{ users, sessions }` counts of a revocation.                                                                                                                                                                                                      |
+| `server/better-auth/userProfiles.ts`         | Public profile lookups for other users.                                                                                                                                                                                                                                   |
+| `server/better-auth/sweepExpiredSessions.ts` | `sweepExpiredSessions`: delete expired sessions through the application's SQL client and return the number removed.                                                                                                                                                       |
+| `server/better-auth/testDatabase.ts`         | `authTestDatabase(pool)`: test-only identity/session readouts and faults for the default PostgreSQL auth schema.                                                                                                                                                          |
+| `server/better-auth/testing.ts`              | `signedInUser(auth, fields)`, `storedProviderAccounts(auth, userId)`: test-only minted user sessions and credential storage observations.                                                                                                                                 |
 
 ### Install, setup and limits
 
 Install `@shivaedev/identity` with `effect` as its peer. Everything outside `server/better-auth/` works with only `effect` installed, including the Promise-based `betterAuthSessions` adapter. Better Auth mounts and test fixtures need the optional peers `better-auth` and `pg`; `sweepExpiredSessions` needs only the application's Effect SQL client. Browser code imports only `identity.ts`, `middleware.ts` and `permission.ts`.
-
 - The package needs Node 24 or newer.
 - Keep the auth provider's configuration, cookie settings and resource authorization in the application. The session adapter takes a session lookup and an optional provider-account lookup and returns a session result; it does not write provider refresh cookies into RPC responses.
 - Without an `HttpServerRequest`, `transportHeaders` falls back to the supplied RPC headers. An application using another transport must decide what headers it can trust.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/identity",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Request identity, sessions, transport trust and permission enforcement for Effect RPC servers",
   "keywords": [
     "effect"
@@ -46,14 +46,14 @@
   "dependencies": {
     "@shivaedev/access": "0.1.1",
     "@shivaedev/changes": "0.5.0",
-    "@shivaedev/contract": "0.19.0",
+    "@shivaedev/contract": "0.19.1",
     "@shivaedev/errors": "0.1.0",
     "@shivaedev/sql": "0.24.0"
   },
   "devDependencies": {
     "@effect/platform-node": "4.0.5",
     "@effect/sql-pg": "4.0.5",
-    "@shivaedev/quality": "0.43.0",
+    "@shivaedev/quality": "0.44.0",
     "@shivaedev/test-sql": "0.10.2",
     "@shivaedev/test-story": "0.22.0",
     "@types/node": "24.19.2",