@gjermundgaraba/clankerauth-sdk 0.22.0 → 0.23.1

package/README.md

@@ -17,19 +17,19 @@ 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.16.0
+vp add @gjermundgaraba/effect-actions@^0.17.0
 ```
 
 ## Entry points
 
-| Import                             | Needs effect-actions | Browser safe | What it holds                                                                         |
-| ---------------------------------- | -------------------- | ------------ | ------------------------------------------------------------------------------------- |
-| `…/clankerauth-sdk`                | no                   | no           | `Verifier`, `RequestPolicy`                                                           |
-| `…/clankerauth-sdk/errors`         | no                   | **yes**      | the verifier's errors; `ProviderUnavailable` is the one a descriptor declares         |
-| `…/clankerauth-sdk/session`        | yes                  | **yes**      | `CurrentPrincipal` and its `Caller`, the `Whoami` contract, `Principal`, `signOutUrl` |
-| `…/clankerauth-sdk/effect-actions` | yes                  | no           | `Resource`                                                                            |
-| `…/clankerauth-sdk/key-list`       | no                   | no           | the key list format, for issuers and fakes                                            |
-| `…/clankerauth-sdk/testing`        | no                   | no           | `startFakeIssuer`, for tests (Node only)                                              |
+| Import                             | Needs effect-actions | Browser safe | What it holds                                                                                                             |
+| ---------------------------------- | -------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| `…/clankerauth-sdk`                | no                   | no           | `Verifier`, `RequestPolicy`                                                                                               |
+| `…/clankerauth-sdk/errors`         | no                   | **yes**      | the verifier's errors; `ProviderUnavailable` is the one a descriptor declares                                             |
+| `…/clankerauth-sdk/session`        | yes                  | **yes**      | `CurrentPrincipal` and its `Caller`, the `Whoami` contract, `Principal`, `signOutUrl`, `signOutPath`, `returnToParameter` |
+| `…/clankerauth-sdk/effect-actions` | yes                  | no           | `Resource`                                                                                                                |
+| `…/clankerauth-sdk/key-list`       | no                   | no           | the key list format and `keyPrefix`, for issuers and fakes                                                                |
+| `…/clankerauth-sdk/testing`        | no                   | no           | `startFakeIssuer`, for tests (Node only)                                                                                  |
 
 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.
 

package/dist/key-list.d.ts

@@ -13,6 +13,8 @@
 import { Schema } from "effect";
 /** The list's JWT `typ`, so neither a list nor an access token can pass for the other. */
 export declare const type = "key-list+jwt";
+/** Every API key the issuer creates begins with this, which tells it apart from a JWT. */
+export declare const keyPrefix = "clankerauth_";
 /**
  * How long a list decides, in seconds from its `iat`: for as long as a resource server
  * cannot read a newer one, it keeps accepting the keys this one grants. So it is also the

package/dist/key-list.js

@@ -14,6 +14,8 @@ import { Schema } from "effect";
 import { base64url } from "jose";
 /** The list's JWT `typ`, so neither a list nor an access token can pass for the other. */
 export const type = "key-list+jwt";
+/** Every API key the issuer creates begins with this, which tells it apart from a JWT. */
+export const keyPrefix = "clankerauth_";
 /**
  * How long a list decides, in seconds from its `iat`: for as long as a resource server
  * cannot read a newer one, it keeps accepting the keys this one grants. So it is also the

package/dist/request-policy.d.ts

@@ -25,7 +25,7 @@ export interface Request {
  */
 export declare const make: (options: Options) => {
     allows: (request: Request) => boolean;
-    /** Refuse anything `allows` rejects with an empty-bodied 403, before any handler. */
+    /** Refuse anything `allows` rejects with a 403 (body `Forbidden`) before any handler. */
     middleware: HttpRouter.Middleware<{
         provides: never;
         handles: never;

package/dist/request-policy.js

@@ -36,14 +36,13 @@ export const make = (options) => {
     const allows = (request) => {
         if (pathOf(request.target) === probePath)
             return true;
-        // A request with no Host is not a browser request for this app's origin.
         if (request.host !== host)
             return false;
         return request.origin === undefined || origins.has(request.origin);
     };
     return {
         allows,
-        /** Refuse anything `allows` rejects with an empty-bodied 403, before any handler. */
+        /** Refuse anything `allows` rejects with a 403 (body `Forbidden`) before any handler. */
         middleware: HttpRouter.middleware((httpEffect) => Effect.gen(function* () {
             const request = yield* HttpServerRequest.HttpServerRequest;
             const permitted = allows({

package/dist/resource.js

@@ -45,11 +45,7 @@ const refusalOf = (error) => {
  */
 export const authenticate = (verifier, token) => Effect.mapError(verifier.verifyToken(Redacted.value(token)), refusalOf);
 const build = Effect.fn("Resource.layer")(function* (authentication, { scopes, required }, options) {
-    // One resource per application, at the public origin root, trailing slash and all.
-    // An MCP client sends `new URL(metadata.resource).href`, and the token's audience is
-    // that string, so deriving it here is what keeps the two in agreement.
     const identifier = new URL("/", options.publicUrl).href;
-    // effect-actions checks every scope here is an OAuth scope token, when the provider builds.
     const metadata = {
         resource: identifier,
         authorizationServers: [options.issuer],
@@ -63,9 +59,6 @@ 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 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" })),
@@ -80,7 +73,6 @@ const build = Effect.fn("Resource.layer")(function* (authentication, { scopes, r
      */
     const principalOf = Effect.fn("Resource.principal")(function* (authorization, scope) {
         const token = Authentication.bearerTokenOf(authorization);
-        // As a protected route refuses a request without one, before its verifier runs.
         if (Option.isNone(token))
             return yield* new Action.Unauthenticated({ message: "A bearer token is required." });
         const principal = yield* authenticate(verifier, token.value);
@@ -97,7 +89,6 @@ const build = Effect.fn("Resource.layer")(function* (authentication, { scopes, r
         const verified = yield* Effect.result(principalOf(authorization, scope));
         if (Result.isSuccess(verified))
             return { ok: true, principal: verified.success };
-        // A refusal, or the `ProviderUnavailable` the descriptor declares, as its routes send it.
         const web = HttpServerResponse.toWeb(Authentication.refusalResponse(verified.failure, {
             authentication,
             protectedResource,
@@ -121,12 +112,8 @@ const build = Effect.fn("Resource.layer")(function* (authentication, { scopes, r
         const principal = yield* principalOf(authorization, scope);
         const now = yield* Clock.currentTimeMillis;
         const remaining = Math.max(0, (principal.expiresAt ?? Infinity) - now);
-        // A key is checked again against each refreshed list, until it expires.
         if (principal.actor.kind === "key")
             return yield* Effect.sleep(Math.min(remaining, Duration.toMillis(keyListRefresh)));
-        // An access token cannot be revoked and never becomes valid again, so its expiry is
-        // all that ends it: no second JWKS read that an issuer outage could fail. It ends as
-        // the verifier refuses an expired token.
         yield* Effect.sleep(remaining);
         return yield* refusalOf(new Unauthorized());
     }));
@@ -156,17 +143,11 @@ export const make = (authentication, declaration) => {
     const { scopes } = declaration;
     const service = Context.Service(`@clankerauth/Resource/${authentication.name}`);
     const layer = (options) => Layer.effect(service, build(authentication, declaration, options));
-    // The descriptor as the verifier fails: `DeclaresUnavailable` holds that every alternative of
-    // `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.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;

package/dist/session.d.ts

@@ -47,6 +47,10 @@ export declare const Whoami: Action.Action<"whoami", Schema.$Record<Schema.Strin
     readonly issuer: Schema.NonEmptyString;
     readonly scopes: Schema.$Array<Schema.String>;
 }>, readonly never[], true, typeof CurrentPrincipal>;
+/** The query parameter naming where the issuer sends the owner after signing in or out. */
+export declare const returnToParameter = "rd";
+/** Where the issuer signs the owner out and clears the forward cookie. */
+export declare const signOutPath = "/forward-auth/logout";
 /**
  * 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.

package/dist/session.js

@@ -32,12 +32,16 @@ export const Whoami = Action.make("whoami", {
     caller: CurrentPrincipal,
     success: Principal,
 });
+/** The query parameter naming where the issuer sends the owner after signing in or out. */
+export const returnToParameter = "rd";
+/** Where the issuer signs the owner out and clears the forward cookie. */
+export const signOutPath = "/forward-auth/logout";
 /**
  * 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);
+    const url = new URL(signOutPath, issuer);
+    url.searchParams.set(returnToParameter, returnTo);
     return url.href;
 };

package/dist/testing.js

@@ -41,8 +41,6 @@ export const startFakeIssuer = async (options) => {
         if (Option.isNone(asked))
             return send(400, '{"error":"Invalid request"}');
         const { resource } = asked.value;
-        // Like the real issuer, a list holds only what is granted on the resource it names,
-        // and only what has not expired.
         const now = Date.now();
         const entries = await Promise.all([...keys].flatMap(([key, { keyId, permissions, expiresAt }]) => {
             const scopes = permissions[resource] ?? [];
@@ -85,7 +83,7 @@ export const startFakeIssuer = async (options) => {
                 .sign(pair.privateKey);
         },
         apiKey: (permissions = { [options.resource]: options.scopes }, expiresAt) => {
-            const key = `clankerauth_${randomBytes(48).toString("base64url")}`;
+            const key = `${KeyList.keyPrefix}${randomBytes(48).toString("base64url")}`;
             keys.set(key, {
                 keyId: `key-${++minted}`,
                 permissions,

package/dist/transport.js

@@ -1,8 +1,6 @@
 import { Context, Effect } from "effect";
 import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/http";
 import { ProviderUnavailable } from "./errors.js";
-// Node transports do not follow redirects by default. Also pin FetchHttpClient's policy;
-// forwarding credentials through a redirect is not an authentication fallback.
 export const execute = (client, request) => Effect.contextWith((context) => HttpClient.withScope(client)
     .execute(request)
     .pipe(Effect.provideService(FetchHttpClient.RequestInit, {

package/dist/verify.js

@@ -66,15 +66,11 @@ 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, 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({
             try: () => resolve({ alg: "EdDSA", kid }),
-            // Selecting from fetched keys does no I/O: every failure is the credential's.
             catch: unauthorized,
         });
     });
@@ -89,8 +85,7 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
             try: () => decodeProtectedHeader(jws),
             catch: unauthorized,
         });
-        // The issuer always names its key, so key selection is never ambiguous. Reject other
-        // documents before doing provider I/O; JOSE still enforces its algorithm allowlist.
+        // why: refused before any JWKS read, so an unauthenticated request causes no issuer traffic.
         if (header.alg !== "EdDSA" || header.kid === undefined)
             return yield* unauthorized();
         const key = yield* signingKey(header.kid);
@@ -103,7 +98,6 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
                 typ,
                 currentDate: new Date(now),
             }),
-            // Verification against a resolved key does no I/O either.
             catch: unauthorized,
         });
         return payload;
@@ -117,7 +111,6 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
             subject: claims.sub,
             scopes: claims.scope.split(" ").filter(Boolean),
             actor: { kind: "client", clientId: claims.client_id },
-            // `jwtVerify` already checked this claim against the current time.
             expiresAt: claims.exp * 1000,
         };
     });
@@ -130,7 +123,6 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
                 cause: { status: response.status },
             });
         const { list } = yield* HttpClientResponse.schemaBodyJson(KeyListResponse)(response).pipe(Effect.mapError((cause) => new ProviderUnavailable({ operation: "key-list.decode", cause })));
-        // A list that does not verify is no list: the held one keeps deciding.
         const rejected = (cause) => new ProviderUnavailable({ operation: "key-list.verify", cause });
         const payload = yield* verifySigned(list, KeyList.type).pipe(Effect.catchTag("Unauthorized", (cause) => Effect.fail(rejected(cause))));
         const claims = yield* Schema.decodeUnknownEffect(KeyListClaims)(payload).pipe(Effect.mapError(rejected));
@@ -140,8 +132,6 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
             entries: new Map(claims.keys.map((entry) => [entry.id, entry.sealed])),
         };
     }, Effect.scoped);
-    // While a list is held, a failing issuer is otherwise invisible until that list runs
-    // out. Reads are logged when they start failing and when they recover, not per retry.
     const failing = yield* Ref.make(false);
     const readList = yield* Effect.cachedWithTTL(listDocument().pipe(Effect.timeoutOrElse({
         duration: listReadTimeout,
@@ -149,8 +139,6 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
     }), Effect.tapError(({ operation }) => Effect.flatMap(Ref.getAndSet(failing, true), (was) => was
         ? Effect.void
         : Effect.logWarning("clankerauth key list reads are failing; a held list decides until it expires", { operation }))), Effect.tap(() => Effect.flatMap(Ref.getAndSet(failing, false), (was) => was ? Effect.logInfo("clankerauth key list reads have recovered") : Effect.void))), cooldown);
-    // The list is verified once, when it is read. Holding its entries, not the document,
-    // is what lets keys verify through an outage that has already taken JWKS with it.
     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* () {
@@ -158,7 +146,6 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
         if (Result.isSuccess(fetched))
             yield* Ref.set(held, fetched.success);
         const list = yield* Ref.get(held);
-        // A list is held past its own check, so the window is checked on every use.
         if (list !== undefined && list.expiresAt > (yield* Clock.currentTimeMillis))
             return list;
         return yield* Result.isFailure(fetched)
@@ -172,17 +159,13 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
         });
         const now = yield* Clock.currentTimeMillis;
         const current = yield* Ref.get(held);
-        // One read decides the keys it names for a minute, without the issuer.
         const list = current !== undefined &&
             now - current.readAt < Duration.toMillis(keyListRefresh) &&
             current.expiresAt > now
             ? current
             : yield* latest;
-        // A key it does not name may have been created since, so the list is read again,
-        // unless a read answered within the cooldown and there is nothing new to look in.
         const grant = (yield* open(list)) ??
             (yield* Effect.flatMap(latest, (next) => next === list ? Effect.succeed(undefined) : open(next)));
-        // No entry is the same case as a token for another audience: not this resource's.
         if (grant === undefined)
             return yield* unauthorized();
         if (grant.expiresAt !== null && grant.expiresAt <= (yield* Clock.currentTimeMillis))
@@ -195,7 +178,7 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
         };
     });
     const verifyToken = Effect.fn("Verifier.verifyToken")(function* (token) {
-        const principal = yield* token.startsWith("clankerauth_")
+        const principal = yield* token.startsWith(KeyList.keyPrefix)
             ? options.apiKeys === false
                 ? Effect.fail(unauthorized())
                 : verifyKey(token)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/clankerauth-sdk",
-  "version": "0.22.0",
+  "version": "0.23.1",
   "description": "Effect-native clankerauth access-token and offline API-key verification, with optional effect-actions integration",
   "license": "MIT",
   "repository": {
@@ -46,16 +46,18 @@
     "jose": "6.2.12"
   },
   "devDependencies": {
-    "@gjermundgaraba/effect-actions": "0.16.0",
+    "@effect/vitest": "4.0.4",
+    "@gjermundgaraba/effect-actions": "0.17.0",
     "@modelcontextprotocol/client": "2.3.1",
     "@types/node": "26.6.4",
     "effect": "4.0.4",
     "typescript": "7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
-    "vite-plus": "1.1.0"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.2.0",
+    "vite-plus": "1.2.0",
+    "vitest": "5.0.4"
   },
   "peerDependencies": {
-    "@gjermundgaraba/effect-actions": "^0.16.0",
+    "@gjermundgaraba/effect-actions": "^0.17.0",
     "effect": "^4.0.4"
   },
   "peerDependenciesMeta": {