@xyne/workflow-sdk 3.2.15 → 3.2.17

package/dist/runtime/workflow-runtime.js

@@ -13,6 +13,7 @@
  */
 import { ConfigValidator } from '../engine/config-validator.js';
 import { validateTriggerPayload } from '../common/validate-payload.js';
+import { AccessDeniedError, ResourceNotFoundError } from '../authz/default.js';
 import { EventTrigger } from '../triggers/event-trigger.js';
 import { WebhookTrigger } from '../triggers/webhook-trigger.js';
 import { CronTrigger } from '../triggers/cron-trigger.js';
@@ -61,6 +62,8 @@ function findStepConfigById(config, id) {
 // ─── WorkflowRuntime ───
 export class WorkflowRuntime {
     persistence;
+    /** Authorization port — host-supplied, always. See {@link RuntimeOptions.authorizer}. */
+    authorizer;
     queue;
     scheduler;
     services;
@@ -83,6 +86,10 @@ export class WorkflowRuntime {
     aiBuilder;
     constructor(opts) {
         this.persistence = opts.persistence;
+        // No fallback and no cast: the authorizer and the adapter must agree on
+        // `TFilter`, and the only way to guarantee that is to make the host supply
+        // both. See {@link RuntimeOptions.authorizer}.
+        this.authorizer = opts.authorizer;
         this.queue = opts.queue;
         this.scheduler = opts.scheduler;
         this.services = opts.services;
@@ -99,6 +106,86 @@ export class WorkflowRuntime {
         this.defaultCronTimezone = config.defaultCronTimezone ?? 'Asia/Kolkata';
         this.aiBuilder = config.aiBuilder;
     }
+    // ─── Authorization primitives ───
+    //
+    // Every caller-facing operation goes through exactly one of these. There is no
+    // bypass: system-initiated work lives on `this.system` and never reaches here.
+    /**
+     * Guard an action on a ref the caller already has. Throws
+     * {@link AccessDeniedError} if denied; returns the full action set so callers
+     * can reuse it as the resource's `permittedActions` for the UI.
+     */
+    async require(ctx, action, ref) {
+        const perms = await this.authorizer.permissions(ctx, ref);
+        if (!perms.includes(action))
+            throw new AccessDeniedError(action, ref);
+        return perms;
+    }
+    /**
+     * Fetch a workflow AND decide on it, atomically. This is the ONLY way a
+     * caller-facing op obtains a workflow — so "forgot to authorize" is not
+     * expressible, rather than merely discouraged.
+     */
+    async authorizedWorkflow(ctx, id, action) {
+        const record = await this.persistence.getWorkflow(id);
+        if (!record)
+            throw new ResourceNotFoundError('Workflow', id);
+        const permittedActions = await this.require(ctx, action, this.workflowRef(record));
+        return { record, permittedActions };
+    }
+    /** Fetch a folder AND decide on it, atomically. See {@link authorizedWorkflow}. */
+    async authorizedFolder(ctx, id, action) {
+        const record = await this.persistence.getFolder(id);
+        if (!record)
+            throw new ResourceNotFoundError('Folder', id);
+        const permittedActions = await this.require(ctx, action, this.folderRef(record));
+        return { record, permittedActions };
+    }
+    /** The caller's list predicate for `type`, handed to the adapter verbatim. */
+    filterFor(ctx, type) {
+        return this.authorizer.visibleFilter(ctx, type);
+    }
+    /**
+     * The container a new resource would land in: the named folder, or `root`
+     * when there is no parent. Create is guarded against this — the container is
+     * the only thing that exists to ask about before the resource does.
+     */
+    async containerRef(parentId) {
+        if (!parentId)
+            return { type: 'root' };
+        const folder = await this.persistence.getFolder(parentId);
+        if (!folder)
+            throw new ResourceNotFoundError('Folder', parentId);
+        return this.folderRef(folder);
+    }
+    /** Build a workflow ref — the record already carries typed `attributes`. */
+    workflowRef(wf) {
+        return { type: 'workflow', id: wf.id, record: wf };
+    }
+    /** Build a folder ref from the stored record — carries the folder's typed `attributes`. */
+    folderRef(folder) {
+        return { type: 'folder', id: folder.id, record: folder };
+    }
+    executionRef(exec) {
+        return { type: 'execution', id: exec.id, record: exec };
+    }
+    credentialRef(cred) {
+        return { type: 'credential', id: cred.id, record: cred };
+    }
+    /**
+     * Populate each list row's `permittedActions` in one authorizer round-trip
+     * (via `permissionsBatch`, falling back to per-item) so the UI gates inline
+     * row actions synchronously — no N+1 fetch, no optimistic buttons.
+     */
+    async project(ctx, records, toRef) {
+        if (records.length === 0)
+            return records;
+        const refs = records.map(toRef);
+        const perms = this.authorizer.permissionsBatch
+            ? await this.authorizer.permissionsBatch(ctx, refs)
+            : await Promise.all(refs.map((ref) => this.authorizer.permissions(ctx, ref)));
+        return records.map((r, i) => ({ ...r, permittedActions: perms[i] }));
+    }
     // ─── Validation ───
     /**
      * Validate a workflow config before saving.
@@ -119,11 +206,18 @@ export class WorkflowRuntime {
      * - CronTrigger: registers with the scheduler
      * - EventTrigger / ManualTrigger: no activation needed (status change only)
      */
-    async activateWorkflow(workflowId) {
-        const workflow = await this.persistence.getWorkflow(workflowId);
-        if (!workflow) {
-            throw new Error(`Workflow ${workflowId} not found`);
-        }
+    async activateWorkflow(ctx, workflowId) {
+        // Guard up front, before any external side-effects (webhook/scheduler).
+        const { record } = await this.authorizedWorkflow(ctx, workflowId, 'workflow:activate');
+        return this.activateInternal(record);
+    }
+    /**
+     * The activation work, already authorized. Used by the guarded
+     * {@link activateWorkflow} and by `createWorkflow` (whose create was itself
+     * authorized against the target folder).
+     */
+    async activateInternal(workflow) {
+        const workflowId = workflow.id;
         const config = parseWorkflowConfig(workflow.config);
         if (!this.triggers.has(config.trigger.type)) {
             throw new Error(`Trigger type "${config.trigger.type}" is not registered`);
@@ -152,11 +246,12 @@ export class WorkflowRuntime {
     /**
      * Deactivate a workflow's trigger.
      */
-    async deactivateWorkflow(workflowId) {
+    async deactivateWorkflow(ctx, workflowId) {
         const workflow = await this.persistence.getWorkflow(workflowId);
         if (!workflow) {
             throw new Error(`Workflow ${workflowId} not found`);
         }
+        await this.require(ctx, 'workflow:activate', this.workflowRef(workflow));
         const config = parseWorkflowConfig(workflow.config);
         if (!this.triggers.has(config.trigger.type))
             return;
@@ -332,7 +427,9 @@ export class WorkflowRuntime {
         const data = body && typeof body === 'object' && !Array.isArray(body)
             ? body
             : { body };
-        await this.resume(executionId, {
+        // System path: the unguessable secret in the URL is the authorization —
+        // there is no caller to ask the authorizer about.
+        await this.resumeInternal(executionId, {
             data: { action: 'approve', data },
         });
         return { status: 202, body: { received: true, executionId } };
@@ -349,11 +446,12 @@ export class WorkflowRuntime {
      *
      * Returns the execution ID.
      */
-    async triggerManual(workflowId, payload) {
+    async triggerManual(ctx, workflowId, payload) {
         const workflow = await this.persistence.getWorkflow(workflowId);
         if (!workflow) {
             throw new Error(`Workflow ${workflowId} not found`);
         }
+        await this.require(ctx, 'workflow:run', this.workflowRef(workflow));
         const config = parseWorkflowConfig(workflow.config);
         const triggerCfg = (config.trigger.config ?? {});
         const inputSchema = triggerCfg['inputSchema'];
@@ -368,11 +466,21 @@ export class WorkflowRuntime {
         return this.createAndEnqueue(workflow, triggerPayload);
     }
     /**
-     * Resume a paused execution.
-     *
-     * Stores the resume payload and re-enqueues the execution.
+     * Resume a paused execution. Guards `execution:approve`, then does the work.
      */
-    async resume(executionId, input) {
+    async resume(ctx, executionId, input) {
+        const exec = await this.persistence.getExecution(executionId);
+        if (!exec)
+            throw new ResourceNotFoundError('Execution', executionId);
+        await this.require(ctx, 'execution:approve', this.executionRef(exec));
+        return this.resumeInternal(executionId, input);
+    }
+    /**
+     * The resume work, already authorized. Private so the only ways in are the
+     * guarded {@link resume} or an explicit system entry point (a wait-callback,
+     * whose secret-in-path IS its authorization).
+     */
+    async resumeInternal(executionId, input) {
         const exec = await this.persistence.getExecution(executionId);
         if (!exec) {
             throw new Error(`Execution ${executionId} not found`);
@@ -447,27 +555,36 @@ export class WorkflowRuntime {
      *
      * Returns the new execution ID.
      */
-    async rerunFromStep(sourceExecutionId, fromStepId, options) {
+    async rerunFromStep(ctx, sourceExecutionId, fromStepId, options) {
+        const source = await this.persistence.getExecution(sourceExecutionId);
+        if (!source)
+            throw new Error(`Execution ${sourceExecutionId} not found`);
+        await this.require(ctx, 'execution:rerun', this.executionRef(source));
         const newExecutionId = await this.executor.rerunFromStep(sourceExecutionId, fromStepId, options);
         await this.queue.enqueue({ executionId: newExecutionId });
         return newExecutionId;
     }
     // ─── CRUD (used by router) ───
     /**
-     * List all workflows visible to the given auth metadata.
+     * List the workflows visible to `ctx`. The host's filter is pushed *into*
+     * the adapter's query — the SDK never enumerates ids to post-filter.
      */
-    async listWorkflows(metadata, filter) {
-        return this.persistence.listWorkflows(metadata, filter);
+    async listWorkflows(ctx, page) {
+        const filter = await this.filterFor(ctx, 'workflow');
+        const records = await this.persistence.listWorkflows(filter, page);
+        return this.project(ctx, records, (wf) => this.workflowRef(wf));
     }
-    /** Workflow counts for the scope — total + per-folder, for the folder rail. */
-    async workflowCounts(metadata) {
-        return this.persistence.countWorkflowsByFolder(metadata);
+    /** Workflow counts for the visible set — total + per-folder, for the folder rail. */
+    async workflowCounts(ctx) {
+        return this.persistence.countWorkflowsByFolder(await this.filterFor(ctx, 'workflow'));
     }
     /**
-     * Get a single workflow by ID.
+     * Get a single workflow by ID. Guards `workflow:read` and attaches the
+     * caller's `permittedActions` for the UI.
      */
-    async getWorkflow(workflowId) {
-        return this.persistence.getWorkflow(workflowId);
+    async getWorkflow(ctx, workflowId) {
+        const { record, permittedActions } = await this.authorizedWorkflow(ctx, workflowId, 'workflow:read');
+        return { ...record, permittedActions };
     }
     /**
      * Create a new workflow definition.
@@ -475,13 +592,12 @@ export class WorkflowRuntime {
      * Validates the config, persists it, and optionally activates the trigger.
      * Returns the created WorkflowRecord.
      */
-    async createWorkflow(input) {
+    async createWorkflow(ctx, input) {
+        // Create is an action on the *container*: the folder is the thing that
+        // exists, so this same decision is what the UI projects onto its "New
+        // workflow" button. Also proves the folder exists — no separate lookup.
+        await this.authorizedFolder(ctx, input.folderId, 'workflow:create');
         const validation = this.validateConfig(input.config);
-        // Every workflow must live in an existing folder.
-        const folders = await this.persistence.listFolders(input.metadata ?? {});
-        if (!folders.some((f) => f.id === input.folderId)) {
-            throw new Error(`Folder ${input.folderId} not found`);
-        }
         const metadata = { ...input.metadata, name: input.name };
         const id = await this.persistence.createWorkflow({
             status: 'ACTIVE',
@@ -490,13 +606,15 @@ export class WorkflowRuntime {
             eventType: input.config.trigger.type,
             summary: input.summary ?? null,
             folderId: input.folderId,
+            attributes: input.attributes,
         });
         const record = await this.persistence.getWorkflow(id);
         if (!record)
             throw new Error('Failed to read created workflow');
         if (validation.valid) {
             try {
-                await this.activateWorkflow(id);
+                // Internal post-create activation — already authorized by the create above.
+                await this.activateInternal(record);
             }
             catch {
                 // Non-fatal — workflow is created but trigger may need manual activation
@@ -511,20 +629,16 @@ export class WorkflowRuntime {
      * Accepts partial updates: config, metadata, or both.
      * If config changes, validates it and updates the trigger type.
      */
-    async updateWorkflow(workflowId, input) {
-        const existing = await this.persistence.getWorkflow(workflowId);
-        if (!existing) {
-            throw new Error(`Workflow ${workflowId} not found`);
-        }
+    async updateWorkflow(ctx, workflowId, input) {
+        const { record: existing } = await this.authorizedWorkflow(ctx, workflowId, 'workflow:update');
         const update = {};
         if (input.summary !== undefined)
             update.summary = input.summary;
-        // Move to another folder — must exist in scope.
-        if (input.folderId !== undefined) {
-            const folders = await this.persistence.listFolders(input.metadata ?? {});
-            if (!folders.some((f) => f.id === input.folderId)) {
-                throw new Error(`Folder ${input.folderId} not found`);
-            }
+        // Move to another folder — needs `workflow:create` on the destination, the
+        // same decision that gates creating one there. `authorizedFolder` also
+        // proves the folder exists.
+        if (input.folderId !== undefined && input.folderId !== existing.folderId) {
+            await this.authorizedFolder(ctx, input.folderId, 'workflow:create');
             update.folderId = input.folderId;
         }
         // Update config if provided.
@@ -552,12 +666,35 @@ export class WorkflowRuntime {
         return updated;
     }
     // ─── Folders ───
-    /** List folders visible to the given scope metadata. */
-    async listFolders(metadata) {
-        return this.persistence.listFolders(metadata);
+    /** List folders the caller may see. */
+    async listFolders(ctx) {
+        const records = await this.persistence.listFolders(await this.filterFor(ctx, 'folder'));
+        return this.project(ctx, records, (f) => this.folderRef(f));
+    }
+    /**
+     * Get a single folder by id. Guards `folder:read` and attaches the caller's
+     * `permittedActions` — which include the container actions
+     * (`workflow:create` / `folder:create`), so the UI gates this folder's "New…"
+     * menu off the same decision the runtime will enforce.
+     */
+    async getFolder(ctx, folderId) {
+        const { record, permittedActions } = await this.authorizedFolder(ctx, folderId, 'folder:read');
+        return { ...record, permittedActions };
+    }
+    /**
+     * What may the caller do at the top level — create a root folder, manage
+     * credentials? Container actions on a resource that has no instance, so the
+     * client can gate its top-level "New…" buttons without inventing a resource.
+     */
+    async capabilities(ctx) {
+        return this.authorizer.permissions(ctx, { type: 'root' });
     }
     /** Create a folder for organizing workflows. */
-    async createFolder(input) {
+    async createFolder(ctx, input) {
+        // Create is an action on the container: a nested folder is gated by its
+        // parent, a top-level folder by `root`. Both are things the client can ask
+        // about before rendering "New folder".
+        await this.require(ctx, 'folder:create', await this.containerRef(input.parentId));
         const name = input.name.trim();
         if (!name)
             throw new Error('Folder name is required');
@@ -565,21 +702,25 @@ export class WorkflowRuntime {
             name,
             metadata: JSON.stringify(input.metadata ?? {}),
             parentId: input.parentId ?? null,
+            attributes: input.attributes,
         });
-        const folders = await this.persistence.listFolders(input.metadata ?? {});
-        const created = folders.find((f) => f.id === id);
+        const created = await this.persistence.getFolder(id);
         if (!created)
             throw new Error('Failed to read created folder');
         return created;
     }
-    /** Rename or reparent a folder. */
-    async moveBatch(authMetadata, input) {
+    /** Reorganize folders and workflows in one batch (drag-and-drop). */
+    async moveBatch(ctx, input) {
+        // Each item is authorized individually by the op it delegates to, which
+        // guards both ends of the move: `*:update` on the thing moved and
+        // `*:create` on the destination container.
         await Promise.all([
-            ...input.folders.map((f) => this.updateFolder(f.id, { parentId: f.parentId })),
-            ...input.workflows.map((w) => this.updateWorkflow(w.id, { folderId: w.folderId, metadata: authMetadata })),
+            ...input.folders.map((f) => this.updateFolder(ctx, f.id, { parentId: f.parentId })),
+            ...input.workflows.map((w) => this.updateWorkflow(ctx, w.id, { folderId: w.folderId })),
         ]);
     }
-    async updateFolder(id, input) {
+    async updateFolder(ctx, id, input) {
+        await this.authorizedFolder(ctx, id, 'folder:update');
         if (input.name !== undefined && !input.name.trim()) {
             throw new Error('Folder name cannot be empty');
         }
@@ -588,10 +729,14 @@ export class WorkflowRuntime {
             data.name = input.name.trim();
         if ('parentId' in input) {
             const newParent = input.parentId ?? null;
+            // Reparenting adds a child to the destination, so it needs the same
+            // permission as creating one there — otherwise `folder:create` gates the
+            // "New folder" button and a drag-and-drop walks straight around it.
+            await this.require(ctx, 'folder:create', await this.containerRef(newParent));
             // Moving a folder into itself or any of its own descendants creates a
             // cycle — the folder would disappear from all reachable tree paths.
             if (newParent !== null) {
-                const allFolders = await this.persistence.listFolders({});
+                const allFolders = await this.persistence.listAllFolders();
                 const descendants = new Set([id]);
                 const queue = [id];
                 while (queue.length > 0) {
@@ -615,9 +760,12 @@ export class WorkflowRuntime {
      * Delete a folder. Blocked while it still holds workflows — every workflow
      * must belong to a folder, so callers must move/remove its members first.
      */
-    async deleteFolder(id, metadata) {
-        const members = await this.persistence.listWorkflows(metadata, { folderId: id, limit: 1 });
-        if (members.length > 0) {
+    async deleteFolder(ctx, id) {
+        await this.authorizedFolder(ctx, id, 'folder:delete');
+        // Unfiltered on purpose: emptiness is a property of the folder, not of what
+        // this caller can see. Counting only visible workflows would let someone
+        // delete a folder out from under workflows they have no access to.
+        if ((await this.persistence.countWorkflowsInFolder(id)) > 0) {
             throw new Error('Folder not empty');
         }
         await this.persistence.deleteFolder(id);
@@ -625,48 +773,61 @@ export class WorkflowRuntime {
     /**
      * Top N recurring error messages across failed executions in a time window.
      */
-    async getTopErrors(params) {
+    async getTopErrors(ctx, params) {
         if (typeof this.persistence.getTopErrors !== 'function')
             return [];
-        return this.persistence.getTopErrors(params);
+        // Derived from executions, so it carries the same visibility as them.
+        return this.persistence.getTopErrors(await this.filterFor(ctx, 'workflow'), params);
     }
     /**
      * Full analytics summary computed server-side — replaces fetching all executions on the client.
      */
-    async getAnalyticsSummary(params) {
-        if (typeof this.persistence.getAnalyticsSummary !== 'function') {
-            return {
-                totalRuns: 0,
-                successRate: 0,
-                byStatus: {},
-                runsByDay: [],
-                byWorkflow: [],
-                recentFailures: [],
-                activeWorkflows: 0,
-                totalWorkflows: 0,
-            };
-        }
-        return this.persistence.getAnalyticsSummary(params);
+    async getAnalyticsSummary(ctx, params) {
+        const empty = {
+            totalRuns: 0,
+            successRate: 0,
+            byStatus: {},
+            runsByDay: [],
+            byWorkflow: [],
+            recentFailures: [],
+            activeWorkflows: 0,
+            totalWorkflows: 0,
+        };
+        if (typeof this.persistence.getAnalyticsSummary !== 'function')
+            return empty;
+        // Analytics is derived from workflows — scope it to the caller's visible
+        // workflows via the authorizer, exactly like listExecutions.
+        return this.persistence.getAnalyticsSummary(await this.filterFor(ctx, 'workflow'), params);
     }
     /**
      * Per-step progress events (agent thinking / tool calls / logs) for the run
      * view's activity timeline. Delegates to persistence.
      */
-    async getStepEvents(executionId, stepName, after) {
+    async getStepEvents(ctx, executionId, stepName, after) {
+        const exec = await this.persistence.getExecution(executionId);
+        if (exec)
+            await this.require(ctx, 'execution:read', this.executionRef(exec));
         return this.persistence.getStepEvents(executionId, stepName, after);
     }
     /**
-     * List executions with optional filters and cursor pagination.
+     * List executions with optional filters and cursor pagination. Scoped to the
+     * caller's visible workflows (an execution is visible iff its workflow is).
      */
-    async listExecutions(params) {
-        return this.persistence.listExecutions(params);
+    async listExecutions(ctx, params) {
+        // Executions inherit their workflow's visibility — the adapter joins the
+        // workflow filter rather than us enumerating workflow ids first.
+        return this.persistence.listExecutions(await this.filterFor(ctx, 'workflow'), params);
     }
     /**
      * Lightweight list of executions waiting for approval — only the fields
      * needed to render the approval queue without N individual fetches.
      */
-    async listPendingApprovals(limit) {
-        const { items } = await this.persistence.listExecutions({ status: 'EXTERNAL_WAIT', ...(limit !== undefined ? { limit } : {}) });
+    async listPendingApprovals(ctx, limit) {
+        // Visible-workflow scoped for now: any caller who can see the workflow sees
+        // its pending gates. Narrowing this to the step's assignee is P3, and lands
+        // as `visibleFilter(ctx, 'approval')` — this stays the workflow filter until
+        // approval steps actually carry an assignee.
+        const { items } = await this.persistence.listExecutions(await this.filterFor(ctx, 'workflow'), { status: 'EXTERNAL_WAIT', ...(limit !== undefined ? { limit } : {}) });
         const results = await Promise.all(items.map(async (exec) => {
             const steps = await this.persistence.getStepRows(exec.id);
             // Prefer the resumable leaf gate (non-control); fall back to any wait.
@@ -717,13 +878,14 @@ export class WorkflowRuntime {
     /**
      * Get execution detail including step records.
      */
-    async getExecutionDetail(executionId) {
+    async getExecutionDetail(ctx, executionId) {
         const exec = await this.persistence.getExecution(executionId);
         if (!exec)
             return null;
+        const perms = await this.require(ctx, 'execution:read', this.executionRef(exec));
         const stepRows = await this.persistence.getStepRows(executionId);
         // Try to attach the workflow config snapshot
-        const result = { execution: exec, steps: stepRows };
+        const result = { execution: exec, steps: stepRows, permittedActions: perms };
         const workflow = await this.persistence.getWorkflow(exec.workflowId);
         if (workflow) {
             result.summary = workflow.summary;
@@ -746,9 +908,9 @@ export class WorkflowRuntime {
         try {
             const state = await this.persistence.getExecutionState(executionId);
             if (state?.context) {
-                const ctx = JSON.parse(state.context);
-                if (ctx.trigger) {
-                    result.triggerData = ctx.trigger;
+                const wfCtx = JSON.parse(state.context);
+                if (wfCtx.trigger) {
+                    result.triggerData = wfCtx.trigger;
                 }
             }
         }
@@ -760,11 +922,12 @@ export class WorkflowRuntime {
     /**
      * Cancel a running or paused execution.
      */
-    async cancelExecution(executionId) {
+    async cancelExecution(ctx, executionId) {
         const exec = await this.persistence.getExecution(executionId);
         if (!exec) {
             throw new Error(`Execution ${executionId} not found`);
         }
+        await this.require(ctx, 'execution:cancel', this.executionRef(exec));
         if (exec.status === 'COMPLETED' || exec.status === 'FAILED' || exec.status === 'CANCELLED') {
             throw new Error(`Execution ${executionId} is already terminal (status: ${exec.status})`);
         }
@@ -773,23 +936,43 @@ export class WorkflowRuntime {
         this.log.info(`execution ${executionId} cancelled`);
     }
     /**
-     * List credentials visible to the given auth metadata.
+     * List credentials the caller may see — filtered by the authorizer, redacted
+     * (never secret data).
      */
-    async listCredentials(metadata) {
-        return this.persistence.listCredentials(metadata);
+    async listCredentials(ctx) {
+        const creds = await this.persistence.listCredentials(await this.filterFor(ctx, 'credential'));
+        return creds.map((c) => ({ id: c.id, name: c.name, type: c.type }));
     }
-    /**
-     * Store a credential.
-     */
-    async createCredential(metadata, name, credential) {
-        await this.persistence.storeCredential(metadata, name, credential);
-        return { name, type: credential.type };
+    /** Fetch a single credential's metadata by id (guarded `credential:read`; no secret). */
+    async getCredential(ctx, id) {
+        const cred = await this.persistence.getCredential(id);
+        if (!cred)
+            return null;
+        const perms = await this.require(ctx, 'credential:read', this.credentialRef(cred));
+        return { ...cred, permittedActions: perms };
     }
     /**
-     * Delete a credential by name.
+     * Create a credential. Tenant/ownership ride typed `attributes` (via
+     * {@link Register}), stamped and stored exactly like a workflow's.
      */
-    async deleteCredential(metadata, name) {
-        await this.persistence.deleteCredential(metadata, name);
+    async createCredential(ctx, input) {
+        // Credentials have no folder — `root` is their container.
+        await this.require(ctx, 'credential:manage', { type: 'root' });
+        const id = await this.persistence.createCredential({
+            name: input.name,
+            type: input.type,
+            data: input.data,
+            attributes: input.attributes,
+        });
+        return { id, name: input.name, type: input.type };
+    }
+    /** Delete a credential by id — guarded by `credential:manage` on the stored row. */
+    async deleteCredential(ctx, id) {
+        const cred = await this.persistence.getCredential(id);
+        if (!cred)
+            throw new Error(`Credential ${id} not found`);
+        await this.require(ctx, 'credential:manage', this.credentialRef(cred));
+        await this.persistence.deleteCredential(id);
     }
     // ─── Job Processing ───
     /**
@@ -915,6 +1098,10 @@ export class WorkflowRuntime {
         const initialContext = {
             workflow: {
                 id: workflow.id,
+                // The execution's tenant, carried by the resource. The executor
+                // re-hydrates this from the record on every run, so this is a seed
+                // rather than the authority.
+                attributes: workflow.attributes,
                 metadata,
             },
             trigger: triggerPayload,
@@ -930,11 +1117,14 @@ export class WorkflowRuntime {
         return execId;
     }
     async resolveCredentialsForTrigger(workflow) {
-        const metadata = JSON.parse(workflow.metadata ?? '{}');
-        const creds = await this.persistence.listCredentials(metadata);
+        // System path: no caller exists at execution time, so the scope is carried
+        // by the resource — the workflow's own typed `attributes` say which tenant's
+        // credentials it may resolve. Not an ACL decision; there is nobody to ask about.
+        const scope = workflow.attributes;
+        const creds = await this.persistence.listTenantCredentials(scope);
         const resolved = {};
         for (const cred of creds) {
-            const full = await this.persistence.resolveCredential(metadata, cred.name);
+            const full = await this.persistence.resolveCredential(scope, cred.name);
             if (full) {
                 resolved[cred.name] = full;
             }