@kokuin/browser 0.1.2 → 0.2.0

package/README.md

@@ -5,3 +5,16 @@
 ```sh
 npm install @kokuin/browser
 ```
+
+## Requirements
+
+`BrowserKeyStore` holds a non-extractable Ed25519 signing key plus the X25519 agreement key
+derived from it, and needs `SubtleCrypto` support for both algorithms: Chrome 137+, Firefox
+130+, or Safari 17+. On an older browser it hard-errors rather than falling back to ES256 — a
+fallback would mint a different DID for the same keyID.
+
+Key records minted before this requirement (ES256) keep working, but only for signing —
+WebCrypto will not let an ECDSA key do `deriveBits`, so a legacy record cannot decrypt. Use
+`store.provideSigningIdentity(keyID)` for one; `store.provideIdentity(keyID)` throws on it,
+since it promises decryption. Legacy records are never silently re-keyed, since that would
+change the identity's DID.

package/lib/entry.d.ts

@@ -1,11 +1,16 @@
-import type { KeyEntry } from '@kokuin/token';
+import type { MutableKeyEntry } from '@kokuin/token';
+import { type StoredKeyRecord } from './utils.js';
 export type GetStore = (mode?: IDBTransactionMode) => IDBObjectStore;
-export declare class BrowserKeyEntry implements KeyEntry<CryptoKeyPair> {
+export type BrowserKeyEntryParams = {
+    keyID: string;
+    getStore: GetStore;
+};
+export declare class BrowserKeyEntry implements MutableKeyEntry<StoredKeyRecord> {
     #private;
-    constructor(keyID: string, getStore: GetStore);
+    constructor(params: BrowserKeyEntryParams);
     get keyID(): string;
-    getAsync(): Promise<CryptoKeyPair | null>;
-    setAsync(keyPair: CryptoKeyPair): Promise<void>;
-    provideAsync(): Promise<CryptoKeyPair>;
+    getAsync(): Promise<StoredKeyRecord | null>;
+    setAsync(record: StoredKeyRecord): Promise<void>;
+    provideAsync(): Promise<StoredKeyRecord>;
     removeAsync(): Promise<void>;
 }

package/lib/entry.js

@@ -1,10 +1,10 @@
-import { randomKeyPair } from './utils.js';
+import { generateKeyRecord } from './utils.js';
 export class BrowserKeyEntry {
     #getStore;
     #keyID;
-    constructor(keyID, getStore){
-        this.#getStore = getStore;
-        this.#keyID = keyID;
+    constructor(params){
+        this.#getStore = params.getStore;
+        this.#keyID = params.keyID;
     }
     get keyID() {
         return this.#keyID;
@@ -16,27 +16,48 @@ export class BrowserKeyEntry {
             request.onsuccess = ()=>resolve(request.result ?? null);
         });
     }
-    setAsync(keyPair) {
+    setAsync(record) {
         return new Promise((resolve, reject)=>{
-            const request = this.#getStore('readwrite').put(keyPair, this.#keyID);
+            const store = this.#getStore('readwrite');
+            const request = store.put(record, this.#keyID);
             request.onerror = ()=>reject(request.error);
-            request.onsuccess = ()=>resolve();
+            const tx = store.transaction;
+            tx.oncomplete = ()=>resolve();
+            tx.onabort = ()=>reject(tx.error ?? new Error('Transaction aborted'));
+            tx.onerror = ()=>reject(tx.error ?? new Error('Transaction failed'));
         });
     }
-    async provideAsync() {
-        const existing = await this.getAsync();
-        if (existing != null) {
-            return existing;
-        }
-        const keyPair = await randomKeyPair();
-        await this.setAsync(keyPair);
-        return keyPair;
+    provideAsync() {
+        return generateKeyRecord().then((generated)=>new Promise((resolve, reject)=>{
+                const store = this.#getStore('readwrite');
+                const getRequest = store.get(this.#keyID);
+                let result = generated;
+                getRequest.onerror = ()=>reject(getRequest.error);
+                getRequest.onsuccess = ()=>{
+                    const existing = getRequest.result;
+                    if (existing != null) {
+                        // A stored record ALWAYS wins over the freshly generated one — including a
+                        // legacy ES256 record. Overwriting it would change the identity's DID.
+                        result = existing;
+                    } else {
+                        store.put(generated, this.#keyID);
+                    }
+                };
+                const tx = store.transaction;
+                tx.oncomplete = ()=>resolve(result);
+                tx.onabort = ()=>reject(tx.error ?? new Error('Transaction aborted'));
+                tx.onerror = ()=>reject(tx.error ?? new Error('Transaction failed'));
+            }));
     }
     removeAsync() {
         return new Promise((resolve, reject)=>{
-            const request = this.#getStore('readwrite').delete(this.#keyID);
+            const store = this.#getStore('readwrite');
+            const request = store.delete(this.#keyID);
             request.onerror = ()=>reject(request.error);
-            request.onsuccess = ()=>resolve();
+            const tx = store.transaction;
+            tx.oncomplete = ()=>resolve();
+            tx.onabort = ()=>reject(tx.error ?? new Error('Transaction aborted'));
+            tx.onerror = ()=>reject(tx.error ?? new Error('Transaction failed'));
         });
     }
 }

package/lib/identity.d.ts

@@ -1,3 +1,9 @@
-import { type SigningIdentity } from '@kokuin/token';
-import { BrowserKeyStore } from './store.js';
-export declare function provideSigningIdentity(keyID: string, useStore?: BrowserKeyStore | Promise<BrowserKeyStore> | string): Promise<SigningIdentity>;
+import { type FullIdentity, type SigningIdentity } from '@kokuin/token';
+import { type BrowserKeyRecord, type LegacyES256Record } from './utils.js';
+/**
+ * The current identity: non-extractable Ed25519 signing key, plus the X25519 agreement key
+ * derived from it. `did:key` EdDSA, so it is addressable by every other kokuin backend and
+ * decryptable by anyone who knows only its DID.
+ */
+export declare function createBrowserIdentity(record: BrowserKeyRecord): Promise<FullIdentity>;
+export declare function createLegacyES256Identity(record: LegacyES256Record): Promise<SigningIdentity>;

package/lib/identity.js

@@ -1,30 +1,93 @@
-import { createTracer, KokuinAttributeKeys, KokuinSpanNames } from '@kokuin/otel';
-import { CODECS, getDID } from '@kokuin/token';
+import { CODECS, decryptToken, getDID } from '@kokuin/token';
+import { x25519 } from '@noble/curves/ed25519.js';
 import { p256 } from '@noble/curves/nist.js';
 import { b64uFromJSON, fromUTF, toB64U } from '@sozai/codec';
-import { getLogger } from '@sozai/log';
-import { withSpan } from '@sozai/otel';
-import { BrowserKeyStore } from './store.js';
-import { getPublicKey } from './utils.js';
-const tracer = createTracer('keystore.browser');
-const logger = getLogger([
-    'kokuin',
-    'browser'
-]);
-// P-256 curve order, used to reflect a high-S signature to its low-S form.
+import { getES256PublicKey } from './utils.js';
+/**
+ * The current identity: non-extractable Ed25519 signing key, plus the X25519 agreement key
+ * derived from it. `did:key` EdDSA, so it is addressable by every other kokuin backend and
+ * decryptable by anyone who knows only its DID.
+ */ export async function createBrowserIdentity(record) {
+    const publicKey = record.publicKey;
+    const id = getDID(CODECS.EdDSA, publicKey);
+    // The agreement key is stored as raw bytes (WebKit cannot persist an X25519 CryptoKey; see
+    // BrowserKeyRecord). Re-import it here, non-extractable, for ECDH.
+    const agreementPublic = x25519.getPublicKey(record.agreementSecret);
+    const agreement = await globalThis.crypto.subtle.importKey('jwk', {
+        kty: 'OKP',
+        crv: 'X25519',
+        d: toB64U(record.agreementSecret),
+        x: toB64U(agreementPublic)
+    }, {
+        name: 'X25519'
+    }, false, [
+        'deriveBits'
+    ]);
+    async function signToken(payload, options = {}) {
+        if (payload.iss != null && payload.iss !== id) {
+            throw new Error('Invalid payload: issuer does not match signer');
+        }
+        const fullHeader = {
+            ...options.header ?? {},
+            typ: 'JWT',
+            alg: 'EdDSA'
+        };
+        const fullPayload = {
+            ...payload,
+            iss: id
+        };
+        const data = `${b64uFromJSON(fullHeader)}.${b64uFromJSON(fullPayload)}`;
+        // Ed25519 signatures are canonical — no low-S normalization needed, unlike ECDSA.
+        const signature = await globalThis.crypto.subtle.sign({
+            name: 'Ed25519'
+        }, record.signing, fromUTF(data));
+        return {
+            header: fullHeader,
+            payload: fullPayload,
+            signature: toB64U(new Uint8Array(signature)),
+            data
+        };
+    }
+    async function agreeKey(ephemeralPublicKey) {
+        const ephemeral = await globalThis.crypto.subtle.importKey('raw', ephemeralPublicKey, {
+            name: 'X25519'
+        }, true, []);
+        const shared = await globalThis.crypto.subtle.deriveBits({
+            name: 'X25519',
+            public: ephemeral
+        }, agreement, 256);
+        return new Uint8Array(shared);
+    }
+    async function decrypt(jwe) {
+        return decryptToken({
+            id,
+            decrypt,
+            agreeKey
+        }, jwe);
+    }
+    return {
+        id,
+        publicKey,
+        signToken,
+        decrypt,
+        agreeKey
+    };
+}
+// --- Legacy ES256 path ---
+//
+// Records minted before the Ed25519 migration. They can only sign: WebCrypto will not let an
+// ECDSA key do deriveBits, so they cannot do ECDH, so they cannot decrypt. They keep working,
+// and they are NEVER silently re-keyed — that would change the identity's DID under it.
 const P256_N = p256.Point.Fn.ORDER;
-// Web Crypto's subtle.sign does not enforce low-S, so ~half of ECDSA signatures
-// have s > n/2 (high-S). The @kokuin/token verifier runs with `lowS: true` and
-// rejects those for malleability safety, so we normalize here for cross-stack
-// compatibility. `hasHighS()` is the same predicate noble's verifier applies.
+// Web Crypto's subtle.sign does not enforce low-S, so ~half of ECDSA signatures have s > n/2.
+// The @kokuin/token verifier runs with `lowS: true` and rejects those for malleability safety.
 function normalizeSignatureToLowS(sig) {
-    // sig is IEEE P1363 compact format: r (32 bytes) || s (32 bytes).
     const parsed = p256.Signature.fromBytes(sig, 'compact');
     if (!parsed.hasHighS()) return sig;
     return new p256.Signature(parsed.r, P256_N - parsed.s).toBytes('compact');
 }
-async function createBrowserSigningIdentity(keyPair) {
-    const publicKey = await getPublicKey(keyPair);
+export async function createLegacyES256Identity(record) {
+    const publicKey = await getES256PublicKey(record);
     const id = getDID(CODECS.ES256, publicKey);
     async function signToken(payload, options = {}) {
         if (payload.iss != null && payload.iss !== id) {
@@ -40,17 +103,14 @@ async function createBrowserSigningIdentity(keyPair) {
             iss: id
         };
         const data = `${b64uFromJSON(fullHeader)}.${b64uFromJSON(fullPayload)}`;
-        const messageBytes = fromUTF(data);
-        const signatureBuffer = await globalThis.crypto.subtle.sign({
+        const signature = await globalThis.crypto.subtle.sign({
             name: 'ECDSA',
             hash: 'SHA-256'
-        }, keyPair.privateKey, messageBytes.buffer);
-        // Normalize to low-S: @kokuin/token verifier rejects high-S signatures
-        const normalizedSig = normalizeSignatureToLowS(new Uint8Array(signatureBuffer));
+        }, record.privateKey, fromUTF(data));
         return {
             header: fullHeader,
             payload: fullPayload,
-            signature: toB64U(normalizedSig),
+            signature: toB64U(normalizeSignatureToLowS(new Uint8Array(signature))),
             data
         };
     }
@@ -60,29 +120,3 @@ async function createBrowserSigningIdentity(keyPair) {
         signToken
     };
 }
-export async function provideSigningIdentity(keyID, useStore) {
-    return withSpan(tracer, KokuinSpanNames.KEYSTORE_GET_OR_CREATE, {
-        attributes: {
-            [KokuinAttributeKeys.KEYSTORE_STORE_TYPE]: 'browser'
-        }
-    }, async (span)=>{
-        const storePromise = useStore == null || typeof useStore === 'string' ? BrowserKeyStore.open(useStore) : Promise.resolve(useStore);
-        const store = await storePromise;
-        const entry = store.entry(keyID);
-        const existing = await entry.getAsync();
-        if (existing != null) {
-            const identity = await createBrowserSigningIdentity(existing);
-            span.setAttribute(KokuinAttributeKeys.AUTH_DID, identity.id);
-            span.setAttribute(KokuinAttributeKeys.KEYSTORE_KEY_CREATED, false);
-            return identity;
-        }
-        const keyPair = await entry.provideAsync();
-        const identity = await createBrowserSigningIdentity(keyPair);
-        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;
-    });
-}

package/lib/index.d.ts

@@ -9,7 +9,6 @@
  *
  * @module browser-keystore
  */
-export { BrowserKeyEntry } from './entry.js';
-export { provideSigningIdentity } from './identity.js';
-export { BrowserKeyStore } from './store.js';
-export { getPublicKey, randomKeyPair } from './utils.js';
+export { BrowserKeyEntry, type BrowserKeyEntryParams, type GetStore } from './entry.js';
+export { BrowserKeyStore, type BrowserKeyStoreParams } from './store.js';
+export { assertEd25519Available, type BrowserKeyRecord, generateKeyRecord, isLegacyES256Record, type LegacyES256Record, type StoredKeyRecord, } from './utils.js';

package/lib/index.js

@@ -9,6 +9,5 @@
  *
  * @module browser-keystore
  */ export { BrowserKeyEntry } from './entry.js';
-export { provideSigningIdentity } from './identity.js';
 export { BrowserKeyStore } from './store.js';
-export { getPublicKey, randomKeyPair } from './utils.js';
+export { assertEd25519Available, generateKeyRecord, isLegacyES256Record } from './utils.js';

package/lib/store.d.ts

@@ -1,8 +1,29 @@
-import type { KeyStore } from '@kokuin/token';
-import { BrowserKeyEntry } from './entry.js';
-export declare class BrowserKeyStore implements KeyStore<CryptoKeyPair, BrowserKeyEntry> {
+import type { FullIdentity, IdentityProvider, KeyStore, SigningIdentity } from '@kokuin/token';
+import { BrowserKeyEntry, type GetStore } from './entry.js';
+import { type StoredKeyRecord } from './utils.js';
+export type BrowserKeyStoreParams = {
+    /** The IndexedDB database name. Defaults to `'kokuin:key-store'`. */
+    name?: string;
+};
+export declare class BrowserKeyStore implements KeyStore<StoredKeyRecord, BrowserKeyEntry>, IdentityProvider<FullIdentity> {
     #private;
-    static open(name?: string): Promise<BrowserKeyStore>;
-    constructor(db: IDBDatabase);
+    static open(params?: BrowserKeyStoreParams): Promise<BrowserKeyStore>;
+    constructor(getStore: GetStore);
     entry(keyID: string): BrowserKeyEntry;
+    /**
+     * The full identity for `keyID` — signing and decryption.
+     *
+     * **Throws on a legacy ES256 record.** Such a record physically cannot decrypt (WebCrypto
+     * will not let an ECDSA key do `deriveBits`), and it is never silently re-keyed, because
+     * that would change the identity's DID. Use {@link provideSigningIdentity} to work with one.
+     */
+    provideIdentity(keyID: string): Promise<FullIdentity>;
+    /**
+     * A signing identity for `keyID`, accepting **both** suites.
+     *
+     * Returns a `FullIdentity` (a subtype of `SigningIdentity`) for a current record, and an
+     * ES256 signing identity for a legacy one. New code should prefer {@link provideIdentity},
+     * which promises decryption statically.
+     */
+    provideSigningIdentity(keyID: string): Promise<SigningIdentity>;
 }

package/lib/store.js

@@ -1,15 +1,26 @@
+import { createTracer, KokuinAttributeKeys, KokuinSpanNames } from '@kokuin/otel';
 import { defer } from '@sozai/async';
+import { getLogger } from '@sozai/log';
+import { withSpan } from '@sozai/otel';
 import { BrowserKeyEntry } from './entry.js';
+import { createBrowserIdentity, createLegacyES256Identity } from './identity.js';
+import { isLegacyES256Record } from './utils.js';
 const DEFAULT_DB_NAME = 'kokuin:key-store';
 const STORE_NAME = 'keys';
+const tracer = createTracer('keystore.browser');
+const logger = getLogger([
+    'kokuin',
+    'browser'
+]);
 function createGetStore(db) {
     return function getStore(mode = 'readonly') {
         return db.transaction(STORE_NAME, mode).objectStore(STORE_NAME);
     };
 }
 export class BrowserKeyStore {
-    static #byName = {};
-    static open(name = DEFAULT_DB_NAME) {
+    static #byName = Object.create(null);
+    static open(params) {
+        const name = params?.name ?? DEFAULT_DB_NAME;
         const existing = BrowserKeyStore.#byName[name];
         if (existing != null) {
             return existing;
@@ -26,20 +37,65 @@ export class BrowserKeyStore {
         }
         const request = indexedDB.open(name, 1);
         request.onerror = ()=>reject(request.error);
-        request.onsuccess = ()=>resolve(new BrowserKeyStore(request.result));
+        request.onsuccess = ()=>resolve(new BrowserKeyStore(createGetStore(request.result)));
         request.onupgradeneeded = (event)=>{
             ;
             event.target.result.createObjectStore(STORE_NAME);
         };
         return promise;
     }
-    #entries = {};
+    #entries = Object.create(null);
     #getStore;
-    constructor(db){
-        this.#getStore = createGetStore(db);
+    constructor(getStore){
+        this.#getStore = getStore;
     }
     entry(keyID) {
-        this.#entries[keyID] ??= new BrowserKeyEntry(keyID, this.#getStore);
+        this.#entries[keyID] ??= new BrowserKeyEntry({
+            keyID,
+            getStore: this.#getStore
+        });
         return this.#entries[keyID];
     }
+    /**
+   * The full identity for `keyID` — signing and decryption.
+   *
+   * **Throws on a legacy ES256 record.** Such a record physically cannot decrypt (WebCrypto
+   * will not let an ECDSA key do `deriveBits`), and it is never silently re-keyed, because
+   * that would change the identity's DID. Use {@link provideSigningIdentity} to work with one.
+   */ async provideIdentity(keyID) {
+        return withSpan(tracer, KokuinSpanNames.KEYSTORE_GET_OR_CREATE, {
+            attributes: {
+                [KokuinAttributeKeys.KEYSTORE_STORE_TYPE]: 'browser'
+            }
+        }, async (span)=>{
+            const record = await this.entry(keyID).provideAsync();
+            if (isLegacyES256Record(record)) {
+                throw new Error(`Key "${keyID}" holds a legacy ES256 record, which cannot decrypt. It is not ` + "re-keyed automatically: that would change this identity's DID. Use " + 'provideSigningIdentity() to sign with it, or removeAsync() it first to mint a ' + 'new Ed25519 identity under a new DID.');
+            }
+            const identity = await createBrowserIdentity(record);
+            span.setAttribute(KokuinAttributeKeys.AUTH_DID, identity.id);
+            logger.info('Browser identity resolved: {did}', {
+                did: identity.id
+            });
+            return identity;
+        });
+    }
+    /**
+   * A signing identity for `keyID`, accepting **both** suites.
+   *
+   * Returns a `FullIdentity` (a subtype of `SigningIdentity`) for a current record, and an
+   * ES256 signing identity for a legacy one. New code should prefer {@link provideIdentity},
+   * which promises decryption statically.
+   */ async provideSigningIdentity(keyID) {
+        return withSpan(tracer, KokuinSpanNames.KEYSTORE_GET_OR_CREATE, {
+            attributes: {
+                [KokuinAttributeKeys.KEYSTORE_STORE_TYPE]: 'browser'
+            }
+        }, async (span)=>{
+            const record = await this.entry(keyID).provideAsync();
+            const identity = isLegacyES256Record(record) ? await createLegacyES256Identity(record) : await createBrowserIdentity(record);
+            span.setAttribute(KokuinAttributeKeys.AUTH_DID, identity.id);
+            return identity;
+        });
+    }
 }

package/lib/utils.d.ts

@@ -1,2 +1,56 @@
-export declare function getPublicKey(keyPair: CryptoKeyPair): Promise<Uint8Array>;
-export declare function randomKeyPair(): Promise<CryptoKeyPair>;
+/**
+ * A key record minted by this version: a non-extractable Ed25519 signing key, the raw X25519
+ * agreement *secret* derived from the same seed, and the Ed25519 public key the DID is built
+ * from.
+ *
+ * The agreement key is stored as raw bytes, not as a non-extractable `CryptoKey`, because
+ * WebKit cannot persist an X25519 `CryptoKey` in IndexedDB — `put()` reports success but the
+ * subsequent `get()` returns `null` (https://bugs.webkit.org/show_bug.cgi?id=312279). A
+ * non-extractable Ed25519 `CryptoKey` persists fine, so only the agreement key degrades to
+ * bytes. See the backlog item tracking that bug; revert `agreementSecret` to a non-extractable
+ * `CryptoKey` once it is fixed.
+ *
+ * Security cost of the workaround: `agreementSecret` is the Ed25519 private scalar
+ * (`toMontgomerySecret`), so an attacker who can read IndexedDB (e.g. via XSS) can both decrypt
+ * to this identity and forge its signatures. The signing key itself stays non-extractable, but
+ * the scalar in `agreementSecret` is sufficient on its own — treat a stored record as secret.
+ *
+ * `suite` is what distinguishes it from a legacy record. An **untagged** record is ES256 by
+ * definition — that is all a pre-migration record can be.
+ */
+export type BrowserKeyRecord = {
+    suite: 'Ed25519';
+    signing: CryptoKey;
+    agreementSecret: Uint8Array;
+    publicKey: Uint8Array;
+};
+/** A pre-migration record: a bare, untagged P-256 `CryptoKeyPair`. Signing only. */
+export type LegacyES256Record = CryptoKeyPair;
+export type StoredKeyRecord = BrowserKeyRecord | LegacyES256Record;
+export declare function isLegacyES256Record(record: StoredKeyRecord): record is LegacyES256Record;
+/**
+ * Throw unless WebCrypto can do Ed25519.
+ *
+ * There is deliberately **no fallback**. Falling back to P-256 would mint a different DID for
+ * the same keyID, which is identity loss dressed up as graceful degradation. Requires
+ * Chrome 137+, Firefox 130+, or Safari 17+.
+ */
+export declare function assertEd25519Available(): Promise<void>;
+/**
+ * Mint a new key record.
+ *
+ * The seed is generated **here**, not by `subtle.generateKey`, and the signing key is imported
+ * non-extractable. This is forced, not stylistic: `jwe.ts` derives a recipient's agreement key
+ * from its Ed25519 signing key (`toMontgomery`), so the agreement key MUST be the birational
+ * image of the signing key. A `generateKey`'d X25519 keypair is independent, and therefore
+ * unreachable by any sender — nothing addressed to the DID could ever be decrypted. Deriving
+ * the montgomery secret needs the Ed25519 private scalar, which a non-extractable `generateKey`
+ * result never yields.
+ *
+ * The seed is zeroed on the way out. The X25519 `agreementSecret` is **not** — it is the stored
+ * agreement key (WebKit cannot persist an X25519 `CryptoKey`; see {@link BrowserKeyRecord}). It
+ * equals the Ed25519 private scalar, so the returned record is sensitive.
+ */
+export declare function generateKeyRecord(): Promise<BrowserKeyRecord>;
+/** The compressed P-256 public key of a legacy record. Legacy path only. */
+export declare function getES256PublicKey(keyPair: CryptoKeyPair): Promise<Uint8Array>;

package/lib/utils.js

@@ -1,18 +1,75 @@
+import { ed25519 } from '@noble/curves/ed25519.js';
+import { toB64U } from '@sozai/codec';
+export function isLegacyES256Record(record) {
+    return record.suite !== 'Ed25519';
+}
+/**
+ * Throw unless WebCrypto can do Ed25519.
+ *
+ * There is deliberately **no fallback**. Falling back to P-256 would mint a different DID for
+ * the same keyID, which is identity loss dressed up as graceful degradation. Requires
+ * Chrome 137+, Firefox 130+, or Safari 17+.
+ */ export async function assertEd25519Available() {
+    try {
+        await globalThis.crypto.subtle.generateKey({
+            name: 'Ed25519'
+        }, false, [
+            'sign',
+            'verify'
+        ]);
+    } catch (cause) {
+        throw new Error('WebCrypto does not support Ed25519, which @kokuin/browser requires (Chrome 137+, ' + 'Firefox 130+, Safari 17+). Refusing to fall back to another curve: it would mint a ' + 'different DID for the same keyID.', {
+            cause
+        });
+    }
+}
+/**
+ * Mint a new key record.
+ *
+ * The seed is generated **here**, not by `subtle.generateKey`, and the signing key is imported
+ * non-extractable. This is forced, not stylistic: `jwe.ts` derives a recipient's agreement key
+ * from its Ed25519 signing key (`toMontgomery`), so the agreement key MUST be the birational
+ * image of the signing key. A `generateKey`'d X25519 keypair is independent, and therefore
+ * unreachable by any sender — nothing addressed to the DID could ever be decrypted. Deriving
+ * the montgomery secret needs the Ed25519 private scalar, which a non-extractable `generateKey`
+ * result never yields.
+ *
+ * The seed is zeroed on the way out. The X25519 `agreementSecret` is **not** — it is the stored
+ * agreement key (WebKit cannot persist an X25519 `CryptoKey`; see {@link BrowserKeyRecord}). It
+ * equals the Ed25519 private scalar, so the returned record is sensitive.
+ */ export async function generateKeyRecord() {
+    await assertEd25519Available();
+    const seed = ed25519.utils.randomSecretKey();
+    const publicKey = ed25519.getPublicKey(seed);
+    const agreementSecret = ed25519.utils.toMontgomerySecret(seed);
+    try {
+        const signing = await globalThis.crypto.subtle.importKey('jwk', {
+            kty: 'OKP',
+            crv: 'Ed25519',
+            d: toB64U(seed),
+            x: toB64U(publicKey)
+        }, {
+            name: 'Ed25519'
+        }, false, [
+            'sign'
+        ]);
+        return {
+            suite: 'Ed25519',
+            signing,
+            agreementSecret,
+            publicKey
+        };
+    } finally{
+        seed.fill(0);
+    }
+}
 function ecPointCompress(x, y) {
     const out = new Uint8Array(x.length + 1);
     out[0] = 2 + (y[y.length - 1] & 1);
     out.set(x, 1);
     return out;
 }
-export async function getPublicKey(keyPair) {
+/** The compressed P-256 public key of a legacy record. Legacy path only. */ export async function getES256PublicKey(keyPair) {
     const rawKey = await globalThis.crypto.subtle.exportKey('raw', keyPair.publicKey);
     return ecPointCompress(new Uint8Array(rawKey.slice(1, 33)), new Uint8Array(rawKey.slice(33, 65)));
 }
-export async function randomKeyPair() {
-    return await globalThis.crypto.subtle.generateKey({
-        name: 'ECDSA',
-        namedCurve: 'P-256'
-    }, false, [
-        'sign'
-    ]);
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kokuin/browser",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "MIT",
   "description": "Key store for browser",
   "keywords": [
@@ -26,12 +26,15 @@
   "sideEffects": false,
   "dependencies": {
     "@noble/curves": "^2.0.1",
-    "@sozai/async": "^0.1.0",
-    "@sozai/codec": "^0.1.0",
-    "@sozai/log": "^0.1.0",
-    "@sozai/otel": "^0.2.0",
-    "@kokuin/token": "^0.1.1",
-    "@kokuin/otel": "^0.1.0"
+    "@sozai/async": "^0.2.1",
+    "@sozai/codec": "^0.2.0",
+    "@sozai/log": "^0.2.0",
+    "@sozai/otel": "^0.3.0",
+    "@kokuin/otel": "^0.3.0",
+    "@kokuin/token": "^0.3.0"
+  },
+  "devDependencies": {
+    "@kokuin/keystore-conformance": "^0.0.0"
   },
   "scripts": {
     "build:clean": "del lib",