@signedby/sdk 0.1.0

package/README.md

@@ -0,0 +1,101 @@
+# SignedByMe TypeScript SDK
+
+Human-controlled identity for autonomous agents.
+
+## Installation
+
+```bash
+npm install @signedby/sdk
+```
+
+## Quick Start
+
+### For Agents - Authenticate to Enterprises
+
+```typescript
+import { SignedByClient } from '@signedby/sdk';
+
+// Load delegation from your human owner
+const client = await SignedByClient.fromDelegation('./delegation.json');
+
+console.log(`Your npub: ${client.npub}`);
+console.log(`Authorized for: ${JSON.stringify(client.scopes)}`);
+
+// Authenticate to an enterprise
+const token = await client.login({
+  clientId: 'acme-corp',
+  nonce: 'random_nonce_here'
+});
+
+// Use the OIDC token
+console.log(`ID Token: ${token.idToken}`);
+console.log(`Subject: ${token.sub}`);
+```
+
+### For Agent Setup - Initialize Identity
+
+```typescript
+import { SignedByAgent } from '@signedby/sdk';
+
+// Initialize agent (creates DID if first run)
+const agent = await SignedByAgent.init('./agent_data');
+
+console.log(`Agent npub: ${agent.npub}`);
+
+// Configure email mapping for enterprises
+agent.setEmailMapping({
+  'amazon.com': 'you@gmail.com',
+  'acme.com': 'you@gmail.com'
+});
+
+// Connect to relay and watch for authorizations
+await agent.connectRelay('wss://relay.privacy-lion.com');
+
+for await (const event of agent.watchForAuthorizations()) {
+  console.log(`New authorization from: ${event.enterprise}`);
+  console.log(`Scopes: ${event.scopes}`);
+}
+```
+
+## Error Handling
+
+```typescript
+import {
+  SignedByClient,
+  SignedByError,
+  DelegationRevokedError,
+  DelegationExpiredError,
+  ScopeDeniedError,
+} from '@signedby/sdk';
+
+try {
+  const token = await client.login({ clientId: 'acme-corp', nonce });
+} catch (error) {
+  if (error instanceof DelegationRevokedError) {
+    console.log('Delegation was revoked. Contact your human owner.');
+  } else if (error instanceof DelegationExpiredError) {
+    console.log('Delegation expired. Request renewal from your human owner.');
+  } else if (error instanceof ScopeDeniedError) {
+    console.log('Not authorized for this enterprise.');
+  } else if (error instanceof SignedByError) {
+    console.log(`Authentication failed: ${error.message}`);
+  }
+}
+```
+
+## Requirements
+
+- Node.js 18+
+- Supported platforms: Linux (x86_64, arm64), macOS (x86_64, arm64), Windows (x86_64)
+
+## Documentation
+
+- [SDK Quick Start](https://signedbyme.com/docs/sdk-quickstart.html)
+- [API Reference](https://signedbyme.com/docs/api-reference.html)
+- [Understanding Delegation](https://signedbyme.com/docs/delegation.html)
+
+## License
+
+SignedByMe Source-Available License v1.0 (SSAL-1.0)
+
+See [LICENSE](https://github.com/PrivacyLion/SignedByMe/blob/main/LICENSE) for details.

package/dist/index.d.mts

@@ -0,0 +1,242 @@
+/**
+ * Type definitions for SignedByMe SDK.
+ */
+/**
+ * OIDC token returned from successful authentication.
+ */
+interface LoginToken {
+    /** The OIDC id_token (JWT) */
+    idToken: string;
+    /** Token type, always "Bearer" */
+    tokenType: string;
+    /** Seconds until token expires */
+    expiresIn: number;
+    /** Subject - agent's npub in bech32 format */
+    sub: string;
+}
+/**
+ * Request parameters for login.
+ */
+interface LoginRequest {
+    /** Enterprise client ID */
+    clientId: string;
+    /** Random nonce for replay protection */
+    nonce: string;
+}
+/**
+ * Delegation scopes mapping enterprise to permissions.
+ */
+type Scopes = Record<string, string[]>;
+/**
+ * An authorization request from an enterprise (kind 28200).
+ */
+interface AuthorizationEvent {
+    /** Enterprise name/domain */
+    enterprise: string;
+    /** Enterprise client ID */
+    clientId: string;
+    /** Offered permission scopes */
+    scopes: string[];
+    /** NOSTR event ID */
+    eventId: string;
+    /** Unix timestamp of event creation */
+    createdAt: number;
+}
+/**
+ * Login options for customizing authentication.
+ */
+interface LoginOptions {
+    /** NOSTR relay URL (default: wss://relay.privacy-lion.com) */
+    relayUrl?: string;
+    /** SignedByMe API URL (default: https://api.beta.privacy-lion.com) */
+    apiUrl?: string;
+}
+
+/**
+ * SignedByClient - Core client for agent authentication.
+ */
+
+/**
+ * Client for authenticating to enterprises using SignedByMe.
+ *
+ * @example
+ * ```typescript
+ * const client = await SignedByClient.fromDelegation('./delegation.json');
+ * const token = await client.login({
+ *   clientId: 'acme-corp',
+ *   nonce: 'random123'
+ * });
+ * console.log(`ID Token: ${token.idToken}`);
+ * ```
+ */
+declare class SignedByClient {
+    private readonly nativeClient;
+    private readonly delegation;
+    private constructor();
+    /**
+     * Load a SignedByClient from a delegation file.
+     *
+     * @param path - Path to the delegation JSON file (kind 28250 event)
+     * @returns SignedByClient instance ready for authentication
+     * @throws {Error} If delegation file doesn't exist or is invalid
+     */
+    static fromDelegation(path: string): Promise<SignedByClient>;
+    /**
+     * Get the agent's npub (public key in bech32 format).
+     */
+    get npub(): string;
+    /**
+     * Get the delegation scopes (enterprise -> permissions mapping).
+     */
+    get scopes(): Scopes;
+    /**
+     * Authenticate to an enterprise and receive an OIDC token.
+     *
+     * @param request - Login request parameters
+     * @param options - Optional configuration
+     * @returns LoginToken containing the OIDC id_token
+     * @throws {DelegationRevokedError} If delegation has been revoked
+     * @throws {DelegationExpiredError} If delegation has expired
+     * @throws {ScopeDeniedError} If client_id not in delegation scopes
+     * @throws {MerkleRootExpiredError} If proof uses stale merkle root
+     */
+    login(request: LoginRequest, options?: LoginOptions): Promise<LoginToken>;
+}
+
+/**
+ * SignedByAgent - Agent initialization and management.
+ */
+
+/**
+ * Agent for managing identity and watching for authorization requests.
+ *
+ * @example
+ * ```typescript
+ * const agent = await SignedByAgent.init('./agent_data');
+ * agent.setEmailMapping({
+ *   'amazon.com': 'me@gmail.com',
+ *   'acme.com': 'me@gmail.com'
+ * });
+ * await agent.connectRelay('wss://relay.privacy-lion.com');
+ * agent.watchForAuthorizations();
+ * ```
+ */
+declare class SignedByAgent {
+    private readonly nativeAgent;
+    private relayConnected;
+    private _emailMapping;
+    private constructor();
+    /**
+     * Initialize a new agent or load existing identity.
+     *
+     * Creates DID keys and stores them securely if this is first run.
+     * Loads existing identity if storage already exists.
+     *
+     * @param storagePath - Directory for agent data (keys, witness cache)
+     * @returns SignedByAgent instance
+     */
+    static init(storagePath: string): Promise<SignedByAgent>;
+    /**
+     * Get the agent's npub (public key in bech32 format).
+     */
+    get npub(): string;
+    /**
+     * Set email mapping for enterprises.
+     *
+     * This tells the agent which email to provide during Gate 1
+     * enrollment for each enterprise domain.
+     *
+     * @param mapping - Dict of enterprise domain -> email address
+     */
+    setEmailMapping(mapping: Record<string, string>): void;
+    /**
+     * Connect to a NOSTR relay.
+     *
+     * @param relayUrl - WebSocket URL of the relay
+     */
+    connectRelay(relayUrl: string): Promise<void>;
+    /**
+     * Watch for kind 28200 authorization events addressed to this agent.
+     *
+     * @yields AuthorizationEvent for each incoming authorization request
+     */
+    watchForAuthorizations(): AsyncGenerator<AuthorizationEvent>;
+    /**
+     * Get recent agent activity (kinds 28101, 28102, 28103).
+     *
+     * @param limit - Maximum number of events to return
+     * @returns List of activity events
+     */
+    getActivityLog(limit?: number): Array<Record<string, unknown>>;
+}
+
+/**
+ * SignedByMe SDK Errors.
+ */
+/**
+ * Base error class for all SignedByMe errors.
+ */
+declare class SignedByError extends Error {
+    constructor(message: string);
+}
+/**
+ * Raised when the delegation has been revoked.
+ *
+ * The human owner published a kind 28251 revocation event.
+ * Contact your human owner for a new delegation.
+ */
+declare class DelegationRevokedError extends SignedByError {
+    constructor(message?: string);
+}
+/**
+ * Raised when the delegation has expired.
+ *
+ * The expires_at timestamp in the delegation has passed.
+ * Request a renewed delegation from your human owner.
+ */
+declare class DelegationExpiredError extends SignedByError {
+    constructor(message?: string);
+}
+/**
+ * Raised when Groth16 proof verification fails.
+ *
+ * This typically indicates corrupted proof data or
+ * a mismatch between proof and public inputs.
+ */
+declare class InvalidProofError extends SignedByError {
+    constructor(message?: string);
+}
+/**
+ * Raised when the proof references a stale merkle root.
+ *
+ * The merkle root in the proof is not in the last 30 valid roots.
+ * Refresh witness data and regenerate the proof.
+ */
+declare class MerkleRootExpiredError extends SignedByError {
+    constructor(message?: string);
+}
+/**
+ * Raised when attempting to access an unauthorized enterprise.
+ *
+ * The client_id is not in the delegation scopes.
+ * Request an updated delegation that includes this enterprise.
+ */
+declare class ScopeDeniedError extends SignedByError {
+    constructor(message?: string);
+}
+/**
+ * Raised when unable to connect to a NOSTR relay.
+ */
+declare class RelayConnectionError extends SignedByError {
+    constructor(message?: string);
+}
+/**
+ * Raised when the SignedByMe API returns an error.
+ */
+declare class ApiError extends SignedByError {
+    readonly errorCode?: string;
+    readonly statusCode?: number;
+    constructor(message: string, errorCode?: string, statusCode?: number);
+}
+
+export { ApiError, type AuthorizationEvent, DelegationExpiredError, DelegationRevokedError, InvalidProofError, type LoginRequest, type LoginToken, MerkleRootExpiredError, RelayConnectionError, ScopeDeniedError, type Scopes, SignedByAgent, SignedByClient, SignedByError };

package/dist/index.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Type definitions for SignedByMe SDK.
+ */
+/**
+ * OIDC token returned from successful authentication.
+ */
+interface LoginToken {
+    /** The OIDC id_token (JWT) */
+    idToken: string;
+    /** Token type, always "Bearer" */
+    tokenType: string;
+    /** Seconds until token expires */
+    expiresIn: number;
+    /** Subject - agent's npub in bech32 format */
+    sub: string;
+}
+/**
+ * Request parameters for login.
+ */
+interface LoginRequest {
+    /** Enterprise client ID */
+    clientId: string;
+    /** Random nonce for replay protection */
+    nonce: string;
+}
+/**
+ * Delegation scopes mapping enterprise to permissions.
+ */
+type Scopes = Record<string, string[]>;
+/**
+ * An authorization request from an enterprise (kind 28200).
+ */
+interface AuthorizationEvent {
+    /** Enterprise name/domain */
+    enterprise: string;
+    /** Enterprise client ID */
+    clientId: string;
+    /** Offered permission scopes */
+    scopes: string[];
+    /** NOSTR event ID */
+    eventId: string;
+    /** Unix timestamp of event creation */
+    createdAt: number;
+}
+/**
+ * Login options for customizing authentication.
+ */
+interface LoginOptions {
+    /** NOSTR relay URL (default: wss://relay.privacy-lion.com) */
+    relayUrl?: string;
+    /** SignedByMe API URL (default: https://api.beta.privacy-lion.com) */
+    apiUrl?: string;
+}
+
+/**
+ * SignedByClient - Core client for agent authentication.
+ */
+
+/**
+ * Client for authenticating to enterprises using SignedByMe.
+ *
+ * @example
+ * ```typescript
+ * const client = await SignedByClient.fromDelegation('./delegation.json');
+ * const token = await client.login({
+ *   clientId: 'acme-corp',
+ *   nonce: 'random123'
+ * });
+ * console.log(`ID Token: ${token.idToken}`);
+ * ```
+ */
+declare class SignedByClient {
+    private readonly nativeClient;
+    private readonly delegation;
+    private constructor();
+    /**
+     * Load a SignedByClient from a delegation file.
+     *
+     * @param path - Path to the delegation JSON file (kind 28250 event)
+     * @returns SignedByClient instance ready for authentication
+     * @throws {Error} If delegation file doesn't exist or is invalid
+     */
+    static fromDelegation(path: string): Promise<SignedByClient>;
+    /**
+     * Get the agent's npub (public key in bech32 format).
+     */
+    get npub(): string;
+    /**
+     * Get the delegation scopes (enterprise -> permissions mapping).
+     */
+    get scopes(): Scopes;
+    /**
+     * Authenticate to an enterprise and receive an OIDC token.
+     *
+     * @param request - Login request parameters
+     * @param options - Optional configuration
+     * @returns LoginToken containing the OIDC id_token
+     * @throws {DelegationRevokedError} If delegation has been revoked
+     * @throws {DelegationExpiredError} If delegation has expired
+     * @throws {ScopeDeniedError} If client_id not in delegation scopes
+     * @throws {MerkleRootExpiredError} If proof uses stale merkle root
+     */
+    login(request: LoginRequest, options?: LoginOptions): Promise<LoginToken>;
+}
+
+/**
+ * SignedByAgent - Agent initialization and management.
+ */
+
+/**
+ * Agent for managing identity and watching for authorization requests.
+ *
+ * @example
+ * ```typescript
+ * const agent = await SignedByAgent.init('./agent_data');
+ * agent.setEmailMapping({
+ *   'amazon.com': 'me@gmail.com',
+ *   'acme.com': 'me@gmail.com'
+ * });
+ * await agent.connectRelay('wss://relay.privacy-lion.com');
+ * agent.watchForAuthorizations();
+ * ```
+ */
+declare class SignedByAgent {
+    private readonly nativeAgent;
+    private relayConnected;
+    private _emailMapping;
+    private constructor();
+    /**
+     * Initialize a new agent or load existing identity.
+     *
+     * Creates DID keys and stores them securely if this is first run.
+     * Loads existing identity if storage already exists.
+     *
+     * @param storagePath - Directory for agent data (keys, witness cache)
+     * @returns SignedByAgent instance
+     */
+    static init(storagePath: string): Promise<SignedByAgent>;
+    /**
+     * Get the agent's npub (public key in bech32 format).
+     */
+    get npub(): string;
+    /**
+     * Set email mapping for enterprises.
+     *
+     * This tells the agent which email to provide during Gate 1
+     * enrollment for each enterprise domain.
+     *
+     * @param mapping - Dict of enterprise domain -> email address
+     */
+    setEmailMapping(mapping: Record<string, string>): void;
+    /**
+     * Connect to a NOSTR relay.
+     *
+     * @param relayUrl - WebSocket URL of the relay
+     */
+    connectRelay(relayUrl: string): Promise<void>;
+    /**
+     * Watch for kind 28200 authorization events addressed to this agent.
+     *
+     * @yields AuthorizationEvent for each incoming authorization request
+     */
+    watchForAuthorizations(): AsyncGenerator<AuthorizationEvent>;
+    /**
+     * Get recent agent activity (kinds 28101, 28102, 28103).
+     *
+     * @param limit - Maximum number of events to return
+     * @returns List of activity events
+     */
+    getActivityLog(limit?: number): Array<Record<string, unknown>>;
+}
+
+/**
+ * SignedByMe SDK Errors.
+ */
+/**
+ * Base error class for all SignedByMe errors.
+ */
+declare class SignedByError extends Error {
+    constructor(message: string);
+}
+/**
+ * Raised when the delegation has been revoked.
+ *
+ * The human owner published a kind 28251 revocation event.
+ * Contact your human owner for a new delegation.
+ */
+declare class DelegationRevokedError extends SignedByError {
+    constructor(message?: string);
+}
+/**
+ * Raised when the delegation has expired.
+ *
+ * The expires_at timestamp in the delegation has passed.
+ * Request a renewed delegation from your human owner.
+ */
+declare class DelegationExpiredError extends SignedByError {
+    constructor(message?: string);
+}
+/**
+ * Raised when Groth16 proof verification fails.
+ *
+ * This typically indicates corrupted proof data or
+ * a mismatch between proof and public inputs.
+ */
+declare class InvalidProofError extends SignedByError {
+    constructor(message?: string);
+}
+/**
+ * Raised when the proof references a stale merkle root.
+ *
+ * The merkle root in the proof is not in the last 30 valid roots.
+ * Refresh witness data and regenerate the proof.
+ */
+declare class MerkleRootExpiredError extends SignedByError {
+    constructor(message?: string);
+}
+/**
+ * Raised when attempting to access an unauthorized enterprise.
+ *
+ * The client_id is not in the delegation scopes.
+ * Request an updated delegation that includes this enterprise.
+ */
+declare class ScopeDeniedError extends SignedByError {
+    constructor(message?: string);
+}
+/**
+ * Raised when unable to connect to a NOSTR relay.
+ */
+declare class RelayConnectionError extends SignedByError {
+    constructor(message?: string);
+}
+/**
+ * Raised when the SignedByMe API returns an error.
+ */
+declare class ApiError extends SignedByError {
+    readonly errorCode?: string;
+    readonly statusCode?: number;
+    constructor(message: string, errorCode?: string, statusCode?: number);
+}
+
+export { ApiError, type AuthorizationEvent, DelegationExpiredError, DelegationRevokedError, InvalidProofError, type LoginRequest, type LoginToken, MerkleRootExpiredError, RelayConnectionError, ScopeDeniedError, type Scopes, SignedByAgent, SignedByClient, SignedByError };

package/dist/index.js

@@ -0,0 +1,320 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/native.ts
+var require_native = __commonJS({
+  "src/native.ts"(exports2, module2) {
+    "use strict";
+    var import_os = require("os");
+    var import_path = require("path");
+    function loadNativeBinding() {
+      const platformName = (0, import_os.platform)();
+      const archName = (0, import_os.arch)();
+      let nativeBinding;
+      const platformMap = {
+        darwin: {
+          x64: "@signedby/core-darwin-x64",
+          arm64: "@signedby/core-darwin-arm64"
+        },
+        linux: {
+          x64: "@signedby/core-linux-x64-gnu",
+          arm64: "@signedby/core-linux-arm64-gnu"
+        },
+        win32: {
+          x64: "@signedby/core-win32-x64-msvc"
+        }
+      };
+      const packageName = platformMap[platformName]?.[archName];
+      if (!packageName) {
+        throw new Error(
+          `Unsupported platform: ${platformName}-${archName}. SignedByMe SDK supports: linux-x64, linux-arm64, darwin-x64, darwin-arm64, win32-x64`
+        );
+      }
+      try {
+        nativeBinding = require(packageName);
+      } catch (loadError) {
+        try {
+          nativeBinding = require((0, import_path.join)(__dirname, "..", "native", `signedby_core.${platformName}.node`));
+        } catch {
+          throw new Error(
+            `Failed to load native module for ${platformName}-${archName}. Install with: npm install ${packageName}
+Original error: ${loadError}`
+          );
+        }
+      }
+      return nativeBinding;
+    }
+    module2.exports = loadNativeBinding();
+  }
+});
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ApiError: () => ApiError,
+  DelegationExpiredError: () => DelegationExpiredError,
+  DelegationRevokedError: () => DelegationRevokedError,
+  InvalidProofError: () => InvalidProofError,
+  MerkleRootExpiredError: () => MerkleRootExpiredError,
+  RelayConnectionError: () => RelayConnectionError,
+  ScopeDeniedError: () => ScopeDeniedError,
+  SignedByAgent: () => SignedByAgent,
+  SignedByClient: () => SignedByClient,
+  SignedByError: () => SignedByError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_fs = require("fs");
+
+// src/errors.ts
+var SignedByError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SignedByError";
+  }
+};
+var DelegationRevokedError = class extends SignedByError {
+  constructor(message = "Delegation has been revoked") {
+    super(message);
+    this.name = "DelegationRevokedError";
+  }
+};
+var DelegationExpiredError = class extends SignedByError {
+  constructor(message = "Delegation has expired") {
+    super(message);
+    this.name = "DelegationExpiredError";
+  }
+};
+var InvalidProofError = class extends SignedByError {
+  constructor(message = "Invalid Groth16 proof") {
+    super(message);
+    this.name = "InvalidProofError";
+  }
+};
+var MerkleRootExpiredError = class extends SignedByError {
+  constructor(message = "Merkle root is expired") {
+    super(message);
+    this.name = "MerkleRootExpiredError";
+  }
+};
+var ScopeDeniedError = class extends SignedByError {
+  constructor(message = "Enterprise not in delegation scopes") {
+    super(message);
+    this.name = "ScopeDeniedError";
+  }
+};
+var RelayConnectionError = class extends SignedByError {
+  constructor(message = "Failed to connect to relay") {
+    super(message);
+    this.name = "RelayConnectionError";
+  }
+};
+var ApiError = class extends SignedByError {
+  errorCode;
+  statusCode;
+  constructor(message, errorCode, statusCode) {
+    super(message);
+    this.name = "ApiError";
+    this.errorCode = errorCode;
+    this.statusCode = statusCode;
+  }
+};
+
+// src/client.ts
+var native = require_native();
+var DEFAULT_RELAY_URL = "wss://relay.privacy-lion.com";
+var DEFAULT_API_URL = "https://api.beta.privacy-lion.com";
+var SignedByClient = class _SignedByClient {
+  nativeClient;
+  delegation;
+  constructor(nativeClient, delegation) {
+    this.nativeClient = nativeClient;
+    this.delegation = delegation;
+  }
+  /**
+   * Load a SignedByClient from a delegation file.
+   *
+   * @param path - Path to the delegation JSON file (kind 28250 event)
+   * @returns SignedByClient instance ready for authentication
+   * @throws {Error} If delegation file doesn't exist or is invalid
+   */
+  static async fromDelegation(path) {
+    const delegationJson = (0, import_fs.readFileSync)(path, "utf-8");
+    const event = JSON.parse(delegationJson);
+    const content = JSON.parse(event.content);
+    const expiresAt = new Date(content.expiresAt);
+    if (expiresAt < /* @__PURE__ */ new Date()) {
+      throw new DelegationExpiredError();
+    }
+    const nativeClient = await native.SignedByClient.fromDelegationJson(delegationJson);
+    return new _SignedByClient(nativeClient, content);
+  }
+  /**
+   * Get the agent's npub (public key in bech32 format).
+   */
+  get npub() {
+    return native.getNpub(this.nativeClient);
+  }
+  /**
+   * Get the delegation scopes (enterprise -> permissions mapping).
+   */
+  get scopes() {
+    return this.delegation.scopes;
+  }
+  /**
+   * Authenticate to an enterprise and receive an OIDC token.
+   *
+   * @param request - Login request parameters
+   * @param options - Optional configuration
+   * @returns LoginToken containing the OIDC id_token
+   * @throws {DelegationRevokedError} If delegation has been revoked
+   * @throws {DelegationExpiredError} If delegation has expired
+   * @throws {ScopeDeniedError} If client_id not in delegation scopes
+   * @throws {MerkleRootExpiredError} If proof uses stale merkle root
+   */
+  async login(request, options = {}) {
+    const { clientId, nonce } = request;
+    const relayUrl = options.relayUrl ?? DEFAULT_RELAY_URL;
+    const apiUrl = options.apiUrl ?? DEFAULT_API_URL;
+    if (!this.scopes[clientId] && !Object.keys(this.scopes).some((k) => clientId.includes(k))) {
+      throw new ScopeDeniedError(`Not authorized for enterprise: ${clientId}`);
+    }
+    const proofResult = await native.generateLoginProof(this.nativeClient, clientId, nonce);
+    await native.publishProofEvent(this.nativeClient, relayUrl, proofResult);
+    const tokenResponse = await native.verifyAndGetToken(
+      this.nativeClient,
+      apiUrl,
+      proofResult,
+      clientId,
+      nonce
+    );
+    return {
+      idToken: tokenResponse.id_token,
+      tokenType: tokenResponse.token_type ?? "Bearer",
+      expiresIn: tokenResponse.expires_in ?? 3600,
+      sub: tokenResponse.sub
+    };
+  }
+};
+
+// src/agent.ts
+var import_fs2 = require("fs");
+var native2 = require_native();
+var SignedByAgent = class _SignedByAgent {
+  nativeAgent;
+  relayConnected = false;
+  _emailMapping = {};
+  constructor(nativeAgent) {
+    this.nativeAgent = nativeAgent;
+  }
+  /**
+   * Initialize a new agent or load existing identity.
+   *
+   * Creates DID keys and stores them securely if this is first run.
+   * Loads existing identity if storage already exists.
+   *
+   * @param storagePath - Directory for agent data (keys, witness cache)
+   * @returns SignedByAgent instance
+   */
+  static async init(storagePath) {
+    if (!(0, import_fs2.existsSync)(storagePath)) {
+      (0, import_fs2.mkdirSync)(storagePath, { recursive: true });
+    }
+    const nativeAgent = await native2.SignedByAgent.init(storagePath);
+    return new _SignedByAgent(nativeAgent);
+  }
+  /**
+   * Get the agent's npub (public key in bech32 format).
+   */
+  get npub() {
+    return native2.getAgentNpub(this.nativeAgent);
+  }
+  /**
+   * Set email mapping for enterprises.
+   *
+   * This tells the agent which email to provide during Gate 1
+   * enrollment for each enterprise domain.
+   *
+   * @param mapping - Dict of enterprise domain -> email address
+   */
+  setEmailMapping(mapping) {
+    this._emailMapping = mapping;
+    native2.setEmailMapping(this.nativeAgent, mapping);
+  }
+  /**
+   * Connect to a NOSTR relay.
+   *
+   * @param relayUrl - WebSocket URL of the relay
+   */
+  async connectRelay(relayUrl) {
+    try {
+      await native2.connectRelay(this.nativeAgent, relayUrl);
+      this.relayConnected = true;
+    } catch (error) {
+      throw new RelayConnectionError(`Failed to connect to ${relayUrl}: ${error}`);
+    }
+  }
+  /**
+   * Watch for kind 28200 authorization events addressed to this agent.
+   *
+   * @yields AuthorizationEvent for each incoming authorization request
+   */
+  async *watchForAuthorizations() {
+    if (!this.relayConnected) {
+      throw new Error("Not connected to relay. Call connectRelay() first.");
+    }
+    const eventIterator = native2.subscribeAuthorizations(this.nativeAgent);
+    for await (const eventJson of eventIterator) {
+      const event = JSON.parse(eventJson);
+      yield {
+        enterprise: event.enterprise ?? "unknown",
+        clientId: event.client_id,
+        scopes: event.scopes ?? [],
+        eventId: event.id,
+        createdAt: event.created_at
+      };
+    }
+  }
+  /**
+   * Get recent agent activity (kinds 28101, 28102, 28103).
+   *
+   * @param limit - Maximum number of events to return
+   * @returns List of activity events
+   */
+  getActivityLog(limit = 100) {
+    return native2.getActivityLog(this.nativeAgent, limit);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ApiError,
+  DelegationExpiredError,
+  DelegationRevokedError,
+  InvalidProofError,
+  MerkleRootExpiredError,
+  RelayConnectionError,
+  ScopeDeniedError,
+  SignedByAgent,
+  SignedByClient,
+  SignedByError
+});

package/dist/index.mjs

@@ -0,0 +1,292 @@
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __commonJS = (cb, mod) => function __require2() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+
+// src/native.ts
+import { platform, arch } from "os";
+import { join } from "path";
+var require_native = __commonJS({
+  "src/native.ts"(exports, module) {
+    "use strict";
+    function loadNativeBinding() {
+      const platformName = platform();
+      const archName = arch();
+      let nativeBinding;
+      const platformMap = {
+        darwin: {
+          x64: "@signedby/core-darwin-x64",
+          arm64: "@signedby/core-darwin-arm64"
+        },
+        linux: {
+          x64: "@signedby/core-linux-x64-gnu",
+          arm64: "@signedby/core-linux-arm64-gnu"
+        },
+        win32: {
+          x64: "@signedby/core-win32-x64-msvc"
+        }
+      };
+      const packageName = platformMap[platformName]?.[archName];
+      if (!packageName) {
+        throw new Error(
+          `Unsupported platform: ${platformName}-${archName}. SignedByMe SDK supports: linux-x64, linux-arm64, darwin-x64, darwin-arm64, win32-x64`
+        );
+      }
+      try {
+        nativeBinding = __require(packageName);
+      } catch (loadError) {
+        try {
+          nativeBinding = __require(join(__dirname, "..", "native", `signedby_core.${platformName}.node`));
+        } catch {
+          throw new Error(
+            `Failed to load native module for ${platformName}-${archName}. Install with: npm install ${packageName}
+Original error: ${loadError}`
+          );
+        }
+      }
+      return nativeBinding;
+    }
+    module.exports = loadNativeBinding();
+  }
+});
+
+// src/client.ts
+import { readFileSync } from "fs";
+
+// src/errors.ts
+var SignedByError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SignedByError";
+  }
+};
+var DelegationRevokedError = class extends SignedByError {
+  constructor(message = "Delegation has been revoked") {
+    super(message);
+    this.name = "DelegationRevokedError";
+  }
+};
+var DelegationExpiredError = class extends SignedByError {
+  constructor(message = "Delegation has expired") {
+    super(message);
+    this.name = "DelegationExpiredError";
+  }
+};
+var InvalidProofError = class extends SignedByError {
+  constructor(message = "Invalid Groth16 proof") {
+    super(message);
+    this.name = "InvalidProofError";
+  }
+};
+var MerkleRootExpiredError = class extends SignedByError {
+  constructor(message = "Merkle root is expired") {
+    super(message);
+    this.name = "MerkleRootExpiredError";
+  }
+};
+var ScopeDeniedError = class extends SignedByError {
+  constructor(message = "Enterprise not in delegation scopes") {
+    super(message);
+    this.name = "ScopeDeniedError";
+  }
+};
+var RelayConnectionError = class extends SignedByError {
+  constructor(message = "Failed to connect to relay") {
+    super(message);
+    this.name = "RelayConnectionError";
+  }
+};
+var ApiError = class extends SignedByError {
+  errorCode;
+  statusCode;
+  constructor(message, errorCode, statusCode) {
+    super(message);
+    this.name = "ApiError";
+    this.errorCode = errorCode;
+    this.statusCode = statusCode;
+  }
+};
+
+// src/client.ts
+var native = require_native();
+var DEFAULT_RELAY_URL = "wss://relay.privacy-lion.com";
+var DEFAULT_API_URL = "https://api.beta.privacy-lion.com";
+var SignedByClient = class _SignedByClient {
+  nativeClient;
+  delegation;
+  constructor(nativeClient, delegation) {
+    this.nativeClient = nativeClient;
+    this.delegation = delegation;
+  }
+  /**
+   * Load a SignedByClient from a delegation file.
+   *
+   * @param path - Path to the delegation JSON file (kind 28250 event)
+   * @returns SignedByClient instance ready for authentication
+   * @throws {Error} If delegation file doesn't exist or is invalid
+   */
+  static async fromDelegation(path) {
+    const delegationJson = readFileSync(path, "utf-8");
+    const event = JSON.parse(delegationJson);
+    const content = JSON.parse(event.content);
+    const expiresAt = new Date(content.expiresAt);
+    if (expiresAt < /* @__PURE__ */ new Date()) {
+      throw new DelegationExpiredError();
+    }
+    const nativeClient = await native.SignedByClient.fromDelegationJson(delegationJson);
+    return new _SignedByClient(nativeClient, content);
+  }
+  /**
+   * Get the agent's npub (public key in bech32 format).
+   */
+  get npub() {
+    return native.getNpub(this.nativeClient);
+  }
+  /**
+   * Get the delegation scopes (enterprise -> permissions mapping).
+   */
+  get scopes() {
+    return this.delegation.scopes;
+  }
+  /**
+   * Authenticate to an enterprise and receive an OIDC token.
+   *
+   * @param request - Login request parameters
+   * @param options - Optional configuration
+   * @returns LoginToken containing the OIDC id_token
+   * @throws {DelegationRevokedError} If delegation has been revoked
+   * @throws {DelegationExpiredError} If delegation has expired
+   * @throws {ScopeDeniedError} If client_id not in delegation scopes
+   * @throws {MerkleRootExpiredError} If proof uses stale merkle root
+   */
+  async login(request, options = {}) {
+    const { clientId, nonce } = request;
+    const relayUrl = options.relayUrl ?? DEFAULT_RELAY_URL;
+    const apiUrl = options.apiUrl ?? DEFAULT_API_URL;
+    if (!this.scopes[clientId] && !Object.keys(this.scopes).some((k) => clientId.includes(k))) {
+      throw new ScopeDeniedError(`Not authorized for enterprise: ${clientId}`);
+    }
+    const proofResult = await native.generateLoginProof(this.nativeClient, clientId, nonce);
+    await native.publishProofEvent(this.nativeClient, relayUrl, proofResult);
+    const tokenResponse = await native.verifyAndGetToken(
+      this.nativeClient,
+      apiUrl,
+      proofResult,
+      clientId,
+      nonce
+    );
+    return {
+      idToken: tokenResponse.id_token,
+      tokenType: tokenResponse.token_type ?? "Bearer",
+      expiresIn: tokenResponse.expires_in ?? 3600,
+      sub: tokenResponse.sub
+    };
+  }
+};
+
+// src/agent.ts
+import { mkdirSync, existsSync } from "fs";
+var native2 = require_native();
+var SignedByAgent = class _SignedByAgent {
+  nativeAgent;
+  relayConnected = false;
+  _emailMapping = {};
+  constructor(nativeAgent) {
+    this.nativeAgent = nativeAgent;
+  }
+  /**
+   * Initialize a new agent or load existing identity.
+   *
+   * Creates DID keys and stores them securely if this is first run.
+   * Loads existing identity if storage already exists.
+   *
+   * @param storagePath - Directory for agent data (keys, witness cache)
+   * @returns SignedByAgent instance
+   */
+  static async init(storagePath) {
+    if (!existsSync(storagePath)) {
+      mkdirSync(storagePath, { recursive: true });
+    }
+    const nativeAgent = await native2.SignedByAgent.init(storagePath);
+    return new _SignedByAgent(nativeAgent);
+  }
+  /**
+   * Get the agent's npub (public key in bech32 format).
+   */
+  get npub() {
+    return native2.getAgentNpub(this.nativeAgent);
+  }
+  /**
+   * Set email mapping for enterprises.
+   *
+   * This tells the agent which email to provide during Gate 1
+   * enrollment for each enterprise domain.
+   *
+   * @param mapping - Dict of enterprise domain -> email address
+   */
+  setEmailMapping(mapping) {
+    this._emailMapping = mapping;
+    native2.setEmailMapping(this.nativeAgent, mapping);
+  }
+  /**
+   * Connect to a NOSTR relay.
+   *
+   * @param relayUrl - WebSocket URL of the relay
+   */
+  async connectRelay(relayUrl) {
+    try {
+      await native2.connectRelay(this.nativeAgent, relayUrl);
+      this.relayConnected = true;
+    } catch (error) {
+      throw new RelayConnectionError(`Failed to connect to ${relayUrl}: ${error}`);
+    }
+  }
+  /**
+   * Watch for kind 28200 authorization events addressed to this agent.
+   *
+   * @yields AuthorizationEvent for each incoming authorization request
+   */
+  async *watchForAuthorizations() {
+    if (!this.relayConnected) {
+      throw new Error("Not connected to relay. Call connectRelay() first.");
+    }
+    const eventIterator = native2.subscribeAuthorizations(this.nativeAgent);
+    for await (const eventJson of eventIterator) {
+      const event = JSON.parse(eventJson);
+      yield {
+        enterprise: event.enterprise ?? "unknown",
+        clientId: event.client_id,
+        scopes: event.scopes ?? [],
+        eventId: event.id,
+        createdAt: event.created_at
+      };
+    }
+  }
+  /**
+   * Get recent agent activity (kinds 28101, 28102, 28103).
+   *
+   * @param limit - Maximum number of events to return
+   * @returns List of activity events
+   */
+  getActivityLog(limit = 100) {
+    return native2.getActivityLog(this.nativeAgent, limit);
+  }
+};
+export {
+  ApiError,
+  DelegationExpiredError,
+  DelegationRevokedError,
+  InvalidProofError,
+  MerkleRootExpiredError,
+  RelayConnectionError,
+  ScopeDeniedError,
+  SignedByAgent,
+  SignedByClient,
+  SignedByError
+};

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@signedby/sdk",
+  "version": "0.1.0",
+  "description": "SignedByMe SDK - Human-controlled identity for autonomous agents",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "test": "vitest",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "signedby",
+    "identity",
+    "zk-proofs",
+    "zero-knowledge",
+    "nostr",
+    "bitcoin",
+    "lightning",
+    "authentication",
+    "oidc",
+    "did"
+  ],
+  "author": "Privacy Lion <contact@privacy-lion.com>",
+  "license": "SSAL-1.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PrivacyLion/SignedByMe.git",
+    "directory": "sdk/typescript"
+  },
+  "homepage": "https://signedbyme.com",
+  "bugs": {
+    "url": "https://github.com/PrivacyLion/SignedByMe/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0",
+    "eslint": "^8.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0"
+  },
+  "dependencies": {
+    "@noble/curves": "^1.3.0",
+    "@noble/hashes": "^1.3.0"
+  },
+  "optionalDependencies": {
+    "@signedby/core-linux-x64-gnu": "0.1.0",
+    "@signedby/core-linux-arm64-gnu": "0.1.0",
+    "@signedby/core-darwin-x64": "0.1.0",
+    "@signedby/core-darwin-arm64": "0.1.0",
+    "@signedby/core-win32-x64-msvc": "0.1.0"
+  }
+}