@red-hat-developer-hub/backstage-plugin-ai-skills-common 0.0.0-stage → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# @red-hat-developer-hub/backstage-plugin-ai-skills-common
+
+## 0.3.0
+
+### Minor Changes
+
+- 910c3a6: Discover all active tags in public Quay repositories when `quayDiscovery.tag` is
+  omitted or blank. Set `tag: latest` explicitly to retain the previous default;
+  other supplied tags remain exact filters. Bound repository and tag pagination
+  together, and preserve distinct tagged references even when they share a digest.
+  Update shared contract fixtures and documentation for a separate catalog identity
+  per valid OCI skill-image tag.
+
+  OCI record producers adopting this contract must construct keys as
+  `<registry>/<repository>:<tag>` instead of `<registry>/<repository>`, preserving
+  the exact tag case. Consumers with persisted repository-only identities must
+  plan for replacement catalog identities and update references when adopting
+  tagged keys. The shared hashing algorithm and validators are unchanged: the same
+  identity tuple still yields the same catalog name. Upgrading the common library
+  alone does not rewrite caller-supplied keys or migrate existing entities.
+
+## 0.2.0
+
+### Minor Changes
+
+- d69098f: Add stable identity, tag normalization, SemVer fallback, and OCI/npx reference helpers per design D5 (OpenSpec task 1.3)
+- dc2f19a: Add ai-skills-common shared library with v1 SkillRecord and SkillSnapshot contract, runtime validators, deterministic bounded snapshot construction, REST contract documentation, and reusable OCI/npx contract fixtures

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# ai-skills-common
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared v1 skill record and snapshot contract for RHDH skill connectors
+and the common catalog provider.
+
+This library owns schemas, validation, and pure helpers. It performs
+no network, scheduler, database, or Catalog operations.
+
+## Overview
+
+The `ai-skills-common` package defines the versioned normalized REST contract
+(`SkillRecord`, `SkillSnapshot`) that OCI and npx skill connectors expose
+at `GET /skills/:sourceId`. The common catalog provider validates and
+consumes these snapshots to produce `AiResource` entities.
+
+## Types
+
+| Type             | Description                                                       |
+| ---------------- | ----------------------------------------------------------------- |
+| `SkillRecord`    | Base normalized v1 skill record with required and optional fields |
+| `OciSkillRecord` | OCI-source record with optional `extensions.oci` container        |
+| `NpxSkillRecord` | npx-source record with optional `extensions.npx` container        |
+| `SkillSnapshot`  | Versioned snapshot containing records, status, and metadata       |
+| `SnapshotSource` | Source identity (`id` and `type`)                                 |
+| `SnapshotStatus` | `'loading' \| 'ready' \| 'partial' \| 'failed'`                   |
+
+OCI discovery records use `<registry>/<repository>:<tag>` as their stable key;
+the registry host is lowercase and the tag retains its exact case. Two tags may
+share the same manifest digest and `sourceUri` while retaining distinct keys and
+catalog identities. A tag moving to different content keeps the same identity.
+The connector constructs these keys; the shared helpers consume them as opaque
+strings and continue to reject duplicate snapshot keys. Digest-addressed OCI
+reference construction and declared-version mapping are unchanged.
+
+## Constants
+
+| Constant                   | Value             | Description                                      |
+| -------------------------- | ----------------- | ------------------------------------------------ |
+| `MAX_SNAPSHOT_RECORDS`     | `1_000`           | Maximum number of records in a single snapshot   |
+| `MAX_SNAPSHOT_BYTES`       | `5 * 1024 * 1024` | Maximum serialized snapshot size (5 MiB)         |
+| `MAX_RESPONSE_BYTES`       | `5 * 1024 * 1024` | Maximum response read size for consumers (5 MiB) |
+| `SUPPORTED_SCHEMA_VERSION` | `'1'`             | Supported schema version                         |
+
+## Validation
+
+- `validateSnapshot(snapshot)` — validates a complete v1 snapshot
+  including schema version, source identity, status invariants,
+  record fields, source-discriminated extensions, unique keys,
+  disjoint failed keys, and count bounds.
+- `validateSnapshotSize(snapshot)` — validates serialized byte size
+  against the 5 MiB limit.
+- `isValidDigest(digest)` — checks `sha256:<64 lowercase hex>` format.
+- `isValidUtcTimestamp(value)` — checks for valid ISO 8601 UTC
+  timestamps (strings ending in `Z` or `+00:00`).
+
+## Snapshot construction
+
+- `boundSnapshot(options)` — creates a bounded v1 snapshot with
+  deterministic stable-key ordering and longest-prefix selection
+  within count (1,000) and byte-size (5 MiB) limits.
+- `sortRecordsByKey(records)` — sorts skill records by stable `key`
+  in ascending Unicode code-point order.
+- `createLoadingSnapshot(source)` — creates a loading snapshot for
+  initial state.
+- `createFailedSnapshot(source, observedAt)` — creates a failed
+  snapshot.
+
+## REST contract
+
+Each connector exposes `GET /skills/:sourceId` relative to its
+Backstage plugin base URL. The endpoint uses Backstage's default
+backend service-to-service authentication. Responses contain a single
+bounded `SkillSnapshot` v1 JSON body.
+
+| Status | Meaning                      |
+| ------ | ---------------------------- |
+| 200    | Returns a `SkillSnapshot` v1 |
+| 404    | Unknown `sourceId`           |
+
+## Catalog helpers
+
+Pure identity, tag, version, and source-reference helpers for catalog
+entity mapping (design D5). These helpers have no network, database, or
+Catalog side effects.
+
+### Types
+
+| Type                  | Description                                                          |
+| --------------------- | -------------------------------------------------------------------- |
+| `IdentityTuple`       | Identity tuple (`type`, `id`, `key`) for deterministic entity naming |
+| `NormalizeTagsResult` | Result of tag normalization: valid tags and diagnostics              |
+| `OciRef`              | Parsed OCI skill reference (registry, repository, digest, URI)       |
+| `NpxRef`              | Parsed npx skill reference (sourceUri, digest, ref)                  |
+
+### Functions
+
+- `computeCatalogName(tuple)` — computes the deterministic catalog entity
+  name from an identity tuple via SHA-256 of the compact JSON encoding
+  `[type, id, key]`, prefixed with `skill-` (first 56 hex digits).
+- `normalizeTags(tags)` — trims, lowercases, deduplicates, and validates
+  tags against an extended catalog tag pattern (per design D3/D5) that
+  allows colons, plus signs, and hash characters beyond the standard
+  Backstage tag validator. Returns valid tags and diagnostics for dropped
+  entries.
+- `resolveVersion(declaredVersion, digest)` — strips at most one leading
+  `v`, validates as SemVer, and falls back to `0.0.0+<first 12 hex digits
+of digest>` when no valid SemVer is present.
+- `buildOciRef(registry, repository, digest)` — constructs a
+  digest-addressed OCI URI (`oci://<registry>/<repository>@<digest>`).
+- `parseOciRef(uri, recordDigest?)` — parses an OCI URI and optionally
+  validates digest agreement with a record digest.
+- `buildNpxRef(sourceUri, digest)` — constructs an npx reference
+  (`<sourceUri>#<digest>`) from an HTTPS URL, rejecting credentials,
+  fragments, and sensitive query parameters.
+- `parseNpxRef(ref)` — parses an npx reference, validating the URL and
+  digest.
+
+## Fixtures
+
+The package exports valid and invalid OCI/npx fixtures for connector
+and provider contract tests. Import them from the package root.
+
+## Installation
+
+```bash
+yarn add @red-hat-developer-hub/backstage-plugin-ai-skills-common
+```

package/dist/catalog-helpers.cjs.js

@@ -0,0 +1,198 @@
+'use strict';
+
+var crypto = require('crypto');
+var validation = require('./validation.cjs.js');
+
+function computeCatalogName(tuple) {
+  const payload = JSON.stringify([tuple.type, tuple.id, tuple.key]);
+  const hash = crypto.createHash("sha256").update(payload, "utf8").digest("hex");
+  return `skill-${hash.substring(0, 56)}`;
+}
+const CATALOG_TAG_RE = /^[a-z0-9:+#]+(-[a-z0-9:+#]+)*$/;
+const MAX_TAG_LENGTH = 63;
+function normalizeTags(tags) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  const diagnostics = [];
+  for (const raw of tags) {
+    const trimmed = raw.trim().toLocaleLowerCase("en-US");
+    if (trimmed.length === 0) {
+      diagnostics.push(`tag '${raw}': empty after trim, skipped`);
+      continue;
+    }
+    if (seen.has(trimmed)) {
+      diagnostics.push(`tag '${raw}': duplicate '${trimmed}', skipped`);
+      continue;
+    }
+    if (trimmed.length > MAX_TAG_LENGTH) {
+      diagnostics.push(
+        `tag '${raw}': length ${trimmed.length} exceeds maximum ${MAX_TAG_LENGTH}, skipped`
+      );
+      seen.add(trimmed);
+      continue;
+    }
+    if (!CATALOG_TAG_RE.test(trimmed)) {
+      diagnostics.push(
+        `tag '${raw}': '${trimmed}' does not match catalog tag pattern, skipped`
+      );
+      seen.add(trimmed);
+      continue;
+    }
+    seen.add(trimmed);
+    result.push(trimmed);
+  }
+  return { tags: result, diagnostics };
+}
+const SEMVER_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+function resolveVersion(declaredVersion, digest) {
+  if (!validation.isValidDigest(digest)) {
+    throw new Error(`invalid digest: ${digest}`);
+  }
+  if (declaredVersion !== void 0 && declaredVersion !== "") {
+    let candidate = declaredVersion;
+    if (candidate.startsWith("v")) {
+      candidate = candidate.substring(1);
+    }
+    if (SEMVER_RE.test(candidate)) {
+      return candidate;
+    }
+  }
+  const hex = digest.substring(7, 19);
+  return `0.0.0+${hex}`;
+}
+const OCI_URI_RE = /^oci:\/\/([^/]+)\/(.+)@(sha256:[0-9a-f]{64})$/;
+function buildOciRef(registry, repository, digest) {
+  if (!validation.isValidDigest(digest)) {
+    throw new Error(`invalid digest: ${digest}`);
+  }
+  if (!registry || !repository) {
+    throw new Error(
+      `registry and repository must be non-empty: registry=${JSON.stringify(
+        registry
+      )}, repository=${JSON.stringify(repository)}`
+    );
+  }
+  return `oci://${registry}/${repository}@${digest}`;
+}
+function parseOciRef(uri, recordDigest) {
+  const match = OCI_URI_RE.exec(uri);
+  if (!match) {
+    throw new Error(`malformed OCI URI: ${uri}`);
+  }
+  const [, registry, repository, digest] = match;
+  if (recordDigest !== void 0 && digest !== recordDigest) {
+    throw new Error(
+      `OCI URI digest '${digest}' does not match record digest '${recordDigest}'`
+    );
+  }
+  return { uri, registry, repository, digest };
+}
+const SENSITIVE_QUERY_PARAMS = /* @__PURE__ */ new Set([
+  "sig",
+  "signature",
+  "token",
+  "access_token",
+  "api_key",
+  "apikey",
+  "secret",
+  "password",
+  "private_token",
+  "auth_token",
+  "bearer_token",
+  "x-amz-credential",
+  "x-amz-signature",
+  "x-amz-security-token",
+  "x-goog-signature",
+  "client_secret",
+  "refresh_token"
+]);
+const AZURE_SAS_PARAMS = /* @__PURE__ */ new Set([
+  "se",
+  // expiry
+  "sp",
+  // permissions
+  "spr",
+  // protocol
+  "sv",
+  // version
+  "ss",
+  // services
+  "srt",
+  // resource types
+  "st"
+  // start time
+]);
+const AZURE_SAS_CO_OCCURRENCE_THRESHOLD = 3;
+function rejectSensitiveUrl(url, context) {
+  const prefix = `${context}: ` ;
+  if (url.username || url.password) {
+    throw new Error(`${prefix}URL contains credentials`);
+  }
+  if (url.hash) {
+    throw new Error(`${prefix}URL contains a fragment`);
+  }
+  let azureSasCount = 0;
+  for (const [param] of url.searchParams) {
+    const lower = param.toLocaleLowerCase("en-US");
+    if (SENSITIVE_QUERY_PARAMS.has(lower)) {
+      throw new Error(
+        `${prefix}URL contains sensitive query parameter '${param}'`
+      );
+    }
+    if (AZURE_SAS_PARAMS.has(lower)) {
+      azureSasCount++;
+    }
+  }
+  if (azureSasCount >= AZURE_SAS_CO_OCCURRENCE_THRESHOLD) {
+    throw new Error(
+      `${prefix}URL contains Azure SAS token parameters (${azureSasCount} of ${AZURE_SAS_PARAMS.size} present)`
+    );
+  }
+}
+function buildNpxRef(sourceUri, digest) {
+  if (!validation.isValidDigest(digest)) {
+    throw new Error(`invalid digest: ${digest}`);
+  }
+  let url;
+  try {
+    url = new URL(sourceUri);
+  } catch {
+    throw new Error("invalid URL");
+  }
+  if (url.protocol !== "https:") {
+    throw new Error("npx reference: URL must use HTTPS");
+  }
+  rejectSensitiveUrl(url, "npx reference");
+  return `${url.href}#${digest}`;
+}
+function parseNpxRef(ref) {
+  const hashIndex = ref.lastIndexOf("#");
+  if (hashIndex === -1) {
+    throw new Error("malformed npx reference (no '#' separator)");
+  }
+  const sourceUri = ref.substring(0, hashIndex);
+  const digest = ref.substring(hashIndex + 1);
+  if (!validation.isValidDigest(digest)) {
+    throw new Error("malformed npx reference: invalid digest");
+  }
+  let url;
+  try {
+    url = new URL(sourceUri);
+  } catch {
+    throw new Error("malformed npx reference: invalid URL");
+  }
+  if (url.protocol !== "https:") {
+    throw new Error("npx reference: URL must use HTTPS");
+  }
+  rejectSensitiveUrl(url, "npx reference");
+  return { ref, sourceUri, digest };
+}
+
+exports.buildNpxRef = buildNpxRef;
+exports.buildOciRef = buildOciRef;
+exports.computeCatalogName = computeCatalogName;
+exports.normalizeTags = normalizeTags;
+exports.parseNpxRef = parseNpxRef;
+exports.parseOciRef = parseOciRef;
+exports.resolveVersion = resolveVersion;
+//# sourceMappingURL=catalog-helpers.cjs.js.map

package/dist/catalog-helpers.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-helpers.cjs.js","sources":["../src/catalog-helpers.ts"],"sourcesContent":["/*\n * Copyright Red Hat, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Pure identity, tag, version, and source-reference helpers for\n * catalog entity mapping (design D5).\n *\n * These helpers are consumed by the common catalog provider and have\n * no network, database, or Catalog side effects.\n *\n * @packageDocumentation\n */\n\nimport { createHash } from 'crypto';\n\nimport type { SkillSourceType } from './types';\nimport { isValidDigest } from './validation';\n\n// ─── Identity ────────────────────────────────────────────────────────\n\n/**\n * The identity tuple used for deterministic catalog entity naming.\n *\n * @public\n */\nexport interface IdentityTuple {\n  /** Source type discriminator. */\n  type: SkillSourceType;\n  /** Configured source ID. */\n  id: string;\n  /** Stable record key within the source. */\n  key: string;\n}\n\n/**\n * Computes the deterministic catalog entity name from an identity tuple.\n *\n * Per design D5, the name is `skill-` followed by the first 56 lowercase\n * hex digits of the SHA-256 hash of the compact JSON UTF-8 encoding of\n * `[source.type, source.id, record.key]`.\n *\n * Names, versions, tags, and content digests do not affect entity\n * identity. A source ID or native key change creates a different name.\n *\n * @remarks\n * The hashing algorithm (SHA-256 of compact JSON identity tuple, truncated\n * to 56 hex digits) is part of the stable public contract. Persisted\n * entities depend on this producing the same output for the same input.\n * Any change to the algorithm constitutes a breaking (major) change.\n *\n * @public\n */\nexport function computeCatalogName(tuple: IdentityTuple): string {\n  const payload = JSON.stringify([tuple.type, tuple.id, tuple.key]);\n  const hash = createHash('sha256').update(payload, 'utf8').digest('hex');\n  return `skill-${hash.substring(0, 56)}`;\n}\n\n// ─── Tag normalization ───────────────────────────────────────────────\n\n/**\n * Backstage catalog tag validation pattern: one or more segments of\n * `[a-z0-9:+#]` separated by hyphens, maximum 63 characters.\n *\n * This pattern intentionally extends the standard Backstage catalog tag\n * pattern (which uses `[a-z0-9]` segments) to also allow colons, plus\n * signs, and hash characters per design D3/D5 requirements.\n */\nconst CATALOG_TAG_RE = /^[a-z0-9:+#]+(-[a-z0-9:+#]+)*$/;\n\n/** Maximum length for a Backstage catalog tag. */\nconst MAX_TAG_LENGTH = 63;\n\n/**\n * Result of tag normalization.\n *\n * @public\n */\nexport interface NormalizeTagsResult {\n  /** Valid, deduplicated tags in lowercase. */\n  tags: string[];\n  /** Diagnostic messages for tags that were dropped. */\n  diagnostics: string[];\n}\n\n/**\n * Normalizes tags for catalog use per design D3/D5.\n *\n * Trims whitespace, lowercases, deduplicates, and retains only values\n * accepted by an extended catalog tag pattern (per design D3/D5) that\n * allows colons, plus signs, and hash characters beyond the standard\n * Backstage tag validator. Invalid or overlength values are omitted\n * with a diagnostic — tags are never truncated and replacement\n * characters are never synthesized.\n *\n * @public\n */\nexport function normalizeTags(tags: string[]): NormalizeTagsResult {\n  const seen = new Set<string>();\n  const result: string[] = [];\n  const diagnostics: string[] = [];\n\n  for (const raw of tags) {\n    const trimmed = raw.trim().toLocaleLowerCase('en-US');\n\n    if (trimmed.length === 0) {\n      diagnostics.push(`tag '${raw}': empty after trim, skipped`);\n      continue;\n    }\n\n    if (seen.has(trimmed)) {\n      diagnostics.push(`tag '${raw}': duplicate '${trimmed}', skipped`);\n      continue;\n    }\n\n    if (trimmed.length > MAX_TAG_LENGTH) {\n      diagnostics.push(\n        `tag '${raw}': length ${trimmed.length} exceeds maximum ${MAX_TAG_LENGTH}, skipped`,\n      );\n      seen.add(trimmed);\n      continue;\n    }\n\n    if (!CATALOG_TAG_RE.test(trimmed)) {\n      diagnostics.push(\n        `tag '${raw}': '${trimmed}' does not match catalog tag pattern, skipped`,\n      );\n      seen.add(trimmed);\n      continue;\n    }\n\n    seen.add(trimmed);\n    result.push(trimmed);\n  }\n\n  return { tags: result, diagnostics };\n}\n\n// ─── SemVer fallback ─────────────────────────────────────────────────\n\n/**\n * SemVer validation regex per https://semver.org/#is-there-a-suggested-regular-expression-to-check-a-semver-string\n *\n * Matches: MAJOR.MINOR.PATCH with optional pre-release and build metadata.\n */\nconst SEMVER_RE =\n  /^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$/;\n\n/**\n * Resolves a catalog version from a declared version string and record\n * digest, per design D5.\n *\n * Removes at most one leading `v`, validates the result as SemVer, and\n * falls back to `0.0.0+<first 12 hex digits of record.digest>` when no\n * valid SemVer is present.\n *\n * @param declaredVersion - The raw version string from the record, or undefined.\n * @param digest - The record's content digest in `sha256:<64 hex>` format.\n * @returns A valid SemVer string.\n *\n * @public\n */\nexport function resolveVersion(\n  declaredVersion: string | undefined,\n  digest: string,\n): string {\n  // Validate digest upfront, consistent with buildOciRef and buildNpxRef.\n  if (!isValidDigest(digest)) {\n    throw new Error(`invalid digest: ${digest}`);\n  }\n\n  if (declaredVersion !== undefined && declaredVersion !== '') {\n    let candidate = declaredVersion;\n    if (candidate.startsWith('v')) {\n      candidate = candidate.substring(1);\n    }\n    if (SEMVER_RE.test(candidate)) {\n      return candidate;\n    }\n  }\n\n  // Fallback: 0.0.0+<first 12 hex digits of digest>\n  // digest format is sha256:<64 hex>, so hex starts at index 7\n  const hex = digest.substring(7, 19);\n  return `0.0.0+${hex}`;\n}\n\n// ─── OCI references ──────────────────────────────────────────────────\n\n/**\n * A parsed OCI skill reference.\n *\n * @public\n */\nexport interface OciRef {\n  /** Full OCI URI: `oci://<registry>/<repository>@sha256:<hex>`. */\n  uri: string;\n  /** Registry host (and optional port). */\n  registry: string;\n  /** Repository path (may contain slashes). */\n  repository: string;\n  /** Content digest in `sha256:<64 hex>` format. */\n  digest: string;\n}\n\n/**\n * OCI URI pattern: `oci://<registry>/<repository>@sha256:<64 hex digits>`.\n */\nconst OCI_URI_RE = /^oci:\\/\\/([^/]+)\\/(.+)@(sha256:[0-9a-f]{64})$/;\n\n/**\n * Constructs a digest-addressed OCI reference URI.\n *\n * The returned URI has the form `oci://<registry>/<repository>@sha256:<hex>`.\n * The provided digest must be a valid SHA-256 digest string.\n *\n * @param registry - Registry host (e.g., `quay.io`).\n * @param repository - Repository path (e.g., `octo/hello-world-skill`).\n * @param digest - Content digest in `sha256:<64 hex>` format.\n * @returns The constructed OCI URI.\n * @throws If the digest is invalid.\n *\n * @public\n */\nexport function buildOciRef(\n  registry: string,\n  repository: string,\n  digest: string,\n): string {\n  if (!isValidDigest(digest)) {\n    throw new Error(`invalid digest: ${digest}`);\n  }\n  if (!registry || !repository) {\n    throw new Error(\n      `registry and repository must be non-empty: registry=${JSON.stringify(\n        registry,\n      )}, repository=${JSON.stringify(repository)}`,\n    );\n  }\n  return `oci://${registry}/${repository}@${digest}`;\n}\n\n/**\n * Parses a digest-addressed OCI reference URI.\n *\n * Rejects URIs that do not match the `oci://<registry>/<repository>@sha256:<hex>`\n * pattern. When a `recordDigest` is provided, validates that the URI digest\n * agrees with the record digest.\n *\n * @param uri - The OCI URI to parse.\n * @param recordDigest - Optional record digest to verify agreement.\n * @returns The parsed OCI reference.\n * @throws If the URI is malformed or the digest does not agree.\n *\n * @public\n */\nexport function parseOciRef(uri: string, recordDigest?: string): OciRef {\n  const match = OCI_URI_RE.exec(uri);\n  if (!match) {\n    throw new Error(`malformed OCI URI: ${uri}`);\n  }\n\n  const [, registry, repository, digest] = match;\n\n  if (recordDigest !== undefined && digest !== recordDigest) {\n    throw new Error(\n      `OCI URI digest '${digest}' does not match record digest '${recordDigest}'`,\n    );\n  }\n\n  return { uri, registry, repository, digest };\n}\n\n// ─── npx references ─────────────────────────────────────────────────\n\n/**\n * A parsed npx skill reference.\n *\n * @public\n */\nexport interface NpxRef {\n  /** Serialized reference: `<sourceUri>#<digest>`. */\n  ref: string;\n  /** The artifact source URL (HTTPS, no credentials or fragments). */\n  sourceUri: string;\n  /** Content digest in `sha256:<64 hex>` format. */\n  digest: string;\n}\n\n/**\n * Query parameter names that indicate credentials or signed access tokens.\n * Individually rejected regardless of context.\n */\nconst SENSITIVE_QUERY_PARAMS: ReadonlySet<string> = new Set([\n  'sig',\n  'signature',\n  'token',\n  'access_token',\n  'api_key',\n  'apikey',\n  'secret',\n  'password',\n  'private_token',\n  'auth_token',\n  'bearer_token',\n  'x-amz-credential',\n  'x-amz-signature',\n  'x-amz-security-token',\n  'x-goog-signature',\n  'client_secret',\n  'refresh_token',\n]);\n\n/**\n * Azure SAS token query parameters. These short, common names (`se`, `sp`,\n * `sv`, etc.) can appear in non-credential contexts, so they are only\n * rejected when {@link AZURE_SAS_CO_OCCURRENCE_THRESHOLD} or more appear\n * together — a strong signal of a signed URL.\n */\nconst AZURE_SAS_PARAMS: ReadonlySet<string> = new Set([\n  'se', // expiry\n  'sp', // permissions\n  'spr', // protocol\n  'sv', // version\n  'ss', // services\n  'srt', // resource types\n  'st', // start time\n]);\n\n/** Minimum number of Azure SAS params that must co-occur to trigger rejection. */\nconst AZURE_SAS_CO_OCCURRENCE_THRESHOLD = 3;\n\n/**\n * Checks whether a URL contains credentials (userinfo), fragments,\n * query-string credentials, or signed access tokens.\n *\n * @param url - The URL to inspect.\n * @param context - Optional context prefix for error messages (e.g., `\"npx reference\"`).\n * @throws If the URL contains sensitive elements.\n */\nfunction rejectSensitiveUrl(url: URL, context?: string): void {\n  const prefix = context ? `${context}: ` : '';\n\n  if (url.username || url.password) {\n    throw new Error(`${prefix}URL contains credentials`);\n  }\n\n  if (url.hash) {\n    throw new Error(`${prefix}URL contains a fragment`);\n  }\n\n  let azureSasCount = 0;\n  for (const [param] of url.searchParams) {\n    const lower = param.toLocaleLowerCase('en-US');\n    if (SENSITIVE_QUERY_PARAMS.has(lower)) {\n      throw new Error(\n        `${prefix}URL contains sensitive query parameter '${param}'`,\n      );\n    }\n    if (AZURE_SAS_PARAMS.has(lower)) {\n      azureSasCount++;\n    }\n  }\n\n  if (azureSasCount >= AZURE_SAS_CO_OCCURRENCE_THRESHOLD) {\n    throw new Error(\n      `${prefix}URL contains Azure SAS token parameters (${azureSasCount} of ${AZURE_SAS_PARAMS.size} present)`,\n    );\n  }\n}\n\n/**\n * Constructs an npx skill reference from a verified artifact URL and digest.\n *\n * The reference has the form `<sourceUri>#<digest>` where `sourceUri` is an\n * absolute HTTPS URL without credentials or fragments, and `digest` is a\n * lowercase SHA-256 digest.\n *\n * Non-sensitive query parameters retain their original order.\n *\n * @param sourceUri - Absolute HTTPS artifact URL.\n * @param digest - Content digest in `sha256:<64 hex>` format.\n * @returns The serialized npx reference string.\n * @throws If the URL contains credentials, fragments, or sensitive params,\n *   or if the digest is invalid, or the URL is not HTTPS.\n *\n * @public\n */\nexport function buildNpxRef(sourceUri: string, digest: string): string {\n  if (!isValidDigest(digest)) {\n    throw new Error(`invalid digest: ${digest}`);\n  }\n\n  let url: URL;\n  try {\n    url = new URL(sourceUri);\n  } catch {\n    throw new Error('invalid URL');\n  }\n\n  if (url.protocol !== 'https:') {\n    throw new Error('npx reference: URL must use HTTPS');\n  }\n\n  rejectSensitiveUrl(url, 'npx reference');\n\n  // Serialize using URL API to normalize, preserving query order\n  return `${url.href}#${digest}`;\n}\n\n/**\n * Parses an npx skill reference.\n *\n * Splits at the single literal `#` separator. Validates that the URL is\n * HTTPS, contains no credentials or fragments, and that the digest is a\n * valid SHA-256 digest.\n *\n * @param ref - The serialized npx reference (`<sourceUri>#<digest>`).\n * @returns The parsed npx reference.\n * @throws If the reference is malformed or the URL is sensitive.\n *\n * @public\n */\nexport function parseNpxRef(ref: string): NpxRef {\n  // Split at the last '#' to separate URL from digest\n  const hashIndex = ref.lastIndexOf('#');\n  if (hashIndex === -1) {\n    throw new Error(\"malformed npx reference (no '#' separator)\");\n  }\n\n  const sourceUri = ref.substring(0, hashIndex);\n  const digest = ref.substring(hashIndex + 1);\n\n  if (!isValidDigest(digest)) {\n    throw new Error('malformed npx reference: invalid digest');\n  }\n\n  let url: URL;\n  try {\n    url = new URL(sourceUri);\n  } catch {\n    throw new Error('malformed npx reference: invalid URL');\n  }\n\n  if (url.protocol !== 'https:') {\n    throw new Error('npx reference: URL must use HTTPS');\n  }\n\n  rejectSensitiveUrl(url, 'npx reference');\n\n  return { ref, sourceUri, digest };\n}\n"],"names":["createHash","isValidDigest"],"mappings":"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"}

package/dist/catalog-helpers.esm.js

@@ -0,0 +1,190 @@
+import { createHash } from 'crypto';
+import { isValidDigest } from './validation.esm.js';
+
+function computeCatalogName(tuple) {
+  const payload = JSON.stringify([tuple.type, tuple.id, tuple.key]);
+  const hash = createHash("sha256").update(payload, "utf8").digest("hex");
+  return `skill-${hash.substring(0, 56)}`;
+}
+const CATALOG_TAG_RE = /^[a-z0-9:+#]+(-[a-z0-9:+#]+)*$/;
+const MAX_TAG_LENGTH = 63;
+function normalizeTags(tags) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  const diagnostics = [];
+  for (const raw of tags) {
+    const trimmed = raw.trim().toLocaleLowerCase("en-US");
+    if (trimmed.length === 0) {
+      diagnostics.push(`tag '${raw}': empty after trim, skipped`);
+      continue;
+    }
+    if (seen.has(trimmed)) {
+      diagnostics.push(`tag '${raw}': duplicate '${trimmed}', skipped`);
+      continue;
+    }
+    if (trimmed.length > MAX_TAG_LENGTH) {
+      diagnostics.push(
+        `tag '${raw}': length ${trimmed.length} exceeds maximum ${MAX_TAG_LENGTH}, skipped`
+      );
+      seen.add(trimmed);
+      continue;
+    }
+    if (!CATALOG_TAG_RE.test(trimmed)) {
+      diagnostics.push(
+        `tag '${raw}': '${trimmed}' does not match catalog tag pattern, skipped`
+      );
+      seen.add(trimmed);
+      continue;
+    }
+    seen.add(trimmed);
+    result.push(trimmed);
+  }
+  return { tags: result, diagnostics };
+}
+const SEMVER_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+function resolveVersion(declaredVersion, digest) {
+  if (!isValidDigest(digest)) {
+    throw new Error(`invalid digest: ${digest}`);
+  }
+  if (declaredVersion !== void 0 && declaredVersion !== "") {
+    let candidate = declaredVersion;
+    if (candidate.startsWith("v")) {
+      candidate = candidate.substring(1);
+    }
+    if (SEMVER_RE.test(candidate)) {
+      return candidate;
+    }
+  }
+  const hex = digest.substring(7, 19);
+  return `0.0.0+${hex}`;
+}
+const OCI_URI_RE = /^oci:\/\/([^/]+)\/(.+)@(sha256:[0-9a-f]{64})$/;
+function buildOciRef(registry, repository, digest) {
+  if (!isValidDigest(digest)) {
+    throw new Error(`invalid digest: ${digest}`);
+  }
+  if (!registry || !repository) {
+    throw new Error(
+      `registry and repository must be non-empty: registry=${JSON.stringify(
+        registry
+      )}, repository=${JSON.stringify(repository)}`
+    );
+  }
+  return `oci://${registry}/${repository}@${digest}`;
+}
+function parseOciRef(uri, recordDigest) {
+  const match = OCI_URI_RE.exec(uri);
+  if (!match) {
+    throw new Error(`malformed OCI URI: ${uri}`);
+  }
+  const [, registry, repository, digest] = match;
+  if (recordDigest !== void 0 && digest !== recordDigest) {
+    throw new Error(
+      `OCI URI digest '${digest}' does not match record digest '${recordDigest}'`
+    );
+  }
+  return { uri, registry, repository, digest };
+}
+const SENSITIVE_QUERY_PARAMS = /* @__PURE__ */ new Set([
+  "sig",
+  "signature",
+  "token",
+  "access_token",
+  "api_key",
+  "apikey",
+  "secret",
+  "password",
+  "private_token",
+  "auth_token",
+  "bearer_token",
+  "x-amz-credential",
+  "x-amz-signature",
+  "x-amz-security-token",
+  "x-goog-signature",
+  "client_secret",
+  "refresh_token"
+]);
+const AZURE_SAS_PARAMS = /* @__PURE__ */ new Set([
+  "se",
+  // expiry
+  "sp",
+  // permissions
+  "spr",
+  // protocol
+  "sv",
+  // version
+  "ss",
+  // services
+  "srt",
+  // resource types
+  "st"
+  // start time
+]);
+const AZURE_SAS_CO_OCCURRENCE_THRESHOLD = 3;
+function rejectSensitiveUrl(url, context) {
+  const prefix = `${context}: ` ;
+  if (url.username || url.password) {
+    throw new Error(`${prefix}URL contains credentials`);
+  }
+  if (url.hash) {
+    throw new Error(`${prefix}URL contains a fragment`);
+  }
+  let azureSasCount = 0;
+  for (const [param] of url.searchParams) {
+    const lower = param.toLocaleLowerCase("en-US");
+    if (SENSITIVE_QUERY_PARAMS.has(lower)) {
+      throw new Error(
+        `${prefix}URL contains sensitive query parameter '${param}'`
+      );
+    }
+    if (AZURE_SAS_PARAMS.has(lower)) {
+      azureSasCount++;
+    }
+  }
+  if (azureSasCount >= AZURE_SAS_CO_OCCURRENCE_THRESHOLD) {
+    throw new Error(
+      `${prefix}URL contains Azure SAS token parameters (${azureSasCount} of ${AZURE_SAS_PARAMS.size} present)`
+    );
+  }
+}
+function buildNpxRef(sourceUri, digest) {
+  if (!isValidDigest(digest)) {
+    throw new Error(`invalid digest: ${digest}`);
+  }
+  let url;
+  try {
+    url = new URL(sourceUri);
+  } catch {
+    throw new Error("invalid URL");
+  }
+  if (url.protocol !== "https:") {
+    throw new Error("npx reference: URL must use HTTPS");
+  }
+  rejectSensitiveUrl(url, "npx reference");
+  return `${url.href}#${digest}`;
+}
+function parseNpxRef(ref) {
+  const hashIndex = ref.lastIndexOf("#");
+  if (hashIndex === -1) {
+    throw new Error("malformed npx reference (no '#' separator)");
+  }
+  const sourceUri = ref.substring(0, hashIndex);
+  const digest = ref.substring(hashIndex + 1);
+  if (!isValidDigest(digest)) {
+    throw new Error("malformed npx reference: invalid digest");
+  }
+  let url;
+  try {
+    url = new URL(sourceUri);
+  } catch {
+    throw new Error("malformed npx reference: invalid URL");
+  }
+  if (url.protocol !== "https:") {
+    throw new Error("npx reference: URL must use HTTPS");
+  }
+  rejectSensitiveUrl(url, "npx reference");
+  return { ref, sourceUri, digest };
+}
+
+export { buildNpxRef, buildOciRef, computeCatalogName, normalizeTags, parseNpxRef, parseOciRef, resolveVersion };
+//# sourceMappingURL=catalog-helpers.esm.js.map

package/dist/catalog-helpers.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-helpers.esm.js","sources":["../src/catalog-helpers.ts"],"sourcesContent":["/*\n * Copyright Red Hat, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Pure identity, tag, version, and source-reference helpers for\n * catalog entity mapping (design D5).\n *\n * These helpers are consumed by the common catalog provider and have\n * no network, database, or Catalog side effects.\n *\n * @packageDocumentation\n */\n\nimport { createHash } from 'crypto';\n\nimport type { SkillSourceType } from './types';\nimport { isValidDigest } from './validation';\n\n// ─── Identity ────────────────────────────────────────────────────────\n\n/**\n * The identity tuple used for deterministic catalog entity naming.\n *\n * @public\n */\nexport interface IdentityTuple {\n  /** Source type discriminator. */\n  type: SkillSourceType;\n  /** Configured source ID. */\n  id: string;\n  /** Stable record key within the source. */\n  key: string;\n}\n\n/**\n * Computes the deterministic catalog entity name from an identity tuple.\n *\n * Per design D5, the name is `skill-` followed by the first 56 lowercase\n * hex digits of the SHA-256 hash of the compact JSON UTF-8 encoding of\n * `[source.type, source.id, record.key]`.\n *\n * Names, versions, tags, and content digests do not affect entity\n * identity. A source ID or native key change creates a different name.\n *\n * @remarks\n * The hashing algorithm (SHA-256 of compact JSON identity tuple, truncated\n * to 56 hex digits) is part of the stable public contract. Persisted\n * entities depend on this producing the same output for the same input.\n * Any change to the algorithm constitutes a breaking (major) change.\n *\n * @public\n */\nexport function computeCatalogName(tuple: IdentityTuple): string {\n  const payload = JSON.stringify([tuple.type, tuple.id, tuple.key]);\n  const hash = createHash('sha256').update(payload, 'utf8').digest('hex');\n  return `skill-${hash.substring(0, 56)}`;\n}\n\n// ─── Tag normalization ───────────────────────────────────────────────\n\n/**\n * Backstage catalog tag validation pattern: one or more segments of\n * `[a-z0-9:+#]` separated by hyphens, maximum 63 characters.\n *\n * This pattern intentionally extends the standard Backstage catalog tag\n * pattern (which uses `[a-z0-9]` segments) to also allow colons, plus\n * signs, and hash characters per design D3/D5 requirements.\n */\nconst CATALOG_TAG_RE = /^[a-z0-9:+#]+(-[a-z0-9:+#]+)*$/;\n\n/** Maximum length for a Backstage catalog tag. */\nconst MAX_TAG_LENGTH = 63;\n\n/**\n * Result of tag normalization.\n *\n * @public\n */\nexport interface NormalizeTagsResult {\n  /** Valid, deduplicated tags in lowercase. */\n  tags: string[];\n  /** Diagnostic messages for tags that were dropped. */\n  diagnostics: string[];\n}\n\n/**\n * Normalizes tags for catalog use per design D3/D5.\n *\n * Trims whitespace, lowercases, deduplicates, and retains only values\n * accepted by an extended catalog tag pattern (per design D3/D5) that\n * allows colons, plus signs, and hash characters beyond the standard\n * Backstage tag validator. Invalid or overlength values are omitted\n * with a diagnostic — tags are never truncated and replacement\n * characters are never synthesized.\n *\n * @public\n */\nexport function normalizeTags(tags: string[]): NormalizeTagsResult {\n  const seen = new Set<string>();\n  const result: string[] = [];\n  const diagnostics: string[] = [];\n\n  for (const raw of tags) {\n    const trimmed = raw.trim().toLocaleLowerCase('en-US');\n\n    if (trimmed.length === 0) {\n      diagnostics.push(`tag '${raw}': empty after trim, skipped`);\n      continue;\n    }\n\n    if (seen.has(trimmed)) {\n      diagnostics.push(`tag '${raw}': duplicate '${trimmed}', skipped`);\n      continue;\n    }\n\n    if (trimmed.length > MAX_TAG_LENGTH) {\n      diagnostics.push(\n        `tag '${raw}': length ${trimmed.length} exceeds maximum ${MAX_TAG_LENGTH}, skipped`,\n      );\n      seen.add(trimmed);\n      continue;\n    }\n\n    if (!CATALOG_TAG_RE.test(trimmed)) {\n      diagnostics.push(\n        `tag '${raw}': '${trimmed}' does not match catalog tag pattern, skipped`,\n      );\n      seen.add(trimmed);\n      continue;\n    }\n\n    seen.add(trimmed);\n    result.push(trimmed);\n  }\n\n  return { tags: result, diagnostics };\n}\n\n// ─── SemVer fallback ─────────────────────────────────────────────────\n\n/**\n * SemVer validation regex per https://semver.org/#is-there-a-suggested-regular-expression-to-check-a-semver-string\n *\n * Matches: MAJOR.MINOR.PATCH with optional pre-release and build metadata.\n */\nconst SEMVER_RE =\n  /^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$/;\n\n/**\n * Resolves a catalog version from a declared version string and record\n * digest, per design D5.\n *\n * Removes at most one leading `v`, validates the result as SemVer, and\n * falls back to `0.0.0+<first 12 hex digits of record.digest>` when no\n * valid SemVer is present.\n *\n * @param declaredVersion - The raw version string from the record, or undefined.\n * @param digest - The record's content digest in `sha256:<64 hex>` format.\n * @returns A valid SemVer string.\n *\n * @public\n */\nexport function resolveVersion(\n  declaredVersion: string | undefined,\n  digest: string,\n): string {\n  // Validate digest upfront, consistent with buildOciRef and buildNpxRef.\n  if (!isValidDigest(digest)) {\n    throw new Error(`invalid digest: ${digest}`);\n  }\n\n  if (declaredVersion !== undefined && declaredVersion !== '') {\n    let candidate = declaredVersion;\n    if (candidate.startsWith('v')) {\n      candidate = candidate.substring(1);\n    }\n    if (SEMVER_RE.test(candidate)) {\n      return candidate;\n    }\n  }\n\n  // Fallback: 0.0.0+<first 12 hex digits of digest>\n  // digest format is sha256:<64 hex>, so hex starts at index 7\n  const hex = digest.substring(7, 19);\n  return `0.0.0+${hex}`;\n}\n\n// ─── OCI references ──────────────────────────────────────────────────\n\n/**\n * A parsed OCI skill reference.\n *\n * @public\n */\nexport interface OciRef {\n  /** Full OCI URI: `oci://<registry>/<repository>@sha256:<hex>`. */\n  uri: string;\n  /** Registry host (and optional port). */\n  registry: string;\n  /** Repository path (may contain slashes). */\n  repository: string;\n  /** Content digest in `sha256:<64 hex>` format. */\n  digest: string;\n}\n\n/**\n * OCI URI pattern: `oci://<registry>/<repository>@sha256:<64 hex digits>`.\n */\nconst OCI_URI_RE = /^oci:\\/\\/([^/]+)\\/(.+)@(sha256:[0-9a-f]{64})$/;\n\n/**\n * Constructs a digest-addressed OCI reference URI.\n *\n * The returned URI has the form `oci://<registry>/<repository>@sha256:<hex>`.\n * The provided digest must be a valid SHA-256 digest string.\n *\n * @param registry - Registry host (e.g., `quay.io`).\n * @param repository - Repository path (e.g., `octo/hello-world-skill`).\n * @param digest - Content digest in `sha256:<64 hex>` format.\n * @returns The constructed OCI URI.\n * @throws If the digest is invalid.\n *\n * @public\n */\nexport function buildOciRef(\n  registry: string,\n  repository: string,\n  digest: string,\n): string {\n  if (!isValidDigest(digest)) {\n    throw new Error(`invalid digest: ${digest}`);\n  }\n  if (!registry || !repository) {\n    throw new Error(\n      `registry and repository must be non-empty: registry=${JSON.stringify(\n        registry,\n      )}, repository=${JSON.stringify(repository)}`,\n    );\n  }\n  return `oci://${registry}/${repository}@${digest}`;\n}\n\n/**\n * Parses a digest-addressed OCI reference URI.\n *\n * Rejects URIs that do not match the `oci://<registry>/<repository>@sha256:<hex>`\n * pattern. When a `recordDigest` is provided, validates that the URI digest\n * agrees with the record digest.\n *\n * @param uri - The OCI URI to parse.\n * @param recordDigest - Optional record digest to verify agreement.\n * @returns The parsed OCI reference.\n * @throws If the URI is malformed or the digest does not agree.\n *\n * @public\n */\nexport function parseOciRef(uri: string, recordDigest?: string): OciRef {\n  const match = OCI_URI_RE.exec(uri);\n  if (!match) {\n    throw new Error(`malformed OCI URI: ${uri}`);\n  }\n\n  const [, registry, repository, digest] = match;\n\n  if (recordDigest !== undefined && digest !== recordDigest) {\n    throw new Error(\n      `OCI URI digest '${digest}' does not match record digest '${recordDigest}'`,\n    );\n  }\n\n  return { uri, registry, repository, digest };\n}\n\n// ─── npx references ─────────────────────────────────────────────────\n\n/**\n * A parsed npx skill reference.\n *\n * @public\n */\nexport interface NpxRef {\n  /** Serialized reference: `<sourceUri>#<digest>`. */\n  ref: string;\n  /** The artifact source URL (HTTPS, no credentials or fragments). */\n  sourceUri: string;\n  /** Content digest in `sha256:<64 hex>` format. */\n  digest: string;\n}\n\n/**\n * Query parameter names that indicate credentials or signed access tokens.\n * Individually rejected regardless of context.\n */\nconst SENSITIVE_QUERY_PARAMS: ReadonlySet<string> = new Set([\n  'sig',\n  'signature',\n  'token',\n  'access_token',\n  'api_key',\n  'apikey',\n  'secret',\n  'password',\n  'private_token',\n  'auth_token',\n  'bearer_token',\n  'x-amz-credential',\n  'x-amz-signature',\n  'x-amz-security-token',\n  'x-goog-signature',\n  'client_secret',\n  'refresh_token',\n]);\n\n/**\n * Azure SAS token query parameters. These short, common names (`se`, `sp`,\n * `sv`, etc.) can appear in non-credential contexts, so they are only\n * rejected when {@link AZURE_SAS_CO_OCCURRENCE_THRESHOLD} or more appear\n * together — a strong signal of a signed URL.\n */\nconst AZURE_SAS_PARAMS: ReadonlySet<string> = new Set([\n  'se', // expiry\n  'sp', // permissions\n  'spr', // protocol\n  'sv', // version\n  'ss', // services\n  'srt', // resource types\n  'st', // start time\n]);\n\n/** Minimum number of Azure SAS params that must co-occur to trigger rejection. */\nconst AZURE_SAS_CO_OCCURRENCE_THRESHOLD = 3;\n\n/**\n * Checks whether a URL contains credentials (userinfo), fragments,\n * query-string credentials, or signed access tokens.\n *\n * @param url - The URL to inspect.\n * @param context - Optional context prefix for error messages (e.g., `\"npx reference\"`).\n * @throws If the URL contains sensitive elements.\n */\nfunction rejectSensitiveUrl(url: URL, context?: string): void {\n  const prefix = context ? `${context}: ` : '';\n\n  if (url.username || url.password) {\n    throw new Error(`${prefix}URL contains credentials`);\n  }\n\n  if (url.hash) {\n    throw new Error(`${prefix}URL contains a fragment`);\n  }\n\n  let azureSasCount = 0;\n  for (const [param] of url.searchParams) {\n    const lower = param.toLocaleLowerCase('en-US');\n    if (SENSITIVE_QUERY_PARAMS.has(lower)) {\n      throw new Error(\n        `${prefix}URL contains sensitive query parameter '${param}'`,\n      );\n    }\n    if (AZURE_SAS_PARAMS.has(lower)) {\n      azureSasCount++;\n    }\n  }\n\n  if (azureSasCount >= AZURE_SAS_CO_OCCURRENCE_THRESHOLD) {\n    throw new Error(\n      `${prefix}URL contains Azure SAS token parameters (${azureSasCount} of ${AZURE_SAS_PARAMS.size} present)`,\n    );\n  }\n}\n\n/**\n * Constructs an npx skill reference from a verified artifact URL and digest.\n *\n * The reference has the form `<sourceUri>#<digest>` where `sourceUri` is an\n * absolute HTTPS URL without credentials or fragments, and `digest` is a\n * lowercase SHA-256 digest.\n *\n * Non-sensitive query parameters retain their original order.\n *\n * @param sourceUri - Absolute HTTPS artifact URL.\n * @param digest - Content digest in `sha256:<64 hex>` format.\n * @returns The serialized npx reference string.\n * @throws If the URL contains credentials, fragments, or sensitive params,\n *   or if the digest is invalid, or the URL is not HTTPS.\n *\n * @public\n */\nexport function buildNpxRef(sourceUri: string, digest: string): string {\n  if (!isValidDigest(digest)) {\n    throw new Error(`invalid digest: ${digest}`);\n  }\n\n  let url: URL;\n  try {\n    url = new URL(sourceUri);\n  } catch {\n    throw new Error('invalid URL');\n  }\n\n  if (url.protocol !== 'https:') {\n    throw new Error('npx reference: URL must use HTTPS');\n  }\n\n  rejectSensitiveUrl(url, 'npx reference');\n\n  // Serialize using URL API to normalize, preserving query order\n  return `${url.href}#${digest}`;\n}\n\n/**\n * Parses an npx skill reference.\n *\n * Splits at the single literal `#` separator. Validates that the URL is\n * HTTPS, contains no credentials or fragments, and that the digest is a\n * valid SHA-256 digest.\n *\n * @param ref - The serialized npx reference (`<sourceUri>#<digest>`).\n * @returns The parsed npx reference.\n * @throws If the reference is malformed or the URL is sensitive.\n *\n * @public\n */\nexport function parseNpxRef(ref: string): NpxRef {\n  // Split at the last '#' to separate URL from digest\n  const hashIndex = ref.lastIndexOf('#');\n  if (hashIndex === -1) {\n    throw new Error(\"malformed npx reference (no '#' separator)\");\n  }\n\n  const sourceUri = ref.substring(0, hashIndex);\n  const digest = ref.substring(hashIndex + 1);\n\n  if (!isValidDigest(digest)) {\n    throw new Error('malformed npx reference: invalid digest');\n  }\n\n  let url: URL;\n  try {\n    url = new URL(sourceUri);\n  } catch {\n    throw new Error('malformed npx reference: invalid URL');\n  }\n\n  if (url.protocol !== 'https:') {\n    throw new Error('npx reference: URL must use HTTPS');\n  }\n\n  rejectSensitiveUrl(url, 'npx reference');\n\n  return { ref, sourceUri, digest };\n}\n"],"names":[],"mappings":"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"}