engineering-memory 0.1.0

package/runtime/dist/src/runtime/offline-outbox.js

@@ -0,0 +1,274 @@
+import { randomUUID } from 'node:crypto';
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { assertManagedPath, ensureManagedDirectory, readJson, removeFile, writeJson, } from '../utilities/files.js';
+import { sha256, stableStringify } from '../utilities/hash.js';
+const sensitiveKeyPattern = /(authorization|password|passcode|secret|token|cookie|email|phone|mobile|customer|account|user.?id|user.?name)/i;
+const emailPattern = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i;
+const phonePattern = /\+\d[\d ()-]{7,}\d/;
+const bearerPattern = /\bbearer\s+[a-z0-9._~-]+/i;
+const jwtPattern = /\beyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\b/;
+const privateKeyPattern = /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/;
+const credentialUrlPattern = /\b[a-z][a-z0-9+.-]*:\/\/[^\s/@:]+:[^\s/@]+@/i;
+const ipv4Pattern = /\b(?:\d{1,3}\.){3}\d{1,3}\b/;
+const personalHomePathPattern = /(?:^|[\s"'(])(?:[A-Z]:[\\/]+Users[\\/]+[^\\/\s"']+(?:[\\/]|(?=$|\s))|\/(?:Users|home)\/[^/\s"']+(?:\/|(?=$|\s)))/i;
+export class OfflineOutbox {
+    root;
+    queues = new Map();
+    constructor(stateRoot) {
+        this.root = join(stateRoot, 'outbox');
+    }
+    async enqueue(input) {
+        assertSafeToPersist(input.body);
+        if (input.journalRef) {
+            assertSafeToPersist(JSON.parse(JSON.stringify(input.journalRef)));
+        }
+        const idempotencyKey = input.idempotencyKey ?? randomUUID();
+        const id = sha256(`${input.operation}\n${idempotencyKey}`);
+        return await this.exclusive(id, async () => {
+            const path = this.pathFor(id);
+            const existing = await readJson(path, this.root);
+            if (existing) {
+                const expected = stableStringify({
+                    operation: input.operation,
+                    method: input.method,
+                    path: input.path,
+                    body: input.body,
+                    idempotencyKey,
+                    journalRef: input.journalRef ?? null,
+                });
+                const actual = stableStringify({
+                    operation: existing.operation,
+                    method: existing.method,
+                    path: existing.path,
+                    body: existing.body,
+                    idempotencyKey: existing.idempotencyKey,
+                    journalRef: existing.journalRef ?? null,
+                });
+                if (actual !== expected) {
+                    throw new Error('Outbox idempotency key was reused with different content');
+                }
+                return existing;
+            }
+            const entry = {
+                id,
+                operation: input.operation,
+                method: input.method,
+                path: input.path,
+                body: input.body,
+                idempotencyKey,
+                createdAt: new Date().toISOString(),
+                attempts: 0,
+                lastError: null,
+                ...(input.journalRef ? { journalRef: input.journalRef } : {}),
+            };
+            await writeJson(path, entry, this.root);
+            return entry;
+        });
+    }
+    async list() {
+        await ensureManagedDirectory(this.root, this.root);
+        const entries = await readdir(this.root, { withFileTypes: true });
+        const files = entries.filter((entry) => entry.name.endsWith('.json'));
+        for (const entry of files) {
+            if (!entry.isFile() || entry.isSymbolicLink()) {
+                throw new Error(`Unsafe offline outbox entry: ${entry.name}`);
+            }
+        }
+        const values = await Promise.all(files.map(async (entry) => {
+            const path = await assertManagedPath(this.root, join(this.root, entry.name), false);
+            return await readJson(path, this.root);
+        }));
+        return values.filter((entry) => entry !== null).sort(compareEntries);
+    }
+    async markAttempt(id, errorKind) {
+        await this.exclusive(id, async () => {
+            const path = this.pathFor(id);
+            const entry = await readJson(path, this.root);
+            if (!entry) {
+                return;
+            }
+            entry.attempts += 1;
+            entry.lastError = safeErrorKind(errorKind);
+            await writeJson(path, entry, this.root);
+        });
+    }
+    async get(id) {
+        return await this.exclusive(id, async () => {
+            return await readJson(this.pathFor(id), this.root);
+        });
+    }
+    async replaceBody(id, body) {
+        assertSafeToPersist(body);
+        return await this.exclusive(id, async () => {
+            const path = this.pathFor(id);
+            const entry = await readJson(path, this.root);
+            if (!entry) {
+                throw new Error('Offline outbox entry could not be found');
+            }
+            entry.body = body;
+            entry.attempts = 0;
+            entry.lastError = null;
+            await writeJson(path, entry, this.root);
+            return entry;
+        });
+    }
+    async acknowledge(id) {
+        await this.exclusive(id, async () => {
+            await removeFile(this.pathFor(id), this.root);
+        });
+    }
+    pathFor(id) {
+        if (!/^[0-9a-f]{64}$/.test(id)) {
+            throw new Error('Invalid offline outbox identifier');
+        }
+        return join(this.root, `${id}.json`);
+    }
+    async exclusive(key, action) {
+        const previous = this.queues.get(key) ?? Promise.resolve();
+        let release = () => undefined;
+        const current = new Promise((resolvePromise) => {
+            release = resolvePromise;
+        });
+        const tail = previous.then(() => current);
+        this.queues.set(key, tail);
+        await previous;
+        try {
+            return await action();
+        }
+        finally {
+            release();
+            if (this.queues.get(key) === tail) {
+                this.queues.delete(key);
+            }
+        }
+    }
+}
+export function assertSafeToPersist(value, key = '') {
+    if (key && sensitiveKeyPattern.test(key)) {
+        throw new Error(`Sensitive field cannot be persisted: ${key}`);
+    }
+    if (typeof value === 'string') {
+        if (emailPattern.test(value) ||
+            phonePattern.test(value) ||
+            bearerPattern.test(value) ||
+            jwtPattern.test(value) ||
+            privateKeyPattern.test(value) ||
+            credentialUrlPattern.test(value) ||
+            ipv4Pattern.test(value) ||
+            personalHomePathPattern.test(value)) {
+            throw new Error('PII or credentials cannot be persisted');
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item) => assertSafeToPersist(item, key));
+        return;
+    }
+    if (value !== null && typeof value === 'object') {
+        Object.entries(value).forEach(([childKey, item]) => assertSafeToPersist(item, childKey));
+    }
+}
+export function normalizeRepositoryPaths(value, repoRoot) {
+    const root = trimTrailingSeparators(repoRoot);
+    if (!root) {
+        throw new Error('Repository root is required for persistent payload normalization');
+    }
+    return normalizeRepositoryPathValue(value, root);
+}
+export function isSafeToPersist(value) {
+    try {
+        assertSafeToPersist(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function redactForCache(value) {
+    try {
+        return redactValue(value);
+    }
+    catch {
+        return null;
+    }
+}
+function redactValue(value) {
+    if (typeof value === 'string') {
+        assertSafeToPersist(value);
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => redactValue(entry));
+    }
+    if (value !== null && typeof value === 'object') {
+        const result = {};
+        for (const [key, entry] of Object.entries(value)) {
+            if (sensitiveKeyPattern.test(key)) {
+                continue;
+            }
+            result[key] = redactValue(entry);
+        }
+        return result;
+    }
+    return value;
+}
+function normalizeRepositoryPathValue(value, repoRoot) {
+    if (typeof value === 'string') {
+        const variants = [
+            ...new Set([repoRoot, repoRoot.replace(/\\/g, '/'), repoRoot.replace(/\//g, '\\')]),
+        ]
+            .filter(Boolean)
+            .sort((left, right) => right.length - left.length);
+        let normalized = value;
+        for (const variant of variants) {
+            const flags = /^[A-Za-z]:[\\/]/.test(variant) ? 'gi' : 'g';
+            normalized = normalized.replace(new RegExp(`${escapeRegExp(variant)}(?=$|[\\\\/\\s"'])`, flags), '${REPO_ROOT}');
+        }
+        return normalized.replace(/\$\{REPO_ROOT\}(?:[\\/][^\s"'`,;)]*)?/g, (path) => path.replace(/\\/g, '/'));
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => normalizeRepositoryPathValue(entry, repoRoot));
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+            key,
+            normalizeRepositoryPathValue(entry, repoRoot),
+        ]));
+    }
+    return value;
+}
+function trimTrailingSeparators(value) {
+    const trimmed = value.trim();
+    if (/^[A-Za-z]:[\\/]$/.test(trimmed) || trimmed === '/') {
+        return trimmed;
+    }
+    return trimmed.replace(/[\\/]+$/, '');
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function safeErrorKind(value) {
+    const normalized = value
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, '_')
+        .slice(0, 80);
+    return normalized || 'unknown_error';
+}
+function compareEntries(left, right) {
+    const leftBody = asObject(left.body);
+    const rightBody = asObject(right.body);
+    if (leftBody?.taskId === rightBody?.taskId &&
+        typeof leftBody?.expectedTaskVersion === 'number' &&
+        typeof rightBody?.expectedTaskVersion === 'number' &&
+        leftBody.expectedTaskVersion !== rightBody.expectedTaskVersion) {
+        return leftBody.expectedTaskVersion - rightBody.expectedTaskVersion;
+    }
+    return left.createdAt === right.createdAt
+        ? left.id.localeCompare(right.id)
+        : left.createdAt.localeCompare(right.createdAt);
+}
+function asObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+//# sourceMappingURL=offline-outbox.js.map

package/runtime/dist/src/runtime/principal-state.js

@@ -0,0 +1,97 @@
+import { join } from 'node:path';
+import { readJson, removeFile, writeJson } from '../utilities/files.js';
+import { sha256 } from '../utilities/hash.js';
+export class PrincipalStateGuard {
+    stateRoot;
+    credentials;
+    cache;
+    outbox;
+    activeContexts;
+    gate;
+    ownerPath;
+    queue = Promise.resolve();
+    constructor(stateRoot, credentials, cache, outbox, activeContexts, gate) {
+        this.stateRoot = stateRoot;
+        this.credentials = credentials;
+        this.cache = cache;
+        this.outbox = outbox;
+        this.activeContexts = activeContexts;
+        this.gate = gate;
+        this.ownerPath = join(stateRoot, 'principal-owner.json');
+    }
+    async ensure() {
+        await this.exclusive(async () => {
+            const accessToken = await this.credentials.get('access-token');
+            if (!accessToken) {
+                return;
+            }
+            const principalHash = principalFingerprint(accessToken);
+            const current = await readJson(this.ownerPath, this.stateRoot);
+            if (current?.principalHash === principalHash) {
+                return;
+            }
+            if ((await this.outbox.list()).length > 0) {
+                throw new Error('Pending offline work belongs to a different authenticated principal');
+            }
+            await this.clearPrincipalState();
+            await writeJson(this.ownerPath, {
+                schemaVersion: 1,
+                principalHash,
+                boundAt: new Date().toISOString(),
+            }, this.stateRoot);
+        });
+    }
+    async clearAfterLogout() {
+        await this.exclusive(async () => {
+            if ((await this.outbox.list()).length > 0) {
+                throw new Error('Pending offline work must be resolved before logout');
+            }
+            await this.clearPrincipalState();
+            await this.credentials.clear();
+        });
+    }
+    async clearPrincipalState() {
+        await this.cache.clear();
+        await this.activeContexts.clear();
+        await this.gate.clear();
+        await removeFile(this.ownerPath, this.stateRoot);
+    }
+    async exclusive(action) {
+        const previous = this.queue;
+        let release = () => undefined;
+        const current = new Promise((resolvePromise) => {
+            release = resolvePromise;
+        });
+        this.queue = previous.then(() => current);
+        await previous;
+        try {
+            await action();
+        }
+        finally {
+            release();
+        }
+    }
+}
+export function principalFingerprint(accessToken) {
+    const parts = accessToken.split('.');
+    const encodedPayload = parts[1];
+    if (parts.length !== 3 || !encodedPayload) {
+        throw new Error('Access credential cannot establish a local principal namespace');
+    }
+    let payload;
+    try {
+        payload = JSON.parse(Buffer.from(encodedPayload, 'base64url').toString('utf8'));
+    }
+    catch {
+        throw new Error('Access credential cannot establish a local principal namespace');
+    }
+    if (!payload || typeof payload !== 'object') {
+        throw new Error('Access credential cannot establish a local principal namespace');
+    }
+    const subject = payload.sub;
+    if (typeof subject !== 'string') {
+        throw new Error('Access credential cannot establish a local principal namespace');
+    }
+    return sha256(subject);
+}
+//# sourceMappingURL=principal-state.js.map

package/runtime/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/runtime/dist/src/utilities/files.js

@@ -0,0 +1,189 @@
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, open, readFile, realpath, rename, rm } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+export async function atomicWrite(path, content, managedRoot) {
+    const root = managedRoot ?? dirname(path);
+    await ensureManagedDirectory(root, dirname(path));
+    const target = await assertManagedPath(root, path, true);
+    await assertWritableTarget(target);
+    const temporaryPath = `${target}.${randomUUID()}.tmp`;
+    const handle = await open(temporaryPath, 'wx', 0o600);
+    let renamed = false;
+    try {
+        try {
+            await handle.writeFile(content);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporaryPath, target);
+        renamed = true;
+        await syncDirectory(dirname(target));
+    }
+    finally {
+        if (!renamed) {
+            await rm(temporaryPath, { force: true });
+        }
+    }
+}
+export async function readJson(path, managedRoot) {
+    try {
+        const target = managedRoot ? await assertManagedPath(managedRoot, path, false) : path;
+        return JSON.parse(await readFile(target, 'utf8'));
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function writeJson(path, value, managedRoot) {
+    await atomicWrite(path, `${JSON.stringify(value, null, 2)}\n`, managedRoot);
+}
+export async function pathExists(path, managedRoot) {
+    try {
+        const target = managedRoot ? await assertManagedPath(managedRoot, path, false) : path;
+        await lstat(target);
+        return true;
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+export async function removeFile(path, managedRoot) {
+    const target = managedRoot ? await assertManagedPath(managedRoot, path, true) : path;
+    await rm(target, { force: true });
+}
+export function ensureWithinRoot(root, target) {
+    const resolvedRoot = resolve(root);
+    const resolvedTarget = resolve(target);
+    const pathFromRoot = relative(resolvedRoot, resolvedTarget);
+    if (pathFromRoot.startsWith('..') || isAbsolute(pathFromRoot)) {
+        throw new Error(`Path is outside the managed root: ${resolvedTarget}`);
+    }
+    return resolvedTarget;
+}
+export async function canonicalPath(path) {
+    try {
+        return await realpath(path);
+    }
+    catch (error) {
+        if (!isNodeError(error) || error.code !== 'ENOENT') {
+            throw error;
+        }
+        return resolve(path);
+    }
+}
+export async function assertManagedPath(root, target, allowMissingTarget) {
+    const resolvedRoot = resolve(root);
+    const resolvedTarget = ensureWithinRoot(resolvedRoot, target);
+    const rootStat = await lstat(resolvedRoot);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+        throw new Error(`Managed root must be a real directory: ${resolvedRoot}`);
+    }
+    const canonicalRoot = await realpath(resolvedRoot);
+    let current = resolvedRoot;
+    const segments = relative(resolvedRoot, resolvedTarget).split(sep).filter(Boolean);
+    for (let index = 0; index < segments.length; index += 1) {
+        current = join(current, segments[index]);
+        let currentStat;
+        try {
+            currentStat = await lstat(current);
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === 'ENOENT' && allowMissingTarget) {
+                return resolvedTarget;
+            }
+            throw error;
+        }
+        if (currentStat.isSymbolicLink()) {
+            throw new Error(`Symbolic links are not allowed in managed paths: ${current}`);
+        }
+        if (index < segments.length - 1 && !currentStat.isDirectory()) {
+            throw new Error(`Managed path parent is not a directory: ${current}`);
+        }
+        const canonicalCurrent = await realpath(current);
+        const fromRoot = relative(canonicalRoot, canonicalCurrent);
+        if (fromRoot.startsWith('..') || isAbsolute(fromRoot)) {
+            throw new Error(`Managed path escapes its canonical root: ${current}`);
+        }
+    }
+    return resolvedTarget;
+}
+export async function ensureManagedDirectory(root, directory) {
+    const resolvedRoot = resolve(root);
+    const resolvedDirectory = ensureWithinRoot(resolvedRoot, directory);
+    await mkdir(resolvedRoot, { recursive: true });
+    const rootStat = await lstat(resolvedRoot);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+        throw new Error(`Managed root must be a real directory: ${resolvedRoot}`);
+    }
+    let current = resolvedRoot;
+    for (const segment of relative(resolvedRoot, resolvedDirectory).split(sep).filter(Boolean)) {
+        current = join(current, segment);
+        try {
+            const currentStat = await lstat(current);
+            if (!currentStat.isDirectory() || currentStat.isSymbolicLink()) {
+                throw new Error(`Managed directory contains an unsafe path: ${current}`);
+            }
+        }
+        catch (error) {
+            if (!isNodeError(error) || error.code !== 'ENOENT') {
+                throw error;
+            }
+            await mkdir(current, { mode: 0o700 });
+            const created = await lstat(current);
+            if (!created.isDirectory() || created.isSymbolicLink()) {
+                throw new Error(`Managed directory could not be created safely: ${current}`);
+            }
+        }
+    }
+}
+async function assertWritableTarget(path) {
+    try {
+        const targetStat = await lstat(path);
+        if (!targetStat.isFile() || targetStat.isSymbolicLink()) {
+            throw new Error(`Managed file target is unsafe: ${path}`);
+        }
+    }
+    catch (error) {
+        if (!isNodeError(error) || error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+}
+async function syncDirectory(path) {
+    let handle;
+    try {
+        handle = await open(path, 'r');
+        await handle.sync();
+    }
+    catch (error) {
+        if (!isNodeError(error) ||
+            !['EINVAL', 'ENOTSUP', 'EISDIR', 'EPERM', 'EBADF'].includes(error.code ?? '')) {
+            throw error;
+        }
+    }
+    finally {
+        await handle?.close();
+    }
+}
+export function safeSegment(value) {
+    const segment = value
+        .trim()
+        .replace(/[^a-zA-Z0-9._-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (!segment || segment === '.' || segment === '..') {
+        throw new Error('A safe filesystem segment could not be produced');
+    }
+    return segment.slice(0, 120);
+}
+export function isNodeError(error) {
+    return error instanceof Error && 'code' in error;
+}
+//# sourceMappingURL=files.js.map

package/runtime/dist/src/utilities/hash.js

@@ -0,0 +1,19 @@
+import { createHash } from 'node:crypto';
+export function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+export function stableStringify(value) {
+    return JSON.stringify(sortValue(value));
+}
+function sortValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortValue);
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => [key, sortValue(item)]));
+    }
+    return value;
+}
+//# sourceMappingURL=hash.js.map

package/runtime/dist/src/utilities/process.js

@@ -0,0 +1,32 @@
+import { spawn } from 'node:child_process';
+export class NativeCommandRunner {
+    async run(command, args, options = {}) {
+        return await new Promise((resolvePromise, reject) => {
+            const child = spawn(command, args, {
+                cwd: options.cwd,
+                shell: false,
+                windowsHide: true,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            let stdout = '';
+            let stderr = '';
+            child.stdout.setEncoding('utf8');
+            child.stderr.setEncoding('utf8');
+            child.stdout.on('data', (chunk) => {
+                stdout += chunk;
+            });
+            child.stderr.on('data', (chunk) => {
+                stderr += chunk;
+            });
+            child.once('error', reject);
+            child.once('close', (exitCode) => {
+                resolvePromise({ stdout, stderr, exitCode: exitCode ?? -1 });
+            });
+            if (options.input !== undefined) {
+                child.stdin.write(options.input);
+            }
+            child.stdin.end();
+        });
+    }
+}
+//# sourceMappingURL=process.js.map