@tangle-network/braid 0.1.0

package/dist/adapters/credentials/os.d.ts

@@ -0,0 +1,28 @@
+import type { CredentialPort, CredentialRef, CredentialStoreInput, SecretHandle } from '../../ports/credentials.js';
+export interface NativeKeyringEntry {
+    setSecret(secret: Uint8Array): Promise<void>;
+    getSecret(): Promise<Uint8Array | undefined>;
+    deleteCredential(): Promise<boolean>;
+}
+export type NativeKeyringEntryFactory = (service: string, account: string) => NativeKeyringEntry;
+declare abstract class NativeCredentialStore implements CredentialPort {
+    #private;
+    abstract readonly platform: string;
+    constructor(entryFactory?: NativeKeyringEntryFactory);
+    store(input: CredentialStoreInput): Promise<CredentialRef>;
+    resolve(ref: CredentialRef): Promise<SecretHandle>;
+    remove(ref: CredentialRef): Promise<void>;
+    available(): Promise<boolean>;
+}
+export declare class MacOsKeychainCredentialStore extends NativeCredentialStore {
+    readonly platform = "macos-keychain";
+}
+export declare class LinuxSecretServiceCredentialStore extends NativeCredentialStore {
+    readonly platform = "linux-secret-service";
+}
+export declare class WindowsCredentialManagerStore extends NativeCredentialStore {
+    readonly platform = "windows-credential-manager";
+}
+export declare function createOperatingSystemCredentialStore(): CredentialPort;
+export {};
+//# sourceMappingURL=os.d.ts.map

package/dist/adapters/credentials/os.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"os.d.ts","sourceRoot":"","sources":["../../../src/adapters/credentials/os.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACb,oBAAoB,EACpB,YAAY,EACb,MAAM,4BAA4B,CAAA;AAKnC,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5C,SAAS,IAAI,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAA;IAC5C,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;CACrC;AAED,MAAM,MAAM,yBAAyB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,kBAAkB,CAAA;AAiFhG,uBAAe,qBAAsB,YAAW,cAAc;;IAC5D,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IAGlC,YAAY,YAAY,GAAE,yBAA6C,EAEtE;IAMK,KAAK,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC,CAgB/D;IAEK,OAAO,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAmBvD;IAEK,MAAM,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB9C;IAEK,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,CAsBlC;CACF;AAED,qBAAa,4BAA6B,SAAQ,qBAAqB;IACrE,QAAQ,CAAC,QAAQ,oBAAmB;CACrC;AAED,qBAAa,iCAAkC,SAAQ,qBAAqB;IAC1E,QAAQ,CAAC,QAAQ,0BAAyB;CAC3C;AAED,qBAAa,6BAA8B,SAAQ,qBAAqB;IACtE,QAAQ,CAAC,QAAQ,gCAA+B;CACjD;AAED,wBAAgB,oCAAoC,IAAI,cAAc,CAcrE"}

package/dist/adapters/credentials/os.js

@@ -0,0 +1,187 @@
+import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { CredentialError, credentialRef } from '../../ports/credentials.js';
+const SERVICE_NAME = 'Braid';
+class LazyNativeKeyringEntry {
+    #service;
+    #account;
+    #entry;
+    constructor(service, account) {
+        this.#service = service;
+        this.#account = account;
+    }
+    async setSecret(secret) {
+        await (await this.load()).setSecret(secret);
+    }
+    async getSecret() {
+        return (await this.load()).getSecret();
+    }
+    async deleteCredential() {
+        return (await this.load()).deleteCredential();
+    }
+    load() {
+        this.#entry ??= import('@napi-rs/keyring').then(({ AsyncEntry }) => new AsyncEntry(this.#service, this.#account));
+        return this.#entry;
+    }
+}
+const createNativeEntry = (service, account) => new LazyNativeKeyringEntry(service, account);
+class ProcessSecretHandle {
+    ref;
+    #value;
+    constructor(ref, value) {
+        this.ref = ref;
+        this.#value = Buffer.from(value);
+    }
+    read() {
+        if (!this.#value)
+            throw new CredentialError('SECRET_HANDLE_CLOSED', 'Secret handle is closed');
+        return Buffer.from(this.#value);
+    }
+    dispose() {
+        this.#value?.fill(0);
+        this.#value = undefined;
+    }
+}
+function errorText(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+function errorCode(error) {
+    if (!error || typeof error !== 'object' || !('code' in error))
+        return undefined;
+    return typeof error.code === 'string' ? error.code : undefined;
+}
+function isMissingCredential(error) {
+    const code = errorCode(error)
+        ?.replaceAll(/[-_\s]/gu, '')
+        .toLowerCase();
+    if (code === 'noentry' || code === 'notfound' || code === 'credentialnotfound')
+        return true;
+    return /(?:no|missing)\s+(?:matching\s+)?(?:credential|entry)|not found/iu.test(errorText(error));
+}
+function facilityUnavailable(platform, cause) {
+    return new CredentialError('CREDENTIAL_STORE_UNAVAILABLE', `${platform} credential facility is unavailable`, { cause });
+}
+class NativeCredentialStore {
+    #entryFactory;
+    constructor(entryFactory = createNativeEntry) {
+        this.#entryFactory = entryFactory;
+    }
+    #entry(account) {
+        return this.#entryFactory(SERVICE_NAME, account);
+    }
+    async store(input) {
+        const ref = input.ref ?? credentialRef(`cred:v1:${this.platform}-${randomUUID()}`);
+        if (input.value.length === 0) {
+            throw new CredentialError('EMPTY_SECRET', 'Credential values must not be empty');
+        }
+        const secret = Buffer.from(input.value);
+        try {
+            await this.#entry(ref).setSecret(secret);
+        }
+        catch (error) {
+            throw new CredentialError('CREDENTIAL_WRITE_FAILED', 'The credential could not be stored', {
+                cause: error,
+            });
+        }
+        finally {
+            secret.fill(0);
+        }
+        return ref;
+    }
+    async resolve(ref) {
+        let secret;
+        try {
+            secret = await this.#entry(ref).getSecret();
+        }
+        catch (error) {
+            if (isMissingCredential(error)) {
+                throw new CredentialError('CREDENTIAL_NOT_FOUND', `Credential ${ref} was not found`);
+            }
+            throw facilityUnavailable(this.platform, error);
+        }
+        if (!secret || secret.length === 0) {
+            secret?.fill(0);
+            throw new CredentialError('CREDENTIAL_NOT_FOUND', `Credential ${ref} was not found`);
+        }
+        try {
+            return new ProcessSecretHandle(ref, secret);
+        }
+        finally {
+            secret.fill(0);
+        }
+    }
+    async remove(ref) {
+        const entry = this.#entry(ref);
+        try {
+            const removed = await entry.deleteCredential();
+            if (removed)
+                return;
+            const remaining = await entry.getSecret();
+            try {
+                if (remaining === undefined || remaining.length === 0)
+                    return;
+            }
+            finally {
+                remaining?.fill(0);
+            }
+            throw new CredentialError('CREDENTIAL_REMOVE_FAILED', 'The credential store reported success without removing the credential');
+        }
+        catch (error) {
+            if (isMissingCredential(error))
+                return;
+            if (error instanceof CredentialError)
+                throw error;
+            throw new CredentialError('CREDENTIAL_REMOVE_FAILED', 'The credential could not be removed', {
+                cause: error,
+            });
+        }
+    }
+    async available() {
+        const entry = this.#entry(`__braid_availability_probe_v1__-${randomUUID()}`);
+        const expected = randomBytes(32);
+        let observed;
+        let cleanupAttempted = false;
+        try {
+            await entry.setSecret(expected);
+            observed = await entry.getSecret();
+            const matches = observed !== undefined &&
+                observed.length === expected.length &&
+                timingSafeEqual(observed, expected);
+            cleanupAttempted = true;
+            const removed = await entry.deleteCredential();
+            return matches && removed;
+        }
+        catch {
+            if (!cleanupAttempted)
+                await entry.deleteCredential().catch(() => false);
+            return false;
+        }
+        finally {
+            expected.fill(0);
+            observed?.fill(0);
+        }
+    }
+}
+export class MacOsKeychainCredentialStore extends NativeCredentialStore {
+    platform = 'macos-keychain';
+}
+export class LinuxSecretServiceCredentialStore extends NativeCredentialStore {
+    platform = 'linux-secret-service';
+}
+export class WindowsCredentialManagerStore extends NativeCredentialStore {
+    platform = 'windows-credential-manager';
+}
+export function createOperatingSystemCredentialStore() {
+    switch (process.platform) {
+        case 'darwin':
+            return new MacOsKeychainCredentialStore();
+        case 'linux':
+            return new LinuxSecretServiceCredentialStore();
+        case 'win32':
+            return new WindowsCredentialManagerStore();
+        default:
+            throw new CredentialError('CREDENTIAL_STORE_UNAVAILABLE', `No maintained credential adapter is available for ${process.platform}`);
+    }
+}
+//# sourceMappingURL=os.js.map

package/dist/adapters/credentials/os.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"os.js","sourceRoot":"","sources":["../../../src/adapters/credentials/os.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAOtE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAE3E,MAAM,YAAY,GAAG,OAAO,CAAA;AAU5B,MAAM,sBAAsB;IACjB,QAAQ,CAAQ;IAChB,QAAQ,CAAQ;IACzB,MAAM,CAAyC;IAE/C,YAAY,OAAe,EAAE,OAAe;QAC1C,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAA;QACvB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAA;IACzB,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,MAAkB;QAChC,MAAM,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;IAC7C,CAAC;IAED,KAAK,CAAC,SAAS;QACb,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,SAAS,EAAE,CAAA;IACxC,CAAC;IAED,KAAK,CAAC,gBAAgB;QACpB,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,gBAAgB,EAAE,CAAA;IAC/C,CAAC;IAEO,IAAI;QACV,IAAI,CAAC,MAAM,KAAK,MAAM,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAC7C,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,CACjE,CAAA;QACD,OAAO,IAAI,CAAC,MAAM,CAAA;IACpB,CAAC;CACF;AAED,MAAM,iBAAiB,GAA8B,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,CACxE,IAAI,sBAAsB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;AAE9C,MAAM,mBAAmB;IACd,GAAG,CAAe;IAC3B,MAAM,CAAoB;IAE1B,YAAY,GAAkB,EAAE,KAAiB;QAC/C,IAAI,CAAC,GAAG,GAAG,GAAG,CAAA;QACd,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAClC,CAAC;IAED,IAAI;QACF,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,eAAe,CAAC,sBAAsB,EAAE,yBAAyB,CAAC,CAAA;QAC9F,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACjC,CAAC;IAED,OAAO;QACL,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;QACpB,IAAI,CAAC,MAAM,GAAG,SAAS,CAAA;IACzB,CAAC;CACF;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,KAAK,YAAY,KAAK;QAAE,OAAO,KAAK,CAAC,OAAO,CAAA;IAChD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAA;AACtB,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IAC/E,OAAO,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;AAChE,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAc;IACzC,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC;QAC3B,EAAE,UAAU,CAAC,UAAU,EAAE,EAAE,CAAC;SAC3B,WAAW,EAAE,CAAA;IAChB,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,UAAU,IAAI,IAAI,KAAK,oBAAoB;QAAE,OAAO,IAAI,CAAA;IAC3F,OAAO,mEAAmE,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAA;AACnG,CAAC;AAED,SAAS,mBAAmB,CAAC,QAAgB,EAAE,KAAc;IAC3D,OAAO,IAAI,eAAe,CACxB,8BAA8B,EAC9B,GAAG,QAAQ,qCAAqC,EAChD,EAAE,KAAK,EAAE,CACV,CAAA;AACH,CAAC;AAED,MAAe,qBAAqB;IAEzB,aAAa,CAA2B;IAEjD,YAAY,YAAY,GAA8B,iBAAiB;QACrE,IAAI,CAAC,aAAa,GAAG,YAAY,CAAA;IACnC,CAAC;IAED,MAAM,CAAC,OAAe;QACpB,OAAO,IAAI,CAAC,aAAa,CAAC,YAAY,EAAE,OAAO,CAAC,CAAA;IAClD,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,KAA2B;QACrC,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,IAAI,aAAa,CAAC,WAAW,IAAI,CAAC,QAAQ,IAAI,UAAU,EAAE,EAAE,CAAC,CAAA;QAClF,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,eAAe,CAAC,cAAc,EAAE,qCAAqC,CAAC,CAAA;QAClF,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QACvC,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;QAC1C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,eAAe,CAAC,yBAAyB,EAAE,oCAAoC,EAAE;gBACzF,KAAK,EAAE,KAAK;aACb,CAAC,CAAA;QACJ,CAAC;gBAAS,CAAC;YACT,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QAChB,CAAC;QACD,OAAO,GAAG,CAAA;IACZ,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,GAAkB;QAC9B,IAAI,MAA8B,CAAA;QAClC,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,CAAA;QAC7C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC/B,MAAM,IAAI,eAAe,CAAC,sBAAsB,EAAE,cAAc,GAAG,gBAAgB,CAAC,CAAA;YACtF,CAAC;YACD,MAAM,mBAAmB,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;QACjD,CAAC;QACD,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;YACf,MAAM,IAAI,eAAe,CAAC,sBAAsB,EAAE,cAAc,GAAG,gBAAgB,CAAC,CAAA;QACtF,CAAC;QACD,IAAI,CAAC;YACH,OAAO,IAAI,mBAAmB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;QAC7C,CAAC;gBAAS,CAAC;YACT,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QAChB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAkB;QAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAC9B,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,gBAAgB,EAAE,CAAA;YAC9C,IAAI,OAAO;gBAAE,OAAM;YACnB,MAAM,SAAS,GAAG,MAAM,KAAK,CAAC,SAAS,EAAE,CAAA;YACzC,IAAI,CAAC;gBACH,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;oBAAE,OAAM;YAC/D,CAAC;oBAAS,CAAC;gBACT,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;YACpB,CAAC;YACD,MAAM,IAAI,eAAe,CACvB,0BAA0B,EAC1B,uEAAuE,CACxE,CAAA;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,mBAAmB,CAAC,KAAK,CAAC;gBAAE,OAAM;YACtC,IAAI,KAAK,YAAY,eAAe;gBAAE,MAAM,KAAK,CAAA;YACjD,MAAM,IAAI,eAAe,CAAC,0BAA0B,EAAE,qCAAqC,EAAE;gBAC3F,KAAK,EAAE,KAAK;aACb,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,SAAS;QACb,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,mCAAmC,UAAU,EAAE,EAAE,CAAC,CAAA;QAC5E,MAAM,QAAQ,GAAG,WAAW,CAAC,EAAE,CAAC,CAAA;QAChC,IAAI,QAAgC,CAAA;QACpC,IAAI,gBAAgB,GAAG,KAAK,CAAA;QAC5B,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAA;YAC/B,QAAQ,GAAG,MAAM,KAAK,CAAC,SAAS,EAAE,CAAA;YAClC,MAAM,OAAO,GACX,QAAQ,KAAK,SAAS;gBACtB,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM;gBACnC,eAAe,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;YACrC,gBAAgB,GAAG,IAAI,CAAA;YACvB,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,gBAAgB,EAAE,CAAA;YAC9C,OAAO,OAAO,IAAI,OAAO,CAAA;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,gBAAgB;gBAAE,MAAM,KAAK,CAAC,gBAAgB,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAA;YACxE,OAAO,KAAK,CAAA;QACd,CAAC;gBAAS,CAAC;YACT,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YAChB,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;QACnB,CAAC;IACH,CAAC;CACF;AAED,MAAM,OAAO,4BAA6B,SAAQ,qBAAqB;IAC5D,QAAQ,GAAG,gBAAgB,CAAA;CACrC;AAED,MAAM,OAAO,iCAAkC,SAAQ,qBAAqB;IACjE,QAAQ,GAAG,sBAAsB,CAAA;CAC3C;AAED,MAAM,OAAO,6BAA8B,SAAQ,qBAAqB;IAC7D,QAAQ,GAAG,4BAA4B,CAAA;CACjD;AAED,MAAM,UAAU,oCAAoC;IAClD,QAAQ,OAAO,CAAC,QAAQ,EAAE,CAAC;QACzB,KAAK,QAAQ;YACX,OAAO,IAAI,4BAA4B,EAAE,CAAA;QAC3C,KAAK,OAAO;YACV,OAAO,IAAI,iCAAiC,EAAE,CAAA;QAChD,KAAK,OAAO;YACV,OAAO,IAAI,6BAA6B,EAAE,CAAA;QAC5C;YACE,MAAM,IAAI,eAAe,CACvB,8BAA8B,EAC9B,qDAAqD,OAAO,CAAC,QAAQ,EAAE,CACxE,CAAA;IACL,CAAC;AACH,CAAC"}

package/dist/adapters/persistence/safe-file-descriptor.d.ts

@@ -0,0 +1,39 @@
+declare const DIRECTORY_FLAGS: number;
+declare const LEAF_FLAGS: number;
+export type SafeFileErrorCode = 'SAFE_FILE_INVALID_LIMIT' | 'SAFE_FILE_INVALID_PATH' | 'SAFE_FILE_LOCK_NOT_OWNED' | 'SAFE_FILE_NOT_DIRECTORY' | 'SAFE_FILE_NOT_REGULAR' | 'SAFE_FILE_PATH_RACE_UNSUPPORTED' | 'SAFE_FILE_PUBLISHED_INVALID' | 'SAFE_FILE_SYMLINK';
+/** A fail-closed error from the private filesystem boundary. */
+export declare class SafeFileError extends Error {
+    readonly code: SafeFileErrorCode;
+    constructor(code: SafeFileErrorCode, message: string);
+}
+export interface SafePath {
+    readonly absolute: string;
+    readonly root: string;
+    readonly components: readonly string[];
+}
+export interface OpenParent {
+    readonly path: SafePath;
+    readonly fd: number;
+    readonly leaf: string;
+    readonly leafPath: string;
+}
+export declare function errorCode(error: unknown): string | undefined;
+export declare function safePath(path: string): SafePath;
+export declare function componentPath(path: SafePath, count: number): string;
+export declare function childPath(directoryFd: number, leaf: string): string;
+export declare function normalizePathError(error: unknown, path: string): unknown;
+export declare function requireDirectory(handle: number, path: string): void;
+export declare function requireRegularFile(handle: number, path: string): void;
+export declare function openDirectoryComponents(path: SafePath, count: number): number;
+export declare function openParent(path: string): OpenParent;
+export declare function openLeaf(parent: OpenParent, flags: number, mode?: number): number;
+export declare function openExistingLeaf(path: string): number;
+export declare function unlinkAt(parentFd: number, leaf: string, path: string): void;
+/** Performs a one-shot descriptor-relative symlink check; it is not a later path-operation proof. */
+export declare function assertNoSymlinkPath(path: string): void;
+/** Verifies that an existing path is a real directory through a stable descriptor. */
+export declare function assertSafeDirectory(path: string): void;
+/** Creates missing private directories without resolving a renamed parent by path. */
+export declare function ensurePrivateDirectory(path: string, mode?: number): void;
+export { DIRECTORY_FLAGS, LEAF_FLAGS };
+//# sourceMappingURL=safe-file-descriptor.d.ts.map

package/dist/adapters/persistence/safe-file-descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-file-descriptor.d.ts","sourceRoot":"","sources":["../../../src/adapters/persistence/safe-file-descriptor.ts"],"names":[],"mappings":"AAGA,QAAA,MAAM,eAAe,QAAmE,CAAA;AACxF,QAAA,MAAM,UAAU,QAAmE,CAAA;AAMnF,MAAM,MAAM,iBAAiB,GACzB,yBAAyB,GACzB,wBAAwB,GACxB,0BAA0B,GAC1B,yBAAyB,GACzB,uBAAuB,GACvB,iCAAiC,GACjC,6BAA6B,GAC7B,mBAAmB,CAAA;AAEvB,gEAAgE;AAChE,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAEhC,YAAY,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,EAInD;CACF;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CACvC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAWD,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI5D;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAkB/C;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAcnE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAQxE;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAOnE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAOrE;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CA+B7E;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAwBnD;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAQjF;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA6BrD;AAED,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAM3E;AAED,qGAAqG;AACrG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAqBtD;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAItD;AAED,sFAAsF;AACtF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAQ,GAAG,IAAI,CAkCvE;AAED,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,CAAA"}

package/dist/adapters/persistence/safe-file-descriptor.js

@@ -0,0 +1,258 @@
+import { closeSync, constants, fstatSync, mkdirSync, openSync, unlinkSync } from 'node:fs';
+import { join, parse, resolve, sep } from 'node:path';
+const DIRECTORY_FLAGS = constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW;
+const LEAF_FLAGS = constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW;
+/** A fail-closed error from the private filesystem boundary. */
+export class SafeFileError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SafeFileError';
+        this.code = code;
+    }
+}
+function descriptorRoot() {
+    if (process.platform === 'linux')
+        return '/proc/self/fd';
+    if (process.platform === 'darwin')
+        return '/dev/fd';
+    throw new SafeFileError('SAFE_FILE_PATH_RACE_UNSUPPORTED', `Descriptor-relative private-file access is unavailable on ${process.platform}; refusing the unsafe path operation`);
+}
+export function errorCode(error) {
+    if (typeof error !== 'object' || error === null || !('code' in error))
+        return undefined;
+    const code = error.code;
+    return typeof code === 'string' ? code : undefined;
+}
+export function safePath(path) {
+    descriptorRoot();
+    if (path.includes('\u0000')) {
+        throw new SafeFileError('SAFE_FILE_INVALID_PATH', 'Private storage paths must not contain NUL bytes');
+    }
+    const absolute = resolve(path);
+    const root = parse(absolute).root;
+    const components = absolute.slice(root.length).split(sep).filter(Boolean);
+    if (components.some((component) => component === '.' || component === '..')) {
+        throw new SafeFileError('SAFE_FILE_INVALID_PATH', `Private storage path is not canonical: ${path}`);
+    }
+    return { absolute, root, components };
+}
+export function componentPath(path, count) {
+    return join(path.root, ...path.components.slice(0, count));
+}
+export function childPath(directoryFd, leaf) {
+    if (leaf.length === 0 ||
+        leaf === '.' ||
+        leaf === '..' ||
+        leaf.includes('/') ||
+        leaf.includes('\\')) {
+        throw new SafeFileError('SAFE_FILE_INVALID_PATH', 'Private storage path contains an invalid component');
+    }
+    return `${descriptorRoot()}/${directoryFd}/${leaf}`;
+}
+export function normalizePathError(error, path) {
+    if (errorCode(error) === 'ELOOP') {
+        return new SafeFileError('SAFE_FILE_SYMLINK', `Private storage path must not contain a symbolic link: ${path}`);
+    }
+    return error;
+}
+export function requireDirectory(handle, path) {
+    if (!fstatSync(handle).isDirectory()) {
+        throw new SafeFileError('SAFE_FILE_NOT_DIRECTORY', `Private storage path is not a directory: ${path}`);
+    }
+}
+export function requireRegularFile(handle, path) {
+    if (!fstatSync(handle).isFile()) {
+        throw new SafeFileError('SAFE_FILE_NOT_REGULAR', `Private storage path is not a regular file: ${path}`);
+    }
+}
+export function openDirectoryComponents(path, count) {
+    let currentFd;
+    try {
+        currentFd = openSync(path.root, DIRECTORY_FLAGS);
+        requireDirectory(currentFd, path.root);
+        let currentPath = path.root;
+        for (const component of path.components.slice(0, count)) {
+            const nextPath = join(currentPath, component);
+            let nextFd;
+            try {
+                nextFd = openSync(childPath(currentFd, component), DIRECTORY_FLAGS);
+            }
+            catch (error) {
+                throw normalizePathError(error, nextPath);
+            }
+            try {
+                requireDirectory(nextFd, nextPath);
+            }
+            catch (error) {
+                closeSync(nextFd);
+                throw error;
+            }
+            const previousFd = currentFd;
+            currentFd = nextFd;
+            currentPath = nextPath;
+            closeSync(previousFd);
+        }
+        const result = currentFd;
+        currentFd = undefined;
+        return result;
+    }
+    finally {
+        if (currentFd !== undefined)
+            closeSync(currentFd);
+    }
+}
+export function openParent(path) {
+    const parsed = safePath(path);
+    if (parsed.components.length === 0) {
+        throw new SafeFileError('SAFE_FILE_NOT_REGULAR', `Private storage path is not a regular file: ${parsed.absolute}`);
+    }
+    const parentCount = parsed.components.length - 1;
+    const directoryFd = openDirectoryComponents(parsed, parentCount);
+    const leaf = parsed.components[parsed.components.length - 1];
+    if (leaf === undefined) {
+        closeSync(directoryFd);
+        throw new SafeFileError('SAFE_FILE_INVALID_PATH', `Private storage path has no file name: ${path}`);
+    }
+    return {
+        path: parsed,
+        fd: directoryFd,
+        leaf,
+        leafPath: join(componentPath(parsed, parentCount), leaf),
+    };
+}
+export function openLeaf(parent, flags, mode) {
+    try {
+        return mode === undefined
+            ? openSync(childPath(parent.fd, parent.leaf), flags)
+            : openSync(childPath(parent.fd, parent.leaf), flags, mode);
+    }
+    catch (error) {
+        throw normalizePathError(error, parent.leafPath);
+    }
+}
+export function openExistingLeaf(path) {
+    const parsed = safePath(path);
+    if (parsed.components.length === 0) {
+        try {
+            return openSync(parsed.root, LEAF_FLAGS);
+        }
+        catch (error) {
+            throw normalizePathError(error, parsed.absolute);
+        }
+    }
+    const parent = openParent(path);
+    let handle;
+    let parentClosed = false;
+    try {
+        handle = openLeaf(parent, LEAF_FLAGS);
+        closeSync(parent.fd);
+        parentClosed = true;
+        return handle;
+    }
+    catch (error) {
+        if (handle !== undefined)
+            closeSync(handle);
+        throw error;
+    }
+    finally {
+        if (!parentClosed) {
+            try {
+                closeSync(parent.fd);
+            }
+            catch {
+                // Preserve the operation error; the descriptor is already on the failure path.
+            }
+        }
+    }
+}
+export function unlinkAt(parentFd, leaf, path) {
+    try {
+        unlinkSync(childPath(parentFd, leaf));
+    }
+    catch (error) {
+        if (errorCode(error) !== 'ENOENT')
+            throw normalizePathError(error, path);
+    }
+}
+/** Performs a one-shot descriptor-relative symlink check; it is not a later path-operation proof. */
+export function assertNoSymlinkPath(path) {
+    const parsed = safePath(path);
+    if (parsed.components.length === 0)
+        return;
+    let parent;
+    try {
+        parent = openParent(path);
+        let handle;
+        try {
+            handle = openLeaf(parent, LEAF_FLAGS);
+        }
+        catch (error) {
+            if (errorCode(error) === 'ENOENT')
+                return;
+            throw error;
+        }
+        finally {
+            if (handle !== undefined)
+                closeSync(handle);
+        }
+    }
+    catch (error) {
+        if (errorCode(error) === 'ENOENT')
+            return;
+        throw error;
+    }
+    finally {
+        if (parent !== undefined)
+            closeSync(parent.fd);
+    }
+}
+/** Verifies that an existing path is a real directory through a stable descriptor. */
+export function assertSafeDirectory(path) {
+    const parsed = safePath(path);
+    const handle = openDirectoryComponents(parsed, parsed.components.length);
+    closeSync(handle);
+}
+/** Creates missing private directories without resolving a renamed parent by path. */
+export function ensurePrivateDirectory(path, mode = 0o700) {
+    const parsed = safePath(path);
+    let currentFd;
+    try {
+        currentFd = openSync(parsed.root, DIRECTORY_FLAGS);
+        requireDirectory(currentFd, parsed.root);
+        let currentPath = parsed.root;
+        for (const component of parsed.components) {
+            const nextPath = join(currentPath, component);
+            let nextFd;
+            for (;;) {
+                try {
+                    nextFd = openSync(childPath(currentFd, component), DIRECTORY_FLAGS);
+                    break;
+                }
+                catch (error) {
+                    if (errorCode(error) !== 'ENOENT')
+                        throw normalizePathError(error, nextPath);
+                    try {
+                        mkdirSync(childPath(currentFd, component), { mode });
+                    }
+                    catch (mkdirError) {
+                        if (errorCode(mkdirError) !== 'EEXIST') {
+                            throw normalizePathError(mkdirError, nextPath);
+                        }
+                    }
+                }
+            }
+            requireDirectory(nextFd, nextPath);
+            const previousFd = currentFd;
+            currentFd = nextFd;
+            currentPath = nextPath;
+            closeSync(previousFd);
+        }
+    }
+    finally {
+        if (currentFd !== undefined)
+            closeSync(currentFd);
+    }
+}
+export { DIRECTORY_FLAGS, LEAF_FLAGS };
+//# sourceMappingURL=safe-file-descriptor.js.map

package/dist/adapters/persistence/safe-file-descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-file-descriptor.js","sourceRoot":"","sources":["../../../src/adapters/persistence/safe-file-descriptor.ts"],"names":[],"mappings":"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"}

package/dist/adapters/persistence/safe-file-io.d.ts

@@ -0,0 +1,24 @@
+export interface PrivateFileWriteOptions {
+    readonly overwrite: boolean;
+    readonly expected?: (current: Buffer | undefined) => void;
+    readonly maxExistingBytes?: number;
+    readonly verify?: (bytes: Buffer) => void;
+    readonly onPhase?: (phase: PrivateFileWritePhase) => void;
+}
+export type PrivateFileWritePhase = 'temporary-written' | 'temporary-fsynced' | 'renamed' | 'directory-fsynced';
+export declare function readAt(directoryFd: number, leaf: string, path: string, maxBytes: number): Buffer | undefined;
+export declare function readNoFollow(path: string, maxBytes: number): Buffer | undefined;
+/** Removes one private regular file through its opened parent directory. */
+export declare function removePrivateFile(path: string): void;
+export declare function ensurePrivateFile(path: string): void;
+export declare function fsyncDirectory(path: string): void;
+/**
+ * Publishes a private file with a stable parent descriptor.
+ * No-follow and regular-file checks happen on descriptors; unsupported platforms reject before any path I/O.
+ * Node core has no renameat/linkat, so publication uses the platform descriptor namespace
+ * and verifies the published bytes afterward; that closes the parent race without claiming
+ * a stronger conditional-replacement guarantee than the available primitives provide.
+ */
+export declare function replacePrivateFile(path: string, value: string | Buffer, options: PrivateFileWriteOptions): void;
+export declare function writePrivateFile(path: string, value: string | Buffer): void;
+//# sourceMappingURL=safe-file-io.d.ts.map

package/dist/adapters/persistence/safe-file-io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-file-io.d.ts","sourceRoot":"","sources":["../../../src/adapters/persistence/safe-file-io.ts"],"names":[],"mappings":"AAuCA,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAA;IACzD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAA;CAC1D;AAED,MAAM,MAAM,qBAAqB,GAC7B,mBAAmB,GACnB,mBAAmB,GACnB,SAAS,GACT,mBAAmB,CAAA;AAiCvB,wBAAgB,MAAM,CACpB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAapB;AAsDD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAY/E;AAED,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAkBpD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAWpD;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAQjD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,EAAE,uBAAuB,GAC/B,IAAI,CA0EN;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE3E"}