@schema-weaver/pg-connector 0.0.0-stage → 2.0.0

package/dist/cjs/config/schema.js

@@ -0,0 +1,197 @@
+"use strict";
+/**
+ * Config errors and hand-rolled validators for machine and database config files.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigNotFoundError = exports.ConfigInvalidError = exports.ConfigError = void 0;
+exports.isValidHostname = isValidHostname;
+exports.isValidIpv4 = isValidIpv4;
+exports.isValidIpv6 = isValidIpv6;
+exports.isValidEnvVarName = isValidEnvVarName;
+exports.isValidIso8601 = isValidIso8601;
+exports.isValidIdentifier = isValidIdentifier;
+exports.parseSecureUrl = parseSecureUrl;
+exports.isSecureCloudUrl = isSecureCloudUrl;
+exports.isSecureIngestUrl = isSecureIngestUrl;
+exports.writeConfigFileAtomic = writeConfigFileAtomic;
+exports.redactSecrets = redactSecrets;
+const atomic_write_1 = require("./atomic-write");
+class ConfigError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ConfigError';
+    }
+}
+exports.ConfigError = ConfigError;
+class ConfigInvalidError extends ConfigError {
+    constructor(message) {
+        super('invalid', message);
+        this.name = 'ConfigInvalidError';
+    }
+}
+exports.ConfigInvalidError = ConfigInvalidError;
+class ConfigNotFoundError extends ConfigError {
+    constructor(path) {
+        super('not_found', `Config file not found: ${path}`);
+        this.name = 'ConfigNotFoundError';
+    }
+}
+exports.ConfigNotFoundError = ConfigNotFoundError;
+/**
+ * Checks if a string is a valid hostname.
+ */
+function isValidHostname(s) {
+    if (typeof s !== 'string')
+        return false;
+    if (s.length === 0 || s.length > 253)
+        return false;
+    const labelRegex = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/;
+    if (!s.includes('.')) {
+        return labelRegex.test(s);
+    }
+    const labels = s.split('.');
+    return labels.every((label) => labelRegex.test(label));
+}
+/**
+ * Checks if a string is a valid IPv4 address.
+ */
+function isValidIpv4(s) {
+    if (typeof s !== 'string')
+        return false;
+    const parts = s.split('.');
+    if (parts.length !== 4)
+        return false;
+    return parts.every((part) => {
+        if (!/^\d+$/.test(part))
+            return false;
+        const num = parseInt(part, 10);
+        return num >= 0 && num <= 255 && String(num) === part;
+    });
+}
+/**
+ * Checks if a string is a valid IPv6 address.
+ */
+function isValidIpv6(s) {
+    if (typeof s !== 'string')
+        return false;
+    const ipv6Regex = /^(([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,3}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,2}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}|::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9]))$/;
+    return ipv6Regex.test(s);
+}
+/**
+ * Checks if a string is a valid environment variable name.
+ */
+function isValidEnvVarName(s) {
+    if (typeof s !== 'string')
+        return false;
+    return /^[A-Z][A-Z0-9_]*$/.test(s);
+}
+/**
+ * Checks if a string is a valid ISO 8601 timestamp.
+ */
+function isValidIso8601(s) {
+    if (typeof s !== 'string')
+        return false;
+    const iso8601Regex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+    if (!iso8601Regex.test(s))
+        return false;
+    const d = new Date(s);
+    return !isNaN(d.getTime());
+}
+/**
+ * Checks if a string contains only letters, numbers, hyphens, and underscores, up to maxLen.
+ */
+function isValidIdentifier(s, maxLen) {
+    if (typeof s !== 'string')
+        return false;
+    if (s.length === 0 || s.length > maxLen)
+        return false;
+    return /^[a-zA-Z0-9_-]+$/.test(s);
+}
+/** Longest cloud/telemetry URL accepted. */
+const MAX_URL_LENGTH = 2048;
+function hasControlOrSpace(raw) {
+    for (let i = 0; i < raw.length; i++) {
+        const code = raw.charCodeAt(i);
+        if (code <= 0x20 || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+/**
+ * Strictly parses a URL that is required to use `scheme` with an explicit
+ * "//" authority separator.
+ *
+ * The scheme is matched against the raw string with a case-sensitive prefix
+ * check *and* against the parsed URL, because the WHATWG parser normalises
+ * several downgrade shapes that must be rejected: "WSS://host" lower-cases to
+ * the "wss:" scheme, and "wss:/host" (single slash) is happily parsed as the
+ * host. Either one alone would be a bypassable transport check.
+ */
+function parseSecureUrl(raw, scheme) {
+    if (typeof raw !== 'string')
+        return null;
+    const prefix = `${scheme}//`;
+    if (raw.length < prefix.length + 1 || raw.length > MAX_URL_LENGTH)
+        return null;
+    if (hasControlOrSpace(raw))
+        return null;
+    if (!raw.startsWith(prefix))
+        return null;
+    // "wss:///host" parses as host "host": the authority must start immediately.
+    if (raw[prefix.length] === '/')
+        return null;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== scheme)
+        return null;
+    if (url.hostname.length === 0)
+        return null;
+    if (url.username.length > 0 || url.password.length > 0)
+        return null;
+    if (url.hostname.includes('..'))
+        return null;
+    return url;
+}
+/**
+ * True only for a wss: URL with an explicit lowercase "//" authority.
+ * ws:, http:, WSS: and "wss:/x" are all rejected.
+ */
+function isSecureCloudUrl(raw) {
+    return parseSecureUrl(raw, 'wss:') !== null;
+}
+/**
+ * True only for an https: URL with an explicit lowercase "//" authority.
+ * http: is rejected.
+ */
+function isSecureIngestUrl(raw) {
+    return parseSecureUrl(raw, 'https:') !== null;
+}
+/**
+ * Writes a config file atomically with the given owner-only mode: a
+ * create-only mode option is not a control, so the mode is applied explicitly
+ * to both the temporary file and, through the rename, the final file.
+ */
+function writeConfigFileAtomic(filePath, contents, mode) {
+    (0, atomic_write_1.atomicWriteFile)(filePath, contents, mode);
+}
+/**
+ * Redacts secret material from text that is about to be printed or logged.
+ * Replaces each known secret and any URL userinfo password with "***".
+ */
+function redactSecrets(text, ...secrets) {
+    let out = text.replace(/([a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^:@/\s]*:)[^@/\s]*@/g, '$1***@');
+    for (const secret of secrets) {
+        if (typeof secret === 'string' && secret.length > 0) {
+            out = out.split(secret).join('***');
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=schema.js.map

package/dist/cjs/config/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/config/schema.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AA+BH,0CASC;AAKD,kCASC;AAKD,kCAKC;AAKD,8CAGC;AAKD,wCAMC;AAKD,8CAIC;AA0BD,wCAqBC;AAMD,4CAEC;AAMD,8CAEC;AAOD,sDAEC;AAMD,sCAQC;AAhLD,iDAAiD;AAEjD,MAAa,WAAY,SAAQ,KAAK;IAE3B;IADT,YACS,IAA8C,EACrD,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHR,SAAI,GAAJ,IAAI,CAA0C;QAIrD,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AARD,kCAQC;AAED,MAAa,kBAAmB,SAAQ,WAAW;IACjD,YAAY,OAAe;QACzB,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AALD,gDAKC;AAED,MAAa,mBAAoB,SAAQ,WAAW;IAClD,YAAY,IAAY;QACtB,KAAK,CAAC,WAAW,EAAE,0BAA0B,IAAI,EAAE,CAAC,CAAC;QACrD,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AALD,kDAKC;AAED;;GAEG;AACH,SAAgB,eAAe,CAAC,CAAS;IACvC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,GAAG;QAAE,OAAO,KAAK,CAAC;IACnD,MAAM,UAAU,GAAG,+CAA+C,CAAC;IACnE,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5B,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;GAEG;AACH,SAAgB,WAAW,CAAC,CAAS;IACnC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACxC,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACrC,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE;QAC1B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QACtC,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC/B,OAAO,GAAG,IAAI,CAAC,IAAI,GAAG,IAAI,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;IACxD,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,SAAgB,WAAW,CAAC,CAAS;IACnC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACxC,MAAM,SAAS,GACb,upBAAupB,CAAC;IAC1pB,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,SAAgB,iBAAiB,CAAC,CAAS;IACzC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,SAAgB,cAAc,CAAC,CAAS;IACtC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACxC,MAAM,YAAY,GAAG,kEAAkE,CAAC;IACxF,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACxC,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;IACtB,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,SAAgB,iBAAiB,CAAC,CAAS,EAAE,MAAc;IACzD,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,MAAM;QAAE,OAAO,KAAK,CAAC;IACtD,OAAO,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC;AAKD,4CAA4C;AAC5C,MAAM,cAAc,GAAG,IAAI,CAAC;AAE5B,SAAS,iBAAiB,CAAC,GAAW;IACpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC/B,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;IACjD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,cAAc,CAAC,GAAY,EAAE,MAAoB;IAC/D,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC;IAC7B,IAAI,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,cAAc;QAAE,OAAO,IAAI,CAAC;IAC/E,IAAI,iBAAiB,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,6EAA6E;IAC7E,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAE5C,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,GAAG,CAAC,QAAQ,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACzC,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3C,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACpE,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,GAAY;IAC3C,OAAO,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,SAAgB,iBAAiB,CAAC,GAAY;IAC5C,OAAO,cAAc,CAAC,GAAG,EAAE,QAAQ,CAAC,KAAK,IAAI,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,SAAgB,qBAAqB,CAAC,QAAgB,EAAE,QAAgB,EAAE,IAAY;IACpF,IAAA,8BAAe,EAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAC,IAAY,EAAE,GAAG,OAA+B;IAC5E,IAAI,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,oDAAoD,EAAE,QAAQ,CAAC,CAAC;IACvF,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpD,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/cjs/config/token.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Generates a cryptographically random agent token starting with swagt_ followed by 32 base62 characters.
+ */
+export declare function generateAgentToken(): string;
+/**
+ * Validates the format of an agent token.
+ * Returns true if it starts with "swagt_" and the body contains exactly 32 base62 characters.
+ */
+export declare function validateAgentTokenFormat(token: string): boolean;
+/**
+ * Generates an agent ID from the machine label and a random 8 hex char suffix.
+ */
+export declare function generateAgentId(machineLabel: string): string;
+/**
+ * The only token accepted in place of a generated one, for local development
+ * against a dev relay. It is not a credential: every caller must refuse to ship
+ * it to the cloud (see {@link isDevToken}), because it authenticates nothing.
+ */
+export declare const DEV_TOKEN = "swagt_DEV_LOCAL_ONLY";
+/**
+ * True when `token` is the local development token.
+ *
+ * Contract: accepts `unknown` so call sites reading a token out of a config
+ * file, an env var or a cloud payload cannot pass a value the type system
+ * claims is a string when it is not; anything that is not exactly
+ * {@link DEV_TOKEN} — including an empty or absent token — is not a dev token.
+ * This deliberately fails closed: a truthy answer must never mean "treat this
+ * as authenticated".
+ */
+export declare function isDevToken(token: unknown): token is typeof DEV_TOKEN;
+/**
+ * Domain-separation label for the relay-facing credential.
+ *
+ * Bumping this invalidates every derived credential, so it must stay stable
+ * across releases and must never be reused for another purpose.
+ */
+export declare const RELAY_CREDENTIAL_LABEL = "sw-agent/relay-auth/v1";
+/**
+ * Derive the credential actually transmitted to the relay.
+ *
+ * The agent keeps its `swagt_…` token locally and never puts it on the wire.
+ * What travels is this derived value, so the long-lived master token does not
+ * appear in proxy logs, TLS-terminating middleboxes, or `ps` output. The relay
+ * derives the same value from the token it holds at pairing time and compares
+ * digests, so it never needs to store a second secret.
+ *
+ * This is a transmission-hygiene measure, NOT an additional authentication
+ * factor. The derived value is itself a bearer credential with the same
+ * authority as the token it came from: anyone who captures it can
+ * authenticate. Its value is that a leaked relay-side credential is scoped to
+ * the relay and does not also yield the agent's master token for reuse against
+ * other endpoints.
+ *
+ * @param token the locally-held agent token
+ * @returns a lowercase hex digest, 64 characters
+ */
+export declare function deriveRelayCredential(token: string): string;
+/**
+ * Constant-time comparison of two derived relay credentials.
+ * Returns false rather than throwing on malformed input.
+ */
+export declare function relayCredentialsMatch(a: unknown, b: unknown): boolean;
+//# sourceMappingURL=token.d.ts.map

package/dist/cjs/config/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../../src/config/token.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAU3C;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAM/D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAI5D;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,yBAAyB,CAAC;AAEhD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,SAAS,CAEpE;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAE/D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAUrE"}

package/dist/cjs/config/token.js

@@ -0,0 +1,146 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RELAY_CREDENTIAL_LABEL = exports.DEV_TOKEN = void 0;
+exports.generateAgentToken = generateAgentToken;
+exports.validateAgentTokenFormat = validateAgentTokenFormat;
+exports.generateAgentId = generateAgentId;
+exports.isDevToken = isDevToken;
+exports.deriveRelayCredential = deriveRelayCredential;
+exports.relayCredentialsMatch = relayCredentialsMatch;
+const crypto = __importStar(require("crypto"));
+const { createHmac, timingSafeEqual } = crypto;
+const BASE62_CHARS = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
+/**
+ * Generates a cryptographically random agent token starting with swagt_ followed by 32 base62 characters.
+ */
+function generateAgentToken() {
+    let result = '';
+    while (result.length < 32) {
+        const bytes = crypto.randomBytes(1);
+        const val = bytes[0];
+        if (val < 248) {
+            result += BASE62_CHARS[val % 62];
+        }
+    }
+    return `swagt_${result}`;
+}
+/**
+ * Validates the format of an agent token.
+ * Returns true if it starts with "swagt_" and the body contains exactly 32 base62 characters.
+ */
+function validateAgentTokenFormat(token) {
+    if (typeof token !== 'string')
+        return false;
+    if (!token.startsWith('swagt_'))
+        return false;
+    const body = token.slice(6);
+    if (body.length !== 32)
+        return false;
+    return /^[a-zA-Z0-9]+$/.test(body);
+}
+/**
+ * Generates an agent ID from the machine label and a random 8 hex char suffix.
+ */
+function generateAgentId(machineLabel) {
+    const cleaned = machineLabel.replace(/[^a-zA-Z0-9_-]/g, '');
+    const hex = crypto.randomBytes(4).toString('hex');
+    return `agt_${cleaned}_${hex}`;
+}
+/**
+ * The only token accepted in place of a generated one, for local development
+ * against a dev relay. It is not a credential: every caller must refuse to ship
+ * it to the cloud (see {@link isDevToken}), because it authenticates nothing.
+ */
+exports.DEV_TOKEN = 'swagt_DEV_LOCAL_ONLY';
+/**
+ * True when `token` is the local development token.
+ *
+ * Contract: accepts `unknown` so call sites reading a token out of a config
+ * file, an env var or a cloud payload cannot pass a value the type system
+ * claims is a string when it is not; anything that is not exactly
+ * {@link DEV_TOKEN} — including an empty or absent token — is not a dev token.
+ * This deliberately fails closed: a truthy answer must never mean "treat this
+ * as authenticated".
+ */
+function isDevToken(token) {
+    return typeof token === 'string' && token === exports.DEV_TOKEN;
+}
+/**
+ * Domain-separation label for the relay-facing credential.
+ *
+ * Bumping this invalidates every derived credential, so it must stay stable
+ * across releases and must never be reused for another purpose.
+ */
+exports.RELAY_CREDENTIAL_LABEL = 'sw-agent/relay-auth/v1';
+/**
+ * Derive the credential actually transmitted to the relay.
+ *
+ * The agent keeps its `swagt_…` token locally and never puts it on the wire.
+ * What travels is this derived value, so the long-lived master token does not
+ * appear in proxy logs, TLS-terminating middleboxes, or `ps` output. The relay
+ * derives the same value from the token it holds at pairing time and compares
+ * digests, so it never needs to store a second secret.
+ *
+ * This is a transmission-hygiene measure, NOT an additional authentication
+ * factor. The derived value is itself a bearer credential with the same
+ * authority as the token it came from: anyone who captures it can
+ * authenticate. Its value is that a leaked relay-side credential is scoped to
+ * the relay and does not also yield the agent's master token for reuse against
+ * other endpoints.
+ *
+ * @param token the locally-held agent token
+ * @returns a lowercase hex digest, 64 characters
+ */
+function deriveRelayCredential(token) {
+    return createHmac('sha256', token).update(exports.RELAY_CREDENTIAL_LABEL, 'utf8').digest('hex');
+}
+/**
+ * Constant-time comparison of two derived relay credentials.
+ * Returns false rather than throwing on malformed input.
+ */
+function relayCredentialsMatch(a, b) {
+    if (typeof a !== 'string' || typeof b !== 'string')
+        return false;
+    const bufA = Buffer.from(a, 'utf8');
+    const bufB = Buffer.from(b, 'utf8');
+    if (bufA.length !== bufB.length || bufA.length === 0) {
+        // Still do the work so timing does not depend on which branch was taken.
+        timingSafeEqual(bufA, bufA);
+        return false;
+    }
+    return timingSafeEqual(bufA, bufB);
+}
+//# sourceMappingURL=token.js.map

package/dist/cjs/config/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../../../src/config/token.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAQA,gDAUC;AAMD,4DAMC;AAKD,0CAIC;AAmBD,gCAEC;AA6BD,sDAEC;AAMD,sDAUC;AA3GD,+CAAiC;AACjC,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,GAAG,MAAM,CAAC;AAE/C,MAAM,YAAY,GAAG,gEAAgE,CAAC;AAEtF;;GAEG;AACH,SAAgB,kBAAkB;IAChC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,OAAO,MAAM,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;QACpC,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACrB,IAAI,GAAG,GAAG,GAAG,EAAE,CAAC;YACd,MAAM,IAAI,YAAY,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IACD,OAAO,SAAS,MAAM,EAAE,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,SAAgB,wBAAwB,CAAC,KAAa;IACpD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9C,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC5B,IAAI,IAAI,CAAC,MAAM,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACrC,OAAO,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe,CAAC,YAAoB;IAClD,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;IAC5D,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClD,OAAO,OAAO,OAAO,IAAI,GAAG,EAAE,CAAC;AACjC,CAAC;AAED;;;;GAIG;AACU,QAAA,SAAS,GAAG,sBAAsB,CAAC;AAEhD;;;;;;;;;GASG;AACH,SAAgB,UAAU,CAAC,KAAc;IACvC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,iBAAS,CAAC;AAC1D,CAAC;AAED;;;;;GAKG;AACU,QAAA,sBAAsB,GAAG,wBAAwB,CAAC;AAE/D;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,qBAAqB,CAAC,KAAa;IACjD,OAAO,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,MAAM,CAAC,8BAAsB,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1F,CAAC;AAED;;;GAGG;AACH,SAAgB,qBAAqB,CAAC,CAAU,EAAE,CAAU;IAC1D,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACjE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACpC,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrD,yEAAyE;QACzE,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC5B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACrC,CAAC"}

package/dist/cjs/execution/canceller.d.ts

@@ -0,0 +1,41 @@
+import { DbEntry } from '../config/db-config';
+import { InFlightRequest } from './types';
+import { PoolManager } from './pool';
+export interface CancellerOptions {
+    /**
+     * Reuse the pool for the cancellation connection.
+     *
+     * This is not an optimisation: without it every cancel opened a brand-new
+     * TCP + TLS + password-authenticated PostgreSQL connection, so a stream of
+     * cancel requests could exhaust `max_connections` on the customer's database.
+     */
+    poolManager?: PoolManager;
+}
+export interface CancelResult {
+    /** Whether a cancellation signal was delivered to the request. */
+    cancelled: boolean;
+    /** Whether the PostgreSQL backend was actually signalled. */
+    terminated: boolean;
+    /**
+     * Whether the in-process cooperative abort fired. The local runner stops at
+     * its next checkpoint without any database round trip, so this can be true
+     * while `terminated` is false — a blocked server-side statement is still
+     * running until `pg_cancel_backend` reaches it.
+     */
+    local_abort: boolean;
+    reason?: string;
+}
+export declare class Canceller {
+    private readonly inFlight;
+    private readonly opts;
+    constructor(opts?: CancellerOptions);
+    register(req: InFlightRequest): void;
+    unregister(requestId: string): void;
+    getInFlight(): Map<string, InFlightRequest>;
+    /**
+     * Cancel a request by request_id using pg_cancel_backend on a separate
+     * connection (PostgreSQL cannot cancel a query from the busy session).
+     */
+    cancel(requestId: string, dbEntry: DbEntry): Promise<CancelResult>;
+}
+//# sourceMappingURL=canceller.d.ts.map

package/dist/cjs/execution/canceller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canceller.d.ts","sourceRoot":"","sources":["../../../src/execution/canceller.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAmD,MAAM,QAAQ,CAAC;AAEtF,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,SAAS,EAAE,OAAO,CAAC;IACnB,6DAA6D;IAC7D,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2C;IACpE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;gBAE5B,IAAI,GAAE,gBAAqB;IAIvC,QAAQ,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAIpC,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAInC,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC;IAI3C;;;OAGG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC;CAuMzE"}