@kici-dev/orchestrator 0.0.0 → 0.1.1

package/dist/secrets/token-manager.d.ts

@@ -0,0 +1,63 @@
+import { type Kysely } from 'kysely';
+import type { Database, AdminTokenRow } from '../db/types.js';
+import type { Role } from './rbac.js';
+/**
+ * Manages admin API tokens for the secrets management system.
+ *
+ * Tokens are 32-byte random hex strings (64 chars). Only the SHA-256
+ * hash is stored; the plaintext is returned once at generation time.
+ */
+export declare class TokenManager {
+    private readonly db;
+    constructor(db: Kysely<Database>);
+    /**
+     * Generate a new admin API token.
+     *
+     * @param label - Human-readable label for this token.
+     * @param role - Role to assign (owner, admin, auditor).
+     * @param routingKey - Optional routing key scope (null = all).
+     * @returns The plaintext token (shown once) and the row ID.
+     */
+    generateToken(label: string, role: Role, routingKey?: string | null): Promise<{
+        token: string;
+        id: string;
+    }>;
+    /**
+     * Validate a plaintext token against stored hashes.
+     *
+     * @param token - The plaintext token to validate.
+     * @returns Token info if valid, null if invalid/expired/revoked.
+     */
+    validate(token: string): Promise<{
+        id: string;
+        role: Role;
+        routingKey: string | null;
+        label: string;
+    } | null>;
+    /**
+     * Revoke a token by ID.
+     */
+    revokeToken(tokenId: string): Promise<void>;
+    /**
+     * List all tokens (excluding hash for security).
+     *
+     * @param routingKey - Optional filter by routing key.
+     */
+    listTokens(routingKey?: string | null): Promise<Omit<AdminTokenRow, 'token_hash'>[]>;
+    /**
+     * Ensure a bootstrap admin token exists.
+     *
+     * If KICI_BOOTSTRAP_ADMIN_TOKEN env var (or envOverride) is set,
+     * use that as the plaintext, hash, and upsert with label='bootstrap', role='owner'.
+     *
+     * If no env var and no non-revoked tokens exist, generate a new owner
+     * token and return the plaintext for logging.
+     *
+     * If tokens already exist, return null (no bootstrap needed).
+     *
+     * @param envOverride - Override for KICI_BOOTSTRAP_ADMIN_TOKEN env var.
+     * @returns Plaintext token if generated/created, null if not needed.
+     */
+    ensureBootstrapToken(envOverride?: string): Promise<string | null>;
+}
+//# sourceMappingURL=token-manager.d.ts.map

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

@@ -0,0 +1,85 @@
+import type { SecretStore } from '@kici-dev/engine';
+import type { Logger } from '@kici-dev/shared';
+/**
+ * Configuration for the Vault secret store backend.
+ */
+export interface VaultConfig {
+    /** Vault server URL (e.g., 'http://vault:8200'). */
+    vaultUrl: string;
+    /** Authentication method. */
+    authMethod: 'approle' | 'token';
+    /** AppRole role ID (required for 'approle' auth). */
+    roleId?: string;
+    /** AppRole secret ID (required for 'approle' auth). */
+    secretId?: string;
+    /** Static Vault token (required for 'token' auth). */
+    token?: string;
+    /** Vault Enterprise namespace. */
+    namespace?: string;
+    /** KV v2 mount path (default: 'secret'). */
+    mountPath?: string;
+    /** Base path within mount (e.g., 'kici/secrets'). */
+    basePath: string;
+}
+/**
+ * HashiCorp Vault backend implementing SecretStore.
+ *
+ * Supports AppRole and token authentication. KV v2 CRUD operations
+ * map (orgId, scope) to Vault paths under the configured basePath.
+ */
+export declare class VaultSecretStore implements SecretStore {
+    private readonly client;
+    private readonly config;
+    private readonly mountPath;
+    private readonly logger;
+    private authState;
+    constructor(config: VaultConfig, logger: Logger);
+    /**
+     * Log a Vault API request with structured context.
+     * Captures operation, path, status, and optionally error for diagnostics.
+     */
+    private logVaultRequest;
+    /**
+     * Authenticate with Vault and cache the token with TTL tracking.
+     */
+    private authenticate;
+    private getToken;
+    private withRetry;
+    /**
+     * Build the full Vault path for a scoped secret.
+     */
+    private secretPath;
+    /**
+     * Get all secrets for a scope as key-value pairs.
+     */
+    getSecrets(orgId: string, scope: string): Promise<Record<string, string>>;
+    /**
+     * Set (create or update) a secret in a scope.
+     */
+    setSecret(orgId: string, scope: string, key: string, value: string): Promise<void>;
+    /**
+     * Delete a secret key from a scope.
+     */
+    deleteSecret(orgId: string, scope: string, key: string): Promise<void>;
+    /**
+     * List all secret key names in a scope.
+     */
+    listKeys(orgId: string, scope: string): Promise<string[]>;
+    /**
+     * List all distinct scopes for an org.
+     * Vault KV v2 LIST only returns immediate children — directories end with '/'.
+     * We recurse into directories to discover leaf scopes (paths that hold actual secrets).
+     */
+    listScopes(orgId: string): Promise<string[]>;
+    /**
+     * Get all secrets for an org (for resolver).
+     * Lists scopes then reads each to collect all encrypted/plain values.
+     */
+    getAllSecrets(orgId: string): Promise<Array<{
+        scope: string;
+        key: string;
+        encryptedValue: string;
+        keyVersion: number;
+    }>>;
+}
+//# sourceMappingURL=vault-secret-store.d.ts.map

package/dist/security/comment-handler.d.ts

@@ -0,0 +1,67 @@
+/**
+ * /kici approve and /kici reject comment command handler.
+ *
+ * Parses issue_comment webhook bodies for /kici commands and handles
+ * approval/rejection of security holds. Verifies commenter identity
+ * via the trust policy cache and checks ci_trust:write+ before acting.
+ */
+import type { HeldRunStore } from '../environments/held-runs.js';
+import { type IdentityLink, type PermissionLevel } from './trust-resolver.js';
+import type { CheckStatusPoster as EngineCheckStatusPoster } from '@kici-dev/engine';
+/** Parsed /kici command from a comment body. */
+interface CommentCommand {
+    action: 'approve' | 'reject';
+    /** Optional: specific run to approve/reject. */
+    runId?: string;
+}
+/** Parameters for the approval comment handler. */
+export interface HandleApprovalCommentParams {
+    commentBody: string;
+    commenterUsername: string;
+    /**
+     * Commenter immutable IDP-side numeric id from the webhook event. Used to
+     * match the identity link by id first, falling back to username during the
+     * backfill window (see trust-resolver.findIdentityLink).
+     */
+    commenterUserId?: string;
+    provider: string;
+    repoIdentifier: string;
+    prNumber: number;
+    orgId: string;
+    identityLinks: IdentityLink[];
+    orgMemberPermissions: Map<string, PermissionLevel>;
+    heldRunStore: HeldRunStore;
+    /** Check status poster for updating GitHub checks after approval/rejection. */
+    checkStatusPoster?: EngineCheckStatusPoster;
+    /** Commit SHA for the PR head (needed for check status updates). */
+    commitSha?: string;
+    credentials: unknown;
+}
+/** Result of handling a comment. */
+interface HandleApprovalResult {
+    handled: boolean;
+    reason?: string;
+}
+/**
+ * Parse a comment body for /kici commands.
+ *
+ * Looks for `/kici approve` or `/kici reject` at the start of any line.
+ * Case-insensitive for the command word (approve/reject) but the /kici prefix is exact.
+ * Optional run ID follows the command.
+ *
+ * @returns Parsed command or null if no /kici command found.
+ */
+export declare function parseKiciCommand(commentBody: string): CommentCommand | null;
+/**
+ * Handle an approval comment from a PR.
+ *
+ * Flow:
+ * 1. Parse comment for /kici command
+ * 2. Look up commenter's identity link via trust policy cache
+ * 3. Check ci_trust level (must be write+)
+ * 4. Find held runs for the PR
+ * 5. Approve or reject held runs
+ */
+export declare function handleApprovalComment(params: HandleApprovalCommentParams): Promise<HandleApprovalResult>;
+export {};
+//# sourceMappingURL=comment-handler.d.ts.map

package/dist/security/contributor-cache.d.ts

@@ -0,0 +1,75 @@
+/**
+ * LRU cache wrapper for ContributorResolver.
+ *
+ * Caches contributor permission lookups to prevent redundant API calls.
+ * Uses a 15-minute TTL and 10,000 max entries.
+ */
+import type { ContributorResolver, ContributorInfo } from '@kici-dev/engine';
+/**
+ * Caches ContributorResolver results in an LRU cache.
+ *
+ * Cache key format: `{provider}:{repoFullName}:{username}`
+ * TTL: 15 minutes (configurable for testing).
+ */
+export declare class ContributorCache {
+    private readonly cache;
+    constructor(options?: {
+        ttlMs?: number;
+        maxEntries?: number;
+    });
+    /**
+     * Build the cache key from provider, repo, and username.
+     */
+    private buildKey;
+    /**
+     * Resolve contributor info, using cache when available.
+     *
+     * @param provider - Provider identifier (e.g. 'github')
+     * @param repoFullName - Full repo identifier (e.g. 'owner/repo')
+     * @param username - Contributor username
+     * @param resolver - ContributorResolver to call on cache miss
+     * @param credentials - Provider credentials for API calls
+     * @returns Cached or freshly resolved ContributorInfo
+     */
+    resolve(provider: string, repoFullName: string, username: string, resolver: ContributorResolver, credentials: unknown): Promise<ContributorInfo>;
+    /**
+     * Explicitly invalidate a cached entry.
+     *
+     * @returns 1 if an entry was present and deleted, 0 otherwise. Symmetric
+     * with the bulk invalidators so callers can accumulate a total.
+     */
+    invalidate(provider: string, repoFullName: string, username: string): number;
+    /**
+     * Invalidate every cached entry for a specific repository.
+     *
+     * Scans the LRU (bounded to `maxEntries`) and deletes entries whose key
+     * prefix matches `{provider}:{repoFullName}:`. Used when a webhook event
+     * signals a repo-wide permission change (e.g. GitHub `team.added_to_repository`
+     * / `team.removed_from_repository`) where every contributor's effective
+     * permission on that repo may have shifted.
+     *
+     * @returns Number of entries deleted.
+     */
+    invalidateByRepo(provider: string, repoFullName: string): number;
+    /**
+     * Invalidate every cached entry for a user across all repositories in an org.
+     *
+     * Scans the LRU and deletes entries whose key matches
+     * `{provider}:{orgLogin}/*:{username}`. Used when a webhook event signals
+     * that a user's membership in an org changed (e.g. GitHub `organization`,
+     * `membership` events), since any repo under that org could now return a
+     * different permission for the user.
+     *
+     * @returns Number of entries deleted.
+     */
+    invalidateByUserInOrg(provider: string, orgLogin: string, username: string): number;
+    /**
+     * Clear all cached entries. Useful for testing.
+     */
+    clear(): void;
+    /**
+     * Get the current number of cached entries.
+     */
+    get size(): number;
+}
+//# sourceMappingURL=contributor-cache.d.ts.map

package/dist/security/global-workflow-policy.d.ts

@@ -0,0 +1,72 @@
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+interface GlobalWorkflowPermission {
+    allowed: boolean;
+    reason?: string;
+}
+/**
+ * Org-level permission enforcement for global workflows.
+ *
+ * Three independent axes (each stored as a jsonb array of
+ * `{routingKey?, pattern}` entries on `org_settings`):
+ *
+ * - Workflow-repo allow-list (`global_workflow_allowed_repos`): which repos
+ *   may author global workflows. null/empty = any repo. Checked at
+ *   registration-extraction time and at dispatch time against the
+ *   REGISTRATION's repo (the repo that defined the workflow).
+ *
+ * - Source-repo deny-list (`global_workflow_denied_repos`): which repos
+ *   must never have global workflows run against their events (e.g., forks,
+ *   untrusted contrib repos). Checked at dispatch time against the EVENT's
+ *   repo (the repo that emitted the webhook).
+ *
+ * - Elevated access (`global_workflow_elevated_repos`): which workflow-
+ *   authoring repos can read source-repo secrets during execution.
+ *
+ * Each entry can optionally pin a `routingKey`, restricting the entry to
+ * one webhook source. An entry without a routing key applies to any source
+ * in the org. An entry whose routing key no longer matches any current
+ * source becomes a no-op (orphan, never matches) — by design, so deleting
+ * a source does not silently rebind its policy entries to an unrelated
+ * source.
+ */
+export declare class GlobalWorkflowPolicy {
+    private readonly db;
+    constructor(db: Kysely<Database>);
+    /**
+     * Check whether a workflow-authoring repository is allowed to register or
+     * dispatch global workflows. The workflow's own routing key is matched
+     * against each entry's optional `routingKey` qualifier.
+     *
+     * Decision flow:
+     * 1. No org_settings row or globally disabled → not allowed (opt-in).
+     * 2. allowed list null/empty → any repo allowed.
+     * 3. Entry matches when its `routingKey` is absent OR equals
+     *    `workflowRoutingKey`, AND its pattern matches the workflow repo.
+     * 4. Otherwise → not allowed.
+     */
+    isWorkflowRepoAllowed(workflowRoutingKey: string, workflowRepoIdentifier: string, customerId: string): Promise<GlobalWorkflowPermission>;
+    /**
+     * Check whether events from a source repository may trigger any global
+     * workflows. Each deny entry is matched against the EVENT's routing key
+     * (so a source-qualified deny only applies to that specific source).
+     *
+     * Decision flow:
+     * 1. No org_settings row or globally disabled → not allowed (opt-in).
+     * 2. denied list null/empty → allowed.
+     * 3. Any deny entry whose routing key (if set) equals the event's routing
+     *    key AND whose pattern matches the source repo → not allowed.
+     */
+    isSourceRepoAllowed(eventRoutingKey: string, sourceRepoIdentifier: string, customerId: string): Promise<GlobalWorkflowPermission>;
+    /**
+     * Check whether a workflow-authoring repository has elevated access (i.e.,
+     * may read source-repo secrets during execution). The workflow's routing
+     * key is matched against each entry's optional `routingKey` qualifier.
+     *
+     * Returns false if no org_settings row or the elevated list is null/empty.
+     */
+    isElevatedAccessAllowed(workflowRoutingKey: string, repoIdentifier: string, customerId: string): Promise<boolean>;
+    private getSettings;
+}
+export {};
+//# sourceMappingURL=global-workflow-policy.d.ts.map

package/dist/security/lock-source.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Lock-file branch selection for webhook processing.
+ *
+ * For pull-request events, the orchestrator must decide whether to fetch
+ * the workflow lock file from the PR head branch (the contributor's
+ * proposed change) or from the base branch (the protected target). Only
+ * trusted contributors get their HEAD lock evaluated; everyone else
+ * (unknown / known / undefined trust resolution) falls back to the base
+ * branch's lock so an untrusted contributor cannot inject triggers,
+ * jobs, or environment claims that the project's maintainers haven't
+ * vetted.
+ *
+ * The default for non-PR events is HEAD, because there is no untrusted
+ * "incoming" contribution to gate against — push events come directly
+ * from someone with write access.
+ */
+import type { TrustTier } from '@kici-dev/engine';
+/**
+ * Select which branch's lock file to fetch.
+ *
+ * Invariant (customer-isolation): for any pull-request event, an
+ * untrusted contributor (`tier === 'unknown' | 'known' | undefined`)
+ * MUST NOT have their HEAD lock file evaluated by the orchestrator.
+ * The base-branch lock — controlled by the project's trusted
+ * maintainers — is the source of truth for trigger evaluation,
+ * trust-tier-based environment access, and contributor-controlled
+ * fields that downstream secret resolution depends on.
+ *
+ * Only `tier === 'trusted'` (an identity-linked contributor with
+ * provider write+ permission AND ci_trust write+ permission, per
+ * `TrustResolver.resolveTrustTier`) can have their HEAD lock evaluated.
+ */
+export declare function selectLockFileSource(isPREvent: boolean, tier: TrustTier | undefined): 'head' | 'base';
+//# sourceMappingURL=lock-source.d.ts.map

package/dist/security/trust-resolver.d.ts

@@ -0,0 +1,108 @@
+/**
+ * TrustResolver -- combines identity links, RBAC ci_trust, and provider permissions
+ * into a trust tier decision.
+ *
+ * The TrustResolver is the core decision engine for CI security. It determines
+ * whether a contributor is trusted, known, or unknown based on:
+ * 1. Identity link lookup (provider username -> KiCI user ID)
+ * 2. ci_trust RBAC level for that user in the org
+ * 3. Provider API permission (via ContributorResolver + cache)
+ */
+import type { ContributorPermission, ContributorResolver } from '@kici-dev/engine';
+import type { TrustTier } from '@kici-dev/engine';
+import type { ContributorCache } from './contributor-cache.js';
+/**
+ * Match an identity link strictly by `(provider, providerUserId)`.
+ *
+ * Returns `null` whenever the numeric id is missing on either side or when no
+ * link's id matches the event's id. This is the strict end-state contract:
+ * username fallback is gone, mutable-username impersonation cannot grant
+ * trust, and a refused match is recorded under
+ * `kici_orch_trust_match_refused_no_id_total{reason}` so the rate of refusals
+ * stays observable.
+ *
+ * Pre-conditions for callers: Platform's reconcile job has filled
+ * `provider_user_id` for every row in `identity_links` (verified by the
+ * `kici_platform_identity_links_missing_provider_user_id` gauge being 0 for
+ * ≥4 cycles before this strict policy was deployed). See
+ * `.claude/plans/cryptic-jumping-narwhal.md` for the rollout journey.
+ */
+export declare function findIdentityLink(identityLinks: IdentityLink[], provider: string, providerUsername: string, providerUserId: string | undefined): IdentityLink | null;
+/** RBAC permission levels from the Platform permission system. */
+export type PermissionLevel = 'none' | 'read' | 'write' | 'admin';
+/** Identity link mapping a provider identity to a KiCI user. */
+export interface IdentityLink {
+    userId: string;
+    provider: string;
+    providerUsername: string;
+    /**
+     * Immutable IDP-side numeric id (e.g. GitHub's `sender.id`).
+     * Nullable during the backfill window for legacy rows that
+     * predate Platform migration 009. Trust resolver matches on
+     * this field first; once backfill completes the strict policy
+     * refuses trust when this is null.
+     */
+    providerUserId?: string | null;
+}
+/** Parameters for trust tier resolution. */
+interface TrustResolutionParams {
+    /** Sender username from the webhook event. */
+    providerUsername: string;
+    /**
+     * Sender immutable IDP-side numeric id from the webhook event (e.g.
+     * GitHub's `sender.id` coerced to string). Optional during the backfill
+     * window; the strict end-state refuses trust when this is missing.
+     */
+    providerUserId?: string;
+    /** Provider type (e.g. 'github'). */
+    provider: string;
+    /** Repository identifier (e.g. 'owner/repo'). */
+    repoIdentifier: string;
+    /** Whether the PR comes from a fork. */
+    isForkPR: boolean;
+    /** Organization ID this webhook routes to. */
+    orgId: string;
+    /** Cached identity links from Platform push. */
+    identityLinks: IdentityLink[];
+    /** ci_trust permission levels per user ID from Platform push. */
+    orgMemberPermissions: Map<string, PermissionLevel>;
+    /** Provider-specific contributor resolver. */
+    contributorResolver: ContributorResolver;
+    /** Credentials for provider API calls. */
+    credentials: unknown;
+}
+/** Result of trust tier resolution with full audit trail. */
+export interface TrustResolution {
+    tier: TrustTier;
+    contributorUsername: string;
+    identityLinked: boolean;
+    userId?: string;
+    providerPermission: ContributorPermission;
+    ciTrustLevel?: PermissionLevel;
+    reason: string;
+}
+/**
+ * TrustResolver combines identity links, ci_trust RBAC, and provider permissions
+ * into a trust tier.
+ *
+ * Decision matrix:
+ * 1. Fork PR -> always unknown
+ * 2. No identity link -> provider API fallback (never trusted)
+ *    - read+ -> known
+ *    - none -> unknown
+ * 3. Identity linked -> combine ci_trust + provider permission:
+ *    - provider write+ AND ci_trust write+ -> trusted
+ *    - provider write+ AND ci_trust none/read -> known
+ *    - provider read -> known
+ *    - provider none -> unknown
+ */
+export declare class TrustResolver {
+    private readonly contributorCache;
+    constructor(contributorCache: ContributorCache);
+    /**
+     * Resolve the trust tier for a contributor.
+     */
+    resolveTrustTier(params: TrustResolutionParams): Promise<TrustResolution>;
+}
+export {};
+//# sourceMappingURL=trust-resolver.d.ts.map

package/dist/security/workflow-diff.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Workflow modification detection.
+ *
+ * Compares base and head lock files to detect added, modified, or removed workflows.
+ * Used by the processor to flag workflow changes in PRs from non-trusted contributors.
+ */
+import type { LockFile } from '@kici-dev/engine';
+/** A single workflow modification detected between base and head lock files. */
+export interface WorkflowModification {
+    workflowName: string;
+    changeType: 'added' | 'modified' | 'removed';
+}
+/**
+ * Detect workflow modifications between base and head lock files.
+ *
+ * Compares workflow names and configurations:
+ * - Added: in head but not base
+ * - Removed: in base but not head
+ * - Modified: in both but triggers, jobs, or steps differ
+ *
+ * @param baseLockFile - Lock file from the base branch (null for new repos)
+ * @param headLockFile - Lock file from the head commit (null means nothing to detect)
+ * @returns List of detected modifications
+ */
+export declare function detectWorkflowModifications(baseLockFile: LockFile | null, headLockFile: LockFile | null): WorkflowModification[];
+//# sourceMappingURL=workflow-diff.d.ts.map

package/dist/server.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Platform-connected entry point for the customer orchestrator.
+ *
+ * Operates in 'platform' or 'hybrid' mode:
+ * - platform: receives webhooks ONLY via Platform WS relay
+ * - hybrid: receives webhooks via both WS relay and direct HTTP endpoint
+ *
+ * Both modes connect a PlatformClient to the Platform relay and run an agent WS server.
+ *
+ * Startup sequence follows packages/platform/src/server.ts pattern:
+ * config -> DB -> migrations -> provider registry -> dispatcher -> PlatformClient -> app -> HTTP -> heartbeat
+ *
+ * Graceful shutdown in reverse order:
+ * Platform client -> agent WS -> heartbeat -> HTTP -> DB
+ */
+export {};
+//# sourceMappingURL=server.d.ts.map