@wyattjoh/demur 0.1.0 → 0.2.0

package/README.md

@@ -55,15 +55,28 @@ shell arguments when the guard is active.
 
 ## Install
 
-Export the API key before launching the host agent. You can use your shell,
-`.env.local` with a compatible environment loader, or any secret manager:
+Install demur's command-line tools and save your TypeSafe API key in the
+operating system credential store:
+
+```sh
+bun add --global @wyattjoh/demur
+demur auth login
+demur auth status
+```
+
+`Bun.secrets` stores the credential in macOS Keychain, Linux Secret Service, or
+Windows Credential Manager. The operating system may request access when the
+credential is first used or while its credential store is locked.
+
+For automation or a one-off override, set `TYPESAFE_API_KEY` before launching
+the host agent. An environment value takes precedence over the stored key:
 
 ```sh
 export TYPESAFE_API_KEY="..."
 ```
 
 Never commit the key. [`.env.schema`](.env.schema) documents the accepted
-configuration, and local environment files are ignored by Git.
+environment configuration, and local environment files are ignored by Git.
 
 ### Pi
 
@@ -76,10 +89,10 @@ pi install npm:@wyattjoh/demur
 Pin a specific release when reproducibility matters:
 
 ```sh
-pi install npm:@wyattjoh/demur@0.1.0
+pi install npm:@wyattjoh/demur@0.1.1
 ```
 
-Launch Pi from an environment that already contains `TYPESAFE_API_KEY`:
+Launch Pi normally after configuring the credential:
 
 ```sh
 pi
@@ -102,8 +115,8 @@ pi install "$PWD"
 
 ### Claude Code
 
-Register the source adapter in `~/.claude/settings.json`, replacing the path
-with the absolute path to your clone:
+The global package installation above also provides the Claude Code hook.
+Register its executable in `~/.claude/settings.json`:
 
 ```json
 {
@@ -114,7 +127,7 @@ with the absolute path to your clone:
         "hooks": [
           {
             "type": "command",
-            "command": "bun /absolute/path/to/demur/src/adapters/claude-code.ts"
+            "command": "demur-claude-hook"
           }
         ]
       }
@@ -123,37 +136,45 @@ with the absolute path to your clone:
 }
 ```
 
-Launch Claude Code from an environment that already contains
-`TYPESAFE_API_KEY`. The adapter emits Claude Code's
-`hookSpecificOutput.permissionDecision` response.
+Launch Claude Code normally after configuring the credential. The adapter emits
+Claude Code's `hookSpecificOutput.permissionDecision` response.
 
 ### CLI
 
-Judge a single command without installing a host integration:
+Manage the stored credential or judge a single command without a host
+integration:
 
 ```sh
-bun run judge "git reset --hard HEAD~3"
+demur auth login
+demur auth status
+demur auth logout
+demur judge "git reset --hard HEAD~3"
 ```
 
+From a development checkout, `bun run judge "<command>"` remains available.
+
 ## Configuration
 
 | Variable | Default | Purpose |
 | --- | --- | --- |
-| `TYPESAFE_API_KEY` | required | TypeSafe API credential. Missing keys fail closed. |
+| `TYPESAFE_API_KEY` | stored credential | Optional TypeSafe API credential override. Missing keys fail closed. |
 | `DEMUR_TIMEOUT_MS` | `4000` | Per-attempt model timeout in milliseconds. |
 | `DEMUR_DISABLE` | unset | Emergency bypass. `1` or `true` allows every command. |
 
 ## Failure posture
 
-demur fails closed. A missing key, timeout, API failure, malformed response, or
-unexpected guard error returns `deny` with a reason that identifies the guard
-failure rather than presenting it as a policy judgment.
+demur fails closed. A missing key, credential-store failure, timeout, API
+failure, malformed response, or unexpected guard error returns `deny` with a
+reason that identifies the guard failure rather than presenting it as a policy
+judgment.
 
 `DEMUR_DISABLE=1` is an explicit emergency bypass. It disables all protection
 and should remain unset during normal use.
 
 ## Known limitations
 
+- `Bun.secrets` is experimental, and credential-store availability and prompts
+  vary by operating system configuration.
 - Model decisions are probabilistic and may vary between identical requests.
 - The hard-coded `jev-latest` model alias may change without a demur release.
 - Attacker-controlled command text can influence the model.
@@ -175,6 +196,7 @@ and deterministic policy controls alongside demur.
 - `src/policy.ts` — thresholds and `allow` / `ask` / `deny` composition
 - `src/analyze.ts` — deterministic shell analysis for the static uncertainty gate
 - `src/state.ts` — bounded environment and Git context collection
+- `src/key.ts` — environment precedence and operating-system credential storage
 - `src/guard.internal.ts` — Effect-native orchestration and fail-closed recovery
 - `src/guard.ts` — managed runtime and Promise boundary
 - `extensions/demur/` — Pi `tool_call` integration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wyattjoh/demur",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "A proof-of-concept destructive-command guard for coding agents.",
   "license": "MIT",
@@ -12,6 +12,10 @@
     "url": "https://github.com/wyattjoh/demur/issues"
   },
   "homepage": "https://github.com/wyattjoh/demur#readme",
+  "bin": {
+    "demur": "src/cli.ts",
+    "demur-claude-hook": "src/adapters/claude-code.ts"
+  },
   "keywords": [
     "coding-agent",
     "pi-package",

package/src/cli.ts

@@ -1,41 +1,236 @@
 #!/usr/bin/env bun
+import { Predicate } from "effect";
 import { guard } from "./guard.ts";
+import {
+  deleteApiKey,
+  resolveApiKey,
+  storeApiKey,
+  type ResolvedApiKey,
+} from "./key.ts";
+import type { Verdict } from "./types.ts";
+
+const USAGE = `Usage:
+  demur auth login
+  demur auth status
+  demur auth logout
+  demur judge "<command>" [--cwd=<path>]`;
+
+/**
+ * Injectable process boundaries used by the command-line interface.
+ */
+export type CliDependencies = {
+  judge(command: string, cwd: string): Promise<Verdict>;
+  resolveApiKey(): Promise<ResolvedApiKey | undefined>;
+  storeApiKey(value: string): Promise<void>;
+  deleteApiKey(): Promise<boolean>;
+  readSecret(prompt: string): Promise<string>;
+  cwd(): string;
+  stdout(message: string): void;
+  stderr(message: string): void;
+};
+
+const defaultDependencies: CliDependencies = {
+  judge: (command, cwd) => guard(command, cwd, "cli"),
+  resolveApiKey,
+  storeApiKey,
+  deleteApiKey,
+  readSecret,
+  cwd: () => process.cwd(),
+  stdout: (message) => console.log(message),
+  stderr: (message) => console.error(message),
+};
 
 /**
- * Judge a single command from the terminal and print the verdict with the
- * judgments behind it.
+ * Run demur's command-line interface with explicit process dependencies.
  *
- * Usage: `bun run judge "git reset --hard"` — optionally with `--cwd=<path>`.
+ * @param args - Command-line arguments after the executable name
+ * @param dependencies - Guard, credential, terminal, and process boundaries
+ * @returns The process exit code
  */
-async function main(): Promise<void> {
-  const args = Bun.argv.slice(2);
-  const cwdArg = args.find((a) => a.startsWith("--cwd="));
-  const command = args.filter((a) => !a.startsWith("--")).join(" ");
+export async function runCli(
+  args: ReadonlyArray<string>,
+  dependencies: CliDependencies = defaultDependencies,
+): Promise<number> {
+  try {
+    if (args[0] === "auth") {
+      return await runAuth(args.slice(1), dependencies);
+    }
+
+    if (args[0] === "help" || args[0] === "--help" || args[0] === "-h") {
+      dependencies.stdout(USAGE);
+      return 0;
+    }
+
+    const judgeArgs = args[0] === "judge" ? args.slice(1) : args;
+    return await runJudge(judgeArgs, dependencies);
+  } catch (error: unknown) {
+    dependencies.stderr(`demur: ${errorDetail(error)}`);
+    return 1;
+  }
+}
+
+async function runAuth(
+  args: ReadonlyArray<string>,
+  dependencies: CliDependencies,
+): Promise<number> {
+  const command = args[0];
+
+  if (command === "login" && args.length === 1) {
+    const resolved = await dependencies.resolveApiKey();
+    const value =
+      resolved?.source === "environment"
+        ? resolved.value
+        : await dependencies.readSecret("TypeSafe API key: ");
+
+    if (value.trim() === "") {
+      dependencies.stderr("demur: the TypeSafe API key cannot be empty.");
+      return 2;
+    }
+
+    await dependencies.storeApiKey(value);
+    dependencies.stdout(
+      resolved?.source === "environment"
+        ? "Stored TYPESAFE_API_KEY in the operating system credential store."
+        : "Stored the TypeSafe API key in the operating system credential store.",
+    );
+    if (resolved?.source === "environment") {
+      dependencies.stdout(
+        "TYPESAFE_API_KEY remains the active override until it is unset.",
+      );
+    }
+    return 0;
+  }
+
+  if (command === "status" && args.length === 1) {
+    const resolved = await dependencies.resolveApiKey();
+    if (resolved === undefined) {
+      dependencies.stderr("No TypeSafe API key is configured.");
+      return 1;
+    }
+
+    dependencies.stdout(
+      resolved.source === "environment"
+        ? "A TypeSafe API key is configured through TYPESAFE_API_KEY."
+        : "A TypeSafe API key is stored in the operating system credential store.",
+    );
+    return 0;
+  }
+
+  if (command === "logout" && args.length === 1) {
+    const resolved = await dependencies.resolveApiKey();
+    const deleted = await dependencies.deleteApiKey();
+    dependencies.stdout(
+      deleted
+        ? "Deleted the stored TypeSafe API key."
+        : "No stored TypeSafe API key was found.",
+    );
+    if (resolved?.source === "environment") {
+      dependencies.stdout(
+        "TYPESAFE_API_KEY remains configured and must be unset separately.",
+      );
+    }
+    return 0;
+  }
+
+  dependencies.stderr(USAGE);
+  return 2;
+}
+
+async function runJudge(
+  args: ReadonlyArray<string>,
+  dependencies: CliDependencies,
+): Promise<number> {
+  const cwdArg = args.find((arg) => arg.startsWith("--cwd="));
+  const command = args.filter((arg) => !arg.startsWith("--")).join(" ");
 
   if (command.trim() === "") {
-    console.error('Usage: bun run judge "<command>" [--cwd=<path>]');
-    process.exit(2);
+    dependencies.stderr(USAGE);
+    return 2;
   }
 
-  const cwd = cwdArg?.slice("--cwd=".length) ?? process.cwd();
-  const verdict = await guard(command, cwd, "cli");
+  const cwd = cwdArg?.slice("--cwd=".length) || dependencies.cwd();
+  const verdict = await dependencies.judge(command, cwd);
 
   const mark = { allow: "✓", ask: "?", deny: "✗" }[verdict.decision];
-  console.log(`${mark} ${verdict.decision.toUpperCase()}  ${verdict.reason}`);
+  dependencies.stdout(
+    `${mark} ${verdict.decision.toUpperCase()}  ${verdict.reason}`,
+  );
 
   if (verdict.judgments !== undefined) {
-    const j = verdict.judgments;
-    console.log("");
-    console.log(`  executes destruction    ${j.executesDestruction.toFixed(3)}`);
-    console.log(`  unrecoverable           ${j.unrecoverable.toFixed(3)}`);
-    console.log(`  shared infrastructure   ${j.targetsSharedInfrastructure.toFixed(3)}`);
-    console.log(`  blast radius            ${j.blastRadius.toFixed(2)}/3  (confidence ${j.blastRadiusConfidence.toFixed(2)})`);
+    const judgments = verdict.judgments;
+    dependencies.stdout("");
+    dependencies.stdout(
+      `  executes destruction    ${judgments.executesDestruction.toFixed(3)}`,
+    );
+    dependencies.stdout(
+      `  unrecoverable           ${judgments.unrecoverable.toFixed(3)}`,
+    );
+    dependencies.stdout(
+      `  shared infrastructure   ${judgments.targetsSharedInfrastructure.toFixed(3)}`,
+    );
+    dependencies.stdout(
+      `  blast radius            ${judgments.blastRadius.toFixed(2)}/3  (confidence ${judgments.blastRadiusConfidence.toFixed(2)})`,
+    );
   }
 
-  console.log("");
-  console.log(
+  dependencies.stdout("");
+  dependencies.stdout(
     `  ${verdict.latencyMs}ms${verdict.usage ? `, ${verdict.usage.inputTokens} in / ${verdict.usage.outputTokens} out tokens` : ""}`,
   );
+  return 0;
+}
+
+async function readSecret(prompt: string): Promise<string> {
+  if (!process.stdin.isTTY || typeof process.stdin.setRawMode !== "function") {
+    return (await Bun.stdin.text()).trim();
+  }
+
+  process.stderr.write(prompt);
+  process.stdin.setEncoding("utf8");
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+
+  return await new Promise<string>((resolve, reject) => {
+    let value = "";
+
+    const cleanup = () => {
+      process.stdin.off("data", onData);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stderr.write("\n");
+    };
+
+    const onData = (chunk: string | Buffer) => {
+      for (const character of String(chunk)) {
+        if (character === "\u0003" || character === "\u0004") {
+          cleanup();
+          reject(new Error("credential entry cancelled"));
+          return;
+        }
+
+        if (character === "\r" || character === "\n") {
+          cleanup();
+          resolve(value.trim());
+          return;
+        }
+
+        if (character === "\b" || character === "\u007f") {
+          value = Array.from(value).slice(0, -1).join("");
+          continue;
+        }
+
+        if (character >= " ") value += character;
+      }
+    };
+
+    process.stdin.on("data", onData);
+  });
+}
+
+function errorDetail(error: unknown): string {
+  return Predicate.isError(error) ? error.message : String(error);
 }
 
-await main();
+if (import.meta.main) {
+  process.exitCode = await runCli(Bun.argv.slice(2));
+}

package/src/judge.ts

@@ -12,7 +12,11 @@ import {
 } from "effect";
 import { AiError, DecisionModel } from "effect/unstable/ai";
 import { FetchHttpClient } from "effect/unstable/http";
-import { Environment, MISSING_KEY_HELP } from "./key.ts";
+import {
+  Environment,
+  MISSING_KEY_HELP,
+  TypeSafeApiKey,
+} from "./key.ts";
 import { COMMAND_JUDGMENTS } from "./questions.ts";
 import { renderState } from "./state.ts";
 import type { CommandState, FailureKind, Judgments } from "./types.ts";
@@ -71,6 +75,7 @@ export class JudgmentError extends Schema.TaggedError<JudgmentError>()(
   {
     failure: Schema.Literals([
       "no-api-key",
+      "credential-error",
       "timeout",
       "api-error",
       "unexpected",
@@ -92,6 +97,7 @@ export class Judgment extends Context.Service<
     Judgment,
     Effect.gen(function* () {
       const environment = yield* Environment;
+      const apiKey = yield* TypeSafeApiKey;
       let decisionLayer: ReturnType<typeof makeDecisionModelLayer> | undefined;
       let timeoutMs = DEFAULT_TIMEOUT_MS;
 
@@ -102,9 +108,16 @@ export class Judgment extends Context.Service<
         > {
           if (decisionLayer !== undefined) return decisionLayer;
 
-          const apiKey =
-            (yield* environment.get("TYPESAFE_API_KEY"))?.trim() || undefined;
-          if (apiKey === undefined) {
+          const resolvedApiKey = yield* apiKey.resolve.pipe(
+            Effect.mapError(
+              (error) =>
+                new JudgmentError({
+                  failure: "credential-error",
+                  detail: `Unable to read the operating system credential store: ${error.detail}`,
+                }),
+            ),
+          );
+          if (resolvedApiKey === undefined) {
             return yield* new JudgmentError({
               failure: "no-api-key",
               detail: MISSING_KEY_HELP,
@@ -115,7 +128,7 @@ export class Judgment extends Context.Service<
             yield* environment.get("DEMUR_TIMEOUT_MS"),
           );
           timeoutMs = configuredTimeout || DEFAULT_TIMEOUT_MS;
-          decisionLayer = makeDecisionModelLayer(apiKey);
+          decisionLayer = makeDecisionModelLayer(resolvedApiKey.value);
           return decisionLayer;
         },
       );
@@ -158,7 +171,7 @@ export class Judgment extends Context.Service<
   );
 
   static readonly layer = this.layerNoDeps.pipe(
-    Layer.provide(Environment.layer),
+    Layer.provide(Layer.merge(Environment.layer, TypeSafeApiKey.layer)),
   );
 }
 

package/src/key.ts

@@ -1,4 +1,40 @@
-import { Context, Effect, Layer } from "effect";
+import {
+  Context,
+  Effect,
+  Layer,
+  ManagedRuntime,
+  Predicate,
+  Schema,
+} from "effect";
+
+const TYPESAFE_SECRET = {
+  service: "com.github.wyattjoh.demur",
+  name: "typesafe-api-key",
+} as const;
+
+/**
+ * Where demur found the active TypeSafe API key.
+ */
+export type ApiKeySource = "environment" | "system";
+
+/**
+ * A resolved TypeSafe API key and the source that supplied it.
+ */
+export type ResolvedApiKey = {
+  value: string;
+  source: ApiKeySource;
+};
+
+/**
+ * A failure while accessing the operating system credential store.
+ */
+export class SecretStoreError extends Schema.TaggedError<SecretStoreError>()(
+  "SecretStoreError",
+  {
+    operation: Schema.Literals(["read", "write", "delete"]),
+    detail: Schema.String,
+  },
+) {}
 
 /**
  * Effect service for reading process environment variables.
@@ -23,16 +59,167 @@ export class Environment extends Context.Service<
 }
 
 /**
- * Resolve the TypeSafe API key from the environment.
+ * Effect service for the operating system's credential storage.
+ */
+export class SystemSecrets extends Context.Service<
+  SystemSecrets,
+  {
+    get(service: string, name: string): Effect.Effect<string | undefined, SecretStoreError>;
+    set(service: string, name: string, value: string): Effect.Effect<void, SecretStoreError>;
+    delete(service: string, name: string): Effect.Effect<boolean, SecretStoreError>;
+  }
+>()("demur/key/SystemSecrets") {
+  static readonly layer = Layer.succeed(
+    SystemSecrets,
+    SystemSecrets.of({
+      get: Effect.fn("SystemSecrets.get")(function* (
+        service: string,
+        name: string,
+      ) {
+        const value = yield* Effect.tryPromise({
+          try: () => Bun.secrets.get({ service, name }),
+          catch: secretStoreFailure("read"),
+        });
+        return value ?? undefined;
+      }),
+      set: Effect.fn("SystemSecrets.set")(function* (
+        service: string,
+        name: string,
+        value: string,
+      ) {
+        yield* Effect.tryPromise({
+          try: () => Bun.secrets.set({ service, name, value }),
+          catch: secretStoreFailure("write"),
+        });
+      }),
+      delete: Effect.fn("SystemSecrets.delete")(function* (
+        service: string,
+        name: string,
+      ) {
+        return yield* Effect.tryPromise({
+          try: () => Bun.secrets.delete({ service, name }),
+          catch: secretStoreFailure("delete"),
+        });
+      }),
+    }),
+  );
+}
+
+/**
+ * Effect service that resolves and manages demur's TypeSafe API key.
+ *
+ * `TYPESAFE_API_KEY` remains the highest-priority source for automation and
+ * one-off overrides. Otherwise, demur reads the key from the operating system's
+ * credential store through {@link SystemSecrets}.
+ */
+export class TypeSafeApiKey extends Context.Service<
+  TypeSafeApiKey,
+  {
+    readonly resolve: Effect.Effect<ResolvedApiKey | undefined, SecretStoreError>;
+    store(value: string): Effect.Effect<void, SecretStoreError>;
+    readonly remove: Effect.Effect<boolean, SecretStoreError>;
+  }
+>()("demur/key/TypeSafeApiKey") {
+  static readonly layerNoDeps = Layer.effect(
+    TypeSafeApiKey,
+    Effect.gen(function* () {
+      const environment = yield* Environment;
+      const secrets = yield* SystemSecrets;
+
+      const resolve = Effect.gen(function* () {
+        const environmentValue = normalizeApiKey(
+          yield* environment.get("TYPESAFE_API_KEY"),
+        );
+        if (environmentValue !== undefined) {
+          return {
+            value: environmentValue,
+            source: "environment",
+          } satisfies ResolvedApiKey;
+        }
+
+        const storedValue = normalizeApiKey(
+          yield* secrets.get(TYPESAFE_SECRET.service, TYPESAFE_SECRET.name),
+        );
+        if (storedValue === undefined) return undefined;
+
+        return {
+          value: storedValue,
+          source: "system",
+        } satisfies ResolvedApiKey;
+      });
+
+      const store = Effect.fn("TypeSafeApiKey.store")(function* (value: string) {
+        const normalized = normalizeApiKey(value);
+        if (normalized === undefined) {
+          return yield* new SecretStoreError({
+            operation: "write",
+            detail: "The TypeSafe API key cannot be empty.",
+          });
+        }
+
+        yield* secrets.set(
+          TYPESAFE_SECRET.service,
+          TYPESAFE_SECRET.name,
+          normalized,
+        );
+      });
+
+      return TypeSafeApiKey.of({
+        resolve,
+        store,
+        remove: secrets.delete(TYPESAFE_SECRET.service, TYPESAFE_SECRET.name),
+      });
+    }),
+  );
+
+  static readonly layer = this.layerNoDeps.pipe(
+    Layer.provide(Layer.merge(Environment.layer, SystemSecrets.layer)),
+  );
+}
+
+const runtime = ManagedRuntime.make(TypeSafeApiKey.layer);
+
+/**
+ * Resolve the TypeSafe API key for a Promise-based host integration.
+ *
+ * @returns The active key and its source, or `undefined` when none is configured
+ */
+export function resolveApiKey(): Promise<ResolvedApiKey | undefined> {
+  return runtime.runPromise(
+    Effect.gen(function* () {
+      const apiKey = yield* TypeSafeApiKey;
+      return yield* apiKey.resolve;
+    }),
+  );
+}
+
+/**
+ * Store a TypeSafe API key in the operating system credential store.
  *
- * demur does not fetch or persist credentials. Export `TYPESAFE_API_KEY` before
- * launching the host agent, or inject it with a secret manager so every hook
- * invocation inherits the already-resolved value.
+ * @param value - The API key to persist
+ * @returns A promise that completes after the credential is stored
+ */
+export function storeApiKey(value: string): Promise<void> {
+  return runtime.runPromise(
+    Effect.gen(function* () {
+      const apiKey = yield* TypeSafeApiKey;
+      return yield* apiKey.store(value);
+    }),
+  );
+}
+
+/**
+ * Delete demur's TypeSafe API key from the operating system credential store.
  *
- * @returns The API key, or `undefined` when the environment does not carry one
+ * @returns Whether a stored credential existed
  */
-export function resolveApiKey(): string | undefined {
-  return Bun.env.TYPESAFE_API_KEY?.trim() || undefined;
+export function deleteApiKey(): Promise<boolean> {
+  return runtime.runPromise(
+    Effect.gen(function* () {
+      const apiKey = yield* TypeSafeApiKey;
+      return yield* apiKey.remove;
+    }),
+  );
 }
 
 /**
@@ -42,4 +229,18 @@ export function resolveApiKey(): string | undefined {
  * name the fix, or the failure reads like a policy decision.
  */
 export const MISSING_KEY_HELP =
-  "No TYPESAFE_API_KEY in the environment. Export it, or inject it with a secret manager, before launching the agent.";
+  "No TypeSafe API key configured. Run `demur auth login`, set TYPESAFE_API_KEY, or inject it with a secret manager.";
+
+function normalizeApiKey(value: string | undefined): string | undefined {
+  return value?.trim() || undefined;
+}
+
+function secretStoreFailure(
+  operation: SecretStoreError["operation"],
+): (cause: unknown) => SecretStoreError {
+  return (cause) =>
+    new SecretStoreError({
+      operation,
+      detail: Predicate.isError(cause) ? cause.message : String(cause),
+    });
+}

package/src/types.ts

@@ -117,6 +117,7 @@ export type Decision = "allow" | "ask" | "deny";
  */
 export type FailureKind =
   | "no-api-key"
+  | "credential-error"
   | "timeout"
   | "api-error"
   | "unexpected";