@kindgi/compliance 0.0.0-bootstrap.0 → 0.1.0

package/package.json

@@ -1,7 +1,53 @@
 {
   "name": "@kindgi/compliance",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder so a trusted publisher can be attached. Releases are published from https://github.com/kindgi/kindgi-sdk with provenance; use 0.1.0 or later.",
+  "version": "0.1.0",
+  "description": "Kindgi™ compliance evidence contract. Types for the Evidence wire record and its sub-types (EvidenceActor, EvidenceSubject, EvidenceKind, EvidenceOutcome, EvidencePayload, EvidenceSignature, ProvenanceRef, ActorKind; ComplianceEvidence alias), the ComplianceProvider seam (EmitEvidenceInput, ListEvidenceFilter, EvidenceSigner), the ComplianceEvidenceGenerator interface with its inputs (RecordFromRunOptions, RunEvidenceContext, ModelCallSummary, ToolInvocationSummary, GuardrailResultSummary), EvidenceFilter, EvidencePage, SignedEvidenceBundle and EvidenceBundleBody, the classifier file format (ComplianceClassifierFile, Classification, LoadedClassifier), and the ComplianceError union. Runtime exports: the EVIDENCE_KINDS list, the pure auditEventToEvidence transform, and emitResolveEvent / emitLifecycleEvent, which append env-* and secret-* audit events to an AuditEventBinding. The generator implementation and the classifier loader are provided by the Kindgi runtime or by the caller.",
   "license": "Apache-2.0",
-  "repository": { "type": "git", "url": "git+https://github.com/kindgi/kindgi-sdk.git" }
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kindgi/kindgi-sdk.git",
+    "directory": "packages/compliance"
+  },
+  "homepage": "https://github.com/kindgi/kindgi-sdk/tree/main/packages/compliance#readme",
+  "bugs": {
+    "url": "https://github.com/kindgi/kindgi-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@kindgi/audit-events": "0.1.0",
+    "@kindgi/platform": "0.1.0",
+    "@kindgi/types": "0.1.0"
+  },
+  "devDependencies": {
+    "@kindgi/specs": "0.1.0",
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}

package/src/classifier.ts

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Per-kind classification decision. The retention + signing + export
+ * behavior for one event kind. Loaded from a classifier JSON file at
+ * deployment boot; consumed by retention cleanup and signed export.
+ */
+export interface Classification {
+  readonly retention: {
+    /**
+     * Baseline retention in days. Rows older than this are eligible
+     * for deletion UNLESS `legalHold` is set OR `onDenyDays` is set
+     * and applies.
+     */
+    readonly days: number;
+    /**
+     * When set, denied/failed variants of this kind are retained
+     * longer than the baseline. Security investigations often need
+     * denials retained past the operational rows. Only meaningful
+     * for kinds that carry a deny signal (authz-decision:
+     * `allowed=false`).
+     */
+    readonly onDenyDays?: number;
+    /**
+     * When true, retention cleanup NEVER deletes rows of this kind.
+     * Legal-hold semantics — deletion requires operator action past
+     * this classifier. Overrides `days`.
+     */
+    readonly legalHold?: boolean;
+  };
+  /**
+   * Kinds that get Ed25519-signed at export time when a regulator
+   * bundle is generated. Signatures are byte-exact over canonical
+   * event bytes; the classifier doesn't hold the key, only the
+   * decision to sign.
+   */
+  readonly signed: boolean;
+  /**
+   * Kinds included in regulator-facing signed export bundles.
+   * Non-exportable kinds stay out of the bundle regardless of
+   * signature policy.
+   */
+  readonly exportable: boolean;
+}
+
+/** Wire schema for the classifier JSON file. Versioned envelope. */
+export interface ComplianceClassifierFile {
+  readonly version: 1;
+  /** Default classification for kinds not explicitly listed. */
+  readonly default: Classification;
+  /** Per-kind overrides. Missing kind → `default`. */
+  readonly byKind: Readonly<Record<string, Classification>>;
+}
+
+/**
+ * Loaded classifier — same shape as the file, but the `resolve` helper
+ * returns the correct classification (per-kind or default) in one call.
+ *
+ * Built from a `ComplianceClassifierFile` by the runtime's loader or by
+ * the caller; deployments pass it to `@kindgi/api` as
+ * `CreateAppInput.complianceClassifier`. This package only defines the
+ * shape.
+ */
+export interface LoadedClassifier {
+  readonly file: ComplianceClassifierFile;
+  /** Return the classification for the given event kind. */
+  resolve(kind: string): Classification;
+}

package/src/errors.ts

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { ProjectId, Result, SigningKeyId } from '@kindgi/types';
+
+import type { Evidence } from './types.js';
+
+/**
+ * Errors emitted by the compliance surface. Every variant carries a `code`
+ * for pattern matching; messages are human-readable, not API contract.
+ */
+export type ComplianceError =
+  | InvalidEvidenceError
+  | PersistenceError
+  | SignerFailureError
+  | SigningKeyMissingError
+  | SigningFailureError
+  | InvalidCursorError
+  | ProjectNotFoundError
+  | UnsupportedVersionError;
+
+/**
+ * Structural validation of an evidence record against the compliance
+ * schema failed — e.g. `generator.recordFromRun` assembled a record that
+ * doesn't match the wire schema. A caller-shape bug or a schema drift,
+ * never a persistence issue.
+ */
+export interface InvalidEvidenceError {
+  readonly code: 'invalid-evidence';
+  readonly message: string;
+  readonly issues: readonly { readonly path: string; readonly message: string }[];
+}
+
+/**
+ * The caller-plugged persistence binding threw or returned an error.
+ */
+export interface PersistenceError {
+  readonly code: 'persistence-error';
+  readonly message: string;
+  readonly cause: unknown;
+}
+
+/**
+ * A caller-plugged `EvidenceSigner` function threw. Distinct from
+ * `SigningFailureError` (which is specific to the generator's own
+ * Ed25519 signing path, e.g. `exportSigned`) so callers can distinguish
+ * the two signing paths.
+ */
+export interface SignerFailureError {
+  readonly code: 'signer-failure';
+  readonly message: string;
+  readonly cause: unknown;
+}
+
+/**
+ * The caller asked for a signed export but the requested `SigningKeyId`
+ * has no material in the mounted `SigningKeyBinding`. Typically a
+ * misconfiguration.
+ */
+export interface SigningKeyMissingError {
+  readonly code: 'signing-key-missing';
+  readonly message: string;
+  readonly signingKeyId: SigningKeyId;
+}
+
+/**
+ * The Ed25519 signing primitive itself rejected the material — malformed
+ * key bytes, wrong length, or an underlying primitive that refused the
+ * input.
+ */
+export interface SigningFailureError {
+  readonly code: 'signing-failure';
+  readonly message: string;
+  readonly signingKeyId: SigningKeyId;
+  readonly cause: unknown;
+}
+
+/**
+ * An evidence listing received a `cursor` that isn't decodable to a
+ * `(timestamp, id)` pair. Almost always a client bug.
+ */
+export interface InvalidCursorError {
+  readonly code: 'invalid-cursor';
+  readonly message: string;
+}
+
+/**
+ * An evidence write (`recordFromRun`, `ComplianceProvider.emit`) named a
+ * `projectId` that doesn't exist inside the tenant. Distinct from
+ * `PersistenceError` so the API layer can map the caller-shape bug to a
+ * 404 wire response rather than 500.
+ */
+export interface ProjectNotFoundError {
+  readonly code: 'project-not-found';
+  readonly message: string;
+  readonly projectId: ProjectId;
+}
+
+/**
+ * A record read from storage carried a `payload.version` newer than this
+ * reader knows how to normalize — typically during a rolling deploy.
+ */
+export interface UnsupportedVersionError {
+  readonly code: 'unsupported-version';
+  readonly message: string;
+  readonly version: number;
+  readonly evidenceId: string;
+}
+
+export type EmitResult = Result<Evidence, ComplianceError>;
+export type ListResult = Result<readonly Evidence[], ComplianceError>;

package/src/generator.ts

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { AuditEvent } from '@kindgi/audit-events';
+import type { ComplianceEvidenceId, Result, RunId, SigningKeyId, TenantId } from '@kindgi/types';
+
+import type { ComplianceError } from './errors.js';
+import type {
+  ComplianceEvidence,
+  EvidenceFilter,
+  EvidenceOutcome,
+  EvidencePayload,
+  RecordFromRunOptions,
+  SignedEvidenceBundle,
+} from './types.js';
+
+/**
+ * The runtime service that turns terminated runs into audit-event
+ * records and produces signed export bundles.
+ *
+ * Public interface — deployments plug an implementation into
+ * `@kindgi/api` via `CreateAppInput.complianceGenerator`. The Kindgi
+ * runtime provides one; callers may supply their own. Implementations
+ * may expose additional subscription / auto-emit methods; this interface
+ * is the minimum surface `@kindgi/api` consumes.
+ */
+export interface ComplianceEvidenceGenerator {
+  recordFromRun(
+    options: RecordFromRunOptions,
+  ): Promise<Result<{ readonly evidenceId: ComplianceEvidenceId }, ComplianceError>>;
+
+  exportSigned(
+    tenantId: TenantId,
+    filter: EvidenceFilter,
+    signingKeyId: SigningKeyId,
+  ): Promise<Result<SignedEvidenceBundle, ComplianceError>>;
+
+  describe(): { readonly name: string; readonly version: string };
+}
+
+/**
+ * Materialize a `ComplianceEvidence` wire record from an `AuditEvent`.
+ * The bundle body carries `ComplianceEvidence[]` for wire-shape
+ * stability — regulators verifying bundles read one record shape
+ * regardless of how events are stored.
+ *
+ * Pure function — no I/O, no random. Safe to call from any layer.
+ */
+export function auditEventToEvidence(event: AuditEvent): ComplianceEvidence {
+  return {
+    id: event.id as ComplianceEvidenceId,
+    tenantId: event.tenantId,
+    // Tenant-level events carry no project; the key is omitted, never `undefined`.
+    ...(event.projectId !== undefined && { projectId: event.projectId }),
+    kind: event.kind,
+    timestamp: event.timestamp,
+    payload: extractDoc(event.payload) as EvidencePayload,
+    ...(event.outcome !== undefined && { outcome: event.outcome as EvidenceOutcome }),
+    ...(event.runId !== undefined && { provenanceRef: { runId: event.runId as RunId } }),
+  };
+}
+
+function extractDoc(payload: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>> {
+  const inner = payload.doc;
+  if (inner !== null && typeof inner === 'object' && !Array.isArray(inner)) {
+    return inner as Readonly<Record<string, unknown>>;
+  }
+  return payload;
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+// ============ Wire types ============
+export { EVIDENCE_KINDS } from './types.js';
+export type {
+  ActorKind,
+  ComplianceEvidence,
+  ComplianceProvider,
+  EmitEvidenceInput,
+  Evidence,
+  EvidenceActor,
+  EvidenceKind,
+  EvidenceOutcome,
+  EvidencePayload,
+  EvidenceSignature,
+  EvidenceSigner,
+  EvidenceSubject,
+  ListEvidenceFilter,
+  ProvenanceRef,
+} from './types.js';
+
+// ============ Pipeline data types ============
+export type {
+  EvidenceBundleBody,
+  EvidenceFilter,
+  EvidencePage,
+  GuardrailResultSummary,
+  ModelCallSummary,
+  RecordFromRunOptions,
+  RunEvidenceContext,
+  SignedEvidenceBundle,
+  ToolInvocationSummary,
+} from './types.js';
+
+// ============ Errors ============
+export type {
+  ComplianceError,
+  EmitResult,
+  InvalidCursorError,
+  InvalidEvidenceError,
+  ListResult,
+  PersistenceError,
+  ProjectNotFoundError,
+  SignerFailureError,
+  SigningFailureError,
+  SigningKeyMissingError,
+  UnsupportedVersionError,
+} from './errors.js';
+
+// ============ Classifier ============
+export type {
+  Classification,
+  ComplianceClassifierFile,
+  LoadedClassifier,
+} from './classifier.js';
+
+// ============ Generator interface + pure transform ============
+export type { ComplianceEvidenceGenerator } from './generator.js';
+export { auditEventToEvidence } from './generator.js';
+
+// ============ Resolve + lifecycle event emitters ============
+export { emitLifecycleEvent, emitResolveEvent } from './resolve-emit.js';
+export type {
+  EmitLifecycleEventInput,
+  EmitResolveEventInput,
+  ResolveContext,
+} from './resolve-emit.js';

package/src/resolve-emit.ts

@@ -0,0 +1,256 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Shared helpers for emitting `env-*` and `secret-*` audit events.
+ * `EnvBinding` and `SecretBinding` implementations call
+ * `emitResolveEvent` from their `resolve` paths and `emitLifecycleEvent`
+ * for `set` / `delete` / `rotate` / `revoke`.
+ *
+ * Writes land on the single `AuditEventBinding`. Classification
+ * (retention / signing / export) is a lens on top, not baked into the
+ * write path.
+ *
+ * Design guardrails:
+ *   - Framework NEVER copies a secret plaintext `value` into a payload.
+ *     Payloads carry only metadata (name, version, scope,
+ *     caller, errorCode).
+ *   - Emission is fire-and-forget: failures inside the binding are
+ *     logged (via `console.warn`) but never poison the caller's op.
+ *   - The `resolveContext.caller` discriminant maps to a distinct
+ *     `actor` string.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import type { AuditEvent, AuditEventBinding } from '@kindgi/audit-events';
+import type { Scope } from '@kindgi/platform';
+import type { EnvName, ProjectId, TenantId, Timestamp } from '@kindgi/types';
+
+/**
+ * Uniform caller-of-resolution shape. Structurally identical to
+ * `@kindgi/api.ResolveContext` (kept as a duplicate declaration here
+ * to avoid a compliance → api dep cycle — TS structural typing
+ * makes them assignable across the boundary).
+ */
+export interface ResolveContext {
+  readonly runId?: string;
+  readonly deploymentId?: string;
+  readonly nodeId?: string;
+  readonly caller: 'dispatch' | 'deploy-sync' | 'admin-cli' | 'boot-bridge';
+}
+
+/** Input to `emitResolveEvent`. */
+export interface EmitResolveEventInput {
+  readonly kind: 'env' | 'secret';
+  readonly scope: Scope;
+  readonly envName: EnvName;
+  readonly name: string;
+  readonly outcome: 'succeeded' | 'failed';
+  readonly resolveContext: ResolveContext;
+  readonly version?: number;
+  readonly errorCode?: string;
+  readonly auditEvents: AuditEventBinding;
+  readonly tenantId: TenantId;
+  readonly projectId: ProjectId;
+}
+
+/**
+ * Emit an `env-resolved` or `secret-resolved` audit event.
+ *
+ * The helper NEVER accepts nor emits the resolved value — the resolve
+ * outcome carries the plaintext to the caller; the audit event carries
+ * only the fact-of-resolution + version + scope + caller attribution.
+ *
+ * Fire-and-forget: any error is logged but swallowed. The resolve path
+ * must not fail because the audit sink is unreachable.
+ */
+export async function emitResolveEvent(input: EmitResolveEventInput): Promise<void> {
+  const kind = input.kind === 'env' ? 'env-resolved' : 'secret-resolved';
+  const payload = buildResolvePayload(input);
+  const actor = actorFromResolveContext(input.resolveContext);
+  const event = buildEvent({
+    tenantId: input.tenantId,
+    projectId: input.projectId,
+    kind,
+    outcome: input.outcome,
+    actor,
+    runId: input.resolveContext.runId,
+    payload,
+  });
+  await safeEmit(input.auditEvents, event);
+}
+
+/**
+ * Input to `emitLifecycleEvent`. Used for env `set` / `delete` and
+ * secret `set` / `rotate` / `revoke` — the non-resolve write ops that
+ * still need audit-trail attribution.
+ */
+export interface EmitLifecycleEventInput {
+  readonly evidenceKind: string;
+  readonly bindingKind: 'env' | 'secret';
+  readonly scope: Scope;
+  readonly envName: EnvName;
+  readonly name: string;
+  readonly outcome: 'succeeded' | 'failed';
+  /**
+   * Caller-of-op attribution. Same shape as the resolve path — env
+   * `set` from an admin CLI produces `actor = 'admin'`; a
+   * deployment-sync `set` produces `actor = 'system:<deploymentId>'`.
+   */
+  readonly resolveContext?: ResolveContext;
+  readonly version?: number;
+  readonly previousVersion?: number;
+  readonly errorCode?: string;
+  readonly hard?: boolean;
+  readonly reason?: string;
+  readonly auditEvents: AuditEventBinding;
+  readonly tenantId: TenantId;
+  readonly projectId: ProjectId;
+}
+
+/**
+ * Emit a non-resolve lifecycle event (`env-set` / `env-deleted` /
+ * `secret-set` / `secret-rotated` / `secret-rotation-started` /
+ * `secret-rotation-failed` / `secret-revoked` / `secret-hard-revoked`).
+ * Same fire-and-forget contract as `emitResolveEvent`.
+ */
+export async function emitLifecycleEvent(input: EmitLifecycleEventInput): Promise<void> {
+  const payload = buildLifecyclePayload(input);
+  const actor =
+    input.resolveContext !== undefined ? actorFromResolveContext(input.resolveContext) : undefined;
+  const event = buildEvent({
+    tenantId: input.tenantId,
+    projectId: input.projectId,
+    kind: input.evidenceKind,
+    outcome: input.outcome,
+    actor,
+    runId: input.resolveContext?.runId,
+    payload,
+  });
+  await safeEmit(input.auditEvents, event);
+}
+
+// -----------------------------------------------------------------------------
+// Internals
+// -----------------------------------------------------------------------------
+
+interface BuildEventInput {
+  readonly tenantId: TenantId;
+  readonly projectId: ProjectId;
+  readonly kind: string;
+  readonly outcome: string;
+  readonly actor: string | undefined;
+  readonly runId: string | undefined;
+  readonly payload: Readonly<Record<string, unknown>>;
+}
+
+function buildEvent(input: BuildEventInput): AuditEvent {
+  return {
+    id: randomUUID(),
+    tenantId: input.tenantId,
+    projectId: input.projectId,
+    kind: input.kind,
+    timestamp: new Date().toISOString() as unknown as Timestamp,
+    actor: input.actor ?? 'user:system',
+    outcome: input.outcome,
+    ...(input.runId !== undefined && { runId: input.runId }),
+    payload: { v: 1, doc: input.payload },
+  };
+}
+
+async function safeEmit(binding: AuditEventBinding, event: AuditEvent): Promise<void> {
+  try {
+    const result = await binding.append([event]);
+    if (result.kind === 'err') {
+      // eslint-disable-next-line no-console -- no injected logger here
+      console.warn(`[compliance] emit ${event.kind} audit event failed: ${result.error.message}`);
+    }
+  } catch (cause) {
+    // eslint-disable-next-line no-console -- no injected logger here
+    console.warn(
+      `[compliance] emit ${event.kind} audit event threw: ${
+        cause instanceof Error ? cause.message : String(cause)
+      }`,
+    );
+  }
+}
+
+/**
+ * Map the `resolveContext.caller` discriminant to a subject string.
+ * Format matches the audit-events `actor` convention
+ * (`<type>:<id>` — `agent:<runId>`, `system:<deploymentId>`, `user:admin`,
+ * `user:system`).
+ */
+function actorFromResolveContext(ctx: ResolveContext): string | undefined {
+  switch (ctx.caller) {
+    case 'dispatch':
+      return ctx.runId !== undefined ? `agent:${ctx.runId}` : 'agent:unknown';
+    case 'deploy-sync':
+      return ctx.deploymentId !== undefined ? `system:${ctx.deploymentId}` : 'system:deploy';
+    case 'admin-cli':
+      return 'user:admin';
+    case 'boot-bridge':
+      return 'user:system';
+    default:
+      return undefined;
+  }
+}
+
+function scopeToPayloadShape(scope: Scope): Readonly<Record<string, unknown>> {
+  if (scope.kind === 'tenant') {
+    return { kind: 'tenant', tenantId: scope.tenantId as unknown as string };
+  }
+  if (scope.kind === 'org') {
+    return {
+      kind: 'org',
+      tenantId: scope.tenantId as unknown as string,
+      orgId: scope.orgId as unknown as string,
+    };
+  }
+  return {
+    kind: 'project',
+    tenantId: scope.tenantId as unknown as string,
+    projectId: scope.projectId as unknown as string,
+  };
+}
+
+/**
+ * Build the resolve-event payload. Structural guarantee: NO `value`
+ * key ever appears. Every field is either metadata (name,
+ * version, scope) or attribution (caller, errorCode).
+ */
+function buildResolvePayload(input: EmitResolveEventInput): Readonly<Record<string, unknown>> {
+  const payload: Record<string, unknown> = {
+    scope: scopeToPayloadShape(input.scope),
+    envName: input.envName as unknown as string,
+    name: input.name,
+    caller: input.resolveContext.caller,
+  };
+  if (input.version !== undefined) payload.recordVersion = input.version;
+  if (input.errorCode !== undefined) payload.errorCode = input.errorCode;
+  if (input.resolveContext.nodeId !== undefined) payload.nodeId = input.resolveContext.nodeId;
+  if (input.resolveContext.runId !== undefined) payload.runId = input.resolveContext.runId;
+  return payload;
+}
+
+/**
+ * Build the lifecycle-event payload. Same structural rule as
+ * `buildResolvePayload` — never carries the value.
+ */
+function buildLifecyclePayload(input: EmitLifecycleEventInput): Readonly<Record<string, unknown>> {
+  const payload: Record<string, unknown> = {
+    scope: scopeToPayloadShape(input.scope),
+    envName: input.envName as unknown as string,
+    name: input.name,
+  };
+  if (input.resolveContext !== undefined) payload.caller = input.resolveContext.caller;
+  if (input.version !== undefined) payload.recordVersion = input.version;
+  if (input.previousVersion !== undefined) payload.previousVersion = input.previousVersion;
+  if (input.errorCode !== undefined) payload.errorCode = input.errorCode;
+  if (input.hard !== undefined) payload.hard = input.hard;
+  if (input.reason !== undefined) payload.reason = input.reason;
+  if (input.resolveContext?.nodeId !== undefined) payload.nodeId = input.resolveContext.nodeId;
+  if (input.resolveContext?.runId !== undefined) payload.runId = input.resolveContext.runId;
+  return payload;
+}