effect(core-auth): add BearerVerifierService and staticBearerVerifierLayer

Introduces an Effect.Service surface for bearer-token verification (tag
arcp/BearerVerifierService, shape BearerVerifierEffect) alongside the
legacy BearerVerifier interface and StaticBearerVerifier class, which
stay byte-compatible for existing consumers (examples/, sdk/cli, runtime).

The default provider rejects every token with TaggedUnauthenticated;
staticBearerVerifierLayer(table) is the Effect-shaped replacement for
new StaticBearerVerifier(table) and composes via Layer.succeed.

Tests cover the happy path, unknown-token rejection, the no-config
default, and the legacy Promise class.

Closes #40

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Nick Ficano

packages/core/src/auth/bearer.ts

@@ -1,10 +1,22 @@
+import { Effect, Layer, Option } from "effect";
+
+import { TaggedUnauthenticated } from "../errors-tagged.js";
 import { UnauthenticatedError } from "../errors.js";
 
-import type { BearerIdentity, BearerVerifier } from "./types.js";
+import type {
+  BearerIdentity,
+  BearerVerifier,
+  BearerVerifierEffect,
+} from "./types.js";
 
 /**
  * In-memory bearer verifier suitable for tests and small deployments. Maps
  * tokens to identities verbatim.
+ *
+ * Legacy Promise-shaped surface — preserved so consumers that instantiate
+ * `new StaticBearerVerifier(new Map([...]))` keep compiling. Effect-native
+ * callers should use {@link staticBearerVerifierLayer} or
+ * {@link BearerVerifierService} instead.
  */
 export class StaticBearerVerifier implements BearerVerifier {
   public constructor(
@@ -22,3 +34,58 @@ export class StaticBearerVerifier implements BearerVerifier {
     return identity;
   }
 }
+
+/**
+ * Effect-native bearer verifier service. The default provider rejects every
+ * token with `TaggedUnauthenticated` — replace it via
+ * {@link staticBearerVerifierLayer} or a user-supplied `Layer.succeed`
+ * (e.g. for JOSE / JWKS-backed verification).
+ *
+ * @example
+ * ```ts
+ * const layer = staticBearerVerifierLayer(
+ *   new Map([["tok-good", { principal: "alice" }]]),
+ * )
+ * const program = Effect.gen(function* () {
+ *   const v = yield* BearerVerifierService
+ *   return yield* v.verify("tok-good")
+ * }).pipe(Effect.provide(layer))
+ * ```
+ */
+export class BearerVerifierService extends Effect.Service<BearerVerifierService>()(
+  "arcp/BearerVerifierService",
+  {
+    succeed: {
+      verify: (
+        _token: string,
+      ): Effect.Effect<BearerIdentity, TaggedUnauthenticated> =>
+        Effect.fail(
+          new TaggedUnauthenticated({
+            message: "no bearer verifier configured",
+          }),
+        ),
+    } satisfies BearerVerifierEffect,
+  },
+) {}
+
+/**
+ * Build a {@link BearerVerifierService} layer backed by a static token →
+ * identity table. Equivalent of `new StaticBearerVerifier(table)` for
+ * Effect-shaped pipelines.
+ */
+export function staticBearerVerifierLayer(
+  table: ReadonlyMap<string, BearerIdentity>,
+): Layer.Layer<BearerVerifierService> {
+  const impl: BearerVerifierEffect = {
+    verify: (token) =>
+      Option.fromNullable(table.get(token)).pipe(
+        Effect.mapError(
+          () => new TaggedUnauthenticated({ message: "Unknown bearer token" }),
+        ),
+      ),
+  };
+  return Layer.succeed(
+    BearerVerifierService,
+    BearerVerifierService.make(impl),
+  );
+}

packages/core/src/auth/index.ts

@@ -1,2 +1,10 @@
-export { StaticBearerVerifier } from "./bearer.js";
-export type { BearerIdentity, BearerVerifier } from "./types.js";
+export {
+  BearerVerifierService,
+  StaticBearerVerifier,
+  staticBearerVerifierLayer,
+} from "./bearer.js";
+export type {
+  BearerIdentity,
+  BearerVerifier,
+  BearerVerifierEffect,
+} from "./types.js";

packages/core/src/auth/types.ts

@@ -1,3 +1,7 @@
+import type { Effect } from "effect";
+
+import type { TaggedUnauthenticated } from "../errors-tagged.js";
+
 /**
  * Outcome of authenticating a bearer credential. The runtime uses the
  * principal to scope identity; entitlements drive subscription authorization.
@@ -11,10 +15,26 @@ export interface BearerIdentity {
 }
 
 /**
- * Bearer-token verifier. Implementers consult their trust store; the protocol
- * leaves issuance up to the deployment per §2 (auth provider implementations
- * are out of scope).
+ * Bearer-token verifier (legacy Promise-shaped). Implementers consult their
+ * trust store; the protocol leaves issuance up to the deployment per §2 (auth
+ * provider implementations are out of scope).
+ *
+ * Retained as a published interface so existing consumers (including
+ * `examples/custom-auth`) continue to compile. Effect-native consumers should
+ * prefer `BearerVerifierEffect` and `BearerVerifierService` from
+ * `./bearer.js`.
  */
 export interface BearerVerifier {
   verify(token: string): Promise<BearerIdentity>;
 }
+
+/**
+ * Effect-shaped verifier surface. The `verify` method returns an Effect that
+ * fails with `TaggedUnauthenticated` when the token is unknown or invalid.
+ * Used as the operational shape of `BearerVerifierService`.
+ */
+export interface BearerVerifierEffect {
+  readonly verify: (
+    token: string,
+  ) => Effect.Effect<BearerIdentity, TaggedUnauthenticated>;
+}

packages/core/test/auth.test.ts

@@ -0,0 +1,67 @@
+import { Effect, Exit } from "effect";
+import { describe, expect, it } from "vitest";
+
+import {
+  type BearerIdentity,
+  BearerVerifierService,
+  StaticBearerVerifier,
+  staticBearerVerifierLayer,
+  TaggedUnauthenticated,
+  UnauthenticatedError,
+} from "@arcp/core";
+
+const ALICE: BearerIdentity = { principal: "alice" };
+
+describe("staticBearerVerifierLayer (Effect surface)", () => {
+  const table = new Map<string, BearerIdentity>([["tok-good", ALICE]]);
+  const layer = staticBearerVerifierLayer(table);
+
+  it("verifies a known token", async () => {
+    const program = Effect.gen(function* () {
+      const v = yield* BearerVerifierService;
+      return yield* v.verify("tok-good");
+    }).pipe(Effect.provide(layer));
+    const identity = await Effect.runPromise(program);
+    expect(identity).toEqual(ALICE);
+  });
+
+  it("fails with TaggedUnauthenticated for unknown tokens", async () => {
+    const program = Effect.gen(function* () {
+      const v = yield* BearerVerifierService;
+      return yield* v.verify("tok-bad");
+    }).pipe(Effect.provide(layer));
+    const exit = await Effect.runPromiseExit(program);
+    expect(Exit.isFailure(exit)).toBe(true);
+    if (Exit.isFailure(exit)) {
+      const err = exit.cause._tag === "Fail" ? exit.cause.error : undefined;
+      expect(err).toBeInstanceOf(TaggedUnauthenticated);
+    }
+  });
+});
+
+describe("BearerVerifierService default provider", () => {
+  it("rejects every token until a layer is supplied", async () => {
+    const program = Effect.gen(function* () {
+      const v = yield* BearerVerifierService;
+      return yield* v.verify("anything");
+    }).pipe(Effect.provide(BearerVerifierService.Default));
+    const exit = await Effect.runPromiseExit(program);
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+});
+
+describe("StaticBearerVerifier (legacy Promise surface)", () => {
+  it("resolves known tokens to the identity", async () => {
+    const v = new StaticBearerVerifier(
+      new Map([["tok-good", ALICE]]),
+    );
+    await expect(v.verify("tok-good")).resolves.toEqual(ALICE);
+  });
+
+  it("throws UnauthenticatedError for unknown tokens", async () => {
+    const v = new StaticBearerVerifier(new Map());
+    await expect(v.verify("nope")).rejects.toBeInstanceOf(
+      UnauthenticatedError,
+    );
+  });
+});