@novasamatech/host-api-wrapper 0.9.2 → 0.9.3

package/README.md

@@ -262,32 +262,62 @@ if (accountResult.isOk()) {
   console.log('Public key:', account.publicKey);
 }
 
-// Ring VRF: a contextual alias and a proof are addressed by a product-scoped
-// `context` (`[productId, suffix]`) and a `ring` location on a chain (RFC 0004).
-// The suffix is the same selector as an account's derivation index and expands
-// to the same 32-byte value (RFC 0022).
+// Ring VRF: a contextual alias and a proof are addressed by an explicit member
+// key handle, a product-scoped `context` (`[productId, suffix]`) and a `ring`
+// location on a chain (RFC 0004, amended by RFC 0024). The suffix is the same
+// selector as an account's derivation index and expands to the same 32-byte
+// value (RFC 0022).
 const context: ProofContext = ['product.dot', 0]; // [productId, selector]
 const ring = {
   chainId: '0x…', // 32-byte chain genesis hash
   junctions: [{ tag: 'PalletInstance', value: 42 }],
 };
 
-// Get the contextual alias for that (context, ring).
-const aliasResult = await accounts.getContextualAlias(context, ring);
+// Register a key your own product owns for that ring. Permissionless and
+// prompt-free — ownership is the calling product, never a parameter. Returns the
+// member public key. Registering the same index for another ring extends the
+// existing entry rather than adding a second one.
+const registerResult = await accounts.registerRingVrfKey(0, ring);
+
+// Discover another product's keys. Handles are opaque: select by the rings an
+// entry declares, NEVER by index — the index is the owner's implementation
+// detail and hardcoding it breaks the moment the owner rotates or adds a key.
+const keysResult = await accounts.listRingVrfKeys('peopl.dot'); // 'Anonymized' by default
+const personKey = keysResult.isOk()
+  ? keysResult.value.find(entry => entry.rings.some(r => r.chainId === ring.chainId))
+  : undefined;
+
+// A key handle for one of your own keys — for a foreign key use the handle from
+// `listRingVrfKeys` verbatim instead.
+import { ringVrfKeyHandle } from '@novasamatech/host-api-wrapper';
+
+const ownHandle = ringVrfKeyHandle('product.dot', 0);
+
+// Get the contextual alias for that (handle, context, ring).
+const aliasResult = await accounts.getContextualAlias(ownHandle, context, ring);
 
 if (aliasResult.isOk()) {
   const { context: contextBytes, alias } = aliasResult.value;
   console.log('Alias:', alias);
 }
 
-// Create a ring VRF proof binding `message`; the host selects the member key.
-const proofResult = await accounts.createRingVRFProof(context, ring, new Uint8Array([0x48, 0x69]));
+// Create a ring VRF proof binding `message` with an explicit member key.
+// A proof is a bearer token for its context's alias, so a *foreign* handle is
+// admitted only when its owner allowlisted your product in its manifest — there
+// is no user-prompt fallback, and you get `NotAllowlisted` otherwise.
+const proofResult = await accounts.createRingVRFProof(ownHandle, context, ring, new Uint8Array([0x48, 0x69]));
 
 if (proofResult.isOk()) {
   const { proof, contextualAlias, ringIndex, ringRevision } = proofResult.value;
   console.log('Proof:', proof, 'at ring index', ringIndex, 'revision', ringRevision);
 }
 
+// Sign with the member key itself rather than proving membership anonymously
+// (RFC 0024). No context and no ring: it derives no alias and proves nothing, so
+// there is nothing for either to scope. Verified against the member public key,
+// which makes the signature linkable to every other use of that key.
+const signatureResult = await accounts.ringVrfSign(ownHandle, new Uint8Array([0x48, 0x69]));
+
 // sr25519 VRF signature over a product account (RFC-0023). The transcript is a
 // recipe — a root label plus ordered `(label, value)` items — that the host
 // replays verbatim (`Transcript::new(label)` then one `append_message` per item)

package/dist/accounts.d.ts

@@ -1,4 +1,4 @@
-import type { AccountConnectionStatus as AccountConnectionStatusCodec, AccountSelector, CodecType, LegacyAccount as LegacyAccountCodec, ProductAccountId as ProductAccountIdCodec, Subscription, Transport, VrfTranscriptItem as VrfTranscriptItemCodec } from '@novasamatech/host-api';
+import type { AccountConnectionStatus as AccountConnectionStatusCodec, AccountSelector, CodecType, LegacyAccount as LegacyAccountCodec, ProductAccountId as ProductAccountIdCodec, RegisteredRingVrfKey as RegisteredRingVrfKeyCodec, RingVrfKeyDisclosure as RingVrfKeyDisclosureCodec, RingVrfKeyHandle as RingVrfKeyHandleCodec, Subscription, Transport, VrfTranscriptItem as VrfTranscriptItemCodec } from '@novasamatech/host-api';
 import { RingLocation } from '@novasamatech/host-api';
 import type { PolkadotSigner } from 'polkadot-api';
 export type { AccountSelector } from '@novasamatech/host-api';
@@ -18,6 +18,29 @@ export type ProductAccount = {
  * product account's.
  */
 export type ProofContext = [productId: string, suffix: AccountSelector];
+/**
+ * Public name of a registered ring VRF key (RFC-0024).
+ *
+ * Deliberately kept in wire form: the index is the owning product's
+ * implementation detail, so a handle obtained from {@link
+ * createAccountsProvider}'s `listRingVrfKeys` must be passed through opaquely.
+ * **Never hardcode another product's index** — select by declared ring instead;
+ * hardcoding breaks the moment the owner rotates or adds a key. Use
+ * {@link ringVrfKeyHandle} to name a key your own product owns.
+ */
+export type RingVrfKeyHandle = CodecType<typeof RingVrfKeyHandleCodec>;
+/** A ring VRF key registry entry (RFC-0024). */
+export type RegisteredRingVrfKey = CodecType<typeof RegisteredRingVrfKeyCodec>;
+/** How much of a registry entry to ask for: `'Anonymized'` or `'PublicKey'` (RFC-0024). */
+export type RingVrfKeyDisclosure = CodecType<typeof RingVrfKeyDisclosureCodec>;
+/**
+ * Builds a {@link RingVrfKeyHandle} for a key inside `owner`'s ring VRF domain.
+ *
+ * Intended for naming your *own* keys — the ones you passed to
+ * `registerRingVrfKey`. For a foreign key, take the handle from
+ * `listRingVrfKeys` instead of constructing one.
+ */
+export declare function ringVrfKeyHandle(owner: string, index: AccountSelector): RingVrfKeyHandle;
 export type LegacyAccount = CodecType<typeof LegacyAccountCodec>;
 export type AccountConnectionStatus = CodecType<typeof AccountConnectionStatusCodec>;
 /** One `transcript.append_message(label, value)` call replayed by the host (RFC-0023). */
@@ -38,19 +61,87 @@ export declare const createAccountsProvider: (transport?: Transport) => {
     }, import("@novasamatech/scale").CodecError<undefined, "RequestCredentialsErr::NotConnected"> | import("@novasamatech/scale").CodecError<undefined, "RequestCredentialsErr::Rejected"> | import("@novasamatech/scale").CodecError<undefined, "RequestCredentialsErr::DomainNotValid"> | import("@novasamatech/scale").CodecError<{
         reason: string;
     }, "RequestCredentialsErr::Unknown">>;
-    getContextualAlias(context: ProofContext, ring: CodecType<typeof RingLocation>): import("neverthrow").ResultAsync<{
+    /**
+     * Registers a ring VRF key this product owns, declaring the ring it is
+     * intended for (RFC-0024).
+     *
+     * Ownership is the calling product, never a parameter, so this is
+     * permissionless and prompt-free. Registering the same `index` for another
+     * `ring` extends the existing entry rather than creating a second one.
+     *
+     * Registration declares *intent*, not membership: it says "this is the key
+     * I will use for that ring", not "the user is a person". Membership is
+     * still discovered only by attempting a proof.
+     */
+    registerRingVrfKey(index: AccountSelector, ring: CodecType<typeof RingLocation>): import("neverthrow").ResultAsync<Uint8Array<ArrayBufferLike>, import("@novasamatech/scale").CodecError<undefined, "RegisterRingVrfKeyErr::NotConnected"> | import("@novasamatech/scale").CodecError<undefined, "RegisterRingVrfKeyErr::Rejected"> | import("@novasamatech/scale").CodecError<{
+        reason: string;
+    }, "RegisterRingVrfKeyErr::Unknown"> | import("@novasamatech/scale").CodecError<undefined, "RegisterRingVrfKeyErr::RingNotFound">>;
+    /**
+     * Lists the ring VRF registry entries owned by `owner` — this product or
+     * another one (RFC-0024).
+     *
+     * Listing your own keys is permissionless; a foreign `owner` needs a grant
+     * or produces a user prompt. `'PublicKey'` disclosure additionally returns
+     * the member public key, which is linkable across every ring it appears in
+     * and so is permissioned cross-product.
+     *
+     * Select the entry you want by the rings it declares, never by index.
+     */
+    listRingVrfKeys(owner: string, disclosure?: RingVrfKeyDisclosure): import("neverthrow").ResultAsync<{
+        handle: [string, {
+            tag: "Index";
+            value: number;
+        } | {
+            tag: "Raw";
+            value: Uint8Array<ArrayBufferLike>;
+        }];
+        rings: {
+            chainId: `0x${string}`;
+            junctions: ({
+                tag: "PalletInstance";
+                value: number;
+            } | {
+                tag: "CollectionId";
+                value: Uint8Array<ArrayBufferLike>;
+            })[];
+        }[];
+        publicKey: Uint8Array<ArrayBufferLike> | undefined;
+    }[], import("@novasamatech/scale").CodecError<undefined, "ListRingVrfKeysErr::NotConnected"> | import("@novasamatech/scale").CodecError<undefined, "ListRingVrfKeysErr::Rejected"> | import("@novasamatech/scale").CodecError<{
+        reason: string;
+    }, "ListRingVrfKeysErr::Unknown">>;
+    /**
+     * Reads the contextual alias `keyHandle` resolves to under `context` in `ring`
+     * (RFC-0004, amended by RFC-0024).
+     *
+     * `ring` stays explicit even though the handle carries its declared rings,
+     * because a key may be registered for several and the caller must say which
+     * the alias is against; the host fails with `KeyNotInRing` otherwise.
+     *
+     * Check `ringRevision` on each use of the resulting alias and renew when it
+     * has moved — nothing else watches for it.
+     */
+    getContextualAlias(keyHandle: RingVrfKeyHandle, context: ProofContext, ring: CodecType<typeof RingLocation>): import("neverthrow").ResultAsync<{
         context: Uint8Array<ArrayBufferLike>;
         alias: Uint8Array<ArrayBufferLike>;
     }, import("@novasamatech/scale").CodecError<undefined, "GetAliasErr::Rejected"> | import("@novasamatech/scale").CodecError<{
         reason: string;
-    }, "GetAliasErr::Unknown"> | import("@novasamatech/scale").CodecError<undefined, "GetAliasErr::RingNotFound"> | import("@novasamatech/scale").CodecError<undefined, "GetAliasErr::NotMember">>;
+    }, "GetAliasErr::Unknown"> | import("@novasamatech/scale").CodecError<undefined, "GetAliasErr::RingNotFound"> | import("@novasamatech/scale").CodecError<undefined, "GetAliasErr::NotMember"> | import("@novasamatech/scale").CodecError<undefined, "GetAliasErr::KeyNotRegistered"> | import("@novasamatech/scale").CodecError<undefined, "GetAliasErr::KeyNotInRing">>;
     getLegacyAccounts(): import("neverthrow").ResultAsync<{
         publicKey: Uint8Array<ArrayBufferLike>;
         name: string | undefined;
     }[], import("@novasamatech/scale").CodecError<undefined, "RequestCredentialsErr::NotConnected"> | import("@novasamatech/scale").CodecError<undefined, "RequestCredentialsErr::Rejected"> | import("@novasamatech/scale").CodecError<undefined, "RequestCredentialsErr::DomainNotValid"> | import("@novasamatech/scale").CodecError<{
         reason: string;
     }, "RequestCredentialsErr::Unknown">>;
-    createRingVRFProof(context: ProofContext, ring: CodecType<typeof RingLocation>, message: Uint8Array): import("neverthrow").ResultAsync<{
+    /**
+     * Produces an anonymous ring VRF proof with `keyHandle` under `context` in
+     * `ring` (RFC-0004, amended by RFC-0024).
+     *
+     * A proof is a bearer token for its context's alias, so a *foreign*
+     * `keyHandle` is admitted only when the owning product allowlisted this one
+     * in its manifest — there is no user-prompt fallback, and the host returns
+     * `NotAllowlisted` otherwise.
+     */
+    createRingVRFProof(keyHandle: RingVrfKeyHandle, context: ProofContext, ring: CodecType<typeof RingLocation>, message: Uint8Array): import("neverthrow").ResultAsync<{
         proof: Uint8Array<ArrayBufferLike>;
         contextualAlias: {
             context: Uint8Array<ArrayBufferLike>;
@@ -60,7 +151,22 @@ export declare const createAccountsProvider: (transport?: Transport) => {
         ringRevision: number;
     }, import("@novasamatech/scale").CodecError<undefined, "CreateProofErr::Rejected"> | import("@novasamatech/scale").CodecError<{
         reason: string;
-    }, "CreateProofErr::Unknown"> | import("@novasamatech/scale").CodecError<undefined, "CreateProofErr::RingNotFound"> | import("@novasamatech/scale").CodecError<undefined, "CreateProofErr::NotMember">>;
+    }, "CreateProofErr::Unknown"> | import("@novasamatech/scale").CodecError<undefined, "CreateProofErr::RingNotFound"> | import("@novasamatech/scale").CodecError<undefined, "CreateProofErr::NotMember"> | import("@novasamatech/scale").CodecError<undefined, "CreateProofErr::KeyNotRegistered"> | import("@novasamatech/scale").CodecError<undefined, "CreateProofErr::KeyNotInRing"> | import("@novasamatech/scale").CodecError<undefined, "CreateProofErr::NotAllowlisted">>;
+    /**
+     * Signs `message` with the ring VRF member key itself, producing an ordinary
+     * signature rather than an anonymous ring proof (RFC-0024).
+     *
+     * Takes no context and no ring: it derives no alias and proves no
+     * membership. A verifier needs the member public key, so the signature is
+     * **linkable** to every other use of that key — including every ring the key
+     * is a member of.
+     *
+     * Like `createRingVRFProof`, a foreign `keyHandle` requires the owner's
+     * manifest allowlist and has no prompt fallback.
+     */
+    ringVrfSign(keyHandle: RingVrfKeyHandle, message: Uint8Array): import("neverthrow").ResultAsync<Uint8Array<ArrayBufferLike>, import("@novasamatech/scale").CodecError<undefined, "RingVrfSignErr::NotConnected"> | import("@novasamatech/scale").CodecError<undefined, "RingVrfSignErr::Rejected"> | import("@novasamatech/scale").CodecError<{
+        reason: string;
+    }, "RingVrfSignErr::Unknown"> | import("@novasamatech/scale").CodecError<undefined, "RingVrfSignErr::KeyNotRegistered"> | import("@novasamatech/scale").CodecError<undefined, "RingVrfSignErr::NotAllowlisted">>;
     /**
      * Produces an sr25519 (schnorrkel) VRF signature from a product account (RFC-0023).
      *
@@ -101,19 +207,87 @@ export declare const accounts: {
     }, import("@novasamatech/scale").CodecError<undefined, "RequestCredentialsErr::NotConnected"> | import("@novasamatech/scale").CodecError<undefined, "RequestCredentialsErr::Rejected"> | import("@novasamatech/scale").CodecError<undefined, "RequestCredentialsErr::DomainNotValid"> | import("@novasamatech/scale").CodecError<{
         reason: string;
     }, "RequestCredentialsErr::Unknown">>;
-    getContextualAlias(context: ProofContext, ring: CodecType<typeof RingLocation>): import("neverthrow").ResultAsync<{
+    /**
+     * Registers a ring VRF key this product owns, declaring the ring it is
+     * intended for (RFC-0024).
+     *
+     * Ownership is the calling product, never a parameter, so this is
+     * permissionless and prompt-free. Registering the same `index` for another
+     * `ring` extends the existing entry rather than creating a second one.
+     *
+     * Registration declares *intent*, not membership: it says "this is the key
+     * I will use for that ring", not "the user is a person". Membership is
+     * still discovered only by attempting a proof.
+     */
+    registerRingVrfKey(index: AccountSelector, ring: CodecType<typeof RingLocation>): import("neverthrow").ResultAsync<Uint8Array<ArrayBufferLike>, import("@novasamatech/scale").CodecError<undefined, "RegisterRingVrfKeyErr::NotConnected"> | import("@novasamatech/scale").CodecError<undefined, "RegisterRingVrfKeyErr::Rejected"> | import("@novasamatech/scale").CodecError<{
+        reason: string;
+    }, "RegisterRingVrfKeyErr::Unknown"> | import("@novasamatech/scale").CodecError<undefined, "RegisterRingVrfKeyErr::RingNotFound">>;
+    /**
+     * Lists the ring VRF registry entries owned by `owner` — this product or
+     * another one (RFC-0024).
+     *
+     * Listing your own keys is permissionless; a foreign `owner` needs a grant
+     * or produces a user prompt. `'PublicKey'` disclosure additionally returns
+     * the member public key, which is linkable across every ring it appears in
+     * and so is permissioned cross-product.
+     *
+     * Select the entry you want by the rings it declares, never by index.
+     */
+    listRingVrfKeys(owner: string, disclosure?: RingVrfKeyDisclosure): import("neverthrow").ResultAsync<{
+        handle: [string, {
+            tag: "Index";
+            value: number;
+        } | {
+            tag: "Raw";
+            value: Uint8Array<ArrayBufferLike>;
+        }];
+        rings: {
+            chainId: `0x${string}`;
+            junctions: ({
+                tag: "PalletInstance";
+                value: number;
+            } | {
+                tag: "CollectionId";
+                value: Uint8Array<ArrayBufferLike>;
+            })[];
+        }[];
+        publicKey: Uint8Array<ArrayBufferLike> | undefined;
+    }[], import("@novasamatech/scale").CodecError<undefined, "ListRingVrfKeysErr::NotConnected"> | import("@novasamatech/scale").CodecError<undefined, "ListRingVrfKeysErr::Rejected"> | import("@novasamatech/scale").CodecError<{
+        reason: string;
+    }, "ListRingVrfKeysErr::Unknown">>;
+    /**
+     * Reads the contextual alias `keyHandle` resolves to under `context` in `ring`
+     * (RFC-0004, amended by RFC-0024).
+     *
+     * `ring` stays explicit even though the handle carries its declared rings,
+     * because a key may be registered for several and the caller must say which
+     * the alias is against; the host fails with `KeyNotInRing` otherwise.
+     *
+     * Check `ringRevision` on each use of the resulting alias and renew when it
+     * has moved — nothing else watches for it.
+     */
+    getContextualAlias(keyHandle: RingVrfKeyHandle, context: ProofContext, ring: CodecType<typeof RingLocation>): import("neverthrow").ResultAsync<{
         context: Uint8Array<ArrayBufferLike>;
         alias: Uint8Array<ArrayBufferLike>;
     }, import("@novasamatech/scale").CodecError<undefined, "GetAliasErr::Rejected"> | import("@novasamatech/scale").CodecError<{
         reason: string;
-    }, "GetAliasErr::Unknown"> | import("@novasamatech/scale").CodecError<undefined, "GetAliasErr::RingNotFound"> | import("@novasamatech/scale").CodecError<undefined, "GetAliasErr::NotMember">>;
+    }, "GetAliasErr::Unknown"> | import("@novasamatech/scale").CodecError<undefined, "GetAliasErr::RingNotFound"> | import("@novasamatech/scale").CodecError<undefined, "GetAliasErr::NotMember"> | import("@novasamatech/scale").CodecError<undefined, "GetAliasErr::KeyNotRegistered"> | import("@novasamatech/scale").CodecError<undefined, "GetAliasErr::KeyNotInRing">>;
     getLegacyAccounts(): import("neverthrow").ResultAsync<{
         publicKey: Uint8Array<ArrayBufferLike>;
         name: string | undefined;
     }[], import("@novasamatech/scale").CodecError<undefined, "RequestCredentialsErr::NotConnected"> | import("@novasamatech/scale").CodecError<undefined, "RequestCredentialsErr::Rejected"> | import("@novasamatech/scale").CodecError<undefined, "RequestCredentialsErr::DomainNotValid"> | import("@novasamatech/scale").CodecError<{
         reason: string;
     }, "RequestCredentialsErr::Unknown">>;
-    createRingVRFProof(context: ProofContext, ring: CodecType<typeof RingLocation>, message: Uint8Array): import("neverthrow").ResultAsync<{
+    /**
+     * Produces an anonymous ring VRF proof with `keyHandle` under `context` in
+     * `ring` (RFC-0004, amended by RFC-0024).
+     *
+     * A proof is a bearer token for its context's alias, so a *foreign*
+     * `keyHandle` is admitted only when the owning product allowlisted this one
+     * in its manifest — there is no user-prompt fallback, and the host returns
+     * `NotAllowlisted` otherwise.
+     */
+    createRingVRFProof(keyHandle: RingVrfKeyHandle, context: ProofContext, ring: CodecType<typeof RingLocation>, message: Uint8Array): import("neverthrow").ResultAsync<{
         proof: Uint8Array<ArrayBufferLike>;
         contextualAlias: {
             context: Uint8Array<ArrayBufferLike>;
@@ -123,7 +297,22 @@ export declare const accounts: {
         ringRevision: number;
     }, import("@novasamatech/scale").CodecError<undefined, "CreateProofErr::Rejected"> | import("@novasamatech/scale").CodecError<{
         reason: string;
-    }, "CreateProofErr::Unknown"> | import("@novasamatech/scale").CodecError<undefined, "CreateProofErr::RingNotFound"> | import("@novasamatech/scale").CodecError<undefined, "CreateProofErr::NotMember">>;
+    }, "CreateProofErr::Unknown"> | import("@novasamatech/scale").CodecError<undefined, "CreateProofErr::RingNotFound"> | import("@novasamatech/scale").CodecError<undefined, "CreateProofErr::NotMember"> | import("@novasamatech/scale").CodecError<undefined, "CreateProofErr::KeyNotRegistered"> | import("@novasamatech/scale").CodecError<undefined, "CreateProofErr::KeyNotInRing"> | import("@novasamatech/scale").CodecError<undefined, "CreateProofErr::NotAllowlisted">>;
+    /**
+     * Signs `message` with the ring VRF member key itself, producing an ordinary
+     * signature rather than an anonymous ring proof (RFC-0024).
+     *
+     * Takes no context and no ring: it derives no alias and proves no
+     * membership. A verifier needs the member public key, so the signature is
+     * **linkable** to every other use of that key — including every ring the key
+     * is a member of.
+     *
+     * Like `createRingVRFProof`, a foreign `keyHandle` requires the owner's
+     * manifest allowlist and has no prompt fallback.
+     */
+    ringVrfSign(keyHandle: RingVrfKeyHandle, message: Uint8Array): import("neverthrow").ResultAsync<Uint8Array<ArrayBufferLike>, import("@novasamatech/scale").CodecError<undefined, "RingVrfSignErr::NotConnected"> | import("@novasamatech/scale").CodecError<undefined, "RingVrfSignErr::Rejected"> | import("@novasamatech/scale").CodecError<{
+        reason: string;
+    }, "RingVrfSignErr::Unknown"> | import("@novasamatech/scale").CodecError<undefined, "RingVrfSignErr::KeyNotRegistered"> | import("@novasamatech/scale").CodecError<undefined, "RingVrfSignErr::NotAllowlisted">>;
     /**
      * Produces an sr25519 (schnorrkel) VRF signature from a product account (RFC-0023).
      *

package/dist/accounts.js

@@ -1,9 +1,19 @@
-import { CreateProofErr, GetAliasErr, GetUserIdErr, LoginErr, ProductProofContext, RequestCredentialsErr, RingLocation, SignVrfErr, SigningPayload, SigningPayloadWithoutAccount, SigningRawPayload, SigningRawPayloadWithoutAccount, assertEnumVariant, createHostApi, derivationIndexOf, enumValue, fromHex, isEnumVariant, toHex, } from '@novasamatech/host-api';
+import { CreateProofErr, GetAliasErr, GetUserIdErr, ListRingVrfKeysErr, LoginErr, ProductProofContext, RegisterRingVrfKeyErr, RequestCredentialsErr, RingLocation, RingVrfSignErr, SignVrfErr, SigningPayload, SigningPayloadWithoutAccount, SigningRawPayload, SigningRawPayloadWithoutAccount, assertEnumVariant, createHostApi, derivationIndexOf, enumValue, fromHex, isEnumVariant, toHex, } from '@novasamatech/host-api';
 import { decAnyMetadata, unifyMetadata } from '@polkadot-api/substrate-bindings';
 import { err, ok } from 'neverthrow';
 import { AccountId } from 'polkadot-api';
 import { getPolkadotSignerFromPjs } from 'polkadot-api/pjs-signer';
 import { sandboxTransport } from './sandboxTransport.js';
+/**
+ * Builds a {@link RingVrfKeyHandle} for a key inside `owner`'s ring VRF domain.
+ *
+ * Intended for naming your *own* keys — the ones you passed to
+ * `registerRingVrfKey`. For a foreign key, take the handle from
+ * `listRingVrfKeys` instead of constructing one.
+ */
+export function ringVrfKeyHandle(owner, index) {
+    return [owner, derivationIndexOf(index)];
+}
 const UNSUPPORTED_VERSION_ERROR = 'Unsupported message version';
 export const createAccountsProvider = (transport = sandboxTransport) => {
     const hostApi = createHostApi(transport);
@@ -48,9 +58,67 @@ export const createAccountsProvider = (transport = sandboxTransport) => {
                 return err(new RequestCredentialsErr.Unknown({ reason: `Unsupported response version ${response.tag}` }));
             });
         },
-        getContextualAlias(context, ring) {
+        /**
+         * Registers a ring VRF key this product owns, declaring the ring it is
+         * intended for (RFC-0024).
+         *
+         * Ownership is the calling product, never a parameter, so this is
+         * permissionless and prompt-free. Registering the same `index` for another
+         * `ring` extends the existing entry rather than creating a second one.
+         *
+         * Registration declares *intent*, not membership: it says "this is the key
+         * I will use for that ring", not "the user is a person". Membership is
+         * still discovered only by attempting a proof.
+         */
+        registerRingVrfKey(index, ring) {
+            return hostApi
+                .accountRegisterRingVrfKey(enumValue('v1', [derivationIndexOf(index), ring]))
+                .mapErr(e => e.value)
+                .andThen(response => {
+                if (isEnumVariant(response, 'v1')) {
+                    return ok(response.value);
+                }
+                // @ts-expect-error response.tag is never here
+                return err(new RegisterRingVrfKeyErr.Unknown({ reason: `Unsupported response version ${response.tag}` }));
+            });
+        },
+        /**
+         * Lists the ring VRF registry entries owned by `owner` — this product or
+         * another one (RFC-0024).
+         *
+         * Listing your own keys is permissionless; a foreign `owner` needs a grant
+         * or produces a user prompt. `'PublicKey'` disclosure additionally returns
+         * the member public key, which is linkable across every ring it appears in
+         * and so is permissioned cross-product.
+         *
+         * Select the entry you want by the rings it declares, never by index.
+         */
+        listRingVrfKeys(owner, disclosure = 'Anonymized') {
             return hostApi
-                .accountGetAlias(enumValue('v1', [toProofContext(context), ring]))
+                .accountListRingVrfKeys(enumValue('v1', [owner, disclosure]))
+                .mapErr(e => e.value)
+                .andThen(response => {
+                if (isEnumVariant(response, 'v1')) {
+                    return ok(response.value);
+                }
+                // @ts-expect-error response.tag is never here
+                return err(new ListRingVrfKeysErr.Unknown({ reason: `Unsupported response version ${response.tag}` }));
+            });
+        },
+        /**
+         * Reads the contextual alias `keyHandle` resolves to under `context` in `ring`
+         * (RFC-0004, amended by RFC-0024).
+         *
+         * `ring` stays explicit even though the handle carries its declared rings,
+         * because a key may be registered for several and the caller must say which
+         * the alias is against; the host fails with `KeyNotInRing` otherwise.
+         *
+         * Check `ringRevision` on each use of the resulting alias and renew when it
+         * has moved — nothing else watches for it.
+         */
+        getContextualAlias(keyHandle, context, ring) {
+            return hostApi
+                .accountGetAlias(enumValue('v1', [keyHandle, toProofContext(context), ring]))
                 .mapErr(e => e.value)
                 .andThen(response => {
                 if (isEnumVariant(response, 'v1')) {
@@ -72,9 +140,18 @@ export const createAccountsProvider = (transport = sandboxTransport) => {
                 return err(new RequestCredentialsErr.Unknown({ reason: `Unsupported response version ${response.tag}` }));
             });
         },
-        createRingVRFProof(context, ring, message) {
+        /**
+         * Produces an anonymous ring VRF proof with `keyHandle` under `context` in
+         * `ring` (RFC-0004, amended by RFC-0024).
+         *
+         * A proof is a bearer token for its context's alias, so a *foreign*
+         * `keyHandle` is admitted only when the owning product allowlisted this one
+         * in its manifest — there is no user-prompt fallback, and the host returns
+         * `NotAllowlisted` otherwise.
+         */
+        createRingVRFProof(keyHandle, context, ring, message) {
             return hostApi
-                .accountCreateProof(enumValue('v1', [toProofContext(context), ring, message]))
+                .accountCreateProof(enumValue('v1', [keyHandle, toProofContext(context), ring, message]))
                 .mapErr(e => e.value)
                 .andThen(response => {
                 if (isEnumVariant(response, 'v1')) {
@@ -84,6 +161,30 @@ export const createAccountsProvider = (transport = sandboxTransport) => {
                 return err(new CreateProofErr.Unknown({ reason: `Unsupported response version ${response.tag}` }));
             });
         },
+        /**
+         * Signs `message` with the ring VRF member key itself, producing an ordinary
+         * signature rather than an anonymous ring proof (RFC-0024).
+         *
+         * Takes no context and no ring: it derives no alias and proves no
+         * membership. A verifier needs the member public key, so the signature is
+         * **linkable** to every other use of that key — including every ring the key
+         * is a member of.
+         *
+         * Like `createRingVRFProof`, a foreign `keyHandle` requires the owner's
+         * manifest allowlist and has no prompt fallback.
+         */
+        ringVrfSign(keyHandle, message) {
+            return hostApi
+                .accountRingVrfSign(enumValue('v1', [keyHandle, message]))
+                .mapErr(e => e.value)
+                .andThen(response => {
+                if (isEnumVariant(response, 'v1')) {
+                    return ok(response.value);
+                }
+                // @ts-expect-error response.tag is never here
+                return err(new RingVrfSignErr.Unknown({ reason: `Unsupported response version ${response.tag}` }));
+            });
+        },
         /**
          * Produces an sr25519 (schnorrkel) VRF signature from a product account (RFC-0023).
          *

package/dist/index.d.ts

@@ -8,8 +8,8 @@ export type { ChatBotRegistrationResult, ChatCustomMessageRenderer, ChatCustomMe
 export { createProductChatManager, matchChatCustomRenderers } from './chat.js';
 export type { ProductAccountId, ProductAccountRef, SignedStatement, Statement, StatementTopicFilter, StatementsPage, Topic, } from './statementStore.js';
 export { createStatementStore } from './statementStore.js';
-export type { AccountConnectionStatus, AccountSelector, LegacyAccount, ProductAccount, ProofContext, VrfTranscriptItem, } from './accounts.js';
-export { accounts, createAccountsProvider } from './accounts.js';
+export type { AccountConnectionStatus, AccountSelector, LegacyAccount, ProductAccount, ProofContext, RegisteredRingVrfKey, RingVrfKeyDisclosure, RingVrfKeyHandle, VrfTranscriptItem, } from './accounts.js';
+export { accounts, createAccountsProvider, ringVrfKeyHandle } from './accounts.js';
 export type { ThemeMode } from './theme.js';
 export { createThemeProvider } from './theme.js';
 export { createLocalStorage, hostLocalStorage } from './localStorage.js';

package/dist/index.js

@@ -6,7 +6,7 @@ export { createLegacyExtensionEnableFactory, injectSpektrExtension } from './inj
 export { createPapiProvider } from './papiProvider.js';
 export { createProductChatManager, matchChatCustomRenderers } from './chat.js';
 export { createStatementStore } from './statementStore.js';
-export { accounts, createAccountsProvider } from './accounts.js';
+export { accounts, createAccountsProvider, ringVrfKeyHandle } from './accounts.js';
 export { createThemeProvider } from './theme.js';
 export { createLocalStorage, hostLocalStorage } from './localStorage.js';
 export { createNotificationManager, notificationManager } from './notification.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@novasamatech/host-api-wrapper",
   "type": "module",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Host API wrapper: integrate and run your product inside Polkadot browser.",
   "license": "Apache-2.0",
   "repository": {
@@ -28,7 +28,7 @@
     "@polkadot/extension-inject": "^0.63.1",
     "@polkadot-api/json-rpc-provider-proxy": "^0.4.0",
     "@polkadot-api/substrate-bindings": "^0.20.3",
-    "@novasamatech/host-api": "0.9.2",
+    "@novasamatech/host-api": "0.9.3",
     "polkadot-api": ">=2",
     "neverthrow": "^8.2.0"
   },