@fabricorg/platform 1.9.0 → 1.10.1

package/dist/index-BXpeFdk2.d.ts

@@ -0,0 +1,190 @@
+//#region privacy/engine.d.ts
+declare const ANONYMIZATION_POLICY_VERSION = "adr-026-platform-anonymization-v1";
+type JsonObject = Record<string, unknown>;
+interface AnonymizationFieldPolicy {
+  method: RedactionMethod;
+  match: "key" | "path";
+  value: string;
+}
+interface AnonymizationPolicy {
+  fields: readonly AnonymizationFieldPolicy[];
+  preservedSemantics?: readonly string[];
+}
+interface AssetEventLike {
+  id: string;
+  tenantId: string;
+  spaceId: string;
+  eventType: string;
+  subjectType: string;
+  subjectId: string;
+  actionInvocationId: string;
+  payload: unknown;
+  sequence: number;
+  occurredAt: Date;
+  recordedAt: Date;
+  correlationId: string;
+  causationId?: string | null;
+}
+interface EvidencePacketLike {
+  id: string;
+  packet: unknown;
+  redactionMetadata: unknown;
+  checksum: string;
+}
+interface AnonymizationLifecycleEvidence {
+  eventType: "AnonymizationApplied";
+  policyVersion: string;
+  jobId: string;
+  reason: string;
+  appliedAt: string;
+  tenantId: string;
+  spaceId: string | null;
+  counts: {
+    assetEvents: number;
+    readModels: number;
+    evidencePackets: number;
+    redactedFields: number;
+  };
+  records: Array<{
+    recordClass: PlatformDataClass;
+    recordId: string;
+    subjectType?: string;
+    subjectId?: string;
+    fieldManifest: Array<Pick<AnonymizationFieldMetadata, "fieldPath" | "method" | "beforeChecksum">>;
+  }>;
+  preservedSemantics: string[];
+}
+declare function stableChecksum(value: unknown): string;
+declare class FieldRedactor {
+  redactField(value: unknown, method: RedactionMethod, context: AnonymizationContext, path: string): unknown;
+  mask(value: unknown): string | null;
+  hash(value: unknown): string;
+  tokenize(value: unknown, context: AnonymizationContext, path: string): string;
+  generalize(value: unknown): unknown;
+}
+declare class AnonymizationEngine {
+  #private;
+  constructor(policy: AnonymizationPolicy);
+  anonymizeJsonValue<TValue>(value: TValue, context: AnonymizationContext, dataClass: PlatformDataClass): AnonymizationResult<TValue>;
+  anonymizeJsonValueAtPath<TValue>(value: TValue, context: AnonymizationContext, dataClass: PlatformDataClass, basePath: string): AnonymizationResult<TValue>;
+  anonymizeAssetEventPayload(event: AssetEventLike, context: AnonymizationContext): AnonymizationResult<unknown>;
+  anonymizeEvidencePacket(packet: EvidencePacketLike, context: AnonymizationContext): AnonymizationResult<Pick<EvidencePacketLike, "packet" | "redactionMetadata" | "checksum">>;
+  buildAnonymizationLifecycleEvidence(input: {
+    context: AnonymizationContext;
+    assetEvents?: Array<{
+      event: AssetEventLike;
+      metadata: AnonymizationMetadata;
+    }>;
+    readModels?: Array<{
+      modelKind: string;
+      record: JsonObject & {
+        id: string;
+      };
+      metadata: AnonymizationMetadata;
+    }>;
+    evidencePackets?: Array<{
+      packet: EvidencePacketLike;
+      metadata: AnonymizationMetadata;
+    }>;
+  }): AnonymizationLifecycleEvidence;
+}
+//#endregion
+//#region privacy/index.d.ts
+declare const PLATFORM_PRIVACY_POLICY_VERSION = "fabric-platform-privacy-v1";
+type RedactionMethod = "nullify" | "mask" | "hash" | "tokenize" | "generalize" | "drop";
+declare function anonymizeJsonValue<TValue>(value: TValue, context: AnonymizationContext, dataClass: PlatformDataClass, policy: AnonymizationPolicy): AnonymizationResult<TValue>;
+declare function anonymizeAssetEventPayload(event: AssetEventLike, context: AnonymizationContext, policy: AnonymizationPolicy): AnonymizationResult<unknown>;
+declare function anonymizeEvidencePacket(packet: EvidencePacketLike, context: AnonymizationContext, policy: AnonymizationPolicy): AnonymizationResult<Pick<EvidencePacketLike, "packet" | "redactionMetadata" | "checksum">>;
+declare function buildAnonymizationLifecycleEvidence(input: {
+  context: AnonymizationContext;
+  assetEvents?: Array<{
+    event: AssetEventLike;
+    metadata: AnonymizationMetadata;
+  }>;
+  readModels?: Array<{
+    modelKind: string;
+    record: Record<string, unknown> & {
+      id: string;
+    };
+    metadata: AnonymizationMetadata;
+  }>;
+  evidencePackets?: Array<{
+    packet: EvidencePacketLike;
+    metadata: AnonymizationMetadata;
+  }>;
+}, policy: AnonymizationPolicy): AnonymizationLifecycleEvidence;
+type PlatformDataClass = "asset_event" | "read_model" | "raw_payload" | "evidence_packet" | "action_evidence" | "access_event";
+interface RedactionRule {
+  fieldPath: string;
+  method: RedactionMethod;
+  reason: string;
+  dataClass?: PlatformDataClass;
+}
+interface DataClassificationRule {
+  fieldPath: string;
+  classification: string;
+  containsDirectIdentifier?: boolean;
+  containsSensitiveData?: boolean;
+}
+interface AnonymizationContext {
+  tenantId: string;
+  spaceId?: string | null;
+  jobId: string;
+  reason: string;
+  redactedAt?: Date;
+  policyVersion?: string;
+}
+interface AnonymizationFieldMetadata {
+  fieldPath: string;
+  method: RedactionMethod;
+  policyVersion: string;
+  jobId: string;
+  redactedAt: string;
+  reason: string;
+  dataClass: PlatformDataClass;
+  beforeChecksum: string;
+}
+interface AnonymizationMetadata {
+  redactionState: "anonymized";
+  policyVersion: string;
+  jobId: string;
+  redactedAt: string;
+  reason: string;
+  dataClass: PlatformDataClass;
+  redactedFields: AnonymizationFieldMetadata[];
+  preservedSemantics: string[];
+}
+interface AnonymizationResult<TValue> {
+  value: TValue;
+  metadata: AnonymizationMetadata;
+}
+interface AnalyticsDataContractSource {
+  name: string;
+  privacyClass: "raw" | "operational_pii" | "tenant_scoped_tokenized" | "anonymized" | "aggregated" | "differentially_minimized";
+  containsDirectIdentifiers?: boolean;
+  containsGloballyStablePersonTokens?: boolean;
+  anonymizationPolicyVersion?: string;
+  minimumGroupSize?: number;
+}
+interface AnalyticsDataContract {
+  contractId: string;
+  status: "draft" | "accepted" | "deprecated";
+  crossTenant: boolean;
+  acceptedBy?: string;
+  acceptedAt?: string;
+  adrReference?: string;
+  sources: AnalyticsDataContractSource[];
+}
+interface AnalyticsEligibilityDecision {
+  eligible: boolean;
+  policyVersion: string;
+  reasons: string[];
+}
+interface RetentionRule {
+  dataClass: PlatformDataClass;
+  retainForDays: number;
+  afterRetention: "delete" | "anonymize" | "archive";
+  legalHoldExempt?: boolean;
+}
+//#endregion
+export { AssetEventLike as C, stableChecksum as E, AnonymizationPolicy as S, FieldRedactor as T, buildAnonymizationLifecycleEvidence as _, AnonymizationFieldMetadata as a, AnonymizationFieldPolicy as b, DataClassificationRule as c, RedactionMethod as d, RedactionRule as f, anonymizeJsonValue as g, anonymizeEvidencePacket as h, AnonymizationContext as i, PLATFORM_PRIVACY_POLICY_VERSION as l, anonymizeAssetEventPayload as m, AnalyticsDataContractSource as n, AnonymizationMetadata as o, RetentionRule as p, AnalyticsEligibilityDecision as r, AnonymizationResult as s, AnalyticsDataContract as t, PlatformDataClass as u, ANONYMIZATION_POLICY_VERSION as v, EvidencePacketLike as w, AnonymizationLifecycleEvidence as x, AnonymizationEngine as y };

package/dist/index-BnbsKZsT.d.cts

@@ -0,0 +1,231 @@
+import { S as AnonymizationPolicy, o as AnonymizationMetadata } from "./index-BXpeFdk2.cjs";
+//#region evidence/canonical-json.d.ts
+/**
+ * Serializes a value as JSON with every object's keys sorted, recursively, by UTF-16 code-unit
+ * order (locale-independent). Array order is preserved.
+ *
+ * This is the serialization behind the `fabric-canonical-json-sha256-v1` digests: Host's
+ * parameter digests (`PARAMETER_DIGEST_ALGORITHM` in `@fabricorg/platform-host`) and evidence
+ * packet checksums (`EVIDENCE_PACKET_CHECKSUM_ALGORITHM`). Its output is a durable contract, so it
+ * must not change for any input. That includes values that are not plain JSON: any non-array
+ * object is rebuilt from its own enumerable entries before serialization, so a `Date` (which has
+ * none) serializes as `{}`, not as an ISO string. Convert dates to strings before calling this
+ * when they must survive into the output.
+ */
+declare function canonicalJson(value: unknown): string;
+//#endregion
+//#region evidence/generator.d.ts
+/**
+ * Identifies how `EvidencePacketEnvelope.checksum` is computed: the lowercase hex SHA-256 of
+ * `canonicalJson(payload)`. It is the same identifier as Host's `PARAMETER_DIGEST_ALGORITHM`
+ * because the algorithm is the same (SHA-256 over `canonicalJson`).
+ */
+declare const EVIDENCE_PACKET_CHECKSUM_ALGORITHM: "fabric-canonical-json-sha256-v1";
+/** Version of the `EvidencePacketPayload` shape produced by `generateEvidencePacket`. */
+declare const EVIDENCE_PACKET_SCHEMA_VERSION: 1;
+/** Packet type used when the input does not name one. */
+declare const DEFAULT_EVIDENCE_PACKET_TYPE = "compliance_evidence";
+/** Anonymization reason recorded when the caller does not supply one. */
+declare const DEFAULT_EVIDENCE_REDACTION_REASON = "evidence_packet_generation";
+/**
+ * A `Date`, or an ISO 8601 / PostgreSQL ISO date-time string with an explicit zone (`Z`, `+HH`,
+ * `+HH:MM` or `+HHMM`). Zone-less, non-ISO and out-of-range strings are rejected.
+ */
+type EvidenceTimestamp = Date | string;
+/** Tenant and space every record read through the port must belong to. */
+interface EvidenceScope {
+  tenantId: string;
+  spaceId: string;
+}
+/**
+ * An asset event as the read port returns it. `AssetEventEnvelope` (events) and `AssetEventLike`
+ * (privacy) both satisfy this shape. Fields beyond these are kept in the packet payload.
+ */
+interface EvidenceEventRecord {
+  id: string;
+  tenantId: string;
+  spaceId: string;
+  eventType: string;
+  subjectType: string;
+  subjectId: string;
+  actionInvocationId?: string | null;
+  sequence: number;
+  occurredAt: EvidenceTimestamp;
+  recordedAt: EvidenceTimestamp;
+  correlationId: string;
+  causationId?: string | null;
+  payload: unknown;
+}
+/** An action invocation, policy evaluation or adapter invocation record. Further fields are kept. */
+interface EvidenceRecord {
+  id: string;
+  tenantId: string;
+  spaceId: string;
+  actionInvocationId?: string | null;
+  [field: string]: unknown;
+}
+/** A record that belongs to one action invocation (policy evaluations, adapter invocations). */
+interface EvidenceInvocationRecord extends EvidenceRecord {
+  actionInvocationId: string;
+}
+interface EvidenceEventQuery extends EvidenceScope {
+  /** The subject the packet is about. Always `subjects[0]`. */
+  primarySubject: EvidencePacketSubject;
+  /** Primary subject first, then related subjects, de-duplicated and sorted. */
+  subjects: readonly EvidencePacketSubject[];
+}
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Read-only access to the application's evidence store. The generator filters nothing the port
+ * returns; it rejects, rather than drops, a record that fails one of its checks:
+ *
+ * - every record must have the generation context's `tenantId` and `spaceId`;
+ * - action invocations must have one of the requested ids, and policy evaluations and adapter
+ *   invocations one of the requested `actionInvocationId`s;
+ * - records must have the documented shape (non-empty `id`, event fields, parseable timestamps) and
+ *   be representable as plain JSON, and any `_privacy` value must be engine-written
+ *   `AnonymizationMetadata`.
+ *
+ * Which events belong to the packet is the port's decision: the generator does not check an event's
+ * subject against `subjects`, because a port may legitimately return events recorded against the
+ * primary subject's own action invocations under another subject.
+ */
+interface EvidencePacketReadPort {
+  /** Asset events for the given subjects within the tenant and space. Required. */
+  listEvents(query: EvidenceEventQuery): MaybePromise<readonly EvidenceEventRecord[]>;
+  /** The application's related-subject rules. When absent, only the primary subject is used. */
+  resolveRelatedSubjects?(subject: EvidencePacketSubject, scope: EvidenceScope): MaybePromise<readonly EvidencePacketSubject[]>;
+  /** Action invocations by id. When absent, the section is empty. */
+  listActionInvocations?(scope: EvidenceScope, ids: readonly string[]): MaybePromise<readonly EvidenceRecord[]>;
+  /** Policy evaluations for the given action invocations. When absent, the section is empty. */
+  listPolicyEvaluations?(scope: EvidenceScope, actionInvocationIds: readonly string[]): MaybePromise<readonly EvidenceInvocationRecord[]>;
+  /** Adapter invocations for the given action invocations. When absent, the section is empty. */
+  listAdapterInvocations?(scope: EvidenceScope, actionInvocationIds: readonly string[]): MaybePromise<readonly EvidenceInvocationRecord[]>;
+}
+/** A record after normalization: plain JSON, every `Date` replaced by its ISO string. */
+type EvidenceJsonRecord = Record<string, unknown>;
+interface EvidencePacketPayload {
+  schemaVersion: typeof EVIDENCE_PACKET_SCHEMA_VERSION;
+  packetType: string;
+  tenantId: string;
+  spaceId: string;
+  primarySubject: EvidencePacketSubject;
+  subjects: EvidencePacketSubject[];
+  includeRelated: boolean;
+  policyVersion?: string;
+  events: EvidenceJsonRecord[];
+  actionInvocations: EvidenceJsonRecord[];
+  policyEvaluations: EvidenceJsonRecord[];
+  adapterInvocations: EvidenceJsonRecord[];
+  /** Metadata from the anonymization pass over the rest of the payload (validated engine-written `_privacy` values pass through it unchanged). */
+  redaction: AnonymizationMetadata;
+}
+interface GenerateEvidencePacketInput {
+  subject: EvidencePacketSubject;
+  /** Set to `false` to skip `resolveRelatedSubjects`. Defaults to `true`. */
+  includeRelated?: boolean;
+  /** Defaults to `DEFAULT_EVIDENCE_PACKET_TYPE`. */
+  packetType?: string;
+  policyVersion?: string;
+}
+interface GenerateEvidencePacketOptions {
+  port: EvidencePacketReadPort;
+  /**
+   * Redaction applied to the whole payload with data class `"evidence_packet"`. Required so that
+   * redaction cannot be skipped by omission; pass `{ fields: [] }` to redact nothing.
+   */
+  anonymizationPolicy: AnonymizationPolicy;
+  anonymization?: {
+    /** Defaults to the packet id. */
+    jobId?: string;
+    /** Defaults to `DEFAULT_EVIDENCE_REDACTION_REASON`. */
+    reason?: string;
+    /** Defaults to the engine's `ANONYMIZATION_POLICY_VERSION`. */
+    policyVersion?: string;
+  };
+  /** Defaults to `createFabricId(FABRIC_ID_PREFIXES.complianceEvidencePacket)`. */
+  idFactory?: () => string;
+}
+type EvidencePacketGenerationErrorCode = "EVIDENCE_SCOPE_MISMATCH" | "EVIDENCE_INVALID_RECORD" | "EVIDENCE_UNREQUESTED_RECORD" | "EVIDENCE_IDENTIFIER_REDACTED";
+declare class EvidencePacketGenerationError extends Error {
+  readonly code: EvidencePacketGenerationErrorCode;
+  constructor(code: EvidencePacketGenerationErrorCode, message: string);
+}
+/** Lowercase hex SHA-256 of `canonicalJson(payload)`. */
+declare function computeEvidencePacketChecksum(payload: unknown): string;
+/**
+ * Builds a sealed evidence packet for one subject from the application's read port.
+ *
+ * Steps: resolve subjects (primary first, then related, de-duplicated and sorted); read events,
+ * then the action invocations, policy evaluations and adapter invocations those events reference;
+ * reject any record outside `context.tenantId`/`context.spaceId`; normalize to plain JSON and sort
+ * deterministically; redact the payload with `AnonymizationEngine` (data class
+ * `"evidence_packet"`); checksum the redacted payload; and build references from it.
+ *
+ * Nothing is persisted. Storing the returned envelope is the application's job.
+ */
+declare function generateEvidencePacket<TDb = unknown>(input: GenerateEvidencePacketInput, context: EvidenceGenerationContext<TDb>, options: GenerateEvidencePacketOptions): Promise<EvidencePacketEnvelope<EvidencePacketPayload>>;
+/**
+ * Recomputes an envelope's checksum. Returns `false`, never throws, when the checksum is missing,
+ * the algorithm is missing or unknown, the payload cannot be serialized, or the values differ.
+ * It covers `payload` only, which includes the subjects and the redaction metadata; the other
+ * envelope fields are not covered.
+ */
+declare function verifyEvidencePacketChecksum(envelope: Pick<EvidencePacketEnvelope<unknown>, "payload" | "checksum" | "checksumAlgorithm">): boolean;
+type EvidencePacketRendererInput = Omit<GenerateEvidencePacketInput, "packetType">;
+interface EvidencePacketRendererOptions extends GenerateEvidencePacketOptions {
+  packetType?: string;
+}
+/** Wraps `generateEvidencePacket` as an `EvidenceRenderer` for one packet type. */
+declare function createEvidencePacketRenderer<TDb = unknown>(options: EvidencePacketRendererOptions): EvidenceRenderer<EvidencePacketRendererInput, EvidencePacketPayload, TDb>;
+//#endregion
+//#region evidence/index.d.ts
+type EvidencePacketStatus = "draft" | "sealed" | "superseded";
+interface EvidencePacketSubject {
+  subjectType: string;
+  subjectId: string;
+}
+interface EvidencePacketReference {
+  referenceType: "action_invocation" | "asset_event" | "policy_evaluation" | "adapter_invocation" | "document" | "external_observation";
+  referenceId: string;
+  checksum?: string;
+  uri?: string;
+  metadata?: Record<string, unknown>;
+}
+interface EvidencePacketEnvelope<TPayload = Record<string, unknown>> {
+  id: string;
+  tenantId: string;
+  spaceId: string;
+  packetType: string;
+  status: EvidencePacketStatus;
+  subjects: EvidencePacketSubject[];
+  references: EvidencePacketReference[];
+  payload: TPayload;
+  generatedAt: Date | string;
+  generatedBy: string;
+  policyVersion?: string;
+  checksum?: string;
+  /**
+   * How `checksum` was computed. Packets built by `generateEvidencePacket` use
+   * `EVIDENCE_PACKET_CHECKSUM_ALGORITHM`. Optional and additive: envelopes built before this field
+   * existed omit it.
+   */
+  checksumAlgorithm?: string;
+  correlationId: string;
+  causationId?: string;
+}
+interface EvidenceGenerationContext<TDb = unknown> {
+  tenantId: string;
+  spaceId: string;
+  actorId: string;
+  correlationId: string;
+  causationId?: string;
+  db: TDb;
+  now?: Date;
+}
+interface EvidenceRenderer<TInput = unknown, TPayload = Record<string, unknown>, TDb = unknown> {
+  packetType: string;
+  render: (input: TInput, context: EvidenceGenerationContext<TDb>) => Promise<EvidencePacketEnvelope<TPayload>> | EvidencePacketEnvelope<TPayload>;
+}
+//#endregion
+export { canonicalJson as A, EvidenceTimestamp as C, createEvidencePacketRenderer as D, computeEvidencePacketChecksum as E, generateEvidencePacket as O, EvidenceScope as S, GenerateEvidencePacketOptions as T, EvidencePacketPayload as _, EvidencePacketSubject as a, EvidencePacketRendererOptions as b, DEFAULT_EVIDENCE_REDACTION_REASON as c, EvidenceEventQuery as d, EvidenceEventRecord as f, EvidencePacketGenerationErrorCode as g, EvidencePacketGenerationError as h, EvidencePacketStatus as i, verifyEvidencePacketChecksum as k, EVIDENCE_PACKET_CHECKSUM_ALGORITHM as l, EvidenceJsonRecord as m, EvidencePacketEnvelope as n, EvidenceRenderer as o, EvidenceInvocationRecord as p, EvidencePacketReference as r, DEFAULT_EVIDENCE_PACKET_TYPE as s, EvidenceGenerationContext as t, EVIDENCE_PACKET_SCHEMA_VERSION as u, EvidencePacketReadPort as v, GenerateEvidencePacketInput as w, EvidenceRecord as x, EvidencePacketRendererInput as y };

package/dist/index-CIl1rYRv.d.cts

@@ -0,0 +1,11 @@
+//#region discovery/index.d.ts
+/** Portable discovery metadata. It never grants or denies runtime invocation authority. */
+interface SurfaceDeclaration {
+  /** Omitted is public discovery; internal contracts are withheld from external catalogs. */
+  surface?: "public" | "internal";
+  /** Required, non-blank explanation when surface is internal; never include sensitive data. */
+  surfaceReason?: string;
+}
+declare function assertSurfaceDeclaration(value: unknown, label?: string): asserts value is SurfaceDeclaration;
+//#endregion
+export { assertSurfaceDeclaration as n, SurfaceDeclaration as t };

package/dist/index-CIl1rYRv.d.ts

@@ -0,0 +1,11 @@
+//#region discovery/index.d.ts
+/** Portable discovery metadata. It never grants or denies runtime invocation authority. */
+interface SurfaceDeclaration {
+  /** Omitted is public discovery; internal contracts are withheld from external catalogs. */
+  surface?: "public" | "internal";
+  /** Required, non-blank explanation when surface is internal; never include sensitive data. */
+  surfaceReason?: string;
+}
+declare function assertSurfaceDeclaration(value: unknown, label?: string): asserts value is SurfaceDeclaration;
+//#endregion
+export { assertSurfaceDeclaration as n, SurfaceDeclaration as t };