@yargote/artifacts-cli 0.1.0-beta.6 → 0.1.0-beta.8

package/src/auth.js

@@ -2,13 +2,12 @@ import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { createServer } from 'node:http';
 import * as oidc from 'openid-client';
-import { canonicalResource, identitySchema, protectedResourceMetadataUrl, restBase } from '@yargote/artifacts-contracts/http';
-import { z } from 'zod';
+import { canonicalResource, httpErrorSchema, identitySchema, protectedResourceMetadataSchema, protectedResourceMetadataUrl, restBase } from '@yargote/artifacts-contracts/http';
+import { HttpError } from '@yargote/artifacts-client';
 import { CredentialStore } from "./credentials.js";
 const networkTimeout = 10_000;
 const callbackTimeout = 180_000;
 const scopes = 'openid profile offline_access artifacts:read artifacts:write artifacts:publish';
-const resourceMetadata = z.object({ resource: z.string(), authorization_servers: z.array(z.string()).min(1) });
 function endpoint(value, issuer) {
     const url = new URL(value);
     const loopback = /^http:\/\/(?:127\.0\.0\.1|\[::1\]|localhost)(?::[0-9]+)?(?:\/|$)/.test(value);
@@ -18,12 +17,34 @@ function endpoint(value, issuer) {
         throw new Error('OAuth endpoints must use the issuer origin');
     return url;
 }
-async function boundedFetch(url, options = {}) {
-    const signal = options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(networkTimeout)]) : AbortSignal.timeout(networkTimeout);
-    const response = await fetch(url, { ...options, redirect: 'manual', signal });
+class AuthTransportError extends Error {
+}
+function safeUrl(value) {
+    try {
+        const url = new URL(value);
+        return `${url.origin}${url.pathname}`;
+    }
+    catch {
+        return '[invalid endpoint]';
+    }
+}
+function authFailure(context, code, explanation, status) {
+    const message = `${context.phase} ${context.method} ${safeUrl(context.url)}${status === undefined ? '' : ` HTTP ${status}`}: ${explanation}`;
+    return status === undefined ? new AuthTransportError(message) : new HttpError(status, code, message);
+}
+async function boundedFetch(context, options = {}) {
+    const timeout = AbortSignal.timeout(networkTimeout);
+    const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+    let response;
+    try {
+        response = await fetch(context.url, { ...options, redirect: 'manual', signal });
+    }
+    catch {
+        throw authFailure(context, 'network_error', timeout.aborted || (options.signal?.aborted && options.signal.reason instanceof DOMException && options.signal.reason.name === 'TimeoutError') ? 'Request timed out' : options.signal?.aborted ? 'Request cancelled' : 'Network request failed');
+    }
     if (response.status >= 300 && response.status < 400) {
-        await response.body?.cancel();
-        throw new Error('Authentication redirects are not allowed');
+        await response.body?.cancel().catch(() => { });
+        throw authFailure(context, 'redirect_refused', 'Redirect refused', response.status);
     }
     const reader = response.body?.getReader();
     const chunks = [];
@@ -36,13 +57,13 @@ async function boundedFetch(url, options = {}) {
                     break;
                 size += chunk.value.byteLength;
                 if (size > 1024 * 1024)
-                    throw new Error('Authentication response is too large');
+                    throw new Error('too large');
                 chunks.push(chunk.value);
             }
         }
-        catch (error) {
+        catch {
             await reader.cancel().catch(() => { });
-            throw error;
+            throw authFailure(context, 'invalid_response', timeout.aborted || (options.signal?.aborted && options.signal.reason instanceof DOMException && options.signal.reason.name === 'TimeoutError') ? 'Response timed out' : options.signal?.aborted ? 'Request cancelled' : 'Cannot read response', response.status);
         }
         finally {
             reader.releaseLock();
@@ -50,31 +71,155 @@ async function boundedFetch(url, options = {}) {
     }
     return new Response(size ? Buffer.concat(chunks) : null, { status: response.status, statusText: response.statusText, headers: response.headers });
 }
-function discoveryOptions(issuer, signal) {
+function jsonResponse(response, context) {
+    if (response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase() !== 'application/json')
+        throw authFailure(context, 'invalid_response', 'Expected a JSON response', response.status);
+    return response.json().catch(() => { throw authFailure(context, 'invalid_response', 'Invalid JSON response', response.status); });
+}
+async function discoverResource(resource, terminal = false) {
+    const context = { phase: 'resource_metadata', method: 'GET', url: protectedResourceMetadataUrl(resource) };
+    const response = await boundedFetch(context);
+    if (!response.ok)
+        throw authFailure(context, response.status >= 500 ? 'service_error' : 'incompatible_resource', response.status >= 500 ? 'Resource metadata service failed' : 'Cannot discover the protected resource. Confirm the configured REST URL', response.status);
+    const document = await jsonResponse(response, context);
+    const parsed = protectedResourceMetadataSchema.safeParse(document);
+    if (!parsed.success)
+        throw authFailure(context, 'invalid_response', 'Invalid protected resource metadata', response.status);
+    if (parsed.data.resource !== resource)
+        throw authFailure(context, 'invalid_response', 'Protected resource metadata does not match the exact server URL', response.status);
+    if (terminal && parsed.data.artifacts_rest_resource !== undefined && parsed.data.artifacts_rest_resource !== resource)
+        throw authFailure(context, 'invalid_response', 'REST resource metadata must not advertise another artifacts_rest_resource', response.status);
+    const issuer = parsed.data.authorization_servers[0];
+    try {
+        endpoint(issuer);
+    }
+    catch {
+        throw authFailure(context, 'invalid_response', 'Invalid authorization server URL in protected resource metadata', response.status);
+    }
+    return { issuer, ...(parsed.data.artifacts_rest_resource === undefined ? {} : { restResource: parsed.data.artifacts_rest_resource }) };
+}
+function compatibleChallenge(value) {
+    if (!value)
+        return false;
+    const match = /^Bearer\s+(.+)$/i.exec(value);
+    if (!match)
+        return false;
+    const parameters = new Map();
+    const input = match[1];
+    const parameter = /\s*([!#$%&'*+.^_`|~0-9A-Za-z-]+)\s*=\s*(?:"((?:[^"\\]|\\[\x20-\x7e])*)"|([!#$%&'*+.^_`|~0-9A-Za-z-]+))\s*(,|$)/gy;
+    let position = 0;
+    while (position < input.length) {
+        parameter.lastIndex = position;
+        const param = parameter.exec(input);
+        if (!param || (param[4] === ',' && parameter.lastIndex === input.length))
+            return false;
+        const key = param[1].toLowerCase();
+        if (parameters.has(key))
+            return false;
+        parameters.set(key, param[2] === undefined ? param[3] : param[2].replace(/\\([\x20-\x7e])/g, '$1'));
+        position = parameter.lastIndex;
+    }
+    return parameters.get('error') === 'invalid_token' && (parameters.get('scope')?.split(/\s+/).includes('artifacts:read') ?? false);
+}
+async function checkIdentity(resource, request) {
+    const context = { phase: request.kind === 'anonymous' ? 'rest_preflight' : 'authenticated_identity', method: 'GET', url: `${restBase(resource)}/identity` };
+    const response = await boundedFetch(context, request.kind === 'anonymous' ? {} : { signal: request.signal, headers: { authorization: `Bearer ${request.accessToken}` } });
+    if (request.kind === 'anonymous') {
+        if (response.status === 401) {
+            const body = httpErrorSchema.safeParse(await jsonResponse(response, context));
+            if (body.success && body.data.error.code === 'unauthenticated' && compatibleChallenge(response.headers.get('www-authenticate')))
+                return;
+        }
+        throw authFailure(context, response.status >= 500 ? 'service_error' : 'incompatible_resource', response.status >= 500 ? 'REST identity service failed' : 'REST identity route is incompatible. Use the exact REST URL or configure artifacts_rest_resource on the MCP server', response.status);
+    }
+    if (!response.ok)
+        throw authFailure(context, response.status >= 500 ? 'service_error' : response.status === 401 || response.status === 403 ? 'access_denied' : 'incompatible_resource', response.status >= 500 ? 'REST identity service failed' : response.status === 401 || response.status === 403 ? 'OAuth grant cannot access this Artifacts server' : 'REST identity route is unavailable. Confirm the configured REST URL', response.status);
+    const parsed = identitySchema.safeParse(await jsonResponse(response, context));
+    if (!parsed.success)
+        throw authFailure(context, 'invalid_response', 'Invalid REST identity response', response.status);
+    if (request.claims.sub !== parsed.data.userId || (request.claims.sid !== undefined && request.claims.sid !== parsed.data.sessionId))
+        throw authFailure(context, 'invalid_response', 'OAuth identity does not match the Artifacts session', response.status);
+    return parsed.data;
+}
+async function oauth(issuer, signal, operation) {
+    const observations = [];
+    try {
+        const result = await operation(discoveryOptions(issuer, signal, observations));
+        if (result instanceof oidc.Configuration) {
+            validateConfiguration(result, issuer, observations);
+            result[oidc.customFetch] = discoveryOptions(issuer, signal)[oidc.customFetch];
+        }
+        return result;
+    }
+    catch (error) {
+        let cause = error;
+        let observed;
+        for (let depth = 0; depth < 5; depth++) {
+            if (cause instanceof HttpError || cause instanceof AuthTransportError)
+                throw cause;
+            const response = cause instanceof Response ? cause : cause instanceof Error && 'response' in cause ? cause.response : undefined;
+            if (response instanceof Response)
+                observed = observations.find((item) => item.response === response);
+            if (observed || !(cause instanceof Error))
+                break;
+            cause = cause.cause;
+        }
+        observed ??= observations.at(-1);
+        if (observed)
+            throw authFailure(observed.context, 'invalid_response', 'OAuth protocol validation failed', observed.response.status);
+        throw new Error('OAuth protocol validation failed');
+    }
+}
+function discoveryOptions(issuer, signal, observations) {
     endpoint(issuer);
     return {
         timeout: networkTimeout / 1000,
         execute: [...(new URL(issuer).protocol === 'http:' ? [oidc.allowInsecureRequests] : []), oidc.enableNonRepudiationChecks],
-        [oidc.customFetch]: (url, options) => boundedFetch(endpoint(url, issuer), { ...options, signal: signal && options.signal ? AbortSignal.any([signal, options.signal]) : signal ?? options.signal, body: options.body instanceof Uint8Array ? Uint8Array.from(options.body) : options.body }),
+        [oidc.customFetch]: async (url, options) => {
+            const context = { phase: 'oauth', method: options.method ?? 'GET', url };
+            try {
+                endpoint(url, issuer);
+            }
+            catch {
+                throw authFailure({ ...context, url: issuer }, 'invalid_response', 'Invalid OAuth endpoint');
+            }
+            const response = await boundedFetch(context, { ...options, signal: signal && options.signal ? AbortSignal.any([signal, options.signal]) : signal ?? options.signal, body: options.body instanceof Uint8Array ? Uint8Array.from(options.body) : options.body });
+            if (!response.ok)
+                throw authFailure(context, response.status >= 500 ? 'service_error' : 'oauth_error', response.status >= 500 ? 'OAuth service failed' : 'OAuth request failed', response.status);
+            observations?.push({ context, response });
+            return response;
+        },
     };
 }
-function validateConfiguration(config, issuer) {
+function validateConfiguration(config, issuer, observations) {
+    const discovery = observations.find((item) => item.context.method === 'GET');
+    const registration = observations.find((item) => item.context.method === 'POST');
+    if (!discovery)
+        throw new Error('OAuth discovery response was not observed');
+    const failDiscovery = (message) => authFailure(discovery.context, 'invalid_response', message, discovery.response.status);
     const metadata = config.serverMetadata();
     if (metadata.issuer !== issuer)
-        throw new Error('OAuth issuer metadata does not match the configured issuer');
+        throw failDiscovery('OAuth issuer metadata does not match the configured issuer');
     for (const [key, value] of Object.entries(metadata)) {
-        if ((key.endsWith('_endpoint') || key === 'jwks_uri') && typeof value === 'string')
-            endpoint(value, issuer);
+        if ((key.endsWith('_endpoint') || key === 'jwks_uri') && typeof value === 'string') {
+            try {
+                endpoint(value, issuer);
+            }
+            catch (error) {
+                const message = error instanceof Error && error.message === 'OAuth endpoints must use the issuer origin' ? error.message : 'OAuth URLs require HTTPS or an exact loopback HTTP host, without credentials, query, or fragment';
+                throw failDiscovery(message);
+            }
+        }
     }
     if (!metadata.authorization_endpoint || !metadata.token_endpoint)
-        throw new Error('OAuth metadata is missing authorization or token endpoints');
-    if (config.clientMetadata().client_secret || config.clientMetadata().token_endpoint_auth_method !== 'none')
-        throw new Error('The CLI requires a public OAuth client without a secret');
+        throw failDiscovery('OAuth metadata is missing authorization or token endpoints');
+    if (config.clientMetadata().client_secret || config.clientMetadata().token_endpoint_auth_method !== 'none') {
+        const message = 'The CLI requires a public OAuth client without a secret';
+        throw registration ? authFailure(registration.context, 'invalid_response', message, registration.response.status) : new Error(message);
+    }
 }
 async function configuration(registration, signal) {
-    const config = await oidc.discovery(new URL(registration.issuer), registration.clientId, { token_endpoint_auth_method: 'none', id_token_signed_response_alg: 'EdDSA' }, oidc.None(), discoveryOptions(registration.issuer, signal));
-    validateConfiguration(config, registration.issuer);
-    return config;
+    return oauth(registration.issuer, signal, (options) => oidc.discovery(new URL(registration.issuer), registration.clientId, { token_endpoint_auth_method: 'none', id_token_signed_response_alg: 'EdDSA' }, oidc.None(), options));
 }
 function tokenRecord(tokens, previousRefresh) {
     if (typeof tokens.expires_in !== 'number' || !Number.isFinite(tokens.expires_in) || tokens.expires_in <= 0)
@@ -142,7 +287,11 @@ async function openBrowser(url) {
     });
 }
 export async function login(options) {
-    const resource = canonicalResource(options.resource);
+    const source = canonicalResource(options.resource);
+    const metadata = await discoverResource(source);
+    const resource = metadata.restResource ?? source;
+    const { issuer } = resource === source ? metadata : await discoverResource(resource, true);
+    await checkIdentity(resource, { kind: 'anonymous' });
     const store = await CredentialStore.open(options.stateDir);
     let listener;
     try {
@@ -151,14 +300,6 @@ export async function login(options) {
             store.write(resource, { ...profile, epoch: profile.epoch + 1 });
             return profile.epoch + 1;
         });
-        const response = await boundedFetch(protectedResourceMetadataUrl(resource));
-        if (!response.ok)
-            throw new Error('Cannot discover the protected resource');
-        const metadata = resourceMetadata.parse(await response.json());
-        if (metadata.resource !== resource)
-            throw new Error('Protected resource metadata does not match the exact server URL');
-        const issuer = metadata.authorization_servers[0];
-        endpoint(issuer);
         listener = await callback();
         const { redirectUri, signal } = listener;
         const config = await store.exclusive(async () => {
@@ -167,11 +308,10 @@ export async function login(options) {
                 throw new Error('Login was superseded by another login or logout');
             if (profile.registration?.issuer === issuer)
                 return configuration(profile.registration, signal);
-            const registered = await oidc.dynamicClientRegistration(new URL(issuer), {
+            const registered = await oauth(issuer, signal, (options) => oidc.dynamicClientRegistration(new URL(issuer), {
                 client_name: 'Artifacts CLI', application_type: 'native', token_endpoint_auth_method: 'none', id_token_signed_response_alg: 'EdDSA',
                 redirect_uris: [redirectUri], grant_types: ['authorization_code', 'refresh_token'], response_types: ['code'], scope: scopes,
-            }, oidc.None(), discoveryOptions(issuer, signal));
-            validateConfiguration(registered, issuer);
+            }, oidc.None(), options));
             store.write(resource, { ...profile, registration: { issuer, clientId: registered.clientMetadata().client_id }, tokens: null, refreshAttempt: null });
             return registered;
         });
@@ -187,22 +327,21 @@ export async function login(options) {
         if (!options.noBrowser)
             await openBrowser(authorizationUrl);
         const currentUrl = await authorization;
+        if (currentUrl.searchParams.has('error'))
+            throw new Error(currentUrl.searchParams.get('error') === 'access_denied' ? 'Authorization denied' : 'Authorization failed');
         return await store.exclusive(async () => {
             const profile = store.read(resource);
             if (profile.epoch !== epoch)
                 throw new Error('Login was superseded by another login or logout');
-            const tokens = await oidc.authorizationCodeGrant(config, currentUrl, { expectedState: state, expectedNonce: nonce, pkceCodeVerifier: verifier, idTokenExpected: true }, { resource });
+            const tokens = await oauth(issuer, signal, (options) => {
+                config[oidc.customFetch] = options[oidc.customFetch];
+                return oidc.authorizationCodeGrant(config, currentUrl, { expectedState: state, expectedNonce: nonce, pkceCodeVerifier: verifier, idTokenExpected: true }, { resource });
+            });
             const credentials = tokenRecord(tokens);
-            const identityResponse = await boundedFetch(`${restBase(resource)}/identity`, { signal, headers: { authorization: `Bearer ${credentials.accessToken}` } });
-            if (!identityResponse.ok)
-                throw new Error('The OAuth grant cannot access this Artifacts server');
-            const identity = identitySchema.parse(await identityResponse.json());
-            const claims = tokens.claims();
-            if (claims.sub !== identity.userId || (claims.sid !== undefined && claims.sid !== identity.sessionId))
-                throw new Error('OAuth identity does not match the Artifacts session');
+            const identity = await checkIdentity(resource, { kind: 'authenticated', accessToken: credentials.accessToken, signal, claims: tokens.claims() });
             signal.throwIfAborted();
-            store.write(resource, { ...profile, tokens: credentials, refreshAttempt: null });
-            return identity;
+            store.commitLogin(resource, epoch, credentials);
+            return { resource, identity };
         });
     }
     finally {

package/src/credentials.d.ts

@@ -32,6 +32,8 @@ export declare class CredentialStore {
     exclusive<T>(work: () => T | Promise<T>): Promise<T>;
     read(resource: string): CredentialProfile;
     write(resource: string, profile: CredentialProfile): void;
+    readSelectedResource(): string | undefined;
+    commitLogin(resource: string, epoch: number, tokens: Tokens): void;
     close(): void;
 }
 export {};

package/src/credentials.js

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { setTimeout as delay } from 'node:timers/promises';
 import { z } from 'zod';
+import { canonicalResource } from '@yargote/artifacts-contracts/http';
 const registrationSchema = z.strictObject({ issuer: z.string(), clientId: z.string().min(1) });
 const tokensSchema = z.strictObject({ accessToken: z.string().min(1), refreshToken: z.string().min(1).optional(), expiresAt: z.number().finite() });
 const profileSchema = z.strictObject({
@@ -50,6 +51,7 @@ export class CredentialStore {
             await store.exclusive(() => {
                 data.exec('PRAGMA busy_timeout = 0; PRAGMA synchronous = FULL; PRAGMA secure_delete = ON;');
                 data.exec('CREATE TABLE IF NOT EXISTS profiles (resource TEXT PRIMARY KEY, profile TEXT NOT NULL) STRICT');
+                data.exec('CREATE TABLE IF NOT EXISTS selected_resource (id INTEGER PRIMARY KEY CHECK (id = 1), resource TEXT NOT NULL) STRICT');
             });
             return store;
         }
@@ -90,5 +92,25 @@ export class CredentialStore {
     write(resource, profile) {
         this.data.prepare('INSERT INTO profiles(resource, profile) VALUES (?, ?) ON CONFLICT(resource) DO UPDATE SET profile = excluded.profile').run(resource, JSON.stringify(profileSchema.parse(profile)));
     }
+    readSelectedResource() {
+        const row = this.data.prepare('SELECT resource FROM selected_resource WHERE id = 1').get();
+        return row ? canonicalResource(String(row.resource)) : undefined;
+    }
+    commitLogin(resource, epoch, tokens) {
+        canonicalResource(resource);
+        this.data.exec('BEGIN IMMEDIATE');
+        try {
+            const profile = this.read(resource);
+            if (profile.epoch !== epoch)
+                throw new Error('Login was superseded by another login or logout');
+            this.write(resource, { ...profile, tokens, refreshAttempt: null });
+            this.data.prepare('INSERT INTO selected_resource(id, resource) VALUES (1, ?) ON CONFLICT(id) DO UPDATE SET resource = excluded.resource').run(resource);
+            this.data.exec('COMMIT');
+        }
+        catch (error) {
+            this.data.exec('ROLLBACK');
+            throw error;
+        }
+    }
     close() { this.data.close(); this.lock.close(); }
 }

package/src/index.js

@@ -10,12 +10,14 @@ import { createSchema, listSharesSchema, moveSchema, publishSchema, shareSchema,
 import { canonicalResource } from '@yargote/artifacts-contracts/http';
 import { createArtifactHttpClient, HttpError, prepareArtifactEdit } from '@yargote/artifacts-client';
 import { accessToken, login, logout } from "./auth.js";
+import { CredentialStore } from "./credentials.js";
 import { loadOperation, retainOperation, submitOperation } from "./operations.js";
 import { runSkillsCommand } from "./skills.js";
 const help = `Usage: artifacts COMMAND [OPTIONS]
 
 Global options:
-  --server RESOURCE       Canonical OAuth resource, or ARTIFACTS_SERVER
+  --server RESOURCE       Exact REST OAuth resource, or ARTIFACTS_SERVER
+                         Defaults to the last successful login
   --state-dir DIR         Private local state, or ARTIFACTS_STATE_DIR
                          Default: ~/.local/state/artifacts
   --help                 Print this reference
@@ -30,12 +32,14 @@ Commands:
   login [--no-browser]
   logout
   whoami
-  create --snapshot FILE [--project NAME] [--request-id ID]
+  create --snapshot FILE [--project NAME] [--slug SLUG] [--request-id ID]
          [--response full|compact]
   create --command FILE
   list [--limit N] [--cursor CURSOR] [--project NAME]
   projects
   read ID [--revision REV] [--response full|compact] [--out FILE [--quiet]]
+  read --slug SLUG [--project NAME] [--revision REV] [--response full|compact]
+         [--out FILE [--quiet]]
   update ID --snapshot FILE --expected-revision REV [--request-id ID]
          [--response full|compact]
   update [ID] --command FILE
@@ -57,10 +61,23 @@ submission. Retry sends the exact retained command for the same server and owner
 Projects group artifacts by name without regard to letter case. A project
 exists while it contains an artifact. Move changes the project of an artifact
 without creating a revision; --no-project removes it from its project.
+A slug such as concepts/rag names an artifact within its project, or within
+the unfiled artifacts without --project. Read --slug finds it without its ID.
 Read --out saves the returned artifact JSON. Export --out saves the ZIP.
 Read --quiet requires --out and suppresses successful JSON stdout.
 Output files are created exclusively and never overwrite an existing path.
 JSON results go to stdout. Diagnostics and recovery guidance go to stderr.
+Login accepts an MCP URL when its metadata advertises artifacts_rest_resource.
+Split MCP and REST resources require this relation. Login remembers the verified
+REST URL for later commands. --server takes precedence over ARTIFACTS_SERVER,
+which takes precedence over the saved URL. Ordinary overrides do not replace
+the saved URL. Logout keeps it for a later login.
+Login checks <resource>/v1/identity before browser
+authorization. Legacy /mcp
+resources work when their REST API is at /mcp/v1. If the check fails, confirm
+the configured REST URL with your service administrator.
+Login errors report the phase, method, endpoint, and HTTP status when received.
+Network failures have no HTTP status. Login verifies identity again after OAuth.
 ARTIFACTS_ACCESS_TOKEN supplies a token for automation without local login.
 Skills commands work offline without a server, login, or private state.
 They print plain text. Global server and state options are accepted and ignored.
@@ -73,8 +90,8 @@ class UsageError extends Error {
 }
 const commandOptions = {
     login: ['no-browser'], logout: [], whoami: [],
-    create: ['snapshot', 'project', 'request-id', 'response', 'command'],
-    list: ['limit', 'cursor', 'project'], projects: [], read: ['revision', 'response', 'out', 'quiet'],
+    create: ['snapshot', 'project', 'slug', 'request-id', 'response', 'command'],
+    list: ['limit', 'cursor', 'project'], projects: [], read: ['slug', 'project', 'revision', 'response', 'out', 'quiet'],
     update: ['snapshot', 'expected-revision', 'request-id', 'response', 'command'],
     edit: ['changes', 'request-id'], history: ['limit', 'before-sequence', 'summary'],
     publish: ['revision', 'expected-version', 'request-id', 'command'],
@@ -116,7 +133,7 @@ async function main() {
             summary: { type: 'boolean' }, out: { type: 'string' }, quiet: { type: 'boolean' },
             full: { type: 'boolean' }, all: { type: 'boolean' }, agent: { type: 'string' },
             global: { type: 'boolean' }, force: { type: 'boolean' },
-            project: { type: 'string' }, 'no-project': { type: 'boolean' }, email: { type: 'string' }, notify: { type: 'boolean' },
+            project: { type: 'string' }, 'no-project': { type: 'boolean' }, slug: { type: 'string' }, email: { type: 'string' }, notify: { type: 'boolean' },
         },
     });
     const seen = new Set();
@@ -144,11 +161,20 @@ async function main() {
             throw new UsageError(`Option --${option} is not supported by ${command}`);
     if (command === 'skills')
         return runSkillsCommand(arguments_, values, seen);
-    const resourceValue = values.server ?? process.env.ARTIFACTS_SERVER;
-    if (!resourceValue)
-        throw new UsageError('Specify --server RESOURCE or ARTIFACTS_SERVER. No production server is selected by default.');
-    const resource = canonicalResource(resourceValue);
     const stateDir = resolve(values['state-dir'] ?? process.env.ARTIFACTS_STATE_DIR ?? join(homedir(), '.local', 'state', 'artifacts'));
+    let resourceValue = values.server ?? process.env.ARTIFACTS_SERVER;
+    if (resourceValue === undefined) {
+        const store = await CredentialStore.open(stateDir);
+        try {
+            resourceValue = await store.exclusive(() => store.readSelectedResource());
+        }
+        finally {
+            store.close();
+        }
+    }
+    if (resourceValue === undefined)
+        throw new UsageError('No server is saved. Run artifacts login --server RESOURCE or set ARTIFACTS_SERVER.');
+    const resource = canonicalResource(resourceValue);
     function argument(required = true) {
         if (arguments_.length > 1 || (required && arguments_.length !== 1))
             throw new UsageError(`${command} requires ${required ? 'one' : 'zero or one'} positional argument`);
@@ -204,7 +230,12 @@ async function main() {
     switch (command) {
         case 'login':
             none();
-            return login({ resource, stateDir, noBrowser: values['no-browser'] ?? false, onAuthorizationUrl: (url) => { process.stderr.write(`Authorize this login in your browser:\n${url}\n`); } });
+            {
+                const result = await login({ resource, stateDir, noBrowser: values['no-browser'] ?? false, onAuthorizationUrl: (url) => { process.stderr.write(`Authorize this login in your browser:\n${url}\n`); } });
+                if (result.resource !== resource)
+                    process.stderr.write(`REST resource: ${result.resource}\nThis verified REST URL is saved for subsequent commands.\n`);
+                return result.identity;
+            }
         case 'logout':
             none();
             return logout({ resource, stateDir });
@@ -215,7 +246,7 @@ async function main() {
             if (values.command)
                 return mutate(await commandFile('create'));
             none();
-            return mutate({ kind: 'create', command: createSchema.parse({ requestId: values['request-id'] ?? randomUUID(), snapshot: await jsonFile(required('snapshot')), ...(values.project === undefined ? {} : { project: values.project }), ...(response === undefined ? {} : { response }) }) });
+            return mutate({ kind: 'create', command: createSchema.parse({ requestId: values['request-id'] ?? randomUUID(), snapshot: await jsonFile(required('snapshot')), ...(values.project === undefined ? {} : { project: values.project }), ...(values.slug === undefined ? {} : { slug: values.slug }), ...(response === undefined ? {} : { response }) }) });
         }
         case 'list':
             none();
@@ -224,7 +255,12 @@ async function main() {
             none();
             return client.projects();
         case 'read': {
-            const result = await client.read({ artifactId: argument(), ...(values.revision === undefined ? {} : { revisionId: values.revision }), ...(response === undefined ? {} : { response }) });
+            if (values.slug === undefined && values.project !== undefined)
+                throw new UsageError('read --project requires --slug');
+            if ((values.slug === undefined) !== (arguments_.length === 1) || arguments_.length > 1)
+                throw new UsageError('read requires exactly one of an artifact ID or --slug SLUG');
+            const target = values.slug === undefined ? { artifactId: arguments_[0] } : { slug: values.slug, ...(values.project === undefined ? {} : { project: values.project }) };
+            const result = await client.read({ ...target, ...(values.revision === undefined ? {} : { revisionId: values.revision }), ...(response === undefined ? {} : { response }) });
             if (values.out)
                 await writeOutput(values.out, `${JSON.stringify(result, null, 2)}\n`);
             return quiet ? undefined : result;

package/src/operations.d.ts

@@ -16,6 +16,7 @@ export declare const operationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                     text: "text";
                     html: "html";
                     markdown: "markdown";
+                    design: "design";
                 }>;
                 text: z.ZodString;
             }, z.core.$strict>;
@@ -30,6 +31,7 @@ export declare const operationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             }, z.core.$strict>>;
         }, z.core.$strict>;
         project: z.ZodOptional<z.ZodString>;
+        slug: z.ZodOptional<z.ZodString>;
         response: z.ZodOptional<z.ZodEnum<{
             full: "full";
             compact: "compact";
@@ -55,6 +57,7 @@ export declare const operationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                     text: "text";
                     html: "html";
                     markdown: "markdown";
+                    design: "design";
                 }>;
                 text: z.ZodString;
             }, z.core.$strict>;