@agentxm/registry-auth 0.28.11 → 0.28.13

package/dist/src/identity.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The authenticated identity of the selected Registry, and the credential
+ * lifecycle rule that governs reading it: a stored credential the Registry
+ * rejects is refreshed once and the read is retried, while a rejected ambient
+ * credential is reported as sign-in required.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import { AuthClient } from "./auth-client.js";
+import { CredentialStore } from "./credential-store.js";
+/** The Registry's canonical answer to "who is this credential". */
+export interface RegistryIdentity {
+    readonly user: Handle;
+    readonly registry: string;
+    readonly credentialType: string;
+    readonly scopes: ReadonlyArray<string>;
+    readonly resourceRestrictions: {
+        readonly extensions: ReadonlyArray<string> | null;
+    };
+    readonly expiresAt: DateTime.Utc | null;
+}
+/**
+ * Read the canonical Registry identity for the resolved credential.
+ *
+ * Only a credential this workspace stores can be refreshed: an ambient token
+ * the Registry rejects is the caller's to replace, so it maps to sign-in
+ * required rather than a silent refresh attempt.
+ */
+export declare const currentIdentity: (registryUrl: string) => Effect.Effect<{
+    user: string & import("effect/Brand").Brand<"Handle">;
+    registry: string;
+    credentialType: string;
+    scopes: readonly string[];
+    resourceRestrictions: {
+        readonly extensions: ReadonlyArray<string> | null;
+    };
+    expiresAt: DateTime.Utc | null;
+}, import("./errors.js").AuthError, AuthClient | CredentialStore>;
+/** The token an invocation would present to the selected Registry. */
+export declare const currentToken: (registryUrl: string) => Effect.Effect<string, import("./errors.js").AuthError, CredentialStore>;
+/** Both members keep `CredentialStore` in `R`; declared for the reader. */
+export type IdentityRequirements = AuthClient | CredentialStore;
+//# sourceMappingURL=identity.d.ts.map

package/dist/src/identity.js

@@ -0,0 +1,49 @@
+/**
+ * The authenticated identity of the selected Registry, and the credential
+ * lifecycle rule that governs reading it: a stored credential the Registry
+ * rejects is refreshed once and the read is retried, while a rejected ambient
+ * credential is reported as sign-in required.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { isRegistryClientFailure } from "@agentxm/registry-client";
+import { AuthClient } from "./auth-client.js";
+import { CredentialStore } from "./credential-store.js";
+import { authLoginRequired } from "./errors.js";
+import { refreshStoredToken, resolveRequiredToken } from "./token-resolution.js";
+const isRejectedCredential = (error) => isRegistryClientFailure(error) && error.metadata?.response?.status === 401;
+/**
+ * Read the canonical Registry identity for the resolved credential.
+ *
+ * Only a credential this workspace stores can be refreshed: an ambient token
+ * the Registry rejects is the caller's to replace, so it maps to sign-in
+ * required rather than a silent refresh attempt.
+ */
+export const currentIdentity = Effect.fn("Identity.current")(function* (registryUrl) {
+    const authClient = yield* AuthClient;
+    const token = yield* resolveRequiredToken(registryUrl, {
+        missingTokenError: authLoginRequired("Not authenticated"),
+    });
+    const identity = yield* authClient.getMe(token.token).pipe(Effect.catch((error) => token._tag === "CredentialStore" && isRejectedCredential(error)
+        ? refreshStoredToken(token).pipe(Effect.flatMap((refreshed) => authClient.getMe(refreshed.token)))
+        : Effect.fail(error)), Effect.mapError((error) => isRejectedCredential(error)
+        ? authLoginRequired("Invalid or expired credential. Authenticate again.", error)
+        : error));
+    return {
+        user: identity.userHandle,
+        registry: registryUrl,
+        credentialType: identity.tokenType,
+        scopes: identity.scopes,
+        resourceRestrictions: identity.resourceRestrictions,
+        expiresAt: identity.expiresAt,
+    };
+});
+/** The token an invocation would present to the selected Registry. */
+export const currentToken = Effect.fn("Identity.currentToken")(function* (registryUrl) {
+    const token = yield* resolveRequiredToken(registryUrl, {
+        missingTokenError: authLoginRequired("No token available"),
+    });
+    return token.token;
+});
+//# sourceMappingURL=identity.js.map

package/dist/src/index.d.ts

@@ -10,7 +10,7 @@
  * @experimental This API is unstable and may change without notice.
  * @packageDocumentation
  */
-export { AuthExchangeFailed, AuthLoginRequired, AuthTokenPolicyRequired, authLoginRequired, DeviceAuthorizationPending, DeviceLoginCodeExpired, DeviceLoginDenied, isAuthError, isRegistryAuthFailure, REGISTRY_AUTH_ERROR_CATEGORIES, RegistryAuthFailed, StepUpRequired, type AuthError, type RegistryAuthErrorCategory, type RegistryAuthFailure, type StepUpRequest, } from "./errors.js";
+export { AuthExchangeFailed, AuthLoginRequired, AuthTokenPolicyRequired, authLoginRequired, DeviceAuthorizationPending, PublishAuthorizationPending, DeviceLoginCodeExpired, DeviceLoginDenied, AuthInteractionAbandoned, isAuthError, isRegistryAuthFailure, REGISTRY_AUTH_ERROR_CATEGORIES, RegistryAuthFailed, StepUpRequired, StepUpVerificationPending, type AuthError, type RegistryAuthErrorCategory, type RegistryAuthFailure, type StepUpRequest, } from "./errors.js";
 export type { CredentialEntry, CredentialFile, StorageTier, StoredCredentials, TokenSource, } from "./schema.js";
 export { CredentialEntrySchema, CredentialFileSchema, CredentialStoreTokenSource, EnvVarTokenSource, FileTokenSource, FlagTokenSource, RegistryAccountsSchema, } from "./schema.js";
 export type { CredentialStoreService, EnvironmentInfo } from "./credential-store.js";
@@ -18,7 +18,7 @@ export { canUsePersistedCredentials, CredentialStore, detectEnvironment, makePer
 export type { PendingDeviceLogin, PendingDeviceLoginStoreService, } from "./pending-device-login-store.js";
 export { PendingDeviceLoginSchema, PendingDeviceLoginStore } from "./pending-device-login-store.js";
 export { getCurrentUserHandle, resolveRequiredToken, resolveToken, resolveStoredToken, refreshStoredToken, resolveAmbientToken, resolveRequestToken, } from "./token-resolution.js";
-export type { AuthClientService, CreateTokenOptions, CreatePublishAuthorizationRequestParams, DeviceFlowResponse, ExchangePublishAuthorizationCodeParams, MeResponse, PollResult, PublishAuthorizationRequestResponse, PublishCapabilityResponse, } from "./auth-client.js";
+export type { AuthClientService, CreateTokenOptions, CreatePublishAuthorizationRequestParams, DeviceFlowResponse, ExchangePublishAuthorizationCodeParams, MeResponse, PollResult, PublishAuthorizationRequestResponse, PublishAuthorizationExchangeResponse, PublishCapabilityResponse, } from "./auth-client.js";
 export { AuthClient, pollOnce, readStepUpRequest } from "./auth-client.js";
 export type { NormalizedTokenResponse } from "./oauth-contract.js";
 export type { DeviceLoginPendingResult, DeviceLoginInteractionService, ResumeDeviceLoginOptions, } from "./device-login.js";
@@ -28,9 +28,19 @@ export { LoopbackCallbackRejected, LoopbackLoginFallback, startLoopbackServer, }
 export { LoginDocumentSchema, LoginResultSchema, makeLoginResult, type LoginDocument, type LoginResult, } from "./login-output.js";
 export type { AuthLoginPresenterService, AuthLoginProgress, DeviceFlowPresentation, } from "./login-presenter.js";
 export { AuthLoginPresenter } from "./login-presenter.js";
+export type { DeviceCodeFallbackReason, SessionReplacementDecision, StepUpChallengePresentation, } from "./login-presenter.js";
+export { runWithStepUp, type StepUpOptions, type StepUpPresentation, type VerifiedWrite, } from "./step-up.js";
+export { selectedRegistry, type SelectedRegistry } from "./selected-registry.js";
+export { classifyLoopbackFailure, deviceLoginOptions, login, resumeLoginOptions, type LoginOutcome, type LoginRequest, } from "./login.js";
+export { logout, type LogoutOutcome } from "./logout.js";
+export { currentIdentity, currentToken, type RegistryIdentity } from "./identity.js";
+export { createToken, listTokens, parseExpiresInSeconds, revokeToken, tokenPermissions, validateExpiresInSeconds, MAX_TOKEN_LIFETIME_SECONDS, MIN_TOKEN_LIFETIME_SECONDS, type CreateTokenRequest, type CreatedToken, type TokenAuthorityRequest, } from "./tokens.js";
+export { hasCredentialsForAll } from "./login-suggestion.js";
+export { AuthEnvironment } from "./internal/environment.js";
 export { runPublishAuthorization, type PublishAuthorizationInput, } from "./publish-authorization.js";
 export { selectLoginStrategy, type LoginStrategy, type LoginStrategyEnvironment, type LoginStrategyOptions, } from "./login-strategy.js";
 export type { AuthLoginInteractionService } from "./login-interaction.js";
 export { AuthLoginInteraction } from "./login-interaction.js";
 export { withAuthGuard } from "./guard.js";
+export { PendingPublishAuthorizationStore, PendingPublishAuthorizationSchema, type PendingPublishAuthorization, type PendingPublishAuthorizationStoreService, } from "./pending-publish-authorization-store.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -11,7 +11,7 @@
  * @packageDocumentation
  */
 // Typed failures
-export { AuthExchangeFailed, AuthLoginRequired, AuthTokenPolicyRequired, authLoginRequired, DeviceAuthorizationPending, DeviceLoginCodeExpired, DeviceLoginDenied, isAuthError, isRegistryAuthFailure, REGISTRY_AUTH_ERROR_CATEGORIES, RegistryAuthFailed, StepUpRequired, } from "./errors.js";
+export { AuthExchangeFailed, AuthLoginRequired, AuthTokenPolicyRequired, authLoginRequired, DeviceAuthorizationPending, PublishAuthorizationPending, DeviceLoginCodeExpired, DeviceLoginDenied, AuthInteractionAbandoned, isAuthError, isRegistryAuthFailure, REGISTRY_AUTH_ERROR_CATEGORIES, RegistryAuthFailed, StepUpRequired, StepUpVerificationPending, } from "./errors.js";
 export { CredentialEntrySchema, CredentialFileSchema, CredentialStoreTokenSource, EnvVarTokenSource, FileTokenSource, FlagTokenSource, RegistryAccountsSchema, } from "./schema.js";
 export { canUsePersistedCredentials, CredentialStore, detectEnvironment, makePersistedCredentialsUnsupportedError, selectTier, } from "./credential-store.js";
 export { PendingDeviceLoginSchema, PendingDeviceLoginStore } from "./pending-device-login-store.js";
@@ -23,9 +23,22 @@ export { makeOAuthState, makePkceChallenge, makePkceVerifier, runLoopbackLogin,
 export { LoopbackCallbackRejected, LoopbackLoginFallback, startLoopbackServer, } from "./loopback-server.js";
 export { LoginDocumentSchema, LoginResultSchema, makeLoginResult, } from "./login-output.js";
 export { AuthLoginPresenter } from "./login-presenter.js";
+// Step-up verification protocol
+export { runWithStepUp, } from "./step-up.js";
+// The Registry this invocation authenticates against
+export { selectedRegistry } from "./selected-registry.js";
+// Sign-in, sign-out, identity, and token policy use cases
+export { classifyLoopbackFailure, deviceLoginOptions, login, resumeLoginOptions, } from "./login.js";
+export { logout } from "./logout.js";
+export { currentIdentity, currentToken } from "./identity.js";
+export { createToken, listTokens, parseExpiresInSeconds, revokeToken, tokenPermissions, validateExpiresInSeconds, MAX_TOKEN_LIFETIME_SECONDS, MIN_TOKEN_LIFETIME_SECONDS, } from "./tokens.js";
+export { hasCredentialsForAll } from "./login-suggestion.js";
+// Environment source for auth policy decisions (default: the process environment)
+export { AuthEnvironment } from "./internal/environment.js";
 export { runPublishAuthorization, } from "./publish-authorization.js";
 export { selectLoginStrategy, } from "./login-strategy.js";
 export { AuthLoginInteraction } from "./login-interaction.js";
 // Auth guard combinator
 export { withAuthGuard } from "./guard.js";
+export { PendingPublishAuthorizationStore, PendingPublishAuthorizationSchema, } from "./pending-publish-authorization-store.js";
 //# sourceMappingURL=index.js.map

package/dist/src/internal/environment.d.ts

@@ -1,16 +1,27 @@
 /**
  * Runtime environment detection for credential policy and login flows.
  *
- * Pure functions for env var / process checks. Effect-based for filesystem
- * checks. Mirrors the shared helpers the extracted kernels carry; a generic
- * utils package is deliberately not created.
+ * Environment values are read through Effect's `ConfigProvider`, whose default
+ * is the process environment. Tests and embedders replace the provider instead
+ * of mutating `process.env`, so no auth policy specification stubs globals.
  */
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as ServiceMap from "effect/Context";
 import * as FileSystem from "effect/FileSystem";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
-/** Read an optional env var. Centralized access point for process.env. */
+/**
+ * The configuration source every auth environment decision reads. Defaults to
+ * the process environment; tests and embedders provide any `ConfigProvider`
+ * — `ConfigProvider.fromEnvRecord({ ... })` — instead of mutating globals.
+ */
+export declare const AuthEnvironment: ServiceMap.Reference<ConfigProvider.ConfigProvider>;
+/**
+ * Read an optional environment value. The single access point: every auth
+ * environment decision resolves through the ambient `ConfigProvider`.
+ */
 export declare const envOption: (name: string) => Effect.Effect<Option.Option<string>>;
-/** Returns true if SSH_CLIENT or SSH_TTY env var is set. */
+/** Returns true if SSH_CLIENT or SSH_TTY is set. */
 export declare const isSSH: Effect.Effect<boolean>;
 /** Returns true if running as root (uid 0). */
 export declare const isRoot: () => boolean;
@@ -20,4 +31,11 @@ export declare const isContainer: Effect.Effect<boolean, never, FileSystem.FileS
 export declare const isWSL: Effect.Effect<boolean, never, FileSystem.FileSystem>;
 /** Returns true if CI env var is set. */
 export declare const isCI: Effect.Effect<boolean>;
+/**
+ * The environment facts login-strategy selection reads. Assembled here so the
+ * strategy decision never touches globals.
+ */
+export declare const loginStrategyEnvironment: Effect.Effect<{
+    [k: string]: string;
+}, never, never>;
 //# sourceMappingURL=environment.d.ts.map

package/dist/src/internal/environment.js

@@ -1,19 +1,53 @@
 /**
  * Runtime environment detection for credential policy and login flows.
  *
- * Pure functions for env var / process checks. Effect-based for filesystem
- * checks. Mirrors the shared helpers the extracted kernels carry; a generic
- * utils package is deliberately not created.
+ * Environment values are read through Effect's `ConfigProvider`, whose default
+ * is the process environment. Tests and embedders replace the provider instead
+ * of mutating `process.env`, so no auth policy specification stubs globals.
  */
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as ServiceMap from "effect/Context";
 import * as FileSystem from "effect/FileSystem";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
-// eslint-disable-next-line no-restricted-properties -- Centralized env var access point; all callers use these helpers
-const readEnv = (name) => process.env[name];
-/** Read an optional env var. Centralized access point for process.env. */
-export const envOption = (name) => Effect.sync(() => Option.fromUndefinedOr(readEnv(name)));
-/** Returns true if SSH_CLIENT or SSH_TTY env var is set. */
-export const isSSH = Effect.sync(() => readEnv("SSH_CLIENT") !== undefined || readEnv("SSH_TTY") !== undefined);
+/**
+ * Reads the live process environment on every lookup. Effect's own
+ * `ConfigProvider` default snapshots the environment the first time any
+ * program reads configuration; auth reads must observe the environment the
+ * invocation actually runs under.
+ */
+const processEnvironmentProvider = ConfigProvider.make((path) => 
+// eslint-disable-next-line no-restricted-properties -- the one process-environment read in registry-auth
+ConfigProvider.fromEnvRecord(process.env).load(path));
+/**
+ * The configuration source every auth environment decision reads. Defaults to
+ * the process environment; tests and embedders provide any `ConfigProvider`
+ * — `ConfigProvider.fromEnvRecord({ ... })` — instead of mutating globals.
+ */
+export const AuthEnvironment = ServiceMap.Reference("@agentxm/registry-auth/AuthEnvironment", {
+    defaultValue: () => processEnvironmentProvider,
+});
+/**
+ * The raw string a provider node carries. A `Record` or `Array` node still
+ * carries the value of the exact key when the environment also defines
+ * longer keys under it (`AXM_TOKEN` beside `AXM_TOKEN_FILE`).
+ */
+const nodeValue = (node) => node === undefined
+    ? Option.none()
+    : node._tag === "Value"
+        ? Option.some(node.value)
+        : Option.fromUndefinedOr(node.value);
+/**
+ * Read an optional environment value. The single access point: every auth
+ * environment decision resolves through the ambient `ConfigProvider`.
+ */
+export const envOption = (name) => Effect.gen(function* () {
+    const provider = yield* AuthEnvironment;
+    const node = yield* provider.load([name]).pipe(Effect.orElseSucceed(() => undefined));
+    return nodeValue(node);
+});
+/** Returns true if SSH_CLIENT or SSH_TTY is set. */
+export const isSSH = Effect.map(Effect.all([envOption("SSH_CLIENT"), envOption("SSH_TTY")]), ([client, tty]) => Option.isSome(client) || Option.isSome(tty));
 /** Returns true if running as root (uid 0). */
 export const isRoot = () => process.getuid?.() === 0;
 /** Returns true if /.dockerenv or /.containerenv exists. Requires FileSystem. */
@@ -42,4 +76,20 @@ export const isWSL = Effect.gen(function* () {
 });
 /** Returns true if CI env var is set. */
 export const isCI = Effect.map(envOption("CI"), (value) => Option.exists(value, (raw) => raw.length > 0 && raw !== "0" && raw.toLowerCase() !== "false"));
+/**
+ * The environment facts login-strategy selection reads. Assembled here so the
+ * strategy decision never touches globals.
+ */
+export const loginStrategyEnvironment = Effect.gen(function* () {
+    const env = yield* Effect.all({
+        SSH_CONNECTION: envOption("SSH_CONNECTION"),
+        SSH_CLIENT: envOption("SSH_CLIENT"),
+        SSH_TTY: envOption("SSH_TTY"),
+        DISPLAY: envOption("DISPLAY"),
+        WAYLAND_DISPLAY: envOption("WAYLAND_DISPLAY"),
+        CI: envOption("CI"),
+        CODESPACES: envOption("CODESPACES"),
+    });
+    return Object.fromEntries(Object.entries(env).flatMap(([key, value]) => Option.isSome(value) ? [[key, value.value]] : []));
+});
 //# sourceMappingURL=environment.js.map

package/dist/src/live.d.ts

@@ -10,4 +10,5 @@ export { AuthMiddlewareLive, makeAuthMiddlewareLive } from "./auth-middleware.js
 export { CredentialStoreLive, CredentialStoreSessionLive } from "./credential-store.js";
 export { AuthLoginInteractionLive } from "./login-interaction.js";
 export { PendingDeviceLoginStoreLive } from "./pending-device-login-store.js";
+export { PendingPublishAuthorizationStoreLive } from "./pending-publish-authorization-store.js";
 //# sourceMappingURL=live.d.ts.map

package/dist/src/live.js

@@ -10,4 +10,5 @@ export { AuthMiddlewareLive, makeAuthMiddlewareLive } from "./auth-middleware.js
 export { CredentialStoreLive, CredentialStoreSessionLive } from "./credential-store.js";
 export { AuthLoginInteractionLive } from "./login-interaction.js";
 export { PendingDeviceLoginStoreLive } from "./pending-device-login-store.js";
+export { PendingPublishAuthorizationStoreLive } from "./pending-publish-authorization-store.js";
 //# sourceMappingURL=live.js.map

package/dist/src/login-presenter.d.ts

@@ -13,6 +13,7 @@ import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as ServiceMap from "effect/Context";
 import type { DeviceLoginPendingResult } from "./device-login.js";
+import type { AuthInteractionAbandoned } from "./errors.js";
 import type { LoginResult } from "./login-output.js";
 export type AuthLoginProgress = {
     readonly _tag: "StartingDeviceAuthorization";
@@ -30,7 +31,42 @@ export type AuthLoginProgress = {
 } | {
     readonly _tag: "CompletingSignIn";
     readonly registryHost: string;
+} | {
+    readonly _tag: "CheckingRegistrySession";
+    readonly registryHost: string;
+} | {
+    readonly _tag: "RevokingRegistrySession";
+    readonly registryHost: string;
+} | {
+    readonly _tag: "ListingRegistryTokens";
+}
+/** A Registry write that the Registry may challenge for human verification. */
+ | {
+    readonly _tag: "RunningVerifiedWrite";
+    readonly operation: string;
+}
+/** The bounded wait while a person completes verification. */
+ | {
+    readonly _tag: "WaitingForHumanVerification";
+    readonly operation: string;
+}
+/** The one retry of the challenged write, after verification. */
+ | {
+    readonly _tag: "RetryingVerifiedWrite";
+    readonly operation: string;
 };
+/** What a person decided about replacing a session that is still valid. */
+export type SessionReplacementDecision = "replace" | "keep";
+/** Why sign-in fell back to the device-code flow. */
+export type DeviceCodeFallbackReason = "remote-or-headless" | "loopback-bind-failed";
+/** One step-up challenge, as a person needs to see it. */
+export interface StepUpChallengePresentation {
+    readonly action: string;
+    readonly target: string;
+    readonly verificationUrl: string;
+    readonly expiresAt: string;
+    readonly browserOpened: boolean;
+}
 export interface DeviceFlowPresentation {
     readonly verificationUri: string;
     readonly verificationUriComplete: string;
@@ -64,6 +100,19 @@ export interface AuthLoginPresenterService {
         readonly candidateCount: number;
         readonly authorizationUrl: string;
     }) => Effect.Effect<void>;
+    /** A still-valid session was found for the selected Registry. */
+    readonly noteExistingSession: (handle: string) => Effect.Effect<void>;
+    /** Stored credentials were rejected, so a new sign-in starts. */
+    readonly noteRejectedStoredCredentials: Effect.Effect<void>;
+    /** Sign-in fell back to the device-code flow for the carried reason. */
+    readonly noteDeviceCodeFallback: (reason: DeviceCodeFallbackReason) => Effect.Effect<void>;
+    /**
+     * Ask whether to replace a session that is still valid. Abandoning the
+     * question fails with `AuthInteractionAbandoned`; declining returns "keep".
+     */
+    readonly confirmSessionReplacement: (message: string) => Effect.Effect<SessionReplacementDecision, AuthInteractionAbandoned>;
+    /** Guidance for one pending step-up verification. */
+    readonly presentStepUpChallenge: (challenge: StepUpChallengePresentation) => Effect.Effect<void>;
 }
 declare const AuthLoginPresenter_base: ServiceMap.ServiceClass<AuthLoginPresenter, "@agentxm/registry-auth/login-presenter/AuthLoginPresenter", AuthLoginPresenterService>;
 export declare class AuthLoginPresenter extends AuthLoginPresenter_base {
@@ -84,9 +133,15 @@ export interface AuthLoginPresenterTestState {
         readonly candidateCount: number;
         readonly authorizationUrl: string;
     }>;
+    readonly existingSessions: Array<string>;
+    readonly rejectedStoredCredentials: Array<true>;
+    readonly deviceCodeFallbacks: Array<DeviceCodeFallbackReason>;
+    readonly sessionReplacementPrompts: Array<string>;
+    readonly stepUpChallenges: Array<StepUpChallengePresentation>;
 }
 export declare const AuthLoginPresenterTest: (overrides?: {
     readonly tryEmitPendingDeviceLogin?: (result: DeviceLoginPendingResult) => Effect.Effect<boolean>;
+    readonly confirmSessionReplacement?: (message: string) => Effect.Effect<SessionReplacementDecision, AuthInteractionAbandoned>;
 }) => {
     layer: Layer.Layer<AuthLoginPresenter, never, never>;
     state: AuthLoginPresenterTestState;

package/dist/src/login-presenter.js

@@ -24,6 +24,11 @@ export const AuthLoginPresenterTest = (overrides) => {
         loopbackStarts: [],
         loopbackBrowserOutcomes: [],
         publishReviews: [],
+        existingSessions: [],
+        rejectedStoredCredentials: [],
+        deviceCodeFallbacks: [],
+        sessionReplacementPrompts: [],
+        stepUpChallenges: [],
     };
     const layer = Layer.succeed(AuthLoginPresenter, {
         withProgress: (progress, run) => Effect.suspend(() => {
@@ -52,6 +57,23 @@ export const AuthLoginPresenterTest = (overrides) => {
         notePublishReview: (review) => Effect.sync(() => {
             state.publishReviews.push(review);
         }),
+        noteExistingSession: (handle) => Effect.sync(() => {
+            state.existingSessions.push(handle);
+        }),
+        noteRejectedStoredCredentials: Effect.sync(() => {
+            state.rejectedStoredCredentials.push(true);
+        }),
+        noteDeviceCodeFallback: (reason) => Effect.sync(() => {
+            state.deviceCodeFallbacks.push(reason);
+        }),
+        confirmSessionReplacement: (message) => Effect.gen(function* () {
+            state.sessionReplacementPrompts.push(message);
+            return yield* overrides?.confirmSessionReplacement?.(message) ??
+                Effect.succeed("replace");
+        }),
+        presentStepUpChallenge: (challenge) => Effect.sync(() => {
+            state.stepUpChallenges.push(challenge);
+        }),
     });
     return { layer, state };
 };

package/dist/src/login-suggestion.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Offline credential-presence probe.
+ *
+ * Answers "could this invocation be missing a private item because it is not
+ * signed in to that origin?" without contacting any Registry. A successful
+ * ambient or stored token suppresses the hint even when that identity cannot
+ * see the requested item.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { CredentialStore } from "./credential-store.js";
+/**
+ * Whether every remote origin among `locations` already has a credential this
+ * invocation would present. False when at least one does not.
+ */
+export declare const hasCredentialsForAll: (locations: ReadonlyArray<string>, defaultRegistryUrl: string) => Effect.Effect<boolean, never, CredentialStore>;
+//# sourceMappingURL=login-suggestion.d.ts.map

package/dist/src/login-suggestion.js

@@ -0,0 +1,34 @@
+/**
+ * Offline credential-presence probe.
+ *
+ * Answers "could this invocation be missing a private item because it is not
+ * signed in to that origin?" without contacting any Registry. A successful
+ * ambient or stored token suppresses the hint even when that identity cannot
+ * see the requested item.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { CredentialStore } from "./credential-store.js";
+import { resolveRequestToken } from "./token-resolution.js";
+const remoteOrigins = (locations) => {
+    const origins = new Set();
+    for (const location of locations) {
+        try {
+            const url = new URL(location);
+            if (url.protocol === "http:" || url.protocol === "https:")
+                origins.add(url.origin);
+        }
+        catch {
+            // Invalid source locations are reported by their owning resolution path.
+        }
+    }
+    return [...origins];
+};
+/**
+ * Whether every remote origin among `locations` already has a credential this
+ * invocation would present. False when at least one does not.
+ */
+export const hasCredentialsForAll = (locations, defaultRegistryUrl) => Effect.forEach(remoteOrigins(locations), (origin) => resolveRequestToken(origin, defaultRegistryUrl).pipe(Effect.map(Option.isSome), Effect.catch(() => Effect.succeed(false)))).pipe(Effect.map((present) => present.every((hasCredential) => hasCredential)));
+//# sourceMappingURL=login-suggestion.js.map

package/dist/src/login.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Sign-in orchestration: flag coherence, persisted-credential policy, the
+ * existing-session decision, strategy selection, and the loopback →
+ * device-code fallback chain.
+ *
+ * The capability decides; the application supplies presentation through
+ * `AuthLoginPresenter` and platform integration through
+ * `AuthLoginInteraction`. No sign-in decision is taken outside this module.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { AuthClient } from "./auth-client.js";
+import { CredentialStore } from "./credential-store.js";
+import { type RunDeviceLoginOptions } from "./device-login.js";
+import { RegistryAuthFailed } from "./errors.js";
+import type { LoopbackCallbackRejected, LoopbackLoginFallback } from "./loopback-server.js";
+import { AuthLoginPresenter } from "./login-presenter.js";
+/** The invocation's sign-in inputs, parsed from the command line. */
+export interface LoginRequest {
+    /** Preapproval: start a new sign-in without asking about a valid session. */
+    readonly yes: boolean;
+    readonly deviceCode: boolean;
+    readonly restart: boolean;
+    /** Resume and wait for a pending device sign-in instead of starting one. */
+    readonly wait: boolean;
+    readonly timeoutSeconds?: number;
+    readonly scopes: ReadonlyArray<string>;
+    /** No terminal is available to run a sign-in flow interactively. */
+    readonly nonInteractive: boolean;
+    /** The invocation reports through a machine document rather than prose. */
+    readonly machineOutput: boolean;
+}
+/** What one `login` invocation settled on. */
+export type LoginOutcome = 
+/** A valid session was found and kept; nothing was written. */
+{
+    readonly _tag: "SessionRetained";
+    readonly registryHost: string;
+    readonly handle: string;
+}
+/** A sign-in flow ran; the presenter reported its result. */
+ | {
+    readonly _tag: "SignInAttempted";
+}
+/** A pending device sign-in was resumed. */
+ | {
+    readonly _tag: "PendingSignInResumed";
+};
+/**
+ * The device-login options one sign-in request means. Exported so the option
+ * shaping is provable without substituting the flow it is handed to.
+ */
+export declare const deviceLoginOptions: (request: Pick<LoginRequest, "restart" | "scopes">, openBrowser: boolean) => RunDeviceLoginOptions;
+/** The resume options one `--wait` request means. */
+export declare const resumeLoginOptions: (request: Pick<LoginRequest, "timeoutSeconds">) => {
+    readonly timeoutSeconds?: number;
+};
+/**
+ * How a loopback sign-in that could not complete is classified.
+ *
+ * A failed bind is recoverable — device-code sign-in replaces it — while an
+ * expired wait or a rejected callback is terminal and leaves credentials
+ * untouched.
+ */
+export declare const classifyLoopbackFailure: (error: LoopbackLoginFallback | LoopbackCallbackRejected) => RegistryAuthFailed;
+export declare const login: (request: LoginRequest, registryUrl: string) => Effect.Effect<{
+    readonly _tag: "PendingSignInResumed";
+    readonly registryHost?: never;
+    readonly handle?: never;
+} | {
+    readonly _tag: "SessionRetained";
+    readonly registryHost: string;
+    readonly handle: string & import("effect/Brand").Brand<"Handle">;
+} | {
+    readonly _tag: "SignInAttempted";
+    readonly registryHost?: never;
+    readonly handle?: never;
+}, RegistryAuthFailed | import("./errors.js").AuthLoginRequired | import("./errors.js").AuthTokenPolicyRequired | import("./errors.js").DeviceLoginDenied | import("./errors.js").DeviceLoginCodeExpired | import("./errors.js").DeviceAuthorizationPending | import("./errors.js").StepUpRequired | import("@agentxm/registry-client").RegistryProblem | import("@agentxm/registry-client").RegistryRequestFailed | import("@agentxm/registry-client").RegistryOperationFailed | import("./errors.js").AuthExchangeFailed | import("./errors.js").PublishAuthorizationPending | import("./errors.js").StepUpVerificationPending | import("./errors.js").AuthInteractionAbandoned, AuthClient | CredentialStore | AuthLoginPresenter | import("./pending-device-login-store.ts").PendingDeviceLoginStore | import("./device-login.js").DeviceLoginInteraction>;
+//# sourceMappingURL=login.d.ts.map