The web is a wonderful place: open, permissionless, linkable, and composable, but it also contains many dangers, with numerous actors—both vulnerable and malicious.

Self-custody key is difficult, and Passkey is, in effect, going to be a custodial solution, so you need a separate app outside of the web, which introduces friction.

The ideal solution is to structure an isolated and secure environment within the web itself and bridge only the results of signing and decryption to general web apps and extensions, with seamless integration. Here is one possible path to achieve that.

For example, it enables users to:

Overview

The browser turns itself into the foundation to help your web apps and extensions build self-custody, providing a new dedicated store and APIs. Therefore, you can easily build self-custody apps using two APIs, window.ssi and browser.ssi.

SSI Store Service

It is an internal, dedicated store for credentials such as secret keys and authorization data. It is protected by an isolated process model and encryption. This service is responsible for executing tasks related to credentials, such as signing/decryption. The separation of concerns ensures a consistent service interface, regardless of where the actual data is stored (e.g., on the file system, a Secure Element (SE), or on separate hardware). It is accessed via internal privileged services in browser.ssi, window.ssi, and browser settings.

browser.ssi

It is a powerful API (in Chrome, it would be named chrome.ssi), bridging tasks related to credentials, such as signing/decryption, between the internal module and user land. It also provides the state of settings while prioritizing privacy and security, allowing users to choose whether to make them open. General web extensions can use this API in their scripts.

window.ssi

It is the most accessible API that is widely published on the web, bridging tasks related to credentials, such as signing/decryption, between the internal module and user land. General web extensions and general web apps can use it anywhere.

Browser setting

It is the user interface to the SSI Store Service, providing key generation and API configuration within the privileged process that differs from general web apps.

Developer Experience

In this section, we’ll explain how web app development changes when browsers have self-custodial key management built in, along with browser features designed to directly integrate self-custodial keys.

Benefits for web developers

While we can’t predict all the potential impacts, we can at least highlight the following:

1. The keys are isolated, concealed, and not accessible to any general web app.
2. You, as web developers, no longer need to handle key management, as it’s delegated to the browser.
3. You will simply use native APIs exposed for web apps.

It’s important to note that this is self-custody, not custody, because custody provides a similar experience for web developers, as you only access the API and don’t need to manage the keys. On the other hand, there is a significant difference for users between the two. As any Bitcoiner knows, “Not your keys, not your coins.”

However, self-custody is very difficult. We won’t delve too much into it here—you’ll need to read other resources to learn more—but the point is that some of the difficulties of self-custody can be alleviated by delegating the responsibility to the browser. It’s also important to clarify that we never intended for the browser to store assets—just to facilitate online spending.

This is similar to storing data in web storage, managed by an extension, but with one key difference: no web app can directly access the key. It’s akin to using an API through an external remote service that holds the key (while remaining non-custodial), but this key can be available from the moment the tab is created and persisted indefinitely. You may no longer need to worry about leakage risks or race conditions.

Browser architecture and APIs

To explain how this works, let’s modify the diagram from the previous section to focus on the app side and distinguish between “cached data” and “secret key.”

“Cached data” is stored in local storage, IndexedDB, and similar locations, while the “secret key” is kept in the internal store. Both are accessed by the app via a global window. However, the secret key is further protected by the browser’s process security model, in addition to the usual web sandboxing.

Taking Firefox as an example, the “secret key” resides in the Parent Process, while the “cached data” is typically located in the WebContent Process, in the Child Process.

cite: https://firefox-source-docs.mozilla.org/dom/ipc/process_model.html

These inter-process communication (IPC) operations require privileged permissions and a security policy, with the bridge to user land handled by the native APIs, browser.ssi and window.ssi.

Again, in Firefox, the “chrome:” on the right corresponds to those native APIs and has permissions to privileged services over the parent process, while interference from the left in user land is blocked.

cite: https://firefox-source-docs.mozilla.org/dom/scriptSecurity/index.html

This means that even if your web app becomes vulnerable or malicious—no matter how carefully it is developed—the user keys are not at risk. While the same issues could arise with browser software, browsers are less susceptible to supply chain attacks due to their limited reliance on package ecosystems (much of it is hand-coded). They are more robust because they center around the process model described above and have significantly limited external communications, which reduces the attack surface.

While not as secure as completely separated hardware or paper, this approach should ensure that the secret key remains secret and minimizes the risk of leakage by web apps. Importantly, online usage will be more seamless than with hardware or paper, and on par with general web apps that manage keys.

Developing App

Currently this is individual project and you can experience those APIs and develop the app in a custom browser of our reference implementation based on Firefox ESR.

This section provides a guide to using that browser as an example and developing apps that run on top of it.

Installation

The custom browser add-ons four main components for Self-Sovereign Individual - window.ssi(global API), browser.ssi(WebExtensions API), services.ssi(SSI Store Service) and about:selfsovereignindividual(Setting Page) - in the Firefox.

Also, those components can easily add-on to other firefox forks as well, so you can choose another implementation. And your implementation, too!

Please choose the best for you.

System Requirements

https://www.mozilla.org/en-US/firefox/128.5.0/system-requirements/

Install from source

1. Set up your editor - https://firefox-source-docs.mozilla.org/contributing/editor.html
2. Check out from https://gitlab.com/studioteatwo/gecko-dev-for-ssi

git clone git@gitlab.com:studioteatwo/gecko-dev-for-ssi.git --depth 1

3. Build

cd gecko-dev-for-ssi
./mach build

4. After that, you can choose ./mach run (for interactive) or ./mach package (for static).

Install from the binaries

Download the one for your platform from the distribution sites.

GitHub Releases

https://github.com/Browser-for-SSI/gecko-dev-pkg-distributor/releases

Install other firefox forks

Tor Browser version

1. Set up your editor - https://firefox-source-docs.mozilla.org/contributing/editor.html
2. Check out from https://gitlab.com/studioteatwo/gecko-dev-for-ssi

git clone git@gitlab.com:studioteatwo/gecko-dev-for-ssi.git --depth 1
git checkout mvp-tor

3. Follow: https://gitlab.torproject.org/tpo/applications/team/-/wikis/Development-Information/Tor-Browser/dev-Build

Configure

Depending on your build, you may need to configure manually in about:config.

Versioning

These builds are forked and therefore managed by versioning both the custom add-on browser and the base browser. The version is difined below:

v<custom-browser-version><custom-browser-branch>-<base-browser-version><base-browser-suffix>

For example v0.0.1mvp-128.5.0esr is destined for a 0.0.1 release from mvp branch, based on the Mozilla Firefox 128.5.0 ESR release. If v0.0.1beta-14.0-1tor, it means a 0.0.1 release from beta branch, based on the Tor browser 14.0-1 release.

And, to distinguish with the branding, the install path and so on of the base browser, the namespace ssb is defined.

Browser Status

gecko-dev-for-ssi

Using window.ssi

window.ssi is accessible anywhere that window is visible. This means that generally it can be accessed by web apps loaded in tab, and in-page scripts (in some cases content scripts as well) in web extensions, etc.

It mainly serves the access to user’s public key and the mediation to the tasks by user’s secret key.

Basic usage

You call it in the same way as window.location, window.navigator, etc.

const publicKey = await window.ssi.nostr.getPublicKey()
const user = someNostrService.getUser(publicKey)

If you won’t/can’t call Promise for security reasons and so on, you can use a callback-type as well.

window.ssi.nostr.getPublicKeyWithCallback(publicKey => {
  const user = someNostrService.getUser(publicKey)
})

Listening to event

You listen the event as CustomEvent.

const accountChangedHandler = (event: CustomEvent<string>) => {
  const newPublicKey = event.detail
  doSomething(newPublicKey)
}
window.ssi.nostr.addEventListener("accountChanged", accountChangedHandler)

Wrapping in protocol standard

In most cases, you would wrap just the parts about the key management in a protocol standard like NIP-07.

const Nip07 = {
  async getPublicKey(): Promise<PulicKey> {
    return window.ssi.nostr.getPublicKey()
  },
  async signEvent(event: {
    kind: number
    content: string
    tags: string[][]
    created_at: number
  }): Promise<NostrEvent> {
    event.pubkey = await this.getPublicKey()
    const eventHash = serializeEvent(event)
    const sig = await window.ssi.nostr.sign(eventHash, { type: "signEvent", event })
    return {...event, id: eventHash, sig}
  }
}
window.nostr = Nip07

Using browser.ssi

browser.ssi is the underlying API that is more powerful than window.ssi. It does everything window.ssi does, and more:

• Can read all the credentials (if the user self-sovereignly does allow)
• Can read the user’s setting states (as long as there are no privacy and security issues)
• Can integrate element APIs to create any flow you want

Instead, this API is limited where you can use. It would be assumed to be built by Built-in API or Experimental API of Firefox based on WebExtensions, so you can access through your web extension.

Set up

To use this API, you declare in the permissions property in your WebExtension’s manifest.json file. For example:

// manifest.json
{
  "manifest_version": 2,
  "name": "Example Web Extension",

  "permissions": ["ssi"],
}

If you want the subset of the specific protocol, please add the one with ssi together.

// manifest.json
{
  "permissions": ["ssi", "ssi.nostr"],
}

Basic usage

The ssi declared in the permissions property in your manifest file is injected into the global object browser.

await browser.ssi.searchCredentialsWithoutSecret({
  protocolName,
  credentialName,
})

Search store

Example of a full search for SSI store service. The return values are array of ssi.Credential.

const credentials = await browser.ssi.searchCredentialsWithoutSecret(
  1,
  {
    primary: false // explicitly set primary to false.
  }
)
store.set(credentials.map(credential => doSomething(credential)))

To get the current public key of the user:

const credentials = await browser.ssi.searchCredentialsWithoutSecret(
  1,
  {
    protocolName: "nostr",
    credentialName: "nsec",
    primary: true,
  }
)
const publicKey = credentials[0].identifier // format is "npub1..."

Request a task related to the key

You can sign and encrypt/decrypt using the internal key currently set as primary for a specific protocol.

const signature = await browser.ssi.nostr.sign(message, { type: "signEvent" })

Get user settings

You will get what you need. The return value is ssi.nostr.Preference.

const preferences = await browser.ssi.nostr.getPrefs()
store.set(preferences)

Receive notifications when user settings status changes

You can listen to this as a special event.

const onPrimaryChangedCallback = async () => {
  // Get the new primary key. If without authorization, auth dialog will be prompted.
  const credentials = await browser.ssi.searchCredentialsWithoutSecret({
    protocolName: "nostr",
    credentialName: "nsec",
    primary: true
  })
  const publicKey = decodeNpub(credentials[0].identifier)

  // Send the message to the contents
  const tabs = await browser.tabs.query()
  for (const tab of tabs) {
    browser.tabs
      .sendMessage(tab.id, {
        action: "accountChanged",
        args: { publicKey },
      })
  }
}
browser.ssi.nostr.onPrimaryChanged.addListener(onPrimaryChangedCallback)

At first glance it looks similar to a normal EventListener, but it may be useful to know that it is a different mechanism to cross IPC.

Authorization

It’s always the libra between the UX and security for powerful features. Just like the history of camera and notification permissions, this one requires careful considerations and is one of the topics we explore the most: Authorization flow.

Currently, the combination of the trusted site method and password authentication is implemented. This is a two step method and the basic flow is as follows:

The trusted site that the user has explicitly declared trust for by specifying the app’s URL is the top level. If that is NG, a prompt of the browser’s primary password or OS account password authentication is presented to the user. However, this is the self-sovereign browser, so, if both settings are explicitly disabled, it is accepted the user has self-sovereignly chosen that the app does not need the user’s consent to use their key, and the request will be allowed through unconditionally.

This can be done below.

// Authorization will be performed using the secret currently set as primary
// within the specified protocol name and credential name.
const permitted = await browser.ssi.askConsent(
  1,
  "nostr", // protocol name
  "nsec", // credential name
  {
    // A text description displayed on Auth dialog. Base title (kind such as sign/encrypt
    // and site URL) is generated by the system, so add additional information as needed.
    caption: "Offer from ABC Company"
  }
)
if (permitted) {
  // Go to next
}

window.ssi

Examples

window.ssi.nostr.getPublicKey()

APIs

ssi

ssi.nostr

ssi

That’s to empower individuals on the self-sovereign path.

window.ssi is the most accessible API that is widely published on the web, bridging tasks related to credentials, such as signing/decrypting, between the internal module and user land.

Functions

addEventListener()

removeEventListener()

ssi.addEventListener()

Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.

The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options’s capture.

When set to true, options’s capture prevents callback from being invoked when the event’s eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event’s eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event’s eventPhase attribute value is AT_TARGET.

When set to true, options’s passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.

When set to true, options’s once indicates that the callback will only be invoked once after which the event listener will be removed.

If an AbortSignal is passed for options’s signal, then the event listener will be removed when signal is aborted.

The event listener is appended to target’s event listener list and is not appended if it has the same type, callback, and capture.

MDN Reference

ssi.removeEventListener()

Removes the event listener in target’s event listener list with the same type, callback, and options.

MDN Reference

ssi.nostr

The window.ssi subset for Nostr protocol.

Types

NostrDecryptType

Implementation list of Nostr encyption spec.

NostrEncryptType

Implementation list of Nostr encyption spec.

NostrSignType

Implementation list of Nostr signature spec.

Functions

addEventListener()

decrypt()

Pass cipher text and return the plain text by Nostr secret key. You should always read the public key without using cache just before sign/encrypt/decrypt, as the user may change their primary key without notifying you. During the execution process, an internal authorization check is performed similar to browser.ssi.askConsent.

decryptWithCallback()

Callback type of decrypt.

encrypt()

Pass plain text and return the cipher text by Nostr secret key. You should always read the public key without using cache just before sign/encrypt/decrypt, as the user may change their primary key without notifying you. During the execution process, an internal authorization check is performed similar to browser.ssi.askConsent.

encryptWithCallback()

Callback type of encrypt.

getPublicKey()

Return public key set as primary currently. During the execution process, an internal authorization check is performed similar to browser.ssi.askConsent.

getPublicKeyWithCallback()

Callback type of getPublicKey.

removeEventListener()

sign()

Pass message and return the signature by Nostr secret key. You should always read the public key without using cache just before sign/encrypt/decrypt, as the user may change their primary key without notifying you. During the execution process, an internal authorization check is performed similar to browser.ssi.askConsent.

signWithCallback()

Callback type of sign.

ssi.nostr.NostrSignType

Implementation list of Nostr signature spec.

Type

literal

Values

signEvent

literal.

ssi.nostr.NostrEncryptType

Implementation list of Nostr encyption spec.

Type

union

Values

nip04

literal.

nip44

literal.

ssi.nostr.NostrDecryptType

Implementation list of Nostr encyption spec.

Type

union

Values

nip04

literal.

nip44

literal.

ssi.nostr.getPublicKey()

Return public key set as primary currently. During the execution process, an internal authorization check is performed similar to browser.ssi.askConsent.

Syntax

const promiseValue = await window.ssi.nostr.getPublicKey(
	options, // optional object
)

Parameters

options(optional)

object. Not implemented

Return value

A Promise that will be fulfilled with a string of public key.

Exceptions

Throw error If failed to get public key.

Examples

Getting public key in NIP-07

const pubkey = await window.ssi.nostr.getPublicKey()
if (!pubkey) {
  throw new Error("Failed to get public key");
}

console.log(pubkey)
// "3327e31cfbef92d143c699e1559e207d977639303d81bb132d9541bff99af3b4"

ssi.nostr.getPublicKeyWithCallback()

Callback type of getPublicKey.

Syntax

 window.ssi.nostr.getPublicKeyWithCallback(
	callback, // object
	options, // optional object
)

Parameters

callback

object. A reference to a function that should be called in the near future, when the result is returned. The callback function is passed two arguments - 1. Error object if failed otherwise null, 2. The resulting public key.

error

Error.

publicKey

string.

options(optional)

object. Not implemented

Return value

None (undefined).

Examples

Getting public key in NIP-07

const callback = (error, pubkey) => {
  if (error) {
    throw new Error("Failed to get public key");
  }

  console.log(pubkey)
}
window.ssi.nostr.getPublicKeyWithCallback(callback)

// callback result
// "3327e31cfbef92d143c699e1559e207d977639303d81bb132d9541bff99af3b4"

In the WebExtension on Firefox

When you care about security and privacy, combining withCallback method with Xray Vision can help prevent eavesdropping via postMessage and prototype chain pollution, with some trade-offs. See also “Share objects with page scripts”.

// In content-script

function getPublicKey() {
  return window.wrappedJSObject.ssi.nostr.getPublicKeyWithCallback((error, pubkey) => {
    if (error) {
      throw new Error("Failed to get public key");
    }

    console.log(pubkey)
  });
}
window.wrappedJSObject.nostr.getPublicKey = exportFunction(getPublicKey, window);


// In page-script

const pubkey = await window.nostr.getPublicKey()

ssi.nostr.sign()

Pass message and return the signature by Nostr secret key. You should always read the public key without using cache just before sign/encrypt/decrypt, as the user may change their primary key without notifying you. During the execution process, an internal authorization check is performed similar to browser.ssi.askConsent.

Syntax

const promiseValue = await window.ssi.nostr.sign(
	message, // string
	options, // object
)

Parameters

message

string. The message to sign. If it’s not a string it must be stringified.

options

object. Direction about sign detail

type

signEvent. The signature spec. e.g., ‘signEvent’

Return value

A Promise that will be fulfilled with a string of resulting signature.

Exceptions

Throw error If failed to sign.

Examples

Signing event in NIP-07

See also the spec.

const event = {
  kind: 1,
  content: "learning curve proceeds, API and DB schema changed largely. It's time to write document! \nDon't do it before developing except for spec summary and sequence :)",
  created_at: 1737375898,
  pubkey: "3589b793b977c4f025175afd792e7c51d26ef683b45cbc66c56c4d14ad53847e",
  tags: [],
}
const eventHash = bytesToHex(
  sha256(new TextEncoder().encode(JSON.stringify([
    0,
    event.pubkey,
    event.created_at,
    event.kind,
    event.tags,
    event.content,
  ])))
);
const signature = await window.ssi.nostr.sign(
  eventHash,
  {
    type: "signEvent",
  },
)
if (!signature) {
  throw new Error("Failed to sign");
}

console.log(signature)
// "4034db40469721e4a5b95722a695bf943131cfab466f1a7f5a6aa70a3f8237dbacf08e06cc6a3f8dbe314313359450b64d75806dfd2e0bb7573ea6e68f43aa86"

ssi.nostr.signWithCallback()

Callback type of sign.

Syntax

 window.ssi.nostr.signWithCallback(
	message, // string
	callback, // object
	options, // object
)

Parameters

message

string. The message to sign. If it’s not a string it must be stringified.

callback

object. A reference to a function that should be called in the near future, when the result is returned. The callback function is passed two arguments - 1. Error object if failed otherwise null, 2. The resulting signature.

error

Error.

signature

string.

options

object. Direction about sign detail

type

signEvent. e.g., ‘signEvent’

Return value

None (undefined).

Examples

Signing event in NIP-07

See also the spec.

const event = {
  kind: 1,
  content: "learning curve proceeds, API and DB schema changed largely. It's time to write document! \nDon't do it before developing except for spec summary and sequence :)",
  created_at: 1737375898,
  pubkey: "3589b793b977c4f025175afd792e7c51d26ef683b45cbc66c56c4d14ad53847e",
  tags: [],
}
const eventHash = bytesToHex(
  sha256(new TextEncoder().encode(JSON.stringify([
    0,
    event.pubkey,
    event.created_at,
    event.kind,
    event.tags,
    event.content,
  ])))
);

const callback = (error, signature) => {
  if (error) {
    throw new Error("Failed to sign");
  }

  console.log(signature)
}
window.ssi.nostr.signWithCallback(
  eventHash,
  callback,
  {
    type: "signEvent",
  },
)

// callback result
// "4034db40469721e4a5b95722a695bf943131cfab466f1a7f5a6aa70a3f8237dbacf08e06cc6a3f8dbe314313359450b64d75806dfd2e0bb7573ea6e68f43aa86"

In the WebExtension on Firefox

When you care about security and privacy, combining withCallback method with Xray Vision can help prevent eavesdropping via postMessage and prototype chain pollution, with some trade-offs. See also “Share objects with page scripts”.

// In content-script

function signEvent(event) {
  const signedEvent = { ...event };
  let eventHash = "";
  return new window.Promise((resolve, reject) => {
    // Attach your holding public key to verify it is the same as the current primary key.
    window.wrappedJSObject.ssi.nostr.getPublicKeyWithCallback(
      exportFunction((error, pubkey) => {
        if (error) {
          reject(error);
        }
        signedEvent.pubkey = pubkey;
        eventHash = bytesToHex(
          sha256(new window.TextEncoder().encode(serializeEvent(signedEvent)))
        );
        window.wrappedJSObject.ssi.nostr.signWithCallback(
          window.JSON.stringify(signedEvent),
          exportFunction((error, signature) => {
            if (error) {
              reject(error);
            }
            signedEvent.id = eventHash;
            signedEvent.sig = signature;
            resolve(cloneInto(signedEvent, window));
          }, window),
          cloneInto(
            {
              type: "signEvent",
            },
            window
          )
        );
        XPCNativeWrapper(window.wrappedJSObject.ssi);
      }, window)
    );
    XPCNativeWrapper(window.wrappedJSObject.ssi);
  });
}
window.wrappedJSObject.nostr.signEvent = exportFunction(signEvent, window);


// In page-script

const singedEvent = await window.nostr.signEvent({kind:1...})

ssi.nostr.encrypt()

Pass plain text and return the cipher text by Nostr secret key. You should always read the public key without using cache just before sign/encrypt/decrypt, as the user may change their primary key without notifying you. During the execution process, an internal authorization check is performed similar to browser.ssi.askConsent.

Syntax

const promiseValue = await window.ssi.nostr.encrypt(
	plaintext, // string
	options, // object
)

Parameters

plaintext

string. The message to sign. If it’s not a string it must be stringified.

options

object. Direction about sign detail

pubkey(optional)

string. The conversation partner’s public key. If type is ‘nip04’ or ‘nip44’, then this is required.

type

NostrEncryptType. The encryption spec. e.g., ‘nip04’, ‘nip44’

version(optional)

string. The version to define encryption algorithms if the type is ‘nip44’.

Return value

A Promise that will be fulfilled with a string of resulting signature.

Exceptions

Throw error If failed to encrypt.

Examples

Encryption in NIP-44

See also the spec.

const ciphertext = await window.ssi.nostr.encrypt(
  "The computer can be used as a tool to liberate and protect people, rather than to control them.",
  {
    type: "nip44",
    pubkey: "3327e31cfbef92d143c699e1559e207d977639303d81bb132d9541bff99af3b4"
  }
);
if (!ciphertext) {
  throw new Error("Failed to encrypt");
}

console.log(ciphertext)
// "AkeXqSWNnU7VrlEUHnnGIs9rqXwHLFVxCsfQTRLbERVWh6fWJqfaRw/BC+cFgtfzPSle1csyfdJ+qf/xaCVmVQ2tXPQg6jw9EHwZxNUwz1EJYZStRo6uCXRnvXraMrPfd4Gx046tHyJ+KJIKUGXOFlWtyni+H+Kr151jvxt0PW5O48AMTxfos3/GxY/EF0yWwsJ8JG82JBEDrmzAz4ph8iXbJg=="

ssi.nostr.encryptWithCallback()

Callback type of encrypt.

Syntax

 window.ssi.nostr.encryptWithCallback(
	plaintext, // string
	callback, // object
	options, // object
)

Parameters

plaintext

string. The message to sign. If it’s not a string it must be stringified.

callback

object. A reference to a function that should be called in the near future, when the result is returned. The callback function is passed two arguments - 1. Error object if failed otherwise null, 2. The resulting ciphertext.

error

Error.

ciphertext

string.

options

object. Direction about sign detail

pubkey(optional)

string. The conversation partner’s public key. If type is ‘nip04’ or ‘nip44’, then this is required.

type

NostrEncryptType. The encryption spec. e.g., ‘nip04’, ‘nip44’

version(optional)

string. The version to define encryption algorithms if the type is ‘nip44’.

Return value

None (undefined).

Examples

Encryption in NIP-44

See also the spec.

const callback = (error, ciphertext) => {
  if (error) {
    throw new Error("Failed to encrypt");
  }

  console.log(ciphertext)
}
window.ssi.nostr.encryptWithCallback(
  "The computer can be used as a tool to liberate and protect people, rather than to control them.",
  callback,
  {
    type: "nip44",
    pubkey: "3327e31cfbef92d143c699e1559e207d977639303d81bb132d9541bff99af3b4"
  }
);

// callback result
// "AkeXqSWNnU7VrlEUHnnGIs9rqXwHLFVxCsfQTRLbERVWh6fWJqfaRw/BC+cFgtfzPSle1csyfdJ+qf/xaCVmVQ2tXPQg6jw9EHwZxNUwz1EJYZStRo6uCXRnvXraMrPfd4Gx046tHyJ+KJIKUGXOFlWtyni+H+Kr151jvxt0PW5O48AMTxfos3/GxY/EF0yWwsJ8JG82JBEDrmzAz4ph8iXbJg=="

In the WebExtension on Firefox

When you care about security and privacy, combining withCallback method with Xray Vision can help prevent eavesdropping via postMessage and prototype chain pollution, with some trade-offs. See also “Share objects with page scripts”.

// In content-script

function nip44Encrypt(pubkey, plaintext) {
  return new window.Promise((resolve, reject) => {
    window.wrappedJSObject.ssi.nostr.encryptWithCallback(
      plaintext,
      exportFunction((error, ciphertext) => {
        if (error) {
          reject(error);
        }
        resolve(ciphertext);
      }, window),
      cloneInto(
        {
          type: "nip44",
          pubkey,
        },
        window
      )
    );
    XPCNativeWrapper(window.wrappedJSObject.ssi);
  });
}
window.wrappedJSObject.nostr.nip44.encrypt = exportFunction(nip44Encrypt, window);


// In page-script

const ciphertext = await window.nostr.nip44.encrypt(pubkey, plaintext)

ssi.nostr.decrypt()

Pass cipher text and return the plain text by Nostr secret key. You should always read the public key without using cache just before sign/encrypt/decrypt, as the user may change their primary key without notifying you. During the execution process, an internal authorization check is performed similar to browser.ssi.askConsent.

Syntax

const promiseValue = await window.ssi.nostr.decrypt(
	ciphertext, // string
	options, // object
)

Parameters

ciphertext

string. The cipher text to decrypt

options

object. Direction about sign detail

pubkey(optional)

string. The conversation partner’s public key. If type is ‘nip04’ or ‘nip44’, then this is required.

type

NostrDecryptType. The encryption spec. e.g., ‘nip04’, ‘nip44’

version(optional)

string. The version to define encryption algorithms if the type is ‘nip44’.

Return value

A Promise that will be fulfilled with a string of resulting signature.

Exceptions

Throw error If failed to decrypt.

Examples

Decryption in NIP-44

See also the spec.

const plaintext = await window.ssi.nostr.decrypt(
  "AkeXqSWNnU7VrlEUHnnGIs9rqXwHLFVxCsfQTRLbERVWh6fWJqfaRw/BC+cFgtfzPSle1csyfdJ+qf/xaCVmVQ2tXPQg6jw9EHwZxNUwz1EJYZStRo6uCXRnvXraMrPfd4Gx046tHyJ+KJIKUGXOFlWtyni+H+Kr151jvxt0PW5O48AMTxfos3/GxY/EF0yWwsJ8JG82JBEDrmzAz4ph8iXbJg==",
  {
    type: "nip44",
    pubkey: "3327e31cfbef92d143c699e1559e207d977639303d81bb132d9541bff99af3b4"
  }
);
if (!plaintext) {
  throw new Error("Failed to decrypt");
}

console.log(plaintext)
// "The computer can be used as a tool to liberate and protect people, rather than to control them."

ssi.nostr.decryptWithCallback()

Callback type of decrypt.

Syntax

 window.ssi.nostr.decryptWithCallback(
	ciphertext, // string
	callback, // object
	options, // object
)

Parameters

ciphertext

string. The cipher text to decrypt

callback

object. A reference to a function that should be called in the near future, when the result is returned. The callback function is passed two arguments - 1. Error object if failed otherwise null, 2. The resulting plaintext.

error

Error.

plaintext

string.

options

object. Direction about sign detail

pubkey(optional)

string. The conversation partner’s public key. If type is ‘nip04’ or ‘nip44’, then this is required.

type

NostrDecryptType. The encryption spec. e.g., ‘nip04’, ‘nip44’

version(optional)

string. The version to define encryption algorithms if the type is ‘nip44’.

Return value

None (undefined).

Examples

Decryption in NIP-44

See also the spec.

const callback = (error, plaintext) => {
  if (error) {
    throw new Error("Failed to decrypt");
  }

  console.log(plaintext)
}
window.ssi.nostr.decryptWithCallback(
  "AkeXqSWNnU7VrlEUHnnGIs9rqXwHLFVxCsfQTRLbERVWh6fWJqfaRw/BC+cFgtfzPSle1csyfdJ+qf/xaCVmVQ2tXPQg6jw9EHwZxNUwz1EJYZStRo6uCXRnvXraMrPfd4Gx046tHyJ+KJIKUGXOFlWtyni+H+Kr151jvxt0PW5O48AMTxfos3/GxY/EF0yWwsJ8JG82JBEDrmzAz4ph8iXbJg==",
  callback,
  {
    type: "nip44",
    pubkey: "3327e31cfbef92d143c699e1559e207d977639303d81bb132d9541bff99af3b4"
  }
);

// callback result
// "The computer can be used as a tool to liberate and protect people, rather than to control them."

In the WebExtension on Firefox

When you care about security and privacy, combining withCallback method with Xray Vision can help prevent eavesdropping via postMessage and prototype chain pollution, with some trade-offs. See also “Share objects with page scripts”.

// In content-script

function nip44Decrypt(pubkey, ciphertext) {
  return new window.Promise((resolve, reject) => {
    window.wrappedJSObject.ssi.nostr.decryptWithCallback(
      ciphertext,
      exportFunction((error, plaintext) => {
        if (error) {
          reject(error);
        }
        resolve(plaintext);
      }, window),
      cloneInto(
        {
          type: "nip44",
          pubkey,
        },
        window
      )
    );
    XPCNativeWrapper(window.wrappedJSObject.ssi);
  });
}
window.wrappedJSObject.nostr.nip44.decrypt = exportFunction(nip44Decrypt, window);


// In page-script

const plaintext = await window.nostr.nip44.decrypt(pubkey, ciphertext)

ssi.nostr.addEventListener()

Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.

The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options’s capture.

When set to true, options’s capture prevents callback from being invoked when the event’s eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event’s eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event’s eventPhase attribute value is AT_TARGET.

When set to true, options’s passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.

When set to true, options’s once indicates that the callback will only be invoked once after which the event listener will be removed.

If an AbortSignal is passed for options’s signal, then the event listener will be removed when signal is aborted.

The event listener is appended to target’s event listener list and is not appended if it has the same type, callback, and capture.

MDN Reference

ssi.nostr.removeEventListener()

Removes the event listener in target’s event listener list with the same type, callback, and options.

MDN Reference

browser.ssi

Examples

browser.ssi.searchCredentialsWithoutSecret({
  protocolName,
  credentialName,
})

APIs

ssi

ssi.nostr

ssi

That’s to empower individuals on the self-sovereign path.

browser.ssi is a powerful API (in Chrome, it would be named chrome.ssi), bridging tasks related to credentials, such as signing/decrypting, between the internal module and user land. It also provides the state of settings while prioritizing privacy and security, allowing users to choose whether to make them open.

Required Permissions

['ssi']

Types

Credential

A credential object picked selectively from nsICredentialInfo and nsICredentialMetaInfo in the SSI store service.

SearchCriteria

Criteria to search credentials. If you want a full search, explicitly set primary to false.

DialogInfo

Option parameters to build Auth dialog

Functions

searchCredentialsWithoutSecret

Return the requested credentials without secrets such like secret key and private setting. During the execution process, an internal authorization check is performed similar to browser.ssi.askConsent.

askConsent

Ask the user whether to give a permission to the requsting web app

askConsentChild

Ask the user whether to give a permission to the requsting web app

ssi.Credential

A credential object picked selectively from nsICredentialInfo and nsICredentialMetaInfo in the SSI store service.

Type

protocolName

string. The protocol name

credentialName

string. The credential name

identifier (optional)

string. The identifier

primary

boolean. The primary flag

ssi.DialogInfo

Option parameters to build Auth dialog

Type

caption (optional)

string. A text description of the authentication. Base title is generated by the system, so add additional information as needed.

submission (optional)

string. Reference data for considering auth. Evidence of signed messages, etc. are generated by the system, so add additional information as needed.

enforce (optional)

boolean. Set to true if you want to perform auth dialog even if trusted site or password authorization is valid.

ssi.SearchCriteria

Criteria to search credentials. If you want a full search, explicitly set primary to false.

Type

protocolName (optional)

string. The protocol name to search

credentialName (optional)

string. The credential name to search

primary (optional)

boolean. The primary flag to search

ssi.askConsent()

Ask the user whether to give a permission to the requsting web app

This is an asynchronous function that returns a Promise.

Syntax

const booleanValue = await browser.ssi.askConsent(
	tabId, // integer
	protocolName, // string
	credentialName, // string
	dialogOptions, // optional object
)

Parameters

tabId

integer. This is tabs.Tab.id. See also https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/Tab#id

protocolName

string. The protocol name targeted

credentialName

string. The credential name targeted

dialogOptions (optional)

DialogInfo. Parameters to build Auth dialog

Return value

A Promise that will be fulfilled with a boolean value to indicate the authorization result.

Examples

Getting consent

// Authorization will be performed using the secret currently set as primary
// within the specified protocol name and credential name.
const permitted = await browser.ssi.askConsent(
  1,
  "nostr", // protocol name
  "nsec", // credential name
  {
    // A text description displayed on Auth dialog. Base title (kind such as sign/encrypt
    // and site URL) is generated by the system, so add additional information as needed.
    caption: "Offer from ABC Company"
  }
)
if (permitted) {
  // Go to next
}

Case for mandatory

Even when a authorization is still valid, you can require re-authorization to the user. It would be useful at critical times.

const isAuthorized = await browser.ssi.askConsent(
  1,
  "nostr",
  "nsec",
  {
    enforce: true
  }
)
if (!isAuthorized) {
  throw new Error("Rejected.")
}

ssi.searchCredentialsWithoutSecret()

Return the requested credentials without secrets such like secret key and private setting. During the execution process, an internal authorization check is performed similar to browser.ssi.askConsent.

This is an asynchronous function that returns a Promise.

Syntax

const arrayValue = await browser.ssi.searchCredentialsWithoutSecret(
	tabId, // integer
	criteria, // object
	dialogOption, // optional object
)

Parameters

tabId

integer. This is tabs.Tab.id. See also https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/Tab#id

criteria

SearchCriteria. Criteria to search credentials

dialogOption (optional)

DialogInfo. Parameters to build Auth dialog

Return value

A Promise that will be fulfilled with array of ssi.Credential.

Examples

Serach store

Example of a full search for SSI store service. The return values are array of ssi.Credential.

const credentials = await browser.ssi.searchCredentialsWithoutSecret(
  1,
  {
    primary: false // explicitly set primary to false.
  }
)
store.set(credentials.map(credential => doSomething(credential)))

To get the current public key of the user:

const credentials = await browser.ssi.searchCredentialsWithoutSecret(
  1,
  {
    protocolName: "nostr",
    credentialName: "nsec",
    primary: true,
  }
)
const publicKey = credentials[0].identifier // format is "npub1..."

ssi.nostr

The browser.ssi subset for Nostr protocol. Requires ssi.nostr along with ssi to set permissions.

Required Permissions

['ssi', 'ssi.nostr']

Types

Preference

The preference values set by the user in about:selfsovereignindividual

Functions

getPrefs

Get preference’s values

sign

Pass message and return the signature by Nostr secret key. You should always read the public key without using cache just before sign/encrypt/decrypt, as the user may change their primary key without notifying you. During the execution process, an internal authorization check is performed similar to browser.ssi.askConsent.

encrypt

Pass plain text and return the cipher text by Nostr secret key. You should always read the public key without using cache just before sign/encrypt/decrypt, as the user may change their primary key without notifying you. During the execution process, an internal authorization check is performed similar to browser.ssi.askConsent.

decrypt

Pass cipher text and return the plain text by Nostr secret key. You should always read the public key without using cache just before sign/encrypt/decrypt, as the user may change their primary key without notifying you. During the execution process, an internal authorization check is performed similar to browser.ssi.askConsent.

Events

onPrimaryChanged

Fire when primary key changed

onPrefEnabledChanged

Fire when the preference value of selfsovereignindividual.nostr.enabled changed

ssi.nostr.Preference

The preference values set by the user in about:selfsovereignindividual

Type

enabled

boolean. Whether the user has ssi.nostr enabled.

ssi.nostr.getPrefs()

Get preference’s values

This is an asynchronous function that returns a Promise.

Syntax

const objectValue = await browser.ssi.nostr.getPrefs()

Parameters

None.

Return value

A Promise that will be fulfilled with a object of ssi.nostr.Preference. Returns Promise<null> if error.

Examples

You will get what you need. The return value is ssi.nostr.Preference.

const preferences = await browser.ssi.nostr.getPrefs()
store.set(preferences)

ssi.nostr.sign()

Pass message and return the signature by Nostr secret key. You should always read the public key without using cache just before sign/encrypt/decrypt, as the user may change their primary key without notifying you. During the execution process, an internal authorization check is performed similar to browser.ssi.askConsent.

This is an asynchronous function that returns a Promise.

Syntax

const stringValue = await browser.ssi.nostr.sign(
	tabId, // integer
	message, // string
	option, // object
	dialogOption, // optional object
)

Parameters

tabId

integer. This is tabs.Tab.id. See also https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/Tab#id

message

string. The message to sign. If it’s not a string it must be stringified.

option

object. Direction about sign detail

type

string. The signature spec. e.g., ‘signEvent’

dialogOption (optional)

ssi.DialogInfo. Parameters to build Auth dialog

Return value

A Promise that will be fulfilled with a string of resulting signature. Returns Promise<null> if error.

Examples

Signing event in NIP-07

See also the spec.

const event = {
  kind: 1,
  content: "learning curve proceeds, API and DB schema changed largely. It's time to write document! \nDon't do it before developing except for spec summary and sequence :)",
  created_at: 1737375898,
  pubkey: "3589b793b977c4f025175afd792e7c51d26ef683b45cbc66c56c4d14ad53847e",
  tags: [],
}
const eventHash = bytesToHex(
  sha256(new TextEncoder().encode(JSON.stringify([
    0,
    event.pubkey,
    event.created_at,
    event.kind,
    event.tags,
    event.content,
  ])))
);
const signature = await browser.ssi.nostr.sign(
  1,
  eventHash,
  {
    type: "signEvent",
  },
)
if (!signature) {
  throw new Error("Failed to sign");
}

console.log(signature)
// "4034db40469721e4a5b95722a695bf943131cfab466f1a7f5a6aa70a3f8237dbacf08e06cc6a3f8dbe314313359450b64d75806dfd2e0bb7573ea6e68f43aa86"

ssi.nostr.encrypt()

Pass plain text and return the cipher text by Nostr secret key. You should always read the public key without using cache just before sign/encrypt/decrypt, as the user may change their primary key without notifying you. During the execution process, an internal authorization check is performed similar to browser.ssi.askConsent.

This is an asynchronous function that returns a Promise.

Syntax

const stringValue = await browser.ssi.nostr.encrypt(
	tabId, // integer
	plaintext, // string
	option, // object
	dialogOption, // optional object
)

Parameters

tabId

integer. This is tabs.Tab.id. See also https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/Tab#id

plaintext

string. The plain text to encrypt

option

object. Direction about encryption detail

type

string. The encryption spec. e.g., ‘nip04’, ‘nip44’

pubkey (optional)

string. The conversation partner’s public key. If type is ‘nip04’ or ‘nip44’, then this is required.

version (optional)

string. The version to define encryption algorithms if the type is ‘nip44’.

dialogOption (optional)

ssi.DialogInfo. Parameters to build Auth dialog

Return value

A Promise that will be fulfilled with a string of the encrypted cipher text. Returns Promise<null> if error.

Examples

Encryption in NIP-44

See also the spec.

const ciphertext = await browser.ssi.nostr.encrypt(
  1,
  "The computer can be used as a tool to liberate and protect people, rather than to control them.",
  {
    type: "nip44",
    pubkey: "3327e31cfbef92d143c699e1559e207d977639303d81bb132d9541bff99af3b4"
  }
);
if (!ciphertext) {
  throw new Error("Failed to encrypt");
}

console.log(ciphertext)
// "AkeXqSWNnU7VrlEUHnnGIs9rqXwHLFVxCsfQTRLbERVWh6fWJqfaRw/BC+cFgtfzPSle1csyfdJ+qf/xaCVmVQ2tXPQg6jw9EHwZxNUwz1EJYZStRo6uCXRnvXraMrPfd4Gx046tHyJ+KJIKUGXOFlWtyni+H+Kr151jvxt0PW5O48AMTxfos3/GxY/EF0yWwsJ8JG82JBEDrmzAz4ph8iXbJg=="

ssi.nostr.decrypt()

Pass cipher text and return the plain text by Nostr secret key. You should always read the public key without using cache just before sign/encrypt/decrypt, as the user may change their primary key without notifying you. During the execution process, an internal authorization check is performed similar to browser.ssi.askConsent.

This is an asynchronous function that returns a Promise.

Syntax

const stringValue = await browser.ssi.nostr.decrypt(
	tabId, // integer
	ciphertext, // string
	option, // object
	dialogOption, // optional object
)

Parameters

tabId

integer. This is tabs.Tab.id. See also https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/Tab#id

ciphertext

string. The cipher text to decrypt

option

object. Direction about decryption detail

type

string. The encryption spec. e.g., ‘nip04’, ‘nip44’

pubkey (optional)

string. The conversation partner’s public key. If type is ‘nip04’ or ‘nip44’, then this is required.

version (optional)

string. The version to define encryption algorithms if the type is ‘nip44’.

dialogOption (optional)

ssi.DialogInfo. Parameters to build Auth dialog

Return value

A Promise that will be fulfilled with a string of the decrypted plain text. Returns Promise<null> if error.

Examples

Decryption in NIP-44

See also the spec.

const plaintext = await browser.ssi.nostr.decrypt(
  1,
  "AkeXqSWNnU7VrlEUHnnGIs9rqXwHLFVxCsfQTRLbERVWh6fWJqfaRw/BC+cFgtfzPSle1csyfdJ+qf/xaCVmVQ2tXPQg6jw9EHwZxNUwz1EJYZStRo6uCXRnvXraMrPfd4Gx046tHyJ+KJIKUGXOFlWtyni+H+Kr151jvxt0PW5O48AMTxfos3/GxY/EF0yWwsJ8JG82JBEDrmzAz4ph8iXbJg==",
  {
    type: "nip44",
    pubkey: "3327e31cfbef92d143c699e1559e207d977639303d81bb132d9541bff99af3b4"
  }
);
if (!plaintext) {
  throw new Error("Failed to decrypt");
}

console.log(plaintext)
// "The computer can be used as a tool to liberate and protect people, rather than to control them."

ssi.nostr.onPrefEnabledChanged

Fire when the preference value of selfsovereignindividual.nostr.enabled changed

Syntax

browser.ssi.nostr.onPrefEnabledChanged.addListener(listener)
browser.ssi.nostr.onPrefEnabledChanged.removeListener(listener)
browser.ssi.nostr.onPrefEnabledChanged.hasListener(listener)

Events have three functions:

addListener(listener) Adds a listener to this event.

removeListener(listener) Stop listening to this event. The listener argument is the listener to remove.

hasListener(listener) Check whether listener is registered for this event. Returns true if it is listening, false otherwise.

addListener syntax

Parameters

None.

Examples

Listening the value of selfsovereignindividual.nostr.enabled changed in about:config, update and notify it.

const onPrefEnabledChangedCallback = async () => {
  // Get the new value.
  const prefs = await browser.ssi.getPrefs()
  // Update store value
  store.prefs.enabled = prefs.enabled

  // Send the message to the contents
  const tabs = await browser.tabs.query()
  for (const tab of tabs) {
    browser.tabs
      .sendMessage(tab.id, {
        action: "providerChanged",
        args: { enabled: store.prefs.enabled },
      })
  }
}
browser.ssi.nostr.onPrefEnabledChanged.addListener(onPrefEnabledChangedCallback)

ssi.nostr.onPrimaryChanged

Fire when primary key changed

Syntax

browser.ssi.nostr.onPrimaryChanged.addListener(listener)
browser.ssi.nostr.onPrimaryChanged.removeListener(listener)
browser.ssi.nostr.onPrimaryChanged.hasListener(listener)

Events have three functions:

addListener(listener) Adds a listener to this event.

removeListener(listener) Stop listening to this event. The listener argument is the listener to remove.

hasListener(listener) Check whether listener is registered for this event. Returns true if it is listening, false otherwise.

addListener syntax

Parameters

None.

Examples

You can listen to this as a special event.

const onPrimaryChangedCallback = async () => {
  // Get the new primary key. If without authorization, auth dialog will be prompted.
  const credentials = await browser.ssi.searchCredentialsWithoutSecret({
    protocolName: "nostr",
    credentialName: "nsec",
    primary: true
  })
  const publicKey = decodeNpub(credentials[0].identifier)

  // Send the message to the contents
  const tabs = await browser.tabs.query()
  for (const tab of tabs) {
    browser.tabs
      .sendMessage(tab.id, {
        action: "accountChanged",
        args: { publicKey },
      })
  }
}
browser.ssi.nostr.onPrimaryChanged.addListener(onPrimaryChangedCallback)

core

core is an internal module and is not exposed, but the entities would sometimes appear in the API and on the setting page.

Types

nsiCredentialInfo

Source of ssi.Credential

nsICredentialMetaInfo

Source of ssi.Credential

nsICredentialInfo

This is described in XPIDL that is an Interface Description Language used to specify XPCOM interface classes.

/**
 * A credential object in the SelfSovereignIndividual.
 * See SsiStore.sys.mjs for the actual data example.
 */
interface nsICredentialInfo : nsISupports {

  /**
   * The freedom tech protocol name:
   * money, e.g. "bitcoin", "lightning", "liquid", "cashu", "fedimint"...
   * identity, e.g. "nostr", "did:dht"...
   * speech, e.g. "matrix", "signal"...
   */
  attribute AString protocolName;

  /**
   * The credential category for when there are multiple types of the same protocol:
   * e.g. "bip39", "lnc", "nsec"...
   */
  attribute AString credentialName;

  /**
   * If true, this credential has the top priority within the same
   * protocol, such as when inserted into a window object.
   */
  attribute boolean primary;

  /**
   * The cryptographic secret that is expected to be unique in the world:
   * e.g. secret key, seed phrase, pairing phrase....
   *
   * It provides a unique key within the protocol, but the same secret can be used across protocols
   * like between Bitcoin and Nostr. So, GUID or `protocolName + credentialName + secret`
   * should be used as unique key in the system.
   */
  attribute AString secret;

  /**
   * The identifier that identifies the user to others:
   * e.g. public key, user id, email, etc.
   */
  attribute AString identifier;

  /**
   * The website list for which this credential is trusted.
   * It is not only web app but also web extensions etc:
   * e.g. https://example, moz-extension://example
   *
   * The actual value is the array by JSON.stringify.
   */
  attribute AString trustedSites;

  /**
   * The website list for which this credential is interactively authorized,
   * using Primary Passowrd/OS Account Password.
   * It is not only web app but also web extensions etc:
   * e.g. https://example, moz-extension://example
   *
   * The actual value is the array by JSON.stringify.
   */
  attribute AString dialogicAuthorizedSites;

  /**
   * A box where you can freely put anything else you need for each credential.
   * Actually string generated by JSON.stringify.
   * e.g. '{"serverHost":"mail.box.lightning.today:443","localKey":"abc...","remoteKey":"xyz..."}'
   *
   * @note optional
   */
  attribute AString properties;

  /**
   * Unknown fields this client doesn't know about but will be roundtripped
   * for other clients to prevent data loss
   *
   * @note optional
   */
  attribute AString unknownFields;

  /**
   * Initialize a newly created nsICredentialInfo object.
   *
   * The arguments are the fields for the new object.
   */
  void init(in AString aProtocolName, in AString aCredentialName,
            in boolean aPrimary, in AString aSecret, in AString aIdentifier,
            in AString aTrustedSites, in AString aDialogicAuthorizedSites,
            [optional] in AString aProperties);

  /**
   * Test for strict equality with another nsICredentialInfo object.
   *
   * @param aCredential
   *        The other object to test.
   */
  boolean equals(in nsICredentialInfo aCredential);

  /**
   * Test for loose equivalency with another nsICredentialInfo object.
   *
   * @param aCredentialInfo
   *        The other object to test.
   */
  boolean matches(in nsICredentialInfo aCredential);

  /**
   * Create an identical copy of the credential, duplicating all of the credential's
   * nsICredentialInfo and nsICredentialMetaInfo properties.
   *
   * This allows code to be forwards-compatible, when additional properties
   * are added to nsICredentialMetaInfo (or nsICredentialInfo) in the future.
   */
  nsICredentialInfo clone();
};

nsICredentialMetaInfo

This is described in XPIDL that is an Interface Description Language used to specify XPCOM interface classes.

/**
 * An object containing metainfo for a credential stored by the ssi.
 *
 * Code using ssi can generally ignore this interface. When adding
 * credentials, default value will be created. When modifying credentials, these
 * properties will be unchanged unless a change is explicitly requested [by
 * using modifyCredential() with a nsIPropertyBag]. When deleting a credential or
 * comparing credentials, these properties are ignored.
 */
interface nsICredentialMetaInfo : nsISupports {
  /**
   * The GUID to uniquely identify the credential. This can be any arbitrary
   * string, but a format as created by nsIUUIDGenerator is recommended.
   * For example, "{d4e1a1f6-5ea0-40ee-bff5-da57982f21cf}"
   *
   * addCredential will generate a random value unless a value is provided.
   *
   * addCredential and modifyCredential will throw if the GUID already exists.
   */
  attribute AString guid;

  /**
   * The time, in Unix Epoch milliseconds, when the credential was first created.
   */
  attribute unsigned long long timeCreated;

  /**
   * The time, in Unix Epoch milliseconds, when the credential was last submitted.
   */
  attribute unsigned long long timeLastUsed;

  /**
   * The time, in Unix Epoch milliseconds, when the secret was last modified.
   */
  attribute unsigned long long timeSecretChanged;

  /**
   * The number of times the credential was submitted.
   */
  attribute unsigned long timesUsed;
};

Current Limitations

These are things that, althogh we recoginize as problem, we would require modifying the Firefox sources beyond components for Self-Sovereign Individual, or changing the standards. We will appreciate any help to fix them.

TabId is unreliable

With browser.ssi, we use TabId to verify whether the tab app matches with authorization states.
However, browser.ssi must rely on the extension app passing in the TabId to get the tab context, which creates some problems.
One of the problems is that the TabId is not something that cannot be guessed like UUID but just an integer, so it can be faked. For example, an tab app the user requests is working with TabId 1, but third party extension can pass through TabId 2 which is valid for the another tab app. This allows for spoofing and can be a security vulnerability.
Another problem is that it is not possible for browser.ssi to distinguish between events that occur inside the browser and requests from tab apps. This becomes a problem when you want to bypass the authorization API because there is no tab context after catching an event from inside the browser.

This problem is tracked as issue #2.

OS password dialog cannot be independently displayed against multiple credentials in a single call

For Mac and Windows, password authorization is done using the password of the OS account that the user is currently logged in as.
If you queue to independently authorize multiple credentials at once in browser.ssi and try to add different captions to each dialog, subsequent dialogs will be displayed with the information from the first dialog.

This problem is tracked as issue #3.

MIT License

Copyright (c) 2024 T2 a.k.a teatwo

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.