@forge-sdk/identity

import * as api from '@forge-sdk/identity';

export interface OasDocument {
  /** The DID identifier. */
  readonly id: string;
  /** The DID document context. */
  readonly context: readonly string[];
  /** Verification methods. */
  readonly verificationMethod: readonly VerificationMethod[];
  /** Authentication references. */
  readonly authentication: readonly string[];
  /** Optional lineage section for derived identities. */
  readonly lineage?: LineageSection;
  /** Optional document proof. */
  readonly proof?: DocumentProof;
}

export interface VerificationMethod {
  /** The method identifier. */
  readonly id: string;
  /** The method type. */
  readonly type: string;
  /** The controller DID. */
  readonly controller: string;
  /** The public key in multibase encoding. */
  readonly publicKeyMultibase: string;
}

export interface LineageSection {
  /** The generation (derivation depth) of this entity. */
  readonly generation: number;
  /** The DID of the human root in the lineage chain. */
  readonly humanRootDid: string;
  /** The DID of the immediate parent. */
  readonly parentDid: string;
  /** The derivation path used. */
  readonly derivationPath: string;
  /** The lineage proof. */
  readonly proof: LineageProof;
}

export interface LineageProof {
  /** The proof type (e.g., 'AgentLineageProof2025'). */
  readonly type: string;
  /** The ISO 8601 creation timestamp. */
  readonly created: string;
  /** The verification method used to create the proof. */
  readonly verificationMethod: string;
  /** The proof value (base64url-encoded signature). */
  readonly proofValue: string;
}

export interface DocumentProof {
  /** The proof type. */
  readonly type: string;
  /** The ISO 8601 creation timestamp. */
  readonly created: string;
  /** The verification method used to create the proof. */
  readonly verificationMethod: string;
  /** The proof value (base64url-encoded signature). */
  readonly proofValue: string;
}

export interface CryptoBridge {
  /** Generates a new Ed25519 keypair. Returns [privateKey, publicKey]. */
  generateKeypair(): [Uint8Array, Uint8Array];
  /** Signs a message with the given private key. Returns a 64-byte signature. */
  sign(privateKey: Uint8Array, message: Uint8Array): Uint8Array;
  /** Verifies a signature. Returns true if valid. */
  verify(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): boolean;
  /** Derives a child key via HKDF-SHA256. Returns [childPrivateKey, childPublicKey]. */
  deriveChild(parentPrivateKey: Uint8Array, path: string): [Uint8Array, Uint8Array];
}

export class ForgeAgentIdentity {
  constructor(
    did: string,
    kind: string,
    privateKey: Uint8Array,
    publicKey: Uint8Array,
    document: OasDocument,
    lineageDepth: number,
    bridge: CryptoBridge
  );
  did(): string;
  kind(): string;
  document(): OasDocument;
  lineageDepth(): number;
  sign(message: Uint8Array): Uint8Array;
  verify(message: Uint8Array, signature: Uint8Array): void;
  verifyingKeyBytes(): Uint8Array;
  toString(): string;
  _privateKeyBytes(): Uint8Array;
  _cryptoBridge(): CryptoBridge;
}

export const ForgeIdentityErrorCode /* type inferred in source */;

export type ForgeIdentityErrorCodeType =
  (typeof ForgeIdentityErrorCode)[keyof typeof ForgeIdentityErrorCode];

export class ForgeIdentityError extends Error {
  public readonly code: ForgeIdentityErrorCodeType;
  static derivationFailed(parentDid: string, path: string, reason: string): ForgeIdentityError;
  static lineageVerificationFailed(did: string, reason: string): ForgeIdentityError;
  static chainTooDeep(depth: number, maxDepth: number): ForgeIdentityError;
  static invalidIdentity(reason: string): ForgeIdentityError;
  static persistenceFailed(reason: string): ForgeIdentityError;
  static wasmBridgeError(reason: string): ForgeIdentityError;
}

export interface GlyphColor {
  /** Red channel (0-255). */
  readonly r: number;
  /** Green channel (0-255). */
  readonly g: number;
  /** Blue channel (0-255). */
  readonly b: number;
}

export function glyphColorRgb(r: number, g: number, b: number): GlyphColor;

export function glyphColorToHex(c: GlyphColor): string;

export function glyphColorLerp(
  a: GlyphColor,
  b: GlyphColor,
  t: number,
): GlyphColor;

export interface GlyphPalette {
  /** Primary identity color. */
  readonly primary: GlyphColor;
  /** Secondary identity color (hue-offset from primary). */
  readonly secondary: GlyphColor;
  /** Accent color for kind region and highlights. */
  readonly accent: GlyphColor;
  /** Background color (dark, desaturated primary). */
  readonly background: GlyphColor;
}

export const GlyphEntityKind /* type inferred in source */;

export type GlyphEntityKind = (typeof GlyphEntityKind)[keyof typeof GlyphEntityKind];

export function parseGlyphEntityKind(s: string): GlyphEntityKind | undefined;

export function glyphEntityKindAsU8(kind: GlyphEntityKind): number;

export function glyphEntityKindFromU8(v: number): GlyphEntityKind | undefined;

export interface GlyphDescriptor {
  /** The agent's DID string (e.g. `did:oas:l1fe:agent:data-analyst`). */
  readonly did: string;
  /** The entity kind that determines the kind-region visual motif. */
  readonly kind: GlyphEntityKind;
  /** Optional human-readable label rendered below the glyph. */
  readonly label?: string;
}

export const GlyphRenderTarget /* type inferred in source */;

export type GlyphRenderTarget =
  (typeof GlyphRenderTarget)[keyof typeof GlyphRenderTarget];

export interface GlyphRenderOptions {
  /** The render target (Web or Terminal). */
  readonly target: GlyphRenderTarget;
  /** Desired width in pixels (Web) or columns (Terminal). */
  readonly width?: number;
  /** Desired height in pixels (Web) or rows (Terminal). */
  readonly height?: number;
  /** Optional background color override. */
  readonly colorOverride?: GlyphColor;
}

export const GlyphRenderFormat /* type inferred in source */;

export type GlyphRenderFormat =
  (typeof GlyphRenderFormat)[keyof typeof GlyphRenderFormat];

export interface GlyphRenderResult {
  /** The output format. */
  readonly format: GlyphRenderFormat;
  /** The rendered data as a string (SVG, ANSI, etc.). */
  readonly data: string;
  /** Width of the rendered output. */
  readonly width: number;
  /** Height of the rendered output. */
  readonly height: number;
}

export async function derivePaletteFromDid(
  did: string,
  kind: GlyphEntityKind,
): Promise<GlyphPalette>;

export function derivePaletteFromDidSync(
  did: string,
  kind: GlyphEntityKind,
): GlyphPalette;

export function renderGlyph(
  descriptor: GlyphDescriptor,
  options: GlyphRenderOptions,
): GlyphRenderResult;

export {
  ForgeIdentityError,
  ForgeIdentityErrorCode,
  type ForgeIdentityErrorCodeType,
} from './error.js';

export {
  ForgeAgentIdentity,
  type CryptoBridge,
  type OasDocument,
  type VerificationMethod,
  type LineageSection,
  type LineageProof,
  type DocumentProof,
} from './agent-identity.js';

export {
  createHmrIdentity,
  createMhrIdentity,
  deriveAgentIdentity,
  setCryptoBridge,
  getCryptoBridge,
  DEFAULT_MAX_LINEAGE_DEPTH,
} from './lineage.js';

export {
  saveIdentity,
  loadIdentity,
  type ProtectedSigningKey,
  type IdentityKeyProtector,
} from './persistence.js';

export {
  type GlyphColor,
  glyphColorRgb,
  glyphColorToHex,
  glyphColorLerp,
  type GlyphPalette,
  GlyphEntityKind,
  parseGlyphEntityKind,
  glyphEntityKindAsU8,
  glyphEntityKindFromU8,
  type GlyphDescriptor,
  GlyphRenderTarget,
  type GlyphRenderOptions,
  GlyphRenderFormat,
  type GlyphRenderResult,
  derivePaletteFromDid,
  derivePaletteFromDidSync,
  renderGlyph,
} from './glyph.js';

export {
  FORGE_DEV_METHOD,
  forgeDevDid,
  deriveMachineId,
  deriveMachineIdSync,
  validateForgeDevDid,
  type LocalOrg,
  createLocalOrg,
  type ForgeDevIdentity,
  type LocalDevProfile,
  PROFILE_SCHEMA_VERSION,
  createLocalDevProfile,
  deriveAgent,
  profileToJSON,
  profileFromJSON,
} from './local-dev.js';

export const DEFAULT_MAX_LINEAGE_DEPTH /* type inferred in source */;

export function setCryptoBridge(bridge: CryptoBridge): void;

export function getCryptoBridge(): CryptoBridge;

export function createHmrIdentity(
  namespace: string,
  identifier: string,
  bridge?: CryptoBridge
): ForgeAgentIdentity;

export function createMhrIdentity(
  namespace: string,
  identifier: string,
  bridge?: CryptoBridge
): ForgeAgentIdentity;

export function deriveAgentIdentity(
  parent: ForgeAgentIdentity,
  name: string,
  namespace: string,
  bridge?: CryptoBridge
): ForgeAgentIdentity;

export const FORGE_DEV_METHOD /* type inferred in source */;

export function forgeDevDid(
  machineId: string,
  kind: string,
  identifier: string,
): string;

export async function deriveMachineId(
  hostname: string,
  username: string,
  profileName: string,
): Promise<string>;

export function deriveMachineIdSync(
  hostname: string,
  username: string,
  profileName: string,
): string;

export function validateForgeDevDid(did: string): boolean;

export interface LocalOrg {
  /** Deterministic org ID. Format: `forge-dev-org:<name>`. */
  readonly id: string;
  /** Human-readable org name. */
  readonly name: string;
}

export function createLocalOrg(name: string): LocalOrg;

export interface ForgeDevIdentity {
  /** The `did:forge-dev` identifier string. */
  readonly did: string;
  /** The entity kind (e.g., "mhr", "agent"). */
  readonly kind: string;
  /** The lineage depth from the root. */
  readonly lineageDepth: number;
  /** The org ID this identity belongs to. */
  readonly orgId: string;
  /** ISO 8601 creation timestamp. */
  readonly createdAt: string;
  /** Schema version for forward compatibility. */
  readonly schemaVersion: number;
}

export interface LocalDevProfile {
  /** The local developer's root identity. */
  readonly root: ForgeDevIdentity;
  /** The local organization context. */
  readonly org: LocalOrg;
  /** Registry of derived agent identities, keyed by agent name. */
  readonly agents: Readonly<Record<string, ForgeDevIdentity>>;
  /** The 16-character hex machine identifier. */
  readonly machineId: string;
  /** The profile name (e.g., "default", "alice"). */
  readonly profileName: string;
}

export const PROFILE_SCHEMA_VERSION /* type inferred in source */;

export function createLocalDevProfile(
  machineId: string,
  profileName: string,
): LocalDevProfile;

export function deriveAgent(
  profile: LocalDevProfile,
  agentName: string,
): LocalDevProfile;

export function profileToJSON(
  profile: LocalDevProfile,
): Record<string, unknown>;

export function profileFromJSON(
  data: Record<string, unknown>,
): LocalDevProfile;

export interface ProtectedSigningKey {
  /** Protection scheme identifier (for example `aws-kms-envelope`). */
  scheme: string;
  /** Opaque serialized payload for the selected scheme. */
  payload: string;
  /** Optional key reference for KMS or secure-store lookups. */
  keyId?: string;
}

export interface IdentityKeyProtector {
  /**
   * Protects a signing key before persistence.
   *
   * Implementations should encrypt, seal, or securely externalize the key.
   */
  protect(signingKey: Uint8Array): Promise<ProtectedSigningKey>;
  /**
   * Restores a protected signing key from persisted storage.
   *
   * Implementations must return the raw Ed25519 signing key bytes.
   */
  unprotect(protectedSigningKey: ProtectedSigningKey): Promise<Uint8Array>;
}

export async function saveIdentity(
  identity: ForgeAgentIdentity,
  protector?: IdentityKeyProtector
): Promise<string>;

export async function loadIdentity(
  json: string,
  protector?: IdentityKeyProtector,
  bridge?: CryptoBridge
): Promise<ForgeAgentIdentity>;