Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
1b2f4107a3 |
No files matched your search
@@ -29,10 +29,6 @@ trim_trailing_whitespace = false
|
||||
end_of_line = crlf
|
||||
|
||||
[*.cs]
|
||||
# Repository-owned C# sources retain the MIT notice in LICENSE; enforced by the existing build.
|
||||
file_header_template = Copyright (c) 2026 James Maes\nSPDX-License-Identifier: MIT
|
||||
dotnet_diagnostic.IDE0073.severity = warning
|
||||
|
||||
#### Formatting (IDE0055 makes every rule below a build error) ####
|
||||
dotnet_diagnostic.IDE0055.severity = warning
|
||||
dotnet_sort_system_directives_first = true
|
||||
|
||||
@@ -4,7 +4,3 @@
|
||||
*.ico binary
|
||||
*.cmd text eol=crlf
|
||||
*.bat text eol=crlf
|
||||
# Preserve third-party legal files byte-for-byte, including vendor line endings.
|
||||
licenses/** -text -whitespace
|
||||
# The inventory is authored here; only upstream legal documents retain vendor formatting.
|
||||
licenses/windows-sdk-packages.json text eol=lf !whitespace
|
||||
@@ -1,68 +0,0 @@
|
||||
name: build
|
||||
on:
|
||||
push:
|
||||
branches: ['**']
|
||||
tags: ['v*']
|
||||
jobs:
|
||||
windows:
|
||||
uses: self:KofTwentyTwo/ci-workflows/.gitea/workflows/windows.yaml@v1
|
||||
secrets: inherit
|
||||
with:
|
||||
runner: qqq-windows-amd64
|
||||
commands: |
|
||||
$temp = $env:RUNNER_TEMP ?? [IO.Path]::GetTempPath()
|
||||
# Protocol fixtures pinned to the revision the verification expects.
|
||||
$protocol = Join-Path $temp "qqq-print-protocol-$env:GITHUB_RUN_ID"
|
||||
git clone --quiet https://git.kof22.com/QRun-IO/qqq-print-protocol.git $protocol
|
||||
git -C $protocol checkout --quiet ac835f8b9396b641b525669249fdb4a1e2a50c99
|
||||
pwsh -NoProfile -File ./build/Verify.ps1 -ProtocolFixtures (Join-Path $protocol fixtures)
|
||||
pwsh -NoProfile -File ./build/Test-WindowsSdkInventory.ps1 -VerifyPackages
|
||||
pwsh -NoProfile -File ./build/Test-BrandedInstaller.ps1
|
||||
pwsh -NoProfile -File ./build/Test-PackagingInputs.ps1
|
||||
# Unsigned MSIs: the base product plus one branded installer per edition. A vX.Y.Z[-rc.N] tag sets the version.
|
||||
$release = if ($env:GITHUB_REF_TYPE -eq 'tag') { $env:GITHUB_REF_NAME.TrimStart('v') } else { '1.2.1' }
|
||||
$product = $release -replace '-.*$', ''
|
||||
pwsh -NoProfile -File ./build/Build-Installer.ps1 -ProductVersion $product -ReleaseVersion $release
|
||||
$installers = @('QqqPrintAgent')
|
||||
foreach ($folder in Get-ChildItem -LiteralPath editions -Directory | Sort-Object Name) {
|
||||
pwsh -NoProfile -File ./build/Build-Installer.ps1 -ProductVersion $product -ReleaseVersion $release -Edition $folder.Name
|
||||
$installers += (Get-Content -LiteralPath (Join-Path $folder.FullName 'edition.json') -Raw | ConvertFrom-Json).assetPrefix
|
||||
}
|
||||
New-Item -ItemType Directory -Path artifacts/release -Force | Out-Null
|
||||
foreach ($prefix in $installers) {
|
||||
Copy-Item -LiteralPath "artifacts/installer/$prefix-$product-x64.msi" -Destination "artifacts/release/$prefix-v$release-x64.msi"
|
||||
}
|
||||
Copy-Item -LiteralPath build/Install-Branded.ps1, docs/branding.example.json -Destination artifacts/release/
|
||||
# PowerShell scripts: analyzer and Pester rejection-path tests with pinned modules saved to the job's temp directory.
|
||||
$modules = Join-Path $temp "psmodules-$env:GITHUB_RUN_ID"
|
||||
New-Item -ItemType Directory -Force -Path $modules | Out-Null
|
||||
Save-PSResource -Name PSScriptAnalyzer -Version 1.25.0 -Repository PSGallery -TrustRepository -Path $modules
|
||||
Save-PSResource -Name Pester -Version 5.7.1 -Repository PSGallery -TrustRepository -Path $modules
|
||||
$env:PSModulePath = "$modules$([IO.Path]::PathSeparator)$env:PSModulePath"
|
||||
pwsh -NoProfile -File ./build/Analyze-Scripts.ps1
|
||||
Import-Module Pester -RequiredVersion 5.7.1
|
||||
# The Pester suites assert on child processes' exit codes themselves.
|
||||
$PSNativeCommandUseErrorActionPreference = $false
|
||||
$pester = New-PesterConfiguration
|
||||
$pester.Run.Path = @('build/Assert-Coverage.Tests.ps1', 'build/Analyze-Scripts.Tests.ps1', 'build/Install-Branded.Tests.ps1', 'build/Test-WindowsSdkInventory.Tests.ps1')
|
||||
$pester.Run.PassThru = $true
|
||||
if ((Invoke-Pester -Configuration $pester).Result -ne 'Passed') { throw 'Pester tests failed' }
|
||||
artifacts: |
|
||||
artifacts/release/*.msi
|
||||
artifacts/release/Install-Branded.ps1
|
||||
artifacts/release/branding.example.json
|
||||
scripts:
|
||||
uses: self:KofTwentyTwo/ci-workflows/.gitea/workflows/node.yaml@v1
|
||||
with:
|
||||
node-version: '24'
|
||||
uv: true
|
||||
install: npm ci --ignore-scripts --no-audit --no-fund
|
||||
commands: |
|
||||
uv sync --locked
|
||||
uv run --locked --no-sync python .github/scripts/test-script-quality.py
|
||||
uv run --locked --no-sync python .github/scripts/check-script-quality.py
|
||||
npm run typecheck
|
||||
npm run lint
|
||||
python3 .github/scripts/test-source-headers.py
|
||||
python3 .github/scripts/check-source-headers.py
|
||||
node --test tools/virtual-agent/test/virtual-agent.test.mjs
|
||||
@@ -1,6 +1,3 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
name: Bug report
|
||||
description: Something is broken
|
||||
labels: [bug]
|
||||
|
||||
@@ -1,6 +1,3 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
blank_issues_enabled: false
|
||||
contact_links:
|
||||
- name: Report a security vulnerability
|
||||
|
||||
@@ -1,6 +1,3 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
name: Feature request
|
||||
description: Suggest an improvement
|
||||
labels: [enhancement]
|
||||
|
||||
@@ -1,6 +1,3 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
# Dependabot for a KofTwentyTwo repository: copy to .github/dependabot.yml and keep
|
||||
# the ecosystems the repository uses. Updates are grouped weekly. A 7-day cooldown
|
||||
# lets the community catch a compromised release before it reaches us; security
|
||||
|
||||
@@ -1,15 +0,0 @@
|
||||
{
|
||||
"typeCheckingMode": "strict",
|
||||
"pythonVersion": "3.13",
|
||||
"include": [
|
||||
"scripts/*.py"
|
||||
],
|
||||
"reportMissingTypeStubs": "error",
|
||||
"reportUnnecessaryTypeIgnoreComment": "error",
|
||||
"reportImplicitOverride": "error",
|
||||
"exclude": [
|
||||
"**/__pycache__"
|
||||
],
|
||||
"venvPath": "..",
|
||||
"venv": ".venv"
|
||||
}
|
||||
@@ -1,6 +1,3 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
# Categories for GitHub's auto-generated release notes (uses issue/PR labels).
|
||||
changelog:
|
||||
exclude:
|
||||
|
||||
@@ -1,108 +1,53 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
"""Reject missing/malformed CodeQL evidence before enforcing the severity gate."""
|
||||
|
||||
import json
|
||||
import math
|
||||
import os
|
||||
from pathlib import Path
|
||||
from typing import TypedDict
|
||||
|
||||
RuleProperties = TypedDict("RuleProperties", {"security-severity": str | float | None}, total=False)
|
||||
|
||||
|
||||
class Rule(TypedDict):
|
||||
"""Keep the rule identity and optional severity metadata used by the gate."""
|
||||
|
||||
id: str
|
||||
properties: RuleProperties
|
||||
|
||||
|
||||
class Component(TypedDict, total=False):
|
||||
"""Describe CodeQL driver or extension rule metadata."""
|
||||
|
||||
name: str
|
||||
rules: list[Rule]
|
||||
|
||||
|
||||
class Tool(TypedDict, total=False):
|
||||
"""Group the driver and optional extension rule catalogs."""
|
||||
|
||||
driver: Component
|
||||
extensions: list[Component]
|
||||
|
||||
|
||||
class Result(TypedDict, total=False):
|
||||
"""Describe only the result fields consumed by the severity gate."""
|
||||
|
||||
ruleId: str
|
||||
rule: dict[str, str]
|
||||
suppressions: list[object]
|
||||
|
||||
|
||||
class Run(TypedDict, total=False):
|
||||
"""Retain invocation success and findings for one analyzed language."""
|
||||
|
||||
tool: Tool
|
||||
results: list[Result]
|
||||
invocations: list[dict[str, bool]]
|
||||
|
||||
|
||||
class Report(TypedDict, total=False):
|
||||
"""Represent SARIF fields while retaining the explicit runtime validation."""
|
||||
|
||||
version: str
|
||||
runs: list[Run]
|
||||
|
||||
|
||||
MAX_SEVERITY = 10
|
||||
|
||||
|
||||
def check(directory: str | Path, language: str, threshold: float) -> bool: # noqa: PLR0912 -- Keep the ordered evidence checks together; none may be skipped.
|
||||
"""Validate complete CodeQL evidence and report findings at the threshold."""
|
||||
if not math.isfinite(threshold) or not 0 <= threshold <= MAX_SEVERITY:
|
||||
raise ValueError("Invalid security severity threshold")
|
||||
canonical = {"java-kotlin": "java", "javascript-typescript": "javascript", "c-cpp": "cpp"}.get(language, language)
|
||||
files = sorted(Path(directory).glob("*.sarif"))
|
||||
if not canonical or not any(path.name == canonical + ".sarif" for path in files):
|
||||
raise ValueError("Missing expected CodeQL SARIF report for " + language)
|
||||
blocking: list[tuple[float, str]] = []
|
||||
for path in files:
|
||||
report: Report = json.loads(path.read_text(encoding="utf-8"))
|
||||
runs = report.get("runs")
|
||||
if report.get("version") != "2.1.0" or not isinstance(runs, list) or not runs:
|
||||
raise ValueError("Invalid or empty SARIF runs: " + path.name)
|
||||
for run in runs:
|
||||
driver = run.get("tool", {}).get("driver", {})
|
||||
results = run.get("results")
|
||||
if driver.get("name") != "CodeQL" or not isinstance(driver.get("rules"), list) or not isinstance(results, list):
|
||||
raise ValueError("Missing CodeQL tool/rules/results evidence: " + path.name)
|
||||
rules: dict[str, Rule] = {}
|
||||
for component in [driver, *run.get("tool", {}).get("extensions", [])]:
|
||||
for rule in component.get("rules", []):
|
||||
rules[rule["id"]] = rule
|
||||
if not rules:
|
||||
raise ValueError("CodeQL report has no analyzed rule metadata: " + path.name)
|
||||
for invocation in run.get("invocations", []):
|
||||
if invocation.get("executionSuccessful") is False:
|
||||
raise ValueError("CodeQL invocation failed: " + path.name)
|
||||
for result in results:
|
||||
rule_id = result.get("ruleId") or result.get("rule", {}).get("id")
|
||||
if rule_id not in rules:
|
||||
raise ValueError("Result references missing rule metadata: " + path.name)
|
||||
if result.get("suppressions"):
|
||||
continue
|
||||
severity = float(rules[rule_id].get("properties", {}).get("security-severity", 0) or 0)
|
||||
if not math.isfinite(severity) or not 0 <= severity <= MAX_SEVERITY:
|
||||
raise ValueError("Invalid rule severity: " + rule_id)
|
||||
if severity >= threshold:
|
||||
blocking.append((severity, rule_id))
|
||||
for severity, rule_id in sorted(blocking, reverse=True):
|
||||
print(f"::error title=CodeQL security finding::{rule_id} ({severity})")
|
||||
print(f"Validated {len(files)} SARIF report(s); {len(blocking)} blocking result(s)")
|
||||
return bool(blocking)
|
||||
def check(directory, language, threshold):
|
||||
if not math.isfinite(threshold) or not 0 <= threshold <= 10:
|
||||
raise ValueError("Invalid security severity threshold")
|
||||
canonical = {"java-kotlin": "java", "javascript-typescript": "javascript", "c-cpp": "cpp"}.get(language, language)
|
||||
files = sorted(Path(directory).glob("*.sarif"))
|
||||
if not canonical or not any(path.name == canonical + ".sarif" for path in files):
|
||||
raise ValueError("Missing expected CodeQL SARIF report for " + language)
|
||||
blocking = []
|
||||
for path in files:
|
||||
report = json.loads(path.read_text(encoding="utf-8"))
|
||||
runs = report.get("runs")
|
||||
if report.get("version") != "2.1.0" or not isinstance(runs, list) or not runs:
|
||||
raise ValueError("Invalid or empty SARIF runs: " + path.name)
|
||||
for run in runs:
|
||||
driver = run.get("tool", {}).get("driver", {})
|
||||
results = run.get("results")
|
||||
if driver.get("name") != "CodeQL" or not isinstance(driver.get("rules"), list) or not isinstance(results, list):
|
||||
raise ValueError("Missing CodeQL tool/rules/results evidence: " + path.name)
|
||||
rules = {}
|
||||
for component in [driver, *run.get("tool", {}).get("extensions", [])]:
|
||||
for rule in component.get("rules", []):
|
||||
rules[rule["id"]] = rule
|
||||
if not rules:
|
||||
raise ValueError("CodeQL report has no analyzed rule metadata: " + path.name)
|
||||
for invocation in run.get("invocations", []):
|
||||
if invocation.get("executionSuccessful") is False:
|
||||
raise ValueError("CodeQL invocation failed: " + path.name)
|
||||
for result in results:
|
||||
rule_id = result.get("ruleId") or result.get("rule", {}).get("id")
|
||||
if rule_id not in rules:
|
||||
raise ValueError("Result references missing rule metadata: " + path.name)
|
||||
if result.get("suppressions"):
|
||||
continue
|
||||
severity = float(rules[rule_id].get("properties", {}).get("security-severity", 0) or 0)
|
||||
if not math.isfinite(severity) or not 0 <= severity <= 10:
|
||||
raise ValueError("Invalid rule severity: " + rule_id)
|
||||
if severity >= threshold:
|
||||
blocking.append((severity, rule_id))
|
||||
for severity, rule_id in sorted(blocking, reverse=True):
|
||||
print(f"::error title=CodeQL security finding::{rule_id} ({severity})")
|
||||
print(f"Validated {len(files)} SARIF report(s); {len(blocking)} blocking result(s)")
|
||||
return bool(blocking)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(1 if check(os.environ["SARIF_DIR"], os.environ["EXPECTED_LANGUAGE"], float(os.environ["THRESHOLD"])) else 0)
|
||||
raise SystemExit(1 if check(os.environ["SARIF_DIR"], os.environ["EXPECTED_LANGUAGE"], float(os.environ["THRESHOLD"])) else 0)
|
||||
@@ -1,104 +1,56 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
"""Require scanner evidence for every resolved NuGet lock-file dependency."""
|
||||
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from typing import TypedDict
|
||||
import sys
|
||||
|
||||
|
||||
class LockedPackage(TypedDict, total=False):
|
||||
"""Describe the resolved NuGet fields consumed by inventory comparison."""
|
||||
|
||||
type: str
|
||||
resolved: str
|
||||
def expected_packages(root):
|
||||
packages = set()
|
||||
for path in Path(root).rglob("packages.lock.json"):
|
||||
if any(part in {"bin", "obj", ".git", ".trivycache"} for part in path.parts):
|
||||
continue
|
||||
lock = json.loads(path.read_text(encoding="utf-8-sig"))
|
||||
for framework in lock.get("dependencies", {}).values():
|
||||
for name, package in framework.items():
|
||||
if package.get("type", "").lower() == "project":
|
||||
continue
|
||||
version = package.get("resolved")
|
||||
if not isinstance(version, str) or not version:
|
||||
raise ValueError("Missing resolved NuGet version in " + str(path))
|
||||
packages.add((name.lower(), version))
|
||||
required = {"microsoft.data.sqlite.core", "microsoft.windowsappsdk", "koftwentytwo.appkit.winui"}
|
||||
if not required.issubset({name for name, _ in packages}):
|
||||
raise ValueError("Expected application NuGet lock graph is missing")
|
||||
return packages
|
||||
|
||||
|
||||
class Lock(TypedDict, total=False):
|
||||
"""Map framework names to their resolved dependency entries."""
|
||||
|
||||
dependencies: dict[str, dict[str, LockedPackage]]
|
||||
def check(mode, report_path, root):
|
||||
expected = expected_packages(root)
|
||||
report = json.loads(Path(report_path).read_text(encoding="utf-8"))
|
||||
if mode == "trivy":
|
||||
packages = [package for result in report.get("Results", []) for package in result.get("Packages", [])]
|
||||
actual = {(package.get("Name", "").lower(), package.get("Version")) for package in packages}
|
||||
elif mode == "sbom":
|
||||
if report.get("bomFormat") != "CycloneDX":
|
||||
raise ValueError("Expected a CycloneDX SBOM")
|
||||
packages = report.get("components", [])
|
||||
actual = {(package.get("name", "").lower(), package.get("version")) for package in packages
|
||||
if package.get("purl", "").lower().startswith("pkg:nuget/")}
|
||||
else:
|
||||
raise ValueError("Unknown inventory mode")
|
||||
missing = expected - actual
|
||||
if missing:
|
||||
raise ValueError(f"Scanner omitted {len(missing)} resolved NuGet package/version(s): {sorted(missing)[:10]}")
|
||||
print(f"Validated {mode} inventory: all {len(expected)} resolved NuGet package/version(s) present")
|
||||
|
||||
|
||||
class Package(TypedDict, total=False):
|
||||
"""Describe the Trivy and CycloneDX coordinate spellings."""
|
||||
|
||||
Name: str
|
||||
Version: str
|
||||
name: str
|
||||
version: str
|
||||
purl: str
|
||||
|
||||
|
||||
class Result(TypedDict, total=False):
|
||||
"""Hold packages analyzed in one Trivy result."""
|
||||
|
||||
Packages: list[Package]
|
||||
|
||||
|
||||
class Report(TypedDict, total=False):
|
||||
"""Describe the supported scanner inventories without changing validation."""
|
||||
|
||||
Results: list[Result]
|
||||
bomFormat: str
|
||||
components: list[Package]
|
||||
|
||||
|
||||
MAX_REPORTED_MISSING = 10
|
||||
OSV_STATUS_ARGUMENT_COUNT = 3
|
||||
|
||||
|
||||
def expected_packages(root: str | Path) -> set[tuple[str, str]]:
|
||||
"""Collect every selected package/version from owned NuGet lock files."""
|
||||
packages: set[tuple[str, str]] = set()
|
||||
for path in Path(root).rglob("packages.lock.json"):
|
||||
if any(part in {"bin", "obj", ".git", ".trivycache"} for part in path.parts):
|
||||
continue
|
||||
lock: Lock = json.loads(path.read_text(encoding="utf-8-sig"))
|
||||
for framework in lock.get("dependencies", {}).values():
|
||||
for name, package in framework.items():
|
||||
if package.get("type", "").lower() == "project":
|
||||
continue
|
||||
version = package.get("resolved")
|
||||
if not isinstance(version, str) or not version:
|
||||
raise ValueError("Missing resolved NuGet version in " + str(path))
|
||||
packages.add((name.lower(), version))
|
||||
required = {"microsoft.data.sqlite.core", "microsoft.windowsappsdk", "koftwentytwo.appkit.winui"}
|
||||
if not required.issubset({name for name, _ in packages}):
|
||||
raise ValueError("Expected application NuGet lock graph is missing")
|
||||
return packages
|
||||
|
||||
|
||||
def check(mode: str, report_path: str | Path, root: str | Path) -> None:
|
||||
"""Require the report to cover the entire selected NuGet graph."""
|
||||
expected = expected_packages(root)
|
||||
report: Report = json.loads(Path(report_path).read_text(encoding="utf-8"))
|
||||
if mode == "trivy":
|
||||
packages = [package for result in report.get("Results", []) for package in result.get("Packages", [])]
|
||||
actual = {(package.get("Name", "").lower(), package.get("Version")) for package in packages}
|
||||
elif mode == "sbom":
|
||||
if report.get("bomFormat") != "CycloneDX":
|
||||
raise ValueError("Expected a CycloneDX SBOM")
|
||||
packages = report.get("components", [])
|
||||
actual = {(package.get("name", "").lower(), package.get("version")) for package in packages if package.get("purl", "").lower().startswith("pkg:nuget/")}
|
||||
else:
|
||||
raise ValueError("Unknown inventory mode")
|
||||
missing = expected - actual
|
||||
if missing:
|
||||
raise ValueError(f"Scanner omitted {len(missing)} resolved NuGet package/version(s): {sorted(missing)[:MAX_REPORTED_MISSING]}")
|
||||
print(f"Validated {mode} inventory: all {len(expected)} resolved NuGet package/version(s) present")
|
||||
|
||||
|
||||
def check_osv_status(status: int) -> None:
|
||||
"""Accept only successful OSV scans, including scans reporting findings."""
|
||||
if status not in (0, 1):
|
||||
raise ValueError(f"OSV failed or reported no packages (exit {status})")
|
||||
def check_osv_status(status):
|
||||
if status not in (0, 1):
|
||||
raise ValueError(f"OSV failed or reported no packages (exit {status})")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
if len(sys.argv) == OSV_STATUS_ARGUMENT_COUNT and sys.argv[1] == "osv-status":
|
||||
check_osv_status(int(sys.argv[2]))
|
||||
else:
|
||||
check(*sys.argv[1:])
|
||||
if len(sys.argv) == 3 and sys.argv[1] == "osv-status":
|
||||
check_osv_status(int(sys.argv[2]))
|
||||
else:
|
||||
check(*sys.argv[1:])
|
||||
@@ -1,144 +0,0 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
"""Fail closed unless every tracked owned script is covered by, and really analyzed by, the quality tools."""
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
import re
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path, PurePosixPath
|
||||
from typing import Any
|
||||
|
||||
PYTHON_SUFFIXES = (".py", ".pyi", ".pyw")
|
||||
SCRIPT_PATTERN = ".github/scripts/*.py"
|
||||
PYRIGHT_CONFIG = ".github"
|
||||
JAVASCRIPT_SUFFIXES = (".js", ".cjs", ".mjs", ".jsx", ".ts", ".mts", ".cts", ".tsx")
|
||||
# EX-0015: the only npm package whose license classification the PR gate may exempt (the matcher ignores versions, so this guard pins it).
|
||||
URI_JS_PURL = "pkg:npm/uri-js"
|
||||
URI_JS_VERSION = "4.4.1"
|
||||
URI_JS_INTEGRITY = "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg=="
|
||||
URI_JS_LICENSE_SHA256 = "0af366eff4c01ec147c9c61ea9e8ffad64a4294754c9d79355f3fd1b97cb2fb9"
|
||||
PR_GATES = ".github/workflows/pr-gates.yml"
|
||||
# Microsoft's official npm Pyright, restored from package-lock.json by `npm ci --ignore-scripts`.
|
||||
PYRIGHT_ENTRY = Path(__file__).resolve().parents[2] / "node_modules" / "pyright" / "index.js"
|
||||
|
||||
|
||||
def tracked_files(root: Path) -> list[str]:
|
||||
"""List tracked and not-yet-ignored new paths so no source file can silently bypass the gates."""
|
||||
# Fixed Git inventory operation; the root is an argument, never shell input.
|
||||
output = subprocess.run(["git", "-C", str(root), "ls-files", "-z", "--cached", "--others", "--exclude-standard"], check=True, capture_output=True).stdout.decode("utf-8") # noqa: S603, S607 -- Resolve Git from the developer/CI PATH; no shell or user-supplied command.
|
||||
return [name for name in output.split("\u0000") if name]
|
||||
|
||||
|
||||
def python_scope(tracked: list[str]) -> list[str]:
|
||||
"""Return the tracked Python sources, rejecting any outside the one checked script root."""
|
||||
candidates = sorted(name for name in tracked if name.endswith(PYTHON_SUFFIXES))
|
||||
outside = [name for name in candidates if not PurePosixPath(name).full_match(SCRIPT_PATTERN)]
|
||||
if outside:
|
||||
raise ValueError("Tracked Python outside the checked script root: " + ", ".join(outside))
|
||||
if not candidates:
|
||||
raise ValueError("No owned Python scripts selected")
|
||||
return candidates
|
||||
|
||||
|
||||
def javascript_scope(root: Path, tracked: list[str]) -> list[str]:
|
||||
"""Return tracked JavaScript/TypeScript sources, rejecting any outside the tsconfig include list."""
|
||||
candidates = sorted(name for name in tracked if name.endswith(JAVASCRIPT_SUFFIXES))
|
||||
tsconfig = root / "tsconfig.json"
|
||||
if not tsconfig.is_file():
|
||||
if candidates:
|
||||
raise ValueError("Tracked JavaScript/TypeScript without a tsconfig.json: " + ", ".join(candidates))
|
||||
return []
|
||||
includes: list[str] = json.loads(tsconfig.read_text(encoding="utf-8"))["include"]
|
||||
outside = [name for name in candidates if not any(PurePosixPath(name).full_match(pattern) for pattern in includes)]
|
||||
if outside:
|
||||
raise ValueError("Tracked JavaScript/TypeScript outside the tsconfig include list: " + ", ".join(outside))
|
||||
if not candidates:
|
||||
raise ValueError("No owned JavaScript sources selected")
|
||||
return candidates
|
||||
|
||||
|
||||
def run_pyright(root: Path, config: str) -> dict[str, Any]:
|
||||
"""Run the locked npm Pyright through Node with JSON output and return its full report."""
|
||||
node = shutil.which("node")
|
||||
if node is None:
|
||||
raise ValueError("Node.js is required to run the locked Pyright")
|
||||
if not PYRIGHT_ENTRY.is_file():
|
||||
raise ValueError(f"Locked Pyright is missing; run npm ci --ignore-scripts ({PYRIGHT_ENTRY})")
|
||||
# Resolved Node and locked entry script; the config is an argument, never shell input.
|
||||
completed = subprocess.run([node, str(PYRIGHT_ENTRY), "-p", config, "--outputjson"], cwd=root, check=False, capture_output=True, text=True, encoding="utf-8") # noqa: S603 -- Resolved Node and locked entry script; no shell.
|
||||
try:
|
||||
report: dict[str, Any] = json.loads(completed.stdout[completed.stdout.index("{") :])
|
||||
int(report["summary"]["filesAnalyzed"]) # Fail here when the summary shape is missing.
|
||||
report["exitCode"] = completed.returncode
|
||||
except (ValueError, KeyError) as error:
|
||||
raise ValueError(f"Pyright produced no JSON summary (exit {completed.returncode}): {completed.stdout}{completed.stderr}") from error
|
||||
return report
|
||||
|
||||
|
||||
def check_pyright_report(report: dict[str, Any], expected: int) -> None:
|
||||
"""Require the analyzed-file count to match the selected sources, with no errors or warnings."""
|
||||
summary = report["summary"]
|
||||
analyzed = summary["filesAnalyzed"]
|
||||
if analyzed == 0 or analyzed != expected:
|
||||
raise ValueError(f"Pyright analyzed {analyzed} files, expected {expected}")
|
||||
if summary["errorCount"] or summary["warningCount"]:
|
||||
details = [f"{item['file']}: {item['message']}" for item in report["generalDiagnostics"]]
|
||||
raise ValueError("Pyright reported findings:\n" + "\n".join(details))
|
||||
if report["exitCode"] != 0:
|
||||
raise ValueError(f"Pyright exited {report['exitCode']} despite a clean summary")
|
||||
|
||||
|
||||
def run_ruff(root: Path, arguments: list[str], sources: list[str]) -> None:
|
||||
"""Run Ruff on the explicit source list so no selected file can be skipped."""
|
||||
# Fixed interpreter module invocation; paths are arguments, never shell input.
|
||||
if subprocess.run([sys.executable, "-m", "ruff", *arguments, "--no-cache", *sources], cwd=root, check=False).returncode != 0: # noqa: S603 -- Fixed interpreter and module; no shell.
|
||||
raise ValueError("Ruff " + " ".join(arguments) + " failed")
|
||||
|
||||
|
||||
def check_uri_js_exception(root: Path) -> None:
|
||||
"""Allow the EX-0015 license exception only for the reviewed, unmodified, development-only uri-js."""
|
||||
packages: dict[str, dict[str, Any]] = json.loads((root / "package-lock.json").read_text(encoding="utf-8"))["packages"]
|
||||
copies = [entry for path, entry in packages.items() if path.rsplit("node_modules/", 1)[-1] == "uri-js"]
|
||||
if len(copies) != 1:
|
||||
raise ValueError(f"EX-0015 covers exactly one locked uri-js copy, found {len(copies)}")
|
||||
if copies[0].get("version") != URI_JS_VERSION or copies[0].get("integrity") != URI_JS_INTEGRITY or copies[0].get("dev") is not True:
|
||||
raise ValueError(f"EX-0015 covers only development-only uri-js {URI_JS_VERSION} with the reviewed integrity")
|
||||
root_entry = packages.get("", {})
|
||||
if "uri-js" in {*root_entry.get("dependencies", {}), *root_entry.get("devDependencies", {})}:
|
||||
raise ValueError("EX-0015 covers uri-js only as a transitive tool dependency, not a direct one")
|
||||
consumers = [path for path, entry in packages.items() if "uri-js" in entry.get("dependencies", {}) and entry.get("dev") is not True]
|
||||
if consumers:
|
||||
raise ValueError("uri-js is required by a non-development package: " + ", ".join(consumers))
|
||||
digest = hashlib.sha256((root / "node_modules" / "uri-js" / "LICENSE").read_bytes()).hexdigest()
|
||||
if digest != URI_JS_LICENSE_SHA256:
|
||||
raise ValueError(f"Installed uri-js LICENSE bytes differ from the reviewed EX-0015 copy ({digest})")
|
||||
caller = [line for line in (root / PR_GATES).read_text(encoding="utf-8").splitlines() if not line.lstrip().startswith("#")]
|
||||
listed = re.findall(r"pkg:npm/[^\s,]+", "\n".join(caller))
|
||||
if listed != [URI_JS_PURL]:
|
||||
raise ValueError(f"EX-0015 permits only {URI_JS_PURL} in allow-dependencies-licenses, found {listed}")
|
||||
|
||||
|
||||
def main() -> None:
|
||||
"""Verify scope, then Ruff format/lint and strict Pyright with a positive analyzed count."""
|
||||
root = Path(__file__).resolve().parents[2]
|
||||
tracked = tracked_files(root)
|
||||
sources = python_scope(tracked)
|
||||
javascript = javascript_scope(root, tracked)
|
||||
run_ruff(root, ["format", "--check"], sources)
|
||||
run_ruff(root, ["check"], sources)
|
||||
report = run_pyright(root, PYRIGHT_CONFIG)
|
||||
check_pyright_report(report, len(sources))
|
||||
check_uri_js_exception(root)
|
||||
print(f"Script quality verified: {len(sources)} Python scripts analyzed by Ruff and Pyright, {len(javascript)} JavaScript files in tsconfig scope")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
try:
|
||||
main()
|
||||
except (ValueError, OSError, subprocess.CalledProcessError) as error:
|
||||
print(str(error), file=sys.stderr)
|
||||
sys.exit(1)
|
||||
@@ -1,130 +0,0 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
"""Check leading notices in explicitly owned, Git-tracked source families."""
|
||||
|
||||
import fnmatch
|
||||
import json
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
|
||||
def selected(name: str, policy: dict[str, Any]) -> bool:
|
||||
"""Select owned paths, honoring documented exact/pattern exclusions first."""
|
||||
if any(fnmatch.fnmatchcase(name, item["pattern"]) for item in policy["exclusions"]):
|
||||
return False
|
||||
return any(fnmatch.fnmatchcase(name, pattern) for pattern in policy["includes"])
|
||||
|
||||
|
||||
def leading_comments(text: str, style: str) -> str: # noqa: PLR0912 -- Each recognized leading-comment syntax has a distinct fail-closed branch.
|
||||
"""Read comments only, preserving required interpreter/XML directive ordering."""
|
||||
text = text.removeprefix("\ufeff")
|
||||
if text.startswith("<?xml"):
|
||||
declaration = re.match(r"<\?xml[^?]*\?>", text)
|
||||
if style != "xml" or declaration is None:
|
||||
raise ValueError("Invalid XML declaration")
|
||||
text = text[declaration.end() :]
|
||||
elif text.startswith("#!"):
|
||||
if style not in ("hash", "powershell", "slash"):
|
||||
raise ValueError("Unexpected interpreter directive")
|
||||
text = text.partition("\n")[2]
|
||||
while re.match(r"#Requires\b", text, re.IGNORECASE):
|
||||
if style != "powershell":
|
||||
raise ValueError("Unexpected PowerShell directive")
|
||||
text = text.partition("\n")[2]
|
||||
comments: list[str] = []
|
||||
while text.strip():
|
||||
text = text.lstrip()
|
||||
if text.startswith("<?xml") or re.match(r"#!|#Requires\b", text, re.IGNORECASE):
|
||||
raise ValueError("Required declaration must precede the notice")
|
||||
if style in ("hash", "powershell") and text.startswith("#"):
|
||||
line, _, text = text.partition("\n")
|
||||
comments.append(line[1:])
|
||||
elif style == "slash" and text.startswith("//"):
|
||||
line, _, text = text.partition("\n")
|
||||
comments.append(line[2:])
|
||||
elif (style == "slash" and text.startswith("/*")) or (style == "xml" and text.startswith("<!--")) or (style == "powershell" and text.startswith("<#")):
|
||||
opening, closing = {"slash": ("/*", "*/"), "xml": ("<!--", "-->"), "powershell": ("<#", "#>")}[style]
|
||||
body, separator, rest = text[len(opening) :].partition(closing)
|
||||
if not separator:
|
||||
raise ValueError("Unterminated leading comment")
|
||||
comments.append(body)
|
||||
text = rest
|
||||
else:
|
||||
break
|
||||
return "\n".join(re.sub(r"^\s*[*~]\s?", "", line).strip() for line in "\n".join(comments).splitlines())
|
||||
|
||||
|
||||
def check_notice(name: str, text: str, policy: dict[str, Any]) -> None:
|
||||
"""Require an approved holder/license pair in real leading comment syntax."""
|
||||
suffix = Path(name).suffix
|
||||
style = policy["styles"].get(suffix)
|
||||
if Path(name).name.startswith("Dockerfile."):
|
||||
style = "hash"
|
||||
if style is None:
|
||||
raise ValueError("Selected path has no configured comment syntax")
|
||||
comments = leading_comments(text, style)
|
||||
approved = [item for item in policy["notices"] if any(fnmatch.fnmatchcase(name, pattern) for pattern in item["paths"])]
|
||||
for notice in approved:
|
||||
holder = re.escape(notice["holder"])
|
||||
copyright_pattern = rf"(?m)^Copyright\s+(?:\([cC]\)\s*)?\d{{4}}(?:[-\u2013]\d{{4}})?\.?\s+{holder}(?:\s+\(KofTwentyTwo\))?\.?(?:\s+Licensed under the MIT License \(see LICENSE\)\.)?$"
|
||||
if re.search(copyright_pattern, comments) is None:
|
||||
continue
|
||||
spdx = re.findall(r"(?m)^SPDX-License-Identifier:\s*(\S+)\s*$", comments)
|
||||
if spdx and any(value != notice["license"] for value in spdx):
|
||||
continue
|
||||
apache = all(
|
||||
phrase in comments
|
||||
for phrase in (
|
||||
"Licensed under the Apache License, Version 2.0",
|
||||
"you may not use this file except in compliance with the License.",
|
||||
"https://www.apache.org/licenses/LICENSE-2.0",
|
||||
"WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND",
|
||||
"limitations under the License.",
|
||||
)
|
||||
)
|
||||
if suffix == ".java" and not apache:
|
||||
continue
|
||||
if notice["license"] in spdx or (notice["license"] == "Apache-2.0" and apache):
|
||||
return
|
||||
raise ValueError("Missing or mismatched leading copyright/license notice")
|
||||
|
||||
|
||||
def check_repository(root: Path, policy: dict[str, Any]) -> int:
|
||||
"""Check tracked sources without scanning build outputs or executing source."""
|
||||
# Fixed Git inventory operation; paths are arguments, never shell input.
|
||||
tracked = subprocess.run(["git", "-C", str(root), "ls-files", "-z"], check=True, capture_output=True).stdout.decode("utf-8").split("\u0000") # noqa: S603, S607 -- Resolve Git from the developer/CI PATH; no shell or user-supplied command.
|
||||
failures: list[str] = []
|
||||
count = 0
|
||||
for name in tracked:
|
||||
if not name or not selected(name, policy):
|
||||
continue
|
||||
count += 1
|
||||
try:
|
||||
check_notice(name, (root / name).read_text(encoding="utf-8-sig"), policy)
|
||||
except (ValueError, OSError) as error:
|
||||
failures.append(f"{name}: {error}")
|
||||
if count == 0:
|
||||
raise ValueError("No owned source files selected")
|
||||
if failures:
|
||||
raise ValueError("\n".join(failures))
|
||||
return count
|
||||
|
||||
|
||||
def main() -> None:
|
||||
"""Load the repository-specific reviewed scope and fail CI on a bad notice."""
|
||||
root = Path(__file__).resolve().parents[2]
|
||||
policy = json.loads((root / ".github/source-headers.json").read_text(encoding="utf-8"))
|
||||
count = check_repository(root, policy)
|
||||
print(f"Leading source notices verified: {count} tracked files")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
try:
|
||||
main()
|
||||
except (ValueError, OSError, subprocess.CalledProcessError) as error:
|
||||
print(str(error), file=sys.stderr)
|
||||
sys.exit(1)
|
||||
+102
-128
@@ -1,168 +1,142 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
"""Exercise the exact CI guards using synthetic evidence only."""
|
||||
|
||||
import contextlib
|
||||
import copy
|
||||
import importlib.util
|
||||
import io
|
||||
import importlib.util
|
||||
import json
|
||||
from pathlib import Path
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
from types import ModuleType
|
||||
from typing import Any, cast, override
|
||||
|
||||
|
||||
sys.dont_write_bytecode = True
|
||||
|
||||
|
||||
def load(name: str) -> ModuleType:
|
||||
"""Load the real sibling guard for synthetic evidence tests."""
|
||||
spec = importlib.util.spec_from_file_location(name, Path(__file__).with_name(name + ".py"))
|
||||
assert spec is not None and spec.loader is not None
|
||||
module = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(module)
|
||||
return module
|
||||
def load(name):
|
||||
spec = importlib.util.spec_from_file_location(name, Path(__file__).with_name(name + ".py"))
|
||||
module = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(module)
|
||||
return module
|
||||
|
||||
|
||||
codeql = load("check-codeql-sarif")
|
||||
|
||||
|
||||
class SarifTests(unittest.TestCase):
|
||||
"""Reject incomplete SARIF evidence and preserve severity enforcement."""
|
||||
def setUp(self):
|
||||
self.temporary = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(self.temporary.cleanup)
|
||||
self.directory = Path(self.temporary.name)
|
||||
self.report = {"version": "2.1.0", "runs": [{"tool": {"driver": {"name": "CodeQL", "rules": [{"id": "synthetic", "properties": {"security-severity": "8.0"}}]}}, "results": []}]}
|
||||
|
||||
@override
|
||||
def setUp(self) -> None:
|
||||
"""Create isolated synthetic evidence with cleanup after each test."""
|
||||
self.temporary = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(self.temporary.cleanup)
|
||||
self.directory = Path(self.temporary.name)
|
||||
self.report: dict[str, Any] = {"version": "2.1.0", "runs": [{"tool": {"driver": {"name": "CodeQL", "rules": [{"id": "synthetic", "properties": {"security-severity": "8.0"}}]}}, "results": []}]}
|
||||
def save(self, report):
|
||||
(self.directory / "java.sarif").write_text(json.dumps(report), encoding="utf-8")
|
||||
|
||||
def save(self, report: object) -> None:
|
||||
"""Write the test body as SARIF without validating it first."""
|
||||
(self.directory / "java.sarif").write_text(json.dumps(report), encoding="utf-8")
|
||||
def test_clean_report_with_zero_findings_passes(self):
|
||||
self.save(self.report)
|
||||
self.assertFalse(codeql.check(self.directory, "java-kotlin", 7))
|
||||
|
||||
def test_clean_report_with_zero_findings_passes(self) -> None:
|
||||
"""Verify clean report with zero findings passes."""
|
||||
self.save(self.report)
|
||||
self.assertFalse(codeql.check(self.directory, "java-kotlin", 7))
|
||||
def test_missing_report_or_wrong_language_fails(self):
|
||||
with self.assertRaises(ValueError):
|
||||
codeql.check(self.directory, "java-kotlin", 7)
|
||||
self.save(self.report)
|
||||
with self.assertRaises(ValueError):
|
||||
codeql.check(self.directory, "csharp", 7)
|
||||
|
||||
def test_missing_report_or_wrong_language_fails(self) -> None:
|
||||
"""Verify missing report or wrong language fails."""
|
||||
with self.assertRaises(ValueError):
|
||||
codeql.check(self.directory, "java-kotlin", 7)
|
||||
self.save(self.report)
|
||||
with self.assertRaises(ValueError):
|
||||
codeql.check(self.directory, "csharp", 7)
|
||||
def test_empty_or_malformed_report_fails(self):
|
||||
for text in ["", "{", "null", "[]"]:
|
||||
with self.subTest(text=text):
|
||||
(self.directory / "java.sarif").write_text(text)
|
||||
with self.assertRaises((ValueError, AttributeError)):
|
||||
codeql.check(self.directory, "java-kotlin", 7)
|
||||
|
||||
def test_empty_or_malformed_report_fails(self) -> None:
|
||||
"""Verify empty or malformed report fails."""
|
||||
for text in ["", "{", "null", "[]"]:
|
||||
with self.subTest(text=text):
|
||||
(self.directory / "java.sarif").write_text(text)
|
||||
with self.assertRaises((ValueError, AttributeError)):
|
||||
codeql.check(self.directory, "java-kotlin", 7)
|
||||
def test_missing_runs_tool_rules_or_results_fails(self):
|
||||
variants = [{"version": "2.1.0"}, {"version": "2.1.0", "runs": []}]
|
||||
for field in ["tool", "results"]:
|
||||
bad = copy.deepcopy(self.report)
|
||||
del bad["runs"][0][field]
|
||||
variants.append(bad)
|
||||
bad = copy.deepcopy(self.report)
|
||||
bad["runs"][0]["tool"]["driver"]["rules"] = []
|
||||
variants.append(bad)
|
||||
for bad in variants:
|
||||
with self.subTest(report=bad):
|
||||
self.save(bad)
|
||||
with self.assertRaises(ValueError):
|
||||
codeql.check(self.directory, "java-kotlin", 7)
|
||||
|
||||
def test_missing_runs_tool_rules_or_results_fails(self) -> None:
|
||||
"""Verify missing runs tool rules or results fails."""
|
||||
variants: list[dict[str, Any]] = [{"version": "2.1.0"}, {"version": "2.1.0", "runs": []}]
|
||||
for field in ["tool", "results"]:
|
||||
bad = copy.deepcopy(self.report)
|
||||
del bad["runs"][0][field]
|
||||
variants.append(bad)
|
||||
bad = copy.deepcopy(self.report)
|
||||
bad["runs"][0]["tool"]["driver"]["rules"] = []
|
||||
variants.append(bad)
|
||||
for bad in variants:
|
||||
with self.subTest(report=bad):
|
||||
self.save(bad)
|
||||
with self.assertRaises(ValueError):
|
||||
codeql.check(self.directory, "java-kotlin", 7)
|
||||
def test_high_finding_blocks_and_unknown_rule_fails(self):
|
||||
self.report["runs"][0]["results"] = [{"ruleId": "synthetic"}]
|
||||
self.save(self.report)
|
||||
with contextlib.redirect_stdout(io.StringIO()):
|
||||
self.assertTrue(codeql.check(self.directory, "java-kotlin", 7))
|
||||
self.report["runs"][0]["results"] = [{"ruleId": "missing"}]
|
||||
self.save(self.report)
|
||||
with self.assertRaises(ValueError):
|
||||
codeql.check(self.directory, "java-kotlin", 7)
|
||||
|
||||
def test_high_finding_blocks_and_unknown_rule_fails(self) -> None:
|
||||
"""Verify high finding blocks and unknown rule fails."""
|
||||
self.report["runs"][0]["results"] = [{"ruleId": "synthetic"}]
|
||||
self.save(self.report)
|
||||
with contextlib.redirect_stdout(io.StringIO()):
|
||||
self.assertTrue(codeql.check(self.directory, "java-kotlin", 7))
|
||||
self.report["runs"][0]["results"] = [{"ruleId": "missing"}]
|
||||
self.save(self.report)
|
||||
with self.assertRaises(ValueError):
|
||||
codeql.check(self.directory, "java-kotlin", 7)
|
||||
|
||||
def test_failed_invocation_and_invalid_threshold_fail(self) -> None:
|
||||
"""Verify failed invocation and invalid threshold fail."""
|
||||
self.report["runs"][0]["invocations"] = [{"executionSuccessful": False}]
|
||||
self.save(self.report)
|
||||
with self.assertRaises(ValueError):
|
||||
codeql.check(self.directory, "java-kotlin", 7)
|
||||
with self.assertRaises(ValueError):
|
||||
codeql.check(self.directory, "java-kotlin", float("nan"))
|
||||
def test_failed_invocation_and_invalid_threshold_fail(self):
|
||||
self.report["runs"][0]["invocations"] = [{"executionSuccessful": False}]
|
||||
self.save(self.report)
|
||||
with self.assertRaises(ValueError):
|
||||
codeql.check(self.directory, "java-kotlin", 7)
|
||||
with self.assertRaises(ValueError):
|
||||
codeql.check(self.directory, "java-kotlin", float("nan"))
|
||||
|
||||
|
||||
inventory = load("check-dependency-inventory")
|
||||
|
||||
|
||||
class InventoryTests(unittest.TestCase):
|
||||
"""Exercise selected dependency coverage using isolated synthetic reports."""
|
||||
def setUp(self):
|
||||
self.temporary = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(self.temporary.cleanup)
|
||||
self.root = Path(self.temporary.name)
|
||||
self.names = ["Microsoft.Data.Sqlite.Core", "Microsoft.WindowsAppSDK", "KofTwentyTwo.AppKit.WinUI", "Synthetic.Transitive"]
|
||||
lock = {"dependencies": {"net10": {name: {"type": "Transitive", "resolved": "1.0.0"} for name in self.names}}}
|
||||
(self.root / "packages.lock.json").write_text(json.dumps(lock))
|
||||
self.report = self.root / "report.json"
|
||||
|
||||
@override
|
||||
def setUp(self) -> None:
|
||||
"""Create isolated synthetic evidence with cleanup after each test."""
|
||||
self.temporary = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(self.temporary.cleanup)
|
||||
self.root = Path(self.temporary.name)
|
||||
self.names = ["Microsoft.Data.Sqlite.Core", "Microsoft.WindowsAppSDK", "KofTwentyTwo.AppKit.WinUI", "Synthetic.Transitive"]
|
||||
lock = {"dependencies": {"net10": {name: {"type": "Transitive", "resolved": "1.0.0"} for name in self.names}}}
|
||||
(self.root / "packages.lock.json").write_text(json.dumps(lock))
|
||||
self.report = self.root / "report.json"
|
||||
def test_complete_trivy_inventory_passes_and_missing_package_fails(self):
|
||||
packages = [{"Name": name, "Version": "1.0.0"} for name in self.names]
|
||||
self.report.write_text(json.dumps({"Results": [{"Packages": packages}]}))
|
||||
inventory.check("trivy", self.report, self.root)
|
||||
packages.pop()
|
||||
self.report.write_text(json.dumps({"Results": [{"Packages": packages}]}))
|
||||
with self.assertRaises(ValueError):
|
||||
inventory.check("trivy", self.report, self.root)
|
||||
|
||||
def test_complete_trivy_inventory_passes_and_missing_package_fails(self) -> None:
|
||||
"""Verify complete trivy inventory passes and missing package fails."""
|
||||
packages = [{"Name": name, "Version": "1.0.0"} for name in self.names]
|
||||
self.report.write_text(json.dumps({"Results": [{"Packages": packages}]}))
|
||||
inventory.check("trivy", self.report, self.root)
|
||||
packages.pop()
|
||||
self.report.write_text(json.dumps({"Results": [{"Packages": packages}]}))
|
||||
with self.assertRaises(ValueError):
|
||||
inventory.check("trivy", self.report, self.root)
|
||||
def test_nonempty_sbom_must_contain_expected_nuget_graph(self):
|
||||
packages = [{"name": name, "version": "1.0.0", "purl": "pkg:nuget/" + name + "@1.0.0"} for name in self.names]
|
||||
self.report.write_text(json.dumps({"bomFormat": "CycloneDX", "components": packages}))
|
||||
inventory.check("sbom", self.report, self.root)
|
||||
for components in [[], packages[:1], [{"name": "unrelated", "version": "1", "purl": "pkg:npm/unrelated@1"}]]:
|
||||
with self.subTest(components=components):
|
||||
self.report.write_text(json.dumps({"bomFormat": "CycloneDX", "components": components}))
|
||||
with self.assertRaises(ValueError):
|
||||
inventory.check("sbom", self.report, self.root)
|
||||
|
||||
def test_nonempty_sbom_must_contain_expected_nuget_graph(self) -> None:
|
||||
"""Verify nonempty sbom must contain expected nuget graph."""
|
||||
packages = [{"name": name, "version": "1.0.0", "purl": "pkg:nuget/" + name + "@1.0.0"} for name in self.names]
|
||||
self.report.write_text(json.dumps({"bomFormat": "CycloneDX", "components": packages}))
|
||||
inventory.check("sbom", self.report, self.root)
|
||||
for components in [[], packages[:1], [{"name": "unrelated", "version": "1", "purl": "pkg:npm/unrelated@1"}]]:
|
||||
with self.subTest(components=components):
|
||||
self.report.write_text(json.dumps({"bomFormat": "CycloneDX", "components": components}))
|
||||
with self.assertRaises(ValueError):
|
||||
inventory.check("sbom", self.report, self.root)
|
||||
def test_empty_or_wrong_version_inventory_fails(self):
|
||||
for report in [{}, {"Results": []}, {"Results": [{"Packages": [{"Name": name, "Version": "0.0.0"} for name in self.names]}]}]:
|
||||
with self.subTest(report=report):
|
||||
self.report.write_text(json.dumps(report))
|
||||
with self.assertRaises(ValueError):
|
||||
inventory.check("trivy", self.report, self.root)
|
||||
|
||||
def test_empty_or_wrong_version_inventory_fails(self) -> None:
|
||||
"""Verify empty or wrong version inventory fails."""
|
||||
for report in cast(list[object], [{}, {"Results": []}, {"Results": [{"Packages": [{"Name": name, "Version": "0.0.0"} for name in self.names]}]}]):
|
||||
with self.subTest(report=report):
|
||||
self.report.write_text(json.dumps(report))
|
||||
with self.assertRaises(ValueError):
|
||||
inventory.check("trivy", self.report, self.root)
|
||||
|
||||
def test_osv_empty_inventory_or_engine_failure_is_rejected(self) -> None:
|
||||
"""Verify osv empty inventory or engine failure is rejected."""
|
||||
for status in [0, 1]:
|
||||
inventory.check_osv_status(status)
|
||||
for status in [2, 127, 128]:
|
||||
with self.subTest(status=status), self.assertRaises(ValueError):
|
||||
def test_osv_empty_inventory_or_engine_failure_is_rejected(self):
|
||||
for status in [0, 1]:
|
||||
inventory.check_osv_status(status)
|
||||
for status in [2, 127, 128]:
|
||||
with self.subTest(status=status):
|
||||
with self.assertRaises(ValueError):
|
||||
inventory.check_osv_status(status)
|
||||
|
||||
def test_missing_lock_graph_fails(self) -> None:
|
||||
"""Verify missing lock graph fails."""
|
||||
(self.root / "packages.lock.json").unlink()
|
||||
with self.assertRaises(ValueError):
|
||||
inventory.expected_packages(self.root)
|
||||
def test_missing_lock_graph_fails(self):
|
||||
(self.root / "packages.lock.json").unlink()
|
||||
with self.assertRaises(ValueError):
|
||||
inventory.expected_packages(self.root)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
unittest.main()
|
||||
@@ -1,297 +0,0 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
"""Prove the quality gates reject real violations, using private temporary fixtures and the locked tools."""
|
||||
|
||||
import importlib.util
|
||||
import json
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
from types import ModuleType
|
||||
from typing import Any, override
|
||||
from unittest import mock
|
||||
|
||||
sys.dont_write_bytecode = True
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[2]
|
||||
GOOD_PYTHON = '"""Probe module."""\n\n\ndef add(left: int, right: int) -> int:\n """Add two integers."""\n return left + right\n'
|
||||
UNUSED_IMPORT_PYTHON = '"""Probe module."""\n\nimport os\n\n\ndef add(left: int, right: int) -> int:\n """Add two integers."""\n return left + right\n'
|
||||
TWO_SPACE_PYTHON = '"""Probe module."""\n\n\ndef add(left: int, right: int) -> int:\n """Add two integers."""\n return left + right\n'
|
||||
INCOMPATIBLE_PYTHON = '"""Probe module."""\n\nVALUE: int = "text"\n'
|
||||
UNANNOTATED_PYTHON = '"""Probe module."""\n\n\ndef echo(value):\n """Return the value."""\n return value\n'
|
||||
GOOD_JAVASCRIPT = "export function addNumbers(left, right)\n{\n return left + right;\n}\n"
|
||||
BAD_LAYOUT_JAVASCRIPT = "export function addNumbers(left, right) {\n return left + right\n}\n"
|
||||
GOOD_TYPED_JAVASCRIPT = "/** @type {number} */\nexport const value = 1;\n"
|
||||
INCOMPATIBLE_JAVASCRIPT = '/** @type {number} */\nexport const value = "text";\n'
|
||||
|
||||
|
||||
def load(name: str) -> ModuleType:
|
||||
"""Load the real sibling guard for tests."""
|
||||
spec = importlib.util.spec_from_file_location(name, Path(__file__).with_name(name + ".py"))
|
||||
assert spec is not None and spec.loader is not None
|
||||
module = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(module)
|
||||
return module
|
||||
|
||||
|
||||
guard = load("check-script-quality")
|
||||
|
||||
|
||||
def run(command: list[str], cwd: Path, stdin: str | None = None) -> subprocess.CompletedProcess[str]:
|
||||
"""Run one real tool invocation without a shell and capture its diagnostics."""
|
||||
return subprocess.run(command, cwd=cwd, input=stdin, check=False, capture_output=True, text=True, encoding="utf-8") # noqa: S603 -- Fixed tool paths and private temporary arguments; no shell.
|
||||
|
||||
|
||||
def ruff(arguments: list[str], source: Path) -> subprocess.CompletedProcess[str]:
|
||||
"""Run the locked Ruff with the repository configuration on one private fixture."""
|
||||
return run([sys.executable, "-m", "ruff", *arguments, "--no-cache", "--config", str(ROOT / "ruff.toml"), str(source)], source.parent)
|
||||
|
||||
|
||||
class ScopeTests(unittest.TestCase):
|
||||
"""Reject tracked sources that fall outside the explicit tool roots."""
|
||||
|
||||
def test_python_outside_script_root_is_rejected(self) -> None:
|
||||
"""Reject a tracked Python file outside the script root instead of letting it disappear."""
|
||||
for stray in ("tools/helper.py", ".github/scripts/nested/helper.py", "helper.pyi"):
|
||||
with self.subTest(stray=stray), self.assertRaisesRegex(ValueError, "outside the checked script root"):
|
||||
guard.python_scope([".github/scripts/check-a.py", stray])
|
||||
|
||||
def test_python_scope_returns_sorted_script_root_and_rejects_empty(self) -> None:
|
||||
"""Select only the direct script root, sorted, and reject selecting nothing."""
|
||||
self.assertEqual([".github/scripts/a.py", ".github/scripts/b.py"], guard.python_scope([".github/scripts/b.py", "README.md", ".github/scripts/a.py"]))
|
||||
with self.assertRaisesRegex(ValueError, "No owned Python"):
|
||||
guard.python_scope(["README.md"])
|
||||
|
||||
def test_javascript_requires_tsconfig_include_scope(self) -> None:
|
||||
"""Reject tracked JavaScript outside tsconfig include patterns, including .js/.cjs/.ts."""
|
||||
with tempfile.TemporaryDirectory() as name:
|
||||
root = Path(name)
|
||||
(root / "tsconfig.json").write_text(json.dumps({"include": ["tools/**/*.mjs", "eslint.config.mjs"]}), encoding="utf-8")
|
||||
self.assertEqual(["eslint.config.mjs", "tools/a/b.mjs", "tools/c.mjs"], guard.javascript_scope(root, ["tools/c.mjs", "tools/a/b.mjs", "eslint.config.mjs", "README.md"]))
|
||||
for stray in ("src/z.js", "tools/w.cjs", "tools/v.ts", "tools/u.js"):
|
||||
with self.subTest(stray=stray), self.assertRaisesRegex(ValueError, "outside the tsconfig include list"):
|
||||
guard.javascript_scope(root, ["tools/c.mjs", stray])
|
||||
with self.assertRaisesRegex(ValueError, "No owned JavaScript"):
|
||||
guard.javascript_scope(root, ["README.md"])
|
||||
|
||||
def test_javascript_without_tsconfig_is_rejected(self) -> None:
|
||||
"""Reject JavaScript in a repository that has no tsconfig."""
|
||||
with tempfile.TemporaryDirectory() as name:
|
||||
root = Path(name)
|
||||
self.assertEqual([], guard.javascript_scope(root, ["README.md"]))
|
||||
with self.assertRaisesRegex(ValueError, "without a tsconfig.json"):
|
||||
guard.javascript_scope(root, ["tools/a.mjs"])
|
||||
|
||||
|
||||
class PyrightCountTests(unittest.TestCase):
|
||||
"""Reject Pyright reports that analyzed too few files or found anything."""
|
||||
|
||||
@staticmethod
|
||||
def report(analyzed: int, errors: int = 0, warnings: int = 0) -> dict[str, Any]:
|
||||
"""Build the exact Pyright JSON shape consumed by the guard."""
|
||||
return {"summary": {"filesAnalyzed": analyzed, "errorCount": errors, "warningCount": warnings}, "generalDiagnostics": [{"file": "x.py", "message": "finding"}] * (errors + warnings), "exitCode": 1 if errors or warnings else 0}
|
||||
|
||||
def test_nonzero_exit_fails_even_with_clean_summary(self) -> None:
|
||||
"""Fail a nonzero Pyright exit even when every count is clean."""
|
||||
clean = self.report(4)
|
||||
clean["exitCode"] = 1
|
||||
with self.assertRaisesRegex(ValueError, "exited 1"):
|
||||
guard.check_pyright_report(clean, 4)
|
||||
|
||||
def test_count_must_match_selected_sources(self) -> None:
|
||||
"""Fail zero or mismatched analyzed counts even with no diagnostics."""
|
||||
guard.check_pyright_report(self.report(4), 4)
|
||||
for analyzed in (0, 3, 5):
|
||||
with self.subTest(analyzed=analyzed), self.assertRaisesRegex(ValueError, "analyzed"):
|
||||
guard.check_pyright_report(self.report(analyzed), 4)
|
||||
|
||||
def test_errors_and_warnings_fail(self) -> None:
|
||||
"""Fail on errors and on warnings at the exact count."""
|
||||
for report in (self.report(4, errors=1), self.report(4, warnings=1)):
|
||||
with self.subTest(report=report), self.assertRaisesRegex(ValueError, "reported findings"):
|
||||
guard.check_pyright_report(report, 4)
|
||||
|
||||
|
||||
class RuffProbeTests(unittest.TestCase):
|
||||
"""Run the real locked Ruff on bounded private fixtures."""
|
||||
|
||||
def test_compliant_fixture_passes_and_violations_fail(self) -> None:
|
||||
"""Pass a compliant control and reject unused imports and wrong indentation."""
|
||||
with tempfile.TemporaryDirectory() as name:
|
||||
probe = Path(name) / "probe.py"
|
||||
probe.write_text(GOOD_PYTHON, encoding="utf-8", newline="\n")
|
||||
self.assertEqual(0, ruff(["check"], probe).returncode)
|
||||
self.assertEqual(0, ruff(["format", "--check"], probe).returncode)
|
||||
probe.write_text(UNUSED_IMPORT_PYTHON, encoding="utf-8", newline="\n")
|
||||
unused = ruff(["check", "--output-format", "concise"], probe)
|
||||
self.assertNotEqual(0, unused.returncode)
|
||||
self.assertIn("F401", unused.stdout)
|
||||
probe.write_text(TWO_SPACE_PYTHON, encoding="utf-8", newline="\n")
|
||||
indented = ruff(["format", "--check"], probe)
|
||||
self.assertNotEqual(0, indented.returncode)
|
||||
self.assertIn("would be reformatted", (indented.stdout + indented.stderr).lower())
|
||||
|
||||
|
||||
class PyrightProbeTests(unittest.TestCase):
|
||||
"""Run the real locked Pyright with the repository strict settings on private projects."""
|
||||
|
||||
@staticmethod
|
||||
def project(root: Path, include: list[str] | None = None) -> None:
|
||||
"""Write the repository Pyright config, without its venv location, into a private project."""
|
||||
config: dict[str, Any] = json.loads((ROOT / ".github/pyrightconfig.json").read_text(encoding="utf-8"))
|
||||
del config["venvPath"], config["venv"]
|
||||
if include is not None:
|
||||
config["include"] = include
|
||||
(root / "pyrightconfig.json").write_text(json.dumps(config), encoding="utf-8")
|
||||
|
||||
def test_compliant_control_passes_and_strict_violations_fail(self) -> None:
|
||||
"""Analyze the control once with no findings and reject incompatible and unannotated code."""
|
||||
with tempfile.TemporaryDirectory() as name:
|
||||
root = Path(name)
|
||||
self.project(root)
|
||||
scripts = root / "scripts"
|
||||
scripts.mkdir()
|
||||
probe = scripts / "probe.py"
|
||||
probe.write_text(GOOD_PYTHON, encoding="utf-8", newline="\n")
|
||||
clean = guard.run_pyright(root, ".")
|
||||
self.assertEqual(0, clean["exitCode"])
|
||||
guard.check_pyright_report(clean, 1)
|
||||
clean["exitCode"] = 1
|
||||
with self.assertRaisesRegex(ValueError, "exited 1"):
|
||||
guard.check_pyright_report(clean, 1)
|
||||
probe.write_text(INCOMPATIBLE_PYTHON, encoding="utf-8", newline="\n")
|
||||
report = guard.run_pyright(root, ".")
|
||||
self.assertIn("reportAssignmentType", {item.get("rule") for item in report["generalDiagnostics"]})
|
||||
with self.assertRaisesRegex(ValueError, "reported findings"):
|
||||
guard.check_pyright_report(report, 1)
|
||||
probe.write_text(UNANNOTATED_PYTHON, encoding="utf-8", newline="\n")
|
||||
strict = guard.run_pyright(root, ".")
|
||||
self.assertIn("reportMissingParameterType", {item.get("rule") for item in strict["generalDiagnostics"]})
|
||||
|
||||
def test_missing_locked_pyright_or_node_is_rejected(self) -> None:
|
||||
"""Reject a missing locked Pyright entry or Node instead of silently skipping the type gate."""
|
||||
with tempfile.TemporaryDirectory() as name:
|
||||
root = Path(name)
|
||||
with mock.patch.object(guard, "PYRIGHT_ENTRY", root / "missing.js"), self.assertRaisesRegex(ValueError, "Locked Pyright is missing"):
|
||||
guard.run_pyright(root, ".")
|
||||
with mock.patch.object(guard.shutil, "which", return_value=None), self.assertRaisesRegex(ValueError, "Node.js is required"):
|
||||
guard.run_pyright(root, ".")
|
||||
|
||||
def test_zero_analyzed_files_cannot_pass(self) -> None:
|
||||
"""Reject an empty include and a hidden-directory root config in the wrapper."""
|
||||
with tempfile.TemporaryDirectory() as name:
|
||||
root = Path(name)
|
||||
scripts = root / ".github" / "scripts"
|
||||
scripts.mkdir(parents=True)
|
||||
(scripts / "probe.py").write_text(GOOD_PYTHON, encoding="utf-8", newline="\n")
|
||||
for include in (["nothing/*.py"], [".github/scripts/*.py"]):
|
||||
self.project(root, include)
|
||||
with self.subTest(include=include), self.assertRaises(ValueError):
|
||||
guard.check_pyright_report(guard.run_pyright(root, "."), 1)
|
||||
|
||||
|
||||
class JavaScriptProbeTests(unittest.TestCase):
|
||||
"""Run the real locked ESLint and TypeScript on bounded private input."""
|
||||
|
||||
@override
|
||||
def setUp(self) -> None:
|
||||
"""Skip only where tsconfig is absent, because the scope guard forbids JavaScript there."""
|
||||
if not (ROOT / "tsconfig.json").is_file():
|
||||
self.skipTest("No JavaScript tooling in this repository")
|
||||
node = shutil.which("node")
|
||||
self.assertIsNotNone(node)
|
||||
self.node = str(node)
|
||||
|
||||
def eslint(self, text: str) -> subprocess.CompletedProcess[str]:
|
||||
"""Lint text as an in-scope tool file using the repository configuration."""
|
||||
return run([self.node, str(ROOT / "node_modules/eslint/bin/eslint.js"), "--stdin", "--stdin-filename", "tools/probe.mjs", "--max-warnings", "0", "--format", "json"], ROOT, text)
|
||||
|
||||
def test_eslint_rejects_wrong_layout(self) -> None:
|
||||
"""Pass a compliant control and reject K&R braces, two-space indent and a missing semicolon."""
|
||||
good = self.eslint(GOOD_JAVASCRIPT)
|
||||
self.assertEqual(0, good.returncode, good.stdout + good.stderr)
|
||||
bad = self.eslint(BAD_LAYOUT_JAVASCRIPT)
|
||||
self.assertNotEqual(0, bad.returncode)
|
||||
rules = {message["ruleId"] for message in json.loads(bad.stdout)[0]["messages"]}
|
||||
self.assertLessEqual({"@stylistic/brace-style", "@stylistic/semi", "@stylistic/indent"}, rules)
|
||||
|
||||
def test_checked_javascript_rejects_incompatible_assignment(self) -> None:
|
||||
"""Reject a real incompatible assignment under the repository strict checkJs settings."""
|
||||
with tempfile.TemporaryDirectory() as name:
|
||||
root = Path(name)
|
||||
(root / "tsconfig.json").write_text(json.dumps({"extends": (ROOT / "tsconfig.json").as_posix(), "compilerOptions": {"typeRoots": [(ROOT / "node_modules/@types").as_posix()]}, "include": ["probe.mjs"]}), encoding="utf-8")
|
||||
tsc = [self.node, str(ROOT / "node_modules/typescript/bin/tsc"), "-p", str(root / "tsconfig.json")]
|
||||
(root / "probe.mjs").write_text(GOOD_TYPED_JAVASCRIPT, encoding="utf-8", newline="\n")
|
||||
good = run(tsc, root)
|
||||
self.assertEqual(0, good.returncode, good.stdout + good.stderr)
|
||||
(root / "probe.mjs").write_text(INCOMPATIBLE_JAVASCRIPT, encoding="utf-8", newline="\n")
|
||||
bad = run(tsc, root)
|
||||
self.assertNotEqual(0, bad.returncode)
|
||||
self.assertIn("TS2322", bad.stdout)
|
||||
|
||||
|
||||
URI_GATES = "jobs:\n pr:\n with:\n allow-dependencies-licenses: pkg:npm/uri-js\n"
|
||||
URI_MIXED_GATES = "jobs:\n pr:\n with:\n allow-dependencies-licenses: >-\n pkg:nuget/Microsoft.WindowsAppSDK,\n pkg:npm/uri-js\n"
|
||||
|
||||
|
||||
def uri_lock(version: str = "4.4.1", integrity: str | None = None, dev: bool = True, direct: bool = False, consumer_dev: bool = True) -> dict[str, Any]:
|
||||
"""Build a minimal package-lock shape with uri-js under an ESLint-like consumer."""
|
||||
root_entry: dict[str, Any] = {"devDependencies": {"uri-js": version} if direct else {"eslint": "10.14.0"}}
|
||||
return {"packages": {"": root_entry, "node_modules/uri-js": {"version": version, "integrity": integrity or guard.URI_JS_INTEGRITY, "dev": dev}, "node_modules/eslint": {"dev": consumer_dev, "dependencies": {"uri-js": "^4.2.2"}}}}
|
||||
|
||||
|
||||
def uri_project(root: Path, lock: dict[str, Any], gates: str = URI_GATES, license_bytes: bytes | None = None) -> None:
|
||||
"""Write a private project with the lock, installed LICENSE and PR caller that the guard inspects."""
|
||||
(root / "package-lock.json").write_text(json.dumps(lock), encoding="utf-8")
|
||||
installed = root / "node_modules" / "uri-js"
|
||||
installed.mkdir(parents=True)
|
||||
installed.joinpath("LICENSE").write_bytes((ROOT / "node_modules" / "uri-js" / "LICENSE").read_bytes() if license_bytes is None else license_bytes)
|
||||
workflows = root / ".github" / "workflows"
|
||||
workflows.mkdir(parents=True)
|
||||
(workflows / "pr-gates.yml").write_text("# EX-0015 pkg:npm/uri-js is cited here\n" + gates, encoding="utf-8")
|
||||
|
||||
|
||||
class UriJsExceptionTests(unittest.TestCase):
|
||||
"""Allow the EX-0015 license exception only for the reviewed, unmodified, development-only uri-js."""
|
||||
|
||||
def test_reviewed_uri_js_with_exact_caller_is_accepted(self) -> None:
|
||||
"""Accept the reviewed package, installed license bytes and an exact caller list, mixed with NuGet entries."""
|
||||
for gates in (URI_GATES, URI_MIXED_GATES):
|
||||
with tempfile.TemporaryDirectory() as name, self.subTest(gates=gates):
|
||||
root = Path(name)
|
||||
uri_project(root, uri_lock(), gates)
|
||||
guard.check_uri_js_exception(root)
|
||||
|
||||
def test_other_version_integrity_scope_or_consumer_is_rejected(self) -> None:
|
||||
"""Reject another version, integrity, non-dev or direct use, a non-dev consumer and a second copy."""
|
||||
duplicate = uri_lock()
|
||||
duplicate["packages"]["node_modules/eslint/node_modules/uri-js"] = dict(duplicate["packages"]["node_modules/uri-js"])
|
||||
for lock in (uri_lock(version="4.4.2"), uri_lock(integrity="sha512-other"), uri_lock(dev=False), uri_lock(direct=True), uri_lock(consumer_dev=False), duplicate):
|
||||
with tempfile.TemporaryDirectory() as name, self.subTest(lock=lock), self.assertRaisesRegex(ValueError, "uri-js"):
|
||||
root = Path(name)
|
||||
uri_project(root, lock)
|
||||
guard.check_uri_js_exception(root)
|
||||
|
||||
def test_modified_installed_license_is_rejected(self) -> None:
|
||||
"""Reject installed license bytes that differ from the reviewed copy."""
|
||||
with tempfile.TemporaryDirectory() as name:
|
||||
root = Path(name)
|
||||
uri_project(root, uri_lock(), license_bytes=(ROOT / "node_modules" / "uri-js" / "LICENSE").read_bytes() + b"\n")
|
||||
with self.assertRaisesRegex(ValueError, "LICENSE bytes differ"):
|
||||
guard.check_uri_js_exception(root)
|
||||
|
||||
def test_caller_must_list_only_uri_js(self) -> None:
|
||||
"""Reject a caller that lists no npm exception, another package, a versioned form or a duplicate."""
|
||||
for gates in ("jobs:\n pr:\n uses: shared\n", URI_GATES.rstrip() + ", pkg:npm/other\n", "jobs:\n pr:\n with:\n allow-dependencies-licenses: pkg:npm/other\n", URI_GATES.rstrip() + "@4.4.1\n", URI_GATES.rstrip() + ", pkg:npm/uri-js\n"):
|
||||
with tempfile.TemporaryDirectory() as name, self.subTest(gates=gates), self.assertRaisesRegex(ValueError, "permits only"):
|
||||
root = Path(name)
|
||||
uri_project(root, uri_lock(), gates)
|
||||
guard.check_uri_js_exception(root)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -1,160 +0,0 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
"""Exercise notice parsing, provenance, scope and real Git inventory rejection."""
|
||||
|
||||
import importlib.util
|
||||
import json
|
||||
import subprocess
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
SPEC = importlib.util.spec_from_file_location("headers", Path(__file__).with_name("check-source-headers.py"))
|
||||
assert SPEC is not None and SPEC.loader is not None
|
||||
HEADERS = importlib.util.module_from_spec(SPEC)
|
||||
SPEC.loader.exec_module(HEADERS)
|
||||
POLICY = json.loads(Path(__file__).parents[1].joinpath("source-headers.json").read_text(encoding="utf-8"))
|
||||
MIT = "Copyright (c) 2026 James Maes\nSPDX-License-Identifier: MIT"
|
||||
APACHE = """Copyright (C) 2021-2025. Kingsrook, LLC
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
https://www.apache.org/licenses/LICENSE-2.0
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License."""
|
||||
|
||||
|
||||
def fixture_policy(holder: str = "James Maes", license_id: str = "MIT") -> dict[str, Any]:
|
||||
"""Use the production styles with a small explicit owned fixture scope."""
|
||||
return {"includes": ["src/*"], "exclusions": [], "styles": POLICY["styles"], "notices": [{"holder": holder, "license": license_id, "paths": ["src/*"]}]}
|
||||
|
||||
|
||||
class HeaderTests(unittest.TestCase):
|
||||
"""Ensure policy failures cannot pass through text-only copyright searches."""
|
||||
|
||||
def test_each_real_comment_syntax(self) -> None:
|
||||
"""Recognize hash, slash, block and XML notices in their own languages."""
|
||||
for name, text in (
|
||||
("src/a.py", "# " + MIT.replace("\n", "\n# ") + "\nprint(1)"),
|
||||
("src/a.cs", "// " + MIT.replace("\n", "\n// ") + "\nclass A {}"),
|
||||
("src/a.mjs", "/*\n * " + MIT.replace("\n", "\n * ") + "\n */\nexport {};"),
|
||||
("src/a.xml", "<!--\n" + MIT + "\n-->\n<root/>"),
|
||||
("src/a.ps1", "<#\n" + MIT + "\n#>\nWrite-Output 1"),
|
||||
):
|
||||
with self.subTest(name=name):
|
||||
HEADERS.check_notice(name, text, fixture_policy())
|
||||
|
||||
def test_year_range_separator_is_hyphen_or_en_dash_only(self) -> None:
|
||||
"""Accept a hyphen or en dash between years and reject any other separator."""
|
||||
for separator, accepted in (("-", True), (chr(0x2013), True), ("/", False), (chr(0x2014), False)):
|
||||
text = f"# Copyright 2025{separator}2026 James Maes\n# SPDX-License-Identifier: MIT"
|
||||
with self.subTest(separator=separator):
|
||||
if accepted:
|
||||
HEADERS.check_notice("src/a.py", text, fixture_policy())
|
||||
else:
|
||||
with self.assertRaises(ValueError):
|
||||
HEADERS.check_notice("src/a.py", text, fixture_policy())
|
||||
|
||||
def test_required_first_lines_and_bom(self) -> None:
|
||||
"""Accept shebangs, PowerShell requirements and XML declarations first."""
|
||||
for name, prefix, body in (
|
||||
("src/a.sh", "#!/bin/sh\n", "# " + MIT.replace("\n", "\n# ")),
|
||||
("src/a.ps1", "#Requires -Version 7.4\n", "# " + MIT.replace("\n", "\n# ")),
|
||||
("src/a.xml", '<?xml version="1.0"?>\n', "<!--" + MIT + "--><root/>"),
|
||||
("src/a.mjs", "#!/usr/bin/env node\n", "/*" + MIT + "*/"),
|
||||
):
|
||||
with self.subTest(name=name):
|
||||
HEADERS.check_notice(name, "\ufeff" + prefix + body, fixture_policy())
|
||||
|
||||
def test_misordered_required_first_lines_fail(self) -> None:
|
||||
"""A notice must not displace an interpreter or XML declaration."""
|
||||
for name, text in (
|
||||
("src/a.sh", "# " + MIT.replace("\n", "\n# ") + "\n#!/bin/sh"),
|
||||
("src/a.ps1", "# " + MIT.replace("\n", "\n# ") + "\n#Requires -Version 7.4"),
|
||||
("src/a.xml", "<!--" + MIT + '--><?xml version="1.0"?><root/>'),
|
||||
):
|
||||
with self.subTest(name=name), self.assertRaises(ValueError):
|
||||
HEADERS.check_notice(name, text, fixture_policy())
|
||||
|
||||
def test_code_strings_and_late_comments_do_not_count(self) -> None:
|
||||
"""Reject docstrings and comments after executable declarations."""
|
||||
for text in ('notice = "' + MIT.replace("\n", "\\n") + '"', '"""' + MIT + '"""', "import os\n# " + MIT.replace("\n", "\n# ")):
|
||||
with self.subTest(text=text), self.assertRaises(ValueError):
|
||||
HEADERS.check_notice("src/a.py", text, fixture_policy())
|
||||
|
||||
def test_wrong_syntax_and_unterminated_comments_fail(self) -> None:
|
||||
"""Notice text alone is insufficient without a complete language comment."""
|
||||
for text in ("# " + MIT, "/*" + MIT, 'string text = "' + MIT + '";'):
|
||||
with self.subTest(text=text), self.assertRaises(ValueError):
|
||||
HEADERS.check_notice("src/a.cs", text, fixture_policy())
|
||||
with self.assertRaises(ValueError):
|
||||
HEADERS.check_notice("src/a.py", "<#" + MIT + "#>", fixture_policy())
|
||||
|
||||
def test_wrong_holder_or_license_and_conflicting_spdx_fail(self) -> None:
|
||||
"""Do not conflate repository licenses or accept conflicting identifiers."""
|
||||
for text in (MIT.replace("James Maes", "Someone Else"), MIT.replace("MIT", "Apache-2.0"), MIT + "\nSPDX-License-Identifier: Apache-2.0", MIT.splitlines()[0]):
|
||||
with self.subTest(text=text), self.assertRaises(ValueError):
|
||||
HEADERS.check_notice("src/a.cs", "/*" + text + "*/", fixture_policy())
|
||||
|
||||
def test_complete_legacy_apache_without_spdx(self) -> None:
|
||||
"""Retain valid legacy year ranges and complete Apache notices."""
|
||||
policy = fixture_policy("Kingsrook, LLC", "Apache-2.0")
|
||||
HEADERS.check_notice("src/A.java", "/*" + APACHE + "*/\nclass A {}", policy)
|
||||
HEADERS.check_notice("src/a.xml", "<!--" + APACHE + "--><root/>", policy)
|
||||
|
||||
def test_java_requires_full_apache_block(self) -> None:
|
||||
"""An abbreviated SPDX-only Java notice cannot replace scoped convention."""
|
||||
policy = fixture_policy("Kingsrook, LLC", "Apache-2.0")
|
||||
for notice in ("Copyright 2026 Kingsrook, LLC\nSPDX-License-Identifier: Apache-2.0", APACHE.replace("limitations under the License.", "")):
|
||||
with self.subTest(notice=notice), self.assertRaises(ValueError):
|
||||
HEADERS.check_notice("src/A.java", "/*" + notice + "*/", policy)
|
||||
|
||||
def test_virtual_agent_provenance_is_path_scoped(self) -> None:
|
||||
"""Only the owned virtual-agent family may use its existing QRun.IO holder."""
|
||||
policy = fixture_policy()
|
||||
policy["notices"].append({"holder": "QRun.IO, Inc.", "license": "MIT", "paths": ["tools/virtual-agent/*"]})
|
||||
text = "/*Copyright 2026 QRun.IO, Inc. Licensed under the MIT License (see LICENSE).\nSPDX-License-Identifier: MIT*/"
|
||||
HEADERS.check_notice("tools/virtual-agent/a.mjs", text, policy)
|
||||
with self.assertRaises(ValueError):
|
||||
HEADERS.check_notice("src/a.mjs", text, policy)
|
||||
|
||||
def test_current_scope_and_documented_exclusions(self) -> None:
|
||||
"""New scripts enter the guard; data, generated and upstream files do not."""
|
||||
self.assertTrue(HEADERS.selected(".github/scripts/new-tool.py", POLICY))
|
||||
self.assertTrue(HEADERS.selected(".github/workflows/new-check.yml", POLICY))
|
||||
for name in (".mvn/wrapper/MavenWrapperDownloader.java", "mvnw", "schemas/new.json", "src/main/resources/openapi/new.yaml", "src/test/resources/openapi/old.yaml", "src/generated/Example.cs", "src/Example/obj/Generated.cs", "packages.lock.json"):
|
||||
with self.subTest(name=name):
|
||||
self.assertFalse(HEADERS.selected(name, POLICY))
|
||||
self.assertTrue(all(item["reason"].strip() for item in POLICY["exclusions"]))
|
||||
|
||||
def test_guard_sources_match_this_repository_provenance(self) -> None:
|
||||
"""Check copied guard files against local policy even before Git staging."""
|
||||
for filename in ("check-source-headers.py", "test-source-headers.py"):
|
||||
path = Path(__file__).with_name(filename)
|
||||
name = ".github/scripts/" + filename
|
||||
self.assertTrue(HEADERS.selected(name, POLICY))
|
||||
HEADERS.check_notice(name, path.read_text(encoding="utf-8"), POLICY)
|
||||
|
||||
def test_real_git_inventory_rejects_missing_tracked_header(self) -> None:
|
||||
"""A tracked new source fails while untracked generated output is ignored."""
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
root = Path(directory)
|
||||
subprocess.run(["git", "init", "-q", str(root)], check=True) # noqa: S603, S607 -- Fixed Git command in the owned temporary test directory.
|
||||
root.joinpath("src").mkdir()
|
||||
source = root / "src/a.py"
|
||||
source.write_text("print(1)", encoding="utf-8")
|
||||
subprocess.run(["git", "-C", str(root), "add", "--", "src/a.py"], check=True) # noqa: S603, S607 -- Fixed synthetic path; never a shell command.
|
||||
with self.assertRaisesRegex(ValueError, "src/a.py"):
|
||||
HEADERS.check_repository(root, fixture_policy())
|
||||
source.write_text("# " + MIT.replace("\n", "\n# ") + "\nprint(1)", encoding="utf-8")
|
||||
root.joinpath("src/untracked.py").write_text("print(2)", encoding="utf-8")
|
||||
self.assertEqual(1, HEADERS.check_repository(root, fixture_policy()))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -1,126 +0,0 @@
|
||||
{
|
||||
"description": "Scope of the reviewed 2026-11-01 owned-source notice pass. Python fnmatch patterns match slash-containing relative paths. Native C# IDE0073 and full Java Apache conventions remain in force.",
|
||||
"includes": [
|
||||
".github/*.yml",
|
||||
".github/*.yaml",
|
||||
".github/scripts/*.py",
|
||||
".pre-commit-config.yaml",
|
||||
"Directory.Build.props",
|
||||
"Directory.Packages.props",
|
||||
"PSScriptAnalyzerSettings.psd1",
|
||||
"build/*.ps1",
|
||||
"installer/*.props",
|
||||
"installer/*.wxs",
|
||||
"installer/*.wixproj",
|
||||
"src/*.cs",
|
||||
"src/*.xaml",
|
||||
"src/*.csproj",
|
||||
"tests/*.cs",
|
||||
"tests/*.csproj",
|
||||
"tests/*.ps1",
|
||||
"tools/virtual-agent/*.mjs"
|
||||
],
|
||||
"exclusions": [
|
||||
{
|
||||
"pattern": "*.json",
|
||||
"reason": "Schema, fixtures, manifests and lock data: repository LICENSE/NOTICE, no comments."
|
||||
},
|
||||
{
|
||||
"pattern": "*.lock",
|
||||
"reason": "Dependency lock data, not owned executable source."
|
||||
},
|
||||
{
|
||||
"pattern": "*/generated/*",
|
||||
"reason": "Explicit generated-code directory."
|
||||
},
|
||||
{
|
||||
"pattern": "*/bin/*",
|
||||
"reason": "Generated build output."
|
||||
},
|
||||
{
|
||||
"pattern": "*/obj/*",
|
||||
"reason": "Generated build output."
|
||||
},
|
||||
{
|
||||
"pattern": "*/node_modules/*",
|
||||
"reason": "Third-party dependency output."
|
||||
},
|
||||
{
|
||||
"pattern": ".mvn/*",
|
||||
"reason": "Upstream Maven wrapper provenance."
|
||||
},
|
||||
{
|
||||
"pattern": "mvnw*",
|
||||
"reason": "Upstream Maven wrapper provenance."
|
||||
},
|
||||
{
|
||||
"pattern": "Assets/Legal/*",
|
||||
"reason": "Byte-exact third-party legal files."
|
||||
},
|
||||
{
|
||||
"pattern": "src/main/resources/*",
|
||||
"reason": "Bundled font/legal assets and OpenAPI schema data."
|
||||
},
|
||||
{
|
||||
"pattern": "src/test/resources/openapi/*",
|
||||
"reason": "Historical contract schema fixtures."
|
||||
},
|
||||
{
|
||||
"pattern": "*.slnx",
|
||||
"reason": "Solution metadata outside the completed source-header pass; root LICENSE/NOTICE applies."
|
||||
},
|
||||
{
|
||||
"pattern": "*.manifest",
|
||||
"reason": "Application activation metadata outside this pass; root LICENSE/NOTICE applies."
|
||||
},
|
||||
{
|
||||
"pattern": "*.runsettings",
|
||||
"reason": "Test runner metadata outside this pass; root LICENSE/NOTICE applies."
|
||||
},
|
||||
{
|
||||
"pattern": ".editorconfig",
|
||||
"reason": "Style configuration outside this pass; root LICENSE/NOTICE applies."
|
||||
}
|
||||
],
|
||||
"styles": {
|
||||
".py": "hash",
|
||||
".ps1": "powershell",
|
||||
".psd1": "powershell",
|
||||
".sh": "hash",
|
||||
".yml": "hash",
|
||||
".yaml": "hash",
|
||||
".cs": "slash",
|
||||
".java": "slash",
|
||||
".mjs": "slash",
|
||||
".js": "slash",
|
||||
".xml": "xml",
|
||||
".props": "xml",
|
||||
".csproj": "xml",
|
||||
".wxs": "xml",
|
||||
".wixproj": "xml",
|
||||
".xaml": "xml"
|
||||
},
|
||||
"notices": [
|
||||
{
|
||||
"paths": [
|
||||
".github/*",
|
||||
".pre-commit-config.yaml",
|
||||
"Directory.*.props",
|
||||
"PSScriptAnalyzerSettings.psd1",
|
||||
"build/*",
|
||||
"installer/*",
|
||||
"src/*",
|
||||
"tests/*"
|
||||
],
|
||||
"license": "MIT",
|
||||
"holder": "James Maes"
|
||||
},
|
||||
{
|
||||
"paths": [
|
||||
"tools/virtual-agent/*"
|
||||
],
|
||||
"license": "MIT",
|
||||
"holder": "QRun.IO, Inc."
|
||||
}
|
||||
]
|
||||
}
|
||||
+11
-26
@@ -1,21 +1,18 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
name: ci
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: ['**']
|
||||
branches: [main]
|
||||
pull_request:
|
||||
workflow_dispatch:
|
||||
workflow_call:
|
||||
inputs:
|
||||
product-version:
|
||||
type: string
|
||||
default: '1.2.1'
|
||||
default: '0.1.9'
|
||||
release-version:
|
||||
type: string
|
||||
default: '1.2.1'
|
||||
default: '0.1.9-rc.1'
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
@@ -42,7 +39,7 @@ jobs:
|
||||
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
||||
with:
|
||||
repository: QRun-IO/qqq-print-protocol
|
||||
ref: ac835f8b9396b641b525669249fdb4a1e2a50c99
|
||||
ref: f4f977ca4aa6b749e6a52760eed5e53c99a7704d
|
||||
path: qqq-print-protocol
|
||||
persist-credentials: false
|
||||
- name: Set up .NET
|
||||
@@ -51,37 +48,25 @@ jobs:
|
||||
global-json-file: qqq-print-agent/global.json
|
||||
- name: Locked restore, build and test
|
||||
run: ./build/Verify.ps1
|
||||
- name: Verify exact Windows SDK inventory and notice bytes
|
||||
run: ./build/Test-WindowsSdkInventory.ps1 -VerifyPackages
|
||||
- name: Validate branded installer dry run
|
||||
run: |
|
||||
./build/Test-BrandedInstaller.ps1
|
||||
./build/Test-PackagingInputs.ps1
|
||||
- name: Build unsigned prerelease MSI
|
||||
env:
|
||||
PRODUCT_VERSION: ${{ inputs.product-version || '1.2.1' }}
|
||||
RELEASE_VERSION: ${{ inputs.release-version || '1.2.1' }}
|
||||
PRODUCT_VERSION: ${{ inputs.product-version || '0.1.9' }}
|
||||
RELEASE_VERSION: ${{ inputs.release-version || '0.1.9-rc.1' }}
|
||||
run: |
|
||||
./build/Build-Installer.ps1 -ProductVersion $env:PRODUCT_VERSION -ReleaseVersion $env:RELEASE_VERSION
|
||||
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
|
||||
# One fully branded installer per client edition (editions/<id>), named after its asset prefix.
|
||||
$installers = @('QqqPrintAgent')
|
||||
foreach ($folder in Get-ChildItem -LiteralPath editions -Directory | Sort-Object Name) {
|
||||
./build/Build-Installer.ps1 -ProductVersion $env:PRODUCT_VERSION -ReleaseVersion $env:RELEASE_VERSION -Edition $folder.Name
|
||||
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
|
||||
$installers += (Get-Content -LiteralPath (Join-Path $folder.FullName 'edition.json') -Raw | ConvertFrom-Json).assetPrefix
|
||||
}
|
||||
New-Item -ItemType Directory -Path artifacts/release -Force | Out-Null
|
||||
Remove-Item -LiteralPath artifacts/release/SHA256SUMS -Force -ErrorAction SilentlyContinue
|
||||
foreach ($prefix in $installers) {
|
||||
$source = "artifacts/installer/$prefix-$env:PRODUCT_VERSION-x64.msi"
|
||||
$name = "$prefix-v$env:RELEASE_VERSION-x64.msi"
|
||||
Copy-Item -LiteralPath $source -Destination "artifacts/release/$name"
|
||||
$hash = (Get-FileHash -LiteralPath "artifacts/release/$name" -Algorithm SHA256).Hash.ToLowerInvariant()
|
||||
"$hash $name" | Add-Content artifacts/release/SHA256SUMS -Encoding ascii
|
||||
}
|
||||
$source = "artifacts/installer/QqqPrintAgent-$env:PRODUCT_VERSION-x64.msi"
|
||||
$name = "QqqPrintAgent-v$env:RELEASE_VERSION-x64.msi"
|
||||
Copy-Item -LiteralPath $source -Destination "artifacts/release/$name"
|
||||
Copy-Item -LiteralPath build/Install-Branded.ps1 -Destination artifacts/release/Install-Branded.ps1
|
||||
Copy-Item -LiteralPath docs/branding.example.json -Destination artifacts/release/branding.example.json
|
||||
$hash = (Get-FileHash -LiteralPath "artifacts/release/$name" -Algorithm SHA256).Hash.ToLowerInvariant()
|
||||
"$hash $name" | Set-Content artifacts/release/SHA256SUMS -Encoding ascii
|
||||
foreach ($file in @('Install-Branded.ps1', 'branding.example.json')) {
|
||||
$hash = (Get-FileHash -LiteralPath "artifacts/release/$file" -Algorithm SHA256).Hash.ToLowerInvariant()
|
||||
"$hash $file" | Add-Content artifacts/release/SHA256SUMS -Encoding ascii
|
||||
|
||||
@@ -1,6 +1,3 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
# Local copy of KofTwentyTwo/standards at fdf5ed029603c938615a32b1beca3628b8787945 (v0.1.2).
|
||||
# Pins, inputs and analysis checks preserved; report validation now fails closed.
|
||||
# Static analysis (K22-CI-22): CodeQL with the security-extended suite, failing on
|
||||
@@ -90,7 +87,7 @@ jobs:
|
||||
global-json-file: global.json
|
||||
|
||||
- name: Initialize CodeQL
|
||||
uses: github/codeql-action/init@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
|
||||
uses: github/codeql-action/init@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
|
||||
with:
|
||||
languages: ${{ matrix.language }}
|
||||
build-mode: ${{ contains(fromJSON('["actions","javascript-typescript","python","ruby"]'), matrix.language) && 'none' || inputs.build-mode }}
|
||||
@@ -110,7 +107,7 @@ jobs:
|
||||
eval "$BUILD_COMMAND"
|
||||
|
||||
- name: Analyze
|
||||
uses: github/codeql-action/analyze@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
|
||||
uses: github/codeql-action/analyze@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
|
||||
with:
|
||||
category: /language:${{ matrix.language }}
|
||||
output: codeql-sarif
|
||||
|
||||
@@ -1,6 +1,3 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
# CodeQL static analysis (K22-CI-22): security-extended queries for C# (a manual x64
|
||||
# build of the solution) and for the workflows themselves, blocking high severity.
|
||||
name: codeql
|
||||
|
||||
@@ -1,6 +1,3 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
# Pull request gates (K22-CI-01): Conventional Commit title, DCO sign-off, and
|
||||
# dependency review, from the shared KofTwentyTwo/standards workflow pinned by SHA
|
||||
# (K22-CI-11). Dependabot's github-actions ecosystem keeps the pin current.
|
||||
@@ -16,126 +13,8 @@ concurrency:
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
resolved-nuget-graph:
|
||||
# Forks and Dependabot use static review without a write token. Dependabot
|
||||
# reruns retain their original restricted privileges; never elevate via
|
||||
# pull_request_target. Check both the actor and original PR author.
|
||||
if: >-
|
||||
github.event.pull_request.head.repo.full_name == github.repository &&
|
||||
github.actor != 'dependabot[bot]' &&
|
||||
github.event.pull_request.user.login != 'dependabot[bot]'
|
||||
runs-on: windows-latest
|
||||
timeout-minutes: 20
|
||||
permissions:
|
||||
contents: write # GitHub's dependency submission API requires this scope.
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
revision: [base, head]
|
||||
steps:
|
||||
- name: Checkout exact comparison revision
|
||||
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
||||
with:
|
||||
ref: ${{ matrix.revision == 'base' && github.event.pull_request.base.sha || github.event.pull_request.head.sha }}
|
||||
persist-credentials: false
|
||||
- name: Set up .NET
|
||||
uses: actions/setup-dotnet@a98b56852c35b8e3190ac28c8c2271da59106c68 # v6.0.0
|
||||
with:
|
||||
global-json-file: global.json
|
||||
- name: Restore and verify every tracked NuGet project
|
||||
shell: pwsh
|
||||
run: |
|
||||
$ErrorActionPreference = 'Stop'
|
||||
$projects = @(git ls-files '*.csproj' '*.wixproj')
|
||||
if ($LASTEXITCODE -ne 0 -or $projects.Count -eq 0) { throw 'No tracked NuGet projects.' }
|
||||
foreach ($project in $projects) {
|
||||
dotnet restore $project -p:Platform=x64 --locked-mode
|
||||
if ($LASTEXITCODE -ne 0) { throw "Locked restore failed: $project" }
|
||||
$directory = Split-Path -Parent $project
|
||||
$assets = Get-Content -LiteralPath "$directory/obj/project.assets.json" -Raw | ConvertFrom-Json -AsHashtable
|
||||
$locked = Get-Content -LiteralPath "$directory/packages.lock.json" -Raw | ConvertFrom-Json -AsHashtable
|
||||
if ($assets.libraries.Count -eq 0 -or $locked.dependencies.Count -eq 0) { throw "Empty resolved graph: $project" }
|
||||
$count = 0
|
||||
foreach ($framework in $locked.dependencies.Values) {
|
||||
foreach ($entry in $framework.GetEnumerator()) {
|
||||
if ($entry.Value.type -eq 'Project') { continue }
|
||||
$identity = "$($entry.Key)/$($entry.Value.resolved)"
|
||||
if (-not $assets.libraries.ContainsKey($identity)) { throw "Locked package missing from resolved graph: $project : $identity" }
|
||||
$count++
|
||||
}
|
||||
}
|
||||
if ($count -eq 0) { throw "No locked packages verified: $project" }
|
||||
Write-Output "$project : $count locked framework/package entries verified."
|
||||
}
|
||||
- name: Submit resolved NuGet dependency graph
|
||||
# Official detector reads project.assets.json, including transitive and
|
||||
# centrally managed versions. Although this action is SHA-pinned, it
|
||||
# downloads Microsoft's latest detector release internally (no version
|
||||
# input); the scanner binary itself is upstream-managed, not pinned here.
|
||||
uses: advanced-security/component-detection-dependency-submission-action@1dde438cd9ce3b680144e2c2e67c3ed8fc55d947
|
||||
with:
|
||||
detectorsCategories: NuGet
|
||||
fail-on-empty: true
|
||||
correlator: qqq-print-agent-resolved-nuget
|
||||
snapshot-sha: ${{ matrix.revision == 'base' && github.event.pull_request.base.sha || github.event.pull_request.head.sha }}
|
||||
snapshot-ref: refs/heads/${{ matrix.revision == 'base' && github.event.pull_request.base.ref || github.event.pull_request.head.ref }}
|
||||
resolved-dependency-graph:
|
||||
name: pr / resolved dependency graph
|
||||
needs: resolved-nuget-graph
|
||||
if: always()
|
||||
runs-on: ubuntu-24.04
|
||||
timeout-minutes: 5
|
||||
permissions: {}
|
||||
steps:
|
||||
- name: Require resolved graphs or the explicit read-only review path
|
||||
env:
|
||||
TRUSTED_PR: ${{ github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]' && github.event.pull_request.user.login != 'dependabot[bot]' }}
|
||||
SUBMISSION_RESULT: ${{ needs.resolved-nuget-graph.result }}
|
||||
run: |
|
||||
if [ "$TRUSTED_PR" = "true" ]; then
|
||||
if [ "$SUBMISSION_RESULT" != "success" ]; then
|
||||
echo 'Resolved base/head NuGet graph submission did not succeed.' >&2
|
||||
exit 1
|
||||
fi
|
||||
echo 'Resolved base/head NuGet graphs submitted successfully.'
|
||||
else
|
||||
if [ "$SUBMISSION_RESULT" != "skipped" ]; then
|
||||
echo 'Unexpected submission result for a read-only PR.' >&2
|
||||
exit 1
|
||||
fi
|
||||
echo 'Fork or Dependabot PR: static dependency review remains required; no write-capable submission ran.'
|
||||
fi
|
||||
pr:
|
||||
needs: resolved-nuget-graph
|
||||
# A failed submission must not turn existing required reviews into skipped
|
||||
# (passing) checks. They still run; the submission job reports its own failure.
|
||||
if: ${{ !cancelled() }}
|
||||
uses: KofTwentyTwo/standards/.github/workflows/pr.yml@fdf5ed029603c938615a32b1beca3628b8787945 # v0.1.2
|
||||
with:
|
||||
# EX-0014: exact reviewed SDK inventory, guarded through 2027-04-30 UTC.
|
||||
# https://github.com/KofTwentyTwo/standards/blob/fbfc8d2cf3b5e16ae9750b04cf9de1794f1e7152/exceptions/register.md#ex-0014
|
||||
# Package-name license exceptions do not constrain versions; the required
|
||||
# SDK guard pins versions, content/archive hashes, terms and this finite list.
|
||||
# EX-0015: development-only uri-js 4.4.1 (ESLint transitive). check-script-quality.py pins its version,
|
||||
# lock integrity and installed license bytes and rejects any other pkg:npm entry in this list.
|
||||
# https://git.kof22.com/KofTwentyTwo/standards/src/commit/a18179e90f8e6d35ba9f5e583249885c066e52b8/exceptions/register.md#ex-0015
|
||||
allow-dependencies-licenses: >-
|
||||
pkg:nuget/Microsoft.Windows.AI.MachineLearning,
|
||||
pkg:nuget/Microsoft.Windows.SDK.BuildTools,
|
||||
pkg:nuget/Microsoft.Windows.SDK.BuildTools.MSIX,
|
||||
pkg:nuget/Microsoft.Windows.SDK.NET.Ref,
|
||||
pkg:nuget/Microsoft.WindowsAppSDK,
|
||||
pkg:nuget/Microsoft.WindowsAppSDK.AI,
|
||||
pkg:nuget/Microsoft.WindowsAppSDK.Base,
|
||||
pkg:nuget/Microsoft.WindowsAppSDK.DWrite,
|
||||
pkg:nuget/Microsoft.WindowsAppSDK.Foundation,
|
||||
pkg:nuget/Microsoft.WindowsAppSDK.InteractiveExperiences,
|
||||
pkg:nuget/Microsoft.WindowsAppSDK.ML,
|
||||
pkg:nuget/Microsoft.WindowsAppSDK.Runtime,
|
||||
pkg:nuget/Microsoft.WindowsAppSDK.Search,
|
||||
pkg:nuget/Microsoft.WindowsAppSDK.Widgets,
|
||||
pkg:nuget/Microsoft.WindowsAppSDK.WinUI,
|
||||
pkg:npm/uri-js
|
||||
uses: KofTwentyTwo/standards/.github/workflows/pr.yml@70b555bd5658273090769991bfc4c9b6681dde18 # v1.2.1
|
||||
permissions:
|
||||
contents: read # read the commits being merged
|
||||
pull-requests: read # read the pull request title and dependency diff
|
||||
@@ -1,11 +1,8 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
name: prerelease
|
||||
|
||||
on:
|
||||
push:
|
||||
tags: ['v*-rc.*', 'v[0-9]+.[0-9]+.[0-9]+']
|
||||
tags: ['v*-rc.*']
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
@@ -21,38 +18,20 @@ jobs:
|
||||
outputs:
|
||||
product: ${{ steps.validate.outputs.product }}
|
||||
release: ${{ steps.validate.outputs.release }}
|
||||
stable: ${{ steps.validate.outputs.stable }}
|
||||
steps:
|
||||
- name: Validate release tag
|
||||
- name: Validate prerelease tag
|
||||
id: validate
|
||||
shell: bash
|
||||
env:
|
||||
RELEASE_TAG: ${{ github.ref_name }}
|
||||
REF_TYPE: ${{ github.ref_type }}
|
||||
run: |
|
||||
if [[ "$REF_TYPE" != tag || ! "$RELEASE_TAG" =~ ^v([0-9]+\.[0-9]+\.[0-9]+)(-rc\.[0-9]+)?$ ]]; then
|
||||
echo '::error::Run this workflow on an existing vX.Y.Z-rc.N prerelease or vX.Y.Z stable tag.'
|
||||
if [[ "$REF_TYPE" != tag || ! "$RELEASE_TAG" =~ ^v([0-9]+\.[0-9]+\.[0-9]+)-rc\.([0-9]+)$ ]]; then
|
||||
echo '::error::Run this workflow on an existing vX.Y.Z-rc.N tag.'
|
||||
exit 1
|
||||
fi
|
||||
echo "product=${BASH_REMATCH[1]}" >> "$GITHUB_OUTPUT"
|
||||
echo "release=${RELEASE_TAG#v}" >> "$GITHUB_OUTPUT"
|
||||
# A stable tag has no prerelease suffix and must be signed; a prerelease stays unsigned.
|
||||
if [[ -z "${BASH_REMATCH[2]}" ]]; then echo "stable=true" >> "$GITHUB_OUTPUT"; else echo "stable=false" >> "$GITHUB_OUTPUT"; fi
|
||||
# A stable tag must be reachable from main, like MarkdownViewr.Windows. Every gate and the signing
|
||||
# job depend on this job, so an off-main stable tag is rejected before anything is built or signed.
|
||||
# Release-candidate tags keep their existing path and are not checked here.
|
||||
- name: Checkout main and tag history
|
||||
if: steps.validate.outputs.stable == 'true'
|
||||
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
||||
with:
|
||||
fetch-depth: 0
|
||||
persist-credentials: false
|
||||
- name: Require the stable tag to be on main
|
||||
if: steps.validate.outputs.stable == 'true'
|
||||
shell: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
git merge-base --is-ancestor "$GITHUB_SHA" origin/main
|
||||
verify:
|
||||
needs: version
|
||||
uses: ./.github/workflows/ci.yml
|
||||
@@ -78,212 +57,8 @@ jobs:
|
||||
uses: ./.github/workflows/scripts.yml
|
||||
permissions:
|
||||
contents: read
|
||||
# Stable tags only. Runs after every gate above, in the protected `release` environment (tags v* only),
|
||||
# and signs the owned binaries before the MSI is built and then the MSI itself, using the same Azure
|
||||
# Artifact Signing account and profile as MarkdownViewr.Windows. Pull requests never reach this job.
|
||||
# Order: verify configuration, locked restore and packaging checks, publish payload, stage owned files,
|
||||
# sign, accept only the exact publisher, build MSI from the signed payload, sign and verify the MSI,
|
||||
# then assemble the four release files with checksums computed after signing.
|
||||
# Lists the client editions (editions/<id>) so the signing job runs once for the generic build and once per edition.
|
||||
editions:
|
||||
needs: version
|
||||
if: needs.version.outputs.stable == 'true'
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 5
|
||||
permissions:
|
||||
contents: read
|
||||
outputs:
|
||||
list: ${{ steps.list.outputs.list }}
|
||||
steps:
|
||||
- name: Checkout tagged source
|
||||
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
||||
with:
|
||||
persist-credentials: false
|
||||
- name: List editions
|
||||
id: list
|
||||
shell: bash
|
||||
run: |
|
||||
list=$(find editions -mindepth 1 -maxdepth 1 -type d -printf '%f\n' | sort | jq -R . | jq -sc '[""] + .')
|
||||
echo "list=$list" >> "$GITHUB_OUTPUT"
|
||||
echo "Editions: $list"
|
||||
sign:
|
||||
if: needs.version.outputs.stable == 'true'
|
||||
needs: [version, verify, security, codeql, scripts, editions]
|
||||
runs-on: windows-latest
|
||||
timeout-minutes: 45
|
||||
environment: release
|
||||
strategy:
|
||||
fail-fast: true
|
||||
matrix:
|
||||
edition: ${{ fromJson(needs.editions.outputs.list) }}
|
||||
permissions:
|
||||
contents: read
|
||||
id-token: write # Azure OIDC for the signing identity; no secret or exported key is stored
|
||||
defaults:
|
||||
run:
|
||||
shell: pwsh
|
||||
env:
|
||||
PRODUCT_VERSION: ${{ needs.version.outputs.product }}
|
||||
RELEASE_VERSION: ${{ needs.version.outputs.release }}
|
||||
EDITION: ${{ matrix.edition }}
|
||||
AZURE_CLIENT_ID: ${{ vars.AZURE_CLIENT_ID }}
|
||||
AZURE_TENANT_ID: ${{ vars.AZURE_TENANT_ID }}
|
||||
AZURE_SUBSCRIPTION_ID: ${{ vars.AZURE_SUBSCRIPTION_ID }}
|
||||
ARTIFACT_SIGNING_ENDPOINT: ${{ vars.ARTIFACT_SIGNING_ENDPOINT }}
|
||||
ARTIFACT_SIGNING_ACCOUNT: ${{ vars.ARTIFACT_SIGNING_ACCOUNT }}
|
||||
ARTIFACT_SIGNING_PROFILE: ${{ vars.ARTIFACT_SIGNING_PROFILE }}
|
||||
ARTIFACT_SIGNING_SUBJECT: ${{ vars.ARTIFACT_SIGNING_SUBJECT }}
|
||||
steps:
|
||||
- name: Checkout tagged source
|
||||
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
||||
with:
|
||||
persist-credentials: false
|
||||
- name: Require verified signing configuration
|
||||
run: ./build/Assert-ReleaseSigning.ps1
|
||||
- name: Set up .NET
|
||||
uses: actions/setup-dotnet@a98b56852c35b8e3190ac28c8c2271da59106c68 # v6.0.0
|
||||
with:
|
||||
global-json-file: global.json
|
||||
- name: Locked restore and packaging checks
|
||||
run: |
|
||||
dotnet restore Qqq.PrintAgent.NativeCI.slnx '-p:Platform=x64' --locked-mode
|
||||
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
|
||||
./build/Test-WindowsSdkInventory.ps1 -VerifyPackages
|
||||
./build/Test-BrandedInstaller.ps1
|
||||
./build/Test-PackagingInputs.ps1
|
||||
- name: Resolve the edition
|
||||
run: |
|
||||
$args = @()
|
||||
$prefix = 'QqqPrintAgent'
|
||||
if ($env:EDITION) {
|
||||
$args = @('-Edition', $env:EDITION)
|
||||
$prefix = (Get-Content -LiteralPath "editions/$env:EDITION/edition.json" -Raw | ConvertFrom-Json).assetPrefix
|
||||
}
|
||||
if ($prefix -cnotmatch '^[A-Za-z][A-Za-z0-9]{1,39}$') { throw 'Invalid edition asset prefix.' }
|
||||
"EDITION_ARGS=$($args -join ' ')" | Add-Content -LiteralPath $env:GITHUB_ENV
|
||||
"MSI_PATH=artifacts/installer/$prefix-$env:PRODUCT_VERSION-x64.msi" | Add-Content -LiteralPath $env:GITHUB_ENV
|
||||
"ARTIFACT_NAME=windows-x64-installer-signed-$(if ($env:EDITION) { $env:EDITION } else { 'generic' })" | Add-Content -LiteralPath $env:GITHUB_ENV
|
||||
Write-Output "Edition: '$env:EDITION' -> $prefix"
|
||||
- name: Publish and check the payload
|
||||
run: |
|
||||
# Hashtable splat: an array splat binds "-Edition gg-forge" positionally (to CertificateThumbprint/TimestampServer) and trips the PublishOnly guard.
|
||||
$editionArgs = @{}
|
||||
if ($env:EDITION) { $editionArgs['Edition'] = $env:EDITION }
|
||||
./build/Build-Installer.ps1 -ProductVersion $env:PRODUCT_VERSION -ReleaseVersion $env:RELEASE_VERSION -PublishOnly -PayloadDirectory "$env:RUNNER_TEMP/payload" @editionArgs
|
||||
- name: Stage owned binaries
|
||||
run: ./build/Sign-Release.ps1 -Operation Stage -Kind Payload -Root "$env:RUNNER_TEMP/payload" -Stage "$env:RUNNER_TEMP/sign-payload"
|
||||
# The pinned signing action's own installer runs `dotnet tool install --add-source`, which the repository's
|
||||
# package source mapping (nuget.config) rejects. Install only the SignCLI version it expects, through that same
|
||||
# mapped config, into the exact folder layout the action looks for; it then finds the tool and skips its install.
|
||||
- name: Install the pinned SignCLI through the repository NuGet configuration
|
||||
run: |
|
||||
$version = '0.9.1-beta.26227.3'
|
||||
$versions = Join-Path $env:LOCALAPPDATA 'ArtifactSigning\sign'
|
||||
$install = Join-Path $versions "sign.$version"
|
||||
$dll = Join-Path $install 'tools\net8.0\any\sign.dll'
|
||||
if (Test-Path -LiteralPath $dll -PathType Leaf) { Write-Output "SignCLI $version is already installed."; return }
|
||||
# Install into a unique temporary folder, then copy the package contents into the expected folder. Nothing
|
||||
# already under ArtifactSigning (other versions, shims) is deleted or moved.
|
||||
$temp = Join-Path $env:RUNNER_TEMP "signcli-$([guid]::NewGuid().ToString('N'))"
|
||||
dotnet tool install sign --version $version --tool-path $temp --configfile (Join-Path $env:GITHUB_WORKSPACE 'nuget.config')
|
||||
if ($LASTEXITCODE -ne 0) { throw "dotnet tool install sign $version failed." }
|
||||
$store = Join-Path $temp ".store\sign\$version\sign\$version"
|
||||
if (-not (Test-Path -LiteralPath $store -PathType Container)) { throw "SignCLI $version package content was not found." }
|
||||
New-Item -ItemType Directory -Path $install -Force | Out-Null
|
||||
Copy-Item -Path (Join-Path $store '*') -Destination $install -Recurse -Force
|
||||
if (-not (Test-Path -LiteralPath $dll -PathType Leaf)) { throw "SignCLI $version is missing tools\net8.0\any\sign.dll." }
|
||||
- name: Azure login (OIDC)
|
||||
uses: azure/login@a641126d1b8aa4d1fa005f4f92df94a3a4c4c906 # v3.1.0
|
||||
with:
|
||||
client-id: ${{ vars.AZURE_CLIENT_ID }}
|
||||
tenant-id: ${{ vars.AZURE_TENANT_ID }}
|
||||
subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
|
||||
- name: Sign owned binaries
|
||||
uses: azure/artifact-signing-action@c7ab2a863ab5f9a846ddb8265964877ef296ee82 # v2.0.0
|
||||
with:
|
||||
endpoint: ${{ vars.ARTIFACT_SIGNING_ENDPOINT }}
|
||||
signing-account-name: ${{ vars.ARTIFACT_SIGNING_ACCOUNT }}
|
||||
certificate-profile-name: ${{ vars.ARTIFACT_SIGNING_PROFILE }}
|
||||
files-folder: ${{ runner.temp }}/sign-payload
|
||||
files-folder-filter: exe,dll
|
||||
files-folder-recurse: true
|
||||
file-digest: SHA256
|
||||
timestamp-rfc3161: http://timestamp.acs.microsoft.com
|
||||
timestamp-digest: SHA256
|
||||
- name: Accept signed binaries for the exact publisher
|
||||
run: ./build/Sign-Release.ps1 -Operation Apply -Kind Payload -Root "$env:RUNNER_TEMP/payload" -Stage "$env:RUNNER_TEMP/sign-payload" -ExpectedSubject $env:ARTIFACT_SIGNING_SUBJECT
|
||||
- name: Build MSI from the signed payload
|
||||
run: |
|
||||
# Hashtable splat: an array splat binds "-Edition gg-forge" positionally (to CertificateThumbprint/TimestampServer) and trips the PublishOnly guard.
|
||||
$editionArgs = @{}
|
||||
if ($env:EDITION) { $editionArgs['Edition'] = $env:EDITION }
|
||||
./build/Build-Installer.ps1 -ProductVersion $env:PRODUCT_VERSION -ReleaseVersion $env:RELEASE_VERSION -SkipPublish -PayloadDirectory "$env:RUNNER_TEMP/payload" @editionArgs
|
||||
- name: Stage MSI
|
||||
run: ./build/Sign-Release.ps1 -Operation Stage -Kind Msi -Root $env:MSI_PATH -Stage "$env:RUNNER_TEMP/sign-msi"
|
||||
- name: Sign MSI
|
||||
uses: azure/artifact-signing-action@c7ab2a863ab5f9a846ddb8265964877ef296ee82 # v2.0.0
|
||||
with:
|
||||
endpoint: ${{ vars.ARTIFACT_SIGNING_ENDPOINT }}
|
||||
signing-account-name: ${{ vars.ARTIFACT_SIGNING_ACCOUNT }}
|
||||
certificate-profile-name: ${{ vars.ARTIFACT_SIGNING_PROFILE }}
|
||||
files-folder: ${{ runner.temp }}/sign-msi
|
||||
files-folder-filter: msi
|
||||
files-folder-recurse: false
|
||||
file-digest: SHA256
|
||||
timestamp-rfc3161: http://timestamp.acs.microsoft.com
|
||||
timestamp-digest: SHA256
|
||||
- name: Accept signed MSI for the exact publisher
|
||||
run: ./build/Sign-Release.ps1 -Operation Apply -Kind Msi -Root $env:MSI_PATH -Stage "$env:RUNNER_TEMP/sign-msi" -ExpectedSubject $env:ARTIFACT_SIGNING_SUBJECT
|
||||
- name: Upload the signed installer of this edition
|
||||
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
|
||||
with:
|
||||
name: ${{ env.ARTIFACT_NAME }}
|
||||
path: ${{ env.MSI_PATH }}
|
||||
if-no-files-found: error
|
||||
retention-days: 14
|
||||
# Gathers the signed generic and edition installers, verifies each signature again, and writes the release
|
||||
# files with one SHA256SUMS computed after signing. Nothing is built or signed here.
|
||||
assemble:
|
||||
if: needs.version.outputs.stable == 'true'
|
||||
needs: [version, sign]
|
||||
runs-on: windows-latest
|
||||
timeout-minutes: 15
|
||||
permissions:
|
||||
contents: read
|
||||
defaults:
|
||||
run:
|
||||
shell: pwsh
|
||||
steps:
|
||||
- name: Checkout tagged source
|
||||
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
||||
with:
|
||||
persist-credentials: false
|
||||
- name: Download the signed installers
|
||||
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
|
||||
with:
|
||||
pattern: windows-x64-installer-signed-*
|
||||
path: artifacts/installer
|
||||
merge-multiple: true
|
||||
- name: Assemble signed release files and checksums
|
||||
env:
|
||||
PRODUCT_VERSION: ${{ needs.version.outputs.product }}
|
||||
RELEASE_VERSION: ${{ needs.version.outputs.release }}
|
||||
ARTIFACT_SIGNING_SUBJECT: ${{ vars.ARTIFACT_SIGNING_SUBJECT }}
|
||||
run: ./build/Package-Release.ps1 -AssembleOnly -ProductVersion $env:PRODUCT_VERSION -ReleaseVersion $env:RELEASE_VERSION -ExpectedPublisherSubject $env:ARTIFACT_SIGNING_SUBJECT
|
||||
- name: Upload signed installers
|
||||
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
|
||||
with:
|
||||
name: windows-x64-installer-signed
|
||||
path: artifacts/release/*
|
||||
if-no-files-found: error
|
||||
retention-days: 14
|
||||
publish:
|
||||
needs: [version, verify, security, codeql, scripts, sign, assemble]
|
||||
# Every gate must pass; the signing and assembly jobs may be skipped only for an unsigned prerelease tag.
|
||||
if: >-
|
||||
${{ !cancelled() && needs.version.result == 'success' && needs.verify.result == 'success'
|
||||
&& needs.security.result == 'success' && needs.codeql.result == 'success' && needs.scripts.result == 'success'
|
||||
&& (needs.version.outputs.stable != 'true' && needs.sign.result == 'skipped' && needs.assemble.result == 'skipped' || needs.version.outputs.stable == 'true' && needs.sign.result == 'success' && needs.assemble.result == 'success') }}
|
||||
needs: [version, verify, security, codeql, scripts]
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 10
|
||||
permissions:
|
||||
@@ -294,7 +69,7 @@ jobs:
|
||||
- name: Download verified installer
|
||||
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
|
||||
with:
|
||||
name: ${{ needs.version.outputs.stable == 'true' && 'windows-x64-installer-signed' || 'windows-x64-installer' }}
|
||||
name: windows-x64-installer
|
||||
path: release
|
||||
- name: Verify packaged checksums
|
||||
working-directory: release
|
||||
@@ -303,26 +78,7 @@ jobs:
|
||||
uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
|
||||
with:
|
||||
subject-path: release/*
|
||||
- name: Publish signed stable release
|
||||
if: needs.version.outputs.stable == 'true'
|
||||
shell: bash
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
GH_REPO: ${{ github.repository }}
|
||||
RELEASE_TAG: ${{ github.ref_name }}
|
||||
run: |
|
||||
cat > release-notes.md <<'NOTES'
|
||||
Windows x64 release of QQQ Print Agent for QQQ 4.1+. The MSI and the first-party service, companion and command-line binaries are Authenticode-signed with SHA256 and an RFC3161 timestamp by the project's Azure Artifact Signing publisher identity.
|
||||
|
||||
Verify the MSI against SHA256SUMS and its GitHub provenance attestation before installing; every asset was built and tested by this workflow after all security, CodeQL and script gates passed, and the checksums were generated after signing.
|
||||
|
||||
This client requires QQQ's semantic printing extension >=2.0.0 <3.0.0 and standard QQQ sign-in; selected-media jobs need printing 2.3+. Upgrade the server first. Existing pairings and history are preserved.
|
||||
|
||||
See CHANGELOG.md, docs/INSTALLATION.md and docs/ACCEPTANCE.md in the tagged source for scope, evidence and limitations. Spool acceptance alone does not establish physical output.
|
||||
NOTES
|
||||
gh release create "$RELEASE_TAG" release/* --verify-tag --latest --title "QQQ Print Agent $RELEASE_TAG" --notes-file release-notes.md
|
||||
- name: Publish unsigned prerelease
|
||||
if: needs.version.outputs.stable != 'true'
|
||||
shell: bash
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
@@ -334,21 +90,7 @@ jobs:
|
||||
|
||||
Assets were built and tested by this workflow. Verify the MSI against SHA256SUMS before installing. No Authenticode signature or production qualification is claimed.
|
||||
|
||||
This client requires QQQ's semantic printing extension >=2.0.0 <3.0.0 and standard QQQ sign-in. When upgrading from 0.2, upgrade the server first: native API 2.0 makes a synchronized authenticated WebSocket mandatory for claims. An existing 0.3 server remains compatible with this client follow-up. Existing pairings and history are preserved; unbound devices require explicit account association.
|
||||
|
||||
New in 0.4.0: optional printer-media selection and 4 x 2 / 4 x 1 test-label choices. Printer profiles describe configured defaults, not physical stock sensing; jobs refuse a selected profile whose revision has drifted. Each job writes a phase-timing log line. Ordered numeric executable versions allow normal upgrades between release candidates. Upgrade the server first for selected-media jobs. The local rc.3 build of the same printing runtime passed installation and the operator's 4 x 1 test; Letter and 4 x 6 output were previously accepted. Physical 4 x 2 testing is deferred. This remains an unsigned prerelease, with no GA or stable 1.0 claim.
|
||||
|
||||
New in 0.3.2: a successful MSI result is accepted only when app, service and CLI have the requested release and identical full build versions. Missing, unreadable or mixed builds report an inconsistent installation without claiming rollback. The SDK credit references Microsoft's separate terms and installed notices. The native test host now matches production's PerMonitorV2 DPI declaration while retaining unelevated execution.
|
||||
|
||||
New in 0.3.1: the footer shows explicit WebSocket state, a server-settings link, live QQQ service upload/download payload rates and totals since service start. Lightweight local observations add no QQQ job/control polling. Windows-normalized startup account names are accepted only when they resolve to the exact expected SID; this preference controls the tray companion, independently of the automatic print service.
|
||||
|
||||
Known issue: a post-print native LayoutCycleException was observed in the 0.3.0 companion. The original trigger remains unreproduced despite nonprinting native geometry/dialog/refresh tests. This follow-up logs that exact fatal exception and permits normal WinUI termination rather than leaving an input-dead window; the service continues and the operator can reopen the companion. This is mitigation, not an underlying layout fix. Actual fatal handling and natural termination were verified with an intentionally cycling native Panel in an isolated nonprinting host; that test does not reproduce the original post-print trigger.
|
||||
|
||||
New in 0.3: persistent outbound authenticated WSS carries controls, commands, receipts, status and job notifications, with no job/control polling or fallback. Documents stream separately over same-origin HTTPS into protected staging. Administrator settings bound document size, copies, aggregate bandwidth, staging, queues, concurrency, liveness and timeouts; defaults include 100 MiB PDF, 20 MiB ZPL and one download/print lane. Durable reconnect reconciliation preserves receipts and prevents blind resubmission of uncertain jobs. The Jobs view adds inline expansion and actions with sortable, bounded history.
|
||||
|
||||
Existing features include standard QQQ sign-in and protected service sessions, PDF/ZPL printing and warehouse diagnostic profiles, exact owned spool cancellation, synchronized device/printer profiles, configurable logs, customer branding, AppKit settings/logs/update prompts, machine-wide MSI updates, tray status and explicit printer exposure. Replacement pairing and recovery from damaged saved credentials preserve history and printer choices without silently enabling printing.
|
||||
|
||||
The published 0.3.2 MSI was reached by a real in-app update from 0.3.1 with pairing, printer profiles and local receipts preserved, and its service restored the native QQQ session and WebSocket. The operator confirmed successful test prints on 0.3.1. Configured provider/browser callbacks also need end-to-end qualification against a compatible native-session API. See docs/ACCEPTANCE.md for version-specific evidence and remaining limits. Spool acceptance alone does not establish physical output or scanner readability; no stable 1.0 readiness is claimed.
|
||||
Features: QQQ-branded warehouse diagnostic documents with native Letter/A4/4 × 6-inch PDF and 203/300/600-dpi ZPL profile choices, label-aware defaults with operator resolution verification, sortable printer and job tables, inline printer details, double-click settings and job dialogs, bounded history pages with creation-time ordering, synchronized computer/printer profiles, daily log limits and clearing, same-installer customer branding, native Windows navigation, AppKit logs/settings/update prompts, verified machine-wide MSI updates, tray status, explicit printer exposure, reconnect and service controls, searchable job history with test/retry/cancel/review actions, bounded printer workers, outbound cloud polling, PDF and ZPL spool submission, durable receipts and protected service credentials. See docs/ACCEPTANCE.md for version-specific installed checks, diagnostic spool submissions, physical-output confirmation and remaining qualification limits. Spool acceptance alone does not establish physical output or scanner readability.
|
||||
|
||||
See CHANGELOG.md, docs/INSTALLATION.md and docs/ACCEPTANCE.md in the tagged source for scope and limitations.
|
||||
NOTES
|
||||
|
||||
@@ -1,6 +1,3 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
# OpenSSF Scorecard (K22-CI-24). Scorecard's publishing API only accepts results
|
||||
# from a workflow shaped exactly like this one: a single job, read-only top-level
|
||||
# permissions, no top-level env or defaults, and only the allowed steps.
|
||||
@@ -37,7 +34,7 @@ jobs:
|
||||
persist-credentials: false
|
||||
|
||||
- name: Run Scorecard
|
||||
uses: ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc # v2.4.4
|
||||
uses: ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e # v2.5.0
|
||||
with:
|
||||
results_file: scorecard.sarif
|
||||
results_format: sarif
|
||||
@@ -51,7 +48,7 @@ jobs:
|
||||
retention-days: 30
|
||||
|
||||
- name: Upload SARIF to code scanning
|
||||
uses: github/codeql-action/upload-sarif@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
|
||||
uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
|
||||
with:
|
||||
sarif_file: scorecard.sarif
|
||||
category: scorecard
|
||||
@@ -1,6 +1,3 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
# K22-CODE-SH: check repository tooling before merges and releases.
|
||||
name: scripts
|
||||
|
||||
@@ -13,44 +10,6 @@ on:
|
||||
permissions: {}
|
||||
|
||||
jobs:
|
||||
virtual-agent:
|
||||
name: virtual-agent
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 10
|
||||
permissions:
|
||||
contents: read
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
||||
with:
|
||||
persist-credentials: false
|
||||
- name: Set up Node
|
||||
uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
|
||||
with:
|
||||
node-version: '24'
|
||||
package-manager-cache: false
|
||||
- name: Restore locked JavaScript tools
|
||||
run: npm ci --ignore-scripts --no-audit --no-fund
|
||||
- name: Set up uv
|
||||
uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
|
||||
with:
|
||||
version: '0.13.6'
|
||||
enable-cache: false
|
||||
- name: Restore locked Python tools
|
||||
run: uv sync --locked
|
||||
- name: Verify script quality gates and rejection paths
|
||||
run: |
|
||||
uv run --locked --no-sync python .github/scripts/test-script-quality.py
|
||||
uv run --locked --no-sync python .github/scripts/check-script-quality.py
|
||||
npm run typecheck
|
||||
npm run lint
|
||||
- name: Verify owned source notices and rejection paths
|
||||
run: |
|
||||
python3 .github/scripts/test-source-headers.py
|
||||
python3 .github/scripts/check-source-headers.py
|
||||
- name: Verify virtual-agent protocol and HTTP boundaries
|
||||
run: node --test tools/virtual-agent/test/virtual-agent.test.mjs
|
||||
|
||||
powershell:
|
||||
name: powershell
|
||||
runs-on: windows-latest
|
||||
@@ -75,7 +34,7 @@ jobs:
|
||||
Install-Module Pester -RequiredVersion 5.7.1 -Scope CurrentUser -Force
|
||||
Import-Module Pester -RequiredVersion 5.7.1
|
||||
$testConfiguration = New-PesterConfiguration
|
||||
$testConfiguration.Run.Path = @('build/Assert-Coverage.Tests.ps1', 'build/Analyze-Scripts.Tests.ps1', 'build/Install-Branded.Tests.ps1', 'build/Test-WindowsSdkInventory.Tests.ps1')
|
||||
$testConfiguration.Run.Path = @('build/Assert-Coverage.Tests.ps1', 'build/Analyze-Scripts.Tests.ps1', 'build/Install-Branded.Tests.ps1')
|
||||
$testConfiguration.Run.Exit = $true
|
||||
$testConfiguration.TestResult.Enabled = $true
|
||||
$testConfiguration.TestResult.OutputPath = 'TestResults/coverage-gate.xml'
|
||||
|
||||
@@ -1,6 +1,3 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
# Local copy of KofTwentyTwo/standards at fdf5ed029603c938615a32b1beca3628b8787945 (v0.1.2).
|
||||
# Scanner pins/checks retained; NuGet inventory and OSV evidence now fail closed.
|
||||
# Security scanning (K22-CI-20, K22-CI-21, K22-CI-23): secrets over full history,
|
||||
@@ -102,7 +99,7 @@ jobs:
|
||||
- name: Upload SARIF to code scanning
|
||||
# Fork pull requests get a read-only token, so only same-repository runs upload.
|
||||
if: always() && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)
|
||||
uses: github/codeql-action/upload-sarif@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
|
||||
uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
|
||||
with:
|
||||
sarif_file: trivy.sarif
|
||||
category: trivy-sca
|
||||
@@ -157,7 +154,7 @@ jobs:
|
||||
persist-credentials: false
|
||||
|
||||
- name: Set up uv
|
||||
uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
|
||||
uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
|
||||
with:
|
||||
enable-cache: false
|
||||
|
||||
@@ -168,7 +165,7 @@ jobs:
|
||||
|
||||
- name: Upload SARIF to code scanning
|
||||
if: always() && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)
|
||||
uses: github/codeql-action/upload-sarif@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
|
||||
uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
|
||||
with:
|
||||
sarif_file: zizmor.sarif
|
||||
category: zizmor
|
||||
|
||||
@@ -1,6 +1,3 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
# Security scans (K22-CI-20, K22-CI-21, K22-CI-23): gitleaks over full history,
|
||||
# Trivy + OSV-Scanner over the lock files, zizmor + actionlint over the workflows.
|
||||
# Runs on every pull request, every push to main, and weekly.
|
||||
|
||||
@@ -492,11 +492,3 @@ testResults.xml
|
||||
journal.db*
|
||||
worker.lock
|
||||
|
||||
# This vendor legal-file directory is not a generated .msix package.
|
||||
!licenses/Microsoft.Windows.SDK.BuildTools.MSIX/
|
||||
|
||||
|
||||
# Local script-quality environments and tool caches.
|
||||
.venv/
|
||||
.ruff_cache/
|
||||
__pycache__/
|
||||
@@ -1,6 +1,3 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
# KofTwentyTwo pre-commit configuration. Works with pre-commit and prek.
|
||||
# Copy to the repository root as .pre-commit-config.yaml, then install both hook
|
||||
# types once per clone:
|
||||
|
||||
@@ -1 +0,0 @@
|
||||
3.13
|
||||
@@ -2,8 +2,7 @@
|
||||
|
||||
This is QRun-IO/qqq-print-agent, built on KofTwentyTwo AppKit's Windows service variant. Follow the current user request and repository .editorconfig/central package versions.
|
||||
|
||||
- Gitea is primary for ordinary branches and pull requests. GitHub is the source shadow, with the authorized existing release/signing and CI/security workflows retained; the installed updater requires GitHub release assets. Do not remove that bridge as part of a source-host migration.
|
||||
- Verify with `./build/Verify.ps1`; package with `./build/Build-Installer.ps1 -ProductVersion 1.0.1 -ReleaseVersion 1.0.1`.
|
||||
- Verify with `./build/Verify.ps1`; package with `./build/Build-Installer.ps1 -ProductVersion 0.1.9 -ReleaseVersion 0.1.9-rc.1`.
|
||||
- Core owns protocol/state/policy; Windows owns OS adapters/storage/runtime; Service owns hosting; UI owns native views/tray plumbing.
|
||||
- Zero compiler/analyzer warnings; locked dependencies. Coverage is reported for the initial prerelease under docs/adr/0002-prerelease-quality-and-packaging.md.
|
||||
- Keep the service alive independently of the companion. Use AppKit update UX with the machine MSI adapter; update service, companion and CLI together. Do not install a per-user-only replacement over the machine package.
|
||||
|
||||
+4
-213
@@ -1,219 +1,10 @@
|
||||
# Changelog
|
||||
|
||||
## 1.2.1
|
||||
|
||||
Release-pipeline fix only; same source as 1.2.0 otherwise. The stable release workflow's per-edition
|
||||
sign job passed the edition to `Build-Installer.ps1` through an array splat, which PowerShell binds
|
||||
positionally, so `-Edition gg-forge` landed in the signing-certificate parameters and the GG Forge
|
||||
sign job refused to publish; tag `v1.2.0` therefore produced no signed installer and must not be
|
||||
moved or reused. The workflow now splats a hashtable. No application or wire change.
|
||||
|
||||
## 1.2.0
|
||||
|
||||
Client editions. A folder under `editions/<id>` (descriptor, SVG mark, ICO icon, optional logo) and
|
||||
`Build-Installer.ps1 -Edition <id>` produce a fully branded build and installer: the client's mark and
|
||||
icon on the splash, About, window, taskbar and Start menu; the client's product, company and file
|
||||
description in every executable; the client's product name, manufacturer and service display name in
|
||||
the MSI, forced over any stored labels; the MSI and release asset named after the edition's asset
|
||||
prefix; and the installed updater following that asset on the shared feed. CI builds every edition,
|
||||
and the stable release workflow signs and publishes one installer per edition beside the generic one
|
||||
with a single checksum list. The first edition is `gg-forge` (GG Forge Print Agent by Greater Goods).
|
||||
Deployment branding through `Install-Branded.ps1` is unchanged and still applies on top of an edition.
|
||||
Native browser sign-in sends the attempt's nonce as `expectedNonce` when the grant policy is REQUIRED or
|
||||
OPTIONAL or when discovery advertises `nativeSessionNonceValidation`; legacy servers keep the unchanged
|
||||
exchange body. `build/Build-CiRelease.ps1` is the shared-CI packaging entrypoint and delegates to
|
||||
`Package-Release.ps1`.
|
||||
|
||||
Printer approval per server. On a printing 2.4 server the client advertises `printer-approval-v1` and
|
||||
takes approval from the server's `PRINTERS` frame, pushed after each accepted inventory and whenever an
|
||||
administrator approves or disables one of this device's printers (protocol 1.1.0, QBit 1.1.0). On a 2.3
|
||||
server the service instead reads the operator printer catalog after each accepted inventory and about once
|
||||
a minute while connected. Either way the snapshot carries a per-printer server state:
|
||||
approved, awaiting approval, not reported (with the reason) or not checked. The Printers page shows it in a
|
||||
new Server column, in the summary line and in the expanded details, named for the connected server, so a
|
||||
printer shared before a server change is never mistaken for one the new server approved. The reading is
|
||||
reset with the connection. The activity log viewer has a Clear logs button, the connection dialog keeps its
|
||||
result banner above the form and shows a waiting state during browser sign-in, and the service's sign-in reply
|
||||
no longer repeats itself. No wire change.
|
||||
|
||||
## 1.1.1
|
||||
|
||||
Browser sign-in fix. The companion runs elevated, and its callback inbox pipe was keyed with
|
||||
PipeOptions.CurrentUserOnly to the elevated token's default owner (the Administrators group), so
|
||||
the protocol handler the browser launches as the ordinary user was refused with "Access to the
|
||||
path is denied" and no browser sign-in could ever complete. The inbox is now created with an
|
||||
explicit descriptor owned by and restricted to the user's own SID, and the handler verifies the
|
||||
companion by process image instead of the owner comparison. A protocol-handler trace in the
|
||||
per-user profile, copied into the activity log when a browser sign-in does not complete, makes
|
||||
the hand-off visible. No wire change.
|
||||
|
||||
## 1.1.0
|
||||
|
||||
Diagnostics for new accounts and servers. The session client now narrates every step of discovery,
|
||||
authentication metadata, native grant validation, provider discovery, browser callback handling,
|
||||
password sign-in, session restore and renewal, identity checks, device binding and the realtime
|
||||
socket upgrade, and says exactly which server-side requirement is missing when it refuses a server;
|
||||
the service logs each sign-in, sign-out, enrollment, authorization and reconnect step and every
|
||||
failure with its inner causes; the companion logs its side and shows the failure reason in the
|
||||
dialog instead of a generic message. TLS certificate rejections are logged with the policy error,
|
||||
certificate identity and remedy. A new **Allow untrusted server certificate for this server** option (Connection
|
||||
settings, bound to one server origin, persisted in the protected store, honored by the service and
|
||||
companion, logged with a warning on every session) supports development servers with self-signed or
|
||||
private-authority certificates without weakening any other server connection.
|
||||
Log settings gain **Debug logging** (request routes, status codes, timings, realtime frames and
|
||||
full failure detail; never credentials) and replace the daily cap that silenced the log with size
|
||||
rollover: a file that reaches the limit (default 100 MiB, up to 1024) becomes a numbered segment and
|
||||
logging continues, keeping at most a configurable number of segments per day (default 10). No wire
|
||||
change; native printing stays 2.3 with wire payload v1.
|
||||
|
||||
## 1.0.1
|
||||
|
||||
Packaging fix; no application, wire or dependency change. The `v1.0.0` release run passed
|
||||
every build, test, security, CodeQL and script gate and the Azure OIDC login, then stopped
|
||||
before signing: the Artifact Signing action installs its SignCLI tool with
|
||||
`dotnet tool install --add-source`, which the repository's NuGet package source mapping
|
||||
rejects. No signed 1.0.0 installer was published and that tag is unchanged. The release
|
||||
workflow now installs only the pinned SignCLI (`0.9.1-beta.26227.3`) through the mapped
|
||||
repository `nuget.config` into the exact folder the action expects, before the first signing
|
||||
step, so the action finds it and the mapping is not weakened. Native printing stays 2.3 with
|
||||
wire payload v1.
|
||||
|
||||
## 1.0.0
|
||||
|
||||
Product version 1.0.0 for the same cohort as 0.4.0-rc.4. A stable `v1.0.0` tag runs the
|
||||
release workflow: after every existing gate it signs the service, companion and CLI binaries
|
||||
and then the MSI with Azure Artifact Signing, verifies the exact publisher, and publishes a
|
||||
non-prerelease with checksums and provenance generated after signing (see
|
||||
docs/RELEASE-SIGNING.md). The numeric file version is `1.0.0.65535`, above every earlier
|
||||
candidate, so the updater offers it over an installed 0.4.0-rc.4. Native printing stays 2.3
|
||||
with wire payload v1; 1.0 is not a wire change. No code or dependency change comes with the
|
||||
version. Physical acceptance covers 4 × 6, Letter and 4 × 1; 4 × 2 is deferred.
|
||||
|
||||
## 0.4.0-rc.4 — unsigned prerelease candidate
|
||||
|
||||
Release identity only: rc.4 is strictly newer than the local, unpublished 0.4.0-rc.3
|
||||
build and ships the same cohort, so the updater accepts it over an installed rc.3. The
|
||||
MSI ProductVersion and `VersionPrefix` stay 0.4.0; `VersionSuffix` and the packaging
|
||||
defaults move to `rc.4`, and the ordered numeric file version becomes `0.4.0.4`. There is
|
||||
no code, test or dependency change. Everything described under rc.3 below (media
|
||||
selection, 4 × 2 and 4 × 1 test labels, phase-timing log, ordered file version) applies.
|
||||
The rc.4 head is version metadata and docs on top of pre-release product source
|
||||
`5c2bfc9`, whose full hosted CI run 41381287355 passed 499 tests (166 Core + 333 CLI) with
|
||||
zero warnings and errors. rc.4 itself is not yet tested or published; its tag pipeline
|
||||
must pass all gates afresh before publication. Earlier operator acceptance covers 4 × 6
|
||||
and Letter output, and the 4 × 1 layout was confirmed on the local rc.3 build of the same
|
||||
product code; 4 × 2 is deferred. The MSI is unsigned and no GA or 1.0 readiness is
|
||||
claimed.
|
||||
|
||||
## 0.4.0-rc.3 — local candidate (superseded by rc.4)
|
||||
|
||||
Release identity: this is a strictly newer semantic version than 0.4.0-rc.1 and
|
||||
0.4.0-rc.2 with the same numeric core, so the MSI ProductVersion (0.4.0) and
|
||||
`VersionPrefix` are unchanged, `VersionSuffix` and the packaging defaults move to `rc.3`,
|
||||
and the updater (which needs a strictly newer version) and the installer's same-version
|
||||
upgrade support both accept it. The rc.2 MSI was installed, but Windows Installer skipped
|
||||
its executables because rc.1 and rc.2 shared the numeric file version 0.4.0.0 ("existing
|
||||
file is of an equal version"). Packaging now stamps each executable with an ordered
|
||||
numeric file version: `X.Y.Z-rc.N` becomes `X.Y.Z.N` (N 1..65534) and stable `X.Y.Z`
|
||||
becomes `X.Y.Z.65535`, and any other prerelease label is refused. Future upgrades replace
|
||||
files automatically. No behavior, dependency or lock change otherwise. The protocol
|
||||
package `0.4.0rc1` is an independent wire-compatibility version and is unchanged. Older
|
||||
notes below that name 0.4.0-rc.1 or rc.2 describe the same cohort.
|
||||
|
||||
This cohort goes beyond the older installed CI 0.4.0-rc.1 build. The rc.3 candidate
|
||||
was built and installed locally with a normal MSI upgrade (exit 0), matching all three
|
||||
components; no repair was needed. It is not publicly released or tagged. Hosted Windows
|
||||
CI and the update-feed handoff await the migration owner.
|
||||
Upgrade the server first: selected-media jobs require
|
||||
printing extension 2.3.0 (wire payload v1 unchanged). Against a 2.0, 2.1 or 2.2
|
||||
(rendering) server the client keeps its three-capability HELLO and offers no media
|
||||
profiles, so existing behavior is unchanged.
|
||||
|
||||
- Add 4 × 1 and 4 × 2 in test labels (ZPL at 203/300/600 dpi, one PDF choice each) to the existing Print test choices; the 4 × 6 choices and defaults are unchanged. These PDFs carry explicit actual-size job paper (101.6 × 25.4 / 50.8 mm) applied to a job-local copy of the queue defaults (so its Direct Thermal and other settings are kept) and checked against the device context before StartDoc. Needs the matching unreleased 0.4 server; older clients reject job paper. Load the correct stock first; nothing prints until the operator confirms.
|
||||
- Report each queue's machine-default paper dimensions and resolution as an opaque, revision-bound media profile, and advertise `printer-media-v1` only when the discovered server supports it. Defaults are configured facts, not physical stock sensing.
|
||||
- Refuse a selected-media job before spooling when the profile is unknown or its revision has drifted, and again at the native submission boundary. A proven pre-submit refusal is recorded as FAILED and is never treated as an uncertain outcome.
|
||||
- Normalize job-only driver copies and scale for selected PDFs and verify the effective device-context dimensions and resolution before StartDoc. ZPL (RAW) only rechecks the profile immediately before StartDocPrinter.
|
||||
- Log one phase-timing line per processed job (inventory, claim and receipt, download, revalidation, submit gate, native submit) with the job identifier only, to attribute print latency from the service log. No new request, payload or printer access.
|
||||
- Pin the printing protocol to the final reviewed contract, commit `42c0d249f81395f00408ec0f92638dcbbf5deb03` ([Gitea PR 2](https://git.kof22.com/QRun-IO/qqq-print-protocol/pulls/2)), in `.github/workflows/ci.yml`; native printing stays 2.3 with wire payload v1. The earlier pin `a26c18c9…` is historical.
|
||||
- Split `PrintWorker` job processing into named submission, revalidation, dispatch-gate and native-submit steps (analyzer MA0051 rejected the first form of the timing instrumentation). Behavior, state order and lease release are unchanged.
|
||||
- Document every type, method, constructor and non-auto property with how/why headers and apply the `.editorconfig` structural spacing. Each batch was token-compared as comment and blank-line only.
|
||||
|
||||
Evidence: this cohort includes changes beyond the installed CI 0.4 build, and the
|
||||
latest release head is neither installed nor tagged. On the merged integration tree the
|
||||
local gate passed: the production UI build under strict XML and analyzers with zero
|
||||
warnings, and the 35 existing paper/media tests; the server's strict full verify (R31)
|
||||
also passed. Core.Tests is not built locally
|
||||
because of a Defender quarantine and is verified only on hosted CI. The prior protected
|
||||
base `0336d5f` had 477 hosted tests; this source head still needs a normal Gitea
|
||||
Core, CLI and build run. The earlier PR-head result (35ed93c) is historical. The
|
||||
existing Auth/S3 qualification is accepted and no new desktop or provider proof is
|
||||
claimed. Still pending: hosted CI, installation of the new label implementation, and
|
||||
a small-stock paper test. No 1.0 claim.
|
||||
|
||||
## 0.3.2-rc.1 — 2026-11-01
|
||||
|
||||
- Verify that the app, service and CLI all have the requested release and identical full build versions before recording MSI update success. Report missing, unreadable or mixed builds without claiming rollback.
|
||||
- Correct the Windows App SDK credit to reference its Microsoft terms and installed third-party notices.
|
||||
- Give the isolated native test host the same PerMonitorV2 DPI declaration as production while retaining its unelevated execution level.
|
||||
|
||||
The updater regressions first failed against the earlier implementation, then
|
||||
passed with the correction. The integrated client gate passed 426 tests with
|
||||
zero warnings, errors or skips. Actual in-app update handoff and the historical
|
||||
layout-cycle cause remain separate acceptance items.
|
||||
|
||||
## 0.3.1-rc.1 — 2026-11-01
|
||||
|
||||
- Show explicit WebSocket connection state and server authority in the footer, with live upload/download rates and service-lifetime application-payload totals. A lightweight local observation refresh adds no QQQ job/control polling.
|
||||
- Recognize Windows-normalized startup account names only when they resolve to the exact expected SID; preserve the remaining task ownership checks. Rename the tray startup section to distinguish it from the automatic print service.
|
||||
- Leave the exact fatal native `LayoutCycleException` unhandled after AppKit logs it, allowing normal WinUI termination instead of retaining a corrupted companion window. The service continues; the operator can reopen the companion. This is failure-handling mitigation, not a fix for the original layout trigger.
|
||||
- Add an isolated native WinUI regression host using actual dialog/action/refresh code and synthetic IPC, with no printing or installed-state changes.
|
||||
|
||||
The installed 0.3.0 companion's post-print LayoutCycleException remains under
|
||||
investigation. Nonprinting geometry and modal-refresh scenarios have not
|
||||
reproduced it; these changes do not yet establish a layout-cycle fix.
|
||||
|
||||
## 0.3.0-rc.1 — 2026-10-31
|
||||
|
||||
Upgrade the server before this client: native printing API 2.0 requires a
|
||||
synchronized authenticated WebSocket, with no job/control polling fallback.
|
||||
Installed and physical-output acceptance remain separate from source/test gates.
|
||||
|
||||
- Require the server's printing 2.x extension and authenticated persistent realtime channel. Replace periodic job/control HTTP polling with pushed state, commands, settings and job notifications.
|
||||
- Stream verified documents into protected staging files, with configurable aggregate bandwidth, storage, download concurrency, per-printer ordered submission and native submission deadlines.
|
||||
- Preserve durable receipts and command outcomes across reconnects; keep control traffic responsive during document transfers.
|
||||
- Expand job details and actions directly beneath the selected row, with consistent sortable table headers and bounded history paging.
|
||||
|
||||
## 0.2.0-rc.1 — 2026-10-31
|
||||
|
||||
Release preparation only; publication and installed qualification remain pending.
|
||||
|
||||
Upgrade the server first: the new client requires the semantic printing extension
|
||||
and standard QQQ sign-in; older bearer-only servers need an upgrade. Existing
|
||||
pairings and history are preserved, but unbound devices need explicit account association.
|
||||
|
||||
- Discover QQQ's semantic printing/authentication capabilities and sign in through
|
||||
standard table-based or explicitly advertised native browser authentication.
|
||||
Protect the service session with DPAPI; resume through QQQ and preserve pairing
|
||||
and journals when authorization is lost.
|
||||
- Add independent device-control polling, durable desired state/command receipts
|
||||
and exact owned spool cancellation; disconnect keeps the control path available.
|
||||
- Route normal CLI operations through the authenticated service; direct legacy
|
||||
diagnostics require an explicit compatibility flag.
|
||||
- Add installer-owned browser callback forwarding, cancellable sign-in and
|
||||
customer-branded callback text. Installed callback/provider acceptance remains
|
||||
unqualified; no signing or stable 1.0 readiness is claimed.
|
||||
- Support explicit replacement pairing after revocation and safe recovery from
|
||||
damaged saved credentials. Pending setup survives restart without presenting
|
||||
old device proof or enabling printing; previous history and choices remain intact.
|
||||
- Pass 365 tests and build WinUI/service/CLI with zero warnings/errors/skips.
|
||||
|
||||
## 0.1.9-rc.1 — 2026-10-31
|
||||
## 0.1.9-rc.1 — unreleased
|
||||
|
||||
- Keep management responses available until the client closes its one-command connection or the existing deadline expires. This prevents Windows from discarding unread success and error responses during server disconnect.
|
||||
- Preserve current and older newline-framed clients without a new acknowledgement protocol or a blocking pipe drain. Cancellation and service shutdown remain bounded.
|
||||
- Reproduce the failure through the real runtime with delayed readers; verify successful responses, error responses, next-client reuse, deadlines and shutdown. All eight reproduction cases and 255 combined regression tests pass; the solution/UI build has zero warnings/errors.
|
||||
- Complete the state-preserving CI-package upgrade and all 16 installed UI checks, including authenticated management and history queries. No physical print was requested by these checks.
|
||||
- Publish the corrective prerelease through [release workflow 41190815995](https://github.com/QRun-IO/qqq-print-agent/actions/runs/41190815995); verify all four release assets and provenance attestations. The unsigned published MSI and the installed CI MSI are distinct builds; [acceptance notes](docs/ACCEPTANCE.md) record their hashes and scope.
|
||||
- Reproduce the failure through the real runtime with delayed readers; verify successful responses, error responses, next-client reuse, deadlines and shutdown. The original eight-case private reproduction and all 255 combined regression tests pass; the solution/UI build has zero warnings/errors. Installed qualification remains pending.
|
||||
|
||||
## 0.1.8-rc.1 — audit candidate, superseded before publication
|
||||
|
||||
@@ -225,8 +16,8 @@ pairings and history are preserved, but unbound devices need explicit account as
|
||||
- Package from fresh output directories with locked restores and matching source, MSI and component versions.
|
||||
- Authenticate the installed service before sending local commands, retain pipe ownership, and reject unsafe machine-state owners, access grants or links before privileged use.
|
||||
- Protect sign-in task definitions through registration and validate machine state before an upgrade removes the prior product.
|
||||
- Fresh regression gate: 249 tests, zero build warnings/errors. Installed audit acceptance and hosted provenance verification were pending at this superseded candidate checkpoint; the completed 0.1.9 checks are recorded above.
|
||||
- The local candidate installed successfully with MSI exit 0 and preserved credentials/journal, but a subsequent management-history check exposed the response-disconnect race corrected in 0.1.9. Service heartbeat and printer readiness were confirmed independently through QQQ.
|
||||
- Fresh regression gate: 249 tests, zero build warnings/errors. Installed audit acceptance and hosted provenance verification remain pending.
|
||||
- The local candidate installed successfully with MSI exit 0 and preserved credentials/journal, but a subsequent management-history check exposed the response-disconnect race corrected in 0.1.9. Service heartbeat and both ready printers were confirmed independently through QQQ.
|
||||
|
||||
## 0.1.7-rc.1 — 2026-10-30
|
||||
|
||||
|
||||
@@ -1,95 +1,3 @@
|
||||
# CLAUDE.md
|
||||
# Agent guidance
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
Policy lives in [AGENTS.md](AGENTS.md) (repository rules: hosting split, authorization, logging, printing) and [CONTRIBUTING.md](CONTRIBUTING.md) (conventions, script quality). Read both; this file adds the commands and architecture they leave implicit.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Windows x64, PowerShell 7.4+, .NET SDK pinned by `global.json` (10.0.x).
|
||||
- `qqq-print-protocol` checked out as a **sibling directory** at the SHA pinned in `.github/workflows/ci.yml`. Only `Core.Tests` consumes it (it links `../qqq-print-protocol/fixtures/*.json` at build time; override with `-p:PrintingProtocolFixtures=<dir>` or `Verify.ps1 -ProtocolFixtures`), so the NativeCI solution builds without it.
|
||||
- Scripts tooling: `uv sync --locked` and `npm ci --ignore-scripts` (Node 24+).
|
||||
|
||||
## Commands
|
||||
|
||||
**Host restriction first.** `Qqq.PrintAgent.Core.Tests` is hosted-CI-only. On this development PC, Windows Defender quarantines the Core test assembly, so that project must not be built or run locally (see `docs/SESSION-STATE.md`; do not add exclusions or restore quarantine to work around it). Local work uses `Qqq.PrintAgent.NativeCI.slnx`, which is the full solution minus `Core.Tests`. Core test evidence comes from the hosted Windows CI run on the pushed commit.
|
||||
|
||||
Local default (locked restore, Release x64 build with `-warnaserror`, Windows/CLI tests), always with `-p:Platform=x64` because the solution maps test projects to AnyCPU and a direct `dotnet test` without it picks stale output. Never pass `--no-build` to `dotnet test`: the solution build writes the test DLL to the AnyCPU folder, so an x64 `--no-build` run executes whatever old x64 DLL is lying around and reports a pass against stale code.
|
||||
|
||||
```powershell
|
||||
dotnet restore Qqq.PrintAgent.NativeCI.slnx -p:Platform=x64 --locked-mode
|
||||
dotnet build Qqq.PrintAgent.NativeCI.slnx -c Release -p:Platform=x64 --no-restore -warnaserror
|
||||
dotnet test tests/Qqq.PrintAgent.Cli.Tests -c Release -p:Platform=x64 --no-restore
|
||||
```
|
||||
|
||||
Single test (xunit):
|
||||
|
||||
```powershell
|
||||
dotnet test tests/Qqq.PrintAgent.Cli.Tests -p:Platform=x64 --filter "FullyQualifiedName~AgentPipeSecurityTests"
|
||||
```
|
||||
|
||||
Full verification, **only on a permitted host or hosted CI** (adds Core.Tests, coverage and TRX output under `TestResults/verify-<guid>`; requires the sibling protocol checkout):
|
||||
|
||||
```powershell
|
||||
./build/Verify.ps1
|
||||
```
|
||||
|
||||
Packaging (unsigned self-contained x64 MSI; never installs or prints):
|
||||
|
||||
```powershell
|
||||
./build/Build-Installer.ps1 -ProductVersion 1.0.1 -ReleaseVersion 1.0.1
|
||||
./build/Package-Release.ps1 # runs the CI packaging checks and assembles artifacts/release
|
||||
```
|
||||
|
||||
Script quality gates (CI runs the same):
|
||||
|
||||
```powershell
|
||||
./build/Analyze-Scripts.ps1 # PSScriptAnalyzer 1.25 over build/*.ps1, one rule at a time
|
||||
uv run --locked --no-sync python .github/scripts/test-script-quality.py
|
||||
uv run --locked --no-sync python .github/scripts/check-script-quality.py
|
||||
python .github/scripts/check-source-headers.py # owned-file copyright/SPDX notices
|
||||
npm run typecheck; npm run lint; npm test # tools/virtual-agent (Node, ESLint Allman)
|
||||
```
|
||||
|
||||
Interactive-only suites (not run by hosted CI):
|
||||
|
||||
- **UI tests**: elevated interactive desktop; build the companion, optionally set `K22_UITEST_EXE`, then `dotnet test tests/Qqq.PrintAgent.UiTests -p:Platform=x64`.
|
||||
- **Layout tests**: `tests/Qqq.PrintAgent.LayoutTests/Run.ps1 -EvidenceDirectory <new dir>`; synthetic service only, not in the solution file.
|
||||
|
||||
Pre-commit hooks (`pre-commit install --hook-type pre-commit --hook-type commit-msg`) enforce Conventional Commit types, DCO sign-off (`git commit -s`), gitleaks, and no direct commits to `main`.
|
||||
|
||||
## Architecture
|
||||
|
||||
Five projects, strict layering (Core → Windows → Service/UI/CLI). Business logic never lives above Core; OS calls never live in Core.
|
||||
|
||||
| Project | Owns | Key entry points |
|
||||
| --- | --- | --- |
|
||||
| `Qqq.PrintAgent.Core` | QQQ session auth, HTTP/WSS clients, realtime settings/policy, document streaming, job state machine | `Authentication/QqqSessionClient*`, `Printing/PrintApiClient*`, `Printing/PrintWorker`, `Printing/PrintingRealtimeChannel` |
|
||||
| `Qqq.PrintAgent.Windows` | Spooler/PDF/ZPL backends, SQLite + DPAPI store, named-pipe IPC, the long-running runtime | `AgentRuntime.*.cs` (partial class split by concern), `AgentPipe*`, `AgentStore` |
|
||||
| `Qqq.PrintAgent.Service` | Windows Service host only | `PrintService.cs` |
|
||||
| `Qqq.PrintAgent` | WinUI/AppKit companion: tray, Printers/Jobs/Logs/Settings views, MSI update UX | `MainWindow.*.cs` (partial class split by concern) |
|
||||
| `Qqq.PrintAgent.Cli` | Authenticated service management over the pipe; isolated legacy diagnostics | `Program.cs` |
|
||||
|
||||
Large classes are deliberately split into partial files by concern (`AgentRuntime.Realtime.cs`, `AgentRuntime.Jobs.cs`, `MainWindow.Updates.cs`, ...). Add new behavior to the matching partial rather than growing `AgentRuntime.cs` / `MainWindow.xaml.cs`.
|
||||
|
||||
**Runtime model.** The service is the only process holding credentials, the journal and printer access. It opens an outbound authenticated WebSocket (`/qqq/v1/qbit/printing/device/realtime`, subprotocol `qqq-printing.v1`) for commands, status and job notifications; documents stream separately over HTTPS into a protected staging directory with length + SHA-256 verification. There is intentionally **no polling fallback**. The companion and CLI talk to the service only through the `QqqPrintAgent` named pipe (administrator clients) and receive credential-free snapshots. Printing runs in an isolated child process with a deadline. See `docs/REALTIME.md` for the worker split, bounds and reconnect rules.
|
||||
|
||||
**Reliability boundary.** `PrintWorker` persists receipt and `SUBMITTING` before calling Windows, records `SPOOLED` plus the spooler job ID afterward, and replays pending cloud events. A crash between spool acceptance and recording is not atomic; the worker reports `OUTCOME_UNKNOWN` rather than auto-reprinting. Preserve this distinction in any retry/cancel change, and keep "spool accepted" and "paper came out" separate in docs and messages.
|
||||
|
||||
**Versions.** Product version (`VersionPrefix` in `Directory.Build.props`, release workflow overrides with `-p:Version`), native printing API (2.3), wire payload (v1) and the WebSocket subprotocol are independent. Do not conflate them when bumping.
|
||||
|
||||
**Updates.** `MsiUpdateService` + `GitHubMsiReleaseClient` read the GitHub release feed and apply a machine MSI through Windows Installer, updating service, companion and CLI together. That GitHub feed is why the GitHub shadow must stay even though Gitea is primary.
|
||||
|
||||
## Test layout
|
||||
|
||||
- `tests/Qqq.PrintAgent.Core.Tests`: protocol fixtures (`ProtocolFixtureTests`), loopback WebSocket peer, worker state machine, media contracts. Hosted CI only on this PC (see Commands); new Core tests are written here and validated by the CI run.
|
||||
- `tests/Qqq.PrintAgent.Cli.Tests`: despite the name, this is the Windows runtime suite (`AgentRuntime*`, `AgentRealtime*`, `AgentPipe*`, `AgentStore*`). Put Windows-layer tests here.
|
||||
- `tests/Qqq.PrintAgent.WorkerFixture`: child-process fixture used by runtime tests.
|
||||
|
||||
## Conventions worth knowing
|
||||
|
||||
- `.editorconfig`: 3-space indentation, Allman braces, everywhere (C#, PowerShell, scripts). Analyzers run in build; zero warnings is enforced by `TreatWarningsAsErrors`.
|
||||
- Every owned source file starts with the `Copyright (c) 2026 James Maes` / `SPDX-License-Identifier: MIT` header; `check-source-headers.py` fails otherwise. `tools/virtual-agent` keeps its QRun.IO attribution.
|
||||
- Package versions are central (`Directory.Packages.props`); after changing them, regenerate each affected `packages.lock.json` (`dotnet restore --force-evaluate`).
|
||||
- Coverage is reported, not gated, per `docs/adr/0002-prerelease-quality-and-packaging.md`.
|
||||
- `docs/SESSION-STATE.md` records the current release/verification state; consult it before claiming anything is verified.
|
||||
See [AGENTS.md](AGENTS.md) for repository instructions and [CONTRIBUTING.md](CONTRIBUTING.md) for development conventions.
|
||||
+4
-20
@@ -1,22 +1,20 @@
|
||||
# Contributing
|
||||
|
||||
QQQ Print Agent is developed in the [QRun-IO organization on Gitea](https://git.kof22.com/QRun-IO). It uses the KofTwentyTwo Windows AppKit service architecture. Contributions are accepted under the [MIT license](LICENSE); preserve existing attribution.
|
||||
QQQ Print Agent is developed in the [QRun-IO organization](https://github.com/QRun-IO). It uses the KofTwentyTwo Windows AppKit service architecture. Contributions are accepted under the [MIT license](LICENSE); preserve existing attribution.
|
||||
|
||||
## Set up
|
||||
|
||||
Use Windows x64, Git and the .NET 10 SDK selected by `global.json`. Check out `qqq-print-agent` and `qqq-print-protocol` into sibling directories. Check out the protocol commit pinned in `.github/workflows/ci.yml` (`42c0d249f81395f00408ec0f92638dcbbf5deb03`, [Gitea PR 2](https://git.kof22.com/QRun-IO/qqq-print-protocol/pulls/2)); its JSON fixtures are linked into the contract tests.
|
||||
Use Windows x64, Git and the .NET 10 SDK selected by `global.json`. Check out `qqq-print-agent` and `qqq-print-protocol` into sibling directories. Check out the protocol commit pinned in `.github/workflows/ci.yml`; its JSON fixtures are linked into the contract tests.
|
||||
|
||||
```powershell
|
||||
./build/Verify.ps1
|
||||
./build/Build-Installer.ps1 -ProductVersion 1.0.1 -ReleaseVersion 1.0.1
|
||||
./build/Build-Installer.ps1 -ProductVersion 0.1.0 -ReleaseVersion 0.1.0-rc.1
|
||||
```
|
||||
|
||||
Verification uses locked NuGet restore, a warnings-as-errors solution build, core tests, Windows/CLI tests and a coverage report. Packaging creates a self-contained x64 MSI. Neither command installs the service or prints a document.
|
||||
|
||||
## Changes and review
|
||||
|
||||
Publish ordinary branches and pull requests to the [primary Gitea repository](https://git.kof22.com/QRun-IO/qqq-print-agent). GitHub is a source shadow; the existing authorized release/signing workflow and CI/security workflows remain there. GitHub release assets also serve the installed updater. See [Releasing](docs/RELEASING.md) before changing either distribution path.
|
||||
|
||||
- Branch from `main`, use Conventional Commit titles, and include a DCO sign-off (`git commit -s`). Sign commits where your account supports signing.
|
||||
- Keep business/protocol logic in Core, Windows integration in Windows, hosting in Service, and view/tray plumbing in the AppKit companion.
|
||||
- Use central versions in `Directory.Packages.props`; regenerate affected `packages.lock.json` files when dependencies change.
|
||||
@@ -36,18 +34,4 @@ A passing unit suite does not establish printer compatibility. Record Windows ve
|
||||
|
||||
## Issues and releases
|
||||
|
||||
Open ordinary bugs or proposals in [Issues](https://git.kof22.com/QRun-IO/qqq-print-agent/issues). Use [private security reporting](SECURITY.md) for vulnerabilities. Release authorization and tagging belong to maintainers; see [RELEASING.md](docs/RELEASING.md).
|
||||
|
||||
## Script quality
|
||||
|
||||
Owned scripts follow the KofTwentyTwo standard at revision `fbfc8d2cf3b5e16ae9750b04cf9de1794f1e7152` (configs adapted from its `python` and `typescript` profiles): three-space indentation, Ruff 0.17.3 format/lint (locked in `uv.lock`) and strict Pyright 1.1.414 (Microsoft's npm package, locked in `package-lock.json` and run through Node) for `.github/scripts/*.py`, and ESLint 10 with Stylistic (Allman) plus strict `tsc` over JSDoc for `tools/**/*.mjs` and `eslint.config.mjs`. Restore with `uv sync --locked` and `npm ci --ignore-scripts`, then run:
|
||||
|
||||
```text
|
||||
uv run --locked --no-sync python .github/scripts/test-script-quality.py
|
||||
uv run --locked --no-sync python .github/scripts/check-script-quality.py
|
||||
npm run typecheck
|
||||
npm run lint
|
||||
npm test
|
||||
```
|
||||
|
||||
`check-script-quality.py` fails for any tracked Python outside `.github/scripts/` or JavaScript outside the `tsconfig.json` include list, and requires Pyright's analyzed-file count to equal the selected scripts. Pyright must run as `pyright -p .github`: it silently skips dot directories from a root config. Documented exceptions: CLI `print`/`console.log` only in `check-*.py` and `tools/`; synthetic test assertions and boundary constants; narrow inline `noqa` comments for fixed no-shell Git/interpreter calls and ordered fail-closed validators. Do not loosen a rule or add a type waiver to pass. `package.json` overrides `minimatch` to 11.0.1, the patched release for [GHSA-g3hv-75wg-m249](https://github.com/advisories/GHSA-g3hv-75wg-m249) (affected before 11.0.1); keep it until ESLint's own dependency range includes a patched release. The only npm license exception, [EX-0015](https://github.com/KofTwentyTwo/standards/blob/main/exceptions/register.md#ex-0015) for development-only `uri-js` 4.4.1, is enforced by `check-script-quality.py` (version, lock integrity, installed license bytes and the exact `pkg:npm/uri-js` caller entry); changing that package or the entry needs renewed approval. The virtual agent's existing QRun.IO attribution is unchanged.
|
||||
Open ordinary bugs or proposals in [Issues](https://github.com/QRun-IO/qqq-print-agent/issues). Use [private security reporting](SECURITY.md) for vulnerabilities. Release authorization and tagging belong to maintainers; see [RELEASING.md](docs/RELEASING.md).
|
||||
+3
-13
@@ -1,8 +1,3 @@
|
||||
<!--
|
||||
Copyright (c) 2026 James Maes
|
||||
SPDX-License-Identifier: MIT
|
||||
-->
|
||||
|
||||
<Project>
|
||||
|
||||
<!-- KofTwentyTwo .NET quality gate (standards: K22-CODE-CS, from
|
||||
@@ -60,19 +55,14 @@
|
||||
commit as "+<sha>" on AssemblyInformationalVersion, which the About dialog and the
|
||||
CLI's version output show as a short hash. -->
|
||||
<PropertyGroup>
|
||||
<VersionPrefix>1.2.1</VersionPrefix>
|
||||
<VersionSuffix></VersionSuffix>
|
||||
<VersionPrefix>0.1.9</VersionPrefix>
|
||||
<VersionSuffix>rc.1</VersionSuffix>
|
||||
</PropertyGroup>
|
||||
|
||||
<!-- Product metadata stamped into every assembly. A client edition build (build/Build-Installer.ps1 -Edition)
|
||||
passes BrandProduct and BrandCompany, so each executable's product, company and file description carry the
|
||||
client's brand; author and copyright stay with the source. -->
|
||||
<!-- Product metadata stamped into every assembly. -->
|
||||
<PropertyGroup>
|
||||
<Authors>James Maes</Authors>
|
||||
<Product>QQQ Print Agent</Product>
|
||||
<Product Condition="'$(BrandProduct)' != ''">$(BrandProduct)</Product>
|
||||
<AssemblyTitle Condition="'$(BrandProduct)' != ''">$(BrandProduct)</AssemblyTitle>
|
||||
<Company Condition="'$(BrandCompany)' != ''">$(BrandCompany)</Company>
|
||||
<Copyright>Copyright (c) 2026 James Maes</Copyright>
|
||||
<RepositoryUrl>https://github.com/QRun-IO/qqq-print-agent</RepositoryUrl>
|
||||
<RepositoryType>git</RepositoryType>
|
||||
|
||||
@@ -1,8 +1,3 @@
|
||||
<!--
|
||||
Copyright (c) 2026 James Maes
|
||||
SPDX-License-Identifier: MIT
|
||||
-->
|
||||
|
||||
<Project>
|
||||
|
||||
<!-- Central package management (K22-CODE-CS-08): every version lives here, so
|
||||
|
||||
@@ -12,21 +12,5 @@ SQLitePCLRaw, CommunityToolkit.Mvvm and WiX. These projects retain their own
|
||||
licenses and copyright notices. Windows OS printing/PDF components and bundled
|
||||
Microsoft runtime binaries remain subject to their corresponding terms.
|
||||
|
||||
The 15 pinned Microsoft Windows SDK packages retain their separate terms,
|
||||
not this project's MIT license. Their five distinct license texts and five
|
||||
distinct notices are preserved unmodified under licenses/ in this repository
|
||||
and ThirdPartyNotices/ in the installed App directory. The package-to-terms
|
||||
mapping and exact versions/hashes are in windows-sdk-packages.json there.
|
||||
See docs/WINDOWS-SDK-LICENSES.md for the exact package scope, including both
|
||||
ML packages' provider terms and the SDK reference-pack runtime projections.
|
||||
Microsoft.Windows.SDK.BuildTools and Microsoft.Windows.SDK.BuildTools.MSIX
|
||||
are build-only; their tooling is not part of the application payload.
|
||||
Preserving these notices does not establish fulfillment of every Microsoft
|
||||
redistribution or end-user protection obligation.
|
||||
|
||||
The QQQ framework, qbit-printing and qqq-print-protocol are separate repositories;
|
||||
this notice does not change their licensing.
|
||||
|
||||
The About dialog bundles Query, the QQQ and QRun.IO dog mascot, supplied by
|
||||
QRun.IO. The unmodified artwork and provenance are in Assets/Query in the
|
||||
application payload and src/Qqq.PrintAgent/Assets/Query in this repository.
|
||||
@@ -1,6 +1,3 @@
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
# KofTwentyTwo PowerShell analysis (K22-CODE-SH-05). CI runs:
|
||||
# ./build/Analyze-Scripts.ps1 (serial rule execution avoids upstream metadata races)
|
||||
# and `Invoke-Formatter` with the same settings for layout. PowerShell supports the
|
||||
|
||||
@@ -1,23 +0,0 @@
|
||||
<Solution>
|
||||
<Configurations>
|
||||
<Platform Name="ARM64" />
|
||||
<Platform Name="x64" />
|
||||
<Platform Name="x86" />
|
||||
</Configurations>
|
||||
<Folder Name="/src/">
|
||||
<Project Path="src/Qqq.PrintAgent/Qqq.PrintAgent.csproj">
|
||||
<Platform Solution="*|ARM64" Project="ARM64" />
|
||||
<Platform Solution="*|x64" Project="x64" />
|
||||
<Platform Solution="*|x86" Project="x86" />
|
||||
</Project>
|
||||
<Project Path="src/Qqq.PrintAgent.Core/Qqq.PrintAgent.Core.csproj" />
|
||||
<Project Path="src/Qqq.PrintAgent.Cli/Qqq.PrintAgent.Cli.csproj" />
|
||||
<Project Path="src/Qqq.PrintAgent.Windows/Qqq.PrintAgent.Windows.csproj" />
|
||||
<Project Path="src/Qqq.PrintAgent.Service/Qqq.PrintAgent.Service.csproj" />
|
||||
</Folder>
|
||||
<Folder Name="/tests/">
|
||||
<Project Path="tests/Qqq.PrintAgent.Cli.Tests/Qqq.PrintAgent.Cli.Tests.csproj" />
|
||||
<Project Path="tests/Qqq.PrintAgent.UiTests/Qqq.PrintAgent.UiTests.csproj" />
|
||||
<Project Path="tests/Qqq.PrintAgent.WorkerFixture/Qqq.PrintAgent.WorkerFixture.csproj" />
|
||||
</Folder>
|
||||
</Solution>
|
||||
@@ -4,100 +4,103 @@
|
||||
<!-- markdownlint-disable-next-line MD033 -->
|
||||
<img src="src/Qqq.PrintAgent/Assets/Brand/app-preview.png" width="96" alt="QQQ Print Agent cloud and printer icon">
|
||||
|
||||
[](https://github.com/QRun-IO/qqq-print-agent/actions/workflows/ci.yml)
|
||||
[](LICENSE)
|
||||
|
||||
Print from **QQQ 4.1+** to local Windows printers without opening inbound network ports. The Windows service opens an authenticated two-way WebSocket to QQQ for commands, status and job notifications. Documents download separately over HTTPS, so a large transfer does not block the control connection. There is no job/control polling fallback.
|
||||
Print from **QQQ 4.1+** to printers at a local facility without opening inbound network ports. QQQ Print Agent runs as a Windows service, connects outward to QQQ, and submits documents to the printers installed for its Windows service account.
|
||||
|
||||
**Current stable release: [1.2.1](https://git.kof22.com/QRun-IO/qqq-print-agent/releases/tag/v1.2.1)** (generic and GG Forge edition installers). The service, companion, CLI and MSI are signed with Azure Artifact Signing. The matching server release is [qbit-printing 1.1.0](https://git.kof22.com/QRun-IO/qbit-printing/releases/tag/v1.1.0), using QQQ **4.1.0-RC.21** for native session login, with [protocol 1.1.0](https://git.kof22.com/QRun-IO/qqq-print-protocol/releases/tag/v1.1.0); 1.2.1 also works unchanged against qbit-printing 1.0.0. Product versions are separate from native printing API **2.4** (2.3 compatible), wire payload **v1** and WebSocket subprotocol `qqq-printing.v1`.
|
||||
The native setup and status application uses the same [KofTwentyTwo AppKit](https://github.com/KofTwentyTwo/AppKit) foundation as GCLO and MarkdownViewr.Windows.
|
||||
|
||||
The setup/status application uses the same [KofTwentyTwo AppKit](https://git.kof22.com/KofTwentyTwo/AppKit) foundation as GCLO and MarkdownViewr.Windows. QQQ's mascot Query appears in About and branded warehouse test documents.
|
||||
> **Prerelease software.** Published v0.1.7-rc.1 assets are verified. Installed 0.1.7 passed 227 unit/regression tests and all 16 UI checks in one run. The user confirmed laser PDF, Zebra ZPL and Zebra PDF output; the PDF label required correcting machine printer defaults to 4 × 6-inch direct thermal. Barcode scanning and measured alignment remain unverified. The MSI remains unsigned.
|
||||
|
||||
## Install and connect
|
||||
## What works
|
||||
|
||||
1. Download `QqqPrintAgent-v1.2.1-x64.msi` (or a client edition such as `GgForgePrintAgent-v1.2.1-x64.msi`; one edition per PC) and `SHA256SUMS` from the [stable release](https://git.kof22.com/QRun-IO/qqq-print-agent/releases/tag/v1.2.1). Check the checksum and Authenticode signature as described in [Installation](docs/INSTALLATION.md).
|
||||
2. Install with administrator rights. The MSI installs the automatic Windows service and adds **QQQ Print Agent** under **Print Connectors** in Start.
|
||||
3. Open the app and accept its administrator prompt. Choose **Settings → Server connection → Sign in / Connection settings**, enter the QQQ HTTPS server address and select **Discover sign-in options**. Sign in using the advertised username/password or browser flow.
|
||||
4. For a new device, create an enrollment code in QQQ under **Printing → Print devices → Actions → Enroll a print device**, then enter it in the client. Existing pairings are reused or explicitly associated with the signed-in account; routine upgrades do not need a replacement pairing.
|
||||
5. In **Printers**, choose which queues to share. Enable the intended discovered queue in QQQ, then submit an authorized test print matched to the loaded paper or labels.
|
||||
|
||||
The service uses machine-installed printers available to its LocalSystem account. A printer mapped only in a user's profile may be unavailable. The QQQ endpoint needs outbound HTTPS and WebSocket upgrades; HTTP/WS is accepted only for loopback development. No inbound firewall rule is installed.
|
||||
|
||||
See [User guide](docs/USER-GUIDE.md), [QQQ sign-in](docs/QQQ-SIGN-IN.md) and [Troubleshooting](docs/TROUBLESHOOTING.md).
|
||||
|
||||
## Daily use
|
||||
|
||||
- **Printers:** share queues, sort columns, expand a selected row, or double-click to edit its name, description and location. The same metadata is reported to QQQ.
|
||||
- **Jobs:** sort and search paged history, expand a selected row for recent events, or double-click for full details. Printers default to Name ascending; jobs default to Created descending. Reprint and cancellation actions require confirmation.
|
||||
- **Logs:** service and companion events share the AppKit viewer, with live follow, error filtering, copying and folder access. Settings controls daily rotation, retention, size limits and clearing diagnostic logs.
|
||||
- **Settings:** select the server and sign in, edit computer details, control the Windows service, choose theme and startup preferences, or check for updates.
|
||||
- **Footer and tray:** show connection/printer health. The footer exposes the server address, reconnect/log shortcuts and live application upload/download counters. Printer status is an observation from Windows, not proof of paper output.
|
||||
- **Background printing:** the Windows service keeps working when the companion is closed or the user logs out. Optional tray startup is a separate setting.
|
||||
|
||||
QQQ can see devices, exposed printers, status, jobs and queue history. Its authorized device actions control dispatch, disconnect/reconnect operation, refresh inventory and revoke credentials. Current QQQ user, tenant, table, process and record permissions apply to client operations; a device token does not replace user authority.
|
||||
- Discover Windows print queues and explicitly choose which ones to expose to QQQ.
|
||||
- Use native Printers, Jobs, Logs and Settings navigation, persistent status, reconnect and a visible health tray icon.
|
||||
- Browse compact printer/job tables with full details and confirmed test/reprint/cancel actions. Expand printer information inside the selected row and open printer settings or job details on double-click.
|
||||
- Sort table headers in either direction. Printers default to Name ascending; jobs default to immutable Created time descending. Job sorting applies across the matching result set before paging.
|
||||
- Page through local history in groups of 50, searching by job ID, document-title or printer-name prefix.
|
||||
- Edit computer/printer names, descriptions and locations locally and synchronize them to QQQ.
|
||||
- Configure daily log retention/size limits, inspect usage and explicitly clear diagnostic logs.
|
||||
- Start/restart the service and opt into tray startup at sign-in; service and companion share the AppKit log viewer.
|
||||
- Check for updates manually or at startup using AppKit; confirm a machine MSI upgrade of the service, companion and CLI together.
|
||||
- Set theme and splash duration, and open project/help/release links and dependency credits.
|
||||
- Print packing slips and other PDFs through the installed Windows driver.
|
||||
- Send printer-ready ZPL to Zebra/ZDesigner queues.
|
||||
- Generate one QQQ-branded warehouse diagnostic at a time: Letter, A4 or 4 × 6-inch PDF; 4 × 6-inch ZPL at 203, 300 or 600 dpi. Native choices prefer ZPL on compatible label queues, with a driver-name DPI suggestion that the operator verifies.
|
||||
- Enroll once using a short-lived code from QQQ; the service stores its own protected device credential.
|
||||
- Keep printing when the desktop app is closed or the user logs out.
|
||||
- Preserve job receipts and outgoing status events across service restarts.
|
||||
- Avoid automatically printing a job again when a previous submission is uncertain.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Q[QQQ printing QBit] <-->|Client-initiated WSS: commands and receipts| S[Windows service]
|
||||
Q -->|Separate streamed HTTPS documents| S
|
||||
Q[QQQ 4.1+ printing QBit] <-->|Outbound HTTPS polling| S[Windows service]
|
||||
U[AppKit setup and status app] -->|Local administrator pipe| S
|
||||
S --> W[Windows spooler]
|
||||
W --> L[Laser printer: PDF]
|
||||
W --> Z[Zebra printer: ZPL]
|
||||
```
|
||||
|
||||
## Documents and printer media
|
||||
The companion projects are [qbit-printing](https://github.com/QRun-IO/qbit-printing), the QQQ server integration, and [qqq-print-protocol](https://github.com/QRun-IO/qqq-print-protocol), the shared versioned API contract. The agent does not require a separate cloud printing vendor.
|
||||
|
||||
The service prints PDFs through the Windows driver and sends printer-ready ZPL to compatible Zebra/ZDesigner queues. Test prints offer Letter and A4 PDF, plus 4 × 6, 4 × 2 and 4 × 1-inch PDF/ZPL labels; ZPL offers 203, 300 and 600 dpi. Match the actual stock and printer resolution before printing. Query branding, warehouse-readable characters and alignment marks make the diagnostics easy to identify.
|
||||
## Install and connect
|
||||
|
||||
The client reports the Windows queue's machine-default media as a revision-bound profile. It does not detect which stock is physically loaded. Selected media is checked before submission; a stale selection is refused. PDF jobs can instead request an explicit width/height pair for that job without changing the queue defaults. The short-label PDF tests use this path. See [Printer media](docs/PRINTER-MEDIA.md).
|
||||
1. Download the x64 MSI and `SHA256SUMS` from [Releases](https://github.com/QRun-IO/qqq-print-agent/releases). Verify the checksum before installing.
|
||||
2. Install the MSI with administrator rights. It installs the service and adds **QQQ Print Agent**, or your configured customer label, under **Print Connectors** in the Start menu.
|
||||
3. In your QQQ printing administration, create an enrollment code for this facility/device.
|
||||
4. Open **QQQ Print Agent**, accept the administrator prompt, enter the QQQ server URL and enrollment code, and select **Connect**.
|
||||
5. In **Printers**, select which queues to expose to QQQ. Then enable the intended discovered queue in QQQ and submit a test document.
|
||||
|
||||
`SPOOLED` means Windows accepted the job; it does not prove that paper came out. `OUTCOME_UNKNOWN` means a submission may have reached the printer. Inspect the output before requesting another copy. Retained receipts prevent uncertain jobs from being silently printed again.
|
||||
The QQQ URL must use HTTPS. HTTP is accepted only for loopback development such as `http://localhost:18081`. No inbound firewall rule is installed. Existing outbound proxy/network policies and local printer connectivity still apply.
|
||||
|
||||
## Requirements and limits
|
||||
See the [installation guide](docs/INSTALLATION.md) for verification, service identity, upgrade and removal instructions, and the [user guide](docs/USER-GUIDE.md) for the setup screen and job statuses.
|
||||
|
||||
| Area | Stable 1.2.1 behavior |
|
||||
## Requirements and supported behavior
|
||||
|
||||
| Area | Initial support |
|
||||
| --- | --- |
|
||||
| Server | QQQ 4.1+; recommended cohort QQQ 4.1.0-RC.21 and qbit-printing 1.0.0, native printing API 2.3 |
|
||||
| Server | QQQ 4.1+ with the printing QBit and protocol v1 |
|
||||
| Windows | x64; Windows 11 used for hardware acceptance; API target Windows 10 build 19041+ |
|
||||
| Runtime | Bundled with the MSI; users do not install .NET separately |
|
||||
| Printers | Installed Windows queues accessible to the service account |
|
||||
| Documents | PDF and ZPL; default limits 100 MiB PDF and 20 MiB ZPL, configurable by authorized QQQ administrators |
|
||||
| Transport | Outbound authenticated WSS plus same-origin HTTPS document streams, with automatic reconnect |
|
||||
| Capacity | Bounded download/print concurrency, staging, bandwidth and timeouts; one download and one print lane by default, ordered per printer |
|
||||
| Local history | 50-row pages; default detailed retention 30 days or latest 300,000 detailed jobs, with active/uncertain evidence and duplicate-suppression records retained |
|
||||
| Diagnostic logs | Daily rotation plus size rollover to numbered segments; defaults 30 days, 100 MiB per file and 10 segments per day, with optional debug logging, configurable in the client |
|
||||
| Printers | Installed Windows queues accessible to LocalSystem, the default service account |
|
||||
| Documents | PDF and ZPL, at most 20 MiB per job |
|
||||
| PDF options | Copies, actual size or fit; queue-default paper/tray settings |
|
||||
| ZPL options | Copies; label dimensions/DPI encoded in printer-ready ZPL |
|
||||
| Transport | Outbound HTTPS polling, normally every five seconds |
|
||||
|
||||
The client supports native printing extension `>=2.0.0 <3.0.0`; optional media negotiation requires stable extension 2.3 or later in that major. Limits are resource bounds, not a printer-throughput guarantee. See [Realtime settings](docs/REALTIME.md) and [History and log limits](docs/SCALABILITY.md).
|
||||
A printer visible only in a signed-in user's profile may not be available to the service. Configure the printer for the machine and test through the installed service. Virtual PDF/fax queues are not suitable for unattended physical printing.
|
||||
|
||||
## Updates and customer branding
|
||||
`SPOOLED` means Windows accepted the job. It does **not** prove that paper came out. If the agent cannot determine whether a previous submission succeeded, it reports `OUTCOME_UNKNOWN`; an operator should inspect the printer before requesting another copy.
|
||||
|
||||
Use **Help → Check for updates** or the same button in Settings. Startup checks are optional; installation requires confirmation and updates the service, companion and CLI together. Stable installations receive newer stable releases. The installed updater reads the project's [GitHub release feed](https://github.com/QRun-IO/qqq-print-agent/releases); this feed remains available alongside the primary Gitea releases.
|
||||
## Validation so far
|
||||
|
||||
Customers can supply a name, company, support link, colors and local artwork during installation using the shared MSI and `Install-Branded.ps1`. No custom build is needed. Branding preserves the software's signing identity, protocol and update feed. See [Customer branding](docs/BRANDING.md).
|
||||
Installed **0.1.7, source 93dd5fc**, completed with MSI exit 0 and no reboot, retaining credentials. Management, computer profile, paged history, log settings, branded shortcut and connected-state checks passed. The source gate passed **227 tests (57 Core + 170 Windows/CLI)** with zero warnings/errors; [exact-source CI 41139885687](https://github.com/QRun-IO/qqq-print-agent/actions/runs/41139885687) passed. All **16 installed UI checks passed in one run**, including the diagnostic media/DPI dialog, which was closed without printing during the UI test.
|
||||
|
||||
## Development and contributions
|
||||
The initial laser PDF and Zebra ZPL diagnostics were physically confirmed. The first Zebra PDF was accepted by the spooler but did not print: machine driver defaults were 4.09 × 2-inch Thermal Transfer. After correcting them to 4 × 6-inch Thermal Direct and clearing the hardware pause, one fresh reviewed PDF printed fully and correctly, as confirmed by the user. Barcode scanning and measured alignment remain unverified. See [the configuration diagnosis](docs/ACCEPTANCE.md).
|
||||
|
||||
Source, branches, issues and pull requests are maintained on [Gitea](https://git.kof22.com/QRun-IO/qqq-print-agent). GitHub is the automatic source shadow and the existing authorized signing/update distribution bridge; do not push ordinary source changes there.
|
||||
[Release workflow 41140882339](https://github.com/QRun-IO/qqq-print-agent/actions/runs/41140882339) succeeded. [v0.1.7-rc.1](https://github.com/QRun-IO/qqq-print-agent/releases/tag/v0.1.7-rc.1) is published, and its MSI, SHA256SUMS and two branding assets were verified. The MSI remains unsigned. The earlier unexplained clean service stop remains unresolved. These checks used the paired loopback QQQ server and do not establish a remote-cloud deployment, broad driver qualification or every accessibility scenario.
|
||||
|
||||
Use Windows x64 and the .NET 10 SDK selected by `global.json`. Clone the protocol repository beside the client and check out the fixture commit pinned by CI:
|
||||
Earlier laser paper output was confirmed on prior builds; those confirmations and historical installed results remain in [acceptance notes](docs/ACCEPTANCE.md).
|
||||
|
||||
## Development
|
||||
|
||||
Requires Windows x64 and the .NET 10 SDK selected by `global.json`. Check out this repository and the protocol repository as siblings; use the pinned protocol commit in `.github/workflows/ci.yml`.
|
||||
|
||||
```powershell
|
||||
git clone https://git.kof22.com/QRun-IO/qqq-print-agent.git
|
||||
git clone https://git.kof22.com/QRun-IO/qqq-print-protocol.git
|
||||
git -C qqq-print-protocol checkout 42c0d249f81395f00408ec0f92638dcbbf5deb03
|
||||
git clone https://github.com/QRun-IO/qqq-print-agent.git
|
||||
git clone https://github.com/QRun-IO/qqq-print-protocol.git
|
||||
Set-Location qqq-print-agent
|
||||
./build/Verify.ps1
|
||||
./build/Build-Installer.ps1 -ProductVersion 1.2.1 -ReleaseVersion 1.2.1
|
||||
./build/Build-Installer.ps1 -ProductVersion 0.1.9 -ReleaseVersion 0.1.9-rc.1
|
||||
```
|
||||
|
||||
Run verification only on a permitted Windows test host; host-specific restrictions remain in force. Local packaging is unsigned unless explicitly signed; stable release signing runs through the protected workflow. Neither command installs the service or sends a physical print.
|
||||
[History and log limits](docs/SCALABILITY.md) · [Customer branding](docs/BRANDING.md) · [Developer guide](docs/DEVELOPMENT.md) · [Administrator guide](docs/ADMINISTRATION.md) · [Troubleshooting](docs/TROUBLESHOOTING.md) · [Release process](docs/RELEASING.md) · [Contributing](CONTRIBUTING.md) · [Security policy](SECURITY.md)
|
||||
|
||||
[Contributing](CONTRIBUTING.md) · [Developer guide](docs/DEVELOPMENT.md) · [Administrator guide](docs/ADMINISTRATION.md) · [Release process](docs/RELEASING.md) · [Security policy](SECURITY.md)
|
||||
## Current limits
|
||||
|
||||
## Release evidence
|
||||
|
||||
The signed 1.2.1 release passed its protected build, test, security, CodeQL, script and per-edition signing workflow (run 42223525626); checksums, Authenticode signatures and provenance attestations were verified on the published generic and GG Forge installers, and the GG Forge installer was upgraded in place on the development PC with pairing, session and settings preserved. The earlier signed 1.0.1 release passed its protected build, test, security, CodeQL, script and signing workflow. Published checksums, signatures and provenance were verified. The local 1.0.1 MSI upgrade completed successfully on 2026-11-03 with matching app/service/CLI versions and a running service. Dated hardware and earlier upgrade evidence remains in [Acceptance](docs/ACCEPTANCE.md); current release status is in [Release readiness](docs/RELEASE-READINESS.md). Earlier test results retain their original version and scope.
|
||||
This prerelease uses polling rather than WebSocket notifications. Custom PDF paper dimensions are rejected; use the Windows queue's default media. Operator actions, safe journal detail retention and bounded renderer subprocesses are implemented. Physical completion telemetry, custom media and production signing remain outside the initial deployment scope. Update checks are implemented; installation requires operator confirmation and administrator rights. Review the [roadmap](docs/TODO.md) before a production rollout.
|
||||
|
||||
## License and acknowledgments
|
||||
|
||||
[MIT](LICENSE). Original Windows template and AppKit notices are preserved in [NOTICE](NOTICE). QQQ and its printing QBit are separate projects with their own licenses. Microsoft Windows SDK components retain their [separate terms](docs/WINDOWS-SDK-LICENSES.md); the installed app includes their license texts and notices.
|
||||
[MIT](LICENSE). The original Windows template and AppKit copyright notices are preserved. See [NOTICE](NOTICE) for the foundation and bundled dependency acknowledgments. QQQ and the printing QBit are separate projects with their own licenses.
|
||||
+2
-2
@@ -4,7 +4,7 @@
|
||||
|
||||
Do not publish a security vulnerability as a normal issue. Use [GitHub private vulnerability reporting](https://github.com/QRun-IO/qqq-print-agent/security/advisories/new). Include the affected version, reproduction steps, impact and sanitized evidence. Do not send live enrollment codes, device credentials, customer documents or local print databases.
|
||||
|
||||
Fixes target the latest stable 1.0 release. There is no long-term support commitment or independently audited production security certification. Gitea is the primary source repository; the established private reporting channel above remains available on GitHub.
|
||||
The initial release is a prerelease for controlled evaluation. Fixes target the latest prerelease; there is no long-term support commitment or independently audited production security certification.
|
||||
|
||||
## Trust and privileges
|
||||
|
||||
@@ -16,6 +16,6 @@ Remote QQQ endpoints require HTTPS. Plain HTTP is allowed only on loopback for d
|
||||
|
||||
## Distribution
|
||||
|
||||
Stable **1.0.1** publishes an Azure Artifact Signing-signed MSI and first-party executables, `SHA256SUMS` and build provenance. Download from the [official release](https://git.kof22.com/QRun-IO/qqq-print-agent/releases/tag/v1.0.1) and verify both checksum and Authenticode signature. The installed updater uses the matching GitHub release assets. Earlier unsigned prereleases retain their historical status; signing does not establish printer compatibility or make arbitrary printer documents safe. See [Installation](docs/INSTALLATION.md) and [release signing](docs/RELEASE-SIGNING.md).
|
||||
The v0.1.0-rc.1 MSI and first-party executables are **unsigned**. Download from the official repository release and compare SHA256SUMS. No Authenticode identity or provenance attestation is claimed. Production signing, renderer process isolation, broader driver testing and operational hardening remain open work.
|
||||
|
||||
See [the threat model](docs/security/threat-model.md) for implemented controls and residual risks.
|
||||
+2
-2
@@ -1,5 +1,5 @@
|
||||
# Support
|
||||
|
||||
Use [Gitea Issues](https://git.kof22.com/QRun-IO/qqq-print-agent/issues) for bugs, setup questions and feature requests. Check the [installation](docs/INSTALLATION.md) and [troubleshooting](docs/TROUBLESHOOTING.md) guides first. Include version, Windows build, printer/driver and sanitized error details.
|
||||
Use [GitHub Issues](https://github.com/QRun-IO/qqq-print-agent/issues/new/choose) for bugs, setup questions and feature requests. Check the installation and troubleshooting guides first. Include version, Windows build, printer/driver and sanitized error details.
|
||||
|
||||
Do not attach enrollment codes, credentials, customer documents or local journals. Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md). No commercial support SLA is implied.
|
||||
Do not attach enrollment codes, credentials, customer documents or local journals. Report vulnerabilities privately as described in SECURITY.md. This prerelease does not provide a commercial support SLA.
|
||||
@@ -1,7 +1,4 @@
|
||||
#Requires -Version 7.4
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
Set-StrictMode -Version Latest
|
||||
$ErrorActionPreference = 'Stop'
|
||||
|
||||
|
||||
@@ -1,7 +1,4 @@
|
||||
#Requires -Version 7.4
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
[CmdletBinding()]
|
||||
param(
|
||||
[string] $ScriptsDirectory = $PSScriptRoot
|
||||
|
||||
@@ -1,7 +1,4 @@
|
||||
#Requires -Version 7.4
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Fails when any named assembly is below the required line coverage.
|
||||
|
||||
@@ -1,36 +0,0 @@
|
||||
#Requires -Version 7.4
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Rejects a stable release when the protected signing configuration is missing or malformed.
|
||||
.DESCRIPTION
|
||||
Checks the non-secret protected-environment variables before any signing step runs. This is
|
||||
configuration validation only; it does not prove Azure access or a valid signature.
|
||||
#>
|
||||
[CmdletBinding()]
|
||||
param()
|
||||
|
||||
Set-StrictMode -Version Latest
|
||||
$ErrorActionPreference = 'Stop'
|
||||
$guidVariables = @('AZURE_CLIENT_ID', 'AZURE_TENANT_ID', 'AZURE_SUBSCRIPTION_ID')
|
||||
foreach($name in @($guidVariables) + @('ARTIFACT_SIGNING_ENDPOINT', 'ARTIFACT_SIGNING_ACCOUNT', 'ARTIFACT_SIGNING_PROFILE', 'ARTIFACT_SIGNING_SUBJECT'))
|
||||
{
|
||||
$value = [Environment]::GetEnvironmentVariable($name)
|
||||
if([string]::IsNullOrWhiteSpace($value)) { throw "Missing verified signing variable: $name" }
|
||||
if($name -in $guidVariables)
|
||||
{
|
||||
$identifier = [guid]::Empty
|
||||
if(-not [guid]::TryParseExact($value, 'D', [ref]$identifier) -or $identifier -eq [guid]::Empty) { throw "Invalid signing identifier: $name" }
|
||||
}
|
||||
}
|
||||
$endpoint = $null
|
||||
if(-not [uri]::TryCreate($env:ARTIFACT_SIGNING_ENDPOINT, [UriKind]::Absolute, [ref]$endpoint) -or $endpoint.Scheme -ne 'https' -or -not $endpoint.Host.EndsWith('.codesigning.azure.net', [StringComparison]::OrdinalIgnoreCase))
|
||||
{
|
||||
throw 'The verified Artifact Signing endpoint must use HTTPS on codesigning.azure.net.'
|
||||
}
|
||||
if($env:ARTIFACT_SIGNING_SUBJECT -notmatch '^CN=.+')
|
||||
{
|
||||
throw 'ARTIFACT_SIGNING_SUBJECT must be the full X.500 certificate subject, not just a display name.'
|
||||
}
|
||||
Write-Output 'Windows release signing configuration is present; Azure access and final signatures still require verification.'
|
||||
@@ -1,24 +0,0 @@
|
||||
#Requires -Version 7.4
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Repository-owned CI packaging entrypoint for the shared Gitea .NET CI.
|
||||
.DESCRIPTION
|
||||
The shared workflow runs this after verification with only the typed versions. It delegates to Package-Release.ps1,
|
||||
the single packaging path that CI, the release workflow and local packaging share: SDK inventory, branded-installer
|
||||
dry run, packaging-input checks, the unsigned generic MSI and one unsigned MSI per client edition, and the release
|
||||
bundle with SHA256SUMS. It takes no certificate, timestamp server or payload input and never signs or installs anything.
|
||||
#>
|
||||
[CmdletBinding()]
|
||||
param(
|
||||
[ValidatePattern('^\d+\.\d+\.\d+$')]
|
||||
[string] $ProductVersion = '1.2.1',
|
||||
[ValidatePattern('^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$')]
|
||||
[string] $ReleaseVersion = '1.2.1'
|
||||
)
|
||||
|
||||
$ErrorActionPreference = 'Stop'
|
||||
Set-StrictMode -Version Latest
|
||||
& (Join-Path $PSScriptRoot 'Package-Release.ps1') -ProductVersion $ProductVersion -ReleaseVersion $ReleaseVersion
|
||||
+7
-124
@@ -1,22 +1,14 @@
|
||||
#Requires -Version 7.4
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
[CmdletBinding()]
|
||||
param(
|
||||
[ValidatePattern('^\d+\.\d+\.\d+$')]
|
||||
[string] $ProductVersion = '1.0.1',
|
||||
[string] $ProductVersion = '0.1.9',
|
||||
[ValidatePattern('^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$')]
|
||||
[string] $ReleaseVersion = '1.0.1',
|
||||
[string] $ReleaseVersion = '0.1.9-rc.1',
|
||||
[string] $PayloadDirectory,
|
||||
[switch] $SkipPublish,
|
||||
[switch] $PublishOnly,
|
||||
[string] $CertificateThumbprint,
|
||||
[string] $TimestampServer,
|
||||
# A client edition folder name under editions/ (see editions/README.md): the build ships that client's mark, icon and
|
||||
# names in every executable and the installer, and names the MSI after the edition's asset prefix.
|
||||
[ValidatePattern('^[a-z0-9][a-z0-9-]{0,39}$')]
|
||||
[string] $Edition
|
||||
[string] $TimestampServer
|
||||
)
|
||||
|
||||
$ErrorActionPreference = 'Stop'
|
||||
@@ -36,60 +28,15 @@ if($versionProperties.SelectSingleNode('/Project/PropertyGroup/VersionPrefix').I
|
||||
{
|
||||
throw 'ProductVersion must match the reviewed source VersionPrefix in Directory.Build.props.'
|
||||
}
|
||||
# Windows Installer replaces a versioned file only when its numeric file version is higher, and the
|
||||
# .NET SDK would give every 0.4.0-rc.N the same 0.4.0.0. Only rc.N (revision N, 1..65534) and stable
|
||||
# (revision 65535, above every rc) have an ordered mapping; any other label is refused, never guessed.
|
||||
$releaseMatch = [regex]::Match($ReleaseVersion, '^\d+\.\d+\.\d+(?:-rc\.(?<revision>[1-9][0-9]{0,4}))?$')
|
||||
$revision = if($releaseMatch.Success -and $releaseMatch.Groups['revision'].Success) { [int]$releaseMatch.Groups['revision'].Value } else { 65535 }
|
||||
if(-not $releaseMatch.Success -or $revision -gt 65535 -or ($releaseMatch.Groups['revision'].Success -and $revision -gt 65534))
|
||||
{
|
||||
throw 'Unsupported ReleaseVersion: use X.Y.Z-rc.N (N 1..65534) or stable X.Y.Z so the numeric file version orders upgrades.'
|
||||
}
|
||||
$fileVersion = "$ProductVersion.$revision"
|
||||
$brand = $null
|
||||
if($Edition)
|
||||
{
|
||||
$editionRoot = Join-Path $projectRoot "editions\$Edition"
|
||||
$editionFile = Join-Path $editionRoot 'edition.json'
|
||||
if(-not (Test-Path -LiteralPath $editionFile -PathType Leaf)) { throw "Unknown edition '$Edition': $editionFile does not exist." }
|
||||
$brand = Get-Content -LiteralPath $editionFile -Raw | ConvertFrom-Json
|
||||
foreach($required in @('id', 'displayName', 'companyName', 'assetPrefix'))
|
||||
{
|
||||
if(-not ($brand.PSObject.Properties.Name -contains $required) -or [string]::IsNullOrWhiteSpace($brand.$required)) { throw "edition.json is missing '$required'." }
|
||||
}
|
||||
if($brand.id -cne $Edition) { throw "edition.json id '$($brand.id)' must equal the folder name '$Edition'." }
|
||||
if($brand.assetPrefix -cnotmatch '^[A-Za-z][A-Za-z0-9]{1,39}$') { throw 'assetPrefix must be 2 to 40 letters or digits starting with a letter.' }
|
||||
foreach($label in @($brand.displayName, $brand.companyName))
|
||||
{
|
||||
if($label.Length -gt 180 -or $label -match '[\x00-\x1F;=]') { throw 'Edition names must be at most 180 characters without control characters, semicolons or equals signs.' }
|
||||
}
|
||||
foreach($asset in @('app-icon.svg', 'app.ico'))
|
||||
{
|
||||
if(-not (Test-Path -LiteralPath (Join-Path $editionRoot $asset) -PathType Leaf)) { throw "Edition asset missing: editions\$Edition\$asset" }
|
||||
}
|
||||
}
|
||||
$msiBaseName = if($brand) { $brand.assetPrefix } else { 'QqqPrintAgent' }
|
||||
$brandPublishArgs = @()
|
||||
$brandInstallerArgs = @()
|
||||
if($brand)
|
||||
{
|
||||
$brandPublishArgs = @("-p:BrandEdition=$Edition", "-p:BrandProduct=$($brand.displayName)", "-p:BrandCompany=$($brand.companyName)")
|
||||
$brandInstallerArgs = @("-p:BrandName=$($brand.displayName)", "-p:BrandCompany=$($brand.companyName)", '-p:BrandForced=1', "-p:MsiBaseName=$msiBaseName")
|
||||
}
|
||||
if($SkipPublish -and -not $PayloadDirectory)
|
||||
{
|
||||
throw 'SkipPublish requires an explicit reviewed PayloadDirectory.'
|
||||
}
|
||||
if($PublishOnly -and ($SkipPublish -or -not $PayloadDirectory -or $CertificateThumbprint))
|
||||
{
|
||||
throw 'PublishOnly requires a new PayloadDirectory and cannot be combined with SkipPublish or a local signing certificate.'
|
||||
}
|
||||
$payloadRoot = if($PayloadDirectory) { [IO.Path]::GetFullPath($PayloadDirectory) } else { Join-Path $projectRoot ('artifacts\package\' + [Guid]::NewGuid().ToString('N')) }
|
||||
if(-not $SkipPublish -and (Test-Path -LiteralPath $payloadRoot))
|
||||
{
|
||||
throw 'Publishing requires a new PayloadDirectory so stale files cannot enter the installer.'
|
||||
}
|
||||
& (Join-Path $PSScriptRoot 'Test-WindowsSdkInventory.ps1')
|
||||
$installerProject = Join-Path $projectRoot 'installer\Qqq.PrintAgent.Installer.wixproj'
|
||||
$outputDirectory = Join-Path $projectRoot 'artifacts\installer'
|
||||
$buildDirectory = Join-Path $outputDirectory $ProductVersion
|
||||
@@ -104,31 +51,9 @@ if(-not $SkipPublish)
|
||||
}
|
||||
foreach($entry in $projects.GetEnumerator())
|
||||
{
|
||||
& dotnet publish (Join-Path $projectRoot $entry.Value) --configuration Release --runtime win-x64 --self-contained true --output (Join-Path $payloadRoot $entry.Key) '-p:Platform=x64' '-p:RestoreLockedMode=true' "-p:Version=$ReleaseVersion" "-p:FileVersion=$fileVersion" @brandPublishArgs
|
||||
& dotnet publish (Join-Path $projectRoot $entry.Value) --configuration Release --runtime win-x64 --self-contained true --output (Join-Path $payloadRoot $entry.Key) '-p:Platform=x64' '-p:RestoreLockedMode=true' "-p:Version=$ReleaseVersion"
|
||||
if($LASTEXITCODE -ne 0) { throw "Publishing $($entry.Key) failed." }
|
||||
}
|
||||
if($brand)
|
||||
{
|
||||
# The companion carries the descriptor through its project; the service and CLI read the same file beside their executables.
|
||||
foreach($target in @('service', 'cli'))
|
||||
{
|
||||
Copy-Item -LiteralPath (Join-Path $projectRoot "editions\$Edition\edition.json") -Destination (Join-Path $payloadRoot "$target\edition.json") -Force
|
||||
}
|
||||
}
|
||||
}
|
||||
if($brand)
|
||||
{
|
||||
foreach($target in @('app', 'service', 'cli'))
|
||||
{
|
||||
if(-not (Test-Path -LiteralPath (Join-Path $payloadRoot "$target\edition.json") -PathType Leaf)) { throw "The payload does not carry edition '$Edition' in $target; publish it with the same -Edition." }
|
||||
}
|
||||
foreach($asset in @('app\Assets\Brand\app-icon.svg', 'app\Assets\Brand\app.ico'))
|
||||
{
|
||||
if((Get-FileHash -LiteralPath (Join-Path $payloadRoot $asset) -Algorithm SHA256).Hash -cne (Get-FileHash -LiteralPath (Join-Path $projectRoot "editions\$Edition\$(Split-Path $asset -Leaf)") -Algorithm SHA256).Hash)
|
||||
{
|
||||
throw "The published $asset is not edition '$Edition' artwork."
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
$executables = @(
|
||||
@@ -144,14 +69,6 @@ foreach($executable in $executables)
|
||||
{
|
||||
throw "Published executable version does not match ReleaseVersion: $executable"
|
||||
}
|
||||
if($brand -and (Get-Item -LiteralPath $executable).VersionInfo.ProductName -cne $brand.displayName)
|
||||
{
|
||||
throw "Published executable does not carry edition '$Edition' product metadata: $executable"
|
||||
}
|
||||
if((Get-Item -LiteralPath $executable).VersionInfo.FileVersion -cne $fileVersion)
|
||||
{
|
||||
throw "Published executable file version does not match $fileVersion; Windows Installer would not replace an older equal file: $executable"
|
||||
}
|
||||
}
|
||||
|
||||
# A successful .NET publish does not guarantee a usable unpackaged WinUI application.
|
||||
@@ -164,17 +81,6 @@ foreach($resource in @('App.xbf', 'MainWindow.xbf', 'Qqq.PrintAgent.pri'))
|
||||
}
|
||||
}
|
||||
|
||||
# Verify actual third-party terms and exclude build-only SDK payloads before WiX.
|
||||
& (Join-Path $PSScriptRoot 'Test-WindowsSdkInventory.ps1') -PayloadDirectory $payloadRoot
|
||||
|
||||
# The release workflow signs the published owned binaries between this stage and the MSI build,
|
||||
# then reruns this script with -SkipPublish so every check above also covers the signed payload.
|
||||
if($PublishOnly)
|
||||
{
|
||||
Write-Output "Published and checked payload for signing: $payloadRoot"
|
||||
return
|
||||
}
|
||||
|
||||
# A supplied certificate opts into signing; unsigned local builds are clearly labelled.
|
||||
if($CertificateThumbprint)
|
||||
{
|
||||
@@ -188,35 +94,12 @@ if($CertificateThumbprint)
|
||||
}
|
||||
|
||||
# WiX incremental inputs do not reliably invalidate a changed version/payload path.
|
||||
# WiX validates the MSI (ICE checks) through the Windows Installer service. A runner that logs on as a batch account cannot
|
||||
# open that service, so WiX fails every ICE action with WIX0217 ("The Windows Installer Service could not be accessed").
|
||||
# Validate whenever the service is reachable. Skip validation only when it is not, with a loud warning, and never for a
|
||||
# signed release build: that must be built on a host where validation works.
|
||||
$installerValidationArguments = @()
|
||||
try
|
||||
{
|
||||
$installerService = Get-Service -Name msiserver -ErrorAction Stop
|
||||
if($installerService.Status -ne 'Running')
|
||||
{
|
||||
$installerService.Start()
|
||||
$installerService.WaitForStatus('Running', [TimeSpan]::FromSeconds(30))
|
||||
}
|
||||
}
|
||||
catch
|
||||
{
|
||||
if($CertificateThumbprint)
|
||||
{
|
||||
throw "The Windows Installer service is not reachable, so the MSI cannot be validated; refusing to build a signed release without validation. $($_.Exception.Message)"
|
||||
}
|
||||
Write-Warning "The Windows Installer service is not reachable from this session; building the MSI WITHOUT ICE validation (not a signed release build). $($_.Exception.Message)"
|
||||
$installerValidationArguments = @('-p:SuppressValidation=true')
|
||||
}
|
||||
& dotnet build $installerProject --configuration Release -t:Rebuild '-p:RestoreLockedMode=true' "-p:ProductVersion=$ProductVersion" "-p:PayloadRoot=$payloadRoot" "-p:OutputPath=$buildDirectory\" @brandInstallerArgs @installerValidationArguments
|
||||
& dotnet build $installerProject --configuration Release -t:Rebuild '-p:RestoreLockedMode=true' "-p:ProductVersion=$ProductVersion" "-p:PayloadRoot=$payloadRoot" "-p:OutputPath=$buildDirectory\"
|
||||
if($LASTEXITCODE -ne 0) { throw 'MSI build failed.' }
|
||||
$builtMsi = Join-Path $buildDirectory "$msiBaseName-$ProductVersion-x64.msi"
|
||||
$builtMsi = Join-Path $buildDirectory "QqqPrintAgent-$ProductVersion-x64.msi"
|
||||
if(-not (Test-Path -LiteralPath $builtMsi)) { throw 'MSI output was not produced.' }
|
||||
# Keep earlier verified installers available for recovery when WiX cleans its build outputs.
|
||||
$msi = Join-Path $outputDirectory "$msiBaseName-$ProductVersion-x64.msi"
|
||||
$msi = Join-Path $outputDirectory "QqqPrintAgent-$ProductVersion-x64.msi"
|
||||
Copy-Item -LiteralPath $builtMsi -Destination $msi -Force
|
||||
|
||||
if($CertificateThumbprint)
|
||||
|
||||
@@ -1,7 +1,4 @@
|
||||
#Requires -Version 7.4
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Regenerates the original cloud/printer mark and Windows icon sizes using WPF.
|
||||
|
||||
@@ -1,7 +1,4 @@
|
||||
#Requires -Version 7.4
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
Set-StrictMode -Version Latest
|
||||
$ErrorActionPreference = 'Stop'
|
||||
|
||||
|
||||
@@ -1,7 +1,4 @@
|
||||
#requires -Version 7.4
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
[CmdletBinding(SupportsShouldProcess)]
|
||||
param(
|
||||
[Parameter(Mandatory)] [string] $MsiPath,
|
||||
|
||||
@@ -1,105 +0,0 @@
|
||||
#Requires -Version 7.4
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
[CmdletBinding()]
|
||||
param(
|
||||
[string] $ProductVersion = '1.2.1',
|
||||
[string] $ReleaseVersion = '1.2.1',
|
||||
# Assemble artifacts/release from an already built MSI (the signed stable flow builds and signs it in
|
||||
# separate workflow steps). With ExpectedPublisherSubject the MSI must carry that publisher's signature.
|
||||
[switch] $AssembleOnly,
|
||||
[string] $ExpectedPublisherSubject
|
||||
)
|
||||
|
||||
# Repository entry point for the unsigned prerelease package: the same packaging checks and
|
||||
# artifact layout as .github/workflows/ci.yml, without building or running Core.Tests.
|
||||
$ErrorActionPreference = 'Stop'
|
||||
Set-StrictMode -Version Latest
|
||||
$projectRoot = Split-Path -Parent $PSScriptRoot
|
||||
|
||||
function Get-Edition
|
||||
{
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Lists the client editions under editions/ (folder id and release asset prefix), in name order.
|
||||
#>
|
||||
$root = Join-Path $projectRoot 'editions'
|
||||
if(-not (Test-Path -LiteralPath $root -PathType Container)) { return @() }
|
||||
$editions = @()
|
||||
foreach($folder in (Get-ChildItem -LiteralPath $root -Directory | Sort-Object Name))
|
||||
{
|
||||
$descriptor = Join-Path $folder.FullName 'edition.json'
|
||||
if(-not (Test-Path -LiteralPath $descriptor -PathType Leaf)) { throw "Edition folder $($folder.Name) has no edition.json." }
|
||||
$edition = Get-Content -LiteralPath $descriptor -Raw | ConvertFrom-Json
|
||||
if($edition.id -cne $folder.Name) { throw "edition.json id '$($edition.id)' must equal the folder name '$($folder.Name)'." }
|
||||
if($edition.assetPrefix -cnotmatch '^[A-Za-z][A-Za-z0-9]{1,39}$') { throw "Edition $($folder.Name) has an invalid assetPrefix." }
|
||||
$editions += [pscustomobject]@{ Id = $folder.Name; AssetPrefix = $edition.assetPrefix }
|
||||
}
|
||||
return $editions
|
||||
}
|
||||
|
||||
if($ExpectedPublisherSubject -and -not $AssembleOnly)
|
||||
{
|
||||
throw 'ExpectedPublisherSubject applies only to -AssembleOnly; signing runs in the release workflow between publish and MSI build.'
|
||||
}
|
||||
Push-Location $projectRoot
|
||||
try
|
||||
{
|
||||
# LASTEXITCODE is only set by native commands, so reset it before each script call: the checks
|
||||
# below then see this call's result (and the variable exists under StrictMode), never a stale value.
|
||||
# The scripts also throw on failure, which $ErrorActionPreference = 'Stop' turns into a failure here.
|
||||
if(-not $AssembleOnly)
|
||||
{
|
||||
$global:LASTEXITCODE = 0
|
||||
& (Join-Path $PSScriptRoot 'Test-WindowsSdkInventory.ps1') -VerifyPackages
|
||||
if($LASTEXITCODE -ne 0) { throw 'Windows SDK inventory verification failed.' }
|
||||
$global:LASTEXITCODE = 0
|
||||
& (Join-Path $PSScriptRoot 'Test-BrandedInstaller.ps1')
|
||||
if($LASTEXITCODE -ne 0) { throw 'Branded installer dry run failed.' }
|
||||
$global:LASTEXITCODE = 0
|
||||
& (Join-Path $PSScriptRoot 'Test-PackagingInputs.ps1')
|
||||
if($LASTEXITCODE -ne 0) { throw 'Packaging input checks failed.' }
|
||||
$global:LASTEXITCODE = 0
|
||||
& (Join-Path $PSScriptRoot 'Build-Installer.ps1') -ProductVersion $ProductVersion -ReleaseVersion $ReleaseVersion
|
||||
if($LASTEXITCODE -ne 0) { throw 'Installer build failed.' }
|
||||
foreach($edition in Get-Edition)
|
||||
{
|
||||
$global:LASTEXITCODE = 0
|
||||
& (Join-Path $PSScriptRoot 'Build-Installer.ps1') -ProductVersion $ProductVersion -ReleaseVersion $ReleaseVersion -Edition $edition.Id
|
||||
if($LASTEXITCODE -ne 0) { throw "Installer build failed for edition $($edition.Id)." }
|
||||
}
|
||||
}
|
||||
# The generic installer plus one per client edition (editions/<id>, named after its asset prefix). Every one
|
||||
# must exist and, for a signed release, carry the publisher's signature; an edition is never silently dropped.
|
||||
$installers = @([pscustomobject]@{ Prefix = 'QqqPrintAgent'; Label = 'generic' }) + @(Get-Edition | ForEach-Object { [pscustomobject]@{ Prefix = $_.AssetPrefix; Label = "edition $($_.Id)" } })
|
||||
$releaseDirectory = Join-Path $projectRoot 'artifacts/release'
|
||||
New-Item -ItemType Directory -Path $releaseDirectory -Force | Out-Null
|
||||
$sums = Join-Path $releaseDirectory 'SHA256SUMS'
|
||||
Remove-Item -LiteralPath $sums -Force -ErrorAction SilentlyContinue
|
||||
foreach($installer in $installers)
|
||||
{
|
||||
$builtMsi = Join-Path $projectRoot "artifacts/installer/$($installer.Prefix)-$ProductVersion-x64.msi"
|
||||
if(-not (Test-Path -LiteralPath $builtMsi -PathType Leaf)) { throw "Missing installer for the $($installer.Label) build: $builtMsi" }
|
||||
if($ExpectedPublisherSubject)
|
||||
{
|
||||
& (Join-Path $PSScriptRoot 'Sign-Release.ps1') -Operation Verify -Kind Msi -Root $builtMsi -ExpectedSubject $ExpectedPublisherSubject
|
||||
}
|
||||
$name = "$($installer.Prefix)-v$ReleaseVersion-x64.msi"
|
||||
Copy-Item -LiteralPath $builtMsi -Destination (Join-Path $releaseDirectory $name) -Force
|
||||
$hash = (Get-FileHash -LiteralPath (Join-Path $releaseDirectory $name) -Algorithm SHA256).Hash.ToLowerInvariant()
|
||||
"$hash $name" | Add-Content -LiteralPath $sums -Encoding ascii
|
||||
}
|
||||
Copy-Item -LiteralPath (Join-Path $PSScriptRoot 'Install-Branded.ps1') -Destination (Join-Path $releaseDirectory 'Install-Branded.ps1') -Force
|
||||
Copy-Item -LiteralPath (Join-Path $projectRoot 'docs/branding.example.json') -Destination (Join-Path $releaseDirectory 'branding.example.json') -Force
|
||||
foreach($file in @('Install-Branded.ps1', 'branding.example.json'))
|
||||
{
|
||||
$hash = (Get-FileHash -LiteralPath (Join-Path $releaseDirectory $file) -Algorithm SHA256).Hash.ToLowerInvariant()
|
||||
"$hash $file" | Add-Content -LiteralPath $sums -Encoding ascii
|
||||
}
|
||||
Write-Output "$(if($ExpectedPublisherSubject) { 'Signed release' } else { 'Unsigned prerelease' }) package assembled in $releaseDirectory"
|
||||
}
|
||||
finally
|
||||
{
|
||||
Pop-Location
|
||||
}
|
||||
@@ -1,140 +0,0 @@
|
||||
#Requires -Version 7.4
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Stages, accepts and verifies the owned binaries and MSI of a signed stable release.
|
||||
.DESCRIPTION
|
||||
The release workflow signs files in a staging folder with the pinned Azure Artifact Signing action,
|
||||
which can only select by extension. Stage copies exactly the owned files, so a third-party signature
|
||||
is never replaced. Apply accepts a staged file only when it carries a valid, timestamped signature
|
||||
for the exact expected publisher subject, then copies it back over the original. Verify checks the
|
||||
final files in place. Nothing here signs, contacts Azure or needs a secret.
|
||||
#>
|
||||
[CmdletBinding()]
|
||||
param(
|
||||
[Parameter(Mandatory)]
|
||||
[ValidateSet('Stage', 'Apply', 'Verify')]
|
||||
[string] $Operation,
|
||||
[Parameter(Mandatory)]
|
||||
[ValidateSet('Payload', 'Msi')]
|
||||
[string] $Kind,
|
||||
# Payload directory (service, app and cli folders) or the MSI file.
|
||||
[Parameter(Mandatory)]
|
||||
[string] $Root,
|
||||
[string] $Stage,
|
||||
# Full X.500 subject of the verified publisher certificate.
|
||||
[string] $ExpectedSubject
|
||||
)
|
||||
|
||||
Set-StrictMode -Version Latest
|
||||
$ErrorActionPreference = 'Stop'
|
||||
|
||||
function Get-OwnedFile
|
||||
{
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Lists the files this repository owns and signs, relative to the root.
|
||||
#>
|
||||
param([string] $Kind, [string] $Root)
|
||||
if($Kind -eq 'Msi')
|
||||
{
|
||||
if(-not (Test-Path -LiteralPath $Root -PathType Leaf) -or [IO.Path]::GetExtension($Root) -cne '.msi') { throw 'Root must be an existing .msi file.' }
|
||||
return @([pscustomobject]@{ Relative = [IO.Path]::GetFileName($Root); Path = [IO.Path]::GetFullPath($Root) })
|
||||
}
|
||||
$base = [IO.Path]::GetFullPath($Root)
|
||||
$required = @('service/Qqq.PrintAgent.Service.exe', 'app/Qqq.PrintAgent.exe', 'cli/qqq-print-agent.exe')
|
||||
foreach($relative in $required)
|
||||
{
|
||||
if(-not (Test-Path -LiteralPath (Join-Path $base $relative) -PathType Leaf)) { throw "Missing owned executable: $relative" }
|
||||
}
|
||||
$found = foreach($directory in @('service', 'app', 'cli'))
|
||||
{
|
||||
foreach($pattern in @('Qqq.PrintAgent*.exe', 'Qqq.PrintAgent*.dll', 'qqq-print-agent.exe', 'qqq-print-agent.dll', 'KofTwentyTwo.AppKit*.dll'))
|
||||
{
|
||||
Get-ChildItem -LiteralPath (Join-Path $base $directory) -Filter $pattern -File -ErrorAction SilentlyContinue
|
||||
}
|
||||
}
|
||||
@($found | Sort-Object FullName -Unique | ForEach-Object { [pscustomobject]@{ Relative = [IO.Path]::GetRelativePath($base, $_.FullName).Replace('\', '/'); Path = $_.FullName } })
|
||||
}
|
||||
|
||||
function Get-SignTool
|
||||
{
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Finds the Windows SDK SignTool, preferring PATH and then the newest installed x64 copy.
|
||||
#>
|
||||
$command = Get-Command signtool.exe -ErrorAction SilentlyContinue
|
||||
if($command) { return $command.Source }
|
||||
$kits = Join-Path ${env:ProgramFiles(x86)} 'Windows Kits/10/bin'
|
||||
$candidate = Get-ChildItem -Path (Join-Path $kits '*/x64/signtool.exe') -ErrorAction SilentlyContinue | Sort-Object FullName -Descending | Select-Object -First 1
|
||||
if(-not $candidate) { throw 'signtool.exe was not found; install the Windows SDK signing tools.' }
|
||||
$candidate.FullName
|
||||
}
|
||||
|
||||
function Assert-Signed
|
||||
{
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Requires a trusted, SHA256, RFC3161-timestamped signature by exactly the expected publisher subject.
|
||||
#>
|
||||
param([string] $Path)
|
||||
$signature = Get-AuthenticodeSignature -LiteralPath $Path
|
||||
if($signature.Status -ne 'Valid') { throw "Signature is not valid ($($signature.Status)): $Path" }
|
||||
if($signature.SignerCertificate.Subject -cne $ExpectedSubject) { throw "Signer subject does not match the verified publisher: $Path" }
|
||||
if($null -eq $signature.TimeStamperCertificate) { throw "Signature has no trusted timestamp: $Path" }
|
||||
$global:LASTEXITCODE = 0
|
||||
$output = (& (Get-SignTool) verify /pa /all /v $Path 2>&1) -join "`n"
|
||||
if($LASTEXITCODE -ne 0) { throw "signtool verify /pa /all /v failed: $Path" }
|
||||
# Match only the file-digest lines ("Hash of file (sha256): ..."), never text that names an algorithm
|
||||
# elsewhere, such as the certificate chain. Exactly one signature with no warnings or errors is required.
|
||||
$digests = @([regex]::Matches($output, '(?m)^\s*Hash of file \((?<algorithm>[^)\r\n]+)\):').ForEach({ $_.Groups['algorithm'].Value }))
|
||||
if($digests.Count -eq 0 -or @($digests | Where-Object { $_ -cne 'sha256' }).Count -gt 0) { throw "File digest is not SHA256 on every signature: $Path" }
|
||||
if($output -notmatch '(?m)^Number of signatures successfully Verified: 1\s*$' -or $output -notmatch '(?m)^Number of warnings: 0\s*$' -or $output -notmatch '(?m)^Number of errors: 0\s*$')
|
||||
{ throw "signtool did not report exactly one verified signature with zero warnings and errors: $Path" }
|
||||
}
|
||||
|
||||
if($Operation -ne 'Stage' -and [string]::IsNullOrWhiteSpace($ExpectedSubject))
|
||||
{
|
||||
throw 'ExpectedSubject (the full verified certificate subject) is required to accept or verify signatures.'
|
||||
}
|
||||
$files = @(Get-OwnedFile -Kind $Kind -Root $Root)
|
||||
if($files.Count -eq 0) { throw 'No owned files were found to sign.' }
|
||||
|
||||
switch($Operation)
|
||||
{
|
||||
'Stage'
|
||||
{
|
||||
if(-not $Stage) { throw 'Stage requires a Stage directory.' }
|
||||
$stageRoot = [IO.Path]::GetFullPath($Stage)
|
||||
if((Test-Path -LiteralPath $stageRoot) -and @(Get-ChildItem -LiteralPath $stageRoot -Force).Count -gt 0) { throw 'Stage must be a new or empty directory.' }
|
||||
foreach($file in $files)
|
||||
{
|
||||
$destination = Join-Path $stageRoot $file.Relative
|
||||
New-Item -ItemType Directory -Path (Split-Path $destination -Parent) -Force | Out-Null
|
||||
Copy-Item -LiteralPath $file.Path -Destination $destination
|
||||
}
|
||||
Write-Output "Staged $($files.Count) owned file(s) for signing."
|
||||
}
|
||||
'Apply'
|
||||
{
|
||||
if(-not $Stage) { throw 'Apply requires the signed Stage directory.' }
|
||||
$stageRoot = [IO.Path]::GetFullPath($Stage)
|
||||
$staged = @(Get-ChildItem -LiteralPath $stageRoot -Recurse -File | ForEach-Object { [IO.Path]::GetRelativePath($stageRoot, $_.FullName).Replace('\', '/') })
|
||||
if((@($staged | Sort-Object) -join '|') -cne (@($files.Relative | Sort-Object) -join '|')) { throw 'The signed stage does not contain exactly the staged owned files.' }
|
||||
foreach($file in $files)
|
||||
{
|
||||
$signed = Join-Path $stageRoot $file.Relative
|
||||
Assert-Signed $signed
|
||||
if((Get-FileHash -LiteralPath $signed -Algorithm SHA256).Hash -ceq (Get-FileHash -LiteralPath $file.Path -Algorithm SHA256).Hash) { throw "Staged file was not changed by signing: $($file.Relative)" }
|
||||
}
|
||||
foreach($file in $files) { Copy-Item -LiteralPath (Join-Path $stageRoot $file.Relative) -Destination $file.Path -Force }
|
||||
foreach($file in $files) { Assert-Signed $file.Path }
|
||||
Write-Output "Applied and verified $($files.Count) signed file(s)."
|
||||
}
|
||||
'Verify'
|
||||
{
|
||||
foreach($file in $files) { Assert-Signed $file.Path }
|
||||
Write-Output "Verified $($files.Count) signed file(s)."
|
||||
}
|
||||
}
|
||||
@@ -1,7 +1,4 @@
|
||||
#requires -Version 7.4
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
[CmdletBinding()]
|
||||
param()
|
||||
|
||||
|
||||
@@ -1,7 +1,4 @@
|
||||
#Requires -Version 7.4
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
[CmdletBinding()]
|
||||
param()
|
||||
|
||||
@@ -26,44 +23,9 @@ function Assert-PackageRejected([string] $Product, [string] $Release, [string] $
|
||||
Assert-PackageRejected -Product $current -Release '999.0.0-rc.1' -Expected 'numeric core'
|
||||
Assert-PackageRejected -Product '256.0.0' -Release '256.0.0-rc.1' -Expected 'Windows Installer limits'
|
||||
Assert-PackageRejected -Product '0.0.0' -Release '0.0.0-rc.1' -Expected 'reviewed source VersionPrefix'
|
||||
Assert-PackageRejected -Product $current -Release "$current-beta.1" -Expected 'Unsupported ReleaseVersion'
|
||||
Assert-PackageRejected -Product $current -Release "$current-rc.65535" -Expected 'Unsupported ReleaseVersion'
|
||||
Assert-PackageRejected -Product $current -Release "$current-rc.0" -Expected 'Unsupported ReleaseVersion'
|
||||
Assert-PackageRejected -Product $current -Release "$current-rc.1" -Expected 'explicit reviewed PayloadDirectory'
|
||||
$message = ''
|
||||
try { & $builder -ProductVersion $current -ReleaseVersion "$current-rc.1" -PayloadDirectory $PSScriptRoot }
|
||||
catch { $message = $_.Exception.Message }
|
||||
if($message -notlike '*requires a new PayloadDirectory*') { throw 'Packaging did not reject an existing publish directory.' }
|
||||
$message = ''
|
||||
try { & $builder -ProductVersion $current -ReleaseVersion "$current-rc.1" -PublishOnly }
|
||||
catch { $message = $_.Exception.Message }
|
||||
if($message -notlike '*PublishOnly requires a new PayloadDirectory*') { throw 'Packaging did not reject PublishOnly without a payload directory.' }
|
||||
$message = ''
|
||||
try { & (Join-Path $PSScriptRoot 'Sign-Release.ps1') -Operation Verify -Kind Payload -Root $PSScriptRoot }
|
||||
catch { $message = $_.Exception.Message }
|
||||
if($message -notlike '*ExpectedSubject*required*') { throw 'Signature verification did not require the verified publisher subject.' }
|
||||
# Stage synthetic file names only: the owned set includes the hyphenated CLI managed DLL and excludes third-party files.
|
||||
$fake = Join-Path ([IO.Path]::GetTempPath()) ('qqq-sign-stage-' + [Guid]::NewGuid().ToString('N'))
|
||||
try
|
||||
{
|
||||
foreach($name in @('service/Qqq.PrintAgent.Service.exe', 'app/Qqq.PrintAgent.exe', 'cli/qqq-print-agent.exe', 'cli/qqq-print-agent.dll', 'cli/Third.Party.dll'))
|
||||
{
|
||||
$path = Join-Path (Join-Path $fake 'payload') $name
|
||||
New-Item -ItemType Directory -Path (Split-Path $path -Parent) -Force | Out-Null
|
||||
Set-Content -LiteralPath $path -Value 'synthetic'
|
||||
}
|
||||
& (Join-Path $PSScriptRoot 'Sign-Release.ps1') -Operation Stage -Kind Payload -Root (Join-Path $fake 'payload') -Stage (Join-Path $fake 'stage') | Out-Null
|
||||
$staged = @(Get-ChildItem -LiteralPath (Join-Path $fake 'stage') -Recurse -File | ForEach-Object { [IO.Path]::GetRelativePath((Join-Path $fake 'stage'), $_.FullName).Replace('\', '/') } | Sort-Object)
|
||||
if(($staged -join '|') -cne 'app/Qqq.PrintAgent.exe|cli/qqq-print-agent.dll|cli/qqq-print-agent.exe|service/Qqq.PrintAgent.Service.exe')
|
||||
{ throw 'Signing stage must include the hyphenated CLI managed DLL and exclude third-party files.' }
|
||||
}
|
||||
finally
|
||||
{
|
||||
# Delete only a resolved absolute path strictly beneath the resolved temp directory; otherwise keep it and fail.
|
||||
$tempRoot = [IO.Path]::GetFullPath([IO.Path]::GetTempPath()).TrimEnd('\', '/') + [IO.Path]::DirectorySeparatorChar
|
||||
$resolved = [IO.Path]::GetFullPath($fake)
|
||||
if(-not $resolved.StartsWith($tempRoot, [StringComparison]::OrdinalIgnoreCase) -or $resolved.Length -le $tempRoot.Length)
|
||||
{ throw "Refusing to delete a synthetic stage outside the temp directory: $resolved" }
|
||||
if(Test-Path -LiteralPath $resolved) { Remove-Item -LiteralPath $resolved -Recurse -Force }
|
||||
}
|
||||
Write-Output 'Packaging rejects inconsistent source/release/MSI versions before publishing payloads.'
|
||||
@@ -1,293 +0,0 @@
|
||||
#Requires -Version 7.4
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
Set-StrictMode -Version Latest
|
||||
$ErrorActionPreference = 'Stop'
|
||||
|
||||
BeforeAll `
|
||||
{
|
||||
$script:Guard = Join-Path $PSScriptRoot 'Test-WindowsSdkInventory.ps1'
|
||||
$script:SourceRoot = Split-Path $PSScriptRoot -Parent
|
||||
$script:AppLock = 'src/Qqq.PrintAgent/packages.lock.json'
|
||||
$script:HostLock = 'tests/Qqq.PrintAgent.LayoutTests/packages.lock.json'
|
||||
$script:BaseTarget = 'net10.0-windows10.0.19041'
|
||||
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Write a modified synthetic lock, retaining JSON arrays and values.
|
||||
#>
|
||||
function Set-FixtureLock
|
||||
{
|
||||
[CmdletBinding(SupportsShouldProcess)]
|
||||
param([string] $Relative, $Lock)
|
||||
if($PSCmdlet.ShouldProcess($Relative, 'Write synthetic package lock'))
|
||||
{
|
||||
$Lock | ConvertTo-Json -Depth 40 | Set-Content -LiteralPath (Join-Path $script:Fixture $Relative) -Encoding utf8
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Describe 'Exact Windows SDK inventory guard' `
|
||||
{
|
||||
BeforeEach `
|
||||
{
|
||||
Mock Get-Date { [DateTimeOffset]::Parse('2026-11-01T00:00:00Z').UtcDateTime }
|
||||
$script:Fixture = Join-Path $TestDrive ([Guid]::NewGuid().ToString('N'))
|
||||
foreach($relative in @('Directory.Packages.props', '.github/workflows/pr-gates.yml', $script:AppLock, $script:HostLock,
|
||||
'src/Qqq.PrintAgent/Qqq.PrintAgent.csproj', 'tests/Qqq.PrintAgent.LayoutTests/Qqq.PrintAgent.LayoutTests.csproj'))
|
||||
{
|
||||
$destination = Join-Path $script:Fixture $relative
|
||||
New-Item -ItemType Directory -Path (Split-Path $destination -Parent) -Force | Out-Null
|
||||
Copy-Item -LiteralPath (Join-Path $script:SourceRoot $relative) -Destination $destination
|
||||
}
|
||||
Copy-Item -LiteralPath (Join-Path $script:SourceRoot 'licenses') -Destination (Join-Path $script:Fixture 'licenses') -Recurse
|
||||
$script:Manifest = Get-Content -LiteralPath (Join-Path $script:Fixture 'licenses/windows-sdk-packages.json') -Raw | ConvertFrom-Json -AsHashtable
|
||||
$libraries = @{}
|
||||
foreach($package in $script:Manifest.packages | Where-Object resolution -EQ 'lock')
|
||||
{
|
||||
$libraries["$($package.id)/$($package.version)"] = @{ sha512 = $package.contentHash }
|
||||
}
|
||||
$reference = $script:Manifest.packages | Where-Object id -EQ 'Microsoft.Windows.SDK.NET.Ref'
|
||||
$script:Assets = @{
|
||||
libraries = $libraries
|
||||
project = @{ frameworks = @{ $script:BaseTarget = @{ downloadDependencies = @(@{ name = $reference.id; version = "[$($reference.version), $($reference.version)]" }) } } }
|
||||
}
|
||||
New-Item -ItemType Directory -Path (Join-Path $script:Fixture 'src/Qqq.PrintAgent/obj') | Out-Null
|
||||
Set-FixtureLock 'src/Qqq.PrintAgent/obj/project.assets.json' $script:Assets
|
||||
}
|
||||
|
||||
It 'accepts the reviewed central pins and all selected lock entries' `
|
||||
{
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture -VerifyResolvedAssets } | Should -Not -Throw
|
||||
}
|
||||
|
||||
It 'accepts the last UTC day of the recorded exception' `
|
||||
{
|
||||
Mock Get-Date { [DateTimeOffset]::Parse('2027-04-30T23:59:59.999Z').UtcDateTime }
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Not -Throw
|
||||
}
|
||||
|
||||
It 'rejects use at the first instant after the recorded expiry' `
|
||||
{
|
||||
Mock Get-Date { [DateTimeOffset]::Parse('2027-05-01T00:00:00Z').UtcDateTime }
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*EX-0014 expired*'
|
||||
}
|
||||
|
||||
It 'rejects an expanded, duplicate or wildcard license allowance: <Replacement>' -ForEach @(
|
||||
@{ Replacement = 'pkg:nuget/KofTwentyTwo.AppKit' },
|
||||
@{ Replacement = 'pkg:nuget/Microsoft.WindowsAppSDK.AI' },
|
||||
@{ Replacement = 'pkg:nuget/Microsoft.WindowsAppSDK.*' }
|
||||
) `
|
||||
{
|
||||
$path = Join-Path $script:Fixture '.github/workflows/pr-gates.yml'
|
||||
$text = [IO.File]::ReadAllText($path).Replace('pkg:nuget/Microsoft.WindowsAppSDK,', "$Replacement,")
|
||||
[IO.File]::WriteAllText($path, $text)
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*only the 15 exact reviewed package names*'
|
||||
}
|
||||
|
||||
It 'rejects any other npm or versioned entry beside the reviewed EX-0015 uri-js: <Replacement>' -ForEach @(
|
||||
@{ Replacement = 'pkg:npm/other' },
|
||||
@{ Replacement = 'pkg:npm/uri-js@4.4.1' },
|
||||
@{ Replacement = 'pkg:pypi/uri-js' },
|
||||
@{ Replacement = "pkg:npm/uri-js,`n pkg:npm/uri-js" },
|
||||
@{ Replacement = "pkg:npm/uri-js,`n pkg:npm/other" }
|
||||
) `
|
||||
{
|
||||
$path = Join-Path $script:Fixture '.github/workflows/pr-gates.yml'
|
||||
[IO.File]::WriteAllText($path, [IO.File]::ReadAllText($path).Replace(' pkg:npm/uri-js', " $Replacement"))
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*plus the EX-0015 pkg:npm/uri-js entry*'
|
||||
}
|
||||
|
||||
It 'rejects the SDK allowance without the reviewed EX-0015 entry' `
|
||||
{
|
||||
$path = Join-Path $script:Fixture '.github/workflows/pr-gates.yml'
|
||||
[IO.File]::WriteAllText($path, [regex]::Replace([IO.File]::ReadAllText($path), ',\s*pkg:npm/uri-js\b', ''))
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*plus the EX-0015 pkg:npm/uri-js entry*'
|
||||
}
|
||||
|
||||
It 'rejects a changed manifest even when locks are changed to match' `
|
||||
{
|
||||
($script:Manifest.packages | Where-Object id -EQ 'Microsoft.WindowsAppSDK.ML').version = '2.1.95'
|
||||
Set-FixtureLock 'licenses/windows-sdk-packages.json' $script:Manifest
|
||||
foreach($relative in @($script:AppLock, $script:HostLock))
|
||||
{
|
||||
$lock = Get-Content -LiteralPath (Join-Path $script:Fixture $relative) -Raw | ConvertFrom-Json -AsHashtable
|
||||
$lock.dependencies[$script:BaseTarget]['Microsoft.WindowsAppSDK.ML'].resolved = '2.1.95'
|
||||
Set-FixtureLock $relative $lock
|
||||
}
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*inventory manifest changed*'
|
||||
}
|
||||
|
||||
It 'rejects an older or newer central version: <Version>' -ForEach @(@{ Version = '2.5.0' }, @{ Version = '2.5.2' }) `
|
||||
{
|
||||
$path = Join-Path $script:Fixture 'Directory.Packages.props'
|
||||
[xml]$central = Get-Content -LiteralPath $path -Raw
|
||||
$central.SelectSingleNode('//PackageVersion[@Include="Microsoft.WindowsAppSDK"]').SetAttribute('Version', $Version)
|
||||
$central.Save($path)
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*Exact single central version*'
|
||||
}
|
||||
|
||||
It 'rejects duplicate central definitions rather than picking one' `
|
||||
{
|
||||
$path = Join-Path $script:Fixture 'Directory.Packages.props'
|
||||
[xml]$central = Get-Content -LiteralPath $path -Raw
|
||||
$node = $central.SelectSingleNode('//PackageVersion[@Include="Microsoft.WindowsAppSDK"]')
|
||||
$null = $node.ParentNode.AppendChild($node.CloneNode($true))
|
||||
$central.Save($path)
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*Exact single central version*'
|
||||
}
|
||||
|
||||
It 'rejects a missing application lock' `
|
||||
{
|
||||
Remove-Item -LiteralPath (Join-Path $script:Fixture $script:AppLock)
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*Missing SDK project lock*'
|
||||
}
|
||||
|
||||
It 'rejects an empty native test-host lock' `
|
||||
{
|
||||
Set-FixtureLock $script:HostLock @{ version = 2; dependencies = @{} }
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*Empty package lock*'
|
||||
}
|
||||
|
||||
It 'rejects a missing selected package in a required base target' `
|
||||
{
|
||||
$lock = Get-Content -LiteralPath (Join-Path $script:Fixture $script:HostLock) -Raw | ConvertFrom-Json -AsHashtable
|
||||
$null = $lock.dependencies[$script:BaseTarget].Remove('Microsoft.Windows.SDK.BuildTools')
|
||||
Set-FixtureLock $script:HostLock $lock
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*Missing or duplicate selected SDK*'
|
||||
}
|
||||
|
||||
It 'rejects selected version drift even while central pins stay unchanged' `
|
||||
{
|
||||
$lock = Get-Content -LiteralPath (Join-Path $script:Fixture $script:HostLock) -Raw | ConvertFrom-Json -AsHashtable
|
||||
$lock.dependencies[$script:BaseTarget]['Microsoft.Windows.SDK.BuildTools'].resolved = '10.0.26100.4654'
|
||||
Set-FixtureLock $script:HostLock $lock
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*Unreviewed SDK version/contentHash*'
|
||||
}
|
||||
|
||||
It 'rejects a missing transitive SDK component' `
|
||||
{
|
||||
$lock = Get-Content -LiteralPath (Join-Path $script:Fixture $script:AppLock) -Raw | ConvertFrom-Json -AsHashtable
|
||||
$null = $lock.dependencies[$script:BaseTarget].Remove('Microsoft.WindowsAppSDK.ML')
|
||||
Set-FixtureLock $script:AppLock $lock
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*Missing or duplicate selected SDK*'
|
||||
}
|
||||
|
||||
It 'rejects a changed transitive SDK content hash' `
|
||||
{
|
||||
$lock = Get-Content -LiteralPath (Join-Path $script:Fixture $script:HostLock) -Raw | ConvertFrom-Json -AsHashtable
|
||||
$lock.dependencies[$script:BaseTarget]['Microsoft.Windows.AI.MachineLearning'].contentHash = 'unreviewed'
|
||||
Set-FixtureLock $script:HostLock $lock
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*Unreviewed SDK version/contentHash*'
|
||||
}
|
||||
|
||||
It 'rejects an additional SDK package instead of allowing a family wildcard' `
|
||||
{
|
||||
$lock = Get-Content -LiteralPath (Join-Path $script:Fixture $script:AppLock) -Raw | ConvertFrom-Json -AsHashtable
|
||||
$lock.dependencies[$script:BaseTarget]['Microsoft.WindowsAppSDK.Unreviewed'] = @{ resolved = '2.5.1'; contentHash = 'unreviewed' }
|
||||
Set-FixtureLock $script:AppLock $lock
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*Unreviewed SDK package in source lock*'
|
||||
}
|
||||
|
||||
It 'rejects removing a package from the reviewed manifest' `
|
||||
{
|
||||
$script:Manifest.packages = @($script:Manifest.packages | Where-Object id -NE 'Microsoft.WindowsAppSDK.ML')
|
||||
Set-FixtureLock 'licenses/windows-sdk-packages.json' $script:Manifest
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*exactly the 15 reviewed packages*'
|
||||
}
|
||||
|
||||
It 'rejects a duplicate manifest package' `
|
||||
{
|
||||
$script:Manifest.packages[1] = $script:Manifest.packages[0]
|
||||
Set-FixtureLock 'licenses/windows-sdk-packages.json' $script:Manifest
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*unknown or duplicate package*'
|
||||
}
|
||||
|
||||
It 'rejects implicit reference-pack version drift: <Version>' -ForEach @(@{ Version = '10.0.19041.56' }, @{ Version = '10.0.19041.58' }) `
|
||||
{
|
||||
$script:Assets.project.frameworks[$script:BaseTarget].downloadDependencies[0].version = "[$Version, $Version]"
|
||||
Set-FixtureLock 'src/Qqq.PrintAgent/obj/project.assets.json' $script:Assets
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture -VerifyResolvedAssets } | Should -Throw '*Unreviewed implicit SDK reference version*'
|
||||
}
|
||||
|
||||
It 'rejects missing implicit reference-pack selection' `
|
||||
{
|
||||
$script:Assets.project.frameworks[$script:BaseTarget].downloadDependencies = @()
|
||||
Set-FixtureLock 'src/Qqq.PrintAgent/obj/project.assets.json' $script:Assets
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture -VerifyResolvedAssets } | Should -Throw '*omit the implicit SDK reference pack*'
|
||||
}
|
||||
|
||||
It 'rejects duplicate implicit reference-pack selections' `
|
||||
{
|
||||
$script:Assets.project.frameworks[$script:BaseTarget].downloadDependencies += $script:Assets.project.frameworks[$script:BaseTarget].downloadDependencies[0]
|
||||
Set-FixtureLock 'src/Qqq.PrintAgent/obj/project.assets.json' $script:Assets
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture -VerifyResolvedAssets } | Should -Throw '*Duplicate implicit SDK reference selection*'
|
||||
}
|
||||
|
||||
It 'rejects missing or mismatched restored SDK libraries' `
|
||||
{
|
||||
$script:Assets.libraries['Microsoft.WindowsAppSDK.ML/2.1.94'].sha512 = 'unreviewed'
|
||||
Set-FixtureLock 'src/Qqq.PrintAgent/obj/project.assets.json' $script:Assets
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture -VerifyResolvedAssets } | Should -Throw '*Unreviewed resolved SDK library*'
|
||||
}
|
||||
|
||||
It 'rejects tampered content hashes at the same selected version' `
|
||||
{
|
||||
$lock = Get-Content -LiteralPath (Join-Path $script:Fixture $script:AppLock) -Raw | ConvertFrom-Json -AsHashtable
|
||||
$lock.dependencies[$script:BaseTarget]['Microsoft.WindowsAppSDK'].contentHash = 'unreviewed'
|
||||
Set-FixtureLock $script:AppLock $lock
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*Unreviewed SDK version/contentHash*'
|
||||
}
|
||||
|
||||
It 'checks an additional source lock instead of just the app and layout host' `
|
||||
{
|
||||
$lock = Get-Content -LiteralPath (Join-Path $script:Fixture $script:AppLock) -Raw | ConvertFrom-Json -AsHashtable
|
||||
$lock.dependencies[$script:BaseTarget]['Microsoft.WindowsAppSDK'].resolved = '2.6.0'
|
||||
New-Item -ItemType Directory -Path (Join-Path $script:Fixture 'src/Additional') | Out-Null
|
||||
Set-FixtureLock 'src/Additional/packages.lock.json' $lock
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*Unreviewed SDK version/contentHash*'
|
||||
}
|
||||
|
||||
It 'rejects duplicate JSON package keys instead of silently choosing the last' `
|
||||
{
|
||||
$path = Join-Path $script:Fixture $script:AppLock
|
||||
$json = [IO.File]::ReadAllText($path).Replace('"Microsoft.WindowsAppSDK": {', '"Microsoft.WindowsAppSDK": {}, "Microsoft.WindowsAppSDK": {')
|
||||
[IO.File]::WriteAllText($path, $json)
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*Missing or duplicate selected SDK*'
|
||||
}
|
||||
|
||||
It 'rejects exposing BuildTools as a distributable dependency' `
|
||||
{
|
||||
$path = Join-Path $script:Fixture 'tests/Qqq.PrintAgent.LayoutTests/Qqq.PrintAgent.LayoutTests.csproj'
|
||||
[xml]$project = Get-Content -LiteralPath $path -Raw
|
||||
$project.SelectSingleNode('//PackageReference[@Include="Microsoft.Windows.SDK.BuildTools"]').RemoveAttribute('PrivateAssets')
|
||||
$project.Save($path)
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*BuildTools must remain PrivateAssets=all*'
|
||||
}
|
||||
|
||||
It 'rejects altered Microsoft terms' `
|
||||
{
|
||||
Add-Content -LiteralPath (Join-Path $script:Fixture 'licenses/Microsoft.WindowsAppSDK/2.5.1/license.txt') -Value 'modified'
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*Modified Microsoft notice*'
|
||||
}
|
||||
|
||||
It 'rejects altered provider-specific ML terms' `
|
||||
{
|
||||
Add-Content -LiteralPath (Join-Path $script:Fixture 'licenses/Microsoft.WindowsAppSDK.ML/2.1.94/license.txt') -Value 'modified'
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture } | Should -Throw '*Modified Microsoft notice*'
|
||||
}
|
||||
|
||||
It 'rejects package bytes that differ from the reviewed archives' `
|
||||
{
|
||||
$cache = Join-Path $TestDrive 'bad-package-cache'
|
||||
foreach($package in $script:Manifest.packages)
|
||||
{
|
||||
$lower = $package.id.ToLowerInvariant()
|
||||
$directory = Join-Path $cache "$lower/$($package.version)"
|
||||
New-Item -ItemType Directory -Path $directory -Force | Out-Null
|
||||
Set-Content -LiteralPath (Join-Path $directory "$lower.$($package.version).nupkg") -Value 'not the reviewed SDK'
|
||||
}
|
||||
{ & $script:Guard -RepositoryRoot $script:Fixture -VerifyPackages -PackageCacheRoot $cache } | Should -Throw '*Unreviewed SDK package archive*'
|
||||
}
|
||||
}
|
||||
@@ -1,279 +0,0 @@
|
||||
#Requires -Version 7.4
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
[CmdletBinding()]
|
||||
param(
|
||||
[string] $RepositoryRoot = (Split-Path $PSScriptRoot -Parent),
|
||||
[string] $PackageCacheRoot = $(if($env:NUGET_PACKAGES) { $env:NUGET_PACKAGES } else { Join-Path $HOME '.nuget/packages' }),
|
||||
[switch] $VerifyPackages,
|
||||
[switch] $VerifyResolvedAssets,
|
||||
[string] $PayloadDirectory
|
||||
)
|
||||
|
||||
Set-StrictMode -Version Latest
|
||||
$ErrorActionPreference = 'Stop'
|
||||
# EX-0014 allows only this exact inventory, through 2027-04-30 UTC inclusive.
|
||||
# The required CI and pre-MSI guard must fail when that recorded scope expires.
|
||||
if([DateTimeOffset](Get-Date -AsUTC) -ge [DateTimeOffset]::Parse('2027-05-01T00:00:00Z', [Globalization.CultureInfo]::InvariantCulture))
|
||||
{ throw 'Windows SDK exception EX-0014 expired after 2027-04-30 UTC; renewed approval is required.' }
|
||||
$expectedIds = @(
|
||||
'Microsoft.Windows.AI.MachineLearning', 'Microsoft.Windows.SDK.BuildTools',
|
||||
'Microsoft.Windows.SDK.BuildTools.MSIX', 'Microsoft.Windows.SDK.NET.Ref',
|
||||
'Microsoft.WindowsAppSDK', 'Microsoft.WindowsAppSDK.AI', 'Microsoft.WindowsAppSDK.Base',
|
||||
'Microsoft.WindowsAppSDK.DWrite', 'Microsoft.WindowsAppSDK.Foundation',
|
||||
'Microsoft.WindowsAppSDK.InteractiveExperiences', 'Microsoft.WindowsAppSDK.ML',
|
||||
'Microsoft.WindowsAppSDK.Runtime', 'Microsoft.WindowsAppSDK.Search',
|
||||
'Microsoft.WindowsAppSDK.Widgets', 'Microsoft.WindowsAppSDK.WinUI'
|
||||
)
|
||||
$directIds = @('Microsoft.WindowsAppSDK', 'Microsoft.Windows.SDK.BuildTools')
|
||||
$referenceId = 'Microsoft.Windows.SDK.NET.Ref'
|
||||
$sdkNamePattern = '^Microsoft\.Windows(?:AppSDK(?:\.|$)|\.SDK\.|\.AI\.)'
|
||||
$root = [IO.Path]::GetFullPath($RepositoryRoot)
|
||||
$manifestPath = Join-Path $root 'licenses/windows-sdk-packages.json'
|
||||
$manifest = Get-Content -LiteralPath $manifestPath -Raw | ConvertFrom-Json
|
||||
if($manifest.schemaVersion -ne 1 -or @($manifest.packages).Count -ne $expectedIds.Count)
|
||||
{ throw 'SDK manifest must contain exactly the 15 reviewed packages.' }
|
||||
$packages = @{}
|
||||
$notices = @{}
|
||||
foreach($package in $manifest.packages)
|
||||
{
|
||||
if($package.id -cnotin $expectedIds -or $packages.ContainsKey($package.id))
|
||||
{ throw 'SDK manifest contains an unknown or duplicate package.' }
|
||||
$isReference = $package.id -ceq $referenceId
|
||||
$expectedRole = if($package.id -cin @('Microsoft.Windows.SDK.BuildTools', 'Microsoft.Windows.SDK.BuildTools.MSIX')) { 'build-only' } elseif($isReference) { 'runtime-projections' } else { 'runtime' }
|
||||
if($package.central -ne ($package.id -cin $directIds) -or
|
||||
$package.resolution -cne $(if($isReference) { 'implicit-download' } else { 'lock' }) -or
|
||||
$package.redistribution -cne $expectedRole -or $package.version -notmatch '^\d+\.\d+\.\d+(?:\.\d+)?$' -or
|
||||
$package.sha256 -cnotmatch '^[A-F0-9]{64}$' -or $package.contentHash -cnotmatch '^[A-Za-z0-9+/]{86}==$' -or
|
||||
@($package.legalFiles).Count -eq 0)
|
||||
{ throw "Invalid reviewed SDK manifest entry: $($package.id)." }
|
||||
foreach($legal in $package.legalFiles)
|
||||
{
|
||||
if($legal.path -notmatch '^licenses/[A-Za-z0-9./_-]+$' -or $legal.path.Contains('..', [StringComparison]::Ordinal) -or
|
||||
$legal.sha256 -cnotmatch '^[A-F0-9]{64}$' -or ($notices.ContainsKey($legal.path) -and $notices[$legal.path] -cne $legal.sha256))
|
||||
{ throw 'Invalid or conflicting SDK legal-file pin.' }
|
||||
$notices[$legal.path] = $legal.sha256
|
||||
}
|
||||
$packages[$package.id] = $package
|
||||
}
|
||||
# Pin the approved authored LF manifest as well as its individual values. A
|
||||
# coordinated manifest/lock change must not silently broaden the recorded scope.
|
||||
if((Get-FileHash -LiteralPath $manifestPath -Algorithm SHA256).Hash -cne '1411401F7BD70842EB4A40220261DD1009482D47064CCBFBC0061AC4E79DDA2E')
|
||||
{ throw 'Reviewed SDK inventory manifest changed; renewed scope approval is required.' }
|
||||
$workflow = [IO.File]::ReadAllText((Join-Path $root '.github/workflows/pr-gates.yml'))
|
||||
$allowanceKeys = [regex]::Matches($workflow, '(?m)^\s*allow-dependencies-licenses:')
|
||||
$allowanceBlock = [regex]::Matches($workflow, '(?m)^ allow-dependencies-licenses: >-\r?\n((?: [^\r\n]+(?:\r?\n|$))+)')
|
||||
if($allowanceKeys.Count -ne 1 -or $allowanceBlock.Count -ne 1)
|
||||
{ throw 'Exactly one explicit SDK license allowance block is required.' }
|
||||
$allowed = @($allowanceBlock[0].Groups[1].Value.Split(',') | ForEach-Object Trim | Sort-Object -CaseSensitive)
|
||||
# EX-0015 adds exactly one development-only npm purl; check-script-quality.py pins its version,
|
||||
# lock integrity and license bytes. Any other ecosystem, package or versioned purl stays rejected here.
|
||||
$expectedAllowances = @(@($expectedIds | ForEach-Object { "pkg:nuget/$_" }) + 'pkg:npm/uri-js' | Sort-Object -CaseSensitive)
|
||||
if(($allowed -join ',') -cne ($expectedAllowances -join ','))
|
||||
{ throw 'SDK license allowance must contain only the 15 exact reviewed package names plus the EX-0015 pkg:npm/uri-js entry.' }
|
||||
[string[]]$lockedIds = @($expectedIds | Where-Object { $_ -cne $referenceId })
|
||||
[xml]$central = Get-Content -LiteralPath (Join-Path $root 'Directory.Packages.props') -Raw
|
||||
foreach($id in $directIds)
|
||||
{
|
||||
$versions = @($central.SelectNodes('//PackageVersion') | Where-Object { $_.GetAttribute('Include') -ieq $id })
|
||||
if($versions.Count -ne 1 -or $versions[0].GetAttribute('Version') -cne $packages[$id].version)
|
||||
{ throw "Exact single central version required: $id." }
|
||||
}
|
||||
|
||||
$sourceDirectories = @('src', 'tests', 'installer') | ForEach-Object { Join-Path $root $_ } | Where-Object { Test-Path -LiteralPath $_ }
|
||||
$locks = @(Get-ChildItem -LiteralPath $sourceDirectories -Filter packages.lock.json -Recurse -File | Where-Object { $_.FullName -notmatch '[/\\](bin|obj|TestResults)[/\\]' })
|
||||
if($locks.Count -eq 0) { throw 'No committed source package locks found.' }
|
||||
$requiredProjects = @('src/Qqq.PrintAgent', 'tests/Qqq.PrintAgent.LayoutTests')
|
||||
foreach($relative in $requiredProjects)
|
||||
{
|
||||
$projectDirectory = Join-Path $root $relative
|
||||
$project = Join-Path $projectDirectory ((Split-Path $relative -Leaf) + '.csproj')
|
||||
[xml]$definition = Get-Content -LiteralPath $project -Raw
|
||||
foreach($id in $directIds)
|
||||
{
|
||||
$references = @($definition.SelectNodes('//PackageReference') | Where-Object { $_.GetAttribute('Include') -ieq $id })
|
||||
if($references.Count -ne 1 -or $references[0].HasAttribute('Version') -or $references[0].HasAttribute('VersionOverride'))
|
||||
{ throw "Exactly one central SDK reference required in $relative for $id." }
|
||||
if($id -eq 'Microsoft.Windows.SDK.BuildTools' -and $references[0].GetAttribute('PrivateAssets') -ine 'all')
|
||||
{ throw "BuildTools must remain PrivateAssets=all in $relative." }
|
||||
}
|
||||
if(!(Test-Path -LiteralPath (Join-Path $projectDirectory 'packages.lock.json') -PathType Leaf))
|
||||
{ throw "Missing SDK project lock: $relative." }
|
||||
}
|
||||
|
||||
$selections = 0
|
||||
foreach($lock in $locks)
|
||||
{
|
||||
$json = [Text.Json.JsonDocument]::Parse([IO.File]::ReadAllText($lock.FullName))
|
||||
try
|
||||
{
|
||||
$targets = @($json.RootElement.GetProperty('dependencies').EnumerateObject())
|
||||
if($targets.Count -eq 0) { throw "Empty package lock: $($lock.FullName)." }
|
||||
$required = $requiredProjects | Where-Object { [IO.Path]::GetFullPath((Join-Path $root $_)) -ieq $lock.DirectoryName }
|
||||
$baseTargets = 0
|
||||
foreach($target in $targets)
|
||||
{
|
||||
$isBase = !$target.Name.Contains('/', [StringComparison]::Ordinal)
|
||||
if($isBase) { $baseTargets++ }
|
||||
foreach($selected in $target.Value.EnumerateObject())
|
||||
{
|
||||
if($selected.Name -match $sdkNamePattern -and !$packages.ContainsKey($selected.Name))
|
||||
{ throw "Unreviewed SDK package in source lock: $($selected.Name)." }
|
||||
}
|
||||
foreach($id in $expectedIds)
|
||||
{
|
||||
$entries = @($target.Value.EnumerateObject() | Where-Object Name -IEQ $id)
|
||||
if($entries.Count -gt 1 -or ($required -and $isBase -and $id -cin $lockedIds -and $entries.Count -ne 1))
|
||||
{ throw "Missing or duplicate selected SDK in $($lock.FullName): $id." }
|
||||
foreach($entry in $entries)
|
||||
{
|
||||
if($entry.Value.GetProperty('resolved').GetString() -cne $packages[$id].version -or $entry.Value.GetProperty('contentHash').GetString() -cne $packages[$id].contentHash)
|
||||
{ throw "Unreviewed SDK version/contentHash in $($lock.FullName): $id." }
|
||||
$selections++
|
||||
}
|
||||
}
|
||||
}
|
||||
if($required -and $baseTargets -eq 0) { throw 'SDK lock lacks a base target framework.' }
|
||||
}
|
||||
finally { $json.Dispose() }
|
||||
}
|
||||
|
||||
foreach($name in $notices.Keys)
|
||||
{
|
||||
if((Get-FileHash -LiteralPath (Join-Path $root $name) -Algorithm SHA256).Hash -cne $notices[$name])
|
||||
{ throw "Modified Microsoft notice: $name." }
|
||||
}
|
||||
|
||||
$assetCount = 0
|
||||
if($VerifyPackages -or $VerifyResolvedAssets -or $PayloadDirectory)
|
||||
{
|
||||
$requiredAsset = [IO.Path]::GetFullPath((Join-Path $root 'src/Qqq.PrintAgent/obj/project.assets.json'))
|
||||
if(!(Test-Path -LiteralPath $requiredAsset -PathType Leaf)) { throw 'Missing restored application assets.' }
|
||||
$assets = @(Get-ChildItem -LiteralPath $sourceDirectories -Filter project.assets.json -Recurse -File | Where-Object { $_.FullName -notmatch '[/\\]bin[/\\]' })
|
||||
foreach($asset in $assets)
|
||||
{
|
||||
$json = [Text.Json.JsonDocument]::Parse([IO.File]::ReadAllText($asset.FullName))
|
||||
try
|
||||
{
|
||||
$required = $asset.FullName -ieq $requiredAsset
|
||||
$selectedIds = [Collections.Generic.HashSet[string]]::new([StringComparer]::OrdinalIgnoreCase)
|
||||
foreach($library in $json.RootElement.GetProperty('libraries').EnumerateObject())
|
||||
{
|
||||
$parts = $library.Name.Split('/')
|
||||
if($parts[0] -notmatch $sdkNamePattern) { continue }
|
||||
if(!$packages.ContainsKey($parts[0]) -or !$selectedIds.Add($parts[0]) -or
|
||||
$parts.Length -ne 2 -or $parts[1] -cne $packages[$parts[0]].version -or
|
||||
$library.Value.GetProperty('sha512').GetString() -cne $packages[$parts[0]].contentHash)
|
||||
{ throw "Unreviewed resolved SDK library in $($asset.FullName)." }
|
||||
}
|
||||
if($required -and @($lockedIds | Where-Object { !$selectedIds.Contains($_) }).Count -gt 0)
|
||||
{ throw 'Restored application assets omit a locked SDK package.' }
|
||||
$referenceCount = 0
|
||||
foreach($framework in $json.RootElement.GetProperty('project').GetProperty('frameworks').EnumerateObject())
|
||||
{
|
||||
$downloads = [Text.Json.JsonElement]::new()
|
||||
if(!$framework.Value.TryGetProperty('downloadDependencies', [ref]$downloads)) { continue }
|
||||
$referenceSelections = @($downloads.EnumerateArray() | Where-Object { $_.GetProperty('name').GetString() -ieq $referenceId })
|
||||
if($referenceSelections.Count -gt 1) { throw 'Duplicate implicit SDK reference selection.' }
|
||||
foreach($match in $referenceSelections)
|
||||
{
|
||||
$version = $packages[$referenceId].version
|
||||
if($match.GetProperty('version').GetString() -cne "[$version, $version]")
|
||||
{ throw "Unreviewed implicit SDK reference version in $($asset.FullName)." }
|
||||
$referenceCount++
|
||||
}
|
||||
}
|
||||
if($required -and $referenceCount -eq 0) { throw 'Restored application assets omit the implicit SDK reference pack.' }
|
||||
$assetCount++
|
||||
}
|
||||
finally { $json.Dispose() }
|
||||
}
|
||||
}
|
||||
|
||||
$archives = @{}
|
||||
if($VerifyPackages -or $PayloadDirectory)
|
||||
{
|
||||
foreach($id in $packages.Keys)
|
||||
{
|
||||
$lower = $id.ToLowerInvariant()
|
||||
$version = $packages[$id].version
|
||||
$archive = Join-Path $PackageCacheRoot "$lower/$version/$lower.$version.nupkg"
|
||||
if((Get-FileHash -LiteralPath $archive -Algorithm SHA256).Hash -cne $packages[$id].sha256)
|
||||
{ throw "Unreviewed SDK package archive: $id." }
|
||||
$metadata = Get-Content -LiteralPath (Join-Path (Split-Path $archive -Parent) '.nupkg.metadata') -Raw | ConvertFrom-Json
|
||||
if($metadata.contentHash -cne $packages[$id].contentHash)
|
||||
{ throw "Unreviewed NuGet cache contentHash: $id." }
|
||||
$zip = [IO.Compression.ZipFile]::OpenRead($archive)
|
||||
try
|
||||
{
|
||||
$entries = @($packages[$id].legalFiles | Where-Object archiveEntry | ForEach-Object { @{ entry = $_.archiveEntry; sha256 = $_.sha256 } }) + @($packages[$id].runtimeProjections)
|
||||
foreach($expected in $entries)
|
||||
{
|
||||
$entry = $zip.GetEntry($expected.entry)
|
||||
if($null -eq $entry) { throw "Missing reviewed archive entry: $id / $($expected.entry)." }
|
||||
$stream = $entry.Open()
|
||||
try { $hash = [Convert]::ToHexString([Security.Cryptography.SHA256]::HashData($stream)) }
|
||||
finally { $stream.Dispose() }
|
||||
if($hash -cne $expected.sha256) { throw "Archive legal/projection hash mismatch: $id / $($expected.entry)." }
|
||||
}
|
||||
}
|
||||
finally { $zip.Dispose() }
|
||||
$archives[$id] = $archive
|
||||
}
|
||||
}
|
||||
|
||||
if($PayloadDirectory)
|
||||
{
|
||||
$payload = [IO.Path]::GetFullPath($PayloadDirectory)
|
||||
foreach($name in @('LICENSE', 'NOTICE'))
|
||||
{
|
||||
if((Get-FileHash -LiteralPath (Join-Path $payload "app/$name")).Hash -cne (Get-FileHash -LiteralPath (Join-Path $root $name)).Hash)
|
||||
{ throw "Missing or changed project notice in App payload: $name." }
|
||||
}
|
||||
foreach($name in $notices.Keys)
|
||||
{
|
||||
$relative = $name.Substring('licenses/'.Length)
|
||||
if((Get-FileHash -LiteralPath (Join-Path $payload "app/ThirdPartyNotices/$relative")).Hash -cne $notices[$name])
|
||||
{ throw "Missing or changed Microsoft notice in App payload: $name." }
|
||||
}
|
||||
if((Get-FileHash -LiteralPath (Join-Path $payload 'app/ThirdPartyNotices/windows-sdk-packages.json')).Hash -cne (Get-FileHash -LiteralPath $manifestPath).Hash)
|
||||
{ throw 'Missing or changed SDK legal-file manifest in App payload.' }
|
||||
# Legal text and the exact reviewed reference-pack runtime projections may ship.
|
||||
# Other build/reference package files, even renamed, must not enter any process.
|
||||
$allowedHashes = [Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal)
|
||||
foreach($hash in $notices.Values) { $null = $allowedHashes.Add($hash) }
|
||||
foreach($projection in $packages[$referenceId].runtimeProjections) { $null = $allowedHashes.Add($projection.sha256) }
|
||||
$toolHashes = [Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal)
|
||||
$toolLengths = [Collections.Generic.HashSet[long]]::new()
|
||||
foreach($package in $packages.Values | Where-Object redistribution -NE 'runtime')
|
||||
{
|
||||
$archive = [IO.Compression.ZipFile]::OpenRead($archives[$package.id])
|
||||
try
|
||||
{
|
||||
foreach($entry in $archive.Entries)
|
||||
{
|
||||
if($entry.Length -eq 0 -or $entry.FullName -match '^(?:_rels/|package/|\[Content_Types\]|\.signature)') { continue }
|
||||
$stream = $entry.Open()
|
||||
try { $hash = [Convert]::ToHexString([Security.Cryptography.SHA256]::HashData($stream)) }
|
||||
finally { $stream.Dispose() }
|
||||
if($allowedHashes.Contains($hash)) { continue }
|
||||
$null = $toolHashes.Add($hash)
|
||||
$null = $toolLengths.Add($entry.Length)
|
||||
}
|
||||
}
|
||||
finally { $archive.Dispose() }
|
||||
$archiveInfo = Get-Item -LiteralPath $archives[$package.id]
|
||||
$null = $toolLengths.Add($archiveInfo.Length)
|
||||
$null = $toolHashes.Add($package.sha256)
|
||||
}
|
||||
foreach($file in Get-ChildItem -LiteralPath $payload -Recurse -File)
|
||||
{
|
||||
if($file.Attributes.HasFlag([IO.FileAttributes]::ReparsePoint)) { throw 'Linked payload file rejected.' }
|
||||
if($toolLengths.Contains($file.Length) -and $toolHashes.Contains((Get-FileHash -LiteralPath $file.FullName -Algorithm SHA256).Hash))
|
||||
{
|
||||
throw "Build/reference SDK package content must not be redistributed: $($file.Name)."
|
||||
}
|
||||
}
|
||||
}
|
||||
Write-Output "Windows SDK inventory passed: 15 pinned packages, $($locks.Count) source locks, $selections exact selections, $assetCount resolved asset files; $($notices.Count) Microsoft legal files verified."
|
||||
+4
-14
@@ -1,38 +1,28 @@
|
||||
#Requires -Version 7.4
|
||||
# Copyright (c) 2026 James Maes
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
[CmdletBinding()]
|
||||
param([string] $ProtocolFixtures)
|
||||
param()
|
||||
|
||||
$ErrorActionPreference = 'Stop'
|
||||
Set-StrictMode -Version Latest
|
||||
$projectRoot = Split-Path -Parent $PSScriptRoot
|
||||
$resultsDirectory = Join-Path $projectRoot ('TestResults/verify-' + [Guid]::NewGuid().ToString('N'))
|
||||
if(-not $ProtocolFixtures) { $ProtocolFixtures = Join-Path (Split-Path -Parent $projectRoot) 'qqq-print-protocol\fixtures' }
|
||||
$protocolFixtures = Join-Path (Split-Path -Parent $projectRoot) 'qqq-print-protocol\fixtures'
|
||||
if(-not (Test-Path -LiteralPath $protocolFixtures))
|
||||
{
|
||||
throw 'Check out the pinned qqq-print-protocol repository beside qqq-print-agent before running verification.'
|
||||
}
|
||||
foreach($fixture in @('claim.response.json', 'enroll.response.json', 'control-poll.response.json', 'printing-session.response.json', 'printing-session-bound.response.json'))
|
||||
{
|
||||
if(-not (Test-Path -LiteralPath (Join-Path $ProtocolFixtures $fixture) -PathType Leaf))
|
||||
{
|
||||
throw "Required protocol fixture is missing: $fixture. Use the protocol revision pinned in .github/workflows/ci.yml, or pass its fixtures directory with -ProtocolFixtures."
|
||||
}
|
||||
}
|
||||
Push-Location $projectRoot
|
||||
try
|
||||
{
|
||||
& dotnet restore Qqq.PrintAgent.slnx '-p:Platform=x64' --locked-mode
|
||||
if($LASTEXITCODE -ne 0) { throw 'Locked dependency restore failed.' }
|
||||
& dotnet build Qqq.PrintAgent.slnx --configuration Release '-p:Platform=x64' "-p:PrintingProtocolFixtures=$ProtocolFixtures" --no-restore -warnaserror
|
||||
& dotnet build Qqq.PrintAgent.slnx --configuration Release '-p:Platform=x64' --no-restore -warnaserror
|
||||
if($LASTEXITCODE -ne 0) { throw 'Solution build failed.' }
|
||||
foreach($project in @('tests/Qqq.PrintAgent.Core.Tests', 'tests/Qqq.PrintAgent.Cli.Tests'))
|
||||
{
|
||||
# Solution mappings use AnyCPU for these projects; direct x64 test invocations
|
||||
# must build their own matching output instead of selecting a stale x64 DLL.
|
||||
& dotnet test $project --configuration Release '-p:Platform=x64' "-p:PrintingProtocolFixtures=$ProtocolFixtures" --no-restore --settings coverage.runsettings --logger trx --collect 'XPlat Code Coverage' --results-directory $resultsDirectory
|
||||
& dotnet test $project --configuration Release '-p:Platform=x64' --no-restore --settings coverage.runsettings --logger trx --collect 'XPlat Code Coverage' --results-directory $resultsDirectory
|
||||
if($LASTEXITCODE -ne 0) { throw "Tests failed: $project" }
|
||||
}
|
||||
Write-Output "Current verification evidence: $resultsDirectory"
|
||||
|
||||
@@ -13,10 +13,6 @@
|
||||
is run separately and must not be inferred from a successful unit-test run.
|
||||
Report each suite separately; duplicate package measurements must not be averaged. -->
|
||||
<RunSettings>
|
||||
<!-- A test run that executes zero tests (for example, a test assembly blocked from loading) must fail, not pass. -->
|
||||
<RunConfiguration>
|
||||
<TreatNoTestsAsError>true</TreatNoTestsAsError>
|
||||
</RunConfiguration>
|
||||
<DataCollectionRunSettings>
|
||||
<DataCollectors>
|
||||
<DataCollector friendlyName="XPlat Code Coverage">
|
||||
|
||||
+4
-112
@@ -1,122 +1,14 @@
|
||||
# Acceptance evidence
|
||||
|
||||
## Installed 0.3.2 through the real in-app update — 2026-11-01
|
||||
## Installed 0.1.9 audit correction — 2026-10-31
|
||||
|
||||
The [0.3.2 release](https://github.com/QRun-IO/qqq-print-agent/releases/tag/v0.3.2-rc.1)
|
||||
was verified against signed tag source
|
||||
`268f951b6728b0e69fedaf46769785c3f5ae55f4`, all four assets/checksums and
|
||||
GitHub attestations. [Release run 41324312106](https://github.com/QRun-IO/qqq-print-agent/actions/runs/41324312106)
|
||||
completed all nine jobs. Published and installed MSI SHA-256:
|
||||
`1191C337265469EB06136AF232DB57FAC6BC5014357521D80B35E5CCA5AF6E18`.
|
||||
The MSI remains unsigned; source signatures and build attestations are separate
|
||||
from publisher code signing.
|
||||
|
||||
The user operated the installed companion's **Help → Check for updates**, chose
|
||||
**Not now** and confirmed continued responsiveness, then chose **Update and
|
||||
restart**. The actual coordinator handed off to the copied installed 0.3.1 CLI
|
||||
helper, MSI returned 0, and the companion automatically reopened. The user
|
||||
confirmed its **Connected** state and both printers.
|
||||
|
||||
Independent before/after observations verified each App, Service and CLI
|
||||
executable against the published payload bytes and identical full ProductVersion
|
||||
`0.3.2-rc.1+268f951b6728b0e69fedaf46769785c3f5ae55f4`. The retained update request
|
||||
matched the original companion identity, copied helper and published MSI. The
|
||||
new service was Running with automatic LocalSystem configuration and restored
|
||||
the native QQQ session and connected WebSocket. Stable identity, pairing,
|
||||
printer exposure and profiles were preserved. All 38 prior local job rows and
|
||||
37 prior server job rows retained their recorded field digests; one additional
|
||||
row in each view was accounted for separately, with no missing or changed old
|
||||
rows. The observers submitted no jobs and did not repeat the installation.
|
||||
|
||||
The diagnostic launcher's final summary failed after its observer child exited
|
||||
successfully: reading stdout while its writer remained open caused a Windows
|
||||
file-sharing violation. The original failed launcher record was preserved.
|
||||
Both original child reports passed, and their hash chain, published-byte matches
|
||||
and preservation comparisons were independently revalidated. This acceptance
|
||||
uses those independent reports and the operator's UI confirmation; it does not
|
||||
claim that the diagnostic launcher passed.
|
||||
|
||||
The old 0.3.1 helper executed this update. The new three-component guard is
|
||||
covered by source regressions and protects future updates. Actual download or
|
||||
installer failure/cancellation, restart-required reporting and reboot recovery
|
||||
remain separate cases. Successful paper output was confirmed on 0.3.1 below;
|
||||
this update check does not claim new 0.3.2 physical-output qualification. The
|
||||
historical layout-cycle cause remains unproven. Real Authentik container checks
|
||||
use an unreleased QQQ API 1.9 candidate and an HTTPS probe callback; installed
|
||||
Windows browser/private-callback acceptance still requires a compatible
|
||||
published QQQ runtime and configured HTTPS provider. No stable 1.0 claim is made.
|
||||
|
||||
## Installed published 0.3.1 — 2026-11-01
|
||||
|
||||
The [0.3.1 release](https://github.com/QRun-IO/qqq-print-agent/releases/tag/v0.3.1-rc.1)
|
||||
was verified against its signed tag, source
|
||||
`346fc285198908c47a2ee9db7b9adb53d5e88c3c`, checksums and all four asset
|
||||
attestations from [release run 41295660341](https://github.com/QRun-IO/qqq-print-agent/actions/runs/41295660341).
|
||||
The installed MSI SHA-256 is
|
||||
`5DE3141DE8861FB96C41DF96A6202F6DFBC9DAAE9C14C6436745CEC66876DCC4`.
|
||||
Read-only MSI inspection verified coherent payload versions, 995 stable existing
|
||||
component identities and all 13 packaged legal files before installation.
|
||||
|
||||
The direct MSI upgrade returned 0 without a reboot, restored the native QQQ
|
||||
session and connected WebSocket, and preserved pairing, printer profiles,
|
||||
exposure, log policy and all 28 local job receipts. All three installed product
|
||||
versions match the published source. The original 27 server jobs also retained
|
||||
all five history/content/receipt digests while six later jobs were accounted for
|
||||
separately. The operator confirmed successful test prints and a responsive window;
|
||||
that confirmation does not identify every document format separately.
|
||||
|
||||
Repeated nonprinting native tests exercised the dialog, real timer, fake queued
|
||||
response, job progression, banner dismissal, status transitions and navigation.
|
||||
The original and current UI both passed at the observed 125% DPI and 1100 by 994
|
||||
outer window size. The original layout-cycle cause remains unproven. The exact
|
||||
fatal-error mitigation was separately qualified with a real induced native
|
||||
exception; this is not an underlying layout fix.
|
||||
|
||||
This 0.3.1 checkpoint used a direct MSI installation. The subsequent real AppKit
|
||||
transition to 0.3.2 is recorded above. Its new component-coherence guard passed
|
||||
73 focused updater cases and the integrated 426-test Release gate. The frozen
|
||||
QQQ RC.20 runtime does not advertise the required API 1.9 native-session grant.
|
||||
|
||||
## Installed published 0.2.0 and confirmed output — 2026-10-31
|
||||
|
||||
The exact published `0.2.0-rc.1` MSI completed with exit 0 and no reboot
|
||||
requirement, retaining pairing, exposed-printer choices and journal history.
|
||||
The installed service completed native QQQ table-based sign-in and explicit
|
||||
association of the existing device. Server pause, disconnect, reconnect and
|
||||
resume were observed; inventory refresh returned a successful receipt.
|
||||
|
||||
Native QQQ Letter PDF and 4 × 6-inch, 300-dpi Zebra ZPL diagnostics reached
|
||||
SPOOLED with the reviewed content hashes. **The user confirmed that both outputs
|
||||
printed correctly**, and manually confirmed the companion's **Connected** footer
|
||||
and both printers. This manual observation is distinct from the historical
|
||||
16-test automated UI run on 0.1.9 below.
|
||||
|
||||
This establishes the local installed 0.2 happy path. It does not establish the
|
||||
0.3 realtime transport/Jobs UI, configured Authentik renewal, remote
|
||||
production deployment or broad driver qualification. The proposed restart
|
||||
elevation was canceled before execution, so this checkpoint does not claim a
|
||||
restart test. Source/CI checks for 0.3 remain separate from installed acceptance.
|
||||
|
||||
## Published 0.1.9-rc.1 — 2026-10-31
|
||||
|
||||
[v0.1.9-rc.1](https://github.com/QRun-IO/qqq-print-agent/releases/tag/v0.1.9-rc.1) is published from protected main revision `cf0e362`. [Release workflow 41190815995](https://github.com/QRun-IO/qqq-print-agent/actions/runs/41190815995) passed. The MSI, `SHA256SUMS`, `Install-Branded.ps1` and `branding.example.json` were verified against release checksums and asset digests; provenance attestations for all four assets were verified against the release workflow and tag.
|
||||
|
||||
| Package | SHA-256 | Verified scope |
|
||||
| --- | --- | --- |
|
||||
| Installed CI MSI | `6DDA81FD515D33E2D27499AC9774D772B1C78094620CDCE098C2D28738D12EC1` | State-preserving upgrade and 16 installed UI checks below |
|
||||
| Published release MSI | `04A0DDEB304F533E243707FA9FF654EA2760BFA6A7C6B0557718E288B0C1BE6C` | Release checksum, asset digest and provenance verification |
|
||||
|
||||
These MSI files are distinct builds. Source comparison between the installed candidate and the published revision found only acceptance/session/task documentation changes; runtime sources are unchanged. The published MSI has not been separately reinstalled, so installed acceptance applies to the CI package above. Both packages remain unsigned prereleases; provenance attestations are not publisher code signing.
|
||||
|
||||
## Installed 0.1.9 CI-package qualification — 2026-10-31
|
||||
|
||||
Reviewed source `13aa84c` passed all ten required hosted checks: the 255-test [CI build 41185716708](https://github.com/QRun-IO/qqq-print-agent/actions/runs/41185716708), security scans, both CodeQL languages, 12 PowerShell tests and script analysis.
|
||||
Reviewed source `13aa84c` passed all ten required hosted checks, including the 255-test build, security scans, both CodeQL languages, 12 PowerShell tests and script analysis. Exact CI MSI SHA256: `6DDA81FD515D33E2D27499AC9774D772B1C78094620CDCE098C2D28738D12EC1`.
|
||||
|
||||
The authorized machine upgrade completed with MSI exit 0 and no restart requirement. Old and new service peers authenticated; protected credential bytes and all journal history were retained. Read-only inspection of a protected closed backup verified integrity and no active or newly uncertain submission before installation. Post-install service, connection and history queries succeeded. All **16 installed UI checks passed in one run**, and the installed companion opened successfully. The package reports `0.1.9-rc.1+4602769b00ac76a6dbded3b4e63873f82e8ad287`, identifying the CI merge revision for the reviewed branch.
|
||||
|
||||
This verifies the corrected management transport and local installed service/app upgrade. It does not establish fresh physical output, Windows reboot behavior, updater-initiated elevation, hostile-tree rollback, remote deployment or publisher signing. No print was submitted by the installer or UI tests. Publication and release-artifact verification are recorded separately above.
|
||||
This verifies the corrected management transport and local installed service/app upgrade. It does not establish fresh physical output, Windows reboot behavior, updater-initiated elevation, hostile-tree rollback, remote deployment or publisher signing. No print was submitted by the installer or UI tests. Public release publication remains pending.
|
||||
|
||||
## Historical 0.1.7 Zebra PDF correction and confirmed output — 2026-10-30
|
||||
## Zebra PDF configuration correction and confirmed output — 2026-10-30
|
||||
|
||||
The user confirmed the laser PDF and Zebra ZPL output. The original Zebra PDF reached SPOOLED but produced no label. Windows machine **Printer properties → Advanced → Printing Defaults** was configured for **4.09 × 2 inches / Thermal Transfer**, while the installed stock is **4 × 6 inches and direct thermal, without ribbon**. The defaults were changed to **4.00 × 6.00 inches / Thermal Direct**, preserving other options; the saved machine DEVMODE dimensions were verified as 1016 × 1524 tenths of a millimeter. The printer was also returned to direct-thermal mode and unpaused without producing output during that correction.
|
||||
|
||||
|
||||
+7
-17
@@ -1,7 +1,5 @@
|
||||
# Administrator operations
|
||||
|
||||
These instructions describe client **1.0.1** with qbit-printing **1.0.0**, native printing API **2.3** and wire payload **v1**. See [realtime architecture and settings](REALTIME.md) for the coordinated server requirement.
|
||||
|
||||
## Service and data
|
||||
|
||||
| Item | Location / identity |
|
||||
@@ -9,11 +7,10 @@ These instructions describe client **1.0.1** with qbit-printing **1.0.0**, nativ
|
||||
| Service | `QqqPrintAgent`, automatic, LocalSystem |
|
||||
| Local management | Administrator-only named pipe `QqqPrintAgent` |
|
||||
| Service data | `%ProgramData%\QqqPrintAgent` |
|
||||
| Credentials | Device proof and QQQ session protected separately with Windows DPAPI CurrentUser under LocalSystem |
|
||||
| Credential | `connection.dpapi`, Windows DPAPI CurrentUser under LocalSystem |
|
||||
| Submission journal | `journal.db` and SQLite WAL/SHM files |
|
||||
| Worker coordination | Exclusive `worker.lock` in the data directory |
|
||||
| Desktop preferences | AppKit's per-user `qqq-print-agent` directory |
|
||||
| Shared service/companion logs | `%ProgramData%\QqqPrintAgent\logs` |
|
||||
| Desktop preferences/logs | AppKit's per-user `qqq-print-agent` directory |
|
||||
|
||||
The MSI applies SYSTEM/Administrators permissions to the service directory. Do not loosen those ACLs or copy its credential to another machine/account. Backups should treat the entire directory as sensitive. Do not upload the database or protected configuration to public issues.
|
||||
|
||||
@@ -24,21 +21,15 @@ Get-Service QqqPrintAgent, Spooler
|
||||
& 'C:\Program Files\QQQ Print Agent\Cli\qqq-print-agent.exe' service-status
|
||||
```
|
||||
|
||||
Use the actual install path if it differs. Normal CLI commands and the companion use the authenticated installed service. Its printer list reflects the service identity; explicit isolated legacy diagnostics may see different queues under their invoking account.
|
||||
Use the actual install path if it differs. The companion's printer list reflects the service identity. Running CLI `printers` directly reflects the current CLI account instead, which may see different queues.
|
||||
|
||||
Use the built-in AppKit activity log for shared service and companion events, with source labels and severity filtering. Windows Event Viewer can also help diagnose service-host startup failures. Record relevant timestamps, job IDs and error text without customer document contents.
|
||||
Windows service messages are emitted through .NET hosting logging. Review Windows Event Viewer and the desktop activity log for the relevant timestamp; record job IDs and error text without customer document contents.
|
||||
|
||||
## Credentials and network
|
||||
|
||||
Sign in through standard QQQ authentication, then associate an existing unbound pairing or enroll a new device explicitly. Every normal printing request requires the current QQQ user session and secondary device proof; server user, tenant and record permissions still apply. Session renewal does not change the journal's device identity. Revoke the device in QQQ when decommissioning a machine. Revocation cannot recall a job already accepted by the Windows spooler.
|
||||
QQQ issues an enrollment code and a dedicated device credential. Each device is scoped by the server; the connector may claim and download only its assigned work. Revoke the device in QQQ when decommissioning a machine. Revocation cannot recall a job already accepted by the Windows spooler.
|
||||
|
||||
Allow outbound WSS upgrades and HTTPS to the configured QQQ origin. The service maintains one authenticated realtime connection for small controls/status/receipts and uses independent HTTPS streams for documents. There is no periodic job/control polling or fallback. Certificate validation uses Windows/.NET trust; do not disable it. Plain HTTP/WS is an explicit loopback development exception. Proxy-specific authentication and long-running production connections require deployment qualification.
|
||||
|
||||
## Queue and control health
|
||||
|
||||
The companion displays observed connection health, desired pause/disconnect state and the last remote action/outcome. The Jobs page includes a bounded preview of at most 50 server-queued jobs, not the entire cloud backlog. Inspect server job and command records for authoritative status. A green connection or READY printer observation does not prove physical output.
|
||||
|
||||
Use QQQ's device actions to pause/resume dispatch, disconnect/reconnect operation, refresh inventory or revoke credentials. Disconnect retains the realtime control path for reconnect and in-flight receipts. Queue clearing cancels only currently QUEUED server jobs and retains history. Spool cancellation targets an exact locally owned job; a success cannot recall paper. Reconnect never restarts Windows or the service and cannot restore revoked credentials.
|
||||
Only outbound HTTPS is required. The initial agent polls every five seconds. HTTPS validation uses Windows/.NET trust; do not disable certificate checks. Local `http://localhost` is a development exception, not a production endpoint. Proxy-specific authentication has not been qualified.
|
||||
|
||||
## Restart and uncertainty
|
||||
|
||||
@@ -48,6 +39,5 @@ There is no global transaction spanning the cloud database and a printer. `SPOOL
|
||||
|
||||
## Capacity and retention
|
||||
|
||||
Authorized QQQ administrators use **Printing connection and limits** to set document sizes, copies, bounded transfer/print concurrency, staging, bandwidth, control queues, liveness, reconnect and timeouts. Defaults are 100 MiB PDF, 20 MiB ZPL, 100 copies and one download/print lane. The configurable native submission timeout defaults to 120 seconds. Invalid policy or values beyond the client's declared ceiling stop new work; the agent does not silently clamp them.
|
||||
Documents are limited to 20 MiB and copies to 1–100. The worker serializes its jobs. The native renderer is bounded but still runs in the service process. Journal/event retention and renderer subprocess isolation are planned; monitor disk use and use this prerelease in a controlled pilot rather than assuming unbounded production capacity.
|
||||
|
||||
**Printing queue and storage limits** controls the separate server admission policy. Server document retention and local journal detail retention are distinct. The service streams into protected temporary files, verifies length/hash and submits through a bounded isolated child. Per-printer ordering remains serialized even when different printers run concurrently. See [settings and architecture](REALTIME.md) and [measured storage scope](SCALABILITY.md). Monitor disk use; retained deduplication summaries have no fixed lifetime size ceiling.
|
||||
+2
-18
@@ -1,22 +1,6 @@
|
||||
# Customer branding
|
||||
|
||||
There are two levels. A **client edition** is a separate, fully branded build and installer: its own mark, icon and logo, the client's product and company in every executable and in Windows, and its own installer and update asset. **Deployment branding** applies labels, a colour and artwork to the shared installer at install time. Editions are for clients who get their own installer; deployment branding is for customers of the shared one.
|
||||
|
||||
## Client editions
|
||||
|
||||
Add a folder under `editions/` (see [editions/README.md](../editions/README.md)) with `edition.json`, `app-icon.svg`, `app.ico` and an optional `logo.png`, then build with:
|
||||
|
||||
```powershell
|
||||
./build/Build-Installer.ps1 -ProductVersion 1.2.0 -ReleaseVersion 1.2.0 -Edition gg-forge
|
||||
```
|
||||
|
||||
The result is `artifacts/installer/<assetPrefix>-<version>-x64.msi`, for example `GgForgePrintAgent-1.2.0-x64.msi`. Installed, it shows the client's name and mark on the splash, About, window title, tray tooltip, Start menu, Programs list and service; Task Manager and file properties show the client's product, company and description; and the in-app updater follows `<assetPrefix>-v<version>-x64.msi` on the release feed. CI builds every edition's unsigned installer, and the stable release workflow signs and publishes one MSI per edition beside the generic one, all listed in the same `SHA256SUMS`. An edition installer forces its client's labels over any labels an earlier install stored.
|
||||
|
||||
An edition's descriptor can also name the server as its users know it (`serverName`, used in sign-in and status text instead of QQQ) and leave the Query mascot and License sections out of About (`aboutMascot`, `aboutLicense`); the generic build keeps all of them. Editions share application id, data paths, executable file names, the install directory, the protocol handler, the MSI upgrade identity and the signing identity, so an edition installer upgrades the generic build and other editions in place and keeps the pairing and history. Deployment branding below still applies on top of an edition.
|
||||
|
||||
## Deployment branding
|
||||
|
||||
Use the same [signed stable machine MSI](https://git.kof22.com/QRun-IO/qqq-print-agent/releases/tag/v1.0.1) for every customer. No customer-specific build is required. The deployment wrapper stages an optional machine branding file and local assets, then supplies customer labels to Windows Installer. The companion, service display name, installed-product labels and all-users Start menu shortcut use that identity.
|
||||
Use the same released machine MSI for every customer. No customer-specific build is required. The deployment wrapper stages an optional machine branding file and local assets, then supplies customer labels to Windows Installer. The companion, service display name, installed-product labels and all-users Start menu shortcut use that identity.
|
||||
|
||||
## Install with a customer name
|
||||
|
||||
@@ -37,7 +21,7 @@ Use PowerShell 7.4 or newer. First validate a downloaded MSI and configuration w
|
||||
./build/Install-Branded.ps1 -MsiPath 'C:\Deployment\QqqPrintAgent.msi' -BrandingFile './docs/branding.example.json' -WhatIf
|
||||
```
|
||||
|
||||
Run the same command **without `-WhatIf` from an elevated administrator PowerShell** to install. The script does not silently elevate or bypass UAC. Supply `-ExpectedSHA256 '<64 hexadecimal digits>'` when you have the expected MSI checksum from your approved release source. The wrapper verifies it before installation and keeps the source MSI read-locked through execution. A checksum does not substitute for publisher signing; verify the stable MSI signature as described in [Installation](INSTALLATION.md#download-and-verify). Customer branding does not change the Authenticode publisher or update feed.
|
||||
Run the same command **without `-WhatIf` from an elevated administrator PowerShell** to install. The script does not silently elevate or bypass UAC. Supply `-ExpectedSHA256 '<64 hexadecimal digits>'` when you have the expected MSI checksum from your approved release source. The wrapper verifies it before installation and keeps the source MSI read-locked through execution. A checksum does not substitute for publisher signing.
|
||||
|
||||
The wrapper launches `msiexec.exe` with `/i`, `/passive` and `/norestart`, using separate arguments. It accepts success/reboot codes 0, 1641 and 3010 and reports the result. It creates `%ProgramData%\QqqPrintAgent` with SYSTEM/Administrators permissions when absent, or rejects unsafe existing permissions. It never broadens access to existing device state. It copies validated assets under unique names, replaces `branding.json`, and restores the previous configuration if Windows Installer fails. The client/service/enrollment remain one coherent MSI installation.
|
||||
|
||||
|
||||
+13
-26
@@ -2,21 +2,17 @@
|
||||
|
||||
## Architecture
|
||||
|
||||
Current source is version `1.0.1` (a packaging fix; see CHANGELOG.md), with native printing 2.3 (wire payload v1).
|
||||
See [realtime architecture](REALTIME.md) for worker separation, policy, streaming
|
||||
and reconnect rules. The service never falls back from WSS to job/control polling.
|
||||
|
||||
| Project | Responsibility |
|
||||
| --- | --- |
|
||||
| Qqq.PrintAgent.Core | QQQ authentication, HTTP/WSS clients, policy, streaming and submission state machine |
|
||||
| Qqq.PrintAgent.Core | Wire DTOs/client, submission state machine and exposure filter |
|
||||
| Qqq.PrintAgent.Windows | Native spooler/PDF adapter, SQLite/DPAPI store and local management runtime |
|
||||
| Qqq.PrintAgent.Service | .NET Windows Service host |
|
||||
| Qqq.PrintAgent | AppKit/WinUI setup, details and tray companion |
|
||||
| Qqq.PrintAgent.Cli | Authenticated service management and explicit isolated legacy diagnostics |
|
||||
| Qqq.PrintAgent.Cli | Scriptable setup and foreground diagnostics |
|
||||
|
||||
The service owns the credential, journal and print operations. The UI is optional at runtime and sees only credential-free snapshots. Service IPC uses the `QqqPrintAgent` named pipe and accepts administrator clients. `snapshot` returns connection health, all locally discovered printers with exposure state, the latest 50 jobs and the latest 100 in-memory log entries. `set-exposure` persists a selected queue and returns a fresh snapshot. Legacy `status`, `printers` and `enroll` operations remain available.
|
||||
|
||||
The cloud API lives in [qqq-print-protocol](https://git.kof22.com/QRun-IO/qqq-print-protocol). Its inventory is the complete currently exposed printer set. The server separately owns authorization/approval. Removing local exposure filters inventory and prevents new local submission to that queue. It cannot retract a job already handed to Windows.
|
||||
The cloud API lives in [qqq-print-protocol](https://github.com/QRun-IO/qqq-print-protocol). Its inventory is the complete currently exposed printer set. The server separately owns authorization/approval. Removing local exposure filters inventory and prevents new local submission to that queue. It cannot retract a job already handed to Windows.
|
||||
|
||||
## Reproducible checks
|
||||
|
||||
@@ -30,26 +26,21 @@ This performs locked restore, Release solution build, core tests and Windows/CLI
|
||||
|
||||
## Local server and CLI
|
||||
|
||||
Use a disposable native QQQ host from the sibling qbit-printing project, using qbit-printing 1.0.0 on QQQ 4.1.0-RC.21 and advertising native printing API 2.3. Sign in through the companion's advertised QQQ authentication flow before using normal CLI commands. The service owns the session, device proof and unattended printing. A bearer-only demo is not a compatible realtime host.
|
||||
Start the sibling qbit-printing demo as described in its README. The default local API origin is `http://localhost:18081`. The demo's administrative credential is a local harness mechanism, not the production QQQ authentication design.
|
||||
|
||||
```powershell
|
||||
$agent = '.\src\Qqq.PrintAgent.Cli\bin\x64\Debug\net10.0-windows10.0.19041.0\qqq-print-agent.exe'
|
||||
& $agent service-status
|
||||
& $agent snapshot
|
||||
$data = Join-Path $env:LOCALAPPDATA 'QqqPrintAgent-Development'
|
||||
& $agent printers
|
||||
& $agent run
|
||||
# Enrollment code is read from QQQ_PRINT_ENROLLMENT_CODE or the prompt.
|
||||
& $agent enroll --server http://localhost:18081 --data-dir $data
|
||||
& $agent expose --printer '<discovered-printer-id>' --exposed true --data-dir $data
|
||||
& $agent run --data-dir $data --once
|
||||
```
|
||||
|
||||
`run` requests a connection refresh through the authenticated service; it does not start a second foreground worker. Device setup and explicit printer exposure use that same service. Submit a physical test only when authorized, after approving the selected exposed queue in QQQ.
|
||||
Enable the selected queue on the server, submit a recognizable test document, then run the worker again. Without `--once`, it polls until Ctrl+C. Use a dedicated private directory; do not share it with the installed service. The exclusive worker.lock prevents simultaneous workers on one journal.
|
||||
|
||||
Direct bearer diagnostics require explicit `--legacy-compat` and a separate private `--data-dir`; they cannot use `--service` and are never an automatic fallback. The exclusive `worker.lock` prevents simultaneous workers on one journal. Do not point a development worker at installed state.
|
||||
|
||||
## Virtual file printer (macOS/Linux)
|
||||
|
||||
`tools/virtual-agent/` holds a dependency-free Node.js agent that speaks the realtime contract and
|
||||
writes each verified job to a directory instead of a Windows queue. Use it to exercise a QQQ server
|
||||
with the printing QBit without Windows or hardware; it does not qualify this service. See
|
||||
[its README](../tools/virtual-agent/README.md).
|
||||
For installed service management use elevated `enroll --service`, `expose --service`, `service-status` or `snapshot`. The CLI `printers` command runs under the invoking account; the service snapshot is authoritative for service-visible queues.
|
||||
|
||||
## Reliability boundary
|
||||
|
||||
@@ -58,19 +49,15 @@ The worker persists receipt and SUBMITTING before invoking Windows. It records S
|
||||
## Packaging
|
||||
|
||||
```powershell
|
||||
./build/Build-Installer.ps1 -ProductVersion 1.0.1 -ReleaseVersion 1.0.1
|
||||
./build/Build-Installer.ps1 -ProductVersion 0.1.3 -ReleaseVersion 0.1.3-rc.1
|
||||
```
|
||||
|
||||
MSI ProductVersion is numeric; assembly/package informational version may contain the prerelease suffix. Service, companion and CLI are published into separate self-contained runtime directories and shipped in one machine MSI. Do not reintroduce the template's per-user Velopack updater.
|
||||
|
||||
`./build/Package-Release.ps1` (defaults `1.0.1` / `1.0.1`) is the repository entry point for the unsigned local package; the signed stable package is built by the release workflow. It runs the same packaging checks as `.github/workflows/ci.yml` (`Test-WindowsSdkInventory.ps1 -VerifyPackages`, `Test-BrandedInstaller.ps1`, `Test-PackagingInputs.ps1`, `Build-Installer.ps1`) and assembles `artifacts/release` with the versioned MSI, `Install-Branded.ps1`, `branding.example.json` and `SHA256SUMS`. It does not build or run Core.Tests.
|
||||
|
||||
`Qqq.PrintAgent.NativeCI.slnx` is `Qqq.PrintAgent.slnx` without the `Core.Tests` project, for hosts that must not build that assembly (for example `dotnet build Qqq.PrintAgent.NativeCI.slnx --configuration Release '-p:Platform=x64' -warnaserror`, then `dotnet test tests/Qqq.PrintAgent.Cli.Tests`). `Qqq.PrintAgent.slnx` and the test projects are unchanged, so `Verify.ps1` still covers Core.Tests; run those tests on a clean CI runner.
|
||||
|
||||
## Machine update integration
|
||||
|
||||
`MainWindow.Updates` wires AppKit `UpdateCoordinator`/`ContentDialogPrompter` to Windows `MsiUpdateService : IUpdateService`. The persisted startup-check preference, version/channel display, splash duration and help/credits use the shared shell. The UI serializes manual/startup checks; confirmation is required before apply.
|
||||
|
||||
`GitHubMsiReleaseClient` reads the fixed QRun-IO release feed, applies strict version/channel/minimum policy and validates bounded release assets and SHA-256. `MsiUpdateInstaller` validates protected staging, ACLs and reparse boundaries, copies the installed self-contained CLI for handoff, rechecks the MSI and uses Windows Installer for all components. The runtime's `prepare-update`/`resume-after-update` operations coordinate a bounded claim pause while preserving heartbeats. No server-supplied executable, per-user replacement package or persistent privileged updater is involved. See the [threat model](security/threat-model.md) for trust and failure boundaries.
|
||||
|
||||
Historical 0.1.3-rc.1 verification: locked restore, zero-warning Release build, **36 Core + 127 Windows/CLI tests (163 total)**. Synthetic release/download/hash/request/ACL/version/maintenance tests do not install an MSI. Installed shell and actual upgrade acceptance remain separate gates; use [session state](SESSION-STATE.md) for current verification. Completed protected update stages are retained for manual administrator review.
|
||||
Current 0.1.3-rc.1 verification: locked restore, zero-warning Release build, **36 Core + 127 Windows/CLI tests (163 total)**. Synthetic release/download/hash/request/ACL/version/maintenance tests do not install an MSI. UI tests compile only; installed shell and actual upgrade acceptance remain separate gates. Completed protected update stages are retained for manual administrator review.
|
||||
@@ -1,62 +0,0 @@
|
||||
# Printing cohort handoff for the Forge agent — 2026-11-05
|
||||
|
||||
Reusable changes were made in the printer client and the printing QBit repositories. Existing
|
||||
authentication, discovery, enrollment, inventory and printing contracts are preserved; there are
|
||||
**no breaking changes**. Nothing was installed over Forge's working client or dependencies; adoption,
|
||||
pinning and the pairing tests (browser sign-in, session resume, enrollment, server printing,
|
||||
TC22 → Echo → Z2) are yours. The previous cohort stays available for rollback.
|
||||
|
||||
## Exact versions and artifacts
|
||||
|
||||
| Component | Version | Tag / source | Artifact | SHA-256 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Protocol (contract + fixtures) | 1.1.0 | `v1.1.0` at `5005f3c9e27053b6c327bb923695012832c0fdcc` | https://git.kof22.com/QRun-IO/qqq-print-protocol/releases/tag/v1.1.0 — `qqq-print-protocol-1.1.0.tar.gz` | `541f0f3054cbfe9ce16e7dea58fad01b55a7f0e9246ade8f30df1bb826940703` |
|
||||
| Printing QBit (server) | **1.1.2**, native printing extension **2.4.0**, on QQQ **4.1.0-RC.22** from the Gitea registry (1.1.1 is the same code on RC.21 from Maven Central; 1.1.0 is superseded: do not adopt it) | `v1.1.2` at `f5639a98be9a2f15d4c61cf0955fe4ecef85824f`, push build 6435 + tag build 6475 | Maven `com.kingsrook.qbits:qbit-printing:1.1.2` from `https://git.kof22.com/api/packages/QRun-IO/maven` (repository id `qrun-io`, reader token); same bytes on https://git.kof22.com/QRun-IO/qbit-printing/releases/tag/v1.1.2 | JAR `786e6e570c5df29b01529562efb246a4f4562bb1d9fff6bea77d264e0d7536ce`, POM `7691a4e1cb7b03c7a559b0e2b92eacd92f86545b98bddafac86fc70f8602b03d` |
|
||||
| Windows print client | **1.2.1** (1.2.0 content + release-pipeline fix; tag v1.2.0 produced no installer) | `v1.2.1` at `3b9d75d18f9cc8b80f4cf6d5aae81cccf8d61243`, GitHub release run 42223525626 | Signed installers: `QqqPrintAgent-v1.2.1-x64.msi` (generic) and `GgForgePrintAgent-v1.2.1-x64.msi` (GG Forge edition), `SHA256SUMS`, on https://github.com/QRun-IO/qqq-print-agent/releases/tag/v1.2.1 and byte-identical on https://git.kof22.com/QRun-IO/qqq-print-agent/releases/tag/v1.2.1 | generic `09920872b3447f8679b404f2b5ebd7d9fe82204b8007db63d58e4287f436f2eb`, GG Forge `5ce489092c1403449174b8a35eda039cd452e8685cbfe436d99aea3e15a5d8b4`; Authenticode valid (CN=James Maes, Microsoft timestamp); GitHub provenance attestation verified |
|
||||
|
||||
Previous cohort for rollback: protocol 1.0.0, QBit 1.0.0 (extension 2.3.0), Windows 1.0.1 / 1.1.1.
|
||||
|
||||
**2026-11-06 update (QBit 1.1.1).** Forge's qualification of 1.1.0 found that the realtime upgrade fails before WELCOME behind an ingress that lowercases header names (the device id was read case-sensitively from the WebSocket context; the same defect exists in 1.0.0, which Forge ran with a local patch). 1.1.1 resolves the device once on the authorized upgrade and carries it on the connection, with a regression test that connects with lowercase header names. No contract change: the pairing matrix and everything else in this handoff is unchanged; replace the `1.0.0-forge…headers1` coordinate with the published 1.1.1 and drop the local patch.
|
||||
|
||||
**2026-11-06 update (QBit 1.1.2, Gitea-only runtime).** James's direction: every QRun artifact resolves from the QRun-IO Gitea registry, no more Maven Central. 1.1.2 is the 1.1.1 code certified on QQQ **4.1.0-RC.22** (the core version Forge already pins; it exists only in the Gitea registry) with `-Pui-demo verify`, 200 tests, 0 failures, and published by the shared `ci-workflows` pipeline. `qqq-frontend-next` 1.0.0-RC.37 is also mirrored into the registry byte-for-byte from Central. Pin `com.kingsrook.qbits:qbit-printing:1.1.2` together with core 4.1.0-RC.22 and read both from `https://git.kof22.com/api/packages/QRun-IO/maven`; third-party libraries still come through the Maven Central mirror until the registry proxies them. No contract change; pairing matrix unchanged.
|
||||
|
||||
## What changed, by contract
|
||||
|
||||
- **Printer approval over the realtime channel (extension 2.4.0, additive).** Client advertises
|
||||
`printer-approval-v1` in HELLO only when discovery shows a stable printing 2.x with minor >= 4.
|
||||
Server then sends a `PRINTERS` frame (`{ "printers": [ { "printerId", "enabled" } ] }`, the complete
|
||||
approval state of the device's exposed printers) after each accepted INVENTORY and whenever an
|
||||
administrator approves or disables one of that device's printers. Not acknowledged. A 2.3 peer on
|
||||
either side keeps the exact 1.0 wire: 1.0.x/1.1.x clients never advertise it and never receive it;
|
||||
the 1.2.1 client against QBit 1.0.0 reads the operator catalog instead (user-scoped; shows "Not
|
||||
reported" without operator permission).
|
||||
- **Remove printers / Remove device (QBit).** Archives with `removed_at`; hidden from lists, catalog,
|
||||
claims and the PRINTERS frame; a re-shared printer returns as awaiting approval; retention purges
|
||||
removed rows that no job references. QQQ 4.1 has no table-level default filter, so the raw Printers
|
||||
/ Print devices tables still show removed rows until a "Removed at is empty" saved view is added.
|
||||
- **Client sign-in nonce.** Sends `expectedNonce` under REQUIRED, OPTIONAL and the discovery capability
|
||||
`nativeSessionNonceValidation`; legacy servers unchanged (PR 11 content, already merged earlier).
|
||||
- **Client UX/ops.** Server column on the Printers page; verbose sign-in diagnostics with DEBUG level;
|
||||
log size rollover; per-server untrusted-certificate option (development only, origin-bound);
|
||||
connection dialog rework; Clear logs button in the log viewer; client editions (GG Forge build is a
|
||||
separate MSI with its own update asset; one edition per PC, shared UpgradeCode).
|
||||
|
||||
## Pairing matrix (what must hold in your tests)
|
||||
|
||||
| Server | Client | Expected |
|
||||
| --- | --- | --- |
|
||||
| QBit 1.0.0 (2.3.0) | 1.2.1 | No `printer-approval-v1` in HELLO; catalog fallback; everything else as 1.1.1 |
|
||||
| QBit 1.1.2 (2.4.0) | 1.0.1 / 1.1.1 | Four-capability HELLO at most; no PRINTERS frame; unchanged behaviour |
|
||||
| QBit 1.1.2 (2.4.0) | 1.2.1 | Five-capability HELLO; PRINTERS after inventory and on approval change; Printers page shows Approved / Awaiting approval live |
|
||||
|
||||
## Evidence
|
||||
|
||||
- Protocol: `npm run check` (79 schema definitions, 82 fixtures), lint, typecheck, quality all green on 5005f3c.
|
||||
- QBit: `mvnw -Pui-demo verify` 199 tests, 0 failures, 0 Checkstyle; main run 5473 verify + secrets + gate + post-publish green; registry files read back byte-for-byte.
|
||||
- Client: hosted GitHub CI run 42116396114 on the PR head (197 Core + 362 Windows tests, 0 failures); Gitea required checks green on both merges; release run 42223525626 (verify, security, CodeQL, sign generic + GG Forge, assemble, publish).
|
||||
|
||||
## Notes for adoption
|
||||
|
||||
- Pin all three together. The client's CI fixture pin is `ac835f8b9396b641b525669249fdb4a1e2a50c99`; the QBit's is `5005f3c9e27053b6c327bb923695012832c0fdcc` (docs PRs 29 and 12 pending).
|
||||
- Forge must approve the shared printers on the server after the first inventory from a 1.2.0 client, as before; the difference is that the client now shows that state.
|
||||
- Coordinate installation on the Forge print station yourself; the GG Forge rc.3 build on James's PC is a local test build (file version 1.2.0.3) and will update to the signed 1.2.1 from its own GG Forge asset.
|
||||
+16
-17
@@ -2,15 +2,14 @@
|
||||
|
||||
## Download and verify
|
||||
|
||||
Download the x64 MSI and `SHA256SUMS` from the same [stable Gitea release](https://git.kof22.com/QRun-IO/qqq-print-agent/releases/tag/v1.0.1). Matching assets remain on [GitHub](https://github.com/QRun-IO/qqq-print-agent/releases/tag/v1.0.1) for the installed updater. Check the file locally:
|
||||
Download the x64 MSI and `SHA256SUMS` from the same [GitHub release](https://github.com/QRun-IO/qqq-print-agent/releases). Check the file locally:
|
||||
|
||||
```powershell
|
||||
Get-FileHash -Algorithm SHA256 -LiteralPath .\QqqPrintAgent-v1.0.1-x64.msi
|
||||
Get-FileHash -Algorithm SHA256 -LiteralPath .\QqqPrintAgent-v0.1.7-rc.1-x64.msi
|
||||
Get-Content .\SHA256SUMS
|
||||
Get-AuthenticodeSignature -LiteralPath .\QqqPrintAgent-v1.0.1-x64.msi | Format-List Status, SignerCertificate, TimeStamperCertificate
|
||||
```
|
||||
|
||||
Use the filename of the release you downloaded and compare the complete hash with its `SHA256SUMS` entry. Stable **1.0.1** signs the MSI, companion, service and CLI through Azure Artifact Signing. Authenticode verification should report **Valid** with publisher **James Maes** and a timestamp. The release also provides build-provenance attestations. Checksums, publisher signatures and provenance establish different facts; see [Release signing](RELEASE-SIGNING.md). Earlier unsigned prereleases retain their historical status. Download only official assets and follow your organization's software-install policy.
|
||||
Use the filename of the release you downloaded and compare the complete hash with its `SHA256SUMS` entry. The published baseline is 0.1.7-rc.1; the audit candidate is not released yet. Checksums detect changes after publication; they do not replace publisher signing. The MSI is **unsigned**, with no Authenticode identity. The current release workflow also produces GitHub build-provenance attestations, which are verified separately from checksums and are not code signing. Older releases may lack those attestations; their presence must be checked for the exact downloaded asset. Download only from the project's release page and follow your organization's software-install policy.
|
||||
|
||||
## Install
|
||||
|
||||
@@ -21,7 +20,7 @@ Run the MSI as an administrator. Windows Installer deploys one coherent applicat
|
||||
- The `qqq-print-agent.exe` diagnostic CLI.
|
||||
- A restricted `%ProgramData%\QqqPrintAgent` directory for enrollment and the job journal.
|
||||
|
||||
There is no inbound firewall rule or local HTTP server. The client requires outbound WSS upgrades and HTTPS to the QQQ server; update checks/downloads use HTTPS to GitHub release services. Use the matching qbit-printing 1.0.0 server with native printing API 2.3. There is no job/control polling fallback. The UI requests administrator elevation because its management pipe permits only SYSTEM and local administrators.
|
||||
There is no inbound firewall rule or local HTTP server. Keep outbound HTTPS available to the QQQ server and, for update checks/downloads, GitHub release services. The UI requests administrator elevation because its management pipe permits only SYSTEM and local administrators.
|
||||
|
||||
## Service recovery
|
||||
|
||||
@@ -49,35 +48,35 @@ Full uninstall removes only tasks whose name, current-user SID, interactive prin
|
||||
|
||||
## Isolated native printer operations
|
||||
|
||||
Discovery, submission and cancellation run in a short-lived child of the service or explicit diagnostic CLI. Control requests use anonymous standard-input/output pipes. Realtime documents stream to protected owned staging files; their content is not placed in command arguments or logs. Discovery and cancellation have bounded helper deadlines. Realtime printing uses the server's `nativeSubmissionTimeoutMillis`, default 120 seconds, rather than a fixed submission deadline. A timed-out child is terminated, with bounded cleanup, and also watches its parent. The child still runs with service privileges; isolation limits a blocked driver, not its authority.
|
||||
Discovery, submission and cancellation run in a short-lived child of the service or foreground CLI. The child receives its request through anonymous standard-input/output pipes; document bytes are not written to command arguments, activity logs or temporary files. Discovery and cancellation are limited to 20 seconds, and printing to 120 seconds. A timed-out child is terminated, with up to five seconds allowed for cleanup. A child also watches its parent and exits when the connector disappears.
|
||||
|
||||
This bounds a blocked printer driver without stopping cloud connectivity permanently. It cannot retract bytes already accepted by a printer: timeout, crash or cancellation after submission begins is an uncertain outcome and requires inspection before reprinting. Existing spooler receipt cancellation verifies the exact QQQ document identity before requesting cancellation; it does not prove that no paper or label has already emerged. Synthetic subprocess tests use a fake backend and never access a printer.
|
||||
|
||||
## Prepare printers
|
||||
|
||||
Install each printer and its appropriate vendor driver in Windows. Print a normal Windows test page, then discover the queues through QQQ Print Agent. The installed service must have access; a queue mapped only under a user's profile is insufficient. Use machine-installed USB/TCP/IP queues where possible. Network share authentication may require a deliberately configured service identity; check access under that identity before using it for unattended printing.
|
||||
Install each printer and its appropriate vendor driver in Windows. Print a normal Windows test page, then discover the queues through QQQ Print Agent. The installed service must have access; a queue mapped only under a user's profile is insufficient. Use machine-installed USB/TCP/IP queues where possible. Network share authentication may require a deliberately configured service identity; that variant has not been qualified for this prerelease.
|
||||
|
||||
Set the queue's machine default paper/tray/orientation for PDF printing. Jobs can use an advertised media profile or a complete explicit PDF width/height pair; job-specific choices do not change the shared queue. See [Printer media](PRINTER-MEDIA.md). For ZPL, configure compatible Zebra/ZDesigner drivers and generate ZPL matching the printer's DPI and label stock. Ribbonless printers require the appropriate direct-thermal mode.
|
||||
Set the queue's default paper/tray/orientation for PDF printing. The initial API supports actual size or fit and copies, but rejects custom media dimensions. For ZPL, configure compatible Zebra/ZDesigner drivers and generate ZPL matching the printer's DPI and label stock.
|
||||
|
||||
## Sign in and pair
|
||||
## Enroll
|
||||
|
||||
Use qbit-printing 1.0.0 on QQQ 4.1.0-RC.21 or a compatible newer server; the released combination advertises native printing API 2.3. In the companion's connection settings, enter its origin, discover the advertised sign-in options and sign in through the configured QQQ authentication. See [QQQ sign-in](QQQ-SIGN-IN.md) for browser-provider requirements and recovery.
|
||||
Create a single-use enrollment code in QQQ. Open the companion, enter the QQQ server origin and code, then connect. Enrollment runs in the service so its credential is protected under the service identity. The desktop stores no device token.
|
||||
|
||||
For an existing unbound installation, choose **Associate the existing pairing with my account**; preserve its device record and history. For a new installation, complete sign-in and enter a single-use enrollment code created in QQQ. Enrollment runs in the service, protecting its device proof and QQQ session under the service identity. The desktop does not retain the password or device token. **Set up a new pairing** is an explicit replacement flow, not routine upgrade migration.
|
||||
Do not enroll the development CLI under your user and copy its protected file into ProgramData: DPAPI credentials are bound to the account that created them. Use the companion or an elevated CLI `enroll --service` command.
|
||||
|
||||
Normal CLI setup, printer exposure and connection commands use the authenticated installed service. Sign in through the companion first; `run` requests a connection refresh. Explicit `--legacy-compat` diagnostics require a separate `--data-dir` and cannot use `--service`. Do not copy a user-protected DPAPI credential into ProgramData: credentials are bound to the account that created them. The service owns unattended discovery and printing.
|
||||
Foreground CLI commands use `%LocalAppData%\QqqPrintAgent` by default. An explicit `--data-dir` may select a separate development directory; directly using the service ProgramData directory is rejected. Use `--service` for installed-service enrollment/exposure. Foreground enrollment and exposure changes take the same exclusive worker lock as `run`, so stop that foreground worker before changing its connection or exposure. Both CLI and service dispatch native discovery/printing through a bounded child process.
|
||||
|
||||
## Updates
|
||||
|
||||
In the MSI-installed companion, open Settings and select **Check for updates**. The **Check for updates on startup** preference enables a quiet check after startup; it does not authorize installation. AppKit's `UpdateCoordinator` and native prompts handle offers and confirmation. Development/portable copies cannot apply machine updates. The elevated companion and apply helper require local administrator rights; there is no persistent privileged update daemon or UAC bypass.
|
||||
|
||||
The feed is fixed to [QRun-IO/qqq-print-agent releases](https://github.com/QRun-IO/qqq-print-agent/releases), independently of customer branding or the QQQ server. Stable builds accept newer stable versions; prerelease builds may accept newer RC or stable versions. Offers below core version 0.1.3 are rejected. Downloads require the expected versioned MSI and same-release `SHA256SUMS`. SHA-256 checks establish consistency with that release, not independent publisher identity. Stable 1.0.1 is signed; earlier unsigned prereleases remain distinguishable by their exact release.
|
||||
The feed is fixed to [QRun-IO/qqq-print-agent releases](https://github.com/QRun-IO/qqq-print-agent/releases), independently of customer branding or the QQQ server. Stable builds accept newer stable versions; prerelease builds may accept newer RC or stable versions. Offers below core version 0.1.3 are rejected. Downloads require the expected versioned MSI and same-release `SHA256SUMS`. SHA-256 checks establish consistency with that release, not independent publisher identity or signing; the prerelease remains unsigned.
|
||||
|
||||
After confirmation, the adapter downloads into a protected unique folder under `%ProgramData%\QqqPrintAgent\updates`, verifies size/hash and prepares a copied CLI helper. The service pauses new claims and waits for active native submissions; connection/control traffic remains separate. The helper waits for the companion to exit, rechecks the package, then runs one MSI for service, companion and CLI. It preserves enrollment and journal evidence. Windows Installer is not forcibly terminated. A failed or abandoned handoff does not leave claims paused permanently.
|
||||
After confirmation, the adapter downloads into a protected unique folder under `%ProgramData%\QqqPrintAgent\updates`, verifies size/hash and prepares a copied CLI helper. The service finishes its current poll/print operation before pausing new claims; heartbeats continue. The helper waits for the companion to exit, rechecks the package, then runs one MSI for service, companion and CLI. It preserves enrollment and journal evidence. Windows Installer is not forcibly terminated. A failed or abandoned handoff does not leave claims paused permanently.
|
||||
|
||||
The helper records a dated result in `updates\last-result.json`, retains a private installation log and attempts to reopen the companion. Settings displays the last result. Exit 3010 means a Windows restart is required, not that the new app is fully ready. On failure, inspect Settings/Logs and the installed version before retrying. Completed update folders, helper copies and install logs are retained for administrator review; there is no automatic cleanup policy for completed stages. Remove an old stage only after confirming its installer/helper has exited and its evidence is no longer needed; never remove enrollment or journal files.
|
||||
|
||||
The signed 1.0.1 MSI is installed locally; the November 3, 2026 check found matching companion, service and CLI versions with the service running. The earlier in-app update from 0.3.1 to 0.3.2-rc.1 completed and reopened Connected, as confirmed by the operator. Those are distinct observations; see [acceptance evidence](ACCEPTANCE.md) and [release readiness](RELEASE-READINESS.md) for their exact scope. A nonworking older companion can be repaired using the official MSI directly.
|
||||
The installed 0.1.7 baseline passed its 16 native UI checks and confirmed laser PDF, Zebra ZPL and Zebra PDF output. The audit candidate's source gate passes 249 tests with zero warnings/errors, but its installation is still pending. These checks do not qualify a complete in-app upgrade, canceled elevation or restart-required recovery. See [current acceptance evidence](ACCEPTANCE.md) and [audit status](SESSION-STATE.md) for the exact versions and remaining checks. A nonworking older companion can be repaired using the reviewed MSI directly.
|
||||
|
||||
## Upgrade and remove
|
||||
|
||||
@@ -85,8 +84,8 @@ Install a newer MSI as administrator. The installer stops and replaces the servi
|
||||
|
||||
Use **Settings → Apps → Installed apps → QQQ Print Agent → Uninstall** to remove application files and the service. Enrollment and journal data are retained to support recovery. After revoking/decommissioning the device in QQQ and resolving all outstanding jobs, an administrator may deliberately remove the retained data. Never delete a live journal as a troubleshooting shortcut: it is evidence used to avoid duplicate printing.
|
||||
|
||||
Local MSI upgrades, updater handoff and installed UI checks are recorded by version in the acceptance evidence. An MSI exit code alone does not establish reboot recovery or compatibility with every printer/driver combination.
|
||||
Local MSI upgrades and installed UI checks are recorded by version in the acceptance evidence. Reboot/recovery, a complete in-app upgrade and broader driver combinations still require qualification; an MSI exit code alone does not establish those results.
|
||||
|
||||
## Select exposed printers
|
||||
|
||||
New installations share no queues. Open the companion's Printers page and enable **Shared** for each intended printer, then approve/enable it in QQQ. Only the selected set is sent to the cloud; all discovered queues remain visible locally for setup. A missing formerly exposed queue is shown as offline.
|
||||
New installations share no queues. Open the companion's Printers tab and enable **Expose to QQQ** for each intended printer, then approve/enable it in QQQ. Only the selected set is sent to the cloud; all discovered queues remain visible locally for setup. A missing formerly exposed queue is shown as offline.
|
||||
@@ -1,43 +0,0 @@
|
||||
# Printer approval as seen by the agent
|
||||
|
||||
Sharing a printer is a local choice; approving it is the server's. The agent must show both for the
|
||||
server it is connected to, so a printer shared before a server change is never mistaken for one the
|
||||
new server approved.
|
||||
|
||||
## Printing extension 2.4: the server pushes approval (client 1.2.0, QBit 1.1.0, protocol 1.1.0)
|
||||
|
||||
When discovery advertises a stable printing `2.4.0` or newer extension, the client adds
|
||||
`printer-approval-v1` to its HELLO capabilities. The server then sends a `PRINTERS` frame
|
||||
(`{ "printers": [ { "printerId", "enabled" } ] }`, the complete approval state of every printer
|
||||
in the device's latest accepted inventory) after each accepted INVENTORY and whenever an
|
||||
administrator approves or disables one of this device's printers. The frame is authoritative:
|
||||
enabled printers are approved, a shared printer listed as disabled or not listed yet is awaiting
|
||||
approval, and the operator catalog is not read on such a server. The reading is reset with the
|
||||
connection like every other negotiated state. The contract is in the protocol repository
|
||||
(`docs/REALTIME.md`, `RealtimePrinters` in the schema, `fixtures/realtime-printers.message.json`).
|
||||
|
||||
## Printing extension 2.3: the client reads the operator catalog
|
||||
|
||||
- The inventory snapshot (`INVENTORY` over the realtime channel, `PUT /device/printers` otherwise) is
|
||||
resent on every new connection, so a server that has never seen this computer's printers receives
|
||||
them as soon as the agent connects. New printers are disabled on the server until approved.
|
||||
- The device routes never report approval, so after each accepted inventory, and about once a
|
||||
minute while connected, the service reads the operator printer catalog (`GET /operator/printers`,
|
||||
printing extension 2.3) and keeps the entries whose `deviceId` is this device. That catalog lists
|
||||
only approved, exposed destinations the signed-in user may use, so an entry is the server's
|
||||
confirmation of approval. The reading is kept in memory and reset with the connection.
|
||||
- Each printer in the status snapshot carries a `serverState`: `APPROVED`, `AWAITING_APPROVAL`,
|
||||
`NOT_SHARED`, `NOT_REPORTED` (the catalog could not be read; the reason is in `printerSync.detail`
|
||||
and the activity log) or `NOT_CHECKED` (no server asked yet). The Printers page shows it in the
|
||||
Server column, the summary line and the expanded details.
|
||||
|
||||
## Why both paths exist
|
||||
|
||||
The catalog is user-scoped. On a 2.3 server, a signed-in user who is not permitted to read it leaves
|
||||
every shared printer at `NOT_REPORTED` with the reason in the tooltip and the activity log. The 2.4
|
||||
PRINTERS frame is device-scoped and pushed on change, so it needs no operator permission and
|
||||
updates the Printers page the moment an approval changes. Pair the 1.2.0 client with QBit 1.1.0
|
||||
(extension 2.4.0) for that behaviour; against QBit 1.0.0 (2.3.0) the client stays on the catalog
|
||||
and the wire is unchanged. The compatibility matrix and the negotiation rule (`printer-approval-v1`
|
||||
minimum 2.4.0, capabilities re-evaluated on every socket) are in the protocol repository's
|
||||
`docs/VERSIONS.md`.
|
||||
@@ -1,91 +0,0 @@
|
||||
# Windows queue-default media profiles
|
||||
|
||||
Client 1.0.1 advertises `printer-media-v1` only when standard discovery
|
||||
reports a stable printing extension version of at least 2.3.0 within major two.
|
||||
Printing 2.0, 2.1 and 2.2 (rendering, no media negotiation) servers retain the original three realtime capabilities and
|
||||
legacy unselected jobs. Each WebSocket establishment refreshes standard discovery
|
||||
once under the authenticated session gate, then uses that refreshed snapshot
|
||||
for HELLO. This handles same-session server upgrades and downgrades without an
|
||||
HTTP polling schedule. An unverified test or
|
||||
custom transport does not claim media support.
|
||||
|
||||
The client includes optional `mediaProfiles` in exposed-printer inventory. It reports at most one profile per
|
||||
queue: the machine-wide Windows driver default. It does not enumerate stock that
|
||||
an operator might have available, infer dimensions from document pages, or claim
|
||||
that the configured stock is physically loaded.
|
||||
|
||||
Discovery reads `GetPrinter` level 8, rather than the current user's level 9
|
||||
preferences. Custom paper dimensions come from both valid DEVMODE width/length
|
||||
fields, converted from tenths of a millimeter to integer microns. Otherwise, a
|
||||
single matching paper ID in the driver's `DeviceCapabilities` paper/size arrays
|
||||
is required. Landscape defaults swap the effective page axes. Positive explicit
|
||||
DEVMODE resolutions are retained; symbolic quality values require resolution
|
||||
from a driver DC created with that exact machine DEVMODE. Unknown, incomplete,
|
||||
ambiguous or out-of-contract values produce no profile, without guessing.
|
||||
|
||||
Each profile has a stable opaque queue/default ID, a lowercase SHA-256 revision,
|
||||
a display name, width/height in microns, horizontal/vertical DPI,
|
||||
`source: WINDOWS_QUEUE_DEFAULT` and `applyMode: DRIVER_DEFAULT`. The revision
|
||||
includes driver identity, resolved dimensions/resolution, and the complete
|
||||
returned public/private DEVMODE bytes. This is deliberately conservative: even a
|
||||
driver-private setting change invalidates an old selection. Drivers returning
|
||||
volatile private bytes may require reselection; the client does not guess which
|
||||
vendor fields can be ignored. The fingerprint is not a credential.
|
||||
|
||||
Consumers submit `options.mediaProfile: {id, revision}` exactly as advertised.
|
||||
It cannot be combined with `paperWidthMm` or `paperHeightMm`. Those two values
|
||||
(a complete pair, PDF only) request explicit actual-size job paper instead: the
|
||||
agent edits a copy of the queue's machine defaults (user paper size, tenths of a
|
||||
millimeter, form name ignored, one copy, 100 percent) and refuses the job before
|
||||
StartDoc unless the device context reports that physical size and resolution. The
|
||||
queue default is never changed. The worker checks
|
||||
the current selection after download and before its submission state. The
|
||||
native helper checks again immediately before opening a spool document. A known
|
||||
media refusal is propagated across the helper boundary and recorded as FAILED
|
||||
with no document submitted; arbitrary native failures and timeouts retain their
|
||||
existing uncertain-outcome handling and are not retried automatically.
|
||||
|
||||
For selected PDF jobs, the captured machine DEVMODE remains the selection
|
||||
fingerprint. A separate job-only copy requests one driver copy and 100% driver
|
||||
scale, only for fields supported by the captured defaults, through
|
||||
`DocumentProperties(DM_IN_BUFFER | DM_OUT_BUFFER)`. Unsupported fields remain
|
||||
absent; drivers without native scale support use the software renderer's scale.
|
||||
This allows
|
||||
the driver to reconcile its private settings without prompting or changing
|
||||
queue defaults. Software remains responsible for requested copies and
|
||||
ACTUAL_SIZE/FIT rendering. The normalized result must confirm these overrides
|
||||
and preserve the original support flags and selected geometry/DPI; otherwise
|
||||
submission is refused. A previously supported override cannot silently disappear.
|
||||
`CreateDC` receives those normalized bytes, never a null/current-user default.
|
||||
Before `StartDoc`, the effective DC must also report matching physical page
|
||||
dimensions and exact horizontal/vertical DPI. Dimension tolerance is one device
|
||||
pixel plus 50 microns (half the DEVMODE 0.1 mm form unit), including landscape
|
||||
axes. Unknown or substituted dimensions/DPI are refused before spooling.
|
||||
RAW ZPL has no DEVMODE application mechanism: the helper rechecks the current
|
||||
profile immediately before `StartDocPrinter`, but cannot lock loaded stock or
|
||||
prevent a physical/device-setting change afterward. `DRIVER_DEFAULT` never
|
||||
changes queue settings, calibrates hardware or loads stock. Such changes require
|
||||
operator verification and fresh discovery. Legacy jobs without a media selection
|
||||
retain their existing path.
|
||||
|
||||
The candidate's actual read-only probe reported the configured label default as
|
||||
101,600 × 152,400 microns at 300 × 300 DPI, with an identical fingerprint across
|
||||
three separate helper launches. Synthetic tests also cover 101,600 × 25,400 and
|
||||
101,600 × 50,800 microns; these are not advertised as current configuration.
|
||||
Physical queue names, driver selectors and inventory evidence remain private.
|
||||
No print, installation, queue change or service operation was performed for this
|
||||
feature's discovery qualification. End-to-end server acceptance and physical
|
||||
printing of a profile-selected job remain separate gates.
|
||||
|
||||
A subsequent read-only probe of the compiled corrected adapter successfully
|
||||
normalized the configured label driver's supported copy field while retaining
|
||||
its absent native scale field. The resulting DC reported 1,200 × 1,800 physical
|
||||
pixels at 300 × 300 DPI. It invoked no StartDoc and changed no queue defaults.
|
||||
All 24 focused adapter regression cases pass; this does not resolve the separate
|
||||
Core test-assembly quarantine or qualify a physical profile-selected print.
|
||||
|
||||
Native references: [machine-wide PRINTER_INFO_8 defaults](https://learn.microsoft.com/en-us/windows/win32/printdocs/printer-info-8),
|
||||
[DEVMODE dimensions and resolution](https://learn.microsoft.com/en-us/windows/win32/api/wingdi/ns-wingdi-devmodew),
|
||||
and [driver paper capabilities](https://learn.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-devicecapabilitiesw).
|
||||
Job-only driver normalization follows [DocumentProperties](https://learn.microsoft.com/en-us/windows/win32/printdocs/documentproperties);
|
||||
effective page checks use [GetDeviceCaps](https://learn.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-getdevicecaps).
|
||||
@@ -1,29 +0,0 @@
|
||||
# QQQ sign-in
|
||||
|
||||
QQQ Print Agent **1.0.1** uses standard QQQ authentication. The matching released server is qbit-printing **1.0.0** on QQQ **4.1.0-RC.21**, advertising native printing API **2.3**. Realtime dispatch requires a compatible 2.x printing API and an authenticated WebSocket; an older API login never enables job polling. Product, native API and wire payload versions are separate. See [Realtime architecture](REALTIME.md).
|
||||
|
||||
Open **Settings → Sign in / Connection settings**, enter the QQQ server origin and choose **Discover sign-in options**. Discovery must advertise a compatible QQQ UI API and the printing extension before credentials are sent. Table-based authentication presents username/password fields; configured external authentication presents a browser button only for an explicitly advertised native session grant. Passwords remain in the companion and are sent only to the selected QQQ server, never stored or sent to the service.
|
||||
|
||||
The service receives the opaque QQQ session through its existing authenticated administrator pipe. It validates and resumes that session, verifies the authoritative user/tenant/device binding, and protects the session with service-identity DPAPI. Provider access and refresh tokens remain on the QQQ server. Normal printing uses `/qqq/v1/qbit/printing` with the current user session; the device ID/token are secondary possession proof, not independent user authority. Session resume runs periodically while printing continues. Expired or denied authorization stops new traffic until sign-in is restored, preserving receipts and pairing.
|
||||
|
||||
Older pairings without a bound QQQ user require sign-in and association. Routine upgrades preserve a valid saved session and pairing. To associate an existing unbound pairing, explicitly select **Associate the existing pairing with my account**. A new pairing still requires an enrollment code after sign-in. Sign-out preserves the device credential, printer choices and print journal, while removing the locally stored QQQ session. It does not recall pages already sent to a printer.
|
||||
|
||||
The installed browser callback is exactly `io.qrun.qqq-print-agent:/oauth/callback`. The host must advertise and approve this redirect for its configured QQQ OAuth2 session client; the separate public bearer client is not substituted for the server-managed session exchange. MSI registers the stable scheme independently of display branding and removes its owned registration on uninstall. The browser launches the quoted installed CLI callback helper, which forwards only to an active companion attempt in the same Windows user/session, after checking the companion executable. The companion validates the single-use state and PKCE exchange using the standard QQQ grant. No callback starts a new sign-in attempt. No provider registration, registry changes or installed browser sign-in are performed by source tests.
|
||||
|
||||
**Shared server with the Android scanner.** One QQQ host and one OAuth2 provider/`clientId` can serve both clients. The native grant's `redirectUris` must contain both exact callbacks, `io.qrun.qqq-print-agent:/oauth/callback` (print agent) and `io.qrun.mobile.scanner.oauth://callback/oauth2redirect` (scanner), and the provider must allow both exactly (no wildcards). The host must also advertise the `api` and `android` client channels and both the `printing` and `mobile-scanners` extensions. Nonce handling is negotiated per server: when the grant descriptor has `nonceValidation: REQUIRED` (which the scanner demands) or `OPTIONAL`, or when discovery advertises the `nativeSessionNonceValidation` capability, the agent sends that attempt's own authorization nonce as `expectedNonce` in the `manageSession` exchange. When neither is present (older servers) the exchange body is unchanged. Any other non-empty policy value is refused as a server configuration problem before a browser opens. The nonce is never taken from the callback, regenerated or logged. Human permissions (`printing_admin` versus the scanner's `mobile.*`) and device credentials stay separate. Validation against a real shared Authentik host is pending; this is not released.
|
||||
|
||||
Normal CLI `printers`, `enroll`, `expose`, `run` and `sign-out` commands use the installed authenticated service. `run` requests a connection refresh; the service owns unattended printing. Direct bearer-based foreground diagnostics require explicit `--legacy-compat` and a separate user data directory; they cannot use `--service`. They are a compatibility diagnostic, not the app's sign-in or fallback path.
|
||||
|
||||
The server and its identity provider govern session lifetime, renewal and current permissions. Unattended service operation does not promise an indefinite authorization lifetime: expiration, revocation or a policy change can require a new sign-in. Configure the advertised native session grant and approved callback for each deployment.
|
||||
|
||||
## Recovering unreadable local credentials
|
||||
|
||||
Explicit sign-in can replace unreadable saved QQQ session data only after fresh server authentication and, when device proof survives, authoritative device binding. Rejected binding leaves the unreadable file untouched. Successful recovery preserves its ciphertext in a uniquely named `qqq-session.recovery-*.dpapi` file in the protected data directory.
|
||||
|
||||
If device proof itself is unreadable, sign-in does not enable printing or reconstruct that proof. Explicit enrollment is required; it preserves the old ciphertext as `connection.recovery-*.dpapi`, printer choices and the old connection's journal without attaching those receipts to the new device. Read-only status remains available. Explicit sign-out can quarantine unreadable session data locally, but cannot revoke an unavailable server session; revoke that previous session in QQQ. Automatic connection recovery does not perform this explicit credential replacement.
|
||||
|
||||
## Replace a revoked or expired pairing
|
||||
|
||||
In Connection settings, choose **Set up a new pairing** before signing in. This explicit choice authenticates an unbound QQQ session without presenting the old device proof. Printing stays blocked while awaiting a new enrollment code, including after a service restart when the retained old proof is unreadable or belongs to another server. The previous device configuration, journal and printer choices remain intact until the new enrollment succeeds; rejected enrollment leaves them unchanged. The replacement gets its own journal scope and never replays the old device's jobs.
|
||||
|
||||
**Reuse the saved pairing** remains the default and verifies its device proof. **Associate the existing pairing with my account** explicitly binds an unbound legacy device to the signed-in user; it does not bypass revocation. Neither choice silently falls back to replacement enrollment.
|
||||
@@ -1,111 +0,0 @@
|
||||
# Realtime architecture and operation
|
||||
|
||||
The realtime transport was introduced in release candidate [0.3.0-rc.1](https://github.com/QRun-IO/qqq-print-agent/releases/tag/v0.3.0-rc.1) as native printing 2.0, and the published `0.2.0-rc.1`
|
||||
polling transport and its acceptance evidence remain historical. The released 1.0.1 client speaks native printing 2.3 with
|
||||
wire payload v1 and the same realtime model; media negotiation is offered only to a stable 2.3+ server. The authoritative
|
||||
[contract at the consumer pin](https://git.kof22.com/QRun-IO/qqq-print-protocol/src/commit/42c0d249f81395f00408ec0f92638dcbbf5deb03/docs/REALTIME.md)
|
||||
(commit `42c0d249f81395f00408ec0f92638dcbbf5deb03`, [Gitea PR 2](https://git.kof22.com/QRun-IO/qqq-print-protocol/pulls/2))
|
||||
defines exact fields, bounds and required cross-runtime tests. The earlier 0.3.0 pin was `f3cbc02e9b0fb4fdfefaa59d976c04df747cc589`, kept as history.
|
||||
|
||||
The 2.0 transport origin: native printing became version 2.0 because claiming then required a synchronized
|
||||
authenticated WebSocket; clients of native printing API 1.0 could claim using HTTP alone.
|
||||
This is a breaking behavioral change even though the route and domain payloads
|
||||
are retained. Product version 1.0.1, framework `/qqq/v1`, wire payload v1 and the
|
||||
`qqq-printing.v1` subprotocol have separate version meanings.
|
||||
|
||||
## Connection and work
|
||||
|
||||
The service discovers printing extension `>=2.0.0 <3.0.0`, resumes the standard
|
||||
QQQ user session and opens `/qqq/v1/qbit/printing/device/realtime` with subprotocol
|
||||
`qqq-printing.v1`. The session cookie is primary authority; device headers are
|
||||
secondary bound-device proof. Current user, tenant and record permissions still
|
||||
apply. No credentials are placed in URLs or messages. WSS and HTTPS share the
|
||||
configured origin; redirects cannot select another document host. Plain WS/HTTP
|
||||
is restricted to explicit loopback development.
|
||||
|
||||
The service owns separate connection, receive, send, synchronization, command
|
||||
and job workers. Settings, desired state, commands, inventory, job events and
|
||||
receipts use small bounded WebSocket messages. A job notification wakes a finite
|
||||
HTTPS claim drain. It stops when the queue is empty or capacity is occupied and
|
||||
resumes on a committed notification or released capacity. There is no periodic
|
||||
HTTP job/control/receipt fetch and no polling fallback. WebSocket liveness and
|
||||
normal QQQ session renewal do not query the job queue.
|
||||
|
||||
Documents stream over separate authenticated HTTPS requests into owned files in
|
||||
the protected service staging directory. Length and SHA-256 are checked while
|
||||
streaming; only a complete verified file can reach the native printer worker.
|
||||
The control reader does not wait for the document body or the printer driver.
|
||||
Download/print concurrency and aggregate staging/bandwidth are bounded; jobs
|
||||
for one printer retain their submission order. Native printing runs in an
|
||||
isolated child with a configurable deadline, retaining uncertain outcomes.
|
||||
|
||||
## Administrator settings
|
||||
|
||||
In QQQ, authorized administrators use **Printing connection and limits** for
|
||||
document, transfer, connection and control limits. **Printing queue and storage
|
||||
limits** manages the existing tenant/device admission policy; document retention
|
||||
is a separate server policy. The companion does not override these settings.
|
||||
|
||||
| Setting group | Initial defaults |
|
||||
| --- | --- |
|
||||
| Documents | PDF 100 MiB; ZPL 20 MiB; up to 100 copies |
|
||||
| Execution | One download and one print lane; configurable from 1 to 16, with per-printer ordering |
|
||||
| Staging and bandwidth | 512 MiB aggregate staged content; bandwidth 0 means unlimited |
|
||||
| Control messages | 1 MiB per complete message; 64 queued messages and 4 MiB queued bytes |
|
||||
| HTTPS requests/transfers | Request and connect 30 seconds; idle 30 seconds; total download 10 minutes |
|
||||
| Native submission | 120 seconds; configurable from 1 second to 24 hours |
|
||||
| Connection | Handshake 30 seconds; heartbeat 20 seconds; liveness timeout 60 seconds |
|
||||
| Reconnect and ACK | 1–30 seconds backoff, 20% jitter within those bounds; ACK timeout 15 seconds |
|
||||
|
||||
All 23 settings, including the server-generated revision, are sent in a complete
|
||||
snapshot. The client advertises its actual ceilings, rejects missing or invalid
|
||||
settings and refuses incompatible policy rather than silently reducing it.
|
||||
Changes are pushed and durably applied before new claims. Admitted transfers
|
||||
retain a consistent policy snapshot and their staging reservations. Host
|
||||
admission/retention and intrinsic OS, renderer and IPC ceilings have separate
|
||||
scopes; a transport limit is not a promise of sustained printer throughput.
|
||||
|
||||
## Queue health and operator actions
|
||||
|
||||
Use the companion footer, Jobs page and QQQ device/job/command records together.
|
||||
An active connection does not establish printer hardware readiness. The Jobs
|
||||
page merges local history with at most 50 server-queued observations; its count
|
||||
is not a complete large cloud-queue count. Offline previews remain observations,
|
||||
not a fresh authoritative queue. Selected job rows expand recent history; the
|
||||
full details view retains the bounded longer history.
|
||||
|
||||
- **Paused:** no new claims; previously admitted work and receipts retain their
|
||||
identities. Resume is separate from reconnect.
|
||||
- **Disconnected by administrator:** the control channel stays available for
|
||||
reconnect and in-flight receipts; ordinary inventory and new claims are held.
|
||||
- **Authorization required:** restore the QQQ session or authorized pairing;
|
||||
repeated reconnect does not repair withdrawn permissions or revocation.
|
||||
- **Queued:** inspect pause/connection state, approval/exposure, current settings,
|
||||
available capacity and server admission information before resubmitting.
|
||||
- **SPOOLED / OUTCOME_UNKNOWN:** inspect Windows and actual output. Neither an
|
||||
empty queue nor a transport reconnect authorizes printing the same job again.
|
||||
|
||||
Clearing a device's server queue cancels only currently QUEUED jobs and retains
|
||||
history. Remote spool cancellation targets one owned local job; success reports
|
||||
Windows accepting the cancellation request, not recalling paper. No remote
|
||||
command restarts Windows, a service or a printer.
|
||||
|
||||
## Reconnect and shutdown
|
||||
|
||||
The journal persists exact events and command receipts before transmission.
|
||||
After reconnect, the service applies current settings/state, waits for their
|
||||
acknowledgment and reconciles assigned jobs and its outbox. Lost acknowledgments
|
||||
replay the original IDs and result; they do not repeat native cancellation or
|
||||
submission. A new socket generation replaces the old one without allowing late
|
||||
callbacks to acknowledge the replacement's work.
|
||||
|
||||
Restart, update preparation and account changes retain journal evidence.
|
||||
Never delete staging/journal/credential files to force a retry. A native timeout
|
||||
or interruption after submission begins can mean output was accepted; preserve
|
||||
OUTCOME_UNKNOWN and require operator review. See [administrator operations](ADMINISTRATION.md).
|
||||
|
||||
Source tests and a published contract are not installed acceptance. Required
|
||||
consumer checks include controls during a stalled large HTTPS transfer, real
|
||||
bounded concurrent lanes, lost-ACK replay, offline work reconciliation and
|
||||
authorization withdrawal. Installed UI, provider renewal, proxy behavior and
|
||||
physical output remain separately qualified.
|
||||
@@ -1,75 +0,0 @@
|
||||
# Release readiness — signed 1.0 closeout
|
||||
|
||||
Updated 2026-11-04. The requested product release and local installation are complete. The dated records below distinguish the stable release from earlier candidate evidence; they are not a claim that every printer or deployment has been qualified.
|
||||
|
||||
## Current release
|
||||
|
||||
- **Windows:** signed [1.0.1 on Gitea](https://git.kof22.com/QRun-IO/qqq-print-agent/releases/tag/v1.0.1) and matching [GitHub updater assets](https://github.com/QRun-IO/qqq-print-agent/releases/tag/v1.0.1), from source `5bf00f3291923f7afb34c6cce61276e69649689b`.
|
||||
- **Release gate:** [run 41532214447](https://github.com/QRun-IO/qqq-print-agent/actions/runs/41532214447) passed the build/test/package, security, CodeQL, script, Azure OIDC signing and publication gates. Published checksums, signatures and provenance were verified. See [release signing](RELEASE-SIGNING.md).
|
||||
- **Installed:** the November 3 check recorded MSI exit 0, app/service/CLI product version `1.0.1+5bf00f3291923f7afb34c6cce61276e69649689b`, file version `1.0.1.65535`, and service **Running**. No new runtime check is implied by this documentation update.
|
||||
- **Server and contract:** [qbit-printing 1.0.0](https://git.kof22.com/QRun-IO/qbit-printing/releases/tag/v1.0.0), [protocol 1.0.0](https://git.kof22.com/QRun-IO/qqq-print-protocol/releases/tag/v1.0.0) and QQQ **4.1.0-RC.21** are released. Native printing API **2.3**, payload **v1** and WebSocket subprotocol `qqq-printing.v1` retain their own version meanings.
|
||||
- **Physical scope:** Letter and 4 × 6 output were accepted earlier; the operator confirmed 4 × 1 on RC3 with the same relevant print path. Physical 4 × 2 was deferred and is not a release blocker. Dated evidence remains in [Acceptance](ACCEPTANCE.md).
|
||||
- **Documentation:** current install, sign-in, settings, media, logs, branding and release instructions reflect the stable release. Ordinary source changes use Gitea; the authorized GitHub signing and updater bridge remains in place.
|
||||
|
||||
No product implementation, release publication or installation task remains in this closeout. Shared CI-platform migration is separate from the shipped product. Historical unchecked items below do not reopen cancelled work or authorize physical tests.
|
||||
|
||||
## Historical scope decision — 2026-11-02
|
||||
|
||||
The post-print native UI layout exception (WinUI `LayoutCycleException` after a print, recovered by the existing mitigation) was removed from the 1.0 blocker list by the user on 2026-11-02 and is accepted as a known limitation. It is **not fixed**, and the history below is preserved unchanged. It is not carried as another mandatory qualification.
|
||||
|
||||
## Historical cancelled work, not active
|
||||
|
||||
Repeat Auth/S3 qualification, the print-latency investigation, and the MSI comparison/install-free upgrade analysis were cancelled by the user. Their recorded evidence is historical; do not resume them.
|
||||
|
||||
---
|
||||
|
||||
# Historical matrix — candidate 0.4.0-rc.1 (superseded 2026-11-02)
|
||||
|
||||
The sections below were the working matrix on 2026-11-01. They are kept as evidence only and are **stale** where they list work as pending; the current truth is above.
|
||||
|
||||
## Observed gates
|
||||
|
||||
Historical (superseded heads, kept as evidence): Windows PR #16 head `35ed93c7…` hosted run 41340470827 passed Core 154 and CLI/Windows 317 with 0 warnings; server PR #30 head `4eee28e9…` passed 183 reported / 182 executed / 1 opt-in skip / Checkstyle 0. Protected main then advanced (server rendering at printing 2.2.0; client virtual-agent), so those heads are not the candidate.
|
||||
|
||||
Current candidate, local results only:
|
||||
|
||||
| Tree | Gate | Result |
|
||||
| --- | --- | --- |
|
||||
| Windows | First focused build | **Rejected**: `PrintWorker.cs(96,29)` MA0051 (method 67 lines, maximum 60), caused by the phase-timing instrumentation. Log preserved. An earlier sandbox build had stalled with orphaned build workers; that was environmental, not source. |
|
||||
| Windows | After extracting `SubmitJobAsync`, `RequireCurrentPrinter`, `RequireSubmitAllowed`, `SubmitNativeAsync` and `JobAttempt` (no analyzer waiver) | Focused negotiation/runtime run **16 of 16 passed**, no warnings, no analyzer errors. Core.Tests was not built. |
|
||||
| Windows | Roslyn token compare against merge base `c4c663a` | Exactly the four intended semantic files differ (`PrintWorker.cs`, `PrintWorkerTests.cs`, `QqqApiDiscovery.cs`, `AgentRealtimeMediaCapabilitiesTests.cs`); no fifth file. The worker refactor was reviewed: same reservation, staged-file and submission disposal inside the same catch, same authority checks and state order. |
|
||||
| Server | Full verify, sandbox | 188 reported, 0 assertion failures, 11 loopback setup errors, 1 skip. Environmental; log preserved. |
|
||||
| Server | Full verify, actual user, before fix | 188 reported, 0 assertion failures, **1 error** (`PrintingRealtimeTest.mediaCapabilityIsReplacedOnEveryAuthenticatedHello`, temp-directory cleanup). Cause: `PrintingRealtimeRoutes.close()` did not wait for in-flight channel drains, which recreated the stopped file database. Log preserved. |
|
||||
| Server | After `stopWorkers()` fix and regression `closeWaitsForChannelWorkersAlreadyRunning` | `PrintingRealtimeTest` five consecutive runs, 4 tests each, no empty-database warnings. Full verify **189 reported / 188 executed / 1 intentional opt-in workload skip / 0 failures / 0 errors, Checkstyle 0**. Source-header guard over 146 tracked files passed; staged whitespace checks passed. |
|
||||
| Protocol | Check | 76 definitions and 78 fixtures passed locally; compatibility docs published as a signed draft PR #15 (commit `1916324e6d2c0dac0fd48f2401b654303ab228f9`). |
|
||||
|
||||
**Not yet observed:** hosted CI on the final signed candidate heads (Windows Core.Tests, the new `RunOnce_LogsOnePhaseTimingLinePerJobWithoutDocumentContent`, Cli.Tests totals, MSI build at ProductVersion 0.4.0; server verify). Hosted passes do not clear the local Defender quarantine of the Core test assembly, which stays unbuilt and unrestored. No installer, installed-upgrade, physical-output or published-cohort native-callback result exists for this candidate.
|
||||
|
||||
Status words are strict. **Proven** names evidence that was observed for the stated scope. **Partial** means part of the requirement has evidence. **Incomplete** means no qualifying evidence exists yet, including where only source or a plan exists.
|
||||
|
||||
| Requirement | Status | Evidence on record | Open gap / exact next evidence |
|
||||
| --- | --- | --- | --- |
|
||||
| AppKit parity (menu, About, settings, theme, logs, tray, update) | Partial | [APPKIT-PARITY.md](APPKIT-PARITY.md); real in-app 0.3.1 → 0.3.2 update accepted ([ACCEPTANCE.md](ACCEPTANCE.md)); 426-test Release gate at 0.3.2 | Update download/installer failure, cancel and reboot-required paths; high contrast, Narrator, scaling and small-screen matrix. Not re-run for this candidate. |
|
||||
| Realtime, reconnect, large-file control concurrency | Partial | Source tests: `PauseAndCancelRemainResponsiveDuringLargeDownloadWithoutHttpPolling`, `NativeCookieAndDeviceProofUpgradeKeepsReceivingDuringStalledDocument`, ordering/generation/bandwidth suites; installed 0.3.x reconnect observed ([REALTIME.md](REALTIME.md)) | [TODO.md](TODO.md) still lists the combined runtime review (stalled transfer, lost ACK, reconnect) as unchecked. Needs the hosted Core + Windows gate on the exact head, then an installed reconnect check on a compatible server. |
|
||||
| Jobs table, details, sorting, 10k/day scale | Partial | `JobSortingTests.TenThousandJobs_AllColumnsSortAcrossPagesAndInterleaveBoundedCloudQueue`; `AgentStoreScaleTests`; 375,000-job store measurements in [SCALABILITY.md](SCALABILITY.md); installed UI checks at 0.1.9/0.3.1 | Measurements are local storage with fake printers. GUI rendering at scale, service scheduling and printer throughput are unmeasured. Not a throughput claim. |
|
||||
| Printer media (this candidate) | Partial | Read-only real-driver/DC normalization probe 4×6 in / 300 DPI with no queue change ([PRINTER-MEDIA.md](PRINTER-MEDIA.md)); media is offered only to stable printing 2.3+ in major 2 (2.2 rendering stays a three-capability peer), covered by the 16 passing focused negotiation/runtime tests (HELLO per version, reconnect upgrade and downgrade) | The earlier hosted Core pass was on a superseded head. Final-head hosted Core is pending and does not clear the local Defender quarantine. No installed profile-selected print has occurred. |
|
||||
| Print latency (measured 5–7 s ZPL test print) | Not pursued | Historical: source trace of the per-job path and a diagnostic plan (`LATENCY-DIAGNOSTIC-PLAN.md` in the coordination outbox); the candidate logs one phase-timing line per job | The user cancelled further latency work; the cause stays unproven and nothing is claimed. The log line remains available. |
|
||||
| Branding and install | Partial | [BRANDING.md](BRANDING.md); branding tests; MSI payload/resource/notice checks recorded for 0.3.2 | Candidate MSI is built only by the hosted job on the final head (pending). Needs MSI resource comparison against the 0.3.2 baseline after CI, then the install-free plan in [UPGRADE-QUALIFICATION.md](UPGRADE-QUALIFICATION.md). |
|
||||
| Status and log rotation | Partial | `AgentLogSettingsTests` (10k jobs × 3 entries inside the default daily budget); daily-cap marker and clear-logs behavior in [SCALABILITY.md](SCALABILITY.md) | Installed rotation across a local-midnight boundary and cap visibility in the UI are not observed. |
|
||||
| Native auth, permissions, recovery | Partial | Isolated real Authentik login, permission, logout, expiry/renewal and revocation against an unreleased API 1.9 candidate in local Docker; recovery regressions in [QQQ-SIGN-IN.md](QQQ-SIGN-IN.md) | Installed browser/private-callback and long-lived grant need a compatible published API 1.9+ cohort. The local server 1.8 does not qualify. **Incomplete** until that cohort exists. |
|
||||
| Retained-source and S3 retention boundaries | Partial | Server local full verify on the merged candidate: 189 reported / 188 executed / 1 intentional opt-in 10k skip / 0 failures, Checkstyle 0; callback authority and accepted-row history fixes independently reviewed; the server's `docs/STORAGE-AND-RETENTION.md` states the layout, outbox-copy and versioning boundaries | Final-head server hosted CI pending. Production IAM, bucket policy, noncurrent-version retention and cross-platform key migration are deployment work, not proven. Echo's experimental core tuple is unqualified; no silent repin. |
|
||||
| Packaging, CI/CD, notices, About | Partial | Notice and Query About guards merged into both bases; release workflow pins actions and protocol; candidate version inputs (0.4.0 / 0.4.0-rc.1) and the reviewed workflow patch are applied by the coordinator, with action pins unchanged | The protocol pin in `ci.yml` is the final commit `42c0d249f81395f00408ec0f92638dcbbf5deb03` ([Gitea PR 2](https://git.kof22.com/QRun-IO/qqq-print-protocol/pulls/2)); earlier pins are historical. Candidate identity is 0.4.0-rc.2 (ProductVersion 0.4.0). Hosted packaging steps on the final head are pending. MSI remains unsigned. |
|
||||
| C# source standards (XML how/why headers, member layout) | Partial | License headers on all tracked C# (IDE0073, [SOURCE-HEADER-COMPLIANCE.md](SOURCE-HEADER-COMPLIANCE.md)); how/why headers and structural spacing completed in batches A to D, each token-compared as comment and blank-line only; Roslyn helper controls passed | Source cleanup is complete and merged. A final inventory over the merged tree has not been reported, and the merged UI build and 35 paper/media tests passed locally; hosted CI is pending. |
|
||||
|
||||
## Order of closure
|
||||
|
||||
1. Done locally: both trees pass their focused/full local gates (table above). Pending: signed functional commits and exact-head hosted CI for the Windows and server candidate heads.
|
||||
2. Done: the Roslyn inventory/compare helper passed its positive and negative controls.
|
||||
3. After the functional baseline is committed: documentation-only C# standards batches of at most 8 files, each with token-equivalence proof and never mixed with semantic fixes.
|
||||
4. Version inputs (`Directory.Build.props`, `build/Build-Installer.ps1`, README, CHANGELOG) and the `ci.yml`/`release.yml` patch are applied for the candidate. No tag.
|
||||
5. Normal Gitea Core/CLI/build CI on the integration head, then installation of the new label implementation and a small-stock paper test.
|
||||
6. Historical, no longer active: the install-free upgrade plan in [UPGRADE-QUALIFICATION.md](UPGRADE-QUALIFICATION.md) and the latency diagnostic plan were cancelled by the user; their recorded evidence is kept.
|
||||
|
||||
## Not claimed (historical, 2026-11-01)
|
||||
|
||||
Authenticode signing, physical-stock sensing, installed profile-selected printing, desktop/native OAuth callback or long-lived grant on a published cohort, remote cloud deployment, broad driver matrix, and any 1.0 readiness.
|
||||
@@ -1,89 +0,0 @@
|
||||
# Stable release signing
|
||||
|
||||
Stable `vX.Y.Z` tags publish a signed MSI; `vX.Y.Z-rc.N` tags stay unsigned prereleases. Signing uses the
|
||||
same Azure Artifact Signing account, profile and publisher as
|
||||
[MarkdownViewr.Windows](https://github.com/KofTwentyTwo/MarkdownViewr.Windows) (its `docs/azure-signing-admin.md`
|
||||
and `docs/release-signing.md`), with the same pinned `azure/login` and `azure/artifact-signing-action`. This
|
||||
repository adds no signing service, key export or secret.
|
||||
|
||||
## What the release workflow does
|
||||
|
||||
`.github/workflows/release.yml` first validates the tag; for a stable tag its `version` job also requires the tagged
|
||||
commit to be an ancestor of `origin/main` (as MarkdownViewr.Windows does), so an off-main stable tag stops before
|
||||
any gate or signing. It then runs every existing gate (Windows build/test/package, security, CodeQL, scripts).
|
||||
Release-candidate tags skip the ancestry check and stay unsigned. For a stable tag the `sign` job then runs in the protected `release` environment (tags `v*` only) with
|
||||
OIDC and no stored secret:
|
||||
|
||||
1. `build/Assert-ReleaseSigning.ps1` checks the protected variables below (configuration only).
|
||||
2. Locked restore, `Test-WindowsSdkInventory -VerifyPackages`, `Test-BrandedInstaller`, `Test-PackagingInputs`.
|
||||
3. `Build-Installer.ps1 -PublishOnly` publishes and checks the service, companion and CLI payloads (versions,
|
||||
file versions, WinUI resources, SDK inventory) without building the MSI.
|
||||
4. `Sign-Release.ps1 -Operation Stage` copies only the owned files into a staging folder: the three executables
|
||||
plus `Qqq.PrintAgent*.dll` and `KofTwentyTwo.AppKit*.dll` beside them. Third-party binaries keep their own
|
||||
signatures.
|
||||
5. `azure/login`, then `azure/artifact-signing-action` signs the stage (SHA256, RFC3161 timestamp).
|
||||
6. `Sign-Release.ps1 -Operation Apply` accepts a staged file only if it changed, passes `signtool verify /pa /all /v`
|
||||
and `Get-AuthenticodeSignature` (valid, timestamped) and has exactly `ARTIFACT_SIGNING_SUBJECT`. The signtool
|
||||
output must show exactly one verified signature, zero warnings and errors, and every `Hash of file (...)` line
|
||||
must be `sha256` (certificate-chain text naming an algorithm is not counted). Only then are the files copied
|
||||
back, and the payload is verified again in place.
|
||||
7. `Build-Installer.ps1 -SkipPublish` builds the MSI from the signed payload (all payload checks run again).
|
||||
8. The MSI is staged, signed by the same action, and accepted by the same publisher check.
|
||||
9. `Package-Release.ps1 -AssembleOnly -ExpectedPublisherSubject` re-verifies the MSI and writes the four release
|
||||
files (versioned MSI, `Install-Branded.ps1`, `branding.example.json`, `SHA256SUMS`). Checksums are computed after
|
||||
signing.
|
||||
|
||||
The `publish` job requires every gate and, for a stable tag, a successful `sign` job. It then verifies the
|
||||
checksums, attests the artifacts and runs `gh release create --verify-tag --latest`, which cannot overwrite an
|
||||
existing release. An unsigned prerelease path is unchanged.
|
||||
|
||||
## Required protected-environment variables (non-secret)
|
||||
|
||||
Set in the GitHub `release` environment of this repository (see the MarkdownViewr runbook for the procedure):
|
||||
|
||||
| Variable | Value |
|
||||
| --- | --- |
|
||||
| `AZURE_TENANT_ID` | Tenant GUID (MarkdownViewr reference: `4ebeb0ad-5782-487a-a1b4-5080255774cf`) |
|
||||
| `AZURE_SUBSCRIPTION_ID` | Signing resource's subscription (reference: `8ef2479e-3346-4cba-93ad-101c6cd237a0`) |
|
||||
| `AZURE_CLIENT_ID` | A client GUID with trust for **this** repository (below); never copy another repository's |
|
||||
| `ARTIFACT_SIGNING_ENDPOINT` | Regional endpoint (reference: `https://eus.codesigning.azure.net/`) |
|
||||
| `ARTIFACT_SIGNING_ACCOUNT` | Account (reference: `kof22signing`) |
|
||||
| `ARTIFACT_SIGNING_PROFILE` | Active PublicTrust profile (reference: `releases`) |
|
||||
| `ARTIFACT_SIGNING_SUBJECT` | Full certificate subject (reference: `CN=James Maes, O=James Maes, L=Chester, S=il, C=US`) |
|
||||
|
||||
The reference values are copied from the MarkdownViewr runbook; read the deployed resource back before use.
|
||||
|
||||
## Identity binding for this repository
|
||||
|
||||
The CI identity must be an approved single-tenant Entra application and service principal with **no client secret**,
|
||||
a federated credential for the exact release-environment subject, and the `Artifact Signing Certificate Profile Signer`
|
||||
role scoped to the profile only:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "qqq-print-agent-release",
|
||||
"issuer": "https://token.actions.githubusercontent.com",
|
||||
"subject": "repo:QRun-IO@<owner-id>/qqq-print-agent@<repo-id>:environment:release",
|
||||
"audiences": ["api://AzureADTokenExchange"]
|
||||
}
|
||||
```
|
||||
|
||||
Read the immutable owner and repository IDs from `gh api repos/QRun-IO/qqq-print-agent/actions/oidc/customization/sub`
|
||||
(and confirm `use_immutable_subject`). Trust must not be broadened to pull requests or other environments. MarkdownViewr's
|
||||
and gclo's identities must not be reused for this repository without separate approval and their own trust.
|
||||
|
||||
## Published stable result — 2026-11-03
|
||||
|
||||
The authorized GitHub signing bridge completed [release run 41532214447](https://github.com/QRun-IO/qqq-print-agent/actions/runs/41532214447) for `v1.0.1`, source `5bf00f3291923f7afb34c6cce61276e69649689b`. Its build, test, security, CodeQL, script, OIDC signing and publication gates passed. The signed MSI and matching assets are published on [Gitea](https://git.kof22.com/QRun-IO/qqq-print-agent/releases/tag/v1.0.1) and [GitHub](https://github.com/QRun-IO/qqq-print-agent/releases/tag/v1.0.1); the latter remains the installed updater feed.
|
||||
|
||||
The downloaded MSI's checksum matched `SHA256SUMS`; Authenticode reported **Valid**, the exact configured publisher `CN=James Maes, O=James Maes, L=Chester, S=il, C=US`, and a timestamp. Release provenance was verified. The local installation on November 3 exited 0 with companion, service and CLI all reporting `1.0.1+5bf00f3291923f7afb34c6cce61276e69649689b`, file version `1.0.1.65535`, and service state **Running**. See [release readiness](RELEASE-READINESS.md).
|
||||
|
||||
The printing-only Azure client uses the exact immutable repository/environment subject, a profile-scoped signer role and protected environment variables, with no stored client secret. The same signing account/profile and verification rules described above remain in use.
|
||||
|
||||
## Historical bootstrap failure and limits
|
||||
|
||||
The first hosted stable attempt, `v1.0.0`, passed its prerequisite gates and Azure OIDC login but stopped before signing because the action's SignCLI installer conflicted with NuGet package source mapping. No signed 1.0.0 installer was published. Version 1.0.1 fixes the bootstrap by preinstalling only pinned SignCLI `0.9.1-beta.26227.3` through the mapped `nuget.config` into the action's expected `%LOCALAPPDATA%\ArtifactSigning\sign\sign.<version>` layout. The 1.0.0 tag is unchanged.
|
||||
|
||||
The earlier local signing proof used copies of the RC4 payload and MSI; it was not the hosted release. The successful 1.0.1 run now supplies the CI identity/signing evidence. QQQ 4.1.0-RC.21 and qbit-printing 1.0.0 provide the released native-authentication cohort; the older RC20 prerequisite is superseded.
|
||||
|
||||
`Apply` still requires exactly the staged files, and publisher matching remains an exact string comparison. `Install-Branded.ps1` and `branding.example.json` are not Authenticode-signed; their integrity rests on release checksums and provenance. Signing establishes publisher identity, not physical printer compatibility or universal deployment qualification.
|
||||
+10
-26
@@ -1,13 +1,5 @@
|
||||
# Release process
|
||||
|
||||
Gitea is primary for source branches, reviews and normal pull requests. GitHub is the automatic source shadow. The existing authorized [GitHub release workflow](../.github/workflows/release.yml), its CI/security dependencies and the GitHub release assets remain the signing and installed-updater bridge. Do not retire those Windows workflows or remove the feed as part of ordinary source migration.
|
||||
|
||||
Current stable release: **[1.2.1 on Gitea](https://git.kof22.com/QRun-IO/qqq-print-agent/releases/tag/v1.2.1)** and the matching **[GitHub assets](https://github.com/QRun-IO/qqq-print-agent/releases/tag/v1.2.1)** (generic and GG Forge installers). The protected [release run](https://github.com/QRun-IO/qqq-print-agent/actions/runs/42223525626) completed signing and publication; checksums, Authenticode signatures and provenance attestations were verified on the downloaded assets (generic `09920872…`, GG Forge `5ce48909…`). The earlier immutable `v1.0.0` and `v1.2.0` tags produced no signed installer (`v1.2.0`: the edition sign job's array splat, fixed in 1.2.1); they must not be moved or reused. Previous stable: 1.1.1.
|
||||
|
||||
## Stable releases
|
||||
|
||||
The release workflow runs on a stable `vX.Y.Z` tag. After every gate below it signs the service, companion and CLI binaries, builds the MSI from them, signs the MSI with the project's Azure Artifact Signing identity, verifies the exact publisher, and publishes a non-prerelease with checksums computed after signing. Prerelease tags are unaffected and stay unsigned. Setup, ordering and required variables are in [RELEASE-SIGNING.md](RELEASE-SIGNING.md).
|
||||
|
||||
## Prereleases
|
||||
|
||||
The [`prerelease` workflow](../.github/workflows/release.yml) runs on tags matching `vX.Y.Z-rc.N`, or can be dispatched against an existing matching tag. It validates the tag and requires the Windows build/test/package, security, CodeQL and PowerShell script gates. It then downloads that run's installer artifact, verifies every packaged checksum, attests the artifacts and creates a GitHub prerelease containing:
|
||||
@@ -19,36 +11,28 @@ The [`prerelease` workflow](../.github/workflows/release.yml) runs on tags match
|
||||
|
||||
Source contents are read-only outside the publication job. That final job receives release-write, OIDC and attestation permissions; security analysis receives only the permissions needed to report its results. Action/reusable-workflow dependencies are pinned by commit. The protocol fixture checkout is pinned to a reviewed commit. Any failed prerequisite or checksum/attestation step prevents publication.
|
||||
|
||||
Release-candidate MSIs remain explicitly unsigned. GitHub provenance identifies the build workflow and artifact digest; it is not Authenticode publisher signing or production qualification. Verify attestations for the exact published files using `gh attestation verify <asset-path> --repo QRun-IO/qqq-print-agent`, and record the result. Older releases may lack attestations; the current workflow does not retroactively attest them. No signing secret or winget submission is implied. Observed in-app update evidence is in [ACCEPTANCE.md](ACCEPTANCE.md). The final job refuses to overwrite an existing GitHub release; use a new prerelease tag for changed binaries.
|
||||
|
||||
## Client editions
|
||||
|
||||
The stable release signs and publishes one installer per folder under `editions/` beside the generic one (`<assetPrefix>-vX.Y.Z-x64.msi`), each built from the same tagged source with that edition's branding, and lists them all in `SHA256SUMS`. The `editions` job enumerates the folders, the `sign` job runs once per edition, and the `assemble` job re-verifies every signature before writing the release files. An installed edition updates only from its own asset name. See [BRANDING.md](BRANDING.md#client-editions).
|
||||
|
||||
## Version identity constraint
|
||||
|
||||
Windows Installer replaces a versioned file only when its numeric file version is higher, and the .NET SDK would give every `X.Y.Z-rc.N` the same `X.Y.Z.0`. `build/Build-Installer.ps1` therefore stamps all three executables with `X.Y.Z.N` for `X.Y.Z-rc.N` (N from 1 to 65534) and `X.Y.Z.65535` for stable `X.Y.Z`, and fails if an executable reports a different file version. Only `rc.N` and stable are supported; any other prerelease label (for example `beta.1`) is refused rather than mapped to an unordered number, so a new label scheme needs a reviewed mapping first. The MSI ProductVersion stays `X.Y.Z`, and the updater still compares the semantic version string.
|
||||
The MSI remains explicitly unsigned. GitHub provenance identifies the build workflow and artifact digest; it is not Authenticode publisher signing or production qualification. Verify attestations for the exact published files using `gh attestation verify <asset-path> --repo QRun-IO/qqq-print-agent`, and record the result. Older releases may lack attestations; the current workflow does not retroactively attest them. No signing secret, winget submission or completed in-app upgrade qualification is implied. The final job refuses to overwrite an existing GitHub release; use a new prerelease tag for changed binaries.
|
||||
|
||||
## Maintainer checklist
|
||||
|
||||
1. Update CHANGELOG.md, acceptance evidence and version inputs. Ensure no local enrollment/journal/payload files are tracked.
|
||||
2. Review the protocol pin, dependency lock files, channel-specific signing notice and release scope.
|
||||
3. Inspect the corresponding successful CI run, or run `./build/Verify.ps1` and build the MSI on a permitted Windows test host. Host restrictions remain in force.
|
||||
4. Obtain explicit release authorization, create the immutable stable or prerelease tag from reviewed primary source, and use the authorized GitHub bridge to run the workflow. Do not push ordinary branches to the GitHub shadow.
|
||||
5. Verify every published filename/checksum, applicable Authenticode signature and provenance attestation. Publish the same reviewed release assets on primary Gitea without rebuilding or changing them. Record the workflow URL and version-specific installed/hardware evidence.
|
||||
2. Review the protocol pin, dependency lock files, unsigned-release notice and open limitations.
|
||||
3. Run `./build/Verify.ps1` and build the MSI locally or inspect the corresponding green CI run.
|
||||
4. Obtain explicit release authorization, create/push the immutable prerelease tag, and wait for the workflow.
|
||||
5. Verify every published filename/checksum and its provenance attestation. Record the workflow URL and version-specific installed/hardware acceptance, distinguishing observed results from pending qualification.
|
||||
|
||||
If publishing the initial release manually, attach only reviewed artifacts and disclose whether they were built locally. Do not claim GitHub build provenance for a local MSI.
|
||||
|
||||
## Signing
|
||||
## Production signing follow-up
|
||||
|
||||
Stable tags are signed by the release workflow with Azure Artifact Signing (see [Stable releases](#stable-releases) and [RELEASE-SIGNING.md](RELEASE-SIGNING.md)); release candidates stay unsigned. `Build-Installer.ps1` also accepts a certificate thumbprint and timestamp server for local signing only. The CI identity completed OIDC authentication and signed stable 1.0.1. Current evidence is in [RELEASE-READINESS.md](RELEASE-READINESS.md).
|
||||
`Build-Installer.ps1` accepts a certificate thumbprint and timestamp server for local signing. Production automation must integrate the organization's approved signing service and sign/verify first-party executables and the final MSI. That setup is not part of this prerelease. Upgrade/reboot/service-account qualification and broader hardware acceptance are also required before calling it a production release.
|
||||
|
||||
## Update-feed contract
|
||||
|
||||
The companion uses AppKit update prompts with a machine MSI adapter. Release assets are also updater inputs: preserve the exact versioned MSI filename and matching `SHA256SUMS` entry. The updater checks release identity, size and SHA-256; provenance verification is a separate release/operator check. The fixed feed is this repository's GitHub releases; branding and QQQ configuration cannot redirect it. Stable installations ignore prereleases, while RC installations may receive a newer RC or stable version. The minimum offered core version is 0.1.3. Never replace a published release's binary under the same version.
|
||||
|
||||
MSI has a numeric three-part ProductVersion; informational version preserves `-rc.N`. Same-numeric-version MSI upgrades are enabled for RC-to-RC/stable transitions, while the updater enforces a strictly newer semantic release. This intentional authoring requires a narrow ICE61 exception alongside the existing Microsoft-resource ICE03 exception; no other MSI checks are disabled. Manual MSI deployments must follow semantic release order because MSI alone cannot order RC suffixes. See [ADR-0002](adr/0002-prerelease-quality-and-packaging.md). The helper verifies the installed component versions against the requested release after exit 0. Exit 3010 remains restart-required.
|
||||
MSI has a numeric three-part ProductVersion; informational version preserves `-rc.N`. Same-numeric-version MSI upgrades are enabled for RC-to-RC/stable transitions, while the updater enforces a strictly newer semantic release. This intentional authoring requires a narrow ICE61 exception alongside the existing Microsoft-resource ICE03 exception; no other MSI checks are disabled. Manual MSI deployments must follow semantic release order because MSI alone cannot order RC suffixes. See [ADR-0002](adr/0002-prerelease-quality-and-packaging.md). The helper verifies the installed companion's actual ProductVersion against the requested release after exit 0. Exit 3010 remains restart-required.
|
||||
|
||||
Same-feed SHA-256 establishes asset consistency, not independent publisher authentication; stable releases additionally carry Authenticode signatures on the first-party binaries and the MSI, while release candidates do not. The helper requires administrator rights, installs service/UI/CLI together and retains credentials/journal; no per-user updater or privileged persistent daemon is shipped. Completed staging folders and install logs are retained for administrator review.
|
||||
Same-feed SHA-256 establishes asset consistency, not independent publisher authentication. Signed first-party binaries/MSI and signing automation remain separate work. The helper requires administrator rights, installs service/UI/CLI together and retains credentials/journal; no per-user updater or privileged persistent daemon is shipped. Completed staging folders and install logs are retained for administrator review.
|
||||
|
||||
Historical: the 0.1.3 source gate passed 163 tests with zero warnings/errors and locked restore. A real in-app update from 0.3.1 to 0.3.2 has since been accepted with retained identity, history and profiles, matching component versions and an automatically reopened companion; see [ACCEPTANCE.md](ACCEPTANCE.md) and [RELEASE-READINESS.md](RELEASE-READINESS.md). Packaging or UI test compilation alone does not establish update acceptance. Stable 1.0.1 publication and its separate local MSI installation are recorded above.
|
||||
The 0.1.3 source gate passed 163 tests with zero warnings/errors and locked restore. Before claiming update acceptance, record a real installed upgrade, version coherence, retained state, cancellation/failure handling, companion relaunch and reboot-required behavior. Current installed UI and actual in-app upgrade acceptance are pending; UI test compilation and packaging alone are insufficient.
|
||||
+3
-10
@@ -1,13 +1,6 @@
|
||||
# History and diagnostic limits
|
||||
|
||||
Client `1.0.1` uses event-driven claim drains and direct realtime control
|
||||
traffic, with separately bounded document downloads and native submissions.
|
||||
Default document limits are 100 MiB PDF and 20 MiB ZPL; administrators configure
|
||||
these and concurrency, staging, bandwidth and deadlines. There is no periodic
|
||||
job/control fetch. See [realtime settings](REALTIME.md). The storage measurements
|
||||
below retain their original versions and do not certify the new runtime pipeline.
|
||||
|
||||
The historical 0.1.8 audit removed the configured idle delay after a newly submitted successful job. Its regression drained three fake jobs before a configured 20-second interval, then verified empty/error responses did not hot-loop. That gate passed 249 tests with zero warnings/errors. This was scheduling evidence for the earlier HTTP transport, not sustained physical throughput qualification.
|
||||
Audit source removes the configured idle delay after a newly submitted successful job. It yields and releases the connection gate between jobs; empty queues, duplicate receipts, failures, errors and pauses retain their delay/backoff. A regression drains three fake jobs before a configured 20-second interval, then verifies empty/error responses do not hot-loop. The current audit gate passed 249 tests with zero warnings/errors. This removes a scheduling bottleneck; it does not certify sustained physical throughput.
|
||||
|
||||
The current source targets facilities producing about 10,000 jobs per day. Synthetic tests exercise 10,000/30,000 stored jobs, a 10,000-event delivery backlog and 30,000 normal status-log entries. They measure local query/write behavior with fake HTTP/printers; they do not certify physical printer throughput or production network capacity.
|
||||
|
||||
@@ -42,7 +35,7 @@ The Jobs page queries SQLite rather than filtering the latest snapshot. Page siz
|
||||
|
||||
A bounded preview of up to 50 cloud-queued jobs interleaves with local history under the same selected sort order and keeps queued cancellation available before receipt. Matching local jobs suppress duplicate preview rows. The UI marks when the preview reaches its bound; its combined count is not an authoritative total for an arbitrarily large cloud queue. The merge reads at most 150 local candidates in bounded SQL pages, regardless of the requested offset, plus at most 50 cached queued jobs. Text ordering uses SQLite NOCASE (ASCII case folding, otherwise UTF-8 order) consistently for both sources; visible fallback labels and reviewed-status suffixes participate in ordering.
|
||||
|
||||
Outbox reads remain bounded to 200 ordered events per batch. The realtime runtime sends events through the authenticated socket and waits for durable ACKs, preserving pending records across reconnect. Interrupted-state recovery is also batched. Job details expose the latest 200 retained events, with a short recent history in the expanded row. The legacy event-to-summary migration runs once, rather than grouping all events each time the service opens its store.
|
||||
Outbox delivery reads at most 200 ordered events per poll. The worker heartbeats and defers new claims until the previous backlog has drained. Interrupted-state recovery is also batched. Job details expose the latest 200 retained events. The legacy event-to-summary migration runs once, rather than grouping all events each time the service opens its store.
|
||||
|
||||
Default detail retention is 30 days or 300,000 jobs, with at most 250 eligible jobs pruned per maintenance pass. Runtime schedules this maintenance once per minute. Pending events, active submissions, unreviewed failures and every uncertain outcome retain their evidence. Operator review never changes delivery status. Terminal summaries remain for duplicate suppression even after event detail is pruned; the database therefore has no fixed lifetime size ceiling. SQLite reuses freed pages; retention does not promise that its file immediately shrinks. Monitor disk use and resolve operational exceptions instead of deleting a live journal.
|
||||
|
||||
@@ -50,7 +43,7 @@ Creation time is separate from the latest status-update time. Receipt captures t
|
||||
|
||||
## Logs
|
||||
|
||||
AppKit retains its local-midnight daily filename rotation and shared log viewer. Machine-wide settings default to 30 days retention, 100 MiB per file and 10 rolled-over segments per day; supported ranges are 1–365 days, 1–1024 MiB and 1–100 segments. A file that reaches its limit is renamed to `qqq-print-agent-yyyy-MM-dd.N.log` and a fresh file continues, so the bound per day is the file size times the kept segments plus the live file, and no entry is ever suppressed. Debug logging (off by default) adds request-level detail. Service and companion use one cross-process lock for appends, rollover, settings, retention and clearing.
|
||||
AppKit retains its local-midnight daily filename rotation and shared log viewer. Machine-wide settings default to 30 days and 20 MiB per daily file; supported ranges are 1–365 days and 1–100 MiB. Service and companion use one cross-process lock for appends, settings, retention and clearing.
|
||||
|
||||
At the daily limit, the backend writes a warning when space permits and persists a cap marker. Settings exposes current bytes and whether that day's limit was reached. Further diagnostics are suppressed until the next local day, an increased limit or explicit clearing; printing continues. The cap is visible rather than silently discarding ongoing errors. Detailed high-frequency logs may need a higher limit than the normal three status entries per job used by the synthetic workload.
|
||||
|
||||
|
||||
+12
-429
@@ -1,443 +1,32 @@
|
||||
# Session state — 2026-11-06
|
||||
# Session state — 2026-10-31
|
||||
|
||||
## Current — 1.2.1 released; printing cohort protocol 1.1.0 / QBit 1.1.0 / client 1.2.1 complete
|
||||
## Installed 0.1.9-rc.1 qualification
|
||||
|
||||
Client 1.2.1 (source `3b9d75d18f9cc8b80f4cf6d5aae81cccf8d61243`, GitHub release run 42223525626) is published with signed generic and GG Forge installers on GitHub and, byte-identical, on Gitea; see [RELEASING](RELEASING.md). Protocol 1.1.0 and QBit 1.1.0 (extension 2.4.0, including Remove printers / Remove device) are published. The handoff for the Forge agent, with every version, artifact and hash, is [FORGE-HANDOFF-2026-11-05.md](FORGE-HANDOFF-2026-11-05.md); Forge adoption, pairing tests and installation on its station are that lane's. The installed GG Forge rc.3 on this PC updates to 1.2.1 from its own asset through the in-app updater (not yet exercised). Open elsewhere: Gitea CI quota/runner-fleet work (Praetor lane); docs PRs qbit-printing 29 and qqq-print-protocol 12.
|
||||
The exact CI installer from reviewed source `13aa84c` completed with MSI exit 0 and no restart requirement. Both installed management peers authenticated, protected credentials and journal history were preserved, and the service is running and connected. All **16 installed UI checks passed in one run**, and the companion opened successfully. No physical printing was requested. The source gate passed 255 tests with zero warnings/errors/skips; all ten required hosted checks passed. See [acceptance evidence](ACCEPTANCE.md).
|
||||
|
||||
The paired local QQQ host completed its native authenticated cutover with preserved pairing and history. Remote deployment, production S3/IAM, Windows reboot/recovery, hostile-tree installer rollback and publisher signing remain separate qualification work. The candidate is installed locally; protected merge and public prerelease are pending.
|
||||
|
||||
## 1.2.1 — release-pipeline fix after the v1.2.0 tag produced no signed installer
|
||||
## Corrective candidate 0.1.9-rc.1
|
||||
|
||||
Protocol 1.1.0 and QBit 1.1.0 are published (see below). PR 10 merged as `c8ea97e` and tag `v1.2.0` was mirrored; GitHub release run 42128511730 failed in `sign (gg-forge)` at "Publish and check the payload": the workflow splatted `-Edition gg-forge` as an array, which PowerShell binds positionally into `CertificateThumbprint`/`TimestampServer`, so `Build-Installer.ps1` refused `-PublishOnly`. Fixed with a hashtable splat (local reproduction of the step publishes the GG Forge payload); version bumped to 1.2.1 because `v1.2.0` is immutable and must not be reused. Next: merge, tag `v1.2.1` on Gitea, mirror, signed release, Gitea mirror of the assets, Forge handoff.
|
||||
The original approved upgrade installed 0.1.8 with MSI exit 0 and no restart requirement. Credentials and the journal were retained; both the old and new installed management peers authenticated. A later `query-jobs` check failed because the service disconnected before the client read the complete response. The helper's `cloudConnected=false` and `printerCount=0` were unassigned defaults after that failure. Independent server inspection confirms a current heartbeat, two enabled/available/ready printers and seven already-spooled jobs, with no pending or uncertain work.
|
||||
|
||||
## Printer approval over the realtime channel (extension 2.4.0) — implemented across three repositories, merges pending
|
||||
The failure was reproduced on an isolated random pipe using the actual runtime with fake printers and no network/configuration. All eight delayed-reader cases failed before the fix; all eight pass with the bounded client-close wait. Permanent tests cover current/legacy readers, success/error responses, subsequent clients, deadline expiry and runtime shutdown. The correction preserves the wire format and existing deadlines. Root source review found no concrete issue. The isolated combined 0.1.9 solution/UI build passed with zero warnings/errors and **255 tests (66 Core + 189 Windows/CLI), none failed or skipped**. All 234 source files and 24 protocol fixtures remained byte-identical after verification. PowerShell analysis (11 scripts, 75 rules), packaging-input validation, workflow lint and changed-document lint also pass. Hosted gates and installed UI/service qualification remain pending; the running 0.1.8 service has not been replaced by this source work.
|
||||
|
||||
- **Client (this repository), PR 10 head `f1ec404`** on `feat/client-editions-20261105`: operator-catalog fallback (2.3), `printer-approval-v1` negotiation and the authoritative `PRINTERS` frame (2.4), per-printer server state on the Printers page (Server column, summary, details), Clear logs button in the log viewer, pinned sign-in feedback banner, non-repeating sign-in reply. Hosted CI run 42116396114: 197 Core + 362 Windows tests, zero failures. Protocol fixture pin moved to `ac835f8b9396b641b525669249fdb4a1e2a50c99`.
|
||||
- **Protocol 1.1.0**, [PR 11](https://git.kof22.com/QRun-IO/qqq-print-protocol/pulls/11) (`ac835f8`): capability, `RealtimePrinters` schema, fixtures, REALTIME/VERSIONS docs; all gates green.
|
||||
- **QBit 1.1.0 (extension 2.4.0)**, [PR 25](https://git.kof22.com/QRun-IO/qbit-printing/pulls/25) (`3fa78de`): 195 tests green; [PR 26](https://git.kof22.com/QRun-IO/qbit-printing/pulls/26) (`c5a9c6d`, stacked on 25) adds Remove printers / Remove device as archives (`removed_at`) purged by retention when no job references them; 199 tests green.
|
||||
- Merge order: protocol 11, then QBit 25 and 26, then client 10. Then tag protocol `v1.1.0`, QBit `v1.1.0` (registry publication through the main run), client `v1.2.0` on Gitea with GitHub mirror sync. Forge adoption and pairing tests belong to the Forge agent; current working versions (protocol 1.0.0, QBit 1.0.0, client 1.1.1 / GG Forge rc.3) stay for rollback.
|
||||
- Local test builds today: 1.2.0-rc.1..rc.3 under `artifacts/share/`; GG Forge rc.3 (commit 887c58c, before the 2.4 negotiation) is installed on this PC.
|
||||
The user approved the prepared H2 record and selected completion against the local QQQ server first. Following separate explicit approval for the CodeQL configuration repair, [standards PR #54](https://github.com/KofTwentyTwo/standards/pull/54) merged normally after all nine required checks and both advanced CodeQL languages passed. Printing's narrow H2 exception is now active and its fresh dependency review passes. Local cutover must preserve the paired database, enrollment and tenant, with a verified native backup before stopping the old H2 2.3.232 host. No real cloud/S3 provisioning or new physical print has occurred.
|
||||
|
||||
# Session state — 2026-11-05
|
||||
|
||||
## Current status: 1.1.1 signed; client editions (1.2.0) complete in PR 10 — 2026-11-05
|
||||
|
||||
Signed **1.1.0** (sign-in diagnostics, debug logging, log rollover, per-server untrusted-certificate exception) and **1.1.1** (browser sign-in fix: the elevated companion's callback inbox pipe refused the unelevated protocol handler) are published on GitHub from Gitea tags through the mirror. Browser sign-in against the local Forge server (API 1.11.0, `nonceValidation: REQUIRED`) was confirmed working by the operator on the 1.1.1 build; PR 11 (required-nonce exchange) is on main.
|
||||
|
||||
[PR 10](https://git.kof22.com/QRun-IO/qqq-print-agent/pulls/10) (`feat/client-editions-20261105`, version 1.2.0) adds client editions (`editions/<id>`, first `gg-forge`): fully branded builds and installers named after the edition's asset prefix, an updater that follows only that asset, a release workflow that signs one installer per edition from one tag, edition options for server wording and About sections, nonce sending under OPTIONAL and the `nativeSessionNonceValidation` capability, and `build/Build-CiRelease.ps1` delegating to `Package-Release.ps1`. GitHub CI is green on the branch (182 Core, 352 Windows/CLI tests). Gitea refuses the merge only because its shared ".NET CI" jobs never start while the Windows runner is down; the operator is distributing local rc-numbered builds (`artifacts/share/print-agent-1.2.0-rc.1`) meanwhile. PRs 1 (stale dependabot) and 6 (superseded CI entrypoint) were closed. Next: when the runner returns, merge PR 10, tag `v1.2.0` on Gitea, synchronize the mirror, verify the first matrix release (generic + GG Forge), publish the same assets on Gitea.
|
||||
|
||||
# Previous session state — 2026-11-05
|
||||
|
||||
## Active scoped work: required-nonce native sign-in fix — 2026-11-05
|
||||
|
||||
Branch `fix/native-login-required-nonce`, integrated on main `f954f11`, makes native sign-in honor the server's `NativeGrant.NonceValidation` policy. One nonce is created per authorization attempt and kept in the attempt only when the policy is `REQUIRED`; the same value is sent as `expectedNonce` at `manageSession`. An absent (legacy) policy keeps the exact old four-field body, and an unknown non-empty policy is refused before any provider or browser step. The callback never supplies the nonce, and state, issuer, PKCE, single-use and expiry checks are unchanged.
|
||||
|
||||
The shared-server scanner Authentik requires this fix. The prior stable printing release below remains historical accepted evidence and is not reopened.
|
||||
|
||||
Observed so far:
|
||||
|
||||
- Previous-base solution build and 333 CLI tests passed locally. Core tests executed 0 tests because Windows security blocked the assembly; that is hosted-CI-only and is **not a pass**.
|
||||
- The integrated NativeCI Release build passed with zero warnings/errors after extracting the code-exchange body into a private helper to meet the existing method-length limit. All 352 Windows/CLI tests passed with no failures/skips; the source-notice check passed for 300 tracked files. Core.Tests was excluded as required on this workstation.
|
||||
- Root verified, in an isolated shared scanner/Printing 1.0.0 fixture with `REQUIRED` nonce, that both exact native callback registrations and real server HTTPS discovery work. This is discovery only, not native login proof.
|
||||
|
||||
Pending: hosted CI (including Core.Tests), real shared-provider native login acceptance, and the final published build.
|
||||
|
||||
## Historical: released and installed — 2026-11-04
|
||||
|
||||
Signed Windows **1.0.1** is published on primary Gitea and GitHub, from source `5bf00f3291923f7afb34c6cce61276e69649689b`. [Release run 41532214447](https://github.com/QRun-IO/qqq-print-agent/actions/runs/41532214447) passed its protected gates, OIDC signing and publication. Checksums, signatures and provenance were verified. The November 3 local MSI installation exited 0; app/service/CLI matched 1.0.1 (`1.0.1.65535`) and the service was Running. This docs-only update does not imply a new runtime check.
|
||||
|
||||
The matching released cohort is **qbit-printing 1.0.0**, **protocol 1.0.0** and **QQQ 4.1.0-RC.21**, with native printing API 2.3 and wire payload v1. The supported native sign-in prerequisite and protected release merges are complete. See [Release readiness](RELEASE-READINESS.md).
|
||||
|
||||
Current README and operator/maintainer guides have been refreshed against the released source. Gitea owns ordinary branches and PRs. The authorized Windows GitHub signing/CI workflows and GitHub release feed remain necessary; the installed updater uses that feed. Server/protocol Actions retirement does not retire the Windows bridge or remove the pinned protocol fixtures.
|
||||
|
||||
The user explicitly authorized publishing this documentation update after being informed that a Markdown-only push triggers the retained Microsoft-hosted workflow's full `Core.Tests` build. The branch `docs/printing-release-closeout-20261104` uses the normal Gitea PR and required checks. This authorization covers that hosted documentation build only; it does not clear local/VM6218 builds, quarantine restoration, exclusions or changes to protections. The prior local publication hold is superseded for this documentation update.
|
||||
|
||||
The requested product implementation, release and local installation are closed. No new builds, print tests, auth/storage qualification, UI-waiver work or Defender investigation belong to this documentation closeout. Earlier checkpoints below retain their original evidence and pending language as history, not active tasks.
|
||||
|
||||
## Historical: stable 1.0 closeout checkpoint — 2026-11-02
|
||||
|
||||
The official 0.4.0-rc.4 build is installed with all three components; the normal MSI
|
||||
upgrade exited 0 and the service is Running. The latest source is
|
||||
`53fe1b8281806eda7adc314f92c8205aefcb51ce`: clean hosted Windows CI run 41442796961 on
|
||||
that exact head passed 499 tests (166 Core + 333 CLI) with zero failures and skips, and the
|
||||
build and MSI had zero warnings and errors. Core.Tests is never built on the local host;
|
||||
that clean hosted pass is its evidence. The earlier run 41384467500 on `b5eb5d73` (499
|
||||
tests) is historical. The primary Gitea feed and the public feed carry all three
|
||||
prereleases (Windows 0.4.0-rc.4; server and protocol 0.4.0-rc.1), with nine assets
|
||||
checked and provenance verified. The source-header inventory (289 tracked files, 231
|
||||
C#) reported zero issues.
|
||||
|
||||
Physical output: the operator confirmed the 4 × 1 label on RC3 with the same relevant
|
||||
printing runtime; 4 × 6 and Letter were accepted earlier. Physical 4 × 2 was deferred by
|
||||
the operator and is not a stable blocker.
|
||||
|
||||
Stable signing is implemented (not in progress): the release workflow signs the owned
|
||||
binaries and the MSI with Azure Artifact Signing, as for MarkdownViewr Windows. All 19
|
||||
first-party binary copies of an installed RC4 payload, including `Cli/qqq-print-agent.dll`,
|
||||
and a disposable official RC4 MSI were Azure-signed and strictly verified (exact publisher,
|
||||
SHA256, timestamp). That is a local administrator proof; the new CI OIDC identity has not
|
||||
been exercised. See [RELEASE-SIGNING.md](RELEASE-SIGNING.md).
|
||||
|
||||
Remaining stable-release work: (1) the Windows release branch (Gitea PR 2) normal protected
|
||||
merge, which awaits the central native 1725 repair for Windows ACL and file sharing on
|
||||
Linux; (2) a supported, published QQQ core with native session login, still awaited (the
|
||||
last official release, RC20, does not have it). Installed and published remains RC4, not
|
||||
1.0. No new stable tag exists and this file makes no 1.0 claim.
|
||||
|
||||
Accepted known limitation: the post-print WinUI `LayoutCycleException` recorded under
|
||||
"Installed realtime release and companion follow-up" was removed from the 1.0 blocker
|
||||
list by the user on 2026-11-02. It is not fixed, and that history is preserved. The repeat
|
||||
Auth/S3 qualification, the latency investigation and the MSI comparison analysis were
|
||||
cancelled by the user and must not be resumed; their evidence is historical. All sections
|
||||
below are historical checkpoints; where they list work as pending they are superseded by
|
||||
this section. See [RELEASE-READINESS.md](RELEASE-READINESS.md).
|
||||
|
||||
## Historical: rc.3 ordered file version — 2026-11-01
|
||||
|
||||
Source `e10d251` implements the standard ordered numeric PE FileVersion: `X.Y.Z-rc.N`
|
||||
becomes `X.Y.Z.N` and stable becomes `X.Y.Z.65535` (details in
|
||||
[RELEASING.md](RELEASING.md)). The packaging-input checks and the actual rc.3
|
||||
production packaging passed: all three payloads report file version `0.4.0.3` and
|
||||
semantic version `0.4.0-rc.3+e10d251`. The local rc.2 installation was verified. The
|
||||
rc.3 normal MSI upgrade completed with exit 0; all three installed executables match
|
||||
the rc.3 source and report numeric file version `0.4.0.3`, with no repair required. The
|
||||
server was updated to printing 2.3.0 with pairing and history preserved.
|
||||
|
||||
Printing observation: the operator confirmed the 4 × 1 test printed perfectly after
|
||||
the initial media-alignment issue. The operator chose to keep 4 × 1 stock loaded;
|
||||
the implemented 4 × 2 test option is awaiting a future stock change, with no physical
|
||||
result claimed for that size. No further test jobs will be sent until requested.
|
||||
|
||||
Not claimed: no GA. The Gitea release artifact, update feed and shared Windows CI stay
|
||||
with the migration owner. Core.Tests is not built or run on this host, which includes the
|
||||
Gitea runner 6; it is not scheduled here.
|
||||
|
||||
## Historical: candidate 0.4.0-rc.1 integration with protected main — 2026-11-01
|
||||
|
||||
Protected main advanced during qualification (client virtual-agent behavior; server
|
||||
printing 2.2.0 rendering), so the earlier green PR heads are historical evidence
|
||||
only. The media/operator/retained feature moved to printing **2.3.0**; this client
|
||||
offers `printer-media-v1` only to a stable 2.3+ server in major two and stays a
|
||||
three-capability peer on 2.0, 2.1 and 2.2. Product candidate 0.4.0-rc.1, wire
|
||||
payload v1, no tag.
|
||||
|
||||
Observed locally (no hosted result for the final heads yet):
|
||||
|
||||
- A focused build was **rejected** by analyzer MA0051 on `PrintWorker.ProcessJobAsync`
|
||||
(67 lines, maximum 60), caused by the new per-job phase-timing instrumentation.
|
||||
It was fixed by extracting `SubmitJobAsync`, `RequireCurrentPrinter`,
|
||||
`RequireSubmitAllowed`, `SubmitNativeAsync` and a nested `JobAttempt`, with no
|
||||
analyzer waiver. Reservation, staged-file and submission leases are still
|
||||
released inside the same catch, and the authority checks and state order are
|
||||
unchanged (reviewed by the coordinator).
|
||||
- The focused negotiation/runtime run then passed **16 of 16** with no warnings or
|
||||
analyzer errors. Core.Tests was not built locally (Defender quarantine unchanged).
|
||||
- The Roslyn token compare against the merge base found exactly the four intended
|
||||
semantic files changed and no fifth file.
|
||||
- Server: the merged candidate's full verify passed 189 reported / 188 executed /
|
||||
1 intentional opt-in skip / 0 failures, Checkstyle 0, after fixing a real
|
||||
lifecycle defect (realtime channel workers outliving the stopped host).
|
||||
|
||||
Pending, not claimed: hosted CI on the final signed heads (including Core.Tests and
|
||||
the MSI build), profile-selected physical output, and installed browser/private-callback
|
||||
sign-in against a published API 1.9+ server. The earlier plans for repeat Auth/S3
|
||||
qualification, ZPL test-print latency measurement and installer/MSI analysis were
|
||||
cancelled by the user and are not active work; the evidence recorded earlier in this
|
||||
file and in [UPGRADE-QUALIFICATION.md](UPGRADE-QUALIFICATION.md) is historical and kept.
|
||||
No 1.0 claim. See [RELEASE-READINESS.md](RELEASE-READINESS.md).
|
||||
|
||||
## Historical: final pin and release identity — 2026-11-01
|
||||
|
||||
The final protocol pin is `42c0d249f81395f00408ec0f92638dcbbf5deb03`
|
||||
([Gitea PR 2](https://git.kof22.com/QRun-IO/qqq-print-protocol/pulls/2)); root updated
|
||||
`.github/workflows/ci.yml` and the Gitea standards-exception (EX-0015) citation. The
|
||||
[standards PR 54](https://github.com/KofTwentyTwo/standards/pull/54) is recorded as
|
||||
merged after CI 777778 passed. The earlier pins (`a26c18c9…`, `df3729ac…`, `f3cbc02e…`)
|
||||
are historical evidence. Because a 0.4.0-rc.1 build is already installed locally and the
|
||||
updater needs a strictly newer semantic version, the candidate identity moves to
|
||||
**0.4.0-rc.2**: `VersionSuffix` and the `Build-Installer.ps1` default change, while
|
||||
`VersionPrefix`/ProductVersion stay 0.4.0 (the installer already allows same-version
|
||||
upgrades, so RC to RC upgrades in place). No behavior, dependency or lock change. The
|
||||
`ci.yml` release-version defaults are protected and are proposed as a patch for root
|
||||
review. Server strict full verify (R31) passed; the merged UI build and 35 paper/media
|
||||
tests passed locally. Hosted Windows CI and the update-feed handoff await the migration
|
||||
owner; nothing is installed or tagged.
|
||||
|
||||
## Historical: release cohort integration — 2026-11-01
|
||||
|
||||
Integration branch `release/printing-cohort-20261101` merges the completed C# source
|
||||
documentation cleanup (every type, method, constructor and non-auto property has a
|
||||
how/why header and the `.editorconfig` structural spacing, proven comment-and-blank-line
|
||||
only by the Roslyn token compare per batch) with the small test-print label change
|
||||
(4 × 6, 4 × 2 and 4 × 1 label stock at 203/300/600 dpi, job-only actual-size paper for
|
||||
short PDF labels, and the 2000 mm paper bound). The three merge conflicts
|
||||
(`PrintOptions.cs`, `TestPrintEditor.cs`, `TestPrintProfileTests.cs`) were resolved by
|
||||
keeping both: the new behavior and the headers. No behavior was rolled back.
|
||||
|
||||
Observed locally on the merged tree (R39): the production UI build under strict XML and
|
||||
analyzers passed with zero warnings, and the 35 existing paper/media tests passed.
|
||||
Core.Tests is hosted-only (Defender quarantine unchanged). The prior protected base
|
||||
`0336d5f` had 477 hosted tests; this head still needs a normal Gitea Core, CLI and build
|
||||
run. Pending: that CI run, installation of the new label implementation, and a
|
||||
small-stock paper test. The label implementation is **not installed** and has produced no
|
||||
physical output; the user's 4 × 6 stock is still loaded and unchanged. Native printing
|
||||
stays 2.3 with wire payload v1; the protocol pin awaits root's final commit. The existing
|
||||
Auth/S3 qualification is accepted and no new desktop or provider proof is claimed. The product stays
|
||||
0.4.0-rc.1, unreleased; no version bump or new updater design is part of the Gitea
|
||||
migration. Publishing and update-feed dependency: the AppKit updater reads the fixed
|
||||
GitHub release channel, so a Gitea move needs a decision on where releases are published
|
||||
before any update is offered from there.
|
||||
|
||||
## Candidate Echo media discovery — 2026-11-01
|
||||
|
||||
The isolated candidate implements `printer-media-v1`, machine-wide queue-default
|
||||
profiles, immutable media selection and pre-spool drift refusal. Selected PDFs
|
||||
use a driver-normalized job-only copy of the captured DEVMODE; RAW's physical-stock limitation is explicit
|
||||
in `docs/PRINTER-MEDIA.md`. Read-only native discovery produced a stable configured
|
||||
4 × 6 inch, 300 × 300 DPI profile across three helper launches. No live component
|
||||
was changed and no physical output was submitted.
|
||||
|
||||
Core/Windows/CLI and synthetic test projects compile without warnings. Seven
|
||||
initial adapter cases and one isolated-worker refusal case passed. Review added
|
||||
driver-normalized copies/scale overrides and effective DC geometry/DPI validation
|
||||
before StartDoc; all 24 focused Windows adapter cases now pass with zero build
|
||||
warnings. The original queue fingerprint remains unchanged, and the driver may
|
||||
update private settings only in the job's in-memory buffer. Unsupported override
|
||||
fields stay absent. A read-only probe of the corrected production adapter passed
|
||||
on the configured label driver, including its absent native-scale flag and an
|
||||
effective 1,200 × 1,800 pixel DC at 300 DPI, without StartDoc or queue changes.
|
||||
A Core run executed
|
||||
150 cases, with 147 passing (including the new media/worker cases) and three
|
||||
failing because the new worktree's linked fixtures were missing. The subsequent
|
||||
full rerun is blocked by local Defender quarantine of the Core test assembly;
|
||||
no protection changes, exclusions or quarantine restoration were performed.
|
||||
This is not a clean full-suite or release qualification. Parent review owns the
|
||||
security provenance investigation and the remaining server/hardware gates.
|
||||
The shared selection validator also enforces protocol IDs of at most 128 ASCII
|
||||
URL-safe characters, profile names of 1–512 characters and at most 32 profiles.
|
||||
New Core boundary regressions are present for hosted validation and were not
|
||||
locally compiled or run after the quarantine.
|
||||
Capability negotiation requires discovered stable printing 2.3+ within major
|
||||
two (2.2 is the rendering extension without media negotiation); older 2.0/2.1/2.2 servers retain the original three-capability HELLO. The real
|
||||
session/loopback-WebSocket compatibility tests cover same-session upgrade and
|
||||
downgrade, refreshing discovery once per socket (separate from initial sign-in
|
||||
discovery), with zero forbidden HTTP polls. The combined focused Windows gate
|
||||
passed 40 cases with zero build warnings/errors.
|
||||
|
||||
## Query in About — 2026-11-01
|
||||
|
||||
The shared AppKit About dialog now places Query and its public links in a compact
|
||||
two-column section just after the brand header. The original header logo/text
|
||||
are reparented into an Auto/Star Grid so long customer names wrap without
|
||||
clipping; identity, version, license and credits remain supplied by AppKit.
|
||||
The PNG is bundled unmodified with provenance on a 128-pixel white card.
|
||||
|
||||
The Release gate passes 426 tests (145 Core, 281 Windows/CLI), with zero build
|
||||
warnings/errors. The isolated native host passed image decoding, rendered
|
||||
contrast, initial mascot/link/name visibility, scrolling, keyboard focus and
|
||||
Close checks in both themes with a long synthetic customer name at observed
|
||||
125% DPI; full dialog captures verify the refinement. The private publish output contains
|
||||
the exact PNG, provenance and required WinUI resources. These About changes are
|
||||
not yet released or installed; the native host uses synthetic service responses.
|
||||
|
||||
## Published and installed 0.3.2 — 2026-11-01
|
||||
|
||||
[0.3.2-rc.1](https://github.com/QRun-IO/qqq-print-agent/releases/tag/v0.3.2-rc.1)
|
||||
is published from protected main `268f951b6728b0e69fedaf46769785c3f5ae55f4`.
|
||||
[Release workflow 41324312106](https://github.com/QRun-IO/qqq-print-agent/actions/runs/41324312106)
|
||||
completed all nine jobs. The signed tag, all four assets, checksums and GitHub
|
||||
provenance attestations were verified. Read-only MSI inspection passed for
|
||||
product version `0.3.2`, coherent app/service/CLI ProductVersion
|
||||
`0.3.2-rc.1+268f951b6728b0e69fedaf46769785c3f5ae55f4`, WinUI resources,
|
||||
service/callback registration and packaged notices. Published MSI SHA-256:
|
||||
`1191C337265469EB06136AF232DB57FAC6BC5014357521D80B35E5CCA5AF6E18`.
|
||||
It remains unsigned by the existing prerelease decision.
|
||||
|
||||
The actual AppKit 0.3.1-to-0.3.2 update completed with MSI exit 0. The user chose
|
||||
Help → Check for updates → Not now and confirmed continued responsiveness,
|
||||
then Update and restart. The companion automatically reopened, and the user
|
||||
confirmed Connected and both printers. Independent read-only observations
|
||||
verified all three installed executable hashes and full versions against the
|
||||
published MSI, the original companion/copied 0.3.1 helper handoff, an automatic
|
||||
LocalSystem service and restored WebSocket. All 38 earlier local and 37 earlier
|
||||
server job rows remained unchanged; one additional row in each view was
|
||||
accounted for separately. Native identity, pairing, exposure and profiles were
|
||||
preserved. The observers submitted no print jobs and did not retry the installer.
|
||||
|
||||
The diagnostic launcher's final summary failed after its child succeeded because
|
||||
it reopened stdout while holding its writer. The original failed record is
|
||||
preserved. Both original child reports passed and were independently revalidated,
|
||||
including their hashes and preservation comparisons; the launcher itself is
|
||||
not reported as passing. See [acceptance evidence](ACCEPTANCE.md).
|
||||
|
||||
Earlier, the published 0.3.1 MSI was installed with exit 0 and no reboot. App, service and
|
||||
CLI product versions exactly match source `346fc285198908c47a2ee9db7b9adb53d5e88c3c`.
|
||||
The service restored its native QQQ session and connected WebSocket. Pairing,
|
||||
printer exposure/profiles, log policy and all 28 existing local job receipts
|
||||
were preserved. A separate authenticated comparison proved that the original
|
||||
27 server jobs remained unchanged while new jobs arrived. The operator confirmed
|
||||
test prints and a responsive installed window.
|
||||
|
||||
The published 0.3.2 checks all three installed components and identical complete
|
||||
build metadata after MSI success. Focused red/green regressions cover missing,
|
||||
old, unreadable and mixed-source builds; 73 focused cases pass. The integrated
|
||||
426-test Release gate passes with zero warnings/errors/skips. The installed
|
||||
0.3.1 helper performed this transition; the new guard protects subsequent
|
||||
updates. Actual failed/canceled update, restart-required and reboot recovery
|
||||
paths remain unqualified. Prior paper confirmation remains specific to 0.3.1.
|
||||
|
||||
The native test host now matches production's PerMonitorV2 declaration while
|
||||
retaining asInvoker. Original 0.3.0 and then-current 0.3.1 UI replays passed at observed
|
||||
125% DPI, including repeated banner dismissal and printer status transitions.
|
||||
These results and operator acceptance do not prove the historical cause fixed.
|
||||
No speculative product layout change was made.
|
||||
|
||||
The repository-owned local Docker reference environment passed real Authentik
|
||||
login, permission checks, logout replay denial, server renewal after expiry and
|
||||
provider revocation denial using production client session code. This isolated
|
||||
proof uses unreleased QQQ API 1.9 candidate `ecf0f550` and an HTTPS probe callback,
|
||||
with trust confined to containers. Released RC.20 lacks the required native grant.
|
||||
Installed Windows browser/private-callback acceptance still needs a compatible
|
||||
published QQQ runtime and properly configured HTTPS provider; no installed OAuth
|
||||
or long-running production qualification is claimed.
|
||||
|
||||
## Installed realtime release and companion follow-up
|
||||
|
||||
All three 0.3.0-rc.1 releases are published from protected main. The Windows
|
||||
release at `213ba02769378a9f82881d7f0abd0012a8747e5c` passed 402 tests and
|
||||
the required build, packaging, security and provenance checks. The published
|
||||
MSI was installed with paired identity, history, printer choices, metadata and
|
||||
settings preserved; automatic restoration after a service restart passed.
|
||||
Fresh native QQQ laser PDF and Zebra ZPL tests reached SPOOLED. The pending
|
||||
Zebra PDF intent must not be confused with a submitted job or paper confirmation.
|
||||
|
||||
The operator then encountered a whole-window freeze after a successful test
|
||||
print. A captured AppKit log confirms a WinUI LayoutCycleException; the managed
|
||||
stack shows no blocked pipe call. Companion-only recovery restored navigation
|
||||
without restarting the service. Saving printer settings without changes also
|
||||
remained responsive. The exact layout trigger is still under investigation with
|
||||
an isolated, nonprinting native WinUI test host; no layout fix is yet claimed.
|
||||
|
||||
The active follow-up branch adds explicit WebSocket connection/traffic status
|
||||
and corrects startup-task identity comparison: Windows can return an account
|
||||
name for a trigger registered with a SID. Acceptance must resolve to that same
|
||||
SID, preserving all other ownership checks. The startup section controls the
|
||||
tray companion; the automatic background print service is independent.
|
||||
|
||||
The 0.3.1-rc.1 source gate passed 414 Release tests (145 Core, 269 Windows/CLI),
|
||||
12 headless presentation tests, and a zero-warning/error WinUI build. Branding
|
||||
dry-run and local MSI packaging also passed. The isolated native host passed
|
||||
the real expanded-row/dialog/timer/feedback/navigation flow, live meter decay,
|
||||
retained totals and the server-settings link using synthetic traffic only.
|
||||
The corrected startup validator also accepted the unchanged actual Windows task.
|
||||
|
||||
Independent review added a guard around native exception metadata access. The
|
||||
fatal-layout policy leaves AppKit's existing decision untouched if inspection
|
||||
fails; only the exact native LayoutCycleException permits normal termination.
|
||||
Native fatal-policy execution was verified on November 1 in a private, nonprinting
|
||||
host using the same policy source. An intentionally cycling native Panel raised
|
||||
the actual LayoutCycleException: AppKit logged it and set Handled=true, the policy
|
||||
set Handled=false, and WinUI terminated the diagnostic process naturally without
|
||||
a timeout. The host ran asInvoker in the actual desktop user context, with no
|
||||
Windows elevation or installed-state changes. This establishes the handler order
|
||||
and fatal outcome only; the original post-print trigger remains unreproduced.
|
||||
A second private nonprinting run used protected, authenticated native QQQ
|
||||
presentation data for the two current printers and 27 jobs. The real dialog,
|
||||
five-second refresh, simulated confirmation, feedback and navigation passed at
|
||||
a 1084 by 721 client viewport with scale 1. It used no service IPC or printing.
|
||||
Local unexposed queues, original timing and incident geometry were unavailable;
|
||||
authentication, transport and contact time remained explicitly synthetic. This
|
||||
passing partial replay does not establish that the original cause was fixed.
|
||||
Experimental probe modes remain excluded from the committed regression host.
|
||||
The maintainer accepted the exact Microsoft SDK closure on November 1.
|
||||
[EX-0014](https://github.com/KofTwentyTwo/standards/blob/fbfc8d2cf3b5e16ae9750b04cf9de1794f1e7152/exceptions/register.md#ex-0014)
|
||||
merged through the protected standards PR after its checks passed. The client
|
||||
allowance retains exact inventory, notice and payload guards, adds an inclusive
|
||||
April 30, 2027 UTC expiry, and passes 31 focused guard tests. Other license and
|
||||
security checks remain enabled. Publication, installation and actual in-app
|
||||
update acceptance of 0.3.1 remain pending.
|
||||
|
||||
The candidate notes below preserve the implementation history.
|
||||
|
||||
## Realtime and Jobs UI source — 0.3.0-rc.1 release candidate
|
||||
|
||||
Current source adopts printing extension 2.0 and immutable protocol commit
|
||||
`df3729ac632d4a34a3fb8423acef465042a624fc`: client-initiated authenticated WSS,
|
||||
direct controls/events/receipts, event-driven finite claim drains and independent
|
||||
streamed HTTPS content. No job/control polling fallback is permitted. Complete
|
||||
server policy includes configurable document, copy, queue, concurrency, bandwidth,
|
||||
liveness and timeout limits, including native submission. README and current
|
||||
architecture/operations guides distinguish this source from published 0.2.
|
||||
|
||||
Jobs UI changes add inline expansion and reject stale detail completions across
|
||||
collapse/reopen, filtering, paging, navigation and closing. Focused Debug x64
|
||||
application and UI-test builds passed with zero warnings/errors using existing
|
||||
project references; three headless tests of the actual generation tracker passed.
|
||||
Desktop assertions were compiled, not executed. Full coordinated consumer and
|
||||
installed realtime acceptance remain separate; no runtime or physical printing
|
||||
was performed by this documentation/UI lane.
|
||||
|
||||
The 0.2 and earlier entries below retain their original checkpoint wording and
|
||||
test counts; they are not current realtime publication or deployment claims.
|
||||
|
||||
## Installed published 0.2 happy path — user confirmed
|
||||
|
||||
The published 0.2 MSI installed with pairing, printer exposure and journal history
|
||||
retained. Native QQQ table-based sign-in, existing-device association, all four
|
||||
dispatch/connection actions and inventory refresh succeeded. The user confirmed
|
||||
the Letter PDF and 4 × 6-inch Zebra ZPL printed correctly and manually confirmed
|
||||
the app's Connected footer and both printers. Restart elevation was canceled
|
||||
before execution. This is local 0.2 evidence; no installed 0.3 realtime/Jobs UI,
|
||||
Authentik renewal or remote-production acceptance is inferred.
|
||||
|
||||
## Explicit credential and pairing recovery — not released
|
||||
|
||||
Latest isolated gate: **365 tests (127 Core + 238 Windows/CLI)**, zero warnings/errors/skips, including the final brand-neutral UI. Evidence: `pending-setup-verify.log`, `TestResults/verify-073522764d7e43eaaab76bab59199907`. Pending unbound sign-in now survives restart when the retained device proof is unreadable or belongs to another server, without replacing that file or allowing claims. Bound saved identities still fail closed for either condition before creating a network client. Both pending cases were reproduced before correction; successful explicit enrollment and preservation of old journal/exposure are covered. Earlier gates below remain historical checkpoints; no installed state or printers were touched.
|
||||
|
||||
The isolated recovery follow-up passes the full solution/UI gate: **360 tests (127 Core + 233 Windows/CLI), zero warnings/errors/skips**. Evidence: `recovery-structure-verify.log` and `TestResults/verify-4f3b5f3febf64e90bf48bd45cbbf4b4e`. Both original failures were first reproduced: unreadable QQQ session data prevented re-login, and unreadable device proof prevented sign-in before enrollment. Fresh authenticated sign-in now permits recovery, preserves unreadable ciphertext, and still requires server-authoritative device binding or explicit new enrollment. Denied binding leaves the original data untouched. Decryptable but structurally invalid session data is also rejected and recoverable; stored origin and identity fields are validated before use. Sign-out and read-only status remain usable; scoped journal and printer exposure are retained. This is synthetic verification only, with no installed-state changes or physical printing. The preceding 356-test candidate remains historical evidence.
|
||||
|
||||
The revoked-pairing follow-up now passes **361 tests (127 Core + 234 Windows/CLI)** with zero warnings/errors/skips: `new-pairing-verify.log`, `TestResults/verify-c27f72e1913549f88eb48f47135e4863`. A standard three-choice pairing selector keeps reuse as the default and adds explicit replacement setup. Saved unbound sign-in survives restart without presenting old revoked proof or claiming jobs. A denied default binding or rejected enrollment preserves old configuration; successful enrollment uses a new journal scope and preserves exposure/history. Final brand-neutral label edits passed a separate UI build in `new-pairing-ui-labels.log`; runtime and test sources were unchanged. UI automation was compiled, not executed against an installed application.
|
||||
|
||||
## Isolated remote-control implementation — not released
|
||||
|
||||
The device-controls worktree adds independent control polling, persisted desired dispatch/connection state, connection-scoped command receipts and verified single-job spool cancellation. Pause stops new claims; administrator disconnect keeps control polling and existing print-event delivery alive while suppressing ordinary synchronization. Reconnect does not restart Windows, the service or an in-flight print. Authorization failure requires explicit local recovery and never erases the print journal. The companion displays desired state, control contact and the last remote action/outcome.
|
||||
|
||||
The reviewed isolated solution/UI build passed without warnings or errors, and all **279 tests (72 Core + 207 Windows/CLI)** passed without skips. Verification evidence is in `TestResults/verify-211a2eed18b04373858451e6a1f59070`; the command used `build/Verify.ps1 -ProtocolFixtures` with the coordinated protocol worktree. Tests cover blocked printing, disconnect/reconnect, lost receipt and native cancellation responses, duplicate delivery, interrupted execution, expiry, ownership, revision rollback, authorization denial, legacy negotiation and receipt retirement. Independent review identified two corrected contract issues: generated receipts now use literal `Z` UTC timestamps, and omitted desired-state fields cannot silently resume dispatch. No installed service, live server, printer or enrollment has been changed by this work.
|
||||
|
||||
Native QQQ authentication integration now passes the combined solution/UI gate: **356 tests (127 Core + 229 Windows/CLI), zero warnings/errors/skips**. Evidence is in `TestResults/verify-01fc65d1e3d742ceac9b69463a75b555` and `native-auth-verify-final.log`. Independent source review findings were corrected and rechecked: malformed input/timeout handling, session-generation races, constructor-failure gate release, installed callback location and visible browser cancellation. Runtime tests also cover temporary resume failure recovery and pre-enrollment session restoration.
|
||||
|
||||
The actual packaged Core client also passed **23 interoperability checks** against a disposable native QQQ server with table-based authentication: discovery, sign-in, enrollment/binding, session resume/restore, pause/replay/observed polling, anonymous refusal, logout and old-cookie refusal. No print jobs or printers were involved. The unsigned candidate MSI built and passed version/resource/registry/service inspection. Neither proves an installed callback, real Authentik deployment or indefinite session renewal.
|
||||
|
||||
The implementation includes discovery-first sign-in, protected service session storage, periodic standard resume, authoritative principal/tenant/device checks, explicit legacy-device association, and native printing transport. Native control 404 cannot fall back to private bearer routes. Settings exposes sign-in/sign-out and current identity; the installed private-scheme callback forwards only to the active companion attempt, where Core validates PKCE/state. Normal CLI commands use the service; direct bearer diagnostics require explicit `--legacy-compat`. See [QQQ sign-in](QQQ-SIGN-IN.md) for setup and remaining installed/provider qualifications. The preceding 279-test gate is historical controls-only evidence. Barcode diagnostics are explicitly outside this printing change.
|
||||
|
||||
## Published 0.1.9-rc.1 — 2026-10-31
|
||||
|
||||
[v0.1.9-rc.1](https://github.com/QRun-IO/qqq-print-agent/releases/tag/v0.1.9-rc.1) is published from protected main revision `cf0e362`, following the audit merge. [Release workflow 41190815995](https://github.com/QRun-IO/qqq-print-agent/actions/runs/41190815995) passed; all four assets, their checksums/digests and their build provenance attestations were verified. The MSI remains unsigned.
|
||||
|
||||
The exact CI installer from reviewed source `13aa84c` completed with MSI exit 0 and no restart requirement. Both installed management peers authenticated, protected credentials and journal history were preserved, and the service was confirmed running and connected. All **16 installed UI checks passed in one run**, and the companion opened successfully. No physical printing was requested. The source gate passed **255 tests (66 Core + 189 Windows/CLI)** with zero warnings/errors and none skipped; all ten required hosted checks passed. The installed CI MSI and published release MSI have different hashes. Runtime sources are unchanged, but no separate installation of the release MSI is claimed. See [artifact hashes and acceptance scope](ACCEPTANCE.md).
|
||||
|
||||
Local QQQ integration was verified with preserved pairing and history. Remote deployment, production S3/IAM, Windows reboot/recovery, real updater handoff, hostile-tree installer rollback and publisher signing remain separate qualification work. Historical physical output below does not establish new 0.1.9 hardware acceptance.
|
||||
|
||||
## Historical pre-install 0.1.9 checkpoint — 2026-10-31
|
||||
|
||||
The original upgrade installed 0.1.8 with MSI exit 0 and no restart requirement. Credentials and the journal were retained; both the old and new installed management peers authenticated. A later history query failed because the service disconnected before the client read the complete response. Unassigned helper fields did not establish a disconnected service or missing printers; independent server inspection confirmed service health and no pending or uncertain work.
|
||||
|
||||
The failure was reproduced on an isolated random pipe using the actual runtime with fake printers and no network/configuration. All eight delayed-reader cases failed before the fix and passed with the bounded client-close wait. Permanent tests cover current/legacy readers, success/error responses, subsequent clients, deadline expiry and runtime shutdown. The correction preserves the wire format and existing deadlines. Independent source review found no concrete issue. The isolated combined 0.1.9 solution/UI build passed with zero warnings/errors and **255 tests (66 Core + 189 Windows/CLI), none failed or skipped**. Source and protocol fixtures remained byte-identical after verification. PowerShell analysis, packaging-input validation, workflow lint and changed-document lint also passed. Hosted and installed qualification were pending at this historical checkpoint; their completed results are recorded above.
|
||||
|
||||
The related server review completed its approved H2 license record and [standards configuration repair](https://github.com/KofTwentyTwo/standards/pull/54). The local database cutover subsequently preserved pairing and history. This work did not provision a remote cloud/S3 deployment or qualify new physical output.
|
||||
|
||||
## Historical audit candidate 0.1.8-rc.1 — 2026-10-30–31
|
||||
## Previous audit candidate 0.1.8-rc.1
|
||||
|
||||
Independent baseline scan and fresh source review are complete. The Windows fixes authenticate the installed pipe peer before sending commands, retain pipe ownership, reject unsafe machine state across all privileged entry points, and protect startup task definitions. Reviewer and packaging findings were corrected. The isolated full gate passed **249 tests (66 Core + 183 Windows/CLI), zero warnings/errors/skips**; updated installer sequencing passed its focused regression. All 12 PowerShell tests and all 75 analyzer rules passed.
|
||||
|
||||
The unsigned CI candidate MSI SHA256 is `CB5C2F6F17246C6DC3FD3D746B9FC82D47AE956940F67A4697CFD7677B3D40B9`, from passing build `41151199441` at source `2e6a2e5`. Every required build, security, CodeQL, script and PR check passed. Actual Windows Installer safe-session formatting and sequence inspection passed; all 995 surviving file targets retain their component identities and key-path roles versus 0.1.7. No installer actions were executed by those inspections. This CI artifact supersedes earlier local candidate hashes.
|
||||
|
||||
At this checkpoint the published baseline was **0.1.7-rc.1**; 0.1.8 was an audit candidate and was superseded before publication. Its local installation and incomplete post-install check are recorded above. Its helper requested no physical printing and did not run desktop qualification. The later 0.1.9 audit merge, publication and installed UI results supersede that pending work; hostile-tree rollback, actual updater handoff, reboot/recovery and remote deployment remain unqualified. See [audit evidence](AUDIT-2026-10-30.md) and the reviewed [workflow compatibility decision](CI-COMPATIBILITY.md).
|
||||
The public baseline remains **0.1.7-rc.1**. The local 0.1.8 installation and its incomplete post-install check are recorded above; no audit merge or release is claimed. Its helper requested no physical printing and did not run desktop qualification. Positive installed peer authentication passed; hostile-tree install/rollback, actual updater handoff, current UI/reboot/recovery and remote deployment remain unqualified. See [audit evidence](AUDIT-2026-10-30.md) and the reviewed [workflow compatibility decision](CI-COMPATIBILITY.md).
|
||||
|
||||
Retained originals and printing delivery copies have separate storage and retention; their typed integration remains pending.
|
||||
User authorization covers audit commits/pushes and deployment; required main-branch checks apply to administrators too. Master coordination is active at `R:\agent-comms\qqq-cloud-printing.md`, acknowledged by Record Files and Mobile Scanner. Each master owns its repositories and services. Retained originals and printing delivery copies have separate retention/buckets; their typed integration remains pending.
|
||||
|
||||
Additional synthetic storage qualification used the packaged 0.1.8 implementation at 375,000 jobs and 1,109,254 events. All sampled totals/page bounds and SQLite integrity checks passed. Appending 10,000 jobs through production journal APIs took 210 seconds using one store connection; first/final 50-row pages measured 67/165 ms medians, while ordinary page allocations remained about 71–83 kB. Retention removed exactly 250 jobs' detail in 10 ms, retaining summaries. This is local storage/query evidence, not CI-MSI binary identity, service scheduling, GUI or physical throughput qualification. See [method and limits](SCALABILITY.md). Installation/release guidance now distinguishes updater SHA-256 checks, current workflow provenance attestations and unsigned MSI publisher identity; older releases are not retroactively attested.
|
||||
|
||||
## Historical 0.1.7 publication and physical acceptance — 2026-10-30
|
||||
## Previous checkpoint: 0.1.7 published; laser, ZPL and corrected PDF output confirmed
|
||||
|
||||
Installed **0.1.7, source 93dd5fc**, completed with MSI exit 0 and no reboot, retaining credentials. Management, computer profile, paged history, log settings, branded shortcut and connected-state checks passed. The source gate passed **227 tests (57 Core + 170 Windows/CLI)** with zero warnings/errors; [exact-source CI 41139885687](https://github.com/QRun-IO/qqq-print-agent/actions/runs/41139885687) passed. All **16 installed UI checks passed in one run**, including the diagnostic media/DPI dialog, which was closed without printing during the UI test.
|
||||
|
||||
@@ -503,9 +92,3 @@ The corrective 0.1.2 source passed 102 tests and built an unsigned MSI; its UAC
|
||||
Earlier development and temporary installed-service laser pages were confirmed by the user. No fresh physical print has been performed for the latest corrections. Zebra is deferred. Reboot/sign-in/recovery, real update cancellation/relaunch and publisher signing remain pending. Do not report a canceled/pending elevation as a completed upgrade.
|
||||
|
||||
QQQ `qbit-printing` 0.1.1-rc.1 verification passed **19 tests with zero Checkstyle violations**, including native record/table job controls. Synthetic Windows update/native-child tests do not invoke an installer or access physical printers.
|
||||
|
||||
## Definitive realtime source verification — 2026-10-31
|
||||
|
||||
Product0.3.0-rc.1 requires native printing API2.x (framework/wire/subprotocol remainv1), pinned shared contract df3729ac632d4a34a3fb8423acef465042a624fc. Locked restore and entire Release solution build passed with zero warnings/errors. Definitive fulltests399PASS:140Core+259Windows/CLI. Earlier UIbuilds and three headless detail-generation regressions passed; no automated desktop acceptance is claimed.
|
||||
|
||||
Actual native-session WebSocket runtime tests cover stalled25MiB transfers with concurrent controls, exactACK replay/reconnect with no duplicate synthetic submission, stickyCLAIMED admission held throughRECEIVED commit, per-printer order/different-printer parallelism, aggregate bandwidth, live concurrency/limits/deadlines, policy/auth generation fences and startup unreadable-credential recovery with a functioning synthetic management pipe. Actual.NET/Java API2 integration separately passed13 checks using this unchanged ReleaseCore, including25MiB verifiedstream, replacement, receipt replay and sign-out denial. Protocol71definitions/73fixtures and server118tests pass. Current installed0.2 remains unchanged. Package/hostedCI/deployment and physicalqualification for0.3 remain separate; prioruserconfirmed0.2 outputs are not0.3 evidence.
|
||||
@@ -1,38 +0,0 @@
|
||||
# C# source header checkpoint
|
||||
|
||||
The 2026-11-01 review of baseline `268f951b6728b0e69fedaf46769785c3f5ae55f4`
|
||||
identified 127 of 221 tracked, repository-owned C# files without a copyright
|
||||
header. Those files now carry the existing `Copyright (c) 2026 James Maes` and
|
||||
`SPDX-License-Identifier: MIT` notice from this repository's LICENSE. Existing
|
||||
copyright notices were preserved; one existing SPDX marker's casing was corrected.
|
||||
Vendor notices and generated files were not rewritten.
|
||||
|
||||
This addresses KofTwentyTwo K22-CODE-24, which recommends source license headers
|
||||
outside Java. The native .NET IDE0073 analyzer now enforces this repository's
|
||||
header through `.editorconfig` and the existing warnings-as-errors build. No
|
||||
workflow, dependency or application behavior was changed. Three existing pairs
|
||||
of namespace imports were also reordered to satisfy the targeted formatter.
|
||||
|
||||
Validation:
|
||||
|
||||
- All 221 tracked C# files have the canonical header.
|
||||
- Roslyn token kind, original token text and value text are identical for all
|
||||
128 header/marker edits, before the separate import corrections. Each of the 127 additions also preserves the original
|
||||
source text exactly after the prepended comment. This is source-token
|
||||
equivalence, not a claim of byte-identical PDBs or assemblies.
|
||||
- Release solution build passed with zero warnings and errors.
|
||||
- The separate layout-test host also compiled with zero warnings and errors;
|
||||
it was not launched.
|
||||
- A deliberate missing-header case failed with IDE0073; restoring the exact
|
||||
source made the build pass. No application or printer operations were run.
|
||||
- `git diff --check` passed.
|
||||
|
||||
The read-only `dotnet format style --diagnostics IDE0073 --verify-no-changes`
|
||||
command also checks imports. It initially reported three existing import-order
|
||||
differences in `AgentRuntime.Controls.cs`, `AgentRuntime.RealtimeStatus.cs`, and
|
||||
`PrinterWorkerIsolationTests.cs`. Each correction swaps only two adjacent,
|
||||
ordinary namespace imports. A separate comparison confirms the same import
|
||||
multiset and identical remaining source text. The targeted command then exited
|
||||
successfully; it emitted a workspace-loading warning. This filtered check does
|
||||
not claim full formatter coverage. The full solution was rebuilt after the
|
||||
import corrections.
|
||||
@@ -1,17 +0,0 @@
|
||||
# Owned source notice check
|
||||
|
||||
Run these commands from the repository root with the existing Python 3 interpreter:
|
||||
|
||||
```text
|
||||
python3 .github/scripts/test-source-headers.py
|
||||
python3 .github/scripts/check-source-headers.py
|
||||
```
|
||||
|
||||
The standard-library checker enforces the scope of the reviewed 2026-11-01 header pass, not an estate-wide licensing or formatting audit. `.github/source-headers.json` names the owned source/config path families, comment syntax, accepted holder/license pairs and explicit exclusion reasons. Python `fnmatch` patterns match slash-containing relative Git paths; new files in those families are covered after they are tracked. Empty selections fail. The checker does not scan untracked build output or modify files.
|
||||
|
||||
Only leading language comments count. Copyright text in a string, Python docstring or comment after code is rejected. UTF-8 BOMs, initial shebangs, PowerShell `#Requires` directives and XML declarations are handled before the notice. These declarations cannot be displaced beneath a new notice. PowerShell block comments are recognized only for PowerShell files. Existing years and holders are not rewritten. Complete canonical Apache notices are valid without redundant SPDX; Java still requires the full Apache block. A contradictory SPDX identifier fails.
|
||||
|
||||
JSON/schema/fixture/lock data, explicit generated output directories, vendor legal assets and upstream Maven wrappers are excluded with reasons in the policy. Solution/activation/test-runner metadata and `.editorconfig` remain outside this completed pass; their applicable root LICENSE/NOTICE remains authoritative. No broad claim about third-party licensing follows from this check. New owned file types or provenance must be reviewed before changing the allowlist; do not add blanket exclusions to make a failure disappear.
|
||||
|
||||
The implementation and its negative tests are intentionally maintained copies across the three printing repositories, with each repository's own copyright/license header and independently reviewed scope. They do not fetch policy or execute source. CI invokes them in existing jobs using the runner's available Python, with no new package or workflow context. Existing native C# IDE0073 and Java Checkstyle conventions remain unchanged.
|
||||
This client accepts James Maes / MIT in its reviewed source/build/config families and preserves QRun.IO, Inc. / MIT solely in tools/virtual-agent. The existing scripts / virtual-agent job runs the guard.
|
||||
+9
-149
@@ -1,154 +1,17 @@
|
||||
# TODO
|
||||
|
||||
## Released: 1.2.1 — 2026-11-06
|
||||
|
||||
Client 1.2.1 (source `3b9d75d`, GitHub release run 42223525626) is the current stable: signed generic and GG Forge installers on GitHub and, byte-identical, on Gitea. See [RELEASING](RELEASING.md).
|
||||
|
||||
- [x] Nonce fix PR 11 (`abc3d0d`) and the OPTIONAL/discovery nonce change (`c59814d`) shipped in `v1.2.0`/`v1.2.1`.
|
||||
- [x] Release run 42128511730 on `v1.2.0` failed in `sign (gg-forge)`: `release.yml` array-splatted `-Edition`, binding it positionally to `-CertificateThumbprint`. Fixed in PR 12 (`3b9d75d`); `v1.2.0` stays immutable and unpublished.
|
||||
- [x] `v1.2.1` tagged on the merge commit, mirrored to GitHub, signed, assembled and published; checksums, signatures and provenance verified; same assets attached to the Gitea release.
|
||||
- [x] Post-merge main checks (ci, codeql, security, scripts, scorecard) green on `b583130`.
|
||||
- [ ] Actual native sign-in/sign-out acceptance against the shared provider (the shared-fixture discovery pass is not acceptance).
|
||||
|
||||
## Historical: required-nonce native sign-in fix — 2026-11-05 (published in 1.2.x)
|
||||
|
||||
The stable printing release below remains accepted historical evidence. The shared-server scanner Authentik requires this fix (`fix/native-login-required-nonce`, integrated on main `f954f11`).
|
||||
|
||||
- [x] Implement per-attempt nonce kept only under `REQUIRED`, sent as `expectedNonce`; legacy four-field body preserved; unknown policy refused before provider/browser.
|
||||
- [x] Root verified exact native callback registrations and real server HTTPS discovery in an isolated shared scanner/Printing 1.0.0 fixture with `REQUIRED` nonce (discovery only, not login proof).
|
||||
- [x] Integrated NativeCI Release build: zero warnings/errors; 352 Windows/CLI tests passed with no failures/skips; source notices passed for 300 tracked files. Existing method-length limit retained; Core.Tests excluded locally.
|
||||
- [x] Hosted CI including Core.Tests: GitHub CI on the editions branch carrying this fix passed 182 Core and 352 Windows/CLI tests (run 42078731426, 2026-11-05).
|
||||
- [ ] Real shared-provider native login acceptance.
|
||||
- [x] Final published build: 1.2.1 (see above).
|
||||
|
||||
## Closed product release — 2026-11-04
|
||||
|
||||
- [x] Publish signed Windows 1.0.1 on Gitea and the GitHub updater feed; release run 41532214447 passed its gates and Azure OIDC signing.
|
||||
- [x] Verify release assets, signatures and provenance; install the official MSI locally. November 3 receipt: exit 0, matching app/service/CLI 1.0.1, service Running.
|
||||
- [x] Publish qbit-printing 1.0.0 and protocol 1.0.0 with QQQ 4.1.0-RC.21 native sign-in support.
|
||||
- [x] Refresh current README, operator and maintainer documentation against the stable source; preserve dated evidence.
|
||||
|
||||
The requested product work is complete. Shared CI migration is separate. Everything below is historical or unscheduled backlog; unchecked boxes do not reopen work or authorize more tests. See [Release readiness](RELEASE-READINESS.md).
|
||||
|
||||
## Documentation publication scope
|
||||
|
||||
The user authorized publishing `docs/printing-release-closeout-20261104` through a normal Gitea PR, including its automatic Microsoft-hosted checks. The previous publication hold is superseded for that scope. No code or workflow change, local/VM6218 build, quarantine restoration or protection exception is part of this update. The PR records publication and merge status.
|
||||
|
||||
## Historical stable 1.0 checkpoint — 2026-11-02
|
||||
|
||||
Active stable-release work is only the two open items below. Every other unchecked item in this file is historical or unscheduled backlog, not a stable-1.0 blocker.
|
||||
|
||||
- [x] Official 0.4.0-rc.4 installed (all three components); normal MSI upgrade exit 0 and the service Running.
|
||||
- [x] Clean hosted Windows CI run 41442796961 on source `53fe1b8281806eda7adc314f92c8205aefcb51ce`: 499 tests (166 Core + 333 CLI), zero failures and skips; build and MSI zero warnings and errors. Core.Tests is never built locally; this hosted pass is its evidence. (Earlier run 41384467500 on `b5eb5d73` is historical.)
|
||||
- [x] Stable signing implemented (workflow, `Sign-Release.ps1`, packaging). All 19 first-party binary copies of an installed RC4 payload, including `Cli/qqq-print-agent.dll`, and a disposable official RC4 MSI were Azure-signed and strictly verified; this is a local administrator proof and the new CI OIDC identity is not yet exercised. Installed and published remains RC4; no new stable tag.
|
||||
- [x] Primary Gitea feed and public feed carry all three prereleases (Windows 0.4.0-rc.4; server and protocol 0.4.0-rc.1); nine assets checked and provenance verified.
|
||||
- [x] Physical 4 × 1 passed by the operator on RC3 (same relevant printing runtime); 4 × 6 and Letter accepted earlier. Physical 4 × 2 is deferred by the operator and is not a stable blocker.
|
||||
- [x] Source-header inventory (289 tracked files, 231 C#) reported zero issues.
|
||||
- [ ] Windows release branch (Gitea PR 2): normal protected merge, awaiting the central native 1725 repair for Windows ACL and file sharing on Linux.
|
||||
- [ ] Supported, published QQQ core with native session login (the last official release, RC20, does not have it); stable tag publication, including the first CI OIDC signing run, follows it.
|
||||
- Accepted known limitation (user decision 2026-11-02, not a blocker, not fixed): the post-print native UI layout exception; see the historical entries below.
|
||||
- Cancelled by the user, do not resume: repeat Auth/S3 qualification, the latency investigation and MSI comparison analysis.
|
||||
|
||||
## Historical rc.3 status (superseded by rc.4 and the closeout above)
|
||||
|
||||
- [x] Implement ordered numeric FileVersion (rc.N revision N, stable 65535) in packaging; source `e10d251`, packaging-input checks and rc.3 production packaging passed (all payloads `0.4.0.3`, `0.4.0-rc.3+e10d251`).
|
||||
- [x] Complete the local rc.3 installation: normal MSI upgrade exit 0; app, service and CLI match rc.3 and numeric file version `0.4.0.3`, with no repair required.
|
||||
- [x] Confirm the 4 × 1 label prints correctly after media alignment; operator reports it printed perfectly.
|
||||
- [ ] Physical 4 × 2 test deferred by the operator, who chose to keep 4 × 1 loaded. The test option is implemented; do not send another label until requested. Not a stable blocker.
|
||||
- [x] Gitea release artifact and update feed: published for rc.4 (see the closeout above). Shared Windows CI remains the active protected-merge item; no GA claim. Core.Tests is not run on this host (including Gitea runner 6).
|
||||
|
||||
## Script quality gates
|
||||
|
||||
- [x] Pin Ruff, strict Pyright, ESLint/Stylistic and strict checkJs with locked restores; reject untracked-scope Python/JavaScript and zero-file Pyright runs; negative tool probes pass locally; virtual-agent Downloads/identity behavior preserved.
|
||||
- [ ] Observe the new `virtual-agent` job steps pass on hosted CI before relying on them.
|
||||
|
||||
## Candidate Echo printer media
|
||||
|
||||
- [x] Discover truthful machine-default dimensions/DPI and expose an opaque, revision-bound profile.
|
||||
- [x] Reject stale/unknown selection before spool; pass captured validated defaults to selected PDF DCs.
|
||||
- [x] Normalize supported job-only driver copies/scale and verify effective DC dimensions/DPI before StartDoc (24 focused Windows tests plus read-only actual driver/DC probe).
|
||||
- [x] Verify synthetic 4 × 1 / 4 × 2 / 4 × 6 profiles, driver-private drift, unknown DPI and isolated-worker refusal.
|
||||
- [x] Verify configured 4 × 6 / 300 DPI fingerprint stability across three read-only helper launches.
|
||||
- [x] Complete the C# source standards cleanup (how/why headers and structural spacing) and merge it with the short-label change; token-compared as comment/blank-line only per batch.
|
||||
- [x] Merged integration tree: production UI build (strict, 0 warnings) and the 35 existing paper/media tests passed locally (R39).
|
||||
- [x] Hosted CI passed (499 tests, run 41384467500), the label implementation is installed in rc.4, and the 4 × 1 stock printed correctly (4 × 2 deferred, not a blocker). Earlier text here said "not installed yet"; that is historical.
|
||||
- [x] Local Core test-assembly quarantine: not pursued. Core.Tests is never built locally; the clean hosted pass is the evidence and no protection was disabled.
|
||||
- [ ] Qualify the matching server/consumer catalog, immutable selection and authorized retained-document submission.
|
||||
- [ ] Perform separately authorized installed/profile-selected physical acceptance; available alternative stock is not current queue configuration.
|
||||
|
||||
## Query in About
|
||||
|
||||
- [x] Place the official mascot and dogfooding/Query links directly below the
|
||||
shared About header, preserving customer logos, identity and credits.
|
||||
- [x] Verify both native themes, initial image/link visibility, unclipped names and
|
||||
Close; pass the 426-test Release gate and exact publish-payload asset check.
|
||||
- [ ] Package, publish and verify the About change in an installed follow-up.
|
||||
|
||||
## Companion layout, live transport status and startup follow-up
|
||||
|
||||
- [x] Install the attested published 0.3.1 MSI; verify all three exact component versions, automatic WebSocket restoration and preserved local receipts, pairing and profiles.
|
||||
- [x] Record operator-confirmed test prints and responsive installed 0.3.1 window; verify repeated native dialog/refresh/banner/status replays at observed 125% DPI.
|
||||
- [x] Reject a successful MSI outcome when the app, service or CLI has a missing, old or different full build version; pass the integrated 426-test gate.
|
||||
- [x] Publish [0.3.2-rc.1](https://github.com/QRun-IO/qqq-print-agent/releases/tag/v0.3.2-rc.1); verify all nine [release jobs](https://github.com/QRun-IO/qqq-print-agent/actions/runs/41324312106), four assets/attestations and static MSI version, resources, service/callback registration and notices. The MSI remains unsigned.
|
||||
- [x] Qualify the actual AppKit 0.3.1-to-0.3.2 update: operator-confirmed Not now/responsiveness, Update and restart, verified old-helper handoff, MSI exit 0, exact published component bytes, preserved identity/profiles/earlier jobs, restored WebSocket and automatic visible reopen.
|
||||
- [x] Pass isolated real Authentik native-session login, permission, logout, expiry/renewal and revocation checks with production client code against unreleased QQQ API 1.9 candidate `ecf0f550` in the local Docker reference environment.
|
||||
- [ ] Qualify the installed Windows browser/private callback against a compatible published QQQ runtime and configured HTTPS provider; the container HTTPS callback does not establish this installed flow.
|
||||
- [x] Publish and verify all three 0.3.0-rc.1 releases; install the matched local server/client and verify retained state and service restart recovery.
|
||||
- [x] Capture the operator's post-print LayoutCycleException and recover only the companion; retain existing print receipts.
|
||||
- [ ] Native post-print layout cycle: reproduce and fix with a nonprinting host. **Accepted known limitation for 1.0 (user decision 2026-11-02): not fixed and not a blocker.** Left unchecked as history.
|
||||
- [x] Verify actual native fatal-layout exception logging, handler order and natural diagnostic termination; keep this mitigation distinct from fixing the original trigger.
|
||||
- [x] Accept scheduler-normalized account names only when they resolve to the exact expected startup SID; verify rejection of other identities and the unchanged actual task.
|
||||
- [x] Show explicit WebSocket state, server endpoint, live upload/download rates and service-lifetime application-traffic totals in the footer; verify actual native presentation with synthetic traffic.
|
||||
- [x] Preserve the original diagnostic launcher's finalization failure and independently validate both passing child reports; no installer retry or observer print was needed. Keep 0.3.1 physical acceptance separate.
|
||||
|
||||
## Realtime and Jobs UI — 0.3.0-rc.1 release candidate
|
||||
|
||||
- [x] Adopt protocol commit `df3729ac632d4a34a3fb8423acef465042a624fc` for printing extension 2.0 and its complete configurable policy.
|
||||
- [x] Update current architecture/operations documentation for WSS, streamed HTTPS, administrator limits and bounded queue observations; preserve published 0.2 evidence.
|
||||
- [x] Compile Jobs UI and UI tests without warnings; pass three headless stale-detail generation regressions.
|
||||
- [ ] Complete combined source and independent runtime review gates, including stalled-transfer controls, ordering, lost ACKs and reconnect recovery.
|
||||
- [ ] Qualify installed realtime service/UI, configured provider renewal and physical output separately; no source check implies those results.
|
||||
|
||||
The following entries preserve earlier implementation checkpoints.
|
||||
|
||||
## Remote controls candidate — not released
|
||||
|
||||
- [x] Restore pending unbound setup across restart with unreadable or different-server old proof; preserve bound-identity refusal. Final isolated gate: 365 tests, zero warnings/errors/skips.
|
||||
|
||||
- [x] Add explicit replacement pairing after revocation, retain pending unbound sign-in across restart, and verify rejected setup preserves old state; 361-test full gate and final brand-neutral UI build pass.
|
||||
|
||||
- [x] Reproduce unreadable session/device proof recovery failures and pass explicit recovery, denied binding, sign-out and preserved-journal regressions; full isolated gate now 360 tests with no warnings/errors/skips.
|
||||
|
||||
- [x] Implement independent bounded control polling and persisted pause/disconnect state without interrupting active print submission.
|
||||
- [x] Persist command execution intent and immutable delivery receipts; recover interrupted commands as unknown without replaying physical cancellation.
|
||||
- [x] Reuse verified single-job spool cancellation, preserving current-connection ownership and reporting absence, refusal and uncertainty explicitly.
|
||||
- [x] Add companion desired-state, control-contact and last-action status with accessible text.
|
||||
- [x] Complete the isolated Verify.ps1 gate: 279 tests (72 Core + 207 Windows/CLI), zero warnings/errors/skips. Independent control-boundary review issues are fixed with runtime regressions.
|
||||
- [x] Wire native QQQ printing transport and refuse control-404 legacy fallback on that advertised extension; keep direct bearer diagnostics behind explicit `--legacy-compat`.
|
||||
- [x] Implement standard QQQ auth discovery/configured sign-in, protected service session storage and periodic resume, preserving device/journal identity.
|
||||
- [x] Complete the combined native-authentication, callback forwarding, CLI, UI and control gate: 356 tests (127 Core + 229 Windows/CLI), zero warnings/errors/skips, and independent source review fixes rechecked.
|
||||
- [ ] Qualify the configured provider and installed private callback end to end; source tests do not establish actual provider renewal or permissions deployment.
|
||||
- [x] Pass 23 actual Core client/native QQQ interoperability checks with table-based authentication and no print jobs.
|
||||
- [x] Build and inspect the unsigned candidate MSI, including payload versions/resources, callback registration and service configuration.
|
||||
- [ ] Qualify the installed companion after protected CI. No new physical printing is implied.
|
||||
|
||||
## Published 0.1.9-rc.1 — 2026-10-31
|
||||
|
||||
- [x] Reproduce and correct management-response loss during immediate named-pipe disconnect; current/legacy delayed readers and bounded shutdown/deadline regressions pass.
|
||||
- [x] Record the superseded 0.1.8 installation with preserved credentials/journal and authenticated peers. Its history-check failure required the management-response correction above.
|
||||
- [x] Install 0.1.8 with preserved credentials/journal and authenticated peers; independently confirm current QQQ heartbeat, two ready printers and no pending or uncertain jobs. The history-check failure requires the correction above.
|
||||
- [x] Pass the combined 0.1.9 solution/UI build with zero warnings/errors and all 255 tests (66 Core + 189 Windows/CLI); verify source/fixture bytes before and after the isolated run.
|
||||
- [x] Complete 0.1.9 hosted gates, state-preserving upgrade and installed app/service qualification: required checks, retained credentials/history, connected service and 16 installed UI checks pass.
|
||||
- [x] Publish v0.1.9-rc.1 from protected main `cf0e362`; [release workflow 41190815995](https://github.com/QRun-IO/qqq-print-agent/actions/runs/41190815995), all four assets and all four provenance attestations are verified.
|
||||
- [x] Record the distinct installed CI and published MSI hashes in [ACCEPTANCE.md](ACCEPTANCE.md). Runtime sources are unchanged; no separate installation of the published MSI is claimed.
|
||||
- [ ] Publish and verify the protected 0.1.9 corrective prerelease after recording installed acceptance.
|
||||
- [x] Audit source regression gate: 249 tests and zero build warnings/errors, including authenticated/bounded IPC, machine-state ownership, metadata preservation, backlog scheduling and SQLite initialization cleanup.
|
||||
- [x] Complete independent deep security scan, investigate all five findings, review fixes and record canonical findings/coverage.
|
||||
- [x] Qualify bounded production store/merge queries at 375,000 synthetic jobs and append 10,000 through journal APIs; integrity and retention checks pass. See SCALABILITY.md for measured scope; sustained service/network/printer throughput remains separate.
|
||||
- [x] Verify audit packaging, installed UI and hosted security/provenance gates for 0.1.9. Real in-app updater handoff remains a separate task below.
|
||||
- [ ] Verify audit packaging, installed UI/updater handoff and hosted security/provenance gates before publishing the next prerelease.
|
||||
- [x] Record user decision: prereleases remain unsigned for now; do not describe hashes or build attestations as code signing.
|
||||
- [x] Merge [audit PR #2](https://github.com/QRun-IO/qqq-print-agent/pull/2) through protected main after the corrective source and installed acceptance passed. Preserve the earlier 0.1.8 audit packaging evidence as history.
|
||||
- [x] Enforce all main-branch checks for administrators too.
|
||||
|
||||
## Historical 0.1.7 acceptance — 2026-10-30
|
||||
- [x] Publish audit draft PR #2; final executable source 2e6a2e5 passes all hosted checks. Download and verify CI MSI/branding checksums and actual installer formatting/sequence/component identities. New installation and tagged-release attestations remain pending.
|
||||
- [x] Enforce all main-branch checks for administrators too, following explicit user approval; establish acknowledged R-drive coordination with Mobile Scanner and Record Files masters.
|
||||
|
||||
- [x] Install 0.1.7 from 93dd5fc: MSI exit 0, no reboot, credentials retained; management/profile/history/log settings/branding/connected-state checks passed.
|
||||
- [x] Pass 227 unit/regression tests (57 Core + 170 Windows/CLI), zero warnings/errors and exact-source CI 41139885687.
|
||||
@@ -161,7 +24,7 @@ The following entries preserve earlier implementation checkpoints.
|
||||
- [x] Restore 0.1.4, then install corrected 0.1.5; all 12 native UI checks have passing results; 204 tests and exact-source CI passed.
|
||||
- [x] Verify and install 0.1.6: 211 tests, clean build, passing exact-source CI, successful MSI upgrade and all 15 native UI checks across 14+1 runs.
|
||||
- [ ] Diagnose the later clean service stop; normal-UAC restart restored Running, but the cause is unconfirmed.
|
||||
- [x] Restore the QQQ connection with credentials preserved and no pending jobs before startup.
|
||||
- [x] Restore the paired local QQQ connection with credentials preserved and no pending jobs before startup; connection healthy on loopback port 18081.
|
||||
|
||||
## Implemented
|
||||
|
||||
@@ -183,7 +46,7 @@ The following entries preserve earlier implementation checkpoints.
|
||||
- [x] AppKit update coordinator/prompts, manual/startup checks, fixed GitHub version/channel policy, verified protected download and coherent machine MSI helper.
|
||||
- [x] Persisted splash duration, shared help/release/project/support links, dependency credits and version/channel display.
|
||||
|
||||
## Historical 0.1.6 verification — 2026-10-30
|
||||
## Current verification and release
|
||||
|
||||
- [x] Publish v0.1.6-rc.1 and verify its release assets.
|
||||
- [x] Complete the 211-test source gate and exact-source CI; install 0.1.6 with credentials retained.
|
||||
@@ -192,10 +55,7 @@ The following entries preserve earlier implementation checkpoints.
|
||||
- [x] Connect a Zebra ZT411 at 300 dpi with confirmed 4 × 6-inch stock; expose locally and enable in QQQ.
|
||||
- [x] Submit exactly one ZPL shipping test and one PDF barcode/alignment test through the paired local QQQ server; both reached SPOOLED and the service remained Running.
|
||||
- [ ] Obtain user confirmation of the earlier 0.1.6 Zebra outputs, alignment and barcode scanning. Spool acceptance alone does not establish physical output.
|
||||
|
||||
## Remaining installed qualification
|
||||
|
||||
- [ ] Qualify actual update download/installer failure and cancellation, restart-required reporting and reboot recovery; the successful 0.3.2 update above does not establish these cases.
|
||||
- [ ] Qualify real in-app update: consent, failed/canceled download or elevation, retained state, helper handoff, coherent versions, relaunch and restart-required reporting.
|
||||
- [ ] Review completed protected update stages/logs manually; no automatic completed-stage retention policy is implemented.
|
||||
- [ ] Qualify remaining input-dependent selection/focus, long-value and metadata synchronization scenarios; passing UI checks do not cover every interaction.
|
||||
- [ ] Qualify installed credential recovery, queued/retry/cancel job controls, stale service state and bounded SCM recovery.
|
||||
@@ -211,4 +71,4 @@ The following entries preserve earlier implementation checkpoints.
|
||||
- [ ] Track custom media dimensions and physical-output confirmation separately from spooler acceptance.
|
||||
|
||||
- [x] Complete independent review after the five baseline security findings are remediated; current details are in SESSION-STATE.md.
|
||||
- [ ] Complete remaining deployment and hardware qualification; the successful 0.1.9 CI-package installation does not establish remote or broader driver acceptance.
|
||||
- [ ] Complete installed and deployment qualification; the normal-UAC upgrade request is pending, not a successful installation.
|
||||
+7
-11
@@ -3,31 +3,27 @@
|
||||
| Symptom | Check |
|
||||
| --- | --- |
|
||||
| Companion cannot connect to service | Confirm the MSI is installed, `QqqPrintAgent` is running, and the companion is elevated. A development CLI worker does not host the installed service pipe. |
|
||||
| Sign-in or discovery fails | Open **View logs**: every step (discovery, authentication metadata, native grant validation, provider discovery, browser callback, session verification by the service, device binding, identity check) is logged with the reason it stopped, and the dialog shows the same reason. Turn on **Debug logging** in Log settings for request routes, status codes, timings and realtime frames. |
|
||||
| Sign-in works in the companion but "Service authorization not completed" | The service verifies the session itself as LocalSystem. A self-signed or private-authority certificate (for example a local Caddy root) that your user account trusts is not in the machine store, so the service's TLS check fails; the log shows `TLS certificate for host rejected: RemoteCertificateChainErrors`. Install the issuing root in **Local Machine → Trusted Root Certification Authorities**, or enter the server address and enable **Allow untrusted server certificate for this server** in Connection settings for a development server (the exception is bound to that one server). |
|
||||
| Enrollment fails | Complete standard QQQ sign-in, then check the server URL, fresh/unconsumed code, device/facility configuration and server logs. Remote endpoints require HTTPS. The log records each enrollment step and the server's answer. |
|
||||
| Enrollment fails | Check server URL, fresh/unconsumed code, device/facility configuration and server logs. Remote endpoints require HTTPS. |
|
||||
| No printers in the service list | Install the queue for the machine/service identity. User-specific network mappings may not be visible to LocalSystem. Confirm Spooler is running. |
|
||||
| Windows test page fails | Repair driver, connection or printer hardware locally before testing cloud printing. |
|
||||
| Discovered printer never receives work | Share the queue locally, enable the matching discovered printer in QQQ and submit to that printer on the intended device. |
|
||||
| Job remains queued | Check service status, authenticated realtime connection, current user/device authority, server pause/disconnect state, queue approval/exposure and configured capacity. The cloud preview is bounded; inspect server records for the full queue. |
|
||||
| Realtime connection cannot start | Use the released native printing API 2.3 server and allow outbound WSS upgrades to the configured origin. Inspect the connection/policy error; a legacy native API 1.x server or blocked socket does not enable HTTP polling fallback. |
|
||||
| CONFIGURATION_REQUIRED | Have the QQQ administrator correct the complete effective policy or upgrade the incompatible client. Limits must fit declared client ceilings; reconnect does not silently lower them. |
|
||||
| Discovered printer never receives work | Enable the queue in QQQ, verify device/printer IDs and submit to that assigned queue. |
|
||||
| Job remains queued | Check service status, outbound network access, device authorization and polling. |
|
||||
| SPOOLED but no output | Check machine Printing Defaults, hardware media/method, pause and paper/label/ribbon conditions. A clear Windows queue or READY status is not proof of physical output. |
|
||||
| OUTCOME_UNKNOWN | Inspect output and the Windows queue before reprinting. Do not delete the journal or assume failure. |
|
||||
| PDF clipped or wrong size | Select actual size versus fit deliberately. Match the machine default, advertised media profile or explicit per-job PDF dimensions to the loaded stock; see [Printer media](PRINTER-MEDIA.md). |
|
||||
| PDF clipped or wrong size | Select actual size versus fit deliberately and configure correct default media in the Windows queue. Custom API media dimensions are not supported yet. |
|
||||
| Zebra prints text or blank labels | Confirm ZPL-capable hardware/driver, DPI, stock dimensions and actual printer mode. Inspect the specific document; previously confirmed output does not qualify every format/driver combination. |
|
||||
| Protected configuration cannot be opened | It belongs to another Windows identity, or the service account changed. Re-enroll through the service after resolving old jobs; do not copy a user-enrolled DPAPI file. |
|
||||
| Another worker owns the directory | Stop the duplicate CLI worker. Only one worker may own a given journal/data directory. |
|
||||
| MSI publisher warning | Stable 1.0.1 is signed. Verify the exact official release checksum and Authenticode signature as described in [Installation](INSTALLATION.md). Earlier prereleases may be unsigned. |
|
||||
| MSI publisher warning | Current prerelease builds are unsigned. Verify the release checksum and follow local installation policy. |
|
||||
|
||||
## ZPL prints but PDF does not
|
||||
|
||||
The paths use different settings: RAW ZPL carries its format instructions, while PDF is rendered through the Windows driver using its default or the requested per-job media. A diagnostic media choice does not rewrite the machine driver's shared configuration; short-label PDF tests send explicit job dimensions. A default that works in a signed-in user's **Printing Preferences** may differ from the defaults used by the Windows service.
|
||||
The paths use different settings: RAW ZPL carries its format instructions, while PDF is rendered through the Windows driver using its defaults. The diagnostic media choice controls the generated document, not the machine driver's configuration. A default that works in a signed-in user's **Printing Preferences** may differ from the defaults used by the Windows service.
|
||||
|
||||
For 4 × 6-inch direct-thermal stock with no ribbon, inspect **Printer properties → Advanced → Printing Defaults** for the queue. Use **4.00 × 6.00 inches** and **Thermal Direct**, with the printer's correct DPI; preserve other settings. Other supplies may require different dimensions or Thermal Transfer. Also verify the physical printer's print method and pause/error state. Do not assume Windows READY or an empty queue rules out a hardware problem.
|
||||
|
||||
During 0.1.7 acceptance the machine defaults were 4.09 × 2-inch Thermal Transfer. The ZPL label printed, but the PDF did not despite SPOOLED. Correcting the machine defaults and hardware state allowed one fresh reviewed PDF to print fully and correctly; the user confirmed it. No application-code fix was needed. Inspect the existing job/output before retrying to avoid duplicates. See [acceptance evidence](ACCEPTANCE.md).
|
||||
|
||||
For a non-security bug, include Windows version, application version, printer model/driver, the stage that failed, job ID and sanitized error text in a [bug report](https://git.kof22.com/QRun-IO/qqq-print-agent/issues). Never attach credentials, enrollment codes, customer PDFs, address labels, journal databases or raw diagnostic archives without reviewing them.
|
||||
For a non-security bug, include Windows version, application version, printer model/driver, the stage that failed, job ID and sanitized error text in a [bug report](https://github.com/QRun-IO/qqq-print-agent/issues/new/choose). Never attach credentials, enrollment codes, customer PDFs, address labels, journal databases or raw diagnostic archives without reviewing them.
|
||||
|
||||
Security issues belong in [private reporting](../SECURITY.md).
|
||||
@@ -1,43 +0,0 @@
|
||||
# Upgrade-preservation qualification plan — candidate 0.4.0-rc.1
|
||||
|
||||
Status: **plan only.** Nothing here has been run. The installed baseline is 0.3.2-rc.1 (MSI SHA-256 `1191C337265469EB06136AF232DB57FAC6BC5014357521D80B35E5CCA5AF6E18`) against the local QQQ on port 18081 (API 1.8 / printing 2.0). This plan follows the observer pattern recorded for the 0.3.1 and 0.3.2 acceptances in [ACCEPTANCE.md](ACCEPTANCE.md). It needs explicit user authorization before any installation, and it never submits a job.
|
||||
|
||||
## Preconditions (all must hold before an authorized install)
|
||||
|
||||
1. Final candidate head has a green hosted gate, including the Core test job. A green hosted gate does not clear the local Defender detection of the Core test assembly.
|
||||
2. The candidate MSI comes from that exact head's CI artifact. Record its SHA-256 and compare with `SHA256SUMS` in the artifact.
|
||||
3. Static MSI inspection (no install): ProductVersion `0.4.0`; app, service and CLI payloads all carry the same full informational version `0.4.0-rc.1+<head sha>`; Windows App SDK resources, service configuration (LocalSystem, automatic start, two 30-second recovery restarts), callback registration and the packaged notice files match the 0.3.2 baseline except for intended differences. Stable component identities must match the baseline so Windows Installer upgrades rather than duplicates.
|
||||
4. A read-only "before" report exists for the installed 0.3.2 state (below).
|
||||
|
||||
## Before/after observations (read-only, no secrets)
|
||||
|
||||
Capture the same fields before and after. Use hashes or counts for protected material; never print credentials, device keys, tokens or document payloads.
|
||||
|
||||
| Item | Method | Pass condition |
|
||||
| --- | --- | --- |
|
||||
| Component versions | File version/ProductVersion of app, service and CLI | After: all three equal `0.4.0-rc.1+<head>`; bytes equal the CI payload |
|
||||
| Machine credential file | Existence and SHA-256 only | Unchanged by the upgrade |
|
||||
| Pairing and identity | Device ID presence and server URL (no token) | Unchanged |
|
||||
| Local job history | Per-row digest of job ID, state, creation time, printer ID | Every prior row present with identical digest; additions accounted for separately |
|
||||
| Server job history | Same digests from the server view | Prior rows unchanged |
|
||||
| Printer exposure and profiles | Exposed set and per-printer profile fields | Unchanged |
|
||||
| Log settings | Retention days and daily cap | Unchanged |
|
||||
| Service configuration | SCM start type, account, recovery actions | Unchanged |
|
||||
| Connectivity | Native QQQ session and authenticated WebSocket state | Restored without operator action |
|
||||
| Companion | In-app update path (Not now, then Update and restart) | Same handoff as 0.3.2; app reopens Connected |
|
||||
|
||||
## Compatibility checks specific to this candidate
|
||||
|
||||
- **Older server, new client.** Against the local printing 2.0 server the HELLO must carry exactly the three pre-existing capabilities and no `printer-media-v1`, inventory must carry no `mediaProfiles`, and existing jobs must behave as before. This is the expected state on the installed local server and is itself a required qualification result.
|
||||
- **Capability only on 2.3+.** `printer-media-v1` and `mediaProfiles` appear only after the client discovers a stable printing 2.3+ server in major 2. A printing 2.2 (rendering) server must leave the client a three-capability peer. Qualify against a server that actually runs the 2.3.0 candidate, in an isolated environment, not the installed 18081 instance.
|
||||
- **Latency diagnostic line.** After upgrade, an authorized later job (not part of this plan) writes one `timing` line per job to the service log with the job ID only. Confirm that the line contains no document text.
|
||||
|
||||
## Failure handling
|
||||
|
||||
- Windows Installer same-upgrade-code downgrade is not supported. Keep the 0.3.2 MSI and its hash so a manual return can be planned, and treat that as a separate authorized operation.
|
||||
- An MSI exit code of 3010 means restart required; report it as such. Do not delete journal, staging or credential files to recover.
|
||||
- A mismatch in any prior-row digest, credential hash or exposure set stops qualification and is reported as a failure with the earlier evidence preserved.
|
||||
|
||||
## Explicitly not covered here
|
||||
|
||||
Physical output with a selected media profile, Authenticode signing, update download or installer failure/cancellation, reboot recovery, installed browser/private-callback sign-in against a published API 1.9+ server, and any 1.0 claim. Each needs its own authorization and evidence.
|
||||
+11
-11
@@ -1,6 +1,6 @@
|
||||
# Using QQQ Print Agent
|
||||
|
||||
This guide describes **1.0.1**, the signed stable Windows release. Use it with qbit-printing **1.0.0** on QQQ **4.1.0-RC.21** or a compatible newer server. See [Acceptance](ACCEPTANCE.md) for dated installation and physical-print evidence.
|
||||
This guide describes installed 0.1.7. Its 227-test source gate and all 16 installed UI checks passed. Laser PDF and Zebra ZPL/PDF output were confirmed; barcode scanning, measured alignment and broader accessibility remain separate. See [Acceptance](ACCEPTANCE.md).
|
||||
|
||||
## Menus
|
||||
|
||||
@@ -10,19 +10,19 @@ This guide describes **1.0.1**, the signed stable Windows release. Use it with q
|
||||
|
||||
## Connect and select printers
|
||||
|
||||
Open **QQQ Print Agent** from Start. In **Settings → Server connection → Sign in / Connection settings**, enter your HTTPS QQQ server address and select **Discover sign-in options**. Every step of discovery, sign-in, the hand-off to the service and the service's own verification is written to the activity log, and a failure's reason is shown in the dialog as well as logged; open **View logs** when something stops. For a development server with a self-signed or private-authority certificate, enter its address and turn on **Allow untrusted server certificate for this server**; both the companion and the Windows service then accept that one server's certificate, and no other server is affected. The service runs as LocalSystem and trusts only the machine certificate store, so a certificate that your user account trusts can still be refused by the service; either install the issuing root in the Local Machine Trusted Root store or use this option. With it on, any certificate is accepted and every session is logged with a warning, so turn it off for production servers. Sign in with the advertised username/password or browser flow. **Reuse the saved pairing** is the default; an older unbound device can be explicitly associated with your account. For a new pairing, obtain an enrollment code from QQQ and choose **Connect this device**. The Windows service holds the device credential; the companion never receives it. **Reconnect** requests another connection attempt. **Sign in again** restores user authentication while preserving the saved pairing and history. Changing servers or replacing a revoked pairing requires the explicit **Set up a new pairing** choice; see [QQQ sign-in](QQQ-SIGN-IN.md).
|
||||
Open **QQQ Print Agent** from Start. In **Settings → Server connection**, choose **Connect this device**, enter your HTTPS QQQ server address and a fresh enrollment code, then connect. The Windows service holds the device credential; the companion never receives it. **Reconnect** immediately requests another connection attempt. **Sign in again** replaces the connection using a fresh code while preserving prior job evidence.
|
||||
|
||||
If enrollment times out, check QQQ before trying again: the code may already have been consumed. Generate a fresh code and revoke an unused/orphaned device through your administrator. An unreadable saved credential can be repaired by explicit enrollment; the previous encrypted file and journal are preserved.
|
||||
|
||||
In **Printers**, use the **Shared** checkbox for each intended queue, then approve it on the server. Local sharing and server approval are separate, and the **Server** column shows the second one for the server this computer is connected to: **Approved** (the server's printer catalog lists the printer for this computer), **Awaiting approval** (the server received the inventory but an administrator has not approved the printer), **Not reported** (the server could not be asked: an older server, or the signed-in user may not read the operator printer catalog; the reason is in the tooltip and the activity log) or **Not checked** (not connected yet). The service asks the server after each inventory and about once a minute while connected, so after a sign-in to a different server every shared printer starts as awaiting approval there until that server approves it. Select a printer to expand its information directly below that row. **Settings** and **Print test** appear at the top of the expansion; there is no fixed printer-details area below the list. The description preview is limited to three lines, and **Windows diagnostics** expands the driver, port and identifier.
|
||||
In **Printers**, use the **Shared** checkbox for each intended queue, then approve it in QQQ. Local sharing and server approval are separate. Select a printer to expand its information directly below that row. **Settings** and **Print test** appear at the top of the expansion; there is no fixed printer-details area below the list. The description preview is limited to three lines, and **Windows diagnostics** expands the driver, port and identifier.
|
||||
|
||||
Double-click the compact printer row, or select it and choose **Settings**, to open a wider editor. Text selection, sharing checkboxes and controls inside the expansion retain their own behavior. Read or edit the full description in Settings. **Print test** asks for confirmation, format and stock/resolution before sending one real test through QQQ. It offers Letter/A4 PDF and 4 × 6, 4 × 2 or 4 × 1-inch PDF/ZPL labels, with 203/300/600 dpi choices for ZPL. Compatible label queues default to ZPL; the suggested DPI must be checked against the printer. Virtual PDF, XPS, fax and save-to-file queues that need interaction are unavailable to the service. **Windows printer settings** opens the native queue setup page.
|
||||
Double-click the compact printer row, or select it and choose **Settings**, to open a wider editor. Text selection, sharing checkboxes and controls inside the expansion retain their own behavior. Read or edit the full description in Settings. **Print test** asks for confirmation, format and stock/resolution before sending one real test through QQQ. It offers Letter/A4/4 × 6-inch PDF and 4 × 6-inch ZPL at 203/300/600 dpi. Compatible label queues default to ZPL; the suggested DPI must be checked against the printer. Virtual PDF, XPS, fax and save-to-file queues that need interaction are unavailable to the service. **Windows printer settings** opens the native queue setup page.
|
||||
|
||||
Printers initially sort by **Name ascending**. Click Name, Status, Location, Formats or Shared to sort that column; click it again to reverse direction. The active header shows an arrow and an accessible direction label. Long table values use ellipses and full tooltips; the expanded fields and editor expose the values separately from technical queue identity.
|
||||
|
||||
## Set machine media defaults before printing labels
|
||||
|
||||
PDF can use the machine default, an advertised media profile or explicit per-job dimensions. These job choices do not rewrite the shared Windows queue. Keep the machine default matched to the usual stock; see [Printer media](PRINTER-MEDIA.md). For a ribbonless direct-thermal printer loaded with 4 × 6-inch labels, open **Windows printer settings → your queue → Printer properties → Advanced → Printing Defaults**. Set width **4.00 inches**, height **6.00 inches**, and the printing method to **Thermal Direct** (driver wording may vary). Preserve unrelated settings. **Printing Preferences** for the signed-in user may not affect the LocalSystem service.
|
||||
PDF uses the Windows driver's machine defaults; choosing a diagnostic document size does not rewrite them. For a ribbonless direct-thermal printer loaded with 4 × 6-inch labels, open **Windows printer settings → your queue → Printer properties → Advanced → Printing Defaults**. Set width **4.00 inches**, height **6.00 inches**, and the printing method to **Thermal Direct** (driver wording may vary). Preserve unrelated settings. **Printing Preferences** for the signed-in user may not affect the LocalSystem service.
|
||||
|
||||
Use the method appropriate to your actual printer and supplies; Thermal Transfer expects ribbon. Check the printer's own mode and pause/error state as well as Windows. After correcting a mismatch, inspect existing output/queue state before requesting one new test. A job marked **SPOOLED** can still fail to produce paper or a label. See [label troubleshooting](TROUBLESHOOTING.md#zpl-prints-but-pdf-does-not).
|
||||
|
||||
@@ -32,7 +32,7 @@ The Jobs table aligns document title, printer, state, format and **Created** tim
|
||||
|
||||
Click Document, Printer, Status, Format or Created to change sorting; click the active header again to reverse it. Sorting applies to the entire matching result set before 50-row paging, including the bounded cloud queue preview. Changing sort returns to the first page. The direction indicator describes the last successfully loaded order; a failed refresh leaves the old rows with an unavailable/stale explanation.
|
||||
|
||||
Select a row to expand its details, recent events and actions directly below that row. Double-click the row or choose **Details** to open a wider dialog with labeled document/printer/outcome fields and a structured event history. The dialog follows the available window size and scrolls vertically. Previous and Next browse 50 results at a time. Search matches the beginning of a document title, printer name or job ID; choose a state or Needs attention to narrow results. Long table text is abbreviated with full tooltips; Details exposes selectable full values. Older jobs retain their IDs when their title was never recorded.
|
||||
Select a row to enable its actions. Double-click the row or choose **Details** to open a wider dialog with labeled document/printer/outcome fields and a structured event history. The dialog follows the available window size and scrolls vertically. Previous and Next browse 50 results at a time. Search matches the beginning of a document title, printer name or job ID; choose a state or Needs attention to narrow results. Long table text is abbreviated with full tooltips; Details exposes selectable full values. Older jobs retain their IDs when their title was never recorded.
|
||||
|
||||
- **Details** shows local events and whether each was reported to QQQ.
|
||||
- **Print again** creates a new server job after confirmation. Inspect output first, especially for uncertain or previously spooled work. The original job is never reset.
|
||||
@@ -58,11 +58,11 @@ Use **Settings → Computer details** to edit this installation’s display name
|
||||
|
||||
## Tray, logs and service
|
||||
|
||||
The footer and tray use text plus color: green for connected/ready, orange for exposed printer issues or no shared queues, and red for disconnection, failures or unreviewed uncertain jobs. The footer also shows the WebSocket connection, configured server and live upload/download rates, with totals since service start in the traffic tooltip. Select the server to open connection settings, or use **Reconnect** and **View logs**. These counters describe application traffic, not all network traffic on the computer. Printer status is a Windows observation, not guaranteed hardware telemetry.
|
||||
The footer and tray use text plus color: green for connected/ready, orange for exposed printer issues or no shared queues, and red for disconnection, failures or unreviewed uncertain jobs. Printer status is a Windows observation, not guaranteed hardware telemetry.
|
||||
|
||||
**Logs**, **View logs**, and **Open activity log** all open the same built-in AppKit viewer. Service and companion activity are together, persisted under the protected machine data directory with configurable daily rotation and retention. Use **Follow**, **Errors only**, **Copy**, and **Open logs folder**. Credentials and document payloads must never be logged; local identifiers remain operational data.
|
||||
|
||||
**Settings → Diagnostic logs → Log settings** controls retention (1–365 days, default 30), the file size at which a day's log rolls over (1–1024 MiB, default 100), how many rolled-over segments of a day are kept (1–100, default 10) and **Debug logging**. A file that reaches the size limit is renamed to a numbered segment (`qqq-print-agent-yyyy-MM-dd.1.log`, `.2.log`, …) and logging continues in a fresh file; logging never stops because of size, and the oldest segments beyond the kept count are removed. Debug logging adds every request route, status code and timing, every realtime frame and full failure detail; credentials, documents and enrollment codes are never logged at any level. **Clear local logs** confirms removal of diagnostic logs only, preserving credentials, jobs, settings and journal history. The same controls are available on Logs.
|
||||
**Settings → Diagnostic logs → Log settings** controls retention (1–365 days, default 30) and daily size (1–100 MiB, default 20). It shows usage and whether the daily cap was reached. At the cap, printing continues but diagnostics pause until the next local day, an increased limit or explicit clearing. **Clear local logs** confirms removal of diagnostic logs only, preserving credentials, jobs, settings and journal history. The same controls are available on Logs.
|
||||
|
||||
Settings shows actual Windows service state and provides **Start service**, **Restart service**, **Windows Services**, and an installer link. Restarting can interrupt a submission; wait for active work when possible. The service continues printing when the companion exits.
|
||||
|
||||
@@ -72,8 +72,8 @@ Administrators can apply [customer branding](BRANDING.md) without rebuilding. Ap
|
||||
|
||||
## Branded warehouse test prints
|
||||
|
||||
Select a printer and choose **Print test**. Choose a document format and stock from the native option boxes, then confirm **Print one test**. PDF offers Letter, A4 or a 4 × 6, 4 × 2 or 4 × 1-inch label. ZPL offers those label sizes at 203, 300 or 600 dpi. Match the loaded stock and actual device resolution; the driver-name suggestion is only a hint. The default stays 4 × 6 until you pick another size, so load 4 × 1 or 4 × 2 stock before choosing it. PDF stock choices do not change Windows queue defaults; a 4 × 2 or 4 × 1 PDF sends its own actual-size paper for that job only, with the released qbit-printing 1.0.0 server.
|
||||
Select a printer and choose **Print test**. Choose a document format and stock from the native option boxes, then confirm **Print one test**. PDF offers Letter, A4 or a 4 × 6-inch label. ZPL offers 4 × 6-inch labels at 203, 300 or 600 dpi. Match the loaded stock and actual device resolution; the driver-name suggestion is only a hint. PDF stock choices do not change Windows queue defaults.
|
||||
|
||||
QQQ generates the same branded diagnostics for desktop requests and its own printer record/table actions. The pages use Query, QQQ's mascot, large warehouse identifiers, dotted zeros and distinct 1/I/l glyphs from embedded JetBrains Mono Bold. PDF embeds the font; ZPL carries rasterized glyphs in bounded document graphics, so neither depends on a resident printer font. Label diagnostics include a Code 128 barcode on the ZPL path, and all layouts include size/alignment checks. Paper output and scanner readability must be checked physically.
|
||||
QQQ generates the same branded diagnostics for desktop requests and its own printer record/table actions. The pages use the QQQ logo, large warehouse identifiers, dotted zeros and distinct 1/I/l glyphs from embedded JetBrains Mono Bold. PDF embeds the font; ZPL carries rasterized glyphs in bounded document graphics, so neither depends on a resident printer font. Label diagnostics include a Code 128 barcode on the ZPL path, and all layouts include size/alignment checks. Paper output and scanner readability must be checked physically.
|
||||
|
||||
Use qbit-printing 1.0.0 for the complete set of branded profiles and per-job media options. Older clients can omit the profile, defaulting to Letter PDF or 203-dpi 4 × 6 ZPL. Native QQQ actions can process selected printers; group devices with the same stock and label resolution. Connecting or discovering a device never automatically sends a test.
|
||||
Use qbit-printing 0.1.3-rc.1 or later for these branded profiles. Older clients can omit the profile, defaulting to Letter PDF or 203-dpi 4 × 6 ZPL. Native QQQ actions can process selected printers; group devices with the same stock and label resolution. Connecting or discovering a device never automatically sends a test.
|
||||
@@ -1,86 +0,0 @@
|
||||
# Microsoft Windows SDK terms
|
||||
|
||||
The project's MIT license applies to this project's code. Microsoft Windows
|
||||
SDK packages retain their separate terms; they are not relicensed as MIT.
|
||||
The maintainer remains responsible for satisfying applicable redistribution
|
||||
and end-user protection obligations. Copying notices and passing these checks does not
|
||||
certify that those obligations have been fulfilled or create a customer EULA.
|
||||
|
||||
The exact inventory is recorded in
|
||||
[`licenses/windows-sdk-packages.json`](../licenses/windows-sdk-packages.json),
|
||||
including each package's NuGet content hash, signed archive SHA-256, separate
|
||||
license and notice files, and their original byte hashes. This is the existing
|
||||
SDK dependency set, not permission to add other packages from these families.
|
||||
|
||||
| Package | Exact version | Role |
|
||||
| --- | --- | --- |
|
||||
| Microsoft.Windows.AI.MachineLearning | 2.1.74 | Runtime SDK dependency |
|
||||
| Microsoft.Windows.SDK.BuildTools | 10.0.28000.2705 | Build only |
|
||||
| Microsoft.Windows.SDK.BuildTools.MSIX | 1.7.251221100 | Build only |
|
||||
| Microsoft.Windows.SDK.NET.Ref | 10.0.19041.57 | Reference pack and Windows runtime projections |
|
||||
| Microsoft.WindowsAppSDK | 2.5.1 | Runtime SDK dependency |
|
||||
| Microsoft.WindowsAppSDK.AI | 2.5.5 | Runtime SDK dependency |
|
||||
| Microsoft.WindowsAppSDK.Base | 2.0.4 | Runtime SDK dependency |
|
||||
| Microsoft.WindowsAppSDK.DWrite | 2.1.0 | Runtime SDK dependency |
|
||||
| Microsoft.WindowsAppSDK.Foundation | 2.3.12 | Runtime SDK dependency |
|
||||
| Microsoft.WindowsAppSDK.InteractiveExperiences | 2.1.9 | Runtime SDK dependency |
|
||||
| Microsoft.WindowsAppSDK.ML | 2.1.94 | Runtime SDK dependency |
|
||||
| Microsoft.WindowsAppSDK.Runtime | 2.5.1 | Runtime SDK dependency |
|
||||
| Microsoft.WindowsAppSDK.Search | 2.5.5 | Runtime SDK dependency |
|
||||
| Microsoft.WindowsAppSDK.Widgets | 2.0.5 | Runtime SDK dependency |
|
||||
| Microsoft.WindowsAppSDK.WinUI | 2.3.9 | Runtime SDK dependency |
|
||||
|
||||
The [Windows App SDK package license](https://www.nuget.org/packages/Microsoft.WindowsAppSDK/2.5.1/License)
|
||||
and accompanying notice are preserved byte-for-byte. The five distinct license
|
||||
texts include both ML packages' separate terms, the MSIX SDK license, and the
|
||||
Windows SDK RTF. Five distinct vendor notices are also retained. Identical files
|
||||
shared by multiple packages are mapped to one copy in the inventory manifest;
|
||||
provider-specific terms are not replaced by the common App SDK license.
|
||||
|
||||
The application and native test host copy the complete `licenses/` tree into
|
||||
`ThirdPartyNotices/`, alongside the project's separate root `LICENSE` and
|
||||
`NOTICE` files in their output directory. Git preserves the vendor bytes without
|
||||
line-ending conversion.
|
||||
|
||||
The [BuildTools package](https://www.nuget.org/packages/Microsoft.Windows.SDK.BuildTools/10.0.28000.2705)
|
||||
identifies [Microsoft's Windows SDK terms](https://aka.ms/WinSDKLicenseURL).
|
||||
Both BuildTools packages remain build-only dependencies. Intentional
|
||||
redistribution of any SDK tool would require a separate scope and terms review.
|
||||
SDK.NET.Ref is resolved implicitly by the .NET SDK, rather than appearing in
|
||||
source package locks. Its three pinned `lib/net8.0` runtime projection DLLs may
|
||||
enter a payload; that does not claim all three are shipped. Its other package
|
||||
files are excluded, apart from retained legal text.
|
||||
|
||||
`build/Test-WindowsSdkInventory.ps1` checks central versions, every selected
|
||||
SDK occurrence and NuGet content hash in every source lockfile, all 15 exact
|
||||
package archive hashes and cache content hashes, and all ten retained legal
|
||||
files. Restored application assets must contain all 14 locked SDK packages and
|
||||
the exact implicit reference-pack download. Other available project assets are
|
||||
also checked for SDK version and hash changes. NuGet's normalized content hash
|
||||
is distinct from the signed archive's raw SHA-512 and SHA-256.
|
||||
|
||||
Required CI runs the guard after locked restore. Packaging also verifies the
|
||||
actual App notices and manifest, then rejects identical build/reference package
|
||||
content, including renamed tools, anywhere in the three-process payload before
|
||||
creating the MSI. Only the exact reference-pack runtime projection bytes and
|
||||
legal text are exempt from this payload exclusion. This check does not grant a
|
||||
license exemption.
|
||||
|
||||
The maintainer accepted this exact 15-package scope on 2026-11-01.
|
||||
[EX-0014](https://github.com/KofTwentyTwo/standards/blob/fbfc8d2cf3b5e16ae9750b04cf9de1794f1e7152/exceptions/register.md#ex-0014)
|
||||
is the approved record, merged through the normal protected workflow in
|
||||
[standards PR 56](https://github.com/KofTwentyTwo/standards/pull/56). The caller
|
||||
allows only these 15 package names through the automated license check, plus the
|
||||
one separately approved EX-0015 development-only `pkg:npm/uri-js` entry. The SDK
|
||||
guard accepts exactly that finite union; any other npm or other-ecosystem purl, or
|
||||
a versioned or duplicate entry, is rejected, and `check-script-quality.py` pins the
|
||||
uri-js version, lock integrity and license bytes.
|
||||
|
||||
EX-0014 is limited to these exact package/version/artifact tuples through
|
||||
2027-04-30 UTC inclusive. The required CI and pre-MSI guard rejects use from
|
||||
2027-05-01 UTC, any change to the pinned inventory manifest, and any expansion
|
||||
of the finite package-name allowance. The dependency-review action does not
|
||||
enforce PURL versions, so the separate version, content-hash and archive-hash
|
||||
checks remain mandatory. A changed version, license or payload scope requires
|
||||
renewed approval. AppKit receives no exception. All other dependency license,
|
||||
vulnerability, provenance and release gates remain in force.
|
||||
@@ -1,24 +1,6 @@
|
||||
# Threat model: QQQ Print Agent
|
||||
|
||||
## Current release boundary — 1.0.1
|
||||
|
||||
The signed 1.0.1 release uses the realtime and native-authentication boundaries described here. Stable distribution now includes Azure-signed first-party binaries and MSI, checksums and provenance; the earlier unsigned audit baseline below is retained as history. Gitea is the primary source; the authorized GitHub signing workflow and fixed GitHub updater feed remain trusted distribution infrastructure. See [release signing](../RELEASE-SIGNING.md) and [current release status](../RELEASE-READINESS.md).
|
||||
|
||||
## Realtime boundary
|
||||
|
||||
The remote-control adapter accepts only inventory refresh and cancellation of one locally journaled spooler job. Desired pause/disconnect state is revisioned and persists by canonical server URL and device identity; older or conflicting revisions cannot resume a device. An independently processed authenticated WSS channel carries controls and receipts while documents stream over separate same-origin HTTPS requests. There is no job/control polling fallback. A paused device claims no new work. A disconnected device retains control traffic and in-flight receipts; already-submitted printing is not recalled. Reconnect is a transport refresh, never an OS or service restart. See [the realtime contract and operational limits](../REALTIME.md).
|
||||
|
||||
The native QQQ session adapter requires discovery before credentials and never treats a native control 404 as legacy permission. After support is negotiated, 404 does not remove restrictions. Authorization denial becomes authorization-required, without inferring that every 401/403 proves revocation. New claims wait for an authenticated, bound QQQ user and valid control state. Existing installations without a protected QQQ session wait for explicit sign-in; device proof alone cannot authorize normal service printing. Explicit isolated CLI diagnostics may use the compatibility bearer adapter with `--legacy-compat`; it is not a fallback from native authentication.
|
||||
|
||||
The service stores only the QQQ session cookie and stable authoritative identity under service-identity DPAPI, and periodically resumes the standard session. Passwords stay in the companion; provider refresh/access tokens remain server-side. Normal CLI operations use the existing authenticated service pipe. The private browser callback is fixed and MSI-owned, forwarding bounded data only into an active same-user/session companion inbox after executable verification. It carries a short-lived authorization code, never a session cookie or PKCE verifier. Core validates exact advertised redirect, random state, PKCE and single-use expiry; when the server advertises `nonceValidation: REQUIRED` it also sends only that attempt's own authorization nonce as `expectedNonce` (never a callback-supplied or regenerated value) and refuses any other non-empty nonce policy; no callback creates an authentication attempt. Provider registration, installed callback delivery and long-duration renewal remain deployment qualifications.
|
||||
|
||||
Realtime frames and queues have administrator-configured byte/count bounds validated against declared client ceilings. Defaults are 1 MiB per complete frame, 64 queued frames and 4 MiB queued bytes. Fragmentation does not bypass the complete-message limit. The journal admits at most 4,096 command records and 128 retained connection states, failing closed when capacity is exhausted. A durable marker precedes any effect. Crash recovery produces OUTCOME_UNKNOWN; duplicate delivery reuses the exact saved receipt rather than repeating cancellation. No raw executable, printer name or arbitrary spool ID comes from the server: CANCEL_SPOOL resolves its job ID through the current connection's local receipt and verifies the exact QQQ document at the Windows spooler boundary.
|
||||
|
||||
Successful cancellation means Windows accepted the request, not that printed paper was recalled. Absent/completed jobs, ownership mismatch, failure, expiry and uncertain outcome remain distinct. Only a specific missing command receipt after expiry plus seven days retires its transport retry, preserving the exact local receipt and distinguishing retirement from server acknowledgement. Discovery/socket failures never use this exception. Acknowledged or transport-retired command history can be pruned after 30 days; unresolved current-connection evidence remains and causes explicit capacity backpressure. No global Windows queue purge is implemented.
|
||||
|
||||
## Historical audit baseline
|
||||
|
||||
Historical baseline: 0.1.7-rc.1, reviewed 2026-10-30. The inventory and source checkpoints below retain their original evidence and pending language; they do not describe the current release status or reopen qualification work. Current distribution and acceptance are summarized above and in [Release readiness](../RELEASE-READINESS.md).
|
||||
Installed baseline: 0.1.7-rc.1; audit source changes pending release. Reviewed: 2026-10-30. This is an implementation-level inventory. The separate independent deep scan has not yet returned its findings.
|
||||
|
||||
## Boundaries and assets
|
||||
|
||||
@@ -26,24 +8,23 @@ The QQQ server supplies assigned document bytes over HTTPS. The Windows LocalSys
|
||||
|
||||
| Boundary | Implemented control | Residual risk / qualification |
|
||||
| --- | --- | --- |
|
||||
| Internet to device | Outbound WSS/HTTPS, normal certificate validation; explicit loopback-only WS/HTTP development exception | Proxy/custom trust deployments not qualified |
|
||||
| Device to server | Standard QQQ session plus secondary device proof; current user/tenant/job permissions | A compromised trusted server can supply hostile print content |
|
||||
| Internet to device | Outbound HTTPS, normal certificate validation; loopback-only HTTP development exception | Proxy/custom trust deployments not qualified |
|
||||
| Device to server | Dedicated bearer credential; server enforces device/job scope | A compromised trusted server can supply hostile print content |
|
||||
| Local UI to service | Pipe ACL permits SYSTEM/admins; narrow command set; bounded newline framing and cancellable reads/writes | Local administrators already control the machine; source regressions passed, installed audit acceptance pending |
|
||||
| Exposure selection | Service-owned persisted allowlist; discovered-ID validation; filter inventory and recheck submission | Removal cannot retract data already accepted by Windows |
|
||||
| Credentials at rest | DPAPI CurrentUser under service identity; restricted ProgramData ACL | Machine/service compromise defeats local protection |
|
||||
| Payload download | Configured per-format/staging limits, streamed length/SHA-256 checks and connect/idle/total deadlines; independent control channel | Integrity does not sanitize PDFs or printer languages; protected staging contains sensitive document bytes |
|
||||
| Payload download | 20 MiB cap, declared length and SHA-256 validation; 60-second body deadline; separate 2 MiB control-response cap | Integrity does not sanitize PDFs or printer languages |
|
||||
| Rendering/driver execution | Native Windows PDF/GDI/spooler APIs; bounded render dimensions | Disposable child with bounded timeouts and parent-exit cleanup; child retains service privileges, so this is fault isolation, not a security sandbox |
|
||||
| RAW ZPL | Explicit compatible queue, trusted server workflow | ZPL can contain printer-control commands; not a sandboxed format |
|
||||
| Duplicate output | Persistent receipts and events; uncertain submissions require review | Database and physical printer cannot share a transaction |
|
||||
| Tray snapshot/logs | No device credential or document bytes; bounded recent jobs/logs; debug logging adds routes, status codes, timings, frame types and certificate identities, never secrets | IDs/errors remain operational data and must be reviewed before sharing |
|
||||
| Server certificate trust | Windows machine-store validation for the service and user-store validation for the companion; rejections are logged with the policy error and certificate identity | An administrator may enable "Allow untrusted server certificate" for one named server origin (scheme, host and port) for development; it accepts any certificate (including a forged one) from that server only until turned off, is persisted in the protected store, never applies to another server, and every session created under it is logged with a warning |
|
||||
| Software distribution | Public source, pinned actions/dependencies, audited locked restore, checksums and exact-release attestations | Published prereleases remain unsigned; source checks do not qualify installed behavior |
|
||||
| Tray snapshot/logs | No device credential or document bytes; bounded recent jobs/logs | IDs/errors remain operational data and must be reviewed before sharing |
|
||||
| Software distribution | Public source, pinned actions/dependencies, audited locked restore, checksums | Initial installer is unsigned; no attestation/production signing claim |
|
||||
|
||||
## Data handling
|
||||
|
||||
The service owns `connection.dpapi`, `journal.db` and its WAL. The MSI retains state through uninstall/reinstall. Revoke/decommission the device and resolve pending jobs before deliberately deleting retained state. Only delivered terminal detail whose failures were reviewed is pruned; final-state evidence is retained. Never publish raw state or customer documents.
|
||||
|
||||
Service and companion persist serialized, credential-redacted AppKit logs with 30-day retention, rolling a day's file over to numbered segments at a configurable size (default 100 MiB, at most 10 segments kept per day) rather than suppressing entries; recent job snapshots come from durable connection-scoped metadata. Tray colors describe observed connectivity/queue state, not a guarantee of physical printer readiness or completed output.
|
||||
Service and companion persist serialized, credential-redacted AppKit logs with 30-day retention; recent job snapshots come from durable connection-scoped metadata. Tray colors describe observed connectivity/queue state, not a guarantee of physical printer readiness or completed output.
|
||||
|
||||
## Follow-up
|
||||
|
||||
@@ -53,6 +34,7 @@ Runtime branding is presentation-only, loaded from the existing administrator-re
|
||||
|
||||
Sign-in startup requires an explicit administrator preference in the installed companion. The task uses that administrator's interactive identity and a fixed Program Files executable/arguments; it stores no password. Same-name foreign tasks are refused. Full uninstall deletes only exact owned definitions; upgrades preserve them. Device operator actions remain scoped to authenticated device jobs and approved/exposed printers; reprint creates a new job and requires duplicate-risk consent for uncertain/spooled originals.
|
||||
|
||||
|
||||
## Machine-MSI updates: implemented source, installed acceptance pending
|
||||
|
||||
The current audit source gate passed **237 tests with zero warnings/errors**. The installed 0.1.7 companion passed all 16 desktop checks before this audit. The AppKit `IUpdateService` adapter, `UpdateCoordinator` integration, fixed-feed client and copied apply helper are implemented, but direct MSI upgrades and synthetic updater tests do not establish a successful real in-app update handoff. That qualification remains pending.
|
||||
@@ -85,6 +67,7 @@ The current audit source gate passed **237 tests with zero warnings/errors**. Th
|
||||
|
||||
Unit/integration fixtures must cover fixed-origin/asset validation, channel/version policy, size/hash mismatch, redirect rejection, canceled download cleanup, reparse/untrusted path rejection and failed helper/apply outcomes. Installed acceptance must cover explicit UAC cancellation, blocked/in-use files, coherent version replacement, retained credentials/deduplication evidence, restart and Windows Installer reboot-required results. No updater operation is considered accepted merely because the AppKit interface compiles.
|
||||
|
||||
|
||||
### Apply-helper source checkpoint
|
||||
|
||||
`MsiUpdateInstaller` now copies the entire installed self-contained CLI into the protected update session's helper directory before handoff, avoiding a running helper's lock on product binaries. Source validation walks existing path components, rejects reparse points, checks trusted ownership and effective write ACLs (including generic write/all rights), and separately checks copied descendants. Normal inherit-only CREATOR OWNER rules do not count as direct write grants on the parent object.
|
||||
@@ -112,19 +95,3 @@ Every management client authenticates the connected pipe's process against the i
|
||||
Canonical machine state accepts only SYSTEM, Administrators and TrustedInstaller ownership and access grants. The initial validation covers existing descendants and rejects links, null DACLs and untrusted inherit-only grants. Existing hostile state is rejected rather than normalized and adopted. Store, log, branding, startup and updater entry points share the invariant; explicitly separate diagnostic directories remain outside machine-state adoption. Administrator changes after successful validation remain within the trusted boundary.
|
||||
|
||||
Direct MSI and branded installation enforce this invariant before using persisted files. The deferred preflight runs before folder creation; the installation script executes before old-product removal, which remains inside the rollback transaction. Startup definitions are created within validated state, then held against write/deletion while Task Scheduler reads them; the resulting definition is verified. Actual MSI formatting, component reuse, successful installed-peer authentication and hostile-tree rollback are separate native qualification requirements, not conclusions from unit tests.
|
||||
|
||||
### Explicit credential recovery
|
||||
|
||||
Unreadable session ciphertext is quarantined only on explicit sign-out or after fresh sign-in and authoritative binding succeed. Unreadable device proof remains in place until explicit enrollment replaces it; old journal scopes and local printer exposure are retained. Recovery never invents device authority or retries old print submissions. A missing readable session cannot be remotely revoked by local sign-out; the UI reports the separate QQQ revocation requirement. Background traffic remains fail closed.
|
||||
|
||||
Replacement pairing requires an explicit local setup choice and fresh standard QQQ authentication. Its persisted unbound identity prevents restoration from presenting old, revoked device proof. New claims remain gated until successful enrollment, binding and control synchronization. Default sign-in still requires the saved pairing's authoritative binding. Failed setup preserves old configuration; successful replacement changes journal scope without replaying prior-device work.
|
||||
|
||||
### Virtual development agent HTTP boundary
|
||||
|
||||
The virtual agent's native HTTP request helper rejects foreign origins before
|
||||
attaching session or device credentials, refuses redirects, and sends the exact
|
||||
configured Origin on unsafe cookie-authenticated requests. This preserves the
|
||||
server's missing/foreign-Origin rejection. Discovery accepts canonical stable
|
||||
three-part printing versions in major 2, matching the protocol fixtures.
|
||||
Synthetic loopback HTTP tests cover these boundaries; they do not establish
|
||||
production authentication, durable spooling or physical printing acceptance.
|
||||
@@ -1,30 +0,0 @@
|
||||
# Client editions
|
||||
|
||||
One folder per client. `./build/Build-Installer.ps1 -Edition <folder>` builds a fully branded
|
||||
installer from the same source: the companion ships the folder's mark and icon, every executable
|
||||
carries the client's product and company metadata, the MSI's product name, manufacturer, service
|
||||
display name and Start menu entry use the client's name, the MSI is named `<assetPrefix>-<version>-x64.msi`,
|
||||
and the installed updater follows that asset name on the release feed.
|
||||
|
||||
Each folder holds:
|
||||
|
||||
| File | Required | Use |
|
||||
| --- | --- | --- |
|
||||
| `edition.json` | yes | Names, accent colour and asset prefix (fields below) |
|
||||
| `app-icon.svg` | yes | Splash and About mark |
|
||||
| `app.ico` | yes | Window, taskbar, executable and Start menu icon (multi-size, 16 to 256 px) |
|
||||
| `logo.png` | no | Client logo in Settings → About and help (PNG, at most 2048 × 2048) |
|
||||
|
||||
`edition.json` fields: `id` (must equal the folder name; lowercase letters, digits, hyphens), `displayName`
|
||||
and `companyName` (at most 180 characters), optional `tagline` and `description`, optional `supportUrl`
|
||||
(HTTPS), optional `accentColor` (`#RRGGBB`, used only when white text stays readable on it) and
|
||||
`assetPrefix` (2 to 40 letters or digits; the MSI and release asset name). Optional `serverName` is what
|
||||
user-facing text calls the server ("Sign in to GG Forge", "GG Forge authorization required"); the generic
|
||||
build says QQQ. Optional `aboutMascot` and `aboutLicense` (default true) set to `false` leave the Query
|
||||
mascot section and the License section out of the About dialog; the header (name, tagline, version) and the
|
||||
Open source components credits always remain, as does the copyright in the installed LICENSE and NOTICE.
|
||||
|
||||
An edition changes presentation and labels only. Application id, data paths, executable file names,
|
||||
the install directory, the protocol handler, the MSI upgrade identity and the signing identity are
|
||||
shared with every other edition, so editions upgrade each other and the generic build in place.
|
||||
See docs/BRANDING.md.
|
||||
@@ -1,12 +0,0 @@
|
||||
<svg width="78" height="78" viewBox="0 0 78 78" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<g clip-path="url(#clip0_8440_398)">
|
||||
<path d="M39.0011 0H38.9989C17.4604 0 0 17.4604 0 38.9989V39.0011C0 60.5396 17.4604 78 38.9989 78H39.0011C60.5396 78 78 60.5396 78 39.0011V38.9989C78 17.4604 60.5396 0 39.0011 0Z" fill="#E2AB44"/>
|
||||
<path d="M55.3877 26.4839L53.9782 26.0657C53.8211 26.0214 53.6574 26.1144 53.6131 26.2737C51.9957 31.1283 45.2624 32.9007 40.3059 34.2593L39.4718 34.4673C39.3678 34.5204 39.2638 34.4142 39.2638 34.2593C39.6289 32.6927 41.1423 26.9021 41.5606 25.4926C41.6048 25.3355 41.5119 25.1717 41.3526 25.1275L39.9431 24.6584C39.786 24.6141 39.6222 24.7071 39.578 24.8664C39.578 24.9195 39.5249 24.9704 39.5249 25.0235C39.5005 25.0899 39.4275 25.1253 39.3611 25.1009C39.3456 25.0943 39.3301 25.0854 39.3169 25.0744C39.0226 24.6761 38.6708 24.3243 38.2725 24.03C35.6084 22.1005 31.2803 23.5609 28.6693 27.3181C26.0606 31.0221 26.1646 35.5648 28.9304 37.4943C29.207 37.6824 29.5057 37.8395 29.8177 37.9634C29.904 38.0054 29.9416 38.1072 29.8996 38.1957C29.8819 38.2311 29.8531 38.2599 29.8177 38.2776C28.1405 39.3176 26.6292 40.6031 25.3282 42.0879C23.7129 43.9156 22.0932 47.2036 22.4583 50.1775C22.6087 51.6777 23.3633 53.0518 24.5449 53.9878C25.4454 54.6627 26.5496 55.0123 27.6758 54.9791C29.5035 54.9791 31.329 54.1449 32.7385 53.0474C36.3917 50.1222 36.9648 46.6283 37.487 43.2894C37.5401 42.9774 38.5823 37.1845 38.5823 37.1845C38.6331 36.95 38.8168 36.7663 39.0513 36.7154C39.6244 36.5583 40.1997 36.4034 40.8237 36.2463C46.2537 34.7859 53.664 32.8011 55.5957 26.8534C55.64 26.6963 55.5471 26.5326 55.3877 26.4883C55.3877 26.4883 55.3855 26.4883 55.3833 26.4883L55.3877 26.4839ZM35.5044 42.9752C34.9822 46.2101 34.5662 48.976 31.4861 51.4299C29.8686 52.6823 27.4147 53.5187 25.7973 52.3172C25.0648 51.7264 24.6112 50.8568 24.5449 49.9164C24.3369 47.9847 25.3282 45.2719 26.8948 43.4465C28.4348 41.7206 30.2736 40.2889 32.3225 39.218C33.5727 38.5675 34.8826 38.043 36.2368 37.6514C36.3408 37.5983 36.4448 37.7045 36.4448 37.8085C36.1328 39.2689 35.5575 42.7141 35.5066 42.9752H35.5044ZM37.0179 34.8346C36.9714 35.0537 36.8121 35.2329 36.5997 35.3037C36.0266 35.5117 34.8782 35.8768 34.8273 35.8768C31.9574 36.815 30.5479 36.1379 30.0788 35.8237C28.3065 34.5713 28.4082 31.2301 30.3399 28.5174C32.2716 25.8046 35.3495 24.55 37.1219 25.7515C38.2172 26.4817 38.6354 28.0483 38.2703 29.8737C37.8012 31.6483 37.3299 33.5269 37.0179 34.8324V34.8346Z" fill="#FFFFFF"/>
|
||||
<path d="M49.4369 41.8775C50.78 41.8643 52.0811 42.3488 53.0901 43.2361C53.2096 43.3401 53.3888 43.3401 53.5083 43.2361L54.5527 42.1917C54.6567 42.0723 54.6567 41.893 54.5527 41.7735C51.5633 38.9966 46.8879 39.167 44.1088 42.1563C41.3318 45.1457 41.5022 49.8211 44.4915 52.6003C45.9829 53.9855 47.9788 54.6957 50.01 54.5608C51.6452 54.4324 53.1963 53.7929 54.4465 52.7309C54.6036 52.6003 54.6965 52.4122 54.7076 52.2087V46.834C54.6965 46.6658 54.5616 46.5331 54.3956 46.522H49.386C49.2179 46.5331 49.0851 46.668 49.0741 46.834V48.2944C49.0851 48.4625 49.2201 48.5953 49.386 48.6064H52.309C52.4772 48.6174 52.61 48.7524 52.621 48.9184V51.162C52.6409 51.4143 52.4927 51.6466 52.2559 51.7351C51.4306 52.2131 50.4946 52.4653 49.5431 52.4653C46.618 52.4941 44.2238 50.1464 44.1928 47.2212C44.1641 44.296 46.5117 41.9019 49.4369 41.8709V41.8775Z" fill="#FFFFFF"/>
|
||||
</g>
|
||||
<defs>
|
||||
<clipPath id="clip0_8440_398">
|
||||
<rect width="78" height="78" fill="#E2AB44"/>
|
||||
</clipPath>
|
||||
</defs>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 3.4 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 22 KiB |
@@ -1,12 +0,0 @@
|
||||
{
|
||||
"id": "gg-forge",
|
||||
"displayName": "GG Forge Print Agent",
|
||||
"companyName": "Greater Goods",
|
||||
"tagline": "Cloud printing for GG Forge",
|
||||
"description": "Connect local printers to GG Forge.",
|
||||
"accentColor": "#424242",
|
||||
"assetPrefix": "GgForgePrintAgent",
|
||||
"serverName": "GG Forge",
|
||||
"aboutMascot": false,
|
||||
"aboutLicense": false
|
||||
}
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 11 KiB |
@@ -1,84 +0,0 @@
|
||||
// Copyright (c) 2026 James Maes
|
||||
// SPDX-License-Identifier: MIT
|
||||
// Based on K22 fbfc8d2cf3b5e16ae9750b04cf9de1794f1e7152.
|
||||
// KofTwentyTwo TypeScript / JavaScript lint configuration (K22-CODE-TS).
|
||||
// The Kingsrook layout (3-space indent, Allman braces, if(...) with no space, no more than
|
||||
// one blank line inside code) is enforced by ESLint Stylistic rather than Prettier, which
|
||||
// cannot express Allman braces. Type-aware strict rules come from typescript-eslint.
|
||||
// Install: npm i -D eslint @eslint/js typescript-eslint @stylistic/eslint-plugin typescript
|
||||
import js from "@eslint/js";
|
||||
import stylistic from "@stylistic/eslint-plugin";
|
||||
import tseslint from "typescript-eslint";
|
||||
|
||||
export default tseslint.config(
|
||||
{
|
||||
ignores: ["**", "!tools/", "!tools/**", "!eslint.config.mjs"],
|
||||
},
|
||||
js.configs.recommended,
|
||||
tseslint.configs.strictTypeChecked,
|
||||
tseslint.configs.stylisticTypeChecked,
|
||||
{
|
||||
languageOptions: {
|
||||
globals: { process: "readonly", console: "readonly", Buffer: "readonly", URL: "readonly", fetch: "readonly", WebSocket: "readonly", setTimeout: "readonly", clearTimeout: "readonly", structuredClone: "readonly", performance: "readonly", AbortController: "readonly", Headers: "readonly", FormData: "readonly", setInterval: "readonly", clearInterval: "readonly" },
|
||||
parserOptions: {
|
||||
projectService: true,
|
||||
tsconfigRootDir: import.meta.dirname,
|
||||
},
|
||||
},
|
||||
plugins: { "@stylistic": stylistic },
|
||||
rules: {
|
||||
// Kingsrook layout
|
||||
"@stylistic/indent": ["error", 3, { SwitchCase: 1 }],
|
||||
"@stylistic/brace-style": ["error", "allman", { allowSingleLine: false }],
|
||||
"@stylistic/keyword-spacing": ["error", {
|
||||
before: true,
|
||||
after: true,
|
||||
overrides: {
|
||||
if: { after: false },
|
||||
for: { after: false },
|
||||
while: { after: false },
|
||||
switch: { after: false },
|
||||
catch: { after: false },
|
||||
},
|
||||
}],
|
||||
// 1 blank line inside code; up to 3 so methods can be separated by 3.
|
||||
"@stylistic/no-multiple-empty-lines": ["error", { max: 3, maxBOF: 0, maxEOF: 0 }],
|
||||
"@stylistic/lines-between-class-members": ["error", "always", { exceptAfterSingleLine: true }],
|
||||
"@stylistic/semi": ["error", "always"],
|
||||
"@stylistic/quotes": ["error", "double", { avoidEscape: true }],
|
||||
"@stylistic/comma-dangle": ["error", "always-multiline"],
|
||||
"@stylistic/eol-last": ["error", "always"],
|
||||
"@stylistic/no-tabs": "error",
|
||||
"@stylistic/no-trailing-spaces": "error",
|
||||
"@stylistic/operator-linebreak": ["error", "before"],
|
||||
"@stylistic/dot-location": ["error", "property"],
|
||||
"@stylistic/max-len": "off",
|
||||
|
||||
// Kingsrook non-layout rules
|
||||
"curly": ["error", "all"],
|
||||
"eqeqeq": ["error", "always"],
|
||||
"no-console": "error",
|
||||
"no-warning-comments": ["error", { terms: ["todo", "fixme"], location: "start" }],
|
||||
"@typescript-eslint/explicit-function-return-type": "error",
|
||||
"@typescript-eslint/naming-convention": ["error",
|
||||
{ selector: "default", format: ["camelCase"] },
|
||||
{ selector: "variable", modifiers: ["const", "global"], format: ["camelCase", "UPPER_CASE"] },
|
||||
{ selector: "typeLike", format: ["PascalCase"] },
|
||||
{ selector: "enumMember", format: ["PascalCase", "UPPER_CASE"] },
|
||||
{ selector: "import", format: null },
|
||||
{ selector: "objectLiteralProperty", format: null },
|
||||
],
|
||||
},
|
||||
},
|
||||
{
|
||||
files: ["**/*.js", "**/*.mjs", "**/*.cjs"],
|
||||
extends: [tseslint.configs.disableTypeChecked],
|
||||
// Checked JavaScript uses JSDoc plus strict tsc; TS-only return syntax is unavailable.
|
||||
rules: { "@typescript-eslint/explicit-function-return-type": "off" },
|
||||
},
|
||||
{
|
||||
files: ["tools/**/*.mjs"],
|
||||
// These command-line tools intentionally print their results and diagnostics.
|
||||
rules: { "no-console": ["error", { allow: ["log", "error"] }] },
|
||||
},
|
||||
);
|
||||
@@ -1,8 +1,3 @@
|
||||
<!--
|
||||
Copyright (c) 2026 James Maes
|
||||
SPDX-License-Identifier: MIT
|
||||
-->
|
||||
|
||||
<Project>
|
||||
<!-- MSI authoring is not a C# compilation; do not inherit runtime analyzers. -->
|
||||
<PropertyGroup>
|
||||
|
||||
+3
-17
@@ -1,24 +1,13 @@
|
||||
<!--
|
||||
Copyright (c) 2026 James Maes
|
||||
SPDX-License-Identifier: MIT
|
||||
-->
|
||||
|
||||
<Wix xmlns="http://wixtoolset.org/schemas/v4/wxs" xmlns:util="http://wixtoolset.org/schemas/v4/wxs/util">
|
||||
<Package Name="$(BrandName)" Manufacturer="$(BrandCompany)" Version="$(ProductVersion)"
|
||||
<Package Name="QQQ Print Agent" Manufacturer="QRun-IO" Version="$(ProductVersion)"
|
||||
UpgradeCode="D761CD03-F616-4C98-9A94-9F590A36E449" Scope="perMachine" InstallerVersion="500">
|
||||
<!-- Execute the protected-state preflight before removing the previous product.
|
||||
Deferred actions are queued until InstallExecute, not run at their table slot.
|
||||
Stable component GUIDs preserve shared files/service during old-product removal. -->
|
||||
<MajorUpgrade AllowSameVersionUpgrades="yes" Schedule="afterInstallExecute" DowngradeErrorMessage="A newer print connector is already installed." />
|
||||
<MediaTemplate EmbedCab="yes" CompressionLevel="high" />
|
||||
<?if $(BrandForced) = 1 ?>
|
||||
<!-- An edition build carries its client's identity and applies it over any labels an earlier install stored. -->
|
||||
<Property Id="BRANDNAME" Secure="yes" Value="$(BrandName)" />
|
||||
<Property Id="BRANDCOMPANY" Secure="yes" Value="$(BrandCompany)" />
|
||||
<?else?>
|
||||
<Property Id="BRANDNAME" Secure="yes" />
|
||||
<Property Id="BRANDCOMPANY" Secure="yes" />
|
||||
<?endif?>
|
||||
<Property Id="STORED_BRAND_NAME">
|
||||
<RegistrySearch Id="FindBrandName" Root="HKLM" Key="SOFTWARE\QRunIO\PrintAgent" Name="DisplayName" Type="raw" Bitness="always64" />
|
||||
</Property>
|
||||
@@ -26,9 +15,9 @@
|
||||
<RegistrySearch Id="FindBrandCompany" Root="HKLM" Key="SOFTWARE\QRunIO\PrintAgent" Name="CompanyName" Type="raw" Bitness="always64" />
|
||||
</Property>
|
||||
<SetProperty Id="BRANDNAME" Action="UseStoredBrandName" Value="[STORED_BRAND_NAME]" After="AppSearch" Condition="NOT BRANDNAME AND STORED_BRAND_NAME" />
|
||||
<SetProperty Id="BRANDNAME" Action="UseDefaultBrandName" Value="$(BrandName)" After="UseStoredBrandName" Condition="NOT BRANDNAME" />
|
||||
<SetProperty Id="BRANDNAME" Action="UseDefaultBrandName" Value="QQQ Print Agent" After="UseStoredBrandName" Condition="NOT BRANDNAME" />
|
||||
<SetProperty Id="BRANDCOMPANY" Action="UseStoredBrandCompany" Value="[STORED_BRAND_COMPANY]" After="UseDefaultBrandName" Condition="NOT BRANDCOMPANY AND STORED_BRAND_COMPANY" />
|
||||
<SetProperty Id="BRANDCOMPANY" Action="UseDefaultBrandCompany" Value="$(BrandCompany)" After="UseStoredBrandCompany" Condition="NOT BRANDCOMPANY" />
|
||||
<SetProperty Id="BRANDCOMPANY" Action="UseDefaultBrandCompany" Value="QRun-IO" After="UseStoredBrandCompany" Condition="NOT BRANDCOMPANY" />
|
||||
<SetProperty Id="ProductName" Action="SetBrandedProductName" Value="[BRANDNAME]" After="UseDefaultBrandCompany" />
|
||||
<SetProperty Id="Manufacturer" Action="SetBrandedManufacturer" Value="[BRANDCOMPANY]" After="SetBrandedProductName" />
|
||||
<CustomAction Id="ValidateMachineStateBeforeFolders" Directory="System64Folder" ExeCommand=""[System64Folder]WindowsPowerShell\v1.0\powershell.exe" -NoProfile -NonInteractive -Command "$ErrorActionPreference='Stop'; $trusted=@('S-1-5-18','S-1-5-32-544','S-1-5-80-956008885-3418522649-1831038044-1853292631-2271478464'); function AssertNode([\[]string[\]]$p) [\{] $i=Get-Item -LiteralPath $p -Force; if($i.Attributes -band [\[]IO.FileAttributes[\]]::ReparsePoint) [\{] throw 'Machine print state contains a link. Installation refused.' [\}]; $a=$i.GetAccessControl(); if($a.GetOwner([\[]Security.Principal.SecurityIdentifier[\]]).Value -notin $trusted) [\{] throw 'Machine print state has an untrusted owner. Installation refused.' [\}]; $raw=[\[]Security.AccessControl.RawSecurityDescriptor[\]]::new($a.GetSecurityDescriptorBinaryForm(),0); if($null -eq $raw.DiscretionaryAcl) [\{] throw 'Machine print state has no ACL.' [\}]; foreach($r in $a.GetAccessRules($true,$true,[\[]Security.Principal.SecurityIdentifier[\]])) [\{] if($r.AccessControlType -eq 'Allow' -and [\[]int[\]]$r.FileSystemRights -ne 0 -and $r.IdentityReference.Value -notin $trusted) [\{] throw 'Machine print state permits untrusted access. Installation refused.' [\}] [\}]; if($i.PSIsContainer) [\{] foreach($c in [\[]IO.Directory[\]]::EnumerateFileSystemEntries($p)) [\{] AssertNode $c [\}] [\}] [\}]; try [\{] $root=Join-Path ([\[]Environment[\]]::GetFolderPath('CommonApplicationData')) 'QqqPrintAgent'; for($p=$root;$p;$p=[\[]IO.Path[\]]::GetDirectoryName($p)) [\{] if(Test-Path -LiteralPath $p) [\{] if((Get-Item -LiteralPath $p -Force).Attributes -band [\[]IO.FileAttributes[\]]::ReparsePoint) [\{] throw 'Machine print state path contains a link.' [\}] [\}] [\}]; if(-not [\[]IO.Directory[\]]::Exists($root)) [\{] $acl=[\[]Security.AccessControl.DirectorySecurity[\]]::new(); $acl.SetSecurityDescriptorSddlForm('O:SYG:SYD:P(A;OICI;FA;;;SY)(A;OICI;FA;;;BA)'); [\[]IO.DirectoryInfo[\]]::new($root).Create($acl) [\}]; AssertNode $root; exit 0 [\}] catch [\{] [\[]Console[\]]::Error.WriteLine($_.Exception.Message); exit 1 [\}]"" Execute="deferred" Impersonate="no" Return="check" />
|
||||
@@ -67,9 +56,6 @@
|
||||
<Directory Id="APPDIR" Name="App">
|
||||
<Component Id="AgentCompanion" Guid="2FD52718-B33B-42AA-9E28-21B3B70FA4BB" Bitness="always64">
|
||||
<File Id="CompanionExe" Source="$(PayloadRoot)\app\Qqq.PrintAgent.exe" KeyPath="yes" />
|
||||
<RegistryValue Root="HKLM" Key="SOFTWARE\Classes\io.qrun.qqq-print-agent" Type="string" Value="URL:[BRANDNAME] sign-in" />
|
||||
<RegistryValue Root="HKLM" Key="SOFTWARE\Classes\io.qrun.qqq-print-agent" Name="URL Protocol" Type="string" Value="" />
|
||||
<RegistryValue Root="HKLM" Key="SOFTWARE\Classes\io.qrun.qqq-print-agent\shell\open\command" Type="string" Value=""[CLIDIR]qqq-print-agent.exe" --auth-callback "%1"" />
|
||||
</Component>
|
||||
<Files Include="$(PayloadRoot)\app\**">
|
||||
<Exclude Files="$(PayloadRoot)\app\Qqq.PrintAgent.exe" />
|
||||
|
||||
@@ -1,22 +1,11 @@
|
||||
<!--
|
||||
Copyright (c) 2026 James Maes
|
||||
SPDX-License-Identifier: MIT
|
||||
-->
|
||||
|
||||
<Project Sdk="WixToolset.Sdk/6.0.2">
|
||||
<PropertyGroup>
|
||||
<OutputType>Package</OutputType>
|
||||
<InstallerPlatform>x64</InstallerPlatform>
|
||||
<ProductVersion Condition="'$(ProductVersion)' == ''">0.3.0</ProductVersion>
|
||||
<ProductVersion Condition="'$(ProductVersion)' == ''">0.1.8</ProductVersion>
|
||||
<PayloadRoot Condition="'$(PayloadRoot)' == ''">$(MSBuildThisFileDirectory)..\artifacts\package</PayloadRoot>
|
||||
<!-- Client editions: the build script passes the edition's names, forces them over any stored labels and names the
|
||||
MSI after the edition's asset prefix; the generic build keeps the defaults below. -->
|
||||
<MsiBaseName Condition="'$(MsiBaseName)' == ''">QqqPrintAgent</MsiBaseName>
|
||||
<BrandName Condition="'$(BrandName)' == ''">QQQ Print Agent</BrandName>
|
||||
<BrandCompany Condition="'$(BrandCompany)' == ''">QRun-IO</BrandCompany>
|
||||
<BrandForced Condition="'$(BrandForced)' == ''">0</BrandForced>
|
||||
<OutputName>$(MsiBaseName)-$(ProductVersion)-x64</OutputName>
|
||||
<DefineConstants>ProductVersion=$(ProductVersion);PayloadRoot=$(PayloadRoot);BrandName=$(BrandName);BrandCompany=$(BrandCompany);BrandForced=$(BrandForced)</DefineConstants>
|
||||
<OutputName>QqqPrintAgent-$(ProductVersion)-x64</OutputName>
|
||||
<DefineConstants>ProductVersion=$(ProductVersion);PayloadRoot=$(PayloadRoot)</DefineConstants>
|
||||
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
|
||||
<!-- Bundled Microsoft WinUI DLLs contain multi-language version resources exceeding
|
||||
ICE03's Language-column limit, and newer MUI LCIDs absent from its static list.
|
||||
|
||||
+4
-4
@@ -3,7 +3,7 @@
|
||||
Build the service, AppKit companion and CLI into one x64 machine MSI:
|
||||
|
||||
```powershell
|
||||
./build/Build-Installer.ps1 -ProductVersion 1.0.1 -ReleaseVersion 1.0.1
|
||||
./build/Build-Installer.ps1 -ProductVersion 0.1.8 -ReleaseVersion 0.1.8-rc.1
|
||||
```
|
||||
|
||||
The build publishes self-contained .NET applications into a fresh per-run directory under `artifacts/package` and builds WiX 6.0.2 authoring. An explicit publish directory must not already exist; this prevents obsolete files from entering the harvested MSI. Existing reviewed outputs can be packaged using `-SkipPublish -PayloadDirectory <path>`; all component versions must match the requested release and source version. The resulting MSI is local development output and is **unsigned unless a signing certificate is explicitly provided**.
|
||||
@@ -11,10 +11,10 @@ The build publishes self-contained .NET applications into a fresh per-run direct
|
||||
For a signing certificate already installed in the Windows certificate store:
|
||||
|
||||
```powershell
|
||||
./build/Build-Installer.ps1 -ProductVersion 1.0.1 -ReleaseVersion 1.0.1 -CertificateThumbprint '<thumbprint>' -TimestampServer 'https://your-approved-timestamp-service'
|
||||
./build/Build-Installer.ps1 -ProductVersion 0.1.3 -ReleaseVersion 0.1.3-rc.1 -CertificateThumbprint '<thumbprint>' -TimestampServer 'https://your-approved-timestamp-service'
|
||||
```
|
||||
|
||||
Signing needs `signtool.exe` on PATH. The script signs the first-party executables before packaging and signs/verifies the resulting MSI. Stable releases are signed by the release workflow with Azure Artifact Signing instead; see [RELEASE-SIGNING.md](../docs/RELEASE-SIGNING.md). Never store signing secrets here.
|
||||
Signing needs `signtool.exe` on PATH. The script signs the first-party executables before packaging and signs/verifies the resulting MSI. Use the existing organization signing workflow for distribution; never store signing secrets here.
|
||||
|
||||
Install the resulting MSI through an elevated Windows Installer session. It installs `QqqPrintAgent` as an automatic LocalSystem service, depends on the Windows Spooler, starts the service, and adds the companion to the Start menu. Configure and test printers accessible to LocalSystem; user-only network printer mappings are not sufficient. The current companion's management pipe requires local administrator access.
|
||||
|
||||
@@ -36,4 +36,4 @@ The installer suppresses MSI validator ICE03 because the bundled Microsoft WinUI
|
||||
|
||||
References: [WiX service installation](https://docs.firegiant.com/wix/schema/wxs/serviceinstall/), [file harvesting](https://docs.firegiant.com/wix/schema/wxs/files/), [MSI directory security](https://docs.firegiant.com/wix/schema/wxs/permissionex/).
|
||||
|
||||
The signed stable [1.0.1 MSI](https://git.kof22.com/QRun-IO/qqq-print-agent/releases/tag/v1.0.1) is published and installed. See [release readiness](../docs/RELEASE-READINESS.md) for the dated release and installation evidence. Same-numeric-version upgrades support RC transitions; the updater separately enforces a strictly newer semantic version.
|
||||
The 0.1.3-rc.1 source gate passed 163 tests with zero warnings/errors. The new MSI is being packaged; installed startup/UI and actual in-app upgrade acceptance remain pending. Same-numeric-version upgrades support RC transitions; the updater separately enforces a strictly newer semantic version.
|
||||
File diff suppressed because it is too large.
Load diff
@@ -1,51 +0,0 @@
|
||||
MICROSOFT SOFTWARE LICENSE TERMS
|
||||
Microsoft Windows ML Runtime
|
||||
________________________________________
|
||||
IF YOU LIVE IN (OR ARE A BUSINESS WITH A PRINCIPAL PLACE OF BUSINESS IN) THE UNITED STATES, PLEASE READ THE “BINDING ARBITRATION AND CLASS ACTION WAIVER” SECTION BELOW. IT AFFECTS HOW DISPUTES ARE RESOLVED.
|
||||
________________________________________
|
||||
These license terms are an agreement between you and Microsoft Corporation (or one of its affiliates). They apply to the software named above and any Microsoft services or software updates (except to the extent such services or updates are accompanied by new or additional terms, in which case those different terms apply prospectively and do not alter your or Microsoft’s rights relating to pre-updated software or services). IF YOU COMPLY WITH THESE LICENSE TERMS, YOU HAVE THE RIGHTS BELOW. BY USING THE SOFTWARE, YOU ACCEPT THESE TERMS.
|
||||
1. INSTALLATION AND USE RIGHTS.
|
||||
a) General. Subject to the terms of this agreement, you may install and use any number of copies of the software to develop and test your applications, solely for use on Windows. When building Generative AI applications follow the guidelines in https://learn.microsoft.com/windows/ai/rai.
|
||||
b) Included Microsoft Applications. The software may include other Microsoft applications. These license terms apply to those included applications, if any, unless other license terms are provided with the other Microsoft applications.
|
||||
c) Microsoft Platforms. The software may include components from Microsoft Windows. These components are governed by separate agreements and their own product support policies, as described in the license terms found in the installation directory for that component or in the “Licenses” folder accompanying the software.
|
||||
d) Third Party Materials. The software may use or include source code, object code, or data available under an open source or open data license (“Open Source Materials”) or a proprietary license from a third party (with Open Source Materials, collectively, “Third Party Materials”) that are licensed under the specific license terms applicable to the Third Party Materials (an “Third Party License Agreement”). To the extent that any Third Party License Agreement requires that the corresponding Third Party Materials be licensed under terms that are different from the terms set forth in this Agreement, then such Third Party Materials are licensed under the terms of that Third Party License Agreement and the other terms and conditions in this Agreement will not apply with respect to those Third Party Materials. You (a) acknowledge that any such Third Party License Agreement is solely between Licensee and the applicable licensor of the Third Party Materials, and (b) will comply with the terms of any such Third Party License Agreement. Without limitation to the foregoing, the licenses referenced on this website (https://learn.microsoft.com/en-us/windows/ai/new-windows-ml/supported-execution-providers) are deemed to be “Third Party Materials.”
|
||||
2. DATA.
|
||||
a) Data Collection. The software may collect information about you and your use of the software, and send that to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may opt-out of many of these scenarios, but not all, as described in the product documentation. There are also some features in the software that may enable you to collect data from users of your applications. If you use these features to enable data collection in your applications, you must comply with applicable law, including providing appropriate notices to users of your applications. You can learn more about data collection and use in the help documentation and the privacy statement at https://aka.ms/privacy. Your use of the software operates as your consent to these practices.
|
||||
b) Processing of Personal Data. To the extent Microsoft is a processor or subprocessor of personal data in connection with the software, Microsoft makes the commitments in the European Union General Data Protection Regulation Terms of the Online Services Terms to all customers effective May 25, 2018, at https://docs.microsoft.com/en-us/legal/gdpr.
|
||||
3. DISTRIBUTABLE CODE. The software may contain code you are permitted to distribute (i.e. make available for third parties) in applications you develop, as described in this Section.
|
||||
a) Distribution Rights. The code and test files described below are distributable if included with the software.
|
||||
i. Any files that are binplaced with your application by the WindowsAppSDK NuGet package are, by definition, permitted to be redistributed. This applies to both framework package dependent and self-contained deployments.
|
||||
ii. Image Library. You may copy and distribute images, graphics, and animations in the Image Library as described in the software documentation; and
|
||||
iii. Third Party Distribution. You may permit distributors of your applications to copy and distribute any of this distributable code you elect to distribute with your applications.
|
||||
b) Distribution Requirements. For any code you distribute, you must:
|
||||
i. add significant primary functionality to it in your applications;
|
||||
ii. require distributors and external end users to agree to terms that protect it and Microsoft at least as much as this agreement; and
|
||||
iii. indemnify, defend, and hold harmless Microsoft from any claims, including attorneys’ fees, related to the distribution or use of your applications, except to the extent that any claim is based solely on the unmodified distributable code.
|
||||
c) Distribution Restrictions. You may not:
|
||||
i. use Microsoft’s trademarks or trade dress in your application in any way that suggests your application comes from or is endorsed by Microsoft; or
|
||||
ii. modify or distribute the source code of any distributable code so that any part of it becomes subject to any license that requires that the distributable code, any other part of the software, or any of Microsoft’s other intellectual property be disclosed or distributed in source code form, or that others have the right to modify it.
|
||||
4. SCOPE OF LICENSE. The software is licensed, not sold. Microsoft reserves all other rights. Unless applicable law gives you more rights despite this limitation, you will not (and have no right to):
|
||||
a) work around any technical limitations in the software that only allow you to use it in certain ways;
|
||||
b) reverse engineer, decompile or disassemble the software, or otherwise attempt to derive the source code for the software, except and to the extent required by third party licensing terms governing use of certain open source components that may be included in the software;
|
||||
c) remove, minimize, block, or modify any notices of Microsoft or its suppliers in the software;
|
||||
d) use the software in any way that is against the law or to create or propagate malware; or
|
||||
e) share, publish, distribute, or lease the software (except for any distributable code, subject to the terms above), provide the software as a stand-alone offering for others to use, or transfer the software or this agreement to any third party.
|
||||
5. EXPORT RESTRICTIONS. You must comply with all domestic and international export laws and regulations that apply to the software, which include restrictions on destinations, end users, and end use. For further information on export restrictions, visit https://aka.ms/exporting.
|
||||
6. SUPPORT SERVICES. Microsoft is not obligated under this agreement to provide any support services for the software. Any support provided is “as is”, “with all faults”, and without warranty of any kind.
|
||||
7. UPDATES. The software may periodically check for updates, and download and install them for you. You may obtain updates only from Microsoft or authorized sources. Microsoft may need to update your system to provide you with updates. You agree to receive these automatic updates without any additional notice. Updates may not include or support all existing software features, services, or peripheral devices.
|
||||
8. BINDING ARBITRATION AND CLASS ACTION WAIVER. This Section applies if you live in (or, if a business, your principal place of business is in) the United States. If you and Microsoft have a dispute, you and Microsoft agree to try for 60 days to resolve it informally. If you and Microsoft can’t, you and Microsoft agree to binding individual arbitration before the American Arbitration Association under the Federal Arbitration Act (“FAA”), and not to sue in court in front of a judge or jury. Instead, a neutral arbitrator will decide. Class action lawsuits, class-wide arbitrations, private attorney-general actions, and any other proceeding where someone acts in a representative capacity are not allowed; nor is combining individual proceedings without the consent of all parties. The complete Arbitration Agreement contains more terms and is at https://aka.ms/arb-agreement-4. You and Microsoft agree to these terms.
|
||||
9. ENTIRE AGREEMENT. This agreement, and any other terms Microsoft may provide for supplements, updates, or third-party applications, is the entire agreement for the software.
|
||||
10. APPLICABLE LAW AND PLACE TO RESOLVE DISPUTES. If you acquired the software in the United States or Canada, the laws of the state or province where you live (or, if a business, where your principal place of business is located) govern the interpretation of this agreement, claims for its breach, and all other claims (including consumer protection, unfair competition, and tort claims), regardless of conflict of laws principles, except that the FAA governs everything related to arbitration. If you acquired the software in any other country, its laws apply, except that the FAA governs everything related to arbitration. If U.S. federal jurisdiction exists, you and Microsoft consent to exclusive jurisdiction and venue in the federal court in King County, Washington for all disputes heard in court (excluding arbitration). If not, you and Microsoft consent to exclusive jurisdiction and venue in the Superior Court of King County, Washington for all disputes heard in court (excluding arbitration).
|
||||
11. CONSUMER RIGHTS; REGIONAL VARIATIONS. This agreement describes certain legal rights. You may have other rights, including consumer rights, under the laws of your state or country. Separate and apart from your relationship with Microsoft, you may also have rights with respect to the party from which you acquired the software. This agreement does not change those other rights if the laws of your state or country do not permit it to do so. For example, if you acquired the software in one of the below regions, or mandatory country law applies, then the following provisions apply to you:
|
||||
a) Australia. You have statutory guarantees under the Australian Consumer Law and nothing in this agreement is intended to affect those rights.
|
||||
b) Canada. If you acquired this software in Canada, you may stop receiving updates by turning off the automatic update feature, disconnecting your device from the Internet (if and when you re-connect to the Internet, however, the software will resume checking for and installing updates), or uninstalling the software. The product documentation, if any, may also specify how to turn off updates for your specific device or software.
|
||||
c) Germany and Austria.
|
||||
i. Warranty. The properly licensed software will perform substantially as described in any Microsoft materials that accompany the software. However, Microsoft gives no contractual guarantee in relation to the licensed software.
|
||||
ii. Limitation of Liability. In case of intentional conduct, gross negligence, claims based on the Product Liability Act, as well as, in case of death or personal or physical injury, Microsoft is liable according to the statutory law.
|
||||
Subject to the foregoing clause ii., Microsoft will only be liable for slight negligence if Microsoft is in breach of such material contractual obligations, the fulfillment of which facilitate the due performance of this agreement, the breach of which would endanger the purpose of this agreement and the compliance with which a party may constantly trust in (so-called "cardinal obligations"). In other cases of slight negligence, Microsoft will not be liable for slight negligence.
|
||||
12. DISCLAIMER OF WARRANTY. THE SOFTWARE IS LICENSED “AS IS.” YOU BEAR THE RISK OF USING IT. MICROSOFT GIVES NO EXPRESS WARRANTIES, GUARANTEES, OR CONDITIONS. TO THE EXTENT PERMITTED UNDER APPLICABLE LAWS, MICROSOFT EXCLUDES ALL IMPLIED WARRANTIES, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
|
||||
13. LIMITATION ON AND EXCLUSION OF DAMAGES. IF YOU HAVE ANY BASIS FOR RECOVERING DAMAGES DESPITE THE PRECEDING DISCLAIMER OF WARRANTY, YOU CAN RECOVER FROM MICROSOFT AND ITS SUPPLIERS ONLY DIRECT DAMAGES UP TO U.S. $5.00. YOU CANNOT RECOVER ANY OTHER DAMAGES, INCLUDING CONSEQUENTIAL, LOST PROFITS, SPECIAL, INDIRECT, OR INCIDENTAL DAMAGES.
|
||||
|
||||
This limitation applies to (a) anything related to the software, services, content (including code) on third party Internet sites, or third party applications; and (b) claims for breach of contract, warranty, guarantee, or condition; strict liability, negligence, or other tort; or any other claim; in each case to the extent permitted by applicable law.
|
||||
|
||||
It also applies even if Microsoft knew or should have known about the possibility of the damages. The above limitation or exclusion may not apply to you because your state, province, or country may not allow the exclusion or limitation of incidental, consequential, or other damages.
|
||||
@@ -1,51 +0,0 @@
|
||||
NOTICES AND INFORMATION
|
||||
Do Not Translate or Localize
|
||||
|
||||
This software incorporates material from third parties.
|
||||
Microsoft makes certain open source code available at https://3rdpartysource.microsoft.com,
|
||||
or you may send a check or money order for US $5.00, including the product name,
|
||||
the open source component name, platform, and version number, to:
|
||||
|
||||
Source Code Compliance Team
|
||||
Microsoft Corporation
|
||||
One Microsoft Way
|
||||
Redmond, WA 98052
|
||||
USA
|
||||
|
||||
Notwithstanding any other terms, you may reverse engineer this software to the extent
|
||||
required to debug changes to any libraries licensed under the GNU Lesser General Public License.
|
||||
|
||||
---------------------------------------------------------
|
||||
|
||||
Newtonsoft.Json 13.0.3 - MIT
|
||||
|
||||
|
||||
Copyright James Newton-King 2008
|
||||
Copyright (c) 2007 James Newton-King
|
||||
Copyright (c) James Newton-King 2008
|
||||
Copyright James Newton-King 2008 Json.NET
|
||||
|
||||
The MIT License (MIT)
|
||||
|
||||
Copyright (c) 2007 James Newton-King
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy of
|
||||
this software and associated documentation files (the "Software"), to deal in
|
||||
the Software without restriction, including without limitation the rights to
|
||||
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
|
||||
the Software, and to permit persons to whom the Software is furnished to do so,
|
||||
subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
|
||||
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
||||
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
|
||||
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
||||
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
|
||||
---------------------------------------------------------
|
||||
|
||||
@@ -1,651 +0,0 @@
|
||||
**MICROSOFT SOFTWARE LICENSE TERMS**
|
||||
|
||||
**MICROSOFT WINDOWS SOFTWARE DEVELOPMENT KIT (SDK) FOR WINDOWS 10 **
|
||||
|
||||
\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
|
||||
|
||||
These license terms are an agreement between Microsoft Corporation (or
|
||||
based on where you live, one of its affiliates) and you. Please read
|
||||
them. They apply to the software named above, which includes the media
|
||||
on which you received it, if any. The terms also apply to any Microsoft
|
||||
|
||||
- APIs (i.e., APIs included with the installation of the SDK or APIs
|
||||
accessed by installing extension packages or service to use with the
|
||||
SDK),
|
||||
|
||||
- updates,
|
||||
|
||||
- supplements,
|
||||
|
||||
- internet-based services, and
|
||||
|
||||
- support services
|
||||
|
||||
for this software, unless other terms accompany those items. If so,
|
||||
those terms apply.
|
||||
|
||||
By using the software, you accept these terms. If you do not accept
|
||||
them, do not use the software.
|
||||
|
||||
As described below, using some features also operates as your consent to
|
||||
the transmission of certain standard computer information for
|
||||
Internet-based services.
|
||||
|
||||
\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
|
||||
|
||||
If you comply with these license terms, you have the rights below.
|
||||
|
||||
1. **INSTALLATION AND USE RIGHTS. **
|
||||
|
||||
a. You may install and use any number of copies of the software on
|
||||
your devices to design, develop and test your programs that run
|
||||
on a Microsoft operating system. Further, you may install, use
|
||||
and/or deploy via a network management system or as part of a
|
||||
desktop image, any number of copies of the software on computer
|
||||
devices within your internal corporate network to design,
|
||||
develop and test your programs that run on a Microsoft operating
|
||||
system. Each copy must be complete, including all copyright and
|
||||
trademark notices. You must require end users to agree to terms
|
||||
that protect the software as much as these license terms.
|
||||
|
||||
b. **Utilities. **The software contains certain components that are
|
||||
identified in the Utilities List located at . Depending on the
|
||||
specific edition of the software, the number of Utility files
|
||||
you receive with the software may not be equal to the number of
|
||||
Utilities listed in the Utilities List. Except as otherwise
|
||||
provided on the Utilities List for specific files, you may copy
|
||||
and install the Utilities you receive with the software on to
|
||||
other third party machines. These Utilities may only be used to
|
||||
debug and deploy your programs and databases you have developed
|
||||
with the software. You must delete all the Utilities installed
|
||||
onto a third party machine within the earlier of (i) when you
|
||||
have finished debugging or deploying your programs; or (ii)
|
||||
thirty (30) days after installation of the Utilities onto that
|
||||
machine. We may add additional files to this list from time to
|
||||
time.
|
||||
|
||||
c. **Build Services and Enterprise Build Servers.** You may
|
||||
install and use any number of copies of the software onto your
|
||||
build machines or servers, solely for the purpose of:
|
||||
|
||||
i. Compiling, building, verifying and archiving your programs;
|
||||
|
||||
ii. Creating and configuring build systems internal to your
|
||||
organization to support your internal build environment; or
|
||||
|
||||
iii. Enabling a service for third parties to design, develop and
|
||||
test programs or services that run on a Microsoft operating
|
||||
system.
|
||||
|
||||
<!-- -->
|
||||
|
||||
a. **Included Microsoft Programs.** The software contains other
|
||||
Microsoft programs. The license terms with those programs apply
|
||||
to your use of them.
|
||||
|
||||
b. **Third Party Notices.** The software may include third party
|
||||
code that Microsoft, not the third party, licenses to you under
|
||||
this agreement. Notices, if any, for the third party code are
|
||||
included for your information only. Notices, if any, for this
|
||||
third party code are included with the software and may be
|
||||
located at .
|
||||
|
||||
<!-- -->
|
||||
|
||||
1. **ADDITIONAL LICENSING REQUIREMENTS AND/OR USE RIGHTS.**
|
||||
|
||||
a. **Distributable Code. **The software contains code that you are
|
||||
permitted to distribute in programs you develop if you comply
|
||||
with the terms below.
|
||||
|
||||
i. **Right to Use and Distribute. The code and test files
|
||||
listed below are "Distributable Code".**
|
||||
|
||||
- [REDIST.TXT Files. ]{.underline}You may copy and
|
||||
distribute the object code form of code listed in
|
||||
REDIST.TXT files plus the files listed on the REDIST.TXT
|
||||
list located at . Depending on the specific edition of
|
||||
the software, the number of REDIST files you receive
|
||||
with the software may not be equal to the number of
|
||||
REDIST files listed in the REDIST.TXT List. We may add
|
||||
additional files to the list from time to time.
|
||||
|
||||
- Third Party Distribution. You may permit distributors of
|
||||
your programs to copy and distribute the Distributable
|
||||
Code as part of those programs.
|
||||
|
||||
<!-- -->
|
||||
|
||||
i. **Distribution Requirements. For any Distributable Code you
|
||||
distribute, you must**
|
||||
|
||||
- Add significant primary functionality to it in your
|
||||
programs;
|
||||
|
||||
- For any Distributable Code having a filename extension
|
||||
of .lib, distribute only the results of running such
|
||||
Distributable Code through a linker with your program;
|
||||
|
||||
- Distribute Distributable Code included in a setup
|
||||
program only as part of that setup program without
|
||||
modification;
|
||||
|
||||
- Require distributors and external end users to agree to
|
||||
terms that protect it at least as much as this
|
||||
agreement;
|
||||
|
||||
- For Distributable Code from the Windows Performance
|
||||
Toolkit portions of the software, distribute the
|
||||
unmodified software package as a whole with your
|
||||
programs, with the exception of the
|
||||
KernelTraceControl.dll and the
|
||||
WindowsPerformanceRecorderControl.dll which can be
|
||||
distributed with your programs;
|
||||
|
||||
- Display your valid copyright notice on your programs;
|
||||
and
|
||||
|
||||
- Indemnify, defend, and hold harmless Microsoft from any
|
||||
claims, including attorneys' fees, related to the
|
||||
distribution or use of your programs.
|
||||
|
||||
<!-- -->
|
||||
|
||||
i. **Distribution Restrictions. You may not**
|
||||
|
||||
- Alter any copyright, trademark or patent notice in the
|
||||
Distributable Code;
|
||||
|
||||
- Use Microsoft's trademarks in your programs' names or in
|
||||
a way that suggests your programs come from or are
|
||||
endorsed by Microsoft;
|
||||
|
||||
- Distribute partial copies of the Windows Performance
|
||||
Toolkit portion of the software package with the
|
||||
exception of the KernelTraceControl.dll and the
|
||||
WindowsPerformanceRecorderControl.dll which can be
|
||||
distributed with your programs;
|
||||
|
||||
- Distribute Distributable Code to run on a platform other
|
||||
than the Microsoft operating system platform;
|
||||
|
||||
- Include Distributable Code in malicious, deceptive or
|
||||
unlawful programs; or
|
||||
|
||||
- Modified or distribute the source code of any
|
||||
Distributable Code so that any part of it becomes
|
||||
subject to an Excluded License. And Excluded License is
|
||||
on that requir3es, as a condition of use, modification
|
||||
or distribution, that
|
||||
|
||||
- The code be disclosed or distributed in source code
|
||||
form; or
|
||||
|
||||
- Others have the right to modify it.
|
||||
|
||||
<!-- -->
|
||||
|
||||
a. **Additional Rights and Restrictions for Features made Available
|
||||
with the Software. **
|
||||
|
||||
i. **Windows App Requirements.** If you intend to make your
|
||||
program available in the Windows Store, the program must
|
||||
comply with the Certification Requirements as defined and
|
||||
described in the App Developer Agreement, currently
|
||||
available at: .
|
||||
|
||||
ii. **Bing Maps. **The software may include features that
|
||||
retrieve content such as maps, images and other data through
|
||||
the Bing Maps (or successor branded) application programming
|
||||
interface (the "Bing Maps API") to create reports displaying
|
||||
data on top of maps, aerial and hybrid imagery. If these
|
||||
features are included, you may use these features to create
|
||||
and view dynamic or static documents only in conjunction
|
||||
with and through methods and means of access integrated in
|
||||
the software. You may not otherwise copy, store, archive, or
|
||||
create a database of the entity information including
|
||||
business names, addresses and geocodes available through the
|
||||
Bing Maps API. You may not use the Bing Maps API to provide
|
||||
sensor based guidance/routing, nor use any Road Traffic Data
|
||||
or Bird's Eye Imager (or associated metadata) even if
|
||||
available through the Bing Maps API for any purpose. Your
|
||||
use of the Bing Maps API and associated content is also
|
||||
subject to the additional terms and conditions at .
|
||||
|
||||
iii. **Additional Mapping APIs. **The software may include
|
||||
application programming interfaces that provide maps and
|
||||
other related mapping features and services that are not
|
||||
provided by Bing (the "Additional Mapping APIs"). These
|
||||
Additional Mapping APIs are subject to additional terms and
|
||||
conditions and may require payment of fees to Microsoft
|
||||
and/or third party providers based on the use or volume of
|
||||
use of such Additional Mapping APIs. These terms and
|
||||
conditions will be provided when you obtain any necessary
|
||||
license keys to use such Additional Mapping APIs or when
|
||||
you review or receive documentation related to the use of
|
||||
such Additional Mapping APIs.
|
||||
|
||||
iv. **Push Notifications. **The Microsoft Push Notification
|
||||
Service may not be used to send notifications that are
|
||||
mission critical or otherwise could affect matters of life
|
||||
or death, including without limitation critical
|
||||
notifications related to a medical device or condition.
|
||||
MICROSOFT EXPRESSLY DISCLAIMS ANY WARRANTIES THAT THE USE OF
|
||||
THE MICROSOFT PUSH NOTIFICATION SERVICE OR DELIVERY OF
|
||||
MICROSOFT PUSH NOTIFICATION SERVICE NOTIFICATIONS WILL BE
|
||||
UNINTERRUPTED, ERROR FREE, OR OTHERWISE GUARANTEED TO OCCUR
|
||||
ON A REAL-TIME BASIS.
|
||||
|
||||
v. **Speech namespace API. **Using speech recognition
|
||||
functionality via the Speech namespace APIs in a program
|
||||
requires the support of a speech recognition service. The
|
||||
service may require network connectivity at the time of
|
||||
recognition (e.g., when using a predefined grammar). In
|
||||
addition, the service may also collect speech-related data
|
||||
in order to provide and improve the service. The
|
||||
speech-related data may include, for example, information
|
||||
related to grammar size and string phrases in a grammar.
|
||||
|
||||
vi. Also, in order for a user to use speech recognition on the
|
||||
phone they must first accept certain terms of use. The terms
|
||||
of use notify the user that data related to their use of the
|
||||
speech recognition service will be collected and used to
|
||||
provide and improve the service. If a user does not accept
|
||||
the terms of use and speech recognition is attempted by the
|
||||
application, the operation will not work and an error will
|
||||
be returned to the application.
|
||||
|
||||
vii. **PlayReady Support. **The software may include the Windows
|
||||
Emulator, which contains Microsoft's PlayReady content
|
||||
access technology. Content owners use Microsoft PlayReady
|
||||
content access technology to protect their intellectual
|
||||
property, including copyrighted content. This software uses
|
||||
PlayReady technology to access PlayReady-protected content
|
||||
and/or WMDRM-protected content. Microsoft may decide to
|
||||
revoke the software's ability to consume
|
||||
PlayReady-protected content for reasons including but not
|
||||
limited to (i) if a breach or potential breach of PlayReady
|
||||
technology occurs, (ii) proactive robustness enhancement,
|
||||
and (iii) if Content owners require the revocation because
|
||||
the software fails to properly enforce restrictions on
|
||||
content usage. Revocation should not affect unprotected
|
||||
content or content protected by other content access
|
||||
technologies. Content owners may require you to upgrade
|
||||
PlayReady to access their content. If you decline an
|
||||
upgrade, you will not be able to access content that
|
||||
requires the upgrade and may not be able to install other
|
||||
operating system updates or upgrades.** **
|
||||
|
||||
viii. **Package Managers. **The software may include package
|
||||
managers, like NuGet, that give you the option to download
|
||||
other Microsoft and third party software packages to use
|
||||
with your application. Those packages are under their own
|
||||
licenses, and not this agreement. Microsoft does not
|
||||
distribute, license or provide any warranties for any of
|
||||
the third party packages.
|
||||
|
||||
ix. **Font Components. **While the software is running, you may
|
||||
use its fonts to display and print content. You may only
|
||||
embed fonts in content as permitted by the embedding
|
||||
restrictions in the fonts; and temporarily download them to
|
||||
a printer or other output device to help print content.
|
||||
|
||||
x. **Notice about the H.264/AVD Visual Standard, and the VC-1
|
||||
Video Standard. **This software may include H.264/MPEG-4 AVC
|
||||
and/or VD-1 decoding technology. MPEG LA, L.L.C. requires
|
||||
this notice:
|
||||
|
||||
<!-- -->
|
||||
|
||||
a. THIS PRODUCT IS LICENSED UNDER THE AVC AND THE VC-1 PATENT
|
||||
PORTFOLIO LICENSES FOR THE PERSONAL AND NON-COMMERCIAL USE OF A
|
||||
CONSUMER TO (i) ENCODE VIDEO IN COMPLIANCE WITH THE ABOVE
|
||||
STANDARDS ("VIDEO STANDARDS") AND/OR (ii) DECODE AVC, AND VC-1
|
||||
VIDEO THAT WAS ENCODED BY A CONSUMER ENGAGED IN A PERSONAL AND
|
||||
NON-COMMERCIAL ACTIVITY AND/OR WAS OBTAINED FROM A VIDEO
|
||||
PROVIDER LICENSED TO PROVIDE SUCH VIDEO. NONE OF THE LICENSES
|
||||
EXTEND TO ANY OTHER PRODUCT REGARDLESS OF WHETHER SUCH PRODUCT
|
||||
IS INCLUDED WITH THIS SOFTWARE IN A SINGLE ARTICLE. NO LICENSE
|
||||
IS GRANTED OR SHALL BE IMPLIED FOR ANY OTHER USE. ADDITIONAL
|
||||
INFORMATION MAY BE OBTAINED FROM MPEG LA, L.L.C. SEE .
|
||||
|
||||
b. For clarification purposes, this notice does not limit or
|
||||
inhibit the use of the software for normal business uses that
|
||||
are personal to that business which do not include (i)
|
||||
redistribution of the software to third parties, or (ii)
|
||||
creation of content with the VIDEO STANDARDS compliant
|
||||
technologies for distribution to third parties.
|
||||
|
||||
<!-- -->
|
||||
|
||||
1. **INTERNET-BASED SERVICES. Microsoft provides Internet-based
|
||||
services with the software. It may change or cancel them at any
|
||||
time. **
|
||||
|
||||
a. **Consent for Internet-Based Services.** The software features
|
||||
described below and in the privacy statement at connect to
|
||||
Microsoft or service provider computer systems over the
|
||||
Internet. In some cases, you will not receive a separate notice
|
||||
when they connect. In some cases, you may switch off these
|
||||
features or not use them as described in the applicable product
|
||||
documentation. By using these features, you consent to the
|
||||
transmission of this information. Microsoft does not use the
|
||||
information to identify or contact you.
|
||||
|
||||
i. **Computer Information.** The following features use
|
||||
Internet protocols, which send to the appropriate systems
|
||||
computer information, such as your Internet protocol
|
||||
address, the type of operating system, browser, and name and
|
||||
version of the software you are using, and the language code
|
||||
of the device where you installed the software. Microsoft
|
||||
uses this information to make the Internet-based services
|
||||
available to you.
|
||||
|
||||
- [Software Use and Performance]{.underline}. This
|
||||
software collects info about your hardware and how you
|
||||
use the software and automatically sends error reports
|
||||
to Microsoft. These reports include information about
|
||||
problems that occur in the software. Reports might
|
||||
unintentionally contain personal information. For
|
||||
example, a report that contains a snapshot of computer
|
||||
memory might include your name. Part of a document you
|
||||
were working on could be included as well, but this
|
||||
information in reports or any info collected about
|
||||
hardware or your software use will not be used to
|
||||
identify or contact you.
|
||||
|
||||
- [Digital Certificates]{.underline}. The software uses
|
||||
digital certificates. These digital certificates confirm
|
||||
the identity of Internet users sending X.509 standard
|
||||
encryption information. They also can be used to
|
||||
digitally sign files and macros to verify the integrity
|
||||
and origin of the file contents. The software retrieves
|
||||
certificates and updates certificate revocation lists
|
||||
using the Internet, when available.
|
||||
|
||||
- [Windows Application Certification Kit]{.underline}. To
|
||||
ensure you have the latest certification tests, when
|
||||
launched this software periodically checks a Windows
|
||||
Application Certification Kit file on
|
||||
download.microsft.com to see if an update is available.
|
||||
If an update is found, you are prompted and provided a
|
||||
link to a web site where you can download the update.
|
||||
You may use the Windows Application Certification Kit
|
||||
solely to test your programs before you submit them for
|
||||
a potential Microsoft Windows Certification and for
|
||||
inclusion on the Microsoft Windows Store. The results
|
||||
you receive are for informational purposes only.
|
||||
Microsoft has no obligation to either (i) provide you
|
||||
with a Windows Certification for your programs
|
||||
and/or ii) include your program in the Microsoft Windows
|
||||
Store.
|
||||
|
||||
- [Microsoft Digital Rights Management for Silverlight.
|
||||
]{.underline}
|
||||
|
||||
- If you use Silverlight to access content that has been
|
||||
protected with Microsoft Digital Rights Management
|
||||
(DRM), in order to let you play the content, the
|
||||
software may automatically
|
||||
|
||||
<!-- -->
|
||||
|
||||
- request media usage rights from a rights server on the
|
||||
Internet and
|
||||
|
||||
- download and install available DRM Updates.
|
||||
|
||||
<!-- -->
|
||||
|
||||
- For more information about this feature, including
|
||||
instructions for turning the Automatic Updates off, go
|
||||
to .
|
||||
|
||||
1. [Web Content Features. ]{.underline} Features in the
|
||||
software can retrieve related content from Microsoft and
|
||||
provide it to you. To provide the content, these
|
||||
features send to Microsoft the type of operating system,
|
||||
name and version of the software you are using, type of
|
||||
browser and language code of the device where you
|
||||
installed the software. Examples of these features are
|
||||
clip art, templates, online training, online assistance,
|
||||
help and Appshelp. You may choose not to use these web
|
||||
content features.
|
||||
|
||||
<!-- -->
|
||||
|
||||
i. **Use of Information.** We may use nformation collected
|
||||
about software use and performance to provide and improve
|
||||
Microsoft software and services as further described in
|
||||
Microsoft's Privacy Statement available at:
|
||||
https://go.microsoft.com/fwlink/?LinkID=521839. We may also
|
||||
share it with others, such as hardware and software vendors.
|
||||
They may use the information to improve how their products
|
||||
run with Microsoft software.
|
||||
|
||||
ii. **Misuse of Internet-based Services.** You may not use these
|
||||
services in any way that could harm them or impair anyone
|
||||
else's use of them. You may not use the services to try to
|
||||
gain unauthorized access to any service, data, account or
|
||||
network by any means.
|
||||
|
||||
<!-- -->
|
||||
|
||||
1. **YOUR COMPLIANCE WITH PRIVACY AND DATA PROTECTION LAWS.**
|
||||
|
||||
a. **Personal Information Definition. **\"Personal Information\"
|
||||
means any information relating to an identified or identifiable
|
||||
natural person; an identifiable natural person is one who can be
|
||||
identified, directly or indirectly, in particular by reference
|
||||
to an identifier such as a name, an identification number,
|
||||
location data, an online identifier or to one or more factors
|
||||
specific to the physical, physiological, genetic, mental,
|
||||
economic, cultural or social identity of that natural person.
|
||||
|
||||
b. **Collecting Personal Information using Packaged and Add-on
|
||||
APIs. **If you use any API to collect personal information from
|
||||
the software, you must comply with all laws and regulations
|
||||
applicable to your use of the data accessed through APIs
|
||||
including without limitation laws related to privacy, biometric
|
||||
data, data protection, and confidentiality of communications.
|
||||
Your use of the software is conditioned upon implementing and
|
||||
maintaining appropriate protections and measures for your
|
||||
applications and services, and that includes your responsibility
|
||||
to the data obtained through the use of APIs. For the data you
|
||||
obtained through any APIs, you must:
|
||||
|
||||
i. obtain all necessary consents before collecting and using
|
||||
data and only use the data for the limited purposes to which
|
||||
the user consented, including any consent to changes in use;
|
||||
|
||||
ii. In the event you're storing data, ensure that data is kept
|
||||
up to date and implement corrections, restrictions to data,
|
||||
or the deletion of data as updated through packaged or
|
||||
add-on APIs or upon user request if required by applicable
|
||||
law;
|
||||
|
||||
iii. implement proper retention and deletion policies, including
|
||||
deleting all data when as directed by your users or as
|
||||
required by applicable law; and
|
||||
|
||||
iv. maintain and comply with a written statement available to
|
||||
your customers that describes your privacy practices
|
||||
regarding data and information you collect, use and that you
|
||||
share with any third parties.
|
||||
|
||||
<!-- -->
|
||||
|
||||
a. **Location Framework. **The software may contain a location
|
||||
framework component or APIs that enable support of location
|
||||
services in programs. Programs that receive device location must
|
||||
comply with the requirements related to the Location Service
|
||||
APIs as described in the Microsoft Store Policies (). If you
|
||||
choose to collect device location data outside of the control of
|
||||
Windows system settings, you must obtain legally sufficient
|
||||
consent for your data practices, and such practices must comply
|
||||
with all other applicable laws and regulations.
|
||||
|
||||
b. **Security. **If your application or service collects, stores or
|
||||
transmits personal information, it must do so securely, by using
|
||||
modern cryptography methods.
|
||||
|
||||
<!-- -->
|
||||
|
||||
1. **BACKUP COPY. **You may make one backup copy of the software. You
|
||||
may use it only to reinstall the software.
|
||||
|
||||
2. **DOCUMENTATION. **Any person that has valid access to your computer
|
||||
or internal network may copy and use the documentation for your
|
||||
internal, reference purposes.
|
||||
|
||||
3. **SCOPE OF LICENSE. **The software is licensed, not sold. This
|
||||
agreement only gives you some rights to use the software. Microsoft
|
||||
reserves all other rights. Unless applicable law gives you more
|
||||
rights despite this limitation, you may use the software only as
|
||||
expressly permitted in this agreement. In doing so, you must comply
|
||||
with any technical limitations in the software that only allow you
|
||||
to use it in certain ways. You may not
|
||||
|
||||
- Except for the Microsoft .NET Framework, you must obtain
|
||||
Microsoft\'s prior written approval to disclose to a third party the
|
||||
results of any benchmark test of the software.
|
||||
|
||||
- work around any technical limitations in the software;
|
||||
|
||||
- reverse engineer, decompile or disassemble the software, except and
|
||||
only to the extent that applicable law expressly permits, despite
|
||||
this limitation;
|
||||
|
||||
- make more copies of the software than specified in this agreement or
|
||||
allowed by applicable law, despite this limitation;
|
||||
|
||||
- publish the software for others to copy;
|
||||
|
||||
- rent, lease or lend the software;
|
||||
|
||||
- transfer the software or this agreement to any third party; or
|
||||
|
||||
- use the software for commercial software hosting services.
|
||||
|
||||
1. **EXPORT RESTRICTIONS. **The software is subject to United States
|
||||
export laws and regulations. You must comply with all domestic and
|
||||
international export laws and regulations that apply to the
|
||||
software. These laws include restrictions on destinations, end users
|
||||
and end use. For additional information, see
|
||||
www.microsoft.com/exporting.
|
||||
|
||||
2. **SUPPORT SERVICES. **Because this software is "as is," we may not
|
||||
provide support services for it.
|
||||
|
||||
3. **ENTIRE AGREEMENT. **This agreement, and the terms for supplements,
|
||||
updates, Internet-based services and support services that you use,
|
||||
are the entire agreement for the software and support services.
|
||||
|
||||
4. **INDEPENDENT PARTIES. **Microsoft and you are independent
|
||||
contractors. Nothing in this agreement shall be construed as
|
||||
creating an employer-employee relationship, processor-subprocessor
|
||||
relationship, a partnership, or a joint venture between the parties.
|
||||
|
||||
5. **APPLICABLE LAW AND PLACE TO RESOLVE DISPUTES**. If you acquired
|
||||
the software in the United States or Canada, the laws of the state
|
||||
or province where you live (or, if a business, where your principal
|
||||
place of business is located) govern the interpretation of this
|
||||
agreement, claims for its breach, and all other claims (including
|
||||
consumer protection, unfair competition, and tort claims),
|
||||
regardless of conflict of laws principles. If you acquired the
|
||||
software in any other country, its laws apply. If U.S. federal
|
||||
jurisdiction exists, you and Microsoft consent to exclusive
|
||||
jurisdiction and venue in the federal court in King County,
|
||||
Washington for all disputes heard in court. If not, you and
|
||||
Microsoft consent to exclusive jurisdiction and venue in the
|
||||
Superior Court of King County, Washington for all disputes heard in
|
||||
court.
|
||||
|
||||
6. **LEGAL EFFECT. **This agreement describes certain legal rights. You
|
||||
may have other rights under the laws of your country. You may also
|
||||
have rights with respect to the party from whom you acquired the
|
||||
software. This agreement does not change your rights under the laws
|
||||
of your country if the laws of your country do not permit it to do
|
||||
so.
|
||||
|
||||
7. **DISCLAIMER OF WARRANTY. The software is licensed "as-is." You bear
|
||||
the risk of using it. Microsoft gives no express warranties,
|
||||
guarantees or conditions. You may have additional consumer rights or
|
||||
statutory guarantees under your local laws which this agreement
|
||||
cannot change. To the extent permitted under your local laws,
|
||||
Microsoft excludes the implied warranties of merchantability,
|
||||
fitness for a particular purpose and non-infringement.**
|
||||
|
||||
FOR AUSTRALIA -- You have statutory guarantees under the Australian
|
||||
Consumer Law and nothing in these terms is intended to affect those
|
||||
rights.
|
||||
|
||||
1. **LIMITATION ON AND EXCLUSION OF REMEDIES AND DAMAGES. You can
|
||||
recover from Microsoft and its suppliers only direct damages up to
|
||||
U.S. \$5.00. You cannot recover any other damages, including
|
||||
consequential, lost profits, special, indirect or incidental
|
||||
damages.**
|
||||
|
||||
This limitation applies to
|
||||
|
||||
- anything related to the software, services, content (including code)
|
||||
on third party Internet sites, or third party programs; and
|
||||
|
||||
- claims for breach of contract, breach of warranty, guarantee or
|
||||
condition, strict liability, negligence, or other tort to the extent
|
||||
permitted by applicable law.
|
||||
|
||||
It also applies even if Microsoft knew or should have known about the
|
||||
possibility of the damages. The above limitation or exclusion may not
|
||||
apply to you because your country may not allow the exclusion or
|
||||
limitation of incidental, consequential or other damages.
|
||||
|
||||
Please note: As this software is distributed in Quebec, Canada, some of
|
||||
the clauses in this agreement are provided below in French.
|
||||
|
||||
Remarque : Ce logiciel étant distribué au Québec, Canada, certaines des
|
||||
clauses dans ce contrat sont fournies ci-dessous en français.
|
||||
|
||||
EXONÉRATION DE GARANTIE. Le logiciel visé par une licence est offert «
|
||||
tel quel ». Toute utilisation de ce logiciel est à votre seule risque et
|
||||
péril. Microsoft n'accorde aucune autre garantie expresse. Vous pouvez
|
||||
bénéficier de droits additionnels en vertu du droit local sur la
|
||||
protection des consommateurs, que ce contrat ne peut modifier. La ou
|
||||
elles sont permises par le droit locale, les garanties implicites de
|
||||
qualité marchande, d'adéquation à un usage particulier et d'absence de
|
||||
contrefaçon sont exclues.
|
||||
|
||||
LIMITATION DES DOMMAGES-INTÉRÊTS ET EXCLUSION DE RESPONSABILITÉ POUR LES
|
||||
DOMMAGES. Vous pouvez obtenir de Microsoft et de ses fournisseurs une
|
||||
indemnisation en cas de dommages directs uniquement à hauteur de 5,00 \$
|
||||
US. Vous ne pouvez prétendre à aucune indemnisation pour les autres
|
||||
dommages, y compris les dommages spéciaux, indirects ou accessoires et
|
||||
pertes de bénéfices.
|
||||
|
||||
Crete limitation concern:
|
||||
|
||||
- tout ce qui est relié au logiciel, aux services ou au contenu (y
|
||||
compris le code) figurant sur des sites Internet tiers ou dans des
|
||||
programmes tiers ; et
|
||||
|
||||
- les réclamations au titre de violation de contrat ou de garantie, ou
|
||||
au titre de responsabilité stricte, de négligence ou d'une autre
|
||||
faute dans la limite autorisée par la loi en vigueur.
|
||||
|
||||
Elle s'applique également, même si Microsoft connaissait ou devrait
|
||||
connaître l'éventualité d'un tel dommage. Si votre pays n'autorise pas
|
||||
l'exclusion ou la limitation de responsabilité pour les dommages
|
||||
indirects, accessoires ou de quelque nature que ce soit, il se peut que
|
||||
la limitation ou l'exclusion ci-dessus ne s'appliquera pas à votre
|
||||
égard.
|
||||
|
||||
EFFET JURIDIQUE. Le présent contrat décrit certains droits juridiques.
|
||||
Vous pourriez avoir d'autres droits prévus par les lois de votre pays.
|
||||
Le présent contrat ne modifie pas les droits que vous confèrent les lois
|
||||
de votre pays si celles-ci ne le permettent pas.
|
||||
|
||||
\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*
|
||||
|
||||
EULAID:WIN10SDK.RTM.AUG_2018_en-US
|
||||
|
||||
\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*
|
||||
File diff suppressed because it is too large.
Load diff
@@ -1,53 +0,0 @@
|
||||
MICROSOFT SOFTWARE LICENSE TERMS
|
||||
|
||||
1. MICROSOFT WINDOWS APP SDK
|
||||
2. WINDOWS MACHINE LEARNING (ML)
|
||||
________________________________________
|
||||
IF YOU LIVE IN (OR ARE A BUSINESS WITH A PRINCIPAL PLACE OF BUSINESS IN) THE UNITED STATES, PLEASE READ THE “BINDING ARBITRATION AND CLASS ACTION WAIVER” SECTION BELOW. IT AFFECTS HOW DISPUTES ARE RESOLVED.
|
||||
________________________________________
|
||||
These license terms are an agreement between you and Microsoft Corporation (or one of its affiliates). They apply to the software named above and any Microsoft services or software updates (except to the extent such services or updates are accompanied by new or additional terms, in which case those different terms apply prospectively and do not alter your or Microsoft’s rights relating to pre-updated software or services). IF YOU COMPLY WITH THESE LICENSE TERMS, YOU HAVE THE RIGHTS BELOW. BY USING THE SOFTWARE, YOU ACCEPT THESE TERMS.
|
||||
1. INSTALLATION AND USE RIGHTS.
|
||||
a) General. Subject to the terms of this agreement, you may install and use any number of copies of the software to develop and test your applications, solely for use on Windows. When building Generative AI applications follow the guidelines in https://learn.microsoft.com/windows/ai/rai.
|
||||
b) Included Microsoft Applications. The software may include other Microsoft applications. These license terms apply to those included applications, if any, unless other license terms are provided with the other Microsoft applications.
|
||||
c) Microsoft Platforms. The software may include components from Microsoft Windows. These components are governed by separate agreements and their own product support policies, as described in the license terms found in the installation directory for that component or in the “Licenses” folder accompanying the software.
|
||||
d) Third Party Materials. The software may use or include source code, object code, or data available under an open source or open data license (“Open Source Materials”) or a proprietary license from a third party (with Open Source Materials, collectively, “Third Party Materials”) that are licensed under the specific license terms applicable to the Third Party Materials (an “Third Party License Agreement”). To the extent that any Third Party License Agreement requires that the corresponding Third Party Materials be licensed under terms that are different from the terms set forth in this Agreement, then such Third Party Materials are licensed under the terms of that Third Party License Agreement and the other terms and conditions in this Agreement will not apply with respect to those Third Party Materials. You (a) acknowledge that any such Third Party License Agreement is solely between Licensee and the applicable licensor of the Third Party Materials, and (b) will comply with the terms of any such Third Party License Agreement. Without limitation to the foregoing, the licenses referenced on this website (https://learn.microsoft.com/en-us/windows/ai/new-windows-ml/supported-execution-providers) are deemed to be “Third Party Materials.”
|
||||
2. DATA.
|
||||
a) Data Collection. The software may collect information about you and your use of the software, and send that to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may opt-out of many of these scenarios, but not all, as described in the product documentation. There are also some features in the software that may enable you to collect data from users of your applications. If you use these features to enable data collection in your applications, you must comply with applicable law, including providing appropriate notices to users of your applications. You can learn more about data collection and use in the help documentation and the privacy statement at https://aka.ms/privacy. Your use of the software operates as your consent to these practices.
|
||||
b) Processing of Personal Data. To the extent Microsoft is a processor or subprocessor of personal data in connection with the software, Microsoft makes the commitments in the European Union General Data Protection Regulation Terms of the Online Services Terms to all customers effective May 25, 2018, at https://docs.microsoft.com/en-us/legal/gdpr.
|
||||
3. DISTRIBUTABLE CODE. The software may contain code you are permitted to distribute (i.e. make available for third parties) in applications you develop, as described in this Section.
|
||||
a) Distribution Rights. The code and test files described below are distributable if included with the software.
|
||||
i. Any files that are binplaced with your application by the WindowsAppSDK NuGet package are, by definition, permitted to be redistributed. This applies to both framework package dependent and self-contained deployments.
|
||||
ii. Image Library. You may copy and distribute images, graphics, and animations in the Image Library as described in the software documentation; and
|
||||
iii. Third Party Distribution. You may permit distributors of your applications to copy and distribute any of this distributable code you elect to distribute with your applications.
|
||||
b) Distribution Requirements. For any code you distribute, you must:
|
||||
i. add significant primary functionality to it in your applications;
|
||||
ii. require distributors and external end users to agree to terms that protect it and Microsoft at least as much as this agreement; and
|
||||
iii. indemnify, defend, and hold harmless Microsoft from any claims, including attorneys’ fees, related to the distribution or use of your applications, except to the extent that any claim is based solely on the unmodified distributable code.
|
||||
c) Distribution Restrictions. You may not:
|
||||
i. use Microsoft’s trademarks or trade dress in your application in any way that suggests your application comes from or is endorsed by Microsoft; or
|
||||
ii. modify or distribute the source code of any distributable code so that any part of it becomes subject to any license that requires that the distributable code, any other part of the software, or any of Microsoft’s other intellectual property be disclosed or distributed in source code form, or that others have the right to modify it.
|
||||
4. SCOPE OF LICENSE. The software is licensed, not sold. Microsoft reserves all other rights. Unless applicable law gives you more rights despite this limitation, you will not (and have no right to):
|
||||
a) work around any technical limitations in the software that only allow you to use it in certain ways;
|
||||
b) reverse engineer, decompile or disassemble the software, or otherwise attempt to derive the source code for the software, except and to the extent required by third party licensing terms governing use of certain open source components that may be included in the software;
|
||||
c) remove, minimize, block, or modify any notices of Microsoft or its suppliers in the software;
|
||||
d) use the software in any way that is against the law or to create or propagate malware; or
|
||||
e) share, publish, distribute, or lease the software (except for any distributable code, subject to the terms above), provide the software as a stand-alone offering for others to use, or transfer the software or this agreement to any third party.
|
||||
5. EXPORT RESTRICTIONS. You must comply with all domestic and international export laws and regulations that apply to the software, which include restrictions on destinations, end users, and end use. For further information on export restrictions, visit https://aka.ms/exporting.
|
||||
6. SUPPORT SERVICES. Microsoft is not obligated under this agreement to provide any support services for the software. Any support provided is “as is”, “with all faults”, and without warranty of any kind.
|
||||
7. UPDATES. The software may periodically check for updates, and download and install them for you. You may obtain updates only from Microsoft or authorized sources. Microsoft may need to update your system to provide you with updates. You agree to receive these automatic updates without any additional notice. Updates may not include or support all existing software features, services, or peripheral devices.
|
||||
8. BINDING ARBITRATION AND CLASS ACTION WAIVER. This Section applies if you live in (or, if a business, your principal place of business is in) the United States. If you and Microsoft have a dispute, you and Microsoft agree to try for 60 days to resolve it informally. If you and Microsoft can’t, you and Microsoft agree to binding individual arbitration before the American Arbitration Association under the Federal Arbitration Act (“FAA”), and not to sue in court in front of a judge or jury. Instead, a neutral arbitrator will decide. Class action lawsuits, class-wide arbitrations, private attorney-general actions, and any other proceeding where someone acts in a representative capacity are not allowed; nor is combining individual proceedings without the consent of all parties. The complete Arbitration Agreement contains more terms and is at https://aka.ms/arb-agreement-4. You and Microsoft agree to these terms.
|
||||
9. ENTIRE AGREEMENT. This agreement, and any other terms Microsoft may provide for supplements, updates, or third-party applications, is the entire agreement for the software.
|
||||
10. APPLICABLE LAW AND PLACE TO RESOLVE DISPUTES. If you acquired the software in the United States or Canada, the laws of the state or province where you live (or, if a business, where your principal place of business is located) govern the interpretation of this agreement, claims for its breach, and all other claims (including consumer protection, unfair competition, and tort claims), regardless of conflict of laws principles, except that the FAA governs everything related to arbitration. If you acquired the software in any other country, its laws apply, except that the FAA governs everything related to arbitration. If U.S. federal jurisdiction exists, you and Microsoft consent to exclusive jurisdiction and venue in the federal court in King County, Washington for all disputes heard in court (excluding arbitration). If not, you and Microsoft consent to exclusive jurisdiction and venue in the Superior Court of King County, Washington for all disputes heard in court (excluding arbitration).
|
||||
11. CONSUMER RIGHTS; REGIONAL VARIATIONS. This agreement describes certain legal rights. You may have other rights, including consumer rights, under the laws of your state or country. Separate and apart from your relationship with Microsoft, you may also have rights with respect to the party from which you acquired the software. This agreement does not change those other rights if the laws of your state or country do not permit it to do so. For example, if you acquired the software in one of the below regions, or mandatory country law applies, then the following provisions apply to you:
|
||||
a) Australia. You have statutory guarantees under the Australian Consumer Law and nothing in this agreement is intended to affect those rights.
|
||||
b) Canada. If you acquired this software in Canada, you may stop receiving updates by turning off the automatic update feature, disconnecting your device from the Internet (if and when you re-connect to the Internet, however, the software will resume checking for and installing updates), or uninstalling the software. The product documentation, if any, may also specify how to turn off updates for your specific device or software.
|
||||
c) Germany and Austria.
|
||||
i. Warranty. The properly licensed software will perform substantially as described in any Microsoft materials that accompany the software. However, Microsoft gives no contractual guarantee in relation to the licensed software.
|
||||
ii. Limitation of Liability. In case of intentional conduct, gross negligence, claims based on the Product Liability Act, as well as, in case of death or personal or physical injury, Microsoft is liable according to the statutory law.
|
||||
Subject to the foregoing clause ii., Microsoft will only be liable for slight negligence if Microsoft is in breach of such material contractual obligations, the fulfillment of which facilitate the due performance of this agreement, the breach of which would endanger the purpose of this agreement and the compliance with which a party may constantly trust in (so-called "cardinal obligations"). In other cases of slight negligence, Microsoft will not be liable for slight negligence.
|
||||
12. DISCLAIMER OF WARRANTY. THE SOFTWARE IS LICENSED “AS IS.” YOU BEAR THE RISK OF USING IT. MICROSOFT GIVES NO EXPRESS WARRANTIES, GUARANTEES, OR CONDITIONS. TO THE EXTENT PERMITTED UNDER APPLICABLE LAWS, MICROSOFT EXCLUDES ALL IMPLIED WARRANTIES, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
|
||||
13. LIMITATION ON AND EXCLUSION OF DAMAGES. IF YOU HAVE ANY BASIS FOR RECOVERING DAMAGES DESPITE THE PRECEDING DISCLAIMER OF WARRANTY, YOU CAN RECOVER FROM MICROSOFT AND ITS SUPPLIERS ONLY DIRECT DAMAGES UP TO U.S. $5.00. YOU CANNOT RECOVER ANY OTHER DAMAGES, INCLUDING CONSEQUENTIAL, LOST PROFITS, SPECIAL, INDIRECT, OR INCIDENTAL DAMAGES.
|
||||
|
||||
This limitation applies to (a) anything related to the software, services, content (including code) on third party Internet sites, or third party applications; and (b) claims for breach of contract, warranty, guarantee, or condition; strict liability, negligence, or other tort; or any other claim; in each case to the extent permitted by applicable law.
|
||||
|
||||
It also applies even if Microsoft knew or should have known about the possibility of the damages. The above limitation or exclusion may not apply to you because your state, province, or country may not allow the exclusion or limitation of incidental, consequential, or other damages.
|
||||
@@ -1,51 +0,0 @@
|
||||
NOTICES AND INFORMATION
|
||||
Do Not Translate or Localize
|
||||
|
||||
This software incorporates material from third parties.
|
||||
Microsoft makes certain open source code available at https://3rdpartysource.microsoft.com,
|
||||
or you may send a check or money order for US $5.00, including the product name,
|
||||
the open source component name, platform, and version number, to:
|
||||
|
||||
Source Code Compliance Team
|
||||
Microsoft Corporation
|
||||
One Microsoft Way
|
||||
Redmond, WA 98052
|
||||
USA
|
||||
|
||||
Notwithstanding any other terms, you may reverse engineer this software to the extent
|
||||
required to debug changes to any libraries licensed under the GNU Lesser General Public License.
|
||||
|
||||
---------------------------------------------------------
|
||||
|
||||
Newtonsoft.Json 13.0.1 - MIT
|
||||
|
||||
|
||||
Copyright James Newton-King 2008
|
||||
Copyright (c) 2007 James Newton-King
|
||||
Copyright (c) James Newton-King 2008
|
||||
Copyright James Newton-King 2008 Json.NET
|
||||
|
||||
The MIT License (MIT)
|
||||
|
||||
Copyright (c) 2007 James Newton-King
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy of
|
||||
this software and associated documentation files (the "Software"), to deal in
|
||||
the Software without restriction, including without limitation the rights to
|
||||
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
|
||||
the Software, and to permit persons to whom the Software is furnished to do so,
|
||||
subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
|
||||
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
||||
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
|
||||
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
||||
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
|
||||
---------------------------------------------------------
|
||||
|
||||
@@ -1,19 +0,0 @@
|
||||
NOTICES AND INFORMATION
|
||||
Do Not Translate or Localize
|
||||
|
||||
This software incorporates material from third parties. Microsoft makes certain
|
||||
open source code available at https://3rdpartysource.microsoft.com, or you may
|
||||
send a check or money order for US $5.00, including the product name, the open
|
||||
source component name, and version number, to:
|
||||
|
||||
Source Code Compliance Team
|
||||
Microsoft Corporation
|
||||
One Microsoft Way
|
||||
Redmond, WA 98052
|
||||
USA
|
||||
|
||||
Notwithstanding any other terms, you may reverse engineer this software to the
|
||||
extent required to debug changes to any libraries licensed under the GNU Lesser
|
||||
General Public License.
|
||||
|
||||
-----
|
||||
File diff suppressed because it is too large.
Load diff
Loaded 100 of 371 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user