@gjermundgaraba/clankerauth-sdk 0.6.0 → 0.7.1

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,32 +32,21 @@ 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
-
-Install the optional peer dependency and import the integration subpath:
-
-```sh
-vp add @gjermundgaraba/effect-actions@0.3.0
-```
-
-Core and integration declarations both type-check without `skipLibCheck`.
-
 ## One resource per application
 
 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.
 
-The identifier must already be canonical: `new URL(id).href === id`. An MCP client sends `new URL(metadata.resource).href` and the access token's audience is that string, so `https://notes.internal` (no slash) would be rewritten by the client and no longer match the issuer's registered resource. `Resource.make` refuses it with `ConfigurationError` rather than let that fail later. The official client's own `checkResourceAllowed` accepts an origin-root resource for an endpoint beneath it.
+`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.
 
 Acquire the resource once at application construction, never per request.
 
@@ -55,6 +55,7 @@ import { Effect, Layer } from "effect";
 import { FetchHttpClient } from "effect/unstable/http";
 import { McpProtocol } from "effect/unstable/ai";
 import { Resource } from "@gjermundgaraba/clankerauth-sdk/effect-actions";
+import { authenticationErrors } from "@gjermundgaraba/clankerauth-sdk/errors";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 
 // Http and app are your effect-actions HTTP binding and implemented group.
@@ -62,17 +63,24 @@ const routes = Layer.unwrap(
   Effect.gen(function* () {
     const notes = yield* Resource.make({
       issuer: "https://auth.internal/api/auth",
-      resource: "https://notes.internal/",
-      scopes: ["notes:read", "notes:write"],
-      requiredScopes: ["notes:read"],
-      writeScope: "notes:write",
+      publicUrl: new URL("https://notes.internal"),
+      scopes: { read: "notes:read", write: "notes:write" },
     });
 
     return Layer.mergeAll(
       notes.discovery.layer,
-      Http.layer(app).pipe(Layer.provide(Resource.middleware(notes).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(notes).layer)),
     );
@@ -80,38 +88,48 @@ const routes = Layer.unwrap(
 ).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.
 
 ## Scope enforcement
 
-An application names two scopes and writes no authorization code. Each action declares what it does to the resource, and the resource's `authorize` is the group's pre-handler hook: it runs before every handler on every surface — HTTP, MCP, Toolkit, CLI — so no handler can forget it.
+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 * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
-import { InsufficientScope } from "@gjermundgaraba/clankerauth-sdk";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import { authenticationErrors } from "@gjermundgaraba/clankerauth-sdk/errors";
+import { Session } from "@gjermundgaraba/clankerauth-sdk/session";
 
 const Notes = ActionGroup.make(
-  { name: "notes", errors: [InsufficientScope] },
+  { name: "notes" },
   Action.make("list", { description: "List notes", access: "read", success: Notes }),
   Action.make("write", { description: "Write a note", access: "write", success: Note }),
 );
 
-// `notes` is the acquired Resource above, configured with `writeScope`.
-const app = Notes.implement(handlers, { before: notes.authorize });
+// 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);
 ```
 
-A read needs nothing beyond what verification already required. A write needs the configured `writeScope`; without one, `authorize` passes every action, so a single-scope resource is expressed by leaving it out. `InsufficientScope` is a 403 naming **only** the missing scope, so a refusal never enumerates the resource's permissions. Declare it on the group.
+`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 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.
+
+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.
 
-An action still 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.
+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`:
+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"));
@@ -125,7 +143,7 @@ if (!admission.ok) {
 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. Passing `"write"` demands the write scope before the socket is established. `Resource.middleware` is built on the same function, so a router and a socket can never answer differently.
+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.
 
@@ -139,7 +157,6 @@ 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
-  exemptPaths: ["/healthz"], // a container probe carries neither header
 });
 
 const routes = protectedRoutes.pipe(Layer.provide(policy.middleware.layer));
@@ -156,19 +173,31 @@ if (
 }
 ```
 
-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 unless its path is exempt. An absent `Origin` is allowed; a present one must match exactly. This is not authentication, and it does not set body limits or security headers — those stay the application's.
+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.
 
-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.
+## Browser applications
 
-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 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:
 
-## Browser applications
+```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}/`);
+```
 
-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.
+`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), `InsufficientScope` (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/effect-actions.d.ts

@@ -1,3 +1,2 @@
 export * as Resource from "./resource.ts";
 export { CurrentPrincipal } from "./resource.ts";
-export { InsufficientScope } from "./errors.ts";

package/dist/effect-actions.js

@@ -1,3 +1,2 @@
 export * as Resource from "./resource.js";
 export { CurrentPrincipal } from "./resource.js";
-export { InsufficientScope } from "./errors.js";

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>;
@@ -45,18 +45,10 @@ declare const ConfigurationError_base: Schema.Class<ConfigurationError, Schema.T
 }>, 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;
-/** What `Resource.admit` may refuse with: verification, plus the write-scope check. */
-export declare const admissionErrors: readonly [typeof Unauthorized, typeof Forbidden, typeof RateLimited, typeof ProviderUnavailable, typeof InsufficientScope];
-export type AdmissionError = AuthenticationError | InsufficientScope;
-/** An error schema: service-free, so encoding a refusal needs no request context. */
-export type ErrorSchema = Schema.Codec<unknown, unknown, never, never>;
-/** One declared error as a status and a JSON body. Undeclared errors are defects. */
-export declare const describeError: <const Schemas extends ReadonlyArray<ErrorSchema>>(schemas: Schemas) => (error: Schemas[number]["Type"]) => Effect.Effect<{
-    status: number;
-    body: string;
-}, never, never>;
-/** Encode one of the declared schemas as a JSON response with its `httpApiStatus`. */
-export declare const encodeError: <const Schemas extends ReadonlyArray<ErrorSchema>>(schemas: Schemas) => (error: Schemas[number]["Type"], headers?: Headers.Input) => Effect.Effect<HttpServerResponse.HttpServerResponse, never, never>;
+/**
+ * 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 }) {
@@ -25,36 +28,13 @@ export class InsufficientScope extends Schema.TaggedError()("InsufficientScope",
 }
 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,
 ];
-/** What `Resource.admit` may refuse with: verification, plus the write-scope check. */
-export const admissionErrors = [...authenticationErrors, InsufficientScope];
-/** One declared error as a status and a JSON body. Undeclared errors are defects. */
-export const describeError = (schemas) => {
-    const encoders = new Map(schemas.map((schema) => [
-        schema,
-        {
-            status: SchemaAST.resolveAt("httpApiStatus")(schema.ast) ?? 500,
-            encode: Schema.encodeUnknownEffect(Schema.toCodecJson(schema)),
-        },
-    ]));
-    return (error) => {
-        const schema = schemas.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),
-        }));
-    };
-};
-/** Encode one of the declared schemas as a JSON response with its `httpApiStatus`. */
-export const encodeError = (schemas) => {
-    const describe = describeError(schemas);
-    return (error, headers) => Effect.map(describe(error), ({ status, body }) => HttpServerResponse.text(body, { status, headers, contentType: "application/json" }));
-};

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/request-policy.d.ts

@@ -11,11 +11,6 @@ export interface Options {
      * whose renderer has a private scheme, such as `wtf://app`. No wildcards.
      */
     readonly allowedOrigins?: readonly string[];
-    /**
-     * Exact paths answered without either check, such as `/healthz`. A container probe
-     * reaches the app on its bind address and carries neither header.
-     */
-    readonly exemptPaths?: readonly string[];
 }
 /** One request, as a Node `upgrade` handler or a router middleware sees it. */
 export interface Request {

package/dist/request-policy.js

@@ -10,6 +10,11 @@
  */
 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("://");
@@ -28,9 +33,8 @@ const forbidden = HttpServerResponse.text("Forbidden", { status: 403 });
 export const make = (options) => {
     const host = options.publicUrl.host;
     const origins = new Set([options.publicUrl.origin, ...(options.allowedOrigins ?? [])]);
-    const exempt = new Set(options.exemptPaths ?? []);
     const allows = (request) => {
-        if (exempt.has(pathOf(request.target)))
+        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)

package/dist/resource.d.ts

@@ -1,20 +1,31 @@
-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, InsufficientScope, RateLimited, Unauthorized } from "./errors.ts";
-import type { AdmissionError } 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;
     /**
-     * The scope a write needs beyond `requiredScopes`. Omit for a single-scope
-     * resource, where verification alone is the whole policy and `authorize` passes
-     * every action.
+     * Additionally required by an `access: "write"` action and by `admit(..., "write")`.
+     * Omit for a single-scope application, where verification is the whole policy.
      */
-    readonly writeScope?: string;
+    readonly write?: string;
+}
+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
@@ -33,7 +44,7 @@ export type Admission = {
     readonly ok: false;
     readonly refusal: Refusal;
 };
-/** One resource: its verifier, discovery, scope policy and refusals. Acquire once per audience. */
+/** 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<{
@@ -52,7 +63,7 @@ export declare const make: (options: Options) => Effect.Effect<{
                 keyId: string;
             };
             expiresAt: undefined;
-        }, Forbidden | import("./errors.ts").ProviderUnavailable | RateLimited | Unauthorized, never>;
+        }, InsufficientScope | import("./errors.ts").ProviderUnavailable | RateLimited | Unauthorized, never>;
         verify: (authorization: string | null | undefined) => Effect.Effect<{
             subject: string;
             scopes: string[];
@@ -69,24 +80,28 @@ export declare const make: (options: Options) => Effect.Effect<{
                 keyId: string;
             };
             expiresAt: undefined;
-        }, Forbidden | import("./errors.ts").ProviderUnavailable | RateLimited | Unauthorized, never>;
+        }, 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: AdmissionError) => {
-        [x: string]: string;
-    };
-    admit: (authorization: string | null | undefined, access?: Action.Access | undefined) => Effect.Effect<Admission, never, never>;
+    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;
-    writeScope: string | undefined;
 }, ConfigurationError, import("effect/unstable/http/HttpClient").HttpClient>;
 export type Resource = Effect.Success<ReturnType<typeof make>>;
 /** Bearer authentication providing `CurrentPrincipal`, on the same admission `admit` renders. */

package/dist/resource.js

@@ -1,38 +1,53 @@
-import { Context, Effect, Result } from "effect";
+import { Context, Effect, Result, Schema, SchemaAST } from "effect";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
 import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
-import { admissionErrors, ConfigurationError, describeError, Forbidden, InsufficientScope, RateLimited, Unauthorized, } from "./errors.js";
+import { authenticationErrors, ConfigurationError, InsufficientScope, RateLimited, Unauthorized, } from "./errors.js";
+import { Session } from "./session.js";
 import * as Verifier from "./verify.js";
-const describe = describeError(admissionErrors);
+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, discovery, scope policy and refusals. Acquire once per 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. Refuse an identifier that is not already in that form, rather than
-    // normalizing it and leaving the issuer's registered resource to disagree: an origin
-    // root is `https://app.example/`, with the trailing slash.
-    yield* Effect.try({
-        try: () => new URL(options.resource),
-        catch: () => new ConfigurationError({ message: "Resource identifier is not a URL" }),
-    }).pipe(Effect.filterOrFail((url) => url.href === options.resource, () => new ConfigurationError({
-        message: `Resource identifier must be canonical: use ${new URL(options.resource).href}`,
-    })));
+    // 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;
-    const challengeValue = (error, missing) => discovery.challenge({ error, scope: missing ?? scope });
-    /** Bearer challenge for this resource; no error code when the request carried no credentials. */
-    const challenge = (error) => ({
-        "www-authenticate": challengeValue(error),
+    const verifier = yield* Verifier.make({
+        issuer: options.issuer,
+        resource: identifier,
+        requiredScopes: [options.scopes.read],
+        apiKeys: options.apiKeys,
     });
+    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.
@@ -42,20 +57,12 @@ export const make = Effect.fn("Resource.make")(function* (options) {
             return ["retry-after", "60"];
         if (error instanceof InsufficientScope)
             return ["www-authenticate", challengeValue("insufficient_scope", error.scope)];
-        if (error instanceof Forbidden)
-            return ["www-authenticate", challengeValue("insufficient_scope")];
         // RFC 6750 §3.1: a request that carried no credentials gets no error code.
         if (error instanceof Unauthorized)
             return ["www-authenticate", credential ? challengeValue("invalid_token") : challengeValue()];
         return undefined;
     };
     const asRecord = (header) => header === undefined ? {} : { [header[0]]: header[1] };
-    /** The header a caller rendering its own response adds for this failure. */
-    const headers = (error) => asRecord(refusalHeader(error, true));
-    /** The write scope, if one is configured and this principal lacks it. */
-    const missingScope = (principal) => options.writeScope !== undefined && !principal.scopes.includes(options.writeScope)
-        ? options.writeScope
-        : undefined;
     const refuse = (error, authorization) => Effect.map(describe(error), ({ status, body }) => ({
         ok: false,
         refusal: {
@@ -68,12 +75,16 @@ export const make = Effect.fn("Resource.make")(function* (options) {
             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: "write"` also demands the
-     * configured write scope, so a socket can require it before it is established.
+     * 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 = "read") {
+    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);
@@ -84,11 +95,11 @@ export const make = Effect.fn("Resource.make")(function* (options) {
         return { ok: true, principal };
     });
     /**
-     * The effect-actions pre-handler hook. 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.
+     * 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.writeScope === undefined
+    const authorize = (action) => action.access === "read" || options.scopes.write === undefined
         ? Effect.void
         : Effect.flatMap(CurrentPrincipal, (principal) => {
             const missing = missingScope(principal);
@@ -96,22 +107,29 @@ export const make = Effect.fn("Resource.make")(function* (options) {
                 ? 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,
         admit,
         authorize,
-        resource: options.resource,
+        session,
+        resource: identifier,
         issuer: options.issuer,
-        writeScope: options.writeScope,
     };
 });
 /** 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;
-    const admission = yield* resource.admit(request.headers.authorization);
+    // 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, {

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[];
@@ -27,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<{
@@ -49,7 +49,7 @@ export declare const make: (options: Options) => Effect.Effect<{
             keyId: string;
         };
         expiresAt: undefined;
-    }, Forbidden | ProviderUnavailable | RateLimited | Unauthorized, never>;
+    }, InsufficientScope | ProviderUnavailable | RateLimited | Unauthorized, never>;
     verify: (authorization: string | null | undefined) => Effect.Effect<{
         subject: string;
         scopes: string[];
@@ -66,5 +66,5 @@ export declare const make: (options: Options) => Effect.Effect<{
             keyId: string;
         };
         expiresAt: undefined;
-    }, Forbidden | ProviderUnavailable | RateLimited | Unauthorized, never>;
+    }, 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({
@@ -119,10 +119,10 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
     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)
@@ -151,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.6.0",
+  "version": "0.7.1",
   "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,7 +39,7 @@
     "jose": "6.2.12"
   },
   "devDependencies": {
-    "@gjermundgaraba/effect-actions": "0.3.0",
+    "@gjermundgaraba/effect-actions": "0.4.1",
     "@modelcontextprotocol/client": "2.0.0",
     "@types/node": "26.6.2",
     "typescript": "7.0.2",
@@ -38,7 +47,7 @@
     "vite-plus": "0.3.3"
   },
   "peerDependencies": {
-    "@gjermundgaraba/effect-actions": "0.3.0"
+    "@gjermundgaraba/effect-actions": "0.4.1"
   },
   "peerDependenciesMeta": {
     "@gjermundgaraba/effect-actions": {