@gjermundgaraba/clankerauth-sdk 0.5.0 → 0.6.0

package/README.md

@@ -37,12 +37,18 @@ const makeVerifier = Verifier.make({
 Install the optional peer dependency and import the integration subpath:
 
 ```sh
-vp add @gjermundgaraba/effect-actions@0.2.0
+vp add @gjermundgaraba/effect-actions@0.3.0
 ```
 
 Core and integration declarations both type-check without `skipLibCheck`.
 
-Register a resource in the Clanker Auth dashboard. Its identifier is the exact audience URL, not just an origin. Acquire one resource capability per protected audience at application construction, not per request.
+## 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.
+
+Acquire the resource once at application construction, never per request.
 
 ```ts
 import { Effect, Layer } from "effect";
@@ -54,26 +60,21 @@ import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 // Http and app are your effect-actions HTTP binding and implemented group.
 const routes = Layer.unwrap(
   Effect.gen(function* () {
-    const api = yield* Resource.make({
-      issuer: "https://auth.internal/api/auth",
-      resource: "https://notes.internal/api",
-      scopes: ["notes:read", "notes:write"],
-      requiredScopes: ["notes:read"],
-    });
-    const mcp = yield* Resource.make({
+    const notes = yield* Resource.make({
       issuer: "https://auth.internal/api/auth",
-      resource: "https://notes.internal/mcp",
+      resource: "https://notes.internal/",
       scopes: ["notes:read", "notes:write"],
       requiredScopes: ["notes:read"],
+      writeScope: "notes:write",
     });
+
     return Layer.mergeAll(
-      api.discovery.layer,
-      mcp.discovery.layer,
-      Http.layer(app).pipe(Layer.provide(Resource.middleware(api).layer)),
+      notes.discovery.layer,
+      Http.layer(app).pipe(Layer.provide(Resource.middleware(notes).layer)),
       ActionMcp.layerHttp(
         { name: "notes", version: "1.0.0", path: "/mcp", protocols: [McpProtocol.v2026_07_28] },
         app,
-      ).pipe(Layer.provide(Resource.middleware(mcp).layer)),
+      ).pipe(Layer.provide(Resource.middleware(notes).layer)),
     );
   }),
 ).pipe(Layer.provide(FetchHttpClient.layer));
@@ -83,25 +84,79 @@ Serve this layer with Effect's `HttpRouter` and your Node server layer. If using
 
 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.
 
-An action reads identity from `CurrentPrincipal` and enforces its own permissions:
+## 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.
 
 ```ts
-import { Effect } from "effect";
-import { Forbidden } from "@gjermundgaraba/clankerauth-sdk";
-import { CurrentPrincipal } from "@gjermundgaraba/clankerauth-sdk/effect-actions";
-
-const write = Effect.gen(function* () {
-  const principal = yield* CurrentPrincipal;
-  if (!principal.scopes.includes("notes:write")) {
-    return yield* new Forbidden({ message: "Write permission required" });
-  }
-  return principal.subject;
-});
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
+import { InsufficientScope } from "@gjermundgaraba/clankerauth-sdk";
+
+const Notes = ActionGroup.make(
+  { name: "notes", errors: [InsufficientScope] },
+  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 });
+```
+
+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.
+
+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.
+
+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`:
+
+```ts
+const admission = await Effect.runPromise(notes.admit(request.headers.authorization, "write"));
+
+if (!admission.ok) {
+  const { status, headers, body } = admission.refusal;
+  response.writeHead(status, headers).end(body);
+  return;
+}
+
+connect(admission.principal);
 ```
 
-Declare `Forbidden` in that action/group's error schemas. Middleware authenticates the request; it does not infer per-action policy or filter MCP tool discovery.
+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 resource also exposes `verifier.verify(authorization)` and `verifier.verifyToken(token)` as Effects for callers that render their own responses.
+
+## Request policy
+
+Forward auth makes a browser's credential ambient: the proxy attaches an `Authorization` header to whatever the browser sends, including a cross-site navigation. So an application behind it checks where a request came from before anything reads the credential.
+
+```ts
+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));
+
+// The same decision from a Node upgrade handler, with no services:
+if (
+  !policy.allows({
+    target: request.url,
+    host: request.headers.host,
+    origin: request.headers.origin,
+  })
+) {
+  socket.end("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
+}
+```
 
-A principal contains `subject`, `scopes`, and `actor`: either `{ kind: "client", clientId }` or `{ kind: "key", keyId }`. The resource also exposes `verifier.verify(authorization)` and `verifier.verifyToken(token)` as Effects.
+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.
 
 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.
 
@@ -113,7 +168,7 @@ Browser apps do not use this package. Put them behind a reverse proxy with the i
 
 ## Errors and observability
 
-Schema-tagged errors: `Unauthorized` (401), `Forbidden` (403), `RateLimited` (429) and `ProviderUnavailable` (503). Invalid construction fails with `ConfigurationError`.
+Schema-tagged errors: `Unauthorized` (401), `Forbidden` (403), `InsufficientScope` (403), `RateLimited` (429) and `ProviderUnavailable` (503). Invalid construction fails with `ConfigurationError`.
 
 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,2 +1,3 @@
 export * as Resource from "./resource.ts";
 export { CurrentPrincipal } from "./resource.ts";
+export { InsufficientScope } from "./errors.ts";

package/dist/effect-actions.js

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

package/dist/errors.d.ts

@@ -31,6 +31,15 @@ export declare class ProviderUnavailable extends ProviderUnavailable_base {
         readonly cause?: unknown;
     });
 }
+declare const InsufficientScope_base: Schema.Class<InsufficientScope, Schema.TaggedStruct<"InsufficientScope", {
+    readonly scope: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A verified credential lacks one scope the requested access needs. It names only
+ * the missing scope, so a refusal never enumerates the resource's permissions.
+ */
+export declare class InsufficientScope extends InsufficientScope_base {
+}
 declare const ConfigurationError_base: Schema.Class<ConfigurationError, Schema.TaggedStruct<"ConfigurationError", {
     readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
@@ -38,6 +47,16 @@ 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;
-/** Encode one of the declared schemas as JSON with its `httpApiStatus`. Undeclared errors are defects. */
-export declare const encodeError: <const Schemas extends ReadonlyArray<Schema.Top>>(schemas: Schemas) => (error: Schemas[number]["Type"], headers?: Headers.Input) => Effect.Effect<HttpServerResponse.HttpServerResponse, never, { [K in keyof Schemas]: Schemas[K]["EncodingServices"]; }[number]>;
+/** 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>;
 export {};

package/dist/errors.js

@@ -17,6 +17,12 @@ export class ProviderUnavailable extends Schema.TaggedError()("ProviderUnavailab
         Object.defineProperty(this, "cause", { value: options.cause });
     }
 }
+/**
+ * A verified credential lacks one scope the requested access needs. It names only
+ * the missing scope, so a refusal never enumerates the resource's permissions.
+ */
+export class InsufficientScope extends Schema.TaggedError()("InsufficientScope", { scope: Schema.String }, { httpApiStatus: 403 }) {
+}
 export class ConfigurationError extends Schema.TaggedError()("ConfigurationError", { message: Schema.String }) {
 }
 export const authenticationErrors = [
@@ -25,16 +31,30 @@ export const authenticationErrors = [
     RateLimited,
     ProviderUnavailable,
 ];
-/** Encode one of the declared schemas as JSON with its `httpApiStatus`. Undeclared errors are defects. */
-export const encodeError = (schemas) => {
-    const encode = HttpServerResponse.schemaJson(Schema.Union(schemas));
-    return (error, headers) => {
-        const schema = schemas.find((schema) => Schema.is(schema)(error));
-        if (schema === undefined)
-            return Effect.die(new Error("Undeclared error"));
-        return encode(error, {
+/** 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,
-            headers,
-        }).pipe(Effect.orDie);
+            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,3 +1,4 @@
 export * as Verifier from "./verify.ts";
+export * as RequestPolicy from "./request-policy.ts";
 export type { Principal } from "./verify.ts";
-export { Unauthorized, Forbidden, RateLimited, ProviderUnavailable, ConfigurationError, type AuthenticationError, } from "./errors.ts";
+export { Unauthorized, Forbidden, InsufficientScope, RateLimited, ProviderUnavailable, ConfigurationError, authenticationErrors, admissionErrors, type AdmissionError, type AuthenticationError, } from "./errors.ts";

package/dist/index.js

@@ -1,2 +1,3 @@
 export * as Verifier from "./verify.js";
-export { Unauthorized, Forbidden, RateLimited, ProviderUnavailable, ConfigurationError, } from "./errors.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

@@ -0,0 +1,43 @@
+import { HttpRouter } from "effect/unstable/http";
+export interface Options {
+    /**
+     * The origin browsers reach this app at. The application has already validated it;
+     * its `host` (with port, when the scheme's default is not used) must equal the Host
+     * header, and its `origin` is the one Origin accepted by default.
+     */
+    readonly publicUrl: URL;
+    /**
+     * Origins accepted besides the public one, compared exactly. For a desktop shell
+     * 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 {
+    /** The request target: `/a?b` or an absolute URL. Only its path is read. */
+    readonly target: string;
+    readonly host: string | undefined;
+    readonly origin: string | undefined;
+}
+/**
+ * Build the policy once, at startup. `allows` is the whole decision and takes no
+ * services, so a Node `upgrade` handler applies the same rule as the router.
+ */
+export declare const make: (options: Options) => {
+    allows: (request: Request) => boolean;
+    /** Refuse anything `allows` rejects with an empty-bodied 403, before any handler. */
+    middleware: HttpRouter.Middleware<{
+        provides: never;
+        handles: never;
+        error: never;
+        requires: never;
+        layerError: never;
+        layerRequires: never;
+    }>;
+};
+export type Policy = ReturnType<typeof make>;

package/dist/request-policy.js

@@ -0,0 +1,53 @@
+/**
+ * Which callers this app answers at all. Forward auth makes a browser's credential
+ * ambient: the proxy attaches an Authorization header to whatever the browser sends,
+ * including a cross-site navigation. So the app checks the two headers that say where
+ * a request came from, before anything reads the credential.
+ *
+ * Both checks are raw string comparisons on the headers as sent. Nothing is parsed,
+ * so nothing throws and no normalization can widen what is accepted: `notes.example`
+ * and `notes.example:443` are different hosts here, as they are to a browser's cookie.
+ */
+import { Effect } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+/** The path of a request target. Deliberately not `new URL`: this must not throw. */
+const pathOf = (target) => {
+    const authority = target.indexOf("://");
+    const start = authority === -1 ? 0 : target.indexOf("/", authority + 3);
+    if (start === -1)
+        return "/";
+    const rest = target.slice(start);
+    const stop = rest.search(/[?#]/u);
+    return stop === -1 ? rest : rest.slice(0, stop);
+};
+const forbidden = HttpServerResponse.text("Forbidden", { status: 403 });
+/**
+ * Build the policy once, at startup. `allows` is the whole decision and takes no
+ * services, so a Node `upgrade` handler applies the same rule as the router.
+ */
+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)))
+            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. */
+        middleware: HttpRouter.middleware((httpEffect) => Effect.gen(function* () {
+            const request = yield* HttpServerRequest.HttpServerRequest;
+            const permitted = allows({
+                target: request.originalUrl,
+                host: request.headers.host,
+                origin: request.headers.origin,
+            });
+            return permitted ? yield* httpEffect : forbidden;
+        })),
+    };
+};

package/dist/resource.d.ts

@@ -1,15 +1,39 @@
 import { Context, Effect } from "effect";
+import type * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
-import { ConfigurationError, Forbidden, RateLimited, Unauthorized } from "./errors.ts";
-import type { AuthenticationError } from "./errors.ts";
+import { ConfigurationError, Forbidden, InsufficientScope, RateLimited, Unauthorized } from "./errors.ts";
+import type { AdmissionError } 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[];
+    /**
+     * 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.
+     */
+    readonly writeScope?: string;
 }
-/** One resource: its verifier and discovery. Acquire once per protected audience. */
+/**
+ * A refusal a caller outside the router can send as-is: an RFC 6750 challenge or a
+ * `Retry-After`, `Cache-Control: no-store`, and the error's own JSON encoding.
+ */
+export interface Refusal {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+}
+/** What one Authorization header value amounts to for this resource. */
+export type Admission = {
+    readonly ok: true;
+    readonly principal: Verifier.Principal;
+} | {
+    readonly ok: false;
+    readonly refusal: Refusal;
+};
+/** One resource: its verifier, discovery, scope policy and refusals. Acquire once per audience. */
 export declare const make: (options: Options) => Effect.Effect<{
     verifier: {
         verifyToken: (token: string) => Effect.Effect<{
@@ -19,6 +43,7 @@ export declare const make: (options: Options) => Effect.Effect<{
                 kind: "client";
                 clientId: string;
             };
+            expiresAt: number;
         } | {
             subject: string;
             scopes: readonly string[];
@@ -26,6 +51,7 @@ export declare const make: (options: Options) => Effect.Effect<{
                 kind: "key";
                 keyId: string;
             };
+            expiresAt: undefined;
         }, Forbidden | import("./errors.ts").ProviderUnavailable | RateLimited | Unauthorized, never>;
         verify: (authorization: string | null | undefined) => Effect.Effect<{
             subject: string;
@@ -34,6 +60,7 @@ export declare const make: (options: Options) => Effect.Effect<{
                 kind: "client";
                 clientId: string;
             };
+            expiresAt: number;
         } | {
             subject: string;
             scopes: readonly string[];
@@ -41,6 +68,7 @@ export declare const make: (options: Options) => Effect.Effect<{
                 kind: "key";
                 keyId: string;
             };
+            expiresAt: undefined;
         }, Forbidden | import("./errors.ts").ProviderUnavailable | RateLimited | Unauthorized, never>;
     };
     discovery: {
@@ -51,18 +79,17 @@ export declare const make: (options: Options) => Effect.Effect<{
     challenge: (error?: "invalid_token" | "insufficient_scope") => {
         "www-authenticate": string;
     };
-    headers: (error: AuthenticationError) => {
-        "www-authenticate": string;
-    } | {
-        "retry-after": string;
-    } | {
-        "retry-after"?: undefined;
+    headers: (error: AdmissionError) => {
+        [x: string]: string;
     };
+    admit: (authorization: string | null | undefined, access?: Action.Access | undefined) => Effect.Effect<Admission, never, never>;
+    authorize: (action: Action.Any) => Effect.Effect<void, InsufficientScope, CurrentPrincipal>;
     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`. */
+/** Bearer authentication providing `CurrentPrincipal`, on the same admission `admit` renders. */
 export declare const middleware: (resource: Resource) => import("effect/unstable/http/HttpRouter").Middleware<{
     provides: CurrentPrincipal;
     handles: never;

package/dist/resource.js

@@ -1,13 +1,23 @@
-import { Context, Effect } from "effect";
+import { Context, Effect, Result } from "effect";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
-import { HttpServerRequest } from "effect/unstable/http";
-import { authenticationErrors, ConfigurationError, encodeError, Forbidden, RateLimited, Unauthorized, } from "./errors.js";
+import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { admissionErrors, ConfigurationError, describeError, Forbidden, InsufficientScope, RateLimited, Unauthorized, } from "./errors.js";
 import * as Verifier from "./verify.js";
-const encode = encodeError(authenticationErrors);
+const describe = describeError(admissionErrors);
 export class CurrentPrincipal extends Context.Service()("@clankerauth/CurrentPrincipal") {
 }
-/** One resource: its verifier and discovery. Acquire once per protected audience. */
+/** One resource: its verifier, discovery, scope policy and refusals. Acquire once per audience. */
 export const make = Effect.fn("Resource.make")(function* (options) {
+    // 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}`,
+    })));
     const discovery = yield* Effect.try({
         try: () => Authentication.protectedResource({
             resource: options.resource,
@@ -18,37 +28,94 @@ export const make = Effect.fn("Resource.make")(function* (options) {
     });
     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": discovery.challenge({ error, scope }),
+        "www-authenticate": challengeValue(error),
     });
-    const headers = (error) => {
+    /**
+     * 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.
+     */
+    const refusalHeader = (error, credential) => {
         if (error instanceof RateLimited)
-            return { "retry-after": "60" };
+            return ["retry-after", "60"];
+        if (error instanceof InsufficientScope)
+            return ["www-authenticate", challengeValue("insufficient_scope", error.scope)];
         if (error instanceof Forbidden)
-            return challenge("insufficient_scope");
+            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 challenge("invalid_token");
-        return {};
+            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: {
+            status,
+            headers: {
+                ...asRecord(refusalHeader(error, authorization !== undefined && authorization !== null)),
+                "content-type": "application/json",
+                "cache-control": "no-store",
+            },
+            body,
+        },
+    }));
+    /**
+     * 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.
+     */
+    const admit = Effect.fn("Resource.admit")(function* (authorization, access = "read") {
+        const verified = yield* Effect.result(verifier.verify(authorization));
+        if (Result.isFailure(verified))
+            return yield* refuse(verified.failure, authorization);
+        const principal = verified.success;
+        const missing = access === "write" ? missingScope(principal) : undefined;
+        if (missing !== undefined)
+            return yield* refuse(new InsufficientScope({ scope: missing }), authorization);
+        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.
+     */
+    const authorize = (action) => action.access === "read" || options.writeScope === undefined
+        ? Effect.void
+        : Effect.flatMap(CurrentPrincipal, (principal) => {
+            const missing = missingScope(principal);
+            return missing === undefined
+                ? Effect.void
+                : Effect.fail(new InsufficientScope({ scope: missing }));
+        });
     return {
         verifier,
         discovery,
         challenge,
         headers,
+        admit,
+        authorize,
         resource: options.resource,
         issuer: options.issuer,
+        writeScope: options.writeScope,
     };
 });
-/** Bearer authentication providing `CurrentPrincipal`. */
+/** 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;
-    return yield* resource.verifier.verify(request.headers.authorization);
-}).pipe(Effect.catch((error) => Effect.gen(function* () {
-    const request = yield* HttpServerRequest.HttpServerRequest;
-    // RFC 6750 §3.1: a request that carried no credentials gets no error code.
-    const headers = error instanceof Unauthorized && request.headers.authorization === undefined
-        ? resource.challenge()
-        : resource.headers(error);
-    return yield* Effect.flatMap(encode(error, headers), Effect.fail);
-}))));
+    const admission = yield* resource.admit(request.headers.authorization);
+    if (admission.ok)
+        return admission.principal;
+    return yield* Effect.fail(HttpServerResponse.text(admission.refusal.body, {
+        status: admission.refusal.status,
+        headers: admission.refusal.headers,
+    }));
+}));

package/dist/verify.d.ts

@@ -11,6 +11,13 @@ export interface Principal {
         readonly kind: "key";
         readonly keyId: string;
     };
+    /**
+     * When this credential stops being valid, in epoch milliseconds: an access token's
+     * verified `exp`, so a host never decodes the token again. `undefined` for an API
+     * key, which has no token lifetime and is re-verified against the issuer on every
+     * request; a host that caches a key decision must choose its own bound.
+     */
+    readonly expiresAt: number | undefined;
 }
 export interface Options {
     readonly issuer: string;
@@ -33,6 +40,7 @@ export declare const make: (options: Options) => Effect.Effect<{
             kind: "client";
             clientId: string;
         };
+        expiresAt: number;
     } | {
         subject: string;
         scopes: readonly string[];
@@ -40,6 +48,7 @@ export declare const make: (options: Options) => Effect.Effect<{
             kind: "key";
             keyId: string;
         };
+        expiresAt: undefined;
     }, Forbidden | ProviderUnavailable | RateLimited | Unauthorized, never>;
     verify: (authorization: string | null | undefined) => Effect.Effect<{
         subject: string;
@@ -48,6 +57,7 @@ export declare const make: (options: Options) => Effect.Effect<{
             kind: "client";
             clientId: string;
         };
+        expiresAt: number;
     } | {
         subject: string;
         scopes: readonly string[];
@@ -55,5 +65,6 @@ export declare const make: (options: Options) => Effect.Effect<{
             kind: "key";
             keyId: string;
         };
+        expiresAt: undefined;
     }, Forbidden | ProviderUnavailable | RateLimited | Unauthorized, never>;
 }, ConfigurationError, HttpClient.HttpClient>;

package/dist/verify.js

@@ -18,6 +18,7 @@ const Claims = Schema.Struct({
     sub: Schema.NonEmptyString,
     client_id: Schema.NonEmptyString,
     scope: Schema.String,
+    exp: Schema.Finite,
 });
 const KeyResponse = Schema.Struct({
     keyId: Schema.NonEmptyString,
@@ -111,6 +112,8 @@ 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,
         };
     });
     const verifyKey = Effect.fn("Verifier.apiKey")(function* (key) {
@@ -137,6 +140,9 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
             subject: body.ownerId,
             scopes: body.scopes,
             actor: { kind: "key", keyId: body.keyId },
+            // A key's own expiry is enforced above, on every verification; it is not a
+            // lifetime a caller may hold a decision for.
+            expiresAt: undefined,
         };
     }, Effect.scoped);
     const verifyToken = Effect.fn("Verifier.verifyToken")(function* (token) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/clankerauth-sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Effect-native Clanker Auth access-token and API-key verification, with optional effect-actions integration",
   "license": "MIT",
   "repository": {
@@ -30,14 +30,15 @@
     "jose": "6.2.12"
   },
   "devDependencies": {
-    "@gjermundgaraba/effect-actions": "0.2.0",
+    "@gjermundgaraba/effect-actions": "0.3.0",
+    "@modelcontextprotocol/client": "2.0.0",
     "@types/node": "26.6.2",
     "typescript": "7.0.2",
     "vite": "npm:@voidzero-dev/vite-plus-core@0.3.3",
     "vite-plus": "0.3.3"
   },
   "peerDependencies": {
-    "@gjermundgaraba/effect-actions": "0.2.0"
+    "@gjermundgaraba/effect-actions": "0.3.0"
   },
   "peerDependenciesMeta": {
     "@gjermundgaraba/effect-actions": {