@xandreed/plugin-models 0.13.0 → 0.15.0

package/README.md

@@ -1,5 +1,5 @@
 # @xandreed/plugin-models
 
-Efferent composable agent framework, 0.13.0. Node 24 or Bun.
+Efferent composable agent framework, 0.15.0. Node 24.5 or Bun.
 
 Documentation: https://github.com/xandreeddev/efferent

package/dist/auth/anthropicOAuth.d.ts

@@ -1,5 +1,6 @@
-import { Effect, Option } from "effect";
-import { AuthError } from "@xandreed/core";
+import { Effect, Option, Redacted } from "effect";
+import { AuthError } from "../ports/auth-store.port.js";
+import type { ModelsFetch } from "../ports/models-transport.port.js";
 /**
  * Anthropic OAuth (Claude Pro/Max subscription) — the full protocol:
  * authorization-code + PKCE (begin/exchange) and refresh. Constants match
@@ -15,20 +16,45 @@ export declare const ANTHROPIC_REDIRECT_URI = "http://localhost:53692/callback";
 export declare const ANTHROPIC_OAUTH_BETA = "claude-code-20250219,oauth-2025-04-20";
 /** Anthropic rejects OAuth tokens unless the first system block is exactly this. */
 export declare const CLAUDE_CODE_SYSTEM = "You are Claude Code, Anthropic's official CLI for Claude.";
+/**
+ * The tokens a sign-in or a refresh grants, `Redacted` from the token response on.
+ *
+ * @public
+ */
 export interface RefreshedTokens {
-    readonly access: string;
-    readonly refresh: string;
+    readonly access: Redacted.Redacted<string>;
+    readonly refresh: Redacted.Redacted<string>;
     /** Absolute expiry, epoch ms (with a 5-minute early-refresh skew baked in). */
     readonly expires: number;
 }
-/** Refresh an expired (or near-expiry) access token. */
-export declare const refreshAnthropicToken: (refreshToken: string) => Effect.Effect<RefreshedTokens, AuthError>;
+/**
+ * How one token request is made, for both subscription providers. `fetch`
+ * replaces the global fetch (a test stub, or a `ModelsTransport`'s fetch, so
+ * the request goes through the models plugin's proxy); `now` is
+ * the time the new token's expiry is counted from, in epoch ms (default: the
+ * Effect `Clock`).
+ *
+ * @public
+ */
+export interface TokenRequestOptions {
+    readonly fetch?: ModelsFetch;
+    readonly now?: number;
+}
+/** The time a token's expiry is counted from: the caller's, or the Effect Clock's. */
+export declare const tokenTime: (options: TokenRequestOptions) => Effect.Effect<number>;
+/**
+ * Refresh an expired (or near-expiry) access token; the refresh token is unwrapped only into the request body.
+ *
+ * @public
+ */
+export declare const refreshAnthropicToken: (refreshToken: Redacted.Redacted<string>, options?: TokenRequestOptions) => Effect.Effect<RefreshedTokens, AuthError>;
 export interface Pkce {
     readonly verifier: string;
     readonly challenge: string;
 }
-/** Generate a PKCE verifier + S256 challenge (Web Crypto; Bun-global). */
+/** Generate a PKCE verifier (32 bytes of the platform's cryptographic generator) + its S256 challenge. */
 export declare const generatePkce: Effect.Effect<Pkce>;
+/** @public */
 export interface OAuthBegin {
     /** The PKCE verifier — ALSO the `state`; the driver must verify the
      *  redirect echoes it (CSRF) before exchanging. */
@@ -37,14 +63,22 @@ export interface OAuthBegin {
     readonly callbackPort: number;
     readonly callbackPath: string;
 }
-/** Start an authorization: PKCE material + the browser URL. */
+/**
+ * Start an authorization: PKCE material + the browser URL.
+ *
+ * @public
+ */
 export declare const beginAnthropicOAuth: Effect.Effect<OAuthBegin>;
-/** Exchange the authorization code for tokens. */
-export declare const exchangeAnthropicCode: (code: string, verifier: string) => Effect.Effect<RefreshedTokens, AuthError>;
+/** Exchange the authorization code for tokens, `Redacted` (ready for `AuthStore.set`). */
+export declare const exchangeAnthropicCode: (code: string, verifier: string, options?: TokenRequestOptions) => Effect.Effect<RefreshedTokens, AuthError>;
+/** @public */
 export interface AuthRedirect {
     readonly code: Option.Option<string>;
     readonly state: Option.Option<string>;
 }
 /** Pull `code`/`state` out of a pasted redirect URL, `code#state` pair,
- *  bare query string, or raw code. Total — garbage is `{none, none}`. */
+ *  bare query string, or raw code. Total — garbage is `{none, none}`.
+ *
+ * @public
+ */
 export declare const parseAuthorizationInput: (input: string) => AuthRedirect;

package/dist/auth/anthropicOAuth.js

@@ -1,5 +1,8 @@
-import { Effect, Option } from "effect";
-import { AuthError } from "@xandreed/core";
+import { createHash } from "node:crypto";
+import { Clock, Effect, Option, Redacted } from "effect";
+import { AuthError } from "../ports/auth-store.port.js";
+import { redactCredentials } from "../transport/http-proxy.entity.functions.js";
+import { decodeTokenResponse, tokenRefusalText } from "./token-response.entity.functions.js";
 export const ANTHROPIC_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
 const AUTHORIZE_URL = "https://claude.ai/oauth/authorize", TOKEN_URL = "https://platform.claude.com/v1/oauth/token";
 export const ANTHROPIC_CALLBACK_PORT = 53692, ANTHROPIC_CALLBACK_PATH = "/callback", ANTHROPIC_REDIRECT_URI = `http://localhost:${ANTHROPIC_CALLBACK_PORT}${ANTHROPIC_CALLBACK_PATH}`;
@@ -8,11 +11,13 @@ export const ANTHROPIC_OAUTH_BETA = "claude-code-20250219,oauth-2025-04-20", CLA
 const oauthError = (stage) => (detail) => new AuthError({
   provider: "anthropic",
   message: `OAuth ${stage} failed: ${detail}`
-}), postToken = (body, stage) => {
+});
+export const tokenTime = (options) => options.now === void 0 ? Clock.currentTimeMillis : Effect.succeed(options.now);
+const postToken = (body, stage, options, previous) => {
   const fail = oauthError(stage);
   return Effect.tryPromise({
     try: async () => {
-      const res = await fetch(TOKEN_URL, {
+      const res = await (options.fetch ?? fetch)(TOKEN_URL, {
         method: "POST",
         headers: { "Content-Type": "application/json", Accept: "application/json" },
         body: JSON.stringify(body),
@@ -20,27 +25,22 @@ const oauthError = (stage) => (detail) => new AuthError({
       });
       return { ok: res.ok, status: res.status, text: await res.text() };
     },
-    catch: (e) => fail(String(e))
-  }).pipe(Effect.filterOrFail((res) => res.ok, (res) => fail(`status ${res.status}: ${res.text.slice(0, 200)}`)), Effect.flatMap((res) => Effect.try({
-    try: () => JSON.parse(res.text),
-    catch: () => fail("the token response was not JSON")
-  })), Effect.map((data) => ({
-    access: data.access_token,
-    refresh: data.refresh_token,
-    expires: Date.now() + data.expires_in * 1000 - 300000
-  })));
+    catch: (e) => fail(redactCredentials(String(e)))
+  }).pipe(Effect.filterOrFail((res) => res.ok, (res) => fail(tokenRefusalText(res.status, res.text, body))), Effect.flatMap((res) => decodeTokenResponse(res.text, previous).pipe(Effect.mapError(fail))), Effect.flatMap((issued) => Effect.map(tokenTime(options), (now) => ({
+    access: issued.access,
+    refresh: issued.refresh,
+    expires: now + issued.lifetimeMs - 300000
+  }))));
 };
-export const refreshAnthropicToken = (refreshToken) => postToken({
+export const refreshAnthropicToken = (refreshToken, options = {}) => postToken({
   grant_type: "refresh_token",
   client_id: ANTHROPIC_CLIENT_ID,
-  refresh_token: refreshToken
-}, "token refresh");
+  refresh_token: Redacted.value(refreshToken)
+}, "token refresh", options, Option.some(refreshToken));
 const base64url = (bytes) => btoa(Array.from(bytes, (b) => String.fromCharCode(b)).join("")).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
-export const generatePkce = Effect.promise(async () => {
-  const verifierBytes = new Uint8Array(32);
-  crypto.getRandomValues(verifierBytes);
-  const verifier = base64url(verifierBytes), digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
-  return { verifier, challenge: base64url(new Uint8Array(digest)) };
+export const generatePkce = Effect.sync(() => {
+  const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
+  return { verifier, challenge: base64url(new Uint8Array(createHash("sha256").update(verifier).digest())) };
 }), beginAnthropicOAuth = Effect.map(generatePkce, (pkce) => ({
   verifier: pkce.verifier,
   authorizeUrl: `${AUTHORIZE_URL}?${new URLSearchParams({
@@ -55,14 +55,14 @@ export const generatePkce = Effect.promise(async () => {
   }).toString()}`,
   callbackPort: ANTHROPIC_CALLBACK_PORT,
   callbackPath: ANTHROPIC_CALLBACK_PATH
-})), exchangeAnthropicCode = (code, verifier) => postToken({
+})), exchangeAnthropicCode = (code, verifier, options = {}) => postToken({
   grant_type: "authorization_code",
   client_id: ANTHROPIC_CLIENT_ID,
   code,
   redirect_uri: ANTHROPIC_REDIRECT_URI,
   code_verifier: verifier,
   state: verifier
-}, "code exchange");
+}, "code exchange", options, Option.none());
 const fromNullableTrimmed = (value) => Option.filter(Option.fromNullishOr(value), (v) => v.trim().length > 0);
 export const parseAuthorizationInput = (input) => {
   const value = input.trim();

package/dist/auth/auth-store.conformance.d.ts

@@ -0,0 +1,63 @@
+import { Effect } from "effect";
+import type { Context, Scope } from "effect";
+import { ProviderId } from "@xandreed/core";
+import type { ConformanceCheck } from "@xandreed/core/conformance";
+import type { AuthStore } from "../ports/auth-store.port.js";
+type Store = Context.Service.Shape<typeof AuthStore>;
+/**
+ * The token endpoint a store refreshes through, as the kit sees it: the
+ * test builds the store over a fetch (or an equivalent) that it controls,
+ * and hands the kit this view of it.
+ *
+ * @public
+ */
+export interface AuthStoreRefreshProbe {
+    /**
+     * A provider whose expired OAuth token the store refreshes through this
+     * endpoint (`anthropic`, `openai-codex`). The refresh checks write and
+     * remove its credential, then put it back as they found it.
+     */
+    readonly provider: ProviderId;
+    /** The token requests the endpoint has received so far. */
+    readonly requests: Effect.Effect<number>;
+    /**
+     * Hold the endpoint: a request that arrives waits, unanswered, until the
+     * returned effect runs. Running that effect again does nothing.
+     */
+    readonly hold: Effect.Effect<Effect.Effect<void>>;
+}
+/**
+ * What the kit can do to a store beyond calling it; each option turns on its checks.
+ *
+ * @public
+ */
+export interface AuthStoreConformanceOptions {
+    /** The endpoint the store refreshes through: the refresh-once and refresh-remove checks. */
+    readonly refresh?: AuthStoreRefreshProbe;
+    /**
+     * Damage the store's backing data (a file that is not JSON) for the
+     * scope's lifetime, and repair it when the scope closes: the corrupt check.
+     * A store with nothing to damage, such as one in memory, leaves it out.
+     */
+    readonly corrupt?: Effect.Effect<void, never, Scope.Scope>;
+}
+/**
+ * The AuthStore contract, as checks any store must pass: what `get`, `all`
+ * and `resolveKey` say about each kind of credential (every secret
+ * `Redacted`, holding the value that was set), what `set` and `remove`
+ * change, and that providers do not share state. Every check uses
+ * fresh provider ids (`conformance-<uuid>`, which no store can refresh) and
+ * removes them when it ends, so the kit can run against a shared store.
+ *
+ * With `options.refresh`, two checks refresh the probe's provider through
+ * the endpoint the test controls: concurrent calls on one expired token send
+ * one token request, and a `remove` made while it is in flight sticks. They
+ * wait for the store's requests on the live clock (up to two seconds), so
+ * run them without a `TestClock`. With
+ * `options.corrupt`, a store whose backing data cannot be read fails every
+ * call with an `AuthError` of code `auth.corrupt` instead of reading empty.
+ *
+ * @public
+ */
+export declare const authStoreConformance: (store: Store, options?: AuthStoreConformanceOptions) => ReadonlyArray<ConformanceCheck>;
+export {};

package/dist/auth/auth-store.conformance.js

@@ -0,0 +1,152 @@
+import { Clock, Effect, Fiber, Match, Option, Redacted, Schema } from "effect";
+import { harnessCodeOf, ProviderId } from "@xandreed/core";
+import { check, ConformanceFailure } from "@xandreed/core/conformance";
+import { randomUuid } from "@xandreed/core/internal";
+import { Credential } from "../ports/auth-store.port.js";
+const fail = (id, message) => Effect.fail(new ConformanceFailure({ check: id, message })), expect = (id, holds, message) => holds ? Effect.void : fail(id, message), HOUR = 3600000, CALLERS = 4, WAIT = "2 seconds", SETTLE = "100 millis", freshProvider = Effect.map(randomUuid, (id) => ProviderId.make(`conformance-${id}`)), secret = (label) => Effect.map(randomUuid, (id) => Redacted.make(`conformance-${label}-${id}`)), secretsOf = (credential) => Match.value(credential).pipe(Match.discriminatorsExhaustive("type")({
+  api_key: ({ key }) => [key],
+  oauth: ({ access, refresh }) => [access, refresh],
+  local: () => []
+})), redactedThroughout = (credential) => secretsOf(credential).every(Redacted.isRedacted), equivalent = Schema.toEquivalence(Credential), same = (a, b) => Option.exists(a, (value) => redactedThroughout(value) && equivalent(value, b)), keyOf = (id, resolved) => Option.match(resolved, {
+  onNone: () => Effect.succeed(Option.none()),
+  onSome: (key) => Redacted.isRedacted(key) ? Effect.succeed(Option.some(Redacted.value(key))) : fail(id, "the resolved key is not Redacted")
+}), withProviders = (store, count, body) => Effect.forEach(Array.from({ length: count }), () => freshProvider, { concurrency: 1 }).pipe(Effect.flatMap((providers) => body(providers).pipe(Effect.ensuring(Effect.forEach(providers, (provider) => store.remove(provider).pipe(Effect.ignore({ log: "Warn", message: `the kit could not remove its provider ${provider}` })), { concurrency: 1, discard: !0 }))))), withProbeProvider = (store, probe, body) => store.get(probe.provider).pipe(Effect.flatMap((before) => body(probe.provider).pipe(Effect.ensuring(Option.match(before, {
+  onNone: () => store.remove(probe.provider),
+  onSome: (credential) => store.set(probe.provider, credential)
+}).pipe(Effect.ignore({ log: "Warn", message: `the kit could not put back the credential of ${probe.provider}` })))))), expiredToken = Effect.gen(function* () {
+  const now = yield* Clock.currentTimeMillis;
+  return { type: "oauth", access: yield* secret("stale"), refresh: yield* secret("refresh"), expires: now - HOUR };
+}), requestsAbove = (probe, floor, within) => {
+  const poll = probe.requests.pipe(Effect.flatMap((count) => count > floor ? Effect.succeed(count) : Effect.sleep("2 millis").pipe(Effect.andThen(Effect.suspend(() => poll)))));
+  return Effect.timeoutOption(poll, within).pipe(Effect.flatMap(Option.match({ onNone: () => probe.requests, onSome: Effect.succeed })));
+}, corrupted = (what, effect) => Effect.result(effect).pipe(Effect.flatMap((result) => {
+  if (result._tag === "Success")
+    return fail("corrupt", `${what} succeeded on a store whose backing data cannot be read`);
+  const error = result.failure, tag = typeof error === "object" && error !== null && "_tag" in error ? String(error._tag) : "an error", code = Option.getOrElse(harnessCodeOf(error), () => "no code");
+  return expect("corrupt", tag === "AuthError" && code === "auth.corrupt", `${what} failed with ${tag} (${code}), not an AuthError of code auth.corrupt`);
+})), refreshChecks = (store, probe) => [
+  check(`${CALLERS} concurrent calls on one expired OAuth token send one refresh request and all get its new token`, "refresh-once", () => withProbeProvider(store, probe, (provider) => Effect.gen(function* () {
+    const stale = yield* expiredToken;
+    yield* store.set(provider, stale);
+    const before = yield* probe.requests, keys = yield* Effect.acquireUseRelease(probe.hold, (release) => Effect.gen(function* () {
+      const callers = yield* Effect.forEach(Array.from({ length: CALLERS }), () => Effect.forkChild(store.resolveKey(provider)), { concurrency: 1 });
+      yield* expect("refresh-once", (yield* requestsAbove(probe, before, WAIT)) > before, `no refresh request reached the endpoint within ${WAIT}`);
+      yield* requestsAbove(probe, before + 1, SETTLE);
+      yield* release;
+      return yield* Fiber.joinAll(callers);
+    }), (release) => release), sent = (yield* probe.requests) - before;
+    yield* expect("refresh-once", sent === 1, `${CALLERS} concurrent calls on one expired token sent ${sent} refresh requests`);
+    const values = yield* Effect.forEach(keys, (key) => keyOf("refresh-once", key), { concurrency: 1 }), first = Option.getOrUndefined(values[0] ?? Option.none());
+    yield* expect("refresh-once", first !== void 0 && first !== Redacted.value(stale.access), "the first call did not get a new token");
+    yield* expect("refresh-once", values.every((value) => Option.getOrUndefined(value) === first), "the concurrent calls got different keys");
+    const stored = yield* store.get(provider);
+    yield* expect("refresh-once", Option.exists(stored, (credential) => credential.type === "oauth" && redactedThroughout(credential) && Redacted.value(credential.access) === first), "the store does not hold the refreshed token");
+  }))),
+  check("a remove made while a refresh is in flight stays a remove: the refreshed token is not stored", "refresh-remove", () => withProbeProvider(store, probe, (provider) => Effect.gen(function* () {
+    yield* store.set(provider, yield* expiredToken);
+    const before = yield* probe.requests;
+    yield* Effect.acquireUseRelease(probe.hold, (release) => Effect.gen(function* () {
+      const refreshing = yield* Effect.forkChild(store.resolveKey(provider));
+      yield* expect("refresh-remove", (yield* requestsAbove(probe, before, WAIT)) > before, `no refresh request reached the endpoint within ${WAIT}`);
+      const removing = yield* Effect.forkChild(store.remove(provider));
+      yield* Effect.timeoutOption(Fiber.await(removing), SETTLE);
+      yield* release;
+      yield* Fiber.join(removing);
+      yield* Effect.result(Fiber.join(refreshing));
+    }), (release) => release);
+    yield* expect("refresh-remove", Option.isNone(yield* store.get(provider)), "get finds a credential after the remove");
+    yield* expect("refresh-remove", !(yield* store.all).has(provider), "all lists the provider after the remove");
+    yield* expect("refresh-remove", Option.isNone(yield* store.resolveKey(provider)), "resolveKey finds a key after the remove");
+  })))
+], corruptCheck = (store, corrupt) => check("a store whose backing data cannot be read fails every call with an AuthError of code auth.corrupt, never reads it as empty", "corrupt", () => withProviders(store, 2, ([provider, other]) => Effect.gen(function* () {
+  const id = provider, kept = { type: "api_key", key: yield* secret("kept") };
+  yield* store.set(id, kept);
+  yield* Effect.scoped(Effect.gen(function* () {
+    yield* corrupt;
+    yield* corrupted("get", store.get(id));
+    yield* corrupted("all", store.all);
+    yield* corrupted("resolveKey", store.resolveKey(id));
+    yield* corrupted("set", store.set(other, { type: "api_key", key: yield* secret("other") }));
+    yield* corrupted("remove", store.remove(id));
+  }));
+  yield* expect("corrupt", same(yield* store.get(id), kept), "once the backing data is repaired, the store does not read it again");
+})));
+export const authStoreConformance = (store, options = {}) => [
+  check("an absent provider has no credential, no key and no entry", "absent", () => withProviders(store, 1, ([provider]) => Effect.gen(function* () {
+    const id = provider;
+    yield* expect("absent", Option.isNone(yield* store.get(id)), "get found a credential");
+    yield* expect("absent", Option.isNone(yield* store.resolveKey(id)), "resolveKey found a key");
+    yield* expect("absent", !(yield* store.all).has(id), "all lists the provider");
+  }))),
+  check("an api_key credential reads back, is listed, and resolves to its key as Redacted", "api-key", () => withProviders(store, 1, ([provider]) => Effect.gen(function* () {
+    const id = provider, credential = { type: "api_key", key: yield* secret("key") };
+    yield* store.set(id, credential);
+    yield* expect("api-key", same(yield* store.get(id), credential), "get returned a different credential");
+    yield* expect("api-key", same(Option.fromNullishOr((yield* store.all).get(id)), credential), "all lists a different credential, or none");
+    const key = yield* keyOf("api-key", yield* store.resolveKey(id));
+    yield* expect("api-key", Option.getOrUndefined(key) === Redacted.value(credential.key), "resolveKey did not return the stored key");
+  }))),
+  check("a local credential reads back and resolves to no key", "local", () => withProviders(store, 1, ([provider]) => Effect.gen(function* () {
+    const id = provider, credential = { type: "local", baseUrl: "http://127.0.0.1:1/v1" };
+    yield* store.set(id, credential);
+    yield* expect("local", same(yield* store.get(id), credential), "get returned a different credential");
+    yield* expect("local", Option.isNone(yield* store.resolveKey(id)), "resolveKey returned a key for a local credential");
+  }))),
+  check("an OAuth token that has not expired resolves to its access token", "oauth-valid", () => withProviders(store, 1, ([provider]) => Effect.gen(function* () {
+    const id = provider, now = yield* Clock.currentTimeMillis, credential = { type: "oauth", access: yield* secret("access"), refresh: yield* secret("refresh"), expires: now + HOUR };
+    yield* store.set(id, credential);
+    yield* expect("oauth-valid", same(yield* store.get(id), credential), "get returned a different credential");
+    const key = yield* keyOf("oauth-valid", yield* store.resolveKey(id));
+    yield* expect("oauth-valid", Option.getOrUndefined(key) === Redacted.value(credential.access), "resolveKey did not return the access token");
+  }))),
+  check("get and all hand out every secret Redacted", "redacted", () => withProviders(store, 2, ([first, second]) => Effect.gen(function* () {
+    const now = yield* Clock.currentTimeMillis, written = [
+      [first, { type: "api_key", key: yield* secret("key") }],
+      [second, { type: "oauth", access: yield* secret("access"), refresh: yield* secret("refresh"), expires: now + HOUR }]
+    ];
+    yield* Effect.forEach(written, ([id, credential]) => store.set(id, credential), { concurrency: 1, discard: !0 });
+    const all = yield* store.all;
+    yield* Effect.forEach(written, ([id, credential]) => Effect.gen(function* () {
+      yield* expect("redacted", Option.exists(yield* store.get(id), redactedThroughout), `get returned no ${credential.type} credential, or one whose secrets are not all Redacted`);
+      yield* expect("redacted", Option.exists(Option.fromNullishOr(all.get(id)), redactedThroughout), `all lists no ${credential.type} credential, or one whose secrets are not all Redacted`);
+    }), { concurrency: 1, discard: !0 });
+  }))),
+  check("an expired OAuth token the store cannot refresh fails with an AuthError naming the provider, never the stale token", "oauth-expired", () => withProviders(store, 1, ([provider]) => Effect.gen(function* () {
+    const id = provider, now = yield* Clock.currentTimeMillis;
+    yield* store.set(id, { type: "oauth", access: yield* secret("stale"), refresh: yield* secret("refresh"), expires: now - HOUR });
+    const resolved = yield* Effect.result(store.resolveKey(id));
+    if (resolved._tag === "Success")
+      return yield* fail("oauth-expired", Option.isSome(resolved.success) ? "resolveKey returned the expired token" : "resolveKey found no key instead of failing");
+    yield* expect("oauth-expired", resolved.failure._tag === "AuthError" && resolved.failure.provider === id, `failed with ${resolved.failure._tag} for ${resolved.failure.provider}`);
+  }))),
+  check("a second set replaces the first", "overwrite", () => withProviders(store, 1, ([provider]) => Effect.gen(function* () {
+    const id = provider, second = { type: "api_key", key: yield* secret("second") };
+    yield* store.set(id, { type: "api_key", key: yield* secret("first") });
+    yield* store.set(id, second);
+    yield* expect("overwrite", same(yield* store.get(id), second), "get still returns the first credential");
+    const key = yield* keyOf("overwrite", yield* store.resolveKey(id));
+    yield* expect("overwrite", Option.getOrUndefined(key) === Redacted.value(second.key), "resolveKey still returns the first key");
+  }))),
+  check("remove deletes a credential wherever it is read, and removing an absent provider succeeds", "remove", () => withProviders(store, 2, ([provider, unknown]) => Effect.gen(function* () {
+    const id = provider;
+    yield* store.set(id, { type: "api_key", key: yield* secret("removed") });
+    yield* store.remove(id);
+    yield* expect("remove", Option.isNone(yield* store.get(id)), "get still finds the credential");
+    yield* expect("remove", Option.isNone(yield* store.resolveKey(id)), "resolveKey still finds a key");
+    yield* expect("remove", !(yield* store.all).has(id), "all still lists the provider");
+    yield* store.remove(id);
+    yield* store.remove(unknown);
+  }))),
+  check("providers are isolated: writing or removing one leaves another as it was", "isolation", () => withProviders(store, 2, ([first, second]) => Effect.gen(function* () {
+    const a = first, b = second, kept = { type: "api_key", key: yield* secret("kept") };
+    yield* store.set(b, kept);
+    yield* store.set(a, { type: "api_key", key: yield* secret("other") });
+    yield* store.remove(a);
+    yield* store.set(a, { type: "local" });
+    yield* expect("isolation", same(yield* store.get(b), kept), "another provider's credential changed");
+    const key = yield* keyOf("isolation", yield* store.resolveKey(b));
+    yield* expect("isolation", Option.getOrUndefined(key) === Redacted.value(kept.key), "another provider's key changed");
+  }))),
+  ...Option.match(Option.fromNullishOr(options.refresh), { onNone: () => [], onSome: (probe) => refreshChecks(store, probe) }),
+  ...Option.match(Option.fromNullishOr(options.corrupt), { onNone: () => [], onSome: (corrupt) => [corruptCheck(store, corrupt)] })
+];

package/dist/auth/credential-input.entity.d.ts

@@ -0,0 +1,52 @@
+import { Schema } from "effect";
+/**
+ * The provider account an OAuth credential is for (the ChatGPT account of an `openai-codex` subscription).
+ *
+ * @public
+ */
+export declare const AccountId: Schema.brand<Schema.String, "AccountId">;
+export type AccountId = typeof AccountId.Type;
+/**
+ * The installation an OAuth credential was issued to, when its provider names one.
+ *
+ * @public
+ */
+export declare const InstallationId: Schema.brand<Schema.String, "InstallationId">;
+export type InstallationId = typeof InstallationId.Type;
+export declare const CredentialInput: Schema.Union<readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"api_key">;
+    readonly key: Schema.Redacted<Schema.String>;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"oauth">;
+    readonly access: Schema.Redacted<Schema.String>;
+    readonly refresh: Schema.Redacted<Schema.String>;
+    /** Absolute expiry, epoch ms. */
+    readonly expires: Schema.Number;
+    readonly accountId: Schema.optionalKey<Schema.brand<Schema.String, "AccountId">>;
+    readonly installationId: Schema.optionalKey<Schema.brand<Schema.String, "InstallationId">>;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"local">;
+    readonly baseUrl: Schema.optionalKey<Schema.String>;
+}>]>;
+export type CredentialInput = typeof CredentialInput.Type;
+/**
+ * Credentials by provider id.
+ *
+ * @public
+ */
+export declare const CredentialInputs: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"api_key">;
+    readonly key: Schema.Redacted<Schema.String>;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"oauth">;
+    readonly access: Schema.Redacted<Schema.String>;
+    readonly refresh: Schema.Redacted<Schema.String>;
+    /** Absolute expiry, epoch ms. */
+    readonly expires: Schema.Number;
+    readonly accountId: Schema.optionalKey<Schema.brand<Schema.String, "AccountId">>;
+    readonly installationId: Schema.optionalKey<Schema.brand<Schema.String, "InstallationId">>;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"local">;
+    readonly baseUrl: Schema.optionalKey<Schema.String>;
+}>]>>;
+export type CredentialInputs = typeof CredentialInputs.Type;

package/dist/auth/credential-input.entity.functions.d.ts

@@ -0,0 +1,18 @@
+import { Effect } from "effect";
+import { AuthError, Credential } from "../ports/auth-store.port.js";
+import type { CredentialInput, CredentialInputs } from "./credential-input.entity.js";
+/**
+ * A credential in its stored form, secrets in the clear: what `auth.json`
+ * holds for it. A secret that is not `Redacted` (a plain string from
+ * untyped code), or a field the credential does not type so, fails with an
+ * `AuthError` naming the provider, never the value.
+ */
+export declare const encodeCredential: (provider: string, credential: Credential) => Effect.Effect<typeof Credential.Encoded, AuthError>;
+/**
+ * A stored credential as a host receives it: the same secrets, already
+ * `Redacted`, and an OAuth credential's account and installation ids
+ * branded (`AccountId`, `InstallationId`).
+ */
+export declare const toCredentialInput: (credential: Credential) => CredentialInput;
+/** Handed-over credentials, by provider id, as the store keeps them. */
+export declare const credentialsOf: (inputs: CredentialInputs) => ReadonlyMap<string, Credential>;

package/dist/auth/credential-input.entity.functions.js

@@ -0,0 +1,12 @@
+import { Effect, Match, Schema } from "effect";
+import { AuthError, Credential } from "../ports/auth-store.port.js";
+import { AccountId, InstallationId } from "./credential-input.entity.js";
+const encode = Schema.encodeEffect(Credential);
+export const encodeCredential = (provider, credential) => encode(credential).pipe(Effect.mapError(() => new AuthError({
+  provider,
+  message: `the ${provider} credential cannot be stored: its secrets must be Redacted values (Redacted.make(...)), and its other fields those of a credential`
+}))), toCredentialInput = (credential) => Match.value(credential).pipe(Match.when({ type: "api_key" }, (apiKey) => apiKey), Match.when({ type: "oauth" }, ({ accountId, installationId, ...oauth }) => ({
+  ...oauth,
+  ...accountId === void 0 ? {} : { accountId: AccountId.make(accountId) },
+  ...installationId === void 0 ? {} : { installationId: InstallationId.make(installationId) }
+})), Match.when({ type: "local" }, (local) => local), Match.exhaustive), credentialsOf = (inputs) => new Map(Object.entries(inputs));

package/dist/auth/credential-input.entity.js

@@ -0,0 +1,22 @@
+import { Schema } from "effect";
+const secret = Schema.Redacted(Schema.String).annotate({
+  message: "a secret must be a Redacted value (Redacted.make(...)); JSON configuration names an environment variable in credentialEnv instead"
+});
+export const AccountId = Schema.String.pipe(Schema.brand("AccountId")), InstallationId = Schema.String.pipe(Schema.brand("InstallationId"));
+const unexpectedKey = { messageUnexpectedKey: "not a field of a credential" };
+export const CredentialInput = Schema.Union([
+  Schema.Struct({ type: Schema.Literal("api_key"), key: secret }).annotate(unexpectedKey),
+  Schema.Struct({
+    type: Schema.Literal("oauth"),
+    access: secret,
+    refresh: secret,
+    expires: Schema.Number.annotate({ message: "expires is the access token's expiry, in epoch ms" }).check(Schema.isFinite()),
+    accountId: Schema.optionalKey(AccountId),
+    installationId: Schema.optionalKey(InstallationId)
+  }).annotate(unexpectedKey),
+  Schema.Struct({ type: Schema.Literal("local"), baseUrl: Schema.optionalKey(Schema.String) }).annotate(unexpectedKey)
+]).annotate({
+  message: 'a credential is { type: "api_key", key }, { type: "oauth", access, refresh, expires, accountId?, installationId? } or { type: "local", baseUrl? }, with Redacted secrets'
+}), CredentialInputs = Schema.Record(Schema.String, CredentialInput).annotate({
+  message: "credentials maps provider ids to credentials"
+});

package/dist/auth/credential-refresh.entity.d.ts

@@ -0,0 +1,17 @@
+import { Schema } from "effect";
+import type { Credential } from "../ports/auth-store.port.js";
+/**
+ * The providers whose OAuth tokens a store can refresh: each has its token endpoint in an auth module.
+ *
+ * @public
+ */
+export declare const RefreshableProvider: Schema.Literals<readonly ["anthropic", "openai-codex"]>;
+export type RefreshableProvider = typeof RefreshableProvider.Type;
+/**
+ * An OAuth subscription credential: an access token, its refresh token and its expiry (epoch ms).
+ *
+ * @public
+ */
+export type OAuthCredential = Extract<Credential, {
+    readonly type: "oauth";
+}>;

package/dist/auth/credential-refresh.entity.functions.d.ts

@@ -0,0 +1,57 @@
+import { Effect, Option } from "effect";
+import type { Redacted, Semaphore } from "effect";
+import { AuthError } from "../ports/auth-store.port.js";
+import type { ProviderId } from "@xandreed/core";
+import type { Credential } from "../ports/auth-store.port.js";
+import type { TokenRequestOptions } from "./anthropicOAuth.js";
+import type { OAuthCredential } from "./credential-refresh.entity.js";
+/**
+ * Refresh this many ms before the recorded expiry.
+ *
+ * @public
+ */
+export declare const REFRESH_SKEW_MS = 60000;
+/**
+ * Whether an OAuth credential can still be used at `now`: more than the skew before its expiry.
+ *
+ * @public
+ */
+export declare const isUsableAt: (credential: OAuthCredential, now: number) => boolean;
+/**
+ * Refresh one provider's OAuth credential through that provider's token
+ * endpoint: the same credential with the new access token, refresh token
+ * and expiry (and account id, where the provider sends one), its tokens
+ * `Redacted`. A provider with no refresh flow fails with an `AuthError`
+ * naming it.
+ *
+ * @public
+ */
+export declare const refreshCredential: (provider: string, credential: OAuthCredential, options?: TokenRequestOptions) => Effect.Effect<OAuthCredential, AuthError>;
+/** Whether `held` is still the token `stale` is: the same access token, refresh token and expiry. */
+export declare const isSameToken: (held: Credential, stale: OAuthCredential) => boolean;
+/** One provider's credential as a store keeps it, seen by the refresh. */
+export interface CredentialSlot {
+    /** The credential the store holds now, read again on every call. */
+    readonly current: Effect.Effect<Option.Option<Credential>, AuthError>;
+    /**
+     * Store `fresh` only if the provider still holds `stale` (`isSameToken`),
+     * atomically with the store's other writes; whether it was stored.
+     */
+    readonly commit: (stale: OAuthCredential, fresh: OAuthCredential) => Effect.Effect<boolean, AuthError>;
+    /** Held while a refresh runs, so one refresh of the credential runs at a time. */
+    readonly refreshLock: Effect.Effect<Semaphore.Semaphore>;
+}
+/**
+ * The key a slot's credential resolves to: an API key as it is, a usable
+ * OAuth access token, or the token a refresh gives a near-expiry one. A
+ * `local` credential, or none, has no key.
+ *
+ * One refresh runs at a time. Once the lock is held, a credential that is no
+ * longer the expired one (refreshed by the call ahead, replaced or removed)
+ * is resolved again instead, so concurrent calls send one token request. A
+ * refresh stores its token only if the credential is still the one it
+ * refreshed: a login or logout made meanwhile wins. The token request and
+ * its commit run uninterrupted, since a provider that rotated the refresh
+ * token has already spent the old one.
+ */
+export declare const resolveSlotKey: (provider: ProviderId, slot: CredentialSlot, tokens: TokenRequestOptions) => Effect.Effect<Option.Option<Redacted.Redacted<string>>, AuthError>;

package/dist/auth/credential-refresh.entity.functions.js

@@ -0,0 +1,21 @@
+import { Clock, Effect, Equal, Match, Option, Schema } from "effect";
+import { AuthError } from "../ports/auth-store.port.js";
+import { refreshAnthropicToken } from "./anthropicOAuth.js";
+import { RefreshableProvider } from "./credential-refresh.entity.js";
+import { refreshOpenAiCodexToken } from "./openAiCodexOAuth.js";
+export const REFRESH_SKEW_MS = 60000, isUsableAt = (credential, now) => credential.expires > now + REFRESH_SKEW_MS, refreshCredential = (provider, credential, options = {}) => Option.match(Schema.decodeUnknownOption(RefreshableProvider)(provider), {
+  onNone: () => Effect.fail(new AuthError({
+    provider,
+    message: `the ${provider} OAuth token expired and only anthropic and openai-codex tokens can be refreshed \u2014 sign in again or use an API key`
+  })),
+  onSome: (refreshable) => Match.value(refreshable).pipe(Match.when("anthropic", () => refreshAnthropicToken(credential.refresh, options)), Match.when("openai-codex", () => refreshOpenAiCodexToken(credential.refresh, options)), Match.exhaustive).pipe(Effect.map((fresh) => ({ ...credential, ...fresh })))
+}), isSameToken = (held, stale) => held.type === "oauth" && Equal.equals(held.access, stale.access) && Equal.equals(held.refresh, stale.refresh) && held.expires === stale.expires, resolveSlotKey = (provider, slot, tokens) => {
+  const refreshing = (stale) => slot.refreshLock.pipe(Effect.flatMap((lock) => lock.withPermit(slot.current.pipe(Effect.flatMap((before) => Option.exists(before, (held) => isSameToken(held, stale)) ? Effect.uninterruptible(refreshCredential(provider, stale, tokens).pipe(Effect.flatMap((fresh) => slot.commit(stale, fresh).pipe(Effect.map((stored) => stored ? Option.some(fresh.access) : Option.none()))))) : Effect.succeedNone)))), Effect.flatMap(Option.match({
+    onSome: (access) => Effect.succeedSome(access),
+    onNone: () => resolveSlotKey(provider, slot, tokens)
+  })));
+  return slot.current.pipe(Effect.flatMap(Option.match({
+    onNone: () => Effect.succeedNone,
+    onSome: (credential) => Match.value(credential).pipe(Match.when({ type: "api_key" }, ({ key }) => Effect.succeedSome(key)), Match.when({ type: "local" }, () => Effect.succeedNone), Match.when({ type: "oauth" }, (oauth) => Clock.currentTimeMillis.pipe(Effect.flatMap((now) => isUsableAt(oauth, now) ? Effect.succeedSome(oauth.access) : refreshing(oauth)))), Match.exhaustive)
+  })));
+};

package/dist/auth/credential-refresh.entity.js

@@ -0,0 +1,2 @@
+import { Schema } from "effect";
+export const RefreshableProvider = Schema.Literals(["anthropic", "openai-codex"]);

package/dist/auth/localAuth.d.ts

@@ -1,8 +1,18 @@
 import { Layer } from "effect";
-import { AuthStore } from "@xandreed/core";
+import { AuthStore } from "../ports/auth-store.port.js";
 export declare const authPaths: (cwd: string, home: string, directory?: string) => ReadonlyArray<string>;
 /**
  * `LocalAuthStoreLive(cwd, home)` — read-through: every call re-reads disk,
- * so a credential added mid-session applies on the next request.
+ * so a credential added mid-session applies on the next request. A token
+ * refresh goes through the `ModelsTransport` the layer is built over, if any.
+ *
+ * A file that cannot be read or is not a JSON object fails every call with
+ * an `AuthError` of code `auth.corrupt`; only a missing file reads as empty.
+ * Each write re-reads its file under that file's lock, which every store in
+ * the process shares, and replaces it through a temp file of its own. One
+ * refresh of a provider's token runs at a time, and stores its token only if
+ * the provider still holds the one it refreshed, so a login or logout made
+ * during the refresh wins. The locks hold within one process: two processes
+ * sharing these files can still lose an update.
  */
 export declare const LocalAuthStoreLive: (cwd: string, home: string, directory?: string, fallbackDirectory?: string) => Layer.Layer<AuthStore, never, never>;