@docstack/client 0.0.4 → 0.0.5

package/lib/core/job-engine/index.js

@@ -0,0 +1,220 @@
+/**
+ * Calculates a SHA-256 hash of the given content.
+ * Used to verify job content integrity.
+ * @param content - The string content to hash
+ * @returns The hex-encoded hash string
+ */
+const calculateHash = async (content) => {
+    const getCrypto = () => globalThis.crypto;
+    const crypto = getCrypto();
+    const encoder = new TextEncoder();
+    const data = encoder.encode(content);
+    const buffer = await crypto.subtle.digest('SHA-256', data);
+    return Array.from(new Uint8Array(buffer)).map(b => b.toString(16).padStart(2, '0')).join('');
+};
+const now = () => Date.now();
+/**
+ * Represents an executable job that can perform background tasks.
+ *
+ * Jobs are stored as documents with executable content that is verified
+ * via hash before execution. They support singleton mode (only one instance
+ * can run at a time), metadata persistence, and run history tracking.
+ *
+ * @example
+ * ```typescript
+ * // Jobs are typically executed via JobEngine
+ * const run = await stack.jobEngine.executeJob('Job-auth', {
+ *     password: 'user-password',
+ *     salt: 'user-salt'
+ * });
+ * console.log('Job result:', run.finalMetadata);
+ * ```
+ */
+export class Job {
+    constructor(model, stack) {
+        this.model = model;
+        this.stack = stack;
+    }
+    /**
+     * Creates a validated Job instance from a JobModel document.
+     * Verifies the content hash to ensure integrity.
+     *
+     * @param model - The JobModel document from the database
+     * @param stack - The parent ClientStack instance
+     * @returns A validated Job instance
+     * @throws Error if the content hash doesn't match
+     */
+    static async create(model, stack) {
+        const computed = await calculateHash(model.content);
+        if (computed !== model.hash) {
+            throw new Error(`Job content hash mismatch for ${model._id}`);
+        }
+        return new Job(model, stack);
+    }
+    /**
+     * Hydrates the job content into an executable function.
+     * The job content must define an `execute(stack, params, job)` function.
+     */
+    hydrate() {
+        return new Function("stack", "params", "job", `"use strict"; ${this.model.content}; return execute(stack, params, job);`);
+    }
+    async hasRunningInstance() {
+        var _a;
+        if (!this.model.isSingleton)
+            return false;
+        const existingRuns = await this.stack.db.find({
+            selector: {
+                "~class": "~JobRun",
+                jobId: this.model._id,
+                status: "RUNNING",
+            },
+            limit: 1,
+        });
+        return Boolean((_a = existingRuns === null || existingRuns === void 0 ? void 0 : existingRuns.docs) === null || _a === void 0 ? void 0 : _a.length);
+    }
+    buildRun(triggerType, runtimeArgs) {
+        const getCrypto = () => globalThis.crypto;
+        const crypto = getCrypto();
+        const id = `JobRun-${crypto.randomUUID ? crypto.randomUUID() :
+            Array.from(crypto.getRandomValues(new Uint8Array(16))).map(b => b.toString(16).padStart(2, '0')).join('')}`;
+        const base = {
+            _id: id,
+            "~class": "~JobRun",
+            jobId: this.model._id,
+            status: "PENDING",
+            triggerType,
+            startTime: now(),
+            runtimeArgs,
+            initialMetadata: this.model.metadata ? Object.assign({}, this.model.metadata) : undefined,
+        };
+        return base;
+    }
+    async persistRun(run) {
+        const existing = await this.stack.db.get(run._id).catch(() => null);
+        const doc = existing ? Object.assign(Object.assign({}, run), { _rev: existing._rev }) : run;
+        await this.stack.db.bulkDocs([doc]);
+        return doc;
+    }
+    async persistJobMetadata(metadata) {
+        if (!metadata)
+            return;
+        const current = await this.stack.db.get(this.model._id).catch(() => null);
+        const nextDoc = Object.assign(Object.assign({}, this.model), { _rev: current === null || current === void 0 ? void 0 : current._rev, metadata });
+        await this.stack.db.bulkDocs([nextDoc]);
+    }
+    /**
+     * Executes the job with optional runtime arguments.
+     *
+     * Creates a JobRun document to track execution, handles singleton logic,
+     * and persists any metadata updates from the job execution.
+     *
+     * @param runtimeArgs - Optional parameters to pass to the job
+     * @param triggerType - How the job was triggered ('manual', 'scheduled', etc.)
+     * @returns The completed JobRunModel with status and results
+     * @throws Error if the job is disabled or a singleton instance is already running
+     *
+     * @example
+     * ```typescript
+     * const run = await job.execute({ userId: 'user-123' }, 'manual');
+     * if (run.status === 'SUCCESS') {
+     *     console.log('Result:', run.finalMetadata);
+     * }
+     * ```
+     */
+    async execute(runtimeArgs, triggerType = "manual") {
+        let run = this.buildRun(triggerType, runtimeArgs);
+        run = await this.persistRun(run);
+        if (!this.model.isEnabled) {
+            run.status = "SKIPPED";
+            run.errorMessage = `Job ${this.model._id} is disabled`;
+            run.endTime = now();
+            run.durationMs = run.endTime - run.startTime;
+            await this.persistRun(run);
+            throw new Error(run.errorMessage);
+        }
+        if (await this.hasRunningInstance()) {
+            run.status = "SKIPPED";
+            run.errorMessage = `Job ${this.model._id} already has a running instance`;
+            run.endTime = now();
+            run.durationMs = run.endTime - run.startTime;
+            await this.persistRun(run);
+            throw new Error(run.errorMessage);
+        }
+        try {
+            run.status = "RUNNING";
+            run.startTime = now();
+            run = await this.persistRun(run);
+            const executor = this.hydrate();
+            const params = Object.assign(Object.assign({}, (this.model.defaultParams || {})), (runtimeArgs || {}));
+            const result = await executor(this.stack, params, this.model);
+            const finalMetadata = (result && result.metadata) || this.model.metadata;
+            if (finalMetadata) {
+                run.finalMetadata = finalMetadata;
+                this.model.metadata = finalMetadata;
+                await this.persistJobMetadata(finalMetadata);
+            }
+            run.status = "SUCCESS";
+            run.endTime = now();
+            run.durationMs = run.endTime - run.startTime;
+            return await this.persistRun(run);
+        }
+        catch (error) {
+            run.status = "FAILURE";
+            run.errorMessage = (error === null || error === void 0 ? void 0 : error.message) || String(error);
+            run.errorStack = error === null || error === void 0 ? void 0 : error.stack;
+            run.endTime = now();
+            run.durationMs = run.endTime - run.startTime;
+            return await this.persistRun(run);
+        }
+    }
+}
+/**
+ * Engine for executing background jobs in the DocStack system.
+ *
+ * The JobEngine provides a simple interface to execute jobs by their ID.
+ * Jobs are fetched from the database, validated, and executed with
+ * full run tracking and metadata persistence.
+ *
+ * @example
+ * ```typescript
+ * // Execute a job
+ * const run = await stack.jobEngine.executeJob('Job-process-data', {
+ *     batchSize: 100
+ * });
+ *
+ * console.log('Status:', run.status);
+ * console.log('Duration:', run.durationMs, 'ms');
+ * ```
+ */
+export class JobEngine {
+    /**
+     * Creates a new JobEngine instance.
+     * @param stack - The parent ClientStack instance
+     */
+    constructor(stack) {
+        this.stack = stack;
+    }
+    /**
+     * Executes a job by its document ID.
+     *
+     * @param jobId - The job document ID (e.g., 'Job-auth')
+     * @param runtimeArgs - Optional parameters to pass to the job
+     * @param triggerType - How the job was triggered (default: 'manual')
+     * @returns The completed JobRunModel with execution results
+     *
+     * @example
+     * ```typescript
+     * const authRun = await jobEngine.executeJob('Job-auth', {
+     *     password: 'secret',
+     *     salt: 'user-salt'
+     * });
+     * const derivedKey = authRun.finalMetadata?.derivedKey;
+     * ```
+     */
+    async executeJob(jobId, runtimeArgs, triggerType = "manual") {
+        const jobDoc = await this.stack.db.get(jobId);
+        const job = await Job.create(jobDoc, this.stack);
+        return job.execute(runtimeArgs, triggerType);
+    }
+}
+//# sourceMappingURL=index.js.map

package/lib/core/job-engine/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/job-engine/index.ts"],"names":[],"mappings":"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"}

package/lib/core/policy-engine/index.js

@@ -0,0 +1,232 @@
+/**
+ * Set of system classes that bypass policy evaluation.
+ * These classes are internal to DocStack and always accessible.
+ */
+const SYSTEM_CLASSES = new Set([
+    "~Policy",
+    "~Job",
+    "~JobRun",
+    "~AuthModule",
+    "~UserSession",
+    "class",
+    "domain"
+]);
+/**
+ * Engine for evaluating access control policies on documents.
+ *
+ * PolicyEngine implements role-based access control (RBAC) by evaluating
+ * policy rules against documents and user sessions. Policies can be:
+ * - Class-level (apply to all documents of a class)
+ * - User-specific (apply only to a specific user)
+ * - Group-specific (apply only to users in a specific group)
+ *
+ * Policy rules are JavaScript expressions that receive the document,
+ * session, and groupId as context and return a boolean.
+ *
+ * @example
+ * ```typescript
+ * // Policy engine is used automatically during document operations
+ * // Policies are defined as documents:
+ * await stack.createDoc(null, '~Policy', null, {
+ *     name: 'user-read-own',
+ *     targetClass: ['User'],
+ *     rule: 'return document.userId === session.userId;'
+ * });
+ * ```
+ */
+export class PolicyEngine {
+    /**
+     * Creates a new PolicyEngine instance.
+     * @param stack - The parent ClientStack instance
+     */
+    constructor(stack) {
+        this.stack = stack;
+    }
+    /**
+     * Gets the current authentication session proof.
+     * @returns The session proof, or undefined if not authenticated
+     */
+    getSessionProof() {
+        return this.stack.authSession;
+    }
+    /**
+     * Checks if a class should bypass policy evaluation.
+     * System classes (prefixed with ~) are always allowed.
+     *
+     * @param targetClass - The class name to check
+     * @returns `true` if the class should bypass policies
+     */
+    shouldBypass(targetClass) {
+        if (SYSTEM_CLASSES.has(targetClass))
+            return true;
+        const normalized = targetClass.startsWith("~") ? targetClass.slice(1) : `~${targetClass}`;
+        return SYSTEM_CLASSES.has(normalized);
+    }
+    async loadPolicies(targetClass, aliases = []) {
+        const identifiers = new Set([targetClass, ...aliases]);
+        const result = await this.stack.findDocuments({ "~class": "~Policy" });
+        return result.docs.filter((doc) => {
+            if (!Array.isArray(doc.targetClass))
+                return false;
+            return doc.targetClass.some((entry) => identifiers.has(entry));
+        });
+    }
+    getTargetIdentifiers(targetId, targetName) {
+        const identifiers = new Set();
+        const variants = [targetId, targetName];
+        for (const value of variants) {
+            identifiers.add(value);
+            if (value.startsWith("~")) {
+                identifiers.add(value.slice(1));
+            }
+            else {
+                identifiers.add(`~${value}`);
+            }
+        }
+        return Array.from(identifiers);
+    }
+    async resolveClassTarget(targetClass) {
+        var _a, _b;
+        const classModel = await this.stack.getClassModel(targetClass).catch(() => null);
+        return {
+            id: (_a = classModel === null || classModel === void 0 ? void 0 : classModel._id) !== null && _a !== void 0 ? _a : targetClass,
+            name: (_b = classModel === null || classModel === void 0 ? void 0 : classModel.name) !== null && _b !== void 0 ? _b : targetClass,
+        };
+    }
+    /**
+     * Evaluates a policy rule against a document and session.
+     * The rule is a JavaScript expression that returns a boolean.
+     *
+     * @param policy - The policy containing the rule
+     * @param document - The document being accessed
+     * @param session - The current auth session
+     * @returns Whether the rule permits access
+     */
+    async evaluateRule(policy, document, session) {
+        const executor = new Function("document", "session", "groupId", `"use strict"; ${policy.rule}`);
+        const result = executor(document || {}, session.session, session.session.groupId);
+        if (result instanceof Promise) {
+            return Boolean(await result);
+        }
+        return Boolean(result);
+    }
+    filterPoliciesForSession(policies, session) {
+        const sessionUserId = session.session.userId || session.session.username;
+        const sessionGroups = Array.isArray(session.session.groupId)
+            ? session.session.groupId
+            : session.session.groupId
+                ? [session.session.groupId]
+                : [];
+        return policies.filter((policy) => {
+            const matchesUser = !policy.userId || policy.userId === sessionUserId || policy.userId === session.session.username;
+            const matchesGroup = !policy.groupId || sessionGroups.includes(policy.groupId);
+            return matchesUser && matchesGroup;
+        });
+    }
+    async authorize(targetClass, operation, document) {
+        const { id: targetId, name: targetName } = await this.resolveClassTarget(targetClass);
+        const identifiers = this.getTargetIdentifiers(targetId, targetName);
+        if (this.shouldBypass(targetName)) {
+            return true;
+        }
+        const policies = await this.loadPolicies(targetId, identifiers);
+        if (policies.length === 0) {
+            return true;
+        }
+        const session = this.getSessionProof();
+        if (!session) {
+            throw new Error("Stack is not authenticated for policy evaluation");
+        }
+        const targetedPolicies = policies.filter((policy) => policy.userId || policy.groupId);
+        const basePolicies = policies.filter((policy) => !policy.userId && !policy.groupId);
+        const matchingPolicies = targetedPolicies.length > 0
+            ? this.filterPoliciesForSession(targetedPolicies, session)
+            : this.filterPoliciesForSession(basePolicies, session);
+        if (targetedPolicies.length > 0 && matchingPolicies.length === 0) {
+            throw new Error(`No matching policy allowed ${operation} on class '${targetClass}'`);
+        }
+        let allowed = false;
+        for (const policy of matchingPolicies) {
+            const result = await this.evaluateRule(policy, document, session);
+            if (result === false) {
+                throw new Error(`Policy '${policy._id}' denied ${operation} on class '${targetClass}'`);
+            }
+            if (result === true) {
+                allowed = true;
+            }
+        }
+        return allowed;
+    }
+    /**
+     * Ensures write access is allowed for a document of the given class.
+     * Throws an error if no policy permits the write operation.
+     *
+     * @param targetClass - The class of the document being written
+     * @param document - The document to write
+     * @throws Error if write is not permitted
+     *
+     * @example
+     * ```typescript
+     * // Called automatically during createDoc/updateCard operations
+     * await policyEngine.ensureWriteAllowed('Task', taskDocument);
+     * ```
+     */
+    async ensureWriteAllowed(targetClass, document) {
+        const allowed = await this.authorize(targetClass, "write", document);
+        if (!allowed) {
+            throw new Error(`No matching policy allowed write on class '${targetClass}'`);
+        }
+    }
+    /**
+     * Checks if a document is readable by the current user.
+     * Used to filter query results based on read policies.
+     *
+     * @param document - The document to check
+     * @returns `true` if the document can be read
+     * @throws Error if the stack is not authenticated
+     *
+     * @example
+     * ```typescript
+     * // Used internally during findDocuments
+     * const readable = await policyEngine.isReadableDocument(doc);
+     * if (readable) {
+     *     results.push(doc);
+     * }
+     * ```
+     */
+    async isReadableDocument(document) {
+        const targetClass = document === null || document === void 0 ? void 0 : document["~class"];
+        const { id: targetId, name: targetName } = await this.resolveClassTarget(targetClass);
+        if (!targetClass || this.shouldBypass(targetName)) {
+            return true;
+        }
+        const policies = await this.loadPolicies(targetId, this.getTargetIdentifiers(targetId, targetName));
+        if (policies.length === 0) {
+            return true;
+        }
+        const session = this.getSessionProof();
+        if (!session) {
+            throw new Error("Stack is not authenticated for policy evaluation");
+        }
+        const targetedPolicies = policies.filter((policy) => policy.userId || policy.groupId);
+        const basePolicies = policies.filter((policy) => !policy.userId && !policy.groupId);
+        const matchingPolicies = targetedPolicies.length > 0
+            ? this.filterPoliciesForSession(targetedPolicies, session)
+            : this.filterPoliciesForSession(basePolicies, session);
+        if (targetedPolicies.length > 0 && matchingPolicies.length === 0) {
+            return false;
+        }
+        let permitted = false;
+        for (const policy of matchingPolicies) {
+            const result = await this.evaluateRule(policy, document, session);
+            if (result === false) {
+                return false;
+            }
+            if (result === true) {
+                permitted = true;
+            }
+        }
+        return permitted;
+    }
+}
+//# sourceMappingURL=index.js.map

package/lib/core/policy-engine/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/policy-engine/index.ts"],"names":[],"mappings":"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"}