aptly 0.1.0 → 0.1.1

package/dist/src/secret-store.js

@@ -0,0 +1,263 @@
+import { spawnSync } from 'node:child_process';
+import { windowsPowerShellPath } from './windows-powershell.js';
+const fail = (code) => { throw new Error(code); };
+const validName = (value) => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,254}$/.test(value);
+const validValue = (value) => typeof value === 'string' && !!value && value.trim() === value && Buffer.byteLength(value) <= 8192 && !/[\x00-\x1f\x7f]/.test(value);
+const runner = (command, args, options) => spawnSync(command, args, options);
+// Keychain Services generic-password dictionary keys are stable API values.
+// Literal NSString keys avoid JXA's opaque CFString global-constant wrappers.
+// Rebinding CopyMatching's output as id* bridges its NSData result correctly.
+const keychainScript = String.raw `ObjC.import('Foundation');
+ObjC.import('Security');
+ObjC.bindFunction('SecItemCopyMatching', ['int', ['id', 'id*']]);
+const input = JSON.parse(ObjC.unwrap($.NSString.alloc.initWithDataEncoding($.NSFileHandle.fileHandleWithStandardInput.readDataToEndOfFile, $.NSUTF8StringEncoding)));
+const query = $.NSMutableDictionary.alloc.init;
+query.setObjectForKey($('genp'), $('class'));
+query.setObjectForKey($(input.service), $('svce'));
+query.setObjectForKey($(input.account), $('acct'));
+let status = 0;
+let value = null;
+if (input.action === 'store') {
+  const data = $(input.value).dataUsingEncoding($.NSUTF8StringEncoding);
+  const changes = $.NSMutableDictionary.alloc.init;
+  changes.setObjectForKey(data, $('v_Data'));
+  status = $.SecItemUpdate(query, changes);
+  if (status === -25300) {
+    query.setObjectForKey(data, $('v_Data'));
+    status = $.SecItemAdd(query, null);
+  }
+} else if (input.action === 'load') {
+  query.setObjectForKey($(true), $('r_Data'));
+  query.setObjectForKey($('m_LimitOne'), $('m_Limit'));
+  const result = Ref();
+  status = $.SecItemCopyMatching(query, result);
+  if (status === 0) value = ObjC.unwrap($.NSString.alloc.initWithDataEncoding(result[0], $.NSUTF8StringEncoding));
+} else if (input.action === 'delete') {
+  status = $.SecItemDelete(query);
+} else {
+  status = -50;
+}
+const output = $(JSON.stringify({ status, value })).dataUsingEncoding($.NSUTF8StringEncoding);
+$.NSFileHandle.fileHandleWithStandardOutput.writeData(output);`;
+// Windows generic credentials belong to the current token's credential set.
+// The script is constant: target metadata and secret values arrive over stdin.
+// CREDENTIALW layout/blob limit: learn.microsoft.com/windows/win32/api/wincred/ns-wincred-credentialw
+const windowsScript = String.raw `$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+[Console]::InputEncoding = New-Object System.Text.UTF8Encoding($false)
+[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
+$status = -1
+$value = $null
+try {
+  $request = [Console]::In.ReadToEnd() | ConvertFrom-Json
+  Add-Type -TypeDefinition @'
+using System;
+using System.Text;
+using System.Runtime.InteropServices;
+public static class AptlyCredentialStore {
+  [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+  private struct Credential {
+    public uint Flags;
+    public uint Type;
+    [MarshalAs(UnmanagedType.LPWStr)] public string TargetName;
+    [MarshalAs(UnmanagedType.LPWStr)] public string Comment;
+    public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
+    public uint CredentialBlobSize;
+    public IntPtr CredentialBlob;
+    public uint Persist;
+    public uint AttributeCount;
+    public IntPtr Attributes;
+    [MarshalAs(UnmanagedType.LPWStr)] public string TargetAlias;
+    [MarshalAs(UnmanagedType.LPWStr)] public string UserName;
+  }
+  [DllImport("Advapi32.dll", EntryPoint="CredWriteW", CharSet=CharSet.Unicode, ExactSpelling=true, SetLastError=true)]
+  [return: MarshalAs(UnmanagedType.Bool)]
+  private static extern bool CredWrite(ref Credential credential, uint flags);
+  [DllImport("Advapi32.dll", EntryPoint="CredReadW", CharSet=CharSet.Unicode, ExactSpelling=true, SetLastError=true)]
+  [return: MarshalAs(UnmanagedType.Bool)]
+  private static extern bool CredRead(string target, uint type, uint flags, out IntPtr credential);
+  [DllImport("Advapi32.dll", EntryPoint="CredDeleteW", CharSet=CharSet.Unicode, ExactSpelling=true, SetLastError=true)]
+  [return: MarshalAs(UnmanagedType.Bool)]
+  private static extern bool CredDelete(string target, uint type, uint flags);
+  [DllImport("Advapi32.dll", ExactSpelling=true)]
+  private static extern void CredFree(IntPtr credential);
+  private static readonly UTF8Encoding Utf8 = new UTF8Encoding(false, true);
+  public static int Store(string target, string value) {
+    byte[] bytes = Utf8.GetBytes(value);
+    IntPtr blob = IntPtr.Zero;
+    try {
+      if (bytes.Length == 0 || bytes.Length > 2560) return 87;
+      blob = Marshal.AllocHGlobal(bytes.Length);
+      Marshal.Copy(bytes, 0, blob, bytes.Length);
+      Credential credential = new Credential();
+      credential.Type = 1;
+      credential.TargetName = target;
+      credential.UserName = "Aptly";
+      credential.CredentialBlobSize = (uint)bytes.Length;
+      credential.CredentialBlob = blob;
+      credential.Persist = 2;
+      return CredWrite(ref credential, 0) ? 0 : Marshal.GetLastWin32Error();
+    } finally {
+      if (blob != IntPtr.Zero) {
+        for (int i = 0; i < bytes.Length; i++) Marshal.WriteByte(blob, i, 0);
+        Marshal.FreeHGlobal(blob);
+      }
+      Array.Clear(bytes, 0, bytes.Length);
+    }
+  }
+  public static int Load(string target, out string value) {
+    value = null;
+    IntPtr pointer = IntPtr.Zero;
+    byte[] bytes = null;
+    try {
+      if (!CredRead(target, 1, 0, out pointer)) return Marshal.GetLastWin32Error();
+      Credential credential = (Credential)Marshal.PtrToStructure(pointer, typeof(Credential));
+      if (credential.CredentialBlobSize == 0 || credential.CredentialBlobSize > 2560 || credential.CredentialBlob == IntPtr.Zero) return 87;
+      bytes = new byte[(int)credential.CredentialBlobSize];
+      Marshal.Copy(credential.CredentialBlob, bytes, 0, bytes.Length);
+      value = Utf8.GetString(bytes);
+      return 0;
+    } finally {
+      if (bytes != null) Array.Clear(bytes, 0, bytes.Length);
+      if (pointer != IntPtr.Zero) CredFree(pointer);
+    }
+  }
+  public static int Delete(string target) {
+    return CredDelete(target, 1, 0) ? 0 : Marshal.GetLastWin32Error();
+  }
+}
+'@
+  $target = [string]$request.service + ':' + [string]$request.account
+  switch ($request.action) {
+    'store' { $status = [AptlyCredentialStore]::Store($target, [string]$request.value) }
+    'load' { $status = [AptlyCredentialStore]::Load($target, [ref]$value) }
+    'delete' { $status = [AptlyCredentialStore]::Delete($target) }
+  }
+} catch {
+  $status = -1
+  $value = $null
+}
+[Console]::Out.WriteLine((@{status=$status;value=$value} | ConvertTo-Json -Compress))`;
+function execute(command, args, input, options) {
+    let result;
+    try {
+        result = (options.exec ?? runner)(command, args, { input, encoding: 'utf8', timeout: 15000, maxBuffer: 65536, stdio: ['pipe', 'pipe', 'pipe'] });
+    }
+    catch {
+        return fail('secure_store_failed');
+    }
+    const errorCode = result.error && 'code' in result.error ? result.error.code : undefined;
+    if (errorCode === 'ENOENT')
+        fail('secure_store_unavailable');
+    if (errorCode === 'ETIMEDOUT')
+        fail('secure_store_timeout');
+    if (result.error)
+        fail('secure_store_failed');
+    return result;
+}
+function operate(action, value, options) {
+    const service = options.service ?? 'dev.aptly.mcp', account = options.account ?? 'OPENAI_API_KEY';
+    if (!validName(service) || !validName(account))
+        fail('secure_store_invalid_options');
+    if (action === 'store' && !validValue(value))
+        fail('secure_store_invalid_value');
+    const platform = options.platform ?? process.platform;
+    if (platform === 'win32') {
+        if (action === 'store' && Buffer.byteLength(value) > 2560)
+            fail('secure_store_invalid_value');
+        const input = JSON.stringify({ action, service, account, ...(action === 'store' ? { value } : {}) });
+        let executable;
+        try {
+            executable = windowsPowerShellPath();
+        }
+        catch {
+            return fail('secure_store_unavailable');
+        }
+        const result = execute(executable, ['-NoProfile', '-NonInteractive', '-Command', windowsScript], input, options);
+        if (result.status !== 0)
+            fail('secure_store_failed');
+        let parsed;
+        try {
+            parsed = JSON.parse(String(result.stdout ?? ''));
+        }
+        catch {
+            return fail('secure_store_failed');
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            fail('secure_store_failed');
+        const response = parsed;
+        if (response.status === 1168 && action !== 'store')
+            return null;
+        if (response.status === 5)
+            fail('secure_store_denied');
+        if (response.status === 1223)
+            fail('secure_store_cancelled');
+        if (response.status === 1312 || response.status === 50)
+            fail('secure_store_unavailable');
+        if (response.status !== 0)
+            fail('secure_store_failed');
+        if (action !== 'load')
+            return null;
+        const loaded = response.value;
+        if (!validValue(loaded) || Buffer.byteLength(loaded) > 2560)
+            return fail('secure_store_invalid_value');
+        return loaded;
+    }
+    if (platform === 'darwin') {
+        const input = JSON.stringify({ action, service, account, ...(action === 'store' ? { value } : {}) });
+        const result = execute('/usr/bin/osascript', ['-l', 'JavaScript', '-e', keychainScript], input, options);
+        if (result.status !== 0)
+            fail('secure_store_failed');
+        let parsed;
+        try {
+            parsed = JSON.parse(String(result.stdout ?? ''));
+        }
+        catch {
+            return fail('secure_store_failed');
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            fail('secure_store_failed');
+        const response = parsed;
+        if (response.status === -25300) {
+            if (action === 'store')
+                fail('secure_store_unavailable');
+            return null;
+        }
+        if (response.status === -128)
+            fail('secure_store_cancelled');
+        if (response.status === -25293)
+            fail('secure_store_denied');
+        if (response.status === -25308)
+            fail('secure_store_locked');
+        if (response.status === -34018)
+            fail('secure_store_unavailable');
+        if (response.status !== 0)
+            fail('secure_store_failed');
+        if (action !== 'load')
+            return null;
+        const loaded = response.value;
+        if (!validValue(loaded))
+            return fail('secure_store_invalid_value');
+        return loaded;
+    }
+    if (platform === 'linux') {
+        const args = action === 'store' ? ['store', '--label=Aptly MCP classification key', 'service', service, 'account', account] : [action === 'load' ? 'lookup' : 'clear', 'service', service, 'account', account];
+        const result = execute('secret-tool', args, action === 'store' ? value + '\n' : undefined, options);
+        if (result.status === 1 && !String(result.stderr ?? '').trim() && (action === 'delete' || (action === 'load' && !String(result.stdout ?? '').trim())))
+            return null;
+        if (result.status !== 0)
+            fail('secure_store_failed');
+        if (action !== 'load')
+            return null;
+        const loaded = String(result.stdout ?? '').replace(/\r?\n$/, '');
+        if (!validValue(loaded))
+            fail('secure_store_invalid_value');
+        return loaded;
+    }
+    return fail('secure_store_unsupported_platform');
+}
+/** Secret values are sent to OS tools only over stdin, never command arguments. */
+export function storeSecret(value, options = {}) { operate('store', value, options); }
+/** Internal runtime API: callers must never echo the returned value. */
+export function loadSecret(options = {}) { return operate('load', undefined, options); }
+export function deleteSecret(options = {}) { operate('delete', undefined, options); }

package/dist/src/server.js

@@ -13,7 +13,7 @@ const constraintsSchema = z.object({ model_pinned: z.boolean().optional(), effor
 const hookSchema = { client: z.enum(['codex', 'claude']), event: z.record(z.string(), z.unknown()) };
 const content = (result) => ({ content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result });
 export function createServer({ env = process.env } = {}) {
-    const { router, mode, modelInfo, disabledClients } = runtime(env);
+    const { router, mode, modelInfo, credentialStatus, disabledClients } = runtime(env);
     let lastAutomaticHook = null;
     const server = new McpServer({ name: 'aptly', version: VERSION });
     const annotations = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: mode === 'decisions' };
@@ -28,6 +28,7 @@ export function createServer({ env = process.env } = {}) {
         precedence: 'per_call_effective_host_evidence_required', automatic_settings_discovery: false,
         recommendation: { application: 'advisory_only', host_evidence_required: false, constraints: 'caller_declared_pins' },
         model_information: { status: modelInfo.status, refresh: 'explicit_only', account_access_verified: false }, disabled_clients: disabledClients,
+        credential_status: credentialStatus,
         automatic_hook: { status: loadAutomaticHookPolicy(env.APTLY_HOOK_POLICY_PATH).reason, mode: loadAutomaticHookPolicy(env.APTLY_HOOK_POLICY_PATH).policy?.mode ?? 'disabled', host_settings_verified: false, last_result: lastAutomaticHook },
     }));
     server.registerTool('recommend_agent', {

package/dist/src/setup.d.ts

@@ -17,6 +17,11 @@ export interface SetupResult {
     status: 'complete' | 'partial' | 'skipped';
     clients: SetupClientResult[];
 }
+export declare const configurableEnvironmentKeys: readonly string[];
 export declare function setupHosts(options?: SetupOptions): SetupResult;
 export declare function removeSetup(options?: SetupOptions): SetupResult;
+export declare function setDefaults(options?: SetupOptions): SetupResult;
+export declare function setEnvironment(key: string, value: string, options?: SetupOptions): SetupResult;
+/** Store only the nonsecret source reference; credential values never enter setup. */
+export declare function setCredentialReference(options?: SetupOptions): SetupResult;
 export {};

package/dist/src/setup.js

@@ -1,13 +1,28 @@
 import { lstatSync, readFileSync, mkdirSync, chmodSync, openSync, writeFileSync, closeSync, renameSync, unlinkSync, rmdirSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { randomUUID } from 'node:crypto';
 import { isDeepStrictEqual } from 'node:util';
 import { parse } from 'smol-toml';
+import { resolveCatalog } from './catalog.js';
+import { assertPrivateStatePath } from './files.js';
+import { assertWindowsPrivatePath, protectNewWindowsPrivateDirectory, copyWindowsFilePermissions } from './windows-private.js';
 const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
 const stringify = (value) => JSON.stringify(value, null, 2) + '\n';
 const fail = (code) => { throw new Error(code); };
+function privatePermissions(path, code) {
+    if (process.platform === 'win32') {
+        try {
+            assertWindowsPrivatePath(path);
+        }
+        catch {
+            fail(code);
+        }
+    }
+    else if ((lstatSync(path).mode & 0o077) !== 0)
+        fail(code);
+}
 const checkedDirectory = (path) => { const s = lstatSync(path); if (!s.isDirectory() || s.isSymbolicLink())
     fail('unsafe_directory'); };
 function noSymlinks(path) {
@@ -140,6 +155,85 @@ function removeTomlEnv(text, additions) {
         fail('managed_entry_changed');
     return text;
 }
+export const configurableEnvironmentKeys = Object.freeze(['ROUTER_PROVIDER', 'APTLY_CLAUDE_MODELS', 'APTLY_CODEX_MODELS', 'CLAUDE_MODELS', 'CODEX_MODELS', 'APTLY_MODEL_INFO_PATH']);
+const defaultEnvironment = { ROUTER_PROVIDER: 'decisions', APTLY_CLAUDE_MODELS: '["haiku","sonnet","opus"]', APTLY_CODEX_MODELS: '["gpt-6-luna","gpt-6.1-terra","gpt-6.1-sol"]' };
+function validateEnvironmentValue(key, value) {
+    if (!configurableEnvironmentKeys.includes(key))
+        fail(/KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL/i.test(key) ? 'environment_secret_key_unsupported' : 'environment_key_unsupported');
+    if (typeof value !== 'string' || !value || Buffer.byteLength(value) > 8192 || /[\x00-\x1f\x7f]/.test(value))
+        fail('environment_invalid_value');
+    if (/\bsk-[A-Za-z0-9_-]{8,}|\bBearer\s+\S+|https?:\/\/[^/\s]+:[^/\s]+@/i.test(value))
+        fail('environment_sensitive_value');
+    if (key === 'ROUTER_PROVIDER' && !['fixture', 'decisions'].includes(value))
+        fail('environment_invalid_value');
+    if (key === 'APTLY_MODEL_INFO_PATH') {
+        try {
+            assertPrivateStatePath(value);
+        }
+        catch {
+            fail('environment_invalid_value');
+        }
+    }
+}
+function editEnvironment(current, edit, client) {
+    const updates = {};
+    if ('defaults' in edit) {
+        for (const [key, value] of Object.entries(defaultEnvironment)) {
+            const alias = key === 'APTLY_CLAUDE_MODELS' ? 'CLAUDE_MODELS' : key === 'APTLY_CODEX_MODELS' ? 'CODEX_MODELS' : null;
+            if (current[key] === undefined && (!alias || current[alias] === undefined))
+                updates[key] = value;
+        }
+    }
+    else if ('credential' in edit) {
+        updates.APTLY_SECRET_BACKEND = 'os';
+        updates.APTLY_SECRET_CLIENT = client;
+    }
+    else {
+        validateEnvironmentValue(edit.key, edit.value);
+        updates[edit.key] = edit.value;
+    }
+    const effective = { ...current, ...updates };
+    if (effective.ROUTER_PROVIDER !== undefined && !['fixture', 'decisions'].includes(effective.ROUTER_PROVIDER))
+        fail('environment_invalid_value');
+    try {
+        resolveCatalog(effective);
+    }
+    catch {
+        fail('environment_invalid_value');
+    }
+    return Object.fromEntries(Object.entries(updates).filter(([key, value]) => current[key] !== value));
+}
+/** Change only selected single-line scalar env assignments; refuse ambiguous TOML layouts. */
+function updateTomlEnv(text, updates) {
+    const parsed = toml(text), existing = parsed.mcp_servers?.aptly?.env ?? {};
+    const expected = structuredClone(parsed);
+    Object.assign(map(map(map(expected, 'mcp_servers'), 'aptly'), 'env'), updates);
+    const headers = [...text.matchAll(/^\s*\[([^\n]+)\][ \t]*(?:#[^\n]*)?\r?$/gm)];
+    const header = headers.find(h => { try {
+        return toml(h[0] + '\naptly_probe = true\n').mcp_servers?.aptly?.env?.aptly_probe === true;
+    }
+    catch {
+        return false;
+    } });
+    const present = Object.entries(updates).filter(([key]) => existing[key] !== undefined);
+    if (present.length) {
+        if (!header)
+            fail('unsupported_toml_layout');
+        const end = headers.find(h => h.index > header.index)?.index ?? text.length;
+        let body = text.slice(header.index + header[0].length, end);
+        for (const [key, value] of present) {
+            const line = new RegExp('^[ \t]*' + key + '[ \t]*=[^\n]*(?:\n|$)', 'gm');
+            if ([...body.matchAll(line)].length !== 1)
+                fail('unsupported_toml_layout');
+            body = body.replace(line, () => key + ' = ' + q(value) + '\n');
+        }
+        text = text.slice(0, header.index + header[0].length) + body + text.slice(end);
+    }
+    text = addTomlEnv(text, Object.fromEntries(Object.entries(updates).filter(([key]) => existing[key] === undefined)));
+    if (!isDeepStrictEqual(toml(text), expected))
+        fail('unsupported_toml_layout');
+    return text;
+}
 function resolved(options, client) {
     const home = resolve(options.home ?? homedir()), env = options.env ?? process.env;
     const override = client === 'codex' ? env.CODEX_HOME : env.CLAUDE_CONFIG_DIR;
@@ -154,7 +248,23 @@ function ownership(value, client) {
         fail('invalid_ownership');
     return value;
 }
-function prepare(options, client, removing) {
+/** Compatibility restriction only: this does not authenticate arbitrary launcher code. */
+function requireCredentialRuntime(entry, root) {
+    const allowed = [join(root, 'dist', 'src', 'server.js'), join(root, 'src', 'server.ts')];
+    if (entry.command !== process.execPath || !Array.isArray(entry.args) || entry.args.length !== 1 || !allowed.includes(entry.args[0]))
+        fail('credential_launcher_unverified');
+    try {
+        const extension = entry.args[0].endsWith('.ts') ? 'ts' : 'js';
+        const server = read(entry.args[0]).text;
+        const runtime = read(join(dirname(entry.args[0]), 'runtime.' + extension)).text;
+        if (!server?.includes('./runtime.' + extension) || !runtime?.includes('APTLY_SECRET_BACKEND') || !runtime.includes('APTLY_SECRET_CLIENT'))
+            fail('credential_launcher_unverified');
+    }
+    catch {
+        fail('credential_launcher_unverified');
+    }
+}
+function prepare(options, client, removing, edit) {
     const env = options.env ?? process.env, paths = resolved(options, client), { dir, mcpPath, hooksPath, privateDir } = paths;
     const changes = [], dirs = [];
     noSymlinks(dir);
@@ -162,8 +272,7 @@ function prepare(options, client, removing) {
     for (const path of [privateDir, join(privateDir, 'state')]) {
         try {
             checkedDirectory(path);
-            if ((lstatSync(path).mode & 0o077) !== 0)
-                fail('private_directory_permissions');
+            privatePermissions(path, 'private_directory_permissions');
         }
         catch (e) {
             if (e.code !== 'ENOENT')
@@ -186,8 +295,8 @@ function prepare(options, client, removing) {
     const snap = (path) => { const source = read(path); return { path, before: source.text, after: source.text, mode: source.mode }; };
     const mcp = snap(mcpPath), hooks = snap(hooksPath), policy = snap(policyPath), manifest = snap(manifestPath);
     for (const privateFile of [policy, manifest])
-        if (privateFile.before !== null && (privateFile.mode & 0o077) !== 0)
-            fail('private_file_permissions');
+        if (privateFile.before !== null)
+            privatePermissions(privateFile.path, 'private_file_permissions');
     const oldOwner = manifest.before === null ? undefined : ownership(json(manifest.before), client);
     if (removing && !oldOwner)
         return { changes, dirs, result: { client, status: 'skipped', codes: ['no_owned_setup'] } };
@@ -247,17 +356,13 @@ function prepare(options, client, removing) {
         let created = false, tomlBlock;
         if (servers.aptly === undefined) {
             created = true;
-            servers.aptly = { ...(client === 'claude' ? { type: 'stdio' } : {}), command: process.execPath, args: [join(root, 'dist', 'src', 'server.js')], ...(client === 'codex' ? { env_vars: ['OPENAI_API_KEY'] } : {}), env: { ROUTER_PROVIDER: env.ROUTER_PROVIDER === 'fixture' ? 'fixture' : 'decisions', ...additions } };
-            if (client === 'codex') {
-                tomlBlock = newTomlBlock(servers.aptly);
-                mcp.after = (mcp.before ?? '') + ((mcp.before ?? '').endsWith('\n') || !mcp.before ? '\n' : '\n\n') + tomlBlock;
-            }
-            else
-                mcp.after = stringify(config);
+            servers.aptly = { ...(client === 'claude' ? { type: 'stdio' } : {}), command: process.execPath, args: [join(root, 'dist', 'src', 'server.js')], ...(client === 'codex' ? { env_vars: ['OPENAI_API_KEY'] } : {}), env: { ROUTER_PROVIDER: edit && 'defaults' in edit ? 'decisions' : env.ROUTER_PROVIDER === 'fixture' ? 'fixture' : 'decisions', ...additions } };
         }
         else {
             if (!object(servers.aptly))
                 fail('mcp_entry_conflict');
+            if (edit && oldOwner?.mcp_created && !isDeepStrictEqual(servers.aptly, oldOwner.mcp))
+                fail('managed_mcp_changed');
             const currentEnv = map(servers.aptly, 'env');
             if (currentEnv.APTLY_HOOK_POLICY_PATH !== undefined && currentEnv.APTLY_HOOK_POLICY_PATH !== policyPath)
                 fail('mcp_environment_conflict');
@@ -265,13 +370,29 @@ function prepare(options, client, removing) {
             Object.assign(currentEnv, missing);
             mcp.after = client === 'codex' ? addTomlEnv(mcp.before ?? '', missing) : stringify(config);
         }
+        if (edit && 'credential' in edit)
+            requireCredentialRuntime(servers.aptly, root);
+        const currentEnv = map(servers.aptly, 'env');
+        const updates = edit ? editEnvironment(currentEnv, edit, client) : {};
+        Object.assign(currentEnv, updates);
+        if (created) {
+            if (client === 'codex') {
+                tomlBlock = newTomlBlock(servers.aptly);
+                mcp.after = (mcp.before ?? '') + ((mcp.before ?? '').endsWith('\n') || !mcp.before ? '\n' : '\n\n') + tomlBlock;
+            }
+            else
+                mcp.after = stringify(config);
+        }
+        else if (edit)
+            mcp.after = client === 'codex' ? updateTomlEnv(mcp.after, updates) : stringify(config);
         const existingRoute = entries.filter(routeHook);
         if (existingRoute.some(entry => !isDeepStrictEqual(entry, hookValue)))
             fail('existing_routing_hook_conflict');
         if (existingRoute.length === 0)
             entries.push(hookValue);
         hooks.after = stringify(hooksObject);
-        const policyValue = { schema_version: 1, kind: 'aptly-auto-hook', mode: options.mode ?? 'defaults', issuer: 'operator_installation', enabled: true, state_directory: stateDir };
+        const preservedMode = edit && policy.before !== null ? json(policy.before).mode : undefined;
+        const policyValue = { schema_version: 1, kind: 'aptly-auto-hook', mode: options.mode ?? (['defaults', 'advisory'].includes(preservedMode) ? preservedMode : 'defaults'), issuer: 'operator_installation', enabled: true, state_directory: stateDir };
         if (policy.before !== null) {
             const p = json(policy.before);
             if (!isDeepStrictEqual(p, policyValue))
@@ -286,6 +407,36 @@ function prepare(options, client, removing) {
         if (existingRoute.length && !oldOwner)
             fail('existing_hook_not_owned');
         const owner = oldOwner ?? { schema_version: 1, kind: 'aptly-setup-ownership', client, hook: hookValue, policy: policyValue, policy_created: policy.before === null, mcp_created: created, ...(created ? { mcp: servers.aptly } : {}), env_added: envAdded, ...(tomlBlock ? { toml_block: tomlBlock } : {}) };
+        if (edit && oldOwner) {
+            if (oldOwner.mcp_created) {
+                owner.mcp = structuredClone(servers.aptly);
+                if (client === 'codex') {
+                    const oldBlock = oldOwner.toml_block;
+                    if (!oldBlock || !(mcp.before ?? '').includes(oldBlock))
+                        fail('managed_mcp_changed');
+                    const nextBlock = newTomlBlock(servers.aptly);
+                    const rendered = (mcp.before ?? '').replace(oldBlock, nextBlock);
+                    if (!isDeepStrictEqual(toml(rendered), config))
+                        fail('managed_mcp_changed');
+                    mcp.after = rendered;
+                    owner.toml_block = nextBlock;
+                }
+            }
+            else {
+                const prior = client === 'codex' ? toml(mcp.before ?? '') : json(mcp.before);
+                const priorEnv = prior[client === 'codex' ? 'mcp_servers' : 'mcpServers']?.aptly?.env ?? {};
+                for (const [key, value] of Object.entries(updates))
+                    if (Object.hasOwn(owner.env_added, key) || priorEnv[key] === undefined)
+                        owner.env_added[key] = value;
+            }
+        }
+        else if (edit && !created) {
+            const prior = client === 'codex' ? toml(mcp.before ?? '') : json(mcp.before);
+            const priorEnv = prior[client === 'codex' ? 'mcp_servers' : 'mcpServers']?.aptly?.env ?? {};
+            for (const [key, value] of Object.entries(updates))
+                if (priorEnv[key] === undefined)
+                    owner.env_added[key] = value;
+        }
         manifest.after = stringify(owner);
         if (client === 'codex')
             result.requires_hook_review = true;
@@ -316,13 +467,21 @@ function replace(snapshot, forward) {
     let fd;
     try {
         fd = openSync(stage, 'wx', 0o600);
+        if (process.platform === 'win32' && expected !== null) {
+            try {
+                copyWindowsFilePermissions(snapshot.path, stage);
+            }
+            catch {
+                fail('private_file_permissions');
+            }
+        }
         writeFileSync(fd, next);
         closeSync(fd);
         fd = undefined;
         if (read(snapshot.path).text !== expected)
             fail('concurrent_configuration_change');
         renameSync(stage, snapshot.path);
-        if (snapshot.mode !== 0o600)
+        if (process.platform !== 'win32' && snapshot.mode !== 0o600)
             chmodSync(snapshot.path, snapshot.mode);
     }
     finally {
@@ -337,7 +496,7 @@ function replace(snapshot, forward) {
         }
     }
 }
-function execute(options, removing) {
+function execute(options, removing, edit) {
     const clients = [...new Set(options.clients ?? ['codex', 'claude'])];
     if (clients.some(client => client !== 'codex' && client !== 'claude'))
         return { status: 'partial', clients: [] };
@@ -346,13 +505,15 @@ function execute(options, removing) {
         return { status: 'skipped', clients: clients.map(client => ({ client, status: 'skipped', codes: [env.APTLY_SKIP_SETUP === '1' ? 'setup_disabled' : 'ci_environment'] })) };
     const prepared = clients.map(client => {
         try {
-            return prepare(options, client, removing);
+            return prepare(options, client, removing, edit);
         }
         catch (e) {
             return { changes: [], dirs: [], result: { client, status: 'error', codes: [safeCode(e)] } };
         }
     });
     const results = prepared.map(plan => plan.result);
+    if (edit && results.some(result => result.status === 'error'))
+        return { status: 'partial', clients: results.map(result => result.status === 'error' ? result : { ...result, status: 'skipped', codes: ['other_host_validation_failed'] }) };
     // Each host is independent; prepare every host before committing any host.
     for (const plan of prepared) {
         if (!plan.changes.length)
@@ -369,11 +530,17 @@ function execute(options, removing) {
                         throw e;
                     mkdirSync(path, { mode: 0o700 });
                     madeDirs.push(path);
+                    if (process.platform === 'win32') {
+                        try {
+                            protectNewWindowsPrivateDirectory(path);
+                        }
+                        catch {
+                            fail('private_directory_permissions');
+                        }
+                    }
                 }
-                if (path.endsWith('/aptly') || path.endsWith('/aptly/state')) {
-                    if ((lstatSync(path).mode & 0o077) !== 0)
-                        fail('private_directory_permissions');
-                }
+                if (basename(path) === 'aptly' || (basename(path) === 'state' && basename(dirname(path)) === 'aptly'))
+                    privatePermissions(path, 'private_directory_permissions');
             }
             for (const snapshot of plan.changes) {
                 replace(snapshot, true);
@@ -402,7 +569,19 @@ function execute(options, removing) {
     }
     return { status: results.some(result => result.status === 'error') ? 'partial' : results.every(result => result.status === 'skipped') ? 'skipped' : 'complete', clients: results };
 }
-const codes = new Set(['unsafe_directory', 'unsafe_symlink', 'unsafe_configuration_file', 'invalid_json', 'invalid_json_object', 'configuration_shape_conflict', 'hook_shape_conflict', 'invalid_toml', 'unsupported_toml_layout', 'relative_configuration_directory', 'invalid_ownership', 'managed_hook_changed', 'managed_mcp_changed', 'managed_entry_changed', 'managed_policy_changed', 'mcp_entry_conflict', 'mcp_environment_conflict', 'existing_routing_hook_conflict', 'policy_conflict', 'existing_hook_not_owned', 'concurrent_configuration_change', 'private_directory_permissions', 'private_file_permissions']);
+const codes = new Set(['credential_launcher_unverified', 'environment_invalid_value', 'environment_sensitive_value', 'environment_key_unsupported', 'environment_secret_key_unsupported', 'unsafe_directory', 'unsafe_symlink', 'unsafe_configuration_file', 'invalid_json', 'invalid_json_object', 'configuration_shape_conflict', 'hook_shape_conflict', 'invalid_toml', 'unsupported_toml_layout', 'relative_configuration_directory', 'invalid_ownership', 'managed_hook_changed', 'managed_mcp_changed', 'managed_entry_changed', 'managed_policy_changed', 'mcp_entry_conflict', 'mcp_environment_conflict', 'existing_routing_hook_conflict', 'policy_conflict', 'existing_hook_not_owned', 'concurrent_configuration_change', 'private_directory_permissions', 'private_file_permissions']);
 function safeCode(error) { return error instanceof Error && codes.has(error.message) ? error.message : 'configuration_io_error'; }
 export function setupHosts(options = {}) { return execute(options, false); }
 export function removeSetup(options = {}) { return execute(options, true); }
+export function setDefaults(options = {}) { return execute(options, false, { defaults: true }); }
+export function setEnvironment(key, value, options = {}) {
+    try {
+        validateEnvironmentValue(key, value);
+    }
+    catch (error) {
+        return { status: 'partial', clients: (options.clients ?? ['codex', 'claude']).map(client => ({ client, status: 'error', codes: [safeCode(error)] })) };
+    }
+    return execute(options, false, { key, value });
+}
+/** Store only the nonsecret source reference; credential values never enter setup. */
+export function setCredentialReference(options = {}) { return execute(options, false, { credential: true }); }

package/dist/src/types.d.ts

@@ -71,6 +71,9 @@ export interface ProviderAnswer {
     confidence?: number;
     usage?: unknown;
 }
-export type RoutingProvider = (args: ProviderArguments) => Promise<ProviderAnswer>;
+export type RoutingProvider = ((args: ProviderArguments) => Promise<ProviderAnswer>) & {
+    /** Synchronous local readiness check only; must not initiate transport. */
+    preflight?: () => void;
+};
 export declare function isRecord(value: unknown): value is UnknownRecord;
 export declare function errorCode(error: unknown): string | undefined;

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.1.1";

package/dist/src/version.js

@@ -1 +1 @@
-export const VERSION = '0.1.0';
+export const VERSION = '0.1.1';

package/dist/src/windows-powershell.d.ts

@@ -0,0 +1,2 @@
+/** Use the operator's Windows system directory, never cwd or PATH lookup. */
+export declare function windowsPowerShellPath(env?: NodeJS.ProcessEnv): string;