@bothat-io/molenkopf 0.1.2

package/docs/MOLENKOPF_PROVIDER_ENV.md

@@ -0,0 +1,123 @@
+# Molenkopf Provider ENV Setup
+
+This documents environment-based provider setup. The JSON config path for
+providers, agent bindings, plugin policies, and team distribution is
+[MOLENKOPF_JSON_CONFIG_PLAN.md](MOLENKOPF_JSON_CONFIG_PLAN.md).
+
+Use this when you want several upstream provider profiles in one local
+Molenkopf instance. Credentials stay in environment variables. Molenkopf only
+stores and displays the variable names.
+
+## Do Not Use
+
+- Do not paste Claude, ChatGPT, Codex, or browser login/session tokens here.
+- Do not commit a file with real keys.
+- Do not give employees upstream provider keys. Later they get Molenkopf tokens.
+
+Use provider API keys for API routing:
+
+- OpenAI API key: `OPENAI_API_KEY` or your own named env key.
+- Anthropic/Claude API key: `ANTHROPIC_API_KEY` or your own named env key.
+- Codex CLI / Claude CLI login sessions are supported through JSON config and
+  runtime-auth import flows. They are not configured through env provider blocks.
+
+## Single Built-In Profiles
+
+PowerShell:
+
+```powershell
+Copy-Item .env.example .env
+# Edit .env and set MOLENKOPF_SESSION_SECRET.
+$env:OPENAI_API_KEY = "replace-with-openai-api-key"
+$env:ANTHROPIC_API_KEY = "replace-with-anthropic-api-key"
+npm run dev
+```
+
+Then open:
+
+```text
+http://127.0.0.1:8787/__molenkopf/dashboard
+```
+
+Built-in provider IDs:
+
+```text
+openai-env
+anthropic-env
+ollama-local
+lmstudio-local
+```
+
+## Multiple Provider Profiles
+
+Use `MOLENKOPF_PROVIDER_IDS` plus one block per ID. The ID is converted to an
+env suffix by uppercasing and replacing `-` with `_`.
+
+Example:
+
+```powershell
+$env:MOLENKOPF_PROVIDER_IDS = "openai-main,openai-backup,claude-main,claude-work"
+
+$env:MOLENKOPF_PROVIDER_OPENAI_MAIN_NAME = "OpenAI Main"
+$env:MOLENKOPF_PROVIDER_OPENAI_MAIN_TARGET = "https://api.openai.com/v1"
+$env:MOLENKOPF_PROVIDER_OPENAI_MAIN_CREDENTIAL_ENV = "OPENAI_MAIN_API_KEY"
+$env:OPENAI_MAIN_API_KEY = "replace-with-openai-main-api-key"
+
+$env:MOLENKOPF_PROVIDER_OPENAI_BACKUP_NAME = "OpenAI Backup"
+$env:MOLENKOPF_PROVIDER_OPENAI_BACKUP_TARGET = "https://api.openai.com/v1"
+$env:MOLENKOPF_PROVIDER_OPENAI_BACKUP_CREDENTIAL_ENV = "OPENAI_BACKUP_API_KEY"
+$env:OPENAI_BACKUP_API_KEY = "replace-with-openai-backup-api-key"
+
+$env:MOLENKOPF_PROVIDER_CLAUDE_MAIN_NAME = "Claude Main"
+$env:MOLENKOPF_PROVIDER_CLAUDE_MAIN_TARGET = "https://api.anthropic.com/v1"
+$env:MOLENKOPF_PROVIDER_CLAUDE_MAIN_CREDENTIAL_ENV = "ANTHROPIC_MAIN_API_KEY"
+$env:MOLENKOPF_PROVIDER_CLAUDE_MAIN_AUTH = "x-api-key"
+$env:ANTHROPIC_MAIN_API_KEY = "replace-with-anthropic-main-api-key"
+
+$env:MOLENKOPF_PROVIDER_CLAUDE_WORK_NAME = "Claude Work"
+$env:MOLENKOPF_PROVIDER_CLAUDE_WORK_TARGET = "https://api.anthropic.com/v1"
+$env:MOLENKOPF_PROVIDER_CLAUDE_WORK_CREDENTIAL_ENV = "ANTHROPIC_WORK_API_KEY"
+$env:MOLENKOPF_PROVIDER_CLAUDE_WORK_AUTH = "x-api-key"
+$env:ANTHROPIC_WORK_API_KEY = "replace-with-anthropic-work-api-key"
+
+npm run dev
+```
+
+## Private Env File
+
+`.env` is ignored by git and loaded automatically by source runs. It may contain
+the required session secret and provider environment variables. Replace the
+placeholder session secret before starting Molenkopf:
+
+```env
+MOLENKOPF_SESSION_SECRET=replace-with-at-least-32-random-characters
+MOLENKOPF_PROVIDER_IDS=openai-main,claude-main
+MOLENKOPF_PROVIDER_OPENAI_MAIN_NAME=OpenAI Main
+MOLENKOPF_PROVIDER_OPENAI_MAIN_TARGET=https://api.openai.com/v1
+MOLENKOPF_PROVIDER_OPENAI_MAIN_CREDENTIAL_ENV=OPENAI_MAIN_API_KEY
+OPENAI_MAIN_API_KEY=replace-with-openai-main-api-key
+MOLENKOPF_PROVIDER_CLAUDE_MAIN_NAME=Claude Main
+MOLENKOPF_PROVIDER_CLAUDE_MAIN_TARGET=https://api.anthropic.com/v1
+MOLENKOPF_PROVIDER_CLAUDE_MAIN_CREDENTIAL_ENV=ANTHROPIC_MAIN_API_KEY
+MOLENKOPF_PROVIDER_CLAUDE_MAIN_AUTH=x-api-key
+ANTHROPIC_MAIN_API_KEY=replace-with-anthropic-main-api-key
+```
+
+`--env-file FILE` remains available when you intentionally want a different
+private file. Docker does not automatically read host `.env` files; pass the
+file explicitly with `docker run --env-file .env ...`.
+
+## Fields
+
+```text
+MOLENKOPF_PROVIDER_<ID>_NAME
+MOLENKOPF_PROVIDER_<ID>_TARGET
+MOLENKOPF_PROVIDER_<ID>_CREDENTIAL_ENV
+MOLENKOPF_PROVIDER_<ID>_AUTH=bearer | x-api-key | none
+MOLENKOPF_PROVIDER_<ID>_KIND=api | local
+MOLENKOPF_PROVIDER_<ID>_ENABLED=false
+```
+
+When a configured provider is selected, Molenkopf strips incoming client auth
+and injects the configured server-side env credential at the forwarding
+boundary.

package/docs/MOLENKOPF_USAGE.md

@@ -0,0 +1,195 @@
+# Molenkopf Usage
+
+This is the practical local test flow for Molenkopf.
+
+## Start
+
+```bash
+cp .env.example .env
+# Edit .env and set MOLENKOPF_SESSION_SECRET.
+npm run dev
+```
+
+Source runs load `./.env` automatically without overriding values already
+exported in your shell.
+
+Open `http://127.0.0.1:8787/__molenkopf/dashboard`. Use
+`http://127.0.0.1:8787/v1` as the OpenAI-compatible base URL in local clients.
+
+## Authenticate Proxy Traffic
+
+Create a Molenkopf API key in the dashboard after first-run setup. Every
+`/v1/...` proxy request needs that key. Use `Authorization: Bearer mk_...` when
+Molenkopf supplies provider credentials. If your client also needs to forward an
+upstream `Authorization` header, send the Molenkopf key as `x-molenkopf-token`.
+
+```text
+Authorization: Bearer mk_...
+x-molenkopf-token: mk_...
+```
+
+`x-molenkopf-agent` is optional local request metadata. It can select only an
+agent/provider binding already allowed by the authenticated key, team, and
+profile policy. Molenkopf strips local Molenkopf auth and routing headers before
+forwarding upstream.
+
+## Test Request
+
+Send a normal OpenAI-compatible request through the proxy. Then refresh the dashboard.
+
+```bash
+MOLENKOPF_API_KEY="mk_..."
+curl http://127.0.0.1:8787/v1/responses \
+  -H "x-molenkopf-token: ${MOLENKOPF_API_KEY}" \
+  -H "authorization: Bearer ${OPENAI_API_KEY}" \
+  -H "content-type: application/json" \
+  -d '{"model":"gpt-4.1-mini","input":"short local test"}'
+```
+
+PowerShell:
+
+```powershell
+$env:MOLENKOPF_API_KEY = "mk_..."
+curl.exe http://127.0.0.1:8787/v1/responses `
+  -H "x-molenkopf-token: $env:MOLENKOPF_API_KEY" `
+  -H "authorization: Bearer $env:OPENAI_API_KEY" `
+  -H "content-type: application/json" `
+  -d '{ "model": "gpt-4.1-mini", "input": "short local test" }'
+```
+
+Expected result:
+
+- `/__molenkopf/requests/latest` returns a redacted audit manifest for an
+  authenticated admin session.
+- `Dashboard -> Overview` updates after refresh or polling.
+- `Context compression flow` increments request and token counters.
+- `Memory graph workspace` shows text-derived safe graph data after transferred text is observed.
+
+## Provider Setup
+
+`molenkopf.config.json` is the provider startup source when present or passed
+  with `--config`. Provider API keys must be referenced from environment
+variables with `auth.credentialRef`, for example `env:OPENAI_MAIN_API_KEY`.
+Inline credentials are rejected in file config. The setup for ENV-defined
+providers remains in
+[MOLENKOPF_PROVIDER_ENV.md](MOLENKOPF_PROVIDER_ENV.md).
+
+Start from the example:
+
+```powershell
+Copy-Item molenkopf.config.example.json molenkopf.config.json
+$env:OPENAI_MAIN_API_KEY = "<your OpenAI API key>"
+$env:ANTHROPIC_MAIN_API_KEY = "<your Anthropic API key>"
+molenkopf proxy --config molenkopf.config.json
+```
+
+Then inspect:
+
+```text
+http://127.0.0.1:8787/__molenkopf/providers
+http://127.0.0.1:8787/__molenkopf/config
+```
+
+Expected:
+
+- only the JSON providers are listed
+- `credentialRef: env:OPENAI_MAIN_API_KEY` and `credentialConfigured: true`
+  are visible after the environment variable is set
+- real API key values are loaded from the local environment but not returned by
+  Local API
+- no ENV provider blocks are mixed into JSON startup
+
+### Local CLI And Local Models
+
+Use `kind: "cli-claude"` or `kind: "cli-codex"` for local CLI accounts, and
+`kind: "ollama"` or `kind: "lmstudio"` for local OpenAI-compatible model
+servers. Runtime-auth imports run CLI providers with isolated local auth/profile
+directories. Provider switching is visible in Admin; explicit agent bindings can
+route `x-molenkopf-agent` values to configured providers without bypassing
+team/provider allowlists or API-key scopes.
+
+Providers added through the Admin form are runtime state unless represented by
+JSON config, env configuration, or imported runtime-auth metadata.
+
+## Users, Teams, Projects, And Keys
+
+Molenkopf separates project attribution from team policy:
+
+- `Project` is required on every API key. It describes the workload that uses
+  the key, for example `project-a`, `billing-batch`, or `local-test`.
+- `Team` is the organizational policy bucket. Teams own provider allowlists,
+  budget accounting, and scoped visibility. First-run setup creates the default
+  `everyone` team for the first admin.
+- `User` is the login and key owner. Users can belong to one or more teams.
+
+Dashboard support: Admin manages users, teams, providers, and system controls;
+Overview lets the signed-in user create and revoke permitted project keys. Raw
+key secrets are shown once only.
+
+Local API support:
+
+| Action | Endpoint |
+| --- | --- |
+| List users and teams | `GET /__molenkopf/identity` |
+| Create/update user | `POST /__molenkopf/identity/users` |
+| Remove user | `POST /__molenkopf/identity/users/remove` |
+| Create/update team | `POST /__molenkopf/identity/teams` |
+| Remove team | `POST /__molenkopf/identity/teams/remove` |
+| Create/list/revoke keys | `/__molenkopf/keys` and `/__molenkopf/keys/revoke` |
+
+If a user belongs to multiple teams, key creation must choose the team. If a
+user belongs to one team, Molenkopf can use that team automatically.
+
+## Troubleshooting
+
+- Dashboard stuck on `connecting`: restart the proxy so the current dashboard bundle is served.
+- `EADDRINUSE`: another proxy is already listening on the port; stop that process or start on another port.
+- `invalid_api_key`: create a Molenkopf project key in the dashboard and send it
+  as `Authorization: Bearer mk_...` or `x-molenkopf-token: mk_...`.
+- `OPENAI_API_KEY missing`: set the provider environment variable or forward an
+  upstream `Authorization` header with `x-molenkopf-token` for Molenkopf auth.
+- No graph nodes: send API traffic through `/v1/...`; internal dashboard requests are intentionally ignored.
+- Saved tokens stay `0`: the payload may be small or the compressor is disabled.
+- Imported Claude auth works but write/edit prompts still appear: that is the outer Claude harness permission profile, not the imported runtime auth. Track and fix this separately from provider auth.
+- Claude/Codex no-response: use the provider card `Test` action first. Molenkopf reports spawned CLI lifecycle, timeout, malformed output, and permission-prompt classes for the child process it owns.
+
+## Current Dashboard Views
+
+- `Overview`: connection status, signed-in user usage, teams, members, project
+  keys, and client connection snippets.
+- `Admin`: users, teams, provider accounts, routing, plugin controls, imported runtime auth, and workspace links.
+
+Dedicated Providers, Plugins, Requests, Audit, Agents, and Settings views are
+planned in `ROADMAP.md`. Until then, use the local APIs and plugin pages below
+for request/audit/plugin details.
+
+## Plugin Pages And Data
+
+Open plugin pages from the Admin plugin section. Context compression owns token
+pressure and savings views. The graph page is fed from redacted transferred text
+and safe request metadata; it does not read an Obsidian vault yet and does not
+render raw prompt or response content.
+
+## Current Boundaries
+
+- No full prompts or full responses are displayed.
+- File config rejects inline raw API credentials; use `auth.credentialRef`.
+  Provider credentials entered in the dashboard and imported runtime auth are
+  intentional local operator state, and Local API responses do not display
+  credential values.
+- Token hash drafts store hash metadata only; list responses show only that a hash exists plus a short fingerprint.
+- Provider routing is explicit: teams carry provider allowlists, API keys carry
+  project attribution, and provider selection can be manual or distributed by
+  configured profile.
+- Plugin toggle and order state persists in local runtime settings. Locked
+  plugin settings are normalized back to safe defaults on startup.
+
+## Verification
+
+Run:
+
+```bash
+npm test
+```
+
+The relevant checks cover dashboard rendering, script parsing, provider/plugin controls, agent draft safety, audit summaries, plugin pages, and proxy behavior.

package/docs/PRODUCT_INTENT.md

@@ -0,0 +1,36 @@
+# Molenkopf Product Intent
+
+Molenkopf is a local agent gateway for API and CLI based coding agents. The
+product must connect OpenAI/Codex and Anthropic/Claude traffic into one local
+endpoint and one local memory layer.
+
+## Target
+
+- Accept agent traffic from OpenAI-compatible APIs, Anthropic/Claude-compatible APIs, Codex CLI, and Claude CLI.
+- Let CLI agents run locally while their prompt/context stream is still observable through the gateway.
+- Reduce the real text/context that is sent upstream or into a CLI runtime.
+- Show live token savings only from real transferred payloads, not placeholder counters.
+- Store safe derived memory from transferred text so later turns can reuse it.
+- Build an Obsidian-style graph from the transferred text and derived memory, not from generic HTTP metadata.
+
+## Plugin Meaning
+
+Plugins are local capabilities in the agent path, not decorative dashboard pages.
+Plugins are middleware, but not all middleware can mutate traffic. Mutation
+rights are explicit plugin descriptor fields and are enforced by the proxy.
+
+- Context compression plugin: owns token reduction, before/after accounting, saved-token totals, skip reasons, and retrieval IDs for real context chunks.
+- Memory/Obsidian plugin: owns the derived text memory graph, semantic nodes, links, and local store updates from real agent text.
+- Provider/runtime plugins: adapt OpenAI API, Anthropic API, Codex CLI, Claude CLI, and later MCP into the same run/event contract.
+- Core safety pipeline: redacts secrets and prevents raw credentials, full prompts, and full responses from leaking into UI/logs. This is not optional plugin behavior.
+
+## UI Rules
+
+- Empty state must say no payloads observed yet. It must not show fake token pressure.
+- No unauthenticated proxy traffic graph as a product target. If attribution is
+  unknown, show it only as a routing/accounting warning.
+- Compression views must answer: what text entered, what was removed or represented by ID, what was sent, and how many tokens were saved.
+- Graph views must answer: what concepts/entities/threads were learned from transferred text and how they relate.
+- HTTP metadata graphs are diagnostics only, not the Obsidian workspace goal.
+
+Molenkopf should adapt that pattern at the gateway/runtime boundary instead of pretending all agents are API-key-only HTTP clients.

package/docs/THREAT_MODEL.md

@@ -0,0 +1,94 @@
+# Molenkopf Threat Model
+
+Date: 2026-06-23
+
+This model describes the public Molenkopf product target and calls out
+unfinished hardening explicitly.
+
+## Assets
+
+- Upstream provider credentials.
+- Molenkopf employee and agent tokens.
+- Raw prompts and raw responses.
+- Retrieval originals and derived summaries.
+- Audit manifests and token accounting.
+- Provider selection, plugin toggles, and memory export controls.
+
+## Attackers
+
+- Local untrusted process on the same machine.
+- Malicious local webpage that can reach loopback endpoints.
+- Another employee on the LAN if public bind is enabled.
+- Compromised plugin or dashboard payload.
+- Over-privileged internal agent token.
+- Accidental operator mistake, such as sending secrets in query strings.
+
+## Boundaries
+
+```text
+employee client
+  -> Molenkopf auth boundary
+  -> policy and plugin boundary
+  -> provider credential boundary
+  -> upstream provider
+```
+
+```text
+safe transferred text
+  -> redaction
+  -> compression
+  -> retrieval or memory store
+  -> audit/dashboard/exports
+```
+
+## Hardened Release Invariants
+
+These are target invariants for the team gateway. Remaining hardening work is
+tracked through the roadmap, GitHub issues, and release PRs.
+
+- No provider credential values in audit, dashboard, events, docs, or plugin data.
+- No full prompt or full response in audit, dashboard, events, or plugin pages.
+- Query strings are stripped or redacted before audit persistence.
+- First-run open mode exposes only health, current-session status, and
+  first-run admin creation.
+- `__molenkopf/*` control APIs require auth after setup; provider, plugin,
+  routing, agent, stats, event, config metadata, and retention endpoints are
+  admin-only.
+- `/v1/*` proxy traffic requires a valid Molenkopf API key.
+- Non-loopback source binds require an explicit `--allow-public-bind` opt-in.
+- Molenkopf tokens are stored as hashes and shown once.
+- Retrieval writes happen only after a real compression artifact is committed.
+- Obsidian writes require dry-run and path guards before apply.
+- Multi-account routing uses explicit provider profiles only.
+
+## Implemented Plugin And Core Safety Invariants
+
+- Plugins are optional extensions; core safety, audit, event, storage, and
+  routing code is not exposed as a plugin and is not user-toggleable.
+- Plugin descriptors declare type, read scopes, mutation scopes, toggle policy,
+  and workspace data scopes.
+- The request pipeline restores unauthorized body, route, and block mutations
+  and fails closed with `plugin_capability_violation`.
+- Remote plugin loading is disabled.
+- Core redaction runs before optional plugin middleware.
+
+## Storage Policy
+
+- Audit manifests are metadata-only. Manual purge exists; retention policy,
+  quotas, pagination, and project scope are planned.
+- Retrieval originals are local sensitive artifacts. Manual purge exists;
+  retention policy, quotas, and project scope are planned.
+- Memory currently stores a bounded in-memory derived graph. Persistent memory,
+  source refs, and retention policy are planned.
+- Dashboard state must not persist raw tokens.
+
+## Required Tests
+
+- Query secret does not appear in `/requests`, latest audit, summaries, SSE, dashboard, or plugin pages.
+- Nested JSON secrets are redacted before compression and audit.
+- `x-molenkopf-token` and local routing headers never reach upstream.
+- Unauthenticated control APIs return `401`; insufficient scopes return `403`.
+- Non-loopback bind without explicit opt-in fails at startup.
+- Revoked/expired tokens cannot call `/v1/*` or control APIs.
+- Retrieval no-op compression leaves no stored original.
+- Obsidian apply cannot write outside the selected vault root.

package/molenkopf.config.example.json

@@ -0,0 +1,68 @@
+{
+  "schemaVersion": 1,
+  "server": {
+    "bindHost": "127.0.0.1",
+    "port": 8787,
+    "dataDir": ".molenkopf"
+  },
+  "providers": [
+    {
+      "id": "openai-main",
+      "name": "OpenAI Main",
+      "kind": "openai-compatible",
+      "baseUrl": "https://api.openai.com/v1",
+      "auth": {
+        "scheme": "bearer",
+        "credentialRef": "env:OPENAI_MAIN_API_KEY"
+      },
+      "enabled": true
+    },
+    {
+      "id": "claude-main",
+      "name": "Claude Main",
+      "kind": "anthropic",
+      "baseUrl": "https://api.anthropic.com/v1",
+      "auth": {
+        "scheme": "x-api-key",
+        "credentialRef": "env:ANTHROPIC_MAIN_API_KEY"
+      },
+      "enabled": true
+    },
+    {
+      "id": "claude-local",
+      "name": "Claude Local CLI",
+      "kind": "cli-claude",
+      "command": "claude",
+      "args": ["--print"],
+      "inputMode": "stdin",
+      "timeoutMs": 120000,
+      "enabled": false
+    }
+  ],
+  "profiles": [
+    {
+      "id": "default-local",
+      "providerId": "openai-main",
+      "allowedModels": ["gpt-4.1-mini"],
+      "defaultModel": "gpt-4.1-mini"
+    }
+  ],
+  "pluginPolicies": [
+    {
+      "id": "standard-policy",
+      "enabledPluginIds": ["context-compressor-plugin"],
+      "remotePlugins": false
+    }
+  ],
+  "agents": [
+    {
+      "id": "local-codex",
+      "ownerId": "local",
+      "kind": "local-agent",
+      "profileId": "default-local",
+      "pluginPolicyId": "standard-policy",
+      "scopes": ["proxy:use"],
+      "enabled": true
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@bothat-io/molenkopf",
+  "version": "0.1.2",
+  "description": "Local gateway for API and CLI based coding agents with routing, redaction, compression, memory, audit, and dashboard controls.",
+  "author": "Molenkopf contributors",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "molenkopf": "bin/molenkopf.js"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bothat-io/molenkopf.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bothat-io/molenkopf/issues"
+  },
+  "homepage": "https://github.com/bothat-io/molenkopf#readme",
+  "keywords": [
+    "molenkopf",
+    "local-ai-gateway",
+    "coding-agents",
+    "proxy",
+    "redaction",
+    "audit"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    ".env.example",
+    "bin/",
+    "packages/core/src/",
+    "packages/proxy/src/",
+    "packages/plugins/context-compressor-plugin/descriptor.ts",
+    "packages/plugins/context-compressor-plugin/plugin.ts",
+    "packages/plugins/context-compressor-plugin/page.html",
+    "packages/plugins/obsidian-graph-plugin/descriptor.ts",
+    "packages/plugins/obsidian-graph-plugin/plugin.ts",
+    "packages/plugins/obsidian-graph-plugin/page.html",
+    "packages/plugins/shared/audit-projects.ts",
+    "packages/dashboard/dist/",
+    "packages/dashboard/public/molenkopf-logo.png",
+    "packages/dashboard/public/favicon.png",
+    "docs/DEPLOYMENT.md",
+    "docs/MOLENKOPF_PLUGIN_API.md",
+    "docs/MOLENKOPF_PROVIDER_ENV.md",
+    "docs/MOLENKOPF_USAGE.md",
+    "docs/PRODUCT_INTENT.md",
+    "docs/THREAT_MODEL.md",
+    "molenkopf.config.example.json",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "bootstrap": "npm ci && npm --prefix packages/dashboard ci",
+    "typecheck": "npm run typecheck:node && npm --prefix packages/dashboard run typecheck",
+    "typecheck:node": "tsc -p tsconfig.node.json",
+    "test": "npm run test:unit",
+    "test:unit": "npm run check:docs && npm run check:dashboard-install && npm run check:reachability && npm run check:source-completeness && npm run check:container-contract && npm run check:line-limits && npm run typecheck && npm --prefix packages/dashboard run build && npm run check:package && npm run test:scripts && npm run test:launcher && npm run vitest && npm run test:node",
+    "check:docs": "node scripts/check-doc-paths.js",
+    "check:dashboard-install": "node scripts/check-dashboard-install.js",
+    "check:reachability": "node scripts/check-reachability.js",
+    "check:source-completeness": "node scripts/check-source-completeness.js",
+    "check:container-contract": "node scripts/check-container-contract.js",
+    "check:package": "node scripts/check-package-contents.js",
+    "check:line-limits": "node scripts/check-line-limits.js",
+    "test:scripts": "node --test scripts/*.test.js",
+    "test:launcher": "node --test test/*.test.js",
+    "test:node": "node --experimental-strip-types --experimental-sqlite --disable-warning=ExperimentalWarning --import ./packages/proxy/test/setup.ts --test --test-concurrency=1 packages/core/test/*.test.ts packages/proxy/test/*.test.ts packages/dashboard/test/*.test.ts",
+    "test:all": "npm run test:unit && npm run e2e",
+    "vitest": "npm --prefix packages/dashboard run test",
+    "e2e": "npm --prefix packages/dashboard run e2e",
+    "prepack": "npm --prefix packages/dashboard run build && npm run check:package",
+    "pack:dry": "npm pack --dry-run",
+    "smoke:installed": "node scripts/smoke-installed-package.js",
+    "smoke:docker": "node scripts/smoke-docker.js",
+    "release:npm:check": "node scripts/check-npm-release.js",
+    "release:verify": "npm run test:unit && npm run e2e && npm run smoke:installed && npm run smoke:docker",
+    "serve:dev": "node --experimental-strip-types --experimental-sqlite --disable-warning=ExperimentalWarning packages/proxy/src/cli/profile-server.ts dev",
+    "serve:test": "node --experimental-strip-types --experimental-sqlite --disable-warning=ExperimentalWarning packages/proxy/src/cli/profile-server.ts test",
+    "serve:prod": "npm --prefix packages/dashboard run build && node --experimental-strip-types --experimental-sqlite --disable-warning=ExperimentalWarning packages/proxy/src/cli/profile-server.ts prod",
+    "dev": "npm run serve:dev",
+    "prod": "npm run serve:prod"
+  },
+  "directories": {
+    "doc": "docs"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  }
+}

package/packages/core/src/auth/password.ts

@@ -0,0 +1,47 @@
+import { randomBytes, scrypt, scryptSync, timingSafeEqual } from "node:crypto";
+import { promisify } from "node:util";
+
+// Password hashing with scrypt (Node built-in). We store salt + hash only, never
+// the raw password. Used for admin/user login.
+
+const scryptAsync = promisify(scrypt);
+export const MAX_PASSWORD_BYTES = 4096;
+export type PasswordHash = { salt: string; hash: string; version?: 1; keyLength?: number };
+
+export function hashPassword(password: string): PasswordHash {
+  assertPasswordSize(password);
+  const salt = randomBytes(16).toString("hex");
+  const hash = scryptSync(password, salt, 64).toString("hex");
+  return { salt, hash, version: 1, keyLength: 64 };
+}
+
+export async function hashPasswordAsync(password: string): Promise<PasswordHash> {
+  assertPasswordSize(password);
+  const salt = randomBytes(16).toString("hex");
+  const keyLength = 64;
+  const hash = (await scryptAsync(password, salt, keyLength) as Buffer).toString("hex");
+  return { salt, hash, version: 1, keyLength };
+}
+
+export function verifyPassword(password: string, stored: PasswordHash | undefined): boolean {
+  if (!stored?.salt || !stored.hash) return false;
+  if (passwordTooLong(password)) return false;
+  const candidate = scryptSync(password, stored.salt, stored.keyLength ?? 64);
+  const expected = Buffer.from(stored.hash, "hex");
+  return candidate.length === expected.length && timingSafeEqual(candidate, expected);
+}
+
+export async function verifyPasswordAsync(password: string, stored: PasswordHash | undefined): Promise<boolean> {
+  if (!stored?.salt || !stored.hash || passwordTooLong(password)) return false;
+  const candidate = await scryptAsync(password, stored.salt, stored.keyLength ?? 64) as Buffer;
+  const expected = Buffer.from(stored.hash, "hex");
+  return candidate.length === expected.length && timingSafeEqual(candidate, expected);
+}
+
+export function passwordTooLong(password: string): boolean {
+  return Buffer.byteLength(password, "utf8") > MAX_PASSWORD_BYTES;
+}
+
+function assertPasswordSize(password: string): void {
+  if (passwordTooLong(password)) throw new Error("password_too_long");
+}