@steve228uk/nhs-cli 0.0.1 → 0.1.0

package/src/domains.mjs

@@ -0,0 +1,184 @@
+import { NhsError, shape } from './errors.mjs';
+import { jsonResponse, assertHttp } from './transport.mjs';
+import { origins } from './config.mjs';
+
+export function parsePositiveInteger(value, fallback) {
+  if (value === undefined) return fallback;
+  return /^\d+$/.test(String(value)) && Number.isSafeInteger(Number(value)) && Number(value) > 0 ? Number(value) : fallback;
+}
+export function positive(value, fallback, max = 100) {
+  if (value === undefined) return fallback;
+  const n = parsePositiveInteger(value, 0);
+  if (!n || n > max) throw new NhsError('usage', 'Numeric option is outside its supported range.');
+  return n;
+}
+export function identifier(value) {
+  if (typeof value !== 'string' || !value || value.length > 512 || /[\x00-\x20]/.test(value) || value === '.' || value === '..') throw new NhsError('usage', 'A valid resource identifier is required.');
+  return encodeURIComponent(value);
+}
+
+export function buildStatusPayload(data) {
+  shape(data && Array.isArray(data.courses));
+  const courses = data.courses.map(course => {
+    shape(course && ['string', 'number'].includes(typeof course.id) && typeof course.name === 'string' && typeof course.requestable === 'boolean' && (course.details === undefined || typeof course.details === 'string'));
+    return { id: course.id, name: course.name, details: course.details ?? '', requestable: course.requestable };
+  });
+  const available = courses.filter(course => course.requestable);
+  return { ok: true, checkedAt: new Date().toISOString(), summary: { total: courses.length, requestable: available.length, requestableNames: available.map(course => course.name), specialRequestNecessity: data.specialRequestNecessity ?? 'None' }, courses };
+}
+
+function capability(enabled, supported = true) {
+  let status = 'unsupported';
+  if (enabled === false) status = 'unavailable';
+  else if (enabled === true && supported) status = 'available';
+  return { status, evidence: 'client-observed' };
+}
+function providerCapability(provider) {
+  if (provider === 'none') return capability(false);
+  if (provider === 'im1') return capability(true);
+  return capability(undefined);
+}
+export function capabilitiesFrom(data) {
+  shape(data?.journeys && typeof data.journeys === 'object' && !Array.isArray(data.journeys));
+  const rules = data.journeys;
+  const provider = name => rules[name]?.provider;
+  const record = ['1', '2'].includes(String(rules.medicalRecord?.version));
+  let records = capability(undefined);
+  if (rules.medicalRecord?.version === null) records = capability(false);
+  else if (record) records = capability(true);
+  return {
+    prescriptions: providerCapability(provider('prescriptions')),
+    records,
+    results: capability(record && [null, '1', '2'].includes(rules.im1TestResults?.version) ? true : undefined),
+    appointments: providerCapability(provider('appointments')),
+    nhsMessages: capability(rules.messaging), gpMessages: capability(rules.im1Messaging?.isEnabled),
+    pharmacy: capability(rules.nominatedPharmacy), documents: capability(rules.documents), profile: capability(true),
+  };
+}
+
+export class NhsServices {
+  /** @param {import('./auth.mjs').AuthClient} auth */
+  constructor(auth) { this.auth = auth; this.capabilities = null; }
+  /** @param {string} path @param {Parameters<import('./auth.mjs').AuthClient['read']>[1]} options */
+  async #readJson(path, options = {}) {
+    return jsonResponse(await this.auth.read(path, options));
+  }
+  async discover() {
+    if (!this.capabilities) {
+      const data = await this.#readJson('/v1/patient/journey-configuration');
+      this.capabilities = capabilitiesFrom(data);
+    }
+    return this.capabilities;
+  }
+  async require(name, gp = false) {
+    const capabilities = await this.discover();
+    const cap = capabilities[name];
+    if (!cap || cap.status !== 'available') throw new NhsError(cap?.status === 'unavailable' ? 'capability_unavailable' : 'unsupported', 'This capability is not available through a supported provider for this account.', { capability: name });
+    if (gp && !this.auth.session.hasGpSession) await this.auth.ensureGp();
+  }
+  async courses() {
+    await this.require('prescriptions', true);
+    let response;
+    try { response = await this.auth.read('/v1/patient/courses', { gp: true }); }
+    catch (error) {
+      if (error.details?.status !== 598) throw error;
+      await this.auth.ensureGp();
+      response = await this.auth.read('/v1/patient/courses', { gp: true });
+    }
+    return buildStatusPayload(await jsonResponse(response));
+  }
+  async order({ ids = undefined, all = false, note = '', confirm = false, dryRun = false } = {}) {
+    if ((!ids && !all) || (ids && all)) throw new NhsError('order_requires_scope', 'Choose either explicit --ids or --all-requestable.');
+    if (typeof note !== 'string' || note.length > 1000) throw new NhsError('usage', 'The prescription note must contain at most 1000 characters.');
+    if (!dryRun && !confirm) throw new NhsError('order_requires_confirmation', 'Review a fresh dry-run preview and confirm the exact medicines before using --confirm.');
+    const status = await this.courses();
+    const wanted = ids ? String(ids).split(',').map(id => id.trim()).filter(Boolean) : [];
+    if (ids && (!wanted.length || new Set(wanted).size !== wanted.length)) throw new NhsError('order_invalid_scope', 'Prescription IDs must be non-empty and unique.');
+    const selected = wanted.length ? wanted.map(id => status.courses.find(course => String(course.id) === id)) : status.courses.filter(course => course.requestable);
+    if (selected.some(course => !course?.requestable)) throw new NhsError('order_invalid_scope', 'Some supplied medication IDs are unknown or not currently requestable.');
+    if (!selected.length) return { ...status, order: { submitted: false, reason: 'no_requestable_courses' } };
+    if (dryRun) return { ...status, order: { submitted: false, dryRun: true, courseIds: selected.map(course => course.id), selectedNames: selected.map(course => course.name), note } };
+    let response;
+    try { response = await this.auth.request('/v1/patient/prescriptions', { method: 'POST', body: { CourseIds: selected.map(course => course.id), SpecialRequest: note } }); }
+    catch { throw new NhsError('order_unknown', 'The prescription request outcome is unknown. Check the official NHS App before submitting again.'); }
+    if (response.status >= 500 || response.status === 202 || response.status === 408) {
+      await response.body?.cancel();
+      throw new NhsError('order_unknown', 'The prescription request outcome is unknown. Check the official NHS App before submitting again.');
+    }
+    await assertHttp(response, 'prescription request');
+    if (response.status !== 201) {
+      await response.body?.cancel();
+      throw new NhsError('order_unknown', 'NHS returned an unrecognised submission acknowledgement. Check the official NHS App before submitting again.');
+    }
+    await response.body?.cancel();
+    return { ...status, order: { submitted: true, result: { submitted: true }, orderedNames: selected.map(course => course.name) } };
+  }
+  async history(from) {
+    await this.require('prescriptions', true);
+    const date = from ? new Date(from) : new Date(new Date().setMonth(new Date().getMonth() - 6));
+    if (!Number.isFinite(date.getTime())) throw new NhsError('usage', '--from must be an ISO date.');
+    const data = await this.#readJson(`/v1/patient/prescriptions?${new URLSearchParams({ fromDate: date.toISOString() })}`, { gp: true });
+    shape(Array.isArray(data?.prescriptions) && Array.isArray(data?.courses)); return data;
+  }
+  async record() {
+    await this.require('records', true);
+    const data = await this.#readJson('/v1/patient/my-record', { gp: true });
+    shape(data?.response && typeof data.response === 'object');
+    if (data.response.hasSummaryRecordAccess === false && data.response.hasDetailedRecordAccess !== true) throw new NhsError('capability_unavailable', 'The GP has not enabled access to this medical record.');
+    return data.response;
+  }
+  async results({ id = undefined, year = undefined } = {}) {
+    await this.require('results', true);
+    if (id && year) throw new NhsError('usage', 'Choose a result ID or a historical year.');
+    if (!id && !year) {
+      const record = await this.record(); shape(record.testResults !== undefined); return record.testResults;
+    }
+    if (year && (!/^\d{4}$/.test(String(year)) || Number(year) < 1900 || Number(year) > new Date().getFullYear())) throw new NhsError('usage', '--year must be a year between 1900 and the current year.');
+    const path = id ? `/v1/patient/test-result?${new URLSearchParams({ testResultId: String(id) })}` : `/v1/patient/historic-test-results/${year}`;
+    const data = await this.#readJson(path, { gp: true });
+    shape(data?.response !== undefined); return data.response;
+  }
+  async appointments(slots = false) {
+    await this.require('appointments', true);
+    const data = await this.#readJson(slots ? '/v1/patient/appointment-slots' : '/v1/patient/appointments', { gp: true });
+    shape(data && typeof data === 'object');
+    if (!slots) shape(Array.isArray(data.upcomingAppointments) || Array.isArray(data.pastAppointments));
+    else shape(Array.isArray(data.slots));
+    return data;
+  }
+  async messages({ source = 'nhs', id = undefined, index = 0, count = 20 } = {}) {
+    if (!['nhs', 'gp'].includes(source)) throw new NhsError('usage', '--source must be nhs or gp.');
+    await this.require(source === 'nhs' ? 'nhsMessages' : 'gpMessages', source === 'gp');
+    if (!Number.isSafeInteger(index) || index < 0 || index > 100000 || !Number.isInteger(count) || count < 1 || count > 100) throw new NhsError('usage', 'Message index must be 0–100000 and count 1–100.');
+    const path = source === 'nhs' ? id ? `/v1/api/users/me/messages/${identifier(id)}` : `/v2/api/users/me/messages?${new URLSearchParams({ index: String(index), count: String(count) })}` : id ? `/v1/patient/messages/${identifier(id)}` : '/v1/patient/messages';
+    const data = await this.#readJson(path, { bearer: source === 'nhs', gp: source === 'gp' });
+    shape(data && typeof data === 'object');
+    if (!id && source === 'nhs') shape(Array.isArray(data.messages) && typeof data.canLoadMore === 'boolean');
+    if (!id && source === 'gp') shape(Array.isArray(data.messageSummaries));
+    if (id && source === 'gp') shape(data.messageDetails && typeof data.messageDetails === 'object');
+    return data;
+  }
+  async profile() {
+    const data = await this.#readJson('/v1/patient/demographics');
+    shape(data && typeof data === 'object' && !Array.isArray(data)); return data;
+  }
+  async pharmacy() {
+    await this.require('pharmacy');
+    const data = await this.#readJson('/v1/patient/nominated-pharmacy');
+    shape(data === null || typeof data === 'object'); return data;
+  }
+  async documents(id = undefined, download = false) {
+    await this.require('documents', true);
+    if (!this.auth.nhsNumber || !/^\d{10}$/.test(this.auth.nhsNumber)) throw new NhsError('unsupported', 'NHS did not provide the own-account identifier required for document access.');
+    const list = await this.#readJson(`/v1/AccessDocuments/Patient/${this.auth.nhsNumber}/DocumentReference`, { origin: origins.gpconnect, gp: true });
+    shape(Array.isArray(list?.patientDocuments));
+    if (!id) return { documents: list.patientDocuments };
+    const metadata = list.patientDocuments.find(doc => String(doc.id) === String(id));
+    if (!metadata) throw new NhsError('not_found', 'That document is not in this account’s available document list.');
+    if (!download) return metadata;
+    const data = await this.#readJson(`/v1/AccessDocuments/Download/${identifier(id)}`, { origin: origins.gpconnect, gp: true, headers: { Prefer: 'statuscode=200' } });
+    shape(typeof data?.content === 'string' && typeof data?.contentType === 'string');
+    if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(data.content) || !data.content) throw new NhsError('invalid_response', 'Document content is missing or invalid base64.');
+    return { content: Buffer.from(data.content, 'base64'), contentType: data.contentType, metadata };
+  }
+}

package/src/errors.mjs

@@ -0,0 +1,31 @@
+export class NhsError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = 'NhsError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export function redact(value) {
+  return String(value ?? '')
+    .replace(/[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]+/g, '[redacted-jwt]')
+    .replace(/\b[A-Fa-f0-9]{32,}\b/g, '[redacted-token]')
+    .replace(/\b\d{6}\b/g, '[redacted-code]')
+    .replace(/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi, '[redacted-email]')
+    .replace(/((?:NHSO-Session-[\w-]+|authorization|cookie|csrfToken|email|id_token|password|patientId|patientSessionId|phone_number|phoneNumber|sessionId|sessionExpiry|token|rmdToken|rememberMyDevice|code|state|nonce)["']?\s*[:=]\s*)[^\s&,;}]+/gi, '$1[redacted]');
+}
+
+// Upstream bodies and native exception messages can contain arbitrary secrets.
+// Only our own constant messages and explicitly selected metadata reach output.
+export function errorPayload(error) {
+  if (!(error instanceof NhsError)) return { ok: false, code: 'unexpected_error', message: 'Unexpected failure. Run nhs doctor to check local prerequisites.' };
+  const details = {};
+  if (Number.isInteger(error.details?.status)) details.status = error.details.status;
+  if (typeof error.details?.capability === 'string') details.capability = error.details.capability;
+  return { ok: false, code: error.code, message: redact(error.message), ...details };
+}
+
+export function shape(condition, message = 'NHS returned an unsupported response structure.') {
+  if (!condition) throw new NhsError('invalid_response', message);
+}

package/src/otp.mjs

@@ -0,0 +1,46 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { NhsError } from './errors.mjs';
+import { promptInput } from './ui.mjs';
+
+const exec = promisify(execFile);
+export function isLikelyNhsOtpText(text) {
+  return /\bNHS\b/i.test(text) && /\b(login|security|verification|code|passcode|OTP)\b/i.test(text) && /\b\d{6}\b/.test(text);
+}
+export function extractOtpCode(text) { return isLikelyNhsOtpText(text) ? text.match(/\b(\d{6})\b/)?.[1] ?? null : null; }
+
+export async function readOtpFromMessages({ since = Date.now(), execImpl = exec, platform = process.platform } = {}) {
+  if (platform !== 'darwin') throw new NhsError('otp_messages_unsupported', 'Messages OTP lookup requires macOS.');
+  if (!Number.isFinite(since)) throw new NhsError('otp_invalid', 'The security-code challenge time is invalid.');
+  const sql = `WITH nhs_messages AS (SELECT text, CASE WHEN date > 1000000000000 THEN date / 1000000000.0 + 978307200 ELSE date + 978307200 END AS received_unix FROM message WHERE is_from_me = 0 AND text LIKE '%NHS%') SELECT text, received_unix FROM nhs_messages WHERE received_unix >= ${since / 1000} ORDER BY received_unix DESC LIMIT 30;`;
+  let rows;
+  try {
+    const { stdout } = await execImpl('sqlite3', ['-readonly', '-json', join(homedir(), 'Library', 'Messages', 'chat.db'), sql], { timeout: 5000, maxBuffer: 128 * 1024 });
+    rows = JSON.parse(String(stdout) || '[]');
+  } catch { throw new NhsError('otp_messages_unavailable', 'Messages OTP lookup is unavailable. Enter the code directly in the terminal or enable Messages access.'); }
+  const now = Date.now();
+  for (const row of rows) {
+    const received = Number(row.received_unix) * 1000;
+    if (!Number.isFinite(received) || received < since || received > now + 1000) continue;
+    const code = extractOtpCode(row.text || ''); if (code) return code;
+  }
+  throw new NhsError('otp_not_found', 'No NHS code received after this login challenge was found.');
+}
+
+export async function resolveOtp({ since, messages = false, allowPrompt = false, prompt = promptInput, readMessages = readOtpFromMessages, pause = ms => new Promise(resolve => setTimeout(resolve, ms)) }) {
+  if (messages) {
+    for (let attempt = 0; attempt < 6; attempt++) {
+      try { return await readMessages({ since }); }
+      catch (error) {
+        if (error.code !== 'otp_not_found') { if (!allowPrompt) throw error; break; }
+        if (attempt < 5) await pause(10000);
+      }
+    }
+  }
+  if (!allowPrompt) throw new NhsError('auth_required', 'NHS requires a security code. Run nhs auth login in a terminal.');
+  const value = String(await prompt('NHS security code', { validate: value => /^\d{6}$/.test(value?.trim() || '') ? undefined : 'Enter the six-digit NHS security code.' })).trim();
+  if (!/^\d{6}$/.test(value)) throw new NhsError('otp_invalid', 'The NHS security code must contain six digits.');
+  return value;
+}

package/src/output.mjs

@@ -0,0 +1,32 @@
+import { NhsError } from './errors.mjs';
+import { open, unlink } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+const secretKey = /^(?:authorization|cookie|cookies|set-cookie|password|csrfToken|token|accessToken|refreshToken|id_token|rmd_token|rmdToken|rememberMyDevice|remember_my_device|sessionId|patientId|patientSessionId|sessionExpiry|codeVerifier|nonce)$/i;
+/** Strip protocol secrets from domain output; clinical data remains intentionally visible. */
+export function publicData(value) {
+  if (Array.isArray(value)) return value.map(publicData);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).filter(([key]) => !secretKey.test(key)).map(([key, item]) => [key, publicData(item)]));
+  return value;
+}
+function terminalText(text) { return String(text).replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, ''); }
+export function render(payload, json) {
+  const data = publicData(payload);
+  if (json) return `${JSON.stringify(data, null, 2)}\n`;
+  if (Array.isArray(data.checks)) return data.checks.map(check => `${check.ok ? '[OK]' : '[FAIL]'} ${check.name}: ${terminalText(check.detail)}`).join('\n') + '\n';
+  if (data.courses && !data.order) return data.courses.map(course => `${course.requestable ? '[REQUESTABLE]' : '[not available]'} ${terminalText(course.name)}${course.details ? `\n  ${terminalText(course.details).replace(/\n/g, '\n  ')}` : ''}`).join('\n') + `\n\n${data.summary.requestable} of ${data.summary.total} medication(s) available to order.\n`;
+  if (data.ok === false) return `Error [${data.code}]: ${terminalText(data.message)}\n`;
+  // Nested record sections retain their labels and structure in human output.
+  return `${JSON.stringify(data, null, 2)}\n`;
+}
+export async function exportFile(path, content) {
+  const absolute = resolve(path); let handle; let created = false;
+  try {
+    handle = await open(absolute, 'wx', 0o600); created = true;
+    await handle.writeFile(content); await handle.sync();
+    return absolute;
+  } catch (error) {
+    if (created) await unlink(absolute).catch(() => {});
+    throw new NhsError('export_failed', 'Could not create the export. Choose a new file path in an existing directory; existing files are never overwritten.');
+  } finally { await handle?.close(); }
+}

package/src/storage.mjs

@@ -0,0 +1,211 @@
+import { randomBytes, createHash, createCipheriv, createDecipheriv, timingSafeEqual } from 'node:crypto';
+import { constants } from 'node:fs';
+import { chmod, lstat, mkdir, open, rename, unlink, rm } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { userInfo } from 'node:os';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { NhsError } from './errors.mjs';
+
+const SERVICE = 'nhs-cli';
+const ACCOUNT = 'vault-key-v1';
+const MAX_BYTES = 1024 * 1024;
+const AAD = Buffer.from('nhs-cli:vault:v1');
+const storageError = () => new NhsError('secure_storage_unavailable', 'Secure storage is unavailable or locked. Unlock Keychain/Secret Service, or explicitly configure encrypted-file storage with an injected key.');
+
+/** Explicit legacy import only; backend access remains inside storage. */
+export async function legacyCredentials({ loadNative = () => import('@napi-rs/keyring'), platform = process.platform } = {}) {
+  if (platform !== 'darwin') throw new NhsError('unsupported', 'Legacy credential migration is only available on macOS.');
+  try {
+    const { AsyncEntry } = await loadNative();
+    const email = await new AsyncEntry('openclaw-nhs-email', userInfo().username).getPassword();
+    const password = await new AsyncEntry('openclaw-nhs-password', userInfo().username).getPassword();
+    if (typeof email !== 'string' || !email.trim() || typeof password !== 'string' || !password) throw new Error();
+    return { email: email.trim(), password };
+  } catch { throw new NhsError('legacy_credentials_unavailable', 'Legacy Keychain credentials could not be read. Configure credentials with nhs auth login --save-credentials instead.'); }
+}
+
+export async function privateDirectory(path) {
+  await mkdir(path, { recursive: true, mode: 0o700 });
+  const info = await lstat(path);
+  if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid?.()) throw new NhsError('unsafe_storage_path', 'Storage directory must be owned by the current user and must not be a symlink.');
+  await chmod(path, 0o700);
+}
+
+export async function readPrivate(path) {
+  let handle;
+  try {
+    handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.uid !== process.getuid?.() || (stat.mode & 0o077) || stat.size > MAX_BYTES) throw new NhsError('unsafe_storage_file', 'Storage file has unsafe ownership, permissions, type, or size.');
+    return await handle.readFile('utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    if (error instanceof NhsError) throw error;
+    throw new NhsError('storage_read_failed', 'Could not safely read the storage file.');
+  } finally { await handle?.close(); }
+}
+
+export async function atomicWrite(path, data, { replace = rename } = {}) {
+  const temporary = `${path}.${randomBytes(12).toString('hex')}.tmp`;
+  let file;
+  try {
+    file = await open(temporary, 'wx', 0o600);
+    await file.writeFile(data);
+    await file.sync();
+    await file.close(); file = undefined;
+    await replace(temporary, path);
+    const directory = await open(dirname(path), 'r');
+    try { await directory.sync(); } finally { await directory.close(); }
+  } finally {
+    await file?.close();
+    await unlink(temporary).catch(() => {});
+  }
+}
+
+/** Serializes the entire command, including auth renewal, migration and writes. */
+export async function withLock(directory, run, { timeoutMs = 10000 } = {}) {
+  await privateDirectory(directory);
+  const path = join(directory, 'operation.lock');
+  const deadline = Date.now() + timeoutMs;
+  let held = false;
+  while (!held) {
+    try {
+      await mkdir(path, { mode: 0o700 }); held = true;
+      await atomicWrite(join(path, 'owner.json'), JSON.stringify({ pid: process.pid }));
+    } catch (error) {
+      if (held) { await rm(path, { recursive: true, force: true }); throw error; }
+      if (error.code !== 'EEXIST') throw new NhsError('storage_lock_failed', 'Could not acquire the storage lock.');
+      // Never steal a live or unidentifiable lock. A crashed process requires explicit repair.
+      if (Date.now() >= deadline) throw new NhsError('storage_busy', 'Another nhs command holds the storage lock. If it crashed, verify no nhs process is running before removing operation.lock.');
+      await sleep(100);
+    }
+  }
+  try { return await run(); } finally { await rm(path, { recursive: true, force: true }); }
+}
+
+export function injectedKey(env = process.env) {
+  const raw = env.NHS_CLI_STATE_KEY;
+  if (!raw || !/^[A-Za-z0-9+/]{43}=$/.test(raw)) throw new NhsError('storage_key_required', 'Encrypted-file storage requires NHS_CLI_STATE_KEY containing a base64-encoded random 32-byte key from your secret manager.');
+  const key = Buffer.from(raw, 'base64');
+  if (key.length !== 32) throw new NhsError('storage_key_required', 'NHS_CLI_STATE_KEY must decode to exactly 32 bytes.');
+  return key;
+}
+
+/**
+ * Linux enumeration is implemented directly against Secret Service in pinned
+ * @napi-rs/keyring 2.0.0. A non-secret probe proves a NEW Entry is bound to that
+ * store before we ever give it a secret. Reuse that Entry for the key write:
+ * constructing another Entry would re-run the library's fallback selection.
+ */
+export class NativeKeyProvider {
+  constructor({ platform = process.platform, loadNative = () => import('@napi-rs/keyring'), service = SERVICE } = {}) {
+    this.platform = platform; this.loadNative = loadNative; this.service = service;
+  }
+  async key(create = false) {
+    if (!['darwin', 'linux'].includes(this.platform)) throw storageError();
+    try {
+      const native = await this.loadNative();
+      let value;
+      if (this.platform === 'linux') {
+        const rows = await native.findCredentialsAsync(this.service);
+        const matches = rows.filter(row => row.account === ACCOUNT);
+        if (matches.length > 1) throw storageError();
+        value = matches[0]?.password;
+      } else {
+        value = await new native.AsyncEntry(this.service, ACCOUNT).getPassword();
+      }
+      if (this.platform === 'linux' && /^nhs-cli-storage-probe:[0-9a-f]{32}$/.test(value || '')) value = undefined;
+      if (value) {
+        const key = Buffer.from(value, 'base64');
+        if (key.length !== 32 || key.toString('base64') !== value) throw storageError();
+        return key;
+      }
+      if (!create) return null;
+      const entry = new native.AsyncEntry(this.service, ACCOUNT);
+      if (this.platform === 'linux') {
+        const probe = `nhs-cli-storage-probe:${randomBytes(16).toString('hex')}`;
+        await entry.setPassword(probe);
+        try {
+          const rows = await native.findCredentialsAsync(this.service);
+          if (!rows.some(row => row.account === ACCOUNT && row.password === probe)) throw storageError();
+        } catch {
+          await entry.deleteCredential().catch(() => {});
+          throw storageError();
+        }
+      }
+      const key = randomBytes(32);
+      await entry.setPassword(key.toString('base64'));
+      const verified = await this.key(false);
+      if (!verified || !timingSafeEqual(verified, key)) throw storageError();
+      return key;
+    } catch { throw storageError(); }
+  }
+}
+
+/** @typedef {import('./types.mjs').SecureStore} SecureStore */
+/** @implements {SecureStore} */
+export class VaultStore {
+  constructor({ directory, backend = 'keyring', keyProvider = new NativeKeyProvider(), env = process.env }) {
+    this.directory = directory; this.backend = backend; this.keyProvider = keyProvider; this.env = env;
+    this.path = join(directory, 'vault.enc');
+  }
+  async getKey(create = false) {
+    return this.backend === 'encrypted-file' ? injectedKey(this.env) : this.keyProvider.key(create);
+  }
+  async probe() { await this.getKey(false); }
+  /** @returns {Promise<import('./types.mjs').Vault>} */
+  async load() {
+    const key = await this.getKey(false);
+    const raw = await readPrivate(this.path);
+    if (raw === null) return { version: 1, session: {} };
+    if (!key) throw new NhsError('storage_key_missing', 'An encrypted vault exists but its key is unavailable. Restore the original key; the vault has not been overwritten.');
+    try {
+      const envelope = JSON.parse(raw);
+      if (envelope.version !== 1) throw new Error();
+      const iv = Buffer.from(envelope.iv, 'base64'), tag = Buffer.from(envelope.tag, 'base64');
+      if (iv.length !== 12 || tag.length !== 16) throw new Error();
+      const decipher = createDecipheriv('aes-256-gcm', key, iv);
+      decipher.setAAD(AAD); decipher.setAuthTag(tag);
+      const value = JSON.parse(Buffer.concat([decipher.update(Buffer.from(envelope.data, 'base64')), decipher.final()]).toString('utf8'));
+      if (value.version !== 1 || !value.session || typeof value.session !== 'object' || Array.isArray(value.session)) throw new Error();
+      return value;
+    } catch { throw new NhsError('storage_corrupt', 'Could not authenticate the encrypted vault. Check the injected key or restore the encrypted vault; it has not been overwritten.'); }
+  }
+  /** @param {import('./types.mjs').Vault} value */
+  async save(value) {
+    const serialized = JSON.stringify(value);
+    if (Buffer.byteLength(serialized) > MAX_BYTES / 2) throw new NhsError('storage_too_large', 'Authentication state exceeds the supported vault size.');
+    const key = await this.getKey(true);
+    if (!key) throw storageError();
+    const iv = randomBytes(12), cipher = createCipheriv('aes-256-gcm', key, iv);
+    cipher.setAAD(AAD);
+    const data = Buffer.concat([cipher.update(serialized, 'utf8'), cipher.final()]);
+    await privateDirectory(this.directory);
+    await atomicWrite(this.path, JSON.stringify({ version: 1, iv: iv.toString('base64'), tag: cipher.getAuthTag().toString('base64'), data: data.toString('base64') }));
+  }
+}
+
+/** Run only under withLock. Local status and diagnostics never migrate. */
+export async function migrateLegacy(store, path) {
+  const vault = await store.load();
+  const raw = await readPrivate(path);
+  if (raw === null) return vault;
+  const digest = createHash('sha256').update(raw).digest('hex');
+  if (vault.legacyMigrated) {
+    // A crash may happen after verified secure storage but before unlink. Never
+    // reimport old sessions over rotated state, or remove a different source.
+    if (vault.legacyMigrationDigest !== digest) throw new NhsError('migration_conflict', 'Legacy state changed after migration. The secure vault and legacy file have both been preserved.');
+    await unlink(path);
+    return vault;
+  }
+  let old;
+  try { old = JSON.parse(raw); } catch { throw new NhsError('migration_failed', 'Legacy state is invalid; it has not been changed.'); }
+  const allowed = ['csrfToken', 'patientId', 'sessionId', 'sessionExpiry', 'rememberMyDevice', 'rmdToken', 'lastOtpTriggerAt', 'updatedAt'];
+  const session = Object.fromEntries(allowed.filter(key => typeof old[key] === 'string').map(key => [key, old[key]]));
+  const next = { ...vault, session: { ...session, ...vault.session }, legacyMigrated: true, legacyMigrationDigest: digest };
+  await store.save(next);
+  const verified = await store.load();
+  if (JSON.stringify(verified) !== JSON.stringify(next)) throw new NhsError('migration_failed', 'Secure migration verification failed; the legacy file has been preserved.');
+  await unlink(path);
+  return next;
+}

package/src/transport.mjs

@@ -0,0 +1,116 @@
+import { CookieJar } from 'tough-cookie';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { compatibility, origins } from './config.mjs';
+import { NhsError } from './errors.mjs';
+
+const allowedOrigins = new Set(Object.values(origins).map(value => new URL(value).origin));
+/** @param {string|URL} value @param {string} base */
+export function trustedUrl(value, base = origins.app) {
+  let url;
+  try { url = new URL(value, base); } catch { throw new NhsError('invalid_redirect', 'NHS returned an invalid redirect URL.'); }
+  if (url.protocol !== 'https:' || url.username || url.password || !allowedOrigins.has(url.origin)) throw new NhsError('untrusted_redirect', 'NHS returned a redirect outside the supported HTTPS origins.');
+  return url;
+}
+
+export class Transport {
+  constructor({ fetchImpl = fetch, timeoutMs = 30000, pause = sleep } = {}) {
+    this.fetchImpl = fetchImpl; this.timeoutMs = timeoutMs; this.pause = pause;
+  }
+  /** @param {string|URL} value @param {RequestInit & {jar?: CookieJar}} options */
+  async raw(value, options = {}) {
+    const url = trustedUrl(value);
+    const { jar, ...init } = options;
+    const headers = new Headers(init.headers);
+    headers.set('User-Agent', compatibility.userAgent);
+    if (jar) {
+      const cookie = await jar.getCookieString(url.toString());
+      if (cookie) headers.set('Cookie', cookie);
+    }
+    let response;
+    try {
+      response = await this.fetchImpl(url.toString(), { ...init, headers, redirect: 'manual', signal: AbortSignal.timeout(this.timeoutMs) });
+    } catch {
+      throw new NhsError('network_error', 'NHS could not be reached within the request deadline.');
+    }
+    if (jar) {
+      for (const cookie of response.headers.getSetCookie()) {
+        try { await jar.setCookie(cookie, url.toString()); } catch { throw new NhsError('invalid_response', 'NHS returned an invalid cookie.'); }
+      }
+    }
+    return response;
+  }
+  async redirects(url, jar, stop = (_url) => false) {
+    let current = trustedUrl(url);
+    for (let count = 0; count < 10; count++) {
+      if (stop(current)) return { url: current, response: null };
+      const response = await this.raw(current, { jar });
+      if (response.status < 300 || response.status >= 400) return { url: current, response };
+      const location = response.headers.get('location');
+      await response.body?.cancel();
+      if (!location) throw new NhsError('invalid_redirect', 'NHS returned a redirect without a destination.');
+      current = trustedUrl(location, current.toString());
+    }
+    throw new NhsError('redirect_limit', 'NHS authentication exceeded the redirect limit.');
+  }
+}
+
+export async function jsonResponse(response) {
+  try {
+    const text = await boundedBody(response, 8 * 1024 * 1024);
+    return JSON.parse(text.toString('utf8'));
+  } catch (error) {
+    if (error instanceof NhsError) throw error;
+    throw new NhsError('invalid_response', 'NHS returned invalid JSON.');
+  }
+}
+
+export async function boundedBody(response, limit) {
+  if (Number(response.headers.get('content-length')) > limit) {
+    await response.body?.cancel();
+    throw new NhsError('response_too_large', 'NHS response exceeds the supported size.');
+  }
+  const reader = response.body?.getReader();
+  if (!reader) return Buffer.alloc(0);
+  const chunks = []; let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read(); if (done) break;
+      size += value.length;
+      if (size > limit) { await reader.cancel(); throw new NhsError('response_too_large', 'NHS response exceeds the supported size.'); }
+      chunks.push(value);
+    }
+    return Buffer.concat(chunks);
+  } catch (error) {
+    if (error instanceof NhsError) throw error;
+    throw new NhsError('network_error', 'NHS response could not be read within the request deadline.');
+  } finally { reader.releaseLock(); }
+}
+
+export async function assertHttp(response, operation = 'request') {
+  if (response.ok) return;
+  await response.body?.cancel();
+  if (response.status === 401) throw new NhsError('session_expired', 'NHS session has expired.');
+  if (response.status === 403) throw new NhsError('access_denied', 'NHS denied access to this operation.');
+  if (response.status === 404 || response.status === 501) throw new NhsError('unsupported', 'This NHS operation is unavailable for this account or client version.');
+  if (response.status === 429) throw new NhsError('rate_limited', 'NHS is limiting requests. Wait before trying again.');
+  if (response.status >= 500) throw new NhsError('upstream_unavailable', 'NHS or the GP provider is temporarily unavailable.', { status: response.status });
+  throw new NhsError('request_failed', `NHS ${operation} failed.`, { status: response.status });
+}
+
+/** @param {import('./types.mjs').Session} session */
+export function apiHeaders(session, bearer = false) {
+  /** @type {Record<string, string>} */
+  const headers = {
+    Accept: 'application/json', 'Content-Type': 'application/json',
+    'NHSO-Request-ID': randomUUID(), 'NHSO-Web-Version-Tag': compatibility.webVersion,
+    'NHSO-Native-Version-Tag': compatibility.nativeVersion,
+    Origin: origins.app, Referer: `${origins.app}/`,
+  };
+  if (session.csrfToken) headers['X-CSRF-TOKEN'] = session.csrfToken;
+  if (session.patientId) headers['NHSO-Patient-Id'] = session.patientId;
+  if (bearer && session.accessToken) headers.Authorization = `Bearer ${session.accessToken}`;
+  return headers;
+}
+
+export { CookieJar };

package/src/types.mjs

@@ -0,0 +1,13 @@
+/**
+ * @typedef {null | boolean | number | string | JsonValue[] | {[key: string]: JsonValue}} JsonValue
+ * @typedef {{email: string, password: string}} Credentials
+ * @typedef {{csrfToken?: string, patientId?: string, sessionId?: string,
+ * sessionExpiry?: string, accessToken?: string, rememberMyDevice?: string,
+ * rmdToken?: string, lastOtpTriggerAt?: string, updatedAt?: string,
+ * hasGpSession?: boolean, sessionTimeout?: number, checkedAt?: number,
+ * cookies?: import('tough-cookie').SerializedCookieJar}} Session
+ * @typedef {{version: 1, session: Session, credentials?: Credentials, credentialAccount?: string, legacyMigrated?: boolean, legacyMigrationDigest?: string}} Vault
+ * @typedef {{load(): Promise<Vault>, save(value: Vault): Promise<void>,
+ * probe(): Promise<void>, backend: string}} SecureStore
+ */
+export {};