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:
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:
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
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
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):
- Generate a random 32-byte
content_keyand a 12-bytenonce_ct, and encrypt the payload once with AES-256-GCM undercontent_key. - For each recipient device, generate an ephemeral X25519 keypair, compute
shared = X25519(eph_sk, device_pk), derivekek = HKDF-SHA256(shared, salt=nonce_ct, info="oc-lock/v2/kek:" || device_id), and wrapcontent_keyunderkekwith AES-256-GCM. - Canonicalize the envelope and set its
idto the SHA-256 of the canonical bytes withsig.valueemptied. - The sender signs the
idwith 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
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):
- Recompute the envelope
idfrom its canonical bytes and reject a mismatch. - Verify the sender's BIP-322 signature over
idforfrom.address, and reject if it fails. - Find the recipient entry matching the local
device_id. - Recompute
shared = X25519(device_sk, eph_pk)from that entry'seph_pk, derivekek = HKDF-SHA256(shared, salt=nonce_ct, info="oc-lock/v2/kek:" || device_id), and unwrapcontent_keywith AES-256-GCM. - 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
- Envelope format — the exact JSON shape, canonicalization rule, fields a validator must check
- Device keys — generation, binding, revocation, rotation
- Security — OC Lock specifics — envelope replay, compromised device recovery, forward secrecy tradeoffs