@agentxm/registry-auth 0.28.4-bootstrap.0

package/dist/src/schema.js

@@ -0,0 +1,55 @@
+/**
+ * Schema definitions for credential storage and token sources.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Data from "effect/Data";
+import * as Schema from "effect/Schema";
+import { DateTimeUtcSchema } from "@agentxm/extension-model/unstable/date-time";
+import { HandleSchema } from "@agentxm/extension-model/unstable/extensions/handle";
+// -----------------------------------------------------------------------------
+// Credential Entry
+// -----------------------------------------------------------------------------
+export const CredentialEntrySchema = Schema.Struct({
+    access_token: Schema.String.pipe(Schema.annotateKey({ messageMissingKey: "access_token is required" })),
+    refresh_token: Schema.String.pipe(Schema.annotateKey({ messageMissingKey: "refresh_token is required" })),
+    expires_at: DateTimeUtcSchema.pipe(Schema.annotateKey({ messageMissingKey: "expires_at is required" })),
+    active: Schema.Boolean.pipe(Schema.annotateKey({ messageMissingKey: "active is required" })),
+}).annotate({
+    identifier: "CredentialEntry",
+    title: "Credential Entry",
+    description: "A saved login credential with access token, refresh token, and expiration time.",
+});
+// -----------------------------------------------------------------------------
+// Registry Accounts
+// -----------------------------------------------------------------------------
+export const RegistryAccountsSchema = Schema.Struct({
+    accounts: Schema.Record(HandleSchema, CredentialEntrySchema).pipe(Schema.annotateKey({ messageMissingKey: "accounts is required" })),
+}).annotate({
+    identifier: "RegistryAccounts",
+    title: "Registry Accounts",
+    description: "Accounts you're logged into on a registry, keyed by handle.",
+});
+// -----------------------------------------------------------------------------
+// Credential File (versioned, keyed by registry URL)
+// -----------------------------------------------------------------------------
+export const CredentialFileSchema = Schema.Struct({
+    version: Schema.Literal(1).pipe(Schema.annotateKey({ messageMissingKey: "version is required" })),
+    registries: Schema.Record(Schema.String, RegistryAccountsSchema).pipe(Schema.annotateKey({ messageMissingKey: "registries is required" })),
+}).annotate({
+    identifier: "CredentialFile",
+    title: "Credential File",
+    description: "Your saved credentials, organized by registry URL.",
+});
+// -----------------------------------------------------------------------------
+// Token Source (tagged union)
+// -----------------------------------------------------------------------------
+export class EnvVarTokenSource extends Data.TaggedClass("EnvVar") {
+}
+export class FlagTokenSource extends Data.TaggedClass("Flag") {
+}
+export class FileTokenSource extends Data.TaggedClass("File") {
+}
+export class CredentialStoreTokenSource extends Data.TaggedClass("CredentialStore") {
+}
+//# sourceMappingURL=schema.js.map

package/dist/src/testing.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Deterministic in-memory Layer implementations of the registry-auth
+ * services. Tests and specifications may import this module; production
+ * source composes real services from `./live` at the application boundary.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export { AuthClientTest } from "./auth-client.js";
+export { CredentialStoreTest } from "./credential-store.js";
+export { DeviceLoginInteractionTest, type DeviceLoginInteractionTestState, } from "./device-login.js";
+export { AuthLoginInteractionTest, type AuthLoginInteractionTestState, } from "./login-interaction.js";
+export { AuthLoginPresenterTest, type AuthLoginPresenterTestState } from "./login-presenter.js";
+export { PendingDeviceLoginStoreTest } from "./pending-device-login-store.js";
+//# sourceMappingURL=testing.d.ts.map

package/dist/src/testing.js

@@ -0,0 +1,14 @@
+/**
+ * Deterministic in-memory Layer implementations of the registry-auth
+ * services. Tests and specifications may import this module; production
+ * source composes real services from `./live` at the application boundary.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export { AuthClientTest } from "./auth-client.js";
+export { CredentialStoreTest } from "./credential-store.js";
+export { DeviceLoginInteractionTest, } from "./device-login.js";
+export { AuthLoginInteractionTest, } from "./login-interaction.js";
+export { AuthLoginPresenterTest } from "./login-presenter.js";
+export { PendingDeviceLoginStoreTest } from "./pending-device-login-store.js";
+//# sourceMappingURL=testing.js.map

package/dist/src/token-resolution.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Token resolution with precedence chain.
+ *
+ * Resolves authentication tokens from multiple sources in priority order:
+ * 1. AXM_TOKEN environment variable
+ * 2. AXM_TOKEN_FILE
+ * 3. --token flag (per-command, passed as parameter)
+ * 4. Credential store lookup by registry URL
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { type Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import { RegistryAuthFailed, type AuthError, type AuthLoginRequired, type AuthTokenPolicyRequired } from "./errors.js";
+import { AuthClient } from "./auth-client.js";
+import { CredentialStore } from "./credential-store.js";
+import { CredentialStoreTokenSource, type TokenSource } from "./schema.js";
+/**
+ * Read the locally-stored user handle for the given registry URL.
+ *
+ * Offline only — does not call the registry. Returns Option.none() when
+ * persisted credentials are unsupported, no credentials are stored, or the
+ * stored entry has no handle.
+ */
+export declare const getCurrentUserHandle: (registryUrl: string) => Effect.Effect<Option.Option<Handle>, RegistryAuthFailed, CredentialStore>;
+/**
+ * Resolve a token from the credential store only.
+ *
+ * Looks up stored credentials by origin URL. Does not check env vars or flags.
+ */
+export declare const resolveStoredToken: (origin: string) => Effect.Effect<Option.Option<CredentialStoreTokenSource>, RegistryAuthFailed, CredentialStore>;
+export declare const refreshStoredToken: (tokenSource: CredentialStoreTokenSource) => Effect.Effect<CredentialStoreTokenSource, AuthError, AuthClient | CredentialStore>;
+/**
+ * Resolve a token from ambient sources only (env var, file, and flag).
+ *
+ * Does not access the credential store.
+ *
+ * Precedence:
+ * 1. AXM_TOKEN env var
+ * 2. AXM_TOKEN_FILE
+ * 3. --token flag (passed as `flagToken` parameter)
+ */
+export declare const resolveAmbientToken: (flagToken?: string) => Effect.Effect<Option.Option<TokenSource>, RegistryAuthFailed, never>;
+/**
+ * Resolve the token that should be attached to a specific request target.
+ *
+ * Ambient sources are only considered for the configured default registry.
+ * Stored credentials remain scoped by request origin.
+ */
+export declare const resolveRequestToken: (requestUrl: string, defaultRegistryUrl: string, flagToken?: string) => Effect.Effect<Option.Option<TokenSource>, RegistryAuthFailed, CredentialStore>;
+/**
+ * Resolve a token from the precedence chain.
+ *
+ * Precedence:
+ * 1. AXM_TOKEN env var
+ * 2. AXM_TOKEN_FILE
+ * 3. --token flag (passed as `flagToken` parameter)
+ * 4. CredentialStore lookup by registry URL
+ *
+ * Returns the stored token as-is without proactive refresh. Callers should
+ * handle 401 responses from the server (e.g., prompt re-login). The auth
+ * middleware handles automatic refresh on 401 for requests going through
+ * HttpClient.
+ *
+ * Returns `Option.none()` when no token is available from any source.
+ */
+export declare const resolveToken: (registryUrl: string, flagToken?: string) => Effect.Effect<Option.Option<TokenSource>, RegistryAuthFailed, CredentialStore>;
+/**
+ * Resolve a token and fail with the correct auth policy error when none is available.
+ *
+ * In CI environments, persisted credentials are disabled by policy, so
+ * callers should surface the auth policy error instead of suggesting `axm login`.
+ */
+export declare const resolveRequiredToken: (registryUrl: string, options?: {
+    readonly flagToken?: string;
+    readonly missingTokenError?: AuthError;
+}) => Effect.Effect<TokenSource, RegistryAuthFailed | AuthLoginRequired | AuthTokenPolicyRequired | AuthError, CredentialStore>;
+//# sourceMappingURL=token-resolution.d.ts.map

package/dist/src/token-resolution.js

@@ -0,0 +1,190 @@
+/**
+ * Token resolution with precedence chain.
+ *
+ * Resolves authentication tokens from multiple sources in priority order:
+ * 1. AXM_TOKEN environment variable
+ * 2. AXM_TOKEN_FILE
+ * 3. --token flag (per-command, passed as parameter)
+ * 4. Credential store lookup by registry URL
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import { envOption } from "./internal/environment.js";
+import { normalizeHandle } from "@agentxm/extension-model/unstable/extensions/handle";
+import { authLoginRequired, RegistryAuthFailed, } from "./errors.js";
+import { AuthClient } from "./auth-client.js";
+import { CredentialStore, makePersistedCredentialsUnsupportedError } from "./credential-store.js";
+import { CredentialStoreTokenSource, EnvVarTokenSource, FileTokenSource, FlagTokenSource, } from "./schema.js";
+// -----------------------------------------------------------------------------
+// Token resolution
+// -----------------------------------------------------------------------------
+const parseOrigin = (url) => Effect.try({
+    try: () => new URL(url).origin,
+    catch: (error) => new RegistryAuthFailed({
+        category: "validation",
+        detail: `Invalid URL: ${url}`,
+        suggestions: [{ description: "Check the registry URL in your settings." }],
+        cause: error,
+    }),
+});
+const makeStoredTokenSource = (registryUrl, credentials) => new CredentialStoreTokenSource({
+    token: credentials.access_token,
+    refresh_token: credentials.refresh_token,
+    expires_at: credentials.expires_at,
+    registryUrl,
+});
+const persistRefreshedCredentials = (registryUrl, token) => Effect.gen(function* () {
+    const store = yield* CredentialStore;
+    const existing = yield* store.load(registryUrl);
+    const handle = Option.match(existing, {
+        onNone: () => normalizeHandle("@unknown"),
+        onSome: (credentials) => credentials.handle,
+    });
+    yield* store.save(registryUrl, handle, {
+        access_token: token.access_token,
+        refresh_token: token.refresh_token,
+        expires_at: token.expires_at,
+    });
+    return makeStoredTokenSource(registryUrl, token);
+});
+const makeLoginRequiredError = () => authLoginRequired();
+/**
+ * Read the locally-stored user handle for the given registry URL.
+ *
+ * Offline only — does not call the registry. Returns Option.none() when
+ * persisted credentials are unsupported, no credentials are stored, or the
+ * stored entry has no handle.
+ */
+export const getCurrentUserHandle = (registryUrl) => Effect.gen(function* () {
+    const store = yield* CredentialStore;
+    if (!store.allowsPersistedCredentials) {
+        return Option.none();
+    }
+    const stored = yield* store.load(registryUrl);
+    return Option.map(stored, (credentials) => credentials.handle);
+});
+/**
+ * Resolve a token from the credential store only.
+ *
+ * Looks up stored credentials by origin URL. Does not check env vars or flags.
+ */
+export const resolveStoredToken = (origin) => Effect.gen(function* () {
+    const store = yield* CredentialStore;
+    if (!store.allowsPersistedCredentials) {
+        return Option.none();
+    }
+    const stored = yield* store.load(origin);
+    return Option.map(stored, (credentials) => makeStoredTokenSource(origin, credentials));
+});
+export const refreshStoredToken = (tokenSource) => Effect.gen(function* () {
+    const authClient = yield* AuthClient;
+    const token = yield* authClient.refreshToken(tokenSource.refresh_token);
+    return yield* persistRefreshedCredentials(tokenSource.registryUrl, token);
+});
+/**
+ * Resolve a token from ambient sources only (env var, file, and flag).
+ *
+ * Does not access the credential store.
+ *
+ * Precedence:
+ * 1. AXM_TOKEN env var
+ * 2. AXM_TOKEN_FILE
+ * 3. --token flag (passed as `flagToken` parameter)
+ */
+export const resolveAmbientToken = (flagToken) => Effect.gen(function* () {
+    const envTokenOpt = yield* envOption("AXM_TOKEN");
+    const envToken = Option.getOrUndefined(envTokenOpt);
+    if (envToken !== undefined && envToken.length > 0) {
+        return Option.some(new EnvVarTokenSource({ token: envToken }));
+    }
+    const tokenFileOpt = yield* envOption("AXM_TOKEN_FILE");
+    if (Option.isSome(tokenFileOpt) && tokenFileOpt.value.length > 0) {
+        const maybeFs = yield* Effect.serviceOption(FileSystem.FileSystem);
+        if (Option.isNone(maybeFs)) {
+            return yield* new RegistryAuthFailed({
+                category: "internal",
+                detail: "AXM_TOKEN_FILE cannot be read in this runtime.",
+            });
+        }
+        const fs = maybeFs.value;
+        const token = yield* fs.readFileString(tokenFileOpt.value).pipe(Effect.map((content) => content.trim()), Effect.mapError((error) => new RegistryAuthFailed({
+            category: "auth",
+            detail: `Could not read AXM_TOKEN_FILE at ${tokenFileOpt.value}.`,
+            suggestions: [
+                { description: "Check that AXM_TOKEN_FILE names a readable token file." },
+            ],
+            cause: error,
+        })));
+        if (token.length === 0) {
+            return yield* new RegistryAuthFailed({
+                category: "validation",
+                detail: `AXM_TOKEN_FILE at ${tokenFileOpt.value} is empty.`,
+            });
+        }
+        return Option.some(new FileTokenSource({ token, path: tokenFileOpt.value }));
+    }
+    if (flagToken !== undefined && flagToken.length > 0) {
+        return Option.some(new FlagTokenSource({ token: flagToken }));
+    }
+    return Option.none();
+});
+/**
+ * Resolve the token that should be attached to a specific request target.
+ *
+ * Ambient sources are only considered for the configured default registry.
+ * Stored credentials remain scoped by request origin.
+ */
+export const resolveRequestToken = (requestUrl, defaultRegistryUrl, flagToken) => Effect.gen(function* () {
+    const requestOrigin = yield* parseOrigin(requestUrl);
+    const defaultRegistryOrigin = yield* parseOrigin(defaultRegistryUrl);
+    if (requestOrigin === defaultRegistryOrigin) {
+        const ambient = yield* resolveAmbientToken(flagToken);
+        if (Option.isSome(ambient)) {
+            return ambient;
+        }
+    }
+    return yield* resolveStoredToken(requestOrigin);
+});
+/**
+ * Resolve a token from the precedence chain.
+ *
+ * Precedence:
+ * 1. AXM_TOKEN env var
+ * 2. AXM_TOKEN_FILE
+ * 3. --token flag (passed as `flagToken` parameter)
+ * 4. CredentialStore lookup by registry URL
+ *
+ * Returns the stored token as-is without proactive refresh. Callers should
+ * handle 401 responses from the server (e.g., prompt re-login). The auth
+ * middleware handles automatic refresh on 401 for requests going through
+ * HttpClient.
+ *
+ * Returns `Option.none()` when no token is available from any source.
+ */
+export const resolveToken = (registryUrl, flagToken) => Effect.gen(function* () {
+    const ambient = yield* resolveAmbientToken(flagToken);
+    if (Option.isSome(ambient))
+        return ambient;
+    return yield* resolveStoredToken(registryUrl);
+});
+/**
+ * Resolve a token and fail with the correct auth policy error when none is available.
+ *
+ * In CI environments, persisted credentials are disabled by policy, so
+ * callers should surface the auth policy error instead of suggesting `axm login`.
+ */
+export const resolveRequiredToken = (registryUrl, options) => Effect.gen(function* () {
+    const token = yield* resolveToken(registryUrl, options?.flagToken);
+    if (Option.isSome(token)) {
+        return token.value;
+    }
+    const store = yield* CredentialStore;
+    if (!store.allowsPersistedCredentials) {
+        return yield* makePersistedCredentialsUnsupportedError();
+    }
+    return yield* options?.missingTokenError ?? makeLoginRequiredError();
+});
+//# sourceMappingURL=token-resolution.js.map

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@agentxm/registry-auth",
+  "version": "0.28.4-bootstrap.0",
+  "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.",
+  "type": "module",
+  "license": "FSL-1.1-MIT",
+  "homepage": "https://axm.sh",
+  "bugs": {
+    "url": "https://github.com/agentxm/axm/issues"
+  },
+  "author": "AgentXM <hello@agentxm.ai> (https://agentxm.ai)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentxm/axm.git",
+    "directory": "packages/registry-auth"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./live": {
+      "types": "./dist/src/live.d.ts",
+      "default": "./dist/src/live.js"
+    },
+    "./testing": {
+      "types": "./dist/src/testing.d.ts",
+      "default": "./dist/src/testing.js"
+    }
+  },
+  "files": [
+    "dist/src/",
+    "!**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "nx": {
+    "includedScripts": []
+  },
+  "dependencies": {
+    "@napi-rs/keyring": "^1.3.0",
+    "effect": "4.0.0-rc.112",
+    "proper-lockfile": "^4.1.2",
+    "@agentxm/registry-protocol": "^0.28.4-bootstrap.0",
+    "@agentxm/registry-client": "^0.28.4-bootstrap.0",
+    "@agentxm/extension-model": "^0.28.4-bootstrap.0"
+  },
+  "devDependencies": {
+    "@effect/platform-node": "4.0.0-rc.112",
+    "@effect/vitest": "4.0.0-rc.112",
+    "@types/bun": "^1.3.14",
+    "@types/proper-lockfile": "^4.1.4",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^4.1.10"
+  }
+}