@orangecheck/lock-device 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OrangeCheck
+
+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.

package/README.md

@@ -0,0 +1,29 @@
+# @orangecheck/lock-device
+
+Device-key binding and Nostr kind-30078 directory publication helpers for [OC Lock](https://github.com/orangecheck/oc-lock-protocol).
+
+## Install
+
+```
+npm i @orangecheck/lock-device
+```
+
+## What this package does
+
+- Generates X25519 device keypairs used by recipients to receive sealed envelopes.
+- Builds canonical binding/revocation statements that a Bitcoin wallet signs via BIP-322.
+- Derives a Nostr Schnorr keypair deterministically from a device secret (so the same browser always publishes under a stable Nostr pubkey, without asking the user to manage Nostr keys).
+- Builds, finalizes, and parses kind-30078 addressable events keyed by `d: oc-lock:device:<btc-address>`.
+
+This package is WebCrypto-free: it works in Node and in the browser.
+
+## Exports
+
+- `generateDeviceKey()` — new `(device_sk, device_pk, device_id, created_at)`.
+- `buildBindingStatement({ address, device_pk, device_id, created_at })` — exact bytes per SPEC §3.2.
+- `buildRevocationStatement({ address, device_id, revoked_at })` — for explicit revocation.
+- `deriveNostrKey(deviceSk)` — deterministic `nostr_sk` from `device_sk` (HKDF).
+- `finalizeDeviceEvent({ ... bindingSigBase64, ... })` — returns a fully signed kind-30078 `NostrEvent`.
+- `parseDeviceEvent(event)` — extracts `{ address, device_pk, device_id, bindingStatement, bindingSigBase64, revoked }`.
+
+The caller is responsible for obtaining the BIP-322 signature from the user's wallet and for publishing / querying Nostr relays. See [`SPEC.md`](https://github.com/orangecheck/oc-lock-protocol/blob/main/SPEC.md) §3 for the normative device-binding rules.

package/dist/index.d.mts

@@ -0,0 +1,68 @@
+declare const DEVICE_KIND = 30078;
+declare const BINDING_VERSION = "v2";
+interface DeviceKeyPair {
+    device_id: string;
+    device_pk: string;
+    device_sk: Uint8Array;
+    created_at: string;
+}
+declare function generateDeviceKey(): DeviceKeyPair;
+declare function buildBindingStatement(params: {
+    address: string;
+    device_pk: string;
+    device_id: string;
+    created_at: string;
+}): string;
+declare function buildRevocationStatement(params: {
+    address: string;
+    device_id: string;
+    revoked_at: string;
+}): string;
+interface NostrEvent {
+    id: string;
+    pubkey: string;
+    created_at: number;
+    kind: number;
+    tags: string[][];
+    content: string;
+    sig: string;
+}
+declare function deriveNostrKey(deviceSk: Uint8Array): {
+    nostrSk: string;
+    nostrPk: string;
+};
+declare function buildDeviceEvent(params: {
+    address: string;
+    device_id: string;
+    device_pk: string;
+    bindingStatement: string;
+    bindingSigBase64: string;
+    createdAtUnix?: number;
+}): Omit<NostrEvent, 'id' | 'sig' | 'pubkey'> & {
+    pubkey?: undefined;
+};
+declare function signNostrEvent(event: Omit<NostrEvent, 'id' | 'sig'>, nostrSkHex: string): NostrEvent;
+declare function computeNostrEventId(event: Omit<NostrEvent, 'id' | 'sig'>): string;
+declare function finalizeDeviceEvent(params: {
+    deviceSk: Uint8Array;
+    address: string;
+    device_id: string;
+    device_pk: string;
+    bindingStatement: string;
+    bindingSigBase64: string;
+    createdAtUnix?: number;
+}): NostrEvent;
+interface ParsedDeviceEvent {
+    address: string;
+    device_id: string;
+    device_pk: string;
+    bindingStatement: string;
+    bindingSigBase64: string;
+    revoked: boolean;
+    createdAtUnix: number;
+    nostrPubkey: string;
+    eventId: string;
+}
+declare function parseDeviceEvent(event: NostrEvent): ParsedDeviceEvent;
+
+export { BINDING_VERSION, DEVICE_KIND, type DeviceKeyPair, type NostrEvent, type ParsedDeviceEvent, buildBindingStatement, buildDeviceEvent, buildRevocationStatement, computeNostrEventId, deriveNostrKey, finalizeDeviceEvent, generateDeviceKey, parseDeviceEvent, signNostrEvent };

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+declare const DEVICE_KIND = 30078;
+declare const BINDING_VERSION = "v2";
+interface DeviceKeyPair {
+    device_id: string;
+    device_pk: string;
+    device_sk: Uint8Array;
+    created_at: string;
+}
+declare function generateDeviceKey(): DeviceKeyPair;
+declare function buildBindingStatement(params: {
+    address: string;
+    device_pk: string;
+    device_id: string;
+    created_at: string;
+}): string;
+declare function buildRevocationStatement(params: {
+    address: string;
+    device_id: string;
+    revoked_at: string;
+}): string;
+interface NostrEvent {
+    id: string;
+    pubkey: string;
+    created_at: number;
+    kind: number;
+    tags: string[][];
+    content: string;
+    sig: string;
+}
+declare function deriveNostrKey(deviceSk: Uint8Array): {
+    nostrSk: string;
+    nostrPk: string;
+};
+declare function buildDeviceEvent(params: {
+    address: string;
+    device_id: string;
+    device_pk: string;
+    bindingStatement: string;
+    bindingSigBase64: string;
+    createdAtUnix?: number;
+}): Omit<NostrEvent, 'id' | 'sig' | 'pubkey'> & {
+    pubkey?: undefined;
+};
+declare function signNostrEvent(event: Omit<NostrEvent, 'id' | 'sig'>, nostrSkHex: string): NostrEvent;
+declare function computeNostrEventId(event: Omit<NostrEvent, 'id' | 'sig'>): string;
+declare function finalizeDeviceEvent(params: {
+    deviceSk: Uint8Array;
+    address: string;
+    device_id: string;
+    device_pk: string;
+    bindingStatement: string;
+    bindingSigBase64: string;
+    createdAtUnix?: number;
+}): NostrEvent;
+interface ParsedDeviceEvent {
+    address: string;
+    device_id: string;
+    device_pk: string;
+    bindingStatement: string;
+    bindingSigBase64: string;
+    revoked: boolean;
+    createdAtUnix: number;
+    nostrPubkey: string;
+    eventId: string;
+}
+declare function parseDeviceEvent(event: NostrEvent): ParsedDeviceEvent;
+
+export { BINDING_VERSION, DEVICE_KIND, type DeviceKeyPair, type NostrEvent, type ParsedDeviceEvent, buildBindingStatement, buildDeviceEvent, buildRevocationStatement, computeNostrEventId, deriveNostrKey, finalizeDeviceEvent, generateDeviceKey, parseDeviceEvent, signNostrEvent };

package/dist/index.js

@@ -0,0 +1,141 @@
+'use strict';
+
+var secp256k1 = require('@noble/curves/secp256k1');
+var lockCrypto = require('@orangecheck/lock-crypto');
+
+// src/index.ts
+var DEVICE_KIND = 30078;
+var BINDING_VERSION = "v2";
+function generateDeviceKey() {
+  const kp = lockCrypto.generateX25519KeyPair();
+  const deviceIdBytes = lockCrypto.randomBytesN(16);
+  return {
+    device_id: lockCrypto.hexEncode(deviceIdBytes),
+    device_pk: lockCrypto.hexEncode(kp.public),
+    device_sk: kp.secret,
+    created_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function buildBindingStatement(params) {
+  const lines = [
+    `oc-lock:device-bind:${BINDING_VERSION}`,
+    `address: ${params.address}`,
+    `device_pk: ${params.device_pk}`,
+    `device_id: ${params.device_id}`,
+    `created_at: ${params.created_at}`
+  ];
+  return lines.join("\n") + "\n";
+}
+function buildRevocationStatement(params) {
+  const lines = [
+    `oc-lock:device-revoke:${BINDING_VERSION}`,
+    `address: ${params.address}`,
+    `device_id: ${params.device_id}`,
+    `revoked_at: ${params.revoked_at}`
+  ];
+  return lines.join("\n") + "\n";
+}
+function deriveNostrKey(deviceSk) {
+  const sk = lockCrypto.hkdfSha256(
+    deviceSk,
+    lockCrypto.utf8Encode("oc-lock/v2/nostr-key"),
+    lockCrypto.utf8Encode("nostr-sk"),
+    32
+  );
+  const pk = secp256k1.schnorr.getPublicKey(sk);
+  return { nostrSk: lockCrypto.hexEncode(sk), nostrPk: lockCrypto.hexEncode(pk) };
+}
+function buildDeviceEvent(params) {
+  const tags = [
+    ["d", `oc-lock:device:${params.address}`],
+    ["addr", params.address],
+    ["device_id", params.device_id],
+    ["device_pk", params.device_pk],
+    ["alg", "x25519"],
+    ["binding_sig", params.bindingSigBase64]
+  ];
+  const created_at = params.createdAtUnix ?? Math.floor(Date.now() / 1e3);
+  return {
+    kind: DEVICE_KIND,
+    tags,
+    content: params.bindingStatement,
+    created_at
+  };
+}
+function signNostrEvent(event, nostrSkHex) {
+  const id = computeNostrEventId(event);
+  const sk = lockCrypto.hexDecode(nostrSkHex);
+  const sig = secp256k1.schnorr.sign(lockCrypto.hexDecode(id), sk);
+  return {
+    ...event,
+    id,
+    sig: lockCrypto.hexEncode(sig)
+  };
+}
+function computeNostrEventId(event) {
+  const serialized = JSON.stringify([
+    0,
+    event.pubkey,
+    event.created_at,
+    event.kind,
+    event.tags,
+    event.content
+  ]);
+  return lockCrypto.hexEncode(lockCrypto.sha256Bytes(lockCrypto.utf8Encode(serialized)));
+}
+function finalizeDeviceEvent(params) {
+  const { nostrSk, nostrPk } = deriveNostrKey(params.deviceSk);
+  const base = buildDeviceEvent({
+    address: params.address,
+    device_id: params.device_id,
+    device_pk: params.device_pk,
+    bindingStatement: params.bindingStatement,
+    bindingSigBase64: params.bindingSigBase64,
+    createdAtUnix: params.createdAtUnix
+  });
+  const withPubkey = { ...base, pubkey: nostrPk };
+  return signNostrEvent(withPubkey, nostrSk);
+}
+function parseDeviceEvent(event) {
+  if (event.kind !== DEVICE_KIND) {
+    throw new Error("not a device event (kind mismatch)");
+  }
+  const tag = (name) => {
+    for (const t of event.tags) {
+      if (t[0] === name && t.length > 1) return t[1] ?? null;
+    }
+    return null;
+  };
+  const address = tag("addr");
+  const device_id = tag("device_id");
+  const device_pk = tag("device_pk");
+  const binding_sig = tag("binding_sig");
+  if (!address || !device_id || !device_pk || !binding_sig) {
+    throw new Error("device event missing required tags");
+  }
+  return {
+    address,
+    device_id,
+    device_pk,
+    bindingStatement: event.content,
+    bindingSigBase64: binding_sig,
+    revoked: device_pk === "revoked",
+    createdAtUnix: event.created_at,
+    nostrPubkey: event.pubkey,
+    eventId: event.id
+  };
+}
+
+exports.BINDING_VERSION = BINDING_VERSION;
+exports.DEVICE_KIND = DEVICE_KIND;
+exports.buildBindingStatement = buildBindingStatement;
+exports.buildDeviceEvent = buildDeviceEvent;
+exports.buildRevocationStatement = buildRevocationStatement;
+exports.computeNostrEventId = computeNostrEventId;
+exports.deriveNostrKey = deriveNostrKey;
+exports.finalizeDeviceEvent = finalizeDeviceEvent;
+exports.generateDeviceKey = generateDeviceKey;
+exports.parseDeviceEvent = parseDeviceEvent;
+exports.signNostrEvent = signNostrEvent;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["generateX25519KeyPair","randomBytesN","hexEncode","hkdfSha256","utf8Encode","schnorr","hexDecode","sha256Bytes"],"mappings":"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","file":"index.js","sourcesContent":["// Device key binding and Nostr directory publication.\n// See SPEC.md §3.\n\nimport { schnorr } from '@noble/curves/secp256k1';\nimport {\n    generateX25519KeyPair,\n    hexDecode,\n    hexEncode,\n    hkdfSha256,\n    randomBytesN,\n    sha256Bytes,\n    utf8Encode,\n} from '@orangecheck/lock-crypto';\n\nexport const DEVICE_KIND = 30078;\nexport const BINDING_VERSION = 'v2';\n\nexport interface DeviceKeyPair {\n    device_id: string;\n    device_pk: string; // 32-byte hex\n    device_sk: Uint8Array; // 32 bytes\n    created_at: string; // iso8601\n}\n\nexport function generateDeviceKey(): DeviceKeyPair {\n    const kp = generateX25519KeyPair();\n    const deviceIdBytes = randomBytesN(16);\n    return {\n        device_id: hexEncode(deviceIdBytes),\n        device_pk: hexEncode(kp.public),\n        device_sk: kp.secret,\n        created_at: new Date().toISOString(),\n    };\n}\n\nexport function buildBindingStatement(params: {\n    address: string;\n    device_pk: string;\n    device_id: string;\n    created_at: string;\n}): string {\n    // Exact byte layout per SPEC §3.2. Each line ends with LF; no trailing LF\n    // beyond the last field's. Order is fixed.\n    const lines = [\n        `oc-lock:device-bind:${BINDING_VERSION}`,\n        `address: ${params.address}`,\n        `device_pk: ${params.device_pk}`,\n        `device_id: ${params.device_id}`,\n        `created_at: ${params.created_at}`,\n    ];\n    return lines.join('\\n') + '\\n';\n}\n\nexport function buildRevocationStatement(params: {\n    address: string;\n    device_id: string;\n    revoked_at: string;\n}): string {\n    const lines = [\n        `oc-lock:device-revoke:${BINDING_VERSION}`,\n        `address: ${params.address}`,\n        `device_id: ${params.device_id}`,\n        `revoked_at: ${params.revoked_at}`,\n    ];\n    return lines.join('\\n') + '\\n';\n}\n\n// ---------------------------------------------------------------------------\n// Nostr event helpers\n// ---------------------------------------------------------------------------\n\nexport interface NostrEvent {\n    id: string;\n    pubkey: string;\n    created_at: number;\n    kind: number;\n    tags: string[][];\n    content: string;\n    sig: string;\n}\n\n/**\n * Derive an ephemeral Nostr keypair from a device secret per SPEC §3.4.\n * Returns a 32-byte private key (hex).\n */\nexport function deriveNostrKey(deviceSk: Uint8Array): { nostrSk: string; nostrPk: string } {\n    const sk = hkdfSha256(\n        deviceSk,\n        utf8Encode('oc-lock/v2/nostr-key'),\n        utf8Encode('nostr-sk'),\n        32\n    );\n    const pk = schnorr.getPublicKey(sk);\n    return { nostrSk: hexEncode(sk), nostrPk: hexEncode(pk) };\n}\n\n/**\n * Build a kind-30078 addressable event announcing a device binding.\n * The caller must supply the BIP-322 signature produced by the user's Bitcoin\n * wallet (we cannot sign BIP-322 in this package — that requires a wallet).\n */\nexport function buildDeviceEvent(params: {\n    address: string;\n    device_id: string;\n    device_pk: string;\n    bindingStatement: string;\n    bindingSigBase64: string;\n    createdAtUnix?: number;\n}): Omit<NostrEvent, 'id' | 'sig' | 'pubkey'> & { pubkey?: undefined } {\n    const tags: string[][] = [\n        ['d', `oc-lock:device:${params.address}`],\n        ['addr', params.address],\n        ['device_id', params.device_id],\n        ['device_pk', params.device_pk],\n        ['alg', 'x25519'],\n        ['binding_sig', params.bindingSigBase64],\n    ];\n    const created_at = params.createdAtUnix ?? Math.floor(Date.now() / 1000);\n    return {\n        kind: DEVICE_KIND,\n        tags,\n        content: params.bindingStatement,\n        created_at,\n    } as unknown as Omit<NostrEvent, 'id' | 'sig' | 'pubkey'> & { pubkey?: undefined };\n}\n\n/**\n * Sign a Nostr event with a Schnorr key (derived via deriveNostrKey). Produces\n * the full NostrEvent with id and sig.\n */\nexport function signNostrEvent(\n    event: Omit<NostrEvent, 'id' | 'sig'>,\n    nostrSkHex: string\n): NostrEvent {\n    const id = computeNostrEventId(event);\n    const sk = hexDecode(nostrSkHex);\n    const sig = schnorr.sign(hexDecode(id), sk);\n    return {\n        ...event,\n        id,\n        sig: hexEncode(sig),\n    };\n}\n\nexport function computeNostrEventId(event: Omit<NostrEvent, 'id' | 'sig'>): string {\n    // Per NIP-01: id = sha256(utf8(JSON.stringify([0, pubkey, created_at, kind, tags, content]))).\n    // The array must be serialized in *exactly* this form with no whitespace.\n    const serialized = JSON.stringify([\n        0,\n        event.pubkey,\n        event.created_at,\n        event.kind,\n        event.tags,\n        event.content,\n    ]);\n    return hexEncode(sha256Bytes(utf8Encode(serialized)));\n}\n\n/**\n * Finalize a device event: derive Nostr key from device_sk, attach pubkey,\n * compute id, sign. Returns a fully-signed NIP-01 event ready to publish.\n */\nexport function finalizeDeviceEvent(params: {\n    deviceSk: Uint8Array;\n    address: string;\n    device_id: string;\n    device_pk: string;\n    bindingStatement: string;\n    bindingSigBase64: string;\n    createdAtUnix?: number;\n}): NostrEvent {\n    const { nostrSk, nostrPk } = deriveNostrKey(params.deviceSk);\n    const base = buildDeviceEvent({\n        address: params.address,\n        device_id: params.device_id,\n        device_pk: params.device_pk,\n        bindingStatement: params.bindingStatement,\n        bindingSigBase64: params.bindingSigBase64,\n        createdAtUnix: params.createdAtUnix,\n    });\n    const withPubkey = { ...base, pubkey: nostrPk } as Omit<NostrEvent, 'id' | 'sig'>;\n    return signNostrEvent(withPubkey, nostrSk);\n}\n\n// ---------------------------------------------------------------------------\n// Parsing\n// ---------------------------------------------------------------------------\n\nexport interface ParsedDeviceEvent {\n    address: string;\n    device_id: string;\n    device_pk: string;\n    bindingStatement: string;\n    bindingSigBase64: string;\n    revoked: boolean;\n    createdAtUnix: number;\n    nostrPubkey: string;\n    eventId: string;\n}\n\nexport function parseDeviceEvent(event: NostrEvent): ParsedDeviceEvent {\n    if (event.kind !== DEVICE_KIND) {\n        throw new Error('not a device event (kind mismatch)');\n    }\n    const tag = (name: string): string | null => {\n        for (const t of event.tags) {\n            if (t[0] === name && t.length > 1) return t[1] ?? null;\n        }\n        return null;\n    };\n    const address = tag('addr');\n    const device_id = tag('device_id');\n    const device_pk = tag('device_pk');\n    const binding_sig = tag('binding_sig');\n    if (!address || !device_id || !device_pk || !binding_sig) {\n        throw new Error('device event missing required tags');\n    }\n    return {\n        address,\n        device_id,\n        device_pk,\n        bindingStatement: event.content,\n        bindingSigBase64: binding_sig,\n        revoked: device_pk === 'revoked',\n        createdAtUnix: event.created_at,\n        nostrPubkey: event.pubkey,\n        eventId: event.id,\n    };\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,129 @@
+import { schnorr } from '@noble/curves/secp256k1';
+import { generateX25519KeyPair, randomBytesN, hexEncode, hkdfSha256, utf8Encode, hexDecode, sha256Bytes } from '@orangecheck/lock-crypto';
+
+// src/index.ts
+var DEVICE_KIND = 30078;
+var BINDING_VERSION = "v2";
+function generateDeviceKey() {
+  const kp = generateX25519KeyPair();
+  const deviceIdBytes = randomBytesN(16);
+  return {
+    device_id: hexEncode(deviceIdBytes),
+    device_pk: hexEncode(kp.public),
+    device_sk: kp.secret,
+    created_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function buildBindingStatement(params) {
+  const lines = [
+    `oc-lock:device-bind:${BINDING_VERSION}`,
+    `address: ${params.address}`,
+    `device_pk: ${params.device_pk}`,
+    `device_id: ${params.device_id}`,
+    `created_at: ${params.created_at}`
+  ];
+  return lines.join("\n") + "\n";
+}
+function buildRevocationStatement(params) {
+  const lines = [
+    `oc-lock:device-revoke:${BINDING_VERSION}`,
+    `address: ${params.address}`,
+    `device_id: ${params.device_id}`,
+    `revoked_at: ${params.revoked_at}`
+  ];
+  return lines.join("\n") + "\n";
+}
+function deriveNostrKey(deviceSk) {
+  const sk = hkdfSha256(
+    deviceSk,
+    utf8Encode("oc-lock/v2/nostr-key"),
+    utf8Encode("nostr-sk"),
+    32
+  );
+  const pk = schnorr.getPublicKey(sk);
+  return { nostrSk: hexEncode(sk), nostrPk: hexEncode(pk) };
+}
+function buildDeviceEvent(params) {
+  const tags = [
+    ["d", `oc-lock:device:${params.address}`],
+    ["addr", params.address],
+    ["device_id", params.device_id],
+    ["device_pk", params.device_pk],
+    ["alg", "x25519"],
+    ["binding_sig", params.bindingSigBase64]
+  ];
+  const created_at = params.createdAtUnix ?? Math.floor(Date.now() / 1e3);
+  return {
+    kind: DEVICE_KIND,
+    tags,
+    content: params.bindingStatement,
+    created_at
+  };
+}
+function signNostrEvent(event, nostrSkHex) {
+  const id = computeNostrEventId(event);
+  const sk = hexDecode(nostrSkHex);
+  const sig = schnorr.sign(hexDecode(id), sk);
+  return {
+    ...event,
+    id,
+    sig: hexEncode(sig)
+  };
+}
+function computeNostrEventId(event) {
+  const serialized = JSON.stringify([
+    0,
+    event.pubkey,
+    event.created_at,
+    event.kind,
+    event.tags,
+    event.content
+  ]);
+  return hexEncode(sha256Bytes(utf8Encode(serialized)));
+}
+function finalizeDeviceEvent(params) {
+  const { nostrSk, nostrPk } = deriveNostrKey(params.deviceSk);
+  const base = buildDeviceEvent({
+    address: params.address,
+    device_id: params.device_id,
+    device_pk: params.device_pk,
+    bindingStatement: params.bindingStatement,
+    bindingSigBase64: params.bindingSigBase64,
+    createdAtUnix: params.createdAtUnix
+  });
+  const withPubkey = { ...base, pubkey: nostrPk };
+  return signNostrEvent(withPubkey, nostrSk);
+}
+function parseDeviceEvent(event) {
+  if (event.kind !== DEVICE_KIND) {
+    throw new Error("not a device event (kind mismatch)");
+  }
+  const tag = (name) => {
+    for (const t of event.tags) {
+      if (t[0] === name && t.length > 1) return t[1] ?? null;
+    }
+    return null;
+  };
+  const address = tag("addr");
+  const device_id = tag("device_id");
+  const device_pk = tag("device_pk");
+  const binding_sig = tag("binding_sig");
+  if (!address || !device_id || !device_pk || !binding_sig) {
+    throw new Error("device event missing required tags");
+  }
+  return {
+    address,
+    device_id,
+    device_pk,
+    bindingStatement: event.content,
+    bindingSigBase64: binding_sig,
+    revoked: device_pk === "revoked",
+    createdAtUnix: event.created_at,
+    nostrPubkey: event.pubkey,
+    eventId: event.id
+  };
+}
+
+export { BINDING_VERSION, DEVICE_KIND, buildBindingStatement, buildDeviceEvent, buildRevocationStatement, computeNostrEventId, deriveNostrKey, finalizeDeviceEvent, generateDeviceKey, parseDeviceEvent, signNostrEvent };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["// Device key binding and Nostr directory publication.\n// See SPEC.md §3.\n\nimport { schnorr } from '@noble/curves/secp256k1';\nimport {\n    generateX25519KeyPair,\n    hexDecode,\n    hexEncode,\n    hkdfSha256,\n    randomBytesN,\n    sha256Bytes,\n    utf8Encode,\n} from '@orangecheck/lock-crypto';\n\nexport const DEVICE_KIND = 30078;\nexport const BINDING_VERSION = 'v2';\n\nexport interface DeviceKeyPair {\n    device_id: string;\n    device_pk: string; // 32-byte hex\n    device_sk: Uint8Array; // 32 bytes\n    created_at: string; // iso8601\n}\n\nexport function generateDeviceKey(): DeviceKeyPair {\n    const kp = generateX25519KeyPair();\n    const deviceIdBytes = randomBytesN(16);\n    return {\n        device_id: hexEncode(deviceIdBytes),\n        device_pk: hexEncode(kp.public),\n        device_sk: kp.secret,\n        created_at: new Date().toISOString(),\n    };\n}\n\nexport function buildBindingStatement(params: {\n    address: string;\n    device_pk: string;\n    device_id: string;\n    created_at: string;\n}): string {\n    // Exact byte layout per SPEC §3.2. Each line ends with LF; no trailing LF\n    // beyond the last field's. Order is fixed.\n    const lines = [\n        `oc-lock:device-bind:${BINDING_VERSION}`,\n        `address: ${params.address}`,\n        `device_pk: ${params.device_pk}`,\n        `device_id: ${params.device_id}`,\n        `created_at: ${params.created_at}`,\n    ];\n    return lines.join('\\n') + '\\n';\n}\n\nexport function buildRevocationStatement(params: {\n    address: string;\n    device_id: string;\n    revoked_at: string;\n}): string {\n    const lines = [\n        `oc-lock:device-revoke:${BINDING_VERSION}`,\n        `address: ${params.address}`,\n        `device_id: ${params.device_id}`,\n        `revoked_at: ${params.revoked_at}`,\n    ];\n    return lines.join('\\n') + '\\n';\n}\n\n// ---------------------------------------------------------------------------\n// Nostr event helpers\n// ---------------------------------------------------------------------------\n\nexport interface NostrEvent {\n    id: string;\n    pubkey: string;\n    created_at: number;\n    kind: number;\n    tags: string[][];\n    content: string;\n    sig: string;\n}\n\n/**\n * Derive an ephemeral Nostr keypair from a device secret per SPEC §3.4.\n * Returns a 32-byte private key (hex).\n */\nexport function deriveNostrKey(deviceSk: Uint8Array): { nostrSk: string; nostrPk: string } {\n    const sk = hkdfSha256(\n        deviceSk,\n        utf8Encode('oc-lock/v2/nostr-key'),\n        utf8Encode('nostr-sk'),\n        32\n    );\n    const pk = schnorr.getPublicKey(sk);\n    return { nostrSk: hexEncode(sk), nostrPk: hexEncode(pk) };\n}\n\n/**\n * Build a kind-30078 addressable event announcing a device binding.\n * The caller must supply the BIP-322 signature produced by the user's Bitcoin\n * wallet (we cannot sign BIP-322 in this package — that requires a wallet).\n */\nexport function buildDeviceEvent(params: {\n    address: string;\n    device_id: string;\n    device_pk: string;\n    bindingStatement: string;\n    bindingSigBase64: string;\n    createdAtUnix?: number;\n}): Omit<NostrEvent, 'id' | 'sig' | 'pubkey'> & { pubkey?: undefined } {\n    const tags: string[][] = [\n        ['d', `oc-lock:device:${params.address}`],\n        ['addr', params.address],\n        ['device_id', params.device_id],\n        ['device_pk', params.device_pk],\n        ['alg', 'x25519'],\n        ['binding_sig', params.bindingSigBase64],\n    ];\n    const created_at = params.createdAtUnix ?? Math.floor(Date.now() / 1000);\n    return {\n        kind: DEVICE_KIND,\n        tags,\n        content: params.bindingStatement,\n        created_at,\n    } as unknown as Omit<NostrEvent, 'id' | 'sig' | 'pubkey'> & { pubkey?: undefined };\n}\n\n/**\n * Sign a Nostr event with a Schnorr key (derived via deriveNostrKey). Produces\n * the full NostrEvent with id and sig.\n */\nexport function signNostrEvent(\n    event: Omit<NostrEvent, 'id' | 'sig'>,\n    nostrSkHex: string\n): NostrEvent {\n    const id = computeNostrEventId(event);\n    const sk = hexDecode(nostrSkHex);\n    const sig = schnorr.sign(hexDecode(id), sk);\n    return {\n        ...event,\n        id,\n        sig: hexEncode(sig),\n    };\n}\n\nexport function computeNostrEventId(event: Omit<NostrEvent, 'id' | 'sig'>): string {\n    // Per NIP-01: id = sha256(utf8(JSON.stringify([0, pubkey, created_at, kind, tags, content]))).\n    // The array must be serialized in *exactly* this form with no whitespace.\n    const serialized = JSON.stringify([\n        0,\n        event.pubkey,\n        event.created_at,\n        event.kind,\n        event.tags,\n        event.content,\n    ]);\n    return hexEncode(sha256Bytes(utf8Encode(serialized)));\n}\n\n/**\n * Finalize a device event: derive Nostr key from device_sk, attach pubkey,\n * compute id, sign. Returns a fully-signed NIP-01 event ready to publish.\n */\nexport function finalizeDeviceEvent(params: {\n    deviceSk: Uint8Array;\n    address: string;\n    device_id: string;\n    device_pk: string;\n    bindingStatement: string;\n    bindingSigBase64: string;\n    createdAtUnix?: number;\n}): NostrEvent {\n    const { nostrSk, nostrPk } = deriveNostrKey(params.deviceSk);\n    const base = buildDeviceEvent({\n        address: params.address,\n        device_id: params.device_id,\n        device_pk: params.device_pk,\n        bindingStatement: params.bindingStatement,\n        bindingSigBase64: params.bindingSigBase64,\n        createdAtUnix: params.createdAtUnix,\n    });\n    const withPubkey = { ...base, pubkey: nostrPk } as Omit<NostrEvent, 'id' | 'sig'>;\n    return signNostrEvent(withPubkey, nostrSk);\n}\n\n// ---------------------------------------------------------------------------\n// Parsing\n// ---------------------------------------------------------------------------\n\nexport interface ParsedDeviceEvent {\n    address: string;\n    device_id: string;\n    device_pk: string;\n    bindingStatement: string;\n    bindingSigBase64: string;\n    revoked: boolean;\n    createdAtUnix: number;\n    nostrPubkey: string;\n    eventId: string;\n}\n\nexport function parseDeviceEvent(event: NostrEvent): ParsedDeviceEvent {\n    if (event.kind !== DEVICE_KIND) {\n        throw new Error('not a device event (kind mismatch)');\n    }\n    const tag = (name: string): string | null => {\n        for (const t of event.tags) {\n            if (t[0] === name && t.length > 1) return t[1] ?? null;\n        }\n        return null;\n    };\n    const address = tag('addr');\n    const device_id = tag('device_id');\n    const device_pk = tag('device_pk');\n    const binding_sig = tag('binding_sig');\n    if (!address || !device_id || !device_pk || !binding_sig) {\n        throw new Error('device event missing required tags');\n    }\n    return {\n        address,\n        device_id,\n        device_pk,\n        bindingStatement: event.content,\n        bindingSigBase64: binding_sig,\n        revoked: device_pk === 'revoked',\n        createdAtUnix: event.created_at,\n        nostrPubkey: event.pubkey,\n        eventId: event.id,\n    };\n}\n"]}

package/package.json

@@ -0,0 +1,59 @@
+{
+    "name": "@orangecheck/lock-device",
+    "version": "0.1.0",
+    "description": "Device-key binding and Nostr kind-30078 directory publication for OC Lock.",
+    "keywords": [
+        "bitcoin",
+        "bip322",
+        "nostr",
+        "encryption",
+        "oc-lock",
+        "orangecheck"
+    ],
+    "author": "OrangeCheck",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/orangecheck/oc-packages.git",
+        "directory": "lock-device"
+    },
+    "homepage": "https://github.com/orangecheck/oc-lock-protocol",
+    "bugs": {
+        "url": "https://github.com/orangecheck/oc-lock-protocol/issues"
+    },
+    "main": "./dist/index.js",
+    "module": "./dist/index.mjs",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "build": "tsup",
+        "dev": "tsup --watch",
+        "type-check": "tsc --noEmit",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "clean": "rm -rf dist",
+        "prepublishOnly": "npm run clean && npm run build"
+    },
+    "dependencies": {
+        "@noble/curves": "^1.6.0",
+        "@orangecheck/lock-crypto": "^0.1.0"
+    },
+    "devDependencies": {
+        "@types/node": "^22.10.2",
+        "tsup": "^8.3.5",
+        "typescript": "^5.7.2",
+        "vitest": "^3.2.4"
+    }
+}

package/src/index.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest';
+import {
+    buildBindingStatement,
+    buildRevocationStatement,
+    computeNostrEventId,
+    deriveNostrKey,
+    finalizeDeviceEvent,
+    generateDeviceKey,
+    parseDeviceEvent,
+} from './index.js';
+
+describe('device', () => {
+    it('generates a device key with expected shape', () => {
+        const k = generateDeviceKey();
+        expect(k.device_pk).toMatch(/^[0-9a-f]{64}$/);
+        expect(k.device_id).toMatch(/^[0-9a-f]{32}$/);
+        expect(k.device_sk.length).toBe(32);
+    });
+
+    it('binding statement is deterministic and canonical', () => {
+        const s = buildBindingStatement({
+            address: 'bc1qalice',
+            device_pk: 'aa'.repeat(32),
+            device_id: '01'.repeat(16),
+            created_at: '2026-04-22T14:03:11.000Z',
+        });
+        expect(s).toBe(
+            'oc-lock:device-bind:v2\n' +
+                'address: bc1qalice\n' +
+                'device_pk: ' + 'aa'.repeat(32) + '\n' +
+                'device_id: ' + '01'.repeat(16) + '\n' +
+                'created_at: 2026-04-22T14:03:11.000Z\n'
+        );
+    });
+
+    it('revocation statement is canonical', () => {
+        const s = buildRevocationStatement({
+            address: 'bc1qalice',
+            device_id: '01'.repeat(16),
+            revoked_at: '2026-05-01T00:00:00.000Z',
+        });
+        expect(s).toBe(
+            'oc-lock:device-revoke:v2\n' +
+                'address: bc1qalice\n' +
+                'device_id: ' + '01'.repeat(16) + '\n' +
+                'revoked_at: 2026-05-01T00:00:00.000Z\n'
+        );
+    });
+
+    it('derives a deterministic Nostr key from device secret', () => {
+        const k = generateDeviceKey();
+        const n1 = deriveNostrKey(k.device_sk);
+        const n2 = deriveNostrKey(k.device_sk);
+        expect(n1.nostrSk).toBe(n2.nostrSk);
+        expect(n1.nostrPk).toBe(n2.nostrPk);
+        expect(n1.nostrPk).toMatch(/^[0-9a-f]{64}$/);
+    });
+
+    it('finalized device event has stable id and valid signature', () => {
+        const k = generateDeviceKey();
+        const binding = buildBindingStatement({
+            address: 'bc1qalice',
+            device_pk: k.device_pk,
+            device_id: k.device_id,
+            created_at: k.created_at,
+        });
+        const event = finalizeDeviceEvent({
+            deviceSk: k.device_sk,
+            address: 'bc1qalice',
+            device_id: k.device_id,
+            device_pk: k.device_pk,
+            bindingStatement: binding,
+            bindingSigBase64: 'fakeBip322Sig==',
+            createdAtUnix: 1_700_000_000,
+        });
+        expect(event.id).toMatch(/^[0-9a-f]{64}$/);
+        expect(event.sig).toMatch(/^[0-9a-f]{128}$/);
+        // Recomputed id must match.
+        const { id: _id, sig: _sig, ...rest } = event;
+        const recomputed = computeNostrEventId(rest);
+        expect(recomputed).toBe(event.id);
+    });
+
+    it('round-trips through parseDeviceEvent', () => {
+        const k = generateDeviceKey();
+        const binding = buildBindingStatement({
+            address: 'bc1qalice',
+            device_pk: k.device_pk,
+            device_id: k.device_id,
+            created_at: k.created_at,
+        });
+        const event = finalizeDeviceEvent({
+            deviceSk: k.device_sk,
+            address: 'bc1qalice',
+            device_id: k.device_id,
+            device_pk: k.device_pk,
+            bindingStatement: binding,
+            bindingSigBase64: 'sig==',
+        });
+        const parsed = parseDeviceEvent(event);
+        expect(parsed.address).toBe('bc1qalice');
+        expect(parsed.device_pk).toBe(k.device_pk);
+        expect(parsed.device_id).toBe(k.device_id);
+        expect(parsed.revoked).toBe(false);
+    });
+
+    it('detects revoked device records', () => {
+        const k = generateDeviceKey();
+        const event = finalizeDeviceEvent({
+            deviceSk: k.device_sk,
+            address: 'bc1qalice',
+            device_id: k.device_id,
+            device_pk: 'revoked',
+            bindingStatement: buildRevocationStatement({
+                address: 'bc1qalice',
+                device_id: k.device_id,
+                revoked_at: new Date().toISOString(),
+            }),
+            bindingSigBase64: 'revoked-sig==',
+        });
+        const parsed = parseDeviceEvent(event);
+        expect(parsed.revoked).toBe(true);
+    });
+});

package/src/index.ts

@@ -0,0 +1,229 @@
+// Device key binding and Nostr directory publication.
+// See SPEC.md §3.
+
+import { schnorr } from '@noble/curves/secp256k1';
+import {
+    generateX25519KeyPair,
+    hexDecode,
+    hexEncode,
+    hkdfSha256,
+    randomBytesN,
+    sha256Bytes,
+    utf8Encode,
+} from '@orangecheck/lock-crypto';
+
+export const DEVICE_KIND = 30078;
+export const BINDING_VERSION = 'v2';
+
+export interface DeviceKeyPair {
+    device_id: string;
+    device_pk: string; // 32-byte hex
+    device_sk: Uint8Array; // 32 bytes
+    created_at: string; // iso8601
+}
+
+export function generateDeviceKey(): DeviceKeyPair {
+    const kp = generateX25519KeyPair();
+    const deviceIdBytes = randomBytesN(16);
+    return {
+        device_id: hexEncode(deviceIdBytes),
+        device_pk: hexEncode(kp.public),
+        device_sk: kp.secret,
+        created_at: new Date().toISOString(),
+    };
+}
+
+export function buildBindingStatement(params: {
+    address: string;
+    device_pk: string;
+    device_id: string;
+    created_at: string;
+}): string {
+    // Exact byte layout per SPEC §3.2. Each line ends with LF; no trailing LF
+    // beyond the last field's. Order is fixed.
+    const lines = [
+        `oc-lock:device-bind:${BINDING_VERSION}`,
+        `address: ${params.address}`,
+        `device_pk: ${params.device_pk}`,
+        `device_id: ${params.device_id}`,
+        `created_at: ${params.created_at}`,
+    ];
+    return lines.join('\n') + '\n';
+}
+
+export function buildRevocationStatement(params: {
+    address: string;
+    device_id: string;
+    revoked_at: string;
+}): string {
+    const lines = [
+        `oc-lock:device-revoke:${BINDING_VERSION}`,
+        `address: ${params.address}`,
+        `device_id: ${params.device_id}`,
+        `revoked_at: ${params.revoked_at}`,
+    ];
+    return lines.join('\n') + '\n';
+}
+
+// ---------------------------------------------------------------------------
+// Nostr event helpers
+// ---------------------------------------------------------------------------
+
+export interface NostrEvent {
+    id: string;
+    pubkey: string;
+    created_at: number;
+    kind: number;
+    tags: string[][];
+    content: string;
+    sig: string;
+}
+
+/**
+ * Derive an ephemeral Nostr keypair from a device secret per SPEC §3.4.
+ * Returns a 32-byte private key (hex).
+ */
+export function deriveNostrKey(deviceSk: Uint8Array): { nostrSk: string; nostrPk: string } {
+    const sk = hkdfSha256(
+        deviceSk,
+        utf8Encode('oc-lock/v2/nostr-key'),
+        utf8Encode('nostr-sk'),
+        32
+    );
+    const pk = schnorr.getPublicKey(sk);
+    return { nostrSk: hexEncode(sk), nostrPk: hexEncode(pk) };
+}
+
+/**
+ * Build a kind-30078 addressable event announcing a device binding.
+ * The caller must supply the BIP-322 signature produced by the user's Bitcoin
+ * wallet (we cannot sign BIP-322 in this package — that requires a wallet).
+ */
+export function buildDeviceEvent(params: {
+    address: string;
+    device_id: string;
+    device_pk: string;
+    bindingStatement: string;
+    bindingSigBase64: string;
+    createdAtUnix?: number;
+}): Omit<NostrEvent, 'id' | 'sig' | 'pubkey'> & { pubkey?: undefined } {
+    const tags: string[][] = [
+        ['d', `oc-lock:device:${params.address}`],
+        ['addr', params.address],
+        ['device_id', params.device_id],
+        ['device_pk', params.device_pk],
+        ['alg', 'x25519'],
+        ['binding_sig', params.bindingSigBase64],
+    ];
+    const created_at = params.createdAtUnix ?? Math.floor(Date.now() / 1000);
+    return {
+        kind: DEVICE_KIND,
+        tags,
+        content: params.bindingStatement,
+        created_at,
+    } as unknown as Omit<NostrEvent, 'id' | 'sig' | 'pubkey'> & { pubkey?: undefined };
+}
+
+/**
+ * Sign a Nostr event with a Schnorr key (derived via deriveNostrKey). Produces
+ * the full NostrEvent with id and sig.
+ */
+export function signNostrEvent(
+    event: Omit<NostrEvent, 'id' | 'sig'>,
+    nostrSkHex: string
+): NostrEvent {
+    const id = computeNostrEventId(event);
+    const sk = hexDecode(nostrSkHex);
+    const sig = schnorr.sign(hexDecode(id), sk);
+    return {
+        ...event,
+        id,
+        sig: hexEncode(sig),
+    };
+}
+
+export function computeNostrEventId(event: Omit<NostrEvent, 'id' | 'sig'>): string {
+    // Per NIP-01: id = sha256(utf8(JSON.stringify([0, pubkey, created_at, kind, tags, content]))).
+    // The array must be serialized in *exactly* this form with no whitespace.
+    const serialized = JSON.stringify([
+        0,
+        event.pubkey,
+        event.created_at,
+        event.kind,
+        event.tags,
+        event.content,
+    ]);
+    return hexEncode(sha256Bytes(utf8Encode(serialized)));
+}
+
+/**
+ * Finalize a device event: derive Nostr key from device_sk, attach pubkey,
+ * compute id, sign. Returns a fully-signed NIP-01 event ready to publish.
+ */
+export function finalizeDeviceEvent(params: {
+    deviceSk: Uint8Array;
+    address: string;
+    device_id: string;
+    device_pk: string;
+    bindingStatement: string;
+    bindingSigBase64: string;
+    createdAtUnix?: number;
+}): NostrEvent {
+    const { nostrSk, nostrPk } = deriveNostrKey(params.deviceSk);
+    const base = buildDeviceEvent({
+        address: params.address,
+        device_id: params.device_id,
+        device_pk: params.device_pk,
+        bindingStatement: params.bindingStatement,
+        bindingSigBase64: params.bindingSigBase64,
+        createdAtUnix: params.createdAtUnix,
+    });
+    const withPubkey = { ...base, pubkey: nostrPk } as Omit<NostrEvent, 'id' | 'sig'>;
+    return signNostrEvent(withPubkey, nostrSk);
+}
+
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+
+export interface ParsedDeviceEvent {
+    address: string;
+    device_id: string;
+    device_pk: string;
+    bindingStatement: string;
+    bindingSigBase64: string;
+    revoked: boolean;
+    createdAtUnix: number;
+    nostrPubkey: string;
+    eventId: string;
+}
+
+export function parseDeviceEvent(event: NostrEvent): ParsedDeviceEvent {
+    if (event.kind !== DEVICE_KIND) {
+        throw new Error('not a device event (kind mismatch)');
+    }
+    const tag = (name: string): string | null => {
+        for (const t of event.tags) {
+            if (t[0] === name && t.length > 1) return t[1] ?? null;
+        }
+        return null;
+    };
+    const address = tag('addr');
+    const device_id = tag('device_id');
+    const device_pk = tag('device_pk');
+    const binding_sig = tag('binding_sig');
+    if (!address || !device_id || !device_pk || !binding_sig) {
+        throw new Error('device event missing required tags');
+    }
+    return {
+        address,
+        device_id,
+        device_pk,
+        bindingStatement: event.content,
+        bindingSigBase64: binding_sig,
+        revoked: device_pk === 'revoked',
+        createdAtUnix: event.created_at,
+        nostrPubkey: event.pubkey,
+        eventId: event.id,
+    };
+}