@kici-dev/orchestrator 0.0.0 → 0.1.2

package/dist/secrets/backend-sync.d.ts

@@ -0,0 +1,40 @@
+import type { Logger } from '@kici-dev/shared';
+import type { BackendRegistry } from './backend-registry.js';
+/**
+ * Manages scope discovery and sync for all registered secret backends.
+ *
+ * On each sync cycle, lists scopes from each backend's store, applies
+ * the scope filter, and updates the registry with the discovered count.
+ */
+export declare class BackendSyncManager {
+    private readonly registry;
+    private readonly logger;
+    private readonly intervalHandles;
+    constructor(registry: BackendRegistry, logger: Logger);
+    /**
+     * Sync a single backend by name. Discovers scopes via listing,
+     * applies the scope filter, and updates the registry.
+     */
+    syncBackend(name: string): Promise<{
+        scopeCount: number;
+        error?: string;
+    }>;
+    /**
+     * Sync all enabled backends in parallel via Promise.allSettled.
+     */
+    syncAllBackends(): Promise<Array<{
+        name: string;
+        scopeCount: number;
+        error?: string;
+    }>>;
+    /**
+     * Start periodic sync for each enabled backend at its configured interval.
+     */
+    startPeriodicSync(): void;
+    private startPeriodicSyncAsync;
+    /**
+     * Stop all periodic sync intervals.
+     */
+    stopPeriodicSync(): void;
+}
+//# sourceMappingURL=backend-sync.d.ts.map

package/dist/secrets/cleanup.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Periodic cleanup of orphaned ephemeral keys and secret outputs.
+ *
+ * Runs on a configurable interval (default: 1 hour) and deletes rows
+ * from run_ephemeral_keys and run_secret_outputs older than a configurable
+ * threshold (default: 24 hours). This catches data from crashed or
+ * abandoned runs whose normal cleanup never fired.
+ */
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+export interface SecretCleanupDeps {
+    db: Kysely<Database>;
+    /** Max age in hours before rows are considered orphaned. Default: 24 */
+    maxAgeHours?: number;
+    /** Optional logger for cleanup messages */
+    logger?: {
+        info(msg: string, meta?: Record<string, unknown>): void;
+        warn(msg: string, meta?: Record<string, unknown>): void;
+    };
+}
+/**
+ * Delete orphaned ephemeral keys and secret outputs older than maxAgeHours.
+ *
+ * @returns Count of deleted rows from each table
+ */
+export declare function cleanupOrphanedSecrets(db: Kysely<Database>, maxAgeHours?: number): Promise<{
+    keysDeleted: number;
+    outputsDeleted: number;
+}>;
+/**
+ * Build a per-tick handler for the orphan-secret-cleanup scheduled job.
+ *
+ * The cadence and the periodic wrapper itself live in
+ * `packages/orchestrator/src/queue/scheduled-job.ts` — this factory
+ * just produces the tick function. Success is logged only when rows
+ * were actually deleted to keep the hourly log line noise-free on an
+ * idle orchestrator.
+ */
+export declare function createOrphanSecretCleanupHandler(deps: SecretCleanupDeps): () => Promise<void>;
+//# sourceMappingURL=cleanup.d.ts.map

package/dist/secrets/config.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Secret store configuration.
+ */
+export interface SecretStoreConfig {
+    /** 32-byte AES-256 encryption key. */
+    masterKey: Buffer;
+    /** Key version for rotation tracking. Default 1. */
+    keyVersion: number;
+    /** Path to key file, if used. */
+    keyFilePath: string | undefined;
+    /** Previous master key for dual-key rotation. */
+    oldMasterKey?: Buffer;
+}
+/**
+ * Load the master encryption key from environment or file.
+ *
+ * Priority:
+ * 1. Environment variable (envKey, defaults to KICI_SECRET_KEY)
+ * 2. Key file (keyFilePath)
+ *
+ * @param envKey - Environment variable name to read. Defaults to KICI_SECRET_KEY.
+ * @param keyFilePath - Optional path to a file containing the key material.
+ * @returns 32-byte Buffer suitable for AES-256-GCM.
+ * @throws If neither env var nor key file provides a valid key.
+ */
+export declare function loadMasterKey(envKey?: string, keyFilePath?: string): Buffer;
+/**
+ * Load the old (previous) master encryption key for key rotation.
+ *
+ * Returns undefined when no old key is configured (normal operation).
+ * Returns a 32-byte Buffer when KICI_SECRET_KEY_OLD or a key file is set.
+ *
+ * @param envKey - Environment variable name to read. Defaults to KICI_SECRET_KEY_OLD.
+ * @param keyFilePath - Optional path to a file containing the old key material.
+ * @returns 32-byte Buffer or undefined if no old key is configured.
+ */
+export declare function loadOldMasterKey(envKey?: string, keyFilePath?: string): Buffer | undefined;
+/**
+ * Load the full secret store configuration.
+ *
+ * @param opts - Optional overrides for env var name, key file path, and key version.
+ * @returns Complete SecretStoreConfig ready for PgSecretStore.
+ */
+export declare function loadSecretStoreConfig(opts?: {
+    envKey?: string;
+    keyFilePath?: string;
+    keyVersion?: number;
+    oldEnvKey?: string;
+    oldKeyFilePath?: string;
+}): SecretStoreConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/secrets/crypto.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Encrypted value with key version tracking.
+ * The data field contains base64-encoded IV || AuthTag || Ciphertext.
+ */
+export interface EncryptedValue {
+    /** Base64-encoded IV + auth tag + ciphertext. */
+    data: string;
+    /** Version of the encryption key used. */
+    keyVersion: number;
+}
+/**
+ * Encrypt a plaintext string using AES-256-GCM with AAD.
+ *
+ * @param plaintext - The string to encrypt
+ * @param key - 32-byte encryption key
+ * @param keyVersion - Version number for key rotation tracking
+ * @param aad - Additional authenticated data (e.g., "contextId:keyName")
+ * @returns Encrypted value with key version
+ */
+export declare function encrypt(plaintext: string, key: Buffer, keyVersion: number, aad: string): EncryptedValue;
+/**
+ * Decrypt an encrypted value using AES-256-GCM with AAD verification.
+ *
+ * @param encrypted - The encrypted value to decrypt
+ * @param key - 32-byte encryption key (must match the key used for encryption)
+ * @param aad - Additional authenticated data (must match the AAD used for encryption)
+ * @returns Decrypted plaintext string
+ * @throws If decryption fails (wrong key, wrong AAD, tampered data)
+ */
+export declare function decrypt(encrypted: EncryptedValue, key: Buffer, aad: string): string;
+/**
+ * Derive a 32-byte encryption key from a string input.
+ *
+ * Accepts two formats:
+ * - 64-character hex string (e.g., from generateMasterKey())
+ * - Base64-encoded 32-byte key
+ *
+ * @param input - Hex or base64 encoded key material
+ * @returns 32-byte Buffer suitable for use with encrypt/decrypt
+ * @throws If the derived key is not exactly 32 bytes
+ */
+export declare function deriveKey(input: string): Buffer;
+/**
+ * Generate a new random 32-byte master key as a hex string.
+ *
+ * @returns 64-character hex string suitable for KICI_SECRET_KEY env var
+ */
+export declare function generateMasterKey(): string;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/secrets/ephemeral-keys.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Generate an X25519 key pair for a run.
+ *
+ * @returns publicKey and privateKey as DER-encoded Buffers
+ */
+export declare function generateRunKeyPair(): {
+    publicKey: Buffer;
+    privateKey: Buffer;
+};
+/**
+ * Encrypt a run's private key using the orchestrator secret key (KICI_SECRET_KEY).
+ *
+ * @param privateKey - DER-encoded private key Buffer
+ * @param secretKey - Orchestrator secret key (hex or base64 string)
+ * @returns Base64-encoded encrypted data (IV || AuthTag || Ciphertext)
+ */
+export declare function encryptPrivateKey(privateKey: Buffer, secretKey: string): string;
+/**
+ * Decrypt a run's private key using the orchestrator secret key (KICI_SECRET_KEY).
+ *
+ * @param encryptedData - Base64-encoded encrypted private key
+ * @param secretKey - Orchestrator secret key (hex or base64 string)
+ * @returns DER-encoded private key Buffer
+ * @throws If decryption fails
+ */
+export declare function decryptPrivateKey(encryptedData: string, secretKey: string): Buffer;
+/**
+ * Decrypt a secret output envelope produced by an agent.
+ *
+ * The agent encrypts with:
+ * 1. Generate ephemeral X25519 key pair
+ * 2. ECDH: shared secret = agentPrivateKey x runPublicKey
+ * 3. HKDF(sha256, sharedSecret, salt='', info='kici-run-secret-outputs', 32)
+ * 4. AES-256-GCM encrypt with derived key
+ *
+ * We decrypt with:
+ * 1. ECDH: shared secret = runPrivateKey x agentPublicKey
+ * 2. Same HKDF derivation
+ * 3. AES-256-GCM decrypt
+ *
+ * @param envelope - { agentPublicKey: base64, encrypted: base64 (IV||AuthTag||Ciphertext) }
+ * @param runPrivateKeyDer - DER-encoded run private key Buffer
+ * @returns Decrypted plaintext string
+ */
+export declare function decryptSecretOutput(envelope: {
+    agentPublicKey: string;
+    encrypted: string;
+}, runPrivateKeyDer: Buffer): string;
+//# sourceMappingURL=ephemeral-keys.d.ts.map

package/dist/secrets/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Secrets management module.
+ *
+ * Re-exports the PG secret store, audit logger, crypto utilities,
+ * and configuration helpers.
+ */
+export { PgSecretStore } from './pg-secret-store.js';
+export { AuditLogger } from './audit-logger.js';
+export { loadMasterKey, loadOldMasterKey, loadSecretStoreConfig, type SecretStoreConfig, } from './config.js';
+export { encrypt, decrypt, deriveKey, generateMasterKey, type EncryptedValue } from './crypto.js';
+export { VaultSecretStore, type VaultConfig } from './vault-secret-store.js';
+export { SecretResolver, type SecretResolverDeps, type ResolvedSecretMeta, type EnvironmentStoreLike, type BindingStoreLike, type SecretStoreLike, } from './secret-resolver.js';
+export { BackendSyncManager } from './backend-sync.js';
+export { RbacEnforcer, PermissionDeniedError, type Role, type Permission } from './rbac.js';
+export { TokenManager } from './token-manager.js';
+export { cleanupOrphanedSecrets, createOrphanSecretCleanupHandler, type SecretCleanupDeps, } from './cleanup.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/secrets/pg-secret-store.d.ts

@@ -0,0 +1,105 @@
+/**
+ * PostgreSQL-backed secret store implementing SecretStore.
+ *
+ * Encrypts secret values at rest using AES-256-GCM with AAD binding
+ * (orgId:scope:keyName) to prevent cross-scope secret swaps.
+ *
+ * Operates on the scoped_secrets table with (org_id, scope, key) composite key.
+ */
+import { type Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { SecretStore } from '@kici-dev/engine';
+import type { AuditLogger } from './audit-logger.js';
+/**
+ * PostgreSQL secret store with AES-256-GCM encryption.
+ * Uses scoped_secrets table keyed by (org_id, scope, key).
+ */
+export declare class PgSecretStore implements SecretStore {
+    private readonly db;
+    private readonly masterKey;
+    private keyVersion;
+    private readonly auditLogger;
+    private readonly oldMasterKey?;
+    /**
+     * When false, setSecret() rejects for non-internal scopes (customer secrets disabled).
+     * Internal scopes (__source__/* and __webhook__/*) are always allowed.
+     */
+    customerSecretsEnabled: boolean;
+    constructor(db: Kysely<Database>, masterKey: Buffer, keyVersion: number, auditLogger: AuditLogger, oldMasterKey?: Buffer | undefined);
+    /**
+     * Create a PgSecretStore with keyVersion initialized from the database.
+     * Reads MAX(key_version) from scoped_secrets to avoid version conflicts
+     * after orchestrator restarts.
+     */
+    static create(db: Kysely<Database>, masterKey: Buffer, auditLogger: AuditLogger, oldMasterKey?: Buffer): Promise<PgSecretStore>;
+    /**
+     * Decrypt with current key, falling back to old key if available.
+     * Follows the same dual-key pattern as decryptPrivateKey() in ephemeral-keys.ts.
+     */
+    private decryptWithFallback;
+    /**
+     * Get all secrets for a scope as decrypted key-value pairs.
+     */
+    getSecrets(orgId: string, scope: string): Promise<Record<string, string>>;
+    /**
+     * Set (create or update) a secret in a scope.
+     * Encrypts the value with AAD = "orgId:scope:key".
+     */
+    /** Check if a scope is internal/operational (always allowed regardless of toggle). */
+    private isInternalScope;
+    setSecret(orgId: string, scope: string, key: string, value: string): Promise<void>;
+    /**
+     * Delete a secret from a scope.
+     */
+    deleteSecret(orgId: string, scope: string, key: string): Promise<void>;
+    /**
+     * List all secret key names in a scope (no values returned).
+     */
+    listKeys(orgId: string, scope: string): Promise<string[]>;
+    /**
+     * List all distinct scopes for an org.
+     *
+     * When orgId is empty, returns all distinct org_ids (with trailing slash)
+     * to support backend-sync scope discovery. This matches the Vault convention
+     * where listScopes('') returns top-level directory entries.
+     */
+    listScopes(orgId: string): Promise<string[]>;
+    /**
+     * Get all secrets for an org (for resolver).
+     * Returns scope, key, encrypted value, and key version without decrypting.
+     */
+    getAllSecrets(orgId: string): Promise<Array<{
+        scope: string;
+        key: string;
+        encryptedValue: string;
+        keyVersion: number;
+    }>>;
+    /**
+     * Decrypt a single secret value given its encrypted data, key version, and AAD components.
+     */
+    decryptValue(orgId: string, scope: string, key: string, encryptedValue: string, keyVersion: number): string;
+    /**
+     * Create an empty scope using a sentinel row (__empty__ key).
+     * If the scope already has keys, this is a no-op (idempotent).
+     */
+    createScope(orgId: string, scope: string): Promise<void>;
+    /**
+     * Rename a scope -- atomically update scoped_secrets and environment_bindings.
+     */
+    renameScope(orgId: string, oldScope: string, newScope: string): Promise<void>;
+    /**
+     * Delete a scope and all its secrets, plus any environment bindings referencing it.
+     */
+    deleteScope(orgId: string, scope: string): Promise<void>;
+    /**
+     * Rotate the encryption key version.
+     * Re-encrypts all secrets with the same master key but a new key version.
+     * Runs in a transaction for atomicity.
+     *
+     * @returns Number of re-encrypted secret values.
+     */
+    rotateKey(): Promise<{
+        reEncrypted: number;
+    }>;
+}
+//# sourceMappingURL=pg-secret-store.d.ts.map

package/dist/secrets/rbac.d.ts

@@ -0,0 +1,47 @@
+/**
+ * RBAC (Role-Based Access Control) enforcer for secrets management admin API.
+ *
+ * Provides a fixed 3-role permission model:
+ * - owner: all permissions (manages tokens, rotates keys)
+ * - admin: context + secret + audit management
+ * - auditor: read-only access to contexts and audit logs (no secret values)
+ */
+/**
+ * Fixed roles for the secrets management admin API.
+ */
+export type Role = 'owner' | 'admin' | 'auditor';
+/**
+ * Permissions for the secrets management admin API.
+ */
+export type Permission = 'context.create' | 'context.read' | 'context.update' | 'context.delete' | 'secret.read' | 'secret.write' | 'secret.delete' | 'secret.reveal' | 'audit.read' | 'token.manage' | 'key.rotate' | 'run.read' | 'run.cancel' | 'event_log.read' | 'event_log.read_payload' | 'access_log.read' | 'scheduled_job.trigger' | 'event_dlq.read' | 'event_dlq.manage';
+/**
+ * Error thrown when a role lacks the required permission.
+ */
+export declare class PermissionDeniedError extends Error {
+    readonly role: Role;
+    readonly permission: Permission;
+    constructor(role: Role, permission: Permission);
+}
+/**
+ * RBAC enforcer for the secrets management admin API.
+ *
+ * Checks role-based permissions using a static permission mapping.
+ * No database or external state -- purely in-memory evaluation.
+ */
+export declare class RbacEnforcer {
+    /**
+     * Check whether a role has a specific permission.
+     */
+    hasPermission(role: Role, permission: Permission): boolean;
+    /**
+     * Require a permission, throwing PermissionDeniedError if not authorized.
+     */
+    requirePermission(role: Role, permission: Permission): void;
+    /**
+     * Check whether a role can access secret values (not just metadata).
+     * Only owner and admin can see actual secret values.
+     * Auditor can see context metadata and audit logs but NOT secret values.
+     */
+    canAccessSecretValues(role: Role): boolean;
+}
+//# sourceMappingURL=rbac.d.ts.map

package/dist/secrets/secret-output-store.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Secret output store for cross-job secret output CRUD.
+ *
+ * Provides typed operations against the run_secret_outputs table:
+ * - Upsert encrypted secret outputs (per run/job/key)
+ * - Retrieve outputs for a specific job or multiple upstream jobs
+ * - Delete all outputs for a run (cleanup)
+ * - Delete orphaned outputs older than a threshold (maintenance)
+ */
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+export declare class SecretOutputStore {
+    private readonly db;
+    constructor(db: Kysely<Database>);
+    /**
+     * Store an encrypted secret output (upsert).
+     * If (run_id, job_id, output_key) already exists, the value is updated.
+     */
+    storeSecretOutput(runId: string, jobId: string, outputKey: string, encryptedValue: string): Promise<void>;
+    /**
+     * Get all secret outputs for a specific job in a run.
+     *
+     * @returns Record mapping output_key -> encrypted_value
+     */
+    getSecretOutputs(runId: string, jobId: string): Promise<Record<string, string>>;
+    /**
+     * Get secret outputs from multiple upstream jobs.
+     *
+     * @returns Record mapping jobId -> Record<output_key, encrypted_value>
+     */
+    getUpstreamSecretOutputs(runId: string, jobIds: string[]): Promise<Record<string, Record<string, string>>>;
+    /**
+     * Delete all secret outputs for a run.
+     *
+     * @returns Number of rows deleted
+     */
+    deleteByRunId(runId: string): Promise<number>;
+    /**
+     * Delete orphaned secret outputs older than maxAgeHours.
+     * Used for periodic cleanup of outputs from completed/abandoned runs.
+     *
+     * @returns Number of rows deleted
+     */
+    cleanupOrphaned(maxAgeHours: number): Promise<number>;
+}
+//# sourceMappingURL=secret-output-store.d.ts.map

package/dist/secrets/secret-resolver.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Secret resolver for dispatch-time secret resolution.
+ *
+ * Uses environment bindings + scope resolver to match secrets from multiple backends.
+ * When a job dispatches with an environment name, the resolver:
+ * 1. Looks up the environment by name
+ * 2. Gets bindings for that environment
+ * 3. Queries ALL registered backend stores for secrets
+ * 4. Prefixes each secret's scope with the backend name (e.g., pg:aws/prod)
+ * 5. Uses resolveSecretsForEnvironment to match bindings against prefixed secrets
+ * 6. Returns a flat decrypted key-value map
+ *
+ * unreachable backends cause job failure (not silent skip).
+ * external (Vault) secrets are fetched real-time (no cache).
+ * longest-path-wins uses scope path after stripping backend prefix.
+ * audit log includes backend name.
+ */
+import { type EnvironmentBinding, type ScopedSecret } from '@kici-dev/engine';
+import type { Logger } from '@kici-dev/shared';
+import type { AuditLogger } from './audit-logger.js';
+/**
+ * Minimal environment store interface (subset needed by resolver).
+ */
+export interface EnvironmentStoreLike {
+    getByName(orgId: string, name: string): Promise<{
+        id: string;
+        name: string;
+        orgId: string;
+    } | null>;
+}
+/**
+ * Minimal binding store interface (subset needed by resolver).
+ */
+export interface BindingStoreLike {
+    getByEnvironmentId(environmentId: string): Promise<EnvironmentBinding[]>;
+}
+/**
+ * Minimal secret store interface (subset needed by resolver).
+ * getAllSecrets returns raw encrypted secrets; decrypt decrypts a single secret.
+ * getSecrets returns a decrypted key-value map for a single scope (used by
+ * resolveNamed for source-scoped credential lookup).
+ */
+export interface SecretStoreLike {
+    getAllSecrets(orgId: string): Promise<ScopedSecret[]>;
+    decrypt(secret: ScopedSecret): string;
+    getSecrets(orgId: string, scope: string): Promise<Record<string, string>>;
+}
+/**
+ * Dependencies for the SecretResolver.
+ */
+export interface SecretResolverDeps {
+    environmentStore: EnvironmentStoreLike;
+    bindingStore: BindingStoreLike;
+    /** Map of backend name to store. Replaces single secretStore. */
+    backendStores: Map<string, SecretStoreLike>;
+    auditLogger: AuditLogger;
+    logger: Logger;
+}
+/** Metadata about a resolved secret. */
+export interface ResolvedSecretMeta {
+    value: string;
+    backend: string;
+    scope: string;
+}
+/**
+ * Resolves secrets for a job by matching environment bindings against scoped secrets
+ * from multiple backends.
+ *
+ * All backend stores are queried. Each secret's scope is prefixed with the backend
+ * name (e.g., 'pg:aws/prod', 'vault-prod:databases/staging'). The prefixed scopes
+ * are matched against binding patterns, and longest-path-wins uses the path AFTER
+ * stripping the backend prefix.
+ */
+export declare class SecretResolver {
+    private readonly environmentStore;
+    private readonly bindingStore;
+    private readonly backendStores;
+    private readonly auditLogger;
+    private readonly logger;
+    constructor(deps: SecretResolverDeps);
+    /**
+     * Resolve secrets for a job dispatch.
+     *
+     * @param orgId - Organization ID
+     * @param environmentName - Environment name to resolve secrets for
+     * @returns Flat map of decrypted secret key-value pairs
+     */
+    resolveForJob(orgId: string, environmentName: string): Promise<Record<string, string>>;
+    /**
+     * Resolve a single named secret by (orgId, scope, key), optionally scoped to
+     * a specific backend. Bypasses environment bindings — this is a direct
+     * lookup used for source-scoped credentials (e.g. universal-git PAT/SSH
+     * keys stored under `__source__/<sourceId>`).
+     *
+     * When `store` is omitted, backends are tried in Map iteration order (the
+     * order they were registered) and the first hit wins. An explicit `store`
+     * restricts the lookup to that one backend and returns null on miss.
+     *
+     * Audit-log: writes one `resolve_named` entry on success. Throws when the
+     * named store is requested but doesn't exist, mirroring `resolveForJob`'s
+     * fail-fast policy — the caller asked for a specific backend and
+     * it's gone.
+     */
+    resolveNamed(orgId: string, scope: string, key: string, opts?: {
+        store?: string;
+        runId?: string;
+        jobId?: string;
+    }): Promise<string | null>;
+    /**
+     * Resolve secrets with metadata (per, for secrets.getMeta).
+     *
+     * Returns the secret value along with which backend and scope provided it.
+     */
+    resolveForJobWithMeta(orgId: string, environmentName: string): Promise<Record<string, ResolvedSecretMeta>>;
+    /**
+     * Collect all secrets from all backend stores, prefixing scopes.
+     * Per /: unreachable backends are tracked but not fatal here.
+     * Callers apply scoped failure policy based on job bindings.
+     */
+    private collectAllSecrets;
+    /**
+     * Build a decrypt function that dispatches to the correct backend store.
+     */
+    private buildDecryptFn;
+    /**
+     * Check if any failed backend could affect the job's environment bindings.
+     * throw when a failed backend's scopes could match a binding and
+     * no healthy backend already satisfies that binding.
+     * jobs referencing only healthy backends succeed normally.
+     */
+    private checkScopedFailure;
+    /**
+     * Find the winning secret for a given key (highest scope depth after prefix strip).
+     */
+    private findWinningSecret;
+}
+//# sourceMappingURL=secret-resolver.d.ts.map

package/dist/secrets/source-credentials.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Source-scoped credential resolution.
+ *
+ * Generic/universal-git webhook sources store a `credentialRef` (see
+ * `providers/universal-git/config.ts`) that points to a secret the agent
+ * will use to clone the source's repo. The secret itself is stored under
+ * the reserved scope `__source__/<sourceId>` — the same convention already
+ * used by `PgSecretStore.isInternalScope()` — with `credentialRef.key` as
+ * the key name.
+ *
+ * This module is a thin, opinionated wrapper around
+ * `SecretResolver.resolveNamed()` that:
+ *   1. Builds the canonical scope string for a given source ID.
+ *   2. Delegates to the resolver's direct-lookup method.
+ *   3. Returns a structured failure (null + reason) so callers can emit
+ *      metrics without throwing across the clone-token boundary.
+ *
+ * The universal-git provider bundle's `CloneTokenProvider` is the primary
+ * consumer; an agent-side secret store lookup is **not** implemented here
+ * because the agent never talks to the orchestrator's secret backend
+ * directly — the orchestrator resolves and passes the material in the
+ * dispatch message (`gitAuth` / `sourceAuth` / `workflowAuth`).
+ */
+import type { SecretResolver } from './secret-resolver.js';
+import type { CredentialRef } from '../providers/universal-git/config.js';
+/**
+ * Canonical scope for a source-owned secret. Uses the `__source__/` prefix
+ * which is whitelisted by `PgSecretStore.isInternalScope()` so setting
+ * these secrets is allowed even when customer secrets are globally
+ * disabled.
+ */
+export declare function sourceCredentialScope(sourceId: string): string;
+/**
+ * Result of a source credential lookup. `ok: false` is a recoverable
+ * miss (secret not present in any backend, or explicit backend empty) —
+ * callers can emit metrics or fall through. Throws are reserved for
+ * genuine errors (missing backend when one was explicitly requested).
+ */
+export type SourceCredentialResult = {
+    ok: true;
+    value: string;
+    backend: string;
+} | {
+    ok: false;
+    reason: 'not_found' | 'store_missing';
+    message: string;
+};
+/**
+ * Resolve a source-scoped credential via the shared SecretResolver.
+ *
+ * @param resolver      The orchestrator's SecretResolver instance.
+ * @param orgId         Organisation/customer ID that owns the source.
+ * @param sourceId      Source row ID (`generic_webhook_sources.id`).
+ * @param credentialRef The `{ key, store? }` ref validated by Zod.
+ * @param opts          Optional correlation IDs for audit entries.
+ */
+export declare function resolveSourceCredential(resolver: SecretResolver, orgId: string, sourceId: string, credentialRef: CredentialRef, opts?: {
+    runId?: string;
+    jobId?: string;
+}): Promise<SourceCredentialResult>;
+//# sourceMappingURL=source-credentials.d.ts.map