@fabricorg/platform 1.7.0 → 1.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +56 -0
- package/README.md +214 -3
- package/dist/actions/index.cjs +6 -6
- package/dist/actions/index.d.cts +9 -2
- package/dist/actions/index.d.ts +9 -2
- package/dist/actions/index.js +1 -1
- package/dist/adapters/index.cjs +33 -9
- package/dist/adapters/index.d.cts +388 -1
- package/dist/adapters/index.d.ts +388 -1
- package/dist/adapters/index.js +1 -1
- package/dist/chunk-5FOCPRTR.js +511 -0
- package/dist/chunk-5FOCPRTR.js.map +1 -0
- package/dist/{chunk-USDLP4E7.cjs → chunk-5IVFPWK6.cjs} +4 -4
- package/dist/{chunk-USDLP4E7.cjs.map → chunk-5IVFPWK6.cjs.map} +1 -1
- package/dist/chunk-6HY35TKB.cjs +491 -0
- package/dist/chunk-6HY35TKB.cjs.map +1 -0
- package/dist/chunk-6UGEIDLC.cjs +26 -0
- package/dist/chunk-6UGEIDLC.cjs.map +1 -0
- package/dist/chunk-BJGZE3GE.js +20 -0
- package/dist/chunk-BJGZE3GE.js.map +1 -0
- package/dist/{chunk-X3GHYMAJ.cjs → chunk-CRZXTZ36.cjs} +2 -22
- package/dist/chunk-CRZXTZ36.cjs.map +1 -0
- package/dist/{chunk-DCC3UIUJ.js → chunk-GFU7BGEJ.js} +3 -3
- package/dist/{chunk-DCC3UIUJ.js.map → chunk-GFU7BGEJ.js.map} +1 -1
- package/dist/chunk-HEYMMVDP.js +480 -0
- package/dist/chunk-HEYMMVDP.js.map +1 -0
- package/dist/chunk-IF6NJORI.cjs +526 -0
- package/dist/chunk-IF6NJORI.cjs.map +1 -0
- package/dist/{chunk-6QX4I45I.js → chunk-PIDZQAEL.js} +2 -2
- package/dist/{chunk-6QX4I45I.js.map → chunk-PIDZQAEL.js.map} +1 -1
- package/dist/{chunk-ATWWZTRC.js → chunk-TYNIFC7J.js} +3 -18
- package/dist/chunk-TYNIFC7J.js.map +1 -0
- package/dist/{chunk-XCAOO6KG.cjs → chunk-UGWGHTNC.cjs} +2 -2
- package/dist/{chunk-XCAOO6KG.cjs.map → chunk-UGWGHTNC.cjs.map} +1 -1
- package/dist/evidence/index.cjs +45 -1
- package/dist/evidence/index.d.cts +187 -1
- package/dist/evidence/index.d.ts +187 -1
- package/dist/evidence/index.js +3 -1
- package/dist/governance/index.d.cts +1 -0
- package/dist/governance/index.d.ts +1 -0
- package/dist/index.cjs +124 -59
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +7 -6
- package/dist/privacy/index.cjs +19 -18
- package/dist/privacy/index.js +2 -1
- package/dist/testing/index.cjs +5 -5
- package/dist/testing/index.js +2 -2
- package/package.json +1 -1
- package/dist/chunk-ATWWZTRC.js.map +0 -1
- package/dist/chunk-FAG2RTPM.js +0 -120
- package/dist/chunk-FAG2RTPM.js.map +0 -1
- package/dist/chunk-OZLZHISS.js +0 -3
- package/dist/chunk-OZLZHISS.js.map +0 -1
- package/dist/chunk-PG5LYTUX.cjs +0 -4
- package/dist/chunk-PG5LYTUX.cjs.map +0 -1
- package/dist/chunk-X3GHYMAJ.cjs.map +0 -1
- package/dist/chunk-XZQZQ5SW.cjs +0 -129
- package/dist/chunk-XZQZQ5SW.cjs.map +0 -1
|
@@ -1,3 +1,183 @@
|
|
|
1
|
+
import { AnonymizationMetadata, AnonymizationPolicy } from '../privacy/index.cjs';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Serializes a value as JSON with every object's keys sorted, recursively, by UTF-16 code-unit
|
|
5
|
+
* order (locale-independent). Array order is preserved.
|
|
6
|
+
*
|
|
7
|
+
* This is the serialization behind the `fabric-canonical-json-sha256-v1` digests: Host's
|
|
8
|
+
* parameter digests (`PARAMETER_DIGEST_ALGORITHM` in `@fabricorg/platform-host`) and evidence
|
|
9
|
+
* packet checksums (`EVIDENCE_PACKET_CHECKSUM_ALGORITHM`). Its output is a durable contract, so it
|
|
10
|
+
* must not change for any input. That includes values that are not plain JSON: any non-array
|
|
11
|
+
* object is rebuilt from its own enumerable entries before serialization, so a `Date` (which has
|
|
12
|
+
* none) serializes as `{}`, not as an ISO string. Convert dates to strings before calling this
|
|
13
|
+
* when they must survive into the output.
|
|
14
|
+
*/
|
|
15
|
+
declare function canonicalJson(value: unknown): string;
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Identifies how `EvidencePacketEnvelope.checksum` is computed: the lowercase hex SHA-256 of
|
|
19
|
+
* `canonicalJson(payload)`. It is the same identifier as Host's `PARAMETER_DIGEST_ALGORITHM`
|
|
20
|
+
* because the algorithm is the same (SHA-256 over `canonicalJson`).
|
|
21
|
+
*/
|
|
22
|
+
declare const EVIDENCE_PACKET_CHECKSUM_ALGORITHM: "fabric-canonical-json-sha256-v1";
|
|
23
|
+
/** Version of the `EvidencePacketPayload` shape produced by `generateEvidencePacket`. */
|
|
24
|
+
declare const EVIDENCE_PACKET_SCHEMA_VERSION: 1;
|
|
25
|
+
/** Packet type used when the input does not name one. */
|
|
26
|
+
declare const DEFAULT_EVIDENCE_PACKET_TYPE = "compliance_evidence";
|
|
27
|
+
/** Anonymization reason recorded when the caller does not supply one. */
|
|
28
|
+
declare const DEFAULT_EVIDENCE_REDACTION_REASON = "evidence_packet_generation";
|
|
29
|
+
/**
|
|
30
|
+
* A `Date`, or an ISO 8601 / PostgreSQL ISO date-time string with an explicit zone (`Z`, `+HH`,
|
|
31
|
+
* `+HH:MM` or `+HHMM`). Zone-less, non-ISO and out-of-range strings are rejected.
|
|
32
|
+
*/
|
|
33
|
+
type EvidenceTimestamp = Date | string;
|
|
34
|
+
/** Tenant and space every record read through the port must belong to. */
|
|
35
|
+
interface EvidenceScope {
|
|
36
|
+
tenantId: string;
|
|
37
|
+
spaceId: string;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* An asset event as the read port returns it. `AssetEventEnvelope` (events) and `AssetEventLike`
|
|
41
|
+
* (privacy) both satisfy this shape. Fields beyond these are kept in the packet payload.
|
|
42
|
+
*/
|
|
43
|
+
interface EvidenceEventRecord {
|
|
44
|
+
id: string;
|
|
45
|
+
tenantId: string;
|
|
46
|
+
spaceId: string;
|
|
47
|
+
eventType: string;
|
|
48
|
+
subjectType: string;
|
|
49
|
+
subjectId: string;
|
|
50
|
+
actionInvocationId?: string | null;
|
|
51
|
+
sequence: number;
|
|
52
|
+
occurredAt: EvidenceTimestamp;
|
|
53
|
+
recordedAt: EvidenceTimestamp;
|
|
54
|
+
correlationId: string;
|
|
55
|
+
causationId?: string | null;
|
|
56
|
+
payload: unknown;
|
|
57
|
+
}
|
|
58
|
+
/** An action invocation, policy evaluation or adapter invocation record. Further fields are kept. */
|
|
59
|
+
interface EvidenceRecord {
|
|
60
|
+
id: string;
|
|
61
|
+
tenantId: string;
|
|
62
|
+
spaceId: string;
|
|
63
|
+
actionInvocationId?: string | null;
|
|
64
|
+
[field: string]: unknown;
|
|
65
|
+
}
|
|
66
|
+
/** A record that belongs to one action invocation (policy evaluations, adapter invocations). */
|
|
67
|
+
interface EvidenceInvocationRecord extends EvidenceRecord {
|
|
68
|
+
actionInvocationId: string;
|
|
69
|
+
}
|
|
70
|
+
interface EvidenceEventQuery extends EvidenceScope {
|
|
71
|
+
/** The subject the packet is about. Always `subjects[0]`. */
|
|
72
|
+
primarySubject: EvidencePacketSubject;
|
|
73
|
+
/** Primary subject first, then related subjects, de-duplicated and sorted. */
|
|
74
|
+
subjects: readonly EvidencePacketSubject[];
|
|
75
|
+
}
|
|
76
|
+
type MaybePromise<T> = T | Promise<T>;
|
|
77
|
+
/**
|
|
78
|
+
* Read-only access to the application's evidence store. The generator filters nothing the port
|
|
79
|
+
* returns; it rejects, rather than drops, a record that fails one of its checks:
|
|
80
|
+
*
|
|
81
|
+
* - every record must have the generation context's `tenantId` and `spaceId`;
|
|
82
|
+
* - action invocations must have one of the requested ids, and policy evaluations and adapter
|
|
83
|
+
* invocations one of the requested `actionInvocationId`s;
|
|
84
|
+
* - records must have the documented shape (non-empty `id`, event fields, parseable timestamps) and
|
|
85
|
+
* be representable as plain JSON, and any `_privacy` value must be engine-written
|
|
86
|
+
* `AnonymizationMetadata`.
|
|
87
|
+
*
|
|
88
|
+
* Which events belong to the packet is the port's decision: the generator does not check an event's
|
|
89
|
+
* subject against `subjects`, because a port may legitimately return events recorded against the
|
|
90
|
+
* primary subject's own action invocations under another subject.
|
|
91
|
+
*/
|
|
92
|
+
interface EvidencePacketReadPort {
|
|
93
|
+
/** Asset events for the given subjects within the tenant and space. Required. */
|
|
94
|
+
listEvents(query: EvidenceEventQuery): MaybePromise<readonly EvidenceEventRecord[]>;
|
|
95
|
+
/** The application's related-subject rules. When absent, only the primary subject is used. */
|
|
96
|
+
resolveRelatedSubjects?(subject: EvidencePacketSubject, scope: EvidenceScope): MaybePromise<readonly EvidencePacketSubject[]>;
|
|
97
|
+
/** Action invocations by id. When absent, the section is empty. */
|
|
98
|
+
listActionInvocations?(scope: EvidenceScope, ids: readonly string[]): MaybePromise<readonly EvidenceRecord[]>;
|
|
99
|
+
/** Policy evaluations for the given action invocations. When absent, the section is empty. */
|
|
100
|
+
listPolicyEvaluations?(scope: EvidenceScope, actionInvocationIds: readonly string[]): MaybePromise<readonly EvidenceInvocationRecord[]>;
|
|
101
|
+
/** Adapter invocations for the given action invocations. When absent, the section is empty. */
|
|
102
|
+
listAdapterInvocations?(scope: EvidenceScope, actionInvocationIds: readonly string[]): MaybePromise<readonly EvidenceInvocationRecord[]>;
|
|
103
|
+
}
|
|
104
|
+
/** A record after normalization: plain JSON, every `Date` replaced by its ISO string. */
|
|
105
|
+
type EvidenceJsonRecord = Record<string, unknown>;
|
|
106
|
+
interface EvidencePacketPayload {
|
|
107
|
+
schemaVersion: typeof EVIDENCE_PACKET_SCHEMA_VERSION;
|
|
108
|
+
packetType: string;
|
|
109
|
+
tenantId: string;
|
|
110
|
+
spaceId: string;
|
|
111
|
+
primarySubject: EvidencePacketSubject;
|
|
112
|
+
subjects: EvidencePacketSubject[];
|
|
113
|
+
includeRelated: boolean;
|
|
114
|
+
policyVersion?: string;
|
|
115
|
+
events: EvidenceJsonRecord[];
|
|
116
|
+
actionInvocations: EvidenceJsonRecord[];
|
|
117
|
+
policyEvaluations: EvidenceJsonRecord[];
|
|
118
|
+
adapterInvocations: EvidenceJsonRecord[];
|
|
119
|
+
/** Metadata from the anonymization pass over the rest of the payload (validated engine-written `_privacy` values pass through it unchanged). */
|
|
120
|
+
redaction: AnonymizationMetadata;
|
|
121
|
+
}
|
|
122
|
+
interface GenerateEvidencePacketInput {
|
|
123
|
+
subject: EvidencePacketSubject;
|
|
124
|
+
/** Set to `false` to skip `resolveRelatedSubjects`. Defaults to `true`. */
|
|
125
|
+
includeRelated?: boolean;
|
|
126
|
+
/** Defaults to `DEFAULT_EVIDENCE_PACKET_TYPE`. */
|
|
127
|
+
packetType?: string;
|
|
128
|
+
policyVersion?: string;
|
|
129
|
+
}
|
|
130
|
+
interface GenerateEvidencePacketOptions {
|
|
131
|
+
port: EvidencePacketReadPort;
|
|
132
|
+
/**
|
|
133
|
+
* Redaction applied to the whole payload with data class `"evidence_packet"`. Required so that
|
|
134
|
+
* redaction cannot be skipped by omission; pass `{ fields: [] }` to redact nothing.
|
|
135
|
+
*/
|
|
136
|
+
anonymizationPolicy: AnonymizationPolicy;
|
|
137
|
+
anonymization?: {
|
|
138
|
+
/** Defaults to the packet id. */
|
|
139
|
+
jobId?: string;
|
|
140
|
+
/** Defaults to `DEFAULT_EVIDENCE_REDACTION_REASON`. */
|
|
141
|
+
reason?: string;
|
|
142
|
+
/** Defaults to the engine's `ANONYMIZATION_POLICY_VERSION`. */
|
|
143
|
+
policyVersion?: string;
|
|
144
|
+
};
|
|
145
|
+
/** Defaults to `createFabricId(FABRIC_ID_PREFIXES.complianceEvidencePacket)`. */
|
|
146
|
+
idFactory?: () => string;
|
|
147
|
+
}
|
|
148
|
+
type EvidencePacketGenerationErrorCode = "EVIDENCE_SCOPE_MISMATCH" | "EVIDENCE_INVALID_RECORD" | "EVIDENCE_UNREQUESTED_RECORD" | "EVIDENCE_IDENTIFIER_REDACTED";
|
|
149
|
+
declare class EvidencePacketGenerationError extends Error {
|
|
150
|
+
readonly code: EvidencePacketGenerationErrorCode;
|
|
151
|
+
constructor(code: EvidencePacketGenerationErrorCode, message: string);
|
|
152
|
+
}
|
|
153
|
+
/** Lowercase hex SHA-256 of `canonicalJson(payload)`. */
|
|
154
|
+
declare function computeEvidencePacketChecksum(payload: unknown): string;
|
|
155
|
+
/**
|
|
156
|
+
* Builds a sealed evidence packet for one subject from the application's read port.
|
|
157
|
+
*
|
|
158
|
+
* Steps: resolve subjects (primary first, then related, de-duplicated and sorted); read events,
|
|
159
|
+
* then the action invocations, policy evaluations and adapter invocations those events reference;
|
|
160
|
+
* reject any record outside `context.tenantId`/`context.spaceId`; normalize to plain JSON and sort
|
|
161
|
+
* deterministically; redact the payload with `AnonymizationEngine` (data class
|
|
162
|
+
* `"evidence_packet"`); checksum the redacted payload; and build references from it.
|
|
163
|
+
*
|
|
164
|
+
* Nothing is persisted. Storing the returned envelope is the application's job.
|
|
165
|
+
*/
|
|
166
|
+
declare function generateEvidencePacket<TDb = unknown>(input: GenerateEvidencePacketInput, context: EvidenceGenerationContext<TDb>, options: GenerateEvidencePacketOptions): Promise<EvidencePacketEnvelope<EvidencePacketPayload>>;
|
|
167
|
+
/**
|
|
168
|
+
* Recomputes an envelope's checksum. Returns `false`, never throws, when the checksum is missing,
|
|
169
|
+
* the algorithm is missing or unknown, the payload cannot be serialized, or the values differ.
|
|
170
|
+
* It covers `payload` only, which includes the subjects and the redaction metadata; the other
|
|
171
|
+
* envelope fields are not covered.
|
|
172
|
+
*/
|
|
173
|
+
declare function verifyEvidencePacketChecksum(envelope: Pick<EvidencePacketEnvelope<unknown>, "payload" | "checksum" | "checksumAlgorithm">): boolean;
|
|
174
|
+
type EvidencePacketRendererInput = Omit<GenerateEvidencePacketInput, "packetType">;
|
|
175
|
+
interface EvidencePacketRendererOptions extends GenerateEvidencePacketOptions {
|
|
176
|
+
packetType?: string;
|
|
177
|
+
}
|
|
178
|
+
/** Wraps `generateEvidencePacket` as an `EvidenceRenderer` for one packet type. */
|
|
179
|
+
declare function createEvidencePacketRenderer<TDb = unknown>(options: EvidencePacketRendererOptions): EvidenceRenderer<EvidencePacketRendererInput, EvidencePacketPayload, TDb>;
|
|
180
|
+
|
|
1
181
|
type EvidencePacketStatus = "draft" | "sealed" | "superseded";
|
|
2
182
|
interface EvidencePacketSubject {
|
|
3
183
|
subjectType: string;
|
|
@@ -23,6 +203,12 @@ interface EvidencePacketEnvelope<TPayload = Record<string, unknown>> {
|
|
|
23
203
|
generatedBy: string;
|
|
24
204
|
policyVersion?: string;
|
|
25
205
|
checksum?: string;
|
|
206
|
+
/**
|
|
207
|
+
* How `checksum` was computed. Packets built by `generateEvidencePacket` use
|
|
208
|
+
* `EVIDENCE_PACKET_CHECKSUM_ALGORITHM`. Optional and additive: envelopes built before this field
|
|
209
|
+
* existed omit it.
|
|
210
|
+
*/
|
|
211
|
+
checksumAlgorithm?: string;
|
|
26
212
|
correlationId: string;
|
|
27
213
|
causationId?: string;
|
|
28
214
|
}
|
|
@@ -40,4 +226,4 @@ interface EvidenceRenderer<TInput = unknown, TPayload = Record<string, unknown>,
|
|
|
40
226
|
render: (input: TInput, context: EvidenceGenerationContext<TDb>) => Promise<EvidencePacketEnvelope<TPayload>> | EvidencePacketEnvelope<TPayload>;
|
|
41
227
|
}
|
|
42
228
|
|
|
43
|
-
export type
|
|
229
|
+
export { DEFAULT_EVIDENCE_PACKET_TYPE, DEFAULT_EVIDENCE_REDACTION_REASON, EVIDENCE_PACKET_CHECKSUM_ALGORITHM, EVIDENCE_PACKET_SCHEMA_VERSION, type EvidenceEventQuery, type EvidenceEventRecord, type EvidenceGenerationContext, type EvidenceInvocationRecord, type EvidenceJsonRecord, type EvidencePacketEnvelope, EvidencePacketGenerationError, type EvidencePacketGenerationErrorCode, type EvidencePacketPayload, type EvidencePacketReadPort, type EvidencePacketReference, type EvidencePacketRendererInput, type EvidencePacketRendererOptions, type EvidencePacketStatus, type EvidencePacketSubject, type EvidenceRecord, type EvidenceRenderer, type EvidenceScope, type EvidenceTimestamp, type GenerateEvidencePacketInput, type GenerateEvidencePacketOptions, canonicalJson, computeEvidencePacketChecksum, createEvidencePacketRenderer, generateEvidencePacket, verifyEvidencePacketChecksum };
|
package/dist/evidence/index.d.ts
CHANGED
|
@@ -1,3 +1,183 @@
|
|
|
1
|
+
import { AnonymizationMetadata, AnonymizationPolicy } from '../privacy/index.js';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Serializes a value as JSON with every object's keys sorted, recursively, by UTF-16 code-unit
|
|
5
|
+
* order (locale-independent). Array order is preserved.
|
|
6
|
+
*
|
|
7
|
+
* This is the serialization behind the `fabric-canonical-json-sha256-v1` digests: Host's
|
|
8
|
+
* parameter digests (`PARAMETER_DIGEST_ALGORITHM` in `@fabricorg/platform-host`) and evidence
|
|
9
|
+
* packet checksums (`EVIDENCE_PACKET_CHECKSUM_ALGORITHM`). Its output is a durable contract, so it
|
|
10
|
+
* must not change for any input. That includes values that are not plain JSON: any non-array
|
|
11
|
+
* object is rebuilt from its own enumerable entries before serialization, so a `Date` (which has
|
|
12
|
+
* none) serializes as `{}`, not as an ISO string. Convert dates to strings before calling this
|
|
13
|
+
* when they must survive into the output.
|
|
14
|
+
*/
|
|
15
|
+
declare function canonicalJson(value: unknown): string;
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Identifies how `EvidencePacketEnvelope.checksum` is computed: the lowercase hex SHA-256 of
|
|
19
|
+
* `canonicalJson(payload)`. It is the same identifier as Host's `PARAMETER_DIGEST_ALGORITHM`
|
|
20
|
+
* because the algorithm is the same (SHA-256 over `canonicalJson`).
|
|
21
|
+
*/
|
|
22
|
+
declare const EVIDENCE_PACKET_CHECKSUM_ALGORITHM: "fabric-canonical-json-sha256-v1";
|
|
23
|
+
/** Version of the `EvidencePacketPayload` shape produced by `generateEvidencePacket`. */
|
|
24
|
+
declare const EVIDENCE_PACKET_SCHEMA_VERSION: 1;
|
|
25
|
+
/** Packet type used when the input does not name one. */
|
|
26
|
+
declare const DEFAULT_EVIDENCE_PACKET_TYPE = "compliance_evidence";
|
|
27
|
+
/** Anonymization reason recorded when the caller does not supply one. */
|
|
28
|
+
declare const DEFAULT_EVIDENCE_REDACTION_REASON = "evidence_packet_generation";
|
|
29
|
+
/**
|
|
30
|
+
* A `Date`, or an ISO 8601 / PostgreSQL ISO date-time string with an explicit zone (`Z`, `+HH`,
|
|
31
|
+
* `+HH:MM` or `+HHMM`). Zone-less, non-ISO and out-of-range strings are rejected.
|
|
32
|
+
*/
|
|
33
|
+
type EvidenceTimestamp = Date | string;
|
|
34
|
+
/** Tenant and space every record read through the port must belong to. */
|
|
35
|
+
interface EvidenceScope {
|
|
36
|
+
tenantId: string;
|
|
37
|
+
spaceId: string;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* An asset event as the read port returns it. `AssetEventEnvelope` (events) and `AssetEventLike`
|
|
41
|
+
* (privacy) both satisfy this shape. Fields beyond these are kept in the packet payload.
|
|
42
|
+
*/
|
|
43
|
+
interface EvidenceEventRecord {
|
|
44
|
+
id: string;
|
|
45
|
+
tenantId: string;
|
|
46
|
+
spaceId: string;
|
|
47
|
+
eventType: string;
|
|
48
|
+
subjectType: string;
|
|
49
|
+
subjectId: string;
|
|
50
|
+
actionInvocationId?: string | null;
|
|
51
|
+
sequence: number;
|
|
52
|
+
occurredAt: EvidenceTimestamp;
|
|
53
|
+
recordedAt: EvidenceTimestamp;
|
|
54
|
+
correlationId: string;
|
|
55
|
+
causationId?: string | null;
|
|
56
|
+
payload: unknown;
|
|
57
|
+
}
|
|
58
|
+
/** An action invocation, policy evaluation or adapter invocation record. Further fields are kept. */
|
|
59
|
+
interface EvidenceRecord {
|
|
60
|
+
id: string;
|
|
61
|
+
tenantId: string;
|
|
62
|
+
spaceId: string;
|
|
63
|
+
actionInvocationId?: string | null;
|
|
64
|
+
[field: string]: unknown;
|
|
65
|
+
}
|
|
66
|
+
/** A record that belongs to one action invocation (policy evaluations, adapter invocations). */
|
|
67
|
+
interface EvidenceInvocationRecord extends EvidenceRecord {
|
|
68
|
+
actionInvocationId: string;
|
|
69
|
+
}
|
|
70
|
+
interface EvidenceEventQuery extends EvidenceScope {
|
|
71
|
+
/** The subject the packet is about. Always `subjects[0]`. */
|
|
72
|
+
primarySubject: EvidencePacketSubject;
|
|
73
|
+
/** Primary subject first, then related subjects, de-duplicated and sorted. */
|
|
74
|
+
subjects: readonly EvidencePacketSubject[];
|
|
75
|
+
}
|
|
76
|
+
type MaybePromise<T> = T | Promise<T>;
|
|
77
|
+
/**
|
|
78
|
+
* Read-only access to the application's evidence store. The generator filters nothing the port
|
|
79
|
+
* returns; it rejects, rather than drops, a record that fails one of its checks:
|
|
80
|
+
*
|
|
81
|
+
* - every record must have the generation context's `tenantId` and `spaceId`;
|
|
82
|
+
* - action invocations must have one of the requested ids, and policy evaluations and adapter
|
|
83
|
+
* invocations one of the requested `actionInvocationId`s;
|
|
84
|
+
* - records must have the documented shape (non-empty `id`, event fields, parseable timestamps) and
|
|
85
|
+
* be representable as plain JSON, and any `_privacy` value must be engine-written
|
|
86
|
+
* `AnonymizationMetadata`.
|
|
87
|
+
*
|
|
88
|
+
* Which events belong to the packet is the port's decision: the generator does not check an event's
|
|
89
|
+
* subject against `subjects`, because a port may legitimately return events recorded against the
|
|
90
|
+
* primary subject's own action invocations under another subject.
|
|
91
|
+
*/
|
|
92
|
+
interface EvidencePacketReadPort {
|
|
93
|
+
/** Asset events for the given subjects within the tenant and space. Required. */
|
|
94
|
+
listEvents(query: EvidenceEventQuery): MaybePromise<readonly EvidenceEventRecord[]>;
|
|
95
|
+
/** The application's related-subject rules. When absent, only the primary subject is used. */
|
|
96
|
+
resolveRelatedSubjects?(subject: EvidencePacketSubject, scope: EvidenceScope): MaybePromise<readonly EvidencePacketSubject[]>;
|
|
97
|
+
/** Action invocations by id. When absent, the section is empty. */
|
|
98
|
+
listActionInvocations?(scope: EvidenceScope, ids: readonly string[]): MaybePromise<readonly EvidenceRecord[]>;
|
|
99
|
+
/** Policy evaluations for the given action invocations. When absent, the section is empty. */
|
|
100
|
+
listPolicyEvaluations?(scope: EvidenceScope, actionInvocationIds: readonly string[]): MaybePromise<readonly EvidenceInvocationRecord[]>;
|
|
101
|
+
/** Adapter invocations for the given action invocations. When absent, the section is empty. */
|
|
102
|
+
listAdapterInvocations?(scope: EvidenceScope, actionInvocationIds: readonly string[]): MaybePromise<readonly EvidenceInvocationRecord[]>;
|
|
103
|
+
}
|
|
104
|
+
/** A record after normalization: plain JSON, every `Date` replaced by its ISO string. */
|
|
105
|
+
type EvidenceJsonRecord = Record<string, unknown>;
|
|
106
|
+
interface EvidencePacketPayload {
|
|
107
|
+
schemaVersion: typeof EVIDENCE_PACKET_SCHEMA_VERSION;
|
|
108
|
+
packetType: string;
|
|
109
|
+
tenantId: string;
|
|
110
|
+
spaceId: string;
|
|
111
|
+
primarySubject: EvidencePacketSubject;
|
|
112
|
+
subjects: EvidencePacketSubject[];
|
|
113
|
+
includeRelated: boolean;
|
|
114
|
+
policyVersion?: string;
|
|
115
|
+
events: EvidenceJsonRecord[];
|
|
116
|
+
actionInvocations: EvidenceJsonRecord[];
|
|
117
|
+
policyEvaluations: EvidenceJsonRecord[];
|
|
118
|
+
adapterInvocations: EvidenceJsonRecord[];
|
|
119
|
+
/** Metadata from the anonymization pass over the rest of the payload (validated engine-written `_privacy` values pass through it unchanged). */
|
|
120
|
+
redaction: AnonymizationMetadata;
|
|
121
|
+
}
|
|
122
|
+
interface GenerateEvidencePacketInput {
|
|
123
|
+
subject: EvidencePacketSubject;
|
|
124
|
+
/** Set to `false` to skip `resolveRelatedSubjects`. Defaults to `true`. */
|
|
125
|
+
includeRelated?: boolean;
|
|
126
|
+
/** Defaults to `DEFAULT_EVIDENCE_PACKET_TYPE`. */
|
|
127
|
+
packetType?: string;
|
|
128
|
+
policyVersion?: string;
|
|
129
|
+
}
|
|
130
|
+
interface GenerateEvidencePacketOptions {
|
|
131
|
+
port: EvidencePacketReadPort;
|
|
132
|
+
/**
|
|
133
|
+
* Redaction applied to the whole payload with data class `"evidence_packet"`. Required so that
|
|
134
|
+
* redaction cannot be skipped by omission; pass `{ fields: [] }` to redact nothing.
|
|
135
|
+
*/
|
|
136
|
+
anonymizationPolicy: AnonymizationPolicy;
|
|
137
|
+
anonymization?: {
|
|
138
|
+
/** Defaults to the packet id. */
|
|
139
|
+
jobId?: string;
|
|
140
|
+
/** Defaults to `DEFAULT_EVIDENCE_REDACTION_REASON`. */
|
|
141
|
+
reason?: string;
|
|
142
|
+
/** Defaults to the engine's `ANONYMIZATION_POLICY_VERSION`. */
|
|
143
|
+
policyVersion?: string;
|
|
144
|
+
};
|
|
145
|
+
/** Defaults to `createFabricId(FABRIC_ID_PREFIXES.complianceEvidencePacket)`. */
|
|
146
|
+
idFactory?: () => string;
|
|
147
|
+
}
|
|
148
|
+
type EvidencePacketGenerationErrorCode = "EVIDENCE_SCOPE_MISMATCH" | "EVIDENCE_INVALID_RECORD" | "EVIDENCE_UNREQUESTED_RECORD" | "EVIDENCE_IDENTIFIER_REDACTED";
|
|
149
|
+
declare class EvidencePacketGenerationError extends Error {
|
|
150
|
+
readonly code: EvidencePacketGenerationErrorCode;
|
|
151
|
+
constructor(code: EvidencePacketGenerationErrorCode, message: string);
|
|
152
|
+
}
|
|
153
|
+
/** Lowercase hex SHA-256 of `canonicalJson(payload)`. */
|
|
154
|
+
declare function computeEvidencePacketChecksum(payload: unknown): string;
|
|
155
|
+
/**
|
|
156
|
+
* Builds a sealed evidence packet for one subject from the application's read port.
|
|
157
|
+
*
|
|
158
|
+
* Steps: resolve subjects (primary first, then related, de-duplicated and sorted); read events,
|
|
159
|
+
* then the action invocations, policy evaluations and adapter invocations those events reference;
|
|
160
|
+
* reject any record outside `context.tenantId`/`context.spaceId`; normalize to plain JSON and sort
|
|
161
|
+
* deterministically; redact the payload with `AnonymizationEngine` (data class
|
|
162
|
+
* `"evidence_packet"`); checksum the redacted payload; and build references from it.
|
|
163
|
+
*
|
|
164
|
+
* Nothing is persisted. Storing the returned envelope is the application's job.
|
|
165
|
+
*/
|
|
166
|
+
declare function generateEvidencePacket<TDb = unknown>(input: GenerateEvidencePacketInput, context: EvidenceGenerationContext<TDb>, options: GenerateEvidencePacketOptions): Promise<EvidencePacketEnvelope<EvidencePacketPayload>>;
|
|
167
|
+
/**
|
|
168
|
+
* Recomputes an envelope's checksum. Returns `false`, never throws, when the checksum is missing,
|
|
169
|
+
* the algorithm is missing or unknown, the payload cannot be serialized, or the values differ.
|
|
170
|
+
* It covers `payload` only, which includes the subjects and the redaction metadata; the other
|
|
171
|
+
* envelope fields are not covered.
|
|
172
|
+
*/
|
|
173
|
+
declare function verifyEvidencePacketChecksum(envelope: Pick<EvidencePacketEnvelope<unknown>, "payload" | "checksum" | "checksumAlgorithm">): boolean;
|
|
174
|
+
type EvidencePacketRendererInput = Omit<GenerateEvidencePacketInput, "packetType">;
|
|
175
|
+
interface EvidencePacketRendererOptions extends GenerateEvidencePacketOptions {
|
|
176
|
+
packetType?: string;
|
|
177
|
+
}
|
|
178
|
+
/** Wraps `generateEvidencePacket` as an `EvidenceRenderer` for one packet type. */
|
|
179
|
+
declare function createEvidencePacketRenderer<TDb = unknown>(options: EvidencePacketRendererOptions): EvidenceRenderer<EvidencePacketRendererInput, EvidencePacketPayload, TDb>;
|
|
180
|
+
|
|
1
181
|
type EvidencePacketStatus = "draft" | "sealed" | "superseded";
|
|
2
182
|
interface EvidencePacketSubject {
|
|
3
183
|
subjectType: string;
|
|
@@ -23,6 +203,12 @@ interface EvidencePacketEnvelope<TPayload = Record<string, unknown>> {
|
|
|
23
203
|
generatedBy: string;
|
|
24
204
|
policyVersion?: string;
|
|
25
205
|
checksum?: string;
|
|
206
|
+
/**
|
|
207
|
+
* How `checksum` was computed. Packets built by `generateEvidencePacket` use
|
|
208
|
+
* `EVIDENCE_PACKET_CHECKSUM_ALGORITHM`. Optional and additive: envelopes built before this field
|
|
209
|
+
* existed omit it.
|
|
210
|
+
*/
|
|
211
|
+
checksumAlgorithm?: string;
|
|
26
212
|
correlationId: string;
|
|
27
213
|
causationId?: string;
|
|
28
214
|
}
|
|
@@ -40,4 +226,4 @@ interface EvidenceRenderer<TInput = unknown, TPayload = Record<string, unknown>,
|
|
|
40
226
|
render: (input: TInput, context: EvidenceGenerationContext<TDb>) => Promise<EvidencePacketEnvelope<TPayload>> | EvidencePacketEnvelope<TPayload>;
|
|
41
227
|
}
|
|
42
228
|
|
|
43
|
-
export type
|
|
229
|
+
export { DEFAULT_EVIDENCE_PACKET_TYPE, DEFAULT_EVIDENCE_REDACTION_REASON, EVIDENCE_PACKET_CHECKSUM_ALGORITHM, EVIDENCE_PACKET_SCHEMA_VERSION, type EvidenceEventQuery, type EvidenceEventRecord, type EvidenceGenerationContext, type EvidenceInvocationRecord, type EvidenceJsonRecord, type EvidencePacketEnvelope, EvidencePacketGenerationError, type EvidencePacketGenerationErrorCode, type EvidencePacketPayload, type EvidencePacketReadPort, type EvidencePacketReference, type EvidencePacketRendererInput, type EvidencePacketRendererOptions, type EvidencePacketStatus, type EvidencePacketSubject, type EvidenceRecord, type EvidenceRenderer, type EvidenceScope, type EvidenceTimestamp, type GenerateEvidencePacketInput, type GenerateEvidencePacketOptions, canonicalJson, computeEvidencePacketChecksum, createEvidencePacketRenderer, generateEvidencePacket, verifyEvidencePacketChecksum };
|
package/dist/evidence/index.js
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
-
|
|
1
|
+
export { DEFAULT_EVIDENCE_PACKET_TYPE, DEFAULT_EVIDENCE_REDACTION_REASON, EVIDENCE_PACKET_CHECKSUM_ALGORITHM, EVIDENCE_PACKET_SCHEMA_VERSION, EvidencePacketGenerationError, canonicalJson, computeEvidencePacketChecksum, createEvidencePacketRenderer, generateEvidencePacket, verifyEvidencePacketChecksum } from '../chunk-HEYMMVDP.js';
|
|
2
|
+
import '../chunk-RALMUSOX.js';
|
|
3
|
+
import '../chunk-TYNIFC7J.js';
|
|
2
4
|
//# sourceMappingURL=index.js.map
|
|
3
5
|
//# sourceMappingURL=index.js.map
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { ActorType } from '../actions/index.cjs';
|
|
2
2
|
import { EvidencePacketReference } from '../evidence/index.cjs';
|
|
3
3
|
import '../discovery/index.cjs';
|
|
4
|
+
import '../privacy/index.cjs';
|
|
4
5
|
|
|
5
6
|
/** Language-neutral governance contract version shared by TypeScript and .NET. */
|
|
6
7
|
declare const FABRIC_GOVERNANCE_CONTRACT_VERSION: 1;
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { ActorType } from '../actions/index.js';
|
|
2
2
|
import { EvidencePacketReference } from '../evidence/index.js';
|
|
3
3
|
import '../discovery/index.js';
|
|
4
|
+
import '../privacy/index.js';
|
|
4
5
|
|
|
5
6
|
/** Language-neutral governance contract version shared by TypeScript and .NET. */
|
|
6
7
|
declare const FABRIC_GOVERNANCE_CONTRACT_VERSION: 1;
|