@gjermundgaraba/clankerauth-sdk 0.13.0 → 0.15.0

package/README.md

@@ -17,7 +17,7 @@ vp add effect
 The `/session` and `/effect-actions` entry points also need effect-actions, an optional peer. Install this range: the SDK's declarations are built against it, and under `skipLibCheck` they silently degrade to `any` with another.
 
 ```sh
-vp add @gjermundgaraba/effect-actions@^0.10.0
+vp add @gjermundgaraba/effect-actions@^0.11.0
 ```
 
 ## Entry points
@@ -56,6 +56,8 @@ Register **one** resource in the clankerauth dashboard, identified by the applic
 
 A declared resource's `layer` 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.
 
+The public URL is where the listener that publishes discovery is reached, because an OAuth client refuses metadata naming another resource than the one it reached (RFC 9728). API keys never read discovery, so they keep working whatever the URL says; only OAuth logins fail. The resource therefore logs one warning the first time a request reaches its publishing listener at another host. A proxy that rewrites the host makes that warning harmless; anything else means the URL is wrong.
+
 Contracts state who may call them, `caller: CurrentPrincipal`, and a binding names how a caller proves it: an effect-actions authentication descriptor, declared once beside the contracts, where a browser client imports it too. The descriptor also declares what its verifier fails with besides a refusal: `ProviderUnavailable`, the issuer being unreachable.
 
 ```ts
@@ -111,9 +113,9 @@ const routes = Layer.mergeAll(
 
 Serve this layer with Effect's `HttpRouter` and your Node server layer. If using `@effect/platform-node`, install the release that matches your Effect. The scopes are the same in every deployment, so they are declared with the resource; `NotesResource.layer` takes what varies by deployment and builds the resource once: its verifier and refusals. `NotesResource.provider` is the descriptor's provider, effect-actions' `Authentication.layer`: it verifies every protected route and tool call before decoding, and publishes discovery itself, public and outside authentication; there is no discovery route to merge. Discovery cache policy belongs to the host. Every response to a request it authenticates carries `Cache-Control: no-store`. Middleware of your own runs as effect-actions runs it: router middleware provided after the provider, or an HTTP layer's `middleware`.
 
-A surface whose callers hold API keys and never run an OAuth flow, such as a second listener beside the one that publishes the resource, sets `discovery: false`: it authenticates the same way, publishes nothing, and its challenge is a plain `Bearer`.
+A surface whose callers hold API keys and never run an OAuth flow, such as a second listener beside the one that publishes the resource, sets `discovery: false`: it authenticates the same way, publishes nothing, and its challenge is a plain `Bearer`. It is the same registered resource, so it takes the publishing listener's public URL, not its own address: a public machine listener beside a private admin one still passes the admin URL.
 
-A process serving two resources, such as two listeners with different scopes, declares two descriptors and two resources: `Resource.make(Authentication.make("notes.admin", CurrentPrincipal, { error: ProviderUnavailable }), { scopes: ["notes:read", "notes:write"], required: "notes:read" })` and one for `"notes.machine"`, each named by its own binding. Each is a service of its own, so each surface reads its own resource, in one layer graph or several. The descriptor's name is the identity: declaring one name twice declares the same resource twice.
+Two listeners with different scopes, such as that admin and machine pair, are still one resource in the dashboard, with every scope of both. The process declares two descriptors and two resources over it, one per listener, each requiring its own scope and given the same `layer` options but `discovery`: `Resource.make(Authentication.make("notes.admin", CurrentPrincipal, { error: ProviderUnavailable }), { scopes: ["notes:read", "notes:write"], required: "notes:read" })` and one for `"notes.machine"`, each named by its own binding. Each is a service of its own, so each surface reads its own resource, in one layer graph or several. The descriptor's name is the identity: declaring one name twice declares the same resource twice.
 
 A declared resource is a `Resource.Declared<"notes.Login">`, and what its `layer` builds a `Resource.Built`; its descriptor is a `Resource.Login<"notes.Login">`. `Declared` and `Login` take what the descriptor declares as an optional second parameter, `ProviderUnavailable` alone when left out. `Declared` and `Built` take the resource's scopes as an optional parameter, last, which `make` infers from `scopes`: an annotation that leaves it out accepts any scope string. The entry point also exports each type a resource's declarations mention under a flat name (`DeclaredResource`, `BuiltResource`, `ResourceService`, `ResourceDeclaration`, `ResourceOptions`, `Login`, `Admission`, `Refusal`, `Principal`, `Verifier`); `CurrentPrincipal` and its `Caller` are `/session`'s, where declarations name them. So a package that exports its descriptor, its resource or its implementations emits declarations without an annotation.
 
@@ -296,7 +298,7 @@ Tagged errors, all from `@gjermundgaraba/clankerauth-sdk/errors`: `Unauthorized`
 
 There is one 403. Only the verifier's own check fails with `InsufficientScope`: a credential that is valid but lacks a scope in `requiredScopes`, a resource's `required`. It names that scope and the credential's `actor`, which decides whether its `Forbidden` steps up. A scope asked for after verification, by `requires(scope)`, `admitted(scope)`, `admit(header, scope)` or `watch(header, scope)`, is refused with effect-actions' `Action.Forbidden` directly, decided by the same rule. A credential that is not this resource's at all — the wrong audience, or an API key with no entry in this resource's key list — 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. 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 a token with an invented `kid` 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 verified offline, against the resource's key list: one document the issuer signs with its access-token key, holding a sealed entry per key granted on this resource, which only that key can find or open. The list is verified once, when it is read, and one read answers every key it names for a minute, without issuer traffic; so a key disabled, deleted or re-scoped keeps the access it had until the next read, within about a minute. A key the held list does not name may have been created, enabled or granted on this resource since, so the list is read again before the key is refused, unless it was read within the last five seconds: such a key works within seconds, and unknown keys reach the issuer at most once every five seconds. A key's own expiry is checked on every verification, so it applies at once. A failed read, one that takes longer than three seconds, or one whose caller gave up, is no error while the last list is inside its own lifetime, which the issuer sets to 24 hours: keys keep verifying through an outage, JWKS or not, and the issuer is tried again after five seconds. Past that lifetime, or before any list has been read, a key is `ProviderUnavailable`. Reads that start failing are logged once as a warning, and their recovery once at info level, so an outage the held list hides still shows in the application's logs without a line per retry. The last list read is the one held, whatever its `iat`: HTTPS to the issuer is what keeps an old list from being replayed, and one could only ever be replayed inside its own day. The issuer does not count key use, so rate limiting is the application's. A key is a bearer secret, and one granted on several resources can be replayed by any of them to the others; a resource you trust less gets its own key. A resource that accepts only OAuth access tokens sets `apiKeys: false`; key-shaped bearers then fail as `Unauthorized` without reading the key list. 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 exception is the key list read's own three seconds: shorter than that deadline, so an issuer that stops answering delays a key by at most that long, never fails it while a list is held.
+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 a token with an invented `kid` cannot become provider traffic. A failed read answers `ProviderUnavailable` (503) for five seconds before the next attempt; a read every waiting caller gave up on is dropped, and the next verification reads again. API keys are verified offline, against the resource's key list: one document the issuer signs with its access-token key, holding a sealed entry per key granted on this resource, which only that key can find or open. The list is verified once, when it is read, and one read answers every key it names for a minute, without issuer traffic; so a key disabled, deleted or re-scoped keeps the access it had until the next read, within about a minute. A key the held list does not name may have been created, enabled or granted on this resource since, so the list is read again before the key is refused, unless it was read within the last five seconds: such a key works within seconds, and unknown keys reach the issuer at most once every five seconds. A key's own expiry is checked on every verification, so it applies at once. A failed read, or one that takes longer than three seconds, is no error while the last list is inside its own lifetime, which the issuer sets to 24 hours: keys keep verifying through an outage, JWKS or not, and the issuer is tried again after five seconds. A read every waiting caller gave up on is dropped, and the next key reads again. Past that lifetime, or before any list has been read, a key is `ProviderUnavailable`. Reads that start failing are logged once as a warning, and their recovery once at info level, so an outage the held list hides still shows in the application's logs without a line per retry. The last list read is the one held, whatever its `iat`: HTTPS to the issuer is what keeps an old list from being replayed, and one could only ever be replayed inside its own day. The issuer does not count key use, so rate limiting is the application's. A key is a bearer secret, and one granted on several resources can be replayed by any of them to the others; a resource you trust less gets its own key. A resource that accepts only OAuth access tokens sets `apiKeys: false`; key-shaped bearers then fail as `Unauthorized` without reading the key list. 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 exception is the key list read's own three seconds: shorter than that deadline, so an issuer that stops answering delays a key by at most that long, never fails it while a list is held.
 
 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; a key list signed by it is not taken until then either, and the held list keeps deciding. Publish-before-use avoids that window; it is not mandatory. Key lists are re-signed on every read, so issued API keys are unaffected by rotation.
 

package/dist/resource.d.ts

@@ -20,8 +20,10 @@ export declare const authenticate: (verifier: Verifier.Verifier, token: Redacted
 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.
+     * The origin browsers and agents reach this application at: the listener that publishes
+     * discovery. The resource is its origin root, so any path here is discarded: one identifier
+     * covers `/api`, `/mcp` and sockets. A request reaching that listener at another host is
+     * logged once as a warning, since an OAuth client discovering the resource there refuses it.
      */
     readonly publicUrl: URL;
     /** `false` refuses API keys without reading the issuer's key list; only OAuth access tokens are accepted. */
@@ -29,7 +31,8 @@ export interface Options {
     /**
      * `false` publishes no RFC 9728 discovery and names none in a challenge: for a surface
      * whose callers hold API keys and never run an OAuth flow, such as a second listener
-     * beside the one that publishes the resource.
+     * beside the one that publishes the resource. That listener still names the same resource,
+     * so it takes the publishing listener's `publicUrl`, not its own.
      */
     readonly discovery?: boolean;
 }

package/dist/resource.js

@@ -1,7 +1,7 @@
-import { Clock, Context, Duration, Effect, Layer, Option, Redacted, Result } from "effect";
+import { Clock, Context, Duration, Effect, Layer, Option, Redacted, Ref, Result } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
-import { HttpRouter, HttpServerResponse } from "effect/http";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
 import { InsufficientScope, ProviderUnavailable, Unauthorized } from "./errors.js";
 import { keyListRefresh } from "./refresh.js";
 import { CurrentPrincipal, Whoami } from "./session.js";
@@ -63,9 +63,9 @@ const build = Effect.fn("Resource.layer")(function* (authentication, { scopes, r
         requiredScopes: [required],
         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. A key list read gives up
-    // sooner, so a held list still decides a key.
+    // A request must not wait on an issuer that does not answer: the credential is refused
+    // as unavailable, and a read no other request waits on is interrupted. A key list read
+    // gives up sooner, so a held list still decides a key.
     const deadline = (effect) => Effect.timeoutOrElse(effect, {
         duration: "5 seconds",
         orElse: () => Effect.fail(new ProviderUnavailable({ operation: "verify.timeout" })),
@@ -160,7 +160,24 @@ export const make = (authentication, declaration) => {
     // `E` declares `ProviderUnavailable`, which a generic `E` cannot show the types by itself.
     const declaring = authentication;
     // The descriptor's verifier: a token to its principal, a refusal, or `ProviderUnavailable`.
-    const provider = Authentication.layer(declaring, Effect.map(service, ({ verifier }) => (token) => authenticate(verifier, token)), { protectedResource: Effect.map(service, ({ protectedResource }) => protectedResource) });
+    const provider = Authentication.layer(declaring, Effect.gen(function* () {
+        const { verifier, resource, protectedResource } = yield* service;
+        const host = new URL(resource).host;
+        const warned = yield* Ref.make(protectedResource === undefined);
+        // RFC 9728 has a client refuse metadata naming another resource than the one it
+        // reached, so a listener publishing discovery at another host fails every OAuth login
+        // while keys keep working. A proxy may rewrite the host, so this warns and refuses nothing.
+        const noteHost = Effect.gen(function* () {
+            if (yield* Ref.get(warned))
+                return;
+            const reached = (yield* HttpServerRequest.HttpServerRequest).headers.host;
+            if (reached === undefined || reached === host)
+                return;
+            yield* Ref.set(warned, true);
+            yield* Effect.logWarning(`The resource ${resource} publishes discovery, but a request reached it at ${reached}: an OAuth client discovering it there refuses the mismatch. Set publicUrl to the origin this listener is reached at.`);
+        });
+        return (token) => Effect.andThen(noteHost, authenticate(verifier, token));
+    }), { protectedResource: Effect.map(service, ({ protectedResource }) => protectedResource) });
     /**
      * Refuse a caller that lacks `scope`, as the application's authorizer decides:
      * `Action.implement(actions, handlers, { authorize: (action) => action.readOnly ? Effect.void : Notes.requires("notes:write") })`.

package/dist/verify.js

@@ -1,4 +1,4 @@
-import { Cause, Clock, Duration, Effect, Exit, Ref, Result, Schema } from "effect";
+import { Clock, Duration, Effect, Exit, Ref, Result, Schema } from "effect";
 import { createLocalJWKSet, decodeProtectedHeader, jwtVerify } from "jose";
 import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http";
 import { ConfigurationError, InsufficientScope, ProviderUnavailable, Unauthorized, } from "./errors.js";
@@ -66,15 +66,10 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
             keys: jwks.keys.map(({ key_ops, ...key }) => key_ops ? { ...key, key_ops: [...key_ops] } : key),
         });
     }, 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 : cooldown);
-    // Replaying a 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 replayed = (cached, operation) => Effect.catchCause(cached, (cause) => Cause.hasInterrupts(cause)
-        ? Effect.fail(new ProviderUnavailable({ operation }))
-        : Effect.failCause(cause));
-    const keys = replayed(read, "jwks.refresh");
+    // One read serves every key identifier until it expires, or for the cooldown if it
+    // failed, so an unknown `kid` in an unauthenticated request never becomes traffic at
+    // the issuer. A read every caller gave up on is dropped, and the next caller reads again.
+    const keys = yield* Effect.cachedWithTTL(document(), (exit) => Exit.isSuccess(exit) ? documentLifetime : cooldown);
     const signingKey = Effect.fn("Verifier.signingKey")(function* (kid) {
         const resolve = yield* keys;
         return yield* Effect.tryPromise({
@@ -159,7 +154,7 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
     const held = yield* Ref.make(undefined);
     /** The list read now, or within the cooldown, or else the held one, while inside its window. */
     const latest = Effect.gen(function* () {
-        const fetched = yield* Effect.result(replayed(readList, "key-list.refresh"));
+        const fetched = yield* Effect.result(readList);
         if (Result.isSuccess(fetched))
             yield* Ref.set(held, fetched.success);
         const list = yield* Ref.get(held);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/clankerauth-sdk",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Effect-native clankerauth access-token and offline API-key verification, with optional effect-actions integration",
   "license": "MIT",
   "repository": {
@@ -46,17 +46,17 @@
     "jose": "6.2.12"
   },
   "devDependencies": {
-    "@gjermundgaraba/effect-actions": "0.10.0",
-    "@modelcontextprotocol/client": "2.0.0",
-    "@types/node": "26.6.2",
-    "effect": "4.0.0",
+    "@gjermundgaraba/effect-actions": "0.11.0",
+    "@modelcontextprotocol/client": "2.3.1",
+    "@types/node": "26.6.4",
+    "effect": "4.0.2",
     "typescript": "7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0",
-    "vite-plus": "1.0.0"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
+    "vite-plus": "1.1.0"
   },
   "peerDependencies": {
-    "@gjermundgaraba/effect-actions": "^0.10.0",
-    "effect": "^4.0.0"
+    "@gjermundgaraba/effect-actions": "^0.11.0",
+    "effect": "^4.0.2"
   },
   "peerDependenciesMeta": {
     "@gjermundgaraba/effect-actions": {