@gjermundgaraba/clankerauth-sdk 0.7.1 → 0.7.2

package/README.md

@@ -69,20 +69,17 @@ const routes = Layer.unwrap(
 
     return Layer.mergeAll(
       notes.discovery.layer,
-      Http.layer({ before: notes.authorize }, app, notes.session).pipe(
+      Http.layer([app, notes.session], { before: notes.authorize }).pipe(
         Layer.provide(Resource.middleware(notes).layer),
       ),
-      ActionMcp.layerHttp(
-        {
-          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)),
+      ActionMcp.layerHttp([app], {
+        name: "notes",
+        version: "1.0.0",
+        path: "/mcp",
+        protocols: [McpProtocol.v2026_07_28],
+        errors: authenticationErrors,
+        before: notes.authorize,
+      }).pipe(Layer.provide(Resource.middleware(notes).layer)),
     );
   }),
 ).pipe(Layer.provide(FetchHttpClient.layer));
@@ -94,7 +91,7 @@ The supplied `HttpClient` must not retry credential exchanges or follow redirect
 
 ## 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.
+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 after the input is decoded and 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";
@@ -114,7 +111,7 @@ const Notes = ActionGroup.make(
 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);
+const routes = Http.layer([Notes.implement(handlers), notes.session], { before: notes.authorize });
 ```
 
 `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.
@@ -123,7 +120,7 @@ A forward-auth browser token carries **every** scope the resource defines, becau
 
 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.
 
-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.
+A hook refusal is a plain declared error: effect-actions encodes it with the schema's status and adds no headers of its own; `Cache-Control: no-store` comes from `Resource.middleware`, which wraps every route it authenticates. 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.
 
@@ -195,11 +192,11 @@ Schema-tagged errors, all from `@gjermundgaraba/clankerauth-sdk/errors`: `Unauth
 
 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.
+JWTs are checked against issuer, audience, EdDSA signature, token type, required claims, expiry and scopes. Sender-constrained tokens are rejected. One JWKS read answers every verification for a minute, so a key the issuer starts or stops publishing takes effect within that minute; a `kid` the current document does not publish is `Unauthorized` and never triggers a read, so unauthenticated requests cannot become provider traffic. A failed read, or one whose caller gave up, answers `ProviderUnavailable` (503) for five seconds before the next attempt. 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. Admission through a `Resource` has a five-second deadline; the raw `Verifier` has none, so an in-process caller can await a provider call it cannot cancel.
 
-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 bundled issuer does not configure automatic signing-key rotation. Immediate-use rotation is supported, but tokens signed by a new key are rejected until the next JWKS read, up to a minute. Publish-before-use avoids that 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.
+The SDK Resource adapter owns authentication error encoding and challenge headers; effect-actions supplies request-scoped identity, and its authentication middleware marks every response it answers or wraps `Cache-Control: no-store`; other cache policy is the host's. 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.
 
 Operational failures retain their underlying `cause` for application-side Effect error handling. `ProviderUnavailable` and `Unauthorized` keep this diagnostic field outside their public schemas; effect-actions serializes only those schemas. Causes may contain sensitive transport or provider details: inspect selectively, never serialize them into responses or log them indiscriminately.
 

package/dist/resource.d.ts

@@ -1,7 +1,7 @@
 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, InsufficientScope, RateLimited, Unauthorized } from "./errors.ts";
+import { ConfigurationError, InsufficientScope } 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 {
@@ -46,42 +46,7 @@ export type Admission = {
 };
 /** 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<{
-            subject: string;
-            scopes: string[];
-            actor: {
-                kind: "client";
-                clientId: string;
-            };
-            expiresAt: number;
-        } | {
-            subject: string;
-            scopes: readonly string[];
-            actor: {
-                kind: "key";
-                keyId: string;
-            };
-            expiresAt: undefined;
-        }, InsufficientScope | import("./errors.ts").ProviderUnavailable | RateLimited | Unauthorized, never>;
-        verify: (authorization: string | null | undefined) => Effect.Effect<{
-            subject: string;
-            scopes: string[];
-            actor: {
-                kind: "client";
-                clientId: string;
-            };
-            expiresAt: number;
-        } | {
-            subject: string;
-            scopes: readonly string[];
-            actor: {
-                kind: "key";
-                keyId: string;
-            };
-            expiresAt: undefined;
-        }, InsufficientScope | import("./errors.ts").ProviderUnavailable | RateLimited | Unauthorized, never>;
-    };
+    verifier: Verifier.Verifier;
     discovery: {
         layer: import("effect/Layer").Layer<never, never, import("effect/unstable/http/HttpRouter").HttpRouter>;
         metadataUrl: string;

package/dist/resource.js

@@ -1,7 +1,7 @@
 import { Context, Effect, Result, Schema, SchemaAST } from "effect";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
 import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
-import { authenticationErrors, ConfigurationError, InsufficientScope, RateLimited, Unauthorized, } from "./errors.js";
+import { authenticationErrors, ConfigurationError, InsufficientScope, ProviderUnavailable, RateLimited, Unauthorized, } from "./errors.js";
 import { Session } from "./session.js";
 import * as Verifier from "./verify.js";
 const encoders = new Map(authenticationErrors.map((schema) => [
@@ -41,12 +41,22 @@ export const make = Effect.fn("Resource.make")(function* (options) {
         }),
         catch: () => new ConfigurationError({ message: "Invalid resource metadata configuration" }),
     });
-    const verifier = yield* Verifier.make({
+    const unbounded = yield* Verifier.make({
         issuer: options.issuer,
         resource: identifier,
         requiredScopes: [options.scopes.read],
         apiKeys: options.apiKeys,
     });
+    // A request must not wait on an issuer that does not answer: the transport is
+    // interrupted and the credential refused as unavailable.
+    const deadline = (effect) => Effect.timeoutOrElse(effect, {
+        duration: "5 seconds",
+        orElse: () => Effect.fail(new ProviderUnavailable({ operation: "verify.timeout" })),
+    });
+    const verifier = {
+        verify: (authorization) => deadline(unbounded.verify(authorization)),
+        verifyToken: (token) => deadline(unbounded.verifyToken(token)),
+    };
     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

package/dist/session.d.ts

@@ -15,7 +15,7 @@ export declare const Principal: Schema.Struct<{
 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)`.
+ * 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;

package/dist/session.js

@@ -14,7 +14,7 @@ export const Principal = Schema.Struct({
 });
 /**
  * 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)`.
+ * 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.",

package/dist/verify.d.ts

@@ -31,7 +31,11 @@ export interface Verifier {
     readonly verify: (authorization: string | null | undefined) => Effect.Effect<Principal, AuthenticationError>;
     readonly verifyToken: (token: string) => Effect.Effect<Principal, AuthenticationError>;
 }
-/** Acquire once per resource; transport is selected by the application, not the SDK. */
+/**
+ * Acquire once per resource; transport is selected by the application, not the SDK.
+ * Verification runs to completion: a deadline is the request edge's policy, which
+ * `Resource` applies, so an in-process caller can await a provider call it cannot cancel.
+ */
 export declare const make: (options: Options) => Effect.Effect<{
     verifyToken: (token: string) => Effect.Effect<{
         subject: string;

package/dist/verify.js

@@ -1,4 +1,4 @@
-import { Clock, Effect, Exit, Schema, Semaphore } from "effect";
+import { Cause, Clock, DateTime, Effect, Exit, Schema } from "effect";
 import { createLocalJWKSet, decodeProtectedHeader, jwtVerify } from "jose";
 import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
 import { ConfigurationError, InsufficientScope, ProviderUnavailable, RateLimited, Unauthorized, } from "./errors.js";
@@ -25,10 +25,18 @@ const KeyResponse = Schema.Struct({
     ownerId: Schema.NonEmptyString,
     resource: Schema.String,
     scopes: Schema.Array(Schema.NonEmptyString),
-    expiresAt: Schema.NullOr(Schema.String),
+    expiresAt: Schema.NullOr(Schema.DateTimeUtcFromString),
 });
 const unauthorized = () => new Unauthorized({ message: "Authentication required" });
-/** Acquire once per resource; transport is selected by the application, not the SDK. */
+/** How long a JWKS document answers verification before it is read again. */
+const documentLifetime = "1 minute";
+/** How long a failed read holds off the next one. */
+const failureCooldown = "5 seconds";
+/**
+ * Acquire once per resource; transport is selected by the application, not the SDK.
+ * Verification runs to completion: a deadline is the request edge's policy, which
+ * `Resource` applies, so an in-process caller can await a provider call it cannot cancel.
+ */
 export const make = Effect.fn("Verifier.make")(function* (options) {
     const client = yield* HttpClient.HttpClient;
     const endpoints = yield* Effect.try({
@@ -38,49 +46,33 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
         }),
         catch: () => new ConfigurationError({ message: "Invalid issuer URL" }),
     });
-    const refreshLock = yield* Semaphore.make(1);
-    let refreshAfter = 0;
-    let refreshFailure;
-    const makeCachedKeys = Effect.cachedWithTTL(Effect.gen(function* () {
+    const document = Effect.fn("Verifier.jwks")(function* () {
         const response = yield* execute(client, HttpClientRequest.get(endpoints.jwks));
         if (response.status !== 200)
             return yield* new ProviderUnavailable({
                 operation: "jwks.fetch",
                 cause: { status: response.status },
             });
-        const document = yield* HttpClientResponse.schemaBodyJson(Jwks)(response).pipe(Effect.mapError((cause) => new ProviderUnavailable({ operation: "jwks.decode", cause })));
-        refreshAfter = (yield* Clock.currentTimeMillis) + 30_000;
-        refreshFailure = undefined;
+        const jwks = yield* HttpClientResponse.schemaBodyJson(Jwks)(response).pipe(Effect.mapError((cause) => new ProviderUnavailable({ operation: "jwks.decode", cause })));
         return createLocalJWKSet({
-            keys: document.keys.map(({ key_ops, ...key }) => key_ops ? { ...key, key_ops: [...key_ops] } : key),
+            keys: jwks.keys.map(({ key_ops, ...key }) => key_ops ? { ...key, key_ops: [...key_ops] } : key),
         });
-    }).pipe(Effect.scoped), (exit) => (Exit.isSuccess(exit) ? "10 minutes" : 0));
-    let keys = yield* makeCachedKeys;
-    const resolveKey = (resolve, header) => Effect.tryPromise({
-        try: () => resolve(header),
-        // Selecting from fetched keys does no I/O: every failure is the credential's.
-        catch: unauthorized,
-    });
-    const signingKey = Effect.fn("Verifier.signingKey")(function* (header) {
+    }, Effect.scoped);
+    // One read serves every key identifier until it expires, whatever its outcome, so an
+    // unknown `kid` in an unauthenticated request never becomes traffic at the issuer.
+    const read = yield* Effect.cachedWithTTL(document(), (exit) => Exit.isSuccess(exit) ? documentLifetime : failureCooldown);
+    // Replaying that read must not hand a later request the interruption of an earlier
+    // one's deadline; within the window the issuer simply was not reached.
+    const keys = Effect.catchCause(read, (cause) => Cause.hasInterrupts(cause)
+        ? Effect.fail(new ProviderUnavailable({ operation: "jwks.refresh" }))
+        : Effect.failCause(cause));
+    const signingKey = Effect.fn("Verifier.signingKey")(function* (kid) {
         const resolve = yield* keys;
-        return yield* resolveKey(resolve, header).pipe(Effect.catchTag("Unauthorized", () => refreshLock.withPermit(Effect.gen(function* () {
-            const current = yield* keys;
-            // Another request may have refreshed while this one waited for admission.
-            if (current !== resolve)
-                return yield* resolveKey(current, header);
-            const now = yield* Clock.currentTimeMillis;
-            // Cool down failed or interrupted refreshes too, without discarding still-valid cached keys.
-            if (now < refreshAfter)
-                return yield* refreshFailure ?? unauthorized();
-            refreshAfter = now + 30_000;
-            refreshFailure = new ProviderUnavailable({ operation: "jwks.refresh" });
-            const next = yield* makeCachedKeys;
-            const refreshed = yield* next.pipe(Effect.tapError((error) => Effect.sync(() => {
-                refreshFailure = error;
-            })));
-            keys = next;
-            return yield* resolveKey(refreshed, header);
-        }))));
+        return yield* Effect.tryPromise({
+            try: () => resolve({ alg: "EdDSA", kid }),
+            // Selecting from fetched keys does no I/O: every failure is the credential's.
+            catch: unauthorized,
+        });
     });
     const verifyJwt = Effect.fn("Verifier.jwt")(function* (token) {
         const header = yield* Effect.try({
@@ -91,7 +83,7 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
         // tokens before doing provider I/O; JOSE still enforces its algorithm allowlist.
         if (header.alg !== "EdDSA" || header.kid === undefined)
             return yield* unauthorized();
-        const key = yield* signingKey(header);
+        const key = yield* signingKey(header.kid);
         const now = yield* Clock.currentTimeMillis;
         const { payload } = yield* Effect.tryPromise({
             try: () => jwtVerify(token, key, {
@@ -131,10 +123,10 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
                 cause: { status: response.status },
             });
         const body = yield* HttpClientResponse.schemaBodyJson(KeyResponse)(response).pipe(Effect.mapError((cause) => new ProviderUnavailable({ operation: "api-key.response", cause })));
-        const expiry = body.expiresAt === null ? null : Date.parse(body.expiresAt);
-        if (body.resource !== options.resource || (expiry !== null && !Number.isFinite(expiry)))
+        if (body.resource !== options.resource)
             return yield* new ProviderUnavailable({ operation: "api-key.response" });
-        if (expiry !== null && expiry <= (yield* Clock.currentTimeMillis))
+        if (body.expiresAt !== null &&
+            DateTime.toEpochMillis(body.expiresAt) <= (yield* Clock.currentTimeMillis))
             return yield* unauthorized();
         return {
             subject: body.ownerId,
@@ -155,10 +147,7 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
         if (missing !== undefined)
             return yield* new InsufficientScope({ scope: missing });
         return principal;
-    }, Effect.timeoutOrElse({
-        duration: "5 seconds",
-        orElse: () => Effect.fail(new ProviderUnavailable({ operation: "verify.timeout" })),
-    }));
+    });
     return {
         verifyToken,
         verify: Effect.fn("Verifier.verify")(function* (authorization) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/clankerauth-sdk",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Effect-native Clanker Auth access-token and API-key verification, with optional effect-actions integration",
   "license": "MIT",
   "repository": {
@@ -39,7 +39,7 @@
     "jose": "6.2.12"
   },
   "devDependencies": {
-    "@gjermundgaraba/effect-actions": "0.4.1",
+    "@gjermundgaraba/effect-actions": "0.5.0",
     "@modelcontextprotocol/client": "2.0.0",
     "@types/node": "26.6.2",
     "typescript": "7.0.2",
@@ -47,7 +47,7 @@
     "vite-plus": "0.3.3"
   },
   "peerDependencies": {
-    "@gjermundgaraba/effect-actions": "0.4.1"
+    "@gjermundgaraba/effect-actions": "0.5.0"
   },
   "peerDependenciesMeta": {
     "@gjermundgaraba/effect-actions": {