@bcts/xid 1.0.0-alpha.17 → 1.0.0-alpha.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bcts/xid",
-  "version": "1.0.0-alpha.17",
+  "version": "1.0.0-alpha.18",
   "type": "module",
   "description": "Blockchain Commons XID for TypeScript",
   "license": "BSD-2-Clause-Patent",
@@ -68,11 +68,11 @@
   },
   "devDependencies": {
     "@bcts/eslint": "^0.1.0",
-    "@bcts/rand": "^1.0.0-alpha.17",
+    "@bcts/rand": "^1.0.0-alpha.18",
     "@bcts/tsconfig": "^0.1.0",
     "@eslint/js": "^9.39.2",
-    "@typescript-eslint/eslint-plugin": "^8.53.1",
-    "@typescript-eslint/parser": "^8.53.1",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
     "eslint": "^9.39.2",
     "ts-node": "^10.9.2",
     "tsdown": "^0.20.1",
@@ -81,10 +81,10 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@bcts/components": "^1.0.0-alpha.17",
-    "@bcts/dcbor": "^1.0.0-alpha.17",
-    "@bcts/envelope": "^1.0.0-alpha.17",
-    "@bcts/known-values": "^1.0.0-alpha.17",
-    "@bcts/provenance-mark": "^1.0.0-alpha.17"
+    "@bcts/components": "^1.0.0-alpha.18",
+    "@bcts/dcbor": "^1.0.0-alpha.18",
+    "@bcts/envelope": "^1.0.0-alpha.18",
+    "@bcts/known-values": "^1.0.0-alpha.18",
+    "@bcts/provenance-mark": "^1.0.0-alpha.18"
   }
 }

package/src/index.ts

@@ -64,5 +64,8 @@ export {
   XIDVerifySignature,
 } from "./xid-document";
 
+// Re-export Attachments and Edges from envelope for convenience
+export { Attachments, Edges, type Edgeable } from "@bcts/envelope";
+
 // Version information
 export const VERSION = "1.0.0-alpha.3";

package/src/key.ts

@@ -10,6 +10,7 @@
 import { Envelope, type EnvelopeEncodable } from "@bcts/envelope";
 import { ENDPOINT, NICKNAME, PRIVATE_KEY, SALT, type KnownValue } from "@bcts/known-values";
 import type { EnvelopeEncodableValue } from "@bcts/envelope";
+import { type Cbor } from "@bcts/dcbor";
 
 // Helper to convert KnownValue to EnvelopeEncodableValue
 const kv = (v: KnownValue): EnvelopeEncodableValue => v as unknown as EnvelopeEncodableValue;
@@ -19,8 +20,12 @@ import {
   PublicKeys,
   PrivateKeys,
   type PrivateKeyBase,
+  type SigningPublicKey,
+  type EncapsulationPublicKey,
   type Verifier,
   type Signature,
+  type KeyDerivationMethod,
+  defaultKeyDerivationMethod,
 } from "@bcts/components";
 import { Permissions, type HasPermissions } from "./permissions";
 import { type Privilege } from "./privilege";
@@ -47,6 +52,7 @@ export enum XIDPrivateKeyOptions {
 export interface XIDPrivateKeyEncryptConfig {
   type: XIDPrivateKeyOptions.Encrypt;
   password: Uint8Array;
+  method?: KeyDerivationMethod;
 }
 
 /**
@@ -121,8 +127,8 @@ export class Key implements HasNickname, HasPermissions, EnvelopeEncodable, Veri
    * Create a new Key with private key base (derives keys from it).
    */
   static newWithPrivateKeyBase(privateKeyBase: PrivateKeyBase): Key {
-    const privateKeys = privateKeyBase.ed25519PrivateKeys();
-    const publicKeys = privateKeyBase.ed25519PublicKeys();
+    const privateKeys = privateKeyBase.schnorrPrivateKeys();
+    const publicKeys = privateKeyBase.schnorrPublicKeys();
     return Key.newWithPrivateKeys(privateKeys, publicKeys);
   }
 
@@ -172,6 +178,20 @@ export class Key implements HasNickname, HasPermissions, EnvelopeEncodable, Veri
     return this._publicKeys.reference();
   }
 
+  /**
+   * Get the signing public key.
+   */
+  signingPublicKey(): SigningPublicKey {
+    return this._publicKeys.signingPublicKey();
+  }
+
+  /**
+   * Get the encapsulation public key.
+   */
+  encapsulationPublicKey(): EncapsulationPublicKey {
+    return this._publicKeys.encapsulationPublicKey();
+  }
+
   // ============================================================================
   // Verifier Interface
   // ============================================================================
@@ -271,9 +291,13 @@ export class Key implements HasNickname, HasPermissions, EnvelopeEncodable, Veri
           case XIDPrivateKeyOptions.Encrypt: {
             if (typeof privateKeyOptions === "object") {
               const privateKeysEnvelope = Envelope.new(data.privateKeys.taggedCborData());
+              const method: KeyDerivationMethod =
+                privateKeyOptions.method ?? defaultKeyDerivationMethod();
               const encrypted = (
-                privateKeysEnvelope as unknown as { encryptSubject(p: Uint8Array): Envelope }
-              ).encryptSubject(privateKeyOptions.password);
+                privateKeysEnvelope as unknown as {
+                  lockSubject(m: KeyDerivationMethod, p: Uint8Array): Envelope;
+                }
+              ).lockSubject(method, privateKeyOptions.password);
               envelope = envelope.addAssertion(kv(PRIVATE_KEY), encrypted);
               envelope = envelope.addAssertion(kv(SALT), salt.toData());
             }
@@ -316,19 +340,29 @@ export class Key implements HasNickname, HasPermissions, EnvelopeEncodable, Veri
       asByteString(): Uint8Array | undefined;
       subject(): Envelope;
       assertionsWithPredicate(p: unknown): Envelope[];
-      decryptSubject(p: Uint8Array): Envelope;
+      unlockSubject(p: Uint8Array): Envelope;
+      isLockedWithPassword(): boolean;
     };
     const env = envelope as EnvelopeExt;
 
-    // Extract PublicKeys from subject (stored as tagged CBOR)
-    // The envelope may be a node (with assertions) or a leaf
+    // Extract PublicKeys from subject.
+    // Rust-generated documents store PublicKeys as tagged CBOR directly in the leaf.
+    // TS-generated documents may store the tagged CBOR binary inside a byte string.
     const envCase = env.case();
     const subject = envCase.type === "node" ? env.subject() : env;
+    let publicKeys: PublicKeys;
     const publicKeysData = (subject as EnvelopeExt).asByteString();
-    if (publicKeysData === undefined) {
-      throw XIDError.component(new Error("Could not extract public keys from envelope"));
+    if (publicKeysData !== undefined) {
+      // TS format: tagged CBOR binary stored as a byte string
+      publicKeys = PublicKeys.fromTaggedCborData(publicKeysData);
+    } else {
+      // Rust format: tagged CBOR stored directly as the leaf CBOR value
+      const leaf = (subject as unknown as { asLeaf(): Cbor | undefined }).asLeaf?.();
+      if (leaf === undefined) {
+        throw XIDError.component(new Error("Could not extract public keys from envelope"));
+      }
+      publicKeys = PublicKeys.fromTaggedCbor(leaf);
     }
-    const publicKeys = PublicKeys.fromTaggedCborData(publicKeysData);
 
     // Extract optional private key
     let privateKeyData: { data: PrivateKeyData; salt: Salt } | undefined;
@@ -356,13 +390,12 @@ export class Key implements HasNickname, HasPermissions, EnvelopeEncodable, Veri
       if (assertionCase.type === "assertion") {
         const privateKeyObject = assertionCase.assertion.object() as EnvelopeExt;
 
-        // Check if encrypted
-        const objCase = privateKeyObject.case();
-        if (objCase.type === "encrypted") {
+        // Check if locked with password (uses hasSecret assertion with EncryptedKey)
+        if (privateKeyObject.isLockedWithPassword()) {
           if (password !== undefined) {
             try {
-              const decrypted = privateKeyObject.decryptSubject(password) as EnvelopeExt;
-              const decryptedData = decrypted.asByteString();
+              const decrypted = privateKeyObject.unlockSubject(password) as EnvelopeExt;
+              const decryptedData = (decrypted.subject() as EnvelopeExt).asByteString();
               if (decryptedData !== undefined) {
                 // Parse PrivateKeys from tagged CBOR
                 const privateKeys = PrivateKeys.fromTaggedCborData(decryptedData);
@@ -431,6 +464,39 @@ export class Key implements HasNickname, HasPermissions, EnvelopeEncodable, Veri
     return new Key(publicKeys, privateKeyData, nickname, endpoints, permissions);
   }
 
+  /**
+   * Get the private key envelope, optionally decrypting it.
+   *
+   * Returns:
+   * - undefined if no private keys
+   * - The decrypted private key envelope if unencrypted
+   * - The decrypted envelope if encrypted + correct password
+   * - The encrypted envelope as-is if encrypted + no password
+   * - Throws on wrong password
+   */
+  privateKeyEnvelope(password?: string): Envelope | undefined {
+    if (this._privateKeyData === undefined) {
+      return undefined;
+    }
+    const { data } = this._privateKeyData;
+    if (data.type === "decrypted") {
+      return Envelope.new(data.privateKeys.taggedCborData());
+    }
+    // Encrypted case
+    if (password !== undefined) {
+      try {
+        const decrypted = (
+          data.envelope as unknown as { unlockSubject(p: Uint8Array): Envelope }
+        ).unlockSubject(new TextEncoder().encode(password));
+        return decrypted;
+      } catch {
+        throw XIDError.invalidPassword();
+      }
+    }
+    // No password — return encrypted envelope as-is
+    return data.envelope;
+  }
+
   /**
    * Check equality with another Key.
    */

package/src/provenance.ts

@@ -9,14 +9,21 @@
 
 import { Envelope, type EnvelopeEncodable, type EnvelopeEncodableValue } from "@bcts/envelope";
 import { PROVENANCE_GENERATOR, SALT, type KnownValue } from "@bcts/known-values";
-import { Salt } from "@bcts/components";
+import { Salt, type KeyDerivationMethod, defaultKeyDerivationMethod } from "@bcts/components";
 
 // Helper to convert KnownValue to EnvelopeEncodableValue
 const kv = (v: KnownValue): EnvelopeEncodableValue => v as unknown as EnvelopeEncodableValue;
 import { ProvenanceMark, ProvenanceMarkGenerator } from "@bcts/provenance-mark";
-import { cborData, decodeCbor } from "@bcts/dcbor";
 import { XIDError } from "./error";
 
+// Encode generator JSON as bytes for storage in envelope
+const encodeGeneratorJSON = (json: Record<string, unknown>): Uint8Array =>
+  new TextEncoder().encode(JSON.stringify(json));
+
+// Decode generator JSON from bytes stored in envelope
+const decodeGeneratorJSON = (data: Uint8Array): Record<string, unknown> =>
+  JSON.parse(new TextDecoder().decode(data)) as Record<string, unknown>;
+
 /**
  * Options for handling generators in envelopes.
  */
@@ -37,6 +44,7 @@ export enum XIDGeneratorOptions {
 export interface XIDGeneratorEncryptConfig {
   type: XIDGeneratorOptions.Encrypt;
   password: Uint8Array;
+  method?: KeyDerivationMethod;
 }
 
 /**
@@ -150,7 +158,8 @@ export class Provenance implements EnvelopeEncodable {
    */
   generatorMut(password?: Uint8Array): ProvenanceMarkGenerator | undefined {
     type EnvelopeExt = Envelope & {
-      decryptSubject(p: Uint8Array): Envelope;
+      unlockSubject(p: Uint8Array): Envelope;
+      subject(): Envelope;
       tryUnwrap(): Envelope;
       asByteString(): Uint8Array | undefined;
     };
@@ -165,12 +174,12 @@ export class Provenance implements EnvelopeEncodable {
     if (password !== undefined) {
       const encryptedEnvelope = this._generator.data.envelope as EnvelopeExt;
       try {
-        const decrypted = encryptedEnvelope.decryptSubject(password) as EnvelopeExt;
-        const unwrapped = decrypted.tryUnwrap() as EnvelopeExt;
+        const decrypted = encryptedEnvelope.unlockSubject(password) as EnvelopeExt;
+        const unwrapped = (decrypted.subject() as EnvelopeExt).tryUnwrap() as EnvelopeExt;
         // Extract generator from unwrapped envelope
         const generatorData = unwrapped.asByteString();
         if (generatorData !== undefined) {
-          const json = decodeCbor(generatorData) as unknown as Record<string, unknown>;
+          const json = decodeGeneratorJSON(generatorData);
           const generator = ProvenanceMarkGenerator.fromJSON(json);
           // Replace encrypted with decrypted
           this._generator = {
@@ -187,6 +196,47 @@ export class Provenance implements EnvelopeEncodable {
     throw XIDError.invalidPassword();
   }
 
+  /**
+   * Get the generator envelope, optionally decrypting it.
+   *
+   * Returns:
+   * - undefined if no generator
+   * - An envelope containing the generator if unencrypted
+   * - The decrypted envelope if encrypted + correct password
+   * - The encrypted envelope as-is if encrypted + no password
+   * - Throws on wrong password
+   */
+  generatorEnvelope(password?: string): Envelope | undefined {
+    type EnvelopeExt = Envelope & {
+      unlockSubject(p: Uint8Array): Envelope;
+      subject(): Envelope;
+      tryUnwrap(): Envelope;
+    };
+
+    if (this._generator === undefined) {
+      return undefined;
+    }
+    const { data } = this._generator;
+    if (data.type === "decrypted") {
+      const generatorBytes = encodeGeneratorJSON(data.generator.toJSON());
+      return Envelope.new(generatorBytes);
+    }
+    // Encrypted case
+    if (password !== undefined) {
+      try {
+        const decrypted = (data.envelope as EnvelopeExt).unlockSubject(
+          new TextEncoder().encode(password),
+        ) as EnvelopeExt;
+        const unwrapped = (decrypted.subject() as EnvelopeExt).tryUnwrap();
+        return unwrapped;
+      } catch {
+        throw XIDError.invalidPassword();
+      }
+    }
+    // No password — return encrypted envelope as-is
+    return data.envelope;
+  }
+
   /**
    * Convert to envelope with specified options.
    */
@@ -194,7 +244,7 @@ export class Provenance implements EnvelopeEncodable {
     type EnvelopeExt = Envelope & {
       elide(): Envelope;
       wrap(): Envelope;
-      encryptSubject(p: Uint8Array): Envelope;
+      lockSubject(m: KeyDerivationMethod, p: Uint8Array): Envelope;
     };
 
     // Create envelope with the mark as subject
@@ -215,13 +265,13 @@ export class Provenance implements EnvelopeEncodable {
 
         switch (option) {
           case XIDGeneratorOptions.Include: {
-            const generatorBytes = cborData(data.generator.toJSON());
+            const generatorBytes = encodeGeneratorJSON(data.generator.toJSON());
             envelope = envelope.addAssertion(kv(PROVENANCE_GENERATOR), generatorBytes);
             envelope = envelope.addAssertion(kv(SALT), salt.toData());
             break;
           }
           case XIDGeneratorOptions.Elide: {
-            const generatorBytes2 = cborData(data.generator.toJSON());
+            const generatorBytes2 = encodeGeneratorJSON(data.generator.toJSON());
             const baseAssertion = Envelope.newAssertion(kv(PROVENANCE_GENERATOR), generatorBytes2);
             const elidedAssertion = (baseAssertion as EnvelopeExt).elide();
             envelope = envelope.addAssertionEnvelope(elidedAssertion);
@@ -230,10 +280,15 @@ export class Provenance implements EnvelopeEncodable {
           }
           case XIDGeneratorOptions.Encrypt: {
             if (typeof generatorOptions === "object") {
-              const generatorBytes3 = cborData(data.generator.toJSON());
+              const generatorBytes3 = encodeGeneratorJSON(data.generator.toJSON());
               const generatorEnvelope = Envelope.new(generatorBytes3) as EnvelopeExt;
               const wrapped = generatorEnvelope.wrap() as EnvelopeExt;
-              const encrypted = wrapped.encryptSubject(generatorOptions.password);
+              const method: KeyDerivationMethod =
+                generatorOptions.method ?? defaultKeyDerivationMethod();
+              const encrypted = (wrapped as unknown as EnvelopeExt).lockSubject(
+                method,
+                generatorOptions.password,
+              );
               envelope = envelope.addAssertion(kv(PROVENANCE_GENERATOR), encrypted);
               envelope = envelope.addAssertion(kv(SALT), salt.toData());
             }
@@ -261,8 +316,10 @@ export class Provenance implements EnvelopeEncodable {
   static tryFromEnvelope(envelope: Envelope, password?: Uint8Array): Provenance {
     type EnvelopeExt = Envelope & {
       asByteString(): Uint8Array | undefined;
+      subject(): Envelope;
       assertionsWithPredicate(p: unknown): Envelope[];
-      decryptSubject(p: Uint8Array): Envelope;
+      unlockSubject(p: Uint8Array): Envelope;
+      isLockedWithPassword(): boolean;
       tryUnwrap(): Envelope;
     };
     const env = envelope as EnvelopeExt;
@@ -304,16 +361,15 @@ export class Provenance implements EnvelopeEncodable {
       if (assertionCase.type === "assertion") {
         const generatorObject = assertionCase.assertion.object() as EnvelopeExt;
 
-        // Check if encrypted
-        const objCase = generatorObject.case();
-        if (objCase.type === "encrypted") {
+        // Check if locked with password (uses hasSecret assertion with EncryptedKey)
+        if (generatorObject.isLockedWithPassword()) {
           if (password !== undefined) {
             try {
-              const decrypted = generatorObject.decryptSubject(password) as EnvelopeExt;
-              const unwrapped = decrypted.tryUnwrap() as EnvelopeExt;
+              const decrypted = generatorObject.unlockSubject(password) as EnvelopeExt;
+              const unwrapped = (decrypted.subject() as EnvelopeExt).tryUnwrap() as EnvelopeExt;
               const generatorData = unwrapped.asByteString();
               if (generatorData !== undefined) {
-                const json = decodeCbor(generatorData) as unknown as Record<string, unknown>;
+                const json = decodeGeneratorJSON(generatorData);
                 const gen = ProvenanceMarkGenerator.fromJSON(json);
                 generator = {
                   data: { type: "decrypted", generator: gen },
@@ -338,7 +394,7 @@ export class Provenance implements EnvelopeEncodable {
           // Plain text generator
           const generatorData = generatorObject.asByteString();
           if (generatorData !== undefined) {
-            const json2 = decodeCbor(generatorData) as unknown as Record<string, unknown>;
+            const json2 = decodeGeneratorJSON(generatorData);
             const gen = ProvenanceMarkGenerator.fromJSON(json2);
             generator = {
               data: { type: "decrypted", generator: gen },

package/src/service.ts

@@ -12,7 +12,7 @@ import { KEY, DELEGATE, NAME, CAPABILITY, ALLOW, type KnownValue } from "@bcts/k
 
 // Helper to convert KnownValue to EnvelopeEncodableValue
 const kv = (v: KnownValue): EnvelopeEncodableValue => v as unknown as EnvelopeEncodableValue;
-import type { Reference } from "@bcts/components";
+import { Reference, type PublicKeys, type XID } from "@bcts/components";
 import { Permissions, type HasPermissions } from "./permissions";
 import { privilegeFromEnvelope } from "./privilege";
 import { XIDError } from "./error";
@@ -147,6 +147,22 @@ export class Service implements HasPermissions, EnvelopeEncodable {
     this.addDelegateReferenceHex(delegateReference.toHex());
   }
 
+  /**
+   * Add a key by its public keys provider (convenience method).
+   * Matches Rust's `add_key(&mut self, key: &dyn PublicKeysProvider)`.
+   */
+  addKey(keyProvider: { publicKeys(): PublicKeys }): void {
+    this.addKeyReference(keyProvider.publicKeys().reference());
+  }
+
+  /**
+   * Add a delegate by its XID provider (convenience method).
+   * Matches Rust's `add_delegate(&mut self, delegate: &dyn XIDProvider)`.
+   */
+  addDelegate(xidProvider: { xid(): XID }): void {
+    this.addDelegateReference(Reference.hash(xidProvider.xid().toData()));
+  }
+
   /**
    * Get the name.
    */