@kindgi/api 0.0.0-bootstrap.0 → 0.1.0

package/src/index.ts

@@ -0,0 +1,606 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+export { createApp } from './app.js';
+export type {
+  CreateAppInput,
+  OpenApiConfig,
+  ScalarDocsConfig,
+  SessionConfig,
+} from './app.js';
+export type { AppEnv } from './types.js';
+export {
+  SESSION_TOKEN_PREFIX,
+  encodeSessionToken,
+  MULTI_TENANT_LOOKUP,
+} from './middleware/auth.js';
+export type { TokenResolution, TokenResolver } from './middleware/auth.js';
+export type {
+  ClaimMappingScopesSpec,
+  ClaimMappingSpec,
+  IdentityProviderBinding,
+  IdentityProviderGetInput,
+  IdentityProviderKind,
+  IdentityProviderListInput,
+  IdentityProviderPage,
+  IdentityProviderRegisterInput,
+  IdentityProviderRegisterOutcome,
+  IdentityProviderUnregisterInput,
+  IdentityProviderUnregisterOutcome,
+  ProviderConfig,
+  ExchangeCodeFn,
+  ExchangeCodeInput,
+  ExchangeCodeOutcome,
+  RefreshTokenFn,
+  RefreshTokenInput,
+} from './identity-provider-binding.js';
+export type {
+  Session,
+  SessionCreateInput,
+  SessionCreateOutput,
+  SessionGetInput,
+  SessionListInput,
+  SessionPage,
+  SessionRevokeAllForUserInput,
+  SessionRevokeAllForUserOutcome,
+  SessionRevokeInput,
+  SessionRevokeOutcome,
+  SessionStoreBinding,
+  SessionTouchInput,
+  SessionTouchOutcome,
+} from './session-store-binding.js';
+export type {
+  IdentityDirectoryBinding,
+  IdentityGetUserInput,
+  IdentityListSessionsInput,
+  IdentityListUsersInput,
+  IdentityRevokeSessionsInput,
+  RevokeSessionsResult,
+  SessionSummary,
+  SessionSummaryPage,
+  UserCollectionPage,
+  UserRecord,
+} from './identity-directory-binding.js';
+export { createInMemoryOauthStateStore } from './state-store-binding.js';
+export type {
+  OauthStateEntry,
+  OauthStateStore,
+  OauthStateTakeInput,
+} from './state-store-binding.js';
+export {
+  createInMemoryIdempotencyStore,
+  idempotencyMiddleware,
+} from './middleware/idempotency.js';
+export type { IdempotencyStore, StoredIdempotencyEntry } from './middleware/idempotency.js';
+export { CURRENT_EVENT_BUS_ENVELOPE_VERSION } from './event-bus-binding.js';
+export type {
+  EventBusBinding,
+  EventBusError,
+  EventPayload,
+  SubscribeOptions,
+  Subscription,
+} from './event-bus-binding.js';
+export {
+  API_TOKEN_ROLES,
+  type ApiTokenRecord,
+  type ApiTokenRole,
+  type TokenAdmin,
+  type TokenGetInput,
+  type TokenListInput,
+  type TokenMintInput,
+  type TokenMintOutput,
+  type TokenRevokeInput,
+  type TokenRevokeOutcome,
+} from './token-admin.js';
+export type {
+  InvokeAgentBindingInput,
+  InvokeFlowBindingInput,
+  RunHandlerBinding,
+  RunHandlerFailure,
+  RunHandlerOutcome,
+} from './handler-binding.js';
+export type {
+  ReviewerBinding,
+  ReviewerGetInput,
+  ReviewerListInput,
+  ReviewerLookupInput,
+  ReviewerPage,
+  ReviewerRecord,
+  ReviewerRegisterInput,
+  ReviewerRegisterOutcome,
+  ReviewerRegistryBinding,
+  ReviewerUnregisterInput,
+  ReviewerUnregisterOutcome,
+} from './reviewer-binding.js';
+export type {
+  Approval,
+  ApprovalStatus,
+  HitlBinding,
+  HitlBindingError,
+  ListApprovalsBindingInput,
+  ListApprovalsBindingResult,
+  ReviewDecision,
+  ReviewDecisionKind,
+  ReviewDecisionRecord,
+  SubmitReviewBindingInput,
+  SubmitReviewBindingResult,
+} from './hitl-binding.js';
+export type {
+  BlobDeleteOutcome,
+  BlobError,
+  BlobFilter,
+  BlobListPage,
+  BlobMeta,
+  BlobPutInput,
+  BlobRead,
+  BlobStorageBinding,
+  MultipartInitiateInput,
+  MultipartListPartsPage,
+  S3ListPage,
+} from '@kindgi/blob-binding';
+export type { S3Credential, S3CredentialBinding } from './s3-credential-binding.js';
+export {
+  ADAPTER_KINDS,
+  ADAPTER_STATUSES,
+} from './adapter-binding.js';
+export type {
+  AdapterGetInput,
+  AdapterInfo,
+  AdapterKind,
+  AdapterListFilter,
+  AdapterListInput,
+  AdapterPage,
+  AdapterRegistryBinding,
+  AdapterStatus,
+  AdapterTestInput,
+  AdapterTestOutcome,
+} from './adapter-binding.js';
+export { TRIGGER_KINDS } from './trigger-binding.js';
+export {
+  DEFAULT_PUBLIC_RUN_TOKEN_TTL_SECONDS,
+  MAX_PUBLIC_RUN_TOKEN_RUNS,
+  MAX_PUBLIC_RUN_TOKEN_TTL_SECONDS,
+  PUBLIC_RUN_TOKEN_PREFIX,
+  mintPublicRunToken,
+  verifyPublicRunToken,
+} from './public-run-token.js';
+export type {
+  MintPublicRunTokenInput,
+  MintPublicRunTokenResult,
+  PublicRunTokenClaims,
+  PublicRunTokenConfig,
+  VerifyPublicRunTokenFailure,
+  VerifyPublicRunTokenResult,
+} from './public-run-token.js';
+export {
+  WEBHOOK_DELIVERY_STATUSES,
+  WEBHOOK_EVENT_TYPES,
+} from './webhook-endpoint-binding.js';
+export type {
+  FinishedRun,
+  RunFinishedEvent,
+  WebhookDelivery,
+  WebhookDeliveryListInput,
+  WebhookDeliveryListOutcome,
+  WebhookDeliveryOutcome,
+  WebhookDeliveryRef,
+  WebhookDeliveryStatus,
+  WebhookEndpoint,
+  WebhookEndpointBinding,
+  WebhookEndpointCreateInput,
+  WebhookEndpointCreateOutcome,
+  WebhookEndpointFilter,
+  WebhookEndpointListInput,
+  WebhookEndpointPage,
+  WebhookEndpointRef,
+  WebhookEndpointRefusal,
+  WebhookEndpointUpdateInput,
+  WebhookEndpointUpdateOutcome,
+  WebhookEvent,
+  WebhookEventType,
+  WebhookSecretRef,
+  WebhookTestEvent,
+} from './webhook-endpoint-binding.js';
+export type {
+  CronTriggerRecord,
+  EventTriggerRecord,
+  GetTriggerInput,
+  ListTriggersInput,
+  RegisterCronTriggerInput,
+  RegisterEventTriggerInput,
+  RegisterTriggerError,
+  RegisterTriggerInput,
+  RegisterWebhookTriggerInput,
+  TriggerKind,
+  TriggerLifecycleError,
+  TriggerLifecycleInput,
+  TriggerListPage,
+  TriggerRecord,
+  TriggerRegistryBinding,
+  UpdateCronTriggerInput,
+  UpdateEventTriggerInput,
+  UpdateTriggerError,
+  UpdateTriggerInput,
+  UpdateWebhookTriggerInput,
+  WebhookTriggerRecord,
+} from './trigger-binding.js';
+export type {
+  AgentGetInput,
+  AgentGetVersionInput,
+  AgentListInput,
+  AgentListVersionsInput,
+  AgentPage,
+  AgentPublishInput,
+  AgentPublishOutcome,
+  AgentRegistryBinding,
+  AgentReinstateVersionInput,
+  AgentReinstateVersionOutcome,
+  AgentUnregisterInput,
+  AgentUnregisterOutcome,
+} from './agent-binding.js';
+export type {
+  FlowGetInput,
+  FlowGetVersionInput,
+  FlowListInput,
+  FlowListVersionsInput,
+  FlowPage,
+  FlowPublishInput,
+  FlowPublishOutcome,
+  FlowRegistryBinding,
+  FlowReinstateVersionInput,
+  FlowReinstateVersionOutcome,
+  FlowUnregisterInput,
+  FlowUnregisterOutcome,
+} from './flow-binding.js';
+export type {
+  CapabilityDescriptor,
+  CapabilityGetInput,
+  CapabilityListInput,
+  CapabilityPage,
+  CapabilityRegistryBinding,
+} from './capability-binding.js';
+export type {
+  ProviderCapabilitiesForInput,
+  ProviderGetInput,
+  ProviderListInput,
+  ProviderPage,
+  ProviderRegisterInput,
+  ProviderRegisterOutcome,
+  ProviderRegistryBinding,
+  ProviderResolveForRuntimeInput,
+  ProviderRuntimeEntry,
+  ProviderSecretRef,
+  ProviderUnregisterInput,
+  ProviderUnregisterOutcome,
+} from './provider-binding.js';
+export { MCP_TRANSPORTS } from './mcp-endpoint-binding.js';
+export type {
+  MCPClientProbeBinding,
+  MCPClientProbeInput,
+  MCPEndpoint,
+  MCPEndpointConfig,
+  MCPEndpointGetInput,
+  MCPEndpointListInput,
+  MCPEndpointPage,
+  MCPEndpointRegisterInput,
+  MCPEndpointRegisterOutcome,
+  MCPEndpointRegistryBinding,
+  MCPEndpointUnregisterInput,
+  MCPEndpointUnregisterOutcome,
+  MCPGetPromptOutcome,
+  MCPHttpSseConfig,
+  MCPListPromptsOutcome,
+  MCPListResourcesOutcome,
+  MCPPromptArgument,
+  MCPPromptDescriptor,
+  MCPPromptMessage,
+  MCPReadResourceOutcome,
+  MCPResourceContent,
+  MCPResourceDescriptor,
+  MCPEndpointSecretRef,
+  MCPStdioConfig,
+  MCPStreamableHttpConfig,
+  MCPTransport,
+} from './mcp-endpoint-binding.js';
+export {
+  TENANT_HOST_ACCESS_LEVELS,
+  deniesHostReach,
+  parseTenantHostAccess,
+  stdioRefusal,
+} from './tenant-host-access.js';
+export type { HostReach, TenantHostAccess } from './tenant-host-access.js';
+export { POLICY_KINDS } from '@kindgi/policy-contract';
+export type {
+  Policy,
+  PolicyGetInput,
+  PolicyGetVersionInput,
+  PolicyKind,
+  PolicyListInput,
+  PolicyListVersionsInput,
+  PolicyPage,
+  PolicyPublishInput,
+  PolicyPublishOutcome,
+  PolicyRegistryBinding,
+  PolicyReinstateVersionInput,
+  PolicyReinstateVersionOutcome,
+  PolicyUnregisterInput,
+  PolicyUnregisterOutcome,
+  PolicyVersionPage,
+  PolicyVersionRow,
+} from '@kindgi/policy-contract';
+export { EVAL_KINDS } from './eval-suite-binding.js';
+export type {
+  EvalKind,
+  EvalSuite,
+  EvalSuiteGetInput,
+  EvalSuiteGetVersionInput,
+  EvalSuiteListInput,
+  EvalSuiteListVersionsInput,
+  EvalSuitePage,
+  EvalSuitePublishInput,
+  EvalSuitePublishOutcome,
+  EvalSuiteRegistryBinding,
+  EvalSuiteReinstateVersionInput,
+  EvalSuiteReinstateVersionOutcome,
+  EvalSuiteUnregisterInput,
+  EvalSuiteUnregisterOutcome,
+} from './eval-suite-binding.js';
+export { EVAL_RUN_STATUSES } from './eval-run-binding.js';
+export type {
+  AgentRef,
+  EvalRun,
+  EvalRunBinding,
+  EvalRunCancelInput,
+  EvalRunCancelOutcome,
+  EvalRunFilter,
+  EvalRunGetInput,
+  EvalRunListInput,
+  EvalRunPage,
+  EvalRunStartInput,
+  EvalRunStartOutcome,
+  EvalRunStatus,
+  FlowRef,
+} from './eval-run-binding.js';
+export {
+  createAccuracyDispatcher,
+  createInProcessEvalRunBinding,
+} from './eval-run-dispatcher.js';
+export type {
+  AccuracyDispatcherOptions,
+  DispatchContext,
+  DispatchResult,
+  EvalCase,
+  EvalGrader,
+  EvalGraderInput,
+  EvalGraderOutcome,
+  EvalRunDispatcher,
+  EvalRunSubjectInvokeInput,
+  EvalRunSubjectInvokeOutcome,
+  EvalSubjectInvoker,
+  InProcessEvalRunBindingOptions,
+} from './eval-run-dispatcher.js';
+export { COST_GROUP_DIMENSIONS } from './cost-binding.js';
+export type {
+  CostAggregateGroup,
+  CostAggregateInput,
+  CostAggregateResult,
+  CostBinding,
+  CostGetRecordInput,
+  CostGroupDimension,
+  CostListRecordsInput,
+  CostRecord,
+  CostRecordFilter,
+  CostRecordPage,
+} from './cost-binding.js';
+export type {
+  ToolGetInput,
+  ToolGetVersionInput,
+  ToolListInput,
+  ToolListVersionsInput,
+  ToolPage,
+  ToolPublishInput,
+  ToolPublishOutcome,
+  ToolRegistryBinding,
+  ToolReinstateVersionInput,
+  ToolReinstateVersionOutcome,
+  ToolResolveInput,
+  ToolResolveOutcome,
+  ToolUnregisterInput,
+  ToolUnregisterOutcome,
+  ToolVersionPage,
+} from './tool-binding.js';
+export type {
+  GuardrailGetInput,
+  GuardrailListInput,
+  GuardrailPage,
+  GuardrailRegisterInput,
+  GuardrailRegisterOutcome,
+  GuardrailRegistryBinding,
+  GuardrailUnregisterInput,
+  GuardrailUnregisterOutcome,
+} from './guardrail-binding.js';
+export type {
+  MemoryBinding,
+  MemoryFactPage,
+  MemoryGetFactInput,
+  MemoryListFactsInput,
+  MemoryRetrievalHit,
+  MemoryRetrieveInput,
+  MemoryRetrieveIntent,
+  MemoryRetrieveOutcome,
+  MemorySupersedeFactInput,
+  MemorySupersedeFactOutcome,
+  MemoryWriteFactInput,
+  MemoryWriteFactOutcome,
+} from './memory-binding.js';
+export type {
+  SupervisorApplyOutcome,
+  SupervisorApplyProposalInput,
+  SupervisorBinding,
+  SupervisorDraftOutcome,
+  SupervisorDraftProposalInput,
+  SupervisorDryRunOutcome,
+  SupervisorDryRunProposalInput,
+  SupervisorGetProposalInput,
+  SupervisorListProposalsInput,
+  SupervisorProposalPage,
+  SupervisorRollbackOutcome,
+  SupervisorRollbackProposalInput,
+  SupervisorSubmitReviewInput,
+  SupervisorSubmitReviewOutcome,
+  SupervisorWithdrawOutcome,
+  SupervisorWithdrawProposalInput,
+} from './supervisor-binding.js';
+export type {
+  FixProposal,
+  FixProposalStatus,
+  Observation,
+  ObservationStatus,
+  ObservedViolation,
+  PassCriterion,
+  PatternKind,
+  PatternRef,
+  PromptChange,
+  ProposedChange,
+  RetrievalChange,
+  RetrievalIntentShape,
+  SupervisorObservationPage,
+  SupervisorQueryObservationsInput,
+  SupervisorQueryObservationsOutcome,
+  ToolConfigChange,
+} from './supervisor-binding.js';
+export type {
+  Deployment,
+  DeploymentBinding,
+  DeploymentGetByImageDigestInput,
+  DeploymentGetInput,
+  DeploymentListInput,
+  DeploymentPage,
+  DeployedPrimitive,
+  DeploymentContents,
+  DeploymentPrimitiveCounts,
+  DeploymentRegisterInput,
+  DeploymentRegisterOutcome,
+} from './deployment-binding.js';
+export type {
+  ImageBlobDescriptor,
+  ImageDescriptor,
+  ImageExtractFileInput,
+  ImageFile,
+  ImageHeadInput,
+  ImageLayerDescriptor,
+  ImagePlatform,
+  ImagePushInput,
+  ImagePushOutcome,
+  ImageRegistryBinding,
+  ImageRegistryError,
+} from './image-registry-binding.js';
+export type {
+  AddTrustedInput,
+  AddTrustedOutcome,
+  GetTrustedInput,
+  IsTrustedInput,
+  ListTrustedInput,
+  RevokeTrustedInput,
+  RevokeTrustedOutcome,
+  SigningKeyBinding,
+  SigningKeyError,
+  TrustedKey,
+  TrustedKeyPage,
+  VerifyInput,
+  VerifyOutcome,
+} from './signing-key-binding.js';
+export type {
+  EnvBinding,
+  EnvDeleteInput,
+  EnvDeleteOutcome,
+  EnvError,
+  EnvGetInput,
+  EnvListInput,
+  EnvListPage,
+  EnvRecord,
+  EnvResolveInput,
+  EnvResolveOutcome,
+  EnvSetInput,
+  EnvSetOutcome,
+  ResolveContext,
+} from './env-binding.js';
+export type {
+  SecretBinding,
+  SecretError,
+  SecretGetInput,
+  SecretGetVersionInput,
+  SecretListInput,
+  SecretListPage,
+  SecretListVersionsInput,
+  SecretRecord,
+  SecretResolveInput,
+  SecretResolveOutcome,
+  SecretRevokeInput,
+  SecretRevokeOutcome,
+  SecretRotateInput,
+  SecretRotateOutcome,
+  SecretSetInput,
+  SecretSetOutcome,
+  SecretVersionPage,
+  SecretVersionRecord,
+} from './secrets-binding.js';
+export { RESERVED_SECRET_NAME_PREFIX } from './secrets-binding.js';
+export type {
+  ListProvenanceRecordsInput,
+  ListProvenanceRecordsResult,
+  ProvenanceBinding,
+  ProvenanceBindingError,
+  ProvenanceListCursor,
+  ProvenanceRecordSummary,
+} from './provenance-binding.js';
+export type { KeyManagementBinding, KmsError } from './key-management-binding.js';
+export { createInMemoryRotationStatusStore } from './rotation-status-store.js';
+export type {
+  RotationStatus,
+  RotationStatusCreateInput,
+  RotationStatusGetInput,
+  RotationStatusStore,
+  RotationStatusSubscribeInput,
+  RotationStatusUpdateInput,
+} from './rotation-status-store.js';
+export type {
+  SecretProviderBinding,
+  SecretProviderDeleteInput,
+  SecretProviderDeleteOutput,
+  SecretProviderError,
+  SecretProviderGetInput,
+  SecretProviderGetVersionInput,
+  SecretProviderListInput,
+  SecretProviderListOutput,
+  SecretProviderMetadata,
+  SecretProviderPayload,
+  SecretProviderProbeOutput,
+  SecretProviderPutInput,
+  SecretProviderPutOutput,
+  SecretProviderRotateInput,
+  SecretProviderRotateOutput,
+  SecretProviderScope,
+} from './secrets-provider-binding.js';
+export { statusFor, toWireError, ERROR_CODE_TO_STATUS } from './errors.js';
+export type { WireError, WireErrorBody } from './errors.js';
+export { generateOpenApiDocument } from './openapi/generate.js';
+export type { GenerateOptions, OpenApiInfo, OpenApiServer } from './openapi/generate.js';
+export { OPERATIONS, honoToOpenapiPath } from './openapi/operations.js';
+export type {
+  OperationSpec,
+  ParameterSpec,
+  ResponseSpec,
+  HttpMethod,
+} from './openapi/operations.js';
+export { COMPONENT_SCHEMAS } from './openapi/schemas.js';
+export type { JsonSchema } from './openapi/schemas.js';
+
+export type {
+  RetentionBinding,
+  RetentionScheduledInput,
+  RetentionScheduledItem,
+  RetentionScheduledPage,
+  RetentionSweepInput,
+  RetentionSweepResult,
+} from './retention-binding.js';

package/src/key-management-binding.ts

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Result } from '@kindgi/types';
+
+/**
+ * Caller-plugged Key Management surface consumed by envelope-encryption
+ * secret stores. The framework never talks to a KMS directly — every
+ * wrap / unwrap / rewrap / destroy flows through this interface so a
+ * deployment can choose a local key (dev + CI) or a managed KMS without
+ * changing any framework code.
+ *
+ * The four load-bearing operations are `generateDek` (write path),
+ * `unwrap` (read path), `rewrap` (KEK rotation batch job), and
+ * `destroyDek` (cryptographic-erasure primitive backing
+ * `SecretBinding.revoke({ hard: true })`). `probe` is a boot-time
+ * reachability check the runtime runs before serving requests; a
+ * failing probe fails boot fast so a mis-configured KMS never manifests
+ * as a `secret-decryption-failed` at request time.
+ */
+export interface KeyManagementBinding {
+  /**
+   * Diagnostic identifier for the concrete KMS adapter. Emitted as
+   * `kms-provider` on every compliance-evidence event so auditors can
+   * filter `kms-provider = 'libsodium'` to find dev-shape leakage into
+   * regulated deployments.
+   */
+  readonly providerName: string;
+
+  /**
+   * Generate a fresh Data Encryption Key + wrap it with the current KEK.
+   * Returns the raw DEK (for immediate use in AES-GCM encryption; caller
+   * MUST discard after encrypting), the wrapped bytes (persisted
+   * alongside ciphertext), and the KEK id used (persisted for later
+   * unwrap even after rotation).
+   */
+  generateDek(): Promise<Result<{ dek: Uint8Array; wrapped: Uint8Array; kekId: string }, KmsError>>;
+
+  /** Unwrap a previously-wrapped DEK using the KEK it was wrapped with. */
+  unwrap(input: {
+    readonly kekId: string;
+    readonly wrapped: Uint8Array;
+  }): Promise<Result<Uint8Array, KmsError>>;
+
+  /**
+   * Rewrap a DEK from an old KEK to a new one. Used by the KEK-rotation
+   * batch job — the DEK itself does NOT change (no ciphertext rewrite),
+   * only its wrapping.
+   */
+  rewrap(input: {
+    readonly oldKekId: string;
+    readonly newKekId: string;
+    readonly wrapped: Uint8Array;
+  }): Promise<Result<Uint8Array, KmsError>>;
+
+  /**
+   * Destroy a specific DEK — cryptographic-erasure primitive backing
+   * `SecretBinding.revoke({ hard: true })`. Semantics vary by provider
+   * (scheduled key deletion, key-version destruction, ...). An adapter
+   * that wraps with a local key cannot destroy an already-wrapped DEK in
+   * isolation (the KEK is what would need destruction); it returns
+   * `{ destroyed: true }` and relies on the caller having dropped the
+   * ciphertext + wrapped bytes. Idempotent —
+   * returns `{ destroyed: false }` if the KMS reports the DEK is
+   * already gone.
+   */
+  destroyDek(input: {
+    readonly kekId: string;
+    readonly wrapped: Uint8Array;
+  }): Promise<Result<{ destroyed: boolean }, KmsError>>;
+
+  /**
+   * Health check called at boot. Returns latency for observability.
+   * A failing probe fails boot fast so a KMS
+   * misconfiguration surfaces at deploy time, not at request time.
+   */
+  probe(): Promise<
+    Result<{ reachable: true; providerVersion: string; latencyMs: number }, KmsError>
+  >;
+}
+
+export type KmsError =
+  | { readonly code: 'kms-unreachable'; readonly message: string; readonly cause?: unknown }
+  | { readonly code: 'kms-unauthorized'; readonly message: string; readonly cause?: unknown }
+  | {
+      readonly code: 'kms-key-not-found';
+      readonly message: string;
+      readonly kekId: string;
+    }
+  | { readonly code: 'kms-wrap-failed'; readonly message: string; readonly cause?: unknown }
+  | { readonly code: 'kms-unwrap-failed'; readonly message: string; readonly cause?: unknown };