Skip to content
On this page

How OC Lock works

Four steps — two recipient-side, two sender-side. End-to-end.

1. Recipient registers a deviceLink to this section

The recipient generates an X25519 keypair, builds a canonical binding statement, and signs it with BIP-322 from their Bitcoin address:

Code
oc-lock:device-bind:v3
address: bc1qbob...
device_pk: <32-byte X25519 public key, hex>
nostr_pk: <the device's derived Nostr pubkey, hex>
device_id: <16 random bytes, hex>
created_at: 2026-04-24T06:47:29.977Z

Signature + binding are wrapped as a kind-30078 Nostr event with d tag oc-lock:device:<bc1qbob...> (addressable, replaceable by the same pubkey) and published.

Code:

TypeScript
import {
    buildBindingStatement,
    deriveNostrKey,
    generateDeviceKey,
} from '@orangecheck/lock-device';

declare function walletSignBIP322(message: string): Promise<string>; // your wallet's BIP-322 signer

const { device_sk, device_pk, device_id, created_at } = generateDeviceKey();

const statement = buildBindingStatement({
    address: 'bc1qbob...',
    device_pk,
    nostr_pk: deriveNostrKey(device_sk).nostrPk,
    device_id,
    created_at,
});

const signature = await walletSignBIP322(statement);
// Sign and publish as a kind-30078 event: see Device keys

The device secret (device_sk) stays on the recipient's device. Never leaves. If it does, that device's envelopes are compromised.

2. Sender looks up the recipientLink to this section

TypeScript
import { verifySignature } from '@orangecheck/bip322';
import {
    authorizedDevices,
    DEVICE_KIND,
    liveDevices,
    verifyDeviceRecords,
} from '@orangecheck/lock-device';
import { queryEvents } from '@orangecheck/nostr-core';

// One page from each relay. Before sealing, page each relay and check the
// read floor (below).
const { events } = await queryEvents({
    kinds: [DEVICE_KIND],
    '#d': ['oc-lock:device:bc1qbob...'],
});
// Records with a valid Nostr event, a statement naming this address, matching
// tags and a BIP-322 signature by the address.
const verified = await verifyDeviceRecords(events, 'bc1qbob...', {
    verifyBip322: ({ address, message, signature }) =>
        verifySignature(address, message, signature),
});
// The binds no revocation retires, from any relay and any key (SPEC §3.5).
const live = liveDevices(verified);
// One recipient per device: a device can carry more than one live record.
const devices = [...new Map(live.map((d) => [d.device_id, d])).values()];
// Each device.device_pk is a 32-byte X25519 public key we'll encrypt to.

// Only to deliver over Nostr: the keys that are each device's inbox (SPEC §3.4).
const inboxes = authorizedDevices(live);

The sender MUST verify each record's BIP-322 signature before using it; a record whose signature fails is forged. liveDevices then applies every revocation among the verified records, so a revoked device gets nothing new. Seal to devices, not to inboxes: a device whose record names no inbox key still receives the envelope by link.

One queryEvents call is not enough to rule out a revocation: a relay answers newest first, up to its own cap. A sender MUST page each relay with until until a page comes back short, and seal only when the read floor answered in full (four of the default five relays) and none was cut off. Otherwise it does not seal, and reports E_RELAY_UNREACHABLE (spec §3.5).

3. Sender sealsLink to this section

TypeScript
import type { DeviceRecord } from '@orangecheck/lock-core';

import { seal } from '@orangecheck/lock-core';

declare const devices: DeviceRecord[]; // from step 2
declare function walletSignBIP322(message: string): Promise<string>; // your wallet's BIP-322 signer

const envelope = await seal({
    payload: new TextEncoder().encode('hello bob'),
    sender: {
        address: 'bc1qalice...',
        signMessage: async (msg) => walletSignBIP322(msg),
    },
    recipients: devices.map((d) => ({
        address: d.address,
        device_id: d.device_id,
        device_pk: d.device_pk,
    })),
});

Inside seal() (spec §4.2):

  1. Generate a random 32-byte content_key and a 12-byte nonce_ct, and encrypt the payload once with AES-256-GCM under content_key.
  2. For each recipient device, generate an ephemeral X25519 keypair, compute shared = X25519(eph_sk, device_pk), derive kek = HKDF-SHA256(shared, salt=nonce_ct, info="oc-lock/v2/kek:" || device_id), and wrap content_key under kek with AES-256-GCM.
  3. Canonicalize the envelope and set its id to the SHA-256 of the canonical bytes with sig.value emptied.
  4. The sender signs the id with BIP-322, binding the envelope to their Bitcoin address.

The result is a self-contained JSON blob. Send it over any transport.

4. Recipient unsealsLink to this section

TypeScript
import type { LockEnvelope } from '@orangecheck/lock-core';

import { unseal } from '@orangecheck/lock-core';

declare const envelope: LockEnvelope; // as the sender sent it
declare const device_id: string, device_sk: Uint8Array; // this device's key, from step 1
declare function walletVerifyBIP322(
    message: string,
    signatureB64: string,
    address: string
): Promise<boolean>;

const { payload, sender, matchedDeviceId } = await unseal({
    envelope,
    device: { device_id, secretKey: device_sk },
    verifyBip322: async (msg, sig, addr) => walletVerifyBIP322(msg, sig, addr),
});

Inside unseal() (spec §4.3):

  1. Recompute the envelope id from its canonical bytes and reject a mismatch.
  2. Verify the sender's BIP-322 signature over id for from.address, and reject if it fails.
  3. Find the recipient entry matching the local device_id.
  4. Recompute shared = X25519(device_sk, eph_pk) from that entry's eph_pk, derive kek = HKDF-SHA256(shared, salt=nonce_ct, info="oc-lock/v2/kek:" || device_id), and unwrap content_key with AES-256-GCM.
  5. Decrypt the payload with content_key. A failed tag rejects the envelope.

On success, the recipient gets the plaintext + a verified sender address.

Why ephemeral sender keysLink to this section

Each envelope has a fresh (eph_sk, eph_pk) pair. The sender discards eph_sk after sealing. Consequences:

  • Ephemeral secrets are discarded. The sender's ephemeral secrets are gone, so they cannot reopen what was sealed to others. lock.ochk.io and chat.ochk.io also seal every send to the sender's own devices, though, so a compromised sender device key opens the messages it sent.
  • No sender-key rotation needed. The sender's Bitcoin address is the long-lived identifier; the X25519 key is throwaway.

There is NOT forward secrecy within a single envelope — if the recipient's device_sk is compromised, every envelope sent to that device_id is decryptable. Rotate device keys if you need that guarantee.

What's nextLink to this section