@interop/wallet-core 0.5.0 → 0.7.0

package/dist/keyring/fetch.js

@@ -0,0 +1,35 @@
+import { deriveUnlockIdentity, KEYRING_KDF } from './kdf.js';
+import { getUnlockKeyring } from './unlockSpace.js';
+import { unwrapKeyringRecord } from './record.js';
+/**
+ * Fetches and unwraps the keyring record an unlock secret addresses, or
+ * resolves `null` when no record exists there (an unknown secret). The derived
+ * unlock Space id is returned alongside the contents -- it is already computed,
+ * and callers key their local state on it.
+ *
+ * @param options {object}
+ * @param options.secret {string | Uint8Array}   the unlock secret
+ * @param [options.kdf] {UnlockKdf}   the unlock method's parameter set
+ * @param options.storageServerUrl {string}   the WAS server origin
+ * @returns {Promise<(KeyringRecordContents & { unlockSpaceId: string }) | null>}
+ */
+export async function fetchKeyringRecord({ secret, kdf = KEYRING_KDF, storageServerUrl }) {
+    const unlock = await deriveUnlockIdentity({ secret, kdf });
+    const record = await getUnlockKeyring({
+        storageServerUrl,
+        zcapClient: unlock.zcapClient,
+        spaceId: unlock.spaceId
+    });
+    if (record === null) {
+        return null;
+    }
+    const contents = await unwrapKeyringRecord({
+        record,
+        // `id` is always set on the unlock KAK (a controller was supplied at
+        // derivation), so it satisfies IKeyAgreementKey's required `id`.
+        keyAgreementKey: unlock.keyAgreementKey,
+        keyResolver: unlock.keyResolver
+    });
+    return { ...contents, unlockSpaceId: unlock.spaceId };
+}
+//# sourceMappingURL=fetch.js.map

package/dist/keyring/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../../src/keyring/fetch.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAGjD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,EACvC,MAAM,EACN,GAAG,GAAG,WAAW,EACjB,gBAAgB,EAKjB;IACC,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;IAC1D,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC;QACpC,gBAAgB;QAChB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAC,CAAA;IACF,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO,IAAI,CAAA;IACb,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC;QACzC,MAAM;QACN,qEAAqE;QACrE,iEAAiE;QACjE,eAAe,EAAE,MAAM,CAAC,eAAmC;QAC3D,WAAW,EAAE,MAAM,CAAC,WAAW;KAChC,CAAC,CAAA;IACF,OAAO,EAAE,GAAG,QAAQ,EAAE,aAAa,EAAE,MAAM,CAAC,OAAO,EAAE,CAAA;AACvD,CAAC"}

package/dist/keyring/index.d.ts

@@ -0,0 +1,30 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `@interop/wallet-core/keyring` subpath: the unlock layer -- how an
+ * unlock secret (a passphrase, a passkey PRF output) locates an account
+ * without authorizing anything against it.
+ *
+ * - `deriveUnlockIdentity` / `KEYRING_KDF` / `unlockSpaceIdFor` -- the
+ *   wire-level unlock derivation (implemented over `@noble/hashes`, so it runs
+ *   unchanged where WebCrypto's `deriveBits` is unavailable) and the unlock
+ *   Space addressing convention.
+ * - `wrapKeyringRecord` / `unwrapKeyringRecord` -- the `{ version, wrapped }`
+ *   account-pointer record codec.
+ * - `ensureUnlockSpace` / `getUnlockKeyring` / `putUnlockKeyring` /
+ *   `deleteUnlockSpace` / `deleteUnlockSpaceWithCapability` -- the unlock
+ *   Space's lifecycle and its one resource.
+ * - `fetchKeyringRecord` -- the composed lookup (derive, read, unwrap); an
+ *   app's caching, pinning, and client-key persistence wrap around it.
+ *
+ * Kept out of the root export: this subpath pulls the webkms-client / ezcap /
+ * was-client dependency graph (the same isolation pattern as `./identity`).
+ */
+export { deriveUnlockIdentity, KEYRING_KDF, UNLOCK_HANDLE, UNLOCK_KEY_NAME, unlockSpaceIdFor } from './kdf.js';
+export type { UnlockIdentity, UnlockKdf } from './kdf.js';
+export { KEYRING_RECORD_VERSION, parseRecordPointer, unwrapKeyringRecord, wrapKeyringRecord } from './record.js';
+export type { AccountPointer, KeyringRecordContents } from './record.js';
+export { deleteUnlockSpace, deleteUnlockSpaceWithCapability, ensureUnlockSpace, getUnlockKeyring, putUnlockKeyring, UNLOCK_SPACE_NAME } from './unlockSpace.js';
+export { fetchKeyringRecord } from './fetch.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/keyring/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/keyring/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,eAAe,EACf,gBAAgB,EACjB,MAAM,UAAU,CAAA;AACjB,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAEzD,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAExE,OAAO,EACL,iBAAiB,EACjB,+BAA+B,EAC/B,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA"}

package/dist/keyring/index.js

@@ -0,0 +1,28 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `@interop/wallet-core/keyring` subpath: the unlock layer -- how an
+ * unlock secret (a passphrase, a passkey PRF output) locates an account
+ * without authorizing anything against it.
+ *
+ * - `deriveUnlockIdentity` / `KEYRING_KDF` / `unlockSpaceIdFor` -- the
+ *   wire-level unlock derivation (implemented over `@noble/hashes`, so it runs
+ *   unchanged where WebCrypto's `deriveBits` is unavailable) and the unlock
+ *   Space addressing convention.
+ * - `wrapKeyringRecord` / `unwrapKeyringRecord` -- the `{ version, wrapped }`
+ *   account-pointer record codec.
+ * - `ensureUnlockSpace` / `getUnlockKeyring` / `putUnlockKeyring` /
+ *   `deleteUnlockSpace` / `deleteUnlockSpaceWithCapability` -- the unlock
+ *   Space's lifecycle and its one resource.
+ * - `fetchKeyringRecord` -- the composed lookup (derive, read, unwrap); an
+ *   app's caching, pinning, and client-key persistence wrap around it.
+ *
+ * Kept out of the root export: this subpath pulls the webkms-client / ezcap /
+ * was-client dependency graph (the same isolation pattern as `./identity`).
+ */
+export { deriveUnlockIdentity, KEYRING_KDF, UNLOCK_HANDLE, UNLOCK_KEY_NAME, unlockSpaceIdFor } from './kdf.js';
+export { KEYRING_RECORD_VERSION, parseRecordPointer, unwrapKeyringRecord, wrapKeyringRecord } from './record.js';
+export { deleteUnlockSpace, deleteUnlockSpaceWithCapability, ensureUnlockSpace, getUnlockKeyring, putUnlockKeyring, UNLOCK_SPACE_NAME } from './unlockSpace.js';
+export { fetchKeyringRecord } from './fetch.js';
+//# sourceMappingURL=index.js.map

package/dist/keyring/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/keyring/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,eAAe,EACf,gBAAgB,EACjB,MAAM,UAAU,CAAA;AAGjB,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,aAAa,CAAA;AAGpB,OAAO,EACL,iBAAiB,EACjB,+BAA+B,EAC/B,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA"}

package/dist/keyring/kdf.d.ts

@@ -0,0 +1,102 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The unlock derivation: an unlock secret (a passphrase, or a passkey PRF
+ * output) to the unlock identity that locates an account's keyring record and
+ * wraps/unwraps it. Nothing about the account is derivable from the secret --
+ * the identity's only jobs are addressing the minimal unlock Space and holding
+ * the key-agreement key the keyring record is encrypted to.
+ *
+ * The derivation is wire-level: two wallet apps must produce byte-identical
+ * output for the same secret and parameter set, or the same passphrase would
+ * address two different unlock Spaces. It is therefore implemented over
+ * `@noble/hashes` rather than WebCrypto's `crypto.subtle.deriveBits`, which
+ * React Native does not provide; PBKDF2 and HKDF are both fully specified
+ * (RFC 8018 / RFC 5869), so the two implementations agree bit for bit.
+ */
+import { CapabilityAgent } from '@interop/webkms-client';
+import { ZcapClient } from '@interop/ezcap';
+import { X25519KeyAgreementKey2020 } from '@interop/x25519-key-agreement-key';
+import type { IKeyResolver } from '@interop/data-integrity-core';
+/**
+ * The load-bearing `CapabilityAgent` derivation names for an unlock identity
+ * (the counterpart of the data identity's bootstrap names): every unlock
+ * derivation runs through these exact strings, so they can never change
+ * without stranding existing accounts.
+ */
+export declare const UNLOCK_HANDLE = "unlock";
+export declare const UNLOCK_KEY_NAME = "unlock-key";
+/**
+ * Unlock-derivation parameters, one variant per KDF family: PBKDF2 stretches
+ * a low-entropy passphrase; HKDF expands already-uniform key material (e.g. a
+ * passkey PRF output). Each unlock method pins its own parameter set -- and
+ * its own salt, so two methods can never derive the same unlock identity.
+ * The `version` records which parameter set produced a derivation; the
+ * keyring record's own `version` is stamped separately.
+ */
+export type UnlockKdf = {
+    version: number;
+    algorithm: 'PBKDF2';
+    iterations: number;
+    hash: string;
+    salt: string;
+} | {
+    version: number;
+    algorithm: 'HKDF';
+    hash: string;
+    salt: string;
+    info: string;
+};
+/**
+ * PBKDF2 parameters for the passphrase unlock derivation
+ * (`unlockSeed = PBKDF2(passphrase)`). Version 1 pins exactly these
+ * parameters; the keyring record's `version` field records which set produced
+ * it, so changing any of them (iterations, hash, salt) requires minting a new
+ * record version rather than silently breaking existing unlock derivations.
+ * The salt is a fixed app-wide constant -- login stays passphrase-only, with
+ * no email (or other) input mixed into the derivation. Every unlock method's
+ * KDF carries a distinct salt, so two methods can never derive the same
+ * unlock Space.
+ */
+export declare const KEYRING_KDF: UnlockKdf;
+/**
+ * Derives the full unlock identity from an unlock secret: the unlock
+ * CapabilityAgent, a ZcapClient that can both invoke and delegate (the
+ * unlock agent delegates a management zcap on its own Space to the account
+ * controller at bind time), the unlock KAK + resolver for wrap/unwrap, and the
+ * unlock Space id. Performs no I/O -- the derivation seam for tests and future
+ * unlock methods.
+ *
+ * @param options {object}
+ * @param options.secret {string | Uint8Array}
+ * @param options.kdf {UnlockKdf}
+ * @returns {Promise<object>}
+ */
+export declare function deriveUnlockIdentity({ secret, kdf }: {
+    secret: string | Uint8Array;
+    kdf: UnlockKdf;
+}): Promise<{
+    agent: CapabilityAgent;
+    zcapClient: ZcapClient;
+    keyAgreementKey: X25519KeyAgreementKey2020;
+    keyResolver: IKeyResolver;
+    spaceId: string;
+}>;
+/**
+ * The unlock Space id an unlock identity addresses:
+ * `base64url(SHA-256(did))`, unpadded -- a discovery convention, not an
+ * authorization one (holding the id grants nothing).
+ *
+ * @param options {object}
+ * @param options.did {string}   the unlock identity's did:key
+ * @returns {string}
+ */
+export declare function unlockSpaceIdFor({ did }: {
+    did: string;
+}): string;
+/**
+ * The derived unlock identity, as `deriveUnlockIdentity` returns it.
+ */
+export type UnlockIdentity = Awaited<ReturnType<typeof deriveUnlockIdentity>>;
+//# sourceMappingURL=kdf.d.ts.map

package/dist/keyring/kdf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kdf.d.ts","sourceRoot":"","sources":["../../src/keyring/kdf.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAExD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAA;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAOhE;;;;;GAKG;AACH,eAAO,MAAM,aAAa,WAAW,CAAA;AACrC,eAAO,MAAM,eAAe,eAAe,CAAA;AAQ3C;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GACjB;IACE,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,QAAQ,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACb,GACD;IACE,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAEL;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,EAAE,SAMzB,CAAA;AA2DD;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CAAC,EACzC,MAAM,EACN,GAAG,EACJ,EAAE;IACD,MAAM,EAAE,MAAM,GAAG,UAAU,CAAA;IAC3B,GAAG,EAAE,SAAS,CAAA;CACf;;;;;;GAyBA;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,GAAG,EAAE,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAEjE;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAA"}

package/dist/keyring/kdf.js

@@ -0,0 +1,148 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The unlock derivation: an unlock secret (a passphrase, or a passkey PRF
+ * output) to the unlock identity that locates an account's keyring record and
+ * wraps/unwraps it. Nothing about the account is derivable from the secret --
+ * the identity's only jobs are addressing the minimal unlock Space and holding
+ * the key-agreement key the keyring record is encrypted to.
+ *
+ * The derivation is wire-level: two wallet apps must produce byte-identical
+ * output for the same secret and parameter set, or the same passphrase would
+ * address two different unlock Spaces. It is therefore implemented over
+ * `@noble/hashes` rather than WebCrypto's `crypto.subtle.deriveBits`, which
+ * React Native does not provide; PBKDF2 and HKDF are both fully specified
+ * (RFC 8018 / RFC 5869), so the two implementations agree bit for bit.
+ */
+import { CapabilityAgent } from '@interop/webkms-client';
+import { Ed25519Signature2020 } from '@interop/ed25519-signature';
+import { ZcapClient } from '@interop/ezcap';
+import { X25519KeyAgreementKey2020 } from '@interop/x25519-key-agreement-key';
+import { base64urlnopad } from '@scure/base';
+import { hkdf } from '@noble/hashes/hkdf.js';
+import { pbkdf2Async } from '@noble/hashes/pbkdf2.js';
+import { sha256, sha512 } from '@noble/hashes/sha2.js';
+import { singleKeyResolver } from '../identity/keyResolver.js';
+/**
+ * The load-bearing `CapabilityAgent` derivation names for an unlock identity
+ * (the counterpart of the data identity's bootstrap names): every unlock
+ * derivation runs through these exact strings, so they can never change
+ * without stranding existing accounts.
+ */
+export const UNLOCK_HANDLE = 'unlock';
+export const UNLOCK_KEY_NAME = 'unlock-key';
+/**
+ * The number of bytes an unlock derivation produces (a 32-byte seed, which is
+ * what `CapabilityAgent.fromSeed` takes).
+ */
+const UNLOCK_SEED_BYTES = 32;
+/**
+ * PBKDF2 parameters for the passphrase unlock derivation
+ * (`unlockSeed = PBKDF2(passphrase)`). Version 1 pins exactly these
+ * parameters; the keyring record's `version` field records which set produced
+ * it, so changing any of them (iterations, hash, salt) requires minting a new
+ * record version rather than silently breaking existing unlock derivations.
+ * The salt is a fixed app-wide constant -- login stays passphrase-only, with
+ * no email (or other) input mixed into the derivation. Every unlock method's
+ * KDF carries a distinct salt, so two methods can never derive the same
+ * unlock Space.
+ */
+export const KEYRING_KDF = {
+    version: 1,
+    algorithm: 'PBKDF2',
+    iterations: 600_000,
+    hash: 'SHA-256',
+    salt: 'freewallet/keyring/unlock/v1'
+};
+/**
+ * The noble hash constructor a WebCrypto hash name selects, so the derivation
+ * matches `crypto.subtle.deriveBits` for the same parameters.
+ *
+ * @param hash {string}   a WebCrypto digest name (`SHA-256`, `SHA-512`)
+ * @returns {object}   the noble hash
+ */
+function nobleHash(hash) {
+    if (hash === 'SHA-256') {
+        return sha256;
+    }
+    if (hash === 'SHA-512') {
+        return sha512;
+    }
+    throw new Error(`Unsupported unlock KDF hash "${hash}".`);
+}
+/**
+ * Derives the 32-byte unlock seed from an unlock secret, branching on the KDF
+ * family: PBKDF2 stretches a passphrase, HKDF expands already-uniform key
+ * material such as a passkey PRF output.
+ *
+ * @param options {object}
+ * @param options.secret {string | Uint8Array}
+ * @param options.kdf {UnlockKdf}
+ * @returns {Promise<Uint8Array>}
+ */
+async function deriveUnlockSeed({ secret, kdf }) {
+    // Copy a bytes secret into a fresh buffer: a caller's slice may be a view
+    // into a larger buffer, and the codecs below read the whole view.
+    const secretBytes = typeof secret === 'string'
+        ? new TextEncoder().encode(secret)
+        : new Uint8Array(secret);
+    const hash = nobleHash(kdf.hash);
+    const salt = new TextEncoder().encode(kdf.salt);
+    if (kdf.algorithm === 'PBKDF2') {
+        return pbkdf2Async(hash, secretBytes, salt, {
+            c: kdf.iterations,
+            dkLen: UNLOCK_SEED_BYTES
+        });
+    }
+    return hkdf(hash, secretBytes, salt, new TextEncoder().encode(kdf.info), UNLOCK_SEED_BYTES);
+}
+/**
+ * Derives the full unlock identity from an unlock secret: the unlock
+ * CapabilityAgent, a ZcapClient that can both invoke and delegate (the
+ * unlock agent delegates a management zcap on its own Space to the account
+ * controller at bind time), the unlock KAK + resolver for wrap/unwrap, and the
+ * unlock Space id. Performs no I/O -- the derivation seam for tests and future
+ * unlock methods.
+ *
+ * @param options {object}
+ * @param options.secret {string | Uint8Array}
+ * @param options.kdf {UnlockKdf}
+ * @returns {Promise<object>}
+ */
+export async function deriveUnlockIdentity({ secret, kdf }) {
+    const seed = await deriveUnlockSeed({ secret, kdf });
+    const agent = await CapabilityAgent.fromSeed({
+        seed,
+        handle: UNLOCK_HANDLE,
+        keyName: UNLOCK_KEY_NAME
+    });
+    const signer = agent.getSigner();
+    const zcapClient = new ZcapClient({
+        SuiteClass: Ed25519Signature2020,
+        invocationSigner: signer,
+        delegationSigner: signer
+    });
+    // The unlock KAK is the Montgomery form of the unlock signing key -- the same
+    // derivation the client side uses (`agentsFromSeed`), so a returning user
+    // reconstitutes the exact key that wrapped the keyring record.
+    const keyAgreementKey = X25519KeyAgreementKey2020.fromEd25519VerificationKey2020({
+        keyPair: agent.getVerificationKeyPair()
+    });
+    const keyResolver = singleKeyResolver({ keyAgreementKey });
+    const spaceId = unlockSpaceIdFor({ did: agent.id });
+    return { agent, zcapClient, keyAgreementKey, keyResolver, spaceId };
+}
+/**
+ * The unlock Space id an unlock identity addresses:
+ * `base64url(SHA-256(did))`, unpadded -- a discovery convention, not an
+ * authorization one (holding the id grants nothing).
+ *
+ * @param options {object}
+ * @param options.did {string}   the unlock identity's did:key
+ * @returns {string}
+ */
+export function unlockSpaceIdFor({ did }) {
+    return base64urlnopad.encode(sha256(new TextEncoder().encode(did)));
+}
+//# sourceMappingURL=kdf.js.map

package/dist/keyring/kdf.js.map

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

package/dist/keyring/record.d.ts

@@ -0,0 +1,98 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The keyring record codec: the `{ version, wrapped }` envelope stored as the
+ * one resource of an account's unlock Space. Its plaintext carries the account
+ * controller, the email captured at bind time, and the account pointer -- and
+ * deliberately no key material of any kind, so the record locates an account
+ * without authorizing anything against it.
+ *
+ * The wrap is an EDV document envelope under the unlock key-agreement key,
+ * bound to the `keyring` cipher context, so a keyring envelope can never be
+ * mistaken for (or swapped with) any other wrapped record.
+ */
+import type { IKeyAgreementKey, IKeyResolver } from '@interop/data-integrity-core';
+/**
+ * The version stamped on the stored `{ version, wrapped }` keyring envelope.
+ * Version 2 is the account-pointer record; version-1 records (which carried a
+ * wrapped account-wide data seed) are refused as unusable -- such accounts are
+ * re-provisioned, not migrated.
+ */
+export declare const KEYRING_RECORD_VERSION = 2;
+/**
+ * The account pointer a keyring record carries in place of the retired data
+ * seed: where the account lives (`spaceId` + `host`, the WAS server origin)
+ * and, once provisioning has published it, the account's stable did:webvh id.
+ * Discovery only -- holding the pointer authorizes nothing.
+ */
+export interface AccountPointer {
+    did?: string;
+    spaceId: string;
+    host: string;
+}
+/**
+ * The unwrapped contents of a keyring record: the account controller (the
+ * first enrolled client's did:key today), the account email captured at bind
+ * time (when one was given -- carried so any unlock method recovers it; a
+ * passkey login has no login form to ask on), and the account pointer (absent
+ * only on no-WAS deployments, where there is no Space to point at).
+ */
+export interface KeyringRecordContents {
+    controller: string;
+    email?: string;
+    pointer?: AccountPointer;
+}
+/**
+ * Wraps the account-pointer contents into a keyring record: the controller,
+ * email, and pointer (+ timestamp) encrypted under the unlock KAK via the EDV
+ * cipher. Deliberately carries no key material of any kind.
+ *
+ * @param options {object}
+ * @param options.controller {string}   the account did:key
+ * @param [options.email] {string}   the account email, when known
+ * @param [options.pointer] {AccountPointer}   the account pointer (absent on
+ *   no-WAS deployments)
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the unlock KAK
+ * @param options.keyResolver {IKeyResolver}
+ * @returns {Promise<{ version: number, wrapped: unknown }>}
+ */
+export declare function wrapKeyringRecord({ controller, email, pointer, keyAgreementKey, keyResolver }: {
+    controller: string;
+    email?: string;
+    pointer?: AccountPointer;
+    keyAgreementKey: IKeyAgreementKey;
+    keyResolver: IKeyResolver;
+}): Promise<{
+    version: number;
+    wrapped: unknown;
+}>;
+/**
+ * Unwraps and validates a keyring record. Rejects a record whose `version` is
+ * not the current one (version-1 records carried the retired wrapped data
+ * seed and are refused -- accounts are re-provisioned, not migrated), and
+ * sanity-checks the decrypted plaintext (non-empty controller, well-formed
+ * pointer when present).
+ *
+ * @param options {object}
+ * @param options.record {unknown}
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the unlock KAK
+ * @param options.keyResolver {IKeyResolver}
+ * @returns {Promise<KeyringRecordContents>}
+ */
+export declare function unwrapKeyringRecord({ record, keyAgreementKey, keyResolver }: {
+    record: unknown;
+    keyAgreementKey: IKeyAgreementKey;
+    keyResolver: IKeyResolver;
+}): Promise<KeyringRecordContents>;
+/**
+ * Parses and validates the optional `pointer` member of a keyring record
+ * plaintext. An absent member is a no-WAS record (returns undefined); a
+ * present-but-malformed one throws -- a record that claims a pointer but
+ * cannot state where the account lives is unusable.
+ *
+ * @param value {unknown}   the record's `pointer` member
+ * @returns {AccountPointer | undefined}
+ */
+export declare function parseRecordPointer(value: unknown): AccountPointer | undefined;
+//# sourceMappingURL=record.d.ts.map

package/dist/keyring/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/keyring/record.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACb,MAAM,8BAA8B,CAAA;AAIrC;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,cAAc,CAAA;CACzB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CAAC,EACtC,UAAU,EACV,KAAK,EACL,OAAO,EACP,eAAe,EACf,WAAW,EACZ,EAAE;IACD,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,cAAc,CAAA;IACxB,eAAe,EAAE,gBAAgB,CAAA;IACjC,WAAW,EAAE,YAAY,CAAA;CAC1B,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAuBjD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CAAC,EACxC,MAAM,EACN,eAAe,EACf,WAAW,EACZ,EAAE;IACD,MAAM,EAAE,OAAO,CAAA;IACf,eAAe,EAAE,gBAAgB,CAAA;IACjC,WAAW,EAAE,YAAY,CAAA;CAC1B,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAsCjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAsB7E"}

package/dist/keyring/record.js

@@ -0,0 +1,119 @@
+import { createEdvDocCipher } from '@interop/was-client/edv';
+import { KEYRING_COLLECTION } from '../space/collections.js';
+/**
+ * The version stamped on the stored `{ version, wrapped }` keyring envelope.
+ * Version 2 is the account-pointer record; version-1 records (which carried a
+ * wrapped account-wide data seed) are refused as unusable -- such accounts are
+ * re-provisioned, not migrated.
+ */
+export const KEYRING_RECORD_VERSION = 2;
+/**
+ * Wraps the account-pointer contents into a keyring record: the controller,
+ * email, and pointer (+ timestamp) encrypted under the unlock KAK via the EDV
+ * cipher. Deliberately carries no key material of any kind.
+ *
+ * @param options {object}
+ * @param options.controller {string}   the account did:key
+ * @param [options.email] {string}   the account email, when known
+ * @param [options.pointer] {AccountPointer}   the account pointer (absent on
+ *   no-WAS deployments)
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the unlock KAK
+ * @param options.keyResolver {IKeyResolver}
+ * @returns {Promise<{ version: number, wrapped: unknown }>}
+ */
+export async function wrapKeyringRecord({ controller, email, pointer, keyAgreementKey, keyResolver }) {
+    const cipher = await createEdvDocCipher({
+        keyAgreementKey,
+        keyResolver,
+        collectionId: KEYRING_COLLECTION.id
+    });
+    const { envelope } = await cipher.encrypt({
+        data: {
+            controller,
+            ...(email ? { email } : {}),
+            ...(pointer
+                ? {
+                    pointer: {
+                        ...(pointer.did ? { did: pointer.did } : {}),
+                        spaceId: pointer.spaceId,
+                        host: pointer.host
+                    }
+                }
+                : {}),
+            createdAt: new Date().toISOString()
+        }
+    });
+    return { version: KEYRING_RECORD_VERSION, wrapped: envelope };
+}
+/**
+ * Unwraps and validates a keyring record. Rejects a record whose `version` is
+ * not the current one (version-1 records carried the retired wrapped data
+ * seed and are refused -- accounts are re-provisioned, not migrated), and
+ * sanity-checks the decrypted plaintext (non-empty controller, well-formed
+ * pointer when present).
+ *
+ * @param options {object}
+ * @param options.record {unknown}
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the unlock KAK
+ * @param options.keyResolver {IKeyResolver}
+ * @returns {Promise<KeyringRecordContents>}
+ */
+export async function unwrapKeyringRecord({ record, keyAgreementKey, keyResolver }) {
+    if (record === null || typeof record !== 'object') {
+        throw new Error('Malformed keyring record.');
+    }
+    const { version, wrapped } = record;
+    if (version !== KEYRING_RECORD_VERSION) {
+        throw new Error(`Unsupported keyring record version "${String(version)}".`);
+    }
+    const cipher = await createEdvDocCipher({
+        keyAgreementKey,
+        keyResolver,
+        collectionId: KEYRING_COLLECTION.id
+    });
+    const plaintext = (await cipher.decrypt({
+        envelope: wrapped
+    }));
+    if (typeof plaintext.controller !== 'string' || !plaintext.controller) {
+        throw new Error('Keyring record is missing a controller.');
+    }
+    const pointer = parseRecordPointer(plaintext.pointer);
+    return {
+        controller: plaintext.controller,
+        // A record bound without an email simply has no email; anything
+        // non-string is ignored, not fatal.
+        ...(typeof plaintext.email === 'string' && plaintext.email
+            ? { email: plaintext.email }
+            : {}),
+        ...(pointer ? { pointer } : {})
+    };
+}
+/**
+ * Parses and validates the optional `pointer` member of a keyring record
+ * plaintext. An absent member is a no-WAS record (returns undefined); a
+ * present-but-malformed one throws -- a record that claims a pointer but
+ * cannot state where the account lives is unusable.
+ *
+ * @param value {unknown}   the record's `pointer` member
+ * @returns {AccountPointer | undefined}
+ */
+export function parseRecordPointer(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null || typeof value !== 'object') {
+        throw new Error('Keyring record has a malformed account pointer.');
+    }
+    const { did, spaceId, host } = value;
+    if (typeof spaceId !== 'string' || !spaceId) {
+        throw new Error('Keyring record account pointer is missing its spaceId.');
+    }
+    if (typeof host !== 'string' || !host) {
+        throw new Error('Keyring record account pointer is missing its host.');
+    }
+    if (did !== undefined && (typeof did !== 'string' || !did)) {
+        throw new Error('Keyring record account pointer has a malformed did.');
+    }
+    return { ...(did ? { did } : {}), spaceId, host };
+}
+//# sourceMappingURL=record.js.map

package/dist/keyring/record.js.map

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