@bcts/xid 1.0.0-alpha.5

package/src/service.ts

@@ -0,0 +1,343 @@
+/**
+ * XID Service
+ *
+ * Represents a service endpoint in an XID document, containing URI, key references,
+ * delegate references, permissions, capability, and name.
+ *
+ * Ported from bc-xid-rust/src/service.rs
+ */
+
+import { Envelope, type EnvelopeEncodable, type EnvelopeEncodableValue } from "@bcts/envelope";
+import { KEY, DELEGATE, NAME, CAPABILITY, ALLOW, type KnownValue } from "@bcts/known-values";
+
+// Helper to convert KnownValue to EnvelopeEncodableValue
+const kv = (v: KnownValue): EnvelopeEncodableValue => v as unknown as EnvelopeEncodableValue;
+import type { Reference } from "@bcts/components";
+import { Permissions, type HasPermissions } from "./permissions";
+import { privilegeFromEnvelope } from "./privilege";
+import { XIDError } from "./error";
+
+// Raw values for predicate matching
+const KEY_RAW = KEY.value();
+const DELEGATE_RAW = DELEGATE.value();
+const NAME_RAW = NAME.value();
+const CAPABILITY_RAW = CAPABILITY.value();
+const ALLOW_RAW = ALLOW.value();
+
+/**
+ * Represents a service endpoint in an XID document.
+ */
+export class Service implements HasPermissions, EnvelopeEncodable {
+  private readonly _uri: string;
+  private _keyReferences: Set<string>; // Store as hex strings for easier comparison
+  private _delegateReferences: Set<string>;
+  private _permissions: Permissions;
+  private _capability: string;
+  private _name: string;
+
+  constructor(uri: string) {
+    this._uri = uri;
+    this._keyReferences = new Set();
+    this._delegateReferences = new Set();
+    this._permissions = Permissions.new();
+    this._capability = "";
+    this._name = "";
+  }
+
+  /**
+   * Create a new Service with the given URI.
+   */
+  static new(uri: string): Service {
+    return new Service(uri);
+  }
+
+  /**
+   * Get the service URI.
+   */
+  uri(): string {
+    return this._uri;
+  }
+
+  /**
+   * Get the capability string.
+   */
+  capability(): string {
+    return this._capability;
+  }
+
+  /**
+   * Set the capability string.
+   */
+  setCapability(capability: string): void {
+    this._capability = capability;
+  }
+
+  /**
+   * Add a capability, throwing if one already exists or is empty.
+   */
+  addCapability(capability: string): void {
+    if (this._capability !== "") {
+      throw XIDError.duplicate("capability");
+    }
+    if (capability === "") {
+      throw XIDError.emptyValue("capability");
+    }
+    this.setCapability(capability);
+  }
+
+  /**
+   * Get the key references set.
+   */
+  keyReferences(): Set<string> {
+    return this._keyReferences;
+  }
+
+  /**
+   * Get the key references set for mutation.
+   */
+  keyReferencesMut(): Set<string> {
+    return this._keyReferences;
+  }
+
+  /**
+   * Add a key reference by hex string.
+   */
+  addKeyReferenceHex(keyReferenceHex: string): void {
+    if (this._keyReferences.has(keyReferenceHex)) {
+      throw XIDError.duplicate("key reference");
+    }
+    this._keyReferences.add(keyReferenceHex);
+  }
+
+  /**
+   * Add a key reference.
+   */
+  addKeyReference(keyReference: Reference): void {
+    this.addKeyReferenceHex(keyReference.toHex());
+  }
+
+  /**
+   * Get the delegate references set.
+   */
+  delegateReferences(): Set<string> {
+    return this._delegateReferences;
+  }
+
+  /**
+   * Get the delegate references set for mutation.
+   */
+  delegateReferencesMut(): Set<string> {
+    return this._delegateReferences;
+  }
+
+  /**
+   * Add a delegate reference by hex string.
+   */
+  addDelegateReferenceHex(delegateReferenceHex: string): void {
+    if (this._delegateReferences.has(delegateReferenceHex)) {
+      throw XIDError.duplicate("delegate reference");
+    }
+    this._delegateReferences.add(delegateReferenceHex);
+  }
+
+  /**
+   * Add a delegate reference.
+   */
+  addDelegateReference(delegateReference: Reference): void {
+    this.addDelegateReferenceHex(delegateReference.toHex());
+  }
+
+  /**
+   * Get the name.
+   */
+  name(): string {
+    return this._name;
+  }
+
+  /**
+   * Set the name, throwing if one already exists or is empty.
+   */
+  setName(name: string): void {
+    if (this._name !== "") {
+      throw XIDError.duplicate("name");
+    }
+    if (name === "") {
+      throw XIDError.emptyValue("name");
+    }
+    this._name = name;
+  }
+
+  // HasPermissions implementation
+  permissions(): Permissions {
+    return this._permissions;
+  }
+
+  permissionsMut(): Permissions {
+    return this._permissions;
+  }
+
+  /**
+   * Convert to envelope.
+   */
+  intoEnvelope(): Envelope {
+    let envelope = Envelope.new(this._uri);
+
+    // Add key references
+    for (const keyRef of this._keyReferences) {
+      const refBytes = hexToBytes(keyRef);
+      envelope = envelope.addAssertion(kv(KEY), refBytes);
+    }
+
+    // Add delegate references
+    for (const delegateRef of this._delegateReferences) {
+      const refBytes = hexToBytes(delegateRef);
+      envelope = envelope.addAssertion(kv(DELEGATE), refBytes);
+    }
+
+    // Add capability if not empty
+    if (this._capability !== "") {
+      envelope = envelope.addAssertion(kv(CAPABILITY), this._capability);
+    }
+
+    // Add name if not empty
+    if (this._name !== "") {
+      envelope = envelope.addAssertion(kv(NAME), this._name);
+    }
+
+    // Add permissions
+    envelope = this._permissions.addToEnvelope(envelope);
+
+    return envelope;
+  }
+
+  /**
+   * Try to extract a Service from an envelope.
+   */
+  static tryFromEnvelope(envelope: Envelope): Service {
+    // Extract URI from subject
+    // The envelope may be a node (with assertions) or a leaf
+    const envExt = envelope as unknown as {
+      subject(): Envelope;
+      asText(): string | undefined;
+      case(): { type: string };
+    };
+    const envCase = envExt.case();
+    const subject = envCase.type === "node" ? envExt.subject() : envelope;
+    const uri = (subject as unknown as { asText(): string | undefined }).asText();
+    if (uri === undefined) {
+      throw XIDError.component(new Error("Could not extract URI from envelope"));
+    }
+
+    const service = new Service(uri);
+
+    // Process assertions
+    const assertions = (envelope as unknown as { assertions(): Envelope[] }).assertions();
+    for (const assertion of assertions) {
+      const assertionCase = assertion.case();
+      if (assertionCase.type !== "assertion") {
+        continue;
+      }
+
+      const predicateEnv = assertionCase.assertion.predicate();
+      const predicateCase = predicateEnv.case();
+      if (predicateCase.type !== "knownValue") {
+        continue;
+      }
+
+      const predicate = predicateCase.value.value();
+      const object = assertionCase.assertion.object();
+
+      // Check for nested assertions
+      const objectAssertions = (object as unknown as { assertions(): Envelope[] }).assertions();
+      if (objectAssertions.length > 0) {
+        throw XIDError.unexpectedNestedAssertions();
+      }
+
+      switch (predicate) {
+        case KEY_RAW: {
+          const keyData = (
+            object as unknown as { asByteString(): Uint8Array | undefined }
+          ).asByteString();
+          if (keyData !== undefined) {
+            service.addKeyReferenceHex(bytesToHex(keyData));
+          }
+          break;
+        }
+        case DELEGATE_RAW: {
+          const delegateData = (
+            object as unknown as { asByteString(): Uint8Array | undefined }
+          ).asByteString();
+          if (delegateData !== undefined) {
+            service.addDelegateReferenceHex(bytesToHex(delegateData));
+          }
+          break;
+        }
+        case CAPABILITY_RAW: {
+          const capability = (object as unknown as { asText(): string | undefined }).asText();
+          if (capability !== undefined) {
+            service.addCapability(capability);
+          }
+          break;
+        }
+        case NAME_RAW: {
+          const name = (object as unknown as { asText(): string | undefined }).asText();
+          if (name !== undefined) {
+            service.setName(name);
+          }
+          break;
+        }
+        case ALLOW_RAW: {
+          const privilege = privilegeFromEnvelope(object);
+          service._permissions.addAllow(privilege);
+          break;
+        }
+        default:
+          throw XIDError.unexpectedPredicate(String(predicate));
+      }
+    }
+
+    return service;
+  }
+
+  /**
+   * Check equality with another Service (based on URI).
+   */
+  equals(other: Service): boolean {
+    return this._uri === other._uri;
+  }
+
+  /**
+   * Get a hash key for use in Sets/Maps.
+   */
+  hashKey(): string {
+    return this._uri;
+  }
+
+  /**
+   * Clone this Service.
+   */
+  clone(): Service {
+    const clone = new Service(this._uri);
+    clone._keyReferences = new Set(this._keyReferences);
+    clone._delegateReferences = new Set(this._delegateReferences);
+    clone._permissions = this._permissions.clone();
+    clone._capability = this._capability;
+    clone._name = this._name;
+    return clone;
+  }
+}
+
+// Helper functions
+function hexToBytes(hex: string): Uint8Array {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+  }
+  return bytes;
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}

package/src/shared.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared Reference Wrapper
+ *
+ * Provides a wrapper for shared references to objects.
+ * In TypeScript, we don't have Arc/RwLock like Rust, but we can provide
+ * a simple wrapper that allows shared access to a value.
+ *
+ * Ported from bc-xid-rust/src/shared.rs
+ */
+
+/**
+ * A wrapper for shared references to objects.
+ *
+ * Unlike Rust's Arc<RwLock<T>>, JavaScript uses reference semantics for objects,
+ * so this is primarily a type-safe wrapper that makes the sharing explicit.
+ */
+export class Shared<T> {
+  private readonly value: T;
+
+  constructor(value: T) {
+    this.value = value;
+  }
+
+  /**
+   * Create a new Shared instance.
+   */
+  static new<T>(value: T): Shared<T> {
+    return new Shared(value);
+  }
+
+  /**
+   * Get a read-only reference to the value.
+   */
+  read(): T {
+    return this.value;
+  }
+
+  /**
+   * Get a mutable reference to the value.
+   */
+  write(): T {
+    return this.value;
+  }
+
+  /**
+   * Check equality with another Shared instance.
+   */
+  equals(other: Shared<T>): boolean {
+    // Use JSON.stringify for deep equality check
+    // This is a simple approach; for complex objects, a proper deep equals would be better
+    if (this.value === other.value) return true;
+    try {
+      return JSON.stringify(this.value) === JSON.stringify(other.value);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Clone this Shared instance.
+   * Note: This creates a shallow copy in JS; for deep copy, implement on T.
+   */
+  clone(): Shared<T> {
+    // If the value has a clone method, use it
+    if (
+      typeof this.value === "object" &&
+      this.value !== null &&
+      "clone" in this.value &&
+      typeof (this.value as { clone(): T }).clone === "function"
+    ) {
+      return new Shared((this.value as { clone(): T }).clone());
+    }
+    // Otherwise, return the same reference (shallow copy)
+    return new Shared(this.value);
+  }
+}