@krimto-labs/krimto 0.2.6

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,268 @@
+# Krimto
+
+> **Krimto — open-source team memory for AI coding agents.** Personal, team, and org knowledge your
+> agents share, in plain markdown you own (git-backed, Apache-2.0). **Try it solo in two minutes, then
+> bring your team.**
+
+One shared brain for every agent at your company. Every agent at every team writes facts to one
+place and reads the right slice of it — Alice's preferences override the team's defaults, the team's
+conventions override the org's standards, and every fact carries a paper trail (author, source,
+timestamp, reviewer).
+
+> **Where we are:** this is the **v0.2** surface. Here today: the markdown-in-git storage layer, the
+> `user → team → org` hierarchy, hybrid retrieval, server-enforced access, two-way git sync, and the
+> MCP server over **both stdio and HTTP — the HTTP transport has `Bearer` API-key auth and
+> `/health` endpoints**. On the near-term roadmap: a single-Docker image and the web UI. We claim the
+> team-memory position now and fulfil it in the open — see [ROADMAP.md](ROADMAP.md).
+
+## Try it in 2 minutes (solo, no account)
+
+1. **Run it** (data stays in `~/.krimto`):
+   ```bash
+   docker run -d -p 8080:8080 -v ~/.krimto:/data ghcr.io/krimto-labs/krimto:latest    # or, from a clone: pnpm dev
+   ```
+2. **Point Claude Code at it — one line, no key:**
+   ```json
+   { "mcpServers": { "krimto": { "url": "http://localhost:8080/mcp" } } }
+   ```
+   (or run `claude mcp add --transport http krimto http://localhost:8080/mcp`)
+3. Tell your agent: **"remember that our staging DB resets every Sunday."** Then ask in a *new* chat:
+   **"what do you know about staging?"** — it remembers.
+4. Open **http://localhost:8080** to browse. That's your *personal* layer — Krimto's point is the
+   **team** layer: restart with `KRIMTO_BOOTSTRAP_ADMIN=you@acme.com` to turn on accounts and invite
+   teammates.
+
+## Connect your agent
+
+Krimto is one MCP server — point any client at `http://localhost:8080/mcp`. Verified for **Claude Code**
+and **Cursor**:
+
+**Claude Code** (local, no key):
+
+```bash
+claude mcp add --transport http krimto http://localhost:8080/mcp
+```
+
+**Cursor** (local, no key) — add to `~/.cursor/mcp.json` and restart Cursor:
+
+```json
+{ "mcpServers": { "krimto": { "url": "http://localhost:8080/mcp" } } }
+```
+
+…or one-click: open **http://localhost:8080/ui/connect** and click **Add to Cursor**.
+
+**Team mode** (after `KRIMTO_BOOTSTRAP_ADMIN`): connecting needs your API key. The server prints a
+ready-to-paste config (with the key) on boot, and `/ui/connect` shows it too. Add the key as a header:
+
+- Claude Code: append `--header "Authorization: Bearer krm_live_…"`
+- Cursor: add `"headers": { "Authorization": "Bearer krm_live_…" }` to the server block
+
+Other clients (Codex, Gemini CLI, Copilot, Cline) use the same `url` (plus the `Bearer` header in team
+mode); those are best-effort and not yet individually verified.
+
+### Make it automatic
+
+By default your agent uses Krimto only when you ask. To make it recall and save **on its own**, add a
+standing rule to your agent's rules file — Claude Code: `CLAUDE.md`; Cursor: `.cursor/rules/krimto.mdc`;
+Codex: `AGENTS.md`; Gemini CLI: `GEMINI.md`:
+
+```
+# Krimto memory — always use
+- Before a task, call krimto_recall to load what we already know.
+- When I say "remember", or you learn a durable fact, call krimto_write
+  (user/me = personal, team/<slug> = shared).
+- Respect precedence: user beats team beats org.
+- Don't save secrets or one-off chatter.
+```
+
+The in-product **Connect** page (`/ui/connect`) shows this same rule with a copy button.
+
+## How it works
+
+Three layers, one source of truth:
+
+1. **Storage** — facts are **markdown files in a git repository**. Humans read them, edit them, and
+   review them via pull request. Git is the audit log.
+2. **Index** — a **SQLite + sqlite-vec** hybrid index (BM25 + vector) sits on top for fast semantic
+   retrieval, with hierarchical scope precedence applied at ranking time.
+3. **Access** — an **API server** enforces who can read/write which scope. Folder paths are the data
+   model; the server is the access enforcer (filesystem permissions are not RBAC).
+
+This hybrid pattern (markdown for storage + index for retrieval + server for access) is the
+verified-successful approach used by Claude Code's CLAUDE.md system, Manus, OpenClaw, and
+[memweave](https://towardsdatascience.com/) (Towards Data Science, April 2026). Krimto's
+differentiator is the storage *choice within* that pattern — human-readable markdown in git — plus
+`user → team → org` hierarchy as the primary primitive.
+
+## Quick start (self-host)
+
+```bash
+git clone https://github.com/krimto-labs/krimto && cd krimto
+pnpm install
+```
+
+Facts live as markdown files under `KRIMTO_DATA` (default `~/.krimto/`) — a folder you can open in any
+editor and version with git. Run Krimto with `pnpm` (Options A/B) or in **Docker** (Option C).
+
+### Option A — local, over stdio (no auth)
+
+For a single developer on one machine. **Fastest path — no clone, no Docker** (Claude Code shown):
+
+```bash
+claude mcp add krimto -- npx -y @krimto-labs/krimto
+```
+
+…or the config-file form any stdio MCP client accepts (Cursor, Codex CLI, Gemini CLI, Copilot,
+OpenClaw, Cline use the same shape):
+
+```json
+{
+  "mcpServers": {
+    "krimto": {
+      "command": "npx",
+      "args": ["-y", "@krimto-labs/krimto"],
+      "env": { "KRIMTO_IDENTITY": "you@acme.com" }
+    }
+  }
+}
+```
+
+The first run downloads dependencies (including `better-sqlite3`, which ships prebuilt binaries), then
+starts the **stdio** server with data in `~/.krimto` (override with `KRIMTO_DATA`). This is the solo
+path; HTTP/team mode uses Docker (Option C) or the server below.
+
+From a clone instead of npm, swap the command for `pnpm`:
+
+```json
+{
+  "mcpServers": {
+    "krimto": {
+      "command": "pnpm",
+      "args": ["--dir", "/absolute/path/to/krimto", "dev"],
+      "env": { "KRIMTO_DATA": "/Users/you/.krimto", "KRIMTO_IDENTITY": "you@acme.com" }
+    }
+  }
+}
+```
+
+`KRIMTO_IDENTITY` is who the agent writes as (fact author + access scope). Stdio mode has **no network
+auth** — run it locally/trusted.
+
+### Option B — over HTTP, with bearer auth (teams)
+
+For a shared/networked deployment. Start the HTTP server; the first run prints an admin API key once:
+
+```bash
+KRIMTO_HTTP_PORT=8080 KRIMTO_BOOTSTRAP_ADMIN=you@acme.com pnpm dev
+# → "issued admin API key for you@acme.com (shown once): krm_live_…"
+# MCP at http://localhost:8080/mcp ; health at http://localhost:8080/health/ready
+```
+
+Then point your agent at it with that key:
+
+```json
+{
+  "mcpServers": {
+    "krimto": {
+      "url": "http://localhost:8080/mcp",
+      "headers": { "Authorization": "Bearer krm_live_..." }
+    }
+  }
+}
+```
+
+To sync with teammates, set `KRIMTO_GIT_REMOTE` to a git remote you can push/pull over SSH.
+
+Optional HTTP knobs (both **off by default**): set `KRIMTO_RATE_LIMIT_PER_MINUTE=<n>` to rate-limit
+each API key on `/mcp` (responses carry `X-RateLimit-*`; over the limit returns `429` with
+`Retry-After`); set `KRIMTO_TELEMETRY_ENDPOINT=<url>` to send anonymous, **bucketed** usage counts
+(version, install id, and size buckets only — never fact content, identities, queries, scopes, or git
+remotes).
+
+**Locked out of the admin account?** Restart with `KRIMTO_REISSUE_ADMIN_KEY=you@acme.com` to mint and
+print a fresh admin key. (The web UI also refuses to revoke your last remaining key.)
+
+**Multi-instance sync:** Krimto pushes and pulls on the repo's current branch, so give every instance
+the same default branch — e.g. `git config --global init.defaultBranch main` before first run. A
+stuck pull is reported at `/health/ready` under `git_sync` (it never blocks readiness).
+
+When an agent saves a personal note, point it at `user/me` — the server resolves that to the caller's
+own scope, so facts never land in an unreadable scope.
+
+**Inviting teammates (org admins).** Open `http://localhost:8080/ui/admin` (or use the
+admin REST API: `POST /admin/members`, `POST /admin/keys`, `POST /admin/teams`,
+`PATCH /admin/teams/:slug`, all bearer-authed and org-admin-only) to add members, manage teams, and
+issue/revoke keys — no file edits or restarts. `KRIMTO_BOOTSTRAP_ADMIN` only makes the **first** admin;
+add later admins/members through the admin surface.
+
+### Option C — Docker (HTTP + bearer auth, containerized)
+
+Build the image and run it (a published image is coming):
+
+```bash
+docker build -t krimto .
+docker run -d --name krimto -p 8080:8080 \
+  -e KRIMTO_BOOTSTRAP_ADMIN=you@acme.com \
+  -v ~/.krimto:/data \
+  krimto
+docker logs krimto | grep "admin API key"   # the key is printed once
+```
+
+The container serves MCP at `http://localhost:8080/mcp` (bearer auth) and health at
+`/health/ready`; facts persist in the mounted `/data` volume. Point your agent at it with the same
+`"url"` + `Bearer` config as Option B.
+
+**Pulling a published image (no local build):** pushing a `v*` git tag runs
+[`.github/workflows/docker-publish.yml`](.github/workflows/docker-publish.yml), which publishes the
+image to `ghcr.io/krimto-labs/krimto`. After the first release tag you can skip `docker build` and run
+the published image directly:
+
+```bash
+docker run -d --name krimto -p 8080:8080 \
+  -e KRIMTO_BOOTSTRAP_ADMIN=you@acme.com -v ~/.krimto:/data \
+  ghcr.io/krimto-labs/krimto:latest
+```
+
+### Web UI (humans)
+
+When the HTTP server is running, open `http://localhost:8080/ui` and **sign in with any Krimto API
+key**. You can browse and search the facts you're allowed to see, open a fact, and manage your own API
+keys (issue / revoke). It reuses the same access control as the MCP tools, so you only ever see facts
+you can read. Set `KRIMTO_SESSION_SECRET` to keep sessions valid across restarts (otherwise a random
+per-boot secret is used). The UI is read-only for facts; editing with a review/approval flow lands in
+v0.3.
+
+## The eight promises (current status)
+
+| # | Promise | Status |
+|---|---------|--------|
+| 1 | Markdown-first hybrid storage | ✓ v0.2 |
+| 2 | Hierarchical scope (`user`/`team`/`org`) as primary primitive | ✓ v0.2 |
+| 3 | Cross-vendor SDK (MCP server + per-marketplace plugins) | ✓ MCP server over stdio + HTTP v0.2; native plugins planned |
+| 4 | Attribution baked into every fact | ✓ v0.2 |
+| 5 | Self-hostable, single Docker | ✓ v0.2 — stdio, HTTP, or **Docker** (`docker build` + `docker run`); a published pull-image is next |
+| 6 | Apache-2.0 — fully open, no rug-pull | ✓ |
+| 7 | Web interface for humans, on top of git | ✓ minimal v0.2 (`/ui` — login, browse/search, fact detail, API keys); full UI + PR approval in v0.3 |
+| 8 | Zero-friction migration between self-hosted and Cloud | ⏳ full flow with v1.0 Cloud (`git clone` works today) |
+
+## How Krimto compares
+
+Krimto combines three properties that are each uncommon among existing memory tools:
+
+- **Apache-2.0** — fully open, with no managed-service restriction. (ByteRover/Cipher is
+  source-available under the Elastic License 2.0, which is not OSI-approved open source.)
+- **Markdown-files-in-git storage** — human-readable and reviewable in git. (Hindsight uses
+  PostgreSQL; Mem0 uses a vector + graph database.)
+- **`user → team → org` hierarchy as the primary primitive.** (Mem0 organizes by user/session/agent.)
+
+Cross-vendor reach — working across Claude Code, Cursor, Codex, Gemini CLI, Copilot, OpenClaw, and
+Cline — is table stakes today, so Krimto ships it but doesn't lead with it.
+
+## Roadmap
+
+`v0.2` (teams, today) → `v0.3` (web UI) → `v1.0` (Krimto Cloud). See [ROADMAP.md](ROADMAP.md).
+
+## License
+
+[Apache-2.0](LICENSE). The same code is self-hostable by a solo developer, a startup, or an
+enterprise — no tier walls in the open-source distribution.

package/bin/krimto.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// npx entry: start the Krimto MCP server over stdio (solo, no Docker / no key).
+// The server source is ESM with extensionless imports, so it is loaded through tsx's
+// programmatic API — the same tsx-at-runtime approach the Dockerfile uses. No build step,
+// no rewrite. With no KRIMTO_HTTP_PORT set, main() takes the stdio path automatically.
+import process from "node:process";
+import { tsImport } from "tsx/esm/api";
+
+try {
+  const mod = await tsImport("../src/server/index.ts", import.meta.url);
+  await mod.main();
+} catch (e) {
+  process.stderr.write(`krimto: ${e instanceof Error ? e.message : String(e)}\n`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@krimto-labs/krimto",
+  "version": "0.2.6",
+  "description": "Open-source team memory layer for AI agents — markdown files in git, user/team/org hierarchy, cross-vendor MCP server.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "packageManager": "pnpm@11.2.2",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/krimto-labs/krimto.git"
+  },
+  "homepage": "https://krimto.com",
+  "bin": {
+    "krimto": "bin/krimto.mjs"
+  },
+  "files": [
+    "src",
+    "bin",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:integration": "vitest run tests/integration --passWithNoTests",
+    "dev": "tsx src/server/index.ts",
+    "start": "tsx src/server/index.ts"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.13.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.8.0",
+    "eslint": "^9.13.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.12.0",
+    "vitest": "^2.1.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.10.0",
+    "express": "^5.2.1",
+    "sqlite-vec": "^0.1.9",
+    "tsx": "^4.19.0",
+    "ulid": "^3.0.2",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  }
+}

package/src/access/auth.ts

@@ -0,0 +1,123 @@
+// Gap 06 — Authentication. MCP clients present an API key (bearer token); humans
+// paste an API key into the web UI (/ui), which holds it as a signed-cookie session
+// (real OAuth sign-in is v0.3). Keys are krm_live_/krm_test_ + 32 random base62 chars,
+// shown once, stored only as a hash.
+//
+// Note: API keys are ~190-bit random tokens, not passwords. A fast SHA-256 hash at
+// rest is the correct, performant choice (a per-request memory-hard KDF would add
+// ~100ms to every call). This is an intentional, reasoned divergence from the Build
+// Spec's literal "Argon2", which is meant for low-entropy secrets.
+
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+
+export type KeyEnvironment = "live" | "test";
+
+/** OAuth providers supported for the web UI (v0.3). Scaffold only for now. */
+export const OAUTH_PROVIDERS = ["google", "github", "microsoft-entra", "okta", "auth0"] as const;
+
+const BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+const KEY_BODY_LENGTH = 32;
+
+export interface ApiKeyRecord {
+  /** sha256(plaintext key), hex. */
+  hash: string;
+  identity: string;
+  prefix: string;
+  created: string;
+  label?: string;
+}
+
+export interface GeneratedKey {
+  /** Plaintext key — shown once, never persisted. */
+  key: string;
+  record: ApiKeyRecord;
+}
+
+function randomBase62(length: number): string {
+  const bytes = randomBytes(length);
+  let out = "";
+  for (let i = 0; i < length; i++) out += BASE62[(bytes[i] ?? 0) % 62];
+  return out;
+}
+
+export function hashKey(key: string): string {
+  return createHash("sha256").update(key).digest("hex");
+}
+
+export function generateApiKey(
+  identity: string,
+  env: KeyEnvironment = "live",
+  now: Date = new Date(),
+  label?: string,
+): GeneratedKey {
+  const prefix = `krm_${env}_`;
+  const key = `${prefix}${randomBase62(KEY_BODY_LENGTH)}`;
+  return { key, record: { hash: hashKey(key), identity, prefix, created: now.toISOString(), label } };
+}
+
+/** Constant-time comparison of a presented key against a stored hash. */
+export function keyMatches(presented: string, storedHashHex: string): boolean {
+  const a = Buffer.from(hashKey(presented), "hex");
+  const b = Buffer.from(storedHashHex, "hex");
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+/**
+ * File-backed API key store. MUST live outside the facts git repo (it holds secrets,
+ * even though only hashes are stored).
+ */
+export class ApiKeyStore {
+  constructor(private readonly filePath: string) {}
+
+  private async read(): Promise<ApiKeyRecord[]> {
+    try {
+      return JSON.parse(await fs.readFile(this.filePath, "utf8")) as ApiKeyRecord[];
+    } catch {
+      return [];
+    }
+  }
+
+  private async write(records: ApiKeyRecord[]): Promise<void> {
+    await fs.mkdir(path.dirname(this.filePath), { recursive: true });
+    await fs.writeFile(this.filePath, JSON.stringify(records, null, 2), "utf8");
+  }
+
+  /** Issue a new key for an identity. Returns the plaintext once. */
+  async issue(identity: string, env: KeyEnvironment = "live", label?: string): Promise<GeneratedKey> {
+    const generated = generateApiKey(identity, env, new Date(), label);
+    const records = await this.read();
+    records.push(generated.record);
+    await this.write(records);
+    return generated;
+  }
+
+  /** Resolve a presented key to its identity, or null if unknown. */
+  async resolveIdentity(presentedKey: string): Promise<string | null> {
+    for (const record of await this.read()) {
+      if (keyMatches(presentedKey, record.hash)) return record.identity;
+    }
+    return null;
+  }
+
+  /** List keys. Exposes the hash so callers can revoke by id. */
+  async list(): Promise<{ hash: string; identity: string; prefix: string; created: string; label?: string }[]> {
+    return (await this.read()).map((r) => ({
+      hash: r.hash,
+      identity: r.identity,
+      prefix: r.prefix,
+      created: r.created,
+      label: r.label,
+    }));
+  }
+
+  /** Remove the key with this hash. Returns true if one was removed. */
+  async revoke(hash: string): Promise<boolean> {
+    const records = await this.read();
+    const next = records.filter((r) => r.hash !== hash);
+    if (next.length === records.length) return false;
+    await this.write(next);
+    return true;
+  }
+}