@datafog/core-fogvault-legacy-browser 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DataFog
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# Import supported Core reference backups
 
-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.
+This optional `1.0.0` package reads only the non-shipping Core
+workspace example's `datafog-workspace-backup` envelope versions 1 and 2. It
+**does not establish compatibility with an unidentified shipping extension**.
+Backup envelope versions are separate from the Core snapshot decoder versions.
+
+```sh
+npm install --save-exact @datafog/core-fogvault-legacy-browser@1.0.0
+```
+
+`LegacyBackupImport.open` authenticates the complete canonical archive, decrypts
+it using the existing legacy algorithms, and validates its namespace/full head
+through the initialized actual Core WASM decoder. The returned opaque session
+exposes metadata/counts, not a plaintext bundle or legacy keys. `commit` requires
+literal `approved: true`, fresh request/operation/record IDs and a fresh unlocked
+FogVault destination. The existing browser adapter owns recovery, exact save,
+activation, record/head CAS, occupied-destination rejection and reconciliation.
+Source archive bytes are borrowed unchanged; only importer-owned copies are wiped.
+
+```js
+const staged = await LegacyBackupImport.open({Workspace, archive, credential,
+  method: 'password', signal: controller.signal});
+const metadata = staged.preview(); // Review locally before approval.
+const owner = await staged.commit({vault: freshUnlockedVault, recordId,
+  operationId, requestId, approved: true});
+// owner is the maintained FogVaultWorkspace facade.
+```
+
+Password strings preserve the reference format's exact UTF-8 bytes, without
+normalization; recovery codes use its existing DFR1 syntax. The original fixed
+Argon2id v1.3/t3/p1 profiles remain 64 MiB (v1) and 256 MiB (v2), with no cheaper
+fallback. Recovery uses the original HKDF-SHA-256/AES-GCM path. The importer uses
+an actual disposable bundled libsodium worker and WebCrypto, not another crypto
+implementation. `vault-read.mjs`, `backup-read.mjs` and the worker derive directly
+from `examples/workspace-extension/src/{vault.js,backup.js,kdf-worker.js}`; only
+read/authenticate helpers are retained. The original example remains the fixture
+producer, so tests do not validate an importer against its own serializer.
+
+Call `close` or abort the supplied signal to discard a session. Cancellation
+terminates a pending KDF; after publication starts it locks the exclusive fresh
+destination. A late persisted save may require receipt reconciliation and fresh
+reopen; cancellation never promises rollback. Uncertain publication returns
+`import_requires_reopen` with the exact request ID and `requiresReopen: true`.
+A cleanup failure cannot hide that outcome: the error also carries
+`cleanupFailed: true`; explicit close reports content-free `cleanup_failed`. Successful commit consumes the
+session and removes its abort listener, so later cancellation does not lock the
+returned owner. Serialize imports and destination creation/KDF work in the host.
+JavaScript strings, CryptoKey cleanup and browser memory erasure are best effort.
+The 24 MiB archive / 16 MiB bundle caps do not establish peak-memory qualification.
+
+Build with `npm ci --legacy-peer-deps --ignore-scripts` and `npm run build`.
+The installed runner accepts explicit Core and FogVault tarballs:
+
+```
+python scripts/verify-fogvault-legacy.py --prepared PREPARED.json --output REPORT.json --engine chromium
+```
+
+It packs this package plus the actual Core browser adapter, installs all four
+packages in an isolated consumer, verifies installed bytes, runs TypeScript and
+real browser/KDF/IndexedDB cases, and retains named evidence. Browser workers need
+same-origin script loading and a CSP permitting WebAssembly (`wasm-unsafe-eval`).
+The preparation marker must bind both consumed tarballs and the exact current
+Core build inputs; a stale marker fails before the browser starts.
+No RPC broker, synthetic fault control, legacy export API or credential-creation
+API is included in the maintained importer package. Native legacy import and a
+final v1 schema upgrade are separate scope; this package cannot close those gates.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,21 @@
+# Bundled legacy KDF notices
+
+The bundled worker includes libsodium-wrappers-sumo 0.8.4 and libsodium-sumo
+0.8.4. Both installed distributions carry the following notice:
+
+Copyright (c) 2015-2026
+Ahmad Ben Mrad <batikhsouri at gmail dot org>
+Frank Denis <j at pureftpd dot org>
+Ryan Lester <ryan at cyph dot com>
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/backup-read.mjs

@@ -0,0 +1,63 @@
+import {LegacyImportError as HostError} from "./error.mjs";
+import {validateVault, validateRecord, openVault, randomId, toBase64url, fromBase64url} from "./vault-read.mjs";
+
+export const MAX_BACKUP_BYTES = 24 * 1024 * 1024;
+const encoder = new TextEncoder();
+const vaultFields = ["vaultId", "vaultKeyId", "workspaceId", "salt", "rootNonce", "wrappedRoot"];
+const recordFields = ["vaultId", "workspaceId", "keyId", "keyNonce", "wrappedKey", "nonce", "ciphertext"];
+function fields(value, expected) {
+  if (!value || typeof value !== "object" || Object.keys(value).sort().join(",") !== [...expected].sort().join(",")) throw new HostError("invalid_backup");
+}
+function payload(vault, record, exportedAt, version = 2) {
+  return {format: "datafog-workspace-backup", version, exportedAt,
+    vault: {version: vault.version, profile: vault.profile, ...Object.fromEntries(vaultFields.map(key => [key, toBase64url(vault[key])])),
+      recovery: {version: vault.recovery.version, salt: toBase64url(vault.recovery.salt), nonce: toBase64url(vault.recovery.nonce), wrappedRoot: toBase64url(vault.recovery.wrappedRoot)}},
+    workspace: {version: record.version, head: {revision: record.head.revision, commitId: toBase64url(new Uint8Array(record.head.commitId))},
+      ...Object.fromEntries(recordFields.map(key => [key, toBase64url(record[key])]))}};
+}
+function authentication(body, nonce) {
+  return {name: "AES-GCM", iv: nonce, tagLength: 128,
+    additionalData: encoder.encode(`DFGB${body.version}:AUTH:${JSON.stringify(body)}`)};
+}
+
+function decodeBackup(bytes) {
+  if (!(bytes instanceof Uint8Array)) throw new HostError("invalid_backup");
+  if (bytes.length > MAX_BACKUP_BYTES) throw new HostError("resource_limit");
+  try {
+    const source = new TextDecoder("utf-8", {fatal: true, ignoreBOM: true}).decode(bytes);
+    const file = JSON.parse(source);
+    fields(file, ["payload", "nonce", "tag"]);
+    const body = file.payload;
+    fields(body, ["format", "version", "exportedAt", "vault", "workspace"]);
+    if (body.format !== "datafog-workspace-backup" || ![1, 2].includes(body.version) || typeof body.exportedAt !== "string" || body.exportedAt.length !== 24 || new Date(body.exportedAt).toISOString() !== body.exportedAt) throw new HostError("invalid_backup");
+    const v = body.vault, r = body.workspace;
+    fields(v, ["version", "profile", ...vaultFields, "recovery"]);
+    fields(v.recovery, ["version", "salt", "nonce", "wrappedRoot"]);
+    fields(r, ["version", "head", ...recordFields]); fields(r.head, ["revision", "commitId"]);
+    if (v.version !== 2 || v.profile !== body.version) throw new HostError("invalid_backup");
+    const vaultSizes = {vaultId: 16, vaultKeyId: 16, workspaceId: 16, salt: 16, rootNonce: 12, wrappedRoot: 48};
+    const recordSizes = {vaultId: 16, workspaceId: 16, keyId: 16, keyNonce: 12, wrappedKey: 48, nonce: 12, ciphertext: 16 * 1024 * 1024 + 16};
+    const vault = {version: v.version, profile: v.profile, accessGeneration: randomId(),
+      ...Object.fromEntries(vaultFields.map(key => [key, fromBase64url(v[key], vaultSizes[key])])),
+      recovery: {version: v.recovery.version, salt: fromBase64url(v.recovery.salt, 16), nonce: fromBase64url(v.recovery.nonce, 12), wrappedRoot: fromBase64url(v.recovery.wrappedRoot, 48)}};
+    const record = {version: r.version, head: {revision: r.head.revision, commitId: Array.from(fromBase64url(r.head.commitId, 16))},
+      ...Object.fromEntries(recordFields.map(key => [key, fromBase64url(r[key], recordSizes[key])]))};
+    validateVault(vault); validateRecord(record, vault);
+    const nonce = fromBase64url(file.nonce, 12), tag = fromBase64url(file.tag, 16);
+    if (nonce.length !== 12 || tag.length !== 16 || JSON.stringify({payload: payload(vault, record, body.exportedAt, body.version), nonce: toBase64url(nonce), tag: toBase64url(tag)}) !== source) throw new HostError("invalid_backup");
+    return {vault, record, exportedAt: body.exportedAt, body, nonce, tag};
+  } catch { throw new HostError("invalid_backup"); }
+}
+
+/** Authenticate every exported field, even the unused credential slot, before staging. */
+export async function openBackup(bytes, credential, method, signal) {
+  const decoded = decodeBackup(bytes);
+  const opened = await openVault(credential, decoded.vault, decoded.record, signal, method);
+  try {
+    await crypto.subtle.decrypt(authentication(decoded.body, decoded.nonce), opened.dataKey, decoded.tag);
+    return {vault: decoded.vault, record: decoded.record, exportedAt: decoded.exportedAt, ...opened};
+  } catch {
+    opened.bundle.fill(0);
+    throw new HostError("invalid_backup");
+  }
+}

package/error.mjs

@@ -0,0 +1 @@
+export class LegacyImportError extends Error { constructor(code){super(code);this.name='LegacyImportError';this.code=code;} }

package/index.d.ts

@@ -0,0 +1,16 @@
+import type {Workspace,WorkspaceHead} from '@datafog/wasm';
+import type {FogVaultWorkspace,WorkspaceVaultOptions} from '@datafog/core-fogvault-browser';
+export class LegacyImportError extends Error {readonly code:string;readonly requestId?:Uint8Array;readonly requiresReopen?:boolean;readonly cleanupFailed?:boolean;}
+export interface LegacyOpenOptions {
+ Workspace:typeof Workspace; archive:Uint8Array; credential:string; method?:'password'|'recovery';
+ signal?:AbortSignal; expectedNamespace?:Uint8Array; expectedHead?:WorkspaceHead;
+}
+export class LegacyBackupImport {
+ private constructor();
+ static open(options:LegacyOpenOptions):Promise<LegacyBackupImport>;
+ preview():{exportedAt:string;namespace:Uint8Array;head:WorkspaceHead;counts:ReturnType<Workspace['counts']>};
+ /** Fresh unlocked destination exclusively owned by this operation. Exact literal approval required. */
+ commit(options:Omit<WorkspaceVaultOptions,'Workspace'> & {operationId:Uint8Array;requestId:Uint8Array;approved:true}):Promise<FogVaultWorkspace>;
+ /** Wipes the owned bundle; once publication starts also locks the destination. */
+ close():Promise<void>;
+}

package/index.mjs

@@ -0,0 +1,75 @@
+import {FogVaultWorkspace} from '@datafog/core-fogvault-browser';
+import {openBackup,MAX_BACKUP_BYTES} from './backup-read.mjs';
+import {LegacyImportError} from './error.mjs';
+export {LegacyImportError};
+const construct=Symbol('authenticated legacy session'),states=new WeakMap();
+const fail=code=>{throw new LegacyImportError(code);};
+const same=(a,b)=>a.length===b.length&&a.every((v,i)=>v===b[i]);
+const typedPrototype=Object.getPrototypeOf(Uint8Array.prototype);
+const bufferOf=Object.getOwnPropertyDescriptor(typedPrototype,'buffer').get;
+const lengthOf=Object.getOwnPropertyDescriptor(typedPrototype,'length').get;
+function bytes(value,length,maximum=MAX_BACKUP_BYTES){
+ if(!ArrayBuffer.isView(value)||Object.getPrototypeOf(value)!==Uint8Array.prototype)fail('invalid_transport');
+ for(const key of ['buffer','byteLength','byteOffset','length','constructor',Symbol.iterator])if(Object.hasOwn(value,key))fail('invalid_transport');
+ const buffer=bufferOf.call(value),size=lengthOf.call(value);
+ if(!(buffer instanceof ArrayBuffer)||buffer.detached)fail('invalid_transport');
+ if(size>maximum)fail('resource_limit');
+ if(length!==undefined&&size!==length)fail('invalid_identity');
+ const result=new Uint8Array(size);Uint8Array.prototype.set.call(result,value);return result;
+}
+function head(value){
+ if(!value||typeof value.revision!=='string'||!/^(0|[1-9][0-9]{0,19})$/.test(value.revision)||BigInt(value.revision)>18446744073709551615n)fail('invalid_head');
+ if(!(value.commitId instanceof Uint8Array)&&(!Array.isArray(value.commitId)||value.commitId.length!==16||value.commitId.some(v=>!Number.isInteger(v)||v<0||v>255)))fail('invalid_head');
+ const commitId=value.commitId instanceof Uint8Array?bytes(value.commitId,16):Uint8Array.from(value.commitId);
+ return {revision:value.revision,commitId:Array.from(commitId)};
+}
+function state(session){const s=states.get(session);if(!s||s.closed)fail('import_closed');return s;}
+async function closeState(s){
+ s.closed=true;s.bundle?.fill(0);s.bundle=null;s.controller.abort();s.signal?.removeEventListener('abort',s.abort);
+ try{await s.vault?.lock();return true;}catch{s.cleanupFailed=true;return false;}
+}
+/** Import-only supported reference archives; never a generic archive decryptor. */
+export class LegacyBackupImport {
+ constructor(token,s){if(token!==construct)fail('invalid_import');states.set(this,s);Object.freeze(this);}
+ static async open({Workspace,archive,credential,method='password',signal,expectedNamespace,expectedHead}){
+  if(!['password','recovery'].includes(method))fail('invalid_credentials');
+  if(typeof credential!=='string'||!credential.isWellFormed()||credential.length>1024)fail('invalid_credentials');
+  const wantedNamespace=expectedNamespace===undefined?undefined:bytes(expectedNamespace,16),wantedHead=expectedHead===undefined?undefined:head(expectedHead);
+  if(signal?.aborted)fail('cancelled');
+  const source=bytes(archive),controller=new AbortController();
+  const s={Workspace,controller,signal,closed:false,busy:false,bundle:null,vault:null};
+  s.abort=()=>{void closeState(s);};
+  signal?.addEventListener('abort',s.abort,{once:true});
+  let opened,workspace;
+  try{
+   if(signal?.aborted){s.abort();fail('cancelled');}
+   opened=await openBackup(source,credential,method,controller.signal);
+   if(s.closed||controller.signal.aborted)fail('cancelled');
+   workspace=Workspace.openBundle(opened.bundle);
+   const namespace=bytes(workspace.namespace(),16),saved=head(workspace.head());
+   if(!same(namespace,opened.vault.workspaceId)||saved.revision!==opened.record.head.revision||!same(saved.commitId,opened.record.head.commitId)
+      ||wantedNamespace&&!same(namespace,wantedNamespace)||wantedHead&&(saved.revision!==wantedHead.revision||!same(saved.commitId,wantedHead.commitId)))fail('binding_mismatch');
+   s.namespace=namespace;s.head=saved;s.exportedAt=opened.exportedAt;s.counts=workspace.counts();s.bundle=opened.bundle;
+   return new LegacyBackupImport(construct,s);
+  }catch(error){opened?.bundle.fill(0);await closeState(s);throw error instanceof LegacyImportError?error:new LegacyImportError(error.code??'invalid_backup');}
+  finally{workspace?.close();source.fill(0);}
+ }
+ preview(){const s=state(this);return {exportedAt:s.exportedAt,namespace:Uint8Array.from(s.namespace),head:structuredClone(s.head),counts:structuredClone(s.counts)};}
+ async commit({vault,recordId,operationId,requestId,approved}){
+  const s=state(this);if(approved!==true)fail('approval_required');if(s.busy)fail('operation_in_progress');
+  const record=bytes(recordId,16),operation=bytes(operationId,16),request=bytes(requestId,16);
+  s.busy=true;s.vault=vault;let owner;
+  try{
+   owner=await FogVaultWorkspace.importAuthenticatedBundle({Workspace:s.Workspace,vault,recordId:record,bundle:s.bundle,
+    expectedNamespace:s.namespace,expectedHead:s.head,operationId:operation,requestId:request,approved:true});
+   if(s.closed||s.controller.signal.aborted){await owner.close();fail('cancelled');}
+   s.vault=null;await closeState(s);return owner;
+  }catch(error){
+   const uncertain=s.closed||s.controller.signal.aborted||['OutcomeUnknown','outcome_unknown','invalid_save_confirmation'].includes(error?.code);
+   const cleanupSucceeded=await closeState(s);
+   if(uncertain||!cleanupSucceeded||s.cleanupFailed){const failure=new LegacyImportError('import_requires_reopen');failure.requestId=request.slice();failure.requiresReopen=true;if(s.cleanupFailed)failure.cleanupFailed=true;throw failure;}
+   throw error;
+  }
+ }
+ async close(){const s=states.get(this);if(s&&!s.closed)await closeState(s);if(s?.cleanupFailed)fail('cleanup_failed');}
+}