@kokuin/electron 0.3.0 → 0.4.0

package/README.md

@@ -5,3 +5,20 @@
 ```sh
 npm install @kokuin/electron
 ```
+
+## Cross-process locking
+
+`ElectronKeyStore.open({ name, lockPath })` is opt-in. Without it, two processes racing to
+generate a key for a fresh keyID both create one, and only the in-process lock applies — the
+result is unsafe: silent key loss on backends that upsert unconditionally (e.g. Linux/
+libsecret), or a thrown duplicate-item error on macOS Keychain. With `lockPath` set,
+`provideAsync()` serializes the create through a file lock (`@sozai/lock`) so both processes
+converge on the same key.
+
+`lockPath` must point to a **local** filesystem — `link()` is not atomic on NFS — and names a
+file, not a directory: one coarse lock per store, not one per keyID. Acquisition is bounded and
+throws on timeout rather than proceeding unlocked.
+
+The synchronous `entry.provide()` cannot hold a cross-process lock (a file lock can't be
+acquired synchronously), so it throws when the store was opened with a `lockPath`; use
+`provideAsync()` instead.

package/lib/entry.d.ts

@@ -1,15 +1,26 @@
-import type { KeyEntry } from '@kokuin/token';
+import type { MutableKeyEntry } from '@kokuin/token';
 import type { KeyStorage } from './types.js';
-export declare class ElectronKeyEntry implements KeyEntry<string> {
+export type ElectronKeyEntryParams = {
+    storage: KeyStorage;
+    keyID: string;
+    key?: Uint8Array;
+    allowInsecureStorage?: boolean;
+    lockPath?: string;
+};
+export declare class ElectronKeyEntry implements MutableKeyEntry<Uint8Array> {
     #private;
-    constructor(storage: KeyStorage, keyID: string, key?: string, allowInsecureStorage?: boolean);
+    constructor(params: ElectronKeyEntryParams);
     get keyID(): string;
-    getAsync(): Promise<string | null>;
-    get(): string | null;
-    setAsync(key: string): Promise<void>;
-    set(key: string): void;
-    provideAsync(): Promise<string>;
-    provide(): string;
-    removeAsync(): Promise<void>;
+    get(): Uint8Array | null;
+    getAsync(): Promise<Uint8Array | null>;
+    set(privateKey: Uint8Array): void;
+    setAsync(privateKey: Uint8Array): Promise<void>;
+    /**
+     * The stored key, generating one if absent. Synchronous, and therefore **not** cross-process
+     * safe. Throws when a `lockPath` is set rather than silently dropping the guarantee.
+     */
+    provide(): Uint8Array;
+    provideAsync(): Promise<Uint8Array>;
     remove(): void;
+    removeAsync(): Promise<void>;
 }

package/lib/entry.js

@@ -1,23 +1,26 @@
 import { randomPrivateKey } from '@kokuin/token';
 import { fromB64, toB64 } from '@sozai/codec';
+import { withFileLock } from '@sozai/lock';
 import { safeStorage } from 'electron';
-function encryptKey(encoded) {
-    return toB64(safeStorage.encryptString(encoded));
+/** Encrypt raw key bytes for storage: base64(safeStorage(base64(key))). */ function encryptKey(privateKey) {
+    return toB64(safeStorage.encryptString(toB64(privateKey)));
 }
 function decryptKey(encrypted) {
-    return safeStorage.decryptString(Buffer.from(fromB64(encrypted)));
+    return fromB64(safeStorage.decryptString(Buffer.from(fromB64(encrypted))));
 }
-// Stored as base64
 export class ElectronKeyEntry {
     #keyID;
     #key;
     #storage;
     #allowInsecureStorage;
-    constructor(storage, keyID, key, allowInsecureStorage = false){
-        this.#keyID = keyID;
-        this.#key = key;
-        this.#storage = storage;
-        this.#allowInsecureStorage = allowInsecureStorage;
+    #lockPath;
+    #provideLock = Promise.resolve();
+    constructor(params){
+        this.#keyID = params.keyID;
+        this.#key = params.key;
+        this.#storage = params.storage;
+        this.#allowInsecureStorage = params.allowInsecureStorage ?? false;
+        this.#lockPath = params.lockPath;
     }
     #assertEncryptionAvailable() {
         if (!this.#allowInsecureStorage && !safeStorage.isEncryptionAvailable()) {
@@ -27,9 +30,6 @@ export class ElectronKeyEntry {
     get keyID() {
         return this.#keyID;
     }
-    getAsync() {
-        return Promise.resolve(this.get());
-    }
     get() {
         if (this.#key != null) {
             return this.#key;
@@ -38,42 +38,61 @@ export class ElectronKeyEntry {
         if (encrypted == null) {
             return null;
         }
-        const key = decryptKey(encrypted);
-        if (key == null) {
-            return null;
-        }
-        this.#key = key;
+        this.#key = decryptKey(encrypted);
         return this.#key;
     }
-    async setAsync(key) {
-        return this.set(key);
+    async getAsync() {
+        return this.get();
     }
-    set(key) {
+    set(privateKey) {
         this.#assertEncryptionAvailable();
-        const encrypted = encryptKey(key);
         const keys = this.#storage.getKeys();
-        keys[this.#keyID] = encrypted;
+        keys[this.#keyID] = encryptKey(privateKey);
         this.#storage.setKeys(keys);
-        this.#key = key;
+        this.#key = privateKey;
     }
-    async provideAsync() {
-        return this.provide();
+    async setAsync(privateKey) {
+        this.set(privateKey);
+    }
+    /**
+   * The stored key, generating one if absent. Synchronous, and therefore **not** cross-process
+   * safe. Throws when a `lockPath` is set rather than silently dropping the guarantee.
+   */ provide() {
+        if (this.#lockPath != null) {
+            throw new Error('ElectronKeyEntry.provide() cannot hold a cross-process lock: a file lock cannot be ' + 'acquired synchronously. This store was opened with a lockPath — use provideAsync().');
+        }
+        return this.#provideUnlocked();
     }
-    provide() {
+    provideAsync() {
+        const run = this.#provideLock.then(async ()=>{
+            const lockPath = this.#lockPath;
+            if (lockPath == null) {
+                return this.#provideUnlocked();
+            }
+            return await withFileLock(lockPath, async ()=>this.#provideUnlocked());
+        });
+        this.#provideLock = run.catch(()=>undefined);
+        return run;
+    }
+    /** Read-if-absent, generate, write. The caller owns exclusion. */ #provideUnlocked() {
+        // Drop the in-memory cache: inside the lock we must see a peer's write, not our own
+        // stale read. Without this the winner clobbers the peer's key.
+        this.#key = undefined;
         const existing = this.get();
         if (existing != null) {
             return existing;
         }
-        const privateKey = toB64(randomPrivateKey());
+        const privateKey = randomPrivateKey();
         this.set(privateKey);
         return privateKey;
     }
-    removeAsync() {
-        return Promise.resolve(this.remove());
-    }
     remove() {
-        const { [this.#keyID]: _, ...keys } = this.#storage.getKeys();
+        const keys = this.#storage.getKeys();
+        delete keys[this.#keyID];
         this.#storage.setKeys(keys);
         this.#key = undefined;
     }
+    async removeAsync() {
+        this.remove();
+    }
 }

package/lib/index.d.ts

@@ -9,6 +9,6 @@
  *
  * @module electron-keystore
  */
-export { ElectronKeyEntry } from './entry.js';
-export { provideFullIdentity, provideFullIdentityAsync } from './identity.js';
-export { ElectronKeyStore } from './store.js';
+export { ElectronKeyEntry, type ElectronKeyEntryParams } from './entry.js';
+export { ElectronKeyStore, type ElectronKeyStoreParams } from './store.js';
+export type { KeyStorage } from './types.js';

package/lib/index.js

@@ -9,5 +9,4 @@
  *
  * @module electron-keystore
  */ export { ElectronKeyEntry } from './entry.js';
-export { provideFullIdentity, provideFullIdentityAsync } from './identity.js';
 export { ElectronKeyStore } from './store.js';

package/lib/store.d.ts

@@ -1,10 +1,30 @@
-import type { KeyStore } from '@kokuin/token';
+import { type FullIdentity, type IdentityProvider, type KeyStore } from '@kokuin/token';
 import { ElectronKeyEntry } from './entry.js';
-export declare class ElectronKeyStore implements KeyStore<string, ElectronKeyEntry> {
+export type ElectronKeyStoreParams = {
+    /** The electron-store file name. Defaults to `'keystore'`. */
+    name?: string;
+    allowInsecureStorage?: boolean;
+    /**
+     * Path to a lockfile enabling **cross-process** exclusion on `provideAsync`.
+     *
+     * Absent, nothing touches the filesystem and only the in-process lock applies — two
+     * processes can still both generate a key for a fresh keyID, and the loser's key is lost.
+     *
+     * A **file**, not a directory: one coarse lock per store, not one per keyID. A per-keyID
+     * lockfile would derive its name from an attacker-influenced keyID (`entry('../../etc/x')`),
+     * and `provideAsync` runs once per identity, so serializing across keyIDs costs nothing real.
+     *
+     * Must be on a local filesystem (`link()` is not atomic on NFS). Acquisition is bounded and
+     * throws `TimeoutInterruption` on expiry — it never proceeds unlocked.
+     */
+    lockPath?: string;
+};
+export declare class ElectronKeyStore implements KeyStore<Uint8Array, ElectronKeyEntry>, IdentityProvider<FullIdentity> {
     #private;
-    static open(name?: string, options?: {
-        allowInsecureStorage?: boolean;
-    }): ElectronKeyStore;
-    constructor(name: string, allowInsecureStorage?: boolean);
+    static open(params?: ElectronKeyStoreParams): ElectronKeyStore;
+    constructor(params?: ElectronKeyStoreParams);
     entry(keyID: string): ElectronKeyEntry;
+    provideIdentity(keyID: string): Promise<FullIdentity>;
+    /** {@link provideIdentity}, synchronously. Beyond the `IdentityProvider` contract. */
+    provideIdentitySync(keyID: string): FullIdentity;
 }

package/lib/store.js

@@ -1,23 +1,40 @@
+import { createTracer, KokuinAttributeKeys, KokuinSpanNames } from '@kokuin/otel';
+import { createFullIdentity } from '@kokuin/token';
+import { getLogger } from '@sozai/log';
+import { withSpan, withSyncSpan } from '@sozai/otel';
 import Store from 'electron-store';
 import { ElectronKeyEntry } from './entry.js';
+const tracer = createTracer('keystore.electron');
+const logger = getLogger([
+    'kokuin',
+    'electron'
+]);
 export class ElectronKeyStore {
     static #byName = Object.create(null);
-    static open(name = 'keystore', options) {
+    static open(params) {
+        const name = params?.name ?? 'keystore';
         const cached = ElectronKeyStore.#byName[name];
         if (cached == null) {
-            ElectronKeyStore.#byName[name] = new ElectronKeyStore(name, options?.allowInsecureStorage ?? false);
-        } else if (options?.allowInsecureStorage != null && options.allowInsecureStorage !== cached.#allowInsecureStorage) {
-            throw new Error(`ElectronKeyStore.open('${name}') was already opened with allowInsecureStorage: ` + `${cached.#allowInsecureStorage}; cannot reopen with conflicting allowInsecureStorage: ` + `${options.allowInsecureStorage}.`);
+            ElectronKeyStore.#byName[name] = new ElectronKeyStore(params);
+            return ElectronKeyStore.#byName[name];
         }
-        return ElectronKeyStore.#byName[name];
+        if (params?.allowInsecureStorage != null && params.allowInsecureStorage !== cached.#allowInsecureStorage) {
+            throw new Error(`ElectronKeyStore.open('${name}') was already opened with allowInsecureStorage: ` + `${cached.#allowInsecureStorage}; cannot reopen with conflicting allowInsecureStorage: ` + `${params.allowInsecureStorage}.`);
+        }
+        if (params?.lockPath != null && params.lockPath !== cached.#lockPath) {
+            throw new Error(`ElectronKeyStore.open('${name}') was already opened with lockPath: ` + `${String(cached.#lockPath)}; cannot reopen with conflicting lockPath: ${params.lockPath}.`);
+        }
+        return cached;
     }
     #entries = Object.create(null);
     #storage;
     #allowInsecureStorage;
-    constructor(name, allowInsecureStorage = false){
-        this.#allowInsecureStorage = allowInsecureStorage;
+    #lockPath;
+    constructor(params){
+        this.#allowInsecureStorage = params?.allowInsecureStorage ?? false;
+        this.#lockPath = params?.lockPath;
         const store = new Store({
-            name,
+            name: params?.name ?? 'keystore',
             schema: {
                 keys: {
                     type: 'object',
@@ -33,12 +50,61 @@ export class ElectronKeyStore {
             }
         });
         this.#storage = {
-            getKeys: ()=>store.get('keys', {}),
-            setKeys: (keys)=>store.set('keys', keys)
+            // Copy onto a null prototype: the object electron-store hands back is JSON-derived and
+            // inherits Object.prototype, which makes '__proto__' and 'constructor' hazardous keyIDs.
+            getKeys: ()=>Object.assign(Object.create(null), store.get('keys', {})),
+            setKeys: (keys)=>store.set('keys', {
+                    ...keys
+                })
         };
     }
     entry(keyID) {
-        this.#entries[keyID] ??= new ElectronKeyEntry(this.#storage, keyID, undefined, this.#allowInsecureStorage);
+        this.#entries[keyID] ??= new ElectronKeyEntry({
+            storage: this.#storage,
+            keyID,
+            allowInsecureStorage: this.#allowInsecureStorage,
+            lockPath: this.#lockPath
+        });
         return this.#entries[keyID];
     }
+    async provideIdentity(keyID) {
+        return withSpan(tracer, KokuinSpanNames.KEYSTORE_GET_OR_CREATE, {
+            attributes: {
+                [KokuinAttributeKeys.KEYSTORE_STORE_TYPE]: 'electron'
+            }
+        }, async (span)=>{
+            const entry = this.entry(keyID);
+            const existing = await entry.getAsync();
+            const privateKey = existing ?? await entry.provideAsync();
+            const identity = createFullIdentity(privateKey);
+            span.setAttribute(KokuinAttributeKeys.AUTH_DID, identity.id);
+            span.setAttribute(KokuinAttributeKeys.KEYSTORE_KEY_CREATED, existing == null);
+            if (existing == null) {
+                logger.info('New identity generated: {did}', {
+                    did: identity.id
+                });
+            }
+            return identity;
+        });
+    }
+    /** {@link provideIdentity}, synchronously. Beyond the `IdentityProvider` contract. */ provideIdentitySync(keyID) {
+        return withSyncSpan(tracer, KokuinSpanNames.KEYSTORE_GET_OR_CREATE, {
+            attributes: {
+                [KokuinAttributeKeys.KEYSTORE_STORE_TYPE]: 'electron'
+            }
+        }, (span)=>{
+            const entry = this.entry(keyID);
+            const existing = entry.get();
+            const privateKey = existing ?? entry.provide();
+            const identity = createFullIdentity(privateKey);
+            span.setAttribute(KokuinAttributeKeys.AUTH_DID, identity.id);
+            span.setAttribute(KokuinAttributeKeys.KEYSTORE_KEY_CREATED, existing == null);
+            if (existing == null) {
+                logger.info('New identity generated: {did}', {
+                    did: identity.id
+                });
+            }
+            return identity;
+        });
+    }
 }

package/lib/types.d.ts

@@ -1,3 +1,11 @@
+/**
+ * The persisted keyID → encrypted-key map.
+ *
+ * `getKeys` MUST return a **null-prototype** object. A plain `{}` inherits from
+ * `Object.prototype`, so `keys['constructor']` reads back a function rather than `undefined`,
+ * and `keys['__proto__'] = value` sets the prototype instead of creating an own property —
+ * silently discarding the key. With a null prototype both behave as ordinary string keys.
+ */
 export type KeyStorage = {
     getKeys: () => Record<string, string>;
     setKeys: (keys: Record<string, string>) => void;

package/lib/types.js

@@ -1 +1,8 @@
-export { };
+/**
+ * The persisted keyID → encrypted-key map.
+ *
+ * `getKeys` MUST return a **null-prototype** object. A plain `{}` inherits from
+ * `Object.prototype`, so `keys['constructor']` reads back a function rather than `undefined`,
+ * and `keys['__proto__'] = value` sets the prototype instead of creating an own property —
+ * silently discarding the key. With a null prototype both behave as ordinary string keys.
+ */ export { };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kokuin/electron",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "MIT",
   "description": "Electron keystore",
   "keywords": [
@@ -26,14 +26,16 @@
   "sideEffects": false,
   "dependencies": {
     "@sozai/codec": "^0.2.0",
-    "@sozai/log": "^0.1.0",
-    "@sozai/otel": "^0.2.0",
+    "@sozai/lock": "^0.1.0",
+    "@sozai/log": "^0.2.0",
+    "@sozai/otel": "^0.3.0",
     "electron-store": "^11.0.2",
-    "@kokuin/otel": "^0.1.0",
-    "@kokuin/token": "^0.2.0"
+    "@kokuin/otel": "^0.3.0",
+    "@kokuin/token": "^0.3.0"
   },
   "devDependencies": {
-    "electron": "^43.1.0"
+    "electron": "^43.1.0",
+    "@kokuin/keystore-conformance": "^0.0.0"
   },
   "scripts": {
     "build:clean": "del lib",

package/lib/identity.d.ts

@@ -1,4 +0,0 @@
-import { type FullIdentity } from '@kokuin/token';
-import { ElectronKeyStore } from './store.js';
-export declare function provideFullIdentity(store: ElectronKeyStore | string, keyID: string): FullIdentity;
-export declare function provideFullIdentityAsync(store: ElectronKeyStore | string, keyID: string): Promise<FullIdentity>;

package/lib/identity.js

@@ -1,61 +0,0 @@
-import { createTracer, KokuinAttributeKeys, KokuinSpanNames } from '@kokuin/otel';
-import { createFullIdentity, decodePrivateKey } from '@kokuin/token';
-import { getLogger } from '@sozai/log';
-import { withSpan, withSyncSpan } from '@sozai/otel';
-import { ElectronKeyStore } from './store.js';
-const tracer = createTracer('keystore.electron');
-const logger = getLogger([
-    'kokuin',
-    'electron'
-]);
-function getStore(store) {
-    return typeof store === 'string' ? ElectronKeyStore.open(store) : store;
-}
-export function provideFullIdentity(store, keyID) {
-    return withSyncSpan(tracer, KokuinSpanNames.KEYSTORE_GET_OR_CREATE, {
-        attributes: {
-            [KokuinAttributeKeys.KEYSTORE_STORE_TYPE]: 'electron'
-        }
-    }, (span)=>{
-        const entry = getStore(store).entry(keyID);
-        const existing = entry.get();
-        if (existing != null) {
-            const identity = createFullIdentity(decodePrivateKey(existing));
-            span.setAttribute(KokuinAttributeKeys.AUTH_DID, identity.id);
-            span.setAttribute(KokuinAttributeKeys.KEYSTORE_KEY_CREATED, false);
-            return identity;
-        }
-        const key = entry.provide();
-        const identity = createFullIdentity(decodePrivateKey(key));
-        span.setAttribute(KokuinAttributeKeys.AUTH_DID, identity.id);
-        span.setAttribute(KokuinAttributeKeys.KEYSTORE_KEY_CREATED, true);
-        logger.info('New identity generated: {did}', {
-            did: identity.id
-        });
-        return identity;
-    });
-}
-export async function provideFullIdentityAsync(store, keyID) {
-    return withSpan(tracer, KokuinSpanNames.KEYSTORE_GET_OR_CREATE, {
-        attributes: {
-            [KokuinAttributeKeys.KEYSTORE_STORE_TYPE]: 'electron'
-        }
-    }, async (span)=>{
-        const entry = getStore(store).entry(keyID);
-        const existing = await entry.getAsync();
-        if (existing != null) {
-            const identity = createFullIdentity(decodePrivateKey(existing));
-            span.setAttribute(KokuinAttributeKeys.AUTH_DID, identity.id);
-            span.setAttribute(KokuinAttributeKeys.KEYSTORE_KEY_CREATED, false);
-            return identity;
-        }
-        const key = await entry.provideAsync();
-        const identity = createFullIdentity(decodePrivateKey(key));
-        span.setAttribute(KokuinAttributeKeys.AUTH_DID, identity.id);
-        span.setAttribute(KokuinAttributeKeys.KEYSTORE_KEY_CREATED, true);
-        logger.info('New identity generated: {did}', {
-            did: identity.id
-        });
-        return identity;
-    });
-}