@le-space/orbitdb-identity-provider-webauthn-did 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changes
 
+## 0.10.0
+
+An identity that is nobody's passkey, so that every security key of an owner can write as the same
+one; and the varsig registration's half of 0.9.1's fix, which #83 had entered under 0.9.1 after
+0.9.1 was already published from #81.
+
+### Added
+
+- **`createSecretSigner(secret, { info })`**: an Ed25519 signer derived from at least 32 bytes of
+  secret with HKDF-SHA-256 under `info`, its DID the key's `did:key`. Kept in a vault
+  (`createVault`), the secret gives every key that opens a slot the same identity — the root of a
+  database's `OrbitDBAccessController`, which OrbitDB fixes at creation and a passkey identity
+  would hold for good. In `./standalone` and `./keystore` as well.
+- **`OrbitDBWebAuthnIdentityProviderFunction({ signer })` needs no `webauthnCredential`.** A signer
+  is the whole identity, and no passkey stands behind it. Without either, the provider refuses
+  instead of failing on the missing credential.
+
+### Fixed
+
+- The varsig registration — `WebAuthnVarsigProvider.createCredential`, `createWebAuthnSigner` and
+  the signers built on it, and `createWebAuthnEd25519Credential` — honours `authenticatorType` too,
+  which it dropped the same way (#83). It still requires user verification: its code asked for
+  `'preferred'`, which never reached the browser either, and a varsig signature without the UV flag
+  is refused when it is made and when it is verified.
+
+### Changed
+
+- `createEd25519DidFromPublicKey` lives in `src/keystore/` and is re-exported from where it was, so
+  the main entry can build a `did:key` without importing the worker client.
+
+## 0.9.1
+
+`createCredential` honours the choice of authenticator that its options, its types and
+`docs/API.md` have offered all along.
+
+### Fixed
+
+- `authenticatorType` (`'platform'`, `'cross-platform'` or `'any'`) and its WebAuthn name
+  `authenticatorAttachment` reach the browser. Since 0.2.8 neither did: `buildAuthenticatorSelection`
+  dropped them, so the request named no attachment and the browser offered every kind of
+  authenticator, a security key as much as the device's own — though the code asked for
+  `'platform'`. That stays the default, so nothing changes for a caller that passes neither.
+- An unknown value, or the two disagreeing, is a `TypeError` before anyone is asked, instead of
+  being ignored.
+
+Tested in Chromium with a virtual authenticator on the USB transport: offered by default, asked for
+with `'cross-platform'`, never asked with `'platform'`. The vault test from 0.9.0 now also runs with
+two such security keys.
+
 ## 0.9.0
 
 What applications kept writing for themselves, once and here: one read of the PRF output for every

package/README.md

@@ -19,6 +19,7 @@ This package provides:
 - Authentication/assertion requests omit `allowCredentials` by default, so the browser/authenticator can resolve the credential discoverably.
 - You can switch this centrally with `configureWebAuthn({ discoverableCredentials: true|false })`.
 - Registration is still the point where this package extracts the credential public key from attestation.
+- Registration offers every kind of authenticator — the device's own, a security key such as a YubiKey, a phone — unless `authenticatorType: 'platform' | 'cross-platform'` narrows it, in `createCredential` as in the varsig registration and the standalone signers (honoured since 0.9.1). It always requires user verification.
 - Later `navigator.credentials.get()` assertions do not reliably return the public key again, so identity reconstruction still needs metadata from somewhere else.
 
 Since **0.6.0** the passkey alone is enough, and stored metadata is a convenience rather than a requirement:
@@ -227,6 +228,8 @@ const withSecondKey = await addSlot(vault, vaultKey, secondKeysSlot);
 
 How it works, and what a vault does not do: [docs/API.md](docs/API.md#prf-keys-and-vaults).
 
+Since **0.10.0**, a secret kept in that vault can be an identity of its own: `createSecretSigner(secret, { info })` turns it into an Ed25519 signer for the provider's `signer` option, so every key that opens the vault writes as the same identity — the root of a database's access controller, which a single passkey's identity would hold for good. See [docs/API.md](docs/API.md#an-identity-that-is-nobodys-passkey-createsecretsignersecret--info-).
+
 ### Keystore-based DID (WebAuthn + OrbitDB keystore)
 
 ```mermaid

package/docs/API.md

@@ -61,7 +61,17 @@ Options:
 - `encryptKeystore?: boolean`
 - `keystoreEncryptionMethod?: 'prf' | 'largeBlob' | 'hmac-secret'`
 - `discoverableCredentials?: boolean`
-- `authenticatorType?: 'platform' | 'cross-platform' | 'any'`
+- `authenticatorType?: 'platform' | 'cross-platform' | 'any'` — which
+  authenticators the browser offers: the device's own (Touch ID, Windows
+  Hello, a phone's screen lock), a security key or another phone, or every
+  kind. `'any'` is the default and names none in the request.
+- `authenticatorAttachment?: 'platform' | 'cross-platform'` — the WebAuthn name
+  for the same choice. Giving both with different values, or a value neither
+  knows, throws a `TypeError` before anyone is asked.
+
+Before 0.9.1 both were listed here and neither reached the browser: the request
+named no attachment, so every kind of authenticator was offered — a YubiKey as
+much as the device's own. That is still the default.
 
 ```js
 const credential = await WebAuthnDIDProvider.createCredential({
@@ -376,6 +386,50 @@ What a vault does not do:
 `tests/vault-two-authenticators.test.js` runs this in Chromium with two virtual
 authenticators, each with its own PRF secret as two YubiKeys have.
 
+#### An identity that is nobody's passkey: `createSecretSigner(secret, { info })`
+
+Since 0.10.0. A database whose access controller is rooted at one passkey's
+identity belongs to that passkey for good: OrbitDB fixes who may grant write
+access when a database is created, and a second security key is a second
+identity. Give the database an identity of its own instead, and let every key
+act as it: keep a random secret in the vault, and turn it into a signer.
+
+```js
+// `secret`: 32 random bytes the application keeps in its vault's payload,
+// so that any slot — any of the owner's keys — gets them back.
+const books = await createSecretSigner(secret, {
+  info: 'invoice/books-identity/v1',
+});
+
+const keystore = await createSessionKeystore({ signer: books });
+const identities = await Identities({ ipfs, keystore });
+const identity = await identities.createIdentity({
+  provider: OrbitDBWebAuthnIdentityProviderFunction({ signer: books }),
+});
+const orbitdb = await createOrbitDB({ ipfs, identities, identity });
+const db = await orbitdb.open('books', {
+  AccessController: OrbitDBAccessController({ write: [books.did] }),
+});
+```
+
+- The key is Ed25519, derived with HKDF-SHA-256 from at least 32 bytes of
+  secret under `info`, and the DID is its `did:key`. The same secret and
+  `info` give the same key, DID and identity document on every device and
+  through every slot; another `info` gives another identity. Version `info`.
+- What comes back is `{ did, type: 'Ed25519', publicKey, sign(data) }`, the
+  shape the `signer` option takes. The private key stays inside `sign`.
+- With `signer`, `OrbitDBWebAuthnIdentityProviderFunction` needs no
+  `webauthnCredential`: no passkey stands behind this identity, and nothing
+  asks one. Peers verify it as any signer identity — the DID's key is the
+  identity's public key.
+- People who should write without holding the secret are granted access under
+  their own identities (`db.access.grant('write', did)`), which can be revoked.
+  The secret's identity, as the root, cannot; against a stolen key, make a new
+  vault with a new secret and move the data.
+
+`tests/secret-signer.test.js` writes through two keys as the same root and has
+an identity from another secret refused.
+
 ### largeBlob Metadata Helpers
 
 These helpers encode and recover identity metadata used by the demo recovery
@@ -492,6 +546,17 @@ const credential = await WebAuthnVarsigProvider.createCredential({
 const identity = await createWebAuthnVarsigIdentity({ credential });
 ```
 
+`WebAuthnVarsigProvider.createCredential(options)` takes `userId`,
+`displayName`, `domain`, `discoverableCredentials`, `forceP256` (offer only
+P-256), and `authenticatorType` / `authenticatorAttachment` as
+`WebAuthnDIDProvider.createCredential` does. Before 0.9.1 it dropped the choice
+of authenticator the same way and offered every kind.
+
+It always requires user verification, whatever the options say. A varsig
+signature without the UV flag is refused, when it is made and when it is
+verified, so a credential registered without user verification could never
+sign.
+
 ## Standalone Export
 
 Use the standalone export when you want WebAuthn signing and worker-keystore
@@ -515,6 +580,10 @@ import {
 - `createWebAuthnEd25519Credential(userId, displayName, options?)`
 - `checkEd25519Support()`
 
+The `create…Signer` functions register as
+`WebAuthnVarsigProvider.createCredential` does and take its options;
+`createWebAuthnEd25519Credential` passes on `options.authenticatorType` alone.
+
 ```js
 const signer = await createWebAuthnSigner({
   userId: 'alice@example.com',
@@ -552,8 +621,9 @@ const ucanSigner = signer.toUcantoSigner({
 
 The same functions as the root export, without OrbitDB: `readPrfOutput`,
 `deriveSubkey`, `deriveAesKey`, `createVault`, `openVault`, `addSlot`,
-`removeSlot`, `replacePayload`, `slotIdFor`, `PrfUnavailableError` and
-`VaultError`. See [PRF Keys and Vaults](#prf-keys-and-vaults).
+`removeSlot`, `replacePayload`, `slotIdFor`, `createSecretSigner`,
+`PrfUnavailableError` and `VaultError`. See
+[PRF Keys and Vaults](#prf-keys-and-vaults).
 
 ### P-256 Wallet Primitives
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@le-space/orbitdb-identity-provider-webauthn-did",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "WebAuthn-based DID identity provider for OrbitDB for hardware-secured wallets and biometric Passkey authentication",
   "main": "src/index.js",
   "types": "types/index.d.ts",

package/src/index.js

@@ -329,6 +329,9 @@ export {
   replacePayload,
   slotIdFor,
 } from './keystore/vault.js';
+// An identity that is nobody's passkey — the books every key of their owner
+// writes as, its secret kept in a vault.
+export { createSecretSigner } from './keystore/secret-signer.js';
 
 export default {
   WebAuthnDIDProvider,

package/src/keystore/ed25519-did.js

@@ -0,0 +1,26 @@
+import { varint } from 'multiformats';
+import { base58btc } from 'multiformats/bases/base58';
+
+/**
+ * Build a did:key identifier from raw Ed25519 public key bytes.
+ * @param {Uint8Array} publicKeyBytes
+ * @returns {string}
+ */
+export function createEd25519DidFromPublicKey(publicKeyBytes) {
+  if (!(publicKeyBytes instanceof Uint8Array) || publicKeyBytes.length !== 32) {
+    throw new Error(
+      `Invalid Ed25519 public key length: ${publicKeyBytes?.length || 0}`
+    );
+  }
+
+  const ED25519_MULTICODEC = 0xed;
+  const codecLength = varint.encodingLength(ED25519_MULTICODEC);
+  const codecBytes = new Uint8Array(codecLength);
+  varint.encodeTo(ED25519_MULTICODEC, codecBytes, 0);
+
+  const multikey = new Uint8Array(codecBytes.length + publicKeyBytes.length);
+  multikey.set(codecBytes, 0);
+  multikey.set(publicKeyBytes, codecBytes.length);
+
+  return `did:key:${base58btc.encode(multikey)}`;
+}

package/src/keystore/index.js

@@ -5,4 +5,5 @@ export * from './encryption.js';
 export { default } from './encryption.js';
 export * from './provider.js';
 export * from './session-keystore.js';
+export { createSecretSigner } from './secret-signer.js';
 export { PrfUnavailableError } from '../errors.js';

package/src/keystore/provider.js

@@ -46,7 +46,9 @@ function normalizeByteArray(value) {
 export class OrbitDBWebAuthnIdentityProvider {
   /**
    * @param {Object} options - Provider configuration.
-   * @param {Object} options.webauthnCredential - WebAuthn credential info.
+   * @param {Object} [options.webauthnCredential] - WebAuthn credential info.
+   *   Required unless `signer` is given: a signer is the whole identity, and
+   *   no passkey stands behind it (`createSecretSigner`).
    * @param {boolean} [options.useKeystoreDID=false] - Use keystore DID instead of WebAuthn DID.
    * @param {Object|null} [options.keystore=null] - OrbitDB keystore instance.
    * @param {string} [options.keystoreKeyType='secp256k1'] - Keystore key type.
@@ -82,6 +84,11 @@ export class OrbitDBWebAuthnIdentityProvider {
     prfOutput = null,
   }) {
     if (signer) assertSigner(signer);
+    if (!signer && !webauthnCredential) {
+      throw new TypeError(
+        'the provider needs a webauthnCredential, or a signer that is the identity'
+      );
+    }
     if (
       prfOutput != null &&
       !(prfOutput instanceof Uint8Array && prfOutput.length >= 32)
@@ -104,7 +111,9 @@ export class OrbitDBWebAuthnIdentityProvider {
     this.deriveSigningKeyFromPrf = deriveSigningKeyFromPrf;
     // Held only until the signing key is in the keystore; see getId().
     this.prfOutput = prfOutput;
-    this.webauthnProvider = new WebAuthnDIDProvider(webauthnCredential);
+    this.webauthnProvider = webauthnCredential
+      ? new WebAuthnDIDProvider(webauthnCredential)
+      : null;
     this.type = IDENTITY_TYPES.WEBAUTHN; // Set instance property
     this.useKeystoreDID = useKeystoreDID; // Flag to use Ed25519 DID from keystore
     this.keystore = keystore; // OrbitDB keystore instance

package/src/keystore/secret-signer.js

@@ -0,0 +1,64 @@
+/**
+ * @module SecretSigner
+ * @description
+ * An identity that is nobody's passkey: the books of an application, which
+ * every registered security key of their owner may write to.
+ *
+ * A passkey identity belongs to one authenticator — its DID is the
+ * credential's key, its signing key comes from that authenticator's PRF
+ * output — so a second security key is a second identity. OrbitDB's access
+ * controllers fix who may grant write access when a database is created, so
+ * a database rooted at one key's identity stays that key's forever. The books
+ * get an identity of their own instead, and every key acts as it:
+ * the application keeps a random secret in a vault (`createVault`), any slot
+ * opens it, and this turns the secret into the books' signing key. Other
+ * people are not given the secret; they are granted write access under their
+ * own identities, which can be revoked.
+ *
+ * The key is Ed25519, derived with HKDF-SHA-256 under `info`; its DID is the
+ * key's `did:key`. The same secret and `info` give the same key, DID and
+ * OrbitDB identity document on every device and for every slot. Use it as
+ * `createSessionKeystore({ signer })` and
+ * `OrbitDBWebAuthnIdentityProviderFunction({ signer })`.
+ */
+import { generateKeyPairFromSeed } from '@libp2p/crypto/keys';
+import { deriveSubkey } from './prf-keys.js';
+import { createEd25519DidFromPublicKey } from './ed25519-did.js';
+
+const MIN_SECRET_BYTES = 32;
+
+/**
+ * An Ed25519 signer derived from a secret, in the shape the provider's
+ * `signer` option and `createSessionKeystore` take.
+ *
+ * The private key stays in this closure: what comes back can sign, but has no
+ * field that holds the key.
+ *
+ * @param {Uint8Array} secret - At least 32 random bytes, e.g. from a vault.
+ * @param {Object} options
+ * @param {string} options.info - Domain separation, part of the identity:
+ *   another `info` is another key and another DID. Version it
+ *   (`invoice/books-identity/v1`).
+ * @returns {Promise<{ did: string, type: 'Ed25519', publicKey: Uint8Array,
+ *   sign: (data: Uint8Array) => Promise<Uint8Array> }>}
+ */
+export async function createSecretSigner(secret, { info } = {}) {
+  if (!(secret instanceof Uint8Array) || secret.length < MIN_SECRET_BYTES) {
+    throw new TypeError(
+      `createSecretSigner needs a secret of at least ${MIN_SECRET_BYTES} bytes`
+    );
+  }
+  if (typeof info !== 'string' || info.length === 0) {
+    throw new TypeError('createSecretSigner needs a non-empty info string');
+  }
+  const seed = await deriveSubkey(secret, info);
+  const key = await generateKeyPairFromSeed('Ed25519', seed);
+  seed.fill(0);
+  const publicKey = key.publicKey.raw;
+  return {
+    did: createEd25519DidFromPublicKey(publicKey),
+    type: 'Ed25519',
+    publicKey,
+    sign: async (data) => key.sign(data),
+  };
+}

package/src/standalone/index.js

@@ -47,6 +47,7 @@ export {
   slotIdFor,
 } from '../keystore/vault.js';
 export { PrfUnavailableError, VaultError } from '../errors.js';
+export { createSecretSigner } from '../keystore/secret-signer.js';
 
 export {
   createWorkerKeystoreClient,

package/src/standalone/worker/client.js

@@ -1,5 +1,9 @@
-import { varint } from 'multiformats';
-import { base58btc } from 'multiformats/bases/base58';
+// Lives in keystore/ so the main entry can build an Ed25519 did:key without
+// importing this module, whose `new Worker(new URL(…))` would make bundlers
+// pack the worker into every app.
+import { createEd25519DidFromPublicKey } from '../../keystore/ed25519-did.js';
+
+export { createEd25519DidFromPublicKey };
 
 /**
  * Convert a Uint8Array into a detached ArrayBuffer slice.
@@ -59,30 +63,6 @@ function normalizeArchiveAfterDeserialization(archive) {
   return archive;
 }
 
-/**
- * Build a did:key identifier from raw Ed25519 public key bytes.
- * @param {Uint8Array} publicKeyBytes
- * @returns {string}
- */
-export function createEd25519DidFromPublicKey(publicKeyBytes) {
-  if (!(publicKeyBytes instanceof Uint8Array) || publicKeyBytes.length !== 32) {
-    throw new Error(
-      `Invalid Ed25519 public key length: ${publicKeyBytes?.length || 0}`
-    );
-  }
-
-  const ED25519_MULTICODEC = 0xed;
-  const codecLength = varint.encodingLength(ED25519_MULTICODEC);
-  const codecBytes = new Uint8Array(codecLength);
-  varint.encodeTo(ED25519_MULTICODEC, codecBytes, 0);
-
-  const multikey = new Uint8Array(codecBytes.length + publicKeyBytes.length);
-  multikey.set(codecBytes, 0);
-  multikey.set(publicKeyBytes, codecBytes.length);
-
-  return `did:key:${base58btc.encode(multikey)}`;
-}
-
 /**
  * @returns {boolean}
  */

package/src/varsig/credential.js

@@ -4,7 +4,10 @@
 import { DIDKey } from 'iso-did';
 import { parseAttestationObject } from 'iso-passkeys';
 import { toArrayBuffer } from './utils.js';
-import { buildAuthenticatorSelection } from '../webauthn/config.js';
+import {
+  buildAuthenticatorSelection,
+  resolveAuthenticatorAttachment,
+} from '../webauthn/config.js';
 import { logWebAuthnResponse } from '../webauthn/debug-log.js';
 
 /**
@@ -62,6 +65,13 @@ function extractCredentialInfo(attestationObject) {
  * @param {string} [options.displayName] - Display name.
  * @param {string} [options.domain] - RP ID / domain.
  * @param {boolean} [options.discoverableCredentials] - Override global discoverable credential policy.
+ * @param {'platform'|'cross-platform'|'any'} [options.authenticatorType='any'] -
+ *   Which authenticators the browser offers, as for
+ *   `WebAuthnDIDProvider.createCredential`. `'any'` names none in the
+ *   request, which is what this has sent since 0.2.8.
+ * @param {'platform'|'cross-platform'} [options.authenticatorAttachment] -
+ *   The WebAuthn name for the same choice; refused if it disagrees with
+ *   `authenticatorType`.
  * @returns {Promise<Object>} Credential info including public key and DID.
  */
 async function createWebAuthnVarsigCredential(options = {}) {
@@ -69,7 +79,6 @@ async function createWebAuthnVarsigCredential(options = {}) {
     userId,
     displayName,
     domain,
-    authenticatorType = 'any',
     forceP256 = false,
   } = {
     userId: `orbitdb-user-${Date.now()}`,
@@ -78,6 +87,9 @@ async function createWebAuthnVarsigCredential(options = {}) {
     ...options,
   };
 
+  // Before any prompt: a choice this cannot honour is the caller's mistake.
+  const authenticatorAttachment = resolveAuthenticatorAttachment(options);
+
   const publicKey = {
     rp: { name: 'OrbitDB Varsig Identity', id: domain },
     user: {
@@ -94,13 +106,19 @@ async function createWebAuthnVarsigCredential(options = {}) {
           { type: 'public-key', alg: -7 },
         ],
     attestation: 'none',
-    authenticatorSelection: buildAuthenticatorSelection({
-      ...options,
-      ...(authenticatorType !== 'any' && {
-        authenticatorAttachment: authenticatorType,
-      }),
-      userVerification: 'preferred',
-    }),
+    // This named the attachment and `userVerification: 'preferred'` from March
+    // to October 2026 without effect: buildAuthenticatorSelection passed on
+    // neither, so every kind of authenticator was offered and user
+    // verification was required. Every kind stays the default;
+    // `authenticatorType` narrows it. Verification stays required: a varsig
+    // signature without the UV flag is refused — `verifyWebAuthnAssertion`
+    // insists on it, when signing and when verifying — and asking for less
+    // would let an authenticator that cannot verify the user register here
+    // and then never sign.
+    authenticatorSelection: {
+      ...buildAuthenticatorSelection(options),
+      ...(authenticatorAttachment && { authenticatorAttachment }),
+    },
     // Recovery writes the varsig metadata into the passkey's largeBlob after
     // registration — which an authenticator only allows for a credential that
     // was created asking for it. `preferred` costs nothing where the

package/src/webauthn/config.js

@@ -44,18 +44,75 @@ export function resolveWebAuthnConfig(options = {}) {
   };
 }
 
+const AUTHENTICATOR_TYPES = ['platform', 'cross-platform', 'any'];
+const AUTHENTICATOR_ATTACHMENTS = ['platform', 'cross-platform'];
+
+/**
+ * The attachment a registration asks for: `authenticatorType` —
+ * `'platform'` (the device's own authenticator), `'cross-platform'` (a
+ * security key or a phone) or `'any'` — or its WebAuthn name
+ * `authenticatorAttachment`, which has no word for "any".
+ *
+ * A value this does not know is refused rather than ignored: a typo would
+ * otherwise quietly offer every authenticator, or none the caller meant.
+ *
+ * @param {Object} [options]
+ * @param {'platform'|'cross-platform'|'any'} [options.authenticatorType]
+ * @param {'platform'|'cross-platform'} [options.authenticatorAttachment]
+ * @param {'platform'|'cross-platform'|'any'} [fallback='any'] - When neither
+ *   is given.
+ * @returns {'platform'|'cross-platform'|undefined} `undefined` for any
+ *   authenticator: the request then names none.
+ */
+export function resolveAuthenticatorAttachment(
+  { authenticatorType, authenticatorAttachment } = {},
+  fallback = 'any'
+) {
+  if (
+    authenticatorType != null &&
+    !AUTHENTICATOR_TYPES.includes(authenticatorType)
+  ) {
+    throw new TypeError(
+      `authenticatorType must be one of ${AUTHENTICATOR_TYPES.join(', ')}, not '${authenticatorType}'`
+    );
+  }
+  if (
+    authenticatorAttachment != null &&
+    !AUTHENTICATOR_ATTACHMENTS.includes(authenticatorAttachment)
+  ) {
+    throw new TypeError(
+      `authenticatorAttachment must be one of ${AUTHENTICATOR_ATTACHMENTS.join(', ')}, not '${authenticatorAttachment}'`
+    );
+  }
+  if (
+    authenticatorType != null &&
+    authenticatorAttachment != null &&
+    authenticatorType !== authenticatorAttachment
+  ) {
+    throw new TypeError(
+      `authenticatorType '${authenticatorType}' and authenticatorAttachment '${authenticatorAttachment}' disagree; give one`
+    );
+  }
+  const choice = authenticatorType ?? authenticatorAttachment ?? fallback;
+  return choice === 'any' ? undefined : choice;
+}
+
+/**
+ * `authenticatorSelection` for a registration. Only the discoverable-credential
+ * policy comes from `options` and `configureWebAuthn`, and user verification is
+ * always required; an `authenticatorAttachment` or `userVerification` in
+ * `options` is not read. This used to destructure both as if it read them,
+ * which is how two registrations came to name values that never reached the
+ * browser. A registration that wants an attachment adds it itself — see
+ * `resolveAuthenticatorAttachment`.
+ */
 export function buildAuthenticatorSelection(options = {}) {
-  const {
-    discoverableCredentials,
-    authenticatorAttachment,
-    userVerification = 'required',
-  } = resolveWebAuthnConfig(options);
+  const { discoverableCredentials } = resolveWebAuthnConfig(options);
 
   return {
-    ...(authenticatorAttachment ? { authenticatorAttachment } : {}),
     requireResidentKey: discoverableCredentials,
     residentKey: discoverableCredentials ? 'required' : 'discouraged',
-    userVerification,
+    userVerification: 'required',
   };
 }
 

package/src/webauthn/provider.js

@@ -24,6 +24,7 @@ import {
 } from '../errors.js';
 import {
   buildAuthenticatorSelection,
+  resolveAuthenticatorAttachment,
   buildCredentialRequestOptions,
 } from './config.js';
 import { logWebAuthnResponse } from './debug-log.js';
@@ -115,6 +116,13 @@ export class WebAuthnDIDProvider {
    * @param {boolean} options.encryptKeystore - Enable keystore encryption
    * @param {string} options.keystoreEncryptionMethod - 'prf' (default), 'hmac-secret', or 'largeBlob'
    * @param {boolean} [options.discoverableCredentials] - Override global discoverable credential policy
+   * @param {'platform'|'cross-platform'|'any'} [options.authenticatorType='any'] -
+   *   Which authenticators the browser offers: the device's own, a security
+   *   key or phone, or every kind. `'any'` names none in the request, which is
+   *   what this has sent since 0.2.8.
+   * @param {'platform'|'cross-platform'} [options.authenticatorAttachment] -
+   *   The WebAuthn name for the same choice; refused if it disagrees with
+   *   `authenticatorType`.
    * @returns {Promise<Object>} Credential info with public key and metadata.
    */
   static async createCredential(options = {}) {
@@ -131,10 +139,14 @@ export class WebAuthnDIDProvider {
       ...options,
     };
 
+    // Before any prompt: a choice this cannot honour is the caller's mistake.
+    const authenticatorAttachment = resolveAuthenticatorAttachment(options);
+
     webauthnLog('createCredential() called with options: %o', {
       userId,
       displayName,
       domain,
+      authenticatorAttachment: authenticatorAttachment ?? 'any',
     });
 
     if (!this.isSupported()) {
@@ -177,11 +189,14 @@ export class WebAuthnDIDProvider {
           { alg: -7, type: 'public-key' }, // ES256 (P-256 curve)
           { alg: -257, type: 'public-key' }, // RS256 fallback
         ],
-        authenticatorSelection: buildAuthenticatorSelection({
-          ...options,
-          authenticatorAttachment: 'platform',
-          userVerification: 'required',
-        }),
+        // This named 'platform' from March to October 2026 without effect:
+        // buildAuthenticatorSelection never passed it on, so every kind of
+        // authenticator was offered, security keys included. That stays the
+        // default; `authenticatorType` narrows it.
+        authenticatorSelection: {
+          ...buildAuthenticatorSelection(options),
+          ...(authenticatorAttachment && { authenticatorAttachment }),
+        },
         timeout: 60000,
         attestation: 'none', // Don't need attestation for DID creation
       },

package/types/index.d.ts

@@ -131,8 +131,14 @@ export interface CreateCredentialOptions {
   encryptKeystore?: boolean;
   keystoreEncryptionMethod?: KeystoreEncryptionMethod;
   discoverableCredentials?: boolean;
+  /**
+   * Which authenticators the browser offers: the device's own, a security key
+   * or phone, or every kind. Default `'any'`: the request names none.
+   */
   authenticatorType?: AuthenticatorType;
+  /** The WebAuthn name for `authenticatorType`; the two must not disagree. */
   authenticatorAttachment?: AuthenticatorAttachment;
+  /** Not read: a registration always requires user verification. */
   userVerification?: UserVerificationRequirement;
   [key: string]: unknown;
 }
@@ -140,6 +146,7 @@ export interface CreateCredentialOptions {
 export interface WebAuthnConfig {
   discoverableCredentials?: boolean;
   userVerification?: UserVerificationRequirement;
+  /** Not read by `configureWebAuthn`; give `createCredential` an `authenticatorType`. */
   authenticatorAttachment?: AuthenticatorAttachment;
   residentKey?: ResidentKeyRequirement;
   requireResidentKey?: boolean;
@@ -612,6 +619,22 @@ export function replacePayload(
 /** The slot id an authenticator is filed under. */
 export function slotIdFor(rawCredentialId: Uint8Array): Promise<string>;
 
+/**
+ * An Ed25519 signer derived from a secret — an identity that is nobody's
+ * passkey, e.g. the books every key of their owner writes as. Same secret and
+ * `info`, same DID everywhere. Use with `createSessionKeystore({ signer })`
+ * and the provider's `signer` option.
+ */
+export function createSecretSigner(
+  secret: Uint8Array,
+  options: { info: string }
+): Promise<{
+  did: string;
+  type: 'Ed25519';
+  publicKey: Uint8Array;
+  sign(data: Uint8Array): Promise<Uint8Array>;
+}>;
+
 export type VaultErrorCode =
   | 'VAULT_MALFORMED'
   | 'VAULT_NO_SLOT'

package/types/keystore.d.ts

@@ -40,6 +40,7 @@ export interface ExtensionSupport {
 }
 
 export interface OrbitDBWebAuthnIdentityProviderOptions {
+  /** Required unless `signer` is given. */
   webauthnCredential?: Record<string, unknown>;
   keystore?: unknown;
   usePersistentKey?: boolean;
@@ -95,6 +96,11 @@ export function createSessionKeystore(options?: {
   signer?: ExternalSigner;
 }): Promise<unknown>;
 export function isSessionKeystore(keystore: unknown): boolean;
+/** An Ed25519 signer derived from a secret (HKDF under `info`): an identity that is nobody's passkey. */
+export function createSecretSigner(
+  secret: Uint8Array,
+  options: { info: string }
+): Promise<ExternalSigner>;
 export function assertSigner(signer: unknown): void;
 
 /** The authenticator returned no PRF output; nothing stands in for it. */

package/types/standalone.d.ts

@@ -26,7 +26,15 @@ export interface WebAuthnVarsigCredential {
 export interface WebAuthnSignerOptions {
   userId?: string;
   displayName?: string;
+  /**
+   * Which authenticators the browser offers: the device's own, a security key
+   * or phone, or every kind. Default `'any'`: the request names none.
+   */
   authenticatorType?: AuthenticatorType;
+  /** The WebAuthn name for `authenticatorType`; the two must not disagree. */
+  authenticatorAttachment?: AuthenticatorAttachment;
+  /** Not read: a registration always requires user verification. */
+  userVerification?: UserVerificationRequirement;
   forceP256?: boolean;
   domain?: string;
   [key: string]: unknown;
@@ -381,6 +389,22 @@ export function replacePayload(
 /** The slot id an authenticator is filed under. */
 export function slotIdFor(rawCredentialId: Uint8Array): Promise<string>;
 
+/**
+ * An Ed25519 signer derived from a secret — an identity that is nobody's
+ * passkey, e.g. the books every key of their owner writes as. Same secret and
+ * `info`, same DID everywhere. Use with `createSessionKeystore({ signer })`
+ * and the provider's `signer` option.
+ */
+export function createSecretSigner(
+  secret: Uint8Array,
+  options: { info: string }
+): Promise<{
+  did: string;
+  type: 'Ed25519';
+  publicKey: Uint8Array;
+  sign(data: Uint8Array): Promise<Uint8Array>;
+}>;
+
 export type VaultErrorCode =
   | 'VAULT_MALFORMED'
   | 'VAULT_NO_SLOT'