@pellux/goodvibes-sdk 0.18.3 → 0.18.11

package/dist/platform/security/token-audit.js

@@ -0,0 +1,292 @@
+/**
+ * ApiTokenAuditor — minimum scope and rotation cadence enforcement.
+ *
+ * Security model (two audit dimensions):
+ *   1. Scope audit  — verifies each registered token only holds the scopes
+ *                     its declared policy permits (minimum scope principle)
+ *   2. Rotation audit — checks token age against the rotation cadence policy
+ *                       and emits warnings at the warning threshold, errors
+ *                       when rotation is overdue
+ *
+ * In managed mode, out-of-policy tokens are blocked from use.
+ * In advisory mode, violations are reported but not blocked.
+ */
+import { logger } from '../utils/logger.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default rotation cadence: 90 days in ms. */
+export const DEFAULT_ROTATION_CADENCE_MS = 90 * 24 * 60 * 60 * 1000;
+/** Default warning threshold: 14 days before rotation deadline. */
+export const DEFAULT_ROTATION_WARNING_THRESHOLD_MS = 14 * 24 * 60 * 60 * 1000;
+// ---------------------------------------------------------------------------
+// ApiTokenAuditor
+// ---------------------------------------------------------------------------
+/**
+ * Audits registered API tokens for scope minimization and rotation cadence.
+ *
+ * Usage:
+ * ```ts
+ * const auditor = new ApiTokenAuditor({ managed: true });
+ * auditor.registerPolicy({
+ *   id: 'openai',
+ *   name: 'OpenAI API',
+ *   allowedScopes: ['completions:write', 'models:read'],
+ *   rotationCadenceMs: 90 * 24 * 60 * 60 * 1000,
+ * });
+ * auditor.registerToken({
+ *   id: 'tok_openai_main',
+ *   label: 'OPENAI_API_KEY',
+ *   issuedAt: Date.now() - 30 * 24 * 60 * 60 * 1000,
+ *   grantedScopes: ['completions:write', 'models:read'],
+ *   policyId: 'openai',
+ * });
+ * const report = auditor.auditAll();
+ * ```
+ */
+export class ApiTokenAuditor {
+    _policies = new Map();
+    _tokens = new Map();
+    _config;
+    _emitter;
+    constructor(config = { managed: false }, options) {
+        this._config = config;
+        this._emitter = options?.emitter ?? ((_event) => { });
+    }
+    // -------------------------------------------------------------------------
+    // Registry
+    // -------------------------------------------------------------------------
+    /**
+     * Register a scope policy. Policies must be registered before tokens that
+     * reference them.
+     */
+    registerPolicy(policy) {
+        this._policies.set(policy.id, policy);
+        logger.debug('ApiTokenAuditor: registered policy', { policyId: policy.id });
+    }
+    /**
+     * Register an API token for auditing.
+     * Throws if the referenced policyId is not registered.
+     */
+    registerToken(metadata) {
+        if (!this._policies.has(metadata.policyId)) {
+            throw new Error(`ApiTokenAuditor: policyId '${metadata.policyId}' not registered — register the policy before the token`);
+        }
+        this._tokens.set(metadata.id, metadata);
+        logger.debug('ApiTokenAuditor: registered token', { tokenId: metadata.id, label: metadata.label });
+    }
+    /**
+     * Deregister a token (e.g. on rotation — remove the old registration,
+     * then registerToken with the new metadata).
+     */
+    deregisterToken(tokenId) {
+        return this._tokens.delete(tokenId);
+    }
+    // -------------------------------------------------------------------------
+    // Individual audits
+    // -------------------------------------------------------------------------
+    /**
+     * Audit the scope of a single token against its policy.
+     * Returns a TokenScopeAuditResult or null if the token is not registered.
+     */
+    auditScope(tokenId) {
+        const token = this._tokens.get(tokenId);
+        if (!token)
+            return null;
+        const policy = this._policies.get(token.policyId);
+        if (!policy)
+            return null;
+        return this._auditScopeFor(token, policy);
+    }
+    /**
+     * Audit the rotation cadence of a single token.
+     * Returns a TokenRotationAuditResult or null if the token is not registered.
+     */
+    auditRotation(tokenId, now = Date.now()) {
+        const token = this._tokens.get(tokenId);
+        if (!token)
+            return null;
+        const policy = this._policies.get(token.policyId);
+        if (!policy)
+            return null;
+        return this._auditRotationFor(token, policy, now);
+    }
+    // -------------------------------------------------------------------------
+    // Internal audit helpers (avoid map lookups + non-null assertions in auditAll)
+    // -------------------------------------------------------------------------
+    _auditScopeFor(token, policy) {
+        const allowedSet = new Set(policy.allowedScopes);
+        const excessScopes = token.grantedScopes.filter((s) => !allowedSet.has(s));
+        const outcome = excessScopes.length > 0 ? 'violation' : 'ok';
+        if (outcome === 'violation') {
+            logger.warn('ApiTokenAuditor: scope violation', {
+                tokenId: token.id,
+                label: token.label,
+                excessScopes,
+                policyId: policy.id,
+            });
+        }
+        return { tokenId: token.id, outcome, excessScopes, policyId: policy.id };
+    }
+    _auditRotationFor(token, policy, now) {
+        const cadenceMs = policy.rotationCadenceMs ?? DEFAULT_ROTATION_CADENCE_MS;
+        const warningThresholdMs = policy.rotationWarningThresholdMs ?? DEFAULT_ROTATION_WARNING_THRESHOLD_MS;
+        const ageMs = now - token.issuedAt;
+        const dueAt = token.issuedAt + cadenceMs;
+        const msUntilDue = dueAt - now;
+        let outcome;
+        if (msUntilDue < 0) {
+            outcome = 'overdue';
+            logger.warn('ApiTokenAuditor: token rotation overdue', {
+                tokenId: token.id,
+                label: token.label,
+                ageMs,
+                cadenceMs,
+                overdueMsByMs: Math.abs(msUntilDue),
+            });
+        }
+        else if (msUntilDue <= warningThresholdMs) {
+            outcome = 'warning';
+            logger.info('ApiTokenAuditor: token rotation approaching', {
+                tokenId: token.id,
+                label: token.label,
+                msUntilDue,
+                warningThresholdMs,
+            });
+        }
+        else {
+            outcome = 'ok';
+        }
+        return { tokenId: token.id, outcome, ageMs, cadenceMs, msUntilDue, dueAt };
+    }
+    // -------------------------------------------------------------------------
+    // Full audit
+    // -------------------------------------------------------------------------
+    /**
+     * Run scope and rotation audits for all registered tokens.
+     *
+     * In managed mode, tokens with scope violations or overdue rotation are
+     * flagged as blocked. Callers must check `result.blocked` or
+     * `report.blocked` before using a token.
+     */
+    auditAll(now = Date.now()) {
+        const results = [];
+        const blocked = [];
+        const scopeViolations = [];
+        const rotationWarnings = [];
+        const rotationOverdue = [];
+        for (const [tokenId, metadata] of this._tokens) {
+            const policy = this._policies.get(metadata.policyId);
+            if (!policy)
+                continue;
+            const scope = this._auditScopeFor(metadata, policy);
+            const rotation = this._auditRotationFor(metadata, policy, now);
+            const hasViolation = scope.outcome === 'violation';
+            const isOverdue = rotation.outcome === 'overdue';
+            const isWarning = rotation.outcome === 'warning';
+            // In managed mode: block tokens with scope violations or overdue rotation
+            const isBlocked = this._config.managed && (hasViolation || isOverdue);
+            const result = {
+                tokenId,
+                label: metadata.label,
+                scope,
+                rotation,
+                blocked: isBlocked,
+            };
+            results.push(result);
+            if (hasViolation) {
+                scopeViolations.push(tokenId);
+                this._emitter({
+                    type: 'TOKEN_SCOPE_VIOLATION',
+                    tokenId,
+                    label: metadata.label,
+                    policyId: scope.policyId,
+                    excessScopes: scope.excessScopes,
+                });
+            }
+            if (isOverdue) {
+                rotationOverdue.push(tokenId);
+                this._emitter({
+                    type: 'TOKEN_ROTATION_EXPIRED',
+                    tokenId,
+                    label: metadata.label,
+                    ageMs: rotation.ageMs,
+                    cadenceMs: rotation.cadenceMs,
+                    dueAt: rotation.dueAt,
+                });
+            }
+            if (isWarning) {
+                rotationWarnings.push(tokenId);
+                this._emitter({
+                    type: 'TOKEN_ROTATION_WARNING',
+                    tokenId,
+                    label: metadata.label,
+                    msUntilDue: rotation.msUntilDue,
+                    dueAt: rotation.dueAt,
+                    ageMs: rotation.ageMs,
+                });
+            }
+            if (isBlocked) {
+                blocked.push(tokenId);
+                const reason = hasViolation && isOverdue
+                    ? 'scope_violation_and_rotation_overdue'
+                    : hasViolation
+                        ? 'scope_violation'
+                        : 'rotation_overdue';
+                this._emitter({ type: 'TOKEN_BLOCKED', tokenId, label: metadata.label, reason });
+                logger.error('ApiTokenAuditor: token blocked (out-of-policy, managed mode)', {
+                    tokenId,
+                    label: metadata.label,
+                    scopeViolation: hasViolation,
+                    rotationOverdue: isOverdue,
+                });
+            }
+        }
+        return {
+            results,
+            blocked,
+            scopeViolations,
+            rotationWarnings,
+            rotationOverdue,
+            capturedAt: now,
+        };
+    }
+    /**
+     * Check whether a specific token is currently blocked.
+     * Returns false when not in managed mode or when the token is not registered.
+     */
+    isBlocked(tokenId, now = Date.now()) {
+        if (!this._config.managed)
+            return false;
+        const scope = this.auditScope(tokenId);
+        if (!scope)
+            return false;
+        const rotation = this.auditRotation(tokenId, now);
+        if (!rotation)
+            return false;
+        return scope.outcome === 'violation' || rotation.outcome === 'overdue';
+    }
+    // -------------------------------------------------------------------------
+    // Accessors
+    // -------------------------------------------------------------------------
+    /** Whether managed mode is active. */
+    get isManaged() {
+        return this._config.managed;
+    }
+    /** Number of registered tokens. */
+    get tokenCount() {
+        return this._tokens.size;
+    }
+    /** Number of registered policies. */
+    get policyCount() {
+        return this._policies.size;
+    }
+    /** Get a registered policy by id, or undefined if not found. */
+    getPolicy(id) {
+        return this._policies.get(id);
+    }
+    /** Get registered token metadata by id (without the secret value). */
+    getTokenMetadata(id) {
+        return this._tokens.get(id);
+    }
+}

package/dist/platform/security/user-auth.d.ts

@@ -0,0 +1,63 @@
+export interface AuthUser {
+    username: string;
+    passwordHash: string;
+    roles?: string[];
+}
+export interface AuthSession {
+    token: string;
+    username: string;
+    expiresAt: number;
+}
+interface UserAuthConfig {
+    sessionTtlMs?: number;
+    users?: AuthUser[];
+    bootstrapFilePath: string;
+    bootstrapCredentialPath: string;
+}
+export interface AuthUserRecord {
+    readonly username: string;
+    readonly roles: readonly string[];
+}
+export interface AuthSessionRecord {
+    readonly token: string;
+    readonly username: string;
+    readonly expiresAt: number;
+}
+export interface LocalAuthSnapshot {
+    readonly userStorePath: string;
+    readonly bootstrapCredentialPath: string;
+    readonly persisted: boolean;
+    readonly bootstrapCredentialPresent: boolean;
+    readonly userCount: number;
+    readonly sessionCount: number;
+    readonly users: readonly AuthUserRecord[];
+    readonly sessions: readonly AuthSessionRecord[];
+}
+export declare class UserAuthManager {
+    private users;
+    private sessions;
+    private sessionTtlMs;
+    private readonly userStorePath;
+    private readonly bootstrapCredentialPath;
+    private readonly persistUsers;
+    constructor(config: UserAuthConfig);
+    static hashPassword(password: string): string;
+    authenticate(username: string, password: string): AuthUser | null;
+    getUser(username: string): AuthUserRecord | null;
+    createSession(username: string): AuthSession;
+    validateSession(token: string): AuthSession | null;
+    revokeSession(token: string): boolean;
+    revokeSessionsForUser(username: string): number;
+    listUsers(): AuthUserRecord[];
+    listSessions(): AuthSessionRecord[];
+    addUser(username: string, password: string, roles?: readonly string[]): AuthUserRecord;
+    deleteUser(username: string): boolean;
+    rotatePassword(username: string, nextPassword: string): void;
+    inspect(): LocalAuthSnapshot;
+    clearBootstrapCredentialFile(): boolean;
+    getBootstrapCredentialPath(): string;
+    private pruneExpiredSessions;
+    private persist;
+}
+export {};
+//# sourceMappingURL=user-auth.d.ts.map

package/dist/platform/security/user-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-auth.d.ts","sourceRoot":"","sources":["../../../src/platform/security/user-auth.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,cAAc;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAUD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,0BAA0B,EAAE,OAAO,CAAC;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACjD;AA6FD,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAS;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;gBAE3B,MAAM,EAAE,cAAc;IAclC,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAI7C,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAMjE,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAShD,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW;IAY5C,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAUlD,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIrC,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAW/C,SAAS,IAAI,cAAc,EAAE;IAS7B,YAAY,IAAI,iBAAiB,EAAE;IAOnC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,GAAE,SAAS,MAAM,EAAc,GAAG,cAAc;IAejG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAarC,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;IAgB5D,OAAO,IAAI,iBAAiB;IAc5B,4BAA4B,IAAI,OAAO;IAMvC,0BAA0B,IAAI,MAAM;IAIpC,OAAO,CAAC,oBAAoB;IAS5B,OAAO,CAAC,OAAO;CAIhB"}

package/dist/platform/security/user-auth.js

@@ -0,0 +1,257 @@
+import { randomBytes, scryptSync, timingSafeEqual } from 'crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const DEFAULT_SESSION_TTL_MS = 3_600_000;
+const SCRYPT_KEY_LENGTH = 64;
+function toBase64(value) {
+    return value.toString('base64');
+}
+function hashPassword(password, salt) {
+    const actualSalt = salt ?? randomBytes(16);
+    const derived = scryptSync(password, actualSalt, SCRYPT_KEY_LENGTH);
+    return `${toBase64(actualSalt)}:${toBase64(derived)}`;
+}
+/**
+ * Generate a cryptographically random one-time password.
+ * Called once on first boot when no users are configured.
+ */
+function generateInitialPassword() {
+    return randomBytes(16).toString('hex');
+}
+function verifyPassword(password, passwordHash) {
+    const [saltEncoded, hashEncoded] = passwordHash.split(':');
+    if (!saltEncoded || !hashEncoded)
+        return false;
+    const salt = Buffer.from(saltEncoded, 'base64');
+    const expected = Buffer.from(hashEncoded, 'base64');
+    const actual = scryptSync(password, salt, SCRYPT_KEY_LENGTH);
+    if (actual.length !== expected.length)
+        return false;
+    return timingSafeEqual(actual, expected);
+}
+function readBootstrapUsers(filePath) {
+    try {
+        if (!existsSync(filePath))
+            return null;
+        const raw = readFileSync(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== 1 || !Array.isArray(parsed.users))
+            return null;
+        const users = parsed.users.filter((user) => Boolean(user)
+            && typeof user.username === 'string'
+            && typeof user.passwordHash === 'string'
+            && (user.roles === undefined || Array.isArray(user.roles)));
+        return users.length > 0 ? users : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeBootstrapUsers(filePath, users) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    const payload = { version: 1, users };
+    writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
+}
+function writeBootstrapCredentialFile(filePath, username, password) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, [
+        'GoodVibes bootstrap auth',
+        `username=${username}`,
+        `password=${password}`,
+        'purpose=Use these credentials only for local daemon/http listener /login routes when those surfaces are enabled.',
+        'note=Normal TUI usage does not require these credentials.',
+    ].join('\n') + '\n', 'utf-8');
+    try {
+        chmodSync(filePath, 0o600);
+    }
+    catch {
+        // best-effort only
+    }
+}
+function loadOrBootstrapUsers(filePath, credentialPath) {
+    const existing = readBootstrapUsers(filePath);
+    if (existing)
+        return existing;
+    const initialPassword = generateInitialPassword();
+    const username = 'admin';
+    const users = [
+        {
+            username,
+            passwordHash: hashPassword(initialPassword),
+            roles: ['admin'],
+        },
+    ];
+    writeBootstrapUsers(filePath, users);
+    writeBootstrapCredentialFile(credentialPath, username, initialPassword);
+    return users;
+}
+export class UserAuthManager {
+    users = new Map();
+    sessions = new Map();
+    sessionTtlMs;
+    userStorePath;
+    bootstrapCredentialPath;
+    persistUsers;
+    constructor(config) {
+        if (!config.bootstrapFilePath)
+            throw new Error('UserAuthManager requires an explicit bootstrapFilePath.');
+        if (!config.bootstrapCredentialPath)
+            throw new Error('UserAuthManager requires an explicit bootstrapCredentialPath.');
+        this.sessionTtlMs = config.sessionTtlMs ?? DEFAULT_SESSION_TTL_MS;
+        this.userStorePath = config.bootstrapFilePath;
+        this.bootstrapCredentialPath = config.bootstrapCredentialPath;
+        this.persistUsers = config.users === undefined;
+        const seedUsers = config.users ?? loadOrBootstrapUsers(this.userStorePath, this.bootstrapCredentialPath);
+        for (const user of seedUsers) {
+            this.users.set(user.username, user);
+        }
+    }
+    static hashPassword(password) {
+        return hashPassword(password);
+    }
+    authenticate(username, password) {
+        const user = this.users.get(username);
+        if (!user)
+            return null;
+        return verifyPassword(password, user.passwordHash) ? user : null;
+    }
+    getUser(username) {
+        const user = this.users.get(username);
+        if (!user)
+            return null;
+        return {
+            username: user.username,
+            roles: Object.freeze([...(user.roles ?? [])]),
+        };
+    }
+    createSession(username) {
+        this.pruneExpiredSessions();
+        const token = randomBytes(32).toString('hex');
+        const session = {
+            token,
+            username,
+            expiresAt: Date.now() + this.sessionTtlMs,
+        };
+        this.sessions.set(token, session);
+        return session;
+    }
+    validateSession(token) {
+        const session = this.sessions.get(token);
+        if (!session)
+            return null;
+        if (Date.now() > session.expiresAt) {
+            this.sessions.delete(token);
+            return null;
+        }
+        return session;
+    }
+    revokeSession(token) {
+        return this.sessions.delete(token);
+    }
+    revokeSessionsForUser(username) {
+        let removed = 0;
+        for (const [token, session] of this.sessions.entries()) {
+            if (session.username === username) {
+                this.sessions.delete(token);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    listUsers() {
+        return [...this.users.values()]
+            .map((user) => ({
+            username: user.username,
+            roles: Object.freeze([...(user.roles ?? [])]),
+        }))
+            .sort((a, b) => a.username.localeCompare(b.username));
+    }
+    listSessions() {
+        this.pruneExpiredSessions();
+        return [...this.sessions.values()]
+            .map((session) => ({ ...session }))
+            .sort((a, b) => a.username.localeCompare(b.username) || a.expiresAt - b.expiresAt);
+    }
+    addUser(username, password, roles = ['admin']) {
+        const normalized = username.trim();
+        if (!normalized)
+            throw new Error('Username is required.');
+        if (this.users.has(normalized))
+            throw new Error(`User already exists: ${normalized}`);
+        if (!password || password.length < 8)
+            throw new Error('Password must be at least 8 characters.');
+        const user = {
+            username: normalized,
+            passwordHash: hashPassword(password),
+            roles: [...new Set(roles.filter(Boolean))],
+        };
+        this.users.set(normalized, user);
+        this.persist();
+        return { username: user.username, roles: Object.freeze([...(user.roles ?? [])]) };
+    }
+    deleteUser(username) {
+        const normalized = username.trim();
+        const existing = this.users.get(normalized);
+        if (!existing)
+            return false;
+        if (this.users.size <= 1) {
+            throw new Error('Cannot delete the last local auth user.');
+        }
+        this.users.delete(normalized);
+        this.revokeSessionsForUser(normalized);
+        this.persist();
+        return true;
+    }
+    rotatePassword(username, nextPassword) {
+        const normalized = username.trim();
+        const existing = this.users.get(normalized);
+        if (!existing)
+            throw new Error(`Unknown local auth user: ${normalized}`);
+        if (!nextPassword || nextPassword.length < 8)
+            throw new Error('Password must be at least 8 characters.');
+        this.users.set(normalized, {
+            ...existing,
+            passwordHash: hashPassword(nextPassword),
+        });
+        this.revokeSessionsForUser(normalized);
+        this.persist();
+        if (normalized === 'admin') {
+            writeBootstrapCredentialFile(this.bootstrapCredentialPath, normalized, nextPassword);
+        }
+    }
+    inspect() {
+        this.pruneExpiredSessions();
+        return Object.freeze({
+            userStorePath: this.userStorePath,
+            bootstrapCredentialPath: this.bootstrapCredentialPath,
+            persisted: this.persistUsers,
+            bootstrapCredentialPresent: existsSync(this.bootstrapCredentialPath),
+            userCount: this.users.size,
+            sessionCount: this.sessions.size,
+            users: Object.freeze(this.listUsers()),
+            sessions: Object.freeze(this.listSessions()),
+        });
+    }
+    clearBootstrapCredentialFile() {
+        if (!existsSync(this.bootstrapCredentialPath))
+            return false;
+        rmSync(this.bootstrapCredentialPath, { force: true });
+        return true;
+    }
+    getBootstrapCredentialPath() {
+        return this.bootstrapCredentialPath;
+    }
+    pruneExpiredSessions() {
+        const now = Date.now();
+        for (const [token, session] of this.sessions.entries()) {
+            if (session.expiresAt <= now) {
+                this.sessions.delete(token);
+            }
+        }
+    }
+    persist() {
+        if (!this.persistUsers)
+            return;
+        writeBootstrapUsers(this.userStorePath, [...this.users.values()]);
+    }
+}

package/dist/platform/sessions/change-tracker.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Tracks files written or edited during the current runtime session.
+ *
+ * Ownership is explicit: the runtime creates one tracker and shares it with
+ * write/edit tools plus diff-oriented command surfaces that need to inspect it.
+ */
+export declare class SessionChangeTracker {
+    private readonly changed;
+    recordChange(filePath: string): void;
+    getChangedFiles(): string[];
+    clear(): void;
+    count(): number;
+}
+//# sourceMappingURL=change-tracker.d.ts.map

package/dist/platform/sessions/change-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-tracker.d.ts","sourceRoot":"","sources":["../../../src/platform/sessions/change-tracker.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAE7C,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIpC,eAAe,IAAI,MAAM,EAAE;IAI3B,KAAK,IAAI,IAAI;IAIb,KAAK,IAAI,MAAM;CAGhB"}

package/dist/platform/sessions/change-tracker.js

@@ -0,0 +1,24 @@
+// ---------------------------------------------------------------------------
+// SessionChangeTracker — tracks files written/edited during the current session
+// ---------------------------------------------------------------------------
+/**
+ * Tracks files written or edited during the current runtime session.
+ *
+ * Ownership is explicit: the runtime creates one tracker and shares it with
+ * write/edit tools plus diff-oriented command surfaces that need to inspect it.
+ */
+export class SessionChangeTracker {
+    changed = new Set();
+    recordChange(filePath) {
+        this.changed.add(filePath);
+    }
+    getChangedFiles() {
+        return Array.from(this.changed);
+    }
+    clear() {
+        this.changed.clear();
+    }
+    count() {
+        return this.changed.size;
+    }
+}