Keys, trust, and signatures

export interface AllowedSignerPrincipalLookupOptions {
    /** Lookup instant. Numbers and bigints are Unix seconds; Dates are converted to seconds. */
    at?: Date | number | bigint;
    /** Optional revocation policy applied before returning principals. */
    revocations?: KeyRevocationList;
}

/** OpenSSH allowed-signers policy with integrated detached-signature verification. */
export default class AllowedSigners {
    static parse(content: string | Buffer): AllowedSigners;
    static load(path: string): Promise<AllowedSigners>;
    /** Returns the policy principal fields whose pattern lists positively match this value. */
    matchPrincipals(principal: string): readonly string[];
    /** Finds the first entry's principals authorized for an embedded signature key. */
    findPrincipals(signature: SSHSignature | string | Buffer, options?: AllowedSignerPrincipalLookupOptions): readonly string[];
    verify(message: Buffer, signature: SSHSignature | string | Buffer, options: AllowedSignerVerificationOptions): boolean;
}

export interface AllowedSignerVerificationOptions {
    /** Expected signer identity matched against the entry and any user certificate principals. */
    principal: string;
    /** Expected SSHSIG namespace and allowed-signers namespace pattern input. */
    namespace: string;
    /** Verification instant. Numbers and bigints are Unix seconds; Dates are converted to seconds. */
    at?: Date | number | bigint;
    /** Optional revocation policy applied to the embedded signing key or certificate. */
    revocations?: KeyRevocationList;
}

export interface EncodedSecurityKeySignatureData {
    flags: number;
    counter: number;
    webAuthn?: EncodedWebAuthnSignatureData;
}

export default class EncodedSignature {
    data: EncodedSignatureData;
    constructor(data: EncodedSignatureData);
    serialize(): Buffer;
    static parse(raw: Buffer): EncodedSignature;
}

export interface EncodedSignatureData {
    alg: string;
    data: Buffer;
    securityKey?: EncodedSecurityKeySignatureData;
}

export interface EncodedWebAuthnSignatureData {
    origin: string;
    clientData: Buffer;
    extensions: Buffer;
}

export interface GeneratedKeyPair {
    readonly privateKey: PrivateKey;
    readonly publicKey: PublicKey;
}

/** Generate a supported SSH key pair using Node's cryptographic random source. */
export declare function generateKeyPair(type: KeyPairType, options?: GenerateKeyPairOptions): Promise<GeneratedKeyPair>;

export interface GenerateKeyPairOptions {
    /** RSA modulus or ECDSA curve size. RSA defaults to 3072; ECDSA defaults to 256; fixed-size keys reject it. */
    bits?: number;
    /** Optional comment embedded in both OpenSSH serializations. */
    comment?: string;
}

/** Generate a supported SSH key pair synchronously using Node's cryptographic random source. */
export declare function generateKeyPairSync(type: KeyPairType, options?: GenerateKeyPairOptions): GeneratedKeyPair;

export type KeyPairType = "ed25519" | "ed448" | "rsa" | "ecdsa" | "dsa";

export default class KeyRevocationList {
    /** Monotonic version recorded in the KRL header. Rollback enforcement is application policy. */
    readonly version: bigint;
    /** KRL generation time as unsigned Unix seconds. */
    readonly generatedAt: bigint;
    /** Human-readable KRL header comment. */
    readonly comment: string;
    static parse(content: Buffer): KeyRevocationList;
    static load(path: string): Promise<KeyRevocationList>;
    /** Tests plain keys and all applicable certificate, embedded-key, and authority records. */
    isRevoked(key: PublicKey | Buffer): boolean;
    /** Returns whether an embedded, cryptographically verified signature uses this exact key. */
    isSignedBy(key: PublicKey | Buffer): boolean;
}

export interface KnownHostCheckResult {
    readonly status: KnownHostStatus;
    readonly line?: number;
    readonly key?: PublicKey;
}

export type KnownHostMarker = "cert-authority" | "revoked";

export default class KnownHosts {
    static parse(content: string | Buffer): KnownHosts;
    static load(path: string): Promise<KnownHosts>;
    check(hostname: string, key: PublicKey | Buffer, port?: number): KnownHostCheckResult;
    assertTrusted(hostname: string, key: PublicKey | Buffer, port?: number): void;
    hostKeyHook(hostname: string, port?: number): Hook<ClientHooker["hostKey"]>;
    replaceHostKeys(hostname: string, keys: readonly (PublicKey | string | Buffer)[], options?: KnownHostsReplaceOptions): Promise<void>;
    toString(): string;
}

export declare class KnownHostsError extends Error {
    readonly status: Exclude<KnownHostStatus, "trusted">;
    readonly line?: number;
    constructor(result: KnownHostCheckResult, host: string);
}

export interface KnownHostsReplaceOptions {
    /** SSH port. Port 22 uses the bare hostname; other ports use `[hostname]:port`. */
    port?: number;
    /** Store one independently salted HMAC-SHA1 hostname for each key. */
    hashHostname?: boolean;
}

export type KnownHostStatus = "trusted" | "unknown" | "changed" | "revoked";

export type ParsedKey = PrivateKey | PublicKey;

export declare function parseKey(data: string | Buffer, passphrase?: string | Buffer): ParsedKey;

export declare function parseKeys(data: string | Buffer, passphrase?: string | Buffer): ParsedKey[];

export declare function parseRFC4716PublicKey(data: string | Buffer): PublicKey;

export declare function parseRFC4716PublicKeyFile(data: string | Buffer): RFC4716PublicKeyFile;

export default class PrivateKey {
    static algorithms: Map<string, typeof PrivateKeyAlgorithm>;
    data: PrivateKeyData;
    constructor(data: PrivateKeyData);
    sign(data: Buffer, algorithm?: string): EncodedSignature;
    equals(other: PrivateKey): boolean;
    withCertificate(certificate: PublicKey): PrivateKey;
    serialize(options?: OpenSSHPrivateKeyEncryptionOptions): Buffer;
    static serializeMany(keys: readonly PrivateKey[], options?: OpenSSHPrivateKeyEncryptionOptions): Buffer;
    static parse(raw: Buffer, passphrase?: string | Buffer): PrivateKey;
    static parseAll(raw: Buffer, passphrase?: string | Buffer): PrivateKey[];
    toString(options?: OpenSSHPrivateKeyEncryptionOptions): string;
    /** Export the locally held private scalar as unencrypted PKCS#8 PEM. */
    toPEM(): string;
    static toStringMany(keys: readonly PrivateKey[], options?: OpenSSHPrivateKeyEncryptionOptions): string;
    static fromString(data: string, passphrase?: string | Buffer): PrivateKey;
    static fromStringAll(data: string, passphrase?: string | Buffer): PrivateKey[];
    static fromPuTTY(data: string | Buffer, passphrase?: string | Buffer): PrivateKey;
    static fromPEM(data: string, passphrase?: string | Buffer): PrivateKey;
    static generate(alg: string): Promise<PrivateKey>;
    static generateSync(alg: string): PrivateKey;
}

export declare abstract class PrivateKeyAlgorithm {
    static alg_name: string;
    constructor(data: unknown);
    sign(data: Buffer, algorithm?: string): EncodedSignature;
    getPublicKey(): PublicKey;
    serialize(): Buffer;
    static parse(raw: Buffer): [
        PrivateKeyAlgorithm,
        Buffer
    ];
    static generate(): Promise<PrivateKey>;
    static generateSync(): PrivateKey;
}

export interface PrivateKeyData {
    publicKey: PublicKey;
    alg: string;
    algorithm: PrivateKeyAlgorithm;
    comment?: string;
}

export default class PublicKey {
    static algorithms: Map<string, typeof PublicKeyAlgorithm>;
    data: PublicKeyData;
    constructor(data: PublicKeyData);
    get signatureAlgorithms(): readonly string[];
    supportsSignatureAlgorithm(algorithm: string): boolean;
    signatureAlgorithmFor(algorithm: string): string;
    verifySignature(data: Buffer, signature: EncodedSignature): boolean;
    toString(): string;
    /** Export the underlying cryptographic public key as SubjectPublicKeyInfo PEM. */
    toPEM(): string;
    hash(algorithm: "md5" | "sha256" | "sha512"): string;
    serialize(): Buffer;
    equals(other: PublicKey): boolean;
    static parse(raw: Buffer): PublicKey;
    static parseString(content: string): PublicKey;
    static fromPEM(data: string | Buffer): PublicKey;
    static parseAuthorizedKeysFile(content: string): PublicKey[];
}

export declare abstract class PublicKeyAlgorithm {
    static alg_name: string;
    static has_encryption: boolean;
    static has_signature: boolean;
    constructor(data: unknown);
    verifySignature(data: Buffer, signature: Buffer, algorithm?: string, securityKey?: EncodedSecurityKeySignatureData): boolean;
    serialize(): Buffer;
    equals(other: PublicKeyAlgorithm): boolean;
    static parse(raw: Buffer): PublicKeyAlgorithm;
}

export interface PublicKeyData {
    alg: string;
    algorithm: PublicKeyAlgorithm;
    comment?: string;
}

export interface RFC4716Header {
    readonly tag: string;
    readonly value: string;
}

export interface RFC4716PublicKeyFile {
    readonly publicKey: PublicKey;
    readonly headers: readonly Readonly<RFC4716Header>[];
}

/** Opaque enrollment evidence stored in the published security-key attestation format. */
export default class SecurityKeyAttestation {
    readonly format: SecurityKeyAttestationFormat;
    readonly flags: number;
    get certificate(): Buffer;
    get enrollmentSignature(): Buffer;
    get authenticatorData(): Buffer | undefined;
    get reserved(): Buffer;
    static parse(content: Buffer): SecurityKeyAttestation;
    static load(path: string): Promise<SecurityKeyAttestation>;
    serialize(): Buffer;
}

export type SecurityKeyAttestationFormat = "ssh-sk-attest-v00" | "ssh-sk-attest-v01";

export declare function serializeRFC4716PublicKey(publicKey: PublicKey, headers?: readonly RFC4716Header[]): string;

export declare const SSH_ECDSA_SECURITY_KEY_ALGORITHM = "sk-ecdsa-sha2-nistp256@openssh.com";

export declare const SSH_ED25519_SECURITY_KEY_ALGORITHM = "sk-ssh-ed25519@openssh.com";

export declare const SSH_WEBAUTHN_ECDSA_SECURITY_KEY_ALGORITHM = "webauthn-sk-ecdsa-sha2-nistp256@openssh.com";

export interface SSHCertificateData {
    readonly nonce: Buffer;
    readonly publicKey: PublicKey;
    readonly serial: bigint;
    readonly role: SSHCertificateRole;
    readonly identifier: string;
    readonly principals: readonly string[];
    readonly validAfter: bigint;
    readonly validBefore: bigint;
    readonly criticalOptions: readonly SSHCertificateOption[];
    readonly extensions: readonly SSHCertificateOption[];
    readonly reserved: Buffer;
    readonly signatureKey: PublicKey;
    readonly signature: EncodedSignature;
}

export interface SSHCertificateOption {
    readonly name: string;
    readonly data: Buffer;
}

export declare class SSHCertificatePublicKey implements PublicKeyAlgorithm {
    static has_encryption: boolean;
    static has_signature: boolean;
    readonly algorithmName: string;
    readonly data: SSHCertificateData;
    get publicKey(): PublicKey;
    verifyCertificateSignature(): boolean;
    verifyHostCertificate(hostname: string, at?: bigint): boolean;
    verifySignature(data: Buffer, signature: Buffer, algorithm?: string, securityKey?: EncodedSecurityKeySignatureData): boolean;
    serialize(): Buffer;
    equals(other: PublicKeyAlgorithm): boolean;
    static parse(algorithmName: string, keyAlgorithm: string, payload: Buffer): SSHCertificatePublicKey;
}

export type SSHCertificateRole = "user" | "host";

export declare class SSHECDSASecurityKeyPrivateKey implements PrivateKeyAlgorithm {
    static alg_name: string;
    readonly data: SSHECDSASecurityKeyPrivateKeyData;
    constructor(data: SSHECDSASecurityKeyPrivateKeyData);
    sign(): EncodedSignature;
    getPublicKey(): PublicKey;
    serialize(): Buffer;
    static parse(raw: Buffer): [
        PrivateKeyAlgorithm,
        Buffer
    ];
    static generate(): Promise<PrivateKey>;
    static generateSync(): PrivateKey;
}

export interface SSHECDSASecurityKeyPrivateKeyData {
    publicKey: Buffer;
    application: string;
    flags: number;
    keyHandle: Buffer;
    reserved: Buffer;
}

export declare class SSHECDSASecurityKeyPublicKey implements PublicKeyAlgorithm {
    static alg_name: string;
    static has_encryption: boolean;
    static has_signature: boolean;
    readonly data: SSHECDSASecurityKeyPublicKeyData;
    constructor(data: SSHECDSASecurityKeyPublicKeyData);
    verifySignature(data: Buffer, signature: Buffer, algorithm?: string, securityKey?: EncodedSecurityKeySignatureData): boolean;
    serialize(): Buffer;
    equals(other: PublicKeyAlgorithm): boolean;
    static parse(raw: Buffer): SSHECDSASecurityKeyPublicKey;
}

export interface SSHECDSASecurityKeyPublicKeyData {
    publicKey: Buffer;
    application: string;
}

export declare class SSHED25519SecurityKeyPrivateKey implements PrivateKeyAlgorithm {
    static alg_name: string;
    readonly data: SSHED25519SecurityKeyPrivateKeyData;
    constructor(data: SSHED25519SecurityKeyPrivateKeyData);
    sign(): EncodedSignature;
    getPublicKey(): PublicKey;
    serialize(): Buffer;
    static parse(raw: Buffer): [
        PrivateKeyAlgorithm,
        Buffer
    ];
    static generate(): Promise<PrivateKey>;
    static generateSync(): PrivateKey;
}

export interface SSHED25519SecurityKeyPrivateKeyData {
    publicKey: Buffer;
    application: string;
    flags: number;
    keyHandle: Buffer;
    reserved: Buffer;
}

export declare class SSHED25519SecurityKeyPublicKey implements PublicKeyAlgorithm {
    static alg_name: string;
    static has_encryption: boolean;
    static has_signature: boolean;
    readonly data: SSHED25519SecurityKeyPublicKeyData;
    constructor(data: SSHED25519SecurityKeyPublicKeyData);
    verifySignature(data: Buffer, signature: Buffer, algorithm?: string, securityKey?: EncodedSecurityKeySignatureData): boolean;
    serialize(): Buffer;
    equals(other: PublicKeyAlgorithm): boolean;
    static parse(raw: Buffer): SSHED25519SecurityKeyPublicKey;
}

export interface SSHED25519SecurityKeyPublicKeyData {
    publicKey: Buffer;
    application: string;
}

/** DNS SSHFP public-key algorithm numbers assigned by the IANA registry. */
export declare enum SSHFPAlgorithm {
    RSA = 1,
    DSA = 2,
    ECDSA = 3,
    Ed25519 = 4,
    Ed448 = 6
}

/** DNS SSHFP fingerprint-type numbers assigned by the IANA registry. */
export declare enum SSHFPFingerprintType {
    SHA1 = 1,
    SHA256 = 2
}

/**
 * One SSHFP RDATA value. DNS owner names, TTLs, and DNSSEC validation state are deliberately not
 * part of this value object.
 */
export default class SSHFPRecord {
    readonly algorithm: number;
    readonly fingerprintType: number;
    constructor(algorithm: number, fingerprintType: number, fingerprint: Buffer);
    /** A defensive copy of the opaque fingerprint bytes. */
    get fingerprint(): Buffer;
    /** Parses the complete binary RDATA of one SSHFP resource record. */
    static parse(rdata: Buffer): SSHFPRecord;
    /**
     * Parses the presentation-format RDATA fields, without a DNS owner name, class, TTL, or `SSHFP`
     * mnemonic.
     */
    static parseText(rdata: string): SSHFPRecord;
    /** Generates a fingerprint over the exact SSH public-key blob. SHA-256 is the default. */
    static fromPublicKey(publicKey: PublicKey, fingerprintType?: SSHFPFingerprintType): SSHFPRecord;
    serialize(): Buffer;
    /** Returns the three presentation-format RDATA fields accepted by DNS zone-file tools. */
    toString(): string;
}

export type SSHFPVerificationResult = "match" | "mismatch" | "no-supported-records";

/** OpenSSH-compatible detached signatures with mandatory namespace-bound verification. */
export default class SSHSignature {
    readonly version: number;
    readonly publicKey: PublicKey;
    readonly hashAlgorithm: SSHSignatureHashAlgorithm;
    readonly signature: EncodedSignature;
    /** Namespace bytes retained by the detached signature. */
    get namespace(): Buffer;
    /** Reserved format bytes. Version 1 signers emit an empty value. */
    get reserved(): Buffer;
    static sign(message: Buffer, privateKey: PrivateKey, options: SSHSignatureOptions): SSHSignature;
    static signWithAgent<Id>(message: Buffer, agent: Agent<Id>, id: Id, options: SSHSignatureOptions): Promise<SSHSignature>;
    static parse(content: string | Buffer): SSHSignature;
    verify(message: Buffer, expectedNamespace: string | Buffer): boolean;
    serialize(): Buffer;
    toString(): string;
}

export type SSHSignatureHashAlgorithm = "sha256" | "sha512";

export interface SSHSignatureOptions {
    /** Application domain that prevents a signature from being reused by another protocol. */
    namespace: string | Buffer;
    /** Message digest placed in the signed preimage. Defaults to `sha512`. */
    hashAlgorithm?: SSHSignatureHashAlgorithm;
}

/**
 * Verifies one public key against an authenticated SSHFP RRset.
 *
 * The caller must establish the owner name and DNSSEC authenticity before treating `match` as
 * trust. SHA-256 records take precedence over SHA-1 records as required by RFC 6594.
 */
export declare function verifySSHFP(publicKey: PublicKey, records: readonly SSHFPRecord[]): SSHFPVerificationResult;