synomem 0.6.0 → 0.6.2

package/src/cli.ts

@@ -21,14 +21,19 @@ import {
   type ConfigPlan,
   type CredentialStoreChoice,
 } from './configure.js';
-import { discoverBoundWorkspace, discoverOrganizations, workspaceChoices } from './discover.js';
+import {
+  discoverAccessKeyWorkspaces,
+  discoverOrganizations,
+  workspaceChoices,
+  type DiscoveredWorkspace,
+} from './discover.js';
 import { DEFAULT_WORKSPACE, listLocalWorkspaces, localWorkspaceHome } from './workspaces.js';
 import {
   findProjectSelection,
   resolveWorkspaceSelection,
   writeProjectSelection,
 } from './project.js';
-import { defaultPromptIo, type PromptIo } from './prompt.js';
+import { defaultPromptIo, select, type PromptIo } from './prompt.js';
 import { credentialReference, OsCredentialStore, type CredentialStore } from './credentials.js';
 import { asSynomemError, SynomemError, type SynomemErrorCode } from './errors.js';
 import { atomicWriteFile } from './fs-utils.js';
@@ -84,12 +89,12 @@ export interface CliDependencies {
   }) => Promise<void>;
   /*
    * Injected so setup can be tested without a network. The default asks the
-   * service which workspace an access key is bound to.
+   * service which workspaces an access key can reach.
    */
-  discoverBoundWorkspace?: (options: {
+  discoverAccessKeyWorkspaces?: (options: {
     baseUrl: string;
     accessToken: string;
-  }) => Promise<{ workspaceId: string }>;
+  }) => Promise<{ organizationId: string; workspaces: DiscoveredWorkspace[] }>;
   createImportBundle?: (home: string) => Promise<ImportBundle>;
   remoteImport?: (options: {
     baseUrl: string;
@@ -419,7 +424,8 @@ export function createCli(
 
   const credentialStore = dependencies.credentialStore ?? new OsCredentialStore();
   const oauthLogin = dependencies.oauthLogin ?? loginWithOAuth;
-  const discoverWorkspace = dependencies.discoverBoundWorkspace ?? discoverBoundWorkspace;
+  const discoverWorkspaces =
+    dependencies.discoverAccessKeyWorkspaces ?? discoverAccessKeyWorkspaces;
   const promptIo = dependencies.promptIo ?? defaultPromptIo();
   const verifyRemoteCredential =
     dependencies.verifyRemoteCredential ??
@@ -565,12 +571,12 @@ export function createCli(
   const remoteCommand = program.command('remote').description('Administer a remote workspace');
 
   /*
-   * The browser counterpart to an access key naming its own workspace.
-   *
-   * A signed-in account may reach several organizations, each with several
-   * workspaces, so there is a genuine choice to make -- and no way to make it
-   * without seeing the list. Printing the IDs alongside the names is the point:
-   * the ID is what `backend use remote --workspace` takes.
+   * The browser counterpart to `discoverAccessKeyWorkspaces` — same purpose,
+   * different credential: a signed-in account may reach several
+   * organizations, each with several workspaces, so there is a genuine choice
+   * to make, and no way to make it without seeing the list. Printing the IDs
+   * alongside the names is the point: the ID is what `backend use remote
+   * --workspace` takes.
    */
   remoteCommand
     .command('workspaces')
@@ -655,6 +661,8 @@ export function createCli(
                     credentialReference(backend.baseUrl, backend.workspaceId, administrator),
                     credentialStore,
                     env,
+                    fetch,
+                    resolveHome(global.home),
                   );
               const importer = new RemoteImportClient({
                 baseUrl: backend.baseUrl,
@@ -723,18 +731,63 @@ export function createCli(
     const serviceUrl = plan.serviceUrl ?? cloudApiUrl(env);
 
     /*
-     * The workspace is discovered, not typed.
-     *
-     * An installation access key is bound to exactly one workspace, so the
-     * service can be asked which one rather than the person. An explicit
-     * --workspace still wins, because automation should not depend on a
-     * network round trip to configure a machine.
+     * A member-owned access key reaches every workspace in its organization,
+     * never just one, so the workspace is discovered and then chosen — not
+     * typed from memory, and not assumed. An explicit --workspace still wins
+     * regardless: automation should not depend on a network round trip, and a
+     * person who already knows which one they want should not be asked again.
      */
     let workspaceId = plan.workspaceId;
     if (plan.backend === 'remote' && !workspaceId && token) {
-      const bound = await discoverWorkspace({ baseUrl: serviceUrl, accessToken: token });
-      workspaceId = bound.workspaceId;
-      io.stdout(`Access key is bound to workspace ${workspaceId}.\n`);
+      const discovered = await discoverWorkspaces({ baseUrl: serviceUrl, accessToken: token });
+      if (discovered.workspaces.length === 0) {
+        throw new SynomemError(
+          'INVALID_INPUT',
+          [
+            "This access key's organization has no workspaces yet.",
+            'Create one in the Synomem portal, then re-run this command — or pass',
+            '--workspace <workspace-id> once one exists.',
+          ].join('\n'),
+        );
+      } else if (discovered.workspaces.length === 1) {
+        workspaceId = discovered.workspaces[0]!.id;
+        /*
+         * The key itself reaches every workspace this organization has —
+         * there is just one to choose from today. Wording this as the key's
+         * own workspace ("this key's workspace") was a repeated, corrected
+         * mistake: it is this MACHINE's choice of which workspace to act in
+         * with the key, not a property of the key.
+         */
+        io.stdout(
+          `This machine will use ${discovered.workspaces[0]!.displayName} (${workspaceId}) — ` +
+            'the only workspace this key currently reaches. Run `synomem backend use ' +
+            'remote --workspace <workspace-id>` to point it at a different one later.\n',
+        );
+      } else if (promptIo.interactive) {
+        workspaceId = await select(
+          promptIo,
+          'Which workspace should this machine use?',
+          discovered.workspaces.map((workspace) => ({
+            value: workspace.id,
+            label: workspace.displayName,
+            detail: workspace.id,
+          })),
+        );
+      } else {
+        throw new SynomemError(
+          'INVALID_INPUT',
+          [
+            'This access key can reach more than one workspace, so a non-interactive',
+            'setup needs to be told which one:',
+            '',
+            ...discovered.workspaces.map(
+              (workspace) => `  ${workspace.id}  ${workspace.displayName}`,
+            ),
+            '',
+            'Re-run with --workspace <workspace-id>.',
+          ].join('\n'),
+        );
+      }
     }
     if (plan.backend === 'remote' && !workspaceId) {
       /*
@@ -846,7 +899,7 @@ export function createCli(
     .option('--credential-store <where>', 'auto, keychain, file, or environment', 'auto')
     // The token is read from stdin, never taken as an argument: an argument is
     // kept by the shell history and visible in the process list.
-    .option('--access-token-stdin', 'read the installation access key from stdin', false)
+    .option('--access-token-stdin', 'read the access key from stdin', false)
     .option('--yes', 'apply without confirming', false)
     .action(
       async (
@@ -864,12 +917,12 @@ export function createCli(
           throw new SynomemError('INVALID_INPUT', 'Pass --backend local or --backend remote.');
         }
         const backend: BackendChoice = options.backend;
-        // An access key names its own workspace, so --workspace is only
-        // required when there is no key to ask.
+        // An access key can be asked which workspaces it reaches, so
+        // --workspace is only required when there is no key to ask.
         if (backend === 'remote' && !global.workspace && !options.accessTokenStdin) {
           throw new SynomemError(
             'INVALID_INPUT',
-            'Remote setup requires --workspace, or --access-token-stdin so the key can name its own.',
+            'Remote setup requires --workspace, or --access-token-stdin so the key can be asked.',
           );
         }
         const token = options.accessTokenStdin ? await readAccessToken(promptIo) : undefined;

package/src/configure.ts

@@ -7,7 +7,7 @@
  * that blocks forever on a pipe is worse than one that says which flags it
  * needs.
  */
-import { chmodSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { cloudApiUrl } from './cloud.js';
 import { SynomemError } from './errors.js';
@@ -117,16 +117,39 @@ export function assertInteractive(io: PromptIo): void {
  * Separate from `config.json` so a configuration file can be read, copied or
  * pasted into an issue without carrying a secret with it.
  */
+function credentialFilePath(home: string): string {
+  return join(home, 'credentials', 'installation.json');
+}
+
 export function writeCredentialFile(home: string, token: string): string {
   const directory = join(home, 'credentials');
   mkdirSync(directory, { recursive: true, mode: 0o700 });
   chmodSync(directory, 0o700);
-  const path = join(directory, 'installation.json');
+  const path = credentialFilePath(home);
   writeFileSync(path, `${JSON.stringify({ accessToken: token }, null, 2)}\n`, { mode: 0o600 });
   chmodSync(path, 0o600);
   return path;
 }
 
+/**
+ * Reads back what `writeCredentialFile` wrote.
+ *
+ * Without this, choosing the restricted-file store at `synomem config` wrote
+ * a credential nothing ever read again: every later command still asked the
+ * OS keychain, found nothing there, and failed with AUTH_REQUIRED even though
+ * the key was sitting right there on disk.
+ */
+export function readCredentialFile(home: string): string | undefined {
+  const path = credentialFilePath(home);
+  if (!existsSync(path)) return undefined;
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as { accessToken?: unknown };
+    return typeof parsed.accessToken === 'string' ? parsed.accessToken : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** A key's identifying prefix. Never the key. */
 export function credentialFingerprint(token: string): string {
   const head = token.slice(0, 12);
@@ -194,8 +217,8 @@ export async function runConfigWizard(
     },
     {
       value: 'access-key',
-      label: 'Use an installation access key',
-      detail: 'Create one at https://portal.synomem.ai/installations',
+      label: 'Use an access key',
+      detail: 'Create one at https://portal.synomem.ai/access-keys/new',
     },
   ]);
 
@@ -203,10 +226,11 @@ export async function runConfigWizard(
    * Deliberately no workspace prompt here.
    *
    * A hosted workspace ID looks like `ws-04psqx2rkt8ttft7a1t2z69r97`, and the
-   * credential authorized in the next step already knows which workspace it
-   * reaches -- an installation key is bound to exactly one, and a browser
-   * sign-in can list the ones the account belongs to. Asking first means
-   * asking a person to go and look something up that we are about to be told.
+   * credential authorized in the next step already knows the answer -- an
+   * access key can list every workspace its organization has, and a browser
+   * sign-in can list the ones the account belongs to across every
+   * organization. Asking first means asking a person to go and look something
+   * up that we are about to be told.
    */
 
   const credentialStore =
@@ -223,7 +247,7 @@ export async function runConfigWizard(
 
 /** Reads an access key without ever accepting it as an argument. */
 export async function readAccessToken(io: PromptIo): Promise<string> {
-  const token = await askSecret(io, 'Installation access key');
+  const token = await askSecret(io, 'Access key');
   if (!token) throw new SynomemError('INVALID_INPUT', 'No access key was provided.');
   return token;
 }

package/src/credentials.ts

@@ -7,12 +7,19 @@ const serviceName = 'ai.synomem.credentials';
 const maximumOutputBytes = 128 * 1024;
 
 /**
- * An installation access key.
+ * A member-owned access key.
  *
- * Not an OAuth credential: it has no refresh, no token endpoint and no client,
- * and it authorizes a MACHINE rather than a person. Keeping it a distinct shape
- * stops code treating it as refreshable, which would mean silently failing to
- * renew something that never expires that way.
+ * Not an OAuth credential: it has no refresh, no token endpoint and no
+ * client, and it authorizes the MEMBER who created it, reaching every
+ * workspace their organization membership allows -- never a single machine
+ * or a single workspace. Keeping it a distinct shape stops code treating it
+ * as refreshable, which would mean silently failing to renew something that
+ * never expires that way.
+ *
+ * The `kind` value and this type's own name predate member-owned access
+ * keys; both still say "installation" because renaming either changes the
+ * shape already written to disk and the OS keychain on every machine that
+ * has run `synomem config`, for no behavioral gain.
  */
 export interface StoredInstallationKey {
   kind: 'installation-key';

package/src/discover.ts

@@ -1,5 +1,5 @@
 /*
- * Finding out which workspace a credential belongs to, so nobody has to type
+ * Finding out which workspaces a credential can reach, so nobody has to type
  * one from memory.
  *
  * A hosted workspace ID looks like `ws-04psqx2rkt8ttft7a1t2z69r97`. Asking a
@@ -9,11 +9,12 @@
  *
  * Two credentials, two routes, because they carry different authority:
  *
- *   An installation access key is bound to exactly one workspace. There is
- *   nothing to choose, so `discoverBoundWorkspace` reads it off the data plane
- *   and setup asks nothing at all.
+ *   A member-owned access key authenticates the ACCOUNT that created it, and
+ *   reaches every workspace in that account's organization -- never just one
+ *   -- so `discoverAccessKeyWorkspaces` lists them off the data plane, with no
+ *   workspace chosen yet, which is exactly what setup cannot supply up front.
  *
- *   A browser sign-in authorizes an ACCOUNT, which may reach several
+ *   A browser sign-in also authorizes an ACCOUNT, which may reach several
  *   organizations, each with several workspaces. `discoverOrganizations` lists
  *   them for selection.
  */
@@ -82,23 +83,21 @@ async function readJson<T>(options: DiscoveryOptions, path: string): Promise<T>
 }
 
 /**
- * The single workspace an installation access key can address.
+ * Every workspace a member-owned access key can reach, asked before any one
+ * of them has been chosen.
  *
- * Answered by the data plane rather than the control plane: an installation key
- * is not an account principal, so it cannot list organizations, but it can
- * always say where it is bound.
+ * Answered by the data plane rather than the control plane: an access key is
+ * not an account principal the control plane recognizes, but the data plane
+ * already knows which organization owns it and can list that organization's
+ * workspaces without requiring one to be named first.
  */
-export async function discoverBoundWorkspace(
+export async function discoverAccessKeyWorkspaces(
   options: DiscoveryOptions,
-): Promise<{ workspaceId: string; actor: { kind: string; id: string; displayName?: string } }> {
-  const identity = await readJson<{
-    workspaceId: string;
-    actor: { kind: string; id: string; displayName?: string };
-  }>(options, 'v1/identity');
-  if (!identity.workspaceId) {
-    throw new SynomemError('REMOTE_PROTOCOL', 'The service did not report a bound workspace.');
-  }
-  return { workspaceId: identity.workspaceId, actor: identity.actor };
+): Promise<{ organizationId: string; workspaces: DiscoveredWorkspace[] }> {
+  return await readJson<{ organizationId: string; workspaces: DiscoveredWorkspace[] }>(
+    options,
+    'v1/access-keys/workspaces',
+  );
 }
 
 /**

package/src/index.ts

@@ -58,7 +58,11 @@ export {
   writeProjectSelection,
 } from './project.js';
 export type { ProjectConfig, ProjectSelection } from './project.js';
-export { discoverBoundWorkspace, discoverOrganizations, workspaceChoices } from './discover.js';
+export {
+  discoverAccessKeyWorkspaces,
+  discoverOrganizations,
+  workspaceChoices,
+} from './discover.js';
 export type { DiscoveredOrganization, DiscoveredWorkspace, DiscoveryOptions } from './discover.js';
 export { asSynomemError, errorCodes, SynomemError } from './errors.js';
 export {

package/src/oauth.ts

@@ -8,6 +8,7 @@ import {
 import { SynomemError } from './errors.js';
 import type { CredentialStore, StoredOAuthCredential } from './credentials.js';
 import type { SynomemCredentialProvider } from './remote.js';
+import { readCredentialFile } from './configure.js';
 
 const defaultScope = 'synomem:read synomem:write offline_access';
 
@@ -195,6 +196,8 @@ export async function loginWithOAuth(options: OAuthLoginOptions): Promise<void>
 export class StoredCredentialProvider implements SynomemCredentialProvider {
   private refresh?: Promise<string | undefined>;
   private credential?: StoredOAuthCredential;
+  /** Set when the stored credential is an access key rather than an OAuth grant. */
+  private staticAccessToken?: string;
   private loaded = false;
 
   constructor(
@@ -202,6 +205,12 @@ export class StoredCredentialProvider implements SynomemCredentialProvider {
     private readonly store: CredentialStore,
     private readonly env: NodeJS.ProcessEnv = process.env,
     private readonly fetchImplementation: typeof fetch = fetch,
+    /**
+     * Where `synomem config`'s restricted-file credential store, if chosen,
+     * would have written an access key. Optional because local-only and
+     * environment-only callers have no such file to fall back to.
+     */
+    private readonly home?: string,
   ) {}
 
   async getAccessToken(signal?: AbortSignal): Promise<string | undefined> {
@@ -209,14 +218,20 @@ export class StoredCredentialProvider implements SynomemCredentialProvider {
     if (!this.loaded) {
       const stored = await this.store.get(this.reference);
       /*
-       * An installation key is not an OAuth credential: it cannot be refreshed
-       * and has no client or token endpoint. Treating one as OAuth would mean
-       * trying to renew something that never renews that way, so this path
-       * ignores it and lets the installation-key path handle it.
+       * An access key is not an OAuth credential: it cannot be refreshed and
+       * has no client or token endpoint. It is used exactly as stored,
+       * whichever of the two places it was found.
        */
-      this.credential = stored && 'kind' in stored ? undefined : stored;
+      if (stored && 'kind' in stored) {
+        this.staticAccessToken = stored.accessToken;
+      } else if (stored) {
+        this.credential = stored;
+      } else if (this.home) {
+        this.staticAccessToken = readCredentialFile(this.home);
+      }
       this.loaded = true;
     }
+    if (this.staticAccessToken) return this.staticAccessToken;
     const credential = this.credential;
     if (!credential) return undefined;
     if (!credential.expiresAt || credential.expiresAt > Date.now()) return credential.accessToken;

package/src/remote.ts

@@ -647,6 +647,15 @@ export class RemoteSynomemService implements SynomemService {
         headers: {
           accept: 'application/json',
           authorization: `Bearer ${accessToken}`,
+          /*
+           * Harmless for an OAuth actor token (its workspace and identity are
+           * already bound into the token itself), and required for an access
+           * key: an access key authenticates the member who owns it, not a
+           * machine or a workspace, so which workspace and which agent are
+           * meant have to be named on every request.
+           */
+          'synomem-workspace-id': this.workspaceId,
+          ...(this.actor.kind === 'agent' ? { 'synomem-agent-id': this.actor.id } : {}),
           ...(body ? { 'content-type': 'application/json' } : {}),
           ...(idempotencyKey ? { 'idempotency-key': idempotencyKey } : {}),
         },