@vibe-agent-toolkit/utils 0.1.39-rc.1 → 0.1.39-rc.11

package/dist/link-auth/select-provider.js

@@ -0,0 +1,55 @@
+/**
+ * Provider selection by URL host.
+ *
+ * Iterates the configured providers in order; the first one whose `match.host`
+ * glob matches the URL hostname (and no `match.excludeHost` glob excludes it)
+ * claims the URL. Returns `undefined` if no provider claims it — the caller
+ * then falls back to anonymous link-checking.
+ *
+ * Hostname matching is case-insensitive per RFC 3986. Pattern syntax follows
+ * `picomatch` (already a utils dep): `*` matches any character, `**` matches
+ * across `/`. For hostnames (no slashes) the practical effect is that `*`
+ * happily matches dots — e.g. `*.sharepoint.com` claims both
+ * `contoso.sharepoint.com` and `foo.bar.sharepoint.com`.
+ *
+ * Per design issue #113 §4 (vocabulary item 1: match.host + excludeHost).
+ */
+import picomatch from 'picomatch';
+/**
+ * Find the first provider whose `match` claims the given URL.
+ *
+ * @returns the matching provider, or `undefined` if none claim the URL (no
+ *   pattern matched, all candidates were excluded, or the URL is malformed).
+ */
+export function selectProvider(url, providers) {
+    const host = extractHostname(url);
+    if (host === undefined)
+        return undefined;
+    for (const provider of providers) {
+        if (matches(host, provider.match)) {
+            return provider;
+        }
+    }
+    return undefined;
+}
+function extractHostname(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+function matches(host, match) {
+    const lowerHost = host.toLowerCase();
+    if (!picomatch.isMatch(lowerHost, match.host.toLowerCase()))
+        return false;
+    if (match.excludeHost !== undefined) {
+        for (const pattern of match.excludeHost) {
+            if (picomatch.isMatch(lowerHost, pattern.toLowerCase()))
+                return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=select-provider.js.map

package/dist/link-auth/select-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-provider.js","sourceRoot":"","sources":["../../src/link-auth/select-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,SAAS,MAAM,WAAW,CAAC;AAOlC;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,GAAW,EACX,SAAuB;IAEvB,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAEzC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,IAAI,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAClC,OAAO,QAAQ,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,eAAe,CAAC,GAAW;IAClC,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,OAAO,CAAC,IAAY,EAAE,KAAoB;IACjD,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACrC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QAAE,OAAO,KAAK,CAAC;IAE1E,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACpC,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;YACxC,IAAI,SAAS,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;gBAAE,OAAO,KAAK,CAAC;QACxE,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/link-auth/template.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Tiny template renderer for linkAuth rewrite + header templates.
+ *
+ * Syntax (strict, no escapes, no nesting):
+ *   - `${name}`              → context[name]
+ *   - `${transform(name)}`   → applyTransform(transform, context[name])
+ *
+ * Anything else inside `${...}` throws `TemplateSyntaxError`. Missing context
+ * keys throw `TemplateMissingVarError`. Unknown transform names propagate
+ * `UnknownTransformError` from the transforms allowlist.
+ *
+ * This is NOT the project's general-purpose Handlebars renderer
+ * (`utils/template.ts`) — that one is `{{...}}` and consumed widely. linkAuth
+ * needs different syntax and a closed transform set; the two coexist by
+ * namespace (`link-auth/template.ts`).
+ */
+/**
+ * Thrown when a template references a variable not present in the context.
+ * Message names the missing variable and includes the full template for
+ * caller-side debugging.
+ */
+export declare class TemplateMissingVarError extends Error {
+    constructor(varName: string, template: string);
+}
+/**
+ * Thrown when a template contains syntactically invalid content inside `${...}`
+ * (empty expression, whitespace, unrecognized form) or an unterminated `${`.
+ */
+export declare class TemplateSyntaxError extends Error {
+    constructor(detail: string, template: string);
+}
+/**
+ * Render a template by substituting `${...}` expressions from a context map.
+ *
+ * @throws {TemplateMissingVarError} if a referenced variable is absent
+ * @throws {TemplateSyntaxError} for invalid expressions or unterminated `${`
+ * @throws {UnknownTransformError} from a `${transform(name)}` call
+ */
+export declare function renderTemplate(template: string, context: Record<string, string>): string;
+//# sourceMappingURL=template.d.ts.map

package/dist/link-auth/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/link-auth/template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAI9C;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAI7C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAUxF"}

package/dist/link-auth/template.js

@@ -0,0 +1,89 @@
+/**
+ * Tiny template renderer for linkAuth rewrite + header templates.
+ *
+ * Syntax (strict, no escapes, no nesting):
+ *   - `${name}`              → context[name]
+ *   - `${transform(name)}`   → applyTransform(transform, context[name])
+ *
+ * Anything else inside `${...}` throws `TemplateSyntaxError`. Missing context
+ * keys throw `TemplateMissingVarError`. Unknown transform names propagate
+ * `UnknownTransformError` from the transforms allowlist.
+ *
+ * This is NOT the project's general-purpose Handlebars renderer
+ * (`utils/template.ts`) — that one is `{{...}}` and consumed widely. linkAuth
+ * needs different syntax and a closed transform set; the two coexist by
+ * namespace (`link-auth/template.ts`).
+ */
+import { applyTransform } from './transforms.js';
+const IDENTIFIER = /^[a-zA-Z_]\w*$/;
+const TRANSFORM_CALL = /^(?<fn>[a-zA-Z_]\w*)\((?<arg>[a-zA-Z_]\w*)\)$/;
+/**
+ * Thrown when a template references a variable not present in the context.
+ * Message names the missing variable and includes the full template for
+ * caller-side debugging.
+ */
+export class TemplateMissingVarError extends Error {
+    constructor(varName, template) {
+        super(`Template variable "${varName}" not in context. Template: ${template}`);
+        this.name = 'TemplateMissingVarError';
+    }
+}
+/**
+ * Thrown when a template contains syntactically invalid content inside `${...}`
+ * (empty expression, whitespace, unrecognized form) or an unterminated `${`.
+ */
+export class TemplateSyntaxError extends Error {
+    constructor(detail, template) {
+        super(`Invalid template syntax — ${detail}. Template: ${template}`);
+        this.name = 'TemplateSyntaxError';
+    }
+}
+/**
+ * Render a template by substituting `${...}` expressions from a context map.
+ *
+ * @throws {TemplateMissingVarError} if a referenced variable is absent
+ * @throws {TemplateSyntaxError} for invalid expressions or unterminated `${`
+ * @throws {UnknownTransformError} from a `${transform(name)}` call
+ */
+export function renderTemplate(template, context) {
+    const rendered = template.replaceAll(/\$\{([^}]*)\}/g, (_match, body) => resolveExpression(body, template, context));
+    if (rendered.includes('${')) {
+        throw new TemplateSyntaxError('unterminated "${" with no matching "}"', template);
+    }
+    return rendered;
+}
+function resolveExpression(body, template, context) {
+    if (body !== body.trim()) {
+        throw new TemplateSyntaxError(`whitespace in "${body}"`, template);
+    }
+    if (IDENTIFIER.test(body)) {
+        return lookupContextVar(context, body, template);
+    }
+    const callMatch = TRANSFORM_CALL.exec(body);
+    if (callMatch?.groups !== undefined) {
+        const { fn, arg } = callMatch.groups;
+        if (fn === undefined || arg === undefined) {
+            throw new TemplateSyntaxError(`unexpected regex result for "${body}"`, template);
+        }
+        return applyTransform(fn, lookupContextVar(context, arg, template));
+    }
+    throw new TemplateSyntaxError(`unrecognized expression "${body}"`, template);
+}
+/**
+ * Fetch a variable from the context map, blocking prototype-chain bypass.
+ *
+ * Without `Object.hasOwn`, `context["__proto__"]` would return `Object.prototype`
+ * (a non-undefined object) and the renderer would substitute `[object Object]`
+ * into the output. Mirrors the closed-allowlist discipline in `transforms.ts`.
+ */
+function lookupContextVar(context, key, template) {
+    if (!Object.hasOwn(context, key)) {
+        throw new TemplateMissingVarError(key, template);
+    }
+    const value = context[key];
+    if (value === undefined) {
+        throw new TemplateMissingVarError(key, template);
+    }
+    return value;
+}
+//# sourceMappingURL=template.js.map

package/dist/link-auth/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../src/link-auth/template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,UAAU,GAAG,gBAAgB,CAAC;AACpC,MAAM,cAAc,GAAG,+CAA+C,CAAC;AAEvE;;;;GAIG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,YAAY,OAAe,EAAE,QAAgB;QAC3C,KAAK,CAAC,sBAAsB,OAAO,+BAA+B,QAAQ,EAAE,CAAC,CAAC;QAC9E,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,MAAc,EAAE,QAAgB;QAC1C,KAAK,CAAC,6BAA6B,MAAM,eAAe,QAAQ,EAAE,CAAC,CAAC;QACpE,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,OAA+B;IAC9E,MAAM,QAAQ,GAAG,QAAQ,CAAC,UAAU,CAAC,gBAAgB,EAAE,CAAC,MAAM,EAAE,IAAY,EAAE,EAAE,CAC9E,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAC3C,CAAC;IAEF,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,mBAAmB,CAAC,wCAAwC,EAAE,QAAQ,CAAC,CAAC;IACpF,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,iBAAiB,CACxB,IAAY,EACZ,QAAgB,EAChB,OAA+B;IAE/B,IAAI,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;QACzB,MAAM,IAAI,mBAAmB,CAAC,kBAAkB,IAAI,GAAG,EAAE,QAAQ,CAAC,CAAC;IACrE,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,OAAO,gBAAgB,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IACnD,CAAC;IAED,MAAM,SAAS,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,SAAS,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;QACpC,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,SAAS,CAAC,MAAM,CAAC;QACrC,IAAI,EAAE,KAAK,SAAS,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YAC1C,MAAM,IAAI,mBAAmB,CAAC,gCAAgC,IAAI,GAAG,EAAE,QAAQ,CAAC,CAAC;QACnF,CAAC;QACD,OAAO,cAAc,CAAC,EAAE,EAAE,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,MAAM,IAAI,mBAAmB,CAAC,4BAA4B,IAAI,GAAG,EAAE,QAAQ,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;GAMG;AACH,SAAS,gBAAgB,CACvB,OAA+B,EAC/B,GAAW,EACX,QAAgB;IAEhB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,uBAAuB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACnD,CAAC;IACD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,uBAAuB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/link-auth/transforms.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Transform allowlist for linkAuth rewrite templates.
+ *
+ * Rewrite `to:` templates may call transforms over named regex captures —
+ * e.g. `${base64url(u)}` for Microsoft Graph share-ids. The allowed set is
+ * frozen in this file: adding a transform requires a VAT PR (see issue #113
+ * design §4.1). There is no arbitrary-evaluation path.
+ *
+ * v1 inputs are assumed to be ASCII URL host/path captures. Non-ASCII edge
+ * cases (lone surrogates) are pinned by tests so future regressions surface.
+ */
+declare const TRANSFORMS: {
+    readonly base64url: (s: string) => string;
+    readonly urlencode: (s: string) => string;
+    readonly lower: (s: string) => string;
+};
+export type TransformName = keyof typeof TRANSFORMS;
+/**
+ * The closed allowlist of transform names. Callers parsing rewrite templates
+ * can validate transform calls (e.g. `${base64url(u)}`) against this list at
+ * config-load time, surfacing typos before any URL is rewritten.
+ */
+export declare const ALLOWED_TRANSFORMS: readonly TransformName[];
+/**
+ * Thrown by `applyTransform` when called with a name not in the closed
+ * allowlist. The message names the bad transform and the full allowlist so
+ * a misconfigured macro surfaces a clear error at load time.
+ */
+export declare class UnknownTransformError extends Error {
+    constructor(name: string);
+}
+/**
+ * Dispatch a transform by name on a string input.
+ *
+ * Security claim: only the names in `ALLOWED_TRANSFORMS` resolve; any other
+ * input throws `UnknownTransformError`. Lookup uses `Object.hasOwn` to block
+ * prototype-chain keys (`toString`, `__proto__`, `constructor`, …) that a
+ * `name in TRANSFORMS` check would let through.
+ *
+ * @throws {UnknownTransformError} if `name` is not in the allowlist
+ * @throws {URIError} from `urlencode` on lone-surrogate inputs — deliberate;
+ *   v1 callers pass URL-derived captures that cannot legally contain these
+ */
+export declare function applyTransform(name: string, input: string): string;
+export {};
+//# sourceMappingURL=transforms.d.ts.map

package/dist/link-auth/transforms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transforms.d.ts","sourceRoot":"","sources":["../../src/link-auth/transforms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,QAAA,MAAM,UAAU;4BACC,MAAM;4BACN,MAAM;wBACV,MAAM;CAC6B,CAAC;AAEjD,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,UAAU,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,aAAa,EAEtD,CAAC;AAEF;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,IAAI,EAAE,MAAM;CAIzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKlE"}

package/dist/link-auth/transforms.js

@@ -0,0 +1,52 @@
+/**
+ * Transform allowlist for linkAuth rewrite templates.
+ *
+ * Rewrite `to:` templates may call transforms over named regex captures —
+ * e.g. `${base64url(u)}` for Microsoft Graph share-ids. The allowed set is
+ * frozen in this file: adding a transform requires a VAT PR (see issue #113
+ * design §4.1). There is no arbitrary-evaluation path.
+ *
+ * v1 inputs are assumed to be ASCII URL host/path captures. Non-ASCII edge
+ * cases (lone surrogates) are pinned by tests so future regressions surface.
+ */
+const TRANSFORMS = {
+    base64url: (s) => Buffer.from(s, 'utf8').toString('base64url'),
+    urlencode: (s) => encodeURIComponent(s),
+    lower: (s) => s.toLowerCase(),
+};
+/**
+ * The closed allowlist of transform names. Callers parsing rewrite templates
+ * can validate transform calls (e.g. `${base64url(u)}`) against this list at
+ * config-load time, surfacing typos before any URL is rewritten.
+ */
+export const ALLOWED_TRANSFORMS = Object.freeze(Object.keys(TRANSFORMS));
+/**
+ * Thrown by `applyTransform` when called with a name not in the closed
+ * allowlist. The message names the bad transform and the full allowlist so
+ * a misconfigured macro surfaces a clear error at load time.
+ */
+export class UnknownTransformError extends Error {
+    constructor(name) {
+        super(`Unknown transform "${name}". Allowed: ${ALLOWED_TRANSFORMS.join(', ')}.`);
+        this.name = 'UnknownTransformError';
+    }
+}
+/**
+ * Dispatch a transform by name on a string input.
+ *
+ * Security claim: only the names in `ALLOWED_TRANSFORMS` resolve; any other
+ * input throws `UnknownTransformError`. Lookup uses `Object.hasOwn` to block
+ * prototype-chain keys (`toString`, `__proto__`, `constructor`, …) that a
+ * `name in TRANSFORMS` check would let through.
+ *
+ * @throws {UnknownTransformError} if `name` is not in the allowlist
+ * @throws {URIError} from `urlencode` on lone-surrogate inputs — deliberate;
+ *   v1 callers pass URL-derived captures that cannot legally contain these
+ */
+export function applyTransform(name, input) {
+    if (!Object.hasOwn(TRANSFORMS, name)) {
+        throw new UnknownTransformError(name);
+    }
+    return TRANSFORMS[name](input);
+}
+//# sourceMappingURL=transforms.js.map

package/dist/link-auth/transforms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transforms.js","sourceRoot":"","sources":["../../src/link-auth/transforms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,UAAU,GAAG;IACjB,SAAS,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;IACtE,SAAS,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,kBAAkB,CAAC,CAAC,CAAC;IAC/C,KAAK,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE;CACS,CAAC;AAIjD;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA6B,MAAM,CAAC,MAAM,CACvE,MAAM,CAAC,IAAI,CAAC,UAAU,CAAoB,CAC3C,CAAC;AAEF;;;;GAIG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,IAAY;QACtB,KAAK,CAAC,sBAAsB,IAAI,eAAe,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACjF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,KAAa;IACxD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,qBAAqB,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,UAAU,CAAC,IAAqB,CAAC,CAAC,KAAK,CAAC,CAAC;AAClD,CAAC"}

package/dist/path-utils.d.ts

@@ -175,9 +175,11 @@ export declare function toForwardSlash(p: string): string;
  * import { safePath } from '@vibe-agent-toolkit/utils';
  *
  * // Always forward slashes, even on Windows
- * safePath.join('C:\\Users', 'docs', 'file.md')   // → 'C:/Users/docs/file.md'
- * safePath.resolve('/project', './docs')            // → '/project/docs'
- * safePath.relative('/project/docs', '/project')    // → '..'
+ * safePath.join('C:\\Users', 'docs', 'file.md')          // → 'C:/Users/docs/file.md'
+ * safePath.resolve('/project', './docs')                   // → '/project/docs'
+ * safePath.relative('/project/docs', '/project')           // → '..'
+ * safePath.joinUnderRoot('/harness', 'skill-abc')          // → '/harness/skill-abc'
+ * safePath.joinUnderRoot('/harness', '../escape')          // throws Error
  * ```
  */
 export declare const safePath: {
@@ -187,6 +189,36 @@ export declare const safePath: {
     readonly resolve: (...paths: string[]) => string;
     /** Like `path.relative()` but always returns forward slashes. */
     readonly relative: (from: string, to: string) => string;
+    /**
+     * Join path segments under a security root, throwing if the result would escape.
+     *
+     * Resolves `root + segments` and verifies the result is strictly inside `root`
+     * (or equal to it). Throws when any segment would cause the result to escape:
+     *
+     * - A `..` traversal that climbs above root
+     * - An absolute POSIX path segment (e.g. `/etc/passwd`)
+     * - A Windows drive-letter segment (e.g. `C:\Users\evil`)
+     *
+     * On success returns a forward-slash-normalized absolute path (consistent with
+     * the other `safePath` helpers).
+     *
+     * **Use this instead of `safePath.join(root, segment)` whenever `segment` may
+     * contain caller-controlled input** — this is the bug class that the original
+     * skill-test staging code was vulnerable to on Windows.
+     *
+     * @returns Forward-slash absolute path guaranteed to be inside `root`.
+     * @throws {Error} If the resolved path would escape `root`.
+     *
+     * @example
+     * ```typescript
+     * // ✅ Safe — throws if caller passes '../../../etc'
+     * const dest = safePath.joinUnderRoot(harnessRoot, stagedDirName(item.name));
+     *
+     * // ❌ Unsafe — silently escapes on Windows with absolute segment
+     * const dest = safePath.join(harnessRoot, item.name);
+     * ```
+     */
+    readonly joinUnderRoot: (root: string, ...segments: string[]) => string;
 };
 /**
  * Resolve an OS-native absolute path from an ESM module's `import.meta.url` and

package/dist/path-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../src/path-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAgB,MAAM,SAAS,CAAC;AAKlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,aAAa,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CA+BxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAezC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,GACxC,MAAM,CAiBR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAKjE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAMhE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,QAAQ;IACnB,6DAA6D;8BAC9C,MAAM,EAAE,KAAG,MAAM;IAIhC,gEAAgE;iCAC9C,MAAM,EAAE,KAAG,MAAM;IAInC,iEAAiE;8BAClD,MAAM,MAAM,MAAM,KAAG,MAAM;CAGlC,CAAC;AAEX;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAQ1F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAGhF"}
+{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../src/path-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAgB,MAAM,SAAS,CAAC;AAKlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,aAAa,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CA+BxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAezC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,GACxC,MAAM,CAiBR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAKjE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAMhE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,QAAQ;IACnB,6DAA6D;8BAC9C,MAAM,EAAE,KAAG,MAAM;IAIhC,gEAAgE;iCAC9C,MAAM,EAAE,KAAG,MAAM;IAInC,iEAAiE;8BAClD,MAAM,MAAM,MAAM,KAAG,MAAM;IAI1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;mCACiB,MAAM,eAAe,MAAM,EAAE,KAAG,MAAM;CAuClD,CAAC;AAEX;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAQ1F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAGhF"}

package/dist/path-utils.js

@@ -260,9 +260,11 @@ export function toForwardSlash(p) {
  * import { safePath } from '@vibe-agent-toolkit/utils';
  *
  * // Always forward slashes, even on Windows
- * safePath.join('C:\\Users', 'docs', 'file.md')   // → 'C:/Users/docs/file.md'
- * safePath.resolve('/project', './docs')            // → '/project/docs'
- * safePath.relative('/project/docs', '/project')    // → '..'
+ * safePath.join('C:\\Users', 'docs', 'file.md')          // → 'C:/Users/docs/file.md'
+ * safePath.resolve('/project', './docs')                   // → '/project/docs'
+ * safePath.relative('/project/docs', '/project')           // → '..'
+ * safePath.joinUnderRoot('/harness', 'skill-abc')          // → '/harness/skill-abc'
+ * safePath.joinUnderRoot('/harness', '../escape')          // throws Error
  * ```
  */
 export const safePath = {
@@ -278,6 +280,64 @@ export const safePath = {
     relative(from, to) {
         return toForwardSlash(path.relative(from, to));
     },
+    /**
+     * Join path segments under a security root, throwing if the result would escape.
+     *
+     * Resolves `root + segments` and verifies the result is strictly inside `root`
+     * (or equal to it). Throws when any segment would cause the result to escape:
+     *
+     * - A `..` traversal that climbs above root
+     * - An absolute POSIX path segment (e.g. `/etc/passwd`)
+     * - A Windows drive-letter segment (e.g. `C:\Users\evil`)
+     *
+     * On success returns a forward-slash-normalized absolute path (consistent with
+     * the other `safePath` helpers).
+     *
+     * **Use this instead of `safePath.join(root, segment)` whenever `segment` may
+     * contain caller-controlled input** — this is the bug class that the original
+     * skill-test staging code was vulnerable to on Windows.
+     *
+     * @returns Forward-slash absolute path guaranteed to be inside `root`.
+     * @throws {Error} If the resolved path would escape `root`.
+     *
+     * @example
+     * ```typescript
+     * // ✅ Safe — throws if caller passes '../../../etc'
+     * const dest = safePath.joinUnderRoot(harnessRoot, stagedDirName(item.name));
+     *
+     * // ❌ Unsafe — silently escapes on Windows with absolute segment
+     * const dest = safePath.join(harnessRoot, item.name);
+     * ```
+     */
+    joinUnderRoot(root, ...segments) {
+        // Eagerly reject any segment that is absolute (POSIX or Windows drive-letter)
+        // BEFORE resolving, so the error message can name the offending segment.
+        for (const seg of segments) {
+            if (path.isAbsolute(seg)) {
+                throw new Error(`safePath.joinUnderRoot: segment "${seg}" is absolute and escapes root "${root}".`);
+            }
+            // Windows drive-letter check for POSIX hosts (path.isAbsolute won't catch
+            // 'C:\...' on POSIX, but node's path.win32.isAbsolute does).
+            if (path.win32.isAbsolute(seg)) {
+                throw new Error(`safePath.joinUnderRoot: segment "${seg}" contains a Windows drive letter and escapes root "${root}".`);
+            }
+        }
+        const resolvedRoot = path.resolve(root);
+        const resolvedResult = segments.length > 0
+            ? path.resolve(resolvedRoot, ...segments)
+            : resolvedRoot;
+        // Containment check: normalize both to forward slashes so the comparison
+        // is platform-independent and no path.sep is needed in string operations.
+        const fwdRoot = toForwardSlash(resolvedRoot);
+        const fwdResult = toForwardSlash(resolvedResult);
+        // Result must equal root or start with root + '/' (not just startsWith(root)
+        // which would match '/rootEvil' when root is '/root').
+        const rootPrefix = fwdRoot.endsWith('/') ? fwdRoot : `${fwdRoot}/`;
+        if (fwdResult !== fwdRoot && !fwdResult.startsWith(rootPrefix)) {
+            throw new Error(`safePath.joinUnderRoot: result "${fwdResult}" escapes root "${fwdRoot}".`);
+        }
+        return fwdResult;
+    },
 };
 /**
  * Resolve an OS-native absolute path from an ESM module's `import.meta.url` and

package/dist/path-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"path-utils.js","sourceRoot":"","sources":["../src/path-utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"path-utils.js","sourceRoot":"","sources":["../src/path-utils.ts"],"names":[],"mappings":"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"}

package/dist/skill-test/auth-resolver.d.ts

@@ -0,0 +1,34 @@
+export type AuthMode = 'inherit' | 'subscription' | 'api-key' | 'auto';
+export type AuthMechanism = 'subscription' | 'api-key';
+export interface AuthStatusResult {
+    loggedIn: boolean;
+    authMethod?: string;
+    apiKeySource?: string;
+}
+export type AuthStatusProbe = (env: NodeJS.ProcessEnv) => AuthStatusResult | null;
+export interface ResolveAuthOptions {
+    mode: AuthMode;
+    requireAuth?: AuthMechanism;
+    sourceEnv: NodeJS.ProcessEnv;
+    /** Injected in tests; defaults to the real CLI probe in production. */
+    probe?: AuthStatusProbe;
+    modelVars?: string[];
+}
+export interface ResolvedAuth {
+    forwardedEnv: NodeJS.ProcessEnv;
+    effectiveMechanism: AuthMechanism;
+    authMethod?: string;
+    apiKeySource?: string;
+}
+/** A preflight auth failure — maps to exit code 2. */
+export declare class AuthPreflightError extends Error {
+    readonly exitCode: 2;
+    constructor(message: string);
+}
+/**
+ * Token-free auth probe (spec §8/§10). Runs `claude auth status --json` in the
+ * given env: returns in ~150ms, exit 0, spends NO tokens. NOT a `-p` call.
+ */
+export declare function probeAuthStatus(env: NodeJS.ProcessEnv): AuthStatusResult | null;
+export declare function resolveAuth(opts: ResolveAuthOptions): ResolvedAuth;
+//# sourceMappingURL=auth-resolver.d.ts.map

package/dist/skill-test/auth-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-resolver.d.ts","sourceRoot":"","sources":["../../src/skill-test/auth-resolver.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,GAAG,MAAM,CAAC;AACvE,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,SAAS,CAAC;AAEvD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,KAAK,gBAAgB,GAAG,IAAI,CAAC;AAElF,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC,UAAU,CAAC;IAC7B,uEAAuE;IACvE,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,kBAAkB,EAAE,aAAa,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,sDAAsD;AACtD,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,QAAQ,EAAG,CAAC,CAAU;gBACnB,OAAO,EAAE,MAAM;CAI5B;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,gBAAgB,GAAG,IAAI,CAa/E;AAgBD,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,YAAY,CA+BlE"}

package/dist/skill-test/auth-resolver.js

@@ -0,0 +1,68 @@
+import { safeExecResult } from '../safe-exec.js';
+import { buildForwardedEnv } from './env-scrub.js';
+/** A preflight auth failure — maps to exit code 2. */
+export class AuthPreflightError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = 'AuthPreflightError';
+    }
+}
+/**
+ * Token-free auth probe (spec §8/§10). Runs `claude auth status --json` in the
+ * given env: returns in ~150ms, exit 0, spends NO tokens. NOT a `-p` call.
+ */
+export function probeAuthStatus(env) {
+    const res = safeExecResult('claude', ['auth', 'status', '--json'], { env, encoding: 'utf8', stdio: 'pipe' });
+    if (!res.success)
+        return null;
+    try {
+        const parsed = JSON.parse(res.stdout.toString());
+        return {
+            loggedIn: parsed['loggedIn'] === true,
+            ...(typeof parsed['authMethod'] === 'string' ? { authMethod: parsed['authMethod'] } : {}),
+            ...(typeof parsed['apiKeySource'] === 'string' ? { apiKeySource: parsed['apiKeySource'] } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function hasInferenceKey(env) {
+    return Boolean(env['ANTHROPIC_API_KEY'] ?? env['ANTHROPIC_AUTH_TOKEN']);
+}
+/** Decide whether to scrub the inference key, given mode + a subscription-present probe. */
+function decideScrub(mode, sourceEnv, probe) {
+    if (mode === 'subscription')
+        return true;
+    if (mode === 'api-key' || mode === 'auto')
+        return false;
+    // inherit: scrub the key only if a subscription is actually logged in.
+    const scrubbed = buildForwardedEnv(sourceEnv, { scrubInferenceKey: true });
+    const status = probe(scrubbed);
+    return status?.loggedIn === true;
+}
+export function resolveAuth(opts) {
+    const probe = opts.probe ?? probeAuthStatus;
+    const baseOpts = opts.modelVars ? { modelVars: opts.modelVars } : {};
+    if (opts.mode === 'api-key' && !hasInferenceKey(opts.sourceEnv)) {
+        throw new AuthPreflightError('--auth api-key requires ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN to be set.');
+    }
+    const scrubInferenceKey = decideScrub(opts.mode, opts.sourceEnv, probe);
+    const forwardedEnv = buildForwardedEnv(opts.sourceEnv, { scrubInferenceKey, ...baseOpts });
+    const status = probe(forwardedEnv);
+    if (opts.mode === 'subscription' && status?.loggedIn !== true) {
+        throw new AuthPreflightError('--auth subscription requires a logged-in subscription (claude auth status reports not logged in).');
+    }
+    const effectiveMechanism = !scrubInferenceKey && hasInferenceKey(forwardedEnv) ? 'api-key' : 'subscription';
+    if (opts.requireAuth && opts.requireAuth !== effectiveMechanism) {
+        throw new AuthPreflightError(`--require-auth ${opts.requireAuth} but the effective mechanism is ${effectiveMechanism}. Refusing to spend tokens.`);
+    }
+    return {
+        forwardedEnv,
+        effectiveMechanism,
+        ...(status?.authMethod ? { authMethod: status.authMethod } : {}),
+        ...(status?.apiKeySource ? { apiKeySource: status.apiKeySource } : {}),
+    };
+}
+//# sourceMappingURL=auth-resolver.js.map

package/dist/skill-test/auth-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-resolver.js","sourceRoot":"","sources":["../../src/skill-test/auth-resolver.ts"],"names":[],"mappings":"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"}