@bothat-io/molenkopf 0.1.2

package/packages/core/src/identity/identity-validation.ts

@@ -0,0 +1,102 @@
+import { isBudget } from "./budget.ts";
+import { IDENTITY_SCHEMA_VERSION, type ApiKey, type IdentityData, type Team, type User } from "./types.ts";
+import type { PriceTable } from "./pricing.ts";
+
+export type IdentityRow = { id: string; json: string };
+export type IdentityMetaRow = { k: string; json: string };
+
+export function parseIdentityRow<T extends { id: string }>(row: IdentityRow, check: (value: unknown) => value is T, label: string): T {
+  const value = parseJson(row.json, label);
+  if (!check(value)) throw new Error(`invalid ${label} row`);
+  if (value.id !== row.id) throw new Error(`${label} id mismatch`);
+  return value;
+}
+
+export function loadIdentityMeta(data: IdentityData, row: IdentityMetaRow): void {
+  const value = parseJson(row.json, `meta ${row.k}`);
+  if (row.k === "orgBudget" && isBudget(value)) data.orgBudget = value;
+  else if (row.k === "pricing" && isPriceTable(value)) data.pricing = value;
+  else throw new Error(`invalid meta row ${row.k}`);
+}
+
+export function validateIdentityReferences(data: IdentityData): void {
+  for (const user of Object.values(data.users)) for (const id of user.teamIds) if (!data.teams[id]) throw new Error(`user ${user.id} references missing team`);
+  for (const team of Object.values(data.teams)) for (const id of team.managerIds) if (!data.users[id]) throw new Error(`team ${team.id} references missing manager`);
+  for (const key of Object.values(data.keys)) {
+    if (!data.users[key.ownerUserId]) throw new Error(`key ${key.id} references missing owner`);
+    if (key.teamId && !data.teams[key.teamId]) throw new Error(`key ${key.id} references missing team`);
+  }
+}
+
+export function validateIdentityData(data: IdentityData): void {
+  if (data.schemaVersion !== IDENTITY_SCHEMA_VERSION) throw new Error("invalid identity schema version");
+  validateRows(data.users, isIdentityUser, "user");
+  validateRows(data.teams, isIdentityTeam, "team");
+  validateRows(data.keys, isIdentityApiKey, "api_key");
+  if (data.orgBudget !== undefined && !isBudget(data.orgBudget)) throw new Error("invalid orgBudget row");
+  if (data.pricing !== undefined && !isPriceTable(data.pricing)) throw new Error("invalid pricing row");
+  validateIdentityReferences(data);
+}
+
+export function isIdentityUser(value: unknown): value is User {
+  const user = value as User;
+  return isObject(user) && isUserId(user.id) && typeof user.displayName === "string" && ["admin", "manager", "member"].includes(user.role)
+    && stringArray(user.teamIds) && typeof user.createdAt === "string" && (user.password === undefined || isPassword(user.password))
+    && (user.loginDisabled === undefined || typeof user.loginDisabled === "boolean") && (user.budget === undefined || isBudget(user.budget))
+    && (user.sessionVersion === undefined || (Number.isSafeInteger(user.sessionVersion) && user.sessionVersion >= 0));
+}
+
+export function isIdentityTeam(value: unknown): value is Team {
+  const team = value as Team;
+  return isObject(team) && isSlugId(team.id) && typeof team.name === "string" && (team.allowedProviders === "*" || stringArray(team.allowedProviders))
+    && stringArray(team.managerIds) && typeof team.createdAt === "string" && (team.budget === undefined || isBudget(team.budget));
+}
+
+export function isIdentityApiKey(value: unknown): value is ApiKey {
+  const key = value as ApiKey;
+  return isObject(key) && isSlugId(key.id) && typeof key.hash === "string" && typeof key.prefix === "string" && isUserId(key.ownerUserId)
+    && typeof key.createdAt === "string" && (key.teamId === undefined || isSlugId(key.teamId)) && (key.scopes === undefined || stringArray(key.scopes))
+    && (key.budget === undefined || isBudget(key.budget));
+}
+
+function parseJson(json: string, label: string): unknown {
+  try { return JSON.parse(json) as unknown; } catch { throw new Error(`invalid ${label} json`); }
+}
+
+function isPriceTable(value: unknown): value is PriceTable {
+  if (!isObject(value)) return false;
+  return Object.values(value).every((entry) => isObject(entry) && nonNegativeNumber(entry.inPerMTok) && nonNegativeNumber(entry.outPerMTok));
+}
+
+function isPassword(value: unknown): boolean {
+  const password = value as { salt?: unknown; hash?: unknown };
+  return isObject(password) && typeof password.salt === "string" && typeof password.hash === "string";
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function validateRows<T extends { id: string }>(rows: Record<string, T>, check: (value: unknown) => value is T, label: string): void {
+  for (const [id, value] of Object.entries(rows)) {
+    if (!check(value)) throw new Error(`invalid ${label} row`);
+    if (value.id !== id) throw new Error(`${label} id mismatch`);
+  }
+}
+
+function isUserId(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  return /^[a-z0-9][a-z0-9._:-]{0,63}$/i.test(value) || (value.length <= 254 && /^[a-z0-9._%+-]{1,64}@[a-z0-9.-]{1,190}\.[a-z]{2,24}$/i.test(value));
+}
+
+function isSlugId(value: unknown): value is string {
+  return typeof value === "string" && /^[a-z0-9][a-z0-9._:-]{0,63}$/i.test(value);
+}
+
+function stringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function nonNegativeNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}

package/packages/core/src/identity/key-permissions.ts

@@ -0,0 +1,18 @@
+import type { KeyPermissions, User } from "./types.ts";
+
+export type ResolvedKeyPermissions = Required<KeyPermissions>;
+
+export function resolveKeyPermissions(user: Pick<User, "keyPermissions"> | undefined): ResolvedKeyPermissions {
+  return {
+    create: user?.keyPermissions?.create !== false,
+    revoke: user?.keyPermissions?.revoke !== false
+  };
+}
+
+export function canCreateOwnKey(user: Pick<User, "keyPermissions"> | undefined): boolean {
+  return resolveKeyPermissions(user).create;
+}
+
+export function canRevokeOwnKey(user: Pick<User, "keyPermissions"> | undefined): boolean {
+  return resolveKeyPermissions(user).revoke;
+}

package/packages/core/src/identity/pricing.ts

@@ -0,0 +1,11 @@
+// Local, manually-maintained price table → € cost. No network lookups (invariant).
+// Prices are per 1,000,000 tokens, keyed by provider id; 0/absent means free.
+
+export type ProviderPrice = { inPerMTok: number; outPerMTok: number };
+export type PriceTable = Record<string, ProviderPrice>;
+
+export function costEur(price: ProviderPrice | undefined, inputTokens: number, outputTokens: number): number {
+  if (!price) return 0;
+  const cost = (inputTokens / 1_000_000) * (price.inPerMTok || 0) + (outputTokens / 1_000_000) * (price.outPerMTok || 0);
+  return Math.round(cost * 1e6) / 1e6; // round to micro-euro to avoid float drift
+}

package/packages/core/src/identity/types.ts

@@ -0,0 +1,87 @@
+import type { PasswordHash } from "../auth/password.ts";
+import type { PriceTable } from "./pricing.ts";
+
+// Identity model for the multi-user / team gateway (see
+// docs/superpowers/plans/2026-06-21-molenkopf-multiuser-team-redesign.md).
+// Persisted locally; provider credentials are NEVER stored here (RAM-only),
+// and API-key secrets are stored as a hash only — never in plaintext.
+
+export type Role = "admin" | "manager" | "member";
+export type BudgetPeriod = "day" | "week" | "month" | "total";
+export type BudgetAction = "block" | "warn";
+export type KeyPermissions = { create?: boolean; revoke?: boolean };
+
+export type Budget = {
+  tokenLimit?: number;
+  costLimitEur?: number;
+  period: BudgetPeriod;
+  onExceed: BudgetAction;
+};
+
+export type User = {
+  id: string;
+  displayName: string;
+  role: Role;
+  password?: PasswordHash;
+  loginDisabled?: boolean;
+  teamIds: string[];
+  keyPermissions?: KeyPermissions;
+  budget?: Budget;
+  disabled?: boolean;
+  sessionVersion?: number;
+  createdAt: string;
+  createdBy?: string;
+};
+
+export type Team = {
+  id: string;
+  name: string;
+  allowedProviders: "*" | string[];
+  managerIds: string[];
+  budget?: Budget;
+  createdAt: string;
+};
+
+export type ApiKey = {
+  id: string;            // public, displayable id, e.g. "key_ab12cd"
+  hash: string;          // sha256(secret) hex — the only stored form of the secret
+  prefix: string;        // first chars of the secret for recognition, e.g. "mk_ab12"
+  ownerUserId: string;
+  teamId?: string;       // optional billing team; fallback is owner team membership
+  agentLabel?: string;   // optional logical agent name ("ci-bot")
+  project?: string;      // optional project/workspace grouping for reporting
+  scopes?: string[];     // allowed provider ids; undefined = inherit owner/team allowance
+  budget?: Budget;
+  disabled?: boolean;
+  createdAt: string;
+  lastUsedAt?: string;
+};
+
+export type IdentityData = {
+  schemaVersion: number;
+  users: Record<string, User>;
+  teams: Record<string, Team>;
+  keys: Record<string, ApiKey>;
+  orgBudget?: Budget;
+  pricing?: PriceTable;
+};
+
+export const IDENTITY_SCHEMA_VERSION = 1;
+
+export function emptyIdentity(): IdentityData {
+  return { schemaVersion: IDENTITY_SCHEMA_VERSION, users: {}, teams: {}, keys: {} };
+}
+
+// View types omit secrets/hashes for safe display.
+export type UserView = Omit<User, "password"> & { hasPassword: boolean };
+export type ApiKeyView = Omit<ApiKey, "hash"> & {};
+
+export function viewUser(user: User): UserView {
+  const { password, ...rest } = user;
+  return { ...rest, hasPassword: Boolean(password?.hash) };
+}
+
+export function viewKey(key: ApiKey): ApiKeyView {
+  const { hash, ...rest } = key;
+  return { ...rest };
+}

package/packages/core/src/identity/usage-snapshot.ts

@@ -0,0 +1,116 @@
+import { openDb, type Db } from "./db.ts";
+import { defaultDataDir } from "../storage/local-paths.ts";
+
+// Persistent live-usage snapshot, stored in the SQLite `usage` table so per-key/
+// user/team/provider counters survive restarts. Audit remains the raw source of
+// truth; this is the fast aggregate. Coalesced background flush.
+
+export type UsageMaps = {
+  usageByAgent: Record<string, unknown>;
+  usageByUser: Record<string, unknown>;
+  usageByProvider: Record<string, unknown>;
+  usageByKey: Record<string, unknown>;
+  usageByTeam: Record<string, unknown>;
+};
+
+const FIELDS: (keyof UsageMaps)[] = ["usageByAgent", "usageByUser", "usageByProvider", "usageByKey", "usageByTeam"];
+
+export class UsageSnapshotError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "UsageSnapshotError";
+  }
+}
+
+export class UsageSnapshotStore {
+  private root: string;
+  private db?: Db;
+  private flushing = false;
+  private pending?: UsageMaps;
+  private flushPromise?: Promise<void>;
+  private lastError?: unknown;
+  private closed = false;
+
+  constructor(root = defaultDataDir()) {
+    this.root = root;
+  }
+
+  private handle(): Db {
+    if (!this.db) this.db = openDb(this.root);
+    return this.db;
+  }
+
+  async load(): Promise<Partial<UsageMaps> | undefined> {
+    const db = this.handle();
+    const rows = db.prepare("SELECT id, json FROM usage WHERE scope = 'live'").all() as { id: string; json: string }[];
+    if (!rows.length) return undefined;
+    const out: Partial<UsageMaps> = {};
+    for (const row of rows) {
+      if ((FIELDS as string[]).includes(row.id)) {
+        try {
+          (out as Record<string, unknown>)[row.id] = JSON.parse(row.json);
+        } catch {
+          throw new UsageSnapshotError(`invalid usage snapshot row: ${row.id}`);
+        }
+      }
+    }
+    return out;
+  }
+
+  async save(maps: UsageMaps): Promise<void> {
+    if (this.closed) throw new UsageSnapshotError("usage snapshot store closed");
+    const db = this.handle();
+    db.exec("BEGIN");
+    try {
+      const stmt = db.prepare("INSERT INTO usage(scope, id, json) VALUES('live', ?, ?) ON CONFLICT(scope, id) DO UPDATE SET json = excluded.json");
+      for (const field of FIELDS) stmt.run(field, JSON.stringify(maps[field] ?? {}));
+      db.exec("COMMIT");
+    } catch (error) {
+      db.exec("ROLLBACK");
+      throw error;
+    }
+  }
+
+  async flush(): Promise<void> {
+    if (this.lastError) { const error = this.lastError; this.lastError = undefined; throw error; }
+    if (this.closed) throw new UsageSnapshotError("usage snapshot store closed");
+    if (!this.flushPromise && this.pending) this.flushPromise = this.runFlush();
+    await this.flushPromise;
+    if (this.lastError) { const error = this.lastError; this.lastError = undefined; throw error; }
+  }
+
+  async close(): Promise<void> {
+    if (!this.closed) await this.flush();
+    this.closed = true;
+    try { this.db?.close(); } catch { /* ignore */ }
+    this.db = undefined;
+  }
+
+  // Coalesced background flush: marks dirty and flushes at most one at a time.
+  schedule(maps: UsageMaps): void {
+    if (this.closed) return;
+    this.pending = maps;
+    if (!this.flushing) queueMicrotask(() => {
+      this.flushPromise ??= this.runFlush().catch((error) => { this.lastError = error; });
+    });
+  }
+
+  private async runFlush(): Promise<void> {
+    this.flushing = true;
+    try {
+      while (this.pending && !this.closed) {
+        const next = this.pending;
+        this.pending = undefined;
+        try {
+          await this.save(next);
+        } catch (error) {
+          this.pending = next;
+          throw error;
+        }
+      }
+    } finally {
+      this.flushing = false;
+      this.flushPromise = undefined;
+    }
+  }
+}

package/packages/core/src/manifest/audit-activity.ts

@@ -0,0 +1,74 @@
+import type { AuditManifest } from "./audit-store.ts";
+import { confirmedSavedTokens } from "./audit-metrics.ts";
+
+export type AuditActivityGroup = {
+  id: string;
+  label: string;
+  clientId: string;
+  clientLabel: string;
+  keyId?: string;
+  project?: string;
+  providerId: string;
+  endpoint: string;
+  status: string;
+  requests: number;
+  errors: number;
+  unknown: number;
+  originalTokens: number;
+  forwardedTokens: number;
+  savedTokens: number;
+  compressedItems: number;
+  retrievalRefs: number;
+  latestAt?: string;
+};
+
+export function summarizeRecentActivity(manifests: AuditManifest[], limit = 8): AuditActivityGroup[] {
+  const groups = new Map<string, AuditActivityGroup>();
+  for (const manifest of manifests.slice(-50)) add(groups, manifest);
+  return [...groups.values()]
+    .sort((a, b) => (b.latestAt ?? "").localeCompare(a.latestAt ?? "") || b.requests - a.requests || a.id.localeCompare(b.id))
+    .slice(0, limit);
+}
+
+function add(groups: Map<string, AuditActivityGroup>, manifest: AuditManifest) {
+  const client: NonNullable<AuditManifest["client"]> = manifest.client ?? { id: "unattributed", label: "unattributed client", source: "unattributed" };
+  const providerId = manifest.providerId || manifest.targetHost || "unknown";
+  const endpoint = `${manifest.method} ${pathOnly(manifest.path)}`;
+  const status = statusGroup(manifest.statusCode);
+  const id = [client.id, client.keyId ?? "", client.project ?? "", providerId, endpoint, status].join("|");
+  const group: AuditActivityGroup = groups.get(id) ?? {
+    id, label: `${client.label} -> ${providerId}`, clientId: client.id, clientLabel: client.label, keyId: client.keyId, project: client.project,
+    providerId, endpoint, status, requests: 0, errors: 0, unknown: 0, originalTokens: 0, forwardedTokens: 0,
+    savedTokens: 0, compressedItems: 0, retrievalRefs: 0
+  };
+  group.requests++;
+  if (statusKind(manifest.statusCode) === "error") group.errors++;
+  if (statusKind(manifest.statusCode) === "unknown") group.unknown++;
+  group.originalTokens += manifest.estimatedOriginalTokens;
+  group.forwardedTokens += manifest.estimatedCompressedTokens;
+  group.savedTokens += confirmedSavedTokens(manifest);
+  group.compressedItems += manifest.compressedItems;
+  group.retrievalRefs += manifest.retrievalIds.length;
+  if (!group.latestAt || manifest.timestamp > group.latestAt) group.latestAt = manifest.timestamp;
+  groups.set(id, group);
+}
+
+function statusGroup(statusCode: number | undefined): string {
+  if (statusCode === undefined) return "unknown";
+  return `${Math.floor(statusCode / 100)}xx`;
+}
+
+function statusKind(statusCode: number | undefined): "ok" | "error" | "unknown" {
+  if (!Number.isInteger(statusCode)) return "unknown";
+  if (statusCode >= 200 && statusCode <= 399) return "ok";
+  if (statusCode >= 400 && statusCode <= 599) return "error";
+  return "unknown";
+}
+
+function pathOnly(path: string): string {
+  try {
+    return new URL(path, "http://molenkopf.local").pathname || "/";
+  } catch {
+    return "unknown";
+  }
+}

package/packages/core/src/manifest/audit-metrics.ts

@@ -0,0 +1,7 @@
+import type { AuditManifest } from "./audit-store.ts";
+
+export function confirmedSavedTokens(manifest: AuditManifest): number {
+  if (manifest.compressedItems <= 0) return 0;
+  if (manifest.estimatedSavedTokens > 0) return manifest.estimatedSavedTokens;
+  return Math.max(0, manifest.estimatedOriginalTokens - manifest.estimatedCompressedTokens);
+}

package/packages/core/src/manifest/audit-safety.ts

@@ -0,0 +1,113 @@
+import { redactSecrets } from "../security/secret-redactor.ts";
+import type { AuditManifest } from "./audit-store.ts";
+
+export function normalizedManifest(manifest: AuditManifest): AuditManifest {
+  if (!isAuditManifest(manifest)) throw new Error("invalid audit manifest");
+  const safe: AuditManifest = {
+    requestId: safeName(redactSecrets(manifest.requestId).text),
+    timestamp: Number.isNaN(Date.parse(manifest.timestamp)) ? new Date().toISOString() : manifest.timestamp,
+    method: manifest.method.replace(/[^A-Z]/gi, "").toUpperCase().slice(0, 12) || "GET",
+    path: safePath(manifest.path),
+    targetHost: safeToken(redactSecrets(manifest.targetHost).text, "target"),
+    compressedItems: finiteNumber(manifest.compressedItems),
+    estimatedOriginalTokens: finiteNumber(manifest.estimatedOriginalTokens),
+    estimatedCompressedTokens: finiteNumber(manifest.estimatedCompressedTokens),
+    estimatedSavedTokens: finiteNumber(manifest.estimatedSavedTokens),
+    redactedSecrets: finiteNumber(manifest.redactedSecrets),
+    retrievalIds: manifest.retrievalIds.map(safeRetrievalId).filter((item): item is string => Boolean(item)).slice(0, 50),
+    compressorsUsed: manifest.compressorsUsed.map((item) => redactedToken(String(item), "compressor")).slice(0, 20),
+    warnings: manifest.warnings.map((item) => safeWarning(redactSecrets(String(item)).text)).slice(0, 20)
+  };
+  const statusCode = finiteOptional(manifest.statusCode);
+  const durationMs = finiteOptional(manifest.durationMs);
+  const upstreamInputTokens = finiteOptional(manifest.upstreamInputTokens);
+  const upstreamOutputTokens = finiteOptional(manifest.upstreamOutputTokens);
+
+  if (manifest.providerId) safe.providerId = redactedToken(manifest.providerId, "provider");
+  if (manifest.client) safe.client = safeClient(manifest.client);
+  if (statusCode !== undefined) safe.statusCode = statusCode;
+  if (durationMs !== undefined) safe.durationMs = durationMs;
+  if (upstreamInputTokens !== undefined) safe.upstreamInputTokens = upstreamInputTokens;
+  if (upstreamOutputTokens !== undefined) safe.upstreamOutputTokens = upstreamOutputTokens;
+  return safe;
+}
+
+export function isAuditManifest(value: unknown): value is AuditManifest {
+  const item = value as AuditManifest;
+  return Boolean(item && typeof item === "object" && typeof item.requestId === "string" && typeof item.timestamp === "string"
+    && typeof item.method === "string" && typeof item.path === "string" && typeof item.targetHost === "string"
+    && typeof item.compressedItems === "number" && typeof item.estimatedOriginalTokens === "number"
+    && typeof item.estimatedCompressedTokens === "number" && typeof item.estimatedSavedTokens === "number"
+    && typeof item.redactedSecrets === "number" && finiteOptionalNumber(item.statusCode) && finiteOptionalNumber(item.durationMs)
+    && stringArray(item.retrievalIds) && stringArray(item.compressorsUsed) && stringArray(item.warnings));
+}
+
+function safeClient(client: NonNullable<AuditManifest["client"]>): NonNullable<AuditManifest["client"]> {
+  const source = safeSource(client.source);
+  const safe: NonNullable<AuditManifest["client"]> = {
+    source,
+    id: redactedToken(text(client.id, "client"), "client"),
+    label: redactedToken(text(client.label, source), source)
+  };
+  if (client.userId) safe.userId = redactedToken(text(client.userId, "user"), "user");
+  if (client.agentId) safe.agentId = redactedToken(text(client.agentId, "agent"), "agent");
+  if (client.teamIds) safe.teamIds = client.teamIds.map((id) => redactedToken(text(id, "team"), "team")).slice(0, 50);
+  if (client.keyId) safe.keyId = redactedToken(text(client.keyId, "key"), "key");
+  if (client.project) safe.project = redactedToken(text(client.project, "project"), "project");
+  return safe;
+}
+
+function safeName(value: string): string {
+  return value.replace(/[^a-z0-9._:-]/gi, "_").slice(0, 96) || "request";
+}
+
+function finiteNumber(value: number): number {
+  return Number.isFinite(value) ? value : 0;
+}
+
+function finiteOptional(value: number | undefined): number | undefined {
+  return Number.isFinite(value) ? value : undefined;
+}
+
+function text(value: unknown, fallback: string): string {
+  return typeof value === "string" ? value : fallback;
+}
+
+function safeToken(value: string, fallback: string): string {
+  const cleaned = value.replace(/[^a-z0-9._:@/-]/gi, "_").slice(0, 96);
+  return cleaned || fallback;
+}
+
+function redactedToken(value: string, fallback: string): string {
+  return safeToken(redactSecrets(value).text, fallback);
+}
+
+function safeSource(value: string): NonNullable<AuditManifest["client"]>["source"] {
+  return value === "user" || value === "agent" || value === "api_key" || value === "unattributed" ? value : "unattributed";
+}
+
+function safePath(path: string): string {
+  try {
+    return new URL(path, "http://local").pathname || "/";
+  } catch {
+    return path.split("?")[0] || "/";
+  }
+}
+
+function safeRetrievalId(value: string): string | undefined {
+  const redacted = redactSecrets(value).text;
+  return /^molenkopf:\/\/sha256\/[a-f0-9]{64}$/.test(redacted) ? redacted : undefined;
+}
+
+function safeWarning(value: string): string {
+  const cleaned = value.replace(/[^a-z0-9._:@/ -]/gi, "_").replace(/\s+/g, " ").trim().slice(0, 160);
+  return cleaned || "warning";
+}
+
+function stringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function finiteOptionalNumber(value: unknown): boolean {
+  return value === undefined || (typeof value === "number" && Number.isFinite(value));
+}