@norskvideo/ctl-sdk 0.1.0

package/fonts/Geist-LICENSE.txt

@@ -0,0 +1,92 @@
+Copyright (c) 2023 Vercel, in collaboration with basement.studio
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/fonts/README.md

@@ -0,0 +1,21 @@
+# Vendored fonts
+
+`Geist.woff2` and `GeistMono.woff2` are **Geist Sans** and **Geist Mono**
+(single variable files, weights 100–900), from Vercel's `geist` package
+(v1.7.2). They back `../base.css`'s two `@font-face` rules and its
+`--font-sans` / `--font-mono` theme tokens.
+
+They are vendored here — not pulled from a CDN or an npm dependency — and live
+in `@product/sdk` so every product frontend gets them from one place via
+`@import "@product/sdk/base.css"`, never its own copy.
+
+**Norsk Studio must ship the byte-identical Geist files.** Studio vendors its own
+copies under `workspaces/core/static/`. For them to hash-match these, both repos
+must obtain the woff2 the same way (the npm-prebuilt route below) — see
+[`STUDIO-FONT-SYNC.md`](./STUDIO-FONT-SYNC.md) for the cross-repo handoff. Keep
+them in sync: if either bumps Geist, update the other.
+
+To refresh: `npm pack geist`, then copy `dist/fonts/geist-sans/Geist-Variable.woff2`
+→ `Geist.woff2` and `dist/fonts/geist-mono/GeistMono-Variable.woff2` → `GeistMono.woff2`.
+
+Licensed under the SIL Open Font License 1.1 — see `Geist-LICENSE.txt`.

package/fonts/STUDIO-FONT-SYNC.md

@@ -0,0 +1,86 @@
+# Font sync: norsk-ctl ↔ Norsk Studio (handoff)
+
+Goal: **one canonical pair of Geist woff2 files, byte-identical in both repos**,
+so norsk-ctl and Norsk Studio render the same glyphs — in the live UIs and in
+generated doc screenshots.
+
+## How norsk-ctl produced its woff2 (the answer to "which method")
+
+**Not** built from Glyphs/UFO sources, **not** subsetted, **not** converted from
+TTF. norsk-ctl vendors the **prebuilt woff2 that ship inside the `geist` npm
+package, pinned to `geist@1.7.2`, unmodified** (a plain file copy). Those files
+are Vercel's own official prebuilt woff2 for that release.
+
+```
+geist@1.7.2 (npm)
+  dist/fonts/geist-sans/Geist-Variable.woff2   → vendored as Geist.woff2
+  dist/fonts/geist-mono/GeistMono-Variable.woff2 → vendored as GeistMono.woff2
+  LICENSE.txt                                   → vendored as Geist-LICENSE.txt
+```
+
+Both are single **variable** files (weights 100–900, upright roman — no separate
+italic axis file). Verified: the vendored files' sha256 equals the npm package's
+files exactly (unaltered by the copy).
+
+## Canonical bytes (verify after dropping in)
+
+| file              | sha256                                                             | size  |
+| ----------------- | ------------------------------------------------------------------ | ----- |
+| `Geist.woff2`     | `a369fcf5628ea2aa4e1b9e2ec6a5b3624e365bda588e1f0f2f12b564f728fbb8` | 69652 |
+| `GeistMono.woff2` | `fba8f577f38a2bbcbe818efa6348dd58f36303a10b8737c42fefad275be563ab` | 71368 |
+
+Your current Studio files differ (`3bc49040…` / `61cd31b3…`, ~71 KB / ~74 KB)
+because they came from `vercel/geist-font@main`'s TTF run through
+`npx ttf2woff2`. That's why the glyphs match but the bytes don't: a git-`main`
+snapshot (moving target) plus a local TTF→woff2 conversion whose output bytes
+depend on the ttf2woff2/woff2 encoder version — neither reproducible against a
+tagged release.
+
+## Recommendation: adopt norsk-ctl's files as canonical
+
+The npm-prebuilt route wins on reproducibility: a **pinned release tag**
+(`geist@1.7.2`), Vercel's **official** encoder output, and **no local
+conversion** step to drift. Please drop in the two files above (identical to
+what's in norsk-ctl at `packages/sdk/src/fonts/`) and re-verify your render.
+After that both repos should hash-match.
+
+### Reproduce it yourself (instead of copying)
+
+```sh
+npm pack geist@1.7.2 && tar -xzf geist-1.7.2.tgz
+cp package/dist/fonts/geist-sans/Geist-Variable.woff2   Geist.woff2
+cp package/dist/fonts/geist-mono/GeistMono-Variable.woff2 GeistMono.woff2
+cp package/LICENSE.txt Geist-LICENSE.txt
+shasum -a 256 Geist.woff2 GeistMono.woff2   # must match the table above
+```
+
+To bump Geist later: change the pinned version in **both** repos together, copy
+the new prebuilt woff2 the same way, and re-hash. Don't hand-convert from TTF.
+
+## The CSS side (already aligned — for reference)
+
+Studio's `@font-face` rules (`static/tailwind.css`) already match norsk-ctl's on
+family name, weight range, and `font-display` — only the `src` path differs by
+necessity, and that's fine:
+
+- **Studio** serves the file statically, so it references an absolute path:
+  `src: url("/static/Geist.woff2") format("woff2-variations"), url("/static/Geist.woff2") format("woff2")`.
+- **norsk-ctl** bundles via Vite, so `base.css` uses a relative path
+  (`url("./fonts/Geist.woff2")`) which Vite hashes into `dist/assets/`.
+
+Same for the theme tokens — keep these identical in both:
+
+```css
+--font-sans: "Geist", ui-sans-serif, system-ui, sans-serif;
+--font-mono: "Geist Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+```
+
+Only the **bytes** need to become identical; the wiring already is.
+
+## Doc screenshots
+
+norsk-ctl regenerates its guide screenshots with `bun run docs:generate`
+(Playwright drives the real UIs, `document.fonts.ready` is awaited before each
+snapshot). Once the canonical files are in place on both sides, regenerate the
+Studio screenshots the equivalent way so the two products look identical
+side-by-side.

package/index.d.ts

@@ -0,0 +1,15 @@
+export * from "./browser.js";
+export * from "./capabilities-router.js";
+export * from "./cjs-interop.js";
+export * from "./dev-url.js";
+export * from "./docker-runner.js";
+export * from "./license-registration.js";
+export * from "./license-stager.js";
+export * from "./license-v2.js";
+export * from "./manifest-fetch.js";
+export * from "./manifest-router.js";
+export * from "./openapi-router.js";
+export * from "./product-health-monitor.js";
+export * from "./product-service.js";
+export * from "./product-template-materials.js";
+export * from "./proxy-middleware.js";

package/index.js

@@ -0,0 +1,17 @@
+// Full surface (Node + browser-safe). For browser-only consumers, import
+// from "@norskvideo/ctl-sdk/browser".
+export * from "./browser.js";
+export * from "./capabilities-router.js";
+export * from "./cjs-interop.js";
+export * from "./dev-url.js";
+export * from "./docker-runner.js";
+export * from "./license-registration.js";
+export * from "./license-stager.js";
+export * from "./license-v2.js";
+export * from "./manifest-fetch.js";
+export * from "./manifest-router.js";
+export * from "./openapi-router.js";
+export * from "./product-health-monitor.js";
+export * from "./product-service.js";
+export * from "./product-template-materials.js";
+export * from "./proxy-middleware.js";

package/license-registration.d.ts

@@ -0,0 +1,52 @@
+import { type Result } from "@norskvideo/ctl-foundation";
+/**
+ * Why a licence could not be staged. Owned here, with the port: the codes are
+ * part of the `LicenseStager` contract, so a host's store implements this union
+ * rather than declaring a parallel one. Literal codes, not `string` — widening
+ * them loses the exhaustiveness that keeps a fatal conflict from silently
+ * becoming a warning when a code is renamed.
+ */
+export type LicenseStageError = {
+    code: "LICENSE_NOT_FOUND";
+    message: string;
+} | {
+    code: "LICENSE_NAME_CONFLICT";
+    message: string;
+} | {
+    code: "LICENSE_UNREADABLE";
+    message: string;
+};
+/**
+ * Copies a licence somewhere the daemon owns, returning the new path. Injected
+ * rather than imported: where to stage is a host concern (norsk-ctl stages
+ * under its config dir, norsk-mgr under its store dir — both via
+ * `makeBasenameLicenseStager`).
+ */
+export type LicenseStager = (sourcePath: string) => Result<string, LicenseStageError>;
+export interface ResolvedLicenseFile {
+    /** The path to record in the registry — staged when staging succeeded. */
+    file: string;
+    /** Non-fatal: registration continues, having recorded the original path. */
+    warning?: string;
+    /** Fatal: registration must not proceed. */
+    fatal?: string;
+}
+/**
+ * Decide which licence path a registration should record.
+ *
+ * The registry's path is read at every launch — `launch-plan` reads
+ * `license.file` and `override-generator` mounts it as the `license.json`
+ * docker secret — so recording the operator's own argument means a licence
+ * under /tmp survives exactly until the box reboots. Staging fixes that.
+ *
+ * Failure is not uniform, so the outcomes are not either:
+ *
+ * - **unreadable / missing** is non-fatal. The daemon runs unprivileged and the
+ *   licence lives wherever the operator put it, so a file readable by docker
+ *   (root, which mounts the secret) but not by us has always registered fine.
+ *   Failing here would regress those installs; warn and record the original.
+ * - **a name conflict is fatal.** Two different licences claiming one staged
+ *   filename cannot both be honoured, and silently overwriting would change the
+ *   entitlement of every product already referencing it.
+ */
+export declare function resolveLicenseFile(file: string, stage: LicenseStager | undefined): ResolvedLicenseFile;

package/license-registration.js

@@ -0,0 +1,38 @@
+import { assertNever } from "@norskvideo/ctl-foundation";
+/**
+ * Decide which licence path a registration should record.
+ *
+ * The registry's path is read at every launch — `launch-plan` reads
+ * `license.file` and `override-generator` mounts it as the `license.json`
+ * docker secret — so recording the operator's own argument means a licence
+ * under /tmp survives exactly until the box reboots. Staging fixes that.
+ *
+ * Failure is not uniform, so the outcomes are not either:
+ *
+ * - **unreadable / missing** is non-fatal. The daemon runs unprivileged and the
+ *   licence lives wherever the operator put it, so a file readable by docker
+ *   (root, which mounts the secret) but not by us has always registered fine.
+ *   Failing here would regress those installs; warn and record the original.
+ * - **a name conflict is fatal.** Two different licences claiming one staged
+ *   filename cannot both be honoured, and silently overwriting would change the
+ *   entitlement of every product already referencing it.
+ */
+export function resolveLicenseFile(file, stage) {
+    if (!stage)
+        return { file };
+    const staged = stage(file);
+    if (staged.status === "ok")
+        return { file: staged.value };
+    // Switch, not an `if`: adding or renaming a code then fails to compile here
+    // rather than falling through to the non-fatal branch, which would quietly
+    // downgrade a conflict to a warning.
+    switch (staged.error.code) {
+        case "LICENSE_NAME_CONFLICT":
+            return { file, fatal: staged.error.message };
+        case "LICENSE_NOT_FOUND":
+        case "LICENSE_UNREADABLE":
+            return { file, warning: staged.error.message };
+        default:
+            return assertNever(staged.error, "unknown licence stage error");
+    }
+}

package/license-stager.d.ts

@@ -0,0 +1,30 @@
+import { type Result } from "@norskvideo/ctl-foundation";
+import type { LicenseStageError, LicenseStager } from "./license-registration.js";
+/** Bytes the caller already holds, with the operator's filename to key them by. */
+export interface LicenseContent {
+    /** Only the basename steers the destination — see `destinationFor`. */
+    name: string;
+    contents: string;
+}
+export type LicenseContentStager = (source: LicenseContent) => Result<string, LicenseStageError>;
+/**
+ * Basename-keyed licence staging, shared by the hosts (ctl stages under its
+ * config dir, mgr under its store dir). Staging exists because the recorded
+ * path is read at every launch — a path under /tmp survives exactly until the
+ * box reboots.
+ *
+ * Keyed by the operator's own filename, NOT by product — one licence can
+ * entitle several products, so two products sharing a licence must reference
+ * one staged file rather than getting a copy each.
+ */
+export declare function makeBasenameLicenseStager(licensesDir: string): LicenseStager;
+/**
+ * Stage bytes the caller already holds, rather than a path the daemon must
+ * read. The two sides of a registration do not share a filesystem identity:
+ * the daemon runs as its service user and cannot read a licence in the
+ * operator's home directory, while the CLI runs as the operator and can. So
+ * the CLI reads and sends the contents, and this writes the canonical copy
+ * into the dir the daemon already owns — neither side needing a permission it
+ * did not already have.
+ */
+export declare function makeBasenameContentStager(licensesDir: string): LicenseContentStager;

package/license-stager.js

@@ -0,0 +1,118 @@
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { err, ok, tryResult } from "@norskvideo/ctl-foundation";
+/**
+ * A licence is a secret, and once staged the daemon is its only reader: the
+ * docker daemon mounts it as a compose secret and runs as root, so it is
+ * unaffected by this. Operators do not read the staged copy either — they pass
+ * their own file and the CLI, running as them, sends the bytes.
+ */
+const STAGED_MODE = 0o600;
+/**
+ * Where a licence lands, and whether it needs writing at all. Shared by both
+ * stagers so the reuse-vs-conflict rule cannot drift between them.
+ *
+ * Same bytes already there: either a re-registration or a second product on
+ * the same licence. Both are reuse, not conflict.
+ */
+function decideDest(licensesDir, name, sameBytesAtDest) {
+    const dest = join(licensesDir, name);
+    if (!existsSync(dest))
+        return { kind: "write", dest };
+    return sameBytesAtDest(dest) ? { kind: "reuse", dest } : { kind: "conflict", dest };
+}
+function conflictError(dest) {
+    return {
+        code: "LICENSE_NAME_CONFLICT",
+        message: `a different license is already staged at ${dest} — ` +
+            "rename the incoming file, or remove the products still using the staged one. " +
+            "Overwriting it would change the entitlement of every product referencing it.",
+    };
+}
+/**
+ * Basename-keyed licence staging, shared by the hosts (ctl stages under its
+ * config dir, mgr under its store dir). Staging exists because the recorded
+ * path is read at every launch — a path under /tmp survives exactly until the
+ * box reboots.
+ *
+ * Keyed by the operator's own filename, NOT by product — one licence can
+ * entitle several products, so two products sharing a licence must reference
+ * one staged file rather than getting a copy each.
+ */
+export function makeBasenameLicenseStager(licensesDir) {
+    return (sourcePath) => {
+        if (!existsSync(sourcePath)) {
+            return err({ code: "LICENSE_NOT_FOUND", message: `license file not found: ${sourcePath}` });
+        }
+        // The daemon runs unprivileged and the licence lives wherever the operator
+        // put it, so an unreadable source is an expected outcome rather than an
+        // exception: a file readable by docker (root, which mounts it as a compose
+        // secret at launch) but not by us has always registered fine, and throwing
+        // here would turn that into a failed registration. The comparison reads the
+        // source too, so it sits inside the same guard as the copy.
+        return tryResult(() => {
+            // Only the basename may steer the destination — the source path is
+            // operator input, and its directories must not place the copy elsewhere.
+            const decision = decideDest(licensesDir, basename(sourcePath), (dest) => readFileSync(dest).equals(readFileSync(sourcePath)));
+            if (decision.kind === "conflict")
+                throw new StageConflict(decision.dest);
+            if (decision.kind === "reuse")
+                return decision.dest;
+            mkdirSync(licensesDir, { recursive: true });
+            copyFileSync(sourcePath, decision.dest);
+            // copyFileSync carries the source's mode across, which is whatever the
+            // operator's own file happened to be (often 0644).
+            chmodSync(decision.dest, STAGED_MODE);
+            return decision.dest;
+        }, (e) => e instanceof StageConflict
+            ? conflictError(e.dest)
+            : {
+                code: "LICENSE_UNREADABLE",
+                message: `could not stage license ${sourcePath} to ${join(licensesDir, basename(sourcePath))}: ${e instanceof Error ? e.message : String(e)}`,
+            });
+    };
+}
+/** Thrown to carry a conflict out of the tryResult body, where the only other
+ *  exit is an I/O failure. Never escapes this module. */
+class StageConflict extends Error {
+    dest;
+    constructor(dest) {
+        super("license name conflict");
+        this.dest = dest;
+    }
+}
+/**
+ * Stage bytes the caller already holds, rather than a path the daemon must
+ * read. The two sides of a registration do not share a filesystem identity:
+ * the daemon runs as its service user and cannot read a licence in the
+ * operator's home directory, while the CLI runs as the operator and can. So
+ * the CLI reads and sends the contents, and this writes the canonical copy
+ * into the dir the daemon already owns — neither side needing a permission it
+ * did not already have.
+ */
+export function makeBasenameContentStager(licensesDir) {
+    return ({ name, contents }) => {
+        // The name crosses an API boundary. Only its basename may steer the
+        // destination, or a caller could write anywhere the daemon can.
+        const safeName = basename(name);
+        if (safeName === "" || safeName === "." || safeName === "..") {
+            return err({ code: "LICENSE_NOT_FOUND", message: `not a usable license filename: '${name}'` });
+        }
+        const decision = decideDest(licensesDir, safeName, (dest) => readFileSync(dest, "utf-8") === contents);
+        if (decision.kind === "conflict")
+            return err(conflictError(decision.dest));
+        if (decision.kind === "reuse")
+            return ok(decision.dest);
+        return tryResult(() => {
+            mkdirSync(licensesDir, { recursive: true });
+            writeFileSync(decision.dest, contents, { encoding: "utf-8", mode: STAGED_MODE });
+            // mode above applies on creation only; an earlier daemon may have left
+            // a looser one behind on a file we are now overwriting.
+            chmodSync(decision.dest, STAGED_MODE);
+            return decision.dest;
+        }, (e) => ({
+            code: "LICENSE_UNREADABLE",
+            message: `could not stage license to ${decision.dest}: ${e instanceof Error ? e.message : String(e)}`,
+        }));
+    };
+}

package/license-v2.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Norsk Licensing V2 (per-product licenses).
+ *
+ * A V2 license file is a detached-signature envelope
+ * `{format, payload: base64, signature: base64}` where the signature is
+ * RSASSA-PKCS1-v1.5/SHA-256 by the Norsk root key over the exact payload
+ * bytes. The payload grants a list of per-product entitlements
+ * (product name + imageRef + versionConstraint + expiry).
+ *
+ * Anything that is NOT a V2 envelope — today's V1 license JSON, the
+ * "aws"/"gcp" marketplace sentinels, license archives — classifies as
+ * `legacy`. Classification is not acceptance: registration rejects `legacy`
+ * (see `notV2EnvelopeMessage`), while other readers — the CI expiry
+ * classifier, for one — still legitimately read V1 files. The kind survives
+ * precisely so "not an envelope at all" stays distinguishable from "envelope
+ * that failed verification"; the two send an operator to different remedies.
+ *
+ * One trust anchor is embedded: the production root key. A license may
+ * self-declare `nonProduction: true` (still production-signed) which warrants a
+ * "not for production" warning — it is not a separate trust anchor.
+ */
+export declare const LICENSE_V2_FORMAT = "norsk-license-v2";
+/**
+ * Wording for a readable file that is not a V2 envelope. Split rather than
+ * frozen because each door that rejects one needs its own middle clause while
+ * the diagnosis and the remedy must not drift between them: `add` says "at
+ * registration" (which also tells the operator their existing registrations
+ * still launch), renewal will say something else.
+ *
+ * Leads with "not a V2 envelope" deliberately — the same message fires for a
+ * path typo pointing at an HTML page or a truncated download, and those must
+ * not be misdiagnosed as "you have a V1 license".
+ */
+export declare function notV2EnvelopeMessage(doorClause: string): string;
+export type SignedEnvelope = {
+    format: string;
+    payload: string;
+    signature: string;
+};
+export type ProductEntitlement = {
+    product: string;
+    imageRef: string;
+    versionConstraint?: string;
+    expiresAt?: string;
+    featurePacks?: string[];
+    mode?: "signed" | "designer";
+};
+export type LicenseV2Payload = {
+    version: 2;
+    licenseId: string;
+    issuedAt: string;
+    expiry?: string;
+    issuedTo: string;
+    email: string;
+    timeout?: number;
+    nonProduction?: boolean;
+    products: ProductEntitlement[];
+    revocations?: {
+        minIssuedAt?: string;
+        blockedSerials?: string[];
+    };
+};
+export type ParsedLicense = {
+    kind: "v2";
+    license: LicenseV2Payload;
+} | {
+    kind: "legacy";
+} | {
+    kind: "invalid-v2";
+    reason: string;
+};
+export declare function parseLicenseContents(contents: string): ParsedLicense;
+/** How a product entry's image resolves, for previewing before an add. The
+ *  licence carries a repo + versionConstraint but no tag: an exact version or
+ *  sha256 digest is fixed (not editable); a caret range / * / no constraint
+ *  defaults to `latest` and the tag is free to edit (a caret still has to stay
+ *  in band, enforced at add time). */
+export declare function describeProductImage(entry: ProductEntitlement): {
+    image: string;
+    tag: string;
+    editable: boolean;
+};
+/** Split `repo[:tag][@digest]`; a ':' only separates the tag when it appears
+ *  after the last '/' (registry hosts can carry ports). */
+export declare function parseImageRef(ref: string): {
+    repo: string;
+    tag?: string;
+    digest?: string;
+};
+/** Same semantics as the engine's matcher: `*` (or absent) accepts any tag;
+ *  `sha256:...` pins the digest; `^x[.y[.z]]` is a caret semver range over
+ *  the tag; anything else is an exact tag match. Unparseable tags against a
+ *  semver constraint fail closed. */
+export declare function imageRefMatches(entry: ProductEntitlement, presented: string): boolean;
+export type EntitlementCheck = {
+    ok: true;
+    entry: ProductEntitlement;
+    warnings: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+/** Does this V2 license entitle `productName`, optionally pinned to the
+ *  container image being registered? */
+export declare function checkProductEntitlement(parsed: {
+    license: LicenseV2Payload;
+}, productName: string, imageRef: string | undefined, now?: Date): EntitlementCheck;