synomem 0.8.0 → 0.9.1

package/src/credentials.ts

@@ -1,42 +1,80 @@
-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 { randomBytes, randomUUID } from 'node:crypto';
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  linkSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeSync,
+} from 'node:fs';
+import { hostname } from 'node:os';
+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 +82,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,34 +149,28 @@ 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;
 
   constructor(options: { platform?: NodeJS.Platform; run?: CredentialCommandRunner } = {}) {
     this.platform = options.platform ?? process.platform;
-    this.run = options.run ?? command;
+    const run = options.run ?? command;
+    // A missing helper (a headless Linux box with no Secret Service) is a
+    // configuration answer, not a crash: name the explicit alternatives. There
+    // is still no fallback — the caller chooses --store file deliberately.
+    this.run = async (executable, arguments_, input) => {
+      try {
+        return await run(executable, arguments_, input);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') this.unsupported();
+        throw error;
+      }
+    };
   }
 
-  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 +185,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 +201,7 @@ export class OsCredentialStore implements CredentialStore {
               '-s',
               serviceName,
               '-l',
-              'Synomem OAuth credential',
+              'Synomem credential',
               '-U',
               '-w',
             ],
@@ -172,21 +210,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 +239,217 @@ 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.'
+        : 'No operating-system credential store is available here (it needs the macOS Keychain, or secret-tool with a Secret Service on Linux). Choose one explicitly: --store file keeps it in a 0600 file under your Synomem home; --store environment reads 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;
+    assertPrivate(this.directory, 0o700);
+    assertPrivate(path, 0o600);
+    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;
+  }
+}
+
+/*
+ * Like ssh with a private key: a credential file (or its directory) that other
+ * users can read, or that another user owns, is refused rather than used. The
+ * fix is the owner's to make; silently tightening it would hide that the
+ * secret may already have been exposed.
+ */
+function assertPrivate(path: string, expected: number): void {
+  if (process.platform === 'win32') return;
+  const stat = statSync(path);
+  if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) {
+    throw new SynomemError(
+      'CONFIG_INVALID',
+      `${path} is owned by another user; refusing to use it.`,
+    );
+  }
+  if ((stat.mode & 0o077) !== 0) {
+    throw new SynomemError(
+      'CONFIG_INVALID',
+      `${path} is accessible to other users (mode ${(stat.mode & 0o777).toString(8)}). ` +
+        `Run \`chmod ${expected.toString(8)} ${path}\` if you are sure it was not exposed, ` +
+        'otherwise remove it and sign in again.',
     );
   }
 }
+
+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. The lock file records its owner
+ * (pid, host) and a random token. A lock is broken only when its owner is
+ * provably gone — a dead pid on this host — or, for an owner on another host
+ * or an unreadable file, once it is older than `staleMs`. A live owner is never
+ * preempted however long its refresh takes (the refresh request itself times
+ * out well inside `staleMs`).
+ *
+ * Breaking renames the file aside first and checks the token: if another
+ * process already broke and re-acquired it in between, the fresh lock is put
+ * back rather than deleted. Correctness against a concurrent writer is still
+ * the generation compare-and-swap in the refresh path; the lock exists so that
+ * only one process ever spends a given refresh token. Locks assume one host's
+ * filesystem; a home shared over a network filesystem is not supported.
+ */
+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;
+  const token = randomBytes(16).toString('hex');
+  const host = hostname();
+  let descriptor: number | undefined;
+  while (descriptor === undefined) {
+    try {
+      descriptor = openSync(path, 'wx', 0o600);
+      writeSync(descriptor, `${process.pid}\n${host}\n${token}\n`);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      if (breakIfAbandoned(path, host, staleMs)) 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);
+    // Release only our own lock.
+    if (readLock(path)?.token === token) rmSync(path, { force: true });
+  }
+}
+
+interface LockOwner {
+  pid: number;
+  host: string;
+  token: string;
+}
+
+function readLock(path: string): LockOwner | undefined {
+  try {
+    const [pid, host, token] = readFileSync(path, 'utf8').split('\n');
+    const parsed = Number(pid);
+    if (!Number.isSafeInteger(parsed) || !host || !token) return undefined;
+    return { pid: parsed, host, token };
+  } catch {
+    return undefined;
+  }
+}
+
+function processAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM: it exists but belongs to someone else — alive.
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+/** Returns true when the caller should immediately retry acquiring. */
+function breakIfAbandoned(path: string, host: string, staleMs: number): boolean {
+  let age: number;
+  try {
+    age = Date.now() - statSync(path).mtimeMs;
+  } catch {
+    return true; // Released between the failed open and now.
+  }
+  const owner = readLock(path);
+  // A lock whose contents are still being written is fresh, not abandoned.
+  if (!owner && age < 1_000) return false;
+  const abandoned = owner
+    ? owner.host === host
+      ? !processAlive(owner.pid)
+      : age > staleMs
+    : age > staleMs;
+  if (!abandoned) return false;
+  const aside = `${path}.broken-${randomBytes(6).toString('hex')}`;
+  try {
+    renameSync(path, aside);
+  } catch {
+    return true; // Someone else broke or released it first.
+  }
+  const taken = readLock(aside);
+  if (owner && taken?.token !== owner.token) {
+    // We grabbed a lock re-acquired after our inspection: restore it.
+    try {
+      linkSync(aside, path);
+    } catch {
+      /* a third process holds the path now; ours is the one to discard */
+    }
+  }
+  rmSync(aside, { force: true });
+  return 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;
@@ -33,19 +27,6 @@ export interface DiscoveredOrganization {
   workspaces: DiscoveredWorkspace[];
 }
 
-export interface WorkspaceMembership {
-  id: string;
-  displayName: string;
-  roles: string[];
-  /**
-   * Reachable right now, with this same credential, by naming it as
-   * Synomem-Workspace-Id — no new token or re-authentication. A human
-   * credential's own organization is the boundary; an agent credential has
-   * only ever one such entry, its own.
-   */
-  addressableWithThisToken: boolean;
-}
-
 export interface DiscoveryOptions {
   baseUrl: string;
   accessToken: string;
@@ -60,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,
@@ -69,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) {
@@ -87,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.
  *
@@ -147,19 +128,32 @@ export async function discoverOrganizations(
 }
 
 /**
- * Every workspace this credential's account belongs to, and which are
- * reachable right now without a new token — the data-plane counterpart to
- * `discoverOrganizations`, and the one that actually works with an ordinary
- * bearer token (OAuth or access key alike). `/v1/me` requires a first-party
- * control-plane credential a CLI never holds; `/v1/identity` requires only
- * the normal `synomem:read` scope every credential already has.
+ * 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 discoverIdentity(
-  options: DiscoveryOptions,
-): Promise<{ workspaceId: string; workspaces: WorkspaceMembership[] }> {
-  return await readJson<{ workspaceId: string; workspaces: WorkspaceMembership[] }>(
+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,
   );
 }
 

package/src/errors.ts

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

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),
       });