@gjermundgaraba/clankerauth-sdk 0.12.0 → 0.13.0

package/dist/resource.d.ts

@@ -1,21 +1,22 @@
-import { Context, Effect, Schema } from "effect";
-import type * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Context, Effect, Layer, Redacted } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
-import { ConfigurationError, InsufficientScope, ProviderUnavailable, Unauthorized } from "./errors.ts";
+import { HttpRouter } from "effect/http";
+import type { HttpClient } from "effect/http";
+import type { HttpApiSecurity } from "effect/http-api";
+import type { ConfigurationError } from "./errors.ts";
+import { ProviderUnavailable } from "./errors.ts";
+import { CurrentPrincipal, Whoami } from "./session.ts";
+import type { Caller } from "./session.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 {
-}
-/** What this resource's credentials must carry. */
-export interface Scopes {
-    /** Required of every credential, so verification alone admits a read. */
-    readonly read: string;
-    /**
-     * Additionally required by an `access: "write"` action and by `admit(..., "write")`.
-     * Omit for a single-scope application, where verification is the whole policy.
-     */
-    readonly write?: string;
-}
+/**
+ * Verify a request's bearer token with `verifier`, failing as an effect-actions surface
+ * refuses: what a verifier of your own, given to `Authentication.layer`, yields before its
+ * own checks. A declared resource's `provider` does this; reach for it only with a verifier
+ * of your own, whose descriptor declares `ProviderUnavailable` too, or another error the
+ * verifier maps it to.
+ */
+export declare const authenticate: (verifier: Verifier.Verifier, token: Redacted.Redacted<string>) => Effect.Effect<Verifier.Principal, Action.Refusal | ProviderUnavailable>;
 export interface Options {
     readonly issuer: string;
     /**
@@ -23,13 +24,18 @@ export interface Options {
      * root, so any path here is discarded: one identifier covers `/api`, `/mcp` and sockets.
      */
     readonly publicUrl: URL;
-    readonly scopes: Scopes;
     /** `false` refuses API keys without reading the issuer's key list; only OAuth access tokens are accepted. */
     readonly apiKeys?: boolean;
+    /**
+     * `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.
+     */
+    readonly discovery?: boolean;
 }
 /**
- * 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.
+ * A refusal a caller outside the router can send as-is: the status, headers and JSON body
+ * `authentication` answers the same refusal with on a route.
  */
 export interface Refusal {
     readonly status: number;
@@ -44,39 +50,112 @@ export type Admission = {
     readonly ok: false;
     readonly refusal: Refusal;
 };
-/** One resource: its verifier, discovery, scope policy and refusals. Acquire once per application. */
-export declare const make: (options: Options) => Effect.Effect<{
-    verifier: Verifier.Verifier;
-    discovery: {
-        layer: import("effect/Layer").Layer<never, never, import("effect/http/HttpRouter").HttpRouter>;
-        metadataUrl: string;
-        challenge: (challenge?: Authentication.BearerChallengeOptions) => string;
-    };
-    admit: (authorization: string | null | undefined, access: Action.Access) => Effect.Effect<Admission, never, never>;
-    watch: (authorization: string | null | undefined, access: Action.Access) => Effect.Effect<never, InsufficientScope | ProviderUnavailable | Unauthorized, never>;
-    authorize: (action: Action.Any) => Effect.Effect<void, InsufficientScope, CurrentPrincipal>;
-    session: import("@gjermundgaraba/effect-actions/ActionGroup").Implementation<import("@gjermundgaraba/effect-actions/ActionGroup").Group<"session", readonly [Action.Action<"whoami", Schema.$Record<Schema.String, Schema.Never>, Schema.Struct<{
-        readonly subject: Schema.NonEmptyString;
-        readonly issuer: Schema.NonEmptyString;
-        readonly scopes: Schema.$Array<Schema.String>;
-    }>, readonly [], "read", false>], never>, {
-        whoami: () => Effect.Effect<{
-            subject: string;
-            issuer: string;
-            scopes: readonly string[];
-        }, never, CurrentPrincipal>;
-    }, never, never>;
-    resource: string;
-    issuer: string;
-}, ConfigurationError, import("effect/http/HttpClient").HttpClient>;
-export type Resource = Effect.Success<ReturnType<typeof make>>;
-/** Bearer authentication providing `CurrentPrincipal`, on the same admission `admit` renders. */
-export declare const middleware: (resource: Resource) => import("effect/http/HttpRouter").Middleware<{
-    provides: CurrentPrincipal;
-    handles: never;
-    error: never;
-    requires: never;
-    layerError: never;
-    layerRequires: never;
-}>;
+/**
+ * What a declared resource's `layer` builds: its verifier and its refusals. An
+ * interface, as `Declared` is, so a consumer's emitted declarations name it. `Scope` is the
+ * resource's scopes, as `make` infers them: a scope `admit` and `watch` check is one of them.
+ */
+export interface Built<Scope extends string = string> {
+    /** The resource identifier: the public origin root, which a token's audience names. */
+    readonly resource: string;
+    readonly issuer: string;
+    /** What `authentication` publishes and names in every challenge; none with `discovery: false`. */
+    readonly protectedResource: Authentication.ProtectedResource | undefined;
+    readonly verifier: Verifier.Verifier;
+    /**
+     * What an Authorization header value amounts to, for a caller outside the router: any
+     * verified caller, or with `scope`, one that also holds it.
+     */
+    readonly admit: (authorization: string | null | undefined, scope?: Scope) => Effect.Effect<Admission>;
+    /** Fails, with the refusal `admit` would now answer, once the credential it admitted stops being valid. */
+    readonly watch: (authorization: string | null | undefined, scope?: Scope) => Effect.Effect<never, Action.Refusal | ProviderUnavailable>;
+}
+/**
+ * The service identity of the resource whose descriptor is named `Name`, so two resources are
+ * two services: each surface reads its own, whatever layer graph builds them.
+ */
+export interface Resource<Name extends string> {
+    readonly "~@clankerauth/Resource": Name;
+}
+/** What `make` requires a descriptor to declare: the issuer being unreachable. */
+type Unavailable = readonly [typeof ProviderUnavailable];
+/**
+ * A descriptor of `CurrentPrincipal` by bearer token, declaring `ProviderUnavailable`, as a
+ * binding and an MCP endpoint name it, beside the contracts:
+ * `Authentication.make("notes.Login", CurrentPrincipal, { error: ProviderUnavailable })`.
+ * `E` is what it declares, that one error unless it declares more.
+ */
+export type Login<Name extends string = string, E extends Action.Errors = Unavailable> = Authentication.Descriptor<CurrentPrincipal, Caller, HttpApiSecurity.Http, Name, E>;
+/**
+ * `unknown` when every alternative of `E` declares `ProviderUnavailable`, by what its schemas
+ * decode (one of them, or a `Schema.Union` holding it), and what names the omission otherwise:
+ * a descriptor that may declare it, such as `error: cond ? ProviderUnavailable : undefined`,
+ * does not.
+ */
+type DeclaresUnavailable<E extends Action.Errors> = [
+    E extends unknown ? (ProviderUnavailable extends E[number]["Type"] ? never : E) : never
+] extends [never] ? unknown : {
+    readonly "Resource.make takes a descriptor declaring error: ProviderUnavailable": never;
+};
+/**
+ * What a resource declares beside its descriptor, the same in every deployment: the
+ * application's scopes, and the one every credential must carry.
+ */
+export interface Declaration<Scope extends string = string> {
+    /**
+     * Every scope the resource has: published in discovery, and held by `local`'s principal.
+     * effect-actions refuses one that is no OAuth scope token when the provider builds that
+     * discovery; with `discovery: false`, nothing checks them.
+     */
+    readonly scopes: readonly Scope[];
+    /**
+     * The scope every credential must carry, one of `scopes`: verification requires it, every
+     * 401 names it, and a first login requests it. Any other scope is the application's to
+     * require, with `requires`.
+     */
+    readonly required: NoInfer<Scope>;
+}
+/**
+ * A declared resource, as `make` gives it. `E` is what its descriptor declares,
+ * `ProviderUnavailable` alone unless it declares more. `Scope` is its scopes, as `make`
+ * infers them: `requires`, `admitted`, `admit` and `watch` take only one of them, so a scope
+ * it does not declare is a type error. Where an exported declaration must be written out,
+ * annotate with all three:
+ * `Resource.Declared<"notes.Login", readonly [typeof ProviderUnavailable], "notes:read" | "notes:write">`.
+ */
+export interface Declared<Name extends string, E extends Action.Errors = Unavailable, Scope extends string = string> {
+    /** The descriptor the resource verifies, as given to `make`. */
+    readonly authentication: Login<Name, E>;
+    /** The built resource: `admit` and `watch` for a caller outside the router, `verifier`. */
+    readonly service: Context.Service<Resource<Name>, Built<Scope>>;
+    /** The resource, built once per layer graph: provide it beside the surfaces it guards. */
+    readonly layer: (options: Options) => Layer.Layer<Resource<Name>, ConfigurationError, HttpClient.HttpClient>;
+    /**
+     * The descriptor's provider: its verifier, reading the resource, which also publishes the
+     * resource's discovery. Provide it to every layer serving the resource's protected actions.
+     */
+    readonly provider: Layer.Layer<Authentication.Provider<CurrentPrincipal, Name>, never, Resource<Name> | HttpRouter.HttpRouter>;
+    /** Refuses a caller without `scope`, for an authorizer the application writes. */
+    readonly requires: (scope: Scope) => Effect.Effect<void, Action.Forbidden, CurrentPrincipal>;
+    /** The host's own routes, admitted as the resource's actions are, holding `scope` if given. */
+    readonly admitted: (scope?: Scope) => Authentication.Protection<CurrentPrincipal, Name>;
+    /** The process itself as a principal, for a trusted local surface. */
+    readonly local: (subject: string) => Caller;
+    /** `Whoami`, answered from the verified credential. */
+    readonly session: Action.Implementation<typeof Whoami, {
+        readonly whoami: CurrentPrincipal;
+    }, never, Resource<Name>>;
+}
+/**
+ * Declare an application's resource, at module level, by the descriptor its bindings and
+ * MCP endpoints name, its scopes and the one every credential carries:
+ * `const Notes = Resource.make(Login, { scopes: ["notes:read", "notes:write"], required: "notes:read" })`.
+ * The descriptor's name names its service, so two resources of one process are two services.
+ * What varies by deployment comes later, where the application starts, as
+ * `Notes.layer(options)`, provided once beside the surfaces. Which scope an action needs
+ * beyond `required` is the application's rule, written with `requires`. The descriptor
+ * declares `ProviderUnavailable`, which its verifier fails with when the issuer cannot be
+ * reached; one that does not is a type error here.
+ */
+export declare const make: <const Name extends string, E extends Action.Errors, const Scope extends string>(authentication: Login<Name, E> & DeclaresUnavailable<E>, declaration: Declaration<Scope>) => Declared<Name, E, Scope>;
 export {};

package/dist/resource.js

@@ -1,51 +1,66 @@
-import { Clock, Context, Duration, Effect, Result, Schema, SchemaAST } from "effect";
+import { Clock, Context, Duration, Effect, Layer, Option, Redacted, Result } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
-import { HttpServerRequest, HttpServerResponse } from "effect/http";
-import { authenticationErrors, ConfigurationError, InsufficientScope, ProviderUnavailable, Unauthorized, } from "./errors.js";
+import { HttpRouter, HttpServerResponse } from "effect/http";
+import { InsufficientScope, ProviderUnavailable, Unauthorized } from "./errors.js";
 import { keyListRefresh } from "./refresh.js";
-import { Session } from "./session.js";
+import { CurrentPrincipal, Whoami } from "./session.js";
 import * as Verifier from "./verify.js";
-const encoders = new Map(authenticationErrors.map((schema) => [
-    schema,
-    {
-        status: SchemaAST.resolveAt("httpApiStatus")(schema.ast) ?? 500,
-        encode: Schema.encodeUnknownEffect(Schema.toCodecJson(schema)),
-    },
-]));
-/** One refusal as its own status and JSON body. An undeclared error is a defect. */
-const describe = (error) => {
-    const schema = authenticationErrors.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),
-    }));
+/**
+ * What a caller lacking `scope` is refused with, wherever the lack is found. Only an OAuth
+ * client can step up, so only its `Forbidden` names the scope: an API key or the process
+ * cannot re-authorize.
+ */
+const forbidden = (scope, actor) => {
+    const message = `Requires ${scope}.`;
+    return actor.kind === "client"
+        ? new Action.Forbidden({ message, scopes: [scope] })
+        : new Action.Forbidden({ message });
+};
+/**
+ * The one scope check, which `requires`, `admitted`, `admit` and `watch` share: what
+ * `principal` is refused for lacking `scope`, if one is asked for and it lacks it.
+ */
+const lacking = (principal, scope) => scope === undefined || principal.scopes.includes(scope)
+    ? undefined
+    : forbidden(scope, principal.actor);
+/**
+ * A verification failure as every effect-actions surface declares it: the built-in
+ * `Unauthenticated` and `Forbidden`, which every client decodes. The issuer being
+ * unreachable stays the SDK's own `ProviderUnavailable`, which the descriptor declares.
+ */
+const refusalOf = (error) => {
+    if (error instanceof Unauthorized)
+        return new Action.Unauthenticated({ message: error.message });
+    if (error instanceof InsufficientScope)
+        return forbidden(error.scope, error.actor);
+    return error;
 };
-export class CurrentPrincipal extends Context.Service()("@clankerauth/CurrentPrincipal") {
-}
-/** One resource: its verifier, discovery, scope policy and refusals. Acquire once per application. */
-export const make = Effect.fn("Resource.make")(function* (options) {
+/**
+ * Verify a request's bearer token with `verifier`, failing as an effect-actions surface
+ * refuses: what a verifier of your own, given to `Authentication.layer`, yields before its
+ * own checks. A declared resource's `provider` does this; reach for it only with a verifier
+ * of your own, whose descriptor declares `ProviderUnavailable` too, or another error the
+ * verifier maps it to.
+ */
+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;
-    const scopesSupported = options.scopes.write === undefined
-        ? [options.scopes.read]
-        : [options.scopes.read, options.scopes.write];
-    const discovery = yield* Effect.try({
-        try: () => Authentication.protectedResource({
-            resource: identifier,
-            authorizationServers: [options.issuer],
-            scopesSupported,
-        }),
-        catch: () => new ConfigurationError({ message: "Invalid resource metadata configuration" }),
-    });
+    // effect-actions checks every scope here is an OAuth scope token, when the provider builds.
+    const metadata = {
+        resource: identifier,
+        authorizationServers: [options.issuer],
+        scopesSupported: scopes,
+        scopesRequired: [required],
+    };
+    const protectedResource = options.discovery === false ? undefined : metadata;
     const unbounded = yield* Verifier.make({
         issuer: options.issuer,
         resource: identifier,
-        requiredScopes: [options.scopes.read],
+        requiredScopes: [required],
         apiKeys: options.apiKeys,
     });
     // A request must not wait on an issuer that does not answer: the transport is
@@ -55,118 +70,147 @@ export const make = Effect.fn("Resource.make")(function* (options) {
         duration: "5 seconds",
         orElse: () => Effect.fail(new ProviderUnavailable({ operation: "verify.timeout" })),
     });
-    const verify = (authorization) => deadline(unbounded.verify(authorization));
     const verifier = {
-        verify,
         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
-     * challenge naming only the missing scope.
+     * The principal an Authorization header value proves, holding `scope` if one is asked
+     * for, or what a route refuses the same request with: `admit` renders it, `watch` fails
+     * with it.
      */
-    const refusalHeader = (error, credential) => {
-        if (error instanceof InsufficientScope)
-            return ["www-authenticate", challengeValue("insufficient_scope", error.scope)];
-        // RFC 6750 §3.1: a request that carried no credentials gets no error code.
-        if (error instanceof Unauthorized)
-            return ["www-authenticate", credential ? challengeValue("invalid_token") : challengeValue()];
-        return undefined;
-    };
-    const asRecord = (header) => header === undefined ? {} : { [header[0]]: header[1] };
-    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,
-        },
-    }));
-    /** The write scope, if one is configured and this principal lacks it. */
-    const missingScope = (principal) => options.scopes.write !== undefined && !principal.scopes.includes(options.scopes.write)
-        ? options.scopes.write
-        : undefined;
-    /** The principal an Authorization header value has for `access`, or its refusal. */
-    const principalFor = Effect.fn("Resource.principal")(function* (authorization, access) {
-        const principal = yield* verify(authorization);
-        const missing = access === "write" ? missingScope(principal) : undefined;
-        if (missing !== undefined)
-            return yield* new InsufficientScope({ scope: missing });
-        return principal;
+    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);
+        const refusal = lacking(principal, scope);
+        return refusal === undefined ? principal : yield* refusal;
     });
     /**
      * Verify one Authorization header value outside an Effect router: a Node `upgrade`
-     * handler, a socket, a per-request endpoint. `access` is the same declaration an
-     * action carries, so `"write"` demands the write scope before a socket is established.
+     * handler, a socket, a per-request endpoint. With `scope`, the credential must also hold
+     * it, so a socket that writes demands its scope before it is established. It is
+     * `admitted`'s check, given the header rather than the request.
      */
-    const admit = Effect.fn("Resource.admit")(function* (authorization, access) {
-        const verified = yield* Effect.result(principalFor(authorization, access));
-        if (Result.isFailure(verified))
-            return yield* refuse(verified.failure, authorization);
-        return { ok: true, principal: verified.success };
+    const admit = Effect.fn("Resource.admit")(function* (authorization, scope) {
+        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,
+            authorization,
+        }));
+        return {
+            ok: false,
+            refusal: {
+                status: web.status,
+                headers: Object.fromEntries(web.headers),
+                body: yield* Effect.promise(() => web.text()),
+            },
+        };
     });
     /**
-     * Hold what `admit` let in, such as a socket, to the same header value and `access`:
-     * fails with the first refusal, once a token expires or a key is revoked, expires or
-     * loses the scope. Never succeeds; race it against the connection.
+     * Hold what `admit` let in, such as a socket, to the same header value and `scope`: fails
+     * with the refusal `admit` would now answer, once a token expires or a key is revoked,
+     * expires or loses the scope. Never succeeds; race it against the connection.
      */
-    const watch = (authorization, access) => Effect.forever(Effect.gen(function* () {
-        const principal = yield* principalFor(authorization, access);
+    const watch = (authorization, scope) => Effect.forever(Effect.gen(function* () {
+        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.
+        // 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* new Unauthorized({ message: "Authentication required" });
+        return yield* refusalOf(new Unauthorized());
     }));
-    /**
-     * The effect-actions pre-handler hook, bound once per surface. 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.scopes.write === undefined
-        ? Effect.void
-        : Effect.flatMap(CurrentPrincipal, (principal) => {
-            const missing = missingScope(principal);
-            return missing === undefined
-                ? Effect.void
-                : Effect.fail(new InsufficientScope({ scope: missing }));
-        });
-    /** The `session` group of `@gjermundgaraba/clankerauth-sdk/session`, already answered. */
-    const session = Session.implement({
-        whoami: () => Effect.map(CurrentPrincipal, ({ subject, scopes }) => ({
-            subject,
-            issuer: options.issuer,
-            scopes,
-        })),
-    });
     return {
+        /** The resource identifier: the public origin root, which a token's audience names. */
+        resource: identifier,
+        issuer: options.issuer,
+        /** What `authentication` publishes and names in every challenge; none with `discovery: false`. */
+        protectedResource,
         verifier,
-        discovery,
         admit,
         watch,
-        authorize,
-        session,
-        resource: identifier,
-        issuer: options.issuer,
     };
 });
-/** 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;
-    // Read level: an action's own `access` is what the authorization hook then enforces.
-    const admission = yield* resource.admit(request.headers.authorization, "read");
-    if (admission.ok)
-        return admission.principal;
-    return yield* Effect.fail(HttpServerResponse.text(admission.refusal.body, {
-        status: admission.refusal.status,
-        headers: admission.refusal.headers,
-    }));
-}));
+/**
+ * Declare an application's resource, at module level, by the descriptor its bindings and
+ * MCP endpoints name, its scopes and the one every credential carries:
+ * `const Notes = Resource.make(Login, { scopes: ["notes:read", "notes:write"], required: "notes:read" })`.
+ * The descriptor's name names its service, so two resources of one process are two services.
+ * What varies by deployment comes later, where the application starts, as
+ * `Notes.layer(options)`, provided once beside the surfaces. Which scope an action needs
+ * beyond `required` is the application's rule, written with `requires`. The descriptor
+ * declares `ProviderUnavailable`, which its verifier fails with when the issuer cannot be
+ * reached; one that does not is a type error here.
+ */
+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.map(service, ({ verifier }) => (token) => 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") })`.
+     * The `Forbidden` names the scope for an OAuth client, which steps up to it; an API key or
+     * the process cannot, so theirs names none.
+     */
+    const requires = (scope) => Effect.flatMap(CurrentPrincipal, (principal) => {
+        const refusal = lacking(principal, scope);
+        return refusal === undefined ? Effect.void : Effect.fail(refusal);
+    });
+    /**
+     * The host's own routes behind the resource, provided around them:
+     * `HttpRouter.add("GET", "/frame", frame).pipe(Layer.provide(Notes.admitted().layer))`.
+     * effect-actions' `Authentication.protect` authenticates them with the descriptor's provider,
+     * as it does an action's route, and answers them as one; `scope`, if given, is checked
+     * inside it with `requires`. An admitted route reads its caller from `CurrentPrincipal`.
+     */
+    const admitted = (scope) => scope === undefined
+        ? Authentication.protect(authentication)
+        : HttpRouter.middleware((route) => Effect.andThen(requires(scope), route)).combine(Authentication.protect(authentication));
+    /**
+     * The process itself as the caller of a trusted local surface, such as stdio MCP or a local
+     * command, where no credential exists to verify: every scope the resource declares, no
+     * expiry. The application's authorizer runs against it as against a verified caller.
+     * `Effect.provideService(CurrentPrincipal, Notes.local("owner"))`.
+     */
+    const local = (subject) => ({
+        subject,
+        scopes: [...scopes],
+        actor: { kind: "local" },
+        expiresAt: undefined,
+    });
+    /**
+     * `whoami` of `@gjermundgaraba/clankerauth-sdk/session`, already answered. The credential
+     * is a transport concern: a process surface has none, so serve it over HTTP alone,
+     * `ActionHttp.layer(Http, [app, Notes.session])`, and leave it out of MCP.
+     */
+    const session = Action.implement(Whoami, Effect.map(service, ({ issuer }) => () => Effect.map(CurrentPrincipal, (principal) => ({
+        subject: principal.subject,
+        issuer,
+        scopes: principal.scopes,
+    }))), { authorize: Action.allowAll });
+    return {
+        authentication,
+        service,
+        layer,
+        provider,
+        requires,
+        admitted,
+        local,
+        session,
+    };
+};

package/dist/session.d.ts

@@ -1,11 +1,35 @@
 /**
  * The identity a browser page needs, without any verification code. This entry point is
- * browser-safe: it declares the `session` contract and builds the issuer's sign-out URL,
- * so a page imports it directly and a server answers it with `resource.session`.
+ * browser-safe: it declares the identity a protected contract states, the `whoami` contract
+ * and the issuer's sign-out URL, so contracts, bindings and pages import it directly, and a
+ * server answers `Whoami` with its resource's `session`.
  */
-import { Schema } from "effect";
+import { Context, Schema } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
-import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
+import type { Principal as Verified } from "./verify.ts";
+/**
+ * Who calls, as `CurrentPrincipal` carries it: a verified credential's principal, the
+ * `Verifier`'s, or on a trusted local surface the process itself, `actor: { kind: "local" }`,
+ * which no verifier produces, with no `expiresAt`. Declared here, so a package declaring a
+ * descriptor of `CurrentPrincipal` from this entry alone names it in its emitted declarations.
+ */
+export interface Caller extends Omit<Verified, "actor"> {
+    readonly actor: Verified["actor"]
+    /** The process itself, on a trusted local surface: no credential was verified. */
+     | {
+        readonly kind: "local";
+    };
+}
+declare const CurrentPrincipal_base: Context.ServiceClass<CurrentPrincipal, "@clankerauth/CurrentPrincipal", Caller>;
+/**
+ * The caller: what a protected contract states, `caller: CurrentPrincipal`, and what an
+ * authentication descriptor proves,
+ * `Authentication.make("notes.Login", CurrentPrincipal, { error: ProviderUnavailable })`.
+ * Remotely, the resource's provider gives it per request, from the verified credential; on
+ * a trusted local surface, the host gives it the process, `Notes.local(subject)`.
+ */
+export declare class CurrentPrincipal extends CurrentPrincipal_base {
+}
 /** The verified credential behind a request, as the resource server read it. */
 export declare const Principal: Schema.Struct<{
     readonly subject: Schema.NonEmptyString;
@@ -14,16 +38,18 @@ 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])`.
+ * The credential is a transport concern: a process surface has none, so bind `Whoami` to
+ * HTTP alone, `ActionHttp.layer(Http, [app, Notes.session])`, and leave `Notes.session` out
+ * of MCP.
  */
-export declare const Session: ActionGroup.Group<"session", readonly [Action.Action<"whoami", Schema.$Record<Schema.String, Schema.Never>, Schema.Struct<{
+export declare const Whoami: Action.Action<"whoami", Schema.$Record<Schema.String, Schema.Never>, Schema.Struct<{
     readonly subject: Schema.NonEmptyString;
     readonly issuer: Schema.NonEmptyString;
     readonly scopes: Schema.$Array<Schema.String>;
-}>, readonly [], "read", false>], never>;
+}>, readonly never[], true, typeof CurrentPrincipal>;
 /**
  * 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 declare const signOutUrl: (issuer: string, returnTo: string) => string;
+export {};