@xandreed/plugin-models 0.14.0 → 0.15.0

package/README.md

@@ -1,5 +1,5 @@
 # @xandreed/plugin-models
 
-Efferent composable agent framework, 0.14.0. Node 24.5 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,5 @@
-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:
@@ -16,9 +16,14 @@ 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;
 }
@@ -28,6 +33,8 @@ export interface RefreshedTokens {
  * 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;
@@ -35,14 +42,19 @@ export interface TokenRequestOptions {
 }
 /** 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. */
-export declare const refreshAnthropicToken: (refreshToken: string, options?: TokenRequestOptions) => Effect.Effect<RefreshedTokens, AuthError>;
+/**
+ * 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. */
@@ -51,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. */
+/** 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,6 +1,8 @@
-import { Clock, 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}`;
@@ -11,7 +13,7 @@ const oauthError = (stage) => (detail) => new AuthError({
   message: `OAuth ${stage} failed: ${detail}`
 });
 export const tokenTime = (options) => options.now === void 0 ? Clock.currentTimeMillis : Effect.succeed(options.now);
-const postToken = (body, stage, options) => {
+const postToken = (body, stage, options, previous) => {
   const fail = oauthError(stage);
   return Effect.tryPromise({
     try: async () => {
@@ -24,26 +26,21 @@ const postToken = (body, stage, options) => {
       return { ok: res.ok, status: res.status, text: await res.text() };
     },
     catch: (e) => fail(redactCredentials(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.flatMap((data) => Effect.map(tokenTime(options), (now) => ({
-    access: data.access_token,
-    refresh: data.refresh_token,
-    expires: now + data.expires_in * 1000 - 300000
+  }).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, options = {}) => postToken({
   grant_type: "refresh_token",
   client_id: ANTHROPIC_CLIENT_ID,
-  refresh_token: refreshToken
-}, "token refresh", options);
+  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({
@@ -65,7 +62,7 @@ export const generatePkce = Effect.promise(async () => {
   redirect_uri: ANTHROPIC_REDIRECT_URI,
   code_verifier: verifier,
   state: verifier
-}, "code exchange", options);
+}, "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

@@ -1,4 +1,18 @@
 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>;
@@ -8,14 +22,18 @@ export declare const CredentialInput: Schema.Union<readonly [Schema.Struct<{
     readonly refresh: Schema.Redacted<Schema.String>;
     /** Absolute expiry, epoch ms. */
     readonly expires: Schema.Number;
-    readonly accountId: Schema.optionalKey<Schema.String>;
-    readonly installationId: Schema.optionalKey<Schema.String>;
+    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. */
+/**
+ * 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>;
@@ -25,8 +43,8 @@ export declare const CredentialInputs: Schema.$Record<Schema.String, Schema.Unio
     readonly refresh: Schema.Redacted<Schema.String>;
     /** Absolute expiry, epoch ms. */
     readonly expires: Schema.Number;
-    readonly accountId: Schema.optionalKey<Schema.String>;
-    readonly installationId: Schema.optionalKey<Schema.String>;
+    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>;

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

@@ -1,8 +1,18 @@
-import type { Credential } from "@xandreed/core";
+import { Effect } from "effect";
+import { AuthError, Credential } from "../ports/auth-store.port.js";
 import type { CredentialInput, CredentialInputs } from "./credential-input.entity.js";
-/** The stored form of a credential a host handed over: its secrets unwrapped. */
-export declare const toCredential: (input: CredentialInput) => Credential;
-/** A stored credential as a host receives it: its secrets `Redacted`. */
+/**
+ * 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, in their stored form. */
+/** 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

@@ -1,9 +1,12 @@
-import { Match, Redacted } from "effect";
-export const toCredential = (input) => Match.value(input).pipe(Match.when({ type: "api_key" }, ({ key }) => ({ type: "api_key", key: Redacted.value(key) })), Match.when({ type: "oauth" }, ({ access, refresh, ...rest }) => ({ ...rest, access: Redacted.value(access), refresh: Redacted.value(refresh) })), Match.when({ type: "local" }, (local) => local), Match.exhaustive), toCredentialInput = (credential) => Match.value(credential).pipe(Match.when({ type: "api_key" }, ({ key }) => ({ type: "api_key", key: Redacted.make(key) })), Match.when({ type: "oauth" }, ({ type, access, refresh, expires, accountId, installationId }) => ({
-  type,
-  expires,
-  access: Redacted.make(access),
-  refresh: Redacted.make(refresh),
-  ...accountId === void 0 ? {} : { accountId },
-  ...installationId === void 0 ? {} : { installationId }
-})), Match.when({ type: "local" }, ({ type, baseUrl }) => ({ type, ...baseUrl === void 0 ? {} : { baseUrl } })), Match.exhaustive), credentialsOf = (inputs) => new Map(Object.entries(inputs).map(([provider, input]) => [provider, toCredential(input)]));
+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

@@ -1,7 +1,9 @@
 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"
-}), unexpectedKey = { messageUnexpectedKey: "not a field of a credential" };
+});
+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({
@@ -9,8 +11,8 @@ export const CredentialInput = Schema.Union([
     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(Schema.String),
-    installationId: Schema.optionalKey(Schema.String)
+    accountId: Schema.optionalKey(AccountId),
+    installationId: Schema.optionalKey(InstallationId)
   }).annotate(unexpectedKey),
   Schema.Struct({ type: Schema.Literal("local"), baseUrl: Schema.optionalKey(Schema.String) }).annotate(unexpectedKey)
 ]).annotate({

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

@@ -1,9 +1,17 @@
 import { Schema } from "effect";
-import type { Credential } from "@xandreed/core";
-/** The providers whose OAuth tokens a store can refresh: each has its token endpoint in an auth module. */
+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). */
+/**
+ * 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

@@ -1,15 +1,57 @@
-import { Effect } from "effect";
-import { AuthError } from "@xandreed/core";
+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. */
+/**
+ * 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. */
+/**
+ * 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). A provider
- * with no refresh flow fails with an `AuthError` naming it.
+ * 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

@@ -1,5 +1,5 @@
-import { Effect, Match, Option, Schema } from "effect";
-import { AuthError } from "@xandreed/core";
+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";
@@ -9,4 +9,13 @@ export const REFRESH_SKEW_MS = 60000, isUsableAt = (credential, now) => credenti
     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)
+  })));
+};