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

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @red-hat-developer-hub/backstage-plugin-ai-skills-common
 
+## 0.4.0
+
+### Minor Changes
+
+- e526768: Add pure OCI and npx metadata normalizers implementing design D3 native-field mappings and precedence, with input types, normalization diagnostics, shared catalog-valid tag processing, author string normalization, allowlisted extension mapping, and reusable native metadata fixtures including conflicting-version scenarios.
+
+  Both metadata normalizers and the existing `normalizeTags` helper share Backstage's catalog tag rules. Dots, underscores, consecutive hyphens, and tags longer than 63 characters are omitted with diagnostics. For example, `rhdh:2`, `version+beta`, and `tag#1` remain valid; `rhdh:2.2`, `has_underscore`, and `in--valid` are omitted. Development-only parity tests compare all three normalization paths with Backstage's catalog validator.
+
+  The OCI trusted-input fixture uses the tagged key `quay.io/octo/hello-world-skill:1.0.0-draft`, consistent with the per-tag identity contract. Its digest-addressed source URI is unchanged.
+
+  The `normalizeTags` diagnostic messages now use "omitted" instead of "skipped". Their wording is informational and may change.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -41,6 +41,69 @@ reference construction and declared-version mapping are unchanged.
 | `MAX_RESPONSE_BYTES`       | `5 * 1024 * 1024` | Maximum response read size for consumers (5 MiB) |
 | `SUPPORTED_SCHEMA_VERSION` | `'1'`             | Supported schema version                         |
 
+## Normalization
+
+Pure metadata normalizers implementing design D3 native-field mappings
+and precedence. These functions accept already-parsed, verified inputs
+and return schema-valid `SkillRecord`s or explicit per-record
+diagnostics. They perform no network, scheduler, database, or catalog
+operations.
+
+### Functions
+
+| Function               | Description                                                |
+| ---------------------- | ---------------------------------------------------------- |
+| `normalizeOciMetadata` | Normalizes OCI SkillCard and Markdown frontmatter metadata |
+| `normalizeNpxMetadata` | Normalizes npx discovery entry and Markdown frontmatter    |
+
+### Input types
+
+| Type                     | Description                                                 |
+| ------------------------ | ----------------------------------------------------------- |
+| `OciNativeInput`         | Combined OCI SkillCard and frontmatter for normalization    |
+| `OciSkillCard`           | Parsed OCI SkillCard document                               |
+| `OciSkillCardMetadata`   | Parsed OCI SkillCard metadata fields                        |
+| `OciSkillCardSpec`       | Parsed OCI SkillCard spec fields                            |
+| `OciMarkdownFrontmatter` | Parsed OCI Markdown frontmatter                             |
+| `NpxNativeInput`         | Combined npx discovery entry and frontmatter                |
+| `NpxDiscoveryEntry`      | Parsed npx discovery entry                                  |
+| `NpxFrontmatter`         | Parsed npx Markdown frontmatter                             |
+| `TrustedSourceInput`     | Trusted source identity/integrity fields from the connector |
+
+### Result types
+
+| Type                      | Description                                              |
+| ------------------------- | -------------------------------------------------------- |
+| `NormalizationResult<T>`  | Contains the normalized record (or null) and diagnostics |
+| `NormalizationDiagnostic` | A single diagnostic with field name and message          |
+
+The metadata normalizers return diagnostics as `{ field, message }` objects
+because they process multiple metadata fields. The existing `normalizeTags`
+catalog helper returns diagnostic strings for its single tag input. Both shapes
+are intentional. Diagnostic message text is informational and may change.
+
+### Constants
+
+| Constant              | Value | Description                                   |
+| --------------------- | ----- | --------------------------------------------- |
+| `MAX_TAG_LENGTH`      | `63`  | Maximum tag length for Backstage catalog tags |
+| `CATALOG_TAG_PATTERN` | regex | Backstage catalog tag validation pattern      |
+
+### Behavior
+
+- **D3 precedence**: Each field has an ordered list of candidates.
+  The first non-empty, correctly typed value wins.
+- **Tag processing**: Tags are trimmed, lowercased, deduplicated, and
+  validated against `CATALOG_TAG_PATTERN`. Invalid or overlength tags
+  are omitted with diagnostics.
+- **Author normalization**: String authors are normalized to
+  `[{ name: value }]`. Array authors require a non-empty `name`.
+  Invalid entries are omitted with diagnostics.
+- **Extension allowlisting**: Only `extensions.oci.namespace`,
+  `extensions.oci.prompt`, and `extensions.npx.type` are preserved.
+- **Diagnostics**: Non-string candidates at any priority level emit
+  a diagnostic even when a valid lower-priority candidate is selected.
+
 ## Validation
 
 - `validateSnapshot(snapshot)` — validates a complete v1 snapshot
@@ -98,10 +161,12 @@ Catalog side effects.
   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.
+  tags against `CATALOG_TAG_PATTERN` and `MAX_TAG_LENGTH`. The tag
+  pattern matches Backstage's default catalog validator: lowercase letters,
+  digits, colons (`:`), plus signs (`+`), and hash characters (`#`), separated
+  by single hyphens. Dots, underscores, and consecutive hyphens are invalid.
+  Parity tests use Backstage's validator to detect drift. 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.

package/dist/catalog-helpers.cjs.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var crypto = require('crypto');
+var tagConstants = require('./tag-constants.cjs.js');
 var validation = require('./validation.cjs.js');
 
 function computeCatalogName(tuple) {
@@ -8,8 +9,6 @@ function computeCatalogName(tuple) {
   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 = [];
@@ -17,23 +16,23 @@ function normalizeTags(tags) {
   for (const raw of tags) {
     const trimmed = raw.trim().toLocaleLowerCase("en-US");
     if (trimmed.length === 0) {
-      diagnostics.push(`tag '${raw}': empty after trim, skipped`);
+      diagnostics.push(`tag '${raw}': empty after trim, omitted`);
       continue;
     }
     if (seen.has(trimmed)) {
-      diagnostics.push(`tag '${raw}': duplicate '${trimmed}', skipped`);
+      diagnostics.push(`tag '${raw}': duplicate '${trimmed}', omitted`);
       continue;
     }
-    if (trimmed.length > MAX_TAG_LENGTH) {
+    if (trimmed.length > tagConstants.MAX_TAG_LENGTH) {
       diagnostics.push(
-        `tag '${raw}': length ${trimmed.length} exceeds maximum ${MAX_TAG_LENGTH}, skipped`
+        `tag '${raw}': length ${trimmed.length} exceeds maximum ${tagConstants.MAX_TAG_LENGTH}, omitted`
       );
       seen.add(trimmed);
       continue;
     }
-    if (!CATALOG_TAG_RE.test(trimmed)) {
+    if (!tagConstants.CATALOG_TAG_PATTERN.test(trimmed)) {
       diagnostics.push(
-        `tag '${raw}': '${trimmed}' does not match catalog tag pattern, skipped`
+        `tag '${raw}': '${trimmed}' does not match catalog tag pattern, omitted`
       );
       seen.add(trimmed);
       continue;

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

@@ -1 +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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"}
+{"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 { CATALOG_TAG_PATTERN, MAX_TAG_LENGTH } from './tag-constants';\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 * Result of tag normalization.\n *\n * @public\n */\nexport interface NormalizeTagsResult {\n  /** Valid, deduplicated tags in lowercase. */\n  tags: string[];\n  /**\n   * Diagnostic messages for tags that were dropped.\n   *\n   * @remarks\n   * Message text is informational and may change. Consumers must not\n   * treat wording as a stable API or use it for programmatic decisions.\n   */\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 {@link CATALOG_TAG_PATTERN} (per design D3/D5). Invalid or\n * overlength values are omitted with a diagnostic — tags are never\n * truncated and replacement 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, omitted`);\n      continue;\n    }\n\n    if (seen.has(trimmed)) {\n      diagnostics.push(`tag '${raw}': duplicate '${trimmed}', omitted`);\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}, omitted`,\n      );\n      seen.add(trimmed);\n      continue;\n    }\n\n    if (!CATALOG_TAG_PATTERN.test(trimmed)) {\n      diagnostics.push(\n        `tag '${raw}': '${trimmed}' does not match catalog tag pattern, omitted`,\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","MAX_TAG_LENGTH","CATALOG_TAG_PATTERN","isValidDigest"],"mappings":"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"}

package/dist/catalog-helpers.esm.js

@@ -1,4 +1,5 @@
 import { createHash } from 'crypto';
+import { MAX_TAG_LENGTH, CATALOG_TAG_PATTERN } from './tag-constants.esm.js';
 import { isValidDigest } from './validation.esm.js';
 
 function computeCatalogName(tuple) {
@@ -6,8 +7,6 @@ function computeCatalogName(tuple) {
   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 = [];
@@ -15,23 +14,23 @@ function normalizeTags(tags) {
   for (const raw of tags) {
     const trimmed = raw.trim().toLocaleLowerCase("en-US");
     if (trimmed.length === 0) {
-      diagnostics.push(`tag '${raw}': empty after trim, skipped`);
+      diagnostics.push(`tag '${raw}': empty after trim, omitted`);
       continue;
     }
     if (seen.has(trimmed)) {
-      diagnostics.push(`tag '${raw}': duplicate '${trimmed}', skipped`);
+      diagnostics.push(`tag '${raw}': duplicate '${trimmed}', omitted`);
       continue;
     }
     if (trimmed.length > MAX_TAG_LENGTH) {
       diagnostics.push(
-        `tag '${raw}': length ${trimmed.length} exceeds maximum ${MAX_TAG_LENGTH}, skipped`
+        `tag '${raw}': length ${trimmed.length} exceeds maximum ${MAX_TAG_LENGTH}, omitted`
       );
       seen.add(trimmed);
       continue;
     }
-    if (!CATALOG_TAG_RE.test(trimmed)) {
+    if (!CATALOG_TAG_PATTERN.test(trimmed)) {
       diagnostics.push(
-        `tag '${raw}': '${trimmed}' does not match catalog tag pattern, skipped`
+        `tag '${raw}': '${trimmed}' does not match catalog tag pattern, omitted`
       );
       seen.add(trimmed);
       continue;

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

@@ -1 +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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"}
+{"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 { CATALOG_TAG_PATTERN, MAX_TAG_LENGTH } from './tag-constants';\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 * Result of tag normalization.\n *\n * @public\n */\nexport interface NormalizeTagsResult {\n  /** Valid, deduplicated tags in lowercase. */\n  tags: string[];\n  /**\n   * Diagnostic messages for tags that were dropped.\n   *\n   * @remarks\n   * Message text is informational and may change. Consumers must not\n   * treat wording as a stable API or use it for programmatic decisions.\n   */\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 {@link CATALOG_TAG_PATTERN} (per design D3/D5). Invalid or\n * overlength values are omitted with a diagnostic — tags are never\n * truncated and replacement 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, omitted`);\n      continue;\n    }\n\n    if (seen.has(trimmed)) {\n      diagnostics.push(`tag '${raw}': duplicate '${trimmed}', omitted`);\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}, omitted`,\n      );\n      seen.add(trimmed);\n      continue;\n    }\n\n    if (!CATALOG_TAG_PATTERN.test(trimmed)) {\n      diagnostics.push(\n        `tag '${raw}': '${trimmed}' does not match catalog tag pattern, omitted`,\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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"}

package/dist/fixtures.cjs.js

@@ -236,6 +236,115 @@ const invalidSnapshotNonUtcTimestamp = {
   skills: [],
   failedSkillKeys: []
 };
+const ociSkillCardFull = {
+  metadata: {
+    "display-name": "Hello World Skill",
+    name: "hello-world-skill",
+    description: "A demo OCI skill image",
+    version: "1.0.0",
+    license: "Apache-2.0",
+    authors: [{ name: "OCTO Team", email: "octo@example.com" }],
+    tags: ["Demo", "hello-world"],
+    compatibility: "rhdh-2.2",
+    namespace: "octo-skills"
+  },
+  spec: {
+    prompt: "You are a helpful assistant."
+  }
+};
+const ociMarkdownFrontmatterFull = {
+  name: "Hello World (Markdown)",
+  description: "A demo OCI skill from Markdown",
+  version: "0.9.0",
+  license: "MIT",
+  compatibility: "rhdh-2.1",
+  metadata: {
+    version: "1.0",
+    author: "Markdown Author",
+    tags: ["markdown-tag"],
+    owner: "team-octo",
+    lifecycle: "production"
+  }
+};
+const ociSkillCardConflictingVersion = {
+  metadata: {
+    name: "version-test-skill",
+    version: "1.0.0"
+  }
+};
+const ociMarkdownFrontmatterConflictingVersion = {
+  name: "Version Test (Markdown)",
+  metadata: {
+    version: "1.0"
+  },
+  version: "0.9.0"
+};
+const ociSkillCardMinimal = {
+  metadata: {
+    name: "Minimal Skill"
+  }
+};
+const ociNativeInputFull = {
+  skillCard: ociSkillCardFull,
+  frontmatter: ociMarkdownFrontmatterFull
+};
+const ociNativeInputConflictingVersion = {
+  skillCard: ociSkillCardConflictingVersion,
+  frontmatter: ociMarkdownFrontmatterConflictingVersion
+};
+const ociNativeInputMinimal = {
+  skillCard: ociSkillCardMinimal
+};
+const ociTrustedInput = {
+  key: "quay.io/octo/hello-world-skill:1.0.0-draft",
+  sourceUri: "oci://quay.io/octo/hello-world-skill@sha256:abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
+  digest: "sha256:abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
+};
+const npxDiscoveryEntryFull = {
+  name: "summarize-text",
+  description: "Summarizes input text using an LLM",
+  type: "skill-md"
+};
+const npxFrontmatterFull = {
+  name: "Summarize Text",
+  description: "A skill for summarizing text content",
+  version: "0.2.0",
+  license: "MIT",
+  compatibility: "agent-skills-v0.2",
+  metadata: {
+    version: "0.2.0",
+    author: "Agent Team",
+    tags: ["summarization", "text"],
+    owner: "team-agents",
+    lifecycle: "experimental"
+  }
+};
+const npxDiscoveryEntryMinimal = {
+  name: "basic-skill"
+};
+const npxFrontmatterConflictingVersion = {
+  name: "Version Conflict Skill",
+  metadata: {
+    version: "2.0.0"
+  },
+  version: "1.5.0"
+};
+const npxNativeInputFull = {
+  entry: npxDiscoveryEntryFull,
+  frontmatter: npxFrontmatterFull
+};
+const npxNativeInputConflictingVersion = {
+  entry: npxDiscoveryEntryMinimal,
+  frontmatter: npxFrontmatterConflictingVersion
+};
+const npxNativeInputMinimal = {
+  entry: npxDiscoveryEntryMinimal
+};
+const npxTrustedInput = {
+  key: "summarize-text",
+  sourceUri: "https://registry.example.com/skills/summarize-text/SKILL.md",
+  digest: "sha256:fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210"
+};
 
 exports.invalidFailedWithSkills = invalidFailedWithSkills;
 exports.invalidLoadingWithObservedAt = invalidLoadingWithObservedAt;
@@ -251,8 +360,25 @@ exports.invalidSnapshotDuplicateKeys = invalidSnapshotDuplicateKeys;
 exports.invalidSnapshotNonUtcTimestamp = invalidSnapshotNonUtcTimestamp;
 exports.invalidSnapshotOverlappingKeys = invalidSnapshotOverlappingKeys;
 exports.invalidSnapshotReadyWithFailedKeys = invalidSnapshotReadyWithFailedKeys;
+exports.npxDiscoveryEntryFull = npxDiscoveryEntryFull;
+exports.npxDiscoveryEntryMinimal = npxDiscoveryEntryMinimal;
+exports.npxFrontmatterConflictingVersion = npxFrontmatterConflictingVersion;
+exports.npxFrontmatterFull = npxFrontmatterFull;
+exports.npxNativeInputConflictingVersion = npxNativeInputConflictingVersion;
+exports.npxNativeInputFull = npxNativeInputFull;
+exports.npxNativeInputMinimal = npxNativeInputMinimal;
 exports.npxSource = npxSource;
+exports.npxTrustedInput = npxTrustedInput;
+exports.ociMarkdownFrontmatterConflictingVersion = ociMarkdownFrontmatterConflictingVersion;
+exports.ociMarkdownFrontmatterFull = ociMarkdownFrontmatterFull;
+exports.ociNativeInputConflictingVersion = ociNativeInputConflictingVersion;
+exports.ociNativeInputFull = ociNativeInputFull;
+exports.ociNativeInputMinimal = ociNativeInputMinimal;
+exports.ociSkillCardConflictingVersion = ociSkillCardConflictingVersion;
+exports.ociSkillCardFull = ociSkillCardFull;
+exports.ociSkillCardMinimal = ociSkillCardMinimal;
 exports.ociSource = ociSource;
+exports.ociTrustedInput = ociTrustedInput;
 exports.validFailedSnapshot = validFailedSnapshot;
 exports.validLoadingSnapshot = validLoadingSnapshot;
 exports.validNpxRecordFull = validNpxRecordFull;