synomem 0.7.2 → 0.9.0

package/src/credentials.ts

@@ -1,42 +1,78 @@
-import { createHash } from 'node:crypto';
+/**
+ * Credential storage, indexed by connection — never by actor or workspace.
+ *
+ * One stored secret serves every profile that routes through its connection:
+ * adding a profile for another agent or workspace never copies a refresh
+ * token, and rotating a credential updates exactly one entry. Which actor and
+ * workspace an operation uses is the profile's business (see `profiles.ts`),
+ * and the server authorizes it on every request regardless of what is stored
+ * here.
+ *
+ * Two credential kinds, deliberately distinct so nothing tries to refresh a
+ * key or treat an OAuth family as a static secret:
+ *
+ *   - `oauth`: an authorization-code family for one connection, refreshed
+ *     under a cross-process lock with a generation counter;
+ *   - `access-key`: a member-owned `syn_…` key, used exactly as stored.
+ *
+ * Backends: the macOS Keychain, Linux Secret Service (`secret-tool`), an
+ * explicit restricted file, or the process environment. There is no silent
+ * fallback from one to another: a keychain that refuses a write is an error
+ * that names the explicit alternative.
+ */
 import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  unlinkSync,
+  writeSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
 import { SynomemError } from './errors.js';
-import type { ActorIdentity } from './types.js';
+import { atomicWriteFile } from './fs-utils.js';
 
 const serviceName = 'ai.synomem.credentials';
 const maximumOutputBytes = 128 * 1024;
 
-/**
- * A member-owned access key.
- *
- * 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';
-  accessToken: string;
-}
+export const storedOAuthCredentialSchema = z.object({
+  kind: z.literal('oauth'),
+  issuer: z.string().min(1),
+  resource: z.string().min(1),
+  clientId: z.string().min(1),
+  tokenEndpoint: z.string().min(1),
+  scope: z.string(),
+  accessToken: z.string().min(1),
+  refreshToken: z.string().min(1).optional(),
+  /** Epoch milliseconds, already reduced by a safety margin. */
+  expiresAt: z.number().int().nonnegative(),
+  /** Incremented on every successful refresh; the compare-and-swap token. */
+  generation: z.number().int().nonnegative(),
+});
 
-export type StoredCredential = StoredOAuthCredential | StoredInstallationKey;
+export const storedAccessKeySchema = z.object({
+  kind: z.literal('access-key'),
+  secret: z.string().min(1),
+});
 
-export interface StoredOAuthCredential {
-  accessToken: string;
-  refreshToken?: string;
-  expiresAt?: number;
-  tokenEndpoint: string;
-  clientId: string;
-  resource: string;
-  scope: string;
-}
+export const storedCredentialSchema = z.discriminatedUnion('kind', [
+  storedOAuthCredentialSchema,
+  storedAccessKeySchema,
+]);
+
+export type StoredOAuthCredential = z.infer<typeof storedOAuthCredentialSchema>;
+export type StoredAccessKey = z.infer<typeof storedAccessKeySchema>;
+export type StoredCredential = z.infer<typeof storedCredentialSchema>;
+
+/** Where a connection's secret lives. `environment` stores nothing. */
+export type CredentialBackendKind = 'keychain' | 'file' | 'environment';
 
 export interface CredentialStore {
   get(reference: string): Promise<StoredCredential | undefined>;
@@ -44,20 +80,26 @@ export interface CredentialStore {
   delete(reference: string): Promise<boolean>;
 }
 
-export function credentialReference(
-  baseUrl: string,
-  workspaceId: string,
-  actor: ActorIdentity,
-): string {
-  return createHash('sha256')
-    .update(
-      JSON.stringify({
-        baseUrl: new URL(baseUrl).origin,
-        workspaceId,
-        actor: { kind: actor.kind, id: actor.id },
-      }),
-    )
-    .digest('base64url');
+/** An opaque, non-secret handle for a stored secret. Never derived from names. */
+export function newSecretReference(): string {
+  return `synomem-${randomUUID()}`;
+}
+
+export function parseStoredCredential(value: string): StoredCredential {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(value);
+  } catch {
+    throw new SynomemError('AUTH_REQUIRED', 'Stored Synomem credential is malformed.');
+  }
+  const parsed = storedCredentialSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new SynomemError(
+      'AUTH_REQUIRED',
+      'Stored Synomem credential is in an unsupported format. Run `synomem connection login` (or `connection add-key`) again.',
+    );
+  }
+  return parsed.data;
 }
 
 interface CommandResult {
@@ -105,24 +147,7 @@ async function command(
   });
 }
 
-function parseCredential(value: string): StoredOAuthCredential {
-  try {
-    const parsed = JSON.parse(value) as Partial<StoredOAuthCredential>;
-    if (
-      typeof parsed.accessToken !== 'string' ||
-      typeof parsed.tokenEndpoint !== 'string' ||
-      typeof parsed.clientId !== 'string' ||
-      typeof parsed.resource !== 'string' ||
-      typeof parsed.scope !== 'string'
-    ) {
-      throw new Error();
-    }
-    return parsed as StoredOAuthCredential;
-  } catch {
-    throw new SynomemError('AUTH_REQUIRED', 'Stored Synomem credentials are malformed.');
-  }
-}
-
+/** macOS Keychain or Linux Secret Service. */
 export class OsCredentialStore implements CredentialStore {
   private readonly platform: NodeJS.Platform;
   private readonly run: CredentialCommandRunner;
@@ -132,7 +157,7 @@ export class OsCredentialStore implements CredentialStore {
     this.run = options.run ?? command;
   }
 
-  async get(reference: string): Promise<StoredOAuthCredential | undefined> {
+  async get(reference: string): Promise<StoredCredential | undefined> {
     const result =
       this.platform === 'darwin'
         ? await this.run('/usr/bin/security', [
@@ -147,11 +172,11 @@ export class OsCredentialStore implements CredentialStore {
           ? await this.run('secret-tool', ['lookup', 'service', serviceName, 'account', reference])
           : this.unsupported();
     if (result.code !== 0) return undefined;
-    return parseCredential(result.stdout.trim());
+    return parseStoredCredential(result.stdout.trim());
   }
 
-  async set(reference: string, credential: StoredOAuthCredential): Promise<void> {
-    const serialized = JSON.stringify(credential);
+  async set(reference: string, credential: StoredCredential): Promise<void> {
+    const serialized = JSON.stringify(storedCredentialSchema.parse(credential));
     const result =
       this.platform === 'darwin'
         ? await this.run(
@@ -163,7 +188,7 @@ export class OsCredentialStore implements CredentialStore {
               '-s',
               serviceName,
               '-l',
-              'Synomem OAuth credential',
+              'Synomem credential',
               '-U',
               '-w',
             ],
@@ -172,21 +197,14 @@ export class OsCredentialStore implements CredentialStore {
         : this.platform === 'linux'
           ? await this.run(
               'secret-tool',
-              [
-                'store',
-                '--label=Synomem OAuth credential',
-                'service',
-                serviceName,
-                'account',
-                reference,
-              ],
+              ['store', '--label=Synomem credential', 'service', serviceName, 'account', reference],
               serialized,
             )
           : this.unsupported();
     if (result.code !== 0) {
       throw new SynomemError(
-        'AUTH_REQUIRED',
-        'The operating-system credential store rejected the credential.',
+        'CONFIG_INVALID',
+        'The operating-system credential store rejected the credential. Re-run with --store file to use a restricted file instead.',
       );
     }
   }
@@ -208,17 +226,123 @@ export class OsCredentialStore implements CredentialStore {
   }
 
   /*
-   * Windows Credential Manager is not implemented yet. `cmdkey` can write a
-   * generic credential but deliberately will not read the secret back, so a
-   * store built on it would accept a credential and then never return it --
-   * worse than saying so plainly.
+   * Windows Credential Manager is not implemented: `cmdkey` can write a generic
+   * credential but will not read the secret back, so a store built on it would
+   * accept a credential and never return it.
    */
   private unsupported(): never {
     throw new SynomemError(
       'CONFIG_INVALID',
       this.platform === 'win32'
-        ? 'Windows Credential Manager storage is not supported yet. Run `synomem config init` and choose the restricted-file store, or set SYNOMEM_ACCESS_TOKEN.'
-        : 'Operating-system credential storage needs the macOS Keychain, or secret-tool on Linux. Run `synomem config init` and choose the restricted-file store, or set SYNOMEM_ACCESS_TOKEN.',
+        ? 'Windows Credential Manager storage is not supported yet. Use --store file, or --store environment with SYNOMEM_ACCESS_TOKEN.'
+        : 'Operating-system credential storage needs the macOS Keychain, or secret-tool on Linux. Use --store file, or --store environment with SYNOMEM_ACCESS_TOKEN.',
+    );
+  }
+}
+
+/**
+ * One restricted file per secret under `<home>/credentials/`, mode 0600 in a
+ * 0700 directory. Chosen explicitly (`--store file`), never as a fallback.
+ */
+export class FileCredentialStore implements CredentialStore {
+  private readonly directory: string;
+
+  constructor(home: string) {
+    this.directory = join(home, 'credentials');
+  }
+
+  private path(reference: string): string {
+    if (!/^[A-Za-z0-9_-]{1,100}$/.test(reference)) {
+      throw new SynomemError('CONFIG_INVALID', 'Credential reference is malformed.');
+    }
+    return join(this.directory, `${reference}.json`);
+  }
+
+  async get(reference: string): Promise<StoredCredential | undefined> {
+    const path = this.path(reference);
+    if (!existsSync(path)) return undefined;
+    return parseStoredCredential(readFileSync(path, 'utf8'));
+  }
+
+  async set(reference: string, credential: StoredCredential): Promise<void> {
+    if (!existsSync(this.directory)) mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+    chmodSync(this.directory, 0o700);
+    atomicWriteFile(
+      this.path(reference),
+      `${JSON.stringify(storedCredentialSchema.parse(credential))}\n`,
+      0o600,
     );
   }
+
+  async delete(reference: string): Promise<boolean> {
+    const path = this.path(reference);
+    if (!existsSync(path)) return false;
+    rmSync(path, { force: true });
+    return true;
+  }
+}
+
+export interface CredentialStores {
+  keychain: CredentialStore;
+  file: CredentialStore;
+}
+
+export function defaultCredentialStores(home: string): CredentialStores {
+  return { keychain: new OsCredentialStore(), file: new FileCredentialStore(home) };
+}
+
+/**
+ * A cross-process lock around one credential's refresh.
+ *
+ * `O_EXCL` creation is the mutual exclusion; a lock older than `staleMs` is
+ * from a crashed process and is broken. The lock only serializes refreshes —
+ * correctness against a concurrent writer is the generation compare-and-swap
+ * in `refreshCredential`.
+ */
+export async function withCredentialLock<T>(
+  home: string,
+  name: string,
+  operation: () => Promise<T>,
+  options: { staleMs?: number; timeoutMs?: number; pollMs?: number } = {},
+): Promise<T> {
+  if (!/^[A-Za-z0-9_.-]{1,100}$/.test(name)) {
+    throw new SynomemError('CONFIG_INVALID', 'Credential name is malformed.');
+  }
+  const directory = join(home, 'locks');
+  if (!existsSync(directory)) mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const path = join(directory, `${name}.lock`);
+  const staleMs = options.staleMs ?? 60_000;
+  const deadline = Date.now() + (options.timeoutMs ?? 30_000);
+  const pollMs = options.pollMs ?? 50;
+  let descriptor: number | undefined;
+  while (descriptor === undefined) {
+    try {
+      descriptor = openSync(path, 'wx', 0o600);
+      writeSync(descriptor, `${process.pid}\n`);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      try {
+        if (Date.now() - statSync(path).mtimeMs > staleMs) {
+          unlinkSync(path);
+          continue;
+        }
+      } catch {
+        // Removed between the failed open and the stat: try again at once.
+        continue;
+      }
+      if (Date.now() > deadline) {
+        throw new SynomemError(
+          'DATABASE_BUSY',
+          `Another Synomem process is refreshing the ${name} credential. Try again.`,
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+  }
+  try {
+    return await operation();
+  } finally {
+    closeSync(descriptor);
+    rmSync(path, { force: true });
+  }
 }

package/src/discover.ts

@@ -1,24 +1,18 @@
 /*
- * Finding out which workspaces a credential can reach, so nobody has to type
- * one from memory.
+ * Finding out what a credential can reach, so nobody has to type an id from memory.
  *
- * A hosted workspace ID looks like `ws-04psqx2rkt8ttft7a1t2z69r97`. Asking a
- * person to enter that during setup is asking them to leave and go find it, and
- * the credential they just authorized already knows the answer -- or knows
- * enough to offer a short list.
+ * Two questions, two routes, because they carry different authority:
  *
- * Two credentials, two routes, because they carry different authority:
+ *   `discoverContexts` / `describeIdentity` ask the DATA plane, with any credential
+ *   (OAuth access token or `syn_` access key), which workspace/actor targets that
+ *   credential's grant may use right now (identity contract §4). No context has to be
+ *   chosen first — that is the point.
  *
- *   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 also authorizes an ACCOUNT, which may reach several
- *   organizations, each with several workspaces. `discoverOrganizations` lists
- *   them for selection.
+ *   `discoverOrganizations` asks the control plane which organizations an account
+ *   belongs to, for first-party setup flows that hold an account session.
  */
 import { SynomemError } from './errors.js';
+import type { ContextListing, IdentityDescription } from './types.js';
 
 export interface DiscoveredWorkspace {
   id: string;
@@ -47,7 +41,11 @@ interface Envelope<T> {
   error?: { code?: string; message?: string };
 }
 
-async function readJson<T>(options: DiscoveryOptions, path: string): Promise<T> {
+async function readJson<T>(
+  options: DiscoveryOptions,
+  path: string,
+  extraHeaders?: Record<string, string>,
+): Promise<T> {
   const request = options.fetch ?? globalThis.fetch;
   const url = new URL(
     path,
@@ -56,7 +54,11 @@ async function readJson<T>(options: DiscoveryOptions, path: string): Promise<T>
   let response: Response;
   try {
     response = await request(url, {
-      headers: { authorization: `Bearer ${options.accessToken}`, accept: 'application/json' },
+      headers: {
+        authorization: `Bearer ${options.accessToken}`,
+        accept: 'application/json',
+        ...extraHeaders,
+      },
       ...(options.signal ? { signal: options.signal } : {}),
     });
   } catch (error) {
@@ -74,32 +76,24 @@ async function readJson<T>(options: DiscoveryOptions, path: string): Promise<T>
   if (!response.ok || body.ok !== true || body.data === undefined) {
     // 401 and 403 are the ones a person can act on, so they keep their own
     // codes rather than being flattened into a generic protocol error.
+    const reported = body.error?.code;
     const code =
-      response.status === 401 ? 'AUTH_REQUIRED' : response.status === 403 ? 'AUTH_FORBIDDEN' : null;
+      reported === 'CONTEXT_REQUIRED' ||
+      reported === 'CONTEXT_FORBIDDEN' ||
+      reported === 'CONTEXT_AMBIGUOUS' ||
+      reported === 'REAUTHORIZATION_REQUIRED'
+        ? reported
+        : response.status === 401
+          ? 'AUTH_REQUIRED'
+          : response.status === 403
+            ? 'AUTH_FORBIDDEN'
+            : null;
     const message = body.error?.message ?? `${url.pathname} returned ${response.status}.`;
     throw new SynomemError(code ?? 'REMOTE_PROTOCOL', message);
   }
   return body.data;
 }
 
-/**
- * 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 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 discoverAccessKeyWorkspaces(
-  options: DiscoveryOptions,
-): Promise<{ organizationId: string; workspaces: DiscoveredWorkspace[] }> {
-  return await readJson<{ organizationId: string; workspaces: DiscoveredWorkspace[] }>(
-    options,
-    'v1/access-keys/workspaces',
-  );
-}
-
 /**
  * Every organization this account belongs to, each with its workspaces.
  *
@@ -133,6 +127,36 @@ export async function discoverOrganizations(
   return organizations;
 }
 
+/**
+ * Every context this credential's grant may use right now, with canonical ids
+ * (`GET /v1/contexts`). Follows `nextCursor` until the listing is complete, bounded.
+ */
+export async function discoverContexts(options: DiscoveryOptions): Promise<ContextListing> {
+  let listing: ContextListing | undefined;
+  let cursor: string | null | undefined;
+  for (let page = 0; page < 20; page += 1) {
+    const next: ContextListing = await readJson<ContextListing>(
+      options,
+      `v1/contexts?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ''}`,
+    );
+    listing = listing ? { ...next, contexts: [...listing.contexts, ...next.contexts] } : next;
+    cursor = next.nextCursor;
+    if (!cursor) break;
+  }
+  return { ...listing!, nextCursor: null };
+}
+
+/** Who this credential is: account, connection, grant, and effective context if selected. */
+export async function describeIdentity(
+  options: DiscoveryOptions & { contextId?: string },
+): Promise<IdentityDescription> {
+  return await readJson<IdentityDescription>(
+    options,
+    'v1/identity',
+    options.contextId ? { 'synomem-context-id': options.contextId } : undefined,
+  );
+}
+
 /** Flattens discovery into the choices a person picks from. */
 export function workspaceChoices(
   organizations: DiscoveredOrganization[],

package/src/errors.ts

@@ -30,6 +30,11 @@ export const errorCodes = [
   'CONFIG_INVALID',
   'AUTH_REQUIRED',
   'AUTH_FORBIDDEN',
+  'CONTEXT_REQUIRED',
+  'CONTEXT_FORBIDDEN',
+  'CONTEXT_AMBIGUOUS',
+  'REAUTHORIZATION_REQUIRED',
+  'UNSUPPORTED_BACKEND',
   'REMOTE_UNAVAILABLE',
   'REMOTE_PROTOCOL',
   'RATE_LIMITED',

package/src/import.ts

@@ -169,6 +169,8 @@ export async function createLocalImportBundle(fromHome: string): Promise<ImportB
 export interface RemoteImportClientOptions {
   baseUrl: string;
   workspaceId: string;
+  /** The selected context; sent as Synomem-Context-Id (identity contract §3). */
+  contextId?: string;
   credentialProvider: SynomemCredentialProvider;
   fetch?: typeof fetch;
 }
@@ -176,6 +178,7 @@ export interface RemoteImportClientOptions {
 export class RemoteImportClient {
   private readonly baseUrl: URL;
   private readonly workspaceId: string;
+  private readonly contextId: string | undefined;
   private readonly credentialProvider: SynomemCredentialProvider;
   private readonly fetchImplementation: typeof fetch;
 
@@ -195,6 +198,7 @@ export class RemoteImportClient {
       throw new SynomemError('CONFIG_INVALID', 'Remote import baseUrl must be an origin.');
     }
     this.workspaceId = options.workspaceId;
+    this.contextId = options.contextId;
     this.credentialProvider = options.credentialProvider;
     this.fetchImplementation = options.fetch ?? fetch;
   }
@@ -224,6 +228,7 @@ export class RemoteImportClient {
           accept: 'application/json',
           authorization: `Bearer ${token}`,
           'content-type': 'application/json',
+          ...(this.contextId ? { 'synomem-context-id': this.contextId } : {}),
         },
         body: JSON.stringify(payload),
       });

package/src/index.ts

@@ -2,22 +2,24 @@ export { SynomemClient, SynomemCore } from './client.js';
 export type { SynomemCoreOptions } from './client.js';
 export type { ProjectionWriter } from './ports/projections.js';
 export type { SynomemRepository } from './ports/repository.js';
-export {
-  configuredServiceFactory,
-  createConfiguredService,
-  readSynomemConfig,
-  writeSynomemBackend,
-} from './backend.js';
+export { readSynomemConfig } from './backend.js';
 export { RemoteSynomemService, environmentCredentialProvider } from './remote.js';
-export type { SynomemCredentialProvider, RemoteSynomemOptions } from './remote.js';
-export { credentialReference, OsCredentialStore } from './credentials.js';
+export type {
+  RemoteCredential,
+  RemoteCredentialSource,
+  SynomemCredentialProvider,
+  RemoteSynomemOptions,
+} from './remote.js';
+export { createLocalResolver, createRemoteResolver, localContextId } from './resolvers.js';
+export type { ContextResolver, ResolvedContext } from './resolvers.js';
+export { OsCredentialStore } from './credentials.js';
 export type {
   CredentialStore,
+  StoredAccessKey,
   StoredCredential,
-  StoredInstallationKey,
   StoredOAuthCredential,
 } from './credentials.js';
-export { loginWithOAuth, StoredCredentialProvider } from './oauth.js';
+export { loginWithOAuth } from './oauth.js';
 export type { OAuthLoginOptions } from './oauth.js';
 export {
   createLocalImportBundle,
@@ -54,12 +56,12 @@ export {
   PROJECT_CONFIG_FILE,
   PROJECT_DIRECTORY,
   projectConfigSchema,
-  resolveWorkspaceSelection,
   writeProjectSelection,
 } from './project.js';
 export type { ProjectConfig, ProjectSelection } from './project.js';
 export {
-  discoverAccessKeyWorkspaces,
+  describeIdentity,
+  discoverContexts,
   discoverOrganizations,
   workspaceChoices,
 } from './discover.js';