@agentxm/registry-auth 0.28.4-bootstrap.0

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

@@ -0,0 +1,114 @@
+/**
+ * Shared device-code login flow for auth commands and guards.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as ServiceMap from "effect/Context";
+import * as Layer from "effect/Layer";
+import { DeviceAuthorizationPending, RegistryAuthFailed } from "./errors.js";
+import { AuthClient } from "./auth-client.js";
+import { CredentialStore } from "./credential-store.js";
+import { AuthLoginPresenter } from "./login-presenter.js";
+import { PendingDeviceLoginStore } from "./pending-device-login-store.js";
+export interface DeviceLoginInteractionService {
+    readonly openBrowser: (url: string) => Effect.Effect<boolean>;
+    readonly copyToClipboard: (text: string) => Effect.Effect<boolean>;
+}
+declare const DeviceLoginInteraction_base: ServiceMap.ServiceClass<DeviceLoginInteraction, "@agentxm/registry-auth/device-login/DeviceLoginInteraction", DeviceLoginInteractionService>;
+export declare class DeviceLoginInteraction extends DeviceLoginInteraction_base {
+}
+export interface DeviceLoginInteractionTestState {
+    readonly openBrowserCalls: Array<string>;
+    readonly copyToClipboardCalls: Array<string>;
+}
+export declare const DeviceLoginInteractionTest: (overrides?: {
+    readonly openBrowser?: (url: string) => Effect.Effect<boolean>;
+    readonly copyToClipboard?: (text: string) => Effect.Effect<boolean>;
+}) => {
+    layer: Layer.Layer<DeviceLoginInteraction, never, never>;
+    state: DeviceLoginInteractionTestState;
+};
+export interface RunDeviceLoginOptions {
+    readonly emitPendingResult?: boolean;
+    readonly openBrowser?: boolean;
+    readonly restart?: boolean;
+    readonly scopes?: ReadonlyArray<string>;
+}
+export interface ResumeDeviceLoginOptions {
+    readonly timeoutSeconds?: number;
+}
+export declare const DeviceLoginPendingResultSchema: Schema.Struct<{
+    readonly status: Schema.Literal<"pending-human">;
+    readonly blockedOn: Schema.Literal<"human">;
+    readonly retryable: Schema.Literal<true>;
+    readonly flow: Schema.Literals<readonly ["started", "re-emitted"]>;
+    readonly registryHost: Schema.String;
+    readonly verificationUri: Schema.String;
+    readonly verificationUriComplete: Schema.String;
+    readonly requestedScopes: Schema.$Array<Schema.String>;
+    readonly userCode: Schema.String;
+    readonly expiresAt: Schema.String;
+    readonly interval: Schema.Number;
+    readonly resume: Schema.String;
+    readonly action: Schema.Struct<{
+        readonly kind: Schema.Literal<"open-url">;
+        readonly url: Schema.String;
+        readonly fallbackUrl: Schema.String;
+        readonly code: Schema.String;
+        readonly expiresAt: Schema.String;
+        readonly resume: Schema.String;
+    }>;
+}>;
+export type DeviceLoginPendingResult = typeof DeviceLoginPendingResultSchema.Type;
+export declare const DeviceLoginPendingDocumentSchema: Schema.Struct<{
+    readonly result: Schema.Struct<{
+        readonly status: Schema.Literal<"pending-human">;
+        readonly blockedOn: Schema.Literal<"human">;
+        readonly retryable: Schema.Literal<true>;
+        readonly flow: Schema.Literals<readonly ["started", "re-emitted"]>;
+        readonly registryHost: Schema.String;
+        readonly verificationUri: Schema.String;
+        readonly verificationUriComplete: Schema.String;
+        readonly requestedScopes: Schema.$Array<Schema.String>;
+        readonly userCode: Schema.String;
+        readonly expiresAt: Schema.String;
+        readonly interval: Schema.Number;
+        readonly resume: Schema.String;
+        readonly action: Schema.Struct<{
+            readonly kind: Schema.Literal<"open-url">;
+            readonly url: Schema.String;
+            readonly fallbackUrl: Schema.String;
+            readonly code: Schema.String;
+            readonly expiresAt: Schema.String;
+            readonly resume: Schema.String;
+        }>;
+    }>;
+}>;
+export declare const initiateDeviceLogin: (registryUrl: string, options?: RunDeviceLoginOptions) => Effect.Effect<{
+    readonly status: "pending-human";
+    readonly blockedOn: "human";
+    readonly retryable: true;
+    readonly flow: "started" | "re-emitted";
+    readonly registryHost: string;
+    readonly verificationUri: string;
+    readonly verificationUriComplete: string;
+    readonly requestedScopes: readonly string[];
+    readonly userCode: string;
+    readonly expiresAt: string;
+    readonly interval: number;
+    readonly resume: string;
+    readonly action: {
+        readonly kind: "open-url";
+        readonly url: string;
+        readonly fallbackUrl: string;
+        readonly code: string;
+        readonly expiresAt: string;
+        readonly resume: string;
+    };
+}, import("./errors.js").AuthError, AuthClient | CredentialStore | AuthLoginPresenter | PendingDeviceLoginStore | DeviceLoginInteraction>;
+export declare const resumeDeviceLogin: (registryUrl: string, options?: ResumeDeviceLoginOptions) => Effect.Effect<undefined, RegistryAuthFailed | import("./errors.js").AuthLoginRequired | import("./errors.js").AuthTokenPolicyRequired | DeviceAuthorizationPending | import("./errors.js").StepUpRequired | import("@agentxm/registry-client").RegistryClientFailure | import("./errors.js").AuthExchangeFailed, AuthClient | CredentialStore | AuthLoginPresenter | PendingDeviceLoginStore>;
+export declare const runDeviceLogin: (registryUrl: string, options?: RunDeviceLoginOptions) => Effect.Effect<void, RegistryAuthFailed | import("./errors.js").AuthLoginRequired | import("./errors.js").AuthTokenPolicyRequired | import("./errors.js").DeviceLoginDenied | import("./errors.js").DeviceLoginCodeExpired | DeviceAuthorizationPending | import("./errors.js").StepUpRequired | import("@agentxm/registry-client").RegistryProblem | import("@agentxm/registry-client").RegistryRequestFailed | import("@agentxm/registry-client").RegistryOperationFailed | import("./errors.js").AuthExchangeFailed, AuthClient | CredentialStore | AuthLoginPresenter | PendingDeviceLoginStore | DeviceLoginInteraction>;
+export {};
+//# sourceMappingURL=device-login.d.ts.map

package/dist/src/device-login.js

@@ -0,0 +1,300 @@
+/**
+ * Shared device-code login flow for auth commands and guards.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as ServiceMap from "effect/Context";
+import * as Layer from "effect/Layer";
+import { normalizeHandle } from "@agentxm/extension-model/unstable/extensions/handle";
+import { DeviceAuthorizationPending, RegistryAuthFailed } from "./errors.js";
+import { AuthClient, normalizeRequestedLoginScopes } from "./auth-client.js";
+import { CredentialStore, makePersistedCredentialsUnsupportedError } from "./credential-store.js";
+import { emitLoginSuccess } from "./login-output.js";
+import { AuthLoginPresenter } from "./login-presenter.js";
+import { PendingDeviceLoginStore } from "./pending-device-login-store.js";
+export class DeviceLoginInteraction extends ServiceMap.Service()("@agentxm/registry-auth/device-login/DeviceLoginInteraction") {
+}
+export const DeviceLoginInteractionTest = (overrides) => {
+    const state = {
+        openBrowserCalls: [],
+        copyToClipboardCalls: [],
+    };
+    const layer = Layer.succeed(DeviceLoginInteraction, {
+        openBrowser: (url) => Effect.gen(function* () {
+            state.openBrowserCalls.push(url);
+            return yield* overrides?.openBrowser?.(url) ?? Effect.succeed(false);
+        }),
+        copyToClipboard: (text) => Effect.gen(function* () {
+            state.copyToClipboardCalls.push(text);
+            return yield* overrides?.copyToClipboard?.(text) ?? Effect.succeed(false);
+        }),
+    });
+    return { layer, state };
+};
+// -----------------------------------------------------------------------------
+// Device login orchestration
+// -----------------------------------------------------------------------------
+const UNKNOWN_HANDLE = normalizeHandle("@unknown");
+const persistLoginCredentials = (registryUrl, token) => Effect.gen(function* () {
+    const authClient = yield* AuthClient;
+    const credStore = yield* CredentialStore;
+    const meResult = yield* authClient
+        .getMe(token.access_token)
+        .pipe(Effect.retry({ times: 1 }), Effect.option);
+    const handle = Option.match(meResult, {
+        onNone: () => UNKNOWN_HANDLE,
+        onSome: (me) => me.userHandle,
+    });
+    yield* credStore.save(registryUrl, handle, {
+        access_token: token.access_token,
+        refresh_token: token.refresh_token,
+        expires_at: token.expires_at,
+    });
+    return Option.map(meResult, (me) => me.userHandle);
+});
+const DeviceLoginActionSchema = Schema.Struct({
+    kind: Schema.Literal("open-url"),
+    url: Schema.String,
+    fallbackUrl: Schema.String,
+    code: Schema.String,
+    expiresAt: Schema.String,
+    resume: Schema.String,
+});
+export const DeviceLoginPendingResultSchema = Schema.Struct({
+    status: Schema.Literal("pending-human"),
+    blockedOn: Schema.Literal("human"),
+    retryable: Schema.Literal(true),
+    flow: Schema.Literals(["started", "re-emitted"]),
+    registryHost: Schema.String,
+    verificationUri: Schema.String,
+    verificationUriComplete: Schema.String,
+    requestedScopes: Schema.Array(Schema.String),
+    userCode: Schema.String,
+    expiresAt: Schema.String,
+    interval: Schema.Number,
+    resume: Schema.String,
+    action: DeviceLoginActionSchema,
+});
+export const DeviceLoginPendingDocumentSchema = Schema.Struct({
+    result: DeviceLoginPendingResultSchema,
+});
+const presentDeviceFlow = (verificationUri, verificationUriComplete, userCode, expiresInSeconds, options) => Effect.gen(function* () {
+    const presenter = yield* AuthLoginPresenter;
+    const interaction = yield* DeviceLoginInteraction;
+    const shouldOpenBrowser = options.openBrowser ?? true;
+    const copiedToClipboard = yield* interaction.copyToClipboard(userCode);
+    const browserOpened = shouldOpenBrowser
+        ? yield* interaction.openBrowser(verificationUriComplete)
+        : false;
+    yield* presenter.presentDeviceFlow({
+        verificationUri,
+        verificationUriComplete,
+        userCode,
+        expiresInSeconds,
+        browserOpened,
+        copiedToClipboard,
+    });
+});
+const makePendingResult = (pending, flow = "started") => {
+    const registryHost = new URL(pending.registryUrl).host;
+    const expiresAt = DateTime.formatIso(pending.expiresAt);
+    const resume = "axm login --wait --json";
+    return {
+        status: "pending-human",
+        blockedOn: "human",
+        retryable: true,
+        flow,
+        registryHost,
+        verificationUri: pending.verificationUri,
+        verificationUriComplete: pending.verificationUriComplete,
+        requestedScopes: pending.requestedScopes,
+        userCode: pending.userCode,
+        expiresAt,
+        interval: pending.interval,
+        resume,
+        action: {
+            kind: "open-url",
+            url: pending.verificationUriComplete,
+            fallbackUrl: pending.verificationUri,
+            code: pending.userCode,
+            expiresAt,
+            resume,
+        },
+    };
+};
+const emitPendingDeviceLogin = (pending, options, flow = "started") => Effect.gen(function* () {
+    const presenter = yield* AuthLoginPresenter;
+    const result = makePendingResult(pending, flow);
+    // Machine mode consumes the pending document; browser/clipboard side
+    // effects and human presentation must not run afterwards.
+    if (yield* presenter.tryEmitPendingDeviceLogin(result)) {
+        return result;
+    }
+    yield* presentDeviceFlow(pending.verificationUri, pending.verificationUriComplete, pending.userCode, Math.max(0, Math.ceil((DateTime.toEpochMillis(pending.expiresAt) -
+        DateTime.toEpochMillis(yield* DateTime.now)) /
+        1000)), options);
+    yield* presenter.notePendingApproval(result);
+    return result;
+});
+export const initiateDeviceLogin = (registryUrl, options = {}) => Effect.gen(function* () {
+    const authClient = yield* AuthClient;
+    const credStore = yield* CredentialStore;
+    const pendingStore = yield* PendingDeviceLoginStore;
+    const presenter = yield* AuthLoginPresenter;
+    const registryHost = new URL(registryUrl).host;
+    const requestedScopes = normalizeRequestedLoginScopes(options.scopes);
+    if (!credStore.allowsPersistedCredentials) {
+        return yield* makePersistedCredentialsUnsupportedError();
+    }
+    const existing = yield* pendingStore.load();
+    if (Option.isSome(existing)) {
+        const expired = yield* DateTime.isPast(existing.value.expiresAt);
+        if (expired || options.restart === true) {
+            yield* pendingStore.clear();
+        }
+        else if (existing.value.registryUrl === registryUrl &&
+            existing.value.requestedScopes.length === requestedScopes.length &&
+            existing.value.requestedScopes.every((scope, index) => scope === requestedScopes[index])) {
+            return yield* emitPendingDeviceLogin(existing.value, options, "re-emitted");
+        }
+        else {
+            return yield* new RegistryAuthFailed({
+                category: "conflict",
+                detail: existing.value.registryUrl === registryUrl
+                    ? `A device sign-in for ${registryHost} is already pending with a different scope set.`
+                    : `A device sign-in for ${new URL(existing.value.registryUrl).host} is already pending.`,
+                suggestions: [
+                    {
+                        description: "Finish the pending sign-in before starting another.",
+                        cmd: "axm login --wait --json",
+                    },
+                    {
+                        description: "Replace the pending sign-in intentionally.",
+                        cmd: "axm login --device-code --restart --json",
+                    },
+                ],
+            });
+        }
+    }
+    const deviceFlow = yield* presenter.withProgress({ _tag: "StartingDeviceAuthorization", registryHost }, () => authClient.initiateDeviceFlow({ scopes: requestedScopes }));
+    const pending = {
+        version: 2,
+        registryUrl,
+        deviceCode: deviceFlow.device_code,
+        userCode: deviceFlow.user_code,
+        verificationUri: deviceFlow.verification_uri,
+        verificationUriComplete: deviceFlow.verification_uri_complete,
+        requestedScopes,
+        interval: deviceFlow.interval,
+        expiresAt: DateTime.add(yield* DateTime.now, { seconds: deviceFlow.expires_in }),
+    };
+    yield* pendingStore.save(pending);
+    if (options.emitPendingResult === false) {
+        yield* presentDeviceFlow(pending.verificationUri, pending.verificationUriComplete, pending.userCode, deviceFlow.expires_in, options);
+        return makePendingResult(pending);
+    }
+    return yield* emitPendingDeviceLogin(pending, options);
+});
+const pendingLoginNotFound = () => new RegistryAuthFailed({
+    category: "not_found",
+    detail: "No pending device sign-in was found.",
+    suggestions: [
+        {
+            description: "Start a device sign-in first.",
+            cmd: "axm login --device-code --json",
+        },
+    ],
+});
+export const resumeDeviceLogin = (registryUrl, options = {}) => Effect.gen(function* () {
+    const authClient = yield* AuthClient;
+    const credStore = yield* CredentialStore;
+    const pendingStore = yield* PendingDeviceLoginStore;
+    const presenter = yield* AuthLoginPresenter;
+    const registryHost = new URL(registryUrl).host;
+    if (!credStore.allowsPersistedCredentials) {
+        return yield* makePersistedCredentialsUnsupportedError();
+    }
+    const loaded = yield* pendingStore.load();
+    if (Option.isNone(loaded))
+        return yield* pendingLoginNotFound();
+    const pending = loaded.value;
+    if (pending.registryUrl !== registryUrl) {
+        return yield* new RegistryAuthFailed({
+            category: "conflict",
+            detail: `The pending sign-in belongs to ${new URL(pending.registryUrl).host}, not ${registryHost}.`,
+            suggestions: [
+                {
+                    description: "Resume with the registry that started the sign-in.",
+                    cmd: "axm login --wait --registry <url> --json",
+                },
+            ],
+        });
+    }
+    if (yield* DateTime.isPast(pending.expiresAt)) {
+        yield* pendingStore.clear();
+        return yield* new RegistryAuthFailed({
+            category: "auth_expired",
+            detail: "The pending device sign-in expired. No credentials were changed.",
+            suggestions: [
+                {
+                    description: "Request a new device sign-in code.",
+                    cmd: "axm login --device-code --json",
+                },
+            ],
+        });
+    }
+    const polling = authClient.pollDeviceToken(pending.deviceCode, pending.interval);
+    const boundedPolling = options.timeoutSeconds === undefined
+        ? polling
+        : polling.pipe(Effect.timeoutOrElse({
+            duration: Duration.seconds(options.timeoutSeconds),
+            orElse: () => {
+                const timeoutSeconds = options.timeoutSeconds ?? 0;
+                const action = makePendingResult(pending).action;
+                return Effect.fail(new DeviceAuthorizationPending({
+                    timeoutSeconds,
+                    verificationUri: action.fallbackUrl,
+                    verificationUriComplete: action.url,
+                    userCode: action.code,
+                    expiresAt: action.expiresAt,
+                    resume: action.resume,
+                }));
+            },
+        }));
+    const token = yield* presenter
+        .withProgress({ _tag: "WaitingForDeviceAuthorization", registryHost }, () => boundedPolling)
+        .pipe(Effect.catchTag("DeviceLoginCodeExpired", (error) => pendingStore.clear().pipe(Effect.flatMap(() => Effect.fail(new RegistryAuthFailed({
+        category: "auth_expired",
+        detail: "The pending device sign-in expired. No credentials were changed.",
+        suggestions: [
+            {
+                description: "Request a new device sign-in code.",
+                cmd: "axm login --device-code --json",
+            },
+        ],
+        cause: error,
+    }))))), Effect.catchTag("DeviceLoginDenied", (error) => pendingStore.clear().pipe(Effect.flatMap(() => Effect.fail(new RegistryAuthFailed({
+        category: "auth_denied",
+        detail: "Device sign-in was denied or cancelled. No credentials were changed.",
+        suggestions: [
+            {
+                description: "Start a new device sign-in when ready.",
+                cmd: "axm login --device-code --json",
+            },
+        ],
+        cause: error,
+    }))))));
+    yield* pendingStore.clear();
+    const handle = yield* presenter.withProgress({ _tag: "SavingCredentials", registryHost }, () => persistLoginCredentials(registryUrl, token));
+    yield* emitLoginSuccess(registryUrl, handle);
+});
+export const runDeviceLogin = (registryUrl, options = {}) => Effect.gen(function* () {
+    yield* initiateDeviceLogin(registryUrl, { ...options, emitPendingResult: false });
+    yield* resumeDeviceLogin(registryUrl);
+});
+//# sourceMappingURL=device-login.js.map

package/dist/src/errors.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Typed failures for the registry-auth feature. The producer owns the
+ * category choice and user-facing wording; the application boundary converts
+ * the carried fields into its error envelope verbatim. Failures that carry a
+ * registry transport failure keep it intact so the boundary can restore the
+ * exact evidence, metadata, and semantics the former in-place conversion
+ * produced.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import { type RegistryClientFailure } from "@agentxm/registry-client";
+import type { SuggestedAction } from "@agentxm/registry-protocol/unstable/suggested-action";
+/** Every category a registry-auth failure can carry. Identical strings to the CLI error codes. */
+export declare const REGISTRY_AUTH_ERROR_CATEGORIES: readonly ["auth", "auth_denied", "auth_expired", "conflict", "internal", "not_found", "validation"];
+export type RegistryAuthErrorCategory = (typeof REGISTRY_AUTH_ERROR_CATEGORIES)[number];
+declare const RegistryAuthFailed_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "RegistryAuthFailed";
+} & Readonly<A>;
+/**
+ * An auth policy step could not proceed. The carried fields mirror the
+ * application error envelope's inputs 1:1: `category` selects the code,
+ * `recover`/`cmd` fold into the leading suggested action, and `detail`,
+ * `suggestions`, and `cause` carry over verbatim.
+ */
+export declare class RegistryAuthFailed extends RegistryAuthFailed_base<{
+    readonly category: RegistryAuthErrorCategory;
+    readonly detail: string;
+    readonly recover?: string;
+    readonly cmd?: string;
+    readonly suggestions?: ReadonlyArray<SuggestedAction>;
+    readonly cause?: unknown;
+}> {
+}
+declare const AuthLoginRequired_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "AuthLoginRequired";
+} & Readonly<A>;
+/**
+ * Sign-in is required and a person must approve it. The boundary renders the
+ * fixed device-flow and token-creation guidance; the producer chooses only
+ * the leading message.
+ */
+export declare class AuthLoginRequired extends AuthLoginRequired_base<{
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+export declare const authLoginRequired: (message?: string, cause?: unknown) => AuthLoginRequired;
+declare const AuthTokenPolicyRequired_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "AuthTokenPolicyRequired";
+} & Readonly<A>;
+/**
+ * Persisted credentials are unavailable by policy (for example in CI), so an
+ * ambient token is the only accepted authentication. The boundary renders the
+ * fixed AXM_TOKEN_FILE / token-creation guidance.
+ */
+export declare class AuthTokenPolicyRequired extends AuthTokenPolicyRequired_base<{
+    readonly cause?: unknown;
+}> {
+}
+declare const DeviceLoginDenied_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "DeviceLoginDenied";
+} & Readonly<A>;
+/** The device authorization was denied or cancelled by the person approving it. */
+export declare class DeviceLoginDenied extends DeviceLoginDenied_base {
+}
+declare const DeviceLoginCodeExpired_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "DeviceLoginCodeExpired";
+} & Readonly<A>;
+/** The device authorization code expired before the person approved it. */
+export declare class DeviceLoginCodeExpired extends DeviceLoginCodeExpired_base {
+}
+declare const DeviceAuthorizationPending_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "DeviceAuthorizationPending";
+} & Readonly<A>;
+/**
+ * A bounded wait for device approval elapsed while the pending flow is still
+ * valid. Carries every fact the boundary needs to render the pending-human
+ * envelope: status, blocked-on semantics, the open-url action with fallback
+ * and one-time code, and the resume command.
+ */
+export declare class DeviceAuthorizationPending extends DeviceAuthorizationPending_base<{
+    readonly timeoutSeconds: number;
+    readonly verificationUri: string;
+    readonly verificationUriComplete: string;
+    readonly userCode: string;
+    /** ISO timestamp at which the pending device authorization expires. */
+    readonly expiresAt: string;
+    /** Exact command that resumes the pending sign-in. */
+    readonly resume: string;
+}> {
+}
+/** One step-up verification request as the registry described it on the wire. */
+export interface StepUpRequest {
+    readonly requestId: string;
+    readonly verificationUrl: string;
+    readonly statusUrl: string;
+    readonly expiresAt: string;
+    readonly intervalSeconds: number;
+    readonly maxAgeSeconds?: number;
+    readonly action: string;
+    readonly target: string;
+}
+declare const StepUpRequired_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "StepUpRequired";
+} & Readonly<A>;
+/**
+ * The registry demands step-up verification by a person before the operation
+ * can proceed. Carries the parsed step-up request and the underlying
+ * transport failure so the boundary reproduces the exact metadata and cause
+ * evidence.
+ */
+export declare class StepUpRequired extends StepUpRequired_base<{
+    readonly stepUp: StepUpRequest;
+    readonly failure: RegistryClientFailure;
+}> {
+}
+declare const AuthExchangeFailed_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "AuthExchangeFailed";
+} & Readonly<A>;
+/**
+ * A token-exchange endpoint failed and the flow assigns it auth semantics:
+ * the boundary overlays the carried detail and suggestions onto the mapped
+ * transport failure exactly as the former in-place conversion did.
+ */
+export declare class AuthExchangeFailed extends AuthExchangeFailed_base<{
+    readonly detail: string;
+    readonly suggestions?: ReadonlyArray<SuggestedAction>;
+    readonly failure: RegistryClientFailure;
+}> {
+}
+/** Every typed failure the registry-auth feature constructs. */
+export type RegistryAuthFailure = RegistryAuthFailed | AuthLoginRequired | AuthTokenPolicyRequired | DeviceLoginDenied | DeviceLoginCodeExpired | DeviceAuthorizationPending | StepUpRequired | AuthExchangeFailed;
+export declare const isRegistryAuthFailure: (error: unknown) => error is RegistryAuthFailure;
+/**
+ * Every failure a registry-auth use case can surface: the feature's own typed
+ * failures plus registry transport failures propagated unwrapped.
+ */
+export type AuthError = RegistryAuthFailure | RegistryClientFailure;
+export declare const isAuthError: (error: unknown) => error is AuthError;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/errors.js

@@ -0,0 +1,84 @@
+/**
+ * Typed failures for the registry-auth feature. The producer owns the
+ * category choice and user-facing wording; the application boundary converts
+ * the carried fields into its error envelope verbatim. Failures that carry a
+ * registry transport failure keep it intact so the boundary can restore the
+ * exact evidence, metadata, and semantics the former in-place conversion
+ * produced.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Data from "effect/Data";
+import { isRegistryClientFailure } from "@agentxm/registry-client";
+/** Every category a registry-auth failure can carry. Identical strings to the CLI error codes. */
+export const REGISTRY_AUTH_ERROR_CATEGORIES = [
+    "auth",
+    "auth_denied",
+    "auth_expired",
+    "conflict",
+    "internal",
+    "not_found",
+    "validation",
+];
+/**
+ * An auth policy step could not proceed. The carried fields mirror the
+ * application error envelope's inputs 1:1: `category` selects the code,
+ * `recover`/`cmd` fold into the leading suggested action, and `detail`,
+ * `suggestions`, and `cause` carry over verbatim.
+ */
+export class RegistryAuthFailed extends Data.TaggedError("RegistryAuthFailed") {
+}
+/**
+ * Sign-in is required and a person must approve it. The boundary renders the
+ * fixed device-flow and token-creation guidance; the producer chooses only
+ * the leading message.
+ */
+export class AuthLoginRequired extends Data.TaggedError("AuthLoginRequired") {
+}
+export const authLoginRequired = (message = "Authentication required", cause) => new AuthLoginRequired({ message, ...(cause === undefined ? {} : { cause }) });
+/**
+ * Persisted credentials are unavailable by policy (for example in CI), so an
+ * ambient token is the only accepted authentication. The boundary renders the
+ * fixed AXM_TOKEN_FILE / token-creation guidance.
+ */
+export class AuthTokenPolicyRequired extends Data.TaggedError("AuthTokenPolicyRequired") {
+}
+/** The device authorization was denied or cancelled by the person approving it. */
+export class DeviceLoginDenied extends Data.TaggedError("DeviceLoginDenied") {
+}
+/** The device authorization code expired before the person approved it. */
+export class DeviceLoginCodeExpired extends Data.TaggedError("DeviceLoginCodeExpired") {
+}
+/**
+ * A bounded wait for device approval elapsed while the pending flow is still
+ * valid. Carries every fact the boundary needs to render the pending-human
+ * envelope: status, blocked-on semantics, the open-url action with fallback
+ * and one-time code, and the resume command.
+ */
+export class DeviceAuthorizationPending extends Data.TaggedError("DeviceAuthorizationPending") {
+}
+/**
+ * The registry demands step-up verification by a person before the operation
+ * can proceed. Carries the parsed step-up request and the underlying
+ * transport failure so the boundary reproduces the exact metadata and cause
+ * evidence.
+ */
+export class StepUpRequired extends Data.TaggedError("StepUpRequired") {
+}
+/**
+ * A token-exchange endpoint failed and the flow assigns it auth semantics:
+ * the boundary overlays the carried detail and suggestions onto the mapped
+ * transport failure exactly as the former in-place conversion did.
+ */
+export class AuthExchangeFailed extends Data.TaggedError("AuthExchangeFailed") {
+}
+export const isRegistryAuthFailure = (error) => error instanceof RegistryAuthFailed ||
+    error instanceof AuthLoginRequired ||
+    error instanceof AuthTokenPolicyRequired ||
+    error instanceof DeviceLoginDenied ||
+    error instanceof DeviceLoginCodeExpired ||
+    error instanceof DeviceAuthorizationPending ||
+    error instanceof StepUpRequired ||
+    error instanceof AuthExchangeFailed;
+export const isAuthError = (error) => isRegistryAuthFailure(error) || isRegistryClientFailure(error);
+//# sourceMappingURL=errors.js.map

package/dist/src/guard.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Auth guard combinator for commands that require authentication.
+ *
+ * Wraps an Effect with a pre-check for authentication. If no token is
+ * resolvable, fails immediately with an actionable error message directing
+ * the user to `axm login`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { RegistryUrl } from "@agentxm/registry-client";
+import { type AuthError } from "./errors.js";
+import { CredentialStore } from "./credential-store.js";
+/**
+ * Wraps an Effect with an auth guard.
+ *
+ * - If the target registry is local, runs the inner effect directly.
+ * - If a token is already resolvable, runs the inner effect directly.
+ * - If no token: fails with `AUTH_LOGIN_REQUIRED`.
+ */
+export declare const withAuthGuard: <A, E, R>(effect: Effect.Effect<A, E | AuthError, R>, options?: {
+    registryUrl?: string;
+}) => Effect.Effect<A, AuthError | E, RegistryUrl | CredentialStore | R>;
+//# sourceMappingURL=guard.d.ts.map