@auths-dev/sdk 0.0.1 → 0.1.0

package/lib/signing.ts

@@ -0,0 +1,204 @@
+import native from './native'
+import { mapNativeError, CryptoError } from './errors'
+import type { Auths } from './client'
+
+/** Result of a signing operation. */
+export interface SignResult {
+  /** Hex-encoded Ed25519 signature. */
+  signature: string
+  /** DID of the signer. */
+  signerDid: string
+}
+
+/** A signed action envelope containing the payload and its signature. */
+export interface ActionEnvelope {
+  /** JSON-serialized envelope with action metadata. */
+  envelopeJson: string
+  /** Hex-encoded signature over the envelope. */
+  signatureHex: string
+  /** DID of the signer. */
+  signerDid: string
+}
+
+/** Options for {@link SigningService.signAsIdentity}. */
+export interface SignAsIdentityOptions {
+  /** The message bytes to sign. */
+  message: Buffer
+  /** DID of the identity to sign with. */
+  identityDid: string
+  /** Override the client's passphrase. */
+  passphrase?: string
+}
+
+/** Options for {@link SigningService.signActionAsIdentity}. */
+export interface SignActionAsIdentityOptions {
+  /** Action type label (e.g. `'tool_call'`). */
+  actionType: string
+  /** JSON-serialized action payload. */
+  payloadJson: string
+  /** DID of the identity to sign with. */
+  identityDid: string
+  /** Override the client's passphrase. */
+  passphrase?: string
+}
+
+/** Options for {@link SigningService.signAsAgent}. */
+export interface SignAsAgentOptions {
+  /** The message bytes to sign. */
+  message: Buffer
+  /** Keychain alias of the agent key. */
+  keyAlias: string
+  /** Override the client's passphrase. */
+  passphrase?: string
+}
+
+/** Options for {@link SigningService.signActionAsAgent}. */
+export interface SignActionAsAgentOptions {
+  /** Action type label (e.g. `'tool_call'`). */
+  actionType: string
+  /** JSON-serialized action payload. */
+  payloadJson: string
+  /** Keychain alias of the agent key. */
+  keyAlias: string
+  /** DID of the agent identity. */
+  agentDid: string
+  /** Override the client's passphrase. */
+  passphrase?: string
+}
+
+/**
+ * Signs messages and actions using identity or agent keys.
+ *
+ * Access via {@link Auths.signing}.
+ *
+ * @example
+ * ```typescript
+ * const result = auths.signing.signAsIdentity({
+ *   message: Buffer.from('hello world'),
+ *   identityDid: identity.did,
+ * })
+ * console.log(result.signature) // hex-encoded Ed25519 signature
+ * ```
+ */
+export class SigningService {
+  constructor(private client: Auths) {}
+
+  /**
+   * Signs a message as an identity.
+   *
+   * @param opts - Signing options.
+   * @returns The signature and signer DID.
+   * @throws {@link CryptoError} if the key is missing or signing fails.
+   *
+   * @example
+   * ```typescript
+   * const result = auths.signing.signAsIdentity({
+   *   message: Buffer.from('hello'),
+   *   identityDid: identity.did,
+   * })
+   * ```
+   */
+  signAsIdentity(opts: SignAsIdentityOptions): SignResult {
+    const pp = opts.passphrase ?? this.client.passphrase
+    try {
+      const result = native.signAsIdentity(
+        opts.message,
+        opts.identityDid,
+        this.client.repoPath,
+        pp,
+      )
+      return { signature: result.signature, signerDid: result.signerDid }
+    } catch (err) {
+      throw mapNativeError(err, CryptoError)
+    }
+  }
+
+  /**
+   * Signs a structured action as an identity, producing a verifiable envelope.
+   *
+   * @param opts - Action signing options.
+   * @returns The signed action envelope.
+   * @throws {@link CryptoError} if signing fails.
+   *
+   * @example
+   * ```typescript
+   * const envelope = auths.signing.signActionAsIdentity({
+   *   actionType: 'tool_call',
+   *   payloadJson: '{"tool":"read_file"}',
+   *   identityDid: identity.did,
+   * })
+   * ```
+   */
+  signActionAsIdentity(opts: SignActionAsIdentityOptions): ActionEnvelope {
+    const pp = opts.passphrase ?? this.client.passphrase
+    try {
+      return native.signActionAsIdentity(
+        opts.actionType,
+        opts.payloadJson,
+        opts.identityDid,
+        this.client.repoPath,
+        pp,
+      )
+    } catch (err) {
+      throw mapNativeError(err, CryptoError)
+    }
+  }
+
+  /**
+   * Signs a message as an agent using its keychain alias.
+   *
+   * @param opts - Agent signing options.
+   * @returns The signature and signer DID.
+   * @throws {@link CryptoError} if the key is missing or signing fails.
+   *
+   * @example
+   * ```typescript
+   * const result = auths.signing.signAsAgent({
+   *   message: Buffer.from('payload'),
+   *   keyAlias: agent.keyAlias,
+   * })
+   * ```
+   */
+  signAsAgent(opts: SignAsAgentOptions): SignResult {
+    const pp = opts.passphrase ?? this.client.passphrase
+    try {
+      const result = native.signAsAgent(opts.message, opts.keyAlias, this.client.repoPath, pp)
+      return { signature: result.signature, signerDid: result.signerDid }
+    } catch (err) {
+      throw mapNativeError(err, CryptoError)
+    }
+  }
+
+  /**
+   * Signs a structured action as an agent.
+   *
+   * @param opts - Agent action signing options.
+   * @returns The signed action envelope.
+   * @throws {@link CryptoError} if signing fails.
+   *
+   * @example
+   * ```typescript
+   * const envelope = auths.signing.signActionAsAgent({
+   *   actionType: 'tool_call',
+   *   payloadJson: '{"tool":"execute"}',
+   *   keyAlias: agent.keyAlias,
+   *   agentDid: agent.did,
+   * })
+   * ```
+   */
+  signActionAsAgent(opts: SignActionAsAgentOptions): ActionEnvelope {
+    const pp = opts.passphrase ?? this.client.passphrase
+    try {
+      return native.signActionAsAgent(
+        opts.actionType,
+        opts.payloadJson,
+        opts.keyAlias,
+        opts.agentDid,
+        this.client.repoPath,
+        pp,
+      )
+    } catch (err) {
+      throw mapNativeError(err, CryptoError)
+    }
+  }
+}

package/lib/trust.ts

@@ -0,0 +1,152 @@
+import native from './native'
+import { mapNativeError, StorageError } from './errors'
+import type { Auths } from './client'
+
+/**
+ * Trust level for a pinned identity.
+ *
+ * Values match the Rust `TrustLevel` enum in `auths-core/src/trust/pinned.rs`.
+ */
+export const TrustLevel = {
+  /** Accepted on first use (interactive prompt). */
+  Tofu: 'tofu',
+  /** Manually pinned via CLI or `--issuer-pk`. */
+  Manual: 'manual',
+  /** Loaded from roots.json org policy file. */
+  OrgPolicy: 'org_policy',
+} as const
+export type TrustLevel = (typeof TrustLevel)[keyof typeof TrustLevel]
+
+/** A pinned (trusted) identity in the local trust store. */
+export interface PinnedIdentity {
+  /** The pinned identity's DID. */
+  did: string
+  /** Optional label for the pinned identity. */
+  label: string | null
+  /** Trust level: `'tofu'`, `'manual'`, or `'org_policy'`. */
+  trustLevel: string
+  /** ISO 8601 timestamp when this identity was first seen. */
+  firstSeen: string
+  /** KERI event log sequence number at time of pinning, or `null`. */
+  kelSequence: number | null
+  /** ISO 8601 timestamp when this identity was pinned. */
+  pinnedAt: string
+}
+
+/** Options for {@link TrustService.pin}. */
+export interface PinIdentityOptions {
+  /** DID of the identity to pin. */
+  did: string
+  /** Optional label for the pinned identity. */
+  label?: string
+  /** Trust level to assign. Defaults to `'tofu'`. */
+  trustLevel?: 'tofu' | 'manual' | 'org_policy'
+}
+
+/**
+ * Manages the local trust store for pinning and querying trusted identities.
+ *
+ * Access via {@link Auths.trust}.
+ *
+ * @example
+ * ```typescript
+ * auths.trust.pin({ did: peer.did, label: 'alice' })
+ * const entries = auths.trust.list()
+ * ```
+ */
+export class TrustService {
+  constructor(private client: Auths) {}
+
+  /**
+   * Pins an identity as trusted in the local store.
+   *
+   * @param opts - Pin options.
+   * @returns The pinned identity entry.
+   * @throws {@link StorageError} if the pin operation fails.
+   *
+   * @example
+   * ```typescript
+   * const entry = auths.trust.pin({ did: identity.did, label: 'my-peer' })
+   * console.log(entry.trustLevel) // 'tofu'
+   * ```
+   */
+  pin(opts: PinIdentityOptions): PinnedIdentity {
+    try {
+      const result = native.pinIdentity(
+        opts.did,
+        this.client.repoPath,
+        opts.label ?? null,
+        opts.trustLevel ?? null,
+      )
+      return {
+        did: result.did,
+        label: result.label ?? null,
+        trustLevel: result.trustLevel,
+        firstSeen: result.firstSeen,
+        kelSequence: result.kelSequence ?? null,
+        pinnedAt: result.pinnedAt,
+      }
+    } catch (err) {
+      throw mapNativeError(err, StorageError)
+    }
+  }
+
+  /**
+   * Removes a pinned identity from the local trust store.
+   *
+   * @param did - DID of the identity to unpin.
+   * @throws {@link StorageError} if the operation fails.
+   */
+  remove(did: string): void {
+    try {
+      native.removePinnedIdentity(did, this.client.repoPath)
+    } catch (err) {
+      throw mapNativeError(err, StorageError)
+    }
+  }
+
+  /**
+   * Lists all pinned identities in the local trust store.
+   *
+   * @returns Array of pinned identity entries.
+   * @throws {@link StorageError} if the operation fails.
+   */
+  list(): PinnedIdentity[] {
+    try {
+      const json = native.listPinnedIdentities(this.client.repoPath)
+      return JSON.parse(json)
+    } catch (err) {
+      throw mapNativeError(err, StorageError)
+    }
+  }
+
+  /**
+   * Looks up a specific pinned identity by DID.
+   *
+   * @param did - DID to look up.
+   * @returns The pinned identity entry, or `null` if not found.
+   * @throws {@link StorageError} if the operation fails.
+   *
+   * @example
+   * ```typescript
+   * const entry = auths.trust.get('did:keri:EBfd...')
+   * if (entry) console.log(entry.label)
+   * ```
+   */
+  get(did: string): PinnedIdentity | null {
+    try {
+      const result = native.getPinnedIdentity(did, this.client.repoPath)
+      if (!result) return null
+      return {
+        did: result.did,
+        label: result.label ?? null,
+        trustLevel: result.trustLevel,
+        firstSeen: result.firstSeen,
+        kelSequence: result.kelSequence ?? null,
+        pinnedAt: result.pinnedAt,
+      }
+    } catch (err) {
+      throw mapNativeError(err, StorageError)
+    }
+  }
+}

package/lib/types.ts

@@ -0,0 +1,179 @@
+/**
+ * Branded DID types and identity bundle type definitions.
+ *
+ * These types mirror the JSON schema at `auths/schemas/identity-bundle-v1.json`
+ * and the Rust DID type system in `auths-verifier/src/types.rs`.
+ *
+ * @module
+ */
+
+// ── Branded DID Types ─────────────────────────────────────────────────
+
+declare const __brand: unique symbol
+type Brand<T, B extends string> = T & { readonly [__brand]: B }
+
+/**
+ * Identity DID — always `did:keri:...` format.
+ *
+ * Represents a KERI-based decentralized identity. Used for organizations
+ * and individual identities. Parse with {@link parseIdentityDid}.
+ */
+export type IdentityDID = Brand<string, 'IdentityDID'>
+
+/**
+ * Device DID — always `did:key:z...` format.
+ *
+ * Represents a device's ephemeral key-based identity. Used for device
+ * attestations and signing keys. Parse with {@link parseDeviceDid}.
+ */
+export type DeviceDID = Brand<string, 'DeviceDID'>
+
+/**
+ * Parse and validate an identity DID string.
+ *
+ * @param raw - A DID string that should start with `did:keri:`.
+ * @returns The validated DID as an `IdentityDID` branded type.
+ * @throws Error if the string does not start with `did:keri:`.
+ *
+ * @example
+ * ```typescript
+ * const did = parseIdentityDid('did:keri:EOrg123')
+ * // did is typed as IdentityDID
+ * ```
+ */
+export function parseIdentityDid(raw: string): IdentityDID {
+  if (!raw.startsWith('did:keri:')) {
+    throw new Error(`Expected did:keri: prefix, got: ${raw.slice(0, 20)}`)
+  }
+  return raw as IdentityDID
+}
+
+/**
+ * Parse and validate a device DID string.
+ *
+ * @param raw - A DID string that should start with `did:key:z`.
+ * @returns The validated DID as a `DeviceDID` branded type.
+ * @throws Error if the string does not start with `did:key:z`.
+ *
+ * @example
+ * ```typescript
+ * const did = parseDeviceDid('did:key:z6MkDevice...')
+ * // did is typed as DeviceDID
+ * ```
+ */
+export function parseDeviceDid(raw: string): DeviceDID {
+  if (!raw.startsWith('did:key:z')) {
+    throw new Error(`Expected did:key:z prefix, got: ${raw.slice(0, 20)}`)
+  }
+  return raw as DeviceDID
+}
+
+// ── Signer Type ───────────────────────────────────────────────────────
+
+/** The type of entity that produced a signature. */
+export const SignerType = {
+  Human: 'Human',
+  Agent: 'Agent',
+  Workload: 'Workload',
+} as const
+export type SignerType = (typeof SignerType)[keyof typeof SignerType]
+
+// ── Role ──────────────────────────────────────────────────────────────
+
+/** Organization member role. */
+export const Role = {
+  Admin: 'admin',
+  Member: 'member',
+  Readonly: 'readonly',
+} as const
+export type Role = (typeof Role)[keyof typeof Role]
+
+// ── Capability ────────────────────────────────────────────────────────
+
+/**
+ * Well-known capability identifiers.
+ *
+ * Custom capabilities can be any valid string (alphanumeric + `:` + `-` + `_`, max 64 chars).
+ * The `auths:` prefix is reserved.
+ */
+export const WellKnownCapability = {
+  SignCommit: 'sign_commit',
+  SignRelease: 'sign_release',
+  ManageMembers: 'manage_members',
+  RotateKeys: 'rotate_keys',
+} as const
+
+// ── Identity Bundle ───────────────────────────────────────────────────
+
+/**
+ * An attestation in the identity bundle's chain.
+ *
+ * Represents a 2-way key attestation between a primary identity and a device key.
+ * Matches `auths/schemas/attestation-v1.json`.
+ */
+export interface BundleAttestation {
+  /** Record identifier linking this attestation to its storage ref. */
+  rid: string
+  /** Schema version. */
+  version: number
+  /** DID of the issuing identity (`did:keri:...`). */
+  issuer: string
+  /** DID of the device being attested (`did:key:z...`). */
+  subject: string
+  /** Ed25519 public key of the device (32 bytes, hex-encoded). */
+  device_public_key: string
+  /** Device's Ed25519 signature over the canonical attestation data (hex-encoded). */
+  device_signature: string
+  /** Issuer's Ed25519 signature over the canonical attestation data (hex-encoded). */
+  identity_signature?: string
+  /** Capabilities this attestation grants. */
+  capabilities?: string[]
+  /** Role for org membership attestations. */
+  role?: Role | null
+  /** The type of entity that produced this signature. */
+  signer_type?: SignerType | null
+  /** DID of the attestation that delegated authority. */
+  delegated_by?: string | null
+  /** Creation timestamp (ISO 8601). */
+  timestamp?: string | null
+  /** Expiration timestamp (ISO 8601). */
+  expires_at?: string | null
+  /** Timestamp when the attestation was revoked (ISO 8601). */
+  revoked_at?: string | null
+  /** Optional human-readable note. */
+  note?: string | null
+  /** Optional arbitrary JSON payload. */
+  payload?: unknown
+}
+
+/**
+ * Identity bundle for stateless verification in CI/CD environments.
+ *
+ * Contains all the information needed to verify commit signatures without
+ * requiring access to the identity repository or daemon.
+ *
+ * Matches `auths/schemas/identity-bundle-v1.json`.
+ *
+ * @example
+ * ```typescript
+ * import { readFileSync } from 'node:fs'
+ * import type { IdentityBundle } from '@auths-dev/sdk'
+ *
+ * const bundle: IdentityBundle = JSON.parse(
+ *   readFileSync('.auths/identity-bundle.json', 'utf-8')
+ * )
+ * console.log(bundle.identity_did) // did:keri:E...
+ * ```
+ */
+export interface IdentityBundle {
+  /** The DID of the identity (`did:keri:...`). */
+  identity_did: string
+  /** The public key in hex format for signature verification (32 bytes, hex). */
+  public_key_hex: string
+  /** Chain of attestations linking the signing key to the identity. */
+  attestation_chain: BundleAttestation[]
+  /** UTC timestamp when this bundle was created (ISO 8601). */
+  bundle_timestamp: string
+  /** Maximum age in seconds before this bundle is considered stale. */
+  max_valid_for_secs: number
+}