@gjermundgaraba/clankerauth-sdk 0.14.0 → 0.16.0

package/README.md

@@ -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.
 

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";
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/clankerauth-sdk",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Effect-native clankerauth access-token and offline API-key verification, with optional effect-actions integration",
   "license": "MIT",
   "repository": {