@gjermundgaraba/clankerauth-sdk 0.5.1 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # @gjermundgaraba/clankerauth-sdk
 
-Effect-native [Clanker Auth](https://github.com/gjermundgaraba/clankerauth) verification. Verifies JWT access tokens and API keys, including the tokens a reverse proxy obtains through the issuer's forward auth for browser sessions. Optional **effect-actions** integration provides request-scoped identity and OAuth discovery.
+Effect-native [Clanker Auth](https://github.com/gjermundgaraba/clankerauth) verification. Verifies JWT access tokens and API keys, including the tokens a reverse proxy obtains through the issuer's forward auth for browser sessions. Optional **effect-actions** integration provides request-scoped identity, OAuth discovery, scope enforcement and a `session` contract a browser page can import on its own.
 
 ## Install
 
@@ -14,6 +14,17 @@ Install Effect in the application:
 vp add effect@4.0.0-rc.116
 ```
 
+## Entry points
+
+| Import                             | Needs effect-actions | Browser safe | What it holds                                     |
+| ---------------------------------- | -------------------- | ------------ | ------------------------------------------------- |
+| `…/clankerauth-sdk`                | no                   | no           | `Verifier`, `RequestPolicy`                       |
+| `…/clankerauth-sdk/errors`         | no                   | **yes**      | the error schemas and `authenticationErrors`      |
+| `…/clankerauth-sdk/session`        | yes                  | **yes**      | the `session` contract, `Principal`, `signOutUrl` |
+| `…/clankerauth-sdk/effect-actions` | yes                  | no           | `Resource`, `CurrentPrincipal`                    |
+
+The package is free of side effects, so a bundler drops what a page does not use. Errors are **not** re-exported from the root: a shared contract imports them from `/errors`, and nothing about that import pulls token verification into a browser bundle.
+
 ## Verify tokens directly
 
 Core consumers do not need effect-actions or `skipLibCheck`.
@@ -21,28 +32,23 @@ Core consumers do not need effect-actions or `skipLibCheck`.
 ```ts
 import { Effect } from "effect";
 import { FetchHttpClient } from "effect/unstable/http";
-import { McpProtocol } from "effect/unstable/ai";
 import { Verifier } from "@gjermundgaraba/clankerauth-sdk";
 
 const makeVerifier = Verifier.make({
   issuer: "https://auth.internal/api/auth",
-  resource: "https://notes.internal/api",
+  resource: "https://notes.internal/",
   requiredScopes: ["notes:read"],
 }).pipe(Effect.provide(FetchHttpClient.layer));
 // Acquire once, then use verifier.verify(authorization) or verifier.verifyToken(token).
 ```
 
-## Protect effect-actions routes
+## One resource per application
 
-Install the optional peer dependency and import the integration subpath:
+Register **one** resource in the Clanker Auth dashboard, identified by the application's public origin root, written with its trailing slash: `https://notes.internal/`. That one resource covers `/api`, `/mcp` and any socket, with one RFC 9728 document at `/.well-known/oauth-protected-resource` and one `forward_auth` block in the proxy.
 
-```sh
-vp add @gjermundgaraba/effect-actions@0.2.0
-```
+`Resource.make` takes the public URL and derives that identifier itself, so the application never writes it twice and never writes a form an MCP client would rewrite. Any path on the URL is discarded. The official client's own `checkResourceAllowed` accepts an origin-root resource for an endpoint beneath it.
 
-Core and integration declarations both type-check without `skipLibCheck`.
-
-Register a resource in the Clanker Auth dashboard. Its identifier is the exact audience URL, not just an origin. Acquire one resource capability per protected audience at application construction, not per request.
+Acquire the resource once at application construction, never per request.
 
 ```ts
 import { Effect, Layer } from "effect";
@@ -54,66 +60,141 @@ import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 // Http and app are your effect-actions HTTP binding and implemented group.
 const routes = Layer.unwrap(
   Effect.gen(function* () {
-    const api = yield* Resource.make({
-      issuer: "https://auth.internal/api/auth",
-      resource: "https://notes.internal/api",
-      scopes: ["notes:read", "notes:write"],
-      requiredScopes: ["notes:read"],
-    });
-    const mcp = yield* Resource.make({
+    const notes = yield* Resource.make({
       issuer: "https://auth.internal/api/auth",
-      resource: "https://notes.internal/mcp",
-      scopes: ["notes:read", "notes:write"],
-      requiredScopes: ["notes:read"],
+      publicUrl: new URL("https://notes.internal"),
+      scopes: { read: "notes:read", write: "notes:write" },
     });
+
     return Layer.mergeAll(
-      api.discovery.layer,
-      mcp.discovery.layer,
-      Http.layer(app).pipe(Layer.provide(Resource.middleware(api).layer)),
+      notes.discovery.layer,
+      Http.layer({ before: notes.authorize }, app, notes.session).pipe(
+        Layer.provide(Resource.middleware(notes).layer),
+      ),
       ActionMcp.layerHttp(
-        { name: "notes", version: "1.0.0", path: "/mcp", protocols: [McpProtocol.v2026_07_28] },
+        {
+          name: "notes",
+          version: "1.0.0",
+          path: "/mcp",
+          protocols: [McpProtocol.v2026_07_28],
+          errors: authenticationErrors,
+          before: notes.authorize,
+        },
         app,
-      ).pipe(Layer.provide(Resource.middleware(mcp).layer)),
+      ).pipe(Layer.provide(Resource.middleware(notes).layer)),
     );
   }),
 ).pipe(Layer.provide(FetchHttpClient.layer));
 ```
 
-Serve this layer with Effect's `HttpRouter` and your Node server layer. If using `@effect/platform-node`, install the matching `@effect/platform-node@4.0.0-rc.116` package. Discovery is public; do not wrap it in authentication. Discovery cache policy belongs to the host. Authentication responses use `Cache-Control: no-store`.
+Serve this layer with Effect's `HttpRouter` and your Node server layer. If using `@effect/platform-node`, install the matching `@effect/platform-node@4.0.0-rc.116` package. Discovery is public; do not wrap it in authentication. Discovery cache policy belongs to the host. Every authentication response carries `Cache-Control: no-store`.
 
 The supplied `HttpClient` must not retry credential exchanges or follow redirects. The SDK overrides only FetchHttpClient's redirect policy to reject redirects, preserves other caller-provided fetch defaults, and never installs retry middleware.
 
-An action reads identity from `CurrentPrincipal` and enforces its own permissions:
+## Scope enforcement
+
+An application names its scopes once and writes no authorization code. Each action declares what it does to the resource, and `resource.authorize` is the surface's pre-handler hook: it runs before every handler on every surface — HTTP, MCP, Toolkit, CLI — so no handler can forget it.
 
 ```ts
-import { Effect } from "effect";
-import { Forbidden } from "@gjermundgaraba/clankerauth-sdk";
-import { CurrentPrincipal } from "@gjermundgaraba/clankerauth-sdk/effect-actions";
-
-const write = Effect.gen(function* () {
-  const principal = yield* CurrentPrincipal;
-  if (!principal.scopes.includes("notes:write")) {
-    return yield* new Forbidden({ message: "Write permission required" });
-  }
-  return principal.subject;
-});
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
+import { authenticationErrors } from "@gjermundgaraba/clankerauth-sdk/errors";
+
+const Notes = ActionGroup.make(
+  { name: "notes" },
+  Action.make("list", { description: "List notes", access: "read", success: Notes }),
+  Action.make("write", { description: "Write a note", access: "write", success: Note }),
+);
+
+// Declared on the surface, because the surface is what renders them — including the
+// hook's own refusals, which is why the group no longer lists `InsufficientScope`.
+const Http = ActionHttp.make({ apiPath: "/api", errors: authenticationErrors }, Notes, Session);
+
+// And bound once per surface, so no handler and no group can forget it.
+const routes = Http.layer({ before: notes.authorize }, Notes.implement(handlers), notes.session);
 ```
 
-Declare `Forbidden` in that action/group's error schemas. Middleware authenticates the request; it does not infer per-action policy or filter MCP tool discovery.
+`scopes.read` is required at verification, so a read needs nothing further. `scopes.write` is what an `access: "write"` action additionally needs; leave it out and every action passes, which is how a single-scope application is expressed. `InsufficientScope` is a 403 naming **only** the missing scope, so a refusal never enumerates the resource's permissions.
 
-A principal contains `subject`, `scopes`, and `actor`: either `{ kind: "client", clientId }` or `{ kind: "key", keyId }`. The resource also exposes `verifier.verify(authorization)` and `verifier.verifyToken(token)` as Effects.
+A forward-auth browser token carries **every** scope the resource defines, because the issuer mints it for the signed-in owner and not for a program. The write scope therefore gates agents and API keys, not the owner at a keyboard: give a read-only agent or key only `scopes.read` and the same rule refuses its writes.
 
-JWTs are checked against issuer, audience, EdDSA signature, token type, required claims, expiry and scopes. Sender-constrained tokens are rejected. JWKS lookups are cached for ten minutes. Unknown keys trigger one refresh and resolution retry, with a thirty-second cooldown to bound provider traffic. Failed miss-triggered refreshes also cool down and return 503; still-valid cached keys remain usable. Initial lookup failures are not retained. Removed keys can remain trusted until cache expiry. API keys are checked online on **every request**, so revocation is effective immediately. A resource that accepts only OAuth access tokens sets `apiKeys: false`; key-shaped bearers then fail as `Unauthorized` without contacting the issuer. Verification has a five-second deadline.
+An action reads identity from `CurrentPrincipal`, which contains `subject`, `scopes`, `actor` — either `{ kind: "client", clientId }` or `{ kind: "key", keyId }` — and `expiresAt`: an access token's verified `exp` in epoch milliseconds, so a host bounding a connection to its credential never decodes the token again. It is `undefined` for an API key, which carries no token lifetime and is re-verified on every request; choose your own bound for those.
 
-The bundled issuer does not configure automatic signing-key rotation. Immediate-use rotation is supported, but tokens signed by a new key can be rejected during the thirty-second cooldown after a successful lookup. Publish-before-use avoids that short window; it is not mandatory.
+A hook refusal is a plain declared error: effect-actions encodes it with the schema's status and `Cache-Control: no-store`, and adds no `WWW-Authenticate`. Challenge headers come from admission — `Resource.middleware` and `admit` — which is what a client onboarding through RFC 9728 reads. No current client reads the header on a scope refusal, because an MCP denial is a tool error.
+
+Middleware authenticates the request and the hook authorizes it; neither filters MCP tool discovery.
+
+## Outside the router
+
+A socket, a Node `upgrade` handler or a per-request endpoint verifies the same credential against the same resource, and renders the same refusal, with `admit`. The access level is required, so the call says what the credential is for:
+
+```ts
+const admission = await Effect.runPromise(notes.admit(request.headers.authorization, "write"));
+
+if (!admission.ok) {
+  const { status, headers, body } = admission.refusal;
+  response.writeHead(status, headers).end(body);
+  return;
+}
+
+connect(admission.principal);
+```
+
+The refusal carries each error's own status (401/403/429/503), the RFC 6750 challenge including the no-credential case, `Cache-Control: no-store`, and the error's JSON encoding. `Resource.middleware` is built on the same function at `"read"`, so a router and a socket can never answer differently.
+
+The resource also exposes `verifier.verify(authorization)` and `verifier.verifyToken(token)` as Effects for callers that render their own responses.
+
+## Request policy
+
+Forward auth makes a browser's credential ambient: the proxy attaches an `Authorization` header to whatever the browser sends, including a cross-site navigation. So an application behind it checks where a request came from before anything reads the credential.
+
+```ts
+import { RequestPolicy } from "@gjermundgaraba/clankerauth-sdk";
+
+const policy = RequestPolicy.make({
+  publicUrl: new URL("https://notes.internal"),
+  allowedOrigins: ["wtf://app"], // a desktop shell's private renderer scheme
+});
+
+const routes = protectedRoutes.pipe(Layer.provide(policy.middleware.layer));
+
+// The same decision from a Node upgrade handler, with no services:
+if (
+  !policy.allows({
+    target: request.url,
+    host: request.headers.host,
+    origin: request.headers.origin,
+  })
+) {
+  socket.end("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
+}
+```
+
+Both checks are raw string comparisons on the headers as sent. Nothing is parsed, so nothing throws and no normalization widens what is accepted: `notes.internal` and `notes.internal:443` are different hosts here, as they are to a browser's cookie. A request with no `Host` is refused. An absent `Origin` is allowed; a present one must match exactly. `/healthz` is the one path answered without either check, because a container probe reaches the app on its bind address and carries neither header; it is fixed, not configurable. This is not authentication, and it does not set body limits or security headers — those stay the application's.
 
 ## Browser applications
 
-Browser apps do not use this package. Put them behind a reverse proxy with the issuer's forward auth, described in the Clanker Auth README; the proxy adds an `Authorization` header the same verifier above accepts.
+A browser page holds no credential of its own: put it behind a reverse proxy with the issuer's forward auth, described in the Clanker Auth README, and the proxy adds the `Authorization` header this package verifies. What the page does need is who it is signed in as, and a way out:
+
+```ts
+import { Principal, Session, signOutUrl } from "@gjermundgaraba/clankerauth-sdk/session";
+
+// `Session` is the contract; the server answers it with `resource.session`.
+const principal: Principal = await api.session.whoami({ payload: {} });
+link.href = signOutUrl(principal.issuer, `${location.origin}/`);
+```
+
+`Principal` is `{ subject, issuer, scopes }`. `signOutUrl` points at the issuer's `/forward-auth/logout?rd=…`, which ends the issuer session and every app's forward cookie; it is a plain link. On the server, `resource.session` is the same group already implemented from the verified credential — pass it to the HTTP binding beside your own application, and delete the hand-written `whoami`.
 
 ## Errors and observability
 
-Schema-tagged errors: `Unauthorized` (401), `Forbidden` (403), `RateLimited` (429) and `ProviderUnavailable` (503). Invalid construction fails with `ConfigurationError`.
+Schema-tagged errors, all from `@gjermundgaraba/clankerauth-sdk/errors`: `Unauthorized` (401), `InsufficientScope` (403), `RateLimited` (429) and `ProviderUnavailable` (503), collected as `authenticationErrors`. Invalid construction fails with `ConfigurationError`.
+
+There is one 403. A credential that is valid but lacks a scope is `InsufficientScope`; a credential that is not this resource's at all — the wrong audience, or an API key with no grant here, which the issuer answers `403` for — is `Unauthorized`, because from the resource's side those are the same thing.
+
+JWTs are checked against issuer, audience, EdDSA signature, token type, required claims, expiry and scopes. Sender-constrained tokens are rejected. JWKS lookups are cached for ten minutes. Unknown keys trigger one refresh and resolution retry, with a thirty-second cooldown to bound provider traffic. Failed miss-triggered refreshes also cool down and return 503; still-valid cached keys remain usable. Initial lookup failures are not retained. Removed keys can remain trusted until cache expiry. API keys are checked online on **every request**, so revocation is effective immediately. A resource that accepts only OAuth access tokens sets `apiKeys: false`; key-shaped bearers then fail as `Unauthorized` without contacting the issuer. Verification has a five-second deadline.
+
+The bundled issuer does not configure automatic signing-key rotation. Immediate-use rotation is supported, but tokens signed by a new key can be rejected during the thirty-second cooldown after a successful lookup. Publish-before-use avoids that short window; it is not mandatory.
 
 The SDK Resource adapter owns authentication error encoding and challenge headers; effect-actions supplies request-scoped identity and the no-store response policy. Defects and interruption are not relabeled as authentication rejection. Named effects supply tracing boundaries; application logging/tracing layers remain caller-owned. No `onFailure` callbacks or hidden runtime.
 

package/dist/errors.d.ts

@@ -1,9 +1,14 @@
-import { Effect, Schema } from "effect";
-import { type Headers, HttpServerResponse } from "effect/unstable/http";
+/**
+ * Every refusal this package produces, as schemas. This entry point is browser-safe:
+ * a shared contract declares these on its surface and a browser client decodes them,
+ * without pulling token verification or its cryptography into the bundle.
+ *
+ * Schemas define public responses. Diagnostic causes are internal, non-enumerable fields.
+ */
+import { Schema } from "effect";
 declare const Unauthorized_base: Schema.Class<Unauthorized, Schema.TaggedStruct<"Unauthorized", {
     readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
-/** Schemas define public responses. Diagnostic causes are internal, non-enumerable fields. */
 export declare class Unauthorized extends Unauthorized_base {
     readonly cause?: unknown;
     constructor(options: {
@@ -11,11 +16,6 @@ export declare class Unauthorized extends Unauthorized_base {
         readonly cause?: unknown;
     });
 }
-declare const Forbidden_base: Schema.Class<Forbidden, Schema.TaggedStruct<"Forbidden", {
-    readonly message: Schema.String;
-}>, import("effect/Cause").YieldableError>;
-export declare class Forbidden extends Forbidden_base {
-}
 declare const RateLimited_base: Schema.Class<RateLimited, Schema.TaggedStruct<"RateLimited", {
     readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
@@ -31,13 +31,24 @@ export declare class ProviderUnavailable extends ProviderUnavailable_base {
         readonly cause?: unknown;
     });
 }
+declare const InsufficientScope_base: Schema.Class<InsufficientScope, Schema.TaggedStruct<"InsufficientScope", {
+    readonly scope: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A verified credential lacks one scope the requested access needs. It names only
+ * the missing scope, so a refusal never enumerates the resource's permissions.
+ */
+export declare class InsufficientScope extends InsufficientScope_base {
+}
 declare const ConfigurationError_base: Schema.Class<ConfigurationError, Schema.TaggedStruct<"ConfigurationError", {
     readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 export declare class ConfigurationError extends ConfigurationError_base {
 }
-export declare const authenticationErrors: readonly [typeof Unauthorized, typeof Forbidden, typeof RateLimited, typeof ProviderUnavailable];
-export type AuthenticationError = Unauthorized | Forbidden | RateLimited | ProviderUnavailable;
-/** Encode one of the declared schemas as JSON with its `httpApiStatus`. Undeclared errors are defects. */
-export declare const encodeError: <const Schemas extends ReadonlyArray<Schema.Top>>(schemas: Schemas) => (error: Schemas[number]["Type"], headers?: Headers.Input) => Effect.Effect<HttpServerResponse.HttpServerResponse, never, { [K in keyof Schemas]: Schemas[K]["EncodingServices"]; }[number]>;
+/**
+ * What verification, admission and the authorization hook refuse with — one list, so a
+ * surface declares `errors: authenticationErrors` and answers every refusal the same way.
+ */
+export declare const authenticationErrors: readonly [typeof Unauthorized, typeof InsufficientScope, typeof RateLimited, typeof ProviderUnavailable];
+export type AuthenticationError = Unauthorized | InsufficientScope | RateLimited | ProviderUnavailable;
 export {};

package/dist/errors.js

@@ -1,14 +1,17 @@
-import { Effect, Schema, SchemaAST } from "effect";
-import { HttpServerResponse } from "effect/unstable/http";
-/** Schemas define public responses. Diagnostic causes are internal, non-enumerable fields. */
+/**
+ * Every refusal this package produces, as schemas. This entry point is browser-safe:
+ * a shared contract declares these on its surface and a browser client decodes them,
+ * without pulling token verification or its cryptography into the bundle.
+ *
+ * Schemas define public responses. Diagnostic causes are internal, non-enumerable fields.
+ */
+import { Schema } from "effect";
 export class Unauthorized extends Schema.TaggedError()("Unauthorized", { message: Schema.String }, { httpApiStatus: 401 }) {
     constructor(options) {
         super({ message: options.message });
         Object.defineProperty(this, "cause", { value: options.cause });
     }
 }
-export class Forbidden extends Schema.TaggedError()("Forbidden", { message: Schema.String }, { httpApiStatus: 403 }) {
-}
 export class RateLimited extends Schema.TaggedError()("RateLimited", { message: Schema.String }, { httpApiStatus: 429 }) {
 }
 export class ProviderUnavailable extends Schema.TaggedError()("ProviderUnavailable", { operation: Schema.String }, { httpApiStatus: 503 }) {
@@ -17,24 +20,21 @@ export class ProviderUnavailable extends Schema.TaggedError()("ProviderUnavailab
         Object.defineProperty(this, "cause", { value: options.cause });
     }
 }
+/**
+ * A verified credential lacks one scope the requested access needs. It names only
+ * the missing scope, so a refusal never enumerates the resource's permissions.
+ */
+export class InsufficientScope extends Schema.TaggedError()("InsufficientScope", { scope: Schema.String }, { httpApiStatus: 403 }) {
+}
 export class ConfigurationError extends Schema.TaggedError()("ConfigurationError", { message: Schema.String }) {
 }
+/**
+ * What verification, admission and the authorization hook refuse with — one list, so a
+ * surface declares `errors: authenticationErrors` and answers every refusal the same way.
+ */
 export const authenticationErrors = [
     Unauthorized,
-    Forbidden,
+    InsufficientScope,
     RateLimited,
     ProviderUnavailable,
 ];
-/** Encode one of the declared schemas as JSON with its `httpApiStatus`. Undeclared errors are defects. */
-export const encodeError = (schemas) => {
-    const encode = HttpServerResponse.schemaJson(Schema.Union(schemas));
-    return (error, headers) => {
-        const schema = schemas.find((schema) => Schema.is(schema)(error));
-        if (schema === undefined)
-            return Effect.die(new Error("Undeclared error"));
-        return encode(error, {
-            status: SchemaAST.resolveAt("httpApiStatus")(schema.ast) ?? 500,
-            headers,
-        }).pipe(Effect.orDie);
-    };
-};

package/dist/index.d.ts

@@ -1,3 +1,2 @@
 export * as Verifier from "./verify.ts";
-export type { Principal } from "./verify.ts";
-export { Unauthorized, Forbidden, RateLimited, ProviderUnavailable, ConfigurationError, type AuthenticationError, } from "./errors.ts";
+export * as RequestPolicy from "./request-policy.ts";

package/dist/index.js

@@ -1,2 +1,2 @@
 export * as Verifier from "./verify.js";
-export { Unauthorized, Forbidden, RateLimited, ProviderUnavailable, ConfigurationError, } from "./errors.js";
+export * as RequestPolicy from "./request-policy.js";

package/dist/request-policy.d.ts

@@ -0,0 +1,38 @@
+import { HttpRouter } from "effect/unstable/http";
+export interface Options {
+    /**
+     * The origin browsers reach this app at. The application has already validated it;
+     * its `host` (with port, when the scheme's default is not used) must equal the Host
+     * header, and its `origin` is the one Origin accepted by default.
+     */
+    readonly publicUrl: URL;
+    /**
+     * Origins accepted besides the public one, compared exactly. For a desktop shell
+     * whose renderer has a private scheme, such as `wtf://app`. No wildcards.
+     */
+    readonly allowedOrigins?: readonly string[];
+}
+/** One request, as a Node `upgrade` handler or a router middleware sees it. */
+export interface Request {
+    /** The request target: `/a?b` or an absolute URL. Only its path is read. */
+    readonly target: string;
+    readonly host: string | undefined;
+    readonly origin: string | undefined;
+}
+/**
+ * Build the policy once, at startup. `allows` is the whole decision and takes no
+ * services, so a Node `upgrade` handler applies the same rule as the router.
+ */
+export declare const make: (options: Options) => {
+    allows: (request: Request) => boolean;
+    /** Refuse anything `allows` rejects with an empty-bodied 403, before any handler. */
+    middleware: HttpRouter.Middleware<{
+        provides: never;
+        handles: never;
+        error: never;
+        requires: never;
+        layerError: never;
+        layerRequires: never;
+    }>;
+};
+export type Policy = ReturnType<typeof make>;

package/dist/request-policy.js

@@ -0,0 +1,57 @@
+/**
+ * Which callers this app answers at all. Forward auth makes a browser's credential
+ * ambient: the proxy attaches an Authorization header to whatever the browser sends,
+ * including a cross-site navigation. So the app checks the two headers that say where
+ * a request came from, before anything reads the credential.
+ *
+ * Both checks are raw string comparisons on the headers as sent. Nothing is parsed,
+ * so nothing throws and no normalization can widen what is accepted: `notes.example`
+ * and `notes.example:443` are different hosts here, as they are to a browser's cookie.
+ */
+import { Effect } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+/**
+ * The one path answered without either check. A container probe reaches the app on its
+ * bind address and carries neither header, and no application has a second such path.
+ */
+const probePath = "/healthz";
+/** The path of a request target. Deliberately not `new URL`: this must not throw. */
+const pathOf = (target) => {
+    const authority = target.indexOf("://");
+    const start = authority === -1 ? 0 : target.indexOf("/", authority + 3);
+    if (start === -1)
+        return "/";
+    const rest = target.slice(start);
+    const stop = rest.search(/[?#]/u);
+    return stop === -1 ? rest : rest.slice(0, stop);
+};
+const forbidden = HttpServerResponse.text("Forbidden", { status: 403 });
+/**
+ * Build the policy once, at startup. `allows` is the whole decision and takes no
+ * services, so a Node `upgrade` handler applies the same rule as the router.
+ */
+export const make = (options) => {
+    const host = options.publicUrl.host;
+    const origins = new Set([options.publicUrl.origin, ...(options.allowedOrigins ?? [])]);
+    const allows = (request) => {
+        if (pathOf(request.target) === probePath)
+            return true;
+        // A request with no Host is not a browser request for this app's origin.
+        if (request.host !== host)
+            return false;
+        return request.origin === undefined || origins.has(request.origin);
+    };
+    return {
+        allows,
+        /** Refuse anything `allows` rejects with an empty-bodied 403, before any handler. */
+        middleware: HttpRouter.middleware((httpEffect) => Effect.gen(function* () {
+            const request = yield* HttpServerRequest.HttpServerRequest;
+            const permitted = allows({
+                target: request.originalUrl,
+                host: request.headers.host,
+                origin: request.headers.origin,
+            });
+            return permitted ? yield* httpEffect : forbidden;
+        })),
+    };
+};

package/dist/resource.d.ts

@@ -1,15 +1,50 @@
-import { Context, Effect } from "effect";
+import { Context, Effect, Schema } from "effect";
+import type * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
-import { ConfigurationError, Forbidden, RateLimited, Unauthorized } from "./errors.ts";
-import type { AuthenticationError } from "./errors.ts";
+import { ConfigurationError, InsufficientScope, RateLimited, Unauthorized } from "./errors.ts";
 import * as Verifier from "./verify.ts";
 declare const CurrentPrincipal_base: Context.ServiceClass<CurrentPrincipal, "@clankerauth/CurrentPrincipal", Verifier.Principal>;
 export declare class CurrentPrincipal extends CurrentPrincipal_base {
 }
-export interface Options extends Verifier.Options {
-    readonly scopes: readonly string[];
+/** What this resource's credentials must carry. */
+export interface Scopes {
+    /** Required of every credential, so verification alone admits a read. */
+    readonly read: string;
+    /**
+     * Additionally required by an `access: "write"` action and by `admit(..., "write")`.
+     * Omit for a single-scope application, where verification is the whole policy.
+     */
+    readonly write?: string;
 }
-/** One resource: its verifier and discovery. Acquire once per protected audience. */
+export interface Options {
+    readonly issuer: string;
+    /**
+     * The origin browsers and agents reach this application at. The resource is its origin
+     * root, so any path here is discarded: one identifier covers `/api`, `/mcp` and sockets.
+     */
+    readonly publicUrl: URL;
+    readonly scopes: Scopes;
+    /** `false` rejects API keys without consulting the issuer; only OAuth access tokens are accepted. */
+    readonly apiKeys?: boolean;
+}
+/**
+ * A refusal a caller outside the router can send as-is: an RFC 6750 challenge or a
+ * `Retry-After`, `Cache-Control: no-store`, and the error's own JSON encoding.
+ */
+export interface Refusal {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+}
+/** What one Authorization header value amounts to for this resource. */
+export type Admission = {
+    readonly ok: true;
+    readonly principal: Verifier.Principal;
+} | {
+    readonly ok: false;
+    readonly refusal: Refusal;
+};
+/** One resource: its verifier, discovery, scope policy and refusals. Acquire once per application. */
 export declare const make: (options: Options) => Effect.Effect<{
     verifier: {
         verifyToken: (token: string) => Effect.Effect<{
@@ -19,6 +54,7 @@ export declare const make: (options: Options) => Effect.Effect<{
                 kind: "client";
                 clientId: string;
             };
+            expiresAt: number;
         } | {
             subject: string;
             scopes: readonly string[];
@@ -26,7 +62,8 @@ export declare const make: (options: Options) => Effect.Effect<{
                 kind: "key";
                 keyId: string;
             };
-        }, Forbidden | import("./errors.ts").ProviderUnavailable | RateLimited | Unauthorized, never>;
+            expiresAt: undefined;
+        }, InsufficientScope | import("./errors.ts").ProviderUnavailable | RateLimited | Unauthorized, never>;
         verify: (authorization: string | null | undefined) => Effect.Effect<{
             subject: string;
             scopes: string[];
@@ -34,6 +71,7 @@ export declare const make: (options: Options) => Effect.Effect<{
                 kind: "client";
                 clientId: string;
             };
+            expiresAt: number;
         } | {
             subject: string;
             scopes: readonly string[];
@@ -41,28 +79,32 @@ export declare const make: (options: Options) => Effect.Effect<{
                 kind: "key";
                 keyId: string;
             };
-        }, Forbidden | import("./errors.ts").ProviderUnavailable | RateLimited | Unauthorized, never>;
+            expiresAt: undefined;
+        }, InsufficientScope | import("./errors.ts").ProviderUnavailable | RateLimited | Unauthorized, never>;
     };
     discovery: {
         layer: import("effect/Layer").Layer<never, never, import("effect/unstable/http/HttpRouter").HttpRouter>;
         metadataUrl: string;
         challenge: (challenge?: Authentication.BearerChallengeOptions) => string;
     };
-    challenge: (error?: "invalid_token" | "insufficient_scope") => {
-        "www-authenticate": string;
-    };
-    headers: (error: AuthenticationError) => {
-        "www-authenticate": string;
-    } | {
-        "retry-after": string;
-    } | {
-        "retry-after"?: undefined;
-    };
+    admit: (authorization: string | null | undefined, access: Action.Access) => Effect.Effect<Admission, never, never>;
+    authorize: (action: Action.Any) => Effect.Effect<void, InsufficientScope, CurrentPrincipal>;
+    session: import("@gjermundgaraba/effect-actions/ActionGroup").Implementation<import("@gjermundgaraba/effect-actions/ActionGroup").Group<"session", readonly [Action.Action<"whoami", Schema.$Record<Schema.String, Schema.Never>, Schema.Struct<{
+        readonly subject: Schema.NonEmptyString;
+        readonly issuer: Schema.NonEmptyString;
+        readonly scopes: Schema.$Array<Schema.String>;
+    }>, readonly [], "read", true, false>], []>, {
+        whoami: () => Effect.Effect<{
+            subject: string;
+            issuer: string;
+            scopes: readonly string[];
+        }, never, CurrentPrincipal>;
+    }, never, never>;
     resource: string;
     issuer: string;
 }, ConfigurationError, import("effect/unstable/http/HttpClient").HttpClient>;
 export type Resource = Effect.Success<ReturnType<typeof make>>;
-/** Bearer authentication providing `CurrentPrincipal`. */
+/** Bearer authentication providing `CurrentPrincipal`, on the same admission `admit` renders. */
 export declare const middleware: (resource: Resource) => import("effect/unstable/http/HttpRouter").Middleware<{
     provides: CurrentPrincipal;
     handles: never;

package/dist/resource.js

@@ -1,54 +1,139 @@
-import { Context, Effect } from "effect";
+import { Context, Effect, Result, Schema, SchemaAST } from "effect";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
-import { HttpServerRequest } from "effect/unstable/http";
-import { authenticationErrors, ConfigurationError, encodeError, Forbidden, RateLimited, Unauthorized, } from "./errors.js";
+import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { authenticationErrors, ConfigurationError, InsufficientScope, RateLimited, Unauthorized, } from "./errors.js";
+import { Session } from "./session.js";
 import * as Verifier from "./verify.js";
-const encode = encodeError(authenticationErrors);
+const encoders = new Map(authenticationErrors.map((schema) => [
+    schema,
+    {
+        status: SchemaAST.resolveAt("httpApiStatus")(schema.ast) ?? 500,
+        encode: Schema.encodeUnknownEffect(Schema.toCodecJson(schema)),
+    },
+]));
+/** One refusal as its own status and JSON body. An undeclared error is a defect. */
+const describe = (error) => {
+    const schema = authenticationErrors.find((candidate) => Schema.is(candidate)(error));
+    const encoder = schema === undefined ? undefined : encoders.get(schema);
+    if (encoder === undefined)
+        return Effect.die(new Error("Undeclared error"));
+    return Effect.map(Effect.orDie(encoder.encode(error)), (body) => ({
+        status: encoder.status,
+        body: JSON.stringify(body),
+    }));
+};
 export class CurrentPrincipal extends Context.Service()("@clankerauth/CurrentPrincipal") {
 }
-/** One resource: its verifier and discovery. Acquire once per protected audience. */
+/** One resource: its verifier, discovery, scope policy and refusals. Acquire once per application. */
 export const make = Effect.fn("Resource.make")(function* (options) {
+    // One resource per application, at the public origin root, trailing slash and all.
+    // An MCP client sends `new URL(metadata.resource).href`, and the token's audience is
+    // that string, so deriving it here is what keeps the two in agreement.
+    const identifier = new URL("/", options.publicUrl).href;
+    const scopesSupported = options.scopes.write === undefined
+        ? [options.scopes.read]
+        : [options.scopes.read, options.scopes.write];
     const discovery = yield* Effect.try({
         try: () => Authentication.protectedResource({
-            resource: options.resource,
+            resource: identifier,
             authorizationServers: [options.issuer],
-            scopesSupported: options.scopes,
+            scopesSupported,
         }),
         catch: () => new ConfigurationError({ message: "Invalid resource metadata configuration" }),
     });
-    const verifier = yield* Verifier.make(options);
-    const scope = options.requiredScopes?.length ? options.requiredScopes.join(" ") : undefined;
-    /** Bearer challenge for this resource; no error code when the request carried no credentials. */
-    const challenge = (error) => ({
-        "www-authenticate": discovery.challenge({ error, scope }),
+    const verifier = yield* Verifier.make({
+        issuer: options.issuer,
+        resource: identifier,
+        requiredScopes: [options.scopes.read],
+        apiKeys: options.apiKeys,
     });
-    const headers = (error) => {
+    const challengeValue = (error, missing) => discovery.challenge({ error, scope: missing ?? options.scopes.read });
+    /**
+     * The one header besides the content type that a refusal carries: an RFC 6750
+     * challenge naming only the missing scope, or an RFC 6585 retry hint.
+     */
+    const refusalHeader = (error, credential) => {
         if (error instanceof RateLimited)
-            return { "retry-after": "60" };
-        if (error instanceof Forbidden)
-            return challenge("insufficient_scope");
+            return ["retry-after", "60"];
+        if (error instanceof InsufficientScope)
+            return ["www-authenticate", challengeValue("insufficient_scope", error.scope)];
+        // RFC 6750 §3.1: a request that carried no credentials gets no error code.
         if (error instanceof Unauthorized)
-            return challenge("invalid_token");
-        return {};
+            return ["www-authenticate", credential ? challengeValue("invalid_token") : challengeValue()];
+        return undefined;
     };
+    const asRecord = (header) => header === undefined ? {} : { [header[0]]: header[1] };
+    const refuse = (error, authorization) => Effect.map(describe(error), ({ status, body }) => ({
+        ok: false,
+        refusal: {
+            status,
+            headers: {
+                ...asRecord(refusalHeader(error, authorization !== undefined && authorization !== null)),
+                "content-type": "application/json",
+                "cache-control": "no-store",
+            },
+            body,
+        },
+    }));
+    /** The write scope, if one is configured and this principal lacks it. */
+    const missingScope = (principal) => options.scopes.write !== undefined && !principal.scopes.includes(options.scopes.write)
+        ? options.scopes.write
+        : undefined;
+    /**
+     * Verify one Authorization header value outside an Effect router: a Node `upgrade`
+     * handler, a socket, a per-request endpoint. `access` is the same declaration an
+     * action carries, so `"write"` demands the write scope before a socket is established.
+     */
+    const admit = Effect.fn("Resource.admit")(function* (authorization, access) {
+        const verified = yield* Effect.result(verifier.verify(authorization));
+        if (Result.isFailure(verified))
+            return yield* refuse(verified.failure, authorization);
+        const principal = verified.success;
+        const missing = access === "write" ? missingScope(principal) : undefined;
+        if (missing !== undefined)
+            return yield* refuse(new InsufficientScope({ scope: missing }), authorization);
+        return { ok: true, principal };
+    });
+    /**
+     * The effect-actions pre-handler hook, bound once per surface. A read needs nothing
+     * beyond what verification already required; a write needs the configured write scope.
+     * Without one it passes, so a single-scope resource has no authorization code at all.
+     */
+    const authorize = (action) => action.access === "read" || options.scopes.write === undefined
+        ? Effect.void
+        : Effect.flatMap(CurrentPrincipal, (principal) => {
+            const missing = missingScope(principal);
+            return missing === undefined
+                ? Effect.void
+                : Effect.fail(new InsufficientScope({ scope: missing }));
+        });
+    /** The `session` group of `@gjermundgaraba/clankerauth-sdk/session`, already answered. */
+    const session = Session.implement({
+        whoami: () => Effect.map(CurrentPrincipal, ({ subject, scopes }) => ({
+            subject,
+            issuer: options.issuer,
+            scopes,
+        })),
+    });
     return {
         verifier,
         discovery,
-        challenge,
-        headers,
-        resource: options.resource,
+        admit,
+        authorize,
+        session,
+        resource: identifier,
         issuer: options.issuer,
     };
 });
-/** Bearer authentication providing `CurrentPrincipal`. */
+/** Bearer authentication providing `CurrentPrincipal`, on the same admission `admit` renders. */
 export const middleware = (resource) => Authentication.middleware(CurrentPrincipal, Effect.gen(function* () {
     const request = yield* HttpServerRequest.HttpServerRequest;
-    return yield* resource.verifier.verify(request.headers.authorization);
-}).pipe(Effect.catch((error) => Effect.gen(function* () {
-    const request = yield* HttpServerRequest.HttpServerRequest;
-    // RFC 6750 §3.1: a request that carried no credentials gets no error code.
-    const headers = error instanceof Unauthorized && request.headers.authorization === undefined
-        ? resource.challenge()
-        : resource.headers(error);
-    return yield* Effect.flatMap(encode(error, headers), Effect.fail);
-}))));
+    // Read level: an action's own `access` is what the authorization hook then enforces.
+    const admission = yield* resource.admit(request.headers.authorization, "read");
+    if (admission.ok)
+        return admission.principal;
+    return yield* Effect.fail(HttpServerResponse.text(admission.refusal.body, {
+        status: admission.refusal.status,
+        headers: admission.refusal.headers,
+    }));
+}));

package/dist/session.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The identity a browser page needs, without any verification code. This entry point is
+ * browser-safe: it declares the `session` contract and builds the issuer's sign-out URL,
+ * so a page imports it directly and a server answers it with `resource.session`.
+ */
+import { Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
+/** The verified credential behind a request, as the resource server read it. */
+export declare const Principal: Schema.Struct<{
+    readonly subject: Schema.NonEmptyString;
+    readonly issuer: Schema.NonEmptyString;
+    readonly scopes: Schema.$Array<Schema.String>;
+}>;
+export type Principal = typeof Principal.Type;
+/**
+ * The credential is a transport concern: a process surface has none, so `whoami` is its
+ * own group and never an MCP tool. Bind it with `Http.layer(app, resource.session)`.
+ */
+export declare const Session: ActionGroup.Group<"session", readonly [Action.Action<"whoami", Schema.$Record<Schema.String, Schema.Never>, Schema.Struct<{
+    readonly subject: Schema.NonEmptyString;
+    readonly issuer: Schema.NonEmptyString;
+    readonly scopes: Schema.$Array<Schema.String>;
+}>, readonly [], "read", true, false>], []>;
+/**
+ * Sign out at the issuer, which ends its session and every app's forward cookie, then
+ * return to `returnTo`. It is a plain link: any page under the cookie domain may use it.
+ */
+export declare const signOutUrl: (issuer: string, returnTo: string) => string;

package/dist/session.js

@@ -0,0 +1,33 @@
+/**
+ * The identity a browser page needs, without any verification code. This entry point is
+ * browser-safe: it declares the `session` contract and builds the issuer's sign-out URL,
+ * so a page imports it directly and a server answers it with `resource.session`.
+ */
+import { Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
+/** The verified credential behind a request, as the resource server read it. */
+export const Principal = Schema.Struct({
+    subject: Schema.NonEmptyString,
+    issuer: Schema.NonEmptyString,
+    scopes: Schema.Array(Schema.String),
+});
+/**
+ * The credential is a transport concern: a process surface has none, so `whoami` is its
+ * own group and never an MCP tool. Bind it with `Http.layer(app, resource.session)`.
+ */
+export const Session = ActionGroup.make({ name: "session" }, Action.make("whoami", {
+    description: "The verified subject, issuer and scopes behind this request's credential.",
+    access: "read",
+    success: Principal,
+    mcp: false,
+}));
+/**
+ * Sign out at the issuer, which ends its session and every app's forward cookie, then
+ * return to `returnTo`. It is a plain link: any page under the cookie domain may use it.
+ */
+export const signOutUrl = (issuer, returnTo) => {
+    const url = new URL("/forward-auth/logout", issuer);
+    url.searchParams.set("rd", returnTo);
+    return url.href;
+};

package/dist/verify.d.ts

@@ -1,6 +1,7 @@
 import { Effect } from "effect";
 import { HttpClient } from "effect/unstable/http";
-import { ConfigurationError, Forbidden, ProviderUnavailable, RateLimited, Unauthorized } from "./errors.ts";
+import { ConfigurationError, InsufficientScope, ProviderUnavailable, RateLimited, Unauthorized } from "./errors.ts";
+import type { AuthenticationError } from "./errors.ts";
 export interface Principal {
     readonly subject: string;
     readonly scopes: readonly string[];
@@ -11,6 +12,13 @@ export interface Principal {
         readonly kind: "key";
         readonly keyId: string;
     };
+    /**
+     * When this credential stops being valid, in epoch milliseconds: an access token's
+     * verified `exp`, so a host never decodes the token again. `undefined` for an API
+     * key, which has no token lifetime and is re-verified against the issuer on every
+     * request; a host that caches a key decision must choose its own bound.
+     */
+    readonly expiresAt: number | undefined;
 }
 export interface Options {
     readonly issuer: string;
@@ -20,10 +28,9 @@ export interface Options {
     readonly apiKeys?: boolean;
 }
 export interface Verifier {
-    readonly verify: (authorization: string | null | undefined) => Effect.Effect<Principal, VerificationError>;
-    readonly verifyToken: (token: string) => Effect.Effect<Principal, VerificationError>;
+    readonly verify: (authorization: string | null | undefined) => Effect.Effect<Principal, AuthenticationError>;
+    readonly verifyToken: (token: string) => Effect.Effect<Principal, AuthenticationError>;
 }
-export type VerificationError = Unauthorized | Forbidden | RateLimited | ProviderUnavailable;
 /** Acquire once per resource; transport is selected by the application, not the SDK. */
 export declare const make: (options: Options) => Effect.Effect<{
     verifyToken: (token: string) => Effect.Effect<{
@@ -33,6 +40,7 @@ export declare const make: (options: Options) => Effect.Effect<{
             kind: "client";
             clientId: string;
         };
+        expiresAt: number;
     } | {
         subject: string;
         scopes: readonly string[];
@@ -40,7 +48,8 @@ export declare const make: (options: Options) => Effect.Effect<{
             kind: "key";
             keyId: string;
         };
-    }, Forbidden | ProviderUnavailable | RateLimited | Unauthorized, never>;
+        expiresAt: undefined;
+    }, InsufficientScope | ProviderUnavailable | RateLimited | Unauthorized, never>;
     verify: (authorization: string | null | undefined) => Effect.Effect<{
         subject: string;
         scopes: string[];
@@ -48,6 +57,7 @@ export declare const make: (options: Options) => Effect.Effect<{
             kind: "client";
             clientId: string;
         };
+        expiresAt: number;
     } | {
         subject: string;
         scopes: readonly string[];
@@ -55,5 +65,6 @@ export declare const make: (options: Options) => Effect.Effect<{
             kind: "key";
             keyId: string;
         };
-    }, Forbidden | ProviderUnavailable | RateLimited | Unauthorized, never>;
+        expiresAt: undefined;
+    }, InsufficientScope | ProviderUnavailable | RateLimited | Unauthorized, never>;
 }, ConfigurationError, HttpClient.HttpClient>;

package/dist/verify.js

@@ -1,7 +1,7 @@
 import { Clock, Effect, Exit, Schema, Semaphore } from "effect";
 import { createLocalJWKSet, decodeProtectedHeader, jwtVerify } from "jose";
 import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
-import { ConfigurationError, Forbidden, ProviderUnavailable, RateLimited, Unauthorized, } from "./errors.js";
+import { ConfigurationError, InsufficientScope, ProviderUnavailable, RateLimited, Unauthorized, } from "./errors.js";
 import { execute } from "./transport.js";
 const Jwks = Schema.Struct({
     keys: Schema.Array(Schema.Struct({
@@ -18,6 +18,7 @@ const Claims = Schema.Struct({
     sub: Schema.NonEmptyString,
     client_id: Schema.NonEmptyString,
     scope: Schema.String,
+    exp: Schema.Finite,
 });
 const KeyResponse = Schema.Struct({
     keyId: Schema.NonEmptyString,
@@ -111,15 +112,17 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
             subject: claims.sub,
             scopes: claims.scope.split(" ").filter(Boolean),
             actor: { kind: "client", clientId: claims.client_id },
+            // `jwtVerify` already checked this claim against the current time.
+            expiresAt: claims.exp * 1000,
         };
     });
     const verifyKey = Effect.fn("Verifier.apiKey")(function* (key) {
         const request = HttpClientRequest.post(endpoints.apiKey).pipe(HttpClientRequest.setHeader("authorization", `Bearer ${key}`), HttpClientRequest.bodyJsonUnsafe({ resource: options.resource }));
         const response = yield* execute(client, request);
-        if (response.status === 401)
+        // The issuer answers 403 for a key with no grant on this resource. That is the same
+        // case as a token for another audience: the credential is not this resource's.
+        if (response.status === 401 || response.status === 403)
             return yield* unauthorized();
-        if (response.status === 403)
-            return yield* new Forbidden({ message: "Insufficient scope" });
         if (response.status === 429)
             return yield* new RateLimited({ message: "Authentication rate exceeded" });
         if (response.status !== 200)
@@ -137,6 +140,9 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
             subject: body.ownerId,
             scopes: body.scopes,
             actor: { kind: "key", keyId: body.keyId },
+            // A key's own expiry is enforced above, on every verification; it is not a
+            // lifetime a caller may hold a decision for.
+            expiresAt: undefined,
         };
     }, Effect.scoped);
     const verifyToken = Effect.fn("Verifier.verifyToken")(function* (token) {
@@ -145,8 +151,9 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
                 ? Effect.fail(unauthorized())
                 : verifyKey(token)
             : verifyJwt(token);
-        if (options.requiredScopes?.some((scope) => !principal.scopes.includes(scope)))
-            return yield* new Forbidden({ message: "Insufficient scope" });
+        const missing = options.requiredScopes?.find((scope) => !principal.scopes.includes(scope));
+        if (missing !== undefined)
+            return yield* new InsufficientScope({ scope: missing });
         return principal;
     }, Effect.timeoutOrElse({
         duration: "5 seconds",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/clankerauth-sdk",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Effect-native Clanker Auth access-token and API-key verification, with optional effect-actions integration",
   "license": "MIT",
   "repository": {
@@ -12,11 +12,20 @@
     "dist"
   ],
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js"
+    },
+    "./session": {
+      "types": "./dist/session.d.ts",
+      "import": "./dist/session.js"
+    },
     "./effect-actions": {
       "types": "./dist/effect-actions.d.ts",
       "import": "./dist/effect-actions.js"
@@ -30,14 +39,15 @@
     "jose": "6.2.12"
   },
   "devDependencies": {
-    "@gjermundgaraba/effect-actions": "0.2.0",
+    "@gjermundgaraba/effect-actions": "0.4.0",
+    "@modelcontextprotocol/client": "2.0.0",
     "@types/node": "26.6.2",
     "typescript": "7.0.2",
     "vite": "npm:@voidzero-dev/vite-plus-core@0.3.3",
     "vite-plus": "0.3.3"
   },
   "peerDependencies": {
-    "@gjermundgaraba/effect-actions": "0.2.0"
+    "@gjermundgaraba/effect-actions": "0.4.0"
   },
   "peerDependenciesMeta": {
     "@gjermundgaraba/effect-actions": {