@tak-ps/node-tak 12.24.0 → 12.26.0

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../cli.ts","../index.ts","../test/default.test.ts","../test/findCoT.test.ts","../test/mission-layer.test.ts","../test/mission.test.ts","../test/pipeline.test.ts","../test/queue.test.ts","../test/uploadPackage.test.ts","../lib/api.ts","../lib/auth.ts","../lib/commands.ts","../lib/fetch.ts","../lib/multipart.ts","../lib/stream.ts","../lib/api/certificate.ts","../lib/api/client.ts","../lib/api/contacts.ts","../lib/api/credentials.ts","../lib/api/export.ts","../lib/api/files.ts","../lib/api/groups.ts","../lib/api/iconsets.ts","../lib/api/injectors.ts","../lib/api/locate.ts","../lib/api/mission-invite.ts","../lib/api/mission-layer.ts","../lib/api/mission-log.ts","../lib/api/mission.ts","../lib/api/oauth.ts","../lib/api/package.ts","../lib/api/profile.ts","../lib/api/query.ts","../lib/api/repeater.ts","../lib/api/security.ts","../lib/api/subscriptions.ts","../lib/api/types.ts","../lib/api/video.ts","../lib/utils/queue.ts"],"version":"6.0.3"}
+{"root":["../cli.ts","../index.ts","../test/certificate.test.ts","../test/default.test.ts","../test/findCoT.test.ts","../test/html-error.test.ts","../test/mission-layer.test.ts","../test/mission.test.ts","../test/pipeline.test.ts","../test/queue.test.ts","../test/uploadPackage.test.ts","../lib/api.ts","../lib/auth.ts","../lib/commands.ts","../lib/fetch.ts","../lib/multipart.ts","../lib/stream.ts","../lib/api/certificate.ts","../lib/api/client.ts","../lib/api/contacts.ts","../lib/api/credentials.ts","../lib/api/export.ts","../lib/api/files.ts","../lib/api/groups.ts","../lib/api/iconsets.ts","../lib/api/injectors.ts","../lib/api/locate.ts","../lib/api/mission-invite.ts","../lib/api/mission-layer.ts","../lib/api/mission-log.ts","../lib/api/mission.ts","../lib/api/oauth.ts","../lib/api/package.ts","../lib/api/profile.ts","../lib/api/query.ts","../lib/api/repeater.ts","../lib/api/security.ts","../lib/api/subscriptions.ts","../lib/api/types.ts","../lib/api/video.ts","../lib/utils/html-error.ts","../lib/utils/queue.ts"],"version":"6.0.3"}

package/index.ts

@@ -9,6 +9,7 @@ import TAKAPI from './lib/api.js';
 import { TAKAuth } from './lib/auth.js';
 import { Queue } from './lib/utils/queue.js';
 export * from './lib/auth.js';
+export * from './lib/utils/html-error.js';
 
 /* eslint-disable no-control-regex */
 export const REGEX_CONTROL = /[\u000B-\u001F\u007F-\u009F]/g;

package/lib/api/certificate.ts

@@ -1,4 +1,8 @@
 import Commands from '../commands.js';
+import Err from '@openaddresses/batch-error';
+import { Readable } from 'node:stream';
+import { X509Certificate } from 'node:crypto';
+import { TAKServerError } from '../utils/html-error.js';
 import { Type } from '@sinclair/typebox';
 import type { Static } from '@sinclair/typebox';
 import { TAKItem, TAKList } from './types.js';
@@ -22,6 +26,44 @@ export const Certificate = Type.Object({
 export const TAKList_Certificate = TAKList(Certificate);
 export const TAKItem_Certificate = TAKItem(Certificate);
 
+export const CertificateValidation = Type.Object({
+    fingerprint: Type.String({ description: 'SHA-256 fingerprint of the DER encoded certificate - the TAK Server `hash`' }),
+    subject: Type.String(),
+    username: Type.String({ description: 'Common Name of the certificate subject - the TAK Server `userDn`' }),
+    validFrom: Type.String(),
+    validTo: Type.String(),
+    expired: Type.Boolean({ description: 'validTo is in the past' }),
+    known: Type.Boolean({ description: 'The TAK Server has a record for this fingerprint' }),
+    revoked: Type.Boolean({ description: 'The TAK Server record carries a revocationDate' }),
+    revocationDate: Type.Optional(Type.String({ format: 'date-time' })),
+    valid: Type.Boolean({ description: 'Neither expired nor revoked' }),
+    certificate: Type.Optional(Certificate)
+});
+
+export const CertificateProbe = Type.Object({
+    accepted: Type.Boolean({ description: 'The TAK Server authenticated the credentials' }),
+    version: Type.Optional(Type.String({ description: 'TAK Server version string when accepted' })),
+    reason: Type.Optional(Type.Union([
+        Type.Literal('revoked', { description: 'X509Authenticator raised RevokedException' }),
+        Type.Literal('rejected', { description: 'Authentication failed for another reason (BadCredentialsException)' }),
+        Type.Literal('tls', { description: 'The TLS handshake failed - typically an expired or untrusted client certificate' })
+    ])),
+    message: Type.Optional(Type.String())
+});
+
+/**
+ * Extract the Common Name from an X509 subject string as reported by Node
+ * (newline separated `key=value` pairs)
+ */
+function commonName(subject: string): string | undefined {
+    for (const line of subject.split('\n')) {
+        const [key, ...rest] = line.split('=');
+        if (key.trim() === 'CN') return rest.join('=').trim();
+    }
+
+    return undefined;
+}
+
 export default class CertificateCommands extends Commands {
     schema = {}
 
@@ -46,6 +88,19 @@ export default class CertificateCommands extends Commands {
         return await this.api.fetch(url) as Static<typeof TAKList_Certificate>;
     }
 
+    /**
+     * List Active Certificates
+     *
+     * The most recently issued certificate for each Client UID / User DN pair
+     *
+     * {@link https://docs.tak.gov/api/takserver/redoc#tag/cert-manager-admin-api/operation/getActive TAK Server Docs}.
+     */
+    async listActive(): Promise<Static<typeof TAKList_Certificate>> {
+        const url = new URL('/Marti/api/certadmin/cert/active', this.api.url);
+
+        return await this.api.fetch(url) as Static<typeof TAKList_Certificate>;
+    }
+
     /**
      * List Revoked Certificates
      *
@@ -79,6 +134,105 @@ export default class CertificateCommands extends Commands {
         return await this.api.fetch(url) as Static<typeof TAKList_Certificate>;
     }
 
+    /**
+     * Probe whether the TAK Server accepts the credentials this API instance was created with
+     *
+     * The X509 filter runs on every request and rethrows on failure, so `GET /Marti/api/version`
+     * (an anonymous, DB-free endpoint returning a short string) is the cheapest authoritative
+     * check - unlike {@link validate} it reflects the server's actual enforcement (e.g. whether
+     * `x509checkRevocation` is enabled) and requires no admin credentials. An expired client
+     * certificate is rejected during the TLS handshake and surfaces as `reason: 'tls'`.
+     *
+     * Only authentication failures are returned as a verdict - any other error (server
+     * unreachable, unexpected status) is rethrown so it is not mistaken for a rejection
+     */
+    async probe(): Promise<Static<typeof CertificateProbe>> {
+        const url = new URL('/Marti/api/version', this.api.url);
+
+        try {
+            const version = String(await this.api.fetch(url)).trim();
+
+            return { accepted: true, version };
+        } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const details = err instanceof TAKServerError ? err.details : '';
+            const haystack = `${message}\n${details}`;
+
+            let reason: Static<typeof CertificateProbe>['reason'];
+            if (/RevokedException|revoked certificate/i.test(haystack)) {
+                reason = 'revoked';
+            } else if (/BadCredentialsException|AuthenticationException|TAK Server authentication/i.test(haystack)) {
+                reason = 'rejected';
+            } else if (
+                err instanceof Err && err.status === 400 && !(err instanceof TAKServerError)
+                && /certificate|handshake|alert|EPROTO|ECONNRESET|SSL|TLS/i.test(haystack)
+            ) {
+                reason = 'tls';
+            } else {
+                throw err;
+            }
+
+            return { accepted: false, reason, message };
+        }
+    }
+
+    /**
+     * Validate a PEM encoded client certificate against local expiry and the TAK Server revocation record
+     *
+     * Expiry is evaluated locally from the certificate. Revocation is looked up via the
+     * Certificate Admin API using the same SHA-256 fingerprint the TAK Server `X509Authenticator`
+     * consults - `get(hash)` first (a single cached row) falling back to the user's certificate
+     * list when the TAK Server answers 500, which is how it reports an unknown hash.
+     *
+     * Note: The TAK Server only enforces revocation when `auth.x509checkRevocation` (or
+     * `x509TokenAuth`) is enabled in CoreConfig - `revoked` reports the stored state regardless
+     */
+    async validate(
+        pem: string,
+        opts: {
+            now?: Date;
+        } = {}
+    ): Promise<Static<typeof CertificateValidation>> {
+        const x509 = new X509Certificate(pem);
+        const now = opts.now ?? new Date();
+
+        const username = commonName(x509.subject);
+        if (!username) throw new Error('Certificate subject does not contain a Common Name');
+
+        const fingerprint = x509.fingerprint256.toUpperCase();
+
+        let certificate: Static<typeof Certificate> | undefined;
+        try {
+            // Single cached row lookup - the same query X509Authenticator performs
+            certificate = (await this.get(fingerprint)).data;
+        } catch (err) {
+            // The TAK Server reports an unknown hash via sendError(500), which is
+            // indistinguishable from a genuine failure - disambiguate against the
+            // (uncached, but authoritative) list of the user's certificates
+            if (!(err instanceof Err) || err.status < 500) throw err;
+
+            certificate = (await this.list(username)).data
+                .find((cert) => cert.hash.toUpperCase() === fingerprint);
+        }
+
+        const expired = Date.parse(x509.validTo) < now.getTime();
+        const revoked = !!certificate?.revocationDate;
+
+        return {
+            fingerprint,
+            subject: x509.subject,
+            username,
+            validFrom: x509.validFrom,
+            validTo: x509.validTo,
+            expired,
+            known: !!certificate,
+            revoked,
+            revocationDate: certificate?.revocationDate,
+            valid: !expired && !revoked,
+            certificate
+        };
+    }
+
     /**
      * Get Single Certificate
      *
@@ -107,6 +261,36 @@ export default class CertificateCommands extends Commands {
         }) as string;
     }
 
+    /**
+     * Download Certificates by Id
+     *
+     * Returns a ZIP archive stream containing one `{n}_{userDn}_ClientCert.pem` entry per certificate
+     *
+     * {@link https://docs.tak.gov/api/takserver/redoc#tag/cert-manager-admin-api/operation/downloadCertificates TAK Server Docs}.
+     */
+    async downloadIds(
+        ids: Array<string | number>
+    ): Promise<Readable> {
+        if (ids.length === 0) {
+            throw new Error('At least one ID must be provided');
+        }
+
+        const url = new URL(`/Marti/api/certadmin/cert/download/${ids.map((id) => encodeURIComponent(String(id))).join(',')}`, this.api.url);
+
+        const res = await this.api.fetch(url, {
+            method: 'GET'
+        }, true);
+
+        // The raw fetch path skips status validation - without this check a
+        // TAK Server error page would be streamed as if it were the ZIP archive
+        if (res.status < 200 || res.status >= 400) {
+            const body = await res.text().catch(() => '');
+            throw new Err(res.status, null, body || `Status Code: ${res.status}`);
+        }
+
+        return res.body;
+    }
+
     /**
      * Revoke Single Certificate
      *

package/lib/api.ts

@@ -21,6 +21,7 @@ import Subscription from './api/subscriptions.js';
 import Video from './api/video.js';
 import Export from './api/export.js';
 import Err from '@openaddresses/batch-error';
+import { TAKServerError, isHTML } from './utils/html-error.js';
 import * as auth from './auth.js';
 
 type ErrorWithCause = Error & {
@@ -210,6 +211,9 @@ export default class TAKAPI {
                     bdy = null;
                 }
 
+                // TAK Server returns HTML error pages
+                if (isHTML(bdy)) throw new TAKServerError(res.status, bdy);
+
                 throw new Err(res.status, null, bdy || `Status Code: ${res.status}`);
             }
 
@@ -219,7 +223,7 @@ export default class TAKAPI {
                 return await res.text();
             }
         } catch (err) {
-            if (err instanceof Error && err.name === 'PublicError') throw err;
+            if (err instanceof Err) throw err;
             throw new Err(400, null, formatFetchError(err));
         }
     }

package/lib/utils/html-error.ts

@@ -0,0 +1,208 @@
+import Err from '@openaddresses/batch-error';
+import xmljs from '@tak-ps/xml-js';
+import type { Element } from '@tak-ps/xml-js';
+
+/**
+ * TAK Server (Tomcat) returns HTML "Exception Report" pages on failure.
+ * Parse them into a human readable message + plain-text details
+ * so clients don't render raw HTML.
+ */
+export interface HTMLErrorDetails {
+    /** <title> or <h1> */
+    title?: string;
+    /** <p><b>Label</b> value</p> pairs - ie: Type, Message, Description */
+    fields: Record<string, string>;
+    /** <pre> stack traces */
+    exception?: string;
+    /** Visible text fallback */
+    text: string;
+}
+
+const HIDDEN = new Set(['style', 'script', 'head']);
+
+function collapse(input: string): string {
+    return input.replace(/\s+/g, ' ').trim();
+}
+
+/** Linear-time tag stripper for malformed HTML - drops the contents of HIDDEN elements */
+function stripTags(html: string): string {
+    const lower = html.toLowerCase();
+    let out = '';
+    let i = 0;
+
+    while (i < html.length) {
+        const open = html.indexOf('<', i);
+        if (open === -1) {
+            out += html.slice(i);
+            break;
+        }
+
+        out += html.slice(i, open) + ' ';
+
+        const close = html.indexOf('>', open);
+        if (close === -1) break;
+
+        const tag = lower.slice(open + 1, close).trim().split(/\s/, 1)[0];
+        i = close + 1;
+
+        if (HIDDEN.has(tag)) {
+            const end = lower.indexOf(`</${tag}`, i);
+            if (end === -1) break;
+            i = html.indexOf('>', end);
+            if (i === -1) break;
+            i += 1;
+        }
+    }
+
+    return collapse(out);
+}
+
+function textOf(el: Element, opts: { skipPre?: boolean } = {}): string {
+    if (el.type === 'text') return String(el.text ?? '');
+    if (el.type !== 'element' || !el.elements) return '';
+    if (opts.skipPre && el.name === 'pre') return '';
+
+    return el.elements.map((child) => textOf(child, opts)).join('');
+}
+
+function* walk(el: Element, skipHidden = true): Generator<Element> {
+    if (el.type === 'element' && el.name && skipHidden && HIDDEN.has(el.name.toLowerCase())) return;
+
+    if (el.type === 'element') yield el;
+
+    for (const child of el.elements || []) yield* walk(child, skipHidden);
+}
+
+function find(root: Element, name: string): Element | undefined {
+    for (const el of walk(root, false)) {
+        if (el.name?.toLowerCase() === name) return el;
+    }
+}
+
+export function isHTML(body: unknown): body is string {
+    if (typeof body !== 'string') return false;
+
+    const head = body.slice(0, 512).trimStart().toLowerCase();
+
+    return head.startsWith('<!doctype html')
+        || head.startsWith('<html')
+        || /^<(head|body|title|h1)[\s>]/.test(head);
+}
+
+/** Returns null if body is not HTML */
+export function parseHTMLError(body: unknown): HTMLErrorDetails | null {
+    if (!isHTML(body)) return null;
+
+    const details: HTMLErrorDetails = {
+        fields: {},
+        text: '',
+    };
+
+    let root: Element;
+    try {
+        root = xmljs.xml2js(body, { compact: false }) as Element;
+    } catch {
+        // Not well-formed XHTML - fall back to visible text
+        details.text = stripTags(body);
+
+        return details;
+    }
+
+    const title = find(root, 'title') || find(root, 'h1');
+    if (title && collapse(textOf(title))) details.title = collapse(textOf(title));
+
+    const pres: string[] = [];
+    let text = '';
+
+    for (const el of walk(root)) {
+        const name = el.name?.toLowerCase();
+
+        if (name === 'p' && el.elements?.[0]?.name?.toLowerCase() === 'b') {
+            const label = collapse(textOf(el.elements[0]));
+            const value = collapse(el.elements.slice(1).map((child) => textOf(child)).join(''));
+
+            if (label && value) details.fields[label] = value;
+        } else if (name === 'pre') {
+            const value = textOf(el)
+                .split('\n')
+                .map((line) => line.trimEnd())
+                .join('\n')
+                .trim();
+
+            if (value) pres.push(value);
+        } else if (name === 'body') {
+            text = collapse(textOf(el, { skipPre: true }));
+        }
+    }
+
+    if (pres.length) details.exception = pres.join('\n\n');
+
+    details.text = text || collapse(textOf(root, { skipPre: true }));
+
+    return details;
+}
+
+/** Most useful human readable line from the page */
+export function summarizeHTMLError(details: HTMLErrorDetails, status?: number): string {
+    const message = details.fields.Message
+        || details.fields.message
+        || details.fields.Description
+        || details.fields.description;
+
+    if (message) return message;
+
+    if (details.exception) {
+        // "<ExceptionClass>: <message>"
+        const first = details.exception.split('\n')[0].trim();
+        const colon = first.indexOf(': ');
+        if (colon !== -1 && colon < first.length - 2) return first.slice(colon + 2).trim();
+    }
+
+    if (details.title) return details.title;
+
+    if (details.text) return details.text.length > 200 ? details.text.slice(0, 197) + '...' : details.text;
+
+    return status ? `Status Code: ${status}` : 'Unknown TAK Server Error';
+}
+
+/** Plain-text breakdown for an "Advanced" details pane */
+export function formatHTMLError(details: HTMLErrorDetails): string {
+    const lines: string[] = [];
+
+    if (details.title) lines.push(details.title);
+
+    for (const [label, value] of Object.entries(details.fields)) {
+        if (value) lines.push(`${label}: ${value}`);
+    }
+
+    if (details.exception) {
+        if (lines.length) lines.push('');
+        lines.push(details.exception);
+    }
+
+    if (!lines.length && details.text) lines.push(details.text);
+
+    return lines.join('\n');
+}
+
+/**
+ * TAK Server HTML error page - `safe` is the summary, `details` the full breakdown
+ */
+export class TAKServerError extends Err {
+    details: string;
+    html: string;
+    parsed: HTMLErrorDetails;
+
+    constructor(status: number, html: string, parsed?: HTMLErrorDetails) {
+        const details = parsed || parseHTMLError(html) || {
+            fields: {},
+            text: stripTags(html)
+        };
+
+        super(status, null, summarizeHTMLError(details, status));
+
+        this.parsed = details;
+        this.details = formatHTMLError(details);
+        this.html = html;
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@tak-ps/node-tak",
     "type": "module",
-    "version": "12.24.0",
+    "version": "12.26.0",
     "description": "Lightweight JavaScript library for communicating with TAK Server",
     "author": "Nick Ingalls <nick@ingalls.ca>",
     "main": "dist/index.js",