zuke.tools.signpath

class SignPathConnectionSettings(Settings)

• organization_id(id: str) -> Self

  The SignPath organization id — the GUID in the web app's URLs and under *Organization settings*. Defaults to the SIGNPATH_ORGANIZATION_ID environment variable.

• api_token(token: str) -> Self

  The API token of a SignPath user with submitter permission on the project's signing policy, sent as Authorization: Bearer <token>. Defaults to the SIGNPATH_API_TOKEN environment variable. The token never reaches a progress line or an error message: every message this package builds is scrubbed of it. Declare it in the build as a parameter(...).secret() so Zuke masks it in its own output too.

• api_url(url: str) -> Self

  The REST API's base URL, https://app.signpath.io/Api by default; the version and organization (/v1/<org>/…) are appended. It carries the token, so it must be https: unless it is loopback or ZUKE_ALLOW_INSECURE_URL is set. The web app's links in errors and progress lines use the same origin (<origin>/Web/<org>/…).

• request_timeout(duration: str | float) -> Self

  Abort one API call after this long ("30s", or ms); default one minute.

• download_timeout(duration: str | float) -> Self

  Abort a signed-artifact download that has not finished after this long ("10m", or ms); default five minutes.

• max_download_bytes(bytes: float) -> Self

  Refuse a signed artifact larger than this many bytes; default 2 GiB.

• retries(count: float) -> Self

  Retry a transient failure this many times (default 3), with a doubling delay from one second. A status poll or a download is retried after a network error, a timeout, or HTTP 429, 502, 503 or 504; a submission only after 429 or 503, the answers that say the request was not processed, so a retry cannot create a second signing request.

class SignPathDownloadSettings(SignPathStatusSettings)

• output(path: str) -> Self

  The file to write the signed artifact to; its directory is created when missing, and an existing file is replaced. Required.

class SignPathGitHubOriginSettings(Settings)

• artifact_id(id: str | float) -> Self

  The id of the artifact actions/upload-artifact (v4 or later) uploaded — its artifact-id step output. Required.

• run_id(id: str | float) -> Self

  The workflow run the artifact belongs to; defaults to GITHUB_RUN_ID.

• repository(name: str) -> Self

  The repository, owner/name; defaults to GITHUB_REPOSITORY.

• token(value: str) -> Self

  The GitHub token the connector reads the run and downloads the artifact with — the workflow's GITHUB_TOKEN (with actions: read and contents: read) is enough. Defaults to the GITHUB_TOKEN environment variable. It is masked out of every message, like the API token. The workflow's own token stops working when the workflow ends, so the task must wait for SignPath to fetch the artifact; submit always waits.

• connector_url(url: str) -> Self

  The SignPath GitHub connector to submit through; SignPath's hosted GitHub.com one by default. Only a self-hosted GitHub Enterprise Server needs another. It carries the API token, so it must be https:.

class SignPathStatusSettings(SignPathConnectionSettings)

• signing_request_id(id: str) -> Self

  The signing request to read — the GUID submit returned. Required.

class SignPathSubmitSettings(SignPathConnectionSettings)

• project_slug(slug: str) -> Self

  The SignPath project's slug. Required.

• signing_policy_slug(slug: str) -> Self

  The signing policy's slug, such as release-signing — it decides the certificate and whether an approver must sign off. Required.

• artifact_configuration_slug(slug: str) -> Self

  The artifact configuration's slug — which files inside the artifact are signed, and how. The project's default configuration when unset.

• description(text: str) -> Self

  A description shown on the request, such as the version being released.

• parameter(name: str, value: str) -> Self

  A user-defined parameter the artifact configuration reads (a version number to stamp, say). Names are letters, digits, ., - and _. Repeatable.

• artifact(path: str) -> Self

  Upload this local file as the artifact (SubmitWithArtifact). Exactly one of artifact and gitHubOrigin is required. SignPath's open-source programme accepts only builds whose origin it can verify, so for it use gitHubOrigin instead.

• git_hub_origin(configure: Callable[[SignPathGitHubOriginSettings], SignPathGitHubOriginSettings]) -> Self

  Have SignPath fetch the artifact from a GitHub Actions workflow run and verify its origin. Exactly one of artifact and gitHubOrigin is required.

• output(path: str) -> Self

  Download the signed artifact to this file once the request completes; its directory is created when missing. Without it, submit only waits.

• timeout(duration: str | float) -> Self

  Fail with a SignPathTimeoutError when the request is not final after this long ("30m", or ms); default ten minutes. A policy that needs a manual approval wants longer.

• poll_interval(duration: str | float) -> Self

  Poll the request's status this often ("5s", or ms; at least one second); default ten seconds.

class SignPathTasks

• static async submit(ctx: ServiceContext, configure: Callable[[SignPathSubmitSettings], SignPathSubmitSettings]) -> object

  Submit a signing request, wait for it to complete, and — with .output(path) — download the signed artifact. `ts const { signingRequestId } = await SignPathTasks.submit((s) => s.organizationId(orgId).apiToken(token) .projectSlug("zuke").signingPolicySlug("release-signing") .gitHubOrigin((g) => g.artifactId(artifactId)) .timeout("30m").output("dist/signed/zuke.zip") ); `

• static async status(ctx: ServiceContext, configure: Callable[[SignPathStatusSettings], SignPathStatusSettings]) -> object

  Read a signing request's status once — no waiting. `ts const { status } = await SignPathTasks.status((s) => s.signingRequestId(id) ); `

• static async download(ctx: ServiceContext, configure: Callable[[SignPathDownloadSettings], SignPathDownloadSettings]) -> object

  Download a completed signing request's signed artifact. `ts await SignPathTasks.download((s) => s.signingRequestId(id).output("dist/signed/zuke.exe") ); `

class SigntoolTasks

• static async verify(ctx: ServiceContext, configure: Callable[[SigntoolVerifySettings], SigntoolVerifySettings]) -> ExecResult

  Check a file's Authenticode signature with signtool verify; a file that is unsigned or fails the policy exits non-zero, which throws unless .noThrow() is set.

class SigntoolVerifySettings(ToolSettings)

• authenticode_policy() -> Self

  Verify against the default Authenticode policy (/pa) — what a signed .exe or .msi needs. Without it signtool applies the Windows driver policy and rejects ordinary code-signing certificates.

• kernel_policy() -> Self

  Verify against the kernel-mode driver signing policy (/kp).

• policy(guid: str) -> Self

  Verify against the policy with this GUID (/pg).

• all_signatures() -> Self

  Verify every signature of a file that carries several (/all).

• signature_index(index: float) -> Self

  Verify only the signature at this index, from 0 (/ds).

• hash(algorithm: Literal['SHA1', 'SHA256']) -> Self

  Look the file up in a catalog only for this digest algorithm (/hash).

• catalog(path: str) -> Self

  Verify against this catalog file (/c).

• root_subject_name(name: str) -> Self

  Require the signing certificate to chain to a root whose subject name contains this text (/r).

• timestamp_warning() -> Self

  Warn when the signature is not timestamped (/tw).

• description() -> Self

  Print the signature's description and URL (/d).

• verbose() -> Self

  Print the signer, the chain and the timestamp (/v).

• debug() -> Self

  Print debugging information (/debug).

• file(*paths: str) -> Self

  The files to verify (positional), at least one. A relative path that starts with - is passed as ./-… so it cannot be read as an option; one that starts with / is refused, since signtool would read it as an option and on Windows it means the current drive's root — give a drive-qualified or a relative path instead.