@push.rocks/smartconfig 6.1.0 → 6.2.0

package/ts/sshagent/smartconfig.sshagentsecret.ts

@@ -0,0 +1,602 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  createPublicKey,
+  hkdfSync,
+  randomBytes,
+  verify,
+} from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import * as net from 'node:net';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import type { KeyValueStore } from '../classes.keyvaluestore.js';
+
+export type TSmartconfigSshKeyType = 'ssh-ed25519';
+export type TSmartconfigSecretFormat = 'ssh-agent-sign-v1';
+export type TSmartconfigSecretBoxAlgorithm = 'AES-256-GCM';
+export type TSmartconfigSecretPayloadEncoding = 'utf8';
+
+export interface ISmartconfigSshAgentSecretOptions {
+  agentSocket?: string;
+}
+
+export interface ISmartconfigSshAgentSecretEncryptOptions extends ISmartconfigSshAgentSecretOptions {
+  authorizedKey?: string;
+  authorizedKeyPath?: string;
+}
+
+export interface ISmartconfigSshAgentSecretDecryptOptions extends ISmartconfigSshAgentSecretOptions {}
+
+export interface ISmartconfigSshPublicKey {
+  type: TSmartconfigSshKeyType;
+  keyBlob: Buffer;
+  publicKeyBytes: Buffer;
+  comment: string;
+  fingerprint: string;
+  authorizedKey: string;
+}
+
+export interface ISmartconfigSshAgentIdentity extends ISmartconfigSshPublicKey {}
+
+export interface ISmartconfigSshAgentSignature {
+  algorithm: string;
+  signature: Buffer;
+  signatureBlob: Buffer;
+}
+
+export interface ISmartconfigSecretKeyHint {
+  format: 'openssh-authorized-key-v1';
+  authorizedKey: string;
+  fingerprint: string;
+}
+
+export interface ISmartconfigSecretPayload {
+  encoding: TSmartconfigSecretPayloadEncoding;
+}
+
+export interface ISmartconfigSecretKdf {
+  name: 'HKDF-SHA256';
+  salt: string;
+}
+
+export interface ISmartconfigSecretBox {
+  alg: TSmartconfigSecretBoxAlgorithm;
+  nonce: string;
+  ciphertext: string;
+  tag: string;
+}
+
+export interface ISmartconfigEncryptedValue {
+  __smartconfigSecret: TSmartconfigSecretFormat;
+  keyHint: ISmartconfigSecretKeyHint;
+  payload: ISmartconfigSecretPayload;
+  kdf: ISmartconfigSecretKdf;
+  box: ISmartconfigSecretBox;
+}
+
+const sshAgentFailure = 5;
+const sshAgentRequestIdentities = 11;
+const sshAgentIdentitiesAnswer = 12;
+const sshAgentSignRequest = 13;
+const sshAgentSignResponse = 14;
+const maxAgentResponseBytes = 16 * 1024 * 1024;
+const maxAgentIdentities = 1024;
+const defaultAgentTimeoutMs = 15_000;
+const secretFormat: TSmartconfigSecretFormat = 'ssh-agent-sign-v1';
+const aadEncoding: TSmartconfigSecretPayloadEncoding = 'utf8';
+
+class BinaryReader {
+  private offset = 0;
+
+  constructor(private readonly buffer: Buffer) {}
+
+  public readUInt8(): number {
+    this.ensureAvailable(1);
+    const value = this.buffer.readUInt8(this.offset);
+    this.offset += 1;
+    return value;
+  }
+
+  public readUInt32BE(): number {
+    this.ensureAvailable(4);
+    const value = this.buffer.readUInt32BE(this.offset);
+    this.offset += 4;
+    return value;
+  }
+
+  public readBuffer(lengthArg: number): Buffer {
+    this.ensureAvailable(lengthArg);
+    const value = this.buffer.subarray(this.offset, this.offset + lengthArg);
+    this.offset += lengthArg;
+    return value;
+  }
+
+  public readSshStringBuffer(): Buffer {
+    return this.readBuffer(this.readUInt32BE());
+  }
+
+  public readSshStringUtf8(): string {
+    return this.readSshStringBuffer().toString('utf8');
+  }
+
+  public get remainingBytes(): number {
+    return this.buffer.length - this.offset;
+  }
+
+  private ensureAvailable(lengthArg: number): void {
+    if (lengthArg < 0 || this.buffer.length - this.offset < lengthArg) {
+      throw new Error('Malformed ssh-agent response.');
+    }
+  }
+}
+
+class SshAgentClient {
+  constructor(private readonly socketPath = process.env.SSH_AUTH_SOCK ?? '') {}
+
+  public async listIdentities(): Promise<ISmartconfigSshAgentIdentity[]> {
+    const response = await this.request(Buffer.from([sshAgentRequestIdentities]));
+    const reader = new BinaryReader(response);
+    const responseType = reader.readUInt8();
+
+    if (responseType === sshAgentFailure) {
+      throw new Error('ssh-agent refused to list identities.');
+    }
+    if (responseType !== sshAgentIdentitiesAnswer) {
+      throw new Error(`Unexpected ssh-agent response type ${responseType}.`);
+    }
+
+    const count = reader.readUInt32BE();
+    if (count > maxAgentIdentities) {
+      throw new Error(`Refusing oversized ssh-agent identity list with ${count} identities.`);
+    }
+
+    const identities: ISmartconfigSshAgentIdentity[] = [];
+    for (let i = 0; i < count; i++) {
+      const keyBlob = reader.readSshStringBuffer();
+      const comment = reader.readSshStringUtf8();
+      const parsedKeyBlob = tryParseSupportedKeyBlob(keyBlob);
+      if (!parsedKeyBlob) continue;
+      const fingerprint = fingerprintSha256(keyBlob);
+      const authorizedKey = formatAuthorizedKey(parsedKeyBlob.type, keyBlob, comment);
+
+      identities.push({
+        type: parsedKeyBlob.type,
+        keyBlob,
+        publicKeyBytes: parsedKeyBlob.publicKeyBytes,
+        comment,
+        fingerprint,
+        authorizedKey,
+      });
+    }
+
+    return identities;
+  }
+
+  public async sign(keyBlobArg: Buffer, dataArg: Buffer): Promise<ISmartconfigSshAgentSignature> {
+    const payload = Buffer.concat([
+      Buffer.from([sshAgentSignRequest]),
+      sshString(keyBlobArg),
+      sshString(dataArg),
+      uint32(0),
+    ]);
+
+    const response = await this.request(payload);
+    const reader = new BinaryReader(response);
+    const responseType = reader.readUInt8();
+
+    if (responseType === sshAgentFailure) {
+      throw new Error('ssh-agent refused to sign. The key may be locked, constrained, or missing.');
+    }
+    if (responseType !== sshAgentSignResponse) {
+      throw new Error(`Unexpected ssh-agent response type ${responseType}.`);
+    }
+
+    const signatureBlob = reader.readSshStringBuffer();
+    const signatureReader = new BinaryReader(signatureBlob);
+    const algorithm = signatureReader.readSshStringUtf8();
+    const signature = signatureReader.readSshStringBuffer();
+    if (signatureReader.remainingBytes !== 0) {
+      throw new Error('Malformed ssh-agent signature blob.');
+    }
+
+    return {
+      algorithm,
+      signature,
+      signatureBlob,
+    };
+  }
+
+  private async request(payloadArg: Buffer): Promise<Buffer> {
+    if (!this.socketPath) {
+      throw new Error('SSH_AUTH_SOCK is not set. Start ssh-agent and add the matching SSH key.');
+    }
+
+    return await new Promise<Buffer>((resolve, reject) => {
+      const socket = net.createConnection({ path: this.socketPath });
+      const chunks: Buffer[] = [];
+      let finished = false;
+      let timeoutRef: NodeJS.Timeout | undefined;
+
+      const cleanup = (): void => {
+        if (timeoutRef) clearTimeout(timeoutRef);
+      };
+
+      const fail = (errorArg: Error): void => {
+        if (finished) return;
+        finished = true;
+        cleanup();
+        socket.destroy();
+        reject(errorArg);
+      };
+
+      timeoutRef = setTimeout(() => {
+        fail(new Error(`ssh-agent request timed out after ${defaultAgentTimeoutMs}ms.`));
+      }, defaultAgentTimeoutMs);
+      timeoutRef.unref?.();
+
+      socket.on('connect', () => {
+        socket.write(Buffer.concat([uint32(payloadArg.length), payloadArg]));
+      });
+      socket.on('error', fail);
+      socket.on('close', () => {
+        if (!finished) {
+          fail(new Error('ssh-agent closed the connection before sending a complete response.'));
+        }
+      });
+      socket.on('data', (chunkArg) => {
+        if (finished) return;
+        chunks.push(Buffer.from(chunkArg));
+        const buffer = Buffer.concat(chunks);
+        if (buffer.length < 4) return;
+
+        const responseLength = buffer.readUInt32BE(0);
+        if (responseLength > maxAgentResponseBytes) {
+          fail(new Error('Refusing oversized ssh-agent response.'));
+          return;
+        }
+        if (buffer.length < 4 + responseLength) return;
+
+        finished = true;
+        cleanup();
+        socket.destroy();
+        resolve(buffer.subarray(4, 4 + responseLength));
+      });
+    });
+  }
+}
+
+export class SmartconfigSshAgentSecrets {
+  public static async encryptString(
+    valueArg: string,
+    optionsArg: ISmartconfigSshAgentSecretEncryptOptions = {},
+  ): Promise<ISmartconfigEncryptedValue> {
+    const publicKey = await resolvePublicKey(optionsArg);
+    const agent = new SshAgentClient(optionsArg.agentSocket);
+    const identity = await findIdentity(agent, publicKey);
+    const salt = randomBytes(32);
+    const challenge = makeChallenge(publicKey, salt);
+    const signature = await agent.sign(identity.keyBlob, challenge);
+
+    assertEd25519Signature(signature);
+    assertSignatureMatchesPublicKey(publicKey, challenge, signature.signature);
+
+    const kek = deriveKek(signature.signature, salt, publicKey);
+    const aad = makeAad(publicKey, salt);
+    const box = encryptAes256Gcm(kek, Buffer.from(valueArg, 'utf8'), aad);
+
+    return {
+      __smartconfigSecret: secretFormat,
+      keyHint: {
+        format: 'openssh-authorized-key-v1',
+        authorizedKey: publicKey.authorizedKey,
+        fingerprint: publicKey.fingerprint,
+      },
+      payload: {
+        encoding: aadEncoding,
+      },
+      kdf: {
+        name: 'HKDF-SHA256',
+        salt: toBase64(salt),
+      },
+      box,
+    };
+  }
+
+  public static async decryptString(
+    encryptedValueArg: ISmartconfigEncryptedValue,
+    optionsArg: ISmartconfigSshAgentSecretDecryptOptions = {},
+  ): Promise<string> {
+    const buffer = await this.decryptBuffer(encryptedValueArg, optionsArg);
+    return buffer.toString('utf8');
+  }
+
+  public static async decryptBuffer(
+    encryptedValueArg: ISmartconfigEncryptedValue,
+    optionsArg: ISmartconfigSshAgentSecretDecryptOptions = {},
+  ): Promise<Buffer> {
+    const normalized = normalizeEncryptedValue(encryptedValueArg);
+    const publicKey = parseOpenSshPublicKeyLine(normalized.keyHint.authorizedKey);
+    if (publicKey.fingerprint !== normalized.keyHint.fingerprint) {
+      throw new Error('Encrypted value public key does not match its fingerprint.');
+    }
+
+    const salt = fromBase64(normalized.kdf.salt, 'kdf.salt', 32);
+    const agent = new SshAgentClient(optionsArg.agentSocket);
+    const identity = await findIdentity(agent, publicKey);
+    const challenge = makeChallenge(publicKey, salt);
+    const signature = await agent.sign(identity.keyBlob, challenge);
+
+    assertEd25519Signature(signature);
+    assertSignatureMatchesPublicKey(publicKey, challenge, signature.signature);
+
+    const kek = deriveKek(signature.signature, salt, publicKey);
+    return decryptAes256Gcm(kek, normalized.box, makeAad(publicKey, salt));
+  }
+
+  public static isEncryptedValue(valueArg: unknown): valueArg is ISmartconfigEncryptedValue {
+    return Boolean(
+      valueArg
+      && typeof valueArg === 'object'
+      && (valueArg as Partial<ISmartconfigEncryptedValue>).__smartconfigSecret === secretFormat,
+    );
+  }
+
+  public static async writeKey(
+    kvStoreArg: Pick<KeyValueStore<any>, 'writeKey'>,
+    keyArg: string,
+    valueArg: string,
+    optionsArg: ISmartconfigSshAgentSecretEncryptOptions = {},
+  ): Promise<ISmartconfigEncryptedValue> {
+    const encryptedValue = await this.encryptString(valueArg, optionsArg);
+    await kvStoreArg.writeKey(keyArg, encryptedValue);
+    return encryptedValue;
+  }
+
+  public static async readKey(
+    kvStoreArg: Pick<KeyValueStore<any>, 'readKey'>,
+    keyArg: string,
+    optionsArg: ISmartconfigSshAgentSecretDecryptOptions = {},
+  ): Promise<string> {
+    const value = await kvStoreArg.readKey(keyArg);
+    if (!this.isEncryptedValue(value)) {
+      throw new Error(`Key "${keyArg}" does not contain a smartconfig ssh-agent encrypted value.`);
+    }
+    return await this.decryptString(value, optionsArg);
+  }
+}
+
+async function resolvePublicKey(optionsArg: ISmartconfigSshAgentSecretEncryptOptions): Promise<ISmartconfigSshPublicKey> {
+  if (optionsArg.authorizedKey) {
+    return parseOpenSshPublicKeyLine(optionsArg.authorizedKey);
+  }
+  const authorizedKeyPath = optionsArg.authorizedKeyPath ?? '~/.ssh/id_ed25519.pub';
+  const content = await fs.readFile(expandHome(authorizedKeyPath), 'utf8');
+  return parseOpenSshPublicKeyLine(content);
+}
+
+async function findIdentity(agentArg: SshAgentClient, publicKeyArg: ISmartconfigSshPublicKey): Promise<ISmartconfigSshAgentIdentity> {
+  const identities = await agentArg.listIdentities();
+  const identity = identities.find((candidate) => candidate.fingerprint === publicKeyArg.fingerprint && candidate.keyBlob.equals(publicKeyArg.keyBlob));
+  if (!identity) {
+    throw new Error(`Required SSH key ${publicKeyArg.fingerprint} is not loaded in ssh-agent.`);
+  }
+  return identity;
+}
+
+function normalizeEncryptedValue(valueArg: unknown): ISmartconfigEncryptedValue {
+  if (!SmartconfigSshAgentSecrets.isEncryptedValue(valueArg)) {
+    throw new Error('Value is not a smartconfig ssh-agent encrypted value.');
+  }
+  if (valueArg.keyHint?.format !== 'openssh-authorized-key-v1') {
+    throw new Error('Encrypted value uses an unsupported key hint format.');
+  }
+  if (typeof valueArg.keyHint.authorizedKey !== 'string' || !valueArg.keyHint.authorizedKey) {
+    throw new Error('Encrypted value is missing an authorized key hint.');
+  }
+  if (typeof valueArg.keyHint.fingerprint !== 'string' || !valueArg.keyHint.fingerprint.startsWith('SHA256:')) {
+    throw new Error('Encrypted value is missing a supported SSH key fingerprint.');
+  }
+  if (valueArg.payload?.encoding !== aadEncoding) {
+    throw new Error('Encrypted value uses an unsupported payload encoding.');
+  }
+  if (valueArg.kdf?.name !== 'HKDF-SHA256') {
+    throw new Error('Encrypted value uses an unsupported KDF.');
+  }
+  if (valueArg.box?.alg !== 'AES-256-GCM') {
+    throw new Error('Encrypted value uses an unsupported encryption algorithm.');
+  }
+  return valueArg;
+}
+
+function parseOpenSshPublicKeyLine(lineOrFileArg: string): ISmartconfigSshPublicKey {
+  const line = lineOrFileArg
+    .split(/\r?\n/)
+    .map((candidate) => candidate.trim())
+    .find((candidate) => candidate && !candidate.startsWith('#'));
+
+  if (!line) {
+    throw new Error('No OpenSSH authorized key line found.');
+  }
+
+  const tokens = line.split(/\s+/);
+  const keyIndex = tokens.findIndex((token) => token === 'ssh-ed25519');
+  if (keyIndex === -1 || !tokens[keyIndex + 1]) {
+    throw new Error('Only ssh-ed25519 authorized key hints are supported.');
+  }
+
+  const keyBlob = fromBase64(tokens[keyIndex + 1], 'authorizedKey.keyBlob');
+  const parsedKeyBlob = parseSupportedKeyBlob(keyBlob);
+  if (parsedKeyBlob.type !== tokens[keyIndex]) {
+    throw new Error(`SSH public key type mismatch: line says ${tokens[keyIndex]}, blob says ${parsedKeyBlob.type}.`);
+  }
+
+  const comment = tokens.slice(keyIndex + 2).join(' ');
+  const fingerprint = fingerprintSha256(keyBlob);
+  return {
+    type: parsedKeyBlob.type,
+    keyBlob,
+    publicKeyBytes: parsedKeyBlob.publicKeyBytes,
+    comment,
+    fingerprint,
+    authorizedKey: formatAuthorizedKey(parsedKeyBlob.type, keyBlob, comment),
+  };
+}
+
+function parseSupportedKeyBlob(keyBlobArg: Buffer): { type: TSmartconfigSshKeyType; publicKeyBytes: Buffer } {
+  const reader = new BinaryReader(keyBlobArg);
+  const type = reader.readSshStringUtf8();
+  if (type !== 'ssh-ed25519') {
+    throw new Error(`Unsupported SSH key type: ${type}.`);
+  }
+  const publicKeyBytes = reader.readSshStringBuffer();
+  if (publicKeyBytes.length !== 32) {
+    throw new Error(`Expected 32-byte Ed25519 public key, got ${publicKeyBytes.length} bytes.`);
+  }
+  if (reader.remainingBytes !== 0) {
+    throw new Error('Malformed ssh-ed25519 public key blob.');
+  }
+  return { type, publicKeyBytes };
+}
+
+function tryParseSupportedKeyBlob(keyBlobArg: Buffer): { type: TSmartconfigSshKeyType; publicKeyBytes: Buffer } | undefined {
+  try {
+    return parseSupportedKeyBlob(keyBlobArg);
+  } catch (error) {
+    if ((error as Error).message.startsWith('Unsupported SSH key type:')) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+function assertEd25519Signature(signatureArg: ISmartconfigSshAgentSignature): void {
+  if (signatureArg.algorithm !== 'ssh-ed25519') {
+    throw new Error(`Expected ssh-ed25519 signature, got ${signatureArg.algorithm}.`);
+  }
+  if (signatureArg.signature.length !== 64) {
+    throw new Error(`Expected 64-byte Ed25519 signature, got ${signatureArg.signature.length} bytes.`);
+  }
+}
+
+function assertSignatureMatchesPublicKey(
+  publicKeyArg: ISmartconfigSshPublicKey,
+  challengeArg: Buffer,
+  signatureArg: Buffer,
+): void {
+  const spkiPrefix = Buffer.from('302a300506032b6570032100', 'hex');
+  const keyObject = createPublicKey({
+    key: Buffer.concat([spkiPrefix, publicKeyArg.publicKeyBytes]),
+    format: 'der',
+    type: 'spki',
+  });
+  const valid = verify(null, challengeArg, keyObject, signatureArg);
+  if (!valid) {
+    throw new Error('ssh-agent signature does not match the encrypted value key hint.');
+  }
+}
+
+function makeChallenge(publicKeyArg: ISmartconfigSshPublicKey, saltArg: Buffer): Buffer {
+  return Buffer.concat([
+    Buffer.from('smartconfig:ssh-agent-sign-v1:kek\n', 'utf8'),
+    sshString(publicKeyArg.fingerprint),
+    sshString(publicKeyArg.authorizedKey),
+    sshString(saltArg),
+  ]);
+}
+
+function deriveKek(signatureArg: Buffer, saltArg: Buffer, publicKeyArg: ISmartconfigSshPublicKey): Buffer {
+  const info = Buffer.concat([
+    Buffer.from('smartconfig:ssh-agent-sign-v1:hkdf-info\n', 'utf8'),
+    sshString(publicKeyArg.fingerprint),
+    sshString(publicKeyArg.authorizedKey),
+  ]);
+  return Buffer.from(hkdfSync('sha256', signatureArg, saltArg, info, 32));
+}
+
+function makeAad(publicKeyArg: ISmartconfigSshPublicKey, saltArg: Buffer): Buffer {
+  return Buffer.from(JSON.stringify({
+    format: secretFormat,
+    keyHint: {
+      format: 'openssh-authorized-key-v1',
+      authorizedKey: publicKeyArg.authorizedKey,
+      fingerprint: publicKeyArg.fingerprint,
+    },
+    payload: {
+      encoding: aadEncoding,
+    },
+    kdf: {
+      name: 'HKDF-SHA256',
+      salt: toBase64(saltArg),
+    },
+  }), 'utf8');
+}
+
+function encryptAes256Gcm(keyArg: Buffer, plaintextArg: Buffer, aadArg: Buffer): ISmartconfigSecretBox {
+  const nonce = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', keyArg, nonce);
+  cipher.setAAD(aadArg);
+  const ciphertext = Buffer.concat([cipher.update(plaintextArg), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return {
+    alg: 'AES-256-GCM',
+    nonce: toBase64(nonce),
+    ciphertext: toBase64(ciphertext),
+    tag: toBase64(tag),
+  };
+}
+
+function decryptAes256Gcm(keyArg: Buffer, boxArg: ISmartconfigSecretBox, aadArg: Buffer): Buffer {
+  if (boxArg.alg !== 'AES-256-GCM') {
+    throw new Error(`Unsupported encryption algorithm: ${boxArg.alg}.`);
+  }
+  const nonce = fromBase64(boxArg.nonce, 'box.nonce', 12);
+  const ciphertext = fromBase64(boxArg.ciphertext, 'box.ciphertext');
+  const tag = fromBase64(boxArg.tag, 'box.tag', 16);
+  const decipher = createDecipheriv('aes-256-gcm', keyArg, nonce);
+  decipher.setAAD(aadArg);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+
+function formatAuthorizedKey(typeArg: TSmartconfigSshKeyType, keyBlobArg: Buffer, commentArg: string): string {
+  return `${typeArg} ${keyBlobArg.toString('base64')}${commentArg ? ` ${commentArg}` : ''}`;
+}
+
+function fingerprintSha256(keyBlobArg: Buffer): string {
+  return `SHA256:${createHash('sha256').update(keyBlobArg).digest('base64').replace(/=+$/g, '')}`;
+}
+
+function sshString(valueArg: Buffer | string): Buffer {
+  const buffer = Buffer.isBuffer(valueArg) ? valueArg : Buffer.from(valueArg, 'utf8');
+  return Buffer.concat([uint32(buffer.length), buffer]);
+}
+
+function uint32(valueArg: number): Buffer {
+  const buffer = Buffer.alloc(4);
+  buffer.writeUInt32BE(valueArg, 0);
+  return buffer;
+}
+
+function toBase64(valueArg: Buffer): string {
+  return valueArg.toString('base64');
+}
+
+function fromBase64(valueArg: string, fieldNameArg: string, expectedLengthArg?: number): Buffer {
+  if (typeof valueArg !== 'string' || !valueArg || valueArg.length % 4 === 1 || !/^[A-Za-z0-9+/]+={0,2}$/.test(valueArg)) {
+    throw new Error(`${fieldNameArg} must be a base64 string.`);
+  }
+  const buffer = Buffer.from(valueArg, 'base64');
+  if (expectedLengthArg !== undefined && buffer.length !== expectedLengthArg) {
+    throw new Error(`${fieldNameArg} must decode to ${expectedLengthArg} bytes.`);
+  }
+  return buffer;
+}
+
+function expandHome(pathArg: string): string {
+  if (pathArg === '~') return homedir();
+  if (pathArg.startsWith('~/')) return join(homedir(), pathArg.slice(2));
+  return pathArg;
+}