@auths-dev/sdk 0.0.1 → 0.1.0

package/lib/errors.ts

@@ -0,0 +1,306 @@
+/**
+ * Base error for all Auths SDK operations.
+ *
+ * All errors thrown by the SDK inherit from this class, carrying a
+ * machine-readable {@link AuthsError.code | code} and human-readable
+ * {@link AuthsError.message | message}.
+ *
+ * @example
+ * ```typescript
+ * import { Auths, AuthsError } from '@auths-dev/sdk'
+ *
+ * try {
+ *   auths.signAs({ message: data, identityDid: did })
+ * } catch (e) {
+ *   if (e instanceof AuthsError) {
+ *     console.log(e.code, e.message)
+ *   }
+ * }
+ * ```
+ */
+export class AuthsError extends Error {
+  /** Machine-readable error code (e.g. `'key_not_found'`, `'invalid_signature'`). */
+  code: string
+  constructor(message: string, code: string) {
+    super(message)
+    this.name = 'AuthsError'
+    this.code = code
+  }
+}
+
+/**
+ * Raised when attestation or chain verification fails.
+ *
+ * Common codes: `'invalid_signature'`, `'expired_attestation'`,
+ * `'revoked_device'`, `'missing_capability'`.
+ *
+ * @example
+ * ```typescript
+ * import { verifyAttestation, VerificationError } from '@auths-dev/sdk'
+ *
+ * try {
+ *   await verifyAttestation(json, publicKey)
+ * } catch (e) {
+ *   if (e instanceof VerificationError) {
+ *     console.log('Verification failed:', e.code)
+ *   }
+ * }
+ * ```
+ */
+export class VerificationError extends AuthsError {
+  constructor(message: string, code: string) {
+    super(message, code)
+    this.name = 'VerificationError'
+  }
+}
+
+/**
+ * Raised when a cryptographic operation fails.
+ *
+ * Common codes: `'invalid_key'`, `'key_not_found'`, `'signing_failed'`.
+ *
+ * @example
+ * ```typescript
+ * import { Auths, CryptoError } from '@auths-dev/sdk'
+ *
+ * try {
+ *   auths.signAs({ message: data, identityDid: did })
+ * } catch (e) {
+ *   if (e instanceof CryptoError && e.code === 'key_not_found') {
+ *     console.log('Identity key not in keychain')
+ *   }
+ * }
+ * ```
+ */
+export class CryptoError extends AuthsError {
+  constructor(message: string, code: string) {
+    super(message, code)
+    this.name = 'CryptoError'
+  }
+}
+
+/**
+ * Raised when the platform keychain is inaccessible or locked.
+ *
+ * Common codes: `'keychain_locked'`.
+ *
+ * @example
+ * ```typescript
+ * import { Auths, KeychainError } from '@auths-dev/sdk'
+ *
+ * try {
+ *   auths.identities.create({ label: 'main' })
+ * } catch (e) {
+ *   if (e instanceof KeychainError) {
+ *     console.log('Unlock your keychain or set AUTHS_KEYCHAIN_BACKEND=file')
+ *   }
+ * }
+ * ```
+ */
+export class KeychainError extends AuthsError {
+  constructor(message: string, code: string) {
+    super(message, code)
+    this.name = 'KeychainError'
+  }
+}
+
+/**
+ * Raised when a storage or registry operation fails.
+ *
+ * Common codes: `'repo_not_found'`, `'trust_error'`, `'witness_error'`.
+ *
+ * @example
+ * ```typescript
+ * import { Auths, StorageError } from '@auths-dev/sdk'
+ *
+ * try {
+ *   auths.trust.pin({ did: 'did:keri:ENOTREAL' })
+ * } catch (e) {
+ *   if (e instanceof StorageError) {
+ *     console.log('Storage error:', e.message)
+ *   }
+ * }
+ * ```
+ */
+export class StorageError extends AuthsError {
+  constructor(message: string, code: string) {
+    super(message, code)
+    this.name = 'StorageError'
+  }
+}
+
+/**
+ * Raised when a network operation fails (e.g. witness communication).
+ *
+ * Common codes: `'server_error'`.
+ *
+ * @example
+ * ```typescript
+ * import { NetworkError } from '@auths-dev/sdk'
+ *
+ * try {
+ *   // network operation
+ * } catch (e) {
+ *   if (e instanceof NetworkError && e.shouldRetry) {
+ *     // safe to retry
+ *   }
+ * }
+ * ```
+ */
+export class NetworkError extends AuthsError {
+  /** Whether the operation is safe to retry. Defaults to `true`. */
+  shouldRetry: boolean
+  constructor(message: string, code: string, shouldRetry = true) {
+    super(message, code)
+    this.name = 'NetworkError'
+    this.shouldRetry = shouldRetry
+  }
+}
+
+/**
+ * Raised when an identity or device operation fails.
+ *
+ * Common codes: `'identity_not_found'`, `'unknown'`.
+ *
+ * @example
+ * ```typescript
+ * import { Auths, IdentityError } from '@auths-dev/sdk'
+ *
+ * try {
+ *   auths.devices.link({ identityDid: did, capabilities: ['sign'] })
+ * } catch (e) {
+ *   if (e instanceof IdentityError) {
+ *     console.log('Identity error:', e.code)
+ *   }
+ * }
+ * ```
+ */
+export class IdentityError extends AuthsError {
+  constructor(message: string, code: string) {
+    super(message, code)
+    this.name = 'IdentityError'
+  }
+}
+
+/**
+ * Raised when an organization operation fails.
+ *
+ * Common codes: `'org_error'`.
+ *
+ * @example
+ * ```typescript
+ * import { Auths, OrgError } from '@auths-dev/sdk'
+ *
+ * try {
+ *   auths.orgs.addMember({ orgDid, memberDid, role: 'member' })
+ * } catch (e) {
+ *   if (e instanceof OrgError) {
+ *     console.log('Org error:', e.message)
+ *   }
+ * }
+ * ```
+ */
+export class OrgError extends AuthsError {
+  constructor(message: string, code: string) {
+    super(message, code)
+    this.name = 'OrgError'
+  }
+}
+
+/**
+ * Raised when a device pairing operation fails or times out.
+ *
+ * Common codes: `'pairing_error'`, `'timeout'`.
+ *
+ * @example
+ * ```typescript
+ * import { PairingError } from '@auths-dev/sdk'
+ *
+ * try {
+ *   await auths.pairing.createSession({ bindAddress: '127.0.0.1' })
+ * } catch (e) {
+ *   if (e instanceof PairingError && e.shouldRetry) {
+ *     // safe to retry
+ *   }
+ * }
+ * ```
+ */
+export class PairingError extends AuthsError {
+  /** Whether the operation is safe to retry. Defaults to `true`. */
+  shouldRetry: boolean
+  constructor(message: string, code: string, shouldRetry = true) {
+    super(message, code)
+    this.name = 'PairingError'
+    this.shouldRetry = shouldRetry
+  }
+}
+
+const ERROR_CODE_MAP: Record<string, [string, new (message: string, code: string) => AuthsError]> = {
+  AUTHS_ISSUER_SIG_FAILED: ['invalid_signature', VerificationError],
+  AUTHS_DEVICE_SIG_FAILED: ['invalid_signature', VerificationError],
+  AUTHS_ATTESTATION_EXPIRED: ['expired_attestation', VerificationError],
+  AUTHS_ATTESTATION_REVOKED: ['revoked_device', VerificationError],
+  AUTHS_TIMESTAMP_IN_FUTURE: ['future_timestamp', VerificationError],
+  AUTHS_MISSING_CAPABILITY: ['missing_capability', VerificationError],
+  AUTHS_CRYPTO_ERROR: ['invalid_key', CryptoError],
+  AUTHS_DID_RESOLUTION_ERROR: ['invalid_key', CryptoError],
+  AUTHS_INVALID_INPUT: ['invalid_signature', VerificationError],
+  AUTHS_SERIALIZATION_ERROR: ['invalid_signature', VerificationError],
+  AUTHS_BUNDLE_EXPIRED: ['expired_attestation', VerificationError],
+  AUTHS_KEY_NOT_FOUND: ['key_not_found', CryptoError],
+  AUTHS_INCORRECT_PASSPHRASE: ['signing_failed', CryptoError],
+  AUTHS_SIGNING_FAILED: ['signing_failed', CryptoError],
+  AUTHS_SIGNING_ERROR: ['signing_failed', CryptoError],
+  AUTHS_INPUT_TOO_LARGE: ['invalid_signature', VerificationError],
+  AUTHS_INTERNAL_ERROR: ['unknown', VerificationError],
+  AUTHS_ORG_VERIFICATION_FAILED: ['invalid_signature', VerificationError],
+  AUTHS_ORG_ATTESTATION_EXPIRED: ['expired_attestation', VerificationError],
+  AUTHS_ORG_DID_RESOLUTION_FAILED: ['invalid_key', CryptoError],
+  AUTHS_REGISTRY_ERROR: ['repo_not_found', StorageError],
+  AUTHS_KEYCHAIN_ERROR: ['keychain_locked', KeychainError],
+  AUTHS_IDENTITY_ERROR: ['identity_not_found', IdentityError],
+  AUTHS_DEVICE_ERROR: ['unknown', IdentityError],
+  AUTHS_ROTATION_ERROR: ['unknown', IdentityError],
+  AUTHS_NETWORK_ERROR: ['server_error', NetworkError],
+  AUTHS_VERIFICATION_FAILED: ['invalid_signature', VerificationError],
+  AUTHS_ORG_ERROR: ['org_error', OrgError],
+  AUTHS_PAIRING_ERROR: ['pairing_error', PairingError],
+  AUTHS_PAIRING_TIMEOUT: ['timeout', PairingError],
+  AUTHS_TRUST_ERROR: ['trust_error', StorageError],
+  AUTHS_WITNESS_ERROR: ['witness_error', StorageError],
+  AUTHS_AUDIT_ERROR: ['audit_error', VerificationError],
+  AUTHS_DIAGNOSTIC_ERROR: ['diagnostic_error', VerificationError],
+}
+
+/**
+ * Maps a native napi-rs error into a typed {@link AuthsError} subclass.
+ *
+ * Parses the `[AUTHS_CODE] message` format emitted by the Rust layer
+ * and instantiates the appropriate error class with a machine-readable code.
+ *
+ * @param err - The raw error from the native binding.
+ * @param defaultCls - Fallback error class when the code is unrecognized.
+ * @returns A typed {@link AuthsError} instance.
+ */
+export function mapNativeError(err: unknown, defaultCls: new (message: string, code: string) => AuthsError = VerificationError): AuthsError {
+  const msg = err instanceof Error ? err.message : String(err)
+
+  // Parse [AUTHS_CODE] prefix from native errors
+  if (msg.startsWith('[AUTHS_') && msg.includes('] ')) {
+    const code = msg.substring(1, msg.indexOf(']'))
+    const message = msg.substring(msg.indexOf('] ') + 2)
+    const mapping = ERROR_CODE_MAP[code]
+    if (mapping) {
+      const [pyCode, Cls] = mapping
+      return new Cls(message, pyCode)
+    }
+  }
+
+  // Fallback heuristics
+  const low = msg.toLowerCase()
+  if (low.includes('public key') || low.includes('private key') || low.includes('invalid key') || low.includes('hex')) {
+    return new CryptoError(msg, 'invalid_key')
+  }
+
+  return new defaultCls(msg, 'unknown')
+}

package/lib/identity.ts

@@ -0,0 +1,280 @@
+import native from './native'
+import { mapNativeError, CryptoError, IdentityError } from './errors'
+import type { Auths } from './client'
+
+/** A cryptographic identity anchored in a KERI key event log. */
+export interface Identity {
+  /** The KERI decentralized identifier (e.g. `did:keri:EBfd...`). */
+  did: string
+  /** Keychain alias used to retrieve the signing key. */
+  keyAlias: string
+  /** Human-readable label for this identity. */
+  label: string
+  /** Path to the Git registry that stores this identity. */
+  repoPath: string
+  /** Hex-encoded Ed25519 public key. */
+  publicKey: string
+}
+
+/** A standalone agent identity with its self-signed attestation. */
+export interface AgentIdentity {
+  /** The agent's KERI decentralized identifier. */
+  did: string
+  /** Keychain alias for the agent's signing key. */
+  keyAlias: string
+  /** JSON-serialized self-signed attestation. */
+  attestation: string
+  /** Hex-encoded Ed25519 public key. */
+  publicKey: string
+}
+
+/** An agent delegated under an existing identity. */
+export interface DelegatedAgent {
+  /** The delegated agent's DID (typically `did:key:z...`). */
+  did: string
+  /** Keychain alias for the agent's signing key. */
+  keyAlias: string
+  /** JSON-serialized delegation attestation signed by the parent identity. */
+  attestation: string
+  /** Hex-encoded Ed25519 public key. */
+  publicKey: string
+}
+
+/** Result of a key rotation operation. */
+export interface RotationResult {
+  /** The controller DID whose keys were rotated. */
+  controllerDid: string
+  /** Fingerprint of the new signing key. */
+  newKeyFingerprint: string
+  /** Fingerprint of the previous signing key. */
+  previousKeyFingerprint: string
+  /** New KERI event sequence number after rotation. */
+  sequence: number
+}
+
+/** Options for {@link IdentityService.create}. */
+export interface CreateIdentityOptions {
+  /** Human-readable label. Defaults to `'main'`. */
+  label?: string
+  /** Override the client's repo path. */
+  repoPath?: string
+  /** Override the client's passphrase. */
+  passphrase?: string
+}
+
+/** Options for {@link IdentityService.createAgent}. */
+export interface CreateAgentOptions {
+  /** Name for the agent identity. */
+  name: string
+  /** Capabilities to grant (e.g. `['sign']`). */
+  capabilities: string[]
+  /** Override the client's passphrase. */
+  passphrase?: string
+}
+
+/** Options for {@link IdentityService.delegateAgent}. */
+export interface DelegateAgentOptions {
+  /** DID of the parent identity that delegates authority. */
+  identityDid: string
+  /** Name for the delegated agent. */
+  name: string
+  /** Capabilities to grant (e.g. `['sign']`). */
+  capabilities: string[]
+  /** Optional expiration in days. */
+  expiresInDays?: number
+  /** Override the client's passphrase. */
+  passphrase?: string
+}
+
+/** Options for {@link IdentityService.rotate}. */
+export interface RotateKeysOptions {
+  /** DID of the identity to rotate. Defaults to the primary identity. */
+  identityDid?: string
+  /** Override the client's passphrase. */
+  passphrase?: string
+}
+
+/** Options for {@link IdentityService.getPublicKey}. */
+export interface GetPublicKeyOptions {
+  /** DID of the identity whose public key to retrieve. */
+  identityDid: string
+  /** Override the client's passphrase. */
+  passphrase?: string
+}
+
+/**
+ * Manages cryptographic identities, agents, and key rotation.
+ *
+ * Access via {@link Auths.identities}.
+ *
+ * @example
+ * ```typescript
+ * const auths = new Auths()
+ * const identity = auths.identities.create({ label: 'laptop' })
+ * console.log(identity.did) // did:keri:EBfd...
+ * ```
+ */
+export class IdentityService {
+  constructor(private client: Auths) {}
+
+  /**
+   * Creates a new cryptographic identity backed by an Ed25519 keypair.
+   *
+   * @param opts - Creation options.
+   * @returns The newly created identity.
+   * @throws {@link IdentityError} if the identity cannot be created.
+   *
+   * @example
+   * ```typescript
+   * const identity = auths.identities.create({ label: 'laptop' })
+   * console.log(identity.did)       // did:keri:EBfd...
+   * console.log(identity.publicKey) // hex-encoded Ed25519 key
+   * ```
+   */
+  create(opts: CreateIdentityOptions = {}): Identity {
+    const rp = opts.repoPath ?? this.client.repoPath
+    const pp = opts.passphrase ?? this.client.passphrase
+    try {
+      const result = native.createIdentity(opts.label ?? 'main', rp, pp)
+      return {
+        did: result.did,
+        keyAlias: result.keyAlias,
+        label: opts.label ?? 'main',
+        repoPath: rp,
+        publicKey: result.publicKeyHex,
+      }
+    } catch (err) {
+      throw mapNativeError(err, IdentityError)
+    }
+  }
+
+  /**
+   * Creates a standalone agent identity with a self-signed attestation.
+   *
+   * @param opts - Agent creation options.
+   * @returns The agent identity with its attestation.
+   * @throws {@link IdentityError} if the agent cannot be created.
+   *
+   * @example
+   * ```typescript
+   * const agent = auths.identities.createAgent({
+   *   name: 'ci-bot',
+   *   capabilities: ['sign'],
+   * })
+   * console.log(agent.did) // did:keri:...
+   * ```
+   */
+  createAgent(opts: CreateAgentOptions): AgentIdentity {
+    const pp = opts.passphrase ?? this.client.passphrase
+    try {
+      const bundle = native.createAgentIdentity(
+        opts.name,
+        opts.capabilities,
+        this.client.repoPath,
+        pp,
+      )
+      return {
+        did: bundle.agentDid,
+        keyAlias: bundle.keyAlias,
+        attestation: bundle.attestationJson,
+        publicKey: bundle.publicKeyHex,
+      }
+    } catch (err) {
+      throw mapNativeError(err, IdentityError)
+    }
+  }
+
+  /**
+   * Delegates an agent under an existing identity with scoped capabilities.
+   *
+   * @param opts - Delegation options.
+   * @returns The delegated agent with its signed attestation.
+   * @throws {@link IdentityError} if delegation fails.
+   *
+   * @example
+   * ```typescript
+   * const agent = auths.identities.delegateAgent({
+   *   identityDid: identity.did,
+   *   name: 'deploy-bot',
+   *   capabilities: ['sign'],
+   *   expiresInDays: 90,
+   * })
+   * ```
+   */
+  delegateAgent(opts: DelegateAgentOptions): DelegatedAgent {
+    const pp = opts.passphrase ?? this.client.passphrase
+    try {
+      const bundle = native.delegateAgent(
+        opts.name,
+        opts.capabilities,
+        this.client.repoPath,
+        pp,
+        opts.expiresInDays ?? null,
+        opts.identityDid,
+      )
+      return {
+        did: bundle.agentDid,
+        keyAlias: bundle.keyAlias,
+        attestation: bundle.attestationJson,
+        publicKey: bundle.publicKeyHex,
+      }
+    } catch (err) {
+      throw mapNativeError(err, IdentityError)
+    }
+  }
+
+  /**
+   * Rotates the signing keys for an identity, advancing the KERI event log.
+   *
+   * @param opts - Rotation options.
+   * @returns The rotation result with old and new key fingerprints.
+   * @throws {@link IdentityError} if rotation fails.
+   *
+   * @example
+   * ```typescript
+   * const result = auths.identities.rotate({ identityDid: identity.did })
+   * console.log(result.sequence) // incremented sequence number
+   * ```
+   */
+  rotate(opts: RotateKeysOptions = {}): RotationResult {
+    const pp = opts.passphrase ?? this.client.passphrase
+    try {
+      const result = native.rotateIdentityKeys(
+        this.client.repoPath,
+        opts.identityDid ?? null,
+        null,
+        pp,
+      )
+      return {
+        controllerDid: result.controllerDid,
+        newKeyFingerprint: result.newKeyFingerprint,
+        previousKeyFingerprint: result.previousKeyFingerprint,
+        sequence: result.sequence,
+      }
+    } catch (err) {
+      throw mapNativeError(err, IdentityError)
+    }
+  }
+
+  /**
+   * Retrieves the hex-encoded Ed25519 public key for an identity.
+   *
+   * @param opts - Lookup options.
+   * @returns Hex-encoded public key string (64 characters).
+   * @throws {@link CryptoError} if the key cannot be found.
+   *
+   * @example
+   * ```typescript
+   * const pk = auths.identities.getPublicKey({ identityDid: identity.did })
+   * console.log(pk.length) // 64
+   * ```
+   */
+  getPublicKey(opts: GetPublicKeyOptions): string {
+    const pp = opts.passphrase ?? this.client.passphrase
+    try {
+      return native.getIdentityPublicKey(opts.identityDid, this.client.repoPath, pp)
+    } catch (err) {
+      throw mapNativeError(err, CryptoError)
+    }
+  }
+}

package/lib/index.ts

@@ -0,0 +1,125 @@
+export { Auths, type ClientConfig, type VerifyOptions, type VerifyChainOptions } from './client'
+export {
+  IdentityService,
+  type Identity,
+  type AgentIdentity,
+  type DelegatedAgent,
+  type RotationResult,
+  type CreateIdentityOptions,
+  type CreateAgentOptions,
+  type DelegateAgentOptions,
+  type RotateKeysOptions,
+  type GetPublicKeyOptions,
+} from './identity'
+export {
+  DeviceService,
+  type Device,
+  type DeviceExtension,
+  type LinkDeviceOptions,
+  type RevokeDeviceOptions,
+  type ExtendDeviceOptions,
+} from './devices'
+export {
+  SigningService,
+  type SignResult,
+  type ActionEnvelope,
+  type SignAsIdentityOptions,
+  type SignActionAsIdentityOptions,
+  type SignAsAgentOptions,
+  type SignActionAsAgentOptions,
+} from './signing'
+export {
+  OrgService,
+  isAdmin,
+  type OrgResult,
+  type OrgMember,
+  type CreateOrgOptions,
+  type AddOrgMemberOptions,
+  type RevokeOrgMemberOptions,
+  type ListOrgMembersOptions,
+} from './org'
+export { TrustService, TrustLevel, type PinnedIdentity, type PinIdentityOptions } from './trust'
+export { WitnessService, type WitnessEntry, type AddWitnessOptions } from './witness'
+export { AttestationService, type AttestationInfo } from './attestations'
+export {
+  ArtifactService,
+  type ArtifactResult,
+  type SignArtifactOptions,
+  type SignArtifactBytesOptions,
+} from './artifacts'
+export { CommitService, type CommitSignResult, type SignCommitOptions } from './commits'
+export {
+  AuditService,
+  parseIdentityBundle,
+  parseIdentityBundleInfo,
+  type AuditReport,
+  type AuditCommit,
+  type AuditSummary,
+  type AuditReportOptions,
+  type AuditComplianceOptions,
+  type IdentityBundleInfo,
+} from './audit'
+export {
+  PolicyBuilder,
+  Outcome,
+  ReasonCode,
+  compilePolicy,
+  evaluatePolicy,
+  evalContextFromCommitResult,
+  type PolicyDecision,
+  type EvalContextOpts,
+  type CommitResultLike,
+} from './policy'
+export {
+  PairingService,
+  type PairingSession,
+  type PairingResponse,
+  type PairingResult,
+  type CreatePairingSessionOptions,
+  type WaitForPairingResponseOptions,
+  type JoinPairingOptions,
+  type CompletePairingOptions,
+} from './pairing'
+export {
+  verifyAttestation,
+  verifyAttestationWithCapability,
+  verifyChain,
+  verifyChainWithCapability,
+  verifyDeviceAuthorization,
+  verifyAtTime,
+  verifyAtTimeWithCapability,
+  verifyChainWithWitnesses,
+  type VerificationResult,
+  type VerificationReport,
+  type VerificationStatus,
+  type ChainLink,
+  type WitnessConfig,
+  type WitnessKey,
+} from './verify'
+export {
+  AuthsError,
+  VerificationError,
+  CryptoError,
+  KeychainError,
+  StorageError,
+  NetworkError,
+  IdentityError,
+  OrgError,
+  PairingError,
+  mapNativeError,
+} from './errors'
+
+export {
+  parseIdentityDid,
+  parseDeviceDid,
+  SignerType,
+  Role,
+  WellKnownCapability,
+  type IdentityDID,
+  type DeviceDID,
+  type BundleAttestation,
+  type IdentityBundle,
+} from './types'
+
+import native from './native'
+export const version: () => string = native.version