@tenderprompt/accounts 0.4.0 → 0.5.1

package/dist/main.js

@@ -1,19 +1,21 @@
 import { fileURLToPath } from "node:url";
 import { copyFile, mkdir, readFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
-import { hostname } from "node:os";
+import { homedir, hostname } from "node:os";
 import { AgentApiClient } from "./api.js";
-import { CLI_AUTH_SCHEMA, createDefaultAuthStore, } from "./auth-store.js";
+import { CLI_AUTH_SCHEMA, DEFAULT_AUTH_PROFILE, createDefaultAuthStore, validateAuthProfile, validateNamedAuthProfile, } from "./auth-store.js";
 import { labelLocalArtifact, verifyArtifact } from "./artifact.js";
 import { BUILD_ENVELOPE_FILENAME, CLI_CONFIG_SCHEMA, CLI_LINK_SCHEMA, } from "./contracts.js";
 import { CliApiError, CliError } from "./errors.js";
 import { loadProjectContext, normalizeApiUrl, pathExists, readBoundedFile, readOptionalToken, requiredProjectId, resolveArtifactDirectory, safeArtifactPath, writeProjectLink, } from "./files.js";
 import { OAuthApiClient, createPkcePair, openSystemBrowser, waitForLoopbackAuthorization, } from "./oauth.js";
 import { captureCommand, runProjectCommand } from "./processes.js";
+import { createDefaultProfileBindings, } from "./profile-bindings.js";
 import { initializeStarter } from "./starter.js";
-export const CLI_VERSION = "0.4.0";
+export const CLI_VERSION = "0.5.1";
 const DEFAULT_RUNTIME = {
     cwd: process.cwd(),
+    homeDirectory: homedir(),
     environment: process.env,
     stdin: process.stdin,
     stdout: process.stdout,
@@ -23,6 +25,7 @@ const DEFAULT_RUNTIME = {
     runProjectCommand,
     captureCommand,
     authStore: createDefaultAuthStore(process.env),
+    profileBindings: createDefaultProfileBindings(process.env),
     openBrowser: openSystemBrowser,
     waitForLoopbackAuthorization,
     openLogStream: (url, protocols) => new WebSocket(url, protocols),
@@ -91,7 +94,7 @@ async function execute(topic, options, cwd, runtime) {
                 ? { value: { schema: "tender.accounts-skill/v1", content: await readSkill() } }
                 : { raw: await readSkill() };
         case "skill install":
-            return { value: await installSkill(cwd, options) };
+            return { value: await installSkill(cwd, options, runtime) };
         case "dev":
             return await runDev(cwd, options, runtime);
         case "check":
@@ -100,10 +103,20 @@ async function execute(topic, options, cwd, runtime) {
             return { value: await buildProject(cwd, options, runtime) };
         case "auth status":
             return { value: await authStatus(cwd, options, runtime) };
+        case "auth list":
+            return { value: await authList(runtime) };
+        case "auth create":
+            return { value: await authCreate(cwd, options, runtime) };
+        case "auth delete":
+            return { value: await authDelete(cwd, options, runtime) };
+        case "auth activate":
+            return { value: await authActivate(cwd, options, runtime) };
+        case "auth deactivate":
+            return { value: await authDeactivate(cwd, options, runtime) };
         case "auth login":
             return { value: await authLogin(cwd, options, runtime) };
         case "auth logout":
-            return { value: await authLogout(options, runtime) };
+            return { value: await authLogout(cwd, options, runtime) };
         case "link":
             return { value: await linkProject(cwd, options, runtime) };
         case "doctor":
@@ -221,34 +234,68 @@ async function authStatus(cwd, options, runtime) {
     const context = await optionalContext(cwd);
     const resolved = await authenticatedClient(cwd, context?.link ?? null, options, runtime);
     const principal = await resolved.client.whoami();
+    if (resolved.profile)
+        await savePrincipalSummary(runtime.authStore, resolved.profile, principal);
     return {
         ...principal,
         authentication: {
             source: resolved.source,
             apiUrl: resolved.apiUrl,
             ...(resolved.accessTokenExpiresAt ? { accessTokenExpiresAt: resolved.accessTokenExpiresAt } : {}),
-            ...(resolved.source === "login" ? { storage: runtime.authStore.description() } : {}),
+            ...(resolved.source === "login" ? { profile: resolved.profile, storage: runtime.authStore.description() } : {}),
         },
     };
 }
+async function authList(runtime) {
+    const profiles = await runtime.authStore.list();
+    const bindings = await runtime.profileBindings.list();
+    return {
+        schema: "tender.accounts-auth-profiles/v1",
+        storage: runtime.authStore.description(),
+        bindingStorage: runtime.profileBindings.description(),
+        profiles: profiles.map(({ profile, auth }) => ({
+            profile,
+            default: profile === DEFAULT_AUTH_PROFILE,
+            apiUrl: auth.apiUrl,
+            status: auth.pendingDevice ? "authorization_pending" : "authenticated",
+            ...(auth.pendingDevice ? { expiresAt: auth.pendingDevice.expiresAt } : {}),
+            ...(!auth.pendingDevice && auth.refreshTokenExpiresAt ? { expiresAt: auth.refreshTokenExpiresAt } : {}),
+            boundDirectories: bindings
+                .filter((binding) => binding.profile === profile)
+                .map((binding) => binding.directory),
+            containsCredential: false,
+        })),
+    };
+}
 async function authLogin(cwd, options, runtime) {
+    return await authenticateProfile(cwd, options, runtime, DEFAULT_AUTH_PROFILE, options.booleans.has("force"));
+}
+async function authCreate(cwd, options, runtime) {
+    assertNoEnvironmentCredentialForProfileManagement(runtime.environment);
+    const profile = validateNamedAuthProfile(requiredPositional(options, 0, "profile name"));
+    return await authenticateProfile(cwd, options, runtime, profile, true);
+}
+async function authenticateProfile(cwd, options, runtime, profile, replaceExisting) {
     const context = await optionalContext(cwd);
     const apiUrl = selectedApiUrl(options, context?.link ?? null, runtime.environment);
     const projectHint = options.flags.get("project") ?? context?.link?.projectId;
     const clientName = options.flags.get("client-name") ?? `Tender CLI on ${hostname()}`;
-    const existing = await runtime.authStore.read();
-    if (existing && !options.booleans.has("force")) {
+    const existing = await runtime.authStore.read(profile);
+    if (existing && !replaceExisting) {
+        const replacement = profile === DEFAULT_AUTH_PROFILE
+            ? "tender-accounts auth login --force"
+            : `tender-accounts auth create ${profile}`;
         throw new CliError("already_authenticated", existing.pendingDevice
-            ? "A Tender CLI device authorization is already pending."
-            : "This machine already has a Tender Accounts login.", existing.pendingDevice
-            ? "Run tender-accounts auth status --json after approving it, or auth login --force to replace it."
-            : "Run tender-accounts auth status --json, or auth login --force to replace it.");
+            ? `Tender CLI profile ${profile} already has a pending device authorization.`
+            : `Tender CLI profile ${profile} is already authenticated.`, existing.pendingDevice
+            ? `Run tender-accounts auth status --profile ${profile} --json after approving it, or ${replacement} to replace it.`
+            : `Run tender-accounts auth status --profile ${profile} --json, or ${replacement} to replace it.`);
     }
     if (existing?.refreshToken) {
         await new OAuthApiClient(existing.apiUrl, runtime.fetcher).revoke(existing.refreshToken);
     }
     if (existing)
-        await runtime.authStore.clear();
+        await clearStoredProfile(runtime.authStore, profile, existing);
     const oauth = new OAuthApiClient(apiUrl, runtime.fetcher);
     if (options.booleans.has("device")) {
         const device = await oauth.deviceAuthorization({ clientName, ...(projectHint ? { projectHint } : {}) });
@@ -265,7 +312,8 @@ async function authLogin(cwd, options, runtime) {
                 intervalSeconds: device.interval,
             },
         };
-        await runtime.authStore.write(pending);
+        if (!await runtime.authStore.compareAndSwap(profile, null, pending))
+            throw authProfileChanged(profile);
         if (!options.booleans.has("no-open"))
             await runtime.openBrowser(device.verification_uri_complete);
         if (!options.booleans.has("wait")) {
@@ -275,13 +323,14 @@ async function authLogin(cwd, options, runtime) {
                 userCode: device.user_code,
                 verificationUrl: device.verification_uri,
                 verificationUrlComplete: device.verification_uri_complete,
+                profile,
                 expiresAt,
-                next: "Approve the request, then run tender-accounts auth status --json.",
+                next: `Approve the request, then run tender-accounts auth status --profile ${profile} --json.`,
             };
         }
-        const token = await waitForDeviceToken(oauth, pending, runtime);
-        await saveTokenResponse(runtime.authStore, apiUrl, token);
-        return await authenticatedLoginSummary(apiUrl, token, runtime);
+        const token = await waitForDeviceToken(oauth, pending, profile, runtime);
+        await saveTokenResponse(runtime.authStore, profile, apiUrl, token, oauth, pending);
+        return await authenticatedLoginSummary(apiUrl, token, profile, runtime);
     }
     const pkce = createPkcePair();
     const callback = await runtime.waitForLoopbackAuthorization({
@@ -305,32 +354,117 @@ async function authLogin(cwd, options, runtime) {
         codeVerifier: pkce.verifier,
         redirectUri: callback.redirectUri,
     });
-    await saveTokenResponse(runtime.authStore, apiUrl, token);
-    return await authenticatedLoginSummary(apiUrl, token, runtime);
+    await saveTokenResponse(runtime.authStore, profile, apiUrl, token, oauth, null);
+    return await authenticatedLoginSummary(apiUrl, token, profile, runtime);
 }
-async function authLogout(options, runtime) {
-    if (options.booleans.has("local")) {
-        await runtime.authStore.clear();
-        return { status: "logged_out", remoteSessionRevoked: false, storage: runtime.authStore.description() };
+async function authActivate(cwd, options, runtime) {
+    assertNoEnvironmentCredentialForProfileManagement(runtime.environment);
+    const profile = validateNamedAuthProfile(requiredPositional(options, 0, "profile name"));
+    if (!await runtime.authStore.read(profile)) {
+        throw new CliError("auth_profile_not_found", `Tender Accounts auth profile ${profile} does not exist.`, `tender-accounts auth create ${profile}`);
     }
-    const stored = await runtime.authStore.read();
+    const directory = resolve(cwd, options.positionals[1] ?? ".");
+    await runtime.profileBindings.activate(profile, directory);
+    return {
+        status: "activated",
+        profile,
+        directory,
+        inheritedByDescendants: true,
+        containsCredential: false,
+    };
+}
+async function authDeactivate(cwd, options, runtime) {
+    assertNoEnvironmentCredentialForProfileManagement(runtime.environment);
+    const directory = resolve(cwd, options.positionals[0] ?? ".");
+    const removed = await runtime.profileBindings.deactivate(directory);
+    const fallback = await runtime.profileBindings.resolve(directory);
+    return {
+        status: "deactivated",
+        profile: removed.profile,
+        directory: removed.directory,
+        activeProfile: fallback?.profile ?? (await runtime.authStore.read(DEFAULT_AUTH_PROFILE) ? DEFAULT_AUTH_PROFILE : null),
+        containsCredential: false,
+    };
+}
+async function authDelete(_cwd, options, runtime) {
+    assertNoEnvironmentCredentialForProfileManagement(runtime.environment);
+    const profile = validateNamedAuthProfile(requiredPositional(options, 0, "profile name"));
+    const stored = await runtime.authStore.read(profile);
     if (!stored)
-        return { status: "not_authenticated", remoteSessionRevoked: false };
-    if (stored.refreshToken) {
+        throw new CliError("auth_profile_not_found", `Tender Accounts auth profile ${profile} does not exist.`);
+    if (!options.booleans.has("local") && stored.refreshToken) {
         await new OAuthApiClient(stored.apiUrl, runtime.fetcher).revoke(stored.refreshToken);
     }
-    await runtime.authStore.clear();
+    await clearStoredProfile(runtime.authStore, profile, stored);
+    const removedBindings = await runtime.profileBindings.removeProfile(profile);
+    return {
+        status: "deleted",
+        profile,
+        remoteSessionRevoked: !options.booleans.has("local") && Boolean(stored.refreshToken),
+        removedBindings,
+        storage: runtime.authStore.description(),
+    };
+}
+function assertNoEnvironmentCredentialForProfileManagement(environment) {
+    if (!environment.TENDER_ACCOUNTS_TOKEN)
+        return;
+    throw new CliError("auth_profile_environment_override", "TENDER_ACCOUNTS_TOKEN overrides local auth profiles, so profile management is disabled for this command.", "Unset TENDER_ACCOUNTS_TOKEN, then retry the auth profile command.");
+}
+async function authLogout(_cwd, options, runtime) {
+    if (options.booleans.has("all") && options.booleans.has("local")) {
+        await runtime.authStore.clearAll();
+        await runtime.profileBindings.clearAll();
+        return {
+            status: "logged_out",
+            profiles: "all",
+            remoteSessionRevoked: false,
+            remoteSessionsRevoked: 0,
+            storage: runtime.authStore.description(),
+        };
+    }
+    const profiles = await runtime.authStore.list();
+    if (profiles.length === 0)
+        return { status: "not_authenticated", remoteSessionRevoked: false };
+    if (!options.booleans.has("all") && !profiles.some(({ profile }) => profile === DEFAULT_AUTH_PROFILE)) {
+        return {
+            status: "not_authenticated",
+            profile: DEFAULT_AUTH_PROFILE,
+            namedProfilesRetained: profiles.length,
+            remoteSessionRevoked: false,
+        };
+    }
+    const selectedProfiles = options.booleans.has("all")
+        ? profiles.map(({ profile }) => profile)
+        : [DEFAULT_AUTH_PROFILE];
+    let revoked = 0;
+    for (const profile of selectedProfiles) {
+        const stored = await runtime.authStore.read(profile);
+        if (!stored)
+            continue;
+        if (!options.booleans.has("local") && stored.refreshToken) {
+            await new OAuthApiClient(stored.apiUrl, runtime.fetcher).revoke(stored.refreshToken);
+            revoked += 1;
+        }
+        await clearStoredProfile(runtime.authStore, profile, stored);
+    }
+    if (options.booleans.has("all"))
+        await runtime.profileBindings.clearAll();
     return {
         status: "logged_out",
-        remoteSessionRevoked: Boolean(stored.refreshToken),
+        profiles: selectedProfiles,
+        remoteSessionRevoked: revoked > 0,
+        remoteSessionsRevoked: revoked,
         storage: runtime.authStore.description(),
     };
 }
 async function linkProject(cwd, options, runtime) {
     const context = await loadProjectContext(cwd);
     const apiUrl = selectedApiUrl(options, context.link, runtime.environment);
-    const { client } = await authenticatedClient(context.root, context.link, options, runtime);
+    const resolved = await authenticatedClient(context.root, context.link, options, runtime);
+    const { client } = resolved;
     const principal = await client.whoami();
+    if (resolved.profile)
+        await savePrincipalSummary(runtime.authStore, resolved.profile, principal);
     const requested = options.flags.get("project");
     const project = requested
         ? principal.projects.find((candidate) => candidate.projectId === requiredProjectId(requested))
@@ -354,6 +488,7 @@ async function linkProject(cwd, options, runtime) {
         projectId: project.projectId,
         role: project.role,
         apiUrl,
+        ...(resolved.profile ? { activeProfile: resolved.profile } : {}),
         linkPath: path,
         containsCredential: false,
         reminder: "Keep .tender/ and .dev.vars out of Git.",
@@ -513,63 +648,85 @@ async function authenticatedClient(cwd, link, options, runtime) {
                 : "dev-vars";
         return { client: new AgentApiClient(apiUrl, explicit, runtime.fetcher), apiUrl, source };
     }
-    const stored = await resolveStoredLogin(apiUrl, runtime);
+    const profile = await selectAuthProfile(cwd, options, runtime);
+    const stored = await resolveStoredLogin(apiUrl, profile, runtime);
     return {
         client: new AgentApiClient(apiUrl, stored.accessToken, runtime.fetcher),
         apiUrl,
         source: "login",
+        profile,
         accessTokenExpiresAt: stored.accessTokenExpiresAt,
     };
 }
+async function selectAuthProfile(cwd, options, runtime) {
+    const explicit = options.flags.get("profile") ?? runtime.environment.TENDER_ACCOUNTS_PROFILE;
+    if (explicit)
+        return validateAuthProfile(explicit);
+    const binding = await runtime.profileBindings.resolve(cwd);
+    if (binding)
+        return binding.profile;
+    const profiles = await runtime.authStore.list();
+    if (profiles.some(({ profile }) => profile === DEFAULT_AUTH_PROFILE))
+        return DEFAULT_AUTH_PROFILE;
+    if (profiles.length === 0) {
+        throw new CliError("authentication_required", "No Tender Accounts credential or CLI login was found.", "tender-accounts auth login, or tender-accounts auth create merchant-name");
+    }
+    throw new CliError("auth_profile_required", "Named Tender Accounts logins are available, but this directory does not select one and no default login exists.", `Run tender-accounts auth list --json, then tender-accounts auth activate ${profiles[0].profile}.`);
+}
 function selectedApiUrl(options, link, environment) {
     return normalizeApiUrl(options.flags.get("api-url")
         ?? environment.TENDER_ACCOUNTS_API_URL
         ?? link?.apiUrl
         ?? "https://agents.tenderprompt.dev");
 }
-async function resolveStoredLogin(apiUrl, runtime) {
-    let stored = await runtime.authStore.read();
+async function resolveStoredLogin(apiUrl, profile, runtime) {
+    let stored = await runtime.authStore.read(profile);
     if (!stored) {
-        throw new CliError("authentication_required", "No Tender Accounts credential or CLI login was found.", "tender-accounts auth login");
+        throw new CliError("authentication_required", `Tender Accounts auth profile ${profile} is not logged in.`, authCommandForProfile(profile));
     }
     if (stored.apiUrl !== apiUrl) {
-        throw new CliError("auth_origin_mismatch", `The stored login belongs to ${stored.apiUrl}, not ${apiUrl}.`, `tender-accounts auth login --api-url ${apiUrl} --force`);
+        throw new CliError("auth_origin_mismatch", `The stored login belongs to ${stored.apiUrl}, not ${apiUrl}.`, `${authCommandForProfile(profile)} --api-url ${apiUrl}${profile === DEFAULT_AUTH_PROFILE ? " --force" : ""}`);
     }
     const oauth = new OAuthApiClient(apiUrl, runtime.fetcher);
     if (stored.pendingDevice) {
         const pendingDevice = stored.pendingDevice;
         if (Date.parse(pendingDevice.expiresAt) <= Date.now()) {
-            await runtime.authStore.clear();
-            throw new CliError("device_authorization_expired", "The pending device authorization expired.", "tender-accounts auth login --device --json");
+            await clearStoredProfile(runtime.authStore, profile, stored);
+            throw new CliError("device_authorization_expired", "The pending device authorization expired.", `${authCommandForProfile(profile)} --device --json`);
         }
         try {
             const token = await oauth.exchangeDeviceCode(pendingDevice.deviceCode);
-            stored = await saveTokenResponse(runtime.authStore, apiUrl, token);
+            stored = await saveTokenResponse(runtime.authStore, profile, apiUrl, token, oauth, stored);
         }
         catch (error) {
             if (error instanceof CliApiError && error.code === "authorization_pending") {
-                throw new CliError("authorization_pending", `Approve Tender CLI with code ${pendingDevice.userCode}.`, `Open ${pendingDevice.verificationUriComplete}, then run tender-accounts auth status --json.`);
+                throw new CliError("authorization_pending", `Approve Tender CLI with code ${pendingDevice.userCode}.`, `Open ${pendingDevice.verificationUriComplete}, then run tender-accounts auth status --profile ${profile} --json.`);
             }
             throw error;
         }
     }
     if (!stored.accessToken || !stored.accessTokenExpiresAt || !stored.refreshToken || !stored.refreshTokenExpiresAt) {
-        throw new CliError("authentication_required", "The stored Tender Accounts login is incomplete.", "tender-accounts auth login --force");
+        throw new CliError("authentication_required", "The stored Tender Accounts login is incomplete.", `${authCommandForProfile(profile)}${profile === DEFAULT_AUTH_PROFILE ? " --force" : ""}`);
     }
     if (Date.parse(stored.refreshTokenExpiresAt) <= Date.now()) {
-        await runtime.authStore.clear();
-        throw new CliError("authentication_expired", "The Tender Accounts login expired.", "tender-accounts auth login");
+        await clearStoredProfile(runtime.authStore, profile, stored);
+        throw new CliError("authentication_expired", "The Tender Accounts login expired.", authCommandForProfile(profile));
     }
     if (Date.parse(stored.accessTokenExpiresAt) <= Date.now() + 30_000) {
         const token = await oauth.refresh(stored.refreshToken);
-        stored = await saveTokenResponse(runtime.authStore, apiUrl, token);
+        stored = await saveTokenResponse(runtime.authStore, profile, apiUrl, token, oauth, stored);
     }
     if (!stored.accessToken || !stored.accessTokenExpiresAt) {
-        throw new CliError("authentication_required", "Tender Accounts could not restore the stored login.", "tender-accounts auth login --force");
+        throw new CliError("authentication_required", "Tender Accounts could not restore the stored login.", `${authCommandForProfile(profile)}${profile === DEFAULT_AUTH_PROFILE ? " --force" : ""}`);
     }
     return { accessToken: stored.accessToken, accessTokenExpiresAt: stored.accessTokenExpiresAt };
 }
-async function saveTokenResponse(store, apiUrl, token) {
+function authCommandForProfile(profile) {
+    return profile === DEFAULT_AUTH_PROFILE
+        ? "tender-accounts auth login"
+        : `tender-accounts auth create ${profile}`;
+}
+async function saveTokenResponse(store, profile, apiUrl, token, oauth, previous) {
     const now = Date.now();
     const stored = {
         schema: CLI_AUTH_SCHEMA,
@@ -578,11 +735,27 @@ async function saveTokenResponse(store, apiUrl, token) {
         accessTokenExpiresAt: new Date(now + token.expires_in * 1000).toISOString(),
         refreshToken: token.refresh_token,
         refreshTokenExpiresAt: new Date(now + token.refresh_expires_in * 1000).toISOString(),
+        ...(previous?.principal ? { principal: previous.principal } : {}),
     };
-    await store.write(stored);
+    if (!await store.compareAndSwap(profile, previous, stored)) {
+        try {
+            await oauth.revoke(token.refresh_token);
+        }
+        catch {
+            throw new CliError("auth_profile_race_revoke_failed", `Tender Accounts profile ${profile} changed while authentication was rotating, and the newly issued session could not be revoked safely.`, `Run tender-accounts auth status --profile ${profile} --json, then tender-accounts auth delete ${profile} if the session is not expected.`);
+        }
+        throw authProfileChanged(profile);
+    }
     return stored;
 }
-async function waitForDeviceToken(oauth, pending, runtime) {
+async function clearStoredProfile(store, profile, expected) {
+    if (!await store.compareAndSwap(profile, expected, null))
+        throw authProfileChanged(profile);
+}
+function authProfileChanged(profile) {
+    return new CliError("auth_profile_changed", `Tender Accounts profile ${profile} changed while this command was running. No newer local login was overwritten.`, `Run tender-accounts auth status --profile ${profile} --json, then retry the command.`);
+}
+async function waitForDeviceToken(oauth, pending, profile, runtime) {
     const device = pending.pendingDevice;
     if (!device)
         throw new CliError("device_authorization_missing", "The device authorization was not saved.");
@@ -596,15 +769,17 @@ async function waitForDeviceToken(oauth, pending, runtime) {
             await runtime.sleep(device.intervalSeconds * 1000);
         }
     }
-    await runtime.authStore.clear();
-    throw new CliError("device_authorization_expired", "The device authorization expired.", "tender-accounts auth login --device --json");
+    await clearStoredProfile(runtime.authStore, profile, pending);
+    throw new CliError("device_authorization_expired", "The device authorization expired.", `${authCommandForProfile(profile)} --device --json`);
 }
-async function authenticatedLoginSummary(apiUrl, token, runtime) {
+async function authenticatedLoginSummary(apiUrl, token, profile, runtime) {
     const principal = await new AgentApiClient(apiUrl, token.access_token, runtime.fetcher).whoami();
+    await savePrincipalSummary(runtime.authStore, profile, principal);
     return {
         status: "authenticated",
         flow: "oauth",
         apiUrl,
+        profile,
         ownerEmail: principal.ownerEmail,
         tenantId: principal.tenantId,
         projects: principal.projects,
@@ -613,6 +788,21 @@ async function authenticatedLoginSummary(apiUrl, token, runtime) {
         containsCredential: false,
     };
 }
+async function savePrincipalSummary(store, profile, principal) {
+    const stored = await store.read(profile);
+    if (!stored)
+        return;
+    const updated = {
+        ...stored,
+        principal: {
+            tenantId: principal.tenantId,
+            ownerEmail: principal.ownerEmail,
+            projects: principal.projects.map(({ projectId }) => projectId),
+        },
+    };
+    if (!await store.compareAndSwap(profile, stored, updated))
+        throw authProfileChanged(profile);
+}
 async function sourceState(root, runtime) {
     let revision;
     try {
@@ -679,15 +869,15 @@ async function optionalContext(cwd) {
         throw error;
     }
 }
-async function installSkill(cwd, options) {
+async function installSkill(cwd, options, runtime) {
     const agent = options.flags.get("agent") ?? "codex";
     const requestedDirectory = options.flags.get("directory");
     const base = requestedDirectory
         ? resolve(cwd, requestedDirectory)
         : agent === "codex"
-            ? resolve(cwd, ".agents/skills")
+            ? resolve(runtime.homeDirectory, ".agents/skills")
             : agent === "claude"
-                ? resolve(cwd, ".claude/skills")
+                ? resolve(runtime.homeDirectory, ".claude/skills")
                 : null;
     if (!base) {
         throw new CliError("skill_target_invalid", "--agent must be codex or claude unless --directory is provided.");
@@ -745,14 +935,18 @@ function commandTopic(argv) {
 function parseOptions(values) {
     const flags = new Map();
     const booleans = new Set();
+    const positionals = [];
     const booleanNames = new Set([
         "json", "token-stdin", "dry-run", "no-wait", "force",
-        "device", "wait", "no-open", "local", "production",
+        "device", "wait", "no-open", "local", "all", "production",
     ]);
     for (let index = 0; index < values.length; index += 1) {
         const raw = values[index];
-        if (!raw?.startsWith("--"))
-            throw new CliError("argument_unexpected", `Unexpected argument: ${raw ?? ""}.`);
+        if (!raw?.startsWith("--")) {
+            if (raw)
+                positionals.push(raw);
+            continue;
+        }
         const name = raw.slice(2);
         if (name === "token") {
             throw new CliError("credential_argument_forbidden", "Never pass credentials as command-line arguments.");
@@ -770,11 +964,11 @@ function parseOptions(values) {
         flags.set(name, value);
         index += 1;
     }
-    return { flags, booleans, json: booleans.has("json") };
+    return { flags, booleans, positionals, json: booleans.has("json") };
 }
 function assertAllowedOptions(topic, options) {
     const common = ["cwd", "json"];
-    const authentication = ["api-url", "token-stdin"];
+    const authentication = ["api-url", "token-stdin", "profile"];
     const allowed = {
         init: [...common, "name", "slug", "directory", "template", "dry-run"],
         "config example": common,
@@ -784,8 +978,13 @@ function assertAllowedOptions(topic, options) {
         check: common,
         build: common,
         "auth status": [...common, ...authentication],
+        "auth list": common,
+        "auth create": [...common, "api-url", "project", "client-name", "timeout-seconds", "device", "wait", "no-open"],
+        "auth delete": [...common, "local"],
+        "auth activate": common,
+        "auth deactivate": common,
         "auth login": [...common, "api-url", "project", "client-name", "timeout-seconds", "device", "wait", "no-open", "force"],
-        "auth logout": [...common, "local"],
+        "auth logout": [...common, "local", "all"],
         link: [...common, ...authentication, "project"],
         doctor: [...common, ...authentication],
         preview: [
@@ -818,6 +1017,25 @@ function assertAllowedOptions(topic, options) {
     if (unexpected) {
         throw new CliError("argument_unknown", `Option --${unexpected} is not valid for ${topic}.`, `tender-accounts ${topic} --help`);
     }
+    const positionalLimits = {
+        "auth create": { minimum: 1, maximum: 1 },
+        "auth delete": { minimum: 1, maximum: 1 },
+        "auth activate": { minimum: 1, maximum: 2 },
+        "auth deactivate": { minimum: 0, maximum: 1 },
+    };
+    const limit = positionalLimits[topic] ?? { minimum: 0, maximum: 0 };
+    if (options.positionals.length < limit.minimum) {
+        throw new CliError("argument_required", `Missing ${topic.startsWith("auth ") ? "profile name" : "argument"}.`, `tender-accounts ${topic} --help`);
+    }
+    if (options.positionals.length > limit.maximum) {
+        throw new CliError("argument_unexpected", `Unexpected argument: ${options.positionals[limit.maximum] ?? ""}.`, `tender-accounts ${topic} --help`);
+    }
+}
+function requiredPositional(options, index, label) {
+    const value = options.positionals[index];
+    if (!value)
+        throw new CliError("argument_required", `Missing ${label}.`);
+    return value;
 }
 function requiredFlag(options, name) {
     const value = options.flags.get(name);
@@ -894,11 +1112,16 @@ function writeOutput(value, options, runtime) {
 function helpText(topic) {
     const topics = {
         init: "Usage: tender-accounts init --name NAME [--slug SLUG] [--directory PATH] [--template shopify-customer-account] [--dry-run] [--json]\n\nCreate a new merchant-owned Shopify gateway and React portal in an empty directory.\n\nExamples:\n  tender-accounts init --name \"Acme account\" --directory ./acme-account\n  tender-accounts init --name \"Acme account\" --directory ./acme-account --dry-run --json",
-        auth: "Usage: tender-accounts auth <login|status|logout> [options]",
-        "auth login": "Usage: tender-accounts auth login [--device] [--project PROJECT_ID] [--no-open] [--wait] [--force] [--json]\n\nSign in through Tender and authorize exact developer projects. Browser-capable terminals use Authorization Code with PKCE. --device returns an agent-safe approval URL and code; add --wait to keep polling.\n\nExamples:\n  tender-accounts auth login\n  tender-accounts auth login --device --json\n  tender-accounts auth login --device --project prj_... --no-open --json",
-        "auth status": "Usage: tender-accounts auth status [--api-url URL] [--token-stdin] [--json]\n\nValidate the current login or explicit project-scoped credential and list its permitted projects. A pending device login is exchanged after browser approval.",
-        "auth logout": "Usage: tender-accounts auth logout [--local] [--json]\n\nRevoke the stored Tender CLI session and remove it from this machine. --local removes only the local copy.\n\nExamples:\n  tender-accounts auth logout --json\n  tender-accounts auth logout --local --json",
-        link: "Usage: tender-accounts link [--project PROJECT_ID] [--api-url URL] [--json]\n\nLink this app checkout to exactly one project permitted by the current credential.",
+        auth: "Usage: tender-accounts auth <login|create|activate|deactivate|status|list|delete|logout> [options]",
+        "auth login": "Usage: tender-accounts auth login [--device] [--project PROJECT_ID] [--no-open] [--wait] [--force] [--json]\n\nCreate or refresh the default login. Browser-capable terminals use Authorization Code with PKCE. --device returns an agent-safe approval URL and code; add --wait to keep polling. Use auth create for named merchant profiles.",
+        "auth create": "Usage: tender-accounts auth create NAME [--device] [--project PROJECT_ID] [--no-open] [--wait] [--json]\n\nCreate or re-authorize one named login without changing the active profile for any directory.\n\nExample:\n  tender-accounts auth create acme --device --project prj_... --json",
+        "auth activate": "Usage: tender-accounts auth activate NAME [DIRECTORY] [--json]\n\nActivate a named login for a directory and all descendants. A closer descendant binding wins. The binding is machine-local and is not written to the repository.",
+        "auth deactivate": "Usage: tender-accounts auth deactivate [DIRECTORY] [--json]\n\nRemove the binding declared exactly at the directory. An inherited binding must be removed at the ancestor that declares it.",
+        "auth delete": "Usage: tender-accounts auth delete NAME [--local] [--json]\n\nRevoke and delete one named login plus its directory bindings. --local keeps the remote session intact.",
+        "auth status": "Usage: tender-accounts auth status [--profile NAME] [--api-url URL] [--token-stdin] [--json]\n\nValidate the selected login or explicit project-scoped credential and list its permitted projects. Selection order is explicit profile, nearest private directory binding, then default. Repository files cannot select a local profile.",
+        "auth list": "Usage: tender-accounts auth list [--json]\n\nList locally stored profile names, expiration state, and bound directories without credentials or tenant metadata.",
+        "auth logout": "Usage: tender-accounts auth logout [--all] [--local] [--json]\n\nRevoke the default login. --local removes only the local copy; --all must be explicit to remove every login and directory binding.",
+        link: "Usage: tender-accounts link [--project PROJECT_ID] [--profile NAME] [--api-url URL] [--json]\n\nLink this checkout to exactly one project. The project ID remains a target guard; profile activation stays machine-local.",
         doctor: "Usage: tender-accounts doctor [--json]\n\nValidate configuration, authentication, project scope, and local artifact readiness.",
         dev: "Usage: tender-accounts dev\n\nRun the app's declared local development command. This starts local development and does not create a Tender deployment.",
         check: "Usage: tender-accounts check [--json]\n\nRun the app's declared validation command.",
@@ -911,13 +1134,13 @@ function helpText(topic) {
         "delivery retry": "Usage: tender-accounts delivery retry --delivery dly_... [--json]\n\nRetry one requested or failed developer preview idempotently. A dwf_ production workflow is resumed by a merchant administrator from Activity.",
         skill: "Usage: tender-accounts skill <print|install> [options]",
         "skill print": "Usage: tender-accounts skill print [--json]",
-        "skill install": "Usage: tender-accounts skill install [--agent codex|claude] [--directory PATH] [--force] [--json]",
+        "skill install": "Usage: tender-accounts skill install [--agent codex|claude] [--directory PATH] [--force] [--json]\n\nInstall globally for the current user by default: ~/.agents/skills for Codex or ~/.claude/skills for Claude. --directory is an explicit custom or repository-local override.",
         config: "Usage: tender-accounts config example [--json]",
         "config example": "Usage: tender-accounts config example [--json]\n\nPrint the committed tender-accounts.json contract.",
     };
     if (topic && topics[topic])
         return topics[topic];
-    return `Tender Accounts merchant developer CLI ${CLI_VERSION}\n\nCommands:\n  init              Create a new Shopify account starter\n  auth login        Sign in and choose exact project access\n  auth status       Validate the current login or scoped credential\n  auth logout       Revoke the stored CLI login\n  link              Link this checkout to one permitted project\n  doctor            Check developer readiness\n  dev               Run the project-owned local dev command\n  check             Run project validation\n  build             Package and verify a portable artifact\n  preview           Build and deploy an exact preview\n  tail              Stream logs for one exact linked project\n  delivery status   Read preview workflow state\n  delivery preview  Mint a fresh preview session\n  delivery retry    Retry a failed preview workflow\n  skill install     Install the Tender Accounts agent skill\n  config example    Print the project configuration contract\n\nThere is intentionally no production publish command.\nRun tender-accounts <command> --help for examples.`;
+    return `Tender Accounts merchant developer CLI ${CLI_VERSION}\n\nCommands:\n  init              Create a new Shopify account starter\n  auth login        Create or refresh the default login\n  auth create       Create or re-authorize a named login\n  auth activate     Bind a named login to a directory tree\n  auth deactivate   Remove an exact directory binding\n  auth status       Validate one login or scoped credential\n  auth list         List local login profiles and bindings\n  auth delete       Revoke one named login\n  auth logout       Revoke the default or every login\n  link              Link this checkout to one permitted project\n  doctor            Check developer readiness\n  dev               Run the project-owned local dev command\n  check             Run project validation\n  build             Package and verify a portable artifact\n  preview           Build and deploy an exact preview\n  tail              Stream logs for one exact linked project\n  delivery status   Read preview workflow state\n  delivery preview  Mint a fresh preview session\n  delivery retry    Retry a failed preview workflow\n  skill install     Install the Tender Accounts agent skill\n  config example    Print the project configuration contract\n\nThere is intentionally no production publish command.\nRun tender-accounts <command> --help for examples.`;
 }
 function normalizeError(error) {
     if (error instanceof CliApiError) {