@datafog/core-fogvault-node 0.0.0-stage → 1.0.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 DataFog
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,163 @@
1
- # Temporary Holding Version
1
+ # Optional native Node Core–FogVault integration
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ `@datafog/core-fogvault-node` owns the Rust Core–FogVault adapter in a native
4
+ N-API addon. Version `1.0.0` implements the reviewed Core Workspace contract 1;
5
+ production host and key-provider acceptance remain separate.
6
+ Existing `@datafog/node` remains independent and retains its Rust 1.88 floor.
7
+ This optional isolated package builds with Rust 1.94.1 and uses Node 24+.
8
+
9
+ ```sh
10
+ npm install --save-exact @datafog/core-fogvault-node@1.0.0
11
+ ```
12
+
13
+ ## Build and installed proof
14
+
15
+ From the Core repository root:
16
+
17
+ ```sh
18
+ npm ci --ignore-scripts --prefix integrations/fogvault-node
19
+ node integrations/fogvault-node/test/run-installed.mjs --output target/fogvault-node-installed.json
20
+ ```
21
+
22
+ That command builds a fresh release addon, runs Rust boundary tests, packs it,
23
+ installs the tarball into an isolated consumer without install scripts, compiles
24
+ positive/negative TypeScript usage, and executes the real installed addon against
25
+ synthetic SQLite/control namespaces. Source/tool/log, tarball and installed-addon
26
+ hashes are retained with the report. A local build packs one explicitly tagged
27
+ native binary and a checksum manifest. CI retains the actually qualified binary
28
+ from each existing runner (`ubuntu-24.04`, `macos-15`, `windows-2025`), checks their
29
+ source revision, public package files, installed tests and checksums, then assembles
30
+ one qualified archive. That archive is installed and exercised on
31
+ Linux without rebuilding its binaries. The assembly manifest records the exact
32
+ observed platform/architecture set, including the macOS runner's actual architecture.
33
+
34
+ The supported distribution scope is Linux x64 with GNU libc, Windows x64/MSVC,
35
+ and the macOS architecture actually provided and qualified by `macos-15` (arm64
36
+ or x64). This does not promise both macOS architectures in every archive. Linux
37
+ musl, Linux arm64 and all other unqualified targets fail with an informative
38
+ `unsupported_native_target` error; there is no download or source-build fallback.
39
+ A missing manifest, absent selected binary or checksum mismatch fails closed.
40
+ No registry package is published by assembly.
41
+ The package itself has no runtime npm dependencies. TypeScript is a pinned
42
+ repository-only development tool.
43
+
44
+ ## Create, review, save and reopen
45
+
46
+ ```js
47
+ import {randomBytes} from 'node:crypto';
48
+ import {NativeWorkspace} from '@datafog/core-fogvault-node';
49
+
50
+ const tenant = 'trusted-host-tenant-id';
51
+ const recordId = randomBytes(16), namespace = randomBytes(16);
52
+ const config = {
53
+ tenant,
54
+ protectedControlPath: '/host-established/protected/control',
55
+ vaultPath: '/host-selected/vault.sqlite',
56
+ password: Buffer.from('synthetic-example-only; obtain real bytes from host'),
57
+ recordId, namespace, profile: 'password_only',
58
+ };
59
+ const owner = NativeWorkspace.createNew({
60
+ ...config, operationId: randomBytes(16), requestId: randomBytes(16),
61
+ });
62
+ const text = 'alice@example.test';
63
+ const input = {
64
+ text,
65
+ scannerFindings: [{
66
+ entityType: 'EMAIL', matchedText: text,
67
+ range: {unit: 'utf8_bytes', start: 0, end: Buffer.byteLength(text)},
68
+ }],
69
+ userSelections: [], corrections: [],
70
+ };
71
+ const change = owner.prepareReview(tenant, [input], randomBytes(16));
72
+ const localPreview = change.previews(tenant); // Local review only.
73
+ // The host obtains literal user approval of this exact preview before continuing.
74
+ const committed = owner.commit(tenant, change, true, randomBytes(16));
75
+ // Only now may the host release committed.previews through its separate transport.
76
+ owner.close(tenant);
77
+ const reopened = NativeWorkspace.openExisting({...config, expectedHead: committed.head});
78
+ const restored = reopened.restore(tenant, committed.previews[0]);
79
+ reopened.close(tenant);
80
+ ```
81
+
82
+ The control namespace must have real OS protection independent of the vault
83
+ files. A second path or directory alone is not isolation. Paths, tenant identity,
84
+ passwords, IDs and records must come from trusted host routing, not arbitrary
85
+ HTTP request fields. `createNew` requires a fresh control namespace and new vault;
86
+ `openExisting` never creates missing state. The default admission is 16 MiB Core
87
+ payload, 88 metadata bytes and 64 vault records; `maxPayloadBytes` can lower the
88
+ host's admitted payload ceiling. This does not establish a peak-memory budget.
89
+
90
+ Tenant-first calls check the exact captured tenant and creator thread. Those
91
+ checks catch host routing errors; they are not user authentication or filesystem
92
+ authorization. Keep an owner on its creating Node worker/isolate, serialize its
93
+ requests and reject stale/cancelled worker replies before network release. Native
94
+ KDF/storage calls are synchronous; this package does not move them to a worker
95
+ or provide global server admission. A cloned JS owner cannot become a new native
96
+ capability. No unsafe Send/Sync implementation is used.
97
+
98
+ IDs are exact byte values. Heads, receipt generations and record revisions are
99
+ lossless canonical decimal strings; do not convert them through Number. JSON
100
+ results carry ID arrays, which the host can copy into Uint8Array when needed.
101
+ Only ordinary copied buffers/plain DTOs are accepted. Proxies, accessors, shared
102
+ buffers, lossy numbers, malformed Unicode and forged/foreign handles reject.
103
+ Native-owned temporary password copies are wiped; host-owned input/output and
104
+ foreign copies remain the host's cleanup responsibility. Password bytes are not
105
+ normalized or serialized into JSON. Non-password access profiles reject with
106
+ `unsupported_profile`; the factory does not provide device fallback or hardware
107
+ claims.
108
+
109
+ ## Lifecycle, restoration and recovery
110
+
111
+ Each owner admits one active prepared change. A second preparation returns
112
+ `resource_limit` before cloning Core state; read-only review remains available.
113
+ Discard, confirmed consumption, collection of an abandoned handle, or owner
114
+ lock/close releases admission. Keep explicit discard/close in application code;
115
+ garbage collection has no timing guarantee. This per-owner bound does not provide
116
+ aggregate server, model, stream or device memory admission.
117
+
118
+ `PreparedChange` and restore streams are opaque, owner-bound handles. The addon
119
+ uses the existing Rust Owner for all save, complete-head/record CAS, activation,
120
+ lock and uncertain-outcome authority. Raw Workspace/Vault handles, plaintext
121
+ bundle export and direct activation are not public exports. Local previews are
122
+ sensitive views, never a grant to bypass host approval.
123
+
124
+ Conversation preparation, observed-send and definite-non-delivery resolutions
125
+ use the same saved path. Only actual matching trusted host observation may claim
126
+ a send succeeded. Pending conversations remain blocked across reopen; unscoped
127
+ restore is not a fallback around scoped failure. Reports return null text when
128
+ marker issues block restoration. Strict streams buffer until finalization;
129
+ progressive streams are explicit irreversible output. Wrong feed transport is
130
+ terminated through Core's error path and retains prior progressive delivery
131
+ counts without failing-call text. Lock closes owned Core state/plans/streams;
132
+ caller copies cannot be retracted. Call `discard` on unused plans and `close` on
133
+ streams and owners for deterministic cleanup. Abandoned plan/stream wrappers
134
+ also release their native handles after JavaScript garbage collection; timing
135
+ is not guaranteed. A retained child keeps its owner alive, so dropping only the
136
+ owner variable is not a lock operation. Explicit lock/close always revokes all
137
+ children, including retained children.
138
+
139
+ Unknown-save errors retain `requestId` and `requiresReopen`. Keep the operation
140
+ identity in trusted host state. `owner.reconcile(tenant, requestId)` leaves Core
141
+ closed. After process loss, `NativeWorkspace.reconcileExisting` opens only the
142
+ registered locked vault and reconciles the exact request, returning a receipt
143
+ without plaintext or Core activation. Authenticate/open a fresh owner afterward;
144
+ never resend automatically or reuse an old approval. The dropped-ack installed
145
+ test discards an actual successful return; it is not a power-cut experiment.
146
+
147
+ `prepareRecovery` stages Core's same-vault recovery workflow. The separate
148
+ `importAuthenticatedBundle` factory accepts only a previously authenticated,
149
+ decrypted Core bundle with its exact source namespace/head, explicit approval
150
+ and a fresh destination. It delegates validation to the migration crate and
151
+ publication to the Rust Owner, creates fresh destination keys, and never
152
+ transplants legacy credentials. It does not decrypt legacy archives or establish
153
+ source authenticity itself. Final v1 schema migration remains a release gate.
154
+
155
+ ## Evidence limits
156
+
157
+ Local installed tests do not qualify another OS, real key-provider hardware,
158
+ power loss, production tenant routing, deployment permissions, peak memory or
159
+ signed registry publication. Rust dependency and licensing/release review must
160
+ cover the final distributed binary. Root CI and joint release qualification are
161
+ separate. N-API pins match Core; the derive backend is constrained to Core's
162
+ 6.1.2 version because a newer compatible-range backend moved its syn ABI beyond
163
+ pinned napi-derive 3.6.3.
package/index.d.ts ADDED
@@ -0,0 +1,72 @@
1
+ export type Id = Uint8Array;
2
+ export interface Head { revision:string; commitId:readonly number[] }
3
+ export interface HeadInput {revision:string; commitId:Uint8Array|readonly number[]}
4
+ export interface Receipt {generation:string;requestId:readonly number[];headDigest:readonly number[]}
5
+ export interface FactoryOptions {tenant:string;protectedControlPath:string;vaultPath:string;password:Uint8Array;recordId:Id;namespace:Id;profile?:'password_only';maxPayloadBytes?:number}
6
+ export interface CreateOptions extends FactoryOptions {operationId:Id;requestId:Id}
7
+ export interface OpenOptions extends FactoryOptions {expectedHead?:HeadInput}
8
+ export interface ImportOptions extends CreateOptions {sourceHead:HeadInput}
9
+ export type ReconcileOptions = Omit<FactoryOptions,'password'>;
10
+ export interface Range {start:number;end:number}
11
+ export interface Finding {entityType:string;matchedText:string;range:Range&{unit:'utf8_bytes'};confidence?:number|null;detectorName?:string|null;detectorVersion?:string|null;source?:'scanner'|'recall'|'user';needsReview?:boolean}
12
+ export interface ReviewInput {text:string;scannerFindings:readonly Finding[];userSelections:readonly Finding[];corrections?:readonly {candidateKey:string;replacement:Finding}[]}
13
+ export interface Operation {id:Id|readonly number[];occurredAtMs:number}
14
+ export interface Conversation {id:Id|readonly number[];surface:string;siteId:string|null;siteIdByteBudget:number}
15
+ export interface SendInput {input:ReviewInput;conversation:Conversation}
16
+ export interface SendIntent {preparationId:readonly number[];inputIndex:number}
17
+ export interface MarkerIssue {kind:string;byteRange:Range;codepointRange:Range;utf16Range:Range}
18
+ export interface RestoreReport {text:string|null;restoredMarkers:number;issues:MarkerIssue[]}
19
+ export interface Transformation {source:string;needsReview:boolean;sourceByteRange:Range;sourceCodepointRange:Range;sourceUtf16Range:Range;outputByteRange:Range;outputCodepointRange:Range;outputUtf16Range:Range}
20
+ export interface Preview {text:string;transformations:Transformation[]}
21
+ export interface OperationRecord {id:readonly number[];kind:string;occurredAtMs:number|null;preparedInputs:number;transformedSpans:number}
22
+ export interface Counts {operations:number;preparedInputs:number;transformedSpans:number;confirmedHandoffs:number;reportedBlockedAttempts:number}
23
+ export interface Committed {head:Head;receipt:Receipt;recordRevision:string;previews:string[]}
24
+ export interface PolicyEdits {rules:readonly {entityType:string;rule:'hide'|'keep'|null}[];choices:readonly {entityType:string;value:string;disposition:'keep'|'not_sensitive'|null}[]}
25
+ export interface Delivered {bytes:number;codepoints:number;utf16:number;restoredMarkers:number}
26
+ export interface RestoreChunk {text:string;complete:boolean;delivered:Delivered}
27
+ export class DataFogVaultError extends Error {readonly code:string;readonly requestId?:readonly number[];readonly requiresReopen?:boolean;readonly markerIssues?:MarkerIssue[];readonly complete?:boolean;readonly delivered?:Delivered}
28
+ export class PreparedChange {
29
+ private constructor();
30
+ previews(tenant:string):Preview[];
31
+ heads(tenant:string):{parent:Head;candidate:Head};
32
+ sendIntents(tenant:string):SendIntent[];
33
+ snapshotFormat(tenant:string):{currentVersion:number;candidateVersion:number};
34
+ policyPreview(tenant:string):unknown;
35
+ discard(tenant:string):void;
36
+ }
37
+ export class RestoreStream {
38
+ private constructor();
39
+ feed(tenant:string,value:Uint8Array|Uint16Array):null|RestoreChunk;
40
+ finalize(tenant:string):RestoreReport|RestoreChunk;
41
+ reset(tenant:string):void;
42
+ close(tenant:string):void;
43
+ }
44
+ export class NativeWorkspace {
45
+ private constructor();
46
+ static createNew(options:CreateOptions):NativeWorkspace;
47
+ static openExisting(options:OpenOptions):NativeWorkspace;
48
+ static importAuthenticatedBundle(options:ImportOptions,bundle:Uint8Array,approved:true):NativeWorkspace;
49
+ static reconcileExisting(options:ReconcileOptions,requestId:Id):Receipt;
50
+ head(tenant:string):Head;
51
+ counts(tenant:string):Counts;
52
+ historyCoverage(tenant:string):{recordedHistoryOnly:boolean;preUpgradeHistory:'unknown'|'not_applicable'};
53
+ policy(tenant:string):unknown;
54
+ operationsPage(tenant:string,offset:number,limit:number):{records:OperationRecord[];total:number;offset:number;nextOffset:number|null};
55
+ review(tenant:string,input:ReviewInput):{head:Head;candidates:unknown[];conflicts:unknown[]};
56
+ prepareReview(tenant:string,inputs:readonly ReviewInput[],operationId:Id):PreparedChange;
57
+ prepareConversationSend(tenant:string,inputs:readonly SendInput[],operation:Operation):PreparedChange;
58
+ prepareObservedSend(tenant:string,intent:SendIntent,logicalId:Id,surface:string,siteId:string,operation:Operation):PreparedChange;
59
+ prepareDefinitelyNotSent(tenant:string,intent:SendIntent,logicalId:Id,operation:Operation):PreparedChange;
60
+ preparePolicyChanges(tenant:string,edits:PolicyEdits,operationId:Id):PreparedChange;
61
+ prepareRecovery(tenant:string,operationId:Id):PreparedChange;
62
+ commit(tenant:string,change:PreparedChange,approved:true,requestId:Id):Committed;
63
+ reconcile(tenant:string,requestId:Id):Receipt;
64
+ restore(tenant:string,text:string):string;
65
+ restoreReport(tenant:string,text:string):RestoreReport;
66
+ restoreInConversation(tenant:string,text:string,logicalId:Id):string;
67
+ restoreReportInConversation(tenant:string,text:string,logicalId:Id):RestoreReport;
68
+ bufferedRestore(tenant:string,encoding?:'utf8'|'utf16',logicalId?:Id):RestoreStream;
69
+ progressiveRestore(tenant:string,encoding?:'utf8'|'utf16',logicalId?:Id):RestoreStream;
70
+ lock(tenant:string):void;
71
+ close(tenant:string):void;
72
+ }
package/index.mjs ADDED
@@ -0,0 +1,140 @@
1
+ import {loadNative} from './native-loader.mjs';
2
+ import {types} from 'node:util';
3
+ const {NativeOwner}=loadNative();
4
+ const owners=new WeakMap(), changes=new WeakMap(), streams=new WeakMap();
5
+ // Held values retain the owner, never their target. Cleanup only releases
6
+ // abandoned handles; it cannot save, activate or approve a candidate.
7
+ const abandoned=new FinalizationRegistry(({owner,handle,method})=>{
8
+ const state=owners.get(owner);
9
+ if(!state)return;
10
+ try{state.raw.call(state.tenant,method,JSON.stringify(method==='discard'?handle:{handle}));}catch{/* Explicit lock/close may already have revoked it. */}
11
+ });
12
+ const internal=Symbol('Core FogVault owner construction');
13
+ const MAX=16*1024*1024;
14
+ export class DataFogVaultError extends Error {
15
+ constructor(code, detail={}) {super(code);this.name='DataFogVaultError';this.code=code;Object.assign(this,detail);}
16
+ }
17
+ const fail=code=>{throw new DataFogVaultError(code);};
18
+ function plain(value,depth=0,budget={items:0}) {
19
+ if(depth>32||++budget.items>300000)fail('resource_limit');
20
+ if(value===null||typeof value==='boolean')return value;
21
+ if(typeof value==='string'){if(!value.isWellFormed())fail('invalid_encoding');if(Buffer.byteLength(value)>MAX)fail('resource_limit');return value;}
22
+ if(typeof value==='number'){if(!Number.isFinite(value)||(Number.isInteger(value)&&!Number.isSafeInteger(value)))fail('invalid_transport');return value;}
23
+ if(typeof value!=='object'||types.isProxy(value))fail('invalid_transport');
24
+ if(value instanceof Uint8Array){return Array.from(bytes(value));}
25
+ if(value instanceof Uint16Array){safeTyped(value,Uint16Array.prototype);if(value.byteLength>MAX)fail('resource_limit');return Array.from(value);}
26
+ const prototype=Object.getPrototypeOf(value);
27
+ const array=Array.isArray(value);
28
+ if(array?prototype!==Array.prototype:prototype!==Object.prototype&&prototype!==null)fail('invalid_transport');
29
+ const descriptors=Object.getOwnPropertyDescriptors(value),out=array?[]:{};
30
+ for(const key of Reflect.ownKeys(descriptors)){
31
+ if(array&&key==='length')continue;
32
+ if(typeof key!=='string'||key==='__proto__'||key==='constructor'||key==='prototype')fail('invalid_transport');
33
+ const d=descriptors[key];if(!('value' in d)||!d.enumerable)fail('invalid_transport');
34
+ if(array&&(!/^(0|[1-9][0-9]*)$/.test(key)||Number(key)>=value.length))fail('invalid_transport');
35
+ out[key]=plain(d.value,depth+1,budget);
36
+ }
37
+ if(array&&Object.keys(out).length!==value.length)fail('invalid_transport');
38
+ return out;
39
+ }
40
+ function serialized(value){const out=JSON.stringify(plain(value));if(Buffer.byteLength(out)>MAX)fail('resource_limit');return out;}
41
+ function error(e){if(e instanceof DataFogVaultError)return e;try{const d=JSON.parse(e.message);if(typeof d.code==='string')return new DataFogVaultError(d.code,d);}catch{}return new DataFogVaultError('native_error');}
42
+ function safeTyped(value,prototype){
43
+ if(types.isProxy(value)||Object.getPrototypeOf(value)!==prototype)fail('invalid_transport');
44
+ for(const key of ['buffer','byteLength','byteOffset','length','constructor',Symbol.iterator])if(Object.hasOwn(value,key))fail('invalid_transport');
45
+ if(!(value.buffer instanceof ArrayBuffer)||types.isSharedArrayBuffer(value.buffer)||value.buffer.detached)fail('invalid_transport');
46
+ }
47
+ function bytes(value,length,maximum=MAX){
48
+ if(!(value instanceof Uint8Array))fail('invalid_transport');
49
+ safeTyped(value,Buffer.isBuffer(value)?Buffer.prototype:Uint8Array.prototype);
50
+ if(length!==undefined&&value.length!==length)fail('invalid_transport');
51
+ if(value.byteLength>maximum)fail('resource_limit');return Buffer.from(value);
52
+ }
53
+ function id(value){return Array.from(bytes(value,16));}
54
+ function tenant(value){if(typeof value!=='string'||!value.isWellFormed()||!value.length||Buffer.byteLength(value)>128||/\p{Cc}/u.test(value))fail('invalid_tenant');return value;}
55
+ function state(owner){const s=owners.get(owner);if(!s)fail('invalid_owner');return s;}
56
+ function call(owner,t,method,value=null){const s=state(owner);tenant(t);try{return JSON.parse(s.raw.call(t,method,serialized(value)));}catch(e){throw error(e);}}
57
+ function factory(options,mode,bundle,approved){
58
+ if(!options||typeof options!=='object'||types.isProxy(options)||![Object.prototype,null].includes(Object.getPrototypeOf(options)))fail('invalid_configuration');
59
+ const descriptors=Object.getOwnPropertyDescriptors(options),config={};let originalPassword;
60
+ for(const key of Reflect.ownKeys(descriptors)){
61
+ const d=descriptors[key];if(typeof key!=='string'||!('value' in d)||!d.enumerable||['__proto__','constructor','prototype'].includes(key))fail('invalid_transport');
62
+ if(key==='password')originalPassword=d.value;else config[key]=d.value;
63
+ }
64
+ const data=plain(config);
65
+ const creating=mode==='createNew'||mode==='importAuthenticatedBundle';
66
+ const allowed=creating?['tenant','protectedControlPath','vaultPath','recordId','namespace','operationId','requestId','profile','maxPayloadBytes',...(mode==='importAuthenticatedBundle'?['sourceHead']:[])]:['tenant','protectedControlPath','vaultPath','recordId','namespace','expectedHead','profile','maxPayloadBytes'];
67
+ if(Object.keys(data).some(k=>!allowed.includes(k)))fail('invalid_configuration');tenant(data.tenant);
68
+ for(const key of ['recordId','namespace',...(creating?['operationId','requestId']:[])]){
69
+ if(!Array.isArray(data[key])||data[key].length!==16||data[key].some(v=>!Number.isInteger(v)||v<0||v>255))fail('invalid_transport');
70
+ }
71
+ if('profile' in data&&typeof data.profile!=='string')fail('invalid_configuration');
72
+ if('maxPayloadBytes' in data&&(!Number.isSafeInteger(data.maxPayloadBytes)||data.maxPayloadBytes<64||data.maxPayloadBytes>MAX))fail('invalid_configuration');
73
+ if('expectedHead' in data&&(data.expectedHead===null||typeof data.expectedHead.revision!=='string'||!/^(0|[1-9][0-9]*)$/.test(data.expectedHead.revision)))fail('invalid_head');
74
+ if(mode==='importAuthenticatedBundle'){if(approved!==true)fail('approval_required');data.approved=true;if(!data.sourceHead||typeof data.sourceHead.revision!=='string')fail('invalid_head');}
75
+ const password=bytes(originalPassword,undefined,1024);let source;
76
+ try{if(password.length>1024)fail('resource_limit');if(mode==='importAuthenticatedBundle')source=bytes(bundle);return new NativeWorkspace(internal,source?NativeOwner[mode](serialized(data),password,source):NativeOwner[mode](serialized(data),password),data.tenant);}catch(e){throw error(e);}finally{password.fill(0);source?.fill(0);}
77
+ }
78
+ export class NativeWorkspace {
79
+ constructor(token,raw,tenant){if(token!==internal)fail('invalid_owner');owners.set(this,{raw,tenant});Object.freeze(this);}
80
+ static createNew(options){return factory(options,'createNew');}
81
+ static openExisting(options){return factory(options,'openExisting');}
82
+ static importAuthenticatedBundle(options,bundle,approved){return factory(options,'importAuthenticatedBundle',bundle,approved);}
83
+ static reconcileExisting(options,requestId){if(!options||typeof options!=='object'||types.isProxy(options))fail('invalid_configuration');const keys=Reflect.ownKeys(Object.getOwnPropertyDescriptors(options));if(keys.some(k=>!['tenant','protectedControlPath','vaultPath','recordId','namespace','profile','maxPayloadBytes'].includes(k)))fail('invalid_configuration');const data=plain(options);tenant(data.tenant);try{return JSON.parse(NativeOwner.reconcileExisting(serialized(data),bytes(requestId,16)));}catch(e){throw error(e);}}
84
+ head(t){return call(this,t,'head');}
85
+ counts(t){return call(this,t,'counts');}
86
+ historyCoverage(t){return call(this,t,'historyCoverage');}
87
+ policy(t){return call(this,t,'policy');}
88
+ operationsPage(t,offset,limit){return call(this,t,'operationsPage',{offset,limit});}
89
+ review(t,input){return call(this,t,'review',input);}
90
+ prepareReview(t,inputs,operationId){return stage(this,t,'prepareReview',{inputs,operationId:id(operationId)});}
91
+ prepareConversationSend(t,inputs,operation){return stage(this,t,'prepareConversationSend',{inputs,operation});}
92
+ prepareObservedSend(t,intent,logicalId,surface,siteId,operation){return stage(this,t,'prepareObservedSend',{intent,logicalId:id(logicalId),surface,siteId,operation});}
93
+ prepareDefinitelyNotSent(t,intent,logicalId,operation){return stage(this,t,'prepareDefinitelyNotSent',{intent,logicalId:id(logicalId),operation});}
94
+ preparePolicyChanges(t,edits,operationId){return stage(this,t,'preparePolicyChanges',{edits,operationId:id(operationId)});}
95
+ prepareRecovery(t,operationId){return stage(this,t,'prepareRecovery',id(operationId));}
96
+ commit(t,change,approved,requestId){
97
+ if(approved!==true)fail('approval_required');
98
+ const c=changes.get(change);if(!c||c.owner!==this)fail('foreign_change');
99
+ const result=call(this,t,'commit',{handle:c.handle,approved:true,requestId:id(requestId)});
100
+ abandoned.unregister(change);changes.delete(change);return result;
101
+ }
102
+ reconcile(t,requestId){return call(this,t,'reconcile',id(requestId));}
103
+ restore(t,text){return call(this,t,'restore',text);}
104
+ restoreReport(t,text){return call(this,t,'restoreReport',text);}
105
+ restoreInConversation(t,text,logicalId){return call(this,t,'restoreInConversation',{text,logicalId:id(logicalId)});}
106
+ restoreReportInConversation(t,text,logicalId){return call(this,t,'restoreReportInConversation',{text,logicalId:id(logicalId)});}
107
+ bufferedRestore(t,encoding='utf8',logicalId){return stream(this,t,false,encoding,logicalId);}
108
+ progressiveRestore(t,encoding='utf8',logicalId){return stream(this,t,true,encoding,logicalId);}
109
+ lock(t){return call(this,t,'lock');}
110
+ close(t){return call(this,t,'close');}
111
+ }
112
+ function stage(owner,t,method,args){const {handle}=call(owner,t,method,args);return new PreparedChange(internal,owner,handle);}
113
+ export class PreparedChange {
114
+ constructor(token,owner,handle){if(token!==internal)fail('foreign_change');changes.set(this,{owner,handle});abandoned.register(this,{owner,handle,method:'discard'},this);Object.freeze(this);}
115
+ #call(t,method){const c=changes.get(this);if(!c)fail('inactive_plan');return call(c.owner,t,method,c.handle);}
116
+ previews(t){return this.#call(t,'previews');}
117
+ heads(t){return this.#call(t,'planHeads');}
118
+ sendIntents(t){return this.#call(t,'sendIntents');}
119
+ snapshotFormat(t){return this.#call(t,'snapshotFormat');}
120
+ policyPreview(t){return this.#call(t,'policyPreview');}
121
+ discard(t){this.#call(t,'discard');abandoned.unregister(this);changes.delete(this);}
122
+ }
123
+ function stream(owner,t,progressive,encoding,logicalId){const data={progressive,encoding};if(logicalId!==undefined)data.logicalId=id(logicalId);const{handle}=call(owner,t,'stream',data);return new RestoreStream(internal,owner,handle,encoding);}
124
+ export class RestoreStream {
125
+ constructor(token,owner,handle,encoding){if(token!==internal)fail('inactive_stream');streams.set(this,{owner,handle,encoding});abandoned.register(this,{owner,handle,method:'streamClose'},this);Object.freeze(this);}
126
+ #call(t,method,data={}){const s=streams.get(this);if(!s)fail('inactive_stream');return call(s.owner,t,method,{handle:s.handle,...data});}
127
+ feed(t,value){
128
+ const s=streams.get(this);if(!s)fail('inactive_stream');
129
+ this.#call(t,'streamCheck');
130
+ let copy;
131
+ try{
132
+ if(s.encoding==='utf8')copy=bytes(value);
133
+ else{if(!(value instanceof Uint16Array))fail('invalid_transport');safeTyped(value,Uint16Array.prototype);if(value.byteLength>MAX)fail('resource_limit');copy=Buffer.alloc(value.byteLength);for(let i=0;i<value.length;i++)copy.writeUInt16LE(value[i],i*2);}
134
+ }catch(e){try{this.#call(t,'streamPoison',{utf16:s.encoding==='utf16'});}catch(failure){throw failure;}throw error(e);}
135
+ try{return JSON.parse(state(s.owner).raw.feed(t,s.handle,copy,s.encoding==='utf16'));}catch(e){throw error(e);}finally{copy.fill(0);}
136
+ }
137
+ finalize(t){return this.#call(t,'streamFinalize');}
138
+ reset(t){return this.#call(t,'streamReset');}
139
+ close(t){this.#call(t,'streamClose');abandoned.unregister(this);streams.delete(this);}
140
+ }
@@ -0,0 +1,60 @@
1
+ {
2
+ "schema": "datafog-fogvault-node-artifacts/v1",
3
+ "version": "1.0.0",
4
+ "artifacts": [
5
+ {
6
+ "target": "darwin-arm64",
7
+ "file": "datafog-fogvault.darwin-arm64.node",
8
+ "sha256": "5a2509a39f2c0868d92371be83462c9ece9864984192929c97bde117506f2ff2",
9
+ "sourceFiles": {
10
+ "index.mjs": "3f0ee108a2e09becc938dbf85d00c3140600fe64fe0a4b794a00f28b7e6f6db5",
11
+ "index.d.ts": "4e7ef6ef1530196ad0243e19090f68a771f847f302b1b488901e076b0180ee8c",
12
+ "native-loader.mjs": "0c000552210f48e229b3632f9cf32b6d69e3351dc295bfafd65a800980c1759d",
13
+ "package.json": "925710d8c720f2ce9f478fa11e280f12f5087fca7c56b2320ce2a6feaac05f4d",
14
+ "README.md": "acd1747bf0af198b758c5fba988926f9f74bfc218feb45b336c2bc3e32c20a98",
15
+ "LICENSE": "ce1ff3fa2e2167f504b4c9b6ca3875cecc7e69ce072b4e1dcf61028781fa75bc"
16
+ },
17
+ "revision": "4c2531525497da612b79aa889cf182e8f3094b32",
18
+ "runnerScope": "macos-15",
19
+ "platform": "darwin",
20
+ "arch": "arm64",
21
+ "libc": null
22
+ },
23
+ {
24
+ "target": "linux-x64-gnu",
25
+ "file": "datafog-fogvault.linux-x64-gnu.node",
26
+ "sha256": "c2006de7dd52cb6189df3217ce4ab68e8348147800ff39d1f377141f203b813d",
27
+ "sourceFiles": {
28
+ "index.mjs": "3f0ee108a2e09becc938dbf85d00c3140600fe64fe0a4b794a00f28b7e6f6db5",
29
+ "index.d.ts": "4e7ef6ef1530196ad0243e19090f68a771f847f302b1b488901e076b0180ee8c",
30
+ "native-loader.mjs": "0c000552210f48e229b3632f9cf32b6d69e3351dc295bfafd65a800980c1759d",
31
+ "package.json": "925710d8c720f2ce9f478fa11e280f12f5087fca7c56b2320ce2a6feaac05f4d",
32
+ "README.md": "acd1747bf0af198b758c5fba988926f9f74bfc218feb45b336c2bc3e32c20a98",
33
+ "LICENSE": "ce1ff3fa2e2167f504b4c9b6ca3875cecc7e69ce072b4e1dcf61028781fa75bc"
34
+ },
35
+ "revision": "4c2531525497da612b79aa889cf182e8f3094b32",
36
+ "runnerScope": "ubuntu-24.04",
37
+ "platform": "linux",
38
+ "arch": "x64",
39
+ "libc": "gnu"
40
+ },
41
+ {
42
+ "target": "win32-x64-msvc",
43
+ "file": "datafog-fogvault.win32-x64-msvc.node",
44
+ "sha256": "fad42ba8fb8c529413bd206da5fa61bc824c0d5e6da1ca4cdd3d37d6b27cd90c",
45
+ "sourceFiles": {
46
+ "index.mjs": "3f0ee108a2e09becc938dbf85d00c3140600fe64fe0a4b794a00f28b7e6f6db5",
47
+ "index.d.ts": "4e7ef6ef1530196ad0243e19090f68a771f847f302b1b488901e076b0180ee8c",
48
+ "native-loader.mjs": "0c000552210f48e229b3632f9cf32b6d69e3351dc295bfafd65a800980c1759d",
49
+ "package.json": "925710d8c720f2ce9f478fa11e280f12f5087fca7c56b2320ce2a6feaac05f4d",
50
+ "README.md": "acd1747bf0af198b758c5fba988926f9f74bfc218feb45b336c2bc3e32c20a98",
51
+ "LICENSE": "ce1ff3fa2e2167f504b4c9b6ca3875cecc7e69ce072b4e1dcf61028781fa75bc"
52
+ },
53
+ "revision": "4c2531525497da612b79aa889cf182e8f3094b32",
54
+ "runnerScope": "windows-2025",
55
+ "platform": "win32",
56
+ "arch": "x64",
57
+ "libc": null
58
+ }
59
+ ]
60
+ }
@@ -0,0 +1,37 @@
1
+ // Private distribution boundary. No install-time download or source-build fallback.
2
+ import {createRequire} from 'node:module';
3
+ import {readFileSync} from 'node:fs';
4
+ import {createHash} from 'node:crypto';
5
+ import {fileURLToPath} from 'node:url';
6
+ import path from 'node:path';
7
+ export const nativeFiles = ['index.mjs','index.d.ts','native-loader.mjs','package.json','README.md','LICENSE'];
8
+ const allowed = new Set(['linux-x64-gnu','darwin-arm64','darwin-x64','win32-x64-msvc']);
9
+ const failure = message => {const error = new Error(message);error.code='unsupported_native_target';throw error;};
10
+ export function nativeTarget(platform=process.platform, arch=process.arch, header=process.report.getReport().header) {
11
+ if(platform==='linux' && !header.glibcVersionRuntime)failure('Core FogVault Node supports GNU libc on Linux; musl is not qualified.');
12
+ const target=`${platform}-${arch}${platform==='linux'?'-gnu':platform==='win32'?'-msvc':''}`;
13
+ if(!allowed.has(target))failure(`Core FogVault Node has no qualified target for ${target}.`);
14
+ return target;
15
+ }
16
+ export const artifactFile = target => `datafog-fogvault.${target}.node`;
17
+ export const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
18
+ export function validateArtifacts(manifest, version) {
19
+ if(manifest?.schema!=='datafog-fogvault-node-artifacts/v1' || manifest.version!==version || !Array.isArray(manifest.artifacts) || !manifest.artifacts.length)throw Error('Invalid Core FogVault native artifact manifest');
20
+ const seen=new Set();
21
+ for(const entry of manifest.artifacts){
22
+ if(!allowed.has(entry.target)||seen.has(entry.target)||entry.file!==artifactFile(entry.target)||!/^[a-f0-9]{64}$/.test(entry.sha256)||!entry.sourceFiles||typeof entry.sourceFiles!=='object')throw Error('Invalid or duplicate Core FogVault native artifact');
23
+ seen.add(entry.target);
24
+ }
25
+ return manifest;
26
+ }
27
+ export function loadNative() {
28
+ const root=path.dirname(fileURLToPath(import.meta.url));
29
+ const pkg=JSON.parse(readFileSync(path.join(root,'package.json'),'utf8'));
30
+ const manifest=validateArtifacts(JSON.parse(readFileSync(path.join(root,'native-artifacts.json'),'utf8')),pkg.version);
31
+ const target=nativeTarget();
32
+ const entry=manifest.artifacts.find(item=>item.target===target);
33
+ if(!entry)failure(`Core FogVault Node archive does not include ${target}; available: ${manifest.artifacts.map(item=>item.target).join(', ')}.`);
34
+ const file=path.join(root,entry.file);
35
+ if(sha256(readFileSync(file))!==entry.sha256)throw Error('Core FogVault native binary checksum mismatch');
36
+ return createRequire(import.meta.url)(file);
37
+ }
package/package.json CHANGED
@@ -1,6 +1,41 @@
1
1
  {
2
2
  "name": "@datafog/core-fogvault-node",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.0",
4
+ "type": "module",
5
+ "description": "Optional native Core\u2013FogVault integration candidate",
6
+ "license": "MIT",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/DataFog/datafog-core.git"
10
+ },
11
+ "engines": {
12
+ "node": ">=24"
13
+ },
14
+ "exports": {
15
+ ".": {
16
+ "types": "./index.d.ts",
17
+ "import": "./index.mjs"
18
+ }
19
+ },
20
+ "files": [
21
+ "index.mjs",
22
+ "index.d.ts",
23
+ "README.md",
24
+ "LICENSE",
25
+ "native-loader.mjs",
26
+ "native-artifacts.json",
27
+ "datafog-fogvault.*.node"
28
+ ],
29
+ "scripts": {
30
+ "build": "node scripts/build.mjs",
31
+ "test": "node scripts/test-package.mjs",
32
+ "test:package": "node scripts/test-package.mjs"
33
+ },
34
+ "devDependencies": {
35
+ "typescript": "7.0.2"
36
+ },
37
+ "publishConfig": {
38
+ "access": "public",
39
+ "tag": "latest"
40
+ }
41
+ }