@agentxm/registry-auth 0.28.12 → 0.28.13

package/dist/src/step-up.js

@@ -0,0 +1,174 @@
+/**
+ * Step-up verification: the protocol that carries one challenged Registry
+ * write through human verification and retries it exactly once.
+ *
+ * The capability owns challenge detection, request-reference validation,
+ * resumption and terminal-status rules, expiry, the bounded wait, and the
+ * retry-once contract. The application supplies only presentation and browser
+ * launch through the login presenter and interaction ports.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Clock from "effect/Clock";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import { isRegistryClientFailure } from "@agentxm/registry-client";
+import { AuthClient, readStepUpRequest } from "./auth-client.js";
+import { CredentialStore } from "./credential-store.js";
+import { authLoginRequired, RegistryAuthFailed, StepUpRequired, StepUpVerificationPending, } from "./errors.js";
+import { AuthLoginInteraction } from "./login-interaction.js";
+import { AuthLoginPresenter } from "./login-presenter.js";
+import { resolveRequiredToken } from "./token-resolution.js";
+const invalidReference = (detail, recover) => new RegistryAuthFailed({
+    category: "validation",
+    detail,
+    ...(recover === undefined ? {} : { recover }),
+});
+/** Request references may only address the selected Registry's step-up resource. */
+const readRequestReference = (reference, registryUrl) => Effect.try({
+    try: () => {
+        const url = new URL(reference);
+        const registry = new URL(registryUrl);
+        const match = /^\/v1\/auth\/step-up\/requests\/(step_[a-z0-9]+)$/.exec(url.pathname);
+        if (url.origin !== registry.origin ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash ||
+            match?.[1] === undefined)
+            throw new Error("Invalid step-up reference");
+        return match[1];
+    },
+    catch: () => invalidReference("The step-up request URL must identify a step-up request on the selected Registry.", "Use the requestRef from this Registry's pending-human result."),
+});
+const pendingVerification = (stepUp, registryUrl, timedOut) => new StepUpVerificationPending({
+    timedOut,
+    action: {
+        kind: "open-url",
+        purpose: "step-up",
+        requestRef: stepUp.statusUrl,
+        registryUrl,
+        url: stepUp.verificationUrl,
+        expiresAt: stepUp.expiresAt,
+        intervalSeconds: stepUp.intervalSeconds,
+        resume: `Rerun the same command with the same inputs and --step-up-request ${stepUp.statusUrl}. Add --wait-for-human SECONDS for a bounded wait.`,
+    },
+});
+/** The challenge a failure carries, whether typed or still on the wire. */
+const challengeOf = (failure) => failure instanceof StepUpRequired
+    ? failure.stepUp
+    : isRegistryClientFailure(failure)
+        ? readStepUpRequest(failure)
+        : null;
+/**
+ * Run a Registry write that may be challenged, carry the challenge through
+ * human verification, and retry the write exactly once with the verified
+ * request id.
+ *
+ * The write is never replayed without verification, and a wait that elapses
+ * while the request is still valid resolves to `StepUpVerificationPending`
+ * rather than a failure of the write.
+ */
+export const runWithStepUp = (operation, presentation, options, registryUrl) => Effect.gen(function* () {
+    const authClient = yield* AuthClient;
+    const interaction = yield* AuthLoginInteraction;
+    const presenter = yield* AuthLoginPresenter;
+    const waitSeconds = options.waitForHumanSeconds;
+    if (waitSeconds !== undefined && (!Number.isSafeInteger(waitSeconds) || waitSeconds <= 0)) {
+        return yield* invalidReference("--wait-for-human must be a positive number of seconds.");
+    }
+    const resumedId = options.resumeReference === undefined
+        ? undefined
+        : yield* readRequestReference(options.resumeReference, registryUrl);
+    const initial = resumedId === undefined
+        ? yield* presenter.withProgress({ _tag: "RunningVerifiedWrite", operation: presentation.operationLabel }, () => Effect.result(operation()))
+        : undefined;
+    if (initial !== undefined && Result.isSuccess(initial)) {
+        return { value: initial.success, stepUpCompleted: false };
+    }
+    const challenge = initial !== undefined && Result.isFailure(initial) ? challengeOf(initial.failure) : null;
+    if (initial !== undefined && Result.isFailure(initial) && challenge === null) {
+        return yield* Effect.fail(initial.failure);
+    }
+    const token = yield* resolveRequiredToken(registryUrl, {
+        missingTokenError: authLoginRequired("Not authenticated"),
+    });
+    const resumed = resumedId === undefined
+        ? undefined
+        : yield* authClient.getStepUpRequest(token.token, resumedId);
+    if (resumed !== undefined && resumed.status !== "pending" && resumed.status !== "verified") {
+        return yield* new RegistryAuthFailed({
+            category: resumed.status === "expired"
+                ? "auth_expired"
+                : resumed.status === "cancelled"
+                    ? "auth_denied"
+                    : "conflict",
+            detail: `The step-up request is ${resumed.status}. It cannot be resumed.`,
+            recover: "Review the result of the previous request before explicitly starting a new command without --step-up-request.",
+        });
+    }
+    const stepUp = challenge ??
+        (resumed !== undefined && resumedId !== undefined
+            ? {
+                requestId: resumedId,
+                statusUrl: new URL(`/v1/auth/step-up/requests/${resumedId}`, registryUrl).href,
+                verificationUrl: new URL(`/step-up/${resumedId}`, authClient.getAuthorizationIssuer())
+                    .href,
+                expiresAt: DateTime.formatIso(resumed.expires_at),
+                intervalSeconds: 2,
+                action: presentation.operationLabel,
+                target: presentation.operationLabel,
+            }
+            : null);
+    if (stepUp === null) {
+        return yield* new RegistryAuthFailed({
+            category: "auth",
+            detail: "The Registry did not return a verification request.",
+        });
+    }
+    const challengeId = yield* readRequestReference(stepUp.statusUrl, registryUrl);
+    if (challengeId !== stepUp.requestId) {
+        return yield* invalidReference("The Registry returned mismatched step-up references.");
+    }
+    const now = yield* Clock.currentTimeMillis;
+    const remaining = Date.parse(stepUp.expiresAt) - now;
+    if (!Number.isFinite(remaining) || remaining <= 0) {
+        return yield* new RegistryAuthFailed({
+            category: "auth_expired",
+            detail: "The step-up request has expired.",
+        });
+    }
+    if (resumed?.status !== "verified") {
+        if (options.unattended && waitSeconds === undefined) {
+            return yield* pendingVerification(stepUp, registryUrl, false);
+        }
+        const opened = options.unattended
+            ? false
+            : yield* interaction.openBrowser(stepUp.verificationUrl);
+        yield* presenter.presentStepUpChallenge({
+            action: stepUp.action,
+            target: stepUp.target,
+            verificationUrl: stepUp.verificationUrl,
+            expiresAt: stepUp.expiresAt,
+            browserOpened: opened,
+        });
+        const waited = yield* presenter.withProgress({ _tag: "WaitingForHumanVerification", operation: presentation.waitingLabel }, () => authClient
+            .waitForStepUpRequest(token.token, stepUp.statusUrl, stepUp.intervalSeconds)
+            .pipe(Effect.timeoutOption(Duration.millis(Math.min(remaining, waitSeconds === undefined ? remaining : waitSeconds * 1000)))));
+        if (Option.isNone(waited)) {
+            if ((yield* Clock.currentTimeMillis) >= Date.parse(stepUp.expiresAt)) {
+                return yield* new RegistryAuthFailed({
+                    category: "auth_expired",
+                    detail: "The step-up request has expired.",
+                });
+            }
+            return yield* pendingVerification(stepUp, registryUrl, true);
+        }
+    }
+    const value = yield* presenter.withProgress({ _tag: "RetryingVerifiedWrite", operation: presentation.operationLabel }, () => operation(stepUp.requestId));
+    return { value, stepUpCompleted: true };
+});
+//# sourceMappingURL=step-up.js.map

package/dist/src/tokens.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Granular access-token policy: the expiry grammar and its bounds, the
+ * permission payload the Registry accepts, and the human-verification
+ * requirement on every token write.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { AuthClient, type CreatedTokenResponse, type TokenPermissionsRequest } from "./auth-client.js";
+import { CredentialStore } from "./credential-store.js";
+import { RegistryAuthFailed } from "./errors.js";
+import { AuthLoginPresenter } from "./login-presenter.js";
+import { type StepUpOptions } from "./step-up.js";
+/** A token may live no less than an hour and no more than a year. */
+export declare const MIN_TOKEN_LIFETIME_SECONDS = 3600;
+export declare const MAX_TOKEN_LIFETIME_SECONDS = 31536000;
+/** The authority a new token carries. */
+export interface TokenAuthorityRequest {
+    readonly owners: ReadonlyArray<string>;
+    readonly extensions: ReadonlyArray<string>;
+    readonly permission: Option.Option<"read" | "publish" | "admin">;
+    readonly orgPermission: Option.Option<"read" | "write" | "admin">;
+    readonly cidr: ReadonlyArray<string>;
+    readonly bypassMfa: boolean;
+}
+export interface CreateTokenRequest extends TokenAuthorityRequest {
+    readonly name: string;
+    /** Relative lifetime (`7d`, `30d`, `1y`) or an absolute ISO timestamp. */
+    readonly expires: string;
+    readonly verification: StepUpOptions;
+}
+export interface CreatedToken {
+    readonly token: CreatedTokenResponse;
+    readonly stepUpCompleted: boolean;
+}
+/**
+ * Read the requested lifetime. Relative forms are exact multiples; an
+ * absolute timestamp becomes the distance from now.
+ */
+export declare const parseExpiresInSeconds: (raw: string) => Effect.Effect<number, RegistryAuthFailed>;
+/** Enforce the accepted lifetime window. */
+export declare const validateExpiresInSeconds: (expiresIn: number) => Effect.Effect<number, RegistryAuthFailed>;
+/** Only the authority a caller actually asked for reaches the Registry. */
+export declare const tokenPermissions: (request: TokenAuthorityRequest) => TokenPermissionsRequest;
+export declare const createToken: (request: CreateTokenRequest, registryUrl: string) => Effect.Effect<{
+    token: CreatedTokenResponse;
+    stepUpCompleted: boolean;
+}, import("./errors.js").AuthError, AuthClient | CredentialStore | AuthLoginPresenter | import("./login-interaction.ts").AuthLoginInteraction>;
+export declare const revokeToken: (tokenId: string, verification: StepUpOptions, registryUrl: string) => Effect.Effect<{
+    tokenId: string;
+    stepUpCompleted: boolean;
+}, import("./errors.js").AuthError, AuthClient | CredentialStore | AuthLoginPresenter | import("./login-interaction.ts").AuthLoginInteraction>;
+export declare const listTokens: (registryUrl: string) => Effect.Effect<import("./auth-client.js").TokenListResponse, import("./errors.js").AuthError, AuthClient | CredentialStore | AuthLoginPresenter>;
+/** Declared for the reader; every member keeps these in `R`. */
+export type TokenRequirements = AuthClient | CredentialStore | AuthLoginPresenter;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/src/tokens.js

@@ -0,0 +1,78 @@
+/**
+ * Granular access-token policy: the expiry grammar and its bounds, the
+ * permission payload the Registry accepts, and the human-verification
+ * requirement on every token write.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { AuthClient, } from "./auth-client.js";
+import { CredentialStore } from "./credential-store.js";
+import { RegistryAuthFailed } from "./errors.js";
+import { AuthLoginPresenter } from "./login-presenter.js";
+import { currentToken } from "./identity.js";
+import { runWithStepUp } from "./step-up.js";
+/** A token may live no less than an hour and no more than a year. */
+export const MIN_TOKEN_LIFETIME_SECONDS = 3_600;
+export const MAX_TOKEN_LIFETIME_SECONDS = 31_536_000;
+const invalid = (detail) => new RegistryAuthFailed({ category: "validation", detail });
+/**
+ * Read the requested lifetime. Relative forms are exact multiples; an
+ * absolute timestamp becomes the distance from now.
+ */
+export const parseExpiresInSeconds = (raw) => {
+    const trimmed = raw.trim();
+    const relative = /^(\d+)([hdy])$/.exec(trimmed);
+    if (relative) {
+        const amount = Number(relative[1]);
+        const unit = relative[2];
+        const multiplier = unit === "h" ? 3_600 : unit === "d" ? 86_400 : 31_536_000;
+        return Effect.succeed(amount * multiplier);
+    }
+    return Option.match(DateTime.make(trimmed), {
+        onNone: () => Effect.fail(invalid("Invalid --expires value. Use 7d, 30d, 1y, or an ISO timestamp.")),
+        onSome: (expiry) => Effect.map(DateTime.now, (now) => Math.floor(Duration.toSeconds(DateTime.distance(now, expiry)))),
+    });
+};
+/** Enforce the accepted lifetime window. */
+export const validateExpiresInSeconds = (expiresIn) => expiresIn < MIN_TOKEN_LIFETIME_SECONDS || expiresIn > MAX_TOKEN_LIFETIME_SECONDS
+    ? Effect.fail(invalid("Token expiry must be between 1 hour and 365 days."))
+    : Effect.succeed(expiresIn);
+/** Only the authority a caller actually asked for reaches the Registry. */
+export const tokenPermissions = (request) => ({
+    ...(request.owners.length > 0 ? { owners: request.owners } : {}),
+    ...(request.extensions.length > 0 ? { extensions: request.extensions } : {}),
+    ...(Option.isSome(request.permission) ? { permission: request.permission.value } : {}),
+    ...(Option.isSome(request.orgPermission) ? { org_permission: request.orgPermission.value } : {}),
+    ...(request.cidr.length > 0 ? { cidr: request.cidr } : {}),
+    ...(request.bypassMfa ? { bypass_mfa: true } : {}),
+});
+export const createToken = Effect.fn("Tokens.create")(function* (request, registryUrl) {
+    const authClient = yield* AuthClient;
+    const token = yield* currentToken(registryUrl);
+    const expiresIn = yield* parseExpiresInSeconds(request.expires).pipe(Effect.flatMap(validateExpiresInSeconds));
+    const created = yield* runWithStepUp((stepUpRequestId) => authClient.createToken(token, { name: request.name, expiresIn, permissions: tokenPermissions(request) }, stepUpRequestId === undefined ? undefined : { stepUpRequestId }), {
+        operationLabel: `Create registry token "${request.name}"`,
+        waitingLabel: `verification to create registry token "${request.name}"`,
+    }, request.verification, registryUrl);
+    return { token: created.value, stepUpCompleted: created.stepUpCompleted };
+});
+export const revokeToken = Effect.fn("Tokens.revoke")(function* (tokenId, verification, registryUrl) {
+    const authClient = yield* AuthClient;
+    const token = yield* currentToken(registryUrl);
+    const revoked = yield* runWithStepUp((stepUpRequestId) => authClient.deleteToken(token, tokenId, stepUpRequestId === undefined ? undefined : { stepUpRequestId }), {
+        operationLabel: `Revoke registry token ${tokenId}`,
+        waitingLabel: `verification to revoke token ${tokenId}`,
+    }, verification, registryUrl);
+    return { tokenId, stepUpCompleted: revoked.stepUpCompleted };
+});
+export const listTokens = Effect.fn("Tokens.list")(function* (registryUrl) {
+    const authClient = yield* AuthClient;
+    const presenter = yield* AuthLoginPresenter;
+    const token = yield* currentToken(registryUrl);
+    return yield* presenter.withProgress({ _tag: "ListingRegistryTokens" }, () => authClient.listTokens(token));
+});
+//# sourceMappingURL=tokens.js.map

package/package.json

@@ -4,15 +4,16 @@
     "url": "https://github.com/agentxm/axm/issues"
   },
   "dependencies": {
-    "@agentxm/extension-model": "^0.28.12",
-    "@agentxm/registry-client": "^0.28.12",
-    "@agentxm/registry-protocol": "^0.28.12",
+    "@agentxm/extension-model": "^0.28.13",
+    "@agentxm/registry-client": "^0.28.13",
+    "@agentxm/registry-protocol": "^0.28.13",
     "@napi-rs/keyring": "^1.3.0",
     "effect": "4.0.0-rc.112",
     "proper-lockfile": "^4.1.2"
   },
   "description": "AXM registry-auth feature: login, logout, token, identity inspection, device and loopback flows, and credential lifecycle for the axm CLI. Unstable and unsupported — use the axm.sh CLI.",
   "devDependencies": {
+    "@agentxm/specification-metadata": "^0.28.13",
     "@effect/platform-node": "4.0.0-rc.112",
     "@effect/vitest": "4.0.0-rc.112",
     "@types/bun": "^1.3.14",
@@ -55,11 +56,11 @@
     "access": "public"
   },
   "repository": {
-    "directory": "packages/registry-auth",
+    "directory": "packages/supporting/registry-auth",
     "type": "git",
     "url": "https://github.com/agentxm/axm.git"
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.28.12"
-}
+  "version": "0.28.13"
+}