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

package/dist/index.d.ts

@@ -17,4 +17,9 @@ export * from './test-helpers.js';
 export * from './zod-introspection.js';
 export * from './template.js';
 export * from './skill-targets.js';
+export { type LinkAuthConfig, type Provider, type ProviderAuth, type ProviderCheck, resolveAuthenticatedUrl, type ResolveOutcome, } from './link-auth/resolve.js';
+export type { ProviderMatch } from './link-auth/select-provider.js';
+export type { RewriteRule } from './link-auth/rewrite.js';
+export type { TokenSource } from './link-auth/resolve-token.js';
+export { expandMacro, UnknownMacroError } from './link-auth/expand-macro.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,gBAAgB,CAAC;AAG/B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,eAAe,CAAC;AAG9B,cAAc,mBAAmB,CAAC;AAGlC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,gBAAgB,CAAC;AAI/B,cAAc,oBAAoB,CAAC;AAGnC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,eAAe,CAAC;AAG9B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,gBAAgB,CAAC;AAG/B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,eAAe,CAAC;AAG9B,cAAc,mBAAmB,CAAC;AAGlC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,gBAAgB,CAAC;AAI/B,cAAc,oBAAoB,CAAC;AAGnC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,eAAe,CAAC;AAG9B,cAAc,oBAAoB,CAAC;AAInC,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,uBAAuB,EACvB,KAAK,cAAc,GACpB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/index.js

@@ -31,4 +31,8 @@ export * from './zod-introspection.js';
 export * from './template.js';
 // Skill target resolution (cross-platform flat skill install paths)
 export * from './skill-targets.js';
+// linkAuth pure engine — public API only (issue #113).
+// Internal helpers (rewrite, build-headers, etc.) stay module-private.
+export { resolveAuthenticatedUrl, } from './link-auth/resolve.js';
+export { expandMacro, UnknownMacroError } from './link-auth/expand-macro.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8DAA8D;AAC9D,cAAc,gBAAgB,CAAC;AAE/B,gCAAgC;AAChC,cAAc,iBAAiB,CAAC;AAEhC,2DAA2D;AAC3D,cAAc,sBAAsB,CAAC;AAErC,uBAAuB;AACvB,cAAc,eAAe,CAAC;AAE9B,wCAAwC;AACxC,cAAc,mBAAmB,CAAC;AAElC,sBAAsB;AACtB,cAAc,wBAAwB,CAAC;AAEvC,8CAA8C;AAC9C,cAAc,gBAAgB,CAAC;AAE/B,2DAA2D;AAC3D,iEAAiE;AACjE,cAAc,oBAAoB,CAAC;AAEnC,yDAAyD;AACzD,cAAc,kBAAkB,CAAC;AAEjC,oDAAoD;AACpD,cAAc,mBAAmB,CAAC;AAElC,4CAA4C;AAC5C,cAAc,wBAAwB,CAAC;AAEvC,2DAA2D;AAC3D,cAAc,eAAe,CAAC;AAE9B,oEAAoE;AACpE,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8DAA8D;AAC9D,cAAc,gBAAgB,CAAC;AAE/B,gCAAgC;AAChC,cAAc,iBAAiB,CAAC;AAEhC,2DAA2D;AAC3D,cAAc,sBAAsB,CAAC;AAErC,uBAAuB;AACvB,cAAc,eAAe,CAAC;AAE9B,wCAAwC;AACxC,cAAc,mBAAmB,CAAC;AAElC,sBAAsB;AACtB,cAAc,wBAAwB,CAAC;AAEvC,8CAA8C;AAC9C,cAAc,gBAAgB,CAAC;AAE/B,2DAA2D;AAC3D,iEAAiE;AACjE,cAAc,oBAAoB,CAAC;AAEnC,yDAAyD;AACzD,cAAc,kBAAkB,CAAC;AAEjC,oDAAoD;AACpD,cAAc,mBAAmB,CAAC;AAElC,4CAA4C;AAC5C,cAAc,wBAAwB,CAAC;AAEvC,2DAA2D;AAC3D,cAAc,eAAe,CAAC;AAE9B,oEAAoE;AACpE,cAAc,oBAAoB,CAAC;AAEnC,uDAAuD;AACvD,uEAAuE;AACvE,OAAO,EAKL,uBAAuB,GAExB,MAAM,wBAAwB,CAAC;AAIhC,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/link-auth/build-headers.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Render auth-header templates with rendered values, and a structural
+ * redaction helper for serialization.
+ *
+ * `buildHeaders` renders each header value template against a context that
+ * carries `${token}` plus any named captures / vars from the rewrite step.
+ * `redactHeaders` masks `Authorization` values for any caller that needs to
+ * serialize headers into logs, errors, or cache entries — the design's §8
+ * "tokens never leak" claim depends on every such site routing through this.
+ *
+ * Per design issue #113 §4 (auth.headers vocabulary) and §8 (redaction is
+ * structural; Authorization values never appear in serialized output).
+ */
+export declare const REDACTED_VALUE = "<redacted>";
+/**
+ * Render a map of header templates into a map of concrete header values.
+ *
+ * @throws {TemplateMissingVarError} if a header template references an
+ *   unknown context key
+ * @throws {TemplateSyntaxError} from a malformed template expression
+ * @throws {UnknownTransformError} from a template calling an unknown transform
+ */
+export declare function buildHeaders(templates: Record<string, string>, context: Record<string, string>): Record<string, string>;
+/**
+ * Return a copy of `headers` with sensitive values replaced by `REDACTED_VALUE`.
+ * Header-name matching is case-insensitive but exact (no prefix matching) — a
+ * header like `X-Authorization-Foo` is NOT considered sensitive.
+ *
+ * **Input must be a plain key-value object.** A `Headers` instance (Web Fetch
+ * API) or a `Map` yields `[]` from `Object.entries` and would silently no-op
+ * redaction — converting to a plain object is the caller's responsibility.
+ */
+export declare function redactHeaders(headers: Record<string, string>): Record<string, string>;
+//# sourceMappingURL=build-headers.d.ts.map

package/dist/link-auth/build-headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-headers.d.ts","sourceRoot":"","sources":["../../src/link-auth/build-headers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,eAAO,MAAM,cAAc,eAAe,CAAC;AAc3C;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMrF"}

package/dist/link-auth/build-headers.js

@@ -0,0 +1,58 @@
+/**
+ * Render auth-header templates with rendered values, and a structural
+ * redaction helper for serialization.
+ *
+ * `buildHeaders` renders each header value template against a context that
+ * carries `${token}` plus any named captures / vars from the rewrite step.
+ * `redactHeaders` masks `Authorization` values for any caller that needs to
+ * serialize headers into logs, errors, or cache entries — the design's §8
+ * "tokens never leak" claim depends on every such site routing through this.
+ *
+ * Per design issue #113 §4 (auth.headers vocabulary) and §8 (redaction is
+ * structural; Authorization values never appear in serialized output).
+ */
+import { renderTemplate } from './template.js';
+export const REDACTED_VALUE = '<redacted>';
+/**
+ * Header names whose values must be masked when serialized.
+ *
+ * v1 ships only `authorization` because that is the only secret-bearing
+ * header the current macros emit. **Omission is the security risk** — any
+ * future macro that emits a header carrying a secret (`Cookie`,
+ * `Proxy-Authorization`, `X-API-Key`, custom bearer-style headers) must add
+ * that name here, or the token will silently leak through serialization.
+ * Extending the set is not the dangerous edit; forgetting to extend it is.
+ */
+const SENSITIVE_HEADER_NAMES = new Set(['authorization']);
+/**
+ * Render a map of header templates into a map of concrete header values.
+ *
+ * @throws {TemplateMissingVarError} if a header template references an
+ *   unknown context key
+ * @throws {TemplateSyntaxError} from a malformed template expression
+ * @throws {UnknownTransformError} from a template calling an unknown transform
+ */
+export function buildHeaders(templates, context) {
+    const headers = Object.create(null);
+    for (const [name, template] of Object.entries(templates)) {
+        headers[name] = renderTemplate(template, context);
+    }
+    return headers;
+}
+/**
+ * Return a copy of `headers` with sensitive values replaced by `REDACTED_VALUE`.
+ * Header-name matching is case-insensitive but exact (no prefix matching) — a
+ * header like `X-Authorization-Foo` is NOT considered sensitive.
+ *
+ * **Input must be a plain key-value object.** A `Headers` instance (Web Fetch
+ * API) or a `Map` yields `[]` from `Object.entries` and would silently no-op
+ * redaction — converting to a plain object is the caller's responsibility.
+ */
+export function redactHeaders(headers) {
+    const redacted = Object.create(null);
+    for (const [name, value] of Object.entries(headers)) {
+        redacted[name] = SENSITIVE_HEADER_NAMES.has(name.toLowerCase()) ? REDACTED_VALUE : value;
+    }
+    return redacted;
+}
+//# sourceMappingURL=build-headers.js.map

package/dist/link-auth/build-headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-headers.js","sourceRoot":"","sources":["../../src/link-auth/build-headers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,MAAM,CAAC,MAAM,cAAc,GAAG,YAAY,CAAC;AAE3C;;;;;;;;;GASG;AACH,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC;AAE/E;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,SAAiC,EACjC,OAA+B;IAE/B,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAA2B,CAAC;IAC9D,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACzD,OAAO,CAAC,IAAI,CAAC,GAAG,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,OAA+B;IAC3D,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAA2B,CAAC;IAC/D,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACpD,QAAQ,CAAC,IAAI,CAAC,GAAG,sBAAsB,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC;IAC3F,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/link-auth/expand-macro.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Macro loader + expander.
+ *
+ * Loads the bundled `macros.yaml` once at module init and exposes
+ * `expandMacro(name, overrides?)` which deep-merges the named macro with any
+ * adopter overrides. The merge is "adopter wins": objects merge recursively,
+ * arrays and primitives are replaced wholesale (no element-wise array merge).
+ *
+ * The shipped macro file is at `link-auth/macros.yaml`, copied into the dist
+ * tree by `packages/dev-tools/src/copy-yaml-assets.ts` during build so the
+ * runtime `fs.readFileSync(new URL('./macros.yaml', import.meta.url))`
+ * resolves in both source-mode (vitest) and built-mode (dist).
+ *
+ * Per design issue #113 §5 (macros are config, not a privileged code path).
+ */
+/**
+ * Thrown when a `use: <name>` references a macro not in the shipped set.
+ * Message lists the available macros so a typo surfaces clearly.
+ */
+export declare class UnknownMacroError extends Error {
+    constructor(name: string, available: readonly string[]);
+}
+/**
+ * Look up a macro by name and deep-merge optional adopter overrides on top.
+ *
+ * Merge semantics:
+ *   - Plain objects merge recursively (sibling keys preserved).
+ *   - Arrays are replaced wholesale (override's array wins; no concat).
+ *   - Primitives are replaced.
+ *   - `undefined` in an override is treated as "not provided" (base wins).
+ *
+ * The returned object and all nested plain objects use null prototypes so
+ * `__proto__` / `constructor` keys can never poison consumers.
+ *
+ * @throws {UnknownMacroError} if `name` is not in the shipped macro set
+ */
+export declare function expandMacro(name: string, overrides?: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=expand-macro.d.ts.map

package/dist/link-auth/expand-macro.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expand-macro.d.ts","sourceRoot":"","sources":["../../src/link-auth/expand-macro.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAwCH;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE;CAIvD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYzB"}

package/dist/link-auth/expand-macro.js

@@ -0,0 +1,131 @@
+/**
+ * Macro loader + expander.
+ *
+ * Loads the bundled `macros.yaml` once at module init and exposes
+ * `expandMacro(name, overrides?)` which deep-merges the named macro with any
+ * adopter overrides. The merge is "adopter wins": objects merge recursively,
+ * arrays and primitives are replaced wholesale (no element-wise array merge).
+ *
+ * The shipped macro file is at `link-auth/macros.yaml`, copied into the dist
+ * tree by `packages/dev-tools/src/copy-yaml-assets.ts` during build so the
+ * runtime `fs.readFileSync(new URL('./macros.yaml', import.meta.url))`
+ * resolves in both source-mode (vitest) and built-mode (dist).
+ *
+ * Per design issue #113 §5 (macros are config, not a privileged code path).
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+const macrosPath = fileURLToPath(new URL('./macros.yaml', import.meta.url));
+let macrosCache;
+/**
+ * Load macros lazily on first use rather than at module init.
+ *
+ * Why lazy: vitest tests elsewhere in the repo mock `node:fs` (replacing
+ * `readFileSync` with `vi.fn()` that returns `undefined`). If we eagerly read
+ * at module load, any unrelated test that imports `@vibe-agent-toolkit/utils`
+ * and mocks fs crashes inside `parseYaml(undefined)` — module-init code runs
+ * unconditionally, before the mock-setup intent reaches our file.
+ *
+ * Lazy load makes module import side-effect-free; only callers of
+ * `expandMacro` pay the fs cost.
+ */
+function getMacros() {
+    if (macrosCache !== undefined)
+        return macrosCache;
+    // Path is derived from `import.meta.url`, not user input — points at the
+    // shipped macros.yaml asset next to this module in both src and dist trees.
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    const macrosFileContent = readFileSync(macrosPath, 'utf8');
+    const parsed = parseYaml(macrosFileContent);
+    if (!isPlainObject(parsed)) {
+        throw new Error('macros.yaml: expected top-level object mapping macro name → provider config.');
+    }
+    macrosCache = freezeMacros(parsed);
+    return macrosCache;
+}
+/**
+ * Thrown when a `use: <name>` references a macro not in the shipped set.
+ * Message lists the available macros so a typo surfaces clearly.
+ */
+export class UnknownMacroError extends Error {
+    constructor(name, available) {
+        super(`Unknown macro "${name}". Available: ${available.join(', ')}.`);
+        this.name = 'UnknownMacroError';
+    }
+}
+/**
+ * Look up a macro by name and deep-merge optional adopter overrides on top.
+ *
+ * Merge semantics:
+ *   - Plain objects merge recursively (sibling keys preserved).
+ *   - Arrays are replaced wholesale (override's array wins; no concat).
+ *   - Primitives are replaced.
+ *   - `undefined` in an override is treated as "not provided" (base wins).
+ *
+ * The returned object and all nested plain objects use null prototypes so
+ * `__proto__` / `constructor` keys can never poison consumers.
+ *
+ * @throws {UnknownMacroError} if `name` is not in the shipped macro set
+ */
+export function expandMacro(name, overrides) {
+    const macros = getMacros();
+    const base = macros[name];
+    if (base === undefined) {
+        throw new UnknownMacroError(name, Object.keys(macros));
+    }
+    if (overrides === undefined) {
+        return cloneWithNullProto(base);
+    }
+    const merged = deepMerge(base, overrides);
+    // Top-level result is guaranteed object here because base is.
+    return merged;
+}
+function deepMerge(base, override) {
+    if (override === undefined)
+        return base;
+    if (!isPlainObject(base) || !isPlainObject(override))
+        return cloneValue(override);
+    const result = Object.create(null);
+    for (const [key, value] of Object.entries(base)) {
+        result[key] = cloneValue(value);
+    }
+    for (const [key, value] of Object.entries(override)) {
+        const existing = Object.hasOwn(result, key) ? result[key] : undefined;
+        if (isPlainObject(existing) && isPlainObject(value)) {
+            result[key] = deepMerge(existing, value);
+        }
+        else {
+            result[key] = cloneValue(value);
+        }
+    }
+    return result;
+}
+function cloneValue(value) {
+    if (Array.isArray(value))
+        return value.map(cloneValue);
+    if (isPlainObject(value))
+        return cloneWithNullProto(value);
+    return value;
+}
+function cloneWithNullProto(obj) {
+    const cloned = Object.create(null);
+    for (const [key, value] of Object.entries(obj)) {
+        cloned[key] = cloneValue(value);
+    }
+    return cloned;
+}
+function freezeMacros(parsed) {
+    const frozen = Object.create(null);
+    for (const [name, value] of Object.entries(parsed)) {
+        if (!isPlainObject(value)) {
+            throw new Error(`macros.yaml: macro "${name}" is not an object.`);
+        }
+        frozen[name] = cloneWithNullProto(value);
+    }
+    return frozen;
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+//# sourceMappingURL=expand-macro.js.map

package/dist/link-auth/expand-macro.js.map

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

package/dist/link-auth/macros.yaml

@@ -0,0 +1,50 @@
+# linkAuth provider macros — shipped defaults referenced by `use: <name>` in
+# adopter `vibe-agent-toolkit.config.yaml` files.
+#
+# Each entry is a full provider config in the §4 vocabulary (match, rewrite,
+# auth, token, check). Adopters reference a macro by name and may deep-merge
+# overrides on top — see design issue #113 §5.
+#
+# Adding a new host is intended to be a config-only PR: append an entry here
+# and add unit tests. Only `vocabulary` changes (e.g. a new transform) require
+# engine code.
+
+github:
+  match:
+    host: github.com
+  rewrite:
+    - when: '^https://github\.com/(?<owner>[^/]+)/(?<repo>[^/]+)/(?:blob|tree)/(?<ref>[^/]+)/(?<path>.+)$'
+      to: 'https://api.github.com/repos/${owner}/${repo}/contents/${path}?ref=${ref}'
+  auth:
+    headers:
+      Authorization: 'Bearer ${token}'
+      Accept: application/vnd.github+json
+  token:
+    - command: gh auth token
+    - env: GITHUB_TOKEN
+  check:
+    method: GET
+    aliveStatus: [200]
+    notFoundMeaning: ambiguous
+
+sharepoint:
+  match:
+    host: '*.sharepoint.com'
+    excludeHost:
+      - '*-my.sharepoint.com'
+  rewrite:
+    - when: '^(?<u>https://.+)$'
+      vars:
+        shareId: 'u!${base64url(u)}'
+      to: 'https://graph.microsoft.com/v1.0/shares/${shareId}/driveItem'
+  auth:
+    headers:
+      Authorization: 'Bearer ${token}'
+  # SharePoint has no zero-config token source (design §5.1 note): a SharePoint-
+  # scoped token requires an Entra app registration; the stock `az` token does
+  # not work. Adopter must supply their own token command.
+  token: []
+  check:
+    method: GET
+    aliveStatus: [200]
+    notFoundMeaning: dead

package/dist/link-auth/resolve-token.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Token resolution — ordered, first-non-empty-wins.
+ *
+ * Iterates a provider's `token` source list and returns the first source that
+ * yields a non-empty value. Two source shapes:
+ *   - `{ env: "NAME" }`                — read from process env (no trimming)
+ *   - `{ command: argv }`              — run a command, return trimmed stdout
+ *   - `{ command: "gh auth token" }`   — convenience: whitespace-tokenized into
+ *     argv. **Not** passed through a shell — operators (`|`, `&&`, `$(...)`)
+ *     become literal argv elements, per the design's §6.1 sharp-edge note.
+ *
+ * Returns `undefined` if every source fails or yields an empty/whitespace
+ * value — the caller's `resolveAuthenticatedUrl` translates that to the
+ * `unverified` outcome (LINK_AUTH_UNVERIFIED in slice 2).
+ *
+ * Per design issue #113 §4 (token vocabulary) and §6.1 (command execution,
+ * `safeExecSync`-backed, `shell: false`).
+ */
+export type TokenSource = {
+    readonly env: string;
+} | {
+    readonly command: string | readonly string[];
+};
+export interface TokenResolutionDeps {
+    /**
+     * Environment lookup map. Defaults to `process.env`. Injectable for tests so
+     * unit tests don't depend on ambient environment state.
+     */
+    readonly env: Record<string, string | undefined>;
+    /**
+     * Command runner. Defaults to `safeExecResult`-wrapped invocation. Injectable
+     * for tests. Receives argv; returns `success` + `stdout`. Should NOT throw
+     * for normal exec failures (return `success: false` instead). Throws are
+     * propagated by `resolveToken` — they indicate operator-level bugs.
+     */
+    readonly runCommand: (argv: readonly string[]) => {
+        success: boolean;
+        stdout: string;
+    };
+}
+/**
+ * Resolve a token from an ordered list of sources.
+ *
+ * @returns the first non-empty value, or `undefined` if every source failed.
+ * @throws whatever the injected `runCommand` throws (operator-level bug; not
+ *   swallowed). Standard `safeExecResult` does not throw under normal use.
+ */
+export declare function resolveToken(sources: readonly TokenSource[], deps?: Partial<TokenResolutionDeps>): string | undefined;
+//# sourceMappingURL=resolve-token.d.ts.map

package/dist/link-auth/resolve-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-token.d.ts","sourceRoot":"","sources":["../../src/link-auth/resolve-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,MAAM,MAAM,WAAW,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAEtG,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAEjD;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACxF;AAWD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,IAAI,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAClC,MAAM,GAAG,SAAS,CASpB"}

package/dist/link-auth/resolve-token.js

@@ -0,0 +1,72 @@
+/**
+ * Token resolution — ordered, first-non-empty-wins.
+ *
+ * Iterates a provider's `token` source list and returns the first source that
+ * yields a non-empty value. Two source shapes:
+ *   - `{ env: "NAME" }`                — read from process env (no trimming)
+ *   - `{ command: argv }`              — run a command, return trimmed stdout
+ *   - `{ command: "gh auth token" }`   — convenience: whitespace-tokenized into
+ *     argv. **Not** passed through a shell — operators (`|`, `&&`, `$(...)`)
+ *     become literal argv elements, per the design's §6.1 sharp-edge note.
+ *
+ * Returns `undefined` if every source fails or yields an empty/whitespace
+ * value — the caller's `resolveAuthenticatedUrl` translates that to the
+ * `unverified` outcome (LINK_AUTH_UNVERIFIED in slice 2).
+ *
+ * Per design issue #113 §4 (token vocabulary) and §6.1 (command execution,
+ * `safeExecSync`-backed, `shell: false`).
+ */
+import { safeExecResult } from '../safe-exec.js';
+const DEFAULT_RUN_COMMAND = (argv) => {
+    if (argv.length === 0)
+        return { success: false, stdout: '' };
+    const [bin, ...args] = argv;
+    if (bin === undefined)
+        return { success: false, stdout: '' };
+    const result = safeExecResult(bin, [...args], { encoding: 'utf8' });
+    const stdout = typeof result.stdout === 'string' ? result.stdout : result.stdout.toString('utf8');
+    return { success: result.success, stdout };
+};
+/**
+ * Resolve a token from an ordered list of sources.
+ *
+ * @returns the first non-empty value, or `undefined` if every source failed.
+ * @throws whatever the injected `runCommand` throws (operator-level bug; not
+ *   swallowed). Standard `safeExecResult` does not throw under normal use.
+ */
+export function resolveToken(sources, deps) {
+    const env = deps?.env ?? process.env;
+    const runCommand = deps?.runCommand ?? DEFAULT_RUN_COMMAND;
+    for (const source of sources) {
+        const value = tryResolveSource(source, env, runCommand);
+        if (value !== undefined && value.length > 0)
+            return value;
+    }
+    return undefined;
+}
+function tryResolveSource(source, env, runCommand) {
+    if ('env' in source) {
+        // Object.hasOwn defends against env names like "__proto__" returning
+        // Object.prototype via the prototype chain.
+        if (!Object.hasOwn(env, source.env))
+            return undefined;
+        return env[source.env];
+    }
+    const argv = toArgv(source.command);
+    if (argv.length === 0)
+        return undefined;
+    const result = runCommand(argv);
+    if (!result.success)
+        return undefined;
+    const trimmed = result.stdout.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+}
+function toArgv(command) {
+    if (Array.isArray(command))
+        return command;
+    // Whitespace-tokenize the string form. Empty segments (from multiple spaces)
+    // are filtered. Shell operators ('|', '&&', etc.) become literal argv, NOT
+    // pipes — see design §6.1.
+    return command.split(/\s+/).filter((s) => s.length > 0);
+}
+//# sourceMappingURL=resolve-token.js.map

package/dist/link-auth/resolve-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-token.js","sourceRoot":"","sources":["../../src/link-auth/resolve-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAoBjD,MAAM,mBAAmB,GAAsC,CAAC,IAAI,EAAE,EAAE;IACtE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAC7D,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IAC5B,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAC7D,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IACpE,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAClG,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;AAC7C,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAC1B,OAA+B,EAC/B,IAAmC;IAEnC,MAAM,GAAG,GAAG,IAAI,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACrC,MAAM,UAAU,GAAG,IAAI,EAAE,UAAU,IAAI,mBAAmB,CAAC;IAE3D,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;QACxD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;IAC5D,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,gBAAgB,CACvB,MAAmB,EACnB,GAAuC,EACvC,UAA6C;IAE7C,IAAI,KAAK,IAAI,MAAM,EAAE,CAAC;QACpB,qEAAqE;QACrE,4CAA4C;QAC5C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC;YAAE,OAAO,SAAS,CAAC;QACtD,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAExC,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IACtC,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACrC,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;AACpD,CAAC;AAED,SAAS,MAAM,CAAC,OAAmC;IACjD,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IAC3C,6EAA6E;IAC7E,2EAA2E;IAC3E,2BAA2B;IAC3B,OAAQ,OAAkB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACtE,CAAC"}

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

@@ -0,0 +1,58 @@
+/**
+ * Public API for the linkAuth pure engine.
+ *
+ * `resolveAuthenticatedUrl(url, config)` is the single entry point per design
+ * §6: select the first provider whose `match.host` claims the URL, run its
+ * rewrite pipeline, resolve a token, build the auth headers, and return
+ * everything the caller needs to issue an authenticated fetch.
+ *
+ * Three outcomes:
+ *   - `{ fetchUrl, headers }`              — ready to fetch (provider claimed,
+ *                                            rewrite matched, token resolved)
+ *   - `{ outcome: 'unsupported' }`         — no provider claims the host, OR
+ *                                            host matched but no rewrite did
+ *                                            (per §4: "the provider does not
+ *                                            claim the URL for rewriting")
+ *   - `{ outcome: 'unverified', reason }`  — claimed and rewrote, but no token
+ *                                            source resolved a non-empty value
+ *
+ * Per design issue #113 §6.
+ */
+import { type TokenResolutionDeps, type TokenSource } from './resolve-token.js';
+import { type RewriteRule } from './rewrite.js';
+import { type ProviderMatch } from './select-provider.js';
+export interface ProviderAuth {
+    readonly headers: Record<string, string>;
+}
+export interface ProviderCheck {
+    readonly method: 'GET' | 'HEAD';
+    readonly aliveStatus: readonly number[];
+    readonly notFoundMeaning: 'ambiguous' | 'dead';
+}
+export interface Provider {
+    readonly match: ProviderMatch;
+    readonly rewrite: readonly RewriteRule[];
+    readonly auth: ProviderAuth;
+    readonly token: readonly TokenSource[];
+    readonly check: ProviderCheck;
+}
+export interface LinkAuthConfig {
+    readonly providers: readonly Provider[];
+}
+export type ResolveOutcome = {
+    readonly fetchUrl: string;
+    readonly headers: Record<string, string>;
+} | {
+    readonly outcome: 'unsupported';
+} | {
+    readonly outcome: 'unverified';
+    readonly reason: string;
+};
+/**
+ * Resolve an authenticated fetch plan for `url` against the configured providers.
+ *
+ * @param deps - Optional dependency injection for token resolution (`env` map
+ *   + `runCommand`). Production callers omit this; tests supply mocks.
+ */
+export declare function resolveAuthenticatedUrl(url: string, config: LinkAuthConfig, deps?: Partial<TokenResolutionDeps>): ResolveOutcome;
+//# sourceMappingURL=resolve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/link-auth/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,WAAW,EACjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,WAAW,EAAc,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,sBAAsB,CAAC;AAE1E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,WAAW,GAAG,MAAM,CAAC;CAChD;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;CAGzC;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACvE;IAAE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;CAAE,GACnC;IAAE,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,cAAc,EACtB,IAAI,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAClC,cAAc,CAyBhB"}

package/dist/link-auth/resolve.js

@@ -0,0 +1,55 @@
+/**
+ * Public API for the linkAuth pure engine.
+ *
+ * `resolveAuthenticatedUrl(url, config)` is the single entry point per design
+ * §6: select the first provider whose `match.host` claims the URL, run its
+ * rewrite pipeline, resolve a token, build the auth headers, and return
+ * everything the caller needs to issue an authenticated fetch.
+ *
+ * Three outcomes:
+ *   - `{ fetchUrl, headers }`              — ready to fetch (provider claimed,
+ *                                            rewrite matched, token resolved)
+ *   - `{ outcome: 'unsupported' }`         — no provider claims the host, OR
+ *                                            host matched but no rewrite did
+ *                                            (per §4: "the provider does not
+ *                                            claim the URL for rewriting")
+ *   - `{ outcome: 'unverified', reason }`  — claimed and rewrote, but no token
+ *                                            source resolved a non-empty value
+ *
+ * Per design issue #113 §6.
+ */
+import { buildHeaders } from './build-headers.js';
+import { resolveToken, } from './resolve-token.js';
+import { rewriteUrl } from './rewrite.js';
+import { selectProvider } from './select-provider.js';
+/**
+ * Resolve an authenticated fetch plan for `url` against the configured providers.
+ *
+ * @param deps - Optional dependency injection for token resolution (`env` map
+ *   + `runCommand`). Production callers omit this; tests supply mocks.
+ */
+export function resolveAuthenticatedUrl(url, config, deps) {
+    const provider = selectProvider(url, config.providers);
+    if (provider === undefined)
+        return { outcome: 'unsupported' };
+    const rewrite = rewriteUrl(url, provider.rewrite);
+    if (!rewrite.matched)
+        return { outcome: 'unsupported' };
+    const token = resolveToken(provider.token, deps);
+    // eslint-disable-next-line security/detect-possible-timing-attacks -- compare to undefined sentinel, not secret content
+    if (token === undefined) {
+        return {
+            outcome: 'unverified',
+            reason: 'No token source resolved a non-empty value — configure `token` or log in.',
+        };
+    }
+    // Headers see captures + vars + the resolved token. The resolved token wins
+    // over any regex capture named "token" (later in Object.assign wins), so
+    // URL-derived data never leaks into Authorization values.
+    const headerContext = Object.create(null);
+    Object.assign(headerContext, rewrite.context);
+    headerContext['token'] = token;
+    const headers = buildHeaders(provider.auth.headers, headerContext);
+    return { fetchUrl: rewrite.rewrittenUrl, headers };
+}
+//# sourceMappingURL=resolve.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/link-auth/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EACL,YAAY,GAGb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAoB,UAAU,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAsB,cAAc,EAAE,MAAM,sBAAsB,CAAC;AA+B1E;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,GAAW,EACX,MAAsB,EACtB,IAAmC;IAEnC,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;IACvD,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC;IAE9D,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IAClD,IAAI,CAAC,OAAO,CAAC,OAAO;QAAE,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC;IAExD,MAAM,KAAK,GAAG,YAAY,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACjD,wHAAwH;IACxH,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO;YACL,OAAO,EAAE,YAAY;YACrB,MAAM,EAAE,2EAA2E;SACpF,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,yEAAyE;IACzE,0DAA0D;IAC1D,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAA2B,CAAC;IACpE,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,aAAa,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC;IAE/B,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IACnE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,YAAY,EAAE,OAAO,EAAE,CAAC;AACrD,CAAC"}

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

@@ -0,0 +1,52 @@
+/**
+ * Rewrite pipeline: ordered when → vars → to.
+ *
+ * Each provider declares one or more rewrite rules. For an input URL the
+ * pipeline strips `?query` and `#fragment`, finds the first rule whose
+ * `when` regex matches, computes `vars` (templates over captures), and
+ * renders the `to` template against captures + vars merged. The merged
+ * context flows out so downstream header templates can interpolate the
+ * same variables.
+ *
+ * Per design issue #113 §4 (vocabulary) and §5.2 (fragment/query
+ * stripping must precede a greedy `(?<path>.+)` capture).
+ */
+export interface RewriteRule {
+    readonly when: string;
+    readonly vars?: Record<string, string>;
+    readonly to: string;
+}
+export type RewriteOutcome = {
+    readonly matched: true;
+    readonly rewrittenUrl: string;
+    readonly context: Record<string, string>;
+} | {
+    readonly matched: false;
+};
+/**
+ * Thrown when a rule's `when` field is not a compilable regex.
+ */
+export declare class InvalidRewriteRuleError extends Error {
+    constructor(pattern: string, cause: unknown);
+}
+/**
+ * Thrown when a `vars` key collides with a named capture in `when`.
+ * Adopter must rename one — vars cannot shadow captures (the design's
+ * intent is captures + vars in a single namespace).
+ */
+export declare class VarCaptureCollisionError extends Error {
+    constructor(name: string);
+}
+/**
+ * Apply an ordered list of rewrite rules to a URL.
+ *
+ * @returns `{ matched: true, rewrittenUrl, context }` for the first matching
+ *   rule, or `{ matched: false }` if no rule claims the URL.
+ * @throws {InvalidRewriteRuleError} if a `when` field does not compile
+ * @throws {VarCaptureCollisionError} if a vars name shadows a capture name
+ * @throws {TemplateMissingVarError} from a template referencing an unknown name
+ * @throws {TemplateSyntaxError} from a malformed template expression
+ * @throws {UnknownTransformError} from a template calling an unknown transform
+ */
+export declare function rewriteUrl(url: string, rules: readonly RewriteRule[]): RewriteOutcome;
+//# sourceMappingURL=rewrite.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rewrite.d.ts","sourceRoot":"","sources":["../../src/link-auth/rewrite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,cAAc,GACtB;IACE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C,GACD;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAA;CAAE,CAAC;AAEhC;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAK5C;AAED;;;;GAIG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,IAAI,EAAE,MAAM;CAMzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,cAAc,CAerF"}

package/dist/link-auth/rewrite.js

@@ -0,0 +1,102 @@
+/**
+ * Rewrite pipeline: ordered when → vars → to.
+ *
+ * Each provider declares one or more rewrite rules. For an input URL the
+ * pipeline strips `?query` and `#fragment`, finds the first rule whose
+ * `when` regex matches, computes `vars` (templates over captures), and
+ * renders the `to` template against captures + vars merged. The merged
+ * context flows out so downstream header templates can interpolate the
+ * same variables.
+ *
+ * Per design issue #113 §4 (vocabulary) and §5.2 (fragment/query
+ * stripping must precede a greedy `(?<path>.+)` capture).
+ */
+import { renderTemplate } from './template.js';
+/**
+ * Thrown when a rule's `when` field is not a compilable regex.
+ */
+export class InvalidRewriteRuleError extends Error {
+    constructor(pattern, cause) {
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        super(`Invalid rewrite rule "when" regex: ${pattern}. ${reason}`);
+        this.name = 'InvalidRewriteRuleError';
+    }
+}
+/**
+ * Thrown when a `vars` key collides with a named capture in `when`.
+ * Adopter must rename one — vars cannot shadow captures (the design's
+ * intent is captures + vars in a single namespace).
+ */
+export class VarCaptureCollisionError extends Error {
+    constructor(name) {
+        super(`Rewrite var "${name}" collides with a regex capture of the same name. Rename one.`);
+        this.name = 'VarCaptureCollisionError';
+    }
+}
+/**
+ * Apply an ordered list of rewrite rules to a URL.
+ *
+ * @returns `{ matched: true, rewrittenUrl, context }` for the first matching
+ *   rule, or `{ matched: false }` if no rule claims the URL.
+ * @throws {InvalidRewriteRuleError} if a `when` field does not compile
+ * @throws {VarCaptureCollisionError} if a vars name shadows a capture name
+ * @throws {TemplateMissingVarError} from a template referencing an unknown name
+ * @throws {TemplateSyntaxError} from a malformed template expression
+ * @throws {UnknownTransformError} from a template calling an unknown transform
+ */
+export function rewriteUrl(url, rules) {
+    const stripped = stripFragmentAndQuery(url);
+    for (const rule of rules) {
+        const regex = compileWhen(rule.when);
+        const match = regex.exec(stripped);
+        if (match === null)
+            continue;
+        const captures = collectCaptures(match);
+        const context = computeContext(captures, rule.vars);
+        const rewrittenUrl = renderTemplate(rule.to, context);
+        return { matched: true, rewrittenUrl, context };
+    }
+    return { matched: false };
+}
+function stripFragmentAndQuery(url) {
+    const idx = url.search(/[?#]/);
+    return idx === -1 ? url : url.slice(0, idx);
+}
+function compileWhen(pattern) {
+    try {
+        // Rule patterns originate in trusted config (see design §8); runtime
+        // compilation is intentional, not user-input regex injection.
+        // eslint-disable-next-line security/detect-non-literal-regexp
+        return new RegExp(pattern);
+    }
+    catch (e) {
+        throw new InvalidRewriteRuleError(pattern, e);
+    }
+}
+function collectCaptures(match) {
+    const captures = Object.create(null);
+    // The lib typedef for RegExpMatchArray.groups says values are `string`, but
+    // optional named groups that did not match show up at runtime as `undefined`.
+    // Cast to reflect runtime reality so the filter below is type-meaningful.
+    const groups = (match.groups ?? {});
+    for (const [key, value] of Object.entries(groups)) {
+        if (value !== undefined) {
+            captures[key] = value;
+        }
+    }
+    return captures;
+}
+function computeContext(captures, vars) {
+    const context = Object.create(null);
+    Object.assign(context, captures);
+    if (vars === undefined)
+        return context;
+    for (const [name, template] of Object.entries(vars)) {
+        if (Object.hasOwn(captures, name)) {
+            throw new VarCaptureCollisionError(name);
+        }
+        context[name] = renderTemplate(template, captures);
+    }
+    return context;
+}
+//# sourceMappingURL=rewrite.js.map

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

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

package/dist/link-auth/select-provider.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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).
+ */
+export interface ProviderMatch {
+    readonly host: string;
+    readonly excludeHost?: readonly string[];
+}
+/**
+ * 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 declare function selectProvider<P extends {
+    readonly match: ProviderMatch;
+}>(url: string, providers: readonly P[]): P | undefined;
+//# sourceMappingURL=select-provider.d.ts.map

package/dist/link-auth/select-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-provider.d.ts","sourceRoot":"","sources":["../../src/link-auth/select-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;CAAE,EACxE,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,SAAS,CAAC,EAAE,GACtB,CAAC,GAAG,SAAS,CAUf"}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/utils",
-  "version": "0.1.39-rc.1",
+  "version": "0.1.39-rc.2",
   "type": "module",
   "description": "Core utility functions with no external dependencies",
   "keywords": [
@@ -23,7 +23,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsx ../dev-tools/src/copy-yaml-assets.ts",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
@@ -33,7 +33,8 @@
     "handlebars": "^4.7.8",
     "ignore": "^7.0.5",
     "picomatch": "^4.0.3",
-    "which": "^5.0.0"
+    "which": "^5.0.0",
+    "yaml": "^2.6.1"
   },
   "peerDependencies": {
     "zod": "^3.25.0 || ^4.0.0"